@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/types/client/member-configuration.js

@@ -0,0 +1,114 @@
+/** One shared source for every visible entry to the same member. */
+export class MemberConfigurationStore {
+    id;
+    face;
+    onIdle;
+    snapshot = { connected: false };
+    listeners = new Set();
+    controller;
+    constructor(id, face, onIdle = () => { }) {
+        this.id = id;
+        this.face = face;
+        this.onIdle = onIdle;
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        if (this.controller === undefined) {
+            const controller = this.controller = new AbortController();
+            void this.follow(controller.signal);
+            void this.followDirectory(controller.signal);
+        }
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size === 0) {
+                this.controller?.abort();
+                this.controller = undefined;
+                this.onIdle();
+            }
+        };
+    };
+    publish(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    accept(state) {
+        if (state.memberId !== this.id || state.revision < (this.snapshot.state?.revision ?? -1))
+            return;
+        this.publish({ state, connected: true, error: undefined });
+    }
+    async follow(signal) {
+        while (!signal.aborted) {
+            try {
+                for await (const state of this.face.follow(this.id, signal)) {
+                    if (signal.aborted)
+                        return;
+                    this.accept(state);
+                }
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    this.publish({ error: error instanceof Error ? error.message : String(error) });
+            }
+            if (signal.aborted)
+                return;
+            this.publish({ connected: false });
+            await pause(signal);
+        }
+    }
+    async followDirectory(signal) {
+        while (!signal.aborted) {
+            try {
+                for await (const directory of this.face.followDirectory(this.id, signal)) {
+                    if (signal.aborted)
+                        return;
+                    this.publish({ directory });
+                }
+            }
+            catch { /* The independent configuration subscription stays available. */ }
+            if (signal.aborted)
+                return;
+            await pause(signal);
+        }
+    }
+    async refreshDirectory() {
+        const directory = await this.face.directory(this.id, true);
+        if (directory !== null)
+            this.publish({ directory });
+    }
+    async refresh() {
+        const before = this.snapshot;
+        const state = await this.face.read(this.id);
+        // A response cannot roll back a stream update received while it was in flight.
+        if (this.snapshot === before && state.memberId === this.id && state.revision >= (before.state?.revision ?? -1))
+            this.publish({ state });
+    }
+}
+function pause(signal) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+        const timer = setTimeout(done, 1_000);
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+export class MemberConfigurationStores {
+    face;
+    stores = new Map();
+    constructor(face) {
+        this.face = face;
+    }
+    get(id) {
+        let store = this.stores.get(id);
+        if (store === undefined)
+            this.stores.set(id, store = new MemberConfigurationStore(id, this.face, () => {
+                if (this.stores.get(id) === store)
+                    this.stores.delete(id);
+            }));
+        return store;
+    }
+}

