@huanlin/dsh-plugin-preface-context 0.1.0

package/lib/types/client/config.js

@@ -0,0 +1,42 @@
+/**
+ * Config schema for the preface-context plugin (Schemastery, strict).
+ *
+ * The plugin-row config (the `entry` passed to `apply`) is the composition
+ * BASE of the `preface-context` settings namespace. The settings user layer
+ * is layered on top (schema defaults → base → user layer) when a settings
+ * service is mounted; without one, the entry is the sole source.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/config
+ */
+import z from 'schemastery';
+/**
+ * Schemastery schema for the `preface-context` settings namespace.
+ *
+ * Strict by construction: unknown keys fail validation here, even though the
+ * settings service itself is non-strict and would otherwise accept them.
+ */
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    contextText: z.string().default(''),
+});
+/** Known config keys (for strict unknown-key rejection). */
+const CONFIG_KEYS = new Set(['enabled', 'contextText']);
+/**
+ * Resolve a raw config patch through the schema, returning a full
+ * {@link PrefaceConfig} with defaults applied. Unknown keys are rejected
+ * here (the settings service itself is non-strict and would otherwise accept
+ * them), matching the Loader's strict validation.
+ * @param input - a partial or complete config object.
+ * @returns the schema-resolved config.
+ * @throws when the input carries an unknown key or a value the schema rejects.
+ */
+export function resolvePrefaceConfig(input) {
+    if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+        for (const key of Object.keys(input)) {
+            if (!CONFIG_KEYS.has(key)) {
+                throw new Error(`preface-context: unknown config key "${key}"`);
+            }
+        }
+    }
+    return Config(input);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Preface-context settings plugin, browser half. Registers the
+ * `preface-context` card into the shell-declared `settings.plugin.item` slot
+ * (the "插件配置" settings page), keyed by the `preface-context` settings
+ * namespace. The card's controller binds the namespace through
+ * `ctx.settingsScope.bind()`, which reads/writes through the standard
+ * `settings.describe` / `settings.mutate` RPCs (the apiproxy accepts any
+ * registered namespace — no allowlist gate on current upstream dsh).
+ *
+ * Export discipline: value-imports ONLY the frozen platform module table
+ * (React / cordis / ui-primitives); every other `@deepseek-ai/*` import is
+ * type-only (erased at build) — values arrive via cordis injection
+ * (`ctx.settingsScope` is the read/write channel).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type PrefaceLocaleKey } from './locales.ts';
+export type { PrefaceCardProps } from './preface-card.tsx';
+export type { PrefaceLocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The preface-context settings card copy. */
+        'settings.preface-context': PrefaceLocaleKey;
+    }
+}
+/**
+ * Required services (cordis fiber inject). `settingsScope` is provided by the
+ * ui-settings base plugin; `locale` by the locale plugin; `slots` is the
+ * composition root. The target slot is declared by ui-settings-plugins'
+ * `configurable` tab, whose activation order relative to this one is
+ * unconstrained; registration depends on the slot through `slots.inject()`.
+ */
+export declare const inject: string[];
+/**
+ * Register the preface-context card once the `settings.plugin.item`
+ * declaration is on the ledger, wire its controller to the settings scope,
+ * and keep it fresh on every pushed invalidation.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/client/index.js

@@ -0,0 +1,50 @@
+/**
+ * Preface-context settings plugin, browser half. Registers the
+ * `preface-context` card into the shell-declared `settings.plugin.item` slot
+ * (the "插件配置" settings page), keyed by the `preface-context` settings
+ * namespace. The card's controller binds the namespace through
+ * `ctx.settingsScope.bind()`, which reads/writes through the standard
+ * `settings.describe` / `settings.mutate` RPCs (the apiproxy accepts any
+ * registered namespace — no allowlist gate on current upstream dsh).
+ *
+ * Export discipline: value-imports ONLY the frozen platform module table
+ * (React / cordis / ui-primitives); every other `@deepseek-ai/*` import is
+ * type-only (erased at build) — values arrive via cordis injection
+ * (`ctx.settingsScope` is the read/write channel).
+ */
+import { PrefaceCard } from "./preface-card.js";
+import { installPrefaceCardStyles } from "./preface-card.css.js";
+import { PrefaceCardController } from "./preface-card-controller.js";
+import { en, zh } from "./locales.js";
+/** Dictionary namespace owned by this plugin. */
+const NS = 'settings.preface-context';
+/** Settings namespace the host half registers (must match the host constant). */
+const SETTINGS_NAMESPACE = 'preface-context';
+/**
+ * Required services (cordis fiber inject). `settingsScope` is provided by the
+ * ui-settings base plugin; `locale` by the locale plugin; `slots` is the
+ * composition root. The target slot is declared by ui-settings-plugins'
+ * `configurable` tab, whose activation order relative to this one is
+ * unconstrained; registration depends on the slot through `slots.inject()`.
+ */
+export const inject = ['slots', 'locale', 'settingsScope'];
+/**
+ * Register the preface-context card once the `settings.plugin.item`
+ * declaration is on the ledger, wire its controller to the settings scope,
+ * and keep it fresh on every pushed invalidation.
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    ctx.effect(installPrefaceCardStyles, 'preface-context: card styles');
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'preface-context: copy dictionaries');
+    const settingsScope = ctx.settingsScope;
+    const controller = new PrefaceCardController(settingsScope.bind({ namespace: SETTINGS_NAMESPACE }));
+    ctx.slots.inject('settings.plugin.item', function* () {
+        yield ctx.slots.register({
+            name: 'settings.plugin.item',
+            key: SETTINGS_NAMESPACE,
+            locale: NS,
+            inject: () => controller.inject(),
+        }, PrefaceCard);
+    });
+}

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

@@ -0,0 +1,7 @@
+/** Locale bundles for the preface-context settings card. */
+/** Locale keys the preface-context card renders. */
+export type PrefaceLocaleKey = 'title' | 'description' | 'enabled' | 'enabledHint' | 'contextText' | 'contextTextHint' | 'contextTextPlaceholder' | 'overridden' | 'reset' | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed' | 'readOnly' | 'expand' | 'collapse';
+/** English copy. */
+export declare const en: Record<PrefaceLocaleKey, string>;
+/** Simplified Chinese copy. */
+export declare const zh: Record<PrefaceLocaleKey, string>;

