@notis_ai/cli 0.2.18 → 0.2.20

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

@@ -0,0 +1,49 @@
+import type { SpaceCloudComputerLevel, SpaceCloudComputerRunResult, SpaceCloudComputerStatus, SpaceCloudComputerUploadInput, SpaceCloudComputerUploadResult } from '../space';
+export interface UseCloudComputerShellResult {
+    /**
+     * The level this Space declares (`'read'` or `'shell'`) when this host offers the cloud computer,
+     * else null (Sites, links, verification harnesses, older hosts): keep the page's own fallback.
+     */
+    level: SpaceCloudComputerLevel | null;
+    /** True when `run` and `upload` are offered: the host offers the cloud computer and the Space declares `'shell'`. */
+    available: boolean;
+    /** The viewer's approval for this Space's current code (either level), or null while it is read. */
+    status: SpaceCloudComputerStatus | null;
+    approved: boolean;
+    loading: boolean;
+    /**
+     * Run one non-interactive command on the viewer's own cloud computer. Same result as the shell tool.
+     * Pass the same `requestId` when the page retries this run itself: a run is never repeated for one key.
+     */
+    run(command: string, options?: RunOptions): Promise<SpaceCloudComputerRunResult>;
+    /** Write one file (at most 1 MiB) straight to the cloud computer; it never travels by URL or chat. */
+    upload(file: SpaceCloudComputerUploadInput): Promise<SpaceCloudComputerUploadResult>;
+    /**
+     * Ask the host to show its approval prompt, for either declared level. Only the person's click in
+     * that prompt approves; once allowed, every `useCloudComputer()` reads the facts again.
+     */
+    requestApproval(): Promise<SpaceCloudComputerStatus | null>;
+    refresh(): Promise<void>;
+}
+type RunOptions = {
+    cwd?: string;
+    timeoutMs?: number;
+    maxOutputLength?: number;
+    requestId?: string;
+};
+/**
+ * The viewer's approval and, for `cloudComputer: 'shell'`, commands and file writes on the signed-in
+ * viewer's own cloud computer, from a Space page.
+ *
+ * ```tsx
+ * const shell = useCloudComputerShell();
+ * if (!shell.level) return <AskNotisFallback />;
+ * if (!shell.approved) return <Button onClick={() => shell.requestApproval()}>Allow</Button>;
+ * const result = await shell.run(`bash ${SCRIPTS}/workspace.sh sync ${quote(repo)} ${quote(name)}`);
+ * ```
+ *
+ * Requires `cloudComputer` in `defineSpace` and the viewer's approval, which the Portal asks for in
+ * its own prompt and which covers only the exact code the viewer allowed: any new release asks again.
+ */
+export declare function useCloudComputerShell(): UseCloudComputerShellResult;
+export {};

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

