@notis_ai/cli 0.2.17 → 0.2.19

package/{template/packages → dist}/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';
@@ -19,14 +19,19 @@ export interface UseDocumentsOptions {
   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;
+  /** Reads again; resolves to the read's error, or null when it succeeded. */
+  refetch: () => Promise<Error | null>;
 }
 
 /**
@@ -44,78 +49,39 @@ 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[]> => {
+  // An untitled document reads "Untitled" in the Space's language.
+  const locale = runtime?.context?.locale === 'fr' ? 'fr' : 'en';
+  const query = useQuery<DocumentRecord[]>(
+    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll), options.includeContent !== false, locale],
+    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 } : {}),
+            ...(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);
-        }
+        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((document) => normalizeDocumentRecord(document, { locale })).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 → dist}/sdk/src/hooks/useHandover.ts

@@ -43,18 +43,18 @@ export interface UseHandoverResult {
  * 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.
+ * 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 (!runtime?.handover) {
+      if (!dispatch) {
         throw new Error('This Notis host cannot hand work to the manager chat.');
       }
 
@@ -62,7 +62,7 @@ export function useHandover(): UseHandoverResult {
       setError(null);
 
       try {
-        return await runtime.handover(payload);
+        return await dispatch(payload);
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
         setError(e);
@@ -71,8 +71,8 @@ export function useHandover(): UseHandoverResult {
         setPending(false);
       }
     },
-    [runtime],
+    [dispatch],
   );
 
-  return { handover, pending, error, available: Boolean(runtime?.handover) };
+  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/useMarqueeSelection.ts

@@ -0,0 +1,194 @@
+'use client';
+
+/**
+ * `useMarqueeSelection`: drag from empty space to select (the rubber band), shared by the Manager
+ * (`useCollectionInteractions`) and the toolkit list (`ListReader`), so both run the same code.
+ *
+ * - A press starts a marquee only on empty space inside the container: not on an item, not on a control
+ *   (button, link, field). A press on a control does nothing here; a press on an item is left to the item.
+ * - The marquee shows once the pointer moved past `threshold` px; the text selection is cleared then.
+ * - While dragging, every selectable item the rectangle intersects is selected, live (`onSelect`, in DOM order;
+ *   the last one is the anchor).
+ * - Releasing after a drag swallows the click that follows; a plain click on empty space clears (`onClear`).
+ * - Mouse events only: a touch drag scrolls and never draws a marquee.
+ */
+
+import { useCallback, useEffect, useRef, useState, type MouseEvent as ReactMouseEvent } from 'react';
+
+export interface SelectionMarqueeRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** Clicks on these belong to the control (Manager `INTERACTIVE_SELECTOR`). */
+export const MARQUEE_INTERACTIVE_SELECTOR =
+  'button, a, input, textarea, select, [role="button"], [contenteditable]:not([contenteditable="false"])';
+
+export interface UseMarqueeSelectionOptions {
+  /** The marquee is on: the collection allows multiple selection and the surface did not opt out. */
+  enabled: boolean;
+  /** The attribute every item element carries, holding its id. */
+  itemAttribute: string;
+  /** Items that may join the selection (pending and disabled ones may not). */
+  isSelectable: (id: string) => boolean;
+  /** The items under the rectangle, in DOM order, on every move of a drag. Replaces the selection. */
+  onSelect: (ids: string[]) => void;
+  /** A plain click (no drag) on empty space. */
+  onClear: () => void;
+  /** Distance in px before a press becomes a drag. Default 5. */
+  threshold?: number;
+  interactiveSelector?: string;
+  /** A part of an item a drag may also start from (a row's leading strip), so a list with no empty space left still
+   *  has a place to start one. A plain click there still reaches the item. Default: empty space only. */
+  startSelector?: string;
+}
+
+export interface MarqueeSelection {
+  /** The marquee in viewport coordinates while dragging, else null (draw it with `SelectionMarquee`). */
+  rect: SelectionMarqueeRect | null;
+  /** Put on the container. */
+  onMouseDown: (event: ReactMouseEvent) => void;
+  /** Put on the container: swallows the click that ends a drag (or any gesture that armed it). */
+  onClickCapture: (event: ReactMouseEvent) => void;
+  /** Swallow the next click inside the container (Mod-press toggles use it too). */
+  armSuppressNextClick: () => void;
+}
+
+function rectsIntersect(
+  a: { left: number; top: number; right: number; bottom: number },
+  b: { left: number; top: number; right: number; bottom: number },
+): boolean {
+  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+}
+
+/** The ids of the selectable items under `rect` inside `container`, in DOM order. */
+export function itemsInMarquee(
+  container: ParentNode | null,
+  rect: { left: number; top: number; right: number; bottom: number },
+  itemAttribute: string,
+  isSelectable: (id: string) => boolean,
+): string[] {
+  const nodes = container?.querySelectorAll<HTMLElement>(`[${itemAttribute}]`);
+  if (!nodes) return [];
+  const ids: string[] = [];
+  nodes.forEach((node) => {
+    if (!rectsIntersect(rect, node.getBoundingClientRect())) return;
+    const id = node.getAttribute(itemAttribute);
+    if (id && isSelectable(id)) ids.push(id);
+  });
+  return ids;
+}
+
+export function useMarqueeSelection(options: UseMarqueeSelectionOptions): MarqueeSelection {
+  const {
+    enabled, itemAttribute, threshold = 5, interactiveSelector = MARQUEE_INTERACTIVE_SELECTOR, startSelector,
+  } = options;
+  const latest = useRef(options);
+  latest.current = options;
+  const [rect, setRect] = useState<SelectionMarqueeRect | null>(null);
+
+  const containerRef = useRef<HTMLElement | null>(null);
+  const pendingRef = useRef(false);
+  const activeRef = useRef(false);
+  const startRef = useRef({ x: 0, y: 0 });
+  const currentRef = useRef({ x: 0, y: 0 });
+  const clickShouldClearRef = useRef(false);
+  const suppressNextClickRef = useRef(false);
+
+  const armSuppressNextClick = useCallback(() => {
+    suppressNextClickRef.current = true;
+    setTimeout(() => { suppressNextClickRef.current = false; }, 0);
+  }, []);
+
+  const onMouseDown = useCallback((event: ReactMouseEvent) => {
+    if (!enabled || event.button !== 0) return;
+    const target = event.target as HTMLElement | null;
+    if (!target || typeof target.closest !== 'function') return;
+    const itemTarget = target.closest(`[${itemAttribute}]`);
+    const interactiveTarget = target.closest(interactiveSelector);
+    if (interactiveTarget && interactiveTarget !== itemTarget) {
+      clickShouldClearRef.current = false;
+      return;
+    }
+    clickShouldClearRef.current = !itemTarget;
+    if (itemTarget) {
+      const startTarget = startSelector ? target.closest(startSelector) : null;
+      if (!startTarget || !itemTarget.contains(startTarget)) return;
+      // Neither the item's own drag nor a text selection starts from the strip.
+      event.preventDefault();
+    }
+    containerRef.current = event.currentTarget as HTMLElement;
+    pendingRef.current = true;
+    startRef.current = { x: event.clientX, y: event.clientY };
+    currentRef.current = { x: event.clientX, y: event.clientY };
+  }, [enabled, interactiveSelector, itemAttribute, startSelector]);
+
+  const onClickCapture = useCallback((event: ReactMouseEvent) => {
+    if (!suppressNextClickRef.current) return;
+    suppressNextClickRef.current = false;
+    event.preventDefault();
+    event.stopPropagation();
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      pendingRef.current = false;
+      if (activeRef.current) {
+        activeRef.current = false;
+        setRect(null);
+      }
+      return undefined;
+    }
+    if (typeof document === 'undefined') return undefined;
+    const doc = document;
+    const handleMouseMove = (event: MouseEvent) => {
+      if (pendingRef.current) {
+        const dx = event.clientX - startRef.current.x;
+        const dy = event.clientY - startRef.current.y;
+        if (Math.abs(dx) > threshold || Math.abs(dy) > threshold) {
+          pendingRef.current = false;
+          activeRef.current = true;
+          window.getSelection()?.removeAllRanges();
+        } else return;
+      }
+      if (!activeRef.current) return;
+      event.preventDefault();
+      currentRef.current = { x: event.clientX, y: event.clientY };
+      const next: SelectionMarqueeRect = {
+        left: Math.min(startRef.current.x, currentRef.current.x),
+        top: Math.min(startRef.current.y, currentRef.current.y),
+        width: Math.abs(currentRef.current.x - startRef.current.x),
+        height: Math.abs(currentRef.current.y - startRef.current.y),
+      };
+      setRect(next);
+      const { itemAttribute: attribute, isSelectable, onSelect } = latest.current;
+      onSelect(itemsInMarquee(containerRef.current, {
+        left: next.left, top: next.top, right: next.left + next.width, bottom: next.top + next.height,
+      }, attribute, isSelectable));
+    };
+    const handleMouseUp = () => {
+      const wasPending = pendingRef.current;
+      const wasActive = activeRef.current;
+      pendingRef.current = false;
+      activeRef.current = false;
+      if (wasActive) {
+        setRect(null);
+        clickShouldClearRef.current = false;
+        armSuppressNextClick();
+      } else if (wasPending && clickShouldClearRef.current) {
+        clickShouldClearRef.current = false;
+        latest.current.onClear();
+      }
+    };
+    doc.addEventListener('mousemove', handleMouseMove);
+    doc.addEventListener('mouseup', handleMouseUp);
+    return () => {
+      doc.removeEventListener('mousemove', handleMouseMove);
+      doc.removeEventListener('mouseup', handleMouseUp);
+    };
+  }, [armSuppressNextClick, enabled, threshold]);
+
+  return { rect, onMouseDown, onClickCapture, armSuppressNextClick };
+}

