@lmzhen/dsh-evolution-settings-ui 0.6.1 → 0.8.0

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

@@ -4,13 +4,27 @@
  * Structural local types on purpose: this package is distributed outside the
  * platform repository and a value import of another plugin is forbidden, so the
  * settings scope and its snapshot are declared by the shape the renderer hands
- * over (`getSnapshot`/`subscribe`, status/value/user/writable).
+ * over (\`getSnapshot\`/\`subscribe\`, status/value/user/writable).
+ *
+ * Layout and behaviour follow the platform's own settings fields: a collapsed card
+ * header (namespace title, change count, chevron), then one block per field —
+ * label with its unit and source chip, a control HOLDING THE CURRENT VALUE, the
+ * Chinese hint — and one 放弃修改/保存 pair at the card's foot. The control is
+ * typed from the registry (\`control\`), so booleans are switches, enums are
+ * selects and numbers are numeric inputs with the unit shown beside the label.
  */
 import { type ReactNode } from 'react';
 import type { ClientParamField } from './generated-params.ts';
-import type { MessageKey } from './messages.ts';
+import { type MessageKey } from './messages.ts';
 import type { ParamSectionSnapshot, ParamSectionSource } from './seam.ts';
-/** Injected face: plain data and callbacks, plus the hook seat. */
+/**
+ * Injected face: plain data and callbacks, plus the hook seat.
+ *
+ * The `hooks` compartment belongs to the shell, not to the component: the
+ * renderer binds its entries to `use<Name>` props and omits `hooks` from what
+ * the component receives. A card that reads `props.hooks` therefore reads a prop
+ * that never exists.
+ */
 export interface ParamCardFace {
     namespace: string;
     fields: readonly ClientParamField[];
@@ -21,9 +35,13 @@ export interface ParamCardFace {
         paramSection: ParamSectionSource;
     };
 }
-/** Props the renderer binds for one card: the inject face plus its hook seat. */
-export type ParamCardProps = ParamCardFace & {
-    /** Bound from `hooks.paramSection` by the renderer. */
+/**
+ * Props the renderer binds for one card: the inject face minus its hook compartment,
+ * plus the seats bound from it. Spelled the way the shell derives it, so reaching for
+ * `props.hooks` fails the type check instead of failing at runtime.
+ */
+export type ParamCardProps = Omit<ParamCardFace, 'hooks'> & {
+    /** Bound from \`hooks.paramSection\` by the renderer. */
     readonly useParamSection: <T>(selector: (state: ParamSectionSnapshot) => T) => T;
 };
 /**

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

@@ -0,0 +1,18 @@
+/**
+ * The section shell: title, one-line explanation, then one card per namespace.
+ *
+ * This is the shape the platform's own settings sections use — a heading plus the
+ * child slots it declared in its registration. The cards themselves are separate
+ * registrations keyed by namespace, so a namespace the Host does not serve simply
+ * renders nothing and a deployment that drops this row loses the whole section.
+ * @module @lmzhen/dsh-evolution-settings-ui/client
+ */
+import { type ReactNode } from 'react';
+import { type SectionFace } from './seam.ts';
+/**
+ * Render the section.
+ * @param face - the shell's inject face: translator and child-slot renderer.
+ * @returns the section element.
+ */
+export declare function SettingsSection(face: SectionFace): ReactNode;
+//# sourceMappingURL=SettingsSection.d.ts.map

package/lib/types/client/generated-params.d.ts

@@ -8,8 +8,18 @@
 export interface ClientParamField {
     id: string;
     group: string;
-    /** The registry summary, used as the field help text. */
+    /** The registry summary (English), kept for parity with PARAMETERS.md. */
     doc: string;
+    /** Card label, from the registry UI tail (Chinese). */
+    label: string;
+    /** Card help text, from the registry UI tail (Chinese). */
+    hint: string;
+    /** Which control the card renders. */
+    control: 'number' | 'switch' | 'select' | 'text';
+    /** Unit suffix for a number field ('' when it carries none). */
+    unit: string;
+    /** Allowed values for a select field ([] otherwise). */
+    values: readonly string[];
 }
 /** One card: the settings namespace plus the fields it exposes. */
 export interface ClientParamSection {

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

@@ -1,18 +1,28 @@
 /**
- * Browser half: one card per settings namespace the family registers.
+ * Browser half: one settings section ("自进化") hosting one card per namespace.
  *
- * The join key is the namespace itself — the Host half of each owning plugin
- * registers it, this half claims it in the keyed `settings.plugin.item` slot, and
- * the configuration tab pairs them. A namespace the Host does not serve renders
- * nothing, and a deployment that drops this row shows no cards at all: the pair
- * carries no Host-side behaviour.
+ * Until 0.7.0 the cards lived inside the platform's own 插件 section, because
+ * this bundle injected `@deepseek-ai/dsh-client-ui-settings-plugins` and claimed
+ * its keyed `settings.plugin.item` slot. The parameters are not a plugin
+ * inventory though — the other feature areas (market, skins, Web plugins, side
+ * cards) each register their OWN section, so this bundle now does the same:
+ * inject the settings shell, register `settings.section`, and host the cards in
+ * a keyed child slot of that section.
+ *
+ * The join key is still the namespace itself: the Host half of each owning plugin
+ * registers it, this half claims it in the keyed card slot, and the section pairs
+ * them. A namespace the Host does not serve renders nothing, and a deployment that
+ * drops this row shows no section at all: the pair carries no Host-side behaviour.
  * @module @lmzhen/dsh-evolution-settings-ui/client
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-/** Required client services: the slot registry and the settings transport. */
+/** Required client services: the slot registry, the settings transport, the locale seat. */
 export declare const inject: string[];
+/** Section id and nav order (the platform's own sections sit at 0/10/15/20). */
+export declare const SECTION_ID = "evolution";
+export declare const SECTION_ORDER = 25;
 /**
- * Register one card per generated namespace section.
+ * Register the locale namespace, the section and its cards.
  * @param ctx - client cordis context.
  */
 export declare function apply(ctx: ClientContext): void;

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

@@ -1,29 +1,52 @@
 /**
- * Copy for the evolution parameter cards.
+ * Copy for the evolution settings section and its parameter cards.
  *
- * The bundle carries its own dictionary: this package is distributed outside the
- * platform repository, whose typed locale seats are declared per in-repo
- * namespace. Components never inline a string — the card receives `t` through its
- * inject face, which is where a locale-service binding would plug in later.
+ * The section is registered through the platform's locale seat (`ctx.locale`),
+ * which is the same route the other out-of-repo client plugins take. The earlier
+ * note in this package's README — that an outside package cannot bind the locale
+ * seat — is wrong: `locale.register(namespace, { zh, en })` is the documented
+ * call, and it is what makes the section title and its copy follow the UI
+ * language instead of shipping one hard-coded dictionary.
  */
-/** Message keys the cards render. */
-export declare const MESSAGES: {
-    readonly title: "Evolution parameters";
-    readonly overridden: "user override";
-    readonly deployment: "deployment value";
-    readonly loading: "reading the settings document…";
-    readonly unavailable: "this namespace is not served by the Host (its owning plugin row is not mounted)";
-    readonly readonly: "the settings document is read-only in this session (memory mode)";
-    readonly apply: "Apply";
-    readonly reset: "Reset to deployment";
-    readonly empty: "no writable field in this namespace";
+/** Locale namespace this bundle registers. */
+export declare const NS = "evolution-settings";
+/** Chinese copy (the family's primary language). */
+export declare const zh: {
+    readonly title: "自进化";
+    readonly subtitle: "审查／记忆／策展／技能四个命名空间的参数可在用户层覆盖；此处只列可改项，其余仍由部署面决定。";
+    readonly overridden: "用户";
+    readonly deployment: "部署";
+    readonly loading: "正在读取设置文档…";
+    readonly unavailable: "这个命名空间没有宿主提供服务（对应插件行未挂载）";
+    readonly readonly: "本次会话的设置文档是只读的（内存模式）";
+    readonly apply: "保存";
+    readonly reset: "恢复部署默认";
+    readonly empty: "这个命名空间没有可改项";
+    readonly changed: "{n} 项已改";
+    readonly discard: "放弃修改";
+    readonly saving: "保存中…";
+    readonly refused: "写入未被接受——宿主的校验拒绝了它（值保持原样）。原因见 /evolution params 或 /evolution doctor。";
+    readonly cardReview: "审查";
+    readonly cardMemory: "记忆";
+    readonly cardToolMemory: "记忆工具";
+    readonly cardCurator: "策展";
+    readonly cardSkills: "技能";
 };
+/** English copy, key for key with {@link zh}. */
+export declare const en: Record<keyof typeof zh, string>;
+/**
+ * Card titles per settings namespace. A namespace without an entry falls back to
+ * its raw name, so a Host that registers a new namespace still renders — the
+ * title is presentation, the namespace is the join key.
+ */
+export declare const NAMESPACE_TITLES: Readonly<Record<string, string>>;
 /** One message key. */
-export type MessageKey = keyof typeof MESSAGES;
+export type MessageKey = keyof typeof zh;
 /**
- * Resolve one message.
+ * Resolve one message without the locale seat (tests and the fallback path).
  * @param key - the message key.
+ * @param language - which dictionary to read; defaults to Chinese.
  * @returns the copy this bundle carries.
  */
-export declare function message(key: MessageKey): string;
+export declare function message(key: MessageKey, language?: 'zh' | 'en'): string;
 //# sourceMappingURL=messages.d.ts.map

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

@@ -4,11 +4,15 @@
  * The package is distributed OUTSIDE the platform repository, so it declares the
  * two seams it consumes instead of importing another plugin's values (forbidden
  * by the client bundle-purity rule) or its types (which would drag the platform
- * sources into this project). The shapes are the renderer's contract: a keyed
- * `settings.plugin.item` registration, the inject face it hands back, and the
- * per-namespace settings scope the write path fences with the revision it read.
+ * sources into this project). The shapes are the shell's contract: a
+ * `settings.section` registration hosting a keyed card slot, the inject faces
+ * both hand back, the per-namespace settings scope the write path fences with the
+ * revision it read, and the locale seat the section's copy resolves through.
  * @module @lmzhen/dsh-evolution-settings-ui/client
  */
+import type { ReactNode } from 'react';
+/** Our card slot, hosted by the section this bundle registers. */
+export declare const CARD_SLOT = "evolution.namespace.card";
 /** Snapshot of one settings namespace, as the client scope reports it. */
 export interface ParamSectionSnapshot {
     status: 'loading' | 'ready' | 'unavailable';
@@ -27,23 +31,58 @@ export interface SettingsScopeLike {
     set(field: string, value: unknown): Promise<void>;
     unset(field: string): Promise<void>;
 }
-/** Registration options the keyed slot takes. */
+/** Registration options the keyed card slot under our own section takes. */
 export interface SlotRegisterOptions {
-    name: 'settings.plugin.item';
+    name: typeof CARD_SLOT;
     /** The settings namespace this card edits — the slot's key. */
     key: string;
     inject: () => unknown;
 }
+/** Options a `settings.section` registration carries (the shell's own shape). */
+export interface SectionRegisterOptions {
+    name: 'settings.section';
+    /** Section id; the shell derives the nav entry's DOM id from it. */
+    id: string;
+    /** Nav order: the platform's own sections sit at 0/10/15/20. */
+    order: number;
+    /** Lazy label: the shell re-reads it when the locale changes. */
+    label: () => string;
+    /** Locale namespace the label and the section's copy resolve through. */
+    locale: string;
+    /** Child slots this section hosts, declared for the shell's renderer. */
+    children?: Record<string, {
+        kind: 'keyed' | 'list' | 'single';
+        scope: 'root';
+    }>;
+}
+/**
+ * The face the shell hands a section component: a translator bound to our locale
+ * namespace and the renderer for the child slots we declared.
+ */
+export interface SectionFace {
+    t: (key: string) => string;
+    /** Render one child slot; `filter` selects keyed entries (e.g. `{ entryKey }`). */
+    renderSlot: (name: string, props?: Record<string, unknown>, filter?: Record<string, unknown>) => ReactNode;
+}
+/** The locale seat: register this bundle's namespace, bind a translator. */
+export interface LocaleSeat {
+    register(namespace: string, dictionaries: {
+        zh: Record<string, string>;
+        en: Record<string, string>;
+    }): () => void;
+    bind(namespace: string): (key: string) => string;
+}
 /** The slice of the client context this plugin consumes. */
 export interface ClientSeam {
     slots: {
         inject(name: string, callback: () => Generator<unknown, void, unknown>): unknown;
-        register(options: SlotRegisterOptions, component: (props: never) => unknown): () => void;
+        register(options: SlotRegisterOptions | SectionRegisterOptions, component: (props: never) => unknown): () => void;
     };
     settingsScope: {
         bind(spec: {
             namespace: string;
         }): SettingsScopeLike;
     };
+    locale: LocaleSeat;
 }
 //# sourceMappingURL=seam.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * The save verdict: did the Host take the values this card asked for?
+ *
+ * A write promise that resolves is not a verdict. Both settings scopes this bundle runs
+ * on finish a recovery read before it resolves, so a value the Host refused is simply
+ * still the previous one. Presence in the user layer cannot tell refusal from acceptance
+ * on a field the operator had already overridden — the refused value's key is present
+ * too — so the verdict compares what each staged id holds now against what was requested.
+ * @module @lmzhen/dsh-evolution-settings-ui
+ */
+/** One staged write awaiting its verdict. */
+export interface PendingWrite {
+    /** Parameter id the write named. */
+    readonly id: string;
+    /** The value handed to the scope's `set`. */
+    readonly want: unknown;
+}
+/**
+ * Whether every staged write is visible in the user layer.
+ * @param pending - the writes awaiting a verdict.
+ * @param user - the user layer of the post-write snapshot; a non-section reads as empty.
+ * @returns true when each staged id now holds the value that was requested.
+ */
+export declare function landedWrites(pending: readonly PendingWrite[], user: unknown): boolean;
+//# sourceMappingURL=settle.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * The section's stylesheet.
+ *
+ * The platform's own client bundles compile CSS Modules into a string and inject
+ * it once behind a \`<style data-plugin-css="<pkg>/<file>">\` tag; this bundle is
+ * built outside that pipeline, so it carries its own string and injects it the
+ * same way. Every rule reads the platform's design tokens (\`--dsw-alias-*\`), so
+ * the section follows the light and dark themes without owning a colour, and the
+ * field metrics (12px/6px padding-gap, 13px label, 12px hint) match the ones the
+ * platform's own settings fields use.
+ * @module @lmzhen/dsh-evolution-settings-ui/client
+ */
+/** Tag id that makes the injection idempotent. */
+export declare const CSS_TAG_ID = "@lmzhen/dsh-evolution-settings-ui/settings.css";
+/** The stylesheet the section injects once. */
+export declare const CSS: string;
+/** The slice of the DOM the injection touches (this package typechecks without DOM lib). */
+interface StyleHost {
+    querySelector(selector: string): unknown;
+    createElement(tag: string): {
+        dataset: Record<string, string>;
+        textContent: string;
+    };
+    head: {
+        appendChild(node: unknown): void;
+    };
+}
+/**
+ * Inject the stylesheet once per document.
+ * @param host - the document to inject into; defaults to the global one.
+ */
+export declare function injectStyles(host?: StyleHost): void;
+export {};
+//# sourceMappingURL=styles.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-settings-ui",
   "description": "Web settings cards for the evolution family's parameter namespaces (community build)",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale"
       ]
     }
   },