@playcraft/cli 0.1.63 → 0.1.64

package/dist/model-preparation/glb.js

@@ -0,0 +1,176 @@
+import { readModelSourceDocument } from '@playcraft/common/cloud-workspace/runtime';
+import { createHash } from 'node:crypto';
+import { add, cross, dot, f32, length, mul, unit } from './geometry.js';
+export const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const identity = () => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function matrixMultiply(a, b) {
+    return Array.from({ length: 16 }, (_, i) => { const r = i % 4, c = Math.floor(i / 4); return [0, 1, 2, 3].reduce((sum, k) => sum + a[k * 4 + r] * b[c * 4 + k], 0); });
+}
+function nodeMatrix(node) {
+    if (node.matrix) {
+        if (!Array.isArray(node.matrix) || node.matrix.length !== 16 || !node.matrix.every(Number.isFinite))
+            throw Error('model_preparation_transform_invalid');
+        return node.matrix;
+    }
+    const t = node.translation ?? [0, 0, 0], s = node.scale ?? [1, 1, 1], q = node.rotation ?? [0, 0, 0, 1];
+    if (t.length !== 3 || s.length !== 3 || q.length !== 4 || ![...t, ...s, ...q].every(Number.isFinite) || Math.abs(Math.hypot(...q) - 1) > 1e-4)
+        throw Error('model_preparation_transform_invalid');
+    const [x, y, z, w] = q;
+    return [(1 - 2 * (y * y + z * z)) * s[0], 2 * (x * y + z * w) * s[0], 2 * (x * z - y * w) * s[0], 0,
+        2 * (x * y - z * w) * s[1], (1 - 2 * (x * x + z * z)) * s[1], 2 * (y * z + x * w) * s[1], 0,
+        2 * (x * z + y * w) * s[2], 2 * (y * z - x * w) * s[2], (1 - 2 * (x * x + y * y)) * s[2], 0,
+        t[0], t[1], t[2], 1];
+}
+export function readRigidGlb(bytes) {
+    const parsed = readModelSourceDocument(bytes), d = parsed.document, binary = parsed.binary;
+    if (!binary || parsed.extraChunks?.length || d.asset?.version !== '2.0' || d.buffers?.length !== 1 || d.buffers.some((b) => b.uri) ||
+        d.animations?.length || d.skins?.length || d.meshes?.length !== 1 || !Array.isArray(d.nodes) || d.nodes.length > 256)
+        throw Error('model_preparation_single_rigid_glb_required');
+    const primitive = d.meshes[0].primitives?.[0];
+    if (d.meshes[0].primitives?.length !== 1 || !primitive || primitive.targets || primitive.extensions || (primitive.mode ?? 4) !== 4 ||
+        Object.keys(primitive.attributes ?? {}).some(key => !['POSITION', 'NORMAL', 'TEXCOORD_0'].includes(key)))
+        throw Error('model_preparation_attributes_unsupported');
+    let world;
+    const visited = new Set();
+    const walk = (id, parent) => {
+        if (!Number.isSafeInteger(id) || visited.has(id) || !d.nodes[id])
+            throw Error('model_preparation_node_graph_invalid');
+        visited.add(id);
+        const node = d.nodes[id];
+        if (node.skin !== undefined || node.extensions)
+            throw Error('model_preparation_node_unsupported');
+        const matrix = matrixMultiply(parent, nodeMatrix(node));
+        if (node.mesh !== undefined) {
+            if (world || node.mesh !== 0)
+                throw Error('model_preparation_single_instance_required');
+            world = matrix;
+        }
+        for (const child of node.children ?? [])
+            walk(child, matrix);
+    };
+    for (const node of d.scenes?.[d.scene ?? 0]?.nodes ?? [])
+        walk(node, identity());
+    if (!world)
+        throw Error('model_preparation_empty_scene');
+    const m = world, axes = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]], sizes = axes.map(length);
+    const determinant = dot(axes[0], cross(axes[1], axes[2]));
+    if (!m.every(Number.isFinite) || Math.abs(m[3]) + Math.abs(m[7]) + Math.abs(m[11]) + Math.abs(m[15] - 1) > 1e-9 || determinant <= 0 ||
+        Math.min(...sizes) < 1e-12 || Math.max(...sizes) / Math.min(...sizes) > 1.00001 ||
+        Math.abs(dot(axes[0], axes[1])) + Math.abs(dot(axes[1], axes[2])) + Math.abs(dot(axes[2], axes[0])) > sizes[0] ** 2 * 1e-5)
+        throw Error('model_preparation_positive_rigid_transform_required');
+    function accessor(id, components, allowed) {
+        const a = d.accessors?.[id], v = d.bufferViews?.[a?.bufferView], bytesPer = a?.componentType === 5126 || a?.componentType === 5125 ? 4 : 2;
+        if (!a || a.sparse || a.normalized || !allowed.includes(a.componentType) || a.type !== (components === 3 ? 'VEC3' : components === 2 ? 'VEC2' : 'SCALAR') ||
+            !Number.isSafeInteger(a.count) || a.count < 1 || a.count > 600000 || !v || v.buffer !== 0 || v.extensions)
+            throw Error('model_preparation_accessor_unsupported');
+        const start = (v.byteOffset ?? 0) + (a.byteOffset ?? 0), stride = v.byteStride ?? components * bytesPer;
+        if (![start, stride, v.byteLength].every(Number.isSafeInteger) || start < 0 || stride < components * bytesPer ||
+            start + (a.count - 1) * stride + components * bytesPer > (v.byteOffset ?? 0) + v.byteLength || (v.byteOffset ?? 0) + v.byteLength > binary.length)
+            throw Error('model_preparation_accessor_bound');
+        const view = new DataView(binary.buffer, binary.byteOffset, binary.byteLength);
+        return Array.from({ length: a.count }, (_, i) => Array.from({ length: components }, (_, k) => {
+            const offset = start + i * stride + k * bytesPer, value = a.componentType === 5126 ? view.getFloat32(offset, true) : bytesPer === 4 ? view.getUint32(offset, true) : view.getUint16(offset, true);
+            if (!Number.isFinite(value))
+                throw Error('model_preparation_nonfinite_accessor');
+            return value;
+        }));
+    }
+    const p = accessor(primitive.attributes.POSITION, 3, [5126]), n = accessor(primitive.attributes.NORMAL, 3, [5126]), uv = accessor(primitive.attributes.TEXCOORD_0, 2, [5126]);
+    const indices = accessor(primitive.indices, 1, [5123, 5125]).flat();
+    if (p.length !== n.length || p.length !== uv.length || indices.length % 3 || indices.length / 3 > 100000 || indices.some(i => i >= p.length))
+        throw Error('model_preparation_primitive_bound');
+    const transformVector = (v) => add(add(mul(axes[0], v[0]), mul(axes[1], v[1])), mul(axes[2], v[2]));
+    const faces = [];
+    for (let i = 0; i < indices.length; i += 3)
+        faces.push({ sourceTriangle: i / 3, kind: 'exterior', v: [0, 1, 2].map(k => {
+                const id = indices[i + k];
+                return { p: f32(add(transformVector(p[id]), [m[12], m[13], m[14]])), n: unit(transformVector(n[id])), uv: uv[id],
+                    bary: [+(k === 0), +(k === 1), +(k === 2)] };
+            }) });
+    const textures = (d.images ?? []).map((image) => {
+        const v = d.bufferViews?.[image.bufferView];
+        if (image.uri || !v || v.buffer !== 0 || !['image/png', 'image/jpeg', 'image/webp'].includes(image.mimeType) || v.byteOffset < 0 || v.byteOffset + v.byteLength > binary.length)
+            throw Error('model_preparation_embedded_image_required');
+        const data = binary.slice(v.byteOffset ?? 0, (v.byteOffset ?? 0) + v.byteLength);
+        return { image, bytes: data, contentHash: digest(data) };
+    });
+    if (!d.materials?.[primitive.material])
+        throw Error('model_preparation_material_required');
+    const positionAccessor = d.accessors[primitive.attributes.POSITION], positionView = d.bufferViews[positionAccessor.bufferView];
+    const binaryOffset = 28 + new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(12, true);
+    const positionByteOffsets = p.map((_, i) => binaryOffset + (positionView.byteOffset ?? 0) + (positionAccessor.byteOffset ?? 0) + i * (positionView.byteStride ?? 12));
+    return { faces, document: d, textures, materialIndex: primitive.material, sourceWorldMatrix: m,
+        localPositions: p, sourceIndices: indices, positionByteOffsets };
+}
+export function encodeSplitGlb(source, parts, parentHash) {
+    const chunks = [], bufferViews = [], accessors = [];
+    let byteOffset = 0;
+    const append = (bytes, target) => {
+        const id = bufferViews.length;
+        bufferViews.push({ buffer: 0, byteOffset, byteLength: bytes.length, ...(target ? { target } : {}) });
+        const padded = new Uint8Array(Math.ceil(bytes.length / 4) * 4);
+        padded.set(bytes);
+        chunks.push(padded);
+        byteOffset += padded.length;
+        return id;
+    };
+    const images = source.textures.map(t => ({ ...t.image, bufferView: append(t.bytes) }));
+    const materials = [...source.document.materials, { name: 'authored_untextured_wood_interior', doubleSided: false,
+            pbrMetallicRoughness: { baseColorFactor: [.18, .095, .035, 1], metallicFactor: 0, roughnessFactor: .9 } }];
+    const attribute = (array, type, components, target) => {
+        const id = accessors.length, view = append(new Uint8Array(array.buffer), target), count = array.length / components;
+        const min = Array.from({ length: components }, () => Infinity), max = min.map(() => -Infinity);
+        for (let i = 0; i < array.length; i++) {
+            const k = i % components;
+            min[k] = Math.min(min[k], array[i]);
+            max[k] = Math.max(max[k], array[i]);
+        }
+        accessors.push({ bufferView: view, componentType: array instanceof Float32Array ? 5126 : 5125, count, type, min, max });
+        return id;
+    };
+    const primitiveFaceCounts = [];
+    const meshes = parts.map(part => {
+        const groups = [part.faces.filter(f => ['exterior', 'auxiliary'].includes(f.kind)), part.faces.filter(f => ['interior', 'rim'].includes(f.kind))];
+        primitiveFaceCounts.push({ exterior: groups[0].length, interiorAndRim: groups[1].length });
+        return { name: `split_${part.role}_mesh`, primitives: groups.filter(fs => fs.length).map((fs, group) => {
+                const positions = [], normals = [], uvs = [], indices = [], seen = new Map();
+                for (const face of fs)
+                    for (const v of face.v) {
+                        const p = f32(v.p), n = f32(v.n), uv = v.uv.map(Math.fround), key = [...p, ...n, ...uv].join(',');
+                        let id = seen.get(key);
+                        if (id === undefined) {
+                            id = positions.length / 3;
+                            seen.set(key, id);
+                            positions.push(...p);
+                            normals.push(...n);
+                            uvs.push(...uv);
+                        }
+                        indices.push(id);
+                    }
+                return { attributes: { POSITION: attribute(new Float32Array(positions), 'VEC3', 3, 34962), NORMAL: attribute(new Float32Array(normals), 'VEC3', 3, 34962),
+                        TEXCOORD_0: attribute(new Float32Array(uvs), 'VEC2', 2, 34962) }, indices: attribute(new Uint32Array(indices), 'SCALAR', 1, 34963), material: group ? materials.length - 1 : source.materialIndex };
+            }) };
+    });
+    const document = { asset: { ...source.document.asset, generator: 'PlayCraft restricted rigid shell preparation' }, buffers: [{ byteLength: byteOffset }], bufferViews, accessors,
+        images, textures: source.document.textures ?? [], samplers: source.document.samplers ?? [], materials, meshes,
+        nodes: parts.map((part, mesh) => ({ name: `split_${part.role}`, mesh, extras: { playcraftPart: part.role } })), scenes: [{ nodes: parts.map((_, i) => i) }], scene: 0,
+        ...(source.document.extensionsUsed ? { extensionsUsed: source.document.extensionsUsed } : {}),
+        ...(source.document.extensionsRequired ? { extensionsRequired: source.document.extensionsRequired } : {}), extras: { playcraftParentSourceHash: parentHash, preparation: 'restricted-rigid-shell-v1' } };
+    const json = new TextEncoder().encode(JSON.stringify(document)), jsonLength = Math.ceil(json.length / 4) * 4;
+    const output = new Uint8Array(12 + 8 + jsonLength + 8 + byteOffset), view = new DataView(output.buffer);
+    view.setUint32(0, 0x46546c67, true);
+    view.setUint32(4, 2, true);
+    view.setUint32(8, output.length, true);
+    view.setUint32(12, jsonLength, true);
+    view.setUint32(16, 0x4e4f534a, true);
+    output.fill(32, 20, 20 + jsonLength);
+    output.set(json, 20);
+    view.setUint32(20 + jsonLength, byteOffset, true);
+    view.setUint32(24 + jsonLength, 0x004e4942, true);
+    let offset = 28 + jsonLength;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return { bytes: output, document, primitiveFaceCounts };
+}

