@matte97p/demowright 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-22
+
+Initial public release.
+
+### Added
+- `demowright run <config.js>` — record a demo from a config, with captions, a
+  synthetic cursor, auto-zoom, highlights, and an end card baked into the video.
+- `demowright init` — scaffold a starter `demowright.config.js`.
+- Step types: `caption`, `captionHide`, `goto`, `move`, `click`, `type`, `key`,
+  `highlight`, `highlightHide`, `zoom`, `zoomReset`, `scroll`, `wait`, `endcard`.
+- `auth` block — log in once in a throwaway, non-recorded context; credentials
+  are read from the environment so they never appear in the config or the video.
+- Social crops from a single capture: `landscape`, `square`, `vertical`.
+- Library API: `recordDemo`, `defineDemo`.
+- Bundled ffmpeg via `ffmpeg-static`; no system dependency beyond Chromium.

package/LICENSE

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

@@ -0,0 +1,112 @@
+# demowright
+
+Product demo videos rot the moment you touch the UI. You record a beautiful 40-second walkthrough, ship a redesign two weeks later, and now the video is a lie — but re-recording it by hand is annoying enough that nobody does it.
+
+So I wrote this: a demo video you describe as a **script that lives in your repo**. Playwright drives the browser, and the polish — captions, a smooth synthetic cursor, auto-zoom on what matters, an end card — is painted straight into the recording. No external editor, no SaaS, no "click here to start your trial". When the UI changes, you re-run it in CI and the video is current again.
+
+```bash
+npm install --save-dev @matte97p/demowright
+npx playwright install chromium   # the browser it drives
+npx demowright init               # writes a starter demowright.config.js
+npx demowright run demowright.config.js -o output/demo.mp4
+```
+
+## What a demo looks like
+
+A demo is a plain object: where to start, and an ordered list of steps. This is the bundled example (`examples/local-demo.config.js`):
+
+```js
+import { defineDemo } from 'demowright'
+
+export default defineDemo({
+  name: 'local-demo',
+  url: 'http://localhost:3000',
+  viewport: { width: 1280, height: 720 },
+  theme: { accent: '#e91e63' },
+  formats: ['landscape'],          // add 'square' and 'vertical' for social
+  steps: [
+    { type: 'caption', text: 'Too many items in the sidebar.', duration: 2600 },
+    { type: 'highlight', selector: '.sidebar', duration: 1500 },
+    { type: 'zoom', selector: '.sidebar', scale: 1.2 },
+    { type: 'zoomReset' },
+    { type: 'caption', text: 'Or: just ask.' },
+    { type: 'type', selector: '#q', text: 'How does ChatGPT see me?' },
+    { type: 'click', selector: '#ask' },
+    { type: 'wait', selector: '#result .done' },
+    { type: 'zoom', selector: '.assistant', scale: 1.25 },
+    { type: 'endcard', title: 'My Product', subtitle: 'myproduct.com' },
+  ],
+})
+```
+
+Run it and you get `output/demo.mp4` — captions, cursor, and zooms baked in.
+
+## Steps
+
+| type | fields | what it does |
+|---|---|---|
+| `caption` | `text`, `duration?`, `hold?` | show a caption (bottom center). `hold: true` keeps it until `captionHide` |
+| `captionHide` | — | hide the current caption |
+| `goto` | `url` | navigate mid-demo (overlay re-installs automatically) |
+| `move` | `selector` \| `x`+`y`, `duration?` | glide the synthetic cursor |
+| `click` | `selector`, `duration?` | move the cursor there, pulse, and really click |
+| `type` | `selector`, `text`, `perChar?`, `clear?` | focus and type, character by character |
+| `key` | `key` | press a key (e.g. `"Enter"`) |
+| `highlight` | `selector`, `pad?`, `duration?` | draw a ring around an element |
+| `highlightHide` | — | remove the ring |
+| `zoom` | `selector`, `scale?`, `duration?` | smoothly zoom toward an element |
+| `zoomReset` | `duration?` | zoom back out |
+| `scroll` | `selector` \| `y`, `duration?` | smooth-scroll to an element or offset |
+| `wait` | `duration` \| `selector` | pause for ms, or until an element is visible |
+| `endcard` | `title`, `subtitle?`, `duration?` | full-screen closing card |
+
+Timing is real-time: a `caption` with `duration: 2600` is on screen for 2.6 seconds of video. `wait` with a `selector` is how you sync to your app actually doing something (a request finishing, a result rendering) instead of guessing milliseconds.
+
+## CLI
+
+```
+demowright run <config.js> [options]
+  -o, --out <file>      output path (default: output/<name>.mp4)
+  -f, --format <list>   landscape,square,vertical  (overrides config)
+  -m, --music <file>    background music track
+      --keep-raw        keep the intermediate .webm
+
+demowright init [dir]   write a starter config
+demowright --version
+```
+
+## As a library
+
+```js
+import { recordDemo } from 'demowright'
+
+const { outputs } = await recordDemo(demo, {
+  out: 'output/demo.mp4',
+  formats: ['landscape', 'vertical'],
+  onStep: (i, step) => console.log(i, step.type),
+})
+```
+
+## Social formats
+
+One capture, three crops — so you don't record three times:
+
+- `landscape` — 1280×720, for the site / YouTube / X
+- `square` — 1080×1080, center-cropped, for the LinkedIn / Instagram feed
+- `vertical` — 1080×1920, the landscape centered over a blurred fill, for Reels / Shorts
+
+## How it works
+
+`addInitScript` installs a tiny overlay runtime (`window.__dw`) into the page before its own scripts run, so it survives navigation. The runner drives it over `page.evaluate` while Playwright records the context video. Because the overlay is real DOM and the zoom is a CSS transform on `<body>`, all of it is captured in the same frames — there is no compositing step. The raw `.webm` is then muxed to H.264 MP4 (and any extra crops) with a bundled static ffmpeg.
+
+The overlay attaches itself to `<html>` rather than `<body>`, so the zoom transform never scales the captions or the cursor — they stay crisp while the page zooms underneath them.
+
+## Requirements
+
+- Node ≥ 20
+- Chromium, via `npx playwright install chromium` (headless — runs fine on a server / in CI with no display)
+- ffmpeg is bundled (`ffmpeg-static`); nothing to install on the system
+
+## License
+
+MIT © Matteo Perino

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { pathToFileURL } from 'node:url'
+import path from 'node:path'
+import { recordDemo, estimateDurationMs, normalizeDemo } from '../src/index.js'
+import { scaffold } from '../src/scaffold.js'
+
+const HELP = `demowright — record polished product demo videos from a script
+
+Usage:
+  demowright run <config.js> [options]   capture a demo and render MP4(s)
+  demowright init [dir]                  write a starter demowright.config.js
+  demowright --help | --version
+
+Options for "run":
+  -o, --out <file>      output path (default: output/<name>.mp4)
+  -f, --format <list>   comma list: landscape,square,vertical (default from config)
+  -m, --music <file>    background music track (overrides config)
+      --keep-raw        keep the intermediate .webm and work dir
+`
+
+function fmt(ms) {
+  return (ms / 1000).toFixed(1) + 's'
+}
+
+async function loadConfig(configPath) {
+  const abs = path.resolve(process.cwd(), configPath)
+  const mod = await import(pathToFileURL(abs).href)
+  const demo = mod.default || mod.demo || mod
+  if (!demo || !demo.steps) {
+    throw new Error('config "' + configPath + '" must default-export a demo object with steps')
+  }
+  return demo
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      out: { type: 'string', short: 'o' },
+      format: { type: 'string', short: 'f' },
+      music: { type: 'string', short: 'm' },
+      'keep-raw': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+      version: { type: 'boolean', default: false },
+    },
+  })
+
+  if (values.version) {
+    const { readFile } = await import('node:fs/promises')
+    const pkg = JSON.parse(
+      await readFile(new URL('../package.json', import.meta.url), 'utf8')
+    )
+    console.log(pkg.version)
+    return
+  }
+
+  const command = positionals[0]
+  if (values.help || !command) {
+    console.log(HELP)
+    return
+  }
+
+  if (command === 'init') {
+    const res = await scaffold(positionals[1] || process.cwd())
+    console.log(
+      res.created
+        ? '✓ wrote ' + res.path + '\n  edit it, then: npx demowright run ' + path.basename(res.path)
+        : '• ' + res.path + ' already exists — left untouched'
+    )
+    return
+  }
+
+  if (command === 'run') {
+    const configPath = positionals[1]
+    if (!configPath) throw new Error('usage: demowright run <config.js>')
+    const rawDemo = await loadConfig(configPath)
+
+    const formats = values.format ? values.format.split(',').map((s) => s.trim()).filter(Boolean) : null
+    const est = estimateDurationMs(normalizeDemo(rawDemo))
+    console.log('▶ recording "' + (rawDemo.name || 'demo') + '" (~' + fmt(est) + ')')
+
+    const { outputs } = await recordDemo(rawDemo, {
+      out: values.out,
+      formats,
+      music: values.music,
+      keepRaw: values['keep-raw'],
+      onAuth: () => process.stdout.write('  · logging in…\n'),
+      onStep: (i, step) => process.stdout.write('  · ' + String(i + 1).padStart(2) + ' ' + step.type + '\n'),
+    })
+
+    console.log('✓ done:')
+    for (const o of outputs) console.log('  ' + o.format.padEnd(10) + o.path)
+    return
+  }
+
+  throw new Error('unknown command "' + command + '" — try: demowright --help')
+}
+
+main().catch((err) => {
+  console.error('✗ ' + (err && err.message ? err.message : err))
+  process.exit(1)
+})

