@jini-ai/ui 0.4.3 → 0.4.5

package/dist/features/panel-kit/helpers/resolve-active-tab-id.js

@@ -1,3 +1,5 @@
+// ADR-063: URL-owned screens retain their own tab lists and defaults. Pages mirrors local state
+// to the URL to avoid navigation over eagerly fetched data; tab-manifest enumerability is a separate decision.
 /** Keep an allowed selection or choose the allowed default/first id; an empty list keeps defaultId. */
 /**
  * URL query values can come from stale bookmarks or typos; validating against allowed ids prevents

package/dist/features/panel-kit/helpers/standing-draft-local-backup.d.ts

@@ -0,0 +1,51 @@
+import type { StandingDraftAutosaveInput, StandingDraftAutosaveSnapshot } from "../hooks/use-standing-draft-autosave.hooks.js";
+/**
+ * @file Last-resort per-tab mirror for a standing draft the SERVER REFUSED (2026-09-06 stale-basis
+ * fix). Deliberately NOT a general autosave backend — browser storage was explicitly rejected for
+ * that (see `use-standing-draft-autosave.hooks.ts`'s header); this holds exactly one thing: the
+ * text the server answered `applied: false` or HTTP 401 to, which it will keep refusing until the
+ * editor reloads the row or the operator signs in again. Server-side parking is impossible for that text, so without this the
+ * operator's only copy lives in a tab they may close at any moment.
+ *
+ * Written only on a refusal, read only as the mount-time fallback when the server has nothing
+ * parked, and dropped the moment the server accepts a write again, the operator discards, or a real
+ * Save lands. Every access is wrapped: `localStorage` throws outright in some privacy modes and on
+ * quota exhaustion, and a failed backup must never break the editor it is protecting.
+ *
+ * Type-only import from the hook module — no runtime edge, and the hook keeps owning the shapes
+ * both editors already import from it.
+ */
+/** Namespaced so one entry's backup can never collide with another's, or with unrelated app keys. */
+/** Legacy marker for injected ports with no identity metadata — a recovered backup is identifiably
+ *  local rather than pretending the server parked it. Production now uses the actual principal id
+ *  captured by the session adapter. The legacy marker still keeps old fakes honest because
+ *  {@link StandingDraftAutosaveSnapshot} requires the field; inventing a server principal would be
+ *  the same class of defect this whole fix is about. */
+export declare const LOCAL_BACKUP_PRINCIPAL_ID = "local-tab-backup";
+/** Bind a profile-local refusal mirror without choosing the host's storage namespace.
+ * Storage is obtained lazily inside guarded operations, so privacy-mode getters cannot break mount.
+ * @complexity O(draft size) for reads/writes; O(1) for clears.
+ */
+export declare function createStandingDraftLocalBackup({ keyPrefix: KEY_PREFIX, getStorage }: {
+    keyPrefix: string;
+    getStorage: (required: Record<string, never>, optional?: Record<string, never>) => Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}, _options?: Record<string, never>): {
+    write: ({ entryId, draft, savedAt }: {
+        entryId: string;
+        draft: StandingDraftAutosaveInput;
+        savedAt: string;
+    }, options?: {
+        principalId?: string | null | undefined;
+    }) => void;
+    read: ({ entryId }: {
+        entryId: string;
+    }, options?: {
+        principalId?: string | null | undefined;
+    }) => StandingDraftAutosaveSnapshot | null;
+    clear: ({ entryId }: {
+        entryId: string;
+    }, options?: {
+        principalId?: string | null | undefined;
+    }) => void;
+};
+//# sourceMappingURL=standing-draft-local-backup.d.ts.map

package/dist/features/panel-kit/helpers/standing-draft-local-backup.js

