@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/presetThumbGeometry.js

@@ -0,0 +1,103 @@
+import { presetPoints } from './pathPresets';
+export const THUMB_VW = 100;
+export const THUMB_VH = 64;
+/** 四周留白:取景锥探出路径边缘,要多留一点 */
+const PAD = 12;
+const COS30 = Math.cos(Math.PI / 6);
+/** 3/4 轴测投影:y 直上,x/z 各向左右下方退 */
+function project(p) {
+    return [(p.x - p.z) * COS30, -p.y + (p.x + p.z) * 0.3];
+}
+/** 地面投影:压掉高度 */
+function projectGround(p) {
+    return project({ x: p.x, y: 0, z: p.z });
+}
+/** Catmull-Rom → 三次贝塞尔;closed 时首尾环绕 */
+export function smoothPath(pts, closed) {
+    const n = pts.length;
+    if (n < 2)
+        return '';
+    if (n === 2)
+        return `M ${pts[0][0]} ${pts[0][1]} L ${pts[1][0].toFixed(1)} ${pts[1][1].toFixed(1)}`;
+    const get = (i) => closed ? pts[(i + n) % n] : pts[Math.max(0, Math.min(n - 1, i))];
+    let d = `M ${pts[0][0].toFixed(1)} ${pts[0][1].toFixed(1)}`;
+    const segs = closed ? n : n - 1;
+    for (let i = 0; i < segs; i++) {
+        const p0 = get(i - 1);
+        const p1 = get(i);
+        const p2 = get(i + 1);
+        const p3 = get(i + 2);
+        const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
+        const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
+        d += ` C ${c1[0].toFixed(1)} ${c1[1].toFixed(1)} ${c2[0].toFixed(1)} ${c2[1].toFixed(1)} ${p2[0].toFixed(1)} ${p2[1].toFixed(1)}`;
+    }
+    return d + (closed ? ' Z' : '');
+}
+/** 以原点为落点生成预设的缩略图几何 */
+export function buildPresetThumb(preset) {
+    const pts = presetPoints(preset, { x: 0, y: 0, z: 0 });
+    const path2 = pts.map(project);
+    const ground2 = pts.map(projectGround);
+    // 网格范围:包住路径地面投影和原点,向外取整扩 2
+    let gx0 = 0;
+    let gx1 = 0;
+    let gz0 = 0;
+    let gz1 = 0;
+    for (const q of pts) {
+        gx0 = Math.min(gx0, q.x);
+        gx1 = Math.max(gx1, q.x);
+        gz0 = Math.min(gz0, q.z);
+        gz1 = Math.max(gz1, q.z);
+    }
+    gx0 = Math.floor(gx0) - 2;
+    gx1 = Math.ceil(gx1) + 2;
+    gz0 = Math.floor(gz0) - 2;
+    gz1 = Math.ceil(gz1) + 2;
+    const gridLines = [];
+    for (let x = gx0; x <= gx1; x += 2) {
+        gridLines.push([
+            projectGround({ x, y: 0, z: gz0 }),
+            projectGround({ x, y: 0, z: gz1 }),
+        ]);
+    }
+    for (let z = gz0; z <= gz1; z += 2) {
+        gridLines.push([
+            projectGround({ x: gx0, y: 0, z }),
+            projectGround({ x: gx1, y: 0, z }),
+        ]);
+    }
+    // 统一归一化:路径(含高度)+ 地面投影 + 网格一起进框
+    const all = [...path2, ...ground2, ...gridLines.flat()];
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const [x, y] of all) {
+        minX = Math.min(minX, x);
+        maxX = Math.max(maxX, x);
+        minY = Math.min(minY, y);
+        maxY = Math.max(maxY, y);
+    }
+    const w = maxX - minX || 1;
+    const h = maxY - minY || 1;
+    const s = Math.min((THUMB_VW - PAD * 2) / w, (THUMB_VH - PAD * 2) / h);
+    const ox = (THUMB_VW - w * s) / 2;
+    const oy = (THUMB_VH - h * s) / 2;
+    const fit = ([x, y]) => [ox + (x - minX) * s, oy + (y - minY) * s];
+    const pathF = path2.map(fit);
+    const groundF = ground2.map(fit);
+    const hasHeight = pts.some((q) => Math.abs(q.y) > 0.01);
+    const gridD = gridLines
+        .map(([a, b]) => {
+        const [ax, ay] = fit(a);
+        const [bx, by] = fit(b);
+        return `M ${ax.toFixed(1)} ${ay.toFixed(1)} L ${bx.toFixed(1)} ${by.toFixed(1)}`;
+    })
+        .join(' ');
+    return {
+        d: smoothPath(pathF, preset.closed),
+        groundD: hasHeight ? smoothPath(groundF, preset.closed) : undefined,
+        gridD,
+        subject: fit(projectGround({ x: 0, y: 0, z: 0 })),
+    };
+}

