@lmzhen/dsh-evolution-ui 0.0.0-stage → 0.32.0

package/lib/types/panels/settings/generated-params.d.ts

@@ -0,0 +1,51 @@
+/**
+ * GENERATED by packages/scripts/gen-param-client-view.mjs — do not edit.
+ *
+ * One card per settings namespace; fields are the E3 rows of the registry, so
+ * the browser half names exactly what the Host half registers.
+ */
+/** One field a card renders a control for. */
+export interface ClientParamField {
+    id: string;
+    group: string;
+    /** U-4: the sibling id this field may not go below (an empty string when the row declares no relation). */
+    atLeast: string;
+    /** 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[];
+    /** Display names for `values`, same order ([] shows the raw value). */
+    valueLabels: readonly string[];
+}
+/** One card: the settings namespace it writes through, the SEAT key its source is looked up by,
+ * and the fields it exposes. A73 (`ClientParamSection.namespace` 一名字两义): the two roles are
+ * spelled separately so a Host may key them differently — `namespace` is what a save writes into
+ * (`update(namespace, patch)`) and what the card title is looked up by; `seatKey` is what the
+ * shell's `sources.sourceFor(...)` probes. Both are the LOADER ROW ID today. */
+export interface ClientParamSection {
+    namespace: string;
+    /** The settings-card seat key the shell probes for this section's source. */
+    seatKey: string;
+    fields: readonly ClientParamField[];
+}
+export declare const CLIENT_PARAM_SECTIONS: readonly ClientParamSection[];
+/**
+ * One bundle that mounts family rows: the plugins.row.config key of a row is
+ * <bundle package name>#<row id>. The names are the SOURCE-plane spellings -
+ * the release rescopes them with every other package literal.
+ */
+export interface ClientRowSeat {
+    bundle: string;
+    rows: readonly string[];
+}
+/** Every (bundle, row) pair the Plugins page can open a configuration page for. */
+export declare const CLIENT_ROW_SEATS: readonly ClientRowSeat[];
+//# sourceMappingURL=generated-params.d.ts.map

package/lib/types/panels/settings/guards.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Is this a non-null, non-array object (what JSON calls an object)?
+ * @param value - the value to test.
+ * @returns whether it is a plain object.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Read a value as a record, or undefined when it is not one.
+ * @param value - the value to read.
+ * @returns the value typed as a record, or undefined.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+//# sourceMappingURL=guards.d.ts.map

