@notis_ai/cli 0.2.17 → 0.2.19

package/dist/space-sdk/src/ui/comments/CommentPane.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The comment pane and its pieces, rendered from a `useComments` controller:
+ *
+ * - `CommentPane`: the side panel (filters, Copy changes, the new comment box, the thread cards, the delete
+ *   confirmation and the toast).
+ * - `CommentPins`: the numbered pins and zones on the anchor element. Put it inside the element the comments sit on (a
+ *   slide, a section) and give that element `position: relative`. With `controller.commenting` on it covers the element:
+ *   a click drops a pin, a press and drag marks a zone (when the table has zone columns). The pane's "Comment on this
+ *   item" starts a comment on the whole anchor, with no pin.
+ * - `CommentThreadCard`, `NewCommentBox` and `CommentAvatar` for Spaces that lay the pane out themselves.
+ *
+ * Keyboard: Enter sends a reply or a new comment and Shift+Enter adds a line; Escape in an empty new comment drops it
+ * (with text, the first Escape leaves the field); Escape leaves Add comment mode; a thread card selects with Enter.
+ */
+import React from 'react';
+import { type CommentThread } from './commentModel';
+import type { CommentController } from './useComments';
+export interface CommentAvatarProps {
+    author: string;
+    /** The person using the Space: their avatar is filled, everyone else's is quiet. */
+    me?: string;
+    className?: string;
+}
+/** The author's initial. Decorative: the author's name is always written next to it. */
+export declare function CommentAvatar({ author, me, className }: CommentAvatarProps): React.JSX.Element;
+export interface CommentThreadCardProps {
+    controller: CommentController;
+    thread: CommentThread;
+    /** Name the anchor in the card's meta line (when the pane lists every anchor). */
+    showAnchor?: boolean;
+}
+export declare function CommentThreadCard({ controller, thread, showAnchor }: CommentThreadCardProps): React.JSX.Element;
+export interface NewCommentBoxProps {
+    controller: CommentController;
+}
+/** The box for the comment `controller.draftPin` started. Takes focus when it opens. */
+export declare function NewCommentBox({ controller }: NewCommentBoxProps): React.JSX.Element | null;
+export interface CommentPinsProps {
+    controller: CommentController;
+    /** The anchor the pins sit on. Default: `controller.anchorKey`. */
+    anchorKey?: string | null;
+    /** A pin was pressed. Default: `controller.selectThread`. */
+    onOpen?(thread: CommentThread): void;
+}
+/**
+ * Numbered pins at each thread's x and y on the anchor element, the zones threads mark, and the pin or zone of the
+ * comment being written. In Add comment mode it also covers the element to take the click or drag that places one.
+ */
+export declare function CommentPins({ controller, anchorKey, onOpen }: CommentPinsProps): React.JSX.Element;
+export interface CommentPaneProps {
+    controller: CommentController;
+    /** The heading. Default "Comments". */
+    title?: string;
+    /** Hide Copy changes (a pane read by people only). Default shown. */
+    showCopy?: boolean;
+    className?: string;
+}
+export declare function CommentPane({ controller, title, showCopy, className }: CommentPaneProps): React.JSX.Element;

