mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
feat: intro video + /how-it-works page (spec-v7) — Remotion video/ project (62s explainer, centered scene composition), self-hosted MP4 + poster + EN/VI VTT, lazy page + manifest + UI group 15 + nav entry, spec-v7 + AGENTS updates
This commit is contained in:
1 parent
9124f569fb
commit
7bb7bd68ae
42 files changed
+4039
-17
No files matched your search
@@ -15,6 +15,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
||||
| Animation | motion ^14.0.0 (`motion/react` ESM entrypoint) |
|
||||
| Linter | Oxlint 1 (`plugins: react, typescript, oxc`) |
|
||||
| Resume generation | playwright ^1.64.0, tsx ^4.23.15 |
|
||||
| Video rendering | Remotion ^4 — standalone workspace member `video/`; the SPA never imports it |
|
||||
| Package manager | pnpm |
|
||||
|
||||
## Commands
|
||||
@@ -30,6 +31,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
||||
| `pnpm generate:ids` | Regenerate `src/types/content-ids.ts` from the structure documents (also run by `predev` / `prebuild` / `prepare`) |
|
||||
| `pnpm sitemap` | Regenerate `dist/sitemap.xml` + `dist/robots.txt` on its own (also run by `pnpm build`) |
|
||||
| `pnpm preview` | Preview production build locally |
|
||||
| `pnpm --dir video render` | Render the `/how-it-works` intro video → `public/media/how-it-works.mp4` (standalone Remotion project in `video/`, spec-v7) |
|
||||
|
||||
## Routing
|
||||
|
||||
@@ -37,7 +39,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
||||
- Layout: `<Navigation>` (top) → `<main id="main-content">` → `<Footer>` (bottom)
|
||||
- All internal navigation MUST use `<Link>`/`<NavLink>`, never `<a href>` (causes full page reload)
|
||||
- Footer internal links also use `<Link>`; external links (GitHub, LinkedIn, email) keep `<a>` with `target="_blank"`
|
||||
- Route-level splitting: `HomePage` is imported eagerly because it owns the LCP; the other six pages load through `React.lazy` inside one `<Suspense fallback={null}>` boundary in `App.tsx`. Pages export named components, so each factory maps the named export to `default`
|
||||
- Route-level splitting: `HomePage` is imported eagerly because it owns the LCP; the other seven pages load through `React.lazy` inside one `<Suspense fallback={null}>` boundary in `App.tsx`. Pages export named components, so each factory maps the named export to `default`
|
||||
|
||||
## Pages
|
||||
|
||||
@@ -50,6 +52,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
||||
| `/projects/:id` | `ProjectDetailPage` | Single project |
|
||||
| `/contact` | `ContactPage` | Contact info |
|
||||
| `/philosophy` | `PhilosophyPage` | Engineering philosophy |
|
||||
| `/how-it-works` | `HowItWorksPage` | Intro video: git-backed content, live editing, CI deploy |
|
||||
|
||||
## Theming
|
||||
|
||||
@@ -74,20 +77,20 @@ Content is split once, at authoring time, into language-neutral **structure docu
|
||||
- `src/data/skills.json` + `skills.ts` loader — skill groups: `{id, skills}`; group titles are text
|
||||
- `src/data/experience.json` + `experience.ts` loader — work history: id / location / logo / optional `variant: 'current' | 'gap'` (timeline decoration: live node / career break); company, duration, titles and responsibilities are text — the VI document carries localized dates ("11/2026 – nay") and company labels, en overrides with the originals, proper nouns identical per language
|
||||
- `src/data/projects.json` + `projects.ts` loader — cards: category / technologies / featured / `sections[].{id, type}`; titles, summaries, role, metrics and section prose are text (role follows the owner's EN title convention; metrics are localized)
|
||||
- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy.<id>.{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 14 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `resume`, `edit`, `common`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission
|
||||
- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy.<id>.{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 15 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `howItWorks`, `resume`, `edit`, `common`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission
|
||||
- Content ids and the category values a project uses are **generated**, never hand-maintained (spec: `docs/design/specs/v5/spec-v5-generated-content-ids.md`): `scripts/generate-content-types.ts` reads the four structure documents and writes `src/types/content-ids.ts` (gitignored) under `predev` / `prebuild` / `prepare`; `src/types/index.ts` re-exports those unions type-only and keeps only the code-owned ones (`Language`, `Palette`, `SocialId`, `PageId`, manifest types). A content add or delete touches JSON only — a text entry left behind by a deleted record is a `tsc` error (`TS2741`), never a stale union member — and a category with no label in either language is a validator error naming both `ui/projects.json` files (rule 7)
|
||||
- `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id`
|
||||
- `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,how-it-works,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id`
|
||||
- `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record<Language, Resolved…>`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values, the manifest rules above) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render
|
||||
- `src/i18n/provider.tsx` — `I18nProvider` wraps the app; components consume `const { ui: s, content: c } = useI18n()`: `s` is the chrome of the current language, `c` the joined records (`c.profile`, `c.skillGroups`, `c.experiences`, `c.projects`). There is no `field()` and no `*En` field pair anymore
|
||||
- Translation is a JSON edit, never a component edit; a new language is a new locale directory plus one `Language` union member
|
||||
- `src/data/resume.ts` — resume availability, supported languages, URL generation, and `resumeQr` (the `{id, file, label}` descriptors the resume header renders as QR codes)
|
||||
- `src/data/navigation.ts` — `navPaths` (bar + sheet order: Home, About, Experience, Projects, Contact, Philosophy), `footerPaths`
|
||||
- `src/data/navigation.ts` — `navPaths` (bar + sheet order: Home, About, Experience, Projects, Contact, Philosophy, How it works), `footerPaths`
|
||||
- `src/data/social.ts` — social tiles as `{id, href, external}` (github, linkedin, email, telegram); `email` is a `mailto:` link with `external: false`, so it renders no `target`/`rel`
|
||||
- `src/data/palettes.ts`, `src/data/site.ts` — code config, not content: `siteUrl` (the canonical origin) and `siteName` are read from the environment (`SITE_URL` / `SITE_NAME` — CI variables in production, the uncommitted local `.env` in development; unset → the build fails with an error naming the variable); every absolute URL the site publishes — canonical, Open Graph, JSON-LD, `robots.txt`, `sitemap.xml` — derives from it
|
||||
|
||||
## Live Edit Mode (`?edit`, v4)
|
||||
|
||||
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, reads the live branch documents the current route needs (see the next bullet), and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview
|
||||
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, reads the live branch documents the current route needs (see the next bullet), and re-wraps the tree in an `I18nProvider` override — the eight routes ARE the preview
|
||||
|
||||
- Document scope (`src/i18n/edit-scope.ts`): the documents a session reads come from the page manifests, never from component code — a claim names a joined record, and an entity owns its structure document plus its two text documents, which are always read as one unit (a half-loaded entity would make the validator compare a live document against a bundled one). Entry = the entry route's scope plus anything a restored draft already touched (those need a real blob sha). A route change reads only the documents still missing — each is adopted through `DraftStore.adoptBase`, which refuses a document the draft has already changed — and the category labels only where a project renders. A document still on its bundled baseline is never PUT over the branch: `saveDraft` sees the empty sha, reads the branch, and hands it to the conflict flow. The bundled copy stays the offline fallback, never a silent substitute for a live read
|
||||
- Target branch (spec D10): `?edit=<branch>` reads (`?ref=`) and writes (`branch` in the PUT body) that branch; a bare `?edit` resumes the session's last branch, default `master`. Names are validated against git ref rules in `src/i18n/edit-session.ts` before any request (illegal → exit like a failed auth); the branch is stored beside the session flag. The target branch must already exist — Contents API updates never create branches. Only `master` deploys, so the EditBar shows a merge hint on other branches. `master` carries **no branch protection**: a required-PR rule would refuse the edit-mode PUT (spec-v6 D7)
|
||||
@@ -108,12 +111,17 @@ src/
|
||||
sections/ — Hero, About, Expertise, Experience, Projects, Contact, HeroParticles, DownloadResume (the hero lazer CTA; it gates itself on `resumeAvailable`)
|
||||
ui/ — Badge, Button, ContactLinks, LanguageIcon, ResumeDialog, SectionHeading, SocialLinks, Tag, Typewriter, InView, RollingTextLink, BackToTop, EditableText, TagListEditor, RecordControls, RecordSettings, icons
|
||||
data/ — profile, skills, experience, projects (JSON documents + typed loaders), pages (manifest JSON + pages.ts loader), resume, palettes, navigation, social, site (TS modules)
|
||||
i18n/ — index.ts (loader), dict-types.ts, validate.ts, provider.tsx, draft.ts (DraftStore + save pipeline), edit-scope.ts (manifest-derived read scope), edit-session.ts (`?edit`/flag/branch state, dependency-free), edit-mode.ts (Basic-auth probe), locales/{vi,en}/content/{profile,skills,experience,projects}.json + ui/{group}.json (14 chrome groups)
|
||||
i18n/ — index.ts (loader), dict-types.ts, validate.ts, provider.tsx, draft.ts (DraftStore + save pipeline), edit-scope.ts (manifest-derived read scope), edit-session.ts (`?edit`/flag/branch state, dependency-free), edit-mode.ts (Basic-auth probe), locales/{vi,en}/content/{profile,skills,experience,projects}.json + ui/{group}.json (15 chrome groups)
|
||||
hooks/ — useTheme.tsx, useLanguage.tsx, useClickOutside.ts, useResumeDialog.ts, useEdit.ts (edit context)
|
||||
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage
|
||||
pages/ — HomePage, AboutPage, ExperiencePage, ProjectsListPage, ProjectDetailPage, PhilosophyPage, ContactPage, HowItWorksPage
|
||||
types/ — shared TypeScript interfaces; content-ids.ts (generated id unions, gitignored)
|
||||
```
|
||||
|
||||
```
|
||||
video/ # standalone Remotion project (spec-v7-intro-video), a pnpm workspace member — renders public/media/*; never imported by the SPA
|
||||
└── src/ — index.ts, Root.tsx, Explainer.tsx, timeline.ts (the scene boundaries — source of truth for the chapters + .vtt), kit.tsx, motion.ts, theme.ts, scenes/{Title,DataLayer,LiveEdit,GitStorage,Pipeline,Outro}.tsx
|
||||
```
|
||||
|
||||
## Motion & Animation
|
||||
|
||||
- `motion/react` v14 — ESM-first entrypoint (NOT `framer-motion`)
|
||||
@@ -128,6 +136,7 @@ src/
|
||||
|
||||
## External Assets
|
||||
|
||||
- `public/media/` — the `/how-it-works` intro video: `how-it-works.mp4`, `how-it-works-poster.jpg`, `how-it-works.{en,vi}.vtt` — generated by `pnpm --dir video render` / `poster`, committed like the resume assets, served with the static build
|
||||
- `public/fonts/` — Source Sans 3 woff2 (Regular, Medium, Semibold, Bold); used by the resume generator only — the SPA renders `system-ui`
|
||||
- `public/resume-template.html` — HTML template for resume PDF generation
|
||||
- `public/resume-logos/` — official company logo SVGs (Lazada, SAP from Wikimedia Commons), embedded in the resume timeline via `ExperienceEntry.logo`
|
||||
@@ -195,6 +204,7 @@ compose.override.yaml
|
||||
6. **`lazy()` needs a default export:** pages export named components, so each factory must map `{ default: m.XPage }` — a bare `import('@/pages/XPage')` fails `tsc` with `TS2322: Property 'default' is missing`. There is no `src/pages/index.ts` barrel: importing it would pull every route back into the entry chunk
|
||||
7. **A locked `dist/resume*.pdf` blocks the build:** while a generated PDF is open in a viewer, `pnpm build:resume-all` fails with `EBUSY` on that file and `pnpm build` fails too (vite `emptyDir` → `EPERM`). Close the viewer first
|
||||
8. **`src/types/content-ids.ts` is generated, not committed:** a fresh checkout has no id unions until a script writes them. `pnpm install` (`prepare`) or `pnpm dev` (`predev`) creates it; before that the IDE reports `Cannot find module './content-ids'`, and `pnpm generate:ids` is the one-off fix. Editing it by hand is pointless — the next `prebuild` overwrites it
|
||||
9. **The video timeline is a four-way contract:** `video/src/timeline.ts` scene boundaries, the `howItWorks.chapters` entries in both `ui/how-it-works.json`, and both `public/media/how-it-works.*.vtt` must match. Change the timeline → re-render, re-cut the captions, update the chapters in the same commit (spec-v7 §2)
|
||||
|
||||
## Design Specs
|
||||
|
||||
@@ -210,6 +220,7 @@ All specification documents are in `docs/design/`:
|
||||
| `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, palette reference, UI enhancements, mobile navigation, nav & CTA enhancements, nav swatch & hamburger, typography, i18n, resume improvements, resume redesign, review fixes) |
|
||||
| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending |
|
||||
| `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 |
|
||||
|`specs/v7/spec-v7-*.md`|v7 feature specs. `spec-v7-intro-video.md`: the 62-second Remotion-rendered explainer (`video/` workspace member → `public/media/`) shown on the new `/how-it-works` page — route, manifest, `howItWorks` UI group, EN/VI caption tracks, chapter seeking; the optional captured-footage variant awaits owner screen recordings — implemented 2026-10-28 (automated checks pass; browser walkthrough pending)|
|
||||
|`specs/v6/spec-v6-*.md`|v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline, and the Basic-auth file leaves the repository — `deploy/htpasswd` is gitignored, the infra job writes it on the VPS from the `HTPASSWD_CONTENT` repository secret (D16, 2026-10-28) — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1|
|
||||
|
||||
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
||||
|
||||
Reference in new issue
Block a user