@voithos-labs/aragonite 0.10.2 → 0.10.4

package/dist/editor-actions/focus/focus-dispatch.js

@@ -3,7 +3,7 @@
  * No Svelte context or reactivity; inputs are passed in as parameters.
  */
 import { CURSOR_END, CURSOR_START } from '../../block-component';
-import { consumeStickyLanding } from './focus-landing';
+import { consumeStickyLanding, verticalArrival } from './focus-landing';
 /** Move focus within a container, or delegate upward when out of range. */
 export async function dispatchMoveFocus(refs, innerIndex, position, stickyColumn, parent, scope = {}) {
     const { childCount, options, gapStop } = scope;
@@ -89,13 +89,16 @@ export function dispatchFocusAtColumn(refs, x, from) {
     if (refs.length === 0)
         return;
     const indices = from === 'above' ? refs.map((_, i) => i) : refs.map((_, i) => refs.length - 1 - i);
-    // Skip vertically-transparent refs so an entry from above/below lands on the
-    // first/last text-bearing child, not an image-only paragraph.
+    // Pass over transparent refs so an entry from above/below lands on the first/last
+    // text-bearing child.
     for (const i of indices) {
         const ref = refs[i];
         if (!ref?.focusable)
             continue;
-        if (ref.isVerticallyTransparent?.())
+        const arrival = verticalArrival(ref, from);
+        if (arrival === 'entered')
+            return;
+        if (arrival === 'transparent')
             continue;
         if (ref.focusAtColumn)
             ref.focusAtColumn(x, from);

package/dist/editor-actions/focus/focus-landing.d.ts

@@ -2,6 +2,15 @@
  * Shared cross-block landing tail for the focus dispatchers. Sticky-X null handling
  * lives here, so `focusAtColumn` receivers always get a finite x.
  */
-import { type BlockComponent, type FocusPosition } from '../../block-component';
+import { type BlockComponent, type FocusPosition, type StickyColumnDirection } from '../../block-component';
 import type { StickyColumnState } from '../../cursor/sticky-column';
 export declare function consumeStickyLanding(block: BlockComponent, index: number, position: FocusPosition, stickyColumn: StickyColumnState, retryAt: (index: number) => Promise<void> | void): Promise<void>;
+/** What a vertical arrival does at a block: enter its widget, pass over it, or seat a caret. */
+export type VerticalArrival = 'entered' | 'transparent' | 'seat';
+/**
+ * The vertical stop rule, asked by both vertical doors: the per-block landing and a container's
+ * column entry. A widget-only block carries no column, so it is passed over unless its edge widget
+ * takes the arrival, which is a stop of its own and reads alike from either side. `'entered'` means
+ * the widget ALREADY took it, so the caller stops rather than repeating the entry.
+ */
+export declare function verticalArrival(block: BlockComponent, from: StickyColumnDirection): VerticalArrival;

package/dist/editor-actions/focus/focus-landing.js

@@ -5,12 +5,15 @@
 import { CURSOR_END, CURSOR_START } from '../../block-component';
 export async function consumeStickyLanding(block, index, position, stickyColumn, retryAt) {
     const isStickyMove = typeof position === 'object' && 'stickyColumnFrom' in position;
-    // Widget-only blocks contribute no column landing, so ArrowUp/Down passes through.
-    // Horizontal moves still stop at the widget edge.
-    if (isStickyMove && block.isVerticallyTransparent?.()) {
-        const direction = position.stickyColumnFrom === 'below' ? -1 : 1;
-        await retryAt(index + direction);
-        return;
+    if (isStickyMove) {
+        const from = position.stickyColumnFrom;
+        const arrival = verticalArrival(block, from);
+        if (arrival === 'entered')
+            return;
+        if (arrival === 'transparent') {
+            await retryAt(index + (from === 'below' ? -1 : 1));
+            return;
+        }
     }
     // Enter an edge widget rather than dropping a no-op caret at its boundary, so the
     // arrow key produces one visible step.
@@ -37,3 +40,14 @@ export async function consumeStickyLanding(block, index, position, stickyColumn,
     else
         block.focus(CURSOR_END);
 }
+/**
+ * The vertical stop rule, asked by both vertical doors: the per-block landing and a container's
+ * column entry. A widget-only block carries no column, so it is passed over unless its edge widget
+ * takes the arrival, which is a stop of its own and reads alike from either side. `'entered'` means
+ * the widget ALREADY took it, so the caller stops rather than repeating the entry.
+ */
+export function verticalArrival(block, from) {
+    if (!block.isVerticallyTransparent?.())
+        return 'seat';
+    return block.enterEdgeWidget?.(from === 'above' ? 'start' : 'end') ? 'entered' : 'transparent';
+}

package/dist/editor-actions/inline-range-commit.js

@@ -5,7 +5,7 @@
  */
 import { docPathFrom } from '../cursor/coordinate-spaces';
 import { expectStateForNode } from '../reactivity/state-registry';
-import { isBlockNode, nodeAt, normalizeOwnRaw, writeOwnRaw } from '../tree-operations/node-ops';
+import { isBlockNode, nodeAt, normalizeOwnRaw, writeOwnRaw } from '../tree-operations/node-primitives';
 import { ensureUnsharedChild, ensureUnsharedPath } from '../tree-operations/unshare';
 export function createInlineRangeCommit(deps) {
     async function commitInlineRange(path, start, end, bytes, caretAfter) {

package/dist/editor-actions/plugin/container.d.ts

@@ -87,6 +87,13 @@ export interface ContainerBlock {
      * entry and windowing reveal. False for a modified or non-arrow key: leave it native.
      */
     moveFocusOut(e: KeyboardEvent): boolean;
+    /**
+     * The reader's scroll position, captured now. Call before a state flip that swaps this
+     * block's view for one of a different height, then await the returned restore: the
+     * scrollport is back where it was once the swap has flushed. A reveal in flight outranks
+     * it and the restore stands down.
+     */
+    captureScrollPosition(): () => Promise<void>;
 }
 /**
  * Collapse-ness has ONE definition: the descriptor's `reservedChrome.isCollapsed`

package/dist/editor-actions/plugin/container.js

@@ -13,6 +13,7 @@ import { eventToChord } from '../../schema/keybindings';
 import { isReadingMode } from '../../presentation-mode';
 import { devWarn } from '../../dev-warn';
 import { BLOCK_EDIT_KEY, CONTAINER_EDIT_KEY, EDITOR_DOC_KEY, EDITOR_POLICIES_KEY, EDITOR_SERVICES_KEY, FOCUS_KEY, HISTORY_KEY } from '../../editor-keys';
+import { captureScrollPosition } from '../../cursor/scroll-hold';
 import { emitCommandError } from '../../editor-events';
 import { owningPluginEditor } from '../../schema/plugin-install';
 import { createBlockListState } from '../../reactivity/block-list-state.svelte';
@@ -130,7 +131,7 @@ export function createContainerBlock(deps) {
     const parentFocus = getContext(FOCUS_KEY);
     const parentContainerEdit = getContext(CONTAINER_EDIT_KEY);
     const history = getContext(HISTORY_KEY);
-    const { stickyColumn, edgeAffinity, selection, reorder, events: editorEvents, registryView, activePlugins } = getContext(EDITOR_SERVICES_KEY);
+    const { stickyColumn, edgeAffinity, selection, reorder, revealAnchor, events: editorEvents, registryView, activePlugins } = getContext(EDITOR_SERVICES_KEY);
     const { keybindingOverrides, presentationMode: getPresentationMode, theme: getTheme } = getContext(EDITOR_POLICIES_KEY);
     const editorDoc = getContext(EDITOR_DOC_KEY);
     const pluginEditor = editorDoc?.pluginEditor;
@@ -344,6 +345,7 @@ export function createContainerBlock(deps) {
         updateOwnMetadata,
         handleKeydown,
         moveFocusOut,
+        captureScrollPosition: () => captureScrollPosition(deps.getBoxEl(), () => revealAnchor.get() !== null),
         getPresentationMode,
         getTheme,
         getOptions

package/dist/editor-actions/reorder-action.js

@@ -9,7 +9,7 @@
 import { CURSOR_START } from '../block-component';
 import { reorderChildrenWithTrivia } from '../tree-operations/reorder';
 import { resolveReorderUnit } from '../tree-operations/reorder-unit';
-import { blockNodeAt, nodeAt } from '../tree-operations/node-ops';
+import { blockNodeAt, nodeAt } from '../tree-operations/node-primitives';
 import { renumberOrderedList } from '../tree-operations/list/ordered-markers';
 import { expectStateForNode } from '../reactivity/state-registry';
 import { readCurrentSelection } from '../selection/native-bridge';
@@ -25,7 +25,7 @@ export function createReorderAction(deps, controller, onReorder) {
     function caretOffset() {
         return readCurrentSelection(deps.selectionState, deps.blockRefs)?.focus.offset ?? 0;
     }
-    async function commitReorder(unit, to, offset) {
+    async function commitReorder(unit, to, offset, focusAfter) {
         let landing = to;
         if (unit.scope === 'document') {
             await controller.commitStructural({
@@ -36,11 +36,14 @@ export function createReorderAction(deps, controller, onReorder) {
                     eventPath: docPathFrom([unit.index])
                 },
                 mutate: (children) => {
-                    const settled = reorderChildrenWithTrivia(children, unit.index, to, deps.sharing);
+                    const settled = reorderChildrenWithTrivia(children, unit.index, to, deps.sharing, true);
                     landing = settled.landing;
                     return settled.change;
                 },
-                afterTick: () => deps.blockRefs[landing]?.focus(CURSOR_START)
+                afterTick: () => {
+                    if (focusAfter)
+                        deps.blockRefs[landing]?.focus(CURSOR_START);
+                }
             });
             return { landing, total: deps.doc.children.length };
         }
@@ -69,7 +72,10 @@ export function createReorderAction(deps, controller, onReorder) {
                 }
                 return settled.change;
             },
-            afterTick: () => state.innerBlockRefs[landing]?.focus(CURSOR_START)
+            afterTick: () => {
+                if (focusAfter)
+                    state.innerBlockRefs[landing]?.focus(CURSOR_START);
+            }
         });
         // Re-resolved, not `parent`: the ceremony's copy-on-write replaced that node, so the one
         // this action resolved still holds the pre-move children.
@@ -86,19 +92,22 @@ export function createReorderAction(deps, controller, onReorder) {
             return null;
         return { unit, to };
     }
-    async function run(fromPath, computeTo) {
+    async function run(fromPath, computeTo, focusAfter) {
         const target = resolveAndClamp(fromPath, computeTo);
         if (!target)
             return;
         // Drop any cross-block selection so the overlay doesn't fight the move; the
-        // commit's afterTick re-places the caret.
+        // commit's afterTick re-places the caret when the caller wants it.
         deps.selectionState.collapse();
-        const outcome = await commitReorder(target.unit, target.to, caretOffset());
+        const outcome = await commitReorder(target.unit, target.to, caretOffset(), focusAfter);
         if (outcome)
             onReorder?.(outcome.landing, outcome.total);
     }
     return {
-        moveReorderUnit: (fromPath, toIndex) => run(fromPath, () => toIndex),
-        nudgeReorderUnit: (fromPath, dir) => run(fromPath, (index) => index + dir)
+        // A dropped block is not a block you asked to edit: focusing it opens whatever a caret
+        // opens there (an equation reveals its source), which is not what a drag asked for.
+        // The keyboard nudge is the opposite — the caret must ride the block it is moving.
+        moveReorderUnit: (fromPath, toIndex) => run(fromPath, () => toIndex, false),
+        nudgeReorderUnit: (fromPath, dir) => run(fromPath, (index) => index + dir, true)
     };
 }

package/dist/editor-actions/reorder-drag.js

@@ -144,9 +144,37 @@ function indexOf(host) {
         return readBlockPath(host)?.at(-1) ?? null;
     return readBlockPath(host.querySelector('[data-block-path]'))?.at(-2) ?? null;
 }
+/**
+ * What the block IS, for the kinds whose text does not read as a label: a table's cells run
+ * together into `IngredientAmountWater35 L`, an equation reads as its own source. Prose keeps
+ * its first words, which is the best label it could have.
+ */
+const KIND_LABELS = {
+    table: 'Table',
+    mathBlock: 'Equation',
+    fencedCode: 'Code',
+    mermaid: 'Diagram',
+    thematicBreak: 'Divider',
+    details: 'Details',
+    image: 'Image'
+};
 function ghostLabel(host) {
+    const kind = host.dataset.blockKind ?? '';
+    if (kind === 'table')
+        return tableLabel(host);
+    const named = KIND_LABELS[kind];
+    if (named)
+        return named;
     const text = (host.textContent ?? '').trim().replace(/\s+/g, ' ');
     if (!text)
-        return 'block';
+        return host.querySelector('[data-image-widget]') ? 'Image' : 'Block';
     return text.length > 40 ? text.slice(0, 40) + '…' : text;
 }
+/** Body rows × columns: the shape is what tells one table from another at a glance. */
+function tableLabel(host) {
+    const rows = host.querySelectorAll('.table-row').length;
+    const cols = host.querySelector('.table-row')?.childElementCount ?? 0;
+    if (rows === 0 || cols === 0)
+        return 'Table';
+    return `Table · ${rows} × ${cols}`;
+}

package/dist/editor-actions/replacement-focus.d.ts

@@ -3,7 +3,7 @@
  * probe that picks structural-vs-typing, and the post-commit caret restore.
  */
 import { updateNodeContent } from '../tree-operations';
-import { type SettledContent } from '../tree-operations/node-ops';
+import { type SettledContent } from '../tree-operations/content-write';
 import { type AnyBlockKind } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
 import type { StructuralChange } from '../tree-operations/structural-change';

package/dist/editor-actions/replacement-focus.js

@@ -3,7 +3,7 @@
  * probe that picks structural-vs-typing, and the post-commit caret restore.
  */
 import { updateNodeContent } from '../tree-operations';
-import { settledCaretTarget } from '../tree-operations/node-ops';
+import { settledCaretTarget } from '../tree-operations/content-write';
 import { makeBlockNode } from '../core/nodes';
 import { readBlockPath } from '../selection/path-lookup';
 // ── Reparse probe ────────────────────────────────────────────────────────────

package/dist/editor-actions/search-replace.js

@@ -2,7 +2,7 @@ import { parse } from '../core/parser';
 import { cloneNode } from '../tree-operations/clone';
 import { spliceMany } from '../tree-operations/splice-many';
 import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
-import { normalizeBodyWrite, normalizeReplacementTrivia, writeOwnRaw } from '../tree-operations/node-ops';
+import { normalizeBodyWrite, normalizeReplacementTrivia, writeOwnRaw } from '../tree-operations/node-primitives';
 import { rebuildAncestryRaw } from '../schema/container-raw';
 import { replacePreservingFirst, stampStructuralChange } from '../tree-operations/structural-change';
 import { applyRangesToText } from '../search/replace';

package/dist/editor-actions/table-context.d.ts

@@ -4,6 +4,7 @@
  * live here.
  */
 import type { CellPosition, ContainerEditActions, TableContext } from '../action-contracts';
+import type { GrammarView } from '../schema/block-openers';
 import type { NodeView } from '../core/node-views';
 import type { UndoController } from './deps';
 import type { BlockListState } from '../reactivity/block-list-state.svelte';
@@ -29,6 +30,8 @@ export interface TableMutationsContextDeps {
     controller: UndoController;
     focusCell: (rowIdx: number, colIdx: number, position: CellPosition) => void;
     announceReorder: (message: string) => void;
+    /** The instance grammar the cell byte-write door threads (absent: the global one). */
+    grammar?: GrammarView;
 }
-export type TableMutationsContext = Pick<TableContext, 'insertRowAbove' | 'insertRowBelow' | 'insertColumnLeft' | 'insertColumnRight' | 'deleteRow' | 'deleteColumn' | 'reorderRowTo' | 'moveRowUp' | 'moveRowDown' | 'reorderColumnTo' | 'moveColumnLeft' | 'moveColumnRight' | 'cycleAlignment' | 'setColumnAlignment'>;
+export type TableMutationsContext = Pick<TableContext, 'insertRowAbove' | 'insertRowBelow' | 'insertColumnLeft' | 'insertColumnRight' | 'deleteRow' | 'deleteColumn' | 'reorderRowTo' | 'moveRowUp' | 'moveRowDown' | 'reorderColumnTo' | 'moveColumnLeft' | 'moveColumnRight' | 'cycleAlignment' | 'setColumnAlignment' | 'pasteGrid'>;
 export declare function createTableMutationsContext(deps: TableMutationsContextDeps): TableMutationsContext;

package/dist/editor-actions/table-context.js

@@ -8,8 +8,9 @@ import { extendDocPath, docPathFrom } from '../cursor/coordinate-spaces';
 import { getStateForNode } from '../reactivity/state-registry';
 import { assertInvariant } from '../assert';
 import { columnAligned, COLUMN_ALIGNMENT_CLEARED, DELETED_COLUMN, DELETED_ROW, INSERTED_COLUMN, INSERTED_ROW, movedColumnToPosition, movedRowToPosition } from '../a11y-strings';
-import { ensureUnsharedChildren } from '../tree-operations/unshare';
+import { ensureUnsharedChildren, ensureUnsharedSubtree } from '../tree-operations/unshare';
 import { rebuildTableRowRaw, rebuildTableRaw } from '../schema/container-rebuilders';
+import { writeOwnRaw } from '../tree-operations/node-primitives';
 import { reorderChildren } from '../tree-operations/reorder';
 import { insertEmptyRow, insertEmptyColumn, deleteRow as mutDeleteRow, deleteColumn as mutDeleteColumn, moveColumn as mutMoveColumn, cycleAlignment as mutCycleAlignment, setAlignment as mutSetAlignment, canDeleteRow, canDeleteColumn } from '../tree-operations/table-mutations';
 /**
@@ -105,6 +106,60 @@ export function createTableMutationsContext(deps) {
             afterTick: opts.afterTick
         });
     }
+    // Grown at the bottom and the right only, so each scope's change is one contiguous insert:
+    // rows for the table, cells for every mounted row. Cell texts go through the cell kind's own
+    // raw rule in place, and the table raw is rebuilt once, delimiter line included.
+    async function pasteGrid(origin, grid) {
+        const { myPath, controller, focusCell } = deps;
+        const rows = grid.length;
+        let cols = 0;
+        for (const line of grid)
+            cols = Math.max(cols, line.length);
+        if (rows === 0 || cols === 0)
+            return;
+        const { scopes, rowIndices } = mountedColumnScopes();
+        await controller.commitMultiScope({
+            scopes,
+            snapshot: { path: docPathFrom(myPath), offset: 0 },
+            mutate: ([tableScope, ...rowScopes]) => {
+                // Subtree, not children: the cell writes below land at depth two, and a row's
+                // cells stay shared with the undo snapshot when only the rows are unshared —
+                // the write would go through it and undo would restore the pasted bytes.
+                ensureUnsharedSubtree(tableScope.node, tableScope.sharing);
+                assertInvariant('column-scope-alignment', () => rowScopes.every((s, i) => s.node === tableScope.node.children?.[rowIndices[i]])
+                    ? null
+                    : {
+                        code: 'column-scope-alignment',
+                        message: 'pasteGrid: row scopes misaligned with owned table children'
+                    });
+                const table = tableScope.node;
+                const oldRows = table.children?.length ?? 0;
+                const oldCols = metadataOf(table, 'table').columnCount;
+                const needRows = origin.rowIdx + rows;
+                const needCols = origin.colIdx + cols;
+                for (let r = oldRows; r < needRows; r++)
+                    insertEmptyRow(table, r - 1, 'below');
+                for (let c = oldCols; c < needCols; c++)
+                    insertEmptyColumn(table, c - 1, 'right');
+                grid.forEach((line, r) => {
+                    const cells = table.children[origin.rowIdx + r].children;
+                    line.forEach((text, c) => writeOwnRaw(cells[origin.colIdx + c], text, deps.grammar));
+                });
+                rebuildTableRaw(table);
+                const addedRows = needRows - oldRows;
+                const addedCols = needCols - oldCols;
+                const tableChange = addedRows > 0 ? { op: 'insert', at: oldRows, count: addedRows } : { op: 'noop' };
+                const rowChange = addedCols > 0 ? { op: 'insert', at: oldCols, count: addedCols } : { op: 'noop' };
+                return [tableChange, ...rowScopes.map(() => rowChange)];
+            },
+            op: {
+                kind: 'tablePasteGrid',
+                detail: { rowIdx: origin.rowIdx, colIdx: origin.colIdx, rows, cols },
+                eventPath: docPathFrom(myPath)
+            },
+            afterTick: () => focusCell(origin.rowIdx + rows - 1, origin.colIdx + cols - 1, 'end')
+        });
+    }
     async function insertColumn(colIdx, side) {
         const { focusCell, focusedCell } = deps;
         const insertAt = side === 'left' ? colIdx : colIdx + 1;
@@ -187,6 +242,7 @@ export function createTableMutationsContext(deps) {
     return {
         insertRowAbove: (rowIdx) => insertRow(rowIdx, 'above'),
         insertRowBelow: (rowIdx) => insertRow(rowIdx, 'below'),
+        pasteGrid,
         insertColumnLeft: (colIdx) => insertColumn(colIdx, 'left'),
         insertColumnRight: (colIdx) => insertColumn(colIdx, 'right'),
         reorderRowTo,

package/dist/editor-events.d.ts

@@ -54,6 +54,9 @@ export interface EditorEventMap {
     /** 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;
+    /** `true` when an editor-owned menu (right-click, insert `+`) opens, `false` when it closes,
+     *  so host chrome over the selection can step aside rather than stack on it. */
+    menuChange: boolean;
 }
 export interface EditorEvents {
     on<K extends keyof EditorEventMap>(event: K, handler: (payload: EditorEventMap[K]) => void): () => void;

package/dist/editor-keys.d.ts

@@ -45,6 +45,35 @@ export interface PastedImage {
 /** 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>;
+/** What a code block hands its host when the run affordance is pressed. */
+export interface CodeRunRequest {
+    /** The fence body alone — opener and closer lines excluded. */
+    code: string;
+    /** The opener's full info string, untrimmed of trailing attributes (`py {1-3}`). */
+    info: string;
+    /** Child indices from the document root to this block. */
+    path: number[];
+}
+/**
+ * Host hook for executing a code block. The editor runs nothing itself: installing this is
+ * what puts the run affordance on the block's rail, and the host owns everything after —
+ * the engine, the result, and where output goes. Absent, no run affordance renders.
+ */
+export type RunCodeHook = (request: CodeRunRequest) => void;
+/** One entry in a code block's overflow menu. `run` is called with the menu already closed. */
+export interface CodeMenuItem {
+    id: string;
+    label: string;
+    run: () => void;
+    /** Renders dimmed and refuses activation. */
+    disabled?: boolean;
+}
+/**
+ * Host hook for the code block's overflow menu, consulted each time the menu opens so the
+ * items can read live state. Absent — or returning nothing — renders no overflow affordance:
+ * the editor has no app-level actions of its own to put there.
+ */
+export type CodeMenuItemsHook = (request: CodeRunRequest) => readonly CodeMenuItem[];
 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. */
@@ -150,6 +179,10 @@ export interface EditorPolicies {
     /** 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;
+    /** Set-once host execution hook; its presence is what renders the run affordance. */
+    onRunCode: RunCodeHook | undefined;
+    /** Set-once host menu hook; its presence is what renders the overflow affordance. */
+    codeMenuItems: CodeMenuItemsHook | 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`). */

package/dist/editor-props.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Snippet } from 'svelte';
 import type { AnyBlockKind } from './core/nodes';
-import type { PasteImageHook, ResolveImageUrl, ResolveLinkUrl } from './editor-keys';
+import type { CodeMenuItemsHook, PasteImageHook, ResolveImageUrl, ResolveLinkUrl, RunCodeHook } from './editor-keys';
 import type { ImageLoadPolicy } from './core/inline-render';
 import type { PresentationMode } from './presentation-mode';
 import type { KeybindingOverride } from './schema/keybinding-overrides';
@@ -27,16 +27,29 @@ export interface EditorProps {
      *  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;
+    /** Execution hook for code blocks, set once at mount. The editor runs nothing itself:
+     *  installing this is what puts the run affordance on a code block's rail, and the host
+     *  owns the engine, the result, and where output goes. Absent, no run affordance renders. */
+    onRunCode?: RunCodeHook;
+    /** Overflow-menu hook for code blocks, set once at mount and consulted each time a menu
+     *  opens so items can read live state. Absent, or returning nothing, renders no overflow
+     *  affordance — the editor has no app-level actions of its own to offer there. */
+    codeMenuItems?: CodeMenuItemsHook;
     /** 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. */
+    /** The block drag handle (default on; reading mode never shows it). A hover reveals it;
+     *  touch, which has none, shows it outright. Only the blocks a reader picks up whole carry
+     *  one — code, tables, equations, diagrams, pictures, list items, dividers, cards — never
+     *  prose (paragraph, heading, quote, note). `false` removes them, except on a picture,
+     *  whose grip is the only pointer road to move it. Keyboard reorder (Alt+Arrow) is always
+     *  available, as is the table's right-click cell menu. */
     blockDragHandles?: boolean;
     searchBar?: boolean;
+    /** The editor's own formatting popover beside a prose selection (default on; reading mode
+     *  never shows it). A host with its own bar over `runCommand` passes false. */
+    selectionToolbar?: 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
@@ -102,14 +115,13 @@ export interface EditorInstance {
      */
     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.
+     * Run a command by id at the focused surface, or across a painted range where the id has a
+     * cross-block arm (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. `arg` reaches the arm as a keybinding's argument would (`heading.cycle`
+     * takes the level, 0 for plain text); an arm that takes none ignores it.
      */
-    runCommand(commandId: string): boolean;
+    runCommand(commandId: string, arg?: unknown): 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.

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { default as Editor } from './components/Editor.svelte';
 export type { EditorProps, EditorInstance } from './editor-props';
 export type { EditorDiagnostics, InteractionTraceEntry } from './editor-props';
 export type { BlockComponent } from './block-component';
-export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook } from './editor-keys';
+export type { ResolveImageUrl, ResolveLinkUrl, PastedImage, PasteImageHook, CodeRunRequest, RunCodeHook, CodeMenuItem, CodeMenuItemsHook } from './editor-keys';
 export type { ImageLoadPolicy } from './core/inline-render';
 export type { PresentationMode } from './presentation-mode';
 export type { SearchState, SearchOptions } from './search/search-state.svelte';

package/dist/plugin.d.ts

@@ -29,9 +29,15 @@ export type { OuterBlockScan } from './schema/block-openers';
 export { OPENER_PRIORITIES } from './schema/opener-priorities';
 export { registerBlockCompleter } from './schema/block-completions';
 export type { BlockCompleter, CompletionResult } from './schema/block-completions';
+export { registerLanguage, listLanguages, getLanguageAliases } from './components/blocks/code/code-languages';
+export type { LanguageGrammar } from './components/blocks/code/code-languages';
+export { tokenizeBody as highlightCode } from './components/blocks/code/code-renderer';
+export type { LanguageFn } from 'highlight.js';
 export type { CommandId } from './schema/commands';
 export type { KeyBinding } from './schema/keybindings';
 export { registerBlockCommand } from './schema/block-commands';
+export { registerBlockContextActions } from './schema/context-actions';
+export type { BlockContextAction, BlockActionContext, BlockContextActionProvider } from './schema/context-actions';
 export type { BlockCommandContext, BlockCommandHandler } from './schema/block-commands';
 export type { PluginCommandId, AnyCommandId } from './schema/command-id';
 export { registerGlobalCommand } from './schema/global-commands';
@@ -97,6 +103,7 @@ export { caretOffsetAtPoint } from './cursor/point-offset';
 export type { CaretTarget } from './schema/block-kind-descriptor';
 export { CURSOR_END } from './block-component';
 export type { CursorEnd } from './block-component';
+export { POINTER_GESTURE_ATTR } from './selection/pointer-gesture';
 export type { EditorSelection, SelectionPoint } from './selection/primitives';
 export { SELECTION_END } from './block-component';
 export type { SelectionEnd } from './block-component';

package/dist/plugin.js

@@ -38,9 +38,21 @@ export { OPENER_PRIORITIES } from './schema/opener-priorities';
 // never type into existence: a completer reads one typed line and answers the lines that
 // complete it, plus where the caret seats inside the mint.
 export { registerBlockCompleter } from './schema/block-completions';
+// ── Code-block languages (pre-freeze) ────────────────────────────────────────
+// The registry behind fenced-code highlighting. The editor bootstraps a curated set (every
+// grammar is bundle weight for every consumer), so a host needing more registers them itself,
+// BEFORE mounting an editor: a block on screen re-tokenizes only when its bytes next change.
+// An unregistered language is not an error — the fence still round-trips, just untokenized.
+// `listLanguages` lists each language once; `getLanguageAliases` holds the other spellings.
+export { registerLanguage, listLanguages, getLanguageAliases } from './components/blocks/code/code-languages';
+// The code block's own tokenizer, for a plugin whose source surface wants the same highlighting
+// (block math paints its LaTeX with it). Text-preserving: the fragment's textContent is `body`.
+export { tokenizeBody as highlightCode } from './components/blocks/code/code-renderer';
 // ── Command mint (pre-freeze) ────────────────────────────────────────────────
 // A (kind, name) block-command mints a PluginCommandId; AnyCommandId spans built-in and minted.
 export { registerBlockCommand } from './schema/block-commands';
+// The block context menu: a kind's right-click actions, empty unless something registers them.
+export { registerBlockContextActions } from './schema/context-actions';
 // A global command is process-wide but runs against the dispatching instance's EditorContext.
 export { registerGlobalCommand } from './schema/global-commands';
 // ── Parse / serialize helpers (pre-freeze) ───────────────────────────────────
@@ -153,4 +165,8 @@ export { registerPasteTransform } from './tree-operations/paste/paste-transforms
 // names one), and the sentinel for "wherever this leaf ends".
 export { caretOffsetAtPoint } from './cursor/point-offset';
 export { CURSOR_END } from './block-component';
+// ── Pointer gestures (pre-freeze) ────────────────────────────────────────────
+// Put this attribute on an element whose drags are your widget's own (a pan, a brush) and the
+// editor's pointer arms leave a press inside it alone: no block range, no click ladder.
+export { POINTER_GESTURE_ATTR } from './selection/pointer-gesture';
 export { SELECTION_END } from './block-component';