package/dist/space-sdk/src/ui/comments/commentModel.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Comment threads on a Space database (pure; no React). The table shape is the Notis Slides Comments table:
+ *
+ * | Column      | Type                 | Meaning                                                               |
+ * | ----------- | -------------------- | --------------------------------------------------------------------- |
+ * | Body        | title                | The comment text.                                                     |
+ * | Deck        | relation             | The scope the comment belongs to (a deck, a page, a review).          |
+ * | Slide       | relation             | The anchor record it is on (a slide, a section). Empty: on the scope. |
+ * | Thread      | text                 | Empty on a thread's first comment; the root's record key on a reply.  |
+ * | Author      | select               | Who wrote it (Flo, Claude, Notis, or any name).                       |
+ * | X, Y        | number               | The pin, 0 to 1 across and down the anchor. Empty: on the whole anchor. |
+ * | W, H        | number               | A zone from the pin, 0 to 1 of the anchor's width and height. Empty: a point. |
+ * | Status      | select               | Open, Resolved or Deleted (a delete keeps the row for the digest).    |
+ * | Needs       | select               | none, check, choice or input: what the author asks of the reader.     |
+ * | Options     | text                 | The choices of a choice ask, separated by `|`.                       |
+ * | Answer      | text                 | The reader's answer to the ask.                                       |
+ * | Answered at | date                 | When the answer was given.                                            |
+ * | Change      | select               | The last change made here: created, replied, answered, resolved, reopened, deleted. |
+ * | Changed at  | date                 | When that change was made; the digest lists changes after the checkpoint. |
+ * | Example     | checkbox             | A sample comment shown with an Example badge.                         |
+ *
+ * Every column name can be renamed with `CommentColumns`; the defaults are the Slides names, so a Space that copies
+ * the Slides table needs no mapping and no migration. Zones are opt-in: a table that adds W and H number columns
+ * passes `{ w: 'W', h: 'H' }`. Without them (`w` and `h` null, the default) a drag on the anchor places a pin where it
+ * started, and nothing writes a column the table does not have.
+ */
+export type CommentRow = Record<string, unknown>;
+export type CommentNeeds = 'none' | 'check' | 'choice' | 'input';
+export type CommentStatus = 'Open' | 'Resolved' | 'Deleted';
+export type CommentChange = 'created' | 'replied' | 'answered' | 'resolved' | 'reopened' | 'deleted';
+/** Column names of the Comments table. `scope` or `anchor` set to null: the table has no such column. */
+export interface CommentColumns {
+    body: string;
+    scope: string | null;
+    anchor: string | null;
+    thread: string;
+    author: string;
+    x: string;
+    y: string;
+    /** The zone's width and height. Null: the table has no zone columns, and comments are points only. */
+    w: string | null;
+    h: string | null;
+    status: string;
+    needs: string;
+    options: string;
+    answer: string;
+    answeredAt: string;
+    change: string;
+    changedAt: string;
+    example: string;
+}
+export declare const COMMENT_COLUMNS: Readonly<CommentColumns>;
+export declare function commentColumns(columns?: Partial<CommentColumns>): CommentColumns;
+export interface CommentRecord {
+    id: string;
+    recordKey: string;
+    revision: number;
+    body: string;
+    scopeIds: string[];
+    anchorIds: string[];
+    thread: string;
+    author: string;
+    x: number | null;
+    y: number | null;
+    w: number | null;
+    h: number | null;
+    status: CommentStatus;
+    needs: CommentNeeds;
+    options: string[];
+    answer: string;
+    answeredAt: string | null;
+    change: CommentChange | null;
+    changedAt: string | null;
+    example: boolean;
+    createdAt: string | null;
+}
+/** The record a thread sits on (a slide, a section). `order` numbers it in the digest and the card meta. */
+export interface CommentAnchor {
+    id: string;
+    recordKey: string;
+    order: number;
+    title: string;
+}
+/** The record the comments belong to (a deck, a page). `checkpoint` is the last time changes were copied. */
+export interface CommentScope {
+    id: string;
+    recordKey: string;
+    name: string;
+    checkpoint: string | null;
+}
+export interface CommentThread {
+    root: CommentRecord;
+    replies: CommentRecord[];
+    anchor: CommentAnchor | undefined;
+}
+/** One Comments row as a comment. An author outside `authors` (when given) reads as `fallbackAuthor`. */
+export declare function readCommentRow(row: CommentRow, options?: {
+    columns?: Partial<CommentColumns>;
+    authors?: readonly string[];
+    fallbackAuthor?: string;
+}): CommentRecord;
+/** The rows of a list answer (`{ rows }`), skipping anything that is not an object. */
+export declare function commentRowsOf(value: unknown): CommentRow[];
+/** Time in ms; a date without an offset is read as UTC so ordering stays stable. */
+export declare function commentTimeOf(value: string | null | undefined): number;
+/** True when the comment belongs to `scope` (by id or record key). No scope: every comment belongs. */
+export declare function inCommentScope(comment: CommentRecord, scope: Pick<CommentScope, 'id' | 'recordKey'> | null | undefined): boolean;
+export declare function commentAnchorOf(comment: CommentRecord, anchors: readonly CommentAnchor[]): CommentAnchor | undefined;
+/** Threads in anchor order, then by creation; deleted replies are left out. Deleted roots stay (filter them to hide). */
+export declare function commentThreads(comments: readonly CommentRecord[], anchors: readonly CommentAnchor[]): CommentThread[];
+/** Changes after the checkpoint: `me`'s comments and replies, and every answer or status change. */
+export declare function commentChangesSince(comments: readonly CommentRecord[], checkpoint: string | null | undefined, me?: string): CommentRecord[];
+export interface CommentDigestOptions {
+    /** First line, before the scope name. Default "Slide comments". */
+    heading?: string;
+    /** What the scope is called ("Deck"): the fallback name and "Deck record". */
+    scopeNoun?: string;
+    /** What an anchor is called ("Slide"): "Slide 3" and "Unknown slide". */
+    anchorNoun?: string;
+    /** The table agents insert replies into. Default "Comments". */
+    table?: string;
+    /** The reader whose answers and status changes the digest reports. Default "Flo". */
+    me?: string;
+    columns?: Partial<CommentColumns>;
+}
+/** True when the comment marks a zone (a pin with a width and a height), not a point. */
+export declare function isCommentZone(comment: Pick<CommentRecord, 'x' | 'y' | 'w' | 'h'> | null | undefined): boolean;
+/**
+ * The compact digest pasted into an agent's chat: every change since the scope's checkpoint, with where it is, what
+ * changed and the thread state. Always English: it is read by agents, not shown to people.
+ */
+export declare function commentDigest(input: {
+    scope: CommentScope | null;
+    comments: readonly CommentRecord[];
+    anchors: readonly CommentAnchor[];
+    changes: readonly CommentRecord[];
+    nowIso: string;
+}, options?: CommentDigestOptions): string;
+/** Local fields shown until the server row reaches `revision` (null while the write is in flight). */
+export interface CommentPatch {
+    fields: Partial<CommentRecord>;
+    revision: number | null;
+}
+export declare function applyCommentPatches(comments: readonly CommentRecord[], patches: Readonly<Record<string, CommentPatch>>): CommentRecord[];
+/** The two answers of a check ask, stored in English and shown in the reader's language. */
+export declare const COMMENT_CHECK_ANSWERS: readonly ['Looks good', 'Undo'];
+/** Text files an input ask accepts as an attachment. */
+export declare const COMMENT_TEXT_FILE: RegExp;
+/** An answer to an input ask is kept to 500 characters. */
+export declare function clipCommentAnswer(body: string): string;
+export declare function newCommentId(): string;
+/** "2 min ago", "il y a 3 h": short relative time in the reader's language. */
+export declare function commentRelativeTime(iso: string | null, locale: string, now: number): string;
+/** Clipboard API first; the selection copy runs inside `host` (the Space's own element), never on the page body. */
+export declare function writeCommentClipboard(text: string, host: HTMLElement | null): Promise<boolean>;
+/** Bring an element into view inside its nearest scrolling box only; the page around the Space never moves. */
+export declare function scrollCommentIntoView(element: HTMLElement): void;

