@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/ext/capability-factory.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 0 — the FACADE. This is where capability objects meet the real registries.
+ * ============================================================================
+ *
+ * Read this file as the answer to "did they rewrite the registries?" — no. Every
+ * method below is a delegation to the registry that already existed, wrapped in
+ * exactly two things it did not have:
+ *
+ *   1. a DISPOSER, and
+ *   2. RESTORE-ON-DISPOSE (put back what was there before, don't just delete).
+ *
+ * `buildCapabilities` also enforces the grant: it materialises ONLY the keys the
+ * manifest declared. An extension that did not ask for `routers` does not get a
+ * `routers` object it could call — the property is absent, not merely typed away.
+ *
+ * ---------------------------------------------------------------------------
+ * WHOSE REGISTRY — the thing that used to be missing
+ * ---------------------------------------------------------------------------
+ * Every delegation below now goes through `bindings.registry`, which is
+ * `diagram.registry` when the host was bound to one and the process-global
+ * registry otherwise. Both are the SAME class (see `diagram-registry.ts`), so
+ * there is one implementation of restore-on-dispose rather than one per scope.
+ *
+ * That single indirection is the whole per-diagram isolation fix. Before it,
+ * two hosts on one page wrote the same module-global map: the second
+ * registration silently repainted the first diagram, and the first host's
+ * `dispose()` — faithfully restoring what was there before IT registered —
+ * deleted the second diagram's shape out from under it.
+ *
+ * NOT YET ROUTED: `tools` and `registerConnectionValidator`. Those registries are
+ * read on the INTERACTION path (`resolveTool` on pointerdown, `isValidConnection`
+ * during snapping), not inside the render pass, so scoping their storage without
+ * also scoping those four read sites would make a scoped tool invisible — a
+ * worse bug than the one being fixed. They are still process-global and still
+ * collide between diagrams; see the note on `tools` below.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapabilities = buildCapabilities;
+const tools_1 = require("./tools");
+const portal_1 = require("./portal");
+const diagram_registry_1 = require("./diagram-registry");
+/**
+ * Build the capability objects for ONE extension, tracking every registration in
+ * that extension's own {@link DisposableStore}.
+ */
+function buildCapabilities(granted, bindings, store) {
+    var _a;
+    const capabilities = {};
+    const wanted = new Set(granted);
+    // Any contribution that changes the picture should schedule a repaint —
+    // otherwise a shape registered after mount would not appear until something
+    // else happened to dirty the scene. (That is the dead-config failure mode in
+    // miniature, and it is why this is threaded through every register().)
+    const track = (disposer) => {
+        var _a;
+        (_a = bindings.requestRender) === null || _a === void 0 ? void 0 : _a.call(bindings);
+        return store.add(() => {
+            var _a;
+            disposer();
+            (_a = bindings.requestRender) === null || _a === void 0 ? void 0 : _a.call(bindings);
+        });
+    };
+    // The registry this host contributes to: the diagram's own when it was bound
+    // to one, else the process-wide one. Same class, same disposer semantics.
+    const registry = (_a = bindings.registry) !== null && _a !== void 0 ? _a : diagram_registry_1.GLOBAL_DIAGRAM_REGISTRY;
+    // -- shapes ---------------------------------------------------------------
+    if (wanted.has('shapes')) {
+        capabilities.shapes = {
+            register: (type, definition) => track(registry.registerShape(type, definition)),
+            registerPath: (type, geometry, options) => track(registry.registerPathShape(type, geometry, options)),
+            has: (type) => registry.hasShape(type),
+            list: () => registry.listShapes(),
+        };
+    }
+    // -- links ----------------------------------------------------------------
+    if (wanted.has('links')) {
+        capabilities.links = {
+            registerTemplate: (name, template) => track(registry.registerLinkTemplate(name, template)),
+            registerLabelTemplate: (name, template) => track(registry.registerLabelTemplate(name, template)),
+            registerMarker: (name, definition) => track(registry.registerMarker(name, definition)),
+            registerConnector: (name, connector) => track(registry.registerConnector(name, connector)),
+            registerAnchor: (name, anchor) => track(registry.registerAnchor(name, anchor)),
+            registerConnectionPoint: (name, strategy) => track(registry.registerConnectionPoint(name, strategy)),
+            listConnectors: () => registry.listConnectors(),
+            listAnchors: () => registry.listAnchors(),
+            listConnectionPoints: () => registry.listConnectionPoints(),
+        };
+    }
+    // -- routers --------------------------------------------------------------
+    if (wanted.has('routers')) {
+        const routing = bindings.engine.getRoutingEngine();
+        capabilities.routers = {
+            register(name, router) {
+                // NOTE: `RoutingEngine.registerRouter` THROWS on a duplicate name (it is
+                // the one registry that refuses to overwrite). We keep that contract
+                // rather than papering over it — but we do give back a real disposer,
+                // which it never had.
+                routing.registerRouter(name, router);
+                return track(() => {
+                    routing.unregisterRouter(name);
+                });
+            },
+            list: () => routing.getAvailableAlgorithms(),
+            has: (name) => routing.getAvailableAlgorithms().includes(name),
+        };
+    }
+    // -- templates ------------------------------------------------------------
+    if (wanted.has('templates')) {
+        // Guaranteed present: the host's `assertGrantable` refuses to register an
+        // extension that declares `templates` without one bound.
+        const templates = bindings.templateRegistry;
+        if (!templates) {
+            throw new Error("[ExtensionHost] 'templates' capability requires a TemplateRegistry");
+        }
+        capabilities.templates = {
+            register(template) {
+                templates.register(template);
+                return track(() => {
+                    templates.unregister(template.id);
+                });
+            },
+            list: () => templates.getAll(),
+            has: (id) => templates.has(id),
+        };
+    }
+    // -- animations -----------------------------------------------------------
+    if (wanted.has('animations')) {
+        const animations = registry.animations;
+        capabilities.animations = {
+            register(definition) {
+                animations.register(definition);
+                return track(() => {
+                    animations.unregister(definition.name);
+                });
+            },
+            has: (name) => animations.has(name),
+            list: () => animations.getAll(),
+        };
+    }
+    // -- tools ----------------------------------------------------------------
+    //
+    // STILL PROCESS-GLOBAL, deliberately. `resolveTool` (pointerdown) and
+    // `isValidConnection` (snapping) read these from the interaction path, which the
+    // render pass's registry scope does not cover — so partitioning the storage here
+    // without also scoping those readers would hide a scoped tool from the very
+    // gesture it was registered for. Two diagrams still share tools and validators;
+    // that is a known remaining collision, not an oversight.
+    if (wanted.has('tools')) {
+        capabilities.tools = {
+            register: (tool) => track((0, tools_1.registerTool)(tool)),
+            registerConnectionValidator: (validator) => track((0, tools_1.registerConnectionValidator)(validator)),
+            list: tools_1.listTools,
+            has: tools_1.hasTool,
+        };
+    }
+    // -- panels ---------------------------------------------------------------
+    if (wanted.has('panels')) {
+        const root = bindings.root;
+        if (!root) {
+            // The host already refused to register this extension (assertGrantable),
+            // so reaching here means the bindings changed underneath us.
+            throw new Error("[ExtensionHost] 'panels' capability requires a DOM root");
+        }
+        capabilities.panels = {
+            createPanel(options) {
+                const portal = (0, portal_1.createPortal)(root, options);
+                store.add(() => portal.dispose());
+                return portal;
+            },
+            createViewportPanel(options) {
+                const layer = bindings.htmlLayer;
+                if (!layer)
+                    throw new Error("[ExtensionHost] world-space panels require the HTML layer");
+                const portal = (0, portal_1.createViewportPortal)(layer, options);
+                store.add(() => portal.dispose());
+                return portal;
+            },
+            createCounterScaledPanel(options) {
+                const layer = bindings.htmlLayer;
+                const viewport = bindings.viewport;
+                if (!layer || !viewport) {
+                    throw new Error('[ExtensionHost] counter-scaled panels require the HTML layer and the camera');
+                }
+                const portal = (0, portal_1.createCounterScaledPortal)(layer, viewport, options);
+                store.add(() => portal.dispose());
+                return portal;
+            },
+        };
+    }
+    return capabilities;
+}
+//# sourceMappingURL=capability-factory.js.map

package/src/libs/renderer/src/ext/components/attach.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ============================================================================
+ * Card 6 — attaching the plugin components to a live diagram
+ * ============================================================================
+ *
+ * `attachCanvasPlugins(instance, options)` mounts Background / MiniMap /
+ * Controls onto a `createDiagram()` instance and — critically — WIRES THEM TO
+ * THE ENGINE'S OWN STATE, closing three dead-config bugs the audit flagged:
+ *
+ *   DiagramStore.gridEnabled   was: `true`,  read by NOBODY  → now: shows/hides Background
+ *   DiagramStore.showMinimap   was: `false`, read by NOBODY  → now: shows/hides MiniMap
+ *   DiagramStore.snapEnabled   was: `true`,  read by NOBODY  → now: gates grid snapping
+ *                                                                (see `snapEnabled` below)
+ *
+ * These three flags were the textbook instance of this codebase's #1 bug shape:
+ * config declared, defaulted, serialized, and never consumed. They are now
+ * two-way live — flip `engine.getStore().set('showMinimap', true)` and the
+ * minimap appears; the Controls' lock button writes back to `store.locked`.
+ *
+ * The whole attachment is ONE disposer. Every subscription made here (store
+ * watches, model listeners, camera listeners, DOM listeners inside the
+ * components) is unwound by it — that is the leak-free rule, and
+ * `attach.spec.ts` asserts the store has no listeners left afterwards.
+ */
+import type { DiagramEngine, DiagramModel } from '@grafloria/engine';
+import type { DiagramInstance } from '../../instance/create-diagram';
+import type { Disposer } from '../disposable';
+import type { BackgroundOptions, BackgroundHandle } from './background';
+import type { MiniMapOptions, MiniMapHandle } from './minimap';
+import type { ControlsOptions, ControlsHandle } from './controls';
+export interface CanvasPluginOptions {
+    /**
+     * Background grid. `true` = defaults; an object = options; omitted/false = off.
+     * When the engine's `gridEnabled` flag is present it OVERRIDES visibility.
+     */
+    background?: boolean | BackgroundOptions;
+    /** MiniMap. Visibility is additionally gated by the store's `showMinimap`. */
+    minimap?: boolean | MiniMapOptions;
+    /** Zoom/fit/lock toolbar. */
+    controls?: boolean | ControlsOptions;
+    /**
+     * Honour `DiagramStore.gridEnabled` / `showMinimap` and keep them in sync.
+     * Default true — this is what makes the flags real. Turn it off if you want
+     * the component visibility to be purely declarative.
+     */
+    bindToStore?: boolean;
+}
+export interface CanvasPlugins {
+    background?: BackgroundHandle;
+    minimap?: MiniMapHandle;
+    controls?: ControlsHandle;
+    dispose: Disposer;
+}
+/**
+ * The structural surface the plugins actually need. `DiagramInstance`
+ * satisfies it; so does any framework canvas that keeps a live
+ * `ViewportController` (the Angular wrapper builds exactly this adapter).
+ */
+export interface CanvasPluginHost {
+    container: HTMLElement;
+    viewport: DiagramInstance['viewport'];
+    getModel(): DiagramModel;
+    getEngine(): DiagramEngine;
+    fitView(padding?: number): void;
+}
+export declare function attachCanvasPlugins(instance: CanvasPluginHost, options?: CanvasPluginOptions): CanvasPlugins;

package/src/libs/renderer/src/ext/components/attach.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 6 — attaching the plugin components to a live diagram
+ * ============================================================================
+ *
+ * `attachCanvasPlugins(instance, options)` mounts Background / MiniMap /
+ * Controls onto a `createDiagram()` instance and — critically — WIRES THEM TO
+ * THE ENGINE'S OWN STATE, closing three dead-config bugs the audit flagged:
+ *
+ *   DiagramStore.gridEnabled   was: `true`,  read by NOBODY  → now: shows/hides Background
+ *   DiagramStore.showMinimap   was: `false`, read by NOBODY  → now: shows/hides MiniMap
+ *   DiagramStore.snapEnabled   was: `true`,  read by NOBODY  → now: gates grid snapping
+ *                                                                (see `snapEnabled` below)
+ *
+ * These three flags were the textbook instance of this codebase's #1 bug shape:
+ * config declared, defaulted, serialized, and never consumed. They are now
+ * two-way live — flip `engine.getStore().set('showMinimap', true)` and the
+ * minimap appears; the Controls' lock button writes back to `store.locked`.
+ *
+ * The whole attachment is ONE disposer. Every subscription made here (store
+ * watches, model listeners, camera listeners, DOM listeners inside the
+ * components) is unwound by it — that is the leak-free rule, and
+ * `attach.spec.ts` asserts the store has no listeners left afterwards.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachCanvasPlugins = attachCanvasPlugins;
+const disposable_1 = require("../disposable");
+const background_1 = require("./background");
+const minimap_1 = require("./minimap");
+const controls_1 = require("./controls");
+/** The diagram root element the instance mounted (portals attach to this). */
+function rootOf(instance) {
+    var _a;
+    const root = instance.container.querySelector('.grafloria-diagram-root');
+    // Fall back to the container itself: a host may have handed us the root.
+    return (_a = root) !== null && _a !== void 0 ? _a : instance.container;
+}
+function attachCanvasPlugins(instance, options = {}) {
+    var _a, _b, _c, _d;
+    const store = new disposable_1.DisposableStore();
+    const root = rootOf(instance);
+    const engine = instance.getEngine();
+    const bind = (_a = options.bindToStore) !== null && _a !== void 0 ? _a : true;
+    const diagramStore = bind && typeof engine.getStore === 'function' ? engine.getStore() : undefined;
+    const plugins = { dispose: () => store.dispose() };
+    // -- Background -------------------------------------------------------------
+    if (options.background) {
+        const backgroundOptions = typeof options.background === 'object' ? options.background : {};
+        const background = (0, background_1.createBackground)(root, instance.viewport, backgroundOptions);
+        plugins.background = background;
+        store.add(() => background.dispose());
+        if (diagramStore) {
+            // Initial state comes FROM the store — the flag is now the source of truth.
+            const enabled = diagramStore.get('gridEnabled');
+            if (typeof enabled === 'boolean')
+                background.setVisible(enabled);
+            store.add(diagramStore.watch('gridEnabled', (value) => {
+                background.setVisible(value !== false);
+            }));
+        }
+    }
+    // -- MiniMap ----------------------------------------------------------------
+    if (options.minimap) {
+        const minimapOptions = typeof options.minimap === 'object' ? options.minimap : {};
+        const minimap = (0, minimap_1.createMiniMap)(root, instance.viewport, () => instance.getModel(), minimapOptions);
+        plugins.minimap = minimap;
+        store.add(() => minimap.dispose());
+        // The minimap's node layer is rebuilt on MODEL change only (panning must not
+        // be O(nodes) — see minimap.ts). These are the events that move a node rect.
+        for (const event of [
+            'node:added',
+            'node:removed',
+            'node:changed',
+            'link:added',
+            'link:removed',
+            'link:changed',
+            'selection:changed',
+        ]) {
+            store.add(instance.getModel().on(event, () => minimap.refresh()));
+        }
+        if (diagramStore) {
+            const show = diagramStore.get('showMinimap');
+            // `showMinimap` DEFAULTS TO FALSE in the store. Respect an explicit
+            // `minimap: true` from the caller by writing the flag rather than letting
+            // the default silently hide what they just asked for.
+            if (show === false)
+                diagramStore.set('showMinimap', true);
+            store.add(diagramStore.watch('showMinimap', (value) => {
+                minimap.setVisible(value !== false);
+            }));
+        }
+    }
+    // -- Controls ---------------------------------------------------------------
+    if (options.controls) {
+        const controlOptions = typeof options.controls === 'object' ? options.controls : {};
+        const controls = (0, controls_1.createControls)(root, instance.viewport, Object.assign(Object.assign({}, controlOptions), { onFitView: (_b = controlOptions.onFitView) !== null && _b !== void 0 ? _b : (() => instance.fitView()), onToggleLock: (_c = controlOptions.onToggleLock) !== null && _c !== void 0 ? _c : ((locked) => {
+                // Write through to the engine's own lock flag rather than inventing a
+                // second source of truth.
+                diagramStore === null || diagramStore === void 0 ? void 0 : diagramStore.set('locked', locked);
+            }), locked: (_d = controlOptions.locked) !== null && _d !== void 0 ? _d : Boolean(diagramStore === null || diagramStore === void 0 ? void 0 : diagramStore.get('locked')) }));
+        plugins.controls = controls;
+        store.add(() => controls.dispose());
+        if (diagramStore) {
+            store.add(diagramStore.watch('locked', (value) => {
+                controls.setLocked(value === true);
+            }));
+        }
+    }
+    return plugins;
+}
+//# sourceMappingURL=attach.js.map

package/src/libs/renderer/src/ext/components/background.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ============================================================================
+ * Card 6 — <Background>: the rendered grid. GAP CLOSED.
+ * ============================================================================
+ *
+ * The audit's finding was blunt: "no background grid". The engine had a
+ * `gridEnabled` flag on `DiagramStore` with ZERO consumers — declared, defaulted
+ * to `true`, and read by nobody. There were `gridSize` values all over the
+ * renderer, but every one of them belonged to the A-star / Manhattan ROUTING
+ * grid, not to anything drawn on screen. Nothing ever painted a pixel of grid.
+ *
+ * This is that grid, and it is wired to `DiagramStore.gridEnabled`, so the flag
+ * now means something (see `attachBackground`, which subscribes to the store).
+ *
+ * ---------------------------------------------------------------------------
+ * How it tracks the camera
+ * ---------------------------------------------------------------------------
+ * The background lives in its own layer BELOW the SVG layer, and is a single
+ * `<rect>` filled with an SVG `<pattern>`. It is NOT re-tessellated per frame:
+ * a pattern tile of `gap * zoom` CSS px, offset by the camera's fractional
+ * remainder, gives an infinite grid for the cost of two attribute writes.
+ *
+ *     tile   = gap * zoom
+ *     offset = -(world.x * zoom) mod tile     (likewise y)
+ *
+ * The modulo is what makes it infinite: only the SUB-TILE remainder matters, so
+ * the numbers stay small no matter how far you pan. Panning to x = 10^7 does not
+ * produce a 10^7-px pattern offset and lose float precision.
+ *
+ * ---------------------------------------------------------------------------
+ * Why not draw it into the main VNode tree?
+ * ---------------------------------------------------------------------------
+ * Because the patcher reconciles that tree every frame against the diagram
+ * model, and the grid is not part of the model. Keeping it in a sibling layer
+ * means (a) zero interaction with the reconciler's keyed diff, (b) it costs
+ * nothing when the model changes, and (c) it cannot be picked or hit-tested —
+ * it is `pointer-events: none`, so it can never eat a click.
+ */
+import type { ViewportController } from '../../viewport/viewport-controller';
+export declare const BACKGROUND_LAYER_CLASS = "grafloria-background-layer";
+export type BackgroundVariant = 'dots' | 'lines' | 'cross' | 'none';
+export interface BackgroundOptions {
+    /** Pattern style. Default `'dots'`. */
+    variant?: BackgroundVariant;
+    /** Grid spacing in WORLD units. Default 20. */
+    gap?: number;
+    /** Dot radius / line thickness in CSS px. Default 1 (dots) or 1 (lines). */
+    size?: number;
+    /** Pattern colour. Default a theme-neutral grey. */
+    color?: string;
+    /** Page colour painted under the pattern. Default transparent. */
+    backgroundColor?: string;
+    /**
+     * Draw a heavier line every N cells (graph-paper look). 0 = off (default).
+     * Only meaningful for `'lines'` / `'cross'`.
+     */
+    majorEvery?: number;
+    /** Colour of the major lines. Defaults to `color` at higher opacity. */
+    majorColor?: string;
+    /**
+     * Hide the grid below this zoom, so it does not turn into visual mud when you
+     * zoom way out. Default 0.25. Set 0 to always draw.
+     */
+    minZoom?: number;
+    /** Unique-ish suffix for the pattern id, when several diagrams share a page. */
+    idSuffix?: string;
+}
+export interface BackgroundHandle {
+    readonly element: SVGSVGElement;
+    /** Change any option; re-renders immediately. */
+    update(options: Partial<BackgroundOptions>): void;
+    /** Show/hide without tearing down (this is what `gridEnabled` drives). */
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    dispose(): void;
+}
+/**
+ * Create the background grid inside `root`, tracking `viewport`.
+ *
+ * Returns a handle whose `dispose()` unsubscribes from the camera — the
+ * subscription is the leak that Wave 6's "every register() returns a disposer"
+ * rule exists to prevent.
+ */
+export declare function createBackground(root: HTMLElement, viewport: ViewportController, options?: BackgroundOptions): BackgroundHandle;

package/src/libs/renderer/src/ext/components/background.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 6 — <Background>: the rendered grid. GAP CLOSED.
+ * ============================================================================
+ *
+ * The audit's finding was blunt: "no background grid". The engine had a
+ * `gridEnabled` flag on `DiagramStore` with ZERO consumers — declared, defaulted
+ * to `true`, and read by nobody. There were `gridSize` values all over the
+ * renderer, but every one of them belonged to the A-star / Manhattan ROUTING
+ * grid, not to anything drawn on screen. Nothing ever painted a pixel of grid.
+ *
+ * This is that grid, and it is wired to `DiagramStore.gridEnabled`, so the flag
+ * now means something (see `attachBackground`, which subscribes to the store).
+ *
+ * ---------------------------------------------------------------------------
+ * How it tracks the camera
+ * ---------------------------------------------------------------------------
+ * The background lives in its own layer BELOW the SVG layer, and is a single
+ * `<rect>` filled with an SVG `<pattern>`. It is NOT re-tessellated per frame:
+ * a pattern tile of `gap * zoom` CSS px, offset by the camera's fractional
+ * remainder, gives an infinite grid for the cost of two attribute writes.
+ *
+ *     tile   = gap * zoom
+ *     offset = -(world.x * zoom) mod tile     (likewise y)
+ *
+ * The modulo is what makes it infinite: only the SUB-TILE remainder matters, so
+ * the numbers stay small no matter how far you pan. Panning to x = 10^7 does not
+ * produce a 10^7-px pattern offset and lose float precision.
+ *
+ * ---------------------------------------------------------------------------
+ * Why not draw it into the main VNode tree?
+ * ---------------------------------------------------------------------------
+ * Because the patcher reconciles that tree every frame against the diagram
+ * model, and the grid is not part of the model. Keeping it in a sibling layer
+ * means (a) zero interaction with the reconciler's keyed diff, (b) it costs
+ * nothing when the model changes, and (c) it cannot be picked or hit-tested —
+ * it is `pointer-events: none`, so it can never eat a click.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKGROUND_LAYER_CLASS = void 0;
+exports.createBackground = createBackground;
+const disposable_1 = require("../disposable");
+exports.BACKGROUND_LAYER_CLASS = 'grafloria-background-layer';
+const SVG_NS = 'http://www.w3.org/2000/svg';
+let backgroundSeq = 0;
+/**
+ * Create the background grid inside `root`, tracking `viewport`.
+ *
+ * Returns a handle whose `dispose()` unsubscribes from the camera — the
+ * subscription is the leak that Wave 6's "every register() returns a disposer"
+ * rule exists to prevent.
+ */
+function createBackground(root, viewport, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const doc = root.ownerDocument;
+    let opts = {
+        variant: (_a = options.variant) !== null && _a !== void 0 ? _a : 'dots',
+        gap: (_b = options.gap) !== null && _b !== void 0 ? _b : 20,
+        size: (_c = options.size) !== null && _c !== void 0 ? _c : 1,
+        color: (_d = options.color) !== null && _d !== void 0 ? _d : 'rgba(120,130,145,0.45)',
+        majorEvery: (_e = options.majorEvery) !== null && _e !== void 0 ? _e : 0,
+        minZoom: (_f = options.minZoom) !== null && _f !== void 0 ? _f : 0.25,
+        majorColor: options.majorColor,
+        backgroundColor: options.backgroundColor,
+        idSuffix: options.idSuffix,
+    };
+    const uid = (_g = opts.idSuffix) !== null && _g !== void 0 ? _g : `bg${++backgroundSeq}`;
+    const patternId = `grafloria-grid-${uid}`;
+    const majorId = `grafloria-grid-major-${uid}`;
+    // -- layer (below the SVG layer) --------------------------------------------
+    let layer = root.querySelector(`:scope > .${exports.BACKGROUND_LAYER_CLASS}`);
+    if (!layer) {
+        layer = doc.createElement('div');
+        layer.className = exports.BACKGROUND_LAYER_CLASS;
+        layer.setAttribute('style', 'position:absolute;inset:0;pointer-events:none;overflow:hidden');
+        // FIRST child ⇒ painted under the diagram.
+        root.insertBefore(layer, root.firstChild);
+    }
+    const svg = doc.createElementNS(SVG_NS, 'svg');
+    svg.setAttribute('width', '100%');
+    svg.setAttribute('height', '100%');
+    svg.setAttribute('class', 'grafloria-background');
+    svg.style.display = 'block';
+    const defs = doc.createElementNS(SVG_NS, 'defs');
+    const pattern = doc.createElementNS(SVG_NS, 'pattern');
+    pattern.setAttribute('id', patternId);
+    pattern.setAttribute('patternUnits', 'userSpaceOnUse');
+    const majorPattern = doc.createElementNS(SVG_NS, 'pattern');
+    majorPattern.setAttribute('id', majorId);
+    majorPattern.setAttribute('patternUnits', 'userSpaceOnUse');
+    defs.appendChild(pattern);
+    defs.appendChild(majorPattern);
+    svg.appendChild(defs);
+    const bgRect = doc.createElementNS(SVG_NS, 'rect');
+    bgRect.setAttribute('width', '100%');
+    bgRect.setAttribute('height', '100%');
+    svg.appendChild(bgRect);
+    const gridRect = doc.createElementNS(SVG_NS, 'rect');
+    gridRect.setAttribute('width', '100%');
+    gridRect.setAttribute('height', '100%');
+    gridRect.setAttribute('fill', `url(#${patternId})`);
+    svg.appendChild(gridRect);
+    const majorRect = doc.createElementNS(SVG_NS, 'rect');
+    majorRect.setAttribute('width', '100%');
+    majorRect.setAttribute('height', '100%');
+    majorRect.setAttribute('fill', `url(#${majorId})`);
+    svg.appendChild(majorRect);
+    layer.appendChild(svg);
+    let visible = true;
+    /** Fill one pattern element with the geometry for a given tile size. */
+    const paintPattern = (target, tile, offsetX, offsetY, color, thickness, variant) => {
+        target.setAttribute('width', String(tile));
+        target.setAttribute('height', String(tile));
+        target.setAttribute('patternTransform', `translate(${offsetX},${offsetY})`);
+        while (target.firstChild)
+            target.removeChild(target.firstChild);
+        if (variant === 'none' || tile <= 0)
+            return;
+        if (variant === 'dots') {
+            const dot = doc.createElementNS(SVG_NS, 'circle');
+            dot.setAttribute('cx', String(thickness));
+            dot.setAttribute('cy', String(thickness));
+            dot.setAttribute('r', String(thickness));
+            dot.setAttribute('fill', color);
+            target.appendChild(dot);
+            return;
+        }
+        if (variant === 'cross') {
+            // Small plus signs at each intersection.
+            const arm = Math.max(2, tile * 0.12);
+            const path = doc.createElementNS(SVG_NS, 'path');
+            path.setAttribute('d', `M ${-arm} 0 H ${arm} M 0 ${-arm} V ${arm}`);
+            path.setAttribute('stroke', color);
+            path.setAttribute('stroke-width', String(thickness));
+            path.setAttribute('fill', 'none');
+            target.appendChild(path);
+            return;
+        }
+        // 'lines' — one horizontal + one vertical edge per tile.
+        const path = doc.createElementNS(SVG_NS, 'path');
+        path.setAttribute('d', `M ${tile} 0 V ${tile} M 0 ${tile} H ${tile}`);
+        path.setAttribute('stroke', color);
+        path.setAttribute('stroke-width', String(thickness));
+        path.setAttribute('fill', 'none');
+        target.appendChild(path);
+    };
+    const render = () => {
+        var _a, _b;
+        const zoom = viewport.getZoom() || 1;
+        const world = viewport.getViewport();
+        // Below minZoom the grid is noise, not information.
+        const suppressed = opts.variant === 'none' || (opts.minZoom > 0 && zoom < opts.minZoom);
+        svg.style.display = visible && !suppressed ? 'block' : 'none';
+        if (!visible || suppressed)
+            return;
+        bgRect.setAttribute('fill', (_a = opts.backgroundColor) !== null && _a !== void 0 ? _a : 'none');
+        const tile = opts.gap * zoom;
+        if (!(tile > 0.5) || !Number.isFinite(tile)) {
+            // Degenerate camera (zoom→0, gap 0). Draw nothing rather than emit an
+            // invalid pattern the browser will complain about.
+            svg.style.display = 'none';
+            return;
+        }
+        // Only the SUB-TILE remainder matters — see the header note on precision.
+        const modulo = (v, m) => ((v % m) + m) % m;
+        const offsetX = modulo(-world.x * zoom, tile);
+        const offsetY = modulo(-world.y * zoom, tile);
+        paintPattern(pattern, tile, offsetX, offsetY, opts.color, opts.size, opts.variant);
+        if (opts.majorEvery > 0 && opts.variant !== 'dots') {
+            const majorTile = tile * opts.majorEvery;
+            paintPattern(majorPattern, majorTile, modulo(-world.x * zoom, majorTile), modulo(-world.y * zoom, majorTile), (_b = opts.majorColor) !== null && _b !== void 0 ? _b : opts.color, opts.size * 1.5, 'lines');
+            majorRect.style.display = 'block';
+        }
+        else {
+            majorRect.style.display = 'none';
+        }
+    };
+    render();
+    const unsubscribe = viewport.onChange(render);
+    return {
+        element: svg,
+        update(next) {
+            opts = Object.assign(Object.assign({}, opts), next);
+            render();
+        },
+        setVisible(next) {
+            if (visible === next)
+                return;
+            visible = next;
+            render();
+        },
+        isVisible: () => visible,
+        dispose: (0, disposable_1.once)(() => {
+            unsubscribe();
+            svg.remove();
+            if (layer && layer.childElementCount === 0)
+                layer.remove();
+        }),
+    };
+}
+//# sourceMappingURL=background.js.map