@@ -0,0 +1,118 @@
+import { type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent } from 'react';
+import { type CollectionAction, type ResolvedCollectionAction } from '../interactions/actions';
+import { type ShortcutScope } from '../interactions/shortcuts';
+import type { MultiSelectActionBarProps } from '../components/MultiSelectActionBar';
+import { useLongPressSelection } from './useLongPressSelection';
+import { type SelectionMarqueeRect } from './useMarqueeSelection';
+export declare const COLLECTION_ITEM_ATTRIBUTE = "data-notis-collection-item-id";
+declare const LEGACY_ROW_ATTRIBUTE = "data-notis-row-id";
+export type { SelectionMarqueeRect };
+export type CollectionInteractionReason = 'activate' | 'clear' | 'drag' | 'items-changed' | 'navigate' | 'range' | 'select-all' | 'toggle';
+export interface CollectionSelectionChange<T> {
+    reason: CollectionInteractionReason;
+    selectedIds: ReadonlySet<string>;
+    selectedItems: T[];
+    anchorId: string | null;
+}
+export type CollectionNavigationDirection = 'next' | 'previous' | 'up' | 'down' | 'left' | 'right';
+export interface CollectionNavigationContext<T> {
+    direction: CollectionNavigationDirection;
+    currentId: string | null;
+    items: T[];
+    orderedIds: string[];
+}
+export interface CollectionKeyboardShortcuts {
+    clear: string | false;
+    selectAll: string | false;
+    toggle: string | false;
+    extendNext: string | string[] | false;
+    extendPrevious: string | string[] | false;
+    next: string | string[] | false;
+    previous: string | string[] | false;
+    up: string | false;
+    down: string | false;
+    left: string | false;
+    right: string | false;
+    activate: string | false;
+}
+export interface UseCollectionInteractionsOptions<T> {
+    items: T[];
+    getId: (item: T) => string;
+    selectionMode?: 'multiple' | 'single' | 'none';
+    selectedIds?: ReadonlySet<string>;
+    defaultSelectedIds?: Iterable<string>;
+    onSelectionChange?: (change: CollectionSelectionChange<T>) => void;
+    activeId?: string | null;
+    defaultActiveId?: string | null;
+    onActiveIdChange?: (id: string | null, reason: CollectionInteractionReason) => void;
+    anchorId?: string | null;
+    defaultAnchorId?: string | null;
+    onAnchorIdChange?: (id: string | null, reason: CollectionInteractionReason) => void;
+    onActivate?: (item: T, id: string) => void;
+    isItemDisabled?: (item: T) => boolean;
+    enabled?: boolean;
+    bindKeyboardShortcuts?: boolean;
+    enableDragSelect?: boolean;
+    /** Touch-only long press; optional per view. */
+    enableLongPressSelection?: boolean;
+    /** Plain item clicks activate the item and clear checkbox selection by default. */
+    clearSelectionOnPlainClick?: boolean;
+    dragThreshold?: number;
+    shortcuts?: Partial<CollectionKeyboardShortcuts>;
+    shortcutScope?: ShortcutScope;
+    shortcutPriority?: number;
+    resolveNextId?: (context: CollectionNavigationContext<T>) => string | null;
+    onActiveItemChange?: (id: string | null) => void;
+    actions?: CollectionAction<T>[];
+}
+export interface CollectionInteractionController<T> {
+    selectedIds: ReadonlySet<string>;
+    selectedCount: number;
+    activeId: string | null;
+    anchorId: string | null;
+    /** Compatibility aliases used by the original multi-select API. */
+    headId: string | null;
+    lastClickedId: string | null;
+    dragRect: SelectionMarqueeRect | null;
+    actions: ResolvedCollectionAction[];
+    getActionBarProps: () => Pick<MultiSelectActionBarProps, 'selectedCount' | 'actions' | 'collectionOwnerId' | 'isAvailable' | 'shortcutsEnabled' | 'onClearSelection'>;
+    isSelected: (id: string) => boolean;
+    getSelectedItems: () => T[];
+    setActive: (id: string | null, reason?: CollectionInteractionReason) => void;
+    activate: (id: string) => void;
+    toggle: (id: string) => void;
+    select: (ids: string[]) => void;
+    clear: () => void;
+    selectAll: () => void;
+    selectRange: (anchorId: string, targetId: string) => void;
+    onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
+    onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
+    getRowProps: (id: string) => Record<string, string>;
+    getItemProps: (id: string) => Partial<ReturnType<ReturnType<typeof useLongPressSelection>>> & {
+        [COLLECTION_ITEM_ATTRIBUTE]: string;
+        [LEGACY_ROW_ATTRIBUTE]: string;
+        tabIndex: number;
+        'aria-selected': boolean;
+        'aria-disabled': boolean;
+        'data-notis-active': 'true' | 'false';
+        onFocus: () => void;
+        onMouseDown: (event: ReactMouseEvent) => void;
+        onClick: (event: ReactMouseEvent) => void;
+        onKeyDown: (event: ReactKeyboardEvent) => void;
+    };
+    getCheckboxProps: (id: string) => {
+        isSelected: boolean;
+        disabled: boolean;
+        onClick: (event: ReactMouseEvent) => void;
+    };
+    getContainerProps: () => {
+        ref: (node: HTMLElement | null) => void;
+        onMouseDown: (event: ReactMouseEvent) => void;
+        onFocusCapture: () => void;
+        onClickCapture: (event: ReactMouseEvent) => void;
+        style: {
+            userSelect: 'none';
+        };
+    };
+}
+export declare function useCollectionInteractions<T>(options: UseCollectionInteractionsOptions<T>): CollectionInteractionController<T>;

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

