@jini-ai/ui 0.4.6 → 0.4.7

package/dist/features/interactive-ui/providers/shadcn/data-table.manifest.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 /**
- * Same wire shape as `native.data-table` (see that manifest) — same capabilities, so
+ * Same required wire shape as `native.data-table` (see that manifest), plus optional local
+ * sorting/paging settings — shared capabilities, so
  * `resolveByCapability('data-table')` returns both, proving the fallback-chain mechanic across
  * two real providers. `.passthrough()` for the same reason as that manifest: an A2UI-embedded
  * instance may carry an `action` prop this schema doesn't itself validate.
@@ -9,13 +10,15 @@ export const shadcnDataTablePropsSchema = z
     .object({
     columns: z.array(z.object({ key: z.string(), label: z.string() }).strict()).min(1),
     rows: z.array(z.record(z.unknown())),
+    sortable: z.boolean().optional(),
+    pageSize: z.number().int().min(1).max(100).optional(),
 })
     .passthrough();
 export const shadcnDataTableManifest = {
     id: 'shadcn.data-table',
     provider: 'shadcn',
-    capabilities: ['data-table', 'table', 'tabular-data'],
+    capabilities: ['data-table', 'table', 'tabular-data', 'spreadsheet', 'list-of-records'],
     propsSchema: shadcnDataTablePropsSchema,
-    description: 'shadcn/ui table primitives (real CLI-pulled source), composed into columns + rows, optional row click.',
+    description: 'Preferred styled table for tabular data, spreadsheets and lists of records: columns + rows, optional row click. Rounded border, sticky muted headers, row hover, numeric alignment and empty state. Client-side column sorting (sortable defaults to true); optional pageSize (1–100) enables paging. Load @jini-ai/ui/interactive-ui.css in the renderer host.',
 };
 //# sourceMappingURL=data-table.manifest.js.map

package/dist/features/interactive-ui/table-data.d.ts

@@ -0,0 +1,25 @@
+interface TableData {
+    readonly columns: readonly {
+        readonly key: string;
+    }[];
+    readonly rows: readonly Record<string, unknown>[];
+}
+export interface TableSort {
+    readonly key: string;
+    readonly direction: 'ascending' | 'descending';
+}
+/** Infer numeric columns once for both providers; empty cells do not turn a numeric column into text.
+ * @complexity O(c × r), c columns and r rows; no per-cell rescans during rendering. */
+export declare function getNumericColumnKeys({ columns, rows }: TableData, _options?: {}): ReadonlySet<string>;
+/** Sort a copy while preserving source indexes for host actions; missing values stay last in both directions.
+ * @complexity O(r log r) time and O(r) space for r rows; the caller memoizes the result. */
+export declare function sortTableRows({ rows, sort, numericKeys }: {
+    readonly rows: TableData['rows'];
+    readonly sort: TableSort | null;
+    readonly numericKeys: ReadonlySet<string>;
+}, _options?: {}): {
+    row: Record<string, unknown>;
+    index: number;
+}[];
+export {};
+//# sourceMappingURL=table-data.d.ts.map

package/dist/features/interactive-ui/table-data.js

@@ -0,0 +1,36 @@
+function isNumericValue(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return typeof value === 'string' && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(value.trim())
+        && Number.isFinite(Number(value));
+}
+/** Infer numeric columns once for both providers; empty cells do not turn a numeric column into text.
+ * @complexity O(c × r), c columns and r rows; no per-cell rescans during rendering. */
+export function getNumericColumnKeys({ columns, rows }, _options = {}) {
+    return new Set(columns.filter(({ key }) => {
+        const values = rows.map((row) => row[key]).filter((value) => value !== null && value !== undefined && value !== '');
+        return values.length > 0 && values.every(isNumericValue);
+    }).map(({ key }) => key));
+}
+/** Sort a copy while preserving source indexes for host actions; missing values stay last in both directions.
+ * @complexity O(r log r) time and O(r) space for r rows; the caller memoizes the result. */
+export function sortTableRows({ rows, sort, numericKeys }, _options = {}) {
+    const indexed = rows.map((row, index) => ({ row, index }));
+    if (!sort)
+        return indexed;
+    const { key, direction } = sort;
+    const multiplier = direction === 'ascending' ? 1 : -1;
+    return indexed.sort((a, b) => {
+        const left = a.row[key];
+        const right = b.row[key];
+        const leftEmpty = left === null || left === undefined || left === '';
+        const rightEmpty = right === null || right === undefined || right === '';
+        if (leftEmpty || rightEmpty)
+            return Number(leftEmpty) - Number(rightEmpty);
+        const compared = numericKeys.has(key)
+            ? Number(left) - Number(right)
+            : String(left).localeCompare(String(right));
+        return compared * multiplier;
+    });
+}
+//# sourceMappingURL=table-data.js.map

