@playcraft/cli 0.1.63 → 0.1.65

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/batch/deliver.js

@@ -9,10 +9,10 @@ import { workspaceRoot } from '../workspaces/registry.js';
 import { processHasExited, runProcessGroup, stopProcessGroup } from './processes.js';
 import { stopMemberWriters } from './writer-proof.js';
 import { memberStatus, readMember, readStopMarker, serializeRun, writeMember, } from './records.js';
-/** Base build writes dist/index.html. Channel packaging stays on export playable (`--mode full`). */
+/** Base build writes dist/index.html. Channel packaging is done by platform export. */
 function buildCommand() {
     return (process.env.PLAYCRAFT_BATCH_BUILD_COMMAND
-        ?? 'umask 002 && CI=1 playcraft build --mode base --output dist .');
+        ?? 'umask 002 && CI=1 playcraft build --base --output dist .');
 }
 /**
  * The batch build runs as the runtime identity while the agent wrote the tree as the development

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

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { DELIVERY_CHANNELS, } from '@playcraft/common/cloud-workspace/runtime';
+import { DELIVERY_CHANNELS, deliveryExportOptionsSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { rejectTool, toolContent } from './tool-response.js';
 export const WORKSPACE_DELIVERY_TOOLS = [
     {
         type: 'function',
         name: 'playcraft_build_delivery',
-        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit. Each channel uses the same fixed HTML or ZIP choice as the Export button for that channel and the project engine. Other options reuse the channel\'s latest export on this branch, or the defaults when it has none. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
+        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit. Each channel uses the same fixed HTML or ZIP choice as the Export button for that channel and the project engine. Build options given in `options` apply to every requested channel and replace that setting from the channel\'s latest export on this branch; options not given reuse that export, or the defaults when it has none. Store links not given come from the project\'s remembered export links, then from the channel\'s latest export. A later export without `options` keeps the settings this one used. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -13,9 +13,35 @@ export const WORKSPACE_DELIVERY_TOOLS = [
                     type: 'array',
                     items: { type: 'string', enum: DELIVERY_CHANNELS },
                     minItems: 1,
-                    maxItems: 8,
+                    maxItems: DELIVERY_CHANNELS.length,
                     uniqueItems: true,
                 },
+                options: {
+                    type: 'object',
+                    description: 'Optional. Set only the options to change; each one left out keeps its current setting. Each option affects the size and quality of the channel packages.',
+                    properties: {
+                        compressImages: { type: 'boolean', description: 'Lossy palette compression (pngquant) of PNG images.' },
+                        imageQuality: { type: 'integer', minimum: 40, maximum: 95, description: 'Quality of lossy image compression, 40 to 95; lower is smaller and blurrier. Used with compressImages.' },
+                        convertToWebP: { type: 'boolean', description: 'Convert PNG and JPG images to WebP, usually much smaller; on by default.' },
+                        compressModels: { type: 'boolean', description: 'Compress 3D model geometry.' },
+                        modelCompression: { type: 'string', enum: ['draco', 'meshopt'], description: 'Model compression method: draco is widely supported, meshopt compresses further. Used with compressModels.' },
+                        jsMinify: { type: 'boolean', description: 'Minify and obfuscate JavaScript; on by default.' },
+                        cssMinify: { type: 'boolean', description: 'Minify CSS; on by default.' },
+                        selectedScenes: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 100, uniqueItems: true, description: 'Package just these scene names; scenes left out are not in the package.' },
+                        esmMode: { type: 'string', enum: ['auto', 'enabled', 'disabled'], description: 'How ES modules are bundled; auto detects them.' },
+                        storeUrls: {
+                            type: 'object',
+                            description: 'App store links the call-to-action opens. A link given is used for that store; a store not given keeps the project\'s remembered link, or the channel\'s latest export link.',
+                            properties: {
+                                ios: { type: 'string', format: 'uri', description: 'iOS App Store URL (http or https).' },
+                                android: { type: 'string', format: 'uri', description: 'Google Play URL (http or https).' },
+                            },
+                            minProperties: 1,
+                            additionalProperties: false,
+                        },
+                    },
+                    additionalProperties: false,
+                },
             },
             additionalProperties: false,
         },
@@ -70,18 +96,24 @@ export class WorkspaceDeliveryTools {
             await this.reject(client, requestId, 'permission_denied');
             return;
         }
-        const unknown = Object.keys(input).filter(key => key !== 'channels');
+        const unknown = Object.keys(input).filter(key => key !== 'channels' && key !== 'options');
         if (unknown.length) {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
             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');
             return;
         }
+        const options = input.options === undefined ? { success: true, data: undefined }
+            : deliveryExportOptionsSchema.safeParse(input.options);
+        if (!options.success || (options.data?.selectedScenes && new Set(options.data.selectedScenes).size !== options.data.selectedScenes.length)) {
+            await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
+            return;
+        }
         try {
             const result = await this.handlers.build({
                 ...context,
@@ -89,6 +121,7 @@ export class WorkspaceDeliveryTools {
                     ? payload.callId
                     : randomUUID(),
                 channels: channels,
+                ...(options.data ? { options: options.data } : {}),
             });
             await this.respond(client, requestId, result);
         }

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;

package/dist/workspace-runtime/previews/publish.js

@@ -12,7 +12,7 @@ import { revisionScope, workspaceRoot } from '../workspaces/registry.js';
 import { classifyPreviewOutput, findExternalLocalReferences } from './single-file.js';
 import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from './finalize.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
-import { isolateWorkspaceForBuild } from '../workspaces/delivery-build.js';
+import { isolateWorkspaceForBuild } from '../workspaces/build-isolation.js';
 import { openScratchToDevelopment } from '../workspaces/directory-access.js';
 import { injectPreviewDiagnostics } from './diagnostics.js';
 import { OperationLogStore } from '../workspaces/operation-log.js';
@@ -27,7 +27,7 @@ const BUILDER_TEMP_FOLDER = '.playcraft-temp';
  * The generic single-file build. `--mode full` keeps the builder from asking which stages to run.
  * Group-writable output lets the control user, a member of the development group, remove it.
  */
