@sliiu/present-three-bake 0.0.0-stage → 0.1.0

package/dist/esm/resolve.js

@@ -0,0 +1,91 @@
+import { CAMERA_PRESETS, DEFAULT_BEVEL_PX, DEFAULT_FOV, DEFAULT_LIGHT_RIG, DEFAULT_MATERIAL, FOV_LOCKED_PRESETS, } from "./presets.js";
+export function resolveCamera(cam) {
+    let lat = 0;
+    let lon = 0;
+    let rev = 0;
+    let fov = DEFAULT_FOV;
+    if (cam?.prst) {
+        const p = CAMERA_PRESETS[cam.prst];
+        if (p) {
+            lat = p.lat;
+            lon = p.lon;
+            rev = p.rev;
+            fov = p.fov;
+        }
+    }
+    // 显式 <a:rot> 覆盖角度（preset 与 rot 是覆盖而非叠加）。
+    if (cam?.rot) {
+        lat = cam.rot.lat;
+        lon = cam.rot.lon;
+        rev = cam.rot.rev;
+    }
+    // 显式 @fov 覆盖 fov——但 relaxed 系 preset 无条件用预设窄 fov（PPT 把显式 fov 当 zoom 参考）。
+    if (cam?.fov !== undefined && !(cam.prst && FOV_LOCKED_PRESETS.has(cam.prst))) {
+        fov = cam.fov;
+    }
+    return { lat, lon, rev, fov, isOrtho: fov < 1, zoom: cam?.zoom };
+}
+function resolveBevel(b) {
+    if (!b)
+        return undefined;
+    return {
+        w: b.w ?? DEFAULT_BEVEL_PX,
+        h: b.h ?? DEFAULT_BEVEL_PX,
+    };
+}
+export function resolveSp3D(sp3d) {
+    const bevelT = resolveBevel(sp3d?.bevelT);
+    const bevelB = resolveBevel(sp3d?.bevelB);
+    return {
+        extrusionH: sp3d?.extrusionH ?? 0,
+        contourW: sp3d?.contourW,
+        contourClr: sp3d?.contourClr,
+        extrusionClr: sp3d?.extrusionClr,
+        prstMaterial: sp3d?.prstMaterial ?? DEFAULT_MATERIAL,
+        bevelT,
+        bevelB,
+        hasBevel: !!(bevelT || bevelB),
+    };
+}
+export function resolveLightRig(lr) {
+    return { rig: lr?.rig ?? DEFAULT_LIGHT_RIG, dir: lr?.dir };
+}
+function asVec(v) {
+    return "dx" in v ? { x: v.dx, y: v.dy, z: v.dz } : v;
+}
+function normalizeVec(v) {
+    const len = Math.hypot(v.x, v.y, v.z);
+    if (len < 1e-8)
+        return undefined;
+    return { x: v.x / len, y: v.y / len, z: v.z / len };
+}
+function nearAxis(v, x, y, z, eps = 0.02) {
+    return Math.abs(v.x - x) < eps && Math.abs(v.y - y) < eps && Math.abs(v.z - z) < eps;
+}
+/** identity / 全 0 → undefined，setupCamera 保持 preset 朝向。 */
+export function resolveBackdrop(bd) {
+    if (!bd)
+        return undefined;
+    const n = bd.norm ? normalizeVec(asVec(bd.norm)) : undefined;
+    const u = bd.up ? normalizeVec(asVec(bd.up)) : undefined;
+    const identityN = !n || nearAxis(n, 0, 0, 1);
+    const identityU = !u || nearAxis(u, 0, 1, 0);
+    const a = bd.anchor;
+    const hasAnchor = !!(a && (Math.abs(a.x) > 1e-4 || Math.abs(a.y) > 1e-4 || Math.abs(a.z) > 1e-4));
+    if (identityN && identityU && !hasAnchor)
+        return undefined;
+    return {
+        target: a ?? { x: 0, y: 0, z: 0 },
+        forward: identityN ? undefined : n,
+        up: identityU ? undefined : u,
+    };
+}
+export function resolveScene3D(info) {
+    const scene = info.scene3d;
+    return {
+        camera: resolveCamera(scene?.camera),
+        sp3d: resolveSp3D(info.sp3d),
+        lightRig: resolveLightRig(scene?.lightRig),
+        backdrop: resolveBackdrop(scene?.backdrop),
+    };
+}

