@huanlin/dsh-plugin-interpreters 0.2.3 → 0.4.0

package/lib/settings.js

@@ -1,83 +1,82 @@
-/**
- * settings.ts — host-side bridge between the `interpreters` settings namespace
- * and the plugin's other halves (tool registration + RPC gateway).
- *
- * The composition `Config` (cordis.patch.yml) is the first-boot seed; once the
- * `ctx.settings` service mounts, the user-editable layer takes over and live
- * re-registration follows every committed change. Headless assemblies without
- * a settings provider fall back to the composition config (no persistence, no
- * live reload).
- *
- * The bridge pattern mirrors `dsh-advisor/src/settings.ts`: a `source()` thunk
- * the gateway reads in-process, plus an `onChange()` subscription the host
- * entry uses to re-register the tools. This avoids any wire-layer allowlist
- * (the DSH settings RPC domain only serves a fixed namespace set to browser
- * configuration clients; the gateway bypasses it through `/api`).
- *
- * @module dsh-interpreters/settings
- */
-import { settingsNamespace } from '@deepseek-ai/dsh-settings';
-import { Config } from './config.js';
-/** Settings namespace under which interpreter paths persist. */
-export const SETTINGS_NAMESPACE = settingsNamespace('interpreters');
-/**
- * Mirror of the dsh-settings internal `isUnloading` guard. The cordis const
- * enum for fiber state is erased at compile time, so the literal states are
- * matched numerically: 4 = DISPOSED, 5 = UNLOADING.
- */
-function isUnloading(ctx) {
-    const state = ctx.fiber?.state;
-    return state === 4 || state === 5;
-}
-/**
- * Install the `interpreters` settings namespace and return the bridge.
- *
- * The settings service is reached through `ctx.inject(['settings'], ...)` so a
- * composition without a settings provider still loads the plugin (entry-source
- * fallback, no persistence). Multi-fiber dedupe is handled by catching the
- * `"already registered"` rejection — host composition may mount several
- * concurrent fibers of this plugin, and only the first registration owns the
- * namespace.
- * @param ctx - host context.
- * @param entry - composition-layer config (cordis.patch.yml seed).
- * @returns the bridge the gateway and tool re-registration consume.
- */
-export function installInterpretersSettings(ctx, entry) {
-    const listeners = new Set();
-    let source = () => entry;
-    const notify = () => {
-        for (const listener of [...listeners])
-            listener();
-    };
-    ctx.inject(['settings'], (sctx) => {
-        let scope;
-        try {
-            scope = sctx.settings.register(SETTINGS_NAMESPACE, Config, { base: entry });
-        }
-        catch (error) {
-            // Multi-fiber dedupe: the first registration owns the namespace; later
-            // fibers stay on the entry source and emit no notifications of their own.
-            if (!(error instanceof Error) || !error.message.includes('already registered'))
-                throw error;
-            ctx.logger('dsh-interpreters').debug('settings namespace already registered — entry-source fallback');
-            return;
-        }
-        source = () => scope.get();
-        sctx.effect(() => () => {
-            if (isUnloading(ctx))
-                return;
-            source = () => entry;
-            notify();
-        });
-        notify();
-        scope.watch(() => {
-            if (isUnloading(ctx))
-                return;
-            notify();
-        });
-    });
-    return {
-        source: () => source(),
-        onChange: (cb) => { listeners.add(cb); },
-    };
-}
+/**
+ * settings.ts — host-side bridge between the `interpreters` settings namespace
+ * and the plugin's other halves (tool registration + RPC gateway).
+ *
+ * The composition `Config` (cordis.patch.yml) is the first-boot seed; once the
+ * `ctx.settings` service mounts, the user-editable layer takes over and live
+ * re-registration follows every committed change. Headless assemblies without
+ * a settings provider fall back to the composition config (no persistence, no
+ * live reload).
+ *
+ * The bridge pattern mirrors `dsh-advisor/src/settings.ts`: a `source()` thunk
+ * the gateway reads in-process, plus an `onChange()` subscription the host
+ * entry uses to re-register the tools. This avoids any wire-layer allowlist
+ * (the DSH settings RPC domain only serves a fixed namespace set to browser
+ * configuration clients; the gateway bypasses it through `/api`).
+ *
+ * @module dsh-interpreters/settings
+ */
+import { Config } from './config.js';
+/** Settings namespace under which interpreter paths persist. */
+export const SETTINGS_NAMESPACE = 'interpreters';
+/**
+ * Mirror of the dsh-settings internal `isUnloading` guard. The cordis const
+ * enum for fiber state is erased at compile time, so the literal states are
+ * matched numerically: 4 = DISPOSED, 5 = UNLOADING.
+ */
+function isUnloading(ctx) {
+    const state = ctx.fiber?.state;
+    return state === 4 || state === 5;
+}
+/**
+ * Install the `interpreters` settings namespace and return the bridge.
+ *
+ * The settings service is reached through `ctx.inject(['settings'], ...)` so a
+ * composition without a settings provider still loads the plugin (entry-source
+ * fallback, no persistence). Multi-fiber dedupe is handled by catching the
+ * `"already registered"` rejection — host composition may mount several
+ * concurrent fibers of this plugin, and only the first registration owns the
+ * namespace.
+ * @param ctx - host context.
+ * @param entry - composition-layer config (cordis.patch.yml seed).
+ * @returns the bridge the gateway and tool re-registration consume.
+ */
+export function installInterpretersSettings(ctx, entry) {
+    const listeners = new Set();
+    let source = () => entry;
+    const notify = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    ctx.inject(['settings'], (sctx) => {
+        let scope;
+        try {
+            scope = sctx.settings.register(SETTINGS_NAMESPACE, Config, { base: entry });
+        }
+        catch (error) {
+            // Multi-fiber dedupe: the first registration owns the namespace; later
+            // fibers stay on the entry source and emit no notifications of their own.
+            if (!(error instanceof Error) || !error.message.includes('already registered'))
+                throw error;
+            ctx.logger('dsh-interpreters').debug('settings namespace already registered — entry-source fallback');
+            return;
+        }
+        source = () => scope.get();
+        sctx.effect(() => () => {
+            if (isUnloading(ctx))
+                return;
+            source = () => entry;
+            notify();
+        });
+        notify();
+        scope.watch(() => {
+            if (isUnloading(ctx))
+                return;
+            notify();
+        });
+    });
+    return {
+        source: () => source(),
+        onChange: (cb) => { listeners.add(cb); },
+    };
+}

