qlogicagent 2.18.7 → 2.18.8

package/dist/vendor/hatch-pet/NOTICE.md

@@ -1,25 +1,25 @@
-# Vendored: OpenAI Codex Hatch-Pet pipeline
-
-This directory vendors the deterministic image-processing pipeline from the
-OpenAI Skills repository, used by qlogicagent's Petdex forge to produce
-Codex-compatible animated pet sprite sheets.
-
-- **Source:** https://github.com/openai/skills — `skills/.curated/hatch-pet/`
-- **License:** Apache License 2.0 (see `LICENSE.txt`)
-- **Vendored on:** 2026-06-05
-
-## Contents
-
-- `scripts/*.py` — pipeline scripts (chroma-key frame extraction, frame QA,
-  atlas composition, atlas validation, contact sheet, animation GIF previews,
-  running-left mirror derivation, run preparation). Invoked as subprocesses by
-  `src/runtime/pet/` — qlogicagent does **not** import them.
-- `references/*.md` — Codex pet contract / animation-rows / QA rubric, kept for
-  reference and prompt alignment.
-- `LICENSE.txt` — Apache License 2.0.
-
-## Modifications
-
-None. Files are vendored verbatim and executed via a Python subprocess
-(Pillow is the only third-party dependency). Any future local change must be
-recorded here per the Apache-2.0 NOTICE requirement.
+# Vendored: OpenAI Codex Hatch-Pet pipeline
+
+This directory vendors the deterministic image-processing pipeline from the
+OpenAI Skills repository, used by qlogicagent's Petdex forge to produce
+Codex-compatible animated pet sprite sheets.
+
+- **Source:** https://github.com/openai/skills — `skills/.curated/hatch-pet/`
+- **License:** Apache License 2.0 (see `LICENSE.txt`)
+- **Vendored on:** 2026-06-05
+
+## Contents
+
+- `scripts/*.py` — pipeline scripts (chroma-key frame extraction, frame QA,
+  atlas composition, atlas validation, contact sheet, animation GIF previews,
+  running-left mirror derivation, run preparation). Invoked as subprocesses by
+  `src/runtime/pet/` — qlogicagent does **not** import them.
+- `references/*.md` — Codex pet contract / animation-rows / QA rubric, kept for
+  reference and prompt alignment.
+- `LICENSE.txt` — Apache License 2.0.
+
+## Modifications
+
+None. Files are vendored verbatim and executed via a Python subprocess
+(Pillow is the only third-party dependency). Any future local change must be
+recorded here per the Apache-2.0 NOTICE requirement.

package/dist/vendor/hatch-pet/references/animation-rows.md