package/dist/esm/runtime.js

@@ -0,0 +1,141 @@
+// 高层 runtime helper：把 bakeSp3d 接到任意持有 Scene 的离屏光栅消费者
+// （thumbnail=SvgBackend / snapshot+pdf=CanvasBackend）上。bake 完成后通过 `applyBaked`
+// 回调把结果交给 caller 写入**副通道**（meta3D.bakedSrc 等），由那些后端读取显示。
+// player/editor 的实时视图不走这里，改用 packages/renderer 的 WebGLShapeBackend。
+//
+// 触发条件见 needs3DRender：相机 rot 非平凡 / extrusionH>0 / 声明了 bevel。
+// 性能：bake 是 OffscreenCanvas + WebGLRenderer 的一次性渲染，per-shape 30-100 ms。
+import { bakeSp3d } from "./bake-sp3d.js";
+import { shape3DInfo, shape3DPathD, shapeSupports3D } from "./shape-path.js";
+/**
+ * 该 3D 信息是否需要 3D 渲染（实时 or 烘焙）。parser 现在对 `<a:bevelT/>` 留空 w/h，
+ * 所以用「是否声明了 bevel 元素」判断，而非 h>0。
+ */
+export function needs3DRender(meta) {
+    if (!meta)
+        return false;
+    const rot = meta.scene3d?.camera?.rot;
+    const hasRot = !!rot && Math.abs(rot.lat) + Math.abs(rot.lon) + Math.abs(rot.rev) > 0.01;
+    const ext = meta.sp3d?.extrusionH ?? 0;
+    const hasBevel = !!(meta.sp3d?.bevelT || meta.sp3d?.bevelB);
+    return hasRot || ext > 0 || hasBevel;
+}
+function readMeta(s) {
+    return shape3DInfo(s);
+}
+// 烘焙输出的几何/参数签名：bakeSp3d 的全部输入（bbox / fill / stroke / sp3d / scene3d /
+// src / cropRect）。任一变化 → 签名变化 → 需要重烘。id 是身份不入签名。
+function bakeKeyOf(s) {
+    const meta = readMeta(s);
+    return JSON.stringify({
+        k: s.kind,
+        b: s.bbox ?? null,
+        f: s.fill ?? null,
+        st: s.stroke ?? null,
+        sp: meta?.sp3d ?? null,
+        sc: meta?.scene3d ?? null,
+        src: s.kind === "image" ? s.src ?? null : null,
+        cr: s.kind === "image" ? s.cropRect ?? null : null,
+        d: s.kind === "path" ? s.d : s.kind === "polygon" ? s.points : null,
+        tx: s.kind === "text" ? s.paragraphs : null,
+    });
+}
+// 该 shape 当前是否需要（重新）烘焙：image / 自选形状 / 带 body3D 的文字，
+// 需要 3D 渲染，且"当前几何签名"与上次烘焙记录的 bakedKey 不一致
+// （首次烘焙时 bakedKey 为 undefined，必然不一致）。
+export function needs3DBake(s) {
+    if (!shapeSupports3D(s))
+        return false;
+    const meta = readMeta(s);
+    if (!meta || !needs3DRender(meta))
+        return false;
+    return meta.bakedKey !== bakeKeyOf(s);
+}
+function shouldBake(s) {
+    return needs3DBake(s);
+}
+function walkShapes(slide, fn) {
+    for (const layer of slide.layers) {
+        const stack = [[layer.shapes, 0]];
+        while (stack.length) {
+            const top = stack[stack.length - 1];
+            const [arr, i] = top;
+            if (i >= arr.length) {
+                stack.pop();
+                continue;
+            }
+            const s = arr[i];
+            top[1] = i + 1;
+            fn(s);
+            if (s.kind === "group")
+                stack.push([s.children, 0]);
+        }
+    }
+}
+export function createBake3DRuntime() {
+    // markBaked 强制跳过集合（外部显式声明"别再烘这个 id"）。
+    const forceSkip = new Set();
+    const inFlight = new Map();
+    const bakeOne = async (s, applyBaked, frontImageSrc) => {
+        const meta = readMeta(s);
+        if (!meta)
+            return;
+        // 在烘焙前快照签名：bake 是异步的，期间用户可能又动了 shape；用快照写回 bakedKey
+        // 保证"已烘的就是这个签名"，若烘焙期间又变了，下一轮 kick 的签名不一致会再烘。
+        const key = bakeKeyOf(s);
+        const front = s.kind === "text" ? frontImageSrc?.(s) : undefined;
+        const isPicture = s.kind === "image" || !!front;
+        try {
+            const result = await bakeSp3d({
+                id: s.id,
+                bbox: s.bbox,
+                pathD: isPicture ? undefined : shape3DPathD(s),
+                fill: s.fill,
+                stroke: s.stroke,
+                sp3d: meta.sp3d ?? {},
+                scene3d: meta.scene3d,
+                imageSrc: s.kind === "image" ? s.src : front,
+                cropRect: s.kind === "image" ? s.cropRect : undefined,
+            });
+            // baked/bakedKey 仅作 dedupe；不改 shape.src/bbox/cropRect，让 live 视图保持原始几何。
+            meta.baked = true;
+            if (result)
+                applyBaked(s, result);
+        }
+        catch {
+            // 烘焙失败不致命，仍能看到 2D 图。
+        }
+        finally {
+            // 成功或失败都记录签名（避免失败时无限重试）；下次几何变化签名变了再烘。
+            meta.bakedKey = key;
+        }
+    };
+    return {
+        kick(slide, applyBaked, opts) {
+            const front = opts?.frontImageSrc;
+            walkShapes(slide, (s) => {
+                if (forceSkip.has(s.id) || inFlight.has(s.id))
+                    return;
+                if (!shouldBake(s))
+                    return;
+                const p = bakeOne(s, applyBaked, front).then(() => {
+                    inFlight.delete(s.id);
+                });
+                inFlight.set(s.id, p);
+            });
+        },
+        async waitForAll() {
+            while (inFlight.size > 0) {
+                await Promise.all(Array.from(inFlight.values()));
+            }
+            if (typeof requestAnimationFrame !== "undefined") {
+                await new Promise((r) => {
+                    requestAnimationFrame(() => requestAnimationFrame(() => r()));
+                });
+            }
+        },
+        markBaked(id) {
+            forceSkip.add(id);
+        },
+    };
+}

