/** * Form model behind the plugin settings card. Every control applies itself: * a pick (a segment, a select option, a reset) writes the moment it is made, * and typed text writes once typing pauses or the reader leaves the field. * Between the edit and the write the edit is held here as a draft, so what is * on screen is exactly what the write will store; a write the Host refuses * puts a pick back to the stored value and keeps typed text for correcting. * Family-shared slice inlined into each plugin's client bundle. */ import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'; import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'; /** The write one field's draft text performs when it is applied. */ export type FieldWrite = { kind: 'set'; value: unknown; } | { kind: 'clear'; }; /** How one field converts between its stored value and its draft text. */ export interface FieldSpec { /** Field name inside the namespace section. */ field: string; /** * How the reader enters a value, which decides when it is written: a `pick` * is a whole value at once and applies immediately; `type` is text arriving * a keystroke at a time and applies once typing pauses or the field is left. */ entry: 'pick' | 'type'; /** * Whether the Host treats this field as a secret and redacts its value from * the read-back (role('secret') in the section schema). Redacted secrets are * never compared against the draft on save: the Host strips them from every * wire view layer, so the settled snapshot carries nothing to read back. A * staged secret set is judged by the mutation settling; the rest of its * batch, when one exists, is still judged by read-back, and the atomic * mutation lands every write or none. */ secret?: boolean; /** Render a stored value as draft text; the empty string when the section carries none. */ format: (value: unknown) => string; /** * The write this draft text performs, or undefined when the text is not a * value this field accepts — which holds the draft unwritten rather than * discarding it. */ parse: (text: string) => FieldWrite | undefined; } /** One field as the card renders it. */ export interface FieldState { /** Draft text the control renders. */ text: string; /** Whether the field leaves (or will leave) a user-layer entry. */ overridden: boolean; /** Whether the draft is not a value this field accepts, which holds it unwritten. */ invalid: boolean; } /** Form state every plugin settings card shares. */ export interface CardShell { /** False while the namespace is still loading; the card renders nothing. */ available: boolean; /** * Whether the namespace is actually served to this client. False when the * Host deployment does not expose it (e.g. the owning plugin's settings * domain is not mounted): the card renders an explanation * instead of its form, so a missing namespace never looks like a missing * plugin. */ exposed: boolean; /** Whether the Host document accepts writes. */ writable: boolean; /** Whether the form holds drafts not yet written (typed text waiting for its pause). */ dirty: boolean; /** Whether any draft is invalid, which holds it unwritten. */ invalid: boolean; /** Whether a write is crossing the wire. */ saving: boolean; /** Whether the last write did not land; cleared by the next edit or write. */ failed: boolean; /** * The rejection code/message the Host returned for the last failed save, * surfaced next to the generic failure text. Undefined while no save has * failed (or the failure carried no server reason). */ failedReason?: string; } /** The write actions the card's slot entry injects. */ export interface CardActions { /** Take draft text for one field; a pick writes at once, typed text after a pause. */ edit: (field: string, text: string) => void; /** Clear one field at once, so it re-inherits the composition layer. */ resetField: (field: string) => void; /** Write every pending draft now (a text field's Enter or blur), then re-seed from what the Host accepted. */ save: () => void; /** Drop every pending draft, putting each control back to the stored value (a text field's Escape). */ discard: () => void; } /** How long typed text rests before it is written. */ export declare const TYPE_PAUSE_MS = 600; /** One durable write inside the save's atomic form mutation. */ export interface BatchedWrite { /** Field this entry writes. */ field: string; /** set stores a value; unset drops the leaf. */ op: 'set' | 'unset'; /** Value for op set (absent for unset). */ value?: unknown; } /** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */ export interface NumberConstraints { /** The accepted value must be a whole number. */ integer?: boolean; /** The accepted value must be at least this. */ min?: number; } /** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints stays unwritten. */ export declare function numberField(field: string, constraints?: NumberConstraints): FieldSpec; /** * A free-text field. An empty draft clears the field. `entry` is `pick` when * the text arrives whole from a picker (a preset or a reasoning level). */ export declare function textField(field: string, entry?: FieldSpec['entry']): FieldSpec; /** * A free-text field the Host treats as a secret and redacts from the read-back * (role('secret') in the section schema). The card still edits it like text, * but a save never compares the redacted value back: the staged set is judged * by the mutation settling (see {@link FieldSpec.secret}). */ export declare function secretField(field: string): FieldSpec; /** A boolean field, edited through true/false draft text. */ export declare function booleanField(field: string): FieldSpec; /** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */ export declare function choiceField(field: string, choices: readonly string[]): FieldSpec; /** * Applies one card's edits to one settings namespace as the reader makes them. * * 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 write that did not * land puts each pick back to the stored value, the way a switch that could not * flip springs back, and keeps typed text so the reader can correct it instead * of retyping. */ export declare class CardForm { private readonly scope; private readonly specs; private readonly staged; private readonly listeners; /** The form subscription installed in the constructor; released by dispose(). */ private readonly disposeForm; private disposed; /** The pending write of typed text, waiting for typing to pause. */ private typePause; private saving; /** A save asked for while one was in flight; it runs once the first settles (#1754). */ private saveQueued; private failed; private failedReason; /** @param scope - the bound configuration form for this card's namespace. */ constructor(scope: ConfigForm, specs: FieldSpec[]); /** * Release the form subscription and every bound store listener. The card * must call this on teardown; later calls are no-ops. */ dispose(): void; /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */ bind(project: () => S): SnapshotStore; /** Read the card-level state: what the Host serves, and what is still waiting to be written. */ shell(): CardShell; /** Read one field's state from the effective section and its staged draft. */ field(field: string): FieldState; /** The actions the card's slot registration injects. */ actions(): CardActions; /** * Run one write, and re-run it once if another was asked for while this one * was still in flight. * * A write is a Host round trip that also drives the profile reconcile, and * the Host runs it inside one exclusive transaction. Answering an edit that * arrives mid-flight by returning immediately dropped it with no explanation * (#1754). Serializing instead means an edit made while another write is * still settling is written against the settled state. * @returns settlement after the mutation and the read-back. */ requestSave(): Promise; /** * Write every valid draft in one atomic form mutation, then re-seed from * what the Host accepted. A draft the field does not accept stays on screen, * unwritten, without holding the others back. * * The batch rides one mutate, so cross-field validate hooks (baseURL+model) * judge it as a unit: the Host either applies every write or refuses the * batch. The form contract answers a refusal or a skipped write with `false` * (it recovers with a fresh Host view instead of throwing), so the outcome is * judged twice: the answer itself, and then the settled snapshot read back * one planned write at a time. One missed write fails the whole batch. A * transport that rejects instead (the dsh-web bridge controller on a dead * connection) reports through the same failure path with its rejection * message. A batch that did not land puts its picks and clears back to the * stored value and keeps its typed text, so the reader can correct it. * @returns settlement after the mutation and the read-back. */ save(): Promise; /** * Every staged edit a write would carry. An entry whose draft is not a value * its field accepts carries no write: the form is still dirty, and the draft * stays on screen rather than being dropped. A staged edit that matches the * effective section is not a write at all. * @returns the planned writes, in the order the fields were staged. */ private plan; /** * Read-back judgment for a planned set: the user layer must hold the * intended value once the mutation has settled. */ private landedSet; /** * Read-back judgment for a planned unset: the field must be gone from the * user layer once the mutation has settled. */ private landedUnset; /** * Take one edit and schedule its write: a pick or a clear is written now, * typed text once typing has rested for TYPE_PAUSE_MS. */ private stage; /** Write every pending draft now, taking the place of a waiting pause. */ private applyNow; private specOf; private snapshotOf; private sectionValue; private baseValue; private userLayer; private stored; private publish; }