package/lib/types/client/bindSnapshotSelector.js

@@ -1,23 +1,23 @@
-/**
- * uSES bridge: turns any bare observable snapshot source into a typed
- * selector hook. Inlined from dsh-client-ui-renderer/src/client/bind.ts
- * (shell-only glue; business plugins depend on runtime + ui-slots only).
- *
- * @module dsh-interpreters/client/bindSnapshotSelector
- */
-import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector.js';
-/**
- * Bind a bare observable source to a typed uSES selector hook.
- * subscribe/getSnapshot are captured once per source into stable closures
- * (also re-binds `this` for method-based sources), so components never
- * resubscribe across renders. Equality defaults to Object.is.
- * @param w - snapshot source (engine store, Session object, store instance).
- * @returns the selector hook.
- */
-export function bindSnapshotSelector(w) {
-    const subscribe = (fn) => w.subscribe(fn);
-    const getSnapshot = () => w.getSnapshot();
-    return function useSelector(sel, eq) {
-        return useSyncExternalStoreWithSelector(subscribe, getSnapshot, undefined, sel, eq);
-    };
-}
+/**
+ * uSES bridge: turns any bare observable snapshot source into a typed
+ * selector hook. Inlined from dsh-client-ui-renderer/src/client/bind.ts
+ * (shell-only glue; business plugins depend on client-store + ui-slots only).
+ *
+ * @module dsh-interpreters/client/bindSnapshotSelector
+ */
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector.js';
+/**
+ * Bind a bare observable source to a typed uSES selector hook.
+ * subscribe/getSnapshot are captured once per source into stable closures
+ * (also re-binds `this` for method-based sources), so components never
+ * resubscribe across renders. Equality defaults to Object.is.
+ * @param w - snapshot source (engine store, Session object, store instance).
+ * @returns the selector hook.
+ */
+export function bindSnapshotSelector(w) {
+    const subscribe = (fn) => w.subscribe(fn);
+    const getSnapshot = () => w.getSnapshot();
+    return function useSelector(sel, eq) {
+        return useSyncExternalStoreWithSelector(subscribe, getSnapshot, undefined, sel, eq);
+    };
+}

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

