@playcraft/cli 0.1.66 → 0.1.67

package/dist/workspace-runtime/workspaces/artifact-files.js

@@ -2,22 +2,27 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, realpath, link, unlink } from 'node:fs/promises';
 import { extname, join, posix, resolve, sep } from 'node:path';
-import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema, isSoundDocumentPath } from '@playcraft/common/cloud-workspace/runtime';
 import { openSharedFile } from './shared-write.js';
+import { audioArtifactResources } from './audio-assets/artifact-package.js';
 const formats = {
     '.png': ['image', 'image/png'], '.jpg': ['image', 'image/jpeg'], '.jpeg': ['image', 'image/jpeg'],
     '.webp': ['image', 'image/webp'], '.gif': ['image', 'image/gif'], '.avif': ['image', 'image/avif'], '.svg': ['image', 'image/svg+xml'],
     '.hdr': ['image', 'image/vnd.radiance'], '.exr': ['image', 'image/x-exr'],
     '.ktx': ['image', 'image/ktx'], '.ktx2': ['image', 'image/ktx2'], '.dds': ['image', 'image/vnd-ms.dds'],
     '.mp4': ['video', 'video/mp4'], '.webm': ['video', 'video/webm'], '.mov': ['video', 'video/quicktime'],
-    '.mp3': ['audio', 'audio/mpeg'], '.wav': ['audio', 'audio/wav'], '.ogg': ['audio', 'audio/ogg'], '.m4a': ['audio', 'audio/mp4'], '.flac': ['audio', 'audio/flac'],
+    '.mp3': ['audio', 'audio/mpeg'], '.wav': ['audio', 'audio/wav'], '.ogg': ['audio', 'audio/ogg'], '.opus': ['audio', 'audio/ogg'], '.m4a': ['audio', 'audio/mp4'], '.flac': ['audio', 'audio/flac'],
     '.glb': ['model', 'model/gltf-binary'], '.gltf': ['model', 'model/gltf+json'], '.obj': ['model', 'text/plain'], '.fbx': ['model', 'application/octet-stream'], '.stl': ['model', 'model/stl'], '.usdz': ['model', 'model/vnd.usdz+zip'],
     '.md': ['document', 'text/markdown'], '.txt': ['document', 'text/plain'], '.pdf': ['document', 'application/pdf'],
     '.html': ['document', 'text/html'], '.csv': ['document', 'text/csv'], '.docx': ['document', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
     '.pptx': ['document', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'], '.xlsx': ['document', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
     '.zip': ['file', 'application/zip'],
 };
-export function artifactFormat(path) { return formats[extname(path).toLowerCase()]; }
+export function artifactFormat(path) {
+    if (isSoundDocumentPath(path))
+        return ['audio', 'application/json'];
+    return formats[extname(path).toLowerCase()];
+}
 export function artifactMime(path) { return artifactFormat(path)?.[1] ?? 'application/octet-stream'; }
 /** Reject every redirected path segment, including links that happen to remain in the workspace. */
 export async function artifactPath(root, path) {
@@ -152,6 +157,8 @@ async function binaryModelDocument(root, path) {
 }
 /** Only explicit model references become members; neighboring names never imply a relationship. */
 export async function artifactResources(root, path) {
+    if (isSoundDocumentPath(path))
+        return audioArtifactResources(root, path);
     const resources = new Set();
     const add = (from, uri) => { const result = resourcePath(from, uri); if (result)
         resources.add(result); };

package/dist/workspace-runtime/workspaces/artifacts.js

@@ -1,18 +1,23 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import sharp from 'sharp';
-import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, workspaceModelBuildSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, isSoundDocumentPath, workspaceModelBuildSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactBundleDigest, artifactDirectory, artifactFormat, artifactPath, artifactResources, snapshotArtifactBundle, snapshotArtifactFile } from './artifact-files.js';
 import { ARTIFACT_RECEIPTS_DIRECTORY, readArtifactReceipt } from './artifact-receipts.js';
 import { ensureSharedDirectory } from './shared-write.js';
 import { validateWorkspacePlayable } from '../previews/finalize.js';
 import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
 import { applyWorkspaceModelBuildStates, sameWorkspaceModelBuild } from './model-build-inputs.js';
+import { audioArtifactDetails, validateAudioArtifactVersion } from './audio-assets/artifact-package.js';
+import { readAudioSource } from './audio-assets/storage.js';
 const serial = new Map();
 function digest(text) { return createHash('sha256').update(text).digest('hex'); }
-function artifactId(workspaceId, path) { return `artifact_${digest(`${workspaceId}\0${path}`).slice(0, 40)}`; }
+function artifactId(workspaceId, path) {
+    const audioKey = /^dist\/audio\/([a-f0-9]{64})\/[a-f0-9]{64}\/[a-f0-9]{64}\/sound\.(?:pcaudio|pcscore)\.json$/.exec(path)?.[1];
+    return `artifact_${digest(`${workspaceId}\0${audioKey ? `audio-source:${audioKey}` : path}`).slice(0, 40)}`;
+}
 function outputArtifacts(artifacts) {
     return artifacts.flatMap(artifact => {
         const versions = artifact.versions.filter(isWorkspaceArtifactOutputVersion);
@@ -152,10 +157,34 @@ export class WorkspaceArtifactStore {
             catch { /* An incomplete receipt stays pending; the next scan retries its original bytes. */ }
         }
         const candidates = await discoverPaths(root);
-        // Models are inspected before images so their explicitly referenced textures stay under the model.
-        candidates.sort((a, b) => Number(artifactFormat(b)?.[0] === 'model') - Number(artifactFormat(a)?.[0] === 'model') || a.localeCompare(b));
+        // Compound sounds and models claim their explicitly listed resources before standalone media.
+        const priority = (path) => isSoundDocumentPath(path) ? 2 : Number(artifactFormat(path)?.[0] === 'model');
+        candidates.sort((a, b) => priority(b) - priority(a) || a.localeCompare(b));
         const visible = outputArtifacts(catalog.artifacts);
         const members = new Set(visible.flatMap(artifact => artifact.versions.flatMap(version => version.files.filter(file => file.role !== 'primary').map(file => file.path))));
+        const audioMembers = new Set();
+        const currentAudio = new Set();
+        for (const path of candidates.filter(isSoundDocumentPath)) {
+            try {
+                const details = await audioArtifactDetails(root, path);
+                for (const member of details.resources) {
+                    members.add(member);
+                    audioMembers.add(member);
+                }
+                const source = await readAudioSource(root, details.sourcePath).catch(() => undefined);
+                if (source !== undefined && digest(source) === details.sourceContentHash)
+                    currentAudio.add(path);
+            }
+            catch {
+                // An incomplete sound package stays visible as ordinary files, never as a standalone audio fallback.
+                for (const candidate of candidates.filter(value => dirname(value) === dirname(path))) {
+                    members.add(candidate);
+                    if (candidate !== path)
+                        audioMembers.add(candidate);
+                }
+            }
+        }
+        candidates.sort((a, b) => priority(b) - priority(a) || Number(currentAudio.has(a)) - Number(currentAudio.has(b)) || a.localeCompare(b));
         for (const path of candidates) {
             if (members.has(path))
                 continue;
@@ -165,7 +194,9 @@ export class WorkspaceArtifactStore {
                 continue;
             try {
                 const current = visible.find(artifact => artifact.id === artifactId(this.scopeId, path));
-                const version = current?.versions.find(entry => entry.id === current.currentVersionId);
+                const version = isSoundDocumentPath(path)
+                    ? current?.versions.find(entry => entry.path === path && entry.id === catalog.observations[path]?.versionId) ?? current?.versions.find(entry => entry.path === path)
+                    : current?.versions.find(entry => entry.id === current.currentVersionId);
                 const knownWrite = sourcePaths.includes(path) && Boolean(source.operationId) && version?.source.operationId !== source.operationId;
                 const observation = catalog.observations[path];
                 if (!knownWrite && version && (path !== WORKSPACE_PLAYABLE_OUTPUT_PATH || current?.kind === 'playable')
@@ -229,6 +260,8 @@ export class WorkspaceArtifactStore {
         }
         catalog.artifacts = catalog.artifacts.filter(artifact => {
             const current = artifact.versions.find(version => version.id === artifact.currentVersionId);
+            if (audioMembers.has(current.path))
+                return false;
             return !isWorkspaceArtifactOutputVersion(current) || current.source.kind !== 'discovered' || !members.has(current.path);
         });
         catalog.artifacts.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
@@ -238,6 +271,10 @@ export class WorkspaceArtifactStore {
         return { list, changed: original !== JSON.stringify(list.artifacts) };
     }
     async versionKind(objects, version) {
+        if (isSoundDocumentPath(version.path)) {
+            await validateAudioArtifactVersion(objects, version.path, version.files);
+            return 'audio';
+        }
         if (version.path !== WORKSPACE_PLAYABLE_OUTPUT_PATH)
             return artifactFormat(version.path)[0];
         if (version.files.length !== 1)
@@ -260,11 +297,15 @@ export class WorkspaceArtifactStore {
     }
     async add(catalog, version, kind, objects) {
         const id = artifactId(this.scopeId, version.path);
+        const audioName = kind === 'audio' && isSoundDocumentPath(version.path)
+            ? (await validateAudioArtifactVersion(objects, version.path, version.files)).name : undefined;
         let artifact = catalog.artifacts.find(item => item.id === id);
         if (!artifact) {
             artifact = { id, kind, name: basename(version.path), currentVersionId: version.id, updatedAt: version.createdAt, versions: [] };
             catalog.artifacts.push(artifact);
         }
+        if (audioName)
+            artifact.name = audioName;
         if (kind === 'playable' && artifact.kind !== 'playable') {
             const valid = await Promise.all(artifact.versions.map(async (item) => {
                 try {

package/dist/workspace-runtime/workspaces/audio-assets/artifact-package.js

@@ -0,0 +1,104 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { posix } from 'node:path';
+import { parseSoundDocument, soundSourceRenderHash, audioRepresentationSetHash, canonicalAudioJson, isSoundDocumentPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { audioProjectPath, audioError, digest } from './storage.js';
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+async function bytes(root, path, maximum) {
+    const file = await open(await audioProjectPath(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > maximum)
+            throw audioError('invalid_audio_package', 400);
+        const result = await file.readFile(), after = await file.stat();
+        if (result.length !== before.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw audioError('invalid_audio_package', 400);
+        return result;
+    }
+    finally {
+        await file.close();
+    }
+}
+/** A source alone is editable; only a fully verified manifest can identify a delivered sound bundle. */
+export async function audioArtifactResources(root, primaryPath) {
+    return (await audioArtifactDetails(root, primaryPath)).resources;
+}
+export async function audioArtifactDetails(root, primaryPath) {
+    return inspectPackage(primaryPath, (path, maximum) => bytes(root, path, maximum));
+}
+/** Build snapshots retain the exact verified bytes, avoiding a second unverified file read. */
+export async function readAudioArtifactPackage(root, primaryPath) {
+    const files = new Map();
+    const details = await inspectPackage(primaryPath, async (path, maximum) => {
+        const data = await bytes(root, path, maximum);
+        files.set(path, data);
+        return data;
+    });
+    return { ...details, files };
+}
+export async function validateAudioArtifactVersion(objects, primaryPath, files) {
+    if (files.length !== 5 || new Set(files.map(file => file.path)).size !== files.length ||
+        files.filter(file => file.role === 'primary').length !== 1 || !files.some(file => file.path === primaryPath && file.role === 'primary'))
+        throw audioError('invalid_audio_package', 400);
+    return inspectPackage(primaryPath, async (path, maximum) => {
+        const record = files.find(file => file.path === path);
+        if (!record || !hash(record.sha256))
+            throw audioError('invalid_audio_package', 400);
+        const result = await bytes(objects, record.sha256, maximum);
+        if (result.length !== record.size || digest(result) !== record.sha256)
+            throw audioError('invalid_audio_package', 400);
+        return result;
+    });
+}
+async function inspectPackage(primaryPath, read) {
+    const sourceBytes = await read(primaryPath, 65536), document = parseSoundDocument(sourceBytes);
+    const sourceName = document.format === 'playcraft.score' ? 'sound.pcscore.json' : 'sound.pcaudio.json';
+    const directory = posix.dirname(primaryPath), manifestPath = `${directory}/manifest.json`;
+    const manifestBytes = await read(manifestPath, 65536);
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes));
+    }
+    catch {
+        throw audioError('invalid_audio_package', 400);
+    }
+    const allowed = ['version', 'sourcePath', 'sourceContentHash', 'sourceRenderHash', 'engine', 'rendererBuildHash', 'chromiumVersion',
+        'renderKey', 'pcmContentHash', 'files', 'representationSetHash'];
+    if (!manifest || Array.isArray(manifest) || Object.keys(manifest).length !== allowed.length || Object.keys(manifest).some(key => !allowed.includes(key)) ||
+        manifest.version !== 1 || !hash(manifest.sourceContentHash) || manifest.sourceContentHash !== digest(sourceBytes) ||
+        manifest.sourceRenderHash !== soundSourceRenderHash(document) || canonicalAudioJson(manifest.engine) !== canonicalAudioJson(document.engine) ||
+        !hash(manifest.rendererBuildHash) || !hash(manifest.renderKey) || !hash(manifest.pcmContentHash) ||
+        typeof manifest.chromiumVersion !== 'string' || !manifest.chromiumVersion || manifest.chromiumVersion.length > 128 ||
+        typeof manifest.sourcePath !== 'string' || !isSoundDocumentPath(manifest.sourcePath) ||
+        !manifest.sourcePath.endsWith(document.format === 'playcraft.score' ? '.pcscore.json' : '.pcaudio.json') ||
+        !workspaceRelativePathSchema.safeParse(manifest.sourcePath).success || manifest.sourcePath.split('/').some(part => ['.git', '.playcraft', 'node_modules'].includes(part)) ||
+        !hash(manifest.representationSetHash) || !Array.isArray(manifest.files) || manifest.files.length !== 4)
+        throw audioError('invalid_audio_package', 400);
+    if (digest(manifestBytes) !== digest(`${canonicalAudioJson(manifest)}\n`))
+        throw audioError('invalid_audio_package', 400);
+    const { representationSetHash, ...payload } = manifest;
+    if (audioRepresentationSetHash(payload) !== representationSetHash ||
+        directory !== `dist/audio/${digest(manifest.sourcePath)}/${manifest.sourceContentHash}/${representationSetHash}`)
+        throw audioError('invalid_audio_package', 400);
+    const expected = new Map([[sourceName, ['application/json', 'editable']], ['audition.wav', ['audio/wav', 'audition']],
+        ['runtime.mjs', ['text/javascript', 'runtime']], ['sound.mjs', ['text/javascript', 'delivery']]]);
+    const resources = new Set([manifestPath]);
+    for (const file of manifest.files) {
+        if (!file || Array.isArray(file) || Object.keys(file).sort().join(',') !== 'contentHash,mimeType,path,role,size' ||
+            typeof file.path !== 'string' || !expected.has(file.path) || !hash(file.contentHash) || !Number.isSafeInteger(file.size) ||
+            file.size < 1 || file.size > (document.format === 'playcraft.score' ? 6 * 1024 * 1024 : 2 * 1024 * 1024))
+            throw audioError('invalid_audio_package', 400);
+        const [mimeType, role] = expected.get(file.path);
+        expected.delete(file.path);
+        if (file.mimeType !== mimeType || file.role !== role)
+            throw audioError('invalid_audio_package', 400);
+        const path = `${directory}/${file.path}`, member = await read(path, file.size);
+        if (member.length !== file.size || digest(member) !== file.contentHash)
+            throw audioError('invalid_audio_package', 400);
+        if (path !== primaryPath)
+            resources.add(path);
+    }
+    if (expected.size || !primaryPath.endsWith('/' + sourceName))
+        throw audioError('invalid_audio_package', 400);
+    return { resources: [...resources].sort(), name: document.name, sourcePath: manifest.sourcePath, sourceContentHash: manifest.sourceContentHash };
+}

package/dist/workspace-runtime/workspaces/audio-assets/binding-usage.js

@@ -0,0 +1,71 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { workspaceAudioBindingSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { audioProjectPath, digest } from './storage.js';
+const maximumBindingBytes = 16_384;
+/** Observe the tracked public binding without rewriting the source, binding, or private history. */
+export async function readAudioBindingUsage(root, sourcePath, sourceContentHash, history, tracked) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(tracked.eventName))
+        return undefined;
+    const bindingPath = `source/audio-bindings/${tracked.eventName}.json`;
+    const location = { status: 'integration_required', bindingPath, eventName: tracked.eventName };
+    const invalid = { ...location, bindingState: 'invalid' };
+    if (tracked.bindingPath !== bindingPath)
+        return invalid;
+    try {
+        const path = await audioProjectPath(root, tracked.bindingPath);
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        let bytes;
+        try {
+            const before = await file.stat();
+            if (!before.isFile() || before.nlink !== 1 || before.size < 1 || before.size > maximumBindingBytes)
+                return invalid;
+            // Recheck the path after opening, before reading any bytes through the retained descriptor.
+            const named = await lstat(await audioProjectPath(root, tracked.bindingPath));
+            if (named.dev !== before.dev || named.ino !== before.ino)
+                return invalid;
+            const buffer = Buffer.alloc(before.size + 1);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, 0), after = await file.stat();
+            if (bytesRead !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+                return invalid;
+            bytes = buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await file.close();
+        }
+        const parsed = workspaceAudioBindingSchema.safeParse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+        if (!parsed.success || parsed.data.eventName !== tracked.eventName)
+            return invalid;
+        const binding = parsed.data;
+        if (binding.sourcePath !== sourcePath)
+            return { ...location, bindingState: 'different_source' };
+        if (!history.some(version => version.revision === binding.revision && version.contentHash === binding.sourceContentHash))
+            return invalid;
+        const directory = `dist/audio/${digest(sourcePath)}/${binding.sourceContentHash}/${binding.representationSetHash}`;
+        if (binding.modulePath !== `${directory}/sound.mjs`)
+            return invalid;
+        const bundle = await readAudioArtifactPackage(root, `${directory}/sound.${sourcePath.endsWith('.pcscore.json') ? 'pcscore' : 'pcaudio'}.json`);
+        const audition = bundle.files.get(`${directory}/audition.wav`);
+        if (bundle.sourcePath !== sourcePath || bundle.sourceContentHash !== binding.sourceContentHash
+            || !audition || digest(audition) !== binding.auditionContentHash)
+            return invalid;
+        return { ...location, bindingState: binding.sourceContentHash === sourceContentHash ? 'current' : 'different_version',
+            sourceContentHash: binding.sourceContentHash, revision: binding.revision, modulePath: binding.modulePath,
+            representationSetHash: binding.representationSetHash,
+            ...(binding.previousBinding ? { previousContentHash: binding.previousBinding } : {}) };
+    }
+    catch (error) {
+        // Only an absent binding is missing; broken package members are invalid bindings.
+        if (error.code === 'ENOENT') {
+            try {
+                await lstat(await audioProjectPath(root, tracked.bindingPath));
+            }
+            catch (missing) {
+                if (missing.code === 'ENOENT')
+                    return { ...location, bindingState: 'missing' };
+            }
+        }
+        return invalid;
+    }
+}

package/dist/workspace-runtime/workspaces/audio-assets/build-inputs.js

@@ -0,0 +1,76 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { canonicalAudioJson } from '@playcraft/common/cloud-workspace/runtime';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { audioError, audioProjectPath, digest, readAudioSource } from './storage.js';
+import { ensureSharedDirectory, writeSharedFile } from '../shared-write.js';
+const hashPart = /^[a-f0-9]{64}$/;
+const MAX_PACKAGES = 256;
+const MAX_PACKAGE_BYTES = 64 * 1024 * 1024;
+async function packagePaths(root) {
+    const paths = [];
+    const visit = async (path, depth) => {
+        const absolute = await audioProjectPath(root, path);
+        const stat = await lstat(absolute).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (!stat?.isDirectory() || stat.isSymbolicLink())
+            return;
+        if (depth === 3) {
+            if (paths.length >= MAX_PACKAGES)
+                throw audioError('audio_build_budget_exceeded', 422);
+            const names = await readdir(absolute);
+            for (const name of ['sound.pcaudio.json', 'sound.pcscore.json'])
+                if (names.includes(name)) {
+                    if (paths.length >= MAX_PACKAGES)
+                        throw audioError('audio_build_budget_exceeded', 422);
+                    paths.push(`${path}/${name}`);
+                }
+            return;
+        }
+        for (const entry of (await readdir(absolute, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name)))
+            if (entry.isDirectory() && !entry.isSymbolicLink() && hashPart.test(entry.name))
+                await visit(`${path}/${entry.name}`, depth + 1);
+    };
+    await visit('dist/audio', 0);
+    return paths;
+}
+/** Only validated immutable sound packages join source inputs; unrelated dist outputs stay excluded. */
+export async function readAudioBuildInputs(root, destination) {
+    const packages = [];
+    let totalBytes = 0;
+    for (const primaryPath of await packagePaths(root)) {
+        let bundle;
+        try {
+            bundle = await readAudioArtifactPackage(root, primaryPath);
+        }
+        catch {
+            continue;
+        }
+        const sourceText = await readAudioSource(root, bundle.sourcePath);
+        const files = [...bundle.files].map(([path, bytes]) => ({ path, contentHash: digest(bytes) })).sort((a, b) => a.path.localeCompare(b.path));
+        totalBytes += [...bundle.files.values()].reduce((total, bytes) => total + bytes.length, 0) + (sourceText === undefined ? 0 : Buffer.byteLength(sourceText));
+        if (totalBytes > MAX_PACKAGE_BYTES)
+            throw audioError('audio_build_budget_exceeded', 422);
+        if (destination) {
+            for (const [path, bytes] of bundle.files) {
+                const target = await audioProjectPath(destination, path, true);
+                await ensureSharedDirectory(destination, dirname(target));
+                await writeSharedFile(destination, target, bytes);
+            }
+            if (sourceText !== undefined) {
+                const target = await audioProjectPath(destination, bundle.sourcePath, true);
+                await ensureSharedDirectory(destination, dirname(target));
+                await writeSharedFile(destination, target, sourceText);
+            }
+        }
+        packages.push({ primaryPath, sourcePath: bundle.sourcePath, sourceContentHash: sourceText === undefined ? null : digest(sourceText), files });
+    }
+    return { version: 1, inputHash: digest(canonicalAudioJson(packages)), packages };
+}
+export async function verifyAudioBuildInputs(root, snapshot) {
+    if ((await readAudioBuildInputs(root)).inputHash !== snapshot.inputHash)
+        throw audioError('audio_build_input_changed');
+}
+export function markAudioBuildInputs(bytes, snapshot) {
+    return snapshot.packages.length ? Buffer.concat([Buffer.from(`<!--playcraft-audio-inputs:v1:${snapshot.inputHash}-->\n`), bytes]) : bytes;
+}

package/dist/workspace-runtime/workspaces/audio-assets/render-worker.js

@@ -0,0 +1,117 @@
+import { open, readFile, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright-core';
+export const AUDIO_RENDER_CHUNK_BYTES = 64 * 1024;
+/** This function is serialized into the isolated browser and must have no module closure. */
+export function encodeAudioRenderChunk(rendered, request) {
+    const { kind, offset, length } = request;
+    if (!['pcm', 'wav'].includes(kind) || !Number.isSafeInteger(offset) || offset < 0
+        || !Number.isSafeInteger(length) || length < 1 || length > 64 * 1024)
+        throw new Error('audio_budget_exceeded');
+    const total = kind === 'pcm' ? rendered.buffer.length * 4 : rendered.wav.byteLength;
+    if (offset + length > total || kind === 'pcm' && (offset % 4 || length % 4))
+        throw new Error('invalid_audio_output');
+    let data;
+    if (kind === 'pcm') {
+        data = new Uint8Array(length);
+        const view = new DataView(data.buffer), samples = rendered.buffer.getChannelData(0);
+        for (let index = 0; index < length / 4; index++)
+            view.setFloat32(index * 4, samples[offset / 4 + index], true);
+    }
+    else
+        data = new Uint8Array(rendered.wav, offset, length);
+    let text = '';
+    for (let index = 0; index < data.length; index += 16384)
+        text += String.fromCharCode(...data.subarray(index, index + 16384));
+    return btoa(text);
+}
+/** Acknowledged, bounded chunks keep the control transport and worker from retaining the entire payload. */
+export async function writeAudioRenderOutput(outputPath, summary, chromiumVersion, readChunk, maximumFrames) {
+    if (!Number.isSafeInteger(summary.frames) || summary.frames < 1 || summary.frames > maximumFrames
+        || maximumFrames > 2_646_000 || summary.wavBytes !== 44 + summary.frames * 2)
+        throw new Error('audio_budget_exceeded');
+    const created = [], files = [];
+    const openOutput = async (suffix) => {
+        // shared: the render worker runs as the development identity and the controller reads its bytes.
+        const path = `${outputPath}.${suffix}`, file = await open(path, 'wx', 0o660);
+        created.push(path);
+        files.push(file);
+        return file;
+    };
+    try {
+        const pcmHash = createHash('sha256');
+        for (const kind of ['pcm', 'wav']) {
+            const file = await openOutput(kind), total = kind === 'pcm' ? summary.frames * 4 : summary.wavBytes;
+            for (let offset = 0; offset < total; offset += AUDIO_RENDER_CHUNK_BYTES) {
+                const length = Math.min(AUDIO_RENDER_CHUNK_BYTES, total - offset);
+                const encoded = await readChunk({ kind, offset, length });
+                if (typeof encoded !== 'string' || encoded.length !== Math.ceil(length / 3) * 4
+                    || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded))
+                    throw new Error('invalid_audio_output');
+                const chunk = Buffer.from(encoded, 'base64');
+                if (chunk.length !== length || chunk.toString('base64') !== encoded)
+                    throw new Error('invalid_audio_output');
+                await file.writeFile(chunk);
+                if (kind === 'pcm')
+                    pcmHash.update(chunk);
+            }
+        }
+        const metadata = await openOutput('json');
+        await metadata.writeFile(JSON.stringify({ chromiumVersion, metrics: summary.metrics, pcmContentHash: pcmHash.digest('hex') }));
+        for (const file of files)
+            await file.close();
+        return created;
+    }
+    catch (error) {
+        await Promise.allSettled(files.map(file => file.close()));
+        await Promise.all(created.map(path => rm(path, { force: true })));
+        throw error;
+    }
+}
+/** This worker executes only the verified platform graph, never a project page. */
+async function main() {
+    const [inputPath, outputPath] = process.argv.slice(2);
+    const uid = process.getuid?.();
+    if (!inputPath || !outputPath || typeof uid !== 'number' || uid <= 0)
+        throw new Error('audio_renderer_identity_unavailable');
+    const input = JSON.parse(await readFile(inputPath, 'utf8'));
+    if (Buffer.byteLength(input.script) > 512 * 1024 || createHash('sha256').update(input.script).digest('hex') !== input.rendererBuildHash)
+        throw new Error('engine_build_mismatch');
+    const browser = await chromium.launch({ executablePath: process.env.PLAYCRAFT_CHROMIUM_PATH || '/usr/bin/chromium',
+        headless: true, chromiumSandbox: true, timeout: 8000, args: ['--mute-audio', '--disable-background-networking'] });
+    let created = [];
+    try {
+        try {
+            const context = await browser.newContext({ serviceWorkers: 'block', acceptDownloads: false });
+            await context.route('**/*', route => route.abort('blockedbyclient'));
+            const page = await context.newPage();
+            await page.addScriptTag({ content: input.script });
+            const rendered = await page.evaluateHandle(async (document) => {
+                const engine = globalThis.playcraftAudio;
+                const buffer = await engine.renderAudioDocument(document);
+                const maximumFrames = document && typeof document === 'object' && 'format' in document && document.format === 'playcraft.score' ? 2_646_000 : 441_000;
+                if (buffer.length > maximumFrames || buffer.numberOfChannels !== 1)
+                    throw new Error('audio_budget_exceeded');
+                return { buffer, wav: engine.audioBufferToWav(buffer), metrics: engine.audioPcmMetrics(buffer) };
+            }, input.document);
+            try {
+                const summary = await rendered.evaluate(value => ({ frames: value.buffer.length, wavBytes: value.wav.byteLength, metrics: value.metrics }));
+                const score = input.document && typeof input.document === 'object' && 'format' in input.document && input.document.format === 'playcraft.score';
+                created = await writeAudioRenderOutput(outputPath, summary, browser.version(), request => rendered.evaluate(encodeAudioRenderChunk, request), score ? 2_646_000 : 441_000);
+            }
+            finally {
+                await rendered.dispose();
+            }
+        }
+        finally {
+            await browser.close();
+        }
+    }
+    catch (error) {
+        await Promise.all(created.map(path => rm(path, { force: true })));
+        throw error;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+    void main().catch(error => { process.stderr.write(`${error instanceof Error ? error.message : 'audio_render_failed'}\n`); process.exitCode = 1; });