@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/ui/DraggableAspect.d.ts

@@ -1,4 +1,13 @@
 /**
+ * Turns an element into a drag gesture source.
+ *
+ * All positions reported to the callbacks are relative to the top-left corner of `el`, with the
+ * corner sampled once when the drag gesture begins. Freezing the frame for the duration of the
+ * gesture keeps positions stable even when `el` itself is being moved as part of the drag
+ * (e.g. dragging an element by itself), and makes `position - origin` a pure cursor displacement.
+ *
+ * Consumers that need positions in the frame of a different element can use the `event` argument
+ * together with {@link readPositionFromMouseEvent}.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -7,9 +16,9 @@ export class DraggableAspect {
     /**
      *
      * @param {EventTarget} el
-     * @param {function} [dragStart=noop]
-     * @param {(position:Vector2,origin:Vector2)=>*} [drag=noop]
-     * @param {function} [dragEnd=noop]
+     * @param {(position:Vector2, event:Event)=>*} [dragStart=noop]
+     * @param {(position:Vector2, origin:Vector2, delta:Vector2, event:Event)=>*} [drag=noop]
+     * @param {(position:Vector2, origin:Vector2, event:Event)=>*} [dragEnd=noop]
      * @param {boolean} [stopPropagation=true] prevent propagation of pointer events up the DOM tree
      */
     constructor({ el, dragStart, drag, dragEnd, stopPropagation }: EventTarget);

package/src/engine/ui/DraggableAspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DraggableAspect.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/DraggableAspect.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;;;;;OAOG;IACH,+DANW,WAAW,EAoDrB;IA7CG;;;;;OAKG;IACH,8BAAyC;IAQnB,+BAA8C;IAiCxE;;;OAGG;IACH,cAFa,aAAa,CAIzB;IAED,cAEC;IAED,aAGC;CACJ;8BAhF6B,mCAAmC"}
+{"version":3,"file":"DraggableAspect.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/DraggableAspect.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IACI;;;;;;;OAOG;IACH,+DANW,WAAW,EA2ErB;IApEG;;;;;OAKG;IACH,8BAAyC;IAQnB,+BAA8C;IAwDxE;;;OAGG;IACH,cAFa,aAAa,CAIzB;IAED,cAEC;IAED,aAGC;CACJ;8BAhHyD,mCAAmC"}

package/src/engine/ui/DraggableAspect.js

