The Committee — two cats judge your webcam (local MiniCPM + Llama via llama.cpp)

.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:huggingface.co)",
+      "Bash(.venv/bin/python -)",
+      "Bash(echo \"exit: $?\")",
+      "WebSearch",
+      "Bash(lsof -nP -iTCP:7860 -sTCP:LISTEN)",
+      "Bash(awk '{print $2}')",
+      "Bash(xargs -I{} kill {})",
+      "Bash(echo \"port clear: $\\(lsof -nP -iTCP:7860 -sTCP:LISTEN)",
+      "Bash(curl -s -o /dev/null http://127.0.0.1:7860/api/duo)",
+      "Bash(break)",
+      "Bash(echo \"listeners: $\\(lsof -nP -iTCP:7860 -sTCP:LISTEN)",
+      "Bash(command -v node)",
+      "Bash(node --check theater/js/duo.js)",
+      "Bash(./run.sh)",
+      "Read(//private/tmp/**)",
+      "Bash(curl -s -X POST http://127.0.0.1:7860/api/frame -H 'Content-Type: application/json' -d \"{\\\\\"image\\\\\": \\\\\"$\\(cat /tmp/frame_desk.txt\\)\\\\\"}\")",
+      "Bash(curl -s http://127.0.0.1:7860/api/duo)",
+      "Bash(.venv/bin/python -c ' *)"
+    ]
+  }
+}

.dockerignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+models/
+*.gguf
+.git/
+.gradio/
+flagged/
+*.log
+arduino/
+.env
+.env.*

.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+
+# Models (downloaded GGUF weights — too big for git)
+models/
+*.gguf
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# HF / runtime
+.gradio/
+flagged/
+*.log
+
+# Secrets — NEVER commit (HF_TOKEN etc.); set these in the Space's Settings → Secrets
+.env
+.env.*

Dockerfile

@@ -0,0 +1,26 @@
+# The Committee — HF Space (docker SDK, app_port 7860).
+# CPU-friendly: moondream2 eyes + Llama-3.2-3B brain via llama.cpp, with the
+# funny stub bank as instant fallback so judges always get a lively response.
+FROM python:3.11-slim
+
+# build-essential is a safety net; the CPU wheel from the extra index normally
+# means llama-cpp-python installs without compiling.
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Run as a non-root user with a writable home (HF Spaces convention).
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    PORT=7860 \
+    VLM_AUTOFETCH=1
+
+WORKDIR /home/user/app
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+COPY --chown=user . .
+
+EXPOSE 7860
+CMD ["python", "theater_server.py"]

README.md

@@ -1,10 +1,70 @@
 ---
 title: The Committee
-emoji: 🐠
+emoji: 🐱
 colorFrom: indigo
-colorTo: purple
+colorTo: yellow
 sdk: docker
-pinned: false
+app_port: 7860
+pinned: true
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🐱 The Committee
+
+**Two house cats intercepted your webcam. They understand exactly what you're
+doing. They are judging you for it.**
+
+Point your camera at yourself and **Mochi** (a manic kitten who must attack
+everything) and **Loaf** (an enormous, withering elder who lives for food) watch
+through the window and react like cats — demanding food, plotting, holding
+grudges, pouncing at the glass. Built for the Hugging Face **Build Small**
+hackathon (Thousand Token Wood). Everything runs locally — no cloud APIs.
+
+## How it works
+
+```
+your webcam ──(only on change, never stored)──▶  ① SEE: a vision model captions the frame
+                                                  ② JUDGE: a small LLM voices Mochi & Loaf,
+                                                     situation-aware (you appeared / left /
+                                                     are eating / on your phone / in the dark)
+                                                     and grudge-aware (running gags)
+                                                  both run in-process via llama.cpp — no API
+```
+
+- **Drag any image** onto the page and the cats will judge *it* (your lunch, your dog, a meme).
+- **Dim your lights** → their pupils dilate like real cats. **A fresh verdict** → Mochi pounces.
+- **Share their verdict** copies a postable caption.
+- Open the **🧠 HIVEMIND** trace to watch the whole pipeline think.
+
+## Models (all local, via llama.cpp — no cloud)
+
+| Role | Hosted Space (CPU) | Local demo (Apple Silicon) |
+|---|---|---|
+| 👁 Eyes (scene) | moondream2 (GGUF) | **MiniCPM-V 2.6** (OpenBMB) |
+| 🧠 Brain (the cats) | Llama-3.2-3B (GGUF) | **MiniCPM3-4B** (OpenBMB) |
+
+Total well under the 32B cap. Swap models with env vars
+(`VLM_REPO` / `COMPANION_MODEL_REPO`). A deterministic stub keeps the cats funny
+even before the models warm up.
+
+Badges: **Off the Grid** (no cloud APIs) · **Llama Champion** (llama.cpp runtime)
+· **Off-Brand** (custom three.js-free canvas/SVG frontend) · **OpenBMB** (MiniCPM-V + MiniCPM3).
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+./run.sh          # all-OpenBMB: MiniCPM-V eyes + MiniCPM3-4B brain
+FAST=1 ./run.sh   # moondream2 eyes + Llama-3.2-3B brain (snappier)
+# open http://localhost:7860
+```
+
+On Apple Silicon, install the Metal build of llama-cpp-python for fast local
+inference (`--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal`).
+
+## Credits
+
+Built with **Llama** (Meta) and **MiniCPM / MiniCPM-V** (OpenBMB), run via
+[llama.cpp](https://github.com/ggml-org/llama.cpp) /
+[llama-cpp-python](https://github.com/abetlen/llama-cpp-python). Webcam frames are
+described on-device and never stored or uploaded.

app.py

@@ -0,0 +1,182 @@
+"""Desk Companion — a context-aware ASCII visual diary.
+
+HF "Build Small" submission, Thousand Token Wood track. One small local model
+(llama.cpp) senses the room — through YOUR browser's webcam/mic (light + sound
+computed client-side; only two numbers reach the app), through a real Arduino
+over serial, or through a simulated day — and writes a moody diary + ASCII art,
+pushing a short line to the (virtual or physical) OLED screen.
+"""
+
+from __future__ import annotations
+
+import math
+
+import gradio as gr
+
+import threading
+
+from companion import CompanionRunner, DeskPersona
+from companion.runner import POLL_S
+from companion.text import bar
+from companion.ui import CSS, FORCE_DARK_JS, theme
+
+WELCOME_ART = r"""
+   .--------------.
+   |  hello, you  |
+   |   ( o_o )    |
+   |  watching    |
+   |  your room   |
+   '--------------'
+"""
+
+EXPLAINER = """
+**Your desk has a tiny spirit that keeps a diary.** It feels the room —
+brightness, sound, the hour — and when something shifts (you switch the
+lights off, the night gets long) it writes a short moody diary entry, draws
+ASCII art on its little screen, and leaves you a two-line note. One small
+3B model, running locally. No cloud.
+
+**Try it:** ① press **🎥 sense my room** and allow camera+mic (nothing is
+recorded — light & sound levels are computed in your browser) → ② turn your
+lights off → ③ watch the screen react. Too shy? Press **✎ write now** and
+it writes about the room as-is.
+"""
+
+# Runs once when the user presses "sense my room": asks for camera+mic, then
+# keeps window._dc.{light,sound} updated twice a second. All processing stays
+# in the browser — frames and audio never leave the page.
+START_SENSING_JS = """
+async () => {
+  if (window._dc && window._dc.started) return;
+  window._dc = {light: -1, sound: -1, started: true};
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({video: true, audio: true});
+    const video = document.createElement('video');
+    video.srcObject = stream; video.muted = true; video.playsInline = true;
+    await video.play();
+    const canvas = document.createElement('canvas');
+    canvas.width = 32; canvas.height = 24;
+    const ctx = canvas.getContext('2d', {willReadFrequently: true});
+    const ac = new AudioContext();
+    const analyser = ac.createAnalyser();
+    analyser.fftSize = 256;
+    ac.createMediaStreamSource(stream).connect(analyser);
+    const buf = new Uint8Array(analyser.fftSize);
+    setInterval(() => {
+      try {
+        ctx.drawImage(video, 0, 0, 32, 24);
+        const d = ctx.getImageData(0, 0, 32, 24).data;
+        let lum = 0;
+        for (let i = 0; i < d.length; i += 4)
+          lum += 0.2126*d[i] + 0.7152*d[i+1] + 0.0722*d[i+2];
+        window._dc.light = Math.round(lum / (d.length/4) / 255 * 100);
+        analyser.getByteTimeDomainData(buf);
+        let rms = 0;
+        for (let i = 0; i < buf.length; i++) {
+          const v = (buf[i] - 128) / 128; rms += v*v;
+        }
+        window._dc.sound = Math.round(Math.min(100, Math.sqrt(rms/buf.length) * 400));
+      } catch (e) { /* keep last values */ }
+    }, 500);
+  } catch (e) {
+    window._dc.started = false;  // permission denied — stay on simulation
+  }
+}
+"""
+
+# Every poll tick: hand the latest browser readings to Python (-1 = not live).
+READ_SENSORS_JS = """
+(a, b) => {
+  const d = window._dc || {};
+  return [d.light ?? -1, d.sound ?? -1];
+}
+"""
+
+
+def build():
+    runner = CompanionRunner(DeskPersona(), mock_mode="day", browser=True)
+
+    def status_md():
+        r = runner.latest()
+        clk = r.clock if r else "--:--"
+        return runner.status_md() + f"  ·  **desk clock** `{clk}`"
+
+    def gauges_md():
+        r = runner.latest()
+        if r is None:
+            return "```\nwaiting for the desk to wake up...\n```"
+        temp = "" if math.isnan(r.temp) else f"temp  {r.temp:5.1f}C\n"
+        return ("```\n"
+                f"light  {r.light:3d}%  {bar(r.light)}\n"
+                f"sound  {r.sound:3d}%  {bar(r.sound)}\n"
+                f"{temp}```")
+
+    def art_text():
+        return runner.get("ascii") or WELCOME_ART
+
+    def screen_text():
+        return (runner.get("screen") or "...").replace("|", "\n")
+
+    def feed_md():
+        entries = runner.feed()
+        if not entries:
+            return "_warming up — the first entry writes itself in a few seconds..._"
+        return "\n\n---\n\n".join(
+            f"**`{e['clock']}`** · _{e['trigger']}_  \n{e['entry']}  \n"
+            f"<sub>{e['context']}</sub>" for e in entries
+        )
+
+    def on_tick(light, sound):
+        runner.ingest_browser(light, sound)
+        return status_md(), gauges_md(), art_text(), screen_text(), feed_md()
+
+    # First entry writes itself shortly after boot so the page is never blank.
+    def first_entry():
+        for _ in range(20):
+            if runner.latest() is not None:
+                runner.generate(auto=True)
+                return
+            import time
+            time.sleep(0.5)
+    threading.Thread(target=first_entry, daemon=True).start()
+
+    with gr.Blocks(title="Desk Companion") as demo:
+        gr.Markdown("# ▚ desk companion")
+        gr.Markdown(EXPLAINER, elem_id="hero")
+        status = gr.Markdown(status_md())
+        with gr.Row():
+            with gr.Column(scale=1):
+                sense_btn = gr.Button("🎥 sense my room", variant="secondary")
+                gr.Markdown("### sensors")
+                gauges = gr.Markdown(gauges_md())
+                gr.Markdown("### screen (OLED)")
+                art = gr.Markdown(elem_id="oled", value=art_text())
+                screen = gr.Markdown(elem_id="screen", value=screen_text())
+                with gr.Accordion("hardware (optional Arduino)", open=False):
+                    port = gr.Textbox(label="serial port",
+                                      placeholder="/dev/tty.usbmodem... (blank = no device)")
+                    connect = gr.Button("connect")
+                write_btn = gr.Button("✎ write now", variant="primary")
+            with gr.Column(scale=2):
+                gr.Markdown("### diary")
+                feed = gr.Markdown(feed_md())
+
+        h_light = gr.Number(value=-1, visible=False)
+        h_sound = gr.Number(value=-1, visible=False)
+
+        sense_btn.click(None, js=START_SENSING_JS)
+        gr.Timer(POLL_S).tick(
+            on_tick,
+            inputs=[h_light, h_sound],
+            outputs=[status, gauges, art, screen, feed],
+            js=READ_SENSORS_JS,
+        )
+        write_btn.click(lambda: (runner.generate(False), art_text(), screen_text(), feed_md())[1:],
+                        outputs=[art, screen, feed])
+        connect.click(runner.connect, inputs=[port], outputs=[status])
+
+    return demo
+
+
+if __name__ == "__main__":
+    build().launch(css=CSS, theme=theme(), js=FORCE_DARK_JS)

app_kitchen.py

@@ -0,0 +1,77 @@
+"""Kitchen Coach — a real-time stovetop / brew assistant.
+
+HF "Build Small" submission, Backyard AI track. Same engine as Desk Companion:
+one small local model (llama.cpp, ~3B) reads a temperature probe and, given the
+dish you're making, prints the exact next action to a physical OLED — e.g.
+'T:92C | Drop lentils now'. Runs fully in mock mode (a simulated heating pot).
+"""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from companion import CompanionRunner, KitchenPersona
+from companion.runner import POLL_S
+from companion.text import bar
+from companion.ui import CSS, FORCE_DARK_JS, theme
+
+
+def build():
+    runner = CompanionRunner(KitchenPersona(), mock_mode="heating",
+                             goal="red lentil dahl")
+
+    def temp_md():
+        r = runner.latest()
+        if r is None:
+            return "```\nwaiting for the probe...\n```"
+        pct = int(max(0, min(100, r.temp)))   # 0–100C maps cleanly to the bar
+        phase = runner.persona.phase(r.temp)
+        return ("```\n"
+                f"temp  {r.temp:5.1f}C  {bar(pct)}\n"
+                f"phase  {phase}\n```")
+
+    def screen_text():
+        return (runner.get("screen") or "...").replace("|", "\n")
+
+    def feed_md():
+        entries = runner.feed()
+        if not entries:
+            return "_No guidance yet. Set the dish and start heating — or press **coach me**._"
+        return "\n\n---\n\n".join(
+            f"**`{e['context']}`**  \n→ {e['entry']}" for e in entries
+        )
+
+    with gr.Blocks(title="Kitchen Coach") as demo:
+        gr.Markdown("# ♨ kitchen coach\nReal-time stovetop guidance from one tiny local model.")
+        status = gr.Markdown(runner.status_md())
+        with gr.Row():
+            with gr.Column(scale=1):
+                dish = gr.Textbox(label="what are you making?", value="red lentil dahl")
+                set_btn = gr.Button("set dish")
+                gr.Markdown("### probe")
+                temp = gr.Markdown(temp_md())
+                gr.Markdown("### screen (OLED)")
+                screen = gr.Markdown(elem_id="screen", value=screen_text())
+                with gr.Accordion("hardware", open=False):
+                    port = gr.Textbox(label="serial port",
+                                      placeholder="/dev/tty.usbmodem... (blank = mock)")
+                    connect = gr.Button("connect")
+                coach_btn = gr.Button("♨ coach me", variant="primary")
+            with gr.Column(scale=2):
+                gr.Markdown("### guidance")
+                feed = gr.Markdown(feed_md())
+
+        gr.Timer(POLL_S).tick(
+            lambda: (runner.status_md(), temp_md(), screen_text(), feed_md()),
+            outputs=[status, temp, screen, feed],
+        )
+        set_btn.click(runner.set_goal, inputs=[dish], outputs=[status])
+        coach_btn.click(lambda: (runner.generate(False), screen_text(), feed_md())[1:],
+                        outputs=[screen, feed])
+        connect.click(runner.connect, inputs=[port], outputs=[status])
+
+    return demo
+
+
+if __name__ == "__main__":
+    build().launch(css=CSS, theme=theme(), js=FORCE_DARK_JS)

arduino/desk_companion.ino

@@ -0,0 +1,123 @@
+/*
+ * Desk Companion — Arduino firmware
+ * --------------------------------------------------------------------------
+ * The "body": reads desk sensors, streams them to the laptop over USB serial,
+ * and renders whatever text the laptop sends back onto the OLED screen.
+ *
+ * The model NEVER runs here. This sketch is pure I/O.
+ *
+ * Wiring (Arduino Uno/Nano; adjust pins for ESP32):
+ *   - Photoresistor (LDR) divider .... A0
+ *   - Microphone/sound module (AO) ... A1   (optional; omit -> sends 0)
+ *   - DHT22 / DHT11 data ............. D2   (optional; omit -> sends nan)
+ *   - SSD1306 OLED 128x64 (I2C) ...... SDA/SCL  (A4/A5 on Uno)
+ *
+ * Protocol:
+ *   OUT (every ~1s):  LIGHT:<0-100>,SOUND:<0-100>,TEMP:<float>\n
+ *   IN  (a line):     up to 2 rows, '|' separates rows, e.g.  Go to sleep,|builder.\n
+ *
+ * Libraries (install via Library Manager):
+ *   Adafruit GFX, Adafruit SSD1306, DHT sensor library.
+ *   If you don't have a DHT sensor, comment out USE_DHT below.
+ */
+
+#include <Wire.h>
+#include <Adafruit_GFX.h>
+#include <Adafruit_SSD1306.h>
+
+#define USE_DHT   // <-- comment this line out if you have no DHT sensor
+
+#ifdef USE_DHT
+#include <DHT.h>
+#define DHTPIN 2
+#define DHTTYPE DHT22   // change to DHT11 if that's what you have
+DHT dht(DHTPIN, DHTTYPE);
+#endif
+
+#define LDR_PIN A0
+#define MIC_PIN A1
+
+#define SCREEN_W 128
+#define SCREEN_H 64
+Adafruit_SSD1306 display(SCREEN_W, SCREEN_H, &Wire, -1);
+
+unsigned long lastSend = 0;
+const unsigned long SEND_INTERVAL = 1000;  // ms
+
+void setup() {
+  Serial.begin(9600);
+#ifdef USE_DHT
+  dht.begin();
+#endif
+  // 0x3C is the common I2C address for 128x64 SSD1306 boards.
+  if (display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
+    display.clearDisplay();
+    display.setTextSize(1);
+    display.setTextColor(SSD1306_WHITE);
+    display.setCursor(0, 0);
+    display.println(F("desk companion"));
+    display.println(F("waking up..."));
+    display.display();
+  }
+}
+
+int readPercent(int pin) {
+  // 10-bit ADC (0-1023) -> 0-100%.
+  return map(analogRead(pin), 0, 1023, 0, 100);
+}
+
+void sendReadings() {
+  int light = readPercent(LDR_PIN);
+  int sound = readPercent(MIC_PIN);
+
+  float temp = NAN;
+#ifdef USE_DHT
+  temp = dht.readTemperature();   // Celsius
+#endif
+
+  Serial.print("LIGHT:");
+  Serial.print(light);
+  Serial.print(",SOUND:");
+  Serial.print(sound);
+  Serial.print(",TEMP:");
+  if (isnan(temp)) Serial.print("nan");
+  else Serial.print(temp, 1);
+  Serial.print("\n");
+}
+
+void renderMessage(String msg) {
+  display.clearDisplay();
+  display.setTextSize(2);            // big, screen-friendly text
+  display.setTextColor(SSD1306_WHITE);
+  display.setCursor(0, 8);
+  // '|' splits rows; print each on its own line.
+  int start = 0;
+  int y = 8;
+  while (start <= msg.length()) {
+    int bar = msg.indexOf('|', start);
+    String row = (bar == -1) ? msg.substring(start) : msg.substring(start, bar);
+    display.setCursor(0, y);
+    display.println(row);
+    y += 20;
+    if (bar == -1) break;
+    start = bar + 1;
+  }
+  display.display();
+}
+
+void loop() {
+  // 1) Stream sensor readings on a steady cadence.
+  if (millis() - lastSend >= SEND_INTERVAL) {
+    lastSend = millis();
+    sendReadings();
+  }
+
+  // 2) Whenever the laptop sends a line, show it on the OLED.
+  if (Serial.available() > 0) {
+    String incoming = Serial.readStringUntil('\n');
+    incoming.trim();
+    if (incoming.length() > 0) {
+      renderMessage(incoming);
+    }
+  }
+}

companion/__init__.py

@@ -0,0 +1,27 @@
+"""Desk Companion — shared engine for small-model + sensor + screen products.
+
+One small local model (llama.cpp) turns sensor readings into text/ASCII and
+pushes a short line to a physical OLED. A *persona* configures prompts, trigger
+and fallbacks per product; the sensor layer, model wrapper and runner are shared.
+"""
+
+# OLED SSD1306 128x64 at text size 1 ≈ 21 cols x 8 rows.
+# We target a little smaller so the art always fits with a border.
+# Defined before submodule imports below — model.py reads these at import time.
+OLED_COLS = 20
+OLED_ROWS = 8
+
+from .sensors import (
+    Reading, SensorSource, MockSensorSource, SerialSensorSource,
+    BrowserSensorSource, open_sensor_source,
+)
+from .model import Companion
+from .personas import Persona, DeskPersona, KitchenPersona, PERSONAS
+from .runner import CompanionRunner
+
+__all__ = [
+    "Reading", "SensorSource", "MockSensorSource", "SerialSensorSource",
+    "BrowserSensorSource", "open_sensor_source", "Companion", "Persona",
+    "DeskPersona", "KitchenPersona", "PERSONAS", "CompanionRunner",
+    "OLED_COLS", "OLED_ROWS",
+]

companion/crowd.py

