From c1364a2f253aad359f8c64b98a48e383956ddb21 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 15:48:09 +0800
Subject: [PATCH 1/4] doc(web): agent note for the shell dist chunk split and
 directory layout

---
 ...8-06-web-shell-dist-chunk-layout.i18n.yaml |  6 +++
 .../2026-08-06-web-shell-dist-chunk-layout.md | 48 +++++++++++++++++++
 ...26-08-06-web-shell-dist-chunk-layout.zh.md | 48 +++++++++++++++++++
 3 files changed, 102 insertions(+)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
new file mode 100644
index 0000000000..0dc618924a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
+2026-08-06-web-shell-dist-chunk-layout.md: bce46591d65bae2daa61b1d513b4bdf37a9fad20
+2026-08-06-web-shell-dist-chunk-layout.zh.md: 595338ddec4ff5a9926dafcf0b1181241dc51788
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
new file mode 100644
index 0000000000..bce46591d6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
@@ -0,0 +1,48 @@
+# Agent Note: Web shell dist chunk split and directory layout
+
+Status: implemented
+
+English | [中文](2026-08-06-web-shell-dist-chunk-layout.zh.md)
+
+## Problem
+
+The apps/web shell previously built into a single ~1.2 MB (minified) index chunk, roughly 80% of it vendor bytes — KaTeX, the boot grammars and the shiki engine, react-dom, the markdown pipeline — fused with all the workspace shell code (about one fifth). Any one-line shell change rehashed the whole chunk, forcing returning clients to redownload everything; `dist/assets/` was a flat single-level spread of 100-plus files (the main chunk, 23 lazy-loaded grammar chunks, 59 KaTeX font faces, and sourcemaps intermixed), impossible to navigate.
+
+## Decision
+
+`apps/web/vite.config.ts` splits the shell into two initial chunks via `manualChunks` and sorts the output into directories via naming functions; the entire configuration contains zero regexes — an exact-package-name Set, a filename list, an extension list.
+
+**Membership** (`VENDOR_PACKAGES`, by exact npm package name):
+
+- `vendor` = the **facade packages** of the three heavy rendering families: math (katex, rehype-katex), highlight (shiki), markdown (react-markdown, remark-gfm, remark-math, mdast-util-from-markdown, mdast-util-gfm, micromark-extension-gfm, micromark-extension-math, micromark-factory-space, micromark-util-character, micromark-util-symbol, micromark-util-types). The list only needs the packages that workspace code **imports directly**: private transitive dependencies (the unified/hast family, the oniguruma family, @shikijs/core, and dozens more) are referenced only by these facades, so rollup's chunk coloring pulls them into vendor automatically; dependencies shared with the index side fall back to index, diluting it by a few KB — not a correctness issue.
+- `index` (the default chunk) = the react family, vendored cordis, all workspace code, and the unlisted small pieces (anser, clsx).
+- `@shikijs/langs` is special-cased: the boot grammars (`BOOT_GRAMMAR_FILES`: typescript, shellscript, json — the three that highlight.ts statically imports, all self-contained data modules with zero internal imports) go into vendor; the remaining 23 lazy-loaded grammars get no assignment and each keeps its own on-demand chunk.
+- `index.html` is wired up automatically by vite: index loads via `<script>` and vendor via `<link rel="modulepreload">`, so the two chunks fetch in parallel with no waterfall.
+
+**Directory layout** (`chunkFileNames` + `assetFileNames`):
+
+- The `assets/` root keeps only the index and vendor js (with their adjacent sourcemaps) and css.
+- Grammar chunks go under `assets/langs/`. The criterion is whether a chunk's `moduleIds` include an `@shikijs/langs` member, not the facade: the shared chunks of embedded grammars (php/ruby/mdx embed html+javascript, which rollup splits out for sharing) **have no facade**, so a facade criterion would miss them; index and vendor are excluded by name, because vendor legitimately carries the three boot grammars.
+- Fonts go under `assets/fonts/` (`FONT_EXTENSIONS`: woff2/woff/ttf; today all of them are KaTeX faces referenced by vendor.css, and the browser fetches only woff2, on demand and only when a formula renders).
+- Sourcemaps need no arrangement: rollup writes each `.map` next to its js and references it by bare relative filename, so when a chunk moves directories its map follows automatically.
+
+All cross-directory references (index's dynamic imports into `langs/`, same-directory relative references among grammar chunks, vendor.css's relative references into `fonts/`) are emitted by the bundler, so the runtime needs zero accompanying changes; the host-side webserver serves the nested paths verbatim under its static prefix.
+
+## Alternatives considered
+
+- **Serving react and the other vendors from a CDN**: dsh web targets local/intranet hosts (often without internet access), so a CDN is simply unavailable; react is the platform seed external of every plugin bundle (the shell is its sole supplier), and switching to the CDN global-variable form would touch three places — the platform manifest, the seed, and the module table; the caching benefit is already delivered by the vendor split.
+- **An inverse catch-all rule (everything in node_modules except the react family goes to vendor)**: membership cannot be read off the configuration, and small pieces like anser/clsx get misassigned to vendor; superseded by the positive exact-package-name list.
+- **Regex family matching**: hard to read; exact package names plus rollup's automatic coloring of transitive dependencies make pattern matching unnecessary.
+- **Identifying grammar chunks by facadeModuleId**: the facade-less shared chunks of embedded grammars would go undetected and fall back to the root directory; the `moduleIds` membership criterion covers both shapes.
+- **Lazy-loading KaTeX wholesale, or turning the boot TypeScript grammar lazy**: either would change first-frame rendering behavior (the fallback for formulas / the first code block); that trade-off is independent of the dist layout and is decided separately.
+
+## Verification
+
+A sourcemap byte-attribution audit proves that vendor contains no workspace bytes and that the npm side of index retains only the react family plus anser/clsx; the lazy grammar chunk count matches the `LAZY_GRAMMARS` table one to one; the browser keyless replay case is verbatim-identical to the pre-change baseline (apart from environment-specific local reds), so the two-chunk shell loads and renders with no regression.
+
+## Consequences
+
+- A shell code change rehashes only index (about one third of the dist output); vendor (about two thirds) stays cache-stable across shell releases and is invalidated only by dependency upgrades.
+- `dist/assets/` is navigable: two js/css pairs at the root, on-demand grammars in `langs/`, fonts in `fonts/`.
+- Maintenance cost: when workspace code adds a direct import of a rendering family's facade package, `VENDOR_PACKAGES` must be updated alongside (an omission merely dilutes index, nothing breaks); when the boot grammar set grows in highlight.ts without `BOOT_GRAMMAR_FILES` following, that grammar silently lands in index, visible only to a dist audit.
+- The webserver's static surface has no compression yet, so the gzip size win is still on the table; transport-layer compression is a separate, independent decision.
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
new file mode 100644
index 0000000000..595338ddec
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: Web 壳产物的 chunk 切分与目录布局
+
+Status: implemented
+
+[English](2026-08-06-web-shell-dist-chunk-layout.md) | 中文
+
+## Problem
+
+apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 管线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，回头客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主 chunk、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
+
+## Decision
+
+`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始 chunk，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
+
+**成员归属**（`VENDOR_PACKAGES`，按精确 npm 包名）：
+
+- `vendor` = 三个重渲染家族的**门面包**：math（katex、rehype-katex）、highlight（shiki）、markdown（react-markdown、remark-gfm、remark-math、mdast-util-from-markdown、mdast-util-gfm、micromark-extension-gfm、micromark-extension-math、micromark-factory-space、micromark-util-character、micromark-util-symbol、micromark-util-types）。清单只需列 workspace 代码**直接 import** 的包：私有传递依赖（unified/hast 系、oniguruma 系、@shikijs/core 等数十个）只被这些门面引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
+- `index`（默认 chunk）= react 族、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
+- `@shikijs/langs` 特判：boot 语法（`BOOT_GRAMMAR_FILES`：typescript、shellscript、json——highlight.ts 静态 import 的三件，均为零内部 import 的自含数据模块）进 vendor；其余 23 个懒加载语法不做指派，各自保持按需 chunk。
+- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两 chunk 并行拉取，无瀑布。
+
+**目录布局**（`chunkFileNames` + `assetFileNames`）：
+
+- `assets/` 根只留 index 与 vendor 的 js（含随行 sourcemap）与 css。
+- 语法 chunk 归 `assets/langs/`。判据是 chunk 的 `moduleIds` 含 `@shikijs/langs` 成员，而非 facade：内嵌语法共享 chunk（php/ruby/mdx 内嵌 html+javascript，被 rollup 拆出共享）**没有 facade**，facade 判据会漏；index/vendor 按名排除，因 vendor 合法携带 boot 三语法。
+- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面，浏览器按需只拉 woff2，且仅在公式渲染时）。
+- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，chunk 挪目录 map 自动跟随。
+
+跨目录引用（index 的动态 import 指向 `langs/`、语法 chunk 间同目录相对引用、vendor.css 相对引用 `fonts/`）均由构建器生成，运行时零配套改动；host 侧 webserver 按静态前缀原样服务嵌套路径。
+
+## Alternatives considered
+
+- **react 等 vendor 走 CDN**：dsh web 面向本机/内网主机（常无外网），CDN 直接不可用；react 是全部插件 bundle 的 platform seed external（壳是唯一供给方），改 CDN 全局变量形态需牵动 platform 清单/seed/模块表三处；缓存收益由 vendor 切分即可取得。
+- **反向兜底规则（node_modules 除 react 族全归 vendor）**：成员从配置上读不出来，且把 anser/clsx 类小件错归 vendor；被正向精确包名清单取代。
+- **正则家族匹配**：可读性差；精确包名 + rollup 对传递依赖的自动着色使模式匹配没有必要。
+- **以 facadeModuleId 识别语法 chunk**：无 facade 的内嵌语法共享 chunk 会漏检落回根目录；`moduleIds` 成员判据覆盖两种形态。
+- **KaTeX 整体懒加载、boot TypeScript 语法转懒**：会改变首帧渲染行为（公式/首个代码块的回退），是独立于产物布局的取舍，另行决策。
+
+## Verification
+
+sourcemap 字节归属审计证明 vendor 不含任何 workspace 字节、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
+
+## Consequences
+
+- 壳代码改动只重哈希 index（约为产物三分之一）；vendor（约三分之二）跨壳版本缓存稳定，仅依赖升级时失效。
+- `dist/assets/` 可导航：根两对 js/css，`langs/` 按需语法，`fonts/` 字体。
+- 维护成本：workspace 代码新增对某渲染家族门面包的直接 import 时需同步 `VENDOR_PACKAGES`（漏列仅稀释 index，不致坏）；在 highlight.ts 扩 boot 语法集而未同步 `BOOT_GRAMMAR_FILES` 时，该语法静默落入 index，仅产物审计可见。
+- webserver 静态面尚无压缩，gzip 体量是潜在值；传输层压缩是另一项独立决策。

From 021074c0ee2f46de09261a264fe897790004639f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 15:48:10 +0800
Subject: [PATCH 2/4] build(web): split the shell dist into index and vendor
 chunks with langs/ and fonts/ dirs

---
 apps/web/vite.config.ts | 91 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 842317911e..d2d717f0dc 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -18,10 +18,101 @@ function rejectStandaloneServe(): Plugin {
   }
 }
 
+/**
+ * Vendor-chunk membership, by exact npm package name — the heavy render
+ * families (math, highlight, markdown) that change only on dependency bumps.
+ * Only packages workspace code imports DIRECTLY need listing: their private
+ * transitive dependencies (unified/hast/oniguruma machinery, ~50 packages)
+ * are imported solely by these and rollup's chunk coloring pulls them into
+ * vendor automatically. A dependency shared with index-side code falls back
+ * to index — a few kB of dilution, never a correctness problem. Anything not
+ * listed (react family, the vendored cordis workspace, tiny helpers like
+ * anser/clsx, all workspace code) stays in the default `index` chunk, so
+ * editing shell code re-hashes only index and returning clients keep the
+ * cached vendor chunk.
+ */
+const VENDOR_PACKAGES: ReadonlySet<string> = new Set([
+  // math
+  'katex',
+  'rehype-katex',
+  // syntax highlight (@shikijs/langs is handled separately below —
+  // lazy grammars must not land here)
+  'shiki',
+  // markdown pipeline
+  'react-markdown',
+  'remark-gfm',
+  'remark-math',
+  'mdast-util-from-markdown',
+  'mdast-util-gfm',
+  'micromark-extension-gfm',
+  'micromark-extension-math',
+  'micromark-factory-space',
+  'micromark-util-character',
+  'micromark-util-symbol',
+  'micromark-util-types',
+])
+
+/**
+ * Boot grammars statically imported by ui-primitives' highlight.ts
+ * (`@shikijs/langs/typescript` → `dist/typescript.mjs`, etc.). They live in
+ * the same package as the lazy read-card grammars, but unlike those they are
+ * part of the initial load and belong in the vendor chunk; the lazy ones must
+ * stay unassigned so each keeps its own on-demand chunk.
+ */
+const BOOT_GRAMMAR_FILES: readonly string[] = [
+  'dist/typescript.mjs',
+  'dist/shellscript.mjs',
+  'dist/json.mjs',
+]
+
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces today). */
+const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
+
+/** npm package name of a resolved module id (the segment after the LAST `node_modules/` — pnpm nests the real package under an inner node_modules). */
+function npmPackageOf(id: string): string | undefined {
+  const parts = id.split('/node_modules/')
+  if (parts.length === 1) return undefined
+  const [first, second] = parts[parts.length - 1].split('/')
+  if (first.startsWith('.')) return undefined // .pnpm store segment, not a package
+  return first.startsWith('@') ? `${first}/${second}` : first
+}
+
 export default defineConfig({
   plugins: [rejectStandaloneServe(), react()],
   build: {
     sourcemap: true,
+    rollupOptions: {
+      output: {
+        // Output layout: the two main chunks stay at assets/ root; lazy
+        // @shikijs/langs grammar chunks group under assets/langs/; fonts
+        // (today all KaTeX faces referenced by vendor.css) group under
+        // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
+        // .map next to its js and references it by bare relative filename.
+        chunkFileNames(chunk): string {
+          // Grammar chunks are recognized by their member modules, not the
+          // facade: shared embedded-grammar chunks (e.g. html+javascript,
+          // split out because php/ruby/mdx embed them) have no facade at all.
+          // index and vendor are excluded by name — vendor legitimately
+          // carries the three boot grammars.
+          if (chunk.name === 'index' || chunk.name === 'vendor') return 'assets/[name]-[hash].js'
+          const isLangChunk = chunk.moduleIds.some(id => id.includes('/node_modules/@shikijs/langs/'))
+          return isLangChunk ? 'assets/langs/[name]-[hash].js' : 'assets/[name]-[hash].js'
+        },
+        assetFileNames(asset): string {
+          const fileName = asset.names[0] ?? ''
+          const isFont = FONT_EXTENSIONS.some(ext => fileName.endsWith(ext))
+          return isFont ? 'assets/fonts/[name]-[hash][extname]' : 'assets/[name]-[hash][extname]'
+        },
+        manualChunks(id: string): string | undefined {
+          const pkg = npmPackageOf(id)
+          if (pkg === undefined) return undefined // workspace + vendored cordis: index
+          if (pkg === '@shikijs/langs') {
+            return BOOT_GRAMMAR_FILES.some(file => id.endsWith(`/${file}`)) ? 'vendor' : undefined
+          }
+          return VENDOR_PACKAGES.has(pkg) ? 'vendor' : undefined
+        },
+      },
+    },
   },
   resolve: {
     // Workspace packages resolve to SOURCE: package.json exports point at lib

From 193473dab2894edc14e15d6e3a14f8f8cc96ae15 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:26:38 +0800
Subject: [PATCH 3/4] doc(web): update the chunk-layout note for the react-free
 vendor invariant and the audit tool

---
 .../2026-08-06-web-shell-dist-chunk-layout.i18n.yaml   |  4 ++--
 .../2026-08-06-web-shell-dist-chunk-layout.md          | 10 ++++++----
 .../2026-08-06-web-shell-dist-chunk-layout.zh.md       | 10 ++++++----
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
index 0dc618924a..815f5eee75 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
-2026-08-06-web-shell-dist-chunk-layout.md: bce46591d65bae2daa61b1d513b4bdf37a9fad20
-2026-08-06-web-shell-dist-chunk-layout.zh.md: 595338ddec4ff5a9926dafcf0b1181241dc51788
+2026-08-06-web-shell-dist-chunk-layout.md: 1c7b4273dc243685317b149e2fd7fddf2a6c18d1
+2026-08-06-web-shell-dist-chunk-layout.zh.md: 6f4b94e0bd7412e480458e34922273b389aa8892
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
index bce46591d6..1c7b4273dc 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
@@ -14,8 +14,9 @@ The apps/web shell previously built into a single ~1.2 MB (minified) index chunk
 
 **Membership** (`VENDOR_PACKAGES`, by exact npm package name):
 
-- `vendor` = the **facade packages** of the three heavy rendering families: math (katex, rehype-katex), highlight (shiki), markdown (react-markdown, remark-gfm, remark-math, mdast-util-from-markdown, mdast-util-gfm, micromark-extension-gfm, micromark-extension-math, micromark-factory-space, micromark-util-character, micromark-util-symbol, micromark-util-types). The list only needs the packages that workspace code **imports directly**: private transitive dependencies (the unified/hast family, the oniguruma family, @shikijs/core, and dozens more) are referenced only by these facades, so rollup's chunk coloring pulls them into vendor automatically; dependencies shared with the index side fall back to index, diluting it by a few KB — not a correctness issue.
-- `index` (the default chunk) = the react family, vendored cordis, all workspace code, and the unlisted small pieces (anser, clsx).
+- `vendor` = the three heavy rendering families: math (katex), highlight (shiki), markdown (the micromark/mdast parse pipeline — the incremental React renderer above it is workspace code and not part of this). The live membership is `VENDOR_PACKAGES`; the list is the packages workspace code **imports directly**: the remaining private transitive dependencies (the oniguruma family, @shikijs/core, character tables, dozens more) are referenced only by listed members, so rollup's chunk coloring pulls them into vendor automatically; dependencies shared with the index side fall back to index, diluting it by a few KB — not a correctness issue.
+- **Every vendor member must be react-free (the boundary invariant)**: rollup folds a module shared between the entry and a manual chunk into the manual chunk — one listed package importing react/jsx-runtime would drag the single shared react copy into vendor, away from index. The React side of markdown/math rendering is workspace code and naturally lives in index, so the whole react family stays pinned to index.
+- `index` (the default chunk) = the react family (react, react-dom, scheduler, use-sync-external-store), vendored cordis, all workspace code, and the unlisted small pieces (anser, clsx).
 - `@shikijs/langs` is special-cased: the boot grammars (`BOOT_GRAMMAR_FILES`: typescript, shellscript, json — the three that highlight.ts statically imports, all self-contained data modules with zero internal imports) go into vendor; the remaining 23 lazy-loaded grammars get no assignment and each keeps its own on-demand chunk.
 - `index.html` is wired up automatically by vite: index loads via `<script>` and vendor via `<link rel="modulepreload">`, so the two chunks fetch in parallel with no waterfall.
 
@@ -23,7 +24,7 @@ The apps/web shell previously built into a single ~1.2 MB (minified) index chunk
 
 - The `assets/` root keeps only the index and vendor js (with their adjacent sourcemaps) and css.
 - Grammar chunks go under `assets/langs/`. The criterion is whether a chunk's `moduleIds` include an `@shikijs/langs` member, not the facade: the shared chunks of embedded grammars (php/ruby/mdx embed html+javascript, which rollup splits out for sharing) **have no facade**, so a facade criterion would miss them; index and vendor are excluded by name, because vendor legitimately carries the three boot grammars.
-- Fonts go under `assets/fonts/` (`FONT_EXTENSIONS`: woff2/woff/ttf; today all of them are KaTeX faces referenced by vendor.css, and the browser fetches only woff2, on demand and only when a formula renders).
+- Fonts go under `assets/fonts/` (`FONT_EXTENSIONS`: woff2/woff/ttf; today all of them are KaTeX faces referenced by vendor.css — katex.min.css is imported by an index-side component, but CSS modules go through manualChunks like any module and follow `katex` into vendor.css; the browser fetches only woff2, on demand and only when a formula renders).
 - Sourcemaps need no arrangement: rollup writes each `.map` next to its js and references it by bare relative filename, so when a chunk moves directories its map follows automatically.
 
 All cross-directory references (index's dynamic imports into `langs/`, same-directory relative references among grammar chunks, vendor.css's relative references into `fonts/`) are emitted by the bundler, so the runtime needs zero accompanying changes; the host-side webserver serves the nested paths verbatim under its static prefix.
@@ -34,11 +35,12 @@ All cross-directory references (index's dynamic imports into `langs/`, same-dire
 - **An inverse catch-all rule (everything in node_modules except the react family goes to vendor)**: membership cannot be read off the configuration, and small pieces like anser/clsx get misassigned to vendor; superseded by the positive exact-package-name list.
 - **Regex family matching**: hard to read; exact package names plus rollup's automatic coloring of transitive dependencies make pattern matching unnecessary.
 - **Identifying grammar chunks by facadeModuleId**: the facade-less shared chunks of embedded grammars would go undetected and fall back to the root directory; the `moduleIds` membership criterion covers both shapes.
+- **Sheltering a react-edged rendering facade in vendor** (the historical react-markdown was one): rollup's shared-module folding would drag the single react copy into vendor, breaking the "react belongs to index" boundary; the constraint is codified as the list's boundary invariant.
 - **Lazy-loading KaTeX wholesale, or turning the boot TypeScript grammar lazy**: either would change first-frame rendering behavior (the fallback for formulas / the first code block); that trade-off is independent of the dist layout and is decided separately.
 
 ## Verification
 
-A sourcemap byte-attribution audit proves that vendor contains no workspace bytes and that the npm side of index retains only the react family plus anser/clsx; the lazy grammar chunk count matches the `LAZY_GRAMMARS` table one to one; the browser keyless replay case is verbatim-identical to the pre-change baseline (apart from environment-specific local reds), so the two-chunk shell loads and renders with no regression.
+The audit tool ships with the repository: `node scripts/attribute-chunk-bytes.mjs <chunk.js>` (zero-dependency sourcemap VLQ byte attribution, aggregated by npm package / workspace directory). It verifies that vendor contains no workspace bytes, that the react family (including react/jsx-runtime) sits entirely in index, and that the npm side of index retains only the react family plus anser/clsx; the lazy grammar chunk count matches the `LAZY_GRAMMARS` table one to one; the browser keyless replay case is verbatim-identical to the pre-change baseline (apart from environment-specific local reds), so the two-chunk shell loads and renders with no regression.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
index 595338ddec..6f4b94e0bd 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
@@ -14,8 +14,9 @@ apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其
 
 **成员归属**（`VENDOR_PACKAGES`，按精确 npm 包名）：
 
-- `vendor` = 三个重渲染家族的**门面包**：math（katex、rehype-katex）、highlight（shiki）、markdown（react-markdown、remark-gfm、remark-math、mdast-util-from-markdown、mdast-util-gfm、micromark-extension-gfm、micromark-extension-math、micromark-factory-space、micromark-util-character、micromark-util-symbol、micromark-util-types）。清单只需列 workspace 代码**直接 import** 的包：私有传递依赖（unified/hast 系、oniguruma 系、@shikijs/core 等数十个）只被这些门面引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
-- `index`（默认 chunk）= react 族、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
+- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析管线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
+- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码天然住 index，react 族因此全部钉在 index。
+- `index`（默认 chunk）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
 - `@shikijs/langs` 特判：boot 语法（`BOOT_GRAMMAR_FILES`：typescript、shellscript、json——highlight.ts 静态 import 的三件，均为零内部 import 的自含数据模块）进 vendor；其余 23 个懒加载语法不做指派，各自保持按需 chunk。
 - `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两 chunk 并行拉取，无瀑布。
 
