three-base 2.0.169 → 2.0.175

package/PipeMesh/PipeMesh.ts

@@ -1,76 +1,223 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-02-16 23:13:14
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-11-23 13:06:54
- */
-import { DoubleSide, DynamicDrawUsage, Mesh, MeshLambertMaterial, Vector3, Material } from "three";
-import { PathPointList } from "./PathPointList";
-import { PathTubeGeometry } from "./PathTubeGeometry";
-
-export type PipeMeshProps = {
-    vector3s: Array<Vector3>;
-    radius?: number;
-    segments?: number;
-};
-
-/**
- * 创建基础的管道模型
- */
-export default class PipeMesh extends Mesh<PathTubeGeometry, Material> {
-    constructor(props: PipeMeshProps) {
-        super();
-        this.set(props);
-    }
-
-    type: string = "pipemesh";
-    vector3s: Array<Vector3> = []; // 管道上的点
-    radius: number = 1; //管道的半径
-    segments: number = 10; //管道的段数
-    pathPointList: PathPointList = new PathPointList();
-    material: Material = new MeshLambertMaterial({
-        side: DoubleSide,
-        color: "#fff",
-    });
-
-    // 设置数据
-    set(props: PipeMeshProps): void {
-        this.vector3s = props.vector3s;
-        this.radius = props.radius || 1;
-        this.segments = props.segments || 10;
-        this.pathPointList.set(this.vector3s, props.radius * 2, 10);
-        this.geometry = new PathTubeGeometry({
-            pathPointList: this.pathPointList,
-            options: {
-                arrow: true,
-                progress: 1,
-                radius: props.radius,
-                radialSegments: this.segments,
-            },
-            usage: DynamicDrawUsage,
-            transparent: true,
-        });
-    }
-
-    // 设置指定点的坐标
-    setVector(i: number, vector: Vector3): void {
-        this.vector3s[i].copy(vector);
-        this.pathPointList.set(this.vector3s, this.radius * 2, this.segments);
-        this.geometry.update(this.pathPointList, { radius: this.radius });
-    }
-
-    // 获取指定点的坐标
-    getVector(i: number): Vector3 {
-        return this.vector3s[i];
-    }
-
-    // 设置最后一个点的坐标
-    setLatestVector(vector: Vector3): void {
-        this.setVector(this.vector3s.length - 1, vector);
-    }
-
-    // 回去最后一个点的坐标
-    getLatestVector(): Vector3 {
-        return this.getVector(this.vector3s.length - 1);
-    }
-}
+import { Color, Group } from "three";
+import InstancedChild, { instancedChildRegistry } from "../instanced/InstancedChild";
+import PipeJoint from "./PipeJoint";
+import PipeStraight from "./PipeStraight";
+import { PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+import { planDirectLayout, makePipeJson, parsePipeJson, type PipeJson, type Vec3 } from "./directRoute";
+
+export interface PipeMeshProps {
+    /** 控制点（米）。**相邻两点之间直连一根直管**（可斜），拐角自动补一颗同径球 */
+    points?: Vec3[];
+    /** 管道直径（米），默认 1 */
+    diameter?: number;
+    /** 管壁颜色（逐实例色，不是材质底色） */
+    color?: Color | number | string;
+    /** 多 InstancedGroup 共存时的归属（配合 `new InstancedGroup(owner)`，如预览弹窗） */
+    owner?: string;
+}
+
+/**
+ * 组合管道（点与点直连）：**直管 + 拐角补角球全部是 InstancedChild**，由 ThreeBase 的 InstancedGroup
+ * 每帧自动合批。
+ *
+ * ⭐ 为什么这样划算：全场景只有两份几何（单位圆柱、单位球），所以**不管多少折点，
+ *   draw call 恒为 2**；改直径/改长度只动实例矩阵，不重建任何几何。旧的 PipeMesh（现
+ *   `three-base/PipeMeshLegacy/`）是一条折线扫一张合并 BufferGeometry，改点要重算顶点，两者路线互斥。
+ *
+ * ⭐ 走线口径（皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」）：
+ *   控制点 i 与 i+1 之间就是一根直管 —— 长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *   没有轴序、没有正交拆段、没有 90° 弯头。走线算术全在 `directRoute.ts`（零依赖，可纯数字断言）。
+ *
+ * 用法：
+ * ```ts
+ * const pipe = new PipeMesh({ points: [[-4,0,0],[0,3,0],[4,3,-4]], diameter: 1 });
+ * scene.add(pipe);
+ * pipe.setDiameter(0.6);          // 只改缩放
+ * pipe.movePoint(1, [0, 5, 0]);   // 只改控制点，走线自动重算
+ * const json = pipe.exportJson();   // 存档 / 导出
+ * PipeMesh.fromJson(json);          // 引用 JSON 重建
+ * pipe.setShown(false);             // 藏起这条管道（走注册表，不是 visible）
+ * ```
+ *
+ * ⚠️ 实例池是**差分复用**的：段数变少时多出来的实例会被摘出注册表并 dispose，不会留在注册表里
+ *   继续被合批（注册表是全局 Set，`scene.remove` 停不了它）。
+ */
+export default class PipeMesh extends Group {
+    points: Vec3[] = [];
+    diameter: number = 1;
+    color: Color = new Color(PIPE_DEFAULT_COLOR);
+    /** 最近一次走线的退化提示（供面板显示；不影响渲染） */
+    warnings: string[] = [];
+    /** 直管实例（段数 = 有效控制点对数） */
+    readonly straights: PipeStraight[] = [];
+    /** 拐角补角球实例（内部控制点各一颗） */
+    readonly joints: PipeJoint[] = [];
+
+    private _owner?: string;
+    private _shown: boolean = true;
+
+    constructor(props: PipeMeshProps = {}) {
+        super();
+        (this as { type: string }).type = "PipeMesh";
+        this.name = "PipeMesh";
+        this._owner = props.owner;
+        this.diameter = props.diameter ?? 1;
+        if (props.color !== undefined) this.color.set(props.color);
+        this.points = (props.points ?? []).map((p) => [p[0], p[1], p[2]] as Vec3);
+        this.rebuild();
+    }
+
+    /**
+     * 显隐：走注册表摘除/挂回，而不是靠 `visible` 标志。
+     * ⚠️ 实例化那条路的真实几何在 InstancedGroup 的 batch 里（不在这棵树下面），
+     *   所以 `pipe.visible = false` 对它**不起作用**；要藏起来就调本方法。
+     */
+    setShown(shown: boolean): this {
+        this._shown = shown;
+        for (const child of this._allInstances()) {
+            if (shown) instancedChildRegistry.add(child);
+            else instancedChildRegistry.delete(child);
+        }
+        return this;
+    }
+
+    get shown(): boolean {
+        return this._shown;
+    }
+
+    /** 按当前 points/diameter 重算实例位姿；只在段数变化时增删实例 */
+    rebuild(): this {
+        const plan = planDirectLayout(this.points, { diameter: this.diameter });
+        this.warnings = plan.warnings;
+
+        this._fitPool(this.straights, plan.straights.length, () => new PipeStraight());
+        this._fitPool(this.joints, plan.joints.length, () => new PipeJoint());
+
+        plan.straights.forEach((part, i) => {
+            const inst = this.straights[i];
+            inst.applyAt(part.center, part.dir, this.diameter, part.length);
+            inst.setPartIndex(part.index);
+            inst.setColor(this.color);
+        });
+        plan.joints.forEach((part, i) => {
+            const inst = this.joints[i];
+            inst.applyAt(part.center, this.diameter);
+            inst.setPartIndex(part.index);
+            inst.setColor(this.color);
+        });
+        return this;
+    }
+
+    private _allInstances(): InstancedChild[] {
+        return [...this.straights, ...this.joints];
+    }
+
+    /** 把池子拉到目标长度：不足 new + add 进本组，超出摘出并 dispose（连带注册表） */
+    private _fitPool<T extends InstancedChild>(pool: T[], want: number, make: () => T): void {
+        while (pool.length < want) {
+            const inst = make();
+            if (this._owner) inst.setOwner(this._owner);
+            this.add(inst);
+            pool.push(inst);
+        }
+        while (pool.length > want) {
+            const inst = pool.pop() as T;
+            this.remove(inst);
+            inst.dispose();
+        }
+    }
+
+    // ===== 参数入口：每一条都收口到 rebuild()，避免各处各自改矩阵 =====
+
+    setPoints(points: Vec3[]): this {
+        this.points = points.map((p) => [p[0], p[1], p[2]] as Vec3);
+        return this.rebuild();
+    }
+    /** 改单个控制点（拖拽现场用，比整表重设省一次数组拷贝） */
+    movePoint(index: number, p: Vec3): this {
+        if (index < 0 || index >= this.points.length) return this;
+        this.points[index] = [p[0], p[1], p[2]];
+        return this.rebuild();
+    }
+    addPoint(p: Vec3): this {
+        this.points.push([p[0], p[1], p[2]]);
+        return this.rebuild();
+    }
+    insertPoint(index: number, p: Vec3): this {
+        if (index < 0 || index > this.points.length) return this;
+        this.points.splice(index, 0, [p[0], p[1], p[2]]);
+        return this.rebuild();
+    }
+    removePoint(index: number): this {
+        if (index < 0 || index >= this.points.length) return this;
+        this.points.splice(index, 1);
+        return this.rebuild();
+    }
+    /**
+     * 控制点顺序整体颠倒（皇上旨 2026-10-25「做一个节点倒序的功能，让管道点的顺序颠倒一下」）。
+     *
+     * ⚠️ 直连方案下几何**逐段等价**（圆柱两端对称、球压在点上，都不认方向）⇒ 画面上看不出变化，
+     *   变的是**数据序**：存档 / 导出 JSON / 将来带方向性的特性（流向箭头、渐变、开孔位置）都按这个序。
+     *   所以别指望点一下画面有动静 —— 要验它，去面板看「控制点 #N」的编号，或导出 JSON 比对。
+     */
+    reversePoints(): this {
+        this.points.reverse();
+        return this.rebuild();
+    }
+    setDiameter(d: number): this {
+        this.diameter = d;
+        return this.rebuild();
+    }
+    setColor(c: Color | number | string): this {
+        this.color.set(c);
+        // 颜色走逐实例 instanceColor，与位姿无关 ⇒ 不动矩阵、不必 rebuild
+        for (const inst of this._allInstances()) inst.setColor(this.color);
+        return this;
+    }
+
+    // ===== JSON：对象与项目存档共用的形状 =====
+
+    /** 导出当前管道的 JSON 数据（不碰 three 的 Object3D 序列化格式，那个是场景树用的） */
+    exportJson(): PipeJson {
+        return makePipeJson(
+            this.points.map((p) => [p[0], p[1], p[2]] as Vec3),
+            this.diameter,
+            `#${this.color.getHexString()}`
+        );
+    }
+
+    /** 引用 JSON 重建当前管道：非法数据不动现场，返回人话原因 */
+    importJson(input: unknown): { ok: boolean; reason?: string } {
+        const parsed = parsePipeJson(input);
+        if (!parsed.ok || !parsed.json) return { ok: false, reason: parsed.reason ?? "JSON 解析失败" };
+        const json = parsed.json;
+        this.diameter = json.diameter;
+        if (json.color) this.color.set(json.color);
+        this.points = json.points.map((p) => [p[0], p[1], p[2]] as Vec3);
+        this.rebuild();
+        return { ok: true };
+    }
+
+    /** 用 JSON 起一个新管道对象；失败时 pipe 为 undefined，reason 可直接弹给用户 */
+    static fromJson(input: unknown): { pipe?: PipeMesh; ok: boolean; reason?: string } {
+        const parsed = parsePipeJson(input);
+        if (!parsed.ok || !parsed.json) return { ok: false, reason: parsed.reason ?? "JSON 解析失败" };
+        const json = parsed.json;
+        const pipe = new PipeMesh({
+            points: json.points,
+            diameter: json.diameter,
+            color: json.color,
+        });
+        return { pipe, ok: true };
+    }
+
+    /** 摘掉全部实例并释放注册表登记（组本身留在 scene 里由调用方 remove） */
+    dispose(): void {
+        for (const inst of this._allInstances()) {
+            this.remove(inst);
+            inst.dispose();
+        }
+        this.straights.length = 0;
+        this.joints.length = 0;
+    }
+}

package/PipeMesh/PipeStraight.d.ts

@@ -0,0 +1,19 @@
+import { CylinderGeometry } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+/**
+ * 直管实例：**直径 1、长度 1、沿 +Y、端面开口**的单位圆柱。
+ *
+ * 长度靠实例矩阵的 Y 缩放拉伸（非均匀缩放不伤法线：圆柱侧面法线是水平的，X/Z 缩放等比 ⇒ 方向不变；
+ * 端面本来就 openEnded 没有盖子），半径靠 X/Z 缩放，因此全场景只有这一份几何、一个 batch。
+ */
+export default class PipeStraight extends InstancedChild {
+    static geometry: CylinderGeometry;
+    static material: import("three").MeshStandardMaterial;
+    /** 控制台取证用：第几段直管（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex: number;
+    constructor();
+    /** 落到某段：中心位置 + 轴向 + [直径, 净长, 直径] 缩放 */
+    applyAt(center: [number, number, number], dir: [number, number, number], diameter: number, length: number): void;
+    /** 段序号变化时同步控制台名字（复用实例时避免留着上一段的编号） */
+    setPartIndex(i: number): void;
+}

package/PipeMesh/PipeStraight.js

@@ -0,0 +1,34 @@
+import { CylinderGeometry, Vector3 } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+import { pipeMaterial } from "./pipeMaterial";
+/** 单位圆柱的轴向：几何按 +Y 生成，实例旋转把 +Y 对到走线方向 */
+const UP = new Vector3(0, 1, 0);
+const _dir = new Vector3();
+/**
+ * 直管实例：**直径 1、长度 1、沿 +Y、端面开口**的单位圆柱。
+ *
+ * 长度靠实例矩阵的 Y 缩放拉伸（非均匀缩放不伤法线：圆柱侧面法线是水平的，X/Z 缩放等比 ⇒ 方向不变；
+ * 端面本来就 openEnded 没有盖子），半径靠 X/Z 缩放，因此全场景只有这一份几何、一个 batch。
+ */
+export default class PipeStraight extends InstancedChild {
+    static geometry = new CylinderGeometry(0.5, 0.5, 1, 48, 1, true);
+    static material = pipeMaterial;
+    /** 控制台取证用：第几段直管（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex = -1;
+    constructor() {
+        super();
+        this.type = "PipeStraight";
+        this.name = "PipeStraight";
+    }
+    /** 落到某段：中心位置 + 轴向 + [直径, 净长, 直径] 缩放 */
+    applyAt(center, dir, diameter, length) {
+        this.position.set(center[0], center[1], center[2]);
+        this.quaternion.setFromUnitVectors(UP, _dir.set(dir[0], dir[1], dir[2]));
+        this.scale.set(diameter, length, diameter);
+    }
+    /** 段序号变化时同步控制台名字（复用实例时避免留着上一段的编号） */
+    setPartIndex(i) {
+        this.partIndex = i;
+        this.name = `PipeStraight[${i}]`;
+    }
+}

package/PipeMesh/PipeStraight.ts

@@ -0,0 +1,45 @@
+import { CylinderGeometry, Vector3 } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+import { pipeMaterial } from "./pipeMaterial";
+
+/** 单位圆柱的轴向：几何按 +Y 生成，实例旋转把 +Y 对到走线方向 */
+const UP = new Vector3(0, 1, 0);
+const _dir = new Vector3();
+
+/**
+ * 直管实例：**直径 1、长度 1、沿 +Y、端面开口**的单位圆柱。
+ *
+ * 长度靠实例矩阵的 Y 缩放拉伸（非均匀缩放不伤法线：圆柱侧面法线是水平的，X/Z 缩放等比 ⇒ 方向不变；
+ * 端面本来就 openEnded 没有盖子），半径靠 X/Z 缩放，因此全场景只有这一份几何、一个 batch。
+ */
+export default class PipeStraight extends InstancedChild {
+    static geometry = new CylinderGeometry(0.5, 0.5, 1, 48, 1, true);
+    static material = pipeMaterial;
+
+    /** 控制台取证用：第几段直管（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex: number = -1;
+
+    constructor() {
+        super();
+        (this as { type: string }).type = "PipeStraight";
+        this.name = "PipeStraight";
+    }
+
+    /** 落到某段：中心位置 + 轴向 + [直径, 净长, 直径] 缩放 */
+    applyAt(
+        center: [number, number, number],
+        dir: [number, number, number],
+        diameter: number,
+        length: number
+    ): void {
+        this.position.set(center[0], center[1], center[2]);
+        this.quaternion.setFromUnitVectors(UP, _dir.set(dir[0], dir[1], dir[2]));
+        this.scale.set(diameter, length, diameter);
+    }
+
+    /** 段序号变化时同步控制台名字（复用实例时避免留着上一段的编号） */
+    setPartIndex(i: number): void {
+        this.partIndex = i;
+        this.name = `PipeStraight[${i}]`;
+    }
+}

package/PipeMesh/axisSnap.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 控制点轴向吸附（纯数字，零运行时依赖）。
+ *
+ * 皇上旨 2026-10-25：「添加节点和编辑节点的时候，实时计算当前节点在 x/y/z 轴上的投影距离，
+ * 距离谁最近就改到哪里，让管道随时保持横平竖直。」
+ *
+ * ⭐ 什么叫「投影到轴上」——不是投影到世界坐标轴，而是投影到**过参考点（相邻控制点）的三条轴线**：
+ *   三条候选各保留一个坐标、另两个坐标抄参考点：
+ *     只沿 X 走 ⇒ [p.x, ref.y, ref.z]，偏离量 = √(Δy² + Δz²)
+ *     只沿 Y 走 ⇒ [ref.x, p.y, ref.z]，偏离量 = √(Δx² + Δz²)
+ *     只沿 Z 走 ⇒ [ref.x, ref.y, p.z]，偏离量 = √(Δx² + Δy²)
+ *   取偏离量最小的那条 ⇒ 该段只剩一根轴有位移 ⇒ 横平竖直。
+ *
+ * ⚠️ 三个候选都**保留待吸附点自身的那根轴坐标**（比如「只沿 X」保留 p.x）——这是关键：
+ *   沿 X 箭头拖动时 p.x 能自由变化，吸附不会把点钉死；被拉回的只是另外两根轴的偏移。
+ *
+ * ⚠️ 这里改的是**控制点本身**（数据层），不是走线算术：PipeMesh 仍是相邻点直连（directRoute.ts），
+ *   只是点的位置被挪到轴线上。⛔ 别在这里插折点 —— 那是已删除的 orthogonalRoute 老路，
+ *   两件事的区别是：正交走线「自动加拐点把斜线拆成三段」，这里是「把点挪正，段还是那一段」。
+ *
+ * 留成零运行时依赖（只用 `import type`，编译时擦除）⇒ `test/pipeRoute.test.js` 能直接 require
+ * 编译产物逐条断言，不必起浏览器。
+ */
+import type { Vec3 } from "./directRoute";
+/** 轴名（与编辑页面板的 X / Y / Z 三行同口径） */
+export type AxisName = "x" | "y" | "z";
+/** 吸附结果：落点 + 保留的轴 + 原位置到落点的欧氏距离 */
+export interface AxisSnapResult {
+    /** 吸附后的位置（新数组，不改入参） */
+    point: Vec3;
+    /** 被保留（即该段唯一有位移）的轴；另两根轴已对齐到参考点 */
+    axis: AxisName;
+    /** 原位置到吸附位置的欧氏距离（米）= 这次「挪了多少」 */
+    distance: number;
+}
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export declare function snapAlongAxis(p: Vec3, ref: Vec3, axis: AxisName): Vec3;
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export declare function snapToNearestAxis(p: Vec3, ref: Vec3): AxisSnapResult;
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export declare function isAxisAligned(a: Vec3, b: Vec3, eps?: number): boolean;

package/PipeMesh/axisSnap.js

@@ -0,0 +1,52 @@
+/** 轴名 → 分量下标 */
+const AXIS_INDEX = { x: 0, y: 1, z: 2 };
+/**
+ * 候选顺序固定 x → y → z。
+ * 偏离量打平时（浮点噪声级）保留先出现的那个 ⇒ 结果可复现，不会因为一次 1e-17 的抖动换轴。
+ */
+const AXIS_ORDER = ["x", "y", "z"];
+/** 判定「两轴坐标相同」的容差（与走线模块的 PIPE_EPS 同量级） */
+const ALIGN_EPS = 1e-6;
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export function snapAlongAxis(p, ref, axis) {
+    const k = AXIS_INDEX[axis];
+    const q = [ref[0], ref[1], ref[2]];
+    q[k] = p[k];
+    return q;
+}
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export function snapToNearestAxis(p, ref) {
+    let best = null;
+    for (const axis of AXIS_ORDER) {
+        const point = snapAlongAxis(p, ref, axis);
+        const dx = point[0] - p[0];
+        const dy = point[1] - p[1];
+        const dz = point[2] - p[2];
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        // 用「严格小于」+ 容差：平局时保留先出现的轴，不被浮点噪声换来换去
+        if (!best || distance < best.distance - 1e-12)
+            best = { point, axis, distance };
+    }
+    // 循环一定跑过一轮 ⇒ best 非空；写这个兜底只为满足 strict 关闭时的可读性
+    return best;
+}
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export function isAxisAligned(a, b, eps = ALIGN_EPS) {
+    let same = 0;
+    for (let i = 0; i < 3; i++) {
+        if (Math.abs(a[i] - b[i]) < eps)
+            same++;
+    }
+    return same >= 2;
+}

package/PipeMesh/axisSnap.ts

@@ -0,0 +1,93 @@
+/**
+ * 控制点轴向吸附（纯数字，零运行时依赖）。
+ *
+ * 皇上旨 2026-10-25：「添加节点和编辑节点的时候，实时计算当前节点在 x/y/z 轴上的投影距离，
+ * 距离谁最近就改到哪里，让管道随时保持横平竖直。」
+ *
+ * ⭐ 什么叫「投影到轴上」——不是投影到世界坐标轴，而是投影到**过参考点（相邻控制点）的三条轴线**：
+ *   三条候选各保留一个坐标、另两个坐标抄参考点：
+ *     只沿 X 走 ⇒ [p.x, ref.y, ref.z]，偏离量 = √(Δy² + Δz²)
+ *     只沿 Y 走 ⇒ [ref.x, p.y, ref.z]，偏离量 = √(Δx² + Δz²)
+ *     只沿 Z 走 ⇒ [ref.x, ref.y, p.z]，偏离量 = √(Δx² + Δy²)
+ *   取偏离量最小的那条 ⇒ 该段只剩一根轴有位移 ⇒ 横平竖直。
+ *
+ * ⚠️ 三个候选都**保留待吸附点自身的那根轴坐标**（比如「只沿 X」保留 p.x）——这是关键：
+ *   沿 X 箭头拖动时 p.x 能自由变化，吸附不会把点钉死；被拉回的只是另外两根轴的偏移。
+ *
+ * ⚠️ 这里改的是**控制点本身**（数据层），不是走线算术：PipeMesh 仍是相邻点直连（directRoute.ts），
+ *   只是点的位置被挪到轴线上。⛔ 别在这里插折点 —— 那是已删除的 orthogonalRoute 老路，
+ *   两件事的区别是：正交走线「自动加拐点把斜线拆成三段」，这里是「把点挪正，段还是那一段」。
+ *
+ * 留成零运行时依赖（只用 `import type`，编译时擦除）⇒ `test/pipeRoute.test.js` 能直接 require
+ * 编译产物逐条断言，不必起浏览器。
+ */
+import type { Vec3 } from "./directRoute";
+
+/** 轴名（与编辑页面板的 X / Y / Z 三行同口径） */
+export type AxisName = "x" | "y" | "z";
+
+/** 吸附结果：落点 + 保留的轴 + 原位置到落点的欧氏距离 */
+export interface AxisSnapResult {
+    /** 吸附后的位置（新数组，不改入参） */
+    point: Vec3;
+    /** 被保留（即该段唯一有位移）的轴；另两根轴已对齐到参考点 */
+    axis: AxisName;
+    /** 原位置到吸附位置的欧氏距离（米）= 这次「挪了多少」 */
+    distance: number;
+}
+
+/** 轴名 → 分量下标 */
+const AXIS_INDEX: Record<AxisName, 0 | 1 | 2> = { x: 0, y: 1, z: 2 };
+
+/**
+ * 候选顺序固定 x → y → z。
+ * 偏离量打平时（浮点噪声级）保留先出现的那个 ⇒ 结果可复现，不会因为一次 1e-17 的抖动换轴。
+ */
+const AXIS_ORDER: AxisName[] = ["x", "y", "z"];
+
+/** 判定「两轴坐标相同」的容差（与走线模块的 PIPE_EPS 同量级） */
+const ALIGN_EPS = 1e-6;
+
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export function snapAlongAxis(p: Vec3, ref: Vec3, axis: AxisName): Vec3 {
+    const k = AXIS_INDEX[axis];
+    const q: Vec3 = [ref[0], ref[1], ref[2]];
+    q[k] = p[k];
+    return q;
+}
+
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export function snapToNearestAxis(p: Vec3, ref: Vec3): AxisSnapResult {
+    let best: AxisSnapResult | null = null;
+    for (const axis of AXIS_ORDER) {
+        const point = snapAlongAxis(p, ref, axis);
+        const dx = point[0] - p[0];
+        const dy = point[1] - p[1];
+        const dz = point[2] - p[2];
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        // 用「严格小于」+ 容差：平局时保留先出现的轴，不被浮点噪声换来换去
+        if (!best || distance < best.distance - 1e-12) best = { point, axis, distance };
+    }
+    // 循环一定跑过一轮 ⇒ best 非空；写这个兜底只为满足 strict 关闭时的可读性
+    return best as AxisSnapResult;
+}
+
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export function isAxisAligned(a: Vec3, b: Vec3, eps = ALIGN_EPS): boolean {
+    let same = 0;
+    for (let i = 0; i < 3; i++) {
+        if (Math.abs(a[i] - b[i]) < eps) same++;
+    }
+    return same >= 2;
+}