@voithos-labs/aragonite 0.10.1

package/dist/editor-events.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Observer-pattern event surface reached via `getEvents()`. Events fire synchronously
+ * and handlers must NOT mutate the document; an `edit` event fires after its mutation
+ * is published, so its handler sees the updated document.
+ */
+import type { AnyBlockKind } from './core/nodes';
+import type { PresentationMode } from './presentation-mode';
+import type { EditorSelection } from './selection/primitives';
+import type { OpDescriptor, OperationDetailMap, OperationKind } from './schema/operations';
+/** Derived per-arm from OperationDetailMap — see schema/operations.ts. */
+export type EditEvent = {
+    [K in OperationKind]: undefined extends OperationDetailMap[K] ? {
+        op: K;
+        path: number[];
+        detail?: OperationDetailMap[K];
+        timestamp: number;
+    } : {
+        op: K;
+        path: number[];
+        detail: OperationDetailMap[K];
+        timestamp: number;
+    };
+}[OperationKind];
+/** The cast is sound by construction: both types derive from OperationDetailMap, which
+ *  TS cannot narrow as a correlated union. */
+export declare function toEditEvent(op: OpDescriptor, path: number[], timestamp: number): EditEvent;
+export type SelectionChangeEvent = EditorSelection | null;
+export interface EditorError {
+    /**
+     * `clipboard` is a failure on the paste route — the channel a host needs to release
+     * an asset `onPasteImage` already imported for it.
+     */
+    origin: 'subscriber' | 'render' | 'commit' | 'command' | 'decoration' | 'clipboard' | 'link';
+    error: unknown;
+    /** Origin-specific: `path` for render, `op`+`path` for commit, `kind`+`command`
+     *  (+`plugin`) for a command throw, `source` for decoration, `url` for link, and the
+     *  paste's start path for clipboard when it was aimed at a range. */
+    context?: {
+        path?: number[];
+        op?: OperationKind;
+        kind?: AnyBlockKind;
+        command?: string;
+        plugin?: string;
+        source?: string;
+        url?: string;
+    };
+}
+export interface EditorEventMap {
+    edit: EditEvent;
+    selectionChange: SelectionChangeEvent;
+    error: EditorError;
+    /** The EFFECTIVE mode after a `presentationMode` prop change (never fired at mount). */
+    presentationModeChange: PresentationMode;
+    /** The theme name after a `theme` prop change (never fired at mount), for a plugin
+     *  that paints its own colors and so cannot pick the change up from CSS. */
+    themeChange: string;
+}
+export interface EditorEvents {
+    on<K extends keyof EditorEventMap>(event: K, handler: (payload: EditorEventMap[K]) => void): () => void;
+    /** Internal emit — not exported from index.ts. */
+    emit<K extends keyof EditorEventMap>(event: K, payload: EditorEventMap[K]): void;
+}
+export declare function createEditorEvents(): EditorEvents;
+/**
+ * Route a contained command throw to the `error` channel, attributing the command and
+ * its owning plugin; no-ops when no events surface is present. A direct `plugin` wins
+ * over the kind lookup, so a global command's own owner is never clobbered by one.
+ */
+export declare function emitCommandError(events: EditorEvents | undefined, report: {
+    kind?: AnyBlockKind;
+    command: string;
+    plugin?: string;
+    error: unknown;
+}): void;
+/**
+ * Route a blocked link activation to the `error` channel: the scheme allowlist refused the URL,
+ * which a host may want to log or surface. Fires for the DEFAULT activation only — a consumer
+ * supplying `onLinkActivate` owns its own policy.
+ */
+export declare function emitBlockedLinkError(events: EditorEvents | undefined, url: string): void;
+/**
+ * Route a contained clipboard-route failure to the `error` channel. `path` addresses the
+ * range the paste was aimed at and is OMITTED where there is none to name — `[]` would
+ * report the document root, which holds no caret.
+ */
+export declare function emitClipboardError(events: EditorEvents, report: {
+    error: unknown;
+    path?: number[];
+}): void;

package/dist/editor-events.js

