@motionscript/code 0.1.0-alpha.9 → 0.1.1-alpha.0

package/src/diff.ts

@@ -1,65 +1,32 @@
 import type { IdLine, IdToken } from "./tokens";
 
-/**
- * The result of diffing one listing structure against another: the *next*
- * structure, with token and line ids carried over from the previous one
- * wherever the content survived, plus the three sets a transition needs to know
- * which role each token plays.
- *
- * Identity is the whole product here. `const variable = 3` becoming
- * `const number = 3` should move `const` and `= 3` rather than dissolve and
- * rebuild them, and a token can only *move* if the frame after the edit still
- * knows it is the same token.
- */
-/**
- * How a `Code` node decides which token became which across an edit. Given
- * the old and new tokenized structures, return the carried-over structure
- * plus the added/removed/renamed-line bookkeeping a transition needs.
- * `diffCode` below is the default implementation (exported as
- * `defaultCodeDiff`) — pass a `diffStrategy` of this shape to `<Code>` to
- * replace it with your own.
- */
+/** Decides which token became which across an edit; `diffCode` (exported as `defaultCodeDiff`) is the default. */
 export type CodeDiffStrategy = (from: IdLine[], to: IdLine[]) => CodeEdit;
 
+/** The next structure with ids carried over wherever content survived, so a surviving token moves rather than dissolves and rebuilds. */
 export interface CodeEdit {
-    /** The new structure. Ids are rewritten in place onto the tokens handed in. */
+    /** The new structure; ids are rewritten in place onto the tokens handed in. */
     lines: IdLine[];
-    /** Ids present only in the old structure — these fade out. */
     removedIds: Set<number>;
-    /** Ids present only in the new structure — these fade in. */
     addedIds: Set<number>;
-    /** Ids of {@link lines} that did not exist before — these enter as a whole row. */
+    /** Lines that did not exist before; they enter as a whole row. */
     newLineIds: Set<number>;
     /** Previous colour of a surviving token whose highlighting changed, for the cross-fade. */
     fromColorById: Map<number, string | undefined>;
 }
 
-/**
- * How similar two lines must be before they are treated as *one line that was
- * edited* rather than as one line deleted and another inserted.
- *
- * Below this, a row's tokens have so little in common that carrying ids across
- * would animate glyphs sliding between unrelated words. Above it, the edit reads
- * the way it was made.
- */
+/** Below this similarity two lines are one deleted and one inserted, not one edited: carrying ids across would slide glyphs between unrelated words. */
 const LINE_MATCH_FLOOR = 0.45;
 
 /**
- * The most line pairs one run of changed lines is scored against each other, and
- * the most across a whole edit.
- *
- * Scoring every pair is quadratic: with 50-character lines it took 31 ms at 200
- * lines and 741 ms at 1,000, paid again for each edit command when it is built.
- * So the lines are first paired where they cannot be in doubt (see
- * {@link alignLines}), and only a run left between two such anchors is scored.
- * A run past the first limit, or what is left of the second, is not compared: its
- * lines leave and enter as whole rows. That is the budget, and an edit that stays
- * inside it is diffed exactly as before.
+ * Most line pairs scored in one run of changed lines, and across a whole edit.
+ * Scoring every pair is quadratic (741 ms at 1,000 lines), so only a run between
+ * two anchors (see {@link alignLines}) is scored; past the budget its lines leave
+ * and enter as whole rows.
  */
-export const LINE_ALIGN_CELLS = 40_000;
-export const EDIT_ALIGN_CELLS = 160_000;
+const LINE_ALIGN_CELLS = 40_000;
+const EDIT_ALIGN_CELLS = 160_000;
 
-/** Weight a token carries when judging similarity: its visible characters. */
 function tokenWeight(tok: IdToken): number {
     return tok.content.trim().length;
 }
