@pascal-app/core 0.8.0 → 0.9.2

package/dist/services/hosting.d.ts

@@ -0,0 +1,88 @@
+import type { SceneApi, SurfacesConfig } from '../registry/types';
+import type { AnyNode, AnyNodeId } from '../schema/types';
+/**
+ * Maximum depth a node tree can host. Guards items-on-items-on-items chains
+ * from growing pathological — pre-Phase-1 the editor had no cap. Set high
+ * enough to allow legitimate stacking (chair on platform on truck on floor)
+ * while preventing AI/plugin-generated runaway.
+ */
+export declare const MAX_HOST_DEPTH = 6;
+export type Vec3 = readonly [number, number, number];
+export type AttachError = {
+    kind: 'self-host';
+    nodeId: AnyNodeId;
+} | {
+    kind: 'cycle';
+    nodeId: AnyNodeId;
+    hostId: AnyNodeId;
+} | {
+    kind: 'depth-exceeded';
+    depth: number;
+    max: number;
+} | {
+    kind: 'host-missing';
+    hostId: AnyNodeId;
+} | {
+    kind: 'kind-not-allowed';
+    hostKind: string;
+    allowed: readonly string[];
+};
+export type AttachResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: AttachError;
+};
+/**
+ * Validates that attaching `child` to `host` is safe and either returns an
+ * actionable error or signals OK. Does NOT mutate the scene — callers apply
+ * the patch after a successful check.
+ *
+ * Rules:
+ * - A node cannot host itself.
+ * - The hosting chain (child → host → host.parent → ...) must not contain
+ *   `child` (cycle prevention).
+ * - The resulting chain must not exceed {@link MAX_HOST_DEPTH}.
+ * - If the child's NodeDefinition declares `capabilities.hostable.parents`,
+ *   `host.type` must appear in that list.
+ */
+export declare function canAttach(childId: AnyNodeId, hostId: AnyNodeId, scene: SceneApi): AttachResult;
+/**
+ * Returns the surfaces declared by a host's NodeDefinition. Surfaces describe
+ * where other nodes can stack/mount — the `top` of a slab, the `sides` of a
+ * wall, or a custom callback. Returns null when the host's def declares no
+ * surfaces (or no def is registered).
+ */
+export declare function getSurface(host: AnyNode): SurfacesConfig | null;
+/**
+ * Resolves the stackable top height of a host (e.g. table surface, slab top,
+ * stair landing). Returns `null` when the host has no `surfaces.top`.
+ */
+export declare function getTopSurfaceHeight(host: AnyNode): number | null;
+/**
+ * Whether `host` can receive a surface-resting (top-stacked) child. A
+ * ceiling-mounted item hangs from the ceiling, so its visible "top" is not a
+ * usable resting surface — nothing should stack on a ceiling fan. The check
+ * reads the instance-level `asset.attachTo` (not the host KIND, which is shared
+ * across all items) so a single gate covers every interaction path.
+ */
+export declare function canHostOnTop(host: AnyNode): boolean;
+/**
+ * Pure host-discovery helper. Given a list of candidate hosts (already
+ * narrowed by spatial query) and a point, returns the first whose
+ * `capabilities.hostable` lists `placedKind` AND whose surface contains the
+ * point. The runtime is responsible for providing pre-filtered candidates;
+ * this function does not perform spatial queries itself.
+ */
+export declare function pickHost(args: {
+    point: Vec3;
+    candidates: readonly AnyNode[];
+    placedKind: string;
+    hitTest?: (host: AnyNode, point: Vec3) => boolean;
+}): AnyNode | null;
+/**
+ * Convenience: clamps a Y coordinate to the top of a host surface, when one
+ * is declared. Returns the original Y if the host has no top surface.
+ */
+export declare function clampYToHostTop(host: AnyNode, originalY: number): number;
+//# sourceMappingURL=hosting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hosting.d.ts","sourceRoot":"","sources":["../../src/services/hosting.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B,MAAM,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEpD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAE9E,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAA;AAE3E;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,GAAG,YAAY,CAoC9F;AAoBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAG/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKhE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,KAAK,EAAE,IAAI,CAAA;IACX,UAAU,EAAE,SAAS,OAAO,EAAE,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,KAAK,OAAO,CAAA;CAClD,GAAG,OAAO,GAAG,IAAI,CAUjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxE"}