@@ -1,39 +1,39 @@
-/**
- * dsh-interpreters — browser half.
- *
- * Registers the `interpreters` card into the shell-declared
- * `settings.plugin.item` slot (the plugin-config settings page — id
- * `dsh-interpreters`, order 50, after the upstream bash / agent-loop /
- * web-search cards). The card's store reads/writes the `interpreters` config
- * through the host gateway `/api/interpreters/get|set` RPC channel, and keeps
- * fresh on pushed invalidations.
- *
- * Export discipline: the client half value-imports ONLY the frozen platform
- * module table (CLIENT_EXTERNALS); every other `@deepseek-ai/*` import is
- * type-only (erased at build) — values arrive via cordis injection
- * (`ctx.get('connection')`, slot inject faces).
- *
- * @module @huanlin/dsh-plugin-interpreters/client
- */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
-import { type InterpretersKey } from './locales.ts';
-export type { InterpretersCardInjected, InterpretersCardProps } from './InterpretersCard.tsx';
-export type { InterpretersKey } from './locales.ts';
-export type { InterpretersCardState, InterpretersCardController } from './store.ts';
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-    interface LocaleNamespaceMap {
-        /** The interpreters card copy. */
-        'interpreters': InterpretersKey;
-    }
-}
-/** Required services (cordis fiber inject). The target slot is declared by
- *  ui-plugin-config's apply, whose activation order relative to this one is
- *  NOT constrained; registration depends on the slot through `slots.inject()`. */
-export declare const inject: string[];
-/**
- * Register the interpreters card once the `settings.plugin.item` declaration
- * is on the ledger, wire its store to the connection, and keep it fresh on
- * every pushed invalidation.
- * @param ctx - client root context.
- */
-export declare function apply(ctx: ClientContext): void;
+/**
+ * dsh-interpreters — browser half.
+ *
+ * Registers the `interpreters` card into the shell-declared
+ * `settings.plugin.item` slot (the plugin-config settings page — id
+ * `dsh-interpreters`, order 50, after the upstream bash / agent-loop /
+ * web-search cards). The card's store reads/writes the `interpreters` config
+ * through the host gateway `/api/interpreters/get|set` RPC channel, and keeps
+ * fresh on pushed invalidations.
+ *
+ * Export discipline: the client half value-imports ONLY the frozen platform
+ * module table (CLIENT_EXTERNALS); every other `@deepseek-ai/*` import is
+ * type-only (erased at build) — values arrive via cordis injection
+ * (`ctx.get('connection')`, slot inject faces).
+ *
+ * @module @huanlin/dsh-plugin-interpreters/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type InterpretersKey } from './locales.ts';
+export type { InterpretersCardInjected, InterpretersCardProps } from './InterpretersCard.tsx';
+export type { InterpretersKey } from './locales.ts';
+export type { InterpretersCardState, InterpretersCardController } from './store.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The interpreters card copy. */
+        'interpreters': InterpretersKey;
+    }
+}
+/** Required services (cordis fiber inject). The target slot is declared by
+ *  ui-plugin-config's apply, whose activation order relative to this one is
+ *  NOT constrained; registration depends on the slot through `slots.inject()`. */
+export declare const inject: string[];
+/**
+ * Register the interpreters card once the `settings.plugin.item` declaration
+ * is on the ledger, wire its store to the connection, and keep it fresh on
+ * every pushed invalidation.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/index.js

@@ -1,94 +1,94 @@
-/**
- * dsh-interpreters — browser half.
- *
- * Registers the `interpreters` card into the shell-declared
- * `settings.plugin.item` slot (the plugin-config settings page — id
- * `dsh-interpreters`, order 50, after the upstream bash / agent-loop /
- * web-search cards). The card's store reads/writes the `interpreters` config
- * through the host gateway `/api/interpreters/get|set` RPC channel, and keeps
- * fresh on pushed invalidations.
- *
- * Export discipline: the client half value-imports ONLY the frozen platform
- * module table (CLIENT_EXTERNALS); every other `@deepseek-ai/*` import is
- * type-only (erased at build) — values arrive via cordis injection
- * (`ctx.get('connection')`, slot inject faces).
- *
- * @module @huanlin/dsh-plugin-interpreters/client
- */
-import { bindSnapshotSelector } from "./bindSnapshotSelector.js";
-import { InterpretersCard } from "./InterpretersCard.js";
-import { InterpretersCardController, refreshIfLoaded } from "./store.js";
-import { en, NS, zh } from "./locales.js";
-import { dicts } from "./dictionaries.js";
-/** Required services (cordis fiber inject). The target slot is declared by
- *  ui-plugin-config's apply, whose activation order relative to this one is
- *  NOT constrained; registration depends on the slot through `slots.inject()`. */
-export const inject = ['slots', 'locale', 'connection'];
-/**
- * Register the interpreters card once the `settings.plugin.item` declaration
- * is on the ledger, wire its store to the connection, and keep it fresh on
- * every pushed invalidation.
- * @param ctx - client root context.
- */
-export function apply(ctx) {
-    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-interpreters: dictionaries');
-    // Opt-in third-language overrides through @huanlin/dsh-plugin-better-locale.
-    // Activation-order-safe: ctx.get('betterLocale') is a non-reactive read, so
-    // if better-locale activates after us, the initial read returns undefined.
-    // We subscribe to ctx.locale — better-locale bumps its revision on activation
-    // (persisted override) and on every override switch — and re-check on each bump.
-    ctx.effect(() => {
-        let dispose;
-        const sync = () => {
-            dispose?.();
-            dispose = undefined;
-            const store = ctx.get('betterLocale');
-            if (store !== undefined) {
-                dispose = store.register(NS, dicts);
-            }
-        };
-        sync();
-        const unsubscribe = ctx.locale.subscribe(sync);
-        return () => {
-            unsubscribe();
-            dispose?.();
-        };
-    }, 'interpreters: better-locale override dicts');
-    // The store reads/writes the interpreters config over the plugin's
-    // self-hosted HTTP route (`/interpreters/api/get` + `/interpreters/api/set`).
-    const controller = new InterpretersCardController();
-    const useSnapshot = bindSnapshotSelector(controller.store);
-    // Pushed invalidations converge the open surface without polling. The dsh
-    // snapshot removed the `settings/changed` host passthrough from the client
-    // runtime Events vocabulary, so convergence rides `connection/reset` — a
-    // connection reset invalidates the whole client state. A burst of resets
-    // coalesces into a single refetch via the microtask debounce, and
-    // `refreshIfLoaded` keeps an unopened card idle.
-    ctx.effect(() => {
-        let pending = false;
-        const refresh = () => {
-            if (pending)
-                return;
-            pending = true;
-            queueMicrotask(() => {
-                pending = false;
-                refreshIfLoaded(controller);
-            });
-        };
-        const disposers = [ctx.on('connection/reset', refresh)];
-        return () => { for (const dispose of disposers)
-            dispose(); };
-    }, 'dsh-interpreters: pushed invalidations');
-    // The card registers into the plugin-config page's card slot with the
-    // upstream card shape — generator + `yield`, `locale: NS`, and an inject
-    // face carrying ONLY the business surface (controller + useSnapshot). The
-    // typed `t` seat is synthesized by the renderer from `locale: NS`.
-    ctx.slots.inject('settings.plugin.item', function* () {
-        yield ctx.slots.register({
-            name: 'settings.plugin.item',
-            key: NS,
-            locale: NS,
-            inject: () => ({ controller, useSnapshot }),
-        }, InterpretersCard);
-    });
-}
+/**
+ * dsh-interpreters — browser half.
+ *
+ * Registers the `interpreters` card into the shell-declared
+ * `settings.plugin.item` slot (the plugin-config settings page — id
+ * `dsh-interpreters`, order 50, after the upstream bash / agent-loop /
+ * web-search cards). The card's store reads/writes the `interpreters` config
+ * through the host gateway `/api/interpreters/get|set` RPC channel, and keeps
+ * fresh on pushed invalidations.
+ *
+ * Export discipline: the client half value-imports ONLY the frozen platform
+ * module table (CLIENT_EXTERNALS); every other `@deepseek-ai/*` import is
+ * type-only (erased at build) — values arrive via cordis injection
+ * (`ctx.get('connection')`, slot inject faces).
+ *
+ * @module @huanlin/dsh-plugin-interpreters/client
+ */
+import { bindSnapshotSelector } from "./bindSnapshotSelector.js";
+import { InterpretersCard } from "./InterpretersCard.js";
+import { InterpretersCardController, refreshIfLoaded } from "./store.js";
+import { en, NS, zh } from "./locales.js";
+import { dicts } from "./dictionaries.js";
+/** Required services (cordis fiber inject). The target slot is declared by
+ *  ui-plugin-config's apply, whose activation order relative to this one is
+ *  NOT constrained; registration depends on the slot through `slots.inject()`. */
+export const inject = ['slots', 'locale', 'connection'];
+/**
+ * Register the interpreters card once the `settings.plugin.item` declaration
+ * is on the ledger, wire its store to the connection, and keep it fresh on
+ * every pushed invalidation.
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-interpreters: dictionaries');
+    // Opt-in third-language overrides through @huanlin/dsh-plugin-better-locale.
+    // Activation-order-safe: ctx.get('betterLocale') is a non-reactive read, so
+    // if better-locale activates after us, the initial read returns undefined.
+    // We subscribe to ctx.locale — better-locale bumps its revision on activation
+    // (persisted override) and on every override switch — and re-check on each bump.
+    ctx.effect(() => {
+        let dispose;
+        const sync = () => {
+            dispose?.();
+            dispose = undefined;
+            const store = ctx.get('betterLocale');
+            if (store !== undefined) {
+                dispose = store.register(NS, dicts);
+            }
+        };
+        sync();
+        const unsubscribe = ctx.locale.subscribe(sync);
+        return () => {
+            unsubscribe();
+            dispose?.();
+        };
+    }, 'interpreters: better-locale override dicts');
+    // The store reads/writes the interpreters config over the plugin's
+    // self-hosted HTTP route (`/interpreters/api/get` + `/interpreters/api/set`).
+    const controller = new InterpretersCardController();
+    const useSnapshot = bindSnapshotSelector(controller.store);
+    // Pushed invalidations converge the open surface without polling. The dsh
+    // client Events vocabulary has no `settings/changed` host passthrough, so
+    // convergence rides `connection/reset` — a
+    // connection reset invalidates the whole client state. A burst of resets
+    // coalesces into a single refetch via the microtask debounce, and
+    // `refreshIfLoaded` keeps an unopened card idle.
+    ctx.effect(() => {
+        let pending = false;
+        const refresh = () => {
+            if (pending)
+                return;
+            pending = true;
+            queueMicrotask(() => {
+                pending = false;
+                refreshIfLoaded(controller);
+            });
+        };
+        const disposers = [ctx.on('connection/reset', refresh)];
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'dsh-interpreters: pushed invalidations');
+    // The card registers into the plugin-config page's card slot with the
+    // upstream card shape — generator + `yield`, `locale: NS`, and an inject
+    // face carrying ONLY the business surface (controller + useSnapshot). The
+    // typed `t` seat is synthesized by the renderer from `locale: NS`.
+    ctx.slots.inject('settings.plugin.item', function* () {
+        yield ctx.slots.register({
+            name: 'settings.plugin.item',
+            key: NS,
+            locale: NS,
+            inject: () => ({ controller, useSnapshot }),
+        }, InterpretersCard);
+    });
+}