@vectojs/markdown 0.5.0 → 0.7.0

package/README.md

@@ -22,9 +22,9 @@ bun add @vectojs/markdown @vectojs/ui @vectojs/core
 ## Usage
 
 ```ts
-import { Markdown } from '@vectojs/markdown';
+import { Markdown } from "@vectojs/markdown";
 
-const md = new Markdown('# Hello\n\nInline math $E = mc^2$.');
+const md = new Markdown("# Hello\n\nInline math $E = mc^2$.");
 scene.add(md);
 ```
 
@@ -35,14 +35,16 @@ parse/layout commit per animation frame. `write()` applies backpressure when its
 bounded buffer is full; await it when consuming an async token source.
 
 ```ts
-const md = new Markdown('');
+const md = new Markdown("");
 scene.add(md);
 
 const stream = md.createStream();
 for await (const token of tokens) {
   await stream.write(token);
 }
-await stream.close(); // final text is committed immediately
+// Commits the final text, then waits for the parse to be applied — once this
+// resolves, the rendered document reflects everything written.
+await stream.close();
 ```
 
 Add fixed-rate typewriter pacing without changing producer code:
@@ -61,6 +63,119 @@ flags, and surrogate pairs stay intact across ordinary chunk/frame boundaries.
 automatically. The existing `appendMarkdown()` API remains synchronous and
 flushes submitted controller text before a direct append.
 