package/dist/services/hosting.js

@@ -0,0 +1,131 @@
+import { nodeRegistry } from '../registry/registry';
+/**
+ * Maximum depth a node tree can host. Guards items-on-items-on-items chains
+ * from growing pathological — pre-Phase-1 the editor had no cap. Set high
+ * enough to allow legitimate stacking (chair on platform on truck on floor)
+ * while preventing AI/plugin-generated runaway.
+ */
+export const MAX_HOST_DEPTH = 6;
+/**
+ * Validates that attaching `child` to `host` is safe and either returns an
+ * actionable error or signals OK. Does NOT mutate the scene — callers apply
+ * the patch after a successful check.
+ *
+ * Rules:
+ * - A node cannot host itself.
+ * - The hosting chain (child → host → host.parent → ...) must not contain
+ *   `child` (cycle prevention).
+ * - The resulting chain must not exceed {@link MAX_HOST_DEPTH}.
+ * - If the child's NodeDefinition declares `capabilities.hostable.parents`,
+ *   `host.type` must appear in that list.
+ */
+export function canAttach(childId, hostId, scene) {
+    if (childId === hostId) {
+        return { ok: false, error: { kind: 'self-host', nodeId: childId } };
+    }
+    const host = scene.get(hostId);
+    if (!host) {
+        return { ok: false, error: { kind: 'host-missing', hostId } };
+    }
+    const child = scene.get(childId);
+    if (!child) {
+        // No child node yet — likely a placement preview. Allow attach to proceed;
+        // the caller is responsible for ensuring child exists before commit.
+        return checkDepth(hostId, scene);
+    }
+    const childDef = nodeRegistry.get(child.type);
+    const allowed = childDef?.capabilities.hostable?.parents;
+    if (allowed && allowed.length > 0 && !allowed.includes(host.type)) {
+        return {
+            ok: false,
+            error: { kind: 'kind-not-allowed', hostKind: host.type, allowed },
+        };
+    }
+    // Cycle: walk host's ancestors and reject if we hit the child.
+    let cursor = host;
+    while (cursor) {
+        if (cursor.id === childId) {
+            return { ok: false, error: { kind: 'cycle', nodeId: childId, hostId } };
+        }
+        cursor = cursor.parentId ? scene.get(cursor.parentId) : undefined;
+    }
+    return checkDepth(hostId, scene);
+}
+function checkDepth(hostId, scene) {
+    // Count host's own depth (root = 0); attaching adds 1 to the child's depth.
+    let depth = 0;
+    let cursor = scene.get(hostId);
+    while (cursor?.parentId) {
+        cursor = scene.get(cursor.parentId);
+        depth += 1;
+        if (depth > MAX_HOST_DEPTH) {
+            return { ok: false, error: { kind: 'depth-exceeded', depth, max: MAX_HOST_DEPTH } };
+        }
+    }
+    // Child sits one below host.
+    if (depth + 1 > MAX_HOST_DEPTH) {
+        return { ok: false, error: { kind: 'depth-exceeded', depth: depth + 1, max: MAX_HOST_DEPTH } };
+    }
+    return { ok: true };
+}
+/**
+ * Returns the surfaces declared by a host's NodeDefinition. Surfaces describe
+ * where other nodes can stack/mount — the `top` of a slab, the `sides` of a
+ * wall, or a custom callback. Returns null when the host's def declares no
+ * surfaces (or no def is registered).
+ */
+export function getSurface(host) {
+    const def = nodeRegistry.get(host.type);
+    return def?.capabilities.surfaces ?? null;
+}
+/**
+ * Resolves the stackable top height of a host (e.g. table surface, slab top,
+ * stair landing). Returns `null` when the host has no `surfaces.top`.
+ */
+export function getTopSurfaceHeight(host) {
+    const surfaces = getSurface(host);
+    if (!surfaces?.top)
+        return null;
+    const { height } = surfaces.top;
+    return typeof height === 'function' ? height(host) : height;
+}
+/**
+ * Whether `host` can receive a surface-resting (top-stacked) child. A
+ * ceiling-mounted item hangs from the ceiling, so its visible "top" is not a
+ * usable resting surface — nothing should stack on a ceiling fan. The check
+ * reads the instance-level `asset.attachTo` (not the host KIND, which is shared
+ * across all items) so a single gate covers every interaction path.
+ */
+export function canHostOnTop(host) {
+    const attachTo = host.asset?.attachTo;
+    return attachTo !== 'ceiling';
+}
+/**
+ * Pure host-discovery helper. Given a list of candidate hosts (already
+ * narrowed by spatial query) and a point, returns the first whose
+ * `capabilities.hostable` lists `placedKind` AND whose surface contains the
+ * point. The runtime is responsible for providing pre-filtered candidates;
+ * this function does not perform spatial queries itself.
+ */
+export function pickHost(args) {
+    for (const host of args.candidates) {
+        const def = nodeRegistry.get(host.type);
+        const hostable = def?.capabilities.hostable;
+        if (!hostable)
+            continue;
+        if (!canHostOnTop(host))
+            continue;
+        if (args.hitTest && !args.hitTest(host, args.point))
+            continue;
+        return host;
+    }
+    return null;
+}
+/**
+ * Convenience: clamps a Y coordinate to the top of a host surface, when one
+ * is declared. Returns the original Y if the host has no top surface.
+ */
+export function clampYToHostTop(host, originalY) {
+    const top = getTopSurfaceHeight(host);
+    return top == null ? originalY : top;
+}

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

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

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

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

