@qilin-agent/client-ui-settings 0.0.0-stage → 3.1.3

package/lib/index.js

@@ -0,0 +1,20 @@
+import z from "@qilin-agent/schemastery";
+//#region lib/types/developer-tools-settings.js
+/** Shared developer-tool preference stored by the Host user-settings document. */
+/** Namespace for developer UI and HTML preview capabilities. */
+const DEVELOPER_TOOLS_NAMESPACE = "ui-settings";
+/** New installations and missing values enable the full interface. */
+const DeveloperToolsSettingsFields = { enabled: z.boolean().default(true) };
+/** Durable developer-tools schema; also the wire envelope the browser scope validates against. */
+const DeveloperToolsSettingsSchema = z.object({ enabled: DeveloperToolsSettingsFields["enabled"] });
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the shared developer-tool preference. */
+/** Register the durable developer-tools section when a provider exists. */
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(DEVELOPER_TOOLS_NAMESPACE, DeveloperToolsSettingsSchema);
+	});
+}
+//#endregion
+export { DEVELOPER_TOOLS_NAMESPACE, apply };

package/lib/types/client/config-form-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Client configuration values and atomic write operations.
+ */
+import type { SettingsPathOpView } from '@qilin-agent/api-remotes/client';
+/** Client-side sync state of one settings namespace. */
+export interface ConfigFormSnapshot<T> {
+    /**
+     * `loading` until the first accepted section, `ready` while one stands, and
+     * `unavailable` when the namespace is not exposed to this client or the
+     * connection keeps preferences process-local (memory mode).
+     */
+    status: 'loading' | 'ready' | 'unavailable';
+    /** Last accepted schema-resolved section; undefined before the first acceptance. */
+    value: T | undefined;
+    /**
+     * Composition layer the Host resolved {@link value} over, when the owning
+     * plugin declared one. What a field reverts to once cleared.
+     */
+    base: unknown;
+    /**
+     * Raw user layer as stored, when one exists. A field's PRESENCE here is what
+     * marks it overridden — an override whose value equals the composition
+     * default is still an override, and comparing values could not see it.
+     */
+    user: unknown;
+    /** Namespace revision fencing the next write; undefined before the first Host view. */
+    revision: number | undefined;
+    /** Whether the Host document accepts writes; memory mode never does. */
+    writable: boolean;
+    /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
+    mode: 'host' | 'memory';
+}
+/**
+ * Accepted values and serialized writes shared by editors of one Host entry.
+ */
+export interface ConfigForm<T> {
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): ConfigFormSnapshot<T>;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Queue one atomic namespace mutation. All operations share one revision
+     * fence, Host validation, persistence decision, and recovery read. Supplying
+     * `expectedRevision` preserves an earlier read as the fence instead of using
+     * the latest queued or mirrored revision.
+     * @param ops - ordered field operations copied when queued.
+     * @param expectedRevision - optional fixed revision read by the domain editor.
+     * @returns true for Host acceptance, false for refusal or skipped writes, after any latest-write recovery.
+     * Transport failures reject.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<boolean>;
+    /**
+     * Queue one field write. Rapid writes preserve mutation order, each carries
+     * the latest known namespace revision, and only the latest settlement may
+     * publish; a Host-refused latest write reloads Host state instead.
+     * @param field - scalar field inside the namespace section.
+     * @param value - JSON-shaped value selected by the user.
+     * @returns true for Host acceptance, false for refusal or skipped writes, after any latest-write recovery.
+     * Transport failures reject.
+     */
+    set(field: string, value: unknown): Promise<boolean>;
+    /**
+     * Queue one field clear, so the field re-inherits the composition layer.
+     * Shares {@link set}'s ordering, revision, and recovery contract.
+     * @param field - scalar field inside the namespace section.
+     * @returns true for Host acceptance, false for refusal or skipped writes, after any latest-write recovery.
+     * Transport failures reject.
+     */
+    unset(field: string): Promise<boolean>;
+}
+//# sourceMappingURL=config-form-types.d.ts.map

package/lib/types/client/config-form.d.ts

