@peter.prib/renderengine 0.13.0 → 0.15.0

package/documentation/REFERENCE.md

@@ -74,7 +74,7 @@ catalog `key` for you.
 | `sankey` | `sankeyDiagram(data, opts)` | `{nodes?: Array<{id,label?,color?}>, links: Array<{source,target,value}>}` | proportional-width flow links; `nodeWidth`, `linkOpacity` |
 | `chord` | `chordDiagram(data, opts)` | same as `sankey` | nodes on a circle with curved chords of proportional thickness |
 | `candlestick` | `candlestick(data, opts)` | `Array<{label, open, high, low, close}>` | `upColor`, `downColor`, `markers` (tooltip annotations) |
-| `stackedBar` | `stackedBarChart(data, opts)` | `Array<{label, values:number[]}>` | `colors` (no built-in legend — a known gap) |
+| `stackedBar` | `stackedBarChart(data, opts)` | multi-series `Array<{name, values:Array<{label,value}>}>` or `Array<{label, values:number[]}>` | `colors`, `legend`, `seriesLabels`; draws Y-axis ticks and legend |
 | `pipe` | `pipeChart(data, opts)` | `Array<{label, value, metric?}>` or multi-series | `metric` tapers line width; `legend` |
 | `radar` | `radarChart(data, opts)` | `Array<{axis, value}>` or multi-series | `colors`, `legend` |
 | `funnel` | `funnelChart(data, opts)` | `Array<{label, value}>` (largest first) | `colors` |