+### Incomplete Markdown while streaming
+
+Mid-stream, the trailing text of a paragraph is often an unclosed inline
+construct — `**bo`, `` `cod ``, `[text](url`. `marked` has no signal that more
+characters are coming, so it lexes those as plain text. `incompleteMode` chooses
+what you show in the meantime:
+
+```ts
+const stream = md.createStream({ incompleteMode: "optimistic" });
+```
+
+| Mode                  | Unclosed `**bo` renders as           |
+| --------------------- | ------------------------------------ |
+| `'literal'` (default) | `**bo` — the literal characters      |
+| `'optimistic'`        | **bo** — guessed bold, syntax hidden |
+
+`'optimistic'` covers strong, emphasis, and inline code. An unclosed link shows
+its label as plain text: with no closing `)` there is no URL yet, so nothing is
+made clickable. Only the document's **last paragraph** is ever guessed at, and
+only while the stream is open — headings, list items, table cells, and any
+earlier paragraph are always literal.
+
+The guess is display-only. `Markdown.tokens` is never affected, and `close()`
+unwinds it, so a `'literal'` and an `'optimistic'` stream of the same source end
+at an identical document. `'literal'` remains the default: it is what every prior
+release rendered.
+
+### Knowing when the document is final
+
+`onStable` fires once, after `close()` has committed the last chunk _and_ the
+parse has been applied. Use it for one-time work you do not want repeated against
+content still in flight:
+
+```ts
+const stream = md.createStream({
+  onStable: (blocks) => {
+    for (const block of blocks) fadeIn(block);
+  },
+});
+```
+
+It never fires on `flush()`, `abort()`, or `destroy()` — none of those mean the
+content stopped changing. It receives a snapshot array, not a live reference.
+Calling `appendMarkdown()` or `setContent()` from inside the callback throws; a
+throw from the callback rejects the `close()` promise. `onStable` is independent
+of `incompleteMode` and works with the `'literal'` default.
+
+### Streamed TeX math
+
+A fenced math block is typeset only once its closing fence arrives:
+
+````md
+```math
+\int_0^1 x\,dx = \frac{1}{2}
+```
+````
+
+While the fence is still open the block renders as an ordinary code block showing
+the TeX source, then becomes the formula on the chunk that closes it. This is
+deliberate. `marked` lexes an unterminated fence as a _complete_ token as soon as
+it reads the info string, so a formula streamed a few characters at a time
+arrives as a long run of whole tokens, nearly all of them invalid TeX — typesetting
+each one spends the most expensive call in this package rendering an error glyph
+that is replaced by the next chunk. Showing the source is both cheaper and more
+honest: the formula genuinely is not finished.
+
+Converted formulas are cached (bounded, process-wide), so a repeated formula is
+converted once no matter how many documents or instances render it.
+
+Inline `$...$` math is a separate path: it is currently shown as styled source
+text, not typeset.
+
+#### MathJax is loaded on demand
+
+MathJax is imported dynamically, the first time a document actually has a formula
+to typeset. It is by far the heaviest thing this package can pull in — measured
+against a browser bundle of a consumer that renders only prose:
+
+| prose-only consumer       |       raw |    gzip |
+| ------------------------- | --------: | ------: |
+| eagerly imported (before) | 2,157,295 | 725,012 |
+| lazily imported (now)     |   339,767 | 106,095 |
+
+That is 85% of the bundle a document with no formulas used to carry, plus roughly
+150 ms of module evaluation at startup. Your bundler needs code splitting enabled
+to see this; without it the bytes are still in the output, just not evaluated
+until first use.
+
+The tradeoff is that **the first formula on a page cannot be typeset
+synchronously.** It renders as a code block of TeX source — the same state an
+unclosed fence already shows — and is replaced once the module resolves. Every
+formula after that is synchronous again.
+
+While streaming this is invisible: the load starts as soon as an _opening_ math
+fence appears, several chunks before the closing one, so the formula is typeset on
+the chunk that closes it. `await stream.close()` and `onStable` also wait for a
+pending load, so a "final" document never hands you an untypeset formula.
+
+If you need the very first formula typeset in the same tick — measuring layout
+immediately after construction, for instance — preload it:
+
+````ts
+import { Markdown, preloadMathJax } from "@vectojs/markdown";
+
+await preloadMathJax();
+const md = new Markdown("```math\n\\int_0^1 x\\,dx\n```"); // typeset synchronously
+````
+
+`preloadMathJax()` is idempotent and shared across every document, so calling it
+from several places starts one load. `isMathJaxReady()` reports whether formulas
+currently typeset without waiting. If the load fails, formulas keep rendering as
+TeX source rather than throwing.
+
 > Migrating from `@vectojs/ui` ≤ 1.x? `Markdown` and `CodeBlock` used to be
 > exported from `@vectojs/ui`. As of `@vectojs/ui@2.0.0` they live here — change
 > `import { Markdown } from '@vectojs/ui'` to `from '@vectojs/markdown'`.

package/dist/Markdown.d.ts

@@ -2,6 +2,9 @@ import { Entity, type DevtoolsDescriptor, GlyphRasterAtlas, type GlyphRasterAtla
 import { type Token } from 'marked';
 import { type StreamController, type StreamControllerOptions } from './StreamController';
 import { Stack, UIComponent } from '@vectojs/ui';
+export declare function preloadMathJax(): Promise<void>;
+/** Whether formulas can be typeset without waiting. Exposed for tests. */
+export declare function isMathJaxReady(): boolean;
 /** Color and typography theme for Markdown rendering. */
 export interface MarkdownTheme {
     /** Body text color. */
@@ -134,6 +137,51 @@ export declare class Markdown extends UIComponent {
     onLayoutUpdated?: () => void;
     private rawMarkdown;
     private streamController;
+    /**
+     * Trailing-unclosed-syntax policy of the active stream, or `'literal'` when no
+     * stream is open.
+     *
+     * Held here rather than read back off the controller because it is a rendering
+     * concern: `StreamController` owns buffering and pacing and has no view of the
+     * entity tree, while the guess is a transform applied where spans are built.
+     */
+    private streamIncompleteMode;
+    /** End-of-stream callback of the active stream, if it supplied one. */
+    private streamOnStable;
+    /**
+     * The trailing paragraph entity currently showing an optimistic guess, plus the
+     * token it was rendered from.
+     *
+     * Both halves are needed. The entity is what must be re-rendered to drop the
+     * guess; the token is what it must be re-rendered FROM, and it is the only
+     * copy — `this.tokens` has already moved on by the time an unwind is decided.
+     * `null` means no guess is live, which is the state every `'literal'` stream
+     * and every closed stream stays in.
+     */
+    private optimisticTail;
+    /** Resolvers waiting for every in-flight worker append to have been applied. */
+    private appendSettledWaiters;
+    /** True only inside an `onStable` callback, to reject reentrant mutation. */
+    private inStableCallback;
+    /** Set by {@link destroy} so late settlement work skips a torn-down tree. */
+    private isDestroyed;
+    /**
+     * This instance's entry in {@link inlineMathRasterWaiters}, or `undefined` if it
+     * has never rendered inline math.
+     *
+     * Subscribed lazily so a document without formulas costs nothing, and held as a
+     * field only so {@link destroy} can remove the exact closure it added.
+     */
+    private inlineMathRepaint?;
+    /**
+     * True while this document is waiting on the lazy MathJax load.
+     *
+     * Tracked per instance rather than read off the module state because it also
+     * gates settlement: `await close()` and `onStable` must not resolve while a
+     * formula is still showing TeX source, or a caller doing expensive one-time
+     * work on a "final" document would measure and export placeholder boxes.
+     */
+    private mathLoadPending;
     private _userTiming;
     private tokens;
     private appendInFlight;
@@ -195,6 +243,13 @@ export declare class Markdown extends UIComponent {
      * the whole subtree alive until the worker replied), then recurse into the
      * content subtree via `super.destroy()` so every block's resources are freed.
      */
+    /**
+     * Repaint this document when an inline formula's raster finishes decoding.
+     *
+     * Idempotent — called on every render of a math-bearing token, and the set holds
+     * one closure per instance.
+     */
+    private subscribeInlineMathRepaint;
     destroy(): void;
     /**
      * Streaming and parse state — the markdown streaming inspector.
@@ -232,6 +287,301 @@ export declare class Markdown extends UIComponent {
      * whenever the worker reports it cannot trust what it holds (`needResync`).
      */
     private dispatchAppend;
+    /**
+     * Spans for one paragraph token exactly as `marked` produced it.
+     *
+     * The literal baseline: what every release renders, and what an optimistic
+     * guess is unwound back to.
+     */
+    private literalParagraphSpans;
+    /**
+     * Update a reused blockquote's tail child in place, or report that it cannot be.
+     *
+     * The render arm builds `container[border, innerStack]` where every inner block
+     * sits in its own single-child `wrapper`, so the tail entity is
+     * `innerStack.children.at(-1).children[0]`. Only the LAST inner block may be
+     * updated: the inner token list is prefix-stable exactly like the top level (a
+     * growing quote keeps its earlier blocks byte-identical), so anything before the
+     * tail is untouched and anything more complicated than a changed tail falls back
+     * to the caller's rebuild.
+     *
+     * Returns `false` without mutating anything when the shape is not the simple
+     * grow-the-tail case, which is the signal for the caller to rebuild. Every early
+     * return has to leave the entity untouched, or a rejected reuse would leave a
+     * half-updated quote on screen.
+     */
+    /**
+     * Build one list item's spans: inline content plus its marker.
+     *
+     * Shared by the `list` render arm and the streamed-reuse path below, because
+     * the two must produce byte-identical spans — a reused list that disagreed with
+     * a rebuilt one about its marker or its entity decoding would make a streamed
+     * document differ from the same source pasted at once.
+     */
+    /**
+     * Inline spans for one table cell.
+     *
+     * Always returns at least one span. A cell whose markup collapses to nothing —
+     * an empty cell, but also a bare `<span>`, an image, or an HTML comment, none
+     * of which `collectSpans` emits for — falls back to its decoded source text,
+     * which is what the previous string-returning path rendered. That guarantee is
+     * what lets every cell be a `RichText`: an empty cell would otherwise become a
+     * `Text`, and since `Text` has `setText` while `RichText` has `setSpans` and
+     * nothing converts between them, a cell that starts empty and later gains
+     * content could not be updated in place. A streamed table needs exactly that,
+     * because `marked` materializes a partial row as a full row of empty cells and
+     * then fills them one at a time.
+     */
+    private tableCellSpans;
+    /**
+     * Spans for one run of consecutive non-image inline tokens.
+     *
+     * A paragraph holding an image renders as a `Stack` of alternating text runs
+     * and images, and this is one text run. Shared by the render arm and
+     * {@link updateImageParagraph} so a reused run cannot drift from a rebuilt one.
+     *
+     * The empty fallback mirrors `renderInlineToRichText('', …)`, which the render
+     * arm passed for these runs: a run is only created when it has at least one
+     * token, so the fallback is for tokens that emit no spans at all rather than
+     * for an empty run.
+     */
+    private inlineRunSpans;
+    /** One text run of an image-bearing paragraph, as both paths build it. */
+    private inlineRunRichText;
+    /**
+     * One image inside a paragraph, sized by a guess until its bitmap decodes.
+     *
+     * Width and height start at a 16:10 guess because the intrinsic size is not
+     * known until the browser has the bitmap; `onLoad` corrects both from
+     * `naturalWidth`/`naturalHeight`. Extracted from the render arm so the streamed
+     * path reuses this exact entity rather than constructing a second variant.
+     *
+     * `markDirty()` is unconditional, matching the display-math sibling. It used
+     * to sit inside the `naturalWidth && naturalHeight` check, which meant a
+     * source that loads successfully while reporting a zero dimension left the
+     * scene un-notified. `Image` sets `loaded` before invoking this callback, so
+     * its `render()` starts drawing the bitmap either way — the cost was not a
+     * stale placeholder but a box frozen at the guess: measured on Chromium and
+     * Firefox, an `<svg width="0" height="0">` paragraph image kept 800x480 of
+     * reserved layout forever while a normal raster corrected to 80x60. An
+     * `onDemand` scene repaints only when marked, so nothing reclaimed it.
+     *
+     * The box is deliberately left at the guess when the bitmap reports zero.
+     * Collapsing it to 0x0 would make the paragraph reflow correctly but would
+     * also silently delete a reserved region on the strength of one browser
+     * quirk, and `Image.render()` still blits whatever the bitmap holds. Sizing
+     * policy for a zero-dimension source is a separate decision from notifying
+     * the scene, which is the actual defect here.
+     */
+    private paragraphImage;
+    /** One table cell entity, shared by the render arm and the streamed-table path. */
+    private tableCellRichText;
+    private listItemSpans;
+    /** Construct the `RichText` for one list item. */
+    private listItemRichText;
+    /**
+     * Reuse a streamed list's `Stack` instead of rebuilding every item.
+     *
+     * Returns `false` to mean "rebuild instead", exactly like
+     * {@link updateBlockquoteTail}, and every rejection path leaves the entity
+     * untouched so a refused reuse cannot leave a half-updated list on screen.
+     *
+     * This is the shape a stream actually produces: items are APPENDED, and only
+     * the last one grows. That matters for the ordinal marker, which is
+     * position-derived (`start + index`) — under append an already-rendered item's
+     * index never changes, so its marker stays correct. A mid-list insertion would
+     * shift every later ordinal, but no stream produces one.
+     *
+     * Two traps this guards, both found by probing marked 18.0.7 rather than by
+     * reading:
+     *
+     * - **A retained item's `raw` is NOT stable.** `items[1].raw` goes `"- two"` ->
+     *   `"- two\\n"` when item 3 arrives, so a byte-equality guard on `raw` fails on
+     *   every chunk and the fast path would never fire. `text` is stable; compare
+     *   that.
+     * - **A tight list can become loose.** Adding a blank line flips
+     *   `token.loose`, which re-lexes every item's children from `text` to
+     *   `paragraph`. Item 0's own `text` is unchanged, so a naive guard would reuse
+     *   and keep stale spans. Bail when `loose` flips.
+     */
+    private updateStreamedList;
+    /**
+     * Reuse a streamed image-bearing paragraph's `Stack` instead of rebuilding it.
+     *
+     * Returns `false` to mean "rebuild instead", and every rejection happens before
+     * any mutation, so a refused reuse leaves the entity exactly as it was.
+     *
+     * This was the last silent fallthrough in the in-place reuse path. A paragraph
+     * holding an image renders as a `Stack` of alternating text runs and images
+     * rather than one `RichText`, so it has no `setSpans` and failed the ordinary
+     * paragraph gate — with no `else`, which is what made the miss invisible:
+     * `inPlaceUpdates` stayed flat while `entitiesRebuilt` climbed. Measured on a
+     * six-chunk stream, `inPlaceUpdates` 0 / `entitiesRebuilt` 4 with an image
+     * against 4 / 0 for the identical shape without one. Every rebuild also
+     * re-created the `Image`, discarding its decoded bitmap and its corrected
+     * intrinsic size.
+     *
+     * It is *only* a performance path. The obvious worry — that a fresh `Image`
+     * starts at `loaded = false` and so repaints its placeholder slab — was
+     * measured and does not happen: sampling the real canvas pixel at the image
+     * centre in both Chromium and Firefox gives zero placeholder frames after the
+     * first paint, at 60ms and at 0ms between chunks, because a cached bitmap
+     * decodes before the next frame.
+     *
+     * The reuse is deliberately narrow: **only a growing trailing text run**. Probed
+     * against `marked@18.0.7`, that is the shape a stream actually produces once an
+     * image has closed — the image token's `raw` and its index are then stable while
+     * trailing prose grows, and the token list settles at
+     * `[…, image, text]` and stops changing length. Anything else (a new image
+     * arriving, an image token changing, a run appearing before the last image)
+     * falls through to the rebuild, which is correct and rare.
+     *
+     * Note the child list is not one entity per token: consecutive non-image tokens
+     * are merged into one `RichText` by the render arm's `flushText`, so
+     * `[text, text, image]` is two children, not three. The guards therefore compare
+     * *token runs* split at the last image, never token index against child index.
+     */
+    private updateImageParagraph;
+    /**
+     * Reuse a streamed table's `Table` entity instead of rebuilding every cell.
+     *
+     * Returns `false` to mean "rebuild instead", and every rejection happens before
+     * any mutation, so a refused reuse leaves the entity exactly as it was.
+     *
+     * A `table` token carries every row, so the rebuild path costs Θ(C·N²)
+     * `RichText` constructions across a stream — and a further 2×, because
+     * `Table.layout()` re-runs `fitCell` on every cell. This was the last block
+     * type without an in-place path.
+     *
+     * Two shapes have to be handled, because of how `marked` lexes a growing table
+     * (probed against 18.0.7): a partial row is materialized immediately as a FULL
+     * row padded with empty cells, and its cells are then filled one at a time. A
+     * 2×2 table passes through eleven distinct row states, of which only two are
+     * clean row appends. So handling appends alone would reject most chunks and
+     * leave the quadratic cost essentially in place:
+     *
+     * 1. the last row's cells are rewritten in place via `setSpans`, and
+     * 2. genuinely new rows go through `Table.appendRows`.
+     *
+     * Cells are compared by `text`, never `raw` — a table cell has no `raw` at all
+     * (its keys are `text`/`tokens`/`header`/`align`).
+     */
+    private updateStreamedTable;
+    private updateBlockquoteTail;
+    /**
+     * Spans for a heading being updated in place.
+     *
+     * Kept in lockstep with the `heading` arm of {@link renderToken}, which builds
+     * its `RichText` through `renderInlineToRichText`: same `collectSpans` call and
+     * the same `decodeEntities` fallback when a heading has no inline tokens (`##`
+     * with no text yet, which a stream produces before its first word arrives). A
+     * plain `token.text` fallback here would leave an entity-bearing heading
+     * undecoded on the in-place path but decoded on a fresh render.
+     */
+    private headingSpans;
+    /**
+     * Spans for the trailing paragraph with its last unclosed inline construct
+     * rendered as though it had closed, or `null` when there is nothing to guess.
+     *
+     * `null` is the answer for every `'literal'` stream, every closed or absent
+     * stream, and any trailing paragraph whose syntax is all balanced — so the
+     * caller falls back to {@link literalParagraphSpans} and pays nothing.
+     *
+     * Only the paragraph's LAST inline token is scanned. An unclosed construct can
+     * only be there: anything that closed is already its own `strong`/`em`/
+     * `codespan`/`link` token, so a syntax character surviving into a trailing
+     * plain-text run is one `marked` could not pair. Scanning the whole raw string
+     * instead would re-find the markers of already-closed constructs.
+     */
+    private optimisticParagraphSpans;
+    /** Display style for a guessed-closed construct. */
+    private optimisticStyle;
+    /**
+     * Re-render the paragraph currently showing a guess from its own tokens, with
+     * no overlay, and forget it.
+     *
+     * Idempotent and free when no guess is live, which is what lets `close()`,
+     * `abort()`, and a mid-stream staleness check all call it unconditionally.
+     */
+    /**
+     * Start the MathJax load, and re-typeset this document once it resolves.
+     *
+     * Called from two places, for two different reasons:
+     *
+     * - When an OPEN math fence is rendered. This is a prefetch, and it is what
+     *   makes the lazy load invisible while streaming: the module starts loading
+     *   the moment a formula begins arriving, several chunks before its closing
+     *   fence, so by the time the fence closes the converter is usually already
+     *   installed and the formula typesets synchronously on the normal path.
+     * - When a CLOSED fence could not be typeset because the module is not ready.
+     *   That is the case a rebuild actually exists for: a document constructed with
+     *   math already complete, or a stream that closed a fence faster than the
+     *   module loaded.
+     *
+     * Idempotent per instance. Concurrent callers coalesce onto the one cached
+     * module promise, and `mathLoadPending` keeps a second rebuild from being
+     * queued while the first is outstanding.
+     */
+    private ensureMathJax;
+    /**
+     * Rebuild every block from the tokens already lexed, without re-lexing.
+     *
+     * Used only when MathJax arrives after a formula has already been rendered as
+     * source. Rebuilding wholesale rather than surgically replacing the math blocks
+     * is the deliberate choice: `tokenChildPrefix` maps token indices to child
+     * slots positionally, so swapping one child in place would have to keep that
+     * mapping, the `Stack`'s cached box, and every following sibling's position in
+     * agreement by hand. Re-rendering the same token list in the same order leaves
+     * the mapping trivially correct, and this runs at most once per document — the
+     * same cost as the `setContent` rebuild that already exists.
+     *
+     * The optimistic tail is dropped first. Its `entity` is about to be destroyed,
+     * so the pointer would dangle; unwinding restores literal spans, and if the
+     * stream is still open the next chunk re-applies a guess.
+     */
+    private retypesetFromTokens;
+    private unwindOptimisticTail;
+    /**
+     * Drop a guess that is no longer on the document's trailing paragraph.
+     *
+     * A coalesced append can add a block after the paragraph that owns the guess,
+     * at which point the guess is frozen — the construct can never close, because
+     * no further text lands in that paragraph. Without this the stale styling would
+     * survive until `close()`.
+     *
+     * `writtenThisPass` is the entity whose spans this reconcile already rewrote,
+     * if any: for that one, literal spans are on screen already and re-rendering it
+     * would be wasted layout, so only the bookkeeping is cleared.
+     */
+    private dropStaleOptimisticTail;
+    /**
+     * Resolve once every in-flight worker append has actually been applied.
+     *
+     * Committing text is not the same as the document reflecting it: `append()`
+     * reaches `dispatchAppend()`, which `postMessage()`s and returns, and the reply
+     * that runs `updateTokens()` lands later. Without waiting here, `close()` could
+     * resolve — and `onStable` fire — against a document missing its last chunk.
+     *
+     * An outstanding lazy MathJax load counts as unsettled for the same reason. A
+     * document whose formulas are still TeX source is not final in any sense a
+     * caller of `onStable` cares about: the boxes are the wrong size, so measuring
+     * or exporting there would capture placeholders.
+     */
+    private waitForAppendSettled;
+    /**
+     * Release settlement waiters, but only once nothing is outstanding.
+     *
+     * Called at the very END of the worker callback, after its coalesced-re-dispatch
+     * check, rather than wherever `appendInFlight` goes false. Within that callback
+     * `appendInFlight` is cleared and then, if another chunk arrived while the
+     * request was in flight, set straight back to `true` by the re-dispatch — both
+     * synchronously, before anything watching the flag could observe the gap. Only
+     * checking here, after that, waits through the re-dispatch instead of resolving
+     * one chunk early.
+     */
+    private flushAppendSettledWaiters;
+    /** Throw if a public mutation is attempted from inside an `onStable` callback. */
+    private assertNotInStableCallback;
     private updateTokens;
     /**
      * Render one nested block with a temporary width/margin context while
@@ -250,6 +600,19 @@ export declare class Markdown extends UIComponent {
      * `renderToken`'s null returns.
      */
     protected producesEntity(token: Token): boolean;
+    /**
+     * Build a centered display-math block, or `null` if MathJax cannot typeset yet.
+     *
+     * Shared by the `$$..$$` block token and a closed ```` ```math ```` fence:
+     * both are display math and must render identically, differing only in how
+     * they were spelled in the source.
+     *
+     * `ex` is font-relative, so the intrinsic box is resolved against the theme's
+     * body size. This is what a previously hardcoded `* 8` got wrong -- exact only
+     * near fontSize 18.1px, so a formula was ~13% oversized at the 16px default
+     * and far worse at other sizes.
+     */
+    private renderDisplayMath;
     protected renderToken(token: Token): Entity | null;
     /** Structural — children draw themselves. */
     render(_r: IRenderer): void;