package/dist/services/hosting.test.js

@@ -0,0 +1,230 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+import { nodeRegistry, registerNode } from '../registry/registry';
+import { canAttach, canHostOnTop, clampYToHostTop, getSurface, getTopSurfaceHeight, MAX_HOST_DEPTH, pickHost, } from './hosting';
+const id = (s) => s;
+function makeItem(idStr, attachTo) {
+    return {
+        id: id(idStr),
+        type: 'item',
+        parentId: null,
+        visible: true,
+        asset: attachTo ? { attachTo } : {},
+    };
+}
+function makeDef(kind, capabilities = {}, overrides = {}) {
+    return {
+        kind,
+        schemaVersion: 1,
+        schema: z.object({ type: z.literal(kind) }),
+        category: 'utility',
+        defaults: () => ({}),
+        capabilities,
+        renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+        ...overrides,
+    };
+}
+function makeNode(kind, idStr, parentId = null) {
+    return {
+        id: id(idStr),
+        type: kind,
+        parentId: parentId ? id(parentId) : null,
+        visible: true,
+    };
+}
+function makeFakeScene(nodes) {
+    return {
+        get: ((nid) => nodes[nid]),
+        nodes: () => nodes,
+        update: () => { },
+        upsert: () => id(''),
+        delete: () => { },
+        restore: () => { },
+        restoreAll: () => { },
+        markDirty: () => { },
+        pauseHistory: () => { },
+        resumeHistory: () => { },
+        getSubtree: () => null,
+        cloneNodesInto: () => null,
+    };
+}
+describe('canAttach', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('rejects self-host', () => {
+        const scene = makeFakeScene({ a: makeNode('thing', 'a') });
+        const result = canAttach(id('a'), id('a'), scene);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.kind).toBe('self-host');
+    });
+    test('rejects missing host', () => {
+        const scene = makeFakeScene({ a: makeNode('thing', 'a') });
+        const result = canAttach(id('a'), id('missing'), scene);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.kind).toBe('host-missing');
+    });
+    test('detects cycle when host is a descendant of child', () => {
+        // child=a, host=b, b's parent chain leads back to a → cycle.
+        const scene = makeFakeScene({
+            a: makeNode('thing', 'a'),
+            b: makeNode('thing', 'b', 'c'),
+            c: makeNode('thing', 'c', 'a'), // c.parent = a, b.parent = c → cycle if a → b
+        });
+        const result = canAttach(id('a'), id('b'), scene);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.kind).toBe('cycle');
+    });
+    test('rejects when chain would exceed MAX_HOST_DEPTH', () => {
+        const nodes = {};
+        for (let i = 0; i <= MAX_HOST_DEPTH; i++) {
+            nodes[`n${i}`] = makeNode('thing', `n${i}`, i === 0 ? null : `n${i - 1}`);
+        }
+        // n6 is already MAX_HOST_DEPTH deep — attaching n_new beneath it would
+        // push the child to MAX_HOST_DEPTH + 1.
+        nodes.candidate = makeNode('thing', 'candidate');
+        const scene = makeFakeScene(nodes);
+        const result = canAttach(id('candidate'), id(`n${MAX_HOST_DEPTH}`), scene);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.kind).toBe('depth-exceeded');
+    });
+    test('accepts attach when chain stays within MAX_HOST_DEPTH', () => {
+        const scene = makeFakeScene({
+            root: makeNode('thing', 'root'),
+            candidate: makeNode('thing', 'candidate'),
+        });
+        expect(canAttach(id('candidate'), id('root'), scene).ok).toBe(true);
+    });
+    test('rejects host kind not in child def.hostable.parents', () => {
+        registerNode(makeDef('shelf', { hostable: { parents: ['wall', 'slab'] } }));
+        const scene = makeFakeScene({
+            s: makeNode('shelf', 's'),
+            ceiling: makeNode('ceiling', 'ceiling'),
+        });
+        const result = canAttach(id('s'), id('ceiling'), scene);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.kind).toBe('kind-not-allowed');
+    });
+    test('accepts when host kind is in parents', () => {
+        registerNode(makeDef('shelf', { hostable: { parents: ['wall', 'slab'] } }));
+        const scene = makeFakeScene({
+            s: makeNode('shelf', 's'),
+            w: makeNode('wall', 'w'),
+        });
+        expect(canAttach(id('s'), id('w'), scene).ok).toBe(true);
+    });
+    test('no def or no hostable.parents = no kind restriction', () => {
+        // Some kinds (e.g. items via catalog) defer to runtime checks instead of
+        // declaring parents up front. canAttach should not block them.
+        const scene = makeFakeScene({
+            i: makeNode('item', 'i'),
+            w: makeNode('wall', 'w'),
+        });
+        expect(canAttach(id('i'), id('w'), scene).ok).toBe(true);
+    });
+    test('allows missing child (placement preview before commit)', () => {
+        const scene = makeFakeScene({ w: makeNode('wall', 'w') });
+        expect(canAttach(id('future-child'), id('w'), scene).ok).toBe(true);
+    });
+});
+describe('getSurface / getTopSurfaceHeight', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('returns null when host has no registered def', () => {
+        const node = makeNode('mystery', 'm');
+        expect(getSurface(node)).toBeNull();
+        expect(getTopSurfaceHeight(node)).toBeNull();
+    });
+    test('returns surface config when declared', () => {
+        registerNode(makeDef('table', {
+            surfaces: { top: { height: 0.74 } },
+        }));
+        const t = makeNode('table', 't');
+        expect(getSurface(t)?.top?.height).toBe(0.74);
+        expect(getTopSurfaceHeight(t)).toBe(0.74);
+    });
+    test('evaluates function-valued height with the node', () => {
+        registerNode(makeDef('shelf', {
+            surfaces: {
+                top: {
+                    height: (n) => (n.id === id('high') ? 1.8 : 0.3),
+                },
+            },
+        }));
+        expect(getTopSurfaceHeight(makeNode('shelf', 'high'))).toBe(1.8);
+        expect(getTopSurfaceHeight(makeNode('shelf', 'low'))).toBe(0.3);
+    });
+});
+describe('clampYToHostTop', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('clamps to top when host has one', () => {
+        registerNode(makeDef('table', { surfaces: { top: { height: 0.74 } } }));
+        expect(clampYToHostTop(makeNode('table', 't'), 5)).toBe(0.74);
+    });
+    test('passes through when host has no top surface', () => {
+        registerNode(makeDef('plain'));
+        expect(clampYToHostTop(makeNode('plain', 'p'), 5)).toBe(5);
+    });
+});
+describe('pickHost', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('returns first candidate that has hostable capability', () => {
+        registerNode(makeDef('slab', { hostable: { parents: ['*'] } }));
+        registerNode(makeDef('item')); // no hostable
+        const candidates = [makeNode('item', 'i'), makeNode('slab', 's')];
+        const picked = pickHost({
+            point: [0, 0, 0],
+            candidates,
+            placedKind: 'chair',
+        });
+        expect(picked?.id).toBe(id('s'));
+    });
+    test('returns null when nothing in candidates is hostable', () => {
+        registerNode(makeDef('item'));
+        const candidates = [makeNode('item', 'i')];
+        expect(pickHost({ point: [0, 0, 0], candidates, placedKind: 'chair' })).toBeNull();
+    });
+    test('hitTest can reject hostable candidates', () => {
+        registerNode(makeDef('slab', { hostable: { parents: ['*'] } }));
+        const candidates = [makeNode('slab', 's1'), makeNode('slab', 's2')];
+        const picked = pickHost({
+            point: [0, 0, 0],
+            candidates,
+            placedKind: 'chair',
+            hitTest: (host) => host.id === id('s2'),
+        });
+        expect(picked?.id).toBe(id('s2'));
+    });
+    test('excludes ceiling-mounted hosts (ceiling fan cannot be a top surface)', () => {
+        registerNode(makeDef('item', { hostable: { parents: ['*'] } }));
+        const candidates = [makeItem('fan', 'ceiling'), makeItem('table')];
+        const picked = pickHost({ point: [0, 0, 0], candidates, placedKind: 'item' });
+        expect(picked?.id).toBe(id('table'));
+    });
+    test('keeps wall-mounted hosts (wall shelf still hosts)', () => {
+        registerNode(makeDef('item', { hostable: { parents: ['*'] } }));
+        const candidates = [makeItem('shelf', 'wall')];
+        const picked = pickHost({ point: [0, 0, 0], candidates, placedKind: 'item' });
+        expect(picked?.id).toBe(id('shelf'));
+    });
+});
+describe('canHostOnTop', () => {
+    test('rejects ceiling-attachTo hosts', () => {
+        expect(canHostOnTop(makeItem('fan', 'ceiling'))).toBe(false);
+    });
+    test('accepts wall / wall-side / floor (undefined) hosts', () => {
+        expect(canHostOnTop(makeItem('shelf', 'wall'))).toBe(true);
+        expect(canHostOnTop(makeItem('sconce', 'wall-side'))).toBe(true);
+        expect(canHostOnTop(makeItem('table'))).toBe(true);
+    });
+});

