# Spec v7 — Intro video & `/how-it-works` page Status: **implemented 2026-10-28** — repo side complete (video rendered, page integrated, checks green); owner-side open items: browser walkthrough (per project rules the owner verifies in a real browser) and the optional captured-footage variant (§6). ## 1. Goal A short introduction video that shows how this portfolio works — with emphasis on the two differentiators: **git as the content storage behind live editing** and **automatic deployment through GitHub Actions** — shown on a dedicated `/how-it-works` page. Decisions (owner-approved 2026-10-28): |Decision|Choice| |---|---| |Production|Remotion hybrid — Remotion-authored diagram/title scenes; real screen footage as an optional `captured` variant| |Placement|Dedicated `/how-it-works` page (route + manifest + nav entry), not a homepage section| |Audio|Captions only — burned-in on-screen text + EN/VI `.vtt` tracks; no voiceover| ## 2. The video `video/` is a standalone pnpm workspace member (Remotion 4 + React 19 + zod 4). The SPA never imports it; its only output is the committed media in `public/media/`. - 1920×1080 @ 30 fps, 2425 frames = **81 s**, H.264 CRF 23 → 1.5 MB, `+faststart` via Remotion defaults. (Extended from 62 s 2026-10-29: every callout chip must hold ≥150 frames / 5 s after it finishes appearing — the 62 s cut switched scenes while text was still mid-read.) - Visual language mirrors the site's dark palette (`src/index.css` `:root` values copied into `video/src/theme.ts` — the project cannot import site CSS). - Timeline source of truth: `video/src/timeline.ts` (`SCENES`). The chapter list in the `howItWorks` UI group and both `.vtt` tracks mirror these boundaries; changing the timeline means updating all four. |Scene|Frames|Seconds|Content| |---|---|---|---| |Title|0–165|0–5.5|"This site's CMS is a git repository."| |DataLayer|165–585|5.5–19.5|Structure documents + per-language dictionaries + manifests → joined once at build time → bilingual rendered page; callouts on the manifests rule and the same-components bilingual render| |LiveEdit|585–1285|19.5–42.8|`?edit` typed into the URL → Basic-auth dialog → inline heading edit → save bar: PUT contents/projects.json, commit on branch, 409 → three-way rebase; four callouts point at URL bar, auth gate, pencil control, save bar| |GitStorage|1285–1705|42.8–56.8|Repository file tree with the edited JSON highlighted, commit diff card, master/preview-branch graph, `?edit=preview`, merge = publish; callouts on JSON-in-repo, the preview branch node, history/rollback| |Pipeline|1705–2215|56.8–73.8|push → master → GitHub Actions group box (named on screen: `GitHub Actions · .github/workflows/deploy.yml`) → build · resume · deploy cards reached strictly in order — each connector draws only after the previous card has appeared, its arrowhead only after its line completes — then a downward arrow from the deploy job to the updated live page; infra guard card (deploy-infra.yml) follows the deploy beat; callouts on push-as-publish-button and the live-site result| |Outro|2215–2425|73.8–80.8|"Edit on the live site. Stored in git. Live on merge to master."| **Scene composition** (reviewed 2026-10-28 from rendered stills; the first render hugged every diagram to the right edge): each scene's visual group is centered on x=960 inside a strict band — title row y 80–175 (left), visual band y ~200–760 (centered). **Explanations are `Callout` chips that point at the diagram element they explain** (kit.tsx): a leader line draws from the element, the chip fades in only after the line completes, and the callout is timed to its beat — so every explanation follows the diagram in order instead of sitting in a fixed bottom text row; the old `SceneChrome` bullet row is deleted. **No-overlap rule** (2026-10-29 review): a leader line ends at the target element's outer edge — it never crosses into a panel, card or stage — and a chip sits fully outside its scene's visual-group bounding box (Pipeline's push callout narrowed to 230px so it clears the group box at x 689; LiveEdit's URL-bar and pencil leaders now stop at the stage border at x 1342 / 578). Two callouts per scene minimum (DataLayer: manifests rule → browser "same components, both languages"; LiveEdit: `?edit` URL → auth gate → inline-edit pencil → save-as-commit; GitStorage: JSON-in-repo → branch node → history/rollback; Pipeline: push-is-the-publish-button → live-site receipt). The four groups span x 420–1500 (DataLayer), 580–1340 (LiveEdit stage), 480–1410 (GitStorage), 449–1471 (Pipeline: push card + GitHub Actions group box). Same review fixed: absolute stage anchors in LiveEdit wrapped by a positioned div, never by `Fade` (Fade's `transform` becomes the containing block and anchors them after the skeleton); repository tree rows at 14px so no line wraps or overflows the panel; the "merge = publish" badge moved clear of the merge curve; the infra card widened to 440px. A second review (same day) applied a strict chain rule to every scene with connectors — DataLayer, GitStorage, Pipeline: an element appears only after the connector that reaches it has finished drawing, and an arrowhead appears only after its own line completes. `markerEnd` is gated on the stroke being ≥90 % drawn (SVG renders `markerEnd` even at full dash offset, so ungated heads floated in the air before their lines); GitStorage's branch/merge node circles are gated with `appear()` on their curve completing (master line and its node stay static — the published base predates the edit); DataLayer re-timed to documents → arrows → join panel → browser; Pipeline's three job cards sit in a dashed group box naming the runner on screen, `GitHub Actions · .github/workflows/deploy.yml`, and both caption tracks name the GitHub Actions pipeline in that scene's cue. Verified beat-by-beat from rendered stills. ## 3. Render commands ```sh pnpm --dir video render # public/media/how-it-works.mp4 pnpm --dir video poster # public/media/how-it-works-poster.jpg (title-card frame) pnpm --dir video studio # interactive preview pnpm --dir video render-captured # with video/inputs/take-*.mp4 present (§6) ``` `pnpm-workspace.yaml` gained `packages: [video]` so `pnpm install` inside `video/` resolves against this lockfile instead of walking up and ignoring the member. CI install behavior is unchanged (the deploy jobs install the workspace root's own dependencies; `video/` adds only dev-time weight locally). ## 4. Page and data plumbing - Route `/how-it-works`, lazy like the other non-LCP pages (`App.tsx`), page `src/pages/HowItWorksPage.tsx` (named export, default-mapped factory). - Manifest `src/data/pages/how-it-works.json`: claims `profile.name` (the footer renders it on every route) and owns the `howItWorks` UI group. Added to `pages.ts`, `MANIFEST_IDS` (validate.ts), `PageId`/`ManifestId` (types). - UI group 15: `howItWorks` — `heading`, `intro`, `videoAria`, `stepsTitle`, `steps[3]`, `chaptersTitle`, `chapters[6]` — in `src/i18n/locales/{vi,en}/ui/how-it-works.json`; registered in `i18n/index.ts` and `dict-types.ts` (`typeof` the VI file). - Nav: `/how-it-works` appended to `navPaths`; label key `how-it-works` in both `navigation.json` files. Sitemap picks the route up automatically from `navPaths`. - Bar width: seven links now share the bar above 1024px; `@media (max-width: 1240px)` drops the link gap 32→22px so the row never overflows near the breakpoint edge. Below 1024px the sheet owns navigation as before. - Player: `