@@ -0,0 +1,14 @@
+import type { DatabaseProperty } from '../runtime';
+export interface UseDatabaseSchemaResult {
+    name: string | null;
+    description: string | null;
+    properties: DatabaseProperty[];
+    loading: boolean;
+    isFetching: boolean;
+    hasData: boolean;
+    error: Error | null;
+    /** Reads again; resolves to the read's error, or null when it succeeded. */
+    refetch: () => Promise<Error | null>;
+}
+/** Fetch a database's schema (normalized properties + metadata). */
+export declare function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult;

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

@@ -0,0 +1,26 @@
+import { type UseDocumentsOptions, type UseDocumentsResult } from './useDocuments';
+import type { DocumentRecord } from '../runtime';
+export interface UseDatabaseSubscriptionOptions extends UseDocumentsOptions {
+    /** Set to false to keep the query but skip the change feed. */
+    subscribe?: boolean;
+}
+export interface UseDatabaseSubscriptionResult extends UseDocumentsResult {
+    /** Alias of `documents`, for views that think in rows. */
+    rows: DocumentRecord[];
+    /** True while a live change feed is attached to this database. */
+    live: boolean;
+}
+/**
+ * Query a Notis database and keep it fresh without polling.
+ *
+ * ```tsx
+ * const { rows, live, refetch } = useDatabaseSubscription('workspaces');
+ * ```
+ *
+ * A change on the database wakes the hook, which then refetches through the
+ * usual `LOCAL_NOTIS_DATABASE_QUERY` path — the change feed is a signal only
+ * and never carries row data. Hosts without a change feed (the dev harness,
+ * the screenshot stub, the vite preview) still return rows; `live` is false
+ * there and the app should keep offering its manual refresh.
+ */
+export declare function useDatabaseSubscription(databaseSlug: string, options?: UseDatabaseSubscriptionOptions): UseDatabaseSubscriptionResult;

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

@@ -0,0 +1,22 @@
+import type { DocumentRecord } from '../runtime';
+/** The words of the document hook's own failures, in English and French (C8). */
+export declare const DOCUMENT_HOOK_WORDS: Readonly<{
+    notFound: {
+        en: string;
+        fr: string;
+    };
+}>;
+export interface UseDocumentOptions {
+    enabled?: boolean;
+}
+export interface UseDocumentResult {
+    document: DocumentRecord | null;
+    loading: boolean;
+    isFetching: boolean;
+    hasData: boolean;
+    error: Error | null;
+    /** Reads again; resolves to the read's error, or null when it succeeded. */
+    refetch: () => Promise<Error | null>;
+}
+/** Fetch a single document (with content) by id, normalized. */
+export declare function useDocument(documentId: string | null | undefined, options?: UseDocumentOptions): UseDocumentResult;

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

@@ -0,0 +1,31 @@
+import type { DocumentRecord, QueryFilter } from '../runtime';
+export interface UseDocumentsOptions {
+    filter?: QueryFilter;
+    pageSize?: number;
+    offset?: number;
+    /** Fetch every page, starting at offset, instead of returning only one page. */
+    fetchAll?: boolean;
+    /** App-view lists can omit bodies until opening/searching a document. Default: true. */
+    includeContent?: boolean;
+    enabled?: boolean;
+}
+export interface UseDocumentsResult {
+    documents: DocumentRecord[];
+    loading: boolean;
+    isFetching: boolean;
+    hasData: boolean;
+    error: Error | null;
+    /** Reads again; resolves to the read's error, or null when it succeeded. */
+    refetch: () => Promise<Error | null>;
+}
+/**
+ * Query a Notis database and get normalized `DocumentRecord`s.
+ *
+ * ```tsx
+ * const { documents, loading, refetch } = useDocuments('notes', {
+ *   filter: { filters: [{ property: 'Folder', operator: 'contains', type: 'relation', value: folderId }] },
+ *   pageSize: 250,
+ * });
+ * ```
+ */
+export declare function useDocuments(databaseSlug: string, options?: UseDocumentsOptions): UseDocumentsResult;

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