package/dist/space-sdk/src/ui/comments/commentWords.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The words of the comment pane, in English and French. `{n}` is an anchor number or a count, `{who}` an author and
+ * `{answer}` an answer. A Space names its own anchors (a slide, a section) by passing `words` to `useComments`.
+ */
+import { type Words } from '../../words';
+export declare const COMMENT_WORDS: Readonly<{
+    comments: Words;
+    thisAnchor: Words;
+    all: Words;
+    open: Words;
+    resolved: Words;
+    resolvedFilter: Words;
+    status: Words;
+    scope: Words;
+    copy: Words;
+    copiedOne: Words;
+    copiedMany: Words;
+    copyFailed: Words;
+    anchorLabel: Words;
+    reply: Words;
+    replyToReopen: Words;
+    newComment: Words;
+    newCommentOn: Words;
+    newCommentWhole: Words;
+    commentOnAnchor: Words;
+    pinHint: Words;
+    zoneHint: Words;
+    commentPlaceholder: Words;
+    send: Words;
+    cancel: Words;
+    resolve: Words;
+    reopen: Words;
+    delete: Words;
+    deleteTitle: Words;
+    deleteBody: Words;
+    needs: Words;
+    needCheck: Words;
+    needChoice: Words;
+    needInput: Words;
+    looksGood: Words;
+    undo: Words;
+    attach: Words;
+    paste: Words;
+    sent: Words;
+    example: Words;
+    emptyAnchor: Words;
+    emptyAll: Words;
+    emptyResolved: Words;
+    saveError: Words;
+    textOnly: Words;
+    newActivity: Words;
+    pin: Words;
+    zone: Words;
+}>;
+export type CommentWordKey = keyof typeof COMMENT_WORDS;
+export type CommentWords = Readonly<Record<CommentWordKey, Words>>;
+/** The pane's words with a Space's own wording on top (for example "This slide" for `thisAnchor`). */
+export declare function commentWords(overrides?: Partial<Record<CommentWordKey, Words>>): CommentWords;
+/** "Copied 3 changes". */
+export declare function commentCopiedWords(words: CommentWords, n: number): Words;

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

