@playcraft/cli 0.1.62-beta → 0.1.64

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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.62-beta",
+  "version": "0.1.64",
   "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.62-beta",
-    "@playcraft/common": "0.1.62-beta",
+    "@playcraft/build": "0.1.64",
+    "@playcraft/common": "0.1.64",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -62,6 +62,7 @@
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.3",
     "drizzle-orm": "^0.45.1",
+    "earcut": "3.2.4",
     "execa": "^9.6.1",
     "express": "^5.2.1",
     "fluent-ffmpeg": "^2.1.3",
@@ -81,6 +82,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@noble/hashes": "2.0.1",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/fluent-ffmpeg": "^2.1.28",

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

@@ -1,8 +1,8 @@
 ---
 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.
+description: Initialize or extend configurable parameters in a Cloud Workspace game by extracting real controls and player-visible text, 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
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -21,9 +21,19 @@ Create or extend the schema, sparse theme overrides and platform labels. Connect
 
 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.
 
+## Localize player-visible text
+
+Games usually ship literal strings. By default, initialization also moves a small set of the text a player really sees into platform runtime text, so the panel can edit it per language and the preview can switch its language. Pick the most visible lines (the title, the primary call to action, key instructions or result messages), at most eight keys; text keys count as candidates in the same bounded first group. Author them with the text rules in the parameter protocol and register them as described in the integration reference.
+
+- Extract only text that a real consumer displays and that can be refreshed in place. Skip text baked into images, identifiers, file names, analytics events and any string the game compares or parses.
+- Keep the English default identical to what the game displayed before the change, and write real translations for the other seventeen languages. Keep placeholders and format tokens (for example `[remaining]` or `{count}`) unchanged in every language, and keep existing pluralization or ordering logic working.
+- A game that already localizes its text keeps its own keys, files and language detection; do not add a parallel text system beside it.
+- Finish a text candidate completely (shared resolver, production and preview consumers, tests) or do not add it. An unfinished candidate keeps the whole initialization from verifying, so leave text you cannot finish unchanged and say so in the final response instead of reporting it as blocked.
+- If the game cannot refresh any text in place, keep its text unchanged rather than registering a language switch that does not work.
+
 ## 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.
+Add or extend `test:parameters` with executable checks for defaults, sparse overrides and changed real-consumer behavior. For text, also check that every referenced key has all eighteen languages in the global file, that a theme entry wins over the global one, that a blank string stays blank, that a missing language never borrows English, and that production and preview resolve the same text. 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.
 

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

@@ -19,3 +19,15 @@ Image, video and other resource leaves retain `xplatform.value_type: "path"` plu
 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.
+
+## Authoring new game text
+
+Use this when text the player sees is still a literal in the game. Text the game already exports through its own localization keeps those keys and files.
+
+- **Schema leaf.** `type: "string"`, `default: "i18n.runtime.<key>"`, `xplatform.value_type: "i18n"`, plus the usual platform label. `<key>` is one flat identifier (letters and digits, at most 128 characters, no dots) that names the purpose, such as `headerTitle` or `downloadButton`, not the English wording. A key and its leaf are unique. Theme data does not receive this leaf's value and never contains translated text.
+- **Global defaults.** `i18n.runtime.json5` in the same directory as the schema file. Each key maps every one of the eighteen languages to a string of at most 4096 characters; a key with fewer or more languages is invalid and its field stays disabled. The `en` entry equals the literal the game displayed before, so default behavior and visuals do not change.
+- **Theme overrides.** `theme.i18n.runtime.json5` sits in the same directory as the theme data file and stays sparse. Do not create it for new text: the platform writes it on the first edit and removes a key again when all of its languages match the global default. Keep an existing file untouched.
+- **Report evidence.** The global file, and the theme file when it exists, belong in the report `sources` of every text candidate. The candidate `fieldPath` is the schema leaf path; its origin names where the literal used to live, and its consumers name the code that now displays the resolved text.
+- **Resolution.** Production and preview share one pure function: the theme map when the theme has the key, otherwise the global map; read only the selected language. A missing key or language yields an empty string. Never fall back to English or another language, and keep an explicit blank as blank. Do not mutate either document.
+- **Language selection.** The preview supplies the selected language (see the integration reference). Production keeps the project's own language detection; a project with none uses the `lng` query parameter, then the browser language, then `en`. Normalize to a supported language by exact match, then base language, then `en`; `zh-TW` is a separate language from `zh`.
+- **Delivery.** Production loads both files through its real theme or configuration entry so the delivered package under `dist/` contains the text it needs.

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