package/lib/types/panels/settings/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Browser half: one settings section ("自进化") hosting one card per family row, plus the
+ * Plugins page's per-row configuration entry for each of those rows.
+ *
+ * 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 does the same: inject
+ * the settings shell, register `settings.section`, and host the cards in a keyed
+ * child slot of that section.
+ *
+ * Since G2 that section is one of TWO render sites for the same card body. The other is
+ * the platform's Plugins page: each family row can be opened there, and the page renders
+ * whatever a plugin registered under key `<bundle package name>#<row id>`
+ * (`plugins.row.config`). The page owns that entry's subscription and hands the row's form
+ * in, so that path needs no seat of ours; our own section binds the same card to the
+ * client settings seat (`configForms`).
+ *
+ * The join key is the row's ENTRY ID — the platform derives a settings namespace from the
+ * Loader entry id, and that id is the registry's owner name — so the card, the seat lookup
+ * and the page key all spell one id. The legacy namespace strings in the registry
+ * (`evolution-memory`, …) are the G3 migration source, never a live lookup key.
+ *
+ * A row 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-ui/panels/settings/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { PENDING_CARD_KEY } from './seam.ts';
+/**
+ * Required client services: the slot registry and the locale seat.
+ *
+ * The settings seat (`configForms`) is deliberately NOT here. A required inject for a
+ * service the deployment did not compose leaves this whole browser half PENDING forever —
+ * no error, no section, no UI — and the family is also installed without a settings
+ * surface. It is probed instead, and the cards say what is missing.
+ */
+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;
+/** The pending-window card's key, re-exported from `seam.ts` (the section names it as well). */
+export { PENDING_CARD_KEY };
+/**
+ * Register the locale namespace, the section, its cards, and the per-row configuration entries.
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/panels/settings/messages.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Copy for the evolution settings section and its parameter cards.
+ *
+ * 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.
+ */
+/** 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 seatMissing: "这个界面没有提供设置服务，参数只能看不能改";
+    readonly projectionFailed: "这一块读设置时出错，已记入日志；其它参数不受影响";
+    readonly readonly: "本次会话不允许写入设置（临时运行模式）";
+    readonly apply: "保存";
+    readonly reset: "恢复默认值";
+    readonly empty: "这里没有可改项";
+    readonly changed: "{n} 项已覆盖";
+    readonly discard: "放弃修改";
+    readonly saving: "保存中…";
+    readonly resetting: "恢复中…";
+    readonly writeTargetHost: "保存去向：宿主配置（对所有会话生效）";
+    readonly invalidNumber: "需要一个数字";
+    readonly invalidSelect: "不在允许的取值里";
+    readonly invalidAtLeast: "不能小于同组的 {n}";
+    readonly approvalConfirmNamed: "即将批准：{n}";
+    readonly approvalConfirmYes: "确认批准";
+    readonly approvalConfirmNo: "取消";
+    readonly resetTo: "复位为 {value}";
+    readonly refused: "这个值没有被接受（界面上保持原样）。想看原因：在对话里让它说明。";
+    readonly resetRefused: "恢复默认值没有生效（这一行还是你的值）。想看原因：在对话里让它说明。";
+    readonly cardReview: "会话回顾";
+    readonly cardMemory: "长期记忆";
+    readonly cardToolMemory: "记忆写入";
+    readonly cardCurator: "技能整理";
+    readonly cardSkills: "技能写入规则";
+    readonly cardApproval: "写入审批";
+    readonly cardCommands: "维护扫描";
+    readonly cardMerge: "技能自动合并";
+    readonly approvalCardHint: "写入审批=使用中生成/修改；合并审批=两轮工作流。";
+    readonly mergeCardHint: "写入审批=使用中生成/修改；合并审批=两轮工作流。";
+    readonly approvalTitle: "待批写入";
+    readonly approvalLoading: "正在读取待批项…";
+    readonly approvalEmpty: "没有待批的写入";
+    readonly approvalFailed: "待批项读取失败";
+    readonly approvalRetry: "重试";
+    readonly approvalApprove: "批准";
+    readonly approvalReject: "拒绝";
+    readonly approvalCount: "{n} 项待批";
+    readonly approvalRunningCount: "{n} 项执行中";
+    readonly approvalRefresh: "刷新";
+    readonly approvalExecuting: "执行中：这条的写效果可能已经落地，不要重复批准；要清掉它请用拒绝。";
+    readonly approvalKindMemory: "记忆";
+    readonly approvalKindSkill: "技能";
+    readonly approvalKindCapability: "能力";
+    readonly approvalAgeNow: "刚刚";
+    readonly approvalAgeMinutes: "{n} 分钟前";
+    readonly approvalAgeHours: "{n} 小时前";
+    readonly approvalAgeDays: "{n} 天前";
+    readonly approvalAgeMonths: "{n} 个月前";
+    readonly approvalPreview: "预览";
+    readonly approvalPreviewClose: "收起";
+    readonly approvalPreviewReading: "正在读取预览…";
+    readonly approvalPreviewNone: "看不了预览：";
+    readonly approvalDiffAdded: "{n} 行新增";
+    readonly approvalDiffRemoved: "{n} 行删除";
+    readonly approvalDiffCut: "改动区域已截断";
+    readonly diagTitle: "诊断";
+    readonly diagSubtitle: "运行状态的只读自查；不会改动任何东西。";
+    readonly diagRuntimeTitle: "运行状态";
+    readonly diagSummaryOk: "运行正常";
+    readonly diagSummaryWarn: "{n} 项需要注意";
+    readonly diagSummaryFail: "{n} 项异常";
+    readonly diagSummaryUnknown: "{n} 项待确认";
+    readonly diagRefresh: "刷新";
+    readonly diagRefreshing: "刷新中…";
+    readonly diagStatusOk: "正常";
+    readonly diagStatusWarn: "注意";
+    readonly diagStatusFail: "异常";
+    readonly diagStatusUnknown: "未知";
+    readonly diagRemedy: "建议：";
+    readonly diagNoRows: "没有可显示的运行状态";
+    readonly stateLoading: "正在读取…";
+    readonly failureUnauthorized: "需要登录：重新打开这个页面完成登录后再试。";
+    readonly failureForbidden: "平台拒绝了这个请求（身份不是 owner）。";
+    readonly failureUnmounted: "该功能没有挂载。";
+    readonly failureServer: "读取失败，可以手动重试。";
+    readonly fallbackHint: "可以改用命令：{command}";
+};
+/** 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 zh;
+/**
+ * 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 English (the platform FALLBACK_LOCALE).
+ * @returns the copy this bundle carries.
+ */
+export declare function message(key: MessageKey, language?: 'zh' | 'en'): string;
+/**
+ * Fill one TEMPLATE's `{slot}` placeholders (G5 C4). The seat's translator takes the values, so the
+ * rule lives here instead of at every call site — `t('changed').replace('{n}', …)` used to be
+ * written seven times across three components. An UNKNOWN slot is left standing: a missing value
+ * must not print "undefined" into the operator's UI.
+ * @param template - the resolved copy, with `{slot}` placeholders.
+ * @param values - substitutions keyed by the slot name inside the braces.
+ * @returns the filled copy.
+ */
+export declare function fill(template: string, values: Readonly<Record<string, string | number>>): string;
+/**
+ * Resolve one message and fill its slots in one step: exactly what the seat's `t` does (G5 C4),
+ * for specs and stand-alone callers that hold no seat.
+ * @param key - the copy key.
+ * @param values - substitutions, or undefined for the plain copy.
+ * @returns the copy a reader sees.
+ */
+export declare function formatText(key: MessageKey, values?: Readonly<Record<string, string | number>>): string;
+//# sourceMappingURL=messages.d.ts.map