package/dist/presetThumbGeometry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=presetThumbGeometry.test.d.ts.map

package/dist/presetThumbGeometry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presetThumbGeometry.test.d.ts","sourceRoot":"","sources":["../src/presetThumbGeometry.test.ts"],"names":[],"mappings":""}

package/dist/presetThumbGeometry.test.js

@@ -0,0 +1,83 @@
+import { PATH_PRESETS } from './pathPresets';
+import { buildPresetThumb, smoothPath, THUMB_VH, THUMB_VW, } from './presetThumbGeometry';
+/** 抽出 path d 里的所有坐标数对 */
+function coordsOf(d) {
+    const nums = d.match(/-?\d+(\.\d+)?/g)?.map(Number) ?? [];
+    const out = [];
+    for (let i = 0; i + 1 < nums.length; i += 2)
+        out.push([nums[i], nums[i + 1]]);
+    return out;
+}
+describe('smoothPath', () => {
+    it('两点退化直线,三点成平滑曲线', () => {
+        expect(smoothPath([
+            [0, 0],
+            [10, 0],
+        ], false)).toBe('M 0 0 L 10.0 0.0');
+        const d = smoothPath([
+            [0, 0],
+            [5, 5],
+            [10, 0],
+        ], false);
+        expect(d.startsWith('M 0.0 0.0 C')).toBe(true);
+        expect(d.endsWith('10.0 0.0')).toBe(true);
+    });
+    it('闭合路径以 Z 收尾,段数等于点数;开放路径段数少一', () => {
+        const pts = [
+            [0, 0],
+            [10, 0],
+            [10, 10],
+            [0, 10],
+        ];
+        expect(smoothPath(pts, true).endsWith('Z')).toBe(true);
+        expect((smoothPath(pts, true).match(/C /g) ?? []).length).toBe(4);
+        expect((smoothPath(pts, false).match(/C /g) ?? []).length).toBe(3);
+    });
+});
+describe('buildPresetThumb', () => {
+    it('11 个预设全部产出合法几何,坐标不出 viewBox', () => {
+        expect(PATH_PRESETS).toHaveLength(11);
+        for (const preset of PATH_PRESETS) {
+            const thumb = buildPresetThumb(preset);
+            expect(thumb.d.length).toBeGreaterThan(0);
+            expect(thumb.gridD.length).toBeGreaterThan(0);
+            // 网格和路径的所有坐标都在 viewBox 内
+            for (const [x, y] of [...coordsOf(thumb.d), ...coordsOf(thumb.gridD)]) {
+                expect(x).toBeGreaterThanOrEqual(0);
+                expect(x).toBeLessThanOrEqual(THUMB_VW);
+                expect(y).toBeGreaterThanOrEqual(0);
+                expect(y).toBeLessThanOrEqual(THUMB_VH);
+            }
+            // 主体十字也在框内
+            expect(thumb.subject[0]).toBeGreaterThanOrEqual(0);
+            expect(thumb.subject[0]).toBeLessThanOrEqual(THUMB_VW);
+            expect(thumb.subject[1]).toBeGreaterThanOrEqual(0);
+            expect(thumb.subject[1]).toBeLessThanOrEqual(THUMB_VH);
+        }
+    });
+    it('带高度的预设有地面投影,平面预设没有', () => {
+        const withHeight = ['reveal', 'spiralUp', 'crane', 'dive', 'figure8v'];
+        for (const preset of PATH_PRESETS) {
+            const thumb = buildPresetThumb(preset);
+            if (withHeight.includes(preset.id)) {
+                expect(thumb.groundD).toBeDefined();
+            }
+            else {
+                expect(thumb.groundD).toBeUndefined();
+            }
+        }
+    });
+    it('闭合预设的路径以 Z 收尾,开放的不闭合', () => {
+        for (const preset of PATH_PRESETS) {
+            const thumb = buildPresetThumb(preset);
+            expect(thumb.d.endsWith('Z')).toBe(preset.closed);
+        }
+    });
+    it('升降摇臂:路径主体在主体十字上方(屏幕上 y 更小)', () => {
+        const crane = PATH_PRESETS.find((p) => p.id === 'crane');
+        const thumb = buildPresetThumb(crane);
+        const ys = coordsOf(thumb.d).map(([, y]) => y);
+        // 路径最高点明显高于主体(屏幕坐标 y 更小)
+        expect(Math.min(...ys)).toBeLessThan(thumb.subject[1] - 10);
+    });
+});