@@ -1,29 +1,29 @@
-# Animation Rows
-
-The Codex app reads one fixed atlas: 8 columns, 9 rows, 192x208 pixels per cell.
-
-| Row | State | Used columns | Durations |
-| --- | --- | ---: | --- |
-| 0 | idle | 0-5 | 280, 110, 110, 140, 140, 320 ms |
-| 1 | running-right | 0-7 | 120 ms each, final 220 ms |
-| 2 | running-left | 0-7 | 120 ms each, final 220 ms |
-| 3 | waving | 0-3 | 140 ms each, final 280 ms |
-| 4 | jumping | 0-4 | 140 ms each, final 280 ms |
-| 5 | failed | 0-7 | 140 ms each, final 240 ms |
-| 6 | waiting | 0-5 | 150 ms each, final 260 ms |
-| 7 | running | 0-5 | 120 ms each, final 220 ms |
-| 8 | review | 0-5 | 150 ms each, final 280 ms |
-
-Unused cells after each row's final used column must be fully transparent.
-
-## Row Purposes
-
-- `idle`: calm, low-distraction breathing/blinking loop; use as the reduced-motion first frame. Keep motion subtle and persona-preserving.
-- `running-right`: locomotion to the right; 8-frame loop should read directionally.
-- `running-left`: mirrored or redrawn locomotion to the left; do not simply reuse right-facing frames unless the design is symmetric, and any mirror derivation must preserve frame order and timing semantics.
-- `waving`: greeting or attention gesture; clear start, raised gesture, return.
-- `jumping`: anticipation, lift, peak, descent, settle.
-- `failed`: error/sad/deflated reaction; readable but not visually noisy.
-- `waiting`: blocked-on-user-input state; expectant asking pose for approval, help, or user input.
-- `running`: active task work state; focused processing, thinking, scanning, typing, or effortful concentration. This row is not foot-running; avoid jogging, sprinting, treadmill motion, raised knees, long steps, pumping arms, or directional travel.
-- `review`: focused/inspecting/thinking loop suitable for review state.
+# Animation Rows
+
+The Codex app reads one fixed atlas: 8 columns, 9 rows, 192x208 pixels per cell.
+
+| Row | State | Used columns | Durations |
+| --- | --- | ---: | --- |
+| 0 | idle | 0-5 | 280, 110, 110, 140, 140, 320 ms |
+| 1 | running-right | 0-7 | 120 ms each, final 220 ms |
+| 2 | running-left | 0-7 | 120 ms each, final 220 ms |
+| 3 | waving | 0-3 | 140 ms each, final 280 ms |
+| 4 | jumping | 0-4 | 140 ms each, final 280 ms |
+| 5 | failed | 0-7 | 140 ms each, final 240 ms |
+| 6 | waiting | 0-5 | 150 ms each, final 260 ms |
+| 7 | running | 0-5 | 120 ms each, final 220 ms |
+| 8 | review | 0-5 | 150 ms each, final 280 ms |
+
+Unused cells after each row's final used column must be fully transparent.
+
+## Row Purposes
+
+- `idle`: calm, low-distraction breathing/blinking loop; use as the reduced-motion first frame. Keep motion subtle and persona-preserving.
+- `running-right`: locomotion to the right; 8-frame loop should read directionally.
+- `running-left`: mirrored or redrawn locomotion to the left; do not simply reuse right-facing frames unless the design is symmetric, and any mirror derivation must preserve frame order and timing semantics.
+- `waving`: greeting or attention gesture; clear start, raised gesture, return.
+- `jumping`: anticipation, lift, peak, descent, settle.
+- `failed`: error/sad/deflated reaction; readable but not visually noisy.
+- `waiting`: blocked-on-user-input state; expectant asking pose for approval, help, or user input.
+- `running`: active task work state; focused processing, thinking, scanning, typing, or effortful concentration. This row is not foot-running; avoid jogging, sprinting, treadmill motion, raised knees, long steps, pumping arms, or directional travel.
+- `review`: focused/inspecting/thinking loop suitable for review state.

package/dist/vendor/hatch-pet/references/codex-pet-contract.md

@@ -1,35 +1,35 @@
-# Codex Pet Contract
-
-## Sprite Atlas
-
-- Format: PNG or WebP.
-- Dimensions: `1536x1872`.
-- Grid: 8 columns x 9 rows.
-- Cell: `192x208`.
-- Background: transparent.
-- Unused cells: fully transparent.
-
-The webview animation uses CSS background positions from the fixed row and column counts. Do not add labels, gutters, borders, grid lines, shadows outside the cell, or extra frames.
-
-## Local Custom Pet Package
-
-Place files under:
-
-```text
-${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
-├── pet.json
-└── spritesheet.webp
-```
-
-Manifest shape:
-
-```json
-{
-  "id": "pet-name",
-  "displayName": "Pet Name",
-  "description": "One short sentence.",
-  "spritesheetPath": "spritesheet.webp"
-}
-```
-
-The app loads custom pets from the folder name under `${CODEX_HOME:-$HOME/.codex}/pets/`.
+# Codex Pet Contract
+
+## Sprite Atlas
+
+- Format: PNG or WebP.
+- Dimensions: `1536x1872`.
+- Grid: 8 columns x 9 rows.
+- Cell: `192x208`.
+- Background: transparent.
+- Unused cells: fully transparent.
+
+The webview animation uses CSS background positions from the fixed row and column counts. Do not add labels, gutters, borders, grid lines, shadows outside the cell, or extra frames.
+
+## Local Custom Pet Package
+
+Place files under:
+
+```text
+${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
+├── pet.json
+└── spritesheet.webp
+```
+
+Manifest shape:
+
+```json
+{
+  "id": "pet-name",
+  "displayName": "Pet Name",
+  "description": "One short sentence.",
+  "spritesheetPath": "spritesheet.webp"
+}
+```
+
+The app loads custom pets from the folder name under `${CODEX_HOME:-$HOME/.codex}/pets/`.

