@pascal-app/core 1.0.0 → 1.0.3

package/dist/services/surface-hosting.d.ts

@@ -0,0 +1,92 @@
+import type { AnyNodeDefinition, SceneApi } from '../registry/types.js';
+import type { AnyNode } from '../schema/types.js';
+export type SurfaceId = string;
+export interface SurfaceRegion {
+    kind: 'rect' | 'polygon';
+    /** Rectangle half-extents in the surface frame's XZ plane. */
+    size?: readonly [number, number];
+    center?: readonly [number, number];
+    /** Counterclockwise boundary in the surface frame's XZ plane. */
+    points?: readonly (readonly [number, number])[];
+    holes?: readonly (readonly (readonly [number, number])[])[];
+}
+interface SurfaceFrame {
+    label?: string;
+    position: readonly [number, number, number];
+    rotation?: readonly [number, number, number];
+    normal: readonly [number, number, number];
+    /** Defaults to true; the caller's snap function still controls whether the grid is active. */
+    gridSnap?: boolean;
+}
+export type DeclaredHostSurface = SurfaceFrame & {
+    id: SurfaceId;
+    region: SurfaceRegion;
+};
+export type HostSurface = DeclaredHostSurface | (SurfaceFrame & {
+    id: null;
+    region?: never;
+});
+export interface SurfaceHit {
+    point: readonly [number, number, number];
+    normalWorldY: number;
+    meshName?: string;
+}
+export interface SurfaceContext {
+    scene: Pick<SceneApi, 'get' | 'nodes'>;
+}
+export interface SurfaceProvider {
+    childFrame: 'host-local' | 'surface-local';
+    surfaces?(host: AnyNode, ctx: SurfaceContext): readonly DeclaredHostSurface[];
+    resolveHit(host: AnyNode, hit: SurfaceHit, ctx: SurfaceContext): HostSurface | null;
+    accepts?(host: AnyNode, childKind: string, surface: HostSurface, ctx: SurfaceContext): boolean;
+}
+export type SurfaceRejectReason = 'host-not-eligible' | 'invalid-hit' | 'no-surface' | 'child-not-accepted' | 'footprint-outside-surface' | 'footprint-exceeds-host' | 'surface-cutout' | 'surface-occupied';
+export type SurfacePlacement = {
+    position: readonly [number, number, number];
+    rotationY: number;
+    surfaceId: SurfaceId | null;
+    /** Movers write surfaceLocal for surface-local providers, otherwise the host-local pose. */
+    childFrame: SurfaceProvider['childFrame'];
+    /** Null exactly for hit-derived surfaces. Full XYZ rotation is needed on tilted surfaces. */
+    surfaceLocal: {
+        position: readonly [number, number, number];
+        rotationY: number;
+        rotation: readonly [number, number, number];
+    } | null;
+};
+export declare const NON_PHYSICAL_HOST_KINDS: readonly string[];
+export declare const hitDerivedSurfaceProvider: SurfaceProvider;
+export declare const itemSurfaceProvider: SurfaceProvider;
+export declare const shelfSurfaceProvider: SurfaceProvider;
+export declare const proceduralItemSurfaceProvider: SurfaceProvider;
+export declare function getSurfaceProvider(host: AnyNode): SurfaceProvider;
+export declare function rendersHostedChildren(def: AnyNodeDefinition): boolean;
+export declare function canHostSurfaceChild(host: AnyNode, childKind: string, childId?: string): boolean;
+/** Hit and child rotation are host-local; bounds and dimensions are scaled child-local values. */
+export declare function resolveSurfacePlacement(args: {
+    host: AnyNode;
+    surface?: HostSurface;
+    childKind: string;
+    childId?: string;
+    childFootprint: {
+        size: readonly [number, number, number];
+        rotationY: number;
+        /** Full host-local XYZ Euler rotation, when available; otherwise rotationY is used. */
+        rotation?: readonly [number, number, number];
+        localBounds?: {
+            min: readonly [number, number, number];
+            max: readonly [number, number, number];
+        };
+    };
+    hit: SurfaceHit;
+    /** Child origin after grab-offset correction; the hit still elects the actual support. */
+    origin?: readonly [number, number, number];
+    scene: SceneApi;
+    /** Pure child-centered grid function; omitted means snapping is off. */
+    snapScalar?: (position: number, dimension: number) => number;
+    /** Defaults to true; drag previews may skip fit while still enforcing host and child eligibility. */
+    checkFootprint?: boolean;
+    onReject?: (reason: SurfaceRejectReason) => void;
+}): SurfacePlacement | null;
+export {};
+//# sourceMappingURL=surface-hosting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surface-hosting.d.ts","sourceRoot":"","sources":["../../src/services/surface-hosting.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,iBAAiB,CAAA;AAKzD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,iEAAiE;IACjE,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAA;IAC/C,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;CAC5D;AAED,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5C,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AACzF,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,CAAC,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAA;AAE7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,OAAO,CAAC,CAAA;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,YAAY,GAAG,eAAe,CAAA;IAC1C,QAAQ,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,SAAS,mBAAmB,EAAE,CAAA;IAC7E,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,cAAc,GAAG,WAAW,GAAG,IAAI,CAAA;IACnF,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAA;CAC/F;AAED,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,aAAa,GACb,YAAY,GACZ,oBAAoB,GACpB,2BAA2B,GAC3B,wBAAwB,GACxB,gBAAgB,GAChB,kBAAkB,CAAA;AAEtB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAC3B,4FAA4F;IAC5F,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAA;IACzC,6FAA6F;IAC7F,YAAY,EAAE;QACZ,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QAC3C,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAC5C,GAAG,IAAI,CAAA;CACT,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAapD,CAAA;AAID,eAAO,MAAM,yBAAyB,EAAE,eAOvC,CAAA;AAED,eAAO,MAAM,mBAAmB,EAAE,eAcjC,CAAA;AA0BD,eAAO,MAAM,oBAAoB,EAAE,eAQlC,CAAA;AAiDD,eAAO,MAAM,6BAA6B,EAAE,eAe3C,CAAA;AAQD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAGjE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAIrE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAiB/F;AA0BD,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE;QACd,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QACvC,SAAS,EAAE,MAAM,CAAA;QACjB,uFAAuF;QACvF,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QAC5C,WAAW,CAAC,EAAE;YAAE,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YAAC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KACjG,CAAA;IACD,GAAG,EAAE,UAAU,CAAA;IACf,0FAA0F;IAC1F,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,KAAK,EAAE,QAAQ,CAAA;IACf,wEAAwE;IACxE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5D,qGAAqG;IACrG,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAA;CACjD,GAAG,gBAAgB,GAAG,IAAI,CAuK1B"}