package/dist/selectionOutline.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 选中轮廓线(Blender 式):不往场景里挂任何辅助网格,屏幕空间画剪影描边。
+ *
+ * 原理(与 Blender 的选中描边同思路):
+ * 1) 蒙版 pass:场景画成纯黑(写深度),选中物画成纯白,得到"可见剪影"
+ *    蒙版——整个选中物是一张联合蒙版,所以只有外剪影有边,绝不会有内部线;
+ *    被其他物体挡住的部分不进蒙版,描边只落在看得见的部分(同 Blender);
+ *    蒙皮网格走正常渲染管线,骨骼动画/姿势播放时剪影跟着变形。
+ * 2) 合成 pass:全屏着色器在蒙版外圈 uThicknessPx 像素内画橙色边,
+ *    宽度按物理像素恒定,与距离无关。
+ *
+ * 两步都在 useFrame 回调里同步完成,不往场景树加任何节点,选中物零侵入。
+ */
+import { Scene } from 'three';
+import type { Camera, Object3D, WebGLRenderer } from 'three';
+/** 选中高亮橙:与锚点/相机视锥的选中色一致(Blender 式选中橙) */
+export declare const SELECTION_OUTLINE_COLOR = 16756768;
+/** 蒙版 pass 用的临时图层:只把选中物画进蒙版,不动对象常驻层 */
+export declare const OUTLINE_LAYER = 7;
+/**
+ * 把 node 下所有网格临时开进 OUTLINE_LAYER,fn 结束后逐个还原。
+ * 只动网格(可渲染物),分组/骨骼等纯节点保持原样。
+ */
+export declare function withOutlineLayer<T>(node: Object3D, fn: () => T): T;
+export type OutlineSize = {
+    width: number;
+    height: number;
+};
+export type SelectionOutlineRenderer = {
+    /**
+     * 在当前帧的渲染结果上叠加选中描边。调用时机:主视角场景画完之后、
+     * 画中画之前(调用方的 useFrame 优先级管这件事)。
+     */
+    render: (gl: WebGLRenderer, scene: Scene, camera: Camera, node: Object3D, size: OutlineSize, dpr: number, thicknessPx?: number) => void;
+    dispose: () => void;
+};
+/**
+ * 持有蒙版 RT 与合成着色器的描边渲染器。一个选中态一个实例,
+ * 卸载时 dispose(跟随 SelectionOutlineHighlight 的生命周期)。
+ */
+export declare function createSelectionOutlineRenderer(): SelectionOutlineRenderer;
+//# sourceMappingURL=selectionOutline.d.ts.map

