@notis_ai/cli 0.2.18 → 0.2.19

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

@@ -1,9 +1,12 @@
 'use client';
 
 import { useNotisRuntime } from '../provider';
-import type { AppDescriptor, CollectionItemDetail, DatabaseDescriptor, RouteDescriptor } from '../runtime';
+import type { RuntimeResource, AppDescriptor, CollectionItemDetail, DatabaseDescriptor, RouteDescriptor } from '../runtime';
 
 interface NotisContext {
+  /** UI selection only; it grants no access and is never a record scope. */
+  selection: string | null;
+  resource: RuntimeResource | null;
   /** App metadata (id, name, icon, description). Null before runtime loads. */
   app: AppDescriptor | null;
   /** Current route descriptor. Null before runtime loads. */
@@ -27,6 +30,8 @@ export function useNotis(): NotisContext {
   const runtime = useNotisRuntime();
 
   return {
+    selection: runtime?.context?.selection ?? null,
+    resource: runtime?.resource ?? null,
     app: runtime?.app ?? null,
     route: runtime?.route ?? null,
     databases: runtime?.databases ?? [],

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

@@ -0,0 +1,70 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+
+export interface SpaceNavigationOptions {
+  recordKey?: string | null;
+  /** Declared view parameters. The destination authorizes records and drops unknown names. */
+  params?: Record<string, string | number | boolean | null | undefined>;
+  selection?: string | null;
+}
+
+interface NavigationActions {
+  /** Resolve a declared portable destination under the current viewer's access. */
+  toNamedSpace: (alias: string, options?: SpaceNavigationOptions) => Promise<void>;
+  /**
+   * Open an exact Space, optionally at a native record's stable record_key. Resolves once the host has taken the
+   * navigation; rejects when the host refuses it (the Space closed, or the view it came from is no longer active).
+   */
+  toSpace: (spaceId: string, options?: SpaceNavigationOptions) => Promise<void>;
+  /** Navigate to a route within the app by its path. */
+  toRoute: (path: string, options?: { resourceId?: string | null }) => void;
+  /** Navigate to the app's default route. */
+  toApp: () => void;
+}
+
+/**
+ * Navigation helpers for Spaces and app routes.
+ * When rendered inside the portal, uses the runtime.navigate() bridge.
+ * Without a portal runtime, falls back to window.location for route navigation.
+ *
+ * ```tsx
+ * const nav = useNotisNavigation();
+ * nav.toSpace(spaceId, { recordKey });
+ * ```
+ */
+export function useNotisNavigation(): NavigationActions {
+  const runtime = useNotisRuntime();
+
+  const toNamedSpace = useCallback(async (alias: string, options?: SpaceNavigationOptions) => {
+    if (runtime?.resource?.kind !== 'space' || !runtime.navigate) throw new Error('Open this Space in a current Notis host to navigate.');
+    await runtime.navigate({ kind: 'space-reference', alias, documentId: options?.recordKey ?? null, selection: options?.selection ?? null,
+      ...(options?.params ? { params: options.params } : {}) });
+  }, [runtime]);
+
+  const toSpace = useCallback(async (spaceId: string, options?: SpaceNavigationOptions) => {
+    if (!runtime?.navigate) throw new Error('Open this Space in a current Notis host to navigate.');
+    await runtime.navigate({ kind: 'space', spaceId, documentId: options?.recordKey ?? null,
+      ...(options?.params ? { params: options.params } : {}), ...(options?.selection ? { selection: options.selection } : {}) });
+  }, [runtime]);
+
+  const toRoute = useCallback((path: string, options?: { resourceId?: string | null }) => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'route', path, resourceId: options?.resourceId ?? null });
+    } else if (typeof window !== 'undefined') {
+      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 toApp = useCallback(() => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'app' });
+    }
+  }, [runtime]);
+
+  return { toNamedSpace, toSpace, toRoute, toApp };
+}

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

