개발 과정에서 우리는 Manifest V3 런타임, 모델 로딩, 그리고 메시지 전달에 관한 몇 가지 실용적인 통찰을 발견했으며, 이를 공유하고 싶습니다.

이 가이드는 Manifest V3 제약 조건 하에 Transformers.js 를 사용하여 Chrome 확장 프로그램의 로컬 AI 기능을 실행하려는 개발자를 위한 것입니다.

가이드를 마치면, 이 프로젝트에서 사용된 동일한 아키텍처를 갖게 될 것입니다: 모델을 호스팅하는 백그라운드 서비스 워커, 사이드 패널 채팅 UI, 그리고 페이지 수준의 작업을 위한 콘텐츠 스크립트입니다.

이 가이드에서는 Transformers.js Gemma 4 Browser Assistant의 핵심 아키텍처를 재현하며, 공개된 확장 프로그램을 참조하고 오픈 소스 코드베이스를 구현 매핑으로 사용합니다.

• 라이브 확장 프로그램: Chrome Web Store
• 소스 코드: github.com/nico-martin/gemma4-browser-extension
• 최종 결과물: 백그라운드 호스팅 Transformers.js 엔진, 사이드 패널 채팅 UI, 페이지 추출 및 하이라이트를 위한 콘텐츠 스크립트

본격적으로 시작하기 전에, 빠른 범위 설명: 저는 React UI 레이어 또는 Vite 빌드 구성을 깊이 있게 다루지 않습니다. 여기서는 상위 레벨 아키텍처 결정에 집중합니다: 각 Chrome 런타임에서 실행되는 내용과 그 부품들이 어떻게 조율되는지입니다.

Manifest V3이 처음이라면, 먼저 이 짧은 개요를 읽으세요: What is Manifest V3?.

MV3 에서 아키텍처는 public/manifest.json 에서 시작합니다.

이 프로젝트는 세 가지 진입점을 정의합니다:

• background.service_worker = background.js
  , src/background/background.ts 에서 구축됨.
• side_panel.default_path = sidebar.html
  , src/sidebar/index.html 에서 구축됨.
• content_scripts[].js = content.js
  과 matches: http(s)://*/* 및 run_at: document_idle, src/content/content.ts 에서 구축됨.

백그라운드 서비스 워커는 또한 활성화된 탭의 사이드 패널을 열기 위해 chrome.action.onClicked 을 처리합니다.
관련 진입점: action.default_popup 으로 팝업을 정의할 수 있으며, 빠른 작업에 잘 작동합니다. 이 프로젝트는 지속 가능한 채팅을 위한 사이드 패널을 사용하지만, 조율 패턴은 동일합니다.

핵심 설계 결정은 무거운 조율을 백그라운드에 두고 UI/페이지 로직을 얇게 유지하는 것입니다.

• 백그라운드 (src/background/background.ts) 는 제어 평면입니다: 에이전트 라이프사이클, 모델 초기화, 도구 실행 및 기능 추출과 같은 공유 서비스.
• 사이드 패널 (src/sidebar/*) 는 상호작용 레이어입니다: 채팅 입력/출력, 스트리밍 업데이트 및 설정 제어.
• 콘텐츠 스크립트 (src/content/content.ts) 는 페이지 브리지입니다: DOM 추출 및 하이라이트 작업.

이 분할의 실용적인 결과 중 하나는 대화 기록도 백그라운드에 lives (존재함) (Agent.chatMessages): UI 는 AGENT_GENERATE_TEXT 와 같은 이벤트를 보냅니다, 배경 애플리케이션은 메시지를 추가하고 추론을 실행한 후 사이드 패널로 MESSAGES_UPDATE 를 다시 방출합니다.

이 분할은 중복 모델 로딩을 피하고 UI 를 응답성 있게 유지하며 Chrome 의 DOM 접근 보안 경계를 존중합니다.

런타임이 분리되면 메시징이 핵심이 됩니다. 이 프로젝트에서는 모든 메시지가 src/shared/types.ts 에 있는 Enum 을 통해 타입화됩니다.

• 사이드 패널 -> 백그라운드 (BackgroundTasks): CHECK_MODELS, INITIALIZE_MODELS, AGENT_INITIALIZE, AGENT_GENERATE_TEXT, AGENT_GET_MESSAGES, AGENT_CLEAR, EXTRACT_FEATURES
• 백그라운드 -> 사이드 패널 (BackgroundMessages): DOWNLOAD_PROGRESS, MESSAGES_UPDATE
• 백그라운드 -> 콘텐츠 (ContentTasks): EXTRACT_PAGE_DATA, HIGHLIGHT_ELEMENTS, CLEAR_HIGHLIGHTS

조율 규칙은 간단합니다: 백그라운드는 단일 조정자이며, 사이드 패널과 콘텐츠 스크립트는 작업을 요청하고 결과를 렌더링하는 전문화된 워커입니다.

일반적인 요청 흐름:

• 사이드 패널이 AGENT_GENERATE_TEXT 를 보냅니다.
• 백그라운드는 Agent.chatMessages 에 추가하고 모델/도구 단계를 실행합니다.
• 백그라운드가 MESSAGES_UPDATE 를 방출합니다.
• 사이드 패널은 업데이트된 메시지 목록에서 다시 렌더링합니다.

src/shared/constants.ts 에서, 이 확장 프로그램은 두 가지 모델 역할을 사용합니다:

• TextGeneration / LLM: onnx-community/gemma-4-E2B-it-ONNX (text-generation, q4f16) - VectorEmbeddi