package/lib/types/client/locales.js

@@ -0,0 +1,41 @@
+/** Locale bundles for the preface-context settings card. */
+/** English copy. */
+export const en = {
+    title: 'Preface context',
+    description: 'Inject a text block as model-visible instructions at the start of every session.',
+    enabled: 'Enabled',
+    enabledHint: 'When off, no context is injected at session start.',
+    contextText: 'Context text',
+    contextTextHint: 'Injected once per session as instructions context, closest to the model\u2019s first answer. Empty text injects nothing.',
+    contextTextPlaceholder: 'Enter the text to inject at the start of every session\u2026',
+    overridden: 'Overridden',
+    reset: 'Reset to default',
+    save: 'Save',
+    saving: 'Saving\u2026',
+    discard: 'Discard',
+    unsaved: 'Unsaved',
+    saveFailed: 'The deployment did not accept these values; they were left for you to correct.',
+    readOnly: 'This deployment stores settings read-only.',
+    expand: 'Show settings',
+    collapse: 'Hide settings',
+};
+/** Simplified Chinese copy. */
+export const zh = {
+    title: '前言上下文',
+    description: '在每次会话开头注入一段文本作为模型可见的指令上下文。',
+    enabled: '启用',
+    enabledHint: '关闭后，会话开始时不注入任何上下文。',
+    contextText: '上下文文本',
+    contextTextHint: '每次会话注入一次，作为指令上下文最贴近模型的首个回答。文本为空则不注入。',
+    contextTextPlaceholder: '输入要在每次会话开头注入的文本\u2026',
+    overridden: '已覆盖',
+    reset: '恢复默认',
+    save: '保存',
+    saving: '保存中\u2026',
+    discard: '放弃修改',
+    unsaved: '未保存',
+    saveFailed: '本部署没有接受这些值，已保留供你修改。',
+    readOnly: '本部署的设置为只读。',
+    expand: '展开设置',
+    collapse: '收起设置',
+};

