@bongos/core 1.17.0

package/scripts/snapshots/backfill-history.mjs

@@ -0,0 +1,292 @@
+// scripts/snapshots/backfill-history.mjs
+//
+// One-shot historical backfill: walk every commit that touched graphics-
+// affecting files and render a snapshot from each commit's tree.
+//
+// Strategy:
+//   1. Ask git for every commit touching `public/assets/tiles/`, `public/game/world/`,
+//      or `src/world/{map,terrain}.js` (in chronological order, oldest first).
+//   2. For each commit, `git archive` the working tree into a temp dir.
+//      The renderer + its node_modules come from the CURRENT worktree (the
+//      renderer didn't exist in old commits) — only the world DATA comes
+//      from the historical commit.
+//   3. Run the renderer with --sha + --timestamp + --label so each snapshot
+//      is stamped correctly.
+//
+// Pre-Phase-D commits (before INITIAL_MAP existed in its two-grid form) are
+// skipped — they would crash the renderer. We start the timeline at Phase D
+// and note the gap in CURATED_LABELS below.
+//
+// Usage:
+//   node scripts/snapshots/backfill-history.mjs              # render all known visual milestones
+//   node scripts/snapshots/backfill-history.mjs --dry-run    # just list what would be rendered
+
+import { execSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync, mkdirSync, existsSync, cpSync, symlinkSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+// The status surface moved to modules/status-ui/public/ in BV1.R84 (task 1635).
+const SNAPSHOTS_DIR = resolve(ROOT, 'modules/status-ui/public/snapshots');
+
+function sh(cmd, opts = {}) {
+  return execSync(cmd, { cwd: ROOT, encoding: 'utf8', ...opts }).trim();
+}
+
+// Curated labels for known visual milestones. Anything not listed gets the
+// commit subject as its label.
+const CURATED_LABELS = {
+  '5354daa': 'Phase D — the first world',
+  '6abe01c': 'The coast is surveyed — sand meets sea',
+  '865d64c': 'A door appears, and a path laid to it',
+  '7ac06df': 'A wanderer arrives — first sight of Hyperion at his door',
+  '13b796d': 'The grass turns green',
+  '358f2cd': 'Rocks scattered through the meadow; the container takes its full form',
+  '86cee70': 'Container wall refined (7.78 → 8.9)',
+  '0e630c8': 'Multi-variant interior tiles',
+  '6fc7c09': 'Hyperion stands taller — vendor poses refined',
+  '1c6654a': 'Container wall regenerated (atlas drift fix)',
+  'd438644': 'The container door painted solid',
+};
+
+// Pre-Phase-D commits to NOT attempt — these crash the renderer (no two-grid map yet).
+const SKIP_BEFORE = '5354daa'; // Phase D — first renderable commit.
+
+function isAncestor(maybeAncestor, descendant) {
+  try {
+    execSync(`git merge-base --is-ancestor ${maybeAncestor} ${descendant}`, { cwd: ROOT, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listGraphicsCommits() {
+  // %H short SHA + ISO date + subject. Reverse so oldest first.
+  const raw = sh(
+    `git log --reverse --format='%H%x09%aI%x09%s' --no-merges -- ` +
+    `'public/assets/tiles/' 'public/game/world/' 'src/world/map.js' 'src/world/terrain.js'`
+  );
+  return raw.split('\n').filter(Boolean).map((line) => {
+    const [sha, timestamp, subject] = line.split('\t');
+    return { sha, timestamp, subject };
+  });
+}
+
+function commitChangedGraphics(sha) {
+  // Did THIS commit change any tile PNGs or world code?
+  // For some commits the path filter above matches a config-only change
+  // (e.g. manifest tweak) that doesn't actually re-render differently. We
+  // still render — let's accept a few duplicates rather than over-filter.
+  try {
+    const out = sh(`git diff-tree --no-commit-id --name-only -r ${sha} -- public/assets/tiles/ public/game/world/ src/world/map.js src/world/terrain.js`);
+    return out.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function setupRenderTree(sha, tmpRoot) {
+  // 1. Extract historical world data from the commit.
+  mkdirSync(tmpRoot, { recursive: true });
+  // git archive paths: tile assets + world code on both sides + the manifest.
+  // Use a wide net so we cover any restructuring across the history.
+  const archivePaths = [
+    'public/assets/tiles',
+    'public/game/world',
+    'src/world',
+  ].filter((p) => {
+    // Skip non-existent paths at this commit (some commits predate src/world).
+    try {
+      execSync(`git ls-tree ${sha} -- ${p}`, { cwd: ROOT, stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (archivePaths.length === 0) return false;
+
+  sh(`git archive ${sha} ${archivePaths.map((p) => `'${p}'`).join(' ')} | tar -x -C '${tmpRoot}'`);
+
+  // 2. Copy renderer + helpers from CURRENT worktree.
+  const rendererSrc = resolve(ROOT, 'scripts/snapshots/render-world.mjs');
+  const rendererDst = resolve(tmpRoot, 'scripts/snapshots/render-world.mjs');
+  mkdirSync(dirname(rendererDst), { recursive: true });
+  cpSync(rendererSrc, rendererDst);
+
+  // 3. Symlink node_modules from current worktree (sharp is required).
+  const nmSrc = resolve(ROOT, 'node_modules');
+  const nmDst = resolve(tmpRoot, 'node_modules');
+  if (!existsSync(nmDst)) symlinkSync(nmSrc, nmDst);
+
+  // 4. Some historical commits may have a different map.js shape (pre-ADR-0012)
+  //    that crashes the renderer. We don't try to compensate — those commits
+  //    are filtered upstream by SKIP_BEFORE.
+  return true;
+}
+
+function shortLabelFor(entry) {
+  const short = entry.sha.slice(0, 7);
+  return CURATED_LABELS[short] || entry.subject;
+}
+
+async function main() {
+  const dryRun = process.argv.includes('--dry-run');
+
+  // Resolve the canonical short SHA of SKIP_BEFORE for ancestor checks.
+  const skipBeforeFull = sh(`git rev-parse ${SKIP_BEFORE}`);
+
+  const commits = listGraphicsCommits();
+  console.log(`[backfill] found ${commits.length} commits touching graphics paths`);
+
+  const candidates = [];
+  for (const c of commits) {
+    if (!isAncestor(c.sha, 'HEAD')) {
+      // Not in current main lineage (e.g. a branch that was never merged).
+      continue;
+    }
+    if (c.sha !== skipBeforeFull && !isAncestor(skipBeforeFull, c.sha)) {
+      // Earlier than Phase D — renderer won't work.
+      continue;
+    }
+    if (!commitChangedGraphics(c.sha)) continue;
+    candidates.push(c);
+  }
+
+  // Always include current HEAD as the final snapshot if it isn't in the list.
+  const head = sh('git rev-parse HEAD');
+  const headTs = sh('git log -1 --format=%aI HEAD');
+  const headSubj = sh('git log -1 --format=%s HEAD');
+  if (!candidates.find((c) => c.sha === head)) {
+    candidates.push({ sha: head, timestamp: headTs, subject: headSubj });
+  }
+
+  console.log(`[backfill] will render ${candidates.length} historical snapshots:`);
+  for (const c of candidates) {
+    const lbl = shortLabelFor(c);
+    console.log(`  ${c.sha.slice(0, 7)}  ${c.timestamp.slice(0, 16)}  ${lbl}`);
+  }
+  if (dryRun) {
+    console.log('[backfill] --dry-run: not rendering');
+    return;
+  }
+
+  mkdirSync(SNAPSHOTS_DIR, { recursive: true });
+
+  let rendered = 0;
+  let failed = 0;
+  for (const c of candidates) {
+    const short = c.sha.slice(0, 7);
+    const label = shortLabelFor(c);
+
+    // Skip work if the snapshot already exists in the manifest with the same sha.
+    // (Re-runs are idempotent.)
+    const manifestPath = resolve(SNAPSHOTS_DIR, 'manifest.json');
+    if (existsSync(manifestPath)) {
+      try {
+        const m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (Array.isArray(m.snapshots) && m.snapshots.find((s) => s.sha === c.sha)) {
+          console.log(`[backfill] skip ${short} (already in manifest)`);
+          continue;
+        }
+      } catch { /* ignore */ }
+    }
+
+    const tmp = mkdtempSync(resolve(tmpdir(), `otb-snap-${short}-`));
+    console.log(`\n[backfill] rendering ${short} → ${tmp}`);
+    try {
+      const ok = setupRenderTree(c.sha, tmp);
+      if (!ok) {
+        console.log(`[backfill] skip ${short} — no archivable paths`);
+        continue;
+      }
+      const result = spawnSync('node', [
+        resolve(tmp, 'scripts/snapshots/render-world.mjs'),
+        '--sha', c.sha,
+        '--timestamp', c.timestamp,
+        '--label', label,
+        '--id', short,
+        '--no-manifest',
+        '--out', resolve(SNAPSHOTS_DIR, `${short}.png`),
+      ], { cwd: tmp, stdio: 'inherit' });
+      if (result.status !== 0) {
+        throw new Error(`renderer exit ${result.status}`);
+      }
+
+      // Update the canonical manifest in the main worktree directly.
+      let m = { version: 2, snapshots: [] };
+      if (existsSync(manifestPath)) {
+        try { m = JSON.parse(readFileSync(manifestPath, 'utf8')); } catch { /* fall back */ }
+      }
+      if (!Array.isArray(m.snapshots)) m.snapshots = [];
+      const entry = {
+        id: short,
+        sha: c.sha,
+        timestamp: c.timestamp,
+        label,
+        image: `${short}.png`,
+      };
+      const i = m.snapshots.findIndex((s) => s.id === entry.id);
+      if (i >= 0) m.snapshots[i] = entry;
+      else m.snapshots.push(entry);
+      m.snapshots.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+      m.version = 2;
+      writeFileSync(manifestPath, JSON.stringify(m, null, 2) + '\n');
+      console.log(`[backfill] manifest: ${m.snapshots.length} entries`);
+
+      rendered++;
+    } catch (e) {
+      console.error(`[backfill] FAIL ${short}: ${e.message}`);
+      failed++;
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+
+  console.log(`\n[backfill] done — ${rendered} rendered, ${failed} failed`);
+
+  // ---- Dedup pass ----
+  // Many commits change graphics code or atlas plumbing without changing the
+  // rendered output. Group snapshots by PNG hash; keep only the earliest
+  // commit (by timestamp) in each group. The later identical entries get
+  // their PNG file removed and their manifest entry dropped.
+  const manifestPath = resolve(SNAPSHOTS_DIR, 'manifest.json');
+  if (!existsSync(manifestPath)) return;
+  const m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (!Array.isArray(m.snapshots)) return;
+
+  const byHash = new Map();
+  for (const snap of m.snapshots) {
+    const imgPath = resolve(SNAPSHOTS_DIR, snap.image);
+    if (!existsSync(imgPath)) continue;
+    const hash = createHash('md5').update(readFileSync(imgPath)).digest('hex');
+    const existing = byHash.get(hash);
+    if (!existing || (snap.timestamp || '') < (existing.timestamp || '')) {
+      byHash.set(hash, snap);
+    }
+  }
+  const keepIds = new Set(Array.from(byHash.values()).map((s) => s.id));
+  const dropped = [];
+  for (const snap of m.snapshots) {
+    if (!keepIds.has(snap.id)) {
+      dropped.push(snap.id);
+      const imgPath = resolve(SNAPSHOTS_DIR, snap.image);
+      if (existsSync(imgPath)) {
+        try { unlinkSync(imgPath); } catch { /* ignore */ }
+      }
+    }
+  }
+  m.snapshots = m.snapshots.filter((s) => keepIds.has(s.id));
+  m.snapshots.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+  writeFileSync(manifestPath, JSON.stringify(m, null, 2) + '\n');
+  if (dropped.length > 0) {
+    console.log(`[backfill] dedup: removed ${dropped.length} duplicates: ${dropped.join(', ')}`);
+  }
+  console.log(`[backfill] manifest now has ${m.snapshots.length} unique snapshots`);
+}
+
+await main();

package/scripts/snapshots/maybe-render-on-deploy.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# scripts/snapshots/maybe-render-on-deploy.sh
+#
+# Called from ~/deploy.sh on the droplet. Decides whether the just-pulled
+# commit changed the world's visible graphics; if so, renders a new
+# snapshot tagged with the commit sha + author timestamp + subject.
+#
+# State: the previous deployed sha is stored at ~/.amazonprimea-last-deploy.
+# If it's missing (first run), we still render a snapshot of HEAD so the
+# timeline isn't empty.
+#
+# Add to ~/deploy.sh right after `sudo systemctl restart amazonprimea`:
+#
+#   bash scripts/snapshots/maybe-render-on-deploy.sh "$PREV_SHA"
+#
+# where $PREV_SHA is captured BEFORE the git fetch + reset --hard. A simple
+# pattern that works inside deploy.sh:
+#
+#   PREV_SHA="$(git rev-parse HEAD)"
+#   git fetch origin && git reset --hard origin/main
+#   ...
+#   bash scripts/snapshots/maybe-render-on-deploy.sh "$PREV_SHA"
+
+set -euo pipefail
+
+GRAPHICS_PATHS=(
+  'public/assets/tiles'
+  'public/game/world'
+  'src/world/map.js'
+  'src/world/terrain.js'
+)
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+PREV="${1:-}"
+NEW="$(git rev-parse HEAD)"
+SHORT="$(git rev-parse --short=7 HEAD)"
+SUBJECT="$(git log -1 --format=%s HEAD)"
+TIMESTAMP="$(git log -1 --format=%aI HEAD)"
+
+if [ -z "$PREV" ] || [ "$PREV" = "$NEW" ]; then
+  # First run, or no commits since last deploy.
+  if [ -z "$PREV" ]; then
+    echo "[snapshot] first run — rendering HEAD snapshot"
+  else
+    echo "[snapshot] no commits since $PREV — skipping"
+    exit 0
+  fi
+else
+  if git diff --name-only "$PREV..$NEW" -- "${GRAPHICS_PATHS[@]}" | read -r _; then
+    echo "[snapshot] graphics changed between $PREV..$SHORT — rendering"
+  else
+    echo "[snapshot] no graphics changes between $PREV..$SHORT — skipping"
+    exit 0
+  fi
+fi
+
+node scripts/snapshots/render-world.mjs \
+  --sha "$NEW" \
+  --timestamp "$TIMESTAMP" \
+  --label "$SUBJECT" \
+  --id "$SHORT" \
+  --out "modules/status-ui/public/snapshots/$SHORT.png"
+
+echo "[snapshot] done — $SHORT"

package/scripts/snapshots/render-pre-art-eras.mjs

@@ -0,0 +1,329 @@
+// scripts/snapshots/render-pre-art-eras.mjs
+//
+// Captures the two snapshot-worthy moments BEFORE the pixel-art pipeline
+// existed, which the main renderer cannot reach:
+//
+//   1. "Before the container washed ashore" — the hello-world page that
+//      lived at amazonprimea.com from 2026-05-08 19:16 (commit faa8c77)
+//      until Phase 1 replaced it ~44 minutes later. Black + gold,
+//      monospace, three lines of text.
+//
+//   2. "The first playable world" — the Phaser scaffold from Phase 7
+//      (commit 0b13bb4, 2026-05-08 20:21). No real tile art yet —
+//      procedural-canvas tiles painted in tilePalette.js at boot. We
+//      replicate those colors here so the snapshot matches what a player
+//      would have seen.
+//
+// Output: writes 2 PNGs into modules/status-ui/public/snapshots/ and inserts both
+// into manifest.json (alongside whatever's already there). Idempotent.
+// (The status surface moved to modules/status-ui/public/ in BV1.R84 / task 1635.)
+
+import sharp from 'sharp';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+const SNAPSHOTS_DIR = resolve(ROOT, 'modules/status-ui/public/snapshots');
+const MANIFEST_PATH = resolve(SNAPSHOTS_DIR, 'manifest.json');
+
+const TILE_SIZE = 32;
+const WORLD_COLS = 30;
+const WORLD_ROWS = 18;
+const WIDTH = WORLD_COLS * TILE_SIZE;   // 960
+const HEIGHT = WORLD_ROWS * TILE_SIZE;  // 576
+
+// ---------- Phase 7 procedural-canvas tile generators -----------------------
+//
+// Mirrors the original public/game/world/tilePalette.js from commit 0b13bb4.
+// Each generator returns a 32×32 PNG Buffer. We hand-build them via sharp
+// composites of small colored rectangles, matching the original colors.
+
+function rect(x, y, w, h, color) {
+  return {
+    input: {
+      create: {
+        width: w,
+        height: h,
+        channels: 4,
+        background: color,
+      },
+    },
+    left: x,
+    top: y,
+  };
+}
+
+function speckle(color, count) {
+  // Original used (i*7)%32, (i*13)%32 — 1×1 pixels at deterministic spots.
+  const pieces = [];
+  for (let i = 0; i < count; i++) {
+    pieces.push(rect((i * 7) % TILE_SIZE, (i * 13) % TILE_SIZE, 1, 1, color));
+  }
+  return pieces;
+}
+
+async function makeTile(layers) {
+  return sharp({
+    create: { width: TILE_SIZE, height: TILE_SIZE, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+  })
+    .composite(layers)
+    .png()
+    .toBuffer();
+}
+
+async function buildPhase7Tiles() {
+  return {
+    sand: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#e6c97a'),
+      ...speckle('#c8a85a', 18),
+      ...speckle('#f3dfa1', 10),
+    ]),
+    wet_sand: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#a88947'),
+      ...speckle('#7a6230', 22),
+      ...speckle('#c5a25a', 8),
+    ]),
+    sea: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#2b6da3'),
+      rect(0, 8,  TILE_SIZE, 4, '#3884bd'),
+      rect(0, 20, TILE_SIZE, 2, '#4ea0d3'),
+      ...speckle('#cce8f7', 6),
+    ]),
+    grass: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#5b7a3a'),
+      ...speckle('#3f5828', 16),
+      ...speckle('#7f9c50', 8),
+    ]),
+    rock: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#5b7a3a'),
+      rect(6, 6,  22, 22, '#8c8c8c'),
+      rect(6, 22, 22, 6,  '#6e6e6e'),
+      rect(8, 8,  8,  4,  '#a8a8a8'),
+    ]),
+    container: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#8a3a1f'),
+      // Original drew vertical ridges every 4 pixels via two thin rects.
+      ...[0, 4, 8, 12, 16, 20, 24, 28].flatMap((x) => [
+        rect(x, 0,     1, TILE_SIZE, '#5e2511'),
+        rect(x + 1, 0, 1, TILE_SIZE, '#a8482a'),
+      ]),
+      rect(0, 0,            TILE_SIZE, 2, '#3e1a0c'),
+      rect(0, TILE_SIZE - 2, TILE_SIZE, 2, '#3e1a0c'),
+    ]),
+    container_door: await makeTile([
+      rect(0, 0, TILE_SIZE, TILE_SIZE, '#8a3a1f'),
+      rect(6, 4,  20, 26, '#1a0e06'),
+      rect(8, 6,  16, 22, '#3a2010'),
+      rect(20, 16, 2, 4,  '#d9b34a'), // door handle
+    ]),
+  };
+}
+
+// Phase 7 map layout (mirrors public/game/world/map.js at commit 0b13bb4).
+function phase7TileAt(x, y) {
+  if (y >= WORLD_ROWS - 4) return 'sea';
+  if (y === WORLD_ROWS - 5) return 'wet_sand';
+  if (y >= 6) return 'sand';
+  // Top band: scattered grass + occasional rocks (deterministic).
+  if ((x * 37 + y * 53) % 11 === 0) return 'rock';
+  return 'grass';
+}
+
+// Procedural player sprite (down-facing) — mirrors playerSprite.js paintDown
+// at commit 0b13bb4. Returned as a 32×32 PNG buffer.
+async function buildPhase7Player() {
+  const svg = Buffer.from(`<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32">
+  <rect x="6"  y="28" width="20" height="3" fill="#0e0c08" fill-opacity="0.4"/>
+  <rect x="11" y="22" width="4"  height="7" fill="#4a3618"/>
+  <rect x="17" y="22" width="4"  height="7" fill="#4a3618"/>
+  <rect x="9"  y="14" width="14" height="9" fill="#7a5a2a"/>
+  <rect x="9"  y="22" width="14" height="1" fill="#c8a85a"/>
+  <rect x="11" y="6"  width="10" height="8" fill="#e8c39a"/>
+  <rect x="12" y="13" width="8"  height="1" fill="#b08858"/>
+  <rect x="10" y="5"  width="12" height="4" fill="#3a2918"/>
+  <rect x="10" y="8"  width="2"  height="2" fill="#3a2918"/>
+  <rect x="20" y="8"  width="2"  height="2" fill="#3a2918"/>
+  <rect x="13" y="10" width="2"  height="2" fill="#1a1208"/>
+  <rect x="17" y="10" width="2"  height="2" fill="#1a1208"/>
+  <rect x="7"  y="16" width="2"  height="5" fill="#e8c39a"/>
+  <rect x="23" y="16" width="2"  height="5" fill="#e8c39a"/>
+</svg>`);
+  return sharp(svg).png().toBuffer();
+}
+
+// Procedural vendor sprite — mirrors buildVendorSprite at commit 0b13bb4.
+async function buildPhase7Vendor() {
+  const svg = Buffer.from(`<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32">
+  <rect x="8"  y="4"  width="16" height="26" fill="#3a2914" fill-opacity="0.67"/>
+  <rect x="7"  y="3"  width="18" height="28" fill="#8a6a3a" fill-opacity="0.33"/>
+  <rect x="7"  y="28" width="18" height="3"  fill="#0e0c08" fill-opacity="0.53"/>
+  <rect x="9"  y="14" width="14" height="14" fill="#3a2814"/>
+  <rect x="11" y="16" width="10" height="10" fill="#1f1407"/>
+  <rect x="9"  y="14" width="14" height="1"  fill="#c8a85a"/>
+  <rect x="9"  y="27" width="14" height="1"  fill="#c8a85a"/>
+  <rect x="14" y="22" width="4"  height="3"  fill="#d8b890"/>
+  <rect x="11" y="12" width="10" height="5"  fill="#d6cfb6"/>
+  <rect x="12" y="16" width="8"  height="2"  fill="#a8a08a"/>
+  <rect x="12" y="7"  width="8"  height="6"  fill="#e8c39a"/>
+  <rect x="13" y="9"  width="2"  height="2"  fill="#0e0c08"/>
+  <rect x="17" y="9"  width="2"  height="2"  fill="#0e0c08"/>
+  <rect x="14" y="9"  width="1"  height="1"  fill="#f5e8b8"/>
+  <rect x="18" y="9"  width="1"  height="1"  fill="#f5e8b8"/>
+</svg>`);
+  return sharp(svg).png().toBuffer();
+}
+
+async function renderPhase7Placeholder(outPath) {
+  const tiles = await buildPhase7Tiles();
+  const playerPng = await buildPhase7Player();
+  const vendorPng = await buildPhase7Vendor();
+
+  const composites = [];
+  for (let y = 0; y < WORLD_ROWS; y++) {
+    for (let x = 0; x < WORLD_COLS; x++) {
+      const key = phase7TileAt(x, y);
+      composites.push({
+        input: tiles[key],
+        left: x * TILE_SIZE,
+        top:  y * TILE_SIZE,
+      });
+    }
+  }
+
+  // Container overlay: 4 wide × 2 tall at (13, 8). Door at (13, 9).
+  for (let dy = 0; dy < 2; dy++) {
+    for (let dx = 0; dx < 4; dx++) {
+      composites.push({
+        input: tiles.container,
+        left: (13 + dx) * TILE_SIZE,
+        top:  (8 + dy) * TILE_SIZE,
+      });
+    }
+  }
+  composites.push({
+    input: tiles.container_door,
+    left: 13 * TILE_SIZE,
+    top:  9 * TILE_SIZE,
+  });
+
+  // Vendor at his canonical (13, 9) door cell; player at spawn (10, 10).
+  composites.push({ input: vendorPng, left: 13 * TILE_SIZE, top: 9 * TILE_SIZE });
+  composites.push({ input: playerPng, left: 10 * TILE_SIZE, top: 10 * TILE_SIZE });
+
+  await sharp({
+    create: { width: WIDTH, height: HEIGHT, channels: 3, background: { r: 0, g: 0, b: 0 } },
+  })
+    .composite(composites)
+    .png({ compressionLevel: 9 })
+    .toFile(outPath);
+  console.log(`[pre-art] wrote ${outPath} (Phase 7 procedural placeholder)`);
+}
+
+// ---------- Hello-world page → PNG ------------------------------------------
+//
+// Mirrors server.js at commit faa8c77 — black bg, gold-tinted serif/mono
+// type, three lines of copy. We render to PNG via sharp's SVG support.
+
+async function renderHelloWorld(outPath) {
+  // Mirror server.js at commit faa8c77 — original body CSS was:
+  //   max-width: 640px; margin: 80px auto; padding: 24px;
+  //   font-family: ui-monospace, "Courier New", monospace;
+  //   background: #0e0c08; color: #e8d59a; line-height: 1.6;
+  //   h1  { font-size: 2.4em; letter-spacing: 0.05em; color: #f5e8b8; }
+  //   .meta { margin-top: 56px; font-size: 0.82em; color: #6b5d3d; }
+  //
+  // Layout: 640-wide content block centered in viewport, text LEFT-aligned
+  // inside it. 80px top margin + 24px padding from the content frame.
+  const contentW = 640;
+  const x0 = (WIDTH - contentW) / 2 + 24;  // left edge of text inside the padded frame
+  const baseFs = 16;                       // browser default 1em
+  const h1Fs = baseFs * 2.4;               // ~38px
+  const bodyFs = baseFs;                   // 16px
+  const metaFs = baseFs * 0.82;            // ~13px
+  const line = baseFs * 1.6;               // 26px (line-height)
+  const top = 80 + 24;                     // body margin-top + padding-top
+  const h1Y = top + h1Fs;                  // baseline of h1
+  const gap = h1Fs * 0.4;                  // h1 margin-bottom
+  const p1Y = h1Y + gap + bodyFs;
+  const p2Y = p1Y + line;
+  const metaY = p2Y + 56 + bodyFs;         // .meta has margin-top: 56px
+
+  const svg = Buffer.from(`<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}">
+  <rect width="${WIDTH}" height="${HEIGHT}" fill="#0e0c08"/>
+  <g font-family="ui-monospace, 'Courier New', 'Menlo', monospace">
+    <text x="${x0}" y="${h1Y}"
+          fill="#f5e8b8" font-size="${h1Fs}"
+          letter-spacing="0.05em">Amazonprimea</text>
+    <text x="${x0}" y="${p1Y}"
+          fill="#e8d59a" font-size="${bodyFs}">The container has not yet washed ashore.</text>
+    <text x="${x0}" y="${p2Y}"
+          fill="#e8d59a" font-size="${bodyFs}">Check back soon.</text>
+    <text x="${x0}" y="${metaY}"
+          fill="#6b5d3d" font-size="${metaFs}">— Off the Boats / Hermeslines</text>
+  </g>
+</svg>`);
+
+  await sharp(svg)
+    .png({ compressionLevel: 9 })
+    .toFile(outPath);
+  console.log(`[pre-art] wrote ${outPath} (hello-world page)`);
+}
+
+// ---------- manifest -------------------------------------------------------
+
+function upsertSnapshot(manifest, entry) {
+  if (!Array.isArray(manifest.snapshots)) manifest.snapshots = [];
+  const idx = manifest.snapshots.findIndex((s) => s.id === entry.id);
+  if (idx >= 0) manifest.snapshots[idx] = { ...manifest.snapshots[idx], ...entry };
+  else manifest.snapshots.push(entry);
+  manifest.snapshots.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+  manifest.version = 2;
+  return manifest;
+}
+
+// ---------- main -----------------------------------------------------------
+
+const PRE_ART_SNAPSHOTS = [
+  {
+    id: 'hello-world',
+    sha: 'faa8c77e5342b1baa4fc6cbb0a83e7561d303840',
+    timestamp: '2026-05-08T19:16:33-04:00',
+    label: 'The container has not yet washed ashore',
+    image: 'hello-world.png',
+    render: renderHelloWorld,
+  },
+  {
+    id: 'phase7-placeholder',
+    sha: '0b13bb44100cead07eb780998c71be6b06f51cc8',
+    timestamp: '2026-05-08T20:21:06-04:00',
+    label: 'The first playable world — colored tiles, no art yet',
+    image: 'phase7-placeholder.png',
+    render: renderPhase7Placeholder,
+  },
+];
+
+mkdirSync(SNAPSHOTS_DIR, { recursive: true });
+
+let manifest = { version: 2, snapshots: [] };
+if (existsSync(MANIFEST_PATH)) {
+  try { manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf8')); } catch { /* ignore */ }
+}
+
+for (const snap of PRE_ART_SNAPSHOTS) {
+  await snap.render(resolve(SNAPSHOTS_DIR, snap.image));
+  upsertSnapshot(manifest, {
+    id: snap.id,
+    sha: snap.sha,
+    timestamp: snap.timestamp,
+    label: snap.label,
+    image: snap.image,
+  });
+}
+
+writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+console.log(`[pre-art] manifest now has ${manifest.snapshots.length} entries`);