@matte97p/demowright 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@matte97p/demowright",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Record polished product demo videos from a script. Playwright drives the browser, the overlay (captions, smooth cursor, auto-zoom, end card) is baked into the recording. A demo that lives in your repo and re-renders in CI — so it never goes stale.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matteo Perino <matte97.p@gmail.com> (https://github.com/matte97p)",
+  "contributors": [
+    "Matteo Perino <matte97.p@gmail.com> (https://github.com/matte97p)",
+    "GeoSuite (https://trygeosuite.it)"
+  ],
+  "homepage": "https://github.com/matte97p/demowright#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matte97p/demowright.git"
+  },
+  "bugs": {
+    "url": "https://github.com/matte97p/demowright/issues"
+  },
+  "keywords": [
+    "demo",
+    "demo-video",
+    "screencast",
+    "screen-recording",
+    "product-demo",
+    "playwright",
+    "video",
+    "ffmpeg",
+    "marketing",
+    "devtools",
+    "ci"
+  ],
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "demowright": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples/local-demo.config.js",
+    "examples/geosuite-howitworks.config.js",
+    "examples/geosuite-workspace-audit.config.js",
+    "examples/site",
+    "assets",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "lint": "node --check src/index.js && node --check src/runner.js && node --check src/overlay.js && node --check src/steps.js && node --check src/render.js && node --check src/scaffold.js && node --check bin/cli.js",
+    "test": "node --check examples/local-demo.config.js && echo \"ok: example config parses (no unit tests yet)\"",
+    "demo": "node bin/cli.js run examples/local-demo.config.js -o output/local-demo.mp4"
+  },
+  "dependencies": {
+    "ffmpeg-static": "^5.2.0",
+    "playwright": "^1.45.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.js

@@ -0,0 +1,41 @@
+/**
+ * demowright — record polished product demo videos from a script.
+ *
+ * Public API:
+ *   recordDemo(demo, opts)  capture + render in one call → { outputs, demo }
+ *   defineDemo(demo)        identity helper for editor autocompletion
+ *   runDemo / renderVideo   the two stages, if you want them separately
+ */
+import { rm } from 'node:fs/promises'
+import path from 'node:path'
+import { normalizeDemo, defineDemo, estimateDurationMs, STEP_TYPES } from './steps.js'
+import { runDemo } from './runner.js'
+import { renderVideo } from './render.js'
+
+export { defineDemo, normalizeDemo, runDemo, renderVideo, estimateDurationMs, STEP_TYPES }
+
+/**
+ * Capture a demo and render it to MP4(s).
+ * @param {object} rawDemo  the demo definition ({ url, steps, ... })
+ * @param {object} [opts]   { out, formats, music, workDir, keepRaw, onStep }
+ * @returns {Promise<{ outputs: Array<{format,path}>, demo: object }>}
+ */
+export async function recordDemo(rawDemo, opts = {}) {
+  const demo = normalizeDemo(rawDemo)
+  const out = opts.out || path.join(process.cwd(), 'output', demo.name + '.mp4')
+  const workDir = opts.workDir || path.join(path.dirname(out), '.demowright-tmp')
+
+  const { rawVideoPath, timelapses } = await runDemo(demo, { workDir, onStep: opts.onStep, onAuth: opts.onAuth })
+  const outputs = await renderVideo(rawVideoPath, {
+    out,
+    formats: opts.formats && opts.formats.length ? opts.formats : demo.formats,
+    music: opts.music || demo.music,
+    musicVolume: demo.musicVolume,
+    fps: demo.fps,
+    timelapses,
+    workDir,
+  })
+
+  if (!opts.keepRaw) await rm(workDir, { recursive: true, force: true })
+  return { outputs, demo }
+}

package/src/overlay.js

@@ -0,0 +1,262 @@
+/**
+ * In-page overlay runtime.
+ *
+ * This function is serialized with `.toString()` and injected into the page via
+ * Playwright's `addInitScript`, so it re-installs itself on every navigation.
+ * It exposes `window.__dw`, a small API the runner drives over `page.evaluate`.
+ *
+ * The whole point: the polish (captions, a smooth synthetic cursor, zoom, an end
+ * card) is part of the DOM, so it ends up *inside* the recorded video — no
+ * post-production compositing needed. The browser never shows the real OS cursor
+ * in a headless recording, which is exactly why we draw our own.
+ *
+ * Coordinate model:
+ *  - The overlay root is attached to <html> (documentElement), so it is NOT a
+ *    descendant of <body> and is therefore unaffected by the zoom transform we
+ *    apply to <body>. Captions and cursor stay crisp while the page zooms.
+ *  - `getBoundingClientRect()` already reflects ancestor CSS transforms, so the
+ *    cursor/ring always land on the element as actually rendered, zoom or not.
+ */
+export function overlayRuntime(theme) {
+  if (window.__dw) return
+  const ACCENT = (theme && theme.accent) || '#e91e63'
+  const FONT =
+    (theme && theme.font) ||
+    'system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif'
+  const EASE = 'cubic-bezier(0.22, 0.61, 0.36, 1)'
+
+  let root = null
+  let cursorEl = null
+  let clickRingEl = null
+  let captionEl = null
+  let ringEl = null
+  let cardEl = null
+  let captionTimer = null
+
+  function ensureRoot() {
+    if (root) return
+    root = document.createElement('div')
+    root.id = '__dw-overlay'
+    Object.assign(root.style, {
+      position: 'fixed',
+      left: '0',
+      top: '0',
+      width: '100%',
+      height: '100%',
+      pointerEvents: 'none',
+      zIndex: '2147483647',
+      fontFamily: FONT,
+      overflow: 'hidden',
+    })
+
+    // Synthetic cursor (SVG arrow) — moves via a transform transition.
+    cursorEl = document.createElement('div')
+    Object.assign(cursorEl.style, {
+      position: 'absolute',
+      left: '0',
+      top: '0',
+      width: '28px',
+      height: '28px',
+      transform: 'translate(-40px, -40px)',
+      filter: 'drop-shadow(0 2px 3px rgba(0,0,0,0.45))',
+      willChange: 'transform',
+    })
+    cursorEl.innerHTML =
+      '<svg viewBox="0 0 24 24" width="28" height="28">' +
+      '<path d="M5 2.5 19 12.2l-6.1.7 3.5 7.1-2.7 1.3-3.5-7.2L5 19.5z" ' +
+      'fill="#fff" stroke="#111" stroke-width="1.2" stroke-linejoin="round"/></svg>'
+
+    // Click pulse ring.
+    clickRingEl = document.createElement('div')
+    Object.assign(clickRingEl.style, {
+      position: 'absolute',
+      left: '0',
+      top: '0',
+      width: '14px',
+      height: '14px',
+      marginLeft: '0px',
+      marginTop: '0px',
+      borderRadius: '50%',
+      border: '2px solid ' + ACCENT,
+      transform: 'translate(-40px, -40px) scale(0.2)',
+      opacity: '0',
+    })
+
+    // Caption bar (bottom-center).
+    captionEl = document.createElement('div')
+    Object.assign(captionEl.style, {
+      position: 'absolute',
+      left: '50%',
+      bottom: '7%',
+      transform: 'translateX(-50%) translateY(12px)',
+      maxWidth: '78%',
+      padding: '14px 22px',
+      borderRadius: '14px',
+      background: 'rgba(12, 12, 14, 0.82)',
+      backdropFilter: 'blur(6px)',
+      color: '#fff',
+      fontSize: '26px',
+      lineHeight: '1.3',
+      fontWeight: '600',
+      letterSpacing: '0.2px',
+      textAlign: 'center',
+      boxShadow: '0 10px 40px rgba(0,0,0,0.35)',
+      opacity: '0',
+      transition: 'opacity 320ms ease, transform 320ms ' + EASE,
+      whiteSpace: 'pre-wrap',
+    })
+
+    // Highlight ring around an element.
+    ringEl = document.createElement('div')
+    Object.assign(ringEl.style, {
+      position: 'absolute',
+      left: '0',
+      top: '0',
+      borderRadius: '12px',
+      border: '3px solid ' + ACCENT,
+      boxShadow: '0 0 0 9999px rgba(8,8,10,0.0)',
+      opacity: '0',
+      transition: 'opacity 260ms ease, left 420ms ' + EASE + ', top 420ms ' + EASE + ', width 420ms ' + EASE + ', height 420ms ' + EASE,
+    })
+
+    root.append(ringEl, captionEl, clickRingEl, cursorEl)
+    ;(document.documentElement || document.body).appendChild(root)
+  }
+
+  function center(selector) {
+    const el = document.querySelector(selector)
+    if (!el) return null
+    const r = el.getBoundingClientRect()
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2, rect: r }
+  }
+
+  const api = {}
+
+  api.ready = function () {
+    ensureRoot()
+    return true
+  }
+
+  api.cursorTo = function (x, y, ms) {
+    ensureRoot()
+    cursorEl.style.transition = 'transform ' + (ms || 600) + 'ms ' + EASE
+    cursorEl.style.transform = 'translate(' + x + 'px, ' + y + 'px)'
+  }
+
+  api.cursorToSelector = function (selector, ms) {
+    ensureRoot()
+    const c = center(selector)
+    if (!c) return false
+    api.cursorTo(c.x, c.y, ms)
+    return true
+  }
+
+  api.click = function () {
+    ensureRoot()
+    const t = cursorEl.style.transform
+    clickRingEl.style.transition = 'none'
+    clickRingEl.style.transform = t + ' scale(0.2)'
+    clickRingEl.style.opacity = '0.9'
+    // Force reflow so the pulse animates from the reset state.
+    void clickRingEl.offsetWidth
+    clickRingEl.style.transition = 'transform 480ms ease-out, opacity 480ms ease-out'
+    clickRingEl.style.transform = t + ' scale(2.6)'
+    clickRingEl.style.opacity = '0'
+  }
+
+  api.caption = function (text, ms) {
+    ensureRoot()
+    if (captionTimer) clearTimeout(captionTimer)
+    captionEl.textContent = text
+    captionEl.style.opacity = '1'
+    captionEl.style.transform = 'translateX(-50%) translateY(0)'
+    if (ms && ms > 0) {
+      captionTimer = setTimeout(api.captionHide, ms)
+    }
+  }
+
+  api.captionHide = function () {
+    if (!captionEl) return
+    captionEl.style.opacity = '0'
+    captionEl.style.transform = 'translateX(-50%) translateY(12px)'
+  }
+
+  api.highlight = function (selector, pad) {
+    ensureRoot()
+    const c = center(selector)
+    if (!c) return false
+    const p = pad == null ? 8 : pad
+    ringEl.style.left = c.rect.left - p + 'px'
+    ringEl.style.top = c.rect.top - p + 'px'
+    ringEl.style.width = c.rect.width + p * 2 + 'px'
+    ringEl.style.height = c.rect.height + p * 2 + 'px'
+    ringEl.style.opacity = '1'
+    return true
+  }
+
+  api.highlightHide = function () {
+    if (ringEl) ringEl.style.opacity = '0'
+  }
+
+  api.zoom = function (selector, scale, ms) {
+    ensureRoot()
+    const c = center(selector)
+    if (!c) return false
+    const ox = c.x + window.scrollX
+    const oy = c.y + window.scrollY
+    const b = document.body
+    b.style.transition = 'transform ' + (ms || 700) + 'ms ' + EASE
+    b.style.transformOrigin = ox + 'px ' + oy + 'px'
+    b.style.transform = 'scale(' + scale + ')'
+    return true
+  }
+
+  api.zoomReset = function (ms) {
+    const b = document.body
+    b.style.transition = 'transform ' + (ms || 600) + 'ms ' + EASE
+    b.style.transform = 'none'
+  }
+
+  api.endcard = function (title, subtitle, ms) {
+    ensureRoot()
+    if (!cardEl) {
+      cardEl = document.createElement('div')
+      Object.assign(cardEl.style, {
+        position: 'absolute',
+        left: '0',
+        top: '0',
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: '14px',
+        background: 'radial-gradient(120% 120% at 50% 30%, #1b1b22 0%, #0b0b0e 70%)',
+        color: '#fff',
+        opacity: '0',
+        transition: 'opacity 520ms ease',
+      })
+      const t = document.createElement('div')
+      t.className = '__dw-card-title'
+      Object.assign(t.style, { fontSize: '56px', fontWeight: '800', letterSpacing: '-0.5px' })
+      const s = document.createElement('div')
+      s.className = '__dw-card-sub'
+      Object.assign(s.style, { fontSize: '24px', fontWeight: '500', color: ACCENT })
+      cardEl.append(t, s)
+      root.appendChild(cardEl)
+    }
+    cardEl.querySelector('.__dw-card-title').textContent = title || ''
+    cardEl.querySelector('.__dw-card-sub').textContent = subtitle || ''
+    void cardEl.offsetWidth
+    cardEl.style.opacity = '1'
+    return true
+  }
+
+  window.__dw = api
+}
+
+/** Build the init-script source string that installs the overlay in-page. */
+export function buildInitScript(theme) {
+  return '(' + overlayRuntime.toString() + ')(' + JSON.stringify(theme || {}) + ')'
+}

