@x1a0f3n9/dsh-client-ui-settings-models 0.1.5-rc.3

package/lib/types/client/locales.d.ts

@@ -0,0 +1,125 @@
+/** Copy dictionaries for the Models settings section. */
+/** English strings (the key-set source of truth for this pair). */
+export declare const en: {
+    nav: string;
+    title: string;
+    intro: string;
+    edit: string;
+    editProvider: string;
+    remove: string;
+    removeProvider: string;
+    deleteTitle: string;
+    deleteDescription: string;
+    deleteDescriptionWithCredential: string;
+    deleteConfirm: string;
+    deleting: string;
+    add: string;
+    provider: string;
+    close: string;
+    cancel: string;
+    apply: string;
+    applying: string;
+    savedProvider: string;
+    credentialConfigured: string;
+    credentialMissing: string;
+    readOnly: string;
+    loadFailed: string;
+    conflict: string;
+    retry: string;
+    keyInput: string;
+    keyPlaceholder: string;
+    keyPlaceholderNative: string;
+    keyStored: string;
+    keyEnvLocked: string;
+    customized: string;
+    baseUrl: string;
+    baseUrlDefault: string;
+    models: string;
+    modelsInherited: string;
+    modelsCustomized: string;
+    resetModels: string;
+    model: string;
+    modelId: string;
+    modelName: string;
+    modelNamePlaceholder: string;
+    contextWindow: string;
+    contextWindowPlaceholder: string;
+    maxTokens: string;
+    maxTokensPlaceholder: string;
+    modelAdvanced: string;
+    modelSupportsImages: string;
+    addModel: string;
+    removeModel: string;
+    modelsEmpty: string;
+    keyBlank: string;
+    keyBlankNew: string;
+    keyIllegalCharacters: string;
+    modelIdRequired: string;
+    modelIdDuplicate: string;
+    modelNameInvalid: string;
+    modelContextInvalid: string;
+    modelMaxTokensInvalid: string;
+    reasoningEffort: string;
+    reasoningEffortNone: string;
+    reasoningEffortCustom: string;
+    reasoningEffortWire: string;
+    retryPolicy: string;
+    retryPolicyNone: string;
+    retryPolicyCustom: string;
+    retryMaxRetries: string;
+    retryInitialDelay: string;
+    retryCountInvalid: string;
+    retryDelayInvalid: string;
+    modelReasoningEmpty: string;
+    modelReasoningWireRequired: string;
+    advancedHint: string;
+    modelCapacityInvalid: string;
+    modelDuplicate: string;
+    modelContextWindow: string;
+    modelMaxTokens: string;
+    fetchModels: string;
+    fetching: string;
+    fetchNeedsBaseUrl: string;
+    fetchEmpty: string;
+    fetchTitle: string;
+    fetchDescription: string;
+    fetchSearch: string;
+    fetchNoMatches: string;
+    fetchSelectAll: string;
+    fetchDeselectAll: string;
+    fetchAdopt: string;
+    customAdd: string;
+    customTitle: string;
+    customTag: string;
+    customRoute: string;
+    customRouteHint: string;
+    customRouteInvalid: string;
+    customRouteTaken: string;
+    customDisplayName: string;
+    customApi: string;
+    customApiUnset: string;
+    customNeedsBaseUrl: string;
+    customBaseUrlInvalid: string;
+    customNeedsModels: string;
+    customBaseUrlPlaceholder: string;
+    settingsPathUnresolvable: string;
+    create: string;
+    creating: string;
+    welcomeTitle: string;
+    welcomeBody: string;
+    welcomeContinue: string;
+    welcomeError: string;
+    onboardingTitle: string;
+    onboardingDescription: string;
+    onboardingLater: string;
+    onboardingSave: string;
+    onboardingSaving: string;
+    keyRequired: string;
+};
+/** The settings.models namespace key union. */
+export type ModelsKey = keyof typeof en;
+/** Chinese strings (same keys as {@link en}). */
+export declare const zh: {
+    [Key in keyof typeof en]: string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/operations.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The Host reads and writes the Models cards perform, as callbacks built in the
+ * plugin body. Cards receive these instead of a context: the outcomes name what
+ * a card renders — a stored view, a stale revision, a refusal message — so the
+ * failure codes and Remote namespaces stay in the apply world.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { CredentialInfo, LlmDiscoveredModel, LlmModelDiscoveryRequest, SettingsNamespaceView, SettingsPathOpView } from '@x1a0f3n9/dsh-api-remotes/client';
+/** What one namespace write answered. */
+export type SettingsWriteOutcome = 
+/** Committed; the view carries the stored user subtree and the new revision. */
+{
+    readonly kind: 'written';
+    readonly view: SettingsNamespaceView;
+}
+/**
+ * The stored revision moved after the card read it, so the draft is stale.
+ * The message stays for callers that report the Host diagnostic as it is.
+ */
+ | {
+    readonly kind: 'conflict';
+    readonly message: string;
+}
+/** Any other refusal, with the Host's own diagnostic. */
+ | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+/** What one endpoint interrogation answered. */
+export type ModelDiscoveryOutcome = 
+/** The candidates the provider disclosed, in its own order. */
+{
+    readonly kind: 'found';
+    readonly models: readonly LlmDiscoveredModel[];
+}
+/** The interrogation was refused, with the Host's own diagnostic. */
+ | {
+    readonly kind: 'refused';
+    readonly message: string;
+};
+/** The Host operations the Models page and its cards invoke. */
+export interface ModelsOperations {
+    /**
+     * Read one credential reference's state.
+     * @param ref - credential reference name.
+     * @returns the state, or undefined when the reference is unknown or the read was refused.
+     */
+    describeCredential(ref: string): Promise<CredentialInfo | undefined>;
+    /**
+     * Store one credential literal under its reference.
+     * @param ref - credential reference name.
+     * @param value - the literal to store.
+     * @returns the refusal message, or undefined once stored.
+     */
+    storeCredential(ref: string, value: string): Promise<string | undefined>;
+    /**
+     * Remove one credential reference (idempotent).
+     * @param ref - credential reference name.
+     * @returns the refusal message, or undefined once removed.
+     */
+    removeCredential(ref: string): Promise<string | undefined>;
+    /**
+     * Apply path operations to one settings namespace.
+     * @param ns - settings namespace identity.
+     * @param ops - ordered path operations against the stored section, as the
+     * wire takes them (the Remote signature owns the array).
+     * @param expectedRevision - revision the draft was opened at, or undefined to write unfenced.
+     * @returns the write outcome the card renders from.
+     */
+    writeSettings(ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined): Promise<SettingsWriteOutcome>;
+    /**
+     * Ask a provider endpoint what models it serves.
+     * @param settingsNs - namespace whose adapter family answers.
+     * @param request - endpoint facts as the form currently shows them.
+     * @returns the candidates, or the refusal.
+     */
+    discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest): Promise<ModelDiscoveryOutcome>;
+}
+/**
+ * Bind the page's Host operations to the plugin's own Remote namespaces.
+ * @param ctx - the page plugin's context, which declares `remote.credentials`,
+ * `remote.llm`, and `remote.settings` in its own `inject`.
+ * @returns the callbacks the section and its cards are injected with.
+ */
+export declare function createModelsOperations(ctx: ClientContext): ModelsOperations;
+//# sourceMappingURL=operations.d.ts.map