@@ -3200,6 +3200,44 @@ to it) / `deleteEdgeCommand(id)`. A subclass whose shapes and lines stand for so
 overrides those factories (ArchimateCanvasEditor does). A template class says whether the editor
 offers it a rotate handle (`static rotatable`, true by default; ArchiMate's templates are not). `pickFile(accept)` resolves with the chosen `File` (or `null`).
 
+## Decision Workbench (`DecisionWorkbench`)
+
+The views of a SADIS recommendation made by decisionengine (`gitlab.com/peter.prib/decisionengine`),
+drawn with this library's charts. It reads decisionengine's JSON, not decisionengine: a workbench
+document
+
+```js
+{ kind: 'sadis-workbench', report, plan?, before? }   // report.toJSON(), plan.toJSON(), an earlier report.toJSON()
+```
+
+which decisionengine's SADIS Explorer downloads ("Download for the Decision Workbench").
+
+```js
+import { DecisionWorkbench } from '@peter.prib/renderengine';
+const workbench = DecisionWorkbench.from(doc, { start: '2026-11-02', periodDays: 14 });
+for (const view of workbench.views()) {
+    view.id, view.title;          // 'executive', 'Executive', …
+    view.charts();                // [{ title, chartType, data, options }] — chartType is a CHART_CATALOG key
+    view.notes();                 // plain lines for what the charts cannot show
+}
+```
+
+| View | Needs | Charts |
+|---|---|---|
+| Executive | a report | `kpi-tile` (what to build next; half the value delivered by), `stackedBar` (score part by part), `line` (value delivered by period) |
+| Architecture | a report | `scatter` (visible rating against basin position: foundations sit high and left), `lollipop` (share each frees) |
+| Delivery | a plan | `gantt` (the plan on a calendar), `stackedBar` (capacity used per period, per team when planned by team) |
+| Portfolio | a report with perspectives | `heatmap` (rank by perspective), `dumbbell` (best and worst rank, most contested first) |
+| Replay | an earlier report | `slopegraph` (rank then → now); notes say what entered, left (and why) and moved |
+
+A view the document cannot fill is not offered. `from()` refuses what is not a workbench document,
+saying why. The delivery plan's periods are put on a calendar: period 1 starts at `start` (default:
+the report's as-of business time, else today), each `periodDays` long (default 14). Each view is a
+`WorkbenchView` subclass (`WORKBENCH_VIEWS`); a new view is a new subclass.
+
+`examples/decision-workbench.html` is the page: open a workbench file and each view is a workspace
+perspective, its charts in `ChartPart`s and its notes in a list.
+
 ## Navigation menus
 
 `NavMenu` is a vertical navigation menu (a sidebar's), written as data: no markup. Each entry is
@@ -3282,6 +3320,35 @@ const mine = ICONS.with({                            // a host's own icons over
 the workspace bundle), until a `foreignObject`, whose children are HTML again. A spec's `ns` sets the namespace
 explicitly.
 
+## Ask Bar & Next-Word Typeahead (`AskBar` / `AskView`)
+
+`AskBar` (`src/charting/ask/AskBar.js`) and its DOM-free state model `AskView` (`src/charting/ask/AskView.js`) provide the interactive question bar and scrollable next-word prediction dropdown (as used in `semanticengine/examples/browser/index.html` and the **Cubing** tab in `test/charts.html`).
+
+```javascript
+import { RenderEngine, AskBar, AskView } from '@peter.prib/renderengine';
+
+const bar = RenderEngine.askBar(document.getElementById('ask-bar'), {
+    value: 'top 3 customers by revenue',
+    // Either pass a custom suggestion callback (e.g. semanticengine's engine.suggest):
+    suggest: (text) => semanticEngine.suggest(text, { sampler: (dim) => semanticEngine.members(dim) }),
+    // Or pass declarative cube/table metadata for built-in next-word prediction:
+    // measures: ['Revenue', 'Cost'],
+    // dimensions: ['Region', 'Quarter'],
+    // members: (dim) => [...],
+    sampleQuestions: ['revenue by region', 'top 3 customers by revenue'],
+    visibleCount: 5,                     // items visible at once in the scrollable list
+    predictChoices: [0, 3, 5, 8, 10],    // 0 = Off; user can switch in the bar's selector
+    onAsk: (question) => runQuery(question),
+});
+```
+
+- **Configurable scrollable next-word prediction:** `visibleCount` (default `5`) sets how many predicted items show at once before scrolling (`max-height` on `.re-ask-suggest-box` with `overflow-y: auto`), and `predictChoices` (default `[0, 3, 5, 8, 10]`) populates the **Predict next word** selector (`Off`, `3 visible (scrollable)`, `5 visible (scrollable)`, …). Set `showPredictControl: false` to hide the selector.
+- **Semantic badges:** each suggestion item (`{ display, completion, sense?, reference?, relation?, kind? }`) renders its `display` token, optional `sense → reference` subtitle, lexical `relation` badge (`synonym`, `hypernym`, `hyponym`, `antonym`), and `kind` badge (`metric`, `dimension`, `keyword`, `value`).
+- **Keyboard navigation:** nothing in the list is selected until you move into it, so `Enter` asks the question as typed. `↑` / `↓` move through the scrollable list, starting at the last or first item and scrolling the active item into view. `Enter` completes the selected item; `Tab` completes the selected item, or the first. Either one immediately predicts the following word. `Escape` closes the popup.
+- **Async sources and answers:** `suggest` can return a promise, for example from an engine that is still loading or a vocabulary on a server. The list keeps showing what it had until the promise settles. An answer for text the user has since changed is dropped, and a rejected promise shows no suggestions. `onAsk` can also return a promise of `{ rows, columns, complete }`, which `resultEngine` shows once it settles.
+- **For a host:** `bar.setSuggest(fn)` swaps where suggestions come from, for example when the user picks another model or ontology. `bar.setValue(text)` sets the question without suggesting. `bar.focus()` puts the cursor in the question, and `bar.destroy()` removes the bar and cancels any pending close.
+- **Accessible:** the input is a WAI-ARIA combobox over a `listbox` of `option`s. `aria-expanded` follows the popup and `aria-activedescendant` follows the active item. Each bar's list has its own id, so several bars can share a page.
+
 ## Where to go next
 
 - **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.13.0",
-  "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
+  "version": "0.15.0",
+  "description": "ArchiMate modeller, data modeller, diagram editor, OLAP cube & pivot chart studio, and 50+ type chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
   "browser": "dist/renderengine.umd.js",
+  "bin": {
+    "renderengine": "./bin/renderengine.mjs"
+  },
   "exports": {
     ".": "./src/index.js",
     "./workspace": "./src/workspace/index.js",
@@ -14,6 +17,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin/*.mjs",
     "src/",
     "dist/*.umd.js",
     "examples/archimate.html",
@@ -24,11 +28,12 @@
     "LICENSE"
   ],
   "scripts": {
+    "cli": "node bin/renderengine.mjs",
     "start": "node scripts/open.mjs examples/archimate.html",
     "archimate": "node scripts/open.mjs examples/archimate.html",
     "diagram": "node scripts/open.mjs examples/diagram-editor.html",
     "datamodel": "node scripts/open.mjs examples/data-model.html",
-    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/pivot/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
+    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/pivot/*.js ./test/charting/ask/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
     "build": "rollup -c",
     "prepublishOnly": "npm test && npm run build",
     "screenshots": "node scripts/screenshots/screenshots.mjs"
@@ -38,6 +43,11 @@
     "archi",
     "diagram",
     "diagram-editor",
+    "data-modelling",
+    "bian",
+    "olap",
+    "pivot",
+    "cube",
     "modelling",
     "charts",
     "svg",

package/src/CanvasRenderer.js

@@ -1,201 +1,226 @@
-import { BaseRenderer } from './BaseRenderer.js';
-
-/**
- * @class CanvasRenderer
- * Renders shapes by drawing on a 2D canvas context.
- */
-export class CanvasRenderer extends BaseRenderer {
-    get type() { return 'canvas'; }
-    get centerTextAnchor() { return 'center'; }
-
-    constructor(container, width, height) {
-        super(container, width, height);
-        this.canvas = document.createElement('canvas');
-        this.canvas.width = width;
-        this.canvas.height = height;
-        // Inline elements (the default for <canvas>) leave a few px of baseline
-        // whitespace below them inside a block container, making the
-        // container's scrollHeight exceed its clientHeight for every chart.
-        this.canvas.style.display = 'block';
-        this._shapes = [];
-        this.container.appendChild(this.canvas);
-        this.ctx = this.canvas.getContext('2d');
-    }
-
-    /** Resize the canvas. Setting a canvas's size clears it, so redraw after. */
-    resize(width, height) {
-        super.resize(width, height);
-        this.canvas.width = width;
-        this.canvas.height = height;
-    }
-
-    clear() {
-        this.ctx.clearRect(0, 0, this.width, this.height);
-        this._shapes = [];
-    }
-
-    // Always returns an isolated Path2D — used by hitTest() to test one
-    // shape's geometry at a time. Previously rect/circle called this.ctx.rect()/
-    // .arc() directly onto the canvas's own current path without resetting it
-    // first, so each hitTest() loop iteration kept accumulating geometry from
-    // every shape checked before it, corrupting hit results for anything but
-    // the very first shape tested (tooltips/clicks/hover on Canvas charts
-    // could resolve to the wrong shape).
-    _drawPath(shape) {
-        const p = new Path2D();
-        switch (shape.type) {
-            case 'rect':
-                p.rect(shape.x, shape.y, shape.width, shape.height);
-                return p;
-            case 'circle':
-                p.arc(shape.cx, shape.cy, shape.r, 0, 2 * Math.PI);
-                return p;
-            case 'path':
-                return new Path2D(shape.d);
-            default:
-                return p; // empty — no geometry to hit-test
-        }
-    }
-    _setShapeType={
-        rect:(shape)=>this.ctx.rect(shape.x, shape.y, shape.width, shape.height),
-        circle:(shape)=>this.ctx.arc(shape.cx, shape.cy, shape.r, 0, 2 * Math.PI),
-        path:(shape,fill,stroke)=>{
-            const p = new Path2D(shape.d);
-            if (fill && fill !== 'none') { this.ctx.fillStyle = fill; this.ctx.fill(p); }
-            if (stroke && stroke.color !== 'none') {
-                this.ctx.strokeStyle = stroke.color;
-                this.ctx.lineWidth = stroke.width || 1;
-                // Used by the gauge arcs' rounded end-caps ({cap: 'round'}).
-                this.ctx.lineCap = stroke.cap || 'butt';
-                this.ctx.stroke(p);
-            }
-        }
-    }
-    // Shared by text() (initial draw) and _draw()'s 'text' case (redraw on
-    // hover enter/leave) so rotation/alignment logic isn't duplicated.
-    _paintText(shape) {
-        const hoverStyle = shape._hoverStyle;
-        const fill = hoverStyle?.fill ?? shape.fill;
-        this.ctx.fillStyle = fill || 'black';
-        this.ctx.font = `${shape.fontStyle || ''} ${shape.fontWeight || ''} ${shape.fontSize || '12px'} ${shape.fontFamily || 'sans-serif'}`.trim().replace(/\s+/g, ' ');
-        let textAlign = shape.textAnchor || 'start';
-        if (textAlign === 'middle') textAlign = 'center';
-        this.ctx.textAlign = textAlign;
-        this.ctx.textBaseline = 'middle';
-        if (shape.rotation) {
-            this.ctx.save();
-            this.ctx.translate(shape.x, shape.y);
-            this.ctx.rotate(shape.rotation);
-            this.ctx.fillText(shape.text, 0, 0);
-            this.ctx.restore();
-        } else {
-            this.ctx.fillText(shape.text, shape.x, shape.y);
-        }
-    }
-    _draw(shape) {
-        if (shape.type === 'text') { this._paintText(shape); return; }
-
-        const hoverStyle = shape._hoverStyle;
-        const fill = hoverStyle?.fill ?? shape.fill;
-        const stroke = hoverStyle?.stroke ?? shape.stroke;
-
-        // For path, we need to handle fill and stroke separately inside the case.
-        const isPath = shape.type === 'path';
-
-        this.ctx.beginPath();
-        this._setShapeType[shape.type](shape, fill, stroke);
-        if (isPath) return
-        if (fill && fill !== 'none') {
-            this.ctx.fillStyle = fill;
-            this.ctx.fill();
-        }
-        if (stroke) {
-            this.ctx.strokeStyle = stroke.color || 'none';
-            this.ctx.lineWidth = stroke.width || 1;
-            this.ctx.stroke();
-        }
-    }
-
-    _redraw() {
-        this.ctx.clearRect(0, 0, this.width, this.height);
-        this._shapes.forEach(shape => this._draw(shape));
-    }
-
-    rect(x, y, width, height, fill, stroke, extra = {}) {
-        const shape = { type: 'rect', x, y, width, height, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
-        this._shapes.push(shape);
-        this._draw(shape);
-    }
-
-    circle(cx, cy, r, fill, stroke, extra = {}) {
-        const shape = { type: 'circle', cx, cy, r, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
-        this._shapes.push(shape);
-        this._draw(shape);
-    }
-
-    path(d, fill, stroke, extra = {}) {
-        const shape = { type: 'path', d, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
-        this._shapes.push(shape);
-        this._draw(shape);
-    }
-
-    /** Text width measured by this renderer's own 2D context. */
-    measureText(text, font = {}) {
-        if (!this.ctx?.measureText) return super.measureText(text, font);
-        this.ctx.save();
-        this.ctx.font = BaseRenderer.cssFont(font);
-        const width = this.ctx.measureText(String(text)).width;
-        this.ctx.restore();
-        return width;
-    }
-
-    text(text, x, y, options = {}) {
-        const shape = { type: 'text', text, x, y, ...options, id: `shape_${this._shapes.length}` };
-        this._shapes.push(shape);
-        this._paintText(shape);
-    }
-
-    hitTest(x, y) {
-        for (let i = this._shapes.length - 1; i >= 0; i--) {
-            const shape = this._shapes[i];
-            const path2d = this._drawPath(shape);
-
-            // 1. Check for a fill hit first.
-            if (shape.fill && shape.fill !== 'none') {
-                if (path2d ? this.ctx.isPointInPath(path2d, x, y) : this.ctx.isPointInPath(x, y)) {
-                    return shape;
-                }
-            }
-
-            // 2. If no fill hit, check for a stroke hit.
-            if (shape.stroke && shape.stroke.color !== 'none') {
-                this.ctx.lineWidth = shape.stroke.width || 1;
-                if (path2d ? this.ctx.isPointInStroke(path2d, x, y) : this.ctx.isPointInStroke(x, y)) {
-                    return shape;
-                }
-            }
-        }
-        return null;
-    }
-
-    enterState(shape, stateName) {
-        const targetShape = this._shapes.find(s => s.id === shape.id);
-        if (targetShape) {
-            targetShape._hoverStyle = { fill: 'orange', stroke: { color: '#333', width: 2 } };
-            this._redraw();
-        }
-    }
-
-    leaveState(shape, stateName) {
-        const targetShape = this._shapes.find(s => s.id === shape.id);
-        if (targetShape) {
-            delete targetShape._hoverStyle;
-            this._redraw();
-        }
-    }
-
-    renderDiagram(diagram) {
-        // Draw the diagram directly onto the canvas context.
-        diagram.drawOn(this.ctx);
-    }
+import { BaseRenderer } from './BaseRenderer.js';
+
+/**
+ * @class CanvasRenderer
+ * Renders shapes by drawing on a 2D canvas context.
+ */
+export class CanvasRenderer extends BaseRenderer {
+    get type() { return 'canvas'; }
+    get centerTextAnchor() { return 'center'; }
+
+    constructor(container, width, height) {
+        super(container, width, height);
+        const doc = typeof document !== 'undefined' ? document : container?.ownerDocument;
+        this.canvas = doc?.createElement ? doc.createElement('canvas') : (container?.canvas || {
+            style: {}, width, height,
+            getContext: () => ({ fillRect: () => {}, measureText: () => ({ width: 10 }), clearRect: () => {}, beginPath: () => {}, arc: () => {}, fill: () => {}, stroke: () => {} }),
+        });
+        this.canvas.width = width;
+        this.canvas.height = height;
+        // Inline elements (the default for <canvas>) leave a few px of baseline
+        // whitespace below them inside a block container, making the
+        // container's scrollHeight exceed its clientHeight for every chart.
+        if (this.canvas?.style) this.canvas.style.display = 'block';
+        this._shapes = [];
+        this.container?.appendChild?.(this.canvas);
+        this.ctx = this.canvas?.getContext?.('2d') || null;
+    }
+
+    /** Resize the canvas. Setting a canvas's size clears it, so redraw after. */
+    resize(width, height) {
+        super.resize(width, height);
+        this.canvas.width = width;
+        this.canvas.height = height;
+    }
+
+    clear() {
+        this.ctx.clearRect(0, 0, this.width, this.height);
+        this._shapes = [];
+    }
+
+    // Always returns an isolated Path2D — used by hitTest() to test one
+    // shape's geometry at a time. Previously rect/circle called this.ctx.rect()/
+    // .arc() directly onto the canvas's own current path without resetting it
+    // first, so each hitTest() loop iteration kept accumulating geometry from
+    // every shape checked before it, corrupting hit results for anything but
+    // the very first shape tested (tooltips/clicks/hover on Canvas charts
+    // could resolve to the wrong shape).
+    _drawPath(shape) {
+        const p = new Path2D();
+        switch (shape.type) {
+            case 'rect':
+                p.rect(shape.x, shape.y, shape.width, shape.height);
+                return p;
+            case 'circle':
+                p.arc(shape.cx, shape.cy, shape.r, 0, 2 * Math.PI);
+                return p;
+            case 'path':
+                return new Path2D(shape.d);
+            default:
+                return p; // empty — no geometry to hit-test
+        }
+    }
+    _setShapeType={
+        rect:(shape)=>this.ctx.rect(shape.x, shape.y, shape.width, shape.height),
+        circle:(shape)=>this.ctx.arc(shape.cx, shape.cy, shape.r, 0, 2 * Math.PI),
+        path:(shape,fill,stroke)=>{
+            const p = new Path2D(shape.d);
+            if (fill && fill !== 'none') { this.ctx.fillStyle = fill; this.ctx.fill(p); }
+            if (stroke && stroke.color !== 'none') {
+                this.ctx.strokeStyle = stroke.color;
+                this.ctx.lineWidth = stroke.width || 1;
+                // Used by the gauge arcs' rounded end-caps ({cap: 'round'}).
+                this.ctx.lineCap = stroke.cap || 'butt';
+                this.ctx.stroke(p);
+            }
+        }
+    }
+    // Shared by text() (initial draw) and _draw()'s 'text' case (redraw on
+    // hover enter/leave) so rotation/alignment logic isn't duplicated.
+    _paintText(shape) {
+        const hoverStyle = shape._hoverStyle;
+        const fill = hoverStyle?.fill ?? shape.fill;
+        this.ctx.fillStyle = fill || 'black';
+        this.ctx.font = `${shape.fontStyle || ''} ${shape.fontWeight || ''} ${shape.fontSize || '12px'} ${shape.fontFamily || 'sans-serif'}`.trim().replace(/\s+/g, ' ');
+        let textAlign = shape.textAnchor || 'start';
+        if (textAlign === 'middle') textAlign = 'center';
+        this.ctx.textAlign = textAlign;
+        this.ctx.textBaseline = 'middle';
+        if (shape.rotation) {
+            this.ctx.save();
+            this.ctx.translate(shape.x, shape.y);
+            this.ctx.rotate(shape.rotation);
+            this.ctx.fillText(shape.text, 0, 0);
+            this.ctx.restore();
+        } else {
+            this.ctx.fillText(shape.text, shape.x, shape.y);
+        }
+    }
+    _draw(shape) {
+        if (shape.type === 'text') { this._paintText(shape); return; }
+
+        const hoverStyle = shape._hoverStyle;
+        const fill = hoverStyle?.fill ?? shape.fill;
+        const stroke = hoverStyle?.stroke ?? shape.stroke;
+
+        // For path, we need to handle fill and stroke separately inside the case.
+        const isPath = shape.type === 'path';
+
+        this.ctx.beginPath();
+        this._setShapeType[shape.type](shape, fill, stroke);
+        if (isPath) return
+        if (fill && fill !== 'none') {
+            this.ctx.fillStyle = fill;
+            this.ctx.fill();
+        }
+        if (stroke) {
+            this.ctx.strokeStyle = stroke.color || 'none';
+            this.ctx.lineWidth = stroke.width || 1;
+            this.ctx.stroke();
+        }
+    }
+
+    _redraw() {
+        this.ctx.clearRect(0, 0, this.width, this.height);
+        this._shapes.forEach(shape => this._draw(shape));
+    }
+
+    rect(x, y, width, height, fill, stroke, extra = {}) {
+        const shape = { type: 'rect', x, y, width, height, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
+        this._shapes.push(shape);
+        this._draw(shape);
+        return shape;
+    }
+
+    circle(cx, cy, r, fill, stroke, extra = {}) {
+        const shape = { type: 'circle', cx, cy, r, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
+        this._shapes.push(shape);
+        this._draw(shape);
+        return shape;
+    }
+
+    path(d, fill, stroke, extra = {}) {
+        const shape = { type: 'path', d, fill, stroke, id: `shape_${this._shapes.length}`, ...extra };
+        this._shapes.push(shape);
+        this._draw(shape);
+        return shape;
+    }
+
+    /** Text width measured by this renderer's own 2D context. */
+    measureText(text, font = {}) {
+        if (!this.ctx?.measureText) return super.measureText(text, font);
+        this.ctx.save();
+        this.ctx.font = BaseRenderer.cssFont(font);
+        const width = this.ctx.measureText(String(text)).width;
+        this.ctx.restore();
+        return width;
+    }
+
+    text(text, x, y, options = {}) {
+        const shape = { type: 'text', text, x, y, ...options, id: `shape_${this._shapes.length}` };
+        this._shapes.push(shape);
+        this._paintText(shape);
+        return shape;
+    }
+
+    hitTest(x, y) {
+        for (let i = this._shapes.length - 1; i >= 0; i--) {
+            const shape = this._shapes[i];
+            const path2d = this._drawPath(shape);
+
+            // 1. Check for a fill hit first.
+            if (shape.fill && shape.fill !== 'none') {
+                if (path2d ? this.ctx.isPointInPath(path2d, x, y) : this.ctx.isPointInPath(x, y)) {
+                    return shape;
+                }
+            }
+
+            // 2. If no fill hit, check for a stroke hit.
+            if (shape.stroke && shape.stroke.color !== 'none') {
+                this.ctx.lineWidth = shape.stroke.width || 1;
+                if (path2d ? this.ctx.isPointInStroke(path2d, x, y) : this.ctx.isPointInStroke(x, y)) {
+                    return shape;
+                }
+            }
+        }
+        return null;
+    }
+
+    enterState(shape, stateName) {
+        const targetShape = this._shapes.find(s => s.id === shape.id);
+        if (targetShape) {
+            targetShape._hoverStyle = { fill: 'orange', stroke: { color: '#333', width: 2 } };
+            this._redraw();
+        }
+    }
+
+    leaveState(shape, stateName) {
+        const targetShape = this._shapes.find(s => s.id === shape.id);
+        if (targetShape) {
+            delete targetShape._hoverStyle;
+            this._redraw();
+        }
+    }
+
+    renderDiagram(diagram) {
+        // Draw the diagram directly onto the canvas context.
+        diagram.drawOn(this.ctx);
+    }
+
+    /**
+     * Create a linear gradient on this canvas context.
+     * @param {string} _id
+     * @param {Array<{offset: string|number, color: string}>} stops
+     * @param {{x0?: number, y0?: number, x1?: number, y1?: number}} [coords]
+     * @returns {CanvasGradient|null}
+     */
+    linearGradient(_id, stops = [], { x0 = 0, y0 = 0, x1 = 0, y1 = 100 } = {}) {
+        if (!this.ctx?.createLinearGradient) return null;
+        const grad = this.ctx.createLinearGradient(x0, y0, x1, y1);
+        for (const stop of stops) {
+            const offset = typeof stop.offset === 'number' ? stop.offset : (parseFloat(stop.offset) || 0) / 100;
+            grad.addColorStop(offset, stop.color);
+        }
+        return grad;
+    }
 }