package/dist/features/mcp-ui/sandbox-proxy-link-forwarder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module features/mcp-ui/sandbox-proxy-link-forwarder
+ *
+ * Page-script source the sandbox proxy (`sandbox-proxy.ts`) embeds so a View's plain `<a href>`
+ * opens in a new tab. Inside the proxy's frame a link is useless on its own: `AppFrame`'s hardcoded
+ * sandbox has neither `allow-popups` nor `allow-top-navigation`, so a same-tab link navigates the
+ * card's own frame away from the View and a `target="_blank"` link is silently blocked. The one
+ * channel a View has to open anything is the `ui/open-link` request, answered by the Host's
+ * `onOpenLink` — so every qualifying link click becomes that request instead.
+ *
+ * Window, bubble phase, and skipped once `defaultPrevented`: it runs after every listener the View
+ * itself registered, so a View that already handles its own link (calling `openLink` itself and
+ * cancelling the click) is not opened twice.
+ *
+ * The request id is a string the View's own JSON-RPC ids (numbers) never use, so the Host's reply
+ * cannot resolve one of the View's pending requests. `link.href` is the resolved URL when the
+ * proxy has a real base; under the opaque `data:` proxy a relative href stays as written and the
+ * Host decides how to resolve it.
+ *
+ * Not re-exported from the package (`index.ts` re-exports `sandbox-proxy.ts` only); the tests
+ * evaluate this exact source.
+ *
+ * Expects `host` (the embedding window) and `hostOrigin` in scope — the proxy script's own vars.
+ */
+export declare const PROXY_LINK_FORWARDER_JS = "var openLinkSeq = 0;\n  function forwardLinkClick(event) {\n    if (event.defaultPrevented || event.button !== 0) return;\n    var target = event.target;\n    var link = target && target.closest ? target.closest(\"a[href]\") : null;\n    if (!link || link.hasAttribute(\"download\")) return;\n    var href = link.getAttribute(\"href\");\n    if (!href || href.charAt(0) === \"#\" || /^\\s*javascript:/i.test(href)) return;\n    event.preventDefault();\n    openLinkSeq += 1;\n    host.postMessage(\n      { jsonrpc: \"2.0\", id: \"jini-proxy-open-link-\" + openLinkSeq, method: \"ui/open-link\", params: { url: link.href } },\n      hostOrigin\n    );\n  }";
+//# sourceMappingURL=sandbox-proxy-link-forwarder.d.ts.map

package/dist/features/mcp-ui/sandbox-proxy-link-forwarder.js