package/dist/model-preparation/split-rigid.js

@@ -0,0 +1,302 @@
+import { lstat, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { canonicalModelAdaptation } from '@playcraft/common/cloud-workspace/runtime';
+import earcut, { deviation } from 'earcut';
+import { add, area, assertClearance, assertNoSelfIntersections, bounds, cross, dot, f32, length, mul, pointKey, sub, topology, unit, windingNumber } from './geometry.js';
+import { digest, encodeSplitGlb, readRigidGlb } from './glb.js';
+const tris = (fs) => fs.map(f => f.v.map(v => v.p));
+function closed(triangles, epsilon) {
+    const result = topology(triangles, epsilon);
+    if (result.degenerate || result.boundaryEdges || result.nonManifoldEdges || result.inconsistentEdges || result.signedVolume <= epsilon ** 3)
+        throw Error('model_preparation_closed_oriented_surface_required');
+    return result;
+}
+function validateOptions(options) {
+    if (Object.keys(options).some(key => !['plane', 'hingeAxis', 'innerScale', 'lidInnerLift', 'minimumThickness', 'hingeBackClearance', 'openAngleDegrees', 'maximumAuxiliaryAreaFraction', 'omitMicroscopicAuxiliary', 'bodyInterior'].includes(key)) ||
+        Object.keys(options.plane).some(key => !['normal', 'constant'].includes(key)) ||
+        (options.omitMicroscopicAuxiliary !== undefined && typeof options.omitMicroscopicAuxiliary !== 'boolean'))
+        throw Error('model_preparation_options_invalid');
+    const axis = (v) => v.length === 3 && v.filter(x => Math.abs(x) === 1).length === 1 && v.filter(x => x === 0).length === 2;
+    if (!axis(options.plane.normal) || !axis(options.hingeAxis) || dot(options.plane.normal, options.hingeAxis) !== 0)
+        throw Error('model_preparation_axis_aligned_scene_plane_required');
+    if (![options.plane.constant, ...options.innerScale, options.lidInnerLift, options.minimumThickness, options.hingeBackClearance, options.openAngleDegrees].every(Number.isFinite) ||
+        options.innerScale.length !== 3 || options.innerScale.some(x => x <= 0 || x >= 1) || options.lidInnerLift < 0 || options.minimumThickness <= 0 ||
+        options.hingeBackClearance <= 0 || options.openAngleDegrees >= 0 || options.openAngleDegrees < -90 ||
+        (options.maximumAuxiliaryAreaFraction !== undefined && (!Number.isFinite(options.maximumAuxiliaryAreaFraction) || options.maximumAuxiliaryAreaFraction < 0 || options.maximumAuxiliaryAreaFraction > .0001)))
+        throw Error('model_preparation_options_invalid');
+    if (options.bodyInterior) {
+        const b = options.bodyInterior;
+        if (b.kind !== 'smooth-inset' || Object.keys(b).some(k => !['kind', 'minU', 'maxU', 'minV', 'maxV', 'floorHeight'].includes(k)) ||
+            ![b.minU, b.maxU, b.minV, b.maxV, b.floorHeight].every(Number.isFinite) || b.minU >= b.maxU || b.minV >= b.maxV || b.floorHeight >= options.plane.constant - options.minimumThickness)
+            throw Error('model_preparation_body_interior_invalid');
+    }
+}
+function clipping(primary, normal, height) {
+    const shared = new Map();
+    const distance = (v) => dot(v.p, normal) - height;
+    const intersection = (a, b) => {
+        const da = distance(a), db = distance(b), t = da / (da - db), ak = pointKey(a.p), bk = pointKey(b.p), key = ak < bk ? `${ak}/${bk}` : `${bk}/${ak}`;
+        let p = shared.get(key);
+        if (!p) {
+            const first = ak < bk ? a : b, second = ak < bk ? b : a, ratio = distance(first) / (distance(first) - distance(second));
+            p = f32(add(first.p, mul(sub(second.p, first.p), ratio)));
+            const axis = normal.findIndex(v => v !== 0);
+            p[axis] = height * normal[axis];
+            shared.set(key, p);
+        }
+        return { p, n: unit(add(mul(a.n, 1 - t), mul(b.n, t))), uv: [a.uv[0] * (1 - t) + b.uv[0] * t, a.uv[1] * (1 - t) + b.uv[1] * t],
+            bary: add(mul(a.bary, 1 - t), mul(b.bary, t)) };
+    };
+    const half = (positive) => {
+        const result = [];
+        for (const face of primary) {
+            const polygon = [];
+            for (let i = 0; i < 3; i++) {
+                const a = face.v[i], b = face.v[(i + 1) % 3], ain = positive ? distance(a) >= 0 : distance(a) <= 0, bin = positive ? distance(b) >= 0 : distance(b) <= 0;
+                if (ain)
+                    polygon.push(a);
+                if (ain !== bin)
+                    polygon.push(intersection(a, b));
+            }
+            const unique = polygon.filter((p, i) => pointKey(p.p) !== pointKey(polygon[(i + polygon.length - 1) % polygon.length].p));
+            for (let i = 1; i + 1 < unique.length; i++)
+                result.push({ ...face, v: [unique[0], unique[i], unique[i + 1]] });
+        }
+        return result;
+    };
+    return { body: half(false), lid: half(true) };
+}
+function boundaryLoop(faces, normal, height, epsilon) {
+    const edges = new Map();
+    for (const f of faces)
+        for (let i = 0; i < 3; i++) {
+            const from = f.v[i], to = f.v[(i + 1) % 3], a = pointKey(from.p), b = pointKey(to.p), key = a < b ? `${a}/${b}` : `${b}/${a}`, old = edges.get(key);
+            if (old)
+                old.count++;
+            else
+                edges.set(key, { from, to, count: 1 });
+        }
+    const boundary = [...edges.values()].filter(e => e.count === 1), outgoing = new Map(), incoming = new Set();
+    for (const edge of boundary) {
+        const key = pointKey(edge.from.p), end = pointKey(edge.to.p);
+        if (Math.abs(dot(edge.from.p, normal) - height) > epsilon || outgoing.has(key) || incoming.has(end))
+            throw Error('model_preparation_simple_cut_loop_required');
+        outgoing.set(key, edge);
+        incoming.add(end);
+    }
+    if (boundary.length < 3 || boundary.length > 4096)
+        throw Error('model_preparation_cut_loop_bound');
+    const ordered = [], start = pointKey(boundary[0].from.p), seen = new Set();
+    let key = start;
+    while (!seen.has(key)) {
+        seen.add(key);
+        const e = outgoing.get(key);
+        if (!e)
+            throw Error('model_preparation_cut_loop_open');
+        ordered.push(e);
+        key = pointKey(e.to.p);
+    }
+    if (key !== start || ordered.length !== boundary.length)
+        throw Error('model_preparation_single_cut_loop_required');
+    return ordered;
+}
+function makeShell(outer, loop, center, basis, scale, lift, epsilon, role) {
+    const transform = (p) => f32(add(center, basis.reduce((sum, axis, i) => add(sum, mul(axis, dot(sub(p, center), axis) * scale[i] + (i === 1 ? lift : 0))), [0, 0, 0])));
+    const innerVertex = (v) => ({ p: transform(v.p), n: mul(unit(basis.reduce((sum, axis, i) => add(sum, mul(axis, dot(v.n, axis) / scale[i])), [0, 0, 0])), -1),
+        uv: [dot(sub(v.p, center), basis[0]), dot(sub(v.p, center), basis[2])], bary: v.bary });
+    const inner = outer.map(f => ({ kind: 'interior', sourceTriangle: -1, v: [innerVertex(f.v[0]), innerVertex(f.v[2]), innerVertex(f.v[1])] }));
+    const ring = loop.map(e => e.from), rim = makeRim(ring, ring.map(innerVertex), center, basis, epsilon, role);
+    return { faces: [...outer, ...inner, ...rim], inner, rim };
+}
+function makeRim(ring, innerRing, center, basis, epsilon, role) {
+    const vertices = [...ring, ...innerRing], flat = vertices.flatMap(v => [dot(v.p, basis[0]), dot(v.p, basis[2])]);
+    const indices = earcut(flat, [ring.length], 2);
+    if (!indices.length || deviation(flat, [ring.length], 2, indices) > 1e-7)
+        throw Error('model_preparation_rim_triangulation_area_failed');
+    const pending = [];
+    for (let i = 0; i < indices.length; i += 3)
+        pending.push(indices.slice(i, i + 3));
+    const triangles = [];
+    // Earcut may remove collinear contour vertices. Reinsert them on every spanning edge to avoid T-junctions.
+    while (pending.length) {
+        const triangle = pending.pop();
+        let split = false;
+        for (let edge = 0; edge < 3 && !split; edge++) {
+            const a = triangle[edge], b = triangle[(edge + 1) % 3], c = triangle[(edge + 2) % 3], ax = flat[a * 2], ay = flat[a * 2 + 1], dx = flat[b * 2] - ax, dy = flat[b * 2 + 1] - ay, square = dx * dx + dy * dy;
+            for (let q = 0; q < vertices.length; q++) {
+                if (triangle.includes(q))
+                    continue;
+                const qx = flat[q * 2] - ax, qy = flat[q * 2 + 1] - ay, t = (qx * dx + qy * dy) / square;
+                if (t <= epsilon / Math.sqrt(square) || t >= 1 - epsilon / Math.sqrt(square) || Math.abs(dx * qy - dy * qx) > epsilon * Math.sqrt(square))
+                    continue;
+                pending.push([a, q, c], [q, b, c]);
+                split = true;
+                break;
+            }
+        }
+        if (!split)
+            triangles.push(triangle);
+        if (triangles.length + pending.length > vertices.length * 8)
+            throw Error('model_preparation_rim_triangulation_bound');
+    }
+    const rim = triangles.map(ids => {
+        const corners = ids.map(i => vertices[i]);
+        let n = unit(cross(sub(corners[1].p, corners[0].p), sub(corners[2].p, corners[0].p)));
+        if (dot(n, basis[1]) * (role === 'lid' ? -1 : 1) < 0) {
+            [corners[1], corners[2]] = [corners[2], corners[1]];
+            n = mul(n, -1);
+        }
+        return { kind: 'rim', sourceTriangle: -1, v: corners.map(v => ({ ...v, n, uv: [dot(sub(v.p, center), basis[0]), dot(sub(v.p, center), basis[2])] })) };
+    });
+    return rim;
+}
+function makeSmoothBody(outer, loop, center, basis, cavity, epsilon) {
+    const point = (u, h, v) => ({ p: f32(add(add(mul(basis[0], u), mul(basis[1], h)), mul(basis[2], v))),
+        n: [0, 0, 0], uv: [u, v], bary: [0, 0, 0] });
+    const rectangle = [[cavity.minU, cavity.minV], [cavity.maxU, cavity.minV], [cavity.maxU, cavity.maxV], [cavity.minU, cavity.maxV]];
+    const top = rectangle.map(([u, v]) => point(u, dot(center, basis[1]), v)), bottom = rectangle.map(([u, v]) => point(u, cavity.floorHeight, v));
+    const inner = [];
+    const face = (v) => {
+        const n = unit(cross(sub(v[1].p, v[0].p), sub(v[2].p, v[0].p)));
+        inner.push({ kind: 'interior', sourceTriangle: -1, v: v.map(c => ({ ...c, n })) });
+    };
+    for (let i = 0; i < 4; i++) {
+        const j = (i + 1) % 4;
+        face([top[j], top[i], bottom[i]]);
+        face([top[j], bottom[i], bottom[j]]);
+    }
+    face([bottom[0], bottom[2], bottom[1]]);
+    face([bottom[0], bottom[3], bottom[2]]);
+    const rim = makeRim(loop.map(e => e.from), top, center, basis, epsilon, 'body');
+    return { faces: [...outer, ...inner, ...rim], inner, rim };
+}
+/** Produces an authored derivative only after proving the supported rigid-shell geometry constraints. */
+export function prepareRigidSplit(bytes, options, signal) {
+    validateOptions(options);
+    signal?.throwIfAborted();
+    const source = readRigidGlb(bytes), inputTriangles = tris(source.faces), box = bounds(inputTriangles);
+    const epsilon = Math.max(length(sub(box.max, box.min)) * 1e-8, 1e-10), sourceTopology = topology(inputTriangles, epsilon);
+    const groups = sourceTopology.components, mainIds = new Set(groups[0]), main = source.faces.filter((_, i) => mainIds.has(i)), sourceAuxiliary = source.faces.filter((_, i) => !mainIds.has(i));
+    const mainTriangles = tris(main), mainArea = mainTriangles.reduce((sum, t) => sum + area(t), 0), auxiliaryArea = tris(sourceAuxiliary).reduce((sum, t) => sum + area(t), 0);
+    if (auxiliaryArea > mainArea * (options.maximumAuxiliaryAreaFraction ?? .0001))
+        throw Error('model_preparation_significant_disconnected_components');
+    const auxiliaryDiagnostics = groups.slice(1).map(ids => {
+        const triangles = ids.map(i => inputTriangles[i]), componentBounds = bounds(triangles), extent = sub(componentBounds.max, componentBounds.min);
+        return { sourceTriangles: ids, area: triangles.reduce((sum, t) => sum + area(t), 0), bounds: componentBounds, extent,
+            maximumExtentFraction: Math.max(...extent) / length(sub(box.max, box.min)) };
+    });
+    if (options.omitMicroscopicAuxiliary && auxiliaryDiagnostics.some(c => c.maximumExtentFraction > .005))
+        throw Error('model_preparation_auxiliary_extent_not_microscopic');
+    const auxiliary = options.omitMicroscopicAuxiliary ? [] : sourceAuxiliary;
+    const validatedSourceTriangles = options.omitMicroscopicAuxiliary ? mainTriangles : inputTriangles;
+    closed(validatedSourceTriangles, epsilon);
+    const sourceIntersection = assertNoSelfIntersections(validatedSourceTriangles, epsilon, signal);
+    const normal = options.plane.normal, height = Math.fround(options.plane.constant), axis = options.hingeAxis, depth = cross(axis, normal), basis = [axis, normal, depth];
+    const heights = main.flatMap(f => f.v.map(v => dot(v.p, normal)));
+    if (height <= Math.min(...heights) + epsilon || height >= Math.max(...heights) - epsilon)
+        throw Error('model_preparation_cut_outside_source');
+    // A plane through an original vertex is intentionally rejected rather than heuristically repairing a branched/zero-area seam.
+    if (heights.some(v => Math.abs(v - height) <= epsilon))
+        throw Error('model_preparation_plane_touches_vertex');
+    const halves = clipping(main, normal, height), loops = { body: boundaryLoop(halves.body, normal, height, epsilon), lid: boundaryLoop(halves.lid, normal, height, epsilon) };
+    const coordinates = source.faces.flatMap(f => f.v.map(v => [dot(v.p, axis), dot(v.p, depth)]));
+    const centerU = (Math.min(...coordinates.map(p => p[0])) + Math.max(...coordinates.map(p => p[0]))) / 2;
+    const centerV = (Math.min(...coordinates.map(p => p[1])) + Math.max(...coordinates.map(p => p[1]))) / 2;
+    const center = add(add(mul(axis, centerU), mul(normal, height)), mul(depth, centerV));
+    const parts = ['body', 'lid'].map(role => {
+        const outer = halves[role], shell = role === 'body' && options.bodyInterior
+            ? makeSmoothBody(outer, loops[role], center, basis, options.bodyInterior, epsilon)
+            : makeShell(outer, loops[role], center, basis, options.innerScale, role === 'lid' ? options.lidInnerLift : 0, epsilon, role);
+        const auxiliaries = auxiliary.filter(face => {
+            const distances = face.v.map(v => dot(v.p, normal) - height);
+            if (Math.min(...distances) < 0 && Math.max(...distances) > 0)
+                throw Error('model_preparation_auxiliary_crosses_cut');
+            return role === 'body' ? Math.max(...distances) < 0 : Math.min(...distances) > 0;
+        }).map(f => ({ ...f, kind: 'auxiliary' }));
+        shell.faces.push(...auxiliaries);
+        const outputTriangles = tris(shell.faces), checks = closed(outputTriangles, epsilon);
+        let selfIntersection;
+        try {
+            selfIntersection = assertNoSelfIntersections(outputTriangles, epsilon, signal);
+        }
+        catch (error) {
+            const match = /self_intersection:(\d+):(\d+)/.exec(error instanceof Error ? error.message : '');
+            if (match)
+                Object.assign(error, { preparationPhase: `${role}:shell`, geometryPair: match.slice(1).map(index => {
+                        const face = shell.faces[Number(index)];
+                        return { index: Number(index), kind: face.kind, sourceTriangle: face.sourceTriangle, positions: face.v.map(v => v.p) };
+                    }) });
+            throw error;
+        }
+        const clearance = assertClearance(tris(shell.inner), validatedSourceTriangles, options.minimumThickness, epsilon, signal);
+        const winding = windingNumber(shell.inner[0].v[0].p, mainTriangles);
+        if (Math.abs(winding - 1) > 1e-4)
+            throw Error('model_preparation_inner_not_contained');
+        return { role, ...shell, checks: { ...checks, components: checks.components.map(ids => ids.length), selfIntersection, clearance, innerWindingNumber: winding },
+            exteriorFaces: outer.length, auxiliaryFaces: auxiliaries.length, boundaryEdges: loops[role].length };
+    });
+    const pivot = add(add(mul(axis, centerU), mul(normal, height)), mul(depth, Math.min(...coordinates.map(p => p[1])) - options.hingeBackClearance));
+    const body = parts[0], lid = parts[1];
+    if (body.faces.some(f => f.v.some(v => dot(v.p, normal) > height + epsilon)) || lid.faces.some(f => f.v.some(v => dot(v.p, normal) < height - epsilon || dot(sub(v.p, pivot), depth) < options.hingeBackClearance - epsilon)))
+        throw Error('model_preparation_hinge_separation_unproven');
+    const output = encodeSplitGlb(source, parts, digest(bytes));
+    const trace = parts.flatMap((part, node) => part.faces.filter(f => ['exterior', 'auxiliary'].includes(f.kind)).map((f, triangle) => ({ node, triangle, sourceTriangle: f.sourceTriangle, barycentric: f.v.map(v => v.bary) })));
+    let maxPositionResidual = 0, maxUvResidual = 0, maxNormalResidual = 0;
+    for (const part of parts)
+        for (const f of part.faces.filter(f => ['exterior', 'auxiliary'].includes(f.kind)))
+            for (const v of f.v) {
+                const original = source.faces[f.sourceTriangle], expected = original.v.reduce((sum, c, i) => add(sum, mul(c.p, v.bary[i])), [0, 0, 0]);
+                maxPositionResidual = Math.max(maxPositionResidual, length(sub(expected, v.p)));
+                for (let k = 0; k < 2; k++)
+                    maxUvResidual = Math.max(maxUvResidual, Math.abs(Math.fround(v.uv[k]) - original.v.reduce((sum, c, i) => sum + c.uv[k] * v.bary[i], 0)));
+                const expectedNormal = unit(original.v.reduce((sum, c, i) => add(sum, mul(c.n, v.bary[i])), [0, 0, 0]));
+                maxNormalResidual = Math.max(maxNormalResidual, length(sub(f32(v.n), expectedNormal)));
+            }
+    if (maxPositionResidual > epsilon * 8 || maxUvResidual > 1e-6 || maxNormalResidual > 1e-6)
+        throw Error('model_preparation_exterior_trace_failed');
+    const recipe = { algorithm: 'restricted-rigid-shell-v1', parentContentHash: digest(bytes), options: { ...options, plane: { normal, constant: height },
+            maximumAuxiliaryAreaFraction: options.maximumAuxiliaryAreaFraction ?? .0001, maximumOmittedAuxiliaryExtentFraction: .005, omitMicroscopicAuxiliary: options.omitMicroscopicAuxiliary === true } };
+    const manifest = { schemaVersion: 1, kind: 'restricted-rigid-shell-v1', recipeHash: digest(canonicalModelAdaptation(recipe)), recipe,
+        source: { contentHash: digest(bytes), bytes: bytes.length, worldMatrix: source.sourceWorldMatrix },
+        options: { ...options, plane: { normal, constant: height } }, sourceTopology: { ...sourceTopology, components: groups.map(ids => ids.length), sourceIntersection },
+        output: { contentHash: digest(output.bytes), bytes: output.bytes.length, nodes: parts.map((part, node) => ({ role: part.role, name: `split_${part.role}`, nodeIndex: node,
+                sourceNodeId: `root/${node}`, meshIndex: node, children: ['outer', 'interior'], runtimeGeometryHash: null, runtimeGeometryStatus: 'pending-actual-loader',
+                primitiveFaceCounts: output.primitiveFaceCounts[node], exteriorFaces: part.exteriorFaces, auxiliaryFaces: part.auxiliaryFaces, rimFaces: part.rim.length, cutEdges: part.boundaryEdges, checks: part.checks })) },
+        exteriorTrace: { triangles: trace.length, maxPositionResidual, maxUvResidual, maxNormalResidual, sourceSurfaceRegenerated: false,
+            omittedMicroscopicAuxiliary: options.omitMicroscopicAuxiliary ? { sourceTriangles: sourceAuxiliary.map(f => f.sourceTriangle), area: auxiliaryArea, areaFraction: auxiliaryArea / mainArea } : null },
+        sourceRepair: { omissionExplicitlyEnabled: options.omitMicroscopicAuxiliary === true, auxiliaryDiagnostics,
+            omittedComponents: options.omitMicroscopicAuxiliary ? auxiliaryDiagnostics : [], originalSourceModified: false },
+        textures: source.textures.map(t => ({ contentHash: t.contentHash, bytes: t.bytes.length, preserved: true })),
+        interior: { provenance: 'authored interior geometry with bridged rim and new untextured material; not recovered supplier interior',
+            body: options.bodyInterior ?? { kind: 'homothetic', scale: options.innerScale }, lid: { kind: 'homothetic', scale: options.innerScale },
+            bodyFloorLift: options.bodyInterior ? options.bodyInterior.floorHeight - Math.min(...heights) : (height - Math.min(...heights)) * (1 - options.innerScale[1]),
+            lidInnerLift: options.lidInnerLift, thicknessProvenLowerBound: options.minimumThickness },
+        hinge: { axis, pivot, openAngleDegrees: options.openAngleDegrees, proof: 'body at/below scene plane; lid at/above plane and wholly ahead of external back pivot; rotation -90..0 keeps lid above body plane',
+            lockAssignment: 'source surface above plane moves with lid, below plane stays with body; lock disengagement and appearance remain unverified', unlockAcceptance: false },
+        physicalHingeConnectionAcceptance: false,
+        geometryChecksPassed: true, visualAcceptance: false, browserAcceptance: false, modelAcceptance: false, publicationAcceptance: false };
+    return { bytes: output.bytes, manifest, trace, parts };
+}
+export async function splitRigidModel(input) {
+    input.signal?.throwIfAborted();
+    const sourcePath = resolve(input.sourcePath), info = await lstat(sourcePath);
+    if (await realpath(sourcePath) !== sourcePath || !info.isFile() || info.nlink !== 1 || info.size > 64 * 1024 * 1024 || !/\.glb$/i.test(sourcePath))
+        throw Error('model_preparation_source_file_invalid');
+    const sourceBytes = new Uint8Array(await readFile(sourcePath));
+    if (digest(sourceBytes) !== input.expectedSourceHash)
+        throw Error('model_preparation_source_hash_mismatch');
+    const outputRoot = resolve(input.outputRoot);
+    if (await realpath(dirname(outputRoot)) !== dirname(outputRoot))
+        throw Error('model_preparation_output_parent_invalid');
+    // Geometry is fully proved before creating any output directory. An existing destination is never reused.
+    const result = prepareRigidSplit(sourceBytes, input.options, input.signal), traceRaw = JSON.stringify(result.trace) + '\n';
+    const manifest = { ...result.manifest, parentFile: `parent/${basename(sourcePath)}`, exteriorTrace: { ...result.manifest.exteriorTrace, path: 'exterior-trace.json', contentHash: digest(traceRaw) } };
+    input.signal?.throwIfAborted();
+    await mkdir(outputRoot);
+    await mkdir(resolve(outputRoot, 'parent'));
+    await writeFile(resolve(outputRoot, 'parent', basename(sourcePath)), sourceBytes, { flag: 'wx' });
+    await writeFile(resolve(outputRoot, 'model.glb'), result.bytes, { flag: 'wx' });
+    await writeFile(resolve(outputRoot, 'exterior-trace.json'), traceRaw, { flag: 'wx' });
+    await writeFile(resolve(outputRoot, 'split-manifest.json'), JSON.stringify(manifest, null, 2) + '\n', { flag: 'wx' });
+    return { outputRoot, manifest };
+}

package/dist/model-preparation/vertex-repairs.js

@@ -0,0 +1,63 @@
+import { canonicalModelAdaptation } from '@playcraft/common/cloud-workspace/runtime';
+import { add, bounds, f32, length, mul, sub } from './geometry.js';
+import { digest, readRigidGlb } from './glb.js';
+export function rigidWeldedPositions(source) {
+    const positions = new Map();
+    source.localPositions.forEach((p, index) => {
+        const key = p.join(','), entry = positions.get(key) ?? { local: p, indices: [] };
+        entry.indices.push(index);
+        positions.set(key, entry);
+    });
+    return [...positions.values()].sort((a, b) => a.local[0] - b.local[0] || a.local[1] - b.local[1] || a.local[2] - b.local[2])
+        .map((entry, weldedPositionId) => ({ ...entry, weldedPositionId }));
+}
+/** Explicit bounded derivative repair. It patches only POSITION bytes, moving every UV/normal split copy. */
+export function applyRigidVertexRepairs(bytes, plan) {
+    if (plan.schemaVersion !== 1 || plan.parentContentHash !== digest(bytes) || plan.weldedPositionIdentity !== 'exact-local-float32-lexicographic-v1' ||
+        !Number.isFinite(plan.maximumDisplacementFraction) || plan.maximumDisplacementFraction <= 0 || plan.maximumDisplacementFraction > .0015 ||
+        !Array.isArray(plan.vertexRepairs) || !plan.vertexRepairs.length || plan.vertexRepairs.length > 64 ||
+        new Set(plan.vertexRepairs.map(r => r.weldedPositionId)).size !== plan.vertexRepairs.length ||
+        Object.keys(plan).some(k => !['schemaVersion', 'parentContentHash', 'weldedPositionIdentity', 'maximumDisplacementFraction', 'vertexRepairs'].includes(k)))
+        throw Error('model_preparation_repair_plan_invalid');
+    const source = readRigidGlb(bytes), welded = rigidWeldedPositions(source), sourceBounds = bounds(source.faces.map(f => f.v.map(v => v.p)));
+    const diagonal = length(sub(sourceBounds.max, sourceBounds.min)), matrix = source.sourceWorldMatrix;
+    const axes = [[matrix[0], matrix[1], matrix[2]], [matrix[4], matrix[5], matrix[6]], [matrix[8], matrix[9], matrix[10]]];
+    const output = bytes.slice(), view = new DataView(output.buffer), allowedBytes = new Set(), affected = new Set();
+    const localBounds = source.localPositions.reduce((b, p) => ({ min: b.min.map((x, k) => Math.min(x, p[k])),
+        max: b.max.map((x, k) => Math.max(x, p[k])) }), { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] });
+    const records = plan.vertexRepairs.map(repair => {
+        const vertex = welded[repair.weldedPositionId];
+        if (!Number.isSafeInteger(repair.weldedPositionId) || !vertex || repair.beforeLocal.length !== 3 || repair.afterLocal.length !== 3 ||
+            ![...repair.beforeLocal, ...repair.afterLocal].every(Number.isFinite) || repair.beforeLocal.some((v, i) => v !== vertex.local[i]) ||
+            Object.keys(repair).some(k => !['weldedPositionId', 'beforeLocal', 'afterLocal'].includes(k)))
+            throw Error('model_preparation_repair_vertex_identity_mismatch');
+        const after = f32(repair.afterLocal), delta = sub(after, vertex.local), worldDelta = axes.reduce((sum, axis, i) => add(sum, mul(axis, delta[i])), [0, 0, 0]);
+        const distance = length(worldDelta);
+        if (!distance || distance > diagonal * plan.maximumDisplacementFraction || after.some((v, k) => v < localBounds.min[k] || v > localBounds.max[k]))
+            throw Error('model_preparation_repair_displacement_bound');
+        for (const id of vertex.indices)
+            for (let k = 0; k < 3; k++) {
+                const offset = source.positionByteOffsets[id] + k * 4;
+                view.setFloat32(offset, after[k], true);
+                for (let j = 0; j < 4; j++)
+                    allowedBytes.add(offset + j);
+            }
+        const indexSet = new Set(vertex.indices);
+        source.sourceIndices.forEach((id, index) => { if (indexSet.has(id))
+            affected.add(Math.floor(index / 3)); });
+        return { weldedPositionId: vertex.weldedPositionId, beforeLocal: vertex.local, afterLocal: after, localDelta: delta, worldDelta,
+            worldDistance: distance, positionAccessorIndices: vertex.indices };
+    });
+    let changedBytes = 0;
+    for (let i = 0; i < bytes.length; i++)
+        if (bytes[i] !== output[i]) {
+            changedBytes++;
+            if (!allowedBytes.has(i))
+                throw Error('model_preparation_repair_nonposition_mutation');
+        }
+    return { bytes: output, manifest: { schemaVersion: 1, kind: 'explicit-bounded-vertex-repair-v1', parentContentHash: digest(bytes), contentHash: digest(output),
+            recipeHash: digest(canonicalModelAdaptation(plan)), recipe: plan, sourceDiagonal: diagonal, maximumDisplacement: Math.max(...records.map(r => r.worldDistance)),
+            vertexRepairs: records, affectedSourceTriangles: [...affected].sort((a, b) => a - b), changedBytes,
+            preserved: { originalSource: true, indices: true, normalAttribute: true, textureCoordinates: true, embeddedImages: true, allNonPositionBytes: true },
+            geometryChecks: 'pending-strict-source-and-shell-validation', visualAcceptance: false, modelAcceptance: false } };
+}