package/lib/types/client/reasoning-efforts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-model reasoning-effort maps edited on the custom-provider Models card.
+ *
+ * Level names match `llm-pi-ai`'s thinking-level vocabulary. The client package
+ * does not import that adapter: a host-side catalog change still has to name
+ * the same keys here before the card can offer them.
+ */
+/** Every thinking level the Models card can declare, in escalation order. */
+export declare const REASONING_EFFORT_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** One thinking level the Models card can declare. */
+export type ReasoningEffortLevel = (typeof REASONING_EFFORT_LEVELS)[number];
+/** Declared levels and the spellings dispatch sends on the wire. */
+export type ReasoningEffortsMap = Partial<Record<ReasoningEffortLevel, string | null>>;
+/**
+ * Read a stored `reasoningEfforts` object, or `undefined` when the model uses
+ * the default of no selectable levels.
+ * @param value - a model draft's `reasoningEfforts` field.
+ * @returns the declared map, or `undefined` for absent / disabled / empty.
+ */
+export declare function reasoningEffortsMap(value: unknown): ReasoningEffortsMap | undefined;
+/**
+ * Whether a stored field is a custom declaration the radio should select.
+ * @param value - a model draft's `reasoningEfforts` field.
+ * @returns true when the field carries at least one known level.
+ */
+export declare function hasCustomReasoningEfforts(value: unknown): boolean;
+/**
+ * Adapter refusals for a custom `reasoningEfforts` map that schema cannot name
+ * by row. Absent and `false` are the default of no levels.
+ * @param value - a model draft's `reasoningEfforts` field.
+ * @returns the failure key, or `undefined` when the adapter will accept it.
+ */
+export declare function validateReasoningEfforts(value: unknown): 'modelReasoningEmpty' | 'modelReasoningWireRequired' | undefined;
+//# sourceMappingURL=reasoning-efforts.d.ts.map

