@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.161.1

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

@@ -0,0 +1,49 @@
+'use client';
+
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { normalizeDatabaseProperty, optionalString } from '../documents';
+import type { DatabaseProperty } from '../runtime';
+
+interface GetDatabaseResult {
+  database?: {
+    name?: string;
+    description?: string | null;
+    schema?: {
+      properties?: unknown[];
+    };
+  };
+  message?: string;
+  error?: string;
+}
+
+export interface UseDatabaseSchemaResult {
+  name: string | null;
+  description: string | null;
+  properties: DatabaseProperty[];
+  loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a database's schema (normalized properties + metadata). */
+export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
+  const runtime = useNotisRuntime();
+  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)),
+    };
+  }, { 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

@@ -0,0 +1,76 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useDocuments, type UseDocumentsOptions, type UseDocumentsResult } from './useDocuments';
+import type { DocumentRecord } from '../runtime';
+
+export interface UseDatabaseSubscriptionOptions extends UseDocumentsOptions {
+  /** Set to false to keep the query but skip the change feed. */
+  subscribe?: boolean;
+}
+
+export interface UseDatabaseSubscriptionResult extends UseDocumentsResult {
+  /** Alias of `documents`, for views that think in rows. */
+  rows: DocumentRecord[];
+  /** True while a live change feed is attached to this database. */
+  live: boolean;
+}
+
+/**
+ * Query a Notis database and keep it fresh without polling.
+ *
+ * ```tsx
+ * const { rows, live, refetch } = useDatabaseSubscription('workspaces');
+ * ```
+ *
+ * A change on the database wakes the hook, which then refetches through the
+ * usual `LOCAL_NOTIS_DATABASE_QUERY` path — the change feed is a signal only
+ * and never carries row data. Hosts without a change feed (the dev harness,
+ * the screenshot stub, the vite preview) still return rows; `live` is false
+ * there and the app should keep offering its manual refresh.
+ */
+export function useDatabaseSubscription(
+  databaseSlug: string,
+  options: UseDatabaseSubscriptionOptions = {},
+): UseDatabaseSubscriptionResult {
+  const runtime = useNotisRuntime();
+  const { subscribe = true, ...documentOptions } = options;
+  const { documents, loading, isFetching, hasData, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const [live, setLive] = useState(false);
+
+  const refetchRef = useRef(refetch);
+  useEffect(() => {
+    refetchRef.current = refetch;
+  }, [refetch]);
+
+  const enabled = options.enabled !== false && subscribe;
+
+  useEffect(() => {
+    if (!runtime?.subscribeDatabase || !enabled || !databaseSlug) {
+      setLive(false);
+      return;
+    }
+
+    let cancelled = false;
+    const unsubscribe = runtime.subscribeDatabase(
+      databaseSlug,
+      () => {
+        refetchRef.current();
+      },
+      {
+        onStatusChange: (isLive) => {
+          if (!cancelled) setLive(isLive);
+        },
+      },
+    );
+
+    return () => {
+      cancelled = true;
+      setLive(false);
+      unsubscribe?.();
+    };
+  }, [runtime, databaseSlug, enabled]);
+
+  return { documents, rows: documents, loading, isFetching, hasData, error, refetch, live };
+}

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

@@ -0,0 +1,43 @@
+'use client';
+
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+interface GetDocumentResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentOptions {
+  enabled?: boolean;
+}
+
+export interface UseDocumentResult {
+  document: DocumentRecord | null;
+  loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a single document (with content) by id, normalized. */
+export function useDocument(
+  documentId: string | null | undefined,
+  options: UseDocumentOptions = {},
+): UseDocumentResult {
+  const runtime = useNotisRuntime();
+  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

@@ -0,0 +1,84 @@
+'use client';
+
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord, QueryFilter } from '../runtime';
+
+interface QueryDatabaseResult {
+  documents?: unknown[];
+  has_more?: boolean;
+  next_offset?: number | null;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentsOptions {
+  filter?: QueryFilter;
+  pageSize?: number;
+  offset?: number;
+  /** Fetch every page, starting at offset, instead of returning only one page. */
+  fetchAll?: boolean;
+  /** App-view lists can omit bodies until opening/searching a document. Default: true. */
+  includeContent?: boolean;
+  enabled?: boolean;
+}
+
+export interface UseDocumentsResult {
+  documents: DocumentRecord[];
+  loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Query a Notis database and get normalized `DocumentRecord`s.
+ *
+ * ```tsx
+ * const { documents, loading, refetch } = useDocuments('notes', {
+ *   filter: { filters: [{ property: 'Folder', operator: 'contains', type: 'relation', value: folderId }] },
+ *   pageSize: 250,
+ * });
+ * ```
+ */
+export function useDocuments(
+  databaseSlug: string,
+  options: UseDocumentsOptions = {},
+): UseDocumentsResult {
+  const runtime = useNotisRuntime();
+  const query = useQuery<DocumentRecord[]>(
+    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll), options.includeContent !== false],
+    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: {
+            ...(options.filter ?? {}),
+            ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
+            ...(options.includeContent === false ? { include_content: false } : {}),
+          },
+          ...(offset > 0 ? { offset } : {}),
+        }, { dedupe: true, readOnly: true });
+        const message = result.error ?? result.message;
+        if (!result.documents && message) throw new Error(message);
+        allDocuments.push(...(result.documents ?? []));
+        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;
+      }
+      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/useHandover.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { HandoverPayload, HandoverResult } from '../runtime';
+
+export interface UseHandoverResult {
+  /** Hand the work over. Rejects when the host has no manager chat. */
+  handover: (payload: HandoverPayload) => Promise<HandoverResult>;
+  /** True while the manager chat is being prepared. */
+  pending: boolean;
+  error: Error | null;
+  /**
+   * False when the host cannot hand work over (dev harness, vite preview).
+   * Render the app's own fallback — a copyable prompt, say — when it is false.
+   */
+  available: boolean;
+}
+
+/**
+ * Hand a piece of work from app code to the Notis manager chat.
+ *
+ * An app displays work; the manager runs it. `handover` puts the message in
+ * the chat surface that already owns streaming progress, billing, cancellation
+ * and the transcript, and the app watches its own databases for the result.
+ *
+ * ```tsx
+ * const { handover, pending, available } = useHandover();
+ *
+ * return available ? (
+ *   <Button
+ *     disabled={pending}
+ *     onClick={() => { void handover({ prompt: 'Create a workspace on notis to ...' }); }}
+ *   >
+ *     Send to Notis
+ *   </Button>
+ * ) : (
+ *   <CopyablePrompt prompt="Create a workspace on notis to ..." />
+ * );
+ * ```
+ *
+ * Omit `prompt` to open a context-only composer, for example when a visible
+ * feedback button should let the user write in their own words.
+ *
+ * Pass `skill` to bind the work to a skill declared in `notis.config.ts`; the
+ * host rejects a key the app does not declare. `autoSend` is accepted for
+ * forward compatibility; today's hosts always return `drafted` and let the
+ * user press send.
+ */
+export function useHandover(): UseHandoverResult {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const handover = useCallback(
+    async (payload: HandoverPayload): Promise<HandoverResult> => {
+      if (!runtime?.handover) {
+        throw new Error('This Notis host cannot hand work to the manager chat.');
+      }
+
+      setPending(true);
+      setError(null);
+
+      try {
+        return await runtime.handover(payload);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [runtime],
+  );
+
+  return { handover, pending, error, available: Boolean(runtime?.handover) };
+}

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

@@ -0,0 +1,79 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import type {
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from 'react';
+
+const LONG_PRESS_MS = 500;
+const MOVE_TOLERANCE_PX = 10;
+const INTERACTIVE_SELECTOR = [
+  'button',
+  'a[href]',
+  'input',
+  'textarea',
+  'select',
+  'summary',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[role="button"]',
+  '[role="link"]',
+  '[role="menuitem"]',
+  '[role="option"]',
+  '[role="switch"]',
+  '[role="tab"]',
+].join(', ');
+
+/** Adds a touch-only long-press entry point without rendering idle checkboxes. */
+export function useLongPressSelection(onSelect: (id: string) => void) {
+  const onSelectRef = useRef(onSelect);
+  onSelectRef.current = onSelect;
+  const timerRef = useRef<number | null>(null);
+  const startRef = useRef<{ x: number; y: number } | null>(null);
+  const suppressClickRef = useRef(false);
+
+  const cancel = useCallback(() => {
+    if (timerRef.current !== null) window.clearTimeout(timerRef.current);
+    timerRef.current = null;
+    startRef.current = null;
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  return useCallback((id: string) => ({
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => {
+      if (event.pointerType !== 'touch' || event.button !== 0) return;
+      const target = event.target;
+      if (
+        target instanceof HTMLElement
+        && target !== event.currentTarget
+        && target.closest(INTERACTIVE_SELECTOR)
+      ) return;
+      cancel();
+      startRef.current = { x: event.clientX, y: event.clientY };
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null;
+        startRef.current = null;
+        suppressClickRef.current = true;
+        onSelectRef.current(id);
+      }, LONG_PRESS_MS);
+    },
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => {
+      const start = startRef.current;
+      if (!start) return;
+      if (
+        Math.abs(event.clientX - start.x) > MOVE_TOLERANCE_PX
+        || Math.abs(event.clientY - start.y) > MOVE_TOLERANCE_PX
+      ) cancel();
+    },
+    onPointerUp: cancel,
+    onPointerCancel: cancel,
+    onClickCapture: (event: ReactMouseEvent<HTMLElement>) => {
+      if (!suppressClickRef.current) return false;
+      suppressClickRef.current = false;
+      event.preventDefault();
+      event.stopPropagation();
+      return true;
+    },
+  }), [cancel]);
+}

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

@@ -0,0 +1,95 @@
+'use client';
+
+import { useCallback, type MouseEvent as ReactMouseEvent } from 'react';
+import {
+  useCollectionInteractions,
+  type CollectionInteractionController,
+  type SelectionMarqueeRect,
+} from './useCollectionInteractions';
+
+const ROW_ATTR = 'data-notis-row-id';
+
+export type DragRect = SelectionMarqueeRect;
+
+export interface UseMultiSelectOptions<T> {
+  items: T[];
+  getId: (item: T) => string;
+  /** When false, suppresses the global Esc / Cmd+A / X / Shift+Arrow listeners. Default true. */
+  bindKeyboardShortcuts?: boolean;
+  /** When false, disables the rubber-band drag-select rectangle. Default true. */
+  enableDragSelect?: boolean;
+  /** Distance (px) the cursor must move past mousedown before a drag begins. Default 5. */
+  dragThreshold?: number;
+  /** Initial head id (the row that Shift+Arrow extends from). */
+  initialHeadId?: string | null;
+  /** Fires when the head moves via Shift+Arrow so the consumer can scroll the row into view. */
+  onHeadChange?: (id: string | null) => void;
+}
+
+export interface MultiSelectController<T> {
+  selectedIds: ReadonlySet<string>;
+  selectedCount: number;
+  lastClickedId: string | null;
+  headId: string | null;
+  dragRect: DragRect | null;
+  isSelected: (id: string) => boolean;
+  getSelectedItems: () => T[];
+  toggle: (id: string) => void;
+  select: (ids: string[]) => void;
+  clear: () => void;
+  selectAll: () => void;
+  selectRange: (anchorId: string, targetId: string) => void;
+  setHead: (id: string | null) => void;
+  onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
+  onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
+  getRowProps: (id: string) => { [ROW_ATTR]: string };
+  getItemProps: CollectionInteractionController<T>['getItemProps'];
+  getCheckboxProps: (id: string) => {
+    isSelected: boolean;
+    onClick: (event: ReactMouseEvent) => void;
+  };
+  getContainerProps: CollectionInteractionController<T>['getContainerProps'];
+}
+
+/**
+ * @deprecated Use `useCollectionInteractions` for controlled selection,
+ * active-item navigation, scoped shortcuts, and semantic actions. This bridge
+ * is retained for the 0.2 minor and scheduled for removal in 0.3.
+ */
+export function useMultiSelect<T>(options: UseMultiSelectOptions<T>): MultiSelectController<T> {
+  const controller = useCollectionInteractions({
+    ...options,
+    defaultActiveId: options.initialHeadId,
+    onActiveItemChange: options.onHeadChange,
+    shortcuts: {
+      next: false,
+      previous: false,
+      activate: false,
+    },
+  });
+
+  const getRowProps = useCallback((id: string) => ({ [ROW_ATTR]: id }), []);
+  const getItemProps = controller.getItemProps;
+
+  return {
+    selectedIds: controller.selectedIds,
+    selectedCount: controller.selectedCount,
+    lastClickedId: controller.lastClickedId,
+    headId: controller.headId,
+    dragRect: controller.dragRect,
+    isSelected: controller.isSelected,
+    getSelectedItems: controller.getSelectedItems,
+    toggle: controller.toggle,
+    select: controller.select,
+    clear: controller.clear,
+    selectAll: controller.selectAll,
+    selectRange: controller.selectRange,
+    setHead: controller.setActive,
+    onCheckboxClick: controller.onCheckboxClick,
+    onRowMouseDown: controller.onRowMouseDown,
+    getRowProps,
+    getItemProps,
+    getCheckboxProps: controller.getCheckboxProps,
+    getContainerProps: controller.getContainerProps,
+  };
+}

package/template/packages/{notis-sdk → sdk}/src/hooks/useNotis.ts

@@ -1,7 +1,7 @@
 'use client';
 
 import { useNotisRuntime } from '../provider';
-import type { AppDescriptor, RouteDescriptor, DatabaseDescriptor } from '../runtime';
+import type { AppDescriptor, CollectionItemDetail, DatabaseDescriptor, RouteDescriptor } from '../runtime';
 
 interface NotisContext {
   /** App metadata (id, name, icon, description). Null before runtime loads. */
@@ -10,14 +10,18 @@ interface NotisContext {
   route: RouteDescriptor | null;
   /** Databases declared by this app. Empty before runtime loads. */
   databases: DatabaseDescriptor[];
+  /** Selected collection item for the current route, when applicable. */
+  collectionItem: CollectionItemDetail | null;
+  /** Resource requested through this route's canonical deep link. */
+  resourceId: string | null;
   /** Whether the runtime is loaded and available. */
   ready: boolean;
 }
 
 /**
- * Access app-level metadata: the app descriptor, current route, and declared
- * databases. Returns safe defaults when the runtime isn't available (SSR or
- * during `next dev` without preview).
+ * Access app-level metadata, the current route, declared databases, and the
+ * selected collection item. Returns safe defaults when the portal runtime is
+ * not available.
  */
 export function useNotis(): NotisContext {
   const runtime = useNotisRuntime();
@@ -26,6 +30,8 @@ export function useNotis(): NotisContext {
     app: runtime?.app ?? null,
     route: runtime?.route ?? null,
     databases: runtime?.databases ?? [],
+    collectionItem: runtime?.context?.collectionItem ?? null,
+    resourceId: runtime?.context?.resourceId ?? null,
     ready: runtime !== null,
   };
 }

package/template/packages/{notis-sdk → sdk}/src/hooks/useNotisNavigation.ts

@@ -5,9 +5,9 @@ import { useNotisRuntime } from '../provider';
 
 interface NavigationActions {
   /** Navigate to a route within the app by its path. */
-  toRoute: (path: string) => void;
+  toRoute: (path: string, options?: { resourceId?: string | null }) => void;
   /** Navigate to a document detail view. */
-  toDocument: (documentId: string) => void;
+  toDocument: (documentId: string, title?: string | null) => void;
   /** Navigate to the app's default route. */
   toApp: () => void;
 }
@@ -15,7 +15,7 @@ interface NavigationActions {
 /**
  * Navigation helpers for moving between routes and documents within the app.
  * When rendered inside the portal, uses the runtime.navigate() bridge.
- * In local preview, falls back to window.location.
+ * Without a portal runtime, falls back to window.location for route navigation.
  *
  * ```tsx
  * const nav = useNotisNavigation();
@@ -25,17 +25,20 @@ interface NavigationActions {
 export function useNotisNavigation(): NavigationActions {
   const runtime = useNotisRuntime();
 
-  const toRoute = useCallback((path: string) => {
+  const toRoute = useCallback((path: string, options?: { resourceId?: string | null }) => {
     if (runtime?.navigate) {
-      runtime.navigate({ kind: 'route', path });
+      runtime.navigate({ kind: 'route', path, resourceId: options?.resourceId ?? null });
     } else if (typeof window !== 'undefined') {
-      window.location.href = path;
+      const url = new URL(path, window.location.href);
+      if (options?.resourceId) url.searchParams.set('resource', options.resourceId);
+      else url.searchParams.delete('resource');
+      window.location.href = url.toString();
     }
   }, [runtime]);
 
-  const toDocument = useCallback((documentId: string) => {
+  const toDocument = useCallback((documentId: string, title?: string | null) => {
     if (runtime?.navigate) {
-      runtime.navigate({ kind: 'document', documentId });
+      runtime.navigate({ kind: 'document', documentId, title: title ?? undefined });
     }
   }, [runtime]);
 

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]);
+}