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

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

@@ -1,27 +1,20 @@
-/**
- * 自动注册面：把 describe 出来的命名空间与 bundle 的行清单配对，为每个能渲染的行注册本行的配置入口。
- *
- * 注册用 `<bundle 包名>#<行 id>`（页面按同一个 key 打开这一行的配置页）与兜底 priority：手写卡片用默认
- * priority 0 注册，按 slots 的 cell winner 规则自然遮住这里的自动项，与加载顺序无关。
- */
+// 自动注册面：把 describe 出来的命名空间与 bundle 的行清单配对，为每个能渲染的行注册本行的配置入口。
+//
+// 注册用 `<bundle 包名>#<行 id>`（页面按同一个 key 打开这一行的配置页）与兜底 priority：手写卡片用默认
+// priority 0 注册，按 slots 的 cell winner 规则自然遮住这里的自动项，与加载顺序无关。
 
 import type { BundleInfo, SettingsNamespaceView } from "@deepseek-ai/dsh-api-remotes/client";
 import type { SettingsDescribeFace } from "@deepseek-ai/dsh-client-ui-settings/client";
 
-/** 一个该自动长出配置页的行。 */
+// 一个该自动长出配置页的行。
 export interface RowRegistrationPlan {
-  /** `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`。 */
+  // `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`。
   key: string;
-  /** settings 命名空间（行 id）。 */
+  // settings 命名空间（行 id）。
   ns: string;
 }
 
