@playcraft/cli 0.1.56-beta → 0.1.58-beta

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

@@ -1,5 +1,5 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { cp, lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { load } from 'js-yaml';
 import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
@@ -9,6 +9,7 @@ import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import
 import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
 import { excludeFromGit } from './dependencies.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
 /** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
 export async function readWorkspaceSkillSnapshot(root) {
     const management = await lstat(join(root, '.playcraft'));
@@ -42,7 +43,7 @@ export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
                     continue;
                 await safeDirectory(root, '.agents/skills');
                 const source = `.agents/skills/${name}`;
-                await mkdir(join(root, source), { mode: 0o755 });
+                await ensureSharedDirectory(root, join(root, source));
                 added.add(source);
                 const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
                 for (const child of await readdir(template))
@@ -61,12 +62,16 @@ async function safeDirectory(root, path) {
     let current = root;
     for (const segment of path.split('/')) {
         current = join(current, segment);
-        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(current);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
+        // Validate every existing segment before creating anything, so a link never redirects the tree.
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
             throw new Error('workspace_skills_invalid');
     }
+    await ensureSharedDirectory(root, current);
     return current;
 }
 /** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
@@ -111,14 +116,7 @@ async function lockedFiles(root, cache, entry, view, loadArtifact) {
         throw new Error('workspace_skills_invalid_bundle');
     if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
         throw new Error('workspace_skills_digest_mismatch');
-    const temporary = `${saved}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
-        await rename(temporary, saved);
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
+    await writeSharedFile(root, saved, archive);
     return extracted.files;
 }
 function metadata(entryKey, content) {
@@ -155,6 +153,7 @@ export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
             const relative = join(entry.entryKey, file.path);
             expectedFiles.add(relative);
             await safeDirectory(generation, dirname(relative));
+            // shared
             await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
                 if (error.code !== 'EEXIST')
                     throw error;

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

@@ -138,7 +138,9 @@ async function copySnapshot(source, target, signal, hashOnly = false) {
                                 size += chunk.length;
                                 callback(size > before.size ? new WorkspaceTransferError('workspace_transfer_conflict') : null, chunk);
                             } });
-                        await pipeline(handle.createReadStream({ autoClose: false }), guard, createWriteStream(to, { flags: 'wx', mode: 0o600 }), { signal });
+                        await pipeline(handle.createReadStream({ autoClose: false }), guard, 
+                        // private
+                        createWriteStream(to, { flags: 'wx', mode: 0o600 }), { signal });
                     }
                     else {
                         for await (const chunk of handle.createReadStream({ autoClose: false })) {
@@ -366,6 +368,7 @@ export async function applyWorkspaceTransfer(root, bundle, expectedTree, options
     try {
         const bundlePath = typeof bundle === 'string' ? resolve(bundle) : join(temporary, 'incoming.bundle');
         const incoming = join(temporary, 'checkout');
+        // private
         if (typeof bundle !== 'string')
             await writeFile(bundlePath, bundle, { mode: 0o600 });
         const bundleInfo = await stat(bundlePath);

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

@@ -0,0 +1,235 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { dirname, join, relative as relativePath } from 'node:path';
+import { runDeveloperCommand } from './developer-command.js';
+import { SHARED_DIRECTORY_MODE, SHARED_FILE_MODE, sharePathWithGroup, workspaceGroup, } from './shared-write.js';
+/**
+ * Subtrees both sandbox identities read and write. Repair never walks the whole checkout: source
+ * files belong to Git and are opened once during preparation; these are the trees a session keeps
+ * writing after that point.
+ */
+export const WORKSPACE_SHARED_PATHS = [
+    '.playcraft/artifact-receipts',
+    '.playcraft/skills',
+    '.playcraft/skill-artifacts',
+    '.playcraft-temp',
+    'dist',
+];
+/** Only the root is shared here; the transaction directories below it stay private. */
+const SHARED_ROOT_ONLY = new Set(['.playcraft-temp']);
+const PERMISSION_CODES = new Set(['EACCES', 'EPERM']);
+export function isWorkspacePermissionError(error) {
+    const code = error?.code;
+    return typeof code === 'string' && PERMISSION_CODES.has(code);
+}
+/** Recognises a filesystem EACCES/EPERM, unwrapping the `cause` some guards attach. */
+export function permissionDriftFromError(error) {
+    const seen = error instanceof Error && error.cause ? error.cause : error;
+    const node = seen;
+    if (!isWorkspacePermissionError(node) || typeof node.path !== 'string' || !node.path)
+        return undefined;
+    const search = ['scandir', 'readdir', 'stat', 'access', 'opendir'].includes(String(node.syscall));
+    return { path: node.path, missing: search ? 'group_search' : 'group_write' };
+}
+/** Recognises the EACCES/EPERM line a failed command or scan leaves in its log. */
+export function permissionDriftFromOutput(output) {
+    const match = /(?:EACCES|EPERM): permission denied, (stat|scandir|open|access|readdir|mkdir|unlink|rename) '([^']+)'/
+        .exec(output);
+    if (!match)
+        return undefined;
+    const operation = match[1];
+    return {
+        path: match[2],
+        missing: operation === 'scandir' || operation === 'readdir' || operation === 'stat' || operation === 'access'
+            ? 'group_search'
+            : 'group_write',
+    };
+}
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+async function shapeOwnedTree(path, groupId, recursive = true) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        return { repaired: 0, foreign: false };
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    // The other identity owns this inode; its own pass repairs the subtree.
+    if (uid !== undefined && uid !== 0 && stat.uid !== uid)
+        return { repaired: 0, foreign: true };
+    const changed = await sharePathWithGroup(path, groupId, stat.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE, stat.isFile());
+    let repaired = changed ? 1 : 0;
+    let foreign = false;
+    if (!stat.isDirectory() || !recursive)
+        return { repaired, foreign };
+    const entries = await readdir(path).catch(error => {
+        // An unreadable directory can only be opened by its owner.
+        if (isWorkspacePermissionError(error)) {
+            foreign = true;
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of entries) {
+        const result = await shapeOwnedTree(join(path, entry), groupId);
+        repaired += result.repaired;
+        foreign ||= result.foreign;
+    }
+    return { repaired, foreign };
+}
+function missingShare(stat, groupId) {
+    if (stat.gid !== groupId)
+        return 'group_write';
+    const mode = Number(stat.mode);
+    if (stat.isDirectory()) {
+        if ((mode & 0o010) === 0)
+            return 'group_search';
+        if ((mode & 0o060) !== 0o060 || (mode & 0o2000) === 0)
+            return 'group_write';
+    }
+    else if ((mode & 0o020) === 0)
+        return 'group_write';
+    return undefined;
+}
+/**
+ * Lists entries of the shared subtrees that lost development-group access. Read-only: the owner of
+ * each entry (or `repairWorkspaceShares` at registration) is what changes them.
+ */
+export async function diagnoseWorkspaceShares(root, scope = 'workspace') {
+    const groupId = await workspaceGroup(root);
+    const targets = scope === 'workspace'
+        ? WORKSPACE_SHARED_PATHS.map((path) => join(root, path))
+        : [scope];
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    const drifts = [];
+    const visit = async (path, recursive) => {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            return;
+        const missing = missingShare(stat, groupId);
+        if (missing)
+            drifts.push({ path, missing, owner: uid !== undefined && stat.uid === uid ? 'self' : 'other' });
+        if (!stat.isDirectory() || !recursive)
+            return;
+        const entries = await readdir(path).catch(error => {
+            if (isWorkspacePermissionError(error))
+                return [];
+            throw error;
+        });
+        for (const entry of entries)
+            await visit(join(path, entry), true);
+    };
+    for (const target of targets) {
+        const stat = await lstat(target).catch(error => { if (isMissing(error))
+            return undefined; throw error; });
+        if (!stat)
+            continue;
+        await visit(target, !SHARED_ROOT_ONLY.has(relativePath(root, target)));
+    }
+    return drifts;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The launcher runs commands as the development identity. Entries that identity owns cannot be
+ * re-shaped from the controller, so the same invariants are applied from the owning side.
+ */
+async function repairAsOwner(state, root, targets, groupId) {
+    if (!targets.length)
+        return 0;
+    const command = [
+        'set -u',
+        'count=0',
+        ...targets.map((target) => {
+            const quoted = shellQuote(target);
+            return [
+                `if test -e ${quoted}; then`,
+                `  n=$(find ${quoted} -uid "$(id -u)" \\( -type d ! -perm -2770 -o -type f ! -perm -g+w \\) -print 2>/dev/null | wc -l)`,
+                '  count=$((count+n))',
+                `  find ${quoted} -uid "$(id -u)" -type d ! -perm -2770 -exec chmod 2770 {} + 2>/dev/null || true`,
+                `  find ${quoted} -uid "$(id -u)" -type f ! -perm -g+w -exec chmod g+rw {} + 2>/dev/null || true`,
+                `  find ${quoted} -uid "$(id -u)" ! -group ${groupId} -exec chgrp ${groupId} {} + 2>/dev/null || true`,
+                'fi',
+            ].join('\n');
+        }),
+        'printf "repaired=%s\\n" "$count"',
+    ].join('\n');
+    let repaired = 0;
+    await runDeveloperCommand(state, {
+        processId: `share-repair-${Date.now().toString(36)}`,
+        // The target itself may be unreadable to the controller; the workspace root is not.
+        cwd: root,
+        command,
+        timeoutMs: 30_000,
+        onOutput: (chunk) => {
+            const found = /repaired=(\d+)/.exec(String(chunk));
+            if (found)
+                repaired = Math.max(repaired, Number(found[1]));
+        },
+    });
+    return repaired;
+}
+/**
+ * Re-applies the shared mode to the subtrees both identities use. Idempotent: only entries missing
+ * group access are touched. `scope` names one path when a failure already identified the drift.
+ */
+export async function repairWorkspaceShares(state, root, scope = 'workspace') {
+    const groupId = await workspaceGroup(root);
+    const targets = scope === 'workspace'
+        ? WORKSPACE_SHARED_PATHS.map((path) => ({
+            path: join(root, path),
+            recursive: !SHARED_ROOT_ONLY.has(path),
+        }))
+        : [{ path: scope, recursive: true }];
+    const existing = [];
+    let repaired = 0;
+    const foreign = [];
+    for (const target of targets) {
+        const stat = await lstat(target.path).catch(error => { if (isMissing(error))
+            return undefined; throw error; });
+        if (!stat || !stat.isDirectory() || stat.isSymbolicLink())
+            continue;
+        existing.push(target.path);
+        const result = await shapeOwnedTree(target.path, groupId, target.recursive);
+        repaired += result.repaired;
+        if (result.foreign)
+            foreign.push(target.path);
+    }
+    if (foreign.length)
+        repaired += await repairAsOwner(state, root, foreign, groupId);
+    const report = { scope, repaired, paths: existing, delegated: foreign.length > 0 };
+    if (repaired > 0 || foreign.length > 0) {
+        console.log(JSON.stringify({
+            event: 'workspace_share_repaired',
+            scope,
+            root,
+            repaired,
+            paths: existing.map((path) => (scope === 'workspace' ? path.slice(root.length + 1) : path)),
+            delegated: report.delegated,
+        }));
+    }
+    return report;
+}
+/** Repairs once and retries a read/build that failed only because of a shared-permission drift. */
+export async function withShareRepair(state, root, action, drift) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (!isWorkspacePermissionError(error))
+            throw error;
+        const path = drift?.path ?? permissionDriftFromError(error)?.path;
+        await repairWorkspaceShares(state, root, await driftScope(root, path));
+        return action();
+    }
+}
+/** The shared subtree (or explicit path) that contains a drifting path. */
+export async function driftScope(root, path) {
+    if (!path)
+        return 'workspace';
+    for (const relative of WORKSPACE_SHARED_PATHS) {
+        const candidate = join(root, relative);
+        if (path === candidate || path.startsWith(`${candidate}/`))
+            return candidate;
+    }
+    return dirname(path);
+}

