@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/ext/manifest.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ============================================================================
+ * Card 7 — the declarative extension manifest + semver engine-compat gate
+ * ============================================================================
+ *
+ * A manifest is a plugin's contract, and it is deliberately DECLARATIVE: the
+ * host can answer "what does this add?" and "may it run here?" by reading it,
+ * WITHOUT importing a line of the plugin's code. That is what makes lazy loading
+ * safe (`registerLazy` validates the manifest and stops) and what makes the
+ * capability grant enforceable (you cannot ask for privileges at runtime that
+ * your manifest did not declare).
+ *
+ * `contributes` is documentation + discovery (a palette can list a plugin's
+ * shapes before it loads). `capabilities` is the ENFORCED grant.
+ *
+ * The semver matcher below is intentionally small — `^`, `~`, `>=`, `x`-ranges
+ * and exact pins — rather than a dependency on `semver`. `libs/renderer` has no
+ * runtime deps and this wave is not the place to add one.
+ */
+import type { CapabilityName } from './capabilities';
+/** What a plugin says it adds. Discovery/UX only — not a security boundary. */
+export interface ExtensionContributions {
+    shapes?: string[];
+    routers?: string[];
+    connectors?: string[];
+    anchors?: string[];
+    connectionPoints?: string[];
+    markers?: string[];
+    linkTemplates?: string[];
+    labelTemplates?: string[];
+    tools?: string[];
+    panels?: string[];
+    animations?: string[];
+    templates?: string[];
+}
+export interface ExtensionManifest<C extends CapabilityName = CapabilityName> {
+    /** Reverse-DNS recommended: `acme.flowchart-shapes`. Must be unique per host. */
+    id: string;
+    /** The plugin's own semver. */
+    version: string;
+    /** Human-facing. */
+    name?: string;
+    description?: string;
+    /**
+     * The host API range this plugin supports, e.g. `{ grafloria: '^1.0.0' }`.
+     * Checked against `EXTENSION_API_VERSION` and REJECTED on mismatch.
+     */
+    engines?: {
+        grafloria?: string;
+    };
+    /**
+     * The ENFORCED privilege grant. `activate()` receives exactly these and
+     * nothing else.
+     */
+    capabilities: readonly C[];
+    /** Declarative inventory, for discovery before load. */
+    contributes?: ExtensionContributions;
+}
+/** Throw with a precise reason. A malformed manifest must never half-load. */
+export declare function validateManifest(manifest: ExtensionManifest<CapabilityName>): void;
+/** Reject a plugin built against an incompatible host API. */
+export declare function assertEngineCompatible(manifest: ExtensionManifest<CapabilityName>, apiVersion: string): void;
+/**
+ * A deliberately small semver range matcher. Supports:
+ *   *  / x            any
+ *   1.2.3             exact
+ *   ^1.2.3            >=1.2.3 <2.0.0   (and ^0.2.3 → >=0.2.3 <0.3.0)
+ *   ~1.2.3            >=1.2.3 <1.3.0
+ *   >=1.2.3, >1.2.3, <=1.2.3, <1.2.3
+ *   1.x / 1.2.x
+ *   " || "            union of any of the above
+ */
+export declare function satisfies(version: string, range: string): boolean;

