@morlay/dsh-client-ui-primitives 0.0.2-alpha.7 → 0.0.2-alpha.9

package/dist/client.d.cts

@@ -1,7 +1,12 @@
 import { a as formatReferenceMention, c as parseReferenceToken, i as formatReference, n as ReferenceSpan, o as isLocalReference, r as findReferences, s as parseReference, t as Reference } from "./reference-BX54bj6_.cjs";
-import { Context } from "@deepseek-ai/cordis";
-import { ComponentProps, ComponentPropsWithRef, ElementType, ForwardRefExoticComponent, Ref, RefAttributes } from "react";
-import { MarkdownFileMentions, MarkdownLabels, MarkdownLabels as MarkdownLabels$1, MarkdownPathImages } from "@deepseek-ai/dsh-client-ui-primitives";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { ComponentProps, ComponentPropsWithRef, ElementType, ForwardRefExoticComponent, ReactNode, Ref, RefAttributes } from "react";
+import { MarkdownFileMentions, MarkdownLabels, MarkdownLabels as MarkdownLabels$1, MarkdownPathImages, SettingsFormShell as SettingsFormShell$1 } from "@deepseek-ai/dsh-client-ui-primitives";
+import { SnapshotStore } from "@deepseek-ai/dsh-client-store";
+import { PropsRuntime, TranslateNS } from "@deepseek-ai/dsh-client-ui-slots";
+import { BundleInfo, SettingsNamespaceView } from "@deepseek-ai/dsh-api-remotes/client";
+import { ConfigForm, SchemaNode, SettingsDescribeFace } from "@deepseek-ai/dsh-client-ui-settings/client";
+//#endregion
 //#region ../../../node_modules/.pnpm/csstype@3.2.3/node_modules/csstype/index.d.ts
 interface StandardLonghandProperties<TLength = (string & {}) | 0, TTime = string & {}> {
   /**
@@ -9414,7 +9419,7 @@ declare function styleOf(component: StyledComponent<ElementType>): CSSProps;
 //#endregion
 //#region src/client/theme.generated.d.ts
 /**
- * 官方主题的 `--dsw-*` token 全集（367 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
+ * 官方主题的 `--dsw-*` token 全集（395 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
  *
  * 叶子是该变量的**默认值**（官方 light 主题里首次出现的定义）：既是类型推导的来源，也可作 fallback。
  * `"$"` 键出现在「自身也是 token 的分支」上（命名体系里有 40 个短名同时是长名前缀的 token）。
@@ -9425,7 +9430,7 @@ declare const designTokens: {
     readonly bg: {
       readonly base: "var(--dsw-static-neutral-bluish-00)";
       readonly document: {
-        readonly preview: "var(--dsw-static-neutral-bluish-750)";
+        readonly preview: "var(--dsw-static-neutral-bluish-100)";
       };
       readonly layer: {
         readonly "1": "var(--dsw-static-neutral-bluish-00)";
@@ -9518,6 +9523,20 @@ declare const designTokens: {
         readonly deleted: "var(--dsw-static-red-600-a08)";
       };
     };
+    readonly file: {
+      readonly diff: {
+        readonly added: {
+          readonly bg: "rgb(230, 244, 231)";
+          readonly gutter: "rgb(237, 247, 237)";
+          readonly marker: "rgb(1, 162, 65)";
+        };
+        readonly deleted: {
+          readonly bg: "rgb(252, 230, 226)";
+          readonly gutter: "rgb(253, 236, 233)";
+          readonly marker: "rgb(186, 39, 35)";
+        };
+      };
+    };
     readonly interactive: {
       readonly bg: {
         readonly active: "rgba(38, 49, 72, 0.1)";
@@ -9533,7 +9552,7 @@ declare const designTokens: {
       readonly caption: "var(--dsw-static-neutral-bluish-400)";
       readonly dimmed: "var(--dsw-static-neutral-bluish-200)";
       readonly document: {
-        readonly preview: "var(--dsw-static-neutral-bluish-200)";
+        readonly preview: "var(--dsw-static-neutral-bluish-700)";
       };
       readonly primary: {
         readonly $: "var(--dsw-static-neutral-bluish-1000)";
@@ -9564,6 +9583,21 @@ declare const designTokens: {
       readonly placeholder: "var(--dsw-static-neutral-bluish-60)";
       readonly tag: "var(--dsw-static-neutral-bluish-75)";
     };
+    readonly menu: {
+      readonly icon: "var(--dsw-static-neutral-bluish-800)";
+    };
+    readonly onboarding: {
+      readonly accent: "rgb(57, 100, 254)";
+      readonly card: {
+        readonly fill: "color-mix(in srgb, var(--dsw-static-neutral-bluish-00) 80%, transparent)";
+      };
+      readonly checkbox: {
+        readonly border: "color-mix(in srgb, var(--dsw-static-neutral-bluish-1000) 20%, transparent)";
+      };
+      readonly secondary: {
+        readonly fill: "var(--dsw-static-neutral-bluish-00)";
+      };
+    };
     readonly scrollbar: {
       readonly bg: {
         readonly l1: "var(--dsw-static-neutral-200)";
@@ -9574,6 +9608,12 @@ declare const designTokens: {
         readonly l2: "var(--dsw-static-neutral-300)";
       };
     };
+    readonly settings: {
+      readonly card: {
+        readonly fill: "var(--dsw-alias-bg-layer-2)";
+        readonly stroke: "var(--dsw-alias-border-l4)";
+      };
+    };
     readonly state: {
       readonly business: {
         readonly primary: "var(--dsw-static-deepseek-500)";
@@ -9600,9 +9640,13 @@ declare const designTokens: {
     };
     readonly toast: {
       readonly bg: "var(--dsw-static-neutral-bluish-800)";
+      readonly label: "var(--dsw-static-neutral-bluish-00)";
     };
     readonly tooltip: {
       readonly bg: "var(--dsw-static-neutral-bluish-850)";
+      readonly key: {
+        readonly bg: "color-mix(in srgb, var(--dsw-alias-tooltip-bg), white 18%)";
+      };
     };
   };
   readonly corner: {
@@ -9617,6 +9661,12 @@ declare const designTokens: {
       readonly color: "var(--dsw-alias-border-l4)";
     };
   };
+  readonly focus: {
+    readonly ring: {
+      readonly color: "transparent";
+      readonly width: "2px";
+    };
+  };
   readonly font: {
     readonly base: {
       readonly "16": {
@@ -9646,7 +9696,10 @@ declare const designTokens: {
         };
       };
     };
-    readonly family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',\n    'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif";
+    readonly family: {
+      readonly $: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',\n    'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif";
+      readonly brand: "'Montserrat', var(--dsw-font-family)";
+    };
     readonly l: {
       readonly "20": {
         readonly $: "500 20px/28px var(--dsw-font-family)";
@@ -10008,6 +10061,19 @@ declare const designTokens: {
       };
     };
   };
+  readonly gradient: {
+    readonly onboarding: {
+      readonly blue: {
+        readonly stops: "#3964fe 18.75%, #398efe 51.78%, #6dccff 86.252%, #3964fe";
+      };
+      readonly cyan: {
+        readonly stops: "#0293b4 21.154%, #2dc8eb 50.954%, #aff0ff 85.326%, #0293b4";
+      };
+      readonly violet: {
+        readonly stops: "#2a2fb6 33.102%, #8b76f6 50.954%, #c5c0ff 85.326%, #2a2fb6";
+      };
+    };
+  };
   readonly linear: {
     readonly gradient: {
       readonly think: "linear-gradient(180deg, #fff 20.19%, rgba(255, 255, 255, 0) 100%)";
@@ -10017,12 +10083,23 @@ declare const designTokens: {
     };
   };
   readonly mask: {
-    readonly blur: "blur(2px)";
+    readonly blur: "none";
   };
   readonly menu: {
     readonly backdrop: {
       readonly filter: "blur(40px) saturate(150%)";
     };
+    readonly surface: {
+      readonly fill: "rgba(248, 249, 250, 0.58)";
+    };
+  };
+  readonly radius: {
+    readonly lg: "16px";
+    readonly md: "12px";
+    readonly panel: "28px";
+    readonly sm: "8px";
+    readonly xl: "20px";
+    readonly xs: "4px";
   };
   readonly shadow: {
     readonly lv1: {
@@ -10043,7 +10120,7 @@ declare const designTokens: {
     readonly login: {
       readonly input: "var(--dsw-static-neutral-bluish-50)";
     };
-    readonly menu: "rgba(248, 249, 250, 0.58)";
+    readonly menu: "var(--dsw-menu-surface-fill)";
     readonly selector: "var(--dsw-static-neutral-bluish-60)";
     readonly sidebar: {
       readonly fill: "var(--dsw-static-neutral-bluish-50)";
@@ -10168,7 +10245,7 @@ declare const dsw: TokenVars<{
     readonly bg: {
       readonly base: "var(--dsw-static-neutral-bluish-00)";
       readonly document: {
-        readonly preview: "var(--dsw-static-neutral-bluish-750)";
+        readonly preview: "var(--dsw-static-neutral-bluish-100)";
       };
       readonly layer: {
         readonly "1": "var(--dsw-static-neutral-bluish-00)";
@@ -10261,6 +10338,20 @@ declare const dsw: TokenVars<{
         readonly deleted: "var(--dsw-static-red-600-a08)";
       };
     };
+    readonly file: {
+      readonly diff: {
+        readonly added: {
+          readonly bg: "rgb(230, 244, 231)";
+          readonly gutter: "rgb(237, 247, 237)";
+          readonly marker: "rgb(1, 162, 65)";
+        };
+        readonly deleted: {
+          readonly bg: "rgb(252, 230, 226)";
+          readonly gutter: "rgb(253, 236, 233)";
+          readonly marker: "rgb(186, 39, 35)";
+        };
+      };
+    };
     readonly interactive: {
       readonly bg: {
         readonly active: "rgba(38, 49, 72, 0.1)";
@@ -10276,7 +10367,7 @@ declare const dsw: TokenVars<{
       readonly caption: "var(--dsw-static-neutral-bluish-400)";
       readonly dimmed: "var(--dsw-static-neutral-bluish-200)";
       readonly document: {
-        readonly preview: "var(--dsw-static-neutral-bluish-200)";
+        readonly preview: "var(--dsw-static-neutral-bluish-700)";
       };
       readonly primary: {
         readonly $: "var(--dsw-static-neutral-bluish-1000)";
@@ -10307,6 +10398,21 @@ declare const dsw: TokenVars<{
       readonly placeholder: "var(--dsw-static-neutral-bluish-60)";
       readonly tag: "var(--dsw-static-neutral-bluish-75)";
     };
+    readonly menu: {
+      readonly icon: "var(--dsw-static-neutral-bluish-800)";
+    };
+    readonly onboarding: {
+      readonly accent: "rgb(57, 100, 254)";
+      readonly card: {
+        readonly fill: "color-mix(in srgb, var(--dsw-static-neutral-bluish-00) 80%, transparent)";
+      };
+      readonly checkbox: {
+        readonly border: "color-mix(in srgb, var(--dsw-static-neutral-bluish-1000) 20%, transparent)";
+      };
+      readonly secondary: {
+        readonly fill: "var(--dsw-static-neutral-bluish-00)";
+      };
+    };
     readonly scrollbar: {
       readonly bg: {
         readonly l1: "var(--dsw-static-neutral-200)";
@@ -10317,6 +10423,12 @@ declare const dsw: TokenVars<{
         readonly l2: "var(--dsw-static-neutral-300)";
       };
     };
+    readonly settings: {
+      readonly card: {
+        readonly fill: "var(--dsw-alias-bg-layer-2)";
+        readonly stroke: "var(--dsw-alias-border-l4)";
+      };
+    };
     readonly state: {
       readonly business: {
         readonly primary: "var(--dsw-static-deepseek-500)";
@@ -10343,9 +10455,13 @@ declare const dsw: TokenVars<{
     };
     readonly toast: {
       readonly bg: "var(--dsw-static-neutral-bluish-800)";
+      readonly label: "var(--dsw-static-neutral-bluish-00)";
     };
     readonly tooltip: {
       readonly bg: "var(--dsw-static-neutral-bluish-850)";
+      readonly key: {
+        readonly bg: "color-mix(in srgb, var(--dsw-alias-tooltip-bg), white 18%)";
+      };
     };
   };
   readonly corner: {
@@ -10360,6 +10476,12 @@ declare const dsw: TokenVars<{
       readonly color: "var(--dsw-alias-border-l4)";
     };
   };
+  readonly focus: {
+    readonly ring: {
+      readonly color: "transparent";
+      readonly width: "2px";
+    };
+  };
   readonly font: {
     readonly base: {
       readonly "16": {
@@ -10389,7 +10511,10 @@ declare const dsw: TokenVars<{
         };
       };
     };
-    readonly family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',\n    'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif";
+    readonly family: {
+      readonly $: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',\n    'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif";
+      readonly brand: "'Montserrat', var(--dsw-font-family)";
+    };
     readonly l: {
       readonly "20": {
         readonly $: "500 20px/28px var(--dsw-font-family)";
@@ -10751,6 +10876,19 @@ declare const dsw: TokenVars<{
       };
     };
   };
+  readonly gradient: {
+    readonly onboarding: {
+      readonly blue: {
+        readonly stops: "#3964fe 18.75%, #398efe 51.78%, #6dccff 86.252%, #3964fe";
+      };
+      readonly cyan: {
+        readonly stops: "#0293b4 21.154%, #2dc8eb 50.954%, #aff0ff 85.326%, #0293b4";
+      };
+      readonly violet: {
+        readonly stops: "#2a2fb6 33.102%, #8b76f6 50.954%, #c5c0ff 85.326%, #2a2fb6";
+      };
+    };
+  };
   readonly linear: {
     readonly gradient: {
       readonly think: "linear-gradient(180deg, #fff 20.19%, rgba(255, 255, 255, 0) 100%)";
@@ -10760,12 +10898,23 @@ declare const dsw: TokenVars<{
     };
   };
   readonly mask: {
-    readonly blur: "blur(2px)";
+    readonly blur: "none";
   };
   readonly menu: {
     readonly backdrop: {
       readonly filter: "blur(40px) saturate(150%)";
     };
+    readonly surface: {
+      readonly fill: "rgba(248, 249, 250, 0.58)";
+    };
+  };
+  readonly radius: {
+    readonly lg: "16px";
+    readonly md: "12px";
+    readonly panel: "28px";
+    readonly sm: "8px";
+    readonly xl: "20px";
+    readonly xs: "4px";
   };
   readonly shadow: {
     readonly lv1: {
@@ -10786,7 +10935,7 @@ declare const dsw: TokenVars<{
     readonly login: {
       readonly input: "var(--dsw-static-neutral-bluish-50)";
     };
-    readonly menu: "rgba(248, 249, 250, 0.58)";
+    readonly menu: "var(--dsw-menu-surface-fill)";
     readonly selector: "var(--dsw-static-neutral-bluish-60)";
     readonly sidebar: {
       readonly fill: "var(--dsw-static-neutral-bluish-50)";
@@ -10909,6 +11058,1198 @@ declare const dsw: TokenVars<{
 type MarkdownCopySeat = (key: "copy" | "copied" | "markdown.footnotes") => string;
 declare function markdownLabels(t: MarkdownCopySeat): MarkdownLabels;
 //#endregion
+//#region src/client/settings-form/form-model.d.ts
+/** What the model reads of one Host entry's form. */
+interface SettingsFormScopeSnapshot<T> {
+  /** `ready` while the Host serves the entry to this client; the form renders nothing otherwise. */
+  status: "loading" | "ready" | "unavailable";
+  /** Last accepted schema-resolved section; undefined before the first acceptance. */
+  value: T | undefined;
+  /** Composition layer the value resolves over: what a field reverts to once cleared. */
+  base: unknown;
+  /** Raw user layer as stored; a field's PRESENCE here is what marks it overridden. */
+  user: unknown;
+  /** Whether the Host document accepts writes. */
+  writable: boolean;
+  /** Revision the snapshot was read at; a save fences its mutation with the revision its drafts started from. */
+  revision: number | undefined;
+}
+/** One path edit a save sends, as the shared configuration form's `mutate` accepts it. */
+type SettingsFormPathOp = {
+  op: "set";
+  path: readonly string[];
+  value: unknown;
+} | {
+  op: "unset";
+  path: readonly string[];
+};
+/** The entry form the model stages over: the reads and the atomic write of the form `ui-settings` shares per Host entry. */
+interface SettingsFormScope<T> {
+  /** @returns the current sync snapshot. */
+  getSnapshot(): SettingsFormScopeSnapshot<T>;
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Apply ordered field edits in one revision-fenced write.
+   * @param ops - the edits, in staging order.
+   * @param expectedRevision - the revision the drafts were staged against, when known.
+   * @returns true for Host acceptance, false for refusal, after any recovery read.
+   */
+  mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+/** The write one field's staged text performs when the card is saved. */
+type SettingsFieldWrite = {
+  kind: "set";
+  value: unknown;
+} | {
+  kind: "clear";
+};
+/** How one section field converts between its stored value and its draft text. */
+interface SettingsFieldSpec {
+  /** Field name inside the namespace section. */
+  field: string;
+  /** Render a stored value as draft text; the empty string when the section carries none. */
+  format: (value: unknown) => string;
+  /**
+   * The write this draft text stages, or undefined when the text is not a
+   * value this field accepts — which blocks the save rather than discarding it.
+   */
+  parse: (text: string) => SettingsFieldWrite | undefined;
+}
+/**
+ * A control whose value is written outside the settings section. A credential
+ * literal never rides a response, so its draft has nothing to seed from: it is
+ * blank until typed, and a blank draft writes nothing.
+ */
+interface SettingsSecretSpec {
+  /** Field name addressing this control inside the card's form. */
+  field: string;
+  /** Write the staged text; resolves to whether the Host accepted it. */
+  write: (text: string) => Promise<boolean>;
+}
+/** One field as a card's control renders it. */
+interface SettingsFieldState {
+  /** Draft text the control renders. */
+  text: string;
+  /**
+   * Whether saving would leave a user-layer entry for this field. A staged
+   * edit answers for itself, so the badge previews the save rather than
+   * reporting a state the pending edit already contradicts.
+   */
+  overridden: boolean;
+  /** Whether the draft is not a value this field accepts, which blocks saving. */
+  invalid: boolean;
+}
+/** Form state every plugin card shares. */
+interface SettingsFormShell {
+  /** False while the namespace is not served to this client; the card renders nothing. */
+  available: boolean;
+  /** Whether the Host document accepts writes. */
+  writable: boolean;
+  /** Whether the form holds edits that a save would write. */
+  dirty: boolean;
+  /** Whether any staged draft is invalid, which blocks the save. */
+  invalid: boolean;
+  /** Whether a save is crossing the wire. */
+  saving: boolean;
+  /** Whether the last save did not land as staged; cleared by the next edit or save. */
+  failed: boolean;
+}
+/** The write actions every plugin card's slot entry injects. */
+interface SettingsFormActions {
+  /** Stage draft text for one field. */
+  edit: (field: string, text: string) => void;
+  /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+  resetField: (field: string) => void;
+  /** Write every staged edit, then re-seed from what the Host accepted. */
+  save: () => void;
+  /** Drop every staged edit. */
+  discard: () => void;
+}
+/**
+ * A whole-number field. An empty draft clears the field; any other draft that
+ * is not a finite number blocks the save.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+declare function settingsNumberField(field: string): SettingsFieldSpec;
+/**
+ * A free-text field. An empty draft clears the field, so emptying the control
+ * and saving is the same gesture as resetting it.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+declare function settingsTextField(field: string): SettingsFieldSpec;
+/**
+ * Stages one card's edits over one settings namespace and writes them on save.
+ *
+ * The form publishes through a snapshot store because slot components read
+ * through a snapshot selector, while both the scope and the local drafts
+ * change underneath; every projection is rebuilt from the two together.
+ */
+declare class SettingsFormModel<T> {
+  private readonly scope;
+  private readonly specs;
+  private readonly secretSpecs;
+  private readonly staged;
+  private readonly listeners;
+  private baseline;
+  private readonly unsubscribe;
+  private saving;
+  private failed;
+  /**
+   * @param scope - the shared configuration form for this card's namespace.
+   * @param specs - the section fields this card edits.
+   * @param secrets - the card's write-only controls, written outside the section.
+   */
+  constructor(scope: SettingsFormScope<T>, specs: SettingsFieldSpec[], secrets?: SettingsSecretSpec[]);
+  /**
+   * Publish a projection of this form, rebuilt whenever the scope or a draft changes.
+   * @param project - build the card's state from the form's current reads.
+   * @returns the store the card's component reads through its bound selector.
+   */
+  bind<S>(project: () => S): SnapshotStore<S>;
+  /**
+   * Read the card-level state: what the Host serves, and what a save would do.
+   * @returns the form state every card shares.
+   */
+  shell(): SettingsFormShell;
+  /**
+   * Read one control's state.
+   * @param field - field name of a section field or of a write-only control.
+   * @returns the draft text, whether a save would leave an override, and whether it is invalid.
+   */
+  field(field: string): SettingsFieldState;
+  /**
+   * Build the edit, reset, save, and discard actions bound to this form.
+   * @returns the actions a card's slot entry injects.
+   */
+  actions(): SettingsFormActions;
+  /**
+   * Write every staged edit, then re-seed from what the Host accepted.
+   *
+   * The Host is the only authority on whether a value was accepted — its
+   * validators own the constraints no schema can express — so the outcome is
+   * read back from the section rather than predicted here. A save that did not
+   * land keeps its drafts, so the user can correct them instead of retyping.
+   * @returns settlement after every write and the read-back.
+   */
+  save(): Promise<void>;
+  /** Release the form's accepted-value subscription. */
+  dispose(): void;
+  /**
+   * Every staged edit a save would write. An entry whose draft is not a value
+   * its field accepts carries no write: the form is still dirty, and the save
+   * refuses rather than dropping the edit.
+   * @returns the planned writes, in the order the fields were staged.
+   */
+  private plan;
+  private stage;
+  private spec;
+  private snapshotOf;
+  private sectionValue;
+  private baseValue;
+  private userLayer;
+  private stored;
+  private publish;
+}
+//#endregion
+//#region src/client/settings-form/fields.d.ts
+/** What every settings field control needs regardless of its value type. */
+interface SettingsFieldProps {
+  /** Stable id associating the label with its control. */
+  id: string;
+  /** Visible label. */
+  label: string;
+  /** One-line explanation rendered under the control. */
+  hint: string;
+  /** Draft text this control renders. */
+  text: string;
+  /** True when saving would leave a user-layer entry for this field. */
+  overridden: boolean;
+  /** True when the draft is not a value this field accepts. */
+  invalid: boolean;
+  /** Copy for the overridden badge. */
+  overriddenLabel: string;
+  /** Copy for the reset control. */
+  resetLabel: string;
+  /** Copy shown in place of the hint while the draft is invalid. */
+  invalidLabel: string;
+  /** Disables every control (read-only document, or an unavailable namespace). */
+  disabled: boolean;
+  /** Stage draft text. */
+  onEdit: (text: string) => void;
+  /** Stage a clear so the field re-inherits the composition layer. */
+  onReset: () => void;
+}
+/**
+ * A staged value field. `numeric` only hints the keypad: which drafts a field
+ * accepts is decided by its spec, so the control never silently rewrites what
+ * the user typed.
+ * @param props - the field's copy, its staged text, and the edit actions.
+ * @returns the labelled control.
+ */
+declare function SettingsValueField(props: Omit<SettingsFieldProps, "hint"> & {
+  /** Optional explanation shown below the input. */
+  hint?: string;
+  /** Rules disclosed by the information button beside the label. */
+  help?: {
+    label: string;
+    content: ReactNode;
+  };
+  /** Hints a numeric keypad without narrowing what the control accepts. */
+  numeric?: boolean;
+  /** Placeholder shown while the draft is empty. */
+  placeholder?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * A write-only credential control. The value never rides a response, so the
+ * control reports only whether one is configured and starts blank; a blank
+ * draft writes nothing, which keeps the stored key rather than clearing it.
+ * 控件要求浏览器不要把已存的登录密码自动填进来（上游 11c0511271）。
+ * @param props - the field's copy, its staged text, and the configured state.
+ * @returns the labelled control.
+ */
+declare function SettingsSecretField(props: Pick<SettingsFieldProps, "id" | "label" | "hint" | "text" | "disabled" | "onEdit"> & {
+  /** Whether the Host reports a configured credential for this reference. */
+  configured: boolean;
+  /** Copy describing the configured state. */
+  stateLabel: string;
+}): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/client/settings-form/SettingsForm.d.ts
+/** The copy the form frame renders, from the owning plugin's dictionary. */
+interface SettingsFormLabels {
+  /** Shown in place of the controls while the namespace is not served. */
+  unavailable: string;
+  /** Shown over the controls while the document is read-only. */
+  readOnly: string;
+  /** Shown beside the save after a save the Host did not accept. */
+  saveFailed: string;
+  /** The save control. */
+  save: string;
+  /** The save control while a save is crossing the wire. */
+  saving: string;
+}
+/** Form chrome shared by every settings page. */
+interface SettingsFormProps {
+  /** The frame's copy. */
+  labels: SettingsFormLabels;
+  /** The form state: availability, writability, and what a save would do. */
+  state: SettingsFormShell;
+  /** Write every staged edit. */
+  onSave: () => void;
+  /** Drop every staged edit; the form calls it when it leaves the page. */
+  onDiscard: () => void;
+  /** 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.
+ */
+declare function SettingsForm(props: SettingsFormProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/client/schema-form/schema-node.d.ts
+/** 节点不可编辑的原因；`null` 表示可编辑。 */
+type ReadOnlyReason = "transform" | "function" | "constructor";
+/** 归一化后的字段元数据（schemastery `meta` 的可用子集）。 */
+interface FieldMeta {
+  /** `description`（可能是本地化字典）：渲染时经 locale 解析。 */
+  description: string | Readonly<Record<string, string>> | undefined;
+  /** `comment`：纯文本补充说明。 */
+  comment: string | undefined;
+  /** `link`：外部文档。 */
+  link: string | undefined;
+  /** `role`：控件提示（`secret` / `slider` / `datetime` …）。 */
+  role: string | undefined;
+  /** `role === 'secret'`：值不回传，只能写。 */
+  secret: boolean;
+  /** `required()`。 */
+  required: boolean;
+  /** `disabled()`：控件禁用。 */
+  disabled: boolean;
+  /** `collapse()`：嵌套分组默认折叠。 */
+  collapse: boolean;
+  /** `deprecated()` / `experimental()` 的徽标文本。 */
+  badges: readonly string[];
+  /** `pattern()` 的正则来源。 */
+  pattern: string | undefined;
+  /** `min()`。 */
+  min: number | undefined;
+  /** `max()`。 */
+  max: number | undefined;
+  /** `step()`：`1` 表示整数。 */
+  step: number | undefined;
+  /** 是否声明了默认值（与「默认值是 undefined」区分开）。 */
+  hasDefault: boolean;
+  /** 声明的默认值。 */
+  defaultValue: unknown;
+  /** `extra()`：角色附带的任意数据，字段槽的自定义控件可用。 */
+  extra: unknown;
+}
+/** 每种节点共有的部分。 */
+interface FieldNodeBase {
+  /** 这一层的名字：对象字段名、tuple 的索引、动态子节点的占位段。 */
+  key: string;
+  /** 从段根起的路径；动态段是 {@link DYNAMIC_SEGMENT}。 */
+  path: readonly string[];
+  /**
+   * 按值展开时算好的显示名：数组成员的**项身份**（见 {@link FieldNodeBase} 所在的 array 节点）。
+   * 投影时没有（`undefined`），渲染层用它优先于字段名。
+   */
+  label: string | undefined;
+  /** 归一化后的元数据。 */
+  meta: FieldMeta;
+  /** 不可编辑的原因；`null` 表示可编辑。 */
+  readOnly: ReadOnlyReason | null;
+}
+/** 位集的一位。 */
+interface BitsEntry {
+  name: string;
+  bit: number;
+}
+/** 渲染层要的一个字段节点。 */
+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 就是索引语义）。
+   */
+  mergeKey: string | undefined;
+}) | (FieldNodeBase & {
+  type: "tuple";
+  items: readonly FieldNode[];
+}) | (FieldNodeBase & {
+  type: "union";
+  /** 成员全是字面量时的可选项；否则 `undefined`。 */
+  choices: readonly unknown[] | undefined;
+  variants: readonly FieldNode[];
+  /**
+   * 判别标签：按哪个字段的值挑变体。显式声明优先
+   * （`z.union([...]).role('union', { tag: 'kind' })`），否则取所有对象成员共有的**唯一**常量字段。
+   * schemastery 本身没有 tag 机制（union 按声明顺序逐个试），所以这只是渲染与校验的选支依据。
+   */
+  tagKey: string | undefined;
+}) | (FieldNodeBase & {
+  type: "intersect";
+  members: readonly FieldNode[];
+}) | (FieldNodeBase & {
+  type: "bitset";
+  bits: readonly BitsEntry[];
+}) | (FieldNodeBase & {
+  type: "const";
+  value: unknown;
+}) | (FieldNodeBase & {
+  type: "lazy";
+  inner: FieldNode;
+}) | (FieldNodeBase & {
+  type: "string" | "number" | "boolean" | "any" | "never" | "function";
+}) |
+/** 自引用 schema 回到祖先处：值这一层以下不再描述，由渲染层展开或只读呈现。 */
+(FieldNodeBase & {
+  type: "recursive";
+  origin: string;
+});
+/**
+ * 投影一个 schema 节点。
+ * @param schema - rehydrate 之后的 volatile 表单 schema（或它的子节点）。
+ * @param path - 该节点相对段根的路径；动态子节点由调用方给占位段。
+ * @returns 渲染层要的字段树。
+ */
+declare function projectNode(schema: SchemaNode, path?: readonly string[]): FieldNode;
+/** 按当前值展开出的一个字段：路径与名字已按真实键与索引替换。 */
+interface WalkedField {
+  path: readonly string[];
+  node: FieldNode;
+  /**
+   * 这一行是某个动态容器的**成员本身**（dict 的键 / array 的项）时给出它的身份：容器路径、键、以及数组
+   * 项的位置。渲染层用它画成员行（名字 + 移除）；成员的子字段不带这个标记。
+   */
+  member?: {
+    parent: readonly string[];
+    key: string;
+    index: number | undefined;
+  };
+}
+/** 候选键的来源（业务注册；见 `hints.ts`）：dict 的「可以加哪些键」。 */
+interface SuggestedKeys {
+  /**
+   * 读某个 dict 字段的候选键。
+   * @param path - 该字段的具体路径。
+   * @returns 候选键；没有就是空数组。
+   */
+  keysFor(path: readonly string[]): readonly string[];
+}
+/**
+ * 按当前值把字段树展开成渲染顺序的扁平列表（前序）：容器在前、子项紧随其后。
+ *
+ * 出现的**只有值里有的东西，加上必填的**：对象的必填字段始终占行（值是空的也要让用户看见"必须填"），非必填的
+ * 按值出现——值里没有就不占行，它在这一层的「添加属性」候选里，选中才加。数组按索引、字典按键展开；字面量
+ * union 是叶子控件，对象 union 只展开与当前值匹配的那个变体，intersect 的各成员在同一层展开。
+ * @param root - 段根的字段树。
+ * @param value - 生效值（或草稿后的值）。
+ * @returns 渲染顺序的字段列表。
+ */
+declare function walkFields(root: FieldNode, value: unknown): WalkedField[];
+/** union 的变体切换：一个选项要写的值。 */
+interface VariantChoice {
+  /** 页面上显示的名字：判别标签的值，或变体的形状。 */
+  label: string;
+  /** 写这个值就等于选中这一支。 */
+  value: unknown;
+}
+//#endregion
+//#region src/client/schema-form/draft.d.ts
+/** 命名空间段（一段配置）的值。 */
+type Section = Record<string, unknown>;
+/** 文本草稿的解析结果：控件把用户输入交给保存那一刻解析。 */
+type TextParseResult =
+/** 得到一个值。 */
+{
+  kind: "value";
+  value: unknown;
+} |
+/** 这段文本不产生写（例如 secret 留空＝保留已存的值）。 */
+{
+  kind: "skip";
+} |
+/** 不是这个字段接受的值：留在屏幕上并挡住保存。 */
+{
+  kind: "invalid";
+  message: string;
+};
+/** 控件给文本草稿的解析规则。 */
+type TextParse = (text: string) => TextParseResult;
+/** 整段校验失败：消息 + 它落在哪一层（页面把消息画在**出错的那一行**上）。 */
+interface ValidationFailure {
+  /** 面向用户的消息（已去掉 schemastery 拼的 `$…` 位置前缀）。 */
+  message: string;
+  /** 具体路径（段根起）；空数组表示错误在整段上。 */
+  path: readonly string[];
+}
+/**
+ * 把校验器抛出的错误收成一条失败。
+ *
+ * schemastery 的 `ValidationError` 把路径留在 `options.path` 上（消息里的 `$…` 前缀是给命令行看的），所以这里
+ * 取路径、去前缀——行内报错据此知道挂在哪一行。
+ * @param error - 校验器抛出的错误。
+ * @returns 消息与路径。
+ */
+declare function failureOf(error: unknown): ValidationFailure;
+/** 一字段渲染时要读的状态。 */
+interface DraftFieldState {
+  /** 控件要显示的值：草稿优先，否则生效层。 */
+  value: unknown;
+  /** 文本草稿（文本控件显示它而不是重新格式化值）。 */
+  text: string | undefined;
+  /** 草稿不合法时的消息（控件显示，同时挡住保存）。 */
+  invalid: string | undefined;
+  /** 保存后这一字段是否会留下用户层条目。 */
+  overridden: boolean;
+  /** 这一字段在本页有还没保存的编辑（页面上给它一处高亮与一个「撤回」）。 */
+  staged: boolean;
+}
+/** 模型要读要写的那个命名空间。 */
+type DraftScope = ConfigForm<Section>;
+//#endregion
+//#region src/client/schema-form/hints.d.ts
+/** 一个 dict 字段的候选键读数。 */
+type SuggestedKeysReader = () => readonly string[];
+/** 一个字段的文案（业务知道的说法；schema 上没有 title 这种位）。 */
+interface FieldText {
+  /** 短名字（行式视图里当注释的抬头）。 */
+  label?: string | undefined;
+  /** 一句话说明。 */
+  hint?: string | undefined;
+}
+/** 一个字段的文案读数。 */
+type FieldTextReader = () => FieldText;
+/** 一个可选项：要写进去的值，以及页面上显示的名字。 */
+interface SelectOption {
+  /** 选中时写进配置的值。 */
+  value: unknown;
+  /** 显示名；省略就用值本身。 */
+  label?: string | undefined;
+}
+/** 一个字段的候选值读数。 */
+interface SelectSpec {
+  /**
+   * 候选依赖哪些**兄弟字段**（相对该字段所在对象的路径）。
+   *
+   * 依赖只声明"什么时候要重算"：读侧在投影时按当前读数（草稿优先）求一次候选，所以声明了依赖的字段会随着
+   * 兄弟字段的编辑立刻换候选——「选完服务商才列它有哪些模型」就是这么来的。
+   */
+  dependsOn?: readonly (readonly string[])[] | undefined;
+  /**
+   * 求候选。
+   * @param read - 按依赖路径（相对该字段所在对象）读当前值：草稿优先。
+   * @returns 可选项，顺序即页面上的顺序。
+   */
+  options: (read: (path: readonly string[]) => unknown) => readonly SelectOption[];
+}
+/** 一个命名空间里各字段的候选键、文案与候选值。 */
+interface SchemaFormHintsFace {
+  /**
+   * 注册一个 dict 字段的候选键读数（重复注册同一处会覆盖，并通知一次）。
+   * @param ns - settings 命名空间（行 id）。
+   * @param path - 该 dict 字段的具体路径（顶层字段就是 `['models']`）。
+   * @param read - 同步读数：当前候选键（顺序即页面上的顺序）。
+   * @returns 注销函数。
+   */
+  suggestKeys(ns: string, path: readonly string[], read: SuggestedKeysReader): () => void;
+  /**
+   * 读某处当前声明的候选键。
+   * @param ns - settings 命名空间。
+   * @param path - 该字段的路径。
+   * @returns 候选键；没注册过就是空数组。
+   */
+  keysFor(ns: string, path: readonly string[]): readonly string[];
+  /**
+   * 注册一个字段的文案（短名 + 一句话说明）。行式视图把它画成注释行；schema 的 `description` 是兜底。
+   * @param ns - settings 命名空间。
+   * @param path - 该字段的路径。
+   * @param read - 同步读数。
+   * @returns 注销函数。
+   */
+  describe(ns: string, path: readonly string[], read: FieldTextReader): () => void;
+  /**
+   * 读某处当前注册的文案。
+   * @param ns - settings 命名空间。
+   * @param path - 该字段的路径。
+   * @returns 文案；没注册过就是空对象。
+   */
+  textFor(ns: string, path: readonly string[]): FieldText;
+  /**
+   * 注册一个字段的候选值读数（页面据此把字段画成选择器，并随依赖字段变化重算）。
+   * @param ns - settings 命名空间。
+   * @param path - 该字段的路径。
+   * @param spec - 候选取法与它依赖的兄弟字段。
+   * @returns 注销函数。
+   */
+  select(ns: string, path: readonly string[], spec: SelectSpec): () => void;
+  /**
+   * 注册一个**具名候选源**：schema 上用 `role('select', { source })` 认领它，字段因此不必在客户端按 ns/path
+   * 登记——同一个源可以被多行、多个字段复用（「服务商」「模型」就是这种）。
+   * @param name - 源的名字（schema 的 `role` extra 里写的那一个）。
+   * @param spec - 候选取法与它依赖的兄弟字段。
+   * @returns 注销函数。
+   */
+  source(name: string, spec: SelectSpec): () => void;
+  /**
+   * 读一个具名候选源。
+   * @param name - 源的名字。
+   * @returns 该源的读数；没注册过就是 `undefined`。
+   */
+  sourceFor(name: string): SelectSpec | undefined;
+  /**
+   * 读某处当前声明的候选值读数。
+   * @param ns - settings 命名空间。
+   * @param path - 该字段的路径。
+   * @returns 候选读数；没注册过就是 `undefined`。
+   */
+  selectFor(ns: string, path: readonly string[]): SelectSpec | undefined;
+}
+/** 提示面的完整服务（业务用注册侧，表单一侧用读侧）。 */
+declare class SchemaFormHints extends Service implements SchemaFormHintsFace {
+  #private;
+  /** @param ctx - 提供本服务的插件上下文。 */
+  constructor(ctx: Context);
+  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处的键。 */
+  keysFor(ns: string, path: readonly string[]): readonly string[];
+  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处注册的文案。 */
+  textFor(ns: string, path: readonly string[]): FieldText;
+  /**
+   * @param ns - settings 命名空间。
+   * @param path - 字段路径。
+   * @param spec - 候选取法与依赖。
+   * @returns 注销函数。
+   */
+  select(ns: string, path: readonly string[], spec: SelectSpec): () => void;
+  /** @param ns - settings 命名空间。 @param path - 字段路径。 @returns 该处注册的候选读数。 */
+  selectFor(ns: string, path: readonly string[]): SelectSpec | undefined;
+  /**
+   * @param name - 源的名字。
+   * @param spec - 候选取法与依赖。
+   * @returns 注销函数。
+   */
+  source(name: string, spec: SelectSpec): () => void;
+  /** @param name - 源的名字。 @returns 该源注册的候选读数。 */
+  sourceFor(name: string): SelectSpec | undefined;
+  /**
+   * @param ns - settings 命名空间。
+   * @param path - 字段路径。
+   * @param read - 同步读数。
+   * @returns 注销函数。
+   */
+  describe(ns: string, path: readonly string[], read: FieldTextReader): () => void;
+  /**
+   * @param ns - settings 命名空间。
+   * @param path - 字段路径。
+   * @param read - 同步读数。
+   * @returns 注销函数。
+   */
+  suggestKeys(ns: string, path: readonly string[], read: SuggestedKeysReader): () => void;
+  /**
+   * 观察候选键的变化（注册与注销）。
+   * @param listener - 变更回调。
+   * @returns 取消订阅。
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * 重新通知一次：读数背后的数据变了（业务自己知道），页面据此重算候选行。
+   */
+  refresh(): void;
+}
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    /** 通用表单的提示面（dict 的候选键）。 */
+    schemaFormHints: SchemaFormHints;
+  }
+}
+//#endregion
+//#region src/client/schema-form/controller.d.ts
+/**
+ * rehydrate 一段配置 schema，并判它能不能当页面的根。
+ *
+ * 能当根的形状有三种：对象段、**相交段**（共享判别字段 + 各分支的 `const` 标记，段值仍是对象）、以及带判别
+ * 标签的 `union`（成员都是对象）。字面量 `union`（整段就是一个标量）不行：那一行的写盘会变成整段替换。
+ * @param serialized - host 发来的 `schema.toJSON()`。
+ * @param rehydrate - host schema 的 rehydrate。
+ * @returns schema 与它的字段树，或 `undefined`（不能当页面根）。
+ */
+declare function projectRoot(serialized: unknown, rehydrate: (serialized: unknown) => SchemaNode): {
+  schema: SchemaNode;
+  root: FieldNode;
+} | undefined;
+/**
+ * 一行能否自动生成配置页：它的 schema 能 rehydrate 且根是 {@link projectRoot} 认的形状。
+ * @param view - host 发来的命名空间视图。
+ * @param rehydrate - host schema 的 rehydrate。
+ * @returns 是否可以渲染。
+ */
+declare function canRender(view: SettingsNamespaceView | undefined, rehydrate: (serialized: unknown) => SchemaNode): boolean;
+/** 提示面在控制器里的读法：候选键 + 字段文案 + 候选值。 */
+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`。
+   */
+  sourceFor?: ((name: string) => SelectSpec | undefined) | undefined;
+}
+/** 控制器要的外部面（`apply` 里从 cordis ctx 组装；测试直接给替身）。 */
+interface SchemaFormDeps {
+  /** 本命名空间的共享配置表单（读 + 带栅栏的写）。 */
+  form: DraftScope;
+  /** describe mirror 的读面：本行的 schema、autoGenerate 与 secret 槽。 */
+  describe: SettingsDescribeFace;
+  /** rehydrate host 发来的 `schema.toJSON()`。 */
+  rehydrate: (serialized: unknown) => SchemaNode;
+  /** 整段校验；失败时连路径一起给（页面把消息画在那一行）。 */
+  validate: (schema: SchemaNode, value: unknown) => ValidationFailure | undefined;
+  /** 本包字典（项身份冲突这类本地校验的消息）。 */
+  t: SchemaFormTranslate;
+  /**
+   * dict 字段的候选键（业务注册，见 `hints.ts`）：候选里有、值里没有的键会补成一行「未配置」，
+   * 用户填了才算写。
+   */
+  hints?: HintSources | undefined;
+}
+/**
+ * 这一层「能加进来」的一项：schema 里声明、值里还没有的字段，或业务注册的候选键。
+ *
+ * 页面上不占行——它们出现在容器的闭合行那个「添加属性 / 添加键」输入框的候选里，选中才加。
+ */
+interface AddableProperty {
+  /** 加进来的键名。 */
+  key: string;
+  /** 说明（schema 的 `description` / `comment`，可能是本地化字典）：渲染层解析后当候选的副标题。 */
+  description: string | Readonly<Record<string, string>> | undefined;
+}
+/** 页面级状态：表单壳 + 字段树 + 每字段草稿状态。 */
+interface SchemaFormState extends SettingsFormShell$1 {
+  /** 这一行的 schema 是否可渲染（否则页面只显示一行说明）。 */
+  configured: boolean;
+  /** 字段树；未 configured 时是空对象树。 */
+  root: FieldNode;
+  /** 按草稿后的值展开的字段列表（渲染顺序）：追加的数组项与新增的字典键立刻出现。 */
+  walked: readonly WalkedField[];
+  /** 每个具体路径的草稿状态，键见 {@link fieldKey}。 */
+  fields: ReadonlyMap<string, DraftFieldState>;
+  /** secret 槽是否已配置，键见 {@link fieldKey}。 */
+  secrets: ReadonlyMap<string, boolean>;
+  /** 每个字段的文案（提示面注册的），键见 {@link fieldKey}；渲染层把它画成注释行。 */
+  texts: ReadonlyMap<string, FieldText>;
+  /**
+   * 每个字段的可选项，键见 {@link fieldKey}：字面量集合的 union 自带候选，其余来自提示面。
+   * 候选依赖的兄弟字段一改，这里就跟着变（投影时按草稿后的值求一次）。
+   */
+  options: ReadonlyMap<string, readonly SelectOption[]>;
+  /**
+   * 每个容器能加进来的项，键见 {@link fieldKey}（容器自己的路径）。没有条目就是加不了东西——对象层的输入框
+   * 因此只在还有声明字段没配时出现。
+   */
+  addable: ReadonlyMap<string, readonly AddableProperty[]>;
+  /** 保存被 schema 挡下时的消息与它的位置。 */
+  violation: ValidationFailure | undefined;
+  /** 每行的校验消息（键见 {@link fieldKey}）：行内报错，与底部的整段提示同源。 */
+  invalidAt: ReadonlyMap<string, string>;
+}
+/** 控件的写动作：全部落在草稿上，`save` 是唯一的写盘点。 */
+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;
+}
+/** 槽位渲染器绑定的动作与可观察状态。 */
+interface SchemaFormFace extends SchemaFormActions {
+  hooks: {
+    schemaForm: SnapshotStore<SchemaFormState>;
+  };
+}
+/**
+ * 一个字段的可选项。
+ *
+ * 字面量集合的 union（`z.union(["wal", "delete"])`）自己就带着候选；其余看提示面注册的读数——读的时候把依赖的
+ * 兄弟字段值喂进去，所以「选完服务商才列它有哪些模型」是投影的一部分，不是额外的一次订阅。
+ * @param node - 字段节点。
+ * @param path - 该字段的具体路径。
+ * @param value - 段值（草稿后的）。
+ * @param hints - 提示面。
+ * @returns 可选项；没有候选就是 `undefined`。
+ */
+declare function optionsFor(node: FieldNode, path: readonly string[], value: unknown, hints: HintSources | undefined): readonly SelectOption[] | undefined;
+/**
+ * 一行配置页的控制器。
+ */
+declare class SchemaFormController {
+  #private;
+  /**
+   * @param ns - settings 命名空间（行 id）。
+   * @param deps - 该行的共享表单与 schema 面。
+   */
+  constructor(ns: string, deps: SchemaFormDeps);
+  /** 槽位渲染器要的动作与状态。 */
+  face(): SchemaFormFace;
+  /** 本行的 settings 命名空间。 */
+  namespace(): string;
+  /** 外部提示（候选键这类）变了：重新投影一次，字段树与草稿都不动。 */
+  refresh(): void;
+  /** 释放订阅。 */
+  dispose(): void;
+}
+//#endregion
+//#region src/client/schema-form/labels.d.ts
+/** 把 schema 里的本地化文本解析成当前语言；由 locale 服务提供。 */
+type ResolveText = (text: string | Readonly<Record<string, string>>) => string;
+//#endregion
+//#region src/client/schema-form/locales.d.ts
+/**
+ * 本包字典（命名空间 `settings.schema-form`）：表单壳、字段控件与只读呈现的文案。
+ *
+ * 字段自身的人话标签不在这里（那是业务方经字段槽或 schema `description` 给的），这里只放**机制**文案。
+ */
+/** 中文文案（部署语言偏好是 zh）。 */
+declare const zh: {
+  readonly unavailable: "该插件当前未加载，暂时无法配置。";
+  readonly readOnly: "本部署的设置为只读。";
+  readonly save: "保存";
+  readonly confirmEdit: "确认";
+  readonly cancelEdit: "取消";
+  readonly saving: "保存中…";
+  readonly saveFailed: "本部署没有接受这些值，已保留供你修改。";
+  readonly notSaved: "没有保存：{message}";
+  readonly noSchema: "这一行没有可自动生成的配置项。";
+  readonly reset: "恢复默认";
+  readonly revert: "撤回";
+  readonly invalid: "这个值不被接受。";
+  readonly invalidNumber: "需要一个数字。";
+  readonly invalidInteger: "需要一个整数。";
+  readonly invalidJson: "需要一段合法的 JSON。";
+  readonly invalidBoolean: "需要 true 或 false。";
+  readonly invalidConst: "这个字段只接受固定值。";
+  readonly invalidPattern: "要匹配 {pattern}。";
+  readonly invalidRange: "要在 {min} 与 {max} 之间。";
+  readonly invalidMin: "不能小于 {min}。";
+  readonly invalidMax: "不能大于 {max}。";
+  readonly invalidChoice: "只能是 {choices} 之一。";
+  readonly unknownProperty: "这一层没有这个字段：从上面的候选里选，或换个键名。";
+  readonly empty: "（空）";
+  readonly toggleGroup: "展开 / 收起这一层";
+  readonly switchVariant: "切换这一层的形状或分支";
+  readonly copyValue: "复制值";
+  readonly copied: "已复制";
+  readonly addProperty: "添加属性";
+  readonly addItemPaste: "添加数组项（可粘贴 JSON 字符串）";
+  readonly addItem: "添加一项";
+  readonly removeItem: "移除";
+  readonly addKey: "添加键（可粘贴 JSON 字符串）";
+  readonly keyName: "键名";
+  readonly noKeys: "还没有键。";
+  readonly noItems: "还没有项。";
+  readonly deprecated: "已废弃";
+  readonly experimental: "试验中";
+  readonly secretSet: "已配置";
+  readonly secretUnset: "未配置";
+  readonly secretHint: "留空即保留已存的值。";
+  readonly constValue: "固定值";
+  readonly notEditable: "这一项由插件在运行时提供，不能在页面上编辑。";
+  readonly recursive: "递归结构：展开到这一层为止。";
+  readonly fixedLength: "固定长度";
+  readonly bitsetHint: "可多选。";
+  readonly unconfigured: "未配置";
+  readonly readOnlyField: "只读";
+  readonly noDescription: "（无说明）";
+  readonly required: "必填";
+  readonly duplicateItem: "重复的 {key}：{value}";
+  readonly missingItem: "每一项都需要一个 {key}";
+};
+/** 本命名空间的字典键。 */
+type SchemaFormLocaleKey = keyof typeof zh;
+//#endregion
+//#region src/client/schema-form/slot-contract.d.ts
+/** 字段槽的 owner props：路由输入 + 显示状态 + 受控动作（默认控件要的一切都在这里）。 */
+interface SchemaFieldOwnerProps {
+  /** settings 命名空间（行 id）。 */
+  ns: string;
+  /** 字段的具体路径（动态段已按真实键或索引替换）。 */
+  path: readonly string[];
+  /** 字段节点（类型、`role`、`extra`、界限、只读原因）。 */
+  node: FieldNode;
+  /** 显示标签：默认是字段名拆词，业务方经槽给时会覆盖。 */
+  label: string;
+  /** 显示说明（`description` 本地化 + `comment`）。 */
+  hint: string | undefined;
+  /** 当前生效值（草稿优先）。 */
+  value: unknown;
+  /**
+   * 这个字段的可选项：给了就是选择器（点值不再进文本编辑）。来源是字面量集合的 union，或业务经提示面注册的
+   * 候选——候选依赖的兄弟字段一变，这里就换一批。
+   */
+  options: readonly SelectOption[] | undefined;
+  /** 文本草稿：文本控件显示它，而不是重新格式化生效值。 */
+  text: string | undefined;
+  /** secret 槽是否已配置（值本身不回传）。 */
+  secretConfigured: boolean;
+  /** 嵌套深度：默认控件按它缩进。 */
+  depth: number;
+  /** 保存后这一字段是否会留下用户层条目。 */
+  overridden: boolean;
+  /** 草稿不合法时的消息。 */
+  invalid: string | undefined;
+  /** 只读部署或不可用命名空间时为 true。 */
+  disabled: boolean;
+  /** 本包字典（复刻或包装默认控件时用）。 */
+  t: SchemaFormTranslate;
+  /** 容器动作（增删数组项、字典键、丢弃、保存）。 */
+  actions: SchemaFormActions;
+  /**
+   * 分组节点的折叠交互（object / dict / array / tuple）；叶子节点是 `undefined`。
+   * 默认折叠与否由 schema 的 `collapse()` 决定，用户点一下就是反转。
+   */
+  group: {
+    collapsed: boolean;
+    toggle: () => void;
+  } | undefined;
+  /**
+   * 这一行是动态容器的成员本身（dict 的键 / array 的项）时的身份：容器路径、键、数组项的位置。容器成员把它画进
+   * 标题行（名字 + 移除），叶子成员由渲染层另起一行——所以「哪个字段属于哪个键/哪一项」在页面上一眼可见。
+   */
+  member: {
+    parent: readonly string[];
+    key: string;
+    index: number | undefined;
+    pending?: boolean;
+  } | undefined;
+  /** 暂存一个合法值。 */
+  onChange: (value: unknown) => void;
+  /**
+   * 暂存一段文本：按字段类型的默认规则解析；给了 `parse` 就用它（例如 secret 留空＝不写）。
+   * @param text - 用户输入。
+   * @param parse - 覆盖默认解析规则。
+   */
+  onEditText: (text: string, parse?: TextParse) => void;
+  /** 暂存「恢复默认」。 */
+  onReset: () => void;
+}
+/**
+ * 字段槽注册项的完整 props：框架注入的 owner props（{@link SchemaFieldOwnerProps}）＋它的 `select` 结果。
+ *
+ * 注册方的组件按这个类型声明参数（**不要**自己重写 owner props 的类型：注册时框架会把它读成 inject 面）。
+ */
+type SchemaFieldComponentProps<M extends SchemaFieldMatch = SchemaFieldMatch> = PropsRuntime<"settings.schema-form.field"> & {
+  matched: M;
+};
+/**
+ * 字段槽注册项的 `select`：返回认领结果，或 `null` 表示不认领（chain 槽的约定是 `null` 放行给下一项，
+ * `undefined` 不会被当成"不认领"）。
+ */
+type SchemaFieldSelect = (field: SchemaFieldOwnerProps) => SchemaFieldMatch | null;
+/** 字段槽 `select` 可以只给文案：控件仍由注册方渲染（拿本包的默认控件包一层即可）。 */
+interface SchemaFieldMatch {
+  /** 覆盖显示标签。 */
+  label?: string;
+  /** 覆盖显示说明。 */
+  hint?: string;
+}
+/** Factory 的输入 props：一行的配置页。 */
+interface SchemaFormProps {
+  /** settings 命名空间（行 id）。 */
+  ns: string;
+  /** 该行的控制器动作与状态。 */
+  face: SchemaFormFace;
+  /** schema 里的本地化文本（`description`）按当前语言解析。 */
+  resolveText: ResolveText;
+}
+/** 本包字典的翻译函数（默认控件与表单壳使用）。 */
+type SchemaFormTranslate = TranslateNS<"settings.schema-form">;
+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 给出。
+     */
+    "settings.schema-form.field": {
+      kind: "chain";
+      scope: "root";
+      owner: SchemaFieldOwnerProps;
+    };
+  }
+  interface SlotFactoryMap {
+    /**
+     * 一行配置页的渲染体：每个可渲染的行注册项经 `renderFactorySlot` 渲染同一个 Factory，字段槽因此只需声明
+     * 一次（slots 的 children 声明 per key 唯一）。
+     */
+    "settings.schema-form.form": {
+      scope: "root";
+      props: SchemaFormProps;
+      locale: "settings.schema-form";
+      children: {
+        "settings.schema-form.field": {
+          kind: "chain";
+          scope: "root";
+        };
+      };
+    };
+  }
+}
+//#endregion
+//#region src/client/schema-form/rows.d.ts
+/** 一个该自动长出配置页的行。 */
+interface RowRegistrationPlan {
+  /** `plugins.row.config` 的 key：`<bundle 包名>#<行 id>`。 */
+  key: string;
+  /** settings 命名空间（行 id）。 */
+  ns: string;
+}
+/**
+ * 配对命名空间与 bundle 行清单。
+ * @param namespaces - host 发来的命名空间视图。
+ * @param bundles - host 的 bundle 清单（含各 bundle 声明的行 id）。
+ * @returns 该自动注册的行，按命名空间视图的顺序。
+ */
+declare function rowRegistrations(namespaces: readonly SettingsNamespaceView[], bundles: readonly BundleInfo[]): RowRegistrationPlan[];
+//#endregion
+//#region src/client/schema-form/value.d.ts
+/** 编辑态文本：字符串就是原文（换行照旧），其余按 JSON 写。 */
+declare function valueText(value: unknown): string;
+/** 显示态文本：字符串带引号；多行与特殊字符都按 JSON 的写法收在一行里。 */
+declare function tokenText(value: unknown): string;
+/** 值的语法色分组。 */
+declare function tokenTone(value: unknown): "string" | "number" | "boolean" | "empty";
+/**
+ * 行内值的默认呈现（显示态 token）。
+ * @param props.owner - 字段上下文（值、是否 secret、只读原因）。
+ * @returns 一行里的值节点。
+ */
+declare function InlineValue({ owner }: {
+  owner: SchemaFieldOwnerProps;
+}): ReactNode;
+/**
+ * 字段槽注册方复用的默认值：只改文案时拿它包一层即可（`owner` 上覆盖 `label`/`hint`）。
+ *
+ * 注意行式视图里键名来自配置键本身、注释来自 `hint`，所以 `label` 只在业务自写控件时才需要。
+ */
+declare function SchemaFieldDefault({ owner }: {
+  owner: SchemaFieldOwnerProps;
+}): ReactNode;
+//#endregion
+//#region src/client/schema-form/fields.d.ts
+/**
+ * 各类型的文本解析规则（消息来自本包字典）。
+ *
+ * 解析不只看类型：schema 上声明的界限（`pattern` / `min` / `max` / `step`）与字面量集合都在这里说话——
+ * 用户敲完当场就知道对不对，而不是等保存时被整段校验退回。
+ * @param node - 字段节点（`meta` 是约束的来源）。
+ * @param t - 本包字典。
+ * @returns 这段文本的解析规则。
+ */
+declare function parseFor(node: FieldNode, t: SchemaFormTranslate): TextParse;
+//#endregion
+//#region src/client/schema-form/lines.d.ts
+/** 一个容器的闭合行后面能加什么。 */
+type AddLineSpec =
+/** 数组：追加一个空项。 */
+{
+  kind: "item";
+} |
+/** 字典：敲键名，或从候选键里选（业务注册的读数）。 */
+{
+  kind: "key";
+  options: readonly AddableProperty[];
+} |
+/** 对象：从「schema 声明了、值里还没有」的字段里选（没有候选项时不给输入框）。 */
+{
+  kind: "prop";
+  options: readonly AddableProperty[];
+};
+/** 一行上的变体切换控件。 */
+interface VariantControl {
+  /** 可以切到哪几支；顺序即声明顺序。 */
+  choices: readonly VariantChoice[];
+  /** 当前落在第几支。 */
+  selected: number;
+}
+/** 容器类型：结构行用 `{` 还是 `[`。 */
+type ContainerShape = "object" | "array";
+/** 一行。 */
+type EditorLine =
+/** 容器的开启行：`key: {` 或 `[`。 */
+{
+  kind: "open";
+  path: readonly string[];
+  node: FieldNode;
+  shape: ContainerShape;
+  depth: number;
+  collapsed: boolean;
+  member: WalkedField["member"];
+  /** 这一层是 union 时，可以在哪几支之间切（写哪个值）。 */
+  variants: VariantControl | undefined;
+} |
+/** 容器的关闭行：`}` / `]`（添加行挂在它后面同一行）。 */
+{
+  kind: "close";
+  path: readonly string[];
+  node: FieldNode;
+  shape: ContainerShape;
+  depth: number;
+  /** 这一层能加什么；`undefined` 表示加不了（对象的声明字段都配齐了）。 */
+  add: AddLineSpec | undefined;
+  member: WalkedField["member"];
+} |
+/** 字段行：`key: value`。 */
+{
+  kind: "field";
+  path: readonly string[];
+  node: FieldNode;
+  depth: number;
+  field: DraftFieldState;
+  member: WalkedField["member"];
+  /** 这个字段是 union 时，可以在哪几支之间切。 */
+  variants: VariantControl | undefined;
+  /**
+   * 变体触发**代替这一行的值**：判别式 union 的标签行就是这样——`type: "sqlite" ▾` 里的值就是那个触发，
+   * 不再另画一份值。
+   */
+  variantsStandIn: boolean;
+} |
+/** 注释行：schema 的说明与业务给的文案，画在字段行上方；这一行有问题时它装的是那条消息。 */
+{
+  kind: "comment";
+  path: readonly string[];
+  depth: number;
+  text: string;
+  /** 这一行有校验消息（草稿解析失败或整段校验落下来）：画成错误，而不是普通说明。 */
+  invalid: boolean;
+};
+/**
+ * 容器的形状：对象类用 `{}`，序列类用 `[]`。
+ *
+ * union 没有自己的形状——它跟着**当前选中那一支**走（`access` 是数组就在页面上画 `[`），这也是
+ * `access: string | string[]` 这类字段以前被画成对象容器的原因。
+ * @param node - 字段节点。
+ * @param value - 这一层的值（选支判据）。
+ * @returns 形状；叶子节点是 `undefined`。
+ */
+declare function containerShape(node: FieldNode, value?: unknown): ContainerShape | undefined;
+/** 折叠状态与可见性：记「用户切换过的路径」，开合 = 切换过就反转 schema 的默认值。 */
+interface FoldState {
+  collapsed(path: readonly string[]): boolean;
+  toggle(path: readonly string[]): void;
+}
+/** 渲染顺序里可见的字段：折叠的容器把整棵子树滤掉，只留它自己的开启行。 */
+declare function visibleFields(state: SchemaFormState, fold: FoldState): readonly WalkedField[];
+/**
+ * 排成行序列。
+ * @param state - 页面读数。
+ * @param fold - 折叠状态。
+ * @param resolveText - `description` 的本地化。
+ * @param t - 本包字典。
+ * @returns 行序列（行号即下标）。
+ */
+declare function editorLines(state: SchemaFormState, fold: FoldState, resolveText: ResolveText, t: SchemaFormTranslate): EditorLine[];
+declare namespace index_d_exports {
+  export { EditorLine, FieldMeta, FieldNode, FieldText, FoldState, InlineValue, NS, RowRegistrationPlan, SchemaFieldComponentProps, SchemaFieldDefault, SchemaFieldMatch, SchemaFieldOwnerProps, SchemaFieldSelect, SchemaFormActions, SchemaFormController, SchemaFormFace, SchemaFormHints, SchemaFormHintsFace, SchemaFormLocaleKey, SchemaFormProps, SchemaFormState, SelectOption, SelectSpec, SuggestedKeys, SuggestedKeysReader, ValidationFailure, WalkedField, apply$1 as apply, canRender, containerShape, editorLines, failureOf, inject$1 as inject, optionsFor, parseFor, projectNode, projectRoot, rowRegistrations, tokenText, tokenTone, valueText, visibleFields, walkFields };
+}
+/** 本包字典与槽位文案的命名空间。 */
+declare const NS = "settings.schema-form";
+/** 需要的服务：槽位、字典、共享配置表单、schema 服务与插件管理（bundle 行清单）。 */
+declare const inject$1: string[];
+/**
+ * 装上本包：字典、Factory（字段槽的声明者）与按行自动注册。
+ * @param ctx - 浏览器插件上下文。
+ */
+declare function apply$1(ctx: Context): void;
+//#endregion
 //#region src/reference-markdown.d.ts
 interface ReferenceActions {
   readonly openFile: (path: string) => void;
@@ -10925,7 +12266,16 @@ declare function referenceMentions(actions?: ReferenceActions, tokens?: Readonly
 declare const ReferenceMarkdown: import("react").MemoExoticComponent<({ text, labels, actions, streaming, pathImages }: ReferenceMarkdownProps) => import("react/jsx-runtime").JSX.Element>;
 //#endregion
 //#region src/client/index.d.ts
+/**
+ * 需要的**服务名**：样式与引用那半不要服务，schema 表单那半要槽位、字典与配置表单。
+ *
+ * 与包清单里的 `dsh.client.inject` 不是一回事：那份是**装配行 id**（谁先到），交给模块系统排 arrival 顺序；
+ * 这里读的是 cordis 服务名（谁已 provide），Loader 拿它决定这一行何时才算 active。写错成包名，这一行就永远
+ * pending（`web boot: ... waiting for services`）。
+ *
+ * 值直接取自 schema 表单那一面，不另抄一份清单。
+ */
 declare const inject: readonly string[];
-declare function apply(_ctx: Context): void;
+declare function apply(ctx: Context): void;
 //#endregion
-export { type CSSObject, type CSSProps, type CSSSelector, type CSSValue, type CSSVar, type CSSVarRef, MarkdownCopySeat, type Reference, type ReferenceActions, ReferenceMarkdown, type ReferenceMarkdownProps, type ReferenceSpan, type StyledComponent, Styling, Token, type TokenVars, type Tokens, apply, designTokens, dsw, findReferences, formatReference, formatReferenceMention, inject, isLocalReference, markdownLabels, parseReference, parseReferenceToken, referenceMentions, styleOf, styled, styling };
+export { type CSSObject, type CSSProps, type CSSSelector, type CSSValue, type CSSVar, type CSSVarRef, type FieldMeta, type FieldNode, MarkdownCopySeat, type Reference, type ReferenceActions, ReferenceMarkdown, type ReferenceMarkdownProps, type ReferenceSpan, NS as SCHEMA_FORM_NS, type SchemaFormActions, SchemaFormController, type SchemaFormFace, SchemaFormHints, type SchemaFormLocaleKey, type SchemaFormState, type SelectOption, type SelectSpec, type SettingsFieldProps, type SettingsFieldSpec, type SettingsFieldState, type SettingsFieldWrite, SettingsForm, type SettingsFormActions, type SettingsFormLabels, SettingsFormModel, type SettingsFormPathOp, type SettingsFormProps, type SettingsFormScope, type SettingsFormScopeSnapshot, type SettingsFormShell, SettingsSecretField, type SettingsSecretSpec, SettingsValueField, type StyledComponent, Styling, type SuggestedKeys, Token, type TokenVars, type Tokens, type ValidationFailure, type WalkedField, apply, designTokens, dsw, failureOf, findReferences, formatReference, formatReferenceMention, inject, isLocalReference, markdownLabels, parseReference, parseReferenceToken, projectRoot, referenceMentions, rowRegistrations, index_d_exports as schemaForm, settingsNumberField, settingsTextField, styleOf, styled, styling, walkFields };