@notis_ai/cli 0.2.0-beta.178.1 → 0.2.0-beta.1792022492092.1

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[] = [];

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

@@ -4,6 +4,8 @@ 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;
@@ -28,6 +30,7 @@ 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,

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

@@ -3,28 +3,49 @@
 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 a document detail view. */
-  toDocument: (documentId: string, title?: string | null) => void;
   /** Navigate to the app's default route. */
   toApp: () => void;
 }
 
 /**
- * Navigation helpers for moving between routes and documents within the app.
+ * 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.toRoute('/settings');
+ * 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 });
@@ -36,17 +57,11 @@ export function useNotisNavigation(): NavigationActions {
     }
   }, [runtime]);
 
-  const toDocument = useCallback((documentId: string, title?: string | null) => {
-    if (runtime?.navigate) {
-      runtime.navigate({ kind: 'document', documentId, title: title ?? undefined });
-    }
-  }, [runtime]);
-
   const toApp = useCallback(() => {
     if (runtime?.navigate) {
       runtime.navigate({ kind: 'app' });
     }
   }, [runtime]);
 
-  return { toRoute, toDocument, toApp };
+  return { toNamedSpace, toSpace, toRoute, toApp };
 }

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

@@ -3,6 +3,8 @@
 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. */
@@ -26,7 +28,7 @@ export function useQuery<T>(key: readonly unknown[], read: () => Promise<T>, opt
   // Older hosts deliberately get a hook-local cache: no cross-runtime/account reuse.
   const fallback = useMemo(() => createQueryClient(), [runtime]);
   const client = runtime?.queryClient ?? fallback;
-  const cacheKey = queryKey(key);
+  const cacheKey = queryKey(spaceQueryKey(runtime, key));
   const enabled = Boolean(runtime) && options.enabled !== false && options.readOnly === true;
   const readRef = useRef(read);
   useLayoutEffect(() => { readRef.current = read; });
@@ -45,12 +47,13 @@ export function useQuery<T>(key: readonly unknown[], read: () => Promise<T>, opt
     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 ? snapshot.error : null,
+    error: enabled ? error : null,
     refetch,
   };
 }
@@ -62,10 +65,10 @@ export function useQueryClient(): {
 } {
   const runtime = useNotisRuntime();
   return useMemo(() => ({
-    invalidate: (key?: readonly unknown[]) => runtime?.queryClient?.invalidate(key ? queryKey(key) : undefined),
+    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(key), read, { staleTimeMs: options.staleTimeMs });
+      return runtime.queryClient.prefetch(queryKey(spaceQueryKey(runtime, key)), read, { staleTimeMs: options.staleTimeMs });
     },
   }), [runtime]);
 }

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

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

