@vkcha/svg-core 0.1.2 → 1.0.0

package/dist/index.js

@@ -0,0 +1,1137 @@
+function svgEl(tag, attrs = {}) {
+    const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
+    for (const [k, v] of Object.entries(attrs))
+        el.setAttribute(k, v);
+    return el;
+}
+
+const DEFAULT_PANZOOM_OPTIONS = {
+    wheelMode: "pan",
+    zoomRequiresCtrlKey: false,
+    panRequiresSpaceKey: false,
+    minZoom: 0.2,
+    maxZoom: 8,
+    zoomSpeed: 1,
+    pinchZoomSpeed: 2,
+    invertZoom: false,
+    invertPan: false,
+};
+/**
+ * Minimal SVG "canvas" with pan/zoom.
+ *
+ * - Wheel: zoom around cursor
+ * - Pointer drag: pan
+ *
+ * This is intentionally tiny and standalone so the project can restart from a clean base.
+ */
+class PanZoomCanvas {
+    svg;
+    world;
+    state = { zoom: 1, panX: 0, panY: 0 };
+    options = { ...DEFAULT_PANZOOM_OPTIONS };
+    listeners = new Set();
+    notifyScheduled = false;
+    dragPointerId = null;
+    panStart = null;
+    isPanning = false;
+    isSpaceDown = false;
+    static DRAG_THRESHOLD_PX = 5;
+    animationFrameId = null;
+    windowKeyDownHandler = null;
+    windowKeyUpHandler = null;
+    svgWheelHandler = null;
+    svgPointerDownHandler = null;
+    svgPointerMoveHandler = null;
+    svgPointerUpHandler = null;
+    svgPointerCancelHandler = null;
+    svgPointerLeaveHandler = null;
+    constructor(svg, opts = {}) {
+        this.svg = svg;
+        this.world = svgEl("g");
+        this.world.dataset.layer = "world";
+        this.svg.replaceChildren(this.world);
+        this.setOptions(opts);
+        this.applyWorldGroupConfig();
+        // Disable browser gestures, focus outline, and selection highlight on the SVG surface.
+        this.svg.style.touchAction = "none";
+        this.svg.style.userSelect = "none";
+        const svgStyle = this.svg.style;
+        svgStyle.webkitUserSelect = "none";
+        svgStyle.webkitTapHighlightColor = "transparent";
+        this.svg.style.outline = "none";
+        this.svg.setAttribute("tabindex", "-1");
+        // Also disable outline on the world group.
+        this.world.style.outline = "none";
+        this.attach();
+        this.render();
+    }
+    applyWorldGroupConfig() {
+        const cfg = this.options.worldGroup;
+        if (!cfg)
+            return;
+        if (cfg.id) {
+            this.world.id = cfg.id;
+        }
+        if (cfg.attributes) {
+            for (const [key, value] of Object.entries(cfg.attributes)) {
+                this.world.setAttribute(key, value);
+            }
+        }
+    }
+    /**
+     * Create a new <g> layer inside the world.
+     * Useful when you want pan/zoom only and manage your own SVG content.
+     */
+    createLayer(name, opts) {
+        const layer = svgEl("g");
+        if (name)
+            layer.dataset.layer = name;
+        if (opts?.pointerEvents)
+            layer.style.pointerEvents = opts.pointerEvents;
+        if (opts?.position === "back" && this.world.firstChild) {
+            this.world.insertBefore(layer, this.world.firstChild);
+        }
+        else {
+            this.world.appendChild(layer);
+        }
+        return layer;
+    }
+    setOptions(next) {
+        this.options = { ...DEFAULT_PANZOOM_OPTIONS, ...this.options, ...next };
+        if (next.worldGroup) {
+            this.applyWorldGroupConfig();
+            this.render();
+        }
+    }
+    /**
+     * Subscribe to pan/zoom state changes (event-driven, no polling).
+     *
+     * Optimized:
+     * - multiple updates within a frame are coalesced into a single notification via rAF
+     */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    setState(next) {
+        const merged = { ...this.state, ...next };
+        if (merged.zoom === this.state.zoom &&
+            merged.panX === this.state.panX &&
+            merged.panY === this.state.panY) {
+            return;
+        }
+        this.state = merged;
+        this.render();
+        this.scheduleNotify();
+    }
+    /**
+     * Animate to a target state over a duration.
+     * Uses linear easing by default. Pass a custom easing function for different curves.
+     * Example: `(t) => 1 - Math.pow(1 - t, 3)` for ease-out cubic.
+     */
+    animateTo(target, durationMs = 300, easing = (t) => t) {
+        return new Promise((resolve) => {
+            if (this.animationFrameId !== null) {
+                cancelAnimationFrame(this.animationFrameId);
+                this.animationFrameId = null;
+            }
+            const start = {
+                zoom: this.state.zoom,
+                panX: this.state.panX,
+                panY: this.state.panY,
+            };
+            const end = {
+                zoom: target.zoom ?? start.zoom,
+                panX: target.panX ?? start.panX,
+                panY: target.panY ?? start.panY,
+            };
+            const startTime = performance.now();
+            const step = (now) => {
+                const elapsed = now - startTime;
+                const t = Math.min(1, elapsed / durationMs);
+                const eased = easing(t);
+                this.setState({
+                    zoom: start.zoom + (end.zoom - start.zoom) * eased,
+                    panX: start.panX + (end.panX - start.panX) * eased,
+                    panY: start.panY + (end.panY - start.panY) * eased,
+                });
+                if (t < 1) {
+                    this.animationFrameId = requestAnimationFrame(step);
+                }
+                else {
+                    this.animationFrameId = null;
+                    resolve();
+                }
+            };
+            this.animationFrameId = requestAnimationFrame(step);
+        });
+    }
+    /** Stop any running animation. */
+    stopAnimation() {
+        if (this.animationFrameId !== null) {
+            cancelAnimationFrame(this.animationFrameId);
+            this.animationFrameId = null;
+        }
+    }
+    reset() {
+        this.setState({ zoom: 1, panX: 0, panY: 0 });
+    }
+    /**
+     * Clean up all event listeners and resources.
+     * Call this when the canvas is no longer needed to prevent memory leaks.
+     */
+    destroy() {
+        // Cancel any running animation
+        this.stopAnimation();
+        // Remove window listeners
+        if (this.windowKeyDownHandler) {
+            window.removeEventListener("keydown", this.windowKeyDownHandler);
+            this.windowKeyDownHandler = null;
+        }
+        if (this.windowKeyUpHandler) {
+            window.removeEventListener("keyup", this.windowKeyUpHandler);
+            this.windowKeyUpHandler = null;
+        }
+        // Remove SVG listeners
+        if (this.svgWheelHandler) {
+            this.svg.removeEventListener("wheel", this.svgWheelHandler);
+            this.svgWheelHandler = null;
+        }
+        if (this.svgPointerDownHandler) {
+            this.svg.removeEventListener("pointerdown", this.svgPointerDownHandler);
+            this.svgPointerDownHandler = null;
+        }
+        if (this.svgPointerMoveHandler) {
+            this.svg.removeEventListener("pointermove", this.svgPointerMoveHandler);
+            this.svgPointerMoveHandler = null;
+        }
+        if (this.svgPointerUpHandler) {
+            this.svg.removeEventListener("pointerup", this.svgPointerUpHandler);
+            this.svgPointerUpHandler = null;
+        }
+        if (this.svgPointerCancelHandler) {
+            this.svg.removeEventListener("pointercancel", this.svgPointerCancelHandler);
+            this.svgPointerCancelHandler = null;
+        }
+        if (this.svgPointerLeaveHandler) {
+            this.svg.removeEventListener("pointerleave", this.svgPointerLeaveHandler);
+            this.svgPointerLeaveHandler = null;
+        }
+        // Release pointer capture if active
+        if (this.dragPointerId !== null) {
+            try {
+                this.svg.releasePointerCapture(this.dragPointerId);
+            }
+            catch {
+                // Ignore errors if pointer is already released
+            }
+            this.dragPointerId = null;
+        }
+        // Clear state
+        this.panStart = null;
+        this.isPanning = false;
+        this.isSpaceDown = false;
+        this.listeners.clear();
+    }
+    scheduleNotify() {
+        if (this.notifyScheduled)
+            return;
+        this.notifyScheduled = true;
+        requestAnimationFrame(() => {
+            this.notifyScheduled = false;
+            for (const fn of this.listeners)
+                fn(this.state);
+        });
+    }
+    attach() {
+        // Track Space key for "Figma-like" panning.
+        this.windowKeyDownHandler = (e) => {
+            if (e.code === "Space")
+                this.isSpaceDown = true;
+        };
+        this.windowKeyUpHandler = (e) => {
+            if (e.code === "Space")
+                this.isSpaceDown = false;
+        };
+        window.addEventListener("keydown", this.windowKeyDownHandler);
+        window.addEventListener("keyup", this.windowKeyUpHandler);
+        this.svgWheelHandler = (e) => {
+            e.preventDefault();
+            const pt = this.svgPoint(e.clientX, e.clientY);
+            const { wheelMode, zoomRequiresCtrlKey, invertZoom, invertPan } = this.options;
+            const ctrl = e.ctrlKey || e.metaKey;
+            const isPinchGesture = e.ctrlKey && !e.metaKey;
+            // Desired behavior:
+            // - wheelMode="zoom" (default): wheel zooms. If zoomRequiresCtrlKey=true, only zoom when ctrl/cmd is pressed.
+            // - wheelMode="pan": wheel pans by default. ctrl/cmd (pinch gesture on macOS) zooms instead.
+            if (wheelMode === "pan" && !ctrl) {
+                const k = invertPan ? -1 : 1;
+                this.setState({
+                    panX: this.state.panX - e.deltaX * k,
+                    panY: this.state.panY - e.deltaY * k,
+                });
+                return;
+            }
+            if (wheelMode === "zoom" && zoomRequiresCtrlKey && !ctrl) {
+                return;
+            }
+            const worldBefore = this.screenToWorld(pt.x, pt.y);
+            const dy = invertZoom ? -e.deltaY : e.deltaY;
+            const pinchBoost = isPinchGesture && e.deltaMode === WheelEvent.DOM_DELTA_PIXEL
+                ? this.options.pinchZoomSpeed
+                : 1;
+            const zoomFactor = Math.exp(-dy * 0.001 * this.options.zoomSpeed * pinchBoost);
+            const nextZoom = clamp(this.state.zoom * zoomFactor, this.options.minZoom, this.options.maxZoom);
+            // Keep world point under cursor stable:
+            // screen = world * zoom + pan  =>  pan = screen - world * zoom
+            const nextPanX = pt.x - worldBefore.x * nextZoom;
+            const nextPanY = pt.y - worldBefore.y * nextZoom;
+            this.setState({ zoom: nextZoom, panX: nextPanX, panY: nextPanY });
+        };
+        this.svg.addEventListener("wheel", this.svgWheelHandler, { passive: false });
+        this.svgPointerDownHandler = (e) => {
+            if (e.button !== 0)
+                return;
+            if (this.dragPointerId !== null)
+                return;
+            if (this.options.panRequiresSpaceKey && !this.isSpaceDown)
+                return;
+            this.dragPointerId = e.pointerId;
+            this.isPanning = false;
+            const pt = this.svgPoint(e.clientX, e.clientY);
+            this.panStart = { panX: this.state.panX, panY: this.state.panY, x: pt.x, y: pt.y };
+        };
+        this.svg.addEventListener("pointerdown", this.svgPointerDownHandler);
+        this.svgPointerMoveHandler = (e) => {
+            if (this.dragPointerId === null)
+                return;
+            if (e.pointerId !== this.dragPointerId)
+                return;
+            if (!this.panStart)
+                return;
+            const pt = this.svgPoint(e.clientX, e.clientY);
+            const dx = pt.x - this.panStart.x;
+            const dy = pt.y - this.panStart.y;
+            if (!this.isPanning) {
+                if (Math.hypot(dx, dy) < PanZoomCanvas.DRAG_THRESHOLD_PX) {
+                    return;
+                }
+                this.isPanning = true;
+                this.svg.setPointerCapture(e.pointerId);
+            }
+            this.setState({ panX: this.panStart.panX + dx, panY: this.panStart.panY + dy });
+        };
+        this.svg.addEventListener("pointermove", this.svgPointerMoveHandler);
+        const end = (e) => {
+            if (this.dragPointerId === null)
+                return;
+            if (e.pointerId !== this.dragPointerId)
+                return;
+            if (this.isPanning) {
+                try {
+                    this.svg.releasePointerCapture(e.pointerId);
+                }
+                catch {
+                    // Ignore if already released
+                }
+            }
+            this.dragPointerId = null;
+            this.panStart = null;
+            this.isPanning = false;
+        };
+        this.svgPointerUpHandler = end;
+        this.svgPointerCancelHandler = end;
+        this.svgPointerLeaveHandler = () => {
+            if (this.isPanning && this.dragPointerId !== null) {
+                try {
+                    this.svg.releasePointerCapture(this.dragPointerId);
+                }
+                catch {
+                    // Ignore
+                }
+            }
+            this.dragPointerId = null;
+            this.panStart = null;
+            this.isPanning = false;
+        };
+        this.svg.addEventListener("pointerup", this.svgPointerUpHandler);
+        this.svg.addEventListener("pointercancel", this.svgPointerCancelHandler);
+        this.svg.addEventListener("pointerleave", this.svgPointerLeaveHandler);
+    }
+    render() {
+        const { zoom, panX, panY } = this.state;
+        this.world.setAttribute("transform", `matrix(${zoom} 0 0 ${zoom} ${panX} ${panY})`);
+        const dynamicAttrs = this.options.worldGroup?.dynamicAttributes;
+        if (dynamicAttrs) {
+            for (const [key, fn] of Object.entries(dynamicAttrs)) {
+                this.world.setAttribute(key, fn(zoom));
+            }
+        }
+    }
+    svgPoint(clientX, clientY) {
+        const r = this.svg.getBoundingClientRect();
+        return { x: clientX - r.left, y: clientY - r.top };
+    }
+    screenToWorld(x, y) {
+        const { zoom, panX, panY } = this.state;
+        return { x: (x - panX) / zoom, y: (y - panY) / zoom };
+    }
+}
+function clamp(v, min, max) {
+    return Math.max(min, Math.min(max, v));
+}
+
+// Cache fragment -> metrics so we only measure when the fragment changes.
+const metricsCache = new Map();
+let measureSvg = null;
+let measureG = null;
+function ensureMeasureDom() {
+    if (measureSvg && measureG)
+        return { svg: measureSvg, g: measureG };
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("width", "0");
+    svg.setAttribute("height", "0");
+    svg.style.position = "absolute";
+    svg.style.left = "-10000px";
+    svg.style.top = "-10000px";
+    svg.style.visibility = "hidden";
+    svg.style.pointerEvents = "none";
+    const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    svg.appendChild(g);
+    measureSvg = svg;
+    measureG = g;
+    return { svg, g };
+}
+function attachMeasureDom(svg) {
+    // getBBox() requires the element to be in the document.
+    if (!svg.isConnected)
+        document.body.appendChild(svg);
+}
+function detachMeasureDom(svg) {
+    // Avoid leaving hidden measurement DOM nodes around permanently.
+    if (svg.isConnected)
+        svg.remove();
+}
+function stripXmlnsDeep(el) {
+    // Remove redundant XML namespace declarations from fragments inserted into an existing <svg>.
+    if (el.hasAttribute("xmlns"))
+        el.removeAttribute("xmlns");
+    for (const attr of Array.from(el.attributes)) {
+        if (attr.name.startsWith("xmlns:"))
+            el.removeAttribute(attr.name);
+    }
+    for (const child of Array.from(el.children))
+        stripXmlnsDeep(child);
+}
+function sanitizeFragment(markup) {
+    const s = markup.trim();
+    if (!s)
+        return "";
+    const wrapped = `<svg xmlns="http://www.w3.org/2000/svg">${s}</svg>`;
+    try {
+        const doc = new DOMParser().parseFromString(wrapped, "image/svg+xml");
+        const svg = doc.documentElement;
+        if (!svg || svg.nodeName.toLowerCase() !== "svg")
+            return "";
+        doc.querySelectorAll("script, foreignObject").forEach((n) => n.remove());
+        doc.querySelectorAll("*").forEach((el) => {
+            for (const attr of Array.from(el.attributes)) {
+                if (attr.name.toLowerCase().startsWith("on"))
+                    el.removeAttribute(attr.name);
+                // We insert fragments into an existing <svg>, so explicit xmlns declarations are redundant.
+                if (attr.name === "xmlns" || attr.name.startsWith("xmlns:"))
+                    el.removeAttribute(attr.name);
+            }
+        });
+        // Prefer innerHTML to avoid browsers sprinkling xmlns="..." on every serialized element.
+        const inner = svg.innerHTML;
+        if (typeof inner === "string")
+            return inner.trim();
+        return new XMLSerializer()
+            .serializeToString(svg)
+            .replace(/^<svg[^>]*>|<\/svg>$/g, "")
+            .trim();
+    }
+    catch {
+        return "";
+    }
+}
+function parseFragmentElements(markup) {
+    const s = markup.trim();
+    if (!s)
+        return [];
+    const wrapped = `<svg xmlns="http://www.w3.org/2000/svg">${s}</svg>`;
+    try {
+        const doc = new DOMParser().parseFromString(wrapped, "image/svg+xml");
+        const svg = doc.documentElement;
+        if (!svg || svg.nodeName.toLowerCase() !== "svg")
+            return [];
+        // Sanitize in DOM (no string re-serialization for canvas nodes).
+        doc.querySelectorAll("script, foreignObject").forEach((n) => n.remove());
+        doc.querySelectorAll("*").forEach((el) => {
+            for (const attr of Array.from(el.attributes)) {
+                if (attr.name.toLowerCase().startsWith("on"))
+                    el.removeAttribute(attr.name);
+                if (attr.name === "xmlns" || attr.name.startsWith("xmlns:"))
+                    el.removeAttribute(attr.name);
+            }
+        });
+        // Import into the live document so we don't carry XML serializer artifacts (like xmlns on every node).
+        const imported = Array.from(svg.children).map((el) => document.importNode(el, true));
+        for (const el of imported)
+            stripXmlnsDeep(el);
+        return imported;
+    }
+    catch {
+        return [];
+    }
+}
+function measureFragmentMetrics(markup) {
+    const key = sanitizeFragment(markup);
+    if (!key)
+        return null;
+    const cached = metricsCache.get(key);
+    if (cached)
+        return cached;
+    const { svg, g } = ensureMeasureDom();
+    attachMeasureDom(svg);
+    g.replaceChildren();
+    const els = parseFragmentElements(key);
+    for (const el of els)
+        g.appendChild(el.cloneNode(true));
+    try {
+        const b = g.getBBox();
+        // getBBox() does NOT include stroke, so compute a padding based on computed stroke-width.
+        let maxStrokeWidth = 0;
+        g.querySelectorAll("*").forEach((node) => {
+            try {
+                const cs = getComputedStyle(node);
+                const stroke = cs.stroke;
+                if (!stroke || stroke === "none" || stroke === "transparent")
+                    return;
+                const sw = Number.parseFloat(cs.strokeWidth ?? "0");
+                if (Number.isFinite(sw) && sw > maxStrokeWidth)
+                    maxStrokeWidth = sw;
+            }
+            catch {
+                // ignore
+            }
+        });
+        const pad = Math.max(0, maxStrokeWidth / 2);
+        const bbox = { x: b.x, y: b.y, width: b.width, height: b.height };
+        const metrics = { bbox, pad };
+        metricsCache.set(key, metrics);
+        return metrics;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        // Detach measurement DOM even when getBBox throws.
+        detachMeasureDom(svg);
+    }
+}
+
+/**
+ * SvgCore entrypoint.
+ *
+ * Usage:
+ *   const v = new SvgCore(svgElement)
+ */
+class SvgCore {
+    canvas;
+    nodesLayer;
+    nodes = [];
+    nodeIdToIndex = new Map();
+    nodeBounds = null;
+    cullingEnabled = true;
+    cullingOverscanPx = 30;
+    resizeObserver = null;
+    unsubPanZoom = null;
+    unsubSvgEvents = null;
+    svgClickTimer = null;
+    suppressNextClick = false;
+    dragWatch = null;
+    cullingListeners = new Set();
+    lastCullingStats = { visible: 0, hidden: 0, total: 0 };
+    cullingNotifyScheduled = false;
+    /** SVG root passed to the constructor. */
+    get svg() {
+        return this.canvas.svg;
+    }
+    /** World layer (<g>) that you draw into. */
+    get world() {
+        return this.canvas.world;
+    }
+    /**
+     * Create a custom <g> layer inside the world.
+     * Useful when you want to add your own SVG content.
+     */
+    createWorldLayer(name, opts) {
+        const layer = svgEl("g");
+        if (name)
+            layer.dataset.layer = name;
+        if (opts?.pointerEvents)
+            layer.style.pointerEvents = opts.pointerEvents;
+        const position = opts?.position ?? "below-nodes";
+        if (position === "below-nodes") {
+            this.world.insertBefore(layer, this.nodesLayer);
+        }
+        else {
+            this.world.appendChild(layer);
+        }
+        return layer;
+    }
+    /** Current pan/zoom state. */
+    get state() {
+        return this.canvas.state;
+    }
+    /** Current pan/zoom options (includes minZoom/maxZoom). */
+    get panZoomOptions() {
+        return this.canvas.options;
+    }
+    constructor(svgOrCanvas, opts) {
+        if (svgOrCanvas instanceof PanZoomCanvas) {
+            this.canvas = svgOrCanvas;
+            if (opts?.panZoom)
+                this.canvas.setOptions(opts.panZoom);
+        }
+        else {
+            this.canvas = new PanZoomCanvas(svgOrCanvas, opts?.panZoom);
+        }
+        this.nodesLayer = document.createElementNS("http://www.w3.org/2000/svg", "g");
+        this.nodesLayer.dataset.layer = "nodes";
+        this.world.appendChild(this.nodesLayer);
+        this.world.style.pointerEvents = "none";
+        const c = opts?.culling;
+        if (typeof c === "boolean") {
+            this.cullingEnabled = c;
+        }
+        else if (c) {
+            if (typeof c.enabled === "boolean")
+                this.cullingEnabled = c.enabled;
+            if (typeof c.overscanPx === "number")
+                this.cullingOverscanPx = Math.max(0, c.overscanPx);
+        }
+        // Core-owned: keep culling in sync with pan/zoom changes.
+        this.unsubPanZoom = this.canvas.subscribe(() => this.applyCulling());
+        // Core-owned: keep culling correct when viewport size changes.
+        this.resizeObserver = new ResizeObserver(() => this.applyCulling());
+        this.resizeObserver.observe(this.svg);
+        // Core-owned: basic SVG interaction events (for now just log).
+        // Notes:
+        // - Drag-to-pan emits a "click" after pointerup; we suppress that when movement exceeds a threshold.
+        // - We do NOT use the native "dblclick" event. Instead:
+        //   - 1st click starts a short timer
+        //   - 2nd click within that window becomes "doubleclick" and cancels the pending single-click
+        const CLICK_DELAY_MS = 300;
+        const DRAG_THRESHOLD_PX = 5;
+        const clearClickTimer = () => {
+            if (this.svgClickTimer !== null) {
+                window.clearTimeout(this.svgClickTimer);
+                this.svgClickTimer = null;
+            }
+        };
+        const onPointerDown = (e) => {
+            // Only track left-button drags for click suppression.
+            if (e.button !== 0)
+                return;
+            this.dragWatch = {
+                pointerId: e.pointerId,
+                startClientX: e.clientX,
+                startClientY: e.clientY,
+                moved: false,
+            };
+        };
+        const onPointerMove = (e) => {
+            const w = this.dragWatch;
+            if (!w)
+                return;
+            if (e.pointerId !== w.pointerId)
+                return;
+            // Only while left button is held.
+            if ((e.buttons & 1) !== 1)
+                return;
+            const dx = e.clientX - w.startClientX;
+            const dy = e.clientY - w.startClientY;
+            if (!w.moved && Math.hypot(dx, dy) >= DRAG_THRESHOLD_PX)
+                w.moved = true;
+        };
+        const onPointerEnd = (e) => {
+            const w = this.dragWatch;
+            if (!w)
+                return;
+            if (e.pointerId !== w.pointerId)
+                return;
+            this.dragWatch = null;
+            if (w.moved) {
+                this.suppressNextClick = true;
+                clearClickTimer();
+            }
+        };
+        const onClick = (e) => {
+            if (this.suppressNextClick) {
+                this.suppressNextClick = false;
+                return;
+            }
+            if (this.svgClickTimer !== null) {
+                // Second click within the window => treat as "doubleclick".
+                clearClickTimer();
+                const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+                if (hit?.onDoubleClick) {
+                    hit.onDoubleClick(hit);
+                }
+                return;
+            }
+            // First click => delay, so a potential second click can convert it to "doubleclick".
+            this.svgClickTimer = window.setTimeout(() => {
+                this.svgClickTimer = null;
+                const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+                if (hit?.onClick) {
+                    hit.onClick(hit);
+                }
+            }, CLICK_DELAY_MS);
+        };
+        const onRightClick = (e) => {
+            e.preventDefault(); // treat this as "rightclick" without opening the context menu
+            clearClickTimer();
+            const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+            if (hit?.onRightClick) {
+                hit.onRightClick(hit);
+            }
+        };
+        this.svg.addEventListener("click", onClick);
+        this.svg.addEventListener("contextmenu", onRightClick);
+        this.svg.addEventListener("pointerdown", onPointerDown);
+        this.svg.addEventListener("pointermove", onPointerMove);
+        this.svg.addEventListener("pointerup", onPointerEnd);
+        this.svg.addEventListener("pointercancel", onPointerEnd);
+        this.unsubSvgEvents = () => {
+            this.svg.removeEventListener("click", onClick);
+            this.svg.removeEventListener("contextmenu", onRightClick);
+            this.svg.removeEventListener("pointerdown", onPointerDown);
+            this.svg.removeEventListener("pointermove", onPointerMove);
+            this.svg.removeEventListener("pointerup", onPointerEnd);
+            this.svg.removeEventListener("pointercancel", onPointerEnd);
+            clearClickTimer();
+        };
+    }
+    /**
+     * Set zoom while keeping a chosen screen-space anchor stable.
+     * By default anchors at the viewport center.
+     */
+    setZoom(nextZoom, anchor) {
+        const minZ = this.canvas.options.minZoom;
+        const maxZ = this.canvas.options.maxZoom;
+        const z = Math.min(maxZ, Math.max(minZ, nextZoom));
+        const r = this.svg.getBoundingClientRect();
+        const ax = anchor?.x ?? Math.max(1, r.width) / 2;
+        const ay = anchor?.y ?? Math.max(1, r.height) / 2;
+        const cur = this.state;
+        // screen = world * zoom + pan  => world = (screen - pan) / zoom
+        const worldX = (ax - cur.panX) / Math.max(1e-9, cur.zoom);
+        const worldY = (ay - cur.panY) / Math.max(1e-9, cur.zoom);
+        // keep world point under anchor stable:
+        // pan = screen - world * zoom
+        const nextPanX = ax - worldX * z;
+        const nextPanY = ay - worldY * z;
+        this.setState({ zoom: z, panX: nextPanX, panY: nextPanY });
+    }
+    /**
+     * Convert a pointer position (client px) into canvas/world coordinates,
+     * using the current pan/zoom state.
+     */
+    clientToCanvas(clientX, clientY) {
+        const r = this.svg.getBoundingClientRect();
+        const sx = clientX - r.left;
+        const sy = clientY - r.top;
+        const { panX, panY, zoom } = this.state;
+        const z = Math.max(1e-9, zoom);
+        return { x: (sx - panX) / z, y: (sy - panY) / z };
+    }
+    /**
+     * Fast hit-test using the culling output: only checks nodes currently attached to `nodesLayer`
+     * (i.e. the visible subset after culling).
+     *
+     * Returns the topmost hit node (based on render order), or null.
+     */
+    hitTestVisibleNodeAtClient(clientX, clientY) {
+        if (!this.nodeBounds || this.nodes.length === 0)
+            return null;
+        const p = this.clientToCanvas(clientX, clientY);
+        const kids = this.nodesLayer.children;
+        // Scan from topmost to bottommost: last child is visually on top.
+        for (let k = kids.length - 1; k >= 0; k--) {
+            const el = kids.item(k);
+            if (!el)
+                continue;
+            const id = el.dataset.nodeId;
+            if (!id)
+                continue;
+            const idx = this.nodeIdToIndex.get(id);
+            if (idx === undefined)
+                continue;
+            const b = this.nodeBounds[idx];
+            if (!b)
+                continue;
+            if (p.x >= b.x0 && p.x <= b.x1 && p.y >= b.y0 && p.y <= b.y1)
+                return this.nodes[idx];
+        }
+        return null;
+    }
+    zoomBy(factor, anchor) {
+        const f = Number.isFinite(factor) ? factor : 1;
+        if (f <= 0)
+            return;
+        this.setZoom(this.state.zoom * f, anchor);
+    }
+    setState(next) {
+        this.canvas.setState(next);
+    }
+    resetView() {
+        this.canvas.reset();
+    }
+    configurePanZoom(opts) {
+        this.canvas.setOptions(opts);
+    }
+    setNodes(nodes) {
+        // Warn if node IDs are not unique
+        const seenIds = new Set();
+        const duplicateIds = new Set();
+        for (let i = 0; i < nodes.length; i++) {
+            const id = nodes[i].id;
+            if (seenIds.has(id)) {
+                duplicateIds.add(id);
+            }
+            else {
+                seenIds.add(id);
+            }
+        }
+        if (duplicateIds.size > 0) {
+            console.warn(`Duplicate node ids found: ${Array.from(duplicateIds)
+                .map((id) => `"${id}"`)
+                .join(", ")}. Each node should have a unique id.`);
+        }
+        this.nodes = nodes;
+        this.nodeIdToIndex.clear();
+        // Build map of node id to index for fast lookup.
+        // Note: If there are duplicate IDs, the last occurrence will overwrite previous ones.
+        for (let i = 0; i < nodes.length; i++) {
+            this.nodeIdToIndex.set(nodes[i].id, i);
+        }
+        this.redraw();
+    }
+    /**
+     * Redraw the currently assigned nodes.
+     *
+     * Call this if you mutate node properties in-place (e.g. `node.x = ...` or `node.fragment = ...`).
+     *
+     * @param ids Optional array of node ids to redraw. If provided, only these nodes will be redrawn.
+     *            If not provided, all nodes will be redrawn.
+     */
+    redraw(ids) {
+        if (Array.isArray(ids) && ids.length > 0) {
+            this.renderNodes(ids);
+            // After selective render, we still need to apply culling to all nodes
+            this.applyCulling();
+        }
+        else {
+            this.renderNodes();
+            this.applyCulling();
+        }
+    }
+    setCullingEnabled(enabled) {
+        this.cullingEnabled = enabled;
+        this.applyCulling();
+    }
+    setCullingOverscanPx(px) {
+        this.cullingOverscanPx = Math.max(0, px);
+        this.applyCulling();
+    }
+    /** Subscribe to culling stats updates (event-driven). */
+    onCullingStatsChange(fn) {
+        this.cullingListeners.add(fn);
+        fn(this.lastCullingStats);
+        return () => this.cullingListeners.delete(fn);
+    }
+    /** Subscribe to pan/zoom updates (event-driven). */
+    onPanZoomChange(fn) {
+        return this.canvas.subscribe(fn);
+    }
+    /**
+     * Remove nodes from the scene.
+     *
+     * @param ids Optional array of node ids to remove. If not provided, removes all nodes.
+     */
+    remove(ids) {
+        if (!ids || ids.length === 0) {
+            // Remove all nodes
+            this.nodes = [];
+            this.nodeIdToIndex.clear();
+            this.nodesLayer.replaceChildren();
+            this.nodeBounds = null;
+            this.setCullingStats({ visible: 0, hidden: 0, total: 0 });
+            return;
+        }
+        // Remove specific nodes by ids
+        const indicesToRemove = new Set();
+        for (const id of ids) {
+            const idx = this.nodeIdToIndex.get(id);
+            if (idx !== undefined) {
+                indicesToRemove.add(idx);
+            }
+        }
+        if (indicesToRemove.size === 0)
+            return;
+        // Remove nodes in reverse order to maintain indices
+        const sortedIndices = Array.from(indicesToRemove).sort((a, b) => b - a);
+        for (const idx of sortedIndices) {
+            const node = this.nodes[idx];
+            if (node) {
+                // Remove from DOM
+                if (node.el.parentElement) {
+                    node.el.remove();
+                }
+                // Remove from map
+                this.nodeIdToIndex.delete(node.id);
+            }
+            this.nodes.splice(idx, 1);
+        }
+        // Rebuild index map
+        this.nodeIdToIndex.clear();
+        for (let i = 0; i < this.nodes.length; i++) {
+            this.nodeIdToIndex.set(this.nodes[i].id, i);
+        }
+        // Rebuild bounds array
+        if (this.nodeBounds) {
+            const newBounds = [];
+            for (let i = 0; i < this.nodes.length; i++) {
+                const node = this.nodes[i];
+                const metrics = measureFragmentMetrics(node.fragment);
+                const bbox = metrics?.bbox ?? { width: 240, height: 160 };
+                const pad = metrics?.pad ?? 0;
+                const w = node.width ?? Math.max(1, bbox.width + pad * 2);
+                const h = node.height ?? Math.max(1, bbox.height + pad * 2);
+                newBounds.push({ x0: node.x, y0: node.y, x1: node.x + w, y1: node.y + h });
+            }
+            this.nodeBounds = newBounds;
+        }
+        this.applyCulling();
+    }
+    destroy() {
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = null;
+        this.unsubPanZoom?.();
+        this.unsubPanZoom = null;
+        this.unsubSvgEvents?.();
+        this.unsubSvgEvents = null;
+        this.cullingListeners.clear();
+        this.canvas.destroy();
+    }
+    renderNodes(ids) {
+        // If ids are provided, only update those specific nodes
+        if (ids && ids.length > 0) {
+            for (const id of ids) {
+                const idx = this.nodeIdToIndex.get(id);
+                if (idx === undefined)
+                    continue;
+                const node = this.nodes[idx];
+                if (!node)
+                    continue;
+                const g = node.el;
+                g.replaceChildren();
+                g.setAttribute("transform", `translate(${node.x} ${node.y})`);
+                const cleaned = sanitizeFragment(node.fragment);
+                if (cleaned) {
+                    const children = parseFragmentElements(cleaned);
+                    const metrics = measureFragmentMetrics(cleaned);
+                    const bbox = metrics?.bbox ?? { x: 0, y: 0, width: 240, height: 160 };
+                    const pad = metrics?.pad ?? 0;
+                    const w = Math.max(1, bbox.width + pad * 2);
+                    const h = Math.max(1, bbox.height + pad * 2);
+                    const offsetX = -bbox.x + pad;
+                    const offsetY = -bbox.y + pad;
+                    const inner = document.createElementNS("http://www.w3.org/2000/svg", "g");
+                    inner.setAttribute("transform", `translate(${offsetX} ${offsetY})`);
+                    for (const child of children)
+                        inner.appendChild(child.cloneNode(true));
+                    g.appendChild(inner);
+                    // Update bounds
+                    if (this.nodeBounds) {
+                        const nodeW = node.width ?? w;
+                        const nodeH = node.height ?? h;
+                        this.nodeBounds[idx] = {
+                            x0: node.x,
+                            y0: node.y,
+                            x1: node.x + nodeW,
+                            y1: node.y + nodeH,
+                        };
+                    }
+                }
+                // Ensure node is attached if it's not already
+                if (!g.parentElement) {
+                    this.nodesLayer.appendChild(g);
+                }
+            }
+            return; // Culling will be applied by redraw()
+        }
+        // Full render: clear and rebuild everything
+        this.nodesLayer.replaceChildren();
+        this.nodeBounds = null;
+        if (this.nodes.length === 0)
+            return;
+        // Cache fragment -> parsed children and metrics.
+        // This allows each node to carry its own fragment while still keeping render fast.
+        const fragmentCache = new Map();
+        for (const node of this.nodes) {
+            const cleaned = sanitizeFragment(node.fragment);
+            if (!cleaned)
+                continue;
+            if (fragmentCache.has(cleaned))
+                continue;
+            const children = parseFragmentElements(cleaned);
+            const metrics = measureFragmentMetrics(cleaned);
+            const bbox = metrics?.bbox ?? { x: 0, y: 0, width: 240, height: 160 };
+            const pad = metrics?.pad ?? 0;
+            const w = Math.max(1, bbox.width + pad * 2);
+            const h = Math.max(1, bbox.height + pad * 2);
+            // Normalize fragment so its bbox starts at (0,0) with padding applied.
+            const offsetX = -bbox.x + pad;
+            const offsetY = -bbox.y + pad;
+            fragmentCache.set(cleaned, { children, w, h, offsetX, offsetY });
+        }
+        const count = this.nodes.length;
+        const frag = document.createDocumentFragment();
+        const bounds = new Array(count);
+        for (let i = 0; i < count; i++) {
+            const node = this.nodes[i];
+            const g = node.el;
+            g.replaceChildren();
+            g.setAttribute("transform", `translate(${node.x} ${node.y})`);
+            const cleaned = sanitizeFragment(node.fragment);
+            const cached = cleaned ? fragmentCache.get(cleaned) : null;
+            if (cached) {
+                // Insert the fragment content directly into the node group (no nested <svg>),
+                // but normalize it to (0,0) using a wrapper group.
+                const inner = document.createElementNS("http://www.w3.org/2000/svg", "g");
+                inner.setAttribute("transform", `translate(${cached.offsetX} ${cached.offsetY})`);
+                for (const child of cached.children)
+                    inner.appendChild(child.cloneNode(true));
+                g.appendChild(inner);
+            }
+            const w = node.width ?? cached?.w ?? 240;
+            const h = node.height ?? cached?.h ?? 160;
+            bounds[i] = { x0: node.x, y0: node.y, x1: node.x + w, y1: node.y + h };
+            frag.appendChild(g);
+        }
+        this.nodesLayer.appendChild(frag);
+        this.nodeBounds = bounds;
+    }
+    applyCulling() {
+        if (!this.nodeBounds) {
+            this.setCullingStats({ visible: 0, hidden: 0, total: this.nodes.length });
+            return;
+        }
+        const count = this.nodes.length;
+        // If disabled, ensure everything is visible/attached.
+        if (!this.cullingEnabled) {
+            this.nodesLayer.replaceChildren(...this.nodes.map((n) => n.el));
+            for (const n of this.nodes)
+                n.el.removeAttribute("display");
+            this.setCullingStats({ visible: count, hidden: 0, total: count });
+            return;
+        }
+        const vp = this.getWorldViewport(this.state, this.cullingOverscanPx);
+        const visibleNodes = [];
+        for (let i = 0; i < count; i++) {
+            const rect = this.nodeBounds[i];
+            if (rect && this.rectsIntersect(rect, vp)) {
+                const el = this.nodes[i].el;
+                el.removeAttribute("display");
+                visibleNodes.push(el);
+            }
+        }
+        this.nodesLayer.replaceChildren(...visibleNodes);
+        this.setCullingStats({
+            visible: visibleNodes.length,
+            hidden: count - visibleNodes.length,
+            total: count,
+        });
+    }
+    setCullingStats(next) {
+        const prev = this.lastCullingStats;
+        if (prev.visible === next.visible && prev.hidden === next.hidden && prev.total === next.total)
+            return;
+        this.lastCullingStats = next;
+        this.scheduleCullingNotify();
+    }
+    scheduleCullingNotify() {
+        if (this.cullingNotifyScheduled)
+            return;
+        this.cullingNotifyScheduled = true;
+        requestAnimationFrame(() => {
+            this.cullingNotifyScheduled = false;
+            for (const fn of this.cullingListeners)
+                fn(this.lastCullingStats);
+        });
+    }
+    rectsIntersect(a, b) {
+        return !(a.x1 < b.x0 || a.x0 > b.x1 || a.y1 < b.y0 || a.y0 > b.y1);
+    }
+    getWorldViewport(s, overscanPx) {
+        const r = this.svg.getBoundingClientRect();
+        const w = Math.max(1, r.width);
+        const h = Math.max(1, r.height);
+        const z = Math.max(1e-9, s.zoom);
+        // screen = world * zoom + pan
+        const o = Math.max(0, overscanPx) / z; // expand in world units
+        const x0 = -s.panX / z - o;
+        const y0 = -s.panY / z - o;
+        const x1 = (w - s.panX) / z + o;
+        const y1 = (h - s.panY) / z + o;
+        return { x0, y0, x1, y1 };
+    }
+}
+
+/**
+ * A scene-graph "node" for the SVG core.
+ */
+class Node {
+    id;
+    fragment;
+    x;
+    y;
+    width;
+    height;
+    onClick;
+    onDoubleClick;
+    onRightClick;
+    /** Backing element (created lazily by the core). */
+    _el = null;
+    constructor(opts) {
+        if (!opts || typeof opts.id !== "string" || opts.id === "") {
+            throw new Error("Node requires a non-empty 'id' property");
+        }
+        this.id = opts.id;
+        this.fragment = opts.fragment ?? "";
+        this.x = Number.isFinite(opts?.x) ? opts?.x : 0;
+        this.y = Number.isFinite(opts?.y) ? opts?.y : 0;
+        const w = opts?.width;
+        const h = opts?.height;
+        this.width = typeof w === "number" && Number.isFinite(w) && w > 0 ? w : null;
+        this.height = typeof h === "number" && Number.isFinite(h) && h > 0 ? h : null;
+        this.onClick = opts?.onClick;
+        this.onDoubleClick = opts?.onDoubleClick;
+        this.onRightClick = opts?.onRightClick;
+    }
+    get el() {
+        if (!this._el) {
+            const el = document.createElementNS("http://www.w3.org/2000/svg", "g");
+            el.dataset.nodeId = this.id;
+            this._el = el;
+        }
+        return this._el;
+    }
+}
+
+export { Node, PanZoomCanvas, SvgCore, measureFragmentMetrics };