@@ -23,7 +24,7 @@ apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其
 
 - `assets/` 根只留 index 与 vendor 的 js（含随行 sourcemap）与 css。
 - 语法 chunk 归 `assets/langs/`。判据是 chunk 的 `moduleIds` 含 `@shikijs/langs` 成员，而非 facade：内嵌语法共享 chunk（php/ruby/mdx 内嵌 html+javascript，被 rollup 拆出共享）**没有 facade**，facade 判据会漏；index/vendor 按名排除，因 vendor 合法携带 boot 三语法。
-- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面，浏览器按需只拉 woff2，且仅在公式渲染时）。
+- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
 - sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，chunk 挪目录 map 自动跟随。
 
 跨目录引用（index 的动态 import 指向 `langs/`、语法 chunk 间同目录相对引用、vendor.css 相对引用 `fonts/`）均由构建器生成，运行时零配套改动；host 侧 webserver 按静态前缀原样服务嵌套路径。
@@ -34,11 +35,12 @@ apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其
 - **反向兜底规则（node_modules 除 react 族全归 vendor）**：成员从配置上读不出来，且把 anser/clsx 类小件错归 vendor；被正向精确包名清单取代。
 - **正则家族匹配**：可读性差；精确包名 + rollup 对传递依赖的自动着色使模式匹配没有必要。
 - **以 facadeModuleId 识别语法 chunk**：无 facade 的内嵌语法共享 chunk 会漏检落回根目录；`moduleIds` 成员判据覆盖两种形态。
