@pascal-app/core 0.8.0 → 0.9.2

package/dist/services/alignment.js

@@ -0,0 +1,171 @@
+/**
+ * Pure alignment-guide resolver — no React, no DOM, no scene access.
+ *
+ * Given a moving object's anchor points at its proposed position and a
+ * pool of candidate anchors from nearby static objects, returns:
+ *   - the best per-axis matches as `Guide` rendering primitives, and
+ *   - an optional `{ dx, dz }` snap delta the caller can apply.
+ *
+ * Anchors are 2D points on the floor plane (XZ, in world meters). The
+ * resolver picks at most one match per axis: the smallest |Δx| match
+ * snaps X; the smallest |Δz| match snaps Z. This mirrors Figma's
+ * behaviour — guides appear along the matched axes, regardless of how
+ * many neighbours could have matched.
+ *
+ * Two guides max per call keeps the visual signal sharp at the cost of
+ * not surfacing every possible alignment at once. Multi-guide ("this
+ * lines up with three things") is intentionally out of scope for v1.
+ */
+const EMPTY = { guides: [], snap: null };
+/** Forward rotation: local XZ → world XZ for a node whose parent has
+ *  position `bx,_,bz` and rotation-Y `rotY` (radians). Matches the
+ *  transform used throughout the editor's tools / floor-plan. */
+function localToWorld(x, z, bx, bz, cos, sin) {
+    return {
+        x: bx + x * cos + z * sin,
+        z: bz - x * sin + z * cos,
+    };
+}
+function transformAnchorToWorld(anchor, bx, bz, cos, sin) {
+    const w = localToWorld(anchor.x, anchor.z, bx, bz, cos, sin);
+    return { nodeId: anchor.nodeId, kind: anchor.kind, x: w.x, z: w.z };
+}
+/**
+ * Resolve alignment in WORLD space while accepting BUILDING-LOCAL anchors.
+ *
+ * Why this exists: the floor-plan grid lives in world XZ (rendered outside
+ * the rotated scene group), so alignment must follow the same axes —
+ * otherwise rotating a building drags the alignment guides off the visible
+ * grid and onto the rotated wall's local axes (the bug the user hit). The
+ * resolver itself is frame-agnostic; this wrapper just transforms anchors
+ * to world, resolves, then rotates the snap delta back into building-local
+ * so callers can add it to a local position without further math.
+ *
+ * `pose === null` → resolve in the caller's frame as-is (no transform).
+ */
+export function resolveAlignmentInBuildingWorld(input) {
+    const { moving, candidates, threshold, pose } = input;
+    if (!pose) {
+        return resolveAlignment({ moving, candidates, threshold });
+    }
+    const cos = Math.cos(pose.rotationY);
+    const sin = Math.sin(pose.rotationY);
+    const bx = pose.position[0];
+    const bz = pose.position[2];
+    const movingWorld = moving.map((a) => transformAnchorToWorld(a, bx, bz, cos, sin));
+    const candidatesWorld = candidates.map((a) => transformAnchorToWorld(a, bx, bz, cos, sin));
+    const result = resolveAlignment({
+        moving: movingWorld,
+        candidates: candidatesWorld,
+        threshold,
+    });
+    if (!result.snap)
+        return { guides: result.guides, snap: null };
+    // World → local rotation (orthogonal matrix → transpose). The inverse of
+    // `localToWorld` above maps (dx_world, dz_world) → (dx_local, dz_local).
+    const dxW = result.snap.dx;
+    const dzW = result.snap.dz;
+    const dxL = dxW * cos - dzW * sin;
+    const dzL = dxW * sin + dzW * cos;
+    return { guides: result.guides, snap: { dx: dxL, dz: dzL } };
+}
+export function resolveAlignment(input) {
+    const { moving, candidates, threshold } = input;
+    if (threshold <= 0 || moving.length === 0 || candidates.length === 0)
+        return EMPTY;
+    let bestX = null;
+    let bestZ = null;
+    for (const m of moving) {
+        for (const c of candidates) {
+            const dx = c.x - m.x;
+            const dz = c.z - m.z;
+            const adx = Math.abs(dx);
+            const adz = Math.abs(dz);
+            if (adx <= threshold &&
+                (bestX === null || adz < bestX.perp || (adz === bestX.perp && adx < bestX.primary))) {
+                bestX = { delta: dx, primary: adx, perp: adz, m, c };
+            }
+            if (adz <= threshold &&
+                (bestZ === null || adx < bestZ.perp || (adx === bestZ.perp && adz < bestZ.primary))) {
+                bestZ = { delta: dz, primary: adz, perp: adx, m, c };
+            }
+        }
+    }
+    if (!bestX && !bestZ)
+        return EMPTY;
+    const dxSnap = bestX?.delta ?? 0;
+    const dzSnap = bestZ?.delta ?? 0;
+    const guides = [];
+    if (bestX) {
+        // X-axis match: vertical guide at x = bestX.c.x. The moving anchor
+        // ends up at (c.x, m.z + dzSnap). Span the line between them.
+        const snappedMz = bestX.m.z + dzSnap;
+        const z1 = Math.min(bestX.c.z, snappedMz);
+        const z2 = Math.max(bestX.c.z, snappedMz);
+        guides.push({
+            axis: 'x',
+            coord: bestX.c.x,
+            from: { x: bestX.c.x, z: z1 },
+            to: { x: bestX.c.x, z: z2 },
+            anchor: { x: bestX.c.x, z: bestX.c.z },
+            movingAnchorKind: bestX.m.kind,
+            candidateAnchorKind: bestX.c.kind,
+            candidateNodeId: bestX.c.nodeId,
+            distance: Math.abs(snappedMz - bestX.c.z),
+        });
+    }
+    if (bestZ) {
+        const snappedMx = bestZ.m.x + dxSnap;
+        const x1 = Math.min(bestZ.c.x, snappedMx);
+        const x2 = Math.max(bestZ.c.x, snappedMx);
+        guides.push({
+            axis: 'z',
+            coord: bestZ.c.z,
+            from: { x: x1, z: bestZ.c.z },
+            to: { x: x2, z: bestZ.c.z },
+            anchor: { x: bestZ.c.x, z: bestZ.c.z },
+            movingAnchorKind: bestZ.m.kind,
+            candidateAnchorKind: bestZ.c.kind,
+            candidateNodeId: bestZ.c.nodeId,
+            distance: Math.abs(snappedMx - bestZ.c.x),
+        });
+    }
+    return { guides, snap: { dx: dxSnap, dz: dzSnap } };
+}
+// ─── Anchor extractors (pure) ─────────────────────────────────────────
+/**
+ * Produces the 9 standard anchors for an axis-aligned bounding box on the
+ * floor plane: 4 corners, 4 edge midpoints, 1 center. Suitable for any
+ * floor-plan entity whose footprint can be expressed as a bbox.
+ *
+ * Caller is responsible for computing the bbox — the resolver doesn't
+ * care how (per-kind dimensions, SVG getBBox(), etc.).
+ */
+export function bboxAnchors(nodeId, minX, minZ, maxX, maxZ) {
+    const cx = (minX + maxX) / 2;
+    const cz = (minZ + maxZ) / 2;
+    return [
+        { nodeId, kind: 'corner', x: minX, z: minZ },
+        { nodeId, kind: 'corner', x: maxX, z: minZ },
+        { nodeId, kind: 'corner', x: maxX, z: maxZ },
+        { nodeId, kind: 'corner', x: minX, z: maxZ },
+        { nodeId, kind: 'edge-mid', x: cx, z: minZ },
+        { nodeId, kind: 'edge-mid', x: maxX, z: cz },
+        { nodeId, kind: 'edge-mid', x: cx, z: maxZ },
+        { nodeId, kind: 'edge-mid', x: minX, z: cz },
+        { nodeId, kind: 'center', x: cx, z: cz },
+    ];
+}
+/**
+ * The 4 corner anchors of a bbox — edges only, no edge-midpoints or center.
+ * Used where alignment should lock to an object's edges (left/right/front/
+ * back), never its centreline.
+ */
+export function bboxCornerAnchors(nodeId, minX, minZ, maxX, maxZ) {
+    return [
+        { nodeId, kind: 'corner', x: minX, z: minZ },
+        { nodeId, kind: 'corner', x: maxX, z: minZ },
+        { nodeId, kind: 'corner', x: maxX, z: maxZ },
+        { nodeId, kind: 'corner', x: minX, z: maxZ },
+    ];
+}

