@pascal-app/nodes 0.1.1

package/dist/shared/slot-paint.js

@@ -0,0 +1,235 @@
+import { generateSceneMaterialId, parseMaterialRef, sceneRegistry, toSceneMaterialRef, useScene, } from '@pascal-app/core';
+import { createMaterial, createMaterialFromPresetRef, useViewer } from '@pascal-app/viewer';
+import { Raycaster } from 'three';
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let index = 0; index < a.length; index += 1) {
+            if (!deepEqual(a[index], b[index]))
+                return false;
+        }
+        return true;
+    }
+    if (typeof a === 'object') {
+        const aRecord = a;
+        const bRecord = b;
+        const aKeys = Object.keys(aRecord);
+        const bKeys = Object.keys(bRecord);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        for (const key of aKeys) {
+            if (!Object.hasOwn(bRecord, key))
+                return false;
+            if (!deepEqual(aRecord[key], bRecord[key]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+function findMatchingSceneMaterial(materials, material) {
+    for (const sceneMaterial of Object.values(materials)) {
+        if (deepEqual(sceneMaterial.material, material))
+            return sceneMaterial;
+    }
+    return null;
+}
+function commitSlotPaint(node, role, material, materialPreset) {
+    const nodeId = node.id;
+    const state = useScene.getState();
+    const currentNode = state.nodes[nodeId] ?? node;
+    let ref;
+    let newSceneMaterial = null;
+    if (material === undefined && materialPreset === undefined) {
+        ref = undefined;
+    }
+    else if (materialPreset) {
+        ref = materialPreset;
+    }
+    else if (material) {
+        const existing = findMatchingSceneMaterial(state.materials, material);
+        if (existing) {
+            ref = toSceneMaterialRef(existing.id);
+        }
+        else {
+            const id = generateSceneMaterialId();
+            newSceneMaterial = {
+                id,
+                name: `Material ${Object.keys(state.materials).length + 1}`,
+                material,
+            };
+            ref = toSceneMaterialRef(id);
+        }
+    }
+    else {
+        return;
+    }
+    const nextSlots = { ...(currentNode.slots ?? {}) };
+    if (ref)
+        nextSlots[role] = ref;
+    else
+        delete nextSlots[role];
+    if (newSceneMaterial) {
+        // Creating the scene material and setting the slot ref are one logical
+        // edit, so apply both in a single `set` — zundo records one history entry,
+        // and one undo removes both the ref and its (now orphaned) material.
+        const sceneMaterial = newSceneMaterial;
+        useScene.setState((s) => {
+            if (s.readOnly)
+                return s;
+            const node2 = s.nodes[nodeId];
+            if (!node2)
+                return s;
+            return {
+                materials: { ...s.materials, [sceneMaterial.id]: sceneMaterial },
+                nodes: {
+                    ...s.nodes,
+                    [nodeId]: { ...node2, slots: nextSlots },
+                },
+            };
+        });
+        useScene.getState().markDirty(nodeId);
+        return;
+    }
+    state.updateNode(nodeId, { slots: nextSlots });
+}
+/** Preview material for a slot paint — mirrors the commit's resolution. */
+export function buildSlotPreviewMaterial(material, materialPreset) {
+    const shading = useViewer.getState().shading;
+    if (materialPreset) {
+        const parsed = parseMaterialRef(materialPreset);
+        if (parsed?.kind === 'scene') {
+            const sceneMaterial = useScene.getState().materials[parsed.id];
+            return sceneMaterial ? createMaterial(sceneMaterial.material, shading) : null;
+        }
+        return createMaterialFromPresetRef(materialPreset, shading);
+    }
+    if (material)
+        return createMaterial(material, shading);
+    return null;
+}
+/**
+ * Preview for kinds whose meshes are produced by `def.geometry` and tagged
+ * with `userData.slotId` (+ `__fromGeometry`). Swaps every builder mesh whose
+ * slot matches `role`, leaving hosted-child meshes (which can carry a colliding
+ * `userData.slotId` from their own GLB) untouched.
+ */
+export function previewGeometrySlot(args) {
+    const { role, root, material, materialPreset } = args;
+    const preview = buildSlotPreviewMaterial(material, materialPreset);
+    if (!preview)
+        return () => { };
+    const restores = [];
+    root.traverse((object) => {
+        const mesh = object;
+        if (!mesh.isMesh)
+            return;
+        const userData = mesh.userData;
+        if (userData.__fromGeometry !== true)
+            return;
+        if (userData.slotId !== role)
+            return;
+        const previous = mesh.material;
+        mesh.material = preview;
+        restores.push(() => {
+            mesh.material = previous;
+        });
+    });
+    if (restores.length === 0)
+        return null;
+    return () => {
+        for (let index = restores.length - 1; index >= 0; index -= 1)
+            restores[index]?.();
+    };
+}
+/**
+ * Preview for kinds whose meshes are built by a viewer system (window, door)
+ * and tagged with `userData.slotId` — no `__fromGeometry` marker and no hosted
+ * children to guard against, so it swaps every mesh whose slot matches `role`.
+ */
+export function previewSlotByUserData(args) {
+    const { role, root, material, materialPreset } = args;
+    const preview = buildSlotPreviewMaterial(material, materialPreset);
+    if (!preview)
+        return () => { };
+    const restores = [];
+    root.traverse((object) => {
+        const mesh = object;
+        if (!mesh.isMesh)
+            return;
+        if (mesh.userData.slotId !== role)
+            return;
+        const previous = mesh.material;
+        mesh.material = preview;
+        restores.push(() => {
+            mesh.material = previous;
+        });
+    });
+    if (restores.length === 0)
+        return null;
+    return () => {
+        for (let index = restores.length - 1; index >= 0; index -= 1)
+            restores[index]?.();
+    };
+}
+// Reused across calls — set from the pointer ray each time.
+const subtreeRaycaster = new Raycaster();
+/**
+ * Resolve the slot for a kind whose paint hit lands on a proud opening proxy
+ * (door/window: a 1m-deep invisible cutout that wins the scene raycast over the
+ * wall in front of the recessed body) rather than the part itself. Re-raycasts
+ * the kind's OWN registered subtree (ignoring everything else) and returns the
+ * first tagged sub-mesh under the cursor; falls back to the direct hit's slot
+ * (e.g. a proud part the scene raycast hit directly).
+ */
+export function resolveSlotByReRaycast(args) {
+    const direct = args.hitObject?.userData?.slotId;
+    if (typeof direct === 'string')
+        return direct;
+    const root = sceneRegistry.nodes.get(args.node.id);
+    if (!root || !args.ray)
+        return null;
+    subtreeRaycaster.ray.copy(args.ray);
+    for (const hit of subtreeRaycaster.intersectObject(root, true)) {
+        const slot = hit.object.userData.slotId;
+        if (typeof slot === 'string')
+            return slot;
+    }
+    return null;
+}
+export function createSlotPaintCapability(config) {
+    return {
+        materialTarget: config.materialTarget,
+        roomScope: config.roomScope,
+        resolveRole: config.resolveRole,
+        buildPatch: ({ node, role, materialPreset }) => {
+            const slots = { ...(node.slots ?? {}) };
+            if (materialPreset)
+                slots[role] = materialPreset;
+            else
+                delete slots[role];
+            return { slots };
+        },
+        commit: ({ node, role, material, materialPreset }) => commitSlotPaint(node, role, material, materialPreset),
+        applyPreview: config.applyPreview,
+        getEffectiveMaterial: ({ node, role }) => {
+            const ref = node.slots?.[role];
+            const parsed = parseMaterialRef(ref);
+            if (parsed) {
+                if (parsed.kind === 'library')
+                    return { material: undefined, materialPreset: ref };
+                const sceneMaterial = useScene.getState().materials[parsed.id];
+                if (sceneMaterial)
+                    return { material: sceneMaterial.material, materialPreset: undefined };
+            }
+            return config.legacyEffective?.(node, role) ?? null;
+        },
+    };
+}

package/dist/shared/surface-paint.d.ts

@@ -0,0 +1,3 @@
+import type { PaintCapability } from '@pascal-app/core';
+export declare const surfacePaintCapability: PaintCapability;
+//# sourceMappingURL=surface-paint.d.ts.map

package/dist/shared/surface-paint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-paint.d.ts","sourceRoot":"","sources":["../../src/shared/surface-paint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2B,eAAe,EAAE,MAAM,kBAAkB,CAAA;AA0BhF,eAAO,MAAM,sBAAsB,EAAE,eA4BpC,CAAA"}

package/dist/shared/surface-paint.js

@@ -0,0 +1,41 @@
+import { createMaterial, createMaterialFromPresetRef } from '@pascal-app/viewer';
+function buildPreviewMaterial(material, materialPreset) {
+    if (materialPreset)
+        return createMaterialFromPresetRef(materialPreset);
+    if (material)
+        return createMaterial(material);
+    return null;
+}
+export const surfacePaintCapability = {
+    // One paintable surface — every face resolves to it.
+    resolveRole: () => 'surface',
+    buildPatch: ({ material, materialPreset }) => ({ material, materialPreset }),
+    applyPreview: ({ material, materialPreset, root }) => {
+        const preview = buildPreviewMaterial(material, materialPreset);
+        if (!preview)
+            return null;
+        // The kinds register a group, so walk the subtree and swap every child
+        // mesh's material, recording a restore for each.
+        const restores = [];
+        root.traverse((object) => {
+            const mesh = object;
+            if (!mesh.isMesh)
+                return;
+            const previous = mesh.material;
+            mesh.material = preview;
+            restores.push(() => {
+                mesh.material = previous;
+            });
+        });
+        if (restores.length === 0)
+            return null;
+        return () => {
+            for (let i = restores.length - 1; i >= 0; i -= 1)
+                restores[i]?.();
+        };
+    },
+    getEffectiveMaterial: ({ node }) => {
+        const n = node;
+        return { material: n.material, materialPreset: n.materialPreset };
+    },
+};

package/dist/shared/use-segment-trim-clip.d.ts

@@ -0,0 +1,44 @@
+import { type RoofSegmentNode } from '@pascal-app/core';
+import * as THREE from 'three';
+/**
+ * Clip a roof accessory's geometry by its host segment's trim, so the part of
+ * the accessory standing in a trimmed-away region is sliced off exactly like
+ * the roof shell.
+ *
+ * `geometry` is in accessory-local space; `localToSegment` maps it into the
+ * segment-local frame the trim cut prisms live in (compose the same
+ * `node.position` + inner-group quaternion the renderer mounts the mesh with).
+ * The function bakes that transform, runs `clipGeometryBySegmentTrim`, then
+ * strips the transform back off so the returned geometry is still
+ * accessory-local and drops straight into the renderer's existing mesh.
+ *
+ * Returns the input geometry untouched when the segment is missing or has no
+ * trim — zero cost for the overwhelmingly common case. The derived (clipped)
+ * geometry is owned by the hook and disposed on change / unmount; the input
+ * geometry is never consumed (we clip a clone), so the caller keeps owning it.
+ */
+export declare function useSegmentTrimClippedGeometry(geometry: THREE.BufferGeometry | null, segment: RoofSegmentNode | undefined, localToSegment: THREE.Matrix4): THREE.BufferGeometry | null;
+/**
+ * A `<mesh>` whose geometry is sliced by the host roof segment's trim, for
+ * accessory sub-parts that live deeper than the registered group (skylight
+ * glass panes, dormer window glass / frame / sill). Pass the matrix that maps
+ * the part's own parent frame into the segment-local frame (`parentToSegment`)
+ * plus the part's local `position` / `rotation`; the component composes the
+ * full mesh→segment transform, clips, and renders the result at the same local
+ * pose. When the segment has no trim the original geometry renders unchanged.
+ *
+ * `geometry` is owned by the caller (built once and reused); the clipped
+ * derivative is owned by the hook and disposed on change / unmount.
+ */
+export declare function TrimClippedMesh({ geometry, segment, parentToSegment, position, rotation, material, name, castShadow, receiveShadow, }: {
+    geometry: THREE.BufferGeometry;
+    segment: RoofSegmentNode | undefined;
+    parentToSegment: THREE.Matrix4;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    material: THREE.Material | THREE.Material[];
+    name?: string;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}): import("react").JSX.Element;
+//# sourceMappingURL=use-segment-trim-clip.d.ts.map

package/dist/shared/use-segment-trim-clip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segment-trim-clip.d.ts","sourceRoot":"","sources":["../../src/shared/use-segment-trim-clip.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgD9B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI,EACrC,OAAO,EAAE,eAAe,GAAG,SAAS,EACpC,cAAc,EAAE,KAAK,CAAC,OAAO,GAC5B,KAAK,CAAC,cAAc,GAAG,IAAI,CAmD7B;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAO,EACP,eAAe,EACf,QAAoB,EACpB,QAAoB,EACpB,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,aAAa,GACd,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAA;IAC9B,OAAO,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC,eAAe,EAAE,KAAK,CAAC,OAAO,CAAA;IAC9B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,+BAgCA"}

package/dist/shared/use-segment-trim-clip.js

@@ -0,0 +1,149 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { normalizeRoofSegmentTrim, useLiveNodeOverrides, } from '@pascal-app/core';
+import { clipGeometryBySegmentTrim } from '@pascal-app/viewer';
+import { useEffect, useMemo } from 'react';
+import * as THREE from 'three';
+import { Matrix4 } from 'three';
+// Does this segment remove any material? Mirrors the viewer's internal
+// `hasSegmentTrim` (not exported) — the clip is a no-op otherwise, so the
+// common (untrimmed) case skips all CSG work.
+function segmentHasTrim(segment) {
+    const t = normalizeRoofSegmentTrim(segment);
+    return (t.left > 0 ||
+        t.right > 0 ||
+        t.front > 0 ||
+        t.back > 0 ||
+        t.frontLeftX > 0 ||
+        t.frontLeftZ > 0 ||
+        t.frontRightX > 0 ||
+        t.frontRightZ > 0 ||
+        t.backLeftX > 0 ||
+        t.backLeftZ > 0 ||
+        t.backRightX > 0 ||
+        t.backRightZ > 0);
+}
+// A stable key for the segment's trim + footprint, so the memo only re-clips
+// when the cut shape actually changes (not on unrelated segment edits like
+// material).
+function segmentTrimKey(segment) {
+    if (!segment)
+        return 'none';
+    const t = normalizeRoofSegmentTrim(segment);
+    return JSON.stringify([
+        segment.width,
+        segment.depth,
+        t.left,
+        t.right,
+        t.front,
+        t.back,
+        t.frontLeftX,
+        t.frontLeftZ,
+        t.frontRightX,
+        t.frontRightZ,
+        t.backLeftX,
+        t.backLeftZ,
+        t.backRightX,
+        t.backRightZ,
+    ]);
+}
+/**
+ * Clip a roof accessory's geometry by its host segment's trim, so the part of
+ * the accessory standing in a trimmed-away region is sliced off exactly like
+ * the roof shell.
+ *
+ * `geometry` is in accessory-local space; `localToSegment` maps it into the
+ * segment-local frame the trim cut prisms live in (compose the same
+ * `node.position` + inner-group quaternion the renderer mounts the mesh with).
+ * The function bakes that transform, runs `clipGeometryBySegmentTrim`, then
+ * strips the transform back off so the returned geometry is still
+ * accessory-local and drops straight into the renderer's existing mesh.
+ *
+ * Returns the input geometry untouched when the segment is missing or has no
+ * trim — zero cost for the overwhelmingly common case. The derived (clipped)
+ * geometry is owned by the hook and disposed on change / unmount; the input
+ * geometry is never consumed (we clip a clone), so the caller keeps owning it.
+ */
+export function useSegmentTrimClippedGeometry(geometry, segment, localToSegment) {
+    // Subscribe to the segment's live trim override so the accessory re-slices
+    // in lockstep with the trim handle drag (the editor publishes the in-flight
+    // trim to `useLiveNodeOverrides`; the store only updates on commit). Without
+    // this the accessory would only re-clip once the drag is released.
+    const liveTrim = useLiveNodeOverrides((s) => segment ? s.get(segment.id)?.trim : undefined);
+    const effectiveSegment = useMemo(() => (segment && liveTrim ? { ...segment, trim: liveTrim } : segment), [segment, liveTrim]);
+    const trimKey = segmentTrimKey(effectiveSegment);
+    // Matrix identity isn't stable across renders; key on its elements.
+    const matrixKey = localToSegment.elements.join(',');
+    const clipped = useMemo(() => {
+        if (!geometry || !effectiveSegment || !segmentHasTrim(effectiveSegment))
+            return null;
+        const baked = geometry.clone();
+        baked.applyMatrix4(localToSegment);
+        const result = clipGeometryBySegmentTrim(baked, effectiveSegment);
+        if (!result)
+            return null;
+        // `clipGeometryBySegmentTrim` returns the same object when there's no trim
+        // (already guarded above) or a fresh clone otherwise; either way it's our
+        // `baked` clone or its descendant, safe to mutate + own.
+        const inverse = new Matrix4().copy(localToSegment).invert();
+        result.applyMatrix4(inverse);
+        result.computeVertexNormals();
+        // CSG can stamp the freshly-exposed cut faces with the cutter's material
+        // slot, which may exceed the accessory's material array (multi-slot kinds:
+        // dormer = 5 slots, solar-panel / skylight = 2). Clamp every group back into
+        // the original geometry's slot range so the renderer never indexes past its
+        // `material` array (mismatch crashes the draw, as the empty-segment
+        // placeholder guard documents).
+        const maxSlot = geometry.groups.reduce((m, g) => Math.max(m, g.materialIndex ?? 0), 0);
+        for (const g of result.groups) {
+            if ((g.materialIndex ?? 0) > maxSlot)
+                g.materialIndex = maxSlot;
+        }
+        return result;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [geometry, localToSegment, effectiveSegment]);
+    useEffect(() => {
+        return () => {
+            clipped?.dispose();
+        };
+    }, [clipped]);
+    // No trim (or no input) → render the original geometry unchanged.
+    return clipped ?? geometry;
+}
+const _trimMeshLocal = new THREE.Matrix4();
+const _trimMeshPos = new THREE.Vector3();
+const _trimMeshQuat = new THREE.Quaternion();
+const _trimMeshEuler = new THREE.Euler();
+const _trimMeshScale = new THREE.Vector3(1, 1, 1);
+/**
+ * A `<mesh>` whose geometry is sliced by the host roof segment's trim, for
+ * accessory sub-parts that live deeper than the registered group (skylight
+ * glass panes, dormer window glass / frame / sill). Pass the matrix that maps
+ * the part's own parent frame into the segment-local frame (`parentToSegment`)
+ * plus the part's local `position` / `rotation`; the component composes the
+ * full mesh→segment transform, clips, and renders the result at the same local
+ * pose. When the segment has no trim the original geometry renders unchanged.
+ *
+ * `geometry` is owned by the caller (built once and reused); the clipped
+ * derivative is owned by the hook and disposed on change / unmount.
+ */
+export function TrimClippedMesh({ geometry, segment, parentToSegment, position = [0, 0, 0], rotation = [0, 0, 0], material, name, castShadow, receiveShadow, }) {
+    // mesh→segment = parentToSegment · T(position) · R(rotation). Keyed in the
+    // hook on the matrix elements, so a moving/animated pane re-clips correctly.
+    const localToSegment = useMemo(() => {
+        _trimMeshEuler.set(rotation[0], rotation[1], rotation[2]);
+        _trimMeshQuat.setFromEuler(_trimMeshEuler);
+        _trimMeshPos.set(position[0], position[1], position[2]);
+        _trimMeshLocal.compose(_trimMeshPos, _trimMeshQuat, _trimMeshScale);
+        return new Matrix4().multiplyMatrices(parentToSegment, _trimMeshLocal);
+    }, [
+        parentToSegment,
+        position[0],
+        position[1],
+        position[2],
+        rotation[0],
+        rotation[1],
+        rotation[2],
+    ]);
+    const clipped = useSegmentTrimClippedGeometry(geometry, segment, localToSegment);
+    return (_jsx("mesh", { castShadow: castShadow, geometry: clipped ?? geometry, material: material, name: name, position: position, receiveShadow: receiveShadow, rotation: rotation }));
+}

package/dist/shared/vertical-offset.d.ts

@@ -0,0 +1,95 @@
+import { type AnyNode, type AnyNodeId, DuctSegmentNode, type PortConnection } from '@pascal-app/core';
+import type { DuctFittingNode } from '../duct-fitting/schema';
+import { type DuctProfile } from './auto-fitting';
+import type { ScenePort } from './ports';
+/**
+ * Center-cube vertical-move auto-routing for duct runs.
+ *
+ * When a run is lifted / lowered with the run-center cube's ±Y arrows, a
+ * RUN-connected end should stay welded to its (stationary) partner by way of
+ * an offset: an elbow on the lifted run, a plumb riser down to the partner's
+ * height, and a second elbow that meets the partner — the classic duct S/Z
+ * offset. Without it, plain connectivity-follow would translate the collinear
+ * partner run straight up too (it has no turn to absorb the lift), dragging
+ * the whole network along.
+ *
+ * RUN-connected end (partner stays at its old height):
+ *   - top elbow at the lifted endpoint, turning the run axis → vertical;
+ *   - a plumb riser straight down (same X/Z) to one leg above the partner;
+ *   - bottom elbow at the partner joint, turning vertical → the partner's
+ *     axis; the partner run is trimmed back one leg so the elbow replaces
+ *     that stretch.
+ * The lifted run is trimmed back one leg at the offset end so it meets the
+ * top elbow's collar instead of overlapping it.
+ *
+ * ELBOW-connected end (a clean L): the existing elbow STAYS PUT and re-aims so
+ * its mated collar swings vertical (flattening toward a straight coupling); a
+ * plumb riser rises from that collar to a single new TOP elbow that turns back
+ * along the run axis onto the lifted endpoint. One new elbow + one riser — no
+ * horizontal jog. Non-elbow fittings (and elbows whose re-aim is out of the
+ * buildable 15–90° range) ride up via plain connectivity-follow instead. Open
+ * ends likewise just ride up.
+ */
+type Point = [number, number, number];
+/**
+ * Three-state outcome of a connected vertical lift:
+ *  - `null` — the run has NO connected ends, so the caller plain-translates it
+ *    (nothing to keep welded; everyone is free to ride along or there's no one).
+ *  - `{ status: 'invalid' }` — at least one connected end CANNOT form a clean
+ *    offset at this height (no room for the elbows + riser, a non-elbow fitting,
+ *    or a re-aim out of the buildable 15–90° range). The caller lifts ONLY the
+ *    dragged run as a red preview, freezes every partner, and commits nothing on
+ *    release. We never silently drag the network up to "absorb" the lift.
+ *  - `{ status: 'valid', plan }` — every connected end welds back to its
+ *    stationary partner via the planned offset; the caller lifts + trims, ghosts
+ *    the new fittings green, and mints them on release.
+ */
+export type VerticalOffsetResult = {
+    status: 'valid';
+    plan: VerticalOffsetPlan;
+} | {
+    status: 'invalid';
+} | null;
+export type VerticalOffsetPlan = {
+    /** Actual vertical offset used by the route. This can differ from the raw
+     *  cursor delta when the route snaps through a topology transition. */
+    dy: number;
+    /** The lifted run's new path: every point raised by `dy`, each RUN-offset
+     *  end trimmed back one elbow-leg to meet its top elbow (fitting / open ends
+     *  keep their lifted endpoint). */
+    ductPath: Point[];
+    /** The path to seed the caller's connectivity-follow from: identical to the
+     *  lifted run except each RUN-offset end is reset to its ORIGINAL height, so
+     *  its trimmed partner shows zero delta (we trim it via `updates` instead)
+     *  while a FITTING / open end shows `+dy` — lifting its elbow rigidly and
+     *  lengthening that elbow's riser into a clean L. */
+    followPath: Point[];
+    /** Two elbows per RUN-offset end (top + bottom). */
+    fittings: DuctFittingNode[];
+    /** One plumb riser per RUN-offset end. */
+    risers: DuctSegmentNode[];
+    /** Partner-run trims (the run mated at each RUN-offset end pulled back one
+     *  leg). Fitting partners are rigid and never updated. */
+    updates: {
+        id: AnyNodeId;
+        data: Partial<AnyNode>;
+    }[];
+    /** Existing generated/absorbed parts to remove when an offset collapses into a direct L. */
+    delete?: AnyNodeId[];
+};
+export declare function planVerticalOffsets(args: {
+    duct: DuctSegmentNode;
+    /** Signed vertical move (meters); +up / -down. */
+    dy: number;
+    profile: DuctProfile;
+    /** The drag-start connectivity snapshot's connections. */
+    connections: PortConnection[];
+    /** Scene ports (excluding the lifted run) for partner direction lookup. */
+    scenePorts: ScenePort[];
+    /** Drag-start node snapshots keyed by id, so a connected elbow's ORIGINAL
+     *  pose can be re-aimed each frame (the live store carries the last frame's
+     *  re-aim). */
+    nodesById: Record<string, AnyNode>;
+}): VerticalOffsetResult;
+export {};
+//# sourceMappingURL=vertical-offset.d.ts.map

package/dist/shared/vertical-offset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertical-offset.d.ts","sourceRoot":"","sources":["../../src/shared/vertical-offset.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,eAAe,EACf,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,EACL,KAAK,WAAW,EAKjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,KAAK,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AASrC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB,IAAI,CAAA;AAER,MAAM,MAAM,kBAAkB,GAAG;IAC/B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV;;uCAEmC;IACnC,QAAQ,EAAE,KAAK,EAAE,CAAA;IACjB;;;;yDAIqD;IACrD,UAAU,EAAE,KAAK,EAAE,CAAA;IACnB,oDAAoD;IACpD,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,0CAA0C;IAC1C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB;8DAC0D;IAC1D,OAAO,EAAE;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;IACpD,4FAA4F;IAC5F,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;CACrB,CAAA;AAqoBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,eAAe,CAAA;IACrB,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,WAAW,CAAA;IACpB,0DAA0D;IAC1D,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B,2EAA2E;IAC3E,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB;;mBAEe;IACf,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GAAG,oBAAoB,CAMvB"}