package/dist/selectionOutline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectionOutline.d.ts","sourceRoot":"","sources":["../src/selectionOutline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAOL,KAAK,EAIN,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAC,MAAM,OAAO,CAAA;AAG1D,yCAAyC;AACzC,eAAO,MAAM,uBAAuB,WAAW,CAAA;AAK/C,uCAAuC;AACvC,eAAO,MAAM,aAAa,IAAI,CAAA;AAE9B;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAalE;AAED,MAAM,MAAM,WAAW,GAAG;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAA;AAEzD,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,MAAM,EAAE,CACN,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,KACjB,IAAI,CAAA;IACT,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAmDD;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,wBAAwB,CAwGzE"}

package/dist/selectionOutline.js

@@ -0,0 +1,174 @@
+/**
+ * 选中轮廓线(Blender 式):不往场景里挂任何辅助网格,屏幕空间画剪影描边。
+ *
+ * 原理(与 Blender 的选中描边同思路):
+ * 1) 蒙版 pass:场景画成纯黑(写深度),选中物画成纯白,得到"可见剪影"
+ *    蒙版——整个选中物是一张联合蒙版,所以只有外剪影有边,绝不会有内部线;
+ *    被其他物体挡住的部分不进蒙版,描边只落在看得见的部分(同 Blender);
+ *    蒙皮网格走正常渲染管线,骨骼动画/姿势播放时剪影跟着变形。
+ * 2) 合成 pass:全屏着色器在蒙版外圈 uThicknessPx 像素内画橙色边,
+ *    宽度按物理像素恒定,与距离无关。
+ *
+ * 两步都在 useFrame 回调里同步完成,不往场景树加任何节点,选中物零侵入。
+ */
+import { BufferGeometry, BufferAttribute, Color, Mesh, MeshBasicMaterial, OrthographicCamera, Scene, ShaderMaterial, Vector3, WebGLRenderTarget, } from 'three';
+import { withEditorOnlyHidden } from './editorOnly';
+/** 选中高亮橙:与锚点/相机视锥的选中色一致(Blender 式选中橙) */
+export const SELECTION_OUTLINE_COLOR = 0xffb020;
+/** 描边宽度(CSS 像素,合成时乘 dpr 换算物理像素) */
+const DEFAULT_THICKNESS_PX = 4;
+/** 蒙版 pass 用的临时图层:只把选中物画进蒙版,不动对象常驻层 */
+export const OUTLINE_LAYER = 7;
+/**
+ * 把 node 下所有网格临时开进 OUTLINE_LAYER,fn 结束后逐个还原。
+ * 只动网格(可渲染物),分组/骨骼等纯节点保持原样。
+ */
+export function withOutlineLayer(node, fn) {
+    const touched = [];
+    node.traverse((child) => {
+        if (child.isMesh) {
+            touched.push({ obj: child, mask: child.layers.mask });
+            child.layers.enable(OUTLINE_LAYER);
+        }
+    });
+    try {
+        return fn();
+    }
+    finally {
+        for (const { obj, mask } of touched)
+            obj.layers.mask = mask;
+    }
+}
+/** 全屏三角形:比 Quad 少一次顶点插值,后处理通行做法 */
+function makeFullscreenTriangle() {
+    const geo = new BufferGeometry();
+    geo.setAttribute('position', new BufferAttribute(new Float32Array([-1, -1, 0, 3, -1, 0, -1, 3, 0]), 3));
+    geo.setAttribute('uv', new BufferAttribute(new Float32Array([0, 0, 2, 0, 0, 2]), 2));
+    return geo;
+}
+const OUTLINE_FRAG = /* glsl */ `
+  varying vec2 vUv;
+  uniform sampler2D tMask;
+  uniform vec2 uResolution; // 蒙版物理像素尺寸
+  uniform float uThicknessPx; // 描边宽(物理像素)
+  uniform vec3 uColor;
+
+  void main() {
+    // 蒙版内部(物体本体)不画:描边只出现在剪影外圈
+    if (texture2D(tMask, vUv).r > 0.5) discard;
+
+    // 环采一周:半径 uThicknessPx 内有蒙版像素 → 在描边带上。
+    // 命中比例直接当 alpha:剪影处约半圈命中,向外渐隐,自带抗锯齿。
+    vec2 radius = uThicknessPx / uResolution;
+    const int TAPS = 12;
+    float acc = 0.0;
+    for (int i = 0; i < TAPS; i++) {
+      float a = float(i) * 6.2831853 / float(TAPS);
+      vec2 off = vec2(cos(a), sin(a)) * radius;
+      acc += step(0.5, texture2D(tMask, vUv + off).r);
+    }
+    float alpha = acc / float(TAPS);
+    if (alpha <= 0.0) discard;
+    gl_FragColor = vec4(uColor, alpha);
+  }
+`;
+const OUTLINE_VERT = /* glsl */ `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position.xy, 0.0, 1.0);
+  }
+`;
+/**
+ * 持有蒙版 RT 与合成着色器的描边渲染器。一个选中态一个实例,
+ * 卸载时 dispose(跟随 SelectionOutlineHighlight 的生命周期)。
+ */
+export function createSelectionOutlineRenderer() {
+    // 蒙版 RT:只要 r 通道够不够,RGBA8 最省;深度必须开(遮挡裁剪靠它)
+    const maskRT = new WebGLRenderTarget(1, 1, { depthBuffer: true });
+    // 蒙版材质:纯色、不吃雾、不吃色调映射,保证白是 1.0、黑是 0.0
+    const blackMat = new MeshBasicMaterial({ color: 0x000000 });
+    blackMat.fog = false;
+    blackMat.toneMapped = false;
+    const whiteMat = new MeshBasicMaterial({ color: 0xffffff });
+    whiteMat.fog = false;
+    whiteMat.toneMapped = false;
+    const outlineMat = new ShaderMaterial({
+        transparent: true,
+        depthTest: false,
+        depthWrite: false,
+        uniforms: {
+            tMask: { value: maskRT.texture },
+            uResolution: { value: { x: 1, y: 1 } },
+            uThicknessPx: { value: DEFAULT_THICKNESS_PX },
+            // ShaderMaterial 的输出不经过 three 的色彩空间转换,片元直写画布;
+            // 所以这里直接给画布的 sRGB 值(0xffb020),不走 Color 的线性换算
+            uColor: { value: new Vector3(1.0, 176 / 255, 32 / 255) },
+        },
+        vertexShader: OUTLINE_VERT,
+        fragmentShader: OUTLINE_FRAG,
+    });
+    const quad = new Mesh(makeFullscreenTriangle(), outlineMat);
+    quad.frustumCulled = false;
+    const quadScene = new Scene();
+    quadScene.add(quad);
+    const quadCam = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    const clearColorBackup = new Color();
+    function render(gl, scene, camera, node, size, dpr, thicknessPx = DEFAULT_THICKNESS_PX) {
+        const w = Math.max(1, Math.round(size.width * dpr));
+        const h = Math.max(1, Math.round(size.height * dpr));
+        if (maskRT.width !== w || maskRT.height !== h)
+            maskRT.setSize(w, h);
+        outlineMat.uniforms.uResolution.value.x = w;
+        outlineMat.uniforms.uResolution.value.y = h;
+        outlineMat.uniforms.uThicknessPx.value = thicknessPx * dpr;
+        // 保存现场:渲染目标/清屏色/autoClear/场景背景与覆盖材质/相机层
+        const prevRT = gl.getRenderTarget();
+        const prevAutoClear = gl.autoClear;
+        gl.getClearColor(clearColorBackup);
+        const prevClearAlpha = gl.getClearAlpha();
+        const prevBackground = scene.background;
+        const prevOverride = scene.overrideMaterial;
+        const prevCamLayers = camera.layers.mask;
+        try {
+            gl.setRenderTarget(maskRT);
+            gl.setClearColor(0x000000, 1);
+            gl.clear(true, true, false);
+            gl.autoClear = false;
+            scene.background = null;
+            // pass 1:全场景画黑并把深度写进蒙版 RT——被挡住的选中物部分
+            // 在 pass 2 里会被深度裁掉,描边只描看得见的剪影(同 Blender)。
+            // 编辑辅助对象(网格地面/手柄/视锥线)藏起来,不当遮挡物。
+            scene.overrideMaterial = blackMat;
+            withEditorOnlyHidden(() => gl.render(scene, camera));
+            // pass 2:同一 RT 上只画选中物(白),深度沿用 pass 1 的场景深度
+            scene.overrideMaterial = whiteMat;
+            camera.layers.set(OUTLINE_LAYER);
+            try {
+                withOutlineLayer(node, () => gl.render(scene, camera));
+            }
+            finally {
+                camera.layers.mask = prevCamLayers;
+            }
+            // 合成:蒙版外圈画橙色边,直写当前帧缓冲(叠在主视角画面上)
+            gl.setRenderTarget(prevRT);
+            gl.render(quadScene, quadCam);
+        }
+        finally {
+            scene.background = prevBackground;
+            scene.overrideMaterial = prevOverride;
+            camera.layers.mask = prevCamLayers;
+            gl.setRenderTarget(prevRT);
+            gl.setClearColor(clearColorBackup, prevClearAlpha);
+            gl.autoClear = prevAutoClear;
+        }
+    }
+    function dispose() {
+        maskRT.dispose();
+        blackMat.dispose();
+        whiteMat.dispose();
+        outlineMat.dispose();
+        quad.geometry.dispose();
+    }
+    return { render, dispose };
+}

