7.9 KiB
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,
+faststartvia Remotion defaults. - Visual language mirrors the site's dark palette (
src/index.css:rootvalues copied intovideo/src/theme.ts— the project cannot import site CSS). - Timeline source of truth:
video/src/timeline.ts(SCENES). The chapter list in thehowItWorksUI group and both.vtttracks 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
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), pagesrc/pages/HowItWorksPage.tsx(named export, default-mapped factory). - Manifest
src/data/pages/how-it-works.json: claimsprofile.name(the footer renders it on every route) and owns thehowItWorksUI group. Added topages.ts,MANIFEST_IDS(validate.ts),PageId/ManifestId(types). - UI group 15:
howItWorks—heading,intro,videoAria,stepsTitle,steps[3],chaptersTitle,chapters[6]— insrc/i18n/locales/{vi,en}/ui/how-it-works.json; registered ini18n/index.tsanddict-types.ts(typeofthe VI file). - Nav:
/how-it-worksappended tonavPaths; label keyhow-it-worksin bothnavigation.jsonfiles. Sitemap picks the route up automatically fromnavPaths. - 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-chipinsrc/App.css; card text follows the typography tokens (--text-metabody, chrome-only 13px mono time). .gitignore:video/inputs/*.mp4— raw Screenity takes are local; the rendered MP4 is the committed artifact.
5. Acceptance criteria
pnpm buildgreen:tsc -b, vite (HowItWorksPage is its own 2.08 kB chunk), sitemap 9 URLs including/how-it-workspnpm validate:contentgreen (manifest rules cover the new manifest and group)pnpm lintadds no new warnings (video project type-checks with its own tsconfig and lints clean)pnpm --dir video renderproducespublic/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
.vtttrack. A fully VI-typed video would mean a second composition or a language prop — not built.