@playcraft/cli 0.1.55-beta → 0.1.57-beta

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

@@ -3,9 +3,10 @@ import { createHash } from 'node:crypto';
 import { posix, relative, resolve, sep } from 'node:path';
 import JSON5 from 'json5';
 import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, validateParameterChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
-import { InvalidWorkspacePathError, writeWorkspaceFile, } from './files.js';
+import { InvalidWorkspacePathError, writeWorkspaceFile } from './files.js';
 import { editJson5Paths, ParameterEditError } from './json5-edit.js';
-import { prepareParameterAssetRegistration, writeParameterAssetRegistration } from './parameter-assets.js';
+import { prepareParameterAssetRegistration, writeParameterAssetRegistration, } from './parameter-assets.js';
+import { themeAssetIndexFingerprint } from './theme-asset-index.js';
 const MANIFEST_PATH = '.playcraft/workspace.json';
 const DEFAULT_SCHEMA_PATH = 'src/theme/theme.schema.json5';
 const THEME_INDEX_PATH = 'src/theme/index.ts';
@@ -22,7 +23,9 @@ export async function readWorkspaceParameters(root, revisions) {
     throw new ParameterEditError('parameter_source_changed');
 }
 async function sourceFingerprint(root, located, ownIndexWrite) {
-    const selectedIndex = located.dataPath ? posix.join(posix.dirname(located.dataPath), 'index.ts') : undefined;
+    const selectedIndex = located.dataPath
+        ? posix.join(posix.dirname(located.dataPath), 'index.ts')
+        : undefined;
     const sources = await Promise.all([
         located.schemaPath ? readOptionalText(root, located.schemaPath) : undefined,
         located.schemaPath ? readOptionalText(root, platformI18nPath(located.schemaPath)) : undefined,
@@ -30,20 +33,40 @@ async function sourceFingerprint(root, located, ownIndexWrite) {
         readOptionalText(root, THEME_INDEX_PATH),
         selectedIndex ? readOptionalText(root, selectedIndex) : undefined,
     ]);
-    const hashes = sources.map(text => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
+    const hashes = sources.map((text) => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
+    const rawIndexHash = hashes[4];
+    if (sources[4] !== undefined) {
+        try {
+            const data = located.dataPath ? await readOptionalText(root, located.dataPath) : undefined;
+            hashes[4] = themeAssetIndexFingerprint(sources[4], themeImageReferences(sources[0] === undefined ? {} : JSON5.parse(sources[0]), data === undefined ? {} : JSON5.parse(data)));
+        }
+        catch {
+            // Invalid configuration cannot authorize a relaxed resource identity.
+            hashes[4] = rawIndexHash;
+        }
+    }
     if (ownIndexWrite) {
         // Only our exact staged registry bytes may differ from the baseline. An external edit,
         // including a schema/manifest change during the write callback, still fails the old guard.
-        if (selectedIndex !== ownIndexWrite.path || hashes[4] !== ownIndexWrite.contentHash)
+        if (selectedIndex !== ownIndexWrite.path || rawIndexHash !== ownIndexWrite.contentHash)
             throw new ParameterEditError('parameter_source_conflict');
-        hashes[4] = ownIndexWrite.previousHash;
+        hashes[4] = ownIndexWrite.previousFingerprint;
     }
-    return createHash('sha256').update(JSON.stringify({
+    return createHash('sha256')
+        .update(JSON.stringify({
         schemaPath: located.schemaPath ?? null,
         dataPath: located.dataPath ?? null,
         themeId: located.themeId ?? null,
         sources: hashes,
-    })).digest('hex');
+    }))
+        .digest('hex');
+}
+function themeImageReferences(schema, data) {
+    return parameterCatalog(schema, data).flatMap((field) => field.asset?.kind === 'image' &&
+        typeof field.value === 'string' &&
+        field.value.startsWith('./assets/')
+        ? [field.value]
+        : []);
 }
 async function readParameterDocuments(root, revisions, located) {
     if (located.errors.some((item) => item.reason === 'parameter_manifest_invalid')) {
@@ -79,7 +102,9 @@ async function readParameterDocuments(root, revisions, located) {
         schema: schemaFile.value,
         schemaHash: schemaFile.contentHash,
         schemaRevision: revisions[located.schemaPath]?.revision ?? 0,
-        ...(platformFile.status === 'ok' ? { platformI18n: platformFile.value, platformI18nPath: i18nPath } : {}),
+        ...(platformFile.status === 'ok'
+            ? { platformI18n: platformFile.value, platformI18nPath: i18nPath }
+            : {}),
     };
     if (platformFile.status === 'invalid') {
         return parameterDocumentSchema.parse({
@@ -128,8 +153,8 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
         throw new ParameterEditError('parameter_data_missing');
     }
-    if ((parsed.sourceFingerprint && parsed.sourceFingerprint !== document.sourceFingerprint)
-        || (observed && observed.dataPath !== document.dataPath)) {
+    if ((parsed.sourceFingerprint && parsed.sourceFingerprint !== document.sourceFingerprint) ||
+        (observed && observed.dataPath !== document.dataPath)) {
         throw new ParameterEditError('parameter_source_conflict');
     }
     const changes = 'changes' in parsed ? parsed.changes : [{ fieldPath: parsed.fieldPath, value: parsed.value }];
@@ -150,27 +175,33 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
         throw new ParameterEditError('parameter_document_invalid');
     }
     const current = await locateParameterFiles(root);
-    if (await sourceFingerprint(root, current) !== document.sourceFingerprint) {
+    if ((await sourceFingerprint(root, current)) !== document.sourceFingerprint) {
         throw new ParameterEditError('parameter_source_conflict');
     }
     const catalog = parameterCatalog(document.schema, document.data);
-    const bindings = changes.flatMap(change => {
+    const bindings = changes.flatMap((change) => {
         if (change.op === 'remove' || typeof change.value !== 'string' || !change.value)
             return [];
-        const field = catalog.find(entry => entry.key === change.fieldPath.join('.'));
+        const field = catalog.find((entry) => entry.key === change.fieldPath.join('.'));
         return field?.asset ? [{ value: change.value, asset: field.asset }] : [];
     });
-    const registration = await prepareParameterAssetRegistration(root, document.dataPath, bindings);
+    const registration = await prepareParameterAssetRegistration(root, document.dataPath, bindings, themeImageReferences(document.schema, document.data));
     // Register first: a failed sparse save can leave an unused asset, never a dangling saved reference.
     const additionalWrites = [];
     let ownIndexWrite;
     if (registration) {
         const written = await writeParameterAssetRegistration(root, registration);
         additionalWrites.push(written);
-        ownIndexWrite = { path: written.path, previousHash: registration.previousHash, contentHash: written.contentHash };
+        ownIndexWrite = {
+            path: written.path,
+            previousHash: registration.previousHash,
+            previousFingerprint: registration.previousFingerprint,
+            contentHash: written.contentHash,
+        };
         await options.onAdditionalWrite?.(written);
     }
-    if (await sourceFingerprint(root, await locateParameterFiles(root), ownIndexWrite) !== document.sourceFingerprint)
+    if ((await sourceFingerprint(root, await locateParameterFiles(root), ownIndexWrite)) !==
+        document.sourceFingerprint)
         throw new ParameterEditError('parameter_source_conflict');
     const latest = await readOptionalText(root, document.dataPath);
     if (latest !== source)
@@ -232,8 +263,12 @@ function declaredPaths(value) {
     if (Object.keys(record).some((key) => !['schemaPath', 'dataPath', 'themeId'].includes(key))) {
         return undefined;
     }
-    const schemaPath = record.schemaPath === undefined ? undefined : workspaceRelativePathSchema.safeParse(record.schemaPath);
-    const dataPath = record.dataPath === undefined ? undefined : workspaceRelativePathSchema.safeParse(record.dataPath);
+    const schemaPath = record.schemaPath === undefined
+        ? undefined
+        : workspaceRelativePathSchema.safeParse(record.schemaPath);
+    const dataPath = record.dataPath === undefined
+        ? undefined
+        : workspaceRelativePathSchema.safeParse(record.dataPath);
     const themeId = record.themeId === undefined
         ? undefined
         : typeof record.themeId === 'string' && record.themeId.trim() && record.themeId.length <= 128
@@ -258,7 +293,8 @@ async function readDeclaredTheme(root) {
     const text = contents.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
     const match = text.match(/export\s+\{\s*default\s*\}\s+from\s+['"]\.\/([^'"]+)['"]/);
     const themeId = match?.[1]?.trim();
-    return themeId && workspaceRelativePathSchema.safeParse(`${THEME_ROOT}/${themeId}/theme.data.json5`).success
+    return themeId &&
+        workspaceRelativePathSchema.safeParse(`${THEME_ROOT}/${themeId}/theme.data.json5`).success
         ? themeId
         : undefined;
 }
@@ -292,7 +328,11 @@ async function readOptionalJson5(root, relativePath) {
     if (text === undefined)
         return { status: 'missing' };
     try {
-        return { status: 'ok', value: JSON5.parse(text), contentHash: createHash('sha256').update(text).digest('hex') };
+        return {
+            status: 'ok',
+            value: JSON5.parse(text),
+            contentHash: createHash('sha256').update(text).digest('hex'),
+        };
     }
     catch {
         return { status: 'invalid', reason: 'parameter_document_invalid' };

package/dist/workspace-runtime/workspaces/platform-export.js

@@ -0,0 +1,185 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { buildStageAt } from '@playcraft/common/build-progress';
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { submitTrustedOperation } from '../server/submit-operation.js';
+import { businessEndpoint } from '../../utils/environment-endpoints.js';
+import { ensureCliCredentials } from './cli-credentials.js';
+import { readWorkspaceGitStatus } from './git.js';
+import { sessionWorkspaceRoot } from './registry.js';
+const run = promisify(execFile);
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Validation findings beyond this are summarized by count; the Agent fixes the first ones first. */
+const MAX_FINDINGS = 30;
+/** A tool error the Agent sees as its reason; `code` is stable, the detail explains it. */
+export class PlatformExportError extends Error {
+    code;
+    constructor(code, detail) {
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+    }
+}
+/** The project and branch a workspace directory exports, or undefined when it has no project. */
+export async function platformExportTarget(state, scope) {
+    const binding = state.journal.getWorkspace(scope.workspaceId);
+    if (!binding?.projectId)
+        return undefined;
+    const root = await sessionWorkspaceRoot(state, scope.workspaceId, scope.directoryName);
+    return { projectId: binding.projectId, root };
+}
+/**
+ * A standalone workspace has no remote to export from. The platform gives it a project (as its
+ * first save does) and registers it again; the registration reaches this runtime before the reply.
+ */
+async function promoteStandalone(state, scope) {
+    if (state.journal.getWorkspace(scope.workspaceId)?.targetKind !== 'standalone' || scope.directoryName !== 'basic')
+        return;
+    const config = state.config;
+    const response = await fetch(platformEndpoint(config.publicBaseUrl, PLATFORM_ROUTES.workspacePromotions), {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
+        body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation, runtimeEpoch: state.runtimeEpoch,
+            workspaceId: scope.workspaceId }),
+    });
+    if (!response.ok) {
+        const body = await response.json().catch(() => undefined);
+        throw new PlatformExportError('workspace_promotion_failed', typeof body?.reason === 'string' ? body.reason : String(response.status));
+    }
+    await response.body?.cancel().catch(() => undefined);
+}
+const credentialSchema = z.object({ apiUrl: z.string().url(), token: z.string().min(1) });
+async function request(state, path, init) {
+    await ensureCliCredentials(state).catch(() => { throw new PlatformExportError('cli_credentials_unavailable'); });
+    const credential = credentialSchema.parse(JSON.parse(await readFile(join(state.config.workspaceRoot, '.playcraft.json'), 'utf8')));
+    const response = await fetch(businessEndpoint(credential.apiUrl, path), {
+        method: init.method,
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'X-Sandbox-Token': credential.token,
+            'playcraft-env': state.config.environment,
+            ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    const error = body && typeof body === 'object' && 'error' in body ? body.error : undefined;
+    if (!response.ok || (typeof error === 'string' && !('id' in body))) {
+        const message = body && typeof body === 'object' && 'message' in body ? body.message : error;
+        throw new PlatformExportError('platform_export_rejected', `${response.status} ${typeof message === 'string' ? message : Array.isArray(message) ? message.join('; ') : text.slice(0, 300)}`);
+    }
+    return body;
+}
+/**
+ * Saves the directory (commit + push), then exports that commit for the channels through the
+ * platform, as the delivery panel's Export does. Each channel repeats its latest export of the
+ * branch, or uses the defaults without one. A standalone workspace first becomes a project.
+ */
+export async function startPlatformExport(state, input) {
+    await promoteStandalone(state, input);
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    const saved = await submitTrustedOperation(state, {
+        kind: 'workspace.save',
+        workspaceId: input.workspaceId,
+        directoryName: input.directoryName,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        clientRequestId: `${input.clientRequestId.slice(0, 80)}:export-save`,
+        payload: {},
+    });
+    if (saved.status !== 'completed')
+        throw new PlatformExportError('workspace_save_failed', saved.error);
+    const status = await readWorkspaceGitStatus(target.root);
+    // A save skips the push during a merge; with an upstream, `ahead` says the push did not land.
+    if (status.merging || (status.hasUpstream && status.ahead > 0))
+        throw new PlatformExportError('workspace_not_pushed');
+    if (status.branch === 'HEAD')
+        throw new PlatformExportError('workspace_detached_head');
+    const commit = (await run('git', ['-C', target.root, 'rev-parse', 'HEAD'])).stdout.trim();
+    const result = await request(state, '/api/builds/agent-exports', {
+        method: 'POST',
+        body: {
+            projectId: target.projectId,
+            branchName: status.branch,
+            commitHash: commit,
+            platforms: input.channels,
+            ...(input.format ? { format: input.format } : {}),
+            clientRequestId: input.clientRequestId,
+        },
+    });
+    return {
+        commit: commit.slice(0, 7),
+        branch: status.branch,
+        builds: result.builds.map((build) => ({
+            buildId: build.id,
+            channel: build.platform,
+            status: build.status,
+            ...(build.format ? { format: build.format } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(result.options?.[build.platform] ? { options: result.options[build.platform] } : {}),
+        })),
+    };
+}
+/** One platform export as the Agent reads it: status, the recorded failure and the checks. */
+export async function readPlatformExport(state, input) {
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    let buildId = input.buildId;
+    if (!buildId) {
+        const { branch } = await readWorkspaceGitStatus(target.root);
+        const query = new URLSearchParams({ projectId: target.projectId, branchName: branch, limit: '1',
+            ...(input.channel ? { platform: input.channel } : {}) });
+        const list = await request(state, `/api/agent/tools/list-builds?${query}`, { method: 'GET' });
+        buildId = list.items[0]?.id;
+        if (!buildId)
+            throw new PlatformExportError('delivery_build_not_found');
+    }
+    const build = await request(state, `/api/agent/tools/get-build?${new URLSearchParams({ id: buildId })}`, { method: 'GET' });
+    const running = build.status === 'queued' || build.status === 'running';
+    const findings = (build.validationWarnings ?? []).map((warning) => ({
+        code: warning.code,
+        severity: warning.severity,
+        message: warning.message,
+        ...(typeof warning.details?.status === 'string' ? { status: warning.details.status } : {}),
+        ...(typeof warning.details?.recommendation === 'string' ? { recommendation: warning.details.recommendation } : {}),
+        ...(typeof warning.details?.file === 'string' ? { file: warning.details.file } : {}),
+        ...(typeof warning.details?.line === 'number' ? { line: warning.details.line } : {}),
+    }));
+    return {
+        build: {
+            buildId: build.id,
+            channel: build.platform,
+            format: build.format,
+            status: build.status,
+            ...(running ? { stage: buildStageAt(build.progress).stage } : {}),
+            ...(build.commitHash ? { commit: build.commitHash } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(build.previewUrl ? { previewUrl: build.previewUrl } : {}),
+            ...(build.downloadUrl ? { downloadUrl: build.downloadUrl } : {}),
+            ...(typeof build.outputSize === 'number' ? { sizeBytes: build.outputSize } : {}),
+            ...(typeof build.sizeLimit === 'number' ? { sizeLimitBytes: build.sizeLimit } : {}),
+        },
+        ...(build.artifacts?.failure ? { failure: build.artifacts.failure } : {}),
+        ...(!running && build.validationPassed !== null && build.validationPassed !== undefined ? {
+            validation: {
+                passed: build.validationPassed,
+                findings: findings.slice(0, MAX_FINDINGS),
+                ...(findings.length > MAX_FINDINGS ? { omitted: findings.length - MAX_FINDINGS } : {}),
+            },
+        } : {}),
+    };
+}

package/dist/workspace-runtime/workspaces/theme-asset-index.js

@@ -1,8 +1,11 @@
 import { createHash } from 'node:crypto';
 import JSON5 from 'json5';
+import { parameterAssetMimeType, parameterAssetValueError, } from '@playcraft/common/cloud-workspace/runtime';
 export class ThemeAssetIndexError extends Error {
     code = 'parameter_asset_index_unsupported';
-    constructor() { super('parameter_asset_index_unsupported'); }
+    constructor() {
+        super('parameter_asset_index_unsupported');
+    }
 }
 /** A bounded lexer recognizes the standard literal registry without evaluating project code. */
 function lex(source) {
@@ -84,9 +87,13 @@ function registry(source) {
     for (let i = exportStart + 3; i < tokens.length && exportDepth; i++) {
         const token = tokens[i];
         const previous = tokens[i - 1]?.text;
-        const properKey = previous === ':' && (tokens[i - 2]?.text === 'assetRecordByPath' || tokens[i - 2]?.string === 'assetRecordByPath');
-        if (exportDepth === 1 && token.text === 'assetRecordByPath' && [',', '}'].includes(tokens[i + 1]?.text ?? '')
-            && (previous === '{' || previous === ',' || properKey))
+        const properKey = previous === ':' &&
+            (tokens[i - 2]?.text === 'assetRecordByPath' ||
+                tokens[i - 2]?.string === 'assetRecordByPath');
+        if (exportDepth === 1 &&
+            token.text === 'assetRecordByPath' &&
+            [',', '}'].includes(tokens[i + 1]?.text ?? '') &&
+            (previous === '{' || previous === ',' || properKey))
             exportsRegistry = true;
         if (token.string === undefined && token.text === '{')
             exportDepth++;
@@ -103,13 +110,17 @@ function registry(source) {
     }
     if (tokens[++cursor]?.text !== '{')
         throw new ThemeAssetIndexError();
+    const start = tokens[cursor].start;
     cursor++;
     const entries = new Map();
     let lastValueEnd, trailingComma = false;
     while (tokens[cursor]?.text !== '}') {
         const key = tokens[cursor], colon = tokens[cursor + 1], value = tokens[cursor + 2];
-        if (key?.string === undefined || colon?.text !== ':' || !value || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value.text)
-            || entries.has(key.string))
+        if (key?.string === undefined ||
+            colon?.text !== ':' ||
+            !value ||
+            !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value.text) ||
+            entries.has(key.string))
             throw new ThemeAssetIndexError();
         entries.set(key.string, value.text);
         lastValueEnd = value.end;
@@ -125,15 +136,110 @@ function registry(source) {
     const end = tokens[cursor].start;
     const imports = new Map();
     for (let i = 0; i < tokens.length - 3; i++) {
-        if (tokens[i].text === 'import' && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(tokens[i + 1].text)
-            && tokens[i + 1].text !== 'type' && tokens[i + 2].text === 'from' && tokens[i + 3].string !== undefined)
+        if (tokens[i].text === 'import' &&
+            /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(tokens[i + 1].text) &&
+            tokens[i + 1].text !== 'type' &&
+            tokens[i + 2].text === 'from' &&
+            tokens[i + 3].string !== undefined)
             imports.set(tokens[i + 3].string, tokens[i + 1].text);
     }
-    return { end, lastValueEnd, trailingComma, entries, imports, tokens };
+    return { start, end, lastValueEnd, trailingComma, entries, imports, tokens };
+}
+/** Only literal, exclusively registered image imports belong to the replaceable resource domain. */
+export function themeAssetIndexFingerprint(source, requiredImageValues = []) {
+    const hash = (value) => createHash('sha256').update(value).digest('hex');
+    try {
+        const state = registry(source), tokens = state.tokens;
+        // Mutation, aliases, getters and other registry consumers cannot be separated safely.
+        if (tokens.filter((token) => token.string === undefined && token.text === 'assetRecordByPath')
+            .length !== 2)
+            return hash(source);
+        const references = new Map(), imports = new Map();
+        const values = new Map();
+        for (const token of tokens) {
+            if (token.string === undefined)
+                references.set(token.text, (references.get(token.text) ?? 0) + 1);
+        }
+        for (let i = 0; i < tokens.length - 4; i++) {
+            if (tokens[i].text !== 'import' ||
+                tokens[i + 2].text !== 'from' ||
+                tokens[i + 3].string === undefined ||
+                tokens[i + 4].text !== ';')
+                continue;
+            const variable = tokens[i + 1].text, imported = imports.get(variable) ?? [];
+            imported.push({ path: tokens[i + 3].string, start: i });
+            imports.set(variable, imported);
+        }
+        for (const [value, variable] of state.entries)
+            values.set(variable, [...(values.get(variable) ?? []), value]);
+        const imageEntries = new Set();
+        const replacements = [];
+        for (const [variable, bindings] of imports) {
+            if (bindings.length !== 1)
+                continue;
+            const binding = bindings[0], importPath = binding.path;
+            const value = importPath.startsWith('./assets/')
+                ? importPath
+                : importPath.startsWith('../../assets/')
+                    ? 'src/' + importPath.slice(6)
+                    : undefined;
+            if (!value)
+                continue;
+            const mime = parameterAssetMimeType(value);
+            if (!mime?.startsWith('image/') ||
+                parameterAssetValueError({
+                    kind: 'image',
+                    mimeTypes: [mime],
+                    extensions: [],
+                    maxBytes: 32 * 1024 * 1024,
+                }, value))
+                continue;
+            const registered = values.get(variable) ?? [];
+            if (registered.some((key) => key !== value) ||
+                references.get(variable) !== registered.length + 1)
+                continue;
+            for (const key of registered)
+                imageEntries.add(key);
+            const start = tokens[binding.start].start;
+            let end = tokens[binding.start + 4].end;
+            if (source.startsWith('\r\n', end))
+                end += 2;
+            else if (source[end] === '\n')
+                end++;
+            replacements.push({ start, end, content: '' });
+        }
+        const start = tokens.findIndex((token) => token.start === state.start);
+        const end = tokens.findIndex((token) => token.start === state.end);
+        if (start < 0 || end <= start)
+            return hash(source);
+        // Shared src/assets defaults belong to the existing build loader. Only theme-relative
+        // effective images require this selected theme's literal registry.
+        const missingThemeImages = [
+            ...new Set(requiredImageValues.filter((value) => value.startsWith('./assets/') && !state.entries.has(value))),
+        ].sort();
+        replacements.push({
+            start: tokens[start].end,
+            end: tokens[end].start,
+            content: JSON.stringify([...state.entries].filter(([value]) => !imageEntries.has(value))),
+        });
+        let canonical = source;
+        for (const replacement of replacements.sort((a, b) => b.start - a.start))
+            canonical =
+                canonical.slice(0, replacement.start) +
+                    replacement.content +
+                    canonical.slice(replacement.end);
+        return hash('theme-asset-code-v1:' + JSON.stringify({ source: canonical, missingThemeImages }));
+    }
+    catch {
+        // Unknown project syntax retains the original strict byte identity.
+        return hash(source);
+    }
 }
 /** Add only literal imports/entries; retain user exports, comments, unrelated mappings and files. */
 export function registerThemeAsset(source, value, importPath) {
-    if (!value || !importPath.startsWith('./') && !importPath.startsWith('../') || /[\r\n\x00]/.test(importPath))
+    if (!value ||
+        (!importPath.startsWith('./') && !importPath.startsWith('../')) ||
+        /[\r\n\x00]/.test(importPath))
         throw new ThemeAssetIndexError();
     const state = registry(source);
     const imported = state.imports.get(importPath);
@@ -143,8 +249,11 @@ export function registerThemeAsset(source, value, importPath) {
             return source;
         throw new ThemeAssetIndexError();
     }
-    const variable = imported ?? '__playcraftParameterAsset_' + createHash('sha256').update(importPath).digest('hex').slice(0, 16);
-    if (!imported && state.tokens.some(token => token.string === undefined && token.text === variable))
+    const variable = imported ??
+        '__playcraftParameterAsset_' +
+            createHash('sha256').update(importPath).digest('hex').slice(0, 16);
+    if (!imported &&
+        state.tokens.some((token) => token.string === undefined && token.text === variable))
         throw new ThemeAssetIndexError();
     let result = source;
     let end = state.end;
@@ -152,6 +261,7 @@ export function registerThemeAsset(source, value, importPath) {
         result = result.slice(0, state.lastValueEnd) + ',' + result.slice(state.lastValueEnd);
         end++;
     }
-    result = result.slice(0, end) + `\n  ${JSON.stringify(value)}: ${variable},\n` + result.slice(end);
+    result =
+        result.slice(0, end) + `\n  ${JSON.stringify(value)}: ${variable},\n` + result.slice(end);
     return (imported ? '' : `import ${variable} from ${JSON.stringify(importPath)};\n`) + result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.55-beta",
+  "version": "0.1.57-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -52,8 +52,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.55-beta",
-    "@playcraft/common": "0.1.55-beta",
+    "@playcraft/build": "0.1.57-beta",
+    "@playcraft/common": "0.1.57-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template-v2/.playcraft/skills.lock.json

@@ -10,8 +10,8 @@
     },
     {
       "skillRef": "platform/playcraft-asset-management",
-      "version": "1.0.0",
-      "artifactHash": "27209dba24f6e1851dc83682fbd24165894c802794c797cac32d8871f740cf14",
+      "version": "1.1.0",
+      "artifactHash": "0b5408792edfeb7b852817bd76893b95738a0e161407f0b48c4b50161797ba3c",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-asset-management"
     },
@@ -108,8 +108,8 @@
     },
     {
       "skillRef": "remix/playcraft-audio-generation",
-      "version": "1.0.0",
-      "artifactHash": "8d1b035b289545ca8fd6c247b9417bf34bddf5a26b31e114c35d001aa3a9ebf0",
+      "version": "1.1.1",
+      "artifactHash": "27661b1b52e7981a0b9cf5531f535fcf10928ea290348fcb469e35ad2082b437",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-audio-generation"
     },
@@ -122,15 +122,15 @@
     },
     {
       "skillRef": "remix/playcraft-image-generation",
-      "version": "1.0.0",
-      "artifactHash": "91bec2422c750d9d47d5be2796ec5aaffb48de561f2c2d8b92112f37d576f489",
+      "version": "1.1.2",
+      "artifactHash": "a006c96700f8dbfe4c34a31d0e1646620ca6148d319e59e7466d627fea1ca65e",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-generation"
     },
     {
       "skillRef": "remix/playcraft-image-processing",
-      "version": "1.0.0",
-      "artifactHash": "d845c067bed103c3d1d3f145b1cb8246ffbd6a9ae91efcfbce2eae456819212d",
+      "version": "1.1.1",
+      "artifactHash": "903f4efc14e2bb57403856edeca43146904ec64811cfd107b6ec76bb451842fd",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-processing"
     },
@@ -147,6 +147,13 @@
       "artifactHash": "e2a59c61ef5b094a821fbbab3b0f65f906bfc0dfda6f3d8c0b33a6f460dd0963",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-remix-workflow"
+    },
+    {
+      "skillRef": "remix/playcraft-workspace-assets",
+      "version": "1.0.0",
+      "artifactHash": "f098949b043a229e561d92a34c3a65b44ffbd83d1758ef30ac09d2d0d5ea2570",
+      "surface": "sandbox-agent",
+      "mountPath": ".playcraft/skills/remix__playcraft-workspace-assets"
     }
   ]
 }

package/project-templates/empty/AGENTS.md

@@ -46,7 +46,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 and place their final output under `dist/` (`playcraft build --mode full --platform playcraft --format html --output ./dist .`). A base build's `dist/index.html` can still require resource files; it is not proof of a self-contained playable. The workspace's playable publish action validates its isolated temporary build, then retains the exact single-file result at `dist/playable/index.html`. 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. 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.
 
 Keep this convention in `AGENTS.md`, the project's standard instruction filename. Do not create a separate `AGENT.md`.
 

package/templates/preview-runtime/v1/README.md

@@ -14,6 +14,18 @@ Create your own `src/preview/runtime.ts`. Import `connectPreviewRuntime` and `re
 - `createGame(context)` returns actual `apply(context)`, `restartScene(context)`, `afterRender(context)` and `dispose()` callbacks. Check `context.assertCurrent()` and honor `context.signal` before late effects. `afterRender` must wait for real rendering, not a successful placeholder.
 - Dispose the endpoint on page exit. Advertising SDK configuration remains the production concern; do not route development updates through advertising caches.
 
+## Runtime image parameters
+
+Register an image consumer with `resource: 'image'` and `mode: 'live'`. Keep its logical asset path in a preview-only resolved property used by `effectivePath`; do not compare an embedded image address with the raw parameter path. `context.loadImage(field, logicalPath)` requests the current declared image through the host and returns a decoded image element. Empty paths clear the consumer without reading a file. The host validates the field against the current schema and configuration; the game receives image bytes, never platform file addresses or credentials.
+
+Prepare all required images before changing visible objects, call `assertCurrent()` after asynchronous work and immediately before installing textures, then wait for the real engine frame. Keep old objects intact until preparation succeeds. Release old preview-owned textures and overlay references after a successful replacement and on disposal. Never remove an engine texture still used by another object.
+
+`ResourceLoadError` is exported from `runtime.mjs`. Live adapters let this error reach the runtime, which retains the last known installation and reports a recoverable, field-level resource failure. Do not catch an arbitrary update exception and claim successful fallback. During initial `createGame`, catch only this load error to start with an embedded default image or empty background; the runtime still reports the saved image as unapplied. A later patch of that field retries it; unrelated parameter updates can continue. `resourceErrors` and file-save receipts are independent. Save logical paths and let the original production asset registry include the file when building delivery output.
+
+The endpoint advertises `canRefreshImages: true` for explicit same-path content refresh. The host sends registered live-image fields and their expected file digests through a separate resource sequence; raw parameters and draft revisions remain unchanged. In `apply`, honor `context.fields` even when a logical path equals its previous value: request that field through `loadImage` and install the returned image after `assertCurrent()`. A local path-equality cache must not hide this explicit update. The runtime prepares new images without blocking unrelated live parameters, checks the expected content digest, rebases against the latest permitted configuration and records installed digests only after the real render acknowledgement. A matching installed digest is a no-op; a failed or superseded preparation leaves the old image available and can be retried. Older endpoints without this optional capability require the existing rebuild route.
+
+Content generations are independent per field. If an opening image and board image are being prepared together, a newer board-only refresh cancels only the old board read; the still-current opening image must finish and apply while preserving the newer board. Each application uses only the prepared fields that remain current and the latest permitted configuration. A preparation failure in a still-current batch retains the old images and marks all its unapplied fields as recoverable, so an explicit retry cannot silently forget a prepared sibling.
+
 ## Preview build
 
 The engineering project must install a compatible Vite as a development dependency. Set a separate package script: