@notis_ai/cli 0.2.0-beta.154.1 → 0.2.0-beta.156.1

package/template/app/page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { getDocumentPreview, useDocuments, useNotis } from '@notis/sdk';
+import { getDocumentPreview, useDocuments, useNotis, Skeleton, ViewSkeleton } from '@notis/sdk';
 import { Badge } from '@/components/ui/badge';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 
@@ -8,7 +8,7 @@ export default function HomePage() {
   const { app, ready } = useNotis();
   // Documents come back normalized: plain property values, camelCase fields,
   // and typed content (contentMarkdown / contentBlocknote / plainText).
-  const { documents, loading } = useDocuments('items', { pageSize: 25 });
+  const { documents, loading, hasData, error, refetch } = useDocuments('items', { pageSize: 25 });
 
   return (
     <main className="notis-app-shell space-y-6">
@@ -16,9 +16,9 @@ export default function HomePage() {
         <CardHeader className="space-y-3">
           <Badge variant="secondary" className="w-fit">Installed app</Badge>
           <div className="space-y-2">
-            <CardTitle>{ready ? app?.name : 'Loading...'}</CardTitle>
+            <CardTitle>{ready ? app?.name : <Skeleton style={{ width: 160 }} />}</CardTitle>
             <CardDescription>
-              {ready ? app?.description : 'Loading app metadata...'}
+              {ready ? app?.description : <Skeleton style={{ width: 240 }} />}
             </CardDescription>
           </div>
         </CardHeader>
@@ -30,11 +30,12 @@ export default function HomePage() {
           <CardDescription>Use shadcn surfaces and portal tokens so the app feels native inside Notis.</CardDescription>
         </CardHeader>
         <CardContent>
+          {error && <p role="alert" className="mb-3 text-sm text-destructive">{error.message} <button onClick={refetch}>Retry</button></p>}
           {loading ? (
-            <p className="text-sm text-muted-foreground">Loading...</p>
-          ) : documents.length === 0 ? (
+            <ViewSkeleton variant="table" rows={4} />
+          ) : !hasData ? null : documents.length === 0 ? (
             <div className="rounded-xl border border-dashed border-border px-4 py-10 text-center text-sm text-muted-foreground">
-              No items yet. Deploy the app and create some.
+              No items yet. Create your first item.
             </div>
           ) : (
             <div className="space-y-3">

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import React, {
+  useEffect,
   useMemo,
+  useRef,
   useState,
   type CSSProperties,
   type ReactElement,
@@ -29,7 +31,7 @@ export interface MultiSelectActionBarProps {
 
 const containerBaseStyle: CSSProperties = {
   position: 'fixed',
-  bottom: '1rem',
+  bottom: 'calc(var(--notis-viewport-bottom, 0px) + max(1rem, var(--notis-safe-area-bottom, env(safe-area-inset-bottom, 0px))))',
   left: '50%',
   transform: 'translateX(-50%)',
   zIndex: 60,
@@ -46,6 +48,8 @@ const containerBaseStyle: CSSProperties = {
   pointerEvents: 'auto',
   fontSize: '13px',
   lineHeight: 1.2,
+  width: 'max-content',
+  maxWidth: 'calc(100% - 2rem)',
 };
 
 const countStyle: CSSProperties = {
@@ -115,6 +119,26 @@ export function MultiSelectActionBar({
   shortcutsEnabled = true,
   shortcutScope = 'collection',
 }: MultiSelectActionBarProps): ReactElement | null {
+  const barRef = useRef<HTMLDivElement>(null);
+  const visible = selectedCount > 0;
+  useEffect(() => {
+    const bar = barRef.current;
+    if (!visible || !bar) return;
+    // Also reaches a Portal launcher when an app renders inside a shadow root.
+    const root = document.documentElement;
+    const property = '--notis-bulk-actions-height';
+    const previous = root.style.getPropertyValue(property);
+    const update = () => root.style.setProperty(property, `${bar.getBoundingClientRect().height + 12}px`);
+    update();
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
+    observer?.observe(bar);
+    return () => {
+      observer?.disconnect();
+      if (previous) root.style.setProperty(property, previous);
+      else root.style.removeProperty(property);
+    };
+  }, [visible]);
+
   const actionShortcuts = useMemo<ShortcutDefinition[]>(() => {
     return actions.flatMap((action): ShortcutDefinition[] => {
         if (!action.shortcut || action.disabled || action.pending) return [];
@@ -147,16 +171,33 @@ export function MultiSelectActionBar({
 
   return (
     <div
+      ref={barRef}
+      data-notis-bulk-actions
       role="toolbar"
       aria-label={`Bulk actions for ${selectedCount} selected ${countWord}`}
       className={className}
       style={composedStyle}
     >
-      <span style={countStyle}>{countLabel}</span>
-      {actions.length > 0 ? <span aria-hidden style={dividerStyle} /> : null}
-      {actions.map((action) => (
-        <ActionButton key={action.id} action={action} />
-      ))}
+      <style>{`
+        [data-notis-bulk-action-icon][data-has-shortcut] { display: none !important; }
+        @media (max-width: 639px) {
+          [data-notis-bulk-actions] { flex-wrap: wrap; width: calc(100% - 2rem) !important; }
+          [data-notis-bulk-count] { flex-basis: 100%; padding: 0.375rem 0.5rem !important; font-size: 14px !important; }
+          [data-notis-bulk-divider] { display: none; }
+          [data-notis-bulk-action-list] { width: 100%; }
+          [data-notis-bulk-actions] button { min-height: 48px; font-size: 16px !important; }
+          [data-notis-bulk-actions] kbd { display: none !important; }
+          [data-notis-bulk-action-icon][data-has-shortcut] { display: inline-flex !important; }
+        }
+        @media (hover: none) { [data-notis-bulk-actions] kbd { display: none !important; } }
+      `}</style>
+      <span data-notis-bulk-count style={countStyle}>{countLabel}</span>
+      {actions.length > 0 ? <span data-notis-bulk-divider aria-hidden style={dividerStyle} /> : null}
+      <div data-notis-bulk-action-list style={{ display: 'flex', minWidth: 0, overflowX: 'auto', overscrollBehaviorX: 'contain', gap: '0.25rem' }}>
+        {actions.map((action) => (
+          <ActionButton key={action.id} action={action} />
+        ))}
+      </div>
     </div>
   );
 }
@@ -192,8 +233,8 @@ function ActionButton({ action }: { action: MultiSelectAction }) {
       onBlur={() => setHover(false)}
       style={buttonStyle}
     >
-      {!action.shortcut && action.icon ? (
-        <span aria-hidden style={iconSlotStyle}>{action.icon}</span>
+      {action.icon ? (
+        <span data-notis-bulk-action-icon data-has-shortcut={action.shortcut ? '' : undefined} aria-hidden style={iconSlotStyle}>{action.icon}</span>
       ) : null}
       {display ? <kbd aria-hidden style={keycapStyle}>{display}</kbd> : null}
       <span>{action.pending ? `${action.label}…` : action.label}</span>

package/template/packages/sdk/src/components/Skeleton.tsx

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+
+/** Content-shaped placeholder. Never use it to replace a successful cached result. */
+export function Skeleton({ className, style }: { className?: string; style?: CSSProperties }) {
+  return <span aria-hidden="true" className={className} style={{ display: 'block', height: 16,
+    // Apps may define --muted as HSL channels or a complete CSS color. A
+    // neutral default remains visible with either token format and no theme.
+    borderRadius: 6, background: 'rgba(128,128,128,.18)', ...style }} />;
+}
+
+export function ViewSkeleton({ variant = 'table', rows = 5 }: {
+  variant?: 'table' | 'cards' | 'graph' | 'detail'; rows?: number;
+}) {
+  return <div role="status" aria-label="Loading content" aria-busy="true" data-notis-content-skeleton
+    style={{ width: '100%', display: 'grid', gap: 16, padding: 24 }}>
+    <Skeleton style={{ width: '32%', height: 28 }} />
+    {variant === 'graph' ? <Skeleton style={{ height: 420 }} /> :
+      <div style={{ display: 'grid', gap: 12, gridTemplateColumns: variant === 'cards' ? 'repeat(auto-fit,minmax(180px,1fr))' : '1fr' }}>
+        {Array.from({ length: rows }, (_, index) => <Skeleton key={index}
+          style={{ height: variant === 'cards' ? 112 : variant === 'detail' ? 20 : 44,
+            width: variant === 'detail' && index === rows - 1 ? '65%' : '100%' }} />)}
+      </div>}
+  </div>;
+}

package/template/packages/sdk/src/hooks/useCloudComputer.ts

@@ -1,6 +1,7 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useRef } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import type { CloudComputerFacts } from '../runtime';
 
@@ -11,6 +12,7 @@ export interface UseCloudComputerResult {
    */
   facts: CloudComputerFacts | null;
   loading: boolean;
+  isFetching: boolean;
   error: Error | null;
   /** Re-read the facts. The platform caches them for a few minutes. */
   refresh: () => Promise<void>;
@@ -47,51 +49,16 @@ const UNAVAILABLE: CloudComputerFacts = {
  */
 export function useCloudComputer(): UseCloudComputerResult {
   const runtime = useNotisRuntime();
-  const [facts, setFacts] = useState<CloudComputerFacts | null>(null);
-  // True from the first committed render: the initial read is already queued
-  // in an effect, and `{ loading: false, facts: null }` would flash a
-  // consumer's fallback branch before the answer arrives.
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const mounted = useRef(true);
-
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-    };
-  }, []);
-
-  const read = useCallback(async (options?: { refresh?: boolean }) => {
-    if (!runtime?.cloudComputerFacts) {
-      setFacts(UNAVAILABLE);
-      setLoading(false);
-      return;
-    }
-
-    setLoading(true);
-    setError(null);
-    try {
-      const next = await runtime.cloudComputerFacts(options);
-      if (mounted.current) setFacts(next);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      if (mounted.current) {
-        setError(e);
-        // A refused or failed read is the same product state as a host that
-        // cannot answer: the app shows its fallback instead of an error.
-        setFacts(UNAVAILABLE);
-      }
-    } finally {
-      if (mounted.current) setLoading(false);
-    }
-  }, [runtime]);
-
-  useEffect(() => {
-    void read();
-  }, [read]);
-
-  const refresh = useCallback(() => read({ refresh: true }), [read]);
-
-  return { facts, loading, error, refresh };
+  const explicitRefresh = useRef(false);
+  const query = useQuery<CloudComputerFacts>(['cloud-computer-facts'], async () => {
+    const refresh = explicitRefresh.current;
+    explicitRefresh.current = false;
+    return runtime?.cloudComputerFacts ? runtime.cloudComputerFacts(refresh ? { refresh: true } : undefined) : UNAVAILABLE;
+  }, { readOnly: true });
+  const refresh = useCallback(async () => {
+    explicitRefresh.current = true;
+    await query.refetch();
+  }, [query.refetch]);
+  return { facts: query.data ?? (query.error ? UNAVAILABLE : null), loading: query.loading,
+    isFetching: query.isFetching, error: query.error, refresh };
 }

package/template/packages/sdk/src/hooks/useDatabaseSchema.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDatabaseProperty, optionalString } from '../documents';
 import type { DatabaseProperty } from '../runtime';
@@ -22,6 +22,8 @@ export interface UseDatabaseSchemaResult {
   description: string | null;
   properties: DatabaseProperty[];
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -29,57 +31,19 @@ export interface UseDatabaseSchemaResult {
 /** Fetch a database's schema (normalized properties + metadata). */
 export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
   const runtime = useNotisRuntime();
-  const [name, setName] = useState<string | null>(null);
-  const [description, setDescription] = useState<string | null>(null);
-  const [properties, setProperties] = useState<DatabaseProperty[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
-        database_slug: databaseSlug,
-      })
-      .then((result) => {
-        if (cancelled) return;
-        const message = result.error ?? result.message;
-        if (!result.database && message) {
-          throw new Error(message);
-        }
-        setName(optionalString(result.database?.name));
-        setDescription(optionalString(result.database?.description));
-        const rawProperties = result.database?.schema?.properties ?? [];
-        setProperties(
-          rawProperties
-            .map(normalizeDatabaseProperty)
-            .filter((property): property is DatabaseProperty => Boolean(property)),
-        );
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
+  const query = useQuery(['database-schema', databaseSlug], async () => {
+    const result = await runtime!.callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
+      database_slug: databaseSlug,
+    }, { dedupe: true, readOnly: true });
+    if (!result.database) throw new Error(result.error || result.message || 'Database not found');
+    return {
+      name: optionalString(result.database.name),
+      description: optionalString(result.database.description),
+      properties: (result.database.schema?.properties ?? []).map(normalizeDatabaseProperty)
+        .filter((property): property is DatabaseProperty => Boolean(property)),
     };
-  }, [runtime, databaseSlug, fetchKey]);
-
-  return { name, description, properties, loading, error, refetch };
+  }, { readOnly: true });
+  return { ...query, name: query.data?.name ?? null, description: query.data?.description ?? null,
+    properties: query.data?.properties ?? EMPTY_PROPERTIES };
 }
+const EMPTY_PROPERTIES: DatabaseProperty[] = [];

package/template/packages/sdk/src/hooks/useDatabaseSubscription.ts

@@ -36,7 +36,7 @@ export function useDatabaseSubscription(
 ): UseDatabaseSubscriptionResult {
   const runtime = useNotisRuntime();
   const { subscribe = true, ...documentOptions } = options;
-  const { documents, loading, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const { documents, loading, isFetching, hasData, error, refetch } = useDocuments(databaseSlug, documentOptions);
   const [live, setLive] = useState(false);
 
   const refetchRef = useRef(refetch);
@@ -72,5 +72,5 @@ export function useDatabaseSubscription(
     };
   }, [runtime, databaseSlug, enabled]);
 
-  return { documents, rows: documents, loading, error, refetch, live };
+  return { documents, rows: documents, loading, isFetching, hasData, error, refetch, live };
 }

package/template/packages/sdk/src/hooks/useDocument.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDocumentRecord } from '../documents';
 import type { DocumentRecord } from '../runtime';
@@ -19,6 +19,8 @@ export interface UseDocumentOptions {
 export interface UseDocumentResult {
   document: DocumentRecord | null;
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -29,50 +31,13 @@ export function useDocument(
   options: UseDocumentOptions = {},
 ): UseDocumentResult {
   const runtime = useNotisRuntime();
-  const [document, setDocument] = useState<DocumentRecord | null>(null);
-  const [loading, setLoading] = useState(Boolean(documentId));
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const enabled = options.enabled !== false && Boolean(documentId);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime || !enabled || !documentId) {
-      setDocument(null);
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
-        document_id: documentId,
-      })
-      .then((result) => {
-        if (cancelled) return;
-        if (!result.document) {
-          throw new Error(result.error ?? result.message ?? 'Document not found');
-        }
-        setDocument(normalizeDocumentRecord(result.document));
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime, documentId, enabled, fetchKey]);
-
-  return { document, loading, error, refetch };
+  const query = useQuery<DocumentRecord>(['document', documentId ?? null], async () => {
+    if (!runtime || !documentId) throw new Error('Document not found');
+    const result = await runtime.callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
+      document_id: documentId,
+    }, { dedupe: true, readOnly: true });
+    if (!result.document) throw new Error(result.error ?? result.message ?? 'Document not found');
+    return normalizeDocumentRecord(result.document);
+  }, { readOnly: true, enabled: options.enabled !== false && Boolean(documentId) });
+  return { document: query.data ?? null, loading: query.loading, isFetching: query.isFetching, hasData: query.hasData, error: query.error, refetch: query.refetch };
 }

package/template/packages/sdk/src/hooks/useDocuments.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDocumentRecord } from '../documents';
 import type { DocumentRecord, QueryFilter } from '../runtime';
@@ -25,6 +25,8 @@ export interface UseDocumentsOptions {
 export interface UseDocumentsResult {
   documents: DocumentRecord[];
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -44,78 +46,36 @@ export function useDocuments(
   options: UseDocumentsOptions = {},
 ): UseDocumentsResult {
   const runtime = useNotisRuntime();
-  const [documents, setDocuments] = useState<DocumentRecord[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const enabled = options.enabled !== false;
-  const filterKey = JSON.stringify(options.filter ?? null);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime || !enabled) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    const filter = filterKey === 'null' ? null : (JSON.parse(filterKey) as QueryFilter);
-
-    const fetchDocuments = async (): Promise<unknown[]> => {
+  const query = useQuery<DocumentRecord[]>(
+    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll)],
+    async () => {
+      if (!runtime) throw new Error('Notis runtime not available');
       const allDocuments: unknown[] = [];
       let offset = options.offset ?? 0;
-
       while (true) {
         const result = await runtime.callTool<QueryDatabaseResult>('LOCAL_NOTIS_DATABASE_QUERY', {
           database_slug: databaseSlug,
           query: {
-            ...(filter ?? {}),
+            ...(options.filter ?? {}),
             ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
           },
           ...(offset > 0 ? { offset } : {}),
-        });
+        }, { dedupe: true, readOnly: true });
         const message = result.error ?? result.message;
-        if (!result.documents && message) {
-          throw new Error(message);
-        }
+        if (!result.documents && message) throw new Error(message);
         allDocuments.push(...(result.documents ?? []));
-        if (!options.fetchAll || !result.has_more) return allDocuments;
-
+        if (!options.fetchAll || !result.has_more) break;
         const nextOffset = result.next_offset;
         if (typeof nextOffset !== 'number' || nextOffset <= offset) {
           throw new Error('Database query returned an invalid pagination offset');
         }
         offset = nextOffset;
       }
-    };
-
-    fetchDocuments()
-      .then((result) => {
-        if (cancelled) return;
-        setDocuments(
-          result
-            .map(normalizeDocumentRecord)
-            .filter((document) => document.id),
-        );
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime, databaseSlug, enabled, fetchKey, filterKey, options.fetchAll, options.offset, options.pageSize]);
-
-  return { documents, loading, error, refetch };
+      return allDocuments.map(normalizeDocumentRecord).filter((document) => document.id);
+    },
+    { readOnly: true, enabled: options.enabled },
+  );
+  return { documents: query.data ?? EMPTY_DOCUMENTS, loading: query.loading, isFetching: query.isFetching, hasData: query.hasData, error: query.error, refetch: query.refetch };
 }
+
+const EMPTY_DOCUMENTS: DocumentRecord[] = [];

package/template/packages/sdk/src/hooks/useQuery.ts

@@ -0,0 +1,71 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useNotisRuntime } from '../provider';
+import { createQueryClient, queryKey } from '../queryCache';
+
+export interface UseQueryOptions {
+  /** Required acknowledgement: only idempotent reads may run on mount or prefetch. */
+  readOnly: true;
+  enabled?: boolean;
+  staleTimeMs?: number;
+}
+
+export interface UseQueryResult<T> {
+  data: T | undefined;
+  hasData: boolean;
+  loading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+/** Cached read callback; scope and lifetime are provided by the host, never by app globals. */
+export function useQuery<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): UseQueryResult<T> {
+  const runtime = useNotisRuntime();
+  // Older hosts deliberately get a hook-local cache: no cross-runtime/account reuse.
+  const fallback = useMemo(() => createQueryClient(), [runtime]);
+  const client = runtime?.queryClient ?? fallback;
+  const cacheKey = queryKey(key);
+  const enabled = Boolean(runtime) && options.enabled !== false && options.readOnly === true;
+  const readRef = useRef(read);
+  useLayoutEffect(() => { readRef.current = read; });
+  const subscribe = useCallback((listener: () => void) => enabled ? client.subscribe(cacheKey, listener) : () => {}, [cacheKey, client, enabled]);
+  const snapshot = useSyncExternalStore(subscribe, () => client.getSnapshot<T>(cacheKey), () => client.getSnapshot<T>(cacheKey));
+  const fetch = useCallback(() => {
+    const capturedRead = readRef.current;
+    return client.fetch(cacheKey, capturedRead, { staleTimeMs: options.staleTimeMs });
+  }, [cacheKey, client, options.staleTimeMs]);
+  useEffect(() => {
+    if (!enabled) return;
+    void fetch().catch(() => {}); // Error belongs to the snapshot; no unhandled rejection.
+  }, [enabled, fetch, snapshot.invalidation]);
+  const refetch = useCallback(async () => {
+    if (!enabled) return;
+    client.invalidate(cacheKey);
+    await fetch().catch(() => {});
+  }, [cacheKey, client, enabled, fetch]);
+  return {
+    data: enabled ? snapshot.data : undefined,
+    hasData: enabled && snapshot.hasData,
+    loading: enabled && !snapshot.hasData && !snapshot.error,
+    isFetching: enabled && snapshot.isFetching,
+    error: enabled ? snapshot.error : null,
+    refetch,
+  };
+}
+
+/** Opt-in preparation for small, known read queries. Never use for writes or full-database crawls. */
+export function useQueryClient(): {
+  invalidate(key?: readonly unknown[]): void;
+  prefetch<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): Promise<T | undefined>;
+} {
+  const runtime = useNotisRuntime();
+  return useMemo(() => ({
+    invalidate: (key?: readonly unknown[]) => runtime?.queryClient?.invalidate(key ? queryKey(key) : undefined),
+    prefetch: <T,>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions) => {
+      if (!runtime?.queryClient || options.enabled === false || options.readOnly !== true) return Promise.resolve(undefined);
+      return runtime.queryClient.prefetch(queryKey(key), read, { staleTimeMs: options.staleTimeMs });
+    },
+  }), [runtime]);
+}

package/template/packages/sdk/src/hooks/useToolQuery.ts

@@ -0,0 +1,12 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryOptions } from './useQuery';
+
+/** An explicitly identified read-only tool, cached by tool name and exact arguments. */
+export function useToolQuery<T = unknown>(name: string, args: Record<string, unknown> = {}, options: UseQueryOptions) {
+  const runtime = useNotisRuntime();
+  return useQuery<T>(['tool', name, args], () => runtime!.callTool<T>(name, args, {
+    readOnly: true, dedupe: true,
+  }), options);
+}