three-base 2.0.175 → 2.0.180

package/MktMesh/imagePlane.ts

@@ -0,0 +1,203 @@
+/*
+ * @Description: 图片平面元素 —— 皇上旨 2026-10-20「先添加一个平面, 再给这个平面上传图片,
+ *   上传的这个图切成 4*4=16 片, 加载的时候也是一帧载入一片」→ 2026-10-21 改口「切成 2*2=4 份，
+ *   不用切成 16 份了」。片数只在库里那一个 `IMAGE_TILE_GRID` 常数上，本文件⛔ 不写数字。
+ *
+ * 设计：
+ * - 独立 Mesh（非 InstancedChild）：每张图片各有自己的 4 张瓦片纹理 ⇒ 材质实例不可共用，不合批。
+ * - 材质 MeshBasicMaterial + FrontSide（皇上旨 2026-10-22「添加的平面图片元素只要单面可见就行了，双面不需要」）：
+ *   平面本身不承受光照（贴图内容自带明暗）。单面 ⇒ 背面既不画也打不中（three 的射线拾取按材质 side 剔背面，
+ *   `node_modules/three/src/objects/Mesh.js:343`），与渲染共用同一条式子 ⇒ 站在这一面的反面既看不见也选不中。
+ * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
+ * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
+ *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
+ *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
+ * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
+ */
+import {
+    Color,
+    DataTexture,
+    FrontSide,
+    Mesh,
+    MeshBasicMaterial,
+    PlaneGeometry,
+    RGBAFormat,
+    Texture,
+    Vector4,
+} from "three";
+
+/*
+ * ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+ * 片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+ * 占位 1×1 灰纹理：sampler 必须绑定有效纹理（未就绪片绑定它、但片元 `uValid` 为 0 时不采样它）。
+ */
+const PLACEHOLDER_TEX: Texture = (() => {
+    const t = new DataTexture(new Uint8Array([204, 204, 204, 255]), 1, 1, RGBAFormat);
+    t.needsUpdate = true;
+    return t;
+})();
+const ZERO_INSET = new Vector4(0, 0, 1, 1);
+
+/**
+ * 皇上旨 2026-10-23「添加的平面 有点隐隐的 边框, 你在代码里面写一下, 把边框的那一点点 discrad 掉」。
+ * 整张图**外圈**这一条 UV 余量在片元里一刀 `discard` 掉 —— 边框那一圈来自裁片留下的描边/柔边像素
+ * （`alphaTest` 砍不到它：那圈像素的 alpha 高于阈值 —— 0.2 / 0.9 / 0.3 这几档都留得住它，只是颜色比内容浅，于是画成实心的一圈浅边）。
+ * 只切外圈：内部那 2×2 拼缝归每片自己的 inset 采样窗口管，两把刀互不重叠。
+ * ⚠️ 这一档是**比例**不是毫米：默认平面 2×1.5 m ⇒ 横着每边切 8 mm、竖着每边切 6 mm。尺只许写在这一处。
+ */
+export const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
+const EDGE_MAX_UV = 1 - IMAGE_PLANE_EDGE_CLIP_UV;
+
+/** 片元打补丁：4 张瓦片按 UV 象限选片，缺图那片显示灰（与旧缺失灰同一观感）。索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
+const IMG_PLANE_MAP_FRAG = `
+    if ( vUv.x < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.x > ${EDGE_MAX_UV} || vUv.y < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.y > ${EDGE_MAX_UV} ) discard;
+    vec4 imgTexel = vec4(0.8, 0.8, 0.8, 1.0); // 缺图灰
+    vec2 cell = floor(vUv * 2.0);
+    vec2 local = fract(vUv * 2.0);
+    if (cell.y >= 0.5 && cell.x < 0.5) {
+        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y >= 0.5 && cell.x >= 0.5) {
+        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y < 0.5 && cell.x < 0.5) {
+        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); }
+    } else {
+        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); }
+    }
+    diffuseColor *= imgTexel;
+`;
+
+/** 图片平面的持久化数据（进 exportData / importData） */
+export interface ImagePlaneData {
+    name?: string;
+    position: { x: number; y: number; z: number };
+    rotation: { x: number; y: number; z: number };
+    width: number;
+    height: number;
+    /** 原图地址（上传后返回的 origin URL，缩略图展示用） */
+    url: string;
+    /** 瓦片地址（行优先、图像左上起；张数 = 库里 `IMAGE_TILE_GRID` 的 cols×rows，10-21 旨 = 2×2=4） */
+    tiles: string[];
+    /** 原图自然像素宽（瓦片纹理实际像素，算 inset 采样窗口需要） */
+    naturalW?: number;
+    /** 原图自然像素高 */
+    naturalH?: number;
+}
+
+const DEFAULT_WIDTH = 2;
+const DEFAULT_HEIGHT = 1.5;
+const HIGHLIGHT_COLOR = "#ffd24a";
+
+export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
+    private _originalColor: string = "#ffffff";
+    private _uTiles!: { value: Texture[] };
+    private _uInset!: { value: Vector4[] };
+    private _uValid!: { value: number[] };
+    private _data: Omit<ImagePlaneData, "position" | "rotation" | "width" | "height"> = {
+        url: "",
+        tiles: [],
+    };
+
+    constructor(name?: string) {
+        const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
+        const mat = new MeshBasicMaterial({
+            color: new Color("#ffffff"),
+            side: FrontSide,
+            // 皇上旨 2026-10-21「平面的材质需要设置 alphaTest = 0.2」⇒ 同日 10-23 两次改口（先 0.9、后 **0.3**）：
+            // alpha 不足阈值的像素丢弃，其余实心。0.9 那一档会把图上半透的内容也切掉，现停在 0.3。
+            // ⛔ 这个构造里不许再写「走半透明通道」与「不透明度数值」那两行：皇上 10-22 点名「没有说过要设置透明度」，
+            //   那是臣 10-21 建这个类时擅自加的（没问过），当日整条删除。平面恒走不透明通道，
+            //   要「透」只能靠 alphaTest 这一刀切掉。
+            alphaTest: 0.3,
+        });
+        // ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+        //   片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰。
+        mat.defines = { USE_UV: "" };
+        const uTiles = { value: [PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX] as Texture[] };
+        const uInset = { value: [ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone()] };
+        const uValid = { value: [0, 0, 0, 0] };
+        mat.onBeforeCompile = (shader) => {
+            shader.uniforms.uTiles = uTiles;
+            shader.uniforms.uInset = uInset;
+            shader.uniforms.uValid = uValid;
+            shader.fragmentShader = shader.fragmentShader
+                .replace(
+                    "#include <common>",
+                    `#include <common>
+                    uniform sampler2D uTiles[4];
+                    uniform vec4 uInset[4];
+                    uniform float uValid[4];`
+                )
+                .replace("#include <map_fragment>", IMG_PLANE_MAP_FRAG);
+        };
+        super(geo, mat);
+        this._uTiles = uTiles;
+        this._uInset = uInset;
+        this._uValid = uValid;
+        this.name = name || "图片平面";
+    }
+
+    get imageWidth(): number { return (this.geometry as PlaneGeometry).parameters.width; }
+    get imageHeight(): number { return (this.geometry as PlaneGeometry).parameters.height; }
+
+    setPlaneSize(w: number, h: number): void {
+        this.geometry.dispose();
+        this.geometry = new PlaneGeometry(w, h);
+    }
+
+    setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void {
+        this._data = { url: d.url, tiles: d.tiles, naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+
+    get tiles(): string[] { return this._data.tiles; }
+    get url(): string { return this._data.url; }
+    get naturalW(): number | undefined { return this._data.naturalW; }
+    get naturalH(): number | undefined { return this._data.naturalH; }
+
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void {
+        for (let i = 0; i < 4; i++) {
+            const t = texs[i] || null;
+            this._uTiles.value[i] = t || PLACEHOLDER_TEX;
+            if (insets[i]) this._uInset.value[i].copy(insets[i]);
+            this._uValid.value[i] = t ? 1 : 0;
+        }
+    }
+
+    highlight(): void {
+        this.material.color.set(HIGHLIGHT_COLOR);
+    }
+
+    restoreColor(): void {
+        this.material.color.set(this._originalColor);
+    }
+
+    toData(): ImagePlaneData {
+        return {
+            name: this.name || undefined,
+            position: { x: this.position.x, y: this.position.y, z: this.position.z },
+            rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
+            width: this.imageWidth,
+            height: this.imageHeight,
+            url: this._data.url,
+            tiles: this._data.tiles,
+            naturalW: this._data.naturalW,
+            naturalH: this._data.naturalH,
+        };
+    }
+
+    applyData(d: ImagePlaneData): void {
+        if (d.name) this.name = d.name;
+        this.position.set(d.position.x, d.position.y, d.position.z);
+        this.rotation.set(d.rotation.x, d.rotation.y, d.rotation.z);
+        this.setPlaneSize(d.width, d.height);
+        this._data = { url: d.url, tiles: d.tiles || [], naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+
+    dispose(): void {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+
+export const IMAGE_PLANE_DEFAULTS = { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT };

package/MktMesh/imageTileLoader.d.ts

@@ -0,0 +1,19 @@
+import { Texture, Vector4 } from "three";
+interface TileEntry {
+    tex: Texture | null;
+    w: number;
+    h: number;
+}
+export declare class ImagePlaneTileLoader {
+    private cache;
+    private inflight;
+    /** 触发某张瓦片下载 + 解码（已缓存 / 在途则跳过）；完成后填入 cache，下一帧 feed 即取到 */
+    preload(url: string): void;
+    /** 取已就绪的瓦片（未就绪返回 null） */
+    get(url: string): TileEntry | null;
+    /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
+    inset(entry: TileEntry, i: number): Vector4;
+    /** 释放本 loader 持有的全部瓦片纹理（项目重置 / 卸载场景时调用；⛔ 不关共享占位纹理） */
+    clear(): void;
+}
+export {};

package/MktMesh/imageTileLoader.js

@@ -0,0 +1,55 @@
+/*
+ * @Description: 图片平面（「加平面」）的瓦片纹理加载器 —— ⭐ 2026-10-22 晚旨配套：图片平面**不用拼合器 RT**，
+ * 直接把上传切好的 4 张瓦片纹理绑到材质。本类负责「按 url 下载 + 异步解码 + 缓存在本 renderer 上下文」，
+ * 并把第 i 片的采样窗口（inset）算好交出去。
+ *
+ * 设计要点：
+ * - 纹理是 **WebGL 上下文私有**资源：编辑页 / 预览页各持一个实例（各自 GL context），⛔ 不跨 renderer 共享同一 Texture。
+ * - 复用库里 `loadPanoTexture`（fetch + createImageBitmap 工作线程解码、`imageOrientation:"flipY"` 预翻 + flipY=false，
+ *   与全景同一套上下翻约定）；本类只补 `colorSpace = SRGBColorSpace`（硬件采样即解 sRGB→linear，与旧 RT 方案逐字节同口径）。
+ * - inset 用库的 `rtStitchTileInset(i, tw, th, IMAGE_TILE_GRID)`：上传多切 8px、采样只取中间干净块 ⇒ 接缝不回潮，
+ *   与上传切片 `rtStitchTileRects` 共用同一份几何（⛔ 不许在这里另算一份）。
+ * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质显示灰），下一帧就绪后即亮。
+ */
+import { SRGBColorSpace, Vector4 } from "three";
+import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+import { IMAGE_TILE_GRID, rtStitchTileInset } from "./mktShader";
+export class ImagePlaneTileLoader {
+    cache = new Map();
+    inflight = new Map();
+    /** 触发某张瓦片下载 + 解码（已缓存 / 在途则跳过）；完成后填入 cache，下一帧 feed 即取到 */
+    preload(url) {
+        if (!url || this.cache.has(url) || this.inflight.has(url))
+            return;
+        const p = loadPanoTexture(url)
+            .then((tex) => {
+            tex.colorSpace = SRGBColorSpace; // 硬件采样解 sRGB→linear（与旧 RT 方案逐字节同口径）
+            const img = tex.image;
+            this.cache.set(url, { tex, w: img?.width ?? 0, h: img?.height ?? 0 });
+        })
+            .catch(() => {
+            // 下载 / 解码失败：留空，下一帧 preload 重新触发（不把半截纹理绑上去）
+        })
+            .finally(() => {
+            this.inflight.delete(url);
+        });
+        this.inflight.set(url, p);
+    }
+    /** 取已就绪的瓦片（未就绪返回 null） */
+    get(url) {
+        return this.cache.get(url) || null;
+    }
+    /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
+    inset(entry, i) {
+        if (!entry.w || !entry.h)
+            return new Vector4(0, 0, 1, 1);
+        const [u0, v0, u1, v1] = rtStitchTileInset(i, entry.w, entry.h, IMAGE_TILE_GRID);
+        return new Vector4(u0, v0, u1, v1);
+    }
+    /** 释放本 loader 持有的全部瓦片纹理（项目重置 / 卸载场景时调用；⛔ 不关共享占位纹理） */
+    clear() {
+        this.cache.forEach((e) => e.tex && releasePanoTexture(e.tex));
+        this.cache.clear();
+        this.inflight.clear();
+    }
+}

package/MktMesh/imageTileLoader.ts

@@ -0,0 +1,64 @@
+/*
+ * @Description: 图片平面（「加平面」）的瓦片纹理加载器 —— ⭐ 2026-10-22 晚旨配套：图片平面**不用拼合器 RT**，
+ * 直接把上传切好的 4 张瓦片纹理绑到材质。本类负责「按 url 下载 + 异步解码 + 缓存在本 renderer 上下文」，
+ * 并把第 i 片的采样窗口（inset）算好交出去。
+ *
+ * 设计要点：
+ * - 纹理是 **WebGL 上下文私有**资源：编辑页 / 预览页各持一个实例（各自 GL context），⛔ 不跨 renderer 共享同一 Texture。
+ * - 复用库里 `loadPanoTexture`（fetch + createImageBitmap 工作线程解码、`imageOrientation:"flipY"` 预翻 + flipY=false，
+ *   与全景同一套上下翻约定）；本类只补 `colorSpace = SRGBColorSpace`（硬件采样即解 sRGB→linear，与旧 RT 方案逐字节同口径）。
+ * - inset 用库的 `rtStitchTileInset(i, tw, th, IMAGE_TILE_GRID)`：上传多切 8px、采样只取中间干净块 ⇒ 接缝不回潮，
+ *   与上传切片 `rtStitchTileRects` 共用同一份几何（⛔ 不许在这里另算一份）。
+ * - 逐张就绪、逐张显影：未就绪那张 `get()` 返回 null ⇒ 调方把那片传 null（材质显示灰），下一帧就绪后即亮。
+ */
+import { SRGBColorSpace, Texture, Vector4 } from "three";
+import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
+import { IMAGE_TILE_GRID, rtStitchTileInset } from "./mktShader";
+
+interface TileEntry {
+    tex: Texture | null;
+    w: number;
+    h: number;
+}
+
+export class ImagePlaneTileLoader {
+    private cache = new Map<string, TileEntry>();
+    private inflight = new Map<string, Promise<void>>();
+
+    /** 触发某张瓦片下载 + 解码（已缓存 / 在途则跳过）；完成后填入 cache，下一帧 feed 即取到 */
+    preload(url: string): void {
+        if (!url || this.cache.has(url) || this.inflight.has(url)) return;
+        const p = loadPanoTexture(url)
+            .then((tex) => {
+                tex.colorSpace = SRGBColorSpace; // 硬件采样解 sRGB→linear（与旧 RT 方案逐字节同口径）
+                const img = tex.image as { width?: number; height?: number } | undefined;
+                this.cache.set(url, { tex, w: img?.width ?? 0, h: img?.height ?? 0 });
+            })
+            .catch(() => {
+                // 下载 / 解码失败：留空，下一帧 preload 重新触发（不把半截纹理绑上去）
+            })
+            .finally(() => {
+                this.inflight.delete(url);
+            });
+        this.inflight.set(url, p);
+    }
+
+    /** 取已就绪的瓦片（未就绪返回 null） */
+    get(url: string): TileEntry | null {
+        return this.cache.get(url) || null;
+    }
+
+    /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
+    inset(entry: TileEntry, i: number): Vector4 {
+        if (!entry.w || !entry.h) return new Vector4(0, 0, 1, 1);
+        const [u0, v0, u1, v1] = rtStitchTileInset(i, entry.w, entry.h, IMAGE_TILE_GRID);
+        return new Vector4(u0, v0, u1, v1);
+    }
+
+    /** 释放本 loader 持有的全部瓦片纹理（项目重置 / 卸载场景时调用；⛔ 不关共享占位纹理） */
+    clear(): void {
+        this.cache.forEach((e) => e.tex && releasePanoTexture(e.tex));
+        this.cache.clear();
+        this.inflight.clear();
+    }
+}

package/MktMesh/modelSlot.d.ts

@@ -0,0 +1,123 @@
+import { Group } from "three";
+/** 模型槽的持久化数据（进 exportData / importData / 预览 loadData） */
+export interface ModelSlotData {
+    name?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** 归一化后模型最长边的实际米数（GLB 按包围盒等比缩到这里；上传时那一档自动填成模型原最长边 ⇒ 一比一） */
+    size: number;
+    /** glb 地址；空串 = 还没上传 ⇒ 画面显示占位小立方体 */
+    url: string;
+    /** 落在地面还是墙面（决定占位方块的落位与落点口径；10-22 旨之后**不再**挪动用户上传模型的位置） */
+    surface: "floor" | "wall";
+    /** 模型原始包围盒尺寸（米，在 GLB 根节点**原姿势**下量，归一之前）—— 面板显示「原模型多大」用 */
+    naturalSize?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** 占位小立方体的棱长（米）—— 皇上要的是「小立方体」，比「加立方体」那颗 1m 的单位方块小一档 */
+export declare const MODEL_SLOT_PLACEHOLDER = 0.3;
+/** 默认尺寸档（米，最长边）：还没上传模型时占位方块用不上它；上传成功后 `useNativeSize()` 会把它填成模型原最长边 ⇒ 一比一 */
+export declare const MODEL_SLOT_DEFAULT_SIZE = 1;
+/** 墙面落点沿法线外推的距离（米）：模型中心压在墙面上会让一半陷进墙皮，且贴墙的平面片会 z-fighting */
+export declare const MODEL_SLOT_WALL_OFFSET = 0.02;
+export declare class ModelSlot extends Group {
+    /** 拾取路由用标记（与 three 的 `isInstancedMesh` 同款判据）：射线命中任意子对象后向上找带这个标记的祖先 */
+    readonly isModelSlot = true;
+    /** 占位小立方体（未上传模型时可见） */
+    private readonly _placeholder;
+    /** GLB 挂载点：内容在这里被等比归一（10-22 旨之后位置保持 GLB 原生，⛔ 不再挪） */
+    private readonly _contentRoot;
+    /**
+     * 选中高亮框（贴合当前内容的包围盒；10-22 旨整搬 archives2026 的 `BoxLine2`）。
+     * ⚠️ 懒建 —— null = 这个槽从没被选中过（预览那一路永远是 null）；⛔ 不参与射线拾取（见 `pickIgnored`）。
+     */
+    private _box;
+    /** 高亮框该套在哪、套多大（`_layout()` 每次算好存这里；框还没建起来时先记着，`highlight()` 建好再贴） */
+    private _boxFit;
+    /** 当前 GLB 子树；null = 没有模型（显示占位方块） */
+    private _model;
+    /**
+     * GLB **载入时的原姿势**（根节点自带的那份 scale/position，导出器常在根上带 cm→m 单位换算缩放）。
+     * ⚠️ 每次排布都先从这两个值复位再量再归一 ⇒ 「原尺寸」有唯一基准，且第二次 `_layout()` 不会量到
+     *   上一次 `scaleTo` 之后的盒子（那是重复缩放的源头）。`_baseFor` 记录这份基准属于哪一棵子树（换模型要重取）。
+     */
+    private _baseFor;
+    private _baseScale;
+    private _basePos;
+    private _url;
+    private _size;
+    private _surface;
+    private _naturalSize?;
+    /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
+    private _loadToken;
+    private _disposed;
+    constructor(name?: string);
+    get size(): number;
+    get url(): string;
+    get surface(): "floor" | "wall";
+    get naturalSize(): {
+        x: number;
+        y: number;
+        z: number;
+    } | undefined;
+    /** 是否已经挂上真模型（false = 仍是占位小立方体） */
+    get hasModel(): boolean;
+    /** 改尺寸档（米，最长边）：立刻重缩内容 */
+    setSize(size: number): void;
+    /**
+     * 把尺寸档填成**模型自己的原最长边** ⇒ 之后那步归一算出的倍率正好是 1 ⇒ 画面上一比一，⛔ 不改模型大小。
+     * ⭐ 皇上旨 2026-10-21「上传模型的时候，不要去修改模型的大小」：只给**上传**那一路调（渲染器 `setModelGlb`）；
+     *   存档导入 / 预览重建那一路**不能**调，否则他在面板里存的尺寸每次重开项目都被抹回原大小。
+     * @returns 是否真的改动了（还没挂上模型 ⇒ false，尺寸档保持原样）
+     */
+    useNativeSize(): boolean;
+    /** 改落点面（地面/墙面）：重摆占位方块的落位 + 重算高亮框（用户上传的模型位置不动，见 10-22 旨） */
+    setSurface(surface: "floor" | "wall"): void;
+    /**
+     * 载入并挂上 GLB（`url` 必须是可直接 fetch 的绝对地址；空串 = 退回占位小立方体）。
+     * @returns 是否真的挂上了（地址无效/载入失败/这次结果已作废 ⇒ false）
+     */
+    setModelUrl(url: string): Promise<boolean>;
+    /**
+     * 把存档里的数据写进来（位置 / 旋转 / 尺寸 / 落点面 / 地址）。
+     * ⚠️ 刻意**不**在这里发起 GLB 载入：载入是异步的，落地那一刻必须由调用方（编辑器导入 / 预览）
+     *   显式标脏才能画出来 —— 换成 `modelRoot` 的子对象不改任何材质版本号。
+     *   故本方法只把 `url` 记好，取模型由调用方 `setModelUrl(d.url).then(...)` 驱动（⛔ 别在这儿偷偷 void）。
+     */
+    applyData(d: ModelSlotData): void;
+    toData(): ModelSlotData;
+    highlight(): void;
+    restoreColor(): void;
+    dispose(): void;
+    /**
+     * 取出（并第一次需要时建起）高亮框：挂进槽、贴上最近一次算好的包围盒。
+     * ⚠️ 建好即 `visible = false` —— 调用方拿到对象后自己决定亮不亮（`highlight()` 里点亮）。
+     */
+    private _ensureBox;
+    /** 把 `_boxFit` 写进框（尺寸 = 包围盒外扩 `BOX_FIT_SCALE`，中心 = 本槽局部系下的盒心） */
+    private _applyBoxFit;
+    /** 摘掉 GLB（几何/材质/贴图一起释放，否则换一只模型就漏一份显存） */
+    private _detachModel;
+    /**
+     * 内容排布的唯一出口：GLB 等比归一 + 占位方块显隐 + 高亮框贴合（⛔ 不再挪模型的位置，见 `_layoutNeutral`）。
+     * ⚠️ 每次改 size / surface / 模型都要走这里（⛔ 别在别处直接写 `_contentRoot.position`）。
+     * ⚠️ 皇上旨 2026-10-21「模型的位置和对应的边框不在一起」：这段曾把 `Box3.setFromObject` 量到的
+     *   **世界**盒子直接写进子对象的**局部** `position`（内容补偿与框中心都是），于是槽离原点越远偏得越远
+     *   —— 框比模型多偏一整份槽的位置。归一与套框两件事都只该**相对本槽**算，故量之前先把槽自身的位移与
+     *   旋转摘掉，算完原样装回（10-22 旨删掉内容补偿后，这把「摘了再装回」的尺仍要为高亮框留着）。
+     */
+    private _layout;
+    /** 只在「本槽自身位移/旋转已摘除」的世界帧里跑 ⇒ 下面量的每个盒子都等于相对本槽的盒子 */
+    private _layoutNeutral;
+}