-const BUILD_COMMAND = 'umask 002 && PLAYCRAFT_BUILD_ISOLATED=1 playcraft build --mode full --platform playcraft --format html';
+const BUILD_COMMAND = 'umask 002 && PLAYCRAFT_BUILD_ISOLATED=1 playcraft build';
 class PreviewFailure extends Error {
     code;
     constructor(code) {

package/dist/workspace-runtime/serve.js

@@ -36,6 +36,7 @@ import { platformExportTarget, readPlatformExport, startPlatformExport } from '.
 import { scheduledTaskProposalHandler } from './workspaces/scheduled-task-proposals.js';
 import { proceduralSkillHandler } from './workspaces/procedural-3d/host.js';
 import { recoverModelPreviewOperations } from './workspaces/procedural-3d/model-preview-recovery.js';
+import { recoverModelPreparationOperations, stopModelPreparations } from './workspaces/model-preparation.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -84,6 +85,9 @@ export async function startWorkspaceRuntime(config, options = {}) {
             runtimeEpoch: config.runtimeEpoch, previousRuntimeEpoch: previousEpoch,
             ...(config.workspaceMode === 'multi' && process.env.PLAYCRAFT_LAUNCHER_SOCKET
                 ? { launcherSocket: process.env.PLAYCRAFT_LAUNCHER_SOCKET } : {}) });
+        await recoverModelPreparationOperations(state, { identityMatches: previousIdentityMatches,
+            runtimeEpoch: config.runtimeEpoch, previousRuntimeEpoch: previousEpoch,
+            ...(config.workspaceMode === 'multi' && process.env.PLAYCRAFT_LAUNCHER_SOCKET ? { launcherSocket: process.env.PLAYCRAFT_LAUNCHER_SOCKET } : {}) });
         const recoveredChanges = [];
         const recoveredWrites = [];
         const recoverLibraryImports = async (root) => {
@@ -316,6 +320,7 @@ export async function startWorkspaceRuntime(config, options = {}) {
             async close() {
                 const serverClosed = closeServer(server);
                 await stopParameterVerifications(state);
+                await stopModelPreparations(state);
                 await closeCliCredentials(state);
                 await gitCredentials?.close();
                 try {

package/dist/workspace-runtime/server/directory-access.js

@@ -8,7 +8,7 @@ const instances = new WeakMap();
 const executing = new WeakMap();
 const freezing = new WeakMap();
 const TERMINAL = new Set(['completed', 'failed', 'interrupted']);
-const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'delivery.build', 'model.preview', 'directory.create',
+const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'model.preview', 'model.prepare', 'directory.create',
     'directory.rename', 'directory.delete', 'workspace.references.import', 'skills.update', 'parameter.verify',
     'checkpoint.create', 'checkpoint.restore']);
 export function managedDirectoryScope(state, value) {