package/lib/types/client/preface-card-controller.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The preface-context card's staged form over the `preface-context` settings
+ * namespace.
+ *
+ * The upstream `ui-settings-plugins` package owns a `CardForm` helper, but it
+ * is an internal module (not re-exported from the package's `/client` public
+ * face), so an external plugin cannot reuse it. This controller is a slim
+ * equivalent: it stages the two fields (`enabled` boolean, `contextText`
+ * multiline string) and writes them through the bound {@link SettingsScope}
+ * on save, re-deriving its projection whenever the scope or a draft changes.
+ *
+ * Unlike the upstream `CardForm`, the `contextText` field is a multiline
+ * textarea: its draft preserves internal whitespace and newlines (the
+ * upstream `textField` helper trims, which would collapse a multi-paragraph
+ * preface into one line).
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { PrefaceConfig } from '../config.ts';
+/** The two fields this card edits, as draft text. */
+export interface PrefaceDraft {
+    /** `enabled` draft — 'true' or 'false'. */
+    enabled: string;
+    /** `contextText` draft — the raw textarea value, whitespace preserved. */
+    contextText: string;
+}
+/** One field's render state. */
+export interface PrefaceFieldState {
+    /** Draft text the control renders. */
+    text: string;
+    /** Whether saving would leave a user-layer entry for this field. */
+    overridden: boolean;
+}
+/** Card-level state shared with the component. */
+export interface PrefaceCardState {
+    /** False while the namespace is not served to this client. */
+    available: boolean;
+    /** Whether the Host document accepts writes. */
+    writable: boolean;
+    /** Whether the form holds edits that a save would write. */
+    dirty: boolean;
+    /** Whether a save is crossing the wire. */
+    saving: boolean;
+    /** Whether the last save did not land as staged. */
+    failed: boolean;
+    /** The `enabled` field state. */
+    enabled: PrefaceFieldState;
+    /** The `contextText` field state. */
+    contextText: PrefaceFieldState;
+}
+/** The write actions the card's slot entry injects. */
+export interface PrefaceCardActions {
+    /** Stage draft text for one field. */
+    edit: (field: keyof PrefaceDraft, text: string) => void;
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField: (field: keyof PrefaceDraft) => void;
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    save: () => void;
+    /** Drop every staged edit. */
+    discard: () => void;
+}
+/** The registration-side face the card's slot entry injects. */
+export interface PrefaceCardFace {
+    hooks: {
+        /** Card snapshot bound by the renderer as usePrefaceCard. */
+        prefaceCard: SnapshotStore<PrefaceCardState>;
+    };
+}
+/**
+ * Bridges the `preface-context` scope onto the card's staged form.
+ *
+ * Publishes through a snapshot store because slot components read through a
+ * snapshot selector, while both the scope and the local drafts change
+ * underneath; every projection is rebuilt from the two together.
+ */
+export declare class PrefaceCardController {
+    private readonly scope;
+    private readonly store;
+    private readonly staged;
+    private saving;
+    private failed;
+    /** @param scope - the bound settings scope for the `preface-context` namespace. */
+    constructor(scope: SettingsScope<PrefaceConfig>);
+    /** @returns the store the card's component reads through its bound selector. */
+    get snapshot(): SnapshotStore<PrefaceCardState>;
+    private project;
+    private fieldState;
+    /** Build the face the card's slot registration injects. */
+    inject(): PrefaceCardFace & PrefaceCardActions;
+    private stage;
+    private publish;
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    private save;
+}

package/lib/types/client/preface-card-controller.js