@@ -0,0 +1,4 @@
+export * from './commentModel';
+export * from './commentWords';
+export * from './useComments';
+export * from './CommentPane';

package/dist/space-sdk/src/ui/comments/useComments.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The comment controller: reads a Comments database through the view's declared list, follows its live feed, writes
+ * through the normal native mutations and keeps every change on screen at once (optimistic patches and drafts) until
+ * the server rows carry it. `CommentPane`, `CommentPins` and `CommentThreadCard` render from it.
+ */
+import { type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent } from 'react';
+import { type Locale, type Words } from '../../words';
+import { type ToastController } from '../actions/useToast';
+import { type CommentAnchor, type CommentColumns, type CommentDigestOptions, type CommentRecord, type CommentScope, type CommentThread } from './commentModel';
+import { type CommentWordKey, type CommentWords } from './commentWords';
+/** Which threads the pane lists: the current anchor's, or every thread in the scope. */
+export type CommentAnchorFilter = 'anchor' | 'all';
+/** Open threads, or resolved ones. */
+export type CommentStatusFilter = 'open' | 'resolved';
+/**
+ * A new comment being written: on an anchor, with a pin (x and y, 0 to 1), a zone (w and h too, 0 to 1 of the
+ * anchor's size) or neither (on the whole anchor).
+ */
+export interface CommentDraftPin {
+    anchorKey: string | null;
+    x: number | null;
+    y: number | null;
+    w: number | null;
+    h: number | null;
+}
+/** The zone being dragged on an anchor, 0 to 1 of its size. */
+export interface CommentDragZone {
+    anchorKey: string | null;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Pointer handlers for the element the anchor is drawn in: a click drops a pin, a drag marks a zone. */
+export interface CommentZoneHandlers {
+    onPointerDown(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerMove(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerUp(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerCancel(event: ReactPointerEvent<HTMLElement>): void;
+}
+export interface CommentActions {
+    /** Adds a reply. A reply reopens a resolved thread and answers an open input ask. True once saved. */
+    reply(thread: CommentThread, body: string): Promise<boolean>;
+    /** Answers a check or choice ask. */
+    answer(root: CommentRecord, answer: string): void;
+    setStatus(root: CommentRecord, status: 'Open' | 'Resolved'): void;
+    /** Opens the delete confirmation for the thread. */
+    askDelete(root: CommentRecord): void;
+    notify(words: Words | string): void;
+}
+export interface UseCommentsOptions {
+    /** The list the view declares in `shows` for the Comments database. Default 'comments'. */
+    list?: string;
+    /** The database alias the list reads and writes (insert and update actions). Default 'comments'. */
+    database?: string;
+    /** The record the comments belong to. Null: every comment is shown and none is written with a scope. */
+    scope?: CommentScope | null;
+    /** The records threads sit on, in order. Empty: comments are not anchored. */
+    anchors?: readonly CommentAnchor[];
+    /** The anchor on screen (its record key): the pane's "this item" filter and where pins are placed. */
+    anchorKey?: string | null;
+    /** The person using the Space; their comments count as changes and never as new activity. Default 'Flo'. */
+    me?: string;
+    /** Authors the Author select knows; anyone else reads as `fallbackAuthor`. Default: any name. */
+    authors?: readonly string[];
+    fallbackAuthor?: string;
+    columns?: Partial<CommentColumns>;
+    /** Wording of the digest Copy changes puts on the clipboard. */
+    digest?: CommentDigestOptions;
+    /** Saves the checkpoint after a copy (for example the scope's "Last turn at"). A throw rolls the checkpoint back. */
+    onCheckpoint?(at: string): Promise<void>;
+    /** The Space's own wording on top of the defaults. */
+    words?: Partial<Record<CommentWordKey, Words>>;
+    pageSize?: number;
+    /** Follow the database's live feed where the host has one. Default true. */
+    live?: boolean;
+    /** Called when a thread is picked (a pin, a card): the Space can move to its anchor and open its panel. */
+    onSelectThread?(thread: CommentThread): void;
+}
+export interface CommentController {
+    comments: CommentRecord[];
+    /** Threads in the scope, deleted ones left out, in anchor order. */
+    threads: CommentThread[];
+    /** The threads the pane lists for the current filters. */
+    visibleThreads: CommentThread[];
+    /** Changes since the checkpoint: what Copy changes puts on the clipboard. */
+    changes: CommentRecord[];
+    checkpoint: string | null;
+    isNew(comment: CommentRecord): boolean;
+    threadsOn(anchorKey: string | null | undefined): CommentThread[];
+    /** The thread's pin number on its anchor (1-based), 0 when it is not there. */
+    numberOf(thread: CommentThread): number;
+    scope: CommentScope | null;
+    anchors: readonly CommentAnchor[];
+    anchorKey: string | null;
+    anchor: CommentAnchor | undefined;
+    filter: CommentAnchorFilter;
+    setFilter(filter: CommentAnchorFilter): void;
+    statusFilter: CommentStatusFilter;
+    setStatusFilter(filter: CommentStatusFilter): void;
+    threadKey: string | null;
+    setThreadKey(key: string | null): void;
+    selectThread(thread: CommentThread): void;
+    actions: CommentActions;
+    /** Add comment mode: the next click on the anchor drops a pin. Escape leaves it. */
+    commenting: boolean;
+    setCommenting(on: boolean): void;
+    toggleCommenting(): void;
+    draftPin: CommentDraftPin | null;
+    /**
+     * Starts a new comment on `anchorKey` at x, y (0 to 1), on a zone when w and h are given too, or on the whole
+     * anchor when x and y are null.
+     */
+    placePin(anchorKey: string | null, x: number | null, y: number | null, w?: number | null, h?: number | null): void;
+    /** In Add comment mode, drops a pin where the anchor element was clicked. True when a pin was placed. */
+    placePinFromEvent(event: ReactMouseEvent<HTMLElement>, anchorKey: string | null): boolean;
+    /** True when the table has zone columns: a drag in Add comment mode marks a zone instead of dropping a pin. */
+    zones: boolean;
+    /** The zone being dragged, while the button is held. */
+    dragZone: CommentDragZone | null;
+    /** In Add comment mode: a click on the element drops a pin, a press and drag marks a zone. */
+    zoneHandlers(anchorKey: string | null): CommentZoneHandlers;
+    cancelPin(): void;
+    /** Saves the new comment. True once saved. */
+    sendNew(body: string): Promise<boolean>;
+    deleting: CommentRecord | null;
+    cancelDelete(): void;
+    confirmDelete(): Promise<void>;
+    /** Copies the digest and records the checkpoint. `host` is the Space's own element, for the selection fallback. */
+    copyChanges(host: HTMLElement | null): Promise<boolean>;
+    copying: boolean;
+    /** Record keys with a write in flight. */
+    busy: ReadonlySet<string>;
+    now: number;
+    toaster: ToastController;
+    words: CommentWords;
+    /** A word in the reader's language, with `{n}`-style values filled. */
+    say(key: CommentWordKey, vars?: Readonly<Record<string, string | number>>): string;
+    locale: Locale;
+    me: string;
+    loading: boolean;
+    hasData: boolean;
+    error: Error | null;
+    refetch(): Promise<unknown>;
+}
+export declare function useComments(options?: UseCommentsOptions): CommentController;

package/dist/space-sdk/src/ui/engine/HelpSheet.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The one translated `?` sheet (toolkit spec 2.1), built from the live registry: only shortcuts that answer here
+ * and now are listed, "This Space" first, then "Notis". Rendered once by the host.
+ */
+export interface HelpSheetProps {
+    /**
+     * Where the sheet mounts. Default: the pinned overlay layer root (LayerRootProvider), else the top-level
+     * container of the page the engine listens on. The sheet is rendered once by the host, never by a Space.
+     */
+    container?: Element | DocumentFragment | null;
+}
+export declare function HelpSheet({ container }: HelpSheetProps): import("react").ReactPortal | null;

package/dist/space-sdk/src/ui/engine/KeyboardEngine.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import type { Locale, Platform } from '../../words';
+import type { KeyboardEngineCore } from './core';
+import { type ShortcutScopeOptions } from './hooks';
+import type { EngineHost } from './types';
+export interface KeyboardEngineProps {
+    host: EngineHost;
+    locale: Locale;
+    platform?: Platform;
+    /** Clashes throw (dev, design check). Default: true unless NODE_ENV is 'production'. */
+    strict?: boolean;
+    /** Production clash log (telemetry). */
+    onClash?: (message: string) => void;
+    /** An own core (tests). Default: the page's shared core. */
+    engine?: KeyboardEngineCore;
+    /** The document to listen on. Default: the global document. */
+    document?: Document;
+    children?: ReactNode;
+}
+/** The one keyboard listener of a page, at the Portal root (or the preview root). */
+export declare function KeyboardEngine(props: KeyboardEngineProps): import("react").JSX.Element;
+export interface ShortcutScopeProps extends ShortcutScopeOptions {
+    owner: string;
+    children?: ReactNode;
+}
+/** Owner of every shortcut below it: a Space, or a retained view that goes silent while hidden. */
+export declare function ShortcutScope({ owner, available, kind, children }: ShortcutScopeProps): import("react").JSX.Element;

package/dist/space-sdk/src/ui/engine/core.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one keyboard listener (toolkit spec 2.1). Document capture phase; React handlers no longer own keys.
+ * No React here: the React pieces (`KeyboardEngine`, hooks) drive one shared core.
+ */
+import { type Locale, type Platform } from '../../words';
+import { ShortcutRegistry } from './registry';
+import type { EngineSettings, ShortcutDef } from './types';
+/** Escape chain order, highest first: menus and dialogs, help sheet, selection clear, detail panel, route back. */
+export declare const ESCAPE_PRIORITY: Readonly<{
+    route: 0;
+    detail: 100;
+    selection: 200;
+    help: 300;
+    overlay: 400;
+}>;
+export declare const SEQUENCE_TIMEOUT_MS = 1500;
+export declare function detectPlatform(): Platform;
+export declare function detectLocale(): Locale;
+export declare class KeyboardEngineCore {
+    readonly registry: ShortcutRegistry;
+    settings: EngineSettings;
+    /** Mounted `<KeyboardEngine>` count. With none, settings hooks fall back to the document (lang). */
+    mounted: number;
+    /** Clock, replaceable in tests. */
+    now: () => number;
+    private layers;
+    private blockers;
+    private seq;
+    private held;
+    private pending;
+    private attached;
+    private helpOpen;
+    private helpUnregister;
+    private forcedRepeat;
+    constructor(settings?: Partial<EngineSettings>);
+    /** Updates settings. Returns true when one changed; listeners hear it unless `silent` (during a React render). */
+    configure(settings: Partial<EngineSettings>, options?: {
+        silent?: boolean;
+    }): boolean;
+    subscribe(listener: () => void): () => void;
+    getVersion(): number;
+    /** Starts listening on a document. Ref counted; the last detach removes the listeners. */
+    attach(doc: Document): () => void;
+    isAttached(doc: Document): boolean;
+    /** The first document the engine listens on (the host page), or null before KeyboardEngine mounts. */
+    attachedDocument(): Document | null;
+    private resetHeld;
+    register(def: ShortcutDef, owner?: string): (() => void) | null;
+    defineOwner: ShortcutRegistry['defineOwner'];
+    setOwnerAvailable(id: string, available: boolean): void;
+    isOwnerAvailable(id: string): boolean;
+    addEscapeLayer(id: string, onEscape: (event?: KeyboardEvent) => boolean, priority?: number): () => void;
+    addEscapeBlocker(priority?: number, isActive?: () => boolean): () => void;
+    escapeLayerIds(): string[];
+    private sortedLayers;
+    /**
+     * Runs the chain. True when a layer handled it. Called without an event by a Close button that means "Escape";
+     * from a key press each layer gets the keydown.
+     */
+    runEscapeChain(event?: KeyboardEvent): boolean;
+    isHelpOpen(): boolean;
+    openHelp(): void;
+    closeHelp(): void;
+    toggleHelp(): void;
+    private ensureHelpShortcut;
+    /** True for a key repeat, including a press of a key that is still held (some hosts drop `event.repeat`). */
+    isRepeat(event: KeyboardEvent): boolean;
+    handleKeyUp(event: KeyboardEvent): void;
+    handleKeyDown(event: KeyboardEvent): void;
+    private run;
+    /** True when Escape is fully handled here (nothing else should see it as a shortcut). */
+    private handleEscape;
+}

package/dist/space-sdk/src/ui/engine/hooks.d.ts

@@ -0,0 +1,64 @@
+/**
+ * React hooks of the keyboard engine (toolkit spec 2.1). Every hook works without a mounted `<KeyboardEngine>`
+ * (unit tests, a bare preview): registrations land in the shared core, which listens only once an engine mounts or
+ * `core.attach(document)` is called, and settings fall back to the document language and the browser platform.
+ */
+import { type Locale, type Platform } from '../../words';
+import { type KeyboardEngineCore } from './core';
+import type { EngineSettings, OwnerKind, ScopeHandle, ShortcutDef } from './types';
+/** The engine core in effect here: an injected one, else the shared one. */
+export declare function useEngineCore(): KeyboardEngineCore;
+/** The owner shortcuts register under: the nearest `<ShortcutScope>`, else 'notis'. */
+export declare function useShortcutOwner(): string;
+/** Toolkit language. Without a mounted engine: the document's `lang` ('fr...' gives 'fr', else 'en'). */
+export declare function useToolkitLocale(): Locale;
+/** 'mac' or 'other'. Without a mounted engine: detected from the browser. */
+export declare function useToolkitPlatform(): Platform;
+/** Host, locale, platform and strict mode. */
+export declare function useToolkitSettings(): Readonly<EngineSettings>;
+/**
+ * Registers one shortcut while mounted. Re-registers only when its id, keys, scope, owner, words or flags change
+ * (or `deps` change); `run` and `when` are read live.
+ */
+export declare function useShortcut(def: ShortcutDef, deps?: readonly unknown[]): void;
+/** Registers several shortcuts while mounted (same rules as `useShortcut`). */
+export declare function useShortcuts(defs: readonly ShortcutDef[], deps?: readonly unknown[]): void;
+export interface ShortcutScopeOptions {
+    /** False for a hidden retained view or a Space in the background: all its shortcuts go silent. */
+    available: boolean;
+    /** 'space' (default under the root) for Space code, 'host' for Notis pages. Inherited from the parent owner. */
+    kind?: OwnerKind;
+}
+/**
+ * Declares a Space or a retained view as an owner, nested under the current owner. Its shortcuts are those
+ * registered under a `<ShortcutScope owner>` with the same id (or with `def.owner`).
+ */
+export declare function useShortcutScope(owner: string, options: ShortcutScopeOptions): ScopeHandle;
+export interface EscapeLayerOptions {
+    /** Chain position (ESCAPE_PRIORITY). Default overlay. */
+    priority?: number;
+    /** False keeps the hook mounted without a layer. Default true. */
+    enabled?: boolean;
+}
+/**
+ * Adds a step to the Escape chain while mounted. `onEscape` returns true when it handled the key (the chain
+ * stops), false to let the next step run. Higher priority runs first; the latest wins within a priority. It gets the
+ * keydown when a key press runs the chain (none from `runEscapeChain()` without an event).
+ */
+export declare function useEscapeLayer(id: string, onEscape: (event?: KeyboardEvent) => boolean, options?: EscapeLayerOptions): void;
+/**
+ * Stops the Escape chain below `priority` while `active` (the composer holds text). Default priority sits between
+ * the detail panel and selection clear, so Escape still clears a selection but never leaves the page.
+ */
+export declare function useEscapeBlocker(active: boolean, options?: {
+    priority?: number;
+}): void;
+export interface HelpSheetControls {
+    open(): void;
+    close(): void;
+    toggle(): void;
+    isOpen: boolean;
+}
+export declare function useHelpSheet(): HelpSheetControls;
+/** Re-renders on every registry change (the help sheet, dev overlays). */
+export declare function useRegistryVersion(): number;

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

@@ -0,0 +1,14 @@
+export { ESCAPE_PRIORITY, SEQUENCE_TIMEOUT_MS, KeyboardEngineCore, detectLocale, detectPlatform } from './core';
+export { NotisKeyClash, ROOT_OWNER, ShortcutRegistry } from './registry';
+export type { DefineOwnerOptions, RegisteredShortcut, RegistryOptions } from './registry';
+export { getSharedInstance } from './instance';
+export type { SharedInstance } from './instance';
+export { useEngineCore, useEscapeBlocker, useEscapeLayer, useHelpSheet, useRegistryVersion, useShortcut, useShortcutOwner, useShortcutScope, useShortcuts, useToolkitLocale, useToolkitPlatform, useToolkitSettings, } from './hooks';
+export type { EscapeLayerOptions, HelpSheetControls, ShortcutScopeOptions } from './hooks';
+export { KeyboardEngine, ShortcutScope } from './KeyboardEngine';
+export type { KeyboardEngineProps, ShortcutScopeProps } from './KeyboardEngine';
+export { HelpSheet } from './HelpSheet';
+export type { HelpSheetProps } from './HelpSheet';
+export { stepCursor } from './step';
+export type { StepOptions } from './step';
+export type { EngineHost, EngineSettings, HelpEntry, OwnerKind, ScopeHandle, ShortcutDef, ShortcutGroup, } from './types';

package/dist/space-sdk/src/ui/engine/instance.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One engine per page, even when two copies of the toolkit load (a Space bundle that inlined `@notis/sdk/ui` by
+ * mistake). The first copy stores its core and React contexts on `globalThis` under a registered symbol; a second
+ * copy logs once and reuses them, so its shortcuts land in the same registry and its hooks read the same contexts.
+ */
+import { type Context } from 'react';
+import { KeyboardEngineCore } from './core';
+import type { KeycapOn } from './keycapContext';
+export interface SharedInstance {
+    readonly version: 1;
+    readonly core: KeyboardEngineCore;
+    /** An injected core (tests, preview) overrides the shared one below it. */
+    readonly EngineContext: Context<KeyboardEngineCore | null>;
+    /** The nearest `<ShortcutScope>` owner. */
+    readonly OwnerContext: Context<string>;
+    /** Keycap `on` default for a subtree (SelectionBar: pill, Menu and HelpSheet: discreet). */
+    readonly KeycapContext: Context<KeycapOn | null>;
+}
+export declare function getSharedInstance(): SharedInstance;
+/** Tests only: forget this module's cached instance (the global slot stays). */
+export declare function __resetSharedInstanceForTests(): void;

package/dist/space-sdk/src/ui/engine/keycapContext.d.ts

@@ -0,0 +1,2 @@
+/** Keycap surfaces (toolkit spec 2.2). */
+export type KeycapOn = 'surface' | 'chrome' | 'pill' | 'discreet' | 'tooltip';