@jini-ai/ui 0.5.5 → 0.5.6

package/dist/features/notifications/react/components/NotificationsTab.js

@@ -27,27 +27,22 @@ import { testStatusLabel } from '../../rules.js';
  */
 export function NotificationsTab({ preferences, onChange, testNotificationTitle, testNotificationBody, labels, agentHandle, }) {
     const t = useT();
-    const successSoundHandles = agentHandle
-        ? buildAgentListHandles({ prefix: agentSubHandle({ base: agentHandle, action: 'success-sound' }), ids: SUCCESS_SOUNDS.map((s) => s.id) })
-        : undefined;
-    const failureSoundHandles = agentHandle
-        ? buildAgentListHandles({ prefix: agentSubHandle({ base: agentHandle, action: 'failure-sound' }), ids: FAILURE_SOUNDS.map((s) => s.id) })
-        : undefined;
     const [permission, setPermission] = useState(() => notificationPermission());
     const [testStatus, setTestStatus] = useState(null);
-    const completionSoundTitle = labels?.completionSoundTitle ?? t('Completion sound');
-    const completionSoundHint = labels?.completionSoundHint ?? t('Play a sound when a task finishes.');
-    const successSoundLabel = labels?.successSoundLabel ?? t('Success sound');
-    const failureSoundLabel = labels?.failureSoundLabel ?? t('Failure sound');
-    const desktopTitle = labels?.desktopTitle ?? t('Desktop notifications');
-    const desktopHint = labels?.desktopHint ?? t('Show a system notification when a task finishes.');
-    const desktopUnsupported = labels?.desktopUnsupported ?? t('Desktop notifications are not supported in this browser.');
-    const desktopBlocked = labels?.desktopBlocked ?? t('Desktop notifications are blocked. Enable them in your browser settings.');
-    const sendTestLabel = labels?.sendTestLabel ?? t('Send test notification');
-    const testSentLabel = labels?.testSentLabel ?? t('Test notification sent.');
-    const testFailedLabel = labels?.testFailedLabel ?? t('Could not send a test notification.');
-    const activeLabel = labels?.activeLabel ?? t('On');
-    const offLabel = labels?.offLabel ?? t('Off');
+    const label = ({ key, fallback }, _options = {}) => labels?.[key] ?? t(fallback);
+    const completionSoundTitle = label({ key: 'completionSoundTitle', fallback: 'Completion sound' });
+    const completionSoundHint = label({ key: 'completionSoundHint', fallback: 'Play a sound when a task finishes.' });
+    const successSoundLabel = label({ key: 'successSoundLabel', fallback: 'Success sound' });
+    const failureSoundLabel = label({ key: 'failureSoundLabel', fallback: 'Failure sound' });
+    const desktopTitle = label({ key: 'desktopTitle', fallback: 'Desktop notifications' });
+    const desktopHint = label({ key: 'desktopHint', fallback: 'Show a system notification when a task finishes.' });
+    const desktopUnsupported = label({ key: 'desktopUnsupported', fallback: 'Desktop notifications are not supported in this browser.' });
+    const desktopBlocked = label({ key: 'desktopBlocked', fallback: 'Desktop notifications are blocked. Enable them in your browser settings.' });
+    const sendTestLabel = label({ key: 'sendTestLabel', fallback: 'Send test notification' });
+    const testSentLabel = label({ key: 'testSentLabel', fallback: 'Test notification sent.' });
+    const testFailedLabel = label({ key: 'testFailedLabel', fallback: 'Could not send a test notification.' });
+    const activeLabel = label({ key: 'activeLabel', fallback: 'On' });
+    const offLabel = label({ key: 'offLabel', fallback: 'Off' });
     const toggleSound = () => {
         const next = !preferences.soundEnabled;
         onChange({ soundEnabled: next });
@@ -76,16 +71,21 @@ export function NotificationsTab({ preferences, onChange, testNotificationTitle,
         // outcome here rather than getting their own dead states.
         setTestStatus(result === 'shown' ? 'sent' : 'failed');
     };
-    return (_jsxs("section", { className: "jini-settings-section jini-settings-notifications", children: [_jsxs("div", { className: "jini-settings-subsection", children: [_jsxs("div", { className: "jini-settings-notify-card", children: [_jsxs("div", { className: "jini-settings-notify-card-header", children: [_jsx("h4", { children: completionSoundTitle }), _jsx("div", { className: "jini-seg-control", role: "group", "aria-label": completionSoundTitle, style: { '--seg-cols': 1 }, children: _jsx("button", { type: "button", className: 'jini-seg-btn' + (preferences.soundEnabled ? ' active' : ''), "aria-pressed": preferences.soundEnabled, "aria-label": completionSoundTitle, onClick: toggleSound, ...agentHandleProps({}, { base: agentHandle, ...({ action: 'sound-toggle', role: 'button', label: completionSoundTitle }) }), children: _jsx("span", { className: "jini-seg-title", children: preferences.soundEnabled ? activeLabel : offLabel }) }) })] }), _jsx("p", { className: "jini-hint", children: completionSoundHint })] }), preferences.soundEnabled ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "jini-settings-field", children: [_jsx("label", { children: successSoundLabel }), _jsx("div", { className: "jini-seg-control", role: "group", "aria-label": successSoundLabel, style: { '--seg-cols': SUCCESS_SOUNDS.length }, children: SUCCESS_SOUNDS.map((sound, index) => (_jsx("button", { type: "button", className: 'jini-seg-btn' + (preferences.successSoundId === sound.id ? ' active' : ''), "aria-pressed": preferences.successSoundId === sound.id, onClick: () => {
-                                                onChange({ successSoundId: sound.id });
-                                                playSound(sound.id);
-                                            }, ...agentHandleProps({}, { base: successSoundHandles?.[index], ...({ role: 'button', label: t(sound.labelKey) }) }), children: _jsx("span", { className: "jini-seg-title", children: t(sound.labelKey) }) }, sound.id))) })] }), _jsxs("div", { className: "jini-settings-field", children: [_jsx("label", { children: failureSoundLabel }), _jsx("div", { className: "jini-seg-control", role: "group", "aria-label": failureSoundLabel, style: { '--seg-cols': FAILURE_SOUNDS.length }, children: FAILURE_SOUNDS.map((sound, index) => (_jsx("button", { type: "button", className: 'jini-seg-btn' + (preferences.failureSoundId === sound.id ? ' active' : ''), "aria-pressed": preferences.failureSoundId === sound.id, onClick: () => {
-                                                onChange({ failureSoundId: sound.id });
-                                                playSound(sound.id);
-                                            }, ...agentHandleProps({}, { base: failureSoundHandles?.[index], ...({ role: 'button', label: t(sound.labelKey) }) }), children: _jsx("span", { className: "jini-seg-title", children: t(sound.labelKey) }) }, sound.id))) })] })] })) : null] }), _jsxs("div", { className: "jini-settings-subsection", children: [_jsxs("div", { className: "jini-settings-notify-card", children: [_jsxs("div", { className: "jini-settings-notify-card-header", children: [_jsx("h4", { children: desktopTitle }), _jsx("div", { className: "jini-seg-control", role: "group", "aria-label": desktopTitle, style: { '--seg-cols': 1 }, children: _jsx("button", { type: "button", className: 'jini-seg-btn' + (preferences.desktopEnabled ? ' active' : ''), "aria-pressed": preferences.desktopEnabled, "aria-label": desktopTitle, disabled: permission === 'unsupported', onClick: () => {
-                                                void toggleDesktop();
-                                            }, ...agentHandleProps({}, { base: agentHandle, ...({ action: 'desktop-toggle', role: 'button', label: desktopTitle }) }), children: _jsx("span", { className: "jini-seg-title", children: preferences.desktopEnabled ? activeLabel : offLabel }) }) })] }), _jsx("p", { className: "jini-hint", children: desktopHint })] }), permission === 'unsupported' ? _jsx("p", { className: "jini-hint", children: desktopUnsupported }) : null, permission === 'denied' ? _jsx("p", { className: "jini-hint", children: desktopBlocked }) : null, preferences.desktopEnabled && permission === 'granted' ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "jini-button jini-button-ghost", onClick: () => {
+    return (_jsxs("section", { className: "jini-settings-section jini-settings-notifications", children: [_jsxs("div", { className: "jini-settings-subsection", children: [_jsxs("div", { className: "jini-settings-notify-card", children: [_jsxs("div", { className: "jini-settings-notify-card-header", children: [_jsx("h4", { children: completionSoundTitle }), _jsx(NotificationToggle, { title: completionSoundTitle, enabled: preferences.soundEnabled, onToggle: toggleSound, activeLabel: activeLabel, offLabel: offLabel, agentHandle: agentHandle, action: "sound-toggle" })] }), _jsx("p", { className: "jini-hint", children: completionSoundHint })] }), preferences.soundEnabled ? (_jsxs(_Fragment, { children: [_jsx(SoundPicker, { label: successSoundLabel, sounds: SUCCESS_SOUNDS, selectedSoundId: preferences.successSoundId, preferenceKey: "successSoundId", onChange: onChange, previewSound: playSound, agentHandle: agentHandle, action: "success-sound" }), _jsx(SoundPicker, { label: failureSoundLabel, sounds: FAILURE_SOUNDS, selectedSoundId: preferences.failureSoundId, preferenceKey: "failureSoundId", onChange: onChange, previewSound: playSound, agentHandle: agentHandle, action: "failure-sound" })] })) : null] }), _jsxs("div", { className: "jini-settings-subsection", children: [_jsxs("div", { className: "jini-settings-notify-card", children: [_jsxs("div", { className: "jini-settings-notify-card-header", children: [_jsx("h4", { children: desktopTitle }), _jsx(NotificationToggle, { title: desktopTitle, enabled: preferences.desktopEnabled, onToggle: toggleDesktop, activeLabel: activeLabel, offLabel: offLabel, agentHandle: agentHandle, action: "desktop-toggle", disabled: permission === 'unsupported' })] }), _jsx("p", { className: "jini-hint", children: desktopHint })] }), permission === 'unsupported' ? _jsx("p", { className: "jini-hint", children: desktopUnsupported }) : null, permission === 'denied' ? _jsx("p", { className: "jini-hint", children: desktopBlocked }) : null, preferences.desktopEnabled && permission === 'granted' ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "jini-button jini-button-ghost", onClick: () => {
                                     void sendTestNotification();
                                 }, ...agentHandleProps({}, { base: agentHandle, ...({ action: 'send-test', role: 'button', label: sendTestLabel }) }), children: sendTestLabel }), testStatus ? (_jsx("p", { className: "jini-hint", role: "status", children: testStatusLabel(testStatus, { testSentLabel, testFailedLabel }) })) : null] })) : null] })] }));
 }