@@ -0,0 +1,96 @@
+/**
+ * Observer-pattern event surface reached via `getEvents()`. Events fire synchronously
+ * and handlers must NOT mutate the document; an `edit` event fires after its mutation
+ * is published, so its handler sees the updated document.
+ */
+import { devWarn } from './dev-warn';
+import { editorEnv } from './env';
+import { pluginKindOwner } from './schema/plugin-install';
+/** The cast is sound by construction: both types derive from OperationDetailMap, which
+ *  TS cannot narrow as a correlated union. */
+export function toEditEvent(op, path, timestamp) {
+    return { op: op.kind, path, detail: op.detail, timestamp };
+}
+// ── Factory ──────────────────────────────────────────────────────────────
+export function createEditorEvents() {
+    const handlers = {};
+    function on(event, handler) {
+        const set = (handlers[event] ??= new Set());
+        const erased = handler;
+        set.add(erased);
+        return () => {
+            set.delete(erased);
+        };
+    }
+    function emit(event, payload) {
+        const set = handlers[event];
+        if (!set)
+            return;
+        // Copy so self-disposing handlers don't mutate the set mid-iteration.
+        // try/catch per handler so one throwing subscriber doesn't starve others.
+        for (const handler of [...set]) {
+            try {
+                handler(payload);
+            }
+            catch (err) {
+                // Recursion guard: an error-channel subscriber's own throw reports rather than
+                // re-emitting, which would loop. Everything the channel cannot carry reds a gate.
+                if (event !== 'error' && handlers.error?.size) {
+                    emit('error', { origin: 'subscriber', error: err });
+                }
+                else if (editorEnv.isDev) {
+                    devWarn('events', `${event} subscriber threw`, err);
+                }
+                else {
+                    // devWarn is silent in production, and the swallow is what hides an exception the
+                    // consumer's own handler threw, which an unguarded call would have surfaced.
+                    console.error(`[aragonite] ${event} subscriber threw`, err);
+                }
+            }
+        }
+    }
+    return { on, emit };
+}
+// ── Contained-failure routing ──────────────────────────────────────────────
+// One envelope minter per origin with more than one emission site, living here so the
+// shell that owns the channel owns the payload shape too.
+/**
+ * Route a contained command throw to the `error` channel, attributing the command and
+ * its owning plugin; no-ops when no events surface is present. A direct `plugin` wins
+ * over the kind lookup, so a global command's own owner is never clobbered by one.
+ */
+export function emitCommandError(events, report) {
+    events?.emit('error', {
+        origin: 'command',
+        error: report.error,
+        context: {
+            kind: report.kind,
+            command: report.command,
+            plugin: report.plugin ?? (report.kind ? (pluginKindOwner(report.kind) ?? undefined) : undefined)
+        }
+    });
+}
+/**
+ * Route a blocked link activation to the `error` channel: the scheme allowlist refused the URL,
+ * which a host may want to log or surface. Fires for the DEFAULT activation only — a consumer
+ * supplying `onLinkActivate` owns its own policy.
+ */
+export function emitBlockedLinkError(events, url) {
+    events?.emit('error', {
+        origin: 'link',
+        error: new Error(`aragonite: blocked link with disallowed scheme: ${url}`),
+        context: { url }
+    });
+}
+/**
+ * Route a contained clipboard-route failure to the `error` channel. `path` addresses the
+ * range the paste was aimed at and is OMITTED where there is none to name — `[]` would
+ * report the document root, which holds no caret.
+ */
+export function emitClipboardError(events, report) {
+    events.emit('error', {
+        origin: 'clipboard',
+        error: report.error,
+        ...(report.path ? { context: { path: report.path } } : {})
+    });
+}

