demowalk 0.0.0-stage → 1.0.0

package/CLAUDE.md

@@ -0,0 +1,67 @@
+# Authoring journeys with Claude
+
+This file is the instruction set for any Claude session asked to create or
+edit a walkthrough video in a host repo. The human gives only a **start
+point and an end point** ("start from login, end at partner listing") —
+everything else below is YOUR job, not theirs.
+
+## The contract
+
+1. **Read `docs/style-rules.md` in this package first** — the 19 visual
+   style rules bind every journey. Do not re-learn them from review rounds;
+   start compliant.
+2. **The human never lists what to blur.** The engine blurs all dynamic data
+   universally; you add only generic patterns (label→value pairs on detail
+   pages, checkbox-name siblings, selection-card text). If they want
+   something readable, they'll say so → use `keepVisible` (one value) or
+   `noUniversalRedact` (whole frame, rare).
+3. **Journeys create nothing** (rule 18): fill real forms, ring the final
+   create/submit button, narrate the completion — never click it. Show the
+   result on an existing record with everything blurred.
+
+## How to auto-write a journey from "start X, end Y"
+
+1. **Mine the host repo — you have full access:**
+   - `docs/<module>.md` — each module's doc explains what every screen,
+     field and button actually does. This is your narration source of truth.
+   - `docs/user-guide/guide.config.json` + `mockups.mjs` — the sections,
+     step order and per-screen elements the team already documents for
+     users. A journey should cover the same ground in the same order.
+   - The screen's source (`src/screen/<Module>/`) — for exact field labels,
+     placeholders (your selectors), conditional sections, and validations.
+2. **Cover EVERYTHING on the path.** Walk the real screen top-to-bottom and
+   give every field/section its moment — name, then subdomain, then type,
+   then each conditional section as it appears. Missing a field the screen
+   shows is a review bounce; the human should never have to say "you skipped
+   X".
+3. **Detect the product's own tour/onboarding.** Search the host for
+   ProductTour / onboarding flags (e.g. `has_completed_onboarding`). Where
+   the product draws its own tour, trigger it (patch the flag in the demo
+   browser's API response — never in the app) and use `protectOnly` frames:
+   the product's backdrop is the only dim in the whole video (rule 4).
+4. **Narration voice:** present tense, "you/your", one or two sentences per
+   frame, say what + why, end transition steps with the click to make
+   ("Click Next", "click Continue"). Opening frame = welcome + what the
+   video covers; closing frame = one-line recap + "thanks for watching".
+5. **Selectors:** accessible (labels, placeholders, roles) — never
+   page-wide text or nth() guesses (rule 6); scope through section titles
+   and siblings. Measurement flakiness is already engine-handled.
+6. **Emails/data:** all typed values come from the journey's `data` object —
+   fictional names, plus-tagged owned mailboxes if an address could ever
+   receive mail (rule 19), fictional addresses/phones (555-01xx).
+
+## Workflow with the human
+
+1. They give start + end (+ anything special to keep visible).
+2. You write `demo/journeys/<id>.ts` + run once; the storyboard
+   `demo/journeys/<id>.md` regenerates automatically — share it for review
+   of the narration before they even watch the video.
+3. They watch, send screenshots; you fix. Engine-level issues get fixed in
+   THIS package (every portal inherits); journey issues in the journey file.
+
+## Debugging a failed run
+
+The run stops loudly with the step id, the page URL, any on-screen toast
+text and a debug frame path. That is the diagnosis — read it before touching
+code. A "spotlight target not found" after a product change is the tool
+working as designed: update that one step and re-run.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 360 Solutions
+
+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,214 @@
-# Temporary Holding Version
+# demowalk
 
-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.
+**Self-regenerating product demo videos.** One command rebuilds a narrated
+walkthrough **from your live app**: Playwright drives the real UI, every
+frame is styled in your own branding (spotlight rings, captions, and
+skeleton-style redaction of all dynamic data), narration is voiced, and
+ffmpeg stitches the final MP4.
+
+When the product changes, you re-run the command — nothing is recorded by
+hand, so nothing can silently go stale.
+
+```bash
+npm run demo:video              # → demo/out/example/example.mp4
+```
+
+- **Always current** — a UI change means a re-run, not a re-shoot.
+- **Privacy-safe by construction** — every filled input, table cell and
+  record value is redacted on every frame, by the engine. Raw captures are
+  deleted after every render.
+- **Your branding, not ours** — ring, chip and redaction colors come from
+  each project's config; the engine ships neutral fallbacks only.
+- **Fails loudly, never lies** — a missing element stops the run with the
+  step name, URL and a debug frame. A wrong video cannot be produced silently.
+
+## How it works
+
+Your repo keeps two inputs; demowalk turns them into a video in four stages:
+
+```
+   demo/journeys/<id>.ts                demo/demo.config.ts
+   steps + narration text               baseUrl · auth hook · brand colors
+            │                                      │
+            └──────────────────┬───────────────────┘
+                               ▼
+                    ┌─────────────────────┐
+  your app      ◄── │  1  CAPTURE          │  signs in with your e2e fixture,
+  (localhost)       │     Playwright       │  walks the steps, shoots 2× retina
+                    └──────────┬──────────┘  frames + element geometry
+                               ▼
+                    ┌─────────────────────┐
+                    │  2  OVERLAY          │  redacts every dynamic value into
+                    │     sharp            │  skeleton bars; draws rings, chips
+                    └──────────┬──────────┘  and captions in YOUR colors
+                               ▼
+                    ┌─────────────────────┐
+                    │  3  NARRATE          │  voices each step's narration
+                    │     say → ffmpeg     │  into one audio clip
+                    └──────────┬──────────┘
+                               ▼
+                    ┌─────────────────────┐
+                    │  4  STITCH           │  per-step segments pinned to the
+                    │     ffmpeg           │  audio length → one seamless MP4
+                    └──────────┬──────────┘
+                               ▼
+                   demo/out/<id>/<id>.mp4
+                   + demo/journeys/<id>.md   (storyboard, regenerated each run)
+```
+
+The engine, starter templates and setup CLI live in this package; journeys
+(one `.ts` file per video) live in your repo.
+
+## Requirements
+
+| Required | Why |
+|---|---|
+| Node 18+ and `tsx` | runs the pipeline |
+| `@playwright/test` + Chromium | the capture engine (peer dependency) |
+| ffmpeg on the machine | narration conversion + stitching |
+| **macOS** (for now) | narration uses the built-in `say`; download a natural voice once via System Settings → Accessibility → Spoken Content → Manage Voices (e.g. "Tom (Enhanced)") |
+| A sign-in function | the only app-specific code — repos with e2e tests reuse their auth fixture |
+| The app running locally | something to film |
+
+Docs, an e2e suite and test-ids are **not** required — they only make
+journeys easier to author or redaction richer when present.
+
+## Quick start
+
+```bash
+# 0. ffmpeg (once per machine — check first: `ffmpeg -version`).
+#    The 2-minute static build beats compiling via brew:
+curl -L "https://evermeet.cx/ffmpeg/getrelease/ffmpeg/zip" -o /tmp/ffmpeg.zip \
+  && unzip -o /tmp/ffmpeg.zip -d /tmp \
+  && sudo mv /tmp/ffmpeg /usr/local/bin/ffmpeg \
+  && sudo xattr -d com.apple.quarantine /usr/local/bin/ffmpeg 2>/dev/null; ffmpeg -version
+
+# 1. in your app's repo:
+npm install --save-dev tsx
+npm install --save-dev demowalk
+#    (straight from GitHub instead: npm i -D demowalk@github:360solutions-dev/demowalk
+#     from a local clone: npm i -D --install-links file:../demowalk
+#     --install-links matters — a symlinked file: install duplicates
+#     Playwright's types and breaks tsc)
+
+# 2. only if the repo doesn't already use Playwright:
+npm install --save-dev @playwright/test && npx playwright install chromium
+
+# 3. let demowalk set itself up (scripts + templates + gitignore, idempotent):
+npx demowalk-init
+
+# 4. review demo/demo.config.ts — init AUTO-WIRES it when the repo has the
+#    common e2e convention (tests/global-setup.ts + tests/fixtures/
+#    auth.fixture.ts), detecting the dev port and theme colors too.
+#    Otherwise wire the marked spots by hand (the env-loading setup import
+#    comes FIRST — the auth fixture reads env when it is imported).
+
+# 5. smoke test — with the app + backend running locally:
+npm run demo:video
+open demo/out/example/example.mp4
+```
+
+Your repo keeps **three small files**:
+
+```
+demo/
+├── demo.config.ts        # THE app-specific file: baseUrl, auth hook, branding
+├── run.ts                # 3-line shim
+└── journeys/<id>.ts      # the videos — one file per video
+```
+
+Day-to-day:
+
+```bash
+npm run demo:video -- --journey=<id>   # build one video
+npm run demo:video -- --from=overlay   # re-style an existing capture (also: tts, stitch)
+npm run demo:video -- --keep-frames    # keep raw frames while iterating on styling
+npm run demo:update                    # pull a newer engine into this repo
+```
+
+## Creating a journey
+
+Journeys are **authored, not configured** — usually by an AI coding
+assistant: give it the **start and end point** ("start from login, end at the
+created record") and it writes `demo/journeys/<id>.ts` following
+[`CLAUDE.md`](./CLAUDE.md) — mining your docs for narration, covering every
+field on the path, and applying the
+[visual style rules](./docs/style-rules.md) that bind every journey.
+
+Every run regenerates a storyboard (`demo/journeys/<id>.md`) with each step's
+narration as text — review the script without watching the video.
+
+## Configuration
+
+demowalk has **no .env of its own**: real configuration lives in
+`demo/demo.config.ts` (typed, committed). Env vars are per-run overrides only:
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `BASE_URL` | Override the base URL for one run | from config |
+| `DEMO_VOICE` | Override the macOS `say` voice | from config |
+| `DEMO_VOICE_RATE` | Words per minute | from config / 165 |
+| `DEMO_ALLOW_REMOTE` | `1` permits a non-localhost base URL (explicit opt-in) | off |
+
+**Auth env belongs to the host, not to demowalk** — the pipeline signs in
+through your repo's own e2e fixture, so whatever your e2e suite needs is all
+it needs. If `npm run e2e` works on a machine, `npm run demo:video` has
+everything besides ffmpeg and the running local app.
+
+Branding is per project — each config passes its own theme's values:
+
+```ts
+import type { DemoConfig } from "demowalk";
+import globalSetup from "../tests/global-setup";
+import { createAuthContext } from "../tests/fixtures/auth.fixture";
+
+const config: DemoConfig = {
+  baseUrl: process.env.BASE_URL ?? "http://localhost:3000",
+  prepare: () => globalSetup(),   // host e2e setup: env + preflight
+  createAuthContext,              // the host's own signed-in context
+  ringColor: "#2F6FEB",           // spotlight ring   (theme primary)
+  chipColor: "#1F2937",           // chips + caption  (theme secondary)
+  redactionTint: "#E2E5E9",       // skeleton grey    (theme placeholder tint)
+  voice: "Tom (Enhanced)",
+};
+export default config;
+```
+
+## Privacy posture
+
+Designed for products whose screens hold sensitive data (including
+regulated/health data):
+
+- **Localhost-only by default** — `DEMO_ALLOW_REMOTE=1` is an explicit opt-in.
+- **Journeys create nothing and send nothing** — the final create/submit is
+  ringed and narrated, never clicked.
+- **All dynamic data is redacted by the engine** on every frame — no step
+  opts in, no frame can be forgotten; raw captures never persist.
+- Output folders are gitignored; distribute videos only through your own
+  storage behind your product's auth.
+
+The full frame-styling contract lives in
+[docs/style-rules.md](./docs/style-rules.md).
+
+## Updating
+
+In a host repo: `npm run demo:update` (set up by `demowalk-init`). Journeys
+and config stay untouched; only the engine updates.
+
+## Contributing
+
+PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, code
+layout, style and the PR workflow.
+
+```bash
+git clone https://github.com/360solutions-dev/demowalk.git
+cd demowalk && npm install && npm run typecheck   # no build step
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+---
+
+*Made for teams tired of re-recording demo videos every sprint.*

package/docs/style-rules.md

@@ -0,0 +1,61 @@
+# Visual style rules
+
+These rules bind **every** journey. They were set by frame-by-frame product
+review; journey authors — human or AI (see [`CLAUDE.md`](../CLAUDE.md)) —
+follow all of them. A behavior change that affects frames must update these
+rules in the same PR.
+
+1. **Rings + label chips are for MAIN CONCEPTS only**: buttons the viewer
+   must click, navigation items, wizard steppers, dialogs, a module's key
+   introduction. **Never on a plain section heading** — captions narrate those.
+2. **Form fields get NO ring and NO chip** — the app's own focus border is
+   the highlight. Fill fields ONE PER FRAME, narrated one at a time.
+3. **Selection cards get NO ring** — the app's selected-state border is the
+   highlight.
+4. **No dim overlay ever** — the only dimming is the product's own tour
+   backdrop (`protectOnly` frames show the product's callout alone).
+5. **Redact values only, skeleton-soft**: row contents not tables, numbers
+   not stat cards, typed text inside fields not whole fields, card text not
+   cards, nav icon+label not the whole sidebar. Never a whole panel/screen.
+6. **Ring geometry**: wrap the WHOLE element group via scoped
+   ancestors/siblings. **Never union with page-wide locators** (a page-wide
+   `input.last()` once grabbed a below-the-fold checkbox; a page-wide text
+   match once ringed a sidebar nav item instead of the section).
+7. **The current screen's own nav items stay readable** (URL-driven); a
+   navigation step `protect`s its subject.
+8. **After an in-app tour finishes, scroll back to the top.**
+9. **Every typed form value is redacted** (engine-enforced); `keepVisible` is
+   the explicit opt-out for the value a step itself teaches.
+10. **No frame ever shows a toast** (engine-enforced).
+11. **A "record created" listing frame** rings the WHOLE row with ALL values
+    redacted — the story is "your record appears here", never the data. The
+    quick-actions (⋮) menu gets its own `protect`ed step.
+12. **Detail/review screens redact EVERY printed value** (generic
+    label→value patterns; names in breadcrumbs and headings included) —
+    labels and section titles stay readable.
+13. **App UI text is never redacted** — field labels, checkbox labels, button
+    text, column headers. Redaction is for DATA only.
+14. **The opening frame of a journey is clean** — welcome narration over the
+    untouched screen; the first highlight arrives with the first action.
+15. **A step without a spotlight scrolls explicitly** to what its narration
+    describes.
+16. **Raw frames are deleted after every successful render**
+    (engine-enforced; `--keep-frames` only while styling).
+17. **Dynamic data is redacted UNIVERSALLY, in the engine** — step `redact`s
+    only ADD patterns. If a value shows, fix the engine or a generic pattern,
+    never a one-off.
+18. **Journeys create NOTHING**: never click the final create/submit — with
+    all rows redacted, a ringed existing record tells the identical story. No
+    records, no emails, no cleanup, no orphan users.
+19. **Any email a flow WOULD send** must target a plus-tagged mailbox the
+    team owns — never a fictional-but-real-looking domain.
+
+## Step-level escape hatches
+
+- `redact` — ADD generic redaction patterns for one step.
+- `keepVisible` — "don't redact this one thing — it's the value the step
+  teaches."
+- `noUniversalRedact` — whole frame clean; rare and deliberate.
+- `protect` / `protectOnly` — re-paste an element sharp over the redactions
+  (`protectOnly`: and show nothing else highlighted). See `src/types.ts` for
+  the full API.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "demowalk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Self-regenerating product demo videos: Playwright walks your live app, every frame is branded and redacted, narration is voiced, ffmpeg stitches the MP4. One command, always up to date.",
+  "keywords": [
+    "demo",
+    "video",
+    "walkthrough",
+    "playwright",
+    "screen-recording",
+    "product-tour",
+    "documentation",
+    "tts",
+    "ffmpeg"
+  ],
+  "homepage": "https://github.com/360solutions-dev/demowalk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/360solutions-dev/demowalk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/360solutions-dev/demowalk/issues"
+  },
+  "license": "MIT",
+  "author": "360 Solutions",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "templates",
+    "scripts",
+    "docs",
+    "README.md",
+    "CLAUDE.md"
+  ],
+  "bin": {
+    "demowalk-init": "./scripts/init.mjs"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "dependencies": {
+    "sharp": "^0.35.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/scripts/init.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * One-command host setup: `npx demowalk-init` (run from the host repo root
+ * after installing the kit). Idempotent — safe to run again any time.
+ *
+ *   1. adds the demo:video / demo:update scripts to the host package.json
+ *   2. copies the starter templates to demo/ (only if demo/ doesn't exist)
+ *   3. adds demo/out/ to .gitignore
+ *   4. prints exactly what is left to do by hand (wire auth + branding)
+ *
+ * Exists because a manual install kept missing step 3 ("Missing script:
+ * demo:video") — the kit now does every mechanical step itself.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const kitRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const hostRoot = process.cwd();
+
+const pkgPath = path.join(hostRoot, "package.json");
+if (!fs.existsSync(pkgPath)) {
+  console.error("[demowalk-init] run this from the host repo root (no package.json here).");
+  process.exit(1);
+}
+
+// 1. scripts
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+pkg.scripts = pkg.scripts ?? {};
+pkg.scripts["demo:video"] = "tsx demo/run.ts";
+// demo:update matches HOW this host installed demowalk: a local folder install
+// keeps the forced --install-links copy; a registry/GitHub install just
+// reinstalls the spec. (The rm -rf is what defeats npm's "up to date" cache.)
+const spec =
+  pkg.devDependencies?.demowalk ?? pkg.dependencies?.demowalk ?? "file:../demowalk";
+pkg.scripts["demo:update"] = spec.startsWith("file:")
+  ? `rm -rf node_modules/demowalk && npm install --save-dev --install-links ${spec}`
+  : "rm -rf node_modules/demowalk && npm install";
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+console.log("✓ scripts: demo:video, demo:update");
+
+if (!pkg.devDependencies?.tsx && !pkg.dependencies?.tsx) {
+  console.log("⚠ tsx is not installed — run: npm install --save-dev tsx");
+}
+
+// 1.5 AUTO-WIRE demo.config.ts when the host follows the common e2e
+// convention (tests/global-setup.ts default export + tests/fixtures/
+// auth.fixture.ts exporting createAuthContext). Detection also reads the
+// dev port from the dev script and the theme's primary/secondary colours —
+// so on a conventional repo, init produces a config that RUNS, with zero
+// manual wiring. Anything undetectable keeps a safe default + a TODO.
+function detectConfig() {
+  const read = (rel) => {
+    try {
+      return fs.readFileSync(path.join(hostRoot, rel), "utf-8");
+    } catch {
+      return null;
+    }
+  };
+  const setup = read("tests/global-setup.ts");
+  const fixture = read("tests/fixtures/auth.fixture.ts");
+  if (!setup || !/export default/.test(setup)) return null;
+  if (!fixture || !/export (async )?function createAuthContext/.test(fixture)) return null;
+
+  const port = /-p\s+(\d+)/.exec(pkg.scripts?.dev ?? "")?.[1] ?? "3000";
+  const theme = read("src/theme/index.ts") ?? "";
+  const primary = /primary:\s*['"](#[0-9a-fA-F]{6})/.exec(theme)?.[1];
+  const secondary = /secondary:\s*['"](#[0-9a-fA-F]{6})/.exec(theme)?.[1];
+
+  return `import type { DemoConfig } from "demowalk";
+
+// ⚠️ Import ORDER matters: the global setup loads the e2e env on import,
+// and the auth fixture reads that env at ITS import — setup must come first.
+import globalSetup from "../tests/global-setup";
+import { createAuthContext } from "../tests/fixtures/auth.fixture";
+
+/**
+ * AUTO-WIRED by demowalk-init from this repo's own conventions
+ * (e2e fixture, dev port, theme colours). Review the values once; adjust
+ * anything the detection got wrong.
+ */
+const config: DemoConfig = {
+  baseUrl: process.env.BASE_URL ?? "http://localhost:${port}",
+  prepare: () => globalSetup(),
+  createAuthContext,
+  ringColor: "${primary ?? "#2F6FEB"}",${primary ? " // from src/theme primary" : " // TODO: your theme primary"}
+  chipColor: "${secondary ?? "#1F2937"}",${secondary ? " // from src/theme secondary" : " // TODO: your theme secondary"}
+  redactionTint: "#E2E5E9", // skeleton grey — adjust to your theme's tint
+  voice: "Tom (Enhanced)",
+};
+
+export default config;
+`;
+}
+
+let autoWired = false;
+const configPath = path.join(hostRoot, "demo", "demo.config.ts");
+const existingConfig = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf-8") : null;
+const isUnwiredPlaceholder = existingConfig?.includes("wire your portal's e2e auth fixture here");
+if (!existingConfig || isUnwiredPlaceholder) {
+  const wired = detectConfig();
+  if (wired) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, wired);
+    autoWired = true;
+    console.log("✓ demo/demo.config.ts AUTO-WIRED from this repo's e2e fixture, dev port and theme");
+  } else if (isUnwiredPlaceholder) {
+    console.log("⚠ demo/demo.config.ts is still the placeholder and no e2e convention was detected — wire it by hand");
+  }
+}
+// (a config the team already edited is never touched)
+
+// 2. templates → demo/, FILE-level idempotent: each missing file is copied,
+// each existing file is left untouched (a discarded install can leave empty
+// folders behind — "the folder exists" proves nothing about its contents).
+const demoDir = path.join(hostRoot, "demo");
+const templatesDir = path.join(kitRoot, "templates");
+let copied = 0;
+for (const rel of fs.readdirSync(templatesDir, { recursive: true })) {
+  const src = path.join(templatesDir, String(rel));
+  if (fs.statSync(src).isDirectory()) continue;
+  const dest = path.join(demoDir, String(rel));
+  if (fs.existsSync(dest)) continue;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  copied++;
+  console.log(`✓ demo/${rel} created from template`);
+}
+if (copied === 0) console.log("✓ demo/ complete — nothing to copy");
+
+// 3. gitignore
+const giPath = path.join(hostRoot, ".gitignore");
+const gi = fs.existsSync(giPath) ? fs.readFileSync(giPath, "utf-8") : "";
+if (!gi.split("\n").some((l) => l.trim() === "demo/out/")) {
+  fs.writeFileSync(giPath, gi.replace(/\n?$/, "\n") + "demo/out/\n");
+  console.log("✓ .gitignore: demo/out/");
+} else {
+  console.log("✓ .gitignore already covers demo/out/");
+}
+
+// 4. what's left (the genuinely portal-specific part)
+const configStep = autoWired
+  ? `  1. Review demo/demo.config.ts (auto-wired — adjust anything detection
+     got wrong) and make sure the e2e env file it relies on exists with the
+     test user's credentials.`
+  : `  1. Wire demo/demo.config.ts — your auth fixture (env-loading setup
+     import FIRST), your baseUrl, YOUR theme colours.`;
+console.log(`
+Left to do by hand (the portal-specific part):
+${configStep}
+  2. Check ffmpeg:            ffmpeg -version
+  3. Run the smoke test:      npm run demo:video        (runs the example)
+`);

package/src/assets.ts

@@ -0,0 +1,17 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import sharp from "sharp";
+
+/**
+ * Render an SVG string to a PNG on disk if it doesn't exist yet — for
+ * journey assets like a fictional demo logo, generated rather than committed
+ * (no binaries in repos, and the asset regenerates with everything else).
+ */
+export async function ensureSvgAsset(outPath: string, svg: string): Promise<string> {
+  if (!fs.existsSync(outPath)) {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    await sharp(Buffer.from(svg)).png().toFile(outPath);
+  }
+  return outPath;
+}