Portraits step 3: persona panel Portrait section + per-hero caching

- New "Portrait" section in the hero panel: an editable appearance prompt (auto-
built from name/class/about) and a 🎨 paint button that generates a portrait via
the active image provider (local Z-Image or cloud FLUX), shown beneath it.
- Reuses the voice spinner/badge UX (now generalized to .persona-ico): the button
badges when there's no portrait or the appearance changed, spins while painting.
- Per-hero PNG cached in IndexedDB (new 'portraits' store, DB v2) and the appearance
prompt persisted, so portraits survive a refresh and live in the barracks.

Verified locally: section renders with auto-appearance; 🎨 paints a 1024² portrait
(~15 s on the 3090) that renders + persists across reload; badge clears when current.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

web/personaPanel.js

@@ -11,7 +11,8 @@ import {
   createVoiceWav, cloneVoiceWav, playWav, synthVoiceWav, speakVoiceLive, stopVoiceLive,
   activeEngineIsDesign, activeEngineIsNative, activeVoices, activeDefaultVoice, onTtsEngineChange,
 } from '/web/tts.js'
-import { listPersonas, savePersona, removePersona, onRosterChange, putAudio, getAudio } from '/web/personaStore.js'
+import { listPersonas, savePersona, removePersona, onRosterChange, putAudio, getAudio, putPortrait, getPortrait } from '/web/personaStore.js'
+import { generatePortrait, imageBackendLabel } from '/web/imagen.js'
 
 const CLASSES = ['Warrior', 'Ranger', 'Monk', 'Assassin', 'Mage', 'Paladin', 'Cleric', 'Knight']
 const MAX_TOKENS = 200 // persona JSON + a voice line + a quote