package/dist/editor-keys.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Svelte context-key symbols shared across the editor tree: three named facets
+ * (services, policies, document) plus the per-key survivors whose granularity is
+ * load-bearing — the action triple a container re-provides, HISTORY (G1.4's
+ * single-provider subject), the scope-provided channels. Internal wiring, not a plugin
+ * extension point; a facet object is not itself reactive, the getters it carries are.
+ */
+import type { Document } from './core/nodes';
+import type { LinkReferenceResolver } from './core/inline/link-reference-resolver';
+import type { ImageLoadPolicy } from './core/inline-render';
+import type { UserScrollport } from './cursor/scroll-ancestors';
+import type { Scrollport } from './cursor/scrollport';
+import type { PresentationMode } from './presentation-mode';
+import type { KeybindingOverrideMap } from './schema/keybinding-overrides';
+import type { EditorContext } from './schema/plugin-install';
+import type { RegistryView } from './schema/registry-view';
+import type { PluginActivation } from './schema/plugin-activation';
+import type { CrossBlockCommandRouter } from './schema/block-commands';
+import type { EditorRects } from './editor-rects';
+import type { EditorEvents } from './editor-events';
+import type { UndoController } from './editor-actions/deps';
+import type { ReorderAction } from './editor-actions/reorder-action';
+import type { PasteCommitCoordinator } from './tree-operations/paste/paste-deps';
+import type { SelectionState } from './selection/selection-state.svelte';
+import type { SearchState } from './search/search-state.svelte';
+import type { DecorationEngine } from './decorations/decoration-state.svelte';
+import type { StickyColumnState } from './cursor/sticky-column';
+import type { EdgeAffinityState } from './cursor/edge-affinity';
+import type { PendingMarksState } from './cursor/pending-marks';
+import type { RevealAnchorState } from './cursor/reveal-anchor';
+import type { HeightOracle } from './cursor/height-oracle';
+import type { WidgetSelectionState } from './components/image/widget-selection-state.svelte';
+import type { LinkCardState } from './components/link-card/link-card-state.svelte';
+export type ReorderAnnounce = (message: string) => void;
+export type KeybindingOverridesGetter = () => KeybindingOverrideMap;
+export type ResolveImageUrl = (rawUrl: string) => string;
+export type ResolveLinkUrl = (rawUrl: string) => string;
+/** One image file lifted off an image-bearing paste, handed to the host's import
+ *  hook. `suggestedName` is the clipboard's filename when it carried one. */
+export interface PastedImage {
+    blob: Blob;
+    mimeType: string;
+    suggestedName?: string;
+}
+/** Host import hook for pasted images: resolves to the markdown to insert, or null
+ *  to skip that image. Called once per image file, in clipboard order. */
+export type PasteImageHook = (image: PastedImage) => Promise<string | null>;
+export type PresentationModeGetter = () => PresentationMode;
+/** The editor's theme name, as reflected to `data-editor-theme`. An open string:
+ *  built-ins are `'dark'`/`'light'`, and a consumer may name its own. */
+export type ThemeGetter = () => string;
+/** `undefined` for a plugin installed in the process that this instance did not activate. */
+export type PluginEditorLookup = (pluginName: string) => EditorContext | undefined;
+export type BlockElLookup = (path: number[]) => HTMLElement | null;
+export type DocumentGetter = () => Document;
+export type FocusedPathGetter = () => number[] | null;
+export type VersionGetter = () => number;
+/** Resolver ref read by inline parsers in block components. Wrapped in a `{ current }`
+ *  accessor so the shell can rebuild it after each commit without invalidating
+ *  descendants' getContext bindings. `epoch` is the compact stamp render memos key on
+ *  instead of concatenating the whole (~MB-scale) `signature` every keystroke. */
+export type LinkReferenceResolverRef = {
+    current?: LinkReferenceResolver;
+    signature?: string;
+    epoch?: number;
+};
+export declare const BLOCK_EDIT_KEY: unique symbol;
+export declare const FOCUS_KEY: unique symbol;
+export declare const CONTAINER_EDIT_KEY: unique symbol;
+/** G1.4's subject: only the editor root provides history, so undo/redo resolve to one
+ *  stack. Folding it into a facet a container could re-provide is the exact violation. */
+export declare const HISTORY_KEY: unique symbol;
+export declare const LIST_CONTEXT_KEY: unique symbol;
+export declare const TABLE_CONTEXT_KEY: unique symbol;
+/**
+ * @internal A hosted block enrolls itself in its scope's batched measure pass.
+ * `register` no-ops when the path isn't a direct child of the scope's depth (nested
+ * hosts route to their own channel); `readHeight` is called inside the scope's
+ * read-all-then-write batch, never inline. `measureOnResize` carries the observer's
+ * border-box height so the scope can O(1)-gate and skip the no-op mount resize.
+ */
+export declare const RECORD_BLOCK_HEIGHT_KEY: unique symbol;
+export type BlockMeasureChannel = {
+    register: (path: number[], index: number, id: string, readHeight: () => number) => () => void;
+    measureNow: (id: string) => void;
+    measureOnResize: (id: string, observedHeight: number) => void;
+};
+/**
+ * @internal A child reports up to its parent scope: a nested CONTAINER pushes its box
+ * subtotal by index, while a `display:contents` ROW (no box of its own) enrolls in the
+ * batched measure pass instead, so a windowed table measures like every other scope.
+ */
+export declare const PARENT_SCOPE_SINK_KEY: unique symbol;
+export type ParentScopeSink = {
+    setChildSubtotal: (index: number, total: number) => void;
+    registerRow: (id: string, readHeight: () => number, applyHeight: (h: number) => void) => () => void;
+    measureRowNow: (id: string) => void;
+};
+/** Cross-cutting editor services: event seam, view-state stores, and the
+ *  cross-scope commit/reorder primitives. Root-provided once. */
+export declare const EDITOR_SERVICES_KEY: unique symbol;
+export interface EditorServices {
+    events: EditorEvents;
+    decorations: DecorationEngine;
+    selection: SelectionState;
+    search: SearchState;
+    stickyColumn: StickyColumnState;
+    /** Which side of an adjacent hidden marker run the caret means; the write seams read
+     *  it and keep their own default when it answers null. */
+    edgeAffinity: EdgeAffinityState;
+    /** The constructs a collapsed-caret toggle promised the next insertion. Invalidated with
+     *  the affinity, spent by the typing and composition seats. */
+    pendingMarks: PendingMarksState;
+    revealAnchor: RevealAnchorState;
+    widgetSelection: WidgetSelectionState;
+    /** The live-mode link card's target slot; `link.openCard` enters it from a kind's keymap. */
+    linkCard: LinkCardState;
+    controller: UndoController;
+    pasteCoordinator: PasteCommitCoordinator;
+    reorder: ReorderAction;
+    reorderAnnounce: ReorderAnnounce;
+    /** The instance's resolution over the global block definitions, so a per-instance
+     *  enablement filter reaches the render path. */
+    registryView: RegistryView;
+    /** The plugins this instance activated, so a paste site scopes the transform pipeline
+     *  the way `registryView` scopes the kinds. */
+    activePlugins: PluginActivation;
+    /** The instance's rect surface, delivered to every block component as a prop
+     *  so a block can measure/reveal/scroll by path through the one seam. */
+    rects: EditorRects;
+    /** The arm a format command takes while a cross-block range is painted, threaded into every
+     *  dispatch site's gates so the chord, the leaf rebind and the `runCommand` door share one. */
+    crossBlockCommands: CrossBlockCommandRouter;
+}
+/** Host-supplied render/behavior policies. The getter members read live editor state
+ *  on each call. */
+export declare const EDITOR_POLICIES_KEY: unique symbol;
+export interface EditorPolicies {
+    resolveImageUrl: ResolveImageUrl;
+    resolveLinkUrl: ResolveLinkUrl;
+    imageLoadPolicy: () => ImageLoadPolicy;
+    /** Getter-wrapped set-once flag: render the mouse-only hover affordances, the block drag
+     *  handle and the table grips. False renders neither; the keyboard routes stay regardless. */
+    blockDragHandles: () => boolean;
+    presentationMode: PresentationModeGetter;
+    /** For a renderer that paints rather than styles: a plugin emitting its own colored
+     *  markup (a diagram SVG) cannot pick the theme up from CSS, so it needs the name. */
+    theme: ThemeGetter;
+    keybindingOverrides: KeybindingOverridesGetter;
+    /** Set-once host import hook for image-bearing pastes. Required-nullable: a mount must
+     *  answer, and `undefined` deliberately leaves the paste on the text/plain path. */
+    onPasteImage: PasteImageHook | undefined;
+    /** Resolved image URLs that failed to load this session. One Set per instance, so a
+     *  failed load never suppresses another editor's broken-state recompute
+     *  (`components/image/widget-dom.ts`). */
+    brokenImageUrls: Set<string>;
+}
+/** Document identity and the per-instance lookups that hang off it. */
+export declare const EDITOR_DOC_KEY: unique symbol;
+export interface EditorDoc {
+    doc: DocumentGetter;
+    /** Changes whenever the document's bytes change — the only sound memo key over a
+     *  document whose `$state` proxy is mutated in place and never changes identity. */
+    contentVersion: () => number;
+    linkRef: LinkReferenceResolverRef;
+    /** Resolves a plugin's per-instance EditorContext — the one identity onEditor
+     *  callbacks, global-command handlers, and BlockCommandContext.editor share. */
+    pluginEditor: PluginEditorLookup;
+    /** AbortSignal tied to the editor's mount lifetime; document-level listeners
+     *  observe it to tear down if the editor unmounts mid-operation. */
+    lifetime: AbortSignal;
+    editorRoot: () => HTMLElement | null;
+    /** What a drag autoscrolls to reach more of this editor: the root in self mode, the
+     *  nearest USER-scrollable ancestor in host mode, null when the page's own viewport
+     *  scrolls. What BOUNDS the visible region is a separate answer held by the rect
+     *  surface — see `cursor/scroll-ancestors`. */
+    scrollHost: () => UserScrollport | null;
+    /** The same scroller as `scrollHost`, in the shape windowing measures and writes it
+     *  through. Null only before the root mounts. */
+    scrollport: () => Scrollport | null;
+    blockElLookup: BlockElLookup;
+    /** Live getter for the focused block's full path; drives per-level VR pins. */
+    focusedPath: FocusedPathGetter;
+    /** Per-kind height oracle (root-constructed); read by nested windowing scopes. */
+    heightOracle: HeightOracle;
+    /** True while the editor holds the reader's place through a height mutation rather than
+     *  leaving it to the host's native scroll anchoring. The `overflow-anchor` opt-out keys
+     *  off the same fact, so the two can never both write one scroll position. */
+    correctsScroll: () => boolean;
+    /** Monotonic width-change counter the root bumps on an editor width resize, so
+     *  every windowing scope rebuilds its model and re-measures at the new width. */
+    widthVersion: VersionGetter;
+    /** Monotonic counter the root bumps when the SCROLLPORT's height changes. Its own
+     *  signal, never `widthVersion`: a height resize re-wraps no prose, so bumping the
+     *  width counter would drop every measured height for nothing. */
+    viewportHeightVersion: VersionGetter;
+}

