perf(edit): read only the documents the current route needs

Edit-mode document scope comes from the page manifests (src/i18n/edit-scope.ts): an entity's structure document and its two text documents are read as one unit, the category labels only where a project renders. A route change fetches only the still-missing documents and adopts them through DraftStore.adoptBase, which refuses a document the draft has already changed. A bundle-seeded baseline is never PUT over the branch: saveDraft reads the branch first and reports a conflict. Every manifest now claims profile.name, which the footer renders on every route.
This commit is contained in:
dong.nguyen committed 2026-10-24 15:24:08 +07:00
1 parent ee1d524bd0
commit 5c71b52d81
13 files changed
+320 -71

No files matched your search

@@ -96,6 +96,7 @@ The current `ui.json` namespaces map 1:1 onto groups; the split is mechanical. O
- `entity` uses the §3 entity ids; `fields` are paths into the joined text/structure records; `"*"` claims the whole entity.
- `ui` lists **page-owned** groups only. Component-owned groups (`navigation`, `footer`, `social`, `common`, `resume`, `edit`) are owned by the component side and provenance for them is the component mapping in §4 — they are not repeated in every manifest.
- Manifests are language-neutral (which data a page shows is not a translation fact). They are structure-side data: part of validation, committed like structure documents, **read-only in the app** (`spec-v4-inline-editing.md` §3) — edited as repo files by the developer.
- A manifest describes the whole page, **chrome included**: the footer renders `profile.name` on every route, so every manifest claims it. Component-owned *UI* groups stay out of the manifest (previous bullet — chrome labels have no entity provenance to name), but a content field a page renders through its chrome is still that page's claim. This is what makes the manifest usable as the edit-mode read scope (spec-v4-live-edit §5.2, row 26): a session reads exactly the documents the current route's manifest claims, so a page cannot be served a document it does not describe.
Initial content mapping — derived from the code scan of every consumer (2026-10-23), to be re-derived exactly at implementation:
@@ -103,11 +104,11 @@ Initial content mapping — derived from the code scan of every consumer (2026-1
|---|---|---|---|---|
| `home` | `name`, `tagline`, `roles`, `bio`, `currentInterests`, `philosophy`, `tldr`, links (`email`, handles) | `*` (Expertise) | `*` (timeline) | featured subset: `title`, `summary`, `metrics` |
| `about` | `name`, `bio`, `subtitle`, `currentInterests`, `philosophy` | `*` | — | — |
| `experience` | `tldr` | — | `*` | — |
| `projects` | — | — | — | `*`: `title`, `summary`, `metrics` |
| `project-detail` | — | — | — | per-id: `title`, `summary`, `role`, `metrics`, `sections.*` |
| `contact` | links (`email`, handles) | — | — | — |
| `philosophy` | `philosophyQuotes` | — | — | — |
| `experience` | `tldr`, `name` (footer) | — | `*` | — |
| `projects` | `name` (footer) | — | — | `*`: `title`, `summary`, `metrics` |
| `project-detail` | `name` (footer) | — | — | per-id: `title`, `summary`, `role`, `metrics`, `sections.*` |
| `contact` | links (`email`, handles), `name` (footer) | — | — | — |
| `philosophy` | `philosophyQuotes`, `name` (footer) | — | — | — |
| `resume` (synthetic) | `name`, `title`, `bio`, `email`, links | `*` | `*` | `*` |
`home` does **not** claim `title` — the code scan shows Hero renders `name`/`roles`/`tagline` only; `title` is consumed by the resume generator, which the synthetic manifest now covers honestly.
@@ -159,4 +160,5 @@ Order decided 2026-10-23: this spec lands **after** `spec-v4-inline-editing.md`
|---|---|---|
| 0 | Design agreed (D1–D5) | ✅ Done 2026-10-23 |
| 1–6 | Implementation steps §7 | ✅ Done 2026-10-23 — content split (4 files × 2 languages) + UI split (14 groups × 2) with merge asserted in `index.ts`; `src/data/pages/*.json` (8 manifests) + `pages.ts` + `PageId`/`PageManifestClaim`/`PageManifest` in `src/types/index.ts`; validator rules 1–4 in `validate.ts` (run at load and by `validate:content`); `draft.ts` registry data-driven over 12 writable documents (4 structure + 8 text, `entityOfDoc`/`docEntityMap` exported for provenance + EditBar); `describeField()` names the per-entity file automatically; EditBar "appears on" annotations via `manifestsClaiming`/`recordEntity`; AGENTS.md Data Layer + Live Edit Mode + Component Structure updated |
| 7 | Manifests describe the whole page, chrome included: every manifest claims `profile.name`, because the footer renders it on every route — the same claim set is the edit-mode read scope (spec-v4-live-edit §5.2, row 26) | ✅ Done 2026-10-24 — `projects.json` and `project-detail.json` gained a `profile: ["name"]` claim, `contact` / `experience` / `philosophy` gained `name` in their existing claim; the rule is stated in `pages.ts`'s header. Verified: `pnpm validate:content`, `tsc -b`, `pnpm build`, and the scope probe over all 7 routes (evidence in live-edit row 26) |
| — | Acceptance §8 | 🟡 Automated rows verified 2026-10-23 (see §8 checkboxes); browser rows open — the owner verifies in a real browser |
+4 -1
View File
@@ -362,6 +362,8 @@ stateDiagram-v2
- **Durability:** every accepted edit is also copied to `sessionStorage` (the documents are tens of KB). An accidental reload restores the draft: the app re-fetches live files, re-applies the saved draft, and flags any document whose blob `sha` moved → conflict flow (§5.6). SPA navigation never loses the draft; `beforeunload` warns while dirty.
- **Mode persistence (row 24, owner request 2026-10-24):** the mode is a session state, not a URL state. `MaybeEditMode` mounts the shell on `?edit` **or** on the session flag; while the shell is mounted a route change that dropped `?edit` gets it back through a replace-navigation, so the address keeps describing the mode the user is in and a reload reopens it. The session initializes once per mount — the entry URL is read from a ref, `stripEditQuery` reads the live URL — so navigation never re-authenticates, re-fetches, or re-restores the draft. Only Exit leaves; a failed auth or an illegal branch name clears the flag the same way, which unmounts the shell. The flag/query/branch helpers live in `src/i18n/edit-session.ts`, a module with no imports: `App.tsx` reads the gate from it without pulling the auth probe — and through it `draft.ts` — into the entry chunk.
- **Document scope (row 26, owner report 2026-10-24):** a session reads only the documents the page it is on needs. `src/i18n/edit-scope.ts` derives them from the page manifests: a claim names a joined record, an entity owns its structure document plus its two text documents, and those are always read as one unit — a half-loaded entity would make the cross-document 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 before any PUT). Navigation: an effect on the route reads only the documents still missing and the label documents only where a project renders; each is adopted with `DraftStore.adoptBase`, which refuses a document the draft has changed, so a late read never replaces work. A document still on its bundled baseline is never PUT over the branch — `saveDraft` sees the empty sha, reads the branch, and hands the document to the conflict flow (or reports a failure when the read itself fails). The bundled copy stays the offline fallback, never a silent substitute for a live read. Because a manifest describes the whole page including its chrome, every manifest claims `profile.name` (the footer renders it on every route); the EditBar's "appears on" annotation for that field reads identically.
### 5.3 `EditableText` contract (inline editing)
- **Visitor mode is transparent:** the component renders exactly the element the site renders today (same tag, same attributes, text as children). Zero DOM/CSS/motion difference outside edit mode.
@@ -417,7 +419,7 @@ v4 exposes no new layout knobs. `featured` and `variant` already exist and are e
Repo: `https://code.vugado.com/dong.nguyen/cv` — self-hosted Gitea (API verified live: `/api/v1/version` → 28.1.0). Contents API paths are fixed to this repo:
- `GET /api/v1/repos/dong.nguyen/cv/contents/{path}` — read the live file + its blob `sha` when a draft session starts (§5.1).
- `GET /api/v1/repos/dong.nguyen/cv/contents/{path}` — read the live file + its blob `sha` for the documents the session's route renders (§5.1, row 26), and again for the documents a later navigation first reaches.
- `PUT /api/v1/repos/dong.nguyen/cv/contents/{path}` — body: base64 content, `message`, `branch`, `sha` (the file's blob ID). Gitea 28 `UpdateFile` keys create-vs-update on this field: empty `sha` → create (an existing file answers 422 "repository file already exists"); a stale `sha` → 422 with a "does not match" message → editor refetches and re-applies; lost updates are impossible. *(Amended 2026-10-23 after the first real save against 28.1.0 — the text previously described the retired `last_commit_sha`/412 contract; `last_commit_sha` exists only in responses.)*
**Save/CI policy (decided):** a save writes its touched documents as **sequential PUTs to `master`** — each is one commit and triggers the existing pipeline. Consequences accepted: a save touching 2–4 documents produces 2–4 sequential CI runs, and between runs the deployed site can transiently mix old/new documents. For a single owner publishing at low frequency this is the boring, correct choice; the final state after the last pipeline is always consistent. (Branch-then-merge for a single pipeline run is noted as a future optimization, not v4.)
@@ -608,3 +610,4 @@ Deferred (not v4):
| 23 | Generated content ids ([`spec-v5-generated-content-ids.md`](../v5/spec-v5-generated-content-ids.md)): the id unions and the project category values are written from the structure documents by `scripts/generate-content-types.ts` (`predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages | 3 | ✅ Done 2026-10-24 (automated) — `scripts/generate-content-types.ts` + `generate:ids` / `predev` / `prebuild` / `prepare`, gitignored `src/types/content-ids.ts`, `src/types/index.ts` re-exports it type-only; row 22's machinery deleted (`draft.ts`, `EditModeShell.tsx`, `EditBar.tsx`, both `ui/edit.json`); rule 7 implemented and wired through the draft store, EditBar, `RecordSettings`, `TagListEditor`. Verified: `pnpm generate:ids` (777-byte module, byte-stable on a second run), `pnpm build` (10 chunks, names identical to a build of the same documents before the change, no runtime reference to the generated module), `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm tsx scripts/smoke-draft.ts` 11/11, `pnpm tsx scripts/smoke-generated-ids.ts` 7/7, `pnpm build:resume-all` (both PDFs; the rendered HTML byte-identical before/after with identical documents). ⬜ Browser: visitor routes unchanged, `?edit` add/delete round-trip with no union card, category-rejection banner |
| 24 | Edit mode survives navigation (owner request 2026-10-24): "if in edit mode, keep the mode when clicking any link; only Exit returns to normal mode" | 3 | ✅ Done 2026-10-24 (automated) — `src/i18n/edit-session.ts` (new, dependency-free): `?edit` parsing, the session flag, the branch flag and rules moved out of `edit-mode.ts`, which is now the Basic-auth handshake alone; `App.tsx` `MaybeEditMode` gates on `editRequested(search) \|\| hasEditFlag()`; `EditModeShell` re-attaches `edit` after a route change that dropped it (replace-navigation, skipped while authenticating so a failed auth is never fought) and its initialization no longer depends on `location.search` (entry URL from a ref, `stripEditQuery` reads `window.location`), so a navigation neither re-authenticates nor re-fetches nor re-restores the draft. `EditBar.tsx` imports `DEFAULT_BRANCH` from the new module. Verified: `tsc -b`, `pnpm build` (entry chunk carries no `probe` literal → the auth handshake stays lazy; `EditModeShell` is still a separate 10.5 kB chunk; the draft module's presence in the entry chunk is pre-existing, via `Hero → EditableText → draft`), `pnpm lint` (no new warnings), throwaway session-semantics smoke 17/17 — gate on query/flag, branch tri-state incl. `?edit=` and an illegal name, flag+branch cleared on exit, cached-credential auth across the new module boundary — deleted after the run. ⬜ Browser: `?edit` → click through Home/About/Experience/Projects/Contact/Philosophy → EditBar and the draft stay; reload reopens the session; Exit → clean URL, visitor site |
| 25 | Edit-mode initialization is one concurrent request wave (owner report 2026-10-24: opening edit mode fetched every document one after another) | 3 | ✅ Done 2026-10-24 (automated) — `EditModeShell.tsx` §5.1 initialization: the 12 draft documents and the 2 label files are issued as two concurrent `Promise.all` requests whose success/failure handlers are attached in the same tick they are created, so a label rejection landing while the documents are still in flight is not an unhandled rejection; the failure split is unchanged (a document failure is the offline state, a label failure only disables rule 7). Measured through the dev proxy, same transport as the app: 12 documents sequential 902 ms → 210 ms for the whole 14-request wave, 38 768 bytes and 12 distinct payloads byte-identical to the sequential loop. Verified: `tsc -b` 0, `pnpm lint` no new warnings, `pnpm build` OK, `smoke-draft.ts` 11/11, throwaway wave probe 6/6 (same bytes as the loop, both failure branches, both-success path, no unhandled rejection) — probe deleted. Paired infra half: `spec-v4-deploy-infra.md` D14 / row 10 — `/api/content/` now proxies to Gitea over HTTP/2, so the wave multiplexes over one pooled upstream connection instead of one HTTP/1.1 connection per in-flight request. ⬜ Browser: edit-mode load on the deployed site |
| 26 | Edit mode reads only what the current page needs (owner report 2026-10-24: `/philosophy?edit` fetched all 14 documents while the page renders profile text alone) | 3 | ✅ Done 2026-10-24 (automated) — `src/i18n/edit-scope.ts` (new): `manifestForPath` + `scopeForPath` derive the needed documents from the page manifests — a claim names a joined record, an entity owns its structure document plus its two text documents, and those are always read as one unit (a half-loaded entity would make the validator compare a live document against a bundled one); the label documents follow the projects scope. `EditModeShell`: the entry fetch is the entry route's scope plus anything a restored draft touched; an effect on `location.pathname` reads only the documents still missing and adopts them through `DraftStore.adoptBase`, which refuses a document the draft has already changed. `saveDraft` never PUTs a bundle-seeded baseline (an empty sha is a create for Gitea 28): it reads the branch first and reports a conflict, or a failure when that read fails. Every manifest now claims `profile.name` — the footer renders it on every route — which also makes the EditBar "appears on" annotation for that field truthful. Verified: `tsc -b`, `pnpm build` (EditModeShell stays a separate lazy chunk), `pnpm lint` (no new warnings), `pnpm validate:content`, `scripts/smoke-draft.ts` 13/13 (new checks 12–13: `adoptBase` replaces an untouched baseline and refuses a touched one; a bundle-seeded document is never written). Throwaway scope probe over all 7 routes + an unknown path + trailing-slash forms (deleted after the run): `/` 12 documents, `/about` 6, `/experience` 6, `/projects` and `/projects/:id` 6 + labels, `/contact` 3, `/philosophy` 3, unknown route 0. ⬜ Browser: `/philosophy?edit` → 3 document GETs; navigating to `/projects` brings the project documents; an edit made before they land goes through the conflict flow instead of overwriting the branch |