@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/schema/built-in-descriptors.js

@@ -1,48 +1,31 @@
 /**
- * Built-in block-kind descriptors and inline-construct policies, applied by an EXPLICIT
- * `registerBuiltInDescriptors()` call from `core/inline/index.ts` and
- * `components/built-in-blocks.ts`: the `sideEffects` allowlist names dist paths, never the src
- * specifiers used inside this library, so only a called binding is safe from tree-shaking. Split
- * from `block-kind-descriptor.ts` so that module carries no registration payload.
+ * Built-in block-kind descriptors and inline-construct policies. Nothing registers on import:
+ * `core/inline/index.ts` and `components/built-in-blocks.ts` call `registerBuiltInDescriptors()`,
+ * since the `sideEffects` list names built paths and tree-shaking keeps only a called binding.
  */
 import { metadataOf } from '../core/nodes';
 import { displayLength } from '../core/lines';
+import { matchHeading } from '../core/parsers/heading';
 import { containerClosure } from './closure';
 import { registerBlockKind } from './block-kind-descriptor';
 import { rebuildBlockquoteRaw, rebuildListItemRaw, rebuildListRaw, rebuildTableRaw, rebuildTableRowRaw } from './container-rebuilders';
-import { normalizeCellRaw } from './table-cell-raw';
-import { normalizeFencedRaw } from './fenced-code-raw';
+import { tableCellWrite } from './table-cell-raw';
+import { fencedCodeWrite } from './fenced-code-raw';
+import { setextHeadingContentRange, setextHeadingWrite } from './setext-raw';
 import { registerInlineConstructPolicy } from './inline-construct-policy';
 import { wrapAsCodeSpan } from '../core/inline/backticks';
+import { containerEstimate, proseEstimate, singleLineEstimate, sourceLinesEstimate } from './height-estimates';
 // ── Content-range helpers ──────────────────────────────────────────────────
-// Headings carry a `# ` prefix that is not part of the editable text.
+// The heading's marker bytes, its `# ` and any closing `#` run, sit outside the editable text.
 function headingContentRange(node) {
-    const raw = node.raw;
-    const displayEnd = displayLength(raw);
-    let i = 0;
-    while (i < raw.length && raw[i] === ' ')
-        i++;
-    while (i < raw.length && raw[i] === '#')
-        i++;
-    if (i < raw.length && raw[i] === ' ')
-        i++;
-    return { start: i, end: displayEnd };
-}
-// Setext headings carry a trailing underline line that is structural, not content.
-function setextHeadingContentRange(node) {
-    const raw = node.raw;
-    const end = displayLength(raw);
-    const underlineStart = raw.lastIndexOf('\n', end - 1);
-    if (underlineStart === -1)
-        return { start: 0, end };
-    let contentEnd = underlineStart;
-    if (contentEnd > 0 && raw[contentEnd - 1] === '\r')
-        contentEnd--;
-    return { start: 0, end: contentEnd };
+    const heading = matchHeading(node.raw);
+    if (!heading)
+        return { start: 0, end: displayLength(node.raw) };
+    return { start: heading.contentStart, end: heading.contentEnd };
 }
 // ── Keymaps ───────────────────────────────────────────────────────────────
