storyshot 0.1.0 → 0.3.1

package/README.md

@@ -15,6 +15,35 @@ second or two on screen.
 The agent plans, writes and fixes the storyboard. Storyshot does the
 recording and editing, and the same storyboard always renders the same video.
 
+## Next to similar tools
+
+Storyshot, [promo-video-recorder](https://github.com/palamut62/promo-video-recorder)
+and [demo-dev](https://www.npmjs.com/package/demo-dev) each made a promo of this
+repo's page, with the same storyline and free local voices only. The grid
+below is muted; open the full videos to hear them.
+
+https://github.com/user-attachments/assets/3d8175ab-ba15-4b61-961d-481e57566e7a
+
+<details>
+<summary>The three full videos, with sound</summary>
+
+**Storyshot**
+
+https://github.com/user-attachments/assets/22987356-2a74-4e28-9a14-a1b01d04f932
+
+**promo-video-recorder**
+
+https://github.com/user-attachments/assets/e5eb86e5-e69c-403b-ad6c-c4499592307a
+
+**demo-dev**
+
+https://github.com/user-attachments/assets/8d3370ca-7a90-48af-b1c9-88189763e95d
+
+</details>
+
+How each one was made, what we saw, and the caveats:
+[docs/comparison](docs/comparison/README.md).
+
 ## Quick start
 
 Open your project in Cursor or Claude Code and paste this into the agent chat:
@@ -51,8 +80,8 @@ macOS, Linux and Windows.
 
    ```
    Here's the plan. Reply "ok", or change any line:
-   1. Type: pitch: a 15–30 s promo
-   2. Length: about 15 s, 6 shots
+   1. Type: pitch: a promo for the landing page
+   2. Length: about 20 s, 6 shots
    3. Flow: hero → Examples → Try It → AI result → pricing → end card
    4. Voice: none (other options: free local English voice; ElevenLabs, key found in .env)
    5. Music: upbeat · Captions: English · Subtitle file (.srt): no
@@ -82,10 +111,13 @@ After your next release, re-render it and you have an up-to-date video.
 
 | ask for | type (`purpose`) | you get |
 |---|---|---|
-| a promo / launch / landing-page clip | `pitch` | 15–30 s, music, captions, tightly cut |
-| a how-to or onboarding video | `tutorial` | narrated, a spotlight on each click, numbered steps, soft music, `.srt` + chapters |
-| a lesson or explainer | `course` | narrated and explains the *why*, no music, `.srt` + chapters |
-| help-center snippets | `docs` | silent, one GIF per step |
+| a promo / launch / landing-page clip | `pitch` | short and tightly cut: intro card, the app in a browser frame, music, captions |
+| a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters |
+| a lesson or explainer | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
+
+Length follows the purpose and the content, not a target: a promo is as short as
+its message, a tutorial as long as the workflow takes to explain.
 
 Any type can also be vertical (9:16) or in another language.
 
@@ -108,11 +140,14 @@ so a change only pays for the lines that changed.
 
 When the flow is behind a login, the agent says so in its plan. Then:
 
-1. A browser window opens (the `login` tool, or `storyshot login <url>`).
-2. You log in there. 2FA and "Sign in with Google" work.
-3. The session is saved to `videos/<site>-login.json` once you're logged in, or
-   when you close the window. It includes cookies, localStorage and IndexedDB,
-   and the file is added to `.gitignore` because it holds your session.
+1. A normal Chrome window opens (the `login` tool, or `storyshot login <url>`).
+   No script is attached to it while you log in, so "Sign in with Google" and
+   2FA work as usual.
+2. You log in there. When you see the app logged in, tell the agent "done"
+   (or press Enter in the terminal). You can also just close the window.
+3. The session is saved to `videos/<site>-login.json`. It includes cookies,
+   localStorage, IndexedDB and sessionStorage, and the file is added to `.gitignore` because
+   it holds your session. The temporary browser profile is deleted.
 4. Every recording starts logged in, so the video never shows a login screen.
 
 If the session expires, Storyshot says so ("the saved login has expired, run
@@ -191,15 +226,24 @@ music: { bpm: 120, volume: 1 }                  # or { file: track.mp3 }, or fal
 sfx: true                                       # click / whoosh / riser sounds
 voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceover, see below
 storageState: auth.json                         # optional Playwright login state
+ignoreHTTPSErrors: true                         # internal site with a self-signed HTTPS certificate (plain http:// needs nothing)
 captionPosition: bottom                         # or top; can also be set per step. A caption that would cover a step's click target or zoom subject moves to the other side automatically
 purpose: pitch                                  # pitch | tutorial | course | docs (sets the defaults below)
 highlight: false                                # spotlight targets before click/type (per step or per action too)
 stepNumbers: false                              # numbered caption badges
-subtitles: false                                # write <out>.srt (narration, else captions)
+subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top)
+pace: slow                                      # fast (pitch) | normal (docs) | slow (tutorial, course): cursor and typing speed, a beat after each click, hold after narration, voice speed, how much of a wait is shown
+follow: true                                    # tutorial/course default: the camera zooms in on what each step touches and pans between steps (a step's own zoom wins; follow: false on a step skips it); or { scale: 1.8 }
+frame: true                                     # pitch default: the recording sits in a browser window on a backdrop; false = full frame, or { background: <css> }
 chapters: false                                 # write <out>.chapters.txt for YouTube
-clips: null                                     # gif | webm | mp4: one file per step in <out>-steps/
+clips: null                                     # gif | webm | mp4 | png, or a list (docs default: [gif, png]): one file per step in <out>-steps/, cropped to what the step touches, plus README.md, a ready-to-paste article (step captions, `doc:` text, images)
 maxWait: 1.0                                    # with duration: auto, the longest a wait is shown
 
+intro:                                          # optional title card before the recording (same fields as end_card)
+  title: Acme
+  subtitle: Ship **faster**
+  say: Meet Acme.
+
 setup:                                          # runs before recording starts
   - dismiss: { role: button, name: Accept cookies }
 
@@ -216,6 +260,11 @@ steps:
     sfx: riser                                        # rising sound + chime (or `chime`)
     actions:
       - waitFor: { text: Done, timeout: 120000 }      # waiting is compressed automatically
+  - card: { kicker: Part 2, title: Read the results }  # a section card before this step (tutorials); becomes a chapter
+    caption: The hits table
+    say: Each row is a protein similar to yours.
+    actions:
+      - mark: { css: "tbody tr:nth-child(1)" }
   - hidden: true                                      # cut, not shown in the video
     actions:
       - goto: /
@@ -256,6 +305,10 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` |
 | `scroll` | `scroll: 600` |
 | `dismiss` | `dismiss: { role: button, name: Close }` (clicks only if visible) |
+| `mark` | `mark: "automatic zoom, captions"` sweeps a highlighter over that phrase, even inside a paragraph (scrolling to it if needed). `mark: { css: "table tr:nth-child(3)" }` marks any target with a box. Options: `ms` (sweep time, default 700), `color` (default: theme accent), `box: true/false`. Marks stay until the step ends. |
+| `unmark` | `unmark: true` clears the marks (and notes) earlier |
+| `note` | `note: { target: { label: Database }, text: Curated proteins only }` puts a short label with an arrow next to the element, on the side with the most room (or `side: left/right/top/bottom`). It stays until the step ends and gets reading time (about 3 words a second, or `ms`). |
+| `select` | `select: { target: { label: Database }, option: "UniProtKB/Swiss-Prot" }` picks an option in a dropdown (by its visible text, or part of it). `inspect` lists each dropdown's options. |
 
 `ms` sets how long the cursor takes to travel to the target (`dragMs` for each
 drag move). `highlight: true/false` on `click`, `type` or `move` overrides the
@@ -322,17 +375,28 @@ changed. Write names the way they should be pronounced (`say: P X Genius.`),
 and spell out prices (`eleven ninety-nine`) in `pronounce` or in the line itself. At normal pace that comes to
 about 2.5 words per second, or roughly 35 words for a 15 s video.
 
-### End card
+### Intro and end card
 
-Every field is optional; leave out `end_card` entirely for no end card.
+Every field is optional; leave out `intro` / `end_card` for none. A step's
+`card` takes the same fields and plays before that step (section titles in
+tutorials). Both are short
+animations: the logo pops in, the title rises, the `**bold**` highlight sweeps,
+and a `cta` that is a command (`npx …`, `npm …`, `pip …`, `brew …`, `curl …`)
+types itself out in a terminal pill. `init` writes an `intro` for promos;
+tutorials and lessons can add one (e.g. "How to export a report"), docs GIFs
+usually shouldn't.
 
 | field | meaning |
 |---|---|
 | `logo` | A target on the page (captured as an image, e.g. `{ alt: Acme logo }`) or a path to an image file. If the logo image already contains the wordmark, leave out `title`. |
 | `title` | Large product name next to the logo. |
+| `kicker` | Small label above the title, e.g. `Part 2`. |
 | `subtitle` | One line; `**bold**` gets an accent highlight. |
+| `image` | A picture or diagram file (png, jpg, svg) under the title: concept cards in lessons. |
+| `think` | Seconds to pause after the card's `say` (a question card), with a "Pause and think" countdown. The next step shows the answer. |
+| `bullets` | A numbered list that appears one item at a time: "what you'll learn" on an intro, a recap on the end card. The card stays up long enough to read it. |
 | `cta` | Dark call-to-action pill, e.g. `Start free at acme.com`. |
-| `duration` | Seconds (default 1.0). |
+| `duration` | Seconds. Default: fits the `say` line, else 1.0 (end card) or 2.2 (intro). |
 | `say` | Voiceover line played over the end card. |
 
 ## License

package/bin/storyshot.mjs

@@ -33,6 +33,8 @@ Options:
   --draft   (render/compose) use the free local voice instead of a paid TTS provider and write
             <out>.draft.mp4; when it looks right, run \`compose\` without --draft (reuses the recording)
   --viewport 1600x900   (inspect, init)
+  --insecure            (inspect, init) accept a self-signed HTTPS certificate (internal sites);
+                        storyboards use \`ignoreHTTPSErrors: true\`
 `;
 
 const args = process.argv.slice(2);
@@ -80,11 +82,11 @@ try {
   } else if (cmd === 'login') {
     const { login, authFileFor } = await import('../src/auth.mjs');
     const r = await login(arg, { file: flag('save') ?? authFileFor(arg), viewport: viewport() });
-    console.log(`✔ saved the login session to ${r.file} (${r.how}, ${r.cookies} cookies)${r.gitignore ? `\n  added it to ${r.gitignore}` : ''}` +
+    console.log(`✔ saved the login session to ${r.file} (${r.how}, ${r.cookies} cookies, ${r.siteCookies} for this site${r.sessionStorage ? `, sessionStorage for ${r.sessionStorage} site(s)` : ''})${r.gitignore ? `\n  added it to ${r.gitignore}` : ''}` +
       `\n  use it: \`storageState: ${r.file.split(/[\\/]/).pop()}\` in the storyboard (path relative to the yaml), or \`--storage ${r.file}\` for inspect/init`);
   } else if (cmd === 'init') {
     const { initStoryboard } = await import('../src/init.mjs');
-    const r = await initStoryboard(arg, { purpose: flag('purpose') ?? 'pitch', topic: flag('topic'), file: flag('file'), storageState: flag('storage'), viewport: viewport() });
+    const r = await initStoryboard(arg, { purpose: flag('purpose') ?? 'pitch', topic: flag('topic'), file: flag('file'), storageState: flag('storage'), ignoreHTTPSErrors: args.includes('--insecure'), viewport: viewport() });
     console.log(`✔ wrote ${r.file}\n  screenshot: ${r.screenshot}\n  next: edit it, then \`storyshot check ${r.file}\``);
   } else if (cmd === 'inspect') {
     await (await import('../src/doctor.mjs')).ensureBrowser();
@@ -94,7 +96,7 @@ try {
       const after = flag('after');
       console.log((await record(cfg, { log: () => {}, inspectAfter: after != null ? Number(after) : cfg.steps.length })).text);
     } else {
-      console.log((await inspect(arg, { viewport: viewport(), storageState: flag('storage') })).text);
+      console.log((await inspect(arg, { viewport: viewport(), storageState: flag('storage'), ignoreHTTPSErrors: args.includes('--insecure') })).text);
     }
   } else if (cmd === 'check') {
     const r = check(arg, { draft: args.includes('--draft') });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Turn a short YAML storyboard into a polished product demo video of your web app — smooth cursor, auto zoom, captions, music.",
   "author": "boheling <boheling@gmail.com>",
   "repository": {

package/skills/storyshot/SKILL.md

@@ -55,9 +55,9 @@ everything.
 
    ```
    Here's the plan. Reply "ok", or change any line:
-   1. Type: pitch: a 15–30 s promo (other options: tutorial = narrated how-to;
-      course = narrated lesson; docs = silent step-by-step GIFs)
-   2. Length: about 15 s, 6 shots
+   1. Type: pitch: a promo for the landing page (other options: tutorial =
+      narrated how-to; course = narrated lesson; docs = silent step-by-step GIFs)
+   2. Length: about 20 s, 6 shots (it follows from the flow below)
    3. Flow: hero → Examples → Try It → AI result → pricing → end card
    4. Voice: none (other options: free local English voice; ElevenLabs, best
       quality and Chinese support, key found in .env)
@@ -67,14 +67,16 @@ everything.
       window for you to log in once; please use a demo account)
    ```
 
-   Defaults by type (propose these unless the request says otherwise):
+   Defaults by type (propose these unless the request says otherwise). There
+   is no target length: it follows from the purpose and the content. Estimate
+   it from the flow and say it in the plan, so the user can react.
 
-   | type | length | voice | music | on screen / files |
+   | type | length comes from | voice | music | on screen / files |
    |---|---|---|---|---|
-   | `pitch` | 15 s (or 30 s), 5–7 shots | optional | upbeat | captions |
-   | `tutorial` | 45–90 s, 6–12 steps | yes | soft | step numbers, spotlight, .srt, chapters |
-   | `course` | 1–3 min | yes | none | spotlight, .srt, chapters |
-   | `docs` | one GIF per step | none | none | step numbers, spotlight, GIFs |
+   | `pitch` | where it's shown and its one message: a landing-page loop or social clip is a handful of shots; a launch video can tell a longer story | optional | upbeat | captions, intro, frame |
+   | `tutorial` | every step of the workflow, each explained, plus a second example; as long as that takes | yes | soft | step numbers, spotlight, camera follows, part cards, recap, .srt, chapters |
+   | `course` | the concepts to teach: each idea, shown in the app, checked with a question | yes | none | spotlight, camera follows, concept and question cards, recap, .srt, chapters |
+   | `docs` | one clip per step, each just long enough to see its result | none | none | step numbers, spotlight, cropped GIFs + PNGs, README.md article |
 
    Captions match the site's language. `kokoro` (free, local) speaks English
    only; for other languages, use ElevenLabs.
@@ -82,9 +84,14 @@ everything.
    - Tell the user a browser window will open and that they should log in
      there, preferably with a demo account (the video shows whatever is on
      screen).
-   - Call `login` with a URL behind the login. It saves the session to
-     `videos/<site>-login.json` and adds it to `.gitignore`. If it returns
-     "still waiting", call it again.
+   - Call `login` with a URL behind the login. It opens a normal Chrome
+     window and returns at once. Tell the user to log in there and, once the
+     app shows them logged in, to leave the window open and reply "done".
+     Nothing watches the window meanwhile (Google sign-in breaks if a script
+     probes it), so wait for their reply.
+   - Then call `login` again with the same URL and `done: true`. It saves the
+     session to `videos/<site>-login.json`, adds it to `.gitignore` and closes
+     the window. (CLI: `storyshot login <url>`, then press Enter.)
    - Pass that file as `storage_state` to `inspect_page` and `init_storyboard`,
      and add `storageState: <site>-login.json` to the storyboard.
    - Never ask for, store or type a password, and never write login steps.
@@ -116,12 +123,72 @@ everything.
 
 ## 3. Write the storyboard
 
-Rules of thumb from real renders:
+### Tutorials and lessons are not ads
+
+A promo shows as much as possible, fast. A tutorial does the opposite: the
+viewer has to be able to **do it themselves** afterwards, often in a technical
+or scientific tool they have never seen. Storyshot paces `tutorial` and
+`course` slowly by default (`pace: slow`: slower cursor and typing, a beat
+after every click, a hold after every narration line, slower voice, real
+progress shown for waits) and the camera follows the action (`follow`), so
+small controls are readable. Your job is the structure:
+
+- **Start with the goal**: an `intro` with `bullets` saying what the viewer
+  will be able to do ("Run a BLAST search", "Read the hits table", "Judge a
+  match by E-value"), and what they need beforehand.
+- **Split the workflow into parts**, each opened by a `card`
+  (`card: { kicker: Part 2, title: Read the results }` on its first step).
+  Cards become the YouTube chapters.
+- **One action per step.** Each click, field or choice is its own step with
+  its own `say:` explaining **what** it does and **why this value**. Never
+  "fill in the form and submit" in one line. `check` warns when a tutorial
+  step does more than two things.
+- **Show, then explain the result.** After an action that produces output
+  (a results table, a number, a plot, a status), add a step that only looks:
+  `mark` the value or row you're talking about (`mark: "E value"`,
+  `mark: { css: "tbody tr:nth-child(1)" }`), and say what it means and how to
+  judge it ("an E-value this small means the match is not by chance").
+- **Label the controls that matter.** `note: { target: …, text: "FASTA or accession" }`
+  puts a short callout with an arrow next to a field, button or column. Use it for
+  the one thing a newcomer would get wrong, not for everything.
+- **Dropdowns:** `select: { target: …, option: "…" }` (inspect lists the
+  options). Say why this option.
+- **Then a different example.** Run the workflow again with a second input
+  that behaves differently (another sequence, sample, parameter), and point
+  out what changed and why. Comparison is what makes the concept stick.
+  A short `card` ("Now a second example") separates it.
+- **Lessons (`course`) explain the why.** Use concept cards for ideas that
+  aren't on screen (`card: { kicker: Concept, title: …, bullets: […], image:
+  diagram.svg }`), and question cards before a reveal (`card: { kicker:
+  Question, title: "Which hit is the real homolog?", think: 3 }`, then the
+  next step marks the answer).
+- **Docs GIFs (`docs`)** become a help-center article: each step's clip is
+  cropped to what it touches and holds the result before looping; a PNG of
+  each result and `<out>-steps/README.md` are written too. Give every step a
+  short `caption` (the heading) and a `doc:` line (the article text), and
+  `note` the field the reader must not miss.
+- **End with a recap**: `end_card` with `bullets` listing the steps or rules
+  to remember, and a `say` that repeats them.
+- **Narrating real results.** You can't know the numbers (scores, counts,
+  E-values) before the app produces them. Write the result steps with
+  general narration, render once, read the actual values from the preview
+  frames, then rewrite those `say:`/`note`/caption lines with the real
+  numbers and run `compose` only (no re-recording, no new jobs).
+- **Waiting is part of the lesson.** Long computations are still compressed,
+  but say what is happening ("BLAST is now comparing your sequence against
+  the database; this usually takes under a minute").
+- Length follows the content. Don't cut explanation to hit a length, and
+  don't pad: if a part is long, split it into more parts rather than
+  speeding it up.
+
+Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
-  - `pitch`: 1.5–3 s per step (`duration:`). A 15 s video is 5–7 visible
-    steps plus a 1–1.5 s `end_card`. Typical shape: hero → 2–4 steps of the
-    core flow ending on a visible result → pricing or CTA → end card.
+  - `pitch`: 1.5–3 s per step (`duration:`), so the viewer gets one beat per
+    shot; the number of shots comes from the story, plus a 1–1.5 s `end_card`. Typical shape: `intro` → hero → 2–4
+    steps of the core flow ending on a visible result → pricing or CTA → end
+    card. Promos sit in a browser window on a backdrop (`frame: false` turns
+    that off).
   - Other purposes: leave out `duration`. `auto` times each step to its
     narration and plays motion in real time.
 - **Captions ≤ 7 words.** `**bold**` the payoff ("Every text box is
@@ -143,6 +210,14 @@ Rules of thumb from real renders:
   and `press: "^"` send single keys. In `tutorial`/`course`, the spotlight
   highlights each click target automatically; add `highlight: true` to a
   `move` to point at something without clicking it.
+- **Point at what the narration names.** `mark: "the exact phrase"` sweeps a
+  highlighter over words on the page (or `mark: <target>` boxes a table row,
+  card or code line) while the voice says them. On text-heavy pages a mark
+  plus a zoom tells the viewer where to look.
+- **Static pages (a landing page, docs, a README) have nothing to click.**
+  Don't make a slideshow of scrolls: open with an `intro` (the promise),
+  `mark` the claims as they are spoken, zoom on 2–3 of them, and end on a
+  command or URL. If the product has a real flow, show that instead.
 - **Cut boring navigation** with a `hidden: true` step (e.g. `goto: /pricing`).
 - **Clean the frame** in `setup`: dismiss cookie banners, announcement bars and
   chat widgets. `dismiss` is a no-op when the element isn't there.
@@ -163,6 +238,9 @@ Rules of thumb from real renders:
   `at (x, y)`.
 - Never put real credentials in a storyboard. For logged-in apps, use
   `storageState` (see step 1).
+- Internal sites: `http://` URLs just work. If an `https://` internal site
+  fails with an untrusted certificate, add `ignoreHTTPSErrors: true` (inspect/init:
+  `ignore_https_errors`). Never turn it on for public sites.
 
 Run `check_storyboard` after every edit, and fix every ✖ before rendering. It
 checks structure, typos and leftover `TODO`s, but not whether targets exist on

package/src/auth.mjs

@@ -1,7 +1,8 @@
 // Logged-in apps: detect login walls, and `storyshot login` — the user logs in once in a real
 // browser window and the session (cookies, localStorage, IndexedDB) is saved for recording.
 import { chromium } from 'playwright';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
+import os from 'node:os';
 import fs from 'node:fs';
 import path from 'node:path';
 import { VIDEO_DIR, siteOf } from './config.mjs';
@@ -41,44 +42,121 @@ export function gitIgnored(file) {
 function ignore(file) {
   if (gitIgnored(file) === true) return null;
   let root = process.cwd();
-  try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: path.dirname(path.resolve(file)) }).toString().trim(); } catch {}
+  try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: path.dirname(path.resolve(file)), stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch {}
   const gi = path.join(root, '.gitignore');
   const rel = path.relative(root, path.resolve(file)).split(path.sep).join('/');
+  if (rel.startsWith('../') || path.isAbsolute(rel)) return null; // outside the project: nothing to ignore
   const cur = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
   if (cur.split('\n').includes(rel)) return null;
   fs.writeFileSync(gi, `${cur}${cur && !cur.endsWith('\n') ? '\n' : ''}# Storyshot login session (contains your session cookies — never commit)\n${rel}\n`);
   return gi;
 }
 
-// Open a visible browser at `url`; save the session when the user has logged in (a login wall
-// appeared and then went away) or closes the window. Resolves with the saved file.
-export async function login(url, { file = authFileFor(url), viewport = { width: 1600, height: 900 }, timeoutMs = 10 * 60_000, log = console.log } = {}) {
-  let browser;
-  try { browser = await chromium.launch({ headless: false }); } catch (e) {
-    throw new Error(`could not open a browser window (${e.message.split('\n')[0]}). Log in on a machine with a screen ` +
-      `(storyshot login ${url} --save ${file}) and copy the file here.`);
+// --- login ------------------------------------------------------------------------------------
+// The user logs in in a plain Chrome window that NOTHING is attached to while they do it: Google
+// (and other SSO providers) refuse automated browsers, polling the page from a script makes
+// Google's sign-in bounce between the app and accounts.google.com, and even an open DevTools port
+// gets "This browser or app may not be secure". So Chrome runs with only a temporary profile; when
+// the user is done we quit it and read the session back from that profile.
+
+function chromeExecutable() {
+  const home = os.homedir();
+  const candidates = process.platform === 'darwin'
+    ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', path.join(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')]
+    : process.platform === 'win32'
+      ? [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean).map((d) => path.join(d, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+      : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+  return candidates.find((c) => fs.existsSync(c)) ?? chromium.executablePath();
+}
+
+// Opens the window and returns at once. Pass the result to finishLogin() when the user is done.
+export function openLoginWindow(url, { viewport = { width: 1600, height: 900 }, headless = false } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'storyshot-login-'));
+  // "Continue where you left off" also keeps session cookies when the user closes the window.
+  fs.mkdirSync(path.join(dir, 'Default'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'Default', 'Preferences'), JSON.stringify({ session: { restore_on_startup: 1 } }));
+  const exe = chromeExecutable();
+  const args = [`--user-data-dir=${dir}`, '--no-first-run', '--no-default-browser-check',
+    `--window-size=${viewport.width},${viewport.height}`, ...(headless ? ['--headless=new'] : []), url];
+  let proc;
+  try { proc = spawn(exe, args, { stdio: 'ignore' }); } catch (e) {
+    throw new Error(`could not open a browser window (${e.message}). Log in on a machine with a screen (storyshot login ${url}) and copy the file here.`);
   }
-  const context = await browser.newContext({ viewport });
-  const page = await context.newPage();
-  await page.goto(url, { waitUntil: 'domcontentloaded' }).catch(() => {});
-  log(`A browser window is open at ${url}. Log in there (2FA and "Sign in with Google" work).`);
-  log('The session is saved automatically once you are logged in — or close the window when done.');
-  let state = null, sawWall = false, clearFor = 0, done = 'timeout';
-  const end = Date.now() + timeoutMs;
-  while (Date.now() < end) {
-    if (!browser.isConnected() || page.isClosed()) { done = 'closed'; break; }
-    try {
-      state = await context.storageState({ indexedDB: true });
-      const d = await detectLogin(page);
-      if (d.wall) { sawWall = true; clearFor = 0; } else if (sawWall && ++clearFor >= 3) { done = 'logged in'; break; }
-    } catch {}
+  const session = { url, dir, exe, proc, exited: false };
+  proc.on('exit', () => { session.exited = true; });
+  proc.on('error', () => { session.exited = true; });
+  return session;
+}
+
+// Quit the window (if the user hasn't), read the session back from its profile, save it and delete
+// the temporary profile.
+export async function finishLogin(session, { file = authFileFor(session.url), log = console.log } = {}) {
+  const { url, dir, exe, proc } = session;
+  const how = session.exited ? 'window closed' : 'logged in';
+  let state;
+  try {
+    if (!session.exited) {
+      // SIGTERM makes Chrome shut down cleanly and flush cookies; force it if it hangs
+      proc.kill('SIGTERM');
+      const t = setTimeout(() => proc.kill('SIGKILL'), 10_000);
+      await new Promise((r) => (session.exited ? r() : proc.once('exit', r)));
+      clearTimeout(t);
+    }
+    // --restore-last-session reopens the user's tabs, which brings back their sessionStorage (some
+    // apps, e.g. Microsoft MSAL, keep the login token there; storageState() doesn't capture it)
+    const context = await chromium.launchPersistentContext(dir, { executablePath: exe, headless: true, ignoreHTTPSErrors: true, args: ['--restore-last-session'] });
     await new Promise((r) => setTimeout(r, 1000));
+    const sessionStorage = {};
+    for (const p of context.pages()) {
+      if (!/^https?:/.test(p.url())) continue;
+      await p.waitForLoadState('load', { timeout: 15_000 }).catch(() => {});
+      const items = await p.evaluate(() => Object.entries(window.sessionStorage)).catch(() => []);
+      if (items.length) Object.assign(sessionStorage[new URL(p.url()).origin] ??= {}, Object.fromEntries(items));
+    }
+    // load the app once in a fresh tab, so its localStorage / IndexedDB are part of the snapshot
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: 'load', timeout: 30_000 }).catch(() => {});
+    state = await context.storageState({ indexedDB: true });
+    const extra = Object.entries(sessionStorage).map(([origin, items]) => ({ origin, items: Object.entries(items).map(([name, value]) => ({ name, value })) }));
+    if (extra.length) state.sessionStorage = extra;
+    await context.close().catch(() => {});
+  } finally {
+    if (!session.exited) proc.kill('SIGKILL');
+    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
   }
-  await browser.close().catch(() => {});
-  if (!state) throw new Error('the browser was closed before anything could be saved — run login again');
-  if (done === 'timeout') log('warning: timed out waiting for the login; saving the session as it is');
+  const host = new URL(url).hostname.replace(/^www\./, '');
+  const siteCookies = state.cookies.filter((c) => host.endsWith(c.domain.replace(/^\./, '')) || c.domain.replace(/^\./, '').endsWith(host)).length;
   fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(state, null, 1));
   const gi = ignore(file);
-  return { file: path.resolve(file), how: done, gitignore: gi, cookies: state.cookies.length, sawWall };
+  return { file: path.resolve(file), how, gitignore: gi, cookies: state.cookies.length, siteCookies, sessionStorage: state.sessionStorage?.length ?? 0 };
+}
+
+// A browser context with a saved login: storageState plus the sessionStorage that login() saved
+// alongside it (Playwright has no sessionStorage in storageState, so it is restored by a script).
+export async function sessionContext(browser, { storageState, ...options } = {}) {
+  let state = storageState;
+  if (typeof state === 'string') state = JSON.parse(fs.readFileSync(state, 'utf8'));
+  const { sessionStorage, ...rest } = state ?? {};
+  const context = await browser.newContext({ ...options, storageState: state ? rest : undefined });
+  if (sessionStorage?.length) {
+    await context.addInitScript((saved) => {
+      const s = saved.find((o) => o.origin === location.origin);
+      if (s) for (const { name, value } of s.items) if (window.sessionStorage.getItem(name) === null) window.sessionStorage.setItem(name, value);
+    }, sessionStorage);
+  }
+  return context;
+}
+
+// CLI: open the window, wait for Enter (or the window closing), then save.
+export async function login(url, { file = authFileFor(url), viewport, log = console.log } = {}) {
+  const session = openLoginWindow(url, { viewport });
+  log(`A Chrome window is open at ${url}. Log in there (2FA and "Sign in with Google" work).`);
+  log('When you see the app logged in, come back here and press Enter (or just close the window).');
+  await new Promise((resolve) => {
+    const done = () => { process.stdin.pause(); resolve(); };
+    process.stdin.resume(); process.stdin.once('data', done);
+    session.proc.once('exit', done);
+  });
+  return finishLogin(session, { file, log });
 }

package/src/build.mjs

@@ -3,15 +3,16 @@ import { record } from './record.mjs';
 import { compose } from './compose.mjs';
 import { soundtrack } from './audio.mjs';
 import { measureVoice } from './voice.mjs';
-import { writeOutputs } from './outputs.mjs';
+import { writeOutputs, burnSubtitles } from './outputs.mjs';
 
 export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const t0 = Date.now();
   if (mode !== 'compose') await record(cfg, { log });
   if (mode === 'record') return { warnings: [] };
   const voiceLens = await measureVoice(cfg, { log });
-  const { silent, events, preview, warnings, captions, segs } = await compose(cfg, { log, voiceLens });
+  const { silent, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
   const audio = await soundtrack(cfg, events, silent, { log });
-  const extras = await writeOutputs(cfg, { captions, segs, narration: audio.narration, total: events.total }, { log });
+  if (cfg.subtitles === 'burn') burnSubtitles(cfg, audio.narration ?? [], { log });
+  const extras = await writeOutputs(cfg, { captions, cards, segs, narration: audio.narration, total: events.total }, { log });
   return { out: audio.out, extras, preview, warnings: [...warnings, ...audio.warnings], duration: events.total, seconds: Math.round((Date.now() - t0) / 1000) };
 }