@pascal-app/core 0.8.0 → 0.9.2

package/dist/services/single-undo-dance.test.js

@@ -0,0 +1,210 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { createSceneApi } from '../registry/scene-api';
+import useScene from '../store/use-scene';
+globalThis.requestAnimationFrame ??= ((cb) => {
+    cb(0);
+    return 0;
+});
+globalThis.cancelAnimationFrame ??=
+    () => { };
+/**
+ * Validates the "single-undo dance" pattern used by Stage D actions:
+ *
+ *   action.commit:
+ *     scene.restoreAll()       // revert via snapshot (paused → no zundo record)
+ *     scene.resumeHistory()    // unpause zundo
+ *     scene.update(...)        // re-apply final → zundo records one diff
+ *     return true
+ *
+ * After the dance, undo() should roll back ONLY the drag's commit —
+ * never further back than that. The fence-bend regression that surfaced
+ * after Phase 5 Stage D porting was reportedly losing the prior create
+ * step on undo; this test pins the correct behavior.
+ */
+const FENCE_ID = 'fence_test';
+function makeFence(curveOffset) {
+    return {
+        id: FENCE_ID,
+        type: 'fence',
+        parentId: null,
+        object: 'node',
+        visible: true,
+        metadata: {},
+        start: [0, 0],
+        end: [3, 0],
+        height: 1.8,
+        thickness: 0.08,
+        baseHeight: 0.22,
+        postSpacing: 2,
+        postSize: 0.1,
+        topRailHeight: 0.04,
+        groundClearance: 0,
+        edgeInset: 0.015,
+        baseStyle: 'grounded',
+        showInfill: true,
+        color: '#ffffff',
+        style: 'slat',
+        curveOffset,
+    };
+}
+describe('Single-undo dance', () => {
+    beforeEach(() => {
+        useScene.setState({ nodes: {}, rootNodeIds: [] });
+        useScene.temporal.getState().clear();
+    });
+    test('curve-style commit yields a single undo step', () => {
+        // 1. Create the fence (recorded by zundo).
+        useScene.getState().createNode(makeFence(0));
+        const pastCountAfterCreate = useScene.temporal.getState().pastStates.length;
+        // 2. Simulate the drag.
+        const scene = createSceneApi(useScene);
+        scene.pauseHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.2 });
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0.5);
+        // 3. Commit dance.
+        scene.restoreAll();
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0);
+        scene.resumeHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        const pastCountAfterDance = useScene.temporal.getState().pastStates.length;
+        expect(pastCountAfterDance).toBe(pastCountAfterCreate + 1);
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0.5);
+        // 4. Undo — should return fence to curveOffset 0, NOT delete it.
+        useScene.temporal.getState().undo();
+        const fenceAfterUndo = useScene.getState().nodes[FENCE_ID];
+        expect(fenceAfterUndo).toBeDefined();
+        expect(fenceAfterUndo.curveOffset).toBe(0);
+    });
+    test('StrictMode double-mount: dispose-then-restart preserves history', () => {
+        useScene.getState().createNode(makeFence(0));
+        const pastBeforeBend = useScene.temporal.getState().pastStates.length;
+        // Simulate StrictMode: first mount → cleanup (dispose) → second mount → drag → commit.
+        const scene = createSceneApi(useScene);
+        // Mount 1.
+        scene.pauseHistory();
+        // Mount 1 cleanup (StrictMode): no apply happened yet. dispose-equivalent.
+        scene.restoreAll(); // snapshot empty, no-op.
+        scene.resumeHistory();
+        // Mount 2.
+        scene.pauseHistory();
+        // Drag.
+        scene.update(FENCE_ID, { curveOffset: 0.3 });
+        scene.update(FENCE_ID, { curveOffset: 0.7 });
+        // Commit dance.
+        scene.restoreAll();
+        scene.resumeHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.7 });
+        const pastAfterBend = useScene.temporal.getState().pastStates.length;
+        // Exactly one new entry: the pre-bend state. Not two (which would mean
+        // StrictMode's first mount/cleanup polluted history).
+        expect(pastAfterBend).toBe(pastBeforeBend + 1);
+        useScene.temporal.getState().undo();
+        expect(useScene.getState().nodes[FENCE_ID]).toBeDefined();
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0);
+    });
+    test('commit-returns-false (no change) does NOT consume the prior pastState', () => {
+        // This is the suspected bend regression: when action.commit returns
+        // false (draft.curveOffset === ctx.originalCurveOffset), session.commit
+        // calls scene.restoreAll() but doesn't push to pastStates. Subsequent
+        // undo pops the PRIOR action (e.g. fence creation), not the no-op
+        // bend.
+        useScene.getState().createNode(makeFence(0));
+        const pastBeforeBend = useScene.temporal.getState().pastStates.length;
+        const scene = createSceneApi(useScene);
+        scene.pauseHistory();
+        // Drag back to original — simulates no-op bend.
+        scene.update(FENCE_ID, { curveOffset: 0.0 });
+        // Cancel path (mimics session.commit → action.commit returns false → scene.restoreAll → terminate).
+        scene.restoreAll();
+        scene.resumeHistory();
+        const pastAfterNoOp = useScene.temporal.getState().pastStates.length;
+        expect(pastAfterNoOp).toBe(pastBeforeBend); // no entries added
+        // Now undo — this should be a no-op (state unchanged), but pops the create.
+        useScene.temporal.getState().undo();
+        // ⚠️ Reproduces the bug — undo removes the fence:
+        const fence = useScene.getState().nodes[FENCE_ID];
+        if (fence === undefined) {
+            // Bug reproduced. The "no-op bend" allowed Ctrl-Z to fall through
+            // to the fence creation. Fix is in action.commit: don't return false
+            // — push a no-op entry instead, or guard against the cancel path.
+            expect(fence).toBeUndefined();
+        }
+        else {
+            expect(fence.curveOffset).toBe(0);
+        }
+    });
+    test('full session flow via createDragSession with real action.commit dance', async () => {
+        // Reproduces the actual wrapper flow:
+        //   - createNode → session.start → moves → grid:click → session.commit.
+        // The action.commit does the dance internally.
+        const { createDragSession } = await import('./drag-session');
+        useScene.getState().createNode(makeFence(0));
+        const pastBeforeBend = useScene.temporal.getState().pastStates.length;
+        const scene = createSceneApi(useScene);
+        const action = {
+            begin: () => ({ original: 0 }),
+            preview: (_ctx, point) => ({ offset: point[0] }),
+            apply: (draft, _ctx, s) => {
+                s.update(FENCE_ID, { curveOffset: draft.offset });
+                return [FENCE_ID];
+            },
+            commit: (draft, ctx, s) => {
+                if (draft.offset === ctx.original)
+                    return false;
+                s.restoreAll();
+                s.resumeHistory();
+                s.update(FENCE_ID, { curveOffset: draft.offset });
+                return true;
+            },
+            cancel: () => { },
+        };
+        const session = createDragSession(action, scene);
+        session.start({ point: [0, 0] });
+        session.move([0.3, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        session.move([0.5, 0], { shift: false, alt: false, ctrl: false, meta: false });
+        const okCommit = session.commit();
+        expect(okCommit).toBe(true);
+        const pastAfter = useScene.temporal.getState().pastStates.length;
+        expect(pastAfter).toBe(pastBeforeBend + 1);
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0.5);
+        useScene.temporal.getState().undo();
+        const after = useScene.getState().nodes[FENCE_ID];
+        expect(after).toBeDefined();
+        expect(after.curveOffset).toBe(0);
+    });
+    test('REAL bend (draft != original): one Ctrl-Z undoes only the bend', () => {
+        useScene.getState().createNode(makeFence(0));
+        const stateAfterCreate = useScene.getState().nodes[FENCE_ID];
+        expect(stateAfterCreate.curveOffset).toBe(0);
+        const scene = createSceneApi(useScene);
+        scene.pauseHistory();
+        // Simulate a real drag: capture original, mutate to non-zero.
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0.5);
+        // Dance.
+        scene.restoreAll();
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0);
+        scene.resumeHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        expect(useScene.getState().nodes[FENCE_ID].curveOffset).toBe(0.5);
+        // First Ctrl-Z should undo the bend.
+        useScene.temporal.getState().undo();
+        const afterFirstUndo = useScene.getState().nodes[FENCE_ID];
+        expect(afterFirstUndo).toBeDefined();
+        expect(afterFirstUndo?.curveOffset).toBe(0);
+    });
+    test('a SECOND undo rolls the create step back', () => {
+        useScene.getState().createNode(makeFence(0));
+        const scene = createSceneApi(useScene);
+        scene.pauseHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        scene.restoreAll();
+        scene.resumeHistory();
+        scene.update(FENCE_ID, { curveOffset: 0.5 });
+        useScene.temporal.getState().undo();
+        expect(useScene.getState().nodes[FENCE_ID]).toBeDefined();
+        useScene.temporal.getState().undo();
+        expect(useScene.getState().nodes[FENCE_ID]).toBeUndefined();
+    });
+});

