@motionscript/code 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/node.ts

@@ -1,71 +1,61 @@
 import {
-    node,
-    RenderContext2D, RenderPass2D, Clip, EasingFunction, NodeConfig, Size2D, SizeConstraints,
-    Node2D, Node2DProps, MeasureContext2D, InsetsResolved, InsetsProps,
-    property, insetsOps, lerpNumber,
-    command, driveCommand, type AssetScope, type Command, type CommandArgs, type Node, type TweenStepper, type Vector2,
-} from "@motionscript/core";
+    Graphics2D,
+    Paint,
+    Types,
+    component2d,
+    lerpNumber,
+    type InsetsResolved,
+    type MeasureContext2D,
+    type Measurer,
+    type NodeOf,
+    type NormalizedColor,
+    type Piece,
+    type RenderContext,
+    type Size2D,
+    // Named so the emitted declaration reaches these through the sdk, not core.
+    type Color as _Color,
+    type Node2D as _Node2D,
+    type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk";
 import {
-    CodeRange,
-    rangeToCharOffsets,
-    charOffsetsToRange,
+    DefaultHighlightStyle,
     TokenAdvanceCache,
-    IdLine,
-    tokenizeCodeToIdLines,
+    canHighlight,
+    charOffsetsToRange,
     defaultCodeDiff,
-    type CodeDiffStrategy,
-    CodeLayout,
-    CodeMetrics,
+    defaultCodePhases,
+    drawCode,
+    ensureHighlighter,
     layoutCode,
-    metricsSignature,
-    AnimToken,
-    CodeTransition,
-    StructuralTransition,
     makeAnim,
-    defaultCodePhases,
-    type CodePhaseStrategy,
-    resolveTokenStates,
+    metricsSignature,
     moveProgress,
-    canHighlight,
-    ensureHighlighter,
-    CodeTheme,
-    DefaultHighlightStyle,
-    drawCode,
+    normalizeSource,
+    rangeToCharOffsets,
+    resolveTokenStates,
+    tokenizeCodeToIdLines,
+    type AnimToken,
+    type CodeDiffStrategy,
+    type CodeLayout,
+    type CodeMetrics,
+    type CodePhaseStrategy,
+    type CodeRange,
+    type CodeTheme,
+    type DimTransition,
+    type IdLine,
+    type RowBand,
+    type RowsTransition,
+    type StructuralTransition,
 } from "./engine";
 