package/dist/services/index.d.ts

@@ -0,0 +1,13 @@
+export { type AlignmentAnchor, type AlignmentGuide, type AlignmentGuideAxis, type AnchorKind, type BuildingPose, bboxAnchors, bboxCornerAnchors, type ResolveAlignmentInBuildingResult, type ResolveAlignmentInput, type ResolveAlignmentResult, resolveAlignment, resolveAlignmentInBuildingWorld, } from './alignment';
+export { collectAlignmentAnchors, type FootprintAABB, footprintAABB, footprintAABBAt, footprintAABBFrom, movingAlignmentAnchors, movingFootprintAnchors, nodeAlignmentAnchors, polygonAnchors, wallSegmentAnchors, } from './alignment-anchors';
+export { createDragSession, type DragSession, type DragSessionInput, type DragSessionOptions, } from './drag-session';
+export { type AttachError, type AttachResult, canAttach, canHostOnTop, clampYToHostTop, getSurface, getTopSurfaceHeight, MAX_HOST_DEPTH, pickHost, type Vec3, } from './hosting';
+export { DEFAULT_LEVEL_HEIGHT, getCeilingAt, getCeilingHeightAt, getLevelHeight, } from './level-height';
+export { type AxisLock, applyAxisLock, isMovable, movePlanToward, moveToward, resolveMovable, } from './movement';
+export { type AlongWallAlignment, type AlongWallFeature, computeEdgeGaps, computeOpeningGuides, DEFAULT_OPENING_GUIDE_TOLERANCES, detectAlongWallAlignment, detectEqualSpacing, detectVerticalAlignment, type EdgeGap, type EqualSpacingRun, type OpeningGuideInput, type OpeningGuides, type OpeningGuideTolerances, type OpeningSpan, type SillHeadGuide, type VerticalAlignment, type VerticalFeature, type WallExtent, } from './opening-guides';
+export { analyzePortConnectivity, type PortConnection, type PortConnectivity, resolveConnectivityUpdates, } from './port-connectivity';
+export { buildRiserDiagram, projectIso, type RiserDiagram, type RiserLine, type RiserMarker, } from './riser-diagram';
+export { DEFAULT_ANGLE_STEP, DEFAULT_GRID_STEP, type SnapServices, snapAngleToList, snapPointAlongAngleRay, snapPointToAngle, snapPointToGrid, snapScalar, snapServices, snapVec3ToGrid, snapWorldXZToBuildingLocal, } from './snap';
+export { buildPortComponents, type SystemSummary, summarizeSystemFor, } from './system-graph';
+export { type DwvFinding, type DwvSeverity, validateDwv, } from './validate-dwv';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,WAAW,EACX,iBAAiB,EACjB,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,+BAA+B,GAChC,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,SAAS,EACT,YAAY,EACZ,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,QAAQ,EACR,KAAK,IAAI,GACV,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,QAAQ,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,eAAe,EACf,oBAAoB,EACpB,gCAAgC,EAChC,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,YAAY,EACjB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,0BAA0B,GAC3B,MAAM,QAAQ,CAAA;AACf,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,WAAW,GACZ,MAAM,gBAAgB,CAAA"}

