@playcraft/cli 0.1.63 → 0.1.65

package/dist/model-adaptation/node-inspection.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import sharp from 'sharp';
+import { canonicalModelAdaptation, createModelAdaptationCore, inspectModelAdaptationSource, readModelSourceDocument, workspaceModelAdaptationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+const require = createRequire(import.meta.url);
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+let serialized = Promise.resolve();
+function assert(condition, code) { if (!condition)
+    throw Error(code); }
+/** Actual engine loading and decoded pixels, with no renderer, browser or project code execution. */
+export function inspectRigidModel(input) {
+    const result = serialized.then(() => inspect(input));
+    serialized = result.catch(() => undefined);
+    return result;
+}
+async function inspect(input) {
+    input.signal?.throwIfAborted();
+    const parsed = readModelSourceDocument(input.bytes), document = parsed.document;
+    const { binary, extraChunks } = parsed;
+    assert(binary && !extraChunks?.length && !(document.buffers ?? []).some((value) => value.uri)
+        && !(document.images ?? []).some((value) => value.uri), 'model_prepare_self_contained_glb_required');
+    assert(!(document.extensionsRequired ?? []).some((name) => ['KHR_draco_mesh_compression', 'KHR_texture_basisu', 'EXT_meshopt_compression'].includes(name)), 'model_prepare_decoder_not_configured');
+    assert((document.images ?? []).length <= 64, 'model_prepare_image_bound');
+    const threeEntry = require.resolve('three'), threeRoot = dirname(dirname(threeEntry));
+    const threePackage = JSON.parse(await readFile(join(threeRoot, 'package.json'), 'utf8'));
+    assert(threePackage.version === '0.183.2', 'model_prepare_loader_version_mismatch');
+    // Variable module URLs avoid inventing a second public engine type contract.
+    const THREE = await import(pathToFileURL(join(threeRoot, 'build/three.module.js')).href);
+    const loaderPath = require.resolve('three/examples/jsm/loaders/GLTFLoader.js');
+    const { GLTFLoader } = await import(pathToFileURL(loaderPath).href);
+    const descriptors = new Map(['self', 'ProgressEvent', 'createImageBitmap'].map(name => [name, Object.getOwnPropertyDescriptor(globalThis, name)]));
+    const pending = new Set(), decoded = [];
+    let loaded, factory;
+    const errors = [];
+    let decodedBytes = 0;
+    try {
+        Object.defineProperty(globalThis, 'self', { configurable: true, value: globalThis });
+        Object.defineProperty(globalThis, 'ProgressEvent', { configurable: true, value: class extends Event {
+                lengthComputable;
+                loaded;
+                total;
+                constructor(type, init = {}) { super(type); this.lengthComputable = Boolean(init.lengthComputable); this.loaded = init.loaded ?? 0; this.total = init.total ?? 0; }
+            } });
+        Object.defineProperty(globalThis, 'createImageBitmap', { configurable: true, value: (blob, options = {}) => {
+                const task = (async () => {
+                    assert(blob instanceof Blob && blob.size <= 32 * 1024 * 1024, 'model_prepare_image_bound');
+                    const bytes = Buffer.from(await blob.arrayBuffer());
+                    let decoder = sharp(bytes, { limitInputPixels: 16_777_216 });
+                    if (options.imageOrientation === 'flipY')
+                        decoder = decoder.flip();
+                    const metadata = await decoder.metadata(), allocation = (metadata.width ?? 0) * (metadata.height ?? 0) * 4;
+                    assert(allocation > 0 && decodedBytes + allocation <= 128 * 1024 * 1024, 'model_prepare_decoded_image_budget');
+                    decodedBytes += allocation;
+                    const raw = await decoder.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+                    assert(raw.info.channels === 4 && raw.data.length === raw.info.width * raw.info.height * 4, 'model_prepare_image_decode_failed');
+                    const image = { width: raw.info.width, height: raw.info.height, data: new Uint8ClampedArray(raw.data), close() { this.data = null; } };
+                    decoded.push({ image, encodedHash: hash(bytes), rgbaHash: hash(raw.data), width: image.width, height: image.height });
+                    return image;
+                })();
+                pending.add(task);
+                void task.then(() => pending.delete(task), () => pending.delete(task));
+                return task;
+            } });
+        const manager = new THREE.LoadingManager();
+        manager.onError = () => errors.push('embedded-resource-load-failed');
+        loaded = await new GLTFLoader(manager).parseAsync(input.bytes.buffer.slice(input.bytes.byteOffset, input.bytes.byteOffset + input.bytes.byteLength), '');
+        await Promise.all([...pending]);
+        input.signal?.throwIfAborted();
+        assert(!errors.length, 'model_prepare_resource_load_failed');
+        const inventory = await inspectModelAdaptationSource({ source: loaded.scene, animationCount: loaded.animations.length, digestBytes: hash, signal: input.signal });
+        assert(!inventory.unsupported.length, 'model_prepare_rigid_source_required');
+        let triangles = 0;
+        loaded.scene.traverse((node) => {
+            if (node.isMesh && node.geometry) {
+                const count = node.geometry.index?.count ?? node.geometry.getAttribute('position')?.count ?? 0;
+                assert(Number.isSafeInteger(count) && count % 3 === 0, 'model_prepare_triangles_required');
+                triangles += count / 3;
+            }
+        });
+        assert(triangles > 0, 'model_prepare_empty_model');
+        let plan = workspaceModelAdaptationSchema.parse(input.adaptation ? { ...input.adaptation, source: input.source } : { schemaVersion: 1, source: input.source });
+        if (input.split) {
+            const ref = (role) => {
+                const expected = input.split.output.nodes.filter(node => node.role === role);
+                assert(expected.length === 1, 'model_prepare_split_roles_invalid');
+                const matches = inventory.nodes.filter(node => node.sourceNodeId === expected[0].sourceNodeId && node.name === expected[0].name);
+                assert(matches.length === 1 && matches[0].geometryHash, 'model_prepare_split_node_identity_mismatch');
+                return { sourceNodeId: matches[0].sourceNodeId, geometryHash: matches[0].geometryHash };
+            };
+            plan = workspaceModelAdaptationSchema.parse({ ...plan, hinges: [{ id: 'primary', movingNodeRef: ref('lid'), bodyNodeRefs: [ref('body')],
+                        pivot: input.split.hinge.pivot, axis: input.split.hinge.axis, openAngleDegrees: input.split.hinge.openAngleDegrees }] });
+        }
+        assert(input.requiredCapability !== 'rigid-hinge' || plan.hinges.length > 0, 'model_prepare_needs_part_mapping');
+        const points = (node) => {
+            const result = [];
+            node.updateMatrixWorld(true);
+            node.traverse((item) => {
+                const position = item.isMesh && item.geometry?.getAttribute('position');
+                if (position)
+                    for (let index = 0; index < position.count; index++) {
+                        if (result.length >= 4_000_000)
+                            throw Error('model_prepare_geometry_bound');
+                        result.push(new THREE.Vector3().fromBufferAttribute(position, index).applyMatrix4(item.matrixWorld).toArray());
+                    }
+            });
+            return result;
+        };
+        const distance = (before, after) => {
+            assert(before.length === after.length, 'model_prepare_geometry_changed');
+            return before.reduce((maximum, point, index) => Math.max(maximum, Math.hypot(...point.map((value, axis) => value - after[index][axis]))), 0);
+        };
+        const original = points(loaded.scene);
+        factory = await createModelAdaptationCore({ THREE, source: loaded.scene, sourceIdentity: input.source, plan,
+            animationCount: loaded.animations.length, digestBytes: hash, signal: input.signal });
+        const instance = factory.create(), samples = [];
+        try {
+            for (const declared of plan.hinges) {
+                const hinge = instance.getHinge(declared.id);
+                const body = hinge.body.map(node => points(node)), moving = points(hinge.moving);
+                for (const fraction of [.25, .5, .75, 1]) {
+                    input.signal?.throwIfAborted();
+                    const angleDegrees = declared.openAngleDegrees * fraction;
+                    instance.setHinge(declared.id, angleDegrees);
+                    const bodyDisplacement = Math.max(...hinge.body.map((node, index) => distance(body[index], points(node))));
+                    const movingDisplacement = distance(moving, points(hinge.moving));
+                    assert(bodyDisplacement <= 1e-8 && movingDisplacement > 1e-8, 'model_prepare_hinge_motion_failed');
+                    samples.push({ hingeId: declared.id, angleDegrees, bodyDisplacement, movingDisplacement });
+                }
+                instance.setHinge(declared.id, 0);
+                assert(distance(moving, points(hinge.moving)) <= 1e-8, 'model_prepare_closed_recovery_failed');
+            }
+            assert(distance(original, points(loaded.scene)) === 0, 'model_prepare_source_mutated');
+        }
+        finally {
+            instance.dispose();
+        }
+        const dependencies = await Promise.all([['three', join(threeRoot, 'build/three.module.js')], ['three-core', join(threeRoot, 'build/three.core.js')], ['loader', loaderPath]]
+            .map(async ([name, path]) => ({ name: name, contentHash: hash(await readFile(path)) })));
+        return { schemaVersion: 1, kind: 'actual-engine-geometry-inspection', source: input.source, plan, inventory, samples, triangles,
+            decodedTextures: decoded.map(({ image: _image, ...value }) => value),
+            tool: { threeVersion: threePackage.version, sharpVersions: sharp.versions, nodeVersion: process.versions.node, dependencies,
+                dependencyHash: hash(canonicalModelAdaptation(dependencies)) },
+            rendered: false, browserStarted: false, modelAcceptance: false };
+    }
+    finally {
+        await Promise.allSettled([...pending]);
+        factory?.release();
+        const disposed = new Set();
+        loaded?.scene?.traverse((node) => {
+            for (const item of [node.geometry, ...(Array.isArray(node.material) ? node.material : node.material ? [node.material] : [])]) {
+                if (!item || disposed.has(item))
+                    continue;
+                disposed.add(item);
+                for (const value of Object.values(item))
+                    if (value?.isTexture && !disposed.has(value)) {
+                        disposed.add(value);
+                        value.dispose();
+                    }
+                item.dispose();
+            }
+        });
+        for (const entry of decoded)
+            entry.image.close();
+        for (const [name, descriptor] of descriptors)
+            if (descriptor)
+                Object.defineProperty(globalThis, name, descriptor);
+            else
+                delete globalThis[name];
+    }
+}

package/dist/model-adaptation/project-template.js

@@ -0,0 +1,194 @@
+export const modelProjectHtml = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title></title></head><body><main><h1 id="model-title"></h1><p id="status" role="status"></p><div id="stage"></div><section id="controls"></section><p id="model-notice"></p></main><script type="module" src="/src/main.js"></script></body></html>\n`;
+export const modelProjectStrings = { en: { title: 'Adapted model', loading: 'Loading model…', ready: 'Ready', open: 'Open ', close: 'Close ',
+        invalidParameter: 'Invalid parameter', staticModel: 'Static model; no opening capability is declared.',
+        notice: 'Temporary preview controls. Save production values in the workspace parameter panel, then rebuild.', parameterLabels: { scale: 'Model scale', unitScale: 'Unit scale' } },
+    zh: { title: '已有模型适配', loading: '正在加载模型…', ready: '已就绪', open: '打开 ', close: '关闭 ', invalidParameter: '参数无效',
+        staticModel: '静态模型，未声明开合能力。', notice: '这里的调整仅用于当前预览；生产默认值请在工作区参数面板保存后重新构建。', parameterLabels: { scale: '模型缩放', unitScale: '单位比例' } } };
+export const modelProjectAdapter = String.raw `import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { createModelAdaptationCore } from './runtime/model-adaptation-core.js';
+const digestBytes = bytes => bytesToHex(sha256(bytes));
+function disposeSource(scene) {
+  const resources = new Set(), images = new Set();
+  scene.traverse(node => { if (node.geometry) resources.add(node.geometry);
+    for (const material of [node.material].flat().filter(Boolean)) { resources.add(material);
+      for (const value of Object.values(material)) if (value?.isTexture) { resources.add(value); if (value.image?.close) images.add(value.image); } }
+  });
+  for (const resource of resources) resource.dispose(); for (const image of images) image.close();
+}
+export function resolvePackedModelBytes(evidence) {
+  const alias = evidence.packedModelField;
+  if (alias !== undefined && (alias !== 'modelBase64' || Object.hasOwn(evidence, 'packedModelBase64') ||
+    evidence.source?.contentHash !== evidence.packedHash || evidence.binding?.sourceHash !== evidence.packedHash)) throw Error('model_packed_alias_invalid');
+  const encoded = alias === undefined ? evidence.packedModelBase64 : evidence.modelBase64;
+  if (typeof encoded !== 'string' || encoded.length % 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw Error('model_packed_encoding_invalid');
+  const bytes = Uint8Array.from(atob(encoded), char => char.charCodeAt(0));
+  if (digestBytes(bytes) !== evidence.packedHash) throw Error('model_packed_bytes_changed');
+  return bytes;
+}
+export async function loadAdaptedModel(evidence, { signal } = {}) {
+  signal?.throwIfAborted(); const plan = JSON.parse(evidence.configRaw);
+  if (evidence.loaderRevision && THREE.REVISION !== evidence.loaderRevision) throw Error('model_loader_version_changed');
+  const bytes = resolvePackedModelBytes(evidence);
+  const gltf = await new GLTFLoader().parseAsync(bytes.buffer, '');
+  let factory, released = false;
+  const release = () => { if (released) return; released = true; factory?.release(); disposeSource(gltf.scene); };
+  try {
+    signal?.throwIfAborted();
+    factory = await createModelAdaptationCore({ THREE, source: gltf.scene, sourceIdentity: evidence.source,
+      plan, digestBytes, animationCount: gltf.animations.length, signal });
+    signal?.throwIfAborted();
+    return Object.freeze({ factory, plan, THREE, release });
+  } catch (error) { release(); throw error; }
+}
+`;
+export const modelProjectMain = String.raw `import { loadAdaptedModel } from './adapter.js';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import strings from './strings.json';
+import './style.css';
+const evidence = JSON.parse(document.getElementById('playcraft-source-evidence').textContent);
+const stage = document.getElementById('stage'), status = document.getElementById('status'), controlsArea = document.getElementById('controls');
+const locale = navigator.language.startsWith('zh') ? 'zh' : 'en', text = strings[locale]; document.documentElement.lang = locale;
+document.title = text.title; document.getElementById('model-title').textContent = text.title; document.getElementById('model-notice').textContent = text.notice; status.textContent = text.loading;
+const abort = new AbortController(); let stopped = false, loaded, renderer, orbit, instance, observer, renderFailed = false;
+let resolveReady, rejectReady; const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; }); ready.catch(() => {});
+const release = () => { if (stopped) return; stopped = true; abort.abort(); observer?.disconnect(); orbit?.dispose(); loaded?.release(); renderer?.dispose(); };
+const fail = error => { renderFailed = true; rejectReady(error); status.textContent = String(error.message); console.error('model_render_failed', error); parent.postMessage({ type: 'playcraft:game-error' }, '*'); release(); };
+addEventListener('pagehide', release, { once: true });
+try {
+  loaded = await loadAdaptedModel(evidence, { signal: abort.signal });
+  if (stopped) { loaded.release(); throw Error('model_closed'); }
+  const { THREE, factory, plan } = loaded, opened = new Set(), probes = new WeakMap();
+  const defaults = { scale: plan.transform.scale, unitScale: plan.normalization.unitScale };
+  for (const hinge of plan.hinges) defaults['hinge:' + hinge.id] = hinge.openAngleDegrees;
+  const materialKey = (field, value) => field + ':' + value.nodeRef.sourceNodeId + ':' + value.materialIndex;
+  for (const override of plan.materialOverrides) for (const key of ['tint', 'roughness', 'metalness']) if (override[key] !== undefined) defaults[materialKey(key, override)] = override[key];
+  let parameters = { ...defaults };
+  const apply = (target, values, open = opened) => {
+    target.setRootTransform({ ...plan.transform, scale: values.scale }); target.setNormalization({ ...plan.normalization, unitScale: values.unitScale });
+    for (const override of plan.materialOverrides) { const current = { ...override };
+      for (const key of ['tint', 'roughness', 'metalness']) if (override[key] !== undefined) current[key] = values[materialKey(key, override)]; target.setMaterialOverride(current); }
+    for (const hinge of plan.hinges) target.setHinge(hinge.id, open.has(hinge.id) ? values['hinge:' + hinge.id] : 0);
+  };
+  instance = factory.create(); const model = instance.root, scene = new THREE.Scene(); scene.background = new THREE.Color('#dbe3e8'); scene.add(model);
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x697788, 2)); const light = new THREE.DirectionalLight(0xffffff, 3); light.position.set(3, 5, 4); scene.add(light);
+  instance.setRootTransform({ ...plan.transform, scale: 1 });
+  const framing = new THREE.Box3().setFromObject(model);
+  for (const hinge of plan.hinges) {
+    for (const fraction of [.25, .5, .75, 1]) { instance.setHinge(hinge.id, hinge.openAngleDegrees * fraction); framing.union(new THREE.Box3().setFromObject(model)); }
+    instance.setHinge(hinge.id, 0);
+  }
+  const sphere = framing.getBoundingSphere(new THREE.Sphere()); apply(instance, parameters);
+  if (!Number.isFinite(sphere.radius) || sphere.radius <= 0) throw Error('model_empty_bounds');
+  const camera = new THREE.PerspectiveCamera(42, 1, Math.max(sphere.radius / 1000, .000001), sphere.radius * 1000);
+  camera.position.copy(sphere.center).add(new THREE.Vector3(3, 2, 5).normalize().multiplyScalar(sphere.radius * 4.5)); camera.lookAt(sphere.center);
+  renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true }); renderer.debug.checkShaderErrors = true;
+  renderer.debug.onShaderError = () => { renderFailed = true; }; stage.append(renderer.domElement);
+  renderer.domElement.addEventListener('webglcontextlost', event => { event.preventDefault(); fail(Error('model_context_lost')); });
+  orbit = new OrbitControls(camera, renderer.domElement); orbit.target.copy(sphere.center); orbit.update();
+  let width = 0, height = 0;
+  const resize = () => { const box = stage.getBoundingClientRect(); if (box.width > 0 && box.height > 0 && (box.width !== width || box.height !== height)) {
+    width = box.width; height = box.height; renderer.setSize(width, height); camera.aspect = width / height; camera.updateProjectionMatrix(); } };
+  observer = new ResizeObserver(resize); observer.observe(stage); resize();
+  for (const hinge of plan.hinges) {
+    const button = document.createElement('button'); button.type = 'button'; button.textContent = text.open + hinge.id; button.dataset.hingeId = hinge.id;
+    button.addEventListener('click', () => { if (opened.has(hinge.id)) opened.delete(hinge.id); else opened.add(hinge.id); apply(instance, parameters); button.textContent = (opened.has(hinge.id) ? text.close : text.open) + hinge.id; }); controlsArea.append(button);
+  }
+  for (const [name, value] of Object.entries(defaults)) {
+    const label = document.createElement('label'), input = document.createElement('input'); label.textContent = (text.parameterLabels[name] ?? name) + ' '; input.dataset.modelParameter = name;
+    input.type = typeof value === 'number' ? 'number' : 'text'; if (input.type === 'number') input.step = 'any'; input.value = String(value);
+    input.addEventListener('input', () => { const next = { ...parameters, [name]: typeof value === 'number' ? Number(input.value) : input.value };
+      try { apply(instance, next); parameters = next; input.setCustomValidity(''); } catch { apply(instance, parameters); input.setCustomValidity(text.invalidParameter); } }); label.append(input); controlsArea.append(label);
+  }
+  if (!plan.hinges.length) status.textContent = text.staticModel;
+  const render = () => { if (stopped || renderFailed) throw Error('model_render_stopped'); resize(); renderer.render(scene, camera); const gl = renderer.getContext();
+    if (renderFailed || gl.isContextLost() || gl.getError() !== gl.NO_ERROR) throw Error('model_render_failed'); };
+  Object.defineProperty(window, '__PLAYCRAFT_ACCEPTANCE__', { value: Object.freeze({ schemaVersion: 1, evidenceKind: evidence.fixtureOnly ? 'fixture' : 'real-asset', binding: evidence.binding, ready,
+    THREE, renderer, scene, camera, model, sourceInspection: factory.inspection, objectsBySourceNodeId: instance.objectsBySourceNodeId, getHinge: instance.getHinge,
+    get parameters() { return Object.freeze({ ...parameters }); }, get defaultParameters() { return Object.freeze({ ...defaults }); },
+    persistence: Object.freeze({ configHash: evidence.configHash }), render,
+    create: values => { const probe = factory.create(); try { apply(probe, { ...defaults, ...values }); probes.set(probe.root, probe); return probe.root; } catch (error) { probe.dispose(); throw error; } },
+    dispose: root => { const probe = probes.get(root); if (probe) { probe.dispose(); probes.delete(root); } } }) });
+  let first = true; const draw = () => { if (stopped) return; try { render(); const box = renderer.domElement.getBoundingClientRect(), gl = renderer.getContext();
+    if (first && box.width > 0 && box.height > 0 && gl.drawingBufferWidth > 0 && gl.drawingBufferHeight > 0 && renderer.info.render.calls > 0) { first = false; resolveReady(); if (plan.hinges.length) status.textContent = text.ready; parent.postMessage({ type: 'playcraft:game-ready' }, '*'); }
+    requestAnimationFrame(draw);
+  } catch (error) { fail(error); } }; requestAnimationFrame(draw);
+} catch (error) { if (!stopped) fail(error); }
+`;
+export const modelProjectStyle = `body{margin:0;background:#eee9e0;color:#202d38;font:16px system-ui}main{max-width:1120px;margin:auto;padding:24px}#stage{height:62vh;min-height:240px;border:1px solid #c2ccd1;border-radius:8px;overflow:hidden}canvas{display:block;width:100%;height:100%}#controls{display:flex;gap:12px;flex-wrap:wrap;margin-top:16px}button,input{padding:10px 18px;border:1px solid currentColor;border-radius:4px;background:#f8f4ec;color:inherit}button{cursor:pointer}label{display:inline-flex;align-items:center;gap:8px}input{width:110px}
+`;
+export const modelProjectPrepare = String.raw `import { createHash } from 'node:crypto';
+import { readFile, readdir, lstat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const canonical = value => Array.isArray(value) ? '[' + value.map(canonical).join(',') + ']' : value && typeof value === 'object'
+  ? '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}' : JSON.stringify(value);
+export async function prepareModelBuild(root) {
+  const configRaw = await readFile(join(root, '.playcraft/model-adaptation.json'), 'utf8'), plan = JSON.parse(configRaw);
+  const meta = JSON.parse(await readFile(join(root, '.playcraft/model-adaptation-lineage.json'), 'utf8'));
+  if (canonical(plan.source) !== canonical(meta.derivedSource)) throw Error('model_source_identity_changed');
+  const sourceFiles = [], evidence = { source: plan.source, configRaw, sourceFiles, fixtureOnly: meta.fixtureOnly, loaderRevision: meta.loaderRevision }; let primaryBytes;
+  for (let index = 0; index < plan.source.files.length; index++) {
+    const file = plan.source.files[index], bytes = await readFile(join(root, file.path)); if (hash(bytes) !== file.contentHash) throw Error('model_source_bytes_changed');
+    const field = file.path === plan.source.path ? 'modelBase64' : 'sourceFile' + index; evidence[field] = bytes.toString('base64'); sourceFiles.push({ ...file, field });
+    if (file.path === plan.source.path) primaryBytes = bytes;
+  }
+  const packed = await readFile(join(root, 'src/assets/packed-model.glb')); if (hash(packed) !== meta.packedHash) throw Error('model_packed_bytes_changed');
+  const core = await readFile(join(root, 'src/runtime/model-adaptation-core.js')); if (hash(core) !== meta.coreHash) throw Error('model_core_changed');
+  const inputs = [];
+  if (meta.buildBindingVersion === 2) {
+    const declaration = JSON.parse(await readFile(join(root, '.playcraft/model-build-inputs.json'), 'utf8'));
+    const model = declaration.models?.[0];
+    if (declaration.schemaVersion !== 1 || !Array.isArray(declaration.models) || declaration.models.length !== 1 ||
+      model?.source?.kind !== 'resource' || canonical(model.source) !== canonical(plan.source) || !Array.isArray(model.adaptationFiles)) throw Error('model_build_manifest_invalid');
+    const paths = new Map();
+    for (const file of [...model.source.files, ...model.adaptationFiles]) {
+      if (!file || typeof file.path !== 'string' || !file.path || file.path.length > 512 || /[\\\0:]/.test(file.path) || file.path.startsWith('/') ||
+        file.path.split('/').some(part => !part || part === '.' || part === '..') ||
+        file.contentHash !== undefined && !/^[a-f0-9]{64}$/.test(file.contentHash)) throw Error('model_build_manifest_invalid');
+      const previous = paths.get(file.path); if (previous?.contentHash && file.contentHash && previous.contentHash !== file.contentHash) throw Error('model_build_input_conflict');
+      paths.set(file.path, previous?.contentHash ? previous : file);
+    }
+    if (paths.size > 256) throw Error('model_build_input_limit');
+    const readInput = async path => {
+      let current = root; for (const [index, part] of path.split('/').entries()) {
+        current = join(current, part); const stat = await lstat(current);
+        if (stat.isSymbolicLink() || (index < path.split('/').length - 1 ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1 || stat.size > 64 * 1024 * 1024)) throw Error('model_input_not_regular');
+      }
+      return readFile(current);
+    };
+    for (const path of ['package.json','pnpm-lock.yaml','package-lock.json','yarn.lock']) {
+      try { const bytes = await readInput(path); if (!paths.has(path)) inputs.push({ path, contentHash: hash(bytes) }); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    for (const file of paths.values()) {
+      const contentHash = hash(await readInput(file.path)); if (file.contentHash && contentHash !== file.contentHash) throw Error('model_build_input_changed');
+      inputs.push({ path: file.path, contentHash });
+    }
+  } else if (meta.buildBindingVersion === undefined || meta.buildBindingVersion === 1) {
+    async function walk(directory) { for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name); if (entry.isDirectory()) await walk(path); else if (entry.isFile()) inputs.push({ path: relative(root, path).split('\\').join('/'), contentHash: hash(await readFile(path)) }); else throw Error('model_input_not_regular');
+    } }
+    await walk(join(root, 'src')); await walk(join(root, 'source')); await walk(join(root, 'scripts'));
+    for (const path of ['index.html','package.json','vite.config.mjs','.playcraft/workspace.json','.playcraft/model-adaptation.json','.playcraft/model-adaptation-lineage.json','package-lock.json','pnpm-lock.yaml']) {
+      try { inputs.push({ path, contentHash: hash(await readFile(join(root, path))) }); } catch (error) { if (error.code !== 'ENOENT' || !path.endsWith('lock.json') && path !== 'pnpm-lock.yaml') throw error; }
+    }
+  } else throw Error('model_build_binding_version_unsupported');
+  inputs.sort((a,b) => a.path.localeCompare(b.path, 'en'));
+  const binding = { sourceKind: 'external-model', candidateId: meta.candidateId, sourceHash: plan.source.contentHash,
+    adaptationHash: hash(await readFile(join(root, 'src/adapter.js'))), buildHash: hash(canonical(inputs)) };
+  const packedEvidence = primaryBytes && plan.source.contentHash === meta.packedHash && primaryBytes.equals(packed)
+    ? { packedModelField: 'modelBase64' } : { packedModelBase64: packed.toString('base64') };
+  return { ...evidence, binding, configHash: hash(configRaw), packedHash: meta.packedHash, ...packedEvidence };
+}
+`;
+export const modelProjectVite = String.raw `import { defineConfig } from 'vite';
+import { fileURLToPath } from 'node:url';
+import { prepareModelBuild } from './scripts/prepare-build.mjs';
+export default defineConfig({ base: './', plugins: [{ name: 'model-adaptation-frozen-inputs', async transformIndexHtml() {
+  const evidence = await prepareModelBuild(fileURLToPath(new URL('./', import.meta.url)));
+  return [{ tag: 'script', attrs: { id: 'playcraft-source-evidence', type: 'application/json' }, children: JSON.stringify(evidence).replace(/</g, '\\u003c'), injectTo: 'head' }];
+} }], build: { outDir: 'dist', emptyOutDir: true, assetsInlineLimit: Infinity, sourcemap: false } });
+`;

package/dist/model-adaptation/project.js

@@ -0,0 +1,76 @@
+import { lstat, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { canonicalModelAdaptation, workspaceModelAdaptationSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { inspectModelSourceFiles, modelSourceDigest } from './source.js';
+import { modelProjectAdapter, modelProjectHtml, modelProjectMain, modelProjectPrepare, modelProjectStrings, modelProjectStyle, modelProjectVite } from './project-template.js';
+export async function generateModelAdaptationProject(input) {
+    input.signal?.throwIfAborted();
+    const root = await realpath(resolve(input.projectRoot)), planPath = resolve(root, input.planPath), info = await lstat(planPath);
+    if (!info.isFile() || info.nlink !== 1 || await realpath(planPath) !== planPath || info.size > 1024 * 1024)
+        throw new Error('model_adaptation_plan_file_invalid');
+    const parentRaw = await readFile(planPath), parentPlan = workspaceModelAdaptationSchema.parse(JSON.parse(parentRaw.toString('utf8')));
+    const source = await inspectModelSourceFiles({ projectRoot: root, modelPath: parentPlan.source.path, signal: input.signal });
+    const identity = (value) => ({ ...value, files: [...value.files].sort((a, b) => a.path.localeCompare(b.path, 'en')) });
+    if (canonicalModelAdaptation(identity(source.source)) !== canonicalModelAdaptation(identity(parentPlan.source)))
+        throw new Error('model_adaptation_source_identity_mismatch');
+    if (source.metadata.unsupported.length)
+        throw new Error(`model_adaptation_rigid_source_required:${source.metadata.unsupported.join(',')}`);
+    const commonEntry = createRequire(import.meta.url).resolve('@playcraft/common/cloud-workspace/runtime');
+    const core = await readFile(join(dirname(commonEntry), 'model-adaptation-core.js')), coreHash = modelSourceDigest(core);
+    const coreMap = await readFile(join(dirname(commonEntry), 'model-adaptation-core.js.map'));
+    if (/^\s*import\s/m.test(core.toString('utf8')))
+        throw new Error('model_adaptation_core_must_be_self_contained');
+    const derivedSource = { ...parentPlan.source, path: `source/${parentPlan.source.path}`,
+        files: parentPlan.source.files.map(file => ({ ...file, path: `source/${file.path}` })) };
+    const plan = workspaceModelAdaptationSchema.parse({ ...parentPlan, source: derivedSource });
+    const candidateId = input.candidateId ?? `source-${parentPlan.source.contentHash.slice(0, 24)}`;
+    if (!/^[a-zA-Z0-9:_-]{1,128}$/.test(candidateId))
+        throw new Error('model_adaptation_candidate_id_invalid');
+    const outputRoot = resolve(input.outputRoot);
+    if (await realpath(dirname(outputRoot)) !== dirname(outputRoot))
+        throw new Error('model_adaptation_output_parent_must_be_canonical');
+    const json = (value) => JSON.stringify(value, null, 2) + '\n';
+    const files = {
+        'package.json': json({ name: 'playcraft-adapted-model-project', version: '0.0.0', private: true, type: 'module',
+            scripts: { dev: 'vite --host 0.0.0.0', build: 'vite build' }, dependencies: { three: '0.183.2', '@noble/hashes': '2.0.1' }, devDependencies: { vite: '7.1.3' } }),
+        'index.html': modelProjectHtml, 'vite.config.mjs': modelProjectVite, 'scripts/prepare-build.mjs': modelProjectPrepare,
+        'src/main.js': modelProjectMain, 'src/adapter.js': modelProjectAdapter, 'src/style.css': modelProjectStyle, 'src/strings.json': json(modelProjectStrings),
+        'src/runtime/model-adaptation-core.js': core, 'src/runtime/model-adaptation-core.js.map': coreMap, 'src/assets/packed-model.glb': source.packed,
+        '.playcraft/workspace.json': json({ parameters: { schemaPath: 'src/theme/theme.schema.json', dataPath: '.playcraft/model-adaptation.json', themeId: 'default' } }),
+        '.playcraft/model-adaptation.json': json(plan), '.playcraft/parent-model-adaptation.json': parentRaw,
+        '.playcraft/model-adaptation-lineage.json': json({ schemaVersion: 1, buildBindingVersion: 2, fixtureOnly: input.fixtureOnly === true, parentSource: parentPlan.source,
+            parentPlanHash: modelSourceDigest(parentRaw), derivedSource, derivedPlanHash: modelSourceDigest(json(plan)), coreHash, packedHash: source.packedHash,
+            candidateId, loaderVersion: '0.183.2', loaderRevision: '183', geometryValidation: 'pending-runtime', modelInference: false, modelAcceptance: false }),
+        'src/theme/theme.schema.json': json({ type: 'object', additionalProperties: false, properties: {
+                schemaVersion: { type: 'number', readOnly: true }, source: { type: 'object', readOnly: true },
+                normalization: { type: 'object', properties: { unitScale: { type: 'number', minimum: .000000001, maximum: 1000000000, title: 'Unit scale' }, rotationDegrees: { type: 'array', readOnly: true } } },
+                transform: { type: 'object', properties: { scale: { type: 'number', minimum: .000001, maximum: 1000000, title: 'Model scale' }, position: { type: 'array', readOnly: true }, rotationDegrees: { type: 'array', readOnly: true } } },
+                materialOverrides: { type: 'array', readOnly: true }, visibility: { type: 'array', readOnly: true }, hinges: { type: 'array', readOnly: true },
+            } }),
+        'AGENTS.md': '# Adapted model project\n\nSource files and the parent adaptation bytes are immutable copies. Save derived configuration through normal workspace operations. Final deliveries belong in root dist/, including dist/preview/index.html; all delivery dependencies must be packaged there. Private inputs and failed evidence stay outside dist/. A static model has no inferred opening capability.\n',
+        'README.md': '# Saved-model adaptation project\n\nThis prepares source without installation, building, inference or acceptance. Install pinned dependencies and build normally. The workspace parameter panel edits scalar production values; structural mappings and arrays belong to the adaptation panel. Both save .playcraft/model-adaptation.json. Original source/ files and exact parent plan are retained. Runtime geometry identities are checked by the same core as the model viewer. Skin, animation, morph targets and instancing are unsupported; merged parts need a real split. Preview controls are temporary.\n',
+    };
+    const adaptationPaths = Object.keys(files).filter(path => path.startsWith('src/') || path.startsWith('scripts/') ||
+        ['index.html', 'package.json', 'vite.config.mjs', '.playcraft/workspace.json', '.playcraft/model-adaptation.json', '.playcraft/model-adaptation-lineage.json'].includes(path));
+    if (derivedSource.files.length + adaptationPaths.length > 256 || adaptationPaths.length > 64)
+        throw new Error('model_adaptation_build_input_bound');
+    files['.playcraft/model-build-inputs.json'] = json({ schemaVersion: 1, models: [{ source: derivedSource, adaptationFiles: adaptationPaths.map(path => ({ path })) }] });
+    for (const [path, bytes] of source.originalFiles)
+        files[`source/${path}`] = bytes;
+    const manifest = { schemaVersion: 1, fixtureOnly: input.fixtureOnly === true, source: parentPlan.source, derivedSource,
+        parentPlanHash: modelSourceDigest(parentRaw), coreHash, packedHash: source.packedHash,
+        files: Object.entries(files).map(([path, bytes]) => ({ path, contentHash: modelSourceDigest(bytes), bytes: typeof bytes === 'string' ? Buffer.byteLength(bytes) : bytes.byteLength }))
+            .sort((a, b) => a.path.localeCompare(b.path, 'en')),
+        geometryValidation: 'pending-runtime', modelInference: false, modelAcceptance: false, publicationAcceptance: false };
+    files['model-adaptation-source-manifest.json'] = json(manifest);
+    input.signal?.throwIfAborted();
+    await mkdir(outputRoot, { recursive: false });
+    for (const [path, bytes] of Object.entries(files)) {
+        input.signal?.throwIfAborted();
+        const absolute = join(outputRoot, path);
+        await mkdir(dirname(absolute), { recursive: true });
+        await writeFile(absolute, bytes, { flag: 'wx' });
+    }
+    return { outputRoot, manifest };
+}

package/dist/model-adaptation/source.js

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { packModelSource, readModelSourceDocument, resolveModelDependencyPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+export const modelSourceDigest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export async function readModelSourceFile(root, path) {
+    workspaceRelativePathSchema.parse(path);
+    if (path.split('/').some(part => ['.git', '.playcraft', '.ssh', 'node_modules'].includes(part) || part === '.env' || part.startsWith('.env.')))
+        throw new Error('model_source_path_unsafe');
+    const absolute = resolve(root, path), rel = relative(root, absolute);
+    if (rel.startsWith(`..${sep}`) || isAbsolute(rel) || await realpath(absolute) !== absolute)
+        throw new Error('model_source_path_unsafe');
+    const stat = await lstat(absolute);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > 64 * 1024 * 1024)
+        throw new Error('model_source_file_bound');
+    return new Uint8Array(await readFile(absolute));
+}
+/** Source metadata only: runtime geometry identities always come from the shared actual-engine inspector. */
+export async function inspectModelSourceFiles(input) {
+    const root = await realpath(resolve(input.projectRoot)), path = relative(root, resolve(root, input.modelPath)).split(sep).join('/');
+    workspaceRelativePathSchema.parse(path);
+    if (!/\.(?:glb|gltf)$/i.test(path))
+        throw new Error('model_source_format_unsupported');
+    const bytes = await readModelSourceFile(root, path), sourceDocument = readModelSourceDocument(bytes).document;
+    const originalFiles = new Map([[path, bytes]]);
+    const packed = await packModelSource({ path, bytes, signal: input.signal, digestBytes: modelSourceDigest,
+        readDependency: async (uri) => {
+            const dependencyPath = resolveModelDependencyPath(uri, path), data = await readModelSourceFile(root, dependencyPath);
+            originalFiles.set(dependencyPath, data);
+            return { path: dependencyPath, bytes: data };
+        } });
+    const source = { kind: 'resource', path, contentHash: modelSourceDigest(bytes), files: packed.sourceFiles };
+    const list = (value) => Array.isArray(value) ? value : [];
+    const rawNodes = list(sourceDocument.nodes);
+    const meshes = list(sourceDocument.meshes);
+    const unsupported = [
+        ...(list(sourceDocument.animations).length ? ['animation'] : []), ...(list(sourceDocument.skins).length ? ['skinned_mesh'] : []),
+        ...(rawNodes.some(node => node.extensions?.EXT_mesh_gpu_instancing) ? ['instanced_mesh'] : []),
+        ...(meshes.some(mesh => mesh.primitives?.some(primitive => primitive.targets?.length)) ? ['morph_targets'] : []),
+        ...(rawNodes.length > 4096 ? ['node_bound'] : []),
+    ];
+    const metadata = { format: /\.glb$/i.test(path) ? 'glb' : 'gltf', nodes: list(sourceDocument.nodes).length,
+        meshes: list(sourceDocument.meshes).length, materials: list(sourceDocument.materials).length,
+        animations: list(sourceDocument.animations).length, skins: list(sourceDocument.skins).length,
+        extensionsUsed: list(sourceDocument.extensionsUsed), unsupported, geometryIdentity: 'requires-runtime-inspection',
+        sourceNodes: rawNodes.slice(0, 4096).map((node, gltfNodeIndex) => ({ gltfNodeIndex, name: node.name ?? '', mesh: node.mesh, children: node.children ?? [] })) };
+    return { source, packed: packed.glb, packedHash: packed.packedHash, originalFiles, metadata,
+        modelInference: false, acceptance: false };
+}