+- **在 vendor 里收留带 react 边的渲染门面**（历史上的 react-markdown 属此类）：会经 rollup 的共享模块归并把唯一 react 副本拽进 vendor，破坏「react 归 index」的边界；该约束已成文为清单的边界不变量。
 - **KaTeX 整体懒加载、boot TypeScript 语法转懒**：会改变首帧渲染行为（公式/首个代码块的回退），是独立于产物布局的取舍，另行决策。
 
 ## Verification
 
-sourcemap 字节归属审计证明 vendor 不含任何 workspace 字节、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
+审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
 
 ## Consequences
 

From 90f738a4c73fb4e4fe6aa09ec4635d98332a00f3 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:26:38 +0800
Subject: [PATCH 4/4] build(web): react-free vendor list for the incremental
 markdown pipeline, npmPackageOf scoped guard, chunk audit script

---
 apps/web/vite.config.ts           |  25 +++++++++++++++++--------
 scripts/attribute-chunk-bytes.mjs | Bin 0 -> 4072 bytes
 2 files changed, 17 insertions(+), 8 deletions(-)
 create mode 100644 scripts/attribute-chunk-bytes.mjs

diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index d2d717f0dc..c5a6e6cc11 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -22,32 +22,40 @@ function rejectStandaloneServe(): Plugin {
  * Vendor-chunk membership, by exact npm package name — the heavy render
  * families (math, highlight, markdown) that change only on dependency bumps.
  * Only packages workspace code imports DIRECTLY need listing: their private
- * transitive dependencies (unified/hast/oniguruma machinery, ~50 packages)
- * are imported solely by these and rollup's chunk coloring pulls them into
+ * transitive dependencies (oniguruma machinery, character tables, …) are
+ * imported solely by these and rollup's chunk coloring pulls them into
  * vendor automatically. A dependency shared with index-side code falls back
  * to index — a few kB of dilution, never a correctness problem. Anything not
  * listed (react family, the vendored cordis workspace, tiny helpers like
  * anser/clsx, all workspace code) stays in the default `index` chunk, so
  * editing shell code re-hashes only index and returning clients keep the
  * cached vendor chunk.
+ *
+ * Boundary invariant: every member must be react-free. A package that
+ * imports react/jsx-runtime must never be listed — rollup folds a module
+ * shared between the entry and a manual chunk into the manual chunk, so one
+ * react-importing member would drag the single shared react copy into
+ * vendor. The React side of markdown/math rendering is workspace code and
+ * rides index.
  */
 const VENDOR_PACKAGES: ReadonlySet<string> = new Set([
   // math
   'katex',
-  'rehype-katex',
   // syntax highlight (@shikijs/langs is handled separately below —
   // lazy grammars must not land here)
   'shiki',
-  // markdown pipeline
-  'react-markdown',
-  'remark-gfm',
-  'remark-math',
+  // markdown parse pipeline (micromark/mdast; the incremental React renderer
+  // over it is workspace code)
   'mdast-util-from-markdown',
   'mdast-util-gfm',
+  'mdast-util-math',
+  'micromark-core-commonmark',
   'micromark-extension-gfm',
   'micromark-extension-math',
   'micromark-factory-space',
   'micromark-util-character',
+  'micromark-util-classify-character',
+  'micromark-util-sanitize-uri',
   'micromark-util-symbol',
   'micromark-util-types',
 ])
@@ -74,7 +82,8 @@ function npmPackageOf(id: string): string | undefined {
   if (parts.length === 1) return undefined
   const [first, second] = parts[parts.length - 1].split('/')
   if (first.startsWith('.')) return undefined // .pnpm store segment, not a package
-  return first.startsWith('@') ? `${first}/${second}` : first
+  if (first.startsWith('@')) return second === undefined ? undefined : `${first}/${second}`
+  return first
 }
 
 export default defineConfig({
diff --git a/scripts/attribute-chunk-bytes.mjs b/scripts/attribute-chunk-bytes.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..d7cc1130d9e012897433d25ad13b4688ff3550cc
GIT binary patch
literal 4072
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
Mu#81_zZf$AUtLfIzW@LL

literal 0
HcmV?d00001