package/dist/services/index.js

@@ -0,0 +1,12 @@
+export { bboxAnchors, bboxCornerAnchors, resolveAlignment, resolveAlignmentInBuildingWorld, } from './alignment';
+export { collectAlignmentAnchors, footprintAABB, footprintAABBAt, footprintAABBFrom, movingAlignmentAnchors, movingFootprintAnchors, nodeAlignmentAnchors, polygonAnchors, wallSegmentAnchors, } from './alignment-anchors';
+export { createDragSession, } from './drag-session';
+export { canAttach, canHostOnTop, clampYToHostTop, getSurface, getTopSurfaceHeight, MAX_HOST_DEPTH, pickHost, } from './hosting';
+export { DEFAULT_LEVEL_HEIGHT, getCeilingAt, getCeilingHeightAt, getLevelHeight, } from './level-height';
+export { applyAxisLock, isMovable, movePlanToward, moveToward, resolveMovable, } from './movement';
+export { computeEdgeGaps, computeOpeningGuides, DEFAULT_OPENING_GUIDE_TOLERANCES, detectAlongWallAlignment, detectEqualSpacing, detectVerticalAlignment, } from './opening-guides';
+export { analyzePortConnectivity, resolveConnectivityUpdates, } from './port-connectivity';
+export { buildRiserDiagram, projectIso, } from './riser-diagram';
+export { DEFAULT_ANGLE_STEP, DEFAULT_GRID_STEP, snapAngleToList, snapPointAlongAngleRay, snapPointToAngle, snapPointToGrid, snapScalar, snapServices, snapVec3ToGrid, snapWorldXZToBuildingLocal, } from './snap';
+export { buildPortComponents, summarizeSystemFor, } from './system-graph';
+export { validateDwv, } from './validate-dwv';