@@ -0,0 +1,81 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useNotisRuntime } from '../provider';
+import { createQueryClient, queryKey } from '../queryCache';
+import { spaceQueryKey } from '../space';
+import { localizeQueryError } from '../queryErrors';
+
+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;
+  /** Reads again; resolves to the read's localized error, or null when it succeeded (never rejects). */
+  refetch: () => Promise<Error | null>;
+}
+
+/** 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(spaceQueryKey(runtime, 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 locale = runtime?.context?.locale;
+  const refetch = useCallback(async (): Promise<Error | null> => {
+    if (!enabled) return null;
+    client.invalidate(cacheKey);
+    try {
+      await fetch();
+      return null;
+    } catch (failure) {
+      return localizeQueryError(failure instanceof Error ? failure : new Error(String(failure)), locale);
+    }
+  }, [cacheKey, client, enabled, fetch, locale]);
+  const error = useMemo(() => localizeQueryError(snapshot.error, runtime?.context?.locale), [snapshot.error, runtime?.context?.locale]);
+  return {
+    data: enabled ? snapshot.data : undefined,
+    hasData: enabled && snapshot.hasData,
+    loading: enabled && !snapshot.hasData && !snapshot.error,
+    isFetching: enabled && snapshot.isFetching,
+    error: enabled ? 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(spaceQueryKey(runtime, 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(spaceQueryKey(runtime, key)), read, { staleTimeMs: options.staleTimeMs });
+    },
+  }), [runtime]);
+}

package/dist/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);
+}

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

@@ -0,0 +1,102 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface TopBarSearchOptions {
+  /** Current value shown in the top bar search input. */
+  value: string;
+  /** Called when the user types in the top bar. */
+  onChange: (value: string) => void;
+  /** Placeholder text for the input. Defaults to 'Search…'. */
+  placeholder?: string;
+  /** Called when the user presses Enter. May return a Promise. */
+  onSubmit?: () => void | Promise<void>;
+}
+
+/** A view that never takes the typed values keeps at most this many waiting. */
+const MAX_UNSHOWN = 64;
+
+interface TopBarSearchActions {
+  /** Toggle the loader that replaces the search icon in the top bar. */
+  setLoading: (loading: boolean) => void;
+}
+
+/**
+ * Registers this view's search binding with the portal's top bar search input.
+ * While the component is mounted, typing in the top bar calls `onChange`,
+ * pressing Enter calls `onSubmit`, and the `value` prop drives the input.
+ *
+ * Use `setLoading(true)` only for an explicitly submitted search action, then
+ * restore the icon with `setLoading(false)`. Automatic reads use content
+ * skeletons initially and refresh populated content silently.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * const [q, setQ] = useState('');
+ * const { setLoading } = useTopBarSearch({
+ *   value: q,
+ *   onChange: setQ,
+ *   placeholder: 'Search notes…',
+ *   onSubmit: async () => {
+ *     setLoading(true);
+ *     try { await runSearch(q); } finally { setLoading(false); }
+ *   },
+ * });
+ * ```
+ *
+ * Callback refs retain the latest committed handlers without re-registering
+ * search on every app render. Inline callbacks are safe.
+ *
+ * The top bar owns what is typed in it. A `value` that came from the bar is
+ * not sent back: the view's answer can arrive after the next key, and sending
+ * it back would undo that key. A value the view sets itself (a clear button,
+ * a link, a value it trims) is sent to the bar.
+ */
+export function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions {
+  const runtime = useNotisRuntime();
+  const { value, onChange, placeholder, onSubmit } = opts;
+  const callbacks = useRef({ onChange, onSubmit });
+  useLayoutEffect(() => { callbacks.current = { onChange, onSubmit }; });
+  // Values the bar sent that the view has not shown yet, oldest first.
+  const fromBar = useRef<string[]>([]);
+  const hasSubmit = Boolean(onSubmit);
+
+  useEffect(() => {
+    const register = runtime?.registerTopBarSearch;
+    if (!register) return;
+    register({
+      onChange: (next) => {
+        const sent = fromBar.current;
+        sent.push(next);
+        if (sent.length > MAX_UNSHOWN) sent.splice(0, sent.length - MAX_UNSHOWN);
+        callbacks.current.onChange(next);
+      },
+      placeholder,
+      onSubmit: hasSubmit ? () => callbacks.current.onSubmit?.() : undefined,
+    });
+    return () => {
+      register(null);
+    };
+  }, [runtime, placeholder, hasSubmit]);
+
+  useLayoutEffect(() => {
+    const sent = fromBar.current;
+    // The view caught up with the bar, or shows a value the bar has already gone past.
+    if (sent.length && value === sent[sent.length - 1]) { sent.length = 0; return; }
+    const shown = sent.indexOf(value);
+    if (shown >= 0) { sent.splice(0, shown + 1); return; }
+    sent.length = 0;
+    runtime?.setTopBarSearchValue?.(value);
+  }, [runtime, value]);
+
+  const setLoading = useCallback(
+    (loading: boolean) => {
+      runtime?.setTopBarSearchLoading?.(loading);
+    },
+    [runtime],
+  );
+
+  return { setLoading };
+}

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

