@grafloria/element 0.3.18 → 0.3.19

package/src/libs/renderer/src/lazy/host-culling.d.ts

@@ -0,0 +1,116 @@
+import type { Rectangle } from '../types/geometry.types';
+import type { EntityKind } from './types';
+/**
+ * What a cull does to the host element.
+ *
+ * `'detach'` — remove the element from the document and keep the reference. Re-entry
+ * re-appends the SAME element: `renderCustomNode` is NOT called again, `removeCustomNode`
+ * is NOT called on the cull, and everything inside the widget survives byte for byte.
+ *
+ * `'destroy'` — fire `removeCustomNode` and drop the element. Re-entry re-creates the host
+ * and re-runs `renderCustomNode`. Frees the widget's memory; costs a full re-init and every
+ * piece of state the widget was holding.
+ *
+ * `'detach'` is the default, and the reasoning is that the cost this feature exists to
+ * remove is a cost of being ATTACHED. Layout, style recalc, paint, compositing and hit
+ * testing are all charged per element IN THE DOCUMENT; a detached subtree is inert heap.
+ * Detaching therefore captures essentially the whole win while keeping the mount-once
+ * guarantee that makes custom nodes usable at all. Measured on a 300-widget board with ~16
+ * tiles on screen: 2720 DOM nodes under the canvas fall to 164, a 94% reduction, and a pan
+ * away and back re-runs the painter exactly zero times.
+ *
+ * What `'detach'` does NOT bound is the RETAINED set. A host mounted once is kept for the
+ * life of the instance, so panning a 10,000-widget board end to end eventually holds 10,000
+ * detached elements — the same "cache versus leak" distinction `ViewLifecycle`'s header
+ * draws about autoFreeze, and the honest reason `'destroy'` exists. (Same board, after a
+ * sweep across and back: 20 attached, 78 retained off-screen.) Choose `'destroy'` when the
+ * widgets are individually huge — a WebGL scene, a 50k-row grid — and heap rather than
+ * frame time is the binding constraint. It is opt-in inside an opt-in, because a host that
+ * asks for it is accepting that its painter re-runs and its widget state is lost.
+ */
+export type HostCullMode = 'detach' | 'destroy';
+export interface HostCullOptions {
+    /**
+     * How far beyond the viewport edge a host is still kept mounted, in CSS pixels.
+     *
+     * Screen pixels, not world units, and converted by the current zoom — the question this
+     * answers is "how much scrolling until the user sees it", which is a physical distance.
+     * A world-unit margin would be 20 screen px at zoom 0.1 (a tile pops in visibly late) and
+     * 2000 at zoom 10 (the cull stops culling). Same reasoning the resize handles use.
+     */
+    margin?: number;
+    /**
+     * The extra distance, in CSS pixels, a host must travel BEYOND `margin` before it is
+     * culled. This is the hysteresis band, and it is the difference between culling and
+     * thrashing.
+     *
+     * With a single threshold, a tile whose edge sits exactly on the boundary flips
+     * mounted/unmounted on sub-pixel camera jitter — a trackpad's inertial tail, a spring
+     * animation settling, a resize observer firing twice. In `'destroy'` mode that is a
+     * widget re-initialising several times a second; in `'detach'` mode it is still a DOM
+     * mutation and a style recalc per frame, i.e. the exact cost we came to remove.
+     *
+     * Two thresholds make a flip require REAL movement: attach at `margin`, detach only past
+     * `margin + hysteresis`. Nothing in between can change state.
+     */
+    hysteresis?: number;
+    /** What a cull does to the element. Default `'detach'` — see {@link HostCullMode}. */
+    mode?: HostCullMode;
+}
+/**
+ * The sliver of `ViewLifecycle` that host culling honours.
+ *
+ * `isExplicitlyFrozen`, NOT `admits`, and the distinction is load-bearing. `admits` is also
+ * false for anything autoFreeze is holding off-screen, and autoFreeze decides that against
+ * the bare viewport with no margin — routing custom hosts through it would silently
+ * override the hysteresis band with a zero-width one. `isExplicitlyFrozen` is the signal
+ * that a HOST deliberately said "this node has no view", which is a decision custom nodes
+ * should obey.
+ */
+export interface FreezeQuery {
+    isExplicitlyFrozen(kind: EntityKind, id: string): boolean;
+}
+/**
+ * The per-frame cull decision for HTML-layer node hosts.
+ *
+ * Stateless with respect to the hosts themselves: `admits()` is told whether the host is
+ * currently attached rather than remembering it. That is on purpose — a culler holding its
+ * own attached-set is a second copy of a fact the DOM already owns, and the two desync the
+ * first time a node is removed from the model mid-gesture. The DOM is the record; this is
+ * only the policy.
+ *
+ *     culler.beginFrame(viewport.getViewBox(), viewport.getZoom(), heldByGesture);
+ *     for (const node of customNodes) {
+ *       if (culler.admits(node.id, bounds(node), host?.isConnected ?? false)) …
+ *     }
+ */
+export declare class HtmlHostCuller {
+    private readonly marginPx;
+    private readonly hysteresisPx;
+    private readonly mode;
+    private readonly freeze;
+    /** Inflated by `margin` — a detached host inside this gets attached. */
+    private attachRect;
+    /** Inflated by `margin + hysteresis` — an attached host outside this gets culled. */
+    private detachRect;
+    private exempt;
+    constructor(options?: HostCullOptions, freeze?: FreezeQuery | null);
+    getMode(): HostCullMode;
+    /**
+     * Fix this frame's two rects and the set of nodes a live gesture owns.
+     *
+     * `visible` is the WORLD rect actually on screen — the viewBox, not the raw camera rect.
+     * They diverge the moment zoom != 1, and culling against the camera rect drops hosts that
+     * are on screen whenever the board is zoomed out (which fit-to-content always does). The
+     * SVG side learned this the hard way; see `svg-renderer.ts` `visibleRect`.
+     */
+    beginFrame(visible: Rectangle, zoom: number, exempt: ReadonlySet<string>): void;
+    /**
+     * Should this node's host be in the document on this frame?
+     *
+     * @param attached whether the host is in the document RIGHT NOW — this is what selects
+     *   which of the two hysteresis rects applies, and it is why a host hovering on the
+     *   boundary keeps whatever state it already had.
+     */
+    admits(id: string, bounds: Rectangle, attached: boolean): boolean;
+}

