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

package/src/client/schema-form/slot-contract.ts

@@ -1,15 +1,12 @@
-/**
- * 槽契约：字段级自定义输入与文案的注入点，以及承载它的 Factory 契约。
- *
- * 字段槽是 **chain**：注册项在 `select` 里按 `node.meta.role` 或 `ns + path` 决定认领哪个字段，命中即渲染自己的
- * 组件（收到 `matched`），未命中落到本包的默认控件。链式槽的注册项还可以只声明 `label`/`hint`（不改控件）——
- * 默认控件仍会渲染，文案以它为准。
- *
- * 字段槽声明在 Factory 上（`children`），而不是每个行注册项上：slots 的 children 声明 per key 只能一次，而本包
- * 会给每个可渲染的行各注册一个 `plugins.row.config` 项——那些项经 `renderFactorySlot` 渲染同一个 Factory，
- * 于是字段槽只需声明一次，所有行共用。
- */
-
+// 槽契约：字段级自定义输入与文案的注入点，以及承载它的 Factory 契约。
+//
+// 字段槽是 **chain**：注册项在 `select` 里按 `node.meta.role` 或 `ns + path` 决定认领哪个字段，命中即渲染自己的
+// 组件（收到 `matched`），未命中落到本包的默认控件。链式槽的注册项还可以只声明 `label`/`hint`（不改控件）——
+// 默认控件仍会渲染，文案以它为准。
+//
+// 字段槽声明在 Factory 上（`children`），而不是每个行注册项上：slots 的 children 声明 per key 只能一次，而本包
+// 会给每个可渲染的行各注册一个 `plugins.row.config` 项——那些项经 `renderFactorySlot` 渲染同一个 Factory，
+// 于是字段槽只需声明一次，所有行共用。
 import type {} from "@deepseek-ai/dsh-client-ui-slots";
 import type {
   FactoryComponentPropsOf,
@@ -23,129 +20,111 @@ import type { ResolveText } from "./labels.ts";
 import type { SchemaFormLocaleKey } from "./locales.ts";
 import type { FieldNode } from "./schema-node.ts";
 
-/** `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`（与页面 `rowConfigKey` 同拼法）。 */
+// `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`（与页面 `rowConfigKey` 同拼法）。
 export type RowConfigKey = string;
 
-/** 字段槽的 owner props：路由输入 + 显示状态 + 受控动作（默认控件要的一切都在这里）。 */
+// 字段槽的 owner props：路由输入 + 显示状态 + 受控动作（默认控件要的一切都在这里）。
 export interface SchemaFieldOwnerProps {
-  /** settings 命名空间（行 id）。 */
+  // settings 命名空间（行 id）。
   ns: string;
-  /** 字段的具体路径（动态段已按真实键或索引替换）。 */
+  // 字段的具体路径（动态段已按真实键或索引替换）。
   path: readonly string[];
-  /** 字段节点（类型、`role`、`extra`、界限、只读原因）。 */
+  // 字段节点（类型、`role`、`extra`、界限、只读原因）。
   node: FieldNode;
-  /** 显示标签：默认是字段名拆词，业务方经槽给时会覆盖。 */
+  // 显示标签：默认是字段名拆词，业务方经槽给时会覆盖。
   label: string;
-  /** 显示说明（`description` 本地化 + `comment`）。 */
+  // 显示说明（`description` 本地化 + `comment`）。
   hint: string | undefined;
-  /** 当前生效值（草稿优先）。 */
+  // 当前生效值（草稿优先）。
   value: unknown;
-  /**
-   * 这个字段的可选项：给了就是选择器（点值不再进文本编辑）。来源是字面量集合的 union，或业务经提示面注册的
-   * 候选——候选依赖的兄弟字段一变，这里就换一批。
-   */
+  // 这个字段的可选项：给了就是选择器（点值不再进文本编辑）。来源是字面量集合的 union，或业务经提示面注册的
+  // 候选——候选依赖的兄弟字段一变，这里就换一批。
   options: readonly SelectOption[] | undefined;
-  /** 文本草稿：文本控件显示它，而不是重新格式化生效值。 */
+  // 文本草稿：文本控件显示它，而不是重新格式化生效值。
   text: string | undefined;
-  /** secret 槽是否已配置（值本身不回传）。 */
+  // secret 槽是否已配置（值本身不回传）。
   secretConfigured: boolean;
-  /** 嵌套深度：默认控件按它缩进。 */
+  // 嵌套深度：默认控件按它缩进。
   depth: number;
-  /** 保存后这一字段是否会留下用户层条目。 */
+  // 保存后这一字段是否会留下用户层条目。
   overridden: boolean;
-  /** 草稿不合法时的消息。 */
+  // 草稿不合法时的消息。
   invalid: string | undefined;
-  /** 只读部署或不可用命名空间时为 true。 */
+  // 只读部署或不可用命名空间时为 true。
   disabled: boolean;
-  /** 本包字典（复刻或包装默认控件时用）。 */
+  // 本包字典（复刻或包装默认控件时用）。
   t: SchemaFormTranslate;
-  /** 容器动作（增删数组项、字典键、丢弃、保存）。 */
+  // 容器动作（增删数组项、字典键、丢弃、保存）。
   actions: SchemaFormActions;
-  /**
-   * 分组节点的折叠交互（object / dict / array / tuple）；叶子节点是 `undefined`。
-   * 默认折叠与否由 schema 的 `collapse()` 决定，用户点一下就是反转。
-   */
+  // 分组节点的折叠交互（object / dict / array / tuple）；叶子节点是 `undefined`。
+  // 默认折叠与否由 schema 的 `collapse()` 决定，用户点一下就是反转。
   group: { collapsed: boolean; toggle: () => void } | undefined;
-  /**
-   * 这一行是动态容器的成员本身（dict 的键 / array 的项）时的身份：容器路径、键、数组项的位置。容器成员把它画进
-   * 标题行（名字 + 移除），叶子成员由渲染层另起一行——所以「哪个字段属于哪个键/哪一项」在页面上一眼可见。
-   */
+  // 这一行是动态容器的成员本身（dict 的键 / array 的项）时的身份：容器路径、键、数组项的位置。容器成员把它画进
+  // 标题行（名字 + 移除），叶子成员由渲染层另起一行——所以「哪个字段属于哪个键/哪一项」在页面上一眼可见。
   member:
     | { parent: readonly string[]; key: string; index: number | undefined; pending?: boolean }
     | undefined;
-  /** 暂存一个合法值。 */
+  // 暂存一个合法值。
   onChange: (value: unknown) => void;
-  /**
-   * 暂存一段文本：按字段类型的默认规则解析；给了 `parse` 就用它（例如 secret 留空＝不写）。
-   * @param text - 用户输入。
-   * @param parse - 覆盖默认解析规则。
-   */
+  // 暂存一段文本：按字段类型的默认规则解析；给了 `parse` 就用它（例如 secret 留空＝不写）。
   onEditText: (text: string, parse?: TextParse) => void;
-  /** 暂存「恢复默认」。 */
+  // 暂存「恢复默认」。
   onReset: () => void;
 }
 
-/**
- * 字段槽注册项的完整 props：框架注入的 owner props（{@link SchemaFieldOwnerProps}）＋它的 `select` 结果。
- *
- * 注册方的组件按这个类型声明参数（**不要**自己重写 owner props 的类型：注册时框架会把它读成 inject 面）。
- */
+// 字段槽注册项的完整 props：框架注入的 owner props（`SchemaFieldOwnerProps`）＋它的 `select` 结果。
+//
+// 注册方的组件按这个类型声明参数（**不要**自己重写 owner props 的类型：注册时框架会把它读成 inject 面）。
 export type SchemaFieldComponentProps<M extends SchemaFieldMatch = SchemaFieldMatch> =
   PropsRuntime<"settings.schema-form.field"> & { matched: M };
 
-/**
- * 字段槽注册项的 `select`：返回认领结果，或 `null` 表示不认领（chain 槽的约定是 `null` 放行给下一项，
- * `undefined` 不会被当成"不认领"）。
- */
+// 字段槽注册项的 `select`：返回认领结果，或 `null` 表示不认领（chain 槽的约定是 `null` 放行给下一项，
+// `undefined` 不会被当成"不认领"）。
 export type SchemaFieldSelect = (field: SchemaFieldOwnerProps) => SchemaFieldMatch | null;
 
-/** 字段槽 `select` 可以只给文案：控件仍由注册方渲染（拿本包的默认控件包一层即可）。 */
+// 字段槽 `select` 可以只给文案：控件仍由注册方渲染（拿本包的默认控件包一层即可）。
 export interface SchemaFieldMatch {
-  /** 覆盖显示标签。 */
+  // 覆盖显示标签。
   label?: string;
-  /** 覆盖显示说明。 */
+  // 覆盖显示说明。
   hint?: string;
 }
 
-/** Factory 的输入 props：一行的配置页。 */
+// Factory 的输入 props：一行的配置页。
 export interface SchemaFormProps {
-  /** settings 命名空间（行 id）。 */
+  // settings 命名空间（行 id）。
   ns: string;
-  /** 该行的控制器动作与状态。 */
+  // 该行的控制器动作与状态。
   face: SchemaFormFace;
-  /** schema 里的本地化文本（`description`）按当前语言解析。 */
+  // schema 里的本地化文本（`description`）按当前语言解析。
   resolveText: ResolveText;
 }
 
-/** Factory 组件收到的完整 props。 */
+// Factory 组件收到的完整 props。
 export type SchemaFormComponentProps = FactoryComponentPropsOf<"settings.schema-form.form">;
 
-/** 本包字典的翻译函数（默认控件与表单壳使用）。 */
+// 本包字典的翻译函数（默认控件与表单壳使用）。
 export type SchemaFormTranslate = TranslateNS<"settings.schema-form">;
 
-/** 渲染层读一行状态的便捷别名。 */
+// 渲染层读一行状态的便捷别名。
 export type { SchemaFormState };
 
 declare module "@deepseek-ai/dsh-client-ui-slots" {
   interface LocaleNamespaceMap {
-    /** 表单壳、字段控件与只读呈现的文案。 */
+    // 表单壳、字段控件与只读呈现的文案。
     "settings.schema-form": SchemaFormLocaleKey;
   }
 
   interface SlotMap {
-    /**
-     * 字段级自定义输入与文案：按 `role` 或 `ns + path` 认领一个字段，命中即渲染注册方的组件（未命中落到默认
-     * 控件）。注册项由业务插件用 `ctx.slots.inject('settings.schema-form.field', …)` 注册，声明由本包的
-     * Factory 给出。
-     */
+    // 字段级自定义输入与文案：按 `role` 或 `ns + path` 认领一个字段，命中即渲染注册方的组件（未命中落到默认
+    // 控件）。注册项由业务插件用 `ctx.slots.inject('settings.schema-form.field', …)` 注册，声明由本包的
+    // Factory 给出。
     "settings.schema-form.field": { kind: "chain"; scope: "root"; owner: SchemaFieldOwnerProps };
   }
 
   interface SlotFactoryMap {
-    /**
-     * 一行配置页的渲染体：每个可渲染的行注册项经 `renderFactorySlot` 渲染同一个 Factory，字段槽因此只需声明
-     * 一次（slots 的 children 声明 per key 唯一）。
-     */
+    // 一行配置页的渲染体：每个可渲染的行注册项经 `renderFactorySlot` 渲染同一个 Factory，字段槽因此只需声明
+    // 一次（slots 的 children 声明 per key 唯一）。
     "settings.schema-form.form": {
       scope: "root";
       props: SchemaFormProps;

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

@@ -1,52 +1,50 @@
-/**
- * 行式编辑器的样式：等宽、行号、语法色、悬停行为——全部消费官方 `--dsw-*` token。
- *
- * 几何只有一套：行高、行内间距、动作按钮尺寸都由下面几个常量给，行与行之间不各自决定。
- */
+// 行式编辑器的样式：等宽、行号、语法色、悬停行为——全部消费官方 `--dsw-*` token。
+//
+// 几何只有一套：行高、行内间距、动作按钮尺寸都由下面几个常量给，行与行之间不各自决定。
 
 import { styled } from "../styling/index.ts";
 import { dsw } from "../theme.ts";
 
-/** 等宽字体栈：配置值的观感与代码一致。 */
+// 等宽字体栈：配置值的观感与代码一致。
 const MONO = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace';
 
-/** 行高：行内容、行内输入、折叠箭头、按钮排都在这一档上对齐。 */
+// 行高：行内容、行内输入、折叠箭头、按钮排都在这一档上对齐。
 const ROW = "22px";
 
-/** 行内元素之间的间距。 */
+// 行内元素之间的间距。
 const GAP = "6px";
 
-/** 动作按钮：方形图标键，尺寸与行高同一档的紧凑版。 */
+// 动作按钮：方形图标键，尺寸与行高同一档的紧凑版。
 const ACTION = "20px";
 
-/** 动作按钮之间的间距（比行内间距紧一档）。 */
+// 动作按钮之间的间距（比行内间距紧一档）。
 const ACTION_GAP = "4px";
 
-/** 图标边长（行内图标与动作键同一档）。 */
+// 图标边长（行内图标与动作键同一档）。
 export const ICON_SIZE = 14;
 
-/** 折叠列（chevron 与它的占位）宽度。 */
+// 折叠列（chevron 与它的占位）宽度。
 const FOLD = "14px";
 
-/** 行号列宽度。 */
+// 行号列宽度。
 const NUMBER = "32px";
 
-/** 行尾留白。 */
+// 行尾留白。
 const PAD = "8px";
 
-/** 细线：theme 给的 0.5px 描边（`0 0 0 0.5px var(--dsw-elevation-stroke-color)`）。 */
+// 细线：theme 给的 0.5px 描边（`0 0 0 0.5px var(--dsw-elevation-stroke-color)`）。
 const HAIRLINE = dsw.elevation.stroke;
 
-/** 描边色：theme 里给描边用的那一档（与官方 `Menu` 面板同源）。 */
+// 描边色：theme 里给描边用的那一档（与官方 `Menu` 面板同源）。
 const LINE = dsw.elevation.stroke.color;
 
-/** 行左侧那道「改过」的标记宽度。 */
+// 行左侧那道「改过」的标记宽度。
 const EDGE = "2px";
 
-/** 出错那一行的底色：theme 的红掺进透明里（半透明红），比整行实红轻、又比只有一道条明显。 */
+// 出错那一行的底色：theme 的红掺进透明里（半透明红），比整行实红轻、又比只有一道条明显。
 const ERROR_WASH = `color-mix(in srgb, ${String(dsw.alias.state.error.secondary)} 12%, transparent)`;
 
-/** 编辑器的根：纵向排列的行。 */
+// 编辑器的根：纵向排列的行。
 export const EditorRoot = styled("div")({
   display: "flex",
   flexDirection: "column",
@@ -57,7 +55,7 @@ export const EditorRoot = styled("div")({
   color: dsw.alias.label.primary,
 });
 
-/** 一行：行号 + 折进 + 行内容。悬停给一层浅底。 */
+// 一行：行号 + 折进 + 行内容。悬停给一层浅底。
 export const LineRow = styled("div")({
   display: "flex",
   // 顶部对齐：行里出现输入框或多行值时，内容不跟着上下跳。
@@ -85,7 +83,7 @@ export const LineRow = styled("div")({
   "&:hover [data-role='actions']": { opacity: 1 },
 });
 
-/** 一行的内容区：**缩进只作用在这里**——行号列固定在左边，缩进不推它。 */
+// 一行的内容区：**缩进只作用在这里**——行号列固定在左边，缩进不推它。
 export const LineBody = styled("div")({
   display: "flex",
   alignItems: "center",
@@ -95,7 +93,7 @@ export const LineBody = styled("div")({
   minHeight: ROW,
 });
 
-/** 行号列：右对齐、不可选、淡色。 */
+// 行号列：右对齐、不可选、淡色。
 export const LineNumber = styled("span")({
   flex: "none",
   width: NUMBER,
@@ -106,7 +104,7 @@ export const LineNumber = styled("span")({
   cursor: "pointer",
 });
 
-/** 折叠 chevron（官方箭头图标，尺寸与别的行内图标同源）。 */
+// 折叠 chevron（官方箭头图标，尺寸与别的行内图标同源）。
 export const LineFold = styled("button")({
   display: "inline-flex",
   alignItems: "center",
@@ -122,26 +120,26 @@ export const LineFold = styled("button")({
   "&:hover": { color: dsw.alias.label.secondary },
 });
 
-/** 叶子行的折叠占位（保持列对齐）。 */
+// 叶子行的折叠占位（保持列对齐）。
 export const LineFoldSpacer = styled("span")({
   flex: "none",
   width: FOLD,
 });
 
-/** 键名（配置键原样；数组下标淡一些）。 */
+// 键名（配置键原样；数组下标淡一些）。
 export const LineKey = styled("span")({
   flex: "none",
   color: dsw.alias.label.primary,
   "&[data-index='true']": { color: dsw.alias.label.caption },
 });
 
-/** 结构符与标点（`{` `}` `[` `]` `:`）。 */
+// 结构符与标点（`{` `}` `[` `]` `:`）。
 export const LineToken = styled("span")({
   flex: "none",
   color: dsw.alias.label.caption,
 });
 
-/** 值（token）：字符串 / 数字 / 布尔各有语法色。 */
+// 值（token）：字符串 / 数字 / 布尔各有语法色。
 export const LineValue = styled("span")({
   minWidth: 0,
   overflow: "hidden",
@@ -153,9 +151,7 @@ export const LineValue = styled("span")({
   "&[data-tone='empty']": { color: dsw.alias.label.caption },
 });
 
-/**
- * 值上的下拉触发：**它自己就是值的呈现**（不再是「值 + 一个下拉」两遍），点开才出菜单。
- */
+// 值上的下拉触发：**它自己就是值的呈现**（不再是「值 + 一个下拉」两遍），点开才出菜单。
 export const ValueTrigger = styled("button")({
   display: "inline-flex",
   alignItems: "center",
@@ -172,11 +168,9 @@ export const ValueTrigger = styled("button")({
   "&:focus-visible": { outline: "none" },
 });
 
-/**
- * 行内输入的外壳：官方 `Input` 压到与值同一行高，并**吃掉剩下的宽度**。
- *
- * 行内编辑与容器闭合行的添加输入共用它——两处的输入框因此长得一模一样。
- */
+// 行内输入的外壳：官方 `Input` 压到与值同一行高，并**吃掉剩下的宽度**。
+//
+// 行内编辑与容器闭合行的添加输入共用它——两处的输入框因此长得一模一样。
 export const CompactInput = styled("span")({
   display: "inline-flex",
   flex: "1 1 auto",
@@ -193,10 +187,8 @@ export const CompactInput = styled("span")({
   },
 });
 
-/**
- * 多行值的行内输入：官方没有多行原子，所以这里用同一套观感的字段壳（同边框、同圆角、同焦点色），
- * 高度跟着内容长、宽度同样撑满剩下的位置。
- */
+// 多行值的行内输入：官方没有多行原子，所以这里用同一套观感的字段壳（同边框、同圆角、同焦点色），
+// 高度跟着内容长、宽度同样撑满剩下的位置。
 export const CompactTextField = styled("span")({
   display: "inline-flex",
   flex: "1 1 auto",
@@ -226,7 +218,7 @@ export const CompactTextField = styled("span")({
   },
 });
 
-/** 行内注释（schema 说明与业务文案）：比配置值小一档，占满这一行剩下的宽度，长了就截断（hover 看全文）。 */
+// 行内注释（schema 说明与业务文案）：比配置值小一档，占满这一行剩下的宽度，长了就截断（hover 看全文）。
 export const LineComment = styled("span")({
   flex: "1 1 auto",
   minWidth: 0,
@@ -237,7 +229,7 @@ export const LineComment = styled("span")({
   fontSize: "12px",
 });
 
-/** 行内的校验消息（与注释放同一档字号）。 */
+// 行内的校验消息（与注释放同一档字号）。
 export const LineInvalid = styled("span")({
   flex: "none",
   color: dsw.alias.state.error.primary,
@@ -245,7 +237,7 @@ export const LineInvalid = styled("span")({
   fontSize: "12px",
 });
 
-/** 行尾的动作组：方形图标键（默认透明，悬停时显形）。 */
+// 行尾的动作组：方形图标键（默认透明，悬停时显形）。
 export const LineActions = styled("span")({
   display: "inline-flex",
   alignItems: "center",
@@ -269,14 +261,10 @@ export const LineActions = styled("span")({
   },
 });
 
-/**
- * 悬停行时才显示这一行的动作按钮：显形规则写在行上（`[data-role='actions']`），组件只需要带这个属性。
- */
+// 悬停行时才显示这一行的动作按钮：显形规则写在行上（`[data-role='actions']`），组件只需要带这个属性。
 export const HoverActions = styled(LineActions)({
-  /**
-   * 编辑态的两个按钮常显，而且**要有底色与描边**：行底色上只有淡色图标是看不见的，
-   * 所以这里给实体按钮（theme 的描边 + 一层底），确认用成功档、取消用中性档。
-   */
+  // 编辑态的两个按钮常显，而且**要有底色与描边**：行底色上只有淡色图标是看不见的，
+  // 所以这里给实体按钮（theme 的描边 + 一层底），确认用成功档、取消用中性档。
   "&[data-editing='true']": {
     opacity: 1,
     gap: GAP,
@@ -289,7 +277,7 @@ export const HoverActions = styled(LineActions)({
   },
 });
 
-/** 添加输入：**跟在容器的闭合括号同一行**（菜单锚在它上面），宽度吃掉剩下的位置。 */
+// 添加输入：**跟在容器的闭合括号同一行**（菜单锚在它上面），宽度吃掉剩下的位置。
 export const AddWrap = styled("span")({
   position: "relative",
   display: "inline-flex",
@@ -301,7 +289,7 @@ export const AddWrap = styled("span")({
   "&[data-invalid='true'] input": { borderColor: dsw.alias.state.error.primary },
 });
 
-/** 一行说明（不可用 / 没有可生成项时用）。 */
+// 一行说明（不可用 / 没有可生成项时用）。
 export const Hint = styled("p")({
   margin: 0,
   fontSize: "12px",

package/src/client/schema-form/testing/fake-describe.ts

@@ -1,20 +1,14 @@
-/**
- * 测试用的 describe 读面替身：可推动命名空间清单变化，形状与上游 mirror 的读面一致。
- */
+// 测试用的 describe 读面替身：可推动命名空间清单变化，形状与上游 mirror 的读面一致。
 
 import type { SettingsNamespaceView } from "@deepseek-ai/dsh-api-remotes/client";
 import type { SettingsDescribeFace } from "@deepseek-ai/dsh-client-ui-settings/client";
 
-/** 一个可以推动变更的 describe 读面。 */
+// 一个可以推动变更的 describe 读面。
 export interface FakeDescribe extends SettingsDescribeFace {
-  /** 换掉命名空间清单并通知订阅者。 */
+  // 换掉命名空间清单并通知订阅者。
   publish(namespaces: readonly SettingsNamespaceView[]): void;
 }
 
-/**
- * @param initial - 初始命名空间清单。
- * @returns 可读可推的 describe 替身。
- */
 export function fakeDescribe(initial: readonly SettingsNamespaceView[] = []): FakeDescribe {
   const listeners = new Set<() => void>();
   let namespaces = initial;

package/src/client/schema-form/testing/fake-scope.ts

@@ -1,21 +1,19 @@
-/**
- * 测试用的共享配置表单：内存里模拟 host 的读写两层（快照 / 订阅 / 一次带 revision 栅栏的写）。
- *
- * 它让控制器与草稿模型的用例不碰远程面、不碰装配，只盯「草稿怎么变成写」与「状态怎么投影」。
- */
+// 测试用的共享配置表单：内存里模拟 host 的读写两层（快照 / 订阅 / 一次带 revision 栅栏的写）。
+//
+// 它让控制器与草稿模型的用例不碰远程面、不碰装配，只盯「草稿怎么变成写」与「状态怎么投影」。
 
 import type { SettingsPathOpView } from "@deepseek-ai/dsh-api-remotes/client";
 import type { ConfigForm, ConfigFormSnapshot } from "@deepseek-ai/dsh-client-ui-settings/client";
 
-/** 命名空间段的值。 */
+// 命名空间段的值。
 export type Section = Record<string, unknown>;
 
 export class FakeScope implements ConfigForm<Section> {
-  /** 每次保存发出的 path op（按保存顺序）。 */
+  // 每次保存发出的 path op（按保存顺序）。
   readonly writes: (readonly SettingsPathOpView[])[] = [];
-  /** 每次保存带的 revision 栅栏。 */
+  // 每次保存带的 revision 栅栏。
   readonly fences: (number | undefined)[] = [];
-  /** 让 host 拒绝下一次写。 */
+  // 让 host 拒绝下一次写。
   accepted = true;
 
   #snapshot: ConfigFormSnapshot<Section>;
@@ -85,7 +83,7 @@ export class FakeScope implements ConfigForm<Section> {
     return Promise.resolve(true);
   }
 
-  /** 从外部改一次读数（模拟另一个界面或 host 的改动）。 */
+  // 从外部改一次读数（模拟另一个界面或 host 的改动）。
   publish(overrides: Partial<ConfigFormSnapshot<Section>> = {}): void {
     this.#snapshot = { ...this.#snapshot, ...overrides };
     this.#publish();

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

@@ -1,9 +1,7 @@
-/**
- * 行内值的呈现与编辑文本规则，以及字段槽注册方复用的默认值组件。
- *
- * 值本身仍走草稿：这个文件只决定"怎么显示"（语法色 token、下拉触发的呈现）与"怎么编辑"（一行输入框里的文本
- * 形状——字符串把换行写成 `\n`，与一行的输入框相配）。
- */
+// 行内值的呈现与编辑文本规则，以及字段槽注册方复用的默认值组件。
+//
+// 值本身仍走草稿：这个文件只决定"怎么显示"（语法色 token、下拉触发的呈现）与"怎么编辑"（一行输入框里的文本
+// 形状——字符串把换行写成 `\n`，与一行的输入框相配）。
 
 import { useState, type ReactNode } from "react";
 import { IconChevronDownOutlineRegular, Menu } from "@deepseek-ai/dsh-client-ui-primitives";
@@ -11,7 +9,7 @@ import type { SelectOption } from "./hints.ts";
 import type { SchemaFieldOwnerProps } from "./slot-contract.ts";
 import { ICON_SIZE, LineValue, ValueTrigger } from "./styles.ts";
 
-/** 编辑态文本：字符串就是原文（换行照旧），其余按 JSON 写。 */
+// 编辑态文本：字符串就是原文（换行照旧），其余按 JSON 写。
 export function valueText(value: unknown): string {
   if (value === undefined || value === null) return "";
   if (typeof value === "string") return value;
@@ -19,12 +17,12 @@ export function valueText(value: unknown): string {
   return JSON.stringify(value);
 }
 
-/** 这个值要在多行输入里编辑吗（字符串带换行）。 */
+// 这个值要在多行输入里编辑吗（字符串带换行）。
 export function isMultiline(value: unknown): boolean {
   return typeof value === "string" && /[\r\n]/.test(value);
 }
 
-/** 显示态文本：字符串带引号；多行与特殊字符都按 JSON 的写法收在一行里。 */
+// 显示态文本：字符串带引号；多行与特殊字符都按 JSON 的写法收在一行里。
 export function tokenText(value: unknown): string {
   if (value === undefined || value === null) return "null";
   if (typeof value === "string") return JSON.stringify(value);
@@ -32,7 +30,7 @@ export function tokenText(value: unknown): string {
   return JSON.stringify(value);
 }
 
-/** 值的语法色分组。 */
+// 值的语法色分组。
 export function tokenTone(value: unknown): "string" | "number" | "boolean" | "empty" {
   if (value === undefined || value === null) return "empty";
   if (typeof value === "number") return "number";
@@ -40,11 +38,7 @@ export function tokenTone(value: unknown): "string" | "number" | "boolean" | "em
   return "string";
 }
 
-/**
- * 行内值的默认呈现（显示态 token）。
- * @param props.owner - 字段上下文（值、是否 secret、只读原因）。
- * @returns 一行里的值节点。
- */
+// 行内值的默认呈现（显示态 token）。
 export function InlineValue({ owner }: { owner: SchemaFieldOwnerProps }): ReactNode {
   if (owner.options !== undefined) return <OptionSelect owner={owner} options={owner.options} />;
   if (owner.node.meta.secret) {
@@ -66,11 +60,8 @@ export function InlineValue({ owner }: { owner: SchemaFieldOwnerProps }): ReactN
   );
 }
 
-/**
- * 选择器：**值本身**就是下拉的触发（不再另画一个 `select` 与它并列），点开是官方菜单。
- *
- * 当前值不在候选里时（例如目录里已经没有那个服务商）照原样显示，选中才换成新值。
- */
+// 选择器：**值本身**就是下拉的触发（不再另画一个 `select` 与它并列），点开是官方菜单。
+// 当前值不在候选里时（例如目录里已经没有那个服务商）照原样显示，选中才换成新值。
 function OptionSelect({
   owner,
   options,
@@ -128,7 +119,7 @@ function OptionSelect({
   );
 }
 
-/** 值是否就是这一项（菜单的高亮判据）。 */
+// 值是否就是这一项（菜单的高亮判据）。
 function sameValue(left: unknown, right: unknown): boolean {
   if (Object.is(left, right)) return true;
   if (typeof left !== "object" || typeof right !== "object" || left === null || right === null)
@@ -136,11 +127,8 @@ function sameValue(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
-/**
- * 字段槽注册方复用的默认值：只改文案时拿它包一层即可（`owner` 上覆盖 `label`/`hint`）。
- *
- * 注意行式视图里键名来自配置键本身、注释来自 `hint`，所以 `label` 只在业务自写控件时才需要。
- */
+// 字段槽注册方复用的默认值：只改文案时拿它包一层即可（`owner` 上覆盖 `label`/`hint`）。
+// 行式视图里键名来自配置键本身、注释来自 `hint`，所以 `label` 只在业务自写控件时才需要。
 export function SchemaFieldDefault({ owner }: { owner: SchemaFieldOwnerProps }): ReactNode {
   return <InlineValue owner={owner} />;
 }

package/src/client/settings-form/SettingsForm.tsx

@@ -12,39 +12,35 @@ const Footer = styled("div")(styles.footer);
 const Failed = styled("p")(styles.failed);
 const Save = styled("button")(styles.save);
 
-/** The copy the form frame renders, from the owning plugin's dictionary. */
+// The copy the form frame renders, from the owning plugin's dictionary.
 export interface SettingsFormLabels {
-  /** Shown in place of the controls while the namespace is not served. */
+  // Shown in place of the controls while the namespace is not served.
   unavailable: string;
-  /** Shown over the controls while the document is read-only. */
+  // Shown over the controls while the document is read-only.
   readOnly: string;
-  /** Shown beside the save after a save the Host did not accept. */
+  // Shown beside the save after a save the Host did not accept.
   saveFailed: string;
-  /** The save control. */
+  // The save control.
   save: string;
-  /** The save control while a save is crossing the wire. */
+  // The save control while a save is crossing the wire.
   saving: string;
 }
 
-/** Form chrome shared by every settings page. */
+// Form chrome shared by every settings page.
 export interface SettingsFormProps {
-  /** The frame's copy. */
+  // The frame's copy.
   labels: SettingsFormLabels;
-  /** The form state: availability, writability, and what a save would do. */
+  // The form state: availability, writability, and what a save would do.
   state: SettingsFormShell;
-  /** Write every staged edit. */
+  // Write every staged edit.
   onSave: () => void;
-  /** Drop every staged edit; the form calls it when it leaves the page. */
+  // Drop every staged edit; the form calls it when it leaves the page.
   onDiscard: () => void;
-  /** The plugin's controls. */
+  // The plugin's controls.
   children: ReactNode;
 }
 
-/**
- * Render one plugin's settings form.
- * @param props - the form's copy and state, its controls, and the save and discard actions.
- * @returns the form, or the unavailable line while the namespace is not served.
- */
+// Render one plugin's settings form.
 export function SettingsForm(props: SettingsFormProps) {
   const { state, labels } = props;
   const discard = useRef(props.onDiscard);