@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/canvas/canvas-renderer.js

@@ -0,0 +1,600 @@
+"use strict";
+// canvas-renderer.ts — the retained-mode Canvas 2D backend.
+//
+// The architecture, in one paragraph:
+//
+//   `SVGRenderer` is not really an SVG renderer — it is the VNODE PRODUCER. It
+//   turns (diagram, viewport, zoom) into a backend-agnostic VNode tree, applying
+//   the engine's spatial index, viewport culling, LOD tiers and per-entity VNode
+//   caching along the way. `CanvasRenderer` CONSUMES that same tree and paints it
+//   to a 2D context instead of reconciling it into SVG DOM. Both backends are
+//   therefore, by construction, drawing exactly the same scene — and a diagram
+//   can switch between them at runtime (see render-backend.ts) because there is
+//   no second model, no second style pipeline and no second geometry pass.
+//
+// What this backend adds on top of the shared tree:
+//
+//   * a paired OFFSCREEN HIT CANVAS with colour-keyed picking — every pickable
+//     element is painted a second time in a unique flat colour, so hit-testing is
+//     one `getImageData(1,1)` read, O(1) in the number of elements. That is the
+//     property that lets canvas mode scale past the point where an SVG DOM (with
+//     one element per shape and CSS-driven hit regions) collapses;
+//   * devicePixelRatio scaling — the backing store is sized in DEVICE pixels
+//     while the element stays sized in CSS pixels, so lines are crisp on retina
+//     instead of the blurry 1x upscale a naive canvas gives;
+//   * DIRTY-RECTANGLE partial redraw — driven by VNode object identity, which the
+//     producer's cache already gives us for free (see dirty-region.ts);
+//   * a geometric picking fallback for headless use, which is also the oracle the
+//     colour-key picker is tested against.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanvasRenderer = void 0;
+exports.parseViewBox = parseViewBox;
+const tslib_1 = require("tslib");
+const themes_1 = require("../themes");
+const svg_renderer_1 = require("../svg/svg-renderer");
+const path_geometry_1 = require("./path-geometry");
+const style_resolution_1 = require("./style-resolution");
+const canvas_context_1 = require("./canvas-context");
+const vnode_painter_1 = require("./vnode-painter");
+const dirty_region_1 = require("./dirty-region");
+class CanvasRenderer {
+    constructor(engine, options = {}) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        this.mode = 'canvas';
+        this.tracker = new dirty_region_1.DirtyRegionTracker();
+        this.hitCanvas = null;
+        this.hitCtx = null;
+        /** Colour keys, memoised on a STABLE element id — see PaintOptions.allocateColorKey. */
+        this.colorKeys = new Map();
+        this.colorKeyCounter = 0;
+        this.lastWorldToDevice = null;
+        this.hitRecords = [];
+        this.colorKeyIndex = new Map();
+        this.unpaintable = [];
+        this.textCache = new Map();
+        this.lastViewportKey = '';
+        this.lastRenderTime = 0;
+        this.lastStats = {
+            painted: 0,
+            culled: 0,
+            dirtyRects: 0,
+            fullRepaint: true,
+            changedEntities: 0,
+        };
+        this.frameCount = 0;
+        this.fps = 0;
+        this.disposed = false;
+        this.theme = (_a = options.theme) !== null && _a !== void 0 ? _a : themes_1.LIGHT_THEME;
+        // ONE VNode contract: the canvas backend drives the SAME producer, with the
+        // SAME config, that SVG mode drives. It does not get a private "canvas-
+        // friendly" tree — if it did, backend parity would be a hope, not a property.
+        this.producer = (_b = options.producer) !== null && _b !== void 0 ? _b : new svg_renderer_1.SVGRenderer(engine, options.producerConfig, this.theme);
+        this.ownsProducer = !options.producer;
+        this.styleHost = (_c = options.styleHost) !== null && _c !== void 0 ? _c : null;
+        this.resolver = new style_resolution_1.CanvasStyleResolver({
+            theme: this.theme,
+            varOverrides: (0, style_resolution_1.readCssVarOverrides)(this.styleHost),
+        });
+        this.painter = new vnode_painter_1.VNodePainter(this.resolver);
+        this.dpr = (_d = options.devicePixelRatio) !== null && _d !== void 0 ? _d : readDevicePixelRatio();
+        this.enableHitDetection = (_e = options.enableHitDetection) !== null && _e !== void 0 ? _e : true;
+        this.enableDirtyRegions = (_f = options.enableDirtyRegions) !== null && _f !== void 0 ? _f : true;
+        this.hitCanvasScale = clamp((_g = options.hitCanvasScale) !== null && _g !== void 0 ? _g : 1, 0.1, 1);
+        this.canvas = (_h = options.canvas) !== null && _h !== void 0 ? _h : null;
+        this.ctx = safeGetContext(this.canvas);
+        if (this.enableHitDetection) {
+            this.hitCanvas = (_j = options.hitCanvas) !== null && _j !== void 0 ? _j : createOffscreenCanvas(this.canvas);
+            this.hitCtx = safeGetContext(this.hitCanvas);
+        }
+        this.capabilities = {
+            supportsHitTest: true,
+            supportsBatching: true,
+            supportsExport: typeof ((_k = this.canvas) === null || _k === void 0 ? void 0 : _k.toDataURL) === 'function',
+            supportsMeasurement: true,
+            // Canvas cannot rasterise a DOM subtree. Nodes that asked for
+            // foreignObject are reported via `getUnpaintableNodes()` so a host can
+            // overlay real HTML on top of the canvas — the hybrid answer — rather than
+            // having them silently vanish.
+            supportsForeignObject: false,
+            supportsFilters: this.ctx ? 'filter' in this.ctx : false,
+            supportsOffscreen: !!this.hitCtx,
+        };
+        this.startFPSTracking();
+    }
+    // =========================================================================
+    // IRenderer
+    // =========================================================================
+    /**
+     * Produce the frame's VNode tree and paint it.
+     *
+     * Returns the tree (rather than `void`) on purpose: it is the same tree SVG
+     * mode would have reconciled, so a caller can assert parity, or hand it to the
+     * SVG patcher, without re-rendering.
+     */
+    render(viewport, zoom) {
+        const start = now();
+        const tree = this.producer.render(viewport, zoom);
+        const worldToDevice = this.computeWorldToDevice(tree, viewport, zoom);
+        // Any camera / DPR change invalidates every cached pixel on the canvas.
+        const viewportKey = `${viewport.x},${viewport.y},${viewport.width},${viewport.height},${zoom},${this.dpr}`;
+        if (viewportKey !== this.lastViewportKey) {
+            this.lastViewportKey = viewportKey;
+            this.tracker.invalidateAll();
+            this.syncCanvasSize(viewport);
+        }
+        this.lastWorldToDevice = worldToDevice;
+        this.paintFrame(tree, worldToDevice);
+        this.lastRenderTime = now() - start;
+        this.frameCount++;
+        return tree;
+    }
+    getPerformanceMetrics() {
+        const producerMetrics = this.producer.getPerformanceMetrics();
+        return {
+            mode: 'canvas',
+            nodeCount: producerMetrics.nodeCount,
+            linkCount: producerMetrics.linkCount,
+            renderTime: this.lastRenderTime,
+            fps: this.fps,
+            memoryUsage: this.estimateMemoryUsage(),
+        };
+    }
+    /**
+     * The topmost element at a WORLD coordinate.
+     *
+     * Colour-keyed pixel picking when a real hit canvas is available (O(1), and
+     * exactly what was drawn); the geometric fallback otherwise. They are two
+     * implementations of ONE geometry — both read the hit records the paint pass
+     * produced — and they are pinned to each other, and to the engine's own
+     * `getNodeAtPosition`, in `canvas-hit-parity.spec.ts` and in the browser e2e.
+     */
+    hitTest(x, y) {
+        var _a, _b;
+        return (_b = (_a = this.pick(x, y)) === null || _a === void 0 ? void 0 : _a.vnode) !== null && _b !== void 0 ? _b : null;
+    }
+    /** Hit-test, with the entity identity the interaction layer wants. */
+    pick(x, y) {
+        var _a;
+        const record = (_a = this.pickPixel(x, y)) !== null && _a !== void 0 ? _a : this.pickGeometric(x, y);
+        if (!record)
+            return null;
+        return { kind: record.kind, id: record.id, vnode: record.vnode };
+    }
+    /**
+     * Colour-key pick: read one pixel off the hit canvas and look the colour up.
+     * `null` when there is no hit canvas (headless) OR when the pixel is empty.
+     */
+    pickPixel(x, y) {
+        var _a, _b, _c, _d, _e;
+        const ctx = this.hitCtx;
+        if (!ctx || typeof ctx.getImageData !== 'function' || !this.lastWorldToDevice)
+            return null;
+        const m = this.lastWorldToDevice;
+        const px = Math.round((m.a * x + m.c * y + m.e) * this.hitCanvasScale);
+        const py = Math.round((m.b * x + m.d * y + m.f) * this.hitCanvasScale);
+        const w = (_b = (_a = this.hitCanvas) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0;
+        const h = (_d = (_c = this.hitCanvas) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0;
+        if (px < 0 || py < 0 || px >= w || py >= h)
+            return null;
+        let data;
+        try {
+            data = ctx.getImageData(px, py, 1, 1).data;
+        }
+        catch (_f) {
+            return null; // tainted canvas / no rasteriser
+        }
+        const key = (0, vnode_painter_1.colorKeyFromPixel)(data[0], data[1], data[2], data[3]);
+        if (!key)
+            return null;
+        // An antialiased edge pixel is a blend of two keys and matches no record —
+        // which reads as "miss", never as "the wrong entity". See `nextColorKey`.
+        return (_e = this.colorKeyIndex.get(key)) !== null && _e !== void 0 ? _e : null;
+    }
+    /**
+     * Geometric pick: reverse paint order over the hit records, point-in-path for
+     * filled regions and distance-to-path for stroked ones. O(n), used headlessly
+     * and as the oracle the pixel picker is checked against.
+     */
+    pickGeometric(x, y) {
+        const query = { x, y };
+        for (let i = this.hitRecords.length - 1; i >= 0; i--) {
+            const record = this.hitRecords[i];
+            if (record.bounds && !withinPadded(record.bounds, query, record.tolerance))
+                continue;
+            if (record.filled) {
+                if ((0, path_geometry_1.pointInPath)(record.cmds, query))
+                    return record;
+            }
+            else if ((0, path_geometry_1.distanceToPath)(record.cmds, query) <= record.tolerance) {
+                return record;
+            }
+        }
+        return null;
+    }
+    /**
+     * Text measurement through the real 2D context when there is one (proper glyph
+     * metrics), falling back to the same average-glyph estimate the SVG text-block
+     * engine uses so headless measurement stays consistent with the wrapping the
+     * producer already did.
+     */
+    measureText(text, style) {
+        var _a, _b, _c, _d, _e, _f;
+        const fontSize = (_a = style.fontSize) !== null && _a !== void 0 ? _a : 12;
+        const cacheKey = `${text}|${fontSize}|${(_b = style.fontFamily) !== null && _b !== void 0 ? _b : ''}|${(_c = style.fontWeight) !== null && _c !== void 0 ? _c : ''}`;
+        const cached = this.textCache.get(cacheKey);
+        if (cached)
+            return cached;
+        let width;
+        if (this.ctx) {
+            const previous = this.ctx.font;
+            this.ctx.font = `${(_d = style.fontWeight) !== null && _d !== void 0 ? _d : 'normal'} ${fontSize}px ${(_e = style.fontFamily) !== null && _e !== void 0 ? _e : 'sans-serif'}`;
+            width = this.ctx.measureText(text).width;
+            this.ctx.font = previous;
+        }
+        else {
+            width = text.length * fontSize * 0.6;
+        }
+        const metrics = {
+            width,
+            height: fontSize * ((_f = style.lineHeight) !== null && _f !== void 0 ? _f : 1.2),
+            baseline: fontSize * 0.8,
+        };
+        this.textCache.set(cacheKey, metrics);
+        return metrics;
+    }
+    /** Export the CURRENT canvas contents. `svg` is not a canvas capability. */
+    export(format_1) {
+        return tslib_1.__awaiter(this, arguments, void 0, function* (format, options = {}) {
+            var _a;
+            if (format === 'svg') {
+                throw new Error('CanvasRenderer cannot export SVG — switch the backend to SVG mode (DiagramRenderBackend), or use the VNode → SVG serializer in export/.');
+            }
+            if (!this.canvas || typeof this.canvas.toDataURL !== 'function') {
+                throw new Error('CanvasRenderer.export requires a canvas with toDataURL');
+            }
+            const mime = format === 'png' ? 'image/png' : format === 'jpeg' ? 'image/jpeg' : 'image/webp';
+            return this.canvas.toDataURL(mime, (_a = options.quality) !== null && _a !== void 0 ? _a : 0.92);
+        });
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.fpsTimer !== undefined)
+            clearInterval(this.fpsTimer);
+        this.fpsTimer = undefined;
+        // Only tear down the producer we created — a producer shared with another
+        // backend (a live mode switch) belongs to the caller.
+        if (this.ownsProducer)
+            this.producer.dispose();
+        this.tracker.reset();
+        this.hitRecords = [];
+        this.colorKeyIndex.clear();
+        this.colorKeys.clear();
+        this.textCache.clear();
+        this.ctx = null;
+        this.canvas = null;
+        this.hitCtx = null;
+        this.hitCanvas = null;
+    }
+    // =========================================================================
+    // Canvas-specific API
+    // =========================================================================
+    getTheme() {
+        return this.theme;
+    }
+    /** Swap the theme. Repaints everything: every resolved colour just changed. */
+    setTheme(theme) {
+        this.theme = theme;
+        this.producer.setTheme(theme);
+        this.resolver.setTheme(theme, (0, style_resolution_1.readCssVarOverrides)(this.styleHost));
+        this.tracker.invalidateAll();
+    }
+    /** The VNode producer — shared with the SVG backend on a mode switch. */
+    getProducer() {
+        return this.producer;
+    }
+    /** Attach (or replace) the canvas this renderer paints into. */
+    setCanvas(canvas, hitCanvas) {
+        this.canvas = canvas;
+        this.ctx = safeGetContext(canvas);
+        if (this.enableHitDetection) {
+            this.hitCanvas = hitCanvas !== null && hitCanvas !== void 0 ? hitCanvas : createOffscreenCanvas(canvas);
+            this.hitCtx = safeGetContext(this.hitCanvas);
+        }
+        this.lastViewportKey = '';
+        this.tracker.reset();
+    }
+    /** Change the device pixel ratio (a window moved to a retina display). */
+    setDevicePixelRatio(dpr) {
+        if (!isFinite(dpr) || dpr <= 0 || dpr === this.dpr)
+            return;
+        this.dpr = dpr;
+        this.lastViewportKey = '';
+        this.tracker.invalidateAll();
+    }
+    getDevicePixelRatio() {
+        return this.dpr;
+    }
+    /** What the last frame actually repainted — the dirty-region proof. */
+    getFrameStats() {
+        return Object.assign({}, this.lastStats);
+    }
+    /** Every pickable region of the current frame, in paint order. */
+    getHitRecords() {
+        return this.hitRecords;
+    }
+    /**
+     * Nodes the canvas could not paint (`foreignObject` — live HTML/components).
+     * A host that uses them should mount an HTML overlay for exactly these.
+     */
+    getUnpaintableNodes() {
+        return this.unpaintable;
+    }
+    /** Force the next frame to repaint the whole canvas. */
+    invalidate() {
+        this.tracker.invalidateAll();
+    }
+    // =========================================================================
+    // internals
+    // =========================================================================
+    /**
+     * World → DEVICE pixels.
+     *
+     * Read straight off the tree's `viewBox`, so the canvas maps world space with
+     * the exact same transform the SVG backend hands to the browser. If these two
+     * ever disagreed, the picture and the hit-tester would silently drift apart at
+     * zoom ≠ 1 — which is precisely the bug the shared `viewBox` convention in
+     * `ViewportController` exists to prevent.
+     */
+    computeWorldToDevice(tree, viewport, zoom) {
+        var _a, _b;
+        const viewBox = (_b = parseViewBox((_a = tree.props) === null || _a === void 0 ? void 0 : _a['viewBox'])) !== null && _b !== void 0 ? _b : {
+            x: viewport.x,
+            y: viewport.y,
+            width: viewport.width / zoom,
+            height: viewport.height / zoom,
+        };
+        const scale = zoom * this.dpr;
+        return {
+            a: scale,
+            b: 0,
+            c: 0,
+            d: scale,
+            e: -viewBox.x * scale,
+            f: -viewBox.y * scale,
+        };
+    }
+    /**
+     * High-DPI: the backing store is in DEVICE pixels, the element stays in CSS
+     * pixels. Skipping this is what makes a naive canvas look soft on a retina
+     * screen — the browser upscales a 1x bitmap into a 2x box.
+     */
+    syncCanvasSize(viewport) {
+        const cssWidth = Math.max(1, Math.round(viewport.width));
+        const cssHeight = Math.max(1, Math.round(viewport.height));
+        if (this.canvas) {
+            this.canvas.width = Math.round(cssWidth * this.dpr);
+            this.canvas.height = Math.round(cssHeight * this.dpr);
+            if (this.canvas.style) {
+                this.canvas.style.width = `${cssWidth}px`;
+                this.canvas.style.height = `${cssHeight}px`;
+            }
+        }
+        if (this.hitCanvas) {
+            this.hitCanvas.width = Math.max(1, Math.round(cssWidth * this.dpr * this.hitCanvasScale));
+            this.hitCanvas.height = Math.max(1, Math.round(cssHeight * this.dpr * this.hitCanvasScale));
+        }
+    }
+    paintFrame(tree, worldToDevice) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const entities = (0, dirty_region_1.collectEntities)(tree);
+        // A live connection preview has no stable identity and follows the pointer,
+        // so a frame carrying one is repainted whole.
+        if ((0, dirty_region_1.previewIsActive)(tree))
+            this.tracker.invalidateAll();
+        const diff = this.enableDirtyRegions
+            ? this.tracker.diff(entities, (vnode) => this.painter.measure(vnode))
+            : { rects: null, changed: [...entities.keys()], removed: [] };
+        const full = diff.rects === null;
+        const rects = (_a = diff.rects) !== null && _a !== void 0 ? _a : [];
+        if (!full && rects.length === 0) {
+            // Nothing changed: the canvas already holds the right pixels. THIS is the
+            // payoff of a retained-mode backend — a no-op frame costs a tree walk, not
+            // a repaint.
+            this.lastStats = {
+                painted: 0,
+                culled: 0,
+                dirtyRects: 0,
+                fullRepaint: false,
+                changedEntities: 0,
+            };
+            return;
+        }
+        const paintOptions = {
+            worldToDevice,
+            dirtyWorld: full ? undefined : rects,
+            allocateColorKey: (id) => this.colorKeyFor(id),
+        };
+        // --- visible canvas -----------------------------------------------------
+        let painted = 0;
+        let culled = 0;
+        if (this.ctx) {
+            const ctx = this.ctx;
+            ctx.save();
+            ctx.setTransform(1, 0, 0, 1, 0, 0);
+            if (full) {
+                ctx.clearRect(0, 0, (_c = (_b = this.canvas) === null || _b === void 0 ? void 0 : _b.width) !== null && _c !== void 0 ? _c : 0, (_e = (_d = this.canvas) === null || _d === void 0 ? void 0 : _d.height) !== null && _e !== void 0 ? _e : 0);
+            }
+            else {
+                clipToRects(ctx, rects, worldToDevice, 1);
+                for (const rect of rects) {
+                    const d = deviceRect(rect, worldToDevice, 1);
+                    ctx.clearRect(d.x, d.y, d.w, d.h);
+                }
+            }
+            const result = this.painter.paint(ctx, tree, paintOptions);
+            ctx.restore();
+            painted = result.paintedCount;
+            culled = result.culledCount;
+            this.hitRecords = result.hitRecords;
+            this.colorKeyIndex = result.colorKeyIndex;
+            this.unpaintable = result.unpaintableNodes;
+        }
+        else {
+            // No 2D context (headless): still build the hit index, so hit-testing and
+            // measurement work without a rasteriser.
+            const result = this.painter.paint(canvas_context_1.NULL_CONTEXT, tree, Object.assign(Object.assign({}, paintOptions), { dirtyWorld: undefined, measureOnly: true }));
+            this.hitRecords = result.hitRecords;
+            this.colorKeyIndex = result.colorKeyIndex;
+            this.unpaintable = result.unpaintableNodes;
+        }
+        // --- offscreen picking canvas ------------------------------------------
+        if (this.hitCtx) {
+            const ctx = this.hitCtx;
+            ctx.save();
+            ctx.setTransform(1, 0, 0, 1, 0, 0);
+            if (full) {
+                ctx.clearRect(0, 0, (_g = (_f = this.hitCanvas) === null || _f === void 0 ? void 0 : _f.width) !== null && _g !== void 0 ? _g : 0, (_j = (_h = this.hitCanvas) === null || _h === void 0 ? void 0 : _h.height) !== null && _j !== void 0 ? _j : 0);
+            }
+            else {
+                clipToRects(ctx, rects, worldToDevice, this.hitCanvasScale);
+                for (const rect of rects) {
+                    const d = deviceRect(rect, worldToDevice, this.hitCanvasScale);
+                    ctx.clearRect(d.x, d.y, d.w, d.h);
+                }
+            }
+            this.painter.paint(ctx, tree, Object.assign(Object.assign({}, paintOptions), { worldToDevice: scaleMatrix(worldToDevice, this.hitCanvasScale), pickingPass: true }));
+            ctx.restore();
+        }
+        this.lastStats = {
+            painted,
+            culled,
+            dirtyRects: full ? 0 : rects.length,
+            fullRepaint: full,
+            changedEntities: diff.changed.length,
+        };
+    }
+    /** Stable colour key for an element id, minted once and never recycled. */
+    colorKeyFor(stableId) {
+        let key = this.colorKeys.get(stableId);
+        if (!key) {
+            key = (0, vnode_painter_1.nextColorKey)(this.colorKeyCounter++);
+            this.colorKeys.set(stableId, key);
+        }
+        return key;
+    }
+    startFPSTracking() {
+        var _a, _b;
+        if (typeof setInterval !== 'function')
+            return;
+        this.fpsTimer = setInterval(() => {
+            this.fps = this.frameCount;
+            this.frameCount = 0;
+        }, 1000);
+        // Never hold a Node process open for a frame counter.
+        (_b = (_a = this.fpsTimer) === null || _a === void 0 ? void 0 : _a.unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    estimateMemoryUsage() {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const backing = ((_b = (_a = this.canvas) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0) * ((_d = (_c = this.canvas) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0) * 4;
+        const hit = ((_f = (_e = this.hitCanvas) === null || _e === void 0 ? void 0 : _e.width) !== null && _f !== void 0 ? _f : 0) * ((_h = (_g = this.hitCanvas) === null || _g === void 0 ? void 0 : _g.height) !== null && _h !== void 0 ? _h : 0) * 4;
+        // ~200 bytes per retained hit record (flattened command list + bookkeeping).
+        return backing + hit + this.hitRecords.length * 200;
+    }
+}
+exports.CanvasRenderer = CanvasRenderer;
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function now() {
+    return typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+}
+function readDevicePixelRatio() {
+    const dpr = globalThis.devicePixelRatio;
+    return typeof dpr === 'number' && dpr > 0 ? dpr : 1;
+}
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+/**
+ * jsdom throws "not implemented" from `getContext('2d')` rather than returning
+ * null. A headless renderer must degrade to the geometric picking path, not
+ * explode — so the throw is absorbed here, in the one place that calls it.
+ */
+function safeGetContext(canvas) {
+    var _a;
+    if (!canvas || typeof canvas.getContext !== 'function')
+        return null;
+    try {
+        return (_a = canvas.getContext('2d')) !== null && _a !== void 0 ? _a : null;
+    }
+    catch (_b) {
+        return null;
+    }
+}
+/** `"0 0 800 600"` → a rectangle. */
+function parseViewBox(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const parts = raw
+        .trim()
+        .split(/[\s,]+/)
+        .map((v) => parseFloat(v));
+    if (parts.length < 4 || parts.some((v) => Number.isNaN(v)))
+        return null;
+    return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+function scaleMatrix(m, s) {
+    return { a: m.a * s, b: m.b * s, c: m.c * s, d: m.d * s, e: m.e * s, f: m.f * s };
+}
+function deviceRect(bounds, m, scale) {
+    const x0 = (m.a * bounds.minX + m.c * bounds.minY + m.e) * scale;
+    const y0 = (m.b * bounds.minX + m.d * bounds.minY + m.f) * scale;
+    const x1 = (m.a * bounds.maxX + m.c * bounds.maxY + m.e) * scale;
+    const y1 = (m.b * bounds.maxX + m.d * bounds.maxY + m.f) * scale;
+    // Grow to whole pixels: a dirty rect that lands on a fraction would otherwise
+    // leave a seam of stale pixels along its edge.
+    const x = Math.floor(Math.min(x0, x1));
+    const y = Math.floor(Math.min(y0, y1));
+    return {
+        x,
+        y,
+        w: Math.ceil(Math.max(x0, x1)) - x,
+        h: Math.ceil(Math.max(y0, y1)) - y,
+    };
+}
+/**
+ * Clip subsequent painting to the dirty rects. The clip is set under the
+ * IDENTITY transform and is stored in device space, so it survives the per-shape
+ * `setTransform` calls the painter makes.
+ */
+function clipToRects(ctx, rects, m, scale) {
+    ctx.beginPath();
+    for (const rect of rects) {
+        const d = deviceRect(rect, m, scale);
+        ctx.moveTo(d.x, d.y);
+        ctx.lineTo(d.x + d.w, d.y);
+        ctx.lineTo(d.x + d.w, d.y + d.h);
+        ctx.lineTo(d.x, d.y + d.h);
+        ctx.closePath();
+    }
+    ctx.clip();
+}
+function withinPadded(bounds, p, pad) {
+    return (p.x >= bounds.minX - pad &&
+        p.x <= bounds.maxX + pad &&
+        p.y >= bounds.minY - pad &&
+        p.y <= bounds.maxY + pad);
+}
+/** Create the offscreen hit canvas next to the visible one. */
+function createOffscreenCanvas(source) {
+    var _a;
+    const doc = (_a = source === null || source === void 0 ? void 0 : source.ownerDocument) !== null && _a !== void 0 ? _a : globalThis.document;
+    if (!doc || typeof doc.createElement !== 'function')
+        return null;
+    return doc.createElement('canvas');
+}
+//# sourceMappingURL=canvas-renderer.js.map

package/src/libs/renderer/src/canvas/dirty-region.d.ts

@@ -0,0 +1,56 @@
+import type { VNode } from '../types/vnode.types';
+import { type Bounds } from './path-geometry';
+/** The bounds of one top-level entity, and the VNode that produced them. */
+export interface EntitySnapshot {
+    vnode: VNode;
+    bounds: Bounds | null;
+}
+export interface DirtyDiff {
+    /**
+     * World rects to repaint, or `null` for "repaint everything" (first frame,
+     * camera move, theme swap, or too much changed to be worth clipping).
+     */
+    rects: Bounds[] | null;
+    /** Entities whose VNode object is new this frame. */
+    changed: string[];
+    /** Entities that disappeared. */
+    removed: string[];
+}
+/** Merge rects that overlap or nearly touch, so we don't clip 40 slivers. */
+export declare function mergeRects(rects: Bounds[], slack?: number): Bounds[];
+export declare class DirtyRegionTracker {
+    private prev;
+    private forceFull;
+    /** Next frame repaints everything (camera moved, theme swapped, resized …). */
+    invalidateAll(): void;
+    /** Forget everything (a new diagram, or a disposed renderer). */
+    reset(): void;
+    /**
+     * Diff this frame's entities against the last one.
+     *
+     * @param current  entity key → this frame's VNode.
+     * @param measure  computes an entity's world bounds. Called ONLY for entities
+     *                 whose VNode object actually changed — an unchanged entity is
+     *                 never measured at all.
+     */
+    diff(current: Map<string, VNode>, measure: (vnode: VNode) => Bounds | null): DirtyDiff;
+    /** Bounds recorded for an entity on the last frame (testing / diagnostics). */
+    getBounds(key: string): Bounds | null | undefined;
+    get size(): number;
+}
+/**
+ * The top-level entities of a rendered tree: every keyed child of the links and
+ * nodes layers. These are the units of change — the granularity at which the SVG
+ * renderer caches, and therefore the granularity at which identity means
+ * "unchanged".
+ *
+ * The connection-preview layer is deliberately NOT an entity: it exists only
+ * mid-drag, changes every frame, and is handled by {@link previewIsActive}.
+ */
+export declare function collectEntities(root: VNode): Map<string, VNode>;
+/**
+ * True when the tree carries a live connection / reconnection preview. It has no
+ * stable identity and moves with the pointer, so any frame containing one is
+ * repainted whole — the honest, correct answer, and it only happens mid-drag.
+ */
+export declare function previewIsActive(root: VNode): boolean;