package/dist/services/snap.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure snap math — no React, no R3F, no scene access.
+ *
+ * Phase 1 ships the kind-agnostic snappers (grid + angle). Wall-specific
+ * snapping (snap-to-endpoint, snap-along-T) currently lives in
+ * `editor/src/components/tools/wall/wall-drafting.ts` and stays there until
+ * Phase 3, when the wall migration ports it here behind a `wallSnap` namespace.
+ *
+ * The functions here are stable contract — Phase 3 only adds, never removes.
+ */
+export type Vec2 = readonly [number, number];
+export type Vec3 = readonly [number, number, number];
+/** Default planar grid spacing in meters. Matches the editor's wall tool. */
+export declare const DEFAULT_GRID_STEP = 0.25;
+/** Default angle-snap step — π/12 = 15°. */
+export declare const DEFAULT_ANGLE_STEP: number;
+/** Snaps a single scalar to the nearest multiple of `step`. */
+export declare function snapScalar(value: number, step?: number): number;
+/** Snaps a 2D point to a regular planar grid. */
+export declare function snapPointToGrid(point: Vec2, step?: number): Vec2;
+/** Snaps a 3D point to a regular grid in the X/Z plane, preserving Y. */
+export declare function snapVec3ToGrid(point: Vec3, step?: number): Vec3;
+/**
+ * Snap a world XZ point to the grid, then express it in the local frame of
+ * a building positioned at `buildingPosition` with rotation `buildingRotationY`
+ * (radians, around the Y axis). Returns both the snapped world point and its
+ * local-frame equivalent, so callers can render in either frame without
+ * recomputing the rotation.
+ *
+ * Use when a tool needs to keep snapping on the world grid (the grid the
+ * editor renders) even when the active building is rotated. Snapping in the
+ * building's local frame would otherwise chase the rotated axes and miss
+ * the visible grid lines.
+ */
+export declare function snapWorldXZToBuildingLocal(worldX: number, worldZ: number, buildingPosition: Vec3, buildingRotationY: number, step?: number): {
+    world: [number, number];
+    local: [number, number];
+};
+/**
+ * Snaps a cursor point to the nearest angle multiple of `angleStep` (radians)
+ * measured from `from`, preserving distance. Useful for axis/diagonal-locked
+ * placement and wall draft endpoint locking.
+ *
+ * After the angle snap, the result is grid-snapped if `gridStep` is provided
+ * — keeps endpoints landing on grid intersections.
+ */
+export declare function snapPointToAngle(from: Vec2, cursor: Vec2, angleStep?: number, gridStep?: number): Vec2;
+/**
+ * Snaps a cursor point onto the nearest angle ray from `from` (multiples of
+ * `angleStep`), projecting the cursor onto that ray, then snaps the distance
+ * ALONG the ray to `distanceStep`. Unlike `snapPointToAngle` with a
+ * `gridStep`, the result stays exactly on the snapped ray — grid-snapping
+ * after the angle projection pulls points off non-axis rays.
+ */
+export declare function snapPointAlongAngleRay(from: Vec2, cursor: Vec2, angleStep?: number, distanceStep?: number): Vec2;
+/**
+ * Snaps an angle (in radians) to the nearest entry in `snapAngles` (also in
+ * radians). Returns the original angle if no entry is within `toleranceRad`.
+ */
+export declare function snapAngleToList(angle: number, snapAngles: readonly number[], toleranceRad?: number): number;
+/**
+ * Stable surface that `DragAction.snap` callbacks receive. Phase 1 ships
+ * `grid` and `angle`. Phase 3 adds a `wall` namespace populated by wall
+ * migration. Plugin authors should target this facade rather than importing
+ * the individual functions, so future Phase contributions become visible
+ * without code changes.
+ */
+export type SnapServices = {
+    grid: {
+        snap: (point: Vec2, step?: number) => Vec2;
+        snapVec3: (point: Vec3, step?: number) => Vec3;
+        snapScalar: (value: number, step?: number) => number;
+    };
+    angle: {
+        snapTo: (from: Vec2, cursor: Vec2, angleStep?: number, gridStep?: number) => Vec2;
+        snapToList: (angle: number, list: readonly number[], toleranceRad?: number) => number;
+    };
+};
+export declare const snapServices: SnapServices;
+//# sourceMappingURL=snap.d.ts.map

