diff --git a/docs/design/specs/v7/spec-v7-intro-video.md b/docs/design/specs/v7/spec-v7-intro-video.md index 11de78b..aa5db6f 100644 --- a/docs/design/specs/v7/spec-v7-intro-video.md +++ b/docs/design/specs/v7/spec-v7-intro-video.md @@ -18,20 +18,20 @@ Decisions (owner-approved 2026-10-28): `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. +- 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–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."| +|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), 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. +**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 @@ -65,7 +65,7 @@ pnpm --dir video render-captured # with video/inputs/take-*.mp4 present (§6) ## 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. +`video/captured.json` + `--propsFile` flips the LiveEdit and Pipeline stages from animated mocks to real screen recordings (`video/inputs/take-edit.mp4` ≥24 s, `take-pipeline.mp4` ≥17 s — each take must cover its now-longer stage; 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 diff --git a/public/media/how-it-works.en.vtt b/public/media/how-it-works.en.vtt index 7e2ccc9..11fdb75 100644 --- a/public/media/how-it-works.en.vtt +++ b/public/media/how-it-works.en.vtt @@ -3,17 +3,17 @@ WEBVTT 00:00:00.000 --> 00:00:05.400 This site's CMS is a git repository. -00:00:05.500 --> 00:00:13.900 +00:00:05.500 --> 00:00:19.400 Everything the site shows is a JSON document: structure documents, per-language dictionaries and field manifests — joined once at build time. -00:00:14.000 --> 00:00:31.900 +00:00:19.500 --> 00:00:42.700 ?edit turns the live site into the editor. HTTP Basic at the nginx proxy is the only gate; every save is a commit through the GitHub Contents API. -00:00:32.000 --> 00:00:42.900 +00:00:42.800 --> 00:00:56.700 Content lives as JSON in the repository: branches are previews, and merging to master publishes. -00:00:43.000 --> 00:00:54.900 +00:00:56.800 --> 00:01:13.700 Merging to master runs the GitHub Actions pipeline — build, resume PDFs, deploy — from commit to live in minutes. -00:00:55.000 --> 00:01:02.000 +00:01:13.800 --> 00:01:20.800 Edit on the live site. Stored in git. Live on merge to master. diff --git a/public/media/how-it-works.mp4 b/public/media/how-it-works.mp4 index fce60c3..a75a194 100644 Binary files a/public/media/how-it-works.mp4 and b/public/media/how-it-works.mp4 differ diff --git a/public/media/how-it-works.vi.vtt b/public/media/how-it-works.vi.vtt index ef1980b..12ccc81 100644 --- a/public/media/how-it-works.vi.vtt +++ b/public/media/how-it-works.vi.vtt @@ -3,17 +3,17 @@ WEBVTT 00:00:00.000 --> 00:00:05.400 Hệ thống quản trị nội dung của trang này chính là một repository git. -00:00:05.500 --> 00:00:13.900 +00:00:05.500 --> 00:00:19.400 Mọi thứ trang hiển thị đều là tài liệu JSON: cấu trúc, từ điển theo từng ngôn ngữ và manifest trường — ghép một lần lúc build. -00:00:14.000 --> 00:00:31.900 +00:00:19.500 --> 00:00:42.700 ?edit biến chính trang đang xem thành trình soạn thảo. HTTP Basic ở nginx là cánh cửa duy nhất; mỗi lần lưu là một commit qua GitHub Contents API. -00:00:32.000 --> 00:00:42.900 +00:00:42.800 --> 00:00:56.700 Nội dung nằm trong repository dưới dạng JSON: nhánh là bản xem trước, merge vào master là công bố. -00:00:43.000 --> 00:00:54.900 +00:00:56.800 --> 00:01:13.700 Merge vào master chạy pipeline GitHub Actions — build, tạo resume PDF, triển khai — từ commit đến khi live chỉ vài phút. -00:00:55.000 --> 00:01:02.000 +00:01:13.800 --> 00:01:20.800 Sửa ngay trên trang thật. Lưu trong git. Live khi merge vào master. diff --git a/src/i18n/locales/en/ui/how-it-works.json b/src/i18n/locales/en/ui/how-it-works.json index db30607..73d28a4 100644 --- a/src/i18n/locales/en/ui/how-it-works.json +++ b/src/i18n/locales/en/ui/how-it-works.json @@ -21,9 +21,9 @@ "chapters": [ { "time": "0:00", "label": "Intro" }, { "time": "0:05", "label": "Content as documents" }, - { "time": "0:14", "label": "Live editing" }, - { "time": "0:32", "label": "Git as the content store" }, - { "time": "0:43", "label": "Automatic deployment" }, - { "time": "0:55", "label": "Closing" } + { "time": "0:19", "label": "Live editing" }, + { "time": "0:42", "label": "Git as the content store" }, + { "time": "0:56", "label": "Automatic deployment" }, + { "time": "1:13", "label": "Closing" } ] } diff --git a/src/i18n/locales/vi/ui/how-it-works.json b/src/i18n/locales/vi/ui/how-it-works.json index eaf1a25..77cde19 100644 --- a/src/i18n/locales/vi/ui/how-it-works.json +++ b/src/i18n/locales/vi/ui/how-it-works.json @@ -21,9 +21,9 @@ "chapters": [ { "time": "0:00", "label": "Giới thiệu" }, { "time": "0:05", "label": "Nội dung là tài liệu JSON" }, - { "time": "0:14", "label": "Chỉnh sửa trực tiếp" }, - { "time": "0:32", "label": "Git là kho nội dung" }, - { "time": "0:43", "label": "Triển khai tự động" }, - { "time": "0:55", "label": "Kết" } + { "time": "0:19", "label": "Chỉnh sửa trực tiếp" }, + { "time": "0:42", "label": "Git là kho nội dung" }, + { "time": "0:56", "label": "Triển khai tự động" }, + { "time": "1:13", "label": "Kết" } ] } diff --git a/video/README.md b/video/README.md index 1a728e8..da6e48b 100644 --- a/video/README.md +++ b/video/README.md @@ -22,8 +22,8 @@ screen recorder: | File (drop into `video/inputs/`) | Beat | Minimum length | |---|---|---| -| `take-edit.mp4` | open the live site → append `?edit` → Basic-auth sign-in → edit one heading inline → Save | 18 s | -| `take-pipeline.mp4` | GitHub Actions run: build → generate-resume → deploy, then the updated live page | 12 s | +| `take-edit.mp4` | open the live site → append `?edit` → Basic-auth sign-in → edit one heading inline → Save | 24 s | +| `take-pipeline.mp4` | GitHub Actions run: build → generate-resume → deploy, then the updated live page | 17 s | Record at 1920×1080, browser zoom 100%, dark theme. Trim so each take starts clean (no cursor scrubbing). Then: @@ -34,8 +34,10 @@ pnpm --dir video render-captured Raw takes are gitignored — the rendered MP4 is the committed artifact. -## Timeline (source of truth: `src/Explainer.tsx`) +## Timeline (source of truth: `src/timeline.ts`) -30 fps · 1860 frames · 62 s. Scene boundaries drive the chapter list and the -`.vtt` caption tracks in `public/media/` — if the timeline changes, those and -the `howItWorks` UI group's chapters must change with it. +30 fps · 2425 frames · 81 s. Scene durations include ≥5 s of hold time after +the last callout so every on-screen explanation is readable before the cut. +Scene boundaries drive the chapter list and the `.vtt` caption tracks in +`public/media/` — if the timeline changes, those and the `howItWorks` UI +group's chapters (EN + VI) must change with it. diff --git a/video/src/kit.tsx b/video/src/kit.tsx index 2eed652..220dba5 100644 --- a/video/src/kit.tsx +++ b/video/src/kit.tsx @@ -1,6 +1,6 @@ import React from 'react'; import { useCurrentFrame } from 'remotion'; -import { appear } from './motion'; +import { appear, drawIn } from './motion'; import { theme } from './theme'; export const Fade: React.FC<{ start: number; y?: number; children: React.ReactNode }> = ({ @@ -15,36 +15,73 @@ export const Fade: React.FC<{ start: number; y?: number; children: React.ReactNo ); }; -export const SceneChrome: React.FC<{ - index: string; - title: string; - bullets: string[]; - bulletStart?: number; -}> = ({ index, title, bullets, bulletStart = 60 }) => ( - <> -
- -
{index}
-
- -
- {title} -
-
-
-
- {bullets.map((b, i) => ( - -
- ▸ - {b} -
-
- ))} -
- +export const SceneChrome: React.FC<{ index: string; title: string }> = ({ index, title }) => ( +
+ +
{index}
+
+ +
+ {title} +
+
+
); +// A callout that points at a diagram element: the leader line draws only after +// the target has appeared, and the chip only after the line completes — the +// scene's explanations therefore follow the diagram beat by beat instead of +// sitting in a fixed text row. `target` is the anchor on the element, `anchor` +// the chip-side end of the line. +export const Callout: React.FC<{ + target: [number, number]; + anchor: [number, number]; + chip: { x: number; y: number; width: number }; + start: number; + accent?: boolean; + children: string; +}> = ({ target, anchor, chip, start, accent, children }) => { + const frame = useCurrentFrame(); + const line = drawIn(frame, start, 12); + const chipOn = appear(frame, start + 12); + return ( + <> + + + +
+ {children} +
+ + ); +}; + export const Panel: React.FC<{ width: number; accent?: boolean; diff --git a/video/src/scenes/DataLayer.tsx b/video/src/scenes/DataLayer.tsx index 2c0b5ca..5b81f53 100644 --- a/video/src/scenes/DataLayer.tsx +++ b/video/src/scenes/DataLayer.tsx @@ -1,6 +1,6 @@ import React from 'react'; import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion'; -import { ArrowDefs, BrowserFrame, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit'; +import { ArrowDefs, BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit'; import { appear, drawIn } from '../motion'; import { theme } from '../theme'; @@ -22,16 +22,7 @@ export const DataLayer: React.FC = () => { return ( - + {DOCS.map((d, i) => ( @@ -112,6 +103,25 @@ export const DataLayer: React.FC = () => {
+ + + Field manifests claim every field a page renders — a missing key fails the build, never a silent half-render. + + + + EN and VI render through the same components — the join happened once, at build time. + ); }; diff --git a/video/src/scenes/GitStorage.tsx b/video/src/scenes/GitStorage.tsx index a4f6326..1cd6c5f 100644 --- a/video/src/scenes/GitStorage.tsx +++ b/video/src/scenes/GitStorage.tsx @@ -1,6 +1,6 @@ import React from 'react'; import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion'; -import { ArrowDefs, Fade, Label, Mono, Panel, SceneBackground, SceneChrome } from '../kit'; +import { ArrowDefs, Callout, Fade, Label, Mono, Panel, SceneBackground, SceneChrome } from '../kit'; import { appear, drawIn } from '../motion'; import { theme } from '../theme'; @@ -25,16 +25,7 @@ export const GitStorage: React.FC = () => { return ( - +
@@ -129,6 +120,34 @@ export const GitStorage: React.FC = () => {
+ + + Content is plain JSON documents in the repository — no database, no admin panel. + + + + Drafts live on a branch — ?edit=preview opens the same site on that branch. + + + + History, review and rollback come from git, free of charge. +
); }; diff --git a/video/src/scenes/LiveEdit.tsx b/video/src/scenes/LiveEdit.tsx index bcbae0d..596997b 100644 --- a/video/src/scenes/LiveEdit.tsx +++ b/video/src/scenes/LiveEdit.tsx @@ -1,6 +1,6 @@ import React from 'react'; import { AbsoluteFill, OffthreadVideo, staticFile, useCurrentFrame } from 'remotion'; -import { BrowserFrame, Fade, Label, Mono, PageSkeleton, SceneBackground, SceneChrome } from '../kit'; +import { BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, SceneBackground, SceneChrome } from '../kit'; import { appear, typed } from '../motion'; import { theme } from '../theme'; @@ -46,17 +46,7 @@ export const LiveEdit: React.FC<{ captured: boolean }> = ({ captured }) => { return ( - + = ({ captured }) => { )} + + + ?edit attaches edit mode — the very page being viewed becomes the editor. + + + + HTTP Basic at the nginx proxy is the only gate — the site itself carries no accounts system. + + + + Text, tags, records and settings edit inline — pencil-triggered, commit on blur, Vietnamese-IME safe. + + + + Every save is a commit through the GitHub Contents API; a 409 conflict three-way rebases and keeps your edit. + ); }; diff --git a/video/src/scenes/Pipeline.tsx b/video/src/scenes/Pipeline.tsx index b2043bd..a73242d 100644 --- a/video/src/scenes/Pipeline.tsx +++ b/video/src/scenes/Pipeline.tsx @@ -1,6 +1,6 @@ import React from 'react'; import { AbsoluteFill, OffthreadVideo, staticFile, useCurrentFrame } from 'remotion'; -import { ArrowDefs, BrowserFrame, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit'; +import { ArrowDefs, BrowserFrame, Callout, Fade, Label, Mono, PageSkeleton, Panel, SceneBackground, SceneChrome } from '../kit'; import { appear, drawIn } from '../motion'; import { theme } from '../theme'; @@ -29,16 +29,7 @@ export const Pipeline: React.FC<{ captured: boolean }> = ({ captured }) => { return ( - + @@ -129,6 +120,25 @@ export const Pipeline: React.FC<{ captured: boolean }> = ({ captured }) => { )} + + + No CMS, no manual upload — the push to master is the publish button. + + + + From commit to live in minutes — the updated page is the receipt. + ); }; diff --git a/video/src/timeline.ts b/video/src/timeline.ts index 28627dc..48cb0d1 100644 --- a/video/src/timeline.ts +++ b/video/src/timeline.ts @@ -8,13 +8,16 @@ export type ExplainerProps = z.infer; // Scene timeline (30 fps). These boundaries are the source of truth for the // chapter list and the .vtt caption tracks on the site page. +// Dwell rule: every callout chip stays on screen at least 150 frames (5 s) +// before its scene switches — a ~25-word chip needs a calm read, not a glance. +// Scene beats are unchanged; the added frames are hold time at the end. export const SCENES = [ { id: 'title', from: 0, duration: 165 }, - { id: 'data', from: 165, duration: 255 }, - { id: 'edit', from: 420, duration: 540 }, - { id: 'git', from: 960, duration: 330 }, - { id: 'pipeline', from: 1290, duration: 360 }, - { id: 'outro', from: 1650, duration: 210 }, + { id: 'data', from: 165, duration: 420 }, + { id: 'edit', from: 585, duration: 700 }, + { id: 'git', from: 1285, duration: 420 }, + { id: 'pipeline', from: 1705, duration: 510 }, + { id: 'outro', from: 2215, duration: 210 }, ] as const; -export const TOTAL_FRAMES = 1860; +export const TOTAL_FRAMES = 2425;