package/lib/types/client/retry-policy-fields.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Default / Custom retry count and delay on a Models provider card.
+ *
+ * Retry is a provider-route policy, unlike reasoning effort which is per model.
+ * Default omits `retryPolicy`; Custom writes normal mode with a count and delay.
+ */
+import type { ReactNode } from 'react';
+import type { en } from './locales.ts';
+/** Props of {@link RetryPolicyFields}. */
+export interface RetryPolicyFieldsProps {
+    /** Stored `retryPolicy`, or `undefined` for adapter defaults. */
+    value: unknown;
+    /** Write a custom draft, or `undefined` to restore adapter defaults. */
+    onChange: (next: unknown) => void;
+    /** Section copy. */
+    t: (key: keyof typeof en) => string;
+    /** Disable the radios and fields. */
+    disabled: boolean;
+    /** Radio `name` unique to this provider card. */
+    name: string;
+}
+/**
+ * Render the provider-level retry radios and, when Custom is selected, the
+ * count and delay fields.
+ * @param props - stored policy, writer, copy, and disabled state.
+ * @returns the fieldset.
+ */
+export declare function RetryPolicyFields(props: RetryPolicyFieldsProps): ReactNode;
+//# sourceMappingURL=retry-policy-fields.d.ts.map

package/lib/types/client/retry-policy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Provider-owned request-retry drafts edited on the Models settings cards.
+ *
+ * Omission uses the adapter defaults (twenty retries, 500 ms to 10 s). A stored
+ * object is a custom normal-mode policy with a retry count and delay.
+ */
+/** Adapter default for eligible retries after the first request. */
+export declare const DEFAULT_RETRY_MAX_RETRIES = 20;
+/** Adapter default for the first local backoff delay, in milliseconds. */
+export declare const DEFAULT_RETRY_INITIAL_DELAY_MS = 500;
+/** Adapter default for the longest local or accepted provider delay, in milliseconds. */
+export declare const DEFAULT_RETRY_MAX_DELAY_MS = 10000;
+/** Custom normal-mode policy the Models cards write. */
+export type RetryPolicyDraft = {
+    readonly mode: 'normal';
+    readonly maxRetries: number;
+    readonly backoff: {
+        readonly initialDelayMs: number;
+        readonly maxDelayMs: number;
+    };
+};
+/** Locale keys `validateRetryPolicy` can return. */
+export type RetryPolicyFailure = 'retryCountInvalid' | 'retryDelayInvalid';
+/**
+ * The adapter-default policy the Custom radio materializes so Apply is valid.
+ * @returns a normal-mode draft matching omitted `retryPolicy`.
+ */
+export declare function defaultRetryPolicy(): RetryPolicyDraft;
+/**
+ * Whether a stored field is a custom policy the radio should select.
+ * @param value - a provider draft's `retryPolicy` field.
+ * @returns true when the field is a non-array object.
+ */
+export declare function hasCustomRetryPolicy(value: unknown): boolean;
+/**
+ * Read a stored `retryPolicy` object into the card's normal-mode draft.
+ * @param value - a provider draft's `retryPolicy` field.
+ * @returns the draft, or `undefined` when the field is absent / not an object.
+ */
+export declare function retryPolicyDraft(value: unknown): RetryPolicyDraft | undefined;
+/**
+ * Build the object the cards store for one pair of count and delay fields.
+ * @param maxRetries - parsed retry count, or `undefined` when the field is blank / illegal.
+ * @param initialDelayMs - parsed initial delay, or `undefined` when the field is blank / illegal.
+ * @returns a complete draft, or a marker object the validator refuses.
+ */
+export declare function retryPolicyFromFields(maxRetries: number | undefined, initialDelayMs: number | undefined): unknown;
+/**
+ * Parse one retry-count field.
+ * @param value - the input's current text or stored number.
+ * @returns the count, or `undefined` when it is not a non-negative safe integer.
+ */
+export declare function parseRetryCount(value: unknown): number | undefined;
+/**
+ * Parse one retry-delay field.
+ * @param value - the input's current text or stored number.
+ * @returns milliseconds, or `undefined` when it is not a positive finite delay.
+ */
+export declare function parseRetryDelay(value: unknown): number | undefined;
+/**
+ * Adapter refusals for a custom `retryPolicy` the cards are about to write.
+ * Absent is the default of adapter policy. A custom object must name a count
+ * and a positive delay.
+ * @param value - a provider draft's `retryPolicy` field.
+ * @returns the failure key, or `undefined` when the adapter will accept it.
+ */
+export declare function validateRetryPolicy(value: unknown): RetryPolicyFailure | undefined;
+//# sourceMappingURL=retry-policy.d.ts.map

