@supersuit/session-player 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.0 (2026-10-11)
+
+- A recast spec may state `device` (`iphone` or `macbook`) when the source could not tell where the real session ran. A Remote Control or SDK session reads the same from a Mac and a phone, so the converter leaves `device` unset and Auto drew an iPhone for a session that really ran on a MacBook (Callum's case study). The spec wins over the source; without it the source's device is kept, as before.
+- `@supersuit/session-player/playback` exports `summarize` and `duration`, so a host page can print the measured who-did-what beside the player without importing the converter.
+
+## 0.6.0 (2026-10-11)
+
+- **Transparent by default** (Gary, 2026-10-11: "render with NO background colour ... so it sits on any site"). Nothing is painted outside the device frame; the frame and the screen keep their own backgrounds. A host that wants one passes `background` (prop or tag attribute) or `?bg=` on the embed URL: any CSS colour, or `theme` for the player's cream. A value that is not a colour is ignored.
+- **Embed it anywhere with one tag** (Gary: "make it easier to embed in any website"): `<script src=".../simulator/embed.js" async></script>` then `<session-player scenario="...">`. A plain script (`src/loader.js`, exported as `@supersuit/session-player/loader.js`, served at `/embed.js` by `session-player serve`) that turns each tag into an iframe of the embed page sized to its content. Defaults: Auto device, Autoplay on, waits for Start.
+- In an iframe the player posts its height (`session-player:height`) and the end of a session (`session-player:done`) to the host page; the loader uses both, and fires `session-player:done` on the iframe so a host can offer the next case study.
+- The README opens with both embed forms.
+
 ## 0.5.0 (2026-10-11)
 
 - **The player is the 0.2.3 experience again** (Gary, 2026-10-11: "really not loving the post-Wilson-merge case study widget, revert the UX"). Wilson's 0.3.0 changes and the 0.3.1 moments fix are reverted with `git revert`, so his commits stay in history: the Start card is back as it was (title, measured line, Start demo button, Autoplay choice; nothing plays on load; `start: 'auto'` opts in), Autoplay is on by default and playing the person when off, and device framing (Auto / iPhone / MacBook, the narrow-MacBook fallback, "Simulating a MacBook" on a phone, toasts) is unchanged from 0.2.3. Gone: `speed`, `highlights`, `moments`, `steps`, the highlights close card and the "Handled for" panel. An embed, tag or prop that still passes them is ignored rather than refused, so existing embeds keep working.

package/README.md

@@ -4,6 +4,26 @@ Plays recorded agent sessions (case studies, and the coming Helm demo): step int
 
 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`.
 
+## Embed it in any website
+
+One tag, any page, any framework or none. Paste this where the case study should appear:
+
+```html
+<script src="https://continentalworks.ai/simulator/embed.js" async></script>
+<session-player scenario="phone-rescue"></session-player>
+```
+
+The player sizes itself to its content (no fixed height), is transparent around the device so it sits on your page's own background, picks the device for the viewer (Auto), plays on Autoplay, and waits for the viewer to press Start. Optional attributes: `device` (`auto`, `iphone`, `macbook`), `autoplay="off"` (the viewer plays the person), `start="auto"` (start without the Start card), `background` (a CSS colour, or `theme` for the player's cream), `artifacts="off"`, `timeline="off"`, `height` (the device's height, e.g. `640px`), `title`.
+
+No scripts allowed? Use the iframe on its own, with a fixed height:
+
+```html
+<iframe src="https://continentalworks.ai/simulator/embed?scenario=phone-rescue" title="Case study"
+        style="width:100%;height:860px;border:0;background:transparent" loading="lazy"></iframe>
+```
+
+The same query switches work on the URL (`device`, `autoplay=off`, `start=auto`, `bg`, `artifacts=off`, `timeline=off`, `height`). Inside an iframe the player posts `{ type: 'session-player:height', height }` to its parent whenever its height changes, and `{ type: 'session-player:done', scenario }` when a session ends, so the script above (or your own listener) can size the frame and offer what comes next. Any host serving the player can serve the loader: it is `src/loader.js` (export `@supersuit/session-player/loader.js`), and `session-player serve` serves it at `/embed.js`.
+
 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
@@ -40,7 +60,7 @@ simulator serve album.json            # watch it at http://127.0.0.1:4460/
 | `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.
+`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. Because unset can mean either, whoever ran the session should state it: `convert --device`, or `device` in a recast spec (0.7.0), which overrides the source.
 
 `intervention` is one of `null`, `redirect`, `correct`, `approve`, `decide`. The converter sets only `redirect`; the rest are set by the person reviewing the draft.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/session-player",
-  "version": "0.5.0",
+  "version": "0.7.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": {
@@ -11,7 +11,9 @@
     ".": "./src/index.mjs",
     "./player": "./src/player.mjs",
     "./embed": "./src/embed.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./loader.js": "./src/loader.js",
+    "./playback": "./src/playback.mjs"
   },
   "files": [
     "bin/",

package/src/embed.mjs

@@ -19,6 +19,8 @@ export function propsFromAttributes(a) {
     height: a.height || undefined,
     device: a.device || undefined,
     start: a.start || undefined,
+    // 0.6.0: transparent unless the host names a colour or 'theme'.
+    background: a.background || a.bg || undefined,
   };
 }
 

package/src/loader.js

@@ -0,0 +1,72 @@
+// The one-tag embed (0.6.0, Gary, 2026-10-11: "make it easier to embed in any website").
+//
+//   <script src="https://continentalworks.ai/simulator/embed.js" async></script>
+//   <session-player scenario="phone-rescue"></session-player>
+//
+// A plain script with no imports and no React: it works on any page, in any framework or none.
+// Each <session-player> becomes an iframe of the embed page that served this script, sized to the
+// player's content (the player posts its height; no fixed 720px), transparent around the device.
+// Defaults: Auto device, Autoplay on, waits for Start. Attributes, all optional: scenario, device
+// (auto|iphone|macbook), autoplay ("off"), start ("auto"), background or bg (a CSS colour or
+// "theme"), artifacts ("off"), timeline ("off"), height (the device's height, e.g. "640px"),
+// title, and src (another embed page). A plain <iframe> of the embed page on the same page is
+// resized too. Each iframe also fires `session-player:done` (bubbling) when its session ends.
+(function () {
+  'use strict';
+  if (typeof window === 'undefined' || typeof document === 'undefined') return;
+  if (window.__sessionPlayerLoader) return;
+  window.__sessionPlayerLoader = true;
+
+  var me = document.currentScript;
+  var base = (me && me.getAttribute('data-embed')) || (me && me.src ? new URL('embed', me.src).href : '/simulator/embed');
+  var PASS = { scenario: 'scenario', device: 'device', autoplay: 'autoplay', start: 'start', background: 'bg', bg: 'bg', artifacts: 'artifacts', timeline: 'timeline' };
+
+  // The device's height, from the HOST's window: inside the iframe 100svh would be the iframe's
+  // own height, which this script sets from the content, so it would chase itself.
+  function deviceHeight() {
+    var v = window.innerHeight || 800;
+    return Math.max(480, Math.min(760, v - 120));
+  }
+
+  function srcFor(el) {
+    var u = new URL(el.getAttribute('src') || base, location.href);
+    for (var k in PASS) {
+      var v = el.getAttribute(k);
+      if (v != null) u.searchParams.set(PASS[k], v);
+    }
+    if (!u.searchParams.has('height')) u.searchParams.set('height', el.getAttribute('height') || deviceHeight() + 'px');
+    return u.href;
+  }
+
+  function mount(el) {
+    if (el.__sessionPlayerFrame) return;
+    var f = document.createElement('iframe');
+    f.src = srcFor(el);
+    f.title = el.getAttribute('title') || 'Case study';
+    f.setAttribute('loading', 'lazy');
+    f.setAttribute('allow', 'clipboard-write');
+    f.setAttribute('allowtransparency', 'true');
+    // color-scheme normal keeps the frame transparent on a dark-mode host page.
+    f.style.cssText = 'display:block;width:100%;border:0;background:transparent;color-scheme:normal;height:' + (deviceHeight() + 90) + 'px';
+    el.style.display = 'block';
+    el.appendChild(f);
+    el.__sessionPlayerFrame = f;
+  }
+
+  window.addEventListener('message', function (e) {
+    var d = e.data;
+    if (!d || typeof d !== 'object' || typeof d.type !== 'string' || d.type.indexOf('session-player:') !== 0) return;
+    var frames = document.getElementsByTagName('iframe');
+    for (var i = 0; i < frames.length; i++) {
+      if (frames[i].contentWindow !== e.source) continue;
+      if (d.type === 'session-player:height' && d.height > 0) frames[i].style.height = Math.ceil(d.height) + 'px';
+      frames[i].dispatchEvent(new CustomEvent(d.type, { detail: d, bubbles: true }));
+    }
+  });
+
+  if (window.customElements && !window.customElements.get('session-player')) {
+    window.customElements.define('session-player', class extends HTMLElement {
+      connectedCallback() { mount(this); }
+    });
+  }
+})();

package/src/player.mjs

@@ -202,7 +202,38 @@ export function CloseCard({ sc, person, onReplay, onBack }) {
         onBack && h('button', { className: 'ss-chip ss-ghost', onClick: onBack }, 'Step into someone else'))));
 }
 
-export function SimulatorPlayer({ scenario, scenarios, scenarioId, height, autoplay = true, artifacts = true, timeline = true, maxSteps = 5, device, viewer, start: startMode }) {
+// The space around the device is transparent unless a host asks for a colour (0.6.0, Gary,
+// 2026-10-11: "render with NO background colour ... so it sits on any site"). 'theme' is the
+// player's own cream; anything else is a CSS colour. The device frame and the screen keep theirs.
+export function backgroundFor(bg) {
+  if (bg == null) return undefined;
+  const v = String(bg).trim();
+  if (!v || v === 'transparent' || v === 'none') return undefined;
+  if (v === 'theme') return 'var(--ss-cream)';
+  // A colour, never a declaration: no semicolons, braces or url().
+  return /^[#a-zA-Z0-9(),.%\s-]+$/.test(v) && !/url\(/i.test(v) ? v : undefined;
+}
+
+// Inside an iframe, tell the host page how tall the player is and when a session ends, so an
+// embed can size itself to its content (the loader does) and offer what comes next.
+export const MESSAGE = { height: 'session-player:height', done: 'session-player:done' };
+export function reportToHost(el, win = typeof window === 'undefined' ? undefined : window, RO = typeof ResizeObserver === 'undefined' ? undefined : ResizeObserver) {
+  if (!el || !win || !win.parent || win.parent === win || !RO) return () => {};
+  let last = 0;
+  const post = () => {
+    const height = Math.ceil(el.getBoundingClientRect().height);
+    if (height > 0 && height !== last) { last = height; win.parent.postMessage({ type: MESSAGE.height, height }, '*'); }
+  };
+  const ro = new RO(post);
+  ro.observe(el);
+  post();
+  return () => ro.disconnect();
+}
+const tellHost = (msg) => { if (typeof window !== 'undefined' && window.parent && window.parent !== window) window.parent.postMessage(msg, '*'); };
+
+export function SimulatorPlayer({ scenario, scenarios, scenarioId, height, autoplay = true, artifacts = true, timeline = true, maxSteps = 5, device, viewer, start: startMode, background }) {
+  const root = useRef(null);
+  useEffect(() => reportToHost(root.current), []);
   const list = scenarios ?? (scenario ? [scenario] : []);
   // An embed may name one scenario from a list and skip the picker.
   const start = scenarioId != null ? Math.max(0, list.findIndex((s) => s.id === scenarioId)) : list.length > 1 ? null : 0;
@@ -215,7 +246,9 @@ export function SimulatorPlayer({ scenario, scenarios, scenarioId, height, autop
   const [seen, setSeen] = useState(() => viewer ?? readViewer());
   useEffect(() => (viewer ? undefined : watchViewer(setSeen)), [viewer]);
   const sc = pick == null ? null : list[pick];
-  return h('div', { className: 'ss-sim', style: height ? { '--ss-height': height } : undefined },
+  const bg = backgroundFor(background);
+  const style = height || bg ? { ...(height ? { '--ss-height': height } : {}), ...(bg ? { background: bg } : {}) } : undefined;
+  return h('div', { className: 'ss-sim', ref: root, style },
     h('style', null, PLAYER_CSS),
     sc ? h(Run, { key: sc.id, sc, autoplay, start: startMode, artifacts, timeline, maxSteps, mode, setMode, viewer: viewer ?? seen, onBack: list.length > 1 && scenarioId == null ? () => setPick(null) : null })
       : h(Picker, { scenarios: list, onPick: setPick }));
@@ -291,6 +324,7 @@ function Run({ sc, autoplay, start, artifacts: showArtifacts, timeline, maxSteps
   const person = sc.persona?.name ?? 'You';
   const [turn, setTurn] = useState(0);
   const [phase, setPhase] = useState('ready'); // ready | saying | working | done
+  useEffect(() => { if (phase === 'done') tellHost({ type: MESSAGE.done, scenario: sc.id }); }, [phase, sc.id]);
   const [log, setLog] = useState([]);
   const [made, setMade] = useState([]);
   const [work, setWork] = useState({ ms: 0, steps: 0 });

package/src/recast.mjs

@@ -27,8 +27,14 @@ const where = (sc, obj) => sc.turns.find((t) => t.human === obj || t.steps.some(
 
 import { allImages } from './scenario.mjs';
 
-export function recast(source, { id, title, persona, keep, replace = [], forbid = [], images = {}, close, highlight = {} }) {
+export function recast(source, { id, title, persona, keep, replace = [], forbid = [], images = {}, close, highlight = {}, device }) {
   const sc = structuredClone(source);
+  // Where the real session ran, when the source could not say (0.7.0): a Remote Control or SDK
+  // session reads the same from a Mac and from a phone, so the person who ran it states it here.
+  if (device != null) {
+    if (!['iphone', 'macbook'].includes(device)) throw new Error(`device must be iphone or macbook, got ${JSON.stringify(device)}`);
+    sc.device = device;
+  }
   const cuts = [];
   if (keep) {
     const kept = new Set(keep);

package/src/serve.mjs

@@ -31,7 +31,7 @@ import { SimulatorPlayer } from './src/player.mjs';
 const scenarios = await (await fetch('./scenarios.json')).json();
 const q = new URLSearchParams(location.search);
 createRoot(document.getElementById('root')).render(h(SimulatorPlayer, {
-  scenarios, scenarioId: q.get('scenario') ?? undefined, height: q.get('height') ?? undefined, autoplay: q.get('autoplay') !== 'off', artifacts: q.get('artifacts') !== 'off', timeline: q.get('timeline') !== 'off', device: q.get('device') ?? undefined, start: q.get('start') ?? undefined,
+  scenarios, scenarioId: q.get('scenario') ?? undefined, height: q.get('height') ?? undefined, autoplay: q.get('autoplay') !== 'off', artifacts: q.get('artifacts') !== 'off', timeline: q.get('timeline') !== 'off', device: q.get('device') ?? undefined, start: q.get('start') ?? undefined, background: q.get('bg') ?? undefined,
 }));
 </script></body></html>`;
 }
@@ -43,6 +43,8 @@ export function createServer({ scenarios, assetsRoot }) {
     const send = (code, type, body) => { res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' }); res.end(body); };
     if (path === '/' || path === '/index.html') return send(200, 'text/html; charset=utf-8', page({ title: scenarios.length === 1 ? scenarios[0].title : undefined }));
     if (path === '/embed') return send(200, 'text/html; charset=utf-8', page({ embed: true }));
+    // The one-tag embed: <script src=".../embed.js"></script><session-player scenario="...">.
+    if (path === '/embed.js') return send(200, 'text/javascript; charset=utf-8', readFileSync(join(SRC, 'loader.js')));
     if (path === '/scenarios.json') return send(200, 'application/json', JSON.stringify(scenarios));
     const a = assetsRoot && path.match(/^\/assets\/([\w-]+)\/([\w.-]+\.(?:png|jpe?g|webp|gif))$/i);
     if (a) {