package/{template/packages → dist}/sdk/src/hooks/useMultiSelect.ts

@@ -43,10 +43,7 @@ export interface MultiSelectController<T> {
   onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
   onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
   getRowProps: (id: string) => { [ROW_ATTR]: string };
-  getItemProps: (id: string) => {
-    [ROW_ATTR]: string;
-    onMouseDown: (event: ReactMouseEvent) => void;
-  };
+  getItemProps: CollectionInteractionController<T>['getItemProps'];
   getCheckboxProps: (id: string) => {
     isSelected: boolean;
     onClick: (event: ReactMouseEvent) => void;
@@ -72,10 +69,7 @@ export function useMultiSelect<T>(options: UseMultiSelectOptions<T>): MultiSelec
   });
 
   const getRowProps = useCallback((id: string) => ({ [ROW_ATTR]: id }), []);
-  const getItemProps = useCallback((id: string) => ({
-    [ROW_ATTR]: id,
-    onMouseDown: controller.onRowMouseDown(id),
-  }), [controller.onRowMouseDown]);
+  const getItemProps = controller.getItemProps;
 
   return {
     selectedIds: controller.selectedIds,

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,143 @@
+'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 locale = runtime?.context?.locale === 'fr' ? 'fr' : 'en';
+  const query = useQuery(['native-documents', binding, options.query ?? {}, Boolean(options.fetchAll), locale], 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((row) => normalizeDocumentRecord(row, { locale })), 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);
+    // A trashed row leaves every cached read at once and comes back if the write fails.
+    const key = operation === 'delete' && typeof (input as NativeDelete).record_key === 'string' ? (input as NativeDelete).record_key : null;
+    const hidden = key ? runtime?.queryClient?.hideRecords?.([key]) : undefined;
+    try {
+      const receipt = await runtime!.callAction!<NativeMutationReceipt>(action, { request: input }, options);
+      hidden?.commit();
+      return receipt;
+    } catch (cause) {
+      hidden?.restore();
+      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 };
+}
+
+export interface NativeDeleteManyResult {
+  done: NativeDelete[];
+  failed: Array<{ input: NativeDelete; error: Error }>;
+}
+
+/**
+ * Trashes many rows of one database binding: every row leaves the cached reads at once, the writes run a few at
+ * a time (each with its own request ID, `${requestId}:${record_key}`, so a retry with the same `requestId` replays
+ * instead of trashing twice), the reads refresh once at the end, and a row whose write failed comes back. It never
+ * throws for a failed row: `failed` lists them.
+ */
+export function useNativeDelete(binding: string): {
+  deleteMany: (inputs: readonly NativeDelete[], options: { schemaRevision: number; requestId: string }) => Promise<NativeDeleteManyResult>;
+  loading: boolean; error: Error | null;
+} {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(0), [error, setError] = useState<Error | null>(null);
+  const deleteMany = useCallback(async (inputs: readonly NativeDelete[], options: { schemaRevision: number; requestId: string }) => {
+    const action = actionFor(runtime, binding, 'delete');
+    const result: NativeDeleteManyResult = { done: [], failed: [] };
+    if (!inputs.length) return result;
+    setPending((value) => value + 1); setError(null);
+    const hidden = runtime?.queryClient?.hideRecords?.(inputs.map((input) => input.record_key));
+    let next = 0;
+    const worker = async () => {
+      while (next < inputs.length) {
+        const input = inputs[next++];
+        try {
+          await runtime!.callAction!<NativeMutationReceipt>(action, { request: input },
+            { schemaRevision: options.schemaRevision, requestId: `${options.requestId}:${input.record_key}`, deferRefresh: true });
+          result.done.push(input);
+        } catch (cause) {
+          result.failed.push({ input, error: cause instanceof Error ? cause : new Error(String(cause)) });
+        }
+      }
+    };
+    try {
+      await Promise.all(Array.from({ length: Math.min(DELETE_CONCURRENCY, inputs.length) }, worker));
+    } finally {
+      hidden?.commit(result.done.map((input) => input.record_key));
+      hidden?.restore(result.failed.map((item) => item.input.record_key));
+      runtime?.queryClient?.invalidate();
+      if (result.failed.length) setError(result.failed[0].error);
+      setPending((value) => value - 1);
+    }
+    return result;
+  }, [runtime, binding]);
+  return { deleteMany, loading: pending > 0, error };
+}
+const DELETE_CONCURRENCY = 4;
+const EMPTY_DOCUMENTS: DocumentRecord[] = [];