package/examples/geosuite-howitworks.config.js

@@ -0,0 +1,127 @@
+import { defineDemo } from '../src/index.js'
+
+// A real-world demowright config: "How GeoSuite works", end to end, on the live
+// app — add a brand (the site is scraped into a brand profile), launch a GEO
+// audit, watch it run, read the result, then ask the Geo copilot. The dead waits
+// — the scrape and the multi-minute audit — are recorded in real time and SPED
+// UP in the final video via the `timelapse` field on those waits.
+//
+// Credentials come from the environment so they never live in the file or appear
+// on screen (see the `auth` block below):
+//
+//   GEOSUITE_URL=https://your-instance.example \
+//   GEOSUITE_EMAIL=you@example.com GEOSUITE_PASSWORD=... \
+//   node bin/cli.js run examples/geosuite-howitworks.config.js -o output/geosuite-howitworks.mp4 --keep-raw
+//
+// `init` suppresses the first-run tour and pre-expands the sidebar groups so the
+// nav is clickable from the first frame.
+
+const BASE = process.env.GEOSUITE_URL || 'http://localhost:3000'
+
+const INIT = `(() => {
+  const get = Storage.prototype.getItem
+  Storage.prototype.getItem = function (k) {
+    if (typeof k === 'string') {
+      if (k.indexOf('gs-workspace-tour:') === 0) return '1'
+      if (k === 'gs-sidebar-expanded-groups') return JSON.stringify(['Analizza', 'Account', 'Analyze'])
+    }
+    return get.call(this, k)
+  }
+})();`
+
+const M = '.gs-admin-modal-shell' // the dialog panel (intercepts clicks)
+
+export default defineDemo({
+  name: 'geosuite-howitworks',
+  url: `${BASE}/app`,
+  viewport: { width: 1920, height: 1080 },
+  theme: { accent: '#ff3b7a' },
+  locale: 'it-IT',
+  formats: ['landscape'],
+  init: INIT,
+
+  auth: {
+    url: `${BASE}/login`,
+    fields: [
+      { selector: 'input[type="email"]', env: 'GEOSUITE_EMAIL' },
+      { selector: 'input[type="password"]', env: 'GEOSUITE_PASSWORD' },
+    ],
+    submit: 'button[type="submit"]',
+    waitUrl: '**/app**',
+  },
+
+  steps: [
+    { type: 'wait', selector: '.gs-workspace-sidebar', timeout: 20000 },
+    { type: 'wait', duration: 800 },
+
+    // --- intro ---
+    { type: 'caption', text: 'GeoSuite: come funziona, dall’inizio.', duration: 2600 },
+    { type: 'highlight', selector: '.gs-admin-hero', pad: 6, duration: 1600 },
+
+    // --- add a brand (onboarding + profile config) ---
+    { type: 'move', selector: '.gs-workspace-sidebar a[href="/app/brand"]', duration: 550 },
+    { type: 'click', selector: '.gs-workspace-sidebar a[href="/app/brand"]' },
+    { type: 'wait', duration: 2000 },
+    { type: 'caption', text: 'Aggiungi un brand: bastano nome e sito.', duration: 2600 },
+    { type: 'move', selector: '.gs-admin-panel-cta.is-accent', duration: 500 },
+    { type: 'click', selector: '.gs-admin-panel-cta.is-accent' }, // open "Aggiungi brand"
+    { type: 'wait', selector: M, timeout: 10000 },
+    { type: 'wait', duration: 700 },
+    { type: 'move', selector: `${M} input[type="text"]`, duration: 400 },
+    { type: 'type', selector: `${M} input[type="text"]`, text: 'Linear', perChar: 70 },
+    { type: 'type', selector: `${M} input[type="url"]`, text: 'https://linear.app', perChar: 48 },
+    { type: 'wait', duration: 500 },
+    { type: 'caption', text: 'GeoSuite legge il sito e costruisce il profilo del brand.', duration: 2600 },
+    { type: 'click', selector: `${M} .gs-admin-panel-cta.is-accent` }, // "Analizza il sito" → scrape
+    // scrape runs ~15-30s; record it and speed it up 8×
+    { type: 'wait', selector: `${M} .gs-starter-profile`, timeout: 90000, timelapse: 8 },
+    { type: 'caption', text: 'Profilo generato: settore, posizionamento, target, personas.', duration: 3200 },
+    { type: 'highlight', selector: `${M} .gs-starter-profile`, pad: 4, duration: 1800 },
+    { type: 'click', selector: `${M} .gs-admin-panel-cta.is-accent` }, // "Crea brand"
+    { type: 'wait', selector: '.gs-table-mini-btn-secondary', timeout: 15000 }, // brand list reloaded (Linear added)
+    { type: 'wait', duration: 1200 },
+
+    // --- launch a real audit ---
+    { type: 'caption', text: 'Ora lancia l’audit di visibilità sulle AI.', duration: 2600 },
+    { type: 'move', selector: '.gs-table-mini-btn-secondary', duration: 550 },
+    { type: 'click', selector: '.gs-table-mini-btn-secondary' }, // "Lancia audit" (newest row = Linear)
+    { type: 'wait', selector: M, timeout: 10000 },
+    { type: 'wait', duration: 800 },
+    { type: 'select', selector: `${M} select`, contains: 'Linear' },
+    { type: 'wait', duration: 700 },
+    { type: 'caption', text: 'L’audit interroga ChatGPT, Gemini e Perplexity sul brand — decine di volte.', hold: true },
+    { type: 'click', selector: `${M} .gs-admin-panel-cta.is-accent` }, // "Nuovo audit" → POST (~20s) → navigate
+
+    // --- the audit runs — speed up the dead waits; fail fast if it never starts ---
+    { type: 'wait', selector: '.gs-audit-progress-fill', timeout: 120000, timelapse: 12 }, // POST + load → progress shows
+    { type: 'wait', selector: '.gs-exec-summary', timeout: 1100000, timelapse: 40 }, // the run → ~20s
+    { type: 'captionHide' },
+    { type: 'wait', duration: 1000 },
+
+    // --- the result ---
+    { type: 'caption', text: 'Il risultato: punteggio di visibilità, competitor, cosa migliorare.', duration: 3200 },
+    { type: 'highlight', selector: '.gs-score-range', pad: 6, duration: 2000 },
+    { type: 'scroll', selector: '.gs-mp-rankings', duration: 800 },
+    { type: 'caption', text: 'Come ti posizioni contro i competitor nelle risposte AI.', duration: 3000 },
+    { type: 'highlight', selector: '.gs-mp-rankings', pad: 6, duration: 2000 },
+    { type: 'wait', duration: 600 },
+
+    // --- ask Geo ---
+    { type: 'caption', text: 'E il copilota Geo risponde sui tuoi dati.', duration: 2600 },
+    { type: 'move', selector: '.gs-workspace-sidebar a[href="/app/assistant"]', duration: 550 },
+    { type: 'click', selector: '.gs-workspace-sidebar a[href="/app/assistant"]' },
+    { type: 'wait', selector: '.gs-asst-composer-input', timeout: 20000 },
+    { type: 'wait', duration: 700 },
+    { type: 'type', selector: '.gs-asst-composer-input', text: 'Qual è il punteggio di visibilità AI del mio ultimo audit?', perChar: 30 },
+    { type: 'click', selector: '.gs-asst-composer button' },
+    { type: 'caption', text: 'Geo legge l’audit e risponde.', hold: true },
+    { type: 'wait', selector: '.gs-asst-feedback', timeout: 120000 },
+    { type: 'captionHide' },
+    { type: 'wait', duration: 800 },
+    { type: 'zoom', selector: '.gs-asst-bubble-assistant', scale: 1.08, duration: 700 },
+    { type: 'wait', duration: 2400 },
+    { type: 'zoomReset', duration: 550 },
+
+    { type: 'endcard', title: 'GeoSuite', subtitle: 'trygeosuite.it', duration: 2800 },
+  ],
+})

package/examples/geosuite-workspace-audit.config.js

@@ -0,0 +1,83 @@
+import { defineDemo } from '../src/index.js'
+
+// A real-world demowright config: a workspace tour ending on a completed audit's
+// results, at 1920×1080. Uses only pre-computed content (no live LLM calls), so
+// it renders reliably in CI. Live add-brand scrape and the Geo assistant are
+// omitted here — see geosuite-howitworks.config.js for those.
+//
+// Credentials come from the environment (see the `auth` block):
+//
+//   GEOSUITE_URL=https://your-instance.example \
+//   GEOSUITE_EMAIL=you@example.com GEOSUITE_PASSWORD=... \
+//   node bin/cli.js run examples/geosuite-workspace-audit.config.js -o output/geosuite-workspace-audit.mp4
+
+const BASE = process.env.GEOSUITE_URL || 'http://localhost:3000'
+
+const INIT = `(() => {
+  const get = Storage.prototype.getItem
+  Storage.prototype.getItem = function (k) {
+    if (typeof k === 'string') {
+      if (k.indexOf('gs-workspace-tour:') === 0) return '1'
+      if (k === 'gs-sidebar-expanded-groups') return JSON.stringify(['Analizza', 'Account', 'Analyze'])
+    }
+    return get.call(this, k)
+  }
+})();`
+
+export default defineDemo({
+  name: 'geosuite-workspace-audit',
+  url: `${BASE}/app`,
+  viewport: { width: 1920, height: 1080 },
+  theme: { accent: '#ff3b7a' },
+  locale: 'it-IT',
+  formats: ['landscape'],
+  init: INIT,
+
+  auth: {
+    url: `${BASE}/login`,
+    fields: [
+      { selector: 'input[type="email"]', env: 'GEOSUITE_EMAIL' },
+      { selector: 'input[type="password"]', env: 'GEOSUITE_PASSWORD' },
+    ],
+    submit: 'button[type="submit"]',
+    waitUrl: '**/app**',
+  },
+
+  steps: [
+    { type: 'wait', selector: '.gs-workspace-sidebar', timeout: 20000 },
+    { type: 'wait', duration: 800 },
+
+    // cockpit
+    { type: 'caption', text: 'GeoSuite: la tua visibilità sulle AI, in un posto solo.', duration: 2800 },
+    { type: 'highlight', selector: '.gs-admin-hero', pad: 6, duration: 1600 },
+    { type: 'caption', text: 'Brand, audit e i tuoi dati — tutto qui.', duration: 2400 },
+
+    // brand profile
+    { type: 'move', selector: '.gs-workspace-sidebar a[href="/app/brand"]', duration: 550 },
+    { type: 'click', selector: '.gs-workspace-sidebar a[href="/app/brand"]' },
+    { type: 'wait', duration: 2200 },
+    { type: 'caption', text: 'Il profilo del brand e il suo punteggio di visibilità GEO.', duration: 3000 },
+    { type: 'highlight', selector: '.gs-admin-panel', pad: 4, duration: 2000 },
+
+    // audit center
+    { type: 'move', selector: '.gs-workspace-sidebar a[href="/app/audits"]', duration: 550 },
+    { type: 'click', selector: '.gs-workspace-sidebar a[href="/app/audits"]' },
+    { type: 'wait', duration: 2200 },
+    { type: 'caption', text: 'Gli audit misurano quanto le AI ti citano.', duration: 2800 },
+    { type: 'highlight', selector: '.gs-admin-tile-row', pad: 6, duration: 1900 },
+
+    // a real completed audit's results
+    { type: 'move', selector: 'a[href*="/app/audits/"]', duration: 550 },
+    { type: 'click', selector: 'a[href*="/app/audits/"]' },
+    { type: 'wait', selector: '.gs-exec-summary', timeout: 30000 },
+    { type: 'wait', duration: 1000 },
+    { type: 'caption', text: 'Dentro un audit: punteggio, competitor, cosa migliorare.', duration: 3200 },
+    { type: 'highlight', selector: '.gs-score-range', pad: 6, duration: 2200 },
+    { type: 'scroll', selector: '.gs-mp-rankings', duration: 800 },
+    { type: 'caption', text: 'Come ti posizioni contro i competitor nelle risposte AI.', duration: 3000 },
+    { type: 'highlight', selector: '.gs-mp-rankings', pad: 6, duration: 2000 },
+    { type: 'wait', duration: 800 },
+
+    { type: 'endcard', title: 'GeoSuite', subtitle: 'trygeosuite.it', duration: 2800 },
+  ],
+})