@@ -0,0 +1,43 @@
+import type { HandoverPayload, HandoverResult } from '../runtime';
+export interface UseHandoverResult {
+    /** Hand the work over. Rejects when the host has no manager chat. */
+    handover: (payload: HandoverPayload) => Promise<HandoverResult>;
+    /** True while the manager chat is being prepared. */
+    pending: boolean;
+    error: Error | null;
+    /**
+     * False when the host cannot hand work over (dev harness, vite preview).
+     * Render the app's own fallback — a copyable prompt, say — when it is false.
+     */
+    available: boolean;
+}
+/**
+ * Hand a piece of work from app code to the Notis manager chat.
+ *
+ * An app displays work; the manager runs it. `handover` puts the message in
+ * the chat surface that already owns streaming progress, billing, cancellation
+ * and the transcript, and the app watches its own databases for the result.
+ *
+ * ```tsx
+ * const { handover, pending, available } = useHandover();
+ *
+ * return available ? (
+ *   <Button
+ *     disabled={pending}
+ *     onClick={() => { void handover({ prompt: 'Create a workspace on notis to ...' }); }}
+ *   >
+ *     Send to Notis
+ *   </Button>
+ * ) : (
+ *   <CopyablePrompt prompt="Create a workspace on notis to ..." />
+ * );
+ * ```
+ *
+ * Omit `prompt` to open a context-only composer, for example when a visible
+ * feedback button should let the user write in their own words.
+ *
+ * Pass `skill` to bind the work to a skill declared in `notis.config.ts`; the
+ * host rejects a key the app does not declare. `autoSend` submits the prepared
+ * message on an active user gesture; background calls still open a draft.
+ */
+export declare function useHandover(): UseHandoverResult;

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

@@ -0,0 +1,9 @@
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+/** Adds a touch-only long-press entry point without rendering idle checkboxes. */
+export declare function useLongPressSelection(onSelect: (id: string) => void): (id: string) => {
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+    onClickCapture: (event: ReactMouseEvent<HTMLElement>) => boolean;
+};

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