package/lib/types/client/member-dock.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The member dock: a unified projection-row stack rendered below the member
+ * composer card. Each ambient state (token stats now; tasks / run progress
+ * later) is one CONTRIBUTOR — a pure function from the projection bag to a
+ * line descriptor or null — and registered contributors render in
+ * registration order as separate rows sharing the official StatsLine metrics.
+ * A contributor with no data returns null and its row is omitted; an all-null
+ * stack renders nothing.
+ *
+ * Why a registry: the fallback-hiding lesson (the official dock lives inside
+ * the composer-chain fallback that `overlay: true` hides on election) makes
+ * self-rendered ambient state a repeating pattern in this composer — a second
+ * ad-hoc row would already be a maintenance hazard, so the first refactor
+ * extracts the pattern.
+ * @module @khorsheed/dsh-local-agent/client/member-dock
+ */
+import type { TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client';
+import type { TodoItem } from '@deepseek-ai/dsh-tool-todo/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+/** The locale seat contributors write copy through. */
+type DockTranslate = PropsLocale<typeof NS>['t'];
+/** One rendered dock row. */
+export interface MemberDockLine {
+    /** Stable row id (the contributor's name; also the row's test hook stem). */
+    id: string;
+    /** The fully formatted row text. */
+    text: string;
+}
+/**
+ * The projection bag contributors read. Sourced from the slot kit's
+ * `useProjection` seat — one entry per projection key a contributor needs
+ * (`tokenUsage` now; `todos` / run progress later). An absent unit reads as
+ * undefined, and the contributor drops out whole.
+ */
+export interface MemberDockProjections {
+    /** Session token accounting (the token-meter unit's durable projection). */
+    tokenUsage?: TokenUsageProjection | undefined;
+    /**
+     * The member's current whole todo list (the latest `todo/write` snapshot —
+     * the dsh mirror passes it through; other providers' translation lands in
+     * later milestones), or null before the first write.
+     */
+    todos?: readonly TodoItem[] | null | undefined;
+}
+/**
+ * One dock contributor: a pure function from the projection bag to a row, or
+ * null when its data is absent (the row is then omitted).
+ */
+export type MemberDockContributor = (projections: MemberDockProjections, t: DockTranslate) => MemberDockLine | null;
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
+ * digits) — the official StatsLine's rule, mirrored so the member composer's
+ * stats read identically.
+ * @param n - token count.
+ * @returns display string.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * Cache-hit share of prompt-side input (cacheRead over the three disjoint
+ * billing buckets), the official StatsLine's formula.
+ * @param usage - the session's token-usage projection value.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export declare function cacheHitPercent(usage: TokenUsageProjection): number | null;
+/**
+ * The stats contributor: the member-channel stats line (cache-hit share over
+ * the three billing buckets + compact input/output totals), behavior
+ * byte-identical to the pre-dock implementation — it just returns a dock line
+ * now instead of rendering in place. While a run is in flight the projection
+ * holds the last settled usage — exactly the desired "no live ticking".
+ */
+export declare function statsContributor(projections: MemberDockProjections, t: DockTranslate): MemberDockLine | null;
+/**
+ * The tasks contributor: a compact summary of the member's todo list —
+ * `任务 <done>/<total>` plus the in-progress task's title when one is active
+ * (an all-completed list shows the summary alone). Declines when the session
+ * has no todos at all (unit absent, pre-first-write null, or an empty list).
+ */
+export declare function tasksContributor(projections: MemberDockProjections, t: DockTranslate): MemberDockLine | null;
+/** The registered contributors, in render order. Registration IS inclusion. */
+export declare const MEMBER_DOCK_CONTRIBUTORS: readonly MemberDockContributor[];
+/**
+ * Evaluate contributors over the current projections.
+ * @param projections - the projection bag from the slot kit.
+ * @param t - the locale seat.
+ * @param contributors - the registry; the parameter exists so tests exercise
+ *   the evaluation contract (null rows omitted, registration order) without
+ *   mutating the real registry.
+ * @returns the rows to render, in registration order (possibly empty).
+ */
+export declare function memberDockLines(projections: MemberDockProjections, t: DockTranslate, contributors?: readonly MemberDockContributor[]): MemberDockLine[];
+export {};
+//# sourceMappingURL=member-dock.d.ts.map

package/lib/types/client/member-dock.js