+function NotificationToggle({ title, enabled, onToggle, activeLabel, offLabel, agentHandle, action, disabled, }) {
+    return (_jsx("div", { className: "jini-seg-control", role: "group", "aria-label": title, style: { '--seg-cols': 1 }, children: _jsx("button", { type: "button", className: 'jini-seg-btn' + (enabled ? ' active' : ''), "aria-pressed": enabled, "aria-label": title, disabled: disabled, onClick: () => { void onToggle(); }, ...agentHandleProps({}, { base: agentHandle, action, role: 'button', label: title }), children: _jsx("span", { className: "jini-seg-title", children: enabled ? activeLabel : offLabel }) }) }));
+}
+function SoundPicker({ label, sounds, selectedSoundId, preferenceKey, onChange, previewSound, agentHandle, action, }) {
+    const t = useT();
+    const handles = agentHandle
+        ? buildAgentListHandles({ prefix: agentSubHandle({ base: agentHandle, action }), ids: sounds.map((sound) => sound.id) })
+        : undefined;
+    return (_jsxs("div", { className: "jini-settings-field", children: [_jsx("label", { children: label }), _jsx("div", { className: "jini-seg-control", role: "group", "aria-label": label, style: { '--seg-cols': sounds.length }, children: sounds.map((sound, index) => (_jsx("button", { type: "button", className: 'jini-seg-btn' + (selectedSoundId === sound.id ? ' active' : ''), "aria-pressed": selectedSoundId === sound.id, onClick: () => {
+                        onChange({ [preferenceKey]: sound.id });
+                        previewSound(sound.id);
+                    }, ...agentHandleProps({}, { base: handles?.[index], role: 'button', label: t(sound.labelKey) }), children: _jsx("span", { className: "jini-seg-title", children: t(sound.labelKey) }) }, sound.id))) })] }));
+}
 //# sourceMappingURL=NotificationsTab.js.map