package/dist/editor-keys.js

@@ -0,0 +1,40 @@
+/**
+ * Svelte context-key symbols shared across the editor tree: three named facets
+ * (services, policies, document) plus the per-key survivors whose granularity is
+ * load-bearing — the action triple a container re-provides, HISTORY (G1.4's
+ * single-provider subject), the scope-provided channels. Internal wiring, not a plugin
+ * extension point; a facet object is not itself reactive, the getters it carries are.
+ */
+// ── Action triple (per-key: containers re-provide these three) ───────────────
+export const BLOCK_EDIT_KEY = Symbol('block-edit-actions');
+export const FOCUS_KEY = Symbol('focus-actions');
+export const CONTAINER_EDIT_KEY = Symbol('container-edit-actions');
+/** G1.4's subject: only the editor root provides history, so undo/redo resolve to one
+ *  stack. Folding it into a facet a container could re-provide is the exact violation. */
+export const HISTORY_KEY = Symbol('history-actions');
+// ── Scope-provided channels (per-key: scope provision IS their mechanism) ────
+export const LIST_CONTEXT_KEY = Symbol('list-context');
+export const TABLE_CONTEXT_KEY = Symbol('table-context');
+/**
+ * @internal A hosted block enrolls itself in its scope's batched measure pass.
+ * `register` no-ops when the path isn't a direct child of the scope's depth (nested
+ * hosts route to their own channel); `readHeight` is called inside the scope's
+ * read-all-then-write batch, never inline. `measureOnResize` carries the observer's
+ * border-box height so the scope can O(1)-gate and skip the no-op mount resize.
+ */
+export const RECORD_BLOCK_HEIGHT_KEY = Symbol('record-block-height');
+/**
+ * @internal A child reports up to its parent scope: a nested CONTAINER pushes its box
+ * subtotal by index, while a `display:contents` ROW (no box of its own) enrolls in the
+ * batched measure pass instead, so a windowed table measures like every other scope.
+ */
+export const PARENT_SCOPE_SINK_KEY = Symbol('parent-scope-sink');
+// ── Facets ───────────────────────────────────────────────────────────────────
+/** Cross-cutting editor services: event seam, view-state stores, and the
+ *  cross-scope commit/reorder primitives. Root-provided once. */
+export const EDITOR_SERVICES_KEY = Symbol('editor-services');
+/** Host-supplied render/behavior policies. The getter members read live editor state
+ *  on each call. */
+export const EDITOR_POLICIES_KEY = Symbol('editor-policies');
+/** Document identity and the per-instance lookups that hang off it. */
+export const EDITOR_DOC_KEY = Symbol('editor-doc');