@@ -0,0 +1,40 @@
+/**
+ * @module features/mcp-ui/sandbox-proxy-link-forwarder
+ *
+ * Page-script source the sandbox proxy (`sandbox-proxy.ts`) embeds so a View's plain `<a href>`
+ * opens in a new tab. Inside the proxy's frame a link is useless on its own: `AppFrame`'s hardcoded
+ * sandbox has neither `allow-popups` nor `allow-top-navigation`, so a same-tab link navigates the
+ * card's own frame away from the View and a `target="_blank"` link is silently blocked. The one
+ * channel a View has to open anything is the `ui/open-link` request, answered by the Host's
+ * `onOpenLink` — so every qualifying link click becomes that request instead.
+ *
+ * Window, bubble phase, and skipped once `defaultPrevented`: it runs after every listener the View
+ * itself registered, so a View that already handles its own link (calling `openLink` itself and
+ * cancelling the click) is not opened twice.
+ *
+ * The request id is a string the View's own JSON-RPC ids (numbers) never use, so the Host's reply
+ * cannot resolve one of the View's pending requests. `link.href` is the resolved URL when the
+ * proxy has a real base; under the opaque `data:` proxy a relative href stays as written and the
+ * Host decides how to resolve it.
+ *
+ * Not re-exported from the package (`index.ts` re-exports `sandbox-proxy.ts` only); the tests
+ * evaluate this exact source.
+ *
+ * Expects `host` (the embedding window) and `hostOrigin` in scope — the proxy script's own vars.
+ */
+export const PROXY_LINK_FORWARDER_JS = `var openLinkSeq = 0;
+  function forwardLinkClick(event) {
+    if (event.defaultPrevented || event.button !== 0) return;
+    var target = event.target;
+    var link = target && target.closest ? target.closest("a[href]") : null;
+    if (!link || link.hasAttribute("download")) return;
+    var href = link.getAttribute("href");
+    if (!href || href.charAt(0) === "#" || /^\\s*javascript:/i.test(href)) return;
+    event.preventDefault();
+    openLinkSeq += 1;
+    host.postMessage(
+      { jsonrpc: "2.0", id: "jini-proxy-open-link-" + openLinkSeq, method: "ui/open-link", params: { url: link.href } },
+      hostOrigin
+    );
+  }`;
+//# sourceMappingURL=sandbox-proxy-link-forwarder.js.map

package/dist/features/mcp-ui/sandbox-proxy.d.ts

@@ -127,8 +127,12 @@
  * survives `document.open()` and would then apply to the guest HTML written in below, silently
  * breaking any UIResource whose HTML this package did not build. Surfaces built by
  * `surfaces/document.ts` already carry their own `SURFACE_CSP` meta tag for exactly that job.
+ *
+ * Once the guest HTML is written, the page also forwards the View's link clicks to the Host as
+ * `ui/open-link` (`sandbox-proxy-link-forwarder.ts`) — registered after `document.close()` because
+ * `document.open()` erases every listener registered before it.
  */
