@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/lib/types/client/plugin-card-seat.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Family plugin-card seat.
+ *
+ * A family plugin contributes its settings card to whichever plugin-card seat
+ * the running host actually renders:
+ *
+ * - `web-ui.plugin.item` — the list seat declared by the dsh-web-settings
+ *   group section (this family's own first-level "Web UI plugins" section);
+ * - `plugins.bundle.config` — the official keyed seat of the harness's plugin
+ *   manager page, keyed by the bundle's package name and rendered on that
+ *   bundle's page. alpha.2 removed the `settings.plugin.item` keyed seat of the
+ *   `ui-settings-plugins` tab that this helper used before, so a card keyed by
+ *   its settings namespace has no seat to land in any more.
+ *
+ * SEAT SELECTION IS NOT A DECLARATION PROBE. The official plugin surface
+ * belongs to the harness bundle and declares its seats before any external
+ * plugin's `apply()` runs, so "is the official seat declared?" answers yes even
+ * in the deployment whose whole point is the family group. Choosing on that
+ * probe sends every family card to the official page and leaves the group's own
+ * section permanently empty — the family of reports where the section renders
+ * its heading and zero cards.
+ *
+ * The signal that actually distinguishes the two deployments is whether
+ * dsh-web-settings is loaded: it is the package that owns the group section and
+ * it publishes the `webUiSettings` service during `apply()`, which every
+ * family plugin already reads for its settings form. Group loaded -> the family
+ * seat; group absent -> the official seat.
+ *
+ * The decision is re-evaluated on every `slots/changed` because the group may
+ * apply after this plugin (the family aggregate orders it first, a profile that
+ * installs the group separately need not): the initial contribution goes to the
+ * official seat, then moves to the family seat the moment the group's section
+ * registers. The entry is disposed before the replacement is registered, so a
+ * card is never in two seats at once.
+ *
+ * The shared tree has no client-SDK dependency, so this module reads its
+ * context through the structural shape below; callers pass the plugin's own
+ * `ctx`.
+ */
+/** The family list seat key. */
+export declare const FAMILY_PLUGIN_CARD_SEAT = "web-ui.plugin.item";
+/** The official keyed plugin-card seat key (the alpha.2 bundle-configuration seat). */
+export declare const OFFICIAL_PLUGIN_CARD_SEAT = "plugins.bundle.config";
+/** The service dsh-web-settings publishes while it is loaded. */
+export declare const FAMILY_GROUP_SERVICE = "webUiSettings";
+/** The slot-registry member this helper uses (structurally satisfied by ctx.slots). */
+export interface PluginCardSlots {
+    /** Contribution of one card entry. */
+    register(options: never, component: never): unknown;
+}
+/** The slice of the client context a card contribution needs. */
+export interface PluginCardContext {
+    slots: PluginCardSlots;
+    /** Service lookup; absent on a context double that only models the slots. */
+    get?(name: string): unknown;
+    /** Event subscription seat; absent on an event-less test double. */
+    on?(event: string, listener: (...args: never[]) => void): unknown;
+}
+/** Owner share of a family list-seat card (that seat supplies nothing). */
+export interface SettingsPluginItemOwnerProps {
+    /** Marker field: card owner props are intentionally empty. */
+    children?: never;
+}
+/** One family plugin's card contribution. */
+export interface PluginCardSeat {
+    /**
+     * Npm package name of the bundle this card configures; the official keyed
+     * seat dispatches on it. Every family package ships its own bundle patch, so
+     * a standalone install lists that package as the bundle whose page renders
+     * this card.
+     */
+    bundle: string;
+    /** Family list-seat entry id. */
+    id: string;
+    /** Family list-seat sort order. */
+    order?: number;
+    /** Family list-seat display label; the official keyed seat carries none. */
+    label?: () => string;
+    /** Locale namespace the card renders with. */
+    locale: string;
+    /** Business-face factory of the registration. */
+    inject?: () => object;
+    /**
+     * The card component. Its props type is the seat's composed shape, which is
+     * chosen at runtime, so the helper takes it erased; the registrant keeps its
+     * own precise typing at the call site.
+     */
+    component: unknown;
+}
+/**
+ * Whether the family group (dsh-web-settings) is loaded in this page. The
+ * service is the group package's own contract, so the probe cannot be fooled
+ * by a harness release that starts declaring the official seat differently.
+ */
+export declare function familyGroupLoaded(ctx: PluginCardContext): boolean;
+/**
+ * Contribute one family plugin card to the seat this host renders, following
+ * the group if it loads later. The entry is disposed and re-registered on a
+ * seat change, never duplicated.
+ * @param ctx - client context (its slot registry decides the seat).
+ * @param seat - the card contribution.
+ */
+export declare function installPluginCard(ctx: PluginCardContext, seat: PluginCardSeat): void;
+//# sourceMappingURL=plugin-card-seat.d.ts.map

package/lib/types/client/plugin-card-seat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-card-seat.d.ts","sourceRoot":"","sources":["../../../src/client/plugin-card-seat.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,gCAAgC;AAChC,eAAO,MAAM,uBAAuB,uBAAuB,CAAA;AAE3D,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,0BAA0B,CAAA;AAEhE,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AAEnD,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,OAAO,CAAA;CACpD;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAA;IACtB,6EAA6E;IAC7E,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC3B,oEAAoE;IACpE,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,OAAO,CAAA;CAClE;AAED,2EAA2E;AAC3E,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IACpB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAUjE;AAWD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CA4DpF"}

package/lib/types/client/plugin-card-seat.js

@@ -0,0 +1,143 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/plugin-card-seat.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family plugin-card seat.
+ *
+ * A family plugin contributes its settings card to whichever plugin-card seat
+ * the running host actually renders:
+ *
+ * - `web-ui.plugin.item` — the list seat declared by the dsh-web-settings
+ *   group section (this family's own first-level "Web UI plugins" section);
+ * - `plugins.bundle.config` — the official keyed seat of the harness's plugin
+ *   manager page, keyed by the bundle's package name and rendered on that
+ *   bundle's page. alpha.2 removed the `settings.plugin.item` keyed seat of the
+ *   `ui-settings-plugins` tab that this helper used before, so a card keyed by
+ *   its settings namespace has no seat to land in any more.
+ *
+ * SEAT SELECTION IS NOT A DECLARATION PROBE. The official plugin surface
+ * belongs to the harness bundle and declares its seats before any external
+ * plugin's `apply()` runs, so "is the official seat declared?" answers yes even
+ * in the deployment whose whole point is the family group. Choosing on that
+ * probe sends every family card to the official page and leaves the group's own
+ * section permanently empty — the family of reports where the section renders
+ * its heading and zero cards.
+ *
+ * The signal that actually distinguishes the two deployments is whether
+ * dsh-web-settings is loaded: it is the package that owns the group section and
+ * it publishes the `webUiSettings` service during `apply()`, which every
+ * family plugin already reads for its settings form. Group loaded -> the family
+ * seat; group absent -> the official seat.
+ *
+ * The decision is re-evaluated on every `slots/changed` because the group may
+ * apply after this plugin (the family aggregate orders it first, a profile that
+ * installs the group separately need not): the initial contribution goes to the
+ * official seat, then moves to the family seat the moment the group's section
+ * registers. The entry is disposed before the replacement is registered, so a
+ * card is never in two seats at once.
+ *
+ * The shared tree has no client-SDK dependency, so this module reads its
+ * context through the structural shape below; callers pass the plugin's own
+ * `ctx`.
+ */
+/** The family list seat key. */
+export const FAMILY_PLUGIN_CARD_SEAT = 'web-ui.plugin.item';
+/** The official keyed plugin-card seat key (the alpha.2 bundle-configuration seat). */
+export const OFFICIAL_PLUGIN_CARD_SEAT = 'plugins.bundle.config';
+/** The service dsh-web-settings publishes while it is loaded. */
+export const FAMILY_GROUP_SERVICE = 'webUiSettings';
+/**
+ * Whether the family group (dsh-web-settings) is loaded in this page. The
+ * service is the group package's own contract, so the probe cannot be fooled
+ * by a harness release that starts declaring the official seat differently.
+ */
+export function familyGroupLoaded(ctx) {
+    const get = ctx.get;
+    if (typeof get !== 'function')
+        return false;
+    try {
+        return get.call(ctx, FAMILY_GROUP_SERVICE) !== undefined;
+    }
+    catch {
+        // A context that refuses the lookup: treat the group as absent, which
+        // falls back to the official seat the harness declares.
+        return false;
+    }
+}
+/** Report a refused registration instead of leaving the user with no card. */
+function warnRefusedSeat(seat, error) {
+    try {
+        console.warn(`[dsh-web] plugin card registration into "${seat}" was refused; the card will not render`, error);
+    }
+    catch {
+        // Best-effort console write; a failed warning must not break the plugin.
+    }
+}
+/**
+ * Contribute one family plugin card to the seat this host renders, following
+ * the group if it loads later. The entry is disposed and re-registered on a
+ * seat change, never duplicated.
+ * @param ctx - client context (its slot registry decides the seat).
+ * @param seat - the card contribution.
+ */
+export function installPluginCard(ctx, seat) {
+    const slots = ctx.slots;
+    const component = seat.component;
+    const inject = seat.inject;
+    let dispose;
+    let current;
+    /**
+     * Re-entrancy latch. The registry emits a change event synchronously from
+     * inside both `register` and the previous entry's disposer, so an unguarded
+     * reconcile would re-enter itself mid-move and register the card twice into
+     * the seat it is leaving ("already has an entry for key ...").
+     */
+    let reconciling = false;
+    /** Reconcile the contribution with the currently live seat (no-op when unchanged). */
+    const reconcile = () => {
+        if (reconciling)
+            return;
+        const target = familyGroupLoaded(ctx) ? FAMILY_PLUGIN_CARD_SEAT : OFFICIAL_PLUGIN_CARD_SEAT;
+        if (current === target)
+            return;
+        reconciling = true;
+        const previous = dispose;
+        dispose = undefined;
+        current = undefined;
+        previous?.();
+        try {
+            dispose = slots.register((target === FAMILY_PLUGIN_CARD_SEAT
+                ? {
+                    name: FAMILY_PLUGIN_CARD_SEAT,
+                    id: seat.id,
+                    ...(seat.order === undefined ? {} : { order: seat.order }),
+                    ...(seat.label === undefined ? {} : { label: seat.label }),
+                    locale: seat.locale,
+                    ...(seat.inject === undefined ? {} : { inject }),
+                }
+                : {
+                    name: OFFICIAL_PLUGIN_CARD_SEAT,
+                    key: seat.bundle,
+                    locale: seat.locale,
+                    ...(seat.inject === undefined ? {} : { inject }),
+                }), component);
+            current = target;
+        }
+        catch (error) {
+            warnRefusedSeat(target, error);
+        }
+        finally {
+            reconciling = false;
+        }
+    };
+    if (typeof ctx.on === 'function') {
+        try {
+            ctx.on('slots/changed', () => { reconcile(); });
+        }
+        catch {
+            // An event seat that refuses the subscription leaves the initial
+            // decision in place; the card still renders in the seat chosen below.
+        }
+    }
+    // The initial decision: the group, when it is already loaded (the aggregate
+    // order), otherwise the official seat the harness declares.
+    reconcile();
+}

package/lib/types/client/remote-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-channel.d.ts","sourceRoot":"","sources":["../../../src/client/remote-channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-channel.d.ts","sourceRoot":"","sources":["../../../src/client/remote-channel.ts"],"names":[],"mappings":"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"}

package/lib/types/client/remote-channel.js

@@ -43,7 +43,11 @@ export function remoteChannelRequired(hostname, snapshot, hostPairingPolicy) {
  * @returns true for localhost, IPv6 loopback, or any 127/8 literal.
  */
 export function isLoopbackHostname(hostname) {
-    if (hostname === 'localhost' || hostname === '::1')
+    // WHATWG location.hostname keeps IPv6 literals bracketed ("[::1]"); the
+    // host-side shared predicate accepts that spelling, so this browser copy must
+    // too, or an IPv6-loopback origin is judged remote and rewrites every call
+    // onto the gated channel where it can never pair.
+    if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]')
         return true;
     const parts = hostname.split('.');
     return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
@@ -193,11 +197,17 @@ export function installRemoteChannel(window, options = {}) {
             return init;
         const headers = init?.headers;
         if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+            // Copy instead of mutating: the instance belongs to the caller, which may
+            // reuse it for a request this channel does not rewrite (the device
+            // credential must not ride along there).
             try {
-                headers.set(RULES.deviceHeader, device);
+                const copy = new Headers(headers);
+                copy.set(RULES.deviceHeader, device);
+                return { ...init, headers: copy };
+            }
+            catch {
+                return init;
             }
-            catch { /* ignore */ }
-            return init;
         }
         if (typeof headers === 'object' && headers !== null) {
             return { ...init, headers: { ...headers, [RULES.deviceHeader]: device } };
@@ -218,7 +228,10 @@ export function installRemoteChannel(window, options = {}) {
                 ? rewritten.toString()
                 : new Request(rewritten, input);
             return Promise.resolve(originalFetch.call(window, next, attach(init))).then(async (response) => {
-                if (await isUnpairedDenied(response.clone()))
+                // The clone tees the response body; only the 403 branch inspects it, so
+                // every other status skips the copy (a large upload or session dump
+                // would otherwise be duplicated per gated request).
+                if (response.status === 403 && await isUnpairedDenied(response.clone()))
                     options.onUnpaired?.();
                 else
                     options.onPaired?.();

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

@@ -6,7 +6,7 @@
  * each plugin's client bundle; mirrors the official ui-plugin-config
  * card-store pattern.
  */
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 /** The write one field's staged text performs when the card is saved. */
 export type FieldWrite = {
@@ -86,7 +86,7 @@ export interface CardActions {
     /** Drop every staged edit. */
     discard: () => void;
 }
-/** One durable write inside the save's atomic scope mutation. */
+/** One durable write inside the save's atomic form mutation. */
 export interface BatchedWrite {
     /** Field this entry writes. */
     field: string;
@@ -130,20 +130,20 @@ export declare class CardForm<T> {
     private readonly specs;
     private readonly staged;
     private readonly listeners;
-    /** The scope subscription installed in the constructor; released by dispose(). */
-    private readonly disposeScope;
+    /** The form subscription installed in the constructor; released by dispose(). */
+    private readonly disposeForm;
     private disposed;
     private saving;
     private failed;
     private failedReason;
-    /** @param scope - the bound settings scope for this card's namespace. */
-    constructor(scope: SettingsScope<T>, specs: FieldSpec[]);
+    /** @param scope - the bound configuration form for this card's namespace. */
+    constructor(scope: ConfigForm<T>, specs: FieldSpec[]);
     /**
-     * Release the scope subscription and every bound store listener. The card
+     * Release the form subscription and every bound store listener. The card
      * must call this on teardown; later calls are no-ops.
      */
     dispose(): void;
-    /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+    /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
     bind<S>(project: () => S): SnapshotStore<S>;
     /** Read the card-level state: what the Host serves, and what a save would do. */
     shell(): CardShell;
@@ -152,19 +152,19 @@ export declare class CardForm<T> {
     /** The actions the card's slot registration injects. */
     actions(): CardActions;
     /**
-     * Write every staged edit in one atomic scope mutation, then re-seed from
+     * Write every staged edit in one atomic form mutation, then re-seed from
      * what the Host accepted.
      *
      * The whole batch rides one mutate, so cross-field validate hooks
      * (baseURL+model) judge it as a unit: the Host either applies every write
-     * or refuses the batch. The 0.1.2 scope contract never rejects a refused
-     * mutation — the scope recovers with a fresh Host view and resolves — so
-     * resolution alone proves nothing: the outcome is judged by reading the
-     * settled snapshot back, one planned write at a time, and one missed write
-     * fails the whole save. A scope that still rejects on refusal (the dsh-web
-     * bridge scope) reports through the same failure path with its rejection
-     * message. A save that did not land keeps its drafts, so the user can
-     * correct them instead of retyping.
+     * or refuses the batch. The form contract answers a refusal or a skipped
+     * write with `false` (it recovers with a fresh Host view instead of
+     * throwing), so the outcome is judged twice: the answer itself, and then the
+     * settled snapshot read back one planned write at a time. One missed write
+     * fails the whole save. A transport that rejects instead (the dsh-web bridge
+     * controller on a dead connection) reports through the same failure path
+     * with its rejection message. A save that did not land keeps its drafts, so
+     * the user can correct them instead of retyping.
      * @returns settlement after the mutation and the read-back.
      */
     save(): Promise<void>;

package/lib/types/client/settings-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-form.d.ts","sourceRoot":"","sources":["../../../src/client/settings-form.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings-form.d.ts","sourceRoot":"","sources":["../../../src/client/settings-form.ts"],"names":[],"mappings":"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"}

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

@@ -91,30 +91,30 @@ export class CardForm {
     specs;
     staged = new Map();
     listeners = new Set();
-    /** The scope subscription installed in the constructor; released by dispose(). */
-    disposeScope;
+    /** The form subscription installed in the constructor; released by dispose(). */
+    disposeForm;
     disposed = false;
     saving = false;
     failed = false;
     failedReason;
-    /** @param scope - the bound settings scope for this card's namespace. */
+    /** @param scope - the bound configuration form for this card's namespace. */
     constructor(scope, specs) {
         this.scope = scope;
         this.specs = new Map(specs.map(spec => [spec.field, spec]));
-        this.disposeScope = scope.subscribe(() => { this.publish(); });
+        this.disposeForm = scope.subscribe(() => { this.publish(); });
     }
     /**
-     * Release the scope subscription and every bound store listener. The card
+     * Release the form subscription and every bound store listener. The card
      * must call this on teardown; later calls are no-ops.
      */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.disposeScope();
+        this.disposeForm();
         this.listeners.clear();
     }
-    /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+    /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
     bind(project) {
         const store = createSnapshotStore(project());
         this.listeners.add(() => { store.set(project()); });
@@ -168,19 +168,19 @@ export class CardForm {
         };
     }
     /**
-     * Write every staged edit in one atomic scope mutation, then re-seed from
+     * Write every staged edit in one atomic form mutation, then re-seed from
      * what the Host accepted.
      *
      * The whole batch rides one mutate, so cross-field validate hooks
      * (baseURL+model) judge it as a unit: the Host either applies every write
-     * or refuses the batch. The 0.1.2 scope contract never rejects a refused
-     * mutation — the scope recovers with a fresh Host view and resolves — so
-     * resolution alone proves nothing: the outcome is judged by reading the
-     * settled snapshot back, one planned write at a time, and one missed write
-     * fails the whole save. A scope that still rejects on refusal (the dsh-web
-     * bridge scope) reports through the same failure path with its rejection
-     * message. A save that did not land keeps its drafts, so the user can
-     * correct them instead of retyping.
+     * or refuses the batch. The form contract answers a refusal or a skipped
+     * write with `false` (it recovers with a fresh Host view instead of
+     * throwing), so the outcome is judged twice: the answer itself, and then the
+     * settled snapshot read back one planned write at a time. One missed write
+     * fails the whole save. A transport that rejects instead (the dsh-web bridge
+     * controller on a dead connection) reports through the same failure path
+     * with its rejection message. A save that did not land keeps its drafts, so
+     * the user can correct them instead of retyping.
      * @returns settlement after the mutation and the read-back.
      */
     async save() {
@@ -198,32 +198,35 @@ export class CardForm {
         this.failed = false;
         this.failedReason = undefined;
         this.publish();
-        // One atomic namespace mutation: the 0.1.2 scope contract takes ordered
-        // path operations, so the whole staged batch is validated, persisted, and
+        // One atomic namespace mutation: the form contract takes ordered path
+        // operations, so the whole staged batch is validated, persisted, and
         // recovered together — either every write lands or none does.
         const ops = valid.map(item => item.op.op === 'set'
             ? { op: 'set', path: [item.field], value: item.op.value }
             : { op: 'unset', path: [item.field] });
         let failedReason;
+        let accepted = false;
         try {
-            await this.scope.mutate(ops);
+            accepted = await this.scope.mutate(ops);
         }
         catch (error) {
             failedReason = error instanceof Error ? error.message : String(error);
         }
-        // The 0.1.2 scope resolves even a refused mutation (it recovers with a
-        // fresh view instead of throwing), so resolution alone proves nothing:
-        // judge every planned write against the settled snapshot. The mutation is
-        // atomic, so one missed write fails the whole save and keeps the drafts.
-        const landed = failedReason === undefined && valid.every(item => item.judge());
+        // `false` is the contract's refusal/skip answer, and the form still
+        // resolves after a refusal (it recovers with a fresh view), so the answer
+        // alone is not enough: judge every planned write against the settled
+        // snapshot as well. The mutation is atomic, so one missed write fails the
+        // whole save and keeps the drafts.
+        const landed = accepted && failedReason === undefined && valid.every(item => item.judge());
         for (const [field, before] of pending) {
             if (landed && this.staged.get(field) === before)
                 this.staged.delete(field);
         }
         this.saving = false;
         this.failed = !landed;
-        // A read-back failure carries no server reason: the card surfaces its
-        // generic failure copy; a rejecting scope (the bridge) adds its message.
+        // A refused or unlanded batch carries no server reason: the card surfaces
+        // its generic failure copy; a rejecting transport (the bridge) adds its
+        // message.
         this.failedReason = failedReason;
         this.publish();
     }
@@ -261,7 +264,7 @@ export class CardForm {
      */
     landedSet(field, value) {
         // A redacted secret never appears in any wire view layer: the Host strips
-        // role('secret') fields and reports them through a sidecar the scope
+        // role('secret') fields and reports them through a sidecar the form
         // snapshot does not expose, so there is nothing to compare the draft
         // against. Settling is the only signal the form has; the rest of the
         // batch, when one exists, still carries the atomic verdict by read-back.

package/lib/types/console-output.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Console-output capture shared by the family's Host halves.
+ *
+ * A child process's stdout/stderr are raw bytes, and on Windows a console
+ * program writes the OEM code page (CP936/GBK on a zh-CN system), not UTF-8.
+ * Decoding each chunk on its own corrupts the text twice over: the
+ * encoding is guessed wrong, and a multi-byte character split across two reads
+ * decodes into two replacement characters. This capture accumulates raw bytes
+ * under a byte budget and decodes exactly once, at read time.
+ */
+/** Bounded byte accumulator for one child process's interleaved stdout/stderr. */
+export interface OutputCapture {
+    /** Append one raw chunk (the bytes are copied into the budget). */
+    push(chunk: Uint8Array): void;
+    /**
+     * Decode everything captured so far. Idempotent, so a caller may read the
+     * tail both after a failure branch and at settlement.
+     */
+    read(): string;
+}
+/**
+ * Decode one console byte buffer. Strict UTF-8 wins whenever it is valid;
+ * otherwise the bytes are not UTF-8 at all and the console wrote its own code
+ * page, so the candidate that loses the least text is taken.
+ * @param bytes - the captured bytes.
+ * @returns the decoded text.
+ */
+export declare function decodeConsoleBytes(bytes: Uint8Array): string;
+/**
+ * Create a capture bounded to a byte budget. Overflow drops from the FRONT
+ * (the tail is what carries a failure reason), and the cut never lands inside
+ * a character: leading UTF-8 continuation bytes are dropped with it, and a
+ * legacy code page's dangling lead byte — indistinguishable from a real byte
+ * without knowing the encoding until the whole buffer is decoded — is removed
+ * with the one replacement character it produced, so an over-long stream still
+ * reads cleanly at the seam.
+ * @param maxBytes - maximum retained bytes.
+ * @returns the capture.
+ */
+export declare function createOutputCapture(maxBytes: number): OutputCapture;
+//# sourceMappingURL=console-output.d.ts.map

package/lib/types/console-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-output.d.ts","sourceRoot":"","sources":["../../src/console-output.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IAC7B;;;OAGG;IACH,IAAI,IAAI,MAAM,CAAA;CACf;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA2B5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAiBnE"}