@@ -0,0 +1,159 @@
+/** Shared entry values and ordered writes over the Host configuration mirror. */
+import { DeveloperToolsPreference } from './developer-tools.ts';
+import { Service } from '@qilin-agent/kylin';
+import type { Context } from '@qilin-agent/kylin';
+import type { SettingsPathOpView } from '@qilin-agent/api-remotes/client';
+import type { SettingsSchemaService } from './schema.ts';
+import type { ConfigForm, ConfigFormSnapshot } from './config-form-types.ts';
+import { SettingsDescribeMirror, type SettingsDescribeFace } from './settings-mirror.ts';
+/** Domain-owned description of one settings namespace consumed by a browser plugin. */
+interface ConfigFormSpec<T> {
+    /** Settings namespace registered by the owning Host plugin. */
+    namespace: string;
+    /**
+     * Narrow one wire section; undefined keeps the last accepted value. The
+     * default validates the section against the namespace's own serialized wire
+     * schema, so domains add a decoder only to narrow beyond that schema.
+     */
+    decode?: (section: unknown) => T | undefined;
+}
+/**
+ * One namespace's derived view over the shared describe mirror, plus that
+ * namespace's serialized Host writes. Writes carry the latest known namespace
+ * revision, fold their answers back into the mirror, and teardown waits for
+ * the operation already crossing the wire.
+ */
+export declare class ConfigFormController<T> implements ConfigForm<T> {
+    private readonly ctx;
+    private readonly spec;
+    private readonly mirror;
+    private readonly persistence;
+    private readonly schema;
+    private readonly store;
+    private tail;
+    private writeGeneration;
+    private disposed;
+    private readonly unsubscribe;
+    /**
+     * Revision answered by a superseded write still ahead of the mirror: the
+     * mirror only folds the LATEST settlement in, so a queued successor takes
+     * its fence from here first.
+     */
+    private pendingRevision;
+    /**
+     * @param ctx - the providing plugin's context, whose `remote.settings`
+     * namespace carries this form's writes (reads ride the mirror).
+     * @param spec - namespace identity and optional narrowing decoder.
+     * @param mirror - the shared describe mirror this form derives from.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
+     * @param schema - settings-owned schema operations.
+     */
+    constructor(ctx: Context, spec: ConfigFormSpec<T>, mirror: SettingsDescribeMirror, persistence: 'host' | 'memory', schema: SettingsSchemaService);
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): ConfigFormSnapshot<T>;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Queue one field write; see {@link ConfigForm.set} for the ordering,
+     * revision, and recovery contract.
+     * @param field - scalar field inside the namespace section.
+     * @param value - JSON-shaped value selected by the user.
+     * @returns whether the Host accepted the write, after any recovery read.
+     */
+    set(field: string, value: unknown): Promise<boolean>;
+    /**
+     * Queue one field clear; see {@link ConfigForm.unset} for the ordering,
+     * revision, and recovery contract.
+     * @param field - scalar field inside the namespace section.
+     * @returns whether the Host accepted the clear, after any recovery read.
+     */
+    unset(field: string): Promise<boolean>;
+    /**
+     * Queue one atomic namespace mutation; see {@link ConfigForm.mutate}.
+     * @param ops - ordered field operations copied when queued.
+     * @param expectedRevision - optional fixed revision read by the domain editor.
+     * @returns whether the Host accepted the mutation, after any recovery read.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<boolean>;
+    /** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
+    private recover;
+    /**
+     * Stop queued operations, stop deriving, and wait for the current wire call
+     * to settle.
+     * @returns settlement after the controller reaches quiescence.
+     */
+    dispose(): Promise<void>;
+    private enqueue;
+    private derive;
+    private decode;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        configForms: ConfigForms;
+    }
+}
+/**
+ * The settings domain's base service. Features that own a preference reach the
+ * settings transport through this service rather than a shared function: the
+ * client bundle purity gate forbids cross-plugin value imports and directs
+ * cross-plugin collaboration through cordis services
+ * (`packages/client/tsdown.client.ts`).
+ */
+export declare class ConfigForms extends Service {
+    private readonly forms;
+    /** Shared developer-tool preference owned by this settings provider. */
+    readonly developerTools: DeveloperToolsPreference;
+    private readonly mirror;
+    private readonly schema;
+    private readonly persistence;
+    /**
+     * The PROVIDING fiber, kept because a Service reads `ctx` as its *consumer's*
+     * fiber: letting a shared form write through the caller's context would make
+     * every caller declare `remote.settings` in its own `inject`.
+     */
+    private readonly owner;
+    /**
+     * @param ctx - the providing plugin's context.
+     * @param config - the shared describe mirror every shared form derives from,
+     * the settings-owned schema operations, and the Host persistence the provider
+     * resolved from `remote.$host`.
+     */
+    constructor(ctx: Context, config: {
+        mirror: SettingsDescribeMirror;
+        schema: SettingsSchemaService;
+        persistence: 'host' | 'memory';
+    });
+    /**
+     * The shared mirror's read/fold face for cross-namespace surfaces (schema
+     * introspection, the served-namespace directory). Per-namespace consumers
+     * use {@link get}; both derive from the same snapshot, so they can never
+     * disagree about the document.
+     * @returns the describe face over the shared mirror.
+     */
+    describe(): SettingsDescribeFace;
+    /** Get the shared form values and write queue for one Host plugin entry.
+     * @param entryId Unique Host plugin entry id.
+     * @returns The entry's form, owned by this provider.
+     */
+    get<T>(entryId: string): ConfigForm<T>;
+    /**
+     * Keep a registration alive while the Host serves any of some namespaces:
+     * `register` runs once one of them is in the describe mirror, and its
+     * disposer runs when none is or when the returned disposer runs. A plugin
+     * whose page edits a namespace another plugin owns registers the page
+     * through this, so a deployment that never composed the owner shows no
+     * trace of the page. The caller owns the returned disposer and wraps it in
+     * `ctx.effect`; unlike {@link bind}, nothing is registered on the caller's
+     * context here.
+     * @param namespaces - the settings namespaces the registration follows.
+     * @param register - registers the contribution, given every namespace the Host serves; returns its disposer.
+     * @returns the disposer ending the watch and any live registration.
+     */
+    whileServed(namespaces: readonly string[], register: (served: ReadonlySet<string>) => () => void): () => void;
+}
+export {};
+//# sourceMappingURL=config-form.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Settings slot contract — the canonical home of every settings slot type,
+ * owned by the settings domain base rather than by the shell that renders
+ * them (ui-settings-general, which occupies `sidebar.settings`). The shell has
+ * zero copy of its own: ALL text (panel title, header actions, close aria,
+ * section content) arrives from registrants. A feature owns its own settings
+ * pages — adding a setting never means editing the shell; copy that belongs to
+ * no single feature (chrome, the General section) is owned by ui-settings-general too.
+ */
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotMap {
+        /**
+         * The panel title text seat. Content renders inside the nav heading row;
+         * the dialog's accessible name points at that node via aria-labelledby.
+         * Absent contribution leaves the heading empty.
+         */
+        'settings.header': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * Optional actions rendered in the content-column header before Close.
+         * Registrants own visibility, behavior, copy, and failure presentation;
+         * the shell supplies only the ordered render site.
+         */
+        'settings.action': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * The close button's visually-hidden label text (the button itself —
+         * icon, geometry, focus — is shell chrome). Absent contribution leaves
+         * the button without an accessible name (broken-composition state).
+         */
+        'settings.close': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsHeaderOwnerProps;
+        };
+        /**
+         * One settings page per list entry. Registrant options carry the nav
+         * identity: `id` (section key, drives `only` filtering), `order` (nav
+         * position), `label` (registrant-localized display text — the registrant
+         * re-registers with fresh text on locale change, so the shell never
+         * subscribes locale state; the ledger bump doubles as the shell's
+         * re-render trigger). Sections render inside the panel content column.
+         * (`settings.general.item`, declared by ui-settings-general's General
+         * entry, is typed in the locale package — the common dependency of every
+         * item registrant; the shell neither declares nor renders it.)
+         */
+        'settings.section': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsSectionOwnerProps;
+        };
+        /**
+         * One page inside the Plugins settings section. The section owner renders
+         * localized entry labels as tabs and mounts each contribution inside its
+         * corresponding tab panel. Options: `id` (tab key), `order` (tab order),
+         * and `label` (registrant-localized tab text). Declared at runtime by the
+         * feature that owns the Plugins section; the type lives here so inventory
+         * and configuration plugins collaborate without depending on one another.
+         */
+        'settings.plugins.tab': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsPluginsTabOwnerProps;
+        };
+        /**
+         * Root-scoped onboarding steps contributed by settings features. The
+         * shell mounts one ordered step at a time; the active registrant either
+         * completes itself or keeps ownership until the user completes its sole
+         * path. Registrants own readiness, copy, dialog behavior, AND visible
+         * chrome: a step wraps its visible content in its modal surface (including
+         * `#root` inert ownership) and renders null while private facts are still
+         * loading. The shell paints no chrome of its own, so a mounted-but-deciding
+         * step shows and blocks nothing.
+         */
+        'settings.onboarding': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsOnboardingOwnerProps;
+        };
+        /**
+         * One preference row inside the General section — the additive seat for a
+         * single setting that needs no page of its own (a whole page is
+         * `settings.section`), contributed by the feature plugin that owns the
+         * preference (locale → Language, ui-theme → Appearance, ui-conversation →
+         * Composer Enter). Options: `id` (row key), `order` (row position). The
+         * section column only stacks rows, so a row draws its own internals,
+         * including its label: nothing projects a `label` here and the owner passes
+         * no props at all — copy, current value, and the write path are all yours,
+         * through your own inject face and `host.call`. Declared at runtime by
+         * ui-settings-general's General entry; the type lives here with every other
+         * settings slot type, because this package is the settings domain's base
+         * layer and every registrant already depends on it for `ctx.configForms`.
+         */
+        'settings.general.item': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsGeneralItemOwnerProps;
+        };
+        /** Mark rendered by the shell-owned About page. */
+        'settings.about.mark': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsMarkOwnerProps;
+        };
+    }
+}
+/** Owner share of a settings project mark. */
+export interface SettingsMarkOwnerProps {
+    /** Requested square edge in pixels. */
+    size: number;
+    /** Optional class name supplied by the host surface. */
+    className?: string | undefined;
+}
+/** Owner share of a General preference row (the section supplies nothing). */
+export interface SettingsGeneralItemOwnerProps {
+    /** Marker field: item owner props are intentionally empty. */
+    children?: never;
+}
+/** Owner share of a Plugins tab (the section supplies nothing). */
+export interface SettingsPluginsTabOwnerProps {
+    /** Marker field: tab owner props are intentionally empty. */
+    children?: never;
+}
+/** Owner share of the header title seat (the shell supplies nothing). */
+export interface SettingsHeaderOwnerProps {
+    /** Marker field: header owner props are intentionally empty. */
+    children?: never;
+}
+/**
+ * Owner share of a settings section entry. The shell owns modal visibility
+ * and navigation; a section's data arrives through its own inject faces and
+ * stores. `close` is the one shell affordance a section receives, for flows
+ * that leave settings altogether (starting a session from a section) — the
+ * onboarding coordinator's `openSection`/`complete` precedent, inverted.
+ */
+export interface SettingsSectionOwnerProps {
+    /** Close the settings panel (the shell owns the open state). */
+    close: () => void;
+}
+/** Owner share of the currently active settings-backed onboarding step. */
+export interface SettingsOnboardingOwnerProps {
+    /** Stable id of the step currently selected by the coordinator. */
+    stepId: string;
+    /** Complete or skip this step and transfer ownership to the next entry. */
+    complete: () => void;
+    /** Open the settings panel directly on one registered section. */
+    openSection: (id: string) => void;
+}
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/developer-tools.d.ts