package/dist/services/alignment.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alignment.test.d.ts.map

package/dist/services/alignment.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.test.d.ts","sourceRoot":"","sources":["../../src/services/alignment.test.ts"],"names":[],"mappings":""}

package/dist/services/alignment.test.js

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+import { bboxAnchors, resolveAlignment } from './alignment';
+function center(nodeId, x, z) {
+    return { nodeId, kind: 'center', x, z };
+}
+function corner(nodeId, x, z) {
+    return { nodeId, kind: 'corner', x, z };
+}
+describe('resolveAlignment', () => {
+    test('returns empty when no candidates within threshold', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0, 0)],
+            candidates: [center('a', 1, 1)],
+            threshold: 0.5,
+        });
+        expect(result.guides).toEqual([]);
+        expect(result.snap).toBeNull();
+    });
+    test('snaps moving anchor onto candidate X when within threshold', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0.03, 5)],
+            candidates: [center('a', 0, 2)],
+            threshold: 0.1,
+        });
+        expect(result.snap).toEqual({ dx: -0.03, dz: 0 });
+        expect(result.guides).toHaveLength(1);
+        expect(result.guides[0].axis).toBe('x');
+        expect(result.guides[0].coord).toBe(0);
+        expect(result.guides[0].from.z).toBe(2);
+        expect(result.guides[0].to.z).toBe(5);
+    });
+    test('snaps both axes when both match', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0.03, 0.04)],
+            candidates: [center('a', 0, 0)],
+            threshold: 0.1,
+        });
+        expect(result.snap).toEqual({ dx: -0.03, dz: -0.04 });
+        expect(result.guides).toHaveLength(2);
+    });
+    test('picks closest candidate per axis', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0.08, 0)],
+            candidates: [center('a', 0, 5), center('b', 0.1, 5), center('c', 0.05, 10)],
+            threshold: 0.1,
+        });
+        // |0.1 - 0.08| = 0.02 wins over |0.05 - 0.08| = 0.03 and |0 - 0.08| = 0.08
+        expect(result.snap?.dx).toBeCloseTo(0.02, 10);
+        expect(result.guides[0].candidateNodeId).toBe('b');
+    });
+    test('ties on the matched axis break toward the nearest perpendicular anchor', () => {
+        const result = resolveAlignment({
+            moving: [corner('m', 0.02, 4)],
+            candidates: [corner('far', 0, 0), corner('near', 0, 5)],
+            threshold: 0.1,
+        });
+        // Both share X (Δx = 0.02); 'near' (z=5) is closer to the moving z=4 than
+        // 'far' (z=0), so the guide connects to the nearest real anchor.
+        expect(result.guides[0].candidateNodeId).toBe('near');
+    });
+    test('threshold = 0 disables alignment', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0, 0)],
+            candidates: [center('a', 0, 0)],
+            threshold: 0,
+        });
+        expect(result.guides).toEqual([]);
+        expect(result.snap).toBeNull();
+    });
+    test('distance is the perpendicular gap to the matched axis', () => {
+        const result = resolveAlignment({
+            moving: [center('m', 0.02, 3)],
+            candidates: [center('a', 0, 0)],
+            threshold: 0.1,
+        });
+        // After snap: moving at (0, 3). X guide runs along x=0 from z=0 to z=3.
+        expect(result.guides[0].distance).toBeCloseTo(3, 10);
+    });
+});
+describe('bboxAnchors', () => {
+    test('returns 9 anchors with correct kinds and positions', () => {
+        const anchors = bboxAnchors('node', 0, 0, 2, 4);
+        expect(anchors).toHaveLength(9);
+        const corners = anchors.filter((a) => a.kind === 'corner');
+        const edges = anchors.filter((a) => a.kind === 'edge-mid');
+        const centers = anchors.filter((a) => a.kind === 'center');
+        expect(corners).toHaveLength(4);
+        expect(edges).toHaveLength(4);
+        expect(centers).toHaveLength(1);
+        expect(centers[0]).toEqual({ nodeId: 'node', kind: 'center', x: 1, z: 2 });
+    });
+});