@@ -0,0 +1,57 @@
+/**
+ * `useMarqueeSelection`: drag from empty space to select (the rubber band), shared by the Manager
+ * (`useCollectionInteractions`) and the toolkit list (`ListReader`), so both run the same code.
+ *
+ * - A press starts a marquee only on empty space inside the container: not on an item, not on a control
+ *   (button, link, field). A press on a control does nothing here; a press on an item is left to the item.
+ * - The marquee shows once the pointer moved past `threshold` px; the text selection is cleared then.
+ * - While dragging, every selectable item the rectangle intersects is selected, live (`onSelect`, in DOM order;
+ *   the last one is the anchor).
+ * - Releasing after a drag swallows the click that follows; a plain click on empty space clears (`onClear`).
+ * - Mouse events only: a touch drag scrolls and never draws a marquee.
+ */
+import { type MouseEvent as ReactMouseEvent } from 'react';
+export interface SelectionMarqueeRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Clicks on these belong to the control (Manager `INTERACTIVE_SELECTOR`). */
+export declare const MARQUEE_INTERACTIVE_SELECTOR = "button, a, input, textarea, select, [role=\"button\"], [contenteditable]:not([contenteditable=\"false\"])";
+export interface UseMarqueeSelectionOptions {
+    /** The marquee is on: the collection allows multiple selection and the surface did not opt out. */
+    enabled: boolean;
+    /** The attribute every item element carries, holding its id. */
+    itemAttribute: string;
+    /** Items that may join the selection (pending and disabled ones may not). */
+    isSelectable: (id: string) => boolean;
+    /** The items under the rectangle, in DOM order, on every move of a drag. Replaces the selection. */
+    onSelect: (ids: string[]) => void;
+    /** A plain click (no drag) on empty space. */
+    onClear: () => void;
+    /** Distance in px before a press becomes a drag. Default 5. */
+    threshold?: number;
+    interactiveSelector?: string;
+    /** A part of an item a drag may also start from (a row's leading strip), so a list with no empty space left still
+     *  has a place to start one. A plain click there still reaches the item. Default: empty space only. */
+    startSelector?: string;
+}
+export interface MarqueeSelection {
+    /** The marquee in viewport coordinates while dragging, else null (draw it with `SelectionMarquee`). */
+    rect: SelectionMarqueeRect | null;
+    /** Put on the container. */
+    onMouseDown: (event: ReactMouseEvent) => void;
+    /** Put on the container: swallows the click that ends a drag (or any gesture that armed it). */
+    onClickCapture: (event: ReactMouseEvent) => void;
+    /** Swallow the next click inside the container (Mod-press toggles use it too). */
+    armSuppressNextClick: () => void;
+}
+/** The ids of the selectable items under `rect` inside `container`, in DOM order. */
+export declare function itemsInMarquee(container: ParentNode | null, rect: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}, itemAttribute: string, isSelectable: (id: string) => boolean): string[];
+export declare function useMarqueeSelection(options: UseMarqueeSelectionOptions): MarqueeSelection;

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

@@ -0,0 +1,51 @@
+import { type MouseEvent as ReactMouseEvent } from 'react';
+import { type CollectionInteractionController, type SelectionMarqueeRect } from './useCollectionInteractions';
+declare const ROW_ATTR = "data-notis-row-id";
+export type DragRect = SelectionMarqueeRect;
+export interface UseMultiSelectOptions<T> {
+    items: T[];
+    getId: (item: T) => string;
+    /** When false, suppresses the global Esc / Cmd+A / X / Shift+Arrow listeners. Default true. */
+    bindKeyboardShortcuts?: boolean;
+    /** When false, disables the rubber-band drag-select rectangle. Default true. */
+    enableDragSelect?: boolean;
+    /** Distance (px) the cursor must move past mousedown before a drag begins. Default 5. */
+    dragThreshold?: number;
+    /** Initial head id (the row that Shift+Arrow extends from). */
+    initialHeadId?: string | null;
+    /** Fires when the head moves via Shift+Arrow so the consumer can scroll the row into view. */
+    onHeadChange?: (id: string | null) => void;
+}
+export interface MultiSelectController<T> {
+    selectedIds: ReadonlySet<string>;
+    selectedCount: number;
+    lastClickedId: string | null;
+    headId: string | null;
+    dragRect: DragRect | null;
+    isSelected: (id: string) => boolean;
+    getSelectedItems: () => T[];
+    toggle: (id: string) => void;
+    select: (ids: string[]) => void;
+    clear: () => void;
+    selectAll: () => void;
+    selectRange: (anchorId: string, targetId: string) => void;
+    setHead: (id: string | null) => void;
+    onCheckboxClick: (id: string) => (event: ReactMouseEvent) => void;
+    onRowMouseDown: (id: string) => (event: ReactMouseEvent) => void;
+    getRowProps: (id: string) => {
+        [ROW_ATTR]: string;
+    };
+    getItemProps: CollectionInteractionController<T>['getItemProps'];
+    getCheckboxProps: (id: string) => {
+        isSelected: boolean;
+        onClick: (event: ReactMouseEvent) => void;
+    };
+    getContainerProps: CollectionInteractionController<T>['getContainerProps'];
+}
+/**
+ * @deprecated Use `useCollectionInteractions` for controlled selection,
+ * active-item navigation, scoped shortcuts, and semantic actions. This bridge
+ * is retained for the 0.2 minor and scheduled for removal in 0.3.
+ */
+export declare function useMultiSelect<T>(options: UseMultiSelectOptions<T>): MultiSelectController<T>;
+export {};

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