package/dist/features/observability/long-task.d.ts

@@ -1,15 +1,3 @@
-/**
- * Long task observer.
- *
- * Reports a `client_long_task` event whenever the main thread is blocked
- * for more than `minDurationMs`. Long tasks are a strong proxy for
- * perceived UI lag — a 500 ms task drops 30 consecutive frames at 60 fps,
- * which the user reads as "stuck".
- *
- * Threshold defaults to 100 ms rather than the W3C 50 ms minimum because
- * the browser already filters at 50 ms; bumping to 100 ms here halves the
- * event volume while still catching every task a human notices.
- */
 import { type SafetyEventReporter } from './ports.js';
 export interface LongTaskObserverOptions {
     reporter?: SafetyEventReporter | undefined;

package/dist/features/observability/long-task.js

@@ -10,6 +10,7 @@
  * the browser already filters at 50 ms; bumping to 100 ms here halves the
  * event volume while still catching every task a human notices.
  */
+import { telemetryUrl } from './telemetry-url.js';
 import { noopSafetyEventReporter } from './ports.js';
 const DEFAULT_MIN_DURATION_MS = 100;
 let observer = null;
@@ -46,37 +47,32 @@ export function installLongTaskObserver(options = {}) {
                 container_type: attribution?.containerType,
                 container_name: attribution?.containerName,
                 // containerSrc can carry a query string; trimmed to origin+pathname.
-                container_src_origin: stripUrlQuery(attribution?.containerSrc),
+                container_src_origin: telemetryUrl({ value: attribution?.containerSrc }),
             });
         }
     });