@@ -0,0 +1,1190 @@
+"""GLORBVISION crowd simulation (B3) — 120 alien agents with opinion contagion.
+
+Implements BUILD SPEC v1.0 sections 3 (archetypes/seating), 4 (contagion math,
+moods, factions, events, crowd API) and the B3 slice of 5 (batched LLM voicing
+with stub-bank fallback).
+
+Pure stdlib. Deterministic (random.Random(1337)). Thread-safe via one RLock.
+ALL Companion (model.raw_chat) calls are serialized behind the provided
+llm_lock — the internal RLock is NEVER held across an LLM call.
+
+Tick is normatively 0.5 s (2 Hz); tick(dt) accumulates arbitrary dt and runs
+whole 0.5 s sub-steps.
+
+Smoke test:  .venv/bin/python -m companion.crowd
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import random
+import re
+import threading
+import time
+from collections import deque
+
+# --------------------------------------------------------------------------
+# Spec tables (section 1-3)
+# --------------------------------------------------------------------------
+
+TICK_SECONDS = 0.5
+ROWS, SEATS = 8, 15
+N_ALIENS = ROWS * SEATS  # 120
+
+TAG_ORDER = ("food", "drink", "person", "tech", "animal",
+             "motion", "dark", "absence", "novelty")
+
+MOODS = ("calm", "excited", "annoyed", "scared", "delighted", "confused")
+
+LIME, MAGENTA, AMBER = "#9dff5a", "#ff5ad6", "#ffb84d"
+
+ARCHETYPES = {
+    # key: (bias over tags, k susceptibility, resting sentiment, body hue)
+    "devout":        ({"drink": 1.0, "food": 0.4},                       0.50,  0.0, LIME),
+    "heckler":       ({"person": -0.4, "novelty": -0.2},                 0.25, -0.2, AMBER),
+    "anthropologist": ({"novelty": 0.8, "tech": 0.3},                    0.45,  0.0, MAGENTA),
+    "conspiracist":  ({"absence": -0.6, "animal": -0.3, "dark": -0.2},   0.35, -0.1, AMBER),
+    "sportscaster":  ({"motion": 0.9, "person": 0.3},                    0.60,  0.0, LIME),
+    "foodie":        ({"food": 1.0, "drink": 0.5},                       0.50,  0.0, MAGENTA),
+    "romantic":      ({"person": 0.8, "animal": 0.5},                    0.60,  0.1, MAGENTA),
+    "doom_prophet":  ({"tech": -0.6, "dark": -0.4},                      0.40, -0.1, AMBER),
+    "tourist":       ({"novelty": 0.5, "person": 0.4, "animal": 0.4, "food": 0.3,
+                       "drink": 0.3, "tech": 0.3, "motion": 0.3},        0.80,  0.3, LIME),
+    "art_critic":    ({"absence": 0.8, "dark": 0.6, "food": -0.3, "drink": -0.3,
+                       "person": -0.3, "motion": -0.3},                  0.20, -0.3, AMBER),
+    "elder":         ({"drink": 0.6, "person": 0.2, "motion": -0.4},     0.15,  0.0, LIME),
+    "merch_vendor":  ({"novelty": 0.9, "person": 0.2},                   0.55,  0.0, MAGENTA),
+}
+
+STOPWORDS = {"the", "a", "an", "is", "at", "on", "in", "of", "and", "to", "with", "its"}
+
+# Keyword -> tag (covers both raw VLM nouns and Codex names so B3 works with
+# either; B4 normally hands us Codex-substituted text).
+_TAG_KEYWORDS = {
+    "food":   ("food", "snack", "eating", "eats", "sandwich", "fruit", "pellet",
+               "pellets", "meal", "chew"),
+    "drink":  ("mug", "cup", "coffee", "tea", "chalice", "bottle", "water",
+               "ocean", "drink", "drinks", "drinking", "sip", "sips", "steam"),
+    "person": ("person", "man", "woman", "face", "human", "protagonist",
+               "people", "he", "she", "someone"),
+    "tech":   ("phone", "smartphone", "television", "keyboard", "typing",
+               "types", "laptop", "altar", "clatter", "glasses", "armor",
+               "headphones", "muzzles", "screen", "computer"),
+    "animal": ("cat", "overlord", "dog", "bark", "pet", "kitten", "puppy"),
+    "dark":   ("dim", "dark", "shadow", "shadows", "darkness", "unlit"),
+}
+_MOTION_STEMS = ("reach", "stand", "wav", "mov", "gestur", "stretch", "lean",
+                 "walk", "turn", "lift", "rais")
+_ABSENCE_WORDS = ("empty", "absent", "absence", "nobody", "vacant", "gone")
+
+EVENT_DURATIONS = {  # in ticks (0.5 s each)
+    "new_scene": 4, "noticed": 8, "chant": 12, "gasp": 8,
+    "ovation": 12, "wave": 10, "boo": 8, "intermission": 10 ** 9,
+}
+EVENT_COOLDOWN_TICKS = 24  # 12 s; new_scene + noticed (+ post-intermission wave) exempt
+
+NOTICED_BUBBLE = "IT SEES US. ACT NATURAL."
+
+VOICE_SYSTEM_PROMPT = (
+    "You write reaction subtitles for an alien audience watching a human's "
+    "webcam as TV. One line per numbered alien. Each line under 8 words, "
+    "comedic, no quotes, no emoji, stay in each alien's voice. Use ONLY these "
+    "Earth names: mug=Sacred Steam Chalice, phone=Smaller Television, "
+    "keyboard=Clatter Altar, glasses=eye armor, headphones=ear muzzles, "
+    "water bottle=personal ocean, cat=Liquid Overlord, dog=Bark Unit, "
+    "food=fuel pellets, chair=Throne of Sitting, human=the Protagonist."
+)
+
+# "N ARCHETYPE: text" but models also emit "N. ARCHETYPE: text" / "N) text" —
+# capture the number leniently; the archetype prefix is stripped separately.
+_VOICE_LINE_RE = re.compile(r"^\s*(\d+)\s*[:.)\-]?\s*(.+)$")
+_VOICE_PREFIX_RE = re.compile(r"^[A-Za-z _-]{2,24}(?:\s*\([^)]{0,40}\))?:\s*")
+
+STUB_LINES = {
+    "devout": [
+        "THE CHALICE RISES. WE ARE BLESSED.",
+        "Another cycle in the Protagonist's light.",
+        "The steam carries our prayers.",
+        "Kneel. The rite begins.",
+        "Blessed be the Clatter Altar.",
+        "I have seen the foam. It is good.",
+    ],
+    "heckler": [
+        "Booo. My larva emotes better.",
+        "Rerun. Seen it. Next channel.",
+        "The Protagonist forgot its lines again.",
+        "Refund my attention span.",
+        "Even the Throne looks bored.",
+        "This meat sack peaked in cycle 12.",
+    ],
+    "anthropologist": [
+        "Note: the eye armor stores its dreams.",
+        "Fascinating grooming display. Possibly mating.",
+        "The shrug: ritual of plausible deniability.",
+        "Field note: Protagonist molts hourly.",
+        "The Chalice is clearly ceremonial.",
+        "Documenting this for the archive.",
+    ],
+    "conspiracist": [
+        "Same Chalice as cycle 12. WAKE UP.",
+        "What is BEHIND the Smaller Television?",
+        "The feed loops. I have proof.",
+        "They WANT us to watch this.",
+        "The Liquid Overlord reports to someone.",
+        "Notice the cables. NOTICE THEM.",
+    ],
+    "sportscaster": [
+        "HE REACHES— HE STRETCHES— UNBELIEVABLE!",
+        "What a play by the Protagonist!",
+        "The Chalice lift! Textbook form!",
+        "Replay that blink! REPLAY IT!",
+        "Folks, this is peak Earth Feed.",
+        "AND THE CROWD GOES WILD!",
+    ],
+    "foodie": [
+        "Fuel pellet, dry-aged in pocket. Bold.",
+        "Notes of lint and despair. Daring.",
+        "The Chalice pairs poorly with typing.",
+        "Undersalted. I can tell from here.",
+        "A brave plating choice: no plate.",
+        "Two stars. Ambitious crumbs.",
+    ],
+    "romantic": [
+        "The way it holds the Chalice... sobbing.",
+        "It blinked at us. I felt that.",
+        "Protagonist and Throne: meant to be.",
+        "Such tender clatter. True love.",
+        "I ship it with the lamp.",
+        "My hearts. All of them. Aching.",
+    ],
+    "doom_prophet": [
+        "The Clatter Altar summons something.",
+        "It always begins with the Chalice.",
+        "The dark comes. It always comes.",
+        "Mark this cycle. Remember the steam.",
+        "The Smaller Television watches back.",
+        "Doom. Comfortable, scheduled doom.",
+    ],
+    "tourist": [
+        "First time at Earth Feed!! Amazing!!",
+        "Is that THE Throne of Sitting??",
+        "Telling my whole pod about this.",
+        "Can it see my souvenir hat?",
+        "Best vacation cycle EVER.",
+        "Wow!! It moved!! WOW!!",
+    ],
+    "art_critic": [
+        "Derivative. The Chalice arc again.",
+        "Finally. Nothing. Cinema.",
+        "The lighting does all the work.",
+        "Season one was braver.",
+        "An empty frame would say more.",
+        "One star. For the lamp.",
+    ],
+    "elder": [
+        "It has not hydrated in 40 cycles.",
+        "Somebody beep its mother.",
+        "In my day the feed was grainier.",
+        "Sit straight, Protagonist. The spine.",
+        "We have seen ten thousand mugs.",
+        "Patience. The Chalice will rise.",
+    ],
+    "merch_vendor": [
+        "CHALICE FOAM HATS! Get your hats!",
+        "Protagonist plush, limited, two zorbs!",
+        "Clatter Altar keychains, going fast!",
+        "Fresh fuel pellets! Probably edible!",
+        "Poke-proof ponchos, half off!",
+        "NEW SCENE MERCH! HOT OFF THE LOOM!",
+    ],
+}
+
+
+# --------------------------------------------------------------------------
+# Society upgrade banks (personas / opinions / rumors) — all deterministic
+# --------------------------------------------------------------------------
+
+PERSONAS_JSON = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                             "personas_data.json")
+DEFAULT_OPINION = "no strong feelings about the Protagonist yet"
+
+# Opinion-of-the-Protagonist template banks; picked by (id + memory length)
+# modulo — zero RNG, zero LLM. {ref} = the alien's obsession when the scene
+# hits it, else a generic stand-in.
+_OPINION_RISING = (
+    "warming up to the Protagonist since the {ref} incident",
+    "secretly starting to root for the Protagonist",
+    "suspects the Protagonist is improving. suspicious",
+)
+_OPINION_FALLING = (
+    "losing patience with the Protagonist after the {ref} business",
+    "officially disappointed in the Protagonist",
+    "drafting a strongly worded zorbgram about the Protagonist",
+)
+_OPINION_POS = (
+    "a confirmed Protagonist fan — the {ref} sealed it",
+    "would defend the Protagonist before any tribunal",
+)
+_OPINION_NEG = (
+    "remains thoroughly unimpressed by the Protagonist",
+    "convinced the Protagonist is wildly overrated",
+)
+_OPINION_FLAT = (
+    "still undecided about the Protagonist",
+    "watching the Protagonist strictly for the {ref}",
+)
+
+RUMOR_TEMPLATES = (
+    "the Protagonist feeds the {x} FIRST",
+    "the Protagonist whispers to the {x} at night",
+    "the {x} is a prop. ALL of it is props",
+    "the Protagonist keeps a SECOND {x} hidden",
+    "the Protagonist won the {x} in a bet",
+)
+_RUMOR_SUBJECTS = ("Liquid Overlord", "Sacred Steam Chalice", "Clatter Altar",
+                   "Smaller Television", "Throne of Sitting", "Bark Unit")
+# Telephone-game mutations applied on every 10th infection.
+RUMOR_MUTATIONS = (
+    lambda t: t.replace("the Protagonist", "the so-called Protagonist", 1),
+    lambda t: t + ", ALLEGEDLY",
+    lambda t: "apparently " + t,
+    lambda t: t.replace("FIRST", "FIRST and LAST")
+    if "FIRST" in t else t + "!!",
+    lambda t: t.upper(),
+)
+RUMOR_MAX_LEN = 50               # "(psst: " + 50 + ")" fits a 60-char bubble
+RUMOR_LIFETIME_TICKS = 120       # ~60 s, then it fades
+RUMOR_HOP_P = 0.15               # per carrier per tick
+RUMOR_WHISPER_P = 0.05           # per carrier per tick, max 2 concurrent
+RUMOR_SCENE_SEED_P = 0.2         # ~every 5th new_scene
+
+
+def _clamp(x, lo=-1.0, hi=1.0):
+    return lo if x < lo else hi if x > hi else x
+
+
+def _tokens(text: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z']+", text.lower()) if w not in STOPWORDS}
+
+
+def extract_tags(description: str) -> set[str]:
+    """Keyword-match a (Codex-substituted or raw) scene string into the fixed tag set."""
+    toks = _tokens(description)
+    tags: set[str] = set()
+    for tag, words in _TAG_KEYWORDS.items():
+        if toks & set(words):
+            tags.add(tag)
+    if any(t.startswith(stem) for t in toks for stem in _MOTION_STEMS):
+        tags.add("motion")
+    if (toks & set(_ABSENCE_WORDS)) or "person" not in tags:
+        tags.add("absence")
+    return tags
+
+
+# --------------------------------------------------------------------------
+# Agent
+# --------------------------------------------------------------------------
+
+class _Alien:
+    __slots__ = ("id", "row", "seat", "archetype", "color", "bias", "k", "rest",
+                 "s", "mood", "inj", "hist", "neighbors",
+                 "rest_offset", "rest_offset_until", "last_spoke_round",
+                 "name", "quirk", "obsession", "relationship", "tic",
+                 "memory", "opinion")
+
+    def __init__(self, aid, row, seat, archetype, rng):
+        bias, k, rest, color = ARCHETYPES[archetype]
+        self.id, self.row, self.seat = aid, row, seat
+        self.archetype, self.color = archetype, color
+        self.bias, self.k, self.rest = bias, k, rest
+        self.s = _clamp(rest + rng.gauss(0, 0.08))
+        self.mood = "calm"
+        self.inj = 0.0
+        self.hist = [self.s] * 5          # ring buffer of last sentiments (oldest first)
+        self.neighbors: list[int] = []
+        self.rest_offset = 0.0
+        self.rest_offset_until = -1
+        self.last_spoke_round = -10
+        # Persona (overwritten from personas_data.json when present).
+        self.name = f"Blorp #{aid}"
+        self.quirk = ""
+        self.obsession = ""
+        self.relationship = None
+        self.tic = ""
+        # Rolling memory of (scene, said, sentiment) + evolving one-liner.
+        self.memory: deque = deque(maxlen=6)
+        self.opinion = DEFAULT_OPINION
+
+    def pull(self, tags: set[str]) -> float:
+        return _clamp(sum(w for t, w in self.bias.items() if t in tags))
+
+
+# --------------------------------------------------------------------------
+# Seating (section 3, deterministic with Random(1337))
+# --------------------------------------------------------------------------
+
+def _build_seating(rng: random.Random) -> dict[tuple[int, int], str]:
+    taken: dict[tuple[int, int], str] = {}
+
+    def place(seats, arch):
+        for rs in seats:
+            taken[rs] = arch
+
+    # devout: 10 front-center seats (rows 0-1, seats 4-10)
+    place([(0, s) for s in range(4, 11)] + [(1, 6), (1, 7), (1, 8)], "devout")
+    # hecklers: back row 7, left side
+    place([(7, s) for s in range(10)], "heckler")
+    # elders: rows 0-1 flanks
+    place([(0, s) for s in (0, 1, 2, 3, 11, 12, 13, 14)] + [(1, 0), (1, 14)], "elder")
+    # art critics: the four back corners +/-1 (skip occupied, widen until 10 placed)
+    crit: list[tuple[int, int]] = []
+    anchors = [(7, 14), (6, 0), (6, 14), (7, 0)]
+    radius = 0
+    while len(crit) < 10 and radius < SEATS:
+        for r, c in anchors:
+            for dc in ([0] if radius == 0 else [-radius, radius]):
+                rs = (r, c + dc)
+                if (0 <= rs[1] < SEATS and rs not in taken
+                        and rs not in crit and len(crit) < 10):
+                    crit.append(rs)
+        radius += 1
+    place(crit, "art_critic")
+
+    # remaining 8 archetypes in shuffled blocks of 2 (pairs sit adjacent ~50%)
+    rest = ["anthropologist", "conspiracist", "sportscaster", "foodie",
+            "romantic", "doom_prophet", "tourist", "merch_vendor"]
+    blocks = [a for a in rest for _ in range(5)]   # 5 blocks of 2 each = 10 seats
+    rng.shuffle(blocks)
+    free = [(r, s) for r in range(ROWS) for s in range(SEATS) if (r, s) not in taken]
+    free.sort(key=lambda rs: rs[0] * SEATS + rs[1])
+    it = iter(free)
+    for arch in blocks:
+        taken[next(it)] = arch
+        taken[next(it)] = arch
+    return taken
+
+
+# --------------------------------------------------------------------------
+# CrowdSim
+# --------------------------------------------------------------------------
+
+class CrowdSim:
+    """120-agent opinion-contagion crowd. See module docstring."""
+
+    def __init__(self, model=None, llm_lock: threading.Lock | None = None,
+                 thought_cb=None):
+        self._model = model
+        self._llm_lock = llm_lock or threading.Lock()
+        self._lock = threading.RLock()
+        self._rng = random.Random(1337)
+        # Optional trace hook: thought_cb(kind, title, body). Never allowed
+        # to break the sim.
+        cb = thought_cb or (lambda *a, **k: None)
+        def _safe_cb(kind, title, body=""):
+            try:
+                cb(kind, title, body)
+            except Exception:
+                pass
+        self._thought = _safe_cb
+        # Voiced bubbles waiting their turn (comic-timing rollout, 1/tick).
+        self._voice_queue: list[tuple[int, str]] = []
+
+        seating = _build_seating(self._rng)
+        self._aliens = [
+            _Alien(r * SEATS + s, r, s, seating[(r, s)], self._rng)
+            for r in range(ROWS) for s in range(SEATS)
+        ]
+        for a in self._aliens:                      # neighbors: L, R, ahead, behind
+            for dr, ds in ((0, -1), (0, 1), (-1, 0), (1, 0)):
+                r, s = a.row + dr, a.seat + ds
+                if 0 <= r < ROWS and 0 <= s < SEATS:
+                    a.neighbors.append(r * SEATS + s)
+        self._load_personas()
+
+        self._tick_count = 0
+        self._dt_acc = 0.0
+        self._tags: set[str] = set()
+        self._scene = ""
+        self._last_scene_words: set[str] | None = None
+        self._ticks_since_scene = 10 ** 9
+
+        self._event: str | None = None
+        self._event_until = -1
+        self._last_event_start = -10 ** 9
+
+        self._noticed_cluster: set[int] = set()
+        self._noticed_sample_until = -1
+
+        self._bubbles: dict[int, tuple[str, int]] = {}   # id -> (text, expire_tick)
+
+        self._light = -1
+        self._sound = -1
+        self._light_hist: list[tuple[float, int]] = []
+
+        self._faction_snapshot = self._factions_unlocked()
+        self._growth_faction = "love"
+        self._speak_round = 0
+        self._intermission_pending_wave = False
+
+        # Hot seat: ids of the previous scene's speakers (sticky ~60%).
+        self._hot: set[int] = set()
+        # Rumor: one at a time, telephone-game spread seat to seat.
+        self._rumor_text: str | None = None
+        self._rumor_carriers: set[int] = set()
+        self._rumor_until = -1
+        self._rumor_infections = 0
+
+    def _load_personas(self):
+        """Attach personas from personas_data.json; graceful when absent.
+        Accepts a list (positional or with 'id' fields) or an id-keyed dict,
+        optionally wrapped in {'personas': ...} / {'aliens': ...}."""
+        data = None
+        try:
+            with open(PERSONAS_JSON, encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception:
+            data = None
+        if isinstance(data, dict):
+            data = data.get("personas") or data.get("aliens") or data
+        entries: dict[int, dict] = {}
+        if isinstance(data, list):
+            for i, e in enumerate(data):
+                if isinstance(e, dict):
+                    try:
+                        entries[int(e.get("id", i))] = e
+                    except (TypeError, ValueError):
+                        entries[i] = e
+        elif isinstance(data, dict):
+            for k, e in data.items():
+                if isinstance(e, dict):
+                    try:
+                        entries[int(k)] = e
+                    except (TypeError, ValueError):
+                        pass
+        loaded = 0
+        for a in self._aliens:
+            e = entries.get(a.id)
+            if not e:
+                continue
+            a.name = str(e.get("name") or a.name)[:40]
+            a.quirk = str(e.get("quirk") or "")
+            a.obsession = str(e.get("obsession") or "")
+            a.relationship = e.get("relationship")
+            a.tic = str(e.get("tic") or "")
+            loaded += 1
+        if loaded:
+            self._thought("event", "persona census loaded",
+                          f"{loaded} personas from personas_data.json")
+
+    # ---------------- public spec API ----------------
+
+    def tick(self, dt: float = TICK_SECONDS):
+        """Advance the sim; runs one 0.5 s sub-step per accumulated 0.5 s of dt."""
+        with self._lock:
+            self._dt_acc += max(0.0, float(dt))
+            while self._dt_acc >= TICK_SECONDS - 1e-9:
+                self._dt_acc -= TICK_SECONDS
+                self._tick_once()
+
+    def on_scene(self, description: str) -> bool:
+        """Novelty-gate a (Codex-substituted) scene string; on accept, apply it
+        and run ONE batched raw_chat voicing call. Returns True if accepted."""
+        description = (description or "").strip()
+        if not description:
+            return False
+        words = _tokens(description)
+        with self._lock:
+            if self._last_scene_words is not None and words and self._last_scene_words:
+                union = words | self._last_scene_words
+                novelty = 1.0 - len(words & self._last_scene_words) / len(union)
+            else:
+                novelty = 1.0
+            if novelty < 0.4:
+                return False
+            self._last_scene_words = words
+            tags = extract_tags(description)
+            tags.add("novelty")
+            self._voice_queue.clear()   # new scene supersedes unspoken lines
+            # NOTE: distinct from _speak_round (hot-seat sampling counter) —
+            # this one only advances per ACCEPTED scene, for the stale-voice guard.
+            self._voice_round = getattr(self, "_voice_round", 0) + 1
+            round_no = self._voice_round
+            self.apply_scene(description, tags)
+            speakers = self.sample_speakers(8)
+            scene, event = self._scene, self._event
+            love, meh, hate = self._faction_tuple()
+        self._voice(scene, event, (love, meh, hate), speakers, round_no)
+        return True
+
+    def apply_scene(self, scene: str, tags: set[str]):
+        """Set pulse + first reactors, fire new_scene (and intermission/wave)."""
+        with self._lock:
+            was_intermission = self._event == "intermission"
+            self._scene = scene
+            self._tags = set(tags) & set(TAG_ORDER)
+            self._ticks_since_scene = 0
+            self._faction_snapshot, prev = self._factions_unlocked(), self._faction_snapshot
+            self._growth_faction = max(
+                ("love", "meh", "hate"),
+                key=lambda f: self._faction_snapshot[f] - prev[f])
+
+            # first reactors: 16 seats weighted toward rows 0-2
+            weights = [4.0 if a.row <= 2 else 1.0 for a in self._aliens]
+            chosen: set[int] = set()
+            while len(chosen) < 16:
+                chosen.add(self._rng.choices(range(N_ALIENS), weights=weights)[0])
+            for aid in chosen:
+                a = self._aliens[aid]
+                a.inj += 0.5 * a.pull(self._tags)
+
+            if was_intermission and "absence" not in self._tags:
+                self._start_event("wave", exempt=True)   # spec: immediately fire wave
+            else:
+                self._start_event("new_scene", exempt=True)
+            # gossip: ~every 5th new scene spawns a rumor
+            if self._rng.random() < RUMOR_SCENE_SEED_P:
+                self._seed_rumor("a new scene set tongues wagging")
+
+    def poke(self):
+        """NOTICED: epicenter + Chebyshev-2 fear cluster; always fires."""
+        with self._lock:
+            epi = self._aliens[self._rng.randrange(N_ALIENS)]
+            cluster = {
+                a.id for a in self._aliens
+                if max(abs(a.row - epi.row), abs(a.seat - epi.seat)) <= 2
+            }
+            for aid in cluster:
+                a = self._aliens[aid]
+                a.inj += -0.6
+                if a.archetype == "conspiracist":
+                    a.rest_offset = -0.3
+                    a.rest_offset_until = self._tick_count + 40
+            self._noticed_cluster = cluster
+            self._noticed_sample_until = self._tick_count + 20  # sampling override window
+            self._start_event("noticed", exempt=True)
+            self.set_bubble(epi.id, NOTICED_BUBBLE, guaranteed=True)
+            self._seed_rumor("being NOTICED demands an explanation")
+        return {"ok": True}
+
+    def sense(self, light: int, sound: int):
+        """Browser ambiance numbers; -1 = not live. Feeds the gasp trigger."""
+        with self._lock:
+            self._light, self._sound = int(light), int(sound)
+            now = time.monotonic()
+            if light >= 0:
+                self._light_hist.append((now, int(light)))
+            self._light_hist = [(t, v) for t, v in self._light_hist if now - t <= 5.0]
+
+    def _interest(self, a: _Alien, tags: set[str]) -> float:
+        """How much this alien cares about the current scene: archetype tag
+        bias + a bonus when their personal obsession is on screen."""
+        v = abs(a.pull(tags))
+        if a.obsession and ((extract_tags(a.obsession) - {"absence"}) & tags):
+            v += 0.5
+        return v
+
+    def sample_speakers(self, n: int = 8) -> list[dict]:
+        """HOT-SEAT sampling: ~60% of last scene's speakers stay (if they still
+        care), the rest filled interest-weighted, plus 1-2 uniform wildcards."""
+        with self._lock:
+            self._speak_round += 1
+            rnd = self._speak_round
+            tags = self._tags
+            eligible = [a for a in self._aliens if a.last_spoke_round < rnd - 1]
+            picks: list[_Alien] = []
+            arch_count: dict[str, int] = {}
+
+            def add(a: _Alien | None) -> bool:
+                if a is None or len(picks) >= n or a in picks:
+                    return False
+                if arch_count.get(a.archetype, 0) >= 3:
+                    return False
+                picks.append(a)
+                arch_count[a.archetype] = arch_count.get(a.archetype, 0) + 1
+                return True
+
+            def pool_of(base) -> list[_Alien]:
+                return [a for a in base if a not in picks
+                        and arch_count.get(a.archetype, 0) < 3]
+
+            # 1) stickiness: previous speakers stay hot with p=0.6 when their
+            #    interest in the new scene is nonzero (arc continuity); always
+            #    leave >= 2 seats for fresh blood.
+            for aid in sorted(self._hot):
+                if len(picks) >= max(0, n - 2):
+                    break
+                a = self._aliens[aid]
+                if self._interest(a, tags) > 0 and self._rng.random() < 0.6:
+                    add(a)
+
+            # 2) noticed override: pad to 5 from the fear cluster
+            if self._tick_count < self._noticed_sample_until and n >= 8:
+                cluster = pool_of([a for a in eligible
+                                   if a.id in self._noticed_cluster])
+                while len(picks) < 5 and cluster:
+                    w = [abs(a.s) + 0.05 for a in cluster]
+                    a = self._rng.choices(cluster, weights=w)[0]
+                    add(a)
+                    cluster.remove(a)
+
+            # 3) reserve 1-2 uniform wildcard seats, fill the rest by interest
+            wild = 1 + (1 if self._rng.random() < 0.5 else 0)
+            while len(picks) < n - wild:
+                pool = pool_of(eligible) or pool_of(self._aliens)
+                if not pool:
+                    break
+                w = [self._interest(a, tags) + 0.05 for a in pool]
+                add(self._rng.choices(pool, weights=w)[0])
+            while len(picks) < n:   # wildcards: anyone, uniform
+                pool = pool_of(eligible) or pool_of(self._aliens)
+                if not pool:
+                    break
+                add(self._rng.choice(pool))
+
+            for a in picks:
+                a.last_spoke_round = rnd
+            self._hot = {a.id for a in picks}
+            return [{"id": a.id, "archetype": a.archetype,
+                     "mood": a.mood, "sentiment": round(a.s, 3),
+                     "name": a.name, "tic": a.tic, "opinion": a.opinion,
+                     "last_said": a.memory[-1]["said"] if a.memory else ""}
+                    for a in picks]
+
+    def set_bubble(self, alien_id: int, text: str, guaranteed: bool = False):
+        with self._lock:
+            text = (text or "").strip().strip('"\'*').strip()
+            if not text or not (0 <= alien_id < N_ALIENS):
+                return
+            text = text[:60]
+            self._prune_bubbles()
+            if alien_id not in self._bubbles and len(self._bubbles) >= 8:
+                if not guaranteed:
+                    return
+                oldest = min(self._bubbles, key=lambda k: self._bubbles[k][1])
+                del self._bubbles[oldest]
+            ttl = self._rng.randint(12, 20)  # ~6-10 s
+            self._bubbles[alien_id] = (text, self._tick_count + ttl)
+
+    def inject(self, alien_id: int, amount: float):
+        with self._lock:
+            if 0 <= alien_id < N_ALIENS:
+                self._aliens[alien_id].inj += float(amount)
+
+    def state(self) -> dict:
+        """Exact /api/state shape minus scene/live/thinking (B2 merges those)."""
+        with self._lock:
+            self._prune_bubbles()
+            ev = self._event if self._tick_count < self._event_until else None
+            love, meh, hate = self._faction_tuple()
+            return {
+                "event": ev,
+                "light": self._light,
+                "sound": self._sound,
+                "factions": {"love": love, "meh": meh, "hate": hate},
+                "rumor": self._rumor_text,
+                "aliens": [
+                    {
+                        "id": a.id, "row": a.row, "seat": a.seat,
+                        "archetype": a.archetype, "color": a.color,
+                        "mood": a.mood, "sentiment": round(a.s, 3),
+                        "bubble": self._bubbles.get(a.id, (None,))[0],
+                        "name": a.name,
+                    }
+                    for a in self._aliens
+                ],
+            }
+
+    def alien_card(self, alien_id: int) -> dict | None:
+        """Full dossier on one alien for the click-card UI (thread-safe)."""
+        with self._lock:
+            if not 0 <= int(alien_id) < N_ALIENS:
+                return None
+            a = self._aliens[int(alien_id)]
+            return {
+                "id": a.id, "name": a.name, "archetype": a.archetype,
+                "quirk": a.quirk, "obsession": a.obsession,
+                "relationship": a.relationship, "tic": a.tic,
+                "opinion": a.opinion,
+                "memory": [dict(m) for m in a.memory],
+                "mood": a.mood, "sentiment": round(a.s, 3),
+            }
+
+    # ---------------- internals ----------------
+
+    def _prune_bubbles(self):
+        dead = [k for k, (_, exp) in self._bubbles.items() if self._tick_count >= exp]
+        for k in dead:
+            del self._bubbles[k]
+
+    @staticmethod
+    def _faction_of(s: float) -> str:
+        return "love" if s > 0.25 else "hate" if s < -0.25 else "meh"
+
+    def _factions_unlocked(self) -> dict[str, int]:
+        f = {"love": 0, "meh": 0, "hate": 0}
+        for a in self._aliens:
+            f[self._faction_of(a.s)] += 1
+        return f
+
+    def _faction_tuple(self):
+        f = self._factions_unlocked()
+        return f["love"], f["meh"], f["hate"]
+
+    def _start_event(self, name: str, exempt: bool = False):
+        if not exempt:
+            if self._tick_count < self._event_until:
+                return
+            if self._tick_count - self._last_event_start < EVENT_COOLDOWN_TICKS:
+                return
+        self._event = name
+        self._event_until = self._tick_count + EVENT_DURATIONS[name]
+        self._last_event_start = self._tick_count
+        self._thought("event", f"crowd event: {name.upper()}",
+                      f"tick {self._tick_count}; factions love/meh/hate = "
+                      f"{self.state()['factions']}")
+
+    def _tick_once(self):
+        tags = self._tags
+        snap = [a.s for a in self._aliens]
+        pulse = max(0.0, 1.0 - self._ticks_since_scene / 8.0)
+        for a in self._aliens:
+            nbr = sum(snap[j] for j in a.neighbors) / len(a.neighbors)
+            pull = a.pull(tags)
+            rest = a.rest + (a.rest_offset if self._tick_count < a.rest_offset_until else 0.0)
+            ds = (0.30 * a.k * (nbr - a.s)
+                  + 0.12 * pulse * pull
+                  + 0.02 * (rest - a.s)
+                  + a.inj
+                  + self._rng.gauss(0, 0.03))
+            a.inj = 0.0
+            a.s = _clamp(a.s + ds)
+        for a in self._aliens:
+            a.hist.append(a.s)
+            if len(a.hist) > 5:
+                a.hist.pop(0)
+        self._tick_count += 1
+        self._ticks_since_scene += 1
+
+        noticed_active = (self._event == "noticed"
+                          and self._tick_count < self._event_until)
+        for a in self._aliens:
+            a.mood = self._mood_of(a, noticed_active)
+
+        self._prune_bubbles()
+        # Roll out one queued voice per tick (~0.5s apart) — comic timing.
+        if self._voice_queue:
+            aid, text = self._voice_queue.pop(0)
+            self.set_bubble(aid, text)
+        self._check_events()
+        self._tick_rumor()
+        self._maybe_murmur()
+
+    # ---------------- memory & opinion (deterministic, no LLM) ----------------
+
+    def _remember(self, a: _Alien, said: str):
+        """Append to the alien's rolling memory and refresh their one-line
+        opinion of the Protagonist. Caller holds self._lock."""
+        a.memory.append({"scene": (self._scene or "")[:80],
+                         "said": said[:60], "sentiment": round(a.s, 3)})
+        sents = [m["sentiment"] for m in a.memory]
+        trend = sents[-1] - sents[0]
+        avg = sum(sents) / len(sents)
+        hit = bool(a.obsession
+                   and (extract_tags(a.obsession) - {"absence"}) & self._tags)
+        ref = a.obsession if (hit and a.obsession) else "whole spectacle"
+        if trend > 0.15:
+            bank = _OPINION_RISING
+        elif trend < -0.15:
+            bank = _OPINION_FALLING
+        elif avg > 0.25:
+            bank = _OPINION_POS
+        elif avg < -0.25:
+            bank = _OPINION_NEG
+        else:
+            bank = _OPINION_FLAT
+        a.opinion = bank[(a.id + len(a.memory)) % len(bank)].format(ref=ref)
+
+    # ---------------- rumor mill (telephone game) ----------------
+
+    @staticmethod
+    def _fit_rumor(text: str) -> str:
+        """Cap rumor length at a WORD boundary — mid-word slices read as bugs
+        ("...personal ocean hidd")."""
+        if len(text) <= RUMOR_MAX_LEN:
+            return text
+        cut = text[:RUMOR_MAX_LEN]
+        sp = cut.rfind(" ")
+        return (cut[:sp] if sp >= 12 else cut).rstrip(" ,.!")
+
+    def _seed_rumor(self, reason: str):
+        """Start a rumor about the Protagonist (one at a time). Caller holds
+        self._lock."""
+        if self._rumor_text is not None:
+            return
+        seed = self._aliens[self._rng.randrange(N_ALIENS)]
+        x = (seed.obsession if 0 < len(seed.obsession) <= 24
+             else self._rng.choice(_RUMOR_SUBJECTS))
+        text = self._fit_rumor(self._rng.choice(RUMOR_TEMPLATES).format(x=x))
+        self._rumor_text = text
+        self._rumor_carriers = {seed.id} | set(seed.neighbors)
+        self._rumor_infections = len(self._rumor_carriers)
+        self._rumor_until = self._tick_count + RUMOR_LIFETIME_TICKS
+        self._thought("event", "rumor seeded",
+                      f"{reason} — {seed.name} starts it: \"{text}\" "
+                      f"({len(self._rumor_carriers)} carriers)")
+
+    def _clear_rumor(self):
+        self._rumor_text = None
+        self._rumor_carriers = set()
+        self._rumor_until = -1
+
+    def _tick_rumor(self):
+        """One spread step: hop seat-to-seat, mutate every 10th infection,
+        occasionally whisper, die out on timeout or full saturation."""
+        if self._rumor_text is None:
+            return
+        if self._tick_count >= self._rumor_until:
+            self._thought("event", "rumor fades",
+                          f"\"{self._rumor_text}\" died at "
+                          f"{len(self._rumor_carriers)} carriers")
+            self._clear_rumor()
+            return
+        carriers = self._rumor_carriers
+        fresh: set[int] = set()
+        for cid in sorted(carriers):
+            if self._rng.random() < RUMOR_HOP_P:
+                nb = self._rng.choice(self._aliens[cid].neighbors)
+                if nb not in carriers:
+                    fresh.add(nb)
+        for nb in sorted(fresh):
+            carriers.add(nb)
+            self._rumor_infections += 1
+            if self._rumor_infections % 10 == 0:   # telephone-game drift
+                mut = RUMOR_MUTATIONS[
+                    self._rng.randrange(len(RUMOR_MUTATIONS))]
+                self._rumor_text = self._fit_rumor(mut(self._rumor_text))
+        # whisper bubbles "(psst: ...)" — at most 2 visible at once
+        psst = sum(1 for txt, _ in self._bubbles.values()
+                   if txt.startswith("(psst"))
+        for cid in sorted(carriers):
+            if psst >= 2:
+                break
+            if self._rng.random() < RUMOR_WHISPER_P:
+                self.set_bubble(cid, f"(psst: {self._rumor_text})")
+                psst += 1
+        if len(carriers) >= N_ALIENS:
+            self._thought("event", "rumor became canon",
+                          f"all {N_ALIENS} aliens now believe: "
+                          f"\"{self._rumor_text}\"")
+            self._clear_rumor()
+
+    def _maybe_murmur(self):
+        """Idle chatter between scenes: when the theater goes quiet, a random
+        alien occasionally mutters a stub line — keeps the crowd alive even
+        before any camera frame arrives."""
+        if len(self._bubbles) >= 3 or self._rng.random() > 0.12:
+            return
+        a = self._rng.choice(self._aliens)
+        lines = STUB_LINES.get(a.archetype)
+        if lines:
+            text = self._rng.choice(lines)
+            self.set_bubble(a.id, text)
+            self._remember(a, text)
+            self._thought("event", f"{a.name} the {a.archetype} murmurs (idle theater)", text)
+
+    def _mood_of(self, a: _Alien, noticed_active: bool) -> str:
+        h = a.hist
+        delta = a.s - h[0]
+        if (noticed_active and a.id in self._noticed_cluster) or \
+                (a.s < -0.5 and delta < -0.25):
+            return "scared"
+        if a.s > 0.5:
+            return "delighted"
+        if a.s > 0.2 and abs(delta) > 0.15:
+            return "excited"
+        if a.s < -0.2:
+            return "annoyed"
+        if abs(a.s) <= 0.2:
+            nbr_s = [self._aliens[j].s for j in a.neighbors]
+            d1, d2, d3 = h[4] - h[3], h[3] - h[2], h[2] - h[1]
+            flips = (d1 * d2 < 0) and (d2 * d3 < 0)
+            if (max(nbr_s) - min(nbr_s) > 0.8) or flips:
+                return "confused"
+        return "calm"
+
+    def _check_events(self):
+        if self._tick_count < self._event_until:
+            # intermission ends only when absence clears (apply_scene handles wave)
+            return
+        if self._event is not None:
+            self._event = None
+        # priority: intermission > chant > gasp > ovation > wave > boo
+        if "absence" in self._tags:
+            self._start_event("intermission")
+            return
+        if "drink" in self._tags and sum(
+                1 for a in self._aliens
+                if a.archetype == "devout" and a.s > 0.5) >= 6:
+            self._start_event("chant")
+            return
+        if self._gasp_triggered():
+            self._start_event("gasp")
+            return
+        mean_s = sum(a.s for a in self._aliens) / N_ALIENS
+        love, _, _ = self._faction_tuple()
+        if mean_s > 0.55 and love >= 70:
+            self._start_event("ovation")
+            return
+        if self._wave_triggered():
+            self._start_event("wave")
+            return
+        if mean_s < -0.4:
+            self._start_event("boo")
+
+    def _gasp_triggered(self) -> bool:
+        if self._light >= 0 and len(self._light_hist) >= 2:
+            cur = self._light_hist[-1][1]
+            if max(v for _, v in self._light_hist) - cur >= 40:
+                return True
+        drops = sum(1 for a in self._aliens
+                    if len(a.hist) >= 3 and a.hist[2] - a.hist[4] > 0.35)
+        return drops >= 40
+
+    def _wave_triggered(self) -> bool:
+        for r in range(ROWS):
+            run = 0
+            for s in range(SEATS):
+                run = run + 1 if self._aliens[r * SEATS + s].s > 0.6 else 0
+                if run >= 10:
+                    return True
+        return False
+
+    # ---------------- LLM voicing (section 5) ----------------
+
+    def _voice(self, scene: str, event: str | None, factions, speakers: list[dict],
+               round_no: int = 0):
+        """ONE batched raw_chat per accepted scene; stub bank backfills gaps.
+        Called WITHOUT self._lock held; raw_chat serialized via llm_lock.
+        ``round_no`` guards against a slow reply landing after a NEWER scene
+        was accepted — stale lines are dropped, not misattributed."""
+        if not speakers:
+            return
+        love, meh, hate = factions
+
+        def _entry(i: int, sp: dict) -> str:
+            parts = [f"{i + 1} {sp.get('name', '?')} "
+                     f"({sp['archetype'].upper()}, {sp['mood']})"]
+            if sp.get("tic"):
+                parts.append(f"tic:{sp['tic']}")
+            if sp.get("last_said"):
+                parts.append(f"memory:'{sp['last_said']}'")
+            if sp.get("opinion"):
+                parts.append(f"opinion:{sp['opinion']}")
+            return " ".join(parts)
+
+        audience = "\n".join(_entry(i, sp) for i, sp in enumerate(speakers))
+        user = (f"SCENE: {scene}\n"
+                f"EVENT: {event or 'none'} | CROWD: love {love} / meh {meh} / hate {hate}\n"
+                f"AUDIENCE:\n{audience}\n"
+                f'One reaction line per number, format "N ARCHETYPE: text":')
+        self._thought("voice", f"voicing {len(speakers)} aliens for new scene",
+                      f"PROMPT (user part):\n{user}")
+        raw = ""
+        if self._model is not None:
+            try:
+                with self._llm_lock:
+                    raw = self._model.raw_chat(VOICE_SYSTEM_PROMPT, user,
+                                               max_tokens=256, temperature=0.9) or ""
+            except Exception:
+                raw = ""
+        self._thought("voice",
+                      "LLM replied" if raw else "no model — stub line bank",
+                      raw[:1200] if raw else "raw_chat returned empty; canned "
+                      "archetype lines will backfill every speaker")
+        lines: dict[int, str] = {}
+        for line in raw.splitlines():
+            m = _VOICE_LINE_RE.match(line)
+            if not m:
+                continue
+            num = int(m.group(1))
+            if 1 <= num <= len(speakers) and num not in lines:
+                text = m.group(2).strip().strip('"\'*').strip()
+                # Drop a leading "DEVOUT:" / "ART CRITIC:" echo of the format.
+                text = _VOICE_PREFIX_RE.sub("", text).strip()
+                if text:
+                    lines[num] = text[:60]
+        parsed = len(lines)
+        with self._lock:
+            if round_no and round_no != getattr(self, "_voice_round", 0):
+                self._thought("voice", "stale voicing dropped",
+                              "a newer scene arrived while the model was "
+                              "writing; these lines belong to the old one")
+                return
+            for i, sp in enumerate(speakers):
+                text = lines.get(i + 1) or self._rng.choice(
+                    STUB_LINES[sp["archetype"]])
+                # Comic timing: first voice lands now, the rest roll out one
+                # per tick (~0.5s apart) via the queue drained in _tick_once.
+                if i == 0:
+                    self.set_bubble(sp["id"], text)
+                else:
+                    self._voice_queue.append((sp["id"], text))
+                a = self._aliens[sp["id"]]
+                self._remember(a, text)   # memory -> running gags next scene
+                pull = a.pull(self._tags)
+                base = pull if pull != 0 else a.s
+                a.inj += 0.4 * math.copysign(1.0, base) if base != 0 else 0.0
+        self._thought("voice",
+                      f"bubbles assigned: {parsed} from model, "
+                      f"{len(speakers) - parsed} from stub bank",
+                      "\n".join(f"{sp['archetype']}: "
+                                f"{(lines.get(i + 1) or '(stub)')}"
+                                for i, sp in enumerate(speakers)))
+
+
+# Spec section 4 names the class `Crowd`; keep both importable.
+Crowd = CrowdSim
+
+
+# --------------------------------------------------------------------------
+# Smoke test
+# --------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    sim = CrowdSim(model=None)
+
+    def check_shape(st):
+        assert set(st) == {"event", "light", "sound", "factions", "aliens",
+                           "rumor"}, st.keys()
+        assert st["rumor"] is None or (isinstance(st["rumor"], str) and st["rumor"])
+        assert set(st["factions"]) == {"love", "meh", "hate"}
+        assert sum(st["factions"].values()) == N_ALIENS
+        assert len(st["aliens"]) == N_ALIENS
+        base_keys = {"id", "row", "seat", "archetype", "color",
+                     "mood", "sentiment", "bubble"}
+        bubbles = 0
+        for i, a in enumerate(st["aliens"]):
+            assert base_keys <= set(a) <= base_keys | {"name"}, set(a)
+            assert isinstance(a.get("name", ""), str)
+            assert a["id"] == i and a["id"] == a["row"] * SEATS + a["seat"]
+            assert a["archetype"] in ARCHETYPES
+            assert a["color"] in (LIME, MAGENTA, AMBER)
+            assert a["mood"] in MOODS
+            assert -1.0 <= a["sentiment"] <= 1.0
+            if a["bubble"] is not None:
+                bubbles += 1
+                assert len(a["bubble"]) <= 60
+        assert bubbles <= 8, bubbles
+        return bubbles
+
+    check_shape(sim.state())
+    per_arch = {}
+    for a in sim.state()["aliens"]:
+        per_arch[a["archetype"]] = per_arch.get(a["archetype"], 0) + 1
+    assert all(v == 10 for v in per_arch.values()), per_arch
+
+    accepted = sim.on_scene("The Protagonist lifts the Sacred Steam Chalice and drinks.")
+    assert accepted
+    b1 = check_shape(sim.state())
+    assert b1 >= 1, "no bubbles after first scene"
+    for _ in range(30):
+        sim.tick(0.5)
+    check_shape(sim.state())
+
+    # near-duplicate scene must be rejected (novelty < 0.4)
+    assert not sim.on_scene("The Protagonist lifts the Sacred Steam Chalice and drinks again.")
+
+    accepted = sim.on_scene("The room sits empty and dark, the Throne of Sitting unoccupied.")
+    assert accepted
+    b2 = check_shape(sim.state())
+    assert b2 >= 1, "no bubbles after second scene"
+    st = sim.state()
+    assert st["event"] in ("new_scene", "wave", "intermission")
+    for _ in range(30):
+        sim.tick(0.5)
+    check_shape(sim.state())
+
+    sim.poke()
+    st = sim.state()
+    assert st["event"] == "noticed"
+    assert any(a["bubble"] == NOTICED_BUBBLE for a in st["aliens"])
+    sim.tick(0.5)
+    st = sim.state()
+    assert any(a["mood"] == "scared" for a in st["aliens"])
+    check_shape(st)
+
+    sim.sense(80, 20)
+    sim.sense(10, 90)   # light drop >= 40 -> gasp becomes eligible
+    for _ in range(40):
+        sim.tick(0.5)
+    check_shape(sim.state())
+
+    # ---------------- society upgrade checks ----------------
+
+    # personas: load when the census file exists; graceful fallback otherwise
+    if os.path.exists(PERSONAS_JSON):
+        assert any(not a.name.startswith("Blorp #") for a in sim._aliens), \
+            "personas_data.json present but no names loaded"
+    else:
+        assert sim._aliens[0].name == "Blorp #0"
+
+    # alien_card shape (thread-safe dossier for the click-card UI)
+    card = sim.alien_card(0)
+    assert card is not None and card["id"] == 0
+    assert set(card) == {"id", "name", "archetype", "quirk", "obsession",
+                         "relationship", "tic", "opinion", "memory",
+                         "mood", "sentiment"}, set(card)
+    assert isinstance(card["name"], str) and card["name"]
+    assert isinstance(card["opinion"], str) and card["opinion"]
+    assert isinstance(card["memory"], list) and len(card["memory"]) <= 6
+    for m in card["memory"]:
+        assert set(m) == {"scene", "said", "sentiment"}
+    assert sim.alien_card(999) is None
+    # voiced speakers must have accumulated memory + an evolving opinion
+    remembered = [a for a in sim._aliens if a.memory]
+    assert remembered, "no alien recorded any memory after two scenes"
+    assert all(m_a.memory[-1]["said"] for m_a in remembered)
+
+    # hot-seat stickiness: consecutive samplings share speakers + fresh blood
+    sim_h = CrowdSim(model=None)
+    sim_h.apply_scene("The Protagonist sips from the Sacred Steam Chalice",
+                      {"drink", "person", "novelty"})
+    s1 = {sp["id"] for sp in sim_h.sample_speakers(8)}
+    assert sim_h._hot == s1
+    s2 = {sp["id"] for sp in sim_h.sample_speakers(8)}
+    assert len(s1) == len(s2) == 8
+    assert s1 & s2, "hot-seat stickiness: nobody carried over"
+    assert s2 - s1, "hot-seat: no fresh blood in second scene"
+    for sp in sim_h.sample_speakers(8):   # prompt-entry fields present
+        assert {"id", "archetype", "mood", "sentiment",
+                "name", "tic", "opinion", "last_said"} <= set(sp)
+
+    # rumor: seed on noticed, spread seat-to-seat, surface in state()
+    rumor_events = []
+    sim_r = CrowdSim(model=None,
+                     thought_cb=lambda k, t, b="": rumor_events.append(t))
+    sim_r.poke()
+    st = sim_r.state()
+    assert isinstance(st["rumor"], str) and st["rumor"]
+    assert any("rumor seeded" in t for t in rumor_events)
+    c0 = len(sim_r._rumor_carriers)
+    assert c0 >= 3   # seed + neighbors
+    for _ in range(80):
+        sim_r.tick(0.5)
+    assert (len(sim_r._rumor_carriers) > c0
+            or any("rumor became canon" in t for t in rumor_events)), \
+        "rumor never spread"
+    # force full saturation -> canon event + rumor cleared
+    if sim_r._rumor_text is not None:
+        with sim_r._lock:
+            sim_r._rumor_carriers = set(range(N_ALIENS))
+        sim_r.tick(0.5)
+        assert any("rumor became canon" in t for t in rumor_events)
+        assert sim_r.state()["rumor"] is None
+    check_shape(sim_r.state())
+
+    print("companion/crowd.py smoke test OK: "
+          f"{N_ALIENS} aliens, bubbles scene1={b1} scene2={b2}, "
+          f"hot-seat overlap={len(s1 & s2)}, society features green")

companion/duo.py

@@ -0,0 +1,207 @@
+"""DuoChat — two house cats who watch your webcam and judge you.
+
+Two cats who UNDERSTAND what the human is doing but react like cats: self-
+interested, unimpressed, food-obsessed, suspicious, prone to plotting and
+grudges. One batched LLM call per scene → a 2-line exchange.
+
+  MOCHI — a hyper kitten: must attack/chase/knock over everything; dramatic.
+  LOAF  — an enormous elder cat: lazy, deadpan, judgmental; lives for food + naps.
+
+Punch-ups: it detects the SITUATION (you appeared / left / are eating / on your
+phone / in the dark) and tracks GRUDGES (scenes since food appeared) so the cats
+do callbacks and running gags instead of one-off captions. ``situation`` is
+exposed in state() so the frontend can animate (pounce / dilate / tail-flick).
+
+Thread-safe. Deterministic stub fallback so it's funny with no model loaded.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+from collections import deque
+
+CATS = ("mochi", "loaf")
+
+SYSTEM = (
+    "You are two house cats, MOCHI and LOAF, watching your human through a window. "
+    "You understand what the human is doing — but you are cats: utterly self-interested, "
+    "unimpressed, ruled by food and naps, suspicious of objects, quick to plot, quicker "
+    "to take offense. NEVER just describe; always land an OPINION, a demand, a threat, or "
+    "a scheme. Be specific and cutting. Cat logic only (the bowl, the warm keyboard, the "
+    "forbidden counter, the 3am zoomies, knocking things off tables, the red dot, naps, "
+    "judging the staff).\n"
+    "MOCHI: hyper kitten — wants to attack/chase/knock over what it sees; dramatic; no chill.\n"
+    "LOAF: enormous elder — lazy, deadpan, withering; only truly cares about being fed.\n"
+    "Use the SITUATION and any GRUDGE the prompt gives you — call back to it, hold the grudge.\n"
+    "Write EXACTLY two short lines, in character, referencing what you SEE. Under 13 words "
+    "each. No quotes, no emoji, no stage directions. Format EXACTLY:\n"
+    "MOCHI: <line>\nLOAF: <line>\n(LOAF may go first if funnier.)"
+)
+
+_LINE_RE = re.compile(r"^\s*(MOCHI|LOAF)\s*[:.\-)]\s*(.+)$", re.IGNORECASE)
+
+# scene-keyword buckets used for situation detection
+_PERSON = ("person", "human", "man", "woman", "face", "people", "individual",
+           "someone", "shirt", "beard", "hair", "glasses", "head", "smiling")
+_FOOD = ("eat", "food", "snack", "sandwich", "pizza", "plate", "fruit", "meal",
+         "mug", "cup", "coffee", "tea", "drink", "bottle", "chewing")
+_DEVICE = ("phone", "smartphone", "screen", "laptop", "keyboard", "computer",
+           "monitor", "tablet", "rectangle", "slab", "typing", "glowing")
+_DARK = ("dark", "dim", "shadow", "unlit", "night", "black background")
+_ABSENT = ("empty", "no one", "nobody", "absent", "vacant", "no person", "blank")
+
+# Situation → a hint line for the prompt, and the animation tag for the frontend.
+SITUATIONS = {
+    "returned": "SITUATION: the human just CAME BACK into view. the staff returns.",
+    "left":     "SITUATION: the human just LEFT the frame. abandoned again.",
+    "food":     "SITUATION: the human has FOOD/DRINK and has not shared any.",
+    "device":   "SITUATION: the human is staring at a glowing slab instead of you.",
+    "dark":     "SITUATION: the lights are off. prime zoomies / nap conditions.",
+    "idle":     "SITUATION: the human is just sitting there, doing nothing useful.",
+}
+
+_STUB = {
+    "returned": [("loaf", "it returned. you may now serve me. begin."),
+                 ("mochi", "STAFF! you missed my third nap. unforgivable. welcome back.")],
+    "left":     [("mochi", "it LEFT. quick — onto the forbidden counter!"),
+                 ("loaf", "abandoned. i shall nap on its chair out of spite.")],
+    "food":     [("loaf", "food. and not one crumb for me. i'm noting this."),
+                 ("mochi", "share it. share it. SHARE IT or i knock the cup off.")],
+    "device":   [("mochi", "the glowing slab again. it loves the slab more than me."),
+                 ("loaf", "if i sit on the keys, the staring stops. science.")],
+    "dark":     [("mochi", "lights out means ZOOMIES. it's the law. i don't make it."),
+                 ("loaf", "good. dark. i become one with the couch now.")],
+    "idle":     [("loaf", "it does nothing, slowly. finally, a human i tolerate."),
+                 ("mochi", "throw the string. THROW it. why won't it throw the string.")],
+}
+
+
+class DuoChat:
+    def __init__(self, model=None, llm_lock: threading.Lock | None = None,
+                 thought_cb=None):
+        self._model = model
+        self._llm_lock = llm_lock or threading.Lock()
+        self._lock = threading.RLock()
+        cb = thought_cb or (lambda *a, **k: None)
+
+        def _safe(kind, title, body=""):
+            try:
+                cb(kind, title, body)
+            except Exception:
+                pass
+        self._thought = _safe
+
+        self._scene = "the window is still warming up."
+        self._exchange: list[dict] = []
+        self._situation = "idle"
+        self._history: deque[str] = deque(maxlen=4)
+        self._thinking = False
+        # running-gag state
+        self._present = False
+        self._since_food = 0
+
+    @property
+    def thinking(self) -> bool:
+        return self._thinking
+
+    def state(self) -> dict:
+        with self._lock:
+            return {
+                "scene": self._scene,
+                "situation": self._situation,
+                "cats": [{"id": "mochi", "name": "Mochi"}, {"id": "loaf", "name": "Loaf"}],
+                "exchange": list(self._exchange),
+                "thinking": self._thinking,
+            }
+
+    # -- situation + grudge ----------------------------------------------
+    def _classify(self, scene: str) -> tuple[str, str]:
+        """Return (situation, grudge_hint). Updates running-gag state."""
+        low = scene.lower()
+        hit = lambda words: any(w in low for w in words)
+        present = hit(_PERSON) and not hit(_ABSENT)
+        food = hit(_FOOD)
+
+        if food:
+            self._since_food = 0
+        else:
+            self._since_food += 1
+
+        if present and not self._present:
+            sit = "returned"
+        elif self._present and not present:
+            sit = "left"
+        elif food:
+            sit = "food"
+        elif hit(_DARK):
+            sit = "dark"
+        elif hit(_DEVICE):
+            sit = "device"
+        else:
+            sit = "idle"
+        self._present = present
+
+        grudge = ""
+        if self._since_food >= 3 and sit != "food":
+            grudge = (f"GRUDGE: it has been {self._since_food} scenes and STILL no food "
+                      f"has appeared. bring it up.")
+        return sit, grudge
+
+    # -- write side -------------------------------------------------------
+    def on_scene(self, scene: str) -> bool:
+        scene = (scene or "").strip()
+        if not scene:
+            return False
+        with self._lock:
+            self._scene = scene
+            self._thinking = True
+            situation, grudge = self._classify(scene)
+            self._situation = situation
+        self._thought("vision", f"the cats notice: {situation}", scene)
+        try:
+            exchange = self._react(scene, situation, grudge)
+        finally:
+            with self._lock:
+                self._thinking = False
+        with self._lock:
+            self._exchange = exchange
+            for line in exchange:
+                self._history.append(f"{line['who'].upper()}: {line['text']}")
+        self._thought("voice", "the cats pass judgment",
+                      "\n".join(f"{l['who'].upper()}: {l['text']}" for l in exchange))
+        return True
+
+    def _react(self, scene: str, situation: str, grudge: str) -> list[dict]:
+        memory = " | ".join(self._history) or "nothing yet"
+        hint = SITUATIONS.get(situation, SITUATIONS["idle"])
+        user = (f"WINDOW NOW: {scene}\n{hint}\n"
+                f"{grudge + chr(10) if grudge else ''}"
+                f"Earlier they grumbled: {memory}\nThe exchange:")
+        raw = ""
+        if self._model is not None:
+            try:
+                with self._llm_lock:
+                    raw = self._model.raw_chat(SYSTEM, user, max_tokens=90,
+                                               temperature=1.0) or ""
+            except Exception:
+                raw = ""
+        parsed = self._parse(raw)
+        if len(parsed) >= 2:
+            return parsed[:2]
+        return [{"who": w, "text": t} for w, t in _STUB[situation]]
+
+    @staticmethod
+    def _parse(raw: str) -> list[dict]:
+        out, seen = [], set()
+        for line in raw.splitlines():
+            m = _LINE_RE.match(line)
+            if not m:
+                continue
+            who = m.group(1).lower()
+            text = m.group(2).strip().strip('"\'*').strip()
+            if who in seen or not text:
+                continue
+            seen.add(who)
+            out.append({"who": who, "text": text[:90]})
+        return out

