@jini-ai/ui 0.3.14 → 0.4.0

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

@@ -28,10 +28,10 @@ import { testStatusLabel } from '../../rules.js';
 export function NotificationsTab({ preferences, onChange, testNotificationTitle, testNotificationBody, labels, agentHandle, }) {
     const t = useT();
     const successSoundHandles = agentHandle
-        ? buildAgentListHandles(agentSubHandle(agentHandle, 'success-sound'), SUCCESS_SOUNDS.map((s) => s.id))
+        ? buildAgentListHandles({ prefix: agentSubHandle({ base: agentHandle, action: 'success-sound' }), ids: SUCCESS_SOUNDS.map((s) => s.id) })
         : undefined;
     const failureSoundHandles = agentHandle
-        ? buildAgentListHandles(agentSubHandle(agentHandle, 'failure-sound'), FAILURE_SOUNDS.map((s) => s.id))
+        ? 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);
@@ -76,16 +76,16 @@ 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(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: () => {
+    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(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: () => {
+                                            }, ...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(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: () => {
+                                            }, ...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(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: () => {
+                                            }, ...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: () => {
                                     void sendTestNotification();
-                                }, ...agentHandleProps(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] })] }));
+                                }, ...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] })] }));
 }
 //# sourceMappingURL=NotificationsTab.js.map

package/dist/features/notifications/types.d.ts

@@ -2,7 +2,7 @@
  * Origin: `NotificationsSection` in `SettingsDialog.tsx` (completion-sound
  * toggle/picker + browser Notification-permission flow), GENERIC per
  * `ADS-memory/reports/jini-port/recon/r6-god-component-internals.md` §1.3 — browser-API
- * only, zero product-domain coupling. See `packages/ui/source-map.md` for
+ * only, zero product-domain coupling. See `packages/ui/archived provenance ledger` for
  * the full provenance note.
  */
 import type { SoundId } from './notifications-catalog.js';

package/dist/features/observability/boot-timing.js