package/src/render.js

@@ -0,0 +1,137 @@
+/**
+ * The render stage: turn the raw .webm Playwright produced into shareable MP4s.
+ *
+ * Playwright records silent video, so audio (if any) is the supplied music track.
+ * Formats are derived with ffmpeg filters so one capture yields landscape (16:9),
+ * square (1:1), and vertical (9:16 with a blurred fill) without re-recording.
+ */
+import { spawn } from 'node:child_process'
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+import ffmpegPath from 'ffmpeg-static'
+
+/** Video-filter graph per format. `[v]` is the labelled final video pad. */
+const FILTERS = {
+  landscape: 'scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,setsar=1[v]',
+  square: 'crop=ih:ih:(iw-ih)/2:0,scale=1080:1080,setsar=1[v]',
+  vertical:
+    'split=2[bg][fg];' +
+    '[bg]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=24:4[bgb];' +
+    '[fg]scale=1080:-2[fgs];' +
+    '[bgb][fgs]overlay=(W-w)/2:(H-h)/2,setsar=1[v]',
+}
+
+function runFfmpeg(args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    proc.stderr.on('data', (d) => {
+      stderr += d.toString()
+    })
+    proc.on('error', reject)
+    proc.on('close', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error('ffmpeg exited ' + code + '\n' + stderr.split('\n').slice(-12).join('\n')))
+    })
+  })
+}
+
+/**
+ * Speed up one or more time ranges of the capture (the "dead waits" — a scrape,
+ * an audit running) while leaving the rest at real time. `timelapses` is a list
+ * of { start, end, factor } in seconds, relative to the video start. Returns the
+ * path to a new intermediate video; the format crops then run on top of it. With
+ * no ranges, the original path is returned untouched.
+ */
+async function applyTimelapse(rawVideoPath, timelapses, workDir, fps) {
+  const ranges = (timelapses || [])
+    .filter((t) => t && t.factor > 1 && t.end > t.start)
+    .sort((a, b) => a.start - b.start)
+  if (!ranges.length) return rawVideoPath
+
+  const parts = []
+  const labels = []
+  let cursor = 0
+  let i = 0
+  const seg = (expr, label) => {
+    parts.push('[0:v]' + expr + '[' + label + ']')
+    labels.push('[' + label + ']')
+  }
+  for (const r of ranges) {
+    if (r.start > cursor) {
+      seg('trim=start=' + cursor.toFixed(3) + ':end=' + r.start.toFixed(3) + ',setpts=PTS-STARTPTS', 'n' + i)
+      i++
+    }
+    seg(
+      'trim=start=' + r.start.toFixed(3) + ':end=' + r.end.toFixed(3) + ',setpts=(PTS-STARTPTS)/' + r.factor,
+      'f' + i
+    )
+    i++
+    cursor = r.end
+  }
+  // tail: from the last range to the end (open-ended trim)
+  seg('trim=start=' + cursor.toFixed(3) + ',setpts=PTS-STARTPTS', 'n' + i)
+
+  const filter = parts.join(';') + ';' + labels.join('') + 'concat=n=' + labels.length + ':v=1:a=0[v]'
+  await mkdir(workDir, { recursive: true })
+  const out = path.join(workDir, 'timelapsed.mp4')
+  await runFfmpeg([
+    '-y', '-loglevel', 'error', '-i', rawVideoPath,
+    '-filter_complex', filter, '-map', '[v]',
+    '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '18',
+    '-r', String(fps), out,
+  ])
+  return out
+}
+
+function outPathFor(base, format, formats) {
+  if (formats.length === 1) return base
+  const ext = path.extname(base) || '.mp4'
+  const stem = base.slice(0, base.length - ext.length)
+  return stem + '.' + format + ext
+}
+
+/**
+ * Render `rawVideoPath` into one MP4 per requested format.
+ * Returns an array of { format, path } for the files written.
+ */
+export async function renderVideo(rawVideoPath, opts = {}) {
+  const formats = opts.formats && opts.formats.length ? opts.formats : ['landscape']
+  const base = opts.out || path.join(process.cwd(), 'output', 'demo.mp4')
+  const fps = opts.fps || 30
+  await mkdir(path.dirname(base), { recursive: true })
+
+  // Speed up the marked dead-wait ranges once, up front; the format crops then
+  // run on top of the time-lapsed intermediate.
+  const source = await applyTimelapse(rawVideoPath, opts.timelapses, opts.workDir || path.dirname(base), fps)
+
+  const results = []
+  for (const format of formats) {
+    const filter = FILTERS[format]
+    if (!filter) throw new Error('[demowright] unknown format "' + format + '" (use landscape|square|vertical)')
+    const out = outPathFor(base, format, formats)
+
+    const args = ['-y', '-loglevel', 'error', '-i', source]
+    if (opts.music) args.push('-stream_loop', '-1', '-i', opts.music)
+
+    args.push('-filter_complex', filter, '-map', '[v]')
+    if (opts.music) {
+      const vol = opts.musicVolume == null ? 0.18 : opts.musicVolume
+      args.push('-map', '1:a', '-af', 'volume=' + vol, '-c:a', 'aac', '-b:a', '128k')
+    }
+    args.push(
+      '-c:v', 'libx264',
+      '-pix_fmt', 'yuv420p',
+      '-preset', 'medium',
+      '-crf', '20',
+      '-r', String(fps),
+      '-movflags', '+faststart',
+      '-shortest',
+      out
+    )
+
+    await runFfmpeg(args)
+    results.push({ format, path: out })
+  }
+  return results
+}