-// Shared by every kind TextEditableBlock renders — prose and the raw-editable fallback alike —
-// so transformative chords behave identically across them.
+// Shared by every kind TextEditableBlock renders, prose and the raw-editable fallback alike, so
+// the chords that transform a block behave the same in all of them.
 const TEXT_EDITABLE_KEYMAP = [
     { chord: 'Enter', command: 'block.split' },
     { chord: 'Shift+Enter', command: 'block.hardBreak' },
@@ -55,9 +38,8 @@ const TEXT_EDITABLE_KEYMAP = [
     { chord: 'Mod+I', command: 'format.toggleEmphasis' },
     { chord: 'Mod+Shift+X', command: 'format.toggleStrikethrough' },
     { chord: 'Mod+E', command: 'format.toggleCode' },
-    // The live-mode link card. Consumed even when no card opens (a caret outside every link
-    // no-ops): `reservedChords()` reports the chord as claimed, and a fall-through would run the
-    // browser's own Mod+K.
+    // The live-mode link card. The chord is taken even where no card opens, since letting it
+    // through would trigger the browser's own Mod+K.
     { chord: 'Mod+K', command: 'link.openCard' },
     { chord: 'Mod+0', command: 'heading.cycle', arg: 0 },
     { chord: 'Mod+1', command: 'heading.cycle', arg: 1 },
@@ -67,10 +49,8 @@ const TEXT_EDITABLE_KEYMAP = [
     { chord: 'Mod+5', command: 'heading.cycle', arg: 5 },
     { chord: 'Mod+6', command: 'heading.cycle', arg: 6 }
 ];
-// The cell is the focused surface inside a table, so the table's whole keyboard vocabulary binds
-// on THIS kind — an override scoped to `table` would resolve against a block that never holds
-// the caret. Plain arrows stay unbound: they depend on caret position, which a chord can't
-// express, so they live in `cell-keydown-plan.ts`.
+// The cell holds the caret inside a table, so the table's keys bind here; a `table` override would
+// miss. Plain arrows depend on the caret's position, so `cell-keydown-plan.ts` handles them.
 const TABLE_CELL_KEYMAP = [
     { chord: 'Enter', command: 'cell.enter' },
     { chord: 'Tab', command: 'cell.tab' },
@@ -91,14 +71,14 @@ const TABLE_CELL_KEYMAP = [
     { chord: 'Alt+ArrowLeft', command: 'table.moveColumnLeft' },
     { chord: 'Alt+ArrowRight', command: 'table.moveColumnRight' },
     { chord: 'Mod+Shift+A', command: 'table.cycleAlignment' },
-    // The whole table among its siblings. Alt+Arrow, every other kind's reorder chord, is taken
-    // by the row reorder a cell caret means first.
+    // Moves the whole table among its siblings, since Alt+Arrow, the reorder chord every other
+    // kind uses, moves the row the caret is in.
     { chord: 'Mod+Alt+ArrowUp', command: 'block.moveUp' },
     { chord: 'Mod+Alt+ArrowDown', command: 'block.moveDown' }
 ];
 // ── Closure blocks ────────────────────────────────────────────────────────────
-// Shared by the not-mergeable, non-inline raw-text leaves — byte-identical rows, hoisted rather
-// than triplicated. fencedCode diverges too widely to spread, so it stays inline.
+// Shared by the not-mergeable, non-inline raw-text leaves: the rows are identical, so they live
+// here once. `fencedCode` differs too much to share, so it declares its own.
 const RAW_TEXT_LEAF_CLOSURE = {
     roundTrip: { mode: 'inherit-default' },
     focus: { mode: 'implemented', via: 'native caret in the raw-editable contenteditable' },
@@ -113,8 +93,8 @@ const RAW_TEXT_LEAF_CLOSURE = {
     clipboard: { mode: 'inherit-default' },
     simOracle: { mode: 'implemented', via: 'note-taking simulation under the loaded-ops oracles' }
 };
-// The prose trio share a closure differing only in three via strings. Bake the
-// structurally-fixed rows; demand the varying vias so the honesty rule stays author-supplied.
+// The three prose kinds share a closure differing only in three `via` strings. The fixed rows are
+// filled in here; the three that vary stay required, so each kind names its own mechanism.
 function proseLeafClosure(vias) {
     return {
         roundTrip: { mode: 'inherit-default' },
@@ -129,8 +109,8 @@ function proseLeafClosure(vias) {
     };
 }
 // ── Inline-construct policies ───────────────────────────────────────────────
-// Registered beside the block descriptors rather than from the component layer so a headless
-// consumer — and the unit bootstrap, which loads only this module — reads the same rows.
+// Registered next to the block descriptors rather than from the component layer, so a consumer
+// with no UI, and the unit tests that load only this module, read the same rows.
 function registerBuiltInInlinePolicies() {
     // Outermost first, and code is innermost because its content is literal: no other mark can
     // take effect inside it.
@@ -151,6 +131,8 @@ function registerBuiltInInlinePolicies() {
             autoUnwrapOnEmpty: true,
             splitBehavior: 'close-and-reopen',
             revealable: true,
+            // A code span's content is literal, so a `#` typed there is code, not a tag.
+            prose: kind === 'inlineCode' ? 'none' : 'all',
             mark: { nestingRank, ...mark }
         });
     });
@@ -161,27 +143,30 @@ function registerBuiltInInlinePolicies() {
         autoUnwrapOnEmpty: true,
         splitBehavior: 'close-and-reopen',
         revealable: true,
-        cardEditable: true
+        cardEditable: true,
+        // The text is prose; the destination and the title are not.
+        prose: 'content'
     });
     // An image with an empty alt is still an image, and a split inside one moves bytes only.
     registerInlineConstructPolicy('image', {
         edgeAffinity: 'never-extend',
         autoUnwrapOnEmpty: false,
         splitBehavior: 'plain',
-        revealable: true
+        revealable: true,
+        // Its alt text is an attribute of the picture, not prose on the page.
+        prose: 'none'
     });
-    // An autolink's `<`/`>` are a link's delimiters by another spelling: the destination IS the
-    // text, so a byte landing between the brackets rewrites where the link goes. Never-extend, for
-    // the same reason the bracket form is (live-mode.md § 4.2), and plain: two halves of a URL
-    // are not two URLs.
+    // An autolink's text is its destination, so neither edge extends and a split stays plain
+    // (`docs/design/live-mode.md` § 4.2 Typing at a hidden edge).
     registerInlineConstructPolicy('autolink', {
         edgeAffinity: 'never-extend',
         autoUnwrapOnEmpty: false,
         splitBehavior: 'plain',
-        revealable: false
+        revealable: false,
+        prose: 'none'
     });
-    // Unstamped marker runs, permanently hidden in live mode: the `\X` pair and the trailing-space
-    // run delete as a unit, so nothing may rewrite their markers around an edit.
+    // Marker runs with no data attribute, always hidden in live mode: the `\X` pair and the
+    // trailing-space run delete as one unit, so nothing may rewrite their markers around an edit.
     for (const kind of ['escape', 'hardLineBreak']) {
         registerInlineConstructPolicy(kind, {
             edgeAffinity: 'never-extend',
@@ -192,8 +177,8 @@ function registerBuiltInInlinePolicies() {
     }
 }
 // ── Built-in registrations ──────────────────────────────────────────────────
-// Idempotence guard, not a registry bypass: both entry points call this, and a
-// dev-server re-eval resets it so the register-once dev valve still replaces.
+// Stops a second run rather than skipping the registries: both entry points call this, and on a
+// dev server a re-evaluation resets the flag so a repeat registration still replaces.
 let registered = false;
 export function registerBuiltInDescriptors() {
     if (registered)
@@ -201,6 +186,8 @@ export function registerBuiltInDescriptors() {
     registered = true;
     registerBuiltInInlinePolicies();
     registerBlockKind('paragraph', {
+        pageRole: 'prose',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'prose',
         editable: true,
@@ -215,14 +202,15 @@ export function registerBuiltInDescriptors() {
         })
     });
     registerBlockKind('heading', {
+        pageRole: 'prose',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'prose-absorber',
         editable: true,
         supportsInline: true,
-        getContentRange: headingContentRange,
-        // Live paints no `## `, so the first Backspace a user can aim at it takes the structure
-        // they CAN see; the second one merges, through the untouched cascade.
-        contentStartBackspace: 'demote-first',
+        // Live mode shows no `## `, so the first Backspace the user can aim at it removes the
+        // structure they can see; the second merges, through the usual path.
+        contentStart: { range: headingContentRange, backspace: 'demote-first' },
         keymap: TEXT_EDITABLE_KEYMAP,
         conformanceFixture: '# Heading\n',
         closure: proseLeafClosure({
@@ -232,12 +220,14 @@ export function registerBuiltInDescriptors() {
         })
     });
     registerBlockKind('setextHeading', {
+        pageRole: 'prose',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'prose-absorber',
         editable: true,
         supportsInline: true,
-        getContentRange: setextHeadingContentRange,
-        contentStartBackspace: 'demote-first',
+        contentStart: { range: setextHeadingContentRange, backspace: 'demote-first' },
+        rawWrite: setextHeadingWrite,
         keymap: TEXT_EDITABLE_KEYMAP,
         conformanceFixture: 'Title\n===\n',
         closure: proseLeafClosure({
@@ -247,12 +237,15 @@ export function registerBuiltInDescriptors() {
         })
     });
     registerBlockKind('fencedCode', {
+        pageRole: 'object',
+        dragLabel: 'Code',
+        estimateHeight: sourceLinesEstimate,
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
         // Enter inside the fence writes a code newline, so neither edge can grow a sibling.
         gapEdges: 'both',
-        normalizeRawWrite: normalizeFencedRaw,
+        rawWrite: fencedCodeWrite,
         keymap: [
             { chord: 'Enter', command: 'code.newline' },
             { chord: 'Tab', command: 'code.indent' },
@@ -287,16 +280,15 @@ export function registerBuiltInDescriptors() {
         }
     });
     registerBlockKind('thematicBreak', {
+        pageRole: 'object',
+        dragLabel: 'Divider',
+        estimateHeight: singleLineEstimate,
         mergeRole: 'not-mergeable',
         editable: false,
         supportsInline: false,
         blockFocus: 'whole-block',
         // Leading edge only: its focused Enter already inserts a paragraph below.
         gapEdges: 'before',
-        keymap: [
-            { chord: 'Alt+ArrowUp', command: 'block.moveUp' },
-            { chord: 'Alt+ArrowDown', command: 'block.moveDown' }
-        ],
         conformanceFixture: '---\n',
         closure: {
             roundTrip: { mode: 'inherit-default' },
@@ -311,7 +303,7 @@ export function registerBuiltInDescriptors() {
             selectionPaint: { mode: 'implemented', via: 'whole-block cover rect (no partial offsets)' },
             searchPaint: {
                 mode: 'not-supported',
-                reason: 'no editable text content — nothing to search'
+                reason: 'no editable text content, nothing to search'
             },
             reorder: { mode: 'implemented', via: 'Alt+Arrow block.move keymap' },
             undo: { mode: 'inherit-default' },
@@ -323,6 +315,8 @@ export function registerBuiltInDescriptors() {
         }
     });
     registerBlockKind('indentedCode', {
+        pageRole: 'object',
+        estimateHeight: sourceLinesEstimate,
         gapEdges: 'none',
         mergeRole: 'not-mergeable',
         editable: true,
@@ -332,24 +326,32 @@ export function registerBuiltInDescriptors() {
         closure: RAW_TEXT_LEAF_CLOSURE
     });
     registerBlockKind('htmlBlock', {
+        pageRole: 'object',
+        estimateHeight: sourceLinesEstimate,
         gapEdges: 'none',
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
         keymap: TEXT_EDITABLE_KEYMAP,
         conformanceFixture: '<div>\nhtml\n</div>\n',
+        readsFollowingLines: true,
         closure: RAW_TEXT_LEAF_CLOSURE
     });
     registerBlockKind('linkReferenceDefinition', {
+        pageRole: 'object',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
         keymap: TEXT_EDITABLE_KEYMAP,
         conformanceFixture: '[id]: /url "title"\n',
+        readsFollowingLines: true,
         closure: RAW_TEXT_LEAF_CLOSURE
     });
     registerBlockKind('table', {
+        pageRole: 'object',
+        estimateHeight: containerEstimate,
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
@@ -382,6 +384,8 @@ export function registerBuiltInDescriptors() {
         }
     });
     registerBlockKind('tableRow', {
+        pageRole: 'object',
+        estimateHeight: containerEstimate,
         gapEdges: 'none',
         mergeRole: 'not-mergeable',
         editable: true,
@@ -399,25 +403,27 @@ export function registerBuiltInDescriptors() {
             searchPaint: { mode: 'implemented', via: 'descends to cells; per-cell mark overlay' },
             reorder: {
                 mode: 'not-supported',
-                reason: 'grid child — not a block-level reorder unit; whole rows move via a row-drag gesture inside the table grid, not the BlockList'
+                reason: 'grid child: not a block-level reorder unit; whole rows move via a row-drag gesture inside the table grid, not the BlockList'
             },
             undo: { mode: 'inherit-default' },
-            // inherit-default, unlike table/tableCell: no clipboard path anchors on a row node,
-            // so the row's per-cell painting does not extend to being a copy source.
+            // Inherit-default, unlike `table` and `tableCell`: no copy path starts from a row node,
+            // so a row painting its cells does not make it a copy source.
             clipboard: { mode: 'inherit-default' },
             simOracle: { mode: 'implemented', via: 'note-taking simulation (table edits)' }
         }
     });
     registerBlockKind('tableCell', {
+        pageRole: 'prose',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: true,
         contextDependentKind: true,
-        normalizeRawWrite: normalizeCellRaw,
+        rawWrite: tableCellWrite,
         renderImagesAsWidgets: false,
         keymap: TABLE_CELL_KEYMAP,
-        // No conformanceFixture: the table opener mints cells, so one never stands alone as the
+        // No `conformanceFixture`: the table opener creates the cells, so one is never the
         // top-level result of a document scan.
         closure: {
             roundTrip: {
@@ -436,24 +442,26 @@ export function registerBuiltInDescriptors() {
             },
             reorder: {
                 mode: 'not-supported',
-                reason: 'grid cell — not a block-level reorder unit; row/column drag gestures inside the table grid move whole rows or columns, not individual cells'
+                reason: 'grid cell: not a block-level reorder unit; row/column drag gestures inside the table grid move whole rows or columns, not individual cells'
             },
             undo: { mode: 'inherit-default' },
             clipboard: {
                 mode: 'implemented',
-                via: 'copy/cut synthesize a GFM sub-table for the selected rectangle (intraTableRectPayload → copyRectangleAsSubTable, cell index)'
+                via: 'copy/cut, from a cell or the editor root, write the selected rectangle as a GFM sub-table and an HTML table (gridClipboard → copyRectangleAsSubTable, cell index)'
             },
             simOracle: { mode: 'implemented', via: 'note-taking simulation (table cell edits)' }
         }
     });
     registerBlockKind('unrecognized', {
+        pageRole: 'object',
+        estimateHeight: proseEstimate,
         gapEdges: 'none',
         mergeRole: 'self-merge',
         editable: true,
         supportsInline: false,
         keymap: TEXT_EDITABLE_KEYMAP,
-        // No conformanceFixture: it is the reserved fallback for content no opener claimed, so a
-        // document scan never yields it in isolation.
+        // No `conformanceFixture`: it is the fallback for content no opener took, so a document
+        // scan never produces it on its own.
         closure: {
             ...RAW_TEXT_LEAF_CLOSURE,
             mergeBackspace: {
@@ -465,6 +473,8 @@ export function registerBuiltInDescriptors() {
         }
     });
     registerBlockKind('blockquote', {
+        pageRole: 'prose',
+        estimateHeight: containerEstimate,
         gapEdges: 'none',
         mergeRole: 'container',
         editable: true,
@@ -497,6 +507,9 @@ export function registerBuiltInDescriptors() {
         })
     });
     registerBlockKind('list', {
+        // Its items carry the handles: one on the list would sit over its first item's.
+        pageRole: 'prose',
+        estimateHeight: containerEstimate,
         gapEdges: 'none',
         mergeRole: 'container',
         editable: true,
@@ -532,6 +545,8 @@ export function registerBuiltInDescriptors() {
         })
     });
     registerBlockKind('listItem', {
+        pageRole: 'object',
+        estimateHeight: containerEstimate,
         gapEdges: 'none',
         mergeRole: 'container',
         editable: true,
@@ -539,7 +554,8 @@ export function registerBuiltInDescriptors() {
         container: { contract: 'strip', rebuildRaw: rebuildListItemRaw },
         keymap: [
             { chord: 'Tab', command: 'list.indent' },
-            { chord: 'Shift+Tab', command: 'list.unindent' }
+            { chord: 'Shift+Tab', command: 'list.unindent' },
+            { chord: 'Mod+Enter', command: 'list.toggleTask' }
         ],
         conformanceFixture: '- item\n',
         closure: containerClosure({

package/dist/schema/child-spans.d.ts

@@ -1,10 +1,8 @@
 /**
  * Byte offsets of each child's rendered region inside its container's own `raw`, so a typing
- * rewrite splices one region instead of re-joining every child (O(1) reads through the `$state`
- * proxy rather than O(children)). Bookkeeping, never bytes: nothing serializes or renders it, and
- * a span the invalidation seams missed fails the region check below and falls back to the full
- * rebuild. A `Uint32Array` on purpose — Svelte proxies plain arrays, and the shift would mint a
- * source per element.
+ * rewrite replaces one region instead of re-joining every child. Bookkeeping only: a span left
+ * stale fails the region check below and falls back to the full rebuild. A `Uint32Array` because
+ * Svelte proxies plain arrays, one reactive source per element.
  */
 import { type CstNode } from '../core/nodes';
 /** The child a rebuild is re-rendering, and the bytes its region currently holds. */
@@ -12,14 +10,18 @@ export interface ChildRawChange {
     index: number;
     previousRaw: string;
 }
-/** A strip container's per-line transform; `first` marks the container's own opening line. */
-export type LinePrefix = (text: string, first: boolean) => string;
-/** Drop the spans a children-shape change invalidated; the next full rebuild reseeds them. */
+/**
+ * A strip container's per-line transform. `first` marks the container's own opening line, and
+ * `trailingBlank` a blank line, other than a separator, with nothing but blank lines after it in
+ * the body.
+ */
+export type LinePrefix = (text: string, first: boolean, trailingBlank: boolean) => string;
+/** Drop the spans a change to the children invalidated; the next full rebuild recomputes them. */
 export declare function dropChildSpans(node: CstNode): void;
 /** A container whose raw is its children's bytes joined (list). */
 export declare function rebuildConcatRaw(node: CstNode, changed?: ChildRawChange): void;
 /**
- * A container whose raw re-prefixes every line of its body (blockquote, list item). `innerPrefix`
- * is unread: these kinds open their body on their own first line, so no parse fills it (G1.5).
+ * A container whose raw re-prefixes every line of its body (blockquote, list item). Its body opens
+ * on its own first line, so no parse fills `innerPrefix` and it is not read here (G1.5).
  */
 export declare function rebuildStripRaw(node: CstNode, prefix: LinePrefix, changed?: ChildRawChange): void;