package/dist/vendor/hatch-pet/references/qa-rubric.md

@@ -1,66 +1,66 @@
-# QA Rubric
-
-Do not accept an atlas until all checks pass.
-
-## Geometry
-
-- Exact `1536x1872` dimensions.
-- 8 columns x 9 rows.
-- Each frame fits inside its `192x208` cell.
-- Unused cells are transparent.
-- Fully transparent atlas pixels do not retain non-zero RGB residue after export.
-- `qa/review.json` has no errors.
-- `frames/frames-manifest.json` records component extraction for production rows unless `stable-slots` was intentionally chosen to preserve row-level playback stability after visual inspection.
-
-## Character Consistency
-
-- Same silhouette and proportions across every row.
-- Same face and expression language.
-- Same style, material, palette, lighting, and prop design.
-- No frame introduces a new unintended character or object.
-
-## Pet-Safe Style
-
-- Art reads as a Codex app pet, not a scene, app icon, logo sheet, or standalone illustration.
-- Silhouette is compact and clear enough to read inside a `192x208` cell.
-- The chosen style is consistent across every row, including edge treatment, material, lighting, and palette.
-- Pixel, plush, clay, sticker, flat vector, 3D toy, painterly mascot, ink, and brand-inspired styles are all acceptable when readable at pet size.
-- No tiny accessories, texture detail, logo detail, or text that disappears or becomes noisy at pet size.
-
-## Animation Completeness
-
-- Each row uses the exact expected number of frames.
-- The first and last frames can loop without an obvious pop.
-- Directional rows read as the intended direction.
-- Mirrored directional rows preserve temporal frame order rather than reversing the cadence.
-- State-specific actions are recognizable at pet size.
-- Poses are generated animation variants, not repeated copies of the same source image.
-- Preview GIFs do not show unintended size popping, extraction-induced baseline jumps, or wrong directional facing.
-
-## App Fitness
-
-- First idle frame works as a static reduced-motion pet.
-- The `idle` row should be calm and low-distraction; reject it if it reads as waving, walking, running, jumping, talking, working, reviewing, reacting dramatically, changing props, or making large pose/silhouette changes.
-- No important detail is too small to read.
-- No frame is clipped by the cell.
-- Failed/review/waiting states are distinct from ordinary idle.
-- Contact sheets must show whole sprite poses inside cells, not cropped tiles from a larger reference image.
-- Contact sheets must not be accepted if every used frame is just the reference image with small geometric transforms.
-- Used cells must not have white or opaque rectangular backgrounds unless the pet intentionally fills the whole cell and the user accepts that tradeoff.
-- The chroma key must be visually absent from the character. If extraction removes character regions, choose a different key and regenerate the affected base/rows.
-- Contact sheets must not show edge slivers or partial neighboring sprites inside cells.
-- Contact sheets must not show darker/lighter versions of the chroma key as shadows, dust, smears, glows, landing marks, or motion effects. These are background extraction failures and should trigger row repair.
-- If `qa/review.json` reports edge pixels, sparse frames, size outliers, or slot-extraction fallback, inspect the row visually and repair it when the issue is visible.
-- If `qa/review.json` reports chroma-adjacent non-transparent pixels, repair the row unless those pixels are an intentional character color and the selected key was manually accepted.
-- If preview GIFs show size popping even though the generated strip itself had stable scale and placement, rerun extraction with `stable-slots` before regenerating the row.
-- If previews show wrong facing direction, reversed cadence, non-alternating gait, or an effectively static idle loop, repair or regenerate the affected row.
-
-## Repair Policy
-
-Repair the smallest failing scope first:
-
-1. Single bad frame.
-2. One row.
-3. Full atlas regeneration only when identity or layout is broadly broken.
-
-The normal production path should regenerate only the affected row and copy the selected replacement into the same decoded output path unless the base character is wrong.
+# QA Rubric
+
+Do not accept an atlas until all checks pass.
+
+## Geometry
+
+- Exact `1536x1872` dimensions.
+- 8 columns x 9 rows.
+- Each frame fits inside its `192x208` cell.
+- Unused cells are transparent.
+- Fully transparent atlas pixels do not retain non-zero RGB residue after export.
+- `qa/review.json` has no errors.
+- `frames/frames-manifest.json` records component extraction for production rows unless `stable-slots` was intentionally chosen to preserve row-level playback stability after visual inspection.
+
+## Character Consistency
+
+- Same silhouette and proportions across every row.
+- Same face and expression language.
+- Same style, material, palette, lighting, and prop design.
+- No frame introduces a new unintended character or object.
+
+## Pet-Safe Style
+
+- Art reads as a Codex app pet, not a scene, app icon, logo sheet, or standalone illustration.
+- Silhouette is compact and clear enough to read inside a `192x208` cell.
+- The chosen style is consistent across every row, including edge treatment, material, lighting, and palette.
+- Pixel, plush, clay, sticker, flat vector, 3D toy, painterly mascot, ink, and brand-inspired styles are all acceptable when readable at pet size.
+- No tiny accessories, texture detail, logo detail, or text that disappears or becomes noisy at pet size.
+
+## Animation Completeness
+
+- Each row uses the exact expected number of frames.
+- The first and last frames can loop without an obvious pop.
+- Directional rows read as the intended direction.
+- Mirrored directional rows preserve temporal frame order rather than reversing the cadence.
+- State-specific actions are recognizable at pet size.
+- Poses are generated animation variants, not repeated copies of the same source image.
+- Preview GIFs do not show unintended size popping, extraction-induced baseline jumps, or wrong directional facing.
+
+## App Fitness
+
+- First idle frame works as a static reduced-motion pet.
+- The `idle` row should be calm and low-distraction; reject it if it reads as waving, walking, running, jumping, talking, working, reviewing, reacting dramatically, changing props, or making large pose/silhouette changes.
+- No important detail is too small to read.
+- No frame is clipped by the cell.
+- Failed/review/waiting states are distinct from ordinary idle.
+- Contact sheets must show whole sprite poses inside cells, not cropped tiles from a larger reference image.
+- Contact sheets must not be accepted if every used frame is just the reference image with small geometric transforms.
+- Used cells must not have white or opaque rectangular backgrounds unless the pet intentionally fills the whole cell and the user accepts that tradeoff.
+- The chroma key must be visually absent from the character. If extraction removes character regions, choose a different key and regenerate the affected base/rows.
+- Contact sheets must not show edge slivers or partial neighboring sprites inside cells.
+- Contact sheets must not show darker/lighter versions of the chroma key as shadows, dust, smears, glows, landing marks, or motion effects. These are background extraction failures and should trigger row repair.
+- If `qa/review.json` reports edge pixels, sparse frames, size outliers, or slot-extraction fallback, inspect the row visually and repair it when the issue is visible.
+- If `qa/review.json` reports chroma-adjacent non-transparent pixels, repair the row unless those pixels are an intentional character color and the selected key was manually accepted.
+- If preview GIFs show size popping even though the generated strip itself had stable scale and placement, rerun extraction with `stable-slots` before regenerating the row.
+- If previews show wrong facing direction, reversed cadence, non-alternating gait, or an effectively static idle loop, repair or regenerate the affected row.
+
+## Repair Policy
+
+Repair the smallest failing scope first:
+
+1. Single bad frame.
+2. One row.
+3. Full atlas regeneration only when identity or layout is broadly broken.
+
+The normal production path should regenerate only the affected row and copy the selected replacement into the same decoded output path unless the base character is wrong.

