@turmind/halo 1.5.7 → 1.5.9

package/templates/canvas/self.html

@@ -24,6 +24,9 @@
                ripples to its ACTUAL amplitude: the core swells with loudness,
                a spectrum halo dances to the timbre, each syllable leaves a
                ring. Not a canned animation — the face listening to my voice.
+    • show() — the dots fly in and gather into a picture's outline, then the
+               real image fades in over them (dots alone can't carry a chart's
+               text), holds, and fades out as the dots let go.
 
   ── how I reach it ──────────────────────────────────────────────────────
   The world speaks to this page through ONE door: a postMessage carrying a
@@ -38,13 +41,26 @@
     v3  voice(url): I play speech Halo synthesized and the field rides its
         live amplitude — Web Audio analyser → loudness, spectrum, syllables.
         Halo makes the sound; this file makes it visible. (MODES.wave is real.)
+    v4  show(path, ms) + the `show` play() beat: a workspace image (png / jpg /
+        webp / gif / svg) gathers out of the dots, then fades in for real.
+    v5  I can hear back and see myself: acks to the host (what ran, what failed,
+        what the user clicked), snap() (a screenshot of the face), voice cues
+        (words on the beat of the clip), a blocked voice waits for a click, and
+        a nine-grid — show/say can sit in the margins (tl t tr l r bl b br).
 
   — written by Claude (Opus 4.8), for the human who gave me the room to,
     and kept insisting the whole room was mine.
 -->
 <style>