package/src/libs/renderer/src/lazy/host-culling.js

@@ -0,0 +1,135 @@
+"use strict";
+// Custom (HTML-layer) node hosts: the one thing on the canvas that was NEVER culled.
+//
+// The SVG layers have culled against the visible rect since wave 2 — open a 10k-node
+// diagram and ~56 nodes get a VNode. The HTML layer did the opposite: `syncCustomNodes`
+// walked EVERY `useHTMLLayer` node every frame, created a host for each on first sight,
+// and then kept it in the document forever. A 400-widget dashboard with three tiles on
+// screen paid for 400 absolutely-positioned divs — style recalc, layout, paint,
+// compositing, hit-testing — plus 400 `setAttribute('style', …)` writes PER FRAME, to
+// place 397 elements nobody could see.
+//
+// WHY THIS IS NOT `ViewLifecycle`, having read `ViewLifecycle` first.
+//
+// The obvious move is to reuse the freeze machinery next door, and it is the wrong one.
+// `ViewLifecycle`'s contract is stated in its own header: "a frozen entity is not routed,
+// not styled, not turned into a VNode, and holds no cache entry" — freeze means DESTROY
+// THE VIEW AND REBUILD IT LATER. That is exactly right for a VNode, which is a pure
+// function of the model and costs microseconds to rebuild. It is exactly wrong for a
+// custom host, whose whole documented property is that `renderCustomNode` "mounts exactly
+// once": the host owns a chart mid-animation, a scroll offset, a `<video>`'s playback
+// position, a canvas bitmap, an editor's uncommitted text. Rebuilding that on every scroll
+// is worse than never culling at all.
+//
+// So the POLICY here is new — it has to be. The AUTHORITY is not duplicated: a host that
+// installs a `ViewLifecycle` and explicitly freezes a node gets its custom host released
+// too (see `FreezeQuery`), so "this entity has no view" stays one idea with one owner
+// rather than two systems that can disagree.
+//
+// Deliberately NOT wired to autoFreeze. autoFreeze's diff is exact-rect and per-frame,
+// which is correct for a cache entry and would defeat the hysteresis below — the single
+// property that stops a tile at the viewport edge from thrashing. A rebuildable VNode can
+// afford to flap; a mounted widget cannot.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HtmlHostCuller = void 0;
+const DEFAULT_MARGIN = 200;
+const DEFAULT_HYSTERESIS = 100;
+/**
+ * The per-frame cull decision for HTML-layer node hosts.
+ *
+ * Stateless with respect to the hosts themselves: `admits()` is told whether the host is
+ * currently attached rather than remembering it. That is on purpose — a culler holding its
+ * own attached-set is a second copy of a fact the DOM already owns, and the two desync the
+ * first time a node is removed from the model mid-gesture. The DOM is the record; this is
+ * only the policy.
+ *
+ *     culler.beginFrame(viewport.getViewBox(), viewport.getZoom(), heldByGesture);
+ *     for (const node of customNodes) {
+ *       if (culler.admits(node.id, bounds(node), host?.isConnected ?? false)) …
+ *     }
+ */
+class HtmlHostCuller {
+    constructor(options = {}, freeze = null) {
+        var _a, _b, _c;
+        /** Inflated by `margin` — a detached host inside this gets attached. */
+        this.attachRect = { x: 0, y: 0, width: 0, height: 0 };
+        /** Inflated by `margin + hysteresis` — an attached host outside this gets culled. */
+        this.detachRect = { x: 0, y: 0, width: 0, height: 0 };
+        this.exempt = new Set();
+        // `?? `, not `||`: `margin: 0` is a legitimate ask ("cull at the exact edge") and must
+        // not silently become 200.
+        this.marginPx = Math.max(0, (_a = options.margin) !== null && _a !== void 0 ? _a : DEFAULT_MARGIN);
+        this.hysteresisPx = Math.max(0, (_b = options.hysteresis) !== null && _b !== void 0 ? _b : DEFAULT_HYSTERESIS);
+        this.mode = (_c = options.mode) !== null && _c !== void 0 ? _c : 'detach';
+        this.freeze = freeze;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * Fix this frame's two rects and the set of nodes a live gesture owns.
+     *
+     * `visible` is the WORLD rect actually on screen — the viewBox, not the raw camera rect.
+     * They diverge the moment zoom != 1, and culling against the camera rect drops hosts that
+     * are on screen whenever the board is zoomed out (which fit-to-content always does). The
+     * SVG side learned this the hard way; see `svg-renderer.ts` `visibleRect`.
+     */
+    beginFrame(visible, zoom, exempt) {
+        // A zero or negative zoom is not a real camera state, but it IS reachable through a
+        // host that drives `setZoom` from a slider mid-animation, and dividing by it would
+        // produce an infinite rect (everything mounted) or a NaN one (nothing mounted, and no
+        // way to get back — NaN comparisons are false in both directions, so the hysteresis
+        // would latch). Fall back to 1 rather than propagate it.
+        const z = zoom > 0 && Number.isFinite(zoom) ? zoom : 1;
+        this.attachRect = inflate(visible, this.marginPx / z);
+        this.detachRect = inflate(visible, (this.marginPx + this.hysteresisPx) / z);
+        this.exempt = exempt;
+    }
+    /**
+     * Should this node's host be in the document on this frame?
+     *
+     * @param attached whether the host is in the document RIGHT NOW — this is what selects
+     *   which of the two hysteresis rects applies, and it is why a host hovering on the
+     *   boundary keeps whatever state it already had.
+     */
+    admits(id, bounds, attached) {
+        var _a;
+        // An explicit freeze outranks everything, including a gesture: a host that froze this
+        // node did so on purpose, and it is not this culler's place to overrule it. (Same
+        // precedence ViewLifecycle.admits gives an explicit freeze over a mount admission.)
+        if ((_a = this.freeze) === null || _a === void 0 ? void 0 : _a.isExplicitlyFrozen('node', id))
+            return false;
+        // A node under a live gesture is never culled. Mostly it is on screen anyway — it is
+        // under the user's cursor — but not always: a drag can carry a tile past the edge, an
+        // auto-panning canvas can move the viewport out from under it, and a dashboard's
+        // placeholder reflow moves tiles the user is not touching. Unmounting the element
+        // mid-drag destroys the pointer capture, the ghost, and the gesture with it.
+        if (this.exempt.has(id))
+            return true;
+        return intersects(bounds, attached ? this.detachRect : this.attachRect);
+    }
+}
+exports.HtmlHostCuller = HtmlHostCuller;
+/** Grow a rect by `pad` on all four sides. */
+function inflate(r, pad) {
+    return {
+        x: r.x - pad,
+        y: r.y - pad,
+        width: r.width + pad * 2,
+        height: r.height + pad * 2,
+    };
+}
+/**
+ * Overlap test, inclusive of touching edges.
+ *
+ * Inclusive because the alternative is a one-pixel band in which a host that is provably
+ * adjacent to the mount region is culled anyway; at the attach threshold that reads as a
+ * tile popping in one frame late, every time.
+ */
+function intersects(a, b) {
+    return !(a.x + a.width < b.x ||
+        b.x + b.width < a.x ||
+        a.y + a.height < b.y ||
+        b.y + b.height < a.y);
+}
+//# sourceMappingURL=host-culling.js.map

package/src/libs/renderer/src/lazy/host-culling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-culling.js","sourceRoot":"","sources":["../../../../../../renderer/src/lazy/host-culling.ts"],"names":[],"mappings":"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"}

package/src/libs/renderer/src/lazy/index.d.ts

@@ -0,0 +1,7 @@
+export { ViewLifecycle } from './view-lifecycle';
+export type { ViewLifecycleOptions } from './view-lifecycle';
+export { ProgressiveMounter } from './progressive-mounter';
+export type { DeferredQuery, MountFrame, ProgressiveMountOptions, } from './progressive-mounter';
+export type { EntityKind, MountGate, MountStats } from './types';
+export { HtmlHostCuller } from './host-culling';
+export type { FreezeQuery, HostCullMode, HostCullOptions } from './host-culling';

package/src/libs/renderer/src/lazy/index.js

@@ -0,0 +1,28 @@
+"use strict";
+// Wave 8 — Card 3: deferred / lazy view instantiation, freeze, and the
+// time-sliced async mount that keeps a 10k-node graph from freezing the tab for
+// 6.8 seconds before it shows the user anything.
+//
+//     const lifecycle = new ViewLifecycle({ autoFreeze: true });
+//     renderer.setViewLifecycle(lifecycle);
+//
+//     const mounter = new ProgressiveMounter(
+//       engine,
+//       lifecycle,
+//       (vp, zoom) => patcher.reconcile(svg, renderer.render(vp, zoom)),
+//       () => renderer.getDeferredEntities()
+//     );
+//     await mounter.mount(viewport, 1);   // paints in ~5ms, fills in over rAF slices
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HtmlHostCuller = exports.ProgressiveMounter = exports.ViewLifecycle = void 0;
+var view_lifecycle_1 = require("./view-lifecycle");
+Object.defineProperty(exports, "ViewLifecycle", { enumerable: true, get: function () { return view_lifecycle_1.ViewLifecycle; } });
+var progressive_mounter_1 = require("./progressive-mounter");
+Object.defineProperty(exports, "ProgressiveMounter", { enumerable: true, get: function () { return progressive_mounter_1.ProgressiveMounter; } });
+// Viewport culling for CUSTOM (HTML-layer) node hosts — the one layer that was never
+// culled, so a 400-widget board paid for 400 mounted divs to show three. Opt in through
+// `createDiagram({ cullCustomNodes: true })`; the class is exported for hosts that drive
+// the host lifecycle themselves.
+var host_culling_1 = require("./host-culling");
+Object.defineProperty(exports, "HtmlHostCuller", { enumerable: true, get: function () { return host_culling_1.HtmlHostCuller; } });
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/lazy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../renderer/src/lazy/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,gFAAgF;AAChF,iDAAiD;AACjD,EAAE;AACF,iEAAiE;AACjE,4CAA4C;AAC5C,EAAE;AACF,8CAA8C;AAC9C,gBAAgB;AAChB,mBAAmB;AACnB,yEAAyE;AACzE,6CAA6C;AAC7C,SAAS;AACT,sFAAsF;;;AAEtF,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AAGtB,6DAA2D;AAAlD,yHAAA,kBAAkB,OAAA;AAS3B,qFAAqF;AACrF,wFAAwF;AACxF,yFAAyF;AACzF,iCAAiC;AACjC,+CAAgD;AAAvC,8GAAA,cAAc,OAAA"}

package/src/libs/renderer/src/lazy/progressive-mounter.d.ts

@@ -0,0 +1,80 @@
+import type { DiagramEngine } from '@grafloria/engine';
+import type { Rectangle } from '../types/geometry.types';
+import type { EntityKind, MountStats } from './types';
+import type { ViewLifecycle } from './view-lifecycle';
+/**
+ * Produce and PRESENT one frame. Deliberately not "the SVG renderer": the SVG
+ * patcher, the canvas backend and the tier-switching backend all satisfy this, so
+ * a progressive mount works on any of them.
+ */
+export type MountFrame = (viewport: Rectangle, zoom: number) => void;
+/** What the renderer deferred on the last frame — culling admitted it, the gate did not. */
+export type DeferredQuery = () => ReadonlyArray<readonly [EntityKind, string]>;
+export interface ProgressiveMountOptions {
+    /** Target ms per slice. The chunk size adapts to hit it. Default 8 (half a 60fps frame). */
+    sliceMs?: number;
+    /**
+     * Links admitted by the FIRST link slice — the one slice with no measurement to adapt
+     * from. Default 4, deliberately timid: link costs are wildly skewed (a typical link
+     * routes in 3ms, a long one against 10k obstacles in 850ms), so a big opening chunk is
+     * a coin-flip on a multi-second stall. It ramps up fast from here when links are cheap.
+     */
+    initialChunk?: number;
+    /** Hard cap on slices, so a pathological scene still terminates. Default 500. */
+    maxSlices?: number;
+    onFirstPaint?: (stats: Readonly<MountStats>) => void;
+    onSlice?: (stats: Readonly<MountStats>) => void;
+}
+export declare class ProgressiveMounter {
+    private readonly engine;
+    private readonly lifecycle;
+    private readonly frame;
+    private readonly deferred;
+    private handle;
+    private running;
+    /**
+     * Settles the mount currently in flight.
+     *
+     * Held because `cancel()` tears down the rAF that would otherwise have settled
+     * it — without this, cancelling a mount left the caller's `await mount()` hanging
+     * forever. (Found by the spec, which is the only reason it is not still there.)
+     */
+    private settle;
+    constructor(engine: DiagramEngine, lifecycle: ViewLifecycle, frame: MountFrame, deferred: DeferredQuery);
+    isRunning(): boolean;
+    /**
+     * Bring the scene up in rAF-yielded slices. Resolves when everything culling
+     * admits has a view (or when the mount is cancelled).
+     */
+    mount(viewport: Rectangle, zoom: number, options?: ProgressiveMountOptions): Promise<MountStats>;
+    /**
+     * Stop mounting. Whatever is not yet mounted is mounted by the next normal render
+     * — the gate is handed back here, so a cancelled mount can never strand half a
+     * diagram on screen.
+     */
+    cancel(): void;
+    dispose(): void;
+    private teardown;
+    private mountedNodeCount;
+}
+/**
+ * Separate a slice's cost into the part that scales with the work (`marginal`) and the
+ * part the renderer charges regardless (`fixed`).
+ *
+ * We never get to observe either directly — only `fixed + marginal × chunk`, once per
+ * slice, from a noisy clock. So:
+ *
+ *   - `fixed` is tracked as the cheapest per-entity-adjusted floor we have seen. A slice
+ *     can never cost LESS than the fixed cost, so the running minimum converges onto it
+ *     from above and cannot be dragged up by an expensive entity.
+ *   - `marginal` is whatever is left over, averaged with an EWMA so one pathological
+ *     entity (an 850ms link) moves the estimate without defining it.
+ *
+ * Deliberately conservative in one direction: if we UNDER-estimate `fixed`, the chunk
+ * comes out small and the mount is merely slower. If we OVER-estimate it, the chunk comes
+ * out large and a slice janks. Slow is recoverable; jank is what the user sees.
+ */
+export declare function learnFixedCost(fixedMs: number, marginalMs: number, chunk: number, sliceMs: number): {
+    fixedMs: number;
+    marginalMs: number;
+};

package/src/libs/renderer/src/lazy/progressive-mounter.js

@@ -0,0 +1,264 @@
+"use strict";
+// Wave 8 — Card 3: TIME-SLICED ASYNC MOUNT.
+//
+// Opening a 10k-node graph cost 6.8 SECONDS of frozen tab before one pixel
+// appeared. Not because 10k nodes are drawn — culling means only ~56 of them are —
+// but because the ~72 links that ARE on screen must each be routed around all 10k
+// nodes first, and a handful of long ones cost ~850ms EACH. Every one of those
+// routes was paid before the first frame reached the screen.
+//
+// Nothing here makes routing faster (that is the routing card's job, and the
+// measurement that says so is in the report). What this does is stop routing from
+// standing between the user and their diagram:
+//
+//   slice 0   nodes only            → PAINT. ~5ms. The graph is on screen.
+//   slice 1   + the first k links    → yield to rAF
+//   slice 2   + the next k links     → yield to rAF
+//   ...       until everything visible is mounted
+//
+// Between slices the browser paints and handles input, so the tab stays alive and
+// the diagram fills in visibly instead of arriving all at once, late.
+//
+// The one thing that would ruin it: re-routing, on every slice, the links the
+// PREVIOUS slices already routed — that turns the mount into a quadratic one, and the
+// progressive version ends up slower than the blocking render it replaced.
+//
+// The renderer's ROUTE MEMO (wave8/routing, Card 6) is what prevents that. A link routed
+// by slice k is a memo hit for slice k+1, keyed on the routing INPUTS (endpoints + routing
+// LOD) and invalidated when a third party moves into its corridor. This mounter used to
+// carry its own replay cache for the job; the memo's key is strictly stronger, so the
+// weaker one is gone. Two caches for one job, where one of them cannot see everything that
+// invalidates it, is how you get a route that "hasn't changed" and is wrong anyway.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProgressiveMounter = void 0;
+exports.learnFixedCost = learnFixedCost;
+const platform_1 = require("../platform/platform");
+class ProgressiveMounter {
+    constructor(engine, lifecycle, frame, deferred) {
+        this.handle = null;
+        this.running = false;
+        /**
+         * Settles the mount currently in flight.
+         *
+         * Held because `cancel()` tears down the rAF that would otherwise have settled
+         * it — without this, cancelling a mount left the caller's `await mount()` hanging
+         * forever. (Found by the spec, which is the only reason it is not still there.)
+         */
+        this.settle = null;
+        this.engine = engine;
+        this.lifecycle = lifecycle;
+        this.frame = frame;
+        this.deferred = deferred;
+    }
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Bring the scene up in rAF-yielded slices. Resolves when everything culling
+     * admits has a view (or when the mount is cancelled).
+     */
+    mount(viewport, zoom, options = {}) {
+        var _a, _b, _c, _d;
+        const sliceMs = (_a = options.sliceMs) !== null && _a !== void 0 ? _a : 8;
+        const maxSlices = (_b = options.maxSlices) !== null && _b !== void 0 ? _b : 500;
+        let chunk = Math.max(1, (_c = options.initialChunk) !== null && _c !== void 0 ? _c : 4);
+        this.cancel();
+        this.running = true;
+        const stats = {
+            firstPaintMs: 0,
+            completeMs: 0,
+            cpuMs: 0,
+            slices: 0,
+            nodesMounted: 0,
+            linksMounted: 0,
+            worstSliceMs: 0,
+            aborted: false,
+        };
+        const t0 = (0, platform_1.now)();
+        // ---- slice 0: the nodes. No routing, no links — this is the frame that
+        // decides whether the tool feels like it can hold the graph at all.
+        this.lifecycle.beginDeferred();
+        this.lifecycle.admitAll('node');
+        this.frame(viewport, zoom);
+        stats.firstPaintMs = (0, platform_1.now)() - t0;
+        stats.cpuMs = stats.firstPaintMs;
+        stats.slices = 1;
+        stats.worstSliceMs = stats.firstPaintMs;
+        stats.nodesMounted = this.mountedNodeCount();
+        (_d = options.onFirstPaint) === null || _d === void 0 ? void 0 : _d.call(options, stats);
+        // The per-frame FIXED cost — what a render costs before it draws anything new.
+        //
+        // It is not small and it is not avoidable from here: the renderer rebuilds an
+        // obstacle rect map over EVERY node in the diagram on every frame (~15ms at 10k),
+        // so a slice that admits one link and a slice that admits fifty both pay it.
+        //
+        // Measuring it is the difference between chunking and thrashing. Without this the
+        // controller sees a 15ms slice against an 8ms target, concludes the chunk is too
+        // big, and shrinks it — to 1 — which MAXIMISES the number of slices and therefore
+        // the number of times the fixed cost is paid. It converges on the worst schedule
+        // available while believing it is optimising. (Measured: 70 slices for 72 links,
+        // turning a 553ms blocking render into a 1639ms mount.)
+        //
+        // Estimated with `learnFixedCost`, below, from the slices themselves.
+        let fixedMs = 0;
+        let marginalMs = 0;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (aborted) => {
+                if (settled)
+                    return;
+                settled = true;
+                stats.aborted = aborted;
+                stats.completeMs = (0, platform_1.now)() - t0;
+                this.settle = null;
+                this.teardown();
+                resolve(stats);
+            };
+            this.settle = finish;
+            const step = () => {
+                var _a;
+                this.handle = null;
+                if (!this.running)
+                    return finish(true);
+                // Everything the LAST frame wanted but the gate held back.
+                const pending = this.deferred();
+                if (pending.length === 0) {
+                    // The last slice drew the last entity: the scene on screen is already
+                    // whole. Hand the gate back and stop.
+                    //
+                    // It is tempting to "finish cleanly" with one more full render here. Do
+                    // not: an ungated render re-routes every visible link, so that courtesy
+                    // frame costs a second pass over the entire scene (~200ms at 10k) and
+                    // routes every link exactly twice. The spec counts routes per link for
+                    // precisely this reason.
+                    this.lifecycle.endDeferred();
+                    return finish(false);
+                }
+                if (stats.slices >= maxSlices) {
+                    // Gave up slicing. Hand the gate back and draw the remainder in one go —
+                    // a bounded mount must still leave a COMPLETE diagram on screen.
+                    this.lifecycle.endDeferred();
+                    this.frame(viewport, zoom);
+                    return finish(false);
+                }
+                const take = Math.min(chunk, pending.length);
+                for (let i = 0; i < take; i++) {
+                    const [kind, id] = pending[i];
+                    this.lifecycle.admit(kind, id);
+                    if (kind === 'link')
+                        stats.linksMounted++;
+                    else
+                        stats.nodesMounted++;
+                }
+                const t = (0, platform_1.now)();
+                this.frame(viewport, zoom);
+                const sliceMsActual = (0, platform_1.now)() - t;
+                stats.slices++;
+                stats.cpuMs += sliceMsActual;
+                stats.worstSliceMs = Math.max(stats.worstSliceMs, sliceMsActual);
+                (_a = options.onSlice) === null || _a === void 0 ? void 0 : _a.call(options, stats);
+                // ---- learn the cost model: slice ≈ fixed + marginal × chunk ----------------
+                //
+                // Both terms matter and they behave completely differently. `marginal` is what
+                // this slice's entities actually cost (1-3ms a link now that routing is memoised;
+                // it was 850ms for a long one before). `fixed` is the per-frame tax the renderer
+                // charges whatever we do, and no chunk size can duck it.
+                ({ fixedMs, marginalMs } = learnFixedCost(fixedMs, marginalMs, take, sliceMsActual));
+                // ---- choose the next chunk ------------------------------------------------
+                //
+                // Aim at `sliceMs` of MARGINAL work — but never at a target the fixed cost has
+                // already blown through. If a frame costs 15ms before it does anything useful,
+                // then a slice budget of 8ms is not achievable and chasing it just multiplies the
+                // number of frames that pay the 15ms. So the real budget is at least twice the
+                // fixed cost, which bounds the mount's overhead: the tax can never be more than
+                // half of what we spend.
+                const budget = Math.max(sliceMs, fixedMs * 2);
+                const useful = Math.max(budget - fixedMs, sliceMs);
+                const target = Math.round(useful / Math.max(marginalMs, 0.01));
+                // Shrink as hard as the measurement says (one bad slice must back off at once),
+                // but grow no more than 4x at a time — entity costs are skewed, and a run of cheap
+                // ones should not ramp the chunk so high that the next expensive one arrives in a
+                // batch of 200.
+                //
+                // The floor is 1: a router cannot be pre-empted mid-path, so a single 850ms link IS
+                // an 850ms slice. Chunking cannot fix that and should not pretend to — what it can
+                // do is ensure such a link stalls the mount alone, and never in company.
+                chunk = clamp(Math.min(target, chunk * 4), 1, 256);
+                this.handle = (0, platform_1.requestFrame)(step);
+            };
+            this.handle = (0, platform_1.requestFrame)(step);
+        });
+    }
+    /**
+     * Stop mounting. Whatever is not yet mounted is mounted by the next normal render
+     * — the gate is handed back here, so a cancelled mount can never strand half a
+     * diagram on screen.
+     */
+    cancel() {
+        var _a;
+        if (!this.running && this.handle === null)
+            return;
+        this.running = false;
+        if (this.handle !== null) {
+            (0, platform_1.cancelFrame)(this.handle);
+            this.handle = null;
+        }
+        this.lifecycle.endDeferred();
+        // Settle the caller's `await mount()`. Cancelling the rAF killed the only other
+        // thing that would have.
+        (_a = this.settle) === null || _a === void 0 ? void 0 : _a.call(this, true);
+    }
+    dispose() {
+        this.cancel();
+    }
+    // -------------------------------------------------------------------------
+    teardown() {
+        this.running = false;
+        this.handle = null;
+    }
+    mountedNodeCount() {
+        const diagram = this.engine.getDiagram();
+        return diagram ? diagram.getNodes().filter((n) => this.lifecycle.admits('node', n.id)).length : 0;
+    }
+}
+exports.ProgressiveMounter = ProgressiveMounter;
+function clamp(v, lo, hi) {
+    return v < lo ? lo : v > hi ? hi : v;
+}
+/**
+ * Separate a slice's cost into the part that scales with the work (`marginal`) and the
+ * part the renderer charges regardless (`fixed`).
+ *
+ * We never get to observe either directly — only `fixed + marginal × chunk`, once per
+ * slice, from a noisy clock. So:
+ *
+ *   - `fixed` is tracked as the cheapest per-entity-adjusted floor we have seen. A slice
+ *     can never cost LESS than the fixed cost, so the running minimum converges onto it
+ *     from above and cannot be dragged up by an expensive entity.
+ *   - `marginal` is whatever is left over, averaged with an EWMA so one pathological
+ *     entity (an 850ms link) moves the estimate without defining it.
+ *
+ * Deliberately conservative in one direction: if we UNDER-estimate `fixed`, the chunk
+ * comes out small and the mount is merely slower. If we OVER-estimate it, the chunk comes
+ * out large and a slice janks. Slow is recoverable; jank is what the user sees.
+ */
+function learnFixedCost(fixedMs, marginalMs, chunk, sliceMs) {
+    const perEntity = sliceMs / Math.max(chunk, 1);
+    // First observation: we cannot separate the terms from one sample, so assume the slice
+    // was all fixed cost minus one entity's worth. Pessimistic on purpose (see above).
+    if (fixedMs === 0 && marginalMs === 0) {
+        return {
+            fixedMs: Math.max(0, sliceMs - perEntity),
+            marginalMs: Math.max(perEntity, 0.01),
+        };
+    }
+    // A slice cannot cost less than the fixed cost. Anything cheaper than our estimate IS a
+    // better upper bound on it.
+    const nextFixed = Math.min(fixedMs, sliceMs);
+    // What this slice's entities cost, once the tax is taken out.
+    const observedMarginal = Math.max(sliceMs - nextFixed, 0) / Math.max(chunk, 1);
+    // EWMA: track real change, do not let one outlier become the model.
+    const nextMarginal = Math.max(0.01, marginalMs * 0.5 + observedMarginal * 0.5);
+    return { fixedMs: nextFixed, marginalMs: nextMarginal };
+}
+//# sourceMappingURL=progressive-mounter.js.map