@@ -0,0 +1,102 @@
+/**
+ * The member dock: a unified projection-row stack rendered below the member
+ * composer card. Each ambient state (token stats now; tasks / run progress
+ * later) is one CONTRIBUTOR — a pure function from the projection bag to a
+ * line descriptor or null — and registered contributors render in
+ * registration order as separate rows sharing the official StatsLine metrics.
+ * A contributor with no data returns null and its row is omitted; an all-null
+ * stack renders nothing.
+ *
+ * Why a registry: the fallback-hiding lesson (the official dock lives inside
+ * the composer-chain fallback that `overlay: true` hides on election) makes
+ * self-rendered ambient state a repeating pattern in this composer — a second
+ * ad-hoc row would already be a maintenance hazard, so the first refactor
+ * extracts the pattern.
+ * @module @khorsheed/dsh-local-agent/client/member-dock
+ */
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
+ * digits) — the official StatsLine's rule, mirrored so the member composer's
+ * stats read identically.
+ * @param n - token count.
+ * @returns display string.
+ */
+export function formatTokens(n) {
+    const scaled = (v) => v >= 100 ? String(Math.round(v)) : String(Math.round(v * 10) / 10);
+    if (n < 1_000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${scaled(n / 1_000)}K`;
+    return `${scaled(n / 1_000_000)}M`;
+}
+/**
+ * Cache-hit share of prompt-side input (cacheRead over the three disjoint
+ * billing buckets), the official StatsLine's formula.
+ * @param usage - the session's token-usage projection value.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export function cacheHitPercent(usage) {
+    const billed = usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
+    return billed === 0 ? null : Math.round(usage.cacheReadTokens / billed * 100);
+}
+/**
+ * The stats contributor: the member-channel stats line (cache-hit share over
+ * the three billing buckets + compact input/output totals), behavior
+ * byte-identical to the pre-dock implementation — it just returns a dock line
+ * now instead of rendering in place. While a run is in flight the projection
+ * holds the last settled usage — exactly the desired "no live ticking".
+ */
+export function statsContributor(projections, t) {
+    const usage = projections.tokenUsage;
+    if (usage === undefined)
+        return null;
+    const billed = usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
+    if (billed === 0 && usage.outputTokens === 0)
+        return null;
+    const groups = [];
+    const cacheHit = cacheHitPercent(usage);
+    if (cacheHit !== null)
+        groups.push(t('member.stats.cacheHit', { percent: cacheHit }));
+    groups.push(t('member.stats.tokens', { input: formatTokens(billed), output: formatTokens(usage.outputTokens) }));
+    return { id: 'stats', text: groups.join(' | ') };
+}
+/**
+ * The tasks contributor: a compact summary of the member's todo list —
+ * `任务 <done>/<total>` plus the in-progress task's title when one is active
+ * (an all-completed list shows the summary alone). Declines when the session
+ * has no todos at all (unit absent, pre-first-write null, or an empty list).
+ */
+export function tasksContributor(projections, t) {
+    const todos = projections.todos;
+    if (todos === undefined || todos === null || todos.length === 0)
+        return null;
+    const done = todos.filter(todo => todo.status === 'completed').length;
+    const active = todos.find(todo => todo.status === 'in_progress');
+    let text = t('member.tasks.summary', { done, total: todos.length });
+    if (active !== undefined)
+        text += t('member.tasks.active', { title: active.content });
+    return { id: 'tasks', text };
+}
+/** The registered contributors, in render order. Registration IS inclusion. */
+export const MEMBER_DOCK_CONTRIBUTORS = [
+    statsContributor,
+    tasksContributor,
+];
+/**
+ * Evaluate contributors over the current projections.
+ * @param projections - the projection bag from the slot kit.
+ * @param t - the locale seat.
+ * @param contributors - the registry; the parameter exists so tests exercise
+ *   the evaluation contract (null rows omitted, registration order) without
+ *   mutating the real registry.
+ * @returns the rows to render, in registration order (possibly empty).
+ */
+export function memberDockLines(projections, t, contributors = MEMBER_DOCK_CONTRIBUTORS) {
+    const lines = [];
+    for (const contributor of contributors) {
+        const line = contributor(projections, t);
+        if (line !== null)
+            lines.push(line);
+    }
+    return lines;
+}

package/lib/types/client/member-feed.d.ts

@@ -0,0 +1,24 @@
+import type { LocalAgentMemberFeedEvent, LocalAgentMemberFeedRequest, LocalAgentStreamFrame } from '../types.ts';
+type Channel = LocalAgentMemberFeedRequest['channel'];
+type Value<C extends Channel> = Extract<LocalAgentMemberFeedEvent, {
+    channel: C;
+}>['value'];
+type Follow = (requests: readonly LocalAgentMemberFeedRequest[], signal: AbortSignal) => AsyncIterable<LocalAgentMemberFeedEvent>;
+/** Coalesce unsent suffixes without losing text; no per-token event queue. */
+export declare function coalesceOutput(previous: LocalAgentStreamFrame, next: LocalAgentStreamFrame): LocalAgentStreamFrame;
+/** All member renderers in one browser plugin instance share one Remote stream. */
+export declare class MemberFeeds {
+    private readonly source;
+    private readonly entries;
+    private controller;
+    private scheduled;
+    private disposed;
+    constructor(source: Follow);
+    follow<C extends Channel>(memberId: string, channel: C, signal: AbortSignal): AsyncIterable<Value<C>>;
+    private schedule;
+    private deliver;
+    private run;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=member-feed.d.ts.map

package/lib/types/client/member-feed.js

@@ -0,0 +1,134 @@
+const keyOf = (id, channel) => JSON.stringify([id, channel]);
+/** Coalesce unsent suffixes without losing text; no per-token event queue. */
+export function coalesceOutput(previous, next) {
+    if (next.baseline)
+        return next;
+    const updates = new Map(previous.updates.map(update => [update.id, update]));
+    for (const update of next.updates) {
+        const old = updates.get(update.id);
+        if (old !== undefined && update.revision <= old.revision)
+            continue;
+        updates.set(update.id, update.append && old !== undefined
+            ? { ...update, text: old.text + update.text, append: old.append } : update);
+    }
+    return { baseline: previous.baseline, updates: [...updates.values()], removed: [...new Set([...previous.removed, ...next.removed])] };
+}
+/** All member renderers in one browser plugin instance share one Remote stream. */
+export class MemberFeeds {
+    source;
+    entries = new Map();
+    controller;
+    scheduled = false;
+    disposed = false;
+    constructor(source) {
+        this.source = source;
+    }
+    async *follow(memberId, channel, signal) {
+        if (signal.aborted || this.disposed)
+            return;
+        const key = keyOf(memberId, channel);
+        let entry = this.entries.get(key);
+        if (entry === undefined) {
+            this.entries.set(key, entry = { request: { memberId, channel }, subscribers: new Set() });
+            this.schedule();
+        }
+        const subscriber = { pending: entry.cached };
+        const wake = () => { subscriber.wake?.(); subscriber.wake = undefined; };
+        entry.subscribers.add(subscriber);
+        signal.addEventListener('abort', wake, { once: true });
+        try {
+            while (!signal.aborted && !this.disposed) {
+                if (subscriber.pending === undefined)
+                    await new Promise(resolve => { subscriber.wake = resolve; });
+                if (signal.aborted || this.disposed)
+                    return;
+                const event = subscriber.pending;
+                subscriber.pending = undefined;
+                if (event === undefined)
+                    continue;
+                if (event.channel === 'error')
+                    throw new Error(event.message);
+                yield event.value;
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', wake);
+            entry.subscribers.delete(subscriber);
+            if (entry.subscribers.size === 0 && this.entries.get(key) === entry) {
+                this.entries.delete(key);
+                this.schedule();
+            }
+        }
+    }
+    schedule() {
+        if (this.scheduled || this.disposed)
+            return;
+        this.scheduled = true;
+        queueMicrotask(() => {
+            this.scheduled = false;
+            this.controller?.abort();
+            this.controller = undefined;
+            if (this.disposed || this.entries.size === 0)
+                return;
+            const controller = this.controller = new AbortController();
+            void this.run(controller);
+        });
+    }
+    deliver(event) {
+        const entry = this.entries.get(keyOf(event.memberId, event.channel === 'error' ? event.source : event.channel));
+        if (entry === undefined)
+            return;
+        if (event.channel === 'output') {
+            // A late local subscriber receives a full active baseline, never a suffix.
+            const old = entry.cached?.channel === 'output' ? entry.cached.value : undefined;
+            const items = new Map(event.value.baseline ? [] : old?.updates.map(item => [item.id, item]) ?? []);
+            for (const update of event.value.updates) {
+                const previous = items.get(update.id);
+                if (update.append && previous === undefined)
+                    throw new Error('Member feed suffix without baseline');
+                if (previous !== undefined && update.revision <= previous.revision)
+                    continue;
+                items.set(update.id, { ...update, text: update.append ? previous.text + update.text : update.text });
+            }
+            for (const id of event.value.removed)
+                items.delete(id);
+            entry.cached = { ...event, value: { baseline: true, updates: [...items.values()].map(item => ({ ...item, append: false })), removed: [] } };
+        }
+        else if (event.channel !== 'error')
+            entry.cached = event;
+        for (const subscriber of entry.subscribers) {
+            subscriber.pending = event.channel === 'output' && subscriber.pending?.channel === 'output'
+                ? { ...event, value: coalesceOutput(subscriber.pending.value, event.value) } : event;
+            subscriber.wake?.();
+            subscriber.wake = undefined;
+        }
+    }
+    async run(controller) {
+        try {
+            for await (const event of this.source([...this.entries.values()].map(entry => entry.request), controller.signal)) {
+                if (controller.signal.aborted)
+                    return;
+                this.deliver(event);
+            }
+            if (!controller.signal.aborted)
+                throw new Error('Member feed disconnected');
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                return;
+            for (const entry of this.entries.values())
+                this.deliver({
+                    memberId: entry.request.memberId, channel: 'error', source: entry.request.channel,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.controller?.abort();
+        for (const entry of this.entries.values())
+            for (const subscriber of entry.subscribers)
+                subscriber.wake?.();
+        this.entries.clear();
+    }
+}

package/lib/types/client/request-id.d.ts

@@ -0,0 +1,3 @@
+/** getRandomValues also works on LAN HTTP origins where randomUUID is unavailable. */
+export declare function requestId(): string;
+//# sourceMappingURL=request-id.d.ts.map

package/lib/types/client/request-id.js

@@ -0,0 +1,6 @@
+/** getRandomValues also works on LAN HTTP origins where randomUUID is unavailable. */
+export function requestId() {
+    if (typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    return Array.from(crypto.getRandomValues(new Uint32Array(4)), value => value.toString(16).padStart(8, '0')).join('');
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Dual-line client settings scope for the family settings cards: one
+ * snapshot/write contract over the two host client generations, probed by
+ * capability, never by version.
+ *
+ * - 0.1.5: `ctx.settingsScope.bind({ namespace })` — the removed
+ *   `SettingsScope` face.
+ * - 0.1.7-rc.1: `ctx.configForms.get(entryId)` — the `ConfigForm` controller
+ *   (`packages/client/ui-settings/src/client/config-form.ts`), keyed by the
+ *   plugin row id, which is the same string the 0.1.5 namespace used.
+ *
+ * Both are snapshot stores with ordered field writes, so the cards consume
+ * one structural type. The 0.1.5 card keeps reading old `settings.yaml`
+ * values through the legacy arm; on rc.1 the official one-shot import has
+ * already moved the same-named section into the row's config.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Client-side sync state of one settings namespace. The field set is the
+ * intersection both host lines serve; the cards read `status`, `value`, and
+ * `writable`, the rest ride along for editors that layer on top.
+ */
+export interface SettingsScopeSnapshot<T> {
+    /** `loading` until the first accepted section, `ready` while one stands, `unavailable` when the namespace is not exposed. */
+    readonly status: 'loading' | 'ready' | 'unavailable';
+    /** Last accepted schema-resolved section; undefined before the first acceptance. */
+    readonly value: T | undefined;
+    /** Composition layer a cleared field reverts to, when the owning plugin declared one. */
+    readonly base: unknown;
+    /** Raw user layer as stored; a field's PRESENCE here marks it overridden. */
+    readonly user: unknown;
+    /** Namespace revision fencing the next write. */
+    readonly revision: number | undefined;
+    /** Whether the Host document accepts writes. */
+    readonly writable: boolean;
+    /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
+    readonly mode: 'host' | 'memory';
+}
+/**
+ * The card's settings face: a hooks source (the renderer's `hooks.settings`
+ * compartment turns `getSnapshot`/`subscribe` into the `useSettings` hook)
+ * plus ordered field writes. `set`/`unset` settle after the write and any
+ * latest-write recovery read on both lines (rc.1's `ConfigForm` additionally
+ * resolves whether the Host accepted the write — the cards ignore it).
+ */
+export interface SettingsScope<T> {
+    getSnapshot(): SettingsScopeSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    set(field: string, value: unknown): Promise<unknown>;
+    unset(field: string): Promise<unknown>;
+}
+/**
+ * An inert scope for a composition whose settings client never came up:
+ * reads report `unavailable` (the cards disable their controls, exactly like
+ * an unregistered namespace) and writes never settle a value change.
+ * @returns the degraded scope.
+ */
+export declare function unavailableSettingsScope<T>(): SettingsScope<T>;
+/**
+ * Bind the provider row's settings scope on the host line actually serving.
+ * Returns the channel synchronously; both line probes ride deferred injects,
+ * so the serving line's arm fires as soon as its settings service is up (the
+ * settings client package is a declared client inject of every family
+ * provider, so in a normal composition arming lands immediately) and a
+ * provider mounting first still gets armed later. Absent both — a broken
+ * composition — the channel keeps the card on the degraded face, alive and
+ * disabled.
+ * @param ctx - the provider's client context.
+ * @param entryId - the plugin row id (`local-agent-dsh` and friends), the
+ *   same string the 0.1.5 namespace used.
+ * @returns the bound scope channel.
+ */
+export declare function bindSettingsScope<T>(ctx: Context, entryId: string): SettingsScope<T>;
+//# sourceMappingURL=settings-scope.d.ts.map

package/lib/types/client/settings-scope.js

@@ -0,0 +1,98 @@
+/**
+ * Dual-line client settings scope for the family settings cards: one
+ * snapshot/write contract over the two host client generations, probed by
+ * capability, never by version.
+ *
+ * - 0.1.5: `ctx.settingsScope.bind({ namespace })` — the removed
+ *   `SettingsScope` face.
+ * - 0.1.7-rc.1: `ctx.configForms.get(entryId)` — the `ConfigForm` controller
+ *   (`packages/client/ui-settings/src/client/config-form.ts`), keyed by the
+ *   plugin row id, which is the same string the 0.1.5 namespace used.
+ *
+ * Both are snapshot stores with ordered field writes, so the cards consume
+ * one structural type. The 0.1.5 card keeps reading old `settings.yaml`
+ * values through the legacy arm; on rc.1 the official one-shot import has
+ * already moved the same-named section into the row's config.
+ */
+/**
+ * Observable channel behind the card's settings face: delegates to the armed
+ * line scope and republishes on arming, reporting the degraded face until
+ * either host line's deferred probe arms it. The channel exists because the
+ * line probe cannot run as a direct property read — cordis 4.0.4's
+ * service-access guard throws `cannot get property "<name>" without inject`
+ * on any undeclared `ctx.<service>` touch, and neither service name exists on
+ * the other host line, so a static inject would pend there; `ctx.inject` +
+ * `ctx.get` is the only probe that is safe on both.
+ */
+class SettingsScopeChannel {
+    inner = unavailableSettingsScope();
+    listeners = new Set();
+    getSnapshot = () => this.inner.getSnapshot();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    set = (field, value) => this.inner.set(field, value);
+    unset = (field) => this.inner.unset(field);
+    /** Bind the line-served scope; the first arm wins (the two lines never coexist). */
+    arm(scope) {
+        this.inner = scope;
+        scope.subscribe(() => { this.emit(); });
+        this.emit();
+    }
+    emit() {
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+/**
+ * An inert scope for a composition whose settings client never came up:
+ * reads report `unavailable` (the cards disable their controls, exactly like
+ * an unregistered namespace) and writes never settle a value change.
+ * @returns the degraded scope.
+ */
+export function unavailableSettingsScope() {
+    const snapshot = {
+        status: 'unavailable',
+        value: undefined,
+        base: undefined,
+        user: undefined,
+        revision: undefined,
+        writable: false,
+        mode: 'memory',
+    };
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: () => () => { },
+        set: () => Promise.resolve(false),
+        unset: () => Promise.resolve(false),
+    };
+}
+/**
+ * Bind the provider row's settings scope on the host line actually serving.
+ * Returns the channel synchronously; both line probes ride deferred injects,
+ * so the serving line's arm fires as soon as its settings service is up (the
+ * settings client package is a declared client inject of every family
+ * provider, so in a normal composition arming lands immediately) and a
+ * provider mounting first still gets armed later. Absent both — a broken
+ * composition — the channel keeps the card on the degraded face, alive and
+ * disabled.
+ * @param ctx - the provider's client context.
+ * @param entryId - the plugin row id (`local-agent-dsh` and friends), the
+ *   same string the 0.1.5 namespace used.
+ * @returns the bound scope channel.
+ */
+export function bindSettingsScope(ctx, entryId) {
+    const channel = new SettingsScopeChannel();
+    ctx.inject(['configForms'], (formsCtx) => {
+        const forms = formsCtx.get('configForms');
+        if (typeof forms?.get === 'function')
+            channel.arm(forms.get(entryId));
+    });
+    ctx.inject(['settingsScope'], (legacyCtx) => {
+        const legacy = legacyCtx.get('settingsScope');
+        if (typeof legacy?.bind === 'function')
+            channel.arm(legacy.bind({ namespace: entryId }));
+    });
+    return channel;
+}

package/lib/types/client/use-configuration-menu.d.ts

@@ -0,0 +1,10 @@
+import { type CSSProperties } from 'react';
+/** Shared dismissal and placement for settings and member configuration menus. */
+export declare function useConfigurationMenu(preferred: 'above' | 'below'): {
+    root: import("react").RefObject<HTMLDetailsElement>;
+    panel: import("react").RefObject<HTMLDivElement>;
+    open: boolean;
+    setOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    style: CSSProperties | undefined;
+};
+//# sourceMappingURL=use-configuration-menu.d.ts.map