@prettier-ai/dsh-client-ui-settings 0.1.2-alpha.1

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host plugin body — no host-side behavior for the settings domain base plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@prettier-ai/dsh-client-ui-settings`.
+* @module @prettier-ai/dsh-client-ui-settings/invariant
+*/
+const PACKAGE_NAME = "@prettier-ai/dsh-client-ui-settings";
+/** Cordis companion plugin name. */
+const name = "client-ui-settings-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a presentation shell projecting the settings.section
+* ledger into navigation — it emits no cordis events and owns no cross-plugin
+* mutable relation; slot declaration/registration conflicts already fail loud
+* in the slot core at load time.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,161 @@
+/**
+ * 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 (trigger label, 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 '@prettier-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * The sidebar-foot trigger row content: icon + label, supplied as slot
+         * content (the accessible name comes from the content — rail state
+         * renders the label visually hidden). The shell renders the button
+         * chrome and owns open state. Absent contribution degrades to an
+         * icon-only button without an accessible name (broken-composition state;
+         * the shipped composition always registers the seat).
+         */
+        'settings.trigger': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsTriggerOwnerProps;
+        };
+        /**
+         * 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.settingsScope`.
+         */
+        'settings.general.item': {
+            kind: 'list';
+            scope: 'root';
+            owner: SettingsGeneralItemOwnerProps;
+        };
+    }
+}
+/** 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 trigger content seat: the sidebar column state. */
+export interface SettingsTriggerOwnerProps {
+    /** Whether the sidebar renders wide content (false = 56px rail, icon only). */
+    wide: boolean;
+}
+/** 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/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Settings domain base plugin, browser half. Provides `ctx.settingsScope`, the
+ * settings-namespace scope service every preference row binds 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 '@prettier-ai/cordis';
+export type { SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsOnboardingOwnerProps, SettingsPluginsTabOwnerProps, SettingsSectionOwnerProps, SettingsTriggerOwnerProps, } from './contract/slots.ts';
+export type { SettingsScopeController, SettingsScopeBinder } from './settings-scope.ts';
+export type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-contract.ts';
+export type { SettingsSchemaService } from './schema.ts';
+export type { SchemaNode } from './schema.ts';
+export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot, SettingsRemote, SettingsWireFace, } from './settings-mirror.ts';
+/**
+ * Required services: the wire handle for the mirror's reads and the forwarded
+ * settings invalidation the mirror refreshes on.
+ */
+export declare const inject: string[];
+/**
+ * Provide the settings-namespace scope service over one shared 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 '@prettier-ai/cordis';
+import type { Context } from '@prettier-ai/cordis';
+import Schema from '@prettier-ai/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 '@prettier-ai/cordis' {
+    interface Context {
+        /** Settings-owned synchronous schema and immutable path operations. */
+        settingsSchema: SettingsSchemaService;
+    }
+}
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1,86 @@
+/**
+ * Settings-namespace scope contracts owned beside the settings transport.
+ */
+import type { SettingsPathOpView } from '@prettier-ai/dsh-api-remotes/client';
+/** Client-side sync state of one settings namespace. */
+export interface SettingsScopeSnapshot<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';
+}
+/** Domain-owned description of one settings namespace consumed by a browser plugin. */
+export interface SettingsScopeSpec<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;
+}
+/**
+ * Reactive owner handle over one namespace's durable section — the browser
+ * mirror of the Host-side `SettingsScope` owner seam. Domain services read
+ * and observe the snapshot and route explicit user choices through its
+ * mutation methods.
+ */
+export interface SettingsScope<T> {
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsScopeSnapshot<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 settlement after the mutation and any latest-write recovery read.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<void>;
+    /**
+     * Queue one field write. Rapid writes preserve mutation order, each carries
+     * the latest known namespace revision, and only the latest settlement may
+     * publish; a rejected or failed latest write reloads Host state instead.
+     * @param field - scalar field inside the namespace section.
+     * @param value - JSON-shaped value selected by the user.
+     * @returns settlement after the write and any latest-write recovery read.
+     */
+    set(field: string, value: unknown): Promise<void>;
+    /**
+     * 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 settlement after the clear and any latest-write recovery read.
+     */
+    unset(field: string): Promise<void>;
+}
+//# sourceMappingURL=settings-contract.d.ts.map

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