@@ -0,0 +1,24 @@
+import { type SpaceDocumentBodyRead, type SpaceDocumentBodySave } from '../space';
+/** Explicit textarea Save. The source owns the draft and retains its request ID
+ * until a receipt or unchanged result; background reads never replace that draft. */
+export declare function useNativeDocumentBody(binding: string, recordKey: string | null, options: {
+    readAction: string;
+    writeAction?: string;
+    enabled?: boolean;
+}): {
+    data: SpaceDocumentBodyRead | undefined;
+    hasData: boolean;
+    loading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    refetch: () => Promise<Error | null>;
+    body: SpaceDocumentBodyRead | undefined;
+    save: (draft: {
+        contentMarkdown: string;
+        expectedRevision: number;
+        schemaRevision: number;
+        requestId: string;
+    }) => Promise<SpaceDocumentBodySave>;
+    saving: boolean;
+    saveError: Error | null;
+};

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

@@ -0,0 +1,55 @@
+import type { DocumentRecord } from '../runtime';
+import type { NativeDelete, NativeInsert, NativeMutationReceipt, NativeQuery, NativeUpdate } from '../nativeData';
+import { type UseQueryResult } from './useQuery';
+/**
+ * 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 declare 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;
+};
+/** Explicit insert/update/trash; update never silently creates a missing row. */
+export declare 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;
+};
+export interface NativeDeleteManyResult {
+    done: NativeDelete[];
+    failed: Array<{
+        input: NativeDelete;
+        error: Error;
+    }>;
+}
+/**
+ * Trashes many rows of one database binding: every row leaves the cached reads at once, the writes run a few at
+ * a time (each with its own request ID, `${requestId}:${record_key}`, so a retry with the same `requestId` replays
+ * instead of trashing twice), the reads refresh once at the end, and a row whose write failed comes back. It never
+ * throws for a failed row: `failed` lists them.
+ */
+export declare function useNativeDelete(binding: string): {
+    deleteMany: (inputs: readonly NativeDelete[], options: {
+        schemaRevision: number;
+        requestId: string;
+    }) => Promise<NativeDeleteManyResult>;
+    loading: boolean;
+    error: Error | null;
+};

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

@@ -0,0 +1,25 @@
+import type { RuntimeResource, AppDescriptor, CollectionItemDetail, DatabaseDescriptor, RouteDescriptor } from '../runtime';
+interface NotisContext {
+    /** UI selection only; it grants no access and is never a record scope. */
+    selection: string | null;
+    resource: RuntimeResource | null;
+    /** App metadata (id, name, icon, description). Null before runtime loads. */
+    app: AppDescriptor | null;
+    /** Current route descriptor. Null before runtime loads. */
+    route: RouteDescriptor | null;
+    /** Databases declared by this app. Empty before runtime loads. */
+    databases: DatabaseDescriptor[];
+    /** Selected collection item for the current route, when applicable. */
+    collectionItem: CollectionItemDetail | null;
+    /** Resource requested through this route's canonical deep link. */
+    resourceId: string | null;
+    /** Whether the runtime is loaded and available. */
+    ready: boolean;
+}
+/**
+ * Access app-level metadata, the current route, declared databases, and the
+ * selected collection item. Returns safe defaults when the portal runtime is
+ * not available.
+ */
+export declare function useNotis(): NotisContext;
+export {};

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

