@pascal-app/core 0.7.0 → 0.9.1

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'));
+    });
+});

package/dist/services/hosting.d.ts

@@ -0,0 +1,80 @@
+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;
+/**
+ * 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,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,CAajB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxE"}