-/**
- * 配对命名空间与 bundle 行清单。
- * @param namespaces - host 发来的命名空间视图。
- * @param bundles - host 的 bundle 清单（含各 bundle 声明的行 id）。
- * @returns 该自动注册的行，按命名空间视图的顺序。
- */
+// 配对命名空间与 bundle 行清单：只给 `autoGenerate` 且能在清单里找到 owner 的行，顺序即命名空间视图的顺序。
 export function rowRegistrations(
   namespaces: readonly SettingsNamespaceView[],
   bundles: readonly BundleInfo[],
@@ -40,9 +33,9 @@ export function rowRegistrations(
   return plans;
 }
 
-/** 注册器要的外部面。 */
+// 注册器要的外部面。
 export interface RowRegistrationDeps {
-  /** 槽位注册：返回注销函数。 */
+  // 槽位注册：返回注销函数。
   slots: {
     register(
       options: {
@@ -54,48 +47,36 @@ export interface RowRegistrationDeps {
       component: unknown,
     ): () => void;
   };
-  /** describe 读面：命名空间清单与变更通知。 */
+  // describe 读面：命名空间清单与变更通知。
   describe: SettingsDescribeFace;
-  /** 读 bundle 清单。 */
+  // 读 bundle 清单。
   bundles(): Promise<readonly BundleInfo[]>;
-  /** 订阅 bundle 清单变化。 */
+  // 订阅 bundle 清单变化。
   subscribeBundles(listener: () => void): () => void;
-  /**
-   * 一行的注册项组件；`undefined` 表示这一行渲染不了（schema rehydrate 不了或段根不是对象）。
-   * 每次调用返回同一个实例（控制器按命名空间缓存）。
-   */
+  // 一行的注册项组件；`undefined` 表示这一行渲染不了（schema rehydrate 不了或段根不是对象）。
+  // 每次调用返回同一个实例（控制器按命名空间缓存）。
   entryFor(ns: string): { component: unknown } | undefined;
-  /** 槽项文案的命名空间。 */
+  // 槽项文案的命名空间。
   locale: string;
-  /** 一行注销时释放它的控制器。 */
+  // 一行注销时释放它的控制器。
   release(ns: string): void;
 }
 
-/** 自动项的兜底优先级：手写卡片（默认 0）遮住它。 */
+// 自动项的兜底优先级：手写卡片（默认 0）遮住它。
 const FALLBACK_PRIORITY = 100;
 
-/**
- * 自动注册的差分器：按 describe 与 bundle 清单把「该有的行」与「已在的行」对齐。
- */
+// 自动注册的差分器：按 describe 与 bundle 清单把「该有的行」与「已在的行」对齐。
 export class RowRegistration {
   readonly #deps: RowRegistrationDeps;
   readonly #live = new Map<string, () => void>();
   #pending: Promise<void> | undefined;
   #disposed = false;
 
-  /**
-   * @param deps - 槽位、清单读面与每行的槽项工厂。
-   */
   constructor(deps: RowRegistrationDeps) {
     this.#deps = deps;
   }
 
-  /**
-   * 对齐一次：新增该有的行，注销不该有的行。
-   *
-   * 并发调用折叠成一次（bundle 清单只读一趟），后到的调用等同一趟结束。
-   * @returns 对齐完成。
-   */
+  // 对齐一次：新增该有的行，注销不该有的行；并发调用折叠成一次（bundle 清单只读一趟）。
   sync(): Promise<void> {
     if (this.#disposed) return Promise.resolve();
     this.#pending ??= this.#run().finally(() => {
@@ -104,7 +85,7 @@ export class RowRegistration {
     return this.#pending;
   }
 
-  /** 收掉自己：注销还活着的全部注册并释放它们的控制器。 */
+  // 收掉自己：注销还活着的全部注册并释放它们的控制器。
   dispose(): void {
     this.#disposed = true;
     this.#release();
@@ -142,7 +123,7 @@ export class RowRegistration {
     }
   }
 
-  /** 注销全部并释放控制器。 */
+  // 注销全部并释放控制器。
   #release(): void {
     for (const [ns, dispose] of this.#live) {
       dispose();

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

@@ -1,103 +1,91 @@
-/**
- * schema 投影：把 host 发来的 volatile 表单 schema 变成渲染层要的字段树。
- *
- * 投影只描述**结构**（字段、路径、meta、只读原因），不读值、不做本地化、不碰 React：值在 `draft.ts`，
- * 文案在 `labels.ts`，控件在 `fields/`。动态子节点（dict 的键与值、array 的项）的路径段用
- * {@link DYNAMIC_SEGMENT} 占位，渲染层按真实键/索引替换后再交给字段槽。
- */
+// schema 投影：把 host 发来的 volatile 表单 schema 变成渲染层要的字段树。
+//
+// 只描述结构（字段、路径、meta、只读原因），不读值、不做本地化、不碰 React；动态子节点的路径段用
+// `DYNAMIC_SEGMENT` 占位，渲染层按真实键 / 索引替换后再交给字段槽。
 
 import type { SchemaNode } from "@deepseek-ai/dsh-client-ui-settings/client";
 
-/** 动态子节点的路径占位段（dict 的键与值、array 的项）：渲染层按真实键或索引替换。 */
+// 动态子节点的路径占位段（dict 的键与值、array 的项）：渲染层按真实键或索引替换。
 export const DYNAMIC_SEGMENT = "*";
 
-/** 节点不可编辑的原因；`null` 表示可编辑。 */
+// 节点不可编辑的原因；`null` 表示可编辑。
 export type ReadOnlyReason = "transform" | "function" | "constructor";
 
-/** 归一化后的字段元数据（schemastery `meta` 的可用子集）。 */
+// 归一化后的字段元数据（schemastery `meta` 的可用子集）。
 export interface FieldMeta {
-  /** `description`（可能是本地化字典）：渲染时经 locale 解析。 */
+  // `description`（可能是本地化字典）：渲染时经 locale 解析。
   description: string | Readonly<Record<string, string>> | undefined;
-  /** `comment`：纯文本补充说明。 */
+  // `comment`：纯文本补充说明。
   comment: string | undefined;
-  /** `link`：外部文档。 */
+  // `link`：外部文档。
   link: string | undefined;
-  /** `role`：控件提示（`secret` / `slider` / `datetime` …）。 */
+  // `role`：控件提示（`secret` / `slider` / `datetime` …）。
   role: string | undefined;
-  /** `role === 'secret'`：值不回传，只能写。 */
+  // `role === 'secret'`：值不回传，只能写。
   secret: boolean;
-  /** `required()`。 */
+  // `required()`。
   required: boolean;
-  /** `disabled()`：控件禁用。 */
+  // `disabled()`：控件禁用。
   disabled: boolean;
-  /** `collapse()`：嵌套分组默认折叠。 */
+  // `collapse()`：嵌套分组默认折叠。
   collapse: boolean;
-  /** `deprecated()` / `experimental()` 的徽标文本。 */
+  // `deprecated()` / `experimental()` 的徽标文本。
   badges: readonly string[];
-  /** `pattern()` 的正则来源。 */
+  // `pattern()` 的正则来源。
   pattern: string | undefined;
-  /** `min()`。 */
+  // `min()`。
   min: number | undefined;
-  /** `max()`。 */
+  // `max()`。
   max: number | undefined;
-  /** `step()`：`1` 表示整数。 */
+  // `step()`：`1` 表示整数。
   step: number | undefined;
-  /** 是否声明了默认值（与「默认值是 undefined」区分开）。 */
+  // 是否声明了默认值（与「默认值是 undefined」区分开）。
   hasDefault: boolean;
-  /** 声明的默认值。 */
+  // 声明的默认值。
   defaultValue: unknown;
-  /** `extra()`：角色附带的任意数据，字段槽的自定义控件可用。 */
+  // `extra()`：角色附带的任意数据，字段槽的自定义控件可用。
   extra: unknown;
 }
 
-/** 每种节点共有的部分。 */
+// 每种节点共有的部分。
 export interface FieldNodeBase {
-  /** 这一层的名字：对象字段名、tuple 的索引、动态子节点的占位段。 */
+  // 这一层的名字：对象字段名、tuple 的索引、动态子节点的占位段。
   key: string;
-  /** 从段根起的路径；动态段是 {@link DYNAMIC_SEGMENT}。 */
+  // 从段根起的路径；动态段是 `DYNAMIC_SEGMENT`。
   path: readonly string[];
-  /**
-   * 按值展开时算好的显示名：数组成员的**项身份**（见 {@link FieldNodeBase} 所在的 array 节点）。
-   * 投影时没有（`undefined`），渲染层用它优先于字段名。
-   */
+  // 按值展开时算好的显示名（数组成员的项身份）：投影时为 `undefined`，渲染层用它优先于字段名。
   label: string | undefined;
-  /** 归一化后的元数据。 */
+  // 归一化后的元数据。
   meta: FieldMeta;
-  /** 不可编辑的原因；`null` 表示可编辑。 */
+  // 不可编辑的原因；`null` 表示可编辑。
   readOnly: ReadOnlyReason | null;
 }
 
-/** 位集的一位。 */
+// 位集的一位。
 export interface BitsEntry {
   name: string;
   bit: number;
 }
 
-/** 渲染层要的一个字段节点。 */
+// 渲染层要的一个字段节点。
 export type FieldNode =
   | (FieldNodeBase & { type: "object"; fields: readonly FieldNode[] })
   | (FieldNodeBase & { type: "dict"; keyNode: FieldNode; valueNode: FieldNode })
   | (FieldNodeBase & {
       type: "array";
       item: FieldNode;
-      /**
-       * 项的**身份键**：这一项的「名字」取自它自己的哪个字段。显式声明优先
-       * （`z.array(inner).role('items', { mergeKey: 'id' })`），否则 item 上有 `id` 字段就用 `id`。
-       * 它只决定显示名与「同名即冲突」的判据——写盘仍按索引（host 的 path op 就是索引语义）。
-       */
+      // 项的**身份键**：显式声明优先（`z.array(inner).role('items', { mergeKey: 'id' })`），否则 item 上有 `id`
+      // 字段就用 `id`。只决定显示名与「同名即冲突」的判据——写盘仍按索引。
       mergeKey: string | undefined;
     })
   | (FieldNodeBase & { type: "tuple"; items: readonly FieldNode[] })
   | (FieldNodeBase & {
       type: "union";
-      /** 成员全是字面量时的可选项；否则 `undefined`。 */
+      // 成员全是字面量时的可选项；否则 `undefined`。
       choices: readonly unknown[] | undefined;
       variants: readonly FieldNode[];
-      /**
-       * 判别标签：按哪个字段的值挑变体。显式声明优先
-       * （`z.union([...]).role('union', { tag: 'kind' })`），否则取所有对象成员共有的**唯一**常量字段。
-       * schemastery 本身没有 tag 机制（union 按声明顺序逐个试），所以这只是渲染与校验的选支依据。
-       */
+      // 判别标签：按哪个字段的值挑变体。显式声明优先（`z.union([...]).role('union', { tag: 'kind' })`），
+      // 否则取所有对象成员共有的**唯一**常量字段——schemastery 没有 tag 机制，这只是渲染与校验的选支依据。
       tagKey: string | undefined;
     })
   | (FieldNodeBase & { type: "intersect"; members: readonly FieldNode[] })
@@ -105,10 +93,10 @@ export type FieldNode =
   | (FieldNodeBase & { type: "const"; value: unknown })
   | (FieldNodeBase & { type: "lazy"; inner: FieldNode })
   | (FieldNodeBase & { type: "string" | "number" | "boolean" | "any" | "never" | "function" })
-  /** 自引用 schema 回到祖先处：值这一层以下不再描述，由渲染层展开或只读呈现。 */
+  // 自引用 schema 回到祖先处：值这一层以下不再描述，由渲染层展开或只读呈现。
   | (FieldNodeBase & { type: "recursive"; origin: string });
 
-/** 空的元数据：动态子节点（无声明 schema 的 dict 键）与空字段树用它。 */
+// 空的元数据：动态子节点（无声明 schema 的 dict 键）与空字段树用它。
 export function emptyMeta(): FieldMeta {
   return {
     description: undefined,
@@ -130,12 +118,12 @@ export function emptyMeta(): FieldMeta {
   };
 }
 
-/** `badges` 只留文本：配色与文案由字典决定。 */
+// `badges` 只留文本：配色与文案由字典决定。
 function badgesOf(meta: SchemaNode["meta"]): string[] {
   return (meta.badges ?? []).map((badge) => badge.text);
 }
 
-/** 归一化一个节点的 meta。 */
+// 归一化一个节点的 meta。
 function metaOf(schema: SchemaNode): FieldMeta {
   const meta = schema.meta ?? {};
   return {
@@ -159,7 +147,7 @@ function metaOf(schema: SchemaNode): FieldMeta {
   };
 }
 
-/** 外层 meta 与内层 meta 合并：外层的 undefined 不覆盖内层（transform 的 inner 带着自己的角色）。 */
+// 外层 meta 与内层 meta 合并：外层的 undefined 不覆盖内层（transform 的 inner 带着自己的角色）。
 function mergeMeta(inner: FieldMeta, outer: FieldMeta): FieldMeta {
   const merged: Record<string, unknown> = { ...inner };
   for (const [key, value] of Object.entries(outer)) {
@@ -168,17 +156,17 @@ function mergeMeta(inner: FieldMeta, outer: FieldMeta): FieldMeta {
   return merged as unknown as FieldMeta;
 }
 
-/** 节点自己的路径末段：动态段保持占位，根节点为空串。 */
+// 节点自己的路径末段：动态段保持占位，根节点为空串。
 function keyOf(path: readonly string[]): string {
   return path[path.length - 1] ?? "";
 }
 
-/** 一个纯字符串叶子（dict 没有声明键 schema 时用它）。 */
+// 一个纯字符串叶子（dict 没有声明键 schema 时用它）。
 function stringLeaf(path: readonly string[], meta: FieldMeta): FieldNode {
   return { key: keyOf(path), path, label: undefined, meta, readOnly: null, type: "string" };
 }
 
-/** 把 schema 的类型名收口成渲染层认识的那几种。 */
+// 把 schema 的类型名收口成渲染层认识的那几种。
 function leafTypeOf(type: string): "string" | "number" | "boolean" | "any" | "never" | "function" {
   switch (type) {
     case "string":
@@ -196,12 +184,7 @@ function leafTypeOf(type: string): "string" | "number" | "boolean" | "any" | "ne
   }
 }
 
-/**
- * 投影一个 schema 节点。
- * @param schema - rehydrate 之后的 volatile 表单 schema（或它的子节点）。
- * @param path - 该节点相对段根的路径；动态子节点由调用方给占位段。
- * @returns 渲染层要的字段树。
- */
+// 投影一个 schema 节点：`path` 是相对段根的路径，动态子节点由调用方给占位段。
 export function projectNode(schema: SchemaNode, path: readonly string[] = []): FieldNode {
   return project(schema, path, []);
 }
@@ -303,14 +286,14 @@ function project(
   }
 }
 
-/** 展开 `lazy` 包装：投影里 lazy 只是一层，值仍在同一路径上。 */
+// 展开 `lazy` 包装：投影里 lazy 只是一层，值仍在同一路径上。
 export function unwrapLazy(node: FieldNode | undefined): FieldNode | undefined {
   let current = node;
   while (current?.type === "lazy") current = current.inner;
   return current;
 }
 
-/** 某一层可见的字段：object 直接给；union / intersect 把各变体的对象字段并起来。 */
+// 某一层可见的字段：object 直接给；union / intersect 把各变体的对象字段并起来。
 export function fieldsOf(node: FieldNode | undefined): readonly FieldNode[] {
   const current = unwrapLazy(node);
   switch (current?.type) {
@@ -325,12 +308,7 @@ export function fieldsOf(node: FieldNode | undefined): readonly FieldNode[] {
   }
 }
 
-/**
- * 按具体路径找回投影节点（动态段匹配真实键或索引）。
- * @param root - 段根的字段树。
- * @param path - 具体路径。
- * @returns 命中的节点，或 `undefined`。
- */
+// 按具体路径找回投影节点（动态段匹配真实键或索引）。
 export function seekNode(root: FieldNode, path: readonly string[]): FieldNode | undefined {
   let current: FieldNode | undefined = root;
   for (const segment of path) {
@@ -358,14 +336,12 @@ export function seekNode(root: FieldNode, path: readonly string[]): FieldNode |
   return unwrapLazy(current);
 }
 
-/** 按当前值展开出的一个字段：路径与名字已按真实键与索引替换。 */
+// 按当前值展开出的一个字段：路径与名字已按真实键与索引替换。
 export interface WalkedField {
   path: readonly string[];
   node: FieldNode;
-  /**
-   * 这一行是某个动态容器的**成员本身**（dict 的键 / array 的项）时给出它的身份：容器路径、键、以及数组
-   * 项的位置。渲染层用它画成员行（名字 + 移除）；成员的子字段不带这个标记。
-   */
+  // 这一行是某个动态容器的**成员本身**（dict 的键 / array 的项）时给出它的身份：容器路径、键、以及数组
+  // 项的位置。渲染层用它画成员行（名字 + 移除）；成员的子字段不带这个标记。
   member?: {
     parent: readonly string[];
     key: string;
@@ -373,26 +349,16 @@ export interface WalkedField {
   };
 }
 
-/** 候选键的来源（业务注册；见 `hints.ts`）：dict 的「可以加哪些键」。 */
+// 候选键的来源（业务注册；见 `hints.ts`）：dict 的「可以加哪些键」。
 export interface SuggestedKeys {
-  /**
-   * 读某个 dict 字段的候选键。
-   * @param path - 该字段的具体路径。
-   * @returns 候选键；没有就是空数组。
-   */
+  // 读某个 dict 字段的候选键；没有就是空数组。
   keysFor(path: readonly string[]): readonly string[];
 }
 
-/**
- * 按当前值把字段树展开成渲染顺序的扁平列表（前序）：容器在前、子项紧随其后。
- *
- * 出现的**只有值里有的东西，加上必填的**：对象的必填字段始终占行（值是空的也要让用户看见"必须填"），非必填的
- * 按值出现——值里没有就不占行，它在这一层的「添加属性」候选里，选中才加。数组按索引、字典按键展开；字面量
- * union 是叶子控件，对象 union 只展开与当前值匹配的那个变体，intersect 的各成员在同一层展开。
- * @param root - 段根的字段树。
- * @param value - 生效值（或草稿后的值）。
- * @returns 渲染顺序的字段列表。
- */
+// 按当前值把字段树展开成渲染顺序的扁平列表（前序）：容器在前、子项紧随其后。
+//
+// 出现的**只有值里有的东西，加上必填的**：非必填字段值里没有就不占行，它在这一层的「添加属性」候选里。
+// 数组按索引、字典按键展开；字面量 union 是叶子控件，对象 union 只展开与当前值匹配的那个变体。
 export function walkFields(root: FieldNode, value: unknown): WalkedField[] {
   const out: WalkedField[] = [];
   visit(root, root.path, value, out, true, undefined, new Set(), undefined);
@@ -491,7 +457,7 @@ function visit(
   }
 }
 
-/** 数组的项身份：显式声明优先，否则 item 上的 `id` 字段。 */
+// 数组的项身份：显式声明优先，否则 item 上的 `id` 字段。
 function mergeKeyOf(schema: SchemaNode, item: FieldNode): string | undefined {
   const declared = declaredExtra(schema, "mergeKey");
   if (declared !== undefined) return declared;
@@ -501,7 +467,7 @@ function mergeKeyOf(schema: SchemaNode, item: FieldNode): string | undefined {
     : undefined;
 }
 
-/** union 的判别标签：显式声明优先，否则所有对象成员共有的唯一常量字段。 */
+// union 的判别标签：显式声明优先，否则所有对象成员共有的唯一常量字段。
 function tagKeyOf(schema: SchemaNode, variants: readonly FieldNode[]): string | undefined {
   const declared = declaredExtra(schema, "tag");
   if (declared !== undefined) return declared;
@@ -520,7 +486,7 @@ function tagKeyOf(schema: SchemaNode, variants: readonly FieldNode[]): string |
   return candidates.length === 1 ? candidates[0] : undefined;
 }
 
-/** `role(text, { … })` 里声明的字符串约定（项身份 `mergeKey`、判别标签 `tag`）。 */
+// `role(text, { … })` 里声明的字符串约定（项身份 `mergeKey`、判别标签 `tag`）。
 function declaredExtra(schema: SchemaNode, name: string): string | undefined {
   const extra = schema.meta?.extra;
   if (typeof extra !== "object" || extra === null) return undefined;
@@ -528,7 +494,7 @@ function declaredExtra(schema: SchemaNode, name: string): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
-/** 一项的项身份值（渲染与冲突检查共用的读法）。 */
+// 一项的项身份值（渲染与冲突检查共用的读法）。
 function memberLabel(value: unknown, mergeKey: string): string | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   const member: unknown = Reflect.get(value, mergeKey);
@@ -537,27 +503,20 @@ function memberLabel(value: unknown, mergeKey: string): string | undefined {
   return undefined;
 }
 
-/** 项身份的一处冲突。 */
+// 项身份的一处冲突。
 export interface MergeKeyConflict {
-  /** `duplicate`：两个成员同名；`missing`：成员没有名字。 */
+  // `duplicate`：两个成员同名；`missing`：成员没有名字。
   kind: "duplicate" | "missing";
-  /** 冲突成员的具体路径。 */
+  // 冲突成员的具体路径。
   path: readonly string[];
-  /** 判据用的字段名。 */
+  // 判据用的字段名。
   mergeKey: string;
-  /** 那个名字（缺名字时是空串）。 */
+  // 那个名字（缺名字时是空串）。
   value: string;
 }
 
-/**
- * 项身份冲突：同一层里两个成员同名，或某个成员没有名字。
- *
- * 名字是成员的「身份」，写盘仍按索引——所以这只是保存前的本地校验：重名的数组在页面上是非法草稿，
- * 而不是悄悄写到 host 上。
- * @param root - 段根的字段树。
- * @param value - 草稿后的段值。
- * @returns 第一处冲突，或 `undefined`。
- */
+// 项身份冲突：同一层里两个成员同名，或某个成员没有名字。名字是成员的「身份」而写盘仍按索引，
+// 所以这是保存前的本地校验——重名的数组在页面上是非法草稿，不会悄悄写到 host 上。
 export function mergeKeyConflict(root: FieldNode, value: unknown): MergeKeyConflict | undefined {
   return scanConflict(root, root.path, value);
 }
@@ -627,14 +586,14 @@ function scanConflict(
   }
 }
 
-/** 一个容器值里的成员（对象键或数组索引）。 */
+// 一个容器值里的成员（对象键或数组索引）。
 function entriesOf(value: unknown): [string, unknown][] {
   if (Array.isArray(value)) return value.map((item, index) => [String(index), item]);
   if (typeof value === "object" && value !== null) return Object.entries(value);
   return [];
 }
 
-/** 读一个成员的值。 */
+// 读一个成员的值。
 function memberOf(value: unknown, key: string | number): unknown {
   if (Array.isArray(value)) return value[Number(key)];
   if (typeof value === "object" && value !== null)
@@ -642,33 +601,28 @@ function memberOf(value: unknown, key: string | number): unknown {
   return undefined;
 }
 
-/** union 的变体切换：一个选项要写的值。 */
+// union 的变体切换：一个选项要写的值。
 export interface VariantChoice {
-  /** 页面上显示的名字：判别标签的值，或变体的形状。 */
+  // 页面上显示的名字：判别标签的值，或变体的形状。
   label: string;
-  /** 写这个值就等于选中这一支。 */
+  // 写这个值就等于选中这一支。
   value: unknown;
 }
 
-/** 把节点收成 union：渲染层判形状与选支都从这里进。 */
+// 把节点收成 union：渲染层判形状与选支都从这里进。
 export function unionOf(node: FieldNode | undefined): (FieldNode & { type: "union" }) | undefined {
   const current = unwrapLazy(node);
   return current?.type === "union" ? current : undefined;
 }
 
-/**
- * 当前值落在哪一支：与 {@link walkFields} 的展开同一判据（标签值优先，其次值的形状，最后第一支）。
- * @param node - 字段节点（不是 union 就原样返回）。
- * @param value - 这一层的值。
- * @returns 选中变体的节点。
- */
+// 当前值落在哪一支：与 `walkFields` 的展开同一判据（标签值优先，其次值的形状，最后第一支）。
 export function variantOf(node: FieldNode, value: unknown): FieldNode {
   const union = unionOf(node);
   if (union === undefined) return unwrapLazy(node) ?? node;
   return pickVariant(union, value) ?? union;
 }
 
-/** 变体里那个判别标签字段的常量值（不是 `const` 就没有）。 */
+// 变体里那个判别标签字段的常量值（不是 `const` 就没有）。
 function tagValueOf(variant: FieldNode, tagKey: string): { found: boolean; value: unknown } {
   const current = unwrapLazy(variant);
   if (current?.type !== "object" && current?.type !== "intersect") {
@@ -682,7 +636,7 @@ function tagValueOf(variant: FieldNode, tagKey: string): { found: boolean; value
   return { found: false, value: undefined };
 }
 
-/** 一个变体在页面上的名字：能看出"这一支是什么"，而不是内部类型名。 */
+// 一个变体在页面上的名字：能看出"这一支是什么"，而不是内部类型名。
 function variantLabel(variant: FieldNode, tag: { found: boolean; value: unknown }): string {
   if (tag.found) return JSON.stringify(tag.value);
   switch (unwrapLazy(variant)?.type) {
@@ -704,14 +658,8 @@ function variantLabel(variant: FieldNode, tag: { found: boolean; value: unknown
   }
 }
 
-/**
- * 变体切换的选项。
- *
- * 带判别标签的 union 写**标签值**（`session-rdb` 的 `type: sqlite` ↔ `type: postgres`）；没有标签的写目标变体的
- * 空值（`access` 在「一段文本」与「一组文本」之间切）。
- * @param union - 投影出来的 union 节点。
- * @returns 每个变体一项，顺序即声明顺序。
- */
+// 变体切换的选项：带判别标签的 union 写**标签值**（`session-rdb` 的 `type: sqlite` ↔ `type: postgres`），
+// 没有标签的写目标变体的空值（`access` 在「一段文本」与「一组文本」之间切）。
 export function variantChoices(union: FieldNode & { type: "union" }): readonly VariantChoice[] {
   return union.variants.map((variant) => {
     const tag =
@@ -725,7 +673,7 @@ export function variantChoices(union: FieldNode & { type: "union" }): readonly V
   });
 }
 
-/** 按路径读一个值：对象键与数组下标都认（值的读法只有这一处）。 */
+// 按路径读一个值：对象键与数组下标都认（值的读法只有这一处）。
 export function readPath(root: unknown, path: readonly string[]): unknown {
   return path.reduce<unknown>((node, segment) => {
     if (Array.isArray(node)) return node[Number(segment)];
@@ -734,14 +682,8 @@ export function readPath(root: unknown, path: readonly string[]): unknown {
   }, root);
 }
 
-/**
- * 这个"默认值"其实不是值——它不该用来当新加进来的那一项的初值。
- *
- * 两种：`null`（"没有值"的判断位，例如 `defaultModel` 用 `.default(null)` 表达"没配就没有这个键"），以及
- * schemastery 给容器类型自动塞的空壳（`{}`）。两种都该让容器把字段摆出来。
- * @param node - 字段节点。
- * @returns 是不是空壳。
- */
+// 这个"默认值"其实不是值——`null`（"没有值"的判断位）或 schemastery 给容器自动塞的空壳（`{}`），
+// 两种都该让容器把字段摆出来，而不是拿来当新加项的初值。
 function isBlankDefault(node: FieldNode): boolean {
   const value = node.meta.defaultValue;
   if (value === null) return true;
@@ -749,15 +691,10 @@ function isBlankDefault(node: FieldNode): boolean {
   return typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
 }
 
-/**
- * 一个新子节点的初值：声明的默认值优先；对象把字段摆出来（见下）；字典/数组给空的容器；其余标量给 **`null`**。
- *
- * `null` 在这里是"还没有值"的判断位（`null` / `undefined` 都算），页面据此把它画成一个等着输入的位子——
- * 而不是 `""`、`0` 这种看着像已经填过的值。host 侧也认这个语义：非必填字段拿到 `null` 回退到默认值，
- * 必填字段拿到 `null` 就是"必须填"。
- * @param node - 子节点的字段树。
- * @returns 初值。
- */
+// 一个新子节点的初值：声明的默认值优先，对象把字段摆出来，字典 / 数组给空容器，其余标量给 `null`。
+//
+// `null` 在这里是"还没有值"的判断位（`null` / `undefined` 都算），页面据此画成等着输入的位子——而不是 `""`、
+// `0` 这种看着像已填过的值；host 侧也认这个语义（非必填字段拿到 `null` 回退默认值，必填就是"必须填"）。
 export function emptyValueOf(node: FieldNode): unknown {
   if (node.meta.hasDefault && !isBlankDefault(node)) {
     return structuredClone(node.meta.defaultValue);
@@ -785,7 +722,7 @@ export function emptyValueOf(node: FieldNode): unknown {
   }
 }
 
-/** 选中与当前值匹配的 union 变体：对象按判别标签的值判，叶子按值类型判。 */
+// 选中与当前值匹配的 union 变体：对象按判别标签的值判，叶子按值类型判。
 function pickVariant(node: FieldNode & { type: "union" }, value: unknown): FieldNode | undefined {
   if (
     node.tagKey !== undefined &&