@jini-ai/ui 0.4.3 → 0.4.5

package/dist/features/panel-kit/hooks/use-standing-draft-autosave.hooks.js

@@ -0,0 +1,300 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useSerialWrites } from "./use-serial-writes.hooks.js";
+/** Idle debounce: fires this long after the LAST `scheduleAutosave` call with no further calls. */
+const IDLE_DEBOUNCE_MS = 3000;
+/** Hard ceiling while continuously typing: once this much time has passed since the first
+ *  unflushed edit, the next tick fires immediately instead of resetting the idle window again. */
+const MAX_WAIT_MS = 15000;
+export function useStandingDraftAutosave(deps, _options = {}) {
+    const { port, backup, entryId, enabled, serverUpdatedAt } = deps;
+    const [backupPrincipalId] = useState(() => port.getBackupPrincipalId?.({}, {}));
+    const latestDraftRef = useRef(null);
+    const backupGenerationRef = useRef(0);
+    const [recoverableDraft, setRecoverableDraft] = useState(null);
+    const [staleBasis, setStaleBasis] = useState(null);
+    // Mirrors `staleBasis` for the SYNCHRONOUS gate in `scheduleAutosave`: the refusal is discovered
+    // inside the request chain, and a React state read there would be a render behind — the window in
+    // which the very ticks this gate exists to stop would still be scheduled.
+    const staleBasisRef = useRef(null);
+    // Which entry's refused text is currently mirrored in browser storage, or `null`. Deliberately
+    // NOT the same lifetime as the gate above (see this file's header), and deliberately an entry id
+    // rather than a boolean: it is the proof that a mirror this hook may drop belongs to the entry
+    // being edited right now, so switching entries can never delete another entry's surviving copy.
+    const backupEntryIdRef = useRef(null);
+    // Every network op (each autosave PUT, and the eventual discard) is appended here, never fired
+    // standalone — this IS the ordering guarantee `clearStandingDraft`'s own doc describes. Caught
+    // internally (see `enqueue`) so one failed request can never permanently wedge the lane.
+    const writes = useSerialWrites();
+    const idleTimerRef = useRef(null);
+    const firstPendingAtRef = useRef(null);
+    // The newest draft handed to `scheduleAutosave` that has NOT yet been written — what a flush
+    // sends. A ref, not the timer's own closure, precisely so an exit event can reach it: the
+    // closure is unreachable from outside the `setTimeout` callback, which is why cancelling the
+    // timer used to be indistinguishable from losing the edit.
+    const pendingDraftRef = useRef(null);
+    // The lowest `baseVersion` a write may still carry for the current entry — see `supersedeBasis`.
+    // `null` until the caller supersedes a basis; reset on an entry change, because another entry's
+    // version numbers are unrelated.
+    const minBaseVersionRef = useRef(null);
+    const clearPendingTimer = useCallback(() => {
+        if (idleTimerRef.current !== null)
+            clearTimeout(idleTimerRef.current);
+        idleTimerRef.current = null;
+        firstPendingAtRef.current = null;
+        pendingDraftRef.current = null;
+    }, []);
+    /** The server refused this draft. Records the basis, and mirrors the text locally — the ONLY
+     *  place it can survive a tab close while the server keeps refusing it. @complexity O(1). */
+    const markStaleBasis = useCallback((id, draft) => {
+        const next = { baseVersion: draft.baseVersion, draft };
+        staleBasisRef.current = next;
+        setStaleBasis(next);
+        backup.write({ entryId: id, draft, savedAt: new Date().toISOString() }, { principalId: backupPrincipalId });
+        backupEntryIdRef.current = id;
+    }, [backupPrincipalId, backup]);
+    /** Lifts the gate so scheduling resumes. Does NOT touch the mirror — see this file's header for
+     *  why those two are separate. No-op when nothing is stale, so the common path never re-renders.
+     *  @complexity O(1). */
+    const liftStaleGate = useCallback(() => {
+        if (staleBasisRef.current === null)
+            return;
+        staleBasisRef.current = null;
+        setStaleBasis(null);
+    }, []);
+    /** Drops the browser-storage mirror for the entry being edited, if it has one. Called only where
+     *  the operator's text provably survives somewhere else — the server just accepted a write (so it
+     *  is parked server-side), or a real Save/discard superseded it. @complexity O(1). */
+    const dropLocalBackup = useCallback(() => {
+        const id = backupEntryIdRef.current;
+        if (id === null)
+            return;
+        backupEntryIdRef.current = null;
+        backup.clear({ entryId: id }, { principalId: backupPrincipalId });
+    }, [backupPrincipalId, backup]);
+    // Mount-time (and entry-change) recovery check — one read, never repeated while this entryId
+    // stays mounted. A stale in-flight response from a PREVIOUS entryId is dropped via `cancelled`.
+    useEffect(() => {
+        setRecoverableDraft(null);
+        // A different entry is a different basis. A gate recorded for the PREVIOUS entryId must never
+        // silence autosave for this one — their `version` numbers are very often both 1, so leaving it
+        // set would silently stop autosaving an entry nobody has a conflict on. In-memory only: the
+        // previous entry's local mirror is keyed under ITS id and stays recoverable there.
+        staleBasisRef.current = null;
+        setStaleBasis(null);
+        // Same reasoning for the mirror pointer, one step further: the previous entry's mirror stays in
+        // storage under ITS OWN key and stays recoverable there — only this hook's permission to drop a
+        // mirror is reset, so a later accepted write for THIS entry cannot delete that other copy.
+        backupEntryIdRef.current = null;
+        minBaseVersionRef.current = null;
+        latestDraftRef.current = null;
+        if (!enabled || !entryId)
+            return;
+        let cancelled = false;
+        port
+            .getAutosave({ id: entryId }, {})
+            .then((result) => {
+            if (cancelled)
+                return;
+            const localBackup = backup.read({ entryId }, { principalId: backupPrincipalId });
+            // Recorded whether or not it is the copy shown below: it exists, so a real Save or an
+            // explicit discard on this entry has to be able to drop it. Without this the mirror written
+            // before a reload would outlive every discard and re-offer itself on every later mount.
+            if (localBackup !== null)
+                backupEntryIdRef.current = entryId;
+            // Historically server first — a parked draft is shared across tabs. For expiry recovery,
+            // compare capture times instead: a 401 mirror may contain edits newer than that parked copy. The local
+            // mirror is the fallback for exactly the case that produced it: the other tab's real save
+            // cleared the server-side draft, so this tab reloads into "nothing to recover" while its
+            // own refused text is the thing the operator actually wants back.
+            const server = result.autosave;
+            // A 401 mirror can be newer than the last accepted server autosave. Keep the newest copy.
+            const newest = localBackup && (!server || localBackup.savedAt > server.savedAt) ? localBackup : server;
+            setRecoverableDraft(newest);
+        })
+            .catch(() => {
+            // A failed server recovery read must not hide the local copy rescued from an expired session.
+            if (cancelled)
+                return;
+            const localBackup = backup.read({ entryId }, { principalId: backupPrincipalId });
+            if (localBackup !== null)
+                backupEntryIdRef.current = entryId;
+            setRecoverableDraft(localBackup);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [enabled, entryId, port, backupPrincipalId, backup]);
+    const enqueue = useCallback((op) => writes.run({ task: op }).catch(() => {
+        // eslint-disable-next-line no-console -- best-effort background persistence; surfaced to
+        // the console rather than the operator, who has nothing actionable to do about one dropped
+        // autosave tick, and rather than thrown, which would wedge every later tick on this chain.
+        console.error("standing-draft autosave: request failed");
+    }), [writes]);
+    const preserveFailedSave = useCallback(({ error, draft }, _options = {}) => {
+        if (!entryId || !isUnauthorizedDraftWrite(error))
+            return;
+        backup.write({ entryId, draft, savedAt: new Date().toISOString() }, { principalId: backupPrincipalId });
+        backupEntryIdRef.current = entryId;
+    }, [entryId, backupPrincipalId, backup]);
+    /** The one place `putAutosave` is called. Its `{ applied }` answer is acted on here rather than
+     *  discarded — see this file's STALE BASIS note. @complexity Time/space: O(1) plus the request. */
+    const writeAutosave = useCallback((id, draft, keepalive) => {
+        const generation = backupGenerationRef.current;
+        return enqueue(async () => {
+            let result;
+            try {
+                result = await port.putAutosave({ id, draft }, { keepalive });
+            }
+            catch (error) {
+                // A 401 can unmount the editor before this settles; the captured identity still owns it.
+                // Use the newest scheduled text, since an older request may fail while typing continues.
+                if (generation === backupGenerationRef.current)
+                    preserveFailedSave({ error, draft: latestDraftRef.current ?? draft });
+                throw error;
+            }
+            if (generation !== backupGenerationRef.current)
+                return;
+            if (!result.applied) {
+                // Refused because the caller already moved past this basis — nothing to pause or mirror.
+                if (isSupersededBasis(draft.baseVersion, minBaseVersionRef.current))
+                    return;
+                markStaleBasis(id, draft);
+                return;
+            }
+            // Accepted — the text is parked server-side now, which is the ONLY point at which the
+            // mirror is redundant and may go.
+            liftStaleGate();
+            dropLocalBackup();
+        });
+    }, [dropLocalBackup, enqueue, liftStaleGate, markStaleBasis, port, preserveFailedSave]);
+    const scheduleAutosave = useCallback((draft) => {
+        if (!enabled || !entryId)
+            return;
+        latestDraftRef.current = draft;
+        if (isSupersededBasis(draft.baseVersion, minBaseVersionRef.current))
+            return;
+        // The gate. Same basis as the one the server already refused => this write would be refused
+        // too, so it is not scheduled at all; a DIFFERENT basis means the editor reloaded the row, so
+        // the gate lifts by itself and no caller has to remember to reset anything.
+        const stale = staleBasisRef.current;
+        if (stale !== null && stale.baseVersion === draft.baseVersion)
+            return;
+        // The mirror is deliberately left in place here: nothing has been written yet, so until the
+        // server accepts, that mirror is still the only copy of the refused text that outlives the tab.
+        liftStaleGate();
+        const now = Date.now();
+        if (firstPendingAtRef.current === null)
+            firstPendingAtRef.current = now;
+        const waitedSoFar = now - firstPendingAtRef.current;
+        // Clamped, not a plain "already past the ceiling?" check: without the clamp, a call arriving
+        // just before the ceiling would still schedule a FULL fresh `IDLE_DEBOUNCE_MS`, pushing the
+        // actual fire time past `MAX_WAIT_MS` under continuous typing (verified by the ceiling test —
+        // an unclamped version never fires within the window it claims to bound).
+        const delay = Math.max(0, Math.min(IDLE_DEBOUNCE_MS, MAX_WAIT_MS - waitedSoFar));
+        pendingDraftRef.current = draft;
+        if (idleTimerRef.current !== null)
+            clearTimeout(idleTimerRef.current);
+        idleTimerRef.current = setTimeout(() => {
+            idleTimerRef.current = null;
+            firstPendingAtRef.current = null;
+            pendingDraftRef.current = null;
+            // Not an exit: the page is still here, so an ordinary fetch (no 64 KiB ceiling) is right.
+            writeAutosave(entryId, draft, false);
+        }, delay);
+    }, [enabled, entryId, liftStaleGate, writeAutosave]);
+    /**
+     * Writes a pending (not yet fired) autosave immediately instead of waiting the debounce out —
+     * the half of the cadence that makes the owner's actual requirement true ("what if they reload
+     * the page on accident or exit out of the page? I don't want them to lose their work"). The
+     * debounce always leaves a window of up to {@link IDLE_DEBOUNCE_MS} in which the newest edit
+     * exists only in React state; without this, every exit inside that window discards it.
+     *
+     * Goes onto the same serial chain every other write uses, so it can never overtake an in-flight
+     * PUT or a discard already queued by {@link clearStandingDraft} — and because that function
+     * nulls `pendingDraftRef`, a flush after a real Save is a no-op rather than a resurrection.
+     *
+     * @complexity Time/space: O(1) — one ref read and at most one enqueued request.
+     */
+    const flushPendingAutosave = useCallback((keepalive) => {
+        const draft = pendingDraftRef.current;
+        if (draft === null || !entryId)
+            return;
+        clearPendingTimer();
+        writeAutosave(entryId, draft, keepalive);
+    }, [clearPendingTimer, entryId, writeAutosave]);
+    // Flush, do not cancel, when this editor goes away. An in-app navigation (the "Posts"/"Pages"
+    // back link, or any router move) unmounts the hook while a debounced tick is still pending, and
+    // the previous cancel-on-unmount is exactly how the last seconds of typing were lost — verified
+    // in a real browser on 2026-09-06: typed into the Pages editor, followed the in-app link one
+    // second later, and no PUT was ever issued. The SPA outlives the unmount, so the request started
+    // here completes normally. Re-running on an `entryId` change is correct too: the cleanup closes
+    // over the OUTGOING entry, so switching entries parks the one being left behind.
+    // `keepalive: false` — an unmount is an in-app navigation, not a page teardown. The SPA outlives
+    // it, so the request started here completes normally and must not pay keepalive's body ceiling.
+    useEffect(() => () => flushPendingAutosave(false), [flushPendingAutosave]);
+    // The exits React never sees. `pagehide` covers a tab close, a reload and a same-tab navigation;
+    // `visibilitychange` covers a tab switch or the OS backgrounding the browser, where `pagehide`
+    // may never fire; `blur` covers switching to another desktop app with the tab still visible.
+    // `beforeunload` is deliberately NOT one of them — `use-dirty-guard.hooks.ts` already registers
+    // it, and it is a PROMPT, not a persistence hook: answering "Leave" still discards whatever the
+    // debounce had not written. Each handler is a no-op when nothing is pending, so overlapping
+    // events (a close fires blur AND pagehide) cost one write, not three.
+    useEffect(() => {
+        if (!enabled || !entryId)
+            return;
+        // Wrapped rather than passed straight to `addEventListener`: a listener is called WITH the
+        // Event, which would arrive as `flushPendingAutosave`'s `keepalive` argument — a truthy object,
+        // so every flush would silently request keepalive whether or not it is an exit.
+        const onExit = () => flushPendingAutosave(true);
+        const onVisibilityChange = () => {
+            if (document.visibilityState === "hidden")
+                flushPendingAutosave(true);
+        };
+        window.addEventListener("pagehide", onExit);
+        window.addEventListener("blur", onExit);
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        return () => {
+            window.removeEventListener("pagehide", onExit);
+            window.removeEventListener("blur", onExit);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [enabled, entryId, flushPendingAutosave]);
+    const clearStandingDraft = useCallback(async () => {
+        // A late 401/refusal must not resurrect a draft a successful Save or Discard superseded.
+        backupGenerationRef.current++;
+        clearPendingTimer();
+        setRecoverableDraft(null);
+        // A real Save landed (or the operator discarded): whatever was refused is superseded, so the
+        // gate lifts and the mirror goes with it — otherwise the next mount would offer a ghost. This
+        // is also the ONLY thing that clears a mirror the operator has already been shown and chose to
+        // discard, since by then the gate that wrote it belongs to a previous mount.
+        liftStaleGate();
+        dropLocalBackup();
+        if (!entryId)
+            return;
+        await enqueue(async () => {
+            await port.discardAutosave({ id: entryId }, {});
+        });
+    }, [clearPendingTimer, dropLocalBackup, enqueue, entryId, liftStaleGate, port]);
+    const dismissRecoverable = useCallback(() => setRecoverableDraft(null), []);
+    const supersedeBasis = useCallback((baseVersion) => {
+        minBaseVersionRef.current = baseVersion;
+        const pending = pendingDraftRef.current;
+        if (pending !== null && isSupersededBasis(pending.baseVersion, baseVersion))
+            clearPendingTimer();
+        const stale = staleBasisRef.current;
+        if (stale !== null && isSupersededBasis(stale.baseVersion, baseVersion))
+            liftStaleGate();
+    }, [clearPendingTimer, liftStaleGate]);
+    const comparedDraft = useMemo(() => recoverableDraft ? { ...recoverableDraft, serverUpdatedAt } : null, [recoverableDraft, serverUpdatedAt]);
+    return { recoverableDraft: comparedDraft, staleBasis, dismissRecoverable, scheduleAutosave, clearStandingDraft, supersedeBasis, preserveFailedSave };
+}
+/** Whether a write built on `baseVersion` belongs to a basis the caller has left (see
+ *  `supersedeBasis`). @complexity O(1). */
+function isSupersededBasis(baseVersion, minBaseVersion) {
+    return minBaseVersion !== null && baseVersion < minBaseVersion;
+}
+function isUnauthorizedDraftWrite(error) {
+    return typeof error === "object" && error !== null && "status" in error && error.status === 401;
+}
+//# sourceMappingURL=use-standing-draft-autosave.hooks.js.map

package/dist/features/panel-kit/index.d.ts

@@ -13,7 +13,13 @@ export { resolveActiveTabId } from './helpers/resolve-active-tab-id.js';
 export { hasPermission } from './helpers/permissions.js';
 export { isAbortError, retryWhileUnreachable, UNREACHABLE_RETRY_DELAYS_MS } from './helpers/retry-unreachable.js';
 export { buildAgentListHandles } from '@jini-ai/agentic';
-export { createDictionaryTranslator, interpolate, splitOnPlaceholders, pickPlural } from '../i18n/index.js';
+export { createDictionaryTranslator, interpolate, splitOnPlaceholders, pickPlural, localeEntry } from '../i18n/index.js';
 export type { Translate, DictionaryTranslator, LocaleDictionary } from '../i18n/index.js';
 export type { DirtyGuardHostPort } from './hooks/use-dirty-guard.hooks.js';
+export { useSettingsSlice, mergeSaveStates, commitQueuedSave, canAcceptRefresh, SAVE_DEBOUNCE_MS } from './hooks/use-settings-slice.hooks.js';
+export type { SaveState, SettingsSlice, SettingsSliceOptions, SettingsSliceRefreshPort, SettingsRefreshScope } from './hooks/use-settings-slice.hooks.js';
+export { useStandingDraftAutosave } from './hooks/use-standing-draft-autosave.hooks.js';
+export type { StandingDraftAutosavePort, StandingDraftAutosaveInput, StandingDraftAutosaveSnapshot, StandingDraftAutosaveController, StandingDraftStaleBasis, StandingDraftAutosaveOptions } from './hooks/use-standing-draft-autosave.hooks.js';
+export { createStandingDraftLocalBackup, LOCAL_BACKUP_PRINCIPAL_ID } from './helpers/standing-draft-local-backup.js';
+export { standingDraftRecoveryMessage } from './helpers/standing-draft-recovery-message.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/features/panel-kit/index.js

@@ -9,5 +9,9 @@ export { resolveActiveTabId } from './helpers/resolve-active-tab-id.js';
 export { hasPermission } from './helpers/permissions.js';
 export { isAbortError, retryWhileUnreachable, UNREACHABLE_RETRY_DELAYS_MS } from './helpers/retry-unreachable.js';
 export { buildAgentListHandles } from '@jini-ai/agentic';
-export { createDictionaryTranslator, interpolate, splitOnPlaceholders, pickPlural } from '../i18n/index.js';
+export { createDictionaryTranslator, interpolate, splitOnPlaceholders, pickPlural, localeEntry } from '../i18n/index.js';
+export { useSettingsSlice, mergeSaveStates, commitQueuedSave, canAcceptRefresh, SAVE_DEBOUNCE_MS } from './hooks/use-settings-slice.hooks.js';
+export { useStandingDraftAutosave } from './hooks/use-standing-draft-autosave.hooks.js';
+export { createStandingDraftLocalBackup, LOCAL_BACKUP_PRINCIPAL_ID } from './helpers/standing-draft-local-backup.js';
+export { standingDraftRecoveryMessage } from './helpers/standing-draft-recovery-message.js';
 //# sourceMappingURL=index.js.map

package/dist/features/resource-dashboard/types.d.ts

@@ -1,41 +1,10 @@
 /**
- * Generic status-badged resource-dashboard primitives.
- *
- * Provenance: `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s "5 more
- * overlaps" section flagged "Resource-dashboard shell, twice, both directly
- * Run-vocabulary-relevant": `DesignsTab.tsx` (sub-tab sort + search +
- * select-mode/bulk-delete + per-item kebab menu + a grid/kanban view toggle
- * over a config-driven status-kanban board) and `TasksView.tsx` (hero header
- * with metric tiles + a flat row-list with inline per-item action buttons +
- * a lazy-loaded expandable per-row run-history sublist). Both were read in
- * full from `/tmp/od-source` (see `packages/ui/archived provenance ledger`'s
- * `features/resource-dashboard/` section for the full shared-vs-separate
- * verdict and quoted structural evidence).
- *
- * Verdict: genuinely TWO distinct composition shapes, not one. The only
- * piece that is actually identical between the two origins is "a status
- * value renders as a small badge" plus "group a list of status-bearing
- * items into ordered buckets" — DesignsTab uses that grouping to build a
- * whole-page kanban board; TasksView never groups by status at all (its
- * only status usage is a per-row/per-run `StatusPill`, one level deeper
- * than DesignsTab's top-level items). So this feature ships ONE shared
- * status vocabulary + `StatusPill` + `groupItemsByStatus` rule, consumed by
- * TWO separately composed components: `ResourceBoard` (the DesignsTab
- * shape) and `ResourceRowList` (the TasksView shape). Neither is generic
- * over the other; forcing them through one composed shell would mean
- * bolting kanban-grouping onto a shape that never uses it, or bolting
- * expandable nested history onto a shape that never had it.
- */
-/**
- * A host-supplied status value + its display label. Never a hardcoded
- * vocabulary: DesignsTab's own 6-value kanban vocabulary
- * (`not_started`/`running`/`awaiting_input`/`succeeded`/`failed`/`canceled`)
- * and TasksView's own 5-value run vocabulary
- * (`succeeded`/`failed`/`running`/`queued`/`canceled`) are two different,
- * non-identical instantiations of this same shape — see
- * `packages/ui/archived provenance ledger` for the note on reconciling either against
- * `@jini-ai/protocol`'s own `RunState` later (explicitly out of scope here).
+ * ResourceBoard and ResourceRowList share status badges/vocabulary and ordered grouping rules,
+ * but compose separate surfaces: a grid/kanban board versus rows with inline actions and nested
+ * lazy history. A combined shell would impose unused grouping or history on the other shape.
  */
+/** Host-supplied status and label. Board and row/run vocabularies can differ; reconciling them
+ * with protocol RunState is a separate decision, not implicit in this display primitive. */
 export interface ResourceStatusOption {
     value: string;
     label: string;
@@ -63,10 +32,7 @@ export interface ResourceMenuActionSpec {
  * option needs (DesignsTab's `recent` sorts by `updatedAt`, `yours` by
  * `createdAt` — two different fields on the same origin `Project` type) —
  * this primitive never assumes a single fixed timestamp field.
- * `body` is a host-supplied render slot for anything else (DesignsTab's
- * cover-thumbnail resolution across html/image/video/logo/brand kinds stays
- * entirely host-owned, never ported into this generic primitive — see
- * archived provenance ledger's "Dropped" list).
+ * `body` is a host-supplied render slot; content-kind-specific thumbnail resolution is host-owned.
  */
 export interface ResourceBoardItem<TBody = unknown> {
     id: string;
@@ -110,7 +76,8 @@ export interface ResourceRowItem {
     paused?: boolean;
     actions: ResourceRowAction[];
 }
-/** One entry in a row's expandable run-history sublist (TasksView's `RoutineRun`, lazy-fetched on first expand). `actions` generalizes the origin's per-run "crystallize"/"view progress" buttons — see archived provenance ledger for what was dropped (the crystallize automation-evolution workflow is OD-specific and not ported; "open" is the one generic action kept). */
+/** Entry in an expandable run-history list. Action kinds are host-owned; the primitive does
+ * not implement a product's automation-evolution workflow. */
 export interface ResourceRunHistoryItem {
     id: string;
     status: string;

package/dist/features/resource-dashboard/types.js

@@ -1,30 +1,7 @@
 /**
- * Generic status-badged resource-dashboard primitives.
- *
- * Provenance: `ADS-memory/reports/jini-port/god-components-extraction-plan.md`'s "5 more
- * overlaps" section flagged "Resource-dashboard shell, twice, both directly
- * Run-vocabulary-relevant": `DesignsTab.tsx` (sub-tab sort + search +
- * select-mode/bulk-delete + per-item kebab menu + a grid/kanban view toggle
- * over a config-driven status-kanban board) and `TasksView.tsx` (hero header
- * with metric tiles + a flat row-list with inline per-item action buttons +
- * a lazy-loaded expandable per-row run-history sublist). Both were read in
- * full from `/tmp/od-source` (see `packages/ui/archived provenance ledger`'s
- * `features/resource-dashboard/` section for the full shared-vs-separate
- * verdict and quoted structural evidence).
- *
- * Verdict: genuinely TWO distinct composition shapes, not one. The only
- * piece that is actually identical between the two origins is "a status
- * value renders as a small badge" plus "group a list of status-bearing
- * items into ordered buckets" — DesignsTab uses that grouping to build a
- * whole-page kanban board; TasksView never groups by status at all (its
- * only status usage is a per-row/per-run `StatusPill`, one level deeper
- * than DesignsTab's top-level items). So this feature ships ONE shared
- * status vocabulary + `StatusPill` + `groupItemsByStatus` rule, consumed by
- * TWO separately composed components: `ResourceBoard` (the DesignsTab
- * shape) and `ResourceRowList` (the TasksView shape). Neither is generic
- * over the other; forcing them through one composed shell would mean
- * bolting kanban-grouping onto a shape that never uses it, or bolting
- * expandable nested history onto a shape that never had it.
+ * ResourceBoard and ResourceRowList share status badges/vocabulary and ordered grouping rules,
+ * but compose separate surfaces: a grid/kanban board versus rows with inline actions and nested
+ * lazy history. A combined shell would impose unused grouping or history on the other shape.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/features/tab-strip/constants.d.ts

@@ -1,8 +1,7 @@
-/** Ported verbatim from `WorkspaceTabsBar.tsx`'s `TAB_DRAG_HAPTIC_MS`. */
+/** Drag feedback duration in milliseconds. */
 export declare const TAB_STRIP_DRAG_HAPTIC_MS = 8;
-/** Ported verbatim from `WorkspaceTabsBar.tsx`'s `TAB_DROP_HAPTIC_MS`. */
+/** Drop feedback duration in milliseconds. */
 export declare const TAB_STRIP_DROP_HAPTIC_MS = 12;
-/** DOM attribute used for strip-level drop-target hit-testing (the generic
- *  form of `WorkspaceTabsBar.tsx`'s `data-workspace-tab-id`). */
+/** DOM attribute used for strip-level drop-target hit-testing. */
 export declare const TAB_STRIP_ITEM_ID_ATTRIBUTE = "data-tab-strip-item-id";
 //# sourceMappingURL=constants.d.ts.map

package/dist/features/tab-strip/constants.js

@@ -1,8 +1,7 @@
-/** Ported verbatim from `WorkspaceTabsBar.tsx`'s `TAB_DRAG_HAPTIC_MS`. */
+/** Drag feedback duration in milliseconds. */
 export const TAB_STRIP_DRAG_HAPTIC_MS = 8;
-/** Ported verbatim from `WorkspaceTabsBar.tsx`'s `TAB_DROP_HAPTIC_MS`. */
+/** Drop feedback duration in milliseconds. */
 export const TAB_STRIP_DROP_HAPTIC_MS = 12;
-/** DOM attribute used for strip-level drop-target hit-testing (the generic
- *  form of `WorkspaceTabsBar.tsx`'s `data-workspace-tab-id`). */
+/** DOM attribute used for strip-level drop-target hit-testing. */
 export const TAB_STRIP_ITEM_ID_ATTRIBUTE = 'data-tab-strip-item-id';
 //# sourceMappingURL=constants.js.map

package/dist/features/tab-strip/dependencies.d.ts

@@ -1,9 +1,4 @@
 import type { TabStripHapticsPort } from './ports.js';
-/**
- * Real browser haptics implementation — ported from `WorkspaceTabsBar.tsx`'s
- * `pulseTabDragHaptic`: SSR-guarded, opportunistic (a `navigator.vibrate`
- * failure/absence is silently swallowed, matching the source's own
- * "unsupported environments should keep dragging normally" comment).
- */
+/** SSR-safe, opportunistic browser haptics. Unavailable or failed vibration must never stop dragging. */
 export declare function createBrowserTabStripHaptics(): TabStripHapticsPort;
 //# sourceMappingURL=dependencies.d.ts.map

package/dist/features/tab-strip/dependencies.js

@@ -1,9 +1,4 @@
-/**
- * Real browser haptics implementation — ported from `WorkspaceTabsBar.tsx`'s
- * `pulseTabDragHaptic`: SSR-guarded, opportunistic (a `navigator.vibrate`
- * failure/absence is silently swallowed, matching the source's own
- * "unsupported environments should keep dragging normally" comment).
- */
+/** SSR-safe, opportunistic browser haptics. Unavailable or failed vibration must never stop dragging. */
 export function createBrowserTabStripHaptics() {
     return {
         pulse(durationMs) {

package/dist/features/tab-strip/react/components/TabBar.d.ts

@@ -1,14 +1,45 @@
 import type { ReactNode } from "react";
+/**
+ * @file Controlled horizontal tabs: id/label pairs, active id and change callback, with no routing,
+ * persistence or panel lifecycle. SettingsDialogShell also owns a header/sidebar/dialog lifecycle;
+ * hosts needing only a tab row can use this standalone component.
+ * Optional agent handles tag only elements whose handles are supplied.
+ */
 export interface TabBarTab {
     readonly id: string;
     readonly label: string;
+    /** Inline icon before the label. Always aria-hidden because adjacent text already names the
+     * tab. Omit for the plain text layout; this slot does not require SettingsDialogShell. */
     readonly icon?: ReactNode | undefined;
+    /** Shown next to the label when present (e.g. a theme count per tier). Omit to show none. */
     readonly count?: number | undefined;
+    /** Pill after the label, using the admin Sidebar's shared "Soon" styling. A tagged tab stays
+     * clickable so its panel can explain status; use disabled when there is no destination. */
     readonly tag?: string | undefined;
+    /**
+     * Renders this tab greyed out and non-interactive: no `onChange` call, not part of the tab
+     * order (native `disabled`), `aria-disabled` set for assistive tech. For scaffolding a future
+     * tab (e.g. a "Marketplace (soon)" placeholder with no real destination yet) that should be
+     * visibly present without inviting a click into nothing.
+     */
     readonly disabled?: boolean | undefined;
+    /** Publishes this tab button as agent-addressable via `agentHandle()` (`@jini-ai/agentic`). Omit
+     *  to leave the tab untagged. */
     readonly handle?: string | undefined;
+    /** Plain-English description of what switching to this tab does, paired with {@link handle}.
+     *  Defaults to `label` (untranslated tab labels, e.g. Deployment's, still read fine as a
+     *  description; a caller with a translated `label` should pass its own). Ignored if `handle` is
+     *  omitted. */
     readonly handleLabel?: string | undefined;
+    /**
+     * A filled dot before the label exposes configuration state across panels shown one at a time,
+     * without making the tab row denser as providers are added. Meaning comes from presence rather
+     * than color alone. The dot is aria-hidden; dotLabel supplies its text equivalent as a suffix
+     * to the tab's accessible name.
+     */
     readonly dot?: boolean | undefined;
+    /** Visually-hidden text appended to this tab's accessible name when {@link dot} is set — e.g.
+     *  "Connected". Required whenever `dot` is true; ignored otherwise. */
     readonly dotLabel?: string | undefined;
 }
 export interface TabBarProps {
@@ -16,8 +47,9 @@ export interface TabBarProps {
     activeId: string;
     onChange: (id: string) => void;
     ariaLabel: string;
+    /** Publishes the tablist container itself as agent-addressable. Omit to leave it untagged. */
     containerHandle?: string | undefined;
 }
 /** Controlled button-based selection strip, including roving focus and optional agent handles. */
-export declare function TabBar({ tabs, activeId, onChange, ariaLabel, containerHandle }: TabBarProps): import("react").JSX.Element;
+export declare function TabBar({ tabs, activeId, onChange, ariaLabel, containerHandle }: TabBarProps, _optional?: Record<string, never>): import("react").JSX.Element;
 //# sourceMappingURL=TabBar.d.ts.map

package/dist/features/tab-strip/react/components/TabBar.hooks.d.ts

@@ -1,25 +1,77 @@
 import type { KeyboardEvent as ReactKeyboardEvent } from "react";
 import type { TabBarTab } from "./TabBar.js";
+/**
+ * @file TabBar's derived props and WAI-ARIA automatic-activation keyboard behavior.
+ * Data and event logic live here; TabBar.tsx keeps the JSX render helpers. Arrow keys activate
+ * immediately and move focus, while disabled tabs are skipped and non-tab controls keep their keys.
+ */
+/** The `TabBarButton` component's own `agentHandle()` spread, as a plain function rather than an
+ *  inline ternary in its JSX — one more small piece pulled out of `TabBar.tsx` for the same
+ *  complexity-gate reason that component's own doc comment gives.
+ * @example tabHandleProps({ tab: { id: "a", label: "A", handle: "tab-a" } });
+ */
 export declare function tabHandleProps({ tab }: {
     tab: TabBarTab;
-}): {};
-/** Resolve arrow/Home/End navigation in enabled-tab order; null means no navigation. */
+}, _optional?: Record<string, never>): {};
+/**
+ * Resolve arrow/Home/End navigation in enabled-tab order; null means no navigation.
+ *
+ * Resolves which tab a keydown on the tablist should move to, for the WAI-ARIA "automatic
+ * activation" tabs pattern (arrow keys change the selection immediately, not just focus).
+ *
+ * @param input.tabs - The tab row in DOM order.
+ * @param input.activeId - The currently active tab's id.
+ * @param input.key - `KeyboardEvent.key` from the tablist's own `onKeyDown`.
+ * @returns The target tab's index into `tabs`, or `null` when `key` isn't a nav key or every tab
+ *   is disabled. Disabled tabs are never a target. Home/End always resolve to the first/last
+ *   enabled tab. When `activeId` matches no enabled tab (unset, unknown id, or a disabled tab),
+ *   ArrowRight/Home resolve to the first enabled tab and ArrowLeft/End resolve to the last —
+ *   the same "nothing to move from" case Home/End already answer explicitly.
+ * @complexity O(n²) time, O(n) space (the enabled-index reducer copies its accumulator) in `tabs.length`.
+ * @example resolveTabBarKeyTarget({ tabs, activeId: "a", key: "ArrowRight" });
+ */
 export declare function resolveTabBarKeyTarget({ tabs, activeId, key }: {
     tabs: readonly TabBarTab[];
     activeId: string;
     key: string;
-}): number | null;
+}, _optional?: Record<string, never>): number | null;
+/**
+ * Resolves one tab's roving-tabindex value — exactly one tab in a `TabBar` is ever in the native
+ * Tab order at a time (WAI-ARIA APG roving tabindex), so arrowing between tabs never lets a plain
+ * Tab keypress land on more than one of them.
+ *
+ * @param input.tabs - The tab row in DOM order.
+ * @param input.activeId - The currently active tab's id.
+ * @param input.tab - The tab being rendered.
+ * @returns `0` for the enabled active tab, or for the first enabled tab when `activeId` matches
+ *   no enabled tab; `-1` otherwise, including every disabled tab.
+ * @complexity O(n) in `tabs.length`.
+ * @example resolveTabBarTabIndex({ tabs, activeId: "a", tab: tabs[0]! });
+ */
 export declare function resolveTabBarTabIndex({ tabs, activeId, tab }: {
     tabs: readonly TabBarTab[];
     activeId: string;
     tab: TabBarTab;
-}): 0 | -1;
+}, _optional?: Record<string, never>): 0 | -1;
 export interface TabBarKeyboardHandlers {
     onKeyDown: (e: ReactKeyboardEvent<HTMLDivElement>) => void;
 }
+/**
+ * Wires {@link resolveTabBarKeyTarget} into a tablist's `onKeyDown`: on a nav key, changes the
+ * active tab and moves DOM focus to the new tab button, so focus and selection never drift apart.
+ * Keydowns that did not originate inside a `[role="tab"]` are ignored, so a non-tab control hosted
+ * in the same tablist keeps its own arrow/Home/End keys.
+ *
+ * @param input.tabs - The tab row in DOM order.
+ * @param input.activeId - The currently active tab's id.
+ * @param input.onChange - `TabBarProps.onChange`, called with the target tab's id.
+ * @returns `onKeyDown`, for the tablist container's own React event prop.
+ * @complexity O(n²) time, O(n) space (the enabled-index reducer copies its accumulator) in `tabs.length` per keydown (bounded by the on-screen tab count).
+ * @example useTabBarKeyboard({ tabs, activeId, onChange });
+ */
 export declare function useTabBarKeyboard({ tabs, activeId, onChange }: {
     tabs: readonly TabBarTab[];
     activeId: string;
     onChange: (id: string) => void;
-}): TabBarKeyboardHandlers;
+}, _optional?: Record<string, never>): TabBarKeyboardHandlers;
 //# sourceMappingURL=TabBar.hooks.d.ts.map