@grafloria/element 0.3.17 → 0.3.19

package/src/libs/renderer/src/instance/create-diagram.js

@@ -0,0 +1,1150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDiagram = createDiagram;
+exports.contentBounds = contentBounds;
+const tslib_1 = require("tslib");
+const engine_1 = require("@grafloria/engine");
+const comment_overlay_1 = require("../comments/comment-overlay");
+const capture_host_1 = require("../export/capture-host");
+const assets_1 = require("../export/assets");
+const svg_renderer_1 = require("../svg/svg-renderer");
+const patch_1 = require("../vnode/patch");
+const interaction_controller_1 = require("../interaction/interaction-controller");
+const viewport_controller_1 = require("../viewport/viewport-controller");
+const render_scheduler_1 = require("./render-scheduler");
+const dom_event_binder_1 = require("./dom-event-binder");
+const model_input_1 = require("./model-input");
+const layers_1 = require("./layers");
+const platform_1 = require("../platform");
+const host_culling_1 = require("../lazy/host-culling");
+function createDiagram(container, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+    if (!(0, platform_1.isBrowser)()) {
+        // A clear failure beats a mysterious `document is not defined` five frames
+        // deep. The server path is `renderToStaticSVG()`; the client then hydrates.
+        throw new Error('createDiagram() requires a browser DOM. On the server call renderToStaticSVG() ' +
+            'and hydrate with createDiagram(el, { hydrate: snapshot }) in an effect.');
+    }
+    const hydration = options.hydrate;
+    const doc = container.ownerDocument;
+    // -- engine + model ---------------------------------------------------------
+    const engine = (_a = options.engine) !== null && _a !== void 0 ? _a : new engine_1.DiagramEngine(options.interaction ? { interaction: options.interaction } : {});
+    const model = (_b = engine.getDiagram()) !== null && _b !== void 0 ? _b : engine.createDiagram('grafloria');
+    // Wave 6 BUG FIX. This used to be `applyNodes(model, options.nodes ?? [])`.
+    //
+    // `applyNodes`/`applyEdges` are full RECONCILERS — anything not in the list is
+    // REMOVED. So passing no `nodes` reconciled against the EMPTY list and silently
+    // deleted every node already on the diagram. That made the documented
+    // "attach to an existing engine" path (`createDiagram(el, { engine })`) wipe
+    // the very diagram it was attaching to.
+    //
+    // Absent means "I am not managing this" — NOT "make it empty". A host that
+    // really wants to clear the diagram passes `nodes: []` explicitly, which still
+    // works.
+    if (options.nodes)
+        (0, model_input_1.applyNodes)(model, options.nodes);
+    if (options.edges)
+        (0, model_input_1.applyEdges)(model, options.edges);
+    // -- camera -----------------------------------------------------------------
+    const rect0 = container.getBoundingClientRect();
+    const viewport = new viewport_controller_1.ViewportController({
+        viewport: {
+            x: (_e = (_c = hydration === null || hydration === void 0 ? void 0 : hydration.viewport.x) !== null && _c !== void 0 ? _c : (_d = options.viewport) === null || _d === void 0 ? void 0 : _d.x) !== null && _e !== void 0 ? _e : 0,
+            y: (_h = (_f = hydration === null || hydration === void 0 ? void 0 : hydration.viewport.y) !== null && _f !== void 0 ? _f : (_g = options.viewport) === null || _g === void 0 ? void 0 : _g.y) !== null && _h !== void 0 ? _h : 0,
+            // Hydration MUST reuse the server's canvas size or the viewBox differs and
+            // the very first client frame would re-lay-out the picture.
+            width: (_k = (_j = hydration === null || hydration === void 0 ? void 0 : hydration.width) !== null && _j !== void 0 ? _j : rect0.width) !== null && _k !== void 0 ? _k : 800,
+            height: (_m = (_l = hydration === null || hydration === void 0 ? void 0 : hydration.height) !== null && _l !== void 0 ? _l : rect0.height) !== null && _m !== void 0 ? _m : 600,
+        },
+        zoom: (_p = (_o = hydration === null || hydration === void 0 ? void 0 : hydration.zoom) !== null && _o !== void 0 ? _o : options.zoom) !== null && _p !== void 0 ? _p : 1,
+        minZoom: options.minZoom,
+        maxZoom: options.maxZoom,
+        zoomSensitivity: options.zoomSensitivity,
+    });
+    // -- layers -----------------------------------------------------------------
+    const layers = ensureLayers(container, doc, hydration);
+    // -- renderer + patcher -----------------------------------------------------
+    // Wave 10 BUG FIX. This used to forward `instanceId` and NOTHING ELSE.
+    //
+    // `SVGRendererConfig` has carried `colorMode`, `themes` and `tokenBridge` for
+    // two waves. `createDiagram()` is the ONLY way a host builds a renderer — so
+    // dropping them here made all three unreachable, and with them:
+    //
+    //   - `colorMode: 'system'`, i.e. following the OS colour scheme at all, and
+    //     the a11y upgrade where `prefers-contrast: more` / forced-colors promotes
+    //     you to the high-contrast theme instead of flashing light at the user.
+    //     The themes existed. The controller existed. Nothing could switch them on.
+    //   - the shadcn / MUI / Tailwind design-token bridge — the whole point of
+    //     which is that a HOST re-points Grafloria's variables at its own tokens.
+    //
+    // Three features, fully built and fully tested, lost in a five-line literal.
+    const renderer = new svg_renderer_1.SVGRenderer(engine, Object.assign(Object.assign({}, ((_q = options.renderer) !== null && _q !== void 0 ? _q : {})), { instanceId: (_r = hydration === null || hydration === void 0 ? void 0 : hydration.instanceId) !== null && _r !== void 0 ? _r : options.instanceId, colorMode: (_s = options.colorMode) !== null && _s !== void 0 ? _s : (_t = options.renderer) === null || _t === void 0 ? void 0 : _t.colorMode, themes: options.themes, tokenBridge: options.tokenBridge, 
+        // "My picture improved with no model change — repaint me." Fired by the
+        // async route solver's refinements and by motion-stable routing's settle
+        // frame (a tween's provisional routes re-deciding once motion stops).
+        // Neither has a model event to ride, so without this wire both improved
+        // pictures were unreachable from a real instance: the renderer bumped its
+        // invalidation epoch and nobody ever asked the scheduler for a frame.
+        // Late-bound on purpose — `scheduler` is constructed below and this
+        // callback only ever fires asynchronously, after mount. The host's own
+        // callback (if any) is chained, not replaced.
+        onRoutesRefined: () => {
+            var _a, _b;
+            (_b = (_a = options.renderer) === null || _a === void 0 ? void 0 : _a.onRoutesRefined) === null || _b === void 0 ? void 0 : _b.call(_a);
+            scheduler.schedule();
+        } }), options.theme);
+    renderer.applyInstanceScope(layers.root);
+    // The lazy subsystem (freeze / autoFreeze / progressive mount) has existed since wave 8
+    // and was reachable only by building an `SVGRenderer` yourself — i.e. not from the
+    // factory that every host actually uses. Absent leaves the renderer ungated, which is
+    // exactly what it did before this line existed.
+    if (options.viewLifecycle)
+        renderer.setViewLifecycle(options.viewLifecycle);
+    const patcher = new patch_1.VNodePatcher({ document: doc });
+    // -- events -----------------------------------------------------------------
+    const listeners = new Map();
+    const emit = (event, payload) => {
+        const set = listeners.get(event);
+        if (!set)
+            return;
+        // Copy: a handler is allowed to unsubscribe itself.
+        for (const listener of [...set])
+            listener(payload);
+    };
+    // -- comments ---------------------------------------------------------------
+    // The overlay hooks the renderer's comment source, so pins render inside the
+    // VNode tree (they survive export and pan/zoom for free).
+    let commentStore = null;
+    let commentOverlay = null;
+    if (options.comments) {
+        commentStore =
+            options.comments === true
+                ? new engine_1.CommentStore(model, { viewer: (_u = options.commentsViewer) !== null && _u !== void 0 ? _u : 'local' })
+                : options.comments;
+        commentOverlay = new comment_overlay_1.CommentOverlayController(commentStore, renderer);
+    }
+    // -- interaction ------------------------------------------------------------
+    const interaction = new interaction_controller_1.InteractionController();
+    interaction.syncWithEngineConfig(engine);
+    // The link grab distance derives from the renderer's interaction-stroke
+    // width; a host override must reach BOTH sides or the painted hit-area and
+    // the accepted press drift apart again.
+    if (((_v = options.renderer) === null || _v === void 0 ? void 0 : _v.linkHitAreaWidth) !== undefined) {
+        interaction.setLinkHitAreaWidth(options.renderer.linkHitAreaWidth);
+    }
+    const getRect = () => container.getBoundingClientRect();
+    const scheduler = new render_scheduler_1.RenderScheduler({
+        onFrame: () => paint(),
+        shouldSkip: () => canSkipFrame(),
+    });
+    const binder = new dom_event_binder_1.DomEventBinder(container, {
+        getEngine: () => engine,
+        viewport,
+        interaction,
+        getRect,
+        requestRender: () => scheduler.schedule(),
+        emit,
+    }, options);
+    // -- custom (HTML-layer) nodes ---------------------------------------------
+    //
+    // `nodeHosts` is the record of every host this instance OWNS — not of what is in the
+    // document. In `'detach'` cull mode a culled host stays in this map with its element
+    // parked off-document, which is what keeps the two teardown paths below (model removal,
+    // and `dispose()`) correct without either of them learning that culling exists: a node
+    // that is culled and then deleted still fires `removeCustomNode` exactly once, because
+    // it never left the map.
+    const nodeHosts = new Map();
+    const culler = options.cullCustomNodes
+        ? new host_culling_1.HtmlHostCuller(options.cullCustomNodes === true ? {} : options.cullCustomNodes, renderer.getViewLifecycle())
+        : null;
+    /**
+     * Nodes a live gesture owns, which must never be culled out from under it.
+     *
+     * Built only when culling is on — a host that never opted in pays not even the Set.
+     */
+    const gestureHeld = () => {
+        const ids = new Set(binder.getDraggingNodeIds());
+        // Resize / rotate / vertex. `SelectionToolsController` keeps the gesture's node
+        // private and these gestures are single-selection by construction, so the selection
+        // is the available answer — and being a superset is the safe direction to be wrong in.
+        if (binder.hasActiveGesture()) {
+            for (const node of model.getSelectedNodes())
+                ids.add(node.id);
+        }
+        return ids;
+    };
+    /** The lifecycle the culler consults, read once so the export can consult it too. */
+    const lifecycle = renderer.getViewLifecycle();
+    /**
+     * THE PAINT LEDGER — what an ASYNC `renderCustomNode` told us about itself.
+     *
+     * `pendingPaints` holds one entry per widget whose painter returned a promise that has
+     * not settled; the entry deletes itself when it does. `paintFailures` remembers the ones
+     * that rejected, so an export can say "its painter rejected: …" instead of the useless
+     * "its host was empty".
+     *
+     * Both are keyed by node id and both are written ONLY on a first mount, because
+     * `renderCustomNode` runs exactly once per host — so there is exactly one promise per
+     * widget, ever, and re-attaching a culled host neither re-runs nor re-awaits anything.
+     */
+    const pendingPaints = new Map();
+    const paintFailures = new Map();
+    const isThenable = (value) => value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function';
+    /**
+     * Record what a painter returned.
+     *
+     * The `.then` here is also what keeps a rejecting painter from surfacing as an unhandled
+     * rejection in the host's console — we are the ones who asked for the promise, so we are
+     * the ones who must handle it, whether or not an export ever happens.
+     */
+    const trackPaint = (id, result) => {
+        if (!isThenable(result))
+            return;
+        try {
+            const settled = Promise.resolve(result).then(() => undefined, (error) => {
+                paintFailures.set(id, error instanceof Error ? error.message : String(error));
+            });
+            const entry = settled.then(() => {
+                // Identity-checked: a 'destroy'-mode remount replaces the entry, and a stale
+                // promise settling afterwards must not delete its successor.
+                if (pendingPaints.get(id) === entry)
+                    pendingPaints.delete(id);
+            });
+            pendingPaints.set(id, entry);
+        }
+        catch (_a) {
+            // A broken thenable is not worth taking a frame down for. It simply is not tracked,
+            // and its widget degrades exactly as an unreadable host already does.
+        }
+    };
+    /** World bounds of a custom node — the rect both the culler and the capture work in. */
+    const nodeBounds = (node) => {
+        var _a, _b, _c, _d;
+        return ({
+            x: node.position.x,
+            y: node.position.y,
+            width: (_b = (_a = node.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0,
+            height: (_d = (_c = node.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0,
+        });
+    };
+    /**
+     * Create-or-re-attach one custom node's host and place it.
+     *
+     * Shared by the frame loop and the export boundary deliberately: the two must agree
+     * byte for byte on what a host is (the class, the `data-node-id`, the style, and above
+     * all the mount-once rule that `renderCustomNode` fires only when the element is
+     * created). Two copies of this would drift, and the drift would be silent.
+     *
+     * The element is put in `nodeHosts` and in the document BEFORE the painter runs, which
+     * is what lets the export boundary undo a mount whose painter threw.
+     */
+    const mountHost = (node) => {
+        var _a;
+        let host = nodeHosts.get(node.id);
+        if (!host) {
+            host = doc.createElement('div');
+            host.setAttribute('data-node-id', node.id);
+            host.className = 'grafloria-node-host';
+            layers.html.appendChild(host);
+            nodeHosts.set(node.id, host);
+            // A fresh paint supersedes whatever the last one ended in — only reachable in
+            // 'destroy' cull mode, which is the one mode that re-runs a painter.
+            pendingPaints.delete(node.id);
+            paintFailures.delete(node.id);
+            // The RETURN VALUE is the whole async contract: a painter that is not finished says
+            // so by handing back a promise. Sync painters return undefined and cost nothing.
+            trackPaint(node.id, (_a = options.renderCustomNode) === null || _a === void 0 ? void 0 : _a.call(options, node, host));
+        }
+        else if (!host.parentNode) {
+            // Re-entry after a detach cull: the SAME element goes back, with its subtree, its
+            // scroll offset, its canvas bitmap and its event listeners intact. `renderCustomNode`
+            // is NOT called again — "a custom node mounts exactly once" is a promise neither the
+            // cull nor the export is allowed to break.
+            layers.html.appendChild(host);
+        }
+        host.setAttribute('style', (0, layers_1.nodeHostStyle)(node.position.x, node.position.y, node.size.width, node.size.height));
+    };
+    /**
+     * Hosts an in-flight ASYNC capture is holding open, which no frame may cull.
+     *
+     * Only an async export can populate this, and only for as long as it is waiting. The
+     * synchronous capture materializes, reads and restores inside one tick with no
+     * suspension point, so nothing can run in the middle of it and it needs no pin.
+     *
+     * Without this, waiting for a painter would be self-defeating: real frames run WHILE we
+     * wait (that is what "async" means here), and one of them culling the very host we are
+     * waiting on would hand the capture a detached element — no layout box, every rect zero,
+     * a blank widget. An animated pan during an export would silently empty it. In 'destroy'
+     * mode it is worse than blank: the frame fires `removeCustomNode` and drops the host, so
+     * the export's own teardown would fire a SECOND time on an element the embedder has
+     * already disposed.
+     */
+    const pinnedHosts = new Set();
+    const syncCustomNodes = () => {
+        var _a, _b;
+        const wanted = new Set();
+        // The viewBox, not `getViewport()`: the two diverge at any zoom != 1 and culling
+        // against the camera rect drops hosts that are on screen whenever the board is zoomed
+        // out — which fitView() always does.
+        if (culler)
+            culler.beginFrame(viewport.getViewBox(), viewport.getZoom(), gestureHeld());
+        for (const node of model.getNodes()) {
+            if (!node.getMetadata('useHTMLLayer'))
+                continue;
+            wanted.add(node.id);
+            const existing = nodeHosts.get(node.id);
+            if (culler && !pinnedHosts.has(node.id)) {
+                // `existing?.parentNode` — the DOM's own answer to "is this mounted", rather than a
+                // bookkeeping set that can drift from it. Feeding the CURRENT state back in is what
+                // makes the hysteresis band work: which of the two rects applies depends on where
+                // the host already is.
+                if (!culler.admits(node.id, nodeBounds(node), !!(existing === null || existing === void 0 ? void 0 : existing.parentNode))) {
+                    if (existing) {
+                        if (culler.getMode() === 'destroy') {
+                            (_a = options.removeCustomNode) === null || _a === void 0 ? void 0 : _a.call(options, node.id, existing);
+                            existing.remove();
+                            nodeHosts.delete(node.id);
+                        }
+                        else if (existing.parentNode) {
+                            // DETACH ONLY. No `removeCustomNode` — the component was not unmounted, it
+                            // is parked. Firing the teardown hook here would be a lie the host would act
+                            // on (disposing a chart it is about to be handed back).
+                            existing.remove();
+                        }
+                    }
+                    // …and no style write. That is most of the saving: a 400-widget board stops
+                    // paying 400 `setAttribute` calls per frame to position elements nobody sees.
+                    continue;
+                }
+            }
+            mountHost(node);
+        }
+        for (const [id, host] of [...nodeHosts]) {
+            if (wanted.has(id))
+                continue;
+            (_b = options.removeCustomNode) === null || _b === void 0 ? void 0 : _b.call(options, id, host);
+            host.remove();
+            nodeHosts.delete(id);
+        }
+    };
+    /**
+     * The custom nodes an export with this scope will contain — the one definition of
+     * "in scope", shared by everything that has to agree on it (what gets materialized,
+     * what gets pinned, what gets waited for).
+     *
+     * WHAT IT WILL NOT INCLUDE. An explicit {@link ViewLifecycle} freeze is skipped, and
+     * that is not timidity: `SVGRenderer.render` gates every entity on
+     * `ViewLifecycle.admits`, so the render pass of this very export omits a frozen node.
+     * Capturing its widget would put content in the file with no node beneath it, and
+     * stretch the fitted viewBox to reach a node the same file does not draw.
+     */
+    const exportableCustomNodes = (needed) => model
+        .getNodes()
+        .filter((node) => !!node.getMetadata('useHTMLLayer') &&
+        needed(node) &&
+        !(lifecycle === null || lifecycle === void 0 ? void 0 : lifecycle.isExplicitlyFrozen('node', node.id)));
+    /**
+     * FORCE-MATERIALIZE the hosts an export is about to read, and hand back the undo.
+     *
+     * THE GAP THIS CLOSES. Culling means a widget the camera has never reached has never
+     * been painted, so there is nothing in the document to capture; a widget culling
+     * detached has an element with no layout box, which every `getBoundingClientRect()`
+     * reports as zero. Either way the export used to emit an empty box, and the option's
+     * own documentation told the caller to "pan or fitView() first". That is not a
+     * workaround anyone can apply from a headless print job, a thumbnailer or a server —
+     * and it made `cullCustomNodes`, a PERFORMANCE knob, silently change what comes out of
+     * a file. A performance knob that loses data is not a performance knob.
+     *
+     * So the rule is now: **an export contains the same widgets whether culling is on or
+     * off.** The capture mounts what it needs, reads it, and puts the document back.
+     *
+     * PUTS IT BACK, precisely — because an export that permanently mounted a 300-widget
+     * board would just be a different bug:
+     *
+     *   was 'attached'  nothing to do, nothing to undo. Already live, already correct.
+     *   was 'detached'  re-attached to be read, then detached again. `renderCustomNode`
+     *                   never re-runs, so mount-once is untouched.
+     *   was 'absent'    created and painted — a legitimate FIRST mount, not a second one.
+     *                   Then re-culled to whatever the configured mode means:
+     *                     • 'detach'  — parked off-document, retained. Identical to what a
+     *                       pan across the board and back leaves behind, and it keeps the
+     *                       promise that this widget's painter runs exactly once, ever.
+     *                     • 'destroy' — torn down for real (`removeCustomNode` fires). That
+     *                       mode exists to BOUND THE HEAP, so leaving hosts retained would
+     *                       defeat it outright; the balanced mount/unmount an export
+     *                       performs is the same lifecycle a pan already produces, and a
+     *                       'destroy' embedder has accepted that its painter re-runs.
+     *                     • no culler at all — left mounted. There is no culled state to
+     *                       restore to, and the documented default is that every custom
+     *                       host is permanently in the document, so this is the state the
+     *                       next frame would have produced anyway. (Reachable by exporting
+     *                       between `setNodes()` and the frame it schedules — which used to
+     *                       export blank widgets, and no longer does.)
+     *
+     * WHAT IT WILL NOT OVERRULE is decided by `exportableCustomNodes` above — an explicit
+     * {@link ViewLifecycle} freeze is skipped, and it says why.
+     *
+     * WHAT IT CANNOT DO ON ITS OWN. `renderCustomNode` is called here and read on the next
+     * line, because `exportSvgString()` is synchronous by contract. A painter that defers
+     * its paint has not drawn anything by the time we look. That is what the async path
+     * below exists for; the synchronous one still reports it rather than exporting a
+     * silent blank.
+     */
+    const materializeCustomNodes = (needed) => {
+        var _a;
+        const undo = [];
+        for (const node of exportableCustomNodes(needed)) {
+            if ((_a = nodeHosts.get(node.id)) === null || _a === void 0 ? void 0 : _a.parentNode)
+                continue; // already live — leave it alone
+            const was = nodeHosts.has(node.id) ? 'detached' : 'absent';
+            try {
+                mountHost(node);
+            }
+            catch (_b) {
+                // A FIRST-MOUNT PAINTER THAT THROWS must not take the export with it. This is the
+                // only place a widget's painter runs outside a frame, so letting it propagate
+                // would abort the whole export AND strand every host materialized before it.
+                // `mountHost` registers the element before it calls the painter, so the undo below
+                // is still knowable, and the capture degrades to the marked box and warning that
+                // every unreadable host already gets.
+            }
+            const host = nodeHosts.get(node.id);
+            if (!host)
+                continue;
+            if (was === 'detached' || !culler) {
+                if (was === 'detached')
+                    undo.push(() => host.remove());
+            }
+            else if (culler.getMode() === 'destroy') {
+                undo.push(() => {
+                    var _a;
+                    // IDENTITY-CHECKED, because the async path can suspend between the mount and
+                    // this undo. If the node left the model while we waited, the frame's own
+                    // teardown loop has already fired `removeCustomNode` and dropped the host —
+                    // firing again would dispose an embedder's component twice. In the synchronous
+                    // path nothing can run in between, so this is always true and changes nothing.
+                    if (nodeHosts.get(node.id) !== host)
+                        return;
+                    (_a = options.removeCustomNode) === null || _a === void 0 ? void 0 : _a.call(options, node.id, host);
+                    host.remove();
+                    nodeHosts.delete(node.id);
+                });
+            }
+            else {
+                undo.push(() => host.remove());
+            }
+        }
+        return () => {
+            for (const restore of undo)
+                restore();
+        };
+    };
+    /**
+     * Why this widget's capture may be short, in the words a developer can act on.
+     *
+     * `waited` distinguishes the two ways an unfinished painter reaches an export, because
+     * they have different fixes: the synchronous entry points CANNOT wait and the caller
+     * should move to `await export(…)`; the asynchronous one waited and gave up, and the
+     * caller should raise the deadline or find out why the painter never settles.
+     */
+    const paintWarning = (id, waited, timeoutMs) => {
+        const failure = paintFailures.get(id);
+        if (failure !== undefined) {
+            return (`custom node "${id}" — its renderCustomNode promise REJECTED (${failure}), so whatever ` +
+                'it had not drawn by then is missing from this export.');
+        }
+        if (!pendingPaints.has(id))
+            return undefined;
+        if (waited) {
+            return (`custom node "${id}" did not finish painting within ${timeoutMs}ms — captured as it ` +
+                'stood at the deadline, which may be partial or blank. Raise ' +
+                'ExportOptions.customNodeTimeout, or check why its renderCustomNode promise never settles.');
+        }
+        return (`custom node "${id}" is STILL PAINTING asynchronously (its renderCustomNode returned a ` +
+            'promise that has not settled). exportSvgString() / exportPdf() are synchronous by ' +
+            "contract and cannot wait — use `await diagram.export('svg' | 'pdf' | 'png', …)`, which does.");
+    };
+    /**
+     * THE EXPORT BOUNDARY for HTML-layer nodes.
+     *
+     * A custom node paints into a raw host that is a SIBLING of the SVG, so the VNode
+     * tree the exporter serializes contains an empty `<g>` for it and nothing else. That
+     * is why an exported dashboard used to be a set of blank rectangles: the content was
+     * never in the tree to begin with.
+     *
+     * THIS is the only place that can fix it, because this is the only place that holds
+     * the hosts. So the DOM read happens HERE, once, and produces plain data —
+     * `exportSvg` stays pure, DOM-free and deterministic, which is a property worth
+     * strictly more than the convenience of reaching into the document from inside it.
+     *
+     * A caller's own `customNodes` always wins (including `[]`, which means "export the
+     * diagram without its widgets").
+     */
+    const captureCustomNodes = (needed) => {
+        const restore = materializeCustomNodes(needed);
+        try {
+            return readHosts(false, 0);
+        }
+        finally {
+            // `finally`: a capture that threw must not leave a board's worth of hosts mounted.
+            // (`captureCustomNodeHost` is documented never to throw, but the restore is the one
+            // thing here whose failure would be permanent, so it does not depend on that.)
+            restore();
+        }
+    };
+    /** The DOM read, shared by both capture paths so they cannot disagree about a host. */
+    const readHosts = (waited, timeoutMs) => {
+        const captures = [];
+        // Model order, not Map order: an export must not depend on mount sequence, or two
+        // runs of the same board would differ in byte order.
+        for (const node of model.getNodes()) {
+            const host = nodeHosts.get(node.id);
+            if (!host)
+                continue;
+            const capture = (0, capture_host_1.captureCustomNodeHost)(node.id, nodeBounds(node), host);
+            // A still-painting caveat is the CAUSE and leads; the capture's own fidelity caveats
+            // (an image that PDF cannot draw, an inset shadow that was skipped) follow it. Merging
+            // rather than overwriting keeps both — a widget can be both async AND hold an image.
+            const paint = paintWarning(node.id, waited, timeoutMs);
+            const warning = [paint, capture.warning].filter(Boolean).join(' ');
+            captures.push(warning ? Object.assign(Object.assign({}, capture), { warning }) : capture);
+        }
+        return captures;
+    };
+    /**
+     * THE ASYNC CAPTURE — the same boundary, allowed to wait for a painter that said it
+     * was not finished.
+     *
+     * THE SIGNAL IS THE PROMISE, and nothing else. A fixed sleep would be both slow (every
+     * export pays for the slowest imaginable widget) and wrong (the slowest widget is always
+     * slower than the guess, on someone's machine). `renderCustomNode` returning a promise
+     * is a contract the painter's author owns, can type, and is never wrong about — so this
+     * waits for exactly those, and returns the instant the last one settles.
+     *
+     * THE BOUND. `customNodeTimeout` (default 5s) is a safety net, never the mechanism: a
+     * painter that never settles must not hang a print job. On expiry the export takes the
+     * host as it stands — partial, or blank — and every widget it did not get to wait out is
+     * WARNED about by id. Degraded, reported, never silent.
+     *
+     * WHY THE SYNC PATH IS REUSED VERBATIM WHEN NOTHING IS PENDING. If no painter in scope
+     * has an unsettled promise, this runs materialize → read → restore with no suspension
+     * point at all, i.e. the identical sequence `exportSvgString()` performs. That makes "an
+     * all-sync board exports the same bytes through both paths" structurally true rather
+     * than merely tested — there is no second code path for it to drift into.
+     */
+    const captureCustomNodesAsync = (needed, timeoutMs) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const scope = exportableCustomNodes(needed).map((node) => node.id);
+        for (const id of scope)
+            pinnedHosts.add(id);
+        const restore = materializeCustomNodes(needed);
+        try {
+            // Only NOW is the pending set knowable: materializing runs first mounts, and a
+            // first mount is exactly where a painter announces that it is async.
+            const waits = scope
+                .map((id) => pendingPaints.get(id))
+                .filter((p) => p !== undefined);
+            if (waits.length === 0)
+                return readHosts(false, timeoutMs); // ← atomic, as above
+            yield settle(waits, timeoutMs);
+            return readHosts(true, timeoutMs);
+        }
+        finally {
+            restore();
+            for (const id of scope)
+                pinnedHosts.delete(id);
+        }
+    });
+    /** Wait for every tracked paint, or for the deadline — whichever comes first. */
+    const settle = (waits, timeoutMs) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+        if (!(timeoutMs > 0))
+            return; // 0 (or nonsense) means "do not wait"; still reported
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        try {
+            // The tracked promises are wrapped never to reject, so this races two resolutions
+            // and cannot itself throw. A rejecting painter is recorded, not propagated.
+            yield Promise.race([Promise.all(waits), deadline]);
+        }
+        finally {
+            // Without this a fast export still holds the event loop open for the full deadline,
+            // which in Node keeps a process alive after the work is done.
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    });
+    /**
+     * ONE async capture at a time.
+     *
+     * Two exports in flight would otherwise interleave their materialize/restore pairs —
+     * the first's restore tearing down a host the second is still waiting to read, which is
+     * a blank widget in a file that asked for nothing unusual. Serializing is also the
+     * cheaper answer: the second export finds the first's painters already settled.
+     */
+    let captureQueue = Promise.resolve();
+    const serializeCapture = (run) => {
+        const result = captureQueue.then(run, run);
+        captureQueue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    /**
+     * Which nodes this export will actually contain.
+     *
+     * Materializing is the expensive half — it runs a painter — so it is bounded by the
+     * export's own scope rather than mounting a 300-widget board to capture the three
+     * widgets `includeIds` asked for. The predicates mirror what the renderer resolves
+     * `ids` to (`SVGRenderer.selectedIds` reads exactly this `state.selected`), so what is
+     * mounted and what survives `filterCaptures` are the same set.
+     */
+    const exportNeeds = (exportOptions) => {
+        if ((exportOptions === null || exportOptions === void 0 ? void 0 : exportOptions.scope) === 'selection')
+            return (node) => { var _a; return ((_a = node.state) === null || _a === void 0 ? void 0 : _a.selected) === true; };
+        if ((exportOptions === null || exportOptions === void 0 ? void 0 : exportOptions.includeIds) === undefined)
+            return () => true;
+        const ids = new Set(exportOptions.includeIds);
+        return (node) => ids.has(node.id);
+    };
+    const withCustomNodes = (exportOptions) => {
+        if ((exportOptions === null || exportOptions === void 0 ? void 0 : exportOptions.customNodes) !== undefined)
+            return exportOptions;
+        const customNodes = captureCustomNodes(exportNeeds(exportOptions));
+        if (customNodes.length === 0)
+            return exportOptions !== null && exportOptions !== void 0 ? exportOptions : {};
+        return Object.assign(Object.assign({}, exportOptions), { customNodes });
+    };
+    /** Default bound on waiting for an async painter. See ExportOptions.customNodeTimeout. */
+    const DEFAULT_CUSTOM_NODE_TIMEOUT = 5000;
+    const withCustomNodesAsync = (exportOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+        // The caller's own captures win, and short-circuit the wait entirely — `customNodes:
+        // []` means "export the diagram without its widgets", which must not sit out a
+        // deadline for painters whose output was never going in the file.
+        if ((exportOptions === null || exportOptions === void 0 ? void 0 : exportOptions.customNodes) !== undefined)
+            return exportOptions;
+        const customNodes = yield serializeCapture(() => {
+            var _a;
+            return captureCustomNodesAsync(exportNeeds(exportOptions), (_a = exportOptions === null || exportOptions === void 0 ? void 0 : exportOptions.customNodeTimeout) !== null && _a !== void 0 ? _a : DEFAULT_CUSTOM_NODE_TIMEOUT);
+        });
+        if (customNodes.length === 0)
+            return exportOptions !== null && exportOptions !== void 0 ? exportOptions : {};
+        return Object.assign(Object.assign({}, exportOptions), { customNodes });
+    });
+    /**
+     * EXTERNAL-URL IMAGES → embedded bytes, for the async export only.
+     *
+     * A widget's `<img src="https://…">` captures as `<image href="https://…">`, which an
+     * SVG renders online and a PDF cannot draw at all. This library is client-side: the
+     * export RUNS IN A BROWSER, and the browser can usually fetch that URL itself. So the
+     * awaited path fetches every external reference and swaps it for the `data:` URI the
+     * PDF writer already embeds as an XObject (b2854b0a1) — three tiers, see
+     * `fetchAssetsTiered`: environment fetch (same-origin / CORS-allowed), then
+     * `ExportOptions.assetFetcher` (the app's proxy), then the accurate warning.
+     *
+     * TWO KINDS OF IMAGE, ONE PASS. Widget captures hold their images as captured VNodes
+     * and are substituted here directly. But a PANEL-type diagram node (an ERD avatar, a
+     * logo — `metadata.panel.image/icon.href`) is painted by the RENDERER'S OWN tree,
+     * which is built inside the synchronous export — this layer never holds it. So the
+     * renderer enumerates that tree's URLs up front (`collectExportImageUrls` — the same
+     * `render()` the export serializes, so no drift), the fetch covers the UNION of both
+     * kinds (one fetch per URL, however many widgets and panels share it), and the
+     * resolved map rides down `ExportOptions.resolvedAssets` for the sync path's pure
+     * `inlineAssets` substitution. A URL the caller pre-resolved is trusted, never fetched.
+     *
+     * THE WARNING LEDGER IS RECONCILED, both ways. A capture whose external images were
+     * all embedded has its capture-time "EXTERNAL URL" caveat STRIPPED — after the fetch
+     * it asserts a problem that no longer exists. A URL every tier failed on keeps the
+     * reference (broken-but-visible beats silently blanked, the `inlineAssets` rule) and
+     * gains a warning naming the URL, the reason, and the escape hatches — a tree image's
+     * failure reaches `onWarnings` the same way a widget image's reaches the capture.
+     *
+     * `exportSvgString()` / `exportPdf()` stay synchronous and network-free: they fetch
+     * nothing, and honour only a `resolvedAssets` map the caller supplies.
+     */
+    const withInlinedImages = (exportOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const captures = (_a = exportOptions.customNodes) !== null && _a !== void 0 ? _a : [];
+        // Collect the union — widget-capture URLs first, then the renderer's tree — each
+        // deduplicated in a STABLE order (model order, then first appearance) for
+        // determinism. One URL, one fetch, no matter which kinds reference it.
+        const roots = new Map();
+        const urls = [];
+        const seen = new Set();
+        const add = (found) => {
+            for (const url of found) {
+                if (!seen.has(url)) {
+                    seen.add(url);
+                    urls.push(url);
+                }
+            }
+        };
+        for (const capture of captures) {
+            if (!capture.content || capture.content.length === 0)
+                continue;
+            const root = { type: 'g', props: {}, children: [...capture.content] };
+            const found = (0, assets_1.collectAssetUrls)(root);
+            if (found.length === 0)
+                continue;
+            roots.set(capture, root);
+            add(found);
+        }
+        const treeUrls = renderer.collectExportImageUrls(exportOptions);
+        add(treeUrls);
+        if (urls.length === 0)
+            return exportOptions; // nothing external — identical options out
+        // A URL the caller already resolved is bytes we hold — fetching it again would be
+        // both wasteful and a trust inversion (their bytes are the ones they want in the file).
+        const preResolved = exportOptions.resolvedAssets;
+        const toFetch = preResolved ? urls.filter((url) => !preResolved.has(url)) : urls;
+        const { byUrl, failures } = toFetch.length > 0
+            ? yield (0, assets_1.fetchAssetsTiered)(toFetch, {
+                fetcher: exportOptions.assetFetcher,
+                maxBytes: exportOptions.assetMaxBytes,
+                timeoutMs: exportOptions.assetTimeout,
+            })
+            : { byUrl: new Map(), failures: new Map() };
+        if (preResolved) {
+            for (const [url, uri] of preResolved)
+                byUrl.set(url, uri);
+        }
+        const customNodes = captures.map((capture) => {
+            var _a;
+            const root = roots.get(capture);
+            if (!root)
+                return capture;
+            const inlined = (0, assets_1.inlineAssets)(root, byUrl);
+            const remaining = (0, assets_1.collectAssetUrls)(inlined);
+            let warning = capture.warning;
+            if (remaining.length === 0) {
+                // Every external image is now bytes in the file — the capture-time caveat
+                // (written for the sync paths, which cannot fetch) is no longer true here.
+                warning = (0, capture_host_1.stripResolvedImageWarnings)(warning);
+            }
+            else {
+                const residue = remaining
+                    .map((url) => {
+                    var _a;
+                    return `widget image "${url}" could not be embedded: ${(_a = failures.get(url)) !== null && _a !== void 0 ? _a : 'unknown failure'}. ` +
+                        'The reference is left in the file (an SVG still renders it online); it will be ' +
+                        'MISSING from a PDF export.';
+                })
+                    .join(' ');
+                warning = [warning, residue].filter(Boolean).join(' ');
+            }
+            return Object.assign(Object.assign({}, capture), { content: (_a = inlined.children) !== null && _a !== void 0 ? _a : [], warning });
+        });
+        const out = Object.assign({}, exportOptions);
+        if (exportOptions.customNodes !== undefined)
+            out.customNodes = customNodes;
+        // The resolved map rides DOWN the same options object: the sync export applies it
+        // to the renderer's tree with the pure `inlineAssets` — which is how a panel image
+        // becomes bytes without the sync path ever fetching.
+        if (byUrl.size > 0)
+            out.resolvedAssets = byUrl;
+        // A TREE image's failure has no capture to carry its warning, so it goes to the
+        // export's own fidelity channel. Same honesty rule as the widget residue: name the
+        // URL, the reason, and (via the tier-3 text) both escape hatches.
+        const treeResidue = treeUrls
+            .filter((url) => !byUrl.has(url))
+            .map((url) => {
+            var _a;
+            return `diagram image "${url}" could not be embedded: ${(_a = failures.get(url)) !== null && _a !== void 0 ? _a : 'unknown failure'}. ` +
+                'The reference is left in the file (an SVG still renders it online); it will be ' +
+                'MISSING from a PDF export.';
+        });
+        if (treeResidue.length > 0) {
+            const original = exportOptions.onWarnings;
+            out.onWarnings = (warnings) => original === null || original === void 0 ? void 0 : original([...warnings, ...treeResidue]);
+        }
+        return out;
+    });
+    // -- the frame --------------------------------------------------------------
+    let lastViewportKey = '';
+    let lastFrameHadPreview = false;
+    /** Mutation epoch as of the end of the last painted frame. See canSkipFrame(). */
+    let lastFrameEpoch = -1;
+    /** Renderer invalidation epoch as of the end of the last painted frame. */
+    let lastRendererEpoch = -1;
+    let ready = false;
+    let disposed = false;
+    /**
+     * `ready` fires on a microtask, not inline in the mount paint. The first paint
+     * happens INSIDE `createDiagram()`, so a caller doing
+     * `const d = createDiagram(...); d.on('ready', …)` could never have observed an
+     * inline emit — the handler is registered one statement too late.
+     */
+    const signalReady = () => {
+        if (ready)
+            return;
+        ready = true;
+        queueMicrotask(() => {
+            if (!disposed)
+                emit('ready', undefined);
+        });
+    };
+    const viewportKey = () => {
+        const v = viewport.getViewport();
+        return `${v.x},${v.y},${v.width},${v.height}@${viewport.getZoom()}`;
+    };
+    const isConnectionPreviewActive = () => {
+        try {
+            return engine.getConnectionStateManager().getState().isConnecting === true;
+        }
+        catch (_a) {
+            return false;
+        }
+    };
+    /**
+     * Idle-skip: drop a queued frame only when nothing visible could have changed.
+     * The connection preview lives in interaction state, not in entity dirty flags,
+     * so we never skip while it is — or was, last frame — active, otherwise its
+     * removal would not repaint.
+     *
+     * wave8/dirty — BUG FIXED HERE. This used to sum `getDirtyNodes/Links/Groups`
+     * and skip only when the total was zero. On any diagram bigger than the
+     * viewport that total is NEVER zero, so the idle-skip never once fired:
+     *
+     *   the renderer marks an entity clean when it RENDERS it, and it renders only
+     *   what is visible. Open a 10,000-node diagram with 56 nodes on screen and the
+     *   other 9,944 stay dirty for the life of the canvas — they are never drawn,
+     *   so they are never cleaned. `dirty > 0` forever. `return false` forever.
+     *
+     * So the one guard whose entire job was "don't repaint an idle canvas" was
+     * dead exactly where idleness costs the most, and it charged three O(n) array
+     * scans per queued frame for the privilege of always saying no.
+     *
+     * The mutation epoch answers the real question — *has anything changed since
+     * the frame on screen?* — in O(1) and without caring whether the change was on
+     * screen. (Off-screen changes matter: an off-screen node is an obstacle the
+     * edge optimizer routes around, and its edge may well cross the viewport.)
+     */
+    const canSkipFrame = () => {
+        if (!engine.getDiagram())
+            return false;
+        if ((0, engine_1.getMutationEpoch)() !== lastFrameEpoch)
+            return false;
+        // …and the RENDERER's own picture must not have gone stale either. The model
+        // epoch answers "did the world change"; this answers "did my picture of it
+        // change". They are not the same question, and the gap is a real bug: when
+        // the off-thread route solver answers, the model has not changed — the epoch
+        // does not move — but the routes have improved. Keyed only on the model, this
+        // would drop that repaint before render() was ever called, and the refined
+        // routes we paid a worker for would never reach the screen.
+        if (renderer.getInvalidationEpoch() !== lastRendererEpoch)
+            return false;
+        if (viewportKey() !== lastViewportKey)
+            return false;
+        if (isConnectionPreviewActive() || lastFrameHadPreview)
+            return false;
+        return true;
+    };
+    /**
+     * THE FRAME — in three strictly ordered phases (wave8/dirty, Card 1).
+     *
+     *   READ    every DOM measurement, before any write.
+     *   COMPUTE pure VNode construction: no DOM in, no DOM out.
+     *   WRITE   every DOM mutation, with no read between them.
+     *
+     * The order is the whole point. A read after a write forces the browser to
+     * flush layout synchronously to answer it; do that inside a loop over N nodes
+     * and you have N forced layouts — layout thrash, and the classic way a canvas
+     * that is fast at 50 nodes dies at 500. Keeping the phases apart makes it
+     * structurally impossible rather than merely absent today. (`node-component.ts`
+     * had exactly this bug in its refresh loop; it now batches the same way.)
+     */
+    const paint = () => {
+        // -- READ ------------------------------------------------------------------
+        const renderViewport = viewport.getRenderViewport();
+        const zoom = viewport.getZoom();
+        const htmlTransform = viewport.getHtmlLayerTransform();
+        // -- COMPUTE ---------------------------------------------------------------
+        const vnode = renderer.render(renderViewport, zoom);
+        // -- WRITE -----------------------------------------------------------------
+        layers.html.setAttribute('style', (0, layers_1.htmlLayerStyle)(htmlTransform));
+        patcher.reconcile(layers.svg, vnode);
+        syncCustomNodes();
+        lastViewportKey = viewportKey();
+        lastFrameHadPreview = isConnectionPreviewActive();
+        // AFTER the frame, not before: rendering legitimately dirties model entities
+        // (routed geometry, auto-sizing), and stamping on entry would record an epoch
+        // the frame itself then invalidates — the skip would never fire again.
+        lastFrameEpoch = (0, engine_1.getMutationEpoch)();
+        lastRendererEpoch = renderer.getInvalidationEpoch();
+        signalReady();
+    };
+    /**
+     * The HYDRATION frame: render the VNode tree, then ADOPT the server's DOM
+     * instead of building it. Zero DOM writes ⇒ no flash and no re-layout.
+     */
+    const hydratePaint = () => {
+        const vnode = renderer.render(viewport.getRenderViewport(), viewport.getZoom());
+        patcher.hydrate(layers.svg, vnode);
+        syncCustomNodes();
+        lastViewportKey = viewportKey();
+        lastFrameHadPreview = isConnectionPreviewActive();
+        lastFrameEpoch = (0, engine_1.getMutationEpoch)();
+        lastRendererEpoch = renderer.getInvalidationEpoch();
+        signalReady();
+    };
+    // -- model → repaint --------------------------------------------------------
+    const unsubs = [];
+    const onModel = (event, handler) => {
+        unsubs.push(model.on(event, handler));
+    };
+    onModel('node:added', () => {
+        scheduler.schedule();
+        emit('nodes:change', { nodes: model.getNodes() });
+    });
+    onModel('node:removed', () => {
+        scheduler.schedule();
+        emit('nodes:change', { nodes: model.getNodes() });
+    });
+    onModel('node:changed', () => scheduler.schedule());
+    onModel('link:added', ((link) => {
+        scheduler.schedule();
+        emit('edges:change', { edges: model.getLinks() });
+        // The engine creates the link ASYNCHRONOUSLY from `connection:complete`, so
+        // this — not the mouseup — is where a user-drawn connection is observable.
+        if (link)
+            emit('connect', { link });
+    }));
+    onModel('link:removed', () => {
+        scheduler.schedule();
+        emit('edges:change', { edges: model.getLinks() });
+    });
+    onModel('link:changed', () => scheduler.schedule());
+    // Groups paint too (frames, lanes, collapse proxies) — leaving these out made
+    // fitToContents() invisible until an unrelated event happened to render.
+    onModel('group:added', () => scheduler.schedule());
+    onModel('group:removed', () => scheduler.schedule());
+    onModel('group:changed', () => scheduler.schedule());
+    onModel('selection:changed', () => {
+        scheduler.schedule();
+        emit('selection:change', {
+            nodes: model.getSelectedNodes(),
+            edges: model.getLinks().filter((l) => l.state === 'selected'),
+        });
+    });
+    unsubs.push(viewport.onChange((state) => {
+        scheduler.schedule();
+        emit('viewport:change', state);
+    }));
+    // -- resize -----------------------------------------------------------------
+    let resizeObserver;
+    if (typeof ResizeObserver !== 'undefined') {
+        resizeObserver = new ResizeObserver(() => {
+            const r = getRect();
+            if (r.width > 0 && r.height > 0)
+                viewport.syncCanvasSize(r);
+        });
+        resizeObserver.observe(container);
+    }
+    // -- mount ------------------------------------------------------------------
+    binder.attach();
+    if (hydration) {
+        hydratePaint();
+    }
+    else {
+        if (options.fitView)
+            fitView(40);
+        // Synchronous first paint: a host that measures right after createDiagram()
+        // must not see an empty container.
+        scheduler.flush();
+    }
+    function fitView(padding = 40) {
+        const bounds = contentBounds(model);
+        // maxZoom 1: fitting means "show me everything", never "magnify a small
+        // graph until it fills the wall". Zooming out to fit is still unbounded
+        // (down to the controller's minZoom). Hosts wanting magnification can call
+        // viewport.fitToBounds directly.
+        if (bounds)
+            viewport.fitToBounds(bounds, padding, { maxZoom: 1 });
+    }
+    const instance = {
+        setNodes(nodes) {
+            if ((0, model_input_1.applyNodes)(model, nodes))
+                scheduler.schedule();
+        },
+        setEdges(edges) {
+            if ((0, model_input_1.applyEdges)(model, edges))
+                scheduler.schedule();
+        },
+        getModel: () => model,
+        getEngine: () => engine,
+        getCommentStore: () => commentStore,
+        on(event, handler) {
+            let set = listeners.get(event);
+            if (!set) {
+                set = new Set();
+                listeners.set(event, set);
+            }
+            set.add(handler);
+            return () => set === null || set === void 0 ? void 0 : set.delete(handler);
+        },
+        off(event, handler) {
+            var _a;
+            (_a = listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+        },
+        viewport,
+        interaction,
+        setTheme(theme) {
+            renderer.setTheme(theme);
+            scheduler.schedule();
+        },
+        // Wave 10: the renderer could already do all of this. The instance — the only
+        // handle a host is given — exposed none of it, and did not expose the renderer
+        // either, so `SVGRenderer.export()` was unreachable from an embed. The library
+        // shipped PNG, JPEG, WebP, a real vector PDF and a deterministic zero-DOM SVG
+        // serializer that an embedder had no way to call.
+        setColorMode(mode, themes) {
+            renderer.setColorMode(mode, themes);
+            scheduler.schedule();
+        },
+        getColorMode: () => renderer.getColorMode(),
+        setTokenBridge(bridge) {
+            renderer.setTokenBridge(bridge);
+            scheduler.schedule();
+        },
+        // THE ONLY ASYNC EXPORT ENTRY POINT — and it always was one. `IRenderer.export`
+        // has returned a Promise since the seam existed, so an ASYNC custom-node painter
+        // needs no new public method: this is where waiting for one belongs. The two
+        // synchronous entry points below keep their contract exactly, and report an
+        // unfinished painter rather than pretending to have read it.
+        export: (format, exportOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () { return renderer.export(format, yield withInlinedImages(yield withCustomNodesAsync(exportOptions))); }),
+        exportSvgString: (exportOptions) => renderer.exportSvgString(withCustomNodes(exportOptions)),
+        exportPdf: (exportOptions) => renderer.exportPdf(withCustomNodes(exportOptions)),
+        exportText: (textOptions) => (0, engine_1.exportDiagramText)(model, textOptions),
+        loadText: (text, textOptions) => {
+            const result = (0, engine_1.importDiagramText)(text, textOptions);
+            // Reconcile INTO the live model (never swap it): applyNodes/applyEdges
+            // are full reconcilers, so removals happen and every listener, plugin,
+            // and renderer binding stays attached to the same DiagramModel.
+            (0, model_input_1.applyNodes)(model, result.diagram.getNodes().map((n) => (0, model_input_1.toNodeSpec)(n)));
+            (0, model_input_1.applyEdges)(model, result.diagram.getLinks().map((l) => (0, model_input_1.toEdgeSpec)(l)));
+            return result;
+        },
+        /** The LOD tier actually rendered, and the governor's last verdict. */
+        getQualityState: () => renderer.getQualityState(),
+        /** Animation policy (global toggle, speed, reduced-motion, battery-saver opt-out). */
+        animations: renderer.getAnimationService(),
+        fitView,
+        render: () => scheduler.schedule(),
+        renderNow: () => scheduler.flush(),
+        batchUpdate(mutate) {
+            model.beginBatch();
+            try {
+                mutate(model);
+            }
+            finally {
+                // `finally`: a throwing mutator must not leave the model batching
+                // forever — every subsequent change would be silently swallowed, and the
+                // canvas would simply stop updating with no error to explain it.
+                model.endBatch();
+            }
+            // endBatch() replays the queued events, and each of those already calls
+            // schedule(). This is for the batch that changed something the model does
+            // not emit for (or nothing at all): schedule() is idempotent within a tick,
+            // so an extra call costs one `coalesced` counter, never an extra frame.
+            scheduler.schedule();
+        },
+        getDraggingNodeIds: () => binder.getDraggingNodeIds(),
+        beginLabelEdit: (target, opts) => binder.beginLabelEdit(target, opts),
+        registry: renderer.getRegistry(),
+        dispose() {
+            var _a;
+            if (disposed)
+                return;
+            disposed = true;
+            commentOverlay === null || commentOverlay === void 0 ? void 0 : commentOverlay.dispose();
+            commentOverlay = null;
+            binder.detach();
+            scheduler.dispose();
+            resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.disconnect();
+            for (const unsub of unsubs)
+                unsub();
+            unsubs.length = 0;
+            listeners.clear();
+            for (const [id, host] of [...nodeHosts]) {
+                (_a = options.removeCustomNode) === null || _a === void 0 ? void 0 : _a.call(options, id, host);
+                host.remove();
+            }
+            nodeHosts.clear();
+            interaction.dispose();
+            viewport.dispose();
+            renderer.dispose();
+            patcher.unmount(layers.svg);
+            // Only tear down the DOM we created. An engine handed in by the caller is
+            // theirs to destroy.
+            layers.root.remove();
+            if (!options.engine)
+                engine.destroy();
+        },
+        container,
+        scheduler,
+        patcher,
+    };
+    return instance;
+}
+/** World bounding box of every visible node, or null when there is nothing to fit. */
+function contentBounds(model) {
+    var _a, _b, _c, _d, _e;
+    const nodes = model.getNodes().filter((n) => { var _a; return ((_a = n.state) === null || _a === void 0 ? void 0 : _a.visible) !== false; });
+    if (nodes.length === 0)
+        return null;
+    let left = Infinity;
+    let top = Infinity;
+    let right = -Infinity;
+    let bottom = -Infinity;
+    for (const node of nodes) {
+        left = Math.min(left, node.position.x);
+        top = Math.min(top, node.position.y);
+        right = Math.max(right, node.position.x + ((_b = (_a = node.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0));
+        bottom = Math.max(bottom, node.position.y + ((_d = (_c = node.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0));
+    }
+    // Routed edges arc OUTSIDE the node bbox (a detour around an obstacle, a
+    // self-loop, a floating attachment's curve). Fitting to nodes alone left
+    // those arcs sliced off at the viewport edge — nodes "contained", picture
+    // clipped. Union in every routed waypoint the links carry.
+    for (const link of model.getLinks()) {
+        for (const p of (_e = link.points) !== null && _e !== void 0 ? _e : []) {
+            left = Math.min(left, p.x);
+            top = Math.min(top, p.y);
+            right = Math.max(right, p.x);
+            bottom = Math.max(bottom, p.y);
+        }
+    }
+    if (!isFinite(left) || !isFinite(top))
+        return null;
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/**
+ * Build the layer skeleton — or ADOPT the server's when hydrating. The adopted
+ * path must not write to the DOM at all: that is what "no flash, no re-layout"
+ * means in practice.
+ */
+function ensureLayers(container, doc, hydration) {
+    if (hydration) {
+        const root = container.querySelector(`.${layers_1.ROOT_CLASS}`);
+        const svg = root === null || root === void 0 ? void 0 : root.querySelector(`.${layers_1.SVG_LAYER_CLASS}`);
+        const html = root === null || root === void 0 ? void 0 : root.querySelector(`.${layers_1.HTML_LAYER_CLASS}`);
+        if (root && svg && html)
+            return { root, svg, html };
+        // Server markup missing → fall through and mount fresh (correct, if not
+        // flash-free). Silently rebuilding beats rendering nothing.
+    }
+    const root = doc.createElement('div');
+    root.className = layers_1.ROOT_CLASS;
+    root.setAttribute('style', layers_1.ROOT_STYLE);
+    const svg = doc.createElement('div');
+    svg.className = layers_1.SVG_LAYER_CLASS;
+    svg.setAttribute('style', layers_1.SVG_LAYER_STYLE);
+    const html = doc.createElement('div');
+    html.className = layers_1.HTML_LAYER_CLASS;
+    html.setAttribute('style', (0, layers_1.htmlLayerStyle)('translate(0px, 0px) scale(1)'));
+    root.appendChild(svg);
+    root.appendChild(html);
+    container.appendChild(root);
+    return { root, svg, html };
+}
+//# sourceMappingURL=create-diagram.js.map