feat: initial Lantern Space (agent loop, 3D viewer, live runs)

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+web/assets/kenney-mini-dungeon/character-human.glb filter=lfs diff=lfs merge=lfs -text
+web/assets/kenney-mini-dungeon/character-orc.glb filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+# Spaces run containers as uid 1000.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    LANTERN_DATA=/home/user/app/data
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+COPY --chown=user lantern ./lantern
+COPY --chown=user web ./web
+COPY --chown=user app.py .
+RUN mkdir -p data/episodes
+
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,32 @@
 ---
 title: Lantern
-emoji: 👁
-colorFrom: blue
-colorTo: gray
+emoji: 🏮
+colorFrom: yellow
+colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 7860
+license: apache-2.0
+short_description: Beam explores dungeons, keeps a journal, and learns.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Lantern
+
+Watch [Beam](https://huggingface.co/reflection/Beam-1.0-501B-A23B) explore procedurally
+generated dungeon levels. Each call, Beam reads the map, plans a short sequence of moves,
+keeps working notes, and acts. After every run it writes lessons into a journal that the
+next run on the same level reads first.
+
+Work in progress for the Build with Beam challenge. Full write-up, benchmark results, and
+dataset coming before the deadline.
+
+## Credits
+
+- Levels: [MiniHack](https://github.com/facebookresearch/minihack) (Meta AI, Apache-2.0)
+  on the NetHack Learning Environment.
+- 3D models: [Kenney Mini Dungeon](https://kenney.nl/assets/mini-dungeon) (CC0).
+- Model: Beam 1.0 by Reflection, via Hugging Face Inference Providers.
+
+## Limitations
+
+Beam is an AI model and makes mistakes; these runs are game play only. Live runs are
+limited per day because each one spends inference credits.

app.py

@@ -0,0 +1,175 @@
+"""Lantern web server: runs Beam episodes and streams them to the browser over SSE.
+
+Live runs spend the Space owner's inference credits, so they are limited to one at a
+time and a daily cap. Every finished episode is saved and can be replayed for free.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import threading
+import time
+import uuid
+from datetime import date
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from lantern.agent import EpisodeConfig, run_episode
+from lantern.env import TASKS, DungeonEnv
+from lantern.journal import Journal
+from lantern.llm import ChatClient
+
+DATA_DIR = Path(os.environ.get("LANTERN_DATA", "data"))
+EPISODES_DIR = DATA_DIR / "episodes"
+DAILY_LIVE_RUNS = int(os.environ.get("LANTERN_DAILY_RUNS", "20"))
+WEB_DIR = Path(__file__).parent / "web"
+
+app = FastAPI(title="Lantern")
+journal = Journal(DATA_DIR / "journal.json")
+
+
+class Run:
+    """One live episode running in a background thread, buffering its events."""
+
+    def __init__(self, task_id: str, seed: int, use_lessons: bool):
+        self.id = uuid.uuid4().hex[:12]
+        self.task_id, self.seed, self.use_lessons = task_id, seed, use_lessons
+        self.events: list[dict] = []
+        self.done = False
+        self.stop = threading.Event()
+
+    def start(self) -> None:
+        threading.Thread(target=self._play, daemon=True).start()
+
+    def _play(self) -> None:
+        env = None
+        try:
+            env = DungeonEnv(TASKS[self.task_id], seed=self.seed)
+            lessons = journal.lessons(self.task_id)
+            config = EpisodeConfig(use_lessons=self.use_lessons)
+            for event in run_episode(env, ChatClient(), lessons, config, self.stop):
+                if event["type"] == "end" and event["new_lessons"]:
+                    event["journal"] = journal.add(self.task_id, event["new_lessons"])
+                self.events.append(event)
+        except Exception as exc:  # surface the failure to the viewer instead of hanging
+            self.events.append({"type": "error", "message": f"{type(exc).__name__}: {exc}"})
+        finally:
+            if env is not None:
+                env.close()
+            self.done = True
+            self._save()
+
+    def _save(self) -> None:
+        EPISODES_DIR.mkdir(parents=True, exist_ok=True)
+        end = next((e for e in reversed(self.events) if e["type"] == "end"), {})
+        record = {"id": self.id, "task": self.task_id, "seed": self.seed,
+                  "use_lessons": self.use_lessons, "finished_at": time.time(),
+                  "outcome": end.get("outcome", "error"), "steps": end.get("steps", 0),
+                  "events": self.events}
+        (EPISODES_DIR / f"{self.id}.json").write_text(json.dumps(record), "utf-8")
+
+
+runs: dict[str, Run] = {}
+_quota = {"day": date.today(), "used": 0}
+_lock = threading.Lock()
+
+
+class RunRequest(BaseModel):
+    task: str
+    seed: int = Field(default=0, ge=0, le=1_000_000)
+    use_lessons: bool = True
+
+
+@app.get("/api/tasks")
+def list_tasks() -> list[dict]:
+    return [{"id": t.id, "title": t.title, "goal": t.goal, "max_steps": t.max_steps,
+             "lessons": len(journal.lessons(t.id))} for t in TASKS.values()]
+
+
+@app.get("/api/status")
+def status() -> dict:
+    busy = any(not r.done for r in runs.values())
+    return {"busy": busy, "runs_left_today": max(0, DAILY_LIVE_RUNS - _quota["used"])}
+
+
+@app.post("/api/runs")
+def start_run(req: RunRequest) -> dict:
+    if req.task not in TASKS:
+        raise HTTPException(404, f"Unknown level '{req.task}'.")
+    with _lock:
+        if _quota["day"] != date.today():
+            _quota.update(day=date.today(), used=0)
+        if any(not r.done for r in runs.values()):
+            raise HTTPException(409, "Beam is already exploring. Watch that run or open a replay.")
+        if _quota["used"] >= DAILY_LIVE_RUNS:
+            raise HTTPException(429, "Today's live runs are used up. Replays are still available.")
+        _quota["used"] += 1
+        run = Run(req.task, req.seed, req.use_lessons)
+        runs[run.id] = run
+    run.start()
+    return {"id": run.id}
+
+
+@app.post("/api/runs/{run_id}/stop")
+def stop_run(run_id: str) -> dict:
+    run = runs.get(run_id)
+    if run is None:
+        raise HTTPException(404, "No such run.")
+    run.stop.set()
+    return {"stopping": True}
+
+
+@app.get("/api/runs/{run_id}/events")
+async def run_events(run_id: str) -> StreamingResponse:
+    run = runs.get(run_id)
+    if run is None:
+        raise HTTPException(404, "No such run.")
+
+    async def stream():
+        sent = 0
+        while True:
+            while sent < len(run.events):
+                yield f"data: {json.dumps(run.events[sent])}\n\n"
+                sent += 1
+            if run.done and sent >= len(run.events):
+                yield "event: close\ndata: {}\n\n"
+                return
+            await asyncio.sleep(0.25)
+
+    return StreamingResponse(stream(), media_type="text/event-stream",
+                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+@app.get("/api/episodes")
+def list_episodes() -> list[dict]:
+    if not EPISODES_DIR.exists():
+        return []
+    out = []
+    for path in sorted(EPISODES_DIR.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)[:50]:
+        rec = json.loads(path.read_text("utf-8"))
+        out.append({k: rec[k] for k in ("id", "task", "seed", "use_lessons", "outcome", "steps", "finished_at")})
+    return out
+
+
+@app.get("/api/episodes/{episode_id}")
+def get_episode(episode_id: str) -> dict:
+    if not episode_id.isalnum():
+        raise HTTPException(400, "Bad episode id.")
+    path = EPISODES_DIR / f"{episode_id}.json"
+    if not path.exists():
+        raise HTTPException(404, "No such episode.")
+    return json.loads(path.read_text("utf-8"))
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(WEB_DIR / "index.html")
+
+
+app.mount("/static", StaticFiles(directory=WEB_DIR), name="static")

lantern/__init__.py

@@ -0,0 +1,7 @@
+"""Lantern: Beam explores procedurally generated dungeons, learns from its own lessons
+journal, and distills what it learns into a small student model.
+
+Dungeon levels come from the MiniHack library (Meta AI, Apache-2.0).
+"""
+
+__version__ = "0.1.0"

lantern/agent.py

@@ -0,0 +1,221 @@
+"""The Lantern agent loop: Beam observes, plans a short action sequence, acts, repeats.
+
+`run_episode` is a generator of plain-dict events so the same loop drives the live web
+UI (streamed over SSE), the benchmark runner, and the trajectory dataset.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass
+from typing import Iterator, Protocol
+
+from .env import Task
+from .llm import ChatClient
+from .render import Frame, legend_for, surroundings, visible_features
+
+MAX_PLAN = 8          # most actions Beam may queue in a single `act` call
+HISTORY_LINES = 24    # recent action log lines shown each step
+MAX_IDLE_CALLS = 3    # consecutive replies without an action before we stop
+
+
+class Env(Protocol):
+    task: Task
+    action_names: list[str]
+
+    def reset(self) -> Frame: ...
+    def step(self, name: str) -> tuple[Frame, float, bool, bool]: ...
+
+
+SYSTEM_PROMPT = """You are Lantern, an explorer in a procedurally generated dungeon. You see an
+ASCII map each turn, with each row labelled by its y coordinate. Positions are x
+(column, increasing east) and y (row, increasing south). Use the "Visible features"
+list for exact positions and "Around you" for what blocks each direction.
+
+Goal: {goal}
+
+How to play:
+- Call `act` with a short plan of 1-{max_plan} actions. The plan is cut short if anything
+  surprising happens (a new message, lost HP), and you will see the new state.
+- Call `write_notes` whenever you learn something worth remembering this episode:
+  where you have been, dead ends, what items do, your current plan. Notes replace the
+  previous notes, so keep what still matters.
+- Letters on the map that are not described in the legend are monsters.
+- Compare your x,y with the target's x,y before planning moves.
+{lessons}"""
+
+TOOLS = [
+    {"type": "function", "function": {
+        "name": "act",
+        "description": "Execute a short sequence of game actions in order.",
+        "parameters": {"type": "object", "properties": {
+            "actions": {"type": "array", "minItems": 1, "maxItems": MAX_PLAN,
+                        "items": {"type": "string", "enum": []}},
+        }, "required": ["actions"]},
+    }},
+    {"type": "function", "function": {
+        "name": "write_notes",
+        "description": "Replace your working notes for this episode.",
+        "parameters": {"type": "object", "properties": {
+            "notes": {"type": "string"},
+        }, "required": ["notes"]},
+    }},
+]
+
+REFLECT_PROMPT = """The episode is over. Outcome: {outcome} after {steps} game steps.
+Your final notes were:
+{notes}
+
+Recent log:
+{log}
+
+Write 1-3 short, concrete lessons that would help you do better on a NEW random layout
+of this same task next time. Generalise; do not reference exact coordinates.
+Reply with JSON only: {{"lessons": ["...", "..."]}}"""
+
+
+@dataclass
+class EpisodeConfig:
+    max_llm_calls: int = 120
+    use_lessons: bool = True
+    reflect: bool = True
+
+
+def tools_for(action_names: list[str]) -> list[dict]:
+    """Tool schemas with the `act` enum restricted to this env's legal actions."""
+    tools = json.loads(json.dumps(TOOLS))
+    tools[0]["function"]["parameters"]["properties"]["actions"]["items"]["enum"] = action_names
+    return tools
+
+
+def build_observation(task: Task, frame: Frame, notes: str, log: list[str], step: int) -> str:
+    """The per-step user message: notes, recent log, and the current map."""
+    s = frame.status
+    parts = [
+        f"Step {step}/{task.max_steps}. You are at x={s['x']}, y={s['y']}. "
+        f"HP {s['hp']}/{s['max_hp']}, {s['hunger']}.",
+        f"Message: {frame.message or '(none)'}",
+        "Map:\n" + frame.map_text,
+        "Around you:\n  " + surroundings(frame),
+        "Visible features (offset from you):\n"
+        + ("\n".join(f"  {f}" for f in visible_features(frame)) or "  (none)"),
+        "Legend:\n" + (legend_for(frame.rows) or "  (nothing notable)"),
+        "Your notes:\n" + (notes or "(empty)"),
+        "Recent log:\n" + ("\n".join(log[-HISTORY_LINES:]) or "(start of episode)"),
+    ]
+    return "\n\n".join(parts)
+
+
+def _outcome(reward: float, terminated: bool, truncated: bool) -> str | None:
+    if terminated:
+        return "success" if reward > 0 else "failure"
+    if truncated:
+        return "timeout"
+    return None
+
+
+def run_episode(env: Env, client: ChatClient, lessons: list[str] | None = None,
+                config: EpisodeConfig | None = None,
+                stop: threading.Event | None = None) -> Iterator[dict]:
+    """Play one episode, yielding events: start, turn, (lessons), end."""
+    config = config or EpisodeConfig()
+    task = env.task
+    tools = tools_for(env.action_names)
+    lesson_block = ""
+    if config.use_lessons and lessons:
+        lesson_block = "\nLessons from your previous attempts at this task:\n" + \
+            "\n".join(f"- {l}" for l in lessons)
+    system = SYSTEM_PROMPT.format(goal=task.goal, max_plan=MAX_PLAN, lessons=lesson_block)
+
+    frame = env.reset()
+    notes, log = "", []
+    steps, idle, total_reward = 0, 0, 0.0
+    outcome: str | None = None
+    usage = {"prompt_tokens": 0, "completion_tokens": 0, "calls": 0}
+
+    yield {"type": "start", "task": task.id, "title": task.title, "goal": task.goal,
+           "actions": env.action_names, "lessons": list(lessons or []) if config.use_lessons else [],
+           "frame": frame.to_dict()}
+
+    while outcome is None:
+        if stop is not None and stop.is_set():
+            outcome = "stopped"
+            break
+        if usage["calls"] >= config.max_llm_calls:
+            outcome = "budget"
+            break
+
+        prompt = build_observation(task, frame, notes, log, steps)
+        reply = client.chat([{"role": "system", "content": system},
+                             {"role": "user", "content": prompt}], tools=tools)
+        usage["calls"] += 1
+        usage["prompt_tokens"] += reply.usage.get("prompt_tokens", 0)
+        usage["completion_tokens"] += reply.usage.get("completion_tokens", 0)
+
+        executed: list[dict] = []
+        start_frame = frame
+        for call in reply.tool_calls:
+            fn = call.get("function", {})
+            try:
+                args = json.loads(fn.get("arguments") or "{}")
+            except json.JSONDecodeError:
+                log.append(f"[{steps}] (malformed tool arguments ignored)")
+                continue
+            if fn.get("name") == "write_notes":
+                notes = str(args.get("notes", ""))[:2000]
+                executed.append({"tool": "write_notes", "notes": notes})
+            elif fn.get("name") == "act":
+                plan = [a for a in args.get("actions", []) if a in env.action_names][:MAX_PLAN]
+                done_actions = []
+                for name in plan:
+                    hp_before = frame.status["hp"]
+                    frame, reward, terminated, truncated = env.step(name)
+                    steps += 1
+                    total_reward += reward
+                    done_actions.append(name)
+                    outcome = _outcome(reward, terminated, truncated)
+                    if outcome or frame.message or frame.status["hp"] < hp_before:
+                        break
+                interrupted = len(done_actions) < len(plan) and outcome is None
+                log.append(f"[{steps}] {' '.join(done_actions) or '(no valid actions)'}"
+                           + (" (interrupted)" if interrupted else "")
+                           + (f" -> \"{frame.message}\"" if frame.message else ""))
+                executed.append({"tool": "act", "planned": plan, "done": done_actions,
+                                 "interrupted": interrupted})
+            if outcome:
+                break
+
+        idle = 0 if any(e["tool"] == "act" for e in executed) else idle + 1
+        if not executed and reply.content:
+            log.append(f"[{steps}] (you replied without calling a tool; use `act`)")
+
+        yield {"type": "turn", "call": usage["calls"], "steps": steps,
+               "reasoning": reply.reasoning, "content": reply.content,
+               "executed": executed, "notes": notes, "latency_s": round(reply.latency_s, 2),
+               "prompt": prompt, "before": start_frame.to_dict(), "frame": frame.to_dict()}
+
+        if idle >= MAX_IDLE_CALLS:
+            outcome = "stalled"
+
+    new_lessons: list[str] = []
+    if config.reflect and outcome not in ("stopped",):
+        new_lessons = reflect(client, outcome, steps, notes, log)
+        yield {"type": "lessons", "lessons": new_lessons}
+
+    yield {"type": "end", "task": task.id, "outcome": outcome, "steps": steps,
+           "reward": total_reward, "usage": usage, "new_lessons": new_lessons}
+
+
+def reflect(client: ChatClient, outcome: str, steps: int, notes: str, log: list[str]) -> list[str]:
+    """Ask Beam to distil the finished episode into reusable lessons."""
+    reply = client.chat([{"role": "user", "content": REFLECT_PROMPT.format(
+        outcome=outcome, steps=steps, notes=notes or "(none)",
+        log="\n".join(log[-HISTORY_LINES:]) or "(none)")}], max_tokens=2048)
+    text = (reply.content or "").strip()
+    start, end = text.find("{"), text.rfind("}")
+    try:
+        lessons = json.loads(text[start:end + 1]).get("lessons", [])
+    except (json.JSONDecodeError, ValueError):
+        return []
+    return [str(l).strip()[:300] for l in lessons if str(l).strip()][:3]

lantern/env.py

@@ -0,0 +1,137 @@
+"""Text-facing dungeon environment, built on the MiniHack library (Meta AI, Apache-2.0).
+
+MiniHack/NLE only ship Linux wheels, so the import is deferred: the rest of the package
+(rendering, agent loop, tests) works on any OS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .render import Frame, kind_from_explanation, render_frame
+
+OBS_KEYS = ("glyphs", "chars", "colors", "message", "blstats")
+
+
+def classify_glyphs(glyphs) -> tuple[list[list[str]], dict[tuple[int, int], str]]:
+    """Exact per-cell identity from NLE glyph ids: tile kinds plus monster/item names.
+
+    Unlike ASCII, glyphs distinguish a tree from a corridor (both '#') or water from lava.
+    """
+    from nle import nethack
+
+    kinds: list[list[str]] = []
+    labels: dict[tuple[int, int], str] = {}
+    for y, row in enumerate(glyphs):
+        out = []
+        for x, g in enumerate(row):
+            g = int(g)
+            if nethack.glyph_is_monster(g):
+                out.append("monster")
+                labels[(y, x)] = nethack.permonst(nethack.glyph_to_mon(g)).mname
+            elif nethack.glyph_is_object(g):
+                obj = nethack.objclass(nethack.glyph_to_obj(g))
+                desc = nethack.objdescr.from_idx(obj.oc_name_idx)
+                name = desc.oc_name or desc.oc_descr or "object"
+                out.append("boulder" if name == "boulder" else "item")
+                labels[(y, x)] = name
+            elif nethack.glyph_is_trap(g):
+                out.append("trap")
+            elif nethack.glyph_is_cmap(g):
+                cmap = nethack.glyph_to_cmap(g)
+                out.append("unknown" if cmap == 0 else
+                           kind_from_explanation(nethack.symdef.from_idx(cmap).explanation))
+            else:
+                out.append("floor")
+        kinds.append(out)
+    return kinds, labels
+
+
+@dataclass(frozen=True)
+class Task:
+    """One benchmark task: a MiniHack level id plus a plain-English goal for the agent."""
+
+    id: str
+    env_id: str
+    title: str
+    goal: str
+    max_steps: int
+
+
+TASKS: dict[str, Task] = {t.id: t for t in [
+    Task("room", "MiniHack-Room-5x5-v0", "Small Room",
+         "Reach the downstairs '>' in a small lit room.", 50),
+    Task("room-monster", "MiniHack-Room-Monster-15x15-v0", "Room with Monsters",
+         "Reach '>' in a large room while monsters roam. Avoid dying.", 200),
+    Task("corridor", "MiniHack-Corridor-R3-v0", "Corridors",
+         "Explore connected rooms through corridors to find '>'.", 300),
+    Task("keyroom", "MiniHack-KeyRoom-S5-v0", "Key Room",
+         "The '>' is behind a locked door. Find the key '(', pick it up, "
+         "stand next to the door and apply the key, then reach '>'.", 200),
+    Task("mazewalk", "MiniHack-MazeWalk-15x15-v0", "Maze Walk",
+         "Navigate a maze you can only see as you explore it to find '>'.", 300),
+    Task("river", "MiniHack-River-v0", "River Crossing",
+         "Cross the river '}' to reach '>'. You cannot swim: push boulders '`' "
+         "into the water to build a bridge.", 350),
+    Task("hidenseek", "MiniHack-HideNSeek-v0", "Hide and Seek",
+         "A powerful hostile monster shares this level. Reach '>' before it kills you; "
+         "trees and clouds (both drawn '#') block its line of sight.", 200),
+    Task("memento", "MiniHack-Memento-Short-F2-v0", "Memento",
+         "Kill the grid bug 'x' by moving into it. One branch of the corridor hides a "
+         "squeaky board that ends the run in failure. The creature you see in the small "
+         "lit room at the start is a clue to which branch is safe.", 200),
+]}
+
+
+def action_name(action) -> str:
+    """Friendly, stable tool-facing name for an NLE action enum member."""
+    compass = {"N": "north", "S": "south", "E": "east", "W": "west",
+               "NE": "northeast", "NW": "northwest", "SE": "southeast", "SW": "southwest"}
+    kind = type(action).__name__
+    if kind == "CompassDirection":
+        return compass[action.name]
+    if kind == "CompassDirectionLonger":
+        return "run_" + compass[action.name]
+    if kind == "MiscDirection":
+        return {"DOWN": "descend", "UP": "ascend", "WAIT": "wait"}.get(action.name, action.name.lower())
+    return action.name.lower()
+
+
+class DungeonEnv:
+    """A MiniHack gymnasium env that speaks in named actions and text `Frame`s.
+
+    `step()` takes an action *name* (from `action_names`) rather than an index, so the
+    LLM's tool schema and the environment can never drift out of sync.
+    """
+
+    def __init__(self, task: Task, seed: int | None = None):
+        import gymnasium as gym
+        import minihack  # noqa: F401  (registers MiniHack-* env ids)
+
+        self.task = task
+        self.seed = seed
+        self._env = gym.make(task.env_id, observation_keys=OBS_KEYS,
+                             max_episode_steps=task.max_steps)
+        actions = self._env.unwrapped.actions
+        self._index = {action_name(a): i for i, a in enumerate(actions)}
+        self.action_names = list(self._index)
+
+    def reset(self) -> Frame:
+        obs, _ = self._env.reset(seed=self.seed)
+        return self._frame(obs)
+
+    def step(self, name: str) -> tuple[Frame, float, bool, bool]:
+        """Apply one named action. Returns (frame, reward, terminated, truncated)."""
+        if name not in self._index:
+            raise ValueError(f"Unknown action {name!r}; allowed: {self.action_names}")
+        obs, reward, terminated, truncated, _ = self._env.step(self._index[name])
+        return self._frame(obs), float(reward), bool(terminated), bool(truncated)
+
+    def close(self) -> None:
+        self._env.close()
+
+    @staticmethod
+    def _frame(obs) -> Frame:
+        kinds, labels = classify_glyphs(obs["glyphs"])
+        return render_frame(obs["chars"], obs["colors"], obs["message"], obs["blstats"],
+                            kinds=kinds, labels=labels)

lantern/journal.py

@@ -0,0 +1,45 @@
+"""The lessons journal: what Beam carries from one episode of a task to the next."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def merge_lessons(old: list[str], new: list[str], limit: int) -> list[str]:
+    """Combine existing lessons with ones Beam just wrote after an episode.
+
+    Returns at most `limit` lessons, oldest first. Newer lessons win: when the journal is
+    full the oldest fall off, and a lesson Beam writes again (ignoring case/spacing) moves
+    to the end instead of appearing twice, so repeatedly confirmed lessons survive longest.
+    """
+    by_key: dict[str, str] = {}
+    for lesson in [*old, *new]:
+        key = " ".join(lesson.lower().split())
+        if not key:
+            continue
+        by_key.pop(key, None)
+        by_key[key] = lesson.strip()
+    return list(by_key.values())[-limit:]
+
+
+class Journal:
+    """Per-task lesson lists stored as one JSON file."""
+
+    def __init__(self, path: Path, limit: int = 12):
+        self.path = Path(path)
+        self.limit = limit
+        self._data: dict[str, list[str]] = (
+            json.loads(self.path.read_text("utf-8")) if self.path.exists() else {}
+        )
+
+    def lessons(self, task_id: str) -> list[str]:
+        return list(self._data.get(task_id, []))
+
+    def add(self, task_id: str, new: list[str]) -> list[str]:
+        """Merge new lessons for a task, persist, and return the updated list."""
+        merged = merge_lessons(self.lessons(task_id), new, self.limit)
+        self._data[task_id] = merged
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(self._data, indent=2), "utf-8")
+        return merged

lantern/llm.py

@@ -0,0 +1,81 @@
+"""Minimal OpenAI-compatible chat client for Beam via the Hugging Face router.
+
+The token is read from the HF_TOKEN environment variable (a Space secret in
+production) or the local `hf auth login` cache. It is never logged.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+ROUTER_URL = "https://router.huggingface.co/v1/chat/completions"
+BEAM_MODEL = "reflection/Beam-1.0-501B-A23B"
+
+
+def _load_token() -> str:
+    token = os.environ.get("HF_TOKEN")
+    if token:
+        return token.strip()
+    cached = Path.home() / ".cache" / "huggingface" / "token"
+    if cached.exists():
+        return cached.read_text().strip()
+    raise RuntimeError("No Hugging Face token: set HF_TOKEN or run `hf auth login`.")
+
+
+@dataclass
+class Reply:
+    """The parts of a chat completion the agent cares about."""
+
+    content: str | None
+    reasoning: str | None
+    tool_calls: list[dict]
+    usage: dict = field(default_factory=dict)
+    latency_s: float = 0.0
+
+
+class ChatClient:
+    """Calls an OpenAI-compatible endpoint; defaults to Beam on the HF router.
+
+    `base_url`/`model` can point at any compatible server, which is how other models
+    are benchmarked with the same harness.
+    """
+
+    def __init__(self, model: str = BEAM_MODEL, url: str = ROUTER_URL,
+                 token: str | None = None, timeout_s: float = 120.0, retries: int = 3):
+        self.model = model
+        self.url = url
+        self._headers = {"Authorization": f"Bearer {token or _load_token()}"}
+        self._http = httpx.Client(timeout=timeout_s)
+        self._retries = retries
+
+    def chat(self, messages: list[dict], tools: list[dict] | None = None,
+             temperature: float = 0.7, max_tokens: int = 4096) -> Reply:
+        """Send one chat completion request, retrying transient failures."""
+        body = {"model": self.model, "messages": messages, "temperature": temperature,
+                "top_p": 0.99, "max_tokens": max_tokens}
+        if tools:
+            body["tools"] = tools
+            body["tool_choice"] = "auto"
+
+        for attempt in range(self._retries):
+            start = time.monotonic()
+            resp = self._http.post(self.url, json=body, headers=self._headers)
+            if resp.status_code in (429, 500, 502, 503, 504) and attempt < self._retries - 1:
+                time.sleep(2 ** attempt)
+                continue
+            resp.raise_for_status()
+            data = resp.json()
+            msg = data["choices"][0]["message"]
+            return Reply(
+                content=msg.get("content"),
+                reasoning=msg.get("reasoning") or msg.get("reasoning_content"),
+                tool_calls=msg.get("tool_calls") or [],
+                usage=data.get("usage") or {},
+                latency_s=time.monotonic() - start,
+            )
+        raise RuntimeError("unreachable")

lantern/render.py

@@ -0,0 +1,227 @@
+"""Turn raw NLE observation arrays into text an LLM (and the web UI) can read.
+
+Pure functions over numpy-like arrays so they can be tested without NLE installed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+# Indices into the NLE `blstats` vector (see nle/include/nletypes.h).
+BL_X, BL_Y, BL_HP, BL_HPMAX, BL_DEPTH, BL_TIME, BL_HUNGER = 0, 1, 10, 11, 12, 20, 21
+
+HUNGER_STATES = ["not hungry", "hungry", "weak", "fainting", "fainted", "starved", "satiated"]
+
+LEGEND = {
+    "@": "you (or a human monster)",
+    ">": "stairs down (usually the goal)",
+    "<": "stairs up",
+    ".": "floor",
+    "#": "corridor, tree, or cloud (trees and clouds block sight)",
+    "|": "wall",
+    "-": "wall (or open door)",
+    "+": "closed door (or spellbook)",
+    "}": "water or lava",
+    "(": "tool or weapon (e.g. a key)",
+    "!": "potion",
+    "=": "ring",
+    "/": "wand",
+    "^": "trap",
+    "`": "boulder / rock",
+}
+# Any other letter on the map is a monster; the UI and prompt say so generically.
+
+
+@dataclass
+class Frame:
+    """A text snapshot of one game state."""
+
+    map_text: str          # cropped ASCII map with y row labels
+    message: str           # the top-line game message, if any
+    status: dict           # hero position, hp, turn, ...
+    origin: tuple[int, int]  # (row, col) of the crop's top-left in the full 21x79 map
+    rows: list[str]        # cropped map rows without rulers (for the UI)
+    colors: list[list[int]]  # NLE color index per cropped cell (for the UI)
+    kinds: list[list[str]] = field(default_factory=list)  # cell identity for the 3D view
+    labels: list[list] = field(default_factory=list)      # [row, col, name] of monsters/items
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def decode_message(message) -> str:
+    """Decode NLE's null-padded uint8 message array into a string."""
+    raw = bytes(int(c) for c in message)
+    return raw.split(b"\0", 1)[0].decode("latin-1").strip()
+
+
+def parse_status(blstats) -> dict:
+    """Pick the human-relevant fields out of the blstats vector."""
+    hunger = int(blstats[BL_HUNGER])
+    return {
+        "x": int(blstats[BL_X]),
+        "y": int(blstats[BL_Y]),
+        "hp": int(blstats[BL_HP]),
+        "max_hp": int(blstats[BL_HPMAX]),
+        "depth": int(blstats[BL_DEPTH]),
+        "turn": int(blstats[BL_TIME]),
+        "hunger": HUNGER_STATES[hunger] if 0 <= hunger < len(HUNGER_STATES) else str(hunger),
+    }
+
+
+def _bounding_box(rows: list[str]) -> tuple[int, int, int, int] | None:
+    """(top, bottom, left, right) inclusive box around non-blank cells, or None if empty."""
+    filled = [(r, c) for r, line in enumerate(rows) for c, ch in enumerate(line) if ch != " "]
+    if not filled:
+        return None
+    rs = [r for r, _ in filled]
+    cs = [c for _, c in filled]
+    return min(rs), max(rs), min(cs), max(cs)
+
+
+def kind_from_explanation(explanation: str) -> str:
+    """Map NetHack's map-symbol explanation (e.g. "open door") to a 3D tile kind."""
+    e = explanation.lower()
+    rules = [
+        ("staircase down", "stairs_down"), ("ladder down", "stairs_down"),
+        ("staircase up", "stairs_up"), ("ladder up", "stairs_up"),
+        ("closed door", "door_closed"), ("open door", "door_open"),
+        ("doorway", "doorway"), ("broken door", "doorway"),
+        ("lava", "lava"), ("water", "water"), ("moat", "water"), ("pool", "water"),
+        ("tree", "tree"), ("cloud", "cloud"), ("ice", "ice"), ("trap", "trap"),
+        ("corridor", "corridor"), ("wall", "wall"), ("corner", "wall"),
+        ("tee", "wall"), ("crosswall", "wall"),
+        ("fountain", "feature"), ("altar", "feature"), ("sink", "feature"),
+        ("throne", "feature"), ("grave", "feature"),
+        ("floor", "floor"), ("dark part of a room", "floor"),
+    ]
+    for needle, kind in rules:
+        if needle in e:
+            return kind
+    return "floor"
+
+
+# Fallback when glyph identities are unavailable (e.g. the dev preview room).
+_CHAR_KINDS = {"|": "wall", "-": "wall", ".": "floor", "#": "corridor", ">": "stairs_down",
+               "<": "stairs_up", "+": "door_closed", "}": "water", "^": "trap", "`": "boulder"}
+
+
+def kinds_from_chars(rows: list[str]) -> list[list[str]]:
+    """Best-effort kinds from ASCII alone; ambiguous symbols fall back to their common case."""
+    def kind(ch: str) -> str:
+        if ch == " ":
+            return "unknown"
+        if ch in _CHAR_KINDS:
+            return _CHAR_KINDS[ch]
+        return "monster" if ch.isalpha() or ch == "@" else "item"
+    return [[kind(ch) for ch in row] for row in rows]
+
+
+def render_frame(chars, colors, message, blstats, margin: int = 1,
+                 kinds: list[list[str]] | None = None,
+                 labels: dict[tuple[int, int], str] | None = None) -> Frame:
+    """Crop the 21x79 map to its visible area and label each row with its game y.
+
+    `kinds`/`labels` (from NLE glyphs) give exact cell identities for the 3D view; without
+    them, kinds are inferred from the ASCII characters.
+    """
+    full = ["".join(chr(int(c)) for c in row) for row in chars]
+    box = _bounding_box(full)
+    if box is None:
+        top, bottom, left, right = 0, 0, 0, 0
+    else:
+        top, bottom, left, right = box
+        top, left = max(0, top - margin), max(0, left - margin)
+        bottom = min(len(full) - 1, bottom + margin)
+        right = min(len(full[0]) - 1, right + margin)
+
+    rows = [line[left : right + 1] for line in full[top : bottom + 1]]
+    color_rows = [[int(v) for v in row[left : right + 1]] for row in list(colors)[top : bottom + 1]]
+
+    # Row labels only: column rulers cost the model more effort to decode than they saved.
+    lines = [f"y={top + i:<3} {row}" for i, row in enumerate(rows)]
+
+    status = parse_status(blstats)
+    if kinds is None:
+        kind_rows = kinds_from_chars(rows)
+    else:
+        kind_rows = [list(row[left : right + 1]) for row in kinds[top : bottom + 1]]
+    hy, hx = status["y"] - top, status["x"] - left
+    if 0 <= hy < len(kind_rows) and 0 <= hx < len(kind_rows[hy]):
+        kind_rows[hy][hx] = "hero"
+    label_list = [[y - top, x - left, name] for (y, x), name in (labels or {}).items()
+                  if top <= y <= bottom and left <= x <= right and (y, x) != (status["y"], status["x"])]
+
+    return Frame(
+        map_text="\n".join(lines),
+        message=decode_message(message),
+        status=status,
+        origin=(top, left),
+        rows=rows,
+        colors=color_rows,
+        kinds=kind_rows,
+        labels=label_list,
+    )
+
+
+FEATURE_SYMBOLS = set(LEGEND) - {"@", ".", "#", "|", "-", "}"}
+
+
+def _offset_words(dx: int, dy: int) -> str:
+    parts = []
+    if dx:
+        parts.append(f"{abs(dx)} {'east' if dx > 0 else 'west'}")
+    if dy:
+        parts.append(f"{abs(dy)} {'south' if dy > 0 else 'north'}")
+    return ", ".join(parts) or "here"
+
+
+def visible_features(frame: Frame, limit: int = 15) -> list[str]:
+    """Notable symbols (stairs, items, doors, monsters) with their offset from the hero.
+
+    Saves the model from counting characters in the ASCII grid, so the benchmark
+    measures planning and memory rather than text-alignment perception.
+    """
+    top, left = frame.origin
+    hx, hy = frame.status["x"], frame.status["y"]
+    found = []
+    for r, row in enumerate(frame.rows):
+        for c, ch in enumerate(row):
+            x, y = c + left, r + top
+            if (x, y) == (hx, hy):
+                continue
+            if ch in FEATURE_SYMBOLS:
+                desc = LEGEND[ch]
+            elif ch.isalpha() or ch == "@":
+                desc = "monster"
+            else:
+                continue
+            dx, dy = x - hx, y - hy
+            found.append((max(abs(dx), abs(dy)), f"'{ch}' {desc} at x={x}, y={y}: {_offset_words(dx, dy)}"))
+    found.sort(key=lambda f: f[0])
+    return [text for _, text in found[:limit]]
+
+
+_DIRECTIONS = [("north", 0, -1), ("northeast", 1, -1), ("east", 1, 0), ("southeast", 1, 1),
+               ("south", 0, 1), ("southwest", -1, 1), ("west", -1, 0), ("northwest", -1, -1)]
+_KIND_WORDS = {"unknown": "unexplored", "door_closed": "closed door", "door_open": "open door",
+               "stairs_down": "stairs down", "stairs_up": "stairs up"}
+
+
+def surroundings(frame: Frame) -> str:
+    """What occupies each of the 8 cells next to the hero, e.g. "north: wall, east: floor"."""
+    top, left = frame.origin
+    hx, hy = frame.status["x"] - left, frame.status["y"] - top
+    parts = []
+    for name, dx, dy in _DIRECTIONS:
+        r, c = hy + dy, hx + dx
+        inside = 0 <= r < len(frame.kinds) and 0 <= c < len(frame.kinds[r])
+        kind = frame.kinds[r][c] if inside else "unknown"
+        parts.append(f"{name}: {_KIND_WORDS.get(kind, kind)}")
+    return ", ".join(parts)
+
+
+def legend_for(rows: list[str]) -> str:
+    """Legend lines for only the symbols currently on screen, to keep prompts short."""
+    seen = {ch for row in rows for ch in row}
+    return "\n".join(f"  {sym}  {desc}" for sym, desc in LEGEND.items() if sym in seen)

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.111.0
+uvicorn==0.49.0
+httpx==0.28.1
+pydantic>=2.7,<3
+nle==1.3.0
+minihack==1.0.2

web/app.js

@@ -0,0 +1,368 @@
+// Lantern front end: renders live (SSE) or recorded episodes. No framework, no build.
+"use strict";
+
+const $ = (id) => document.getElementById(id);
+
+// NLE colour indices (curses palette) mapped onto the cave palette.
+const NLE_COLORS = [
+  "#5b6375", "#d0685f", "#7fb07a", "#b88a4e", "#6f8fd6", "#b07cc6", "#6fb8c0", "#c9c3b5",
+  "#8a93a6", "#e8955a", "#a6dc8e", "#f2d36b", "#8fb2ff", "#de9ce6", "#93e0e6", "#f4efe4",
+];
+
+const ARROWS = {
+  north: "↑ north", south: "↓ south", east: "→ east", west: "← west",
+  northeast: "↗ northeast", northwest: "↖ northwest", southeast: "↘ southeast", southwest: "↙ southwest",
+  pickup: "pick up", apply: "apply", descend: "go down", wait: "wait",
+};
+
+const state = {
+  tasks: [],
+  events: [],
+  turns: [],        // indices into events of type "turn"
+  selected: -1,     // index into turns
+  follow: true,     // stick to the newest turn while live
+  live: null,       // { id, source }
+  replayTimer: null,
+};
+
+// ── data helpers ─────────────────────────────────────
+async function api(path, options) {
+  const res = await fetch(path, options);
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.detail || `Request failed (${res.status}).`);
+  return body;
+}
+
+function startEvent() { return state.events.find((e) => e.type === "start"); }
+function endEvent() { return state.events.find((e) => e.type === "end"); }
+function taskTitle(id) { return (state.tasks.find((t) => t.id === id) || {}).title || id; }
+
+// ── map ──────────────────────────────────────────────
+function renderMap(frame, trail) {
+  const map = $("map");
+  map.replaceChildren();
+  if (!frame) return;
+  state.lastFrame = frame;
+  if (window.Lantern3D) window.Lantern3D.update(frame);
+  const [top, left] = frame.origin;
+  const hx = frame.status.x - left;
+  const hy = frame.status.y - top;
+  let heroEl = null;
+
+  frame.rows.forEach((row, r) => {
+    const line = document.createElement("div");
+    line.className = "row";
+    [...row].forEach((ch, c) => {
+      const span = document.createElement("span");
+      span.textContent = ch;
+      const d = Math.max(Math.abs(r - hy), Math.abs(c - hx));
+      // Lamplight falls off with distance; explored-but-distant cells stay dimly remembered.
+      span.style.opacity = d <= 1 ? 1 : Math.max(0.36, 1 - (d - 1) * 0.085).toFixed(2);
+      if (r === hy && c === hx) { span.className = "hero"; heroEl = span; }
+      else if (trail.has(`${c + left},${r + top}`) && ch !== " ") span.className = "trail";
+      else span.style.color = NLE_COLORS[frame.colors[r][c] & 15] || NLE_COLORS[7];
+      line.appendChild(span);
+    });
+    map.appendChild(line);
+  });
+
+  if (heroEl) {
+    const m = map.getBoundingClientRect();
+    const h = heroEl.getBoundingClientRect();
+    map.style.setProperty("--hx", `${h.left - m.left + h.width / 2}px`);
+    map.style.setProperty("--hy", `${h.top - m.top + h.height / 2}px`);
+  }
+}
+
+function trailUpTo(turnIdx) {
+  const trail = new Set();
+  const start = startEvent();
+  if (start) trail.add(`${start.frame.status.x},${start.frame.status.y}`);
+  for (let i = 0; i <= turnIdx; i++) {
+    const s = state.events[state.turns[i]].frame.status;
+    trail.add(`${s.x},${s.y}`);
+  }
+  return trail;
+}
+
+// ── panels ───────────────────────────────────────────
+function renderMind(turn) {
+  const reasoning = $("reasoning");
+  reasoning.replaceChildren();
+  const text = turn ? (turn.reasoning || turn.content || "") : "";
+  if (!text) {
+    reasoning.innerHTML = `<p class="quiet">${turn ? "Beam acted without writing out its reasoning." : "Beam's reasoning for each move appears here."}</p>`;
+  } else {
+    text.split(/\n{2,}/).forEach((para) => {
+      const p = document.createElement("p");
+      p.textContent = para.trim();
+      reasoning.appendChild(p);
+    });
+  }
+
+  const plan = $("plan");
+  plan.replaceChildren();
+  (turn ? turn.executed : []).filter((e) => e.tool === "act").forEach((e) => {
+    e.planned.forEach((a, i) => {
+      const li = document.createElement("li");
+      li.textContent = ARROWS[a] || a.replace(/_/g, " ");
+      if (i >= e.done.length) li.className = "skipped";
+      plan.appendChild(li);
+    });
+    if (e.interrupted) {
+      const li = document.createElement("li");
+      li.className = "why";
+      li.textContent = "Stopped early: something changed.";
+      plan.appendChild(li);
+    }
+  });
+
+  $("notes").textContent = turn && turn.notes ? turn.notes : "";
+  if (!$("notes").textContent) $("notes").innerHTML = '<span class="quiet">Nothing yet.</span>';
+  $("prompt").textContent = turn ? turn.prompt : "";
+}
+
+function renderStatus(turn) {
+  const status = $("status");
+  const end = endEvent();
+  const frame = turn ? turn.frame : (startEvent() || {}).frame;
+  if (!frame) return;
+  const s = frame.status;
+  const parts = [`HP <strong>${s.hp}/${s.max_hp}</strong>`];
+  if (turn) parts.push(`step <strong>${turn.steps}</strong>`, `call <strong>${turn.call}</strong> of ${state.turns.length}`);
+  if (frame.message) parts.push(`“${escapeHtml(frame.message)}”`);
+  const isLast = state.selected === state.turns.length - 1;
+  if (end && isLast) parts.unshift(outcomeHtml(end));
+  status.innerHTML = parts.join("&ensp;");
+}
+
+const OUTCOMES = {
+  success: ["win", "Goal reached"],
+  failure: ["loss", "Beam died or failed"],
+  timeout: ["loss", "Ran out of steps"],
+  stalled: ["loss", "Stalled without acting"],
+  budget: ["loss", "Hit the call budget"],
+  stopped: ["", "Stopped"],
+};
+function outcomeHtml(end) {
+  const [cls, label] = OUTCOMES[end.outcome] || ["", escapeHtml(end.outcome)];
+  const tokens = end.usage.prompt_tokens + end.usage.completion_tokens;
+  return `<strong class="${cls}">${label}</strong> in ${end.steps} steps, ${end.usage.calls} calls, ${tokens.toLocaleString()} tokens.`;
+}
+
+function renderTimeline() {
+  const tl = $("timeline");
+  const end = endEvent();
+  // Add only the ticks that are new, so live updates do not rebuild the whole strip.
+  while (tl.children.length < state.turns.length) {
+    const i = tl.children.length;
+    const t = state.events[state.turns[i]];
+    const acts = t.executed.filter((e) => e.tool === "act");
+    const done = acts.reduce((n, e) => n + e.done.length, 0);
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "tick" + (done ? " act" : "") + (acts.some((e) => e.interrupted) ? " interrupted" : "");
+    b.style.height = `${8 + Math.min(done, 8) * 4.5}px`;
+    b.setAttribute("role", "option");
+    b.setAttribute("aria-label", `Call ${i + 1}: ${done} action${done === 1 ? "" : "s"}`);
+    b.addEventListener("click", () => { stopReplay(); select(i, false); });
+    tl.appendChild(b);
+  }
+  if (end && tl.lastElementChild) {
+    tl.lastElementChild.classList.add(end.outcome === "success" ? "win" : end.outcome === "stopped" ? "act" : "loss");
+  }
+  [...tl.children].forEach((b, i) => b.setAttribute("aria-selected", String(i === state.selected)));
+}
+
+function renderJournal() {
+  const start = startEvent();
+  const lessonsEv = state.events.find((e) => e.type === "lessons");
+  fillList($("lessons-in"), (start && start.lessons) || [], "Nothing yet. This is a fresh start.");
+  fillList($("lessons-out"), lessonsEv ? lessonsEv.lessons : [], endEvent() ? "No new lessons." : "Written when the run ends.", "new");
+}
+
+function fillList(ul, items, emptyText, cls = "") {
+  ul.replaceChildren();
+  if (!items.length) {
+    const li = document.createElement("li");
+    li.className = "quiet";
+    li.style.listStyle = "none";
+    li.textContent = emptyText;
+    ul.appendChild(li);
+    return;
+  }
+  items.forEach((t) => { const li = document.createElement("li"); li.textContent = t; if (cls) li.className = cls; ul.appendChild(li); });
+}
+
+function select(i, follow) {
+  if (i < 0 || i >= state.turns.length) return;
+  state.selected = i;
+  state.follow = follow;
+  const turn = state.events[state.turns[i]];
+  renderMap(turn.frame, trailUpTo(i));
+  renderMind(turn);
+  renderStatus(turn);
+  renderTimeline();
+  $("follow").hidden = !(state.live && !follow);
+  const tick = $("timeline").children[i];
+  if (tick) tick.scrollIntoView({ block: "nearest", inline: "nearest" });
+}
+
+// ── event intake ─────────────────────────────────────
+function resetView() {
+  stopReplay();
+  state.events = []; state.turns = []; state.selected = -1; state.follow = true;
+  $("timeline").replaceChildren();
+  renderMind(null);
+}
+
+function ingest(ev) {
+  state.events.push(ev);
+  if (ev.type === "start") {
+    $("goal").textContent = `${ev.title}. ${ev.goal}`;
+    renderMap(ev.frame, new Set());
+    renderStatus(null);
+    renderJournal();
+  } else if (ev.type === "turn") {
+    state.turns.push(state.events.length - 1);
+    if (state.follow) select(state.turns.length - 1, true); else renderTimeline();
+  } else if (ev.type === "lessons" || ev.type === "end") {
+    renderJournal();
+    renderTimeline();
+    if (state.turns.length) renderStatus(state.events[state.turns[state.selected]]);
+  } else if (ev.type === "error") {
+    $("status").textContent = `The run failed: ${ev.message}`;
+  }
+}
+
+// ── live runs ────────────────────────────────────────
+async function startRun(evt) {
+  evt.preventDefault();
+  const body = { task: $("task").value, seed: Number($("seed").value) || 0, use_lessons: $("lessons").checked };
+  $("start").disabled = true;
+  try {
+    const { id } = await api("/api/runs", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    watch(id);
+  } catch (err) {
+    $("status").textContent = err.message;
+    $("start").disabled = false;
+  }
+}
+
+function watch(id) {
+  resetView();
+  $("status").textContent = "Lighting the lantern…";
+  const source = new EventSource(`/api/runs/${id}/events`);
+  state.live = { id, source };
+  $("stop").hidden = false;
+  $("start").disabled = true;
+  source.onmessage = (m) => ingest(JSON.parse(m.data));
+  source.addEventListener("close", finishLive);
+  source.onerror = () => { if (source.readyState === EventSource.CLOSED) finishLive(); };
+}
+
+function finishLive() {
+  if (!state.live) return;
+  state.live.source.close();
+  state.live = null;
+  $("stop").hidden = true;
+  $("stop").disabled = false;
+  $("start").disabled = false;
+  $("follow").hidden = true;
+  loadEpisodes();
+  loadTasks();
+}
+
+async function stopRun() {
+  if (!state.live) return;
+  $("stop").disabled = true;
+  await api(`/api/runs/${state.live.id}/stop`, { method: "POST" }).catch(() => {});
+}
+
+// ── replays ──────────────────────────────────────────
+async function openReplay(id) {
+  if (state.live) return;
+  const rec = await api(`/api/episodes/${id}`);
+  resetView();
+  if (state.tasks.some((t) => t.id === rec.task)) $("task").value = rec.task;
+  state.follow = false;
+  rec.events.forEach((ev) => { if (ev.type !== "turn") ingest(ev); else { state.events.push(ev); state.turns.push(state.events.length - 1); } });
+  renderTimeline();
+  const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (!state.turns.length) return;
+  if (reduce) { select(state.turns.length - 1, false); return; }
+  let i = 0;
+  select(0, false);
+  state.replayTimer = setInterval(() => {
+    if (++i >= state.turns.length) return stopReplay();
+    select(i, false);
+  }, 900);
+  window.scrollTo({ top: 0, behavior: "smooth" });
+}
+
+function stopReplay() {
+  if (state.replayTimer) clearInterval(state.replayTimer);
+  state.replayTimer = null;
+}
+
+async function loadEpisodes() {
+  const list = await api("/api/episodes").catch(() => []);
+  const ul = $("episodes");
+  ul.replaceChildren();
+  if (!list.length) {
+    ul.innerHTML = '<li class="quiet">No finished runs yet. Start one above and it will appear here.</li>';
+    return;
+  }
+  list.forEach((ep) => {
+    const li = document.createElement("li");
+    const b = document.createElement("button");
+    b.type = "button";
+    const [cls, label] = OUTCOMES[ep.outcome] || ["", escapeHtml(ep.outcome)];
+    b.innerHTML = `<span>${escapeHtml(taskTitle(ep.task))}, layout ${ep.seed}${ep.use_lessons ? "" : ", no journal"}</span><span class="${cls}">${label}</span>`;
+    b.addEventListener("click", () => openReplay(ep.id));
+    li.appendChild(b);
+    ul.appendChild(li);
+  });
+}
+
+async function loadTasks() {
+  state.tasks = await api("/api/tasks");
+  const sel = $("task");
+  const current = sel.value;
+  sel.replaceChildren(...state.tasks.map((t) => {
+    const o = document.createElement("option");
+    o.value = t.id;
+    o.textContent = t.lessons ? `${t.title} (${t.lessons} lessons)` : t.title;
+    return o;
+  }));
+  if (current) sel.value = current;
+  if (!startEvent()) showGoal();
+}
+
+function showGoal() {
+  const t = state.tasks.find((x) => x.id === $("task").value);
+  if (t) $("goal").textContent = `${t.title}. ${t.goal}`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+
+// ── wiring ───────────────────────────────────────────
+// The 3D module loads asynchronously; catch it up on whatever is already on screen.
+window.addEventListener("lantern3d-ready", () => { if (state.lastFrame) window.Lantern3D.update(state.lastFrame); });
+$("controls").addEventListener("submit", startRun);
+$("stop").addEventListener("click", stopRun);
+$("follow").addEventListener("click", () => select(state.turns.length - 1, true));
+$("task").addEventListener("change", () => { if (!state.live && !startEvent()) showGoal(); });
+$("timeline").addEventListener("keydown", (e) => {
+  if (e.key === "ArrowLeft") { stopReplay(); select(state.selected - 1, false); e.preventDefault(); }
+  if (e.key === "ArrowRight") { stopReplay(); select(state.selected + 1, state.live && state.selected + 1 === state.turns.length - 1); e.preventDefault(); }
+});
+
+(async () => {
+  await loadTasks();
+  await loadEpisodes();
+  const s = await api("/api/status").catch(() => null);
+  if (s && s.busy) $("status").textContent = "Beam is already exploring for another visitor. Open a replay or try again shortly.";
+})();

web/assets/kenney-mini-dungeon/License.txt

@@ -0,0 +1,28 @@
+	
+
+	Mini Dungeon (2.0)
+
+	Created/distributed by Kenney (www.kenney.nl)
+	Creation date: 29-07-2026 10:35
+	
+			------------------------------
+
+	License: (Creative Commons Zero, CC0)
+	http://creativecommons.org/publicdomain/zero/1.0/
+
+	You can use this content for personal, educational, and commercial purposes.
+
+	Support by crediting 'Kenney' or 'www.kenney.nl' (this is not a requirement)
+
+			------------------------------
+
+	• Website : www.kenney.nl
+	• Donate  : www.kenney.nl/donate
+
+	• Patreon : patreon.com/kenney
+	
+	Follow on social media for updates:
+
+	• Twitter:	 twitter.com/KenneyNL
+	• BlueSky:	 kenney.bsky.social
+	• Instagram: instagram.com/kenney_nl

web/assets/kenney-mini-dungeon/character-human.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a149b22f52f5ea6b2983dd38cb164b112be66bad5a51d640d089aafd2647a7b
+size 218072

web/assets/kenney-mini-dungeon/character-orc.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0b021c98b34a633567ca79f7c129cca48fd7919aa9e959464deba226767c284
+size 199616

web/index.html

@@ -0,0 +1,113 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Lantern</title>
+  <meta name="description" content="Watch the Beam model explore dungeon levels, think out loud, and learn from its own journal.">
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='16' cy='16' r='14' fill='%23f4b860' opacity='.25'/%3E%3Ctext x='16' y='22' font-size='18' text-anchor='middle' fill='%23f4b860' font-family='monospace'%3E@%3C/text%3E%3C/svg%3E">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Martian+Mono:wght@400;600&family=Spectral:ital,wght@0,400;0,600;1,400&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+  <header class="bar">
+    <h1 class="wordmark">Lantern</h1>
+    <p class="tagline">Beam explores a dungeon it has never seen, one plan at a time.</p>
+
+    <form class="controls" id="controls">
+      <label class="field">
+        <span>Level</span>
+        <select id="task"></select>
+      </label>
+      <label class="field field-seed">
+        <span>Layout</span>
+        <input id="seed" type="number" min="0" max="1000000" value="0" inputmode="numeric">
+      </label>
+      <label class="toggle">
+        <input id="lessons" type="checkbox" checked>
+        <span>Use journal</span>
+      </label>
+      <button class="primary" id="start" type="submit">Watch Beam explore</button>
+      <button class="secondary" id="stop" type="button" hidden>Stop</button>
+    </form>
+  </header>
+
+  <main class="stage">
+    <section class="map-wrap" aria-label="Dungeon map">
+      <p class="goal" id="goal"></p>
+      <div class="viewport">
+        <div class="view3d" id="view3d" aria-hidden="true"></div>
+        <details class="beam-view" open>
+          <summary>What Beam sees</summary>
+          <div class="map" id="map" role="img" aria-label="ASCII dungeon map, exactly as Beam receives it"></div>
+        </details>
+      </div>
+      <p class="status" id="status" aria-live="polite">Pick a level and press <em>Watch Beam explore</em>, or open a replay below.</p>
+    </section>
+
+    <aside class="mind" aria-label="What Beam is thinking">
+      <h2 class="mind-title">Beam's thinking</h2>
+      <div class="reasoning" id="reasoning"><p class="quiet">Beam's reasoning for each move appears here.</p></div>
+
+      <h3 class="sub">Plan</h3>
+      <ol class="plan" id="plan"></ol>
+
+      <h3 class="sub">Notes to itself</h3>
+      <p class="notes" id="notes"><span class="quiet">Nothing yet.</span></p>
+
+      <details class="prompt">
+        <summary>Show exactly what Beam saw</summary>
+        <pre id="prompt"></pre>
+      </details>
+    </aside>
+
+    <section class="timeline-wrap" aria-label="Timeline">
+      <div class="timeline-head">
+        <h2 class="sub">Timeline</h2>
+        <button class="link" id="follow" type="button" hidden>Jump to live</button>
+      </div>
+      <div class="timeline" id="timeline" role="listbox" aria-label="Beam's calls, oldest first" tabindex="0"></div>
+    </section>
+  </main>
+
+  <section class="lower">
+    <article class="journal">
+      <h2>Journal</h2>
+      <p class="quiet" id="journal-intro">After each run Beam writes down what it learned. The next run on the same level starts by reading it.</p>
+      <div class="journal-cols">
+        <div>
+          <h3 class="sub">Read before this run</h3>
+          <ul id="lessons-in" class="lessons"></ul>
+        </div>
+        <div>
+          <h3 class="sub">Written after this run</h3>
+          <ul id="lessons-out" class="lessons"></ul>
+        </div>
+      </div>
+    </article>
+
+    <article class="replays">
+      <h2>Replays</h2>
+      <ul id="episodes" class="episodes"></ul>
+    </article>
+  </section>
+
+  <footer class="foot">
+    Levels from <a href="https://github.com/facebookresearch/minihack">MiniHack</a> (Meta AI) on the NetHack Learning Environment.
+    3D models by <a href="https://kenney.nl/assets/mini-dungeon">Kenney</a> (CC0).
+    Model: <a href="https://huggingface.co/reflection/Beam-1.0-501B-A23B">Beam 1.0</a> by Reflection.
+    Beam is an AI model and can make mistakes; runs are game play only.
+  </footer>
+
+  <script type="importmap">
+    { "imports": {
+        "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
+        "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/"
+    } }
+  </script>
+  <script type="module" src="/static/scene3d.js"></script>
+  <script src="/static/app.js"></script>
+</body>
+</html>

web/scene3d.js

@@ -0,0 +1,307 @@
+// Lantern 3D view: the dungeon Beam is exploring, lit only by the lantern it carries.
+// Models: Kenney "Mini Dungeon" (CC0). Exposes window.Lantern3D for app.js.
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import * as SkeletonUtils from "three/addons/utils/SkeletonUtils.js";
+
+const ASSET_DIR = "/static/assets/kenney-mini-dungeon/";
+const MODEL_NAMES = ["floor", "floor-detail", "wall", "stairs", "key", "potion", "trap", "chest",
+  "gate", "rocks", "character-human", "character-orc", "coin", "column"];
+const WALKABLE = new Set(["floor", "doorway", "door_open", "door_closed", "stairs_down", "stairs_up",
+  "item", "monster", "hero", "trap", "boulder", "feature", "tree", "cloud"]);
+const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+function webglAvailable() {
+  try {
+    const c = document.createElement("canvas");
+    return !!(window.WebGLRenderingContext && (c.getContext("webgl2") || c.getContext("webgl")));
+  } catch { return false; }
+}
+
+class DungeonScene {
+  constructor(container) {
+    this.container = container;
+    this.renderer = new THREE.WebGLRenderer({ antialias: true });
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    this.renderer.shadowMap.enabled = true;
+    this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+    this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    container.appendChild(this.renderer.domElement);
+
+    this.scene = new THREE.Scene();
+    this.scene.background = new THREE.Color("#0e1118");
+    this.scene.fog = new THREE.Fog("#0e1118", 10, 26);
+
+    this.camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);
+    this.camOffset = new THREE.Vector3(0, 12.5, 9.5);
+    this.camTarget = new THREE.Vector3();
+
+    // Moonlight: just enough to remember explored rooms. The lantern does the real lighting.
+    this.scene.add(new THREE.HemisphereLight("#5b6f9e", "#0b0d12", 0.55));
+    this.lantern = new THREE.PointLight("#f4b860", 16, 10, 1.4);
+    this.lantern.castShadow = true;
+    this.lantern.shadow.mapSize.set(1024, 1024);
+    this.lantern.shadow.bias = -0.004;
+    this.scene.add(this.lantern);
+
+    this.world = new THREE.Group();
+    this.scene.add(this.world);
+    this.cells = new Map();     // "x,y" -> { kind, obj }
+    this.actors = new THREE.Group();
+    this.scene.add(this.actors);
+    this.models = {};
+    this.clock = new THREE.Clock();
+    this.lavaMats = [];
+    this.heroTarget = null;
+
+    new ResizeObserver(() => this.resize()).observe(container);
+    this.resize();
+  }
+
+  async load() {
+    const loader = new GLTFLoader();
+    const loaded = await Promise.all(MODEL_NAMES.map((n) => loader.loadAsync(`${ASSET_DIR}${n}.glb`)));
+    loaded.forEach((gltf, i) => {
+      gltf.scene.traverse((o) => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });
+      this.models[MODEL_NAMES[i]] = gltf;
+    });
+    this.makeMaterials();
+    this.makeHero();
+    this.renderer.setAnimationLoop(() => this.tick());
+  }
+
+  makeMaterials() {
+    this.mats = {
+      // A faint glow of its own so water reads as water, not a hole, outside the lamplight.
+      water: new THREE.MeshStandardMaterial({ color: "#2a6699", emissive: "#123a5c", emissiveIntensity: 0.9, roughness: 0.12, metalness: 0.25 }),
+      lava: new THREE.MeshStandardMaterial({ color: "#5a1a05", emissive: "#ff6a1a", emissiveIntensity: 1.4, roughness: 0.6 }),
+      ice: new THREE.MeshStandardMaterial({ color: "#bfe3f2", roughness: 0.1, metalness: 0.1 }),
+      leaves: new THREE.MeshStandardMaterial({ color: "#3f7a4a", roughness: 0.9, flatShading: true }),
+      trunk: new THREE.MeshStandardMaterial({ color: "#5a3d26", roughness: 1 }),
+      cloud: new THREE.MeshStandardMaterial({ color: "#d9dde6", transparent: true, opacity: 0.55, roughness: 1 }),
+      beacon: new THREE.MeshBasicMaterial({ color: "#f4b860", transparent: true, opacity: 0.55 }),
+    };
+    this.lavaMats.push(this.mats.lava);
+  }
+
+  makeHero() {
+    const gltf = this.models["character-human"];
+    this.hero = SkeletonUtils.clone(gltf.scene);
+    this.hero.scale.setScalar(1.6);
+    this.mixer = new THREE.AnimationMixer(this.hero);
+    const clip = (name) => THREE.AnimationClip.findByName(gltf.animations, name);
+    this.anims = { idle: this.mixer.clipAction(clip("idle")), walk: this.mixer.clipAction(clip("walk")) };
+    this.anims.idle.play();
+    this.current = "idle";
+    this.hero.visible = false;
+    this.scene.add(this.hero);
+  }
+
+  clone(name, scale = 1) {
+    const obj = SkeletonUtils.clone(this.models[name].scene);
+    obj.scale.setScalar(scale);
+    return obj;
+  }
+
+  // ── building cells ──────────────────────────────
+  buildCell(kind, x, y, neighbors, label) {
+    const g = new THREE.Group();
+    g.position.set(x, 0, y);
+    const plane = (mat, h = -0.02) => {
+      const m = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), mat);
+      m.rotation.x = -Math.PI / 2; m.position.y = h; m.receiveShadow = true; return m;
+    };
+
+    if (kind === "wall") { g.add(this.clone("wall")); return g; }
+    if (kind === "corridor") { g.add(this.clone("floor-detail")); return g; }
+    if (kind === "water") { g.add(plane(this.mats.water, -0.08)); return g; }
+    if (kind === "lava") { g.add(plane(this.mats.lava, -0.06)); return g; }
+    if (kind === "ice") { g.add(plane(this.mats.ice)); return g; }
+    if (!WALKABLE.has(kind)) return null;
+
+    g.add(this.clone("floor"));
+    if (kind === "door_closed" || kind === "door_open") {
+      const gate = this.clone("gate");
+      // Doors sit in a wall line; face the gate across the gap.
+      const verticalWall = neighbors.n === "wall" || neighbors.s === "wall";
+      gate.rotation.y = verticalWall ? Math.PI / 2 : 0;
+      if (kind === "door_open") { gate.rotation.y += Math.PI / 2; gate.position.x += verticalWall ? 0 : -0.35; }
+      g.add(gate);
+    } else if (kind === "stairs_down" || kind === "stairs_up") {
+      g.add(this.clone("stairs"));
+      if (kind === "stairs_down") {
+        const ring = new THREE.Mesh(new THREE.RingGeometry(0.38, 0.48, 40), this.mats.beacon);
+        ring.rotation.x = -Math.PI / 2; ring.position.y = 0.02; ring.userData.beacon = true;
+        g.add(ring);
+      }
+    } else if (kind === "trap") {
+      g.add(this.clone("trap"));
+    } else if (kind === "boulder") {
+      g.add(this.clone("rocks", 1.5));
+    } else if (kind === "feature") {
+      g.add(this.clone("column"));
+    } else if (kind === "tree") {
+      const trunk = new THREE.Mesh(new THREE.CylinderGeometry(0.07, 0.09, 0.4, 6), this.mats.trunk);
+      trunk.position.y = 0.2;
+      const crown = new THREE.Mesh(new THREE.ConeGeometry(0.36, 0.9, 7), this.mats.leaves);
+      crown.position.y = 0.8;
+      [trunk, crown].forEach((m) => { m.castShadow = true; g.add(m); });
+    } else if (kind === "cloud") {
+      [[0, 0.5, 0, 0.32], [0.2, 0.6, 0.1, 0.24], [-0.2, 0.55, -0.1, 0.26]].forEach(([px, py, pz, r]) => {
+        const s = new THREE.Mesh(new THREE.SphereGeometry(r, 10, 8), this.mats.cloud);
+        s.position.set(px, py, pz); g.add(s);
+      });
+    } else if (kind === "item") {
+      const name = (label || "").toLowerCase();
+      const model = name.includes("key") ? "key" : name.includes("potion") ? "potion"
+        : name.includes("ring") || name.includes("coin") || name.includes("gold") ? "coin" : "chest";
+      const item = this.clone(model, model === "chest" ? 0.7 : 1.4);
+      item.userData.bob = true;
+      g.add(item);
+    }
+    return g;
+  }
+
+  makeLabel(text) {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    const font = "600 44px Spectral, Georgia, serif";
+    ctx.font = font;
+    canvas.width = Math.ceil(ctx.measureText(text).width) + 36;
+    canvas.height = 64;
+    ctx.font = font;
+    ctx.fillStyle = "rgba(14,17,24,0.78)";
+    ctx.beginPath(); ctx.roundRect(0, 0, canvas.width, canvas.height, 14); ctx.fill();
+    ctx.fillStyle = "#e9e3d3";
+    ctx.textBaseline = "middle";
+    ctx.fillText(text, 18, 34);
+    const tex = new THREE.CanvasTexture(canvas);
+    tex.colorSpace = THREE.SRGBColorSpace;
+    const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: tex, depthTest: false, transparent: true }));
+    sprite.scale.set(canvas.width / canvas.height * 0.32, 0.32, 1);
+    sprite.renderOrder = 10;
+    return sprite;
+  }
+
+  // ── per-frame update from the game ─────────────
+  update(frame) {
+    if (!frame || !frame.kinds || !frame.kinds.length) return;
+    const [top, left] = frame.origin;
+    const kindAt = (r, c) => (frame.kinds[r] && frame.kinds[r][c]) || "unknown";
+    const labels = new Map(frame.labels.map(([r, c, name]) => [`${r},${c}`, name]));
+    const seen = new Set();
+
+    frame.kinds.forEach((row, r) => row.forEach((kind, c) => {
+      const x = c + left, y = r + top, key = `${x},${y}`;
+      // Actors are drawn separately; the tile under them is floor.
+      const tile = kind === "hero" || kind === "monster" ? "floor" : kind;
+      const label = kind === "item" ? labels.get(`${r},${c}`) : "";
+      const sig = `${tile}|${label || ""}`;
+      seen.add(key);
+      const prev = this.cells.get(key);
+      if (prev && prev.sig === sig) return;
+      if (prev && prev.obj) this.world.remove(prev.obj);
+      const neighbors = { n: kindAt(r - 1, c), s: kindAt(r + 1, c), e: kindAt(r, c + 1), w: kindAt(r, c - 1) };
+      const obj = this.buildCell(tile, x, y, neighbors, label);
+      if (obj) this.world.add(obj);
+      this.cells.set(key, { sig, obj });
+    }));
+    for (const [key, cell] of this.cells) {
+      if (!seen.has(key)) { if (cell.obj) this.world.remove(cell.obj); this.cells.delete(key); }
+    }
+
+    // Monsters: few per level, so rebuild each frame.
+    this.actors.clear();
+    frame.kinds.forEach((row, r) => row.forEach((kind, c) => {
+      if (kind !== "monster") return;
+      const m = this.clone("character-orc", 1.5);
+      m.position.set(c + left, 0, r + top);
+      m.lookAt(frame.status.x, 0, frame.status.y);
+      this.actors.add(m);
+      const name = labels.get(`${r},${c}`);
+      if (name) { const s = this.makeLabel(name); s.position.set(c + left, 1.05, r + top); this.actors.add(s); }
+    }));
+
+    // Frame the camera on the explored area; large maps lean toward following Beam.
+    const w = frame.kinds[0].length, h = frame.kinds.length;
+    this.levelCenter = new THREE.Vector3(left + (w - 1) / 2, 0, top + (h - 1) / 2);
+    this.follow = w > 26 || h > 14 ? 0.8 : 0.3;
+    this.zoom = THREE.MathUtils.clamp(Math.max(w / 18, h / 10), 0.85, 1.35);
+
+    const target = new THREE.Vector3(frame.status.x, 0, frame.status.y);
+    if (!this.hero.visible || reduceMotion || target.distanceTo(this.hero.position) > 4) {
+      this.hero.position.copy(target);
+      this.camTarget.copy(target);
+    }
+    this.hero.visible = true;
+    this.heroTarget = target;
+  }
+
+  play(name) {
+    if (this.current === name) return;
+    this.anims[this.current].fadeOut(0.15);
+    this.anims[name].reset().fadeIn(0.15).play();
+    this.current = name;
+  }
+
+  tick() {
+    const dt = Math.min(this.clock.getDelta(), 0.05);
+    const t = this.clock.elapsedTime;
+    if (this.heroTarget) {
+      const toTarget = this.heroTarget.clone().sub(this.hero.position);
+      const dist = toTarget.length();
+      if (dist > 0.02) {
+        this.hero.position.addScaledVector(toTarget.normalize(), Math.min(dist, dt * 4.5));
+        this.hero.rotation.y = Math.atan2(toTarget.x, toTarget.z);
+        this.play("walk");
+      } else {
+        this.hero.position.copy(this.heroTarget);
+        this.play("idle");
+      }
+    }
+    this.mixer && this.mixer.update(dt);
+
+    const flicker = reduceMotion ? 0 : Math.sin(t * 11) * 0.5 + Math.sin(t * 17.3) * 0.35;
+    this.lantern.intensity = 16 + flicker;
+    this.lantern.position.set(this.hero.position.x + 0.25, 1.9, this.hero.position.z + 0.25);
+    const focus = this.levelCenter
+      ? this.levelCenter.clone().lerp(this.hero.position, this.follow) : this.hero.position;
+    this.camTarget.lerp(focus, reduceMotion ? 1 : Math.min(1, dt * 3));
+    this.camera.position.copy(this.camTarget).addScaledVector(this.camOffset, this.zoom || 1);
+    this.camera.lookAt(this.camTarget);
+
+    if (!reduceMotion) {
+      this.lavaMats.forEach((m) => { m.emissiveIntensity = 1.25 + Math.sin(t * 2.2) * 0.25; });
+      this.world.traverse((o) => {
+        if (o.userData.beacon) o.material.opacity = 0.35 + Math.sin(t * 3) * 0.2;
+        if (o.userData.bob) o.position.y = 0.06 + Math.sin(t * 2.5 + o.parent.position.x) * 0.04;
+      });
+    }
+    this.renderer.render(this.scene, this.camera);
+  }
+
+  resize() {
+    const w = this.container.clientWidth, h = this.container.clientHeight;
+    if (!w || !h) return;
+    this.renderer.setSize(w, h, false);
+    this.camera.aspect = w / h;
+    this.camera.updateProjectionMatrix();
+  }
+}
+
+async function boot() {
+  const container = document.getElementById("view3d");
+  if (!container || !webglAvailable()) return;
+  try {
+    const view = new DungeonScene(container);
+    await view.load();
+    window.Lantern3D = view;
+    document.body.classList.add("has-3d");
+    window.dispatchEvent(new Event("lantern3d-ready"));
+  } catch (err) {
+    console.warn("3D view unavailable, using the text map.", err);
+  }
+}
+
+boot();