@@ -0,0 +1,181 @@
+/**
+ * The preface-context card's staged form over the `preface-context` settings
+ * namespace.
+ *
+ * The upstream `ui-settings-plugins` package owns a `CardForm` helper, but it
+ * is an internal module (not re-exported from the package's `/client` public
+ * face), so an external plugin cannot reuse it. This controller is a slim
+ * equivalent: it stages the two fields (`enabled` boolean, `contextText`
+ * multiline string) and writes them through the bound {@link SettingsScope}
+ * on save, re-deriving its projection whenever the scope or a draft changes.
+ *
+ * Unlike the upstream `CardForm`, the `contextText` field is a multiline
+ * textarea: its draft preserves internal whitespace and newlines (the
+ * upstream `textField` helper trims, which would collapse a multi-paragraph
+ * preface into one line).
+ */
+/** A minimal snapshot store: a value + a listener set. Self-contained so the
+ * controller does not pull `createSnapshotStore` (a browser-bundle symbol)
+ * into its unit-test graph. */
+class MiniSnapshotStore {
+    snapshot;
+    listeners = new Set();
+    constructor(initial) {
+        this.snapshot = initial;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    set(value) {
+        this.snapshot = value;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    update(mutator) {
+        // Shallow-clone then mutate (the projections here are plain objects with
+        // no nested mutation, so a deep immer draft is unnecessary).
+        const draft = Array.isArray(this.snapshot) ? [...this.snapshot] : { ...this.snapshot };
+        mutator(draft);
+        this.set(draft);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+}
+/** The default value for a field when the user-layer carries none. */
+function baseValue(snapshot, field) {
+    return snapshot.base?.[field];
+}
+/** The current resolved value of a field. */
+function sectionValue(snapshot, field) {
+    return snapshot.value?.[field];
+}
+/** Whether the user layer carries an entry for a field. */
+function stored(snapshot, field) {
+    const user = snapshot.user;
+    return user !== undefined && Object.hasOwn(user, field);
+}
+/** Format a stored value as draft text for a field. */
+function format(field, value) {
+    if (field === 'enabled')
+        return value === true ? 'true' : 'false';
+    if (field === 'contextText')
+        return typeof value === 'string' ? value : '';
+    return '';
+}
+/** Parse draft text into a write value, or undefined when invalid. */
+function parse(field, text) {
+    if (field === 'enabled') {
+        // The toggle is a boolean; the textarea is not used for this field.
+        return { value: text === 'true' };
+    }
+    // contextText: empty draft clears the field; otherwise the raw text is the
+    // value. Internal whitespace and newlines are preserved.
+    const trimmed = text.trim();
+    return trimmed === '' ? { clear: true } : { value: text };
+}
+/**
+ * Bridges the `preface-context` scope onto the card's staged form.
+ *
+ * Publishes through a snapshot store because slot components read through a
+ * snapshot selector, while both the scope and the local drafts change
+ * underneath; every projection is rebuilt from the two together.
+ */
+export class PrefaceCardController {
+    scope;
+    store;
+    staged = new Map();
+    saving = false;
+    failed = false;
+    /** @param scope - the bound settings scope for the `preface-context` namespace. */
+    constructor(scope) {
+        this.scope = scope;
+        this.store = new MiniSnapshotStore(this.project());
+        scope.subscribe(() => { this.publish(); });
+    }
+    /** @returns the store the card's component reads through its bound selector. */
+    get snapshot() {
+        return this.store;
+    }
+    project() {
+        const snapshot = this.scope.getSnapshot();
+        const dirty = this.staged.size > 0;
+        return {
+            available: snapshot.status === 'ready',
+            writable: snapshot.writable,
+            dirty,
+            saving: this.saving,
+            failed: this.failed,
+            enabled: this.fieldState(snapshot, 'enabled'),
+            contextText: this.fieldState(snapshot, 'contextText'),
+        };
+    }
+    fieldState(snapshot, field) {
+        const staged = this.staged.get(field);
+        if (staged === undefined) {
+            return { text: format(field, sectionValue(snapshot, field)), overridden: stored(snapshot, field) };
+        }
+        const write = staged.clear ? { clear: true } : parse(field, staged.text);
+        return {
+            text: staged.text,
+            overridden: write !== undefined && 'value' in write,
+        };
+    }
+    /** Build the face the card's slot registration injects. */
+    inject() {
+        return {
+            hooks: { prefaceCard: this.store },
+            edit: (field, text) => { this.stage(field, { text, clear: false }); },
+            resetField: (field) => {
+                this.stage(field, { text: format(field, baseValue(this.scope.getSnapshot(), field)), clear: true });
+            },
+            save: () => { void this.save(); },
+            discard: () => {
+                if (this.staged.size === 0 && !this.failed)
+                    return;
+                this.staged.clear();
+                this.failed = false;
+                this.publish();
+            },
+        };
+    }
+    stage(field, edit) {
+        this.staged.set(field, edit);
+        this.failed = false;
+        this.publish();
+    }
+    publish() {
+        this.store.set(this.project());
+    }
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    async save() {
+        if (this.staged.size === 0 || this.saving)
+            return;
+        this.saving = true;
+        this.failed = false;
+        this.publish();
+        let landed = true;
+        for (const [field, staged] of this.staged) {
+            const write = staged.clear ? { clear: true } : parse(field, staged.text);
+            if (write === undefined)
+                continue;
+            try {
+                if ('clear' in write) {
+                    await this.scope.unset(field);
+                }
+                else {
+                    await this.scope.set(field, write.value);
+                }
+            }
+            catch {
+                landed = false;
+            }
+        }
+        if (landed)
+            this.staged.clear();
+        this.saving = false;
+        this.failed = !landed;
+        this.publish();
+    }
+}

package/lib/types/client/preface-card.css.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Card styles + runtime style injection for the preface-context settings
+ * card.
+ *
+ * The DSH client loader never serves `.css` artifacts — every style must be
+ * injected inside the bundle's factory closure (the same contract the
+ * upstream tsdown.client preset implements with lightningcss). A plain
+ * template-string stylesheet installed once at plugin activation is the slim
+ * equivalent for a hand-rolled bundle: static, prefixed class names
+ * (`dsh-pfc-*`, unique in the document) replace the hashed CSS-modules map,
+ * and the `<style data-plugin-css>` tag is removed when the plugin unloads.
+ *
+ * Colors resolve through `--dsw-alias-*` tokens so the card adapts to the
+ * light/dark theme.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/client/preface-card.css
+ */
+/** Class-name map consumed by the card component (CSS-modules replacement). */
+export declare const css: {
+    readonly card: "dsh-pfc-card";
+    readonly cardOpen: "dsh-pfc-card--open";
+    readonly header: "dsh-pfc-header";
+    readonly headText: "dsh-pfc-head-text";
+    readonly name: "dsh-pfc-name";
+    readonly description: "dsh-pfc-description";
+    readonly pending: "dsh-pfc-pending";
+    readonly chevron: "dsh-pfc-chevron";
+    readonly chevronOpen: "dsh-pfc-chevron--open";
+    readonly body: "dsh-pfc-body";
+    readonly readOnly: "dsh-pfc-readonly";
+    readonly field: "dsh-pfc-field";
+    readonly head: "dsh-pfc-field-head";
+    readonly label: "dsh-pfc-label";
+    readonly badges: "dsh-pfc-badges";
+    readonly badge: "dsh-pfc-badge";
+    readonly reset: "dsh-pfc-reset";
+    readonly textarea: "dsh-pfc-textarea";
+    readonly toggleRow: "dsh-pfc-toggle-row";
+    readonly toggle: "dsh-pfc-toggle";
+    readonly toggleOn: "dsh-pfc-toggle--on";
+    readonly knob: "dsh-pfc-knob";
+    readonly knobOn: "dsh-pfc-knob--on";
+    readonly hint: "dsh-pfc-hint";
+    readonly footer: "dsh-pfc-footer";
+    readonly failed: "dsh-pfc-failed";
+    readonly discard: "dsh-pfc-discard";
+    readonly save: "dsh-pfc-save";
+};
+/**
+ * Install the card stylesheet as one tagged `<style>` element.
+ * @returns the disposer removing the tag (idempotent outside a document).
+ */
+export declare function installPrefaceCardStyles(): () => void;