@@ -1,83 +1,115 @@
-import { noop } from "../../core/function/noop.js";
-import Vector2 from "../../core/geom/Vector2.js";
-import { PointerDevice } from "../input/devices/PointerDevice.js";
-
-/**
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class DraggableAspect {
-    /**
-     *
-     * @param {EventTarget} el
-     * @param {function} [dragStart=noop]
-     * @param {(position:Vector2,origin:Vector2)=>*} [drag=noop]
-     * @param {function} [dragEnd=noop]
-     * @param {boolean} [stopPropagation=true] prevent propagation of pointer events up the DOM tree
-     */
-    constructor({ el, dragStart = noop, drag = noop, dragEnd = noop, stopPropagation = true }) {
-        /**
-         *
-         * @type {PointerDevice}
-         * @readonly
-         * @private
-         */
-        this.pointerLocal = new PointerDevice(el);
-
-        /**
-         *
-         * @type {PointerDevice}
-         * @readonly
-         * @private
-         */
-        const pointerGlobal = this.pointerGlobal = new PointerDevice(window);
-
-        const dragOriginalPosition = new Vector2();
-        const pointer_position_last = new Vector2();
-
-        if (stopPropagation) {
-            this.pointerLocal.on.down.add((p, e) => {
-                e.stopPropagation();
-            });
-        }
-
-        this.pointerLocal.on.dragStart.add((position) => {
-            dragOriginalPosition.copy(position);
-            pointer_position_last.copy(position);
-            pointerGlobal.start();
-
-            dragStart(position);
-
-            function stopDrag(position) {
-                pointerGlobal.on.up.remove(stopDrag);
-                pointerGlobal.stop();
-
-                dragEnd(position, dragOriginalPosition);
-            }
-
-            pointerGlobal.on.up.add(stopDrag);
-        });
-
-        this.pointerGlobal.on.move.add((position, event, delta) => {
-            drag(position, dragOriginalPosition, delta);
-        });
-    }
-
-    /**
-     *
-     * @returns {PointerDevice}
-     */
-    getPointer() {
-        return this.pointerLocal;
-    }
-
-    start() {
-        this.pointerLocal.start();
-    }
-
-    stop() {
-        this.pointerLocal.stop();
-        this.pointerGlobal.stop();
-    }
-}
+import { noop } from "../../core/function/noop.js";
+import Vector2 from "../../core/geom/Vector2.js";
+import { PointerDevice, readPositionFromMouseEvent } from "../input/devices/PointerDevice.js";
+
+/**
+ * Turns an element into a drag gesture source.
+ *
+ * All positions reported to the callbacks are relative to the top-left corner of `el`, with the
+ * corner sampled once when the drag gesture begins. Freezing the frame for the duration of the
+ * gesture keeps positions stable even when `el` itself is being moved as part of the drag
+ * (e.g. dragging an element by itself), and makes `position - origin` a pure cursor displacement.
+ *
+ * Consumers that need positions in the frame of a different element can use the `event` argument
+ * together with {@link readPositionFromMouseEvent}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class DraggableAspect {
+    /**
+     *
+     * @param {EventTarget} el
+     * @param {(position:Vector2, event:Event)=>*} [dragStart=noop]
+     * @param {(position:Vector2, origin:Vector2, delta:Vector2, event:Event)=>*} [drag=noop]
+     * @param {(position:Vector2, origin:Vector2, event:Event)=>*} [dragEnd=noop]
+     * @param {boolean} [stopPropagation=true] prevent propagation of pointer events up the DOM tree
+     */
+    constructor({ el, dragStart = noop, drag = noop, dragEnd = noop, stopPropagation = true }) {
+        /**
+         *
+         * @type {PointerDevice}
+         * @readonly
+         * @private
+         */
+        this.pointerLocal = new PointerDevice(el);
+
+        /**
+         *
+         * @type {PointerDevice}
+         * @readonly
+         * @private
+         */
+        const pointerGlobal = this.pointerGlobal = new PointerDevice(window);
+
+        const dragOriginalPosition = new Vector2();
+        const position = new Vector2();
+
+        // top-left corner of `el` in client space, sampled when a drag gesture begins
+        const frameOrigin = new Vector2();
+
+        if (stopPropagation) {
+            this.pointerLocal.on.down.add((p, e) => {
+                e.stopPropagation();
+            });
+        }
+
+        this.pointerLocal.on.dragStart.add((p, event) => {
+            // freeze the coordinate frame of `el` for the duration of the gesture
+            if (typeof el.getBoundingClientRect === "function") {
+                const rect = el.getBoundingClientRect();
+
+                frameOrigin.set(rect.left, rect.top);
+            } else {
+                // some targets (window, document) expose no bounds, client frame is used as-is
+                frameOrigin.set(0, 0);
+            }
+
+            dragOriginalPosition.copy(p);
+            pointerGlobal.start();
+
+            dragStart(p, event);
+
+            function stopDrag(endClientPosition, endEvent) {
+                pointerGlobal.on.up.remove(stopDrag);
+                pointerGlobal.stop();
+
+                position.set(
+                    endClientPosition.x - frameOrigin.x,
+                    endClientPosition.y - frameOrigin.y
+                );
+
+                dragEnd(position, dragOriginalPosition, endEvent);
+            }
+
+            pointerGlobal.on.up.add(stopDrag);
+        });
+
+        this.pointerGlobal.on.move.add((clientPosition, event, delta) => {
+            // the global device reports client coordinates, convert into the frozen frame of `el`
+            position.set(
+                clientPosition.x - frameOrigin.x,
+                clientPosition.y - frameOrigin.y
+            );
+
+            drag(position, dragOriginalPosition, delta, event);
+        });
+    }
+
+    /**
+     *
+     * @returns {PointerDevice}
+     */
+    getPointer() {
+        return this.pointerLocal;
+    }
+
+    start() {
+        this.pointerLocal.start();
+    }
+
+    stop() {
+        this.pointerLocal.stop();
+        this.pointerGlobal.stop();
+    }
+}