-export declare const SANDBOX_PROXY_HTML = "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>MCP-UI sandbox proxy</title>\n<style>html, body { margin: 0; padding: 0; width: 100%; height: 100%; }</style>\n</head>\n<body>\n<script>\n(function () {\n  \"use strict\";\n  var host = window.parent;\n  var hostOrigin = window.location.origin;\n  if (host === window) return;\n\n  function isFromHost(event) {\n    return event.source === host && event.origin === hostOrigin;\n  }\n\n  window.addEventListener(\"message\", function (event) {\n    if (!isFromHost(event)) return;\n    var data = event.data;\n    if (!data || typeof data !== \"object\") return;\n    if (data.method !== \"ui/notifications/sandbox-resource-ready\") return;\n    var html = data.params && data.params.html;\n    if (typeof html !== \"string\") return;\n    document.open();\n    document.write(html);\n    document.close();\n  });\n\n  host.postMessage({ method: \"ui/notifications/sandbox-proxy-ready\", params: {} }, hostOrigin);\n}());\n</script>\n</body>\n</html>";
+export declare const SANDBOX_PROXY_HTML = "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>MCP-UI sandbox proxy</title>\n<style>html, body { margin: 0; padding: 0; width: 100%; height: 100%; }</style>\n</head>\n<body>\n<script>\n(function () {\n  \"use strict\";\n  var host = window.parent;\n  var hostOrigin = window.location.origin;\n  if (host === window) return;\n\n  function isFromHost(event) {\n    return event.source === host && event.origin === hostOrigin;\n  }\n\n  var openLinkSeq = 0;\n  function forwardLinkClick(event) {\n    if (event.defaultPrevented || event.button !== 0) return;\n    var target = event.target;\n    var link = target && target.closest ? target.closest(\"a[href]\") : null;\n    if (!link || link.hasAttribute(\"download\")) return;\n    var href = link.getAttribute(\"href\");\n    if (!href || href.charAt(0) === \"#\" || /^\\s*javascript:/i.test(href)) return;\n    event.preventDefault();\n    openLinkSeq += 1;\n    host.postMessage(\n      { jsonrpc: \"2.0\", id: \"jini-proxy-open-link-\" + openLinkSeq, method: \"ui/open-link\", params: { url: link.href } },\n      hostOrigin\n    );\n  }\n\n  window.addEventListener(\"message\", function (event) {\n    if (!isFromHost(event)) return;\n    var data = event.data;\n    if (!data || typeof data !== \"object\") return;\n    if (data.method !== \"ui/notifications/sandbox-resource-ready\") return;\n    var html = data.params && data.params.html;\n    if (typeof html !== \"string\") return;\n    document.open();\n    document.write(html);\n    document.close();\n    window.addEventListener(\"click\", forwardLinkClick);\n  });\n\n  host.postMessage({ method: \"ui/notifications/sandbox-proxy-ready\", params: {} }, hostOrigin);\n}());\n</script>\n</body>\n</html>";
 /**
  * Same script as {@link SANDBOX_PROXY_HTML}, with one load-bearing difference: `hostOrigin` is the
  * caller-supplied `hostOrigin` argument, baked in as a literal, instead of read from

package/dist/features/mcp-ui/sandbox-proxy.js

@@ -109,6 +109,7 @@
  * hardcodes any particular host — a consumer's origin is discovered at runtime from the page's own
  * URL — and neither touches the single-hop `document.write` shape the section above depends on.
  */
+import { PROXY_LINK_FORWARDER_JS } from './sandbox-proxy-link-forwarder.js';
 /**
  * The sandbox proxy page's complete, self-contained source — see this module's own doc for the
  * protocol it implements and the security tradeoff serving it makes.
@@ -127,6 +128,10 @@
  * survives `document.open()` and would then apply to the guest HTML written in below, silently
  * breaking any UIResource whose HTML this package did not build. Surfaces built by
  * `surfaces/document.ts` already carry their own `SURFACE_CSP` meta tag for exactly that job.
+ *
+ * Once the guest HTML is written, the page also forwards the View's link clicks to the Host as
+ * `ui/open-link` (`sandbox-proxy-link-forwarder.ts`) — registered after `document.close()` because
+ * `document.open()` erases every listener registered before it.
  */
 export const SANDBOX_PROXY_HTML = `<!doctype html>
 <html>
@@ -147,6 +152,8 @@ export const SANDBOX_PROXY_HTML = `<!doctype html>
     return event.source === host && event.origin === hostOrigin;
   }
 