package/dist/workspace-runtime/codex/app-server.js

@@ -577,12 +577,22 @@ export function createCodexAppServerAdapter(options) {
                     }
             }
             if (method === 'turn/completed') {
-                const turnId = asRecord(payload.turn).id;
+                const turn = asRecord(payload.turn);
+                const turnId = turn.id;
                 if (typeof payload.threadId !== 'string' && typeof turnId === 'string') {
                     const matches = [...threads].filter(([, thread]) => thread.lastTurnId === turnId);
                     if (matches.length === 1)
                         payload.threadId = matches[0][0];
                 }
+                const rootThreadId = typeof payload.threadId === 'string' ? owningThreadId(payload.threadId) : undefined;
+                const rootThread = rootThreadId ? threads.get(rootThreadId) : undefined;
+                if (turn.status === 'failed' && rootThread?.cwd) {
+                    const admissionReason = options.modelBroker?.consumeAdmissionReason(rootThread.cwd, rootThread.sessionId);
+                    if (admissionReason) {
+                        const error = asRecord(turn.error);
+                        payload.turn = { ...turn, error: { ...error, admissionReason } };
+                    }
+                }
                 const thread = typeof payload.threadId === 'string' ? threads.get(payload.threadId) : undefined;
                 const currentTurn = thread && typeof turnId === 'string' && thread.lastTurnId === turnId;
                 if (currentTurn) {

package/dist/workspace-runtime/codex/delivery-tools.js

@@ -13,7 +13,7 @@ export const WORKSPACE_DELIVERY_TOOLS = [
                     type: 'array',
                     items: { type: 'string', enum: DELIVERY_CHANNELS },
                     minItems: 1,
-                    maxItems: 8,
+                    maxItems: DELIVERY_CHANNELS.length,
                     uniqueItems: true,
                 },
             },
@@ -76,7 +76,7 @@ export class WorkspaceDeliveryTools {
             return;
         }
         const channels = input.channels === undefined ? ['playcraft'] : input.channels;
-        if (!Array.isArray(channels) || channels.length < 1 || channels.length > 8
+        if (!Array.isArray(channels) || channels.length < 1 || channels.length > DELIVERY_CHANNELS.length
             || channels.some(channel => !DELIVERY_CHANNELS.includes(channel))
             || new Set(channels).size !== channels.length) {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');

package/dist/workspace-runtime/codex/model-broker.js

@@ -106,6 +106,7 @@ export class WorkspaceModelBroker {
                         }
                     }
                 }
+                route.lastAdmissionReason = undefined;
                 route.selected = { entry, model: credential.model,
                     ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, readOnly, refsBlocked,
                             ...(originCwd ? { originCwd } : {}) } } : {}) };