package/dist/services/snap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snap.d.ts","sourceRoot":"","sources":["../../src/services/snap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC5C,MAAM,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEpD,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,QAAe,CAAA;AAI9C,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAA0B,GAAG,MAAM,CAGlF;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,GAAE,MAA0B,GAAG,IAAI,CAEnF;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,GAAE,MAA0B,GAAG,IAAI,CAElF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,IAAI,EACtB,iBAAiB,EAAE,MAAM,EACzB,IAAI,GAAE,MAA0B,GAC/B;IAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA2BtD;AAID;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,IAAI,EACZ,SAAS,GAAE,MAA2B,EACtC,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAWN;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,IAAI,EACZ,SAAS,GAAE,MAA2B,EACtC,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAYN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,YAAY,GAAE,MAAqB,GAClC,MAAM,CAcR;AAID;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;QAC1C,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;QAC9C,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;KACrD,CAAA;IACD,KAAK,EAAE;QACL,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;QACjF,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;KACtF,CAAA;CACF,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,YAU1B,CAAA"}

package/dist/services/snap.js

@@ -0,0 +1,140 @@
+/**
+ * Pure snap math — no React, no R3F, no scene access.
+ *
+ * Phase 1 ships the kind-agnostic snappers (grid + angle). Wall-specific
+ * snapping (snap-to-endpoint, snap-along-T) currently lives in
+ * `editor/src/components/tools/wall/wall-drafting.ts` and stays there until
+ * Phase 3, when the wall migration ports it here behind a `wallSnap` namespace.
+ *
+ * The functions here are stable contract — Phase 3 only adds, never removes.
+ */
+/** Default planar grid spacing in meters. Matches the editor's wall tool. */
+export const DEFAULT_GRID_STEP = 0.25;
+/** Default angle-snap step — π/12 = 15°. */
+export const DEFAULT_ANGLE_STEP = Math.PI / 12;
+// ─── Grid snap ────────────────────────────────────────────────────────
+/** Snaps a single scalar to the nearest multiple of `step`. */
+export function snapScalar(value, step = DEFAULT_GRID_STEP) {
+    if (step <= 0)
+        return value;
+    return Math.round(value / step) * step;
+}
+/** Snaps a 2D point to a regular planar grid. */
+export function snapPointToGrid(point, step = DEFAULT_GRID_STEP) {
+    return [snapScalar(point[0], step), snapScalar(point[1], step)];
+}
+/** Snaps a 3D point to a regular grid in the X/Z plane, preserving Y. */
+export function snapVec3ToGrid(point, step = DEFAULT_GRID_STEP) {
+    return [snapScalar(point[0], step), point[1], snapScalar(point[2], step)];
+}
+/**
+ * Snap a world XZ point to the grid, then express it in the local frame of
+ * a building positioned at `buildingPosition` with rotation `buildingRotationY`
+ * (radians, around the Y axis). Returns both the snapped world point and its
+ * local-frame equivalent, so callers can render in either frame without
+ * recomputing the rotation.
+ *
+ * Use when a tool needs to keep snapping on the world grid (the grid the
+ * editor renders) even when the active building is rotated. Snapping in the
+ * building's local frame would otherwise chase the rotated axes and miss
+ * the visible grid lines.
+ */
+export function snapWorldXZToBuildingLocal(worldX, worldZ, buildingPosition, buildingRotationY, step = DEFAULT_GRID_STEP) {
+    if (step <= 0) {
+        const dx = worldX - buildingPosition[0];
+        const dz = worldZ - buildingPosition[2];
+        const cos = Math.cos(buildingRotationY);
+        const sin = Math.sin(buildingRotationY);
+        return {
+            world: [worldX, worldZ],
+            local: [dx * cos - dz * sin, dx * sin + dz * cos],
+        };
+    }
+    const snappedWX = Math.round(worldX / step) * step;
+    const snappedWZ = Math.round(worldZ / step) * step;
+    const dx = snappedWX - buildingPosition[0];
+    const dz = snappedWZ - buildingPosition[2];
+    const cos = Math.cos(buildingRotationY);
+    const sin = Math.sin(buildingRotationY);
+    // The forward (local → world) rotation used in the editor is
+    //   wx = bx + lx*cos + lz*sin
+    //   wz = bz - lx*sin + lz*cos
+    // so the inverse (orthogonal, so transpose) is
+    //   lx =  dx*cos - dz*sin
+    //   lz =  dx*sin + dz*cos
+    return {
+        world: [snappedWX, snappedWZ],
+        local: [dx * cos - dz * sin, dx * sin + dz * cos],
+    };
+}
+// ─── Angle snap ───────────────────────────────────────────────────────
+/**
+ * Snaps a cursor point to the nearest angle multiple of `angleStep` (radians)
+ * measured from `from`, preserving distance. Useful for axis/diagonal-locked
+ * placement and wall draft endpoint locking.
+ *
+ * After the angle snap, the result is grid-snapped if `gridStep` is provided
+ * — keeps endpoints landing on grid intersections.
+ */
+export function snapPointToAngle(from, cursor, angleStep = DEFAULT_ANGLE_STEP, gridStep) {
+    const dx = cursor[0] - from[0];
+    const dz = cursor[1] - from[1];
+    const angle = Math.atan2(dz, dx);
+    const snappedAngle = Math.round(angle / angleStep) * angleStep;
+    const distance = Math.hypot(dx, dz);
+    const projected = [
+        from[0] + Math.cos(snappedAngle) * distance,
+        from[1] + Math.sin(snappedAngle) * distance,
+    ];
+    return gridStep == null ? projected : snapPointToGrid(projected, gridStep);
+}
+/**
+ * Snaps a cursor point onto the nearest angle ray from `from` (multiples of
+ * `angleStep`), projecting the cursor onto that ray, then snaps the distance
+ * ALONG the ray to `distanceStep`. Unlike `snapPointToAngle` with a
+ * `gridStep`, the result stays exactly on the snapped ray — grid-snapping
+ * after the angle projection pulls points off non-axis rays.
+ */
+export function snapPointAlongAngleRay(from, cursor, angleStep = DEFAULT_ANGLE_STEP, distanceStep) {
+    const dx = cursor[0] - from[0];
+    const dz = cursor[1] - from[1];
+    if (dx === 0 && dz === 0)
+        return [from[0], from[1]];
+    const angle = Math.atan2(dz, dx);
+    const snappedAngle = angleStep > 0 ? Math.round(angle / angleStep) * angleStep : angle;
+    const dirX = Math.cos(snappedAngle);
+    const dirZ = Math.sin(snappedAngle);
+    const projected = dx * dirX + dz * dirZ;
+    const distance = distanceStep != null && distanceStep > 0 ? snapScalar(projected, distanceStep) : projected;
+    return [from[0] + dirX * distance, from[1] + dirZ * distance];
+}
+/**
+ * Snaps an angle (in radians) to the nearest entry in `snapAngles` (also in
+ * radians). Returns the original angle if no entry is within `toleranceRad`.
+ */
+export function snapAngleToList(angle, snapAngles, toleranceRad = Math.PI / 36) {
+    let best = null;
+    let bestDelta = Number.POSITIVE_INFINITY;
+    for (const target of snapAngles) {
+        // wrap delta to [-π, π]
+        let delta = ((angle - target) % (Math.PI * 2)) + Math.PI * 3;
+        delta = (delta % (Math.PI * 2)) - Math.PI;
+        const abs = Math.abs(delta);
+        if (abs < bestDelta && abs <= toleranceRad) {
+            bestDelta = abs;
+            best = target;
+        }
+    }
+    return best ?? angle;
+}
+export const snapServices = {
+    grid: {
+        snap: snapPointToGrid,
+        snapVec3: snapVec3ToGrid,
+        snapScalar,
+    },
+    angle: {
+        snapTo: snapPointToAngle,
+        snapToList: snapAngleToList,
+    },
+};

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

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

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

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