package/dist/services/drag-session.d.ts

@@ -0,0 +1,47 @@
+import { type ChildQuery, type SpatialQuery } from '../registry/relations-resolver';
+import type { DragAction, Modifiers, SceneApi } from '../registry/types';
+import type { AnyNode } from '../schema/types';
+import type { Vec2 } from './snap';
+/**
+ * Pure orchestrator for a single `DragAction` lifecycle:
+ *   begin → (preview → snap? → apply → cascade dirty)* → commit | cancel
+ *
+ * Bracketed by `pauseHistory()` / `resumeHistory()` so the entire drag is one
+ * undo step. The React hook (`useDragAction` in `@pascal-app/editor`) wraps
+ * this with event subscriptions; tests drive it directly.
+ */
+export type DragSessionInput = {
+    node?: AnyNode;
+    point: Vec2;
+    handleId?: string;
+    modifiers?: Modifiers;
+};
+export type DragSessionOptions = {
+    spatialQuery?: SpatialQuery;
+    childQuery?: ChildQuery;
+    /** Called once the session terminates via `commit()`. */
+    onCommit?: () => void;
+    /** Called once the session terminates via `cancel()` or `dispose()`. */
+    onCancel?: () => void;
+};
+export type DragSession<Ctx, Draft> = {
+    /** Begin the drag — pause history, capture ctx via `action.begin`. */
+    start: (input: DragSessionInput) => void;
+    /** Per-pointer-move tick — run preview/snap/apply and cascade dirty marks. */
+    move: (point: Vec2, modifiers: Modifiers) => void;
+    /** Pointer-up / discrete commit. Returns true if `action.commit` agreed. */
+    commit: () => boolean;
+    /** Pointer-cancel / Esc / external abort — restores all touched nodes. */
+    cancel: () => void;
+    /** Returns the latest draft `apply` produced (or null before first move). */
+    getDraft: () => Draft | null;
+    isActive: () => boolean;
+    /** Idempotent cleanup. If active, restores scene state and resumes
+     * history, but does **not** fire `onCancel`. Use for React-effect
+     * teardown — onCancel would re-trigger the parent's state machine and
+     * break StrictMode's double-mount cycle. Esc / external aborts must
+     * still call `cancel()` directly. */
+    dispose: () => void;
+};
+export declare function createDragSession<Ctx, Draft>(action: DragAction<Ctx, Draft>, scene: SceneApi, options?: DragSessionOptions): DragSession<Ctx, Draft>;
+//# sourceMappingURL=drag-session.d.ts.map