@@ -278,8 +279,17 @@ export class WorkspaceModelBroker {
                 });
                 if (upstream.status === 401 || upstream.status === 403)
                     entry.credential = undefined;
+                const admissionReason = upstream.headers.get('x-model-admission-reason')?.trim();
+                const retryAfter = upstream.headers.get('retry-after')?.trim();
+                if (upstream.status < 400)
+                    route.lastAdmissionReason = undefined;
+                else if (admissionReason)
+                    route.lastAdmissionReason = admissionReason;
                 response.writeHead(upstream.status, {
-                    'content-type': upstream.headers.get('content-type') ?? 'application/json', 'cache-control': 'no-store',
+                    'content-type': upstream.headers.get('content-type') ?? 'application/json',
+                    'cache-control': 'no-store',
+                    ...(admissionReason ? { 'x-model-admission-reason': admissionReason } : {}),
+                    ...(retryAfter ? { 'retry-after': retryAfter } : {}),
                 });
                 if (upstream.body)
                     await pipeline(Readable.fromWeb(upstream.body), response);
@@ -316,6 +326,14 @@ export class WorkspaceModelBroker {
             for (const request of this.sessionRequests.get(route) ?? [])
                 request.abort();
     }
+    consumeAdmissionReason(cwd, sessionId) {
+        const routeKey = `${/^(basic|remix-)/.test(basename(cwd)) ? basename(dirname(cwd)) : basename(cwd)}/${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}`;
+        const route = this.routes.get(routeKey);
+        const reason = route?.lastAdmissionReason;
+        if (route)
+            route.lastAdmissionReason = undefined;
+        return reason;
+    }
     async close() {
         const server = this.server;
         this.server = undefined;