package/lib/types/client/schema-operations.d.ts

@@ -0,0 +1,10 @@
+import type { SettingsSchemaService } from '@x1a0f3n9/dsh-client-ui-settings/client';
+/** Plain schema callbacks exposed to Models stores and presentation components. */
+export type SettingsSchemaOperations = Pick<SettingsSchemaService, 'rehydrate' | 'validate' | 'nodeAtPath' | 'getPath' | 'hasPath' | 'setPath' | 'deletePath'>;
+/**
+ * Hide the Cordis service identity behind bound schema callbacks.
+ * @param service - settings-owned schema service available in the apply context.
+ * @returns callbacks that cannot expose the service context to React components.
+ */
+export declare function createSettingsSchemaOperations(service: SettingsSchemaService): SettingsSchemaOperations;
+//# sourceMappingURL=schema-operations.d.ts.map

package/lib/types/client/slot-contract.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Models-page extension slots — the two seats through which a plugin
+ * distributed outside this repository adds UI to the Models settings section
+ * without editing it.
+ *
+ * `settings.models.provider-card` is keyed by the row's owning settings
+ * namespace (`ProviderDirectoryEntry.settingsNs`): an adapter family's
+ * companion plugin registers one entry under the family's namespace and
+ * receives every card of that family — shipped, added, and hand-declared rows
+ * alike — while the section never learns what the namespace means. Keying on
+ * the namespace follows `settings.plugin.item`, and the key domain stays the
+ * open string space because hand-declared route ids are user-chosen at
+ * runtime.
+ *
+ * TYPE HOME RATIONALE: the Models section declares these slots at runtime,
+ * and a plugin registering an extension already depends on this package for
+ * the declaration. The types therefore live with their declarer.
+ */
+import type { ProviderDirectoryEntry } from './store.ts';
+declare module '@x1a0f3n9/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * One provider card's adapter extension area, dispatched with
+         * `entryKey = settingsNs` on every card that renders a directory row: a
+         * saved row's card (its first-run setup posture included) and the
+         * add-provider draft card. The hand-declared draft card has no directory
+         * row yet, so it dispatches nothing until saved. Without a registrant the
+         * area renders nothing.
+         */
+        'settings.models.provider-card': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: ProviderCardExtrasOwnerProps;
+        };
+        /**
+         * Ordered extension area after the provider rows and the add controls.
+         * Without a registrant the area renders nothing.
+         */
+        'settings.models.footer': {
+            kind: 'list';
+            scope: 'root';
+            owner: ModelsFooterOwnerProps;
+        };
+    }
+}
+/** Owner share of one provider-card extension occurrence. */
+export interface ProviderCardExtrasOwnerProps {
+    /** The card's directory row (route id, display name, settings address, live state). */
+    provider: ProviderDirectoryEntry;
+    /** Whether any layer configures this provider (its profile resolves); `false` while the add-provider draft edits a dormant row. */
+    configured: boolean;
+    /** Whether the row's referenced api-key credential is confirmed configured (the page's credential join). */
+    keyConfigured: boolean;
+}
+/** Owner share of the footer area (the section supplies nothing). */
+export interface ModelsFooterOwnerProps {
+    /** Marker field: footer owner props are intentionally empty. */
+    children?: never;
+}
+//# sourceMappingURL=slot-contract.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Models settings page store: one snapshot joining the configurable-provider
+ * directory (`llm/listProviders` joined with `llm/listConfigurableProviders`),
+ * the settings namespaces (shared settings mirror),
+ * and the referenced credentials (`credentials/describe`). The host stays the
+ * single fact source — every mutation writes through the wire and the page
+ * re-renders from the next describe, pushed or refetched.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { CredentialInfo, LlmConfigurableProvider, LlmProviderInfo, SettingsNamespaceView } from '@x1a0f3n9/dsh-api-remotes/client';
+import type { SnapshotStore } from '@x1a0f3n9/dsh-client-store';
+import type { SettingsDescribeFace } from '@x1a0f3n9/dsh-client-ui-settings/client';
+import type { SettingsSchemaOperations } from './schema-operations.ts';
+/** One provider row after joining the configurable directory with live routes. */
+export interface ProviderDirectoryEntry {
+    readonly provider: string;
+    readonly displayName: string;
+    readonly settingsNs: string;
+    readonly settingsPath: readonly string[];
+    readonly active: boolean;
+    readonly declared?: boolean;
+    readonly error?: string;
+}
+/**
+ * Join declared configurable providers with the currently registered routes.
+ * @param registered - live provider routes in registration order.
+ * @param directory - declared configurable providers in declaration order.
+ * @returns declared rows followed by live routes with no declaration.
+ */
+export declare function joinProviderDirectory(registered: readonly LlmProviderInfo[], directory: readonly LlmConfigurableProvider[]): ProviderDirectoryEntry[];
+/** One provider row the page renders. */
+export interface ProviderRow {
+    /** The directory entry (route id, display name, settings address, live state). */
+    entry: ProviderDirectoryEntry;
+    /** Whether any layer configures this provider (its profile resolves). */
+    configured: boolean;
+    /** Whether the user layer alone carries the profile (removal restores the base). */
+    removable: boolean;
+    /** The credential reference the resolved profile names, when one does. */
+    apiKeyEnv: string | undefined;
+    /** Credential state for {@link apiKeyEnv}, once described. */
+    credential: CredentialInfo | undefined;
+    /**
+     * Credential state for the page's derived `<ROUTE>_API_KEY`, described only
+     * while the profile names no reference — the provider-card seat's
+     * `keyConfigured` fact for dormant and keyless rows, matching the editor's
+     * own derivation rule.
+     */
+    derivedCredential?: CredentialInfo;
+}
+/** Page snapshot. */
+export interface ModelsSettingsState {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    /** Whole-load failure text; row-level write failures stay in the editor. */
+    error: string | null;
+    /** Credential enrichment failure; provider/settings rows remain usable. */
+    credentialError: string | null;
+    /** Whether the settings provider accepts writes. */
+    writable: boolean;
+    /** Every configurable provider joined with its configured/credential state. */
+    rows: readonly ProviderRow[];
+    /** Namespace views by ns, for the editor's schema/layers/secrets. */
+    namespaces: ReadonlyMap<string, SettingsNamespaceView>;
+}
+/**
+ * Derive the conventional credential reference for a provider route: the v1
+ * page never asks for an environment-variable name, so a typed key stores
+ * under this derived reference and the profile records it as `apiKeyEnv`.
+ * @param provider - provider route id (e.g. `anthropic`, `minimax-cn`).
+ * @returns the derived reference name (e.g. `MINIMAX_CN_API_KEY`).
+ */
+export declare function deriveKeyRef(provider: string): string;
+/**
+ * The wire protocols a hand-declared route may name, read out of the owning
+ * namespace's own schema. This stays a schema read rather than a wire field so
+ * the choices the page offers cannot drift from the ones the adapter accepts:
+ * both come from the same `Config`.
+ * @param namespace - the namespace view whose schema declares the profile shape.
+ * @param schema - settings schema operations.
+ * @returns the protocol identifiers, or an empty list when the schema has none.
+ */
+export declare function protocolChoices(namespace: SettingsNamespaceView | undefined, schema: SettingsSchemaOperations): string[];
+/** The models settings page controller (one per settings surface). */
+export declare class ModelsSettingsStore {
+    private readonly ctx;
+    private readonly schema;
+    private readonly describeFace;
+    /** The snapshot the section renders from (uSES-safe store). */
+    readonly store: SnapshotStore<ModelsSettingsState>;
+    /** Latest load wins; an older response never overwrites a newer one. */
+    private generation;
+    /**
+     * @param ctx - the page plugin's context, whose `remote.llm` and
+     * `remote.credentials` namespaces carry the directory and credential reads.
+     * @param schema - settings-owned schema and immutable path operations.
+     * @param describeFace - the shared mirror's describe face (namespace views and writability).
+     */
+    constructor(ctx: ClientContext, schema: SettingsSchemaOperations, describeFace: SettingsDescribeFace);
+    /**
+     * Refresh the whole page snapshot: the provider directory and the mirror's
+     * settings answer in parallel, then one batched credential describe over
+     * every referenced ref. Provider failure or absence of an initial settings
+     * answer keeps the last good rows and surfaces an error; a failed settings
+     * refresh reuses the mirror's held view.
+     * @returns nothing; the snapshot carries the outcome.
+     */
+    load(): Promise<void>;
+    /** Publish one load's failure text, unless a newer load already took over. */
+    private failLoad;
+}
+/**
+ * Whether a joined row can serve model requests as it stands: the route is
+ * registered with the adapter registry, and whatever credential its resolved
+ * profile names is stored. A profile naming no reference authenticates through
+ * the provider's own path (the Bedrock chain, Vertex ADC, a gateway that needs
+ * nothing), as does a live route with no settings address at all, so neither
+ * owes this page a key.
+ * @param row - one joined provider row.
+ * @returns whether the user already has this provider to talk to.
+ */
+export declare function providerUsable(row: ProviderRow): boolean;
+/** First-run onboarding readiness derived only from the shared Models join. */
+export type OnboardingReadiness = {
+    kind: 'loading';
+} | {
+    kind: 'adapter-absent';
+} | {
+    kind: 'provider-ready';
+} | {
+    kind: 'credential-missing';
+} | {
+    kind: 'unavailable';
+    reason: 'load-failed' | 'provider-inactive' | 'credentials-unavailable' | 'settings-read-only' | 'credential-read-only';
+};
+/**
+ * Project first-run readiness from the provider/settings/credential join used
+ * by the Models page. The step exists to leave the user with a model to talk
+ * to, so ANY usable provider ends it; only when none exists does the official
+ * DeepSeek route — the one route the prompt can offer a key field for — decide
+ * whether prompting can help. A missing official configurable-provider
+ * declaration means the adapter is not repairable by navigating to Models.
+ * @param state - current shared Models join snapshot.
+ * @returns the onboarding state without reading a parallel fact source.
+ */
+export declare function onboardingReadiness(state: ModelsSettingsState): OnboardingReadiness;
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/welcome-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Welcome-notice state derived from the welcome settings scope. The scope is
+ * the transport: a loopback browser follows the durable Host section, while a
+ * remote browser's memory-mode scope never answers and the acknowledgement
+ * stays process-local here.
+ */
+import { type SnapshotStore } from '@x1a0f3n9/dsh-client-store';
+import type { SettingsScope } from '@x1a0f3n9/dsh-client-ui-settings/client';
+/** State rendered by the welcome step. */
+export interface WelcomeNoticeState {
+    status: 'idle' | 'loading' | 'ready' | 'saving' | 'error';
+    acknowledged: boolean;
+    error: string | null;
+}
+/** The welcome section as the notice reads it. */
+export type WelcomeSection = Record<string, unknown>;
+/**
+ * Accept any object section verbatim; a malformed durable value reads as an
+ * empty section, so the notice treats it as unacknowledged instead of leaving
+ * the scope stuck on its previous value.
+ * @param section - the wire section value.
+ * @returns the section object, or an empty one for non-object values.
+ */
+export declare function decodeWelcomeSection(section: unknown): WelcomeSection;
+/** Coordinates durable Host acknowledgement or a process-local remote fallback. */
+export declare class WelcomeNoticeStore {
+    private readonly scope;
+    /** uSES-safe state source shared by the registered welcome step. */
+    readonly store: SnapshotStore<WelcomeNoticeState>;
+    private localAcknowledged;
+    private saving;
+    private following;
+    /**
+     * @param scope - the welcome settings namespace scope; its memory mode is
+     * what keeps a remote browser process-local.
+     */
+    constructor(scope: SettingsScope<WelcomeSection>);
+    /**
+     * Begin following the bound scope (idempotent) and publish its current answer.
+     * @returns settlement after the current answer is published.
+     */
+    load(): Promise<void>;
+    /**
+     * Persist this copy version, or advance only this process for a remote
+     * browser. Success is judged against the state the write left behind, so a
+     * refused or failed write reports false after its recovery read settles.
+     * @returns true when the selected persistence mode holds the acknowledgement.
+     */
+    acknowledge(): Promise<boolean>;
+    /** Stop following the scope. */
+    dispose(): void;
+    private derive;
+}
+//# sourceMappingURL=welcome-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the models settings plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/onboarding-copy.d.ts

@@ -0,0 +1,10 @@
+/** Durable settings namespace for product-wide GUI onboarding facts. */
+export declare const WELCOME_NOTICE_SETTINGS_NAMESPACE = "ui-onboarding";
+/** Field storing the last welcome notice version the user acknowledged. */
+export declare const WELCOME_NOTICE_ACK_FIELD = "welcomeNoticeVersion";
+/**
+ * Bump only when the notice changes materially and every user should see it
+ * again. The acknowledgement is compared for exact equality.
+ */
+export declare const WELCOME_NOTICE_VERSION = "2026-08-13.1";
+//# sourceMappingURL=onboarding-copy.d.ts.map