package/dist/services/drag-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-session.d.ts","sourceRoot":"","sources":["../../src/services/drag-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAgB,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAA;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC;;;;;;;GAOG;AAEH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,IAAI,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,IAAI;IACpC,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACxC,8EAA8E;IAC9E,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAA;IACjD,4EAA4E;IAC5E,MAAM,EAAE,MAAM,OAAO,CAAA;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,KAAK,GAAG,IAAI,CAAA;IAC5B,QAAQ,EAAE,MAAM,OAAO,CAAA;IACvB;;;;yCAIqC;IACrC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAC1C,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAC9B,KAAK,EAAE,QAAQ,EACf,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAiGzB"}

package/dist/services/drag-session.js

@@ -0,0 +1,100 @@
+import { cascadeDirty } from '../registry/relations-resolver';
+const EMPTY_MODIFIERS = { shift: false, alt: false, ctrl: false, meta: false };
+export function createDragSession(action, scene, options = {}) {
+    let active = false;
+    let ctx = null;
+    let draft = null;
+    let dirtyMarked = new Set();
+    function markWithCascade(id) {
+        if (dirtyMarked.has(id))
+            return;
+        const ids = cascadeDirty(id, {
+            scene,
+            spatialQuery: options.spatialQuery,
+            childQuery: options.childQuery,
+        });
+        for (const dirtyId of ids) {
+            if (!dirtyMarked.has(dirtyId)) {
+                scene.markDirty(dirtyId);
+                dirtyMarked.add(dirtyId);
+            }
+        }
+    }
+    function terminate(committed) {
+        if (!active)
+            return;
+        active = false;
+        ctx = null;
+        draft = null;
+        dirtyMarked = new Set();
+        scene.resumeHistory();
+        if (committed)
+            options.onCommit?.();
+        else
+            options.onCancel?.();
+    }
+    return {
+        start(input) {
+            if (active)
+                return; // ignore re-entry
+            scene.pauseHistory();
+            ctx = action.begin({
+                node: input.node,
+                point: input.point,
+                handleId: input.handleId,
+                modifiers: input.modifiers ?? EMPTY_MODIFIERS,
+            });
+            active = true;
+        },
+        move(point, modifiers) {
+            if (!active || ctx == null)
+                return;
+            let next = action.preview(ctx, point, modifiers);
+            if (action.snap) {
+                next = action.snap(next, ctx, undefined);
+            }
+            draft = next;
+            const dirtyIds = action.apply(next, ctx, scene);
+            for (const id of dirtyIds)
+                markWithCascade(id);
+        },
+        commit() {
+            if (!active || ctx == null)
+                return false;
+            const ok = action.commit?.(draft, ctx, scene) ?? true;
+            if (!ok) {
+                action.cancel(ctx, scene);
+                scene.restoreAll();
+            }
+            terminate(ok);
+            return ok;
+        },
+        cancel() {
+            if (!active || ctx == null)
+                return;
+            action.cancel(ctx, scene);
+            scene.restoreAll();
+            terminate(false);
+        },
+        getDraft() {
+            return draft;
+        },
+        isActive() {
+            return active;
+        },
+        dispose() {
+            if (active && ctx != null) {
+                action.cancel(ctx, scene);
+                scene.restoreAll();
+                // Silent terminate: no onCancel. The caller (e.g. useDragAction's
+                // effect cleanup) is reacting to the parent unmounting and would
+                // loop the state machine if onCancel re-set the parent's state.
+                active = false;
+                ctx = null;
+                draft = null;
+                dirtyMarked = new Set();
+                scene.resumeHistory();
+            }
+        },
+    };
+}