@@ -0,0 +1,33 @@
+export interface SpaceNavigationOptions {
+    recordKey?: string | null;
+    /** Declared view parameters. The destination authorizes records and drops unknown names. */
+    params?: Record<string, string | number | boolean | null | undefined>;
+    selection?: string | null;
+}
+interface NavigationActions {
+    /** Resolve a declared portable destination under the current viewer's access. */
+    toNamedSpace: (alias: string, options?: SpaceNavigationOptions) => Promise<void>;
+    /**
+     * Open an exact Space, optionally at a native record's stable record_key. Resolves once the host has taken the
+     * navigation; rejects when the host refuses it (the Space closed, or the view it came from is no longer active).
+     */
+    toSpace: (spaceId: string, options?: SpaceNavigationOptions) => Promise<void>;
+    /** Navigate to a route within the app by its path. */
+    toRoute: (path: string, options?: {
+        resourceId?: string | null;
+    }) => void;
+    /** Navigate to the app's default route. */
+    toApp: () => void;
+}
+/**
+ * Navigation helpers for Spaces and app routes.
+ * When rendered inside the portal, uses the runtime.navigate() bridge.
+ * Without a portal runtime, falls back to window.location for route navigation.
+ *
+ * ```tsx
+ * const nav = useNotisNavigation();
+ * nav.toSpace(spaceId, { recordKey });
+ * ```
+ */
+export declare function useNotisNavigation(): NavigationActions;
+export {};

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

@@ -0,0 +1,22 @@
+export interface UseQueryOptions {
+    /** Required acknowledgement: only idempotent reads may run on mount or prefetch. */
+    readOnly: true;
+    enabled?: boolean;
+    staleTimeMs?: number;
+}
+export interface UseQueryResult<T> {
+    data: T | undefined;
+    hasData: boolean;
+    loading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    /** Reads again; resolves to the read's localized error, or null when it succeeded (never rejects). */
+    refetch: () => Promise<Error | null>;
+}
+/** Cached read callback; scope and lifetime are provided by the host, never by app globals. */
+export declare function useQuery<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): UseQueryResult<T>;
+/** Opt-in preparation for small, known read queries. Never use for writes or full-database crawls. */
+export declare function useQueryClient(): {
+    invalidate(key?: readonly unknown[]): void;
+    prefetch<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): Promise<T | undefined>;
+};

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

@@ -0,0 +1,20 @@
+import type { ToolCallOptions } from '../runtime';
+type ToolArguments = Record<string, unknown>;
+type ToolCall<TArgs extends ToolArguments | undefined, TResult> = undefined extends TArgs ? (args?: Exclude<TArgs, undefined>, options?: ToolCallOptions) => Promise<TResult> : (args: TArgs, options?: ToolCallOptions) => Promise<TResult>;
+export interface ToolCallState {
+    loading: boolean;
+    error: Error | null;
+}
+export interface UseToolResult<TArgs extends ToolArguments | undefined = ToolArguments | undefined, TResult = unknown> extends ToolCallState {
+    call: ToolCall<TArgs, TResult>;
+}
+/**
+ * Call a specific Notis tool by name.
+ *
+ * ```tsx
+ * const { call, loading } = useTool('LOCAL_NOTIS_WEB_SEARCH');
+ * const result = await call({ query: 'latest news' });
+ * ```
+ */
+export declare function useTool<TArgs extends ToolArguments | undefined = ToolArguments | undefined, TResult = unknown>(toolName: string): UseToolResult<TArgs, TResult>;
+export {};

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

@@ -0,0 +1,3 @@
+import { type UseQueryOptions } from './useQuery';
+/** An explicitly identified read-only tool, cached by tool name and exact arguments. */
+export declare function useToolQuery<T = unknown>(name: string, args: Record<string, unknown> | undefined, options: UseQueryOptions): import("./useQuery").UseQueryResult<T>;

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

@@ -0,0 +1,15 @@
+import type { ToolDescriptor } from '../runtime';
+interface UseToolsResult {
+    tools: ToolDescriptor[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * List all tools available to this app.
+ *
+ * ```tsx
+ * const { tools, loading } = useTools();
+ * ```
+ */
+export declare function useTools(): UseToolsResult;
+export {};