@navipartner/demo-video 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@navipartner/demo-video",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Marketing demo videos of a React app, filmed by Playwright against the app's own e2e mocks.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navipartner/demo-video.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "import": "./dist/runner/index.js"
+    }
+  },
+  "bin": {
+    "demo-video": "./bin/demo-video.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "brands",
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "ffmpeg-static": "5.2.0",
+    "zod": "3.25.76"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.59.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@playwright/test": "^1.59.0",
+    "@types/node": "^25.2.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "globals": "^17.11.0",
+    "prettier": "3.9.6",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
 }

package/skills/np-demo-video/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: np-demo-video
+description: Produce or change a marketing demo video of a NaviPartner React app (retail self-checkout, food-order kiosk, or any app with a demo/ adapter) in the house look, which is calm camera pushes, serif statement cards and customer branding, recorded by the engine @navipartner/demo-video. Use when asked for a product demo video, a showcase of a flow, a marketing or SoMe clip, a customer-branded video (e.g. "two waters, in a customer's branding"), or to re-record a demo after UI changes.
+---
+
+# NaviPartner demo video
+
+You direct; the engine (`@navipartner/demo-video`) films. You write a story
+(JSON). Never write Playwright code for a video and never edit the app to
+make a video pass.
+
+**Read [look.md](look.md) first.** It defines how every video must look and
+feel: chapters, statement cards, camera, cursor, branding. This file is the
+workflow.
+
+## 1. Understand the request
+
+From the request, take:
+- **Product:** which app.
+- **Chapters:** the 1–4 ideas to show.
+- **Brand:** default NaviPartner.
+- **Data:** the products, names and amounts the request mentions ("two
+  waters").
+
+Card text defaults to English. Ask only for what you cannot infer.
+
+### The primary story
+
+Every app has one **primary story**: the journey the app exists for, from
+start to the moment of value. It is the app's first story, and the one filmed
+when a request names no feature ("make a video of the QR app", "a video in
+the customer's branding").
+
+| App | Primary story | Ends on |
+|---|---|---|
+| Self-service food order | order and pay | "Thank you", order number |
+| QR food order | order from the table | order received |
+| Retail self-checkout | scan and pay | paid, receipt |
+| NP Passes | create a pass | the pass is created |
+
+To find it in a new app:
+- **The e2e suite's happy path.** There is almost always a spec that walks the
+  whole flow (`complete-order-flow.spec.ts`, `06-order-complete.spec.ts`).
+  Follow it, and end where it asserts success.
+- **The app's purpose.** Its README, routes and package description say what
+  it is for. If they disagree with the happy-path spec, ask.
+
+Name the story for that job (`checkout`, `create-pass`) and mark it
+`"primary": true`. One story per app may be primary; `demo-video list` refuses
+two. In the PR, say which spec the story follows, so the developer can confirm
+it is the right journey.
+
+Run `pnpm --dir <app> exec demo-video list` first. If a primary story exists and the
+request names no feature, render it (`pnpm --dir <app> exec demo-video render` without `--story`,
+with `--brand` if one is asked for) instead of writing a new one. For a
+repo with several apps and no app named, ask which app, or offer each app's
+primary story. A PR never films it by default; only stories a PR adds or
+changes are filmed there.
+
+## 2. Plan the chapters on paper first
+
+Before any JSON, write the plan. For each chapter give, in this order:
+1. **What the viewer sees happen**, as one plain sentence with the chapter's
+   verb: "the shopper scans an item and it lands in the basket".
+2. **The actions** (2–5), and for each one **what it changes and where on
+   screen** that change appears (a new row at the top, the total at the
+   bottom, a new screen).
+3. **The shot:** one push-in on the area that holds a control *and* what it
+   changes, or wide when they're far apart. The camera never chases the
+   cursor.
+4. **The statement card**, written last, from sentence 1 (see "Writing the
+   cards").
+5. **The payoff fact**, if there is one: a value the app shows, checked with
+   `expectText`.
+
+Check it against look.md:
+- Is the story clear on mute?
+- Does every card describe exactly what the chapter after it shows?
+- Does the hook land by second 6?
+
+Example, retail self-checkout for a customer (here the made-up brand Acme):
+
+```
+open    Introducing · Acme logo · sub "Self-checkout"
+ch1     sees: a guest scans two waters and they land in the basket
+        shots: wide for the scans (the rows appear at the top);
+               push in 1.5 on the basket rows to read them
+        card: "Scan *and go*."
+ch2     sees: the guest pays by card and the payment goes through
+        shots: push in 1.6 on "Go to payment" (button + total);
+               pull out when the payment screen opens
+        card: "Pay *by card*."
+payoff  "Paid *in seconds*." · sub "64,50 kr. by card." (expectText on the total)
+end     Acme logo · "Self-checkout by NaviPartner"
+```
+
+## 3. Learn the app
+
+1. **Adapter:** `<app>/demo/demo.config.ts`. It says how the app runs
+   offline (`setup` → the e2e mocks), its `ready` testid and any
+   `actions` (e.g. retail's `scan`). No adapter yet: see "A new app" below.
+2. **Testids:** read the components for every screen in the plan and collect
+   their `data-testid`s.
+3. **Data:** a story is inspired only by what the project's Playwright
+   e2e tests already have: their mocks, logins and data. Read the e2e specs
+   (they already walk the flows) and the mocks `setup` calls. Only data they
+   return can appear (items, barcodes, prices, names).
+   - Never add fixtures or change the mocks or the app for a video.
+   - Skip the test edge cases the mocks contain on purpose, such as a product
+     with an absurdly long name or an error item.
+   - If the request needs data the e2e tests don't have, say so instead of
+     inventing it.
+   - One exception: a customer brand may rename the mock's products in its
+     `config.demoData` (see "A new brand"). It gives them names only, never
+     new barcodes, prices or flows.
+
+### A new app
+
+1. From the repo root: `npx --ignore-scripts @navipartner/demo-video init --app <app>`, then
+   `pnpm install`. (A repo set up for the first time runs
+   `npx --ignore-scripts @navipartner/demo-video init` without `--app` first.)
+   It adds the
+   dependency and writes a `demo.config.ts` skeleton with the dev server
+   from `playwright.config`.
+2. Finish the skeleton from the app's **current** code and e2e tests, not
+   from notes or an older adapter:
+   - `appPath` and `ready`: what the e2e helpers open and wait for.
+   - `setup`: the e2e mocks exactly as the tests call them.
+   - The brand: find the response that carries the app's branding and the
+     code that parses it. Lay the brand over it with `overlayResponse`,
+     using only keys that code accepts (colour formats, asset fields).
+   - `actions` for what a test does through code (a scanner bridge, a test
+     dispatch), and `idleTimeoutSeconds` if the app resets when idle.
+3. Write the primary story (above), then `pnpm --dir <app> exec demo-video check`.
+
+## 4. Write the story
+
+A developer writes stories locally (VS Code, with this skill) and a PR
+confirms them. A `/demo-video` PR comment, and later the Linear agent, only
+pick an existing story and a brand: they never write one. A story is
+`<app>/demo/stories/<name>.json`, named for what it shows (`checkout`,
+`settings`), and holds no brand: the same story renders for any brand with
+`--brand <name>`. A customer's own words go in a variant (below).
+
+    { "app": "<adapter app>",
+      "description": "One sentence: what the story shows. Follows e2e/<spec>.",
+      "primary": true,
+      "title":   { "eyebrow": "Introducing", "logo": true, "sub": "…" },
+      "closing": { "logo": true, "sub": "…" },
+      "steps": [ … ] }
+
+Steps: `click` `type` `press` `zoom` `frame` `zoomOut` `park` `waitFor`
+`expectText` `hold` `card`, plus the adapter's actions (every field in
+[reference.md](reference.md)).
+
+How the look maps onto steps:
+
+- **Cards:** `{ "do": "card", "heading": "Pay *by card*." }` opens a
+  chapter; `"style": "brand"` is the full-bleed payoff. A card stays up at
+  least as long as it takes to read, so `seconds` is only needed to hold one
+  longer.
+- **Push in:** `{ "do": "zoom", "target": "…", "scale": 1.6 }` on the area
+  where the action *and its result* are, then hold steady through the
+  clicks there. Use 1.4–1.8 (the engine accepts 1.3–2). `"zoom"` on a click
+  pushes in on that control first. At most two push-ins a chapter.
+- **Frame the action and its result together:**
+  `{ "do": "frame", "targets": ["pay-button", "order-total"] }` computes one
+  shot that holds them all (2–4 targets, each a testid or
+  `{ "target", "nth" }`), pushed in as far as they fit (at most 1.8, or
+  `maxScale`). Prefer it to guessing one zoom target. Targets too far apart
+  for a push-in fail `check`: frame things that sit together.
+- **A result elsewhere:** when a click changes something outside the shot (a
+  row added at the top, a new screen), pull out right after it
+  (`zoomOut`), or frame both from the start. `check` fails a click whose
+  change the viewer never sees.
+- **Read:** `hold` 1.5–3 s on anything the viewer must read (a total, a
+  confirmation).
+- **Leave the beats to the engine.** It pauses on each target before the
+  press, holds the press, waits for the app to react, settles the camera
+  before acting, lingers on a chapter's result before its card, and opens
+  every chapter wide with the cursor at rest. Don't add holds for those.
+- **Works with every brand:** any story can be filmed with any brand (the
+  label uses the app's default). Never target text a brand's `demoData`
+  sets (renamed products, an order number): pick products by testid and
+  `nth`, the mock's order. Run `check` without `--brand` as well as with the
+  brand you're writing for.
+- **Safety:** after each navigation, `waitFor` the next screen's testid. Put
+  `expectText` on prices and confirmations so the video fails if the copy is
+  wrong, and so a card may quote them.
+
+### Writing the cards
+
+The words are what the viewer remembers; write them with care.
+
+- **A statement names what the chapter shows,** in the chapter's own verb,
+  before it happens: a scan chapter is "Scan *and go*.", not "Shopping made
+  easy." If the viewer couldn't point at it in the next ten seconds, rewrite
+  it.
+- **The italic word is the action or its result** ("*scan*", "*by card*",
+  "*paid*"), never a filler word.
+- **A payoff states the result just shown,** with the app's real values from
+  an `expectText`: "64,50 kr. by card." No durations, counts or claims the
+  video doesn't show; `check` rejects a number no `expectText` proves.
+- **Title sub:** what the product is ("Self-checkout"). **Closing sub:** one
+  short line, the product's promise.
+- **Never on a card:** testids, barcodes, internal names, "demo", "test",
+  exclamation marks, "seamless", "effortless", "revolutionary".
+- Statements ≤ 7 words, subs ≤ 16 (`check` stops at 8 and 16), sentence
+  case, ending with a full stop.
+
+### A new brand
+
+A customer brand is `<app>/demo/brands/<name>.json` with its assets in
+`<app>/demo/brands/<name>/`. Fields: [reference.md](reference.md).
+
+A customer's name, logo and look are their trademarks. A video in them is
+made with their permission, from what they gave us, and stays internal until
+they approve it.
+
+- **Only with permission.** Make a customer brand only when the request says
+  the customer has agreed to a video in their branding (an account manager or
+  the customer asked for it). If that's unclear, ask before you start.
+- **Only their own material, never invented or recreated:** the logo file and
+  brand guide the customer supplied, or that a NaviPartner colleague received
+  from them. Don't download, trace, redraw or recolour a logo from their
+  website, and don't guess a colour or font. If a value is missing, ask the
+  customer contact for it; colours from their public site are a stand-in to
+  confirm with them, never final.
+- **Say where it came from.** The PR that adds the brand names the source of
+  the logo, colours and fonts, and who gave permission. Without that, the
+  brand doesn't merge.
+- **Logo:** an SVG or a PNG with a transparent background, readable on a
+  light background (`logoColor`, a top-level key, recolours a white SVG; use
+  it only when their brand guide allows that colour version).
+- **Fonts:** only a font whose licence covers use in a video. Google Fonts are
+  open-licensed and fine. A customer's own or commercial font is used only if
+  they confirm their licence covers it; otherwise take the closest Google
+  Font and say so in the report. Never copy font files from their website.
+- **No claims for them:** cards state what the video shows. No customer
+  quotes, statistics or "trusted by" lines, and a closing card says what the
+  product is, not that the customer endorses it.
+- **Publishing:** a customer-branded video goes to the customer for approval
+  before it is published anywhere. Say so in the report.
+- **`config`:** only keys the app's branding code accepts. Override every
+  value the e2e mock sets that would show through, such as a mock
+  `backgroundColor`.
+- **`config.demoData`** (when the adapter supports it): the customer's names
+  for the mock's products, keyed by the mock's barcodes. Mock data such as
+  "Toothpaste" or "TEST CARD" reads as a test run in a customer video. Use
+  plain product names ("Lemonade"), or ones the customer gave you, never a
+  third party's brand ("Coca-Cola"). Keep the mock's prices, so pick
+  products that are believable at those prices, and put the totals on the
+  cards from the render, not from your own sums.
+- **App limits:** an app may only offer presets (retail has two font pairs).
+  Pick the closest and say in the report what the kiosk can't show.
+- **`video` fonts** load from Google Fonts: the heading in 400, 700 and
+  italic 400, the body in 400 and 600. If a font lacks one, give `fontsUrl`
+  yourself.
+- Render with `--brand <name>` and check the stills before calling it done.
+
+### A variant: the story in a customer's words
+
+When a customer video needs its own words (their product, their place), write
+a variant beside the story instead of a copy: `checkout.acme.json`.
+
+    { "extends": "checkout",
+      "brand": "acme",
+      "description": "The checkout story, for Acme.",
+      "title":   { "sub": "Self-service at Acme" },
+      "closing": { "sub": "…" },
+      "cards":   [ { "heading": "A burger *and a lemonade*." }, { … }, { … } ] }
+
+- The steps are always the base story's: a variant changes words and brand,
+  never the flow. Fix the flow in the base, once, for every variant.
+- `cards` gives every card step of the base, in order; each entry, like
+  `title` and `closing`, changes only the fields it names. When the base
+  gains or loses a card, the variant stops loading until it is updated.
+- It films with its own brand only. `/demo-video checkout in acme branding`
+  and the form (story `checkout`, brand `acme`) pick the variant.
+- The same rules as any card: numbers proven by the base's `expectText`s,
+  and the customer's permission for their name (see "A new brand").
+- `check --story checkout.acme` before the PR, and re-check the variants
+  when you change their base.
+
+### Not supported yet
+
+There's no music bed. Videos are silent, so they must work on mute.
+
+## 5. Check, then render
+
+    pnpm --dir <app> exec demo-video check [--story <name>] --json
+
+Without `--story`, commands use the primary story. `check` performs every
+step for real and fails on anything that would film badly:
+
+| It says | Fix |
+|---|---|
+| `"x" is outside the shot …` | The zoom frames the wrong area: zoom on what this shot clicks, or `zoomOut` first |
+| `clicking "x" changes y, which is outside the shot …` | Frame what the click changes, or `zoomOut` right after the click |
+| `N camera push-ins in one chapter` | Push in once on the chapter's area and hold steady |
+| `… only fit in the wide shot` | `frame` things that sit together, or stay wide |
+| `… gives N cards; … has M` | Give the variant one entry per card of its story, in order |
+| `a zoom with nothing in its shot` | Remove it, or act or read something in it |
+| `zoom 2.4; use 1.3–2` | Zoom less: context reads better and stays sharp |
+| `"…" looks like a testid-like name / barcode / code` | Cards are for people: say it in words |
+| `"38" isn't shown by an expectText` | Quote only values an `expectText` checks |
+| `the card announces a chapter in which nothing is done` | Follow it with the steps it describes |
+
+Fix what the report names. Its `visible` list shows what is on screen at the
+failing step. Repeat until it passes, at most 3 rounds; a story that still
+fails is reported as "couldn't show this", with the last report. Then:
+
+    pnpm --dir <app> exec demo-video render [--story <name>] [--brand <name>]
+
+Rendering films every frame (60 fps, frame by frame), so it takes about
+five times the video's length. While tuning, `render --draft` films at
+30 fps in about half the time (`…-draft-demo.mp4`); render the final without
+it. Playwright starts the app's dev server from
+the adapter's `webServer`; if it can't on this machine, start it yourself
+with the same command and env, and it is reused.
+
+## 6. Review like a viewer
+
+Open `<app>/demo/out/review/sheet.jpg` first: one frame a second, the whole
+video at a glance. Then the full-size stills beside it. Judge against
+look.md:
+- **Story:** each statement card is followed by exactly what it says, and
+  the payoff by the result it states.
+- **Camera:** every push-in lands where something then happens; no shot is
+  mostly empty space; each click's result is on screen.
+- **Framing:** pushed-in shots fill the frame and read on a phone; nothing
+  important is cut off; the cursor rests out of the way.
+- **Pacing:** each chapter is one idea; nothing rushed, nothing lingering.
+- **Truth:** every word is true of what's on screen.
+
+Adjust the JSON and re-render. Two rounds of tuning is normal; if it takes
+more, the plan from step 2 is the problem.
+
+## Report
+
+Give:
+- the MP4 path and duration
+- the chapter plan
+- the contact sheet and stills
+- which brand it was rendered with, and for a customer brand, that the
+  video needs the customer's approval before it is published
+- anything the video could not show truthfully (it shows demo fixture data,
+  not a real tenant's)

package/skills/np-demo-video/look.md

@@ -0,0 +1,158 @@
+# The look
+
+Every NaviPartner demo video should look and feel the same, in order of importance for the visuals:
+
+1. **The product tells the story; text only frames it.** No caption pills
+   over the UI. Words appear on their own cards *between* the chapters, never
+   on top of the app.
+2. **Calm, purposeful camera.** It moves between shots, never during the
+   action: one smooth push-in on the area where the chapter's action and its
+   result happen, held steady through the clicks, then back out. It never
+   chases the cursor, and there are no hard cuts inside a chapter.
+3. **Soft, light, branded.** A pale brand-tinted background, a floating app
+   window, serif statements, and one brand colour used boldly once or twice.
+4. **Real-looking data.** Believable names, orders and products in the
+   customer's language and market. Never "Test item 1".
+
+## Structure
+
+A video is a sequence of **chapters**. Each chapter is one idea the viewer
+should remember.
+
+```
+open card      2–4 s   eyebrow "Introducing" + wordmark/logo; tagline fades in
+┌ statement    2–3 s   "A customer *scans* their basket."
+│ demo         10–25 s the app doing exactly that, camera following
+└ payoff       3–5 s   optional: what just happened, as a fact
+… 2–4 chapters …
+tagline        2–3 s   one line on brand colour: "Checkout that runs itself."
+end card       3–5 s   logo + tagline, still
+```
+
+- 30 s is enough for one chapter, 60–95 s for three or four. Length follows
+  the chapters. Don't pad, don't cram.
+- The first chapter's statement lands by second 6. The hook is the
+  open card plus the first statement, and nothing else.
+- A chapter ends wide (the whole window), so the next card has something to
+  dissolve from.
+
+## Text cards
+
+| Card | Text | Look |
+|---|---|---|
+| Open | eyebrow `Introducing` (small sans, grey) · brand wordmark/logo · tagline | pale background, centred |
+| Statement | ≤ 7 words naming what the next chapter shows, sentence case, ends with a full stop, **one word or phrase in italic** (the action or its result): "Pay *by card*." | dark serif on pale background |
+| Payoff | the result just shown as heading; sub-line states the concrete fact the app showed: "64,50 kr. by card." | white serif on full-bleed brand colour |
+| Stat | a number + what it counts: "60+ integrations" | pale, optional logo grid |
+| Tagline | the product's promise in ≤ 5 words | brand colour or pale, alternating |
+| End | logo + one-line tagline | pale, held still |
+
+- **Typeface:** the brand's fonts. For NaviPartner that's **Merriweather** for
+  headings (its italic is the emphasis word) and **Work Sans** for eyebrows and
+  sub-lines.
+  At 1080p: logo ~110 px tall equivalent, statements ~70 px, sub-lines
+  ~18–22 px.
+- **Tone:** plain, confident, present tense. No exclamation marks except
+  inside a quoted customer line. No "seamless", "revolutionary" or
+  "effortless".
+- **Truth:** every fact on a card must be visible in the video itself (the
+  price shown, the receipt that appears), checked by an `expectText`. No
+  invented durations or customer statistics. Stat cards only state real
+  product facts, such as the number of payment methods the app supports.
+- **Never on a card:** testids, barcodes, internal names or any other code.
+- **Reading time:** a card stays up at least 1 s plus ~0.3 s a word.
+
+## Transitions
+
+- **Blur dissolve** everywhere. Text blurs in from ~12 px to sharp over
+  ~500 ms. A card hands over to the app by blurring out while the app blurs in
+  behind it (~700 ms).
+- Into a payoff card: the brand colour washes over the wide app (~600 ms),
+  then the heading blurs in.
+- Card to card: the old words blur out first (~300 ms), then the new ones
+  blur in, so two headings never show at once.
+- No slides, wipes, spins, or zoom-punch transitions.
+
+## Camera
+
+- **Wide shot:** the app floats in the middle of the frame at ~90 % width.
+  Small corner radius, soft long shadow, no browser chrome.
+- **Push in once per shot** on the area that holds the control *and* what it
+  changes, to scale **1.4–1.8** (never past 2: tighter loses the context and
+  softens the picture). The UI should fill the frame and read on a phone.
+- **Hold steady through the action.** The clicks happen inside the shot; the
+  camera doesn't move with them. At most two push-ins a chapter.
+- **Show the result.** When an action changes something outside the shot (a
+  row added at the top, a new screen), pull out right after it. A push-in
+  that shows a button pressed and nothing happening is the worst shot.
+- **Each move eases in and out** (engine: 1200 ms,
+  `cubic-bezier(0.65, 0, 0.35, 1)`), then settles 300 ms before anything
+  happens. Hold ≥ 1.5 s on anything the viewer must read.
+- Every chapter opens wide: the engine resets the camera behind each card.
+
+## Cursor
+
+- A small standard arrow, used sparingly. It appears for the clicks and drags
+  a person would make. It glides on a gentle curve, easing in and out
+  (550–1100 ms by distance), and doesn't pulse, ripple or jerk.
+- **A beat around every click:** it rests on the control (220 ms, its hover
+  state shows), presses (110 ms, the pressed state shows), and the app's
+  reaction plays (650 ms) before anything else happens.
+- Between actions it rests where it doesn't cover what the viewer should
+  read.
+- If the UI animates by itself (an order total updating, a status changing),
+  let it play. Don't point at it.
+
+## Background and branding
+
+- **Background:** white tinted ~5–8 % with the brand's primary colour, with
+  one or two very soft radial blooms. Never a busy wallpaper, and never
+  dark mode.
+- **Brand colour:** the full-bleed payoff and tagline cards are the brand
+  colour. The brand's logo and wordmark are on the open and end cards. The
+  app itself is shown in the customer's branding (their kiosk looks like
+  their kiosk).
+- **Default brand:** NaviPartner (below). A customer video, made with the
+  customer's permission and their own brand material (see "A new brand" in
+  SKILL.md), swaps the logo, colours, fonts, tagline and data (their
+  products, their language), following the same roles.
+
+### NaviPartner brand
+
+These values are taken from navipartner.com and the official logo
+(`NaviPartner_rgb.svg`) on 2026-10-02. Use exactly these, never close guesses.
+
+| Role | Value |
+|---|---|
+| Primary: full-bleed payoff and tagline cards, italic emphasis word, background tint | `#1F5494` |
+| Navy: logo wordmark, statement headings on pale cards | `#123A7E` |
+| Light blue: the logo's "NAVI" mark, soft background bloom, sparingly | `#729FD3` |
+| Text: sub-lines and eyebrows | `#232323`; muted `#707070` |
+| Pale background base | `#F8F8F8` / `#FFFFFF` |
+| Heading font | Merriweather 400/700, italic for the emphasis word |
+| Body font | Work Sans 400/600/700 |
+| Logo | official two-colour SVG: `#729FD3` mark + `#123A7E` wordmark, on pale backgrounds only. On `#1F5494`, use it all white. |
+
+A NaviPartner pale card is `#F8F8F8` with a `#1F5494` tint at ~5 % and one
+`#729FD3` bloom, with the heading in navy and the italic word in primary. A
+brand card is full-bleed `#1F5494` with the heading in white Merriweather and
+the sub-line in white Work Sans at 80 % opacity.
+
+Keep the two brand layers apart. The cards and background use the video's
+brand (NaviPartner, or the customer's). What's inside the app window is the
+kiosk's tenant branding from the adapter's brand file.
+
+## Sound
+
+No music bed yet: videos are silent and must work on mute. The cards carry
+the whole story.
+
+## Formats
+
+- **Master:** 1920×1080, 16:9, 60 fps H.264, filmed frame by frame (each
+  frame a sharp screenshot of exactly that moment, never a screen recording).
+  This is used for the website and the LinkedIn feed.
+- **Portrait kiosk apps** (food order 1080×1920) float centred in the 16:9
+  frame, and the camera pushes in the same way.
+- 1:1 / 9:16 cuts for SoMe come later. Keep card text inside the central
+  1080×1080 area so a square crop still works.

package/skills/np-demo-video/reference.md

@@ -0,0 +1,82 @@
+# Reference: adapter, story and brand fields
+
+## Adapter (`<app>/demo/demo.config.ts`)
+
+`webServer` (`command`, `url`, `env`), `appPath`, `ready` (a testid shown once
+the mocks booted the app), `viewport` (default 1728×972; a portrait kiosk is
+scaled to fit) and `setup(page, { brand })`, which runs the app's e2e mocks
+**unchanged** and lays the brand over the response that carries it.
+Optional: `actions` (app steps such as a barcode scan), `idleTimeoutSeconds`,
+`defaultBrand`, `brands` (folder, default `./brands`), `locale`, `timezone`.
+
+```ts
+import { defineDemo, overlayResponse } from "@navipartner/demo-video";
+
+import { ApiMocks } from "../e2e/helpers/apiMocks";
+
+export default defineDemo({
+  app: "self-service-food-order",
+  webServer: { command: "pnpm dev", url: "http://localhost:3003", env: { VITE_E2E: "true" } },
+  appPath: "/?tenant=test",
+  viewport: { width: 1080, height: 1920 },
+  ready: "home-page",
+  async setup(page, { brand }) {
+    await new ApiMocks(page).setupMocks();
+    await overlayResponse(page, {
+      path: "/api/[^/]+/restaurant/?$",
+      at: "restaurants.*",
+      values: { ...brand.config, name: brand.tenantName, logoUrl: brand.assetUrls.logo },
+    });
+  },
+});
+```
+
+## Story (`<app>/demo/stories/<name>.json`)
+
+`app`, `description`, optional `primary`, `title`, `closing`, `steps`.
+
+- **Steps:** `click` `type` `press` `zoom` `frame` `zoomOut` `park` `waitFor`
+  `expectText` `hold` `card`, plus the adapter's actions as
+  `{ "do": "<action>", …params }`. `target` is a testid or any Playwright
+  selector (`role=button[name=/pay/i]`); `nth` picks among matches (-1 =
+  last). Clicks wait until their target stops moving.
+- **Cards** (`card`, `title`, `closing`): `eyebrow` (≤ 4 words), `heading`
+  (≤ 8, `*word*` in italic, once), `sub` (≤ 16), `logo`, `style` (`pale` |
+  `brand`), `seconds` (a minimum: a card stays up long enough to read).
+  Cards that follow each other hand over directly. A number on a card must be
+  checked by an `expectText` in the story.
+- **Camera:** `zoom` (`target`, `scale` 1.3–2) pushes in on that element's
+  area; `frame` (`targets`: 2–4 testids or `{ target, nth }`, optional
+  `maxScale` 1.3–2, default 1.8) pushes in as far as all of them fit, and
+  fails if they only fit wide; `zoomOut` (`park`) pulls back. A `click` keeps the camera unless it
+  has its own `"zoom"`. At most two push-ins a chapter, and a zoom needs
+  something done or read in its shot. A click target must be inside the
+  current shot, and what a zoomed click changes must be in the shot or shown
+  by the next step (a `zoomOut`, or a zoom that frames it). Every chapter
+  opens wide.
+- **Timing:** `hold` ≤ 6 s; `type` `perCharMs` ≥ 40. The engine adds the
+  beats around clicks, the camera's settle and a linger before each card.
+  Holds may not add up past the app's idle timeout.
+
+## Variant (`<app>/demo/stories/<story>.<brand>.json`)
+
+`extends` (the base story's name), `brand`, optional `description`, `title`,
+`closing` and `cards` (one entry per card step of the base, in order). Each
+card entry takes the card fields and changes only those it names. No
+`steps`, no `primary`: the flow is the base's. Filmed with its brand only.
+
+## Brand (`<app>/demo/brands/<name>.json`, assets in `<name>/`)
+
+- `tenantName`
+- `config`: opaque to the engine, the keys the app's branding API reads
+  (`primaryColor`, …). An adapter may also read `config.demoData`: the
+  customer's names for the mock's products, keyed by the mock's barcodes
+  (prices and flows stay the mock's). It takes `demoData` out before it
+  overlays the branding.
+- `assets`: slot → file, e.g. `{ "logo": "<name>/logo.svg" }`
+- `video`: `primary`, `ink`, `accent`, `text`, `headingFont`, `bodyFont`,
+  optional `fontsUrl`, `logo` (asset slot)
+- optional `logoColor` (recolours white fills in an SVG logo) and
+  `stage.background`
+
+The engine ships `navipartner`; an app's own brand of the same name wins.