@playcraft/cli 0.1.61-beta → 0.1.63

package/dist/commands/build.js

@@ -9,7 +9,8 @@ import inquirer from 'inquirer';
 import { tmpdir } from 'node:os';
 import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
 import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/delivery-build.js';
-import { finalizeWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
+import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
+import { AgentApiClient } from '../utils/agent-api-client.js';
 /**
  * 类型守卫：检查对象是否符合 PlayableScriptsConfig 类型
  */
@@ -268,13 +269,21 @@ export async function buildCommand(projectPath, options) {
                 if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
                     throw new Error('preview_not_single_file');
                 await finalizeWorkspacePlayable(workspace.root, await fs.readFile(path.join(output, entries[0].name)), 'playcraft build', { expectedSignature: signature });
+                console.log(path.join(workspace.root, 'dist/playable/index.html'));
+                try {
+                    const { bytes } = await readWorkspacePlayable(workspace.root);
+                    const { previewUrl } = await new AgentApiClient().publishWorkspacePlayable({ workspaceId: workspace.workspaceId, directoryName: path.basename(workspace.root) }, bytes);
+                    console.log(`Public URL: ${previewUrl}`);
+                }
+                catch (error) {
+                    console.warn(`Public URL unavailable: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                return;
             }
-            else {
-                if (options.clean === true)
-                    await fs.rm(requestedOutput, { recursive: true, force: true });
-                await fs.cp(output, requestedOutput, { recursive: true });
-            }
-            console.log(canonicalOutput ? path.join(workspace.root, 'dist/playable/index.html') : requestedOutput);
+            if (options.clean === true)
+                await fs.rm(requestedOutput, { recursive: true, force: true });
+            await fs.cp(output, requestedOutput, { recursive: true });
+            console.log(requestedOutput);
             return;
         }
         finally {

package/dist/utils/agent-api-client.js

@@ -11,6 +11,7 @@ import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
 import { beginToolOperation, findToolOperation } from './tool-operation-journal.js';
 import { businessEndpoint } from './environment-endpoints.js';
+import { PLATFORM_ROUTES } from '@playcraft/common/cloud-workspace/runtime';
 import { cloudRuntimeCredentialHint, isWorkspaceGenerationPath, withGenerationWorkspaceScope } from './generation-workspace-scope.js';
 import { agentGenerationProvenanceHeaders } from './agent-generation-provenance.js';
 import { redactDiagnosticText } from './error-diagnostics.js';
@@ -301,6 +302,27 @@ export class AgentApiClient {
         }
         await response.body?.cancel();
     }
+    /** Publish a workspace's single-file playable through the runtime with the sandbox credential. */
+    async publishWorkspacePlayable(query, html, signal = AbortSignal.timeout(2 * 60_000)) {
+        const url = businessEndpoint(this.apiUrl, PLATFORM_ROUTES.cliPlayablePublications);
+        url.searchParams.set('workspaceId', query.workspaceId);
+        url.searchParams.set('directoryName', query.directoryName);
+        const response = await fetch(url, {
+            method: 'POST', redirect: 'error', signal,
+            headers: { ...this.authHeaders(), 'content-type': 'application/octet-stream' },
+            body: html,
+        });
+        const text = await response.text().catch(() => response.statusText);
+        if (!response.ok) {
+            const reason = responseErrorReason(text) || redactDiagnosticText(response.statusText);
+            throw new Error(`playable_publication_failed:${response.status}${reason ? `: ${reason}` : ''}`);
+        }
+        const previewUrl = JSON.parse(text).previewUrl;
+        if (typeof previewUrl !== 'string' || !/^https?:$/.test(new URL(previewUrl).protocol)) {
+            throw new Error('playable_publication_failed: invalid_public_url');
+        }
+        return { previewUrl };
+    }
     /**
      * 按顺序搜索本地 .playcraft.json 文件（沙箱内或项目目录）。
      * 与全局 login 配置（~/.playcraft/config.json）不同，前者专用于沙箱 token。

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

@@ -17,6 +17,7 @@ const credentialSchema = z.object({
         generation: z.number().int(), runtimeEpoch: z.number().int(),
     }),
 });
+const MAX_MODEL_REQUEST_BYTES = 128 * 1024 * 1024;
 /** Keeps renewable execution credentials in control memory, outside Codex and project files. */
 export class WorkspaceModelBroker {
     state;
@@ -213,6 +214,16 @@ export class WorkspaceModelBroker {
                 await this.references.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
                 return;
             }
+            const rejectOversizedBody = () => {
+                response.writeHead(413, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+                response.end(JSON.stringify({ error: { message: 'model_request_too_large',
+                        type: 'invalid_request_error', code: 'model_request_too_large', maxBytes: MAX_MODEL_REQUEST_BYTES } }));
+            };
+            const declaredLength = request.headers['content-length'];
+            if (declaredLength !== undefined && /^\d+$/.test(declaredLength) && Number(declaredLength) > MAX_MODEL_REQUEST_BYTES) {
+                rejectOversizedBody();
+                return;
+            }
             activeRoute = route;
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);
@@ -222,9 +233,8 @@ export class WorkspaceModelBroker {
             let size = 0;
             for await (const chunk of request) {
                 size += chunk.length;
-                if (size > 16 * 1024 * 1024) {
-                    response.writeHead(413);
-                    response.end();
+                if (size > MAX_MODEL_REQUEST_BYTES) {
+                    rejectOversizedBody();
                     return;
                 }
                 chunks.push(Buffer.from(chunk));

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

@@ -5,18 +5,19 @@ import { constants } from 'node:fs';
 import { lstat, mkdtemp, open, readdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { PREVIEW_HTML_MAX_BYTES, PREVIEW_LOG_TAIL_MAX, WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, previewPublishResultSchema, previewReservationSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { PREVIEW_HTML_MAX_BYTES, PREVIEW_LOG_TAIL_MAX, WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, WORKSPACE_PLAYABLE_OUTPUT_PATH, workspaceModelBuildSchema, previewPublishResultSchema, previewReservationSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
 import { excludeFromGit, readDependencies, scheduleDependencyInstall, } from '../workspaces/dependencies.js';
 import { runDeveloperCommand } from '../workspaces/developer-command.js';
 import { revisionScope, workspaceRoot } from '../workspaces/registry.js';
 import { classifyPreviewOutput, findExternalLocalReferences } from './single-file.js';
-import { finalizeWorkspacePlayable, workspacePlayableSignature } from './finalize.js';
+import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from './finalize.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
 import { isolateWorkspaceForBuild } from '../workspaces/delivery-build.js';
 import { openScratchToDevelopment } from '../workspaces/directory-access.js';
 import { injectPreviewDiagnostics } from './diagnostics.js';
 import { OperationLogStore } from '../workspaces/operation-log.js';
 import { prepareRuntimePreview, RuntimePreviewBuildError } from './runtime-preview.js';
+import { readWorkspaceModelBuildInputs, verifyWorkspaceModelBuildInputs, markWorkspaceModelBuild } from '../workspaces/model-build-inputs.js';
 import { driftScope, permissionDriftFromOutput, repairWorkspaceShares, } from '../workspaces/workspace-shares.js';
 const BUILD_TIMEOUT_MS = 10 * 60_000;
 /** Build output and the builder's own scratch folder live in the checkout, hidden from Git. */
@@ -86,7 +87,10 @@ export async function runPreviewPublish(state, operation, root) {
     await operationLog.append(operation.operationId, `$ preview build\n`).catch(() => undefined);
     try {
         await ensureDependencies(state, revisionScope(state, workspaceId, operation.directoryName) ?? workspaceId, root, output);
+        const modelInputs = await readWorkspaceModelBuildInputs(root, state.config.stateDir);
         const runtimePreview = await prepareRuntimePreview(state, operation, root);
+        if (modelInputs && runtimePreview)
+            throw new PreviewFailure('model_build_runtime_preview_unsupported');
         remotePreview = Boolean(runtimePreview);
         if (runtimePreview)
             await excludeFromGit(root, '/.playcraft-editor-preview/');
@@ -100,11 +104,31 @@ export async function runPreviewPublish(state, operation, root) {
             await openScratchToDevelopment(buildCopy, (await lstat(root)).gid);
             const project = join(buildCopy, 'project'), staged = join(buildCopy, 'output');
             await isolateWorkspaceForBuild(root, project);
+            if (modelInputs)
+                await verifyWorkspaceModelBuildInputs(project, modelInputs);
             await buildPreview(state, project, staged, operation.operationId, output, appendLog);
-            await finalizeWorkspacePlayable(root, await readSingleHtml(staged), 'preview.publish', {
+            if (modelInputs)
+                await verifyWorkspaceModelBuildInputs(project, modelInputs);
+            if (modelInputs)
+                await verifyWorkspaceModelBuildInputs(root, modelInputs);
+            const built = await readSingleHtml(staged);
+            const finalBytes = modelInputs ? markWorkspaceModelBuild(built, modelInputs) : built;
+            await finalizeWorkspacePlayable(root, finalBytes, 'preview.publish', {
                 expectedSignature: signature, source: { operationId: operation.operationId, ...(operation.sessionId ? { sessionId: operation.sessionId } : {}) },
             });
-            await refreshWorkspaceArtifacts(state, workspaceId, undefined, operation.directoryName ?? 'basic');
+            if (modelInputs) {
+                await verifyWorkspaceModelBuildInputs(root, modelInputs);
+                const finalized = await readWorkspacePlayable(root);
+                if (!finalized.bytes.equals(injectPreviewDiagnostics(finalBytes)))
+                    throw new PreviewFailure('model_build_output_changed');
+                const modelBuild = workspaceModelBuildSchema.parse({ ...modelInputs, buildOperationId: operation.gatewayOperationId ?? operation.operationId,
+                    outputHash: createHash('sha256').update(finalized.bytes).digest('hex') });
+                await refreshWorkspaceArtifacts(state, workspaceId, { source: { kind: 'generated', tool: 'preview.publish', operationId: operation.operationId,
+                        ...(operation.sessionId ? { sessionId: operation.sessionId } : {}) }, paths: [WORKSPACE_PLAYABLE_OUTPUT_PATH],
+                    playable: { mode: 'success', modelBuild } }, operation.directoryName ?? 'basic');
+            }
+            else
+                await refreshWorkspaceArtifacts(state, workspaceId, undefined, operation.directoryName ?? 'basic');
             return;
         }
         await buildPreview(state, root, outputDir, operation.operationId, output, appendLog, runtimePreview.command);

package/dist/workspace-runtime/serve.js

@@ -35,6 +35,7 @@ import { startSourceEventUploader, stopSourceEventUploader } from './server/sour
 import { platformExportTarget, readPlatformExport, startPlatformExport } from './workspaces/platform-export.js';
 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';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -79,6 +80,10 @@ export async function startWorkspaceRuntime(config, options = {}) {
             instanceToken: randomUUID(),
         };
         const recoveredImports = new Map();
+        await recoverModelPreviewOperations(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) => {

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', 'directory.create',
+const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'delivery.build', 'model.preview', 'directory.create',
     'directory.rename', 'directory.delete', 'workspace.references.import', 'skills.update', 'parameter.verify',
     'checkpoint.create', 'checkpoint.restore']);
 export function managedDirectoryScope(state, value) {

package/dist/workspace-runtime/server/dispatch.js

@@ -6,7 +6,7 @@ import { shareWorkspaceGit } from '../workspaces/shared-git.js';
 import { cancelPendingDirectoryAccess, holdDirectoryAccess, withOperationDirectoryAccess } from './directory-access.js';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { fileWritePayloadSchema, fileBinaryWritePayloadSchema, directoryCreatePayloadSchema, directoryRenamePayloadSchema, directoryDeletePayloadSchema, directoryMutationReceiptSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, gitPullPayloadSchema, gitMergeAbortPayloadSchema, parameterPatchPayloadSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, productionSessionAttemptId, reasoningEffortSchema, workspacePermissionModeSchema, workspaceComposerSelectionSchema, workspaceReviewPayloadSchema, workspaceCompactPayloadSchema, workspaceSteerPayloadSchema, workspaceApprovalResponseSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, recoverUncertainOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, workspaceRemixReferenceImportPayloadSchema, deliveryBuildPayloadSchema, deliveryCancelPayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { fileWritePayloadSchema, fileBinaryWritePayloadSchema, directoryCreatePayloadSchema, directoryRenamePayloadSchema, directoryDeletePayloadSchema, directoryMutationReceiptSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, gitPullPayloadSchema, gitMergeAbortPayloadSchema, parameterPatchPayloadSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, productionSessionAttemptId, reasoningEffortSchema, workspacePermissionModeSchema, workspaceComposerSelectionSchema, workspaceReviewPayloadSchema, workspaceCompactPayloadSchema, workspaceSteerPayloadSchema, workspaceApprovalResponseSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, recoverUncertainOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, workspaceRemixReferenceImportPayloadSchema, deliveryBuildPayloadSchema, deliveryCancelPayloadSchema, workspaceModelPreviewBuildSchema, workspaceModelPreviewCancelSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { closeCliCredentials, ensureCliCredentials } from '../workspaces/cli-credentials.js';
 import { artifactFormat } from '../workspaces/artifact-files.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
@@ -43,6 +43,7 @@ import { observeWorkspaceDirectories } from '../workspaces/directory-revisions.j
 import { publishAssetTransfer } from '../workspaces/asset-transfer-publish.js';
 import { AssetTransferError } from '../workspaces/asset-transfer-storage.js';
 import { runDeliveryBuild, cancelDeliveryBuild, trackDeliveryBuild, DeliveryBuildError } from '../workspaces/delivery-build.js';
+import { runModelPreviewBuild, cancelModelPreview, modelPreviewError } from '../workspaces/procedural-3d/model-preview-build.js';
 const CONVERSATION_KINDS = new Set([
     'session.create',
     'session.turn',
@@ -77,6 +78,8 @@ const LOCAL_KINDS = new Set([
     'preview.publish',
     'delivery.build',
     'delivery.cancel',
+    'model.preview',
+    'model.preview.cancel',
     'skills.update',
 ]);
 const parameterVerifications = new WeakMap();
@@ -120,7 +123,7 @@ export async function executeOperation(state, scopeKey, operation, payload, reco
             return executeScopedOperation(state, scopeKey, operation, payload, recovery);
         }, { operationId: operation.operationId, scopeKey, payload, ...(recovery ? { recovery } : {}) });
     };
-    if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'session.steer', 'preview.publish', 'delivery.build', 'delivery.cancel'].includes(operation.kind)) {
+    if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'session.steer', 'preview.publish', 'delivery.build', 'delivery.cancel', 'model.preview', 'model.preview.cancel'].includes(operation.kind)) {
         return run();
     }
     return state.journal.exclusive(operation.kind.startsWith('session.') && operation.sessionId
@@ -202,6 +205,9 @@ async function executeScopedOperation(state, scopeKey, operation, payload, recov
     if (operation.kind === 'delivery.cancel') {
         return executeDeliveryCancel(state, scopeKey, current, payload);
     }
+    if (operation.kind === 'model.preview' || operation.kind === 'model.preview.cancel') {
+        return executeModelPreview(state, scopeKey, current, payload);
+    }
     if (!state.native?.ready()) {
         return persist(state, scopeKey, transitionOperation(current, 'failed', { error: 'capability_unavailable' }));
     }
@@ -1504,6 +1510,29 @@ async function executePreviewPublish(state, scopeKey, operation) {
     }).catch(() => undefined));
     return accepted;
 }
+async function executeModelPreview(state, scopeKey, operation, payload) {
+    if (!operation.workspaceId || operation.directoryName === 'root')
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'model_preview_scope_invalid' }));
+    const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
+    if (operation.kind === 'model.preview.cancel') {
+        try {
+            const input = workspaceModelPreviewCancelSchema.parse(payload);
+            await cancelModelPreview(state, operation.workspaceId, operation.directoryName ?? 'basic', input.previewId);
+            return persist(state, scopeKey, transitionOperation(accepted, 'completed'));
+        }
+        catch (error) {
+            return persist(state, scopeKey, transitionOperation(accepted, 'failed', { error: modelPreviewError(error) }));
+        }
+    }
+    const parsed = workspaceModelPreviewBuildSchema.safeParse(payload);
+    if (!parsed.success)
+        return persist(state, scopeKey, transitionOperation(accepted, 'failed', { error: 'model_preview_invalid_request' }));
+    trackPreviewPublish(state, runModelPreviewBuild(state, accepted, parsed.data).then(async () => { await persist(state, scopeKey, transitionOperation(accepted, 'completed')); }, async (error) => {
+        const code = modelPreviewError(error);
+        await persist(state, scopeKey, transitionOperation(accepted, code === 'model_preview_process_unknown' ? 'uncertain' : code === 'model_preview_cancelled' ? 'interrupted' : 'failed', { error: code }));
+    }).catch(() => undefined));
+    return accepted;
+}
 async function executeDeliveryBuild(state, scopeKey, operation, payload) {
     const parsed = deliveryBuildPayloadSchema.safeParse(payload);
     if (!parsed.success) {

package/dist/workspace-runtime/server/http.js

@@ -47,6 +47,8 @@ import { restoreNativeSession, SessionRestoreError } from './session-restore.js'
 import { handleAssetTransferRequest } from './asset-transfers.js';
 import { readWorktreeSource, registerChatWorktree } from '../workspaces/worktrees.js';
 import { withDirectoryWrite } from './directory-access.js';
+import { readProceduralModelCandidates } from '../workspaces/procedural-3d/read-candidates.js';
+import { ModelPreviewStore } from '../workspaces/procedural-3d/model-preview-store.js';
 export async function handleRuntimeRequest(state, request, response) {
     const url = new URL(request.url ?? '/', 'http://127.0.0.1');
     const workspaceId = url.searchParams.get('workspaceId');
@@ -531,6 +533,40 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, 200, deliveryBuildDetailSchema.parse({ record, ...(report ? { report } : {}) }));
             return;
         }
+        if (['GET', 'HEAD'].includes(request.method ?? '') && url.pathname === '/runtime/model-preview-content') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId');
+            if (!workspaceId || directoryName === 'root') {
+                writeJson(response, 400, { error: 'invalid_workspace' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            try {
+                const output = await new ModelPreviewStore(state.config.stateDir, root).content(url.searchParams.get('previewId') ?? '');
+                response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': output.bytes.length,
+                    'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff', 'x-content-sha256': output.record.contentHash,
+                    'content-security-policy': "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'",
+                    'referrer-policy': 'no-referrer' });
+                response.end(request.method === 'HEAD' ? undefined : output.bytes);
+            }
+            catch {
+                writeJson(response, 404, { error: 'model_preview_unavailable' });
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/model-candidates') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId');
+            if (!workspaceId || directoryName === 'root') {
+                writeJson(response, 400, { error: 'invalid_workspace' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            writeJson(response, 200, await readProceduralModelCandidates(root, state.config.stateDir));
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/artifacts') {
             if (writeDestroyed(state, response))
                 return;

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

@@ -3,12 +3,13 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import sharp from 'sharp';
-import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, 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';
 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)}`; }
@@ -86,7 +87,8 @@ export class WorkspaceArtifactStore {
         const task = previous.catch(() => undefined).then(() => this.scan(root, source, sourcePaths, playable));
         serial.set(key, task);
         try {
-            return await task;
+            const result = await task;
+            return { ...result, list: await applyWorkspaceModelBuildStates(root, this.stateDir, result.list) };
         }
         finally {
             if (serial.get(key) === task)
@@ -214,6 +216,17 @@ export class WorkspaceArtifactStore {
             }
             catch { /* Files being written or temporarily missing are retried, never published as complete. */ }
         }
+        if (playable.modelBuild) {
+            const modelBuild = workspaceModelBuildSchema.parse(playable.modelBuild);
+            const files = await snapshotArtifactBundle(root, WORKSPACE_PLAYABLE_OUTPUT_PATH, objects);
+            const primary = files[0];
+            if (primary.sha256 !== modelBuild.outputHash || source.kind !== 'generated' || !source.operationId)
+                throw new Error('artifact_model_build_mismatch');
+            const version = { id: `version_${digest(`${modelBuild.buildOperationId}\0${modelBuild.inputHash}\0${primary.sha256}`).slice(0, 48)}`,
+                createdAt: new Date().toISOString(), path: WORKSPACE_PLAYABLE_OUTPUT_PATH, mimeType: primary.mimeType,
+                size: primary.size, sha256: primary.sha256, files, source, modelBuild };
+            await this.add(catalog, version, await this.versionKind(objects, version), objects);
+        }
         catalog.artifacts = catalog.artifacts.filter(artifact => {
             const current = artifact.versions.find(version => version.id === artifact.currentVersionId);
             return !isWorkspaceArtifactOutputVersion(current) || current.source.kind !== 'discovered' || !members.has(current.path);
@@ -267,7 +280,8 @@ export class WorkspaceArtifactStore {
         if (this.directoryName !== 'basic')
             version.directoryName = this.directoryName;
         const current = artifact.versions.find(item => item.id === artifact.currentVersionId);
-        if (kind === 'playable' && current && artifactBundleDigest(current.files) === artifactBundleDigest(version.files))
+        if (kind === 'playable' && current && artifactBundleDigest(current.files) === artifactBundleDigest(version.files) &&
+            (!version.modelBuild || sameWorkspaceModelBuild(current.modelBuild, version.modelBuild)))
             return;
         if (!artifact.versions.some(item => item.id === version.id)) {
             // Display ordering is monotonic; the original generation time stays in source.generatedAt.

package/dist/workspace-runtime/workspaces/model-build-inputs.js

@@ -0,0 +1,201 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { WORKSPACE_MODEL_BUILD_INPUTS_PATH, workspaceModelBuildInputsSchema, workspaceRelativePathSchema, workspaceModelPreviewParametersSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { checkedFile, dependencyHash } from './procedural-3d/files.js';
+import { canonicalJson } from './procedural-3d/review-contracts.js';
+import { readProceduralModelCandidates } from './procedural-3d/read-candidates.js';
+import { ModelPreviewStore } from './procedural-3d/model-preview-store.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const sorted = (files) => [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+const fileHash = (files) => digest(canonicalJson(sorted(files)));
+const MAX_INPUT_BYTES = 256 * 1024 * 1024;
+const MAX_INPUT_FILES = 512;
+function unique(files) {
+    const byPath = new Map();
+    for (const file of files) {
+        const previous = byPath.get(file.path);
+        if (previous && previous.contentHash !== file.contentHash)
+            throw new Error('model_build_input_conflict');
+        byPath.set(file.path, file);
+    }
+    if (byPath.size > 256)
+        throw new Error('model_build_input_limit');
+    return sorted([...byPath.values()]);
+}
+function resourcePaths(path, bytes) {
+    let json = bytes;
+    if (/\.glb$/i.test(path)) {
+        if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 || bytes.readUInt32LE(4) !== 2 ||
+            bytes.readUInt32LE(8) !== bytes.length || bytes.readUInt32LE(16) !== 0x4e4f534a)
+            throw new Error('model_build_resource_invalid');
+        const size = bytes.readUInt32LE(12);
+        if (size < 2 || size > 8 * 1024 * 1024 || size + 20 > bytes.length)
+            throw new Error('model_build_resource_invalid');
+        json = bytes.subarray(20, 20 + size);
+    }
+    if (json.length > 8 * 1024 * 1024)
+        throw new Error('model_build_resource_invalid');
+    let document;
+    try {
+        document = JSON.parse(json.toString('utf8').replace(/\0+$/, ''));
+    }
+    catch {
+        throw new Error('model_build_resource_invalid');
+    }
+    if (!document || document.asset?.version !== '2.0' ||
+        document.buffers !== undefined && !Array.isArray(document.buffers) || document.images !== undefined && !Array.isArray(document.images))
+        throw new Error('model_build_resource_invalid');
+    const paths = new Set([path]);
+    for (const item of [...document.buffers ?? [], ...document.images ?? []]) {
+        if (item?.uri === undefined)
+            continue;
+        if (typeof item.uri !== 'string')
+            throw new Error('model_build_resource_invalid');
+        if (item.uri.startsWith('data:'))
+            continue;
+        if (/^[a-z][a-z\d+.-]*:/i.test(item.uri) || /[\\?#]/.test(item.uri) || item.uri.startsWith('/'))
+            throw new Error('model_build_external_resource');
+        let decoded;
+        try {
+            decoded = decodeURIComponent(item.uri);
+        }
+        catch {
+            throw new Error('model_build_resource_invalid');
+        }
+        const relative = posix.normalize(posix.join(posix.dirname(path), decoded));
+        if (!workspaceRelativePathSchema.safeParse(relative).success || /^[a-z][a-z\d+.-]*:/i.test(decoded) || /[\\?#]/.test(decoded) || decoded.startsWith('/'))
+            throw new Error('model_build_resource_invalid');
+        paths.add(relative);
+    }
+    return [...paths].sort();
+}
+/** Capture declared inputs from stable files; project declarations cannot assert host verification. */
+export async function readWorkspaceModelBuildInputs(root, stateDir) {
+    let manifest;
+    try {
+        manifest = await checkedFile(root, WORKSPACE_MODEL_BUILD_INPUTS_PATH, 512 * 1024);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let declaration;
+    try {
+        declaration = workspaceModelBuildInputsSchema.parse(JSON.parse(manifest.toString('utf8')));
+    }
+    catch {
+        throw new Error('model_build_manifest_invalid');
+    }
+    const cache = new Map();
+    let bytesRead = manifest.length;
+    const read = async (path, expected) => {
+        let bytes = cache.get(path);
+        if (!bytes) {
+            if (cache.size >= MAX_INPUT_FILES || bytesRead >= MAX_INPUT_BYTES)
+                throw new Error('model_build_input_limit');
+            bytes = await checkedFile(root, path, Math.min(64 * 1024 * 1024, MAX_INPUT_BYTES - bytesRead));
+            cache.set(path, bytes);
+            bytesRead += bytes.length;
+        }
+        const contentHash = digest(bytes);
+        if (expected !== undefined && expected !== contentHash)
+            throw new Error('model_build_input_changed');
+        return { bytes, file: { path, contentHash } };
+    };
+    const candidates = declaration.models.some(model => model.source.kind === 'procedural')
+        ? await readProceduralModelCandidates(root, stateDir) : undefined;
+    const models = [];
+    for (const model of declaration.models) {
+        const inputs = [];
+        const adaptations = [];
+        for (const file of model.adaptationFiles)
+            adaptations.push((await read(file.path, file.contentHash)).file);
+        const source = model.source;
+        if (source.kind === 'resource') {
+            const primary = await read(source.path, source.contentHash);
+            if (JSON.stringify(resourcePaths(source.path, primary.bytes)) !== JSON.stringify(source.files.map(file => file.path).sort()))
+                throw new Error('model_build_resource_manifest_mismatch');
+            for (const file of source.files)
+                inputs.push((await read(file.path, file.contentHash)).file);
+        }
+        else {
+            const candidate = candidates?.candidates.find(item => item.runId === source.runId && item.candidateId === source.candidateId);
+            if (!candidate || candidate.integrity !== 'verified' || candidate.sourceHash !== source.sourceHash ||
+                candidate.dependencyHash !== source.dependencyHash)
+                throw new Error('model_build_source_unavailable');
+            const preview = await new ModelPreviewStore(stateDir, root).content(source.previewId);
+            if (preview.record.runId !== source.runId || preview.record.candidateId !== source.candidateId ||
+                preview.record.sourceHash !== source.sourceHash || preview.record.dependencyHash !== source.dependencyHash ||
+                preview.record.contentHash !== source.contentHash || preview.record.parameterHash !== source.parameterHash || !preview.record.parameters)
+                throw new Error('model_build_source_changed');
+            const prefix = `.playcraft/procedural-3d/runs/${source.runId}/candidates/${source.candidateId}/source/`;
+            for (const file of candidate.files) {
+                if (!file.path.startsWith(prefix))
+                    throw new Error('model_build_source_changed');
+                const path = file.path.slice(prefix.length);
+                if (path.startsWith('__playcraft-review/'))
+                    continue;
+                inputs.push((await read(posix.join(source.sourceRoot, path), file.contentHash)).file);
+            }
+            const parameters = await read(source.parametersPath);
+            try {
+                const values = workspaceModelPreviewParametersSchema.parse(JSON.parse(parameters.bytes.toString('utf8')));
+                if (canonicalJson(values) !== canonicalJson(preview.record.parameters))
+                    throw new Error('mismatch');
+            }
+            catch {
+                throw new Error('model_build_parameters_changed');
+            }
+            adaptations.push(parameters.file);
+        }
+        const adaptationFiles = unique(adaptations);
+        models.push({ source, adaptationFiles, adaptationHash: fileHash(adaptationFiles), inputs: unique([...inputs, ...adaptationFiles]) });
+    }
+    const manifestHash = digest(manifest);
+    return { schemaVersion: 1, manifestPath: WORKSPACE_MODEL_BUILD_INPUTS_PATH, manifestHash,
+        inputHash: digest(canonicalJson({ manifestHash, models })), hostVerified: true, behaviorValidation: 'pending', models };
+}
+/** Validate the isolated copy and later the live inputs against this build's frozen snapshot. */
+export async function verifyWorkspaceModelBuildInputs(root, snapshot) {
+    if (digest(await checkedFile(root, snapshot.manifestPath, 512 * 1024)) !== snapshot.manifestHash)
+        throw new Error('model_build_input_changed');
+    const files = unique(snapshot.models.flatMap(model => model.inputs));
+    let bytesRead = 0;
+    for (const file of files) {
+        if (bytesRead >= MAX_INPUT_BYTES)
+            throw new Error('model_build_input_limit');
+        const bytes = await checkedFile(root, file.path, Math.min(64 * 1024 * 1024, MAX_INPUT_BYTES - bytesRead));
+        bytesRead += bytes.length;
+        if (digest(bytes) !== file.contentHash)
+            throw new Error('model_build_input_changed');
+    }
+    for (const model of snapshot.models)
+        if (model.source.kind === 'procedural' &&
+            await dependencyHash(root) !== model.source.dependencyHash)
+            throw new Error('model_build_input_changed');
+}
+/** The marker makes otherwise identical HTML from different input declarations distinct artifacts. */
+export function markWorkspaceModelBuild(bytes, snapshot) {
+    const html = bytes.toString('utf8').replace(/^<!--playcraft-model-inputs:v1:[a-f0-9]{64}:[a-f0-9]{64}-->\n/, '');
+    return Buffer.from(`<!--playcraft-model-inputs:v1:${snapshot.manifestHash}:${snapshot.inputHash}-->\n${html}`);
+}
+/** A current claim is calculated for this live read, never persisted as historical truth. */
+export async function applyWorkspaceModelBuildStates(root, stateDir, list) {
+    if (!list.artifacts.some(artifact => artifact.versions.some(version => version.modelBuild)))
+        return list;
+    let current, unavailable = false;
+    try {
+        current = await readWorkspaceModelBuildInputs(root, stateDir);
+    }
+    catch (error) {
+        unavailable = error instanceof Error && /unavailable|limit|EACCES|EPERM/.test(error.message);
+    }
+    return { ...list, artifacts: list.artifacts.map(artifact => ({ ...artifact, versions: artifact.versions.map(version => version.modelBuild
+                ? { ...version, modelBuildState: unavailable ? 'unavailable' : current &&
+                        current.manifestHash === version.modelBuild.manifestHash && current.inputHash === version.modelBuild.inputHash ? 'current' : 'stale' }
+                : version) })) };
+}
+export function sameWorkspaceModelBuild(left, right) {
+    return left?.manifestHash === right?.manifestHash && left?.inputHash === right?.inputHash && left?.outputHash === right?.outputHash;
+}