@morlay/dsh-client-ui-primitives 0.0.3 → 0.0.5

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { o as parseReferenceToken, t as findReferences } from "./reference-Dxy9uQYz.mjs";
+import { o as parseReferenceToken, t as findReferences } from "./reference-Cjcn21uW.mjs";
 //#region src/index.ts
 function apply() {}
 //#endregion

package/dist/{reference-Dxy9uQYz.mjs → reference-Cjcn21uW.mjs}

@@ -368,7 +368,6 @@ function parseBareReference(raw) {
 		...column === void 0 ? {} : { column: Number(column) }
 	};
 }
-/** 引号 mention 的起手字符：`@"path with spaces"`。 */
 const QUOTED_PATH = "\"";
 function parseQuotedReference(body) {
 	const end = body.indexOf(QUOTED_PATH, 1);

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "UI Primitives",
-    "description": "css-in-js styling layer plus the shared reference parser and renderer for the forked conversation UI. It also carries the schema-driven row config pages (field-slot injection)."
+    "description": "css-in-js styling layer, the shared reference parser and renderer for the forked conversation UI, and the settings-form primitives forked from upstream. It also carries the schema-driven row config pages (field-slot injection)."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "UI 基础层",
-    "description": "css-in-js 样式层，以及被 fork 的对话 UI 共用的引用解析与渲染转换。 另含按行 schema 自动生成的行配置页（字段槽注入）。"
+    "description": "css-in-js 样式层、被 fork 的对话 UI 共用的引用解析与渲染转换，以及从上游 fork 过来的设置表单原语。另含按行 schema 自动生成的行配置页（字段槽注入）。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morlay/dsh-client-ui-primitives",
-  "version": "0.0.3",
-  "description": "css-in-js styling kit (styled / Token / Styling) plus the shared reference parser and renderer (findReferences / parseReferenceToken) for the forked conversation UI: consumes the official --dsw-* design tokens, so no CSS Modules precompile step is needed.",
+  "version": "0.0.5",
+  "description": "css-in-js styling kit (styled / Token / Styling), the shared reference parser and renderer (findReferences / parseReferenceToken) for the forked conversation UI, and the settings-form primitives forked from upstream (SettingsFormModel / field controls / form shell): consumes the official --dsw-* design tokens, so no CSS Modules precompile step is needed.",
   "keywords": [
     "client",
     "css-in-js",
@@ -40,15 +40,15 @@
     "micromark-util-types": "^2.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-api-remotes": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1",
     "@deepseek-ai/schemastery": "3.18.4",
     "@testing-library/react": "^16.3.0",
     "@types/mdast": "^4.0.4",
@@ -59,13 +59,13 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2"
+    "@deepseek-ai/dsh-api-remotes": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.1"
   },
   "dsh": {
     "client": {

package/src/client/index.ts

@@ -44,15 +44,13 @@ export type { Reference, ReferenceSpan } from "../reference.ts";
 export { ReferenceMarkdown, referenceMentions } from "../reference-markdown.tsx";
 export type { ReferenceActions, ReferenceMarkdownProps } from "../reference-markdown.tsx";
 
-/**
- * 需要的**服务名**：样式与引用那半不要服务，schema 表单那半要槽位、字典与配置表单。
- *
- * 与包清单里的 `dsh.client.inject` 不是一回事：那份是**装配行 id**（谁先到），交给模块系统排 arrival 顺序；
- * 这里读的是 cordis 服务名（谁已 provide），Loader 拿它决定这一行何时才算 active。写错成包名，这一行就永远
- * pending（`web boot: ... waiting for services`）。
- *
- * 值直接取自 schema 表单那一面，不另抄一份清单。
- */
+// 需要的**服务名**：样式与引用那半不要服务，schema 表单那半要槽位、字典与配置表单。
+//
+// 与包清单里的 `dsh.client.inject` 不是一回事：那份是**装配行 id**（谁先到），交给模块系统排 arrival 顺序；
+// 这里读的是 cordis 服务名（谁已 provide），Loader 拿它决定这一行何时才算 active。写错成包名，这一行就永远
+// pending（`web boot: ... waiting for services`）。
+//
+// 值直接取自 schema 表单那一面，不另抄一份清单。
 export const inject: readonly string[] = [...schemaForm.inject];
 
 export function apply(ctx: Context): void {

package/src/client/schema-form/Editor.tsx

@@ -1,12 +1,10 @@
-/**
- * 行式编辑器：按 `editorLines` 排出的行画 JSON 结构视图——行号、折进、`key: value`、结构行、注释行、容器闭合行
- * 后面的添加入口；值在行内点开编辑（Enter 提交 / Esc 撤销）。
- *
- * 缩进只作用在**行内容**上（行号列固定），添加输入与闭合括号同一行；行内控件用官方的 `Input` / `Menu` / `Button`，
- * 与设置页其余部分同一套视觉与键盘行为。
- *
- * 字段槽仍然生效：命中时该字段**值**的位置换成注册方的组件，键名、注释、行号与行为按钮仍由这里画。
- */
+// 行式编辑器：按 `editorLines` 排出的行画 JSON 结构视图——行号、折进、`key: value`、结构行、注释行、容器闭合行
+// 后面的添加入口；值在行内点开编辑（Enter 提交 / Esc 撤销）。
+//
+// 缩进只作用在**行内容**上（行号列固定），添加输入与闭合括号同一行；行内控件用官方的 `Input` / `Menu` / `Button`，
+// 与设置页其余部分同一套视觉与键盘行为。
+//
+// 字段槽仍然生效：命中时该字段**值**的位置换成注册方的组件，键名、注释、行号与行为按钮仍由这里画。
 
 import { useMemo, useState, type ReactNode } from "react";
 import {
@@ -53,31 +51,22 @@ import {
   ValueTrigger,
 } from "./styles.ts";
 
-/** 编辑器要的一切。 */
+// 编辑器要的一切。
 export interface EditorProps {
-  /** settings 命名空间（行 id）。 */
+  // settings 命名空间（行 id）。
   ns: string;
-  /** 页面读数。 */
+  // 页面读数。
   state: SchemaFormState;
-  /** 动作面（写草稿、保存、丢弃）。 */
+  // 动作面（写草稿、保存、丢弃）。
   face: SchemaFormFace;
-  /** 本包字典。 */
+  // 本包字典。
   t: SchemaFormTranslate;
-  /** `description` 的本地化。 */
+  // `description` 的本地化。
   resolveText: ResolveText;
-  /**
-   * 一个字段的值位置怎么画（字段槽入口：命中用注册方的组件，否则用本包的行内值）。
-   * @param owner - 字段上下文与动作。
-   * @returns 行内值的节点。
-   */
+  // 一个字段的值位置怎么画（字段槽入口：命中用注册方的组件，否则用本包的行内值）。
   renderField: (owner: SchemaFieldOwnerProps) => ReactNode;
 }
 
-/**
- * 画一行的配置。
- * @param props - 读数、动作、字典与字段槽入口。
- * @returns 行式编辑器。
- */
 export function Editor(props: EditorProps): ReactNode {
   const { ns, state, face, t, resolveText, renderField } = props;
   const [toggled, setToggled] = useState<ReadonlySet<string>>(() => new Set());
@@ -135,7 +124,7 @@ export function Editor(props: EditorProps): ReactNode {
   );
 }
 
-/** 折叠状态：记「用户切换过的路径」，开合 = 切换过就反转 schema 的默认值。 */
+// 折叠状态：记「用户切换过的路径」，开合 = 切换过就反转 schema 的默认值。
 function useFold(
   state: SchemaFormState,
   toggled: ReadonlySet<string>,
@@ -169,7 +158,7 @@ function useFold(
   );
 }
 
-/** 一行的渲染分派。 */
+// 一行的渲染分派。
 function Row({
   line,
   n,
@@ -308,7 +297,7 @@ function Row({
   );
 }
 
-/** 字段行：`key: value`（数组成员的键名是下标，淡一些）。 */
+// 字段行：`key: value`（数组成员的键名是下标，淡一些）。
 function FieldLine({
   line,
   ns,
@@ -526,12 +515,12 @@ function FieldLine({
   );
 }
 
-/** 复制用的文本（字符串带引号，粘到哪里都是合法片段）。 */
+// 复制用的文本（字符串带引号，粘到哪里都是合法片段）。
 function tokenFor(value: unknown): string {
   return typeof value === "string" ? JSON.stringify(value) : JSON.stringify(value ?? null);
 }
 
-/** 变体切换：判别式 union 挂在标签行上，按形状选的挂在字段行上。触发元素就是当前那一支。 */
+// 变体切换：判别式 union 挂在标签行上，按形状选的挂在字段行上。触发元素就是当前那一支。
 function VariantSelect({
   control,
   path,
@@ -586,7 +575,7 @@ function VariantSelect({
   );
 }
 
-/** 开启行的前缀：字段键名（对象里的一层）或数组成员的下标；成员行另外带移除。 */
+// 开启行的前缀：字段键名（对象里的一层）或数组成员的下标；成员行另外带移除。
 function LinePrefix({
   line,
   face,
@@ -619,7 +608,7 @@ function LinePrefix({
   );
 }
 
-/** 成员行的移除（悬停时出现）：数组项按索引、字典键按键名。 */
+// 成员行的移除（悬停时出现）：数组项按索引、字典键按键名。
 function RemoveLineButton({
   member,
   face,
@@ -647,12 +636,10 @@ function RemoveLineButton({
   );
 }
 
-/**
- * 容器闭合行后面的添加入口。
- *
- * 数组是「追加一个空项」；对象/字典给出**候选**——对象列的是 schema 声明了、值里还没有的字段（带说明），
- * 字典列的是业务注册的候选键（还能自己敲键名）。粘一整段 `{…}` / `[…]` 则整层覆盖。
- */
+// 容器闭合行后面的添加入口。
+//
+// 数组是「追加一个空项」；对象/字典给出**候选**——对象列的是 schema 声明了、值里还没有的字段（带说明），
+// 字典列的是业务注册的候选键（还能自己敲键名）。粘一整段 `{…}` / `[…]` 则整层覆盖。
 function AddLine({
   line,
   state,

package/src/client/schema-form/SchemaForm.tsx

@@ -1,9 +1,7 @@
-/**
- * 一行的配置页：官方表单壳（保存 / 丢弃 / 只读 / 不可用）+ 行式 JSON 结构编辑器 + 字段槽。
- *
- * 每个可渲染的行注册项经 `renderFactorySlot('settings.schema-form.form', …)` 渲染这个 Factory，字段槽因此只需在
- * Factory 的 `children` 里声明一次（slots 的 children 声明 per key 唯一，而本包给每个行都注册了一项）。
- */
+// 一行的配置页：官方表单壳（保存 / 丢弃 / 只读 / 不可用）+ 行式 JSON 结构编辑器 + 字段槽。
+//
+// 每个可渲染的行注册项经 `renderFactorySlot('settings.schema-form.form', …)` 渲染这个 Factory，字段槽因此只需在
+// Factory 的 `children` 里声明一次（slots 的 children 声明 per key 唯一，而本包给每个行都注册了一项）。
 
 import { useSyncExternalStore, type ReactNode } from "react";
 import { SettingsForm, type SettingsFormLabels } from "@deepseek-ai/dsh-client-ui-primitives";
@@ -13,11 +11,7 @@ import type { SchemaFieldOwnerProps, SchemaFormComponentProps } from "./slot-con
 import { Hint } from "./styles.ts";
 import { SchemaFieldDefault } from "./value.tsx";
 
-/**
- * 渲染一行的配置页。
- * @param props - 行 id、控制器面、本地化解析与框架注入的槽位渲染座位。
- * @returns 表单壳里的行式编辑器，或「没有可自动生成的配置项」一行。
- */
+// 渲染一行的配置页。
 export function SchemaForm(props: SchemaFormComponentProps): ReactNode {
   const { ns, face, t, resolveText, renderSlotChain } = props;
   const store = face.hooks.schemaForm;
@@ -66,7 +60,7 @@ export function SchemaForm(props: SchemaFormComponentProps): ReactNode {
   );
 }
 
-/** 文本草稿的解析规则按字段类型给：行内编辑只上报原文，值在保存那一刻成形。 */
+// 文本草稿的解析规则按字段类型给：行内编辑只上报原文，值在保存那一刻成形。
 function withParse(
   owner: SchemaFieldOwnerProps,
   t: SchemaFormComponentProps["t"],

package/src/client/schema-form/controller.ts

@@ -1,9 +1,7 @@
-/**
- * 一行的配置页控制器：把 describe 里的 volatile schema 投影成字段树，绑上该命名空间的共享配置表单与草稿模型。
- *
- * 一个命名空间一个实例（行 id 就是 settings 命名空间）。行被 describe 出来之后 `configured` 才是 true：
- * schema 变了就重新投影字段树（模型不重建，草稿仍在），行消失时页面只显示一行说明。
- */
+// 一行的配置页控制器：把 describe 里的 volatile schema 投影成字段树，绑上该命名空间的共享配置表单与草稿模型。
+//
+// 一个命名空间一个实例（行 id 就是 settings 命名空间）。行被 describe 出来之后 `configured` 才是 true：
+// schema 变了就重新投影字段树（模型不重建，草稿仍在），行消失时页面只显示一行说明。
 
 import type { SettingsNamespaceView } from "@deepseek-ai/dsh-api-remotes/client";
 import { createSnapshotStore, type SnapshotStore } from "@deepseek-ai/dsh-client-store";
@@ -33,7 +31,7 @@ import {
 import type { FieldText, SelectOption, SelectSpec } from "./hints.ts";
 import type { SchemaFormTranslate } from "./slot-contract.ts";
 
-/** `role('select', { source })` 里声明的候选源名字。 */
+// `role('select', { source })` 里声明的候选源名字。
 function declaredSource(node: FieldNode | undefined): string | undefined {
   const extra = node?.meta.extra;
   if (typeof extra !== "object" || extra === null) return undefined;
@@ -41,20 +39,13 @@ function declaredSource(node: FieldNode | undefined): string | undefined {
   return typeof name === "string" && name.length > 0 ? name : undefined;
 }
 
-/** 字段在状态表里的键（具体路径的 JSON）。 */
+// 字段在状态表里的键（具体路径的 JSON）。
 export function fieldKey(path: readonly string[]): string {
   return JSON.stringify(path);
 }
 
-/**
- * rehydrate 一段配置 schema，并判它能不能当页面的根。
- *
- * 能当根的形状有三种：对象段、**相交段**（共享判别字段 + 各分支的 `const` 标记，段值仍是对象）、以及带判别
- * 标签的 `union`（成员都是对象）。字面量 `union`（整段就是一个标量）不行：那一行的写盘会变成整段替换。
- * @param serialized - host 发来的 `schema.toJSON()`。
- * @param rehydrate - host schema 的 rehydrate。
- * @returns schema 与它的字段树，或 `undefined`（不能当页面根）。
- */
+// rehydrate 一段配置 schema，判它能不能当页面根：对象段、相交段，或带判别标签的 union
+// （字面量 union 会让那一行的写盘变成整段替换）。
 export function projectRoot(
   serialized: unknown,
   rehydrate: (serialized: unknown) => SchemaNode,
@@ -72,12 +63,7 @@ export function projectRoot(
   }
 }
 
-/**
- * 一行能否自动生成配置页：它的 schema 能 rehydrate 且根是 {@link projectRoot} 认的形状。
- * @param view - host 发来的命名空间视图。
- * @param rehydrate - host schema 的 rehydrate。
- * @returns 是否可以渲染。
- */
+// 一行能否自动生成配置页：它的 schema 能 rehydrate 且根是 `projectRoot` 认的形状。
 export function canRender(
   view: SettingsNamespaceView | undefined,
   rehydrate: (serialized: unknown) => SchemaNode,
@@ -85,7 +71,7 @@ export function canRender(
   return view !== undefined && projectRoot(view.schema, rehydrate) !== undefined;
 }
 
-/** 段根不是可渲染对象时的空字段树。 */
+// 段根不是可渲染对象时的空字段树。
 const NO_FIELDS: FieldNode = {
   key: "",
   path: [],
@@ -96,77 +82,52 @@ const NO_FIELDS: FieldNode = {
   fields: [],
 };
 
-/** 提示面在控制器里的读法：候选键 + 字段文案 + 候选值。 */
+// 提示面在控制器里的读法：候选键 + 字段文案 + 候选值。
 export interface HintSources extends SuggestedKeys {
-  /**
-   * 读某个字段的文案。
-   * @param path - 该字段的具体路径。
-   * @returns 业务注册的文案；没有就是空对象。
-   */
+  // 读某个字段的文案；没有就是空对象。
   textFor: (path: readonly string[]) => FieldText;
-  /**
-   * 读某个字段的候选值读数；不接提示面的装配可以不给（字段就还是文本编辑）。
-   * @param path - 该字段的具体路径。
-   * @returns 业务注册的候选读数；没有就是 `undefined`。
-   */
+  // 读某个字段的候选值读数；不接提示面的装配可以不给（字段就还是文本编辑）。
   selectFor?: ((path: readonly string[]) => SelectSpec | undefined) | undefined;
-  /**
-   * 读一个**具名候选源**（schema 的 `role('select', { source })` 认领它）。
-   * @param name - 源的名字。
-   * @returns 该源的读数；没注册过就是 `undefined`。
-   */
+  // 读一个具名候选源（schema 的 `role('select', { source })` 认领它）。
   sourceFor?: ((name: string) => SelectSpec | undefined) | undefined;
 }
 
-/** 控制器要的外部面（`apply` 里从 cordis ctx 组装；测试直接给替身）。 */
+// 控制器要的外部面（`apply` 里从 cordis ctx 组装；测试直接给替身）。
 export interface SchemaFormDeps {
-  /** 本命名空间的共享配置表单（读 + 带栅栏的写）。 */
+  // 本命名空间的共享配置表单（读 + 带栅栏的写）。
   form: DraftScope;
-  /** describe mirror 的读面：本行的 schema、autoGenerate 与 secret 槽。 */
+  // describe mirror 的读面：本行的 schema、autoGenerate 与 secret 槽。
   describe: SettingsDescribeFace;
-  /** rehydrate host 发来的 `schema.toJSON()`。 */
+  // rehydrate host 发来的 `schema.toJSON()`。
   rehydrate: (serialized: unknown) => SchemaNode;
-  /** 整段校验；失败时连路径一起给（页面把消息画在那一行）。 */
+  // 整段校验；失败时连路径一起给（页面把消息画在那一行）。
   validate: (schema: SchemaNode, value: unknown) => ValidationFailure | undefined;
-  /** 本包字典（项身份冲突这类本地校验的消息）。 */
+  // 本包字典（项身份冲突这类本地校验的消息）。
   t: SchemaFormTranslate;
-  /**
-   * dict 字段的候选键（业务注册，见 `hints.ts`）：候选里有、值里没有的键会补成一行「未配置」，
-   * 用户填了才算写。
-   */
+  // dict 字段的候选键（业务注册，见 `hints.ts`）：候选里有、值里没有的键会补成一行「未配置」，
+  // 用户填了才算写。
   hints?: HintSources | undefined;
 }
 
-/**
- * 这一层「能加进来」的一项：schema 里声明、值里还没有的字段，或业务注册的候选键。
- *
- * 页面上不占行——它们出现在容器的闭合行那个「添加属性 / 添加键」输入框的候选里，选中才加。
- */
+// 这一层「能加进来」的一项：schema 里声明、值里还没有的字段，或业务注册的候选键。
+//
+// 页面上不占行——它们出现在容器的闭合行那个「添加属性 / 添加键」输入框的候选里，选中才加。
 export interface AddableProperty {
-  /** 加进来的键名。 */
+  // 加进来的键名。
   key: string;
-  /** 说明（schema 的 `description` / `comment`，可能是本地化字典）：渲染层解析后当候选的副标题。 */
+  // 说明（schema 的 `description` / `comment`，可能是本地化字典）：渲染层解析后当候选的副标题。
   description: string | Readonly<Record<string, string>> | undefined;
 }
 
-/** 值里已有的键（数组给索引）。 */
+// 值里已有的键（数组给索引）。
 function keysOf(value: unknown): string[] {
   if (Array.isArray(value)) return value.map((_item, index) => String(index));
   if (typeof value === "object" && value !== null) return Object.keys(value);
   return [];
 }
 
-/**
- * 一个容器当前能加什么。
- *
- * 对象层（含相交与 union 的选中变体）是**非必填**、值里又没有的字段——必填的已经占着行了；字典层是业务注册的
- * 候选键（模式清单这类运行期数据）。数组层不在这里：它的「添加一项」是追加一个空项，没有键名可选。
- * @param node - 容器节点。
- * @param path - 该容器的具体路径。
- * @param value - 该容器自己的值（草稿后的）。
- * @param hints - 提示面（只用到候选键）。
- * @returns 可添加项，顺序即 schema / 读数的顺序；列表为空时页面不给输入框。
- */
+// 一个容器当前能加什么：对象层给非必填且值里没有的字段（必填的已占着行），字典层给业务注册的候选键；
+// 数组层的「添加一项」是追加空项，没有键名可选。
 export function addableAt(
   node: FieldNode,
   path: readonly string[],
@@ -188,78 +149,65 @@ export function addableAt(
   );
 }
 
-/** 页面级状态：表单壳 + 字段树 + 每字段草稿状态。 */
+// 页面级状态：表单壳 + 字段树 + 每字段草稿状态。
 export interface SchemaFormState extends SettingsFormShell {
-  /** 这一行的 schema 是否可渲染（否则页面只显示一行说明）。 */
+  // 这一行的 schema 是否可渲染（否则页面只显示一行说明）。
   configured: boolean;
-  /** 字段树；未 configured 时是空对象树。 */
+  // 字段树；未 configured 时是空对象树。
   root: FieldNode;
-  /** 按草稿后的值展开的字段列表（渲染顺序）：追加的数组项与新增的字典键立刻出现。 */
+  // 按草稿后的值展开的字段列表（渲染顺序）：追加的数组项与新增的字典键立刻出现。
   walked: readonly WalkedField[];
-  /** 每个具体路径的草稿状态，键见 {@link fieldKey}。 */
+  // 每个具体路径的草稿状态，键见 `fieldKey`。
   fields: ReadonlyMap<string, DraftFieldState>;
-  /** secret 槽是否已配置，键见 {@link fieldKey}。 */
+  // secret 槽是否已配置，键见 `fieldKey`。
   secrets: ReadonlyMap<string, boolean>;
-  /** 每个字段的文案（提示面注册的），键见 {@link fieldKey}；渲染层把它画成注释行。 */
+  // 每个字段的文案（提示面注册的），键见 `fieldKey`；渲染层把它画成注释行。
   texts: ReadonlyMap<string, FieldText>;
-  /**
-   * 每个字段的可选项，键见 {@link fieldKey}：字面量集合的 union 自带候选，其余来自提示面。
-   * 候选依赖的兄弟字段一改，这里就跟着变（投影时按草稿后的值求一次）。
-   */
+  // 每个字段的可选项，键见 `fieldKey`：字面量集合的 union 自带候选，其余来自提示面。
+  // 候选依赖的兄弟字段一改，这里就跟着变（投影时按草稿后的值求一次）。
   options: ReadonlyMap<string, readonly SelectOption[]>;
-  /**
-   * 每个容器能加进来的项，键见 {@link fieldKey}（容器自己的路径）。没有条目就是加不了东西——对象层的输入框
-   * 因此只在还有声明字段没配时出现。
-   */
+  // 每个容器能加进来的项，键见 `fieldKey`（容器自己的路径）。没有条目就是加不了东西——对象层的输入框
+  // 因此只在还有声明字段没配时出现。
   addable: ReadonlyMap<string, readonly AddableProperty[]>;
-  /** 保存被 schema 挡下时的消息与它的位置。 */
+  // 保存被 schema 挡下时的消息与它的位置。
   violation: ValidationFailure | undefined;
-  /** 每行的校验消息（键见 {@link fieldKey}）：行内报错，与底部的整段提示同源。 */
+  // 每行的校验消息（键见 `fieldKey`）：行内报错，与底部的整段提示同源。
   invalidAt: ReadonlyMap<string, string>;
 }
 
-/** 控件的写动作：全部落在草稿上，`save` 是唯一的写盘点。 */
+// 控件的写动作：全部落在草稿上，`save` 是唯一的写盘点。
 export interface SchemaFormActions {
-  /** 暂存一个合法值。 */
+  // 暂存一个合法值。
   set: (path: readonly string[], value: unknown) => void;
-  /** 暂存一段文本（保存时解析）。 */
+  // 暂存一段文本（保存时解析）。
   setText: (path: readonly string[], text: string, parse: TextParse) => void;
-  /** 暂存「恢复默认」。 */
+  // 暂存「恢复默认」。
   clear: (path: readonly string[]) => void;
-  /** 追加一个数组项。 */
+  // 追加一个数组项。
   appendItem: (path: readonly string[]) => void;
-  /** 移除一个数组项。 */
+  // 移除一个数组项。
   removeItem: (path: readonly string[], index: number) => void;
-  /** 加一个字典键。 */
+  // 加一个字典键。
   addKey: (path: readonly string[], key: string) => void;
-  /** 删一个字典键。 */
+  // 删一个字典键。
   removeKey: (path: readonly string[], key: string) => void;
-  /** 写盘。 */
+  // 写盘。
   save: () => void;
-  /** 撤销一个字段的草稿（行内编辑取消）。 */
+  // 撤销一个字段的草稿（行内编辑取消）。
   revert: (path: readonly string[]) => void;
-  /** 丢弃草稿。 */
+  // 丢弃草稿。
   discard: () => void;
 }
 
-/** 槽位渲染器绑定的动作与可观察状态。 */
+// 槽位渲染器绑定的动作与可观察状态。
 export interface SchemaFormFace extends SchemaFormActions {
   hooks: {
     schemaForm: SnapshotStore<SchemaFormState>;
   };
 }
 
-/**
- * 一个字段的可选项。
- *
- * 字面量集合的 union（`z.union(["wal", "delete"])`）自己就带着候选；其余看提示面注册的读数——读的时候把依赖的
- * 兄弟字段值喂进去，所以「选完服务商才列它有哪些模型」是投影的一部分，不是额外的一次订阅。
- * @param node - 字段节点。
- * @param path - 该字段的具体路径。
- * @param value - 段值（草稿后的）。
- * @param hints - 提示面。
- * @returns 可选项；没有候选就是 `undefined`。
- */
+// 一个字段的可选项：字面量集合的 union 自带候选，其余看提示面注册的读数（求值时把依赖的兄弟字段值喂进去，
+// 所以「选完服务商才列它有哪些模型」是投影的一部分，不是额外订阅）。
 export function optionsFor(
   node: FieldNode,
   path: readonly string[],
@@ -280,9 +228,7 @@ export function optionsFor(
   return options.length === 0 ? undefined : options;
 }
 
-/**
- * 一行配置页的控制器。
- */
+// 一行配置页的控制器。
 export class SchemaFormController {
   readonly #ns: string;
   readonly #deps: SchemaFormDeps;
@@ -293,10 +239,6 @@ export class SchemaFormController {
   #schema: SchemaNode | undefined;
   #root: FieldNode | undefined;
 
-  /**
-   * @param ns - settings 命名空间（行 id）。
-   * @param deps - 该行的共享表单与 schema 面。
-   */
   constructor(ns: string, deps: SchemaFormDeps) {
     this.#ns = ns;
     this.#deps = deps;
@@ -320,7 +262,7 @@ export class SchemaFormController {
     this.#sync();
   }
 
-  /** 槽位渲染器要的动作与状态。 */
+  // 槽位渲染器要的动作与状态。
   face(): SchemaFormFace {
     return {
       hooks: { schemaForm: this.#store },
@@ -357,23 +299,23 @@ export class SchemaFormController {
     };
   }
 
-  /** 本行的 settings 命名空间。 */
+  // 本行的 settings 命名空间。
   namespace(): string {
     return this.#ns;
   }
 
-  /** 外部提示（候选键这类）变了：重新投影一次，字段树与草稿都不动。 */
+  // 外部提示（候选键这类）变了：重新投影一次，字段树与草稿都不动。
   refresh(): void {
     this.#store.set(this.#project());
   }
 
-  /** 释放订阅。 */
+  // 释放订阅。
   dispose(): void {
     for (const dispose of this.#disposers.splice(0)) dispose();
     this.#model.dispose();
   }
 
-  /** 重新读 schema（describe 变了）：只换字段树，草稿与 store 不动。 */
+  // 重新读 schema（describe 变了）：只换字段树，草稿与 store 不动。
   #sync(): void {
     const view = this.#deps.describe
       .getSnapshot()
@@ -388,7 +330,7 @@ export class SchemaFormController {
     this.#store.set(this.#project());
   }
 
-  /** 整段校验：schema 先说话，再看数组的项身份有没有冲突。 */
+  // 整段校验：schema 先说话，再看数组的项身份有没有冲突。
   #validate(deps: SchemaFormDeps, value: Section): ValidationFailure | undefined {
     if (this.#schema !== undefined) {
       const failure = deps.validate(this.#schema, value);
@@ -406,7 +348,7 @@ export class SchemaFormController {
     };
   }
 
-  /** 渲染层读的一份完整投影。 */
+  // 渲染层读的一份完整投影。
   #project(): SchemaFormState {
     const fields = new Map<string, DraftFieldState>();
     const root = this.#root;