@deepseek-ai/dsh-client-locale 0.0.1-rc.1

package/lib/index.js

@@ -0,0 +1,26 @@
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/locale-settings.js
+/** Locale preference stored in the Host user-settings document. */
+/** Settings namespace owned by the locale plugin. */
+const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+const LOCALE_PREFERENCE_FIELD = "preference";
+/** Locale identifiers shipped by the browser client. */
+const LOCALE_IDS = ["zh", "en"];
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+const LocaleSettingsSchema = z.object({ [LOCALE_PREFERENCE_FIELD]: z.union([...LOCALE_IDS]).required(false) });
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the browser locale preference. */
+/**
+* Register the durable locale section when a settings provider exists.
+* @param ctx - Host context whose optional settings service owns the section.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(settingsNamespace(LOCALE_SETTINGS_NAMESPACE), LocaleSettingsSchema);
+	});
+}
+//#endregion
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-locale`.
+* @module @deepseek-ai/dsh-client-locale/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-locale";
+/** Cordis companion plugin name. */
+const name = "client-locale-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: ns-by-locale dictionary registry with a stable
+* bind(ns) surface — it emits no cordis events and owns no cross-plugin
+* mutable relation; fallback-chain resolution and locale-store behavior are
+* asserted directly by this package's behavior specs.
+*/
+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/LanguageRow.d.ts

