agent-timelines 0.2.0__tar.gz

agent_timelines-0.2.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 jasondasuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Bundled third-party assets (sprites and font) keep their own licenses:
+see src/agent_timelines/assets/LICENSES.txt.

agent_timelines-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: agent-timelines
+Version: 0.2.0
+Summary: Live delegation graph of Claude Code sessions and their subagents
+Author: jasondasuki
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jasondasuki/agent-timelines
+Project-URL: Source, https://github.com/jasondasuki/agent-timelines
+Project-URL: Issues, https://github.com/jasondasuki/agent-timelines/issues
+Keywords: claude-code,claude,agents,subagents,dashboard,observability,pixel-art
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/agent_timelines/assets/LICENSES.txt
+Dynamic: license-file
+
+# agent-timelines
+
+[![CI](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml/badge.svg)](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE)
+
+A pixel-art dashboard for Claude Code sessions. It shows which agent spawned which, the model and effort
+requested vs. what actually ran, tool calls, weighted token cost and dollars, handoffs and Workflow runs, live while the
+session works. Everything is read from your local transcripts; nothing leaves your machine.
+
+![Chart view: the delegation tree as a party of heroes, with one hero's detail panel open](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/chart.jpg)
+
+- **Lobby**: your 200 most recent sessions as a retro game-server list (live dungeons + hall of records), with search, a project filter and
+  paging (`/` focuses the search box, left/right change the page).
+- **Chart view**: the delegation tree as a party of heroes, with flags for rule breaks (no model set,
+  model mismatch, ignored tool limit, unanswered handoff, …).
+  Each card shows the agent's top tools and the start of its final reply; the detail panel lists every tool and the full report
+  (a running agent shows what it is saying now).
+- **Timeline view**: one bar per agent on a shared clock, rows in party-tree order, so you can see who ran when and what overlapped.
+  Running agents get a striped bar; zoom with + and -.
+- **Map view**: the same session as a procedurally generated dungeon. The main session is the guild master
+  in the guild hall; each agent has its own room and fights an enemy while it works, then celebrates.
+
+![Lobby: live dungeons and the hall of records](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/lobby.jpg)
+![Map view: a procedurally generated dungeon with one room per agent](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/map.jpg)
+
+(The screenshots show a synthetic demo session.)
+
+## Install
+
+Needs Python 3.9+ on macOS or Linux (Windows is not supported). No other dependencies. Use one of the two options, not both.
+
+**Option A: the command-line tool from PyPI** (needs [uv](https://docs.astral.sh/uv/) or pipx)
+
+```sh
+uv tool install agent-timelines   # or: pipx install agent-timelines
+agent-timelines install    # adds 6 hooks to ~/.claude/settings.json (writes a backup next to it first)
+agent-timelines rebuild    # optional: fills the lobby with your sessions from the last 30 days
+agent-timelines serve      # opens http://127.0.0.1:8765/index.html (localhost only)
+```
+
+**Option B: the Claude Code plugin** (no pip, no settings.json edit; the hooks come with the plugin)
+
+```sh
+claude plugin marketplace add jasondasuki/agent-timelines
+claude plugin install agent-timelines@agent-timelines
+```
+
+Then ask for the dashboard with `/agent-timelines:dashboard`. The plugin's hooks run `python3` from your PATH, so Python 3.9+ must be there.
+If `agent-timelines install` hooks are also in settings.json, the plugin's hooks stay quiet so nothing is built twice.
+
+Start or continue a Claude Code session; it appears in the lobby on its first hook event.
+
+| Command | What it does |
+|---|---|
+| `install [--settings PATH]` | Add the hooks (replaces earlier agent-timelines hooks, keeps all others). |
+| `uninstall [--settings PATH]` | Remove the hooks. Your data folder stays. |
+| `serve [--port N] [--no-browser]` | Serve the dashboard on 127.0.0.1. |
+| `open [SESSION-PREFIX]` | Build one session (newest by default) and open it from disk, no server. |
+| `rebuild [--days N]` | Regenerate data for recent sessions from their transcripts. |
+| `list` | Recent sessions with their subagent counts. |
+
+`--settings` targets another Claude config dir, e.g. `--settings ~/.claude-work/settings.json`.
+`CLAUDE_CONFIG_DIR` is respected for the default paths.
+
+Data lives in `~/.claude/agent-timelines/` (one `<session>.data.js` and one `<session>.prompts.js` per session, removed after 30 days untouched).
+The pages hold prompt text from your sessions, which is why `serve` binds to localhost only and refuses requests that come from other sites (wrong `Host`, or a cross-site script or fetch).
+
+## Config (optional)
+
+`~/.config/agent-timelines/config.json` (or `$AGENT_TIMELINES_CONFIG`). Every key is optional:
+
+```json
+{
+  "out_dir": "~/.claude/agent-timelines",
+  "ctx_limit": 200000,
+  "tool_limit": 50,
+  "brief_limit": 8000,
+  "retain_days": 30,
+  "lobby_limit": 200,
+  "handover_dir": "~/.claude/handovers",
+  "agents_dir": "~/.claude/agents",
+  "guard_text": "Main session does not execute",
+  "tiers": {"Explore": "scanner", "Plan": "plan", "general-purpose": "executor"},
+  "rules": {"no-model": true, "no-effort": true},
+  "prices": {"gpt-6": {"in": 1, "out": 2}}
+}
+```
+
+`tool_limit` is unset by default, so there are no hearts, only a tool count; set it to the number your hand-off hook uses.
+`brief_limit`, `guard_text` and `handover_dir` match optional hand-off and guard hooks of your own;
+without such hooks those flags never fire. `tiers` maps agent types to character classes.
+`rules` turns single flags on or off by name; a flag you do not list keeps its default. `no-model` and `no-effort` are off by default;
+turn them on if your setup requires every spawn to name a model and effort. The flag names are `no-model`, `no-effort`, `auto-filled`,
+`frontmatter`, `model-mismatch`, `effort-mismatch`, `ctx` (the context-size flag), `handoff`, `tool-limit`, `ignored-limit`, `orphan`
+and `handoff-not-continued`; an unknown name is an error.
+
+`prices` adds or changes entries of the built-in price table (USD per million tokens; the table is dated, see `PRICES_ASOF` in `timeline.py`).
+The key is a model id prefix without `claude-`, the longest matching key wins, and the columns are `in`, `cc5` (5-minute cache write),
+`cc1` (1-hour cache write), `cr` (cache read), `out` and an optional `over` (`[prompt tokens, multiplier]`); a missing column counts as 0.
+Entries are merged per model, so you only list what you add or change. A model with no price is shown as unpriced (`$0.00+` on its card),
+never guessed.
+
+### Cost
+
+Cost is computed per message from the full model id and the usage recorded in the transcript, at Anthropic first-party API list prices
+([pricing page](https://platform.claude.com/docs/en/about-claude/pricing), table dated 2026-11-10). It is what those tokens would cost through the
+API; a subscription plan is not billed per token. Not modelled: the 1.1x US-only `inference_geo` surcharge (the transcript does not say whether it
+applied), batch discounts, Bedrock and Vertex prices, web-search and other server-tool fees. Gold is the same tokens weighted by cost, as before.
+
+## Development
+
+```sh
+python3 tests/test_timeline.py && python3 tests/test_cli.py   # Python
+node tests/test_dungeon.js && node tests/test_actors.js && node tests/test_lobby.js && node tests/test_gantt.js   # viewer scripts (Node 18+)
+open dev/dungeon-demo.html                                     # dungeon playground: agents, working, reset
+```
+
+## Credits
+
+- Sprites: [Kenney](https://www.kenney.nl) "Tiny Dungeon" and "1-Bit Pack", CC0.
+- Font: Press Start 2P by CodeMan38, SIL Open Font License 1.1.
+
+Details in `src/agent_timelines/assets/LICENSES.txt`.
+
+## License
+
+MIT, see [LICENSE](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE). Contributions welcome: see [CONTRIBUTING.md](https://github.com/jasondasuki/agent-timelines/blob/main/CONTRIBUTING.md). Security reports: [SECURITY.md](https://github.com/jasondasuki/agent-timelines/blob/main/SECURITY.md).

agent_timelines-0.2.0/README.md

@@ -0,0 +1,126 @@
+# agent-timelines
+
+[![CI](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml/badge.svg)](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE)
+
+A pixel-art dashboard for Claude Code sessions. It shows which agent spawned which, the model and effort
+requested vs. what actually ran, tool calls, weighted token cost and dollars, handoffs and Workflow runs, live while the
+session works. Everything is read from your local transcripts; nothing leaves your machine.
+
+![Chart view: the delegation tree as a party of heroes, with one hero's detail panel open](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/chart.jpg)
+
+- **Lobby**: your 200 most recent sessions as a retro game-server list (live dungeons + hall of records), with search, a project filter and
+  paging (`/` focuses the search box, left/right change the page).
+- **Chart view**: the delegation tree as a party of heroes, with flags for rule breaks (no model set,
+  model mismatch, ignored tool limit, unanswered handoff, …).
+  Each card shows the agent's top tools and the start of its final reply; the detail panel lists every tool and the full report
+  (a running agent shows what it is saying now).
+- **Timeline view**: one bar per agent on a shared clock, rows in party-tree order, so you can see who ran when and what overlapped.
+  Running agents get a striped bar; zoom with + and -.
+- **Map view**: the same session as a procedurally generated dungeon. The main session is the guild master
+  in the guild hall; each agent has its own room and fights an enemy while it works, then celebrates.
+
+![Lobby: live dungeons and the hall of records](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/lobby.jpg)
+![Map view: a procedurally generated dungeon with one room per agent](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/map.jpg)
+
+(The screenshots show a synthetic demo session.)
+
+## Install
+
+Needs Python 3.9+ on macOS or Linux (Windows is not supported). No other dependencies. Use one of the two options, not both.
+
+**Option A: the command-line tool from PyPI** (needs [uv](https://docs.astral.sh/uv/) or pipx)
+
+```sh
+uv tool install agent-timelines   # or: pipx install agent-timelines
+agent-timelines install    # adds 6 hooks to ~/.claude/settings.json (writes a backup next to it first)
+agent-timelines rebuild    # optional: fills the lobby with your sessions from the last 30 days
+agent-timelines serve      # opens http://127.0.0.1:8765/index.html (localhost only)
+```
+
+**Option B: the Claude Code plugin** (no pip, no settings.json edit; the hooks come with the plugin)
+
+```sh
+claude plugin marketplace add jasondasuki/agent-timelines
+claude plugin install agent-timelines@agent-timelines
+```
+
+Then ask for the dashboard with `/agent-timelines:dashboard`. The plugin's hooks run `python3` from your PATH, so Python 3.9+ must be there.
+If `agent-timelines install` hooks are also in settings.json, the plugin's hooks stay quiet so nothing is built twice.
+
+Start or continue a Claude Code session; it appears in the lobby on its first hook event.
+
+| Command | What it does |
+|---|---|
+| `install [--settings PATH]` | Add the hooks (replaces earlier agent-timelines hooks, keeps all others). |
+| `uninstall [--settings PATH]` | Remove the hooks. Your data folder stays. |
+| `serve [--port N] [--no-browser]` | Serve the dashboard on 127.0.0.1. |
+| `open [SESSION-PREFIX]` | Build one session (newest by default) and open it from disk, no server. |
+| `rebuild [--days N]` | Regenerate data for recent sessions from their transcripts. |
+| `list` | Recent sessions with their subagent counts. |
+
+`--settings` targets another Claude config dir, e.g. `--settings ~/.claude-work/settings.json`.
+`CLAUDE_CONFIG_DIR` is respected for the default paths.
+
+Data lives in `~/.claude/agent-timelines/` (one `<session>.data.js` and one `<session>.prompts.js` per session, removed after 30 days untouched).
+The pages hold prompt text from your sessions, which is why `serve` binds to localhost only and refuses requests that come from other sites (wrong `Host`, or a cross-site script or fetch).
+
+## Config (optional)
+
+`~/.config/agent-timelines/config.json` (or `$AGENT_TIMELINES_CONFIG`). Every key is optional:
+
+```json
+{
+  "out_dir": "~/.claude/agent-timelines",
+  "ctx_limit": 200000,
+  "tool_limit": 50,
+  "brief_limit": 8000,
+  "retain_days": 30,
+  "lobby_limit": 200,
+  "handover_dir": "~/.claude/handovers",
+  "agents_dir": "~/.claude/agents",
+  "guard_text": "Main session does not execute",
+  "tiers": {"Explore": "scanner", "Plan": "plan", "general-purpose": "executor"},
+  "rules": {"no-model": true, "no-effort": true},
+  "prices": {"gpt-6": {"in": 1, "out": 2}}
+}
+```
+
+`tool_limit` is unset by default, so there are no hearts, only a tool count; set it to the number your hand-off hook uses.
+`brief_limit`, `guard_text` and `handover_dir` match optional hand-off and guard hooks of your own;
+without such hooks those flags never fire. `tiers` maps agent types to character classes.
+`rules` turns single flags on or off by name; a flag you do not list keeps its default. `no-model` and `no-effort` are off by default;
+turn them on if your setup requires every spawn to name a model and effort. The flag names are `no-model`, `no-effort`, `auto-filled`,
+`frontmatter`, `model-mismatch`, `effort-mismatch`, `ctx` (the context-size flag), `handoff`, `tool-limit`, `ignored-limit`, `orphan`
+and `handoff-not-continued`; an unknown name is an error.
+
+`prices` adds or changes entries of the built-in price table (USD per million tokens; the table is dated, see `PRICES_ASOF` in `timeline.py`).
+The key is a model id prefix without `claude-`, the longest matching key wins, and the columns are `in`, `cc5` (5-minute cache write),
+`cc1` (1-hour cache write), `cr` (cache read), `out` and an optional `over` (`[prompt tokens, multiplier]`); a missing column counts as 0.
+Entries are merged per model, so you only list what you add or change. A model with no price is shown as unpriced (`$0.00+` on its card),
+never guessed.
+
+### Cost
+
+Cost is computed per message from the full model id and the usage recorded in the transcript, at Anthropic first-party API list prices
+([pricing page](https://platform.claude.com/docs/en/about-claude/pricing), table dated 2026-11-10). It is what those tokens would cost through the
+API; a subscription plan is not billed per token. Not modelled: the 1.1x US-only `inference_geo` surcharge (the transcript does not say whether it
+applied), batch discounts, Bedrock and Vertex prices, web-search and other server-tool fees. Gold is the same tokens weighted by cost, as before.
+
+## Development
+
+```sh
+python3 tests/test_timeline.py && python3 tests/test_cli.py   # Python
+node tests/test_dungeon.js && node tests/test_actors.js && node tests/test_lobby.js && node tests/test_gantt.js   # viewer scripts (Node 18+)
+open dev/dungeon-demo.html                                     # dungeon playground: agents, working, reset
+```
+
+## Credits
+
+- Sprites: [Kenney](https://www.kenney.nl) "Tiny Dungeon" and "1-Bit Pack", CC0.
+- Font: Press Start 2P by CodeMan38, SIL Open Font License 1.1.
+
+Details in `src/agent_timelines/assets/LICENSES.txt`.
+
+## License
+
+MIT, see [LICENSE](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE). Contributions welcome: see [CONTRIBUTING.md](https://github.com/jasondasuki/agent-timelines/blob/main/CONTRIBUTING.md). Security reports: [SECURITY.md](https://github.com/jasondasuki/agent-timelines/blob/main/SECURITY.md).

agent_timelines-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-timelines"
+version = "0.2.0"
+description = "Live delegation graph of Claude Code sessions and their subagents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "src/agent_timelines/assets/LICENSES.txt"]
+authors = [{ name = "jasondasuki" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["claude-code", "claude", "agents", "subagents", "dashboard", "observability", "pixel-art"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Debuggers",
+]
+
+[project.urls]
+Homepage = "https://github.com/jasondasuki/agent-timelines"
+Source = "https://github.com/jasondasuki/agent-timelines"
+Issues = "https://github.com/jasondasuki/agent-timelines/issues"
+
+[project.scripts]
+agent-timelines = "agent_timelines.cli:main"
+
+[tool.setuptools.package-data]
+agent_timelines = ["viewer.html", "*.js", "assets/*"]

agent_timelines-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_timelines-0.2.0/src/agent_timelines/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

agent_timelines-0.2.0/src/agent_timelines/actors.js

@@ -0,0 +1,202 @@
+/* Characters for the dungeon: the guild master in the hall, one hero + enemy per agent room, a chest per workflow.
+ * Sprites follow the timeline viewer exactly (same HERO map and rules; tests/test_actors.js compares them).
+ * place() is pure (seed + dungeon + nodes -> actors); stamp() remembers when each state began; draw() runs per frame.
+ * Actors not working (idle guild master, a hero after its victory) wander their room's free cells: never onto props,
+ * doors, corridors or the fallen enemy. walk() holds that motion and is canvas-free so it can be tested.
+ * Node fields are the viewer's: {id, tier, kind, running, flags, wf:{state}}. Plain ES5; window.Actors / module.exports. */
+(function (root) {
+  'use strict';
+  var D = root.Dungeon || (typeof require !== 'undefined' && require('./dungeon.js'));
+  // [sheet, col, row]: keep identical to HERO in viewer.html
+  var HERO = {main:["td",0,7],executor:["td",0,8],scanner:["td",1,7],plan:["td",4,8],writer:["td",3,8],runner:["td",4,7],other:["td",3,7],workflow:["td",5,7],wfrun:["td",8,7],ghost:["td",1,10]};
+  var FOES = [108, 109, 110, 111, 120, 122, 123, 124]; // td slime, cyclops, crab, hooded cultist, bat, spider, rat, grey rat
+  var OPEN_CHEST = 91;  // td open chest: a finished workflow
+  var OB_BONES = 721;   // ob bone pile under a fallen enemy
+  var RUG = { 629: 1, 630: 1, 631: 1 }; // ob carpet pieces: the only props that may be walked on
+  var STEP_MS = 220;    // one cell of running
+  var OB_TROPHY = 808;  // ob trophy raised on victory (tinted gold when drawn)
+
+  function cls(n) { return n.id === 'main' ? 'main' : n.kind === 'wf' ? 'workflow' : HERO[n.tier] ? n.tier : 'other'; }
+  function sprite(n) { // the viewer's sprite(): a berserk hero (ignored the tool limit) is a ghost, a running workflow a mimic
+    var berserk = n.id !== 'main' && n.kind !== 'wf' && !n.running && (n.flags || []).indexOf('ignored-limit') >= 0;
+    var s = berserk ? HERO.ghost : n.kind === 'wf' && n.running ? HERO.wfrun : HERO[cls(n)];
+    return s[2] * 12 + s[1];
+  }
+
+  function place(seed, d, nodes) {
+    var solid = {}, path = {}, rooms = {}, out = [];
+    d.deco.forEach(function (e) { if (!(e.sheet === 'ob' && RUG[e.idx])) solid[e.x + ',' + e.y] = 1; });
+    d.paths.forEach(function (p) { p.cells.forEach(function (c) { path[c[0] + ',' + c[1]] = 1; }); });
+    d.rooms.forEach(function (q) { rooms[q.id] = q; });
+    function free(q, x, y) { return x >= q.x && x < q.x + q.w && y >= q.y && y < q.y + q.h && !solid[x + ',' + y] && !path[x + ',' + y]; }
+    function near(q, x, y, two) { // closest free cell to (x, y) in rings outward; `two` also needs its right neighbour free
+      for (var r = 0; r < q.w + q.h; r++) for (var dy = -r; dy <= r; dy++) for (var dx = -r; dx <= r; dx++) {
+        if (Math.max(Math.abs(dx), Math.abs(dy)) === r && free(q, x + dx, y + dy) && (!two || free(q, x + dx + 1, y + dy))) return [x + dx, y + dy];
+      }
+      return [q.cx, q.cy];
+    }
+    function room(q, skip) { // free cells of q, minus `skip`, as {"x,y": 1}
+      var f = {}, x, y;
+      for (y = q.y; y < q.y + q.h; y++) for (x = q.x; x < q.x + q.w; x++) if (free(q, x, y) && x + ',' + y !== skip) f[x + ',' + y] = 1;
+      return f;
+    }
+    nodes.forEach(function (n) {
+      var q = rooms[n.id], a;
+      if (!q) return;
+      if (q.hall) { a = near(q, q.x + 2, q.y); out.push({ id: n.id, kind: 'gm', idx: sprite(n), x: a[0], y: a[1], state: n.running ? 'cast' : 'idle', free: room(q) }); return; }
+      if (n.kind === 'wf') {
+        a = near(q, q.cx, q.cy);
+        out.push({ id: n.id, kind: 'wf', idx: n.running ? sprite(n) : n.wf && n.wf.state === 'failed' ? sprite(n) : OPEN_CHEST, x: a[0], y: a[1],
+          state: n.running ? 'fight' : 'win', failed: !n.running && !!n.wf && n.wf.state === 'failed' });
+        return;
+      }
+      a = near(q, q.cx - 1, q.cy, true);
+      out.push({ id: n.id, kind: 'hero', idx: sprite(n), x: a[0], y: a[1], state: n.running ? 'fight' : 'win',
+        foe: FOES[D.prng(seed + '/foe/' + n.id)() * FOES.length | 0], fx: a[0] + 1, fy: a[1], free: room(q, (a[0] + 1) + ',' + a[1]) });
+    });
+    return out;
+  }
+
+  // mem: {id: {state, since}} kept by the caller. An actor first seen gets since = -Infinity, so a page opened on a
+  // finished session shows the resting pose instead of replaying every victory.
+  function stamp(actors, mem, now) {
+    actors.forEach(function (a) {
+      var m = mem[a.id];
+      // A hero's new state starts a fresh walk from its home cell; the guild master keeps walking through idle <-> cast.
+      if (!m || m.state !== a.state) mem[a.id] = { state: a.state, since: m ? now : -Infinity,
+        walk: m && a.kind === 'gm' ? m.walk : { r: D.prng('walk/' + a.id + '/' + now) } };
+      a.since = mem[a.id].since; a.walk = mem[a.id].walk;
+    });
+  }
+
+  function route(free, from, to) { // BFS over free cells; the cells after `from`, ending at `to` ([] if unreachable)
+    var prev = {}, q = [from], k = from + '', i, c;
+    prev[k] = null;
+    while (q.length) {
+      c = q.shift();
+      if (c[0] === to[0] && c[1] === to[1]) { var out = []; for (; prev[c + ''] !== null; c = prev[c + '']) out.unshift(c); return out; }
+      for (i = 0; i < 4; i++) {
+        var n = [c[0] + [1, -1, 0, 0][i], c[1] + [0, 0, 1, -1][i]];
+        if (free[n[0] + ',' + n[1]] && !(n + '' in prev)) { prev[n + ''] = c; q.push(n); }
+      }
+    }
+    return [];
+  }
+
+  // Position of a resting actor at `now`, in fractional cells: run to a random free cell, pause 1-3 s, repeat.
+  // The loop replays whole steps, so a late frame (hidden tab) catches up instead of skipping cells.
+  function walk(a, now) {
+    var w = a.walk, cells = Object.keys(a.free);
+    if (!w.at) { w.at = [a.x, a.y]; w.path = []; w.until = now + 400 + w.r() * 1500; w.face = 1; }
+    for (;;) {
+      if (!w.path.length) {
+        if (now < w.until || !cells.length) return { x: w.at[0], y: w.at[1], moving: false, face: w.face };
+        var t = cells[w.r() * cells.length | 0].split(',');
+        w.path = route(a.free, w.at, [+t[0], +t[1]]); w.t0 = w.until;
+        if (!w.path.length) { w.until += 1000; continue; }
+      }
+      var n = w.path[0], f = (now - w.t0) / STEP_MS;
+      if (n[0] !== w.at[0]) w.face = n[0] > w.at[0] ? 1 : -1;
+      if (f < 1) return { x: w.at[0] + (n[0] - w.at[0]) * f, y: w.at[1] + (n[1] - w.at[1]) * f, moving: true, face: w.face };
+      w.at = w.path.shift(); w.t0 += STEP_MS;
+      if (!w.path.length) w.until = w.t0 + 1000 + w.r() * 2000;
+    }
+  }
+
+  var tints = {};
+  function tinted(img, cols, idx, color, mix) { // cached recolour of one sprite: mix 1 = solid silhouette (hit flash), <1 keeps shading
+    var k = cols + '/' + idx + color + mix;
+    if (tints[k]) return tints[k];
+    var c = document.createElement('canvas'), x = c.getContext('2d');
+    c.width = c.height = 16;
+    x.drawImage(img, idx % cols * 16, (idx / cols | 0) * 16, 16, 16, 0, 0, 16, 16);
+    x.globalCompositeOperation = 'source-atop'; x.globalAlpha = mix; x.fillStyle = color; x.fillRect(0, 0, 16, 16);
+    return (tints[k] = c);
+  }
+
+  // Every offset is a whole number of sprite pixels and every animation steps (no tweening), so it stays pixel art.
+  // still = true (reduced motion) draws each state's resting pose.
+  function draw(ctx, d, actors, sheets, scale, now, still) {
+    var S = 16 * scale, p = scale, td = sheets.td, i;
+    ctx.imageSmoothingEnabled = false;
+    function spr(idx, x, y, o) {
+      o = o || {};
+      ctx.save(); ctx.globalAlpha = o.alpha == null ? 1 : o.alpha;
+      ctx.translate(x + S / 2, y + S / 2); if (o.flip) ctx.scale(-1, 1); if (o.rot) ctx.rotate(o.rot);
+      if (o.flash) ctx.drawImage(tinted(td, 12, idx, '#fff', 1), -S / 2, -S / 2, S, S);
+      else ctx.drawImage(td, idx % 12 * 16, (idx / 12 | 0) * 16, 16, 16, -S / 2, -S / 2, S, S);
+      ctx.restore();
+    }
+    function ob(idx, x, y, alpha, gold) {
+      ctx.save(); ctx.globalAlpha = alpha;
+      if (gold) ctx.drawImage(tinted(sheets.ob, 48, idx, '#ffc21a', 0.75), x, y, S, S);
+      else ctx.drawImage(sheets.ob, idx % 48 * 16, (idx / 48 | 0) * 16, 16, 16, x, y, S, S);
+      ctx.restore();
+    }
+    function dot(color, x, y, n) { ctx.fillStyle = color; ctx.fillRect(Math.round(x / p) * p, Math.round(y / p) * p, (n || 1) * p, (n || 1) * p); }
+    function step(period, n, off) { return still ? 0 : Math.floor((now + off) % period / period * n); }
+
+    actors.forEach(function (a) {
+      var X = (a.x - d.ox) * S, Y = (a.y - d.oy) * S, off = D.prng('t/' + a.id)() * 5000 | 0, k;
+      if (a.kind === 'gm') return rest(a, a.idx); // always roams the hall; casts at each stop while work is going on
+      if (a.kind === 'wf') return spr(a.idx, X + (a.state === 'fight' ? (step(300, 2, off) ? p : -p) : 0), Y, { alpha: a.failed ? 0.5 : 1 });
+
+      var FX = (a.fx - d.ox) * S, el = now - a.since;
+      if (a.state === 'fight') { // 6 beats: wind-up, lunge, hit (enemy flashes, slash, sparks), recoil, counter-attack, reset
+        k = step(900, 6, off);
+        var hx = [0, 2, 4, 1, 0, 0][k] * p, ex = [0, 0, 2, 1, -3, 0][k] * p;
+        spr(a.idx, X + hx, Y);
+        if (k === 4) spr(a.idx, X + hx, Y, { flash: true, alpha: 0.6 });
+        spr(a.foe, FX + ex, Y, { flip: true, flash: k === 2 });
+        if (k === 2) {
+          for (i = 0; i < 4; i++) dot('#ffffff', X + S + i * p, Y + (2 + i * 3) * p, 2);
+          dot('#ffd23f', FX + 2 * p, Y + 2 * p); dot('#ffd23f', FX + 12 * p, Y + 5 * p); dot('#ff5a5a', FX + 7 * p, Y);
+        }
+        return;
+      }
+      // Finished: for 1.6 s after the change the enemy blinks and falls, the hero hops twice under a raised trophy
+      // with a burst of gold; after that the hero rests and cheers (a hop and a sparkle) every few seconds.
+      var v = still ? 1 : Math.min(1, el / 1600), fell = v > 0.3;
+      if (fell) { ob(OB_BONES, FX, Y + 2 * p, 0.9); spr(a.foe, FX, Y + 3 * p, { flip: true, rot: Math.PI / 2, alpha: 0.55 }); }
+      else spr(a.foe, FX, Y, { flip: true, flash: step(200, 2, 0) === 1 });
+      if (v < 1) {
+        var hop = Math.round(Math.abs(Math.sin(v * 2 * Math.PI)) * 6) * p;
+        spr(a.idx, X, Y - hop);
+        ob(OB_TROPHY, X, Y - S - 3 * p - Math.round(v * 6) * p, v < 0.7 ? 1 : (1 - v) / 0.3, true); // above the hop's peak
+        for (i = 0; i < 8; i++) {
+          var g = i / 8 * 6.2832;
+          dot(i % 2 ? '#ffd23f' : '#fff3b0', X + S / 2 + Math.cos(g) * v * 14 * p, Y + S / 2 - hop + Math.sin(g) * v * 14 * p);
+        }
+        return;
+      }
+      rest(a, a.idx);
+    });
+    // Not working: wander (hop while running, face the way it runs); while paused, bob and now and then cheer.
+    function rest(a, idx) {
+      var o = still ? { x: a.x, y: a.y, moving: false, face: 1 } : walk(a, now), off = D.prng('t/' + a.id)() * 5000 | 0;
+      var X = Math.round((o.x - d.ox) * 16) * p, Y = Math.round((o.y - d.oy) * 16) * p;
+      if (o.moving) return spr(idx, X, Y - step(220, 2, off) * p, { flip: o.face < 0 });
+      if (a.state === 'cast') return cast(idx, X, Y, o.face, off);
+      var k = step(4000, 10, off);
+      spr(idx, X, Y - (k === 0 && a.kind === 'hero' ? 3 : step(1600, 2, off)) * p, { flip: o.face < 0 });
+      if (k === 0 && a.kind === 'hero') { dot('#ffd23f', X + 2 * p, Y - 2 * p); dot('#fff3b0', X + 13 * p, Y - p); }
+    }
+    function cast(idx, X, Y, face, off) { // magic circle on the floor, sparks round the hand, a rune rising off the staff
+      var k = step(800, 8, off), j;
+      for (j = 0; j < 4; j++) {
+        var c = (j / 4 + k / 8) * 6.2832;
+        dot(j % 2 ? '#b48cff' : '#5ab4ff', X + S / 2 + Math.cos(c) * 9 * p, Y + S - p + Math.sin(c) * 3 * p, 2);
+      }
+      for (j = 0; j < 3; j++) {
+        var b = (j / 3 + k / 8) * 6.2832;
+        dot(['#ffffff', '#ffd23f', '#b48cff'][j], X + S / 2 + Math.cos(b) * 7 * p, Y + 4 * p + Math.sin(b) * 4 * p, 2);
+      }
+      dot('#b48cff', face < 0 ? X + p : X + 13 * p, Y - (k % 4) * 3 * p, 2);
+      spr(idx, X, Y - (k % 2) * p, { flip: face < 0 });
+    }
+  }
+
+  var Actors = { place: place, stamp: stamp, draw: draw, walk: walk, sprite: sprite, HERO: HERO, FOES: FOES, OPEN_CHEST: OPEN_CHEST };
+  if (typeof module !== 'undefined' && module.exports) module.exports = Actors;
+  root.Actors = Actors;
+})(typeof window !== 'undefined' ? window : this);