package/dist/selectionOutline.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=selectionOutline.test.d.ts.map

package/dist/selectionOutline.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectionOutline.test.d.ts","sourceRoot":"","sources":["../src/selectionOutline.test.ts"],"names":[],"mappings":""}

package/dist/selectionOutline.test.js

@@ -0,0 +1,58 @@
+/**
+ * 选中轮廓线(Blender 式)的可测逻辑:withOutlineLayer 在蒙版 pass 期间
+ * 把目标子树的网格临时开进描边层,结束后逐个还原。
+ * 渲染本体(RT/着色器)依赖 WebGL,在浏览器实测里验证。
+ */
+import { BoxGeometry, Group, Mesh, MeshBasicMaterial } from 'three';
+import { OUTLINE_LAYER, SELECTION_OUTLINE_COLOR, withOutlineLayer, } from './selectionOutline';
+function meshUnder(root, name) {
+    const m = new Mesh(new BoxGeometry(), new MeshBasicMaterial());
+    m.name = name;
+    root.add(m);
+    return m;
+}
+test('蒙版 pass 期间子树网格全部开描边层,非网格不动', () => {
+    const root = new Group();
+    const a = meshUnder(root, 'a');
+    const inner = new Group();
+    root.add(inner);
+    const b = meshUnder(inner, 'b');
+    const innerMask = inner.layers.mask;
+    withOutlineLayer(root, () => {
+        expect(a.layers.test(maskOf(OUTLINE_LAYER))).toBe(true);
+        expect(b.layers.test(maskOf(OUTLINE_LAYER))).toBe(true);
+        // 纯分组不是可渲染网格,不该被动
+        expect(inner.layers.mask).toBe(innerMask);
+    });
+});
+test('结束后还原每个对象的原始 layers(原本就在描边层的保持开)', () => {
+    const root = new Group();
+    const a = meshUnder(root, 'a');
+    const b = meshUnder(root, 'b');
+    b.layers.enable(OUTLINE_LAYER); // 本来就开着
+    const maskA = a.layers.mask;
+    const maskB = b.layers.mask;
+    withOutlineLayer(root, () => { });
+    expect(a.layers.mask).toBe(maskA);
+    expect(b.layers.mask).toBe(maskB);
+});
+test('fn 抛错也照样还原(finally 语义)', () => {
+    const root = new Group();
+    const a = meshUnder(root, 'a');
+    const maskA = a.layers.mask;
+    expect(() => withOutlineLayer(root, () => {
+        throw new Error('boom');
+    })).toThrow('boom');
+    expect(a.layers.mask).toBe(maskA);
+});
+test('返回值透传', () => {
+    const root = new Group();
+    expect(withOutlineLayer(root, () => 42)).toBe(42);
+});
+test('选中橙保持 Blender 橙', () => {
+    expect(SELECTION_OUTLINE_COLOR).toBe(0xffb020);
+});
+function maskOf(layer) {
+    // three 的 Layers.test 需要一个 Layers 实例;这里用 bit 对象的掩码形式
+    return { mask: 1 << layer };
+}

