pixel-face — author & refine the Frontier Faces pixel art

A persona face is pure data in examples/04-frontier-faces/personas.mjs (one entry per persona). The same data drives the terminal renderer (face-term.mjs), the browser element (web/cotal-face.js), and the PNG tool — so edit personas.mjs once and it's live everywhere. Always work from examples/04-frontier-faces/.

Where things are

• personas.mjs — the entries (rows, colors, glow, mouths, expr, eyes, lines). Single source of truth.
• FACE-DESIGN.md — the full conventions (grid zones, color keys, eye recipe, visemes). Read it first.
• tools/img2rows.mjs — rough a reference photo into a 32×32 rows+palette.
• tools/render-png.mjs — render a 7-state contact sheet (PNG) for review. This is the validator.
• tools/face-template.mjs — copy-me starter entry that encodes the conventions.
• gallery.html (all personas, original-vs-pixel) and preview.html?p=<key> (one persona) — served via python3 -m http.server or tools/serve-wall.mjs; for visual QA.
• assets/<persona-key>.<ext> — reference photos. Gitignored / local-only — never commit them.

Persona key ≠ agent name. The roster uses agent-file basenames; the face comes from each agent's face: frontmatter: elon→musk, steve→jobs, rayan→ray (others match). Persona keys: neon david ray sven garry jobs musk dario mira bernie michelle.

Conventions (condensed — full detail in FACE-DESIGN.md)

• Grid 32×32, . = transparent, face centered ~col 15. Zones: hair 1–9 · brows 10–11 (drawn by expr, not rows) · eyes 12–13 (drawn by eyes()) · nose 14–16 · mouth 18–20 (drawn by mouths) · chin 21–24 · collar 26–31.
• Color keys: skin P light / S mid / s shadow · E pupil · W/w catchlight · R lip · m lip-shadow · b brow · h hair · L cyan + M magenta = the cotal glow ribbon (glow: { L: 8, M: 6 } blurs them). Use rng(row, c1, c2, key) (exported from personas.mjs) for runs.
• Eye recipe: 2-wide iris (E) on the iris row; row below = catchlight (W/w, OUTER corner)
  • lid-shadow (s, INNER). jobs is the "alive" benchmark — match its eye, don't use flat black blocks.
• Surprise = raised brows + open mouth, eyes stay open (growing the iris behind glasses looks wrong). Don't reintroduce a wide eye style.
• The face renders at a fixed 32×16 (not scaled to the pane), so faces look the same size as long as the pane is ≥ ~32 cols.

Tools (exact)

# rough a reference photo → 32×32 rows + palette (macOS: uses sips)
node tools/img2rows.mjs --in assets/<key>.png --w 24 --h 30 [--colors 12] [--x0 4] [--y0 0]

# render a 7-state contact sheet (neutral·happy·sad·angry·surprised·talking·blink) to review
node tools/render-png.mjs --file <draft>.mjs --out /tmp/<key>.png --scale 8     # draft: export const entry = {…}
node tools/render-png.mjs --file personas.mjs --persona <key> --out /tmp/<key>.png --scale 8   # existing

A draft module must export const entry = {…} and (if it uses rng in expr/mouths) import { rng } from '/abs/path/examples/04-frontier-faces/personas.mjs'. After every render, Read the PNG and compare it to assets/<key>.<ext>. Iterate.

Create a new persona

1. Pick a key. If you have a photo, save it as assets/<key>.png and img2rows it for a rough base; otherwise copy tools/face-template.mjs.
2. Hand-edit a /tmp/<key>-draft.mjs (export const entry) following the conventions above.
3. render-png → Read the PNG → compare to the reference → iterate until all 7 states read well.
4. Splice the finished entry into personas.mjs (keep the file's style; reuse color keys).
5. Review in the gallery; confirm no other persona changed.

Improve an existing persona

1. Read its entry in personas.mjs + its reference assets/<key>.<ext> and the current render.
2. Edit only the in-scope rows (e.g. hair = rows 1–9). Preserve eyes(), glasses/beard, expr, mouths, colors of other features, and the collar/glow — change the minimum.
3. render-png the draft → Read → compare → iterate (≥3 passes). Then splice the rows back into personas.mjs and confirm the diff is limited to that entry.

Multi-agent variant loop (use for likeness — "doesn't look like them")

When matching a real person, generate options instead of guessing:

1. Spawn ~3 subagents on the main working tree (NOT git worktrees — assets/ is gitignored, so reference photos are absent from a fresh worktree). Give each: the reference path, the current entry, the conventions, and a distinct direction.
2. Each agent writes its OWN /tmp/<key>-<n>.mjs draft (never edits personas.mjs — avoids conflicts), renders it, Reads the PNG, compares to the photo, iterates, and returns the final rows.
3. You pick the best, splice it in, review in the gallery. Refine one axis per pass (e.g. head shape, then hair). This is the loop used for garry/musk.

QA bar

• Always review visually — the render-png contact sheet and the gallery.html original-vs-pixel view — never blind. Judge: does it read / look like the person across all 5 expressions + blink?
• jobs is the reference standard. Keep faces front-facing/symmetric unless intentional.
• Don't commit assets/ (reference photos stay local). Persona edits to personas.mjs ARE committable.