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

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

@@ -0,0 +1,42 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+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. */
+  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 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();
+
+  return {
+    selection: runtime?.context?.selection ?? null,
+    resource: runtime?.resource ?? null,
+    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/dist/sdk/src/hooks/useNotisNavigation.ts

@@ -0,0 +1,67 @@
+'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. */
+  toSpace: (spaceId: string, options?: SpaceNavigationOptions) => 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((spaceId: string, options?: SpaceNavigationOptions) => {
+    if (!runtime?.navigate) throw new Error('Open this Space in a current Notis host to navigate.');
+    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,74 @@
+'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;
+  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(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 refetch = useCallback(async () => {
+    if (!enabled) return;
+    client.invalidate(cacheKey);
+    await fetch().catch(() => {});
+  }, [cacheKey, client, enabled, fetch]);
+  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/useTool.ts

@@ -0,0 +1,65 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ToolCallOptions } from '../runtime';
+
+type ToolArguments = Record<string, unknown>;
+
+type ToolCall<TArgs extends ToolArguments | undefined, TResult> = undefined extends TArgs
+  ? (args?: Exclude<TArgs, undefined>, options?: ToolCallOptions) => Promise<TResult>
+  : (args: TArgs, options?: ToolCallOptions) => Promise<TResult>;
+
+export interface ToolCallState {
+  loading: boolean;
+  error: Error | null;
+}
+
+export interface UseToolResult<
+  TArgs extends ToolArguments | undefined = ToolArguments | undefined,
+  TResult = unknown,
+> extends ToolCallState {
+  call: ToolCall<TArgs, TResult>;
+}
+
+/**
+ * Call a specific Notis tool by name.
+ *
+ * ```tsx
+ * const { call, loading } = useTool('LOCAL_NOTIS_WEB_SEARCH');
+ * const result = await call({ query: 'latest news' });
+ * ```
+ */
+export function useTool<
+  TArgs extends ToolArguments | undefined = ToolArguments | undefined,
+  TResult = unknown,
+>(toolName: string): UseToolResult<TArgs, TResult> {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const call = useCallback(
+    async (args?: ToolArguments, options?: ToolCallOptions): Promise<TResult> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool<TResult>(toolName, args, options);
+        return result;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, toolName],
+  ) as ToolCall<TArgs, TResult>;
+
+  return { call, loading, error };
+}

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,81 @@
+'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>;
+}
+
+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.
+ */
+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 }; });
+  const hasSubmit = Boolean(onSubmit);
+
+  useEffect(() => {
+    const register = runtime?.registerTopBarSearch;
+    if (!register) return;
+    register({
+      onChange: (next) => callbacks.current.onChange(next),
+      placeholder,
+      onSubmit: hasSubmit ? () => callbacks.current.onSubmit?.() : undefined,
+    });
+    return () => {
+      register(null);
+    };
+  }, [runtime, placeholder, hasSubmit]);
+
+  useEffect(() => {
+    runtime?.setTopBarSearchValue?.(value);
+  }, [runtime, value]);
+
+  const setLoading = useCallback(
+    (loading: boolean) => {
+      runtime?.setTopBarSearchLoading?.(loading);
+    },
+    [runtime],
+  );
+
+  return { setLoading };
+}

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

@@ -0,0 +1,95 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+export interface UpsertDocumentArgs {
+  documentId?: string;
+  title?: string;
+  /** Property values keyed by property name (already-plain values). */
+  properties?: Record<string, unknown>;
+  /** Markdown content; converted server-side to BlockNote. Exclusive with contentBlocknote. */
+  contentMarkdown?: string | null;
+  /** BlockNote block JSON. Exclusive with contentMarkdown. */
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  /** 'archive' soft-deletes the document (sets archived_at); 'restore' undoes it. */
+  operation?: 'create' | 'update' | 'archive' | 'restore';
+}
+
+interface UpsertToolResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseUpsertDocumentResult {
+  upsert: (args: UpsertDocumentArgs) => Promise<DocumentRecord>;
+  loading: boolean;
+  error: Error | null;
+}
+
+function upsertToolName(databaseSlug: string): string {
+  return `LOCAL_NOTIS_DATABASE_UPSERT_${databaseSlug.replace(/-/g, '_').toUpperCase()}`;
+}
+
+function buildToolArgs(args: UpsertDocumentArgs): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  if (args.documentId) payload.document_id = args.documentId;
+  if (typeof args.title === 'string') payload.title = args.title;
+  if (args.properties) Object.assign(payload, args.properties);
+  if ('contentMarkdown' in args) payload.content_markdown = args.contentMarkdown ?? '';
+  if ('contentBlocknote' in args) payload.content_blocknote = args.contentBlocknote ?? null;
+  if (args.operation) payload.operation = args.operation;
+  return payload;
+}
+
+/**
+ * Create/update/archive documents in a Notis database.
+ *
+ * ```tsx
+ * const { upsert } = useUpsertDocument('journal_entries');
+ * await upsert({ documentId, properties: { Mood: 'Great' }, contentMarkdown: reflection });
+ * ```
+ */
+export function useUpsertDocument(databaseSlug: string): UseUpsertDocumentResult {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upsert = useCallback(
+    async (args: UpsertDocumentArgs): Promise<DocumentRecord> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+      if ('contentMarkdown' in args && 'contentBlocknote' in args) {
+        throw new Error('Provide contentMarkdown or contentBlocknote, not both.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool<UpsertToolResult>(
+          upsertToolName(databaseSlug),
+          buildToolArgs(args),
+        );
+        if (!result.document) {
+          throw new Error(result.error ?? result.message ?? 'Failed to save document');
+        }
+        return normalizeDocumentRecord(result.document);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, databaseSlug],
+  );
+
+  return { upsert, loading, error };
+}

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

@@ -0,0 +1,121 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryResult } from './useQuery';
+import { SdkQueryError } from '../queryErrors';
+import type { SpaceDefinition, SpaceShownOptions, SpaceShownResult, SpaceViewParam } from '../space';
+
+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>;
+
+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;
+}
+
+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': {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) return undefined;
+      const parsed = new Date(`${raw}T00:00:00Z`);
+      return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === 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): Omit<ViewParams<Record<string, string | number | boolean>>, 'declared' | 'ready'> {
+  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 view's declared URL params, typed and validated. 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;
+  return useMemo(() => ({ ...parseViewParams(declared, raw), declared: declared || {}, ready: runtime !== null }) as ViewParams<ViewParamsOf<D>>,
+    [declared, raw, runtime]);
+}
+
+export interface UseShownOptions extends SpaceShownOptions {
+  enabled?: boolean;
+  staleTimeMs?: number;
+}
+
+/** 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 } = 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], async () => {
+    if (!runtime?.shown) throw new SdkQueryError('listUnavailable');
+    return runtime.shown<SpaceShownResult & { rows: TRow[] }>(name, params as Record<string, unknown>,
+      { sorts, pageSize, offset, includeContent });
+  }, { 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;
+}