package/dist/esm/scene-builder.js

@@ -0,0 +1,290 @@
+import * as THREE from "three";
+import { setupCamera } from "./camera.js";
+import { applyLightRig } from "./light-rig.js";
+import { buildMaterial, pickPrimaryColor } from "./material.js";
+import { pathDToShapes } from "./path-to-shape.js";
+// ────────────────────────────────────────────────────────────────────────────
+// 共享 three.js 场景构建器。offscreen 光栅（bakeSp3d，给 thumbnail/snapshot/pdf）和
+// live WebGL backend（player/editor 实时）都用它，保证两条路径几何/材质/光照一致。
+// 这里只负责「已解析参数(ResolvedScene3D) → THREE.Scene + 相机」，不碰 DOM / canvas。
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * "前缘有倒角、背面平整、薄侧壁" 的板形几何——复刻 PowerPoint sp3d 在仅声明
+ * `<a:bevelT/>` / `<a:bevelB/>` 没有 extrusionH 时的视觉（如 7.pptx 棋盘）。
+ * 返回 front（贴图面，z=+e/2 内缩 bevelW/H）+ rim（chamfer ring + 薄侧壁），让前面用
+ * textured material 保色、rim 用 PBR 吃光照显倒角折边。详细几何见原始注释保留。
+ */
+function buildFrontBeveledSlab(baseW, baseH, extrusionPx, bevelWpx, bevelHpx) {
+    const e = extrusionPx;
+    const bw = Math.min(bevelWpx, baseW * 0.4);
+    const bh = Math.min(bevelHpx, e * 0.5);
+    const zFront = +e / 2;
+    const zRim = +e / 2 - bh;
+    const zBack = -e / 2;
+    const buildBuf = (pushAll) => {
+        const positions = [];
+        const uvs = [];
+        const normals = [];
+        const pushTri = (p1, p2, p3, uv1, uv2, uv3, n) => {
+            positions.push(...p1, ...p2, ...p3);
+            uvs.push(...uv1, ...uv2, ...uv3);
+            normals.push(...n, ...n, ...n);
+        };
+        const pushQuad = (a, b, c, d, uva, uvb, uvc, uvd, n) => {
+            pushTri(a, b, c, uva, uvb, uvc, n);
+            pushTri(a, c, d, uva, uvc, uvd, n);
+        };
+        pushAll({ pushTri, pushQuad });
+        const geo = new THREE.BufferGeometry();
+        geo.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+        geo.setAttribute("uv", new THREE.Float32BufferAttribute(uvs, 2));
+        geo.setAttribute("normal", new THREE.Float32BufferAttribute(normals, 3));
+        return geo;
+    };
+    const front = buildBuf(({ pushQuad }) => {
+        const u0 = bw / baseW, u1 = 1 - bw / baseW;
+        const v0 = bh / baseH, v1 = 1 - bh / baseH;
+        pushQuad([bw, bh, zFront], [baseW - bw, bh, zFront], [baseW - bw, baseH - bh, zFront], [bw, baseH - bh, zFront], [u0, v0], [u1, v0], [u1, v1], [u0, v1], [0, 0, 1]);
+    });
+    // 倒角 / 侧壁的 UV 直接取顶点 (x,y) 归一化，让正面贴图**连续地**裹过倒角折边到外缘
+    // （复刻 PowerPoint：image 的 bevel 是「图片本身绕圆边卷过去」，不是一圈灰色画框）。
+    // 之前 rim 全用 (0,0) + 灰色材质 → 正面与灰边之间出现「折痕」、顶部朝相机的倒角是
+    // 一条灰色折面（见 7.pptx slide2 棋盘）。连续 UV + 同一张贴图后，正面与倒角无色差，
+    // 折痕消失，倒角只贡献轮廓上的微弱立体感。
+    const uv = (x, y) => [
+        Math.min(1, Math.max(0, x / baseW)),
+        Math.min(1, Math.max(0, y / baseH)),
+    ];
+    const rim = buildBuf(({ pushQuad }) => {
+        pushQuad([0, 0, zRim], [baseW, 0, zRim], [baseW - bw, bh, zFront], [bw, bh, zFront], uv(0, 0), uv(baseW, 0), uv(baseW - bw, bh), uv(bw, bh), [0, -0.71, 0.71]);
+        pushQuad([bw, baseH - bh, zFront], [baseW - bw, baseH - bh, zFront], [baseW, baseH, zRim], [0, baseH, zRim], uv(bw, baseH - bh), uv(baseW - bw, baseH - bh), uv(baseW, baseH), uv(0, baseH), [0, 0.71, 0.71]);
+        pushQuad([0, 0, zRim], [bw, bh, zFront], [bw, baseH - bh, zFront], [0, baseH, zRim], uv(0, 0), uv(bw, bh), uv(bw, baseH - bh), uv(0, baseH), [-0.71, 0, 0.71]);
+        pushQuad([baseW - bw, bh, zFront], [baseW, 0, zRim], [baseW, baseH, zRim], [baseW - bw, baseH - bh, zFront], uv(baseW - bw, bh), uv(baseW, 0), uv(baseW, baseH), uv(baseW - bw, baseH - bh), [0.71, 0, 0.71]);
+        pushQuad([0, 0, zRim], [0, 0, zBack], [baseW, 0, zBack], [baseW, 0, zRim], uv(0, 0), uv(0, 0), uv(baseW, 0), uv(baseW, 0), [0, -1, 0]);
+        pushQuad([baseW, 0, zRim], [baseW, 0, zBack], [baseW, baseH, zBack], [baseW, baseH, zRim], uv(baseW, 0), uv(baseW, 0), uv(baseW, baseH), uv(baseW, baseH), [1, 0, 0]);
+        pushQuad([baseW, baseH, zRim], [baseW, baseH, zBack], [0, baseH, zBack], [0, baseH, zRim], uv(baseW, baseH), uv(baseW, baseH), uv(0, baseH), uv(0, baseH), [0, 1, 0]);
+        pushQuad([0, baseH, zRim], [0, baseH, zBack], [0, 0, zBack], [0, 0, zRim], uv(0, baseH), uv(0, baseH), uv(0, 0), uv(0, 0), [-1, 0, 0]);
+    });
+    return { front, rim };
+}
+// THREE.ExtrudeGeometry 默认 UVGenerator 会把侧面拉伸成镜像图。给定 baseW/baseH：
+//   - 正/背面：vertex.x/y 归一到 [0,1] 让 image 贴满
+//   - 侧面 / 倒角：固定 (0,0)，等于纹理左上角实色，让 fillColor / rim 主导
+// V 轴：texture.flipY=true → uv.v=1 对应原图最顶行；geom 顶点 y=baseH（顶部）→ uv.v=1。
+function rectFrontUVGenerator(baseW, baseH) {
+    const u = (x) => Math.min(1, Math.max(0, x / baseW));
+    const v = (y) => Math.min(1, Math.max(0, y / baseH));
+    return {
+        generateTopUV: (_geo, vs, ia, ib, ic) => {
+            const xy = (i) => new THREE.Vector2(u(vs[i * 3]), v(vs[i * 3 + 1]));
+            return [xy(ia), xy(ib), xy(ic)];
+        },
+        generateSideWallUV: () => {
+            const z = new THREE.Vector2(0, 0);
+            return [z, z, z, z];
+        },
+    };
+}
+export function buildThreeScene(inputs) {
+    const { baseW, baseH, pathD, fill, stroke, resolved, texture, isImage } = inputs;
+    const scene = new THREE.Scene();
+    const r = resolved.sp3d;
+    const fillColor = pickPrimaryColor(fill, "#7f7f7f");
+    const explicitExtH = r.extrusionH;
+    const bevelWpx = Math.min(r.bevelT?.w ?? r.bevelB?.w ?? 0, baseW * 0.4);
+    const bevelHpx = Math.min(r.bevelT?.h ?? r.bevelB?.h ?? 0, baseH * 0.4);
+    const hasBevel = r.hasBevel && bevelWpx > 0 && bevelHpx > 0;
+    const useFrontBevelSlab = isImage && hasBevel && !pathD;
+    const useBevel = hasBevel && !isImage;
+    const extrusionPx = explicitExtH > 0
+        ? explicitExtH
+        // image：用 2×bevelHpx 当深度，让 buildFrontBeveledSlab 里 bh=min(bevelHpx, e/2)
+        // 取满 bevelHpx → 顶/底倒角折面有足够宽度被看见（否则顶光下与正面分不开）。
+        : isImage
+            ? Math.max(bevelHpx * 2, 8)
+            : useBevel
+                ? Math.max(bevelHpx * 1.5, 6)
+                : 1;
+    const pp = pathD ? pathDToShapes(pathD) : null;
+    let geometry = null;
+    let frontGeo = null;
+    let rimGeo = null;
+    let geoCenterX = 0;
+    let geoCenterY = 0;
+    let geoW = baseW;
+    let geoH = baseH;
+    const extrudeOpts = {
+        depth: Math.max(extrusionPx, 0.001),
+        bevelEnabled: useBevel,
+        bevelSegments: 4,
+        bevelSize: bevelWpx,
+        bevelThickness: bevelHpx,
+        curveSegments: 24,
+        UVGenerator: rectFrontUVGenerator(baseW, baseH),
+    };
+    if (pp && pp.shapes.length > 0) {
+        const bbox = pp.bbox;
+        geoW = bbox.maxX - bbox.minX || baseW;
+        geoH = bbox.maxY - bbox.minY || baseH;
+        geoCenterX = (bbox.minX + bbox.maxX) / 2;
+        geoCenterY = (bbox.minY + bbox.maxY) / 2;
+        geometry = new THREE.ExtrudeGeometry(pp.shapes, extrudeOpts);
+    }
+    else if (useFrontBevelSlab) {
+        geoCenterX = baseW / 2;
+        geoCenterY = baseH / 2;
+        const built = buildFrontBeveledSlab(baseW, baseH, extrusionPx, bevelWpx, bevelHpx);
+        frontGeo = built.front;
+        rimGeo = built.rim;
+    }
+    else {
+        geoCenterX = baseW / 2;
+        geoCenterY = baseH / 2;
+        const shape = new THREE.Shape();
+        shape.moveTo(0, 0);
+        shape.lineTo(baseW, 0);
+        shape.lineTo(baseW, baseH);
+        shape.lineTo(0, baseH);
+        shape.lineTo(0, 0);
+        geometry = new THREE.ExtrudeGeometry([shape], extrudeOpts);
+    }
+    const rimColor = r.contourClr ?? fillColor;
+    if (frontGeo && rimGeo) {
+        frontGeo.translate(-geoCenterX, -geoCenterY, -extrusionPx / 2);
+        rimGeo.translate(-geoCenterX, -geoCenterY, -extrusionPx / 2);
+        frontGeo.computeBoundingSphere();
+        frontGeo.computeBoundingBox();
+        rimGeo.computeBoundingSphere();
+        rimGeo.computeBoundingBox();
+        const frontMat = buildMaterial(fill, {
+            prst: r.prstMaterial,
+            fallbackColor: fillColor,
+            imageTexture: texture ?? undefined,
+        });
+        // image 倒角 / 侧壁与正面共用贴图（连续 UV），让图片裹过折边而不是露出灰色画框；
+        // 但 rim 走 litTexture + tint 压暗：正面 basic 满亮、折边受光后再乘灰度 → 顶光下
+        // 「上面（倒角折面）」也明显比「前面（正面）」暗，留出区分两个面的折痕。
+        // 无贴图（纯色 shape 不会走 slab 路径，但兜底）时仍回退到 contour / fill 灰边。
+        const rimMat = texture
+            ? buildMaterial(fill, {
+                prst: r.prstMaterial,
+                fallbackColor: rimColor,
+                imageTexture: texture,
+                litTexture: true,
+                tint: 0x888888,
+            })
+            : buildMaterial(undefined, { prst: r.prstMaterial, fallbackColor: rimColor });
+        scene.add(new THREE.Mesh(frontGeo, frontMat));
+        scene.add(new THREE.Mesh(rimGeo, rimMat));
+    }
+    else if (geometry) {
+        geometry.translate(-geoCenterX, -geoCenterY, -extrusionPx / 2);
+        geometry.computeBoundingSphere();
+        geometry.computeBoundingBox();
+        const material = buildMaterial(fill, {
+            prst: r.prstMaterial,
+            fallbackColor: fillColor,
+            imageTexture: texture ?? undefined,
+        });
+        scene.add(new THREE.Mesh(geometry, material));
+    }
+    if (stroke && r.contourW && r.contourW > 0) {
+        const geomForEdges = frontGeo ?? geometry;
+        if (geomForEdges) {
+            const edges = new THREE.EdgesGeometry(geomForEdges, 12);
+            const lineMat = new THREE.LineBasicMaterial({ color: r.contourClr ?? "#000000", linewidth: 1 });
+            scene.add(new THREE.LineSegments(edges, lineMat));
+        }
+    }
+    applyLightRig(scene, resolved.lightRig.rig, resolved.lightRig.dir);
+    const dispose = () => {
+        scene.traverse((obj) => {
+            if (obj instanceof THREE.Mesh || obj instanceof THREE.LineSegments) {
+                obj.geometry?.dispose();
+                const mat = obj.material;
+                if (Array.isArray(mat))
+                    for (const m of mat)
+                        m.dispose();
+                else
+                    mat?.dispose();
+            }
+        });
+    };
+    return { scene, geoW, geoH, dispose };
+}
+/**
+ * 把相机摆到「物体在 viewW×viewH 视口里接近 1:1（含 pad 余量）」的距离并构建 THREE 相机。
+ * offscreen 与 live 共用：offscreen 传 padded canvas 尺寸；live 传显示像素尺寸。
+ */
+export function createSceneCamera(cam, geoW, geoH, viewW, viewH, pad, backdrop) {
+    const aspect = viewW / viewH;
+    const camFit = 1 + pad;
+    let distance;
+    if (cam.isOrtho) {
+        distance = Math.max(Math.max(geoW, geoH) * 4, 200);
+    }
+    else {
+        const fovRad = (cam.fov * Math.PI) / 180;
+        const tanHalf = Math.tan(fovRad / 2);
+        const dByH = (geoH * camFit) / (2 * tanHalf);
+        const dByW = (geoW * camFit) / (2 * tanHalf * aspect);
+        distance = Math.max(dByH, dByW, 200);
+    }
+    const { camera } = setupCamera(cam, new THREE.Vector3(0, 0, 0), distance, backdrop);
+    if (camera instanceof THREE.PerspectiveCamera) {
+        camera.aspect = aspect;
+        camera.updateProjectionMatrix();
+    }
+    else if (camera instanceof THREE.OrthographicCamera) {
+        const halfX = (viewW / 2) * camFit;
+        const halfY = (viewH / 2) * camFit;
+        camera.left = -halfX;
+        camera.right = halfX;
+        camera.top = halfY;
+        camera.bottom = -halfY;
+        camera.updateProjectionMatrix();
+    }
+    return camera;
+}
+// 已解码的 <img> 缓存（按 src）。解码是 loadImageTexture 里唯一的异步成本；缓存后
+// live WebGLShapeBackend 在每帧重建（编辑器拖动）时可以 **同步** 拿到贴图、当帧首渲，
+// 避免"重建 backend → 异步等贴图 → 3D 空一帧"造成的闪屏。THREE.Texture 不进缓存
+// （它绑定具体 renderer 的 GPU 资源、且会被各自 backend dispose），每次按缓存的
+// HTMLImageElement 新建一个轻量 Texture 即可。
+const decodedImageCache = new Map();
+function textureFromImage(img) {
+    const tex = new THREE.Texture(img);
+    tex.colorSpace = THREE.SRGBColorSpace;
+    tex.needsUpdate = true;
+    return tex;
+}
+/**
+ * 若 src 对应图片此前已被 loadImageTexture 解码过，则同步返回一个新 Texture；否则
+ * 返回 null（调用方需走异步 loadImageTexture）。用于热路径（拖动重建）下零延迟首渲。
+ */
+export function getCachedImageTexture(src) {
+    const img = decodedImageCache.get(src);
+    if (!img || !img.complete || img.naturalWidth === 0)
+        return null;
+    return textureFromImage(img);
+}
+// dataURL / URL 都走 Image → THREE.Texture，避免 TextureLoader 在 headless 对 dataURL 失败。
+export async function loadImageTexture(src) {
+    if (typeof Image === "undefined")
+        return null;
+    const cached = decodedImageCache.get(src);
+    if (cached && cached.complete && cached.naturalWidth > 0) {
+        return textureFromImage(cached);
+    }
+    const img = await new Promise((resolve) => {
+        const i = new Image();
+        i.crossOrigin = "anonymous";
+        i.onload = () => resolve(i);
+        i.onerror = () => resolve(null);
+        i.src = src;
+    });
+    if (!img || !img.complete || img.naturalWidth === 0)
+        return null;
+    decodedImageCache.set(src, img);
+    return textureFromImage(img);
+}