package/dist/editor-props.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Public prop and instance-handle types for <Editor>. Editor.svelte annotates its
+ * $props() and instance surface against these, so neither can drift from the component.
+ */
+import type { Snippet } from 'svelte';
+import type { AnyBlockKind } from './core/nodes';
+import type { PasteImageHook, ResolveImageUrl, ResolveLinkUrl } from './editor-keys';
+import type { ImageLoadPolicy } from './core/inline-render';
+import type { PresentationMode } from './presentation-mode';
+import type { KeybindingOverride } from './schema/keybinding-overrides';
+import type { EditorSelection } from './selection/primitives';
+import type { EditorEvents } from './editor-events';
+import type { SearchState } from './search/search-state.svelte';
+import type { DecorationRegistry } from './decorations/types';
+import type { EditorRects } from './editor-rects';
+import type { EditorPluginEntry } from './schema/plugin-install';
+import type { InteractionTraceEntry } from './debug/interaction-trace';
+export type { EditorPluginEntry } from './schema/plugin-install';
+export type { InteractionTraceEntry } from './debug/interaction-trace';
+export interface EditorProps {
+    source?: string;
+    resolveImageUrl?: ResolveImageUrl;
+    resolveLinkUrl?: ResolveLinkUrl;
+    imageLoadPolicy?: ImageLoadPolicy;
+    onLinkActivate?: (url: string, event: MouseEvent) => void;
+    /** Import hook for image-bearing pastes, set once at mount. Each image file is offered
+     *  in order and the markdown returned is inserted at the caret; `null` skips it.
+     *  Installing it takes the WHOLE paste — the clipboard's `text/plain` is not pasted. */
+    onPasteImage?: PasteImageHook;
+    /** Host chrome rendered INSIDE the editor's scroll container, above the first block
+     *  (a title, properties panel, tag row). It scrolls away with the document rather than
+     *  pinning, which is what lets the editor keep its own scrollport and windowing. */
+    header?: Snippet;
+    /** Opt into the pointer affordances: the block drag handle and the table's row and column
+     *  grips (default off, so the surface stays gutter-free). A hover reveals them; touch, which
+     *  has none, shows them outright. Keyboard reorder (Alt+Arrow) and the cell menu are always
+     *  available and need no opt-in. */
+    blockDragHandles?: boolean;
+    searchBar?: boolean;
+    /** Where the editor's own find/replace bar renders. Default (absent) keeps it pinned inside
+     *  the editor root; an element relocates the SAME bar into it, theme scope included, so
+     *  host-scroll embeds can put it in a pane's chrome instead of mid-page. Read live, and
+     *  ignored while `searchBar` is false. Positioning inside it is the element's own business. */
+    searchBarAnchor?: HTMLElement | null;
+    /** Who owns the scroll, set once at mount. `'self'` (default) makes the root its own
+     *  scrollport. `'host'` lets an ancestor scroll it, and the editor windows against that
+     *  scroller instead — so the mounted set stays O(viewport) either way. The one behavioural
+     *  difference is scroll anchoring; the consumer guide's scrollMode section has the trade. */
+    scrollMode?: 'self' | 'host';
+    /** Theme name reflected to `data-editor-theme` on the editor root. Built-ins:
+     *  `'dark'` (default) and `'light'`; any other value activates a consumer's
+     *  own `.editor[data-editor-theme='<name>']` token block. */
+    theme?: string;
+    /** How the document presents, read live like `theme`; `'source'` by default. The consumer
+     *  guide's Presentation modes section describes what each rung shows and allows. */
+    presentationMode?: PresentationMode;
+    /** Per-instance keymap overrides over the built-in command vocabulary. */
+    keybindings?: KeybindingOverride[];
+    /** Plugins installed once, in array order, at mount. Set-once: a later change to
+     *  this prop is ignored — installation is process-global and cannot re-run. An
+     *  entry may be a bare unit or `{ plugin, options }` for per-instance options.
+     *  The array is the enablement set too: this editor activates exactly what it
+     *  lists, and no prop at all activates everything installed. */
+    plugins?: readonly EditorPluginEntry[];
+}
+/** The `bind:this` surface a consumer can name and hold a ref to. */
+export interface EditorInstance {
+    getSource(): string;
+    /**
+     * The block kind at `path` (child indices from the document root), or null when the path
+     * addresses no block: an out-of-range index, and the empty root path, which is the document
+     * itself. A read, not a handle: the node stays inside the editor. A plugin block answers its
+     * own declared kind name.
+     */
+    getBlockKindAt(path: number[]): AnyBlockKind | null;
+    getSelection(): EditorSelection | null;
+    /**
+     * Restore a `getSelection()` snapshot. Async because the target is scrolled into view
+     * first, and true means it got there, not merely that it mounted. Never throws: an
+     * out-of-range offset clamps in that endpoint's own coordinate space (a TABLE
+     * endpoint's row-major cell index clamps to the last cell, not a character position),
+     * and an unresolvable path or an unsettled scroll resolves false.
+     */
+    setSelection(selection: EditorSelection): Promise<boolean>;
+    /**
+     * Land the caret at a viewport point exactly as a click there would: the point clamps into the
+     * nearest block's box, the block under it resolves the landing, a live cross-block range ends
+     * first. For a shell owning chrome beside the document: the shell decides whether a click on
+     * its own territory comes here, the editor decides where the caret goes. False when no
+     * focusable landing resolves. A point below the whole document resolves against the CST, not
+     * the rendered slice: past a windowed-out tail it claims the point and lands after the reveal.
+     */
+    placeCaretAtPoint(x: number, y: number): boolean;
+    /**
+     * Insert markdown at the caret exactly as pasting it would, minus the clipboard: paste
+     * transforms, every container-aware strategy, delete-selection-first, one undo entry, and
+     * focus at the end of the insertion. True means the pipeline took the text, not that its
+     * commit has flushed — read the result back through the `edit` event. False, and nothing
+     * mutates, when this editor holds no caret, in reading mode, or at a gap caret.
+     */
+    insertMarkdown(md: string): boolean;
+    /**
+     * Run a command by id at the focused surface, no chord in the path, so a consumer's
+     * `keybindings` rebind cannot rewire a toolbar button. `TOOLBAR_COMMANDS` names the built-in
+     * ids; a plugin's global name resolves ahead of the focused block, its per-block one stays
+     * chord-only. Semantics match the chord: one undo entry, same caret — over a cross-block range
+     * a format toggle marks every block it touches, a table by its cells. False, and nothing mutates,
+     * on an unknown id, in reading mode, with nothing focused, and on the link editor over a range.
+     */
+    runCommand(commandId: string): boolean;
+    /**
+     * Whether `runCommand(id)` would reach that command's arm right now, asked at the seam that
+     * would run it, so a host can grey a toolbar button out instead of hiding the affordance.
+     * False wherever the door declines before dispatch: an unknown id, reading mode, a block-local
+     * id with nothing focused (a gap caret included, where only the global ids stay live), and the
+     * link editor while a cross-block range is painted. True is reachability, not success: the arm
+     * that would run still decides whether it writes, and over a range it may reach no block at all.
+     */
+    canRunCommand(commandId: string): boolean;
+    /**
+     * Whether the command's toggle-state reads ON where a press would land — the read a toolbar
+     * paints pressed from, answered by the same bytes the toggle would rewrite. State, not
+     * admissibility, so a disabled button may still paint pressed. Over a cross-block range the
+     * answer is the range's own coverage: true only where every block it touches carries the
+     * mark; the link editor reads ON inside the construct its card would edit, in live mode
+     * alone. False for an id with no state of its own, and with nothing focused.
+     */
+    isCommandActive(commandId: string): boolean;
+    getEvents(): EditorEvents;
+    getSearch(): SearchState;
+    getDecorations(): DecorationRegistry;
+    getRects(): EditorRects;
+    getDiagnostics(): EditorDiagnostics;
+    /**
+     * Every MODIFIER chord this instance consumes, normalized (`Mod` covers Ctrl and Cmd).
+     * Composed live from the kind keymaps, the command tables, the plugins this editor activated,
+     * the `keybindings` overrides and the search option, so a host accelerator table is derived,
+     * not hand-copied. Bare keys are out of contract: a focused document owns them. So is a
+     * DISABLED chord (`command: null`), released for the host to claim app-wide yet still
+     * swallowed INSIDE the editor, whose native fall-through would bypass the CST undo stack.
+     */
+    reservedChords(): ReadonlySet<string>;
+    /** Whether this instance consumes that keystroke, answered with the editor's own chord
+     *  normalization so a host never re-implements the Ctrl/Cmd fold. */
+    claimsChord(event: KeyboardEvent): boolean;
+}
+/**
+ * The diagnostics door: arm the interaction trace, read it, and serialize an attachable
+ * field report. The recorder ships default-off, so a consumer opts in, reproduces, then
+ * serializes. The trace is process-global — two instances interleave their entries.
+ */
+export interface EditorDiagnostics {
+    enableTrace(): void;
+    disableTrace(): void;
+    isTraceEnabled(): boolean;
+    traceSnapshot(): InteractionTraceEntry[];
+    /**
+     * A fenced-markdown snapshot (timestamp, trace tail, ops-log tail, selection). The
+     * document source is EXCLUDED by default; pass `{ includeSource: true }` to opt in.
+     */
+    serializeDiagnostics(opts?: {
+        includeSource?: boolean;
+    }): string;
+}