-/**
- * A listing and nothing else — no paint slots, and no box behind the tokens.
- *
- * It did carry a `fill`/`overlay`/`stroke`/`shadow` set and the corner radius
- * that shaped them, so a block could draw its own panel. That was one node doing
- * two jobs, and the second one is a `Rect`'s: a listing set on a card is a `Code`
- * inside a hugging `Rect`, which tracks the block's size for the same reason
- * every other hugging container tracks its child's. What is left here is the
- * listing — its source, how it is coloured, the face it is set in, and the space
- * it keeps around itself.
- */
-export interface CodeProps extends Node2DProps {
-    code: string;
-    language: string;
-    fontSize: number;
-    fontFamily: string;
-    /** A built-in/registered theme name (e.g. `'github-dark'`), or a {@link CodeHighlightStyle} object. */
-    theme: CodeTheme;
-    lineHeight: number;
-    letterSpacing: number;
-    showLineNumbers: boolean;
-    lineNumberGap: number;
-    padding: InsetsProps;
-}
+/** A row band's paint and corner radius when `highlightRows` is given neither. */
+const ROW_BAND_COLOR = "rgba(255, 255, 255, 0.12)";
+const ROW_BAND_RADIUS = 6;
 
 /**
- * Construction-time-only options: pluggable engine behavior, set once when
- * the node is created. Deliberately *not* part of {@link CodeProps} — every
- * `@property` field accepts either a value or a zero-arg reactive binding
- * (`value | (() => value)`, see `PropInputs`), and the node's own reactive
- * write path (`_writeProp`) treats any function value as the latter. A
- * strategy *is* a function, so it can't be told apart from a binding that
- * computes one — it has to stay outside the reactive prop system entirely.
+ * Which token became which across an edit, and when each part of it happens.
+ * Arguments of {@link defineCode}: a strategy is a function, which a prop would
+ * take for a binding, so it is part of the component's definition instead.
  */
 export interface CodeStrategies {
     /** Decides which token became which across an edit. Defaults to `defaultCodeDiff`. */
@@ -74,748 +64,623 @@ export interface CodeStrategies {
     phaseStrategy?: CodePhaseStrategy;
 }
 
-@node({
-  key: "code",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    defaultWidthMode: "hug",
-    defaultHeightMode: "hug",
-    acceptsChildren: false,
-  },
-})
-export class Code extends Node2D<CodeProps> {
-
-    @property({ default: "" }) declare readonly code: string;
-    @property({ default: "typescript" }) declare readonly language: string;
-    @property({ default: "Fira Mono" }) declare readonly fontFamily: string;
-    @property({ default: DefaultHighlightStyle.name }) declare readonly theme: CodeTheme;
-    @property({ default: 16 }) declare readonly fontSize: number;
-    @property({ default: 1.6 }) declare readonly lineHeight: number;
-    // Extra horizontal space added after every glyph (in px), like CSS
-    // letter-spacing. Folded into the advance a token is measured at, so
-    // measurement and drawing stay in lockstep.
-    @property({ default: 1.1 }) declare readonly letterSpacing: number;
-    @property({ default: false }) declare readonly showLineNumbers: boolean;
-    // Horizontal gap between the line-number column and the code text, expressed
-    // in space-widths (so it scales with fontSize). Only applies when
-    // showLineNumbers is on.
-    @property({ default: 2 }) declare readonly lineNumberGap: number;
-    @property({ default: 0, mapper: insetsOps.resolve, tween: insetsOps.lerp }) declare readonly padding: InsetsResolved;
-
-    /** The settled structure. During an edit, the structure the edit lands on. */
-    private tokenLines: IdLine[] = [];
-    private tokenized: boolean = false;
-
-    private transitions: CodeTransition[] = [];
-
-    // Caches expensive scope.measureText() calls; cleared when the font
-    // signature (fontSize|fontFamily) changes. See TokenAdvanceCache.
-    private advanceCache = new TokenAdvanceCache();
-
-    // Layout cache for *settled* frames. Bumped whenever tokenLines is
-    // reassigned, so a cache hit only ever happens on identical content. Frames
-    // inside a structural edit are served from that edit's own two cached
-    // layouts instead (see StructuralTransition).
-    private structureVersion = 0;
-    private layoutCacheKey: string | null = null;
-    private layoutCache: CodeLayout | null = null;
-
-    // Persistent dim state set by highlight() — applied during render to all
-    // tokens whose id is NOT in the highlight set. null means "not highlighting".
-    private highlightDimOpacity: number | null = null;
-    private highlightedIds: Set<number> = new Set();
-
-    /**
-     * Which token became which across an edit, and when each part of that
-     * edit happens. Construction-time-only (see {@link CodeStrategies}) —
-     * resolved once here rather than left as `?? defaultX` at every call site.
-     */
-    private readonly diffStrategy: CodeDiffStrategy;
-    private readonly phaseStrategy: CodePhaseStrategy;
-
-    constructor(props: NodeConfig<Code, CodeProps> & CodeStrategies) {
-        super(props);
-        this.diffStrategy = props.diffStrategy ?? defaultCodeDiff;
-        this.phaseStrategy = props.phaseStrategy ?? defaultCodePhases;
-        this.applyProp("width", props.width ?? "hug");
-        this.applyProp("height", props.height ?? "hug");
-
-        // Best-effort, for a highlighter constructed outside the asset pipeline
-        // entirely (a bare `new Code(...)` in a test or a headless measure). On
-        // the timeline the authoritative load is the one `declareAssets` declares,
-        // which `AssetManager.loadAt` awaits *before* this node is laid out — so
-        // there the tokens are right the first time rather than upgrading later.
-        // (Theme is a synchronous color style; only the language parser loads.)
-        ensureHighlighter(undefined, [this.language]).catch(() => { });
-        this.tokenize();
-    }
+/** `code` part-way through a `to({ code })`: the source it leaves, the one it lands on, and how far along it is, eased. */
+export interface CodeBlend {
+    readonly from: string;
+    readonly to: string;
+    readonly t: number;
+}
 
-    set(props: { [K in keyof CodeProps]?: CodeProps[K] | (() => CodeProps[K]) }): void {
-        super.set(props);
-        if (props.code !== undefined || props.language !== undefined || props.theme !== undefined) {
-            this.tokenized = false;
-        }
-    }
+/** What `code` holds: a source, or a {@link CodeBlend} while a `to({ code })` runs. */
+export type CodeSource = string | CodeBlend;
 
-    private tokenize(): void {
-        this.setLines(tokenizeCodeToIdLines(this.code, this.language, this.theme));
-        // Only consider ourselves tokenized once we actually highlighted; while
-        // the language is still loading we keep retrying on each render.
-        this.tokenized = canHighlight(this.language, this.theme);
-    }
+/** A range argument: one range, several, or a chain that went through JSON as `{ list }`. */
+export type CodeTarget = CodeRange | Iterable<CodeRange> | { readonly list: CodeRange[] };
 
-    /**
-     * Swap in a new settled structure, invalidating the layout cache.
-     *
-     * The one place `tokenLines` is written, because the cache key is a version
-     * counter rather than a hash of the content — a write that skipped the bump
-     * would keep serving the previous frame's geometry for the new listing.
-     */
-    private setLines(lines: IdLine[]): void {
-        if (this.tokenLines === lines) return;
-        this.tokenLines = lines;
-        this.structureVersion++;
-        this.layoutCache = null;
-        this.layoutCacheKey = null;
-    }
+/** What a structure was tokenized with: the grammar, the theme and whether the grammar had landed. */
+export interface CodeTokenBasis {
+    readonly language: string;
+    readonly theme: CodeTheme;
+    readonly highlighted: boolean;
+}
 
-    /**
-     * The monospaced face this block measures and draws with, and the syntax
-     * grammar it tokenizes with.
-     *
-     * Both belong to *layout*: token x positions are measured against the face,
-     * and how many tokens there are depends on the grammar. Declared here, the
-     * grammar goes on the timeline as an ordinary asset: `AssetManager.loadAt`
-     * waits for it before the frame is laid out, so the first measurement is the
-     * right one. Nothing is freed on eviction — parsers are cheap to keep
-     * resident. The loader touches no node: `renderContent` re-tokenizes once
-     * the grammar is there.
-     */
-    override declareAssets(assets: AssetScope): void {
-        super.declareAssets(assets);
-        assets.font(this.fontFamily);
-        assets.loader(`shiki:lang:${this.language}`, grammarLoader(this.language), { gate: "layout" });
-    }
+/** A listing a command left behind: its source, its tokens, and the basis they were made on. */
+export interface CodeListing {
+    readonly source: string;
+    readonly lines: IdLine[];
+    readonly basis: CodeTokenBasis;
+}
 
-    // ── Geometry ────────────────────────────────────────────────────────────
-
-    private metrics(): CodeMetrics {
-        return {
-            fontSize: this.fontSize,
-            fontFamily: this.fontFamily,
-            lineHeight: this.lineHeight,
-            letterSpacing: this.letterSpacing,
-            padding: this.padding,
-            showLineNumbers: this.showLineNumbers,
-            lineNumberGap: this.lineNumberGap,
-        };
-    }
+export interface CodeEditFrame {
+    readonly transition: StructuralTransition;
+    readonly progress: number;
+}
 
-    /** The structural edit currently in flight, if any. */
-    private activeEdit(): StructuralTransition | null {
-        for (let i = this.transitions.length - 1; i >= 0; i--) {
-            const tr = this.transitions[i];
-            if (tr.kind === "structural") return tr;
-        }
-        return null;
-    }
+/** The dim `highlight` leaves: what stays bright, what the rest dims to, and the cross-fade in flight. */
+export interface CodeFocus {
+    readonly dim: number | null;
+    readonly ids: Set<number>;
+    readonly fade: DimTransition | null;
+}
 
-    private settledLayout(m: CodeMetrics, scope: MeasureContext2D | RenderContext2D): CodeLayout {
-        const key = `${this.structureVersion}|${metricsSignature(m)}|${this.advanceCache.signature(m.fontSize, m.fontFamily)}`;
-        if (this.layoutCache && this.layoutCacheKey === key) return this.layoutCache;
-        const layout = layoutCode(this.tokenLines, m, this.advanceCache, scope);
-        this.layoutCache = layout;
-        this.layoutCacheKey = key;
-        return layout;
-    }
+export interface CodeBanding {
+    readonly bands: RowBand[];
+    readonly fade: RowsTransition | null;
+}
 
-    /**
-     * The one or two layouts this frame is drawn from.
-     *
-     * A settled frame has one. A frame inside an edit has two — where every
-     * token was, and where it is going — and the frame is a point between them.
-     * That is the whole reason an insert no longer piles its glyphs at the left
-     * margin: a token's destination is *computed*, not approximated by collapsing
-     * the advance of everything around it.
-     *
-     * Both endpoints are fixed for the edit's duration, so they are built once
-     * and cached on the transition rather than rebuilt per frame.
-     */
-    private frameLayout(scope: MeasureContext2D | RenderContext2D): {
-        from: CodeLayout;
-        to: CodeLayout;
-        edit: StructuralTransition | null;
-    } {
-        const m = this.metrics();
-        const edit = this.activeEdit();
-        if (!edit) {
-            const layout = this.settledLayout(m, scope);
-            return { from: layout, to: layout, edit: null };
-        }
-        const key = `${metricsSignature(m)}|${this.advanceCache.signature(m.fontSize, m.fontFamily)}`;
-        if (edit.layoutKey !== key || !edit.fromLayout || !edit.toLayout) {
-            edit.fromLayout = layoutCode(edit.from, m, this.advanceCache, scope);
-            edit.toLayout = layoutCode(edit.to, m, this.advanceCache, scope);
-            edit.layoutKey = key;
-        }
-        return { from: edit.fromLayout, to: edit.toLayout, edit };
-    }
+/** Each `Code` component's strategies and edit cache, by the node class it generated. */
+const kits = new WeakMap<object, Kit>();
 
-    override measure(constraints: SizeConstraints, scope: MeasureContext2D): Partial<Size2D> {
-        this.advanceCache.sync(this.advanceCache.signature(this.fontSize, this.fontFamily));
-        const wm = this.width;
-        const hm = this.height;
-
-        const { from, to, edit } = this.frameLayout(scope);
-        const t = moveProgress(edit);
-        const innerW = edit ? lerpNumber(from.innerW, to.innerW, t) : to.innerW;
-        const innerH = edit ? lerpNumber(from.innerH, to.innerH, t) : to.innerH;
-
-        const resolvedW = typeof wm === "number"
-            ? wm
-            : wm === "hug"
-                ? innerW + this.padding.left + this.padding.right
-                : constraints.maxWidth ?? 0;
-
-        const resolvedH = typeof hm === "number"
-            ? hm
-            : hm === "hug"
-                ? innerH + this.padding.top + this.padding.bottom
-                : constraints.maxHeight ?? 0;
-
-        return { width: resolvedW, height: resolvedH };
-    }
+const NO_FOCUS: CodeFocus = { dim: null, ids: new Set(), fade: null };
+const NO_BANDING: CodeBanding = { bands: [], fade: null };
 
-    protected override renderContent(ctx: RenderPass2D): void {
-        // Refuse the ambient `<DefaultTextStyle>` / theme typography defaults for
-        // everything drawn inside this node.
-        //
-        // Those defaults describe the *document's* prose — a display face, a
-        // heading weight, a paragraph line-height — and a code block is not prose.
-        // Its own props are the vocabulary: `fontFamily` defaults to a monospaced
-        // face because column alignment depends on it, `letterSpacing` and
-        // `lineHeight` are tuned against that face, and every token is laid out at
-        // an x measured from those exact values. A scene-wide serif family or a
-        // 700 weight arriving through the draw scope would shape glyphs the
-        // geometry was never measured for, and the block would come apart
-        // column-by-column rather than merely look different.
-        ctx.pushTextStyle(null);
-        try {
-            // Keep retrying until the language+theme have actually loaded, so a frame
-            // that rendered as plain text upgrades to full highlighting the moment the
-            // asset loader resolves. Never mid-edit: re-tokenizing mints fresh ids,
-            // and an in-flight transition is keyed by the ones it captured.
-            if (!this.tokenized && !this.activeEdit() && canHighlight(this.language, this.theme)) {
-                this.tokenize();
-            }
-            super.renderContent(ctx);
-        } finally {
-            ctx.popTextStyle();
-        }
-    }
+/** A private entry: commands write it, documents and calls never see it. */
+function own<T>(initial: T) {
+    return Types.custom<T, T, { readonly private: true }>(initial, { private: true });
+}
 
-    protected override renderSelf(ctx: RenderContext2D): void {
-        this.drawSelf(ctx);
-    }
+const TARGET = Types.custom<CodeTarget | undefined>(undefined, { kind: "selector" });
+const TEXT = Types.text("", { multiline: true });
 
-    /** A listing holds a listing — `append`/`insert`/`erase` are how it grows. */
-    protected override acceptsChild(_child: Node): boolean {
-        return false;
-    }
+/**
+ * A `Code` whose edits are paired and timed by `strategies`. {@link Code} is
+ * the one with the defaults; a project wanting another hands its own to the
+ * engine in its place (the key is the same).
+ *
+ * A listing and nothing else: no paint slots, and no box behind the tokens. A
+ * listing set on a card is a `Code` inside a hugging `Rect`.
+ */
+export function defineCode(strategies: CodeStrategies = {}) {
+    const kit: Kit = {
+        diff: strategies.diffStrategy ?? defaultCodeDiff,
+        phases: strategies.phaseStrategy ?? defaultCodePhases,
+        edits: new WeakMap(),
+    };
+    const act = (timeline: { animate(frame: Frame): Piece; wait(seconds: number): Piece }, frame: Frame | null): Piece =>
+        (frame ? timeline.animate(frame) : timeline.wait(0));
+
+    const component = component2d({
+        key: "code",
+        state: {
+            code: Types.custom<string, CodeSource>("", { lerp: blendSource }),
+            language: "typescript",
+            fontFamily: "Fira Mono",
+            /** A built-in or registered theme name (e.g. `'github-dark'`), or a `CodeHighlightStyle` object. */
+            theme: Types.custom<CodeTheme>(DefaultHighlightStyle.name),
+            fontSize: 16,
+            lineHeight: 1.6,
+            // Extra space after every glyph, in px: folded into the advance a token is measured at.
+            letterSpacing: 1.1,
+            showLineNumbers: false,
+            // In space-widths, so it scales with fontSize.
+            lineNumberGap: 2,
+            listing: own<CodeListing | null>(null),
+            edit: own<CodeEditFrame | null>(null),
+            focus: own(NO_FOCUS),
+            banding: own(NO_BANDING),
+        },
+        defaults: { width: "hug", height: "hug" },
+        allowedChildren: [],
+        // The grammar gates layout: how many tokens there are, and so where each sits, depends on it.
+        load: (loader, state) => {
+            loader.font(state.fontFamily);
+            loader.task(`shiki:lang:${state.language}`, grammarLoader(state.language), { before: "layout" });
+        },
+        commands: {
+            /** Append `code` to the end of the listing. */
+            append: {
+                args: { code: TEXT },
+                run: (timeline, state) => {
+                    const seen = current(state, kit);
+                    return act(timeline, editFrame(kit, seen, seen.source + timeline.args.code, basisOf(state)));
+                },
+            },
+            /** Insert `code` above the listing. */
+            prepend: {
+                args: { code: TEXT },
+                run: (timeline, state) => {
+                    const seen = current(state, kit);
+                    return act(timeline, editFrame(kit, seen, timeline.args.code + seen.source, basisOf(state)));
+                },
+            },
+            /** Insert `code` before the 1-indexed `[line, col]`, clamped into the listing. */
+            insert: {
+                args: {
+                    position: Types.custom<[number, number] | undefined>(undefined, {
+                        kind: "point",
+                        properties: {
+                            line: { kind: "number", default: 1, min: 1, step: 1 },
+                            col: { kind: "number", default: 1, min: 1, step: 1 },
+                        },
+                    }),
+                    code: TEXT,
+                },
+                run: (timeline, state) => {
+                    const seen = current(state, kit);
+                    const offset = offsetAt(seen.lines, timeline.args.position as [number, number]);
+                    const next = seen.source.slice(0, offset) + timeline.args.code + seen.source.slice(offset);
+                    return act(timeline, editFrame(kit, seen, next, basisOf(state)));
+                },
+            },
+            /**
+             * Erase the code in `target`. A range of whole lines takes their line
+             * breaks with it, so the rows below close up.
+             */
+            remove: {
+                args: { target: TARGET },
+                run: (timeline, state) => act(timeline, eraseFrame(kit, state, timeline.args.target as CodeRange)),
+            },
+            replace: {
+                args: { target: TARGET, replacement: TEXT },
+                run: (timeline, state) => {
+                    const seen = current(state, kit);
+                    const { start, end } = rangeToCharOffsets(timeline.args.target as CodeRange, lineLengths(seen.lines));
+                    const next = seen.source.slice(0, start) + timeline.args.replacement + seen.source.slice(end);
+                    return act(timeline, editFrame(kit, seen, next, basisOf(state)));
+                },
+            },
+            /**
+             * Dim everything outside `target` (one range or several) to `dim`.
+             * Persistent: a second highlight cross-fades from this one.
+             */
+            highlight: {
+                args: {
+                    target: TARGET,
+                    dim: Types.number(0.4, { min: 0, max: 1, step: 0.01, scale: 100, unit: "%" }),
+                },
+                run: (timeline, state) => act(timeline, highlightFrame(kit, state, timeline.args.target, timeline.args.dim)),
+            },
+            /** Fade every dimmed token back to full and clear the highlight. */
+            resetHighlight: (timeline, state) => act(timeline, resetHighlightFrame(kit, state)),
+            /**
+             * Lay a band of `color` behind every line a range touches. A second
+             * call slides the bands onto their new rows, paired in order; a band
+             * keeps to its lines through an edit.
+             */
+            highlightRows: {
+                args: {
+                    target: TARGET,
+                    color: Types.color(ROW_BAND_COLOR),
+                    radius: Types.number(ROW_BAND_RADIUS, { min: 0, step: 1 }),
+                },
+                run: (timeline, state) => {
+                    const seen = current(state, kit);
+                    const bands = rowBandsIn(seen.lines, normalizeCodeRanges(timeline.args.target), timeline.args.color, Math.max(0, timeline.args.radius ?? ROW_BAND_RADIUS));
+                    return act(timeline, rowsFrame(seen, state.banding.bands, bands));
+                },
+            },
+            /** Fade every row band out and clear them. */
+            resetRowHighlight: (timeline, state) => act(timeline, rowsFrame(current(state, kit), state.banding.bands, [])),
+        },
+        measure: (measurer, state) => measureListing(measurer, state, kit),
+        // Refuses the ambient text style: every column is measured against this face, so an
+        // inherited family or weight would shape glyphs the geometry was never measured for.
+        render:(ctx, state) => ctx.textStyle(null, () => drawListing(ctx, state, kit)),
+    });
+    kits.set(component.node, kit);
+    return component;
+}
 
-    /**
-     * The node's laid-out rect as a clip outline, so `clip` and any backdrop
-     * effect are confined to the block rather than to nothing — a listing set on
-     * a card is exactly where a backdrop blur is asked for.
-     */
-    protected override clipSelf(): Clip {
-        return new Clip().rect({
-            width: this.layoutBounds.width,
-            height: this.layoutBounds.height,
-        });
-    }
+/**
+ * A syntax-highlighted listing whose edits animate token by token: each edit
+ * is diffed against what is on screen, so a token that survives travels to
+ * its new column and only what changed fades.
+ */
+export const Code = defineCode();
+export type Code = NodeOf<typeof Code>;
+export type CodeProps = NonNullable<Parameters<typeof Code>[0]>;
+
+/** What a listing shows now: its source, its token rows, and the edit in flight, if any. */
+export function listingOf(code: Code): { readonly source: string; readonly lines: readonly IdLine[]; readonly edit: StructuralTransition | null } {
+    const kit = kits.get(code.constructor);
+    if (!kit) throw new TypeError("listingOf takes a node a `Code` component built.");
+    const view = shown(code, kit);
+    return { source: view.source, lines: view.lines, edit: editOf(view) };
+}
 
-    /**
-     * A listing is grabbed by its **text**, line by ragged line, rather than by
-     * the rectangle the lines were laid out in.
-     *
-     * The default narrows a node's grab region to the outline it declares, and
-     * this node's outline is a box it no longer paints anything into. Code is
-     * mostly whitespace: a ten-line snippet with one long line is a rectangle
-     * that is largely empty, and in an editor every one of those empty pixels
-     * swallows a click meant for whatever sits behind or beneath it. Short of the
-     * text itself there is nothing there to have clicked.
-     *
-     * So the region is the union of the lines' own extents — each a line-height
-     * slot as wide as that line's ink — plus the gutter where line numbers are
-     * showing, since those are drawn glyphs too.
-     *
-     * Answered from the **cached** layout, which is what the last frame drew
-     * from, because a hit test arrives with no measurement scope and text cannot
-     * be measured without one. Where there is no usable cache — before the first
-     * frame, or mid-edit, when the geometry is an interpolation of two structures
-     * held on the transition — the box is the honest answer rather than a
-     * silhouette measured against stale metrics.
-     */
-    protected override hitTestSelf(local: Vector2, tolerance: number): boolean {
-        const layout = this.hitLayout();
-        if (!layout) return super.hitTestSelf(local, tolerance);
-
-        // Never *wider* than the box: `hug` sizes to the ink, but a fixed width
-        // narrower than the longest line would otherwise be hit outside itself.
-        if (!super.hitTestSelf(local, tolerance)) return false;
-
-        const half = (this.fontSize * this.lineHeight) / 2;
-        // Line numbers sit in the gutter, to the left of every line's own start,
-        // so a numbered blank line is still grabbable — by its number.
-        const gutter = this.showLineNumbers ? layout.gutter : 0;
-        const left = layout.startX - gutter - tolerance;
-        for (let i = 0; i < layout.lineY.length; i++) {
-            const width = (layout.lineW[i] ?? 0) + gutter;
-            if (width <= 0) continue;
-            if (Math.abs(local.y - layout.lineY[i]) > half + tolerance) continue;
-            if (local.x >= left && local.x <= layout.startX + (layout.lineW[i] ?? 0) + tolerance) {
-                return true;
-            }
-        }
-        return false;
-    }
+/** Every range matching the literal `text` in `source`, in order and not overlapping. Multi-line matches are found too. */
+export function findAllRanges(source: CodeSource, text: string): CodeRange[] {
+    const ranges: CodeRange[] = [];
+    if (!text) return ranges;
+    const joined = normalizeSource(sourceText(source));
+    const lineLens = joined.split("\n").map((line) => line.length);
+    let from = 0;
+    while (true) {
+        const idx = joined.indexOf(text, from);
+        if (idx === -1) break;
+        ranges.push(charOffsetsToRange(idx, idx + text.length, lineLens));
+        from = idx + Math.max(1, text.length);
+    }
+    return ranges;
+}
 
-    /**
-     * The layout a hit test may be answered from: the settled cache, and only
-     * while it still matches the node's current metrics.
-     *
-     * The key is the one {@link settledLayout} writes minus its scope-dependent
-     * half — every input to it (`metricsSignature`, the advance cache's own
-     * signature) is readable without a measurer, which is precisely what makes
-     * the check possible here.
-     */
-    private hitLayout(): CodeLayout | null {
-        if (!this.layoutCache || this.activeEdit()) return null;
-        const m = this.metrics();
-        const key = `${this.structureVersion}|${metricsSignature(m)}|${this.advanceCache.signature(m.fontSize, m.fontFamily)}`;
-        return this.layoutCacheKey === key ? this.layoutCache : null;
-    }
+/** The `index`th range matching `text`, or `null`. */
+export function findRangeAt(source: CodeSource, text: string, index: number): CodeRange | null {
+    return findAllRanges(source, text)[index] ?? null;
+}
 
-    // ── Editing commands ────────────────────────────────────────────────────
-
-    /**
-     * Append `code` to the end of the listing.
-     *
-     * Stated as *what the source becomes*; {@link editTo} works out the rest —
-     * which is why appending a line that closes a block re-highlights the lines
-     * above it, instead of colouring the new text as its own program.
-     */
-    @command({ args: [{ key: "code", kind: "text", multiline: true }] })
-    append(args: CommandArgs<{ code: string }> & { duration: number }): Command<Record<string, never>> {
-        const { code } = args.data as { code: string };
-        return this.editTo(this.joinedSource() + code, args.duration, args.easing);
-    }
+/** The first range matching `text`, or `null`. */
+export function findFirstRange(source: CodeSource, text: string): CodeRange | null {
+    return findRangeAt(source, text, 0);
+}
 
-    /** Insert `code` above the listing. */
-    @command({ args: [{ key: "code", kind: "text", multiline: true }] })
-    prepend(args: CommandArgs<{ code: string }> & { duration: number }): Command<Record<string, never>> {
-        const { code } = args.data as { code: string };
-        return this.editTo(code + this.joinedSource(), args.duration, args.easing);
-    }
+// ── What a listing shows ────────────────────────────────────────────────────
 
-    /**
-     * Insert `code` at the given (line, col). Both are 1-indexed; col is the
-     * column BEFORE which the new content is inserted (col=1 means start of
-     * line). If `code` contains newlines, new lines are created in the middle
-     * of the existing line.
-     */
-    @command({
-        args: [
-            // Two controls, one argument: the method takes a `[line, col]`
-            // tuple, so the pair a host draws is declared *inside* the value it
-            // composes into rather than flattened beside it.
-            {
-                key: "position", kind: "point", properties: {
-                    line: { kind: "number", default: 1, min: 1, step: 1 },
-                    col: { kind: "number", default: 1, min: 1, step: 1 },
-                },
-            },
-            { key: "code", kind: "text", default: "", multiline: true },
-        ],
-    })
-    insert(
-        args: CommandArgs<{ position: [number, number]; code: string }> & { duration: number },
-    ): Command<Record<string, never>> {
-        const { position, code } = args.data as { position: [number, number]; code: string };
-        const source = this.joinedSource();
-        const offset = this.offsetAt(position);
-        return this.editTo(source.slice(0, offset) + code + source.slice(offset), args.duration, args.easing);
-    }
+interface Kit {
+    readonly diff: CodeDiffStrategy;
+    readonly phases: CodePhaseStrategy;
+    /** The edit from a listing to a source and basis, built once: a `to({ code })` asks for it every frame. */
+    readonly edits: WeakMap<IdLine[], Map<string, Map<string, Edited>>>;
+}
 
-    /**
-     * Erase the code in `codeRange`.
-     *
-     * Named `erase` rather than `remove` because a `Code` is also a node, and
-     * `Node.remove(child)` takes a child out of the tree. Two methods spelled
-     * the same on one object, doing entirely different things, is worse than one
-     * of them having a slightly less obvious name.
-     *
-     * A range that covers whole lines takes their line breaks with it, so the
-     * rows below close up; a range inside a line takes only the characters, and
-     * the rest of the line reflows around the hole.
-     */
-    @command({ key: "remove", args: [{ key: "target", kind: "selector" }] })
-    erase(
-        args: CommandArgs<{ target: CodeRange }> & { duration: number },
-    ): Command<Record<string, never>> {
-        const { target: codeRange } = args.data as { target: CodeRange };
-        const { duration, easing } = args;
-        const source = this.joinedSource();
-        let { start, end } = rangeToCharOffsets(codeRange, this.lineLengths());
-        // `lines(2)` resolves to the *characters* of line 2, not to the row —
-        // taking those alone would leave an empty line behind where an editor
-        // would have closed the gap. This is also what makes a blank row
-        // removable at all: it has no characters, so its range is empty, and
-        // "delete nothing" is not what `lines(2)` was asking for.
-        const atLineStart = start === 0 || source[start - 1] === "\n";
-        const atLineEnd = end === source.length || source[end] === "\n";
-        if (atLineStart && atLineEnd) {
-            if (end < source.length) end += 1;
-            else if (start > 0) start -= 1;
-        } else if (end <= start) {
-            return driveCommand(duration, () => { });
-        }
-        if (end <= start) return driveCommand(duration, () => { });
-        return this.editTo(source.slice(0, start) + source.slice(end), duration, easing);
-    }
+interface Edited {
+    readonly transition: StructuralTransition;
+    readonly listing: CodeListing;
+}
 
-    /** Replace the code in `codeRange` with `replacement`. */
-    @command({ args: [{ key: "target", kind: "selector" }, { key: "replacement", kind: "text", default: "", multiline: true }] })
-    replace(
-        args: CommandArgs<{ target: CodeRange; replacement: string }> & { duration: number },
-    ): Command<Record<string, never>> {
-        const { target: codeRange, replacement } = args.data as { target: CodeRange; replacement: string };
-        const source = this.joinedSource();
-        const { start, end } = rangeToCharOffsets(codeRange, this.lineLengths());
-        return this.editTo(source.slice(0, start) + replacement + source.slice(end), args.duration, args.easing);
-    }
+/** What the structure resolves from. A command's snapshot and a node's own state view both are one. */
+interface ListingState {
+    readonly code: CodeSource;
+    readonly language: string;
+    readonly theme: CodeTheme;
+    readonly listing: CodeListing | null;
+    readonly edit: CodeEditFrame | null;
+}
 
-    /**
-     * Highlight a range of code — or several at once (e.g.
-     * `CodeRanges.lines(2).word(5, 1, 3)`) — highlighted as one set: tokens
-     * within any of the ranges stay at opacity 1, tokens outside dim to
-     * `dim`. Persistent — call resetHighlight() to undo, or call highlight()
-     * again with a different range to cross-fade.
-     */
-    @command({ args: [{ key: "target", kind: "selector" }, { key: "dim", kind: "number", default: 0.4, min: 0, max: 1, step: 0.01, scale: 100, unit: "%" }] })
-    highlight(
-        args: CommandArgs<{ target: CodeRange | Iterable<CodeRange>; dim?: number }> & { duration: number },
-    ): Command<Record<string, never>> {
-        const { target: codeRange, dim } = args.data as { target: CodeRange | Iterable<CodeRange>; dim?: number };
-        const { duration, easing } = args;
-        const toDim = dim ?? 0.4;
-        const matchIds = this.tokenIdsInRanges(normalizeCodeRanges(codeRange));
-        if (matchIds.size === 0) return driveCommand(duration, () => { });
-
-        const fromDim = this.highlightDimOpacity ?? 1;
-        const hadPrevious = this.highlightedIds.size > 0;
-        const previousIds = this.highlightedIds;
-
-        const animTokens: AnimToken[] = [];
-        for (const line of this.tokenLines) {
-            for (const tok of line.tokens) {
-                const wasHighlighted = !hadPrevious || previousIds.has(tok.id);
-                const isHighlighted = matchIds.has(tok.id);
-                const fromOp = wasHighlighted ? 1 : fromDim;
-                const toOp = isHighlighted ? 1 : toDim;
-                if (fromOp === toOp) continue;
-                animTokens.push(makeAnim(tok.id, { keys: [0, 1], values: [fromOp, toOp] }));
-            }
-        }
+interface LayoutState extends ListingState {
+    readonly fontSize: number;
+    readonly fontFamily: string;
+    readonly lineHeight: number;
+    readonly letterSpacing: number;
+    readonly padding: InsetsResolved;
+    readonly showLineNumbers: boolean;
+    readonly lineNumberGap: number;
+}
 
-        // Which tokens are dimmed is state the *next* highlight reads to know
-        // what it is cross-fading from, so it is committed at the end and put
-        // back below it — a `finally` could only ever have run forwards.
-        return this.runDim(animTokens, duration, easing, (done) => {
-            this.highlightDimOpacity = done ? toDim : (hadPrevious ? fromDim : null);
-            this.highlightedIds = done ? matchIds : previousIds;
-        });
-    }
+interface DrawState extends LayoutState {
+    readonly focus: CodeFocus;
+    readonly banding: CodeBanding;
+}
 
-    /**
-     * Fade all dimmed tokens back to opacity 1 and clear the persistent
-     * highlight state.
-     */
-    @command()
-    resetHighlight(args: CommandArgs<Record<string, never>> & { duration: number }): Command<Record<string, never>> {
-        const { duration, easing } = args;
-        if (this.highlightDimOpacity === null) return driveCommand(duration, () => { });
-
-        const fromDim = this.highlightDimOpacity;
-        const previousIds = this.highlightedIds;
-
-        const animTokens: AnimToken[] = [];
-        for (const line of this.tokenLines) {
-            for (const tok of line.tokens) {
-                const fromOp = previousIds.has(tok.id) ? 1 : fromDim;
-                if (fromOp === 1) continue;
-                animTokens.push(makeAnim(tok.id, { keys: [0, 1], values: [fromOp, 1] }));
-            }
-        }
+/** The structure a frame draws, and the edit it is part-way through. */
+interface Shown {
+    readonly source: string;
+    readonly lines: IdLine[];
+    readonly transition: StructuralTransition | null;
+    readonly progress: number;
+}
 
-        return this.runDim(animTokens, duration, easing, (done) => {
-            this.highlightDimOpacity = done ? null : fromDim;
-            this.highlightedIds = done ? new Set() : previousIds;
-        });
-    }
+/**
+ * A `to({ code })` mid-flight comes first: it wrote `code` after any edit
+ * command did. Then an edit command in flight, then the settled listing.
+ */
+function shown(s: ListingState, kit: Kit): Shown {
+    const code = s.code;
+    if (typeof code !== "string") {
+        const { transition } = edited(settled(s, code.from, kit), code.to, basisOf(s), kit);
+        return { source: code.to, lines: transition.to, transition, progress: code.t };
+    }
+    if (s.edit) return { source: normalizeSource(code), lines: s.edit.transition.to, transition: s.edit.transition, progress: s.edit.progress };
+    const listing = settled(s, normalizeSource(code), kit);
+    return { source: listing.source, lines: listing.lines, transition: null, progress: 1 };
+}
 
-    /**
-     * Animate the listing to a new source.
-     *
-     * The engine behind every editing command, and behind `to({ code })`. Every
-     * edit is expressed as the source it produces, tokenized, and then *diffed*
-     * against what is on screen — so a token that survived the edit keeps its
-     * identity and simply travels to its new column, and only what genuinely
-     * changed is faded.
-     *
-     * The result runs in three phases (see `phaseStrategy`): what is leaving
-     * fades out, what stays reflows, and only then does what is new arrive.
-     * Playing them together is what made a replacement read as a cross-dissolve
-     * of two unrelated listings rather than as an edit being made.
-     */
-    private editTo(next: string, duration: number, easing?: EasingFunction): Command<Record<string, never>> {
-        const from = this.tokenLines;
-        const fromCode = this.joinedSource();
-        if (next === fromCode) return driveCommand(duration, () => { });
-
-        const edit = this.diffStrategy(from, tokenizeCodeToIdLines(next, this.language, this.theme));
-
-        const transition: StructuralTransition = {
-            kind: "structural",
-            from,
-            to: edit.lines,
-            removedIds: edit.removedIds,
-            addedIds: edit.addedIds,
-            enteringLineIds: edit.newLineIds,
-            fromColorById: edit.fromColorById,
-            phases: this.phaseStrategy(edit.removedIds.size > 0, edit.addedIds.size > 0),
-            progress: 0,
-            layoutKey: null,
-            fromLayout: null,
-            toLayout: null,
-        };
+function editOf(view: Shown): StructuralTransition | null {
+    return view.transition ? { ...view.transition, progress: view.progress } : null;
+}
 
-        // A tokenize triggered by the grammar landing mid-edit would mint fresh
-        // ids underneath this transition, and the transition is keyed by the ones
-        // it captured — so the retry in `onRender` is gated on there being no edit
-        // in flight, which means this flag has to be honest now rather than once
-        // the edit settles.
-        this.tokenized = canHighlight(this.language, this.theme);
-
-        return driveCommand(duration, (t) => {
-            const running = t > 0 && t < 1;
-            const index = this.transitions.indexOf(transition);
-            if (running && index < 0) this.transitions.push(transition);
-            else if (!running && index >= 0) this.transitions.splice(index, 1);
-
-            transition.progress = easing ? easing(t) : t;
-
-            // The settle, in both directions: asked for a time before the edit
-            // starts, the listing is what preceded it; at or past the end, the
-            // result. A `finally` could only ever have run forwards.
-            if (t <= 0) {
-                this.setLines(from);
-                this._writeProp("code", fromCode);
-            } else {
-                this.setLines(edit.lines);
-                this._writeProp("code", next);
-            }
-        });
-    }
+/** The listing a command starts from. */
+function current(s: ListingState, kit: Kit): CodeListing {
+    return settled(s, normalizeSource(sourceText(s.code)), kit);
+}
 
-    /**
-     * Put a dim transition on the stack, drive its progress, take it off and
-     * commit at the end.
-     *
-     * A {@link Command} rather than a generator, which is what makes a listing
-     * scrubbable: membership is a function of `t` (on the stack for `0 < t < 1`,
-     * off it outside), `settle(done)` replaces the `finally` and takes *which
-     * way*, and `progress` is assigned from `t` rather than accumulated.
-     */
-    private runDim(
-        tokens: AnimToken[],
-        duration: number,
-        easing?: EasingFunction,
-        settle?: (done: boolean) => void,
-    ): Command<Record<string, never>> {
-        const transition = { kind: "dim" as const, tokens, progress: 0 };
-
-        return driveCommand(duration, (t) => {
-            const running = t > 0 && t < 1;
-            const index = this.transitions.indexOf(transition);
-            if (running && index < 0) this.transitions.push(transition);
-            else if (!running && index >= 0) this.transitions.splice(index, 1);
-
-            transition.progress = easing ? easing(t) : t;
-            settle?.(t >= 1);
-        });
-    }
+/**
+ * The structure `source` settles on. Until a listing command has acted, the
+ * props are all there is; after one, it is the listing that command left,
+ * recoloured keeping its ids when only the theme moved, and diffed onward
+ * when the source has (a `to({ code })` that landed, a binding).
+ */
+function settled(s: ListingState, source: string, kit: Kit): CodeListing {
+    const basis = basisOf(s);
+    const pinned = s.listing;
+    if (!pinned) return derived(source, basis);
+    if (pinned.source !== source) return edited(pinned, source, basis, kit).listing;
+    if (sameBasis(pinned.basis, basis)) return pinned;
+    if (pinned.basis.language === basis.language && pinned.basis.highlighted === basis.highlighted) return recoloured(pinned, basis);
+    return derived(source, basis);
+}
 
-    /**
-     * Route a tweened `code` through the diff engine.
-     *
-     * `to({ code })` is the form an author reaches for first — it is how every
-     * other prop is animated — and a bare string prop would otherwise land in the
-     * generic tween's discrete-snap bucket and simply cut at the end. Intercepted
-     * here it becomes the same three-phase edit the named commands produce, while
-     * the rest of the step's props tween alongside it untouched.
-     */
-    override _prepareStep(
-        to: Partial<CodeProps>,
-        duration: number,
-        easing?: EasingFunction,
-    ): TweenStepper {
-        const next = to.code;
-        if (typeof next !== "string" || next === this.joinedSource()) {
-            return super._prepareStep(to, duration, easing);
-        }
+function basisOf(s: { readonly language: string; readonly theme: CodeTheme }): CodeTokenBasis {
+    return { language: s.language, theme: s.theme, highlighted: canHighlight(s.language, s.theme) };
+}
 
-        const rest: Partial<CodeProps> = { ...to };
-        delete rest.code;
-        // Prepared before the edit, so a step that also moves `fontSize` has
-        // snapshotted its own start value against the listing that is still on
-        // screen.
-        const others = super._prepareStep(rest, duration, easing);
-        const edit = this.editTo(next, duration, easing)._stepper();
-
-        return {
-            seek: (elapsed: number) => {
-                others.seek(elapsed);
-                edit.seek(elapsed);
-            },
-            advance: (dt: number): boolean => {
-                const othersDone = others.advance(dt);
-                const editDone = edit.advance(dt);
-                return othersDone && editDone;
-            },
-        };
-    }
+function sameBasis(a: CodeTokenBasis, b: CodeTokenBasis): boolean {
+    return a.language === b.language && a.theme === b.theme && a.highlighted === b.highlighted;
+}
 
-    // ── Source queries ──────────────────────────────────────────────────────
-
-    /**
-     * Find every range matching the literal string `text` in the current
-     * source. Multi-line matches are supported.
-     */
-    findAllRanges(text: string): CodeRange[] {
-        const ranges: CodeRange[] = [];
-        if (!text) return ranges;
-        const source = this.joinedSource();
-        const lineLens = this.lineLengths();
-        let from = 0;
-        while (true) {
-            const idx = source.indexOf(text, from);
-            if (idx === -1) break;
-            ranges.push(charOffsetsToRange(idx, idx + text.length, lineLens));
-            from = idx + Math.max(1, text.length);
-        }
-        return ranges;
-    }
+/** The source `code` names: where a `to({ code })` is heading, mid-tween. */
+function sourceText(code: CodeSource): string {
+    return typeof code === "string" ? code : code.to;
+}
 
-    /** Find the `index`th range matching `text`. Returns null if not found. */
-    findRangeAt(text: string, index: number): CodeRange | null {
-        const all = this.findAllRanges(text);
-        return all[index] ?? null;
-    }
+/**
+ * Mid-tween `code` holds both sources, so the frame can draw the edit between
+ * them; at either end it is a source again.
+ */
+function blendSource(from: CodeSource, to: CodeSource, t: number): CodeSource {
+    const leaving = sourceText(from);
+    const arriving = sourceText(to);
+    const a = normalizeSource(leaving);
+    const b = normalizeSource(arriving);
+    // Nothing to edit: it snaps at the end, as any text does.
+    if (a === b) return t >= 1 ? arriving : leaving;
+    if (t <= 0) return a;
+    if (t >= 1) return b;
+    return { from: a, to: b, t };
+}
 
-    /** Find the first range matching `text`. Returns null if not found. */
-    findFirstRange(text: string): CodeRange | null {
-        return this.findRangeAt(text, 0);
+const DERIVED = new Map<string, Map<string, CodeListing>>();
+/** Sources kept tokenized per basis, oldest dropped first; a bound `code` can name any number of them. */
+const DERIVED_LISTINGS = 256;
+
+/** The props' own listing, the same object (and ids) each time it is asked for again. */
+function derived(source: string, basis: CodeTokenBasis): CodeListing {
+    return recall(DERIVED, basisKey(basis), source, DERIVED_LISTINGS, () => ({ source, lines: tokenize(source, basis), basis }));
+}
+
+const RECOLOURED = new WeakMap<IdLine[], Map<string, Map<string, CodeListing>>>();
+
+/** `pinned` in another theme: the same text split the same way keeps the ids a highlight or a band names. */
+function recoloured(pinned: CodeListing, basis: CodeTokenBasis): CodeListing {
+    let shelf = RECOLOURED.get(pinned.lines);
+    if (!shelf) RECOLOURED.set(pinned.lines, shelf = new Map());
+    return recall(shelf, basisKey(basis), pinned.source, 4, () => {
+        const lines = tokenize(pinned.source, basis);
+        adoptIds(pinned.lines, lines);
+        return { source: pinned.source, lines, basis };
+    });
+}
+
+function edited(from: CodeListing, next: string, basis: CodeTokenBasis, kit: Kit): Edited {
+    let shelf = kit.edits.get(from.lines);
+    if (!shelf) kit.edits.set(from.lines, shelf = new Map());
+    return recall(shelf, basisKey(basis), next, 16, () => buildEdit(kit, from.lines, next, basis));
+}
+
+function buildEdit(kit: Kit, from: IdLine[], next: string, basis: CodeTokenBasis): Edited {
+    const edit = kit.diff(from, tokenize(next, basis));
+    const transition: StructuralTransition = {
+        kind: "structural",
+        from,
+        to: edit.lines,
+        removedIds: edit.removedIds,
+        addedIds: edit.addedIds,
+        enteringLineIds: edit.newLineIds,
+        fromColorById: edit.fromColorById,
+        phases: kit.phases(edit.removedIds.size > 0, edit.addedIds.size > 0),
+        progress: 0,
+        layoutKey: null,
+        fromLayout: null,
+        toLayout: null,
+    };
+    return { transition, listing: { source: next, lines: edit.lines, basis } };
+}
+
+function tokenize(source: string, basis: CodeTokenBasis): IdLine[] {
+    // Best effort outside the asset pipeline (a test, a headless measure): on the timeline `load` has the grammar in first.
+    if (!basis.highlighted) ensureHighlighter(undefined, [basis.language]).catch(() => { });
+    return tokenizeCodeToIdLines(source, basis.language, basis.theme);
+}
+
+const styleIds = new WeakMap<object, number>();
+let nextStyleId = 1;
+
+function basisKey(basis: CodeTokenBasis): string {
+    let theme: string;
+    if (typeof basis.theme === "string") theme = `name:${basis.theme}`;
+    else {
+        let id = styleIds.get(basis.theme);
+        if (id === undefined) styleIds.set(basis.theme, id = nextStyleId++);
+        theme = `style:${id}`;
     }
+    return `${basis.language}\n${basis.highlighted ? 1 : 0}\n${theme}`;
+}
+
+/** Memoized by basis, then by source; a basis keeps `limit` sources, least recently asked for dropped first. */
+function recall<T>(shelf: Map<string, Map<string, T>>, basis: string, source: string, limit: number, make: () => T): T {
+    let row = shelf.get(basis);
+    if (!row) shelf.set(basis, row = new Map());
+    const hit = row.get(source);
+    if (hit !== undefined) {
+        row.delete(source);
+        row.set(source, hit);
+        return hit;
+    }
+    const made = make();
+    row.set(source, made);
+    if (row.size > limit) row.delete(row.keys().next().value as string);
+    return made;
+}
 
-    private joinedSource(): string {
-        return this.tokenLines
-            .map(line => line.tokens.map(t => t.content).join(''))
-            .join('\n');
+/** Carry `from`'s line and token ids onto `to` when the two spell the same tokens. */
+function adoptIds(from: IdLine[], to: IdLine[]): void {
+    if (from.length !== to.length) return;
+    for (let i = 0; i < from.length; i++) {
+        const a = from[i].tokens;
+        const b = to[i].tokens;
+        if (a.length !== b.length) return;
+        for (let j = 0; j < a.length; j++) if (a[j].content !== b[j].content) return;
     }
+    for (let i = 0; i < from.length; i++) {
+        to[i].id = from[i].id;
+        for (let j = 0; j < from[i].tokens.length; j++) to[i].tokens[j].id = from[i].tokens[j].id;
+    }
+}
+
+// ── Commands ────────────────────────────────────────────────────────────────
 
-    private lineLengths(): number[] {
-        return this.tokenLines.map(line =>
-            line.tokens.reduce((acc, t) => acc + t.content.length, 0),
-        );
+/** What a listing command writes at a point of its own eased time. */
+interface ListingWrites {
+    readonly code?: string;
+    readonly listing?: CodeListing | null;
+    readonly edit?: CodeEditFrame | null;
+    readonly focus?: CodeFocus;
+    readonly banding?: CodeBanding;
+}
+
+type Frame = (t: number) => ListingWrites;
+
+/**
+ * Each command writes the listing it acted on, at every time it is asked for,
+ * so the ids it captured are the ones drawn; before it starts the timeline has
+ * put back the props, and the listing is derived from them again.
+ */
+function editFrame(kit: Kit, seen: CodeListing, source: string, basis: CodeTokenBasis): Frame | null {
+    const next = normalizeSource(source);
+    if (next === seen.source) return null;
+    const { transition, listing } = buildEdit(kit, seen.lines, next, basis);
+    // Three phases (see `phaseStrategy`): what leaves fades out, what stays reflows, then what is new arrives.
+    return (t) => (t <= 0 ? { code: seen.source, listing: seen, edit: null }
+        : t >= 1 ? { code: next, listing, edit: null }
+        : { code: next, listing, edit: { transition, progress: t } });
+}
+
+function eraseFrame(kit: Kit, state: ListingState, target: CodeRange): Frame | null {
+    const seen = current(state, kit);
+    const source = seen.source;
+    let { start, end } = rangeToCharOffsets(target, lineLengths(seen.lines));
+    // `lines(2)` resolves to the characters of line 2: the row goes too, as an editor would close the gap. That is also what makes a blank row removable.
+    const atLineStart = start === 0 || source[start - 1] === "\n";
+    const atLineEnd = end === source.length || source[end] === "\n";
+    if (atLineStart && atLineEnd) {
+        if (end < source.length) end += 1;
+        else if (start > 0) start -= 1;
+    } else if (end <= start) {
+        return null;
     }
+    if (end <= start) return null;
+    return editFrame(kit, seen, source.slice(0, start) + source.slice(end), basisOf(state));
+}
 
-    /** Character offset of a 1-indexed (line, col), clamped into the document. */
-    private offsetAt(position: [number, number]): number {
-        const lens = this.lineLengths();
-        if (lens.length === 0) return 0;
-        const [rawLine, rawCol] = position;
-        const li = Math.max(0, Math.min(lens.length - 1, rawLine - 1));
-        let offset = 0;
-        for (let k = 0; k < li; k++) offset += lens[k] + 1;
-        return offset + Math.max(0, Math.min(lens[li], rawCol - 1));
+function highlightFrame(kit: Kit, state: ListingState & { readonly focus: CodeFocus }, target: CodeTarget | undefined, dim: number): Frame | null {
+    const seen = current(state, kit);
+    const toDim = dim ?? 0.4;
+    const matchIds = tokenIdsInRanges(seen.lines, normalizeCodeRanges(target));
+    if (matchIds.size === 0) return null;
+
+    const previous = state.focus;
+    const fromDim = previous.dim ?? 1;
+    const hadPrevious = previous.ids.size > 0;
+    const tokens: AnimToken[] = [];
+    for (const line of seen.lines) {
+        for (const tok of line.tokens) {
+            const fromOp = !hadPrevious || previous.ids.has(tok.id) ? 1 : fromDim;
+            const toOp = matchIds.has(tok.id) ? 1 : toDim;
+            if (fromOp === toOp) continue;
+            tokens.push(makeAnim(tok.id, { keys: [0, 1], values: [fromOp, toOp] }));
+        }
     }
+    // Which tokens are dimmed is what the next highlight cross-fades from, so it is committed at the end and put back below it.
+    const before: CodeFocus = { dim: hadPrevious ? fromDim : null, ids: previous.ids, fade: null };
+    const done: CodeFocus = { dim: toDim, ids: matchIds, fade: null };
+    return (t) => ({
+        listing: seen,
+        focus: t <= 0 ? before : t >= 1 ? done : { ...before, fade: { kind: "dim", tokens, progress: t } },
+    });
+}
 
-    /**
-     * Resolve one or more CodeRanges to the set of token ids whose content
-     * overlaps any of them. Tokens that partially overlap are included.
-     */
-    private tokenIdsInRanges(codeRanges: CodeRange[]): Set<number> {
-        const result = new Set<number>();
-        const lineLens = this.lineLengths();
-        if (lineLens.length === 0) return result;
-        const offsets = codeRanges
-            .map(r => rangeToCharOffsets(r, lineLens))
-            .filter(({ start, end }) => end > start);
-        if (offsets.length === 0) return result;
-
-        // Walk tokens with running offsets in the joined string, testing each
-        // token against every requested range's offsets.
-        let off = 0;
-        for (let li = 0; li < this.tokenLines.length; li++) {
-            const line = this.tokenLines[li];
-            for (const tok of line.tokens) {
-                const tStart = off;
-                const tEnd = off + tok.content.length;
-                if (offsets.some(({ start, end }) => tEnd > start && tStart < end)) result.add(tok.id);
-                off = tEnd;
-            }
-            if (li < this.tokenLines.length - 1) off += 1; // newline
+function resetHighlightFrame(kit: Kit, state: ListingState & { readonly focus: CodeFocus }): Frame | null {
+    const previous = state.focus;
+    if (previous.dim === null) return null;
+    const seen = current(state, kit);
+    const fromDim = previous.dim;
+    const tokens: AnimToken[] = [];
+    for (const line of seen.lines) {
+        for (const tok of line.tokens) {
+            const fromOp = previous.ids.has(tok.id) ? 1 : fromDim;
+            if (fromOp === 1) continue;
+            tokens.push(makeAnim(tok.id, { keys: [0, 1], values: [fromOp, 1] }));
         }
-        return result;
     }
+    const before: CodeFocus = { dim: fromDim, ids: previous.ids, fade: null };
+    return (t) => ({
+        listing: seen,
+        focus: t >= 1 ? NO_FOCUS : t <= 0 ? before : { ...before, fade: { kind: "dim", tokens, progress: t } },
+    });
+}
 
-    // ── Drawing ─────────────────────────────────────────────────────────────
-
-    /**
-     * Thin delegator: everything about *how* a frame is painted (settled or
-     * mid structural-edit, entry/exit motion, colour cross-fade) lives in
-     * `drawCode` (the engine's `render.ts`) as a pure function over plain
-     * state — this just gathers that state from the node's own instance
-     * fields and caches.
-     */
-    protected drawSelf(draw: RenderContext2D): void {
-        this.advanceCache.sync(this.advanceCache.signature(this.fontSize, this.fontFamily));
-        drawCode(draw, {
-            tokenLines: this.tokenLines,
-            metrics: this.metrics(),
-            advanceCache: this.advanceCache,
-            ...this.frameLayout(draw),
-            tokenStates: resolveTokenStates(this.tokenLines, this.transitions, this.highlightDimOpacity, this.highlightedIds),
-            highlightActive: this.highlightDimOpacity !== null || this.transitions.some(tr => tr.kind === "dim"),
-        });
+function rowsFrame(seen: CodeListing, from: RowBand[], to: RowBand[]): Frame | null {
+    if (from.length === 0 && to.length === 0) return null;
+    return (t) => ({
+        listing: seen,
+        banding: t >= 1 ? { bands: to, fade: null }
+            : t <= 0 ? { bands: from, fade: null }
+            : { bands: from, fade: { kind: "rows", from, to, progress: t } },
+    });
+}
+
+function lineLengths(lines: IdLine[]): number[] {
+    return lines.map((line) => line.tokens.reduce((acc, t) => acc + t.content.length, 0));
+}
+
+/** Character offset of a 1-indexed (line, col), clamped into the document. */
+function offsetAt(lines: IdLine[], position: [number, number]): number {
+    const lens = lineLengths(lines);
+    if (lens.length === 0) return 0;
+    const [rawLine, rawCol] = position;
+    const li = Math.max(0, Math.min(lens.length - 1, rawLine - 1));
+    let offset = 0;
+    for (let k = 0; k < li; k++) offset += lens[k] + 1;
+    return offset + Math.max(0, Math.min(lens[li], rawCol - 1));
+}
+
+/** The ids of every token any of `codeRanges` overlaps, partly or wholly. */
+function tokenIdsInRanges(lines: IdLine[], codeRanges: CodeRange[]): Set<number> {
+    const result = new Set<number>();
+    const lineLens = lineLengths(lines);
+    if (lineLens.length === 0) return result;
+    const offsets = codeRanges
+        .map((r) => rangeToCharOffsets(r, lineLens))
+        .filter(({ start, end }) => end > start);
+    if (offsets.length === 0) return result;
+
+    let off = 0;
+    for (let li = 0; li < lines.length; li++) {
+        for (const tok of lines[li].tokens) {
+            const tStart = off;
+            const tEnd = off + tok.content.length;
+            if (offsets.some(({ start, end }) => tEnd > start && tStart < end)) result.add(tok.id);
+            off = tEnd;
+        }
+        if (li < lines.length - 1) off += 1;
     }
+    return result;
+}
+
+/** One band per range, over every line it touches; a range past the end of the listing gives none. */
+function rowBandsIn(lines: IdLine[], codeRanges: CodeRange[], color: NormalizedColor, radius: number): RowBand[] {
+    const count = lines.length;
+    const bands: RowBand[] = [];
+    for (const range of codeRanges) {
+        const first = Math.max(1, Math.round(range.startLine ?? 1));
+        const last = Math.min(count, range.endLine == null || range.endLine === Infinity ? count : Math.round(range.endLine));
+        if (first > last) continue;
+        bands.push({ startId: lines[first - 1].id, endId: lines[last - 1].id, color, radius });
+    }
+    return bands;
 }
 
 /**
- * Normalize `highlight()`'s `codeRange` argument to a plain array: a single
- * `CodeRange` (a plain object, not iterable) becomes a one-element array; a
- * `CodeRangeChain`/plain array of ranges spreads as-is. `CodeRange` and
- * `CodeRangeChain` are distinguished by iterability, not `instanceof` — a
- * bare array of `CodeRange`s (no chain) works the same way.
+ * A single range (a plain object) as a one-element array; a chain or an array
+ * of ranges as itself; the `{ list }` a chain serialises as, as that chain.
  */
-function normalizeCodeRanges(codeRange: CodeRange | Iterable<CodeRange>): CodeRange[] {
+function normalizeCodeRanges(codeRange: CodeTarget | undefined): CodeRange[] {
     const maybeIterable = codeRange as Partial<Iterable<CodeRange>>;
     if (typeof maybeIterable[Symbol.iterator] === "function") {
         return [...(codeRange as Iterable<CodeRange>)];
     }
+    const stored = (codeRange as { list?: unknown }).list;
+    if (Array.isArray(stored)) return [...(stored as CodeRange[])];
     return [codeRange as CodeRange];
 }
 
@@ -832,3 +697,158 @@ function grammarLoader(language: string): () => Promise<void> {
     return load;
 }
 
+// ── Geometry and drawing ────────────────────────────────────────────────────
+
+interface Layouts {
+    readonly from: CodeLayout;
+    readonly to: CodeLayout;
+}
+
+/**
+ * A node's measurements, kept between frames: the advance of each token, and
+ * the layouts last built, reused while what they were built from is unchanged.
+ */
+interface Measured {
+    readonly advances: TokenAdvanceCache;
+    measurer: Measurer | null;
+    /** The measurer of the node's last measure, as the engine's helpers take one. */
+    scope: MeasureContext2D | null;
+    settled: { readonly lines: IdLine[]; readonly key: string; readonly layout: CodeLayout } | null;
+    edit: { readonly transition: StructuralTransition; readonly key: string; readonly from: CodeLayout; readonly to: CodeLayout } | null;
+}
+
+/** By the node's state view, one object per node that `measure` and `render` are both handed. */
+const measuredBy = new WeakMap<object, Measured>();
+
+function measuredOf(state: object): Measured {
+    let found = measuredBy.get(state);
+    if (!found) measuredBy.set(state, found = { advances: new TokenAdvanceCache(), measurer: null, scope: null, settled: null, edit: null });
+    return found;
+}
+
+function metricsOf(s: LayoutState): CodeMetrics {
+    return {
+        fontSize: s.fontSize,
+        fontFamily: s.fontFamily,
+        lineHeight: s.lineHeight,
+        letterSpacing: s.letterSpacing,
+        padding: s.padding,
+        showLineNumbers: s.showLineNumbers,
+        lineNumberGap: s.lineNumberGap,
+    };
+}
+
+/**
+ * The one or two layouts a frame is drawn from: a settled frame has one, a
+ * frame inside an edit two (where every token was, and where it is going).
+ * `null` for a node never measured, which has nothing to measure them with.
+ */
+function layoutsOf(measured: Measured, view: Shown, m: CodeMetrics): Layouts | null {
+    const signature = measured.advances.signature(m.fontSize, m.fontFamily);
+    measured.advances.sync(signature);
+    const key = `${metricsSignature(m)}|${signature}`;
+    const scope = measured.scope;
+    if (!view.transition) {
+        const hit = measured.settled;
+        if (hit && hit.lines === view.lines && hit.key === key) return { from: hit.layout, to: hit.layout };
+        if (!scope) return null;
+        const layout = layoutCode(view.lines, m, measured.advances, scope);
+        measured.settled = { lines: view.lines, key, layout };
+        return { from: layout, to: layout };
+    }
+    const hit = measured.edit;
+    if (hit && hit.transition === view.transition && hit.key === key) return hit;
+    if (!scope) return null;
+    const both = {
+        transition: view.transition,
+        key,
+        from: layoutCode(view.transition.from, m, measured.advances, scope),
+        to: layoutCode(view.transition.to, m, measured.advances, scope),
+    };
+    measured.edit = both;
+    return both;
+}
+
+function measureListing(measurer: Measurer, s: LayoutState, kit: Kit): Size2D {
+    const measured = measuredOf(s);
+    if (measured.measurer !== measurer) {
+        measured.measurer = measurer;
+        measured.scope = {
+            measureText: (text, fontSize, fontFamily, fontWeight, letterSpacing) =>
+                measurer.text(text, { fontFamily, fontSize, fontWeight, letterSpacing }),
+        };
+    }
+    const view = shown(s, kit);
+    const m = metricsOf(s);
+    const layouts = layoutsOf(measured, view, m);
+    if (!layouts) return { width: 0, height: 0 };
+    const t = moveProgress(view.transition ? { phases: view.transition.phases, progress: view.progress } : null);
+    const innerW = view.transition ? lerpNumber(layouts.from.innerW, layouts.to.innerW, t) : layouts.to.innerW;
+    const innerH = view.transition ? lerpNumber(layouts.from.innerH, layouts.to.innerH, t) : layouts.to.innerH;
+    return { width: innerW + m.padding.left + m.padding.right, height: innerH + m.padding.top + m.padding.bottom };
+}
+
+const NO_PAINT: Paint.PaintState = { fill: [], stroke: [], shadow: [], overlay: [], start: 0, end: 1, clip: false };
+const NOTHING = (): void => { };
+
+function drawListing(ctx: RenderContext, s: DrawState, kit: Kit): void {
+    const measured = measuredOf(s);
+    const view = shown(s, kit);
+    const m = metricsOf(s);
+    const layouts = layoutsOf(measured, view, m);
+    // Paints nothing: it declares the outline picking and backdrop effects read.
+    Paint.draw(ctx, NO_PAINT, null, { clipShape: outlineOf(view, layouts, m, ctx.size), children: NOTHING });
+    const scope = measured.scope;
+    if (!layouts || !scope) return;
+    const { focus, banding } = s;
+    drawCode({ draw: (graphics) => ctx.draw(graphics), measureText: scope.measureText }, {
+        tokenLines: view.lines,
+        metrics: m,
+        advanceCache: measured.advances,
+        from: layouts.from,
+        to: layouts.to,
+        edit: editOf(view),
+        tokenStates: resolveTokenStates(view.lines, focus.fade ? [focus.fade] : [], focus.dim, focus.ids),
+        highlightActive: focus.dim !== null || focus.fade !== null,
+        rowBands: banding.bands,
+        rowsEdit: banding.fade,
+        boxW: ctx.size.width,
+    });
+}
+
+/**
+ * A listing is grabbed by its text, line by ragged line: each line a slot as
+ * wide as its ink, plus the gutter where numbers show, inside the box. Code is
+ * mostly whitespace, and its empty corners would swallow clicks meant for what
+ * is behind it. Mid-edit, or before it is laid out, the box.
+ */
+function outlineOf(view: Shown, layouts: Layouts | null, m: CodeMetrics, size: Size2D): Graphics2D {
+    const box = { x: 0, y: 0, width: size.width, height: size.height };
+    if (view.transition || !layouts) return new Graphics2D().rect(box);
+    const layout = layouts.to;
+    const half = (m.fontSize * m.lineHeight) / 2;
+    const gutter = m.showLineNumbers ? layout.gutter : 0;
+    const left = Math.max(layout.startX - gutter, -size.width / 2);
+    const outline = new Graphics2D();
+    let lines = 0;
+    for (let i = 0; i < layout.lineY.length; i++) {
+        const ink = layout.lineW[i] ?? 0;
+        if (ink + gutter <= 0) continue;
+        const right = Math.min(layout.startX + ink, size.width / 2);
+        const y = layout.lineY[i];
+        const top = Math.min(y + half, size.height / 2);
+        const bottom = Math.max(y - half, -size.height / 2);
+        if (right < left || top < bottom) continue;
+        // The row's own centre where the box leaves it whole, so a whole row is tested at its own centre.
+        const whole = top === y + half && bottom === y - half;
+        outline.rect({
+            x: (left + right) / 2,
+            y: whole ? y : (top + bottom) / 2,
+            width: right - left,
+            height: whole ? 2 * half : top - bottom,
+        });
+        lines++;
+    }
+    // No line has ink: the box with itself cut away, so nothing is grabbed (an empty outline would fall back to the box).
+    return lines > 0 ? outline : new Graphics2D().rect(box).rect(box).cut();
+}