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

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

@@ -0,0 +1,108 @@
+/** 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;
+    addModel: string;
+    removeModel: string;
+    modelsEmpty: string;
+    keyBlank: string;
+    keyBlankNew: string;
+    keyIllegalCharacters: string;
+    modelIdRequired: string;
+    modelIdDuplicate: string;
+    modelNameInvalid: string;
+    modelContextInvalid: string;
+    modelMaxTokensInvalid: string;
+    advancedHint: string;
+    modelCapacityInvalid: string;
+    modelDuplicate: string;
+    modelContextWindow: string;
+    modelMaxTokens: string;
+    fetchModels: string;
+    fetching: string;
+    fetchNeedsBaseUrl: string;
+    fetchEmpty: string;
+    fetchTitle: string;
+    fetchDescription: 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;
+    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/schema-operations.d.ts

@@ -0,0 +1,10 @@
+import type { SettingsSchemaService } from '@prettier-ai/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 '@prettier-ai/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,163 @@
+/**
+ * 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 { ClientRemote, CredentialInfo, LlmConfigurableProvider, LlmProviderInfo, SettingsNamespaceView } from '@prettier-ai/dsh-api-remotes/client';
+import type { SnapshotStore } from '@prettier-ai/dsh-client-store';
+import type { SettingsDescribeFace, SettingsRemote } from '@prettier-ai/dsh-client-ui-settings/client';
+import type { SettingsSchemaOperations } from './schema-operations.ts';
+/** The credentials Remote methods the Models page reads and writes through. */
+export type ModelsCredentials = Pick<ClientRemote['credentials'], 'describe' | 'set' | 'unset'>;
+/** LLM Remote methods used by the Models page. */
+export type ModelsLlm = Pick<ClientRemote['llm'], 'discoverModels' | 'listConfigurableProviders' | 'listProviders'>;
+/** 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;
+}
+/**
+ * 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[];
+/**
+ * Every Remote wire face the Models page reaches.
+ */
+export interface ModelsWire {
+    /** The settings Remote namespace: the redacted read and the profile writes. */
+    settings: SettingsRemote;
+    /** Credential state and writes for the references provider profiles name. */
+    credentials: ModelsCredentials;
+    /** Provider directory reads and draft endpoint discovery. */
+    llm: ModelsLlm;
+}
+/** 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>;
+}
+/**
+ * Human text for a rejected wire call. A transport failure rejects with an
+ * Error; a host or a runtime can reject with anything, and the page still has
+ * to say something.
+ * @param error - the rejection value.
+ * @returns the message to show.
+ */
+export declare function messageOf(error: unknown): string;
+/**
+ * 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 api;
+    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 api - the page's credentials Remote and LLM wire faces.
+     * @param describeFace - the shared mirror's describe face (namespace views and writability).
+     */
+    constructor(api: Pick<ModelsWire, 'credentials' | 'llm'>, 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>;
+}
+/**
+ * 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 '@prettier-ai/dsh-client-store';
+import type { SettingsScope } from '@prettier-ai/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/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@prettier-ai/dsh-client-ui-settings-models`.
+ * @module @prettier-ai/dsh-client-ui-settings-models/invariant
+ */
+import type { Context } from '@prettier-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-settings-models-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@prettier-ai/dsh-client-ui-settings-models",
+  "description": "Models settings and shared product-onboarding dialogs over existing settings and credential joins",
+  "version": "0.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-settings-models"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@prettier-ai/dsh-client-ui-settings",
+        "@prettier-ai/dsh-client-locale",
+        "@prettier-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@prettier-ai/dsh-api-remotes": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-settings": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-renderer": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@prettier-ai/dsh-api-remotes": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-store": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-test-runtime": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-settings": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-primitives": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-client-ui-slots": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-client-ui-renderer": "^0.1.2-alpha.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}