@@ -0,0 +1,22 @@
+/** One accepted preference drives every developer-tool consumer. */
+import { type ObservableSnapshot } from '@qilin-agent/client-store';
+import type { DeveloperToolsSettings } from '../developer-tools-settings.ts';
+import type { ConfigForm } from './config-form-types.ts';
+/** Shared preference; Host-backed features stay disabled until an accepted value arrives. */
+export declare class DeveloperToolsPreference {
+    private readonly scope;
+    /** Accepted enablement, observable through renderer-bound hooks. */
+    readonly enabled: ObservableSnapshot<boolean>;
+    private readonly local;
+    /**
+     * @param scope - settings-owned namespace controller.
+     */
+    constructor(scope: ConfigForm<DeveloperToolsSettings>);
+    /**
+     * Persist a Host choice with ordered writes, or update the shared browser-local choice.
+     * @param enabled - requested developer-tool mode.
+     * @returns settlement after local publication or Host acceptance; rejects after a refused write recovers.
+     */
+    setEnabled(enabled: boolean): Promise<void>;
+}
+//# sourceMappingURL=developer-tools.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * Settings domain base plugin, browser half. Provides `ctx.configForms`, the
+ * shared configuration-form service every preference row reaches its durable
+ * section through, and owns the one `settings.describe` reader in the browser:
+ * the describe mirror, whose invalidation subscriptions
+ * (`settings/document-updated`, `connection/reset`) live here so every derived
+ * surface refreshes from a single wire read. It depends on no `ui-*`
+ * presentation package, so any feature that owns a preference can reach it:
+ * the settings SHELL — the `sidebar.settings` occupant, its navigation, and
+ * the chrome — lives in ui-settings-general, because a shell dependency on
+ * ui-sidebar would close a reference cycle through ui-layout and ui-theme.
+ * Export discipline: packages/client/AGENTS.md.
+ */
+import type { Context } from '@qilin-agent/kylin';
+export type { SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsMarkOwnerProps, SettingsOnboardingOwnerProps, SettingsPluginsTabOwnerProps, SettingsSectionOwnerProps, } from './contract/slots.ts';
+export type { ConfigForms } from './config-form.ts';
+export type { ConfigForm, ConfigFormSnapshot } from './config-form-types.ts';
+export type { SettingsSchemaService } from './schema.ts';
+export type { SchemaNode } from './schema.ts';
+export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot, } from './settings-mirror.ts';
+/**
+ * Required services: the Remote namespace the mirror reads through and the
+ * forwarded settings invalidation it refreshes on.
+ */
+export declare const inject: string[];
+/**
+ * Provide the shared configuration forms over one describe mirror, and keep
+ * that mirror fresh on the two signals that can move the settings document: a
+ * document commit and a (re)connect.
+ *
+ * Constructing the service in this plugin's fiber keeps its traced methods
+ * bound to each consuming plugin's context.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,72 @@
+/** Synchronous schema introspection and immutable settings-draft edits. */
+import { Service } from '@qilin-agent/kylin';
+import type { Context } from '@qilin-agent/kylin';
+import Schema from '@qilin-agent/schemastery';
+/** Live schemastery node used for settings introspection and validation. */
+export type SchemaNode = Schema;
+/**
+ * Settings-owned synchronous schema service. Dynamic client plugins receive
+ * this Cordis entity instead of importing executable helpers from one another.
+ */
+export declare class SettingsSchemaService extends Service {
+    /** @param ctx - providing ui-settings context. */
+    constructor(ctx: Context);
+    /**
+     * Rehydrate one serialized `schema.toJSON()` envelope.
+     * @param serialized - serialized Schemastery node.
+     * @returns live schema node.
+     */
+    rehydrate(serialized: unknown): SchemaNode;
+    /**
+     * Validate a settings draft.
+     * @param schema - live schema node.
+     * @param draft - candidate settings value.
+     * @returns validation failure text, or `undefined` when valid.
+     */
+    validate(schema: SchemaNode, draft: unknown): string | undefined;
+    /**
+     * Resolve an object, dict, or array schema node at a settings path.
+     * @param root - schema node to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved node, or `undefined` when the path is absent.
+     */
+    nodeAtPath(root: SchemaNode, path: readonly string[]): SchemaNode | undefined;
+    /**
+     * Read a nested value by a string-key or array-index path.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns the resolved value, or `undefined` when the path is absent.
+     */
+    getPath(value: unknown, path: readonly string[]): unknown;
+    /**
+     * Report whether the final path key exists independently of its value.
+     * @param value - value to traverse.
+     * @param path - object keys or array indexes.
+     * @returns whether the path exists.
+     */
+    hasPath(value: unknown, path: readonly string[]): boolean;
+    /**
+     * Immutably set a nested value, materializing missing containers.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @param value - replacement value.
+     * @returns copied root containing the replacement.
+     * @throws when `path` is empty.
+     */
+    setPath(root: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown>;
+    /**
+     * Immutably remove a nested key, preserving an unchanged missing root.
+     * @param root - settings object to copy.
+     * @param path - non-empty object-key or array-index path.
+     * @returns copied root without the key, or `root` when the path is absent.
+     * @throws when `path` is empty.
+     */
+    deletePath(root: Record<string, unknown>, path: readonly string[]): Record<string, unknown>;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Settings-owned synchronous schema and immutable path operations. */
+        settingsSchema: SettingsSchemaService;
+    }
+}
+//# sourceMappingURL=schema.d.ts.map

