scriptscat · cyfung1031 · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026 · Sep 17, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -226,7 +226,7 @@ Service Worker (src/service_worker.ts)
   ├── ExtensionMessage ──────────────→ Content Script (src/content.ts)
   │                                        └── CustomEventMessage ──→ Inject Script (src/inject.ts)
   └── ServiceWorkerMessageSend ──────→ Offscreen (src/offscreen.ts)   (Chrome; Firefox uses EventPageOffscreenManager)
-                                           └── WindowMessage ──→ Sandbox (src/sandbox.ts)
+                                           └── private MessagePort ──→ Sandbox (src/sandbox.ts)
 ```
 
 > SW → Offscreen uses `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage`) on Chrome and
@@ -244,8 +244,9 @@ Sandbox.
 
 ### Message Passing (`packages/message/`)
 
-`ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔
-Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome),
+`ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `MessagePortMessage` +
+`SandboxChannelHost` (one-shot Window bootstrap, then private MessagePort — Offscreen/EventPage ↔ Sandbox),
+`ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome),
 `CustomEventMessage` (CustomEvent — Content ↔ Inject), and `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers

diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
@@ -104,7 +104,7 @@ of sanitization patterns can otherwise look like matches — so don't rely on a
 | [`design.md`](./design.md) | The design system; tokens, component palette, and layout/motion/state/a11y patterns → the three `references/design-*.md`. |
 | [`verification.md`](./verification.md) | *When* to drive the real built extension, where its evidence goes, how to report honestly. Not the harness — link to `e2e/README.md`, don't restate fixtures/isolation/env vars. |
 | [`../e2e/README.md`](../e2e/README.md) | The harness itself: the two tracks and their configs, isolation, fixture/helper inventory, protocol mocks, `E2E_*` variables, artifact paths. |
-| [`architecture.md`](./architecture.md) | Deep internals; subsystem deep-dives → the six `references/architecture-*.md`. |
+| [`architecture.md`](./architecture.md) | Deep internals; subsystem deep-dives → `references/architecture-*.md` and [`references/main-world-message-privacy.md`](./references/main-world-message-privacy.md). |
 | [`cloud-sync.md`](./cloud-sync.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: organization rules, fact-check / anti-drift discipline, policy-consistency checks — across every tracked contributor Markdown, not just `AGENTS.md` + `docs/*`. |

diff --git a/docs/README.md b/docs/README.md
@@ -12,7 +12,7 @@
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |
 | [`../e2e/README.md`](../e2e/README.md) | E2E 测试台手册:两条赛道(committed smoke / gitignored scratch)、浏览器与 profile 隔离、fixtures 与 helper 清单、协议 mock、`E2E_*` 环境变量、产物与失败排查路径。**跑 / 写 E2E 或一次性验证脚本前先读。** |
 | [`verification.md`](./verification.md) | 功能验证指南:启一个常驻会话(默认无头、可多 worktree 并发)逐条命令驱动真实扩展,只在需要复现顺序/时序时才写 spec,不跑全量 E2E、不加永久用例;驱动方法(GM API in-page self-test、SW 消息、主题)拆到 [`references/verification-methods.md`](./references/verification-methods.md),报告模板拆到 [`references/verification-report-template.md`](./references/verification-report-template.md),调试 FAQ 拆到 [`references/verification-debugging.md`](./references/verification-debugging.md)。**验证改动是否真正跑通时读。** |
-| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)、[`references/architecture-agent.md`](./references/architecture-agent.md)(Agent 子系统)。 |
+| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/main-world-message-privacy.md`](./references/main-world-message-privacy.md)(MAIN 消息隐私与回退策略)、[`references/sandbox-message-port-security.md`](./references/sandbox-message-port-security.md)(Sandbox 私有 MessagePort 威胁模型与验证)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)、[`references/architecture-agent.md`](./references/architecture-agent.md)(Agent 子系统)。 |
 | [`cloud-sync.md`](./cloud-sync.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、跨文档政策一致性核对、隐私清理、以及在 resolved final tree 上的复核方法,覆盖全部 tracked 的 agent/contributor Markdown(不止 `AGENTS.md` + `docs/*`,还包括 `.github/*.md`、package-local README)。**改/审文档前先读。** |
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -36,7 +36,7 @@ into several sandboxed JavaScript realms that cannot share memory; ScriptCat the
 Three ideas explain almost everything in the codebase:
 
 - **Contexts are processes.** Each entry point (`service_worker`, `content`, `inject`, `offscreen`, `sandbox`)
-  is an isolated realm. They never share objects — only serializable messages.
+  is an isolated realm. They do not share ordinary mutable objects — cross-context state moves through serialized or transferable messages.
 - **One message layer, several transports.** [`packages/message`](../packages/message) abstracts
   `chrome.runtime`, `postMessage`, and DOM `CustomEvent` behind a single RPC + pub/sub API, so services are
   written against interfaces (`Server`/`Group`/`Client`/`IMessageQueue`), not raw browser APIs.
@@ -62,9 +62,10 @@ Three ideas explain almost everything in the codebase:
                           │  bridges SW ↔ inject  │         │  DOM-capable background   │
                           │  Server("content")    │         │  Server("offscreen")      │
                           └──────────┬───────────┘         └─────────────┬────────────┘
-                       CustomEventMessage                        WindowMessage
-                       (DOM CustomEvent)                         (window.postMessage)
-                                     ▼                                   ▼
+                       CustomEventMessage                 SandboxChannelHost
+                       (DOM CustomEvent)                   one-shot Window bootstrap
+                                     ▼                          + private MessagePort
+                                                                    ▼
                           ┌──────────────────────┐         ┌──────────────────────────┐
                           │     INJECT SCRIPT     │         │       SANDBOX (iframe)    │
                           │  page realm,          │         │  with(){} script eval,    │
@@ -77,6 +78,12 @@ Three ideas explain almost everything in the codebase:
          inject, and sandbox don't hold a MessageQueue instance.
 ```
 
+The diagram compresses the page-facing routes: USER_SCRIPT content uses a native extension channel after bootstrap, while MAIN inject intentionally uses a single keyed performance-event bridge through `scripting`. The `scripting` bundle is a
+document-start extension content script registered per matching frame; it runs a page-bridge runtime and is a
+supporting per-document helper rather than a separate service/background context in this five-context model.
+`CustomEventMessage` carries the content bootstrap
+handoff and synchronous DOM handles; `PageEventMessage` carries MAIN pageLoad, runtime event/value updates, the whitelisted `external.Scriptcat` API, and validated GM RPC through the isolated `scripting` broker. It uses a random event name on `performance`, not the global `window.message` bus. The bridge itself is not an authenticated extension origin.
+
 ---
 
 ## The Five Contexts (Process Model)
@@ -86,13 +93,15 @@ Each context is a separate bundle (see [Build pipeline & manifest](./references/
 | Context | Entry | Realm / capabilities | Bootstraps |
 |---|---|---|---|
 | **Service Worker** | [`src/service_worker.ts`](../src/service_worker.ts) | No DOM. Owns `chrome.*` privileged APIs, storage, permissions, routing. | `ExtensionMessage(true)` → `Server("serviceWorker")` + `MessageQueue` → `ServiceWorkerManager` |
-| **Content** | [`src/content.ts`](../src/content.ts) | Isolated content-script world. Bridges SW and the page. | `CustomEventMessage` channel to inject + `Server("content")` → `ScriptRuntime` |
-| **Inject** | [`src/inject.ts`](../src/inject.ts) | Page (`MAIN`) world. Has `unsafeWindow`; runs page userscripts. | `CustomEventMessage` to content + `Server("inject")` |
-| **Offscreen** | [`src/offscreen.ts`](../src/offscreen.ts) | DOM-capable background page (Blobs, clipboard, DOM scraping, local storage). | `ExtensionMessage()` + `WindowMessage(window, sandbox)` → `OffscreenManager` |
-| **Sandbox** | [`src/sandbox.ts`](../src/sandbox.ts) | `sandbox`ed iframe inside offscreen. Evaluates background/scheduled scripts; runs cron. | `WindowMessage(window, parent)` + `Server("sandbox")` → `SandboxManager` |
+| **Content** | [`src/content.ts`](../src/content.ts) | `USER_SCRIPT` world. Receives a document bootstrap token through the page-side bridge, then uses a native extension channel for script loading, GM RPC, value updates, and callbacks. Dedicated USER_SCRIPT listeners are used when available; otherwise the regular port is token-bound. | `ExtensionMessage` + native callback port → `Server("content")` → `ScriptRuntime`; `CustomEventMessage` for bootstrap handoff and DOM handles |
+| **Inject** | [`src/inject.ts`](../src/inject.ts) | Page (`MAIN`) world. Has `unsafeWindow`; runs page userscripts. | `PageEventMessage` keyed performance-event bridge → `scripting`; broker/SW validate privileged RPC; `CustomEventMessage` for synchronous DOM handles |
+| **Offscreen** | [`src/offscreen.ts`](../src/offscreen.ts) | DOM-capable background page (Blobs, clipboard, DOM scraping, local storage). | SW receiver + `SandboxChannelHost`; parent installs the one-shot bootstrap listener before attaching the sandbox iframe |
+| **Sandbox** | [`src/sandbox.ts`](../src/sandbox.ts) | `sandbox`ed iframe inside offscreen/event page. Evaluates background/scheduled scripts; runs cron. | creates `MessageChannel`, wires `MessagePortMessage` + `Server("sandbox")`, then transfers the peer port to the parent as the readiness signal |
 
-There is also a sixth bundle, [`src/scripting.ts`](../src/scripting.ts), injected via `chrome.userScripts` /
-`chrome.scripting` to carry the compiled page-script payload (see [Script execution](./references/architecture-execution.md)).
+The [`scripting` bundle](../src/scripting.ts) is a document-start content script registered through
+`chrome.scripting`; it supplies the per-document page bridge. Compiled userscript payloads and the `inject.js` /
+`content.js` runners are registered separately through `chrome.userScripts` (see
+[Script execution](./references/architecture-execution.md)).
 
 ### Service-worker bootstrap
 
@@ -126,22 +135,17 @@ already has DOM and plays the offscreen role directly.
   `ExtensionMessage` (`chrome.runtime`).
 - **Firefox:** [`EventPageOffscreenManager`](../src/app/service/offscreen/event_page_manager.ts) substitutes
   for the offscreen document; its sandbox iframe is a `sandbox` manifest page, which Firefox 154+ loads as a
-  cross-origin frame (`contentDocument` is `null`, `contentWindow.location` is unreadable). Only the sandbox
-  itself knows when it's actually ready, so the parent never polls or pings it: `SandboxManager`
-  ([`src/app/service/sandbox/index.ts`](../src/app/service/sandbox/index.ts)) proactively posts a
-  `preparationSandbox` message once its own `Server` is wired up (same mechanism on both platforms), and
-  [`BackgroundEnvManagerBase.preparationSandbox`](../src/app/service/offscreen/base.ts) immediately tells the
-  service worker `preparationOffscreen({ verified: true })` — no round trip, no waiting. The service worker
-  replays enabled background/scheduled scripts and the current language only for this verified signal, once.
-  Separately and non-blockingly, the
-  sandbox reuses its own in-flight `getExtensionEnv` request to self-check that the channel is genuinely
-  bidirectional, and reports the outcome via `reportSandboxChannelHealth`, which the parent logs (visible in
-  the parent's own console/log, since the sandbox iframe's console is far less discoverable). If the sandbox
-  never announces readiness at all (iframe failed to load, script error), a fallback timer in
-  `BackgroundEnvManagerBase` still tells the service worker `preparationOffscreen({ verified: false })` after
-  `SANDBOX_READY_FALLBACK_MS`, logging a clear error instead of hanging forever. That unverified notification
-  does not send initialization through an unavailable channel; if the real handshake arrives later, the
-  verified state replay still occurs exactly once.
+  cross-origin frame (`contentDocument` is `null`, `contentWindow.location` is unreadable). The sandbox transport
+  is nevertheless the same as Chromium: the parent first installs a `SandboxChannelHost` bootstrap listener,
+  then attaches the iframe. After `sandbox.ts` has wired its `Server` and `Runtime`, it creates/transfers one
+  `MessagePort` to the parent. The parent accepts that capability only when `event.source` is the exact sandbox
+  `contentWindow`, removes the global Window `"message"` listener immediately, and uses the private port for all
+  subsequent traffic. Receiving the port is also the only verified sandbox-readiness signal; only then does
+  `BackgroundEnvManagerBase` call `preparationOffscreen({ verified: true })`, which lets the service worker replay
+  enabled background/scheduled scripts and language state. There is no second `preparationSandbox` RPC, health
+  ping, or unverified timeout-ready path. The transport threat model, same-realm prototype hardening, failure
+  semantics, and verification matrix are documented in
+  [Private Offscreen/EventPage ↔ Sandbox MessagePort](./references/sandbox-message-port-security.md).
 
 Firefox packages use `incognito: "spanning"`, so normal and private page scripts share one event page but retain
 their own `sender.tab.incognito` value for global-switch checks, `@run-in`, and `GM_info.isIncognito`. Background
@@ -167,9 +171,10 @@ communication styles** over **several transports**.
 
 | Class | File | Connects | Underlying API |
 |---|---|---|---|
-| `ExtensionMessage` | [`extension_message.ts`](../packages/message/extension_message.ts) | SW ↔ Content / Inject / Offscreen | `chrome.runtime.sendMessage` / `onConnect` (+ `onUserScript*` on Firefox) |
-| `CustomEventMessage` | [`custom_event_message.ts`](../packages/message/custom_event_message.ts) | Content ↔ Inject | DOM `CustomEvent` dispatch (bypasses page tampering) |
-| `WindowMessage` | [`window_message.ts`](../packages/message/window_message.ts) | Offscreen ↔ Sandbox | `window.postMessage` |
+| `ExtensionMessage` | [`extension_message.ts`](../packages/message/extension_message.ts) | SW ↔ Content / Inject / Offscreen | `chrome.runtime.sendMessage` / `onConnect`; browser-identified USER_SCRIPT messages are action-gated, and regular-port fallbacks are token-bound |
+| `PageEventMessage` | [`page_event_message.ts`](../packages/message/page_event_message.ts) | `scripting` ↔ Inject | Keyed `performance` `CustomEvent`; MAIN pageLoad, runtime updates, whitelisted external API, and GM RPC routed through the isolated broker and validated by `PageRpcRegistry` |
+| `CustomEventMessage` | [`custom_event_message.ts`](../packages/message/custom_event_message.ts) | Content ↔ `scripting` page helper | DOM `CustomEvent`; bootstrap handoff and synchronous DOM references, not privileged GM RPC |
+| `MessagePortMessage` / `SandboxChannelHost` | [`message_port_message.ts`](../packages/message/message_port_message.ts), [`sandbox_message_channel.ts`](../packages/message/sandbox_message_channel.ts) | Offscreen/EventPage ↔ Sandbox | sandbox-created `MessageChannel`; one strict source-checked Window bootstrap transfers the peer port, then all payloads use the private `MessagePort` |
 | `ServiceWorkerMessageSend` | [`window_message.ts`](../packages/message/window_message.ts) | SW → Offscreen (Chrome) | `clients.matchAll()` + `postMessage` |
 | `MessageQueue` | [`message_queue.ts`](../packages/message/message_queue.ts) | Broadcast among the contexts that instantiate it — SW, Offscreen, UI pages | `chrome.runtime.sendMessage` + local `EventEmitter3` |
 | `MockMessage` | [`mock_message.ts`](../packages/message/mock_message.ts) | Tests | in-memory `EventEmitter3` |

diff --git a/docs/develop.md b/docs/develop.md
@@ -11,7 +11,7 @@
 ```bash
 pnpm install              # install deps (preinstall enforces pnpm)
 pnpm run dev              # dev build (source maps); load dist/ext as unpacked extension
-pnpm run dev:noMap        # dev build w/o source maps (incognito)
+pnpm run dev:noMap        # dev build w/o source maps
 pnpm run build            # production Rspack build
 pnpm run pack             # package the extension (requires dist/scriptcat.pem)