@@ -0,0 +1,129 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryResult } from './useQuery';
+import {
+  SPACE_VIEWER_READ_OPERATIONS,
+  type SpaceViewerDatabase,
+  type SpaceViewerReadFamily,
+  type SpaceViewerReadInput,
+  type SpaceViewerReadOperation,
+  type SpaceViewerReadResult,
+  type SpaceViewerSkill,
+} from '../space';
+
+export interface UseViewerReadOptions {
+  enabled?: boolean;
+  staleTimeMs?: number;
+}
+
+// Bounded crawl of the viewer's Skill inventory: 50 pages of 100.
+const MAX_SKILL_PAGES = 50;
+
+/**
+ * True when this page may read what the signed-in viewer can open: the Space declares
+ * `viewerReads` for this family and the host offers it (never on a Site or anonymous link).
+ * Render a fallback when false.
+ */
+export function useViewerReadAvailable(family: SpaceViewerReadFamily): boolean {
+  const runtime = useNotisRuntime();
+  return runtime?.resource?.kind === 'space' && typeof runtime.viewerRead === 'function'
+    && Boolean(runtime.space?.viewerReads?.includes(family));
+}
+
+/** One cached, read-only viewer read. Results are scoped to the current viewer by the host cache scope. */
+export function useViewerRead<TOperation extends SpaceViewerReadOperation>(operation: TOperation,
+  input: SpaceViewerReadInput[TOperation], options: UseViewerReadOptions = {}): UseQueryResult<SpaceViewerReadResult[TOperation]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable(SPACE_VIEWER_READ_OPERATIONS[operation]);
+  return useQuery(['viewer-read', operation, input], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    return runtime.viewerRead<SpaceViewerReadResult[TOperation]>(operation, input as Record<string, unknown>);
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}
+
+/** Every database the signed-in viewer can open, with its available links and read target. */
+export function useViewerDatabases(options: UseViewerReadOptions = {}): UseQueryResult<SpaceViewerDatabase[]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable('databases');
+  return useQuery(['viewer-databases'], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    const result = await runtime.viewerRead<SpaceViewerReadResult['list_databases']>('list_databases', {});
+    if (!Array.isArray(result?.databases)) throw new Error('The database list is incomplete.');
+    return result.databases;
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}
+
+type ListSkillsRead = (input: SpaceViewerReadInput['list_skills']) => Promise<SpaceViewerReadResult['list_skills']>;
+
+// Content pages read at once. Each one holds an API worker while its snapshots are read, and the API
+// has only a few, so a large inventory never takes them all: two pages, plus one quick cursor read.
+export const SKILL_CONTENT_PAGES_AT_ONCE = 2;
+
+/**
+ * Every Skill page, in order. Pages with instructions are slow (each reads its snapshots), so the next
+ * page's cursor comes from a quick read without them and that page starts while the previous one is
+ * still read, at most SKILL_CONTENT_PAGES_AT_ONCE content pages at a time. A cursor that no longer
+ * matches (the list changed meanwhile) drops the pages started from it, waits for them to end and
+ * continues from the real cursor.
+ */
+export async function readAllViewerSkills(read: ListSkillsRead,
+  { includeContent, includeDisabled }: { includeContent: boolean; includeDisabled: boolean }): Promise<SpaceViewerSkill[]> {
+  const page = (after: string | null, content: boolean) => read({ limit: 100, include_content: content,
+    include_disabled: includeDisabled, ...(after ? { after } : {}) }).then(result => {
+    if (!Array.isArray(result?.skills)) throw new Error('The Skill list is incomplete.');
+    return result;
+  });
+  const skills: SpaceViewerSkill[] = [];
+  // The pages started and not read yet, in order, each with the cursor it started from.
+  const started: { after: string | null; result: Promise<SpaceViewerReadResult['list_skills']> }[] = [];
+  // Where the next page to start begins, and whether a quick read (or the last page read) says it exists.
+  let cursor: string | null = null;
+  let known = true;
+  let pages = 0;
+  for (;;) {
+    if (known && started.length < (includeContent ? SKILL_CONTENT_PAGES_AT_ONCE : 1) && pages + started.length < MAX_SKILL_PAGES) {
+      const current = { after: cursor, result: page(cursor, includeContent) };
+      void current.result.catch(() => {});
+      started.push(current);
+      known = false;
+      if (includeContent) {
+        const probe = await page(cursor, false);
+        known = Boolean(probe.has_more && probe.next);
+        cursor = probe.next ?? null;
+      }
+      continue;
+    }
+    const head = started.shift();
+    if (!head) break;
+    const result = await head.result;
+    skills.push(...result.skills);
+    pages += 1;
+    if (!result.has_more || !result.next) return skills;
+    // A page started ahead is kept only when it continues exactly where this one ended; otherwise (and
+    // when none was started) the next page starts from this page's own cursor.
+    if (started[0]?.after !== result.next) {
+      const dropped = started.splice(0);
+      await Promise.allSettled(dropped.map(entry => entry.result));
+      cursor = result.next;
+      known = true;
+    }
+  }
+  throw new Error('This account has more Skills than a page can read at once.');
+}
+
+/**
+ * Every Skill the signed-in viewer can see, all pages. With `includeContent`, `skill_md`
+ * is present where the viewer holds content access and null elsewhere (curated, legacy).
+ */
+export function useViewerSkills(options: UseViewerReadOptions & { includeContent?: boolean; includeDisabled?: boolean } = {}):
+  UseQueryResult<SpaceViewerSkill[]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable('skills');
+  const includeContent = options.includeContent === true, includeDisabled = options.includeDisabled === true;
+  return useQuery(['viewer-skills', includeContent, includeDisabled], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    return readAllViewerSkills((input: SpaceViewerReadInput['list_skills']) => runtime.viewerRead!('list_skills', input),
+      { includeContent, includeDisabled });
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}