package/dist/editor-props.js

@@ -0,0 +1 @@
+export {};

package/dist/editor-rects.d.ts

@@ -0,0 +1,58 @@
+import type { BlockComponent } from './block-component';
+import type { RevealAnchorState } from './cursor/reveal-anchor';
+export interface EditorRects {
+    /** The block's outermost box, or null when it isn't mounted. */
+    blockRect(path: number[]): DOMRect | null;
+    /**
+     * Rects covering `[start, end)` in the block's measurable content — one per visual
+     * line on a wrapped prose leaf, one per cell on a grid surface. `SELECTION_END` is
+     * accepted as `end`. Empty when the block isn't mounted or can't measure.
+     */
+    rangeRects(path: number[], start: number, end: number): DOMRect[];
+    /**
+     * The live native single-block caret, or null — including in cross-block mode, whose
+     * parked range is not a caret and must not leak out as one.
+     */
+    caretRect(): DOMRect | null;
+    /** Scroll a windowed-out block into its window and await its mount. Resolves
+     *  true once the block's element is present. */
+    reveal(path: number[]): Promise<boolean>;
+    /**
+     * Reveal (mount) the block at `path`, then scroll the viewport to it. `block` defaults to
+     * `'nearest'`; `hold` (default true) keeps the reveal's pin afterward, so a later layout
+     * shift cannot push the target back out. Resolves true only once the position settles; a
+     * reveal superseded by a later one stops refining and reports honest visibility.
+     */
+    scrollTo(path: readonly number[], opts?: {
+        block?: 'nearest' | 'center';
+        hold?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Navigate to `path`: reveal, scroll, and land the caret at `offset` in it (default 0),
+     * so the next keystroke (Ctrl+Z included) addresses the document rather than the
+     * affordance that was clicked. Runs the same restore road undo and `setSelection` use.
+     * True means the caret landed AND the target settled into view.
+     */
+    navigateTo(path: readonly number[], offset?: number): Promise<boolean>;
+}
+export declare function createEditorRects(deps: {
+    getBlockElByPath: (path: number[]) => HTMLElement | null;
+    getBlockComponentByPath: (path: number[]) => BlockComponent | null;
+    revealPath: (path: number[]) => Promise<unknown>;
+    getEditorRoot: () => HTMLElement | null;
+    /** True when an ancestor owns the scroll (`scrollMode="host"`): the root is then no
+     *  scrollport but spans the WHOLE document, so intersecting a block with it answers
+     *  "is this in the document" rather than "is this visible". */
+    isHostScroll: () => boolean;
+    /** Host mode's ancestors that bound what can be seen. Intersected WITH the window
+     *  viewport, never instead of it: a bound that clips nothing would swallow the fold. */
+    getClipBounds: () => HTMLElement[];
+    isCrossBlock: () => boolean;
+    /** True for nodes in the host's `header` slot — inside the root, but not this
+     *  editor's content. */
+    isHostChrome: (node: Node | null) => boolean;
+    revealAnchor: RevealAnchorState;
+    /** Land a caret at a raw offset in `path` through the shared restore road. Injected
+     *  because this surface owns geometry, not the selection model. */
+    landCaretAt: (path: number[], offset: number) => Promise<boolean>;
+}): EditorRects;