@notis_ai/cli 0.2.18 → 0.2.19

package/dist/space-sdk/src/hooks/useTopBarSearch.d.ts

@@ -0,0 +1,48 @@
+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.
+ *
+ * The top bar owns what is typed in it. A `value` that came from the bar is
+ * not sent back: the view's answer can arrive after the next key, and sending
+ * it back would undo that key. A value the view sets itself (a clear button,
+ * a link, a value it trims) is sent to the bar.
+ */
+export declare function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions;
+export {};

package/dist/space-sdk/src/hooks/useTopBarTitleLeaf.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Adds the open record's label as the last crumb of the Portal top bar title
+ * ("Product / Tickets / PRO-002") while the component is mounted. Pass `null`
+ * when no record is open: the component then owns no leaf and leaves another
+ * component's leaf alone. With several owners, the most recently opened one
+ * names the leaf; closing it gives the leaf back to the one before.
+ *
+ * `onBack` closes the record: the crumb before the leaf (the view) then calls it,
+ * so the top bar is the page's way back and the page draws no breadcrumb of its own.
+ *
+ * `recordKey` names the record the leaf shows, when it is a record of the Space's own
+ * collection (its `collection` database): its Editors can then rename that record from
+ * the leaf in the top bar, and the view shows the new name once its data refreshes.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * useTopBarTitleLeaf(openTicket ? openTicket.key : null, () => setParams({ ticket: null }));
+ * useTopBarTitleLeaf(deck ? deck.name : null, undefined, { recordKey: deck?.recordKey });
+ * ```
+ */
+export declare function useTopBarTitleLeaf(label: string | null, onBack?: () => void, options?: {
+    recordKey?: string | null;
+}): void;

package/dist/space-sdk/src/hooks/useUpsertDocument.d.ts

@@ -0,0 +1,27 @@
+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';
+}
+export interface UseUpsertDocumentResult {
+    upsert: (args: UpsertDocumentArgs) => Promise<DocumentRecord>;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Create/update/archive documents in a Notis database.
+ *
+ * ```tsx
+ * const { upsert } = useUpsertDocument('journal_entries');
+ * await upsert({ documentId, properties: { Mood: 'Great' }, contentMarkdown: reflection });
+ * ```
+ */
+export declare function useUpsertDocument(databaseSlug: string): UseUpsertDocumentResult;

package/dist/space-sdk/src/hooks/useViewParams.d.ts

@@ -0,0 +1,76 @@
+import type { NotisRuntime } from '../runtime';
+import { type UseQueryResult } from './useQuery';
+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>;
+/** A change to the view's URL params: a value sets that param, null or undefined removes it. */
+export type ViewParamChanges<T> = {
+    [K in keyof T]?: T[K] | null;
+};
+export interface SetViewParamsOptions {
+    /** Replace the current history entry instead of adding one, so Back skips this change. Default false. */
+    replace?: boolean;
+}
+export interface ViewParams<T> {
+    /** Declared params only, typed; invalid URL values are left out (their default applies). */
+    params: T;
+    /** Declared params whose URL value was invalid and ignored. */
+    invalid: string[];
+    /** Required params without a value. */
+    missing: string[];
+    declared: Record<string, SpaceViewParam>;
+    ready: boolean;
+    /**
+     * Change this view's own URL params; the same Space and record stay open. Names left out of `changes` keep their
+     * value. No destination lookup and no alias to declare: use `useNotisNavigation().toNamedSpace` for another Space.
+     * Undeclared names are dropped by the host. Rejects outside a Space.
+     */
+    setParams: (changes: ViewParamChanges<T>, options?: SetViewParamsOptions) => Promise<void>;
+}
+/** Keep declared, valid values only; unknown params are dropped and defaults applied. */
+export declare function parseViewParams(declared: Record<string, SpaceViewParam> | undefined, raw: Record<string, string> | null | undefined): Pick<ViewParams<Record<string, string | number | boolean>>, 'params' | 'invalid' | 'missing'>;
+/**
+ * Write the open Space's own URL params (`setParams` of useViewParams; the toolkit's open item and period use it).
+ * The host keeps the Space and record, checks no destination, and adds a history entry unless `replace` is set.
+ */
+export declare function writeViewParams(runtime: NotisRuntime | null | undefined, changes: Record<string, unknown>, options?: SetViewParamsOptions): Promise<void>;
+/**
+ * The view's declared URL params, typed and validated, and `setParams` to change them. Unknown params (such as
+ * `?foo=`) never reach the view. Record params are record keys; the server authorizes them where it uses them.
+ */
+export declare function useViewParams<D extends Pick<SpaceDefinition, 'params'> = SpaceDefinition>(): ViewParams<ViewParamsOf<D>>;
+export interface UseShownOptions extends SpaceShownOptions {
+    enabled?: boolean;
+    staleTimeMs?: number;
+    /**
+     * Read every page and answer with all rows: pages of `pageSize` (default 200) are read from `offset` until one
+     * comes back short, up to `SHOWN_ALL_PAGES_MAX` pages.
+     */
+    allPages?: boolean;
+}
+/** The most pages `useShown({ allPages: true })` reads. */
+export declare const SHOWN_ALL_PAGES_MAX = 50;
+/** True when a declared list has an authorized host reader (Editor or exact record Site). */
+export declare function useShownAvailable(name: string): boolean;
+/**
+ * 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 declare function useShown<TRow = Record<string, unknown>>(name: string, options?: UseShownOptions): UseQueryResult<SpaceShownResult & {
+    rows: TRow[];
+}>;
+export {};

package/dist/space-sdk/src/hooks/useViewerReads.d.ts

@@ -0,0 +1,38 @@
+import { type UseQueryResult } from './useQuery';
+import { type SpaceViewerDatabase, type SpaceViewerReadFamily, type SpaceViewerReadInput, type SpaceViewerReadOperation, type SpaceViewerReadResult, type SpaceViewerSkill } from '../space';
+export interface UseViewerReadOptions {
+    enabled?: boolean;
+    staleTimeMs?: number;
+}
+/**
+ * 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 declare function useViewerReadAvailable(family: SpaceViewerReadFamily): boolean;
+/** One cached, read-only viewer read. Results are scoped to the current viewer by the host cache scope. */
+export declare function useViewerRead<TOperation extends SpaceViewerReadOperation>(operation: TOperation, input: SpaceViewerReadInput[TOperation], options?: UseViewerReadOptions): UseQueryResult<SpaceViewerReadResult[TOperation]>;
+/** Every database the signed-in viewer can open, with its available links and read target. */
+export declare function useViewerDatabases(options?: UseViewerReadOptions): UseQueryResult<SpaceViewerDatabase[]>;
+type ListSkillsRead = (input: SpaceViewerReadInput['list_skills']) => Promise<SpaceViewerReadResult['list_skills']>;
+export declare 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 declare function readAllViewerSkills(read: ListSkillsRead, { includeContent, includeDisabled }: {
+    includeContent: boolean;
+    includeDisabled: boolean;
+}): Promise<SpaceViewerSkill[]>;
+/**
+ * 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 declare function useViewerSkills(options?: UseViewerReadOptions & {
+    includeContent?: boolean;
+    includeDisabled?: boolean;
+}): UseQueryResult<SpaceViewerSkill[]>;
+export {};

package/dist/space-sdk/src/index.d.ts

@@ -0,0 +1,98 @@
+/// <reference path="./tailwind-candidates.d.ts" />
+/**
+ * @notis/sdk - The Notis App SDK
+ *
+ * Public API for building Notis apps. Import hooks and the provider from
+ * this entrypoint. For configuration, use `@notis/sdk/config`. For the
+ * Vite config builder, use `@notis/sdk/vite`.
+ */
+export { NotisProvider, useNotisRuntime } from './provider';
+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';
+export { useDatabaseSubscription } from './hooks/useDatabaseSubscription';
+export type { UseDatabaseSubscriptionOptions, UseDatabaseSubscriptionResult, } from './hooks/useDatabaseSubscription';
+export { useDocument } from './hooks/useDocument';
+export type { UseDocumentOptions, UseDocumentResult } from './hooks/useDocument';
+export { useUpsertDocument } from './hooks/useUpsertDocument';
+export type { UpsertDocumentArgs, UseUpsertDocumentResult } from './hooks/useUpsertDocument';
+export { useDatabaseSchema } from './hooks/useDatabaseSchema';
+export type { UseDatabaseSchemaResult } from './hooks/useDatabaseSchema';
+export { useTool } from './hooks/useTool';
+export type { ToolCallState, UseToolResult } from './hooks/useTool';
+export { useTools } from './hooks/useTools';
+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';
+export { SHORTCUT_SCOPE_PRIORITY, isEditableShortcutEvent, shortcutDisplay, useShortcuts, } from './interactions/shortcuts';
+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, getSecretValue, isPresentString, markdownToPlainText, normalizeDatabaseProperty, normalizeDocumentRecord, normalizePropertyValue, optionalString, } from './documents';
+export type { DocumentWordsOptions } from './documents';
+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';
+export { ShortcutHints } from './components/ShortcutHints';
+export type { DragRect, MultiSelectController, UseMultiSelectOptions, } from './hooks/useMultiSelect';
+export type { MultiSelectAction, MultiSelectActionBarProps, } from './components/MultiSelectActionBar';
+export type { MultiSelectCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOverlay';
+export type { MultiSelectCheckboxProps as SelectionCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps as SelectionMarqueeProps } from './components/MultiSelectDragOverlay';
+export type { ShortcutHint, ShortcutHintsProps } from './components/ShortcutHints';
+export type { CollectionInteractionController, CollectionInteractionReason, CollectionKeyboardShortcuts, CollectionNavigationContext, CollectionNavigationDirection, CollectionSelectionChange, SelectionMarqueeRect, UseCollectionInteractionsOptions, } from './hooks/useCollectionInteractions';
+export type { ShortcutDefinition, ShortcutHelpEntry, ShortcutScope, UseShortcutsOptions, } from './interactions/shortcuts';
+export type { CollectionAction, CollectionActionContext, CollectionActionIntent, ResolvedCollectionAction, } from './interactions/actions';
+export type { AppDescriptor, CloudComputerCliAuthFacts, CloudComputerFacts, CloudComputerSandboxFacts, ContextAttributeValue, ContextResource, ContextSelection, CollectionItem, CollectionItemDetail, DatabaseDescriptor, DatabaseProperty, DatabasePropertyOption, DatabasePropertyType, DocumentContentType, DocumentRecord, HandoverPayload, HandoverResult, NotisDocumentEditorProps, NotisDocumentPageProps, NotisDocumentPageCrumb, NotisDocumentPageMenuItem, NotisDocumentPageParts, NotisRecordProps, NotisRecordPropertiesProps, NotisHtmlFrameProps, NotisHtmlFramePresentAction, NotisReportFrameProps, NotisShareControlProps, NotisSpacePageFrameProps, NotisMarkdownEditorProps, NotisMarkdownEditorSavePayload, NotisMarkdownEditorSaveResult, NotisRuntime, RuntimeResource, NotisRuntimeContext, NotisRuntimeUI, QueryFilter, RouteDescriptor, SecretPropertyValue, SubscribeDatabaseOptions, ToolDescriptor, 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/dist/space-sdk/src/interactions/actions.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+export type CollectionActionIntent = 'archive' | 'star' | 'delete' | 'enable' | 'disable' | 'pause' | 'resume' | 'move' | 'add-to-folder' | 'complete' | 'start-progress' | 'custom';
+export interface CollectionActionContext<T> {
+    selectedIds: string[];
+    selectedItems: T[];
+    clearSelection: () => void;
+}
+export interface CollectionAction<T> {
+    id: string;
+    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);
+    pending?: boolean;
+    onRun: (context: CollectionActionContext<T>) => void | Promise<void>;
+}
+export interface ResolvedCollectionAction {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    shortcut?: string;
+    destructive?: boolean;
+    disabled?: boolean;
+    pending?: boolean;
+    onRun: () => void | Promise<void>;
+}
+export declare function collectionActionDefaults(intent: CollectionActionIntent | undefined): {
+    label?: string;
+    shortcut?: string;
+};

package/dist/space-sdk/src/interactions/shortcuts.d.ts

@@ -0,0 +1,42 @@
+import React, { type ReactNode } from 'react';
+export type ShortcutScope = 'app' | 'route' | 'collection' | 'detail' | 'modal';
+export declare const SHORTCUT_SCOPE_PRIORITY: Record<ShortcutScope, number>;
+export interface ShortcutDefinition {
+    id: string;
+    /** A chord (`Mod+A`) or timed sequence (`G I`). */
+    keys: string | string[];
+    label?: string;
+    enabled?: boolean;
+    allowInEditable?: boolean;
+    allowRepeat?: boolean;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    onTrigger: (event: KeyboardEvent) => void | Promise<void>;
+}
+export interface UseShortcutsOptions {
+    enabled?: boolean;
+    scope?: ShortcutScope;
+    /** Added to the scope priority for local precedence within a scope. */
+    priority?: number;
+    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;
+}
+export declare function createShortcutCollectionOwner(): string;
+export declare function releaseShortcutCollection(ownerId: string): void;
+export declare function activateShortcutCollection(ownerId: string): void;
+export declare function isEditableShortcutEvent(event: Event): boolean;
+export declare function ShortcutProvider({ children, isAvailable }: {
+    children: ReactNode;
+    isAvailable?: () => boolean;
+}): React.JSX.Element;
+export interface ShortcutHelpEntry {
+    id: string;
+    keys: string[];
+    label: string;
+    scope: ShortcutScope;
+}
+export declare function useShortcuts(shortcuts: ShortcutDefinition[], options?: UseShortcutsOptions): void;
+export declare function shortcutDisplay(raw: string): string;

package/dist/space-sdk/src/interactions/visibility.d.ts

@@ -0,0 +1,2 @@
+/** Visibility across light and Shadow DOM, without relying on layout (virtual rows may have no rect). */
+export declare function isInteractionElementVisible(element: HTMLElement | null): boolean;

package/dist/space-sdk/src/nativeData.d.ts

@@ -0,0 +1,66 @@
+/** 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/dist/space-sdk/src/provider.d.ts

@@ -0,0 +1,17 @@
+import React, { type ReactNode } from 'react';
+import type { NotisRuntime } from './runtime';
+/**
+ * Provides the Notis runtime context to all child components. The portal owns
+ * the runtime and injects it into the rendered app tree.
+ */
+export declare function NotisProvider({ children, runtime, onProtocolError, shortcutsAvailable }: {
+    children: ReactNode;
+    runtime: NotisRuntime | null;
+    onProtocolError?: (error: Error) => void;
+    shortcutsAvailable?: () => boolean;
+}): React.JSX.Element;
+/**
+ * Returns the raw NotisRuntime or null if not yet available.
+ * Prefer the typed hooks (useTool, useNotis, etc.) over this.
+ */
+export declare function useNotisRuntime(): NotisRuntime | null;

package/dist/space-sdk/src/queryCache.d.ts

@@ -0,0 +1,45 @@
+/** In-memory read snapshots. The host owns the lifetime and authorization scope. */
+export interface QuerySnapshot<T = unknown> {
+    data: T | undefined;
+    hasData: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    updatedAt: number;
+    invalidation: number;
+}
+export interface QueryFetchOptions {
+    staleTimeMs?: number;
+    force?: boolean;
+}
+export interface NotisQueryClient {
+    getSnapshot<T>(key: string): QuerySnapshot<T>;
+    subscribe(key: string, listener: () => void): () => void;
+    fetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+    prefetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+    invalidate(key?: string): void;
+    clear(): void;
+    /** Host-only: permanently retire a revoked security scope. */
+    dispose?(): void;
+    getRevision?(): number;
+    /**
+     * Hides records (by `record_key` / `recordKey`) from every cached read at once, so a delete
+     * looks done before the server answers. `commit` keeps them hidden until each read that still
+     * holds them is read again; `restore` shows them again (a failed or undone delete).
+     */
+    hideRecords?(recordKeys: readonly string[]): HiddenRecords;
+}
+export interface HiddenRecords {
+    commit(recordKeys?: readonly string[]): void;
+    restore(recordKeys?: readonly string[]): void;
+}
+/** Stable keys distinguish filters, pagination, and resource identities. */
+export declare function queryKey(value: unknown): string;
+/** One shared queue can bound descriptor and data speculation together. */
+export declare function createPrefetchQueue(concurrency?: number): <T>(read: () => Promise<T>) => Promise<T>;
+export declare function createQueryClient(options?: {
+    maxEntries?: number;
+    now?: () => number;
+    schedule?: ReturnType<typeof createPrefetchQueue>;
+    /** Bounds idempotent reads only; never retries the underlying callback. */
+    readTimeoutMs?: number;
+}): NotisQueryClient;

package/dist/space-sdk/src/queryErrors.ts

@@ -0,0 +1,51 @@
+/** SDK-owned read failures. The host still owns messages for server/action refusals. */
+const copy = {
+  en: {
+    bindingUnavailable: 'This Space cannot read this database yet.',
+    actionUnavailable: 'This action is unavailable in this Space.',
+    readUnavailable: 'These data cannot be read in this Space.',
+    schemaChanged: 'This database changed. Refresh the page and try again.',
+    responseIncomplete: 'This database could not be loaded. Refresh the page and try again.',
+    listUnavailable: 'This list is unavailable in this view.',
+    timedOut: 'This read took too long. Please retry.',
+    scopeUnavailable: 'App query scope is no longer available.',
+    scopeCleared: 'App query scope was cleared.',
+  },
+  fr: {
+    bindingUnavailable: 'Ce Space ne peut pas encore lire cette base de données.',
+    actionUnavailable: 'Cette action n’est pas disponible dans ce Space.',
+    readUnavailable: 'Ces données ne sont pas accessibles dans ce Space.',
+    schemaChanged: 'Cette base de données a changé. Actualise la page et réessaie.',
+    responseIncomplete: 'Cette base de données n’a pas pu être chargée. Actualise la page et réessaie.',
+    listUnavailable: 'Cette liste n’est pas disponible dans cette vue.',
+    timedOut: 'Cette lecture a pris trop de temps. Réessaie.',
+    scopeUnavailable: 'Les données de cette vue ne sont plus accessibles.',
+    scopeCleared: 'Les données de cette vue ont été réinitialisées.',
+  },
+} as const;
+
+export type QueryErrorKey = keyof typeof copy.en;
+const PREFIX = 'notis_sdk_query:';
+
+/** Code and diagnostic survive localisation; only SDK-owned messages are translated. */
+export class SdkQueryError extends Error {
+  readonly code: string;
+  readonly diagnostic?: string;
+  constructor(key: QueryErrorKey, diagnostic?: string, locale?: string, cause?: Error) {
+    super(copy[locale === 'fr' ? 'fr' : 'en'][key], cause ? { cause } : undefined);
+    this.name = 'SdkQueryError';
+    this.code = PREFIX + key;
+    this.diagnostic = diagnostic;
+  }
+}
+
+/** Called at render time, so a cached failure changes language without replaying its read. */
+export function localizeQueryError(error: Error | null, locale?: string): Error | null {
+  const failure = error as (Error & { code?: unknown; diagnostic?: unknown }) | null;
+  if (!failure || typeof failure.code !== 'string' || !failure.code.startsWith(PREFIX)) return error;
+  const key = failure.code.slice(PREFIX.length);
+  if (!Object.hasOwn(copy.en, key)) return error;
+  const message = copy[locale === 'fr' ? 'fr' : 'en'][key as QueryErrorKey];
+  if (failure.message === message) return error;
+  return new SdkQueryError(key as QueryErrorKey, typeof failure.diagnostic === 'string' ? failure.diagnostic : undefined, locale, failure);
+}