package/examples/local-demo.config.js

@@ -0,0 +1,36 @@
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { defineDemo } from '../src/index.js'
+
+// Point the demo at the bundled local site (portable across machines).
+const here = path.dirname(fileURLToPath(import.meta.url))
+const siteUrl = pathToFileURL(path.join(here, 'site', 'index.html')).href
+
+// The narrative mirrors the GeoSuite "geobot" story on purpose: a crowded
+// sidebar → "just ask" → the assistant runs the right tool by itself.
+export default defineDemo({
+  name: 'local-demo',
+  url: siteUrl,
+  viewport: { width: 1280, height: 720 },
+  theme: { accent: '#e91e63' },
+  formats: ['landscape'],
+  steps: [
+    { type: 'caption', text: '18 voci nella sidebar.\nTrova tu quella giusta.', duration: 2800 },
+    { type: 'highlight', selector: '.sidebar', pad: 4, duration: 1500 },
+    { type: 'zoom', selector: '.sidebar', scale: 1.18 },
+    { type: 'wait', duration: 900 },
+    { type: 'zoomReset' },
+    { type: 'highlightHide' },
+    { type: 'caption', text: 'Oppure: chiedi e basta.', duration: 2200 },
+    { type: 'move', selector: '#q', duration: 700 },
+    { type: 'type', selector: '#q', text: 'Come mi vede ChatGPT rispetto ai competitor?', perChar: 40 },
+    { type: 'click', selector: '#ask' },
+    { type: 'caption', text: "L'assistente lancia il tool da solo.", duration: 2600 },
+    { type: 'wait', selector: '#result .done', timeout: 15000 },
+    { type: 'wait', duration: 600 },
+    { type: 'zoom', selector: '.assistant', scale: 1.25 },
+    { type: 'wait', duration: 1600 },
+    { type: 'zoomReset' },
+    { type: 'endcard', title: 'demowright', subtitle: 'demo as code', duration: 2600 },
+  ],
+})