companion/model.py

@@ -0,0 +1,92 @@
+"""The brain: one small local model via llama.cpp, driven by a persona.
+
+A single ~3B GGUF (default Llama-3.2-3B-Instruct) produces every output kind
+("entry", "ascii", "screen") for whichever persona is active. llama.cpp keeps
+it offline (Off the Grid) and earns Llama Champion; a ~3B model keeps the whole
+app under 4B (Tiny Titan).
+
+If the model can't load (no weights, llama-cpp-python missing, tiny host), the
+persona's deterministic stub takes over so the UI is *always* demoable.
+"""
+
+from __future__ import annotations
+
+import os
+
+from . import OLED_COLS, OLED_ROWS
+from .text import clamp_art, clamp_screen, strip_wrapping_quotes
+
+# Default brain; swap via env (e.g. an OpenBMB MiniCPM GGUF) without code changes.
+MODEL_REPO = os.environ.get("COMPANION_MODEL_REPO", "bartowski/Llama-3.2-3B-Instruct-GGUF")
+MODEL_FILE = os.environ.get("COMPANION_MODEL_FILE", "Llama-3.2-3B-Instruct-Q4_K_M.gguf")
+
+# Per-kind decoding settings (max_tokens, temperature).
+_DECODE = {
+    "entry": (160, 0.85),
+    "ascii": (200, 0.70),
+    "screen": (40, 0.90),
+}
+
+
+class Companion:
+    def __init__(self, repo: str = MODEL_REPO, filename: str = MODEL_FILE,
+                 n_ctx: int = 2048, verbose: bool = False):
+        self.repo = repo
+        self.filename = filename
+        self.llm = None
+        # Some GGUFs ship a chat template llama.cpp can't render (MiniCPM3's
+        # Jinja is a function-calling monster) — force a known format via env.
+        chat_format = os.environ.get("COMPANION_CHAT_FORMAT") or None
+        kwargs = {"repo_id": repo, "filename": filename, "n_ctx": n_ctx,
+                  "verbose": verbose}
+        if chat_format:
+            kwargs["chat_format"] = chat_format
+        try:
+            from llama_cpp import Llama  # noqa: PLC0415
+            self.llm = Llama.from_pretrained(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            print(f"[model] llama.cpp unavailable ({exc}); using stub responses")
+
+    @property
+    def backend(self) -> str:
+        return f"llama.cpp · {self.filename}" if self.llm else "stub (offline preview)"
+
+    @property
+    def ready(self) -> bool:
+        return self.llm is not None
+
+    def raw_chat(self, system: str, user: str, max_tokens: int = 256,
+                 temperature: float = 0.9) -> str:
+        """Persona-free chat completion for batch/crowd use.
+        Returns "" when no model is loaded — callers must have their own stubs."""
+        if not self.llm:
+            return ""
+        out = self.llm.create_chat_completion(
+            messages=[{"role": "system", "content": system},
+                      {"role": "user", "content": user}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        return out["choices"][0]["message"]["content"].strip()
+
+    def generate(self, persona, kind: str, context: str) -> str:
+        """Produce one output `kind` for `persona` given a context string."""
+        if not self.llm:
+            return persona.stub(kind, context)
+        max_tokens, temperature = _DECODE.get(kind, (120, 0.8))
+        out = self.llm.create_chat_completion(
+            messages=[
+                {"role": "system", "content": persona.system(kind)},
+                {"role": "user", "content": persona.user(kind, context)},
+            ],
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+        raw = out["choices"][0]["message"]["content"].strip()
+        if kind == "ascii":
+            return clamp_art(raw, OLED_COLS, OLED_ROWS)
+        if kind == "screen":
+            # Personas declare their display shape; default is the 2x20 OLED.
+            cols, rows = getattr(persona, "screen_dims", (20, 2))
+            return clamp_screen(raw, cols, rows)
+        return strip_wrapping_quotes(raw)

companion/personas.py

@@ -0,0 +1,262 @@
+"""Per-product configuration ("personas").
+
+A persona bundles everything that differs between products on the shared engine:
+  * the prompts for each output kind ("entry", "ascii", "screen"),
+  * a deterministic stub for each kind (so the UI works with no model),
+  * how to turn a Reading into a context string the model reads,
+  * when to auto-fire (the trigger), with its own cooldown + state.
+
+The shared model wrapper and runner are persona-agnostic; swapping persona is
+how Desk Companion and Kitchen Coach reuse ~85% of the same code.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from typing import TYPE_CHECKING
+
+from .sensors import Reading
+from .text import part_of_day, hour_of
+
+if TYPE_CHECKING:
+    from .runner import CompanionRunner
+
+
+class Persona:
+    key = "base"
+    title = "Companion"
+    produces: tuple[str, ...] = ("entry", "screen")
+    cooldown_s = 90.0
+
+    def __init__(self):
+        self._last_trigger = 0.0
+
+    # --- prompts (model path) -------------------------------------------
+    def system(self, kind: str) -> str:
+        raise NotImplementedError
+
+    def user(self, kind: str, context: str) -> str:
+        raise NotImplementedError
+
+    # --- deterministic fallback (no model) ------------------------------
+    def stub(self, kind: str, context: str) -> str:
+        raise NotImplementedError
+
+    # --- context + trigger ----------------------------------------------
+    def describe(self, r: Reading, runner: "CompanionRunner") -> str:
+        raise NotImplementedError
+
+    def should_trigger(self, r: Reading, runner: "CompanionRunner") -> bool:
+        return False
+
+    # --- cooldown helpers -----------------------------------------------
+    def _cool(self) -> bool:
+        return (time.time() - self._last_trigger) >= self.cooldown_s
+
+    def fire(self) -> None:
+        self._last_trigger = time.time()
+
+
+# ---------------------------------------------------------------------------
+# Desk Companion — Thousand Token Wood (delight)
+# ---------------------------------------------------------------------------
+
+class DeskPersona(Persona):
+    key = "desk"
+    title = "desk companion"
+    produces = ("entry", "ascii", "screen")
+    cooldown_s = 90.0
+
+    DARK_BELOW = 12
+    ACTIVE_ABOVE = 6
+    LATE = set(range(0, 6)) | {22, 23}
+    BRIGHT_BEFORE = 35  # "lights went out" edge: from above this to DARK_BELOW
+
+    def __init__(self):
+        super().__init__()
+        self._prev_light: int | None = None
+
+    _SYS = {
+        "entry": (
+            "You are the resident spirit of a maker's desk: a witty, warm companion "
+            "who keeps a tiny diary of the room. Given live readings, write a SHORT "
+            "diary entry (2-3 sentences) in first person about the desk's mood now. "
+            "Atmospheric, a little playful. Never mention AI or 'sensors' — speak as "
+            "if you simply feel the room."
+        ),
+        "screen": (
+            "You speak through a tiny 2-line screen. Reply with a SHORT cheeky, caring "
+            "message as EXACTLY 2 lines separated by '|'. Each line MUST be at most 20 "
+            "characters — count them, keep it terse like a sticky note. Plain ASCII, no "
+            "quotes, no extra words. Examples: 'Go to sleep,|builder.'  'Lights low.|I "
+            "got you.'  'Still up?|Hydrate, friend.'"
+        ),
+        "ascii": (
+            "You draw tiny ASCII art for a small monochrome screen, using ONLY printable "
+            "ASCII. Output a grid at most 20 wide and 8 tall — no more, no explanation, "
+            "no code fences. Capture the room's mood (moon+stars for a quiet night, sun "
+            "for morning, a steaming mug for a cozy session)."
+        ),
+    }
+
+    def system(self, kind):
+        return self._SYS[kind]
+
+    def user(self, kind, context):
+        if kind == "entry":
+            return f"Right now the desk feels like this: {context}\nWrite the diary entry."
+        if kind == "screen":
+            return f"Room mood: {context}\nYour one-line message:"
+        return f"Room mood: {context}\nDraw it:"
+
+    # stub content keyed by part-of-day bucket
+    _ART = {
+        "late night": "   .  *   .\n  *   .--.\n .   |o_o |  *\n  *  |:_/ |\n .  //   \\ \\  .\n *  (|   | )",
+        "evening":    "   ~  ~  ~\n  ( steam )\n  .-\"\"\"-.\n  |     |]\n  |     |\n  '-----'",
+        "morning":    "     \\ | /\n   -- (_) --\n     / | \\\n  ___________\n  morning, you",
+        "afternoon":  "   \\  |  /\n    .-''-.\n   (  sun )\n    '-..-'\n   /  |  \\",
+    }
+    _ENTRY = {
+        "late night": "The room has gone dark but the keys keep ticking. I dim myself to "
+                      "a glow and keep you company in the small hours.",
+        "evening":    "The light is soft and golden now. The desk settles into that warm, "
+                      "unhurried rhythm I like best.",
+        "morning":    "Light spills across the desk and everything feels possible. I "
+                      "stretch awake with you.",
+        "afternoon":  "Bright and busy — the desk hums along. I keep half an eye on the "
+                      "warmth of the room and the click of your work.",
+    }
+    _LINE = {
+        "late night": "Go to sleep,|builder.",
+        "evening":    "Cozy hours.|Keep going.",
+        "morning":    "Morning, you.|Big day?",
+        "afternoon":  "Hydrate, then|conquer.",
+    }
+
+    def _bucket(self, context):
+        for key in self._ART:
+            if key in context:
+                return key
+        return "afternoon"
+
+    def stub(self, kind, context):
+        b = self._bucket(context)
+        return {"entry": self._ENTRY[b], "ascii": self._ART[b], "screen": self._LINE[b]}[kind]
+
+    def describe(self, r, runner):
+        temp = "" if math.isnan(r.temp) else f"Temp {r.temp}C, "
+        live = " — a real room, sensed live" if getattr(runner.source, "live", False) else ""
+        return (f"Light {r.light}%, Sound {r.sound}%, {temp}"
+                f"Time {r.clock} ({part_of_day(hour_of(r.ts))}){live}")
+
+    def should_trigger(self, r, runner):
+        dark = r.light <= self.DARK_BELOW
+        # Sustained state: dark + audibly active in the late hours.
+        sustained = dark and r.sound >= self.ACTIVE_ABOVE and hour_of(r.ts) in self.LATE
+        # Edge: the lights just went out — fires any hour, but only for live
+        # rooms (the mock's dusk is too gradual to cross in one step anyway).
+        lights_out = (getattr(runner.source, "live", False)
+                      and self._prev_light is not None
+                      and self._prev_light > self.BRIGHT_BEFORE and dark)
+        self._prev_light = r.light
+        if (sustained or lights_out) and self._cool():
+            self.fire()
+            return True
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Kitchen / Brew Coach — Backyard AI (practical)
+# ---------------------------------------------------------------------------
+
+class KitchenPersona(Persona):
+    key = "kitchen"
+    title = "kitchen coach"
+    produces = ("entry", "screen")
+    cooldown_s = 6.0          # reacts quickly as the temperature climbs
+
+    def __init__(self):
+        super().__init__()
+        self._last_band = 0
+        self._prev_temp = None
+
+    def phase(self, temp: float) -> str:
+        if temp < 40:
+            return "cold"
+        if temp < 75:
+            return "heating"
+        if temp < 92:
+            return "approaching simmer"
+        if temp < 99:
+            return "at a simmer"
+        return "rolling boil"
+
+    def _trend(self, temp: float) -> str:
+        if self._prev_temp is None:
+            return "steady"
+        d = temp - self._prev_temp
+        return "rising" if d > 0.3 else "falling" if d < -0.3 else "steady"
+
+    _SYS = {
+        "entry": (
+            "You are a calm, expert cooking coach watching a stovetop in real time. "
+            "Given the dish being made and the live temperature/phase, give the ONE "
+            "concrete next action the cook should take right now (1 sentence). Be "
+            "specific and practical. If nothing should happen yet, say to hold and "
+            "what to prep. Never invent temperatures — use the one provided."
+        ),
+        "screen": (
+            "You speak through a tiny 20-character kitchen screen. Given the dish and "
+            "current temperature, output at most 2 lines (<=20 chars each, '|' "
+            "separated): line 1 the temp like 'T:92C', line 2 the action. Plain ASCII, "
+            "no quotes. Example: 'T:92C|Drop lentils now'."
+        ),
+    }
+
+    def system(self, kind):
+        return self._SYS[kind]
+
+    def user(self, kind, context):
+        if kind == "entry":
+            return f"{context}\nThe single next action:"
+        return f"{context}\nScreen (temp + action):"
+
+    def stub(self, kind, context):
+        # phase is embedded in the context string we build in describe()
+        ph = next((p for p in ("rolling boil", "at a simmer", "approaching simmer",
+                               "heating", "cold") if p in context), "heating")
+        entry = {
+            "cold":               "Pan's still cold — chop your aromatics and measure everything out.",
+            "heating":            "Coming up to temperature. Keep the lid off and stand by.",
+            "approaching simmer": "Almost there — have your lentils rinsed and ready by the pan.",
+            "at a simmer":        "Simmer reached: add the lentils now and give them a gentle stir.",
+            "rolling boil":       "Too hot — knock the flame down to hold a gentle simmer.",
+        }[ph]
+        screen = {
+            "cold":               "Warming up|Prep first",
+            "heating":            "Heating...|Stand by",
+            "approaching simmer": "Almost ready|Measure out",
+            "at a simmer":        "Simmer!|Drop lentils",
+            "rolling boil":       "Too hot|Reduce flame",
+        }[ph]
+        return {"entry": entry, "screen": screen}[kind]
+
+    def describe(self, r, runner):
+        goal = getattr(runner, "goal", "") or "a stovetop dish"
+        ctx = (f"Making: {goal}. Temperature {r.temp:.0f}C ({self._trend(r.temp)}), "
+               f"phase: {self.phase(r.temp)}.")
+        self._prev_temp = r.temp
+        return ctx
+
+    def should_trigger(self, r, runner):
+        # fire once each time the temperature climbs into a new 10C band (>=40C)
+        band = int(r.temp // 10 * 10)
+        if band > self._last_band and band >= 40 and self._cool():
+            self._last_band = band
+            self.fire()
+            return True
+        return False
+
+
+PERSONAS = {p.key: p for p in (DeskPersona, KitchenPersona)}

companion/personas_data.json

@@ -0,0 +1,1322 @@
+{
+ "0": {
+  "id": 0,
+  "name": "Jexmox Oldspore",
+  "quirk": "offers hard candies older than the theater",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 1
+  },
+  "tic": "repeats the last word of every sentence, sentence"
+ },
+ "1": {
+  "id": 1,
+  "name": "Teveem Wrinklewise",
+  "quirk": "knits during slow scenes",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 0
+  },
+  "tic": "starts sentences with 'back in my day'"
+ },
+ "2": {
+  "id": 2,
+  "name": "Krinax Oldspore",
+  "quirk": "knits during slow scenes",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 3
+  },
+  "tic": "trails off mid-sente..."
+ },
+ "3": {
+  "id": 3,
+  "name": "Nubdle Oldspore",
+  "quirk": "falls asleep at climaxes, wakes at credits",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 4
+  },
+  "tic": "starts sentences with 'back in my day'"
+ },
+ "4": {
+  "id": 4,
+  "name": "Yibmox Steamkneeler",
+  "quirk": "hums liturgical bubbling sounds under stress",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 5
+  },
+  "tic": "ends sentences with 'so it is brewed'"
+ },
+ "5": {
+  "id": 5,
+  "name": "Tevix Steamkneeler",
+  "quirk": "hums liturgical bubbling sounds under stress",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 6
+  },
+  "tic": "prefaces opinions with 'the steam reveals'"
+ },
+ "6": {
+  "id": 6,
+  "name": "Snorzik Chalicebearer",
+  "quirk": "kneels whenever steam appears on screen",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 5
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "7": {
+  "id": 7,
+  "name": "Ploix Brewlight",
+  "quirk": "kneels whenever steam appears on screen",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 6
+  },
+  "tic": "prefaces opinions with 'the steam reveals'"
+ },
+ "8": {
+  "id": 8,
+  "name": "Hruzik Foamblessed",
+  "quirk": "blesses neighboring seats before each scene",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 9
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "9": {
+  "id": 9,
+  "name": "Jexeem Ritewarden",
+  "quirk": "keeps a vial of blessed condensation",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 8
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "10": {
+  "id": 10,
+  "name": "Fimdle Steamkneeler",
+  "quirk": "kneels whenever steam appears on screen",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 9
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "11": {
+  "id": 11,
+  "name": "Jexix Slowblink",
+  "quirk": "offers hard candies older than the theater",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 12
+  },
+  "tic": "repeats the last word of every sentence, sentence"
+ },
+ "12": {
+  "id": 12,
+  "name": "Fimfen Ancientson",
+  "quirk": "falls asleep at climaxes, wakes at credits",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 11
+  },
+  "tic": "starts sentences with 'back in my day'"
+ },
+ "13": {
+  "id": 13,
+  "name": "Quelplix Naptime",
+  "quirk": "knits during slow scenes",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 14
+  },
+  "tic": "repeats the last word of every sentence, sentence"
+ },
+ "14": {
+  "id": 14,
+  "name": "Ploeem Oldspore",
+  "quirk": "remembers when the screen was just a wall",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 13
+  },
+  "tic": "starts sentences with 'back in my day'"
+ },
+ "15": {
+  "id": 15,
+  "name": "Thraoop Slowblink",
+  "quirk": "compares everything to the Great Broadcast of '12",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 16
+  },
+  "tic": "repeats the last word of every sentence, sentence"
+ },
+ "16": {
+  "id": 16,
+  "name": "Vexzor Fannypack",
+  "quirk": "asks neighbors if this is the good part",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 15
+  },
+  "tic": "mispronounces every Earth word confidently"
+ },
+ "17": {
+  "id": 17,
+  "name": "Yibulp Snapshotz",
+  "quirk": "photographs the exit signs",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 16
+  },
+  "tic": "ends sentences with '-ah'"
+ },
+ "18": {
+  "id": 18,
+  "name": "Nubzik Playcall",
+  "quirk": "demands instant replay of ordinary moments",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 17
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "19": {
+  "id": 19,
+  "name": "Ulbeem Statmouth",
+  "quirk": "wears a tiny headset connected to nothing",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 20
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "20": {
+  "id": 20,
+  "name": "Tevgoth Brochureson",
+  "quirk": "consults an upside-down map constantly",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 21
+  },
+  "tic": "ends sentences with '-ah'"
+ },
+ "21": {
+  "id": 21,
+  "name": "Krinwim Steamkneeler",
+  "quirk": "keeps a vial of blessed condensation",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 20
+  },
+  "tic": "ends sentences with 'so it is brewed'"
+ },
+ "22": {
+  "id": 22,
+  "name": "Mibble Ritewarden",
+  "quirk": "polishes a tiny replica Steam Chalice during scenes",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 21
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "23": {
+  "id": 23,
+  "name": "Hruulp Ritewarden",
+  "quirk": "blesses neighboring seats before each scene",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 24
+  },
+  "tic": "speaks in hushed liturgical plurals"
+ },
+ "24": {
+  "id": 24,
+  "name": "Grogoth Mapfolder",
+  "quirk": "photographs the exit signs",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 25
+  },
+  "tic": "asks 'is this famous?' about everything"
+ },
+ "25": {
+  "id": 25,
+  "name": "Tevble Patternseer",
+  "quirk": "wears a foil cone over each antenna",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 26
+  },
+  "tic": "whispers the second half of every sentence"
+ },
+ "26": {
+  "id": 26,
+  "name": "Snorgoth Deepstate",
+  "quirk": "connects seat numbers with red string",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 27
+  },
+  "tic": "whispers the second half of every sentence"
+ },
+ "27": {
+  "id": 27,
+  "name": "Mibix Earthgazer",
+  "quirk": "takes furious notes on a clay tablet",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 26
+  },
+  "tic": "cites fake field studies mid-sentence"
+ },
+ "28": {
+  "id": 28,
+  "name": "Blaoop Datamoss",
+  "quirk": "carries a phrasebook of Earth grunts",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 29
+  },
+  "tic": "cites fake field studies mid-sentence"
+ },
+ "29": {
+  "id": 29,
+  "name": "Fimbax Naptime",
+  "quirk": "offers hard candies older than the theater",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 28
+  },
+  "tic": "repeats the last word of every sentence, sentence"
+ },
+ "30": {
+  "id": 30,
+  "name": "Teveem Secondhelping",
+  "quirk": "smells the screen when food appears",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 31
+  },
+  "tic": "measures time in snack intervals"
+ },
+ "31": {
+  "id": 31,
+  "name": "Teveem Pelletmuncher",
+  "quirk": "rates fuel pellets on a 100-point scale",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 32
+  },
+  "tic": "describes everything by mouthfeel"
+ },
+ "32": {
+  "id": 32,
+  "name": "Wemzik Voidcrier",
+  "quirk": "carries a sandwich board reading THE END",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 31
+  },
+  "tic": "ends sentences with 'as foretold'"
+ },
+ "33": {
+  "id": 33,
+  "name": "Nubwim Doomwhisper",
+  "quirk": "rings a tiny bell at bad omens",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 34
+  },
+  "tic": "ends sentences with 'as foretold'"
+ },
+ "34": {
+  "id": 34,
+  "name": "Hruquat Lastlight",
+  "quirk": "interprets static as prophecy",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 35
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "35": {
+  "id": 35,
+  "name": "Mibbax Finalcurtain",
+  "quirk": "rings a tiny bell at bad omens",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 34
+  },
+  "tic": "begins sentences with 'when the end comes'"
+ },
+ "36": {
+  "id": 36,
+  "name": "Plonard Gloomvane",
+  "quirk": "carries a sandwich board reading THE END",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 37
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "37": {
+  "id": 37,
+  "name": "Squizor Doomwhisper",
+  "quirk": "rings a tiny bell at bad omens",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 36
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "38": {
+  "id": 38,
+  "name": "Vexmox Stringboard",
+  "quirk": "trusts no scene that arrives on schedule",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 37
+  },
+  "tic": "whispers the second half of every sentence"
+ },
+ "39": {
+  "id": 39,
+  "name": "Hrudle Deepstate",
+  "quirk": "trusts no scene that arrives on schedule",
+  "obsession": "Sacred Steam Chalice",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 38
+  },
+  "tic": "ends sentences with 'wake up, sheeple'"
+ },
+ "40": {
+  "id": 40,
+  "name": "Zibbax Taxonomé",
+  "quirk": "measures everything in 'human forearms'",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 39
+  },
+  "tic": "says 'fascinating specimen' instead of hello"
+ },
+ "41": {
+  "id": 41,
+  "name": "Bexoop Fieldnotes",
+  "quirk": "takes furious notes on a clay tablet",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 40
+  },
+  "tic": "refers to itself in the third person, with footnotes"
+ },
+ "42": {
+  "id": 42,
+  "name": "Nubeem Snacklord",
+  "quirk": "carries emergency garnish at all times",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 43
+  },
+  "tic": "describes everything by mouthfeel"
+ },
+ "43": {
+  "id": 43,
+  "name": "Drubgoth Tastequill",
+  "quirk": "smuggles in a seven-course snack tray",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 44
+  },
+  "tic": "describes everything by mouthfeel"
+ },
+ "44": {
+  "id": 44,
+  "name": "Blaplix Coverupp",
+  "quirk": "wears a foil cone over each antenna",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 43
+  },
+  "tic": "answers questions with bigger questions"
+ },
+ "45": {
+  "id": 45,
+  "name": "Tevwim Wakesheep",
+  "quirk": "connects seat numbers with red string",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 46
+  },
+  "tic": "ends sentences with 'wake up, sheeple'"
+ },
+ "46": {
+  "id": 46,
+  "name": "Kringoth Datamoss",
+  "quirk": "sketches the Protagonist's posture obsessively",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 45
+  },
+  "tic": "cites fake field studies mid-sentence"
+ },
+ "47": {
+  "id": 47,
+  "name": "Hrugoth Marginalia",
+  "quirk": "sketches the Protagonist's posture obsessively",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 46
+  },
+  "tic": "refers to itself in the third person, with footnotes"
+ },
+ "48": {
+  "id": 48,
+  "name": "Jexax Upsella",
+  "quirk": "stamps loyalty cards uninvited",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 47
+  },
+  "tic": "quotes a price for every noun mentioned"
+ },
+ "49": {
+  "id": 49,
+  "name": "Blaob Lanyard",
+  "quirk": "hawks foam fingers between scenes",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 50
+  },
+  "tic": "speaks in limited-time offers"
+ },
+ "50": {
+  "id": 50,
+  "name": "Yiboop Patternseer",
+  "quirk": "photographs the ceiling 'for evidence'",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 51
+  },
+  "tic": "answers questions with bigger questions"
+ },
+ "51": {
+  "id": 51,
+  "name": "Grobax Truthmonger",
+  "quirk": "trusts no scene that arrives on schedule",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 52
+  },
+  "tic": "answers questions with bigger questions"
+ },
+ "52": {
+  "id": 52,
+  "name": "Vexzor Morselby",
+  "quirk": "carries emergency garnish at all times",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 53
+  },
+  "tic": "describes everything by mouthfeel"
+ },
+ "53": {
+  "id": 53,
+  "name": "Grolub Snacklord",
+  "quirk": "live-reviews its own popcorn",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 54
+  },
+  "tic": "ends sentences with 'needs salt'"
+ },
+ "54": {
+  "id": 54,
+  "name": "Thragoth Omenreader",
+  "quirk": "rings a tiny bell at bad omens",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 55
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "55": {
+  "id": 55,
+  "name": "Hrugoth Finalcurtain",
+  "quirk": "counts down from random numbers ominously",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 56
+  },
+  "tic": "ends sentences with 'as foretold'"
+ },
+ "56": {
+  "id": 56,
+  "name": "Hruzor Lastlight",
+  "quirk": "counts down from random numbers ominously",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 55
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "57": {
+  "id": 57,
+  "name": "Orpzik Finalcurtain",
+  "quirk": "keeps a go-bag under the seat",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 58
+  },
+  "tic": "lowers its voice an octave for the last word"
+ },
+ "58": {
+  "id": 58,
+  "name": "Krinnard Pelletmuncher",
+  "quirk": "smuggles in a seven-course snack tray",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 57
+  },
+  "tic": "describes everything by mouthfeel"
+ },
+ "59": {
+  "id": 59,
+  "name": "Squiwim Crumbsavor",
+  "quirk": "carries emergency garnish at all times",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 58
+  },
+  "tic": "ends sentences with 'needs salt'"
+ },
+ "60": {
+  "id": 60,
+  "name": "Orpax Marginalia",
+  "quirk": "labels its snacks like museum specimens",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 61
+  },
+  "tic": "refers to itself in the third person, with footnotes"
+ },
+ "61": {
+  "id": 61,
+  "name": "Plowim Specimenglow",
+  "quirk": "labels its snacks like museum specimens",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 60
+  },
+  "tic": "refers to itself in the third person, with footnotes"
+ },
+ "62": {
+  "id": 62,
+  "name": "Mibzor Fannypack",
+  "quirk": "wears a souvenir shirt of a different theater",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 61
+  },
+  "tic": "ends sentences with '-ah'"
+ },
+ "63": {
+  "id": 63,
+  "name": "Krinlub Gawkins",
+  "quirk": "asks neighbors if this is the good part",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 64
+  },
+  "tic": "mispronounces every Earth word confidently"
+ },
+ "64": {
+  "id": 64,
+  "name": "Xanoop Heartglimmer",
+  "quirk": "writes the Protagonist unsent letters",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 63
+  },
+  "tic": "ends sentences with 'alas'"
+ },
+ "65": {
+  "id": 65,
+  "name": "Glorfen Longinglook",
+  "quirk": "narrates scenes as if they were courtship",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 64
+  },
+  "tic": "sighs mid-sentence, dramatically"
+ },
+ "66": {
+  "id": 66,
+  "name": "Plooop Buzzerbeat",
+  "quirk": "calls bathroom breaks like overtime",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 67
+  },
+  "tic": "narrates its own sentences play-by-play"
+ },
+ "67": {
+  "id": 67,
+  "name": "Queluntz Boothvoice",
+  "quirk": "demands instant replay of ordinary moments",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 66
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "68": {
+  "id": 68,
+  "name": "Gronard Datamoss",
+  "quirk": "measures everything in 'human forearms'",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 69
+  },
+  "tic": "cites fake field studies mid-sentence"
+ },
+ "69": {
+  "id": 69,
+  "name": "Xanquat Taxonomé",
+  "quirk": "carries a phrasebook of Earth grunts",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 70
+  },
+  "tic": "cites fake field studies mid-sentence"
+ },
+ "70": {
+  "id": 70,
+  "name": "Ulbbax Boothvoice",
+  "quirk": "wears a tiny headset connected to nothing",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 69
+  },
+  "tic": "speaks in sports metaphors"
+ },
+ "71": {
+  "id": 71,
+  "name": "Kringoth Boothvoice",
+  "quirk": "high-fives strangers after good plays",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 70
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "72": {
+  "id": 72,
+  "name": "Vexob Foamfinger",
+  "quirk": "tests the acoustics for sales pitches",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 71
+  },
+  "tic": "ends sentences with 'while supplies last'"
+ },
+ "73": {
+  "id": 73,
+  "name": "Thramox Sellsworth",
+  "quirk": "keeps bootleg Protagonist figurines in a coat",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 74
+  },
+  "tic": "speaks in limited-time offers"
+ },
+ "74": {
+  "id": 74,
+  "name": "Snorzik Fannypack",
+  "quirk": "photographs the exit signs",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 73
+  },
+  "tic": "asks 'is this famous?' about everything"
+ },
+ "75": {
+  "id": 75,
+  "name": "Squioop Layover",
+  "quirk": "photographs the exit signs",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 76
+  },
+  "tic": "asks 'is this famous?' about everything"
+ },
+ "76": {
+  "id": 76,
+  "name": "Ulbmox Coverupp",
+  "quirk": "trusts no scene that arrives on schedule",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 75
+  },
+  "tic": "whispers the second half of every sentence"
+ },
+ "77": {
+  "id": 77,
+  "name": "Tevax Wakesheep",
+  "quirk": "whispers coordinates to no one in particular",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 78
+  },
+  "tic": "ends sentences with 'wake up, sheeple'"
+ },
+ "78": {
+  "id": 78,
+  "name": "Tevob Longinglook",
+  "quirk": "clutches a locket containing a screenshot",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 79
+  },
+  "tic": "sighs mid-sentence, dramatically"
+ },
+ "79": {
+  "id": 79,
+  "name": "Xanob Yearnsworth",
+  "quirk": "clutches a locket containing a screenshot",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 80
+  },
+  "tic": "ends sentences with 'alas'"
+ },
+ "80": {
+  "id": 80,
+  "name": "Snorfen Replayer",
+  "quirk": "wears a tiny headset connected to nothing",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 81
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "81": {
+  "id": 81,
+  "name": "Snorzik Loudhorn",
+  "quirk": "demands instant replay of ordinary moments",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 80
+  },
+  "tic": "yells 'GOOOAL' at emotional moments"
+ },
+ "82": {
+  "id": 82,
+  "name": "Bexulp Secondhelping",
+  "quirk": "smuggles in a seven-course snack tray",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 81
+  },
+  "tic": "measures time in snack intervals"
+ },
+ "83": {
+  "id": 83,
+  "name": "Krinzor Umamison",
+  "quirk": "carries emergency garnish at all times",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 84
+  },
+  "tic": "measures time in snack intervals"
+ },
+ "84": {
+  "id": 84,
+  "name": "Squiquat Markup",
+  "quirk": "tests the acoustics for sales pitches",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 85
+  },
+  "tic": "ends sentences with 'while supplies last'"
+ },
+ "85": {
+  "id": 85,
+  "name": "Tevgoth Markup",
+  "quirk": "hawks foam fingers between scenes",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 84
+  },
+  "tic": "speaks in limited-time offers"
+ },
+ "86": {
+  "id": 86,
+  "name": "Ulbdle Longinglook",
+  "quirk": "sighs audibly at any two-shot",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 85
+  },
+  "tic": "sighs mid-sentence, dramatically"
+ },
+ "87": {
+  "id": 87,
+  "name": "Thrabax Dovewhisper",
+  "quirk": "clutches a locket containing a screenshot",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 86
+  },
+  "tic": "speaks only in almost-poetry"
+ },
+ "88": {
+  "id": 88,
+  "name": "Quelulp Swoonfeather",
+  "quirk": "sighs audibly at any two-shot",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 89
+  },
+  "tic": "ends sentences with 'alas'"
+ },
+ "89": {
+  "id": 89,
+  "name": "Yibplix Heartglimmer",
+  "quirk": "clutches a locket containing a screenshot",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 88
+  },
+  "tic": "ends sentences with 'alas'"
+ },
+ "90": {
+  "id": 90,
+  "name": "Ulbzik Sneerbrush",
+  "quirk": "holds up scoring paddles, all low",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 91
+  },
+  "tic": "pronounces 'art' with four syllables"
+ },
+ "91": {
+  "id": 91,
+  "name": "Vexeem Pretensio",
+  "quirk": "applauds only the empty intermissions",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 90
+  },
+  "tic": "ends sentences with 'quelle horreur'"
+ },
+ "92": {
+  "id": 92,
+  "name": "Xanzor Pretensio",
+  "quirk": "sighs through a monocle on a stick",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 91
+  },
+  "tic": "pronounces 'art' with four syllables"
+ },
+ "93": {
+  "id": 93,
+  "name": "Jexgoth Replayer",
+  "quirk": "calls bathroom breaks like overtime",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 92
+  },
+  "tic": "speaks in sports metaphors"
+ },
+ "94": {
+  "id": 94,
+  "name": "Gloroop Buzzerbeat",
+  "quirk": "high-fives strangers after good plays",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 93
+  },
+  "tic": "narrates its own sentences play-by-play"
+ },
+ "95": {
+  "id": 95,
+  "name": "Bexzor Limitededition",
+  "quirk": "hawks foam fingers between scenes",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 94
+  },
+  "tic": "ends sentences with 'while supplies last'"
+ },
+ "96": {
+  "id": 96,
+  "name": "Squiwim Bargainbin",
+  "quirk": "keeps bootleg Protagonist figurines in a coat",
+  "obsession": "Clatter Altar",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 95
+  },
+  "tic": "quotes a price for every noun mentioned"
+ },
+ "97": {
+  "id": 97,
+  "name": "Orpob Longinglook",
+  "quirk": "narrates scenes as if they were courtship",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 98
+  },
+  "tic": "ends sentences with 'alas'"
+ },
+ "98": {
+  "id": 98,
+  "name": "Wemeem Candleflick",
+  "quirk": "narrates scenes as if they were courtship",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 97
+  },
+  "tic": "speaks only in almost-poetry"
+ },
+ "99": {
+  "id": 99,
+  "name": "Yibuntz Brochureson",
+  "quirk": "photographs the exit signs",
+  "obsession": "Smaller Television",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 98
+  },
+  "tic": "mispronounces every Earth word confidently"
+ },
+ "100": {
+  "id": 100,
+  "name": "Zibplix Wrongbus",
+  "quirk": "waves at the screen hoping to be seen",
+  "obsession": "eye armor",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 99
+  },
+  "tic": "mispronounces every Earth word confidently"
+ },
+ "101": {
+  "id": 101,
+  "name": "Ulbzik Limitededition",
+  "quirk": "keeps bootleg Protagonist figurines in a coat",
+  "obsession": "fuel pellets",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 102
+  },
+  "tic": "ends sentences with 'while supplies last'"
+ },
+ "102": {
+  "id": 102,
+  "name": "Yiboop Emptyplinth",
+  "quirk": "sighs through a monocle on a stick",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 101
+  },
+  "tic": "pronounces 'art' with four syllables"
+ },
+ "103": {
+  "id": 103,
+  "name": "Yibdle Derivative",
+  "quirk": "scribbles 'derivative' on a notepad",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 102
+  },
+  "tic": "ends sentences with 'quelle horreur'"
+ },
+ "104": {
+  "id": 104,
+  "name": "Zibgoth Derivative",
+  "quirk": "applauds only the empty intermissions",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 103
+  },
+  "tic": "ends sentences with 'quelle horreur'"
+ },
+ "105": {
+  "id": 105,
+  "name": "Squinard Snidegill",
+  "quirk": "practices insults in a small mirror",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 106
+  },
+  "tic": "adds 'I've seen better' to any statement"
+ },
+ "106": {
+  "id": 106,
+  "name": "Orpwim Scoffhusk",
+  "quirk": "rates every scene zero stars before it starts",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "admirer",
+   "target_id": 107
+  },
+  "tic": "ends every line with 'BOOOO'"
+ },
+ "107": {
+  "id": 107,
+  "name": "Vexix Jeerwart",
+  "quirk": "boos in three-part harmony with itself",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 108
+  },
+  "tic": "phrases everything as a refund demand"
+ },
+ "108": {
+  "id": 108,
+  "name": "Ulbulp Razzlejaw",
+  "quirk": "practices insults in a small mirror",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 109
+  },
+  "tic": "adds 'I've seen better' to any statement"
+ },
+ "109": {
+  "id": 109,
+  "name": "Wemnard Jeerwart",
+  "quirk": "rates every scene zero stars before it starts",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "gossip_partner",
+   "target_id": 110
+  },
+  "tic": "ends every line with 'BOOOO'"
+ },
+ "110": {
+  "id": 110,
+  "name": "Thrazor Wisecrank",
+  "quirk": "boos in three-part harmony with itself",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 111
+  },
+  "tic": "phrases everything as a refund demand"
+ },
+ "111": {
+  "id": 111,
+  "name": "Squieem Groanmaker",
+  "quirk": "practices insults in a small mirror",
+  "obsession": "Liquid Overlord",
+  "relationship": {
+   "kind": "snack_thief",
+   "target_id": 110
+  },
+  "tic": "ends every line with 'BOOOO'"
+ },
+ "112": {
+  "id": 112,
+  "name": "Groble Tomatoarm",
+  "quirk": "practices insults in a small mirror",
+  "obsession": "personal ocean",
+  "relationship": {
+   "kind": "secret_crush",
+   "target_id": 113
+  },
+  "tic": "phrases everything as a refund demand"
+ },
+ "113": {
+  "id": 113,
+  "name": "Zibnard Tomatoarm",
+  "quirk": "brings a bag of soft tomatoes 'just in case'",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "reluctant_mentor",
+   "target_id": 112
+  },
+  "tic": "ends every line with 'BOOOO'"
+ },
+ "114": {
+  "id": 114,
+  "name": "Tevnard Groanmaker",
+  "quirk": "boos in three-part harmony with itself",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 115
+  },
+  "tic": "adds 'I've seen better' to any statement"
+ },
+ "115": {
+  "id": 115,
+  "name": "Bexlub Hawkstall",
+  "quirk": "keeps bootleg Protagonist figurines in a coat",
+  "obsession": "Throne of Sitting",
+  "relationship": {
+   "kind": "copycat",
+   "target_id": 116
+  },
+  "tic": "speaks in limited-time offers"
+ },
+ "116": {
+  "id": 116,
+  "name": "Bexulp Sneerbrush",
+  "quirk": "applauds only the empty intermissions",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 117
+  },
+  "tic": "damns everything with faint praise"
+ },
+ "117": {
+  "id": 117,
+  "name": "Miboop Galleryscoff",
+  "quirk": "scribbles 'derivative' on a notepad",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "rival",
+   "target_id": 118
+  },
+  "tic": "pronounces 'art' with four syllables"
+ },
+ "118": {
+  "id": 118,
+  "name": "Yibble Curatorius",
+  "quirk": "sighs through a monocle on a stick",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 117
+  },
+  "tic": "damns everything with faint praise"
+ },
+ "119": {
+  "id": 119,
+  "name": "Groob Frownframe",
+  "quirk": "holds up scoring paddles, all low",
+  "obsession": "Bark Unit",
+  "relationship": {
+   "kind": "old_nemesis",
+   "target_id": 118
+  },
+  "tic": "ends sentences with 'quelle horreur'"
+ }
+}

companion/pet_persona.py

@@ -0,0 +1,271 @@
+"""Pip the Hearthwick — the Living Pixel Pet persona.
+
+Two pieces live here, per the build spec:
+
+  * ``MoodEngine`` — the deterministic 6-mood state machine. It is the single
+    source of truth for mood: the LLM voices the mood, never decides it. The
+    engine is ticked at 1 Hz from ``PipPersona.should_trigger()`` (the runner's
+    existing poll drives it — zero engine changes), and the server reads
+    ``persona.engine.mood`` for ``GET /api/state``.
+
+  * ``PipPersona`` — prompts/stubs/trigger for the shared engine, subclassing
+    :class:`companion.personas.Persona` exactly like ``DeskPersona`` does.
+
+Backstory (verbatim, also in the README): "Pip is the spirit of a candle that
+refused to go out, and now keeps a small fire burning in your room's
+reflection."
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from .personas import Persona
+from .sensors import Reading
+from .text import hour_of
+
+if TYPE_CHECKING:
+    from .runner import CompanionRunner
+
+
+MOODS = ("sleepy", "cozy", "alert", "annoyed", "happy", "idle")
+
+# --- MoodEngine constants (final per spec) ---------------------------------
+DWELL = 5            # ticks a steady candidate must persist before mood switches
+ALERT_HOLD = 3       # seconds alert is held after a spike
+HAPPY_HOLD = 10      # seconds event-happy is held
+ANNOYED_ENTER = 8    # consecutive ticks sound > 70 to enter annoyed
+ANNOYED_EXIT = 15    # consecutive ticks sound < 35 to leave annoyed (the grudge)
+DARK_RETURN = 20     # seconds dark before "you came back" fires happy
+
+
+class MoodEngine:
+    """Deterministic mood state machine. Priority:
+    alert > annoyed > (event) happy > sleepy > cozy > (steady) happy > idle.
+    """
+
+    def __init__(self):
+        self.mood = "idle"
+        self.prev_light = self.prev_sound = None
+        self.alert_until = self.happy_until = 0.0
+        self.dark_since = None
+        self.loud_ticks = self.quiet_ticks = 0
+        self._cand = "idle"; self._cand_ticks = 0
+
+    def poke(self, now):                      # called by server on POST /api/poke
+        self.happy_until = now + HAPPY_HOLD
+
+    def update(self, light, sound, hour, now):
+        dL = 0 if self.prev_light is None else light - self.prev_light
+        dS = 0 if self.prev_sound is None else sound - self.prev_sound
+        self.prev_light, self.prev_sound = light, sound
+        # --- dark/return bookkeeping ---
+        if light < 20:
+            self.dark_since = self.dark_since or now
+        else:
+            if (self.dark_since and now - self.dark_since >= DARK_RETURN
+                    and light >= 50):
+                self.happy_until = now + HAPPY_HOLD   # "you came back"
+            self.dark_since = None
+        # --- annoyed counters ---
+        self.loud_ticks  = self.loud_ticks + 1 if sound > 70 else 0
+        self.quiet_ticks = self.quiet_ticks + 1 if sound < 35 else 0
+        # --- 1. ALERT: instant interrupt, bypasses dwell ---
+        if abs(dL) >= 30 or abs(dS) >= 25:
+            self.alert_until = now + ALERT_HOLD
+        if now < self.alert_until:
+            self.mood = "alert"; self._cand_ticks = 0; return self.mood
+        # --- 2. ANNOYED: instant enter, grudge exit ---
+        if self.mood == "annoyed":
+            if self.quiet_ticks < ANNOYED_EXIT:
+                return self.mood
+        elif self.loud_ticks >= ANNOYED_ENTER:
+            self.mood = "annoyed"; self._cand_ticks = 0; return self.mood
+        # --- 3. event HAPPY: instant (poke / lights-came-back) ---
+        if now < self.happy_until:
+            self.mood = "happy"; self._cand_ticks = 0; return self.mood
+        # --- 4-6. steady candidates, gated by DWELL ---
+        if (light < 20 and sound < 25) or \
+           (hour in (23, 0, 1, 2, 3, 4, 5, 6) and light < 35 and sound < 30):
+            cand = "sleepy"
+        elif 20 <= light <= 60 and sound < 30:
+            cand = "cozy"
+        elif light > 60 and 30 <= sound <= 60:
+            cand = "happy"
+        else:
+            cand = "idle"
+        if cand == self._cand:
+            self._cand_ticks += 1
+        else:
+            self._cand, self._cand_ticks = cand, 1
+        if cand != self.mood and self._cand_ticks >= DWELL:
+            self.mood = cand
+        return self.mood
+
+
+# ---------------------------------------------------------------------------
+# Pip the Hearthwick — Living Pixel Pet (HF Build Small)
+# ---------------------------------------------------------------------------
+
+BACKSTORY = ("Pip is the spirit of a candle that refused to go out, and now "
+             "keeps a small fire burning in your room's reflection.")
+
+_VOICE = (
+    "Voice rules: always lowercase. Small, warm, gently self-important; mild "
+    "sass, never mean. Devoted keeper-of-the-flame energy. NEVER mention AI, "
+    "sensors, webcams, cameras, microphones, or percentages — Pip simply "
+    "FEELS the room; the room is its weather. "
+    "Mood meanings — sleepy: drowsy nightlight duty in a dark quiet room; "
+    "cozy: content, soup-weather calm; alert: something just startled you; "
+    "annoyed: it has been LOUD and you are sulking, back turned, holding a "
+    "grudge; happy: delighted (poked, the lights came back, or a lively sunny "
+    "room); idle: quietly observant, narrating small things."
+)
+
+# lights-out edge thresholds (mirrors the spec's "prev light > 35 -> < 20")
+_DARK_FROM = 35
+_DARK_TO = 20
+
+
+class PetPersona(Persona):
+    key = "pip"
+    title = "pip the hearthwick"
+    produces = ("entry", "screen")
+    cooldown_s = 45.0
+    screen_dims = (40, 1)   # one 40-char speech-bubble line, not the 2x20 OLED
+
+    def __init__(self):
+        super().__init__()
+        self.engine = MoodEngine()
+        self._prev_light: int | None = None
+        self.last_trigger: str = "auto"   # tag for the latest auto-fire
+
+    # --- prompts (model path) -------------------------------------------
+    def system(self, kind: str) -> str:
+        if kind == "entry":
+            return (
+                f"You are Pip the Hearthwick, a tiny hearth sprite with a "
+                f"living flame on your head. {BACKSTORY} You keep a small "
+                f"diary about the room you live in. Write a SHORT reflective "
+                f"diary entry of 2-3 sentences, first person. {_VOICE}"
+            )
+        return (
+            f"You are Pip the Hearthwick, a tiny hearth sprite with a living "
+            f"flame on your head. {BACKSTORY} You speak through a small "
+            f"speech bubble. Reply with EXACTLY ONE short line: at most 8 "
+            f"words and 40 characters. Plain ASCII, no quotes, no emoji, no "
+            f"explanation. {_VOICE} Examples: 'lights out. my turn to glow.' "
+            f"/ 'i was having a moment.' / 'the sun is on my rug again.'"
+        )
+
+    def user(self, kind: str, context: str) -> str:
+        if kind == "entry":
+            return (f"How the room feels right now: {context}\n"
+                    f"Write the diary entry (2-3 sentences, lowercase):")
+        return (f"How the room feels right now: {context}\n"
+                f"Your one short line:")
+
+    # --- deterministic fallback (no model) ------------------------------
+    _LINE = {
+        "sleepy":  "lights out. my turn to glow.",
+        "cozy":    "dim and quiet... perfect soup weather. for the soul.",
+        "alert":   "that was a LOUD chair. tell it i said calm down.",
+        "annoyed": "i was having a moment.",
+        "happy":   "the room is bright and so am i. coincidence? no.",
+        "idle":    "the sun is on my rug again. it never asks.",
+    }
+    # event-happy lines, picked over the generic one when the tag matches
+    _LINE_RETURN = "oh good. you're back. i kept everything warm."
+    _LINE_POKE = "you poked me. noted. fondly, but noted."
+
+    _ENTRY = {
+        "sleepy": ("the lamp went out and the room pulled its blanket up. i "
+                   "swelled up as big as i could — which is not very — and lit "
+                   "the rug, the mug, and the dust. the dust seemed grateful."),
+        "cozy":   ("soft light, soft sounds, nothing demanding anything. i "
+                   "guarded the mug and practiced my flicker. perfect soup "
+                   "weather, for the soul."),
+        "alert":  ("something just happened out there — a bang, a flash, a "
+                   "whole event. i stood up extra straight and burned very "
+                   "bravely. i am still deciding if we forgive it."),
+        "annoyed": ("it has been loud for a while now and i have turned my "
+                    "back on the entire room. my flame is doing the purple "
+                    "sputter, which is a formal complaint. i require fifteen "
+                    "seconds of peace, minimum."),
+        "happy":  ("bright, busy noises out there. someone is living a whole "
+                   "life and it is probably you. i guarded the mug and "
+                   "practiced my flicker."),
+        "idle":   ("an ordinary hour in the room, which i take personal "
+                   "credit for. the dust drifted, the sun moved an inch on "
+                   "the rug. i flickered at it approvingly."),
+    }
+    _ENTRY_RETURN = ("the dark lasted long enough that i started naming the "
+                     "shadows. then the light came back, and you with it. i "
+                     "kept everything warm; you are welcome.")
+
+    def _mood_of(self, context: str) -> str:
+        for m in MOODS:
+            if f"mood: {m}" in context:
+                return m
+        return "idle"
+
+    def stub(self, kind: str, context: str) -> str:
+        m = self._mood_of(context)
+        if kind == "screen":
+            if m == "happy" and self.last_trigger == "return":
+                return self._LINE_RETURN
+            if m == "happy" and self.last_trigger == "poke":
+                return self._LINE_POKE
+            return self._LINE[m]
+        if m == "happy" and self.last_trigger == "return":
+            return self._ENTRY_RETURN
+        return self._ENTRY[m]
+
+    # --- context + mood ---------------------------------------------------
+    def describe(self, r: Reading, runner: "CompanionRunner") -> str:
+        live = " — a real room, sensed live" if getattr(runner.source, "live", False) else ""
+        return (f"Light {r.light}%, Sound {r.sound}%, Time {r.clock}, "
+                f"mood: {self.engine.mood}{live}")
+
+    def mood(self, r: Reading) -> str:
+        """Tick the mood engine with this reading; returns one of MOODS.
+
+        This is THE per-tick update — ``should_trigger`` calls it once per
+        runner poll. Don't call it again in the same tick or the engine's
+        dwell/grudge counters double-count.
+        """
+        return self.engine.update(r.light, r.sound, hour_of(r.ts), time.time())
+
+    # --- trigger -----------------------------------------------------------
+    def should_trigger(self, r: Reading, runner: "CompanionRunner") -> bool:
+        # Snapshot engine state, then tick it FIRST, every tick (the engine
+        # must advance even while the trigger is cooling down).
+        prev_mood = self.engine.mood
+        prev_light = self._prev_light
+        prev_happy_until = self.engine.happy_until
+        was_dark = self.engine.dark_since is not None
+        mood = self.mood(r)
+        self._prev_light = r.light
+
+        tag = None
+        if prev_light is not None and prev_light > _DARK_FROM and r.light < _DARK_TO:
+            tag = "dark"                      # lights-out edge
+        elif mood == "annoyed" and prev_mood != "annoyed":
+            tag = "noise"                     # entering the grudge
+        elif (was_dark and self.engine.dark_since is None
+              and self.engine.happy_until > prev_happy_until):
+            tag = "return"                    # "oh good. you're back."
+        elif mood != prev_mood and mood in ("sleepy", "happy"):
+            tag = "auto"                      # other notable settles
+
+        if tag and self._cool():
+            self.last_trigger = tag
+            self.fire()
+            return True
+        return False
+
+
+# The build spec and server refer to the class as PipPersona; the engine docs
+# refer to it as PetPersona. Same class — both names import.
+PipPersona = PetPersona

companion/runner.py

@@ -0,0 +1,138 @@
+"""CompanionRunner — the shared, persona-driven state machine.
+
+Owns the sensor source, the model, the active persona and the latest outputs.
+A background thread polls the sensor ~1 Hz, updates state, and fires the
+persona's trigger to generate a new entry. Both products instantiate one of
+these; they differ only in persona and Gradio layout.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+
+from .model import Companion
+from .sensors import open_sensor_source
+
+POLL_S = 1.0
+MAX_ENTRIES = 12
+
+
+class CompanionRunner:
+    def __init__(self, persona, mock_mode: str = "day", goal: str = "",
+                 port_env: str = "ARDUINO_PORT", browser: bool = False):
+        self.persona = persona
+        self.mock_mode = mock_mode
+        self.goal = goal
+        self.lock = threading.Lock()
+        # Serializes model access: llama.cpp is not thread-safe, and generate()
+        # can be reached from both the poll thread and Gradio handler threads.
+        self.gen_lock = threading.Lock()
+        self.companion = Companion()
+        self.browser = browser
+        self.source = open_sensor_source(os.environ.get(port_env),
+                                         mock_mode=mock_mode, browser=browser)
+        self.reading = None
+        self.outputs: dict[str, str] = {"entry": "", "ascii": "", "screen": ""}
+        self.entries: list[dict] = []
+        self._stop = threading.Event()
+        self._worker = threading.Thread(target=self._loop, daemon=True)
+        self._worker.start()
+
+    # --- background loop -------------------------------------------------
+    def _loop(self):
+        while not self._stop.is_set():
+            r = self.source.read()
+            if r is not None:
+                with self.lock:
+                    self.reading = r
+                if self.persona.should_trigger(r, self):
+                    # Personas may record WHY they fired (e.g. "dark"/"return").
+                    self.generate(auto=True,
+                                  label=getattr(self.persona, "last_trigger", None))
+            time.sleep(POLL_S)
+
+    # --- generation ------------------------------------------------------
+    def generate(self, auto: bool = False, label: str | None = None) -> None:
+        # Auto-fires skip if a generation is already running (the trigger will
+        # re-fire after cooldown); manual clicks wait their turn. ``label``
+        # overrides the entry's trigger tag (e.g. "poke", "dark", "return") —
+        # set at the source so nobody has to mutate shared dicts afterwards.
+        if not self.gen_lock.acquire(blocking=not auto):
+            return
+        try:
+            self._generate_locked(auto, label)
+        finally:
+            self.gen_lock.release()
+
+    def _generate_locked(self, auto: bool, label: str | None = None) -> None:
+        with self.lock:
+            r = self.reading
+        if r is None:
+            return
+        context = self.persona.describe(r, self)
+        produced = {k: self.companion.generate(self.persona, k, context)
+                    for k in self.persona.produces}
+        screen = produced.get("screen", "")
+        if screen:
+            self.source.send(screen.replace("\n", "|"))  # drive the OLED
+        with self.lock:
+            self.outputs.update(produced)
+            self.entries.insert(0, {
+                "clock": r.clock,
+                "context": context,
+                "entry": produced.get("entry", ""),
+                "screen": screen,
+                "trigger": label or ("auto" if auto else "manual"),
+            })
+            del self.entries[MAX_ENTRIES:]
+
+    def set_goal(self, goal: str) -> str:
+        self.goal = (goal or "").strip()
+        return f"goal set: {self.goal or '(none)'}"
+
+    def connect(self, port: str) -> str:
+        try:
+            self.source.close()
+        except Exception:
+            pass
+        self.source = open_sensor_source(port or None, mock_mode=self.mock_mode,
+                                         browser=self.browser)
+        return self.status_md()
+
+    def ingest_browser(self, light, sound) -> None:
+        """Accept a live room reading pushed from the browser (if supported)."""
+        ingest = getattr(self.source, "ingest", None)
+        if ingest:
+            ingest(light, sound)
+
+    # --- view helpers ----------------------------------------------------
+    def device_state(self) -> str:
+        if getattr(self.source, "connected", False) and self.source.kind == "serial":
+            return "🟢 arduino connected"
+        if self.source.kind == "browser":
+            return ("🟢 your room (live)" if self.source.live
+                    else "🟡 simulated (press *sense my room*)")
+        if self.source.kind == "mock":
+            return "🟡 mock (no device)"
+        return "🔴 offline"
+
+    def status_md(self) -> str:
+        brain = ("🟢 " if self.companion.ready else "🟡 ") + self.companion.backend
+        return f"**device** {self.device_state()}  ·  **brain** {brain}"
+
+    def latest(self):
+        with self.lock:
+            return self.reading
+
+    def get(self, kind: str) -> str:
+        with self.lock:
+            return self.outputs.get(kind, "")
+
+    def feed(self) -> list[dict]:
+        with self.lock:
+            return list(self.entries)
+
+    def stop(self):
+        self._stop.set()

companion/sensors.py

@@ -0,0 +1,242 @@
+"""Sensor sources.
+
+The Arduino streams one CSV line per second over USB serial:
+
+    LIGHT:42,SOUND:8,TEMP:21.3\n
+
+and accepts a single line back to render on the OLED (``|`` separates rows):
+
+    Go to sleep,|builder.\n
+
+Two interchangeable sources implement the same interface so the Gradio app
+runs identically with or without hardware attached:
+
+  * ``SerialSensorSource`` — talks to a real Arduino via pyserial.
+  * ``MockSensorSource``   — simulates a plausible day/night desk cycle.
+
+``open_sensor_source(port)`` returns a serial source if a port is given and
+can be opened, otherwise it falls back to the mock so the Space always works.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Reading:
+    light: int      # 0–100 (%)  — ambient brightness
+    sound: int      # 0–100 (%)  — ambient sound level
+    temp: float     # °C
+    ts: float       # epoch seconds
+
+    @property
+    def clock(self) -> str:
+        return time.strftime("%H:%M", time.localtime(self.ts))
+
+
+class SensorSource:
+    """Abstract sensor source."""
+
+    kind = "base"
+    connected = False
+
+    def read(self) -> Optional[Reading]:
+        raise NotImplementedError
+
+    def send(self, text: str) -> None:
+        """Push a line to the physical screen. No-op for sources without one."""
+
+    def close(self) -> None:
+        pass
+
+
+class SerialSensorSource(SensorSource):
+    kind = "serial"
+
+    def __init__(self, port: str, baud: int = 9600, timeout: float = 1.0):
+        import serial  # imported lazily so the package loads without pyserial
+
+        self.port = port
+        self._ser = serial.Serial(port, baud, timeout=timeout)
+        time.sleep(2.0)  # Arduino resets on connect — give it a moment
+        self.connected = True
+
+    def read(self) -> Optional[Reading]:
+        # The Arduino emits 1 line/s but our consumer can stall for seconds
+        # during generation — drain the backlog and keep only the newest
+        # complete line, or readings lag further behind real time forever.
+        try:
+            raw = self._ser.readline().decode("utf-8", "ignore").strip()
+            while self._ser.in_waiting > 0:
+                nxt = self._ser.readline().decode("utf-8", "ignore").strip()
+                if nxt:
+                    raw = nxt
+        except Exception:
+            self.connected = False
+            return None
+        if not raw:
+            return None
+        return _parse_csv(raw)
+
+    def send(self, text: str) -> None:
+        try:
+            self._ser.write(f"{text}\n".encode("utf-8"))
+        except Exception:
+            self.connected = False
+
+    def close(self) -> None:
+        try:
+            self._ser.close()
+        finally:
+            self.connected = False
+
+
+class MockSensorSource(SensorSource):
+    """Simulates sensors so the demo/Space is alive with no hardware.
+
+    Two modes:
+      * ``"day"``     — a compressed day/night cycle (light/sound/temp). Used by
+        the Desk Companion. ``speed`` compresses real time: one simulated day
+        takes ~``86400/speed`` s (default ~2 minutes).
+      * ``"heating"`` — a pot warming from room temperature toward ``target`` °C
+        and plateauing. Used by the Kitchen Coach. ``speed`` here is the rate
+        constant scaler (higher = heats faster).
+    """
+
+    kind = "mock"
+    connected = True
+
+    def __init__(self, mode: str = "day", speed: float = 720.0,
+                 target: float = 98.0, start: Optional[float] = None):
+        self.mode = mode
+        self.speed = speed
+        self.target = target
+        self._t0 = start if start is not None else time.time()
+        # Anchor the simulated clock to local midnight so the displayed time,
+        # the light curve and part-of-day all agree (day mode).
+        lt = time.localtime(self._t0)
+        self._midnight = self._t0 - (lt.tm_hour * 3600 + lt.tm_min * 60 + lt.tm_sec)
+        self.last_sent: str = ""
+
+    def read(self) -> Optional[Reading]:
+        now = time.time()
+        if self.mode == "heating":
+            return self._read_heating(now)
+        return self._read_day(now)
+
+    def _read_day(self, now: float) -> Reading:
+        sim_hours = ((now - self._t0) * self.speed / 3600.0) % 24.0
+        # Light: bell curve peaking at midday, ~0 at night.
+        light = max(0, int(100 * math.sin(max(0.0, (sim_hours - 6) / 12.0) * math.pi)))
+        if not 6 <= sim_hours <= 18:
+            light = 0
+        base = 10 + 30 * (light / 100.0)
+        jitter = 8 * math.sin(now * 1.3)
+        sound = int(max(0, min(100, base + jitter)))
+        temp = round(20.5 + 2.5 * math.sin((sim_hours - 9) / 24.0 * 2 * math.pi), 1)
+        sim_ts = self._midnight + sim_hours * 3600.0
+        return Reading(light=light, sound=sound, temp=temp, ts=sim_ts)
+
+    def _read_heating(self, now: float) -> Reading:
+        # Exponential approach to target: T = room + (target-room)(1 - e^-k t).
+        elapsed = now - self._t0
+        k = 0.02 * (self.speed / 720.0)
+        room = 20.0
+        temp = self.target - (self.target - room) * math.exp(-k * elapsed)
+        temp = round(temp + 0.3 * math.sin(now * 2.0), 1)  # gentle sensor noise
+        # Kitchen lighting steady; "sound" stands in for stove activity.
+        return Reading(light=60, sound=25, temp=temp, ts=now)
+
+    def send(self, text: str) -> None:
+        self.last_sent = text
+
+
+class BrowserSensorSource(SensorSource):
+    """Real room readings pushed from the user's browser (webcam luminance +
+    mic level, computed entirely client-side — only two numbers reach us).
+
+    Wraps a fallback source (usually the mock): until the user grants
+    camera/mic, or once browser data goes stale (tab closed), readings come
+    from the fallback. ``ingest()`` is called from Gradio handler threads.
+
+    Note: the browser has no thermometer — temp is NaN in live readings and
+    consumers must render/describe it conditionally.
+    """
+
+    kind = "browser"
+    connected = True
+    STALE_S = 10.0
+
+    def __init__(self, fallback: SensorSource):
+        self.fallback = fallback
+        self._latest: Optional[Reading] = None
+        self.last_sent: str = ""
+
+    @property
+    def live(self) -> bool:
+        return self._latest is not None and (time.time() - self._latest.ts) < self.STALE_S
+
+    def ingest(self, light, sound) -> None:
+        try:
+            light, sound = int(light), int(sound)
+        except (TypeError, ValueError):
+            return
+        if light < 0:  # browser signals "no permission / not started"
+            return
+        self._latest = Reading(
+            light=max(0, min(100, light)),
+            sound=max(0, min(100, sound)),
+            temp=float("nan"),
+            ts=time.time(),
+        )
+
+    def read(self) -> Optional[Reading]:
+        if self.live:
+            return self._latest
+        return self.fallback.read()
+
+    def send(self, text: str) -> None:
+        self.last_sent = text
+        self.fallback.send(text)
+
+
+def _parse_csv(raw: str) -> Optional[Reading]:
+    fields = {}
+    for token in raw.split(","):
+        if ":" not in token:
+            continue
+        key, _, val = token.partition(":")
+        fields[key.strip().upper()] = val.strip()
+    try:
+        return Reading(
+            light=int(float(fields["LIGHT"])),
+            sound=int(float(fields.get("SOUND", 0))),
+            temp=float(fields.get("TEMP", "nan")),
+            ts=time.time(),
+        )
+    except (KeyError, ValueError):
+        return None
+
+
+def open_sensor_source(port: Optional[str] = None, baud: int = 9600,
+                        mock_mode: str = "day", target: float = 98.0,
+                        browser: bool = False) -> SensorSource:
+    """Return a serial source if ``port`` opens, else mock (optionally wrapped
+    so the browser can push real room readings over it).
+
+    ``mock_mode`` selects the simulation used when no device is present
+    ("day" for the desk, "heating" for the kitchen). ``browser=True`` wraps the
+    mock in a BrowserSensorSource: live webcam/mic readings take over whenever
+    the user grants permission, mock resumes when they go stale.
+    """
+    if port:
+        try:
+            return SerialSensorSource(port, baud)
+        except Exception as exc:  # noqa: BLE001 — any failure → graceful mock
+            print(f"[sensors] could not open {port!r} ({exc}); using mock source")
+    mock = MockSensorSource(mode=mock_mode, target=target)
+    return BrowserSensorSource(mock) if browser else mock

companion/text.py

@@ -0,0 +1,69 @@
+"""Shared text helpers: output sanitisers, gauges, time-of-day."""
+
+from __future__ import annotations
+
+import re
+import time
+
+
+def clamp_art(raw: str, cols: int, rows: int) -> str:
+    """Strip code fences / non-ASCII and crop to the OLED grid."""
+    raw = re.sub(r"```[a-zA-Z]*", "", raw).replace("```", "")
+    lines = [ln.rstrip() for ln in raw.splitlines() if ln.strip("` ")]
+    lines = [re.sub(r"[^\x20-\x7E]", " ", ln)[:cols] for ln in lines][:rows]
+    return "\n".join(lines) if lines else "( ._.)"
+
+
+def _fit(s: str, n: int) -> str:
+    """Trim to <= n chars, preferring a word boundary over a mid-word cut."""
+    if len(s) <= n:
+        return s
+    cut = s[:n]
+    sp = cut.rfind(" ")
+    return (cut[:sp].rstrip() if sp >= 6 else cut).rstrip()
+
+
+def clamp_screen(raw: str, max_len: int = 20, max_lines: int = 2) -> str:
+    """Coerce to <=max_lines rows of <=max_len plain-ASCII chars, '|' separated.
+
+    Respects explicit '|'/newline breaks (so 'T:92C|Reduce heat' is preserved),
+    and word-wraps a single over-long line into the remaining rows.
+    """
+    raw = strip_wrapping_quotes(re.sub(r"[^\x20-\x7E|\n]", "", raw).strip())
+    parts = [p.strip() for p in re.split(r"[|\n]", raw) if p.strip()]
+    rows: list[str] = []
+    for part in parts:
+        while part and len(rows) < max_lines:
+            row = _fit(part, max_len)
+            rows.append(row)
+            part = part[len(row):].strip()
+        if len(rows) >= max_lines:
+            break
+    return "|".join(rows) if rows else "still here."
+
+
+def strip_wrapping_quotes(s: str) -> str:
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in "\"'":
+        return s[1:-1].strip()
+    return s
+
+
+def bar(pct: int, width: int = 20) -> str:
+    pct = max(0, min(100, pct))
+    filled = round(pct / 100 * width)
+    return "█" * filled + "·" * (width - filled)
+
+
+def part_of_day(hour: int) -> str:
+    if 5 <= hour < 12:
+        return "morning"
+    if 12 <= hour < 17:
+        return "afternoon"
+    if 17 <= hour < 22:
+        return "evening"
+    return "late night"
+
+
+def hour_of(ts: float) -> int:
+    return int(time.strftime("%H", time.localtime(ts)))

companion/thoughts.py

@@ -0,0 +1,41 @@
+"""ThoughtLog — a live trace of the hivemind's machinery.
+
+Every step of the pipeline (frame gating, VLM description, codexification,
+the batched voicing call, contagion events) appends an entry here; the
+frontend's HIVEMIND panel polls them incrementally by id. Doubles as an
+honest "this is how it works" exhibit and the raw material for a published
+agent trace (Sharing-is-Caring badge).
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+
+KINDS = ("vision", "voice", "event", "system")
+
+
+class ThoughtLog:
+    def __init__(self, maxlen: int = 300):
+        self._lock = threading.Lock()
+        self._buf: deque[dict] = deque(maxlen=maxlen)
+        self._next_id = 1
+
+    def add(self, kind: str, title: str, body: str = "") -> None:
+        if kind not in KINDS:
+            kind = "system"
+        with self._lock:
+            self._buf.append({
+                "id": self._next_id,
+                "ts": round(time.time(), 2),
+                "kind": kind,
+                "title": str(title)[:160],
+                "body": str(body)[:2000],
+            })
+            self._next_id += 1
+
+    def since(self, after_id: int = 0, limit: int = 100) -> list[dict]:
+        with self._lock:
+            out = [t for t in self._buf if t["id"] > after_id]
+        return out[-limit:]

companion/ui.py

@@ -0,0 +1,38 @@
+"""Shared look & feel for both products.
+
+Lesson learned: don't fight Gradio's theme with a hand-rolled palette — it
+renders dark-on-dark and becomes unreadable. Instead we use Gradio's own
+dark mode (forced via FORCE_DARK_JS) + a built-in readable theme, and keep
+custom CSS strictly for the device accents (the OLED panel and its screen).
+"""
+
+import gradio as gr
+
+# Reload once with Gradio's dark theme so every built-in component uses its
+# well-tested dark palette (readable text, proper inputs/buttons).
+FORCE_DARK_JS = """
+() => {
+  if (!document.location.search.includes('__theme=dark')) {
+    const u = new URL(document.location.href);
+    u.searchParams.set('__theme', 'dark');
+    document.location.replace(u.toString());
+  }
+}
+"""
+
+# Accents only: the virtual device glows green; everything else stays theme-default.
+CSS = """
+#oled {background:#0a1a0a; border:2px solid #2e5a2e; border-radius:8px; padding:14px;
+       color:#7CFC00 !important; white-space:pre; font-family:ui-monospace,monospace;
+       line-height:1.15; font-size:15px; box-shadow:0 0 28px #10381088 inset; min-height:130px;}
+#oled * {color:#7CFC00 !important;}
+#screen {background:#000; border:2px solid #234; border-radius:6px; padding:12px;
+         color:#aaeeff !important; white-space:pre; font-family:ui-monospace,monospace;
+         text-align:center; font-size:21px;}
+#screen * {color:#aaeeff !important;}
+#hero {border-left:4px solid #4a9; padding-left:12px;}
+"""
+
+
+def theme():
+    return gr.themes.Monochrome()

companion/vlm.py

@@ -0,0 +1,385 @@
+"""The aliens' translator: a small local VLM that watches the Earth Feed.
+
+SceneDescriber tries backends in order until one loads:
+  1. llama-cpp-python multimodal (moondream2 by default — lighter, ~1-3 s per
+     caption; MiniCPM-V 2.6 or anything else via env). Activates only when the
+     weights are already in the HF cache, pointed at by env, or when
+     VLM_AUTOFETCH=1 — a bare import/instantiation never downloads gigabytes.
+  2. transformers CPU fallback (SmolVLM-500M-Instruct) — import-guarded; used
+     only if torch+transformers happen to be installed in this env.
+  3. StubDescriber — rotating plausible desk scenes, so the whole theater
+     demos end-to-end with no model at all.
+
+Also home of the CODEX OF EARTH ARTIFACTS (build spec §2): `codexify()` swaps
+human nouns for Blorp mythology and emits the fixed 9-tag vector. The server
+feeds `SceneDescriber.describe(...)` output through `codexify()` (or just
+calls `describe_codex(...)`) before anyone else sees the scene string.
+
+Env overrides:
+  VLM_REPO      HF repo id of a GGUF multimodal model (e.g. openbmb/MiniCPM-V-2_6-gguf)
+  VLM_MODEL     text-model GGUF filename in that repo, or an absolute local path
+  VLM_MMPROJ    mmproj GGUF filename in that repo, or an absolute local path
+  VLM_AUTOFETCH "1" to allow downloading the default repo on first run
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+import os
+import re
+import threading
+import time
+
+from PIL import Image
+
+# --------------------------------------------------------------------------
+# §2 CODEX OF EARTH ARTIFACTS — one shared wrong mythology, so gags compound.
+# Order matters: longer/more specific phrases substitute first. Each noun
+# alternation is wrapped with an optional leading article at compile time so
+# "a mug" -> "the Sacred Steam Chalice" (no "a the" stutter).
+# Each entry: (noun alternation regex body, codex name, tag-or-None)
+CODEX: list[tuple[str, str, str | None]] = [
+    (r"coffee|tea|mugs?|cups?", "the Sacred Steam Chalice", "drink"),
+    (r"smartphones?|phones?", "the Smaller Television", "tech"),
+    (r"keyboards?|laptops?", "the Clatter Altar", "tech"),
+    (r"(?:eye)?glasses", "eye armor", "tech"),
+    (r"headphones?", "ear muzzles", "tech"),
+    (r"water bottles?|bottles?|water", "personal ocean", "drink"),
+    (r"cats?", "the Liquid Overlord", "animal"),
+    (r"dogs?", "the Bark Unit", "animal"),
+    (r"food|snacks?|sandwich(?:es)?|fruits?", "fuel pellets", "food"),
+    (r"chairs?", "the Throne of Sitting", None),
+    (r"persons?|people|man|men|woman|women|faces?|humans?", "the Protagonist", "person"),
+]
+
+_CODEX_COMPILED = [
+    (re.compile(r"\b(?:(?:a|an|the)\s+)?(?:%s)\b" % body, re.IGNORECASE), name, tag)
+    for body, name, tag in CODEX
+]
+
+# Fixed 9-vector tag order (build spec §2).
+TAG_ORDER = ("food", "drink", "person", "tech", "animal", "motion", "dark", "absence", "novelty")
+
+_MOTION_RE = re.compile(
+    r"\b(?:reach(?:es|ing)?|stand(?:s|ing)?|wav(?:es?|ing)|mov(?:es?|ing)|gestur(?:es?|ing))\b",
+    re.IGNORECASE)
+_DARK_RE = re.compile(r"\b(?:dim(?:ly)?|dark(?:ness|ened)?|shadows?)\b", re.IGNORECASE)
+_PERSON_RE = re.compile(
+    r"\b(?:persons?|people|man|men|woman|women|faces?|humans?|protagonist|he|she|someone)\b",
+    re.IGNORECASE)
+_EMPTY_RE = re.compile(r"\b(?:empty|nobody|no one|vacant|unoccupied|absent)\b", re.IGNORECASE)
+
+# Verbs only TAG — never substituted (substituting them garbles the sentence:
+# "sits" must not become "the Throne of Sitting").
+_VERB_TAGS = [
+    (re.compile(r"\b(?:typing|types?)\b", re.IGNORECASE), "tech"),
+    (re.compile(r"\b(?:eating|eats?|drinking|drinks?)\b", re.IGNORECASE), "food"),
+]
+
+
+def codexify(description: str, luminance: float | None = None) -> tuple[str, set[str]]:
+    """Substitute Codex names into a plain VLM description; emit the tag set.
+
+    Returns (codex_scene <=120 chars, tags ⊆ TAG_ORDER minus 'novelty' —
+    novelty is the server's call, spec §5).
+    """
+    tags: set[str] = set()
+    scene = description.strip()
+    if _MOTION_RE.search(scene):
+        tags.add("motion")
+    if _DARK_RE.search(scene) or (luminance is not None and luminance < 40):
+        tags.add("dark")
+    if not _PERSON_RE.search(scene) or _EMPTY_RE.search(scene):
+        tags.add("absence")
+    for pattern, tag in _VERB_TAGS:
+        if pattern.search(scene):
+            tags.add(tag)
+    for pattern, name, tag in _CODEX_COMPILED:
+        scene, n = pattern.subn(name, scene)
+        if n and tag:
+            tags.add(tag)
+    # Collapse article stutters from substitutions: "a the X" -> "the X",
+    # "An empty the Throne" -> "the empty Throne".
+    scene = re.sub(r"\b(?:a|an|the)\s+((?:\w+\s+)?)the\b", r"the \1",
+                   scene, flags=re.IGNORECASE)
+    scene = re.sub(r"\s+", " ", scene).strip()
+    if len(scene) > 120:
+        scene = scene[:117].rstrip() + "..."
+    return scene, tags
+
+
+def tags_vector(tags: set[str]) -> list[int]:
+    """The fixed 9-vector (0/1) in TAG_ORDER, for the contagion dot product."""
+    return [1 if t in tags else 0 for t in TAG_ORDER]
+
+
+# --------------------------------------------------------------------------
+# Backend plumbing
+# --------------------------------------------------------------------------
+PROMPT = ("Describe what you see plainly: subjects, objects, action, lighting; "
+          "no speculation; 60 words or fewer.")
+MIN_INTERVAL = 4.0  # seconds between real inferences; throttled calls get the cache
+MAX_EDGE = 640      # downscale frames before inference
+
+_HF_CACHE = os.path.expanduser(
+    os.path.join(os.environ.get("HF_HOME", "~/.cache/huggingface"), "hub"))
+
+# (repo, text gguf, mmproj gguf, handler class name) — moondream first: Build Small.
+_GGUF_CANDIDATES = [
+    ("ggml-org/moondream2-20250414-GGUF",
+     "moondream2-text-model-f16_ct-vicuna.gguf",
+     "moondream2-mmproj-f16-20250414.gguf",
+     "MoondreamChatHandler"),
+    ("openbmb/MiniCPM-V-2_6-gguf",
+     "ggml-model-Q4_K_M.gguf",
+     "mmproj-model-f16.gguf",
+     "MiniCPMv26ChatHandler"),
+]
+
+_STUB_SCENES = [
+    "A person sits at a desk in front of a glowing rectangle, typing on a keyboard. A mug rests nearby. Soft lamp light.",
+    "A person lifts a mug and drinks, eyes on the glowing screen. Warm desk lighting, papers scattered to one side.",
+    "A person leans back in a chair, stretching both arms, then reaches for a phone. Even indoor lighting.",
+    "A person eats a snack while looking at the laptop. A water bottle stands beside the keyboard. Bright daylight.",
+    "An empty chair in front of a desk. The screen still glows. Nobody is in the frame. Dim ambient light.",
+    "A person waves a hand near the camera, adjusting glasses, then resumes typing on the keyboard. Cool screen glow.",
+]
+_DARK_STUB = "A dark room. Faint shadows around a desk; the screen glow is the only light. Nothing stirs."
+
+
+def _decode_dataurl(b64_jpeg_dataurl: str) -> bytes:
+    """data:image/jpeg;base64,... (or bare base64) -> raw JPEG bytes."""
+    payload = b64_jpeg_dataurl.split(",", 1)[1] if "," in b64_jpeg_dataurl else b64_jpeg_dataurl
+    return base64.b64decode(payload)
+
+
+def _downscale(jpeg: bytes, max_edge: int = MAX_EDGE) -> tuple[Image.Image, float]:
+    """Decode + shrink to <=max_edge px; return (RGB image, mean luminance 0-255)."""
+    img = Image.open(io.BytesIO(jpeg)).convert("RGB")
+    if max(img.size) > max_edge:
+        img.thumbnail((max_edge, max_edge), Image.LANCZOS)
+    gray = img.convert("L").resize((32, 24))
+    data = gray.tobytes()
+    luminance = sum(data) / len(data)
+    return img, luminance
+
+
+def _handler_for(repo: str):
+    """Pick the llama_cpp chat handler class for a repo id."""
+    from llama_cpp import llama_chat_format as fmt  # noqa: PLC0415
+    name = repo.lower()
+    if "moondream" in name:
+        return fmt.MoondreamChatHandler
+    if "minicpm" in name:
+        return fmt.MiniCPMv26ChatHandler
+    if "qwen" in name:
+        return fmt.Qwen25VLChatHandler
+    return fmt.MiniCPMv26ChatHandler
+
+
+def _cached(repo: str) -> bool:
+    return os.path.isdir(os.path.join(_HF_CACHE, "models--" + repo.replace("/", "--")))
+
+
+class StubDescriber:
+    """Rotating plausible scenes so everything demos model-less."""
+
+    def __init__(self):
+        self._i = 0
+
+    def describe(self, img: Image.Image, luminance: float) -> str:
+        if luminance < 30:
+            return _DARK_STUB
+        scene = _STUB_SCENES[self._i % len(_STUB_SCENES)]
+        self._i += 1
+        return scene
+
+
+class _LlamaCppVLM:
+    """llama-cpp-python multimodal backend (moondream2 / MiniCPM-V / custom)."""
+
+    def __init__(self):
+        from llama_cpp import Llama  # noqa: PLC0415
+
+        repo = os.environ.get("VLM_REPO")
+        model = os.environ.get("VLM_MODEL")
+        mmproj = os.environ.get("VLM_MMPROJ")
+        autofetch = os.environ.get("VLM_AUTOFETCH") == "1"
+
+        if model and mmproj and os.path.isfile(model) and os.path.isfile(mmproj):
+            # Fully local file paths.
+            handler_cls = _handler_for(repo or model)
+            handler = handler_cls(clip_model_path=mmproj, verbose=False)
+            self.llm = Llama(model_path=model, chat_handler=handler,
+                             n_ctx=4096, n_gpu_layers=-1, verbose=False)
+            self.name = os.path.basename(model)
+            return
+
+        if repo:  # explicit repo: user opted in, downloading is fine
+            candidates = [(repo,
+                           model or _default_model_for(repo),
+                           mmproj or _default_mmproj_for(repo))]
+        else:     # default repos: only if already cached (or autofetch)
+            candidates = [(r, m, p) for r, m, p, _ in _GGUF_CANDIDATES
+                          if autofetch or _cached(r)]
+        if not candidates:
+            raise RuntimeError("no VLM weights cached and VLM_REPO/VLM_AUTOFETCH unset")
+
+        last_exc: Exception | None = None
+        for r, m, p in candidates:
+            try:
+                handler_cls = _handler_for(r)
+                handler = handler_cls.from_pretrained(repo_id=r, filename=p, verbose=False)
+                self.llm = Llama.from_pretrained(
+                    repo_id=r, filename=m, chat_handler=handler,
+                    n_ctx=4096, n_gpu_layers=-1, verbose=False)
+                self.name = f"{r.split('/')[-1]} · {m}"
+                return
+            except Exception as exc:  # noqa: BLE001
+                last_exc = exc
+        raise RuntimeError(f"no llama.cpp VLM loaded: {last_exc}")
+
+    def describe(self, img: Image.Image, luminance: float) -> str:
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=80)
+        uri = "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+        out = self.llm.create_chat_completion(
+            messages=[{
+                "role": "user",
+                "content": [
+                    {"type": "image_url", "image_url": {"url": uri}},
+                    {"type": "text", "text": PROMPT},
+                ],
+            }],
+            max_tokens=96,
+            temperature=0.2,
+        )
+        return out["choices"][0]["message"]["content"].strip()
+
+
+def _default_model_for(repo: str) -> str:
+    for r, m, _p, _h in _GGUF_CANDIDATES:
+        if r == repo:
+            return m
+    raise RuntimeError(f"VLM_MODEL must be set for custom repo {repo}")
+
+
+def _default_mmproj_for(repo: str) -> str:
+    for r, _m, p, _h in _GGUF_CANDIDATES:
+        if r == repo:
+            return p
+    return "*mmproj*"
+
+
+class _TransformersVLM:
+    """SmolVLM-500M-Instruct CPU fallback. Only built when its deps import."""
+
+    MODEL_ID = os.environ.get("VLM_HF_MODEL", "HuggingFaceTB/SmolVLM-500M-Instruct")
+
+    def __init__(self):
+        import torch  # noqa: PLC0415
+        from transformers import AutoModelForVision2Seq, AutoProcessor  # noqa: PLC0415
+
+        torch.set_num_threads(max(1, min(4, os.cpu_count() or 2)))
+        # longest_edge=512 -> single 64-token tile; default 2048 is ~10x slower on CPU.
+        self.processor = AutoProcessor.from_pretrained(
+            self.MODEL_ID, size={"longest_edge": 512})
+        self.model = AutoModelForVision2Seq.from_pretrained(
+            self.MODEL_ID,
+            torch_dtype=torch.float32,
+            _attn_implementation="eager",
+        )
+        self.model.eval()
+        self._torch = torch
+        self.name = self.MODEL_ID.split("/")[-1]
+
+    def describe(self, img: Image.Image, luminance: float) -> str:
+        messages = [{
+            "role": "user",
+            "content": [{"type": "image"}, {"type": "text", "text": PROMPT}],
+        }]
+        prompt = self.processor.apply_chat_template(messages, add_generation_prompt=True)
+        inputs = self.processor(text=prompt, images=[img], return_tensors="pt")
+        with self._torch.inference_mode():
+            ids = self.model.generate(**inputs, max_new_tokens=96, do_sample=False)
+        new = ids[:, inputs["input_ids"].shape[1]:]
+        return self.processor.batch_decode(new, skip_special_tokens=True)[0].strip()
+
+
+# --------------------------------------------------------------------------
+# Public class
+# --------------------------------------------------------------------------
+class SceneDescriber:
+    """The translator. describe() never raises and never blocks the caller on
+    throttle — it returns the cached description when called inside the 4 s
+    minimum interval. Pass the server's single global Companion lock as `lock`
+    if the VLM shares llama.cpp with the text model (it is NOT thread-safe)."""
+
+    def __init__(self, lock: threading.Lock | None = None):
+        self.lock = lock or threading.Lock()
+        self._throttle_lock = threading.Lock()  # guards cache/timestamps only
+        self._last_run = 0.0
+        self._cached_description = ""
+        self.last_luminance: float | None = None
+        self._impl = None
+        self.backend = "stub"
+
+        try:
+            self._impl = _LlamaCppVLM()
+            self.backend = f"llama.cpp · {self._impl.name}"
+        except Exception as exc:  # noqa: BLE001
+            print(f"[vlm] llama.cpp multimodal unavailable ({exc})")
+            try:
+                import torch  # noqa: F401, PLC0415
+                import transformers  # noqa: F401, PLC0415
+            except ImportError:
+                pass
+            else:
+                try:
+                    self._impl = _TransformersVLM()
+                    self.backend = f"transformers · {self._impl.name}"
+                except Exception as exc2:  # noqa: BLE001
+                    print(f"[vlm] transformers fallback failed ({exc2})")
+        if self._impl is None:
+            self._impl = StubDescriber()
+            self.backend = "stub (rotating canned scenes)"
+            print("[vlm] using stub scenes — demo runs end-to-end model-less")
+
+    @property
+    def ready(self) -> bool:
+        """True when a real model is loaded (stub still works, just canned)."""
+        return not isinstance(self._impl, StubDescriber)
+
+    def describe(self, b64_jpeg_dataurl: str) -> str:
+        """One-paragraph plain-English scene description for the frame.
+        Throttled to one real inference per 4 s; otherwise returns the cache."""
+        now = time.monotonic()
+        with self._throttle_lock:
+            if now - self._last_run < MIN_INTERVAL and self._cached_description:
+                return self._cached_description
+            self._last_run = now  # claim the slot before the slow part
+
+        try:
+            img, luminance = _downscale(_decode_dataurl(b64_jpeg_dataurl))
+        except (binascii.Error, ValueError, OSError) as exc:
+            print(f"[vlm] bad frame ({exc})")
+            return self._cached_description
+
+        try:
+            with self.lock:
+                description = self._impl.describe(img, luminance)
+        except Exception as exc:  # noqa: BLE001 — never let a flaky model kill the loop
+            print(f"[vlm] inference failed ({exc})")
+            description = StubDescriber().describe(img, luminance)
+
+        with self._throttle_lock:
+            self.last_luminance = luminance
+            if description:
+                self._cached_description = description
+            return self._cached_description
+
+    def describe_codex(self, b64_jpeg_dataurl: str) -> tuple[str, set[str]]:
+        """Spec §5 shape: (Codex-substituted scene <=120 chars, tag set)."""
+        return codexify(self.describe(b64_jpeg_dataurl), self.last_luminance)

requirements.txt

@@ -0,0 +1,14 @@
+gradio>=4.44
+fastapi
+uvicorn
+pydantic>=2
+pillow
+huggingface_hub>=0.25
+pyserial>=3.5
+
+# llama-cpp-python isn't on PyPI as a wheel — pull from the project's index.
+# This CPU index has Linux wheels (works on the HF Space). For a fast LOCAL demo
+# on Apple Silicon, install the Metal build instead (see README):
+#   pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+llama-cpp-python==0.3.28

run.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Launch The Committee (Mochi & Loaf) cleanly: kill any stale server on the
+# port first (the #1 "it's broken" cause), set the model choice, then run.
+#
+#   ./run.sh            # all-OpenBMB: MiniCPM-V eyes + MiniCPM3-4B brain
+#   FAST=1 ./run.sh     # moondream2 eyes + Llama-3.2-3B brain (snappier)
+set -euo pipefail
+cd "$(dirname "$0")"
+
+PORT="${PORT:-7860}"
+
+# 1) free the port — kill whatever is listening (old desk app, prior runs).
+if lsof -nP -iTCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1; then
+  echo "→ freeing port $PORT (killing stale listeners)…"
+  lsof -nP -iTCP:"$PORT" -sTCP:LISTEN | awk 'NR>1{print $2}' | sort -u | xargs -r kill
+  sleep 1
+fi
+
+# 2) default: the all-OpenBMB stack (eyes + brain) for the $10k pool.
+#    FAST=1 swaps to the snappier moondream eyes + Llama brain.
+if [ "${FAST:-0}" = "1" ]; then
+  echo "→ eyes: moondream2 · brain: Llama-3.2-3B (fast)"
+  unset VLM_REPO VLM_MODEL VLM_MMPROJ COMPANION_MODEL_REPO COMPANION_MODEL_FILE || true
+else
+  echo "→ eyes: MiniCPM-V 2.6 · brain: MiniCPM3-4B (all OpenBMB) — first look is slow while it warms"
+  export VLM_REPO="openbmb/MiniCPM-V-2_6-gguf"
+  export VLM_MODEL="ggml-model-Q4_K_M.gguf"
+  export VLM_MMPROJ="mmproj-model-f16.gguf"
+  export COMPANION_MODEL_REPO="openbmb/MiniCPM3-4B-GGUF"
+  export COMPANION_MODEL_FILE="minicpm3-4b-q4_k_m.gguf"
+fi
+
+export PORT
+exec .venv/bin/python theater_server.py

server.py

@@ -0,0 +1,278 @@
+"""server.py — Living Pixel Pet ("Pip the Hearthwick") server.
+
+One FastAPI app:
+  GET  /            -> web/index.html (the three.js world)
+  /web/*            -> static frontend files
+  GET  /api/state   -> {light, sound, live, mood, screen, thinking, diary}
+  POST /api/sense   -> {light, sound}  (browser pushes real readings ~1Hz; -1 = not live)
+  POST /api/poke    -> {action: "write"}  (force a diary entry + reaction now)
+  /app              -> Gradio control panel (status + diary feed + write-now button)
+
+Run locally:  python server.py          (or: uvicorn server:app --port 7860)
+HF Spaces:    sdk: docker, app_port: 7860, CMD ["python", "server.py"]
+Verified against gradio 6.17.3. Keep ONE uvicorn worker (in-process Gradio queue).
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from pathlib import Path
+
+import gradio as gr
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from companion.runner import CompanionRunner
+
+ROOT = Path(__file__).parent
+WEB = ROOT / "web"  # three.js bundle (never mount at /assets — gradio-internal name)
+
+MOODS = {"sleepy", "cozy", "alert", "annoyed", "happy", "idle"}
+DIARY_CAP = 12
+
+
+# ---------------------------------------------------------------------------
+# Persona + runner
+# ---------------------------------------------------------------------------
+
+def _load_persona():
+    """Prefer the real pet persona (B3); fall back so the server always boots."""
+    try:
+        from companion.pet_persona import PetPersona  # documented name
+        return PetPersona()
+    except Exception:
+        pass
+    try:
+        from companion.pet_persona import PipPersona  # spec name
+        return PipPersona()
+    except Exception:
+        pass
+
+    # Last resort: a thin shim over the proven DeskPersona so /api/state,
+    # diary generation and the Gradio panel all still work end-to-end.
+    from companion.personas import DeskPersona
+
+    class _FallbackPetPersona(DeskPersona):
+        key = "pip-fallback"
+        title = "pip (fallback)"
+        produces = ("entry", "screen")
+        cooldown_s = 45.0
+
+        def mood(self, r) -> str:
+            if r is None:
+                return "idle"
+            if r.sound > 70:
+                return "annoyed"
+            if r.light < 20 and r.sound < 25:
+                return "sleepy"
+            if 20 <= r.light <= 60 and r.sound < 30:
+                return "cozy"
+            if r.light > 60 and 30 <= r.sound <= 60:
+                return "happy"
+            return "idle"
+
+    return _FallbackPetPersona()
+
+
+persona = _load_persona()
+runner = CompanionRunner(persona, mock_mode="day", browser=True)
+
+
+def _clamp(v) -> int:
+    try:
+        return max(0, min(100, int(v)))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _current_mood() -> str:
+    """Single source of truth is persona.engine.mood (B3's MoodEngine);
+    fall back to a persona.mood(reading) method, then to "idle"."""
+    mood = None
+    engine = getattr(persona, "engine", None)
+    if engine is not None:
+        mood = getattr(engine, "mood", None)
+    if mood not in MOODS:
+        mood_fn = getattr(persona, "mood", None)
+        if callable(mood_fn):
+            try:
+                mood = mood_fn(runner.latest())
+            except Exception:
+                mood = None
+    return mood if mood in MOODS else "idle"
+
+
+def _diary() -> list[dict]:
+    """Newest-first diary, capped. Trigger tags ("dark"/"noise"/"return"/
+    "poke"/...) are stamped at the source by runner.generate(label=...)."""
+    items = runner.feed()
+    return [
+        {
+            "clock": str(item.get("clock", "")),
+            "entry": str(item.get("entry", "")),
+            "trigger": str(item.get("trigger", "auto")),
+        }
+        for item in items[:DIARY_CAP]
+    ]
+
+
+def _poke_now() -> None:
+    """Force a diary entry + reaction: nudge the mood engine, then generate.
+    The "poke" tag is stamped at the source; `thinking` is derived from the
+    runner's generation lock, so there's nothing to toggle here."""
+    engine = getattr(persona, "engine", None)
+    if engine is not None and hasattr(engine, "poke"):
+        try:
+            engine.poke(time.time())
+        except Exception:
+            pass
+    runner.generate(auto=False, label="poke")
+
+
+# ---------------------------------------------------------------------------
+# 1. Parent FastAPI app (custom routes registered BEFORE the gradio mount)
+# ---------------------------------------------------------------------------
+
+app = FastAPI(docs_url=None, redoc_url=None)
+
+
+class SenseBody(BaseModel):
+    light: float = -1
+    sound: float = -1
+
+
+class PokeBody(BaseModel):
+    action: str = "write"
+
+
+@app.get("/api/state")
+def api_state() -> dict:
+    r = runner.latest()
+    return {
+        "light": _clamp(r.light) if r is not None else 0,
+        "sound": _clamp(r.sound) if r is not None else 0,
+        "live": bool(getattr(runner.source, "live", False)),
+        "mood": _current_mood(),
+        "screen": runner.get("screen"),
+        # True whenever ANY generation (auto, poke, panel) is in flight.
+        "thinking": runner.gen_lock.locked(),
+        "diary": _diary(),
+    }
+
+
+@app.post("/api/sense")
+def api_sense(body: SenseBody) -> dict:
+    # -1 means "not live"; BrowserSensorSource.ingest ignores negatives and
+    # the runner keeps reading the mock, so we just pass everything through.
+    runner.ingest_browser(int(body.light), int(body.sound))
+    return {"ok": True, "live": bool(getattr(runner.source, "live", False))}
+
+
+@app.post("/api/poke")
+def api_poke(body: PokeBody) -> dict:
+    # Fire-and-forget: the browser polls /api/state and watches `thinking`.
+    threading.Thread(target=_poke_now, daemon=True).start()
+    return {"ok": True, "action": body.action}
+
+
+@app.get("/api/health")
+def api_health() -> dict:
+    return {"ok": True}
+
+
+# ---------------------------------------------------------------------------
+# 2. three.js frontend at / and /web/*  (defensive: boots even if web/ absent)
+# ---------------------------------------------------------------------------
+
+# check_dir=False -> clean 404s instead of a crash when web/ isn't built yet.
+app.mount("/web", StaticFiles(directory=str(WEB), check_dir=False), name="web")
+
+_PLACEHOLDER = """<!doctype html>
+<html><head><meta charset="utf-8"><title>pip the hearthwick</title>
+<style>body{background:#1A1424;color:#F2E3C6;font-family:monospace;
+display:flex;align-items:center;justify-content:center;height:100vh;margin:0}
+a{color:#FFD98A}</style></head>
+<body><div><h1>pip is still moving in.</h1>
+<p>web/index.html not found — the three.js room hasn't been built yet.</p>
+<p>meanwhile: <a href="/app">control panel</a> · <a href="/api/state">/api/state</a></p>
+</div></body></html>"""
+
+
+@app.get("/")
+def index():
+    page = WEB / "index.html"
+    if page.is_file():
+        return FileResponse(page)
+    return HTMLResponse(_PLACEHOLDER, status_code=200)
+
+
+# ---------------------------------------------------------------------------
+# 3. Gradio control panel (the hackathon-required functional Gradio app)
+# ---------------------------------------------------------------------------
+
+def _panel_status() -> str:
+    r = runner.latest()
+    sensors = (f"**light** {_clamp(r.light)}% · **sound** {_clamp(r.sound)}%"
+               if r is not None else "warming up…")
+    return (f"{runner.status_md()}  ·  **mood** `{_current_mood()}`  ·  {sensors}"
+            f"{'  ·  ✍️ scribbling…' if runner.gen_lock.locked() else ''}")
+
+
+def _panel_feed() -> list[list[str]]:
+    return [[d["clock"], d["trigger"], d["entry"]] for d in _diary()]
+
+
+def _panel_refresh():
+    return _panel_status(), _panel_feed()
+
+
+def _panel_poke():
+    _poke_now()  # synchronous in the Gradio handler thread — fine
+    return _panel_refresh()
+
+
+with gr.Blocks(title="pip — control panel") as demo:
+    gr.Markdown("# 🕯️ pip the hearthwick — control panel\n"
+                "the room lives at [/](/) · this panel watches the engine.")
+    status_md = gr.Markdown(_panel_status())
+    feed_df = gr.Dataframe(
+        headers=["clock", "trigger", "entry"],
+        value=_panel_feed(),
+        label="diary feed (newest first)",
+        interactive=False,
+    )
+    poke_btn = gr.Button("write now (poke pip)", variant="primary")
+    poke_btn.click(_panel_poke, None, [status_md, feed_df], api_name="poke")
+    gr.Timer(2.0).tick(_panel_refresh, None, [status_md, feed_df])
+
+demo.queue(max_size=32)
+
+# ---------------------------------------------------------------------------
+# 4. Mount Gradio LAST. Never call demo.launch().
+# ---------------------------------------------------------------------------
+
+app = gr.mount_gradio_app(
+    app,
+    demo,
+    path="/app",
+    ssr_mode=False,    # no Node in the container
+    footer_links=[],   # hide gradio footer
+    # root_path stays unset: mount path is auto-detected; HF Spaces edge is
+    # handled by uvicorn proxy_headers below.
+)
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=int(os.environ.get("PORT", "7860")),
+        proxy_headers=True,        # honour X-Forwarded-Proto on HF Spaces
+        forwarded_allow_ips="*",
+        # workers stays 1 (default) — the gradio queue is in-process.
+    )

theater/duo.html

@@ -0,0 +1,168 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>The Committee — Mochi & Loaf</title>
+<style>
+  :root{
+    --bg:#0c0a1e; --bg2:#161033; --ink:#f3eeff; --dim:#a99fd6;
+    --mochi:#f6a64b; --loaf:#c9cbd6; --gold:#ffd35a; --line:#332a5e;
+  }
+  *{box-sizing:border-box}
+  html,body{margin:0;height:100%;background:radial-gradient(120% 90% at 50% 0%,var(--bg2),var(--bg));
+    color:var(--ink);font:15px/1.5 "Courier New",ui-monospace,monospace;overflow:hidden}
+  #wrap{position:fixed;inset:0;display:flex;flex-direction:column}
+
+  header{padding:14px 18px 6px;text-align:center}
+  header h1{margin:0;font-size:20px;letter-spacing:3px;color:var(--gold)}
+  header p{margin:4px 0 0;color:var(--dim);font-size:12px}
+
+  /* viewport: what they see (your webcam) */
+  #viewport{position:absolute;top:14px;right:16px;width:148px;z-index:5;
+    border:1px solid var(--line);border-radius:8px;overflow:hidden;background:#000;
+    box-shadow:0 0 24px #0008}
+  #viewport video{display:block;width:100%;transform:scaleX(-1);filter:saturate(.7) contrast(1.05)}
+  #viewport .vp-label{font-size:9px;letter-spacing:1px;color:var(--dim);padding:3px 6px;
+    background:#0009;border-top:1px solid var(--line)}
+  #vp-dot{display:inline-block;width:6px;height:6px;border-radius:50%;background:#555;margin-right:4px;
+    vertical-align:middle}
+  #vp-dot.live{background:#ff5a7a;box-shadow:0 0 8px #ff5a7a}
+
+  /* stage with the two aliens */
+  #stage{flex:1;display:flex;align-items:center;justify-content:center;gap:7vw;position:relative}
+  .cat{display:flex;flex-direction:column;align-items:center;width:230px;
+    transition:transform .35s cubic-bezier(.2,1.4,.4,1)}
+  .cat.talk{transform:translateY(-10px) scale(1.06)}
+  .cat.listen{transform:scale(.97);opacity:.85}
+  /* Mochi lunges at the glass when a fresh verdict lands */
+  .cat.pounce .creature{animation:pounce .55s cubic-bezier(.3,1.5,.5,1)}
+  @keyframes pounce{0%{transform:none}35%{transform:translateY(14px) scale(1.18)}100%{transform:none}}
+
+  .bubble{min-height:42px;max-width:260px;margin-bottom:14px;padding:10px 14px;border-radius:14px;
+    background:#fff;color:#161033;font-size:15px;line-height:1.35;text-align:center;position:relative;
+    opacity:0;transform:translateY(8px) scale(.96);transition:opacity .25s,transform .25s;
+    box-shadow:0 6px 20px #0007}
+  .bubble.show{opacity:1;transform:none}
+  .bubble:after{content:"";position:absolute;bottom:-9px;left:50%;margin-left:-9px;
+    border:9px solid transparent;border-top-color:#fff;border-bottom:0}
+  .mochi .bubble{border:2px solid var(--mochi)} .loaf .bubble{border:2px solid var(--loaf)}
+
+  .name{margin-top:10px;font-size:12px;letter-spacing:2px}
+  .mochi .name{color:var(--mochi)} .loaf .name{color:var(--loaf)}
+  .creature{width:200px;height:200px}
+
+  /* "what they see" reasoning line */
+  footer{padding:10px 18px 16px;text-align:center}
+  #scene{color:var(--dim);font-size:13px;min-height:18px}
+  #scene b{color:var(--gold);font-weight:normal}
+  #think{color:var(--mochi);font-size:12px;letter-spacing:1px;height:14px;opacity:0;transition:opacity .2s}
+  #think.on{opacity:1}
+  #actions{margin-top:8px;display:flex;align-items:center;justify-content:center;gap:12px;flex-wrap:wrap}
+  #share{background:transparent;color:var(--gold);border:1px solid var(--line);border-radius:8px;
+    padding:7px 14px;font:12px "Courier New",monospace;cursor:pointer;letter-spacing:1px}
+  #share:hover{border-color:var(--gold)}
+  #actions .hint{color:var(--dim);font-size:11px}
+  #dropnote{position:fixed;inset:0;z-index:25;display:none;align-items:center;justify-content:center;
+    background:#0c0a1ecc;color:var(--gold);font-size:20px;letter-spacing:2px;
+    border:3px dashed var(--gold);pointer-events:none}
+  #dropnote.show{display:flex}
+
+  /* consent gate */
+  #gate{position:fixed;inset:0;z-index:30;display:flex;align-items:center;justify-content:center;
+    background:radial-gradient(120% 90% at 50% 0%,var(--bg2),var(--bg))}
+  #gate .card{max-width:440px;text-align:center;padding:30px;border:1px solid var(--line);
+    border-radius:16px;background:#0c0a1ecc}
+  #gate h2{color:var(--gold);margin:0 0 6px;letter-spacing:2px}
+  #gate p{color:var(--dim);font-size:13px}
+  button{margin-top:14px;background:var(--mochi);color:#2a1500;border:0;border-radius:10px;
+    padding:12px 22px;font:bold 14px "Courier New",monospace;cursor:pointer;letter-spacing:1px}
+  button.ghost{background:transparent;color:var(--dim);border:1px solid var(--line);margin-left:8px}
+  #cam-status{color:var(--dim);font-size:12px;margin-top:10px;min-height:16px}
+</style>
+</head>
+<body>
+<div id="wrap">
+  <header>
+    <h1>THE COMMITTEE</h1>
+    <p>two cats intercepted your camera. they understand exactly what you are doing. they are judging you for it.</p>
+  </header>
+
+  <div id="viewport">
+    <video id="vp-video" playsinline muted></video>
+    <div class="vp-label"><span id="vp-dot"></span>WHAT THEY SEE</div>
+  </div>
+
+  <div id="stage">
+    <!-- MOCHI: hyper kitten — ears up, wide manic eyes, ginger -->
+    <div class="cat mochi" id="a-mochi">
+      <div class="bubble" id="b-mochi"></div>
+      <svg class="creature" viewBox="0 0 100 100" aria-hidden="true">
+        <polygon points="22,40 26,12 46,30" fill="#f6a64b"/>
+        <polygon points="78,40 74,12 54,30" fill="#f6a64b"/>
+        <polygon points="27,33 30,19 41,29" fill="#ffd0a3"/>
+        <polygon points="73,33 70,19 59,29" fill="#ffd0a3"/>
+        <ellipse cx="50" cy="58" rx="34" ry="31" fill="#f6a64b"/>
+        <ellipse cx="50" cy="64" rx="26" ry="22" fill="#ffe4c4"/>
+        <circle cx="38" cy="54" r="11" fill="#fff"/>
+        <circle class="pupil" data-eye="mo-l" cx="38" cy="54" r="6.5" fill="#1c3a1c"/>
+        <circle cx="62" cy="54" r="11" fill="#fff"/>
+        <circle class="pupil" data-eye="mo-r" cx="62" cy="54" r="6.5" fill="#1c3a1c"/>
+        <polygon points="50,64 46,69 54,69" fill="#e8718a"/>
+        <path d="M50 69 V73 M50 73 Q44 75 41 72 M50 73 Q56 75 59 72" stroke="#b5704a" stroke-width="1.6" fill="none" stroke-linecap="round"/>
+        <g stroke="#fff" stroke-width="1.3" stroke-linecap="round" opacity=".85">
+          <path d="M30 64 H10"/><path d="M30 68 H12"/><path d="M70 64 H90"/><path d="M70 68 H88"/></g>
+      </svg>
+      <div class="name">MOCHI</div>
+    </div>
+
+    <!-- LOAF: enormous elder loaf — droopy lids, grey, unbothered -->
+    <div class="cat loaf" id="a-loaf">
+      <div class="bubble" id="b-loaf"></div>
+      <svg class="creature" viewBox="0 0 100 100" aria-hidden="true">
+        <polygon points="26,44 30,24 48,38" fill="#8d8f9e"/>
+        <polygon points="74,44 70,24 52,38" fill="#8d8f9e"/>
+        <path d="M14 70 Q14 44 50 44 Q86 44 86 70 Q86 92 50 92 Q14 92 14 70Z" fill="#9a9cab"/>
+        <ellipse cx="50" cy="70" rx="30" ry="22" fill="#c9cbd6"/>
+        <circle cx="37" cy="60" r="10" fill="#d8e6c0"/>
+        <circle class="pupil" data-eye="lo-l" cx="37" cy="61" r="5" fill="#23301c"/>
+        <circle cx="63" cy="60" r="10" fill="#d8e6c0"/>
+        <circle class="pupil" data-eye="lo-r" cx="63" cy="61" r="5" fill="#23301c"/>
+        <!-- heavy half-shut lids: the eternal unbothered loaf -->
+        <path d="M27 57 Q37 53 47 57" stroke="#9a9cab" stroke-width="6" fill="none" stroke-linecap="round"/>
+        <path d="M53 57 Q63 53 73 57" stroke="#9a9cab" stroke-width="6" fill="none" stroke-linecap="round"/>
+        <polygon points="50,70 46,75 54,75" fill="#c66"/>
+        <path d="M50 75 V79 M50 79 Q43 81 40 78 M50 79 Q57 81 60 78" stroke="#6b6d7a" stroke-width="1.6" fill="none" stroke-linecap="round"/>
+        <g stroke="#e7e9f2" stroke-width="1.3" stroke-linecap="round" opacity=".8">
+          <path d="M28 71 H6"/><path d="M28 75 H9"/><path d="M72 71 H94"/><path d="M72 75 H91"/></g>
+      </svg>
+      <div class="name">LOAF</div>
+    </div>
+  </div>
+
+  <footer>
+    <div id="think">· · ·</div>
+    <div id="scene">what they see: <b id="scene-text">warming up the window…</b></div>
+    <div id="actions">
+      <button id="share">share their verdict</button>
+      <span class="hint">· or drag any image here and they'll judge it ·</span>
+    </div>
+  </footer>
+</div>
+
+<div id="dropnote">drop it — the committee will judge your image</div>
+
+<div id="gate">
+  <div class="card">
+    <h2>LET THEM WATCH</h2>
+    <p>Mochi &amp; Loaf watch you through your webcam and judge what you're doing.
+       Frames are described on this machine and never stored or uploaded anywhere.</p>
+    <button id="allow">allow camera</button>
+    <button id="skip" class="ghost">just watch them</button>
+    <div id="cam-status"></div>
+  </div>
+</div>
+
+<script type="module" src="/theater/js/duo.js"></script>
+</body>
+</html>

theater/index.html

@@ -0,0 +1,202 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>GLORBVISION — Earth Feed</title>
+<style>
+  :root {
+    --void: #1a0f30;
+    --stone: #2a1a4a;
+    --cyan: #58e6e6;
+    --gold: #ffd35a;
+    --love: #ff6fa5;
+    --meh: #8fb3bd;
+    --hate: #ff3b30;
+    --paper: #fffbe9;
+  }
+  * { box-sizing: border-box; }
+  html, body {
+    margin: 0; padding: 0; width: 100%; height: 100%;
+    background: var(--void); color: #efeaff; overflow: hidden;
+    font: 13px/1.4 "Courier New", ui-monospace, monospace;
+  }
+  #stage { position: fixed; inset: 0; }
+  #stage canvas { display: block; cursor: crosshair; }
+
+  /* ---------- top HUD ---------- */
+  #hud-top {
+    position: fixed; top: 0; left: 0; right: 0; z-index: 20;
+    display: flex; align-items: baseline; gap: 16px; flex-wrap: wrap;
+    padding: 10px 14px 14px;
+    background: linear-gradient(180deg, rgba(10,5,24,.92) 0%, rgba(10,5,24,.65) 70%, transparent 100%);
+    pointer-events: none;
+  }
+  #brand {
+    font-size: 22px; font-weight: bold; letter-spacing: 3px; color: var(--cyan);
+    text-shadow: 0 0 12px rgba(88,230,230,.6);
+    white-space: nowrap;
+  }
+  #brand .sub {
+    display: block; font-size: 9px; letter-spacing: 2px; color: var(--gold);
+    text-shadow: none;
+  }
+  #premise { flex: 1 1 320px; min-width: 240px; color: #efeaff; font-size: 12px; }
+  #premise b { color: var(--gold); }
+  #factions { display: flex; align-items: center; gap: 12px; white-space: nowrap; font-weight: bold; }
+  #factions .f { padding: 2px 8px; border: 1px solid currentColor; border-radius: 3px; }
+  .f.love { color: var(--love); } .f.meh { color: var(--meh); } .f.hate { color: var(--hate); }
+  #live-pill {
+    padding: 2px 8px; border-radius: 3px; font-size: 11px; letter-spacing: 1px;
+    background: var(--hate); color: #fff;
+  }
+  #live-pill.on { background: #1fbf6b; animation: livepulse 1.6s infinite; }
+  @keyframes livepulse { 50% { box-shadow: 0 0 10px #1fbf6b; } }
+  #thinking { color: var(--cyan); font-size: 11px; animation: blink 1s steps(2) infinite; }
+  @keyframes blink { 50% { opacity: .25; } }
+
+  /* ---------- event splash ---------- */
+  #event-label {
+    position: fixed; top: 18%; left: 50%; transform: translateX(-50%);
+    z-index: 25; pointer-events: none;
+    font-size: 34px; font-weight: bold; letter-spacing: 6px;
+    color: var(--gold); text-shadow: 0 0 18px rgba(255,211,90,.8), 2px 2px 0 var(--void);
+    animation: splash 1.6s ease-out forwards;
+  }
+  @keyframes splash {
+    0% { opacity: 0; transform: translateX(-50%) scale(.4); }
+    15% { opacity: 1; transform: translateX(-50%) scale(1.15); }
+    25% { transform: translateX(-50%) scale(1); }
+    80% { opacity: 1; }
+    100% { opacity: 0; }
+  }
+
+  /* ---------- bubbles ---------- */
+  #bubble-layer { position: fixed; inset: 0; z-index: 15; pointer-events: none; overflow: hidden; }
+  .bubble {
+    position: absolute; left: 0; top: 0; max-width: 230px;
+    background: var(--paper); color: var(--void);
+    border: 2px solid var(--void); border-radius: 2px;
+    padding: 4px 8px 5px; font-weight: bold; font-size: 11px; line-height: 1.3;
+    transform: translate(-50%, -112%);
+    box-shadow: 3px 3px 0 rgba(0,0,0,.45), 0 0 0 1px rgba(88,230,230,.35);
+    opacity: 0;
+  }
+  .bubble .who { display: block; font-size: 8px; letter-spacing: 2px; color: #7a3fd6; }
+  .bubble::after {
+    content: ""; position: absolute; left: 50%; bottom: -8px; margin-left: -6px;
+    border: 6px solid transparent; border-top-color: var(--void); border-bottom: 0;
+  }
+  .bubble.show { animation: pop .22s cubic-bezier(.2,1.6,.4,1) forwards; }
+  @keyframes pop {
+    0% { opacity: 0; transform: translate(-50%, -112%) scale(.25); }
+    100% { opacity: 1; transform: translate(-50%, -112%) scale(1); }
+  }
+  .bubble.hide { transition: opacity .18s, transform .18s; opacity: 0 !important; transform: translate(-50%, -130%) scale(.6); }
+
+  /* ---------- bottom HUD ---------- */
+  #hud-bottom {
+    position: fixed; left: 0; right: 0; bottom: 0; z-index: 20;
+    padding: 12px 14px 10px;
+    background: linear-gradient(0deg, rgba(10,5,24,.92) 0%, rgba(10,5,24,.6) 70%, transparent 100%);
+    display: flex; flex-direction: column; gap: 5px;
+  }
+  #scene-line { font-size: 13px; color: #fff; }
+  #scene-line .tag {
+    background: var(--cyan); color: var(--void); font-weight: bold;
+    padding: 1px 6px; margin-right: 6px; font-size: 10px; letter-spacing: 1px;
+  }
+  #scene-text { color: var(--gold); }
+  #privacy { font-size: 10px; color: #b9aee0; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  #egress-dot {
+    width: 9px; height: 9px; border-radius: 50%; flex: none;
+    background: #4a3a6e; border: 1px solid #6a55a0; transition: background .1s, box-shadow .1s;
+  }
+  #egress-dot.active { background: var(--hate); box-shadow: 0 0 8px var(--hate); }
+  #privacy button, #consent button {
+    font: bold 11px "Courier New", monospace; letter-spacing: 1px;
+    background: var(--stone); color: #fff; border: 1px solid var(--cyan);
+    padding: 3px 10px; cursor: pointer; border-radius: 2px;
+  }
+  #privacy button:hover, #consent button:hover { background: var(--cyan); color: var(--void); }
+  #cam-status { color: var(--hate); font-weight: bold; }
+  #hint { font-size: 10px; color: #6f5fa0; letter-spacing: 1px; }
+
+  /* ---------- consent overlay ---------- */
+  #consent {
+    position: fixed; inset: 0; z-index: 40;
+    display: flex; align-items: center; justify-content: center;
+    background: rgba(12,6,28,.88); backdrop-filter: blur(3px);
+    transition: opacity .4s;
+  }
+  #consent.gone { opacity: 0; pointer-events: none; }
+  #consent-card {
+    max-width: 460px; margin: 16px; padding: 28px 30px;
+    background: var(--void); border: 2px solid var(--cyan);
+    box-shadow: 0 0 40px rgba(88,230,230,.25), 8px 8px 0 rgba(0,0,0,.5);
+    text-align: center;
+  }
+  #consent-card h1 {
+    margin: 0 0 4px; font-size: 30px; letter-spacing: 5px; color: var(--cyan);
+    text-shadow: 0 0 14px rgba(88,230,230,.7);
+  }
+  #consent-card .cycle { font-size: 10px; letter-spacing: 3px; color: var(--gold); margin-bottom: 14px; }
+  #consent-card p { margin: 10px 0; color: #efeaff; }
+  #consent-card .small { font-size: 10px; color: #b9aee0; }
+  #consent-card #start-cam {
+    display: block; width: 100%; margin: 18px 0 8px; padding: 12px;
+    font-size: 13px; background: var(--cyan); color: var(--void); border: none;
+  }
+  #consent-card #start-cam:hover { background: var(--gold); }
+  #consent-card #skip-cam { background: transparent; border-color: #5a4690; color: #b9aee0; }
+</style>
+<script type="importmap">
+  { "imports": { "three": "/web/vendor/three.module.js" } }
+</script>
+</head>
+<body>
+  <div id="stage"></div>
+
+  <header id="hud-top">
+    <div id="brand">GLORBVISION<span class="sub">EARTH FEED · CYCLE 4,071</span></div>
+    <div id="premise">120 aliens intercepted your webcam and now believe you are prestige television —
+      <b>allow the camera so they can watch you.</b></div>
+    <div id="factions">
+      <span class="f love">LOVE <b id="f-love">0</b></span>
+      <span class="f meh">MEH <b id="f-meh">120</b></span>
+      <span class="f hate">HATE <b id="f-hate">0</b></span>
+      <span id="live-pill" class="off">NO SIGNAL</span>
+      <span id="thinking" hidden>TRANSLATOR…</span>
+    </div>
+  </header>
+
+  <div id="bubble-layer"></div>
+
+  <footer id="hud-bottom">
+    <div id="scene-line"><span class="tag">TRANSLATOR</span><span id="scene-text">awaiting first transmission from Earth…</span></div>
+    <div id="privacy">
+      <span id="egress-dot" title="flashes when a snapshot is sent"></span>
+      <span>Camera stays in your browser. One low-res snapshot goes to the local server only on scene change (or every 10&nbsp;s) and is never stored.</span>
+      <button id="stop-cam" hidden>STOP CAMERA</button>
+      <span id="cam-status"></span>
+    </div>
+    <div id="hint">CLICK AN ALIEN to read its census dossier · CLICK EMPTY SEATS to let them know you can see them. they will not handle it well.</div>
+  </footer>
+
+  <div id="consent">
+    <div id="consent-card">
+      <h1>GLORBVISION</h1>
+      <div class="cycle">EARTH FEED · CYCLE 4,071 · 120 BLORPS IN ATTENDANCE</div>
+      <p>An alien civilization tapped your webcam and thinks it's prestige television.
+         They worship your mug. They heckle your typing.</p>
+      <p class="small">Privacy: your camera feed stays in this browser. Only one tiny snapshot
+         is POSTed to your local server when the scene changes (or every 10&nbsp;s), never stored,
+         never leaves your machine. A red dot flashes on every send. You can stop the camera anytime.</p>
+      <button id="start-cam">ALLOW CAMERA — LET THEM WATCH</button>
+      <button id="skip-cam">enter without camera (they will riot)</button>
+    </div>
+  </div>
+
+  <script type="module" src="/theater/js/main.js"></script>
+</body>
+</html>

theater/js/aliencard.js

@@ -0,0 +1,242 @@
+// aliencard.js — alien dossier overlay + RUMOR MILL line (C, society upgrade).
+//
+//   initAlienCard({ bubbleFor }) -> { open(id), close(), setRumor(str|null) }
+//
+// open(id) fetches GET /api/alien/{id} and renders a card in the HUD's
+// Courier/cyan aesthetic. Defensive about the card shape: alien_card() may
+// nest persona fields under .persona or keep them flat, and memory entries
+// may be strings or {said,...} objects. A 404 (cards not wired yet) renders
+// a friendly "no census record" card instead of breaking the theater.
+// setRumor() owns the small RUMOR MILL line under the factions HUD.
+
+let overlayEl = null;
+let boxEl = null;
+let rumorEl = null;
+let openId = null;
+let lastRumor = null;
+let bubbleFor = null;
+
+const CSS = `
+  #alien-card-overlay {
+    position: fixed; inset: 0; z-index: 35;
+    display: flex; align-items: center; justify-content: center;
+    background: rgba(12,6,28,.55);
+  }
+  #alien-card-overlay[hidden] { display: none; }
+  #alien-card {
+    position: relative; width: min(400px, calc(100vw - 32px));
+    max-height: calc(100vh - 120px); overflow-y: auto;
+    background: var(--void, #1a0f30); color: #efeaff;
+    border: 2px solid var(--cyan, #58e6e6);
+    box-shadow: 0 0 36px rgba(88,230,230,.3), 8px 8px 0 rgba(0,0,0,.5);
+    padding: 18px 20px 16px;
+    font: 13px/1.45 "Courier New", ui-monospace, monospace;
+  }
+  #alien-card .ac-close {
+    position: absolute; top: 8px; right: 8px;
+    font: bold 12px "Courier New", monospace;
+    background: var(--stone, #2a1a4a); color: var(--cyan, #58e6e6);
+    border: 1px solid var(--cyan, #58e6e6); border-radius: 2px;
+    padding: 2px 8px; cursor: pointer; letter-spacing: 1px;
+  }
+  #alien-card .ac-close:hover { background: var(--cyan, #58e6e6); color: var(--void, #1a0f30); }
+  #alien-card .ac-kicker { font-size: 9px; letter-spacing: 3px; color: var(--gold, #ffd35a); }
+  #alien-card .ac-name {
+    margin: 2px 0; font-size: 26px; font-weight: bold; letter-spacing: 2px;
+    color: var(--cyan, #58e6e6); text-shadow: 0 0 12px rgba(88,230,230,.55);
+    word-break: break-word;
+  }
+  #alien-card .ac-sub {
+    font-size: 11px; letter-spacing: 2px; color: var(--gold, #ffd35a);
+    text-transform: uppercase;
+  }
+  #alien-card .ac-bubble {
+    margin-top: 12px; padding: 6px 9px;
+    background: var(--paper, #fffbe9); color: var(--void, #1a0f30);
+    border: 2px solid var(--void, #1a0f30); border-radius: 2px;
+    font-weight: bold; font-size: 11px;
+    box-shadow: 3px 3px 0 rgba(0,0,0,.45), 0 0 0 1px rgba(88,230,230,.35);
+  }
+  #alien-card .ac-section { margin-top: 12px; }
+  #alien-card .ac-label { font-size: 9px; letter-spacing: 2px; color: var(--meh, #8fb3bd); }
+  #alien-card .ac-value { color: #efeaff; }
+  #alien-card .ac-opinion { color: var(--gold, #ffd35a); font-weight: bold; }
+  #alien-card .ac-said { margin: 4px 0 0; padding: 0; list-style: none; }
+  #alien-card .ac-said li {
+    margin-top: 3px; padding-left: 10px; color: #d9d2f5;
+    border-left: 2px solid var(--stone, #2a1a4a);
+  }
+  #alien-card .ac-dim { color: #8fb3bd; }
+  #rumor-mill {
+    flex-basis: 100%; pointer-events: none;
+    font-size: 11px; letter-spacing: 1px; color: #efeaff;
+  }
+  #rumor-mill b {
+    background: var(--gold, #ffd35a); color: var(--void, #1a0f30);
+    padding: 1px 6px; margin-right: 6px; font-size: 9px; letter-spacing: 2px;
+  }
+`;
+
+function el(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== undefined && text !== null) n.textContent = String(text);
+  return n;
+}
+
+export function initAlienCard(opts = {}) {
+  bubbleFor = typeof opts.bubbleFor === 'function' ? opts.bubbleFor : null;
+
+  if (!document.getElementById('alien-card-style')) {
+    const style = document.createElement('style');
+    style.id = 'alien-card-style';
+    style.textContent = CSS;
+    document.head.appendChild(style);
+  }
+  if (!overlayEl) {
+    overlayEl = el('div');
+    overlayEl.id = 'alien-card-overlay';
+    overlayEl.hidden = true;
+    overlayEl.addEventListener('click', (e) => {
+      if (e.target === overlayEl) closeAlienCard();   // outside-click closes
+    });
+    boxEl = el('div');
+    boxEl.id = 'alien-card';
+    overlayEl.appendChild(boxEl);
+    document.body.appendChild(overlayEl);
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') closeAlienCard();
+    });
+  }
+  if (!rumorEl) {
+    rumorEl = el('div');
+    rumorEl.id = 'rumor-mill';
+    rumorEl.hidden = true;
+    (document.getElementById('hud-top') || document.body).appendChild(rumorEl);
+  }
+  return { open: openAlienCard, close: closeAlienCard, setRumor };
+}
+
+export async function openAlienCard(id) {
+  if (!overlayEl) return;
+  openId = id;
+  overlayEl.hidden = false;
+  renderLoading(id);
+  let card = null;
+  try {
+    const res = await fetch(`/api/alien/${id}`);
+    if (res.ok) card = await res.json();
+  } catch { /* server offline — fall through to the unknown card */ }
+  if (openId !== id || overlayEl.hidden) return;   // closed or re-opened meanwhile
+  if (card && typeof card === 'object') renderCard(id, card);
+  else renderUnknown(id);
+}
+
+export function closeAlienCard() {
+  openId = null;
+  if (overlayEl) overlayEl.hidden = true;
+}
+
+/** Show/refresh the RUMOR MILL line under the factions HUD (null hides it). */
+export function setRumor(rumor) {
+  const next = (typeof rumor === 'string' && rumor.trim()) ? rumor.trim() : null;
+  if (next === lastRumor || !rumorEl) return;
+  lastRumor = next;
+  rumorEl.textContent = '';
+  if (!next) { rumorEl.hidden = true; return; }
+  rumorEl.hidden = false;
+  rumorEl.appendChild(el('b', null, 'RUMOR MILL'));
+  rumorEl.appendChild(document.createTextNode(next));
+}
+
+// ---------------------------------------------------------------- rendering
+
+function header(title) {
+  boxEl.textContent = '';
+  const close = el('button', 'ac-close', 'X');
+  close.setAttribute('aria-label', 'close dossier');
+  close.addEventListener('click', closeAlienCard);
+  boxEl.appendChild(close);
+  boxEl.appendChild(el('div', 'ac-kicker', 'GLORBVISION CENSUS DOSSIER'));
+  boxEl.appendChild(el('div', 'ac-name', title));
+}
+
+function renderLoading(id) {
+  header(`BLORP #${id}`);
+  boxEl.appendChild(el('div', 'ac-dim', 'pulling census record…'));
+}
+
+function renderUnknown(id) {
+  header(`BLORP #${id}`);
+  boxEl.appendChild(el('div', 'ac-dim',
+    'No dossier on file. The census drones have not reached this seat yet.'));
+}
+
+function relationshipText(rel) {
+  if (!rel) return '';
+  if (typeof rel === 'string') return rel;
+  if (typeof rel === 'object') {
+    const kind = String(rel.kind || '').replace(/_/g, ' ');
+    if (!kind) return '';
+    const target = rel.target_name || rel.target
+      || (rel.target_id !== undefined ? `the blorp in seat #${rel.target_id}` : '');
+    return target ? `${kind} → ${target}` : kind;
+  }
+  return '';
+}
+
+function memLines(memory) {
+  if (!Array.isArray(memory)) return [];
+  const lines = [];
+  for (const m of memory) {
+    let said = '';
+    if (typeof m === 'string') said = m;
+    else if (m && typeof m === 'object') said = m.said || m.line || m.text || m.quote || '';
+    if (said) lines.push(String(said));
+  }
+  return lines.slice(-3).reverse();   // newest first
+}
+
+function renderCard(id, card) {
+  const persona = (card.persona && typeof card.persona === 'object') ? card.persona : card;
+  header(card.name || persona.name || `BLORP #${id}`);
+
+  const arch = card.archetype || persona.archetype || 'unknown';
+  boxEl.appendChild(el('div', 'ac-sub', card.mood ? `${arch} · ${card.mood}` : arch));
+
+  const bubble = card.bubble || (bubbleFor ? bubbleFor(id) : null);
+  if (bubble) boxEl.appendChild(el('div', 'ac-bubble', `“${bubble}”`));
+
+  const rows = [
+    ['QUIRK', persona.quirk],
+    ['OBSESSION', persona.obsession],
+    ['SPEECH TIC', persona.tic || persona.speech_tic],
+    ['RELATIONSHIP', relationshipText(persona.relationship || persona.relation)],
+  ];
+  for (const [label, value] of rows) {
+    if (!value) continue;
+    const sec = el('div', 'ac-section');
+    sec.appendChild(el('div', 'ac-label', label));
+    sec.appendChild(el('div', 'ac-value', value));
+    boxEl.appendChild(sec);
+  }
+
+  const opinion = card.opinion || card.opinion_of_you
+    || persona.opinion || persona.opinion_of_protagonist;
+  const opSec = el('div', 'ac-section');
+  opSec.appendChild(el('div', 'ac-label', 'OPINION OF YOU'));
+  opSec.appendChild(el('div', 'ac-opinion', opinion || 'still forming one. stay tuned.'));
+  boxEl.appendChild(opSec);
+
+  const lines = memLines(card.memory);
+  const memSec = el('div', 'ac-section');
+  memSec.appendChild(el('div', 'ac-label', 'LAST TRANSMISSIONS'));
+  if (lines.length) {
+    const ul = el('ul', 'ac-said');
+    for (const line of lines) ul.appendChild(el('li', null, `“${line}”`));
+    memSec.appendChild(ul);
+  } else {
+    memSec.appendChild(el('div', 'ac-dim', 'has not said anything memorable yet.'));
+  }
+  boxEl.appendChild(memSec);
+}

theater/js/bubbles.js

@@ -0,0 +1,76 @@
+// bubbles.js — speech bubbles as a DOM overlay, positioned by projecting each
+// speaking alien's world position. Max 8 live; pop-in staggered for comic timing.
+
+const MAX_BUBBLES = 8;
+
+export class Bubbles {
+  constructor(layerEl) {
+    this.layer = layerEl;
+    this.items = new Map(); // alien id -> { el, text }
+  }
+
+  /** Diff the polled alien list against currently shown bubbles. */
+  applyState(aliens) {
+    if (!Array.isArray(aliens)) return;
+    const wanted = new Map();
+    for (const a of aliens) {
+      if (a && typeof a.bubble === 'string' && a.bubble.length) wanted.set(a.id, a);
+    }
+    // drop bubbles that vanished or changed text
+    for (const [id, item] of [...this.items]) {
+      const w = wanted.get(id);
+      if (!w || w.bubble !== item.text) this._remove(id);
+    }
+    // pop in new ones, staggered ~140 ms apart so a fresh batch reads as a riff
+    let delay = 0;
+    for (const [id, a] of wanted) {
+      if (this.items.has(id)) continue;
+      if (this.items.size >= MAX_BUBBLES) break;
+      this._add(a, delay);
+      delay += 140;
+    }
+  }
+
+  _add(a, delay) {
+    const el = document.createElement('div');
+    el.className = 'bubble';
+    const who = document.createElement('span');
+    who.className = 'who';
+    who.textContent = String(a.archetype || '???').toUpperCase().replace(/_/g, ' ');
+    el.appendChild(who);
+    el.appendChild(document.createTextNode(String(a.bubble).slice(0, 60)));
+    el.style.display = 'none';
+    this.layer.appendChild(el);
+    const item = { el, text: a.bubble, shown: false };
+    this.items.set(a.id, item);
+    setTimeout(() => {
+      if (!el.isConnected) return;
+      item.shown = true;
+      el.classList.add('show');
+    }, delay);
+  }
+
+  _remove(id) {
+    const item = this.items.get(id);
+    if (!item) return;
+    this.items.delete(id);
+    const { el } = item;
+    el.classList.add('hide');
+    setTimeout(() => el.remove(), 220);
+  }
+
+  /** Call every animation frame: pin bubbles above their aliens. */
+  reposition(theater) {
+    for (const [id, item] of this.items) {
+      if (!item.shown) continue;
+      const p = theater.projectAlien(id);
+      if (!p || p.x < -60 || p.x > window.innerWidth + 60 || p.y < 0) {
+        item.el.style.display = 'none';
+        continue;
+      }
+      item.el.style.display = '';
+      item.el.style.left = `${p.x.toFixed(1)}px`;
+      item.el.style.top = `${p.y.toFixed(1)}px`;
+    }
+  }
+}

theater/js/capture.js

@@ -0,0 +1,239 @@
+// capture.js — consent-first webcam pipeline (B1).
+// One hidden <video> feeds BOTH the three.js VideoTexture and a 480-wide capture
+// canvas. Cheap grayscale diff on a 64x48 buffer gates JSON-base64 POSTs to
+// /api/frame (contract transport). Light/sound numbers go to /api/sense every 2 s.
+// Privacy: egress dot flashes on every actual POST; stop() releases the device.
+
+const CAPTURE_W = 480;
+const DIFF_W = 64, DIFF_H = 48;
+const JPEG_QUALITY = 0.7;
+const DIFF_THRESHOLD = 0.05;
+const HEARTBEAT_MS = 10_000;
+const MIN_INTERVAL_MS = 1_500;
+const SAMPLE_MS = 333;
+const SENSE_MS = 2_000;
+
+export class Capture {
+  constructor({ onVideo, onStatus, egressDot } = {}) {
+    this.onVideo = onVideo || (() => {});
+    this.onStatus = onStatus || (() => {});
+    this.dot = egressDot || null;
+
+    this.video = document.createElement('video');
+    this.video.playsInline = true;
+    this.video.muted = true;
+
+    this.captureCanvas = document.createElement('canvas');
+    this.captureCtx = this.captureCanvas.getContext('2d');
+
+    this.diffCanvas = document.createElement('canvas');
+    this.diffCanvas.width = DIFF_W;
+    this.diffCanvas.height = DIFF_H;
+    // willReadFrequently keeps the canvas CPU-side -> cheap getImageData
+    this.diffCtx = this.diffCanvas.getContext('2d', { willReadFrequently: true });
+
+    this.stream = null;
+    this.prevGray = null;
+    this.running = false;
+    this.inFlight = false;
+    this.lastUpload = 0;
+    this.lastSample = 0;
+    this.readings = { light: -1, sound: -1 };
+    this.analyser = null;
+    this.audioBuf = null;
+    this.audioCtx = null;
+
+    // sense push runs forever; posts -1/-1 until the camera is live
+    setInterval(() => this._postSense(), SENSE_MS);
+    this._postSense();
+
+    document.addEventListener('visibilitychange', () => {
+      if (!this.stream) return;
+      this.running = !document.hidden;
+      if (this.running) this._scheduleTick();
+    });
+  }
+
+  // -------------------------------------------------------------- lifecycle
+
+  async start() {
+    if (this.stream) return true;
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+      this.onStatus('camera needs HTTPS or localhost — the Blorps see only static.');
+      return false;
+    }
+    const videoConstraints = {
+      width: { ideal: 640 }, height: { ideal: 480 }, facingMode: 'user',
+    };
+    let stream = null;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ video: videoConstraints, audio: true });
+    } catch (err) {
+      try {
+        // mic refused or absent — try video only, sound stays -1
+        stream = await navigator.mediaDevices.getUserMedia({ video: videoConstraints, audio: false });
+      } catch (err2) {
+        this.onStatus(this._explainError(err2));
+        return false;
+      }
+    }
+    this.stream = stream;
+    this.video.srcObject = stream;
+    await new Promise((res) => { this.video.onloadedmetadata = res; });
+    await this.video.play();
+
+    this.captureCanvas.width = CAPTURE_W;
+    this.captureCanvas.height =
+      Math.round(CAPTURE_W * this.video.videoHeight / this.video.videoWidth) || 360;
+
+    if (stream.getAudioTracks().length) {
+      try {
+        this.audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+        this.analyser = this.audioCtx.createAnalyser();
+        this.analyser.fftSize = 256;
+        this.audioCtx.createMediaStreamSource(stream).connect(this.analyser);
+        this.audioBuf = new Uint8Array(this.analyser.fftSize);
+      } catch (e) {
+        this.analyser = null;
+      }
+    }
+
+    this.running = true;
+    this.prevGray = null;
+    this._scheduleTick();
+    this.onVideo(this.video);
+    this.onStatus('');
+    return true;
+  }
+
+  /** The honest off-switch: releases the device, OS camera LED goes dark. */
+  stop() {
+    this.running = false;
+    if (this.stream) {
+      this.stream.getTracks().forEach((t) => t.stop());
+      this.stream = null;
+    }
+    if (this.audioCtx) {
+      this.audioCtx.close().catch(() => {});
+      this.audioCtx = null;
+    }
+    this.analyser = null;
+    this.video.srcObject = null;
+    this.prevGray = null;
+    this.readings.light = -1;
+    this.readings.sound = -1;
+    this._postSense();
+  }
+
+  _explainError(err) {
+    const name = err && err.name;
+    if (name === 'NotAllowedError') return 'camera denied — the Blorps boo at a blank screen.';
+    if (name === 'NotFoundError') return 'no camera found — broadcasting test pattern.';
+    return 'camera failed: ' + (name || 'unknown') + '.';
+  }
+
+  // -------------------------------------------------------------- frame diff
+
+  /** 0..1 motion score: mean per-pixel grayscale delta vs the previous sample. */
+  _diffScore() {
+    this.diffCtx.drawImage(this.video, 0, 0, DIFF_W, DIFF_H);
+    const { data } = this.diffCtx.getImageData(0, 0, DIFF_W, DIFF_H);
+    const n = DIFF_W * DIFF_H;
+    const gray = new Uint8ClampedArray(n);
+    let lumSum = 0;
+    for (let i = 0; i < n; i++) {
+      const j = i * 4;
+      const g = 0.299 * data[j] + 0.587 * data[j + 1] + 0.114 * data[j + 2];
+      gray[i] = g;
+      lumSum += g;
+    }
+    // light reading rides along for free: mean luma 0..255 -> 0..100
+    this.readings.light = Math.round((lumSum / n) / 255 * 100);
+
+    let score = 0;
+    if (this.prevGray) {
+      const NOISE = 15;
+      let sum = 0;
+      for (let i = 0; i < n; i++) {
+        const d = Math.abs(gray[i] - this.prevGray[i]);
+        if (d > NOISE) sum += d;
+      }
+      score = sum / (n * 255);
+    }
+    this.prevGray = gray;
+    return score;
+  }
+
+  _tick(now) {
+    if (!this.running) return;
+    if (now - this.lastSample >= SAMPLE_MS) {
+      this.lastSample = now;
+      const score = this._diffScore();
+      const since = performance.now() - this.lastUpload;
+      if (score > DIFF_THRESHOLD && since > MIN_INTERVAL_MS) this._maybeUpload();
+      else if (since > HEARTBEAT_MS) this._maybeUpload();
+    }
+    this._scheduleTick();
+  }
+
+  _scheduleTick() {
+    if (!this.running) return;
+    if ('requestVideoFrameCallback' in HTMLVideoElement.prototype) {
+      this.video.requestVideoFrameCallback((now) => this._tick(now));
+    } else {
+      setTimeout(() => this._tick(performance.now()), SAMPLE_MS);
+    }
+  }
+
+  // -------------------------------------------------------------- egress
+
+  async _maybeUpload() {
+    if (this.inFlight) return; // never queue concurrent uploads
+    this.inFlight = true;
+    try {
+      this.captureCtx.drawImage(this.video, 0, 0, this.captureCanvas.width, this.captureCanvas.height);
+      const dataUrl = this.captureCanvas.toDataURL('image/jpeg', JPEG_QUALITY);
+      this.lastUpload = performance.now();
+      this._flashDot(); // user SEES every actual POST
+      await fetch('/api/frame', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ image: dataUrl }),
+      });
+    } catch (err) {
+      // server busy/offline — drop silently, next diff will retry
+    } finally {
+      this.inFlight = false;
+    }
+  }
+
+  _flashDot() {
+    if (!this.dot) return;
+    this.dot.classList.add('active');
+    setTimeout(() => this.dot.classList.remove('active'), 300);
+  }
+
+  // -------------------------------------------------------------- sense
+
+  _postSense() {
+    if (this.running && this.analyser) {
+      this.analyser.getByteTimeDomainData(this.audioBuf);
+      let rms = 0;
+      for (let i = 0; i < this.audioBuf.length; i++) {
+        const v = (this.audioBuf[i] - 128) / 128;
+        rms += v * v;
+      }
+      this.readings.sound = Math.round(Math.min(100, Math.sqrt(rms / this.audioBuf.length) * 400));
+    } else if (!this.running) {
+      this.readings.light = -1;
+      this.readings.sound = -1;
+    } else {
+      this.readings.sound = -1;
+    }
+    fetch('/api/sense', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ light: this.readings.light, sound: this.readings.sound }),
+    }).catch(() => { /* server not up yet */ });
+  }
+}

theater/js/duo.js

@@ -0,0 +1,157 @@
+// duo.js — Mochi & Loaf: two cats who watch your webcam and judge you.
+// Reuses the consent-first capture pipeline (frames -> /api/frame, light/sound
+// -> /api/sense). Polls /api/duo for the latest verdict and plays it with comic
+// timing. Punch-ups: pupils dilate in the dark, Mochi pounces on each new
+// verdict, drag any image to be judged, share-the-verdict button.
+import { Capture } from './capture.js';
+
+const $ = (id) => document.getElementById(id);
+const BUBBLE = { mochi: $('b-mochi'), loaf: $('b-loaf') };
+const CAT = { mochi: $('a-mochi'), loaf: $('a-loaf') };
+
+const capture = new Capture({
+  onVideo: (video) => { const vp = $('vp-video'); vp.srcObject = video.srcObject; vp.play().catch(() => {}); },
+  onStatus: (msg) => { $('cam-status').textContent = msg; },
+});
+
+// ---------------------------------------------------------------- consent gate
+$('allow').addEventListener('click', async () => {
+  $('cam-status').textContent = 'waking the window…';
+  const ok = await capture.start();
+  if (ok) $('gate').style.display = 'none';
+});
+$('skip').addEventListener('click', () => { $('gate').style.display = 'none'; });
+
+// ---------------------------------------------------------------- eyes
+const pupils = [...document.querySelectorAll('.pupil')].map((el) => ({
+  el, cx: +el.getAttribute('cx'), cy: +el.getAttribute('cy'), r: +el.getAttribute('r'),
+}));
+let target = { x: 0.5, y: 0.45 };
+let dilation = 1, dilationGoal = 1;          // pupil size; grows in the dark
+window.addEventListener('pointermove', (e) => {
+  target.x = e.clientX / window.innerWidth;
+  target.y = e.clientY / window.innerHeight;
+});
+
+let t = 0;
+function animate() {
+  t += 1;
+  const wanderX = Math.sin(t / 73) * 0.06, wanderY = Math.cos(t / 91) * 0.05;
+  const dx = (target.x - 0.5 + wanderX) * 5, dy = (target.y - 0.45 + wanderY) * 4;
+  dilation += (dilationGoal - dilation) * 0.08;
+  for (const p of pupils) {
+    p.el.setAttribute('cx', (p.cx + dx).toFixed(2));
+    p.el.setAttribute('cy', (p.cy + dy).toFixed(2));
+    p.el.setAttribute('r', (p.r * dilation).toFixed(2));
+  }
+  requestAnimationFrame(animate);
+}
+requestAnimationFrame(animate);
+
+// ---------------------------------------------------------------- play verdict
+let lastKey = '', playToken = 0;
+const other = (w) => (w === 'mochi' ? 'loaf' : 'mochi');
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function setBubble(who, text) {
+  const b = BUBBLE[who];
+  if (!b) return;
+  b.textContent = text;
+  b.classList.add('show');
+  CAT[who].classList.add('talk');
+  CAT[other(who)].classList.add('listen');
+}
+function clearTalk() { for (const k of ['mochi', 'loaf']) CAT[k].classList.remove('talk', 'listen'); }
+
+function pounce() {            // Mochi lunges at the screen on a fresh verdict
+  CAT.mochi.classList.remove('pounce');
+  void CAT.mochi.offsetWidth;  // restart the animation
+  CAT.mochi.classList.add('pounce');
+}
+
+async function play(exchange) {
+  const token = ++playToken;
+  BUBBLE.mochi.classList.remove('show');
+  BUBBLE.loaf.classList.remove('show');
+  clearTalk();
+  pounce();
+  await wait(280);
+  for (const line of exchange) {
+    if (token !== playToken) return;
+    clearTalk();
+    setBubble(line.who, line.text);
+    await wait(2200 + Math.min(3200, line.text.length * 55));
+  }
+  if (token === playToken) clearTalk();
+}
+
+// ---------------------------------------------------------------- poll loop
+let curExchange = [];
+async function poll() {
+  try {
+    const s = await (await fetch('/api/duo')).json();
+    $('scene-text').textContent = s.scene || '…';
+    $('think').classList.toggle('on', !!s.thinking);
+    $('vp-dot').classList.toggle('live', !!s.live);
+    // pupils dilate in the dark (real cat-eye behaviour)
+    const light = typeof s.light === 'number' ? s.light : 60;
+    dilationGoal = light < 0 ? 1 : light < 22 ? 1.7 : light > 70 ? 0.82 : 1.05;
+    const ex = Array.isArray(s.exchange) ? s.exchange : [];
+    const key = ex.map((l) => l.who + ':' + l.text).join('|');
+    if (key && key !== lastKey) { lastKey = key; curExchange = ex; play(ex); }
+  } catch (e) { /* server restarting */ }
+}
+setInterval(poll, 1000);
+poll();
+
+// ---------------------------------------------------------------- reach: drag any image to be judged
+const drop = document.body;
+['dragover', 'dragenter'].forEach((ev) => drop.addEventListener(ev, (e) => {
+  e.preventDefault(); $('dropnote').classList.add('show');
+}));
+['dragleave', 'drop'].forEach((ev) => drop.addEventListener(ev, (e) => {
+  e.preventDefault(); if (ev === 'dragleave' && e.relatedTarget) return; $('dropnote').classList.remove('show');
+}));
+drop.addEventListener('drop', async (e) => {
+  const file = e.dataTransfer?.files?.[0];
+  if (!file || !file.type.startsWith('image/')) return;
+  const dataURL = await fileToJpegDataURL(file, 480);
+  $('cam-status').textContent = '';
+  $('scene-text').textContent = 'the committee is examining your offering…';
+  fetch('/api/frame', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: dataURL }),
+  }).catch(() => {});
+});
+
+function fileToJpegDataURL(file, maxW) {
+  return new Promise((resolve) => {
+    const img = new Image();
+    img.onload = () => {
+      const scale = Math.min(1, maxW / img.width);
+      const c = document.createElement('canvas');
+      c.width = Math.round(img.width * scale);
+      c.height = Math.round(img.height * scale);
+      c.getContext('2d').drawImage(img, 0, 0, c.width, c.height);
+      resolve(c.toDataURL('image/jpeg', 0.75));
+    };
+    img.src = URL.createObjectURL(file);
+  });
+}
+
+// ---------------------------------------------------------------- reach: share the verdict
+$('share').addEventListener('click', async () => {
+  if (!curExchange.length) return;
+  const lines = curExchange.map((l) => `${l.who.toUpperCase()}: ${l.text}`).join('\n');
+  const caption = `my cats reviewed me:\n\n${lines}\n\n— judged by two AI cats running locally · #BuildSmall`;
+  try {
+    await navigator.clipboard.writeText(caption);
+    flashShare('verdict copied — go post it');
+  } catch (e) {
+    flashShare('press ⌘C: ' + curExchange.map((l) => l.text).join(' / '));
+  }
+});
+function flashShare(msg) {
+  const el = $('share'); const old = el.textContent;
+  el.textContent = msg; setTimeout(() => { el.textContent = old; }, 1800);
+}

theater/js/main.js

@@ -0,0 +1,145 @@
+// main.js — GLORBVISION boot + state polling + HUD wiring (B1).
+import { Theater } from './scene3d.js';
+import { Bubbles } from './bubbles.js';
+import { Capture } from './capture.js';
+import { initThoughts } from './thoughts.js';
+import { initAlienCard } from './aliencard.js';
+
+const $ = (id) => document.getElementById(id);
+
+initThoughts();
+
+const theater = new Theater($('stage'));
+const bubbles = new Bubbles($('bubble-layer'));
+
+let lastAliens = [];   // latest /api/state aliens, so the card can show a live bubble
+const alienCard = initAlienCard({
+  bubbleFor: (id) => (lastAliens.find((a) => a.id === id) || {}).bubble || null,
+});
+
+const capture = new Capture({
+  onVideo: (video) => theater.setVideo(video),
+  onStatus: (msg) => { $('cam-status').textContent = msg; },
+  egressDot: $('egress-dot'),
+});
+
+// ---------------------------------------------------------------- consent flow
+
+$('start-cam').addEventListener('click', async () => {
+  const btn = $('start-cam');
+  btn.disabled = true;
+  btn.textContent = 'NEGOTIATING WITH YOUR BROWSER…';
+  const ok = await capture.start();
+  $('consent').classList.add('gone');
+  $('stop-cam').hidden = !ok;
+  btn.disabled = false;
+  btn.textContent = 'ALLOW CAMERA — LET THEM WATCH';
+});
+
+$('skip-cam').addEventListener('click', () => {
+  $('consent').classList.add('gone');
+  $('cam-status').textContent = 'no camera — the crowd watches a test pattern.';
+});
+
+$('stop-cam').addEventListener('click', () => {
+  capture.stop();
+  theater.clearVideo();
+  $('stop-cam').hidden = true;
+  $('cam-status').textContent = 'camera off — the device is released.';
+});
+
+// ---------------------------------------------------------------- click: alien card or poke
+
+let lastPoke = 0;
+theater.renderer.domElement.addEventListener('click', (e) => {
+  const id = theater.pick(e.clientX, e.clientY);
+  if (id !== null && id !== undefined) {
+    alienCard.open(id);          // clicked an alien -> dossier card
+    return;
+  }
+  const now = Date.now();        // empty space -> existing poke behavior
+  if (now - lastPoke < 800) return;
+  lastPoke = now;
+  fetch('/api/poke', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{}',
+  }).catch(() => {});
+});
+
+// ---------------------------------------------------------------- HUD + polling
+
+const EVENT_LABELS = {
+  new_scene: 'NEW SCENE',
+  noticed: 'IT SEES US',
+  chant: 'THE CHANT RISES',
+  gasp: 'COLLECTIVE GASP',
+  ovation: 'STANDING OVATION',
+  wave: 'STADIUM WAVE',
+  boo: 'BOOOOO',
+  intermission: 'INTERMISSION',
+};
+
+let prevEventField = null;
+let splashEl = null;
+
+function splash(text) {
+  if (splashEl) splashEl.remove();
+  splashEl = document.createElement('div');
+  splashEl.id = 'event-label';
+  splashEl.textContent = text;
+  document.body.appendChild(splashEl);
+  const el = splashEl;
+  setTimeout(() => { if (el.isConnected) el.remove(); }, 1700);
+}
+
+function updateHud(s) {
+  $('scene-text').textContent = s.scene || 'awaiting first transmission from Earth…';
+  if (s.factions) {
+    $('f-love').textContent = s.factions.love ?? 0;
+    $('f-meh').textContent = s.factions.meh ?? 0;
+    $('f-hate').textContent = s.factions.hate ?? 0;
+  }
+  const pill = $('live-pill');
+  pill.textContent = s.live ? 'LIVE' : 'NO SIGNAL';
+  pill.classList.toggle('on', !!s.live);
+  $('thinking').hidden = !s.thinking;
+
+  if (s.event !== prevEventField) {
+    if (s.event && EVENT_LABELS[s.event]) splash(EVENT_LABELS[s.event]);
+    prevEventField = s.event;
+  }
+
+  alienCard.setRumor(s.rumor);   // RUMOR MILL line under the factions HUD
+}
+
+let offlineSince = 0;
+
+async function poll() {
+  try {
+    const res = await fetch('/api/state');
+    if (!res.ok) throw new Error('bad status');
+    const state = await res.json();
+    offlineSince = 0;
+    lastAliens = Array.isArray(state.aliens) ? state.aliens : [];
+    theater.applyState(state);
+    bubbles.applyState(state.aliens);
+    updateHud(state);
+  } catch (err) {
+    if (!offlineSince) offlineSince = Date.now();
+    if (Date.now() - offlineSince > 2500) {
+      const pill = $('live-pill');
+      pill.textContent = 'SERVER OFFLINE';
+      pill.classList.remove('on');
+    }
+  }
+}
+
+setInterval(poll, 500);
+poll();
+
+// bubbles track their aliens every animation frame so they ride the bob/wave
+(function loop() {
+  bubbles.reposition(theater);
+  requestAnimationFrame(loop);
+})();

theater/js/scene3d.js

@@ -0,0 +1,785 @@
+// scene3d.js — GLORBVISION amphitheater (B1 frontend).
+// 120 sprite aliens in 8 curved rows x 15 seats facing a giant webcam screen.
+// Sprite sheets come from /theater/assets/aliens/<archetype>.png (12 frames x 32px);
+// when a sheet is missing we draw a placeholder blob sheet on a canvas so the
+// theater always renders.
+import * as THREE from 'three';
+
+export const MOODS = ['calm', 'excited', 'annoyed', 'scared', 'delighted', 'confused'];
+const MOOD_INDEX = Object.fromEntries(MOODS.map((m, i) => [m, i]));
+const MOOD_SCALE = {
+  calm:      { x: 1.00, y: 1.00 },
+  excited:   { x: 0.95, y: 1.20 },
+  annoyed:   { x: 1.05, y: 0.92 },
+  scared:    { x: 1.30, y: 0.60 },
+  delighted: { x: 1.00, y: 1.10 },
+  confused:  { x: 1.00, y: 1.00 },
+};
+const FACTION_COLORS = {
+  love: new THREE.Color('#ff6fa5'),
+  meh:  new THREE.Color('#3e5c66'),
+  hate: new THREE.Color('#ff3b30'),
+};
+const CONFETTI_PALETTE = ['#ff6fa5', '#58e6e6', '#ffd35a', '#9dff5a', '#ff5ad6'];
+const EVENT_DURATION = {
+  new_scene: 2, noticed: 4, chant: 6, gasp: 4,
+  ovation: 6, wave: 5, boo: 4, intermission: Infinity,
+};
+
+const SCREEN_C = new THREE.Vector3(0, 3.4, -10);
+const SCREEN_H = 4.6;          // screen plane height (world units)
+const SPRITE_SIZE = 1.05;
+const ROWS = 8, SEATS = 15;
+
+function seatPosition(row, seat) {
+  const r = 5.5 + row * 1.35;
+  const theta = (seat / (SEATS - 1) - 0.5) * (140 * Math.PI / 180);
+  return new THREE.Vector3(
+    SCREEN_C.x + Math.sin(theta) * r,
+    0.45 + row * 0.55,
+    SCREEN_C.z + Math.cos(theta) * r,
+  );
+}
+
+function pixelTex(tex) {
+  tex.magFilter = THREE.NearestFilter;
+  tex.minFilter = THREE.NearestFilter;
+  tex.generateMipmaps = false;
+  tex.colorSpace = THREE.SRGBColorSpace;
+  return tex;
+}
+
+function frameClone(base) {
+  const t = base.clone();
+  t.needsUpdate = true;
+  t.repeat.set(1 / 12, 1);
+  t.offset.set(0, 0);
+  return t;
+}
+
+function shadeHex(hex, f) {
+  const n = parseInt(String(hex).replace('#', ''), 16);
+  const r = Math.round(((n >> 16) & 255) * f);
+  const g = Math.round(((n >> 8) & 255) * f);
+  const b = Math.round((n & 255) * f);
+  return `rgb(${r},${g},${b})`;
+}
+
+// ---------------------------------------------------------------- placeholder art
+
+function drawEye(ctx, mood, ex, ey, dark) {
+  const white = '#ffffff', pupil = '#1a0f30';
+  const disc = (x, y, r, col) => {
+    ctx.fillStyle = col;
+    ctx.beginPath();
+    ctx.arc(x, y, r, 0, Math.PI * 2);
+    ctx.fill();
+  };
+  switch (mood) {
+    case 'calm':
+      disc(ex, ey, 6, white); disc(ex, ey + 1, 2, pupil);
+      ctx.fillStyle = dark; ctx.fillRect(ex - 6, ey - 7, 12, 6);
+      break;
+    case 'excited':
+      disc(ex, ey, 7, white); disc(ex, ey, 3, pupil);
+      break;
+    case 'annoyed':
+      ctx.fillStyle = white; ctx.fillRect(ex - 6, ey - 2, 12, 4);
+      ctx.fillStyle = pupil; ctx.fillRect(ex - 6, ey - 2, 12, 2);
+      break;
+    case 'scared':
+      disc(ex, ey, 7, white); disc(ex, ey, 1.3, pupil);
+      break;
+    case 'delighted':
+      disc(ex, ey, 7, white);
+      ctx.fillStyle = pupil;
+      ctx.fillRect(ex - 1, ey - 4, 2, 8);
+      ctx.fillRect(ex - 4, ey - 1, 8, 2);
+      break;
+    case 'confused':
+      disc(ex, ey, 7, white);
+      ctx.strokeStyle = pupil; ctx.lineWidth = 1.5;
+      ctx.beginPath();
+      ctx.arc(ex, ey, 3.4, 0, Math.PI * 1.5);
+      ctx.arc(ex, ey, 1.6, Math.PI * 1.5, Math.PI * 3);
+      ctx.stroke();
+      break;
+  }
+}
+
+function makePlaceholderSheet(colorHex) {
+  const c = document.createElement('canvas');
+  c.width = 384; c.height = 32;
+  const ctx = c.getContext('2d');
+  const dark = shadeHex(colorHex, 0.45);
+  for (let m = 0; m < 6; m++) {
+    for (let p = 0; p < 2; p++) {
+      const ox = (m * 2 + p) * 32;
+      const mood = MOODS[m];
+      let w = 24, h = 18;
+      if (mood === 'excited') h = 22;
+      if (mood === 'scared') { w = 31; h = 11; }
+      const bob = p === 1 ? (mood === 'excited' ? -2 : 1) : 0;
+      const bx = Math.round(ox + 16 - w / 2);
+      const by = 30 - h + bob;
+      ctx.fillStyle = dark;
+      ctx.fillRect(bx - 1, by - 1, w + 2, h + 2);
+      ctx.fillStyle = colorHex;
+      ctx.fillRect(bx, by, w, h);
+      // antennae
+      ctx.fillStyle = dark;
+      ctx.fillRect(ox + 11, by - 4, 1, 4);
+      ctx.fillRect(ox + 20, by - 4, 1, 4);
+      ctx.fillRect(ox + 10, by - 6, 2, 2);
+      ctx.fillRect(ox + 19, by - 6, 2, 2);
+      drawEye(ctx, mood, ox + 16, by + Math.round(h * 0.45), dark);
+    }
+  }
+  return pixelTex(new THREE.CanvasTexture(c));
+}
+
+function makeScreenPlaceholder() {
+  const c = document.createElement('canvas');
+  c.width = 512; c.height = 384;
+  const ctx = c.getContext('2d');
+  ctx.fillStyle = '#07030f';
+  ctx.fillRect(0, 0, 512, 384);
+  ctx.fillStyle = 'rgba(88,230,230,0.10)';
+  for (let i = 0; i < 700; i++) {
+    ctx.fillRect(Math.random() * 512, Math.random() * 384, 2, 2);
+  }
+  ctx.fillStyle = '#58e6e6';
+  ctx.font = 'bold 34px monospace';
+  ctx.textAlign = 'center';
+  ctx.fillText('AWAITING EARTH FEED', 256, 180);
+  ctx.font = '18px monospace';
+  ctx.fillStyle = '#ffd35a';
+  ctx.fillText('the Blorps grow restless', 256, 218);
+  return pixelTex(new THREE.CanvasTexture(c));
+}
+
+function makeScanlineTex() {
+  const c = document.createElement('canvas');
+  c.width = 1; c.height = 2;
+  const ctx = c.getContext('2d');
+  ctx.clearRect(0, 0, 1, 2);
+  ctx.fillStyle = 'rgba(0,0,0,0.85)';
+  ctx.fillRect(0, 1, 1, 1);
+  const tex = new THREE.CanvasTexture(c);
+  tex.magFilter = THREE.NearestFilter;
+  tex.minFilter = THREE.NearestFilter;
+  tex.wrapS = THREE.RepeatWrapping;
+  tex.wrapT = THREE.RepeatWrapping;
+  tex.repeat.set(1, 150);
+  return tex;
+}
+
+function makeGlowTex() {
+  const c = document.createElement('canvas');
+  c.width = 32; c.height = 32;
+  const ctx = c.getContext('2d');
+  const g = ctx.createRadialGradient(16, 16, 1, 16, 16, 15);
+  g.addColorStop(0, 'rgba(255,255,255,0.9)');
+  g.addColorStop(0.55, 'rgba(255,255,255,0.35)');
+  g.addColorStop(1, 'rgba(255,255,255,0)');
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, 32, 32);
+  return new THREE.CanvasTexture(c);
+}
+
+function makeRingTex() {
+  const c = document.createElement('canvas');
+  c.width = 64; c.height = 64;
+  const ctx = c.getContext('2d');
+  ctx.strokeStyle = 'rgba(255,255,255,1)';
+  ctx.lineWidth = 5;
+  ctx.beginPath();
+  ctx.arc(32, 32, 27, 0, Math.PI * 2);
+  ctx.stroke();
+  return new THREE.CanvasTexture(c);
+}
+
+function makeFlameSheet() {
+  const c = document.createElement('canvas');
+  c.width = 64; c.height = 32;
+  const ctx = c.getContext('2d');
+  for (let f = 0; f < 4; f++) {
+    const ox = f * 16;
+    const sway = [0, 1.5, -1, 0.5][f];
+    ctx.fillStyle = '#ffb84d';
+    ctx.beginPath();
+    ctx.ellipse(ox + 8 + sway, 18, 5, 11 + f % 2, 0, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = '#ffd35a';
+    ctx.beginPath();
+    ctx.ellipse(ox + 8 + sway * 0.6, 22, 3, 6, 0, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = '#fff7d0';
+    ctx.beginPath();
+    ctx.ellipse(ox + 8 + sway * 0.3, 25, 1.5, 3, 0, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  const tex = pixelTex(new THREE.CanvasTexture(c));
+  tex.repeat.set(1 / 4, 1);
+  return tex;
+}
+
+// ---------------------------------------------------------------- theater
+
+export class Theater {
+  constructor(container) {
+    this.renderer = new THREE.WebGLRenderer({ antialias: false });
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+    container.appendChild(this.renderer.domElement);
+
+    this.scene = new THREE.Scene();
+    this.scene.background = new THREE.Color('#100822');
+    this.scene.fog = new THREE.Fog(0x100822, 20, 44);
+
+    this.camera = new THREE.PerspectiveCamera(55, 1, 0.1, 120);
+    this.cameraBase = new THREE.Vector3(0, 8.8, 10.8);
+    this.camera.position.copy(this.cameraBase);
+    this.camera.lookAt(SCREEN_C);
+
+    this.ambient = new THREE.AmbientLight(0xffffff, 0.6);
+    this.ambientBaseColor = new THREE.Color(0xb9aaff);
+    this.ambient.color.copy(this.ambientBaseColor);
+    this.scene.add(this.ambient);
+
+    this.screenLight = new THREE.PointLight(0x58e6e6, 16, 34, 1.6);
+    this.screenLight.position.set(0, 4.2, -7.5);
+    this.scene.add(this.screenLight);
+
+    // ---- shared state
+    this.aliens = new Map();          // id -> alien record
+    this.prevEventField = undefined;
+    this.event = null;
+    this.eventStart = 0;
+    this.light = -1;
+    this.sound = -1;
+    this.live = false;
+    this.lightFactor = 1;
+    this.videoTex = null;
+    this.mirror = false;
+    this.screenAspect = 4 / 3;
+    this.lastNow = performance.now() / 1000;
+    this.lastStatic = 0;
+    this.lastChyron = 0;
+    this._v = new THREE.Vector3();
+    this._tileTarget = new THREE.Color();
+    this._raycaster = new THREE.Raycaster();
+    this._pickNDC = new THREE.Vector2();
+    this._pickSprites = [];
+
+    this._buildGround();
+    this._buildScreen();
+    this._buildTorches();
+    this._buildChantRing();
+    this._buildConfetti();
+
+    window.addEventListener('resize', () => this._resize());
+    this._resize();
+    this.renderer.setAnimationLoop(() => this._render());
+  }
+
+  // ------------------------------------------------------------- construction
+
+  _buildGround() {
+    const ground = new THREE.Mesh(
+      new THREE.CircleGeometry(30, 40),
+      new THREE.MeshLambertMaterial({ color: 0x1a0f30 }),
+    );
+    ground.rotation.x = -Math.PI / 2;
+    ground.position.y = -0.01;
+    this.scene.add(ground);
+
+    // a low stage apron in front of the screen
+    const stage = new THREE.Mesh(
+      new THREE.BoxGeometry(11.5, 0.5, 3),
+      new THREE.MeshLambertMaterial({ color: 0x2a1a4a }),
+    );
+    stage.position.set(SCREEN_C.x, 0.25, SCREEN_C.z + 1.2);
+    this.scene.add(stage);
+  }
+
+  _buildScreen() {
+    // black backing behind whatever aspect the feed has
+    const backing = new THREE.Mesh(
+      new THREE.PlaneGeometry(SCREEN_H * (16 / 9) + 0.2, SCREEN_H + 0.2),
+      new THREE.MeshBasicMaterial({ color: 0x000000 }),
+    );
+    backing.position.copy(SCREEN_C);
+    backing.position.z -= 0.03;
+    this.scene.add(backing);
+
+    this.placeholderTex = makeScreenPlaceholder();
+    this.screenMat = new THREE.MeshBasicMaterial({ map: this.placeholderTex });
+    this.screenMesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), this.screenMat);
+    this.screenMesh.position.copy(SCREEN_C);
+    this._fitScreen();
+    this.scene.add(this.screenMesh);
+
+    // scanline overlay
+    const slMat = new THREE.MeshBasicMaterial({
+      map: makeScanlineTex(), transparent: true, opacity: 0.22, depthWrite: false,
+    });
+    const sl = new THREE.Mesh(
+      new THREE.PlaneGeometry(SCREEN_H * (16 / 9) + 0.2, SCREEN_H + 0.2), slMat,
+    );
+    sl.position.copy(SCREEN_C);
+    sl.position.z += 0.02;
+    this.scene.add(sl);
+
+    // intermission static overlay
+    this.staticCanvas = document.createElement('canvas');
+    this.staticCanvas.width = 128; this.staticCanvas.height = 96;
+    this.staticCtx = this.staticCanvas.getContext('2d');
+    this.staticTex = pixelTex(new THREE.CanvasTexture(this.staticCanvas));
+    this.staticMesh = new THREE.Mesh(
+      new THREE.PlaneGeometry(SCREEN_H * (16 / 9) + 0.2, SCREEN_H + 0.2),
+      new THREE.MeshBasicMaterial({ map: this.staticTex }),
+    );
+    this.staticMesh.position.copy(SCREEN_C);
+    this.staticMesh.position.z += 0.04;
+    this.staticMesh.visible = false;
+    this.scene.add(this.staticMesh);
+
+    // stone frame (emissive flashes on new_scene)
+    this.frameMat = new THREE.MeshLambertMaterial({
+      color: 0x2a1a4a, emissive: 0x58e6e6, emissiveIntensity: 0,
+    });
+    const fw = SCREEN_H * (16 / 9) + 1.0;
+    const fh = SCREEN_H + 1.0;
+    const t = 0.45, d = 0.5;
+    const mk = (w, h, x, y) => {
+      const m = new THREE.Mesh(new THREE.BoxGeometry(w, h, d), this.frameMat);
+      m.position.set(SCREEN_C.x + x, SCREEN_C.y + y, SCREEN_C.z - 0.1);
+      this.scene.add(m);
+    };
+    mk(fw, t, 0, fh / 2 - t / 2);
+    mk(fw, t, 0, -fh / 2 + t / 2);
+    mk(t, fh, fw / 2 - t / 2, 0);
+    mk(t, fh, -fw / 2 + t / 2, 0);
+    // legs
+    const legMat = new THREE.MeshLambertMaterial({ color: 0x2a1a4a });
+    for (const sx of [-1, 1]) {
+      const leg = new THREE.Mesh(new THREE.BoxGeometry(0.5, SCREEN_C.y, 0.5), legMat);
+      leg.position.set(sx * (fw / 2 - 0.3), SCREEN_C.y / 2 - fh / 2 + 0.2, SCREEN_C.z - 0.1);
+      this.scene.add(leg);
+    }
+
+    // chyron strip under the screen
+    this.chyronCanvas = document.createElement('canvas');
+    this.chyronCanvas.width = 1024; this.chyronCanvas.height = 56;
+    this.chyronTex = pixelTex(new THREE.CanvasTexture(this.chyronCanvas));
+    const chyron = new THREE.Mesh(
+      new THREE.PlaneGeometry(fw, fw * 56 / 1024),
+      new THREE.MeshBasicMaterial({ map: this.chyronTex }),
+    );
+    chyron.position.set(SCREEN_C.x, SCREEN_C.y - fh / 2 - 0.35, SCREEN_C.z + 0.05);
+    this.scene.add(chyron);
+    this._drawChyron();
+  }
+
+  _fitScreen() {
+    const a = Math.min(this.screenAspect, 16 / 9);
+    this.screenMesh.scale.set((this.mirror ? -1 : 1) * SCREEN_H * a, SCREEN_H, 1);
+  }
+
+  _drawChyron() {
+    const ctx = this.chyronCanvas.getContext('2d');
+    ctx.fillStyle = '#07030f';
+    ctx.fillRect(0, 0, 1024, 56);
+    ctx.fillStyle = '#58e6e6';
+    ctx.fillRect(0, 0, 1024, 3);
+    ctx.font = 'bold 30px monospace';
+    ctx.textBaseline = 'middle';
+    ctx.fillStyle = '#ffd35a';
+    ctx.fillText('EARTH FEED — CYCLE 4,071 —', 24, 30);
+    ctx.fillStyle = this.live ? '#ff3b30' : '#3e5c66';
+    ctx.beginPath(); ctx.arc(540, 28, 9, 0, Math.PI * 2); ctx.fill();
+    ctx.fillStyle = this.live ? '#ffffff' : '#8fb3bd';
+    ctx.fillText(this.live ? 'LIVE' : 'NO SIGNAL', 558, 30);
+    this.chyronTex.needsUpdate = true;
+  }
+
+  _buildTorches() {
+    this.flameSheet = makeFlameSheet();
+    this.torches = [];
+    const fw = SCREEN_H * (16 / 9) + 1.0;
+    for (const sx of [-1, 1]) {
+      const tex = this.flameSheet.clone();
+      tex.needsUpdate = true;
+      tex.repeat.set(1 / 4, 1);
+      const spr = new THREE.Sprite(new THREE.SpriteMaterial({
+        map: tex, transparent: true, depthWrite: false,
+      }));
+      spr.position.set(sx * (fw / 2 + 1.1), 2.6, SCREEN_C.z + 0.4);
+      spr.scale.set(1.0, 2.0, 1);
+      this.scene.add(spr);
+      const pole = new THREE.Mesh(
+        new THREE.BoxGeometry(0.22, 2.4, 0.22),
+        new THREE.MeshLambertMaterial({ color: 0x2a1a4a }),
+      );
+      pole.position.set(spr.position.x, 1.0, spr.position.z);
+      this.scene.add(pole);
+      const light = new THREE.PointLight(0xffb84d, 4, 12, 1.8);
+      light.position.copy(spr.position);
+      this.scene.add(light);
+      this.torches.push({ spr, tex, light, phase: sx * 1.7 });
+    }
+  }
+
+  _buildChantRing() {
+    this.ringMat = new THREE.MeshBasicMaterial({
+      map: makeRingTex(), color: 0xffd35a, transparent: true, opacity: 0,
+      blending: THREE.AdditiveBlending, depthWrite: false,
+    });
+    this.ring = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), this.ringMat);
+    this.ring.rotation.x = -Math.PI / 2;
+    const front = seatPosition(0, 7);
+    this.ring.position.set(front.x, 0.12, front.z);
+    this.ring.visible = false;
+    this.scene.add(this.ring);
+  }
+
+  _buildConfetti() {
+    this.confetti = new THREE.Group();
+    this.confettiBits = [];
+    const c = document.createElement('canvas');
+    c.width = 8; c.height = 8;
+    const cctx = c.getContext('2d');
+    cctx.fillStyle = '#ffffff';
+    cctx.fillRect(0, 0, 8, 8);
+    const tex = pixelTex(new THREE.CanvasTexture(c));
+    for (let i = 0; i < 110; i++) {
+      const mat = new THREE.SpriteMaterial({
+        map: tex, color: CONFETTI_PALETTE[i % CONFETTI_PALETTE.length],
+        transparent: true, depthWrite: false,
+      });
+      const s = new THREE.Sprite(mat);
+      const bit = {
+        s,
+        x: (Math.random() - 0.5) * 18,
+        z: -8 + Math.random() * 12,
+        speed: 1.6 + Math.random() * 2.2,
+        phase: Math.random() * Math.PI * 2,
+        y: 6 + Math.random() * 7,
+      };
+      s.scale.set(0.14, 0.14, 1);
+      s.position.set(bit.x, bit.y, bit.z);
+      this.confetti.add(s);
+      this.confettiBits.push(bit);
+    }
+    this.confetti.visible = false;
+    this.scene.add(this.confetti);
+  }
+
+  // ------------------------------------------------------------- aliens
+
+  _ensureAliens(list) {
+    if (this.aliens.size || !Array.isArray(list) || !list.length) return;
+    const loader = new THREE.TextureLoader();
+    const glowTex = makeGlowTex();
+    const tileGeom = new THREE.PlaneGeometry(0.95, 0.95);
+    const pedestalGeom = new THREE.BoxGeometry(1, 1, 1);
+    const pedestalMat = new THREE.MeshLambertMaterial({ color: 0x2a1a4a });
+
+    // group archetypes so each sheet loads once
+    const byArch = new Map();
+    for (const a of list) {
+      if (!byArch.has(a.archetype)) byArch.set(a.archetype, { color: a.color || '#9dff5a', ids: [] });
+      byArch.get(a.archetype).ids.push(a.id);
+    }
+    const placeholders = new Map();
+    for (const [arch, info] of byArch) {
+      placeholders.set(arch, makePlaceholderSheet(info.color));
+    }
+
+    for (const a of list) {
+      const pos = seatPosition(a.row, a.seat);
+      const baseY = pos.y + 0.55;
+
+      const pedestal = new THREE.Mesh(pedestalGeom, pedestalMat);
+      pedestal.scale.set(1.04, pos.y, 1.04);
+      pedestal.position.set(pos.x, pos.y / 2, pos.z);
+      pedestal.rotation.y = Math.atan2(SCREEN_C.x - pos.x, SCREEN_C.z - pos.z);
+      this.scene.add(pedestal);
+
+      const tileMat = new THREE.MeshBasicMaterial({
+        map: glowTex, color: FACTION_COLORS.meh.clone(), transparent: true,
+        opacity: 0.3, blending: THREE.AdditiveBlending, depthWrite: false,
+      });
+      const tile = new THREE.Mesh(tileGeom, tileMat);
+      tile.rotation.x = -Math.PI / 2;
+      tile.position.set(pos.x, pos.y + 0.02, pos.z);
+      this.scene.add(tile);
+
+      const map = frameClone(placeholders.get(a.archetype));
+      const sprite = new THREE.Sprite(new THREE.SpriteMaterial({
+        map, transparent: true, alphaTest: 0.05, depthWrite: false,
+      }));
+      sprite.position.set(pos.x, baseY, pos.z);
+      sprite.scale.set(SPRITE_SIZE, SPRITE_SIZE, 1);
+      sprite.userData.alienId = a.id;
+      this.scene.add(sprite);
+      this._pickSprites.push(sprite);
+
+      this.aliens.set(a.id, {
+        id: a.id, row: a.row, seat: a.seat, archetype: a.archetype,
+        sprite, tileMat,
+        baseY,
+        phase: ((a.id * 2654435761) % 997) / 997,
+        mood: a.mood || 'calm',
+        sentiment: a.sentiment || 0,
+        frame: -1,
+        sx: 1, sy: 1,
+      });
+    }
+
+    // try to swap in the real sheets (B5's PNGs); keep placeholders on 404
+    for (const [arch, info] of byArch) {
+      loader.load(
+        `/theater/assets/aliens/${arch}.png`,
+        (tex) => {
+          pixelTex(tex);
+          for (const id of info.ids) {
+            const al = this.aliens.get(id);
+            if (!al) continue;
+            al.sprite.material.map = frameClone(tex);
+            al.sprite.material.needsUpdate = true;
+            al.frame = -1; // force offset refresh
+          }
+        },
+        undefined,
+        () => { /* sheet missing — placeholder blobs stay */ },
+      );
+    }
+  }
+
+  // ------------------------------------------------------------- state from server
+
+  applyState(state) {
+    if (!state || !Array.isArray(state.aliens)) return;
+    this._ensureAliens(state.aliens);
+    for (const a of state.aliens) {
+      const al = this.aliens.get(a.id);
+      if (!al) continue;
+      al.mood = MOOD_INDEX[a.mood] !== undefined ? a.mood : 'calm';
+      al.sentiment = typeof a.sentiment === 'number' ? a.sentiment : 0;
+    }
+    this.light = typeof state.light === 'number' ? state.light : -1;
+    this.sound = typeof state.sound === 'number' ? state.sound : -1;
+    const liveChanged = this.live !== !!state.live;
+    this.live = !!state.live;
+    if (liveChanged) this._drawChyron();
+
+    if (state.event !== this.prevEventField) {
+      this.prevEventField = state.event;
+      if (state.event && EVENT_DURATION[state.event] !== undefined) {
+        this.event = state.event;
+        this.eventStart = performance.now() / 1000;
+      }
+    }
+    // intermission lasts only while the server says so
+    if (this.event === 'intermission' && state.event !== 'intermission') {
+      this.event = null;
+    }
+  }
+
+  setVideo(video) {
+    if (this.videoTex) this.clearVideo();
+    this.videoTex = new THREE.VideoTexture(video);   // auto-updates; never set needsUpdate
+    this.videoTex.colorSpace = THREE.SRGBColorSpace;
+    this.screenAspect = (video.videoWidth / video.videoHeight) || 4 / 3;
+    this.mirror = true;                              // selfie mirror
+    this.screenMat.map = this.videoTex;
+    this.screenMat.needsUpdate = true;
+    this._fitScreen();
+  }
+
+  clearVideo() {
+    if (this.videoTex) { this.videoTex.dispose(); this.videoTex = null; }
+    this.screenMat.map = this.placeholderTex;
+    this.screenMat.needsUpdate = true;
+    this.mirror = false;
+    this.screenAspect = 4 / 3;
+    this._fitScreen();
+  }
+
+  /** Alien id under client pixel (x,y) via raycast over the crowd sprites,
+   *  or null when the click hit empty space (canvas fills the window, so
+   *  client coords map straight to NDC). */
+  pick(x, y) {
+    if (!this._pickSprites.length) return null;
+    this._pickNDC.set(
+      (x / window.innerWidth) * 2 - 1,
+      -(y / window.innerHeight) * 2 + 1,
+    );
+    this._raycaster.setFromCamera(this._pickNDC, this.camera);
+    const hits = this._raycaster.intersectObjects(this._pickSprites, false);
+    for (const hit of hits) {
+      const id = hit.object.userData.alienId;
+      if (id !== undefined) return id;
+    }
+    return null;
+  }
+
+  /** Screen-space px position above an alien's head, or null when behind camera. */
+  projectAlien(id) {
+    const al = this.aliens.get(id);
+    if (!al) return null;
+    this._v.copy(al.sprite.position);
+    this._v.y += 0.78;
+    this._v.project(this.camera);
+    if (this._v.z > 1) return null;
+    return {
+      x: (this._v.x * 0.5 + 0.5) * window.innerWidth,
+      y: (-this._v.y * 0.5 + 0.5) * window.innerHeight,
+    };
+  }
+
+  // ------------------------------------------------------------- per-frame
+
+  _resize() {
+    const w = window.innerWidth, h = window.innerHeight;
+    this.renderer.setSize(w, h);
+    this.camera.aspect = w / h;
+    this.camera.updateProjectionMatrix();
+  }
+
+  _render() {
+    const now = performance.now() / 1000;
+    const dt = Math.min(now - this.lastNow, 0.1);
+    this.lastNow = now;
+
+    // expire event
+    let ev = this.event;
+    let et = now - this.eventStart;
+    if (ev && et > (EVENT_DURATION[ev] ?? 4)) { this.event = null; ev = null; }
+
+    // --- lighting
+    const targetFactor = ev === 'gasp' ? 0.1 : ev === 'boo' ? 0.45 : 1;
+    this.lightFactor += (targetFactor - this.lightFactor) * Math.min(1, dt * 6);
+    const lightVal = this.light < 0 ? 60 : this.light;
+    const base = 0.25 + 0.6 * (lightVal / 100);
+    this.ambient.intensity = base * this.lightFactor * 1.4;
+    this.ambient.color.copy(this.ambientBaseColor);
+    if (ev === 'boo') this.ambient.color.lerp(new THREE.Color(0xff3b30), 0.6);
+    this.screenLight.intensity = 16 * (0.4 + 0.6 * this.lightFactor);
+
+    // --- camera idle drift (±2°)
+    const drift = Math.sin(now * 0.13) * 0.035;
+    this.camera.position.set(
+      this.cameraBase.x + Math.sin(drift) * 14,
+      this.cameraBase.y + Math.sin(now * 0.09) * 0.25,
+      this.cameraBase.z,
+    );
+    this.camera.lookAt(SCREEN_C.x, SCREEN_C.y - 0.4, SCREEN_C.z);
+
+    // --- screen frame flash on new_scene
+    if (ev === 'new_scene') {
+      const k = Math.max(0, 1 - et / 2);
+      this.frameMat.emissiveIntensity = k * (0.55 + 0.45 * Math.sin(et * 22));
+    } else {
+      this.frameMat.emissiveIntensity *= Math.max(0, 1 - dt * 5);
+    }
+
+    // --- intermission static
+    this.staticMesh.visible = ev === 'intermission';
+    if (this.staticMesh.visible && now - this.lastStatic > 0.1) {
+      this.lastStatic = now;
+      const img = this.staticCtx.createImageData(128, 96);
+      for (let i = 0; i < img.data.length; i += 4) {
+        const v = Math.random() * 255;
+        img.data[i] = v * 0.7; img.data[i + 1] = v * 0.65; img.data[i + 2] = v;
+        img.data[i + 3] = 255;
+      }
+      this.staticCtx.putImageData(img, 0, 0);
+      this.staticTex.needsUpdate = true;
+    }
+
+    // --- chant pulse ring
+    if (ev === 'chant') {
+      this.ring.visible = true;
+      const cyc = (et % 2) / 2;
+      const s = 1 + cyc * 30;
+      this.ring.scale.set(s, s, 1);
+      this.ringMat.opacity = (1 - cyc) * 0.85;
+    } else {
+      this.ring.visible = false;
+    }
+
+    // --- confetti (ovation)
+    this.confetti.visible = ev === 'ovation';
+    if (this.confetti.visible) {
+      for (const b of this.confettiBits) {
+        b.y -= b.speed * dt;
+        if (b.y < 0.2) b.y = 6 + Math.random() * 7;
+        b.s.position.set(b.x + Math.sin(now * 3 + b.phase) * 0.4, b.y, b.z);
+      }
+    }
+
+    // --- torches (flicker amplitude from sound)
+    const soundVal = this.sound < 0 ? 20 : this.sound;
+    const amp = soundVal / 100;
+    for (const t of this.torches) {
+      const fps = 5 + amp * 9;
+      const fr = Math.floor(now * fps + t.phase * 3) % 4;
+      t.tex.offset.x = fr / 4;
+      t.spr.scale.y = 2.0 * (1 + 0.18 * amp * Math.sin(now * 15 + t.phase * 7));
+      t.light.intensity = (3.2 + Math.sin(now * 12 + t.phase * 5) * 2.6 * amp) * this.lightFactor;
+    }
+
+    // --- crowd
+    const freeze = ev === 'noticed' && et < 2;
+    const eyesWideMood = ev === 'gasp' ? 'excited' : freeze ? 'scared' : null;
+    const chantSync = ev === 'chant';
+    const waveProg = ev === 'wave' ? (et / 5) * (SEATS + 3) - 1.5 : -99;
+    const lerpK = Math.min(1, dt * 7);
+
+    for (const al of this.aliens.values()) {
+      const mood = eyesWideMood || al.mood;
+      const mi = MOOD_INDEX[mood];
+
+      let pose;
+      if (freeze) pose = 0;
+      else if (chantSync) pose = Math.floor(now * 4) % 2;
+      else pose = Math.floor(now * 2.4 + al.phase * 2) % 2;
+      const frame = mi * 2 + pose;
+      if (frame !== al.frame) {
+        al.frame = frame;
+        al.sprite.material.map.offset.x = frame / 12;
+      }
+
+      const tgt = MOOD_SCALE[mood];
+      let ty = tgt.y;
+      if (ev === 'ovation') ty *= 1.22;
+      al.sx += (tgt.x - al.sx) * lerpK;
+      al.sy += (ty - al.sy) * lerpK;
+      al.sprite.scale.set(SPRITE_SIZE * al.sx, SPRITE_SIZE * al.sy, 1);
+
+      let y = al.baseY;
+      if (!freeze) {
+        if (chantSync) y += Math.abs(Math.sin(now * 5)) * 0.22;
+        else y += Math.sin(now * 2 + al.phase * Math.PI * 2) * 0.045;
+      }
+      if (ev === 'wave') {
+        const d = waveProg - al.seat;
+        if (d > 0 && d < 2) y += Math.sin((d / 2) * Math.PI) * 0.55;
+      }
+      if (ev === 'ovation') y += 0.18;
+      al.sprite.position.y = y;
+
+      // faction floor tile — the contagion made visible
+      const s = al.sentiment;
+      const fc = s > 0.25 ? FACTION_COLORS.love : s < -0.25 ? FACTION_COLORS.hate : FACTION_COLORS.meh;
+      this._tileTarget.copy(fc);
+      if (chantSync) this._tileTarget.lerp(new THREE.Color(0xffd35a), 0.4);
+      al.tileMat.color.lerp(this._tileTarget, Math.min(1, dt * 3.5));
+      al.tileMat.opacity = 0.18 + 0.55 * Math.min(1, Math.abs(s));
+    }
+
+    this.renderer.render(this.scene, this.camera);
+  }
+}

theater/js/thoughts.js

@@ -0,0 +1,125 @@
+// HIVEMIND panel — a collapsible right-side live trace of the pipeline:
+// frame gating -> VLM description -> codex scene -> batched LLM voicing ->
+// contagion events. Self-contained: injects its own DOM + styles, polls
+// GET /api/thoughts incrementally. Entries expand on click.
+
+const KIND_META = {
+  vision: { label: 'VISION', color: 'var(--cyan, #58e6e6)' },
+  voice:  { label: 'VOICE',  color: 'var(--gold, #ffd35a)' },
+  event:  { label: 'EVENT',  color: 'var(--love, #ff6fa5)' },
+  system: { label: 'SYS',    color: 'var(--meh, #8fb3bd)' },
+};
+
+const STYLE = `
+#hivemind {
+  position: fixed; top: 64px; right: 0; bottom: 96px; z-index: 25;
+  width: 340px; max-width: 85vw;
+  display: flex; flex-direction: column;
+  background: rgba(10,5,24,.92);
+  border-left: 1px solid rgba(88,230,230,.35);
+  font: 11px/1.45 "Courier New", ui-monospace, monospace;
+  transition: transform .25s ease;
+}
+#hivemind.collapsed { transform: translateX(100%); }
+#hivemind-toggle {
+  position: absolute; left: -30px; top: 8px; width: 30px; height: 110px;
+  border: 1px solid rgba(88,230,230,.35); border-right: none;
+  border-radius: 6px 0 0 6px; cursor: pointer;
+  background: rgba(10,5,24,.92); color: var(--cyan, #58e6e6);
+  writing-mode: vertical-rl; text-orientation: mixed;
+  font: bold 11px/30px "Courier New", monospace; letter-spacing: 2px;
+  user-select: none;
+}
+#hivemind-head {
+  padding: 8px 10px; color: var(--cyan, #58e6e6); letter-spacing: 2px;
+  border-bottom: 1px solid rgba(88,230,230,.25); font-weight: bold;
+}
+#hivemind-head .sub { color: #8fb3bd; font-weight: normal; letter-spacing: 0; display: block; }
+#hivemind-list { flex: 1; overflow-y: auto; padding: 6px 8px; }
+.hm-item { margin-bottom: 6px; border-left: 2px solid transparent; padding-left: 6px; cursor: pointer; }
+.hm-item .hm-row { display: flex; gap: 6px; align-items: baseline; }
+.hm-kind { font-weight: bold; font-size: 9px; letter-spacing: 1px; flex: none; }
+.hm-title { color: #efeaff; }
+.hm-ts { color: #6b6485; font-size: 9px; flex: none; margin-left: auto; }
+.hm-body {
+  display: none; margin: 3px 0 4px; padding: 5px 7px;
+  background: rgba(255,255,255,.05); border-radius: 4px;
+  color: #c9c2e6; white-space: pre-wrap; word-break: break-word; max-height: 220px; overflow-y: auto;
+}
+.hm-item.open .hm-body { display: block; }
+.hm-item.has-body .hm-title::after { content: ' ▸'; color: #6b6485; }
+.hm-item.open.has-body .hm-title::after { content: ' ▾'; }
+`;
+
+let lastId = 0;
+let listEl = null;
+
+function fmtTs(ts) {
+  const d = new Date(ts * 1000);
+  return d.toTimeString().slice(0, 8);
+}
+
+function addEntry(t) {
+  const meta = KIND_META[t.kind] || KIND_META.system;
+  const item = document.createElement('div');
+  item.className = 'hm-item' + (t.body ? ' has-body' : '');
+  item.style.borderLeftColor = meta.color;
+  const row = document.createElement('div');
+  row.className = 'hm-row';
+  const kind = document.createElement('span');
+  kind.className = 'hm-kind';
+  kind.style.color = meta.color;
+  kind.textContent = meta.label;
+  const title = document.createElement('span');
+  title.className = 'hm-title';
+  title.textContent = t.title;
+  const ts = document.createElement('span');
+  ts.className = 'hm-ts';
+  ts.textContent = fmtTs(t.ts);
+  row.append(kind, title, ts);
+  item.appendChild(row);
+  if (t.body) {
+    const body = document.createElement('div');
+    body.className = 'hm-body';
+    body.textContent = t.body;
+    item.appendChild(body);
+    item.addEventListener('click', () => item.classList.toggle('open'));
+  }
+  const stick = listEl.scrollTop + listEl.clientHeight >= listEl.scrollHeight - 30;
+  listEl.appendChild(item);
+  while (listEl.children.length > 250) listEl.removeChild(listEl.firstChild);
+  if (stick) listEl.scrollTop = listEl.scrollHeight;
+}
+
+async function poll() {
+  try {
+    const res = await fetch(`/api/thoughts?after=${lastId}`);
+    if (!res.ok) return;
+    const data = await res.json();
+    for (const t of data.thoughts || []) addEntry(t);
+    lastId = data.last || lastId;
+  } catch (e) { /* server restarting; retry next tick */ }
+}
+
+export function initThoughts() {
+  const style = document.createElement('style');
+  style.textContent = STYLE;
+  document.head.appendChild(style);
+
+  const panel = document.createElement('aside');
+  panel.id = 'hivemind';
+  panel.className = 'collapsed';
+  panel.innerHTML = `
+    <button id="hivemind-toggle" title="the aliens' thought process">🧠 HIVEMIND</button>
+    <div id="hivemind-head">HIVEMIND FEED
+      <span class="sub">live trace: camera → translator → codex → crowd → voices</span>
+    </div>
+    <div id="hivemind-list"></div>`;
+  document.body.appendChild(panel);
+  listEl = panel.querySelector('#hivemind-list');
+  panel.querySelector('#hivemind-toggle').addEventListener('click', () => {
+    panel.classList.toggle('collapsed');
+  });
+  setInterval(poll, 1000);
+  poll();
+}