@@ -0,0 +1,130 @@
+/**
+ * Client mirror of the Host settings document: the one `settings.describe`
+ * reader in the browser. Every settings consumer derives from this store —
+ * per-namespace scopes through `SettingsScopeBinder.bind`, cross-namespace
+ * surfaces through the binder'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 { ClientRemote, SettingsNamespaceView } from '@prettier-ai/dsh-api-remotes/client';
+/**
+ * The settings Remote methods browser configuration surfaces may reach: the
+ * redacted read plus merge, replacement, and path-addressed writes.
+ * Named once here so the consumers share one face instead of each re-deriving
+ * it from the namespace.
+ */
+export type SettingsRemote = Pick<ClientRemote['settings'], 'describe' | 'update' | 'replace' | 'mutate'>;
+/** Wire face carrying the settings Remote namespace. */
+export interface SettingsWireFace {
+    /** The settings Remote namespace. */
+    settings: SettingsRemote;
+}
+type SettingsFace = SettingsWireFace;
+/** 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 api;
+    private readonly persistence;
+    private readonly store;
+    private inFlight;
+    private rerun;
+    private generation;
+    /**
+     * @param api - settings wire face.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
+     */
+    constructor(api: SettingsFace, 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;
+}
+export {};
+//# sourceMappingURL=settings-mirror.d.ts.map

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

@@ -0,0 +1,139 @@
+/**
+ * Host transport for the settings-namespace scope contract. This file owns the
+ * per-namespace derivation over the shared {@link SettingsDescribeMirror} and
+ * the serialized write path. Reads never touch the wire here: the
+ * mirror is the one `settings.describe` reader, and every scope is a selector
+ * over its snapshot.
+ */
+import { Service } from '@prettier-ai/cordis';
+import type { Context } from '@prettier-ai/cordis';
+import type { SettingsPathOpView } from '@prettier-ai/dsh-api-remotes/client';
+import type { SettingsSchemaService } from './schema.ts';
+import type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-contract.ts';
+import { SettingsDescribeMirror, type SettingsDescribeFace, type SettingsWireFace } from './settings-mirror.ts';
+type SettingsFace = SettingsWireFace;
+/**
+ * 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 SettingsScopeController<T> implements SettingsScope<T> {
+    private readonly api;
+    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 api - settings wire face (writes only; reads ride the mirror).
+     * @param spec - namespace identity and optional narrowing decoder.
+     * @param mirror - the shared describe mirror this scope derives from.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
+     * @param schema - settings-owned schema operations.
+     */
+    constructor(api: SettingsFace, spec: SettingsScopeSpec<T>, mirror: SettingsDescribeMirror, persistence: 'host' | 'memory', schema: SettingsSchemaService);
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsScopeSnapshot<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 SettingsScope.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 settlement after the write and any latest-write recovery read.
+     */
+    set(field: string, value: unknown): Promise<void>;
+    /**
+     * Queue one field clear; see {@link SettingsScope.unset} for the ordering,
+     * revision, and recovery contract.
+     * @param field - scalar field inside the namespace section.
+     * @returns settlement after the clear and any latest-write recovery read.
+     */
+    unset(field: string): Promise<void>;
+    /**
+     * Queue one atomic namespace mutation; see {@link SettingsScope.mutate}.
+     * @param ops - ordered field operations copied when queued.
+     * @param expectedRevision - optional fixed revision read by the domain editor.
+     * @returns settlement after the mutation and any latest-write recovery read.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<void>;
+    /** 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 '@prettier-ai/cordis' {
+    interface Context {
+        settingsScope: SettingsScopeBinder;
+    }
+}
+/**
+ * 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 SettingsScopeBinder extends Service {
+    private readonly mirror;
+    private readonly schema;
+    private readonly wire;
+    /**
+     * @param ctx - the providing plugin's context.
+     * @param config - the shared describe mirror every bound scope derives from,
+     * the settings-owned schema operations, and the settings Remote namespace the
+     * bound scopes write through. The namespace is captured here rather than read
+     * inside {@link bind}, because a Service reads `ctx` as its *consumer's*
+     * fiber: reading it there would make every caller declare `remote.settings`
+     * in its own `inject`.
+     */
+    constructor(ctx: Context, config: {
+        mirror: SettingsDescribeMirror;
+        schema: SettingsSchemaService;
+        wire: SettingsWireFace;
+    });
+    /**
+     * The shared mirror's read/fold face for cross-namespace surfaces (schema
+     * introspection, the served-namespace directory). Per-namespace consumers
+     * use {@link bind}; both derive from the same snapshot, so they can never
+     * disagree about the document.
+     * @returns the describe face over the shared mirror.
+     */
+    describe(): SettingsDescribeFace;
+    /**
+     * Bind one namespace scope on the CALLER's plugin lifecycle — the service
+     * proxy binds `this.ctx` to the caller at call time, so the scope's disposer
+     * belongs to the calling fiber. The scope derives from the shared mirror
+     * (whose invalidation subscriptions live with the providing plugin), so
+     * binding adds no wire read of its own and activation never blocks on the
+     * settings transport.
+     * @param spec - domain-owned namespace contract.
+     * @returns the bound scope consumed by the domain's services and rows.
+     */
+    bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
+}
+export {};
+//# sourceMappingURL=settings-scope.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 settings domain base plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map