@@ -59,7 +59,7 @@ export function installBootTimingObserver(options = {}) {
 // only ever runs after that function's own `typeof window === 'undefined'`
 // guard has already passed, so a second check here was dead code for every
 // real call — removed rather than tested around (see
-// packages/ui/source-map.md's 2026-07-22 dated entry).
+// packages/ui/archived provenance ledger's 2026-07-22 dated entry).
 function schedule(fn) {
     const rIC = window.requestIdleCallback;
     if (typeof rIC === 'function') {
@@ -90,7 +90,7 @@ function emit(reporter) {
         // resolvable in global scope by the time this line runs; a `typeof
         // document !== 'undefined'` re-check here was dead code for every real
         // call, removed rather than tested around (see
-        // packages/ui/source-map.md's 2026-07-22 dated entry).
+        // packages/ui/archived provenance ledger's 2026-07-22 dated entry).
         visibility_state: document.visibilityState,
     });
 }

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

@@ -90,7 +90,7 @@ function emitStuck(runId) {
     // time this callback runs, its entry is guaranteed to both exist and
     // have `emitted === false`. Left in place (not stripped) as a guard
     // against a future refactor silently breaking that invariant — see
-    // packages/ui/source-map.md's 2026-07-22 dated entry for the full proof,
+    // 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)

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

@@ -69,7 +69,7 @@ export function installWhiteScreenDetector(options = {}) {
     // 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/source-map.md's 2026-07-22
+    // 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.
     const timer = window.setTimeout(() => {
@@ -105,7 +105,7 @@ function checkAppMounted(options) {
     // `installWhiteScreenDetector`, itself only ever reachable after that
     // function's own `typeof document === 'undefined'` guard has already
     // passed — a second check here was dead code for every real call,
-    // removed rather than tested around (see packages/ui/source-map.md's
+    // removed rather than tested around (see packages/ui/archived provenance ledger's
     // 2026-07-22 dated entry).
     // Primary signal: the host's root-mount effect ran.
     if (document.documentElement.getAttribute(options.mountedAttribute) === options.mountedAttributeValue) {
@@ -126,7 +126,7 @@ function checkAppMounted(options) {
         // only for `Document`/`DocumentType` nodes — for any `Element` it is
         // always a string (possibly `''`). The `?? ''` fallback this used to
         // have was dead code for every real entry here, removed rather than
-        // tested around (see packages/ui/source-map.md's 2026-07-22 dated
+        // tested around (see packages/ui/archived provenance ledger's 2026-07-22 dated
         // entry).
         .map((el) => el.innerText ?? el.textContent)
         .join('')
@@ -154,7 +154,7 @@ function monitorMount(isAppMounted, onMounted) {
     // about): two synchronous body mutations followed by two microtask
     // flushes produced exactly one callback invocation with `stopped` still
     // `false` at its start, and a further post-disconnect mutation produced
-    // zero more. See packages/ui/source-map.md's 2026-07-22 dated entry for
+    // zero more. See packages/ui/archived provenance ledger's 2026-07-22 dated entry for
     // the full record.
     const observer = new MutationObserver(() => {
         if (stopped)

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

@@ -0,0 +1,35 @@
+import { type ReactNode } from 'react';
+import { type FetchQueryEnvironmentPort } from './cache.js';
+import type { CachedLoader, CachedLoaderOptions, FetchMutationOptions, FetchQueryOptions, MutationResult, QueryKey, QueryResult } from './types.js';
+/** Isolated cache scope; no external provider or query-library singleton is needed. */
+export declare function FetchQueryProvider({ children, environment }: {
+    children: ReactNode;
+    environment?: FetchQueryEnvironmentPort;
+}): import("react").JSX.Element;
+/**
+ * Without prior successful data, a disabled read hides cached errors so gesture-gated
+ * content cannot display a failure the user has not asked to retry. With prior data, retain
+ * a later background failure so callers can distinguish usable data from guaranteed freshness.
+ */
+/** Disabled reads keep earlier data but suppress errors before any successful read. */
+export declare function resolveFetchQueryStatus({ disabled, hasData, status }: {
+    disabled: boolean;
+    hasData: boolean;
+    status: 'pending' | 'error' | 'success';
+}): QueryResult<unknown>['status'];
+export declare function resolveFetchQueryError({ error, disabled, hasData }: {
+    error: unknown;
+    disabled: boolean;
+    hasData: boolean;
+}): Error | null;
+/** Reactive keyed read. Background refresh keeps cached data visible. */
+export declare function useFetchQuery<T>(required: Pick<FetchQueryOptions<T>, "key" | "fetch">, optional?: Omit<FetchQueryOptions<T>, "key" | "fetch">): QueryResult<T>;
+/** 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>;
+/** Prefix invalidation refreshes every currently enabled read under that key. */
+export declare function useInvalidate(): (required: {
+    key: QueryKey;
+}) => void;
+//# sourceMappingURL=adapter.react.d.ts.map

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

@@ -0,0 +1,122 @@
+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 './cache.js';
+import { browserFetchQueryEnvironment } from './environment.browser.js';
+const CacheContext = createContext(null);
+/** Isolated cache scope; no external provider or query-library singleton is needed. */
+export function FetchQueryProvider({ children, environment = browserFetchQueryEnvironment }) {
+    // A module singleton would leak cache values between independent providers/tests,
+    // producing cases that pass alone but fail together. Scope ownership to this provider.
+    const cache = useMemo(() => new FetchQueryCache({}, { environment }), [environment]);
+    useEffect(() => {
+        cache.activate();
+        return () => cache.dispose();
+    }, [cache]);
+    return _jsx(CacheContext.Provider, { value: cache, children: children });
+}
+function useCache() {
+    const cache = useContext(CacheContext);
+    if (!cache)
+        throw new Error('Fetch-query hooks require FetchQueryProvider');
+    return cache;
+}
+/**
+ * Without prior successful data, a disabled read hides cached errors so gesture-gated
+ * content cannot display a failure the user has not asked to retry. With prior data, retain
+ * a later background failure so callers can distinguish usable data from guaranteed freshness.
+ */
+// Keep status/error folds outside subscription wiring so their branches are directly
+// testable without mounting observers; flat decisions avoid nested conditional review costs.
+/** Disabled reads keep earlier data but suppress errors before any successful read. */
+export function resolveFetchQueryStatus({ disabled, hasData, status }) {
+    if (disabled)
+        return hasData ? 'success' : 'loading';
+    return status === 'pending' ? 'loading' : status;
+}
+export function resolveFetchQueryError({ error, disabled, hasData }) {
+    if (!error || (disabled && !hasData))
+        return null;
+    return toQueryError(error);
+}
+/** Reactive keyed read. Background refresh keeps cached data visible. */
+export function useFetchQuery(required, optional = {}) {
+    const cache = useCache();
+    const options = { ...optional, ...required };
+    const { key, enabled = true, staleTime = DEFAULT_STALE_TIME, refetchOnWindowFocus = false } = options;
+    const latest = useRef(options);
+    latest.current = options;
+    const entry = cache.entry({ key: key }, { staleTime: staleTime });
+    const subscribe = useCallback((listener) => cache.subscribe({ entry: entry, listener: listener }), [cache, entry]);
+    const snapshot = useCallback(() => entry.state, [entry]);
+    const state = useSyncExternalStore(subscribe, snapshot, snapshot);
+    const fetch = useCallback(() => latest.current.fetch(), []);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const release = cache.observe({ entry: entry, observer: { fetch, staleTime, focus: refetchOnWindowFocus } });
+        void cache.load({ entry: entry, fetch: fetch, staleTime: staleTime });
+        return release;
+    }, [cache, entry, enabled, staleTime, refetchOnWindowFocus, fetch]);
+    const refetch = useCallback(() => { void cache.load({ entry: entry, fetch: fetch, staleTime: staleTime }, { force: true }); }, [cache, entry, fetch, staleTime]);
+    const hasData = state.data !== undefined;
+    return {
+        data: state.data,
+        status: resolveFetchQueryStatus({ disabled: !enabled, hasData: hasData, status: state.status }),
+        error: resolveFetchQueryError({ error: state.error, disabled: !enabled, hasData: hasData }),
+        isFetching: state.isFetching, refetch,
+    };
+}
+/** A write returns its rejection to awaiting callers and also handles discarded promises. */
+export function useFetchMutation(required, optional = {}) {
+    const cache = useCache();
+    const options = { ...optional, ...required };
+    const latest = useRef(options);
+    latest.current = options;
+    const generation = useRef(0);
+    const mounted = useRef(true);
+    useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+    const [state, setState] = useState({ status: 'idle', error: null });
+    const mutate = useCallback(({ input }) => {
+        const current = ++generation.current;
+        const { run, invalidates } = latest.current;
+        setState({ status: 'pending', error: null });
+        // Surface a rejected write immediately instead of silently retrying authorization or
+        // validation failures that another identical attempt cannot fix.
+        const promise = cache.runOnline({ run: () => run({ input }) }).then(value => {
+            // Do not await dependent reads: the mutation promise means the write succeeded,
+            // not that every list finished reloading. Refetches proceed on their own schedule.
+            for (const key of invalidates ?? [])
+                cache.invalidate({ prefix: key });
+            if (mounted.current && current === generation.current)
+                setState({ status: 'success', error: null });
+            return value;
+        }, error => {
+            if (mounted.current && current === generation.current)
+                setState({ status: 'error', error: toQueryError(error) });
+            throw error;
+        });
+        // Handle this same promise for callers that discard it, while still returning it so
+        // await/catch observes the original rejection; discarding the derived promise is intentional.
+        void promise.catch(() => { });
+        return promise;
+    }, [cache]);
+    const reset = useCallback(() => { generation.current += 1; setState({ status: 'idle', error: null }); }, []);
+    return { ...state, mutate, reset };
+}
+/** Promise loader sharing the provider cache; replace wins over an older in-flight read. */
+export function useCachedLoader({ key, fetch }, { staleTime = DEFAULT_STALE_TIME } = {}) {
+    const cache = useCache();
+    return useMemo(() => ({
+        peek: () => cache.entry({ key: key }, { staleTime: staleTime }).state.data,
+        load: () => cache.load({ entry: cache.entry({ key: key }, { staleTime: staleTime }), fetch: fetch, staleTime: staleTime }),
+        replace: ({ value }) => cache.replace({ entry: cache.entry({ key: key }, { staleTime: staleTime }), data: value }),
+    }), [cache, key, fetch, staleTime]);
+}
+// Imperative invalidation also covers externally delivered events, such as an SSE change
+// feed, whose producer cannot call a React read hook or a component-local reload.
+/** Prefix invalidation refreshes every currently enabled read under that key. */
+export function useInvalidate() {
+    const cache = useCache();
+    return useCallback(({ key }) => cache.invalidate({ prefix: key }), [cache]);
+}
+//# sourceMappingURL=adapter.react.js.map

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

@@ -0,0 +1,123 @@
+import type { Clock } from '@jini-ai/core/primitives';
+import type { QueryKey } from './types.js';
+/**
+ * Ten seconds covers reading, closing and reopening a record or bouncing between screens
+ * without paying for another identical request. Five seconds was too short for that read
+ * cycle; thirty seconds exposed more other-operator staleness than the conservative initial
+ * shared default should allow. There is no default polling/focus refresh, so this bounds
+ * the extra exposure on a quick revisit. Write invalidation bypasses freshness; reads that
+ * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
+ */
+export declare const DEFAULT_STALE_TIME = 10000;
+export interface QueryCacheSchedulerPort {
+    schedule(required: {
+        callback: () => void;
+        delayMs: number;
+    }): unknown;
+    cancel(required: {
+        handle: unknown;
+    }): void;
+}
+/** Host connectivity and focus signals; the cache itself has no DOM dependency. */
+export interface FetchQueryEnvironmentPort {
+    isOnline(): boolean;
+    subscribeOnline(required: {
+        listener: (online: boolean) => void;
+    }): () => void;
+    subscribeFocus(required: {
+        listener: () => void;
+    }): () => void;
+}
+export interface FetchQueryCacheOptions {
+    clock?: Clock;
+    scheduler?: QueryCacheSchedulerPort;
+    environment?: FetchQueryEnvironmentPort;
+}
+export interface QueryState {
+    data: unknown;
+    error: Error | null;
+    status: 'pending' | 'success' | 'error';
+    isFetching: boolean;
+}
+export interface QueryObserver {
+    fetch: () => Promise<unknown>;
+    staleTime: number;
+    focus: boolean;
+}
+export interface CacheEntry {
+    key: QueryKey;
+    state: QueryState;
+    updatedAt: number;
+    invalidated: boolean;
+    replacement: number;
+    pending: Promise<unknown> | undefined;
+    refreshAfterPending: boolean;
+    listeners: Set<() => void>;
+    observers: Set<QueryObserver>;
+    retention: number;
+    eviction: unknown;
+}
+export declare function toQueryError(value: unknown): Error;
+/** One provider-owned cache. Requests are shared by structural primitive keys.
+ * Failed reads retain earlier data; replacement writes supersede older requests.
+ * Idle entries live for at least five minutes or their declared freshness period. */
+export declare class FetchQueryCache {
+    private readonly entries;
+    private disposed;
+    private readonly clock;
+    private readonly scheduler;
+    private readonly environment;
+    private online;
+    private readonly onlineWaiters;
+    private releaseEnvironment;
+    constructor(_required?: Record<string, never>, { clock, scheduler, environment }?: FetchQueryCacheOptions);
+    entry({ key }: {
+        key: QueryKey;
+    }, { staleTime }?: {
+        staleTime?: number;
+    }): CacheEntry;
+    fresh({ entry, staleTime }: {
+        entry: CacheEntry;
+        staleTime: number;
+    }): boolean;
+    subscribe({ entry, listener }: {
+        entry: CacheEntry;
+        listener: () => void;
+    }): () => void;
+    observe({ entry, observer }: {
+        entry: CacheEntry;
+        observer: QueryObserver;
+    }): () => void;
+    /** Cache hits respect freshness; explicit refreshes restart background reads.
+     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
+    load<T>({ entry, fetch, staleTime }: {
+        entry: CacheEntry;
+        fetch: () => Promise<T>;
+        staleTime: number;
+    }, { force }?: {
+        force?: boolean;
+    }): Promise<T>;
+    replace({ entry, data }: {
+        entry: CacheEntry;
+        data: unknown;
+    }): void;
+    invalidate({ prefix }: {
+        prefix: QueryKey;
+    }): void;
+    onFocus(): void;
+    /** Execute a read/write once connectivity returns; failures are not retried.
+     * @param required.run Operation to invoke online.
+     * @returns The operation's original result or rejection. */
+    runOnline<T>({ run }: {
+        run: () => Promise<T>;
+    }): Promise<T>;
+    /** Stop timers on provider disposal; reactivate for React's effect replay. */
+    activate(): void;
+    dispose(): void;
+    private onOnline;
+    private refresh;
+    private publish;
+    private cancelEviction;
+    private scheduleEviction;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/features/panel-kit/fetch-query/cache.js

@@ -0,0 +1,231 @@
+/**
+ * Ten seconds covers reading, closing and reopening a record or bouncing between screens
+ * without paying for another identical request. Five seconds was too short for that read
+ * cycle; thirty seconds exposed more other-operator staleness than the conservative initial
+ * shared default should allow. There is no default polling/focus refresh, so this bounds
+ * the extra exposure on a quick revisit. Write invalidation bypasses freshness; reads that
+ * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
+ */
+export const DEFAULT_STALE_TIME = 10_000;
+const IDLE_RETENTION = 5 * 60_000;
+const browserScheduler = {
+    schedule: ({ callback, delayMs }) => setTimeout(callback, delayMs),
+    cancel: ({ handle }) => clearTimeout(handle),
+};
+// Normalize unknown promise rejections once so consumers receive Error without repeating
+// the same narrowing boilerplate at every read and write call site.
+export function toQueryError(value) {
+    return value instanceof Error ? value : new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
+}
+/** One provider-owned cache. Requests are shared by structural primitive keys.
+ * Failed reads retain earlier data; replacement writes supersede older requests.
+ * Idle entries live for at least five minutes or their declared freshness period. */
+export class FetchQueryCache {
+    entries = new Map();
+    disposed = false;
+    clock;
+    scheduler;
+    environment;
+    online;
+    onlineWaiters = new Set();
+    releaseEnvironment;
+    constructor(_required = {}, { clock = { nowMs: () => Date.now() }, scheduler = browserScheduler, environment } = {}) {
+        this.clock = clock;
+        this.scheduler = scheduler;
+        this.environment = environment;
+        this.online = environment?.isOnline() ?? true;
+    }
+    entry({ key }, { staleTime = DEFAULT_STALE_TIME } = {}) {
+        const hash = JSON.stringify(key);
+        let entry = this.entries.get(hash);
+        if (!entry) {
+            entry = {
+                key: [...key], state: { data: undefined, error: null, status: 'pending', isFetching: false },
+                updatedAt: 0, invalidated: false, replacement: 0, pending: undefined,
+                refreshAfterPending: false, listeners: new Set(), observers: new Set(),
+                retention: IDLE_RETENTION, eviction: undefined,
+            };
+            this.entries.set(hash, entry);
+        }
+        // An imperative load has no standing observer: idle eviction must not drop a value
+        // earlier than its declared freshness and unexpectedly force another network request.
+        entry.retention = Math.max(entry.retention, staleTime);
+        return entry;
+    }
+    fresh({ entry, staleTime }) {
+        return entry.state.data !== undefined && !entry.invalidated && this.clock.nowMs() - entry.updatedAt < staleTime;
+    }
+    subscribe({ entry, listener }) {
+        this.cancelEviction(entry);
+        entry.listeners.add(listener);
+        return () => { entry.listeners.delete(listener); this.scheduleEviction(entry); };
+    }
+    observe({ entry, observer }) {
+        entry.observers.add(observer);
+        return () => { entry.observers.delete(observer); this.scheduleEviction(entry); };
+    }
+    /** Cache hits respect freshness; explicit refreshes restart background reads.
+     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
+    load({ entry, fetch, staleTime }, { force = false } = {}) {
+        this.cancelEviction(entry);
+        if (entry.pending && (!force || entry.state.data === undefined))
+            return entry.pending;
+        if (!force && this.fresh({ entry: entry, staleTime: staleTime })) {
+            this.scheduleEviction(entry);
+            return Promise.resolve(entry.state.data);
+        }
+        // Shared per key across loader instances: a replacement while this request is out
+        // must win over its older answer, not just protect the instance that issued the write.
+        const replacement = entry.replacement;
+        const run = () => {
+            // A queued offline refresh may have been superseded before reconnection.
+            if (entry.pending !== pending)
+                return (entry.pending ?? Promise.resolve(entry.state.data));
+            this.publish(entry, { ...entry.state, isFetching: true });
+            return fetch();
+        };
+        const pending = Promise.resolve().then(() => {
+            if (this.online)
+                return run();
+            this.publish(entry, { ...entry.state, isFetching: false });
+            return this.runOnline({ run });
+        }).then(value => {
+            const data = replacement === entry.replacement ? value : entry.state.data;
+            // Undefined is never successful query data, including an initial or background read.
+            if (data === undefined)
+                throw new Error(`${JSON.stringify(entry.key)} data is undefined`);
+            return data;
+        }).then(data => {
+            // Only the current request may publish or clear invalidation. An older transport
+            // need not support abort: its callers follow the replacement request instead.
+            if (entry.pending !== pending)
+                return (entry.pending ?? entry.state.data);
+            entry.updatedAt = this.clock.nowMs();
+            entry.invalidated = false;
+            this.publish(entry, { data, error: null, status: 'success', isFetching: false });
+            return data;
+        }, error => {
+            if (entry.pending !== pending)
+                return (entry.pending ?? entry.state.data);
+            // A replacement write is newer than this read's failure as well as its data.
+            // Keep the write's timestamp and freshness; only settle the obsolete fetch flag.
+            if (replacement !== entry.replacement) {
+                this.publish(entry, { ...entry.state, isFetching: false });
+                return entry.state.data;
+            }
+            entry.invalidated = true;
+            this.publish(entry, { ...entry.state, error: toQueryError(error), status: 'error', isFetching: false });
+            throw error;
+        }).finally(() => {
+            if (entry.pending !== pending)
+                return;
+            entry.pending = undefined;
+            if (entry.refreshAfterPending) {
+                entry.refreshAfterPending = false;
+                this.refresh(entry);
+            }
+            this.scheduleEviction(entry);
+        });
+        entry.pending = pending;
+        // Mark handled even when a UI caller deliberately discards the promise.
+        void pending.catch(() => { });
+        // Like TanStack's background refetches, retain the last error until success clears it
+        // or another failure replaces it. Extend that rule to retries without cached data:
+        // starting a request is not evidence of recovery; isFetching reports its progress.
+        const state = entry.state.data === undefined ? { ...entry.state, status: 'pending' } : entry.state;
+        this.publish(entry, { ...state, isFetching: this.online });
+        return pending;
+    }
+    replace({ entry, data }) {
+        entry.replacement += 1;
+        entry.updatedAt = this.clock.nowMs();
+        entry.invalidated = false;
+        this.publish(entry, { data, error: null, status: 'success', isFetching: entry.state.isFetching });
+        this.scheduleEviction(entry);
+    }
+    invalidate({ prefix }) {
+        for (const entry of this.entries.values()) {
+            if (!prefix.every((part, index) => entry.key[index] === part))
+                continue;
+            entry.invalidated = true;
+            this.refresh(entry);
+        }
+    }
+    onFocus() {
+        for (const entry of this.entries.values()) {
+            const observer = [...entry.observers].find(value => value.focus && !this.fresh({ entry: entry, staleTime: value.staleTime }));
+            // Environmental refreshes share a request already underway, unlike an explicit gesture.
+            if (observer && !entry.pending)
+                void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime });
+        }
+    }
+    /** Execute a read/write once connectivity returns; failures are not retried.
+     * @param required.run Operation to invoke online.
+     * @returns The operation's original result or rejection. */
+    runOnline({ run }) {
+        if (this.online)
+            return Promise.resolve().then(() => {
+                // Connectivity may change between queuing the operation and its invocation.
+                if (!this.online)
+                    return this.runOnline({ run });
+                return run();
+            });
+        return new Promise(resolve => { this.onlineWaiters.add(resolve); }).then(() => this.runOnline({ run }));
+    }
+    /** Stop timers on provider disposal; reactivate for React's effect replay. */
+    activate() {
+        this.disposed = false;
+        if (!this.environment || this.releaseEnvironment)
+            return;
+        const releaseOnline = this.environment.subscribeOnline({ listener: online => this.onOnline({ online }) });
+        const releaseFocus = this.environment.subscribeFocus({ listener: () => this.onFocus() });
+        this.releaseEnvironment = () => { releaseOnline(); releaseFocus(); };
+        this.onOnline({ online: this.environment.isOnline() });
+    }
+    dispose() {
+        this.disposed = true;
+        this.releaseEnvironment?.();
+        this.releaseEnvironment = undefined;
+        for (const entry of this.entries.values())
+            this.cancelEviction(entry);
+    }
+    onOnline({ online }) {
+        const reconnect = online && !this.online;
+        this.online = online;
+        if (!online)
+            return;
+        for (const resume of this.onlineWaiters)
+            resume();
+        this.onlineWaiters.clear();
+        if (!reconnect)
+            return;
+        for (const entry of this.entries.values()) {
+            const observer = [...entry.observers].find(value => !this.fresh({ entry, staleTime: value.staleTime }));
+            // A paused request already owns its resumption; restarting it here would double-fetch.
+            if (observer && !entry.pending)
+                void this.load({ entry, fetch: observer.fetch, staleTime: observer.staleTime });
+        }
+    }
+    refresh(entry) {
+        const observer = entry.observers.values().next().value;
+        if (observer)
+            void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime }, { force: true });
+    }
+    publish(entry, state) {
+        entry.state = state;
+        for (const listener of entry.listeners)
+            listener();
+    }
+    cancelEviction(entry) {
+        if (entry.eviction !== undefined)
+            this.scheduler.cancel({ handle: entry.eviction });
+        entry.eviction = undefined;
+    }
+    scheduleEviction(entry) {
+        this.cancelEviction(entry);
+        if (this.disposed || entry.listeners.size || entry.observers.size || entry.pending || !Number.isFinite(entry.retention))
+            return;
+        entry.eviction = this.scheduler.schedule({ callback: () => this.entries.delete(JSON.stringify(entry.key)), delayMs: entry.retention });
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/features/panel-kit/fetch-query/environment.browser.d.ts

@@ -0,0 +1,4 @@
+import type { FetchQueryEnvironmentPort } from './cache.js';
+/** Browser-only adapter: subscriptions are owned by the provider effect, never module scope. */
+export declare const browserFetchQueryEnvironment: FetchQueryEnvironmentPort;
+//# sourceMappingURL=environment.browser.d.ts.map