castle-web-cli 0.4.122 → 0.4.124

package/dist/versions.js

@@ -0,0 +1,446 @@
+// save-version / list-versions / restore-version.
+//
+// A version is a manual commit of the deck's files. Storage details are in
+// versionStore.ts; this file is the behavior:
+//
+//   save-version              hashes the whole tree and records what moved
+//   save-version <paths...>   records ONLY those paths -- a curated state, not
+//                             the working tree at that moment
+//   list-versions [<id>]      walks back from head (or from the given version)
+//   restore-version <id>      puts the working tree back to that version,
+//                             touching only paths some later version touched
+import * as fs from 'fs';
+import * as path from 'path';
+import { customAlphabet } from 'nanoid';
+import { looksBinary, unifiedDiff } from './diffText.js';
+import { COVER_FILE } from './localPaths.js';
+import * as store from './versionStore.js';
+// Version ids are alphanumeric on purpose: they are filenames, command-line
+// positionals and (later) url segments, and nanoid's default alphabet includes
+// `-`, which reads as a flag wherever an id is typed.
+const newVersionId = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', 12);
+function resolveProjectDir(dir) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(projectDir))
+        throw new Error(`No such directory: ${projectDir}`);
+    return projectDir;
+}
+// A path on the command line may name a directory, which stands for every
+// tracked file under it -- on disk AND in the parent manifest, so deleting a
+// whole directory and saving it still records the deletions.
+function expandSelection(projectDir, given, parentFiles) {
+    const workingFiles = store.walkDeckFiles(projectDir);
+    const selected = new Set();
+    for (const raw of given) {
+        const rel = store.toDeckRelative(projectDir, raw);
+        if (!rel)
+            throw new Error(`Path is outside the deck: ${raw}`);
+        if (store.isIgnoredPath(rel))
+            throw new Error(`Path is not tracked: ${rel}`);
+        const isDir = fs.existsSync(path.join(projectDir, rel)) && fs.statSync(path.join(projectDir, rel)).isDirectory();
+        if (isDir) {
+            const prefix = `${rel}/`;
+            for (const p of workingFiles)
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            for (const p of Object.keys(parentFiles))
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            continue;
+        }
+        if (!fs.existsSync(path.join(projectDir, rel)) && !(rel in parentFiles)) {
+            throw new Error(`No such file: ${rel}`);
+        }
+        selected.add(rel);
+    }
+    return [...selected].sort();
+}
+// The whole tree becomes the manifest. Content is stored as we go, so an
+// unchanged file costs a read and a hash and writes nothing new.
+function manifestFromTree(projectDir) {
+    const files = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+    }
+    return files;
+}
+// The parent's manifest with only the selected paths overridden. Everything
+// else keeps the parent's hash -- so the version describes a curated state, and
+// the paths left out stay dirty on disk for the next save to pick up.
+function manifestFromSelection(projectDir, parentFiles, selected) {
+    const files = { ...parentFiles };
+    for (const rel of selected) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+        else
+            delete files[rel];
+    }
+    return files;
+}
+// The save itself, with no output -- what the CLI command and the editor's
+// Save version button both run.
+export function createVersion(projectDir, opts = {}) {
+    const parentId = store.readHead(projectDir);
+    const parentFiles = store.parentManifest(projectDir, parentId);
+    const given = opts.paths ?? [];
+    const selected = given.length > 0 ? expandSelection(projectDir, given, parentFiles) : null;
+    const files = selected
+        ? manifestFromSelection(projectDir, parentFiles, selected)
+        : manifestFromTree(projectDir);
+    const changes = store.diffManifests(parentFiles, files, selected ?? undefined);
+    if (Object.keys(changes).length === 0)
+        return { version: null, partial: selected !== null };
+    const version = {
+        id: newVersionId(),
+        parentId,
+        createdAt: new Date().toISOString(),
+        message: opts.message ?? '',
+        files,
+        changes,
+    };
+    store.writeVersion(projectDir, version);
+    store.writeHead(projectDir, version.id);
+    return { version, partial: selected !== null };
+}
+export function saveVersion(dir, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    const { version, partial } = createVersion(projectDir, opts);
+    if (!version) {
+        console.log(partial ? 'No changes in the selected paths. Nothing saved.' : 'No changes. Nothing saved.');
+        return;
+    }
+    const changes = version.changes;
+    const count = Object.keys(changes).length;
+    console.log(`Saved version ${version.id} (${count} file${count === 1 ? '' : 's'} changed).`);
+    for (const [p, change] of Object.entries(changes)) {
+        const mark = change.before === null ? 'added' : change.after === null ? 'deleted' : 'changed';
+        console.log(`  ${mark}  ${p}`);
+    }
+    if (partial) {
+        console.log('Partial save: unselected files are still dirty on disk.');
+    }
+}
+// The deck cover is rewritten every time the deck is played, so it is
+// permanently dirty. It is versioned and restored like any other file, but it
+// never counts as a change worth reporting and never blocks a restore -- the
+// old cover it writes back regenerates on the next play. Without this, every
+// restore refused on a file nobody edited.
+function isReportableChange(path) {
+    return path !== COVER_FILE;
+}
+function changeKind(change) {
+    if (change.before === null)
+        return 'added';
+    if (change.after === null)
+        return 'deleted';
+    return 'changed';
+}
+/**
+ * What has changed on disk since head, in the same shape a version's `changes`
+ * takes. Hashes the tree WITHOUT storing anything -- asking what is outstanding
+ * must not write to the store.
+ */
+export function pendingChanges(projectDir) {
+    const headFiles = store.parentManifest(projectDir, store.readHead(projectDir));
+    const current = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.hashWorkingFile(projectDir, rel);
+        if (hash)
+            current[rel] = hash;
+    }
+    return Object.entries(store.diffManifests(headFiles, current))
+        .filter(([path]) => isReportableChange(path))
+        .map(([path, change]) => ({ path, kind: changeKind(change) }));
+}
+function toSummary(version, later) {
+    return {
+        id: version.id,
+        parentId: version.parentId,
+        createdAt: version.createdAt,
+        message: version.message,
+        changes: Object.entries(version.changes)
+            .filter(([path]) => isReportableChange(path))
+            .map(([path, change]) => ({ path, kind: changeKind(change) })),
+        later,
+    };
+}
+/**
+ * The deck's history newest first. From head (no `fromId`): the chain forward
+ * from head -- marked `later` -- then head, then its ancestors. From a named
+ * version: that version and its ancestors, as it has always been.
+ *
+ * The forward walk is why a restore no longer makes the versions after it
+ * vanish from the panel and from `list-versions`. It follows one chain of
+ * children, newest child at each step. After a save there is nothing to follow,
+ * because the new version is a leaf, so the forward rows drop away on their own
+ * -- the abandoned versions are still on disk, just no longer reachable forward
+ * from head.
+ *
+ * Naming a version asks a different question -- how did THIS version come to be
+ * -- so that form stays a walk back and is unchanged.
+ */
+export function versionSummaries(projectDir, fromId) {
+    const startId = fromId ?? store.readHead(projectDir);
+    if (!startId)
+        return [];
+    if (!store.versionExists(projectDir, startId))
+        throw new Error(`No such version: ${startId}`);
+    const forward = fromId ? [] : store.forwardChain(projectDir, startId);
+    return [
+        // Nearest child first out of the walk, so reverse it: the furthest
+        // descendant is the newest thing there is.
+        ...[...forward].reverse().map((v) => toSummary(v, true)),
+        ...store.versionChain(projectDir, startId).map((v) => toSummary(v, false)),
+    ];
+}
+export function listVersions(dir, version) {
+    const summaries = versionSummaries(resolveProjectDir(dir), version);
+    if (summaries.length === 0) {
+        console.log('No versions yet.');
+        return;
+    }
+    for (const v of summaries) {
+        const count = v.changes.length;
+        const message = v.message ? `  ${v.message}` : '';
+        // The same history the panel shows, marked the same way, so the two never
+        // disagree about what happened.
+        const later = v.later ? '  (later)' : '';
+        console.log(`${v.id}  ${v.createdAt}  ${count} file${count === 1 ? '' : 's'}${later}${message}`);
+    }
+}
+// One file's side of a change, as text -- or null when it wasn't there (an add
+// or a delete) and `binary: true` when it must not be rendered as a patch.
+function blobText(projectDir, hash) {
+    if (hash === null)
+        return null;
+    const content = store.getBlob(projectDir, hash);
+    return looksBinary(content) ? { text: '', binary: true } : { text: content.toString('utf8'), binary: false };
+}
+function showFileChange(projectDir, filePath, change) {
+    const kind = changeKind(change);
+    const before = blobText(projectDir, change.before);
+    const after = blobText(projectDir, change.after);
+    // A sprite or an image must never come out as a garbled patch; a line saying
+    // what happened to it is the whole useful answer.
+    if (before?.binary || after?.binary) {
+        console.log(`${filePath}  ${kind}, binary`);
+        return;
+    }
+    console.log(`${filePath}  ${kind}`);
+    const hunks = unifiedDiff(before?.text ?? '', after?.text ?? '');
+    if (!hunks) {
+        console.log('  (too large to show as a diff)');
+        return;
+    }
+    for (const line of hunks)
+        console.log(line);
+}
+/**
+ * What one version changed, as diffs of the CHANGED FILES ONLY -- built from the
+ * two blobs each entry in `changes` already names, so nothing new is stored and
+ * the whole tree is never read. The CLI counterpart of the panel's row
+ * expansion, for an agent working out what a change did.
+ */
+export function showVersion(dir, versionId) {
+    const projectDir = resolveProjectDir(dir);
+    if (!store.versionExists(projectDir, versionId))
+        throw new Error(`No such version: ${versionId}`);
+    const version = store.readVersion(projectDir, versionId);
+    const paths = Object.keys(version.changes).sort();
+    console.log(`${version.id}  ${version.createdAt}  ${paths.length} file${paths.length === 1 ? '' : 's'}`);
+    if (version.message)
+        console.log(version.message);
+    console.log('');
+    for (const filePath of paths) {
+        showFileChange(projectDir, filePath, version.changes[filePath]);
+        console.log('');
+    }
+}
+/**
+ * The versions from `from` back to `to`, exclusive of `to`, newest first -- or
+ * null when `to` is not an ancestor of `from`. Only `parentId` is stored, so
+ * this is the only direction the history can be walked directly.
+ */
+function chainDownTo(projectDir, from, to) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = from;
+    while (cursor && cursor !== to) {
+        if (seen.has(cursor))
+            throw new Error(`Version history loops at ${cursor}`);
+        seen.add(cursor);
+        const version = store.readVersion(projectDir, cursor);
+        chain.push(version);
+        cursor = version.parentId;
+    }
+    return cursor === to ? chain : null;
+}
+/**
+ * What a restore should write, and what it expects to find on disk first.
+ *
+ * The two directions are mirrors of each other over the SAME set of versions --
+ * the ones between head and the target -- read from opposite ends:
+ *
+ *   backward (the target is an ancestor of head): put back the EARLIEST
+ *     `before`, the state closest to the target; expect the LATEST `after`, the
+ *     state closest to head.
+ *   forward (the target is a descendant of head): put back the LATEST `after`,
+ *     again the state closest to the target; expect the EARLIEST `before`,
+ *     again the state closest to head.
+ *
+ * Either way a path no version between the two touched never enters the plan,
+ * so unsaved work on it survives.
+ */
+function planRestore(projectDir, targetId) {
+    const head = store.readHead(projectDir);
+    if (!head)
+        throw new Error('No versions yet.');
+    const backward = chainDownTo(projectDir, head, targetId);
+    if (backward)
+        return planFromChain(backward, 'backward');
+    const forward = chainDownTo(projectDir, targetId, head);
+    if (forward)
+        return planFromChain(forward, 'forward');
+    throw new NotOnThisLine(targetId, head);
+}
+// `chain` is always newest first, so "first seen wins" reads the end nearest the
+// newer version and "last write wins" reads the end nearest the older one.
+function planFromChain(chain, direction) {
+    const plan = {
+        wanted: {},
+        expected: {},
+        offChain: direction === 'backward' ? chain.length : 0,
+    };
+    for (const version of chain) {
+        for (const [p, change] of Object.entries(version.changes)) {
+            if (direction === 'backward') {
+                plan.wanted[p] = change.before;
+                if (!(p in plan.expected))
+                    plan.expected[p] = change.after;
+            }
+            else {
+                if (!(p in plan.wanted))
+                    plan.wanted[p] = change.after;
+                plan.expected[p] = change.before;
+            }
+        }
+    }
+    return plan;
+}
+function removeEmptyParents(projectDir, relPath) {
+    let dir = path.dirname(path.join(projectDir, relPath));
+    while (dir.startsWith(projectDir) && dir !== projectDir) {
+        try {
+            if (fs.readdirSync(dir).length > 0)
+                return;
+            fs.rmdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        dir = path.dirname(dir);
+    }
+}
+function applyRestore(projectDir, actions) {
+    for (const [rel, hash] of actions) {
+        const abs = path.join(projectDir, rel);
+        if (hash === null) {
+            fs.rmSync(abs, { force: true });
+            removeEmptyParents(projectDir, rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, store.getBlob(projectDir, hash));
+    }
+}
+// Work no version has recorded, which a restore would overwrite. The paths ARE
+// the answer to "what would I lose", so they ride on the error and each caller
+// says what to do about it -- the CLI offers `--force`, the panel has no such
+// thing and says to save a version first.
+export class UnsavedChanges extends Error {
+    paths;
+    constructor(paths) {
+        const count = paths.length;
+        super(`Unsaved changes would be lost in ${count} file${count === 1 ? '' : 's'}:\n` +
+            paths.map((p) => `  ${p}`).join('\n'));
+        this.name = 'UnsavedChanges';
+        this.paths = paths;
+    }
+}
+// A version on a different branch: neither an ancestor of head nor a descendant
+// of it. Restore moves along one line in either direction; getting from here to
+// there would mean merging, which is not something this build does silently.
+export class NotOnThisLine extends Error {
+    constructor(targetId, head) {
+        super(`Version ${targetId} is on a different branch than ${head}. ` +
+            'Restore moves back or forward along one line, not across a fork.');
+        this.name = 'NotOnThisLine';
+    }
+}
+// The restore itself, with no output. Throws on unsaved changes unless forced --
+// the message names every conflicting path, since that list IS the answer to
+// "what would I lose".
+export function applyVersionRestore(projectDir, targetId, opts = {}) {
+    if (!store.versionExists(projectDir, targetId))
+        throw new Error(`No such version: ${targetId}`);
+    if (store.readHead(projectDir) === targetId) {
+        return { alreadyThere: true, applied: [], offChain: 0 };
+    }
+    const plan = planRestore(projectDir, targetId);
+    // Only paths whose content would actually move are checked and applied: a
+    // path already holding what the restore wants is neither a conflict nor work.
+    const actions = [];
+    const conflicts = [];
+    for (const [rel, wanted] of Object.entries(plan.wanted)) {
+        const current = store.hashWorkingFile(projectDir, rel);
+        if (current === wanted)
+            continue;
+        // The cover is exempt: it is dirty by construction, so refusing on it would
+        // refuse every restore. It still gets written back.
+        if (current !== plan.expected[rel] && isReportableChange(rel))
+            conflicts.push(rel);
+        actions.push([rel, wanted]);
+    }
+    if (conflicts.length > 0 && !opts.force)
+        throw new UnsavedChanges(conflicts.sort());
+    applyRestore(projectDir, actions.sort((a, b) => a[0].localeCompare(b[0])));
+    // Head moves to the target, so the next save continues from there and the
+    // versions we walked past fork off. They stay on disk and stay loadable by
+    // id -- they are just no longer on head's chain.
+    store.writeHead(projectDir, targetId);
+    return { alreadyThere: false, applied: actions, offChain: plan.offChain };
+}
+export function restoreVersion(dir, targetId, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    let outcome;
+    try {
+        outcome = applyVersionRestore(projectDir, targetId, opts);
+    }
+    catch (e) {
+        // Only the command line has a --force, so only the command line mentions it.
+        if (e instanceof UnsavedChanges) {
+            throw new Error(`${e.message}\nSave a version first, or pass --force to restore anyway.`);
+        }
+        throw e;
+    }
+    if (outcome.alreadyThere) {
+        console.log(`Already at version ${targetId}. Nothing to restore.`);
+        return;
+    }
+    const applied = outcome.applied;
+    if (applied.length === 0) {
+        console.log(`The working tree already matched version ${targetId}.`);
+    }
+    else {
+        console.log(`Restored ${applied.length} file${applied.length === 1 ? '' : 's'} to version ${targetId}.`);
+        for (const [rel, hash] of applied)
+            console.log(`  ${hash === null ? 'deleted' : 'restored'}  ${rel}`);
+    }
+    // A silent head move is the thing people discover a week later. What the move
+    // left behind needs no announcement: `list-versions` shows those versions,
+    // marked `(later)`.
+    console.log(`head is now ${targetId}.`);
+}

package/kits/physics-2d/CLAUDE.md

@@ -448,11 +448,11 @@ Physics is just this kit's use of it.
 Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a terse svg-rect** — a tiny `<svg viewBox="0 0 16 16">` with **one `<rect>` per pixel** — and pipe it to `npm run draw`. It quantizes every fill to the agent palette and writes a single-frame `drawings/<name>.sprite`.
 
 - **Resolution is 16×16.** Use `viewBox="0 0 16 16"` and **one 1×1 `<rect>` per filled pixel** (`width="1" height="1"` at integer `x`/`y`). Leave background pixels out (omitted = transparent). Keep every rect 1×1 — the decoder infers cell size from the smallest rect, so mixing in larger blocks shrinks the whole grid.
-- **Palette is the agent 16-color subset** (a fixed subset of the editor's full Endesga-64 painting palette) — every `fill` must be one of:
+- **Palette is the deck's generation palette.** The default (no `theme.style`, or Endesga-64) is this 16-color subset — every `fill` must be one of:
 
   `#e69c69` `#bf6f4a` `#8a4836` `#391f21` `#891e2b` `#ea323c` `#ffa214` `#ffeb57` `#5ac54f` `#1e6f50` `#134c4c` `#657392` `#c7cfdd` `#ffffff` `#0cf1ff` `#0098dc`
 
-  (Off-palette fills are snapped to the nearest of these, so stay on-palette to keep what you intend. People editing in the app can paint with the full Endesga-64 palette; only this generation path is constrained to the 16.)
+  If the deck defines a palette in `theme.style`, that governs instead. `npm run palette` prints the active generation palette. Off-palette fills snap to the nearest of these, so stay on-palette to keep what you intend. People editing in the app paint from the deck palette (and the sprite's own colors); only this generation path is quantized.
 - **Run it** (sprite name as the arg; stdin is the svg):
 
   ```bash

package/kits/physics-2d/castle.json

@@ -23,7 +23,8 @@
       "scenes/**",
       "blueprints/**",
       "behaviors/**",
-      "assets/**"
+      "assets/**",
+      "theme.style"
     ],
     "fileTypes": [
       {
@@ -55,6 +56,13 @@
         "new": "New behavior",
         "icon": "code"
       },
+      {
+        "ext": ".style",
+        "label": "Style",
+        "icon": "file",
+        "editor": "kit",
+        "data": true
+      },
       {
         "ext": ".png",
         "label": "Image",
@@ -123,5 +131,5 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-16T04:02:06.732Z"
+  "publishedVersion": "2026-08-18T21:05:46.663Z"
 }

package/kits/physics-2d/docs/pxart-format.md

@@ -88,36 +88,42 @@ temporal versions — that the kit treats as one in-memory model:
   transparent.
 - Indexed-with-hex only: **not** RGBA-per-pixel, **not** grayscale.
 
-### Two-tier palette system (Endesga-64)
-
-The kit uses a **two-tier** fixed palette, both tiers drawn from Lospec's
-[Endesga 64](https://lospec.com/palette-list/endesga-64). There is no free color
-picking at either tier.
-
-**Full palette — Endesga 64 (`EDG64`, all 64 colors): what USERS paint with.**
-The kit's `PxArtEditor` exposes the **full 64-color swatch** (canonical Lospec
-order). The editor assigns each color a stable single-char key (`KEY_ALPHABET`,
-64 distinct keys) plus `.` for transparent. When an existing sprite is opened for
-editing, each cell's resolved color is **snapped to the nearest Endesga-64
-color** by RGB distance, so editing always stays on the fixed swatch. (Sprites
-still *render* with their own stored palette via `renderSpriteFrame`; the snap
-only affects what the editor writes back.) The swatch UI renders as an 8-column
-grid (8 rows for the 64 colors) that scrolls within the inspector.
-
-**Agent subset — 16 colors (`AGENT_PALETTE_16`): what the LLM generates with.**
-The agent generation path (the `draw` svg-rect → `.sprite` quantizer and the
-prompt the model receives) is constrained to a **fixed 16-color subset of
-Endesga-64**, so generated art stays coherent. Every color below is a member of
-`EDG64`. In order:
+### Deck palette + derived agent subset
+
+Each sprite file carries its **own** ordered `{ key, hex }` palette. That list
+is truth: opening a sprite for editing never remaps its colors. The editor
+paints with those keys, and picking a new color **allocates** a key into the
+sprite's palette (`KEY_ALPHABET`, capped at 64) rather than snapping existing
+pixels onto a global swatch.
+
+The **deck palette** is a picker source, not a normalization target. It lives
+in `theme.style` at the deck root (`engine/palettes.js`). Missing or malformed
+theme data falls back to Lospec's [Endesga 64](https://lospec.com/palette-list/endesga-64)
+(`EDG64`). The inspector picker is an unlabeled row of the sprite's own colors
+(when that palette is non-empty) plus an 8-column grid of official palettes,
+paged with named arrows. The deck's `theme.style` palette is the default page;
+paging does not write the theme. A custom `{ name, colors }` deck adds one
+extra read-only page. Picking a hex still allocates onto the sprite.
+
+**Agent subset — what the LLM generates with.** The generation path (`draw`
+svg-rect → `.sprite`, and `import-svg`) quantizes to a derived subset of the
+deck palette (`agentPaletteFor`):
+
+- default Endesga-64 → the hand-curated `AGENT_PALETTE_16`
+- custom palette larger than 16 → greedy farthest-point subset in Oklab
+- 16 or fewer colors → used as-is
+
+`npm run palette` prints both the deck palette and the derived generation
+subset. The default 16, in agent-facing order (every entry is a member of
+`EDG64`):
 
 ```
 #e69c69 #bf6f4a #8a4836 #391f21 #891e2b #ea323c #ffa214 #ffeb57
 #5ac54f #1e6f50 #134c4c #657392 #c7cfdd #ffffff #0cf1ff #0098dc
 ```
 
-So: the editor offers all 64 to people; the agent generation path snaps to these
-16. Both constants (`EDG64`, `AGENT_PALETTE_16`) live in the kit's
-`engine/pxart.js`.
+`EDG64` and `AGENT_PALETTE_16` live in `engine/pxart.js`; derivation and
+theme resolution live in `engine/palettes.js`.
 
 ---
 
@@ -656,8 +662,9 @@ system treats it as a full (degenerate) Sprite.
 ### Single-layer / single-frame generation contract
 
 The **generation contract** for this kit is to emit the **compact shorthand**: a
-single 16×16 (default) `{ palette, grid }` sprite over the agent 16-color subset
-(`AGENT_PALETTE_16`).
+single 16×16 (default) `{ palette, grid }` sprite quantized to the deck's
+generation palette (`agentPaletteFor` of the `theme.style` palette, or
+`AGENT_PALETTE_16` when the deck uses the Endesga-64 default).
 The CLI generation worker and the kit's `PxArtEditor` both produce/store this
 compact form when nothing is lost by it. Multi-layer / multi-frame structure is
 authored by tools later, not hand-generated — and the minimal `PxArtEditor`