Files
cv/docs/design/specs/v7/spec-v7-intro-video.md
T

74 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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, 1860 frames = **62 s**, H.264 CRF 23 → 1.5 MB, `+faststart` via Remotion defaults.
- 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–420|5.5–14|Structure documents + per-language dictionaries + manifests → joined once at build time → bilingual rendered page|
|LiveEdit|420–960|14–32|`?edit` typed into the URL → Basic-auth dialog → inline heading edit → save bar: PUT contents/projects.json, commit on branch, 409 → three-way rebase|
|GitStorage|960–1290|32–43|Repository file tree with the edited JSON highlighted, commit diff card, master/preview-branch graph, `?edit=preview`, merge = publish|
|Pipeline|1290–1650|43–55|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|
|Outro|1650–1860|55–62|"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), bullet row y 790+ (left). 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: `<video controls playsInline preload="none" poster>` + `<track kind="captions">` chosen by the active language (`useLanguage().lang`); chapter chips seek the player. `preload="none"` keeps the video out of the page's LCP path — only the 16:9 box and poster paint with the page.
- CSS: `.how-it-works-video`, `.how-it-works-grid` (3→2→1 columns like the other card grids), `.how-it-works-card`, `.chapter-chip` in `src/App.css`; card text follows the typography tokens (`--text-meta` body, chrome-only 13px mono time).
- `.gitignore`: `video/inputs/*.mp4` — raw Screenity takes are local; the rendered MP4 is the committed artifact.
## 5. Acceptance criteria
- [x] `pnpm build` green: `tsc -b`, vite (HowItWorksPage is its own 2.08 kB chunk), sitemap 9 URLs including `/how-it-works`
- [x] `pnpm validate:content` green (manifest rules cover the new manifest and group)
- [x] `pnpm lint` adds no new warnings (video project type-checks with its own tsconfig and lints clean)
- [x] `pnpm --dir video render` produces `public/media/how-it-works.mp4` (1.5 MB) + poster; poster frame visually verified
- [ ] Browser walkthrough — owner verifies in a real browser (project rule 5)
## 6. Captured variant (open, owner-side)
`video/captured.json` + `--propsFile` flips the LiveEdit and Pipeline stages from animated mocks to real screen recordings (`video/inputs/take-edit.mp4` ≥18 s, `take-pipeline.mp4` ≥12 s; recording instructions in `video/README.md`). The composition is complete; only the two takes are owner-supplied raw material. Re-render afterwards and commit the new MP4.
## 7. Known limits
- The MP4 (1.5 MB) is committed like the resume assets; it deploys with `dist/` through the existing pipeline — no pipeline change was needed.
- On-screen video text is English; the VI experience is the `.vtt` track. A fully VI-typed video would mean a second composition or a language prop — not built.