From a94c43343d78a2388bb6f51054566fdf81ba7cb4 Mon Sep 17 00:00:00 2001
From: figmar <figmar@yeah.net>
Date: Fri, 4 Sep 2026 20:20:09 +0800
Subject: [PATCH] =?UTF-8?q?docs(apes-sidebar):=20=E4=BF=AE=E6=AD=A3=20clie?=
 =?UTF-8?q?nt=20=E5=A5=91=E7=BA=A6=E6=8F=8F=E8=BF=B0=20+=20=E8=AE=B0?=
 =?UTF-8?q?=E5=BD=95=20=5F=5FModuleLoader=5F=5F=20bundle=20=E5=9D=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 规则 2 / Layout / Stack 段：client 入口实为命名 export function apply(ctx)
  （tsdown 打包为自包含 bundle，导出 { apply, ... }），非 AGENTS 旧述的
  'CJS closure factory — module.exports = (hostApi) => {}'——hostApi 描述失实，
  实际经 ctx.betterSidebar / ctx.effect 接线
- Gotchas 新增：lib/client.js 第 1 行是 window.__ModuleLoader__.load({...})，
  是 DSH browser 模块加载器格式，Node 侧 require 直接抛 'window is not
  defined'。这坐实 cordis scratch 挂载冒烟无法进单测门禁——client 产物
  按构造是 browser-only，不仅是缺 dsh CLI

门禁：typecheck rc=0 · build rc=0 · test 29/29
---
 AGENTS.md | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index efb32ed..c190f36 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,8 @@ better-sidebar and file a note in `docs/`.
 
 - **Language**: TypeScript (strict, `noUncheckedIndexedAccess`, ESM, `.ts` extension imports)
 - **Build**: `tsdown` (rolldown). Dual output — `lib/index.js` + `lib/invariant.js`
-  (host, ESM) and `lib/client.js` (client, CJS closure factory)
+  (host, ESM) and `lib/client.js` (client, self-contained bundle with a named
+  `apply` export)
 - **Type check**: `tsc --noEmit -p tsconfig.json`
 - **Unit tests**: `vitest` (node environment, no DOM)
 - **Package manager**: `pnpm` (Node ≥ 22.13 required — `node:sqlite` + pnpm 11)
@@ -40,7 +41,7 @@ src/
   invariant.ts        # invariant surface (assert, semver, peer guard) — dep-free
   context-types.ts    # service face contracts (ApesContext = CordisContext & {...})
   client/
-    index.tsx         # CLIENT entry: closure factory registering apes:* tabs
+    index.tsx         # CLIENT entry: named `apply(ctx)` registering apes:* tabs
     locales.ts        # i18n (zh default, en fallback) + useApesLocale hook
 tests/
   smoke.spec.ts       # host plugin shape + apply + invariant surface
@@ -60,9 +61,13 @@ cordis.patch.yml      # plugin registration into the DSH profile
 
 2. **Host / client split is load-bearing.**
    - The **host** half (`lib/index.js`) runs in Node. It may use Node builtins.
-   - The **client** half (`lib/client.js`) runs in the DSH browser shell. It is
-     a **CJS closure factory** — `module.exports = (hostApi) => {...}`. React is
-     external (host-provided). Never `import` a Node builtin into `src/client/**`.
+   - The **client** half (`lib/client.js`) runs in the DSH browser shell. Its
+     entry is a **named `export function apply(ctx: ApesClientContext)`** (not a
+     default export); tsdown bundles it to a self-contained module whose export
+     face is `{ apply, ... }`. The host wires it via `ctx.betterSidebar` /
+     `ctx.effect` (read from `ctx`, not a separately-injected `hostApi`).
+     React is external (host-provided). Never `import` a Node builtin into
+     `src/client/**`.
    - `src/invariant.ts` is reachable from BOTH halves — it must stay
      dependency-free (no Node builtins, no @deepseek-ai imports).
 
@@ -120,6 +125,14 @@ cordis.patch.yml      # plugin registration into the DSH profile
   pnpm store. A fresh `pnpm install` on a clean checkout will re-prompt.
 - The workspace path contains spaces and Chinese characters
   (`文稿 - figmarLite的MacBook Pro/...`) — always quote it in shell commands.
+- **`lib/client.js` is a DSH browser `__ModuleLoader__` bundle, NOT plain
+  CJS/ESM.** Line 1 is `window.__ModuleLoader__.load({...})` — it is consumed
+  by the DSH browser shell's module loader and **cannot be `require()`d in
+  Node** (top-level `window` reference throws `window is not defined`). This is
+  why the cordis scratch mount smoke cannot run in the unit gate: the client
+  artifact is browser-only by construction, not just because the `dsh` CLI is
+  absent. Unit specs test the **source** `src/client/index.tsx` (`apply`
+  contract), never the built bundle.
 
 ## Phase status