@grafloria/element 0.1.0

package/src/lib/grafloria-flow-element.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrafloriaFlowElement = exports.GRAFLORIA_EVENTS = void 0;
+exports.defineGrafloriaFlow = defineGrafloriaFlow;
+const renderer_1 = require("@grafloria/renderer");
+const node_type_registry_1 = require("./node-type-registry");
+/**
+ * `<grafloria-flow>` — the universal embed.
+ *
+ * React Flow serves React. ngx-vflow serves Angular. Each is a wall around one
+ * framework. A custom element has no wall: Vue, Svelte, Solid, Lit, Alpine,
+ * plain HTML, a CMS block, a Jupyter/Observable cell and a static site all speak
+ * "HTML element with attributes and events". This is the piece that lets Grafloria
+ * reach the long tail those libraries cannot.
+ *
+ * ```html
+ * <grafloria-flow theme="dark" fit-view
+ *             nodes='[{"id":"a","position":{"x":0,"y":0},"label":"A"}]'
+ *             edges='[{"source":"a","target":"b"}]'>
+ *   <template data-node-type="card">
+ *     <div class="card"><h4 data-field="title"></h4></div>
+ *   </template>
+ * </grafloria-flow>
+ *
+ * <script>
+ *   document.querySelector('grafloria-flow')
+ *     .addEventListener('grafloria-connect', e => console.log(e.detail.link));
+ * </script>
+ * ```
+ *
+ * Rich data goes in as PROPERTIES (`el.nodes = [...]`) and simple data as
+ * ATTRIBUTES (JSON strings) — the standard custom-element contract that every
+ * framework's template binding already targets:
+ * `:nodes` in Vue, `nodes={...}` in Svelte/Solid, `[attr.nodes]` in Angular.
+ *
+ * Everything it does is delegation. There is no diagram logic in this file.
+ */
+const THEMES = {
+    light: renderer_1.LIGHT_THEME,
+    dark: renderer_1.DARK_THEME,
+};
+/** Events emitted on the element. All bubble and cross shadow boundaries. */
+exports.GRAFLORIA_EVENTS = {
+    ready: 'grafloria-ready',
+    nodesChange: 'grafloria-nodes-change',
+    edgesChange: 'grafloria-edges-change',
+    selectionChange: 'grafloria-selection-change',
+    connect: 'grafloria-connect',
+    nodeClick: 'grafloria-node-click',
+    edgeClick: 'grafloria-edge-click',
+    viewportChange: 'grafloria-viewport-change',
+};
+// wave11/gallery BUG FIX — worker-safe base class.
+//
+// `class GrafloriaFlowElement extends HTMLElement` evaluates `HTMLElement` at MODULE
+// LOAD, so merely IMPORTING this package threw `HTMLElement is not defined` in any
+// context without a DOM — a Web Worker, or Node. The package doc already promised
+// the import is "a no-op on the server", and `defineGrafloriaFlow()` guards
+// `customElements`; but the class declaration itself did not, so the promise was
+// only half true. It matters concretely: the off-thread-layout demo runs the
+// engine's `serveLayout` INSIDE a real Worker by importing this very bundle, which
+// is impossible if the top-level class reference throws. The element only ever
+// EXTENDS the real HTMLElement in a browser (a worker never instantiates it), so a
+// guarded base is behaviourally identical on the client and merely importable off it.
+const HTMLElementBase = typeof HTMLElement !== 'undefined'
+    ? HTMLElement
+    : class {
+    };
+class GrafloriaFlowElement extends HTMLElementBase {
+    constructor() {
+        super(...arguments);
+        this.instance = null;
+        this.canvas = null;
+        this._nodes = [];
+        this._edges = [];
+        this.connected = false;
+    }
+    static get observedAttributes() {
+        return [
+            'nodes',
+            'edges',
+            'theme',
+            'fit-view',
+            'readonly',
+            'zoom',
+            'min-zoom',
+            'max-zoom',
+            'pan',
+            'wheel-zoom',
+        ];
+    }
+    // -- properties (the rich path) ---------------------------------------------
+    get nodes() {
+        return this._nodes;
+    }
+    set nodes(value) {
+        var _a;
+        this._nodes = value !== null && value !== void 0 ? value : [];
+        (_a = this.instance) === null || _a === void 0 ? void 0 : _a.setNodes(this._nodes);
+    }
+    get edges() {
+        return this._edges;
+    }
+    set edges(value) {
+        var _a;
+        this._edges = value !== null && value !== void 0 ? value : [];
+        (_a = this.instance) === null || _a === void 0 ? void 0 : _a.setEdges(this._edges);
+    }
+    /** The headless instance — the escape hatch to everything else. */
+    get diagram() {
+        return this.instance;
+    }
+    // -- lifecycle ---------------------------------------------------------------
+    connectedCallback() {
+        if (this.connected)
+            return;
+        this.connected = true;
+        // Attributes may have been parsed before we upgraded.
+        this.readAttributeModel();
+        // Light DOM, not shadow DOM: the diagram's stylesheet is injected into
+        // <head> and its CSS variables cascade — a shadow root would cut both off,
+        // and hosts routinely want to style nodes from their own stylesheet.
+        this.canvas = document.createElement('div');
+        this.canvas.className = 'grafloria-flow-canvas';
+        this.canvas.setAttribute('style', 'position:relative;width:100%;height:100%');
+        this.appendChild(this.canvas);
+        if (!this.style.display)
+            this.style.display = 'block';
+        this.instance = (0, renderer_1.createDiagram)(this.canvas, this.buildOptions());
+        this.wireEvents(this.instance);
+    }
+    disconnectedCallback() {
+        var _a, _b;
+        this.connected = false;
+        (_a = this.instance) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.instance = null;
+        (_b = this.canvas) === null || _b === void 0 ? void 0 : _b.remove();
+        this.canvas = null;
+    }
+    attributeChangedCallback(name, previous, next) {
+        var _a, _b;
+        if (previous === next)
+            return;
+        switch (name) {
+            case 'nodes':
+                this._nodes = parseJsonAttribute(next, []);
+                (_a = this.instance) === null || _a === void 0 ? void 0 : _a.setNodes(this._nodes);
+                return;
+            case 'edges':
+                this._edges = parseJsonAttribute(next, []);
+                (_b = this.instance) === null || _b === void 0 ? void 0 : _b.setEdges(this._edges);
+                return;
+            case 'theme':
+                if (this.instance)
+                    this.instance.setTheme(this.resolveTheme());
+                return;
+            case 'fit-view':
+                if (this.instance && next !== null)
+                    this.instance.fitView();
+                return;
+            case 'zoom':
+                if (this.instance && next !== null)
+                    this.instance.viewport.setZoom(Number(next));
+                return;
+            default:
+                // pan / wheel-zoom / readonly / min-zoom / max-zoom are read at mount:
+                // they configure the event binder, which is created once. Changing them
+                // afterwards is rare enough that we do not tear the instance down.
+                return;
+        }
+    }
+    // -- API ---------------------------------------------------------------------
+    fitView(padding) {
+        var _a;
+        (_a = this.instance) === null || _a === void 0 ? void 0 : _a.fitView(padding);
+    }
+    // -- internals ---------------------------------------------------------------
+    buildOptions() {
+        return {
+            nodes: this._nodes,
+            edges: this._edges,
+            theme: this.resolveTheme(),
+            fitView: this.hasAttribute('fit-view'),
+            readonly: this.hasAttribute('readonly'),
+            enablePan: this.getAttribute('pan') !== 'false',
+            enableZoom: this.getAttribute('wheel-zoom') !== 'false',
+            zoom: this.hasAttribute('zoom') ? Number(this.getAttribute('zoom')) : undefined,
+            minZoom: this.hasAttribute('min-zoom')
+                ? Number(this.getAttribute('min-zoom'))
+                : undefined,
+            maxZoom: this.hasAttribute('max-zoom')
+                ? Number(this.getAttribute('max-zoom'))
+                : undefined,
+            renderCustomNode: (node, element) => this.renderCustomNode(node, element),
+        };
+    }
+    /**
+     * Custom nodes, two ways and no framework: a registered renderer
+     * (`Grafloria.registerNodeType`), or a slotted `<template data-node-type="…">`.
+     */
+    renderCustomNode(node, element) {
+        const renderer = (0, node_type_registry_1.getNodeType)(node.type);
+        if (renderer) {
+            renderer(node, element);
+            return;
+        }
+        const template = this.querySelector(`template[data-node-type="${cssEscape(node.type)}"]`);
+        if (template) {
+            (0, node_type_registry_1.renderFromTemplate)(template, node, element);
+            return;
+        }
+        // Nothing registered: leave the host empty rather than throwing inside a
+        // render. The node still exists, is selectable and is draggable.
+    }
+    resolveTheme() {
+        var _a, _b;
+        return (_b = THEMES[(_a = this.getAttribute('theme')) !== null && _a !== void 0 ? _a : 'light']) !== null && _b !== void 0 ? _b : renderer_1.LIGHT_THEME;
+    }
+    readAttributeModel() {
+        if (this._nodes.length === 0 && this.hasAttribute('nodes')) {
+            this._nodes = parseJsonAttribute(this.getAttribute('nodes'), []);
+        }
+        if (this._edges.length === 0 && this.hasAttribute('edges')) {
+            this._edges = parseJsonAttribute(this.getAttribute('edges'), []);
+        }
+    }
+    /** Instance events → DOM CustomEvents. `composed` so they escape a shadow root. */
+    wireEvents(instance) {
+        const forward = (type, detail) => {
+            this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+        };
+        instance.on('ready', () => forward(exports.GRAFLORIA_EVENTS.ready, { diagram: instance }));
+        instance.on('nodes:change', (payload) => forward(exports.GRAFLORIA_EVENTS.nodesChange, payload));
+        instance.on('edges:change', (payload) => forward(exports.GRAFLORIA_EVENTS.edgesChange, payload));
+        instance.on('selection:change', (payload) => forward(exports.GRAFLORIA_EVENTS.selectionChange, payload));
+        instance.on('connect', (payload) => forward(exports.GRAFLORIA_EVENTS.connect, payload));
+        instance.on('node:click', (payload) => forward(exports.GRAFLORIA_EVENTS.nodeClick, payload));
+        instance.on('edge:click', (payload) => forward(exports.GRAFLORIA_EVENTS.edgeClick, payload));
+        instance.on('viewport:change', (payload) => forward(exports.GRAFLORIA_EVENTS.viewportChange, payload));
+    }
+}
+exports.GrafloriaFlowElement = GrafloriaFlowElement;
+/** JSON attribute → value. A malformed attribute must not take the page down. */
+function parseJsonAttribute(raw, fallback) {
+    if (!raw)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (_a) {
+        console.warn('[grafloria-flow] ignoring malformed JSON attribute:', raw);
+        return fallback;
+    }
+}
+/** Minimal CSS.escape for the attribute selector (jsdom/older browsers lack it). */
+function cssEscape(value) {
+    return value.replace(/["\\]/g, '\\$&');
+}
+/**
+ * Register the element. Idempotent, and safe to call on the server (where
+ * `customElements` does not exist) — which is what lets a bundle be imported
+ * from an SSR entry point without a `typeof window` dance at every call site.
+ */
+function defineGrafloriaFlow(tagName = 'grafloria-flow') {
+    if (typeof customElements === 'undefined')
+        return;
+    if (customElements.get(tagName))
+        return;
+    customElements.define(tagName, GrafloriaFlowElement);
+}
+//# sourceMappingURL=grafloria-flow-element.js.map

package/src/lib/grafloria-flow-element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grafloria-flow-element.js","sourceRoot":"","sources":["../../../../../libs/element/src/lib/grafloria-flow-element.ts"],"names":[],"mappings":"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"}

package/src/lib/grafloria.d.ts

@@ -0,0 +1,61 @@
+import type { CreateDiagramOptions, DiagramInstance, EdgeSpec, NodeSpec, StaticRenderOptions, StaticRenderResult } from '@grafloria/renderer';
+import { defineGrafloriaFlow } from './grafloria-flow-element';
+import { registerNodeType, registeredNodeTypes } from './node-type-registry';
+import type { NodeTypeRenderer } from './node-type-registry';
+/**
+ * `Grafloria` — the Mermaid-shaped top-level API.
+ *
+ * Mermaid's moat is not its renderer, it is `mermaid.render(id, text)`: one
+ * function, no build step, no framework. That is why it shows up in GitHub
+ * comments, in docs sites, in notebooks and in every CMS. This is the same
+ * surface for a diagram that is *interactive*:
+ *
+ * ```html
+ * <script type="module">
+ *   import { Grafloria } from 'https://esm.sh/@grafloria/element';
+ *
+ *   Grafloria.registerNodeType('card', (node, el) => {
+ *     el.innerHTML = `<div class="card">${node.data.title}</div>`;
+ *   });
+ *
+ *   const diagram = Grafloria.render(
+ *     { nodes: [...], edges: [...] },
+ *     document.getElementById('chart')
+ *   );
+ *   diagram.on('connect', ({ link }) => save(link));
+ * </script>
+ * ```
+ *
+ * `render()` returns the same `DiagramInstance` every wrapper binds to, so the
+ * "tiny API" is not a lesser one — it is the whole engine, addressed in one call.
+ */
+/** What `Grafloria.render()` accepts: an object spec, or the JSON string of one. */
+export interface DiagramSpec {
+    nodes?: NodeSpec[];
+    edges?: EdgeSpec[];
+}
+export type RenderSpec = DiagramSpec | string;
+export type RenderOptions = Omit<CreateDiagramOptions, 'nodes' | 'edges'>;
+/**
+ * Mount `spec` into `target` and return the live instance.
+ *
+ * `target` may be an element or a CSS selector. Custom nodes (`custom: true`)
+ * are rendered by the types registered with {@link registerNodeType}.
+ *
+ * SCOPE, stated plainly: `spec` is data (an object or its JSON), not a Mermaid-
+ * style text DSL. The engine does have a DSL, but wiring it in is a separate
+ * card — `render()` is the embedding surface, not a parser.
+ */
+export declare function render(spec: RenderSpec, target: HTMLElement | string, options?: RenderOptions): DiagramInstance;
+/** Server-side render (Card 6). Re-exported so the tiny API is self-contained. */
+export declare function renderStatic(options?: StaticRenderOptions): StaticRenderResult;
+/** The namespace object, for `import { Grafloria }` and for `<script>` globals. */
+export declare const Grafloria: {
+    render: typeof render;
+    renderStatic: typeof renderStatic;
+    registerNodeType: typeof registerNodeType;
+    registeredNodeTypes: typeof registeredNodeTypes;
+    /** Register `<grafloria-flow>` (called for you when you import this package). */
+    define: typeof defineGrafloriaFlow;
+};
+export type { NodeTypeRenderer };

package/src/lib/grafloria.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Grafloria = void 0;
+exports.render = render;
+exports.renderStatic = renderStatic;
+const renderer_1 = require("@grafloria/renderer");
+const grafloria_flow_element_1 = require("./grafloria-flow-element");
+const node_type_registry_1 = require("./node-type-registry");
+/**
+ * Mount `spec` into `target` and return the live instance.
+ *
+ * `target` may be an element or a CSS selector. Custom nodes (`custom: true`)
+ * are rendered by the types registered with {@link registerNodeType}.
+ *
+ * SCOPE, stated plainly: `spec` is data (an object or its JSON), not a Mermaid-
+ * style text DSL. The engine does have a DSL, but wiring it in is a separate
+ * card — `render()` is the embedding surface, not a parser.
+ */
+function render(spec, target, options = {}) {
+    var _a, _b, _c, _d;
+    const element = typeof target === 'string'
+        ? document.querySelector(target)
+        : target;
+    if (!element) {
+        throw new Error(`Grafloria.render: no element matched ${JSON.stringify(target)}`);
+    }
+    const parsed = typeof spec === 'string' ? parseSpec(spec) : spec;
+    const instance = (0, renderer_1.createDiagram)(element, Object.assign(Object.assign({}, options), { nodes: (_a = parsed.nodes) !== null && _a !== void 0 ? _a : [], edges: (_b = parsed.edges) !== null && _b !== void 0 ? _b : [], 
+        // Wire the global registry in, so `registerNodeType` works for the tiny API
+        // exactly as it does for `<grafloria-flow>` — unless the caller supplies their
+        // own. A KIT SPEC may also carry its own painter (dashboard() does: every
+        // widget is a custom HTML node), and it must be honoured — otherwise the
+        // documented one-liner `render(dashboard({…}), host)` mounts a board whose
+        // widgets never paint. Precedence: explicit option > spec > registry.
+        renderCustomNode: (_d = (_c = options.renderCustomNode) !== null && _c !== void 0 ? _c : parsed.renderCustomNode) !== null && _d !== void 0 ? _d : ((node, host) => { var _a; return (_a = (0, node_type_registry_1.getNodeType)(node.type)) === null || _a === void 0 ? void 0 : _a(node, host); }) }));
+    // Diagram-kit specs (erDiagram/umlDiagram) carry a `finalize(api)` for the
+    // post-render wiring that needs the LIVE instance — row interactions,
+    // multiplicity chips. Auto-run it so a kit diagram is fully wired from one
+    // render() call; finalize is idempotent, so a caller may still call it too.
+    const maybeFinalize = spec.finalize;
+    if (typeof maybeFinalize === 'function') {
+        try {
+            maybeFinalize(instance);
+        }
+        catch (_e) {
+            /* a kit's finalize must never break the mount */
+        }
+    }
+    return instance;
+}
+/** Server-side render (Card 6). Re-exported so the tiny API is self-contained. */
+function renderStatic(options = {}) {
+    return (0, renderer_1.renderToStaticSVG)(options);
+}
+function parseSpec(spec) {
+    try {
+        return JSON.parse(spec);
+    }
+    catch (error) {
+        throw new Error(`Grafloria.render: spec must be an object or a JSON string (${error.message})`);
+    }
+}
+/** The namespace object, for `import { Grafloria }` and for `<script>` globals. */
+exports.Grafloria = {
+    render,
+    renderStatic,
+    registerNodeType: node_type_registry_1.registerNodeType,
+    registeredNodeTypes: node_type_registry_1.registeredNodeTypes,
+    /** Register `<grafloria-flow>` (called for you when you import this package). */
+    define: grafloria_flow_element_1.defineGrafloriaFlow,
+};
+//# sourceMappingURL=grafloria.js.map

package/src/lib/grafloria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grafloria.js","sourceRoot":"","sources":["../../../../../libs/element/src/lib/grafloria.ts"],"names":[],"mappings":";;;AA6DA,wBA8CC;AAGD,oCAEC;AAhHD,kDAAuE;AASvE,qEAA+D;AAC/D,6DAA0F;AAyC1F;;;;;;;;;GASG;AACH,SAAgB,MAAM,CACpB,IAAgB,EAChB,MAA4B,EAC5B,UAAyB,EAAE;;IAE3B,MAAM,OAAO,GACX,OAAO,MAAM,KAAK,QAAQ;QACxB,CAAC,CAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAwB;QACxD,CAAC,CAAC,MAAM,CAAC;IAEb,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,MAAM,GAAgB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9E,MAAM,QAAQ,GAAG,IAAA,wBAAa,EAAC,OAAO,kCACjC,OAAO,KACV,KAAK,EAAE,MAAA,MAAM,CAAC,KAAK,mCAAI,EAAE,EACzB,KAAK,EAAE,MAAA,MAAM,CAAC,KAAK,mCAAI,EAAE;QACzB,4EAA4E;QAC5E,+EAA+E;QAC/E,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,sEAAsE;QACtE,gBAAgB,EACd,MAAA,MAAA,OAAO,CAAC,gBAAgB,mCACvB,MAAmE,CAAC,gBAAgB,mCACrF,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,WAAC,OAAA,MAAA,IAAA,gCAAW,EAAC,IAAI,CAAC,IAAI,CAAC,0CAAG,IAAI,EAAE,IAAI,CAAC,CAAA,EAAA,CAAC,IACxD,CAAC;IAEH,2EAA2E;IAC3E,sEAAsE;IACtE,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,aAAa,GAAI,IAA8C,CAAC,QAAQ,CAAC;IAC/E,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;QAAC,WAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kFAAkF;AAClF,SAAgB,YAAY,CAAC,UAA+B,EAAE;IAC5D,OAAO,IAAA,4BAAiB,EAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAgB,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,8DAA+D,KAAe,CAAC,OAAO,GAAG,CAC1F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,mFAAmF;AACtE,QAAA,SAAS,GAAG;IACvB,MAAM;IACN,YAAY;IACZ,gBAAgB,EAAhB,qCAAgB;IAChB,mBAAmB,EAAnB,wCAAmB;IACnB,iFAAiF;IACjF,MAAM,EAAE,4CAAmB;CAC5B,CAAC"}

package/src/lib/load.d.ts

@@ -0,0 +1,72 @@
+import type { DiagramDocumentEnvelope, DiagramModel, LinkModel, NodeModel, SerializedDiagramData } from '@grafloria/engine';
+import { type DashboardGridHandle } from './dashboard-kit/grid-binder';
+import { type WidgetRenderer } from './dashboard-kit/widgets';
+import { type DashboardHandle } from './dashboard-kit/dashboard';
+/** Anything `DiagramSerializer.deserialize()` accepts, or the JSON string of it. */
+export type SavedDiagram = SerializedDiagramData | DiagramDocumentEnvelope | Record<string, unknown> | string;
+export interface FromDocumentOptions {
+    /**
+     * The app's own widget painter — the same function it passed to
+     * `dashboard({ renderWidget })`. A board authored with a custom painter must
+     * be RELOADED with it, or the reload silently drops the app's chrome.
+     */
+    renderWidget?: WidgetRenderer;
+    /** Full override of the custom-node painter. Outranks everything. */
+    renderCustomNode?: (node: NodeModel, host: HTMLElement) => void;
+    /**
+     * Re-attach kit interaction wiring (row selection, in-canvas editing, the
+     * dashboard grid binder). Default true — a loaded diagram should behave like
+     * the one that was saved. Pass false for a read-only viewer.
+     */
+    interactive?: boolean;
+}
+/** What {@link fromDocument} returns: a `render()` spec, plus the way back in. */
+export interface LoadedDiagramSpec {
+    nodes: NodeModel[];
+    edges: LinkModel[];
+    renderCustomNode: (node: NodeModel, host: HTMLElement) => void;
+    finalize: (api: unknown) => void;
+    /** The deserialized model — the escape hatch, available before any render. */
+    readonly model: DiagramModel;
+    /**
+     * Live grid binders for the boards `finalize()` re-attached, keyed by group
+     * id. Empty for a document that is not a dashboard.
+     *
+     * This is the SAME Map instance the handle drives (`handle.binderOf` returns
+     * from it), so the two can never disagree — `boards` is now derived from the
+     * handle's own binders rather than a parallel copy.
+     */
+    readonly boards: Map<string, DashboardGridHandle>;
+    /**
+     * The dashboard toolbar handle over the reloaded board(s) — the SAME
+     * `DashboardHandle` `dashboard()` returns, built by the one shared builder so
+     * it cannot drift from the authoring surface: addWidget/showView/setSizing/
+     * setColumns/toJSON/exportIds and the widget handles, all live on the reload.
+     *
+     * INERT (empty `views`, every op a no-op) for a document that is not a
+     * dashboard — an ER/UML load carries no board, so an honest empty handle
+     * beats one that pretends a class card is a widget.
+     *
+     * Two carried limits, both because the datum is not in the document:
+     *  - `responsive` is a runtime seam, never serialised, so a reloaded board is
+     *    fixed at its saved column count until `setColumns`/`responsive` is
+     *    re-supplied; `toJSON()` therefore omits it.
+     *  - `renderWidget`/`onLayoutChange` are functions and cannot serialise —
+     *    pass `renderWidget` to `fromDocument({ renderWidget })` to reattach the
+     *    app's own painter, exactly as `dashboard({ renderWidget })` did.
+     */
+    readonly handle: DashboardHandle;
+}
+/**
+ * Turn a saved document back into something `render()` can mount.
+ *
+ * ```ts
+ * const json = JSON.stringify(new DiagramSerializer().serialize(api.getModel()));
+ * // …later, in a fresh page:
+ * render(fromDocument(json), host);
+ * ```
+ *
+ * Accepts the flat serializer form, the portable envelope, or the JSON string
+ * of either.
+ */
+export declare function fromDocument(document: SavedDiagram, options?: FromDocumentOptions): LoadedDiagramSpec;