-    try {
-        observer.observe({ type: 'longtask', buffered: true });
-    }
-    catch {
-        // Older engines sometimes throw when `buffered` is requested.
-        try {
-            observer.observe({ type: 'longtask' });
-        }
-        catch {
-            observer = null;
-            return () => undefined;
-        }
+    if (!observeLongTasks({ observe: (options) => observer.observe(options) })) {
+        observer = null;
+        return () => undefined;
     }
     return () => {
         observer?.disconnect();
         observer = null;
     };
 }
-function stripUrlQuery(value) {
-    if (typeof value !== 'string' || value.length === 0)
-        return undefined;
+function observeLongTasks({ observe }, _options = {}) {
     try {
-        const parsed = new URL(value);
-        return `${parsed.origin}${parsed.pathname}`;
+        observe({ type: 'longtask', buffered: true });
     }
     catch {
-        return value;
+        // Older engines sometimes throw when `buffered` is requested.
+        try {
+            observe({ type: 'longtask' });
+        }
+        catch {
+            return false;
+        }
     }
+    return true;
 }
 //# sourceMappingURL=long-task.js.map

package/dist/features/observability/resource-error.d.ts

@@ -1,13 +1,3 @@
-/**
- * Resource-loading error observer.
- *
- * The bubbling `error` event (registered with capture=false) catches
- * thrown JS errors but NOT failed resource loads — `<script>`, `<link>`,
- * `<img>`, etc. emit an `error` event that does not propagate. To pick
- * those up we register a *capturing* listener on `window`. This is the
- * canonical pattern for chunk-load failures: a missing static bundle
- * chunk results in a non-functional app with no JS exception.
- */
 import { type SafetyEventReporter } from './ports.js';
 export interface ResourceErrorObserverOptions {
     reporter?: SafetyEventReporter | undefined;

package/dist/features/observability/resource-error.js

@@ -8,6 +8,7 @@
  * canonical pattern for chunk-load failures: a missing static bundle
  * chunk results in a non-functional app with no JS exception.
  */
+import { telemetryUrl } from './telemetry-url.js';
 import { noopSafetyEventReporter } from './ports.js';
 const RESOURCE_TAGS = new Set(['SCRIPT', 'LINK', 'IMG', 'IFRAME', 'AUDIO', 'VIDEO', 'SOURCE', 'TRACK']);
 let installed = false;
@@ -29,8 +30,8 @@ export function installResourceErrorObserver(options = {}) {
             return;
         if (!RESOURCE_TAGS.has(target.tagName))
             return;
-        const src = readSrc(target);
-        if (src == null)
+        const src = telemetryUrl({ value: readSrc(target) });
+        if (typeof src !== 'string' || src.length === 0)
             return;
         reporter('client_resource_error', {
             tag: target.tagName.toLowerCase(),
@@ -50,16 +51,20 @@ export function installResourceErrorObserver(options = {}) {
     };
 }
 function readSrc(el) {
-    const value = el instanceof HTMLLinkElement ? el.href :
-        el instanceof HTMLScriptElement ? el.src :
-            el instanceof HTMLImageElement ? el.src :
-                el instanceof HTMLIFrameElement ? el.src :
-                    el instanceof HTMLSourceElement ? el.src :
-                        el instanceof HTMLTrackElement ? el.src :
-                            el instanceof HTMLMediaElement ? el.src :
-                                (el.getAttribute('src') ?? el.getAttribute('href'));
-    if (typeof value !== 'string' || value.length === 0)
-        return null;
-    return value;
+    if (el instanceof HTMLLinkElement)
+        return el.href;
+    if (el instanceof HTMLScriptElement)
+        return el.src;
+    if (el instanceof HTMLImageElement)
+        return el.src;
+    if (el instanceof HTMLIFrameElement)
+        return el.src;
+    if (el instanceof HTMLSourceElement)
+        return el.src;
+    if (el instanceof HTMLTrackElement)
+        return el.src;
+    if (el instanceof HTMLMediaElement)
+        return el.src;
+    return el.getAttribute('src') ?? el.getAttribute('href');
 }
 //# sourceMappingURL=resource-error.js.map

package/dist/features/observability/stuck-run.js

@@ -79,8 +79,8 @@ function scheduleEmit(runId, stuckAfterMs) {
     return setTimeout(() => emitStuck(runId), stuckAfterMs);
 }
 function emitStuck(runId) {
-    const entry = runs.get(runId);
-    // `!entry || entry.emitted` is a defensive invariant guard, empirically
+    // Asserted present: there is no `!entry || entry.emitted` guard here (removed in the 2026-10-21
+    // coverage pass). Such a guard was a defensive invariant check, empirically
     // and structurally unreachable through this module's real call graph
     // today: `emitStuck` only ever runs as a `setTimeout` callback created by
     // `scheduleEmit`, and every path that could remove or re-flag an entry
@@ -88,13 +88,17 @@ function emitStuck(runId) {
     // `clearTimeout`s that exact timer first — in this single-threaded
     // runtime, a cleared timer's callback can never still fire. So by the
     // time this callback runs, its entry is guaranteed to both exist and
-    // have `emitted === false`. Left in place (not stripped) as a guard
+    // have `emitted === false`. Unreachable code is refactored away rather than fake-tested — see
+    // packages/ui/archived provenance ledger's 2026-07-22 dated entry for the full proof.
+    //
+    // Original rationale for the removed guard, kept verbatim (moved, not deleted) so the trade-off
+    // stays visible to whoever revisits it: "Left in place (not stripped) as a guard
     // against a future refactor silently breaking that invariant — see
     // packages/ui/archived provenance ledger's 2026-07-22 dated entry for the full proof,
     // matching this task's own standard for documenting provable
-    // unreachability instead of forcing a test.
-    if (!entry || entry.emitted)
-        return;
+    // unreachability instead of forcing a test." A refactor that lets a cleared or re-flagged
+    // entry reach this callback must therefore restore that guard here.
+    const entry = runs.get(runId);
     entry.emitted = true;
     entry.reporter('client_run_stuck', {
         run_id: runId,

package/dist/features/observability/telemetry-url.d.ts

@@ -0,0 +1,6 @@
+/** Returns an HTTP(S) URL's origin/path, or a relative pathname, with no credentials/query/fragment.
+ * Invalid and opaque URLs are omitted. O(n) time/space in input length. */
+export declare function telemetryUrl({ value }: {
+    value: unknown;
+}, _options?: {}): string | undefined;
+//# sourceMappingURL=telemetry-url.d.ts.map

package/dist/features/observability/telemetry-url.js

@@ -0,0 +1,16 @@
+/** Returns an HTTP(S) URL's origin/path, or a relative pathname, with no credentials/query/fragment.
+ * Invalid and opaque URLs are omitted. O(n) time/space in input length. */
+export function telemetryUrl({ value }, _options = {}) {
+    if (typeof value !== 'string' || value.length === 0 || /\s/.test(value))
+        return undefined;
+    try {
+        const parsed = new URL(value, 'https://telemetry.invalid/');
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return undefined;
+        return /^[a-z][a-z0-9+.-]*:|^\/\//i.test(value) ? `${parsed.origin}${parsed.pathname}` : parsed.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=telemetry-url.js.map

package/dist/features/observability/white-screen.js

@@ -55,26 +55,23 @@ export function installWhiteScreenDetector(options = {}) {
         minVisibleText,
         rootElementId,
     });
-    let cancelled = false;
-    // The `cancelled` guards at the top of this timer callback and inside the
-    // `monitorMount` completion callback just below are defensive invariant
-    // checks, empirically and structurally unreachable through this
-    // function's real call graph: both places that ever set
+    // There is no `cancelled` flag guarding the timer callback or the
+    // `monitorMount` completion callback just below. Such guards were defensive
+    // invariant checks, empirically and structurally unreachable through this
+    // function's real call graph: both places that ever set the old
     // `cancelled = true` (this closure's returned teardown, and the
     // `monitorMount` completion callback itself) always call
     // `window.clearTimeout(timer)` / `observer.disconnect()` synchronously in
     // that same turn — and in this single-threaded runtime, a timer that's
     // been cleared (or a `MutationObserver` that's been disconnected, which
     // also discards its pending record queue per spec) can never still fire
-    // its callback afterward. So by the time either callback runs at all,
-    // `cancelled` is guaranteed to still be its initial `false`. Left in
-    // place (not stripped) as a guard against a future refactor silently
-    // breaking that invariant — see packages/ui/archived provenance ledger's 2026-07-22
-    // dated entry for the full proof, same pattern as this package's
-    // `stuck-run.ts` `emitStuck` precedent.
+    // its callback afterward. So neither callback can run after teardown or
+    // after the other has finished. The guards (and the then write-only flag)
+    // were removed in the 2026-10-21 coverage pass — unreachable code is
+    // refactored away rather than fake-tested; see packages/ui/archived
+    // provenance ledger's 2026-07-22 dated entry for the full proof, same
+    // pattern as this package's `stuck-run.ts` `emitStuck`.
     const timer = window.setTimeout(() => {
-        if (cancelled)
-            return;
         if (isAppMounted())
             return;
         reporter('client_white_screen', {
@@ -89,13 +86,9 @@ export function installWhiteScreenDetector(options = {}) {
         });
     }, timeoutMs);
     const stopMonitor = monitorMount(isAppMounted, () => {
-        if (cancelled)
-            return;
-        cancelled = true;
         window.clearTimeout(timer);
     });
     return () => {
-        cancelled = true;
         window.clearTimeout(timer);
         stopMonitor();
     };
@@ -141,8 +134,8 @@ function isLoadingShell(el, loadingShellClasses) {
     return false;
 }
 function monitorMount(isAppMounted, onMounted) {
-    let stopped = false;
-    // The `stopped` guard at the top of this callback is a defensive
+    // There is no `stopped` flag or guard at the top of this callback (both
+    // removed in the 2026-10-21 coverage pass) — the guard was a defensive
     // invariant check, empirically confirmed unreachable: a `MutationObserver`
     // callback fires at most once per batch of queued mutation records
     // (never re-entrantly mid-callback), `stopped` only ever flips to `true`
@@ -157,10 +150,7 @@ function monitorMount(isAppMounted, onMounted) {
     // zero more. See packages/ui/archived provenance ledger's 2026-07-22 dated entry for
     // the full record.
     const observer = new MutationObserver(() => {
-        if (stopped)
-            return;
         if (isAppMounted()) {
-            stopped = true;
             observer.disconnect();
             onMounted();
         }
@@ -178,12 +168,10 @@ function monitorMount(isAppMounted, onMounted) {
     // Best-effort short-circuit: if the app is already mounted by the time
     // this runs (HMR, slow tab, etc.), fire immediately.
     if (isAppMounted()) {
-        stopped = true;
         observer.disconnect();
         onMounted();
     }
     return () => {
-        stopped = true;
         observer.disconnect();
     };
 }

package/dist/features/panel-kit/fetch-query/adapter.react.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import { type FetchQueryEnvironmentPort } from '@jini-ai/core/fetch';
-import type { CachedLoader, CachedLoaderOptions, FetchMutationOptions, FetchQueryOptions, MutationResult, QueryKey, QueryResult } from '@jini-ai/core/fetch';
+import type { CachedLoader, CachedLoaderDefaults, CachedLoaderOptions, FetchMutationOptions, FetchQueryOptions, MutationResult, QueryKey, QueryResult } from '@jini-ai/core/fetch';
 /** Isolated cache scope; no external provider or query-library singleton is needed. */
 export declare function FetchQueryProvider({ children, environment }: {
     children: ReactNode;
@@ -27,7 +27,7 @@ export declare function useFetchQuery<T>(required: Pick<FetchQueryOptions<T>, "k
 /** A write returns its rejection to awaiting callers and also handles discarded promises. */
 export declare function useFetchMutation<TInput, TOutput>(required: Pick<FetchMutationOptions<TInput, TOutput>, "run">, optional?: Omit<FetchMutationOptions<TInput, TOutput>, "run">): MutationResult<TInput, TOutput>;
 /** Promise loader sharing the provider cache; replace wins over an older in-flight read. */
-export declare function useCachedLoader<T>({ key, fetch }: Pick<CachedLoaderOptions<T>, "key" | "fetch">, { staleTime }?: Omit<CachedLoaderOptions<T>, "key" | "fetch">): CachedLoader<T>;
+export declare function useCachedLoader<T>({ key, fetch }: CachedLoaderDefaults<T>, { staleTime }?: Omit<CachedLoaderOptions<T>, "key" | "fetch">): CachedLoader<T>;
 /** Prefix invalidation refreshes every currently enabled read under that key. */
 export declare function useInvalidate(): (required: {
     key: QueryKey;

package/dist/features/panel-kit/fetch-query/adapter.react.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
-import { DEFAULT_STALE_TIME, FetchQueryCache, toQueryError } from '@jini-ai/core/fetch';
+import { DEFAULT_STALE_TIME, FetchQueryCache, toQueryError, withCachedLoaderFetch } from '@jini-ai/core/fetch';
 import { browserFetchQueryEnvironment } from './environment.browser.js';
 import { FetchQueryBinding } from './binding.react.js';
 const CacheContext = createContext(null);
@@ -109,7 +109,9 @@ export function useCachedLoader({ key, fetch }, { staleTime = DEFAULT_STALE_TIME
     const cache = useCache();
     return useMemo(() => ({
         peek: () => cache.entry({ key: key }, { staleTime: staleTime }).state.data,
-        load: (required = { key, fetch }) => cache.load({ entry: cache.entry({ key: required.key }, { staleTime }), fetch: required.fetch, staleTime }),
+        // `fetch` is the loader's optional default; `withCachedLoaderFetch` rejects an argument-less read
+        // that has none before the cache is touched (see `CachedLoaderDefaults`).
+        load: (required = { key, fetch }, { staleTime: readStaleTime = staleTime } = {}) => withCachedLoaderFetch(required, read => cache.load({ entry: cache.entry({ key: read.key }, { staleTime }), fetch: read.fetch, staleTime: readStaleTime })),
         replace: ({ value }) => cache.replace({ entry: cache.entry({ key: key }, { staleTime: staleTime }), data: value }),
     }), [cache, key, fetch, staleTime]);
 }

package/dist/features/panel-kit/fetch-query/adapter.tanstack.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 /** Optional TanStack translation layer. No library types escape the fetch-query contract. */
 import { createContext, useCallback, useContext, useEffect, useMemo, useSyncExternalStore } from 'react';
 import { isCancelledError, replaceEqualDeep, QueryClient, QueryClientProvider, useMutation, useQuery } from '@tanstack/react-query';
-import { DEFAULT_STALE_TIME, FetchQueryCache, IDLE_RETENTION, toQueryError } from '@jini-ai/core/fetch';
+import { DEFAULT_STALE_TIME, FetchQueryCache, IDLE_RETENTION, toQueryError, withCachedLoaderFetch } from '@jini-ai/core/fetch';
 import { browserFetchQueryEnvironment } from './environment.browser.js';
 import { resolveFetchQueryError, resolveFetchQueryStatus } from './adapter.react.js';
 import { FetchQueryBinding } from './binding.react.js';
@@ -42,12 +42,12 @@ export function FetchQueryProvider({ children, environment = browserFetchQueryEn
     }, [scope, environment]);
     return _jsx(QueryClientProvider, { client: scope.client, children: _jsx(ScopeContext.Provider, { value: scope, children: _jsx(FetchQueryBinding, { adapter: adapter, children: children }) }) });
 }
-/** Fail closed when an adapter hook is used without its provider. */
+/** The provider's scope. This adapter's hooks are not exported: the only route to them is the
+ * `adapter` object this module's own `FetchQueryProvider` binds INSIDE its `ScopeContext`, and the
+ * public hooks already fail closed without a provider (`binding.react.tsx`'s `useAdapter`). So the
+ * old "no scope" throw here was unreachable and is gone; the guarantee is that binding order. */
 function useScope() {
-    const scope = useContext(ScopeContext);
-    if (!scope)
-        throw new Error('Fetch-query hooks require FetchQueryProvider');
-    return scope;
+    return useContext(ScopeContext);
 }
 /** Observe only this provider's connectivity; paused reads do not claim network activity. */
 function useOnline({ environment }) {
@@ -174,40 +174,53 @@ function useFetchMutation({ run }, { invalidates } = {}) {
     }, [mutateAsync]);
     return { mutate, status: mutation.status, error: mutation.status === 'error' ? toQueryError(mutation.error) : null, reset };
 }
+/**
+ * One loader read of `required.key`, unwrapped to its value. Lifted out of `useCachedLoader`'s `load`
+ * verbatim so the missing-fetch guard (`withCachedLoaderFetch`) wrapping it does not push its
+ * callbacks past the function-nesting limit.
+ */
+function loadLoaderQuery({ scope, options, required, staleTime }) {
+    const selected = { ...options, staleTime, queryKey: required.key, queryFn: () => read({ scope, key: required.key, fetch: required.fetch }),
+        structuralSharing: (previous, incoming) => saveResult({ scope, key: required.key, previous, incoming }) };
+    return scope.client.fetchQuery(selected).catch(error => {
+        // A forced refresh can supersede a loader's request without aborting its transport.
+        // Follow the new request instead of exposing TanStack's cancellation vocabulary.
+        if (!isCancelledError(error))
+            throw error;
+        // Invalidation also supersedes loader-only reads. Join (or start) the post-write
+        // request rather than returning an obsolete value while the key is invalidated.
+        const query = scope.client.getQueryCache().find({ queryKey: required.key, exact: true });
+        if (query.state.isInvalidated)
+            return scope.client.fetchQuery(selected);
+        return (query.promise ?? scope.client.getQueryData(required.key));
+    }).then(result => {
+        const query = scope.client.getQueryCache().find({ queryKey: required.key, exact: true });
+        const history = historyFor({ scope, query });
+        // Query.fetch returns the transport envelope, not structuralSharing's accepted value.
+        // Unwrap against the current generation so awaiting loaders agree with observers.
+        if (result.generation !== history.replacement)
+            return scope.client.getQueryData(required.key).value;
+        if ('error' in result)
+            throw result.error;
+        return result.value;
+    });
+}
 /** Loader shares reactive reads, retains fresh idle values, and protects replacement writes. */
 function useCachedLoader({ key, fetch }, { staleTime = DEFAULT_STALE_TIME } = {}) {
     const scope = useScope();
     return useMemo(() => {
-        const options = { queryKey: key, queryFn: () => read({ scope, key, fetch }),
+        // The template every loader query starts from. It carries no `queryFn`: `load` always supplies
+        // its own (for `required.key`), an observer that later mounts on a `replace`-created query
+        // installs the observer's, and an unobserved query is never refetched — so a template `queryFn`
+        // here could never run. Its `structuralSharing` does run: `replace` on a cold key builds the query
+        // from this template and publishes through it.
+        const options = { queryKey: key,
             structuralSharing: (previous, incoming) => saveResult({ scope, key, previous, incoming }), staleTime, gcTime: gcTimeFor({ staleTime }) };
         return {
             peek: () => scope.client.getQueryData(key)?.value,
-            load: (required = { key, fetch }) => {
-                const selected = { ...options, queryKey: required.key, queryFn: () => read({ scope, key: required.key, fetch: required.fetch }),
-                    structuralSharing: (previous, incoming) => saveResult({ scope, key: required.key, previous, incoming }) };
-                return scope.client.fetchQuery(selected).catch(error => {
-                    // A forced refresh can supersede a loader's request without aborting its transport.
-                    // Follow the new request instead of exposing TanStack's cancellation vocabulary.
-                    if (!isCancelledError(error))
-                        throw error;
-                    // Invalidation also supersedes loader-only reads. Join (or start) the post-write
-                    // request rather than returning an obsolete value while the key is invalidated.
-                    const query = scope.client.getQueryCache().find({ queryKey: required.key, exact: true });
-                    if (query.state.isInvalidated)
-                        return scope.client.fetchQuery(selected);
-                    return (query.promise ?? scope.client.getQueryData(required.key));
-                }).then(result => {
-                    const query = scope.client.getQueryCache().find({ queryKey: required.key, exact: true });
-                    const history = historyFor({ scope, query });
-                    // Query.fetch returns the transport envelope, not structuralSharing's accepted value.
-                    // Unwrap against the current generation so awaiting loaders agree with observers.
-                    if (result.generation !== history.replacement)
-                        return scope.client.getQueryData(required.key).value;
-                    if ('error' in result)
-                        throw result.error;
-                    return result.value;
-                });
-            },
+            // `fetch` is the loader's optional default; `withCachedLoaderFetch` rejects an argument-less read
+            // that has none before any query is built (see `CachedLoaderDefaults`).
+            load: (requested = { key, fetch }, { staleTime: readStaleTime = staleTime } = {}) => withCachedLoaderFetch(requested, required => loadLoaderQuery({ scope, options, required, staleTime: readStaleTime })),
             replace: ({ value }) => {
                 const query = scope.client.getQueryCache().build(scope.client, options);
                 const history = historyFor({ scope, query });

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

@@ -26,8 +26,10 @@ export const LOCAL_BACKUP_PRINCIPAL_ID = "local-tab-backup";
  * @complexity O(draft size) for reads/writes; O(1) for clears.
  */
 export function createStandingDraftLocalBackup({ keyPrefix: KEY_PREFIX, getStorage }, _options = {}) {
+    // Never sees a `null` principal: write/read/clear each return before reaching storage for one, so
+    // the old `principalId ?? ""` fallback here could not run.
     function keyFor(entryId, principalId) {
-        return principalId === undefined ? `${KEY_PREFIX}${entryId}` : `${KEY_PREFIX}${encodeURIComponent(principalId ?? "")}.${encodeURIComponent(entryId)}`;
+        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`. */

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

@@ -261,7 +261,9 @@ export function useSettingsSlice(options, _optional = {}) {
         // left to paint. The write itself still has to happen — through the same
         // lane as the debounce path, so it diffs against the base that is
         // current when it RUNS, not the one that was current when it was queued.
-        void writes.run({ task: () => runSave().then(() => { }, () => { }) });
+        void writes.run({ task: () => runSave().then(() => { }, 
+            // No view remains to show the failure; settings and native errors may contain secrets.
+            () => { console.error('[settings] Final save failed after unmount.'); }) });
     }, [runSave, writes]);
     const onChange = useCallback((next) => {
         setValue(next);