package/dist/services/surface-hosting.js

@@ -0,0 +1,305 @@
+import { attachmentBounds, attachmentRegionsOverlap, isProceduralItem, } from '../procedural-items/query.js';
+import { evaluateRecipe } from '../procedural-items/recipe.js';
+import { boundsOf, boxCorners, frame, transformPoint } from '../procedural-items/spatial.js';
+import { nodeRegistry } from '../registry/registry.js';
+import { getScaledDimensions, isLowProfileItemSurface } from '../schema/nodes/item.js';
+import { canHostOnTop, wouldCreateHostingCycle } from './hosting.js';
+import { shelfRowBoardDimensions } from './shelf-board.js';
+import { surfaceRegionContainsFootprint, surfaceRegionContainsPoint } from './surface-region.js';
+export const NON_PHYSICAL_HOST_KINDS = [
+    'guide',
+    'measurement',
+    'scan',
+    'construction-dimension',
+    'lineset',
+    'structural-grid',
+    'spawn',
+    'zone',
+    'unit',
+    'site',
+    'building',
+    'level',
+];
+const UPWARD_SURFACE_NORMAL_MIN_Y = 0.75;
+export const hitDerivedSurfaceProvider = {
+    childFrame: 'host-local',
+    resolveHit(_host, hit) {
+        if (!(hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y) || !hit.point.every(Number.isFinite))
+            return null;
+        return { id: null, position: hit.point, normal: [0, 1, 0], gridSnap: true };
+    },
+};
+export const itemSurfaceProvider = {
+    childFrame: 'host-local',
+    resolveHit(host, hit) {
+        if (host.type !== 'item' || !canHostOnTop(host) || isLowProfileItemSurface(host))
+            return null;
+        if (!(hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y) || !hit.point.every(Number.isFinite))
+            return null;
+        const height = host.asset.surface ? host.asset.surface.height * host.scale[1] : hit.point[1];
+        return {
+            id: null,
+            position: [hit.point[0], height, hit.point[2]],
+            normal: [0, 1, 0],
+            gridSnap: true,
+        };
+    },
+};
+function nearestSurface(surfaces, localY) {
+    let best = surfaces[0] ?? null;
+    for (const surface of surfaces.slice(1)) {
+        if (best && Math.abs(surface.position[1] - localY) < Math.abs(best.position[1] - localY))
+            best = surface;
+    }
+    return best;
+}
+function shelfSurfaces(host) {
+    if (host.type !== 'shelf')
+        return [];
+    return (nodeRegistry.get(host.type)?.capabilities.surfaces?.custom?.(host) ?? []).map((surface, index) => {
+        const [width, , depth] = shelfRowBoardDimensions(host, surface.position[1]);
+        return {
+            ...surface,
+            id: `row:${index}`,
+            gridSnap: true,
+            region: { kind: 'rect', size: [width / 2, depth / 2] },
+        };
+    });
+}
+export const shelfSurfaceProvider = {
+    childFrame: 'host-local',
+    surfaces: shelfSurfaces,
+    resolveHit(host, hit) {
+        if (!(hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y) || !hit.point.every(Number.isFinite))
+            return null;
+        return nearestSurface(shelfSurfaces(host), hit.point[1]);
+    },
+};
+const proceduralSurfaceCache = new WeakMap();
+function proceduralSurfaces(host) {
+    if (!isProceduralItem(host))
+        return [];
+    // Include contents as well as identity so in-place parameter/recipe edits cannot leave stale surfaces.
+    const key = JSON.stringify([host.recipe, host.parameters]);
+    const cached = proceduralSurfaceCache.get(host.recipe);
+    if (cached?.key === key)
+        return cached.surfaces;
+    const surfaces = evaluateRecipe(host.recipe, host.parameters).surfaces.map((surface) => ({
+        id: surface.id,
+        label: surface.label,
+        position: surface.position,
+        rotation: surface.rotation,
+        normal: surface.normal,
+        gridSnap: true,
+        region: { kind: 'rect', size: [surface.size[0] / 2, surface.size[1] / 2] },
+    }));
+    proceduralSurfaceCache.set(host.recipe, { key, surfaces });
+    return surfaces;
+}
+function surfaceLocalPoint(surface, point) {
+    const delta = point.map((v, i) => v - surface.position[i]);
+    return frame([0, 0, 0], [...(surface.rotation ?? [0, 0, 0])]).axes.map((axis) => axis.reduce((sum, v, i) => sum + v * delta[i], 0));
+}
+function surfaceLocalRotation(surface, rotation) {
+    const surfaceRotation = surface.rotation ?? [0, 0, 0];
+    // Preserve unwrapped yaw exactly for the common horizontal, yaw-only case.
+    if (!surfaceRotation[0] && !surfaceRotation[2] && !rotation[0] && !rotation[2])
+        return [0, rotation[1] - surfaceRotation[1], 0];
+    const axes = frame([0, 0, 0], rotation).axes.map((axis) => surfaceLocalPoint({ ...surface, position: [0, 0, 0] }, axis));
+    const y = Math.asin(Math.max(-1, Math.min(1, axes[2][0])));
+    return Math.abs(axes[2][0]) < 0.9999999
+        ? [Math.atan2(-axes[2][1], axes[2][2]), y, Math.atan2(-axes[1][0], axes[0][0])]
+        : [Math.atan2(axes[1][2], axes[1][1]), y, 0];
+}
+export const proceduralItemSurfaceProvider = {
+    childFrame: 'surface-local',
+    surfaces: proceduralSurfaces,
+    resolveHit(host, hit) {
+        if (!(hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y) || !hit.point.every(Number.isFinite))
+            return null;
+        const candidates = proceduralSurfaces(host).filter((surface) => {
+            const point = surfaceLocalPoint(surface, hit.point);
+            return (surface.normal[1] >= UPWARD_SURFACE_NORMAL_MIN_Y &&
+                surfaceRegionContainsPoint(surface.region, [point[0], point[2]]));
+        });
+        return nearestSurface(candidates, hit.point[1]);
+    },
+};
+const adapters = new Map([
+    ['item', itemSurfaceProvider],
+    ['shelf', shelfSurfaceProvider],
+    ['procedural-item', proceduralItemSurfaceProvider],
+]);
+export function getSurfaceProvider(host) {
+    const declaration = nodeRegistry.get(host.type)?.capabilities.surfaces;
+    return declaration?.hosting || adapters.get(host.type) || hitDerivedSurfaceProvider;
+}
+export function rendersHostedChildren(def) {
+    return def.renderer
+        ? def.renderer.kind === 'parametric' && def.rendersChildren !== false
+        : !!def.geometry;
+}
+export function canHostSurfaceChild(host, childKind, childId) {
+    const def = nodeRegistry.get(host.type);
+    if (!def ||
+        NON_PHYSICAL_HOST_KINDS.includes(host.type) ||
+        def.capabilities.surfaces?.hosting === false ||
+        nodeRegistry.get(childKind)?.capabilities.surfacePlacement === 'floor-only' ||
+        !rendersHostedChildren(def))
+        return false;
+    const generated = childId
+        ? undefined
+        : nodeRegistry.get(childKind)?.schema.shape.id?.safeParse(undefined);
+    const id = childId ?? (generated?.success ? generated.data : undefined);
+    if (typeof id !== 'string')
+        return false;
+    const parsed = def.schema.shape.children?.safeParse([id]);
+    return parsed?.success === true && Array.isArray(parsed.data) && parsed.data.includes(id);
+}
+function hostRegion(host, ctx) {
+    const capabilities = nodeRegistry.get(host.type)?.capabilities;
+    const evaluated = isProceduralItem(host) ? evaluateRecipe(host.recipe, host.parameters) : null;
+    const bounds = capabilities?.dragBounds?.(host, ctx.scene.nodes()) ??
+        (evaluated
+            ? {
+                size: evaluated.dimensions,
+                center: evaluated.min.map((v, i) => (v + evaluated.max[i]) / 2),
+            }
+            : undefined);
+    const size = host.type === 'item'
+        ? getScaledDimensions(host)
+        : (bounds?.size ??
+            capabilities?.floorPlaced?.footprint?.(host, { nodes: ctx.scene.nodes() }).dimensions);
+    if (!size)
+        return undefined;
+    return {
+        kind: 'rect',
+        size: [size[0] / 2, size[2] / 2],
+        center: bounds?.center ? [bounds.center[0], bounds.center[2]] : [0, 0],
+    };
+}
+/** Hit and child rotation are host-local; bounds and dimensions are scaled child-local values. */
+export function resolveSurfacePlacement(args) {
+    const { host, hit, childKind, childFootprint } = args;
+    if (args.childId && wouldCreateHostingCycle(args.childId, host, args.scene))
+        return null;
+    // Defer without a refusal so the paired grid event can place on floor support.
+    if (!canHostOnTop(host) || !canHostSurfaceChild(host, childKind, args.childId))
+        return null;
+    const reject = (reason) => {
+        args.onReject?.(reason);
+        return null;
+    };
+    if (!hit.point.every(Number.isFinite))
+        return reject('invalid-hit');
+    const ctx = { scene: args.scene };
+    const provider = getSurfaceProvider(host);
+    const poseFor = (surface) => {
+        const declaredId = surface.id;
+        if (declaredId !== null && !surface.region) {
+            throw new Error(`Declared surface ${host.type}:${declaredId} must publish a region`);
+        }
+        const snap = (surface.gridSnap ?? true) ? args.snapScalar : undefined;
+        const origin = args.origin ?? hit.point;
+        const position = [
+            snap?.(origin[0], childFootprint.size[0]) ?? origin[0],
+            surface.position[1],
+            snap?.(origin[2], childFootprint.size[2]) ?? origin[2],
+        ];
+        const rotation = surfaceLocalRotation(surface, [
+            ...(childFootprint.rotation ?? [0, childFootprint.rotationY, 0]),
+        ]);
+        const localPosition = surfaceLocalPoint(surface, position);
+        if (surface.id !== null) {
+            const bounds = childFootprint.localBounds ?? {
+                min: [-childFootprint.size[0] / 2, 0, -childFootprint.size[2] / 2],
+                max: [
+                    childFootprint.size[0] / 2,
+                    childFootprint.size[1],
+                    childFootprint.size[2] / 2,
+                ],
+            };
+            localPosition[1] = -Math.min(...boxCorners([...bounds.min], [...bounds.max]).map((p) => transformPoint(frame([0, 0, 0], rotation), p)[1]));
+            // Intersect the host-local vertical cursor line with the support plane, then lift the child's bottom.
+            const normal = frame([0, 0, 0], [...(surface.rotation ?? [0, 0, 0])]).axes[1];
+            position[1] =
+                surface.position[1] +
+                    (localPosition[1] -
+                        normal[0] * (position[0] - surface.position[0]) -
+                        normal[2] * (position[2] - surface.position[2])) /
+                        normal[1];
+            const projected = surfaceLocalPoint(surface, position);
+            localPosition[0] = projected[0];
+            localPosition[2] = projected[2];
+        }
+        return {
+            position,
+            rotationY: childFootprint.rotationY,
+            surfaceId: surface.id,
+            childFrame: surface.id === null ? 'host-local' : provider.childFrame,
+            surfaceLocal: surface.id === null ? null : { position: localPosition, rotationY: rotation[1], rotation },
+        };
+    };
+    let surface = args.surface ?? provider.resolveHit(host, hit, ctx);
+    if (!surface && hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y) {
+        // Grab offsets and snapping can leave the pointer over a hole while the child's centre is supported.
+        surface = nearestSurface((provider.surfaces?.(host, ctx) ?? []).filter((candidate) => {
+            if (candidate.normal[1] < UPWARD_SURFACE_NORMAL_MIN_Y)
+                return false;
+            const proposal = poseFor(candidate).surfaceLocal;
+            return surfaceRegionContainsFootprint(candidate.region, proposal.position, childFootprint.size, proposal.rotation, childFootprint.localBounds);
+        }), hit.point[1]);
+    }
+    if (!surface && isProceduralItem(host)) {
+        const bounds = evaluateRecipe(host.recipe, host.parameters);
+        if (hit.point.every((value, axis) => value >= bounds.min[axis] - 1e-6 && value <= bounds.max[axis] + 1e-6))
+            surface = hitDerivedSurfaceProvider.resolveHit(host, hit, ctx);
+    }
+    if (!surface) {
+        const overCutout = hit.normalWorldY >= UPWARD_SURFACE_NORMAL_MIN_Y &&
+            provider.surfaces?.(host, ctx).some((candidate) => {
+                if (!candidate.region?.holes?.length)
+                    return false;
+                const local = surfaceLocalPoint(candidate, hit.point);
+                const point = [local[0], local[2]];
+                return (surfaceRegionContainsPoint({ ...candidate.region, holes: [] }, point) &&
+                    !surfaceRegionContainsPoint(candidate.region, point));
+            });
+        return reject(overCutout ? 'surface-cutout' : 'no-surface');
+    }
+    const pose = poseFor(surface);
+    const localPosition = pose.surfaceLocal?.position ?? [0, 0, 0];
+    const rotation = pose.surfaceLocal?.rotation ?? [0, childFootprint.rotationY, 0];
+    if (provider.accepts && !provider.accepts(host, childKind, surface, ctx)) {
+        return reject('child-not-accepted');
+    }
+    if (args.checkFootprint === false)
+        return pose;
+    if (surface.region) {
+        if (!surfaceRegionContainsFootprint(surface.region, localPosition, childFootprint.size, rotation, childFootprint.localBounds)) {
+            const insideOutline = surfaceRegionContainsFootprint({ ...surface.region, holes: [] }, localPosition, childFootprint.size, rotation, childFootprint.localBounds);
+            return reject(insideOutline ? 'surface-cutout' : 'footprint-outside-surface');
+        }
+    }
+    else {
+        if (!surfaceRegionContainsFootprint(hostRegion(host, ctx), pose.position, childFootprint.size, childFootprint.rotation ?? childFootprint.rotationY, childFootprint.localBounds))
+            return reject('footprint-exceeds-host');
+    }
+    if (isProceduralItem(host) && pose.surfaceId !== null && pose.surfaceLocal) {
+        const bounds = childFootprint.localBounds ?? {
+            min: [-childFootprint.size[0] / 2, 0, -childFootprint.size[2] / 2],
+            max: [childFootprint.size[0] / 2, childFootprint.size[1], childFootprint.size[2] / 2],
+        };
+        const proposal = boundsOf(boxCorners([...bounds.min], [...bounds.max]).map((point) => transformPoint(frame([...pose.surfaceLocal.position], [...pose.surfaceLocal.rotation]), point)));
+        for (const id of host.children) {
+            if (id === args.childId || host.attachments[id] !== pose.surfaceId)
+                continue;
+            const child = args.scene.get(id);
+            if (child &&
+                (isProceduralItem(child) || child.type === 'item') &&
+                attachmentRegionsOverlap(attachmentBounds(child), proposal))
+                return reject('surface-occupied');
+        }
+    }
+    return pose;
+}