package/src/libs/renderer/src/ext/manifest.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 7 — the declarative extension manifest + semver engine-compat gate
+ * ============================================================================
+ *
+ * A manifest is a plugin's contract, and it is deliberately DECLARATIVE: the
+ * host can answer "what does this add?" and "may it run here?" by reading it,
+ * WITHOUT importing a line of the plugin's code. That is what makes lazy loading
+ * safe (`registerLazy` validates the manifest and stops) and what makes the
+ * capability grant enforceable (you cannot ask for privileges at runtime that
+ * your manifest did not declare).
+ *
+ * `contributes` is documentation + discovery (a palette can list a plugin's
+ * shapes before it loads). `capabilities` is the ENFORCED grant.
+ *
+ * The semver matcher below is intentionally small — `^`, `~`, `>=`, `x`-ranges
+ * and exact pins — rather than a dependency on `semver`. `libs/renderer` has no
+ * runtime deps and this wave is not the place to add one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateManifest = validateManifest;
+exports.assertEngineCompatible = assertEngineCompatible;
+exports.satisfies = satisfies;
+const ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i;
+const VALID_CAPABILITIES = [
+    'shapes',
+    'links',
+    'routers',
+    'templates',
+    'animations',
+    'tools',
+    'panels',
+];
+/** Throw with a precise reason. A malformed manifest must never half-load. */
+function validateManifest(manifest) {
+    if (!manifest || typeof manifest !== 'object') {
+        throw new Error('[ExtensionHost] manifest is required');
+    }
+    if (!manifest.id || !ID_RE.test(manifest.id)) {
+        throw new Error(`[ExtensionHost] invalid extension id '${String(manifest.id)}' — expected ` +
+            `letters/digits/dot/dash/underscore, e.g. 'acme.flowchart-shapes'`);
+    }
+    if (!manifest.version || !SEMVER_RE.test(manifest.version)) {
+        throw new Error(`[ExtensionHost] extension '${manifest.id}' has an invalid version ` +
+            `'${String(manifest.version)}' — expected semver, e.g. '1.2.0'`);
+    }
+    if (!Array.isArray(manifest.capabilities)) {
+        throw new Error(`[ExtensionHost] extension '${manifest.id}' must declare a 'capabilities' array ` +
+            `(use [] for a plugin that registers nothing)`);
+    }
+    for (const capability of manifest.capabilities) {
+        if (!VALID_CAPABILITIES.includes(capability)) {
+            throw new Error(`[ExtensionHost] extension '${manifest.id}' declares unknown capability ` +
+                `'${String(capability)}'. Known: ${VALID_CAPABILITIES.join(', ')}`);
+        }
+    }
+}
+/** Reject a plugin built against an incompatible host API. */
+function assertEngineCompatible(manifest, apiVersion) {
+    var _a;
+    const range = (_a = manifest.engines) === null || _a === void 0 ? void 0 : _a.grafloria;
+    if (!range)
+        return; // No claim = no gate. The plugin takes its chances.
+    if (!satisfies(apiVersion, range)) {
+        throw new Error(`[ExtensionHost] extension '${manifest.id}' requires grafloria '${range}', ` +
+            `but this host is '${apiVersion}'. Refusing to register.`);
+    }
+}
+function parse(version) {
+    const match = SEMVER_RE.exec(version.trim());
+    if (!match)
+        return null;
+    return { major: +match[1], minor: +match[2], patch: +match[3] };
+}
+function compare(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+/**
+ * A deliberately small semver range matcher. Supports:
+ *   *  / x            any
+ *   1.2.3             exact
+ *   ^1.2.3            >=1.2.3 <2.0.0   (and ^0.2.3 → >=0.2.3 <0.3.0)
+ *   ~1.2.3            >=1.2.3 <1.3.0
+ *   >=1.2.3, >1.2.3, <=1.2.3, <1.2.3
+ *   1.x / 1.2.x
+ *   " || "            union of any of the above
+ */
+function satisfies(version, range) {
+    const target = parse(version);
+    if (!target)
+        return false;
+    return range
+        .split('||')
+        .map((part) => part.trim())
+        .some((part) => satisfiesOne(target, part));
+}
+function satisfiesOne(target, range) {
+    var _a;
+    if (range === '*' || range === 'x' || range === '')
+        return true;
+    // x-ranges: 1.x, 1.2.x
+    if (/^\d+(\.\d+)?\.?x$/i.test(range) || /^\d+$/.test(range)) {
+        const parts = range.toLowerCase().replace(/\.?x$/, '').split('.').filter(Boolean);
+        const major = Number(parts[0]);
+        if (Number.isNaN(major) || target.major !== major)
+            return false;
+        if (parts.length > 1 && target.minor !== Number(parts[1]))
+            return false;
+        return true;
+    }
+    const operatorMatch = /^(>=|<=|>|<|\^|~)?\s*(.+)$/.exec(range);
+    if (!operatorMatch)
+        return false;
+    const operator = (_a = operatorMatch[1]) !== null && _a !== void 0 ? _a : '';
+    const base = parse(operatorMatch[2]);
+    if (!base)
+        return false;
+    const cmp = compare(target, base);
+    switch (operator) {
+        case '':
+            return cmp === 0;
+        case '>=':
+            return cmp >= 0;
+        case '>':
+            return cmp > 0;
+        case '<=':
+            return cmp <= 0;
+        case '<':
+            return cmp < 0;
+        case '~':
+            // >=base, same major.minor
+            return cmp >= 0 && target.major === base.major && target.minor === base.minor;
+        case '^':
+            if (cmp < 0)
+                return false;
+            // ^0.x is special: the minor acts as the breaking-change axis.
+            if (base.major === 0) {
+                return base.minor === 0
+                    ? target.major === 0 && target.minor === 0 && target.patch === base.patch
+                    : target.major === 0 && target.minor === base.minor;
+            }
+            return target.major === base.major;
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/src/libs/renderer/src/ext/node-component.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ============================================================================
+ * Card 3 — the custom node/edge component AUTHORING CONTRACT
+ * ============================================================================
+ *
+ * SCOPE, STATED PLAINLY. Wave 4 shipped the HOST HOOK (`renderCustomNode(node,
+ * element)` on `createDiagram`) and wave 5 shipped HTML/foreignObject nodes with
+ * content-hash keying. Both are mechanisms: "here is a div, do what you like".
+ * Neither is an authoring CONTRACT — there was no typed prop bag, no lifecycle,
+ * and no way to get a component's MEASURED size back into the model, which is the
+ * hard half (a node whose height depends on its content cannot be laid out or
+ * routed to until something measures it).
+ *
+ * This is that contract, built ON those hooks rather than forking them.
+ *
+ *   defineNodeComponent({ render, onUpdate, onDestroy, autoSize })
+ *   mountNodeComponents(instance, registry)   ← wires into renderCustomNode
+ *
+ * ---------------------------------------------------------------------------
+ * MEASURED SIZE — the part that actually matters
+ * ---------------------------------------------------------------------------
+ * A component that renders text of unknown length must be able to say "I turned
+ * out to be 214 px tall" and have the engine believe it: the node model resizes,
+ * links re-route to the new boundary, and the layout re-flows.
+ *
+ * We measure with a `ResizeObserver` on the component's own host element, and
+ * write the result back through `node.setSize()`. Two hazards, both handled:
+ *
+ *   1. FEEDBACK LOOP. Writing the size re-renders the node, which can resize the
+ *      host, which fires the observer again. We break it by only writing when the
+ *      measurement differs by more than a threshold (sub-pixel jitter from
+ *      fractional zoom is not a resize).
+ *
+ *   2. ZOOM. `getBoundingClientRect()` on the host returns SCREEN px, which is
+ *      world px × zoom. Writing that straight into the model would make a node
+ *      grow every time you zoomed in. We use `offsetWidth/offsetHeight` (layout
+ *      px, unaffected by the CSS transform on the layer) and fall back to
+ *      dividing the client rect by the zoom.
+ */
+import type { NodeModel } from '@grafloria/engine';
+import type { DiagramInstance } from '../instance/create-diagram';
+import type { VNode } from '../types';
+import type { Disposer } from './disposable';
+/** The typed props a node component receives. Recomputed on every update. */
+export interface NodeComponentProps<D = Record<string, unknown>> {
+    readonly id: string;
+    /** The node's own data bag (`node.data` / metadata). */
+    readonly data: D;
+    readonly selected: boolean;
+    readonly dragging: boolean;
+    readonly hovered: boolean;
+    /** Current camera zoom — for LOD rendering ("hide the detail below 0.5"). */
+    readonly zoom: number;
+    readonly width: number;
+    readonly height: number;
+    /** The node's ports, so a component can position its own handles. */
+    readonly ports: ReadonlyArray<{
+        id: string;
+        side: string;
+        type: string;
+    }>;
+    /** Escape hatch: the live model. Prefer the fields above. */
+    readonly node: NodeModel;
+}
+/**
+ * A component's render function.
+ *
+ * Return a `VNode` to have the renderer patch it (the framework-agnostic path),
+ * or take the `HTMLElement` and own it yourself (the React/Angular/Vue path —
+ * mount a portal into it and return `void`).
+ */
+export type NodeRenderFn<D = Record<string, unknown>> = (props: NodeComponentProps<D>, element: HTMLElement) => VNode | void;
+export interface NodeComponent<D = Record<string, unknown>> {
+    render: NodeRenderFn<D>;
+    /** Called on every prop change AFTER the first render. Optional fast path. */
+    onUpdate?: (props: NodeComponentProps<D>, element: HTMLElement) => void;
+    /** Unmount your framework's subtree here. */
+    onDestroy?: (element: HTMLElement) => void;
+    /**
+     * Measure the rendered element and write the size back into the model, so
+     * layout + routing see the node's REAL extent. Default false — a node whose
+     * size is authored should not be silently overridden by its content.
+     */
+    autoSize?: boolean;
+    /** Ignore measurement deltas smaller than this (px). Default 1. */
+    sizeThreshold?: number;
+}
+export declare function defineNodeComponent<D = Record<string, unknown>>(component: NodeComponent<D>): NodeComponent<D>;
+/** type → component. */
+export type NodeComponentRegistry = Record<string, NodeComponent<never>>;
+/**
+ * Wire a component registry into a live diagram.
+ *
+ * Returns a disposer that unmounts every component and disconnects every
+ * observer — the leak rule; a stranded ResizeObserver keeps its target's whole
+ * subtree alive.
+ */
+export declare function mountNodeComponents(instance: DiagramInstance, registry: NodeComponentRegistry): Disposer;
+/**
+ * The options you hand to `createDiagram()` to use a component registry from the
+ * very first paint (preferred over `mountNodeComponents` on a running instance,
+ * because the first render then already has the components).
+ *
+ * ```ts
+ * const diagram = createDiagram(el, {
+ *   nodes, edges,
+ *   ...nodeComponentOptions(registry, () => diagram),
+ * });
+ * ```
+ */
+export declare function nodeComponentOptions(registry: NodeComponentRegistry, getInstance: () => DiagramInstance): {
+    renderCustomNode: (node: NodeModel, element: HTMLElement) => void;
+    removeCustomNode: (id: string, element: HTMLElement) => void;
+};

package/src/libs/renderer/src/ext/node-component.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 3 — the custom node/edge component AUTHORING CONTRACT
+ * ============================================================================
+ *
+ * SCOPE, STATED PLAINLY. Wave 4 shipped the HOST HOOK (`renderCustomNode(node,
+ * element)` on `createDiagram`) and wave 5 shipped HTML/foreignObject nodes with
+ * content-hash keying. Both are mechanisms: "here is a div, do what you like".
+ * Neither is an authoring CONTRACT — there was no typed prop bag, no lifecycle,
+ * and no way to get a component's MEASURED size back into the model, which is the
+ * hard half (a node whose height depends on its content cannot be laid out or
+ * routed to until something measures it).
+ *
+ * This is that contract, built ON those hooks rather than forking them.
+ *
+ *   defineNodeComponent({ render, onUpdate, onDestroy, autoSize })
+ *   mountNodeComponents(instance, registry)   ← wires into renderCustomNode
+ *
+ * ---------------------------------------------------------------------------
+ * MEASURED SIZE — the part that actually matters
+ * ---------------------------------------------------------------------------
+ * A component that renders text of unknown length must be able to say "I turned
+ * out to be 214 px tall" and have the engine believe it: the node model resizes,
+ * links re-route to the new boundary, and the layout re-flows.
+ *
+ * We measure with a `ResizeObserver` on the component's own host element, and
+ * write the result back through `node.setSize()`. Two hazards, both handled:
+ *
+ *   1. FEEDBACK LOOP. Writing the size re-renders the node, which can resize the
+ *      host, which fires the observer again. We break it by only writing when the
+ *      measurement differs by more than a threshold (sub-pixel jitter from
+ *      fractional zoom is not a resize).
+ *
+ *   2. ZOOM. `getBoundingClientRect()` on the host returns SCREEN px, which is
+ *      world px × zoom. Writing that straight into the model would make a node
+ *      grow every time you zoomed in. We use `offsetWidth/offsetHeight` (layout
+ *      px, unaffected by the CSS transform on the layer) and fall back to
+ *      dividing the client rect by the zoom.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineNodeComponent = defineNodeComponent;
+exports.mountNodeComponents = mountNodeComponents;
+exports.nodeComponentOptions = nodeComponentOptions;
+const disposable_1 = require("./disposable");
+function defineNodeComponent(component) {
+    return component;
+}
+function propsFor(node, zoom, dragging) {
+    var _a, _b, _c, _d, _e;
+    return {
+        id: node.id,
+        data: ((_c = (_a = node.data) !== null && _a !== void 0 ? _a : (_b = node.getMetadata) === null || _b === void 0 ? void 0 : _b.call(node, 'data')) !== null && _c !== void 0 ? _c : {}),
+        selected: ((_d = node.state) === null || _d === void 0 ? void 0 : _d.selected) === true,
+        // NOTE: `dragging` is NOT on NodeState — node-drag lives in the DomEventBinder.
+        // The instance exposes it via getDraggingNodeIds(); see Card 3 in that file.
+        dragging,
+        hovered: ((_e = node.state) === null || _e === void 0 ? void 0 : _e.hovered) === true,
+        zoom,
+        width: node.size.width,
+        height: node.size.height,
+        ports: node.getPorts().map((p) => {
+            var _a, _b;
+            return ({
+                id: p.id,
+                side: String((_b = (_a = p.alignment) === null || _a === void 0 ? void 0 : _a.side) !== null && _b !== void 0 ? _b : 'right'),
+                type: String(p.type),
+            });
+        }),
+        node,
+    };
+}
+/**
+ * Wire a component registry into a live diagram.
+ *
+ * Returns a disposer that unmounts every component and disconnects every
+ * observer — the leak rule; a stranded ResizeObserver keeps its target's whole
+ * subtree alive.
+ */
+function mountNodeComponents(instance, registry) {
+    const store = new disposable_1.DisposableStore();
+    const mounted = new Map();
+    const observers = new Map();
+    const componentFor = (node) => { var _a, _b, _c; return (_a = registry[String(node.type)]) !== null && _a !== void 0 ? _a : registry[String((_c = (_b = node.getMetadata) === null || _b === void 0 ? void 0 : _b.call(node, 'component')) !== null && _c !== void 0 ? _c : '')]; };
+    /**
+     * The READ half of auto-sizing: measure, and return the size to write back (or
+     * null when there is nothing to do). It writes NOTHING — see `measureAll`.
+     */
+    const readSize = (node, element, component) => {
+        var _a;
+        if (!component.autoSize)
+            return null;
+        const threshold = (_a = component.sizeThreshold) !== null && _a !== void 0 ? _a : 1;
+        const zoom = instance.viewport.getZoom() || 1;
+        // offsetWidth/Height are LAYOUT px — immune to the CSS transform the HTML
+        // layer carries. The client-rect fallback must be divided by the zoom, or the
+        // node would grow every time the user zoomed in.
+        const width = element.offsetWidth || element.getBoundingClientRect().width / zoom;
+        const height = element.offsetHeight || element.getBoundingClientRect().height / zoom;
+        if (!(width > 0) || !(height > 0))
+            return null;
+        if (Math.abs(width - node.size.width) < threshold &&
+            Math.abs(height - node.size.height) < threshold) {
+            return null; // sub-threshold jitter — writing it would loop
+        }
+        return { width, height };
+    };
+    /**
+     * wave8/dirty — Card 1: measure a WHOLE batch of components in one read phase.
+     *
+     * The bug this replaces: `renderInto()` used to write a component's DOM and
+     * then immediately read `offsetWidth` off it. Inside `refresh()`, which loops
+     * over every mounted component, that is
+     *
+     *     write → READ → write → READ → write → READ …
+     *
+     * and every one of those reads forces the browser to flush layout synchronously
+     * to answer it. N custom nodes ⇒ N forced layouts per frame. Textbook layout
+     * thrash, and invisible until someone puts 200 custom nodes on a canvas.
+     *
+     * Now: all writes, then all reads (ONE layout flush, because the first read
+     * pays for the whole batch), then the size write-backs — inside a single
+     * `batchUpdate` so N resizes still cost exactly one repaint.
+     */
+    const measureAll = (pending) => {
+        if (pending.length === 0)
+            return;
+        // -- READ PHASE (no writes in this loop) ---------------------------------
+        const sizes = [];
+        for (const { node, element, component } of pending) {
+            const size = readSize(node, element, component);
+            if (size)
+                sizes.push(Object.assign({ node }, size));
+        }
+        if (sizes.length === 0)
+            return;
+        // -- WRITE-BACK PHASE ----------------------------------------------------
+        const batch = instance.batchUpdate;
+        const apply = () => {
+            // Wave 9 — Card 7: a SYSTEM write, for the same reason as svg/auto-size.ts —
+            // this is the MEASURED size of the component the document already declares,
+            // not an edit to the document. Exempt from the read-only lock so a custom
+            // node still sizes correctly in presentation mode.
+            for (const { node, width, height } of sizes) {
+                const write = () => node.setSize(width, height);
+                node.diagram ? node.diagram.runSystemWrite(write) : write();
+            }
+        };
+        // `batchUpdate` is the wave8 entry point; tolerate an older instance shape
+        // (tests build partial fakes) by falling back to the plain path.
+        if (typeof batch === 'function')
+            batch.call(instance, apply);
+        else {
+            apply();
+            instance.render();
+        }
+    };
+    /** The WRITE half: paint the component into its host. Reads nothing. */
+    const writeInto = (node, element, first) => {
+        const component = componentFor(node);
+        if (!component)
+            return false;
+        const dragging = instance.getDraggingNodeIds().includes(node.id);
+        const props = propsFor(node, instance.viewport.getZoom(), dragging);
+        if (first || !component.onUpdate) {
+            const vnode = component.render(props, element);
+            // A VNode-returning component gets patched for free; an element-owning one
+            // returned void and has already done its own thing.
+            if (vnode)
+                instance.patcher.reconcile(element, vnode);
+        }
+        else {
+            component.onUpdate(props, element);
+        }
+        return !!component.autoSize;
+    };
+    const renderInto = (node, element, first) => {
+        const component = componentFor(node);
+        if (!component)
+            return;
+        if (writeInto(node, element, first))
+            measureAll([{ node, element, component }]);
+    };
+    // The host hook wave 4 shipped. We are a CONSUMER of it, not a replacement.
+    const onCreate = (node, element) => {
+        const component = componentFor(node);
+        if (!component)
+            return;
+        mounted.set(node.id, { component, element });
+        renderInto(node, element, true);
+        if (component.autoSize && typeof ResizeObserver !== 'undefined') {
+            // A ResizeObserver callback already runs after layout, so reading here is
+            // free — but route it through measureAll anyway so there is exactly one
+            // place that reads a size and one place that writes it back.
+            const observer = new ResizeObserver(() => measureAll([{ node, element, component }]));
+            observer.observe(element);
+            observers.set(node.id, observer);
+        }
+    };
+    const onRemove = (id, element) => {
+        var _a, _b, _c;
+        (_a = observers.get(id)) === null || _a === void 0 ? void 0 : _a.disconnect();
+        observers.delete(id);
+        const entry = mounted.get(id);
+        (_c = entry === null || entry === void 0 ? void 0 : (_b = entry.component).onDestroy) === null || _c === void 0 ? void 0 : _c.call(_b, element);
+        // Drop any VNode tree we patched in, so the patcher does not keep the old
+        // DOM keyed against a node that no longer exists.
+        if (entry)
+            instance.patcher.unmount(element);
+        mounted.delete(id);
+    };
+    // Re-render mounted components when their node or the camera changes (zoom is
+    // a PROP — an LOD component must re-render when it crosses its threshold).
+    //
+    // wave8/dirty — Card 1: WRITE every component first, THEN measure them all in
+    // one read pass. Interleaving (the old shape) cost one forced layout per node.
+    const refresh = () => {
+        const pending = [];
+        for (const [id, entry] of mounted) {
+            const node = instance.getModel().getNode(id);
+            if (!node)
+                continue;
+            if (writeInto(node, entry.element, false)) {
+                pending.push({ node, element: entry.element, component: entry.component });
+            }
+        }
+        measureAll(pending);
+    };
+    store.add(instance.on('nodes:change', refresh));
+    store.add(instance.on('selection:change', refresh));
+    store.add(instance.on('viewport:change', refresh));
+    // Hand our hooks to the instance. NOTE: `createDiagram` takes these as OPTIONS,
+    // so a diagram already running needs them installed here.
+    const host = instance;
+    host.__nodeComponentHooks = { renderCustomNode: onCreate, removeCustomNode: onRemove };
+    store.add(() => {
+        for (const [id, entry] of [...mounted])
+            onRemove(id, entry.element);
+        mounted.clear();
+        for (const observer of observers.values())
+            observer.disconnect();
+        observers.clear();
+        delete host.__nodeComponentHooks;
+    });
+    return (0, disposable_1.once)(() => store.dispose());
+}
+/**
+ * The options you hand to `createDiagram()` to use a component registry from the
+ * very first paint (preferred over `mountNodeComponents` on a running instance,
+ * because the first render then already has the components).
+ *
+ * ```ts
+ * const diagram = createDiagram(el, {
+ *   nodes, edges,
+ *   ...nodeComponentOptions(registry, () => diagram),
+ * });
+ * ```
+ */
+function nodeComponentOptions(registry, getInstance) {
+    let disposer;
+    let wired = false;
+    const ensure = () => {
+        const instance = getInstance();
+        if (!instance)
+            return undefined;
+        if (!wired) {
+            wired = true;
+            disposer = mountNodeComponents(instance, registry);
+            void disposer;
+        }
+        return instance;
+    };
+    return {
+        renderCustomNode(node, element) {
+            var _a;
+            const instance = ensure();
+            if (!instance)
+                return;
+            const hooks = instance.__nodeComponentHooks;
+            (_a = hooks === null || hooks === void 0 ? void 0 : hooks.renderCustomNode) === null || _a === void 0 ? void 0 : _a.call(hooks, node, element);
+        },
+        removeCustomNode(id, element) {
+            var _a;
+            const instance = getInstance();
+            const hooks = instance === null || instance === void 0 ? void 0 : instance.__nodeComponentHooks;
+            (_a = hooks === null || hooks === void 0 ? void 0 : hooks.removeCustomNode) === null || _a === void 0 ? void 0 : _a.call(hooks, id, element);
+        },
+    };
+}
+//# sourceMappingURL=node-component.js.map

package/src/libs/renderer/src/ext/plugins-loader.d.ts

@@ -0,0 +1 @@
+export declare function loadCanvasPlugins(): Promise<typeof import('./components/attach')>;

package/src/libs/renderer/src/ext/plugins-loader.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCanvasPlugins = loadCanvasPlugins;
+/**
+ * Lazy, memoized loader for the canvas-plugins chain (minimap, zoom/fit
+ * controls, background grid) — the elkjs recipe applied to the ext layer.
+ *
+ * The framework wrappers reference `attachCanvasPlugins` on their `plugins`
+ * code path; a STATIC import makes every consumer bundle carry the whole ext
+ * chain whether plugins are used or not (measured: +0.6 MB on the Angular
+ * consumer app). Loading through `import()` keeps the chain out of the module
+ * graph until the first attach — bundlers split it into its own chunk.
+ */
+let pending;
+function loadCanvasPlugins() {
+    return (pending !== null && pending !== void 0 ? pending : (pending = Promise.resolve().then(() => require('./components/attach'))));
+}
+//# sourceMappingURL=plugins-loader.js.map