@@ -0,0 +1,75 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { useNotisRuntime } from '../provider';
+
+type Leaf = { label: string; onBack?: () => void; recordKey?: string };
+type LeafSetter = (leaf: Leaf | null) => void;
+type Owner = { label: string; back: { current: (() => void) | undefined }; hasBack: boolean; recordKey: string | null };
+type LeafOwners = { owners: Owner[]; sent: Owner | null; back: () => void };
+
+// The components that own a leaf, per host setter, in mount order. The newest owner names the leaf; a component
+// with no record open owns nothing and never writes, so it cannot clear another one's leaf.
+const ownersBySetter = new WeakMap<LeafSetter, LeafOwners>();
+
+function publish(set: LeafSetter, entry: LeafOwners) {
+  const top = entry.owners.length ? entry.owners[entry.owners.length - 1] : null;
+  const sent = entry.sent;
+  if (top === sent || (top && sent && top.label === sent.label && top.hasBack === sent.hasBack && top.recordKey === sent.recordKey)) {
+    entry.sent = top;
+    return;
+  }
+  entry.sent = top;
+  // The host keeps one stable way back per setter; it always calls the newest owner's latest onBack.
+  set(top ? { label: top.label, ...(top.hasBack ? { onBack: entry.back } : {}), ...(top.recordKey ? { recordKey: top.recordKey } : {}) } : null);
+}
+
+/**
+ * Adds the open record's label as the last crumb of the Portal top bar title
+ * ("Product / Tickets / PRO-002") while the component is mounted. Pass `null`
+ * when no record is open: the component then owns no leaf and leaves another
+ * component's leaf alone. With several owners, the most recently opened one
+ * names the leaf; closing it gives the leaf back to the one before.
+ *
+ * `onBack` closes the record: the crumb before the leaf (the view) then calls it,
+ * so the top bar is the page's way back and the page draws no breadcrumb of its own.
+ *
+ * `recordKey` names the record the leaf shows, when it is a record of the Space's own
+ * collection (its `collection` database): its Editors can then rename that record from
+ * the leaf in the top bar, and the view shows the new name once its data refreshes.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * useTopBarTitleLeaf(openTicket ? openTicket.key : null, () => setParams({ ticket: null }));
+ * useTopBarTitleLeaf(deck ? deck.name : null, undefined, { recordKey: deck?.recordKey });
+ * ```
+ */
+export function useTopBarTitleLeaf(label: string | null, onBack?: () => void, options?: { recordKey?: string | null }): void {
+  const runtime = useNotisRuntime();
+  const leaf = label?.trim() || null;
+  const back = useRef(onBack);
+  back.current = onBack;
+  const hasBack = Boolean(onBack);
+  const recordKey = options?.recordKey?.trim() || null;
+
+  useEffect(() => {
+    const set = runtime?.setTopBarTitleLeaf;
+    if (!set || !leaf) return;
+    let entry = ownersBySetter.get(set);
+    if (!entry) {
+      const created: LeafOwners = { owners: [], sent: null, back: () => created.sent?.back.current?.() };
+      entry = created;
+      ownersBySetter.set(set, entry);
+    }
+    const owner: Owner = { label: leaf, back, hasBack, recordKey };
+    entry.owners.push(owner);
+    publish(set, entry);
+    return () => {
+      const current = ownersBySetter.get(set);
+      if (!current) return;
+      current.owners = current.owners.filter((item) => item !== owner);
+      publish(set, current);
+    };
+  }, [runtime, leaf, hasBack, recordKey]);
+}

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