package/lib/types/panels/settings/pending-state.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The pending card's state machine, kept OUT of the component so the three states the review asked for
+ * can be asserted without a browser (and so a second rendering of the same data cannot invent a fourth).
+ *
+ * The one rule worth naming: LOADING and EMPTY are different states with different copy. The skill
+ * history panel shipped them merged once and a reader could not tell "nothing is staged" from "the
+ * answer has not arrived" (E7).
+ * @module @lmzhen/dsh-evolution-ui/panels/settings/client/pending-state
+ */
+import type { PendingRow, PreviewAnswer } from './api.ts';
+import type { RouteFailure } from '@lmzhen/dsh-evolution-client-kit/generated/route-client';
+/** What one row's preview is showing while it is open. */
+export type PreviewView = {
+    readonly kind: 'loading';
+} | {
+    readonly kind: 'ready';
+    readonly answer: Extract<PreviewAnswer, {
+        available: true;
+    }>;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly failure: RouteFailure;
+};
+/** What the card is showing right now. */
+export type PendingView = {
+    readonly kind: 'loading';
+} | {
+    readonly kind: 'ready';
+    readonly rows: readonly PendingRow[];
+} | {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'failed';
+    readonly failure: RouteFailure;
+};
+/** The whole card state: the view, the ids with an action in flight, and the last refusal line. */
+export interface PendingState {
+    readonly view: PendingView;
+    readonly busy: readonly string[];
+    readonly notice: string | null;
+    /** The row whose preview is open, or null. One at a time: a preview is a thing being read. */
+    readonly open: string | null;
+    readonly preview: PreviewView | null;
+}
+/** The state a card mounts in: still loading, nothing in flight, nothing said yet. */
+export declare const INITIAL_PENDING_STATE: PendingState;
+/** Open one row's preview: the row is now the open one and its answer is on the way. */
+export declare function expanded(state: PendingState, id: string): PendingState;
+/** Close whatever preview is open. */
+export declare function collapsed(state: PendingState): PendingState;
+/**
+ * A preview answer arrived. An answer for a row the reader has already left is DROPPED: it would
+ * otherwise paint one row's diff under another row's heading.
+ */
+export declare function previewArrived(state: PendingState, id: string, view: PreviewView): PendingState;
+/** The first load, or a refresh after a decision: back to loading, keeping no stale rows. */
+export declare function loading(state: PendingState): PendingState;
+/**
+ * A list arrived. An empty list is its OWN state — the reader is told the window is clear rather than
+ * being shown the same line a slow answer shows.
+ */
+export declare function loaded(state: PendingState, rows: readonly PendingRow[]): PendingState;
+/** The list could not be read: the classified failure stays on screen next to a retry control. */
+export declare function failed(state: PendingState, failure: RouteFailure): PendingState;
+/** Mark one record as having an action in flight (its buttons are disabled until it ends). */
+export declare function beginAction(state: PendingState, id: string): PendingState;
+/** The action ended, whatever it answered. */
+export declare function endAction(state: PendingState, id: string): PendingState;
+/** One refusal or failure line under the list; `null` clears it (a later success does). */
+export declare function noticed(state: PendingState, message: string | null): PendingState;
+//# sourceMappingURL=pending-state.d.ts.map