@@ -71,12 +38,9 @@ function lineWeight(line: IdLine): number {
 }
 
 /**
- * Dice coefficient over the two lines' token multisets, weighted by visible
- * characters so `variable` counts for far more than a run of spaces.
- *
- * Two blank lines are identical (1); a blank line against a non-blank one shares
- * nothing (0), which keeps the blank rows a reformat introduces from anchoring
- * themselves onto real code.
+ * Dice coefficient over the lines' token multisets, weighted by visible characters.
+ * Two blank lines are identical (1) but a blank against a non-blank shares nothing
+ * (0), so blank rows a reformat introduces never anchor onto real code.
  */
 function similarity(a: IdLine, b: IdLine): number {
     const wa = lineWeight(a);
@@ -103,22 +67,15 @@ function similarity(a: IdLine, b: IdLine): number {
 }
 
 /**
- * Align two sequences by maximising total `score`, skipping is free.
- *
- * A plain LCS would only ever pair *identical* elements, which is the wrong tool
- * twice over: two lines that differ by one word are the same line, and two
- * tokens that differ only in colour are the same token. Scoring the pairing and
- * letting anything that scores ≤ 0 fall out expresses that directly, and because
- * skips cost nothing the alignment stays in order.
- *
- * Returns the matched index pairs, in order.
+ * Matched index pairs, in order, maximising total `score`; a pair scoring <= 0 is
+ * skipped. An LCS would pair only identical elements, but two lines that differ by
+ * one word are the same line.
  */
 function align(
     aLength: number,
     bLength: number,
     score: (i: number, j: number) => number,
 ): Array<[number, number]> {
-    // dp[i][j] = best score aligning a[0..i) with b[0..j).
     const width = bLength + 1;
     const dp = new Float64Array((aLength + 1) * width);
     const pairScore = new Float64Array(aLength * bLength);
@@ -156,19 +113,11 @@ function align(
     return pairs;
 }
 
-/**
- * Match the tokens of one line against another's.
- *
- * Scored by visible characters rather than token count, so an alignment that
- * keeps `items.reduce` together beats one that keeps four more spaces. A token
- * pairs only when its content is unchanged — a changed word is a different word,
- * and should be seen to be replaced.
- */
+/** Scored by visible characters, so keeping `items.reduce` beats keeping four spaces; a changed word is a different token. */
 function alignTokens(from: IdToken[], to: IdToken[]): Array<[number, number]> {
     return align(from.length, to.length, (i, j) => {
         if (from[i].content !== to[j].content) return 0;
-        // Whitespace still pairs (it holds indentation together), just weakly
-        // enough that it never outranks real content.
+        // Whitespace pairs weakly: it holds indentation together but never outranks content.
         return tokenWeight(to[j]) || 0.25;
     });
 }
@@ -179,7 +128,7 @@ function sameTokens(a: IdLine, b: IdLine): boolean {
     return true;
 }
 
-/** A line's text, token boundaries included, for telling identical lines apart from similar ones. */
+/** Text with token boundaries, so identical lines tell apart from similar ones. */
 function signature(line: IdLine): string {
     let out = "";
     for (const tok of line.tokens) out += tok.content + "\u0001";
@@ -187,14 +136,10 @@ function signature(line: IdLine): string {
 }
 
 /**
- * Pair the lines of two listings, in order.
- *
- * Lines that are the same at the start and at the end are paired outright. In
- * what is left, a line that occurs exactly once on each side is an anchor, and
- * the longest run of anchors that keeps their order splits the rest into runs of
- * changed lines, each scored against itself within the budget (see
- * {@link LINE_ALIGN_CELLS}). A one-line edit to a long listing therefore never
- * builds a table bigger than the lines around it.
+ * Pairs lines in order: identical head and tail outright, then the longest ordered
+ * run of lines occurring once on each side as anchors, with each run between
+ * anchors scored within the budget. A one-line edit to a long listing therefore
+ * never builds a table bigger than the lines around it.
  */
 function alignLines(from: IdLine[], to: IdLine[]): Array<[number, number]> {
     const fromSig = from.map(signature);
@@ -234,11 +179,7 @@ function alignLines(from: IdLine[], to: IdLine[]): Array<[number, number]> {
     return pairs;
 }
 
-/**
- * The lines that occur once in `from[fa, fb)` and once in `to[ta, tb)`, reduced to
- * the longest subsequence that is increasing on both sides (patience sorting).
- * Blank lines are never anchors: they say nothing about where they belong.
- */
+/** Lines occurring once on each side, reduced to the longest subsequence increasing on both (patience sorting); blanks never anchor. */
 function anchorLines(
     fromSig: string[],
     toSig: string[],
@@ -264,7 +205,6 @@ function anchorLines(
         seenTo.add(sig);
     }
 
-    // In `to` order, each candidate carries its `from` position.
     const candidates: Array<[number, number]> = [];
     for (let j = ta; j < tb; j++) {
         const i = fromAt.get(toSig[j]);
@@ -291,13 +231,7 @@ function anchorLines(
     return chain.reverse();
 }
 
-/**
- * Carry `from`'s identities onto `to`, and report what changed.
- *
- * `to` is freshly tokenized and owns ids nobody has seen yet, so rewriting them
- * in place is safe and is what makes the transition cheap: after this, the two
- * structures share an id for every token that survived the edit.
- */
+/** Carries `from`'s ids onto `to`; `to` is freshly tokenized, so rewriting its ids in place is safe. */
 export function diffCode(from: IdLine[], to: IdLine[]): CodeEdit {
     const removedIds = new Set<number>();
     const addedIds = new Set<number>();

package/src/engine.ts

@@ -1,10 +1,6 @@
-// The Code "engine": syntax highlighting, tokenizing, layout, diffing, and
-// transition/phase scheduling — kept separate from node.ts so a copy of the node
-// can take just its declaration and import this behind
-// `@motionscript/code` instead. What gets copied is whatever this
-// package's registry.json declares, which for this component is node.ts;
-// src/tests/registry.test.ts checks that anything it
-// reaches for is either copied alongside it or re-exported from here.
+// Everything node.ts imports besides its own declaration, so a copy of the node can take
+// just node.ts and import this from `@motionscript/code`. registry.test.ts checks that
+// whatever node.ts reaches for is copied alongside it or re-exported from here.
 export * from './transitions';
 export * from './layout';
 export { drawCode } from './render';

package/src/highlight.ts

@@ -8,22 +8,7 @@ import {
     compileStyle,
 } from "./style";
 
-/**
- * Lezer-backed syntax highlighting for the Code component, replacing the former
- * Shiki wiring. This mirrors Motion Canvas's `LezerHighlighter`:
- *
- *  - {@link prepareHighlight} parses code once and builds a `from:to` → color map
- *    by walking {@link highlightTree}.
- *  - {@link tokenizeCode} splits code at parse-tree leaf boundaries.
- *  - {@link highlightAt} resolves the color (and run length) for a character index.
- *
- * Parsers load lazily and asynchronously (dynamic import) so the bundle doesn't
- * pull in every grammar. The node's asset loader awaits {@link ensureHighlighter}
- * before tokenizing; until a parser resolves, callers fall back to plain text and
- * re-tokenize once {@link canHighlight} returns true.
- */
-
-/** Dynamic-import factories for each supported language → a Lezer {@link Parser}. */
+// Dynamic imports keep the bundle from pulling in every grammar.
 const LANGUAGE_LOADERS: Record<string, () => Promise<Parser>> = {
     typescript: async () => (await import("@lezer/javascript")).parser.configure({ dialect: "ts" }),
     tsx: async () => (await import("@lezer/javascript")).parser.configure({ dialect: "ts jsx" }),
@@ -43,7 +28,6 @@ const LANGUAGE_LOADERS: Record<string, () => Promise<Parser>> = {
     yaml: async () => (await import("@lezer/yaml")).parser,
 };
 
-// Aliases so common language strings resolve to a loader above.
 const LANGUAGE_ALIASES: Record<string, string> = {
     ts: "typescript",
     js: "javascript",
@@ -81,17 +65,12 @@ function resolveLanguageKey(language: string): string {
     return LANGUAGE_ALIASES[key] ?? key;
 }
 
-// Loaded parsers and in-flight loads, keyed by resolved language key, so
-// concurrent Code nodes asking for the same language share one dynamic import.
+// Keyed by resolved language, so concurrent nodes share one import.
 const loadedParsers = new Map<string, Parser>();
 const inFlightLangs = new Map<string, Promise<Parser | null>>();
 
-export const DEFAULT_THEMES = [DefaultHighlightStyle.name];
 export const DEFAULT_LANGS = ["typescript", "javascript", "json", "python"];
 
-// Theme registry, seeded with the built-ins (Motion Canvas default + GitHub
-// dark/light). The `theme` prop is a string name or a CodeHighlightStyle object;
-// apps can register additional styles by name and reference them by that name.
 const themesByName = new Map<string, CodeHighlightStyle>(Object.entries(BUILTIN_THEMES));
 
 /** Register a custom {@link CodeHighlightStyle} so Code nodes can reference it by name. */
@@ -99,11 +78,7 @@ export function registerCodeTheme(style: CodeHighlightStyle): void {
     themesByName.set(style.name, style);
 }
 
-/**
- * Resolve a theme reference (a registered name, or a CodeHighlightStyle object)
- * to a concrete style. Unknown names fall back to the Motion Canvas default so a
- * stray theme string never throws, with one warning per name.
- */
+/** An unknown theme name falls back to the default style with one warning, never a throw. */
 export function resolveTheme(theme: CodeTheme): CodeHighlightStyle {
     if (typeof theme !== "string") return theme;
     const style = themesByName.get(theme);
@@ -116,24 +91,13 @@ export function resolveTheme(theme: CodeTheme): CodeHighlightStyle {
     return DefaultHighlightStyle;
 }
 
-/** Has `language` finished loading its parser? */
-function isLanguageLoaded(language: string): boolean {
-    return loadedParsers.has(resolveLanguageKey(language));
-}
-
 /**
- * Load the parsers for `langs` (themes are synchronous, so they're a no-op here
- * but kept in the signature for API parity with the former Shiki implementation).
- * Resolves once every requested language's parser is available. Unknown languages
- * resolve without loading anything — {@link canHighlight} stays false for them and
- * the node renders them as plain text, with one warning per language. A grammar
- * whose import is rejected is reported the same way and is tried again by the
- * next call.
+ * Resolves once every requested language's parser is loaded. An unknown language
+ * resolves without loading (`canHighlight` stays false and it draws as plain
+ * text); a grammar whose import rejects is reported the same way and retried by
+ * the next call. Each warns once.
  */
-export function ensureHighlighter(
-    _themes: string[] = DEFAULT_THEMES,
-    langs: string[] = DEFAULT_LANGS,
-): Promise<void> {
+export function ensureHighlighter(langs: string[] = DEFAULT_LANGS): Promise<void> {
     const jobs: Promise<unknown>[] = [];
 
     for (const lang of langs) {
@@ -142,7 +106,6 @@ export function ensureHighlighter(
 
         const loader = LANGUAGE_LOADERS[key];
         if (!loader) {
-            // Unsupported language; leave it unhighlighted, and say so.
             if (!PLAIN_LANGUAGES.has(key)) {
                 warnOnce(
                     "language",
@@ -177,33 +140,22 @@ export function ensureHighlighter(
     return jobs.length === 0 ? Promise.resolve() : Promise.all(jobs).then(() => undefined);
 }
 
-/**
- * Load a syntax-highlight language into the shared highlighter. Exposed so a Code
- * node's asset loader can run it on the timeline, and so apps can preload
- * languages explicitly. Returns once the parser is ready (or immediately for an
- * unsupported language). The `theme` arg is accepted for backwards compatibility.
- */
-export async function loadCodeLanguage(language: string, _theme?: string): Promise<void> {
-    await ensureHighlighter(DEFAULT_THEMES, [language]);
+/** Loads one language; resolves at once for an unsupported one. */
+export async function loadCodeLanguage(language: string): Promise<void> {
+    await ensureHighlighter([language]);
 }
 
-export async function initSyntaxHighlighter(
-    themes: string[] = DEFAULT_THEMES,
-    langs: string[] = DEFAULT_LANGS,
-): Promise<void> {
-    await ensureHighlighter(themes, langs);
+export async function initSyntaxHighlighter(langs: string[] = DEFAULT_LANGS): Promise<void> {
+    await ensureHighlighter(langs);
 }
 
-/** True once `language` can be tokenized (its parser has loaded). */
-export function canHighlight(language: string, _theme?: CodeTheme): boolean {
-    return isLanguageLoaded(language);
+/** True once `language`'s parser has loaded. */
+export function canHighlight(language: string): boolean {
+    return loadedParsers.has(resolveLanguageKey(language));
 }
 
-/** A parsed-and-prepared highlight cache for one snapshot of code. */
 interface HighlightCache {
     tree: Tree;
-    code: string;
-    // `${from}:${to}` node id → color, exactly as Motion Canvas keys it.
     colorLookup: Map<string, string>;
 }
 
@@ -211,12 +163,7 @@ function nodeId(from: number, to: number): string {
     return `${from}:${to}`;
 }
 
-/**
- * Parse `code` and build the per-node color map. Mirrors Motion Canvas's
- * `LezerHighlighter.prepare`: for each highlighted range, walk the subtree and
- * record the color against every contained node's `from:to` id, so a later
- * {@link highlightAt} lookup by `resolveInner` index finds it.
- */
+/** Maps every node inside a highlighted range to its color by `from:to` id, for {@link highlightAt}. */
 function prepareHighlight(code: string, language: string, style: CodeHighlightStyle): HighlightCache | null {
     const parser = loadedParsers.get(resolveLanguageKey(language));
     if (!parser) return null;
@@ -226,8 +173,7 @@ function prepareHighlight(code: string, language: string, style: CodeHighlightSt
     const colorLookup = new Map<string, string>();
 
     highlightTree(tree, highlighter, (from, to, classes) => {
-        // tagHighlighter emits our color string as the "class".
-        const color = classes;
+        const color = classes; // the tag highlighter emits the color as the "class"
         if (!color) return;
         const cursor = tree.cursorAt(from, 1);
         do {
@@ -235,32 +181,22 @@ function prepareHighlight(code: string, language: string, style: CodeHighlightSt
         } while (cursor.next() && cursor.to <= to);
     });
 
-    return { tree, code, colorLookup };
+    return { tree, colorLookup };
 }
 
-/**
- * Resolve the color and run length for the token starting at `index`. Mirrors
- * Motion Canvas's `LezerHighlighter.highlight`: resolve the innermost node, look
- * up its color, and report how far the run extends (`skipAhead`).
- */
+/** The color and run length (`skipAhead`) of the innermost node at `index`. */
 function highlightAt(index: number, cache: HighlightCache): { color: string | null; skipAhead: number } {
     const node = cache.tree.resolveInner(index, 1);
     const color = cache.colorLookup.get(nodeId(node.from, node.to));
     if (color) {
         return { color, skipAhead: node.to - index };
     }
-    // No color: skip past a childless (leaf) node so we don't re-resolve every char.
+    // Uncolored: skip a whole leaf rather than re-resolving every character.
     const skipAhead = node.firstChild ? 0 : node.to - index;
     return { color: null, skipAhead };
 }
 
-/**
- * Split `code` into structural tokens at parse-tree leaf boundaries, including the
- * gaps between leaves (whitespace/punctuation). Mirrors Motion Canvas's
- * `LezerHighlighter.tokenize`; this segmentation is what the token-level
- * append/insert/erase/replace animations diff against, so matching it keeps the
- * animation behavior identical to Motion Canvas.
- */
+/** Splits at parse-tree leaf boundaries, gaps between leaves included; the edit animations diff against this segmentation. */
 function tokenizeCode(code: string, language: string): string[] {
     const parser = loadedParsers.get(resolveLanguageKey(language));
     if (!parser) return [code];
@@ -283,13 +219,8 @@ function tokenizeCode(code: string, language: string): string[] {
 }
 
 /**
- * Tokenize `code` into per-line, colored tokens — the contract the rest of the
- * Code component consumes. Combines {@link tokenizeCode} (structural split) with
- * {@link highlightAt} (per-run color), then breaks tokens at newlines so each
- * output line is a row of single-line, single-color tokens.
- *
- * Callers must have checked {@link canHighlight} first; this returns a single
- * uncolored line per source line if the parser isn't loaded.
+ * Per-line rows of single-line, single-color tokens. Without a loaded parser it
+ * returns one uncolored token per source line, so callers check {@link canHighlight}.
  */
 export function highlightToTokens(
     code: string,
@@ -304,19 +235,15 @@ export function highlightToTokens(
     const pushLine = () => lines.push([]);
 
     if (!cache) {
-        // Parser unavailable: one uncolored token per source line.
         return code.split("\n").map(line => [{ content: line, color: style.defaultColor }]);
     }
 
-    // Walk the structural tokens, coloring each by its starting index and
-    // splitting on newlines so no token spans rows.
     let index = 0;
     for (const token of tokenizeCode(code, language)) {
         let offset = 0;
         while (offset < token.length) {
             const { color, skipAhead } = highlightAt(index + offset, cache);
-            // Extend the run as far as the highlight says, but never past this
-            // structural token and never across a newline (lines are drawn rows).
+            // A run never passes its structural token or a newline.
             let runEnd = offset + Math.max(skipAhead, 1);
             if (runEnd > token.length) runEnd = token.length;
             const newlineRel = token.indexOf("\n", offset);

package/src/layout.ts

@@ -19,7 +19,7 @@ export interface CodeMetrics {
     lineNumberGap: number;
 }
 
-/** Where one token sits: its LEFT edge, and the vertical CENTRE of its line's slot. */
+/** A token's LEFT edge and the vertical CENTRE of its line's slot. */
 export interface TokenBox {
     x: number;
     y: number;
@@ -37,38 +37,25 @@ export interface TokenBox {
  * the left margin springing apart.
  */
 export interface CodeLayout {
-    /** Token id → placement. */
     tokens: Map<number, TokenBox>;
-    /** Vertical centre of each line's slot, by line index. */
+    /** By line index. */
     lineY: number[];
-    /**
-     * Width of each line's ink, by line index — the sum of its tokens' advances,
-     * so a blank line is `0` and a short line is short.
-     *
-     * Returned rather than kept local because it is the only thing that knows a
-     * listing is **ragged**: `innerW` is the longest line, and everything that
-     * asks where the text actually is (hit testing, for one) would otherwise have
-     * to treat the block as a rectangle the width of its longest row.
-     */
+    /** Ink width per line (blank is 0): the only record that a listing is ragged, which hit testing needs. */
     lineW: number[];
-    /** Line id → its index in this structure (i.e. its line *number* minus one). */
     lineIndex: Map<number, number>;
     gutter: number;
     gutterGap: number;
     /** Content size, no padding. */
     innerW: number;
     innerH: number;
-    /** Content size plus padding — what the block draws and measures as. */
+    /** Content plus padding. */
     blockW: number;
     blockH: number;
-    /** Left edge of the code column (after padding and gutter). */
+    /** Left edge of the code column, after padding and gutter. */
     startX: number;
 }
 
-/**
- * Signature of everything a layout depends on other than the token structure
- * itself. A cached layout survives exactly as long as this is unchanged.
- */
+/** Everything a layout depends on besides the token structure; a cached layout lives while it is unchanged. */
 export function metricsSignature(m: CodeMetrics): string {
     const p = m.padding;
     return [
@@ -78,16 +65,12 @@ export function metricsSignature(m: CodeMetrics): string {
     ].join("|");
 }
 
-/**
- * Horizontal gap between the line-number column and the code text. Sized in
- * space-widths so it scales with the font, and measured with letterSpacing 0 —
- * line numbers and the gap don't carry the code's letter-spacing.
- */
+/** In space-widths, measured with letterSpacing 0: line numbers and the gap don't carry the code's. */
 function gutterGapOf(scope: MeasureContext2D | RenderContext2D, m: CodeMetrics, cache: TokenAdvanceCache): number {
     return cache.advance(scope, " ", m.fontSize, m.fontFamily, 0) * m.lineNumberGap;
 }
 
-/** Width of the line-number column for a structure of `lineCount` lines, gap included. */
+/** Gap included. */
 function gutterOf(
     scope: MeasureContext2D | RenderContext2D,
     m: CodeMetrics,
@@ -100,13 +83,7 @@ function gutterOf(
     return cache.advance(scope, sample, m.fontSize, m.fontFamily, 0) + gap;
 }
 
-/**
- * Place every token of `lines`.
- *
- * Pure in (lines, metrics, font measurements), which is what lets a caller cache
- * one per structure rather than recomputing it per frame — a transition's two
- * endpoints are both fixed for its whole duration.
- */
+/** Pure in (lines, metrics, measurements), so a caller caches one per structure. */
 export function layoutCode(
     lines: IdLine[],
     m: CodeMetrics,
@@ -133,9 +110,7 @@ export function layoutCode(
     const blockW = innerW + m.padding.left + m.padding.right;
     const blockH = innerH + m.padding.top + m.padding.bottom;
     const startX = -blockW / 2 + m.padding.left + gutter;
-    // y-up author space: the first line sits at the TOP of the block, so the
-    // cursor starts at the top edge (+half height, minus top padding) and steps
-    // DOWNWARD by subtracting a line height per row.
+    // y-up: the first line sits at the TOP, and each row steps down by a line height.
     const startY = blockH / 2 - m.padding.top;
 
     const tokens = new Map<number, TokenBox>();