@@ -79,7 +79,7 @@ export function useUpsertDocument(databaseSlug: string): UseUpsertDocumentResult
         if (!result.document) {
           throw new Error(result.error ?? result.message ?? 'Failed to save document');
         }
-        return normalizeDocumentRecord(result.document);
+        return normalizeDocumentRecord(result.document, { locale: runtime.context?.locale === 'fr' ? 'fr' : 'en' });
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
         setError(e);

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

@@ -0,0 +1,195 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { NotisRuntime } from '../runtime';
+import { useQuery, type UseQueryResult } from './useQuery';
+import { SdkQueryError } from '../queryErrors';
+import type { SpaceDefinition, SpaceShownOptions, SpaceShownResult, SpaceViewParam } from '../space';
+import { isViewDate, isViewPeriod } from '../viewPeriod';
+
+type ParamValue<P> = P extends { type: 'enum'; values: readonly (infer V)[] } ? V
+  : P extends { type: 'number' } ? number : P extends { type: 'boolean' } ? boolean : string;
+
+/** Typed params of a definition: `useViewParams<typeof definition>()`. */
+export type ViewParamsOf<D extends Pick<SpaceDefinition, 'params'>> = D['params'] extends Record<string, SpaceViewParam>
+  ? { [K in keyof D['params']]?: ParamValue<D['params'][K]> } : Record<string, string | number | boolean | undefined>;
+
+/** A change to the view's URL params: a value sets that param, null or undefined removes it. */
+export type ViewParamChanges<T> = { [K in keyof T]?: T[K] | null };
+
+export interface SetViewParamsOptions {
+  /** Replace the current history entry instead of adding one, so Back skips this change. Default false. */
+  replace?: boolean;
+}
+
+export interface ViewParams<T> {
+  /** Declared params only, typed; invalid URL values are left out (their default applies). */
+  params: T;
+  /** Declared params whose URL value was invalid and ignored. */
+  invalid: string[];
+  /** Required params without a value. */
+  missing: string[];
+  declared: Record<string, SpaceViewParam>;
+  ready: boolean;
+  /**
+   * Change this view's own URL params; the same Space and record stay open. Names left out of `changes` keep their
+   * value. No destination lookup and no alias to declare: use `useNotisNavigation().toNamedSpace` for another Space.
+   * Undeclared names are dropped by the host. Rejects outside a Space.
+   */
+  setParams: (changes: ViewParamChanges<T>, options?: SetViewParamsOptions) => Promise<void>;
+}
+
+const RECORD_KEY = /^(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+const NUMBER = /^-?\d+(?:\.\d+)?$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+function parseValue(declaration: SpaceViewParam, raw: string): string | number | boolean | undefined {
+  switch (declaration.type) {
+    case 'text': return raw.length <= 500 && !CONTROL.test(raw) ? raw : undefined;
+    case 'enum': return declaration.values?.includes(raw) ? raw : undefined;
+    case 'number': { const value = Number(raw); return NUMBER.test(raw) && Number.isFinite(value) ? value : undefined; }
+    case 'boolean': return raw === 'true' ? true : raw === 'false' ? false : undefined;
+    case 'date': {
+      return ['today', 'tomorrow'].includes(raw) || isViewDate(raw) ? raw : undefined;
+    }
+    case 'period': return isViewPeriod(raw) ? raw : undefined;
+    case 'record': {
+      if (!RECORD_KEY.test(raw)) return undefined;
+      const hex = raw.replaceAll('-', '').toLowerCase();
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    default: return undefined;
+  }
+}
+
+/** Keep declared, valid values only; unknown params are dropped and defaults applied. */
+export function parseViewParams(declared: Record<string, SpaceViewParam> | undefined,
+  raw: Record<string, string> | null | undefined): Pick<ViewParams<Record<string, string | number | boolean>>, 'params' | 'invalid' | 'missing'> {
+  const params: Record<string, string | number | boolean> = {};
+  const invalid: string[] = [], missing: string[] = [];
+  for (const [name, declaration] of Object.entries(declared || {})) {
+    const value = raw && Object.hasOwn(raw, name) && typeof raw[name] === 'string' && raw[name] !== '' ? raw[name] : undefined;
+    const parsed = value === undefined ? undefined : parseValue(declaration, value);
+    if (value !== undefined && parsed === undefined) invalid.push(name);
+    if (parsed !== undefined) params[name] = parsed;
+    else if (declaration.default !== undefined) params[name] = declaration.default;
+    else if (declaration.required) missing.push(name);
+  }
+  return { params, invalid, missing };
+}
+
+// The params a view asked for last, until the host answers with new ones: two changes in one tick keep each other.
+const pendingWrites = new WeakMap<object, { base: Record<string, string> | null; params: Record<string, string> }>();
+
+/**
+ * Write the open Space's own URL params (`setParams` of useViewParams; the toolkit's open item and period use it).
+ * The host keeps the Space and record, checks no destination, and adds a history entry unless `replace` is set.
+ */
+export function writeViewParams(runtime: NotisRuntime | null | undefined, changes: Record<string, unknown>,
+  options: SetViewParamsOptions = {}): Promise<void> {
+  if (runtime?.resource?.kind !== 'space' || typeof runtime.navigate !== 'function') {
+    return Promise.reject(new Error('Open this Space in a current Notis host to change its params.'));
+  }
+  const current = runtime.context?.params ?? null;
+  const pending = pendingWrites.get(runtime);
+  const next: Record<string, string> = { ...(pending && pending.base === current ? pending.params : current ?? {}) };
+  for (const [name, value] of Object.entries(changes)) {
+    if (value === null || value === undefined) delete next[name];
+    else next[name] = String(value);
+  }
+  pendingWrites.set(runtime, { base: current, params: next });
+  const forget = (error: unknown) => {
+    if (pendingWrites.get(runtime)?.params === next) pendingWrites.delete(runtime);
+    throw error;
+  };
+  try {
+    return Promise.resolve(runtime.navigate({ kind: 'view-params', params: next, ...(options.replace ? { replace: true } : {}) }))
+      .then(() => undefined, forget);
+  } catch (error) {
+    return Promise.reject(error).catch(forget);
+  }
+}
+
+/**
+ * The view's declared URL params, typed and validated, and `setParams` to change them. Unknown params (such as
+ * `?foo=`) never reach the view. Record params are record keys; the server authorizes them where it uses them.
+ */
+export function useViewParams<D extends Pick<SpaceDefinition, 'params'> = SpaceDefinition>(): ViewParams<ViewParamsOf<D>> {
+  const runtime = useNotisRuntime();
+  const declared = runtime?.space?.params;
+  const raw = runtime?.context?.params;
+  const setParams = useCallback((changes: ViewParamChanges<ViewParamsOf<D>>, options?: SetViewParamsOptions) =>
+    writeViewParams(runtime, changes as Record<string, unknown>, options), [runtime]);
+  return useMemo(() => ({ ...parseViewParams(declared, raw), declared: declared || {}, ready: runtime !== null, setParams }) as
+    ViewParams<ViewParamsOf<D>>, [declared, raw, runtime, setParams]);
+}
+
+export interface UseShownOptions extends SpaceShownOptions {
+  enabled?: boolean;
+  staleTimeMs?: number;
+  /**
+   * Read every page and answer with all rows: pages of `pageSize` (default 200) are read from `offset` until one
+   * comes back short, up to `SHOWN_ALL_PAGES_MAX` pages.
+   */
+  allPages?: boolean;
+}
+
+/** The most pages `useShown({ allPages: true })` reads. */
+export const SHOWN_ALL_PAGES_MAX = 50;
+const SHOWN_ALL_PAGES_SIZE = 200;
+
+/** True when a declared list has an authorized host reader (Editor or exact record Site). */
+export function useShownAvailable(name: string): boolean {
+  const runtime = useNotisRuntime();
+  const list = runtime?.space?.shows && Object.hasOwn(runtime.space.shows, name) ? runtime.space.shows[name] : null;
+  return runtime?.resource?.kind === 'space' && typeof runtime.shown === 'function' && Boolean(list && 'database' in list);
+}
+
+/**
+ * Runs exactly the list this view declares in `shows` with the current params, so the declaration
+ * is the list the view displays. Only sorting and paging are chosen here.
+ *
+ * A list this view context cannot read (undeclared, described only, or no host reader) answers
+ * with `error` instead of a query that never starts, so the view can show an error state. Missing
+ * required params are not an error: they are listed by `useViewParams().missing`.
+ */
+export function useShown<TRow = Record<string, unknown>>(name: string, options: UseShownOptions = {}):
+  UseQueryResult<SpaceShownResult & { rows: TRow[] }> {
+  const runtime = useNotisRuntime();
+  const available = useShownAvailable(name);
+  const { params, missing } = useViewParams();
+  const { sorts, pageSize, offset, includeContent, allPages = false } = options;
+  const list = runtime?.space?.shows && Object.hasOwn(runtime.space.shows, name) ? runtime.space.shows[name] : null;
+  const reads = list && 'database' in list && Array.isArray(list.params) ? list.params : null;
+  // Rows are keyed by the params the list reads: picking another record in the view keeps the rows
+  // already shown instead of reading the same list again. The read itself always sends every param.
+  const keyed = useMemo(() => reads ? Object.fromEntries(Object.entries(params).filter(([param]) => reads.includes(param))) : params,
+    [params, reads]);
+  const result = useQuery(['shown', name, keyed, sorts ?? null, pageSize ?? null, offset ?? null, includeContent ?? false,
+    allPages], async () => {
+    if (!runtime?.shown) throw new SdkQueryError('listUnavailable');
+    if (!allPages) {
+      return runtime.shown<SpaceShownResult & { rows: TRow[] }>(name, params as Record<string, unknown>,
+        { sorts, pageSize, offset, includeContent });
+    }
+    const size = pageSize ?? SHOWN_ALL_PAGES_SIZE;
+    let first: (SpaceShownResult & { rows: TRow[] }) | null = null;
+    const rows: TRow[] = [];
+    for (let page = 0; page < SHOWN_ALL_PAGES_MAX; page += 1) {
+      const answer = await runtime.shown<SpaceShownResult & { rows: TRow[] }>(name, params as Record<string, unknown>,
+        { sorts, pageSize: size, offset: (offset ?? 0) + page * size, includeContent });
+      first ??= answer;
+      const pageRows = Array.isArray(answer?.rows) ? answer.rows : [];
+      rows.push(...pageRows);
+      if (pageRows.length < size) break;
+    }
+    const merged = { ...(first as SpaceShownResult & { rows: TRow[] }), rows } as SpaceShownResult & { rows: TRow[] };
+    return merged;
+  }, { readOnly: true, enabled: available && !missing.length && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+  const unavailable = runtime !== null && !available && options.enabled !== false;
+  const error = useMemo(() => unavailable ? new SdkQueryError('listUnavailable', `The list "${name}" is unavailable in this view: declare it in \`shows\` `
+    + `with a database, or gate it on useShownAvailable("${name}").`, runtime?.context?.locale) : null, [unavailable, name, runtime?.context?.locale]);
+  return unavailable ? { ...result, loading: false, isFetching: false, error } : result;
+}