@grafloria/element 0.3.17 → 0.3.19

package/src/libs/renderer/src/svg/svg-renderer.d.ts

@@ -0,0 +1,1737 @@
+import type { DiagramEngine, LODLevel } from '@grafloria/engine';
+import { type GovernorState } from '../perf/quality-governor';
+import { type RouteSolverStats } from './route-solver-bridge';
+import type { IRenderer, PerformanceMetrics, SVGRendererConfig, VNode, Theme, Rectangle, RendererCapabilities, ExportFormat, ExportOptions } from '../types';
+import { type SvgExportResult } from '../export/svg-export';
+import { type PdfExportResult } from '../export/pdf/pdf-export';
+import { type Page, type PaginationOptions } from '../export/pagination';
+/** One paginated tile: its grid position, its world window, and the SVG for it. */
+export interface PagedSvgResult {
+    pages: Array<Page & {
+        svg: string;
+    }>;
+    columns: number;
+    rows: number;
+    warnings: string[];
+}
+import { type ColorMode, type ThemeSet, type TokenBridge } from '../themes';
+import type { ViewLifecycle } from '../lazy/view-lifecycle';
+import type { CommentSource } from '../comments/comment-overlay';
+import type { EntityKind as LazyEntityKind } from '../lazy/types';
+import { DiagramRegistry } from '../ext/diagram-registry';
+import { AnimationService } from '../services/animation.service';
+/**
+ * Id of the SHARED stylesheet: the theme-independent, `var(--grafloria-*)`-based
+ * rules. Identical for every renderer on the page, so it is injected once and
+ * deduped by this id — instances only own their tiny variable block.
+ */
+export declare const GRAFLORIA_BASE_STYLE_ID = "grafloria-renderer-styles";
+/** Prefix of a renderer's own `<style>` element id (one per instance). */
+export declare const GRAFLORIA_INSTANCE_STYLE_PREFIX = "grafloria-renderer-theme-";
+/**
+ * Prefix of a renderer's OVERRIDE `<style>` element — the design-token bridge and
+ * the accessibility media queries (Wave 4, Card "token bridge + a11y theming").
+ *
+ * A SEPARATE element from the theme block, and always inserted after it, because
+ * the cascade inside the variables is the whole mechanism:
+ *   theme values  <  host design tokens  <  prefers-contrast  <  forced-colors
+ * Same selector, same specificity — so only SOURCE ORDER decides, and source
+ * order is only guaranteed if we own it.
+ */
+export declare const GRAFLORIA_INSTANCE_OVERRIDE_PREFIX = "grafloria-renderer-overrides-";
+export declare function fitFontSize(text: string, maxWidth: number, base: number): number;
+export declare class SVGRenderer implements IRenderer {
+    private engine;
+    readonly mode: "svg";
+    /**
+     * What this renderer can actually do — so callers can ask instead of assuming.
+     * `supportsExport` is now TRUE (see `export()` below); hit-testing and text
+     * measurement still are not implemented here, and saying so is the point.
+     */
+    readonly capabilities: RendererCapabilities;
+    /**
+     * This renderer's scope. Stamped on the root `<svg>` as
+     * `data-grafloria-instance` and used to scope BOTH the injected variable block
+     * and this instance's `<style>` element id — so two diagrams with different
+     * themes on one page no longer clobber each other's stylesheet.
+     */
+    private readonly instanceId;
+    /** Unsubscribe from the named-style registry (see the constructor). */
+    private unsubscribeStyleRegistry?;
+    /**
+     * World-space margin added around the viewport when querying the engine's link
+     * SpatialIndex (see expandForLinkCulling). Covers routed detours that have not
+     * been written back into `link.points` yet — an orthogonal detour around a node
+     * stays well inside this, and the cost of an over-wide query is only a few
+     * extra VNodes.
+     */
+    private static readonly LINK_CULL_MARGIN;
+    private theme;
+    private config;
+    private vnodeCache;
+    private styleElement?;
+    private disposed;
+    /** Watches the OS media queries. Only created when `colorMode` is configured. */
+    private colorModeController?;
+    /** The host design system's tokens, mapped onto ours. */
+    private tokenBridge?;
+    /** `<style>` holding the bridge + the a11y media queries (after the theme block). */
+    private overrideElement?;
+    /**
+     * Entities whose LAST rendered VNode froze a theme value into itself, and which
+     * therefore cannot be re-themed by rewriting a CSS variable.
+     *
+     * This is the ledger that makes the hot-swap honest. In CSS mode most of the
+     * theme is painted by the stylesheet through `var(--grafloria-*)`, so rebinding the
+     * variables re-themes those elements with no VNode work at all. But three
+     * things are still resolved to LITERALS in the emitted VNode:
+     *
+     *   - the STATE layer (a selected node carries the theme's selection colours),
+     *   - `theme.nodes[type]` / `theme.links[type]` type-defaults,
+     *   - a `themeRef` on a property that is emitted as an SVG PRESENTATION
+     *     ATTRIBUTE (arrowheads, `rx`, node `opacity`) — attributes cannot hold
+     *     `var()`, so those must be baked.
+     *
+     * Rather than guess, the style computation RECORDS which entities that happened
+     * to. A theme swap then dirties exactly those and nothing else: a diagram with
+     * nothing selected and no bound attributes re-themes with zero restyled VNodes,
+     * and the ones that do need it are found, not assumed.
+     */
+    private themeBoundNodes;
+    private themeBoundLinks;
+    private containerIds;
+    private foreignObjectNodes;
+    private arrowRenderer;
+    private labelRenderer;
+    private jumpPointDetector;
+    private jumpPointRenderer;
+    private waypointEditor;
+    private controlPointEditor;
+    private animationService;
+    private a11yFocus;
+    /**
+     * wave9/comments (card 6): where the comment pins come from, or null for a canvas with
+     * no comment system attached — in which case NO layer is built and NO query is made, so
+     * an idle 10k-node frame is exactly as cheap as it was before this card existed.
+     */
+    private commentSource;
+    /** The root VNode of the last frame we actually built (null ⇒ nothing to reuse). */
+    private lastFrameRoot;
+    /** View + interaction signature of that frame (null ⇒ that frame was not cacheable). */
+    private lastFrameSig;
+    /** Mutation epoch AFTER that frame was built (render() itself dirties links). */
+    private lastFrameEpoch;
+    /** Set by anything whose effect on the picture the epoch cannot see. */
+    private frameInvalidated;
+    /** Monotone count of invalidateFrame() calls — a HOST's idle-skip keys on this. */
+    private invalidationEpoch;
+    /**
+     * Did the frame being built move any link's FINAL geometry? If so it has not
+     * reached a fixed point and must not arm the gate.
+     *
+     * `render()` is not quite a pure function, and this is the one place it shows.
+     * The link cull query (`getVisibleLinks`) runs BEFORE the routing pre-pass, so
+     * a frame that re-routes a link writes its new geometry into the spatial index
+     * only AFTER that frame has already decided what to draw. The next frame
+     * therefore culls against a different index and can legitimately produce a
+     * different picture from identical model + view — which is precisely the
+     * two-frame settle the culling suite documents ("the link's cull box is the
+     * union of its LIVE endpoints and its last routed points, so for ONE frame it
+     * still spans the old route").
+     *
+     * Skipping that second frame leaves a link that should have been culled in the
+     * tree forever. So the gate closes only on a frame that changed nothing — a
+     * genuine fixed point — and geometry settles in the same two frames it always
+     * did.
+     *
+     * Set ONLY by markLinksWhoseFrameChanged, which is the only pass that sees a
+     * link's final geometry (three separate writers rewrite it during a frame; an
+     * intermediate difference is not a change). See the note there.
+     */
+    private frameChangedGeometry;
+    /** Frames served straight from `lastFrameRoot`. A quiet canvas should be all of them. */
+    private framesSkipped;
+    /** Frames actually built. */
+    private framesBuilt;
+    private frameRoutes;
+    /** The gate between "culling says it is on screen" and "build its view". */
+    private viewLifecycle;
+    /** What the gate held back on the last frame — the progressive mounter's work queue. */
+    private deferredThisFrame;
+    private frameObstacleCache;
+    private routeMemo;
+    /** Set true to force the next frame to re-route everything (first frame, config changes). */
+    private routeMemoDirty;
+    /**
+     * resize-ux: the tool-layer geometry for the PAINTED resize handles. Same
+     * class and same resize-only configuration as the DomEventBinder's controller
+     * (halo/rotate/remove/link tools off — those belong to richer host
+     * renderers), so the corner dots and edge lines this renderer draws are the
+     * exact geometry the binder's press ladder hit-tests. Before this the default
+     * renderer hit-tested eight handles it never painted (live audit,
+     * nodes/node-resize-gesture.html).
+     */
+    private readonly resizeTools;
+    private motionTracker;
+    /**
+     * Links whose route THIS frame was computed under motion suppression. Volatile:
+     * never stored in the route memo — the settle frame has the same endpoints,
+     * hence the same route key, and a cached suppressed chord would be served
+     * straight back instead of the real detour. Cleared per frame.
+     */
+    private frameVolatileRoutes;
+    /** One pending settle-epoch bump at a time (see the end of render()). */
+    private motionSettleQueued;
+    /** Per-frame static/moving obstacle partition, keyed on the frame's node-array identity. */
+    private frameMotionPartition;
+    /**
+     * Wave 8 — Card 7. Watches frame time and biases the LOD tier down when this
+     * machine cannot afford what the zoom asked for. `null` when disabled, in which
+     * case the tier is exactly what the zoom says and rendering is deterministic —
+     * which is what screenshot tests and print need.
+     */
+    private governor;
+    private solverBridge;
+    /**
+     * Monotonic id of "the world the obstacles describe". Bumped whenever a node
+     * rect or the group state changes. This is what lets an ASYNC solver answer be
+     * matched to the world it was computed for — and discarded if that world is
+     * gone. Without it, a solve that lands one frame late paints links through
+     * nodes that have since moved.
+     */
+    private worldVersion;
+    private frameSpreadLanes;
+    private edgeOptimizer;
+    private pathSimplifier;
+    private frameJumps;
+    private frameLabelOffsets;
+    private frameSeparation;
+    private frameLinkSigs;
+    /** Unsubscribe from the edge-template registry (Card 5). */
+    private unsubscribeEdgeTemplates?;
+    /** Wave 6 — Card 2/0: cache invalidation for the link pipeline + shape registry. */
+    private unsubscribeLinkPipeline?;
+    private unsubscribeShapeRegistry?;
+    private frameDefs;
+    private frameLod;
+    private frameZoom;
+    private lodCache;
+    private lodCacheTier;
+    private lastRenderTime;
+    private lastNodeCount;
+    private lastLinkCount;
+    private renderTimestamp;
+    private frameCount;
+    private fps;
+    /** Handle of the 1 Hz FPS sampler — cleared in dispose() (see startFPSTracking). */
+    private fpsInterval?;
+    /**
+     * THIS DIAGRAM'S contribution tables — shapes, named styles, link/label
+     * templates, markers, and the link pipeline it registered for itself.
+     *
+     * Empty until something contributes, and an empty scope is treated as no scope
+     * at all, so a renderer nobody extended costs exactly what it always did.
+     */
+    private readonly registryScope;
+    private readonly registryFacade;
+    /**
+     * Register shapes / styles / markers / link-pipeline stages for THIS renderer
+     * alone. The module-level `registerShape()` & friends remain the process-wide
+     * registry, and this one shadows it — see `ext/diagram-registry.ts`.
+     */
+    getRegistry(): DiagramRegistry;
+    constructor(engine: DiagramEngine, config?: SVGRendererConfig, theme?: Theme);
+    /**
+     * Render diagram to VNode tree.
+     *
+     * THE REGISTRY SCOPE IS ACTIVATED HERE, around the whole pass, and this is the
+     * only place it needs to be for the picture to be right. Every contribution
+     * registry the frame consults — shapes, named styles, link/label templates,
+     * markers, anchors, connection points, connectors — resolves this diagram's
+     * own table first and the process-global one second, including from the read
+     * sites that are pure free functions three frames down (`shapeStrategy` in
+     * port-layout, `resolveNodeStyle` in the style cascade) and could not have been
+     * handed an instance without rewriting their signatures. See
+     * `ext/registry-scope.ts`.
+     *
+     * A diagram that contributed nothing activates nothing, so the single-diagram
+     * path is byte-identical to what it was.
+     */
+    render(viewport: Rectangle, zoom: number): VNode;
+    private renderInScope;
+    /**
+     * The tier actually rendered last frame, and the governor's reasoning for it.
+     *
+     * Exposed because an invisible governor is indistinguishable from a bug: if the
+     * picture silently simplifies, the only honest thing to do is be able to say WHY.
+     * The perf HUD reads this; so can an application that wants to tell the user "this
+     * diagram is being drawn at reduced detail to stay responsive".
+     */
+    getQualityState(): {
+        tier: LODLevel;
+        governor?: GovernorState;
+    };
+    /**
+     * Tier names richest → poorest, which is the order the governor's bias walks.
+     *
+     * Derived from the diagram's LIVE config rather than a hard-coded triple, because
+     * `registerLODTier`/`setLODConfig` are public API — a governor that walked a
+     * stale list would step a custom tier into one that no longer exists.
+     */
+    private lodTierNames;
+    /**
+     * wave8/dirty — everything a frame depends on that is NOT model state.
+     *
+     * Returns `null` for a frame that must never be reused: a live connection or
+     * reconnection drag paints a preview out of INTERACTION state, which no dirty
+     * flag and no epoch tracks. Rather than try to hash a drag (and get it subtly
+     * wrong once, which is a stuck ghost line on screen), we simply declare those
+     * frames uncacheable. They are, by definition, frames in which the user is
+     * moving the mouse — there was nothing to skip anyway.
+     */
+    private frameSignature;
+    /**
+     * Drop the cached frame. Call from anything whose effect on the picture the
+     * mutation epoch cannot see — a topology event, a style/theme invalidation, a
+     * registry swap. Cheap and idempotent: the cost of calling it when you did not
+     * need to is one rebuilt frame; the cost of NOT calling it when you did is a
+     * stale picture, so when in doubt, call it.
+     */
+    invalidateFrame(): void;
+    /**
+     * How many times this renderer has been told "the picture you have is no longer
+     * the picture you would draw".
+     *
+     * A HOST'S idle-skip must consult this, not just the model's mutation epoch.
+     * The two are not the same, and the gap between them is a real bug: when the
+     * off-thread route solver answers, the MODEL has not changed — the epoch does
+     * not move — but the renderer's own answer about it has improved. A scheduler
+     * keyed only on the model would drop that repaint before `render()` was ever
+     * called, and the refined routes would never reach the screen. The renderer's
+     * internal gate cannot save you there; it never gets asked.
+     *
+     * So: model epoch says "did the world change", this says "did MY picture of it
+     * change". Skip a frame only when both say no.
+     */
+    getInvalidationEpoch(): number;
+    /**
+     * wave8/dirty — the incrementality is only real if these move. `framesSkipped`
+     * counts frames served from the previous root (zero DOM work); `framesBuilt`
+     * counts frames actually walked. An idle canvas should build ONE.
+     */
+    getFrameStats(): {
+        built: number;
+        skipped: number;
+    };
+    /**
+     * Get current theme
+     */
+    getTheme(): Theme;
+    /**
+     * Set theme and update rendering
+     */
+    setTheme(theme: Theme): void;
+    /**
+     * THE HOT-SWAP. Re-theme by rewriting this instance's `--grafloria-*` variables.
+     *
+     * In CSS mode every value the built-in stylesheet paints resolves through those
+     * variables, and every `themeRef`-bound property that lands in an inline CSS
+     * style string is emitted as `var(--grafloria-…)`. So for all of them, *this one
+     * string write IS the re-theme*: no VNode is rebuilt, no element is touched,
+     * the browser simply recomputes.
+     *
+     * What it cannot cover, it does not pretend to: the entities recorded in
+     * `themeBoundNodes` / `themeBoundLinks` (see the field docs) baked a theme
+     * literal into their VNode, so they — and only they — are marked dirty and
+     * re-resolve on the next frame. An idle diagram re-themes with zero restyles;
+     * a diagram with three selected nodes restyles three nodes.
+     *
+     * Programmatic (Canvas) mode has no stylesheet at all, so there is nothing to
+     * rebind and the full invalidation is the only correct answer.
+     */
+    applyThemeVariables(theme: Theme): void;
+    /** The colorMode in force, or undefined when the host never asked for one. */
+    getColorMode(): ColorMode | undefined;
+    /**
+     * Switch colour mode at runtime. `'system'` starts following the OS; the other
+     * two pin it. Creates the media-query subscription on first use, so a host can
+     * opt in after construction.
+     */
+    setColorMode(mode: ColorMode, themes?: ThemeSet): void;
+    /**
+     * Point this diagram's variables at the host design system's tokens
+     * (`shadcnBridge()`, `muiBridge()`, `tailwindBridge()`, or a hand-written map).
+     * `null` removes the bridge.
+     *
+     * Pure CSS: the values are the host's own `var(--…)` expressions, so when the
+     * host app flips ITS theme, this diagram follows with no code at all — and no
+     * VNode is rebuilt here either, for exactly the reason the hot-swap works.
+     */
+    setTokenBridge(bridge: TokenBridge | null | undefined): void;
+    /** The bridge currently applied, if any. */
+    getTokenBridge(): TokenBridge | undefined;
+    /**
+     * This renderer's instance id (`grafloria-3`). It is the value of the
+     * `data-grafloria-instance` attribute on the root `<svg>`, the scope of this
+     * diagram's CSS variables, and the suffix of its `<style>` element id.
+     */
+    getInstanceId(): string;
+    /** Id of the `<style>` element holding THIS renderer's theme variables. */
+    getStyleElementId(): string;
+    /** Id of the `<style>` element holding THIS renderer's bridge + a11y overrides. */
+    getOverrideElementId(): string;
+    /**
+     * The complete stylesheet this renderer would inject into `<head>`: the shared
+     * theme-independent rules, the animation rules, and THIS instance's
+     * `--grafloria-*` variable block.
+     *
+     * Needed by the SSR path (Card 6). In CSS mode the theme lives entirely in CSS
+     * variables, so the emitted SVG is theme-INDEPENDENT — which is exactly what
+     * makes hydration cheap, but it also means a server-rendered diagram is
+     * unstyled until some stylesheet arrives. `renderToStaticSVG()` returns this
+     * string so the server can ship it in a `<style>` tag; the client renderer then
+     * re-injects byte-identical content under the same ids, so hydration is still a
+     * no-op visually.
+     */
+    getStyleSheet(): string;
+    /**
+     * Put this diagram's scope on a host element.
+     *
+     * The root `<svg>` carries it automatically, and `foreignObject` content
+     * inherits from it (it lives inside the SVG). Nodes rendered on an HTML LAYER
+     * (`metadata.useHTMLLayer`) do NOT — they are siblings of the SVG. Call this
+     * with the element that wraps BOTH layers (the canvas host) so those nodes
+     * inherit the `--grafloria-*` variables and match the scoped rules too.
+     */
+    applyInstanceScope(element: Element | null | undefined): void;
+    /**
+     * The instance-scope prop for a root VNode. Emitted in CSS mode only:
+     * programmatic mode injects no stylesheet, so scoping it would make its
+     * elements match ANOTHER instance's shared rules with no variables defined.
+     */
+    private instanceScopeProps;
+    /**
+     * Drop cached VNodes and mark every entity dirty. Anything that changes how a
+     * style RESOLVES (theme swap, named-style (re)definition) must call this,
+     * because the cascade is resolved into the emitted VNode.
+     */
+    private invalidateStyles;
+    /**
+     * The SURGICAL counterpart of `invalidateStyles`, used by the colorMode
+     * hot-swap: dirty ONLY the entities that baked a theme literal into their last
+     * VNode. Everything else re-themes through the rebound CSS variables, untouched.
+     *
+     * Cache entries are dropped by id rather than by clearing the whole cache, so a
+     * clean node's VNode survives — that is the point; a cleared cache would mean
+     * rebuilding the very frames we set out not to rebuild.
+     */
+    private invalidateThemeBoundStyles;
+    /** Cache keys are `<kind>-<id>-<lod>`; an entity owns one entry per LOD tier. */
+    private dropCacheEntries;
+    /**
+     * Install the freeze / lazy-mount gate.
+     *
+     * With no lifecycle installed the renderer behaves exactly as it always has —
+     * every entity culling admits gets a view, on the frame it is admitted. That is
+     * the default, and it stays the default: laziness is something a host asks for.
+     */
+    setViewLifecycle(lifecycle: ViewLifecycle | null): void;
+    getViewLifecycle(): ViewLifecycle | null;
+    /**
+     * What culling admitted on the last frame and the gate held back.
+     *
+     * This is the progressive mounter's work queue, and it comes from the renderer
+     * rather than being recomputed by the mounter because the viewport→viewBox→cull
+     * maths (zoom, link margin) lives here and must not be reimplemented anywhere it
+     * could drift.
+     */
+    getDeferredEntities(): ReadonlyArray<readonly [LazyEntityKind, string]>;
+    /**
+     * Subtract from what culling admitted: frozen entities, and — during a
+     * progressive mount — everything the mount has not reached yet.
+     */
+    private applyMountGate;
+    /**
+     * How many entities the NEXT theme swap would have to restyle. Zero means the
+     * swap is a pure variable rebind. Exposed because "no restyle of every VNode"
+     * is a claim that should be measurable, not taken on trust — the tests assert
+     * on it, and so can a host.
+     */
+    getThemeBoundEntityCount(): number;
+    /** Node properties this renderer emits through an inline CSS `style` string. */
+    private static readonly NODE_VAR_SAFE;
+    /** Link properties this renderer emits through an inline CSS `style` string. */
+    private static readonly LINK_VAR_SAFE;
+    /**
+     * Replace every `themeRef(...)` in a resolved style with something the DOM can
+     * paint, and report whether doing so froze a theme literal into the VNode.
+     *
+     * TWO emissions, and the difference is not cosmetic:
+     *
+     *   `var(--grafloria-…, literal)` — when the property's value ends up inside an
+     *       inline CSS `style` string. Re-theming is then just rebinding the
+     *       variable, so the element never needs to be rebuilt.
+     *
+     *   the LITERAL — everywhere else. SVG PRESENTATION ATTRIBUTES cannot hold
+     *       `var()` (`fill="var(--x)"` is simply invalid and the shape paints
+     *       black), and programmatic/Canvas mode has no CSS at all. The entity is
+     *       recorded as theme-bound so the next theme swap re-resolves it.
+     *
+     * `varSafe` is therefore not a preference — it is the exact set of properties
+     * this renderer is known to emit through a style string. Adding a property to
+     * it without also routing its emission through `style` would paint black.
+     */
+    private materializeThemeRefs;
+    /**
+     * A paint value safe to put in an SVG PRESENTATION ATTRIBUTE.
+     *
+     * `var(--x)` is not: the attribute is invalid, the browser ignores it, and the
+     * element falls back to whatever the stylesheet says (or black). Everything
+     * else — a literal, a `url(#gradient)` paint-server reference — is fine.
+     */
+    private attributeSafePaint;
+    /** Did a theme LAYER (state / type-default) contribute a literal to this node? */
+    private drawsThemeLiteral;
+    private linkDrawsThemeLiteral;
+    /** `theme.nodes[type]` / `theme.links[type]` — `default` is the BASE layer, not a type. */
+    private hasTypeDefaults;
+    /**
+     * A link's stroke and stroke-width as LITERALS — never a `var()` string.
+     *
+     * Needed by the two consumers that cannot take a CSS variable:
+     *   - the ARROWHEAD, which paints through presentation attributes;
+     *   - the hit-area width, which does ARITHMETIC on the stroke width
+     *     (`Number('var(--x)') + 8` is NaN, and a NaN-wide hit area is unclickable).
+     */
+    private linkPaintLiterals;
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * Export the diagram.
+     *
+     * - `'svg'` → a STANDALONE, styles-inlined SVG document. Pure, deterministic,
+     *   and DOM-free: it runs in plain Node (an SSR pass, a thumbnail worker).
+     * - `'png' | 'jpeg' | 'webp'` → a `data:` URL. Needs an SVG rasterizer: a
+     *   canvas one is used automatically in a browser/worker; in bare Node you must
+     *   pass `options.rasterBackend` (and you get a clear error if you don't).
+     *
+     * Defaults to the whole diagram (content bounds + 20px), not the current
+     * viewport — a thumbnail of the visible slice is rarely what anyone means.
+     */
+    export(format?: ExportFormat, options?: ExportOptions): Promise<string>;
+    /**
+     * The document envelope to embed — the ENGINE's own, so the artifact carries exactly
+     * the format the engine already round-trips losslessly and checksums.
+     *
+     * `createdAt` is the one field that would otherwise make an export non-deterministic,
+     * so a caller who needs byte-identical output passes it in.
+     */
+    private modelEnvelope;
+    /**
+     * The synchronous, fully headless SVG path — what `export('svg')` returns, plus
+     * the fidelity `warnings` (foreignObject, unresolved theme vars) that the
+     * string-only `IRenderer.export` signature has nowhere to put.
+     */
+    exportSvgString(options?: ExportOptions): SvgExportResult;
+    /**
+     * A TRUE VECTOR PDF: paths stay paths and text stays text, so it is selectable,
+     * searchable and scales without pixelation.
+     *
+     * Painted straight from the VNode tree — the same tree the screen gets — so there is no
+     * SVG→DOM→PDF round trip and no second rendering path. See `export/pdf/` for the
+     * dependency decision (we do NOT use svg2pdf.js + jsPDF, and why) and for the honest
+     * list of what a base-14-font PDF cannot do.
+     */
+    exportPdf(options?: ExportOptions): PdfExportResult;
+    /**
+     * Slice the diagram into pages (Card 5).
+     *
+     * Returns one standalone SVG per page — a tile grid you can print, or lay out as a poster.
+     * Breaks are snapped so they do not cut a node in half; see `export/pagination.ts`.
+     */
+    exportPages(pagination: PaginationOptions, options?: ExportOptions): PagedSvgResult;
+    /**
+     * A multi-page PDF of a diagram too big for one sheet.
+     *
+     * The paginator supplies the page grid; the PDF writer honours each page's `clip`, so a
+     * break pulled back to spare a node leaves white space rather than half a box.
+     */
+    exportPaginatedPdf(pagination: PaginationOptions, options?: ExportOptions): PdfExportResult;
+    /**
+     * Every EXTERNAL image URL the exported tree will reference — a panel node's
+     * avatar/logo/icon (`<image href="https://…">` painted by the renderer itself), or
+     * any registered shape that emits one. Widget (HTML-layer) captures are NOT in this
+     * tree; their URLs are collected from the captures by the instance layer.
+     *
+     * This is the LOOK-BEFORE-YOU-EXPORT half of the async image pass: `await export(…)`
+     * calls this first, fetches the URLs through the tiers, and hands the resolved map
+     * back down as {@link ExportOptions.resolvedAssets} for the pure sync substitution.
+     * The tree is enumerated from the SAME `render()` the export will serialize (VNode
+     * caching makes the second call cheap), so what is collected and what is substituted
+     * cannot drift. Synchronous and network-free.
+     */
+    collectExportImageUrls(options?: ExportOptions): string[];
+    /**
+     * The ids currently selected — what `scope: 'selection'` exports.
+     *
+     * Selection is MODEL state (`node.state.selected`, `link.state === 'selected'`),
+     * which is the same place the renderer reads it from to paint the selection
+     * colours. There is no separate selection registry to consult.
+     */
+    private selectedIds;
+    /**
+     * The world rectangle that contains the whole diagram, padded.
+     *
+     * Nodes' bounding boxes plus any routed link points (a link can bulge outside
+     * its endpoints' union). An empty diagram exports a small, still-valid square
+     * rather than a zero-area document a rasterizer would reject.
+     */
+    private contentViewport;
+    /**
+     * Dispose renderer and clean up resources
+     */
+    /**
+     * Wave 8 — Card 6: how many links this frame actually had to route, and how
+     * many were served from the previous frame.
+     *
+     * Public because a cache that silently stops hitting is indistinguishable from
+     * no cache at all — it just gets slow again, and nothing says so. Tests assert
+     * on this; the benchmark harness prints it.
+     */
+    getRoutingStats(): {
+        routed: number;
+        reused: number;
+        cached: number;
+    };
+    dispose(): void;
+    /**
+     * Render links layer
+     * FIXED: Sort links so selected/highlighted links render on top
+     */
+    private renderLinksLayer;
+    /**
+     * Everything that determines a link's route, as a string.
+     *
+     * If two frames produce the same key then `computeAutoRoute` — a pure function
+     * of these inputs and the obstacle set — would produce the same polyline, so we
+     * serve the old one. Which means: anything computeAutoRoute reads MUST be in
+     * here, or the cache serves a stale route. The obstacle set is the single input
+     * deliberately left out (it is the whole diagram); it is handled instead by
+     * invalidateStaleRoutes(), which evicts on obstacle MOTION.
+     *
+     * Endpoints are quantised to 1/100 unit. They are derived from node positions
+     * and port layouts in floating point, and an endpoint that is unchanged in
+     * every way that matters can still differ in the last mantissa bit; keying on
+     * the raw float would miss forever and quietly hand back the O(scene)
+     * behaviour this card exists to delete — a cache that never hits looks exactly
+     * like no cache at all, and says nothing while it does it.
+     */
+    private routeKey;
+    /** The source node's box — the extra input a self-loop's route depends on. */
+    private selfLoopBoxKey;
+    /**
+     * Forget the routes that the world just invalidated — and ONLY those.
+     *
+     * A link needs re-routing if one of its endpoint nodes moved (the route key
+     * catches that by itself, because the endpoints ARE the key) OR if some OTHER
+     * node moved into or out of the corridor it runs through. The second case is
+     * the one that matters and the one that is easy to miss: the link did not
+     * change, its own nodes did not change, and yet a wall just appeared across
+     * its path. "Re-route the links whose endpoints moved" is fast and wrong.
+     *
+     * So: diff the node rects against last frame; every node that moved, resized,
+     * appeared or vanished contributes both the rect it VACATED and the rect it now
+     * OCCUPIES; ask the engine's link spatial index — which is keyed on each link's
+     * routed bounding box, because syncLinkPoints refreshes it — which links run
+     * through those regions once the routing clearance is added; evict exactly them.
+     */
+    private invalidateStaleRoutes;
+    /**
+     * Wave 8 — Card 6: drive the global penalty-field solver, and adopt its answer
+     * when (and only when) it describes the world we are actually drawing.
+     *
+     * Order of events across frames, which is the whole design:
+     *
+     *   frame N   — the sync router paints correct routes; we hand the solver this
+     *               world (edges + obstacles + version) and carry on. Nothing waits.
+     *   frame N+k — the solve lands. If the world is still version N, its routes are
+     *               adopted and `onRoutesRefined` asks the host for a re-render. If
+     *               the world has MOVED, the answer is dropped on the floor: it was
+     *               computed against obstacles that are not there any more, and
+     *               painting it would run links through nodes.
+     *
+     * So a link's geometry is always either "correct, one-at-a-time" or "correct,
+     * globally optimised" — never "optimised for a diagram that no longer exists".
+     */
+    private applyGlobalSolver;
+    /** Wave 8 — Card 6: what the off-thread solver has been doing. */
+    getRouteSolverStats(): RouteSolverStats | null;
+    /**
+     * A fingerprint of the obstacle facts that are NOT node rectangles: which
+     * groups are collapsed, and where their blocks sit. Node motion is tracked
+     * precisely; this only has to notice that GROUP state moved.
+     */
+    private obstacleEpoch;
+    /**
+     * Wave 5 — Card 4: separate corridor-sharing segments of DIFFERENT links onto
+     * parallel lanes. Only orthogonal-geometry links participate (a diagonal
+     * smooth line has no corridor to share); only interior segments move; a
+     * member whose slide would shrink or reverse an adjacent segment pins its
+     * lane, and an unsatisfiable corridor is skipped whole.
+     */
+    private applyChannelNudging;
+    /**
+     * Group every link in the diagram by the (unordered) node pair it connects and
+     * hand each member of a multi-link group its lane offset.
+     *
+     * UNORDERED pairs: A→B and B→A are one visual bundle. Ordering them separately
+     * would give each a group of one, an offset of 0, and put both back on the same
+     * centre line — which is the bug this card exists to kill.
+     *
+     * A pair with exactly ONE link gets offset 0 and is therefore untouched, which
+     * is what keeps every existing diagram pixel-identical.
+     */
+    private computeParallelSeparation;
+    /**
+     * The unit normal a link's bundle fans along.
+     *
+     * Derived from the bundle's CANONICAL node order (lower id → higher id), NOT
+     * from this link's own source → target. Otherwise the two halves of a
+     * bidirectional pair compute opposite normals, their opposite lane offsets
+     * cancel, and both links land back on top of each other.
+     */
+    private bundleNormalFor;
+    /**
+     * Route a self-loop (source node === target node) as a loop away from the node.
+     *
+     * Never goes near the routing engine: the routers exclude a link's own nodes
+     * from their obstacle set, so a "route" from a node back to itself came out as
+     * a degenerate stub buried in the node body. The loop is built geometrically
+     * instead, as a polyline, which the existing path emitters then draw in the
+     * link's own idiom (rounded rectangle for `orthogonal`, a spline for `smooth`,
+     * a hard polygon for `direct`).
+     */
+    private computeSelfLoopRoute;
+    /**
+     * Which self-loop this is on its node (0 = the first). Stable across frames
+     * because it reads the diagram's own link order.
+     */
+    private selfLoopIndex;
+    /**
+     * Feed the whole diagram to the edge optimizer and cache what it decided for
+     * this frame.
+     *
+     * ALL links go in, not just the visible ones: a link scrolled off the left edge
+     * still crosses the one you can see, and its label still occupies space. Only
+     * VISIBLE links have been re-routed this frame — the rest carry the points they
+     * last had, exactly as the old per-link scan read them.
+     */
+    private runEdgeOptimizer;
+    /**
+     * The jump config for a link, or undefined when it draws no jumps.
+     *
+     * Same gate the per-link scan applied: enabled, non-zero size, at least two
+     * points, and NOT a 2-point curve (a chord-based jump would both misplace the
+     * arc and destroy the bezier).
+     */
+    private jumpConfigFor;
+    /** The link's labels, described for the optimizer (anchor, box, path normal). */
+    private optimizerLabelsFor;
+    /**
+     * Mark a link dirty when anything OUTSIDE the link changed the way it renders.
+     *
+     * `renderLink` serves a cached VNode for any link that is not dirty — but a
+     * link's drawing depends on its routed points (which change when a NODE moves),
+     * on the crossings other links make with it, and on where the optimizer put its
+     * labels. None of those mark the link dirty. Comparing a per-frame signature
+     * closes that hole; it also fixes the pre-existing version of this bug, where a
+     * cached link kept drawing yesterday's jump arcs.
+     */
+    private markLinksWhoseFrameChanged;
+    /**
+     * Card 7 — auto-size every opted-in node before culling/rendering. Uses the
+     * theme's label font size for measurement so the reserved box matches the text
+     * the label engine will actually lay out, and feeds each node its composite
+     * panel reserve (Card 5 header band / image / badge row) so the shape grows to
+     * fit the WHOLE body, not just the label.
+     */
+    private autoSizeNodes;
+    /**
+     * The extra content space a node's composite panel (Card 5) reserves around
+     * its label, so auto-sizing (Card 7) grows the shape to fit the WHOLE body.
+     * Returns undefined for a plain (label-only) node.
+     */
+    private panelReserve;
+    /**
+     * Card 5 — the composite panel overlay for a node (header band, image/icon
+     * slots, badges, ERD/UML rows). Built through the framework-agnostic `panel`
+     * module and themed from the active theme; text goes out via `textContent`
+     * and image hrefs are sanitized (see panel.ts). Empty for a plain node.
+     */
+    private renderPanelOverlay;
+    /**
+     * Card 4 — the HTML / foreignObject body for a node (sanitized rich content
+     * sized to node.size). Empty for a non-HTML node. The FO is keyed by a content
+     * hash so a data change replaces the opaque subtree while hover/selection
+     * leaves it intact (see html-node.ts).
+     */
+    private renderHtmlBody;
+    /**
+     * Render nodes layer
+     */
+    private renderNodesLayer;
+    /**
+     * Phase 2: Render connection preview layer
+     */
+    private renderConnectionPreviewLayer;
+    /**
+     * Phase 2: Render connection preview line
+     */
+    private renderConnectionPreview;
+    /**
+     * Wave 2 (Edges & links): render the endpoint-reconnection ghost link.
+     *
+     * Draws a dashed preview from the STATIONARY endpoint of the link (the one
+     * not being dragged) to the cursor, using the same RoutingEngine the real
+     * connection preview uses so the ghost matches the link's routing algorithm.
+     * Colour reflects drop validity (success vs default link colour).
+     */
+    /**
+     * wave15/helper-lines: the live snap guides a node drag publishes
+     * (engine.getSnapGuides) as dashed overlay lines; spacing segments carry
+     * their gap label at the midpoint. Null (no layer at all) when idle, so a
+     * diagram that never snaps pays nothing.
+     */
+    private renderSnapGuidesLayer;
+    /**
+     * The proximity-connect proposal wire: a dashed line between the two port
+     * anchors a drop would link. Port anchors resolve through the SAME helpers
+     * the port glyphs render with (getPortPositionForShape + getWorldPosition),
+     * so the wire lands exactly on the highlighted glyphs.
+     */
+    private renderProximityPreview;
+    private renderReconnectionPreview;
+    /**
+     * Phase 2: Generate connection preview path
+     * Supports straight, bezier, step (orthogonal) routing
+     */
+    private generateConnectionPreviewPath;
+    /**
+     * Render single node
+     */
+    /**
+     * wave2/rendering: single LOD feature gate. Reads the active diagram's
+     * declarative LODConfig (`diagram.shouldRender`) instead of hardcoding
+     * `lod === 'high'` / `lod !== 'low'` here, so custom tiers Just Work.
+     * Returns false when there is no diagram (nothing to render anyway).
+     */
+    private lodAllows;
+    /**
+     * The node group's transform.
+     *
+     * wave4/interaction BUGFIX: `node.rotation` was DEAD in the renderer. The model
+     * had it (`setRotation`, `rotate`, it is serialized, and the hierarchy maths in
+     * `NodeModel.getGlobalPosition` factors it in), the canvas even branched on it
+     * (`hasTransformsInHierarchy`), but the SVG output only ever emitted
+     * `translate(x, y)` — so a rotated node rendered unrotated and the rotate tool
+     * would have had nothing to show. Rotation is about the box CENTRE, which is
+     * the convention `applyResizeToNode` (selection-tools) inverts when it resizes
+     * a rotated node.
+     */
+    private nodeTransform;
+    /** Accessible name of a node: its label, else "<type> node". */
+    private nodeAccessibleName;
+    /**
+     * The ARIA props for a node group.
+     *
+     * FIXED HERE (a real, shipped WCAG 4.1.2 / axe `aria-allowed-attr` violation):
+     * every node used to emit `role="group" aria-selected="…"`. `aria-selected` is
+     * only valid on gridcell/option/row/tab/columnheader/rowheader/treeitem — NOT
+     * on `group`. So every node in every diagram carried an invalid ARIA attribute,
+     * and axe flags it on sight. The node is a graphic, so it takes the W3C Graphics
+     * role; selection now rides in the accessible NAME (which is what a screen
+     * reader actually reads out) and in `data-selected` for tooling. The place
+     * `aria-selected` is genuinely valid — `role="treeitem"` — is the outline
+     * mirror, and that is exactly where the outline view puts it.
+     */
+    private nodeAriaProps;
+    /**
+     * The ARIA props for a link group.
+     *
+     * THE headline gap of this wave: before it, `renderLink` emitted NO ARIA at
+     * all. Every edge in every diagram was invisible to a screen reader, so the
+     * graph read as a bag of disconnected shapes — the one thing a diagram exists
+     * to communicate (what connects to what) was the one thing AT users could not
+     * get.
+     */
+    private linkAriaProps;
+    /**
+     * ROVING TABINDEX (card 1). The canvas is ONE tab stop; arrow keys — not Tab —
+     * move within it. So exactly one element in the whole diagram carries
+     * `tabindex=0` at any moment (the focused one), and every other focusable
+     * element carries `-1`. Tab therefore enters the diagram once and leaves it
+     * once, which is what a composite widget is supposed to do; without this, a
+     * 200-node diagram is a 200-stop tab trap.
+     */
+    private rovingTabIndexProps;
+    /**
+     * Tell the renderer which entity the keyboard controller has focused, so the
+     * next frame emits `tabindex=0` on it (and `-1` on everything else).
+     *
+     * Marks only the OLD and NEW focus targets dirty — moving focus must not
+     * invalidate the whole diagram.
+     */
+    setAccessibleFocus(target: {
+        type: 'node' | 'link' | 'comment';
+        id: string;
+    } | null): void;
+    getAccessibleFocus(): {
+        type: 'node' | 'link' | 'comment';
+        id: string;
+    } | null;
+    /**
+     * wave9/comments (Card 6): attach (or detach) the source of comment pins.
+     *
+     * Installing a source CHANGES THE PICTURE while moving nothing the frame gate watches —
+     * not the model epoch, not the viewport. Without the explicit invalidation the gate would
+     * keep serving back the last frame, which has no pins in it, forever. This is the trap
+     * this wave was warned about, and it is one line.
+     */
+    setCommentSource(source: CommentSource | null): void;
+    getCommentSource(): CommentSource | null;
+    /**
+     * The comment pin layer for this frame, or null when nothing is attached.
+     *
+     * Culled against the same world rect the nodes are, so a diagram with 4,000 comments
+     * costs what the ones ON SCREEN cost. Drawn in WORLD coordinates inside the viewBox, so
+     * pan and zoom carry the pins with the diagram without a line of code.
+     */
+    private renderCommentsLayer;
+    /**
+     * wave12/group-visuals — the group FRAMES.
+     *
+     * One frame per group: a rounded `<rect>` at the group's outer bounds, a label
+     * band carrying its `name`, and — when collapsed — a visibly distinct treatment
+     * (dashed, opaque, marked `data-collapsed`). Returns null when the diagram has
+     * no groups, so a group-free canvas pays a single array read and the children[]
+     * positional contract is untouched (see the children assembly in `render`).
+     *
+     * PURE / READ-ONLY. It only reads group geometry (`getOuterBounds`) — it never
+     * mutates the model, so it cannot dirty an idle frame and disarm the frame gate.
+     *
+     * PAINT ORDER. Groups are sorted parent-behind-child (nesting depth first, then
+     * `zIndex`, then insertion order) so a nested sub-group draws ON TOP of the
+     * parent that contains it — otherwise the parent's fill would bury the child.
+     *
+     * CULLING. A linear intersect against the visible rect, matching how strokes are
+     * culled: groups number in the tens, so a spatial index would be theatre.
+     */
+    private renderGroupsLayer;
+    /** One group's frame + label band, themed and accessible. */
+    private renderGroupFrame;
+    /** The canvas's own semantics. */
+    private rootAriaProps;
+    /**
+     * NON-COLOUR STATUS ENCODING — WCAG 1.4.1 (Use of Colour).
+     *
+     * The audit question, answered honestly: our states WERE largely colour-only.
+     *   - `selected`    already had a dashed outline → a genuine shape cue. Fine.
+     *   - `highlighted` was a fill/stroke SWAP and nothing else. Colour-only.
+     *   - `error`       was a fill/stroke SWAP and nothing else. Colour-only.
+     *
+     * A user with deuteranopia, or anyone on a monochrome display, could not tell
+     * an errored node from a highlighted one from a normal one. This is the exact
+     * failure most diagram engines quietly ship.
+     *
+     * So both now carry a REDUNDANT, non-colour cue:
+     *   - error       → a corner badge with a "!" glyph, plus a dense dashed ring;
+     *   - highlighted → a distinct dashed emphasis ring (a different dash rhythm
+     *                   from selection's, so the two never read as the same thing).
+     *
+     * The badges are `aria-hidden` — the state is already in the accessible name,
+     * and announcing it twice is its own accessibility bug.
+     */
+    private renderStateAffordances;
+    /**
+     * The same 1.4.1 fix for LINKS, which were worse: a selected link and a
+     * highlighted link differed from a default one by stroke COLOUR and nothing
+     * else — no dash, no width, no shape. On a greyscale display all three edges
+     * are identical.
+     *
+     * The cue is a "casing" — a wider, semi-transparent halo drawn UNDER the real
+     * path. It reads as a shape change (the edge visibly thickens) at any colour
+     * perception, and because it is an additive sibling it does not perturb the
+     * path geometry that the routing/label/toolbar code all depend on.
+     */
+    private renderLinkStateAffordances;
+    private renderNode;
+    /**
+     * Every VNode-cache key an entity currently occupies — one per LOD tier it
+     * has been rendered at since its last change.
+     *
+     * A SINGLE dirty flag guards a PER-LOD cache: rebuilding one tier's entry
+     * and calling markClean() left every OTHER tier's cached entry stale, so a
+     * layout that moved geometry resurfaced its PRE-layout picture on the next
+     * zoom/fitView LOD flip (live report: "click force then dagre — the diagram
+     * is destroyed"; the painted edges were the previous layout's routes).
+     * Evicting the entity's whole key set on the dirty rebuild is what makes
+     * markClean() safe again — and it tracks keys rather than hard-coding the
+     * tier vocabulary, so custom governor tiers stay covered.
+     */
+    private entityCacheKeys;
+    private cacheEntityVNode;
+    /**
+     * Check if a node should use foreignObject rendering
+     * Nodes can indicate they want foreignObject by setting metadata.useForeignObject = true
+     */
+    private shouldUseForeignObject;
+    /**
+     * Render a node using foreignObject for component embedding
+     */
+    private renderNodeWithForeignObject;
+    /**
+     * Get container ID for a node (if it uses foreignObject)
+     */
+    getContainerId(nodeId: string): string | undefined;
+    /**
+     * Check if a node uses foreignObject rendering
+     */
+    isUsingForeignObject(nodeId: string): boolean;
+    /**
+     * Phase 2: Render ports for a node
+     *
+     * Wave 6 (Card 1): also resolves LABEL COLLISIONS, which is why the labels
+     * cannot be built inside `renderPort` — nudging a crowded label needs to see
+     * its neighbours, and a single port can't.
+     */
+    private renderPorts;
+    /**
+     * Wave 6 (Card 1): the port labels for one node, with collision-aware nudging.
+     *
+     * Labels are resolved per SIDE, because that is the axis they actually crowd
+     * on: a column of inputs down the left edge whose labels overlap vertically.
+     * Ports with no label cost nothing — a node with no labelled ports returns an
+     * empty array and emits not a single extra VNode.
+     */
+    private renderPortLabels;
+    /**
+     * Phase 3: Render single port
+     * Updated to support template system port rendering configuration
+     * CRITICAL FIX: Added pointer-events and proper z-index to ensure ports are clickable
+     */
+    private renderPort;
+    /**
+     * Wave 6 (Card 6): this port's role in the CURRENT connection drag.
+     *
+     * Reads the drag state's `invalidTargetPorts` — the map the connection manager
+     * now populates with a REASON per rejected port. Before wave 6 there was no
+     * such map, `validTargetPorts` was never filled either, and the renderer had
+     * literally no way to tell a legal target from an illegal one.
+     */
+    private portDragState;
+    /**
+     * Get port position relative to node's local coordinate system
+     * Used for rendering ports inside node groups that are already transformed
+     */
+    private getPortRelativePosition;
+    /**
+     * Phase 3: Determine if port should be rendered based on visibility strategy
+     * Updated to support template system configuration
+     * CRITICAL FIX: Added comprehensive debugging and proper string comparison
+     */
+    private shouldRenderPort;
+    private shouldRenderPortByMode;
+    /**
+     * Phase 2: Get port color based on type
+     *
+     * Wave 6 (Card 7): a port that declares a `dataType` wears THAT type's colour,
+     * if one was registered. Colour-by-type is the affordance that makes a typed
+     * graph readable at a glance — you can see that a `number` output will not
+     * mate with a `string` input before you even start the drag. Falls straight
+     * back to the direction colours, so an untyped port is unchanged.
+     */
+    private getPortColor;
+    /**
+     * Phase 3.1: Render node shape based on shape configuration
+     * Supports: rect, circle, ellipse, diamond, hexagon
+     */
+    /**
+     * Node label engine: render the node's label as a shape-fitted text block.
+     *
+     * - maxWidth  = the shape's inner-rect width (getInnerRect); the diamond /
+     *   ellipse / triangle … inset it so text stays inside the silhouette.
+     * - maxLines  = floor(innerHeight / lineHeight); overflow collapses to '…'.
+     * - a per-node <clipPath> sized to the exact inner rect is the hard backstop
+     *   that guarantees glyphs never escape the shape even if the width estimate
+     *   is off (it uses the naive length*fontSize*0.6 heuristic — see text-block).
+     *
+     * Returns [clipPath, text]; both are children of the node's translated <g>,
+     * so the clip rect and the text share the node-local coordinate space.
+     */
+    private renderNodeLabel;
+    /** Gap between a silhouette's bottom edge and its below-label (px). */
+    private static readonly BELOW_LABEL_GAP;
+    /**
+     * Paint a node's caption BELOW its silhouette (`metadata.labelPlacement:
+     * 'below'`). The label is centred under the node, wraps at a width a little
+     * wider than the shape (a 36px event circle should not force one-character
+     * lines), is NEVER clipped and NEVER shrunk below the theme size — outside
+     * the silhouette there is room, so legibility wins. The text block's top edge
+     * sits {@link BELOW_LABEL_GAP} px under the node's height, so it can never
+     * straddle the silhouette edge.
+     */
+    private renderNodeLabelBelow;
+    private renderNodeShape;
+    /**
+     * Phase 3.1: Render selection highlight matching node shape
+     */
+    private renderSelectionHighlight;
+    /**
+     * resize-ux: the PAINTED resize affordances — React Flow NodeResizer parity.
+     *
+     * When exactly one resizable, unlocked node is selected (the same conditions
+     * under which SelectionToolsController emits resize handles — this method
+     * paints whatever that controller computes, nothing of its own), draw:
+     *
+     *   - 4 EDGE LINES along the node's border (the side handles' bands: grab the
+     *     border anywhere and that edge follows), each with its axis cursor;
+     *   - 4 CORNER DOTS (white squares, primary border) with their diagonal
+     *     cursors, drawn AFTER the lines so a dot wins its own pixels — the same
+     *     priority the hit ladder gives it.
+     *
+     * All sizes are divided by zoom, so the affordances hold a constant SCREEN
+     * size at any zoom (RF's autoScale). That is also why this layer is rebuilt
+     * every frame and never enters the vnode cache: a cached node group would
+     * keep the sizing of whatever zoom it was built at.
+     *
+     * Painted as a ROOT overlay (not inside the node group) so it renders above
+     * the node's ports, and rotation comes from the layer's own geometry —
+     * `computeLayer` rotates every handle with the node.
+     */
+    private renderResizeToolsLayer;
+    /**
+     * Phase 3.1: Render shadow matching node shape
+     */
+    private renderShadow;
+    /**
+     * Get link endpoints (source and target port positions in world coordinates)
+     * CRITICAL FIX: Use the same getPortPositionForShape() as port rendering to ensure alignment
+     */
+    private getLinkEndpoints;
+    /**
+     * Wave 6 (ports, Card 5): resolve where `link` attaches to `port`, and which way
+     * it travels there.
+     *
+     * Two effects compose:
+     *   * the port's `fromSpot`/`toSpot` moves the attachment onto a named point of
+     *     the GLYPH (its corner, its far edge) and can aim the link somewhere other
+     *     than the port's outward normal;
+     *   * `spread` fans the links SHARING this port along the port's edge, so five
+     *     links into one input arrive as five strokes instead of one overdrawn pile.
+     *
+     * With neither configured this returns the port's plain anchor point and its
+     * side — the exact pre-wave-6 endpoint, to the bit. A port with a single link
+     * never moves even WITH spread enabled (a one-lane spread has offset 0).
+     */
+    private portAttachment;
+    /**
+     * The lane offset of every link sharing `port`, memoised for the frame.
+     *
+     * Lanes are keyed on the OTHER endpoint's port id so the fan is stable: adding
+     * an unrelated link, or reloading the diagram, must not reshuffle the strokes
+     * a user is already looking at.
+     */
+    private portSpreadLanes;
+    /**
+     * Map LinkModel pathType to RoutingAlgorithm
+     */
+    private mapPathTypeToAlgorithm;
+    /**
+     * Wave 5 (Edge routing) — Card 0. The routing algorithm for a link: its
+     * explicit `router` when set, else the legacy pathType derivation. This is
+     * the seam that finally makes the registered obstacle routers REACHABLE —
+     * mapPathTypeToAlgorithm could only ever produce straight/orthogonal, so
+     * a-star/dijkstra/visibility-graph were registered but unaddressable.
+     */
+    private routerForLink;
+    /**
+     * Wave 6: validate a router NAME against the live RoutingEngine registry.
+     * Unknown names — and the async-only 'elk' — degrade to 'orthogonal' instead
+     * of throwing out of the render loop. A diagram with one bad router name must
+     * still draw; it must not blank the canvas.
+     */
+    private resolveRouterName;
+    /**
+     * Card 0: does this link's ROUTER produce orthogonal (axis-aligned) geometry?
+     * The waypoint editor, arrow-angle maths and parallel-lane fan-out all branch
+     * on "is this an elbow route" — which is a property of the router, not of the
+     * pathType shorthand (an explicit manhattan/avoid router routes in elbows even
+     * when the legacy pathType says 'smooth').
+     */
+    private isOrthogonalRouting;
+    /**
+     * Wave 6 — Card 2. If this link names a REGISTERED connector, let it draw the
+     * whole path; otherwise return null and the built-in branches run untouched.
+     *
+     * ONE implementation, called from BOTH places a link's `d` is produced (the
+     * auto-routed branch via `convertRoutedPathToSVG`, and the manual-waypoint
+     * branch via `generatePathData`) — so a custom connector cannot work on one
+     * kind of link and silently not the other.
+     *
+     * The four BUILT-IN connector names never reach the registry: they are the
+     * renderer's own branches and stay exactly as they were.
+     */
+    private customConnectorPath;
+    /**
+     * Card 0: the CONNECTOR expressed in the renderer's legacy vocabulary, so the
+     * existing rendering branches (which all read a pathType-shaped string) apply
+     * unchanged: 'rounded' rides the orthogonal branch (that IS the rounded-corner
+     * code path), 'straight' rides direct. A link with no explicit connector
+     * renders byte-identically to before.
+     */
+    private renderPathType;
+    /**
+     * wave8/culling — Card 4. The path type to EMIT at this tier.
+     *
+     * Below the `link-detail` tier a curve is drawn as its polyline. A cubic needs
+     * control points computed per segment and emits a `C` command per bend; at a
+     * zoom where the whole edge is a few dozen pixels the curve and its chord are
+     * the same handful of pixels, so the arithmetic buys nothing.
+     *
+     * Orthogonal stays orthogonal — its right angles are its MEANING (a flowchart
+     * that goes diagonal at low zoom has changed what it says, not how finely it
+     * says it), and the orthogonal emitter is a cheap `L` walk anyway.
+     */
+    private pathTypeForLOD;
+    /**
+     * wave8/culling — Card 4. The polyline to DRAW at this tier.
+     *
+     * Below the `link-detail` tier the path is run through the engine's
+     * `PathSimplifier` (Douglas–Peucker) with a tolerance of one SCREEN pixel —
+     * `1 / zoom` world units, so the tolerance tightens as you zoom in and the
+     * simplification silently retires itself. A bend the user cannot resolve is a
+     * `L` command, a VNode diff and a DOM attribute for nothing.
+     *
+     * The DRAWN path only. `link.points` keeps the true geometry (see the call
+     * site) — hit-testing, link bounds and the spatial index must not be told a
+     * simplification is the truth.
+     *
+     * A route that is already 2 points (which is what `computeCoarseRoute` emits,
+     * so: the common far-zoom case) short-circuits without allocating.
+     */
+    private pathForLOD;
+    /**
+     * Calculate distance between two points
+     */
+    private distance;
+    /**
+     * Generate SVG path segment with rounded bend
+     * Based on React Flow's getBend function from smoothstep-edge.ts
+     */
+    private getBend;
+    /**
+     * Convert orthogonal path to SVG with rounded corners
+     * Implements React Flow's smoothstep edge rendering
+     */
+    private convertOrthogonalPathWithBends;
+    /** Built-in bend radius per path type (React Flow's smoothstep default = 5). */
+    private defaultCornerRadius;
+    /**
+     * The bend radius a link asks for. Unset (or non-finite/negative) → the
+     * built-in default for its path type, so untouched links render byte-identical
+     * to before this knob existed. `getBend` clamps every corner to half the
+     * shorter adjacent segment, so any radius is geometrically safe.
+     */
+    private resolveCornerRadius;
+    /**
+     * Smooth/bezier control-point offset, honouring `style.curvature` (a
+     * multiplier of the endpoint distance; default 0.5 = the legacy factor).
+     * The historical 100px cap scales with the multiplier so curvature 0.5 is
+     * exactly the old `Math.min(distance / 2, 100)`.
+     */
+    private controlDistanceFor;
+    /** The 2-point smooth/bezier control arms — one implementation for the drawn
+     *  path AND the hit polyline. */
+    private smoothControlPoints;
+    /**
+     * The polyline the INTERACTION layer should measure — the PAINTED geometry,
+     * flattened.
+     *
+     * `link.points` used to hold the ROUTE (for a 2-point smooth link: the bare
+     * chord) while the drawn path is a direction-aware cubic that bows up to
+     * ~25 world units away from it. Every consumer of `link.points` — the body
+     * hit test, hover, label anchors, waypoint-insertion t, the edge toolbar's
+     * midpoint — was measuring a line the user cannot see: on dagre-tree's
+     * fan-out edges only ~12-20% of the painted length accepted a click, with
+     * a dead band at the apex wider than the stroke itself (live report:
+     * "not always so easy to select the line on all its points"; investigator-
+     * quantified). Flattening at 16 steps per cubic mirrors the Canvas
+     * backend's own pick flattening (path-geometry.flattenPath), which already
+     * measured the painted commands — the two backends now agree by
+     * construction.
+     */
+    /**
+     * Sync `link.points` from a ROUTE via the painted geometry, not the raw
+     * polyline. Every sync site must go through here: the routing pre-pass
+     * re-syncs every routed link EVERY frame, so a flatten done only in
+     * renderLink is overwritten right back to the chord on the next frame —
+     * which is exactly the bug this exists to prevent (smooth 2-point links
+     * bow ~25px off their chord; hit-testing, hover, labels, toolbars and
+     * bounds all measure link.points).
+     */
+    private syncPaintedLinkPoints;
+    private paintedHitPolyline;
+    /**
+     * Convert RoutedPath to SVG path string
+     *
+     * Wave 3: `style` carries the link's per-link path-shape knobs (cornerRadius,
+     * curvature). Omitted by the connection/reconnection previews, which have no
+     * link style yet — they keep the built-in defaults.
+     */
+    private convertRoutedPathToSVG;
+    /**
+     * Render single link (Option 2: Enhanced with arrows and labels)
+     */
+    private renderLink;
+    /**
+     * Wave 4 (Edges & links) — Card 5: run this link's registered template, if it
+     * named one. Returns null when the link has no template, when the name is not
+     * registered, or when the template opted out by returning null — in every one
+     * of those cases the link falls back to the built-in rendering rather than
+     * vanishing.
+     */
+    private renderLinkTemplate;
+    /**
+     * Assemble the per-frame `<defs>` VNode from the registered paint servers.
+     * Empty (`<defs/>`) when nothing needed a paint server this frame.
+     */
+    private buildDefsNode;
+    /**
+     * Resolve a fill/stroke value to something an SVG `fill`/`stroke` accepts.
+     * A colour string passes through unchanged; a gradient/pattern SPEC OBJECT is
+     * registered as a deduped `<defs>` entry and returned as `url(#grafloria-def-…)`.
+     */
+    private resolvePaint;
+    private resolveFill;
+    private resolveStroke;
+    /**
+     * Resolve a `style.shadow` value to a `filter` attribute. The legacy boolean
+     * is ignored here (its always-on drop-shadow VNode is unchanged); a Shadow
+     * SPEC OBJECT registers a deduped `<filter>` and returns `url(#grafloria-def-…)`.
+     */
+    private resolveShadowFilter;
+    /**
+     * A node/link whose RESOLVED style references a paint server must NOT be
+     * served from (or written to) the vnode cache: the cached VNode carries the
+     * url(#…) reference, but the matching `<defs>` entry is only registered while
+     * the style is (re)computed — a cache hit would skip that and orphan the ref.
+     *
+     * RESOLVED, not raw: a gradient/pattern/shadow can now also arrive from a
+     * named style or a theme type-default, not just from the entity's own style.
+     */
+    private nodeUsesPaintServer;
+    private linkUsesPaintServer;
+    /**
+     * wave8/culling — Card 4. Whether THIS frame emits paint servers at all.
+     *
+     * THE INVARIANT: when this is false, NOTHING registers a `<defs>` entry —
+     * `resolvePaint` returns a flat colour and `resolveShadowFilter` returns
+     * undefined. They are the only two producers. So no VNode built this frame can
+     * hold a `url(#…)`, and the cache-bypass that exists purely to keep such a ref
+     * from being orphaned has nothing left to protect — which is precisely what
+     * lets a gradient-heavy scene use the VNode cache at far zoom instead of
+     * rebuilding every gradient node from scratch on every frame.
+     *
+     * Both producers must stay gated on THIS predicate. Gate one and not the other
+     * and you get the original bug back: a cached VNode pointing at a def that was
+     * never emitted.
+     */
+    private paintServersActive;
+    /**
+     * The cascade's answer for a node, with every `themeRef` turned into something
+     * paintable and the entity's theme-boundness recorded.
+     *
+     * A node is theme-BOUND (i.e. a theme swap must restyle it) when it froze a
+     * theme literal into its VNode. Three sources, all detected here rather than
+     * assumed:
+     *   - `theme.nodes[type]` supplied a type-default,
+     *   - the STATE layer painted it (selected/highlighted/hovered/disabled/error),
+     *   - a `themeRef` had to be baked to a literal (see materializeThemeRefs).
+     */
+    private resolvedNodeStyle;
+    private resolvedLinkStyle;
+    /**
+     * Compute node styles for CSS mode
+     */
+    private computeNodeStylesCSS;
+    /**
+     * Compute node styles for programmatic mode
+     */
+    private computeNodeStylesProgrammatic;
+    /**
+     * Compute link styles for CSS mode
+     */
+    private computeLinkStylesCSS;
+    /**
+     * Compute link styles for programmatic mode
+     */
+    private computeLinkStylesProgrammatic;
+    /**
+     * Generate SVG path data from points and segments
+     * Supports both straight lines and bezier curves
+     *
+     * Wave 3: takes the link's `style` so a MANUAL-WAYPOINT path honours the same
+     * per-link cornerRadius as an auto-routed one (the two path-emitting branches
+     * of renderLink must not disagree about a link's corners).
+     */
+    private generatePathData;
+    /**
+     * Grow the viewport before asking the engine which links intersect it.
+     *
+     * The link SpatialIndex is indexed on the link's straight-line endpoints plus
+     * whatever route was last written back to `link.points`. A link that has never
+     * been drawn (or that was re-routed around a new obstacle this very frame) can
+     * bulge OUTSIDE that box: the detour lives in this renderer's per-frame
+     * `frameRoutes` map and only lands in `link.points` once the link renders.
+     *
+     * Padding the query region by a margin makes the query a superset, so a link
+     * whose detour swings into view is never culled a frame too early. Culling a
+     * little too little costs a handful of VNodes; culling too much makes edges
+     * blink out of existence.
+     */
+    private expandForLinkCulling;
+    /**
+     * Create empty diagram VNode
+     */
+    private createEmptyDiagram;
+    /**
+     * Inject this renderer's CSS.
+     *
+     * TWO stylesheets, deliberately:
+     *   1. the SHARED rules (`generateBaseStyleSheet()` + the animation CSS) —
+     *      theme-INDEPENDENT, written in `var(--grafloria-*)`, injected once per
+     *      document and deduped by `GRAFLORIA_BASE_STYLE_ID`;
+     *   2. this instance's VARIABLE BLOCK — `[data-grafloria-instance="grafloria-3"] { … }`
+     *      in a `<style>` element whose id carries the instance id.
+     *
+     * That split is the fix: the old scheme keyed the element by THEME NAME and
+     * re-emitted every rule with hex literals, so a second diagram with a second
+     * theme repainted the first one, and disposing either renderer could remove
+     * the other's stylesheet.
+     */
+    private injectThemeCSS;
+    /**
+     * This instance's OVERRIDE block: the host's design tokens, then the
+     * accessibility media queries. Always present in CSS mode — even with no
+     * bridge, because `prefers-contrast` and `forced-colors` are the FLOOR every
+     * diagram gets, not an opt-in.
+     */
+    private injectOverrideCSS;
+    /**
+     * Inject the shared, theme-independent rules once per document. Every
+     * renderer feeds the same rules from its own variable block.
+     */
+    private ensureBaseStyleSheet;
+    /** Drop the shared rules once the LAST instance's variable block is gone. */
+    private releaseBaseStyleSheet;
+    /**
+     * This renderer's theme CSS: the VARIABLE BLOCK, and nothing else.
+     *
+     * The rules that consume these variables are theme-independent and live in
+     * the shared stylesheet (theme-css.ts). This block is the ONLY place a
+     * theme's values are written, and it is scoped to this diagram's root — which
+     * is what lets two diagrams with different themes coexist on one page.
+     */
+    private generateThemeCSS;
+    /**
+     * The animation service — global animation enable/speed, reduced-motion and
+     * battery-saver policy. Public because these are HOST decisions: the service
+     * existed with a full config surface and no accessor, so nothing outside
+     * this class could e.g. opt out of the battery auto-toggle
+     * (`respectBatteryStatus: false`) — a laptop under 20% silently killed every
+     * edge animation with no way back.
+     */
+    getAnimationService(): AnimationService;
+    /**
+     * Generate animation CSS
+     * Phase 1: Includes edge animations, node border animations, and status animations
+     */
+    private generateAnimationCSS;
+    /**
+     * Subscribe to engine events
+     */
+    private subscribeToEngineEvents;
+    /**
+     * Start FPS tracking
+     */
+    private startFPSTracking;
+    /**
+     * Estimate memory usage
+     */
+    private estimateMemoryUsage;
+    /**
+     * Calculate intersection point between a line segment and a rectangle
+     * Used to position arrows at node boundaries instead of port centers
+     */
+    private calculateLineRectIntersection;
+    /**
+     * Calculate the tangent angle at the end of a bezier curve
+     * For a cubic bezier curve, the tangent at t=1 (endpoint) is determined by
+     * the direction from the second control point (cp2) to the endpoint
+     *
+     * @param cp2 Second control point of the bezier curve
+     * @param endpoint End point of the bezier curve
+     * @returns Angle in degrees
+     */
+    private calculateBezierEndTangent;
+    /**
+     * Get perpendicular angle from port side
+     * Used for orthogonal routing to ensure arrows are perpendicular to node edges
+     *
+     * @param portSide Port side ('left' | 'right' | 'top' | 'bottom')
+     * @returns Angle in degrees pointing away from the node
+     */
+    private getPerpendicularAngleFromPortSide;
+    /**
+     * Calculate arrow direction based on routing algorithm and path geometry
+     * Implements research-based best practices for each algorithm type
+     *
+     * @param algorithm Routing algorithm used
+     * @param pathType Path type (bezier, smooth, straight, etc.)
+     * @param points Path points
+     * @param portSide Port side for orthogonal routing (optional)
+     * @returns Angle in degrees
+     */
+    private calculateArrowDirection;
+    /**
+     * Calculate arrow position and angle for a link endpoint
+     * Handles both source and target ends with algorithm-aware direction calculation
+     *
+     * @param link Link model
+     * @param points Path points
+     * @param isTarget True for target end, false for source end
+     * @param arrowLength Length of arrow in pixels
+     * @returns Object with position and angle
+     */
+    private calculateArrowPositionAndAngle;
+    /**
+     * HIGH-PERFORMANCE: Create simple orthogonal segment between two points
+     * Uses 3-point path: start -> corner -> end
+     * Much faster than calling routing engine
+     */
+    private createOrthogonalSegment;
+    /**
+     * Wave 3 (Edges & links) — "jumps win over an oversized corner radius".
+     *
+     * buildPathWithJumps derives each segment's legal cut window from the corner
+     * bends: `lo = bendPrev + 1`, `hi = segLen - bendNext - 1`. A big per-link
+     * cornerRadius eats that window from both ends, so a jump-carrying segment
+     * could silently lose its jump (`hi - lo < 3`).
+     *
+     * So: on segments that actually host a crossing, cap the radius at the value
+     * that still leaves a full `size`-wide window —
+     *   bendPrev + bendNext <= 2R  ⇒  R <= (segLen - 2 - reserves - size) / 2
+     * — and NEVER tighten below the built-in default. Consequences:
+     *   • a link at (or below) the default radius is bit-for-bit unchanged;
+     *   • a large radius degrades toward the default only as far as the jumps
+     *     need, instead of dropping arcs;
+     *   • a segment too short for any jump at the DEFAULT radius keeps today's
+     *     behaviour (the `hi - lo < 3` guard drops that one cut).
+     */
+    private cornerRadiusForJumps;
+    /**
+     * Build the link path from its polyline with jump geometry inserted.
+     *
+     * Works on the SAME point array the detector indexed (never re-parses the
+     * rendered path string, whose rounded corners would shift segment indices).
+     * Cuts ±size/2 around each crossing so the rendered jump is exactly `size`
+     * wide, merges overlapping cuts, keeps cuts clear of corner bends, and uses
+     * a constant sweep so every arc on a link bulges to the same side of travel.
+     */
+    private buildPathWithJumps;
+    /**
+     * Manual waypoints are an explicit editor action (flagged via metadata by the
+     * interaction layer), never inferred from point count — auto-routed
+     * orthogonal paths also have >2 points.
+     */
+    private linkHasManualWaypoints;
+    /**
+     * Keep link.points in sync with the rendered route on every frame so hit
+     * testing and jump-point detection see current geometry. Direct assignment
+     * (no setPoints) to avoid emitting link:changed and re-render loops.
+     *
+     * That silence is also why we re-index the link by hand: the diagram's link
+     * SpatialIndex — which now drives viewport culling — only hears about geometry
+     * through events, so without this its grid cells would still describe the route
+     * the link had when it was added, and a detoured link could be culled.
+     */
+    private syncLinkPoints;
+    /**
+     * Compute the auto route for a link.
+     *
+     * pathType determines the base routing algorithm ('orthogonal' → orthogonal
+     * router; direct/smooth/bezier → straight router). If a straight route would
+     * cross the link's own nodes (inverted geometry) or any obstacle, it falls
+     * back to the orthogonal router, which respects port directions and A*
+     * obstacle avoidance — links must never run through node bodies.
+     */
+    /**
+     * Wave 5 — Card 6: the group facts a route needs. Pure derivation from the
+     * diagram's group state; feature-tolerant (a diagram with no groups pays one
+     * empty array read).
+     */
+    private collectGroupRouting;
+    /**
+     * Wave 8 — Card 6: the frame's obstacle arrays, built ONCE.
+     *
+     * `computeAutoRoute` used to rebuild these per link: `getNodes()`, a filter, a
+     * map — O(nodes) allocations for every link it routed, every frame. On the 10k
+     * benchmark that is 10,000 objects × ~700 visible links = 7 million throwaway
+     * rects per frame, before any routing happened at all.
+     *
+     * Two arrays, because the router needs two different sets:
+     *   `routing` — what a link routes AGAINST (minus collapsed-away members);
+     *   `all`     — every node, used by the own-node penetration fallback.
+     *
+     * The ARRAY IDENTITY matters as much as the contents: `RoutingEngine` memoises
+     * its merged obstacle set and spatial index on it, so handing every link the
+     * same array is what collapses N index builds into one.
+     *
+     * NOTE ON THE SOURCE/TARGET EXCLUSION — read before "fixing" this. The old
+     * per-link build filtered the link's own two nodes out of the obstacle array.
+     * That filter never did anything: `RoutingEngine.route()` unions the request's
+     * obstacles with its GLOBAL obstacle map, and `DiagramEngine` registers every
+     * node in that map, so both endpoint nodes came straight back in. Dropping the
+     * filter is therefore behaviour-preserving (the union is identical), which is
+     * why the 225-assertion line harness does not move.
+     *
+     * It is also a LATENT BUG, and a big one: because a link's own endpoints are
+     * obstacles, the straight port-to-port path "collides" for essentially every
+     * link, so essentially every link falls through to A* obstacle avoidance —
+     * measured at 72/72 links on the benchmark scene. Making the exclusion real
+     * would move routes across the whole product and is a routing-semantics
+     * decision, not a performance one. Left as found, and now documented.
+     */
+    private frameObstacles;
+    /**
+     * The obstacle array this link routes against — the frame's shared array in
+     * the overwhelming majority of cases.
+     *
+     * The one link that cannot use it is a PROXY LINK whose endpoint IS a collapsed
+     * group: that link must not treat its own group block as a wall. Rare enough
+     * to pay for a private array, and the group-block exclusion (unlike the node
+     * one above) is worth preserving because a block is not necessarily in the
+     * engine's global map.
+     */
+    private obstaclesForLink;
+    /**
+     * Card 4. The route for this link AT THIS TIER: the real one when the tier
+     * renders `routing`, a direct polyline when it does not.
+     *
+     * The single door both the pre-pass and `renderLink`'s fallback go through, so
+     * the two can never disagree about which geometry a frame is drawing. Note that
+     * the pre-pass memoises AROUND this call and keys on `routingAllowed` — see
+     * `routeKey`: the two routers are indistinguishable by their inputs alone.
+     */
+    private routeForLOD;
+    /**
+     * The far-zoom route: a straight line from port to port. O(1).
+     *
+     * `computeAutoRoute` builds an obstacle rectangle for EVERY node in the diagram
+     * for EVERY link, then searches against them — O(nodes) per edge, O(nodes x
+     * edges) per frame. Measured on the Wave-8 benchmark that is 96% of a 1k frame
+     * and 99% of a 5k one, and it is the whole of the 63-second 10k zoom-out.
+     *
+     * What it buys is a route that dodges node bodies. At the tiers this runs at,
+     * a node body is a smudge and the dodge is sub-pixel — so we do not buy it.
+     *
+     * SELF-LOOPS still loop. `computeSelfLoopRoute` never touches the routing
+     * engine (it is pure geometry, O(1) in the obstacle count), and a self-loop
+     * flattened to a straight line degenerates into a stub inside its own node —
+     * i.e. it would visually DISAPPEAR, which is a correctness loss, not a
+     * fidelity one. Cheap work that keeps an edge visible is work worth doing.
+     */
+    private computeCoarseRoute;
+    private computeAutoRoute;
+    /**
+     * Shortest way OUT of whatever node bodies cover the point (used when a
+     * port is buried inside the peer node because the two bodies overlap).
+     * Marches the four axis rays and returns the nearest point that is outside
+     * every covering body, with a small clearance.
+     */
+    private shortestEscape;
+    private frameSmartSides;
+    /**
+     * Point on the node's VISIBLE outline for a floating smart attachment:
+     * the given side at the given cross-axis coordinate (world). Rects use the
+     * bounding-box edge; ellipse/circle project analytically and hexagon/diamond
+     * intersect the outline polygon, so the line never hovers off the drawn shape.
+     */
+    private shapeEdgePoint;
+    /**
+     * The VISIBLE port on the given side closest to the ideal attachment point,
+     * or null when the node shows no ports there (visibility resolves through
+     * port config → node metadata → the global interaction strategy; only
+     * 'always' counts — hover-revealed ports must not flip attachment mid-drag).
+     */
+    private nearestVisiblePort;
+    /**
+     * The nearest port on a side regardless of visibility — the 'port-facing'
+     * strategy's anchor source. Visibility must not steer ATTACHMENT: ports are
+     * the node's connection anatomy whether or not their glyphs are drawn, and an
+     * endpoint that jumps when a hover reveals them is worse than either state.
+     */
+    private nearestPortOnSide;
+    /**
+     * The link's own endpoint nodes (resolved via cached ids or port search).
+     */
+    private linkOwnNodes;
+    /**
+     * Smooth cubic spline (Catmull-Rom) through every route point — used so a
+     * smooth/bezier link keeps its curved identity on multi-point detours
+     * instead of visually turning into an orthogonal link.
+     */
+    private catmullRomPath;
+    /**
+     * Sample the Catmull-Rom spline into a polyline (for penetration checks —
+     * the spline can overshoot corners beyond the route's own points).
+     */
+    private sampleCatmullRom;
+    /**
+     * Total length of the polyline that lies inside the given node bodies
+     * (rects inset by 1px so port-touch on the border doesn't count).
+     */
+    private penetrationLength;
+    /**
+     * Make an "orthogonal" route strictly orthogonal:
+     * 1. absorb near-miss elbows into the exact endpoint axes (grid-snapped
+     *    elbows sit up to gridSize/2 off the port, producing slanted stubs),
+     * 2. split any remaining diagonal segment with a corner point,
+     * 3. merge collinear runs, which also removes out-and-back retraces.
+     */
+    private rectifyOrthogonalRoute;
+    /**
+     * True if any polyline segment passes through a node body. Node rects are
+     * inset by 1px so a path legitimately touching the border at a port doesn't
+     * count as a crossing.
+     */
+    /**
+     * Motion-stable routing: split the frame's obstacle nodes into the ones at
+     * rest and the ones mid-animation. Memoised on the node ARRAY's identity —
+     * `frameObstacles` hands every link the same array within a frame, so the
+     * partition is computed once per frame, not once per link.
+     */
+    private motionPartition;
+    private routeCrossesNodes;
+    /**
+     * Segment/rect intersection via Liang-Barsky clipping.
+     */
+    private segmentIntersectsRect;
+    /**
+     * Liang-Barsky segment/rect clip — returns the parametric interval of the
+     * segment that lies inside the rect, or null if it misses entirely.
+     */
+    private segmentRectClip;
+}