package/dist/smoke.test.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=smoke.test.d.ts.map

package/dist/smoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke.test.d.ts","sourceRoot":"","sources":["../src/smoke.test.ts"],"names":[],"mappings":""}

package/dist/smoke.test.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * 包骨架冒烟:index 公开面可导入。
+ *
+ * bootstrap 现带 studio 根模块副作用导入(T10 fix round 1:根模块加载即
+ * new Studio() 向 core 自注册)——真身进 jsdom 会装全局监听/定时器,
+ * jest worker 退不干净。按 R8 裁定与 bootstrap.test.tsx 同款手法替身
+ * (jest-esbuild 不提升 jest.mock:doMock + 运行时 import)。
+ */
+jest.doMock('@dreamerbird/studio', () => ({
+    __esModule: true,
+}));
+test('包骨架可导入,版本号与 package.json 同步', async () => {
+    const { version } = require('../package.json');
+    const { CAMERA_STUDIO_VERSION } = await import('./index');
+    expect(CAMERA_STUDIO_VERSION).toBe(version);
+});

package/dist/uiConfig.d.ts

@@ -0,0 +1,16 @@
+/**
+ * UI 装配可配层(spec §3 ui 字段 / §7 约束):停靠框 portal 容器 /
+ * z-index 基准 / 语言。模块级单值,bootstrap 在 boot 时一次写入
+ * (config.ui ?? 空对象);boot 级保留语义与 R14 一致——dispose 不复位,
+ * 重挂幂等复用。缺省 = 现状:portal → document.body、zIndexBase 1000。
+ */
+/** UI 装配(spec §3 ui 字段):停靠框 portal 容器 / z-index 基准 / 语言 */
+type UiConfig = {
+    portalContainer?: HTMLElement;
+    zIndexBase?: number;
+    locale?: string;
+};
+export declare function setUiConfig(cfg: UiConfig): void;
+export declare function getUiConfig(): Required<Pick<UiConfig, 'zIndexBase'>> & UiConfig;
+export {};
+//# sourceMappingURL=uiConfig.d.ts.map