package/lib/types/client/settings-mirror.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Client mirror of the Host settings document: the one `settings.describe`
+ * reader in the browser. Every settings consumer derives from this store —
+ * shared entry forms through `ConfigForms.get`, cross-namespace
+ * surfaces through the provider's shared describe face — so startup cost and
+ * freshness are properties of this class, not of how many features own a
+ * preference. The Host stays the fact source: the mirror re-reads on the
+ * invalidations its owning plugin subscribes to and folds write answers in
+ * through {@link SettingsDescribeMirror.acceptView}.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { SettingsNamespaceView } from '@qilin-agent/api-remotes/client';
+/** The full `settings.describe` answer the mirror serves. */
+export interface SettingsDescribeView {
+    /** Every namespace a live Host plugin registered, as the Host reported it. */
+    namespaces: readonly SettingsNamespaceView[];
+    /** Whether the settings provider accepts writes. */
+    writable: boolean;
+    /** Whether a native settings document exists for the Host to open. */
+    hasDocument: boolean;
+}
+/** Mirror state every derived settings surface renders from. */
+export interface SettingsMirrorSnapshot {
+    /**
+     * `unavailable` is the terminal non-loopback state; `ready` persists across
+     * later failed refreshes (the held view keeps serving); `idle` means no
+     * answer is held and no read is running, so `ensure` will start one.
+     */
+    status: 'idle' | 'loading' | 'ready' | 'unavailable';
+    /** The last good answer; undefined until the first success. */
+    view: SettingsDescribeView | undefined;
+    /** The latest refresh failure message, cleared by the next success. */
+    error: string | null;
+}
+/**
+ * The mirror as cross-namespace surfaces consume it: current answer,
+ * subscription, first-use read, and the write-answer fold. `load` stays off
+ * this face — invalidation refreshes belong to the mirror's owning plugin.
+ */
+export interface SettingsDescribeFace {
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsMirrorSnapshot;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Resolve once an answer is held (or the mirror is terminally unavailable),
+     * reading only from `idle`.
+     * @returns settlement of the current or newly started read, if any.
+     */
+    ensure(): Promise<void>;
+    /**
+     * Fold one write answer's namespace view into the held view without a wire
+     * read, invalidating any older read still in flight.
+     * @param view - the namespace view a settings write answered with.
+     */
+    acceptView(view: SettingsNamespaceView): void;
+}
+/**
+ * Serializes every Host `settings.describe` read behind one snapshot store.
+ * Concurrent {@link load} calls fold into the in-flight read plus one rerun,
+ * so an invalidation arriving mid-read is never lost and never duplicated.
+ */
+export declare class SettingsDescribeMirror implements SettingsDescribeFace {
+    private readonly ctx;
+    private readonly persistence;
+    private readonly store;
+    private inFlight;
+    private rerun;
+    private generation;
+    /**
+     * @param ctx - the providing plugin's context, whose `remote.settings`
+     * namespace answers the describe read.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
+     */
+    constructor(ctx: ClientContext, persistence?: 'host' | 'memory');
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsMirrorSnapshot;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Refresh from the Host. A call during an in-flight read marks one rerun
+     * after it settles instead of racing a second wire read.
+     * @returns settlement after this call's freshness is reflected.
+     */
+    load(): Promise<void>;
+    /**
+     * Resolve once an answer is held (or the mirror is terminally unavailable),
+     * reading only from `idle`. The cheap idempotent entry for surfaces that
+     * render on first use.
+     * @returns settlement of the current or newly started read, if any.
+     */
+    ensure(): Promise<void>;
+    /**
+     * Fold one write answer's namespace view into the held view without a wire
+     * read, and invalidate any read still in flight. With no held document, the
+     * answer is not published as a partial document; an in-flight read reruns so
+     * it cannot publish a document fetched before the write committed.
+     * @param view - the namespace view a settings write answered with.
+     */
+    acceptView(view: SettingsNamespaceView): void;
+    /**
+     * Convenience row lookup on the held view.
+     * @param ns - namespace identity.
+     * @returns the namespace view, or undefined while unanswered or unregistered.
+     */
+    namespace(ns: string): SettingsNamespaceView | undefined;
+    private run;
+    private shouldRerun;
+}
+//# sourceMappingURL=settings-mirror.d.ts.map