@morlay/dsh-client-modules 0.2.11-alpha.2 → 0.2.11

package/src/bundle.ts

@@ -12,12 +12,13 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { findPackageJSON } from "node:module";
-import { dirname, join, relative, sep } from "node:path";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { clientAssetPlugin, NODE_BUILTIN } from "@morlay/dsh-cordis-assets/assets";
 import { cssInlinePlugins } from "@morlay/dsh-cordis-assets/styles";
 import { rolldown, type Plugin } from "rolldown";
 import { esmExternalRequirePlugin, type PluginOption } from "vite";
+import { type ClientBuildMeta, clientBuildMeta, clientMetaDefines } from "./client-meta.ts";
 import { encodePackageName, entryFileNameOf, packageNameOf } from "./resolve.ts";
 
 /** 裸包名 → `^名(/|$)`：既覆盖子路径引用，也不会把 `node:fs`、`./x` 误判成包。 */
@@ -61,7 +62,7 @@ export function clientModulesAlias(options: {
  * 规则变了、源码没变时，旧产物必须作废，否则会继续复用带着老 URL 的字节。
  */
 /** 构建器**规则**版本：改解析 / 改写规则就 bump（见 {@link BUNDLER_REV}）。 */
-const BUNDLER_RULES = "22";
+const BUNDLER_RULES = "36";
 
 /**
  * 地址里的 `?v=`（与 vite 同一个写法）：构建器**规则指纹**（`BUNDLER_RULES` 的哈希，形如 vite 的 `?v=`）。
@@ -96,7 +97,7 @@ export interface BundleOptions {
   name: string;
   /** 包版本（进缓存键与地址）。 */
   version: string;
-  /** 入口名 → 源码文件（我们的包：出口名；三方：`index`）。 */
+  /** 出口名 → 入口文件（由调用方的清单解析得到：`exports` 条件 / `module` / `main`）。 */
   input: Record<string, string>;
   /** 指纹的输入文件集（我们的包给 `src`；三方给它的入口）。 */
   watch: readonly string[];
@@ -307,11 +308,15 @@ export function urlOf(
  * **只替换 `process.env` 系列**：裸的 `process` 不能碰——它可能只是个普通标识符（`zod` 里就有一个叫
  * `process` 的函数，替换掉直接把源码变成语法错误）。
  */
-function browserProcessPlugin(): PluginOption {
-  const replace = (code: string): string =>
-    code
-      .replaceAll(/\bprocess\.env\.NODE_ENV\b/gu, JSON.stringify("development"))
-      .replaceAll(/\bprocess\.env\b/gu, "({ env: {} })");
+export function browserProcessPlugin(meta: ClientBuildMeta = {}): PluginOption {
+  // 版本元数据那几个键**先**换成字面量：它们要的是真值（设置页的版本行、侧栏的 `<commit>-dirty`），
+  // 而后面那条把 `process.env` 整个换成空壳的规则会连它们一起吞掉。
+  const metaDefines = Object.entries(clientMetaDefines(meta));
+  const replace = (code: string): string => {
+    let next = code.replaceAll(/\bprocess\.env\.NODE_ENV\b/gu, JSON.stringify("development"));
+    for (const [key, value] of metaDefines) next = next.replaceAll(key, value);
+    return next.replaceAll(/\bprocess\.env\b/gu, "({ env: {} })");
+  };
   return {
     name: "dsh-browser-process",
     enforce: "pre",
@@ -323,81 +328,262 @@ function browserProcessPlugin(): PluginOption {
 }
 
 /**
- * CJS 入口的**具名导出包装**（`react` 这类）。
+ * `export const <名>` 用不了的键：JS 的保留字（`zod@4` 的 CJS 面有 `function` / `void` / `null`
+ * 这些键，原样拼出去就是 `SyntaxError`）。
+ */
+const RESERVED_EXPORT_NAMES = new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "eval",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "undefined",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+]);
+
+/** ESM 的顶层语法节点：`import` / `export` 声明。 */
+const ESM_STATEMENT_TYPES = new Set([
+  "ImportDeclaration",
+  "ExportNamedDeclaration",
+  "ExportDefaultDeclaration",
+  "ExportAllDeclaration",
+]);
+
+/**
+ * `.js` 且没有 `type` 时，按 **Node 的语法检测**判：有 ESM 语法（顶层 `import`/`export`）就是 ESM，
+ * 否则 CJS（Node 23+ 默认开启 `--experimental-detect-module`）。
+ *
+ * 用 rolldown 自带的解析器（`rolldown/parseAst`），不自己写词法扫描。
+ *
+ * @param entry - `.js` 入口的绝对路径。
+ * @returns 是否含 ESM 语法。
+ */
+async function hasModuleSyntax(entry: string): Promise<boolean> {
+  try {
+    const [{ parseAst }, source] = await Promise.all([
+      import("rolldown/parseAst"),
+      readFile(entry, "utf8"),
+    ]);
+    const program = parseAst(source, null, entry) as unknown as {
+      body: readonly { type: string }[];
+    };
+    return program.body.some((node) => ESM_STATEMENT_TYPES.has(node.type));
+  } catch {
+    // 解析不了（CJS 专有语法在 module 模式下报错等）：按 CJS 走，求值失败时保持原样。
+    return false;
+  }
+}
+
+/** 一个入口的模块类型。 */
+export type ModuleKind = "esm" | "cjs" | "source" | "style" | "asset";
+
+/**
+ * 一个入口的模块类型：**扩展名 + 最近的 `package.json`**，不猜源码。
+ *
+ * | 入口 | 类型 |
+ * | --- | --- |
+ * | `.mjs` / `.mts` | `esm` |
+ * | `.cjs` / `.cts` | `cjs` |
+ * | `.js` + `type: "module"` | `esm` |
+ * | `.js` + `module` 字段指向它 | `esm`（打包器约定） |
+ * | 其余 `.js` | `cjs` |
+ * | `.ts` / `.tsx` / `.jsx` | `source`（转译面，原样） |
+ * | `.css` | `style` |
+ * | 其他（图片 / 字体 / `.json` …） | `asset` |
+ *
+ * 这是 `exports` 条件（`import` / `require`）选出入口之后的**第二步**：条件决定"哪个文件"，这里决定
+ * "那个文件是什么模块"。只有 `cjs` 需要导出面适配，`esm` / `source` 一律原样。
+ *
+ * @param entry - 入口的绝对路径。
+ * @returns 模块类型。
+ */
+export async function moduleKindOf(entry: string): Promise<ModuleKind> {
+  const extension = extname(entry).toLowerCase();
+  if (extension === ".css") return "style";
+  if (extension === ".mjs" || extension === ".mts") return "esm";
+  if (extension === ".cjs" || extension === ".cts") return "cjs";
+  if (extension === ".ts" || extension === ".tsx" || extension === ".jsx") return "source";
+  if (extension !== ".js") return "asset";
+  const manifestPath = await packageJsonNear(entry);
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8").catch(() => "{}")) as {
+    type?: string;
+  };
+  if (manifest.type === "module") return "esm";
+  if (manifest.type === "commonjs") return "cjs";
+  // 没有 `type`：Node 的规则是**语法检测**（`--experimental-detect-module`，Node 23+ 默认开启）。
+  return (await hasModuleSyntax(entry)) ? "esm" : "cjs";
+}
+
+/**
+ * CJS 入口的**具名导出包装**（`react` / `@xterm/xterm` 这类）。
  *
- * `react` 的入口是 `module.exports = require('./cjs/react.development.js')`，rolldown 静态分析不出具名
- * 导出，产物只剩 `export default …`——而浏览器侧要 `import { Fragment } from "react"`，于是**整个 import
- * 阶段就失败**（入口一行都执行不了）。ESM 的导出必须**静态可枚举**（不能 `export * from` 一个运行期对象），
- * 所以这里求值入口拿到它的键，生成一份把它们写成 `export const` 的包装文件，拿包装文件当入口。
+ * rolldown 对 CJS 入口的产物的具名导出只能靠静态分析；`module.exports = require(…)` 与 UMD 包装它都分析
+ * 不出来，产物只剩 `export default …`——而浏览器侧要 `import { Fragment } from "react"`、`import { Terminal }
+ * from "@xterm/xterm"`，整个 import 阶段就失败。ESM 的导出必须**静态可枚举**，所以这里求值入口拿到它的键，
+ * 生成一份把它们写成 `export const` 的包装文件，拿包装文件当入口。
  *
- * @returns 包装文件路径；入口不是 CJS、或求值拿不到键时 undefined（保持原样）。
+ * 类型由 {@link moduleKindOf} 先按 **exports 落点 + 扩展名/type** 静态判定，只有 CJS 才进来；
+ * 这里求值一次只为**拿键**（`export const <键>` + `default = module.exports`）。ESM 原封不动。
+ *
+ * @returns 包装文件路径；入口不是 node 能求值的 CJS、或没有可静态导出的键时 undefined（保持原样）。
  */
 async function cjsShimOf(options: {
   name: string;
   exportName: string;
+  /** 具体文件：只用来求值判 CJS / 枚举键。 */
   entry: string;
-  outDir: string;
+  /** 产物里的 import 来源：说明符（交给 rolldown 按 `exports` 解析）或文件路径。 */
+  from: string;
   log?: (message: string) => void;
-}): Promise<string | undefined> {
-  const source = await readFile(options.entry, "utf8").catch(() => "");
-  // 判据是**CJS 入口**：`.js`/`.cjs` 且源码里真的在赋值 `module.exports` / `exports.x`（`react` 的入口是
-  // `module.exports = require('./cjs/…')`）。TS 源码不在此列——那是 ESM；按"含 `exports.` 子串"判断会把
-  // 注释里的 `re-exports.` 也当成 CJS，反过来给一份纯 ESM 加 `import mod from …` 而构建失败。
-  const isCjsEntry =
-    /\.(?:cjs|js)$/u.test(options.entry) &&
-    /(?:^|\n)\s*(?:module\.exports\s*=|exports\.[A-Za-z_$][A-Za-z0-9_$]*\s*=)/u.test(source);
-  if (!isCjsEntry) return undefined;
-  let keys: string[];
+}): Promise<{ id: string; code: string } | undefined> {
+  let loaded: Record<string, unknown> | undefined;
   try {
-    // 求值才知道键：CJS 的导出面是**运行期**的（静态分析只能看到 `module.exports = require(…)`）。
-    const loaded = createRequire(options.entry)(options.entry) as
-      | Record<string, unknown>
-      | undefined;
-    keys = Object.keys(loaded ?? {});
+    // 类型已由 {@link moduleKindOf} 静态判定（只有 CJS 会走到这里）；这一句只为**拿键**：
+    // CJS 的导出面是运行期的（`module.exports = require(…)` / UMD 包装，静态分析看不到键）。
+    loaded = createRequire(options.entry)(options.entry) as Record<string, unknown> | undefined;
   } catch {
     // 求值有副作用、或本来就是不能在 node 里加载的东西：宁可只有 default 导出，也不要让构建挂掉。
     return undefined;
   }
-  const named = keys.filter((key) => key !== "default" && /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(key));
-  if (named.length === 0) return undefined;
-  const file = join(options.outDir, `${options.exportName.replaceAll("/", "+")}.cjs-shim.mjs`);
-  await mkdir(dirname(file), { recursive: true });
-  await writeFile(
-    file,
-    [
-      `import mod from ${JSON.stringify(options.entry)};`,
-      // 用**计算属性**读：`mod.jsxDEV` 这种静态属性访问会被 rolldown 按它对 CJS 命名空间的静态理解
-      // 摇成 `void 0`（`react/jsx-dev-runtime` 就那么被摇空了，页面报 `jsxDEV is not a function`）。
-      "const __cjs = mod ?? {};",
-      "export default __cjs;",
-      ...named.map((key) => `export const ${key} = __cjs[${JSON.stringify(key)}];`),
-      "",
-    ].join("\n"),
-    "utf8",
+  const keys = Object.keys(loaded ?? {});
+  const named = keys.filter(
+    (key) =>
+      key !== "default" &&
+      /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(key) &&
+      !RESERVED_EXPORT_NAMES.has(key),
   );
+  if (named.length === 0) return undefined;
+
+  // **不落盘**：这是一份只喂给 rolldown 的入口，用虚拟模块（`\0` 前缀 + resolveId/load）即可。
+  // 落成文件反而要操心"放哪、相对路径怎么算、缓存目录里会不会残留"——入口用绝对路径，rolldown 在
+  // **构建期**把它读进来（内联进产物），产物里不会出现这个路径。
+  const id = `\0dsh-cjs-shim:${options.name}:${options.exportName}`;
+  const code = [
+    `import mod from ${JSON.stringify(options.from)};`,
+    // 用**计算属性**读：`mod.jsxDEV` 这种静态属性访问会被 rolldown 按它对 CJS 命名空间的静态理解
+    // 摇成 `void 0`（`react/jsx-dev-runtime` 就那么被摇空了，页面报 `jsxDEV is not a function`）。
+    "const __cjs = mod ?? {};",
+    "export default __cjs;",
+    ...named.map((key) => `export const ${key} = __cjs[${JSON.stringify(key)}];`),
+    "",
+  ].join("\n");
   options.log?.(
     `[bundle-cjs] ${options.name}/${options.exportName}: 补 ${String(named.length)} 个具名导出\n`,
   );
-  return file;
+  return { id, code };
 }
 
 /**
- * CSS 入口的包装：**样式文件不能直接当入口**——vite 的库模式固定 `cssCodeSplit: false`，遇到
- * `rolldownOptions.input` 里有 `.css` 直接报错。包一层 side-effect import，让样式插件按它一贯的方式
- * 把它编成"注入 `<style>`"的模块。
+ * CSS 出口的产物：**就是 CSS 文本**（不包装成 JS、不注入 `<style>`）。
+ *
+ * JS 里的 `import "x.css"` 是另一条路（`cssInlinePlugins` 在构建期内联成注入样式的模块），与本函数无关。
+ * 这里的 `url()` 指向包内资产：读到字节、按内容 hash 落到 `assets/`、改写成联邦地址——否则浏览器会按
+ * CSS 的相对路径去请求 `.pnpm` 里的文件，路由按清单服务就是 404。
  *
- * @returns 包装文件路径；入口不是 CSS 时 undefined。
+ * `lightningcss` 的 visitor 是同步回调，所以分两遍：第一遍只收集相对 `url()`，异步读资产/算 hash；
+ * 第二遍按映射改写（全程异步 IO）。
+ *
+ * @param options - 入口文件、出口名、缓存目录、包键、产物清单。
  */
-async function cssShimOf(options: {
-  exportName: string;
+async function bundleStyleOf(options: {
   entry: string;
+  exportName: string;
   outDir: string;
-}): Promise<string | undefined> {
-  if (!options.entry.endsWith(".css")) return undefined;
-  const file = join(options.outDir, `${options.exportName.replaceAll("/", "+")}.css-shim.mjs`);
+  key: string;
+  files: Record<string, string>;
+}): Promise<void> {
+  const { transform } = await import("lightningcss");
+  const source = await readFile(options.entry);
+  const relativeUrl = (ref: string): boolean =>
+    ref !== "" &&
+    !ref.startsWith("#") &&
+    !ref.startsWith("/") &&
+    !/^[a-z][a-z0-9+.-]*:/iu.test(ref);
+
+  const refs = new Set<string>();
+  transform({
+    filename: options.entry,
+    code: source,
+    minify: false,
+    visitor: {
+      Url(node) {
+        if (relativeUrl(node.url)) refs.add(node.url);
+      },
+    },
+  });
+
+  const mapping = new Map<string, string>();
+  for (const ref of refs) {
+    const absolute = join(dirname(options.entry), ref);
+    const bytes = await readFile(absolute).catch(() => undefined);
+    if (bytes === undefined) continue;
+    const extension = extname(absolute);
+    const name = `assets/${basename(absolute, extension)}-${createHash("sha256")
+      .update(bytes)
+      .digest("hex")
+      .slice(0, 8)}${extension}`;
+    mapping.set(ref, `${CLIENT_MODULES_PREFIX}/${options.key}/${name}`);
+    await mkdir(dirname(join(options.outDir, name)), { recursive: true });
+    await writeFile(join(options.outDir, name), bytes);
+    options.files[name] = `${options.key}/${name}`;
+  }
+
+  const result = transform({
+    filename: options.entry,
+    code: source,
+    minify: false,
+    visitor: {
+      Url(node) {
+        const rewritten = mapping.get(node.url);
+        return rewritten === undefined ? undefined : { ...node, url: rewritten };
+      },
+    },
+  });
+  const file = join(options.outDir, options.exportName);
   await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, `import ${JSON.stringify(options.entry)};\n`, "utf8");
-  return file;
+  await writeFile(file, result.code);
+  options.files[options.exportName] = `${options.key}/${options.exportName}`;
 }
 
 /**
@@ -507,7 +693,13 @@ async function bundlePackageOnce(
   const outDir = join(options.cacheRoot, key);
   const manifestPath = join(outDir, ".files.json");
   options.log?.(`[bundle-rev] ${options.name}: hash-start watch=${options.watch.join(",")}\n`);
-  const rev = `${BUNDLER_REV}:${await fingerprint(options.watch)}`;
+  // **包根路径**也进指纹（与出口无关，同一包的各个出口共享）：入口是包根下的相对位置，包跟着 app
+  // 换目录后路径变了，只算内容就会复用上一套产物——CJS shim 里的相对路径指向的入口已经不在了。
+  const rootRev = createHash("sha1")
+    .update(dirname(options.watch[0] ?? options.manifestOf ?? ""))
+    .digest("hex")
+    .slice(0, 8);
+  const rev = `${BUNDLER_REV}:${rootRev}:${await fingerprint(options.watch)}`;
   options.log?.(`[bundle-rev] ${options.name}: hash=${rev}\n`);
   const cached = JSON.parse(await readFile(manifestPath, "utf8").catch(() => "{}")) as {
     rev?: string;
@@ -537,7 +729,24 @@ async function bundlePackageOnce(
         return undefined;
       },
     },
-    browserProcessPlugin(),
+    browserProcessPlugin(await clientBuildMeta(options.repoRoot)),
+    // 裸说明符的样式引用（`katex/dist/katex.min.css`）先解析成真实文件：否则外置插件会把它当
+    // 包边界、改写成联邦 URL，浏览器按 ESM import 一个 `text/css` 响应直接报 MIME 错误。
+    // 解析成文件后由 `cssInlinePlugins` 在**引用方**产物里内联（JS 里的 CSS import 行为不变）。
+    {
+      name: "dsh-css-specifiers",
+      resolveId(source: string, importer: string | undefined): string | undefined {
+        if (!source.endsWith(".css") || source.startsWith(".") || source.startsWith("/")) {
+          return undefined;
+        }
+        try {
+          return createRequire(importer ?? join(options.repoRoot, "package.json")).resolve(source);
+        } catch {
+          return undefined;
+        }
+      },
+    },
+
     cssInlinePlugins({
       name: key,
       assets: "threshold",
@@ -562,34 +771,72 @@ async function bundlePackageOnce(
     esmExternalRequirePlugin({
       // **外置名单 = 这条链认识的那些包**（包名 → 版本表的键），node 内置除外（它们走替身）。
       // 不是包的（相对路径、内置、虚拟模块）留在产物里内联。
+      // 入口就是本包：它不能被外置成自己的 URL（否则入口解析会拿到 external，构建直接失败）。
       external: [...resolvable.keys()]
-        .filter((name) => !NODE_BUILTIN.test(name))
+        .filter((name) => !NODE_BUILTIN.test(name) && name !== options.name)
         .map((name) => barePackageRegExp(name)),
     }),
   ];
   const startedAt = Date.now();
   options.log?.(`[bundle-build] ${options.name}: rolldown start\n`);
-  // 入口补偿：CJS 要带具名导出的包装；CSS 不能直接当入口（vite 的库模式 `cssCodeSplit: false`，
-  // 明确拒绝 `rolldownOptions.input` 里出现 CSS 文件），包一层 side-effect import 让样式插件处理它。
+  // 入口：调用方已经按清单解析好（`exports` 条件 / `module` / `main`），这里按模块类型决定直通 / CJS 包装 /
+  // CSS 产物。CSS 用虚拟空模块占位（rolldown 的入口管线只吃 JS 文件名），产物在构建后由 `bundleStyleOf` 写。
   const input: Record<string, string> = {};
+  const entryShims = new Map<string, string>();
+  const styleEntries = new Map<string, string>();
   for (const [exportName, entry] of Object.entries(options.input)) {
-    input[exportName] =
-      (await cjsShimOf({
+    const kind = await moduleKindOf(entry);
+    if (kind === "cjs") {
+      const shim = await cjsShimOf({
         name: options.name,
         exportName,
         entry,
+        from: entry,
         ...(options.log === undefined ? {} : { log: options.log }),
-        outDir,
-      })) ??
-      (await cssShimOf({ exportName, entry, outDir })) ??
-      entry;
+      });
+      if (shim !== undefined) entryShims.set(shim.id, shim.code);
+      input[exportName] = shim?.id ?? entry;
+      continue;
+    }
+    if (kind === "style") {
+      styleEntries.set(exportName, entry);
+      const styleId = `\0dsh-style:${options.name}:${exportName}:entry`;
+      entryShims.set(styleId, "export {};\n");
+      input[exportName] = styleId;
+      continue;
+    }
+    input[exportName] = entry;
+  }
+  if (entryShims.size !== 0) {
+    plugins.push({
+      name: "dsh-entry-shims",
+      resolveId(source: string): string | undefined {
+        return entryShims.has(source) ? source : undefined;
+      },
+      load(source: string): string | undefined {
+        return entryShims.get(source);
+      },
+    });
   }
+
   // **直接跑 rolldown**（不经过 `vite build`）：插件本来就是 rolldown 的接口，而 vite 在这条路上只提供了
   // lib 模式的入口/输出命名与 `worker.format`——那几项自己写更直接，且 `build.rolldownOptions` 里的
   // `transform` / `resolve` 也不会再被 vite 吞掉（对照表见债文档，那份债随这次改动一起销）。
   const bundle = await rolldown({
     input,
     plugins,
+    // 装饰器口径在两处声明（tsconfig 的 `experimentalDecorators` 与 `transform.decorator`）时，rolldown 会提
+    // 一条 `CONFIGURATION_FIELD_CONFLICT` 让人确认——那是"重复声明"级提示，两者语义等价，我们主动取
+    // transform 这一侧（见上面的 decorator 注释）。过滤掉这一条，别的日志照旧走默认处理。
+    onLog: (level, log, handler) => {
+      if (
+        log.code === "CONFIGURATION_FIELD_CONFLICT" &&
+        log.message?.includes("experimentalDecorators") === true
+      ) {
+        return;
+      }
+      handler(level, log);
+    },
     // **不指 tsconfig**：装饰器由下面的 `transform.decorator.legacy` 直接开（直出时它生效，见对照表）。
     // rolldown 自己会解析 tsconfig（含 `extends`，实测过），所以两种形态各指一处不如一处都不指。
     ...(options.tsconfig === undefined ? {} : { resolve: { tsconfigFilename: options.tsconfig } }),
@@ -598,12 +845,16 @@ async function bundlePackageOnce(
       // 直出后没有 `build.target: "baseline-widely-available"` 那层展开，这里自己写全。不要图省事写
       // `esnext` 或留空——目标一低，oxc 就给类字段、可选链这些逐个加降级 helper，产物里全是奇怪的垫片。
       target: ["chrome111", "edge111", "firefox114", "safari16.4"],
-      // 装饰器：legacy（cordis 与上游用的就是这套）。有 tsconfig 时它会被那份覆盖，这里是默认。
+      // 装饰器：legacy（cordis 与上游用的就是这套）。**必须显式给**：闭包面（`node_modules`）里的包不在
+      // tsconfig 的 include 面里（tsc 默认排除 `node_modules`，oxc 同样不应用那份设置），只靠根 tsconfig 的
+      // `experimentalDecorators` 的话，上游的 `@Remote` 会原样留在产物里、浏览器整条入口不执行。
+      // 它与 tsconfig 那项**语义相同**，两处都声明时 rolldown 会提示"tsconfig 被 transform 覆盖"——这条提示
+      // 对我们没有决策价值（见下面的 `onLog`），不是需要处理的冲突。
       decorator: { legacy: true },
-      // 浏览器没有 `process`：精确替换 `process.env`，裸 `process` 再给一个空壳——`immer` 这类包会在
-      // 模块顶层读它，漏掉就是一个 `process is not defined` 把整份产物带下去。
+      // 浏览器没有 `process`：裸 `process` 给一个空壳——`immer` 这类包会在模块顶层读它，漏掉就是一个
+      // `process is not defined` 把整份产物带下去。`process.env` 的替换在 `browserProcessPlugin` 里做
+      // （版本元数据要先于"整个 process.env 变空壳"那一步换成真值，顺序写在一处而不是两处）。
       define: {
-        "process.env": "{ env: {} }",
         process: "{ env: {} }",
       },
     },
@@ -642,8 +893,11 @@ async function bundlePackageOnce(
   // 目录会把另一个进程刚写的产物一起带走，表现为偶发 404。产物名本身带语义（出口名 / 资产 hash），直接
   // 覆盖即可；旧的字节留在盘上不碍事。
   await mkdir(outDir, { recursive: true });
+  const styleExports = new Set(styleEntries.keys());
   for (const item of items) {
     if (item.type !== "chunk") continue;
+    // CSS 出口的 JS 占位不落盘：它只是让 rolldown 完成入口解析。
+    if (item.isEntry && styleExports.has(item.name)) continue;
     // 出口名可以含 `/`（子路径出口：`helpers/decorate`），落盘要先把父目录建出来。
     await mkdir(dirname(join(outDir, item.fileName)), { recursive: true });
     await writeFile(join(outDir, item.fileName), item.code, "utf8");
@@ -660,6 +914,9 @@ async function bundlePackageOnce(
     await writeFile(join(outDir, asset.fileName), asset.source ?? "");
     files[asset.fileName] = `${key}/${asset.fileName}`;
   }
+  for (const [exportName, entry] of styleEntries) {
+    await bundleStyleOf({ entry, exportName, outDir, key, files });
+  }
   await writeFile(manifestPath, `${JSON.stringify({ rev, files }, null, 2)}\n`, "utf8");
   // 指纹进地址用的表（{@link revs}）：**每次构建后更新**——同一会话里后构建的产物引用它时就能带上
   // 当前指纹（浏览器于是可以长缓存那一份）。

package/src/client-meta.ts

@@ -0,0 +1,128 @@
+/**
+ * 浏览器构建里烘焙的版本元数据。
+ *
+ * 上游的 client 构建（`scripts/client-build-environment.ts`）把一组 `DSH_CLIENT_*` 值当 `define` 注入产物：
+ * - `DSH_CLIENT_VERSION`：设置页「当前版本」那一行；
+ * - `DSH_CLIENT_COMMIT_HASH` + `DSH_CLIENT_GIT_DIRTY`：侧栏显示的 `<commit>` / `<commit>-dirty`；
+ * - `DSH_CLIENT_BUILD_PROFILE`：`official` / `local`（官方品牌只在 official 下出现）。
+ *
+ * 这条链以前把 `process.env` 整个替换成 `{ env: {} }`，于是这些值全是 `undefined`：版本行不显示、
+ * `ui-settings-account` 还会因为 `DSH_CLIENT_VERSION` 缺失直接抛错。取值顺序（越靠前越权威）：
+ *
+ * 1. 宿主进程的 `DSH_CLIENT_*`（`dshdev` 与桌面壳在起宿主时注入）；
+ * 2. 仓库根的 `.dsh-build/client-build-environment.json`（`just prepare` 里的 `dshdev client-meta` 写）；
+ * 3. 现算：仓库根的 `package.json` 版本 + `git rev-parse` / `git status`（dev 常见，代价是几次 git 调用）。
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+/** 一份构建元数据；缺项表示该值不可得（前端自己会判 `undefined`）。 */
+export interface ClientBuildMeta {
+  readonly version?: string;
+  readonly commit?: string;
+  readonly dirty?: boolean;
+  /** `DSH_CLIENT_BUILD_PROFILE`：`official` / `local`，由上游的构建环境定义，缺了就不注入。 */
+  readonly profile?: string;
+}
+
+/** `prepare` 写、构建读的那份记录（形状与上游 `client-build-environment.json` 一致）。 */
+export const CLIENT_BUILD_RECORD = join(".dsh-build", "client-build-environment.json");
+
+const VERSION = "DSH_CLIENT_VERSION";
+const COMMIT = "DSH_CLIENT_COMMIT_HASH";
+const DIRTY = "DSH_CLIENT_GIT_DIRTY";
+const PROFILE = "DSH_CLIENT_BUILD_PROFILE";
+
+/** 环境里那组 `DSH_CLIENT_*` → 元数据。 */
+function metaOfEnvironment(environment: NodeJS.ProcessEnv): ClientBuildMeta {
+  const version = environment[VERSION];
+  const commit = environment[COMMIT];
+  const dirty = environment[DIRTY];
+  const profile = environment[PROFILE];
+  return {
+    ...(version === undefined || version === "" ? {} : { version }),
+    ...(commit === undefined || commit === "" ? {} : { commit }),
+    ...(dirty === "true" ? { dirty: true } : {}),
+    ...(profile === undefined || profile === "" ? {} : { profile }),
+  };
+}
+
+const runFile = promisify(execFile);
+
+/** `git` 的输出；不在 git 工作树里、或 git 不可用时 undefined。 */
+async function gitOutput(root: string, args: readonly string[]): Promise<string | undefined> {
+  try {
+    const { stdout } = await runFile("git", args, { cwd: root, encoding: "utf8" });
+    return stdout.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 现算：**装的是哪一版 harness**（`DEEPSEEK_HARNESS_VERSION`，与同步链同一个真源）+ 本仓库的 git 元数据。
+ *
+ * 正常路径拿不到这里：`dshdev` 会注入环境、`prepare` 会写记录。只有"绕过 dshdev 直接构建 client 产物"
+ * 时才走到，所以版本只能取环境或仓库根的 `package.json`（后者不是权威值，缺 env 时用它兜底）。
+ */
+async function computeMeta(repoRoot: string): Promise<ClientBuildMeta> {
+  const explicit = process.env["DEEPSEEK_HARNESS_VERSION"];
+  let version: string | undefined = explicit === undefined || explicit === "" ? undefined : explicit;
+  if (version === undefined) {
+    const manifest = await readFile(join(repoRoot, "package.json"), "utf8").catch(() => undefined);
+    if (manifest !== undefined) {
+      const parsed = JSON.parse(manifest) as { version?: unknown };
+      if (typeof parsed.version === "string" && parsed.version !== "") version = parsed.version;
+    }
+  }
+  const commit = await gitOutput(repoRoot, ["rev-parse", "--short=7", "HEAD"]);
+  const status = await gitOutput(repoRoot, ["status", "--porcelain", "--untracked-files=normal"]);
+  return {
+    ...(version === undefined ? {} : { version }),
+    ...(commit === undefined ? {} : { commit }),
+    ...(status === undefined || status === "" ? {} : { dirty: true }),
+  };
+}
+
+/** 读 `prepare` 写下的那份记录（缺失 / 坏掉都给 undefined，不挡构建）。 */
+async function recordedMeta(repoRoot: string): Promise<ClientBuildMeta | undefined> {
+  const raw = await readFile(join(repoRoot, CLIENT_BUILD_RECORD), "utf8").catch(() => undefined);
+  if (raw === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as { environment?: Record<string, string> };
+    const environment = parsed.environment ?? {};
+    return metaOfEnvironment(environment as NodeJS.ProcessEnv);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 这个仓库在浏览器产物里该带的版本元数据。
+ * @param repoRoot - 仓库根（dev 是工作区，打包形态是 profile：那里通常读不到记录，靠宿主注入的环境）。
+ */
+export async function clientBuildMeta(repoRoot: string): Promise<ClientBuildMeta> {
+  const inherited = metaOfEnvironment(process.env);
+  if (inherited.version !== undefined && inherited.commit !== undefined) return inherited;
+  const recorded = await recordedMeta(repoRoot);
+  const computed = recorded ?? (await computeMeta(repoRoot));
+  return { ...computed, ...inherited };
+}
+
+/**
+ * `define` 用的一组键：`process.env.DSH_CLIENT_*` → 字面量。
+ *
+ * `browserProcessPlugin` 会跳过这些键（见那里的负向前瞻），所以 define 这一层能把它们换成真实值；
+ * 其余 `process.env` 仍是空壳对象。
+ */
+export function clientMetaDefines(meta: ClientBuildMeta): Record<string, string> {
+  return {
+    [`process.env.${VERSION}`]: meta.version === undefined ? "undefined" : JSON.stringify(meta.version),
+    [`process.env.${COMMIT}`]: meta.commit === undefined ? "undefined" : JSON.stringify(meta.commit),
+    [`process.env.${DIRTY}`]: meta.dirty === true ? JSON.stringify("true") : "undefined",
+    // 官方品牌（`ui-brand-official`）按这个值判断：值也来自上游的构建环境，缺了就不注入。
+    [`process.env.${PROFILE}`]: meta.profile === undefined ? "undefined" : JSON.stringify(meta.profile),
+  };
+}