package/dist/sdk/src/index.ts

@@ -10,6 +10,28 @@
 export { NotisProvider, useNotisRuntime } from './provider';
 
 // Hooks
+export { useAction, useActionQuery } from './hooks/useAction';
+export { useNativeDocuments, useNativeMutation } from './hooks/useNativeDocuments';
+export type { NativeField, NativeFilter, NativeQuery, NativeInsert, NativeUpdate, NativeDelete, NativeMutationReceipt } from './nativeData';
+export type { SpaceDatabaseCreate, SpaceResourceReference } from './space';
+export type { SpaceActionTemplate, SpaceActionDescriptor, SpaceRuntimeDescriptor, SpaceActionOptions } from './space';
+export type { SpaceDocumentBodyRequest, SpaceDocumentBodyRead, SpaceDocumentBodySave, SpaceDocumentBodyResult } from './space';
+export { useNativeDocumentBody } from './hooks/useNativeDocumentBody';
+export { useViewerRead, useViewerReadAvailable, useViewerDatabases, useViewerSkills } from './hooks/useViewerReads';
+export type { UseViewerReadOptions } from './hooks/useViewerReads';
+export { useViewParams, useShown, useShownAvailable, parseViewParams } from './hooks/useViewParams';
+export type { ViewParams, ViewParamsOf, UseShownOptions } from './hooks/useViewParams';
+export { SPACE_VIEW_SPEC_VERSION } from './space';
+export type { SpaceViewParam, SpaceViewParamType, SpaceShows, SpaceShownDescriptor, SpaceShownOptions, SpaceShownResult,
+  SpaceMemoryPolicy, SpaceMemorySnapshot, SpaceChrome, SpaceMarkdownInput } from './space';
+export { SPACE_VIEWER_READ_OPERATIONS } from './space';
+export { SPACE_CLOUD_COMPUTER_OPERATIONS, spaceCloudComputerAllows } from './space';
+export type { SpaceCloudComputerLevel, SpaceCloudComputerOperation, SpaceCloudComputerStatus, SpaceCloudComputerRelease, SpaceCloudComputerRunInput,
+  SpaceCloudComputerRunResult, SpaceCloudComputerUploadInput, SpaceCloudComputerUploadResult, SpaceCloudComputerTransport } from './space';
+export type { SpaceViewerReadFamily, SpaceViewerReadOperation, SpaceViewerReadInput, SpaceViewerReadResult, SpaceViewerLink,
+  SpaceViewerDatabase, SpaceViewerDatabaseSchema, SpaceViewerSkill, SpaceViewerSkillPage } from './space';
+export { SpaceActionError, SpaceNavigationCancelled, isSpaceNavigationCancelled } from './space';
+export type { SpaceActionFailureDetails } from './space';
 export { useQuery, useQueryClient } from './hooks/useQuery';
 export type { UseQueryOptions, UseQueryResult } from './hooks/useQuery';
 export { createQueryClient, createPrefetchQueue, queryKey } from './queryCache';
@@ -35,6 +57,8 @@ export { useHandover } from './hooks/useHandover';
 export type { UseHandoverResult } from './hooks/useHandover';
 export { useCloudComputer } from './hooks/useCloudComputer';
 export type { UseCloudComputerResult } from './hooks/useCloudComputer';