package/src/generation/COORDINATES.md

@@ -0,0 +1,54 @@
+# Grid ↔ sampler coordinate conventions
+
+Established by review-01 §3. One convention for grid-attached layers, one
+explicitly separate domain for the terrain heightmap.
+
+## Grid space
+
+- Grid coordinates are continuous; **integer coordinates are cell centers**.
+- World mapping: `GridData.transform` (`OffsetScaleTransform2D`) maps grid
+  `(x, y)` to world `(x·scale + offset, y·scale + offset)`; `computeScale`
+  places cell centers at tile centers (offset = tileSize/2).
+
+## GridDataLayer texels (the canonical mapping)
+
+A `GridDataLayer` with `resolution = r` over a `w × h` grid has a `w·r × h·r`
+sampler. The mapping is the **plain ratio**, defined in
+`grid/coords/grid_to_texel.js` / `texel_to_grid.js`:
+
+```
+texel = grid · r        grid = texel / r
+```
+
+Integer texel coordinates are texel centers (this is what
+`Sampler2D.sampleChannelBilinear` expects), so for `r = 1` the mapping is the
+identity and texel t coincides with cell t. For `r > 1`, texel `t` is centered
+at grid `t / r`; cell centers land exactly on every r-th texel.
+
+Do **not** use corner-aligned mappings (`x / (w−1) · (sw−1)`) for layers — they
+disagree with the ratio mapping by up to one cell at the far edge and divide by
+zero on 1-wide grids.
+
+## Out-of-bounds policy
+
+- **Reads** (sampling filters): clamp — `Sampler2D` bilinear/bicubic clamp
+  internally; sampling off-map returns the edge value.
+- **Matches** (`CellMatcher` over a layer): out-of-bounds **fails the match**.
+  A pattern probe that falls off the map matches nothing, it does not match
+  against border cells.
+- **Writes** (cell actions): out-of-bounds writes are **discarded** after an
+  explicit bounds check (never index-arithmetic into a flat array — negative
+  x wraps into the previous row).
+
+## Terrain heightmap and splat — separate domains
+
+- The terrain **heightmap** (`Terrain.samplerHeight`) is the terrain renderer's
+  vertex-aligned domain. `ContinuousGridCellActionSetTerrainHeight` maps grid
+  corners to sampler corners (`x/(w−1) · (sw−1)`) to match the terrain mesh —
+  this is intentional and must stay consistent with the terrain renderer, not
+  with grid layers.
+- The terrain **splat map** is coverage data and uses the ratio mapping
+  (`splat_texel = grid · splatRes/gridRes`), see `MarkerNodeActionPaintTerrain`.
+- Resampling between two samplers of different resolutions (e.g.
+  `ThemeEngine.tResample`) uses texel-center mapping:
+  `source = (target + 0.5) · ratio − 0.5`.

package/src/generation/GridTaskGroup.js

@@ -75,7 +75,7 @@ export class GridTaskGroup extends GridTaskGenerator {
                 const dependencyIndex = generators.indexOf(dependency);
 
                 if (dependencyIndex === -1) {
-                    throw new Error(`Dependency ${j}(name='${dependency.name}') of task generator [${i}] (name='${generator.name}') is not found`);
+                    throw new Error(`Dependency ${j} (name='${dependency.name}') of task generator [${i}] (name='${generator.name}') is not a direct child of this group. Generator dependencies can only reference siblings within the same GridTaskGroup; use GridTaskSequence or restructure the groups for cross-group ordering.`);
                 }
 
                 const dependencyTask = tasks[dependencyIndex];
@@ -101,7 +101,7 @@ export class GridTaskGroup extends GridTaskGenerator {
 function catchGeneratorErrors(generator, task) {
 
     task.promise().catch(reason => {
-        console.error(`Generator '${generator.name}' failed. Task status: ${task.getVerboseStatusMessage()}`);
+        console.error(`Generator '${generator.name}' failed:`, reason, `Task status: ${task.getVerboseStatusMessage()}`);
     });
 
 }