@@ -17,6 +17,7 @@ Import `connectPreviewRuntime` and `readWorkspacePreviewContext` from the copied
 - `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.
+- Localized text registers each refreshable `runtimeI18n` key and the `previewContext.locale` language context as `live` fields, resolves with the production rule (selected language only, no cross-language fallback) and updates existing text objects in place. The preview language switch exists only when `previewContext.locale` is registered `live`. See the copied guide for the document shapes and which transported keys to trust.
 
 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.
 

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

@@ -157,8 +157,8 @@
     },
     {
       "skillRef": "remix/playcraft-runtime-parameters",
-      "version": "1.0.0",
-      "artifactHash": "629de8166ca49e4cd3a8797607dcbe1ee378177a743371c96896c4cd7ad1468d",
+      "version": "1.1.0",
+      "artifactHash": "1cef081cdb9aa9861ea6c5b5142c9adc08d2c63615bf0b37bf35c71f3459d1f0",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-runtime-parameters"
     },

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

@@ -26,6 +26,26 @@ The endpoint advertises `canRefreshImages: true` for explicit same-path content
 
 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.
 
+## Localized text parameters
+
+A game whose player-visible text is exported as `i18n.runtime.<key>` references registers each key it can really refresh, plus the language context. Use one group id (for example `localized-text`) for all of them:
+
+```ts
+{ documentId: 'runtimeI18n', path: ['headerTitle'], effectivePath: ['gamePlay', 'sections', 'top', 'title'], groupId: 'localized-text', mode: 'live' },
+{ documentId: 'previewContext', path: ['locale'], effectivePath: ['previewLocale'], groupId: 'localized-text', mode: 'live' },
+```
+
+`path` is the flat text key; `effectivePath` is where the resolved text lands in the game's own configuration. The platform's preview-language switch is enabled only when `previewContext.locale` is registered as `live`, so register it only when the text really refreshes in place; without it the switch stays disabled.
+
+Documents reaching `resolve(documents)`, `source.install` and the `apply` configuration:
+
+- `documents.previewContext.locale` is the language selected in the panel, one of the eighteen supported languages. Normalize it defensively. `binding.locale` is the fixed session contract value and is not the selected language.
+- `documents.runtimeI18n[key]` is `{ [selectedLanguage]: text }`, with the inherited global text already filled in. It never contains another language, so a missing entry means an empty string; do not fall back to English or another language.
+- The snapshot can include keys the game did not register. Take transported text only for the keys you registered; every other key keeps the text bundled in this build.
+- Resolve through the same pure function as production. Do not mutate the documents.
+
+In `apply`, when `context.fields` contains a `localized-text` field, update the existing text objects (`setText`, relayout) rather than recreating the scene, and keep progress, timers, animations and the current screen. Check `context.assertCurrent()` before late side effects, and let `afterRender` wait for the real frame. An empty string is a valid value: hide or collapse the element cleanly instead of showing a placeholder or the key.
+
 ## 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,7 +4,7 @@
   "protocolVersion": 1,
   "files": {
     "build-preview.mjs": "2bd512675d829cc07ceddcb58365a6f74d36ff93690f8d72f4bbaa1d45511c91",
-    "README.md": "3e35ca2ce6eab84ba8688b400aee8ee5e69458466a13f00e459fd630575d9cbd",
+    "README.md": "907bb956f939b3d957ba83789e6131b2f4366fb22a239acda776df4ed22b7db2",
     "release-guard.mjs": "0c33d1559c68844f3760c3e754ee36ca70dc27151ef6f7ad62f29f95239679cc",
     "runtime.d.mts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",
     "runtime.d.ts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",