@notis_ai/cli 0.2.17 → 0.2.19

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/{template/packages → dist}/sdk/src/index.ts

@@ -10,6 +10,32 @@
 export { NotisProvider, useNotisRuntime } from './provider';
 
 // Hooks
+export { useAction, useActionQuery } from './hooks/useAction';
+export { useNativeDocuments, useNativeMutation, useNativeDelete, type NativeDeleteManyResult } 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, ViewParamChanges, SetViewParamsOptions, UseShownOptions } from './hooks/useViewParams';
+export { SPACE_VIEW_SPEC_VERSION } from './space';
+export type { SpaceViewParam, SpaceViewParamType, SpaceViewFilter, 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';
+export type { NotisQueryClient, QuerySnapshot, QueryFetchOptions, HiddenRecords } from './queryCache';
 export { useNotis } from './hooks/useNotis';
 export { useDocuments } from './hooks/useDocuments';
 export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
@@ -31,14 +57,18 @@ 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 { useTopBarTitleLeaf } from './hooks/useTopBarTitleLeaf';
 export { useBackend } from './hooks/useBackend';
 export { useMultiSelect } from './hooks/useMultiSelect';
 export { useCollectionInteractions, COLLECTION_ITEM_ATTRIBUTE } from './hooks/useCollectionInteractions';
 export { useActiveResource } from './hooks/useActiveResource';
+// ShortcutProvider is not exported here (D2): NotisProvider mounts it for every app; hosts take it from
+// '@notis/sdk/interactions'.
 export {
-  ShortcutProvider,
   SHORTCUT_SCOPE_PRIORITY,
   isEditableShortcutEvent,
   shortcutDisplay,
@@ -49,12 +79,16 @@ 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, SpacePageFrame } from './components/RecordComponents';
+export { RenderChartData } from './ui/charts/RenderChartData';
 export { MarkdownEditor } from './components/MarkdownEditor';
 export { NotisSelectionBoundary, NOTIS_CONTEXT_CLIPBOARD_TYPE } from './components/NotisSelectionBoundary';
 export type { NotisSelectionBoundaryProps } from './components/NotisSelectionBoundary';
 export {
   asRecord,
   blockNoteToPlainText,
+  DOCUMENT_WORDS,
   extractRichText,
   getDocumentPreview,
   getRelationIds,
@@ -66,8 +100,11 @@ export {
   normalizePropertyValue,
   optionalString,
 } from './documents';
+export type { DocumentWordsOptions } from './documents';
 
 // Multi-select components
+export { Dialog } from './components/Dialog';
+export type { DialogProps } from './components/Dialog';
 export { MultiSelectActionBar } from './components/MultiSelectActionBar';
 export { MultiSelectCheckbox, MultiSelectCheckbox as SelectionCheckbox } from './components/MultiSelectCheckbox';
 export { MultiSelectDragOverlay, MultiSelectDragOverlay as SelectionMarquee } from './components/MultiSelectDragOverlay';
@@ -129,10 +166,22 @@ export type {
   HandoverPayload,
   HandoverResult,
   NotisDocumentEditorProps,
+  NotisDocumentPageProps,
+  NotisDocumentPageCrumb,
+  NotisDocumentPageMenuItem,
+  NotisDocumentPageParts,
+  NotisRecordProps,
+  NotisRecordPropertiesProps,
+  NotisHtmlFrameProps,
+  NotisHtmlFramePresentAction,
+  NotisReportFrameProps,
+  NotisShareControlProps,
+  NotisSpacePageFrameProps,
   NotisMarkdownEditorProps,
   NotisMarkdownEditorSavePayload,
   NotisMarkdownEditorSaveResult,
   NotisRuntime,
+  RuntimeResource,
   NotisRuntimeContext,
   NotisRuntimeUI,
   QueryFilter,
@@ -143,3 +192,17 @@ export type {
   ToolCallOptions,
   ToolInputSchema,
 } from './runtime';
+
+export { useToolQuery } from './hooks/useToolQuery';
+
+export { Skeleton, SKELETON_WORDS, ViewSkeleton } from './components/Skeleton';
+
+export { useLongPressSelection } from './hooks/useLongPressSelection';
+export { isInteractionElementVisible } from './interactions/visibility';
+
+export type { AgentContextContent, AgentContextItem, ContextAttachment } from './agentContext';
+export { useAgentContext } from './hooks/useAgentContext';
+export { NotisCommentBoundary, NotisCommentBox } from './components/NotisCommentBoundary';
+export type { NotisCommentBoundaryProps, NotisCommentBoxProps } from './components/NotisCommentBoundary';
+export { VIEW_PERIODS, isViewDate, isViewPeriod, resolveViewPeriod } from './viewPeriod';
+export { journalViewParams, tasksViewParams, tasksViewFilter } from './standardViewParams';

package/{template/packages → dist}/sdk/src/interactions/actions.ts

@@ -1,6 +1,10 @@
 import type { ReactNode } from 'react';
 
-export type CollectionActionIntent = 'archive' | 'star' | 'delete' | 'custom';
+export type CollectionActionIntent =
+  | 'archive' | 'star' | 'delete'
+  | 'enable' | 'disable' | 'pause' | 'resume'
+  | 'move' | 'add-to-folder' | 'complete' | 'start-progress'
+  | 'custom';
 
 export interface CollectionActionContext<T> {
   selectedIds: string[];
@@ -13,6 +17,7 @@ export interface CollectionAction<T> {
   intent?: CollectionActionIntent;
   label?: string;
   icon?: ReactNode;
+  /** Omit to use the intent default, supply a key to override, or false to remove it. */
   shortcut?: string | false;
   destructive?: boolean;
   disabled?: boolean | ((context: CollectionActionContext<T>) => boolean);
@@ -35,6 +40,14 @@ const ACTION_DEFAULTS: Record<Exclude<CollectionActionIntent, 'custom'>, { label
   archive: { label: 'Archive', shortcut: 'E' },
   star: { label: 'Star', shortcut: 'S' },
   delete: { label: 'Delete', shortcut: '#' },
+  enable: { label: 'Enable', shortcut: 'E' },
+  disable: { label: 'Disable', shortcut: 'D' },
+  pause: { label: 'Pause', shortcut: 'P' },
+  resume: { label: 'Resume', shortcut: 'R' },
+  move: { label: 'Move', shortcut: 'M' },
+  'add-to-folder': { label: 'Add to folder', shortcut: 'F' },
+  complete: { label: 'Mark complete', shortcut: 'C' },
+  'start-progress': { label: 'Start progress', shortcut: 'P' },
 };
 
 export function collectionActionDefaults(intent: CollectionActionIntent | undefined): {

package/{template/packages → 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';
 
@@ -42,6 +44,8 @@ export interface UseShortcutsOptions {
   sequenceTimeoutMs?: number;
   /** Internal owner used to route collection shortcuts to the last interacted collection. */
   collectionOwnerId?: string;
+  /** Evaluated at dispatch time, including for retained hidden app views. */
+  isAvailable?: () => boolean;
 }
 
 interface ShortcutRegistration {
@@ -52,6 +56,8 @@ interface ShortcutRegistration {
   enabled: boolean;
   sequenceTimeoutMs: number;
   collectionOwnerId?: string;
+  /** Evaluated at dispatch time, including for retained hidden app views. */
+  isAvailable?: () => boolean;
   getShortcuts: () => ShortcutDefinition[];
 }
 
@@ -92,6 +98,11 @@ export function createShortcutCollectionOwner(): string {
   return `collection-${state.nextOwnerId++}`;
 }
 
+export function releaseShortcutCollection(ownerId: string): void {
+  const state = getShortcutCollectionState();
+  if (state.activeOwnerId === ownerId) state.activeOwnerId = null;
+}
+
 export function activateShortcutCollection(ownerId: string): void {
   getShortcutCollectionState().activeOwnerId = ownerId;
 }
@@ -186,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') || '',
     );
   });
@@ -206,10 +218,37 @@ function consumeShortcut(event: KeyboardEvent, definition: ShortcutDefinition):
   void definition.onTrigger(event);
 }
 
-export function ShortcutProvider({ children }: { children: ReactNode }) {
+// 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 {
+  return event.composedPath().some((target) =>
+    target instanceof HTMLElement && target.matches('dialog.notis-dialog[open]'),
+  );
+}
+
+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 {
@@ -233,7 +272,7 @@ function applicableRegistrations(
   registrations: Iterable<ShortcutRegistration>,
 ): ShortcutRegistration[] {
   const ordered = Array.from(registrations)
-    .filter((registration) => registration.enabled)
+    .filter((registration) => registration.enabled && registration.isAvailable?.() !== false)
     .sort((a, b) => b.priority - a.priority || b.order - a.order);
   const activeCollectionOwner = getShortcutCollectionState().activeOwnerId;
   const hasActiveCollection = Boolean(
@@ -248,6 +287,61 @@ function applicableRegistrations(
     : ordered;
 }
 
+// Standalone app verification and legacy hosts may not install a provider.
+// They must still arbitrate shortcuts together, not by effect/listener order.
+const FALLBACK_REGISTRIES_SYMBOL = Symbol.for('notis.sdk.fallback_shortcut_registries');
+interface FallbackShortcutRegistry {
+  registrations: Map<number, ShortcutRegistration>;
+  nextId: number;
+  dispatch: (event: KeyboardEvent) => void;
+}
+type FallbackShortcutGlobal = typeof globalThis & {
+  [FALLBACK_REGISTRIES_SYMBOL]?: WeakMap<Document, FallbackShortcutRegistry>;
+};
+
+function registerFallbackShortcut(input: Omit<ShortcutRegistration, 'id' | 'order'>): () => void {
+  const scope = globalThis as FallbackShortcutGlobal;
+  const registries = scope[FALLBACK_REGISTRIES_SYMBOL] ??= new WeakMap();
+  const ownerDocument = document;
+  let registry = registries.get(ownerDocument);
+  if (!registry) {
+    const registrations = new Map<number, ShortcutRegistration>();
+    registry = {
+      registrations,
+      nextId: 1,
+      dispatch: (event) => {
+        if (event.defaultPrevented || isDialogEvent(event)) return;
+        const editable = isEditableShortcutEvent(event);
+        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)
+              || isEmptyCollectionClear(shortcut, ownerDocument, event)) continue;
+            const match = parseShortcut(shortcut).some(
+              (candidate) => candidate.sequence.length === 1 && chordToken(candidate.sequence[0]!) === token,
+            );
+            if (match) {
+              consumeShortcut(event, shortcut);
+              return;
+            }
+          }
+        }
+      },
+    };
+    registries.set(ownerDocument, registry);
+    ownerDocument.addEventListener('keydown', registry.dispatch, true);
+  }
+  const id = registry.nextId++;
+  registry.registrations.set(id, { ...input, id, order: id });
+  return () => {
+    registry.registrations.delete(id);
+    if (registry.registrations.size === 0) {
+      ownerDocument.removeEventListener('keydown', registry.dispatch, true);
+      registries.delete(ownerDocument);
+    }
+  };
+}
+
 function shortcutToken(raw: string): string | null {
   const definition: ShortcutDefinition = { id: '', keys: raw, onTrigger: () => undefined };
   const parsed = parseShortcut(definition)[0];
@@ -277,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);
@@ -285,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, {
@@ -307,6 +410,11 @@ 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) {
         event.preventDefault();
@@ -335,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;
 
@@ -575,7 +684,10 @@ export function useShortcuts(
     priority = 0,
     sequenceTimeoutMs = 1500,
     collectionOwnerId,
+    isAvailable,
   } = options;
+  const availableRef = useRef(isAvailable);
+  availableRef.current = isAvailable;
 
   useEffect(() => {
     if (!registry || !enabled) return;
@@ -585,30 +697,24 @@ export function useShortcuts(
       priority: SHORTCUT_SCOPE_PRIORITY[scope] + priority,
       sequenceTimeoutMs,
       collectionOwnerId,
-      getShortcuts: () => shortcutsRef.current,
+      isAvailable: () => availableRef.current?.() !== false,
+      getShortcuts: () => availableRef.current?.() === false ? [] : shortcutsRef.current,
     });
   }, [collectionOwnerId, enabled, priority, registry, scope, sequenceTimeoutMs]);
 
   // Compatibility fallback for SDK components rendered outside a provider.
   useEffect(() => {
     if (registry || !enabled) return;
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEditableShortcutEvent(event)) return;
-      const token = chordToken(eventChord(event));
-      for (const shortcut of shortcutsRef.current) {
-        if (shortcut.enabled === false || event.repeat && !shortcut.allowRepeat) continue;
-        const match = parseShortcut(shortcut).find(
-          (candidate) => candidate.sequence.length === 1 && chordToken(candidate.sequence[0]!) === token,
-        );
-        if (match) {
-          consumeShortcut(event, shortcut);
-          return;
-        }
-      }
-    };
-    document.addEventListener('keydown', handleKeyDown, true);
-    return () => document.removeEventListener('keydown', handleKeyDown, true);
-  }, [enabled, registry]);
+    return registerFallbackShortcut({
+      enabled,
+      scope,
+      priority: SHORTCUT_SCOPE_PRIORITY[scope] + priority,
+      sequenceTimeoutMs,
+      collectionOwnerId,
+      isAvailable: () => availableRef.current?.() !== false,
+      getShortcuts: () => shortcutsRef.current,
+    });
+  }, [collectionOwnerId, enabled, priority, registry, scope, sequenceTimeoutMs]);
 }
 
 export function shortcutDisplay(raw: string): string {

package/dist/sdk/src/interactions/visibility.ts

@@ -0,0 +1,13 @@
+/** Visibility across light and Shadow DOM, without relying on layout (virtual rows may have no rect). */
+export function isInteractionElementVisible(element: HTMLElement | null): boolean {
+  if (!element?.isConnected) return false;
+  let current: Element | null = element;
+  while (current) {
+    if (current.hasAttribute('hidden') || current.hasAttribute('inert') || current.getAttribute('aria-hidden') === 'true') return false;
+    const style = current.ownerDocument.defaultView?.getComputedStyle(current);
+    if (style?.display === 'none' || style?.visibility === 'hidden') return false;
+    const root: Node = current.getRootNode();
+    current = current.parentElement ?? ('host' in root ? (root as ShadowRoot).host : null);
+  }
+  return true;
+}

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

@@ -29,7 +29,8 @@ export type {
   SelectionMarqueeRect,
   UseCollectionInteractionsOptions,
 } from './hooks/useCollectionInteractions';
-export { MultiSelectActionBar } from './components/MultiSelectActionBar';
+export { MultiSelectActionBar, BULK_ACTION_LAYOUT_EVENT } from './components/MultiSelectActionBar';
+export type { BulkActionLayoutDetail } from './components/MultiSelectActionBar';
 export { MultiSelectCheckbox, MultiSelectCheckbox as SelectionCheckbox } from './components/MultiSelectCheckbox';
 export { MultiSelectDragOverlay, MultiSelectDragOverlay as SelectionMarquee } from './components/MultiSelectDragOverlay';
 export { ShortcutHints } from './components/ShortcutHints';
@@ -39,3 +40,6 @@ export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOv
 export type { MultiSelectCheckboxProps as SelectionCheckboxProps } from './components/MultiSelectCheckbox';
 export type { MultiSelectDragOverlayProps as SelectionMarqueeProps } from './components/MultiSelectDragOverlay';
 export type { ShortcutHint, ShortcutHintsProps } from './components/ShortcutHints';
+
+export { useLongPressSelection } from './hooks/useLongPressSelection';
+export { isInteractionElementVisible } from './interactions/visibility';

package/dist/sdk/src/nativeData.ts

@@ -0,0 +1,39 @@
+/** The native row contract, shared by direct tools and scoped Space actions. */
+export type NativeField = { property_id: string } | { property: string } | {
+  column: 'record_key' | 'id' | 'title' | 'created_at' | 'updated_at' | 'last_edited_time' | 'content_type' | 'file_type';
+};
+export type NativeFilter = { and: NativeFilter[] } | { or: NativeFilter[] } | {
+  field: NativeField;
+  op: 'equals' | 'not_equals' | 'in' | 'contains' | 'not_contains' | 'does_not_contain'
+    | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty' | 'greater_than' | 'less_than'
+    | 'greater_than_or_equal_to' | 'less_than_or_equal_to' | 'before' | 'after' | 'on_or_before' | 'on_or_after';
+  value?: unknown;
+};
+export interface NativeQuery {
+  include_content?: boolean;
+  include_archived?: boolean;
+  mode?: 'rows' | 'search' | 'count' | 'aggregate';
+  filter?: NativeFilter;
+  sorts?: Array<{ field: NativeField; direction: 'asc' | 'desc' }>;
+  search?: { text: string; fields: NativeField[] };
+  aggregate?: { op: 'sum' | 'avg' | 'min' | 'max'; field: NativeField };
+  page_size?: number;
+  offset?: number;
+}
+export interface NativeInsert {
+  columns?: { title?: string | null; icon?: string | null; cover?: string | null };
+  properties?: Record<string, unknown>;
+  body?: { blocks: Array<Record<string, unknown>> };
+}
+export interface NativeUpdate extends NativeInsert { record_key: string; expected_revision: number; }
+export interface NativeDelete { record_key: string; expected_revision: number; }
+export interface NativeMutationReceipt {
+  record_key: string;
+  id: string;
+  database_id: string;
+  revision: number;
+  schema_revision: number;
+  receipt_id: string;
+  operation: 'insert' | 'update' | 'delete';
+  replayed?: boolean;
+}

package/{template/packages → dist}/sdk/src/provider.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import React, { createContext, useContext, type Context, type ReactNode } from 'react';
+import React, { createContext, useContext, useMemo, type Context, type ReactNode } from 'react';
 import type { NotisRuntime } from './runtime';
 import { ShortcutProvider } from './interactions/shortcuts';
+import { guardSpaceRuntime } from './space';
 
 const NOTIS_CONTEXT_SYMBOL = Symbol.for('notis.sdk.runtime_context');
 
@@ -24,13 +25,17 @@ const NotisContext = getNotisContext();
  * Provides the Notis runtime context to all child components. The portal owns
  * the runtime and injects it into the rendered app tree.
  */
-export function NotisProvider({ children, runtime }: { children: ReactNode; runtime: NotisRuntime | null }) {
+export function NotisProvider({ children, runtime, onProtocolError, shortcutsAvailable }: {
+  children: ReactNode; runtime: NotisRuntime | null; onProtocolError?: (error: Error) => void;
+  shortcutsAvailable?: () => boolean;
+}) {
+  const scopedRuntime = useMemo(() => guardSpaceRuntime(runtime, onProtocolError), [runtime, onProtocolError]);
   if (runtime === undefined) {
     throw new Error('NotisProvider requires an explicit runtime prop.');
   }
   return (
-    <NotisContext.Provider value={runtime}>
-      <ShortcutProvider>{children}</ShortcutProvider>
+    <NotisContext.Provider value={scopedRuntime}>
+      <ShortcutProvider isAvailable={shortcutsAvailable}>{children}</ShortcutProvider>
     </NotisContext.Provider>
   );
 }