@@ -155,6 +156,12 @@ export function mountPersonaPanel(host) {
   // needed and replays it otherwise. A pulsing badge shows when there's no voice yet, or
   // the quote/voice was edited since the last one was made.
   const playBtn = el('button', { class: 'persona-ico persona-play', type: 'button', title: 'Play voice' }, '▶')
+  // Portrait: an editable appearance prompt + a 🎨 button that paints it (Z-Image/FLUX),
+  // cached per hero. Badge pulses when there's no portrait yet or the appearance changed.
+  const appearanceEl = el('div', { class: 'persona-appearance persona-edit', 'data-ph': 'How they look…' })
+  const portraitBtn = el('button', { class: 'persona-ico persona-portrait-btn', type: 'button', title: 'Paint portrait' }, '🎨')
+  const portraitImg = el('img', { class: 'persona-portrait-img', alt: '' })
+  const portraitWrap = el('div', { class: 'persona-portrait-wrap' }, [portraitImg])
   const thinkEl = el('pre', { class: 'persona-think' })
   const copyBtn = el('button', { class: 'persona-copy', type: 'button' }, '📋 Copy debug')
   const thinkWrap = el('details', { class: 'persona-think-wrap' },
@@ -176,6 +183,7 @@ export function mountPersonaPanel(host) {
     secHead('About'), aboutEl,
     secHead('Quote', playBtn), quoteEl,
     secHead('Voice design'), voiceEl, voicePickRow,
+    secHead('Portrait', portraitBtn), appearanceEl, portraitWrap,
   ])
   const result = el('div', { class: 'persona-result' }, [emptyEl, bodyEl, thinkWrap])
   host.appendChild(el('div', { class: 'persona-view' }, [controls, result]))
@@ -183,6 +191,9 @@ export function mountPersonaPanel(host) {
   let lastPersona = null  // the persona currently shown
   let savedId = null      // its roster id (set the moment it's shown — always saved)
   let hasVoice = false    // a cached voice file exists for this persona
+  let hasPortrait = false // a cached portrait exists for this persona
+  let portraitBusy = false
+  let portraitUrl = null  // object URL for the shown image (revoked on replace)
   let working = false
   let busy = false
   let playing = false     // audio is currently sounding (▶ becomes ⏹)
@@ -286,6 +297,49 @@ export function mountPersonaPanel(host) {
   editable(quoteEl, 'quote', { single: true })
   editable(voiceEl, 'voice')
 
+  // ── Portrait ──────────────────────────────────────────────────────────────
+  const PORTRAIT_STYLE = 'Fantasy hero character portrait, painterly digital art, dramatic lighting, head and shoulders, detailed face, plain background.'
+  const buildAppearance = (p) => [
+    [p.name, p.unitClass && `a ${p.unitClass}`].filter(Boolean).join(', '),
+    (p.about || '').trim(),
+  ].filter(Boolean).join('. ')
+  const appearanceFor = (p) => (p.appearance || '').trim() || buildAppearance(p)
+  const portraitDirty = () => hasPortrait && lastPersona && appearanceFor(lastPersona) !== (lastPersona.portraitUsed || '')
+
+  function setPortrait(blob) {
+    if (portraitUrl) { try { URL.revokeObjectURL(portraitUrl) } catch { /* ignore */ } }
+    portraitUrl = blob ? URL.createObjectURL(blob) : null
+    portraitImg.src = portraitUrl || ''
+    portraitWrap.classList.toggle('has-img', !!blob)
+  }
+  function updatePortraitUI() {
+    portraitBtn.classList.toggle('badged', !!lastPersona && (!hasPortrait || portraitDirty()))
+    portraitBtn.title = !hasPortrait ? 'Paint portrait' : 'Repaint portrait'
+  }
+  // Make the appearance field click-to-edit (drives the prompt + the badge).
+  appearanceEl.contentEditable = 'true'; appearanceEl.spellcheck = false
+  appearanceEl.addEventListener('input', () => { if (lastPersona) { lastPersona.appearance = appearanceEl.textContent.trim(); updatePortraitUI() } })
+  appearanceEl.addEventListener('blur', () => { if (!lastPersona) return; lastPersona.appearance = appearanceEl.textContent.trim(); autosave(); updatePortraitUI() })
+
+  // 🎨 Generate (or regenerate) the portrait from the appearance prompt; cache + persist.
+  async function makePortrait() {
+    if (portraitBusy || !lastPersona) return
+    autosave() // ensure an id to key the image
+    const appearance = appearanceFor(lastPersona)
+    portraitBusy = true; portraitBtn.classList.add('busy'); portraitBtn.disabled = true
+    const prev = status.textContent
+    status.textContent = `painting with ${imageBackendLabel()}…`
+    try {
+      const blob = await generatePortrait(`${appearance}. ${PORTRAIT_STYLE}`, { seed: 42 })
+      await putPortrait(savedId, blob)
+      lastPersona.appearance = appearance; lastPersona.portraitUsed = appearance
+      hasPortrait = true; setPortrait(blob); autosave()
+      status.textContent = prev
+    } catch (e) { status.textContent = `portrait failed: ${e.message || e}` }
+    finally { portraitBusy = false; portraitBtn.classList.remove('busy'); portraitBtn.disabled = false; updatePortraitUI() }
+  }
+  portraitBtn.addEventListener('click', makePortrait)
+
   async function showPersona(p, opts = {}) {
     stopVoice() // picking another hero cuts the current voice
     lastPersona = { ...p }
@@ -294,8 +348,12 @@ export function mountPersonaPanel(host) {
     aboutEl.textContent = p.about || ''
     quoteEl.textContent = p.quote || ''
     voiceEl.textContent = p.voice || ''
+    appearanceEl.textContent = p.appearance || buildAppearance(p)
     hasVoice = savedId ? !!(await getAudio(savedId)) : false
-    refreshVoiceMode(); updateVoiceUI(); refreshVisibility()
+    let pblob = null
+    hasPortrait = savedId ? !!(pblob = await getPortrait(savedId)) : false
+    setPortrait(pblob)
+    refreshVoiceMode(); updateVoiceUI(); updatePortraitUI(); refreshVisibility()
   }
 
   // ▶ The one voice button: if the cached voice is current, just replay it. If the voice
@@ -409,9 +467,9 @@ export function mountPersonaPanel(host) {
     busy = true; btn.disabled = true; refreshVisibility()
     if (window.innerWidth <= 768) result.scrollIntoView({ behavior: 'smooth', block: 'start' })
     nameEl.textContent = '…'; aboutEl.textContent = ''
-    quoteEl.textContent = ''; voiceEl.textContent = ''
-    lastPersona = null; savedId = null; hasVoice = false
-    stopVoice(); updateVoiceUI()
+    quoteEl.textContent = ''; voiceEl.textContent = ''; appearanceEl.textContent = ''
+    lastPersona = null; savedId = null; hasVoice = false; hasPortrait = false
+    stopVoice(); setPortrait(null); updateVoiceUI(); updatePortraitUI()
     thinkEl.textContent = ''; thinkWrap.open = true; stats.textContent = ''
     let acc = ''
     try {

web/personaStore.js

@@ -50,6 +50,10 @@ export function savePersona(p) {
     voiceQuote: p.voiceQuote || '',
     voiceDesignUsed: p.voiceDesignUsed || '',
     voiceIdUsed: p.voiceIdUsed || '',
+    // Portrait: the editable appearance prompt + what the cached image (IndexedDB) was
+    // made from, so a reload knows the image is current vs stale (re-generate it).
+    appearance: p.appearance || '',
+    portraitUsed: p.portraitUsed || '',
     createdAt: now,
     updatedAt: now,
   }
@@ -64,35 +68,43 @@ export function removePersona(id) {
   const d = read()
   const next = d.personas.filter((x) => x.id !== id)
   if (next.length !== d.personas.length) write({ personas: next })
-  delAudio(id)
+  _del(STORE, id); _del(PSTORE, id)
 }
 
-// ── Voice audio store (IndexedDB — WAV blobs are too big for localStorage) ──────
-const DB = 'tinyarmy', STORE = 'voices'
+// ── Media store (IndexedDB — WAV + PNG blobs are too big for localStorage) ──────
+const DB = 'tinyarmy', STORE = 'voices', PSTORE = 'portraits'
 let _dbp = null
 function db() {
   if (!_dbp) {
     _dbp = new Promise((res, rej) => {
-      const r = indexedDB.open(DB, 1)
-      r.onupgradeneeded = () => { if (!r.result.objectStoreNames.contains(STORE)) r.result.createObjectStore(STORE) }
+      const r = indexedDB.open(DB, 2) // v2 adds the 'portraits' store alongside 'voices'
+      r.onupgradeneeded = () => {
+        const d = r.result
+        if (!d.objectStoreNames.contains(STORE)) d.createObjectStore(STORE)
+        if (!d.objectStoreNames.contains(PSTORE)) d.createObjectStore(PSTORE)
+      }
       r.onsuccess = () => res(r.result)
       r.onerror = () => rej(r.error)
     })
   }
   return _dbp
 }
-export async function putAudio(id, blob) {
+async function _put(store, id, blob) {
   try {
     const d = await db()
-    await new Promise((res, rej) => { const t = d.transaction(STORE, 'readwrite'); t.objectStore(STORE).put(blob, id); t.oncomplete = res; t.onerror = () => rej(t.error) })
+    await new Promise((res, rej) => { const t = d.transaction(store, 'readwrite'); t.objectStore(store).put(blob, id); t.oncomplete = res; t.onerror = () => rej(t.error) })
   } catch { /* best-effort */ }
 }
-export async function getAudio(id) {
+async function _get(store, id) {
   try {
     const d = await db()
-    return await new Promise((res) => { const t = d.transaction(STORE, 'readonly'); const q = t.objectStore(STORE).get(id); q.onsuccess = () => res(q.result || null); q.onerror = () => res(null) })
+    return await new Promise((res) => { const t = d.transaction(store, 'readonly'); const q = t.objectStore(store).get(id); q.onsuccess = () => res(q.result || null); q.onerror = () => res(null) })
   } catch { return null }
 }
-async function delAudio(id) {
-  try { const d = await db(); d.transaction(STORE, 'readwrite').objectStore(STORE).delete(id) } catch { /* ignore */ }
+async function _del(store, id) {
+  try { const d = await db(); d.transaction(store, 'readwrite').objectStore(store).delete(id) } catch { /* ignore */ }
 }
+export const putAudio = (id, blob) => _put(STORE, id, blob)
+export const getAudio = (id) => _get(STORE, id)
+export const putPortrait = (id, blob) => _put(PSTORE, id, blob)
+export const getPortrait = (id) => _get(PSTORE, id)

web/shell/persona.css

@@ -111,6 +111,18 @@
 .persona-voice-pick-row { margin-top: 12px; max-width: 320px; }
 .persona-voice-pick-row .persona-label { margin-top: 0; }
 .persona-voice-pick { margin-top: 4px; }
+
+/* Portrait — an editable appearance prompt + the painted image. */
+.persona-appearance {
+  font-family: var(--p-mono); font-size: 12px; line-height: 1.5; color: var(--p-muted);
+  max-width: 60ch; margin-top: 8px; font-style: italic;
+}
+.persona-portrait-wrap { margin-top: 12px; }
+.persona-portrait-wrap:not(.has-img) { display: none; }
+.persona-portrait-img {
+  width: 320px; max-width: 100%; aspect-ratio: 1 / 1; object-fit: cover; display: block;
+  border: 1.5px solid var(--p-ink); box-shadow: 4px 4px 0 var(--p-transmit); background: var(--p-card);
+}
 .persona-quote {
   margin: 8px 0 0; padding: 4px 0 4px 16px; border-left: 3px solid var(--p-transmit);
   font-family: 'Fraunces', Georgia, serif; font-size: 21px; font-style: italic;
@@ -127,16 +139,16 @@
 }
 .persona-ico:hover { background: var(--p-paper-2) !important; }
 .persona-ico.busy { cursor: default; }
-/* Generating a voice → hide the glyph and spin a small ring in its place. */
-.persona-play.busy { color: transparent !important; }
-.persona-play.busy::before {
+/* Working (voice/portrait) → hide the glyph and spin a small ring in its place. */
+.persona-ico.busy { color: transparent !important; }
+.persona-ico.busy::before {
   content: ''; position: absolute; inset: 0; margin: auto; width: 11px; height: 11px;
   border: 2px solid var(--p-paper-2); border-top-color: var(--p-transmit); border-radius: 50%;
   animation: tac-spin .7s linear infinite;
 }
 @keyframes tac-spin { to { transform: rotate(360deg); } }
-/* Badge = "no voice yet, or the quote/voice changed — tap to (re)make it." Pulses. */
-.persona-play.badged::after {
+/* Badge = "nothing made yet, or the inputs changed — tap to (re)make it." Pulses. */
+.persona-ico.badged::after {
   content: ''; position: absolute; top: -4px; right: -4px; width: 9px; height: 9px;
   background: var(--p-transmit); border: 1.5px solid var(--p-card); border-radius: 50%;
   animation: tac-badge-pulse 1.3s ease-out infinite;