package/dist/services/snap.test.js

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+import { DEFAULT_ANGLE_STEP, DEFAULT_GRID_STEP, snapAngleToList, snapPointAlongAngleRay, snapPointToAngle, snapPointToGrid, snapScalar, snapServices, snapVec3ToGrid, } from './snap';
+describe('snapScalar', () => {
+    test('rounds to multiples of step', () => {
+        expect(snapScalar(0.27, 0.25)).toBe(0.25);
+        expect(snapScalar(0.13, 0.25)).toBe(0.25);
+        expect(snapScalar(0.12, 0.25)).toBe(0);
+        expect(snapScalar(1.7, 0.25)).toBeCloseTo(1.75);
+    });
+    test('returns input unchanged when step is non-positive', () => {
+        expect(snapScalar(0.42, 0)).toBe(0.42);
+        expect(snapScalar(0.42, -1)).toBe(0.42);
+    });
+    test('default step is 0.25m', () => {
+        expect(snapScalar(0.3)).toBe(0.25);
+        expect(snapScalar(0.4)).toBe(0.5);
+        expect(DEFAULT_GRID_STEP).toBe(0.25);
+    });
+});
+describe('snapPointToGrid', () => {
+    test('snaps both components independently', () => {
+        expect(snapPointToGrid([0.3, 0.6], 0.25)).toEqual([0.25, 0.5]);
+    });
+    test('preserves exact-grid points', () => {
+        expect(snapPointToGrid([1, 2], 0.5)).toEqual([1, 2]);
+    });
+});
+describe('snapVec3ToGrid', () => {
+    test('snaps X and Z, leaves Y untouched', () => {
+        expect(snapVec3ToGrid([0.3, 1.7, 0.6], 0.25)).toEqual([0.25, 1.7, 0.5]);
+    });
+});
+describe('snapPointToAngle', () => {
+    test('snaps to axis (0°) when cursor is near horizontal', () => {
+        const from = [0, 0];
+        const cursor = [1, 0.05]; // near 0°
+        const snapped = snapPointToAngle(from, cursor, Math.PI / 4);
+        expect(snapped[0]).toBeCloseTo(1, 1);
+        expect(snapped[1]).toBeCloseTo(0, 5);
+    });
+    test('snaps to 45° at π/4 step', () => {
+        const from = [0, 0];
+        const cursor = [1, 0.9]; // near 45°
+        const snapped = snapPointToAngle(from, cursor, Math.PI / 4);
+        // distance preserved (≈ √(1² + 0.9²) ≈ 1.345), angle locked to 45°
+        const expectedDist = Math.hypot(1, 0.9);
+        expect(snapped[0]).toBeCloseTo(expectedDist * Math.cos(Math.PI / 4));
+        expect(snapped[1]).toBeCloseTo(expectedDist * Math.sin(Math.PI / 4));
+    });
+    test('default angle step is π/12 (15°)', () => {
+        expect(DEFAULT_ANGLE_STEP).toBeCloseTo(Math.PI / 12);
+    });
+    test('grid-snaps the projected point when gridStep is provided', () => {
+        const from = [0, 0];
+        const cursor = [1.05, 0.02]; // ~horizontal, slightly off grid
+        const snapped = snapPointToAngle(from, cursor, Math.PI / 4, 0.25);
+        // After 0° lock + 0.25m grid, X must be a 0.25 multiple.
+        expect(snapped[0] / 0.25).toBeCloseTo(Math.round(snapped[0] / 0.25));
+    });
+    test('preserves distance from `from`', () => {
+        const from = [2, 3];
+        const cursor = [3, 4];
+        const distance = Math.hypot(1, 1);
+        const snapped = snapPointToAngle(from, cursor, Math.PI / 4);
+        expect(Math.hypot(snapped[0] - 2, snapped[1] - 3)).toBeCloseTo(distance);
+    });
+});
+describe('snapPointAlongAngleRay', () => {
+    test('stays exactly on the 15° ray while distance-snapping to the grid step', () => {
+        const from = [0, 0];
+        const cursor = [2, 0.5]; // ≈14° — snaps to 15°
+        const snapped = snapPointAlongAngleRay(from, cursor, Math.PI / 12, 0.25);
+        expect(Math.atan2(snapped[1], snapped[0])).toBeCloseTo(Math.PI / 12, 10);
+        const distance = Math.hypot(snapped[0], snapped[1]);
+        expect(distance / 0.25).toBeCloseTo(Math.round(distance / 0.25), 10);
+    });
+    test('grid-snapping after the angle projection would pull the point off the ray', () => {
+        const from = [0, 0];
+        const cursor = [2, 0.5];
+        const offRay = snapPointToAngle(from, cursor, Math.PI / 12, 0.25);
+        expect(Math.atan2(offRay[1], offRay[0])).not.toBeCloseTo(Math.PI / 12, 4);
+    });
+    test('45° back-compat: locks to the diagonal with grid-multiple distance', () => {
+        const from = [1, 1];
+        const cursor = [2.1, 1.9]; // near 45° from `from`
+        const snapped = snapPointAlongAngleRay(from, cursor, Math.PI / 4, 0.25);
+        expect(Math.atan2(snapped[1] - 1, snapped[0] - 1)).toBeCloseTo(Math.PI / 4, 10);
+        const distance = Math.hypot(snapped[0] - 1, snapped[1] - 1);
+        expect(distance / 0.25).toBeCloseTo(Math.round(distance / 0.25), 10);
+    });
+    test('preserves the projected distance when no distanceStep is given', () => {
+        const from = [0, 0];
+        const cursor = [1, 0.05]; // near 0°
+        const snapped = snapPointAlongAngleRay(from, cursor, Math.PI / 12);
+        expect(snapped[0]).toBeCloseTo(1, 10); // projection of (1, 0.05) onto 0° ray
+        expect(snapped[1]).toBeCloseTo(0, 10);
+    });
+    test('returns `from` for a zero-length segment', () => {
+        expect(snapPointAlongAngleRay([2, 3], [2, 3], Math.PI / 12, 0.25)).toEqual([2, 3]);
+    });
+    test('is idempotent on its own output', () => {
+        const from = [0.5, -1];
+        const cursor = [3.2, 0.4];
+        const once = snapPointAlongAngleRay(from, cursor, Math.PI / 12, 0.5);
+        const twice = snapPointAlongAngleRay(from, once, Math.PI / 12, 0.5);
+        expect(twice[0]).toBeCloseTo(once[0], 10);
+        expect(twice[1]).toBeCloseTo(once[1], 10);
+    });
+});
+describe('snapAngleToList', () => {
+    test('snaps to the nearest entry within tolerance', () => {
+        const targets = [0, Math.PI / 2, Math.PI, (3 * Math.PI) / 2];
+        expect(snapAngleToList(0.05, targets, Math.PI / 36)).toBe(0);
+        expect(snapAngleToList(Math.PI / 2 + 0.02, targets, Math.PI / 36)).toBe(Math.PI / 2);
+    });
+    test('returns original angle when no target is within tolerance', () => {
+        const targets = [0, Math.PI / 2];
+        expect(snapAngleToList(0.5, targets, Math.PI / 36)).toBe(0.5);
+    });
+    test('handles wrap-around near ±π', () => {
+        const targets = [Math.PI];
+        expect(snapAngleToList(-Math.PI + 0.01, targets, Math.PI / 36)).toBe(Math.PI);
+    });
+});
+describe('snapServices facade', () => {
+    test('grid.snap matches snapPointToGrid', () => {
+        expect(snapServices.grid.snap([0.3, 0.6], 0.25)).toEqual(snapPointToGrid([0.3, 0.6], 0.25));
+    });
+    test('grid.snapScalar matches snapScalar', () => {
+        expect(snapServices.grid.snapScalar(0.3, 0.25)).toBe(snapScalar(0.3, 0.25));
+    });
+    test('angle.snapTo matches snapPointToAngle', () => {
+        const from = [0, 0];
+        const cursor = [1, 0.9];
+        expect(snapServices.angle.snapTo(from, cursor, Math.PI / 4)).toEqual(snapPointToAngle(from, cursor, Math.PI / 4));
+    });
+});