package/dist/uiConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiConfig.d.ts","sourceRoot":"","sources":["../src/uiConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2DAA2D;AAC3D,KAAK,QAAQ,GAAG;IACd,eAAe,CAAC,EAAE,WAAW,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAE/C;AACD,wBAAgB,WAAW,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,GACnE,QAAQ,CAET"}

package/dist/uiConfig.js

@@ -0,0 +1,13 @@
+/**
+ * UI 装配可配层(spec §3 ui 字段 / §7 约束):停靠框 portal 容器 /
+ * z-index 基准 / 语言。模块级单值,bootstrap 在 boot 时一次写入
+ * (config.ui ?? 空对象);boot 级保留语义与 R14 一致——dispose 不复位,
+ * 重挂幂等复用。缺省 = 现状:portal → document.body、zIndexBase 1000。
+ */
+let current = {};
+export function setUiConfig(cfg) {
+    current = cfg;
+}
+export function getUiConfig() {
+    return { zIndexBase: 1000, ...current };
+}

package/dist/uiConfig.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=uiConfig.test.d.ts.map

package/dist/uiConfig.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiConfig.test.d.ts","sourceRoot":"","sources":["../src/uiConfig.test.tsx"],"names":[],"mappings":""}

package/dist/uiConfig.test.js