@@ -0,0 +1,16 @@
+import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { createLanguageRowStore } from './settings-store.ts';
+/** Injected business face: the preference write (t rides the standard locale seat). */
+export interface LanguageRowInjected {
+    /** Switch the active locale (a registered locale id). */
+    setLocale: (id: string) => void;
+}
+/** Full component props: runtime share + store share + locale seat + injected face. */
+export type LanguageRowComponentProps = PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createLanguageRowStore>> & PropsLocale<'settings.locale'> & LanguageRowInjected;
+/**
+ * Render the Language row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function LanguageRow({ t, setLocale, useStore }: LanguageRowComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=LanguageRow.d.ts.map

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

@@ -0,0 +1,182 @@
+/**
+ * Browser-side locale registry. Bound translation functions retain stable
+ * identity for injected consumers. The plugin also registers the Language
+ * preference row into the settings General section — the locale feature owns
+ * its own settings surface.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type LocaleDictOf, type LocaleNamespaceMap, type Translate, type TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import { type ClientContext, type SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import { type LocaleId, type LocaleSettings } from '../locale-settings.ts';
+import { type CommonKey } from '../locales/index.ts';
+import { type SettingsLocaleKey } from '../locales/settings.ts';
+export type { LanguageRowComponentProps, LanguageRowInjected } from './LanguageRow.tsx';
+export type { LanguageOptionRow, LanguageRowState } from './settings-store.ts';
+export type { SettingsGeneralItemOwnerProps } from './settings-contract.ts';
+export type { CommonKey } from '../locales/index.ts';
+export type { LocaleId, LocaleSettings } from '../locale-settings.ts';
+export type { Translate, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Shared cross-feature vocabulary, consulted by the lookup chain after the entry's own namespace misses. */
+        common: CommonKey;
+        /** This feature's own settings-row copy (the Language row). */
+        'settings.locale': SettingsLocaleKey;
+    }
+}
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>;
+/** One selectable locale: id plus its self-described display name. */
+export interface LocaleDefinition {
+    /** Locale id (persisted; the setLocale argument). */
+    id: LocaleId;
+    /** Display name in its own language (中文 / English). */
+    label: string;
+}
+/** Immutable locale state published on every change. */
+export interface LocaleSnapshot {
+    /** Active locale id. */
+    active: LocaleId;
+    /** Selectable locales in display order. */
+    locales: readonly LocaleDefinition[];
+    /** Monotonic change counter (registry or active changes). */
+    revision: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        locale: LocaleService;
+    }
+    interface Events {
+        /**
+         * The active locale switched. Dictionary registrations do NOT emit this
+         * event (listeners may re-register slots in response, and boot registers
+         * one namespace per package); continuous render refresh rides the
+         * LocaleFace revision instead.
+         * @param snapshot - Current immutable locale snapshot.
+         * @mode emit
+         */
+        'locale/change'(snapshot: LocaleSnapshot): void;
+    }
+}
+/** Fallback locale consulted after the active locale misses (also the last-resort initial locale). */
+export declare const FALLBACK_LOCALE: LocaleId;
+/** Shared namespace for shell-level texts. */
+export declare const COMMON_NS = "common";
+/** Namespace owning this feature's settings-row copy. */
+export declare const SETTINGS_NS = "settings.locale";
+/**
+ * Dictionary registry plus locale preference. Lookup chain per key: the
+ * entry's namespace in the active locale -> that namespace's zh fallback ->
+ * the shared common namespace (active, then zh) -> the key itself (missing
+ * text stays visible, fail loud in the UI rather than blank). Reads go
+ * through {@link getLocale}; writes only through {@link setLocale};
+ * continuous sync through the `locale/change` event, or through the
+ * LocaleFace getSnapshot/subscribe pair the render machinery consumes
+ * (installed via `ctx.slots.installLocale`).
+ */
+export declare class LocaleService {
+    private dicts;
+    private bound;
+    private snapshot;
+    private listeners;
+    private readonly ctx;
+    private readonly host;
+    /** Browser-derived locale standing wherever no explicit Host selection does. */
+    private readonly provisional;
+    /**
+     * @param ctx - owning context (change events are emitted on it; the scope
+     * listener is released through ctx.effect on dispose).
+     * @param host - durable preference scope owned by the providing plugin;
+     * absent compositions (standalone dictionary registries) stay process-local.
+     */
+    constructor(ctx: Context, host?: SettingsScope<LocaleSettings>);
+    /**
+     * Read the current immutable locale snapshot.
+     * @returns the current snapshot (stable reference until the next change).
+     */
+    getLocale(): LocaleSnapshot;
+    /**
+     * LocaleFace getSnapshot: the current snapshot (carries `revision`; stable
+     * reference between changes, uSES-safe).
+     * @returns the current snapshot.
+     */
+    getSnapshot(): LocaleSnapshot;
+    /**
+     * LocaleFace subscribe: notified on every snapshot change (locale switch
+     * or dictionary registration — registrations bump the revision so already
+     * rendered outlets pick up late-arriving dictionaries).
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Switch the active locale — the only user preference write entry.
+     * @param id - a registered locale id; unknown ids throw.
+     */
+    setLocale(id: string): void;
+    /**
+     * Adopt the scope's accepted durable selection without writing it back; an
+     * absent selection returns to the browser-derived locale.
+     * @param host - the constructor-narrowed scope driving this adoption.
+     */
+    private adopt;
+    /**
+     * Register a declared namespace's dictionaries, all locales in one call —
+     * the typed form: each dictionary is checked against the namespace's
+     * {@link LocaleNamespaceMap} key union (a missing or extra key is a
+     * compile error), and every shipped locale is required (bilingual balance
+     * enforced at registration). Duplicate (ns, locale) throws (single occupant; a
+     * namespace's texts have one owner). Registration bumps the revision so
+     * mounted outlets pick up late-arriving dictionaries.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @param dicts - complete dictionaries keyed by locale id.
+     * @returns disposer removing every locale registered by this call (idempotent).
+     */
+    register<N extends keyof LocaleNamespaceMap & string>(ns: N, dicts: Record<LocaleId, LocaleDictOf<N>>): () => void;
+    /**
+     * Single-locale untyped form for namespaces outside the merge table
+     * (dynamic composition, tests).
+     * @param ns - namespace.
+     * @param locale - locale tag.
+     * @param dict - dictionary.
+     * @returns disposer (idempotent).
+     */
+    register(ns: string, locale: string, dict: LocaleDict): () => void;
+    /**
+     * Bind a declared namespace to a translate function typed to its
+     * dictionary key union (plus the shared common vocabulary) — the same key
+     * domain the framework-injected `t` seat carries. The returned reference
+     * is stable per namespace (repeat binds return the same function), so it
+     * can ride inject surfaces without breaking memoization.
+     * @param ns - a namespace merged into LocaleNamespaceMap.
+     * @returns the typed translate function (reads the active locale at call time).
+     */
+    bind<N extends keyof LocaleNamespaceMap & string>(ns: N): TranslateNS<N>;
+    /**
+     * Untyped form for namespaces outside the merge table (dynamic
+     * composition, tests).
+     * @param ns - namespace.
+     * @returns the translate function.
+     */
+    bind(ns: string): Translate;
+    private translate;
+    private lookup;
+    /**
+     * Advance the snapshot revision and notify LocaleFace subscribers (render
+     * refresh). Only an active-locale switch additionally emits
+     * `locale/change` — dictionary registrations stay off the event so
+     * registration-heavy boot cannot storm event listeners (which may
+     * re-register slots in response).
+     */
+    private publish;
+}
+/** Required services: slot registration plus the settings transport. */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide the locale service with base dictionaries and
+ * register the feature-owned Language preference row into the General
+ * section's item slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * The `settings.general.item` slot type — one preference row inside the
+ * settings General section, contributed by the feature plugin that owns the
+ * preference (locale → Language, ui-theme → Appearance). Options: `id` (row
+ * key), `order` (row position). Rows draw their own internals (row layout,
+ * separators via CSS); the section column only stacks them.
+ *
+ * TYPE HOME RATIONALE: the slot is declared at runtime by
+ * ui-settings-general's General entry, but its type lives here — this
+ * package is the common dependency of every item registrant (any settings
+ * row carries copy, so every registrant already depends on locale), whereas
+ * the declarer's own contract is unreachable for locale/ui-theme without a
+ * reference cycle.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** One preference row inside the settings General section (see module JSDoc). */
+        '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;
+}
+//# sourceMappingURL=settings-contract.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * Language row slot store: a mirror of the locale service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/** One selectable locale row (id + self-described label). */
+export interface LanguageOptionRow {
+    /** Locale id (the setLocale argument). */
+    id: string;
+    /** Display name in its own language (中文 / English). */
+    label: string;
+}
+/** Store state mirrored from the locale snapshot. */
+export interface LanguageRowState {
+    /** Active locale id. */
+    active: string;
+    /** Selectable locales in display order. */
+    options: LanguageOptionRow[];
+    /** Service revision; -1 until first sync so revision 0 lands as a change. */
+    revision: number;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+type LanguageRowActions = {
+    sync: (draft: LanguageRowState, active: string, options: LanguageOptionRow[], revision: number) => void;
+};
+/**
+ * Declares the Language row state and write surface.
+ * @returns the store handle.
+ */
+export declare function createLanguageRowStore(): EngineStoreHandle<LanguageRowState, LanguageRowActions>;
+export {};
+//# sourceMappingURL=settings-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/** Host registration for the browser locale preference. */
+import type { Context } from '@deepseek-ai/cordis';
+export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, type LocaleId, type LocaleSettings, } from './locale-settings.ts';
+/**
+ * Register the durable locale section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-locale`.
+ * @module @deepseek-ai/dsh-client-locale/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-locale-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/locale-settings.d.ts

@@ -0,0 +1,18 @@
+/** Locale preference stored in the Host user-settings document. */
+import z from '@deepseek-ai/schemastery';
+/** Settings namespace owned by the locale plugin. */
+export declare const LOCALE_SETTINGS_NAMESPACE = "locale";
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+export declare const LOCALE_PREFERENCE_FIELD = "preference";
+/** Locale identifiers shipped by the browser client. */
+export declare const LOCALE_IDS: readonly ["zh", "en"];
+/** Shipped locale identifier. */
+export type LocaleId = typeof LOCALE_IDS[number];
+/** Durable locale section shared by the Host schema and the browser scope. */
+export interface LocaleSettings {
+    /** Explicit locale selection; absence delegates to the browser. */
+    preference?: LocaleId;
+}
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+export declare const LocaleSettingsSchema: z<LocaleSettings>;
+//# sourceMappingURL=locale-settings.d.ts.map

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