package/dist/workspace-runtime/workspaces/worktree-attachments.js

@@ -11,6 +11,7 @@ async function safeParents(root, path, create = false) {
         if (!segment || segment === '.' || segment === '..')
             throw new Error('workspace_worktree_attachment_unavailable');
         current = join(current, segment);
+        // shared
         if (create)
             await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
                 throw error; });
@@ -43,6 +44,7 @@ async function copyExact(source, target, path, limit) {
         return;
     }
     const temporary = `${join(target, path)}.${randomUUID()}.tmp`;
+    // shared
     try {
         await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
         await rename(temporary, join(target, path));

package/dist/workspace-runtime/workspaces/worktree-checkout.js

@@ -1,22 +1,27 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, realpath, writeFile } from 'node:fs/promises';
+import { lstat, open, realpath } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
 import { readWorkspaceSkills } from './skills.js';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
 const execute = promisify(execFile);
 async function archiveDirectory(root) {
     let directory = root;
     for (const segment of ['.playcraft', 'skill-artifacts']) {
         directory = join(directory, segment);
-        await mkdir(directory, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(directory);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
+        // Reject a redirected archive directory before creating or sharing anything below it.
+        const existing = await lstat(directory).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (existing && (!existing.isDirectory() || existing.isSymbolicLink()))
             throw new Error('workspace_worktree_skill_archive_unavailable');
     }
+    await ensureSharedDirectory(root, join(root, '.playcraft/skill-artifacts'));
 }
 /** Clone the saved commit and its exact skill archives, without copying unsaved files or credentials. */
 export async function checkoutChatWorktree(source, destination, commit, stateDir) {
@@ -60,7 +65,7 @@ export async function checkoutChatWorktree(source, destination, commit, stateDir
         if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
             throw new Error('workspace_worktree_skill_archive_unavailable');
         await archiveDirectory(destination);
-        await writeFile(saved, archive, { flag: 'wx', mode: 0o644 });
+        await writeSharedFile(destination, saved, archive);
     }
     // Existing locked repository bytes and the exact runtime cache can fill missing archives.
     await readWorkspaceSkills(destination, join(stateDir, 'skill-artifacts'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.56-beta",
+  "version": "0.1.58-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "dev": "tsc -w",
-    "build": "node scripts/generate-asset-skills.mjs && node scripts/generate-video-skills.mjs && node scripts/generate-preview-runtime.mjs && tsc",
+    "build": "node scripts/generate-asset-skills.mjs && node scripts/generate-video-skills.mjs && node scripts/generate-parameter-skill.mjs && node scripts/generate-preview-runtime.mjs && tsc",
     "start": "node dist/index.js",
     "test": "pnpm build && vitest run",
     "test:agent": "node scripts/run-agent-tests.mjs --list",
@@ -41,6 +41,7 @@
     "verify:platform-skills": "node scripts/generate-platform-skills.mjs --check",
     "generate:video-skills": "node scripts/generate-video-skills.mjs",
     "verify:video-skills": "node scripts/generate-video-skills.mjs --check && node --test scripts/generate-video-skills.test.mjs",
+    "verify:parameter-skill": "node scripts/generate-parameter-skill.mjs --check && node --test scripts/generate-parameter-skill.test.mjs",
     "verify:asset-skills": "node scripts/generate-asset-skills.mjs --check && node --test scripts/generate-asset-skills.test.mjs",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
@@ -52,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.56-beta",
-    "@playcraft/common": "0.1.56-beta",
+    "@playcraft/build": "0.1.58-beta",
+    "@playcraft/common": "0.1.58-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template/.claude/skills/playcraft-runtime-parameters/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: playcraft-runtime-parameters
+description: Initialize or extend configurable parameters in a Cloud Workspace game by extracting real controls, connecting production consumers and a separate development preview, and generating the platform parameter panel from the project declarations.
+compatibility: agent,opencode
+version: 1.0.0
+surfaces:
+  - sandbox-agent
+metadata:
+  protocol: platform-protocol
+---
+
+# Initialize game parameters
+
+Turn the current game into a configurable engineering project. The platform renders its panel from the actual declaration; do not develop a game-specific platform panel. Work in the authorized engineering directory using the current execution mode and permissions.
+
+Read [the parameter protocol](references/platform-protocol.md) before changing configuration, then [development preview integration](references/preview-integration.md) before connecting the game. The runtime supplies the task identity, report path and report structure separately; use those exact values.
+
+## Extract and connect
+
+Inspect the production entry, engine, configuration and real consumers. Preserve existing paths, settings, scripts and gameplay. Reuse existing equivalent parameters before extracting constants. Select a bounded first group of useful controls whose effects can be tested; a game with different behavior should produce different controls. Do not copy a prior game's catalog or expose every constant.
+
+Create or extend the schema, sparse theme overrides and platform labels. Connect a neutral resolver shared by production and preview to real consumers. A field declaration or unused getter alone is incomplete. Keep current visuals and behavior as defaults. Preserve user overrides, translated text and selected resources on repeated initialization.
+
+For each consumed field, select an honest application mode: `live` for an in-place change, `restart-scene` for a change requiring a new game or scene, or `reload` when a new build is necessary. Register only real consumers. At least one meaningful live consumer should be connected when the game supports it; do not mark every field live to make initialization appear successful. Reuse the existing game's start/reset/dispose lifecycle for a restart.
+
+## Validate the generated project
+
+Add or extend `test:parameters` with executable checks for defaults, sparse overrides and changed real-consumer behavior. Keep or restore a successful production `build`; retain an existing `typecheck`. Use the separate preview entry and production release boundary described in the integration reference.
+
+The platform runs its own checks, builds the first development preview and derives capabilities from the real handshake. Report concrete incomplete work when the project cannot be adapted; do not fabricate receipts, successful builds or live capability. Preserve reviewable partial changes on failure.
+
+Initialization may need one preview build because it changes source. Subsequent ordinary value edits must use the connected runtime and existing persistence, without calling the Agent or rebuilding. Keep development runtime modules out of production output under `dist/`.

package/project-template/.claude/skills/playcraft-runtime-parameters/references/platform-protocol.md

@@ -0,0 +1,21 @@
+# Existing parameter protocol
+
+This is the Cloud Workspace-compatible interpretation of the supplied `platform-protocol` skill. Reuse its schema, `xplatform`, platform translations and sparse theme data; do not introduce a parallel `xplatform.parameter` declaration.
+
+## Declaration and defaults
+
+`.playcraft/workspace.json` may declare `parameters: {schemaPath, dataPath, themeId}`. These are engineering-relative paths and the selected theme identity. Preserve unrelated manifest keys. Prefer an existing declaration and theme layout. For a new layout, use `gamePlay.preloaded`, `gamePlay.sections` and `gamePlay.settlement` for the three game-screen areas; organize their children around the current game rather than a sample catalog.
+
+Object nodes use `type: "object"` and `properties`. Leaves use supported primitive types, valid defaults, meaningful units and known bounds or enums. Basic editable leaves support string, finite number, integer, boolean and null. Preserve existing standard `required` arrays. Unsupported references and conditional composition are not a reason to flatten complex data or silently remove constraints.
+
+Missing theme values inherit supported schema defaults. A data file containing `{}` is valid. Editing creates a raw override; restoring a default removes that override. Never write every resolved value into the theme data. Preserve comments, unknown data, unrelated overrides and empty parent objects already present in the project.
+
+Use `i18n.platform.json5` beside the schema with the same tree. `_self.title` and `_self.description` contain `zh` and `en` labels for the panel. Preserve `xplatform.ext.readonly`, ancestor read-only rules and `xplatform.showIf` / `showIfAny`. Visibility controls presentation rather than write permission.
+
+## Specialized values
+
+Image, video and other resource leaves retain `xplatform.value_type: "path"` plus `mime_type`. Preserve their actual theme/shared path resolution and production asset registration. The platform already provides local upload, shared asset library, intelligent production and engineering-file selection; generated adapters consume the selected logical path rather than adding another asset-upload implementation.
+
+Game text retains `xplatform.value_type: "i18n"` and an `i18n.runtime.<key>` reference. Keep global `i18n.runtime.json5` and per-theme `theme.i18n.runtime.json5` semantics and export the text from the real theme entry used in production. Supported languages are `en`, `zh`, `zh-TW`, `de`, `fr`, `es`, `ja`, `ko`, `pt`, `it`, `hi`, `bn`, `ur`, `ar`, `tr`, `ru`, `ms`, `id`. Keep complete language maps for overridden keys and remove an override only when its full value matches the inherited default. Explicit blank strings remain blank rather than falling back to another language.
+
+Arrays, complex structures and unsupported constraints keep their original meaning. Do not disguise them as ordinary primitive controls to obtain a writable panel. An initialization can leave such controls explicitly unsupported while connecting a useful supported set.

package/project-template/.claude/skills/playcraft-runtime-parameters/references/preview-integration.md

@@ -0,0 +1,57 @@
+# Development preview integration
+
+The development SDK (Software Development Kit, 软件开发工具包) is separate from production advertising integration. Obtain it in the current engineering directory with:
+
+```sh
+playcraft preview-runtime init --dir .
+```
+
+It copies versioned modules, types and helpers to `.playcraft/preview-runtime` and refuses to overwrite modified managed files. Read its `README.md`, which documents the actual supported interfaces. Use a separate preview entry; keep the original production entry and advertising language/configuration behavior.
+
+## Actual game lifecycle
+
+Import `connectPreviewRuntime` and `readWorkspacePreviewContext` from the copied `runtime.mjs` using the correct relative path. Read the real configuration contract version and pass the returned context to `connectPreviewRuntime` along with `fields`, `source`, `resolve` and `createGame`.
+
+- `source.get/install` reads and replaces the actual configuration store; `resolve(documents)` shares production default/override rules.
+- Each field registers its actual `documentId`, raw `path`, resolved `effectivePath`, `groupId` and application `mode`.
+- `createGame(context)` returns real `apply`, `restartScene`, `afterRender` and `dispose` behavior. Honor `context.signal` and `context.assertCurrent()` before asynchronous visible changes. `afterRender` waits for a real frame.
+- Live changes preserve progress and object identity where appropriate. Scene restart uses the game's own lifecycle and disposes obsolete objects, timers, event handlers and owned resources.
+- Image consumers use `resource: "image"`, logical paths and `context.loadImage`. Prepare before installation, retain the previous image on a recoverable load failure, and honor explicit same-path refreshes. See the copied guide for resource error and lifecycle behavior.
+
+Do not route development updates through an advertising configuration cache. Real field registration and a version-matched handshake establish capability; an integration report cannot do so.
+
+## Separate build
+
+The project needs a compatible development Vite. Add `build:cloud-preview` invoking `node .playcraft/preview-runtime/build-preview.mjs --entry <actual-preview-entry>` with optional `--config <actual-preview-configuration>` and `--mount-id <actual-container>`. The helper does not implicitly load production Vite configuration. Adapt aliases, data imports, constants and asset handling explicitly when needed; preserve the production build system.
+
+Preserve unrelated workspace manifest fields and add:
+
+```json
+{
+  "previewRuntime": {
+    "version": 1,
+    "buildScript": "build:cloud-preview",
+    "outputPath": ".playcraft-editor-preview/index.html",
+    "reportPath": ".playcraft-editor-preview/report.json",
+    "configContractVersion": "actual-contract-version",
+    "entryPath": "src/preview/runtime.ts",
+    "gameFilePaths": [
+      "src/preview/runtime.ts",
+      "src/game/configuration.ts",
+      "src/game/game.ts",
+      ".playcraft/preview-runtime/runtime.mjs",
+      ".playcraft/preview-runtime/build-preview.mjs"
+    ]
+  }
+}
+```
+
+Replace example paths and contract version with actual existing inputs. Add optional `viteConfigPath` and `mountId` when used, and include all extra configuration inputs in `gameFilePaths`. The platform invokes its trusted packaged helper and supplies `PLAYCRAFT_RUNTIME_PREVIEW_CONTEXT`; manually inventing this context or authoring a successful module report is invalid.
+
+## Production boundary
+
+Production must read the same neutral resolver and saved data while excluding the preview entry and runtime. With Vite, register `previewRuntimeReleaseGuard({root: process.cwd(), previewEntries: [...]})` from the copied `release-guard.mjs` in the actual production plugins, listing the real preview entry. Keep its default report path `.playcraft-editor-preview/release-report.json`; do not override `reportPath`. Configure production output at the engineering root `dist/`.
+
+Initialization admission removes the previous report before the independent production build, then verifies the new report, actual module boundaries and the complete `dist/` artifact hashes. Missing or stale evidence, soft links, changed artifacts or development runtime markers leave initialization unverified. This establishes the stated module/output boundary, not a general audit of every possible plugin. Other builders need equivalent platform-supported evidence; otherwise report the unsupported boundary.
+
+Keep managed runtime files out of parameter report `sources`, `origins` and `consumers`: they are recorded separately by the preview module report. Parameter evidence names the actual game consumer and resolver, not the copied development library. A successful parameter check or production build alone does not prove live behavior or production isolation.

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/templates/preview-runtime/v1/README.md

@@ -22,6 +22,10 @@ Prepare all required images before changing visible objects, call `assertCurrent
 
 `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:

package/templates/preview-runtime/v1/manifest.json

@@ -4,14 +4,14 @@
   "protocolVersion": 1,
   "files": {
     "build-preview.mjs": "2bd512675d829cc07ceddcb58365a6f74d36ff93690f8d72f4bbaa1d45511c91",
-    "README.md": "f104440b3acb23adb88bde0dff23840fa170a14f477d1d7338575eca75e73571",
+    "README.md": "3e35ca2ce6eab84ba8688b400aee8ee5e69458466a13f00e459fd630575d9cbd",
     "release-guard.mjs": "0c33d1559c68844f3760c3e754ee36ca70dc27151ef6f7ad62f29f95239679cc",
     "runtime.d.mts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",
     "runtime.d.ts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",
-    "runtime.mjs": "25b33218ff32dfeaaad7bcd69647cbf662fa4312d49b62724a2104fd27d9b001",
-    "types/adapters.d.ts": "29b5c18d4576ab00eca44875b5c4eae2fc0e0ed6ab5595dbbaf6ba9b9fd8beed",
-    "types/preview.d.ts": "19ea55ed6faf4faa4f4fc62a2d70309d7ba917fc165c2c149856798e1b4197f8",
-    "types/protocol.d.ts": "716e83802336c4e7377abc1b433c77045ed59997a45646fe2fdbe55cb82c5e62",
-    "types/runtime.d.ts": "efcd429b24d75b06afb3f05ec3f8134efc381ede0dd59cb43ec5770e2559c77b"
+    "runtime.mjs": "700c6cb0859ef4b4390d7a1dae41f7e8fa7be7c8dad90b5b48a7e7ee5f90a6a1",
+    "types/adapters.d.ts": "f5e70c4bb9043de1c590eada14266f613286360c809faf26680b0bbbd1cc7b2c",
+    "types/preview.d.ts": "db2e7eb1fa3406ca53fc7c3a4352da061c05af714ead978111ab5118de58db32",
+    "types/protocol.d.ts": "b298d1d35d6e261bbf6a0500f9029f38cad1532bb46475566180b3b92833c507",
+    "types/runtime.d.ts": "f52d08d7b53ff84394381f9d1741a624142f75fac468abf9a5029e98fe172ca4"
   }
 }