package/dist/services/drag-session.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=drag-session.test.d.ts.map

package/dist/services/drag-session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-session.test.d.ts","sourceRoot":"","sources":["../../src/services/drag-session.test.ts"],"names":[],"mappings":""}

package/dist/services/drag-session.test.js

@@ -0,0 +1,219 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+import { z } from 'zod';
+import { nodeRegistry, registerNode } from '../registry/registry';
+import { createDragSession } from './drag-session';
+const id = (s) => s;
+function makeSpyScene(initial = {}) {
+    const calls = {
+        pauseHistory: 0,
+        resumeHistory: 0,
+        restoreAll: 0,
+        markedDirty: [],
+        updated: [],
+    };
+    const nodes = { ...initial };
+    return {
+        get: ((nid) => nodes[nid]),
+        nodes: () => nodes,
+        update: (nid, patch) => {
+            calls.updated.push([nid, patch]);
+            const existing = nodes[nid];
+            if (existing)
+                nodes[nid] = { ...existing, ...patch };
+        },
+        upsert: (n) => {
+            nodes[n.id] = n;
+            return n.id;
+        },
+        delete: (nid) => {
+            delete nodes[nid];
+        },
+        restore: () => { },
+        restoreAll: () => {
+            calls.restoreAll += 1;
+        },
+        markDirty: (nid) => {
+            calls.markedDirty.push(nid);
+        },
+        pauseHistory: () => {
+            calls.pauseHistory += 1;
+        },
+        resumeHistory: () => {
+            calls.resumeHistory += 1;
+        },
+        getSubtree: () => null,
+        cloneNodesInto: () => null,
+        _calls: calls,
+    };
+}
+function makeDef(kind, relations) {
+    return {
+        kind,
+        schemaVersion: 1,
+        schema: z.object({ type: z.literal(kind) }),
+        category: 'utility',
+        defaults: () => ({}),
+        capabilities: {},
+        relations,
+        renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+    };
+}
+function makeAction() {
+    return {
+        begin: ({ node }) => ({ id: node?.id ?? id('default') }),
+        preview: (_ctx, point) => ({ x: point[0] }),
+        apply: (_draft, ctx) => [ctx.id],
+        cancel: () => { },
+    };
+}
+describe('createDragSession', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('start pauses history; commit resumes', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0] });
+        expect(scene._calls.pauseHistory).toBe(1);
+        expect(scene._calls.resumeHistory).toBe(0);
+        session.commit();
+        expect(scene._calls.resumeHistory).toBe(1);
+    });
+    test('cancel resumes history and calls restoreAll', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0] });
+        session.cancel();
+        expect(scene._calls.resumeHistory).toBe(1);
+        expect(scene._calls.restoreAll).toBe(1);
+    });
+    test('move runs preview + apply and marks the returned id dirty', () => {
+        const scene = makeSpyScene({ a: { id: id('a'), type: 'thing' } });
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0], node: { id: id('a') } });
+        session.move([1, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        expect(session.getDraft()).toEqual({ x: 1 });
+        expect(scene._calls.markedDirty).toContain(id('a'));
+    });
+    test('snap callback is invoked when defined', () => {
+        const action = {
+            ...makeAction(),
+            snap: (draft) => ({ x: Math.round(draft.x) }),
+        };
+        const scene = makeSpyScene({ a: { id: id('a'), type: 'thing' } });
+        const session = createDragSession(action, scene);
+        session.start({ point: [0, 0], node: { id: id('a') } });
+        session.move([0.7, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        expect(session.getDraft()).toEqual({ x: 1 });
+    });
+    test('commit returns false when action.commit returns false; calls action.cancel and restoreAll', () => {
+        const cancelSpy = mock(() => { });
+        const action = {
+            ...makeAction(),
+            cancel: cancelSpy,
+            commit: () => false,
+        };
+        const scene = makeSpyScene({ a: { id: id('a'), type: 'thing' } });
+        const session = createDragSession(action, scene);
+        session.start({ point: [0, 0], node: { id: id('a') } });
+        session.move([1, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        const result = session.commit();
+        expect(result).toBe(false);
+        expect(cancelSpy).toHaveBeenCalledTimes(1);
+        expect(scene._calls.restoreAll).toBe(1);
+    });
+    test('move is a no-op when session is not active', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.move([1, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        expect(scene._calls.markedDirty.length).toBe(0);
+    });
+    test('repeated start is a no-op (re-entry guard)', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0] });
+        session.start({ point: [99, 99] });
+        expect(scene._calls.pauseHistory).toBe(1); // only one pause
+    });
+    test('dispose mid-drag cancels and cleans up', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0] });
+        expect(session.isActive()).toBe(true);
+        session.dispose();
+        expect(session.isActive()).toBe(false);
+        expect(scene._calls.resumeHistory).toBe(1);
+        expect(scene._calls.restoreAll).toBe(1);
+    });
+    test('dispose when inactive is a no-op', () => {
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene);
+        session.dispose();
+        expect(scene._calls.pauseHistory).toBe(0);
+        expect(scene._calls.resumeHistory).toBe(0);
+    });
+    test('onCommit callback fires on successful commit', () => {
+        const onCommit = mock(() => { });
+        const onCancel = mock(() => { });
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene, { onCommit, onCancel });
+        session.start({ point: [0, 0] });
+        session.commit();
+        expect(onCommit).toHaveBeenCalledTimes(1);
+        expect(onCancel).toHaveBeenCalledTimes(0);
+    });
+    test('onCancel callback fires on explicit cancel', () => {
+        const onCommit = mock(() => { });
+        const onCancel = mock(() => { });
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene, { onCommit, onCancel });
+        session.start({ point: [0, 0] });
+        session.cancel();
+        expect(onCommit).toHaveBeenCalledTimes(0);
+        expect(onCancel).toHaveBeenCalledTimes(1);
+    });
+    test('dispose does NOT fire onCancel (silent cleanup)', () => {
+        const onCommit = mock(() => { });
+        const onCancel = mock(() => { });
+        const scene = makeSpyScene();
+        const session = createDragSession(makeAction(), scene, { onCommit, onCancel });
+        session.start({ point: [0, 0] });
+        session.dispose();
+        expect(onCommit).toHaveBeenCalledTimes(0);
+        expect(onCancel).toHaveBeenCalledTimes(0);
+        expect(scene._calls.resumeHistory).toBe(1);
+        expect(scene._calls.restoreAll).toBe(1);
+    });
+    test('dirty cascade fires once per id even across multiple move ticks', () => {
+        // Register a kind with no relations — cascade returns just {startId}.
+        registerNode(makeDef('thing'));
+        const scene = makeSpyScene({ a: { id: id('a'), type: 'thing' } });
+        const session = createDragSession(makeAction(), scene);
+        session.start({ point: [0, 0], node: { id: id('a') } });
+        session.move([1, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        session.move([2, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        session.move([3, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        // a is marked once, not three times
+        expect(scene._calls.markedDirty.filter((mid) => mid === id('a')).length).toBe(1);
+    });
+    test('dirty cascade follows hosts relations from the registry', () => {
+        registerNode(makeDef('wall', { hosts: ['door'] }));
+        registerNode(makeDef('door'));
+        const scene = makeSpyScene({
+            w: { id: id('w'), type: 'wall', children: [id('d')] },
+            d: { id: id('d'), type: 'door', parentId: id('w') },
+        });
+        const action = {
+            begin: () => ({ id: id('w') }),
+            preview: (_ctx, point) => ({ x: point[0] }),
+            apply: (_draft, ctx) => [ctx.id],
+            cancel: () => { },
+        };
+        const session = createDragSession(action, scene);
+        session.start({ point: [0, 0], node: { id: id('w') } });
+        session.move([1, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        // both wall and door marked dirty
+        expect(scene._calls.markedDirty).toContain(id('w'));
+        expect(scene._calls.markedDirty).toContain(id('d'));
+    });
+});