package/dist/esm/shape-path.js

@@ -0,0 +1,64 @@
+// 实时 WebGL 与离屏烘焙共用的形状范围。文字框用正面贴图（字形画进这张图）再挤出。
+// 组合本身不进；组合里的子形状各自判断。
+const SHAPE_3D_KINDS = new Set(["image", "rect", "ellipse", "path", "polygon", "text"]);
+/** 与 bake-sp3d 的 image pad 一致：贴图几何收在 bbox 内。 */
+export const IMAGE_3D_PAD = 0.05;
+/** 与 bake-sp3d 的非 image pad 一致：倒角会对称外扩。 */
+export const SHAPE_3D_PAD = 0.15;
+export function shapeSupports3D(s) {
+    return SHAPE_3D_KINDS.has(s.kind);
+}
+export function shape3DPad(kind) {
+    // 文字正面是字形贴图，留白和 image slab 一样，避免倒角把字挤出画布。
+    return kind === "image" || kind === "text" ? IMAGE_3D_PAD : SHAPE_3D_PAD;
+}
+/** 形状上真正参加 3D 的那份参数。文字只看 bodyPr，避免和形状自己的 spPr 3D 各挤出一次。 */
+export function shape3DInfo(s) {
+    if (s.kind === "text")
+        return s.body3D;
+    return s.meta3D;
+}
+/**
+ * 非 image 形状的挤出轮廓，坐标系是形状本地的 0..bbox。
+ * image 不需要轮廓（正面是贴图 slab）。rect 也不返回：scene-builder 在没有 pathD
+ * 时已经按 bbox 挤出一个矩形。path 的 `d` 原样传入，由场景构建器按路径自身包围盒居中。
+ */
+export function shape3DPathD(s) {
+    if (s.kind === "path")
+        return s.d || undefined;
+    if (s.kind === "ellipse")
+        return ellipsePathD(s.bbox.w, s.bbox.h);
+    if (s.kind === "polygon" && s.points.length > 0)
+        return polygonPathD(s);
+    return undefined;
+}
+function ellipsePathD(w, h) {
+    const rx = w / 2;
+    const ry = h / 2;
+    const k = 0.5522847498;
+    const cx = rx;
+    const cy = ry;
+    const kx = rx * k;
+    const ky = ry * k;
+    return [
+        `M ${cx} 0`,
+        `C ${cx + kx} 0 ${w} ${cy - ky} ${w} ${cy}`,
+        `C ${w} ${cy + ky} ${cx + kx} ${h} ${cx} ${h}`,
+        `C ${cx - kx} ${h} 0 ${cy + ky} 0 ${cy}`,
+        `C 0 ${cy - ky} ${cx - kx} 0 ${cx} 0`,
+        "Z",
+    ].join(" ");
+}
+function polygonPathD(s) {
+    const minX = Math.min(...s.points.map((p) => p[0]));
+    const minY = Math.min(...s.points.map((p) => p[1]));
+    const absolute = Math.abs(minX - s.bbox.x) < 2 && Math.abs(minY - s.bbox.y) < 2;
+    const pts = absolute
+        ? s.points.map(([x, y]) => [x - s.bbox.x, y - s.bbox.y])
+        : s.points;
+    const [x0, y0] = pts[0];
+    let d = `M ${x0} ${y0}`;
+    for (let i = 1; i < pts.length; i++)
+        d += ` L ${pts[i][0]} ${pts[i][1]}`;
+    return `${d} Z`;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/bake-sp3d.d.ts

@@ -0,0 +1,2 @@
+import type { Shape3DRequest, Shape3DResult } from "./types.js";
+export declare function bakeSp3d(req: Shape3DRequest): Promise<Shape3DResult | null>;

package/dist/types/camera.d.ts

@@ -0,0 +1,7 @@
+import * as THREE from "three";
+import type { ResolvedBackdrop, ResolvedCamera } from "./resolve.js";
+export interface CameraResult {
+    camera: THREE.Camera;
+    isOrtho: boolean;
+}
+export declare function setupCamera(cam: ResolvedCamera, target: THREE.Vector3, distance: number, backdrop?: ResolvedBackdrop): CameraResult;

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { bakeSp3d } from "./bake-sp3d.js";
+export { createBake3DRuntime, needs3DRender, needs3DBake, type Bake3DRuntime } from "./runtime.js";
+export { resolveScene3D, resolveCamera, resolveSp3D, resolveLightRig, resolveBackdrop, type ResolvedScene3D, type ResolvedCamera, type ResolvedSp3D, type ResolvedLightRig, type ResolvedBevel, type ResolvedBackdrop, } from "./resolve.js";
+export { buildThreeScene, createSceneCamera, loadImageTexture, getCachedImageTexture, type BuildSceneInputs, type BuiltScene, } from "./scene-builder.js";
+export { applyTextureCrop } from "./material.js";
+export { shapeSupports3D, shape3DInfo, shape3DPathD, shape3DPad, IMAGE_3D_PAD, SHAPE_3D_PAD, } from "./shape-path.js";
+export { CAMERA_PRESETS, type CameraPreset } from "./presets.js";

package/dist/types/light-rig.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from "three";
+export interface LightRigSpec {
+    ambient: number;
+    lights: Array<{
+        color: number;
+        intensity: number;
+        pos: [number, number, number];
+    }>;
+}
+export declare function applyLightRig(scene: THREE.Scene, rigName: string | undefined, dir: string | undefined): void;

package/dist/types/material.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from "three";
+import type { Paint } from "@sliiu/present-core";
+export interface MaterialOpts {
+    prst?: string;
+    fallbackColor?: string;
+    imageTexture?: THREE.Texture;
+    litTexture?: boolean;
+    tint?: number;
+}
+export declare function pickPrimaryColor(paint: Paint | undefined, fallback: string): string;
+export declare function buildMaterial(paint: Paint | undefined, opts?: MaterialOpts): THREE.Material;
+export declare function applyTextureCrop(texture: THREE.Texture, cropRect: {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+} | undefined): void;

package/dist/types/path-to-shape.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+export interface PathParse {
+    shapes: THREE.Shape[];
+    bbox: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+}
+export declare function pathDToShapes(d: string): PathParse;