package/lib/types/panels/settings/seam.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Structural view of the client seams this bundle uses.
+ *
+ * The package is distributed OUTSIDE the platform repository, so it declares the
+ * 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 shell's contract: a `settings.section`
+ * registration hosting a keyed card slot, the keyed `plugins.row.config` seat the
+ * Plugins page opens per row, the client settings seat (`configForms`, one form per
+ * Host plugin entry id), and the locale seat the section's copy resolves through.
+ * @module @lmzhen/dsh-evolution-ui/panels/settings/client
+ */
+import type { ReactNode } from 'react';
+/** Our card slot, hosted by the section this bundle registers. */
+export declare const CARD_SLOT = "evolution.namespace.card";
+/** The Plugins page's per-row configuration seat (declared by `ui-plugin-manager`). */
+export declare const ROW_CONFIG_SLOT = "plugins.row.config";
+/**
+ * The key the Plugins page files a row's configuration under.
+ *
+ * Spelled here because the page's own helper cannot be imported (a value import from
+ * another plugin's client half is forbidden):
+ * `ui-plugin-manager`'s config-ledger module is the definition this mirrors.
+ * @param bundle - the bundle package name that declares the row.
+ * @param rowId - the row id that bundle's patch declares.
+ * @returns the `plugins.row.config` key.
+ */
+export declare function rowConfigKey(bundle: string, rowId: string): string;
+/**
+ * The pending-window card's slot key.
+ *
+ * The section pairs cards by key and the parameter cards use their settings namespace; this card has no
+ * namespace (its data comes from the host's approval routes), so it carries a key of its own. The constant
+ * lives HERE and not in `index.ts` because the SECTION has to name it too, and `index.ts` already imports
+ * the section — one definition in the module both sides already share is what keeps that pair acyclic.
+ */
+export declare const PENDING_CARD_KEY = "approval-pending";
+/** The diagnostics card's slot key: read-only, no settings namespace (its data comes from HOST_ROUTES.diagnostics). */
+export declare const DIAGNOSTICS_CARD_KEY = "diagnostics";
+/** Snapshot of one settings row, as the client seat reports it. */
+export interface ParamSectionSnapshot {
+    status: 'loading' | 'ready' | 'unavailable';
+    value: Record<string, unknown> | undefined;
+    /** Raw user section: a key's PRESENCE marks the override, not its value. */
+    user: unknown;
+    writable: boolean;
+    /** U-5: the composition layer a cleared field reverts to (platform `base`, previously dropped). */
+    base: Record<string, unknown> | undefined;
+    /**
+     * Why an `unavailable` snapshot is unavailable: this bundle found no settings seat at
+     * all, or the seat is there and serves no such row. The two read differently to the
+     * operator (one is the UI's own gap, the other is a row that is not composed).
+     */
+    reason?: 'seat-missing' | 'not-served' | 'projection-failed';
+}
+/** The reactive source the renderer binds to a `use<Name>` seat. */
+export interface ParamSectionSource {
+    getSnapshot(): ParamSectionSnapshot;
+    subscribe(listener: () => void): () => void;
+    /**
+     * T5-11/A66: the seat ARRIVED (or was replaced) — bind it and wake every listener.
+     *
+     * The source re-probes on every READ, which covers a card that has not rendered yet; it does not
+     * cover a card that already rendered its "no settings surface" state, because nothing tells React to
+     * read again. `ctx.inject` is the platform's own arrival channel (it runs the callback when the
+     * service appears and re-runs it when the service changes), so the bundle subscribes there instead of
+     * inventing a timer.
+     */
+    revive(): void;
+}
+/** One ordered field operation, as the client settings seat takes them. */
+export interface SettingsPathOpLike {
+    readonly op: 'set' | 'unset';
+    readonly path: readonly string[];
+    readonly value?: unknown;
+}
+/** One row's client form state, as `configForms.get(entryId)` reports it. */
+export interface ConfigFormSnapshotLike<T = Record<string, unknown>> {
+    status: 'loading' | 'ready' | 'unavailable';
+    value: T | undefined;
+    /** Composition layer the Host resolved `value` over; what a cleared field reverts to. */
+    base: unknown;
+    /** Raw user layer: a key's PRESENCE marks the override. */
+    user: unknown;
+    revision: number | undefined;
+    writable: boolean;
+}
+/** One row's client write face (0.2.x `configForms`). */
+export interface ConfigFormLike<T = Record<string, unknown>> {
+    getSnapshot(): ConfigFormSnapshotLike<T>;
+    subscribe(listener: () => void): () => void;
+    set(field: string, value: unknown): Promise<boolean>;
+    unset(field: string): Promise<boolean>;
+    mutate(ops: readonly SettingsPathOpLike[], expectedRevision?: number): Promise<boolean>;
+}
+/**
+ * The client settings seat, probed rather than injected: a deployment may compose the
+ * family without the settings surface, and a REQUIRED inject for a missing service
+ * leaves the whole browser half pending forever (no error, no UI).
+ */
+export interface ConfigFormsSeat {
+    /** One Host plugin entry id to its form. */
+    get<T>(entryId: string): ConfigFormLike<T>;
+}
+/** Registration options the keyed card slot under our own section takes. */
+export interface SlotRegisterOptions {
+    name: typeof CARD_SLOT;
+    /** The settings row this card edits — the slot's key. */
+    key: string;
+    inject: () => unknown;
+}
+/** Registration options the Plugins page's per-row config seat takes. */
+export interface RowSeatRegisterOptions {
+    name: typeof ROW_CONFIG_SLOT;
+    /** `<bundle package name>#<row id>`, as the page's ledger builds it. */
+    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 values and commands the Plugins page passes to a `plugins.row.config` entry:
+ * the page owns the subscription (it re-renders the entry), so the entry renders from
+ * `state` and writes through `mutate`. Both views receive this face; `summary` uses it
+ * only to say whether anything is overridden.
+ */
+export interface RowConfigViewProps {
+    /** `summary` is the row's one-line description fallback; `page` is the whole form. */
+    readonly view: 'summary' | 'page';
+    /** Absent when the Host serves no configuration for this row. */
+    readonly form?: RowConfigForm | undefined;
+}
+/** The row form the page derived from its settings seat. */
+export interface RowConfigForm {
+    readonly state: ConfigFormSnapshotLike;
+    readonly mutate: (ops: readonly SettingsPathOpLike[], revision?: number) => Promise<boolean>;
+}
+/** 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 | RowSeatRegisterOptions | SectionRegisterOptions, component: (props: never) => unknown): () => void;
+    };
+    locale: LocaleSeat;
+}
+//# sourceMappingURL=seam.d.ts.map

package/lib/types/panels/settings/source.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The adapter between the platform's client settings seat and this bundle's cards.
+ *
+ * One place maps `configForms.get(entryId)` to the three things a card needs — a
+ * snapshot, a subscription and the two write calls — so our own section's cards and the
+ * Plugins page's per-row entry cannot drift apart in how they read or write a row.
+ *
+ * Two invariants live here, both required by the renderer's hook seam:
+ *
+ * - **Stable references.** The renderer binds this source through
+ *   `useSyncExternalStoreWithSelector`, which compares the projected snapshot by reference.
+ *   A `getSnapshot()` that builds a new object on every call never compares equal, so the
+ *   card re-renders until React aborts it (minified invariant #185) and the slot error
+ *   boundary replaces the card with an empty placeholder. The projection therefore caches
+ *   per raw snapshot reference.
+ * - **Never throws.** A throw from `getSnapshot()` happens inside the renderer's render pass,
+ *   where this bundle cannot catch it and a card-level `try`/`catch` around a hook call is
+ *   not legal React. Projection failures return a frozen unavailable snapshot instead.
+ *
+ * The seat itself is probed LAZILY: `apply()` runs before the settings shell may be active
+ * (the shell declares `settings.section` and provides `configForms`), so reading the seat at
+ * apply time would capture `undefined` for the whole life of the fiber.
+ * @module @lmzhen/dsh-evolution-ui/panels/settings/client
+ */
+import type { ConfigFormLike, ConfigFormSnapshotLike, ConfigFormsSeat, ParamSectionSnapshot, ParamSectionSource, SettingsPathOpLike } from './seam.ts';
+/** What a card shows when this UI found no settings seat at all. */
+export declare const SEAT_MISSING: ParamSectionSnapshot;
+/** What a card shows when the seat served the row but projecting it failed. A frozen constant
+ * so a failing row keeps ONE reference: a fresh object per call would reintroduce the
+ * render loop this module exists to prevent. */
+export declare const PROJECTION_FAILED: ParamSectionSnapshot;
+import { isRecord as isSection } from './guards.ts';
+export { isSection };
+/**
+ * Project one platform snapshot into the card's own shape.
+ * @param snapshot - the seat's snapshot.
+ * @returns the card's snapshot, with the reason an unavailable one is unavailable.
+ */
+export declare function sectionSnapshotOf(snapshot: ConfigFormSnapshotLike): ParamSectionSnapshot;
+/**
+ * Bind one row's form to a projection that is stable per raw snapshot and never throws.
+ * @param form - the row's client form, as the settings seat hands it over.
+ * @returns the projection the card's hook reads.
+ */
+export declare function stableProjection(form: ConfigFormLike): () => ParamSectionSnapshot;
+/**
+ * The lazily probed client settings seat.
+ *
+ * Probed at read time rather than captured at apply time: this row may activate before the
+ * settings shell, and a captured `undefined` would pin every card to the empty state.
+ * @returns the seat, or undefined while no settings surface is composed.
+ */
+export type SeatProbe = () => ConfigFormsSeat | undefined;
+/**
+ * The live source one row's card binds.
+ * @param probe - the lazily probed settings seat.
+ * @param namespace - the row's entry id.
+ * @returns the source; without a seat it reports the stated empty state, and it re-probes on
+ *   every read so a seat that appears later is picked up without a timer.
+ */
+export declare function sourceFor(probe: SeatProbe, namespace: string): ParamSectionSource;
+/**
+ * The write pair for one row.
+ * @param probe - the lazily probed settings seat.
+ * @param namespace - the row's entry id.
+ * @returns the two calls a card's save/reset path uses; without a seat they resolve without writing.
+ */
+export declare function writeFaceFor(probe: SeatProbe, namespace: string): {
+    mutateOnce: (ops: readonly SettingsPathOpLike[]) => Promise<boolean>;
+    clear: (field: string) => Promise<boolean>;
+};
+/**
+ * One source object per namespace, for the life of the plugin fiber.
+ *
+ * The renderer caches a hook binding per SOURCE OBJECT, so building a source per render
+ * would re-bind the hook and remount the card. The cache is owned by the caller's fiber and
+ * cleared on dispose.
+ * @param probe - the lazily probed settings seat.
+ * @returns the per-namespace source cache and its disposer.
+ */
+export declare function createSourceCache(probe: SeatProbe): {
+    sourceFor: (namespace: string) => ParamSectionSource;
+    /** T5-11/A66: the seat arrived — wake every source this cache built (the cached ones are exactly the
+     * ones whose cards are already mounted and waiting). */
+    revive: () => void;
+    dispose: () => void;
+};
+//# sourceMappingURL=source.d.ts.map

package/lib/types/panels/settings/styles.d.ts

@@ -0,0 +1,32 @@
+/** Tag id that makes the injection idempotent. */
+export declare const CSS_TAG_ID = "@lmzhen/dsh-evolution-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;
+    /** The element shape the injection uses. `remove()` is on the real DOM element and is what the
+     * S5-08 disposer calls, so the host shape names it too - otherwise the package cannot typecheck
+     * without the DOM lib while still using the disposal the browser offers. */
+    createElement(tag: string): {
+        dataset: Record<string, string>;
+        textContent: string;
+        remove(): void;
+    };
+    head: {
+        appendChild(node: unknown): void;
+    };
+}
+/**
+ * Inject the stylesheet once per document.
+ *
+ * S5-08: it RETURNS the disposer. The tag check alone answered only half the question - "is it
+ * there" - and left "who takes it away" to nobody, so a hot reload (unmount, remount) found the old
+ * tag, skipped the injection, and kept serving the PREVIOUS bundle CSS. skill-history hands its
+ * disposer back to the fiber; this is the same shape for the same concern.
+ * @param host - the document to inject into; defaults to the global one.
+ * @returns the disposal; a no-op when there is no document or the tag was already present.
+ */
+export declare function injectStyles(host?: StyleHost): () => void;
+export {};
+//# sourceMappingURL=styles.d.ts.map