+export { useCloudComputerShell } from './hooks/useCloudComputerShell';
+export type { UseCloudComputerShellResult } from './hooks/useCloudComputerShell';
 export { useNotisNavigation } from './hooks/useNotisNavigation';
 export { useTopBarSearch } from './hooks/useTopBarSearch';
 export { useBackend } from './hooks/useBackend';
@@ -53,6 +77,9 @@ export {
 export { Markdown } from './components/Markdown';
 export type { MarkdownProps } from './components/Markdown';
 export { DocumentEditor } from './components/DocumentEditor';
+export { DocumentPage, DocumentPageSkeleton, usePrefetchRecord } from './components/DocumentPage';
+export { RecordProperties, HtmlFrame, ReportFrame, ShareControl } from './components/RecordComponents';
+export { RenderChartData } from './components/RenderChartData';
 export { MarkdownEditor } from './components/MarkdownEditor';
 export { NotisSelectionBoundary, NOTIS_CONTEXT_CLIPBOARD_TYPE } from './components/NotisSelectionBoundary';
 export type { NotisSelectionBoundaryProps } from './components/NotisSelectionBoundary';
@@ -135,6 +162,15 @@ export type {
   HandoverPayload,
   HandoverResult,
   NotisDocumentEditorProps,
+  NotisDocumentPageProps,
+  NotisDocumentPageCrumb,
+  NotisDocumentPageMenuItem,
+  NotisDocumentPageParts,
+  NotisRecordProps,
+  NotisRecordPropertiesProps,
+  NotisHtmlFrameProps,
+  NotisReportFrameProps,
+  NotisShareControlProps,
   NotisMarkdownEditorProps,
   NotisMarkdownEditorSavePayload,
   NotisMarkdownEditorSaveResult,

package/dist/sdk/src/interactions/shortcuts.tsx

@@ -5,11 +5,13 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type ReactNode,
 } from 'react';
+import { isInteractionElementVisible } from './visibility';
 
 export type ShortcutScope = 'app' | 'route' | 'collection' | 'detail' | 'modal';
 
@@ -195,7 +197,8 @@ export function isEditableShortcutEvent(event: Event): boolean {
       return true;
     }
     if (tag === 'A' && target.hasAttribute('href')) return true;
-    return ['button', 'link', 'menuitem', 'switch', 'tab'].includes(
+    // A focused separator (a resizable edge) owns its arrow keys.
+    return ['button', 'link', 'menuitem', 'separator', 'switch', 'tab'].includes(
       target.getAttribute('role') || '',
     );
   });
@@ -215,6 +218,25 @@ function consumeShortcut(event: KeyboardEvent, definition: ShortcutDefinition):
   void definition.onTrigger(event);
 }
 
+// Apps built before collections stopped binding Escape to an empty selection
+// still register it, which swallows Escape for nothing. With collection items
+// rendered and none selected, leave Escape to the enclosing surface (the Portal
+// closes its frontmost layer, then returns to Inbox).
+function isEmptyCollectionClear(shortcut: ShortcutDefinition, ownerDocument: Document, event: KeyboardEvent): boolean {
+  if (event.key !== 'Escape' || shortcut.id !== 'collection.clear') return false;
+  const items = collectionItems(ownerDocument).filter((item) => isInteractionElementVisible(item as HTMLElement));
+  return items.length > 0 && !items.some((item) => item.getAttribute('aria-selected') === 'true');
+}
+
+/** App views render in open shadow roots, which document queries do not enter. */
+function collectionItems(root: Document | ShadowRoot): Element[] {
+  const items = Array.from(root.querySelectorAll('[data-notis-collection-item-id], [data-notis-row-id]'));
+  for (const element of Array.from(root.querySelectorAll('*'))) {
+    if (element.shadowRoot) items.push(...collectionItems(element.shadowRoot));
+  }
+  return items;
+}
+
 // Native dialogs make the background inert, but document capture listeners still
 // receive their keyboard events. Leave those events to the dialog and its controls.
 function isDialogEvent(event: KeyboardEvent): boolean {
@@ -223,10 +245,10 @@ function isDialogEvent(event: KeyboardEvent): boolean {
   );
 }
 
