@deepseek-ai/dsh-client-ui-settings 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/index.js

@@ -1,6 +1,20 @@
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/developer-tools-settings.js
+/** Shared Web and desktop developer-tool preference stored by the Host. */
+/** New installations and missing values enable the full interface. */
+const DeveloperToolsSettingsFields = { enabled: z.boolean().default(true) };
+z.object(DeveloperToolsSettingsFields);
+//#endregion
 //#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() {}
+/** Live preferences projected to the browser. */
+const Config = z.object({ enabled: DeveloperToolsSettingsFields["enabled"].volatile() });
+/** Host preferences are consumed through the configuration form projection.
+* @param ctx Plugin context used for optional settings presentation.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
+	});
+}
 //#endregion
-export { apply };
+export { Config, apply };

package/lib/types/client/{settings-contract.d.ts → config-form-types.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Settings-namespace scope contracts owned beside the settings transport.
+ * Client configuration values and atomic write operations.
  */
 import type { SettingsPathOpView } from '@deepseek-ai/dsh-api-remotes/client';
 /** Client-side sync state of one settings namespace. */
-export interface SettingsScopeSnapshot<T> {
+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
@@ -30,26 +30,12 @@ export interface SettingsScopeSnapshot<T> {
     /** `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.
+ * Accepted values and serialized writes shared by editors of one Host entry.
  */
-export interface SettingsScope<T> {
+export interface ConfigForm<T> {
     /** @returns the current sync snapshot (stable reference until the next change). */
-    getSnapshot(): SettingsScopeSnapshot<T>;
+    getSnapshot(): ConfigFormSnapshot<T>;
     /**
      * Observe snapshot replacements.
      * @param listener - invoked after each snapshot change.
@@ -63,24 +49,27 @@ export interface SettingsScope<T> {
      * 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.
+     * @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<void>;
+    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 rejected or failed latest write reloads Host state instead.
+     * 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 settlement after the write and any latest-write recovery read.
+     * @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<void>;
+    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 settlement after the clear and any latest-write recovery read.
+     * @returns true for Host acceptance, false for refusal or skipped writes, after any latest-write recovery.
+     * Transport failures reject.
      */
-    unset(field: string): Promise<void>;
+    unset(field: string): Promise<boolean>;
 }
-//# sourceMappingURL=settings-contract.d.ts.map
+//# sourceMappingURL=config-form-types.d.ts.map

package/lib/types/client/{settings-scope.d.ts → config-form.d.ts}

@@ -1,23 +1,29 @@
-/**
- * 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.
- */
+/** Shared entry values and ordered writes over the Host configuration mirror. */
+import { DeveloperToolsPreference } from './developer-tools.ts';
 import { Service } from '@deepseek-ai/cordis';
 import type { Context } from '@deepseek-ai/cordis';
 import type { SettingsPathOpView } from '@deepseek-ai/dsh-api-remotes/client';
 import type { SettingsSchemaService } from './schema.ts';
-import type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-contract.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 SettingsScopeController<T> implements SettingsScope<T> {
+export declare class ConfigFormController<T> implements ConfigForm<T> {
     private readonly ctx;
     private readonly spec;
     private readonly mirror;
@@ -36,15 +42,15 @@ export declare class SettingsScopeController<T> implements SettingsScope<T> {
     private pendingRevision;
     /**
      * @param ctx - the providing plugin's context, whose `remote.settings`
-     * namespace carries this scope's writes (reads ride the mirror).
+     * 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 scope derives from.
+     * @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: SettingsScopeSpec<T>, mirror: SettingsDescribeMirror, persistence: 'host' | 'memory', schema: SettingsSchemaService);
+    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(): SettingsScopeSnapshot<T>;
+    getSnapshot(): ConfigFormSnapshot<T>;
     /**
      * Observe snapshot replacements.
      * @param listener - invoked after each snapshot change.
@@ -52,27 +58,27 @@ export declare class SettingsScopeController<T> implements SettingsScope<T> {
      */
     subscribe(listener: () => void): () => void;
     /**
-     * Queue one field write; see {@link SettingsScope.set} for the ordering,
+     * 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 settlement after the write and any latest-write recovery read.
+     * @returns whether the Host accepted the write, after any recovery read.
      */
-    set(field: string, value: unknown): Promise<void>;
+    set(field: string, value: unknown): Promise<boolean>;
     /**
-     * Queue one field clear; see {@link SettingsScope.unset} for the ordering,
+     * Queue one field clear; see {@link ConfigForm.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.
+     * @returns whether the Host accepted the clear, after any recovery read.
      */
-    unset(field: string): Promise<void>;
+    unset(field: string): Promise<boolean>;
     /**
-     * Queue one atomic namespace mutation; see {@link SettingsScope.mutate}.
+     * 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 settlement after the mutation and any latest-write recovery read.
+     * @returns whether the Host accepted the mutation, after any recovery read.
      */
-    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<void>;
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<boolean>;
     /** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
     private recover;
     /**
@@ -87,7 +93,7 @@ export declare class SettingsScopeController<T> implements SettingsScope<T> {
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        settingsScope: SettingsScopeBinder;
+        configForms: ConfigForms;
     }
 }
 /**
@@ -97,19 +103,22 @@ declare module '@deepseek-ai/cordis' {
  * cross-plugin collaboration through cordis services
  * (`packages/client/tsdown.client.ts`).
  */
-export declare class SettingsScopeBinder extends Service {
+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 bound scope write through the caller's context would make
+     * 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 bound scope derives from,
+     * @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`.
      */
@@ -121,21 +130,30 @@ export declare class SettingsScopeBinder extends Service {
     /**
      * 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
+     * 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>;
     /**
-     * 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.
+     * 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.
      */
-    bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
+    whileServed(namespaces: readonly string[], register: (served: ReadonlySet<string>) => () => void): () => void;
 }
-//# sourceMappingURL=settings-scope.d.ts.map
+export {};
+//# sourceMappingURL=config-form.d.ts.map

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

@@ -10,6 +10,12 @@
  */
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface SlotMap {
+        /** Optional sidebar account launcher; opens the shell-owned settings panel. */
+        'settings.launcher': {
+            kind: 'single';
+            scope: 'root';
+            owner: SettingsLauncherOwnerProps;
+        };
         /**
          * The sidebar-foot trigger row content: icon + label, supplied as slot
          * content (the accessible name comes from the content — rail state
@@ -109,7 +115,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
          * 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`.
+         * layer and every registrant already depends on it for `ctx.configForms`.
          */
         'settings.general.item': {
             kind: 'list';
@@ -153,9 +159,20 @@ export interface SettingsSectionOwnerProps {
 export interface SettingsOnboardingOwnerProps {
     /** Stable id of the step currently selected by the coordinator. */
     stepId: string;
+    /** User explicitly reopened this step outside first-run onboarding. */
+    explicit?: boolean;
     /** 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;
 }
+/** Sidebar launcher geometry and settings navigation. */
+export interface SettingsLauncherOwnerProps {
+    /** Whether the sidebar shows labels. */
+    wide: boolean;
+    /** Open the settings panel. */
+    openSettings: () => void;
+    /** @param id - registered onboarding editor to open explicitly. */
+    openOnboarding: (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 '@deepseek-ai/dsh-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

@@ -1,20 +1,8 @@
-/**
- * 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.
- */
+/** Shared configuration forms and their Host describe mirror. */
 import type { Context } from '@deepseek-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 { SettingsLauncherOwnerProps, SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsOnboardingOwnerProps, SettingsPluginsTabOwnerProps, SettingsSectionOwnerProps, SettingsTriggerOwnerProps, } 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';
@@ -23,14 +11,8 @@ export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot
  * forwarded settings invalidation it 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.
+/** Provide shared forms and refresh them on document changes and reconnects.
+ * @param ctx Client provider context.
  */
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,8 +1,8 @@
 /**
  * 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
+ * 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

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

@@ -0,0 +1,20 @@
+/** Shared Web and desktop developer-tool preference stored by the Host. */
+import z from '@deepseek-ai/schemastery';
+/** Namespace for developer UI and HTML preview capabilities. */
+export declare const DEVELOPER_TOOLS_NAMESPACE = "ui-settings";
+/** Persisted developer-tool choice. */
+export interface DeveloperToolsSettings {
+    /** Enable diagnostic views, preset selection, change summaries and scripted HTML previews. */
+    enabled: boolean;
+}
+/** New installations and missing values enable the full interface. */
+export declare const DeveloperToolsSettingsFields: {
+    enabled: z<boolean, boolean, "defined">;
+};
+/** Schema for shared configuration values. */
+export declare const DeveloperToolsSettingsSchema: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+}>>, "plain">;
+//# sourceMappingURL=developer-tools-settings.d.ts.map

package/lib/types/index.d.ts

@@ -1,4 +1,18 @@
-/** 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;
+import type { Volatile, Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Runtime preferences projected to the browser. */
+export interface Config {
+    /** Whether developer tools are enabled. */
+    enabled: Volatile<boolean>;
+}
+/** Live preferences projected to the browser. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** Host preferences are consumed through the configuration form projection.
+ * @param ctx Plugin context used for optional settings presentation.
+ */
+export declare function apply(ctx: Context): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings",
-  "description": "Settings domain base plugin: the settings-namespace scope service and the canonical settings slot-type contract",
-  "version": "0.1.6-alpha.2",
+  "description": "Settings domain base plugin: shared configuration forms and the canonical settings slot-type contract",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -35,25 +35,27 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-api-remotes": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-test-runtime": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-settings": "0.1.7-alpha.2"
   },
   "files": [
     "lib/index.js",
     "lib/client.js",
     "lib/types/**/*.d.ts"
   ],
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  },
   "scripts": {
     "bundle": "tsdown",
     "watch": "tsdown --watch"