@@ -0,0 +1,77 @@
+/**
+ * @file Last-resort per-tab mirror for a standing draft the SERVER REFUSED (2026-09-06 stale-basis
+ * fix). Deliberately NOT a general autosave backend — browser storage was explicitly rejected for
+ * that (see `use-standing-draft-autosave.hooks.ts`'s header); this holds exactly one thing: the
+ * text the server answered `applied: false` or HTTP 401 to, which it will keep refusing until the
+ * editor reloads the row or the operator signs in again. Server-side parking is impossible for that text, so without this the
+ * operator's only copy lives in a tab they may close at any moment.
+ *
+ * Written only on a refusal, read only as the mount-time fallback when the server has nothing
+ * parked, and dropped the moment the server accepts a write again, the operator discards, or a real
+ * Save lands. Every access is wrapped: `localStorage` throws outright in some privacy modes and on
+ * quota exhaustion, and a failed backup must never break the editor it is protecting.
+ *
+ * Type-only import from the hook module — no runtime edge, and the hook keeps owning the shapes
+ * both editors already import from it.
+ */
+/** Namespaced so one entry's backup can never collide with another's, or with unrelated app keys. */
+/** Legacy marker for injected ports with no identity metadata — a recovered backup is identifiably
+ *  local rather than pretending the server parked it. Production now uses the actual principal id
+ *  captured by the session adapter. The legacy marker still keeps old fakes honest because
+ *  {@link StandingDraftAutosaveSnapshot} requires the field; inventing a server principal would be
+ *  the same class of defect this whole fix is about. */
+export const LOCAL_BACKUP_PRINCIPAL_ID = "local-tab-backup";
+/** Bind a profile-local refusal mirror without choosing the host's storage namespace.
+ * Storage is obtained lazily inside guarded operations, so privacy-mode getters cannot break mount.
+ * @complexity O(draft size) for reads/writes; O(1) for clears.
+ */
+export function createStandingDraftLocalBackup({ keyPrefix: KEY_PREFIX, getStorage }, _options = {}) {
+    function keyFor(entryId, principalId) {
+        return principalId === undefined ? `${KEY_PREFIX}${entryId}` : `${KEY_PREFIX}${encodeURIComponent(principalId ?? "")}.${encodeURIComponent(entryId)}`;
+    }
+    /** Mirrors a refused draft for this browser profile. Silent no-op on any storage failure.
+     *  @complexity Time/space: O(size of the draft) for the one `JSON.stringify`. */
+    function writeStandingDraftLocalBackup({ entryId, draft, savedAt }, options = {}) {
+        if (options.principalId === null)
+            return;
+        const snapshot = { ...draft, savedAt, savedByPrincipalId: options.principalId ?? LOCAL_BACKUP_PRINCIPAL_ID };
+        try {
+            const storage = getStorage({}, {});
+            storage.setItem(keyFor(entryId, options.principalId), JSON.stringify(snapshot));
+        }
+        catch {
+            // eslint-disable-next-line no-console -- best-effort; the operator's text is still in the tab.
+            console.warn("standing-draft local backup: could not write");
+        }
+    }
+    /** The mirrored draft, or `null` when there is none (or storage is unreadable/corrupt).
+     *  @complexity Time/space: O(size of the stored draft). */
+    function readStandingDraftLocalBackup({ entryId }, options = {}) {
+        if (options.principalId === null)
+            return null;
+        try {
+            const storage = getStorage({}, {});
+            const raw = storage.getItem(keyFor(entryId, options.principalId));
+            return raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Drops the mirror. Called on an accepted write, an explicit discard, and a real Save.
+     *  @complexity Time/space: O(1). */
+    function clearStandingDraftLocalBackup({ entryId }, options = {}) {
+        if (options.principalId === null)
+            return;
+        try {
+            const storage = getStorage({}, {});
+            storage.removeItem(keyFor(entryId, options.principalId));
+        }
+        catch {
+            // Nothing to do and nothing to tell the operator — a backup that cannot be removed is
+            // superseded by the next write anyway, and is never auto-applied.
+        }
+    }
+    return { write: writeStandingDraftLocalBackup, read: readStandingDraftLocalBackup, clear: clearStandingDraftLocalBackup };
+}
+//# sourceMappingURL=standing-draft-local-backup.js.map

package/dist/features/panel-kit/helpers/standing-draft-recovery-message.d.ts

@@ -0,0 +1,8 @@
+import type { StandingDraftAutosaveSnapshot } from "../hooks/use-standing-draft-autosave.hooks.js";
+/** Compare timestamps explicitly; restoration only changes the working copy, never the server. */
+export declare function standingDraftRecoveryMessage({ draft, t, serverUpdatedAt }: {
+    draft: StandingDraftAutosaveSnapshot;
+    t: (key: string) => string;
+    serverUpdatedAt?: string;
+}, _options?: {}): string;
+//# sourceMappingURL=standing-draft-recovery-message.d.ts.map

package/dist/features/panel-kit/helpers/standing-draft-recovery-message.js

@@ -0,0 +1,10 @@
+/** Compare timestamps explicitly; restoration only changes the working copy, never the server. */
+export function standingDraftRecoveryMessage({ draft, t, serverUpdatedAt }, _options = {}) {
+    const captured = Date.parse(draft.savedAt);
+    const server = Date.parse(serverUpdatedAt ?? draft.serverUpdatedAt ?? "");
+    const comparison = server > captured ? "Server content is newer."
+        : server < captured ? "Local changes are newer."
+            : server === captured ? "Both copies have the same timestamp." : "";
+    return `${t("Restore unsaved changes from")} ${draft.savedAt}${comparison ? ` · ${t(comparison)}` : ""}`;
+}
+//# sourceMappingURL=standing-draft-recovery-message.js.map

package/dist/features/panel-kit/hooks/use-async-action.hooks.d.ts

@@ -1,5 +1,6 @@
 import { type Dispatch, type SetStateAction } from "react";
 export interface AsyncActionState {
+    /** True for the most recent run; error resets before each attempt and stays null on success. */
     saving: boolean;
     error: string | null;
     setError: Dispatch<SetStateAction<string | null>>;

package/dist/features/panel-kit/hooks/use-dirty-guard.hooks.d.ts

@@ -6,6 +6,7 @@ export interface DirtyGuard {
         unsavedBeyondTracked?: boolean;
     }) => boolean;
 }
+/** @complexity O(n) per render in the serialized size of current/original; intended for small forms. */
 /** Compare small JSON-serializable form states (including key order). Null original is clean.
  * Warn on unload and offer a translated native confirmation for caller-owned navigation. */
 export declare function useDirtyGuard<T>({ current, original }: {

package/dist/features/panel-kit/hooks/use-dirty-guard.hooks.js

@@ -4,6 +4,7 @@ import { useEffect } from "react";
 function shallowJsonEqual(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
+/** @complexity O(n) per render in the serialized size of current/original; intended for small forms. */
 /** Compare small JSON-serializable form states (including key order). Null original is clean.
  * Warn on unload and offer a translated native confirmation for caller-owned navigation. */
 export function useDirtyGuard({ current, original }, { translate = (key) => key, host = window } = {}) {

package/dist/features/panel-kit/hooks/use-serial-writes.hooks.d.ts

@@ -12,6 +12,14 @@
  * Re-entrant run calls queue normally, but awaiting an inner call from a task on the same
  * lane deadlocks: the inner task is waiting for the outer task to release that lane.
  */
+/**
+ * @example
+ * const generation = settlement.next();
+ * await writes.run({ task: async () => {
+ *   const result = await port.write();
+ *   if (settlement.isCurrent({ generation })) setResult(result);
+ * } });
+ */
 export interface SerialWrites {
     /** Each caller observes its own task result or rejection, never the internal lane tail. */
     run<T>({ task }: {

package/dist/features/panel-kit/hooks/use-serial-writes.hooks.js

@@ -38,4 +38,7 @@ export function useSerialWrites() {
         ref.current = createSerialWrites();
     return ref.current;
 }
+// Credentials, activation and autosave share this queue so writes cannot race or be dropped;
+// some callers enqueue their last persistence write from unmount cleanup to prevent data loss.
+// Controllers use this handle in useCallback/useMemo dependencies; keep the adapter stable too.
 //# sourceMappingURL=use-serial-writes.hooks.js.map

package/dist/features/panel-kit/hooks/use-settings-slice.hooks.d.ts

@@ -0,0 +1,211 @@
+export type SettingsRefreshScope = readonly string[] | null;
+/**
+ * @file One settings-dialog tab's load/edit/debounced-save lifecycle,
+ * generic over the tab's own config type.
+ *
+ * This was `SettingsUi.tsx`'s inline machinery when exactly one tab (Execution
+ * mode) was mounted. It is extracted rather than copied because the logic is
+ * subtle out of proportion to its size — successive audits have found FOUR
+ * distinct data-loss bugs in it (see `saveTicket`, `hasUnsavedEdits`, `runSave`,
+ * and `commits` below), and every one of those hazards is identical for every
+ * tab. Duplicating it per tab would mean re-introducing all four bugs three
+ * more times, and fixing them in three more places.
+ *
+ * The last two share one root cause worth stating plainly, because it is the
+ * shape every future bug here will take: **a value read at schedule time is a
+ * claim about the store that may already be false by the time the code using it
+ * runs.** `runSave` fixes it for writes by reading the diff base at run time;
+ * `commits` fixes it for reads by discarding a reload whose response predates a
+ * write that landed while it was in flight. Anything added here that captures
+ * `persisted` or `latest` across an `await` needs the same treatment.
+ *
+ * Each mounted tab owns one instance. They are independent by construction:
+ * separate debounce timers, separate save chains, separate diff bases. The
+ * only shared surface is the merged status the page chrome renders, which
+ * `SettingsUi.tsx` derives.
+ */
+export type SaveState = {
+    status: "idle";
+} | {
+    status: "saving";
+} | {
+    status: "saved";
+} | {
+    status: "error";
+    message: string;
+};
+/** Debounce for text fields: tabs are controlled and fire on every keystroke,
+ *  and each ledger write is an append-only revision. Without this, typing into
+ *  a textarea would write one revision per character. */
+export declare const SAVE_DEBOUNCE_MS = 600;
+/** Namespace-only notifications preserve the authorized re-read boundary; never carry values. */
+export interface SettingsSliceRefreshPort {
+    publish(required: {
+        namespaces: readonly string[];
+    }, optional?: Record<string, never>): void;
+    subscribe(required: {
+        listener: (scope: SettingsRefreshScope) => void;
+    }, optional?: Record<string, never>): () => void;
+}
+export interface SettingsSliceOptions<T> {
+    /** Reads the persisted value. A rejection surfaces as `loadError` and the
+     *  slice falls back to `defaultValue` — an unreadable setting shows defaults
+     *  with a visible warning rather than blocking the whole dialog. */
+    load: (required: Record<string, never>, optional?: Record<string, never>) => Promise<T>;
+    /** Writes whatever changed between `next` and `previous`, returning the keys
+     *  actually written (an empty array means "nothing to do", which the status
+     *  indicator renders as idle rather than a misleading "Saved"). */
+    save: (required: {
+        next: T;
+        previous: T;
+    }, optional?: Record<string, never>) => Promise<readonly string[]>;
+    defaultValue: T;
+    /**
+     * Ledger namespaces this slice reads, so a refresh naming other namespaces
+     * is ignored instead of costing a pointless reload.
+     *
+     * Omit to reload on EVERY refresh. That is the safe default in both
+     * directions: a slice that forgets to declare its namespaces stays correct
+     * (it just refetches more than it needs), whereas defaulting to "ignore
+     * everything" would make a forgotten declaration silently stop updating —
+     * the exact bug this feature exists to remove.
+     */
+    namespaces?: readonly string[];
+    /** Use one port for publication and subscription, so successful writes refresh their own surface.
+     * The host supplies a namespace-only bus; ports own their subscription cleanup. */
+    refreshPort: SettingsSliceRefreshPort;
+    /**
+     * Reconciles a freshly loaded value against the operator's current in-memory value before
+     * {@link SettingsSlice.refresh} lets it replace `value`/`persisted`/`latest`. Defaults to "the
+     * loaded value wins outright" — correct for every field this slice actually round-trips through
+     * `save`/`load`.
+     *
+     * Provide this when `T` carries a field `save`/`load` deliberately never touch (see
+     * `execution-settings.ts`'s `reconcileExecutionConfigRefresh` for `byok.apiKey`, which `save`
+     * never writes and `load` always returns empty). Without it, an external refresh — a same-tab
+     * echo of this slice's OWN write arriving over the settings-changed SSE feed, another tab,
+     * another operator — carries that field back at its "nothing here" default and silently
+     * overwrites an operator's typed-but-unsaved edit to it. `runSave` cannot leak this on its own:
+     * it never calls `setValue`. This path can, because replacing `value` with server truth is its
+     * entire job.
+     *
+     * @param current - `latest.current` at the moment the reload settled — the newest value the
+     *   operator has produced, saved or not.
+     * @param loaded - What `load()` just returned — true server state for every field it manages.
+     */
+    reconcileRefresh?: (required: {
+        current: T;
+        loaded: T;
+    }, optional?: Record<string, never>) => T;
+}
+/**
+ * Runs one save-chain link: calls `runSave`, then paints the ticket-owning outcome onto
+ * `saveState` — unless a newer save has since taken the ticket (`currentTicket()` no longer matches
+ * `ticket`), or the operator has queued another edit behind this one (`hasUnsavedEdits()`). Pulled
+ * out of `onChange`'s debounce-timer closure (2026-08-06, complexity pass) — it was the deepest
+ * nesting in this file, three closures in (`onChange` > the `setTimeout` callback > the
+ * `saveChain.current.then(async () => …)` link) — so the ticket/staleness handling is directly
+ * assertable against a fake `runSave`, without a real timer or save chain.
+ *
+ * The ref reads are passed as thunks rather than plain booleans specifically so this keeps the
+ * original "read at run time, not schedule time" contract this whole file's header calls out:
+ * `deps.currentTicket()`/`deps.hasUnsavedEdits()` are called from inside this function, at the same
+ * points the inline version read `saveTicket.current`/`hasUnsavedEdits.current` directly, so a
+ * ticket or edit that changes while `runSave` is in flight is still seen correctly.
+ *
+ * @param ticket - This link's own ticket, taken by the caller when the debounce timer fired.
+ */
+export declare function commitQueuedSave({ ticket, deps }: {
+    ticket: number;
+    deps: {
+        runSave: () => Promise<readonly string[]>;
+        currentTicket: () => number;
+        hasUnsavedEdits: () => boolean;
+        setSaveState: (state: SaveState) => void;
+    };
+}, _options?: Record<string, never>): Promise<void>;
+/**
+ * Whether a background `refresh()` reload may still land, given what is true about the slice's
+ * uncommitted-work state at the moment of the check.
+ *
+ * Pulled out of `refresh` (2026-08-06, complexity pass, third pass): the same four-flag shape is
+ * checked TWICE inside `refresh` — once before the `load()` await (where `mounted`/`commitsUnchanged`
+ * are trivially true, since nothing could have unmounted or committed a save before the function has
+ * even started awaiting), once after (where all four are live) — and collapsing the check into one
+ * named function removes the duplicated branch count rather than moving it. This does not change
+ * WHEN any ref is read: every call site below still reads `timer.current`/`hasUnsavedEdits.current`/
+ * `mounted.current`/`commits.current` at exactly the point in `refresh`'s own body the inline version
+ * did, in the same tick — this function only names the boolean combination those reads produce. See
+ * `refresh`'s own doc for why a re-check after the await is necessary at all.
+ */
+export declare function canAcceptRefresh(state: {
+    timerPending: boolean;
+    hasUnsavedEdits: boolean;
+    mounted: boolean;
+    commitsUnchanged: boolean;
+}, _options?: Record<string, never>): boolean;
+export interface SettingsSlice<T> {
+    /** `null` until the initial load settles — the caller renders a loading state. */
+    value: T | null;
+    loadError: string | null;
+    saveState: SaveState;
+    onChange: (next: T) => void;
+    /**
+     * Re-reads the persisted value, discarding nothing.
+     *
+     * Wired to {@link subscribeToSettingsRefresh} automatically; exposed mainly so
+     * a caller can force one. Declines while the operator has uncommitted work —
+     * see the implementation for why that is a refusal rather than a merge.
+     */
+    refresh: () => Promise<void>;
+}
+/**
+ * @complexity O(1) per edit — one debounce timer reset plus one link appended
+ * to the save chain.
+ *
+ * @complexityExemption (2026-08-06, complexity pass, third pass; bar raised to ≤9/≤9 same day,
+ * exemption reconfirmed against the new bar) **Score: this hook's own lexical scope is 1
+ * cyclomatic / ~0 cognitive under ESLint — every closure inside it is independently ≤9/≤9 too
+ * (`onChange`'s debounce callback is 2/1, the unmount-flush cleanup is 3/2, `refresh` is 5/4 as of
+ * this pass — see below). What is exempted here is a DIFFERENT, unmeasurable-by-me number: the
+ * dispatch brief's owner-tool score of 17/23, which rolls every nested closure's branches into the
+ * hook's total. Bar: ≤9/≤9 on whichever view is scored — ESLint's view already clears it; the
+ * owner-tool aggregate does not, and I have no local tool that reproduces that aggregate to
+ * re-measure against the new bar.**
+ *
+ * Same shape as `use-assistant-chats.hooks.ts`'s `useAssistantChats` exemption — see that one for
+ * the full reasoning. `commitQueuedSave` (first pass) and `canAcceptRefresh` (this pass, pulled out
+ * of `refresh`'s two duplicated guard checks — see its own doc) are the two pieces of this hook's
+ * logic that genuinely fit a top-level pure-function shape (0–4 plain params, no ref reads);
+ * `refresh` itself dropped from 9/5 to 5/4 as a result, its own per-function score real progress,
+ * not exempted. What remains (`runSave`/`onChange`/the unmount cleanup/the rest of `refresh`) each
+ * reads or writes 3–6 of this hook's own refs (`io`, `persisted`, `latest`, `timer`,
+ * `saveTicket`, `hasUnsavedEdits`, `commits`, `mounted`) plus the shared `writes` lane, and several of
+ * them call each other
+ * (`onChange` schedules a link that calls `runSave`; the unmount cleanup calls `runSave` directly),
+ * so none of them can become a top-level function without threading that whole ref set through as a
+ * parameter object. This file's own header states the reason that is dangerous here specifically:
+ * "a value read at schedule time is a claim about the store that may already be false by the time
+ * the code using it runs," and every ref above exists because an earlier version of exactly this
+ * logic got that ordering wrong (four distinct data-loss bugs, per the header). A previous pass
+ * already tried this kind of extraction on this file and the total was unchanged, 25 → 25 — the
+ * honest reading of that result is that the remaining closures do not have a top-level-shaped cut
+ * available at the risk level a time-boxed pass allows, not that the attempt was done wrong.
+ * Declined for the remainder; flagged to the coordinator. See this session's report for the full
+ * reasoning.
+ */
+export declare function useSettingsSlice<T>(options: SettingsSliceOptions<T>, _optional?: Record<string, never>): SettingsSlice<T>;
+/**
+ * Collapses several slices' save states into the single one the page chrome
+ * renders.
+ *
+ * Precedence is error > saving > saved > idle, and it is deliberate: an error
+ * is the only state the operator must act on, so it must not be hidden by
+ * another tab's cheerful "Saved". "Saving" outranks "saved" for the same
+ * reason in miniature — while anything is still in flight, claiming everything
+ * is saved is false.
+ */
+export declare function mergeSaveStates({ states }: {
+    states: readonly SaveState[];
+}, _options?: Record<string, never>): SaveState;
+//# sourceMappingURL=use-settings-slice.hooks.d.ts.map