@pascal-app/nodes 1.0.0-beta.5 → 1.0.1

package/dist/shared/opening-move-history.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One-undo-entry-per-gesture history session for the door / window MOVE
+ * tools (the E5 drag-commit contract: mid-drag writes none, drop writes
+ * exactly one, undo restores the exact pre-drag state).
+ *
+ * The tools previously called `useScene.temporal.getState().pause()` /
+ * `.resume()` RAW. That pause is invisible to the refcounted
+ * `getSceneHistoryPauseDepth()` every cooperating system checks, which
+ * broke the gesture's atomicity two ways:
+ *
+ *  1. zundo reads `isTracking` AFTER the store's subscribers run for a
+ *     write. A subscriber that takes a balanced
+ *     `pauseSceneHistory`/`resumeSceneHistory` pair during a mid-drag
+ *     write (the space-detection sync does exactly this when a reparent
+ *     touches a wall's `children`) sees depth 0 → its resume re-enables
+ *     tracking — and the mid-drag write that TRIGGERED it, plus every
+ *     write after, lands in `pastStates`. That is night-6's door-drag
+ *     undo defect: a scene commit fired the moment the drag armed, and a
+ *     completed drag left multiple undo entries, none of them the
+ *     baseline (door isTransient/invisible, parented to the level, an
+ *     orphan opening at the drop spot...).
+ *  2. Systems that stand down during interactions gate on
+ *     `getSceneHistoryPauseDepth() > 0`; a raw pause never registered, so
+ *     they kept reconciling against half-written mid-drag states.
+ *
+ * This session holds a refcounted LEASE (`acquireSceneHistoryPause`)
+ * instead. While it is held the depth is ≥ 1, so cooperating systems both
+ * see the interaction and — crucially — can no longer zero the refcount
+ * and resume tracking out from under the gesture. `commitStep` opens the
+ * one deliberate tracking window for the drop write; `end` releases the
+ * lease (idempotent, safe to call from both cancel and effect cleanup).
+ */
+export type OpeningMoveHistorySession = {
+    /**
+     * Run the gesture's single committing write with history tracking live:
+     * releases the lease for exactly this call, then re-acquires it so any
+     * teardown writes that follow (tool unmount, selection churn) stay out
+     * of history. The caller restores the node to its exact pre-drag state
+     * (still paused) right BEFORE this, so the one entry zundo records has
+     * the true baseline as its past state.
+     */
+    commitStep<T>(write: () => T): T;
+    /** Release the gesture's history pause. Idempotent. */
+    end(): void;
+};
+export declare const beginOpeningMoveHistorySession: () => OpeningMoveHistorySession;
+//# sourceMappingURL=opening-move-history.d.ts.map

package/dist/shared/opening-move-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opening-move-history.d.ts","sourceRoot":"","sources":["../../src/shared/opening-move-history.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IAChC,uDAAuD;IACvD,GAAG,IAAI,IAAI,CAAA;CACZ,CAAA;AAED,eAAO,MAAM,8BAA8B,QAAO,yBAejD,CAAA"}

package/dist/shared/opening-move-history.js

@@ -0,0 +1,18 @@
+import { acquireSceneHistoryPause, useScene } from '@pascal-app/core';
+export const beginOpeningMoveHistorySession = () => {
+    let release = acquireSceneHistoryPause(useScene);
+    return {
+        commitStep(write) {
+            release();
+            try {
+                return write();
+            }
+            finally {
+                release = acquireSceneHistoryPause(useScene);
+            }
+        },
+        end() {
+            release();
+        },
+    };
+};

package/dist/shared/opening-move-wall-gate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hidden-wall gate for the door / window MOVE tools.
+ *
+ * #689's hidden-wall pointer hold keeps EVERY hidden wall a ray target while
+ * an opening tool is active — that fixed the drag detaching into the floor
+ * free-follow (red world-axis ghost) when the node's own wall is hidden in
+ * X-ray. But nearest-hit-wins over-corrected the MOVE tools: a hidden wall
+ * INTERPOSED between the camera and the dragged opening's own wall caught
+ * the `wall:move` stream, so the drag silently rode a wall the user cannot
+ * see and the commit RE-PARENTED the opening onto it (night-6 QA: a window
+ * moved along its z=0 wall landed on an invisible wall at z=-2.5).
+ *
+ * Rule — while MOVING an existing opening, a wall event may drive the drag
+ * only when:
+ *  - the event's wall is one of the node's OWN walls (the wall it was
+ *    grabbed from, or the host it legitimately re-parented to mid-drag),
+ *    hidden or not — an X-ray drag along its own hidden wall keeps working
+ *    exactly as #689 intended; or
+ *  - the event's wall is VISIBLE — cross-wall re-parenting stays possible,
+ *    but only onto a target the user can actually see.
+ *
+ * Ignored events must NOT stop propagation: R3F then continues down the
+ * intersection list, so the ray falls through the interposed hidden wall to
+ * the node's own wall behind it and the drag keeps riding the wall the user
+ * is reasoning about. If the ray misses the own wall entirely the existing
+ * off-wall handling (floor free-follow) takes over unchanged.
+ *
+ * PLACE (fresh door/window, incl. `metadata.isNew` duplicates) keeps the
+ * all-walls behavior — placing onto any wall, hidden ones included, is the
+ * intended X-ray experience; the tools skip this gate for those.
+ *
+ * Pure so the truth table is testable without an R3F rig (mirrors
+ * `wallPointerEventsSuppressed`); the tools supply live values per event.
+ */
+export declare const shouldIgnoreWallEventForOpeningMove: ({ eventWallId, eventWallHidden, ownWallIds, }: {
+    /** The wall that emitted the `wall:enter` / `wall:move` / `wall:click`. */
+    eventWallId: string;
+    /** Live hide state of that wall (the wall-mode pass, see `isWallMeshHidden`). */
+    eventWallHidden: boolean;
+    /**
+     * Walls the moving node may ride even while hidden: the wall it was
+     * grabbed from and its current mid-drag host. Non-wall entries (a level id
+     * during free-follow, a roof segment, `null`) simply never match.
+     */
+    ownWallIds: ReadonlyArray<string | null | undefined>;
+}) => boolean;
+/**
+ * Live hide state of a wall's registered mesh. `WallCutout` stamps
+ * `userData.wallHidden` on the wall's scene-registry mesh every pass (X-ray
+ * 'down' mode, cutaway-hidden faces, auto-mode interior partitions); the
+ * wall renderer's pointer gate reads the same stamp. Unregistered walls
+ * (not mounted yet) count as visible — there is nothing to fall through to.
+ */
+export declare const isWallMeshHidden: (wallId: string) => boolean;
+//# sourceMappingURL=opening-move-wall-gate.d.ts.map

package/dist/shared/opening-move-wall-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opening-move-wall-gate.d.ts","sourceRoot":"","sources":["../../src/shared/opening-move-wall-gate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,mCAAmC,GAAI,+CAIjD;IACD,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAA;IACnB,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,UAAU,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;CACrD,KAAG,OAA+D,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,OAC2B,CAAA"}

package/dist/shared/opening-move-wall-gate.js

@@ -0,0 +1,44 @@
+import { sceneRegistry } from '@pascal-app/core';
+/**
+ * Hidden-wall gate for the door / window MOVE tools.
+ *
+ * #689's hidden-wall pointer hold keeps EVERY hidden wall a ray target while
+ * an opening tool is active — that fixed the drag detaching into the floor
+ * free-follow (red world-axis ghost) when the node's own wall is hidden in
+ * X-ray. But nearest-hit-wins over-corrected the MOVE tools: a hidden wall
+ * INTERPOSED between the camera and the dragged opening's own wall caught
+ * the `wall:move` stream, so the drag silently rode a wall the user cannot
+ * see and the commit RE-PARENTED the opening onto it (night-6 QA: a window
+ * moved along its z=0 wall landed on an invisible wall at z=-2.5).
+ *
+ * Rule — while MOVING an existing opening, a wall event may drive the drag
+ * only when:
+ *  - the event's wall is one of the node's OWN walls (the wall it was
+ *    grabbed from, or the host it legitimately re-parented to mid-drag),
+ *    hidden or not — an X-ray drag along its own hidden wall keeps working
+ *    exactly as #689 intended; or
+ *  - the event's wall is VISIBLE — cross-wall re-parenting stays possible,
+ *    but only onto a target the user can actually see.
+ *
+ * Ignored events must NOT stop propagation: R3F then continues down the
+ * intersection list, so the ray falls through the interposed hidden wall to
+ * the node's own wall behind it and the drag keeps riding the wall the user
+ * is reasoning about. If the ray misses the own wall entirely the existing
+ * off-wall handling (floor free-follow) takes over unchanged.
+ *
+ * PLACE (fresh door/window, incl. `metadata.isNew` duplicates) keeps the
+ * all-walls behavior — placing onto any wall, hidden ones included, is the
+ * intended X-ray experience; the tools skip this gate for those.
+ *
+ * Pure so the truth table is testable without an R3F rig (mirrors
+ * `wallPointerEventsSuppressed`); the tools supply live values per event.
+ */
+export const shouldIgnoreWallEventForOpeningMove = ({ eventWallId, eventWallHidden, ownWallIds, }) => eventWallHidden && !ownWallIds.includes(eventWallId);
+/**
+ * Live hide state of a wall's registered mesh. `WallCutout` stamps
+ * `userData.wallHidden` on the wall's scene-registry mesh every pass (X-ray
+ * 'down' mode, cutaway-hidden faces, auto-mode interior partitions); the
+ * wall renderer's pointer gate reads the same stamp. Unregistered walls
+ * (not mounted yet) count as visible — there is nothing to fall through to.
+ */
+export const isWallMeshHidden = (wallId) => sceneRegistry.nodes.get(wallId)?.userData?.wallHidden === true;

package/dist/shared/panel-fields.d.ts

@@ -0,0 +1,15 @@
+export declare function PanelTextField({ label, onCommit, value, }: {
+    label: string;
+    onCommit: (value: string) => void;
+    value: string;
+}): import("react").JSX.Element;
+export declare function PanelSelect({ label, onChange, options, value, }: {
+    label: string;
+    onChange: (value: string) => void;
+    options: ReadonlyArray<{
+        label: string;
+        value: string;
+    }>;
+    value: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=panel-fields.d.ts.map

package/dist/shared/panel-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-fields.d.ts","sourceRoot":"","sources":["../../src/shared/panel-fields.tsx"],"names":[],"mappings":"AAIA,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,QAAQ,EACR,KAAK,GACN,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,KAAK,EAAE,MAAM,CAAA;CACd,+BAoCA;AAED,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,GACN,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,OAAO,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxD,KAAK,EAAE,MAAM,CAAA;CACd,+BAiBA"}

package/dist/shared/panel-fields.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+export function PanelTextField({ label, onCommit, value, }) {
+    const [draft, setDraft] = useState(value);
+    const cancelRef = useRef(false);
+    useEffect(() => setDraft(value), [value]);
+    const commit = () => {
+        if (cancelRef.current) {
+            cancelRef.current = false;
+            setDraft(value);
+            return;
+        }
+        const next = draft.trim();
+        if (next !== value)
+            onCommit(next);
+        else
+            setDraft(value);
+    };
+    return (_jsxs("label", { className: "flex h-10 items-center gap-3 rounded-lg border border-border/50 bg-[#2C2C2E] px-3 text-sm", children: [_jsx("span", { className: "shrink-0 text-muted-foreground", children: label }), _jsx("input", { className: "min-w-0 flex-1 bg-transparent text-right text-foreground outline-none selection:bg-primary/30", onBlur: commit, onChange: (event) => setDraft(event.target.value), onKeyDown: (event) => {
+                    if (event.key === 'Enter')
+                        event.currentTarget.blur();
+                    if (event.key === 'Escape') {
+                        cancelRef.current = true;
+                        event.currentTarget.blur();
+                    }
+                }, type: "text", value: draft })] }));
+}
+export function PanelSelect({ label, onChange, options, value, }) {
+    return (_jsxs("label", { className: "flex h-10 items-center justify-between gap-3 rounded-lg border border-border/50 bg-[#2C2C2E] px-3 text-sm", children: [_jsx("span", { className: "text-muted-foreground", children: label }), _jsx("select", { className: "min-w-0 rounded-md border border-border/50 bg-[#232325] px-2 py-1 text-foreground text-xs outline-none", onChange: (event) => onChange(event.target.value), value: value, children: options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) })] }));
+}

package/dist/shared/path-point-affordance.d.ts

@@ -3,8 +3,8 @@ import { type AnyNodeId, type FloorplanAffordance } from '@pascal-app/core';
  * Shared "drag a path point" floor-plan affordance for polyline
  * distribution kinds (duct-segment / pipe-segment / lineset). It is the
  * 2D counterpart of their 3D `affordanceTools.selection` handles: one
- * draggable handle per path vertex, moved freely on the plan (XZ) with
- * grid snap (Shift bypasses). The vertex's Y (elevation / slope) is held
+ * draggable handle per path vertex, moved freely on the plan (XZ) using
+ * the active snapping mode. The vertex's Y (elevation / slope) is held
  * fixed — plan editing never changes height.
  *
  * Like the 3D handles, dragging a vertex that sits on a fitting carries the

package/dist/shared/path-point-affordance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-point-affordance.d.ts","sourceRoot":"","sources":["../../src/shared/path-point-affordance.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,mBAAmB,EAKzB,MAAM,kBAAkB,CAAA;AAQzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAA;AAE3E,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,SAAS,GAAG;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,EACnF,IAAI,EAAE,MAAM,GACX,mBAAmB,CAAC,CAAC,CAAC,CAqGxB"}
+{"version":3,"file":"path-point-affordance.d.ts","sourceRoot":"","sources":["../../src/shared/path-point-affordance.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,mBAAmB,EAKzB,MAAM,kBAAkB,CAAA;AASzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAA;AAE3E,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,SAAS,GAAG;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,EACnF,IAAI,EAAE,MAAM,GACX,mBAAmB,CAAC,CAAC,CAAC,CAgIxB"}

package/dist/shared/path-point-affordance.js

@@ -1,5 +1,6 @@
 import { analyzePortConnectivity, resolveConnectivityUpdates, useScene, } from '@pascal-app/core';
-import { snapPointToGrid } from '@pascal-app/editor';
+import { isGridSnapActive, snapPointToGrid } from '@pascal-app/editor';
+import { planRunEndCapFollowUpdates } from './automatic-run-end-cap';
 import { detectFittingEndpoint, planFittingEndpointReaim, } from './fitting-endpoint-reaim';
 export function createPathPointMoveAffordance(kind) {
     const inert = {
@@ -30,7 +31,7 @@ export function createPathPointMoveAffordance(kind) {
             const fittingEndpoint = isEndpoint
                 ? detectFittingEndpoint(kind, initialPath, pointIndex, nodes)
                 : null;
-            const connectivity = isEndpoint && !fittingEndpoint
+            const connectivity = isEndpoint
                 ? analyzePortConnectivity(node, nodes)
                 : null;
             // Report every node the drag may write so the dispatcher snapshots them
@@ -40,6 +41,16 @@ export function createPathPointMoveAffordance(kind) {
                 ...(fittingEndpoint ? [fittingEndpoint.fitting.id] : []),
                 ...(connectivity?.connections.map((c) => c.nodeId) ?? []),
             ];
+            const endCapUpdates = (nextPath) => {
+                if ((kind !== 'duct-segment' && kind !== 'pipe-segment') || !isEndpoint)
+                    return [];
+                const preview = {
+                    ...node,
+                    path: nextPath,
+                };
+                const endpoint = pointIndex === 0 ? 'start' : 'end';
+                return planRunEndCapFollowUpdates(node, preview, endpoint, nodes);
+            };
             const followUpdates = (nextPath) => {
                 if (!connectivity)
                     return [];
@@ -47,14 +58,17 @@ export function createPathPointMoveAffordance(kind) {
                     ...node,
                     path: nextPath,
                 };
-                return resolveConnectivityUpdates(connectivity, preview).filter((u) => useScene.getState().nodes[u.id]);
+                const updates = resolveConnectivityUpdates(connectivity, preview).filter((u) => useScene.getState().nodes[u.id]);
+                const capUpdates = endCapUpdates(nextPath);
+                const capIds = new Set(capUpdates.map((update) => update.id));
+                return [...updates.filter((update) => !capIds.has(update.id)), ...capUpdates];
             };
             return {
                 affectedIds,
                 apply({ planPoint, modifiers }) {
                     // Plan coords map x→world X, y→world Z.
                     const raw = [planPoint[0], planPoint[1]];
-                    const [sx, sz] = modifiers.shiftKey ? raw : snapPointToGrid(raw);
+                    const [sx, sz] = isGridSnapActive() ? snapPointToGrid(raw) : raw;
                     const dragged = [sx, y, sz];
                     // Alt = detach: break the joint for this drag — the elbow does NOT
                     // re-aim and mated fittings / runs do NOT follow; the vertex moves
@@ -68,17 +82,27 @@ export function createPathPointMoveAffordance(kind) {
                         if (!plan)
                             return;
                         useScene.getState().updateNodes([
-                            { id: node.id, data: { path: plan.path } },
+                            {
+                                id: node.id,
+                                data: { path: plan.path, wallAttachment: undefined },
+                            },
                             {
                                 id: plan.fittingUpdate.id,
                                 data: plan.fittingUpdate.data,
                             },
+                            ...endCapUpdates(plan.path).map((update) => ({
+                                id: update.id,
+                                data: update.data,
+                            })),
                         ]);
                         return;
                     }
                     const nextPath = initialPath.map((p, i) => (i === pointIndex ? dragged : p));
                     useScene.getState().updateNodes([
-                        { id: node.id, data: { path: nextPath } },
+                        {
+                            id: node.id,
+                            data: { path: nextPath, wallAttachment: undefined },
+                        },
                         ...(detached ? [] : followUpdates(nextPath)).map((u) => ({
                             id: u.id,
                             data: u.data,

package/dist/shared/placeholder-geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"placeholder-geometry.d.ts","sourceRoot":"","sources":["../../src/shared/placeholder-geometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA0B,MAAM,OAAO,CAAA;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,SAAI,GAAG,cAAc,CAUxE"}
+{"version":3,"file":"placeholder-geometry.d.ts","sourceRoot":"","sources":["../../src/shared/placeholder-geometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA0B,MAAM,OAAO,CAAA;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,SAAI,GAAG,cAAc,CAcxE"}

package/dist/shared/placeholder-geometry.js

@@ -20,6 +20,10 @@ import { BufferGeometry, Float32BufferAttribute } from 'three';
  */
 export function createPlaceholderGeometry(groupCount = 0) {
     const geometry = new BufferGeometry();
+    // Owning systems (and the wall self-heal sweep in
+    // viewer/systems/wall/wall-placeholder-sweep.ts) can tell "never built"
+    // from "built" without guessing off vertex counts.
+    geometry.userData.placeholder = true;
     geometry.setAttribute('position', new Float32BufferAttribute(new Float32Array(9), 3));
     geometry.setAttribute('normal', new Float32BufferAttribute(new Float32Array(9), 3));
     geometry.setAttribute('uv', new Float32BufferAttribute(new Float32Array(6), 2));

package/dist/shared/ports.d.ts

@@ -1,4 +1,5 @@
-import { type AnyNodeId, type NodePort } from '@pascal-app/core';
+import { type AnyNode, type AnyNodeId, type NodePort } from '@pascal-app/core';
+import type { RunSurfaceTarget } from './distribution-run-contract';
 /** A port plus the scene node that owns it. */
 export type ScenePort = NodePort & {
     nodeId: AnyNodeId;
@@ -19,6 +20,7 @@ export declare const REFRIGERANT_PORT_SYSTEMS: readonly ["refrigerant"];
  *     A port with no `system` matches any filter.
  */
 export type PortFilter = {
+    levelId?: AnyNodeId;
     excludeNodeId?: AnyNodeId;
     systems?: readonly string[];
 };
@@ -27,7 +29,7 @@ export type PortFilter = {
  * `def.ports`. Positions are level-local meters (the kind applies its own
  * transform inside `def.ports`).
  */
-export declare function collectScenePorts(filter?: PortFilter): ScenePort[];
+export declare function collectScenePorts(filter?: PortFilter, sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>): ScenePort[];
 /**
  * Nearest port within `radius` of `point` on the XZ plane. Y is ignored —
  * grid events ride the floor plane while ports usually hang at duct
@@ -35,6 +37,8 @@ export declare function collectScenePorts(filter?: PortFilter): ScenePort[];
  * unreachable. The snap adopts the port's full 3D position.
  */
 export declare function findNearestPortXZ(point: readonly [number, number, number], ports: ScenePort[], radius: number): ScenePort | null;
+/** Nearest port using true 3D distance. Use this while drafting on a wall. */
+export declare function findNearestPort3D(point: readonly [number, number, number], ports: ScenePort[], radius: number, surface?: RunSurfaceTarget | null): ScenePort | null;
 /** Closest-point hit on a duct run's centerline (not its end ports). */
 export type RunBodyHit = {
     nodeId: AnyNodeId;
@@ -54,7 +58,14 @@ export type RunBodyHit = {
 export declare function findNearestRunBodyXZ(point: readonly [number, number, number], radius: number, filter?: {
     excludeNodeId?: AnyNodeId;
     kinds?: readonly string[];
-}): RunBodyHit | null;
+    levelId?: AnyNodeId;
+}, sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>): RunBodyHit | null;
+/** Nearest run centerline point using true 3D distance, including risers. */
+export declare function findNearestRunBody3D(point: readonly [number, number, number], radius: number, filter?: {
+    excludeNodeId?: AnyNodeId;
+    kinds?: readonly string[];
+    levelId?: AnyNodeId;
+}, surface?: RunSurfaceTarget | null, sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>): RunBodyHit | null;
 /**
  * Where a drawn segment `start`→`end` crosses straight THROUGH an
  * existing run's centerline in XZ — the four-way (cross) case, as
@@ -72,4 +83,10 @@ export declare function findRunBodyCrossingXZ(start: readonly [number, number, n
     excludeNodeId?: AnyNodeId;
     kinds?: readonly string[];
 }): RunBodyHit | null;
+/** Surface-local crossing for wall drafting. Intersects projected U/V lines
+ * and ignores runs that are not coplanar with the selected wall. */
+export declare function findRunBodyCrossingSurface(start: readonly [number, number, number], end: readonly [number, number, number], endMargin: number, surface: RunSurfaceTarget, filter?: {
+    excludeNodeId?: AnyNodeId;
+    kinds?: readonly string[];
+}): RunBodyHit | null;
 //# sourceMappingURL=ports.d.ts.map

package/dist/shared/ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/shared/ports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAA0B,MAAM,kBAAkB,CAAA;AAExF,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAExD,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,+BAAgC,CAAA;AAC9D,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,4BAA6B,CAAA;AAC1D,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,0BAA2B,CAAA;AAEhE;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,UAAe,GAAG,SAAS,EAAE,CActE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACxC,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CAalB;AAID,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,SAAS,CAAA;IACjB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE;IAAE,aAAa,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACpE,UAAU,GAAG,IAAI,CAoCnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACxC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE;IAAE,aAAa,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACpE,UAAU,GAAG,IAAI,CAgDnB"}
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/shared/ports.ts"],"names":[],"mappings":"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"}

package/dist/shared/ports.js

@@ -1,4 +1,4 @@
-import { nodeRegistry, useScene } from '@pascal-app/core';
+import { findLevelAncestorId, nodeRegistry, useScene, } from '@pascal-app/core';
 /** Air-loop port systems — what duct runs and fittings snap to. */
 export const DUCT_PORT_SYSTEMS = ['supply', 'return'];
 /** DWV port systems — what drain / waste / vent pipe runs snap to. */
@@ -10,12 +10,15 @@ export const REFRIGERANT_PORT_SYSTEMS = ['refrigerant'];
  * `def.ports`. Positions are level-local meters (the kind applies its own
  * transform inside `def.ports`).
  */
-export function collectScenePorts(filter = {}) {
-    const { excludeNodeId, systems } = filter;
-    const { nodes } = useScene.getState();
+export function collectScenePorts(filter = {}, sceneNodes) {
+    const { excludeNodeId, systems, levelId } = filter;
+    const nodes = sceneNodes ?? useScene.getState().nodes;
     const result = [];
     for (const node of Object.values(nodes)) {
-        if (!node || node.id === excludeNodeId)
+        if (!node ||
+            node.visible === false ||
+            node.id === excludeNodeId ||
+            (levelId && findLevelAncestorId(node.id, nodes) !== levelId))
             continue;
         const ports = nodeRegistry.get(node.type)?.ports?.(node);
         if (!ports)
@@ -48,6 +51,29 @@ export function findNearestPortXZ(point, ports, radius) {
     }
     return best;
 }
+/** Nearest port using true 3D distance. Use this while drafting on a wall. */
+export function findNearestPort3D(point, ports, radius, surface) {
+    let best = null;
+    let bestDistSq = radius * radius;
+    for (const port of ports) {
+        if (surface?.kind === 'wall') {
+            const planeDistance = (port.position[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+                (port.position[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+                (port.position[2] - surface.frame.origin[2]) * surface.frame.normal[2];
+            if (Math.abs(planeDistance) > radius)
+                continue;
+        }
+        const dx = port.position[0] - point[0];
+        const dy = port.position[1] - point[1];
+        const dz = port.position[2] - point[2];
+        const distSq = dx * dx + dy * dy + dz * dz;
+        if (distSq <= bestDistSq) {
+            bestDistSq = distSq;
+            best = port;
+        }
+    }
+    return best;
+}
 /**
  * Nearest point on any duct-segment CENTERLINE within `radius` of `point`
  * on the XZ plane — how a branch taps the side of a trunk. Same XZ-only
@@ -56,14 +82,16 @@ export function findNearestPortXZ(point, ports, radius) {
  * position. Vertical risers project to a point in XZ and are skipped —
  * tapping those isn't meaningful.
  */
-export function findNearestRunBodyXZ(point, radius, filter = {}) {
+export function findNearestRunBodyXZ(point, radius, filter = {}, sceneNodes) {
     const kinds = filter.kinds ?? ['duct-segment'];
-    const { nodes } = useScene.getState();
+    const nodes = sceneNodes ?? useScene.getState().nodes;
     let best = null;
     let bestDistSq = radius * radius;
     for (const node of Object.values(nodes)) {
         if (!node || !kinds.includes(node.type) || node.id === filter.excludeNodeId)
             continue;
+        if (filter.levelId && findLevelAncestorId(node.id, nodes) !== filter.levelId)
+            continue;
         const path = node.path;
         if (!path)
             continue;
@@ -93,6 +121,55 @@ export function findNearestRunBodyXZ(point, radius, filter = {}) {
     }
     return best;
 }
+/** Nearest run centerline point using true 3D distance, including risers. */
+export function findNearestRunBody3D(point, radius, filter = {}, surface, sceneNodes) {
+    const kinds = filter.kinds ?? ['duct-segment'];
+    const nodes = sceneNodes ?? useScene.getState().nodes;
+    let best = null;
+    let bestDistSq = radius * radius;
+    for (const node of Object.values(nodes)) {
+        if (!node || !kinds.includes(node.type) || node.id === filter.excludeNodeId)
+            continue;
+        if (filter.levelId && findLevelAncestorId(node.id, nodes) !== filter.levelId)
+            continue;
+        if (node.visible === false)
+            continue;
+        const path = node.path;
+        if (!path)
+            continue;
+        for (let i = 0; i < path.length - 1; i++) {
+            const a = path[i];
+            const b = path[i + 1];
+            if (surface?.kind === 'wall') {
+                const aPlane = (a[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+                    (a[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+                    (a[2] - surface.frame.origin[2]) * surface.frame.normal[2];
+                const bPlane = (b[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+                    (b[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+                    (b[2] - surface.frame.origin[2]) * surface.frame.normal[2];
+                if (Math.abs(aPlane) > radius && Math.abs(bPlane) > radius)
+                    continue;
+            }
+            const abx = b[0] - a[0];
+            const aby = b[1] - a[1];
+            const abz = b[2] - a[2];
+            const lenSq = abx * abx + aby * aby + abz * abz;
+            if (lenSq < 1e-8)
+                continue;
+            const t = Math.min(1, Math.max(0, ((point[0] - a[0]) * abx + (point[1] - a[1]) * aby + (point[2] - a[2]) * abz) / lenSq));
+            const hit = [a[0] + abx * t, a[1] + aby * t, a[2] + abz * t];
+            const dx = point[0] - hit[0];
+            const dy = point[1] - hit[1];
+            const dz = point[2] - hit[2];
+            const distSq = dx * dx + dy * dy + dz * dz;
+            if (distSq <= bestDistSq) {
+                bestDistSq = distSq;
+                best = { nodeId: node.id, segmentIndex: i, point: hit };
+            }
+        }
+    }
+    return best;
+}
 /**
  * Where a drawn segment `start`→`end` crosses straight THROUGH an
  * existing run's centerline in XZ — the four-way (cross) case, as
@@ -162,3 +239,67 @@ export function findRunBodyCrossingXZ(start, end, endMargin, filter = {}) {
     }
     return best;
 }
+/** Surface-local crossing for wall drafting. Intersects projected U/V lines
+ * and ignores runs that are not coplanar with the selected wall. */
+export function findRunBodyCrossingSurface(start, end, endMargin, surface, filter = {}) {
+    const project = (p) => {
+        const d = [
+            p[0] - surface.frame.origin[0],
+            p[1] - surface.frame.origin[1],
+            p[2] - surface.frame.origin[2],
+        ];
+        return [
+            d[0] * surface.frame.tangent[0] +
+                d[1] * surface.frame.tangent[1] +
+                d[2] * surface.frame.tangent[2],
+            d[0] * surface.frame.bitangent[0] +
+                d[1] * surface.frame.bitangent[1] +
+                d[2] * surface.frame.bitangent[2],
+            d[0] * surface.frame.normal[0] +
+                d[1] * surface.frame.normal[1] +
+                d[2] * surface.frame.normal[2],
+        ];
+    };
+    const s0 = project(start), s1 = project(end);
+    const dx = s1[0] - s0[0], dy = s1[1] - s0[1];
+    const drawnLen = Math.hypot(dx, dy);
+    if (drawnLen < 1e-8)
+        return null;
+    const drawnPad = Math.min(0.45, endMargin / drawnLen);
+    const kinds = filter.kinds ?? ['duct-segment'];
+    const { nodes } = useScene.getState();
+    let best = null;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const node of Object.values(nodes)) {
+        if (!node ||
+            node.visible === false ||
+            node.parentId !== surface.levelId ||
+            !kinds.includes(node.type) ||
+            node.id === filter.excludeNodeId)
+            continue;
+        const path = node.path;
+        if (!path)
+            continue;
+        for (let i = 0; i < path.length - 1; i++) {
+            const a = path[i], b = path[i + 1], pa = project(a), pb = project(b);
+            const ex = pb[0] - pa[0], ey = pb[1] - pa[1], runLen = Math.hypot(ex, ey);
+            const denom = dx * ey - dy * ex;
+            if (runLen < 1e-8 || Math.abs(denom) < 1e-9)
+                continue;
+            const wx = pa[0] - s0[0], wy = pa[1] - s0[1];
+            const s = (wx * ey - wy * ex) / denom, t = (wx * dy - wy * dx) / denom;
+            if (Math.abs(pa[2] + t * (pb[2] - pa[2]) - (s0[2] + s * (s1[2] - s0[2]))) > 0.01)
+                continue;
+            const runPad = Math.min(0.45, endMargin / runLen);
+            if (s <= drawnPad || s >= 1 - drawnPad || t <= runPad || t >= 1 - runPad || s >= bestScore)
+                continue;
+            bestScore = s;
+            best = {
+                nodeId: node.id,
+                segmentIndex: i,
+                point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t],
+            };
+        }
+    }
+    return best;
+}

package/dist/shared/primitive-uv.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+export type MetricUv = readonly [number, number];
+type Point3 = readonly [number, number, number] | number[];
+/** Return cumulative metre distances along a sampled open or closed profile. */
+export declare function cumulativeProfileDistances(points: readonly Point3[]): number[];
+/** Project a flat polygon into metre-scaled UV coordinates without shearing trapezoids. */
+export declare function planarMetricUvs(points: readonly Point3[], normal: Point3, uOffset?: number, vOffset?: number): MetricUv[];
+/** Reuse the authored unwrap for AO and light maps, which read texture channel 2. */
+export declare function copyUvToSecondaryChannel(geometry: THREE.BufferGeometry): void;
+/** Apply metre-scaled planar UVs to a non-indexed, axis-aligned primitive. */
+export declare function applyPlanarWorldUvs(geometry: THREE.BufferGeometry): void;
+/** Scale cylinder/cone side UVs by circumference and height; caps use XZ metres. */
+export declare function applyCylinderWorldUvs(geometry: THREE.BufferGeometry, radius: number, height: number): void;
+/** Scale a sphere's equirectangular UVs to its circumference and pole distance. */
+export declare function applySphereWorldUvs(geometry: THREE.BufferGeometry, radius: number): void;
+export {};
+//# sourceMappingURL=primitive-uv.d.ts.map

package/dist/shared/primitive-uv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-uv.d.ts","sourceRoot":"","sources":["../../src/shared/primitive-uv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEhD,KAAK,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAAA;AAE1D,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9E;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,MAAM,EACd,OAAO,SAAI,EACX,OAAO,SAAI,GACV,QAAQ,EAAE,CA6BZ;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,CAG7E;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,CA4BxE;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,IAAI,CAkBN;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAQxF"}