package/dist/services/surface-region.d.ts

@@ -0,0 +1,8 @@
+import type { SurfaceRegion } from './surface-hosting.js';
+export declare function surfaceRegionContainsPoint(region: SurfaceRegion | undefined, point: readonly [number, number]): boolean;
+/** Position and XYZ rotation are surface-local; bounds and size are scaled child-local values. */
+export declare function surfaceRegionContainsFootprint(region: SurfaceRegion | undefined, position: readonly [number, number, number], size: readonly [number, number, number], rotation: number | readonly [number, number, number], localBounds?: {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}): boolean;
+//# sourceMappingURL=surface-region.d.ts.map

package/dist/services/surface-region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-region.d.ts","sourceRoot":"","sources":["../../src/services/surface-region.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAiBtD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAeT;AAED,kGAAkG;AAClG,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3C,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACpD,WAAW,CAAC,EAAE;IAAE,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC/F,OAAO,CAiBT"}

package/dist/services/surface-region.js

@@ -0,0 +1,44 @@
+import { pointInPolygon } from '../lib/polygon-relations.js';
+import { frame, transformPoint } from '../procedural-items/spatial.js';
+const EPSILON = 1e-6;
+function outline(region) {
+    if (region.kind === 'polygon')
+        return (region.points ?? []).map(([x, z]) => [x, z]);
+    if (!region.size)
+        return [];
+    const [x, z] = region.center ?? [0, 0];
+    const [w, d] = region.size;
+    return [
+        [x - w, z - d],
+        [x + w, z - d],
+        [x + w, z + d],
+        [x - w, z + d],
+    ];
+}
+export function surfaceRegionContainsPoint(region, point) {
+    if (!region)
+        return true;
+    return ((region.kind === 'rect'
+        ? !!region.size &&
+            Math.abs(point[0] - (region.center?.[0] ?? 0)) <= region.size[0] + EPSILON &&
+            Math.abs(point[1] - (region.center?.[1] ?? 0)) <= region.size[1] + EPSILON
+        : pointInPolygon([...point], outline(region))) &&
+        !(region.holes ?? []).some((hole) => pointInPolygon([...point], hole.map(([x, z]) => [x, z]))));
+}
+/** Position and XYZ rotation are surface-local; bounds and size are scaled child-local values. */
+export function surfaceRegionContainsFootprint(region, position, size, rotation, localBounds) {
+    if (!region)
+        return true;
+    const bounds = localBounds ?? {
+        min: [-size[0] / 2, 0, -size[2] / 2],
+        max: [size[0] / 2, size[1], size[2] / 2],
+    };
+    const childFrame = frame([...position], typeof rotation === 'number' ? [0, rotation, 0] : [...rotation]);
+    // A rotated box and its XZ projection are centrally symmetric, so their centre is the transformed bounds midpoint.
+    const center = transformPoint(childFrame, [
+        (bounds.min[0] + bounds.max[0]) / 2,
+        (bounds.min[1] + bounds.max[1]) / 2,
+        (bounds.min[2] + bounds.max[2]) / 2,
+    ]);
+    return surfaceRegionContainsPoint(region, [center[0], center[2]]);
+}

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