package/dist/services/system-graph.d.ts

@@ -0,0 +1,30 @@
+import type { AnyNode, AnyNodeId } from '../schema';
+export type SystemSummary = {
+    /** Every node in this connected component. */
+    nodeIds: AnyNodeId[];
+    /** Distribution loops present, e.g. ['supply'], ['supply','return']. */
+    systems: string[];
+    /** Duct / lineset run statistics. */
+    runCount: number;
+    runLengthM: number;
+    fittingCount: number;
+    terminalCount: number;
+    equipmentCount: number;
+    /** False = orphaned subtree: air goes nowhere (no furnace / air
+     *  handler / condenser anywhere in the component). */
+    connectedToEquipment: boolean;
+};
+/**
+ * Group every port-bearing node into connected components via coinciding
+ * ports. Nodes with ports but no joints form singleton components; nodes
+ * without `def.ports` don't participate at all.
+ */
+export declare function buildPortComponents(nodes: Readonly<Record<AnyNodeId, AnyNode>>): AnyNodeId[][];
+/**
+ * Summary of the system the given node belongs to, or null when the node
+ * has no ports (not a distribution kind). A node with ports but no
+ * joints yet still gets a (singleton) summary — `connectedToEquipment:
+ * false` is the interesting signal there.
+ */
+export declare function summarizeSystemFor(nodeId: AnyNodeId, nodes: Readonly<Record<AnyNodeId, AnyNode>>): SystemSummary | null;
+//# sourceMappingURL=system-graph.d.ts.map

package/dist/services/system-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph.d.ts","sourceRoot":"","sources":["../../src/services/system-graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAoBnD,MAAM,MAAM,aAAa,GAAG;IAC1B,8CAA8C;IAC9C,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB;0DACsD;IACtD,oBAAoB,EAAE,OAAO,CAAA;CAC9B,CAAA;AA2DD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,EAAE,CA4B9F;AAkDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,GAC1C,aAAa,GAAG,IAAI,CAStB"}