@bpmnkit/canvas 0.0.27 → 0.0.29

package/dist/canvas.js

@@ -1,7 +1,9 @@
-import { Bpmn } from "@bpmnkit/core";
-import { injectStyles } from "./css.js";
+import { Bpmn, applyAutoLayout, checkDiCompleteness, planeForElement } from "@bpmnkit/core";
+import { CANVAS_CSS, injectStyles } from "./css.js";
 import { KeyboardHandler } from "./keyboard.js";
-import { computeDiagramBounds, createDefs, createGrid, render } from "./renderer.js";
+import { OverlayManager } from "./overlays.js";
+import { computeDiagramBounds, createDefs, createGrid } from "./renderer.js";
+import { Scene } from "./scene.js";
 import { ViewportController } from "./viewport.js";
 const NS = "http://www.w3.org/2000/svg";
 let _instanceCounter = 0;
@@ -64,9 +66,12 @@ export class BpmnCanvas {
     _labelsG;
     _gridPattern = null;
     _markerId = "";
+    _breadcrumb;
     // ── Sub-systems ───────────────────────────────────────────────────
     _viewport;
     _keyboard;
+    _overlays;
+    _scene;
     _plugins = [];
     // ── State ─────────────────────────────────────────────────────────
     _shapes = [];
@@ -74,6 +79,24 @@ export class BpmnCanvas {
     _currentDefs = null;
     _theme;
     _fit;
+    _layoutMissingDi;
+    /** Elements from the last load that had no diagram interchange. */
+    _importWarnings = { missingShapes: [], missingEdges: [] };
+    /** The DI plane currently rendered. */
+    _currentPlane = null;
+    /** Element ids (this document) that own a plane and can be drilled into. */
+    _planeElementIds = new Set();
+    /** Breadcrumb path from the root plane to the current one. */
+    _planeStack = [];
+    /** CSS classes applied via {@link addMarker}, keyed by element id. */
+    _markers = new Map();
+    /** Element id currently under the pointer (for hover enter/leave events). */
+    _hoverId = null;
+    /**
+     * Set once the user pans/zooms so a container resize preserves their
+     * viewport instead of force-fitting the diagram.
+     */
+    _userMovedViewport = false;
     // ── Event emitter ─────────────────────────────────────────────────
     _listeners = new Map();
     constructor(options) {
@@ -81,6 +104,7 @@ export class BpmnCanvas {
         this._id = String(_instanceCounter++);
         this._theme = options.theme ?? "auto";
         this._fit = options.fit ?? "contain";
+        this._layoutMissingDi = options.layoutMissingDi ?? "off";
         // ── Build DOM ────────────────────────────────────────────────
         const container = options.container;
         container.innerHTML = "";
@@ -95,6 +119,12 @@ export class BpmnCanvas {
         this._svg = document.createElementNS(NS, "svg");
         this._svg.setAttribute("aria-hidden", "true");
         this._host.appendChild(this._svg);
+        // Drill-down breadcrumb (hidden until a sub-process is opened)
+        this._breadcrumb = document.createElement("div");
+        this._breadcrumb.className = "bpmnkit-breadcrumb";
+        this._breadcrumb.setAttribute("aria-label", "Diagram plane");
+        this._breadcrumb.style.display = "none";
+        this._host.appendChild(this._breadcrumb);
         // Arrow marker defs
         this._markerId = createDefs(this._svg, this._id);
         // Dot grid
@@ -113,10 +143,24 @@ export class BpmnCanvas {
         this._viewportG.appendChild(this._edgesG);
         this._viewportG.appendChild(this._shapesG);
         this._viewportG.appendChild(this._labelsG);
+        // Scene owns the layer content + the id→graphics registry.
+        this._scene = new Scene({
+            containers: this._containersG,
+            edges: this._edgesG,
+            shapes: this._shapesG,
+            labels: this._labelsG,
+        }, this._id);
         // ── Viewport controller ───────────────────────────────────────
         this._viewport = new ViewportController(this._host, this._svg, this._viewportG, this._gridPattern, (state) => {
             this._emit("viewport:change", state);
         });
+        // ── Overlays ──────────────────────────────────────────────────
+        this._overlays = new OverlayManager({
+            hostEl: this._host,
+            getScale: () => this._viewport.state.scale,
+            getBBox: (id) => this.getAbsoluteBBox(id),
+            onViewportChange: (cb) => this.on("viewport:change", cb),
+        });
         // ── Keyboard ──────────────────────────────────────────────────
         this._keyboard = new KeyboardHandler(this._host, this._viewport, () => this.fitView(), (id) => {
             const shape = this._shapes.find((s) => s.id === id);
@@ -137,11 +181,55 @@ export class BpmnCanvas {
             // returns the root <svg> (reproducible in flex/scroll containers). Fall back
             // to e.target for test environments where elementFromPoint isn't reliable.
             const fromPoint = document.elementFromPoint(e.clientX, e.clientY);
-            const target = fromPoint?.closest("[data-bpmnkit-id]") ??
-                e.target.closest("[data-bpmnkit-id]");
+            const domTarget = fromPoint ?? e.target;
+            // Drill-down button takes precedence over element selection.
+            const drill = domTarget
+                .closest("[data-bpmnkit-drilldown]")
+                ?.getAttribute("data-bpmnkit-drilldown");
+            if (drill) {
+                this.showPlane(drill);
+                return;
+            }
+            const target = domTarget.closest("[data-bpmnkit-id]");
             const id = target?.getAttribute("data-bpmnkit-id");
             if (id)
                 this._emit("element:click", id, e);
+            else
+                this._emit("canvas:click", e);
+        });
+        // ── Hover / out ───────────────────────────────────────────────
+        this._svg.addEventListener("pointermove", (e) => {
+            // Suppress hover changes while a button is held (panning/pinching).
+            if (e.buttons !== 0)
+                return;
+            const id = this._elementIdForEvent(e);
+            if (id === this._hoverId)
+                return;
+            if (this._hoverId !== null)
+                this._emit("element:out", this._hoverId);
+            this._hoverId = id;
+            if (id !== null)
+                this._emit("element:hover", id, e);
+        });
+        // ── Double-click ──────────────────────────────────────────────
+        this._svg.addEventListener("dblclick", (e) => {
+            const id = this._elementIdForEvent(e);
+            if (id)
+                this._emit("element:dblclick", id, e);
+        });
+        // ── Context menu ──────────────────────────────────────────────
+        this._svg.addEventListener("contextmenu", (e) => {
+            const id = this._elementIdForEvent(e);
+            if (id)
+                this._emit("element:contextmenu", id, e);
+        });
+        // ── Track user viewport interaction ───────────────────────────
+        this._svg.addEventListener("wheel", () => {
+            this._userMovedViewport = true;
+        });
+        this._svg.addEventListener("pointerup", () => {
+            if (this._viewport.didPan)
+                this._userMovedViewport = true;
         });
         // ── Install plugins ───────────────────────────────────────────
         if (options.plugins) {
@@ -153,9 +241,10 @@ export class BpmnCanvas {
         if (options.xml) {
             this.load(options.xml);
         }
-        // Re-fit on container resize
+        // Re-fit on container resize — but only while the user hasn't taken
+        // control of the viewport, so an explicit pan/zoom survives a resize.
         const ro = new ResizeObserver(() => {
-            if (this._currentDefs)
+            if (this._currentDefs && !this._userMovedViewport)
                 this.fitView();
         });
         ro.observe(this._host);
@@ -177,33 +266,117 @@ export class BpmnCanvas {
      * Use this when you already have the parsed model from `@bpmnkit/core`.
      */
     loadDefinitions(defs) {
-        // Clear previous content
-        this._containersG.innerHTML = "";
-        this._edgesG.innerHTML = "";
-        this._shapesG.innerHTML = "";
-        this._labelsG.innerHTML = "";
-        this._shapes = [];
-        this._edges = [];
-        this._currentDefs = defs;
-        const result = render(defs, this._containersG, this._edgesG, this._shapesG, this._labelsG, this._markerId, this._id);
-        this._shapes = result.shapes;
-        this._edges = result.edges;
+        // Report elements that have no diagram interchange (they would otherwise
+        // be invisible). Warnings describe the *source* model, even when we
+        // auto-layout below.
+        this._importWarnings = checkDiCompleteness(defs);
+        const hasMissingDi = this._importWarnings.missingShapes.length > 0 || this._importWarnings.missingEdges.length > 0;
+        if (hasMissingDi) {
+            const outcome = this._layoutMissingDi === "all" ? "auto-laying out" : "they will not render";
+            const { missingShapes, missingEdges } = this._importWarnings;
+            console.warn(`[bpmnkit] diagram has ${missingShapes.length} element(s) and ${missingEdges.length} connection(s) without diagram interchange — ${outcome}`);
+        }
+        // Optionally lay out a copy so DI-less elements become visible. The
+        // caller's `defs` is never mutated (applyAutoLayout returns a fresh copy).
+        const rendered = this._layoutMissingDi === "all" && hasMissingDi ? applyAutoLayout(defs) : defs;
+        this._currentDefs = rendered;
+        this._planeElementIds = new Set(rendered.diagrams.map((d) => d.plane.bpmnElement));
+        // Start at the primary (first) plane and reset the breadcrumb.
+        const root = rendered.diagrams[0]?.plane;
+        this._planeStack = root
+            ? [{ id: root.bpmnElement, name: this._planeName(root.bpmnElement) }]
+            : [];
+        // A freshly loaded diagram should auto-fit again until the user interacts.
+        this._userMovedViewport = false;
+        this._renderPlane(root ?? null);
+        this._emit("diagram:load", rendered, this._importWarnings);
+    }
+    /**
+     * Returns the elements from the last {@link load}/{@link loadDefinitions}
+     * that had no diagram interchange (and so were auto-laid-out or skipped).
+     */
+    getImportWarnings() {
+        return {
+            missingShapes: [...this._importWarnings.missingShapes],
+            missingEdges: [...this._importWarnings.missingEdges],
+        };
+    }
+    /**
+     * Lists every DI plane in the current document (the primary plane plus any
+     * collapsed sub-processes that carry their own layout).
+     */
+    getPlanes() {
+        if (!this._currentDefs)
+            return [];
+        return this._currentDefs.diagrams.map((d) => ({
+            id: d.plane.bpmnElement,
+            name: this._planeName(d.plane.bpmnElement),
+        }));
+    }
+    /**
+     * Shows the plane identified by a DI plane `bpmnElement` (a process/
+     * collaboration id or a collapsed sub-process id). Drilling into a
+     * sub-process extends the breadcrumb; navigating to an ancestor trims it.
+     * No-op if the id has no plane. Fires `plane:change`.
+     */
+    showPlane(planeElementId) {
+        if (!this._currentDefs)
+            return;
+        const isRoot = this._currentDefs.diagrams[0]?.plane.bpmnElement === planeElementId;
+        const plane = isRoot
+            ? this._currentDefs.diagrams[0]?.plane
+            : planeForElement(this._currentDefs, planeElementId);
+        if (!plane)
+            return;
+        const fromId = this._currentPlane?.bpmnElement ?? "";
+        if (fromId === planeElementId)
+            return;
+        // Navigate up if already in the breadcrumb, otherwise drill down.
+        const existing = this._planeStack.findIndex((c) => c.id === planeElementId);
+        if (existing >= 0) {
+            this._planeStack = this._planeStack.slice(0, existing + 1);
+        }
+        else {
+            this._planeStack.push({ id: planeElementId, name: this._planeName(planeElementId) });
+        }
+        this._userMovedViewport = false;
+        this._renderPlane(plane);
+        this._emit("plane:change", fromId, planeElementId);
+    }
+    /** Renders a specific plane into the (cleared) layers and refits. */
+    _renderPlane(plane) {
+        this._markers.clear();
+        this._overlays.clear();
+        this._hoverId = null;
+        this._currentPlane = plane;
+        if (this._currentDefs && plane) {
+            this._scene.render(this._currentDefs, plane, this._planeElementIds);
+        }
+        else {
+            this._scene.clear();
+        }
+        this._shapes = this._scene.getShapes();
+        this._edges = this._scene.getEdges();
         this._keyboard.setShapes(this._shapes);
+        this._updateBreadcrumb();
         if (this._fit !== "none") {
             // Defer fit to next frame so the SVG has been laid out
             requestAnimationFrame(() => this.fitView());
         }
-        this._emit("diagram:load", defs);
     }
     /** Clears the canvas and fires `diagram:clear`. */
     clear() {
-        this._containersG.innerHTML = "";
-        this._edgesG.innerHTML = "";
-        this._shapesG.innerHTML = "";
-        this._labelsG.innerHTML = "";
+        this._scene.clear();
         this._shapes = [];
         this._edges = [];
+        this._markers.clear();
+        this._overlays.clear();
+        this._hoverId = null;
         this._currentDefs = null;
+        this._currentPlane = null;
+        this._planeStack = [];
+        this._planeElementIds.clear();
+        this._updateBreadcrumb();
         this._emit("diagram:clear");
     }
     /**
@@ -213,7 +386,7 @@ export class BpmnCanvas {
     fitView(padding = 40) {
         if (!this._currentDefs)
             return;
-        const bounds = computeDiagramBounds(this._currentDefs);
+        const bounds = computeDiagramBounds(this._currentDefs, this._currentPlane ?? undefined);
         if (!bounds)
             return;
         const svgW = this._svg.clientWidth;
@@ -238,21 +411,217 @@ export class BpmnCanvas {
         this._theme = theme;
         this._applyTheme(theme);
     }
+    /**
+     * HTML overlays anchored to diagram elements (badges, tooltips, panels).
+     * @example
+     * ```typescript
+     * canvas.overlays.add("Task_1", {
+     *   position: { top: -8, right: -8 },
+     *   html: `<span class="badge">!</span>`,
+     * });
+     * ```
+     */
+    get overlays() {
+        return this._overlays;
+    }
+    /** Returns the rendered shape or edge for a BPMN id, or `undefined` (O(1)). */
+    getElement(id) {
+        return this._scene.getElement(id);
+    }
+    /** Returns the `<g>` graphics element for a BPMN id, or `undefined` (O(1)). */
+    getGraphics(id) {
+        return this._scene.getGraphics(id);
+    }
+    /** Iterates every rendered element (shapes and edges). */
+    forEachElement(fn) {
+        this._scene.forEach(fn);
+    }
+    /**
+     * Re-renders a single element's `<g>` in place from the current model,
+     * preserving markers/selection classes — the incremental-update path used
+     * for cheap edits. No-op for an unknown id.
+     */
+    updateElement(id) {
+        this._scene.updateElement(id);
+        this._shapes = this._scene.getShapes();
+        this._edges = this._scene.getEdges();
+        this._keyboard.setShapes(this._shapes);
+        this._overlays.reposition();
+    }
     /** Zooms in by 25% centred on the canvas. */
     zoomIn() {
         const { width, height } = this._svg.getBoundingClientRect();
+        this._userMovedViewport = true;
         this._viewport.zoomAt(width / 2, height / 2, 1.25);
     }
     /** Zooms out by 25% centred on the canvas. */
     zoomOut() {
         const { width, height } = this._svg.getBoundingClientRect();
+        this._userMovedViewport = true;
         this._viewport.zoomAt(width / 2, height / 2, 0.8);
     }
     /** Resets to 100% zoom, centred on the canvas. */
     resetZoom() {
         const { width, height } = this._svg.getBoundingClientRect();
+        this._userMovedViewport = true;
         this._viewport.set({ scale: 1, tx: width / 2, ty: height / 2 });
     }
+    /**
+     * Adjusts the zoom. Pass `"fit"` (or no argument) to fit the whole diagram;
+     * pass a number for an absolute scale, optionally keeping `center`
+     * (screen-space pixels relative to the host) fixed.
+     */
+    zoom(scaleOrFit = "fit", center) {
+        if (scaleOrFit === "fit") {
+            this._userMovedViewport = false;
+            this.fitView();
+            return;
+        }
+        this._userMovedViewport = true;
+        const { width, height } = this._svg.getBoundingClientRect();
+        const cx = center?.x ?? width / 2;
+        const cy = center?.y ?? height / 2;
+        const current = this._viewport.state.scale;
+        if (current > 0)
+            this._viewport.zoomAt(cx, cy, scaleOrFit / current);
+    }
+    /** Returns the visible region in diagram coordinates plus the zoom scale. */
+    viewbox() {
+        const { tx, ty, scale } = this._viewport.state;
+        const { width, height } = this._svg.getBoundingClientRect();
+        return { x: -tx / scale, y: -ty / scale, width: width / scale, height: height / scale, scale };
+    }
+    /** Pans (without changing zoom) so the element with the given id is centred. */
+    scrollToElement(id) {
+        const box = this._diagramBounds(id);
+        if (!box)
+            return;
+        const { scale } = this._viewport.state;
+        const { width, height } = this._svg.getBoundingClientRect();
+        const centerX = box.x + box.width / 2;
+        const centerY = box.y + box.height / 2;
+        this._userMovedViewport = true;
+        this._viewport.set({ tx: width / 2 - centerX * scale, ty: height / 2 - centerY * scale });
+    }
+    /**
+     * Returns the element's bounding box in screen pixels relative to the host,
+     * or `null` if the element is not found.
+     */
+    getAbsoluteBBox(id) {
+        const box = this._diagramBounds(id);
+        if (!box)
+            return null;
+        const { tx, ty, scale } = this._viewport.state;
+        return {
+            x: box.x * scale + tx,
+            y: box.y * scale + ty,
+            width: box.width * scale,
+            height: box.height * scale,
+        };
+    }
+    /**
+     * Serializes the current diagram to a standalone SVG string with theme
+     * colours inlined, so it renders correctly outside the page.
+     * @param opts.bounds `"diagram"` (default) exports the whole diagram;
+     *   `"viewport"` exports only the currently visible region.
+     */
+    exportSvg(opts) {
+        const box = opts?.bounds === "viewport"
+            ? (() => {
+                const v = this.viewbox();
+                return { x: v.x, y: v.y, width: v.width, height: v.height };
+            })()
+            : (() => {
+                const b = this._currentDefs
+                    ? computeDiagramBounds(this._currentDefs, this._currentPlane ?? undefined)
+                    : null;
+                const pad = 20;
+                return b
+                    ? {
+                        x: b.minX - pad,
+                        y: b.minY - pad,
+                        width: b.maxX - b.minX + pad * 2,
+                        height: b.maxY - b.minY + pad * 2,
+                    }
+                    : { x: 0, y: 0, width: 0, height: 0 };
+            })();
+        const svg = document.createElementNS(NS, "svg");
+        svg.setAttribute("xmlns", NS);
+        svg.setAttribute("viewBox", `${box.x} ${box.y} ${box.width} ${box.height}`);
+        svg.setAttribute("width", String(Math.round(box.width)));
+        svg.setAttribute("height", String(Math.round(box.height)));
+        const style = document.createElementNS(NS, "style");
+        style.textContent = this._exportStyles();
+        svg.appendChild(style);
+        // Marker/pattern defs so `url(#…)` references resolve inside the export.
+        const liveDefs = this._svg.querySelector("defs");
+        if (liveDefs)
+            svg.appendChild(liveDefs.cloneNode(true));
+        // Diagram content lives in the layer groups in diagram coordinates (the
+        // pan/zoom transform is on the viewport group, which is intentionally
+        // excluded so the viewBox alone frames the content).
+        for (const layer of [this._containersG, this._edgesG, this._shapesG, this._labelsG]) {
+            svg.appendChild(layer.cloneNode(true));
+        }
+        return new XMLSerializer().serializeToString(svg);
+    }
+    /**
+     * Rasterizes the current diagram to a PNG data URL at `scale`× the diagram
+     * size. Browser-only (requires `Image`/`<canvas>`).
+     */
+    exportPng(scale = 2) {
+        const svgString = this.exportSvg();
+        const match = svgString.match(/width="(\d+)" height="(\d+)"/);
+        const w = (match ? Number(match[1]) : 0) * scale;
+        const h = (match ? Number(match[2]) : 0) * scale;
+        const url = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgString)}`;
+        return new Promise((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => {
+                const canvas = document.createElement("canvas");
+                canvas.width = w;
+                canvas.height = h;
+                const ctx = canvas.getContext("2d");
+                if (!ctx) {
+                    reject(new Error("2D canvas context unavailable"));
+                    return;
+                }
+                ctx.drawImage(img, 0, 0, w, h);
+                resolve(canvas.toDataURL("image/png"));
+            };
+            img.onerror = () => reject(new Error("Failed to rasterize SVG"));
+            img.src = url;
+        });
+    }
+    /** Adds a CSS class to the element with the given BPMN id. No-op if not found. */
+    addMarker(id, cls) {
+        const element = this._findElement(id);
+        if (!element)
+            return;
+        element.classList.add(cls);
+        let set = this._markers.get(id);
+        if (!set) {
+            set = new Set();
+            this._markers.set(id, set);
+        }
+        set.add(cls);
+    }
+    /** Removes a CSS class from the element with the given BPMN id. */
+    removeMarker(id, cls) {
+        this._findElement(id)?.classList.remove(cls);
+        this._markers.get(id)?.delete(cls);
+    }
+    /** Returns whether the element with the given id currently has the CSS class. */
+    hasMarker(id, cls) {
+        return this._findElement(id)?.classList.contains(cls) ?? false;
+    }
+    /** Toggles a CSS class on the element with the given id. */
+    toggleMarker(id, cls) {
+        if (this.hasMarker(id, cls))
+            this.removeMarker(id, cls);
+        else
+            this.addMarker(id, cls);
+    }
     /**
      * Subscribes to a canvas event. Returns an unsubscribe function.
      *
@@ -282,23 +651,25 @@ export class BpmnCanvas {
      */
     highlight(ids, variant) {
         const cls = `bpmnkit-highlight--${variant}`;
-        const idSet = new Set(ids);
-        for (const { id, element } of [...this._shapes, ...this._edges]) {
-            if (idSet.has(id))
-                element.classList.add(cls);
-        }
+        for (const id of ids)
+            this.addMarker(id, cls);
     }
     /** Removes all highlight classes added by {@link highlight}. */
     clearHighlights() {
         for (const { element } of [...this._shapes, ...this._edges]) {
             element.classList.remove("bpmnkit-highlight--changed", "bpmnkit-highlight--new");
         }
+        for (const set of this._markers.values()) {
+            set.delete("bpmnkit-highlight--changed");
+            set.delete("bpmnkit-highlight--new");
+        }
     }
     /** Destroys the canvas, removing all DOM nodes and event listeners. */
     destroy() {
         this._ro.disconnect();
         this._viewport.destroy();
         this._keyboard.destroy();
+        this._overlays.destroy();
         for (const plugin of this._plugins)
             plugin.uninstall?.();
         this._plugins.length = 0;
@@ -306,6 +677,121 @@ export class BpmnCanvas {
         this._host.remove();
     }
     // ── Private ───────────────────────────────────────────────────────
+    /** Finds the SVG group for a shape or edge by BPMN id. */
+    _findElement(id) {
+        return this._scene.getGraphics(id);
+    }
+    /** Design tokens to resolve from the live host for a self-contained export. */
+    static _EXPORT_TOKENS = [
+        "--bpmnkit-bg",
+        "--bpmnkit-grid",
+        "--bpmnkit-shape-fill",
+        "--bpmnkit-shape-stroke",
+        "--bpmnkit-flow-stroke",
+        "--bpmnkit-text",
+        "--bpmnkit-highlight",
+        "--bpmnkit-focus",
+        "--bpmnkit-warn",
+        "--bpmnkit-success",
+    ];
+    /** Stylesheet for the exported SVG: resolved theme tokens + the canvas CSS. */
+    _exportStyles() {
+        const decls = [];
+        if (typeof getComputedStyle !== "undefined") {
+            const cs = getComputedStyle(this._host);
+            for (const token of BpmnCanvas._EXPORT_TOKENS) {
+                const value = cs.getPropertyValue(token).trim();
+                if (value)
+                    decls.push(`${token}: ${value};`);
+            }
+        }
+        const rootRule = decls.length ? `svg { ${decls.join(" ")} }\n` : "";
+        return `${rootRule}${CANVAS_CSS}`;
+    }
+    /** A human-readable label for a plane's `bpmnElement` (name, or a fallback). */
+    _planeName(planeElementId) {
+        const el = this._findFlowElementById(planeElementId);
+        if (el)
+            return el.name ?? "Sub-process";
+        return "Process";
+    }
+    /** Recursively finds a flow element by id across all processes/sub-processes. */
+    _findFlowElementById(id) {
+        if (!this._currentDefs)
+            return undefined;
+        const walk = (elements) => {
+            for (const el of elements) {
+                if (el.id === id)
+                    return el;
+                if ("flowElements" in el) {
+                    const found = walk(el.flowElements);
+                    if (found)
+                        return found;
+                }
+            }
+            return undefined;
+        };
+        for (const proc of this._currentDefs.processes) {
+            const found = walk(proc.flowElements);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    /** Rebuilds the breadcrumb bar from the current plane stack. */
+    _updateBreadcrumb() {
+        if (this._planeStack.length <= 1) {
+            this._breadcrumb.style.display = "none";
+            this._breadcrumb.replaceChildren();
+            return;
+        }
+        this._breadcrumb.style.display = "";
+        this._breadcrumb.replaceChildren();
+        this._planeStack.forEach((crumb, i) => {
+            if (i > 0) {
+                const sep = document.createElement("span");
+                sep.className = "bpmnkit-breadcrumb-sep";
+                sep.textContent = "›";
+                this._breadcrumb.appendChild(sep);
+            }
+            const btn = document.createElement("button");
+            btn.type = "button";
+            btn.className = "bpmnkit-breadcrumb-crumb";
+            btn.textContent = crumb.name;
+            const targetId = crumb.id;
+            btn.addEventListener("click", () => this.showPlane(targetId));
+            this._breadcrumb.appendChild(btn);
+        });
+    }
+    /**
+     * Resolves the BPMN element id under a pointer/mouse event, or `null`.
+     * Prefers `elementFromPoint` (correct when native SVG hit-testing returns
+     * the root `<svg>` in flex/scroll containers) and falls back to the event
+     * target (for environments where `elementFromPoint` is unavailable).
+     */
+    _elementIdForEvent(e) {
+        const fromPoint = document.elementFromPoint(e.clientX, e.clientY);
+        const target = fromPoint?.closest("[data-bpmnkit-id]") ??
+            e.target?.closest("[data-bpmnkit-id]");
+        return target?.getAttribute("data-bpmnkit-id") ?? null;
+    }
+    /** Diagram-coordinate bounds of a shape (from DI) or edge (waypoint bbox). */
+    _diagramBounds(id) {
+        const shape = this._shapes.find((s) => s.id === id);
+        if (shape) {
+            const { x, y, width, height } = shape.shape.bounds;
+            return { x, y, width, height };
+        }
+        const edge = this._edges.find((e) => e.id === id);
+        if (edge && edge.edge.waypoints.length > 0) {
+            const xs = edge.edge.waypoints.map((w) => w.x);
+            const ys = edge.edge.waypoints.map((w) => w.y);
+            const minX = Math.min(...xs);
+            const minY = Math.min(...ys);
+            return { x: minX, y: minY, width: Math.max(...xs) - minX, height: Math.max(...ys) - minY };
+        }
+        return null;
+    }
     _applyTheme(theme) {
         const resolved = theme === "auto"
             ? window.matchMedia("(prefers-color-scheme: dark)").matches
@@ -326,11 +812,23 @@ export class BpmnCanvas {
             svg: this._svg,
             viewportEl: this._viewportG,
             getViewport: () => this._viewport.state,
-            setViewport: (s) => this._viewport.set(s),
+            setViewport: (s) => {
+                this._userMovedViewport = true;
+                this._viewport.set(s);
+            },
             getShapes: () => [...this._shapes],
             getEdges: () => [...this._edges],
             getTheme: () => this._theme,
             setTheme: (theme) => this.setTheme(theme),
+            overlays: this._overlays,
+            addMarker: (id, cls) => this.addMarker(id, cls),
+            removeMarker: (id, cls) => this.removeMarker(id, cls),
+            hasMarker: (id, cls) => this.hasMarker(id, cls),
+            toggleMarker: (id, cls) => this.toggleMarker(id, cls),
+            zoom: (scaleOrFit, center) => this.zoom(scaleOrFit, center),
+            viewbox: () => this.viewbox(),
+            scrollToElement: (id) => this.scrollToElement(id),
+            getAbsoluteBBox: (id) => this.getAbsoluteBBox(id),
             on: (event, handler) => this.on(event, handler),
             emit: (event, ...args) => this._emit(event, ...args),
         };