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

+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 |