@@ -0,0 +1,28 @@
+/** en base dictionary for the common namespace, checked complete against the zh key set. */
+export declare const en: {
+    ok: string;
+    cancel: string;
+    close: string;
+    copy: string;
+    copied: string;
+    retry: string;
+    loading: string;
+    'load.failed': string;
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    delete: string;
+    edit: string;
+    save: string;
+    search: string;
+    more: string;
+    collapse: string;
+    expand: string;
+    back: string;
+    unknown: string;
+    none: string;
+    truncated: string;
+};
+//# sourceMappingURL=en.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * The common-namespace dictionary pair. zh is the source of truth for the
+ * key set (Chinese-first repo convention); en is checked complete against it
+ * — a missing or extra en key is a compile error.
+ */
+export { zh } from './zh.ts';
+export { en } from './en.ts';
+export type { CommonKey } from './zh.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,12 @@
+/** `settings.locale` namespace dictionaries (the Language row's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'language.title': string;
+};
+/** The settings.locale namespace key union. */
+export type SettingsLocaleKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'language.title': string;
+};
+//# sourceMappingURL=settings.d.ts.map

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

@@ -0,0 +1,30 @@
+/** zh base dictionary for the common namespace: cross-feature standard words. */
+export declare const zh: {
+    ok: string;
+    cancel: string;
+    close: string;
+    copy: string;
+    copied: string;
+    retry: string;
+    loading: string;
+    'load.failed': string;
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    delete: string;
+    edit: string;
+    save: string;
+    search: string;
+    more: string;
+    collapse: string;
+    expand: string;
+    back: string;
+    unknown: string;
+    none: string;
+    truncated: string;
+};
+/** The common vocabulary key union (zh is the key-set source of truth). */
+export type CommonKey = keyof typeof zh;
+//# sourceMappingURL=zh.d.ts.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@deepseek-ai/dsh-client-locale",
+  "description": "Locale plugin: Host-backed zh/en preference, browser-derived fallback, locale snapshots, and typed namespace dictionaries",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/locale"
+  },
+  "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": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}