package/dist/services/level-height.d.ts

@@ -0,0 +1,28 @@
+import type { CeilingNode } from '../schema';
+import type { AnyNode, AnyNodeId } from '../schema/types';
+export declare const DEFAULT_LEVEL_HEIGHT = 2.5;
+/**
+ * Optional resolver for a wall's rendered base Y (mesh elevation).
+ *
+ * `packages/core` is pure domain logic and must not read viewer/Three.js
+ * state (see AGENTS.md “Layer Boundaries”). Callers that legitimately have
+ * registry access (viewer systems, node tools) may pass a resolver so the
+ * mesh elevation is factored in; pure/headless callers (MCP, tests, server)
+ * omit it and get a deterministic result from serialized node data alone.
+ */
+export type WallBaseYResolver = (wallId: AnyNodeId) => number | undefined;
+export declare function getLevelHeight(levelId: string, nodes: Record<AnyNodeId, AnyNode>, resolveWallBaseY?: WallBaseYResolver): number;
+/**
+ * The ceiling covering level-local point `[x, z]`, or `null` when none
+ * sits over it. Points inside a ceiling's hole are treated as uncovered.
+ * When ceilings overlap, the lowest one wins — that's the surface a duct
+ * would actually hang from.
+ */
+export declare function getCeilingAt(levelId: string, nodes: Record<AnyNodeId, AnyNode>, x: number, z: number): CeilingNode | null;
+/**
+ * Underside elevation (meters above the level floor) of the ceiling
+ * covering level-local point `[x, z]`, or `null` when no ceiling sits
+ * over that point. See {@link getCeilingAt}.
+ */
+export declare function getCeilingHeightAt(levelId: string, nodes: Record<AnyNodeId, AnyNode>, x: number, z: number): number | null;
+//# sourceMappingURL=level-height.d.ts.map