package/dist/vendor/hatch-pet/scripts/compose_atlas.py

@@ -1,169 +1,169 @@
-#!/usr/bin/env python3
-"""Compose or normalize a Codex pet spritesheet atlas."""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from PIL import Image
-
-COLUMNS = 8
-ROWS = 9
-CELL_WIDTH = 192
-CELL_HEIGHT = 208
-ATLAS_WIDTH = COLUMNS * CELL_WIDTH
-ATLAS_HEIGHT = ROWS * CELL_HEIGHT
-ATLAS_ASPECT_RATIO = ATLAS_WIDTH / ATLAS_HEIGHT
-ROW_SPECS = [
-    ("idle", 0, 6),
-    ("running-right", 1, 8),
-    ("running-left", 2, 8),
-    ("waving", 3, 4),
-    ("jumping", 4, 5),
-    ("failed", 5, 8),
-    ("waiting", 6, 6),
-    ("running", 7, 6),
-    ("review", 8, 6),
-]
-IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
-
-
-def image_files(path: Path) -> list[Path]:
-    return sorted(p for p in path.iterdir() if p.suffix.lower() in IMAGE_SUFFIXES)
-
-
-def find_row_frames(root: Path, state: str, row_index: int) -> list[Path]:
-    candidates = [
-        root / state,
-        root / f"row-{row_index}",
-        root / f"row{row_index}",
-        root / f"{row_index}-{state}",
-    ]
-    for candidate in candidates:
-        if candidate.is_dir():
-            files = image_files(candidate)
-            if files:
-                return files
-    globs = [
-        f"{state}_*",
-        f"{state}-*",
-        f"row{row_index}_*",
-        f"row-{row_index}-*",
-    ]
-    files: list[Path] = []
-    for pattern in globs:
-        files.extend(p for p in root.glob(pattern) if p.suffix.lower() in IMAGE_SUFFIXES)
-    return sorted(set(files))
-
-
-def paste_centered(atlas: Image.Image, source: Image.Image, row: int, column: int) -> None:
-    frame = source.convert("RGBA")
-    if frame.size != (CELL_WIDTH, CELL_HEIGHT):
-        frame.thumbnail((CELL_WIDTH, CELL_HEIGHT), Image.Resampling.LANCZOS)
-    left = column * CELL_WIDTH + (CELL_WIDTH - frame.width) // 2
-    top = row * CELL_HEIGHT + (CELL_HEIGHT - frame.height) // 2
-    atlas.alpha_composite(frame, (left, top))
-
-
-def compose_from_source_atlas(path: Path, resize_source: bool) -> Image.Image:
-    with Image.open(path) as opened:
-        source = opened.convert("RGBA")
-    if source.size != (ATLAS_WIDTH, ATLAS_HEIGHT):
-        if not resize_source:
-            raise SystemExit(
-                f"source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {source.width}x{source.height}"
-            )
-        source_ratio = source.width / source.height
-        if abs(source_ratio - ATLAS_ASPECT_RATIO) > 0.02:
-            raise SystemExit(
-                "refusing to resize source atlas because its aspect ratio does not match "
-                f"the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. "
-                "Generate exact atlas dimensions or use --frames-root."
-            )
-        source = source.resize((ATLAS_WIDTH, ATLAS_HEIGHT), Image.Resampling.LANCZOS)
-
-    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
-    for _state, row, frame_count in ROW_SPECS:
-        for column in range(frame_count):
-            left = column * CELL_WIDTH
-            top = row * CELL_HEIGHT
-            cell = source.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))
-            atlas.alpha_composite(cell, (left, top))
-    return atlas
-
-
-def compose_from_frames(root: Path) -> Image.Image:
-    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
-    for state, row, frame_count in ROW_SPECS:
-        files = find_row_frames(root, state, row)
-        if len(files) < frame_count:
-            raise SystemExit(
-                f"{state} row needs {frame_count} frames, found {len(files)} under {root}"
-            )
-        for column, frame_path in enumerate(files[:frame_count]):
-            with Image.open(frame_path) as frame:
-                paste_centered(atlas, frame, row, column)
-    return atlas
-
-
-def clear_transparent_rgb(image: Image.Image) -> Image.Image:
-    rgba = image.convert("RGBA")
-    data = bytearray(rgba.tobytes())
-    for index in range(0, len(data), 4):
-        if data[index + 3] == 0:
-            data[index] = 0
-            data[index + 1] = 0
-            data[index + 2] = 0
-    return Image.frombytes("RGBA", rgba.size, bytes(data))
-
-
-def save_outputs(atlas: Image.Image, output: Path, webp_output: Path | None) -> None:
-    atlas = clear_transparent_rgb(atlas)
-    output.parent.mkdir(parents=True, exist_ok=True)
-    atlas.save(output)
-    if webp_output is not None:
-        webp_output.parent.mkdir(parents=True, exist_ok=True)
-        atlas.save(
-            webp_output,
-            format="WEBP",
-            lossless=True,
-            quality=100,
-            method=6,
-            exact=True,
-        )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    source = parser.add_mutually_exclusive_group(required=True)
-    source.add_argument("--source-atlas")
-    source.add_argument("--frames-root")
-    parser.add_argument("--output", required=True)
-    parser.add_argument("--webp-output")
-    parser.add_argument(
-        "--resize-source",
-        action="store_true",
-        help="Resize a lower-resolution source atlas only when it already has the Codex atlas aspect ratio.",
-    )
-    args = parser.parse_args()
-
-    if args.source_atlas:
-        atlas = compose_from_source_atlas(
-            Path(args.source_atlas).expanduser().resolve(), args.resize_source
-        )
-    else:
-        atlas = compose_from_frames(Path(args.frames_root).expanduser().resolve())
-
-    save_outputs(
-        atlas,
-        Path(args.output).expanduser().resolve(),
-        Path(args.webp_output).expanduser().resolve() if args.webp_output else None,
-    )
-    print(f"wrote {Path(args.output).expanduser().resolve()}")
-    if args.webp_output:
-        print(f"wrote {Path(args.webp_output).expanduser().resolve()}")
-
-
-if __name__ == "__main__":
-    main()
+#!/usr/bin/env python3
+"""Compose or normalize a Codex pet spritesheet atlas."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+
+COLUMNS = 8
+ROWS = 9
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ATLAS_WIDTH = COLUMNS * CELL_WIDTH
+ATLAS_HEIGHT = ROWS * CELL_HEIGHT
+ATLAS_ASPECT_RATIO = ATLAS_WIDTH / ATLAS_HEIGHT
+ROW_SPECS = [
+    ("idle", 0, 6),
+    ("running-right", 1, 8),
+    ("running-left", 2, 8),
+    ("waving", 3, 4),
+    ("jumping", 4, 5),
+    ("failed", 5, 8),
+    ("waiting", 6, 6),
+    ("running", 7, 6),
+    ("review", 8, 6),
+]
+IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
+
+
+def image_files(path: Path) -> list[Path]:
+    return sorted(p for p in path.iterdir() if p.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def find_row_frames(root: Path, state: str, row_index: int) -> list[Path]:
+    candidates = [
+        root / state,
+        root / f"row-{row_index}",
+        root / f"row{row_index}",
+        root / f"{row_index}-{state}",
+    ]
+    for candidate in candidates:
+        if candidate.is_dir():
+            files = image_files(candidate)
+            if files:
+                return files
+    globs = [
+        f"{state}_*",
+        f"{state}-*",
+        f"row{row_index}_*",
+        f"row-{row_index}-*",
+    ]
+    files: list[Path] = []
+    for pattern in globs:
+        files.extend(p for p in root.glob(pattern) if p.suffix.lower() in IMAGE_SUFFIXES)
+    return sorted(set(files))
+
+
+def paste_centered(atlas: Image.Image, source: Image.Image, row: int, column: int) -> None:
+    frame = source.convert("RGBA")
+    if frame.size != (CELL_WIDTH, CELL_HEIGHT):
+        frame.thumbnail((CELL_WIDTH, CELL_HEIGHT), Image.Resampling.LANCZOS)
+    left = column * CELL_WIDTH + (CELL_WIDTH - frame.width) // 2
+    top = row * CELL_HEIGHT + (CELL_HEIGHT - frame.height) // 2
+    atlas.alpha_composite(frame, (left, top))
+
+
+def compose_from_source_atlas(path: Path, resize_source: bool) -> Image.Image:
+    with Image.open(path) as opened:
+        source = opened.convert("RGBA")
+    if source.size != (ATLAS_WIDTH, ATLAS_HEIGHT):
+        if not resize_source:
+            raise SystemExit(
+                f"source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {source.width}x{source.height}"
+            )
+        source_ratio = source.width / source.height
+        if abs(source_ratio - ATLAS_ASPECT_RATIO) > 0.02:
+            raise SystemExit(
+                "refusing to resize source atlas because its aspect ratio does not match "
+                f"the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. "
+                "Generate exact atlas dimensions or use --frames-root."
+            )
+        source = source.resize((ATLAS_WIDTH, ATLAS_HEIGHT), Image.Resampling.LANCZOS)
+
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for _state, row, frame_count in ROW_SPECS:
+        for column in range(frame_count):
+            left = column * CELL_WIDTH
+            top = row * CELL_HEIGHT
+            cell = source.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))
+            atlas.alpha_composite(cell, (left, top))
+    return atlas
+
+
+def compose_from_frames(root: Path) -> Image.Image:
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for state, row, frame_count in ROW_SPECS:
+        files = find_row_frames(root, state, row)
+        if len(files) < frame_count:
+            raise SystemExit(
+                f"{state} row needs {frame_count} frames, found {len(files)} under {root}"
+            )
+        for column, frame_path in enumerate(files[:frame_count]):
+            with Image.open(frame_path) as frame:
+                paste_centered(atlas, frame, row, column)
+    return atlas
+
+
+def clear_transparent_rgb(image: Image.Image) -> Image.Image:
+    rgba = image.convert("RGBA")
+    data = bytearray(rgba.tobytes())
+    for index in range(0, len(data), 4):
+        if data[index + 3] == 0:
+            data[index] = 0
+            data[index + 1] = 0
+            data[index + 2] = 0
+    return Image.frombytes("RGBA", rgba.size, bytes(data))
+
+
+def save_outputs(atlas: Image.Image, output: Path, webp_output: Path | None) -> None:
+    atlas = clear_transparent_rgb(atlas)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    atlas.save(output)
+    if webp_output is not None:
+        webp_output.parent.mkdir(parents=True, exist_ok=True)
+        atlas.save(
+            webp_output,
+            format="WEBP",
+            lossless=True,
+            quality=100,
+            method=6,
+            exact=True,
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--source-atlas")
+    source.add_argument("--frames-root")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--webp-output")
+    parser.add_argument(
+        "--resize-source",
+        action="store_true",
+        help="Resize a lower-resolution source atlas only when it already has the Codex atlas aspect ratio.",
+    )
+    args = parser.parse_args()
+
+    if args.source_atlas:
+        atlas = compose_from_source_atlas(
+            Path(args.source_atlas).expanduser().resolve(), args.resize_source
+        )
+    else:
+        atlas = compose_from_frames(Path(args.frames_root).expanduser().resolve())
+
+    save_outputs(
+        atlas,
+        Path(args.output).expanduser().resolve(),
+        Path(args.webp_output).expanduser().resolve() if args.webp_output else None,
+    )
+    print(f"wrote {Path(args.output).expanduser().resolve()}")
+    if args.webp_output:
+        print(f"wrote {Path(args.webp_output).expanduser().resolve()}")
+
+
+if __name__ == "__main__":
+    main()