@playcraft/cli 0.1.61-beta → 0.1.62-beta

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/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/procedural-3d/model-preview-build.js

@@ -0,0 +1,184 @@
+import { mkdtemp, mkdir, writeFile, lstat, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot, revisionScope } from '../registry.js';
+import { openDirectoryToDevelopment, openScratchToDevelopment } from '../directory-access.js';
+import { runDeveloperCommand } from '../developer-command.js';
+import { artifactMime } from '../artifact-files.js';
+import { checkedFile, dependencyHash, digest } from './files.js';
+import { readProceduralModelCandidates } from './read-candidates.js';
+import { createHostReviewFiles } from './review-page.js';
+import { canonicalJson, REVIEW_DIRECTORY, REVIEW_PAGE, reviewProfileSchema } from './review-contracts.js';
+import { ModelPreviewStore, MODEL_PREVIEW_MAX_BYTES } from './model-preview-store.js';
+import { recoverModelPreviewOperations } from './model-preview-recovery.js';
+import { cancelPendingDirectoryAccess } from '../../server/directory-access.js';
+const active = new WeakMap();
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export const modelPreviewError = (error) => error instanceof Error && /^model_[a-z_]+$/.test(error.message)
+    ? error.message : 'model_preview_build_failed';
+/** Parse declarative fields and require exact equality with the host's own page generator. */
+export function parseFrozenModelReview(bytes, helpers) {
+    const page = bytes.toString('utf8');
+    const string = '"(?:\\\\.|[^"\\\\])*"';
+    const match = (expression) => {
+        const value = new RegExp(expression).exec(page)?.[1];
+        if (!value)
+            throw new Error('model_preview_custom_page_unsupported');
+        return JSON.parse(value);
+    };
+    const path = match(`import \\* as factory from (${string});`);
+    const exportName = match(`const createModel = factory\\[(${string})\\];`);
+    const parameters = JSON.parse(match(`const parameters = JSON.parse\\((${string})\\);`));
+    const profile = reviewProfileSchema.parse(JSON.parse(match(`const profile = JSON.parse\\((${string})\\);`)));
+    if (!path.startsWith('/') || !/^[A-Za-z_$][A-Za-z0-9_$]{0,79}$/.test(exportName) ||
+        !parameters || typeof parameters !== 'object' || Array.isArray(parameters))
+        throw new Error('model_preview_custom_page_unsupported');
+    canonicalJson(parameters);
+    const factoryPath = path.slice(1).split('/').map(decodeURIComponent).join('/');
+    const review = { factoryPath, exportName, parameters, profile };
+    if (!createHostReviewFiles(review, helpers)[0].bytes.equals(bytes))
+        throw new Error('model_preview_custom_page_unsupported');
+    return review;
+}
+export async function cancelModelPreview(state, workspaceId, directoryName, previewId) {
+    const root = await workspaceRoot(state, workspaceId, directoryName);
+    const cancelled = await new ModelPreviewStore(state.config.stateDir, root).cancel(previewId);
+    const running = active.get(state)?.get(previewId);
+    if (cancelled && running && running.workspaceId === workspaceId && running.directoryName === directoryName)
+        running.controller.abort();
+    else if (cancelled) {
+        const storedTarget = state.journal.listOperations().find(item => (item.operation.gatewayOperationId ?? item.operation.operationId) === previewId);
+        const operation = storedTarget?.operation;
+        if (operation && operation.workspaceId === workspaceId && (operation.directoryName ?? 'basic') === directoryName) {
+            if (operation.status === 'queued') {
+                await cancelPendingDirectoryAccess(state, `operation:${operation.operationId}`);
+                const queued = state.journal.getOperationById(operation.operationId);
+                const stored = state.journal.listOperations().find(item => item.operation.operationId === operation.operationId);
+                if (queued?.status === 'queued' && stored) {
+                    await state.journal.putOperation(stored.scopeKey, transitionOperation(queued, 'interrupted', { error: 'model_preview_cancelled' }));
+                    await state.journal.deleteDeferredDirectoryOperation(operation.operationId);
+                    return;
+                }
+            }
+            await recoverModelPreviewOperations(state, { identityMatches: operation.generation === state.config.generation,
+                ...(process.env.PLAYCRAFT_LAUNCHER_SOCKET ? { launcherSocket: process.env.PLAYCRAFT_LAUNCHER_SOCKET } : {}) }, previewId);
+            if (state.journal.getOperationById(operation.operationId)?.status === 'uncertain')
+                throw new Error('model_preview_process_unknown');
+        }
+    }
+}
+export async function runModelPreviewBuild(state, operation, input, options = {}) {
+    if (!operation.workspaceId || operation.directoryName === 'root')
+        throw new Error('model_preview_scope_invalid');
+    const directoryName = operation.directoryName ?? 'basic';
+    const root = await workspaceRoot(state, operation.workspaceId, directoryName);
+    const store = new ModelPreviewStore(state.config.stateDir, root), previewId = operation.gatewayOperationId ?? operation.operationId;
+    if (await store.cancelled(previewId))
+        throw new Error('model_preview_cancelled');
+    const previous = await store.read(previewId);
+    if (previous) {
+        if (previous.runId !== input.runId || previous.candidateId !== input.candidateId || previous.sourceHash !== input.sourceHash ||
+            previous.dependencyHash !== input.dependencyHash || canonicalJson(previous.parameterOverrides ?? {}) !== canonicalJson(input.parameterOverrides ?? {}))
+            throw new Error('model_preview_binding_changed');
+        if (previous.status === 'ready') {
+            await store.content(previewId);
+            return;
+        }
+        throw new Error(previous.status === 'cancelled' ? 'model_preview_cancelled' : 'model_preview_recovery_required');
+    }
+    const listing = await readProceduralModelCandidates(root, state.config.stateDir);
+    const candidate = listing.candidates.find(item => item.runId === input.runId && item.candidateId === input.candidateId);
+    if (!candidate || candidate.integrity !== 'verified')
+        throw new Error('model_preview_candidate_unavailable');
+    if (candidate.sourceHash !== input.sourceHash || candidate.dependencyHash !== input.dependencyHash)
+        throw new Error('model_preview_binding_changed');
+    const prefix = `.playcraft/procedural-3d/runs/${input.runId}/candidates/${input.candidateId}/source/`;
+    if (candidate.preview.kind !== 'scene-preview' || candidate.preview.entryPath !== `${prefix}${REVIEW_PAGE}`)
+        throw new Error('model_preview_custom_page_unsupported');
+    const scene = await checkedFile(root, `${prefix}${REVIEW_DIRECTORY}/review-scene.mjs`);
+    const profile = await checkedFile(root, `${prefix}${REVIEW_DIRECTORY}/review-profile.mjs`);
+    const review = parseFrozenModelReview(await checkedFile(root, `${prefix}${REVIEW_PAGE}`), { scene, profile });
+    const parameters = { ...(review.parameters ?? {}) };
+    for (const [key, value] of Object.entries(input.parameterOverrides ?? {})) {
+        if (!Object.hasOwn(parameters, key) || typeof parameters[key] !== typeof value)
+            throw new Error('model_preview_parameter_unsupported');
+        parameters[key] = value;
+    }
+    const publicParameters = Object.fromEntries(Object.entries(parameters).filter(([, value]) => typeof value === 'boolean' || typeof value === 'string' && value.length <= 256 || typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= 100000)
+        .filter(([key]) => /^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key) && !['__proto__', 'prototype', 'constructor'].includes(key)).slice(0, 64));
+    if (!candidate.files.some(file => file.path === `${prefix}${review.factoryPath}` && file.source))
+        throw new Error('model_preview_factory_missing');
+    const record = { previewId, root, ...input, parameters: publicParameters,
+        parameterHash: digest(canonicalJson(publicParameters)), status: 'running', createdAt: new Date().toISOString() };
+    await store.write(record);
+    const controller = new AbortController(), known = active.get(state) ?? new Map();
+    active.set(state, known);
+    known.set(previewId, { workspaceId: operation.workspaceId, directoryName, controller });
+    let scratch, stopped = true;
+    const writeId = `model-preview-${previewId}`;
+    try {
+        if (await store.cancelled(previewId))
+            controller.abort();
+        if (controller.signal.aborted)
+            throw new Error('model_preview_cancelled');
+        scratch = await mkdtemp(join(tmpdir(), 'playcraft-model-preview-'));
+        await openScratchToDevelopment(scratch, (await lstat(root)).gid);
+        const sourceRoot = join(scratch, 'source');
+        await mkdir(sourceRoot);
+        const resources = {};
+        for (const file of candidate.files) {
+            const path = file.path.slice(prefix.length), bytes = await checkedFile(root, file.path);
+            if (digest(bytes) !== file.contentHash)
+                throw new Error('model_preview_binding_changed');
+            const target = join(sourceRoot, path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, bytes);
+            if (!/\.[cm]?[jt]sx?$|\.html$/i.test(path))
+                resources[path] = `data:${artifactMime(path)};base64,${bytes.toString('base64')}`;
+        }
+        const outputPath = join(scratch, 'output/index.html');
+        const config = { projectRoot: root, sourceRoot, outputPath,
+            factoryPath: review.factoryPath, exportName: review.exportName, parameters, profile: review.profile,
+            resources, previewId, runId: input.runId, candidateId: input.candidateId, sourceHash: input.sourceHash };
+        const configPath = join(scratch, 'input.json');
+        await writeFile(configPath, JSON.stringify(config));
+        await openDirectoryToDevelopment(scratch, (await lstat(root)).gid);
+        const worker = options.workerPath ?? fileURLToPath(new URL('./model-preview-worker.js', import.meta.url));
+        const outcome = await runDeveloperCommand(state, { processId: writeId, cwd: scratch,
+            command: `${quote(process.execPath)} ${quote(worker)} ${quote(configPath)}`, timeoutMs: 120_000, signal: controller.signal,
+            onOutput: () => undefined, onStarted: async (identity) => {
+                stopped = false;
+                await state.journal.putManagedWrite({ writeId, workspaceId: revisionScope(state, operation.workspaceId, directoryName) ?? 'single',
+                    source: 'manual', directoryAccessMode: 'exclusive', startedAt: new Date().toISOString(), pid: identity.pid,
+                    ...(identity.launcher ? { executionMode: 'launcher', launcher: identity.launcher, runtimeEpoch: state.runtimeEpoch } : { executionMode: 'local' }) });
+            } });
+        stopped = outcome.code !== undefined;
+        if (!stopped)
+            throw new Error('model_preview_process_unknown');
+        const managed = state.journal.listManagedWrites().find(item => item.writeId === writeId);
+        if (managed)
+            await state.journal.putManagedWrite({ ...managed, stoppedAt: new Date().toISOString() });
+        if (outcome.canceled || await store.cancelled(previewId))
+            throw new Error('model_preview_cancelled');
+        if (outcome.timedOut)
+            throw new Error('model_preview_timeout');
+        if (outcome.code !== 0)
+            throw new Error('model_preview_build_failed');
+        if (await dependencyHash(root) !== input.dependencyHash)
+            throw new Error('model_preview_binding_changed');
+        const bytes = await checkedFile(scratch, 'output/index.html', MODEL_PREVIEW_MAX_BYTES);
+        await store.publish(record, bytes);
+    }
+    catch (error) {
+        const code = stopped ? modelPreviewError(error) : 'model_preview_process_unknown';
+        await store.write({ ...record, status: code === 'model_preview_cancelled' ? 'cancelled' : 'failed', error: code });
+        throw new Error(code);
+    }
+    finally {
+        known.delete(previewId);
+        if (scratch && stopped)
+            await rm(scratch, { recursive: true, force: true });
+    }
+}