package/dist/services/level-height.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level-height.d.ts","sourceRoot":"","sources":["../../src/services/level-height.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,WAAW,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEzD,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,CAAA;AAEzE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,MAAM,CAqBR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,WAAW,GAAG,IAAI,CAepB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EACjC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAGf"}

package/dist/services/level-height.js

@@ -0,0 +1,62 @@
+import { pointInPolygon } from '../hooks/spatial-grid/spatial-grid-manager';
+export const DEFAULT_LEVEL_HEIGHT = 2.5;
+export function getLevelHeight(levelId, nodes, resolveWallBaseY) {
+    const level = nodes[levelId];
+    if (!level)
+        return DEFAULT_LEVEL_HEIGHT;
+    let maxTop = 0;
+    for (const childId of level.children) {
+        const child = nodes[childId];
+        if (!child)
+            continue;
+        if (child.type === 'ceiling') {
+            const ch = child.height ?? DEFAULT_LEVEL_HEIGHT;
+            if (ch > maxTop)
+                maxTop = ch;
+        }
+        else if (child.type === 'wall') {
+            let baseY = resolveWallBaseY?.(childId) ?? 0;
+            if (baseY < 0)
+                baseY = 0;
+            const top = baseY + (child.height ?? DEFAULT_LEVEL_HEIGHT);
+            if (top > maxTop)
+                maxTop = top;
+        }
+    }
+    return maxTop > 0 ? maxTop : DEFAULT_LEVEL_HEIGHT;
+}
+/**
+ * The ceiling covering level-local point `[x, z]`, or `null` when none
+ * sits over it. Points inside a ceiling's hole are treated as uncovered.
+ * When ceilings overlap, the lowest one wins — that's the surface a duct
+ * would actually hang from.
+ */
+export function getCeilingAt(levelId, nodes, x, z) {
+    const level = nodes[levelId];
+    if (!level)
+        return null;
+    let best = null;
+    for (const childId of level.children) {
+        const child = nodes[childId];
+        if (child?.type !== 'ceiling')
+            continue;
+        const ceiling = child;
+        if (ceiling.polygon.length < 3 || !pointInPolygon(x, z, ceiling.polygon))
+            continue;
+        if (ceiling.holes.some((hole) => hole.length >= 3 && pointInPolygon(x, z, hole)))
+            continue;
+        const h = ceiling.height ?? DEFAULT_LEVEL_HEIGHT;
+        if (best === null || h < (best.height ?? DEFAULT_LEVEL_HEIGHT))
+            best = ceiling;
+    }
+    return best;
+}
+/**
+ * Underside elevation (meters above the level floor) of the ceiling
+ * covering level-local point `[x, z]`, or `null` when no ceiling sits
+ * over that point. See {@link getCeilingAt}.
+ */
+export function getCeilingHeightAt(levelId, nodes, x, z) {
+    const ceiling = getCeilingAt(levelId, nodes, x, z);
+    return ceiling ? (ceiling.height ?? DEFAULT_LEVEL_HEIGHT) : null;
+}

