@woosh/meep-engine 2.156.0 → 2.157.0

package/README.md

@@ -82,9 +82,7 @@ export default defineConfig({
 ```
 
 ### Reliability
-* **Tests:** 3,159 handwritten tests covering critical algorithms and complex edge cases.
-
-* **Coverage:** 90%+ core coverage.
+* **Tests:** 7,244 tests with 90%+ core coverage.
 
 * **Stability:** Exhaustively tested corner cases over a decade of development.
 

package/editor/view/ecs/components/common/AutoCanvasView.js

@@ -1,53 +1,100 @@
-import { DomSizeObserver } from "../../../../../src/view/util/DomSizeObserver.js";
-import { CanvasView } from "../../../../../src/view/elements/CanvasView.js";
-
-/**
- * Automatically tracks size on the screen, including that computed from CSS and - re-renders content when size changes
- * @extends View
- */
-export class AutoCanvasView extends CanvasView {
-    constructor({ classList = [] } = {}) {
-        super();
-
-        this.addClasses(classList);
-
-        const sizeObserver = new DomSizeObserver();
-        this.__sizeObserver = sizeObserver;
-
-        const size = sizeObserver.dimensions.size;
-
-        // subscribe to visual dimension changes
-        size.onChanged.add(this.render, this);
-
-        sizeObserver.watchView(this);
-        this.on.linked.add(this.render,this);
-    }
-
-    render() {
-        const dimensions = this.__sizeObserver.dimensions;
-        const size = dimensions.size;
-
-        const width = size.x;
-        const height = size.y;
-
-        if (width <= 0 || height <= 0) {
-            //canvas too small
-            return;
-        }
-
-        // resize canvas as necessary
-        this.size.set(width, height);
-
-        this.draw(this.context2d, width, height);
-    }
-
-    /**
-     *
-     * @param {CanvasRenderingContext2D} ctx
-     * @param {number} width
-     * @param {number} height
-     */
-    draw(ctx, width, height) {
-        //override this method
-    }
-}
+import { DomSizeObserver } from "../../../../../src/view/util/DomSizeObserver.js";
+import { CanvasView } from "../../../../../src/view/elements/CanvasView.js";
+
+/**
+ * Automatically tracks size on the screen, including that computed from CSS and - re-renders content when size changes.
+ * The backing bitmap is kept at native resolution (CSS size x devicePixelRatio) while {@link #draw}
+ * keeps working in CSS pixel coordinates.
+ * @extends View
+ */
+export class AutoCanvasView extends CanvasView {
+
+    /**
+     * Guards against re-entry when {@link #__renderAt} writes this.size, which signals back into rendering
+     * @type {boolean}
+     */
+    #rendering = false;
+
+    constructor({ classList = [] } = {}) {
+        super();
+
+        this.addClasses(classList);
+
+        const sizeObserver = new DomSizeObserver();
+        this.__sizeObserver = sizeObserver;
+
+        const size = sizeObserver.dimensions.size;
+
+        // subscribe to visual dimension changes
+        size.onChanged.add(this.render, this);
+
+        sizeObserver.watchView(this);
+        this.on.linked.add(this.render, this);
+
+        // repaint immediately when sized programmatically; writing the canvas size attribute
+        // clears the bitmap, waiting for the resize observer tick would show a blank frame
+        this.size.onChanged.add(this.__renderAt, this);
+    }
+
+    render() {
+        const dimensions = this.__sizeObserver.dimensions;
+        const size = dimensions.size;
+
+        this.__renderAt(size.x, size.y);
+    }
+
+    /**
+     *
+     * @param {number} width CSS pixels
+     * @param {number} height CSS pixels
+     * @private
+     */
+    __renderAt(width, height) {
+        if (this.#rendering) {
+            // nested invocation via this.size signal, the outer call completes the work
+            return;
+        }
+
+        if (width <= 0 || height <= 0) {
+            //canvas too small
+            return;
+        }
+
+        this.#rendering = true;
+
+        try {
+            // resize canvas as necessary
+            this.size.set(width, height);
+
+            const canvas = this.el;
+            const ctx = this.context2d;
+
+            // bitmap at native resolution, draw code stays in CSS pixels via the transform
+            const dpr = (typeof devicePixelRatio === "number" && devicePixelRatio > 0) ? devicePixelRatio : 1;
+
+            const bitmap_width = Math.round(width * dpr);
+            const bitmap_height = Math.round(height * dpr);
+
+            if (canvas.width !== bitmap_width || canvas.height !== bitmap_height) {
+                canvas.width = bitmap_width;
+                canvas.height = bitmap_height;
+            }
+
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+            this.draw(ctx, width, height);
+        } finally {
+            this.#rendering = false;
+        }
+    }
+
+    /**
+     *
+     * @param {CanvasRenderingContext2D} ctx
+     * @param {number} width
+     * @param {number} height
+     */
+    draw(ctx, width, height) {
+        //override this method
+    }
+}

package/editor/view/ecs/components/common/TextController.js

@@ -0,0 +1,59 @@
+import ObservedString from "../../../../../src/core/model/ObservedString.js";
+import View from "../../../../../src/view/View.js";
+
+/**
+ * Single-line text input bound to an {@link ObservedString} value.
+ * Counterpart of {@link NumberController} for string values.
+ */
+export class TextController extends View {
+    /**
+     *
+     * @param {string[]} [classList]
+     * @param {string} [value]
+     */
+    constructor({ classList = [], value = "" } = {}) {
+        super();
+
+        const _value = new ObservedString(value);
+
+        /**
+         *
+         * @type {ObservedString}
+         */
+        this.value = _value;
+
+        const el = document.createElement('input');
+        this.el = el;
+
+        this.addClasses(classList);
+
+        el.setAttribute('type', 'text');
+        el.setAttribute('spellcheck', false);
+        el.setAttribute('size', 2);
+
+        el.classList.add('ui-text-controller');
+
+        let lockForward = false;
+
+        function data2view() {
+
+            if (lockForward) {
+                return;
+            }
+
+            el.value = _value.getValue();
+        }
+
+        function view2data() {
+            lockForward = true;
+
+            _value.set(el.value);
+
+            lockForward = false;
+        }
+
+        _value.process(data2view);
+
+        el.addEventListener('input', view2data);
+    }
+}

package/editor/view/node-graph/NodeGraphCamera.js

@@ -0,0 +1,90 @@
+import Vector1 from "../../../src/core/geom/Vector1.js";
+import Vector2 from "../../../src/core/geom/Vector2.js";
+import { clamp } from "../../../src/core/math/clamp.js";
+
+/**
+ * Smallest permitted zoom level of a node graph viewport
+ * @type {number}
+ */
+export const NODE_GRAPH_SCALE_MIN = 0.03;
+
+/**
+ * Largest permitted zoom level of a node graph viewport
+ * @type {number}
+ */
+export const NODE_GRAPH_SCALE_MAX = 4;
+
+/**
+ * Viewport of a node graph editor.
+ * Canvas space is measured in pixels from the top-left corner of the viewport,
+ * graph space is the coordinate space node positions live in.
+ */
+export class NodeGraphCamera {
+    constructor() {
+        /**
+         * Graph-space position of the top-left corner of the viewport
+         * @type {Vector2}
+         */
+        this.position = new Vector2();
+
+        /**
+         *
+         * @type {Vector1}
+         */
+        this.scale = new Vector1(1);
+    }
+
+    /**
+     * Convert point from Graph coordinate space to Canvas coordinate space
+     * @param {Vector2} input
+     * @param {Vector2} output
+     */
+    graphToCanvas(input, output) {
+        const scale = this.scale.getValue();
+        const p = this.position;
+
+        output.set(
+            (input.x - p.x) * scale,
+            (input.y - p.y) * scale
+        );
+    }
+
+    /**
+     * Convert point from Canvas coordinate space to Graph coordinate space
+     * @param {Vector2} input
+     * @param {Vector2} output
+     */
+    canvasToGraph(input, output) {
+        const scale = this.scale.getValue();
+        const p = this.position;
+
+        output.set(
+            (input.x / scale) + p.x,
+            (input.y / scale) + p.y
+        );
+    }
+
+    /**
+     * Change zoom level, keeping the graph point under a canvas-space anchor stationary
+     * @param {Vector2} anchor canvas-space point to zoom about, typically the cursor
+     * @param {number} scale target scale, clamped to [{@link NODE_GRAPH_SCALE_MIN}, {@link NODE_GRAPH_SCALE_MAX}]
+     */
+    zoomAt(anchor, scale) {
+        const oldScale = this.scale.getValue();
+        const newScale = clamp(scale, NODE_GRAPH_SCALE_MIN, NODE_GRAPH_SCALE_MAX);
+
+        if (newScale === oldScale) {
+            return;
+        }
+
+        /*
+         graph point under the anchor: g = anchor/scale + position
+         requiring g to remain stationary across the scale change:
+         position' = position + anchor*(1/oldScale - 1/newScale)
+         */
+        const k = 1 / oldScale - 1 / newScale;
+
+        this.scale.set(newScale);
+        this.position._add(anchor.x * k, anchor.y * k);
+    }
+}

package/editor/view/node-graph/NodeGraphEditorView.js

@@ -1,10 +1,19 @@
+import { clamp } from "../../../src/core/math/clamp.js";
 import { min2 } from "../../../src/core/math/min2.js";
+import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
+import KeyboardDevice from "../../../src/engine/input/devices/KeyboardDevice.js";
+import { KeyCodes } from "../../../src/engine/input/devices/KeyCodes.js";
 import View from "../../../src/view/View.js";
+import { NODE_GRAPH_SCALE_MAX, NODE_GRAPH_SCALE_MIN } from "./NodeGraphCamera.js";
 import { NodeGraphCamera, NodeGraphView } from "./NodeGraphView.js";
+import { NodeGraphSelection } from "./NodeGraphSelection.js";
+import { ConnectionDeleteAction } from "./actions/ConnectionDeleteAction.js";
+import { NodeDeleteAction } from "./actions/NodeDeleteAction.js";
+import { SelectionSetAction } from "./actions/SelectionSetAction.js";
 import {
     NodeDescriptionVisualRegistry
 } from "../../../src/core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
-import AABB2 from "../../../src/core/geom/AABB2.js";
+import AABB2 from "../../../src/core/geom/2d/aabb/AABB2.js";
 import ButtonView from "../../../src/view/elements/button/ButtonView.js";
 import EmptyView from "../../../src/view/elements/EmptyView.js";
 
@@ -16,10 +25,23 @@ export class NodeGraphEditorView extends View {
      * @param {NodeGraphVisualData} visual
      * @param {NodeGraphCamera} camera
      * @param {InterfaceCommand[]} [actions]
+     * @param {ActionProcessor} [actionProcessor] timeline that all graph edits are routed through, supply a shared one to integrate with a host editor's UNDO/REDO
      */
-    constructor({ graph, nodeRegistry, visual, camera, actions = [] }) {
+    constructor({ graph, nodeRegistry, visual, camera, actions = [], actionProcessor = new ActionProcessor({}) }) {
         super();
 
+        /**
+         *
+         * @type {ActionProcessor}
+         */
+        this.actionProcessor = actionProcessor;
+
+        /**
+         *
+         * @type {NodeGraphSelection}
+         */
+        this.selection = new NodeGraphSelection();
+
         /**
          *
          * @type {NodeGraphCamera}
@@ -47,17 +69,67 @@ export class NodeGraphEditorView extends View {
             visualRegistry.generate(node);
         });
 
+        /**
+         *
+         * @type {NodeDescriptionVisualRegistry}
+         */
+        this.visualRegistry = visualRegistry;
+
 
         const graphView = new NodeGraphView({
             graph: graph,
             visual: visual,
             camera,
-            nodeVisualRegistry: visualRegistry
+            nodeVisualRegistry: visualRegistry,
+            actionProcessor,
+            selection: this.selection
         });
 
         this.size.onChanged.add((x, y) => graphView.size.set(x, y));
         this.addChild(graphView);
 
+        // keyboard shortcuts, the element must be focusable to receive key events
+        this.el.setAttribute('tabindex', '-1');
+
+        const keyboard = new KeyboardDevice(this.el);
+
+        keyboard.on.down.add(event => {
+            const target = event.target;
+
+            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+                // typing into a parameter field, keystrokes belong to the input
+                return;
+            }
+
+            if (event.keyCode === KeyCodes.delete || event.keyCode === KeyCodes.backspace) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                this.deleteSelection();
+
+                return;
+            }
+
+            if (!event.ctrlKey) {
+                return;
+            }
+
+            if (event.keyCode === KeyCodes.z) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                actionProcessor.undo();
+            } else if (event.keyCode === KeyCodes.y) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                actionProcessor.redo();
+            }
+        });
+
+        this.on.linked.add(keyboard.start, keyboard);
+        this.on.unlinked.add(keyboard.stop, keyboard);
+
         const self = this;
 
 
@@ -92,16 +164,52 @@ export class NodeGraphEditorView extends View {
             vActionBar.addChild(b);
         });
 
-        // ensure point events are enabled
+        // ensure pointer events are enabled; suppress the focus ring of the keyboard-focusable element
         this.css({
-            pointerEvents: 'auto'
+            pointerEvents: 'auto',
+            outline: 'none'
         });
     }
 
     layout() {
+        this.visual.ensure(this.graph, this.visualRegistry);
         this.visual.layout(this.graph);
     }
 
+    /**
+     * Delete everything in the current selection as a single undoable group
+     */
+    deleteSelection() {
+        const selection = this.selection;
+
+        if (selection.isEmpty()) {
+            return;
+        }
+
+        const graph = this.graph;
+
+        const actions = [
+            // emptied selection is part of the group: undo restores graph content first, selection last
+            new SelectionSetAction(selection, [], [])
+        ];
+
+        // explicitly selected wires; wires attached to deleted nodes are captured by NodeDeleteAction
+        selection.connections.forEach(id => {
+            const connection = graph.getConnection(id);
+
+            if (connection !== undefined) {
+                actions.push(new ConnectionDeleteAction(graph, connection));
+            }
+        });
+
+        selection.nodes.forEach(id => {
+            actions.push(new NodeDeleteAction(graph, this.visual, id));
+        });
+
+        this.actionProcessor.mark('delete selection');
+        this.actionProcessor.doMany(actions);
+    }
+
     cameraContainAll() {
         /**
          *
@@ -145,26 +253,17 @@ export class NodeGraphEditorView extends View {
         const xScale = canvas_width / boundsWidth;
         const yScale = canvas_height / boundsHeight;
 
-        const scale = min2(
-            xScale,
-            yScale
+        const scale = clamp(
+            min2(xScale, yScale),
+            NODE_GRAPH_SCALE_MIN,
+            NODE_GRAPH_SCALE_MAX
         );
 
-        if (scale === 0) {
-            camera.position.set(bounds.x0, bounds.y0);
-
-            camera.scale.set(1);
-
-        } else {
-
-            const xOffset = (boundsWidth - (canvas_width / scale)) / 2;
-            const yOffset = (boundsHeight - (canvas_height / scale)) / 2;
-
-            camera.position.set(bounds.x0 + xOffset, bounds.y0 + yOffset);
-
-            camera.scale.set(scale);
-        }
+        const xOffset = (boundsWidth - (canvas_width / scale)) / 2;
+        const yOffset = (boundsHeight - (canvas_height / scale)) / 2;
 
+        camera.position.set(bounds.x0 + xOffset, bounds.y0 + yOffset);
 
+        camera.scale.set(scale);
     }
 }

package/editor/view/node-graph/NodeGraphSelection.js

@@ -0,0 +1,89 @@
+import List from "../../../src/core/collection/list/List.js";
+
+/**
+ * Selection state of a node graph editor.
+ * Stores IDs rather than object references so that history actions remain valid
+ * across delete/undo cycles, which restore equal objects under the same IDs.
+ */
+export class NodeGraphSelection {
+    /**
+     * IDs of selected nodes
+     * @readonly
+     * @type {List<number>}
+     */
+    nodes = new List();
+
+    /**
+     * IDs of selected connections
+     * @readonly
+     * @type {List<number>}
+     */
+    connections = new List();
+
+    /**
+     *
+     * @returns {boolean}
+     */
+    isEmpty() {
+        return this.nodes.isEmpty() && this.connections.isEmpty();
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    containsNode(id) {
+        return this.nodes.contains(id);
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    containsConnection(id) {
+        return this.connections.contains(id);
+    }
+
+    clear() {
+        this.nodes.reset();
+        this.connections.reset();
+    }
+
+    /**
+     *
+     * @param {NodeGraphSelection} other
+     */
+    copy(other) {
+        this.nodes.copy(other.nodes);
+        this.connections.copy(other.connections);
+    }
+
+    /**
+     *
+     * @returns {NodeGraphSelection}
+     */
+    clone() {
+        const r = new NodeGraphSelection();
+
+        r.copy(this);
+
+        return r;
+    }
+
+    /**
+     * Does the selection consist of exactly these elements? Order is ignored.
+     * @param {number[]} nodes node IDs
+     * @param {number[]} connections connection IDs
+     * @returns {boolean}
+     */
+    matches(nodes, connections) {
+        if (this.nodes.length !== nodes.length || this.connections.length !== connections.length) {
+            return false;
+        }
+
+        return nodes.every(id => this.nodes.contains(id))
+            && connections.every(id => this.connections.contains(id));
+    }
+}