@supersuit/session-player 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## 0.4.0 (2026-10-11)
+
+- **Renamed `@supersuit/session-player`** (Gary, 2026-10-11: it plays recorded sessions; case studies and the coming Helm demo are content it plays). Same code as 0.3.2. Swap the package name in your imports; the exports, the scenario format, `SimulatorPlayer` and `<supersuit-simulator>` are unchanged. The CLI is `session-player`, and `simulator` still works. The repository is SupersuitUp/session-player (GitHub redirects the old address).
+
+## 0.3.2 (2026-10-11)
+
+- The last `@supersuit/simulator`. The package is renamed `@supersuit/session-player` (Gary, 2026-10-11: it plays recorded sessions, and case studies and the coming Helm demo are content it plays). No code change; the README and description point to the new name.
+
+## 0.3.1 (2026-10-11)
+
+- A moment never clips a line in half. In a short screen (the MacBook window on continentalworks.ai/demo) the moment's parts were squeezed by flexbox, so the answer and the person's line were cut mid-line. Each part now keeps its height, the big answer is a little smaller (up to 22 px, five lines), and the moment scrolls rather than clipping if it still does not fit. In moments the composer no longer repeats the person's line, which the moment already shows; it keeps its status and its Send and mic.
+
+## 0.3.0 (2026-10-11)
+
+- Highlights (Wilson, 2026-10-11: "make it 40 seconds", "the key things, the most important moments for the human"): `speed` (embed `speed=3`) shortens the work between beats; `highlights` (embed `highlights`) shows where each turn landed, its last answer's first paragraph, with reading time that is never sped up; `steps` (embed) sets how many steps a turn keeps. A recast spec may name a turn's landing answer with `highlight: { "t6": 1 }`.
+- Relief you can see: in highlights the panel is "Handled for <person>", only what got handled (artifacts of kind `other`) ticking off as it lands; the close card can list what Freeda handled (`close.handled`, carried and recast by `recast`). Measured facts only, never time saved.
+- One moment per screen: `moments` (embed `moments`) replaces the scrolling log with the person's line small, where Freeda landed large, a counter ("3 of 8") and what is handled so far. Wilson: "the scroll down ... doesn't give me the TL;DR."
+- An obvious Play, folded into the one Start (Wilson: "make sure the red button is a play button"): the Start demo card's button is now a large pulsing red Play with "Start demo" under it, the Autoplay choice still beside it. There is exactly one Play: the header keeps the Autoplay switch (on by default, named so), and the composer keeps Send and the mic, so no second Play competes with Start.
+- Embeds take the cut too: `speed`, `highlights`, `moments` and `steps` on the iframe URL and as attributes on `<supersuit-simulator>`. A highlights cut still waits on the Start card unless the host opts in with `start=auto`.
+- Board picks on autoplay follow `speed`, as the rest of the run does.
+
+## 0.2.3 (2026-10-11)
+
+- **A Start demo button.** Nothing plays on load anywhere. The device shows a Start card over its screen: the scenario's title, one measured line (commands from the person, Freeda's minutes of work), a Start demo button, and the Autoplay choice beside it (on: it plays itself; off: you play the person). Sending a command or tapping the mic also counts as starting. Play again appears at the end, as before. A host opts into starting at once with `start: 'auto'`, `?start=auto` or `start="auto"` on the tag. Reduced motion is respected (no animation on the card).
+
+## 0.2.2 (2026-10-11)
+
+- **Autoplay is on by default, and is called Autoplay.** The playback checkbox was labelled "auto", next to a device switch whose first option is also Auto, and it was unticked by default, so a viewer read Auto as not selected. Off, the viewer plays the person: each message waits, prefilled, for a tap on Send (or the mic), and each board waits for the viewer's pick, answered with what the person really chose. Turning it on or off says so in a toast. `autoplay={false}`, `?autoplay=off` or `autoplay="off"` on the tag start it off (the old bare `?autoplay` still means on).
+- The device switch marks the active mode and, on Auto, what Auto resolved to: "Auto · iPhone", "Auto · MacBook", or "Auto · this phone". A forced mode is the marked one and Auto carries no hint.
+- Toasts: a tap on the device switch says what is shown now and why ("Now simulating a MacBook: this session ran in Claude Code on a Mac."); a pick on a board says "Same call as X." or "In the real session, X chose Y." Quiet, polite to screen readers, over the demo with no layout shift, gone after about three seconds.
+
+## 0.2.1 (2026-10-11)
+
+- A MacBook in a column too narrow for a believable laptop (under 560 px, such as the book's 434 px figure) keeps its Claude Code window and its "Simulating a MacBook" label and drops the lid, menu bar and base, rather than shrinking into a toy where the composer and the counter overlap.
+
+## 0.2.0 (2026-10-11)
+
+- Device framing. On a desktop or tablet the demo is drawn inside a device: an iPhone (status bar with a real clock, Dynamic Island, side buttons), or a MacBook (lid, notch, menu bar with a real clock, a Claude Code window in a terminal theme, base) when the scenario ran on a Mac. On a phone the demo is the phone, full-bleed, as before.
+- `device` mode: `auto` (default), `iphone` or `macbook`, set by the `device` prop, `?device=` on the embed URL, the `device` attribute on `<supersuit-simulator>`, or the switch on the demo itself (Auto / iPhone / MacBook).
+- A MacBook forced on a phone is never a laptop shrunk into a phone: it is a desktop-style window at phone width with a persistent "Simulating a MacBook" pill. Whenever a frame is drawn, a quiet label outside the screen says what is simulated.
+- Phone or desktop is decided from capability signals (`pointer: coarse`, `hover: none`, `maxTouchPoints`) and the viewport's shorter side, re-read on resize and rotation (`classifyViewer`, `resolveDevice` in `device.mjs`).
+- The scenario format gains an optional `device: "iphone" | "macbook"`, validated; scenarios without it are unchanged and show as an iPhone. `convert` sets `macbook` for a session typed in a terminal (or the desktop app) on a Mac and leaves it unset when it cannot tell; `convert --device` overrides; `recast` keeps it.
+- The player's main container is now named (`container: ss-sim`), so its wide-layout rule follows the MacBook window it sits in. Hosts that copy the player's browser files must also copy `device.mjs` (the player imports it).
+
+## 0.1.1 (2026-10-11)
+
+- Renamed for readers: the Supersuit Simulator is now the **Supersuit Session demo** (the README, the package description, the CLI help and the default page title of `simulator serve`). The package name, the `simulator` CLI, the `supersuit-simulator/1` format, `SimulatorPlayer` and `<supersuit-simulator>` are unchanged, so no install or embed breaks.
+
+## 0.1.0 (2026-10-10)
+
+- The scenario format (`supersuit-simulator/1`) and `validate`.
+- `convert`: drafts a scenario from a Claude Code session transcript. Human turns only, interrupts marked as redirects, tool work condensed into steps timed by wall clock, plumbing tools folded into the next step, chapters from the session name, files and links collected as artifacts, credentials and home paths removed with every cut recorded.
+- Questions the agent asked are kept as the whole board the person saw (`step.ask = { questions: [{ header, question, multiSelect, options: [{ label, description }], answer, chosen }], dismissed }`), read from the session's structured result, and the player draws them as that board: numbered options, the pick checked, a typed answer shown as the person's own words, a closed board marked.
+- Steps and artifacts carry when they happened, so a replay interleaves them with replies.
+- The player: `SimulatorPlayer` (`@supersuit/simulator/player`), mobile first, with persona picker, artifacts and timeline switches; `playback` condenses long turns without changing their totals.
+- `tidy`: cleans the person's commands for display (typo fixes from a reviewer, screenshot paths to [screenshot]), refusing any fix that rewrites what was said; originals kept in `human.raw`, changes in `cuts`.
+- Phone numbers and email addresses are removed from everything a scenario keeps, recorded as cuts.
+- Artifacts are deliverables only (pages, media, documents), never code, config or folders; `tidy` takes `artifacts: { drop, add }` so a reviewer can add what the transcript cannot show (kind `other`, e.g. a release submitted to a store).
+- `recast`: tells a different story from the same real run (new persona and subject, same commands, steps, timing and decisions), marked illustrative on screen, with a `forbid` list that refuses to finish while any word from the original survives.
+- Boards are playable and match the native question board: pinned to the bottom of the phone in place of the composer, one question at a time with a tab per question. Playback pauses on each board, the viewer taps an option (or Other, or Type something else where the person closed it), each pick is answered with the real choice, and the recording resumes on the real path. Autoplay picks the real answers. Once answered, the conversation keeps a compact record (`Asked`): each question, what was chosen, and where the viewer picked differently.
+- The mic "says" the command: tapping it streams the words into the composer like dictation (`dictate`), then sends. It is a 48 px circle, not a stretched oval. The counter reads "No work yet" before anything runs.
+- Idle time is removed: thinking before a step counts at most 3 min, any one step at most 10 min, a question at most 5 min, and a timed-out command counts as no work. What was removed is kept as `step.idleMs`, recorded in cuts, summed by `summarize`, and named on the end screen.
+- Images: what the person pasted is kept from the session (`human.images`); a reviewer attaches what they were shown (`tidy` `images`: on a step, a board, a single option, or the command), since a session often names images only through loop variables; `bundle` copies and shrinks every image into `assets/<id>/` beside the scenario; `recast` must map every image to a replacement by id or it refuses; the player shows option thumbnails, step galleries, pasted images on the command, and tap to enlarge. A step that showed images is never folded into quick steps.
+- The close card (`CloseCard`): a celebration when the session ends, in measured numbers only: Freeda's work time and steps against the person's commands and minutes deciding, the chore freed (from a workflow catalog row), the edge points earned with their four counts, the things made, and the idle time left out. Never time saved. The facts live in an optional `close` block (`tidy` sets it; `recast` carries it, recasts its words, and may restate its measured numbers for the turns it keeps); `validate` refuses an edge total that is not the sum of its counts.
+- Embeddable in any page or book: an `/embed` page for an `<iframe>` (query switches `scenario`, `artifacts`, `timeline`, `autoplay`, `height`), a `<supersuit-simulator>` custom element (`@supersuit/simulator/embed`), `scenarioId` and `height` props, and every overlay contained inside the player, never fixed to the host page's viewport.
+- `bundle` writes a provenance recipe beside every image (mode derive: what it came from, what resized it, and the source's own recipe nested), so a bundled scenario passes a wiki's image-provenance gate.
+- `recast` gives every image a neutral id (`<recast id>-image-<n>`, one per picture), since ids became file names and carried the original's subject.
+- A session opening with a slash command shows the command as typed, not its tags; usage-limit and API-error notices are dropped (they are the harness, and carry the operator's plan and time zone); recast checks and recasts the close card's source notes.
+- The `simulator` CLI: `convert`, `validate`, `tidy`, `recast`, `bundle`, `serve`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @supersuit/session-player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plays recorded agent sessions (case studies, and the coming Helm demo): step into the shoes of someone who needs a great deal of work done, give their commands on a simulated phone, and watch the work and the things it makes appear. Every scenario is built from a real agent session, with the person's corrections left in.
+
+Renamed from `@supersuit/simulator` in 0.4.0 (2026-10-11): it plays recorded sessions, and case studies and the coming Helm demo are content it plays. To move, swap the package name in your imports; the exports, the scenario format (`supersuit-simulator/1`), `SimulatorPlayer` and `<supersuit-simulator>` are unchanged, and the CLI answers to both `session-player` and the old `simulator`.
+
+This package holds the **scenario format**, the **converter** that drafts a scenario from a Claude Code session transcript, and the **player**, a React component that plays scenarios on a simulated phone.
+
+## Install
+
+```
+npm install -g @supersuit/session-player
+```
+
+## Use
+
+```
+simulator convert ~/.claude/projects/<dir>/<session-id>.jsonl --title "Releasing an album" --persona Gary --out album.json
+simulator tidy album.json --fixes fixes.json --out album.json   # {"t7": "corrected text"}
+simulator recast album.json --spec ambient.json --out ambient.json   # same run, different story
+simulator bundle album.json                                    # images into assets/<id>/
+simulator validate album.json
+simulator serve album.json            # watch it at http://127.0.0.1:4460/
+```
+
+`convert` keeps only what the person actually typed as turns (tool results, skill bodies, task notifications, messages from other sessions and interrupt markers are not turns), marks a turn that followed an interrupt as the person redirecting, condenses the agent's tool work into named steps timed by the wall clock, and collects what it delivered: pages it published and the documents, images and audio it made or pointed at (never code or folders, which already show as steps).
+
+**A draft is not ready to publish.** The converter removes credential-shaped strings, phone numbers, email addresses and home-directory paths and records every edit in `cuts`, but it does not anonymize people. Do that, and review the draft, before anyone else sees it.
+
+## The format
+
+`supersuit-simulator/1`, one JSON object:
+
+| Field | What it holds |
+|---|---|
+| `persona` | `{ name, role, blurb }` |
+| `source` | `{ kind: session \| persona, sessionId, date, illustrative }` |
+| `chapters[]` | `{ title, turn }`, from the session's name changes |
+| `turns[]` | `{ id, at, human { text, via, choices[] }, intervention, steps[] { label, tool, ms, count }, replies[] { text, at }, artifacts[] }` |
+| `artifacts[]` | `{ id, kind: file \| link \| other, title, path \| url, turn, at }` |
+| `cuts[]` | `{ turn, what, reason }`: every edit, so nothing is changed silently |
+
+`device` (optional) is where the real session ran: `iphone` or `macbook`. The converter sets `macbook` when the person typed into a terminal (or the desktop app) on a Mac, and leaves it out when it cannot tell (Remote Control and SDK sessions); a scenario without it is shown as an iPhone.
+
+`intervention` is one of `null`, `redirect`, `correct`, `approve`, `decide`. The converter sets only `redirect`; the rest are set by the person reviewing the draft.
+
+## The player
+
+```js
+import { SimulatorPlayer } from '@supersuit/session-player/player';
+<SimulatorPlayer scenario={album} />                       // one scenario
+<SimulatorPlayer scenarios={[dana, marcus]} />             // persona picker first
+<SimulatorPlayer scenario={album} artifacts={false} timeline={false} />  // a limited embed
+```
+
+Nothing plays until the viewer presses Start demo (a host may pass `start: 'auto'` or `?start=auto`). By default the session then plays itself (Autoplay). Untick Autoplay and the viewer plays the person, tapping each command (or the mic to say it), and watches the steps play, sped up from their real durations, with a running count of the work done for the persona. Decisions the person made show as their own cards; things made collect in a side panel on wide screens and a slide-up tray on phones. Needs React 18 or newer; no build step and no stylesheet to import.
+
+## Embedding it in a page or a book
+
+Any page, including a book reader, can drop in an iframe:
+
+```html
+<iframe src="https://<host>/embed?scenario=low-tide-tapes&timeline=off" style="width:100%;height:760px;border:0"></iframe>
+```
+
+A page that runs modules can use the tag instead (it brings its own React through an import map or a bundler):
+
+```html
+<supersuit-simulator src="/simulator/scenarios" scenario="low-tide-tapes" artifacts="off"></supersuit-simulator>
+<script type="module">import { defineSimulatorElement } from '@supersuit/session-player/embed'; defineSimulatorElement();</script>
+```
+
+## A highlights cut
+
+For a short page demo (about 40 seconds), pass `speed` (work between beats runs that many times faster), `highlights` (each turn shows only where it landed, its answer's first paragraph, with real reading time, and the panel ticks off what got handled), `moments` (one screen per moment instead of a scrolling log) and `steps` (how many steps a turn keeps). Same names as props, embed query switches (`?speed=3&highlights&moments&steps=1`) and tag attributes. A recast spec may name a turn's landing answer with `highlight: { "t6": 1 }`, and a scenario's `close.handled` lists what Freeda handled, in measured facts. The Start card still waits for the viewer.
+
+## Device framing
+
+`device` is `auto` (the default), `iphone` or `macbook`: the `device` prop, `?device=` on the embed URL, or the `device` attribute on the tag. The viewer can also switch it on the demo (Auto / iPhone / MacBook).
+
+| | on a phone | on a desktop or tablet |
+| --- | --- | --- |
+| `auto` | full-bleed: the demo is the phone | an iPhone, or a MacBook when the scenario's `device` is `macbook` |
+| `iphone` | full-bleed | an iPhone |
+| `macbook` | a desktop-style window at phone width, labelled "Simulating a MacBook"; never a laptop shrunk into a phone | a MacBook: lid, menu bar clock, a Claude Code window, base |
+
+Whenever a device is drawn, a quiet label outside its screen says what is simulated. Phone or desktop is read from capability signals (coarse pointer, no hover, touch points) and the viewport's shorter side, again on every resize and rotation; a narrow desktop window is still a desktop and an iPad is a desktop unless it is in a narrow split view. Frames are CSS and SVG, sized from the height the player is given, so the same iframe height keeps fitting.
+
+Nothing in the player is fixed to the viewport: the close card and the enlarged image stay inside the player's own box.
+
+## Library
+
+```js
+import { convert, parseSession, validate } from '@supersuit/session-player';
+const scenario = convert(parseSession(text), { title: 'Releasing an album' });
+const problems = validate(scenario); // [] when valid
+```
+
+Exit codes: 0 ok, 1 invalid or refused, 2 usage error. Node 20 or newer, no dependencies.

package/bin/simulator.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// simulator: draft and check Supersuit Session demo scenarios.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { convert, parseSession } from '../src/convert.mjs';
+import { validate } from '../src/scenario.mjs';
+import { createServer } from '../src/serve.mjs';
+import { tidy } from '../src/tidy.mjs';
+import { recast } from '../src/recast.mjs';
+import { bundle } from '../src/bundle.mjs';
+import { dirname, resolve } from 'node:path';
+
+const HELP = `simulator - draft and check Supersuit Session demo scenarios
+
+Usage:
+  simulator convert <session.jsonl> [--out <file>] [--title <t>] [--persona <name>] [--id <id>] [--device iphone|macbook] [--json]
+      Draft a scenario from a Claude Code session transcript. Writes the scenario to --out
+      (or stdout) and a one-line summary to stderr; --json puts the summary on stdout instead.
+      Records where the session ran (device) when the transcript can tell: typed in a terminal
+      on a Mac is a macbook; --device sets it when you know better.
+  simulator validate <scenario.json> [--json]
+      Check a scenario against the format. Exits 1 if anything is wrong.
+  simulator tidy <scenario.json> [--fixes <fixes.json>] [--out <file>]
+      Clean the person's commands for display: screenshot paths become [screenshot], and
+      fixes ({"t7": "corrected text"}) correct typos. Refuses a fix that rewrites what was
+      said. The original stays in human.raw; every change is recorded in cuts.
+  simulator recast <scenario.json> --spec <spec.json> [--out <file>]
+      Tell a different story from the same run: spec is { id, title, persona, keep: [turn ids],
+      replace: [[from, to]], forbid: [words] }. A "from" starting with re: is a regex (global,
+      case-insensitive). Refuses while any forbidden word survives. Marked illustrative.
+  simulator bundle <scenario.json> [--out <file>]
+      Copy every image into assets/<scenario id>/ beside the scenario, shrunk for the phone,
+      and point the scenario at the copies. Refuses if an image source is missing.
+  simulator serve <scenario.json>... [--port 4460] [--host 127.0.0.1]
+      Watch scenarios in the player in a browser. Add ?autoplay=off, ?artifacts=off,
+      ?timeline=off, ?device=iphone|macbook or ?start=auto to the URL to see the limited views an embed uses.
+
+A draft is not a publishable scenario: people in it are not anonymized yet.
+Exit codes: 0 ok, 1 invalid or refused, 2 usage error.`;
+
+function args(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json' || a === '--help' || a === '-h') flags[a.replace(/^-+/, '')] = true;
+    else if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
+    else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+const { pos, flags } = args(process.argv.slice(2));
+const [cmd, file] = pos;
+if (flags.help || flags.h || !cmd) { console.log(HELP); process.exit(cmd || flags.help || flags.h ? 0 : 2); }
+
+try {
+  if (cmd === 'convert') {
+    if (!file) throw Object.assign(new Error('convert needs a session file'), { code: 2 });
+    if (flags.device && !['iphone', 'macbook'].includes(flags.device)) throw Object.assign(new Error('--device must be iphone or macbook'), { code: 2 });
+    const sc = convert(parseSession(readFileSync(file, 'utf8')), {
+      title: flags.title, id: flags.id, persona: flags.persona ? { name: flags.persona } : undefined,
+      device: flags.device,
+    });
+    const problems = validate(sc);
+    const out = JSON.stringify(sc, null, 2) + '\n';
+    if (flags.out) writeFileSync(flags.out, out); else if (!flags.json) process.stdout.write(out);
+    const summary = { ok: problems.length === 0, turns: sc.turns.length, redirects: sc.turns.filter((t) => t.intervention).length, steps: sc.turns.reduce((n, t) => n + t.steps.length, 0), artifacts: sc.artifacts.length, cuts: sc.cuts.length, problems, out: flags.out ?? null };
+    if (flags.json) console.log(JSON.stringify(summary));
+    else console.error(`drafted ${summary.turns} turns, ${summary.steps} steps, ${summary.artifacts} artifacts, ${summary.cuts} cuts${problems.length ? `; PROBLEMS: ${problems.join('; ')}` : ''}`);
+    process.exit(problems.length ? 1 : 0);
+  } else if (cmd === 'validate') {
+    if (!file) throw Object.assign(new Error('validate needs a scenario file'), { code: 2 });
+    const problems = validate(JSON.parse(readFileSync(file, 'utf8')));
+    if (flags.json) console.log(JSON.stringify({ ok: problems.length === 0, problems }));
+    else console.log(problems.length ? problems.map((p) => `- ${p}`).join('\n') : 'valid');
+    process.exit(problems.length ? 1 : 0);
+  } else if (cmd === 'tidy') {
+    if (!file) throw Object.assign(new Error('tidy needs a scenario file'), { code: 2 });
+    const fixes = flags.fixes ? JSON.parse(readFileSync(flags.fixes, 'utf8')) : {};
+    const out = tidy(JSON.parse(readFileSync(file, 'utf8')), fixes);
+    const text = JSON.stringify(out, null, 2) + '\n';
+    if (flags.out) writeFileSync(flags.out, text); else process.stdout.write(text);
+    console.error(`tidied ${out.turns.filter((t) => t.human.raw).length} commands`);
+  } else if (cmd === 'recast') {
+    if (!file || !flags.spec) throw Object.assign(new Error('recast needs a scenario file and --spec'), { code: 2 });
+    const spec = JSON.parse(readFileSync(flags.spec, 'utf8'));
+    spec.replace = (spec.replace ?? []).map(([from, to]) => [from.startsWith('re:') ? new RegExp(from.slice(3), 'gi') : from, to]);
+    const out = recast(JSON.parse(readFileSync(file, 'utf8')), spec);
+    const problems = validate(out);
+    if (problems.length) throw new Error(`recast is not a valid scenario: ${problems[0]}`);
+    const text = JSON.stringify(out, null, 2) + '\n';
+    if (flags.out) writeFileSync(flags.out, text); else process.stdout.write(text);
+    console.error(`recast ${out.turns.length} turns as ${out.persona.name}`);
+  } else if (cmd === 'bundle') {
+    if (!file) throw Object.assign(new Error('bundle needs a scenario file'), { code: 2 });
+    const out = bundle(JSON.parse(readFileSync(file, 'utf8')), { dir: dirname(resolve(file)) });
+    writeFileSync(flags.out ?? file, JSON.stringify(out, null, 2) + '\n');
+    console.error(`bundled images into ${dirname(resolve(file))}/assets/${out.id}`);
+  } else if (cmd === 'serve') {
+    const files = pos.slice(1);
+    if (!files.length) throw Object.assign(new Error('serve needs at least one scenario file'), { code: 2 });
+    const scenarios = files.map((f) => {
+      const sc = JSON.parse(readFileSync(f, 'utf8'));
+      const problems = validate(sc);
+      if (problems.length) throw new Error(`${f} is not a valid scenario: ${problems[0]}`);
+      return sc;
+    });
+    const port = Number(flags.port ?? 4460);
+    const host = flags.host ?? '127.0.0.1';
+    createServer({ scenarios, assetsRoot: dirname(resolve(files[0])) }).listen(port, host, () => console.log(`simulator serving ${scenarios.length} scenario(s) at http://${host}:${port}/`));
+  } else {
+    throw Object.assign(new Error(`unknown command: ${cmd}`), { code: 2 });
+  }
+} catch (e) {
+  console.error(`simulator: ${e.message}`);
+  process.exit(e.code === 2 ? 2 : 1);
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@supersuit/session-player",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Plays recorded agent sessions (case studies) on a simulated phone or MacBook: a scenario format, a converter from Claude Code transcripts, and a React player anyone can step into.",
+  "type": "module",
+  "bin": {
+    "session-player": "bin/simulator.mjs",
+    "simulator": "bin/simulator.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./player": "./src/player.mjs",
+    "./embed": "./src/embed.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SupersuitUp/session-player.git"
+  },
+  "keywords": [
+    "supersuit",
+    "simulator",
+    "claude-code",
+    "agents",
+    "replay"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/bundle.mjs

@@ -0,0 +1,56 @@
+// Makes a scenario self-contained: every image is copied into `<dir>/assets/<scenario id>/`,
+// shrunk for the phone, and the scenario points at it by a relative path. Pasted images
+// arrive as data URIs and are written out the same way. A source that is missing is refused,
+// so a scenario never ships with a hole where a cover should be.
+
+import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, extname } from 'node:path';
+import { allImages } from './scenario.mjs';
+
+const EXT = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp', 'image/gif': '.gif' };
+
+// Every copied image gets a `.recipe.json` beside it in the derive shape wikis check
+// (mode, derivedFrom, generator, timestamp), with the source's own recipe nested as `source`
+// when the source had one, so the chain back to the model and prompt is never cut.
+function writeRecipe(file, { derivedFrom, generator, sourceFile }) {
+  const recipe = { mode: 'derive', asset: file.split('/').pop(), derivedFrom, generator, timestamp: new Date().toISOString() };
+  if (sourceFile && existsSync(`${sourceFile}.recipe.json`)) {
+    try { recipe.source = JSON.parse(readFileSync(`${sourceFile}.recipe.json`, 'utf8')); } catch { /* an unreadable source recipe is left out, not invented */ }
+  }
+  writeFileSync(`${file}.recipe.json`, JSON.stringify(recipe, null, 2) + '\n');
+}
+
+export function bundle(scenario, { dir, resize = true, max = 900 } = {}) {
+  const sc = structuredClone(scenario);
+  const rel = join('assets', sc.id);
+  mkdirSync(join(dir, rel), { recursive: true });
+  const done = new Map();
+  for (const img of allImages(sc)) {
+    if (img.src.startsWith('assets/')) continue;
+    if (done.has(img.src)) { img.src = done.get(img.src); continue; }
+    let name;
+    if (img.src.startsWith('data:')) {
+      const [, type, data] = img.src.match(/^data:([^;]+);base64,(.*)$/s) ?? [];
+      if (!data) throw new Error(`image ${img.id} has an unreadable data URI`);
+      name = `${img.id}${EXT[type] ?? '.png'}`;
+      writeFileSync(join(dir, rel, name), Buffer.from(data, 'base64'));
+      writeRecipe(join(dir, rel, name), { derivedFrom: `an image pasted into the session by the operator (${type})`, generator: '@supersuit/session-player convert + bundle (decoded from the transcript)' });
+    } else {
+      if (!existsSync(img.src)) throw new Error(`image ${img.id}: ${img.src} does not exist`);
+      if (resize && process.platform === 'darwin') {
+        name = `${img.id}.jpg`;
+        execFileSync('sips', ['-Z', String(max), '-s', 'format', 'jpeg', '-s', 'formatOptions', '80', img.src, '--out', join(dir, rel, name)], { stdio: 'ignore' });
+        writeRecipe(join(dir, rel, name), { derivedFrom: img.src, generator: `@supersuit/session-player bundle (sips -Z ${max}, jpeg quality 80)`, sourceFile: img.src });
+      } else {
+        name = `${img.id}${extname(img.src) || '.png'}`;
+        copyFileSync(img.src, join(dir, rel, name));
+        writeRecipe(join(dir, rel, name), { derivedFrom: img.src, generator: '@supersuit/session-player bundle (copied unchanged)', sourceFile: img.src });
+      }
+    }
+    const out = `${rel}/${name}`.split('\\').join('/');
+    done.set(img.src, out);
+    img.src = out;
+  }
+  return sc;
+}