-export function ShortcutProvider({ children }: { children: ReactNode }) {
+export function ShortcutProvider({ children, isAvailable }: { children: ReactNode; isAvailable?: () => boolean }) {
   const parentRegistry = useContext(ShortcutContext);
   if (parentRegistry) return <>{children}</>;
-  return <ShortcutProviderRoot>{children}</ShortcutProviderRoot>;
+  return <ShortcutProviderRoot isAvailable={isAvailable}>{children}</ShortcutProviderRoot>;
 }
 
 export interface ShortcutHelpEntry {
@@ -293,7 +315,8 @@ function registerFallbackShortcut(input: Omit<ShortcutRegistration, 'id' | 'orde
         const token = chordToken(eventChord(event));
         for (const registration of applicableRegistrations(registrations.values())) {
           for (const shortcut of registration.getShortcuts()) {
-            if (shortcut.enabled === false || (editable && !shortcut.allowInEditable) || (event.repeat && !shortcut.allowRepeat)) continue;
+            if (shortcut.enabled === false || (editable && !shortcut.allowInEditable) || (event.repeat && !shortcut.allowRepeat)
+              || isEmptyCollectionClear(shortcut, ownerDocument, event)) continue;
             const match = parseShortcut(shortcut).some(
               (candidate) => candidate.sequence.length === 1 && chordToken(candidate.sequence[0]!) === token,
             );
@@ -348,7 +371,7 @@ function collectShortcutHelpEntries(
   return entries;
 }
 
-function ShortcutProviderRoot({ children }: { children: ReactNode }) {
+function ShortcutProviderRoot({ children, isAvailable }: { children: ReactNode; isAvailable?: () => boolean }) {
   const registrationsRef = useRef(new Map<number, ShortcutRegistration>());
   const nextIdRef = useRef(1);
   const nextOrderRef = useRef(1);
@@ -356,12 +379,21 @@ function ShortcutProviderRoot({ children }: { children: ReactNode }) {
   const [helpOpen, setHelpOpen] = useState(false);
   const helpOpenRef = useRef(false);
   const [, setRegistryVersion] = useState(0);
+  const availabilityRef = useRef(isAvailable);
 
   const updateHelpOpen = useCallback((open: boolean) => {
     helpOpenRef.current = open;
     setHelpOpen(open);
   }, []);
 
+  useLayoutEffect(() => {
+    availabilityRef.current = isAvailable;
+    if (isAvailable?.() === false) {
+      sequenceRef.current = { chords: [], at: 0 };
+      updateHelpOpen(false);
+    }
+  }, [isAvailable, updateHelpOpen]);
+
   const register = useCallback((input: Omit<ShortcutRegistration, 'id' | 'order'>) => {
     const id = nextIdRef.current++;
     registrationsRef.current.set(id, {
@@ -378,6 +410,10 @@ function ShortcutProviderRoot({ children }: { children: ReactNode }) {
 
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
+      if (availabilityRef.current?.() === false) {
+        sequenceRef.current = { chords: [], at: 0 };
+        return;
+      }
       if (event.defaultPrevented || isDialogEvent(event)) return;
       const editable = isEditableShortcutEvent(event);
       if (!editable && !event.repeat && event.key === '?' && !event.metaKey && !event.ctrlKey && !event.altKey) {
@@ -407,6 +443,7 @@ function ShortcutProviderRoot({ children }: { children: ReactNode }) {
           .filter((shortcut) => shortcut.enabled !== false)
           .filter((shortcut) => !editable || shortcut.allowInEditable)
           .filter((shortcut) => !event.repeat || shortcut.allowRepeat)
+          .filter((shortcut) => !isEmptyCollectionClear(shortcut, document, event))
           .flatMap(parseShortcut);
         if (candidates.length === 0) continue;