@@ -1,5 +1,5 @@
-import { type NodePort } from '../registry';
-import type { AnyNode, AnyNodeId } from '../schema';
+import { type NodePort } from '../registry/index.js';
+import type { AnyNode, AnyNodeId } from '../schema/index.js';
 export type SystemSummary = {
     /** Every node in this connected component. */
     nodeIds: AnyNodeId[];

package/dist/services/system-graph.js

@@ -1,5 +1,5 @@
-import { nodeRegistry } from '../registry';
-import { getLevelElevations } from './storey';
+import { nodeRegistry } from '../registry/index.js';
+import { getLevelElevations } from './storey.js';
 /**
  * The "System" primitive: connected components over the port graph.
  *

package/dist/services/validate-dwv.d.ts

@@ -1,4 +1,4 @@
-import type { AnyNode, AnyNodeId } from '../schema';
+import type { AnyNode, AnyNodeId } from '../schema/index.js';
 /**
  * IPC validators for the DWV (drain-waste-vent) system — the "CodeRule"
  * primitive from the domain brief. The slope, minimum-size, and

package/dist/services/validate-dwv.js

@@ -1,4 +1,4 @@
-import { buildPortComponents } from './system-graph';
+import { buildPortComponents } from './system-graph.js';
 /** IPC 704.1 minimum drainage slope (rise/run, dimensionless) by
  *  nominal pipe size: ¼"/ft (1:48) under 3", ⅛"/ft (1:96) for 3–6",
  *  1/16"/ft (1:192) at 8"+. */

package/dist/store/actions/node-actions.d.ts

@@ -1,5 +1,5 @@
-import { type AnyNode, type AnyNodeId } from '../../schema';
-import type { SceneState } from '../use-scene';
+import { type AnyNode, type AnyNodeId } from '../../schema/index.js';
+import type { SceneState } from '../use-scene.js';
 type NodeCreateOp = {
     node: AnyNode;
     parentId?: AnyNodeId;

package/dist/store/actions/node-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-actions.d.ts","sourceRoot":"","sources":["../../../src/store/actions/node-actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node-actions.d.ts","sourceRoot":"","sources":["../../../src/store/actions/node-actions.ts"],"names":[],"mappings":"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"}