@@ -0,0 +1,98 @@
+/*
+ * @jest-environment jsdom
+ */
+/**
+ * UI 装配可配(T9,spec §3 ui 字段 / §7 约束):
+ *  - getUiConfig 缺省/合并语义(单测);
+ *  - portalContainer 可配:真实 PosePropEditor 点开姿势选择框,
+ *    断言框渲染进宿主给的容器且 z-index 以配置为基准;
+ *  - 缺省复位:portal 回 document.body、z-index 基准回 1000。
+ *
+ * PosePropEditor 走真实链路(库单例 + fake-indexeddb + 内置目录),
+ * 不整树渲染场景。React 19 act 环境开关手写(testing-library 缺席,R13
+ * 先例);真实模块链下 react/react-dom 静态 import 安全(无
+ * resetModules)。
+ */
+import { IDBFactory } from 'fake-indexeddb';
+import React from 'react';
+import { act } from 'react-dom/test-utils';
+import ReactDOM from 'react-dom/client';
+import { getUiConfig, setUiConfig } from './uiConfig';
+import PosePropEditor from './poseMode/PosePropEditor';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+globalThis.indexedDB = new IDBFactory();
+URL.createObjectURL = jest.fn(() => 'blob:mock-url');
+URL.revokeObjectURL = jest.fn();
+afterEach(() => {
+    setUiConfig({}); // 模块级单值,用例间必须复位
+});
+describe('getUiConfig 缺省与合并', () => {
+    it('缺省 = 现状:portal 无指定容器、zIndexBase 1000', () => {
+        expect(getUiConfig()).toEqual({ zIndexBase: 1000 });
+    });
+    it('setUiConfig 整体替换:portalContainer/zIndexBase/locale 合并进读侧', () => {
+        const host = document.createElement('div');
+        setUiConfig({ portalContainer: host, zIndexBase: 5000, locale: 'zh-CN' });
+        expect(getUiConfig()).toEqual({
+            portalContainer: host,
+            zIndexBase: 5000,
+            locale: 'zh-CN',
+        });
+    });
+});
+/** 渲染真实 PosePropEditor 并点值区域,返回宿主容器与卸载器 */
+async function renderPicker(ui, mount) {
+    setUiConfig(ui);
+    const root = ReactDOM.createRoot(mount);
+    // 替身只喂断言用到的字段;propConfig 等其余必填项经 unknown 转成
+    // 组件 props 型让行(never 不能展开)
+    const editorProps = {
+        editingTools: { permanentlySetValue: jest.fn() },
+        value: '',
+        obj: undefined,
+    };
+    await act(async () => {
+        root.render(React.createElement(PosePropEditor, { ...editorProps }));
+    });
+    // 库条目异步装载(listEntries)再渲染;补两拍冲刷微任务
+    await act(async () => { });
+    await act(async () => { });
+    const value = mount.querySelector('[data-testid="PosePropValue"]');
+    expect(value).not.toBeNull();
+    await act(async () => {
+        value.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    return {
+        host: ui.portalContainer,
+        unmount: async () => {
+            await act(async () => {
+                root.unmount();
+            });
+            mount.remove();
+        },
+    };
+}
+describe('portalContainer 可配(真实姿势属性编辑器)', () => {
+    it('portalContainer 可配:选择框渲染进宿主给的容器,z-index 以 5000 为基准', async () => {
+        const mount = document.createElement('div');
+        document.body.appendChild(mount);
+        const host = document.createElement('div');
+        document.body.appendChild(host);
+        const { unmount } = await renderPicker({ portalContainer: host, zIndexBase: 5000 }, mount);
+        const frame = host.querySelector('[data-testid="PosePickerFrame"]');
+        expect(frame).not.toBeNull(); // 渲染进了宿主容器,而非 document.body 直挂
+        expect(document.body.querySelectorAll('[data-testid="PosePickerFrame"]')).toHaveLength(1);
+        expect(frame.style.zIndex).toBe('5000');
+        await unmount();
+        host.remove();
+    });
+    it('缺省:portal 落 document.body,z-index 基准 1000', async () => {
+        const mount = document.createElement('div');
+        document.body.appendChild(mount);
+        const { unmount } = await renderPicker({}, mount);
+        const frame = document.body.querySelector('[data-testid="PosePickerFrame"]');
+        expect(frame).not.toBeNull();
+        expect(frame.style.zIndex).toBe('1000');
+        await unmount();
+    });
+});