package/dist/workspace-runtime/workspaces/procedural-3d/model-preview-recovery.js

@@ -0,0 +1,77 @@
+import { transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+import { stopLauncherExecution } from '../../codex/launcher-client.js';
+import { reconcileDirectoryAccess } from '../../server/directory-access.js';
+import { workspaceRoot } from '../registry.js';
+import { ModelPreviewStore } from './model-preview-store.js';
+function absent(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+async function stopRecoveredWriter(writer, recovery) {
+    if (writer.stoppedAt)
+        return true;
+    if (recovery.confirmStopped)
+        return recovery.confirmStopped(writer);
+    if (writer.executionMode === 'launcher') {
+        if (!recovery.identityMatches || !recovery.launcherSocket || !writer.launcher ||
+            writer.launcher.processId !== writer.writeId || writer.launcher.runtimeEpoch !== writer.runtimeEpoch)
+            return false;
+        if (recovery.previousRuntimeEpoch !== undefined && recovery.runtimeEpoch !== undefined &&
+            recovery.runtimeEpoch > recovery.previousRuntimeEpoch && writer.launcher.runtimeEpoch < recovery.runtimeEpoch)
+            return true;
+        try {
+            await stopLauncherExecution(recovery.launcherSocket, writer.launcher);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // A recycled local process id is not authority to signal a process after restart.
+    return Boolean(writer.pid && absent(-writer.pid) && absent(writer.pid));
+}
+/** Recovered work is observed/stopped, never rebuilt or re-inferred automatically. */
+export async function recoverModelPreviewOperations(state, recovery, onlyId) {
+    for (const { scopeKey, operation: snapshot } of state.journal.listOperations()) {
+        if (snapshot.kind !== 'model.preview' || onlyId && (snapshot.gatewayOperationId ?? snapshot.operationId) !== onlyId ||
+            !['dispatched', 'accepted', 'uncertain'].includes(snapshot.status))
+            continue;
+        const operation = state.journal.getOperationById(snapshot.operationId) ?? snapshot;
+        const previewId = operation.gatewayOperationId ?? operation.operationId;
+        if (!['dispatched', 'accepted', 'uncertain'].includes(operation.status))
+            continue;
+        const writer = state.journal.listManagedWrites().find(item => item.writeId === `model-preview-${previewId}`);
+        const stopped = writer ? await stopRecoveredWriter(writer, recovery) : false;
+        let store, ready = false;
+        try {
+            const root = await workspaceRoot(state, operation.workspaceId, operation.directoryName ?? 'basic');
+            store = new ModelPreviewStore(state.config.stateDir, root);
+            ready = (await store.read(previewId))?.status === 'ready';
+            if (ready)
+                await store.content(previewId);
+        }
+        catch {
+            ready = false;
+        }
+        const current = state.journal.getOperationById(operation.operationId) ?? operation;
+        if (!['dispatched', 'accepted', 'uncertain'].includes(current.status))
+            continue;
+        if (!stopped) {
+            await state.journal.putOperation(scopeKey, transitionOperation(current, 'uncertain', { error: 'model_preview_process_unknown' }));
+            continue;
+        }
+        if (writer && !writer.stoppedAt)
+            await state.journal.putManagedWrite({ ...writer, stoppedAt: new Date().toISOString() });
+        const record = await store?.read(previewId).catch(() => undefined);
+        if (record && !ready)
+            await store.write({ ...record,
+                status: await store.cancelled(previewId) ? 'cancelled' : 'failed', error: 'model_preview_interrupted' }).catch(() => undefined);
+        await state.journal.putOperation(scopeKey, transitionOperation(current, ready ? 'completed' : 'interrupted', ready ? {} : { error: 'model_preview_interrupted' }));
+    }
+    reconcileDirectoryAccess(state);
+}

package/dist/workspace-runtime/workspaces/procedural-3d/model-preview-store.js

@@ -0,0 +1,170 @@
+import { readdir, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { PREVIEW_HTML_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+import { checkedFile, digest, writeControlJson } from './files.js';
+export const MODEL_PREVIEW_MAX_BYTES = PREVIEW_HTML_MAX_BYTES;
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const parameterKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,63}$/)
+    .refine(value => !['__proto__', 'prototype', 'constructor'].includes(value));
+const parameters = z.unknown().superRefine((value, context) => {
+    if (value && typeof value === 'object' && Object.keys(value).some(key => !parameterKey.safeParse(key).success))
+        context.addIssue({ code: 'custom', message: 'invalid_model_parameter_key' });
+}).pipe(z.record(parameterKey, z.union([z.string().max(256), z.number().finite().min(-100000).max(100000), z.boolean()]))
+    .refine(value => Object.keys(value).length <= 64));
+const recordSchema = z.object({ previewId: z.string().uuid(), root: z.string(), runId: z.string().uuid(),
+    candidateId: z.string().uuid(), sourceHash: hash, dependencyHash: hash,
+    status: z.enum(['running', 'ready', 'failed', 'cancelled']), createdAt: z.string().datetime(),
+    contentHash: hash.optional(), error: z.string().regex(/^[a-z_]+$/).optional(),
+    parameters: parameters.optional(), parameterHash: hash.optional(),
+    parameterOverrides: parameters.optional() }).strict().superRefine((record, context) => {
+    const normalizedParameters = record.parameters && JSON.stringify(Object.fromEntries(Object.keys(record.parameters).sort().map(key => [key, record.parameters[key]])));
+    if (record.status === 'ready' && !record.contentHash || Boolean(record.parameters) !== Boolean(record.parameterHash) ||
+        normalizedParameters && digest(normalizedParameters) !== record.parameterHash)
+        context.addIssue({ code: 'custom', message: 'model_preview_receipt_invalid' });
+});
+const transactions = new Map();
+async function exclusive(key, action) {
+    const previous = transactions.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise(done => { release = done; });
+    transactions.set(key, current);
+    await previous;
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (transactions.get(key) === current)
+            transactions.delete(key);
+    }
+}
+export class ModelPreviewStore {
+    stateDir;
+    root;
+    relative;
+    constructor(stateDir, root) {
+        this.stateDir = stateDir;
+        this.root = root;
+        this.relative = `model-previews/${digest(root)}`;
+    }
+    async cancel(previewId) {
+        if (!z.string().uuid().safeParse(previewId).success)
+            throw new Error('model_preview_invalid_id');
+        return exclusive(join(this.stateDir, this.relative, previewId), async () => {
+            if ((await this.read(previewId))?.status === 'ready')
+                return false;
+            await writeControlJson(join(this.stateDir, this.relative, 'cancelled', `${previewId}.json`), { previewId, root: this.root });
+            return true;
+        });
+    }
+    async cancelled(previewId) {
+        if (!z.string().uuid().safeParse(previewId).success)
+            throw new Error('model_preview_invalid_id');
+        try {
+            const receipt = JSON.parse((await checkedFile(this.stateDir, `${this.relative}/cancelled/${previewId}.json`, 4096)).toString('utf8'));
+            if (receipt.previewId !== previewId || receipt.root !== this.root)
+                throw new Error('model_preview_scope_mismatch');
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async write(record) {
+        recordSchema.parse(record);
+        if (record.root !== this.root)
+            throw new Error('model_preview_scope_mismatch');
+        if (record.status === 'ready') {
+            const index = `${record.createdAt.replace(/\D/g, '')}-${record.previewId}.json`;
+            await writeControlJson(join(this.stateDir, this.relative, 'bindings', this.binding(record), index), { previewId: record.previewId });
+        }
+        await writeControlJson(join(this.stateDir, this.relative, 'records', `${record.previewId}.json`), record);
+    }
+    binding(input) {
+        return digest(JSON.stringify([input.runId, input.candidateId, input.sourceHash, input.dependencyHash]));
+    }
+    async read(previewId) {
+        if (!z.string().uuid().safeParse(previewId).success)
+            throw new Error('model_preview_invalid_id');
+        try {
+            const record = recordSchema.parse(JSON.parse((await checkedFile(this.stateDir, `${this.relative}/records/${previewId}.json`, 16 * 1024)).toString('utf8')));
+            if (record.root !== this.root || record.previewId !== previewId)
+                throw new Error('model_preview_scope_mismatch');
+            return record;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async publish(record, bytes) {
+        return exclusive(join(this.stateDir, this.relative, record.previewId), async () => {
+            if (await this.cancelled(record.previewId))
+                throw new Error('model_preview_cancelled');
+            if (!bytes.length || bytes.length > MODEL_PREVIEW_MAX_BYTES)
+                throw new Error('model_preview_size_limit');
+            const previous = await this.read(record.previewId);
+            if (previous?.status === 'ready') {
+                if (previous.runId !== record.runId || previous.candidateId !== record.candidateId || previous.sourceHash !== record.sourceHash ||
+                    previous.dependencyHash !== record.dependencyHash || previous.contentHash !== digest(bytes))
+                    throw new Error('model_preview_binding_changed');
+                return;
+            }
+            const directory = join(this.stateDir, this.relative, 'content');
+            await mkdir(directory, { recursive: true, mode: 0o700 }); // private
+            const target = join(directory, `${record.previewId}.html`), temporary = `${target}.${randomUUID()}.pending`;
+            try {
+                await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 }); // private
+                await rename(temporary, target);
+                await this.write({ ...record, status: 'ready', contentHash: digest(bytes) });
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        });
+    }
+    async content(previewId) {
+        const record = await this.read(previewId);
+        if (!record || record.status !== 'ready' || !record.contentHash)
+            throw new Error('model_preview_not_ready');
+        if (await this.cancelled(previewId))
+            throw new Error('model_preview_cancelled');
+        const bytes = await checkedFile(this.stateDir, `${this.relative}/content/${previewId}.html`, MODEL_PREVIEW_MAX_BYTES);
+        if (digest(bytes) !== record.contentHash)
+            throw new Error('model_preview_content_changed');
+        return { bytes, record };
+    }
+    async latest(input) {
+        const records = await this.versions(input);
+        if (records[0])
+            return records[0];
+        return undefined;
+    }
+    async versions(input) {
+        let names;
+        try {
+            names = (await readdir(join(this.stateDir, this.relative, 'bindings', this.binding(input))))
+                .filter(name => /^\d{17}-[a-f0-9-]{36}\.json$/i.test(name)).sort().reverse().slice(0, 32);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const records = [];
+        for (const name of names) {
+            const record = await this.read(name.slice(18, -5));
+            if (record && record.runId === input.runId && record.candidateId === input.candidateId &&
+                record.sourceHash === input.sourceHash && record.dependencyHash === input.dependencyHash && record.status === 'ready' && record.contentHash &&
+                !await this.cancelled(record.previewId))
+                records.push(record);
+        }
+        records.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+        return records.slice(0, 32);
+    }
+}

package/dist/workspace-runtime/workspaces/procedural-3d/model-preview-worker.js

@@ -0,0 +1,85 @@
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';
+import { PREVIEW_HTML_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+/** Bundles only the frozen factory and the installed Three.js; no project config or plugin runs. */
+export async function buildModelPreviewHtml(input) {
+    const sourceRoot = await realpath(input.sourceRoot);
+    const project = createRequire(join(input.projectRoot, 'package.json'));
+    const vite = await import(pathToFileURL(project.resolve('vite')).href);
+    const threeEntry = project.resolve('three');
+    const threeRoot = resolve(dirname(threeEntry), '..');
+    const literal = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+    const entry = join(sourceRoot, '__model-preview-entry.mjs');
+    const code = `import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import * as factory from ${literal(`./${input.factoryPath}`)};
+const binding=${literal({ previewId: input.previewId, runId: input.runId, candidateId: input.candidateId, sourceHash: input.sourceHash })};
+const profile=${literal(input.profile)}, resources=${literal(input.resources)};
+let parameters=${literal(input.parameters)}, model, renderer, scene, camera, controls, stopped=false, revision=0,lastState,pendingParameters,rebuilding=false,resourceHung=false,renderFailed=false;
+let viewportWidth=0,viewportHeight=0,viewportRatio=0,viewportRevision=0,renderReadyRevision=0,resumeFrames=0,viewportObserver;
+const validKey=key=>/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key)&&!['__proto__','prototype','constructor'].includes(key);
+const primitiveParameters=()=>Object.fromEntries(Object.entries(parameters).filter(([key,value])=>validKey(key)&&(typeof value==='boolean'||typeof value==='string'&&value.length<=256||typeof value==='number'&&Number.isFinite(value)&&Math.abs(value)<=100000)).slice(0,64));
+const capabilities=['orbit','fixed-views',...(Object.keys(primitiveParameters()).length?['factory-parameters']:[])];
+const send=state=>{lastState=state;parent.postMessage({type:'playcraft:model-preview',schemaVersion:1,...binding,state,capabilities,parameters:primitiveParameters()},'*');};
+const syncViewport=()=>{if(stopped)return false;const width=Math.floor(document.documentElement?.clientWidth||innerWidth||0),height=Math.floor(document.documentElement?.clientHeight||innerHeight||0);if(!Number.isFinite(width)||!Number.isFinite(height)||width<1||height<1){resumeFrames=0;if(lastState==='ready')send('loading');return false;}const ratio=Math.min(devicePixelRatio||1,2),canvas=renderer.domElement,box=canvas.getBoundingClientRect?.();if(width!==viewportWidth||height!==viewportHeight||ratio!==viewportRatio||canvas.width!==Math.floor(width*ratio)||canvas.height!==Math.floor(height*ratio)||box&&(box.width<1||box.height<1)){renderer.setPixelRatio(ratio);renderer.setSize(width,height);camera.aspect=width/height;camera.updateProjectionMatrix();viewportWidth=width;viewportHeight=height;viewportRatio=ratio;viewportRevision++;resumeFrames=0;}const actual=canvas.getBoundingClientRect?.(),positive=canvas.width>0&&canvas.height>0&&(!actual||actual.width>0&&actual.height>0);if(!positive){resumeFrames=0;if(lastState==='ready')send('loading');}return positive;};
+const drawFrame=()=>{if(renderFailed)throw new Error('model_preview_frame_failed');if(!syncViewport())return false;try{const context=renderer.getContext();if(context.isContextLost())throw new Error('model_preview_context_lost');controls.update();renderer.render(scene,camera);if(renderFailed||context.isContextLost()||context.getError()!==context.NO_ERROR)throw new Error('model_preview_frame_failed');return renderer.domElement.width>0&&renderer.domElement.height>0;}catch(error){renderFailed=true;throw error;}};
+const waitForVisibleFrames=async current=>{let frames=0,sizeRevision=-1;while(!stopped&&current===revision&&!pendingParameters){await new Promise(resolve=>requestAnimationFrame(resolve));if(stopped||current!==revision||pendingParameters)return false;if(renderer.getContext().isContextLost())throw new Error('model_preview_context_lost');if(!drawFrame()){frames=0;continue;}if(renderer.info.render.calls<1)throw new Error('model_preview_empty_frame');if(sizeRevision!==viewportRevision){sizeRevision=viewportRevision;frames=0;}if(++frames>=2)return true;}return false;};
+const disposeModel=()=>{if(!model)return;const owned=new Set();model.traverse(o=>{if(o.geometry)owned.add(o.geometry);for(const m of [o.material].flat().filter(Boolean)){owned.add(m);for(const v of Object.values(m))if(v?.isTexture)owned.add(v);}});for(const resource of owned)resource.dispose();scene.remove(model);model=undefined;};
+const rebuildOnce=async()=>{const current=++revision;disposeModel();let loading=false,loadSettled=false,loadFailed=false,done,failed;const ready=new Promise((resolve,reject)=>{done=resolve;failed=reject;});void ready.catch(()=>{});
+const manager=THREE.DefaultLoadingManager;manager.setURLModifier(url=>{if(url.startsWith('data:'))return url;const key=decodeURIComponent(url).replace(/^\\.?\\//,'').split('?')[0];if(!Object.hasOwn(resources,key))throw new Error('model_preview_resource_unavailable');return resources[key];});
+manager.onStart=()=>{loading=true;};manager.onLoad=()=>{loadSettled=true;loadFailed?failed(new Error('model_preview_resource_failed')):done();};manager.onError=()=>{loadFailed=true;};
+try{const create=factory[${literal(input.exportName)}];if(typeof create!=='function')throw new Error('model_preview_factory_missing');model=await create(parameters);if(!model?.isObject3D)throw new Error('model_preview_model_invalid');if(stopped){disposeModel();return;}scene.add(model);model.updateMatrixWorld(true);if(new THREE.Box3().setFromObject(model).isEmpty())throw new Error('model_preview_model_empty');if(!loading){loadSettled=true;done();}let timeout;try{await Promise.race([ready,new Promise((_,reject)=>{timeout=setTimeout(()=>{resourceHung=true;reject(new Error('model_preview_resource_timeout'));},30000);})]);}finally{clearTimeout(timeout);}
+if(stopped||current!==revision||pendingParameters)return;renderReadyRevision=current;if(await waitForVisibleFrames(current)&&!stopped&&current===revision&&!pendingParameters)send('ready');}catch(error){if(loading&&!loadSettled)resourceHung=true;throw error;}};
+const queueRebuild=next=>{if(stopped||resourceHung||renderFailed)return;pendingParameters=structuredClone(next);if(rebuilding)return;rebuilding=true;void(async()=>{while(pendingParameters&&!stopped&&!resourceHung&&!renderFailed){parameters=pendingParameters;pendingParameters=undefined;send('loading');try{await rebuildOnce();}catch{if(!stopped)send('error');}}})().finally(()=>{rebuilding=false;});};
+try{scene=new THREE.Scene();scene.background=new THREE.Color(profile.background);camera=new THREE.PerspectiveCamera(profile.fovDegrees,1,profile.near,profile.far);camera.position.fromArray(profile.views.hero);renderer=new THREE.WebGLRenderer({antialias:true});renderer.debug.checkShaderErrors=true;renderer.debug.onShaderError=()=>{renderFailed=true;renderReadyRevision=0;if(lastState!=='error')send('error');};renderer.outputColorSpace=THREE.SRGBColorSpace;renderer.toneMapping=THREE.ACESFilmicToneMapping;document.body.append(renderer.domElement);controls=new OrbitControls(camera,renderer.domElement);controls.target.fromArray(profile.target);controls.update();scene.add(new THREE.HemisphereLight(0xffffff,0x6b6a68,2));const light=new THREE.DirectionalLight(0xffffff,3);light.position.fromArray(profile.keyLightPosition);scene.add(light);syncViewport();renderer.setAnimationLoop(()=>{if(stopped||renderFailed)return;try{if(renderer.getContext().isContextLost())throw new Error('model_preview_context_lost');if(!drawFrame())return;if(!rebuilding&&renderReadyRevision===revision&&!pendingParameters&&!resourceHung&&lastState==='loading'&&renderer.info.render.calls>0){if(++resumeFrames>=2)send('ready');}else resumeFrames=0;}catch{renderFailed=true;renderReadyRevision=0;if(lastState!=='error')send('error');}});
+addEventListener('resize',syncViewport);if(typeof ResizeObserver==='function'){viewportObserver=new ResizeObserver(syncViewport);viewportObserver.observe(document.documentElement);}
+addEventListener('message',event=>{const m=event.data;if(event.source!==parent||!m||m.schemaVersion!==1||m.runId!==binding.runId||m.candidateId!==binding.candidateId||m.previewId!==binding.previewId||m.sourceHash!==binding.sourceHash)return;if(m.type==='playcraft:model-preview:status'){if(lastState)send(lastState);return;}if(m.type!=='playcraft:model-preview-command')return;if(m.action==='view'&&Object.hasOwn(profile.views,m.view)){camera.position.fromArray(profile.views[m.view]);controls.target.fromArray(profile.target);controls.update();}if(m.action==='parameters'&&m.parameters&&typeof m.parameters==='object'&&!Array.isArray(m.parameters)){const next={...(pendingParameters??parameters)};for(const [key,value]of Object.entries(m.parameters)){if(!validKey(key)||!Object.hasOwn(parameters,key)||!['string','number','boolean'].includes(typeof value)||typeof value!==typeof parameters[key]||typeof value==='number'&&(!Number.isFinite(value)||Math.abs(value)>100000)||typeof value==='string'&&value.length>256)return;next[key]=value;}queueRebuild(next);}});
+addEventListener('pagehide',()=>{stopped=true;revision++;viewportObserver?.disconnect();renderer.setAnimationLoop(null);controls.dispose();disposeModel();renderer.dispose();},{once:true});
+Object.defineProperty(window,'__PLAYCRAFT_MODEL_PREVIEW__',{value:Object.freeze({...binding,capabilities}),writable:false});queueRebuild(parameters);
+}catch{send('error');}`;
+    await writeFile(entry, code);
+    const allowed = (path) => {
+        const candidate = resolve(path);
+        return [sourceRoot, threeRoot].some(root => { const value = relative(resolve(root), candidate); return value === '' || !value.startsWith('..') && !value.startsWith('/'); });
+    };
+    const built = await vite.build({
+        configFile: false, envFile: false, publicDir: false, root: sourceRoot, logLevel: 'silent',
+        cacheDir: join(sourceRoot, '.vite-cache'),
+        resolve: { alias: [{ find: /^three$/, replacement: join(threeRoot, 'build/three.module.js') },
+                { find: /^three\/addons\//, replacement: `${threeRoot}/examples/jsm/` }] },
+        plugins: [{ name: 'playcraft-model-preview-boundary', enforce: 'pre', resolveId(id, importer) {
+                    if (id.startsWith('\0') || id === 'three' || id.startsWith('three/addons/'))
+                        return null;
+                    if (id.startsWith('.') && importer && allowed(resolve(dirname(importer), id)))
+                        return null;
+                    if (id.startsWith('/') && allowed(id))
+                        return null;
+                    throw new Error('model_preview_import_denied');
+                } }],
+        build: { write: false, minify: false, sourcemap: false, emptyOutDir: false,
+            rollupOptions: { input: entry, output: { format: 'iife', inlineDynamicImports: true } } },
+    });
+    const output = (Array.isArray(built) ? built[0] : built).output;
+    if (output.length !== 1 || output[0].type !== 'chunk')
+        throw new Error('model_preview_bundle_invalid');
+    const javascript = output[0].code.replace(/<\/script/gi, '\\u003c/script');
+    return Buffer.from(`<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'; worker-src 'none'; base-uri 'none'; form-action 'none'"><meta name="viewport" content="width=device-width,initial-scale=1"><style>html,body{margin:0;width:100%;height:100%;overflow:hidden}canvas{display:block;touch-action:none}</style></head><body><script>${javascript}</script></body></html>`);
+}
+async function main() {
+    const path = process.argv[2];
+    if (!path)
+        throw new Error('model_preview_input_missing');
+    const raw = await readFile(path);
+    if (raw.length > 96 * 1024 * 1024)
+        throw new Error('model_preview_size_limit');
+    const input = JSON.parse(raw.toString('utf8'));
+    const bytes = await buildModelPreviewHtml(input);
+    if (bytes.length > PREVIEW_HTML_MAX_BYTES)
+        throw new Error('model_preview_size_limit');
+    await mkdir(dirname(input.outputPath), { recursive: true });
+    await writeFile(input.outputPath, bytes, { flag: 'wx' });
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    main().catch(() => { process.stderr.write('model_preview_build_failed\n'); process.exitCode = 1; });

package/dist/workspace-runtime/workspaces/procedural-3d/read-candidates.js

@@ -0,0 +1,219 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { workspaceModelCandidateListSchema, workspaceModelCandidateSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { checkedFile, dependencyHash, digest, relativeFile } from './files.js';
+import { ModelPreviewStore } from './model-preview-store.js';
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const fileSchema = z.object({ path: z.string().refine(value => {
+        try {
+            relativeFile(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }), hash });
+const candidateSchema = z.object({ id: z.string().uuid(), files: z.array(fileSchema).min(1).max(256),
+    sourcePaths: z.array(z.string()).min(1).max(128), sourceHash: hash, dependencyHash: hash,
+    pagePath: z.string(), specHash: hash, passId: z.string().min(1).max(128),
+    captures: z.array(fileSchema.extend({ view: z.string().min(1).max(64) })).max(16).optional(),
+    hostReview: z.object({ profileHash: hash }).optional(),
+    review: z.object({ decision: z.enum(['accept', 'revise']), sourceHash: hash }).optional(),
+    adoptedPath: z.string().optional() });
+const runSchema = z.object({ schemaVersion: z.literal(1), runId: z.string().uuid(),
+    revision: z.number().int().nonnegative(), root: z.string(), artifactHash: hash,
+    referenceHash: hash, referencePath: z.string(), candidates: z.array(z.unknown()) });
+const MAX_RUNS = 64;
+const MAX_CANDIDATES = 128;
+const MAX_BYTES = 256 * 1024 * 1024;
+/** Read control-owned snapshots without invoking the Skill or changing a completed run. */
+export async function readProceduralModelCandidates(root, stateDir) {
+    const result = { schemaVersion: 1, candidates: [], diagnostics: [],
+        truncated: false, scannedAt: new Date().toISOString() };
+    const controlRelative = `procedural-3d/${digest(root)}`;
+    const controlDirectory = join(stateDir, controlRelative);
+    const diagnose = (code, runId, candidateId) => {
+        if (result.diagnostics.length < 256)
+            result.diagnostics.push({ code, ...(runId ? { runId } : {}), ...(candidateId ? { candidateId } : {}) });
+        else
+            result.truncated = true;
+    };
+    let names;
+    try {
+        const info = await lstat(controlDirectory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error('model_candidates_control_invalid');
+        names = (await readdir(controlDirectory)).filter(name => /^[a-f0-9-]{36}\.json$/i.test(name)).sort();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            diagnose('model_candidates_control_unavailable');
+        return result;
+    }
+    if (names.length > MAX_RUNS) {
+        result.truncated = true;
+        diagnose('model_candidates_run_limit');
+    }
+    let inspectedBytes = 0;
+    let inspectedCandidates = 0;
+    const seenCandidates = new Set();
+    const readBounded = async (base, path) => {
+        if (inspectedBytes >= MAX_BYTES)
+            throw new Error('model_candidates_byte_limit');
+        const bytes = await checkedFile(base, path, Math.min(16 * 1024 * 1024, MAX_BYTES - inspectedBytes));
+        inspectedBytes += bytes.length;
+        return bytes;
+    };
+    let currentDependencyHash;
+    try {
+        currentDependencyHash = await dependencyHash(root);
+    }
+    catch { /* Each candidate remains visible with a diagnostic. */ }
+    for (const name of names.slice(0, MAX_RUNS)) {
+        const runId = name.slice(0, -5);
+        if (!z.string().uuid().safeParse(runId).success) {
+            diagnose('model_candidates_run_invalid');
+            continue;
+        }
+        let run;
+        try {
+            run = runSchema.parse(JSON.parse((await checkedFile(stateDir, `${controlRelative}/${name}`, 4 * 1024 * 1024)).toString('utf8')));
+            if (run.root !== root || run.runId !== runId)
+                throw new Error('model_candidates_scope_mismatch');
+        }
+        catch {
+            diagnose('model_candidates_run_invalid', runId);
+            continue;
+        }
+        const jobRelative = `.playcraft/procedural-3d/runs/${runId}`;
+        const jobRoot = join(root, jobRelative);
+        let referenceVerified = false;
+        try {
+            referenceVerified = digest(await readBounded(jobRoot, run.referencePath)) === run.referenceHash;
+        }
+        catch { /* Reported against every affected candidate, without exposing filesystem errors. */ }
+        for (const raw of run.candidates) {
+            if (inspectedCandidates++ >= MAX_CANDIDATES) {
+                result.truncated = true;
+                diagnose('model_candidates_candidate_limit', runId);
+                break;
+            }
+            if (result.candidates.length >= MAX_CANDIDATES) {
+                result.truncated = true;
+                diagnose('model_candidates_candidate_limit', runId);
+                break;
+            }
+            const parsed = candidateSchema.safeParse(raw);
+            if (!parsed.success) {
+                diagnose('model_candidates_candidate_invalid', runId);
+                continue;
+            }
+            const candidate = parsed.data;
+            if (seenCandidates.has(`${runId}:${candidate.id}`)) {
+                diagnose('model_candidates_candidate_duplicate', runId, candidate.id);
+                continue;
+            }
+            seenCandidates.add(`${runId}:${candidate.id}`);
+            const candidatePrefix = `${jobRelative}/candidates/${candidate.id}`;
+            const source = new Set(candidate.sourcePaths);
+            try {
+                relativeFile(candidate.pagePath);
+                if (candidate.adoptedPath)
+                    relativeFile(candidate.adoptedPath);
+                if (new Set(candidate.files.map(file => file.path)).size !== candidate.files.length ||
+                    new Set(candidate.captures?.map(file => file.path)).size !== (candidate.captures?.length ?? 0) ||
+                    candidate.sourcePaths.some(path => !candidate.files.some(file => file.path === path)) ||
+                    !candidate.files.some(file => file.path === candidate.pagePath) ||
+                    candidate.captures?.some(file => !file.path.startsWith(`candidates/${candidate.id}/captures/`)))
+                    throw new Error('model_candidates_manifest_invalid');
+            }
+            catch {
+                diagnose('model_candidates_manifest_invalid', runId, candidate.id);
+                continue;
+            }
+            const item = {
+                runId, candidateId: candidate.id, revision: run.revision, passId: candidate.passId,
+                sourceHash: candidate.sourceHash, dependencyHash: candidate.dependencyHash,
+                referenceHash: run.referenceHash, skillArtifactHash: run.artifactHash,
+                files: candidate.files.map(file => ({ path: `${candidatePrefix}/source/${file.path}`, contentHash: file.hash, source: source.has(file.path) })),
+                captures: (candidate.captures ?? []).map(file => ({ path: `${jobRelative}/${file.path}`, contentHash: file.hash, view: file.view })),
+                preview: { kind: 'scene-preview', status: 'needs-build', entryPath: `${candidatePrefix}/source/${candidate.pagePath}`,
+                    sourceHash: candidate.sourceHash, dependencyHash: candidate.dependencyHash,
+                    ...(candidate.hostReview ? { profileHash: candidate.hostReview.profileHash } : {}), reason: 'candidate_scene_not_built' },
+                integrity: 'verified', ...(candidate.review ? { review: candidate.review } : {}),
+                ...(candidate.adoptedPath ? { adoptedPath: candidate.adoptedPath } : {}),
+            };
+            const invalidate = (code) => {
+                item.integrity = 'invalid';
+                if (item.preview.kind === 'scene-preview') {
+                    item.preview.status = 'unavailable';
+                    item.preview.reason = code;
+                }
+                diagnose(code, runId, candidate.id);
+            };
+            if (!workspaceModelCandidateSchema.safeParse(item).success) {
+                diagnose('model_candidates_manifest_invalid', runId, candidate.id);
+                continue;
+            }
+            if (!referenceVerified)
+                invalidate('model_candidates_reference_changed');
+            if (currentDependencyHash !== candidate.dependencyHash)
+                invalidate('model_candidates_dependencies_changed');
+            if (digest(JSON.stringify(candidate.files.map(({ path, hash }) => ({ path, hash })))) !== candidate.sourceHash)
+                invalidate('model_candidates_source_hash_changed');
+            if (!candidate.captures?.length)
+                invalidate('model_candidates_captures_missing');
+            if (candidate.review && candidate.review.sourceHash !== candidate.sourceHash)
+                invalidate('model_candidates_review_changed');
+            try {
+                if (digest(await readBounded(root, `${candidatePrefix}/spec.json`)) !== candidate.specHash)
+                    invalidate('model_candidates_spec_changed');
+            }
+            catch {
+                invalidate('model_candidates_spec_unavailable');
+            }
+            for (const file of [...item.files, ...item.captures]) {
+                try {
+                    const bytes = await readBounded(root, file.path);
+                    file.size = bytes.length;
+                    if (digest(bytes) !== file.contentHash)
+                        throw new Error('model_candidates_file_changed');
+                }
+                catch (error) {
+                    const limit = inspectedBytes >= MAX_BYTES || (error instanceof Error && error.message === 'model_candidates_byte_limit');
+                    invalidate(limit ? 'model_candidates_byte_limit' : 'model_candidates_file_unavailable');
+                    if (limit) {
+                        result.truncated = true;
+                        break;
+                    }
+                }
+            }
+            result.candidates.push(item);
+            if (item.integrity === 'verified' && item.preview.kind === 'scene-preview') {
+                try {
+                    const versions = await new ModelPreviewStore(stateDir, root).versions(item), preview = versions[0];
+                    item.previewVersions = versions.map(version => ({ previewId: version.previewId, contentHash: version.contentHash,
+                        createdAt: version.createdAt, ...(version.parameters ? { parameters: version.parameters } : {}),
+                        ...(version.parameterHash ? { parameterHash: version.parameterHash } : {}) }));
+                    if (preview)
+                        Object.assign(item.preview, { status: 'ready', reason: 'candidate_scene_built',
+                            previewId: preview.previewId, contentHash: preview.contentHash,
+                            ...(preview.parameters ? { parameters: preview.parameters } : {}),
+                            ...(preview.parameterHash ? { parameterHash: preview.parameterHash } : {}) });
+                }
+                catch {
+                    invalidate('model_preview_receipt_invalid');
+                }
+            }
+            if (inspectedBytes >= MAX_BYTES)
+                break;
+        }
+        if (inspectedBytes >= MAX_BYTES || inspectedCandidates >= MAX_CANDIDATES) {
+            result.truncated = true;
+            diagnose(inspectedBytes >= MAX_BYTES ? 'model_candidates_byte_limit' : 'model_candidates_candidate_limit', runId);
+            break;
+        }
+    }
+    return workspaceModelCandidateListSchema.parse(result);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.61-beta",
+  "version": "0.1.62-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -53,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.61-beta",
-    "@playcraft/common": "0.1.61-beta",
+    "@playcraft/build": "0.1.62-beta",
+    "@playcraft/common": "0.1.62-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -91,6 +91,7 @@
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.28.1",
+    "three": "^0.183.2",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/project-templates/empty/AGENTS.md

@@ -65,7 +65,7 @@ The artifact panel shows final deliverables under `dist/` at the current project
 
 When a generated asset is ready for delivery, save or copy it into `dist/` with a stable relative path. Keep the resources required by a model or document within `dist/` and preserve their relative links. Reuse the same delivery path for a revised artifact so its versions remain grouped; the platform retains its history. Use different paths for independent candidates or deliverables.
 
-Run playable builds from the project root (`playcraft build --mode full --platform playcraft --format html .`). In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/playable/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. Public sharing is a separate explicit action. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
+Run playable builds from the project root (`playcraft build --mode full --platform playcraft --format html .`). In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/playable/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
 
 Keep this convention in `AGENTS.md`, the project's standard instruction filename. Do not create a separate `AGENT.md`.