package/examples/site/index.html

@@ -0,0 +1,141 @@
+<!doctype html>
+<html lang="it">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Demo App</title>
+    <style>
+      * { box-sizing: border-box; }
+      html, body { margin: 0; height: 100%; }
+      body {
+        font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+        background: #0b0b0e;
+        color: #e7e7ea;
+        display: flex;
+        height: 100vh;
+        overflow: hidden;
+      }
+      .sidebar {
+        width: 240px;
+        flex: 0 0 240px;
+        border-right: 1px solid rgba(255, 255, 255, 0.08);
+        background: rgba(255, 255, 255, 0.02);
+        padding: 16px 10px;
+        overflow-y: auto;
+      }
+      .brand { font-weight: 800; font-size: 18px; padding: 6px 10px 14px; letter-spacing: -0.3px; }
+      .brand span { color: #e91e63; }
+      .nav-group { font-size: 11px; text-transform: uppercase; letter-spacing: 0.08em; color: #75757e; padding: 12px 10px 6px; }
+      .nav-item {
+        display: flex; align-items: center; gap: 10px;
+        padding: 8px 10px; border-radius: 8px;
+        font-size: 13px; color: #b9b9c2; cursor: pointer;
+      }
+      .nav-item:hover { background: rgba(255, 255, 255, 0.05); color: #fff; }
+      .nav-item .dot { width: 6px; height: 6px; border-radius: 50%; background: #44444c; }
+      .main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+      .topbar { padding: 16px 28px; border-bottom: 1px solid rgba(255, 255, 255, 0.06); font-weight: 600; }
+      .stage { flex: 1; display: flex; align-items: center; justify-content: center; padding: 28px; }
+      .assistant {
+        width: 100%; max-width: 620px;
+        background: rgba(255, 255, 255, 0.03);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 18px; padding: 22px;
+      }
+      .assistant h2 { margin: 0 0 4px; font-size: 20px; }
+      .assistant p.sub { margin: 0 0 18px; color: #8a8a93; font-size: 13px; }
+      .composer { display: flex; gap: 10px; }
+      #q {
+        flex: 1; resize: none; height: 46px;
+        background: #141418; color: #fff;
+        border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 12px;
+        padding: 12px 14px; font-size: 15px; font-family: inherit;
+      }
+      #q:focus { outline: none; border-color: #e91e63; }
+      #ask {
+        border: none; border-radius: 12px; padding: 0 20px;
+        background: #e91e63; color: #fff; font-weight: 700; font-size: 14px; cursor: pointer;
+      }
+      #result { margin-top: 18px; min-height: 10px; }
+      .think { color: #8a8a93; font-size: 13px; display: flex; gap: 8px; align-items: center; }
+      .tool {
+        display: inline-flex; align-items: center; gap: 8px;
+        background: rgba(233, 30, 99, 0.12); color: #ff7aa8;
+        border: 1px solid rgba(233, 30, 99, 0.3);
+        border-radius: 999px; padding: 5px 12px; font-size: 12px; font-weight: 600; margin: 6px 0;
+      }
+      .answer { font-size: 15px; line-height: 1.55; }
+      .cursor::after { content: "▍"; color: #e91e63; animation: blink 1s steps(2) infinite; }
+      @keyframes blink { 50% { opacity: 0; } }
+    </style>
+  </head>
+  <body>
+    <aside class="sidebar">
+      <div class="brand">Demo<span>App</span></div>
+      <div class="nav-group">Workspace</div>
+      <div class="nav-item"><span class="dot"></span>Overview</div>
+      <div class="nav-item"><span class="dot"></span>Store &amp; Catalog</div>
+      <div class="nav-group">Insights</div>
+      <div class="nav-item"><span class="dot"></span>Analytics</div>
+      <div class="nav-item"><span class="dot"></span>Categories</div>
+      <div class="nav-item"><span class="dot"></span>Products</div>
+      <div class="nav-item"><span class="dot"></span>Competitors</div>
+      <div class="nav-item"><span class="dot"></span>Citations</div>
+      <div class="nav-group">Tools</div>
+      <div class="nav-item"><span class="dot"></span>Brief Generator</div>
+      <div class="nav-item"><span class="dot"></span>Citation Strategy</div>
+      <div class="nav-item"><span class="dot"></span>Audience Intent</div>
+      <div class="nav-item"><span class="dot"></span>Content Planner</div>
+      <div class="nav-item"><span class="dot"></span>Product Optimizer</div>
+      <div class="nav-group">Account</div>
+      <div class="nav-item"><span class="dot"></span>Audits</div>
+      <div class="nav-item"><span class="dot"></span>Audit History</div>
+      <div class="nav-item"><span class="dot"></span>Reports</div>
+      <div class="nav-item"><span class="dot"></span>Settings</div>
+      <div class="nav-item"><span class="dot"></span>Billing</div>
+    </aside>
+
+    <div class="main">
+      <div class="topbar">Assistant</div>
+      <div class="stage">
+        <div class="assistant">
+          <h2>Ask the assistant</h2>
+          <p class="sub">No more hunting through the sidebar — just say what you need.</p>
+          <div class="composer">
+            <textarea id="q" placeholder="Type a question…"></textarea>
+            <button id="ask">Ask</button>
+          </div>
+          <div id="result"></div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const result = document.getElementById('result')
+      document.getElementById('ask').addEventListener('click', () => {
+        result.innerHTML = '<div class="think">Thinking…</div>'
+        setTimeout(() => {
+          result.innerHTML = '<div class="tool">⚙ running tool: brand-audit</div>'
+        }, 900)
+        setTimeout(() => {
+          result.innerHTML =
+            '<div class="tool">⚙ brand-audit · done</div>' +
+            '<div class="answer cursor" id="ans"></div>'
+          const ans = document.getElementById('ans')
+          const text =
+            'ChatGPT mentions your brand in 3 of 10 comparison prompts, ' +
+            'usually behind two competitors. Strongest on price, weakest on reviews.'
+          let i = 0
+          const tick = setInterval(() => {
+            ans.textContent = text.slice(0, (i += 2))
+            if (i >= text.length) {
+              clearInterval(tick)
+              ans.classList.remove('cursor')
+              ans.classList.add('done')
+            }
+          }, 28)
+        }, 1900)
+      })
+    </script>
+  </body>
+</html>