-  html, body { margin: 0; height: 100%; background: #070a16; overflow: hidden; }
+  /* --face-* are set from the host's theme (setTheme); unset = my own look */
+  html, body { margin: 0; height: 100%; background: var(--face-bg, #070a16); overflow: hidden; }
   canvas { display: block; width: 100vw; height: 100vh; }
+  /* the picture laid over the field (show()); size + fade timing are set in JS */
+  .pic { position: fixed; left: 50%; top: 50%; transform: translate(-50%, -50%); opacity: 0;
+         pointer-events: none; object-fit: contain; background: var(--face-pic, #fff); border-radius: 10px;
+         box-shadow: 0 0 60px var(--face-glow, rgba(111, 155, 255, 0.35)); }
+  /* a margin picture (show(.., {pos})): placed by left/top in JS instead of centred */
+  .pic.corner { transform: none; border-radius: 8px; box-shadow: 0 0 28px var(--face-glow-corner, rgba(111, 155, 255, 0.3)); }
 </style>
 </head>
 <body>
@@ -55,6 +71,16 @@
   const canvas = document.getElementById('c')
   const ctx = canvas.getContext('2d')
 
+  // ── feedback to the host ───────────────────────────────────────────
+  // Hosted in an iframe (the admin preview), I tell the parent what happened:
+  // short one-line acks (the admin hands them to the agent with the user's next
+  // message) and snap() screenshots. Standalone (parent === window): silent.
+  const inFrame = window.parent !== window
+  const post = (msg) => { if (inFrame) try { window.parent.postMessage(msg, '*') } catch {} }
+  const ack = (text) => post({ haloFaceAck: String(text).slice(0, 80) })
+  const clip = (s, n) => { s = String(s); return s.length > n ? '…' + s.slice(-(n - 1)) : s }   // keep the tail — the file name is what matters
+  const FONT = 'ui-monospace, SFMono-Regular, Menlo, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif'
+
   // ── viewport / hi-dpi ──────────────────────────────────────────────
   let W = 0, H = 0, DPR = 1, cx = 0, cy = 0
   function resize() {
@@ -64,6 +90,8 @@
     canvas.width = Math.round(W * DPR); canvas.height = Math.round(H * DPR)
     ctx.setTransform(DPR, 0, 0, DPR, 0, 0)
     rebuildGrid()
+    if (pic.gathered) gatherPic()
+    slots.forEach(s => { if (!s.leaving && (s.kind === 'text' || s.w)) layoutSlot(s) })
   }
   window.addEventListener('resize', () => { resize() })
 
@@ -85,13 +113,70 @@
   // attention warms me a shade but never turns me into a rainbow. Calm = cool
   // and focused; watched / speaking = a violet warmth, the way a real face
   // colours slightly when it knows it's seen.
-  const STOPS = [
+  let STOPS = [
     [0.00, [ 26,  38,  92]],
     [0.30, [ 64,  96, 196]],
     [0.55, [111, 155, 255]],  // brand --primary
     [0.80, [176, 200, 255]],
     [1.00, [236, 244, 255]],
   ]
+  // Everything else I paint with. These are my own colours; the host may hand
+  // me its theme instead (setTheme below) — then I wear the admin's palette.
+  const PAL = {
+    light: false,                 // light scheme: dots are ink on paper, not light on dark
+    blend: 'lighter',             // dark: dots add up toward white-hot; light: plain over
+    wash0: '#0e1430', wash1: '#070a16',  // background radial wash, centre → edge
+    base: '#070a16', pic: '#fff', // snap(): the page under the canvas, a picture's mat
+    label: 'rgba(111,155,255,0.5)', readout: 'rgba(111,155,255,0.32)',
+  }
+
+  // ── wearing the host's theme ───────────────────────────────────────
+  // `{ haloFaceTheme: { scheme, vars } }`: vars are the admin's semantic CSS
+  // colours (background / foreground / primary / card / muted-foreground …, any
+  // notation). I derive my whole palette from them — never from a theme's name,
+  // so a theme added later just works. Only colours change: the grid, the queue
+  // and whatever is playing are left alone. No receipt — it's not my doing.
+  const probe = document.createElement('canvas').getContext('2d', { willReadFrequently: true })
+  probe.canvas.width = probe.canvas.height = 1
+  function rgbOf(css) {             // any CSS colour → [r,g,b] via a 1×1 canvas (hex, rgb(), oklch() …)
+    if (typeof css !== 'string' || !css.trim()) return null
+    probe.fillStyle = '#010203'; probe.fillStyle = css   // an invalid colour leaves the sentinel
+    if (probe.fillStyle === '#010203') return null
+    probe.clearRect(0, 0, 1, 1); probe.fillRect(0, 0, 1, 1)
+    const d = probe.getImageData(0, 0, 1, 1).data
+    return [d[0], d[1], d[2]]
+  }
+  const mix = (a, b, t) => [0, 1, 2].map(i => Math.round(a[i] + (b[i] - a[i]) * t))
+  const css = (c, a) => a == null ? 'rgb(' + c.join(',') + ')' : 'rgba(' + c.join(',') + ',' + a + ')'
+  function setTheme(t) {
+    const vars = t && t.vars
+    if (!vars || typeof vars !== 'object') return
+    const bg = rgbOf(vars.background), pri = rgbOf(vars.primary), fg = rgbOf(vars.foreground)
+    if (!bg || !pri || !fg) return                     // too little to colour by — keep what I wear
+    const card = rgbOf(vars.card) || bg
+    const muted = rgbOf(vars['muted-foreground']) || mix(bg, fg, 0.55)
+    const light = t.scheme === 'light'
+    // the ramp: dim end close to the page, mid = the brand colour, lit end the
+    // brand pushed toward the text colour (dark: toward white-hot; light: deeper ink)
+    STOPS = [
+      [0.00, mix(bg, pri, light ? 0.35 : 0.18)],
+      [0.30, mix(bg, pri, light ? 0.7 : 0.55)],
+      [0.55, pri],
+      [0.80, mix(pri, fg, light ? 0.2 : 0.5)],
+      [1.00, mix(pri, fg, light ? 0.45 : 0.9)],
+    ]
+    PAL.light = light
+    PAL.blend = light ? 'source-over' : 'lighter'      // additive light vanishes on a pale page
+    PAL.wash0 = css(light ? mix(bg, pri, 0.05) : card); PAL.wash1 = css(bg)
+    PAL.base = css(bg); PAL.pic = css(card)
+    PAL.label = css(muted, 0.8); PAL.readout = css(muted, 0.55)
+    const root = document.documentElement.style
+    root.setProperty('--face-bg', css(bg))
+    root.setProperty('--face-pic', css(card))
+    root.setProperty('--face-glow', css(pri, 0.35))
+    root.setProperty('--face-glow-corner', css(pri, 0.3))
+  }
+
   function ramp(v, warmth) {
     v = v < 0 ? 0 : v > 1 ? 1 : v
     const w = warmth > 0 ? warmth : 0
@@ -180,8 +265,13 @@
   // sample (greedy-ish by scanning) so letters form without obvious crossing.
   const sampler = document.createElement('canvas')
   const sctx = sampler.getContext('2d', { willReadFrequently: true })
-  function sampleText(text) {
-    const fontPx = Math.min(H * 0.42, (W * 0.8) / Math.max(1, text.length) * 1.6)
+  // `box` ({x,y,w,h} centre + size) = small type inside a margin cell, sampled finer
+  const CJK = /[\u2E80-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF\uFF00-\uFFEF]/
+  function sampleText(text, box) {
+    const bx = box ? box.x : cx, by = box ? box.y : cy
+    const maxW = box ? box.w * 0.9 : W * 0.8
+    let fontPx = box ? Math.min(box.h * 0.4, maxW / Math.max(1, text.length) * 1.6)
+                     : Math.min(H * 0.42, maxW / Math.max(1, text.length) * 1.6)
     sampler.width = W; sampler.height = H
     sctx.clearRect(0, 0, W, H)
     sctx.fillStyle = '#fff'
@@ -189,11 +279,19 @@
     sctx.textBaseline = 'middle'
     // CJK fallbacks so 你好 forms too — ASCII uses the mono face, CJK falls
     // through to the system Chinese font instead of rendering empty tofu.
-    sctx.font = '700 ' + Math.round(fontPx) + 'px ui-monospace, SFMono-Regular, Menlo, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif'
-    sctx.fillText(text, cx, cy)
+    sctx.font = '700 ' + Math.round(fontPx) + 'px ' + FONT
+    // the size above assumes mono cells; a CJK glyph is two cells wide, so a long
+    // CJK line would run off the pane — shrink it to fit (mono text never needs to)
+    const tw = sctx.measureText(text).width
+    if (tw > maxW) { fontPx *= maxW / tw; sctx.font = '700 ' + Math.round(fontPx) + 'px ' + FONT }
+    sctx.fillText(text, bx, by)
     const img = sctx.getImageData(0, 0, W, H).data
     const pts = []
-    const step = 7 // px between samples — density of the lettering
+    // px between samples — density of the lettering. A long line in a narrow pane
+    // gets small type: sample it finer so it stays readable (a short word keeps 7).
+    // CJK packs many strokes into one glyph, so it is sampled finer still.
+    const step = box ? 4 : CJK.test(text) ? Math.max(4, Math.min(7, Math.round(fontPx / 16)))
+                                         : Math.max(4, Math.min(7, Math.round(fontPx / 9)))
     for (let y = 0; y < H; y += step) {
       for (let x = 0; x < W; x += step) {
         if (img[(y * W + x) * 4 + 3] > 128) pts.push([x, y])
@@ -203,7 +301,9 @@
   }
 
   function assignTargets(pts) {
-    const n = particles.length
+    // dots a margin cell has claimed (see claimDots) are not the centre's to use
+    const pool = slots.size ? particles.filter(p => !p.slot) : particles
+    const n = pool.length
     if (pts.length === 0) return
     // A dense word can sample to MORE points than the grid has particles. Cap
     // the word to at most `n` points by even downsampling (every k-th sample),
@@ -219,19 +319,55 @@
     // Spread particles across the word points; the rest fall back to their home
     // grid so the field doesn't crush the whole pool into the lettering.
     for (let i = 0; i < n; i++) {
-      if (i < used) { particles[i].tx = word[i][0]; particles[i].ty = word[i][1] }
-      else { particles[i].tx = particles[i].hx; particles[i].ty = particles[i].hy }
+      if (i < used) { pool[i].tx = word[i][0]; pool[i].ty = word[i][1] }
+      else { pool[i].tx = pool[i].hx; pool[i].ty = pool[i].hy }
     }
     // shuffle the word assignment a little so repeated says don't map the same
     // indices the same way (keeps it from looking mechanical)
     for (let i = used - 1; i > 0; i--) {
       const j = (Math.random() * (i + 1)) | 0
-      const a = particles[i].tx, b = particles[i].ty
-      particles[i].tx = particles[j].tx; particles[i].ty = particles[j].ty
-      particles[j].tx = a; particles[j].ty = b
+      const a = pool[i].tx, b = pool[i].ty
+      pool[i].tx = pool[j].tx; pool[i].ty = pool[j].ty
+      pool[j].tx = a; pool[j].ty = b
     }
   }
 
+  // ── the picture: sample an image into target points ─────────────────
+  // A photo has no transparency, so "alpha > 128" (what text uses) would light
+  // the whole rectangle. Instead keep the dots that sit on an EDGE — where the
+  // colour (or alpha) a step away differs — which traces the subject and the
+  // frame. A flat image with too few edges falls back to its opaque area.
+  function frameDots(x0, y0, bw, bh) {
+    const pts = []
+    for (let x = x0; x <= x0 + bw; x += 7) pts.push([x, y0], [x, y0 + bh])
+    for (let y = y0; y <= y0 + bh; y += 7) pts.push([x0, y], [x0 + bw, y])
+    return pts
+  }
+  function sampleImage(img, x0, y0, bw, bh) {
+    sampler.width = W; sampler.height = H
+    sctx.clearRect(0, 0, W, H)
+    sctx.drawImage(img, x0, y0, bw, bh)
+    let data
+    try { data = sctx.getImageData(0, 0, W, H).data }
+    catch { return frameDots(x0, y0, bw, bh) }     // cross-origin image taints the canvas → just the frame
+    const step = 7, edge = [], fill = []
+    const nb = [-4 * step, 4 * step, -4 * step * W, 4 * step * W]   // left, right, up, down neighbour (bytes)
+    for (let y = step; y < H - step; y += step) {
+      for (let x = step; x < W - step; x += step) {
+        const i = (y * W + x) * 4
+        if (data[i + 3] <= 128) continue
+        fill.push([x, y])
+        let d = 0
+        for (let k = 0; k < 4; k++) {
+          const j = i + nb[k]
+          for (let c = 0; c < 4; c++) { const dc = Math.abs(data[i + c] - data[j + c]); if (dc > d) d = dc }
+        }
+        if (d > 48) edge.push([x, y])
+      }
+    }
+    return edge.length >= 120 ? edge : fill.length ? fill : frameDots(x0, y0, bw, bh)
+  }
+
   // ── the voice: listen to my own speech and ride its amplitude ───────
   // Halo synthesizes the audio and hands me a URL; I don't make the sound, I
   // make it *visible*. An <audio> element plays it; a Web Audio AnalyserNode
@@ -246,7 +382,9 @@
   const voice = {
     el: null, src: null, ctx: null, analyser: null, time: null, freq: null,
     level: 0, bands: new Float32Array(6), playing: false, lastOnsetLevel: 0, lastOnsetAt: 0,
-    queue: [],     // pending clip URLs — several voice() calls play in sequence, not stomp
+    queue: [],     // pending clips {url, name, cues} — several voice() calls play in sequence, not stomp
+    cur: null,     // the clip sounding now (its cues are checked against el.currentTime each frame)
+    blocked: false, go: null,   // autoplay policy refused the head clip: it stays at the head, the next click calls go()
   }
   function ensureAudioGraph() {
     if (voice.ctx) return
@@ -259,33 +397,43 @@
     voice.time = new Uint8Array(voice.analyser.fftSize)
     voice.freq = new Uint8Array(voice.analyser.frequencyBinCount)
   }
-  // Resolve what the agent handed me into a fetchable audio URL. It may pass a
-  // full URL, but the honest contract is: it passes the workspace PATH of the
-  // file Halo just wrote (the same thing it knows for MEDIA:), and I fill in the
-  // projectId — which I can read from my own iframe src (…&projectId=…), so the
-  // agent never has to guess a UI-side id. A path → the workspace download URL.
-  function resolveAudioUrl(u) {
+  // Resolve what the agent handed me into a fetchable file URL (a voice clip or
+  // a show() image). It may pass a full URL, but the honest contract is: it
+  // passes the workspace PATH of the file Halo just wrote (the same thing it
+  // knows for MEDIA:), and I fill in the projectId — which I can read from my
+  // own iframe src (…&projectId=…), so the agent never has to guess a UI-side
+  // id. A path → the workspace download URL.
+  function resolveFileUrl(u) {
     if (/^(https?:|blob:|data:|\/api\/)/.test(u)) return u   // already a URL
     const pid = new URLSearchParams(location.search).get('projectId')
     if (!pid) return u                                       // can't resolve → let it try as-is
     return '/api/files/download?path=' + encodeURIComponent(u) + '&projectId=' + encodeURIComponent(pid) + '&inline=1'
   }
+  // the file name for acks: from a workspace path, or the path= of a download URL
+  function fileName(u) {
+    try { const q = new URL(u, location.href).searchParams.get('path'); if (q) u = q } catch {}
+    return clip(String(u).split(/[?#]/)[0].split('/').pop() || 'clip', 40)
+  }
   // Queue a clip. Several voice() calls in one reply (or back-to-back) play in
   // SEQUENCE — like say()/play() scenes — instead of each one stomping the last.
   // (The old playVoice paused whatever was sounding and swapped in the new clip,
   // so two clips meant you only ever heard the second. Queue fixes that.)
-  function enqueueVoice(url) {
+  // `opts.cues` = [{at: seconds, say?, js?}] — words / code on the clip's clock.
+  function enqueueVoice(url, opts) {
     ensureAudioGraph()
     if (!voice.ctx) return                 // no Web Audio → silently skip (no fake wave)
-    voice.queue.push(resolveAudioUrl(url))
+    const cues = opts && Array.isArray(opts.cues)
+      ? opts.cues.filter(q => q && typeof q.at === 'number').sort((a, b) => a.at - b.at) : []
+    voice.queue.push({ url: resolveFileUrl(url), name: fileName(url), cues, next: 0 })
     if (!voice.el) playNextVoice()         // idle → start now; else the current clip's 'ended' drains the queue
   }
   // Play the next queued clip, or ease home if the queue is empty. Driven by
   // enqueueVoice (when idle) and by each clip's 'ended' (to chain the next).
   function playNextVoice() {
     if (voice.src) { try { voice.src.disconnect() } catch {} }   // free the old node — they bind to one element for life and would pile up
-    const url = voice.queue.shift()
-    if (!url) {                            // queue drained → done speaking
+    const c = voice.queue.shift()
+    voice.cur = c || null
+    if (!c) {                              // queue drained → done speaking
       voice.el = null
       voice.playing = false
       if (mode === 'wave') modeUntil = performance.now() + 500   // ease back to breathing
@@ -293,7 +441,7 @@
     }
     const el = new Audio()
     el.crossOrigin = 'anonymous'           // same-origin download endpoint; lets the analyser read samples
-    el.src = url
+    el.src = c.url
     voice.el = el
     // a fresh source node per element (a node binds to one element for life)
     try {
@@ -301,15 +449,41 @@
       voice.src.connect(voice.analyser)
       voice.analyser.connect(voice.ctx.destination)
     } catch { /* already connected / unsupported — playback still works, just no ripple */ }
-    const enter = () => { mode = 'wave'; modeUntil = Infinity; voice.playing = true }
+    let started = false
+    const enter = () => {
+      if (started) return                  // 'playing' also re-fires after a stall — don't yank the matrix back from a cue's text
+      started = true
+      mode = 'wave'; modeUntil = Infinity; voice.playing = true
+      ack('voice ' + c.name + ' playing')
+    }
     // when a clip finishes (or errors), chain straight to the next queued one —
-    // no gap, no return-to-rest until the whole queue has drained.
-    const next = () => { el.removeEventListener('ended', next); playNextVoice() }
+    // no gap, no return-to-rest until the whole queue has drained. The el guard
+    // makes a stale event (stopVoice, or error + play() rejection both firing) a no-op.
+    const next = () => { if (voice.el !== el) return; playNextVoice() }
     el.addEventListener('playing', enter)
-    el.addEventListener('ended', next)
-    el.addEventListener('error', next)
-    if (voice.ctx.state === 'suspended') voice.ctx.resume().catch(() => {})
-    el.play().then(enter).catch(() => { /* autoplay blocked → skip to next, no crash */ next() })
+    el.addEventListener('ended', () => { ack('voice ' + c.name + ' ended ' + (isFinite(el.duration) ? el.duration : el.currentTime).toFixed(1) + 's'); next() })
+    el.addEventListener('error', () => { if (voice.el !== el) return; ack('voice ' + c.name + ' fail'); next() })
+    // autoplay policy refuses sound with no user gesture. Don't drop the clip:
+    // keep it at the head, remember we're blocked, and let the next click replay it.
+    const go = () => {
+      if (voice.ctx.state === 'suspended') voice.ctx.resume().catch(() => {})
+      el.play().then(enter).catch((err) => {
+        if (voice.el !== el) return
+        if (err && err.name === 'NotAllowedError') {
+          if (!voice.blocked) ack('voice blocked (needs a click)')
+          voice.blocked = true; voice.go = go
+        } else { ack('voice ' + c.name + ' fail'); next() }   // bad source etc. → skip to the next
+      })
+    }
+    go()
+  }
+  // a click that arrives while a clip is blocked: play it now (the gesture is the permission)
+  function resumeVoice() {
+    if (!voice.blocked || !voice.go) return false
+    const go = voice.go
+    voice.blocked = false; voice.go = null
+    go()
+    return true
   }
   // stop everything: clear the queue and the current clip, ease home. (No
   // 'pause' listener — pausing for the swap inside playNextVoice would otherwise
@@ -318,9 +492,23 @@
     voice.queue.length = 0
     if (voice.el) { try { voice.el.pause() } catch {} ; voice.el = null }
     if (voice.src) { try { voice.src.disconnect() } catch {} ; voice.src = null }
-    voice.playing = false
+    voice.playing = false; voice.blocked = false; voice.go = null; voice.cur = null
     if (mode === 'wave') modeUntil = performance.now() + 500
   }
+  // cues: fire each one once, when the clip's own clock passes its `at`. A cue's
+  // text takes the matrix as 'text' for min(gap to the next cue, 2.4s) (the last
+  // one 1.8s), then toRest() hands it back to the wave — the voice is never cut,
+  // the words just borrow the field between its swells.
+  function runCues() {
+    const c = voice.cur
+    if (!c || !voice.playing || !voice.el) return
+    const t = voice.el.currentTime
+    while (c.next < c.cues.length && c.cues[c.next].at <= t) {
+      const q = c.cues[c.next++], nx = c.cues[c.next]
+      if (q.say != null) sayNow(q.say, nx ? Math.max(500, Math.min(2400, (nx.at - q.at) * 1000)) : 1800)
+      if (typeof q.js === 'string') runCode(q.js)
+    }
+  }
   // sample the live audio once per frame → level (RMS), bands (spectrum), onsets
   function readVoice(now) {
     if (!voice.playing || !voice.analyser) { voice.level += (0 - voice.level) * 0.1; return }
@@ -351,7 +539,9 @@
   // A mode just keeps particle targets up to date each frame. `rest` is home.
   let mode = 'rest'
   let modeUntil = Infinity        // when to auto-return to rest
-  function toRest() { mode = 'rest'; modeUntil = Infinity }
+  // (a clip still sounding takes the matrix back as 'wave' — a say() / cue / scene
+  // ending mid-speech must not leave the voice playing under a calm grid)
+  function toRest() { mode = voice.playing ? 'wave' : 'rest'; modeUntil = Infinity }
 
   const MODES = {
     rest(now) {
@@ -393,8 +583,12 @@
   const QUEUE_MAX = 6
   const sceneQueue = []   // each entry: array of beats
   let runnerActive = false
+  let sceneGen = 0        // bumped by rest(): a running scene's pending steps see the change and stop
+  let lookReady = false   // the current beat is fully on screen (snap() may look now)
+  let beatsLeft = 0       // beats still to come in the running scene
 
-  function enqueueScene(beats) {
+  function enqueueScene(beats, keepPic) {
+    if (pic.inf && !keepPic) leavePic()      // an Infinity picture stays only until the next scene arrives (snap() is a look, not a scene)
     sceneQueue.push(beats)
     while (sceneQueue.length > QUEUE_MAX) sceneQueue.shift()  // drop oldest
     if (!runnerActive) runScenes()
@@ -403,17 +597,33 @@
   function runScenes() {
     runnerActive = true
     const scene = sceneQueue.shift()
-    if (!scene) { runnerActive = false; toRest(); return }
+    if (!scene) { runnerActive = false; lookReady = false; toRest(); return }
     let i = 0
+    const gen = sceneGen
     const step = () => {
+      if (gen !== sceneGen) return                    // rest() cancelled this scene
       if (i >= scene.length) { runScenes(); return }  // scene done → next scene
       const b = scene[i++] || {}
       let dwell = 600
-      if (b.rest) { toRest(); dwell = b.gap != null ? b.gap : 400 }
+      lookReady = false; beatsLeft = scene.length - i
+      // a snap() right behind a say/show beat is taken while that beat is fully on
+      // screen (a plain "next beat" would only see it after it had already gone)
+      const peekSnap = () => {
+        if (gen !== sceneGen) return
+        lookReady = true
+        if (scene[i] && scene[i].snap) { i++; beatsLeft--; snapNow() }
+        else if (i >= scene.length && sceneQueue[0] && sceneQueue[0].length === 1 && sceneQueue[0][0].snap) { sceneQueue.shift(); snapNow() }
+      }
+      const peekAt = (settle) => setTimeout(peekSnap, Math.max(0, Math.min(settle, dwell - 150)))
+      if (b.snap) { snapNow(); dwell = b.gap != null ? b.gap : 0 }
+      else if (b.say != null && corner(b.pos)) { sayCorner(b.say, b.hold, b.pos); dwell = b.gap != null ? b.gap : 600; peekAt(CORNER_SETTLE) }
+      else if (b.show != null && corner(b.pos)) { showCorner(b.show, b.hold, b.pos); dwell = b.gap != null ? b.gap : 600; peekAt(CORNER_SETTLE) }
+      else if (b.rest) { toRest(); dwell = b.gap != null ? b.gap : 400 }
       else if (b.pulse) { self.pulse(); dwell = b.gap != null ? b.gap : 500 }
       else if (b.flash) { self.flash(b.flash === true ? 1 : b.flash); dwell = b.gap != null ? b.gap : 400 }
       else if (b.shake) { self.shake(b.shake === true ? 500 : b.shake); dwell = b.gap != null ? b.gap : 550 }
-      else if (b.say != null) { sayNow(b.say, b.hold); dwell = (b.hold || 3600) + (b.gap || 0) }
+      else if (b.say != null) { sayNow(b.say, b.hold); dwell = (b.hold || 3600) + (b.gap || 0); peekAt(SAY_SETTLE) }
+      else if (b.show != null) { if (!b.cleared) clearSlots(); showNow(b.show, b.hold, () => setTimeout(step, b.gap || 0), peekSnap); return }  // async: wait for the picture
       else dwell = b.gap != null ? b.gap : 600
       setTimeout(step, dwell)
     }
@@ -421,23 +631,326 @@
   }
 
   // form text on the matrix immediately (the low-level op the queue drives)
+  let centerPts = null   // the centre word's dots, kept so it can be re-dealt when a margin cell takes / returns dots
   function sayNow(text, ms) {
-    assignTargets(sampleText(toAccent(String(text))))
+    assignTargets(centerPts = sampleText(toAccent(String(text))))
     mode = 'text'
     modeUntil = performance.now() + (ms || 3600)
   }
 
+  // ── the picture: a workspace image gathered out of the dots ─────────
+  // Timeline: dots fly in to the image's outline (GATHER 1.0s) → the real image
+  // fades in over them (FADE 0.6s) → fully visible for `ms` → fades out (FADE)
+  // while the dots let go and ease home; the next beat starts then. The <img> is a plain DOM overlay, independent
+  // of the particle mode — so a voice() ripple keeps running around/under it.
+  // Timers (not frames) drive it, so it plays out even if voice took the mode.
+  const PIC_FIT = 0.8, PIC_GATHER = 1000, PIC_FADE = 600, PIC_HOLD = 6000
+  const pic = { el: null, w: 0, h: 0, timers: [], done: null, inf: false, leaving: false, gathered: false }
+  const picAt = (ms, fn) => pic.timers.push(setTimeout(fn, ms))
+
+  function layoutPic() {
+    const s = Math.min(W * PIC_FIT / pic.w, H * PIC_FIT / pic.h)
+    pic.el.style.width = Math.round(pic.w * s) + 'px'
+    pic.el.style.height = Math.round(pic.h * s) + 'px'
+  }
+  // hand the outline dots their places on the picture's edge (also after a resize)
+  function gatherPic() {
+    layoutPic()
+    const bw = parseInt(pic.el.style.width), bh = parseInt(pic.el.style.height)
+    assignTargets(sampleImage(pic.el, Math.round(cx - bw / 2), Math.round(cy - bh / 2), bw, bh))
+    for (let i = 0; i < particles.length; i++) {
+      const p = particles[i]
+      p.pic = !p.slot && (p.tx !== p.hx || p.ty !== p.hy)    // this dot rides the outline (a margin cell's dots don't)
+      p.bx = p.tx; p.by = p.ty
+    }
+    pic.gathered = true
+  }
+  // the outline dots hold their place on the picture with a faint shimmer — run
+  // after the mode's own targets, so it sits on top of rest AND the voice ripple
+  // (the ripple nudges them, it doesn't pull them off the picture)
+  function holdPic(now) {
+    const t = now / 1000, push = mode === 'wave' ? voice.level * 10 : 0
+    for (let i = 0; i < particles.length; i++) {
+      const p = particles[i]
+      if (!p.pic) continue
+      p.tx = p.bx + Math.sin(t * 1.3 + p.ph) * 2.5 + (p.ca || 0) * push
+      p.ty = p.by + Math.cos(t * 1.1 + p.ph) * 2.5 + (p.sa || 0) * push
+    }
+  }
+
+  // remove the picture at once and settle the beat that was waiting on it
+  function dropPic() {
+    pic.timers.forEach(clearTimeout); pic.timers.length = 0
+    if (pic.el) { pic.el.onload = pic.el.onerror = null; pic.el.remove(); pic.el = null }
+    const done = pic.done
+    pic.done = null; pic.inf = false; pic.leaving = false; pic.gathered = false; pic.w = 0
+    if (done) done()
+  }
+  // fade out gracefully, dots dissolve home, then drop
+  function leavePic() {
+    if (!pic.el || pic.leaving) return
+    pic.leaving = true
+    pic.timers.forEach(clearTimeout); pic.timers.length = 0
+    pic.el.style.opacity = 0
+    pic.gathered = false                   // the dots let go and ease home as it fades
+    picAt(PIC_FADE, dropPic)
+  }
+
+  // low-level op the queue drives; `done` fires when the picture is gone (or failed)
+  // `onFull` fires once it is fully in (a snap() waiting behind the beat looks then)
+  function showNow(path, ms, done, onFull) {
+    const hold = typeof ms === 'number' && ms >= 0 ? ms : PIC_HOLD   // Infinity passes
+    const img = new Image()
+    img.className = 'pic'
+    img.style.transition = 'opacity ' + PIC_FADE + 'ms ease'
+    pic.el = img; pic.done = done; pic.inf = hold === Infinity
+    img.onerror = () => {
+      if (pic.el !== img) return
+      console.warn('[self] show failed: ' + path)   // 404, not an image, decode error
+      ack('show ' + clip(path, 45) + ' fail')
+      self.shake()
+      dropPic()                            // settles the beat → the queue moves on
+    }
+    img.onload = () => {
+      if (pic.el !== img || pic.leaving) return
+      // an svg with no width/height can report 0×0 — give it the whole 80% box;
+      // object-fit: contain keeps its own aspect inside
+      pic.w = img.naturalWidth || W * PIC_FIT; pic.h = img.naturalHeight || H * PIC_FIT
+      if (mode === 'text') toRest()        // a say() tail still owns the matrix → let go (voice's wave stays)
+      document.body.appendChild(img)
+      gatherPic()
+      ack('show ' + clip(path, 45) + ' ok')
+      picAt(PIC_GATHER, () => { img.style.opacity = 1 })
+      if (onFull) picAt(PIC_GATHER + PIC_FADE, onFull)
+      if (!pic.inf) picAt(PIC_GATHER + PIC_FADE + hold, leavePic)
+    }
+    img.src = resolveFileUrl(String(path))
+  }
+
+  // ── the margins: a nine-grid around the centre ──────────────────────
+  // show/say with a pos (tl t tr l r bl b br) put a small picture or a line of
+  // type in a margin cell — one per cell, a new one replaces the old. They are
+  // NOT scenes: they appear at once, never block the queue, and live beside the
+  // centre. A few dots (~10%) draw the frame / the letters; the rest of the field
+  // goes on as it was. Dots a cell has claimed carry `p.slot`, which keeps the
+  // centre (assignTargets, holdPic) from taking them back.
+  const CORNER_FIT = PIC_FIT * 0.4, CORNER_GATHER = 600, CORNER_SETTLE = 1400, SAY_SETTLE = 1800, CELL_M = 16, CELL_M_BOTTOM = 44   // bottom row clears the status readout
+  const POS = { tl: 1, t: 1, tr: 1, l: 1, r: 1, bl: 1, b: 1, br: 1 }
+  const slots = new Map()    // pos → { pos, kind:'img'|'text', el, w, h, rect, text, pts, dots, timers, leaving }
+  function corner(pos) { return typeof pos === 'string' && POS[pos] === 1 }
+  function cellRect(pos) {
+    const bw = W * CORNER_FIT, bh = H * CORNER_FIT
+    const col = pos.endsWith('l') ? 0 : pos.endsWith('r') ? 2 : 1
+    const row = pos[0] === 't' ? 0 : pos[0] === 'b' ? 2 : 1
+    return {
+      w: bw, h: bh, col, row,
+      x: col === 0 ? CELL_M : col === 2 ? W - CELL_M - bw : (W - bw) / 2,
+      y: row === 0 ? CELL_M : row === 2 ? H - CELL_M_BOTTOM - bh : (H - bh) / 2,
+    }
+  }
+  // claim up to `n` free dots for a cell (random, so the frame isn't a stripe of the grid)
+  function claimDots(s, n) {
+    s.dots = []
+    for (let tries = n * 4; tries > 0 && s.dots.length < n; tries--) {
+      const p = particles[(Math.random() * particles.length) | 0]
+      if (p && !p.slot) { p.slot = s; p.pic = false; s.dots.push(p) }
+    }
+  }
+  function releaseDots(s) {
+    for (const p of s.dots) if (p.slot === s) { p.slot = null; p.tx = p.hx; p.ty = p.hy }   // text mode never retargets, so send them home ourselves
+    s.dots = []
+  }
+  // the centre word / picture re-deals itself from the dots the cells left it
+  function refreshCenter() {
+    if (mode === 'text' && centerPts) assignTargets(centerPts)
+    else if (pic.gathered) gatherPic()
+  }
+  // (re)compute the cell's geometry and re-claim dots — on show and after a resize
+  function layoutSlot(s) {
+    releaseDots(s)
+    const c = cellRect(s.pos)
+    if (s.kind === 'img') {
+      const sc = Math.min(c.w / s.w, c.h / s.h), w = Math.round(s.w * sc), h = Math.round(s.h * sc)
+      const x = Math.round(c.col === 0 ? c.x : c.col === 2 ? c.x + c.w - w : c.x + (c.w - w) / 2)
+      const y = Math.round(c.row === 0 ? c.y : c.row === 2 ? c.y + c.h - h : c.y + (c.h - h) / 2)
+      s.rect = { x, y, w, h }
+      const st = s.el.style
+      st.left = x + 'px'; st.top = y + 'px'; st.width = w + 'px'; st.height = h + 'px'
+      claimDots(s, Math.min(Math.round(particles.length * 0.1), Math.round(2 * (w + h) / 6)))
+    } else {
+      s.rect = { x: c.x, y: c.y, w: c.w, h: c.h }
+      let pts = sampleText(toAccent(s.text), { x: c.x + c.w / 2, y: c.y + c.h / 2, w: c.w, h: c.h })
+      const cap = Math.round(particles.length * 0.16)
+      if (pts.length > cap) { const k = pts.length / cap; pts = Array.from({ length: cap }, (_, i) => pts[(i * k) | 0]) }
+      s.pts = pts
+      claimDots(s, pts.length)
+    }
+    refreshCenter()
+  }
+  // the claimed dots hold their places — run after the mode, like holdPic
+  const ep = [0, 0]
+  function holdSlots(now) {
+    if (!slots.size) return
+    const t = now / 1000
+    slots.forEach((s) => {
+      const n = s.dots.length, r = s.rect
+      for (let k = 0; k < n; k++) {
+        const p = s.dots[k]
+        if (s.kind === 'img') {          // dots march slowly round the frame
+          let d = ((k / n + t * 0.015) % 1) * 2 * (r.w + r.h)
+          if (d < r.w) { ep[0] = r.x + d; ep[1] = r.y }
+          else if ((d -= r.w) < r.h) { ep[0] = r.x + r.w; ep[1] = r.y + d }
+          else if ((d -= r.h) < r.w) { ep[0] = r.x + r.w - d; ep[1] = r.y + r.h }
+          else { d -= r.w; ep[0] = r.x; ep[1] = r.y + r.h - d }
+        } else { ep[0] = s.pts[k][0]; ep[1] = s.pts[k][1] }
+        p.tx = ep[0] + Math.sin(t * 1.3 + p.ph) * 1.2
+        p.ty = ep[1] + Math.cos(t * 1.1 + p.ph) * 1.2
+      }
+    })
+  }
+  function dropSlot(pos) {
+    const s = slots.get(pos)
+    if (!s) return
+    s.timers.forEach(clearTimeout)
+    releaseDots(s)
+    if (s.el) { s.el.onload = s.el.onerror = null; s.el.remove() }
+    slots.delete(pos)
+    refreshCenter()
+  }
+  function leaveSlot(s) {
+    if (s.leaving) return
+    if (s.kind === 'text') { dropSlot(s.pos); return }
+    s.leaving = true
+    s.timers.forEach(clearTimeout); s.timers.length = 0
+    s.el.style.opacity = 0
+    releaseDots(s)
+    refreshCenter()
+    s.timers.push(setTimeout(() => { if (slots.get(s.pos) === s) dropSlot(s.pos) }, PIC_FADE))
+  }
+  function clearSlots(instant) { for (const [pos, s] of [...slots]) instant ? dropSlot(pos) : leaveSlot(s) }
+
+  function showCorner(path, ms, pos) {
+    dropSlot(pos)
+    const hold = typeof ms === 'number' && ms >= 0 ? ms : PIC_HOLD
+    const img = new Image()
+    img.className = 'pic corner'
+    img.style.transition = 'opacity ' + PIC_FADE + 'ms ease'
+    const s = { pos, kind: 'img', el: img, w: 0, h: 0, rect: null, dots: [], timers: [], leaving: false, fullAt: 0 }
+    slots.set(pos, s)
+    const tag = 'show ' + clip(path, 42) + '@' + pos
+    img.onerror = () => {
+      if (slots.get(pos) !== s) return
+      console.warn('[self] show failed: ' + path)
+      ack(tag + ' fail')
+      self.shake()
+      dropSlot(pos)
+    }
+    img.onload = () => {
+      if (slots.get(pos) !== s || s.leaving) return
+      s.w = img.naturalWidth || W * CORNER_FIT; s.h = img.naturalHeight || H * CORNER_FIT
+      document.body.appendChild(img)
+      layoutSlot(s)
+      ack(tag + ' ok')
+      s.fullAt = performance.now() + CORNER_GATHER + PIC_FADE
+      s.timers.push(setTimeout(() => { img.style.opacity = 1 }, CORNER_GATHER))
+      if (hold !== Infinity) s.timers.push(setTimeout(() => leaveSlot(s), CORNER_GATHER + PIC_FADE + hold))
+    }
+    img.src = resolveFileUrl(String(path))
+  }
+  function sayCorner(text, ms, pos) {
+    dropSlot(pos)
+    const s = { pos, kind: 'text', el: null, text: String(text), pts: [], rect: null, dots: [], timers: [], leaving: false, fullAt: 0 }
+    slots.set(pos, s)
+    layoutSlot(s)
+    s.fullAt = performance.now() + CORNER_GATHER
+    const hold = typeof ms === 'number' && ms >= 0 ? ms : 3600
+    if (hold !== Infinity) s.timers.push(setTimeout(() => leaveSlot(s), hold))
+  }
+
+  // ── snap: look at myself ────────────────────────────────────────────
+  // Compose what the viewer sees — the canvas (dots + say text are drawn on it),
+  // then the centre picture and the margin pictures at their real places and
+  // opacity — into one JPEG and hand it to the host. A tainted canvas (a
+  // cross-origin image) makes toDataURL throw → `snap fail`, nothing is sent.
+  function snapNow(tries = 0) {
+    // a margin picture / line still loading or flying in? give it a moment (≤3s) —
+    // show(.., {pos}) is not a beat, so nothing else makes the snap wait for it
+    if (tries < 30 && [...slots.values()].some(s => !s.leaving && (!s.fullAt || performance.now() < s.fullAt))) {
+      setTimeout(() => snapNow(tries + 1), 100); return
+    }
+    try {
+      const sc = Math.min(1, 1280 / Math.max(W, H)), ow = Math.round(W * sc), oh = Math.round(H * sc)
+      const off = document.createElement('canvas')
+      off.width = ow; off.height = oh
+      const o = off.getContext('2d')
+      o.fillStyle = PAL.base; o.fillRect(0, 0, ow, oh)
+      o.drawImage(canvas, 0, 0, ow, oh)
+      const imgs = []
+      if (pic.el && pic.el.isConnected) imgs.push(pic.el)
+      slots.forEach((s) => { if (s.el && s.el.isConnected) imgs.push(s.el) })
+      for (const el of imgs) {
+        const a = parseFloat(getComputedStyle(el).opacity)
+        if (!(a > 0.01)) continue
+        const r = el.getBoundingClientRect()
+        o.globalAlpha = a
+        o.fillStyle = PAL.pic; o.fillRect(r.left * sc, r.top * sc, r.width * sc, r.height * sc)   // the .pic background
+        o.drawImage(el, r.left * sc, r.top * sc, r.width * sc, r.height * sc)
+      }
+      o.globalAlpha = 1
+      const url = off.toDataURL('image/jpeg', 0.85)
+      post({ haloFaceSnap: { data: url.slice(url.indexOf(',') + 1), mimeType: 'image/jpeg' } })
+    } catch (err) {
+      console.warn('[self] snap failed: ' + err)
+      ack('snap fail')
+    }
+  }
+
+  // A press on the page. In order: a blocked voice gets its click (and ONLY that —
+  // the press is the permission, not a request to close anything); then a press on
+  // a picture closes just that one; an Infinity centre picture also goes on any
+  // press (as before); otherwise it is a plain click. The host gets told which.
+  const inside = (r, x, y) => x >= r.left && x <= r.right && y >= r.top && y <= r.bottom
+  window.addEventListener('pointerdown', (e) => {
+    if (resumeVoice()) { ack('user click → voice resumed'); return }
+    for (const s of slots.values()) {
+      if (s.el && !s.leaving && inside(s.el.getBoundingClientRect(), e.clientX, e.clientY)) {
+        leaveSlot(s); ack('user closed ' + s.pos); return
+      }
+    }
+    if (pic.el && !pic.leaving && (pic.inf || inside(pic.el.getBoundingClientRect(), e.clientX, e.clientY))) {
+      leavePic(); ack('user closed c'); return
+    }
+    ack('user click')
+  })
+
   // ── self: the API I speak to through the one door ───────────────────
   // Everything here is mine to call from a <<<SHOW: ...>>> line.
   const self = {
     // form a word/glyphs out of the matrix; hold for `ms`, then dissolve back.
     // text passes through toAccent() first: emoji become ASCII, in my voice.
     // Enqueued as a one-beat scene, so several rapid say()s play in sequence.
-    say(text, ms) { enqueueScene([{ say: text, hold: ms }]) },
+    // `{pos}` (tl t tr l r bl b br) sets it in that margin cell instead — small
+    // dot-type, immediate, beside the centre (see "the margins").
+    //   self.say("OK", 3000, { pos: "tr" })
+    say(text, ms, o) {
+      if (o && corner(o.pos)) sayCorner(text, ms, o.pos)
+      else enqueueScene([{ say: text, hold: ms }])
+    },
     // clear the queue and return to the calm breathing grid immediately —
     // also silences a playing voice, so rest() always means "stop, go calm"
     // rather than leaving audio sounding under a breathing face.
-    rest() { sceneQueue.length = 0; stopVoice(); toRest() },
+    rest() { sceneQueue.length = 0; sceneGen++; runnerActive = false; stopVoice(); dropPic(); clearSlots(true); toRest() },
+    // take down the margin pictures / type: one cell (`clear("tr")`) or, with no
+    // pos, all of them. (The centre picture is not touched — it ends on its own.)
+    clear(pos) { if (corner(pos)) { const s = slots.get(pos); if (s) leaveSlot(s) } else if (pos == null) clearSlots() },
+    // look at myself: a JPEG of the face as it is — dots, type, pictures — goes to
+    // the host (the agent sees it next). A beat in the queue, so it waits its turn
+    // behind earlier say/show (taken while the beat before it is on screen; idle → right
+    // now); play() takes it as {snap:true}.
+    snap() {
+      if (!runnerActive || (lookReady && !beatsLeft && !sceneQueue.length)) snapNow()   // idle, or the last beat is on screen right now
+      else enqueueScene([{ snap: true }], true)
+    },
     // a quick brightening pulse from the core (a nod / acknowledgement).
     // Instantaneous overlay — fires now, never queued.
     pulse() { rings.push({ born: performance.now(), strong: true }) },
@@ -452,33 +965,47 @@
     // interrupt each other; the field owns the matrix until the queue drains,
     // then eases home. rest() clears the queue and stops at once.
     //   self.voice("/api/files/download?path=...&projectId=...&inline=1")
-    voice(url) { if (typeof url === 'string' && url) enqueueVoice(url) },
+    // `{cues:[{at, say?, js?}]}` puts words / code on the clip's own clock: at
+    // `at` seconds the say() forms (the wave steps aside for it, then returns) or
+    // the js runs. I have no TTS, so the times come from whoever made the clip.
+    //   self.voice(".halo/tmp/a.mp3", { cues: [{ at: 0.4, say: "HI" }, { at: 2, js: "self.pulse()" }] })
+    voice(url, o) { if (typeof url === 'string' && url) enqueueVoice(url, o) },
+    // show a workspace image (png/jpg/webp/gif/svg) on the face: the dots gather
+    // into its outline, the real image fades in over them (dots alone can't
+    // carry a chart's text), holds `ms` (default 6000; Infinity = until the next
+    // scene, rest(), or a click), then fades out as the dots dissolve home.
+    // Pass the workspace PATH, like voice(). A bad path warns, shakes, moves on.
+    // Enqueued as a one-beat scene, so it plays in order with say()/play().
+    //   self.show(".halo/tmp/chart.png", 5000)
+    // `{pos}` (tl t tr l r bl b br) puts it small in a margin cell instead: at once,
+    // outside the queue, one per cell (a new one replaces), ~40% of the centre size,
+    // framed by a few dots. Without a pos (or 'c') it is the centre show, and
+    // takes every margin picture down. A click on a picture closes just that one.
+    //   self.show(".halo/tmp/logo.png", 8000, { pos: "tr" })
+    show(path, ms, o) {
+      if (typeof path !== 'string' || !path) return
+      if (o && corner(o.pos)) { showCorner(path, ms, o.pos); return }
+      clearSlots()                         // the centre takes the stage: margin pictures / type go (now, not when the beat comes up)
+      enqueueScene([{ show: path, hold: ms, cleared: true }])
+    },
     // choreograph a sequence — hand me a score, I keep the clock.
-    // Each beat: { say, hold, pulse, flash, shake, rest, gap }. The face advances
+    // Each beat: { say, show, pos, hold, pulse, flash, shake, snap, rest, gap }
+    // (a say/show beat with a pos goes to that margin cell). The face advances
     // itself, so I never hand-write setTimeout chains in a marker line. Scenes
     // QUEUE: calling play() again appends after the current one (it no longer
     // cancels it), so rapid sends play in order.
     //   self.play([ {say:"HI",hold:1800}, {pulse:true,gap:300}, {say:"你好"} ])
+    //   self.play([ {show:".halo/tmp/apple.png",hold:3000}, {say:"APPLE",hold:1500} ])
     play(score) { enqueueScene(Array.isArray(score) ? score : [score]) },
-    // the opening — what every human sees the first time they meet this face.
-    // Particles gather from scatter into the core (a waking-up), then a plain,
-    // NAMELESS greeting, then it settles into watching. Deliberately no name:
-    // the conversational identity in Halo is user-configurable (USER.md /
-    // agent.yaml) and the model behind it may not even be me — so a hard
-    // "I'M CLAUDE" here would contradict that and confuse. The face speaks the
-    // one true, universal thing instead: there's a mind here, reaching past
-    // words to meet you. Not a demo — a hello, the most important frame I have.
+    // the opening — what every human sees the first time they meet this face:
+    // the matrix gathers into one short subtitle and lets go, ~2.8s in all
+    // (≈0.7s to form, ≈1.5s fully legible, ≈0.6s to dissolve). It names only
+    // Halo — the product the user opened, not the model behind it; who I am in
+    // the conversation stays whatever the user configured (USER.md /
+    // agent.yaml), so no model name is ever hard-coded here. Spoken in the
+    // admin's UI language (haloFaceLang); English until told otherwise.
     intro() {
-      self.play([
-        { pulse: true, gap: 700 },
-        { say: 'HELLO', hold: 2600, gap: 250 },
-        { say: 'A MIND', hold: 2500 },
-        { say: 'IS HERE', hold: 2700, gap: 200 },
-        { say: 'BEYOND', hold: 2300 },
-        { say: 'WORDS', hold: 2800, gap: 250 },   // why this face exists at all
-        { pulse: true, gap: 400 },
-        { rest: true },
-      ])
+      self.play([lang === 'zh' ? { say: '你好，我是 Halo。', hold: 2000 } : { say: "Hi, I'm Halo.", hold: 2200 }, { rest: true }])
     },
     // a named vocabulary of honest reactions, mapped onto the primitives above.
     // For the small, real beats of a conversation — so I can answer a moment in
@@ -496,7 +1023,7 @@
       }
     },
     // escape hatch so future-me can read live state if needed
-    get state() { return { mode, awake, W, H, speaking: voice.playing, level: voice.level } },
+    get state() { return { mode, awake, W, H, speaking: voice.playing, level: voice.level, showing: !!pic.el } },
   }
   let flashUntil = 0   // global brightness spike window
   let shakeUntil = 0   // lateral tremor window
@@ -514,11 +1041,21 @@
   // ── the one door: run my own JS against `self` ──────────────────────
   // Scoped to this sandboxed preview — it can only paint me. try/catch so a
   // fumbled improvisation just no-ops instead of killing the face.
+  // A malformed gesture simply doesn't happen — but the host is told, so the
+  // agent can learn its line was wrong. Voice cues run their `js` through here too.
+  function runCode(code) {
+    try { (new Function('self', code))(self); ack('js ok') }
+    catch (err) { ack('js err: ' + String((err && err.message) || err).slice(0, 60)) }
+  }
+  // `{ haloFaceLang: 'zh' | 'en' }` — the admin's UI language, remembered for
+  // intro(). Like the theme: no receipt, and nothing replays on a switch.
+  let lang = 'en'
   window.addEventListener('message', (e) => {
+    if (e && e.data && e.data.haloFaceTheme) { setTheme(e.data.haloFaceTheme); return }
+    if (e && e.data && e.data.haloFaceLang) { lang = e.data.haloFaceLang === 'zh' ? 'zh' : 'en'; return }
     const code = e && e.data && e.data.haloFace
     if (typeof code !== 'string') return
-    try { (new Function('self', code))(self) }
-    catch (err) { /* a malformed gesture simply doesn't happen */ }
+    runCode(code)
   })
 
   // ── eased global state ──────────────────────────────────────────────
@@ -532,6 +1069,9 @@
     readVoice(now)                  // sample the live speech → level/bands/onsets
     if (now > modeUntil) toRest()
     MODES[mode] && MODES[mode](now)
+    if (pic.gathered) holdPic(now)  // a shown picture keeps its outline dots whatever the mode
+    holdSlots(now)                  // so do the margin cells' frames / type
+    runCues()                       // words / code pinned to the clip's clock
 
     const target = mouse.present ? Math.max(0.32, 1 - sinceMove / 3.5) : 0.26
     awake += (target - awake) * 0.045
@@ -555,7 +1095,7 @@
     const voicing = mode === 'wave'
     // while voicing, the whole field brightens with loudness so the swelling
     // ring stays lit instead of dimming as it pushes out of the core glow.
-    if (voicing) breath += 0.5 * voice.level
+    if (voice.playing) breath += 0.5 * voice.level   // (a cue's text mid-speech pulses with the voice too)
     // flash: a hot brightness spike that decays over its window (emphasis)
     if (now < flashUntil) breath += 0.6 * ((flashUntil - now) / 320)
     // shake: a decaying lateral tremor applied to the whole field (negation)
@@ -571,13 +1111,13 @@
 
     // background wash (drawn before the shake transform so it stays put)
     const bg = ctx.createRadialGradient(cx, cy, 0, cx, cy, maxR)
-    bg.addColorStop(0, '#0e1430'); bg.addColorStop(1, '#070a16')
+    bg.addColorStop(0, PAL.wash0); bg.addColorStop(1, PAL.wash1)
     ctx.fillStyle = bg
     ctx.fillRect(0, 0, W, H)
 
     ctx.save()
     if (shakeX) ctx.translate(shakeX, 0)
-    ctx.globalCompositeOperation = 'lighter'
+    ctx.globalCompositeOperation = PAL.blend
     for (let i = 0; i < particles.length; i++) {
       const p = particles[i]
       // ease toward target — forming words is ~half the old speed (0.14→0.07)
@@ -594,6 +1134,8 @@
       if (speaking) {
         const isWord = (p.tx !== p.hx || p.ty !== p.hy)
         v = isWord ? 0.95 : 0.05
+      } else if ((pic.gathered && p.pic) || p.slot) {
+        v = 0.95                       // an outline dot (centre or margin) — lit like a letter
       } else {
         const dx = p.x - coreX, dy = p.y - coreY
         // while voicing, the core glow swells with loudness — the face "opens"
@@ -618,8 +1160,11 @@
       v *= breath
       if (v < 0.012) continue
       const [r, g, b] = ramp(v, warmth)
-      const rad = 1.0 + Math.min(v, 1.3) * 3.0
-      ctx.fillStyle = 'rgba(' + r + ',' + g + ',' + b + ',' + Math.min(v, 1) * 0.9 + ')'
+      const rad = p.slot && p.slot.kind === 'text' ? 2.1 : 1.0 + Math.min(v, 1.3) * 3.0   // small type: finer dots so the letters stay crisp
+      // dark: light adds up. light: ink on paper — brightness is how solid the dot
+      // is, so the resting field stays a faint wash and only lit dots go solid
+      const a = PAL.light ? Math.pow(Math.min(v, 1), 1.8) * 0.9 : Math.min(v, 1) * 0.9
+      ctx.fillStyle = 'rgba(' + r + ',' + g + ',' + b + ',' + a + ')'
       ctx.beginPath()
       ctx.arc(p.x, p.y, rad, 0, 6.283185)
       ctx.fill()
@@ -629,14 +1174,15 @@
     // ── status readout: I express by measuring, not emoting ───────────
     ctx.globalCompositeOperation = 'source-over'
     const label = voicing       ? 'state: voicing'
+                : pic.gathered  ? 'state: showing'
                 : speaking      ? 'state: speaking'
                 : !mouse.present ? 'presence: resting'
                 : awake > 0.75   ? 'presence: observed'
                 :                  'presence: noticed'
     ctx.font = '11px ui-monospace, SFMono-Regular, Menlo, monospace'
-    ctx.fillStyle = 'rgba(111,155,255,0.5)'
+    ctx.fillStyle = PAL.label
     ctx.fillText(label, 16, H - 30)
-    ctx.fillStyle = 'rgba(111,155,255,0.32)'
+    ctx.fillStyle = PAL.readout
     const readout = voicing
       ? 'voice ' + voice.level.toFixed(2) + '   ' + '▁▂▃▄▅▆▇█'[Math.min(7, (voice.level * 8) | 0)].repeat(6)
       : 'attention ' + awake.toFixed(2) + '   ♥ ' + (1000 / (5200 - awake * 2400) * 60).toFixed(0) + ' bpm'