@playcraft/cli 0.1.55-beta → 0.1.56-beta

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

@@ -6,6 +6,8 @@ import sharp from 'sharp';
 import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } 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 { validateWorkspacePlayable } from '../previews/finalize.js';
+import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
 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)}`; }
@@ -23,13 +25,18 @@ function outputArtifacts(artifacts) {
 export class WorkspaceArtifactStore {
     stateDir;
     workspaceId;
-    constructor(stateDir, workspaceId) {
+    directoryName;
+    constructor(stateDir, workspaceId, directoryName = 'basic') {
         this.stateDir = stateDir;
         this.workspaceId = workspaceId;
+        this.directoryName = directoryName;
+        if (!/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName))
+            throw new Error('invalid_workspace_directory');
     }
+    get scopeId() { return this.directoryName === 'basic' ? this.workspaceId : `${this.workspaceId}:${this.directoryName}`; }
     async directory() {
         await mkdir(this.stateDir, { recursive: true, mode: 0o700 });
-        return artifactDirectory(this.stateDir, `artifacts/${digest(this.workspaceId)}`);
+        return artifactDirectory(this.stateDir, `artifacts/${digest(this.scopeId)}`);
     }
     async read(directory) {
         const handle = await open(join(directory, 'catalog.json'), constants.O_RDONLY | constants.O_NOFOLLOW).catch(error => {
@@ -43,10 +50,13 @@ export class WorkspaceArtifactStore {
             const stat = await handle.stat();
             if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
                 throw new Error('artifact_catalog_invalid');
-            const { receipts, observations = {}, ...body } = JSON.parse(await handle.readFile('utf8'));
+            const { receipts, observations = {}, playable, ...body } = JSON.parse(await handle.readFile('utf8'));
             if (!Array.isArray(receipts) || receipts.some(id => typeof id !== 'string'))
                 throw new Error('artifact_catalog_invalid');
-            return { ...workspaceArtifactListSchema.parse(body), receipts, observations };
+            if (playable && (!Array.isArray(playable.pending) || playable.pending.some(value => typeof value !== 'string')
+                || playable.rejectedDigest !== undefined && !/^[a-f0-9]{64}$/.test(playable.rejectedDigest)))
+                throw new Error('artifact_catalog_invalid');
+            return { ...workspaceArtifactListSchema.parse(body), receipts, observations, ...(playable ? { playable } : {}) };
         }
         finally {
             await handle.close();
@@ -67,10 +77,10 @@ export class WorkspaceArtifactStore {
                 throw error; });
         }
     }
-    async discover(root, source = { kind: 'discovered' }, sourcePaths = []) {
-        const key = `${this.stateDir}\0${this.workspaceId}`;
+    async discover(root, source = { kind: 'discovered' }, sourcePaths = [], playable = {}) {
+        const key = `${this.stateDir}\0${this.scopeId}`;
         const previous = serial.get(key) ?? Promise.resolve();
-        const task = previous.catch(() => undefined).then(() => this.scan(root, source, sourcePaths));
+        const task = previous.catch(() => undefined).then(() => this.scan(root, source, sourcePaths, playable));
         serial.set(key, task);
         try {
             return await task;
@@ -84,11 +94,30 @@ export class WorkspaceArtifactStore {
         const catalog = await this.read(await this.directory());
         return workspaceArtifactListSchema.parse({ artifacts: outputArtifacts(catalog.artifacts), scannedAt: catalog.scannedAt });
     }
-    async scan(root, source, sourcePaths) {
+    async rejectedPlayable(bytes) {
+        return (await this.read(await this.directory())).playable?.rejectedDigest === createHash('sha256').update(bytes).digest('hex');
+    }
+    async hasPendingPlayableExecution(executionId) {
+        return (await this.read(await this.directory())).playable?.pending.some(id => id.split('/').length > 2 && id !== executionId) ?? false;
+    }
+    async isCurrentPlayable(bytes) {
+        const catalog = await this.read(await this.directory());
+        const artifact = catalog.artifacts.find(item => item.kind === 'playable' && item.versions.some(version => version.path === WORKSPACE_PLAYABLE_OUTPUT_PATH));
+        return artifact?.versions.find(item => item.id === artifact.currentVersionId)?.sha256 === createHash('sha256').update(bytes).digest('hex');
+    }
+    async scan(root, source, sourcePaths, playable) {
         const directory = await this.directory();
         const objects = await artifactDirectory(directory, 'objects');
         const catalog = await this.read(directory);
         const original = JSON.stringify(outputArtifacts(catalog.artifacts));
+        const gate = catalog.playable ??= { pending: [] };
+        if (playable.mode === 'skip' || playable.mode === 'failure')
+            gate.initialized = true;
+        if (playable.executionId) {
+            gate.pending = gate.pending.filter(id => id !== playable.executionId && (playable.mode === 'hold' || !id.startsWith(`${playable.executionId}/`)));
+            if (playable.mode === 'hold')
+                gate.pending.push(playable.executionId);
+        }
         const receipts = await this.receipts(root, catalog);
         for (const receipt of receipts) {
             try {
@@ -107,7 +136,12 @@ export class WorkspaceArtifactStore {
                     ...(receipt.width ? { width: receipt.width } : {}), ...(receipt.height ? { height: receipt.height } : {}),
                     ...(receipt.duration !== undefined ? { duration: receipt.duration } : {}),
                 };
-                this.add(catalog, version);
+                const kind = await this.versionKind(objects, version);
+                await this.add(catalog, version, kind, objects);
+                if (kind === 'playable') {
+                    gate.rejectedDigest = undefined;
+                    gate.initialized = true;
+                }
                 catalog.receipts.push(receipt.id);
             }
             catch { /* An incomplete receipt stays pending; the next scan retries its original bytes. */ }
@@ -120,12 +154,17 @@ export class WorkspaceArtifactStore {
         for (const path of candidates) {
             if (members.has(path))
                 continue;
+            if (path === WORKSPACE_PLAYABLE_OUTPUT_PATH && ['hold', 'skip'].includes(playable.mode ?? ''))
+                continue;
+            if (path === WORKSPACE_PLAYABLE_OUTPUT_PATH && gate.initialized && !['success', 'failure'].includes(playable.mode ?? ''))
+                continue;
             try {
-                const current = visible.find(artifact => artifact.id === artifactId(this.workspaceId, path));
+                const current = visible.find(artifact => artifact.id === artifactId(this.scopeId, path));
                 const version = current?.versions.find(entry => entry.id === current.currentVersionId);
                 const knownWrite = sourcePaths.includes(path) && Boolean(source.operationId) && version?.source.operationId !== source.operationId;
                 const observation = catalog.observations[path];
-                if (!knownWrite && version && observation?.versionId === version.id && observation.signature === await fileSignature(root, version.files.map(file => file.path)))
+                if (!knownWrite && version && (path !== WORKSPACE_PLAYABLE_OUTPUT_PATH || current?.kind === 'playable')
+                    && observation?.versionId === version.id && observation.signature === await fileSignature(root, version.files.map(file => file.path)))
                     continue;
                 const thumbnail = version?.files.find(file => file.role === 'thumbnail');
                 const thumbnailPath = thumbnail && await lstat(join(root, thumbnail.path)).then(stat => stat.isFile(), () => false) ? thumbnail.path : undefined;
@@ -137,18 +176,37 @@ export class WorkspaceArtifactStore {
                 for (const file of files)
                     if (file.role !== 'primary')
                         members.add(file.path);
-                if (!knownWrite && version && artifactBundleDigest(version.files) === artifactBundleDigest(files)) {
+                if (!knownWrite && version && (path !== WORKSPACE_PLAYABLE_OUTPUT_PATH || current?.kind === 'playable')
+                    && artifactBundleDigest(version.files) === artifactBundleDigest(files)) {
                     catalog.observations[path] = { signature, versionId: version.id };
                     continue;
                 }
                 const primary = files[0];
+                if (path === WORKSPACE_PLAYABLE_OUTPUT_PATH) {
+                    if (playable.mode === 'failure') {
+                        gate.rejectedDigest = primary.sha256;
+                        gate.initialized = true;
+                        continue;
+                    }
+                    if (playable.mode === 'success'
+                        ? gate.pending.some(id => id.split('/').length > 2)
+                        : gate.pending.length > 0)
+                        continue;
+                    if (gate.rejectedDigest === primary.sha256 && !playable.force)
+                        continue;
+                }
                 const next = {
                     id: `version_${knownWrite ? source.operationId : randomUUID()}`, createdAt: new Date().toISOString(),
                     path, mimeType: primary.mimeType, size: primary.size, sha256: primary.sha256, files,
                     source: sourcePaths.includes(path) ? source : { kind: 'discovered' },
                     ...await this.dimensions(objects, primary),
                 };
-                this.add(catalog, next);
+                const kind = await this.versionKind(objects, next);
+                await this.add(catalog, next, kind, objects);
+                if (kind === 'playable') {
+                    gate.rejectedDigest = undefined;
+                    gate.initialized = true;
+                }
                 catalog.observations[path] = { signature, versionId: next.id };
             }
             catch { /* Files being written or temporarily missing are retried, never published as complete. */ }
@@ -163,13 +221,51 @@ export class WorkspaceArtifactStore {
         await this.write(directory, catalog);
         return { list, changed: original !== JSON.stringify(list.artifacts) };
     }
-    add(catalog, version) {
-        const id = artifactId(this.workspaceId, version.path);
+    async versionKind(objects, version) {
+        if (version.path !== WORKSPACE_PLAYABLE_OUTPUT_PATH)
+            return artifactFormat(version.path)[0];
+        if (version.files.length !== 1)
+            throw new Error('preview_not_single_file');
+        const primary = version.files[0];
+        const file = await open(join(objects, primary.sha256), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > PREVIEW_HTML_MAX_BYTES)
+                throw new Error('preview_not_single_file');
+            const bytes = await file.readFile();
+            if (bytes.length !== primary.size || createHash('sha256').update(bytes).digest('hex') !== primary.sha256)
+                throw new Error('artifact_snapshot_invalid');
+            validateWorkspacePlayable(bytes);
+        }
+        finally {
+            await file.close();
+        }
+        return 'playable';
+    }
+    async add(catalog, version, kind, objects) {
+        const id = artifactId(this.scopeId, version.path);
         let artifact = catalog.artifacts.find(item => item.id === id);
         if (!artifact) {
-            artifact = { id, kind: artifactFormat(version.path)[0], name: basename(version.path), currentVersionId: version.id, updatedAt: version.createdAt, versions: [] };
+            artifact = { id, kind, name: basename(version.path), currentVersionId: version.id, updatedAt: version.createdAt, versions: [] };
             catalog.artifacts.push(artifact);
         }
+        if (kind === 'playable' && artifact.kind !== 'playable') {
+            const valid = await Promise.all(artifact.versions.map(async (item) => {
+                try {
+                    return await this.versionKind(objects, item) === 'playable' ? item : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }));
+            artifact.versions = valid.filter((item) => Boolean(item));
+        }
+        artifact.kind = kind;
+        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))
+            return;
         if (!artifact.versions.some(item => item.id === version.id)) {
             // Display ordering is monotonic; the original generation time stays in source.generatedAt.
             const latest = Math.max(0, ...artifact.versions.map(item => Date.parse(item.createdAt)));
@@ -191,7 +287,9 @@ export class WorkspaceArtifactStore {
             return [];
         }
         const seen = new Set(catalog.receipts), receipts = [];
-        for (const name of await readdir(directory)) {
+        // A receipt tree the current identity cannot read is skipped rather than failing the scan.
+        const names = await readdir(directory).catch(() => []);
+        for (const name of names) {
             if (!/^[a-f0-9-]{36}\.json$/.test(name) || seen.has(name.slice(0, -5)))
                 continue;
             try {

package/dist/workspace-runtime/workspaces/asset-publication-access.js

@@ -5,11 +5,15 @@ async function shareWithWorkspaceGroup(root, handle, directory) {
     if (!workspace.isDirectory() || workspace.isSymbolicLink()
         || (directory ? !target.isDirectory() : !target.isFile() || target.nlink !== 1))
         throw new Error('invalid_workspace_asset');
+    const shared = directory ? 0o2770 : 0o660;
+    // Already shared: the other identity owns this entry and cannot re-shape it from here.
+    if (target.gid === workspace.gid && (target.mode & 0o7777) === shared)
+        return;
     if (target.gid !== workspace.gid)
         await handle.chown(target.uid, workspace.gid);
     // Match directory-access.ts: the development group can read and edit public project files.
     // Private transfers, chunks, transaction records and backups never use these helpers.
-    await handle.chmod(directory ? 0o2770 : 0o660);
+    await handle.chmod(shared);
 }
 export async function shareWorkspaceAssetFile(root, handle) {
     await shareWithWorkspaceGroup(root, handle, false);

package/dist/workspace-runtime/workspaces/delivery-build.js

@@ -1,15 +1,22 @@
 import { randomUUID } from 'node:crypto';
-import { copyFile, mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { constants } from 'node:fs';
+import { copyFile, cp, chmod, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { createPlatformAdapter, getChannelRuleProfile, } from '@playcraft/build';
 import { DELIVERY_QUEUE_LIMIT, isWorkspaceArtifactOutputPath, } from '@playcraft/common/cloud-workspace/runtime';
 import { workspaceRoot } from './registry.js';
 import { excludeFromGit, ensureWorkspaceDependencies } from './dependencies.js';
+import { listWorkspaceBuildInputs } from './git.js';
 import { runDeveloperCommand } from './developer-command.js';
+import { openScratchToDevelopment } from './directory-access.js';
 import { DeliveryStore } from './delivery-store.js';
 import { DeliveryValidationError, validateDeliveryArtifact } from './delivery.js';
 export const DELIVERY_BUILD_TIMEOUT_MS = 10 * 60_000;
+/** Staging under the workspace from earlier runtimes; kept out of Git so leftovers never commit. */
 const STAGING_DIRECTORY = '.playcraft-delivery';
+/** Never copied into the build copy: history, outputs and caches that the build neither reads nor owns. */
+const ISOLATE_SKIP = new Set(['.git', 'dist', '.turbo', STAGING_DIRECTORY]);
 export class DeliveryBuildError extends Error {
     code;
     constructor(code) {
@@ -204,9 +211,77 @@ async function copyToDist(root, staging, channel, format) {
     }
     return { primary: `dist/delivery/${channel}/${primary}`, paths, sizeBytes };
 }
+/** Copy-on-write clone where the filesystem supports it (APFS, btrfs, XFS); a plain copy elsewhere. */
+const CLONE = constants.COPYFILE_FICLONE;
+const COPY_CONCURRENCY = 16;
+function skipped(path) {
+    const parts = path.split(/[\\/]/);
+    return ISOLATE_SKIP.has(parts[0]) || parts.includes('node_modules');
+}
+async function copyInput(root, destination, path) {
+    const source = join(root, path);
+    const target = join(destination, path);
+    let entry;
+    try {
+        entry = await lstat(source);
+    }
+    catch (error) {
+        // A tracked file deleted in the work tree is not a build input.
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    if (entry.isSymbolicLink())
+        await symlink(await readlink(source), target);
+    else if (entry.isDirectory())
+        await cp(source, target, { recursive: true, verbatimSymlinks: true, mode: CLONE });
+    else
+        await copyFile(source, target, CLONE);
+}
 /**
- * Runs one channel build. The build writes into a disposable staging directory; only the final
- * artifact is copied into dist so the builder's `--clean` can never erase another delivery.
+ * Copies the workspace into `destination` for one build, like the platform export runner, with the
+ * top-level `node_modules` linked (the build only reads it). Builders rewrite project files in place
+ * (`builds.config.js` and its `.bak`, `package.json` scripts, migrated imports), so the build must
+ * never run in the workspace itself, where autosave would commit those rewrites.
+ *
+ * Only the files Git would carry are copied: tracked ones and untracked ones `.gitignore` keeps, so
+ * caches, logs and local outputs stay behind. Without a repository the whole tree is copied.
+ */
+export async function isolateWorkspaceForBuild(root, destination) {
+    await mkdir(destination, { recursive: true });
+    // The build runs as the development identity and writes its scratch folder inside this copy.
+    await chmod(destination, 0o2770);
+    const modules = join(root, 'node_modules');
+    const modulesEntry = await lstat(modules).catch(() => undefined);
+    if (modulesEntry?.isDirectory() || modulesEntry?.isSymbolicLink()) {
+        await symlink(modulesEntry.isSymbolicLink() ? await readlink(modules) : modules, join(destination, 'node_modules'), 'dir');
+    }
+    const inputs = await listWorkspaceBuildInputs(root).catch(() => undefined);
+    const paths = inputs
+        ?? (await readdir(root)).filter((name) => name !== 'node_modules');
+    const queue = paths.filter((path) => !skipped(path));
+    const workers = Array.from({ length: Math.min(COPY_CONCURRENCY, queue.length) }, async () => {
+        for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+            if (inputs)
+                await copyInput(root, destination, path);
+            else {
+                await cp(join(root, path), join(destination, path), {
+                    recursive: true,
+                    verbatimSymlinks: true,
+                    mode: CLONE,
+                    // Nested dependency folders stay out as well; the build resolves through the linked root.
+                    filter: (source) => !relative(join(root, path), source).split(sep).includes('node_modules'),
+                });
+            }
+        }
+    });
+    await Promise.all(workers);
+}
+/**
+ * Runs one channel build in a disposable copy of the workspace. The build writes into a disposable
+ * output directory; only the final artifact is copied into dist so the builder's `--clean` can never
+ * erase another delivery.
  */
 async function executeBuild(state, input, controller) {
     if (input.directoryName === 'root')
@@ -226,7 +301,8 @@ async function executeBuild(state, input, controller) {
         startedAt,
     };
     await store.write(base);
-    const staging = join(root, STAGING_DIRECTORY, input.buildId);
+    let scratch;
+    let staging = '';
     let status = 'running';
     let error;
     let validationError;
@@ -238,7 +314,13 @@ async function executeBuild(state, input, controller) {
     let logChain = Promise.resolve();
     let record;
     try {
+        scratch = await mkdtemp(join(tmpdir(), 'playcraft-delivery-'));
+        // The build runs as the development identity while this scratch tree belongs to the controller.
+        await openScratchToDevelopment(scratch, (await lstat(root)).gid);
+        staging = join(scratch, 'output');
+        const project = join(scratch, 'project');
         await mkdir(staging, { recursive: true });
+        await chmod(staging, 0o2770);
         await excludeFromGit(root, `/${STAGING_DIRECTORY}/`);
         await excludeFromGit(root, '/dist/');
         const dependencies = await ensureWorkspaceDependencies(state, input.workspaceId, root);
@@ -248,11 +330,17 @@ async function executeBuild(state, input, controller) {
             }
             throw new DeliveryBuildError('delivery_dependencies_failed');
         }
+        try {
+            await isolateWorkspaceForBuild(root, project);
+        }
+        catch {
+            throw new DeliveryBuildError('delivery_isolation_failed');
+        }
         const planned = process.env.PLAYCRAFT_DELIVERY_BUILD_COMMAND || 'playcraft build';
         const command = `umask 002 && NO_COLOR=1 CI=1 ${planned} . --platform ${input.payload.channel} --format ${input.payload.format} --output ${shellQuote(staging)} --mode full`;
         const outcome = await runDeveloperCommand(state, {
             processId: `delivery-${input.buildId}`,
-            cwd: root,
+            cwd: project,
             command,
             timeoutMs: DELIVERY_BUILD_TIMEOUT_MS,
             signal: controller.signal,
@@ -304,7 +392,9 @@ async function executeBuild(state, input, controller) {
         error = cause instanceof DeliveryBuildError ? cause.code : 'delivery_build_failed';
     }
     finally {
-        await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        // `rm` removes the node_modules link, never its target.
+        if (scratch)
+            await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
         await logChain;
         if (report) {
             await store.writeReport(input.buildId, report).catch(() => {

package/dist/workspace-runtime/workspaces/directory-access.js

@@ -9,6 +9,19 @@ export async function grantWorkspaceTraversal(root, groupId) {
         await chown(root, stat.uid, groupId);
     await chmod(root, (stat.mode & 0o777) | 0o2010);
 }
+/**
+ * The controller creates scratch trees under /tmp, but builds run as the development identity
+ * through the launcher. Without group ownership and group write the command cannot even stat its
+ * own cwd, and every build fails with EACCES before it starts.
+ */
+export async function openScratchToDevelopment(path, groupId) {
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('invalid_scratch_directory');
+    if (stat.gid !== groupId)
+        await chown(path, stat.uid, groupId);
+    await chmod(path, 0o2770);
+}
 /** The sandbox development group can edit engine directories. Symlinks never grant access outside the tree. */
 export async function openDirectoryToDevelopment(root, groupId) {
     const currentUid = typeof process.getuid === 'function' ? process.getuid() : undefined;

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

@@ -31,6 +31,19 @@ export async function probeGitBinary() {
         return error instanceof GitWorkspaceError && error.code === 'git_binary_missing' ? false : false;
     }
 }
+/**
+ * Files a build may read: tracked ones plus untracked ones that `.gitignore` does not exclude, the
+ * same inputs a clone of the pushed branch would have. Undefined when the workspace has no repository.
+ */
+export async function listWorkspaceBuildInputs(root) {
+    const rootReal = await realpath(root);
+    if (!(await gitMarkerExists(rootReal)))
+        return undefined;
+    const listed = await gitAllowFail(rootReal, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], 60000);
+    if (listed.code !== 0)
+        return undefined;
+    return [...new Set(listed.stdout.split('\0').filter(Boolean))];
+}
 export async function readWorkspaceGitStatus(root) {
     const rootReal = await ensureWorkspaceGit(root);
     const branchResult = await gitAllowFail(rootReal, ['symbolic-ref', '--short', 'HEAD']);

package/dist/workspace-runtime/workspaces/parameter-assets.js

@@ -5,7 +5,7 @@ import { dirname, join, posix } from 'node:path';
 import sharp from 'sharp';
 import { AssetGenerationVideoValidator, parameterAssetFilePath, parameterAssetMimeType, parameterAssetValueError, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactPath } from './artifact-files.js';
-import { registerThemeAsset } from './theme-asset-index.js';
+import { registerThemeAsset, themeAssetIndexFingerprint } from './theme-asset-index.js';
 export class ParameterAssetError extends Error {
     code;
     constructor(code) {
@@ -83,9 +83,13 @@ export async function validateParameterAssetFile(root, dataPath, value, asset) {
             }
         }
         const after = await file.stat(), pathStat = await lstat(await artifactPath(root, relative));
-        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
-            || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
-            || after.dev !== pathStat.dev || after.ino !== pathStat.ino)
+        if (before.dev !== after.dev ||
+            before.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs ||
+            after.dev !== pathStat.dev ||
+            after.ino !== pathStat.ino)
             throw new ParameterAssetError('parameter_asset_file_changed');
     }
     catch (error) {
@@ -99,7 +103,7 @@ export async function validateParameterAssetFile(root, dataPath, value, asset) {
     return relative;
 }
 /** Prepare all registry edits before changing any project file. Unknown registries stay untouched. */
-export async function prepareParameterAssetRegistration(root, dataPath, bindings) {
+export async function prepareParameterAssetRegistration(root, dataPath, bindings, requiredImageValues = []) {
     if (!bindings.length)
         return undefined;
     if (!/^src\/theme\/[A-Za-z0-9_-]+\/theme\.data\.json5$/.test(dataPath))
@@ -123,7 +127,14 @@ export async function prepareParameterAssetRegistration(root, dataPath, bindings
             importPath = './' + importPath;
         next = registerThemeAsset(next, value, importPath);
     }
-    return next === source ? undefined : { path: index, previousHash: digest(source), content: next };
+    return next === source
+        ? undefined
+        : {
+            path: index,
+            previousHash: digest(source),
+            previousFingerprint: themeAssetIndexFingerprint(source, requiredImageValues),
+            content: next,
+        };
 }
 /** Stage complete bytes and original metadata before atomically replacing the unchanged registry. */
 export async function writeParameterAssetRegistration(root, plan) {
@@ -141,7 +152,10 @@ export async function writeParameterAssetRegistration(root, plan) {
     let published = false;
     try {
         const before = await file.stat();
-        if (!before.isFile() || before.nlink !== 1 || before.size > 1024 * 1024 || digest(await file.readFile()) !== plan.previousHash)
+        if (!before.isFile() ||
+            before.nlink !== 1 ||
+            before.size > 1024 * 1024 ||
+            digest(await file.readFile()) !== plan.previousHash)
             throw new ParameterAssetError('parameter_asset_index_conflict');
         const parent = await lstat(dirname(target));
         const bytes = Buffer.from(plan.content);
@@ -161,14 +175,21 @@ export async function writeParameterAssetRegistration(root, plan) {
         await staged.close();
         staged = undefined;
         const current = await lstat(await artifactPath(root, plan.path)), currentParent = await lstat(dirname(target));
-        if (before.dev !== current.dev || before.ino !== current.ino || before.mtimeMs !== current.mtimeMs || before.ctimeMs !== current.ctimeMs
-            || parent.dev !== currentParent.dev || parent.ino !== currentParent.ino
-            || digest(await readFile(await artifactPath(root, plan.path))) !== plan.previousHash
-            || digest(await readFile(temporary)) !== digest(bytes))
+        if (before.dev !== current.dev ||
+            before.ino !== current.ino ||
+            before.mtimeMs !== current.mtimeMs ||
+            before.ctimeMs !== current.ctimeMs ||
+            parent.dev !== currentParent.dev ||
+            parent.ino !== currentParent.ino ||
+            digest(await readFile(await artifactPath(root, plan.path))) !== plan.previousHash ||
+            digest(await readFile(temporary)) !== digest(bytes))
             throw new ParameterAssetError('parameter_asset_index_conflict');
-        const temporaryPath = plan.path.slice(0, plan.path.lastIndexOf('/') + 1) + temporary.slice(temporary.lastIndexOf('/') + 1);
+        const temporaryPath = plan.path.slice(0, plan.path.lastIndexOf('/') + 1) +
+            temporary.slice(temporary.lastIndexOf('/') + 1);
         const checkedStage = await lstat(await artifactPath(root, temporaryPath));
-        if (checkedStage.dev !== stagedStat.dev || checkedStage.ino !== stagedStat.ino || checkedStage.nlink !== 1)
+        if (checkedStage.dev !== stagedStat.dev ||
+            checkedStage.ino !== stagedStat.ino ||
+            checkedStage.nlink !== 1)
             throw new ParameterAssetError('parameter_asset_index_conflict');
         await rename(temporary, target);
         published = true;
@@ -183,7 +204,9 @@ export async function writeParameterAssetRegistration(root, plan) {
         await staged?.close();
         await file.close();
         if (!published)
-            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
-                throw error; });
+            await unlink(temporary).catch((error) => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
     }
 }