package/dist/services/movement.d.ts

@@ -0,0 +1,48 @@
+import type { MovableConfig } from '../registry/types';
+import type { AnyNode } from '../schema/types';
+import { type Vec3 } from './snap';
+/**
+ * Pure movement constraint helpers. Given a node and a target position, apply
+ * the constraints declared in `def.capabilities.movable` (axis lock, grid
+ * snap, override callback) and return the constrained target.
+ *
+ * No scene access, no React, no Three.js — caller passes the node, this
+ * returns the math result.
+ */
+export type AxisLock = ReadonlyArray<'x' | 'y' | 'z'>;
+/**
+ * Returns the MovableConfig effective for `node` after running its `override`
+ * callback if declared. Returns `null` if the node's def doesn't declare
+ * `movable` (i.e. the node is not movable).
+ */
+export declare function resolveMovable(node: AnyNode): MovableConfig | null;
+/**
+ * Projects a target X/Y/Z onto the axes a node is allowed to move on. Components
+ * outside the lock fall back to the node's current values, so caller-supplied
+ * positions can come from any 3D source without breaking axis-locked motion.
+ */
+export declare function applyAxisLock(current: Vec3, target: Vec3, axes: AxisLock): Vec3;
+/**
+ * Top-level helper: takes a node and a desired position, returns the position
+ * filtered through the node's movable capability (axis lock + optional grid
+ * snap). Returns `null` when the node is not movable.
+ */
+export declare function moveToward(node: AnyNode, current: Vec3, target: Vec3, options?: {
+    gridStep?: number;
+    gridSnap?: boolean;
+}): Vec3 | null;
+/**
+ * 2D convenience: same as moveToward but for plan-view (X/Z) operations like
+ * floor placement. Returns a tuple in the X/Z plane so callers don't have to
+ * pack/unpack the dropped Y.
+ */
+export declare function movePlanToward(node: AnyNode, currentY: number, current: readonly [number, number], target: readonly [number, number], options?: {
+    gridStep?: number;
+    gridSnap?: boolean;
+}): readonly [number, number] | null;
+/**
+ * Returns true when a node's def declares it as movable on any axis.
+ * Quick predicate for tools/UI that gate on movability.
+ */
+export declare function isMovable(node: AnyNode): boolean;
+//# sourceMappingURL=movement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"movement.d.ts","sourceRoot":"","sources":["../../src/services/movement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElD;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CASlE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,IAAI,EACb,MAAM,EAAE,IAAI,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,IAAI,GAAG,IAAI,CAYb;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CASlC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAGhD"}