@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

package/dist/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/dist/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/dist/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/dist/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/dist/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` submits the prepared
+ * message on an active user gesture; background calls still open a draft.
+ */
+export function useHandover(): UseHandoverResult {
+  const runtime = useNotisRuntime();
+  const dispatch = runtime?.resource?.kind === 'space' ? runtime.draftHandover : runtime?.handover;
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const handover = useCallback(
+    async (payload: HandoverPayload): Promise<HandoverResult> => {
+      if (!dispatch) {
+        throw new Error('This Notis host cannot hand work to the manager chat.');
+      }
+
+      setPending(true);
+      setError(null);
+
+      try {
+        return await dispatch(payload);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [dispatch],
+  );
+
+  return { handover, pending, error, available: Boolean(dispatch) };
+}

package/dist/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/dist/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/dist/sdk/src/hooks/useNativeDocumentBody.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useQuery } from './useQuery';
+import { SpaceActionError, spaceQueryKey, type SpaceDocumentBodyRead, type SpaceDocumentBodySave } from '../space';
+
+/** Explicit textarea Save. The source owns the draft and retains its request ID
+ * until a receipt or unchanged result; background reads never replace that draft. */
+export function useNativeDocumentBody(binding: string, recordKey: string | null, options: {
+  readAction: string; writeAction?: string; enabled?: boolean;
+}) {
+  const runtime = useNotisRuntime();
+  const scope = JSON.stringify(spaceQueryKey(runtime, ['native-body', binding, recordKey, options.readAction, options.writeAction]));
+  const currentScope = useRef<string | null>(scope);
+  useLayoutEffect(() => {
+    currentScope.current = scope;
+    return () => { currentScope.current = null; };
+  }, [scope]);
+  const [state, setState] = useState<{ scope: string; pending: number; error: Error | null }>({ scope, pending: 0, error: null });
+  const query = useQuery<SpaceDocumentBodyRead>(['native-body', binding, recordKey, options.readAction], async () => {
+    if (!recordKey || runtime?.resource?.kind !== 'space' || !runtime.documentBody) throw new Error('Open a Space document first.');
+    const result = await runtime.documentBody({ operation: 'read', binding, recordKey, readAction: options.readAction });
+    if (!('content_markdown' in result)) throw new Error('The document response is incomplete.');
+    return result;
+  }, { readOnly: true, enabled: Boolean(recordKey) && options.enabled !== false });
+  const save = useCallback(async (draft: {
+    contentMarkdown: string; expectedRevision: number; schemaRevision: number; requestId: string;
+  }): Promise<SpaceDocumentBodySave> => {
+    if (!recordKey || !options.writeAction || runtime?.resource?.kind !== 'space' || !runtime.documentBody) {
+      throw new Error('This Space does not expose a body-edit action.');
+    }
+    setState(previous => ({ scope, pending: (previous.scope === scope ? previous.pending : 0) + 1, error: null }));
+    try {
+      const result = await runtime.documentBody({ operation: 'save', binding, recordKey,
+        readAction: options.readAction, writeAction: options.writeAction, ...draft });
+      if (currentScope.current !== scope) throw new SpaceActionError('This document view changed. Keep the original save request.', draft.requestId);
+      if (!('status' in result)) throw new Error('The document save receipt is incomplete.');
+      return result;
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      if (currentScope.current === scope) setState(previous => ({ ...previous, error }));
+      throw error;
+    } finally {
+      if (currentScope.current === scope) setState(previous => ({ ...previous, pending: Math.max(0, previous.pending - 1) }));
+    }
+  }, [runtime, binding, recordKey, options.readAction, options.writeAction, scope]);
+  return { ...query, body: query.data, save, saving: state.scope === scope && state.pending > 0,
+    saveError: state.scope === scope ? state.error : null };
+}

package/dist/sdk/src/hooks/useNativeDocuments.ts

@@ -0,0 +1,83 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord, NotisRuntime } from '../runtime';
+import type { NativeDelete, NativeInsert, NativeMutationReceipt, NativeQuery, NativeUpdate } from '../nativeData';
+import { useQuery, type UseQueryResult } from './useQuery';
+import { SdkQueryError } from '../queryErrors';
+
+function actionFor(runtime: NotisRuntime | null, binding: string, operation: 'query' | 'insert' | 'update' | 'delete'): string {
+  const descriptor = runtime?.space?.bindings[binding];
+  const action = descriptor?.kind === 'database' ? descriptor.operations?.[operation] : undefined;
+  if (runtime?.resource?.kind !== 'space' || !runtime.callAction || !action) {
+    const diagnostic = `This Space does not expose ${operation} for database binding "${binding}".`;
+    if (operation === 'query') throw new SdkQueryError('bindingUnavailable', diagnostic);
+    throw new Error(`This Space does not expose ${operation} for that database binding.`);
+  }
+  return action;
+}
+
+/**
+ * A declared query adapter, never an account-wide slug or owner lookup.
+ *
+ * `subscribe: true` follows the binding's live change feed where the host has one (a
+ * signed-in Editor of the Space, owner or teammate): `live` is then true and changes made
+ * elsewhere (another device, a teammate, an agent, an automation) re-read the rows on their
+ * own. Where `live` is false, keep offering a manual reload.
+ */
+export function useNativeDocuments(binding: string, options: {
+  query?: NativeQuery; fetchAll?: boolean; enabled?: boolean; staleTimeMs?: number; subscribe?: boolean;
+} = {}): UseQueryResult<{ documents: DocumentRecord[]; schemaRevision: number }> & { documents: DocumentRecord[]; schemaRevision?: number; live: boolean } {
+  const runtime = useNotisRuntime();
+  const [live, setLive] = useState(false);
+  const follow = options.subscribe === true && options.enabled !== false;
+  useEffect(() => {
+    if (!follow || !runtime?.subscribeDatabase) { setLive(false); return; }
+    let cancelled = false;
+    // The Space host re-reads every query of the view when the database changes, so the
+    // change callback has nothing left to do; the feed is a signal and never carries rows.
+    const stop = runtime.subscribeDatabase(binding, () => {}, { onStatusChange: value => { if (!cancelled) setLive(value); } });
+    return () => { cancelled = true; setLive(false); stop?.(); };
+  }, [runtime, binding, follow]);
+  const query = useQuery(['native-documents', binding, options.query ?? {}, Boolean(options.fetchAll)], async () => {
+    const action = actionFor(runtime, binding, 'query');
+    if (options.query?.mode && !['rows', 'search'].includes(options.query.mode)) throw new Error('Use useActionQuery for counts and aggregates.');
+    const rows: unknown[] = [];
+    let offset = options.query?.offset ?? 0;
+    let revision: number | undefined;
+    while (true) {
+      const result = await runtime!.callAction!<{ rows: unknown[]; schema_revision: number; has_more: boolean; next_offset: number | null }>(
+        action, { request: { ...options.query, offset } }, { readOnly: true, dedupe: true, schemaRevision: revision });
+      if (!result || !Array.isArray(result.rows) || !Number.isSafeInteger(result.schema_revision)) throw new SdkQueryError('responseIncomplete', 'Native query must return rows and a safe integer schema_revision.');
+      if (revision !== undefined && revision !== result.schema_revision) throw new SdkQueryError('schemaChanged');
+      revision = result.schema_revision;
+      rows.push(...result.rows);
+      if (!options.fetchAll || !result.has_more) break;
+      if (typeof result.next_offset !== 'number' || result.next_offset <= offset) throw new SdkQueryError('responseIncomplete', 'Native query pagination did not advance next_offset.');
+      offset = result.next_offset;
+    }
+    return { documents: rows.map(normalizeDocumentRecord), schemaRevision: revision! };
+  }, { readOnly: true, enabled: options.enabled, staleTimeMs: options.staleTimeMs });
+  return { ...query, documents: query.data?.documents ?? EMPTY_DOCUMENTS, schemaRevision: query.data?.schemaRevision, live };
+}
+
+/** Explicit insert/update/trash; update never silently creates a missing row. */
+export function useNativeMutation<TOperation extends 'insert' | 'update' | 'delete'>(binding: string, operation: TOperation): {
+  mutate: (input: TOperation extends 'insert' ? NativeInsert : TOperation extends 'update' ? NativeUpdate : NativeDelete,
+    options: { schemaRevision: number; requestId: string }) => Promise<NativeMutationReceipt>;
+  loading: boolean; error: Error | null;
+} {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(0), [error, setError] = useState<Error | null>(null);
+  const mutate = useCallback(async (input: NativeInsert | NativeUpdate | NativeDelete, options: { schemaRevision: number; requestId: string }) => {
+    const action = actionFor(runtime, binding, operation);
+    setPending((value) => value + 1); setError(null);
+    try { return await runtime!.callAction!<NativeMutationReceipt>(action, { request: input }, options); }
+    catch (cause) { const failure = cause instanceof Error ? cause : new Error(String(cause)); setError(failure); throw failure; }
+    finally { setPending((value) => value - 1); }
+  }, [runtime, binding, operation]);
+  return { mutate, loading: pending > 0, error };
+}
+const EMPTY_DOCUMENTS: DocumentRecord[] = [];