+  ${PROXY_LINK_FORWARDER_JS}
+
   window.addEventListener("message", function (event) {
     if (!isFromHost(event)) return;
     var data = event.data;
@@ -157,6 +164,7 @@ export const SANDBOX_PROXY_HTML = `<!doctype html>
     document.open();
     document.write(html);
     document.close();
+    window.addEventListener("click", forwardLinkClick);
   });
 
   host.postMessage({ method: "ui/notifications/sandbox-proxy-ready", params: {} }, hostOrigin);
@@ -220,6 +228,8 @@ export function buildIsolatedSandboxProxyHtml(hostOrigin) {
     return event.source === host && event.origin === hostOrigin;
   }
 
+  ${PROXY_LINK_FORWARDER_JS}
+
   window.addEventListener("message", function (event) {
     if (!isFromHost(event)) return;
     var data = event.data;
@@ -230,6 +240,7 @@ export function buildIsolatedSandboxProxyHtml(hostOrigin) {
     document.open();
     document.write(html);
     document.close();
+    window.addEventListener("click", forwardLinkClick);
   });
 
   host.postMessage({ method: "ui/notifications/sandbox-proxy-ready", params: {} }, hostOrigin);

package/dist/features/mcp-ui/surfaces/bridge.js

@@ -133,9 +133,13 @@ export function renderBridgeScript(spec) {
     return requestWhenReady("ui/open-link", { url: url });
   }
 
+  // Height only, never width: @mcp-ui/client's AppFrame writes a reported width onto the iframe as a
+  // fixed px style. A surface is fluid, so its scrollWidth is just the frame's width at that moment;
+  // reported while mounting in a hidden or narrow pane it froze the frame at min-content width for
+  // good (owner bug 2026-10-08: an ask-choice card stuck at 192px after a reload). Leaving width out
+  // keeps the frame at the host's width: 100%, and the ResizeObserver below re-reports height on resize.
   function reportSize() {
-    var root = document.documentElement;
-    notify("ui/notifications/size-changed", { width: root.scrollWidth, height: root.scrollHeight });
+    notify("ui/notifications/size-changed", { height: document.documentElement.scrollHeight });
   }
 
   window.addEventListener("message", function (event) {

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

@@ -2,6 +2,7 @@ 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';
+import { FetchQueryBinding } from './binding.react.js';
 const CacheContext = createContext(null);
 /** Isolated cache scope; no external provider or query-library singleton is needed. */
 export function FetchQueryProvider({ children, environment = browserFetchQueryEnvironment }) {
@@ -12,7 +13,7 @@ export function FetchQueryProvider({ children, environment = browserFetchQueryEn
         cache.activate();
         return () => cache.dispose();
     }, [cache]);
-    return _jsx(CacheContext.Provider, { value: cache, children: children });
+    return _jsx(CacheContext.Provider, { value: cache, children: _jsx(FetchQueryBinding, { adapter: adapter, children: children }) });
 }
 function useCache() {
     const cache = useContext(CacheContext);
@@ -119,4 +120,5 @@ export function useInvalidate() {
     const cache = useCache();
     return useCallback(({ key }) => cache.invalidate({ prefix: key }), [cache]);
 }
+const adapter = { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate };
 //# sourceMappingURL=adapter.react.js.map

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

@@ -0,0 +1,11 @@
+/** Optional TanStack translation layer. No library types escape the fetch-query contract. */
+import { type ReactNode } from 'react';
+import { type FetchQueryEnvironmentPort } from './cache.js';
+/** Provider-owned TanStack cache and binding, compatible with hooks from the default entry.
+ * @example <FetchQueryProvider><ResourceScreen /></FetchQueryProvider>
+ * @param props Children and optional host connectivity/focus port. */
+export declare function FetchQueryProvider({ children, environment }: {
+    children: ReactNode;
+    environment?: FetchQueryEnvironmentPort;
+}): import("react").JSX.Element;
+//# sourceMappingURL=adapter.tanstack.d.ts.map

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

@@ -0,0 +1,190 @@
+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, QueryClient, QueryClientProvider, useMutation, useQuery } from '@tanstack/react-query';
+import { DEFAULT_STALE_TIME, FetchQueryCache, IDLE_RETENTION, toQueryError } from './cache.js';
+import { browserFetchQueryEnvironment } from './environment.browser.js';
+import { resolveFetchQueryError, resolveFetchQueryStatus } from './adapter.react.js';
+import { FetchQueryBinding } from './binding.react.js';
+const ScopeContext = createContext(null);
+/** Match built-in defaults. Failed authorization/validation must surface immediately;
+ * automatic retries would hide the server's first useful error behind repeated requests. */
+function createScope({ environment }) {
+    return {
+        client: new QueryClient({ defaultOptions: {
+                queries: { staleTime: DEFAULT_STALE_TIME, retry: false, refetchOnWindowFocus: false, refetchOnReconnect: false, networkMode: 'always' },
+                mutations: { retry: false, networkMode: 'always' },
+            } }),
+        // Reuse the existing connectivity gate; TanStack's online/focus managers are global
+        // and cannot represent two providers with independent host environment ports.
+        gate: new FetchQueryCache({}, { environment }), environment, history: new WeakMap(),
+    };
+}
+/** Provider-owned TanStack cache and binding, compatible with hooks from the default entry.
+ * @example <FetchQueryProvider><ResourceScreen /></FetchQueryProvider>
+ * @param props Children and optional host connectivity/focus port. */
+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 scope = useMemo(() => createScope({ environment }), [environment]);
+    useEffect(() => {
+        scope.gate.activate();
+        let online = environment.isOnline();
+        const release = environment.subscribeOnline({ listener: next => {
+                const reconnect = next && !online;
+                online = next;
+                // An offline/online pair may be batched into one React render. Signal the cache
+                // directly rather than depending on a disabled -> enabled render to revalidate.
+                if (reconnect)
+                    void scope.client.refetchQueries({ predicate: query => query.isActive() && query.isStale() && query.state.fetchStatus !== 'fetching' });
+            } });
+        return () => { release(); scope.gate.dispose(); };
+    }, [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. */
+function useScope() {
+    const scope = useContext(ScopeContext);
+    if (!scope)
+        throw new Error('Fetch-query hooks require FetchQueryProvider');
+    return scope;
+}
+/** Observe only this provider's connectivity; paused reads do not claim network activity. */
+function useOnline({ environment }) {
+    const subscribe = useCallback((listener) => environment.subscribeOnline({ listener }), [environment]);
+    const snapshot = useCallback(() => environment.isOnline(), [environment]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}
+/** Preserve contract metadata across observers, without retaining evicted query objects. */
+function historyFor({ scope, query }) {
+    let history = scope.history.get(query);
+    if (!history) {
+        history = { replacement: 0, request: 0, error: null };
+        scope.history.set(query, history);
+    }
+    return history;
+}
+/** Replacement writes win over either outcome of an older transport, across all loaders
+ * and reactive reads. Weak keys follow TanStack's own query eviction lifecycle. */
+async function read({ scope, key, fetch }) {
+    const query = scope.client.getQueryCache().find({ queryKey: key, exact: true });
+    const history = historyFor({ scope, query });
+    const generation = history.replacement;
+    const request = ++history.request;
+    try {
+        const value = await scope.gate.runOnline({ run: fetch });
+        if (generation !== history.replacement)
+            return scope.client.getQueryData(key);
+        if (value === undefined)
+            throw new Error(`${JSON.stringify(key)} data is undefined`);
+        if (request === history.request)
+            history.error = null;
+        return value;
+    }
+    catch (error) {
+        if (generation !== history.replacement)
+            return scope.client.getQueryData(key);
+        // Earlier data remains useful, but a failed refresh is not a fresh cache hit.
+        // The next loader/mount must retry even when its staleTime would retain that data.
+        if (request === history.request) {
+            history.error = toQueryError(error);
+            query.invalidate();
+        }
+        throw error;
+    }
+}
+/** Match the built-in cache's idle retention. TanStack's default gcTime (5 min) would
+ * otherwise evict an unobserved entry before a longer staleTime says it is stale. */
+function gcTimeFor({ staleTime }) {
+    return Math.max(IDLE_RETENTION, staleTime);
+}
+/** Reactive read translated to the library-free contract, with explicit focus opt-in. */
+function useFetchQuery({ key, fetch }, { enabled = true, staleTime = DEFAULT_STALE_TIME, refetchOnWindowFocus = false } = {}) {
+    const scope = useScope();
+    const online = useOnline(scope);
+    const query = useQuery({ queryKey: key, queryFn: () => read({ scope, key, fetch }), enabled: enabled && online, staleTime, gcTime: gcTimeFor({ staleTime }) }, scope.client);
+    const { refetch: refresh } = query;
+    const refetch = useCallback(() => {
+        if (scope.environment.isOnline()) {
+            void refresh();
+            return;
+        }
+        // Reconnect may already have started a fetch (re-enabled observer or provider refetch);
+        // that request postdates this one, so join it instead of cancelling it into a duplicate.
+        void scope.gate.runOnline({ run: () => refresh({ cancelRefetch: false }) });
+    }, [scope, refresh]);
+    useEffect(() => {
+        if (!enabled || !refetchOnWindowFocus)
+            return;
+        return scope.environment.subscribeFocus({ listener: () => {
+                const cached = scope.client.getQueryCache().find({ queryKey: key, exact: true });
+                if (scope.environment.isOnline() && cached?.isStaleByTime(staleTime) && cached.state.fetchStatus !== 'fetching')
+                    refetch();
+            } });
+    }, [scope, JSON.stringify(key), enabled, staleTime, refetchOnWindowFocus, refetch]);
+    // TanStack clears an initial error when a retry starts. The contract keeps it until
+    // recovery, so a retry is never mistaken for evidence that the last failure is gone.
+    const cached = scope.client.getQueryCache().find({ queryKey: key, exact: true });
+    const history = historyFor({ scope, query: cached });
+    const hasData = query.data !== undefined;
+    return {
+        data: query.data,
+        status: resolveFetchQueryStatus({ disabled: !enabled, hasData, status: query.status }),
+        error: resolveFetchQueryError({ error: history.error ?? query.error, disabled: !enabled, hasData }),
+        isFetching: online && query.isFetching, refetch,
+    };
+}
+/** Preserve promise rejection for awaiting writes while also handling discarded promises. */
+function useFetchMutation({ run }, { invalidates } = {}) {
+    const scope = useScope();
+    const mutation = useMutation({
+        mutationFn: required => scope.gate.runOnline({ run: () => run(required) }),
+        onSuccess: () => {
+            // 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 ?? [])
+                void scope.client.invalidateQueries({ queryKey: key });
+        },
+    }, scope.client);
+    const { mutateAsync, reset } = mutation;
+    const mutate = useCallback((required) => {
+        const promise = mutateAsync(required);
+        // 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;
+    }, [mutateAsync]);
+    return { mutate, status: mutation.status, error: mutation.status === 'error' ? toQueryError(mutation.error) : null, reset };
+}
+/** 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 }), staleTime, gcTime: gcTimeFor({ staleTime }) };
+        return {
+            peek: () => scope.client.getQueryData(key),
+            load: () => scope.client.fetchQuery(options).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;
+                const query = scope.client.getQueryCache().find({ queryKey: key, exact: true });
+                return (query.promise ?? scope.client.getQueryData(key));
+            }),
+            replace: ({ value }) => {
+                const query = scope.client.getQueryCache().build(scope.client, options);
+                const history = historyFor({ scope, query });
+                history.replacement += 1;
+                history.error = null;
+                scope.client.setQueryData(key, value);
+            },
+        };
+    }, [scope, key, fetch, staleTime]);
+}
+/** Prefix invalidation also reaches child keys read by other mounted consumers. */
+function useInvalidate() {
+    const { client } = useScope();
+    return useCallback(({ key }) => { void client.invalidateQueries({ queryKey: key }); }, [client]);
+}
+const adapter = { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate };
+//# sourceMappingURL=adapter.tanstack.js.map

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

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import type { FetchQueryAdapter } from './types.js';
+/** Internal composition seam: hooks and imperative loaders always use the same provider.
+ * Keep the adapter fixed for this provider's lifetime to preserve React hook ordering. */
+export declare function FetchQueryBinding({ adapter, children }: {
+    adapter: FetchQueryAdapter;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Library-free read facade; the provider selects its implementation. */
+export declare const useFetchQuery: FetchQueryAdapter['useFetchQuery'];
+/** Library-free write facade, including safe discarded promises. */
+export declare const useFetchMutation: FetchQueryAdapter['useFetchMutation'];
+/** Prefix invalidator for the nearest provider's cache. */
+export declare const useInvalidate: FetchQueryAdapter['useInvalidate'];
+/** Promise loader using the same cache as reactive reads. */
+export declare const useCachedLoader: FetchQueryAdapter['useCachedLoader'];
+//# sourceMappingURL=binding.react.d.ts.map

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

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+const AdapterContext = createContext(null);
+/** Internal composition seam: hooks and imperative loaders always use the same provider.
+ * Keep the adapter fixed for this provider's lifetime to preserve React hook ordering. */
+export function FetchQueryBinding({ adapter, children }) {
+    return _jsx(AdapterContext.Provider, { value: adapter, children: children });
+}
+/** Resolve the nearest provider; fail before attempting an unscoped read or write. */
+function useAdapter() {
+    const adapter = useContext(AdapterContext);
+    if (!adapter)
+        throw new Error('Fetch-query hooks require FetchQueryProvider');
+    return adapter;
+}
+/** Library-free read facade; the provider selects its implementation. */
+export const useFetchQuery = (required, optional = {}) => useAdapter().useFetchQuery(required, optional);
+/** Library-free write facade, including safe discarded promises. */
+export const useFetchMutation = (required, optional = {}) => useAdapter().useFetchMutation(required, optional);
+/** Prefix invalidator for the nearest provider's cache. */
+export const useInvalidate = () => useAdapter().useInvalidate();
+/** Promise loader using the same cache as reactive reads. */
+export const useCachedLoader = (required, optional = {}) => useAdapter().useCachedLoader(required, optional);
+//# sourceMappingURL=binding.react.js.map

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

@@ -9,6 +9,8 @@ import type { QueryKey } from './types.js';
  * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
  */
 export declare const DEFAULT_STALE_TIME = 10000;
+/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
+export declare const IDLE_RETENTION: number;
 export interface QueryCacheSchedulerPort {
     schedule(required: {
         callback: () => void;

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

@@ -7,7 +7,8 @@
  * 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;
+/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
+export const IDLE_RETENTION = 5 * 60_000;
 const browserScheduler = {
     schedule: ({ callback, delayMs }) => setTimeout(callback, delayMs),
     cancel: ({ handle }) => clearTimeout(handle),

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

@@ -1,4 +1,5 @@
-export { FetchQueryProvider, useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './adapter.react.js';
+export { FetchQueryProvider } from './adapter.react.js';
+export { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './binding.react.js';
 export type { FetchQueryEnvironmentPort } from './cache.js';
 export type { QueryKey, QueryStatus, QueryResult, FetchQueryOptions, MutationStatus, MutationResult, FetchMutationOptions, CachedLoaderOptions, CachedLoader, FetchQueryAdapter } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1,3 @@
-export { FetchQueryProvider, useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './adapter.react.js';
+export { FetchQueryProvider } from './adapter.react.js';
+export { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './binding.react.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,6 @@
+/** Optional adapter entry. Importing the default entry never loads TanStack. */
+export { FetchQueryProvider } from './adapter.tanstack.js';
+export { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './binding.react.js';
+export type { FetchQueryEnvironmentPort } from './cache.js';
+export type { QueryKey, QueryStatus, QueryResult, FetchQueryOptions, MutationStatus, MutationResult, FetchMutationOptions, CachedLoaderOptions, CachedLoader, FetchQueryAdapter } from './types.js';
+//# sourceMappingURL=tanstack.d.ts.map

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

@@ -0,0 +1,4 @@
+/** Optional adapter entry. Importing the default entry never loads TanStack. */
+export { FetchQueryProvider } from './adapter.tanstack.js';
+export { useFetchQuery, useFetchMutation, useCachedLoader, useInvalidate } from './binding.react.js';
+//# sourceMappingURL=tanstack.js.map

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

@@ -9,6 +9,8 @@
  * key also refreshes its derived child keys. Exact-key equality would compile while quietly
  * breaking that guarantee; avoid a shared prefix for resources that merely sound related,
  * or writes will fan out unnecessary refetches.
+ * Stay primitive-only: the built-in cache matches each part with === while TanStack deep-matches,
+ * so an object part would invalidate under one adapter and silently not under the other.
  */
 export type QueryKey = readonly (string | number)[];
 export type QueryStatus = "loading" | "success" | "error";