web/style.css

@@ -0,0 +1,270 @@
+:root {
+  --cave: #1a1f2b;
+  --stone: #262d3b;
+  --stone-edge: #343c4d;
+  --lamp: #f4b860;
+  --ink: #e9e3d3;
+  --muted: #8a93a6;
+  --moss: #86b37e;
+  --blood: #c24e5a;
+  --mono: "Martian Mono", ui-monospace, monospace;
+  --serif: "Spectral", Georgia, serif;
+  --cell: clamp(11px, 1.55vw, 22px);
+  color-scheme: dark;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background: var(--cave);
+  color: var(--ink);
+  font: 400 17px/1.55 var(--serif);
+}
+
+a { color: var(--lamp); }
+:focus-visible { outline: 2px solid var(--lamp); outline-offset: 2px; }
+
+/* ── header ───────────────────────────────────────── */
+.bar {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 4px 20px;
+  align-items: baseline;
+  padding: 20px clamp(16px, 3vw, 40px) 16px;
+}
+.wordmark {
+  margin: 0;
+  font: italic 600 2.1rem/1 var(--serif);
+  color: var(--lamp);
+  text-shadow: 0 0 18px rgb(244 184 96 / 0.45);
+}
+.tagline { margin: 0; color: var(--muted); }
+.controls {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px 16px;
+  align-items: end;
+  margin-top: 14px;
+}
+.field { display: grid; gap: 4px; font-size: 0.85rem; color: var(--muted); }
+.field select, .field input {
+  font: 400 0.95rem var(--serif);
+  color: var(--ink);
+  background: var(--stone);
+  border: 1px solid var(--stone-edge);
+  border-radius: 6px;
+  padding: 7px 10px;
+  min-width: 200px;
+}
+.field-seed input { min-width: 0; width: 7.5em; }
+.toggle { display: flex; gap: 8px; align-items: center; padding-bottom: 8px; color: var(--muted); }
+.toggle input { accent-color: var(--lamp); width: 16px; height: 16px; }
+
+button { font: 600 0.95rem var(--serif); cursor: pointer; border-radius: 6px; }
+button:disabled { opacity: 0.5; cursor: not-allowed; }
+.primary {
+  background: var(--lamp);
+  color: #2a1d08;
+  border: 0;
+  padding: 9px 18px;
+  box-shadow: 0 0 0 0 rgb(244 184 96 / 0.4);
+}
+.primary:not(:disabled):hover { box-shadow: 0 0 22px 2px rgb(244 184 96 / 0.35); }
+.secondary { background: transparent; color: var(--ink); border: 1px solid var(--stone-edge); padding: 8px 16px; }
+.link { background: none; border: 0; color: var(--lamp); padding: 0; text-decoration: underline; }
+
+/* ── stage: map + mind + timeline ─────────────────── */
+.stage {
+  display: grid;
+  grid-template-columns: minmax(0, 1.6fr) minmax(300px, 1fr);
+  grid-template-areas: "map mind" "time time";
+  gap: 0;
+  margin: 0 clamp(16px, 3vw, 40px);
+  border: 1px solid var(--stone-edge);
+  border-radius: 10px;
+  overflow: hidden;
+  background: #151923;
+}
+
+.map-wrap { grid-area: map; padding: 18px 20px 14px; display: flex; flex-direction: column; min-height: 420px; }
+.goal { margin: 0 0 12px; color: var(--muted); max-width: 70ch; }
+
+.viewport { flex: 1; position: relative; display: flex; min-height: 440px; }
+.view3d { display: none; }
+.has-3d .view3d {
+  display: block;
+  position: absolute;
+  inset: 0;
+  border-radius: 8px;
+  overflow: hidden;
+}
+.view3d canvas { width: 100%; height: 100%; display: block; }
+
+/* Without 3D the text map is the main view; with 3D it becomes a corner inset. */
+.beam-view { flex: 1; display: flex; flex-direction: column; }
+.beam-view summary { display: none; }
+.has-3d .beam-view {
+  flex: none;
+  position: absolute;
+  right: 12px;
+  bottom: 12px;
+  max-width: min(46%, 420px);
+  background: rgb(21 25 35 / 0.86);
+  border: 1px solid var(--stone-edge);
+  border-radius: 8px;
+  padding: 8px 10px 10px;
+  backdrop-filter: blur(3px);
+}
+.has-3d .beam-view summary { display: list-item; cursor: pointer; font-size: 0.85rem; color: var(--muted); }
+.has-3d .beam-view[open] summary { margin-bottom: 6px; }
+.has-3d .beam-view .map { --cell: 8px; overflow: hidden; place-content: start; }
+
+.map {
+  flex: 1;
+  display: grid;
+  place-content: center;
+  position: relative;
+  font: 400 var(--cell)/1.2 var(--mono);
+  white-space: pre;
+  user-select: none;
+}
+/* The lantern: a warm pool of light centred on Beam, positioned by app.js. */
+.map::before {
+  content: "";
+  position: absolute;
+  left: var(--hx, 50%);
+  top: var(--hy, 50%);
+  width: calc(var(--cell) * 16);
+  height: calc(var(--cell) * 16);
+  transform: translate(-50%, -50%);
+  background: radial-gradient(closest-side, rgb(244 184 96 / 0.22), rgb(244 184 96 / 0.07) 60%, transparent);
+  pointer-events: none;
+  transition: left 0.25s ease, top 0.25s ease;
+}
+.map .row { position: relative; height: calc(var(--cell) * 1.2); }
+.map span { display: inline-block; width: 1ch; text-align: center; }
+.map .hero { color: var(--lamp); font-weight: 600; text-shadow: 0 0 10px var(--lamp); }
+/* Where Beam has walked: floor glyphs take on a faint lamplight tint. */
+.map .trail { color: #b5874a; }
+
+.status { margin: 12px 0 0; font-size: 0.95rem; color: var(--muted); }
+.status strong { color: var(--ink); font-weight: 600; }
+.status .win { color: var(--moss); }
+.status .loss { color: var(--blood); }
+
+.mind {
+  grid-area: mind;
+  border-left: 1px solid var(--stone-edge);
+  background: var(--stone);
+  padding: 18px 20px;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  max-height: 640px;
+}
+.mind-title { margin: 0 0 8px; font: italic 600 1.25rem var(--serif); }
+.reasoning {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  min-height: 120px;
+  padding-right: 6px;
+  font-style: italic;
+  line-height: 1.65;
+  white-space: pre-wrap;
+}
+.reasoning p { margin: 0 0 0.6em; }
+.sub { margin: 14px 0 6px; font: 600 0.9rem var(--serif); color: var(--muted); }
+
+.plan { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: 6px; }
+.plan li {
+  font: 400 0.8rem var(--mono);
+  padding: 3px 8px;
+  border-radius: 4px;
+  border: 1px solid var(--lamp);
+  color: var(--lamp);
+}
+.plan li.skipped { border-style: dashed; border-color: var(--muted); color: var(--muted); text-decoration: line-through; }
+.plan .why { border: 0; padding: 3px 0; color: var(--muted); font-family: var(--serif); font-style: italic; }
+
+.notes { margin: 0; font-size: 0.95rem; white-space: pre-wrap; max-height: 9em; overflow-y: auto; }
+
+.prompt { margin-top: 14px; font-size: 0.85rem; color: var(--muted); }
+.prompt summary { cursor: pointer; }
+.prompt pre { font: 400 0.72rem/1.35 var(--mono); max-height: 260px; overflow: auto; background: var(--cave); padding: 10px; border-radius: 6px; color: var(--ink); }
+
+.timeline-wrap { grid-area: time; border-top: 1px solid var(--stone-edge); padding: 10px 20px 14px; }
+.timeline-head { display: flex; justify-content: space-between; align-items: baseline; }
+.timeline-head .sub { margin: 0 0 8px; }
+.timeline {
+  display: flex;
+  align-items: flex-end;
+  gap: 3px;
+  height: 46px;
+  overflow-x: auto;
+  scrollbar-width: thin;
+}
+.tick {
+  flex: 0 0 9px;
+  min-height: 6px;
+  border: 0;
+  border-radius: 2px 2px 0 0;
+  background: #4a5367;
+  padding: 0;
+}
+.tick.act { background: #9a7a48; }
+.tick.interrupted { background: var(--lamp); }
+.tick.win { background: var(--moss); }
+.tick.loss { background: var(--blood); }
+.tick[aria-selected="true"] { outline: 2px solid var(--ink); outline-offset: 1px; }
+
+/* ── journal + replays ───────────────────────────── */
+.lower {
+  display: grid;
+  grid-template-columns: minmax(0, 1.6fr) minmax(300px, 1fr);
+  gap: 28px;
+  margin: 28px clamp(16px, 3vw, 40px);
+}
+.lower h2 { margin: 0 0 6px; font: italic 600 1.25rem var(--serif); }
+.journal-cols { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
+.lessons { margin: 0; padding-left: 1.1em; max-width: 60ch; }
+.lessons li { margin-bottom: 0.5em; }
+.lessons li.new::marker { color: var(--lamp); }
+.episodes { list-style: none; margin: 0; padding: 0; }
+.episodes button {
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  text-align: left;
+  background: none;
+  border: 0;
+  border-bottom: 1px solid var(--stone-edge);
+  border-radius: 0;
+  color: var(--ink);
+  padding: 8px 2px;
+  font-weight: 400;
+}
+.episodes button:hover { color: var(--lamp); }
+.episodes .win { color: var(--moss); }
+.episodes .loss { color: var(--blood); }
+.quiet { color: var(--muted); }
+
+.foot { margin: 0 clamp(16px, 3vw, 40px) 28px; font-size: 0.85rem; color: var(--muted); max-width: 90ch; }
+
+@media (max-width: 860px) {
+  .bar { grid-template-columns: 1fr; }
+  .stage { grid-template-columns: 1fr; grid-template-areas: "map" "mind" "time"; }
+  .mind { border-left: 0; border-top: 1px solid var(--stone-edge); max-height: none; }
+  .map { overflow-x: auto; place-content: start; }
+  .viewport { flex-direction: column; min-height: 0; }
+  .has-3d .view3d { position: relative; inset: auto; height: 340px; }
+  .has-3d .beam-view { position: static; max-width: none; margin-top: 12px; }
+  .lower, .journal-cols { grid-template-columns: 1fr; }
+  .field select { min-width: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .map::before { transition: none; }
+}