perf(edit): load the draft documents as one concurrent wave

EditModeShell issued the 12 draft documents with a for-loop of awaits, then the
2 category-label files. It now starts two concurrent requests whose success and
failure handlers are attached in the same tick, so a label rejection landing
while the documents are still in flight is not an unhandled rejection. The two
failure branches are unchanged: a document failure is the offline state, a label
failure only disables the category rule. Measured through the dev proxy, the
same transport the app uses: 12 documents sequential 902 ms -> 210 ms for the
whole 14-request wave, 38768 bytes and 12 distinct payloads byte-identical to
the sequential loop.

nginx.conf now proxies /api/content/ to Gitea over HTTP/2 (proxy_http_version 2
+ a cleared Connection header), so the wave rides one pooled upstream connection
instead of one HTTP/1.1 connection per in-flight request. The stack's nginx
1.31.x already does HTTP/1.1 with upstream keepalive caching by default since
1.29.7, so no upstream block is declared and the envsubst contract is
untouched; the pipeline's test-before-touch nginx -t is what proves the image
accepts proxy_http_version 2.

Specs: spec-v4-live-edit.md row 25 + the draft-initialization bullet,
spec-v4-deploy-infra.md D14 + row 10, AGENTS.md nginx.conf line.
This commit is contained in:
dong.nguyen committed 2026-10-24 14:45:26 +07:00
1 parent 3126971852
commit 83da513931
5 files changed
+43 -12

No files matched your search

+1 -1
View File
@@ -145,7 +145,7 @@ src/
- Site deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml` (push to `master`); infra redeployment by `.gitea/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, plus `workflow_dispatch` (the token-rotation runbook): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md`) - Site deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml` (push to `master`); infra redeployment by `.gitea/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, plus `workflow_dispatch` (the token-rotation runbook): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md`)
- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are Gitea Actions **variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable - Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are Gitea Actions **variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable
- Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `/opt/stacks/dong-site/dist/` - Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `/opt/stacks/dong-site/dist/`
- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Gitea Contents API; the upstream URL and the write token are `${GITEA_CONTENTS_API}` / `${GITEA_TOKEN}` substituted by the image's envsubst step at container start — the token and the Gitea host never enter the SPA bundle or the repository - `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Gitea Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec D14; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template still carries only `${GITEA_CONTENTS_API}` / `${GITEA_TOKEN}` — the token and the Gitea host never enter the SPA bundle or the repository)
- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `GITEA_TOKEN=` / `GITEA_CONTENTS_API=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml` / `deploy/htpasswd` - `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `GITEA_TOKEN=` / `GITEA_CONTENTS_API=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml` / `deploy/htpasswd`
- `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected - `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected
@@ -35,6 +35,7 @@ Dockge is a UI over compose files on disk: it reads the stack's `compose.yaml` f
| D11 | **`GITEA_CONTENTS_API` (full Contents-API base URL, incl. repo path) becomes a runtime configuration value** consumed only by the nginx container and the dev proxy — never CI, never the bundle. Repository literals removed: `nginx.conf` (`proxy_pass ${GITEA_CONTENTS_API};`, rev.6; the `proxy_set_header Host code.vugado.com` line is deleted — nginx's default `$proxy_host` for a literal proxy_pass gives the identical Host header) and `vite.config.ts:19-22` (parse `process.env.GITEA_CONTENTS_API` into proxy target + rewrite prefix; unset → no proxy → edit mode offline, identical to today's no-token behavior). `envsubst` renders at container start **before** nginx parses the config, so the rendered `proxy_pass` is a literal string — no `resolver` needed. Server home: the stack's single config file (D13); local home: the uncommitted local `.env` (vite's standard channel; the dev machine has no Dockge UI). `NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API` stays a plain env var in compose — it names variables to substitute, it is not itself sensitive. [rev.8: the filter is a **regex** the official entrypoint matches against each variable name — alternatives MUST be separated with `|`; the original comma form matched nothing and left the `${…}` tokens in the rendered config.] | The Gitea host + `dong.nguyen/cv` path is infrastructure, not product — today it appears in `nginx.conf:50,52` and `vite.config.ts:19-22`, so the dev proxy drifts from production by hand; after this both read the same value. The URL is public, so its secret-file home is about **placement** (outside the repo, outside the Dockge env tab), not confidentiality. | | D11 | **`GITEA_CONTENTS_API` (full Contents-API base URL, incl. repo path) becomes a runtime configuration value** consumed only by the nginx container and the dev proxy — never CI, never the bundle. Repository literals removed: `nginx.conf` (`proxy_pass ${GITEA_CONTENTS_API};`, rev.6; the `proxy_set_header Host code.vugado.com` line is deleted — nginx's default `$proxy_host` for a literal proxy_pass gives the identical Host header) and `vite.config.ts:19-22` (parse `process.env.GITEA_CONTENTS_API` into proxy target + rewrite prefix; unset → no proxy → edit mode offline, identical to today's no-token behavior). `envsubst` renders at container start **before** nginx parses the config, so the rendered `proxy_pass` is a literal string — no `resolver` needed. Server home: the stack's single config file (D13); local home: the uncommitted local `.env` (vite's standard channel; the dev machine has no Dockge UI). `NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API` stays a plain env var in compose — it names variables to substitute, it is not itself sensitive. [rev.8: the filter is a **regex** the official entrypoint matches against each variable name — alternatives MUST be separated with `|`; the original comma form matched nothing and left the `${…}` tokens in the rendered config.] | The Gitea host + `dong.nguyen/cv` path is infrastructure, not product — today it appears in `nginx.conf:50,52` and `vite.config.ts:19-22`, so the dev proxy drifts from production by hand; after this both read the same value. The URL is public, so its secret-file home is about **placement** (outside the repo, outside the Dockge env tab), not confidentiality. |
| D12 | **`SITE_NAME` (the `<title>`/og:title/twitter:title string) also becomes an env value.** The three `index.html` literals become `%SITE_NAME%` tokens filled by the same plugin; `site.ts`'s `siteName` export (currently **dead** — no consumer in the repo) is kept as the config module's typed accessor for the plugin and scripts. Known duplication recorded: the same person string exists in the content dictionaries (`profile.name` + `profile.title`); meta tags are build-time single-language chrome while content is runtime per-language, so v1 accepts the duplication and the env value. A future single-source option (compose the title from the documents at build time) is a follow-up, not part of this change. | Owner chose "Gồm cả siteName" 2026-10-23. Leaving the name in the repo while the URL moves out would half-solve the stated goal. | | D12 | **`SITE_NAME` (the `<title>`/og:title/twitter:title string) also becomes an env value.** The three `index.html` literals become `%SITE_NAME%` tokens filled by the same plugin; `site.ts`'s `siteName` export (currently **dead** — no consumer in the repo) is kept as the config module's typed accessor for the plugin and scripts. Known duplication recorded: the same person string exists in the content dictionaries (`profile.name` + `profile.title`); meta tags are build-time single-language chrome while content is runtime per-language, so v1 accepts the duplication and the env value. A future single-source option (compose the title from the documents at build time) is a follow-up, not part of this change. | Owner chose "Gồm cả siteName" 2026-10-23. Leaving the name in the repo while the URL moves out would half-solve the stated goal. |
| D13 | **The stack's runtime config is ONE server-side file, not `.env`, not multiple files** (owner direction 2026-10-23: "don't use .env", "use only one file"). `compose.yaml`: `secrets: [site_config]` with `secrets.site_config.file = ./secrets/site_config` (stack directory, chmod 600, owner-side, gitignored), a dotenv-format file holding exactly `GITEA_TOKEN=…` and `GITEA_CONTENTS_API=…` (shell-safe values: hex token, URL — no spaces/quotes). The entrypoint sources it before the official entrypoint renders: `entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"]` — `set -a` is required (a sourced assignment is a shell variable; without export the entrypoint child and its envsubst step see nothing), and the nginx command is written inline because a compose entrypoint override does not keep the image's CMD (`CMD=[]`; an empty `$@` makes the exec a no-op → exit 0 → restart loop). Both proven by a local run 2026-10-23; the original `$$@` form and its rationale were wrong. The full target file is §4.1. The stack directory has **no `.env` at all**; no sensitive value appears in compose's `environment:`. File-based secrets under plain `docker compose` (non-swarm) were verified on the VPS 2026-10-23. | Env vars appear in plaintext in the Dockge env editor and in `docker inspect`; a sourced secret file appears in neither (only its path is visible). Startup stays unattended: the file is read at container start, no human key (an "encrypted .env + key" scheme would break pipeline/boot recreations, which have no one to type the key). One file = one rotation surface, one rsync exclusion, one drift candidate. The only remaining plaintext is the rendered `default.conf` inside the container's writable layer — never bind-mounted, never on the host. | | D13 | **The stack's runtime config is ONE server-side file, not `.env`, not multiple files** (owner direction 2026-10-23: "don't use .env", "use only one file"). `compose.yaml`: `secrets: [site_config]` with `secrets.site_config.file = ./secrets/site_config` (stack directory, chmod 600, owner-side, gitignored), a dotenv-format file holding exactly `GITEA_TOKEN=…` and `GITEA_CONTENTS_API=…` (shell-safe values: hex token, URL — no spaces/quotes). The entrypoint sources it before the official entrypoint renders: `entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"]` — `set -a` is required (a sourced assignment is a shell variable; without export the entrypoint child and its envsubst step see nothing), and the nginx command is written inline because a compose entrypoint override does not keep the image's CMD (`CMD=[]`; an empty `$@` makes the exec a no-op → exit 0 → restart loop). Both proven by a local run 2026-10-23; the original `$$@` form and its rationale were wrong. The full target file is §4.1. The stack directory has **no `.env` at all**; no sensitive value appears in compose's `environment:`. File-based secrets under plain `docker compose` (non-swarm) were verified on the VPS 2026-10-23. | Env vars appear in plaintext in the Dockge env editor and in `docker inspect`; a sourced secret file appears in neither (only its path is visible). Startup stays unattended: the file is read at container start, no human key (an "encrypted .env + key" scheme would break pipeline/boot recreations, which have no one to type the key). One file = one rotation surface, one rsync exclusion, one drift candidate. The only remaining plaintext is the rendered `default.conf` inside the container's writable layer — never bind-mounted, never on the host. |
| D14 | **`/api/content/` proxies to Gitea over HTTP/2** (`proxy_http_version 2` + `proxy_set_header Connection "";`, `nginx.conf:51-60`, 2026-10-24). Measured 2026-10-24: `code.vugado.com` and `cv.vugado.com` both complete an ALPN h2 handshake and answer 200 (`server: openresty`); neither advertises `Alt-Svc`, so HTTP/3 is not offered to browsers and is not pursued. The stack's container is nginx 1.31.6 (owner-confirmed): HTTP/1.1 to upstreams **and** upstream keepalive caching (`keepalive 32 local`) are the defaults since 1.29.7, so connection reuse needs no `upstream` block — the first draft of this change (a named `upstream` + a `${GITEA_HOST}` derived from `GITEA_CONTENTS_API` in the entrypoint) was dropped because it would move the Gitea repo path back into `nginx.conf`, against D11. `proxy_http_version 2` exists since 1.29.4 and requires `ngx_http_v2_module` in the image: if the image lacks it, the test-before-touch `nginx -t` step fails and production is never touched (D3), and the fallback is simply to drop the two lines, since HTTP/1.1 + keepalive is already this container's default behavior. | Pairs with `spec-v4-live-edit.md` row 25: the client now issues its 14 reads as one concurrent wave. Over HTTP/1.1 a concurrent wave costs one upstream connection per in-flight request; over HTTP/2 they are streams on a single pooled connection. |
Env surface (the whole contract): `SITE_URL` + `SITE_NAME` = Gitea Actions **variables** (`vars.` context) on the `build`/`generate-resume` jobs — revised 2026-10-23: these are public values, so Gitea's variables mechanism is the correct channel (secrets are for sensitive values; masked secrets also made a missing/empty `SITE_URL` undiagnosable in logs); `GITEA_TOKEN` + `GITEA_CONTENTS_API` = the stack's single config file `secrets/site_config` (D13; never in `.env`, never in the repository, never in CI, never in the bundle). Local development: an uncommitted local `.env` (vite's standard channel) carries the runtime values; `.env.example` is committed with all four names (`SITE_URL`, `SITE_NAME`, `GITEA_TOKEN`, `GITEA_CONTENTS_API`) and no values. Env surface (the whole contract): `SITE_URL` + `SITE_NAME` = Gitea Actions **variables** (`vars.` context) on the `build`/`generate-resume` jobs — revised 2026-10-23: these are public values, so Gitea's variables mechanism is the correct channel (secrets are for sensitive values; masked secrets also made a missing/empty `SITE_URL` undiagnosable in logs); `GITEA_TOKEN` + `GITEA_CONTENTS_API` = the stack's single config file `secrets/site_config` (D13; never in `.env`, never in the repository, never in CI, never in the bundle). Local development: an uncommitted local `.env` (vite's standard channel) carries the runtime values; `.env.example` is committed with all four names (`SITE_URL`, `SITE_NAME`, `GITEA_TOKEN`, `GITEA_CONTENTS_API`) and no values.
@@ -176,3 +177,4 @@ GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/
| 6 | D10–D12 implementation: `site.ts` env read, `index.html` tokens + vite plugin, robots generation, `nginx.conf` variables, `vite.config.ts` env proxy, `deploy.yml` env, `.env.example`, AGENTS.md | ✅ Done 2026-10-23 — verified: `pnpm build` with `.env` filled emits injected meta + `dist/robots.txt`; `SITE_URL=` empty fails with the named-variable error; runtime files grep-clean of `vugado` | | 6 | D10–D12 implementation: `site.ts` env read, `index.html` tokens + vite plugin, robots generation, `nginx.conf` variables, `vite.config.ts` env proxy, `deploy.yml` env, `.env.example`, AGENTS.md | ✅ Done 2026-10-23 — verified: `pnpm build` with `.env` filled emits injected meta + `dist/robots.txt`; `SITE_URL=` empty fails with the named-variable error; runtime files grep-clean of `vugado` |
| 9 | D13 implementation: `compose.yaml` per §4.1 (secret `site_config` + entrypoint override), `.gitignore` += `secrets/`; VPS: create `secrets/site_config`, delete stack `.env` | 🟡 Repo side Done 2026-10-23, entrypoint corrected the same day (`set -a` + inline nginx command — the `$$@` form restart-looped, proven locally; full local stack verified Up + probe 200); owner-side file + stack `.env` removal TODO | | 9 | D13 implementation: `compose.yaml` per §4.1 (secret `site_config` + entrypoint override), `.gitignore` += `secrets/`; VPS: create `secrets/site_config`, delete stack `.env` | 🟡 Repo side Done 2026-10-23, entrypoint corrected the same day (`set -a` + inline nginx command — the `$$@` form restart-looped, proven locally; full local stack verified Up + probe 200); owner-side file + stack `.env` removal TODO |
| 7 | Owner-side: Gitea Actions **variables** `SITE_URL`, `SITE_NAME` (rev.: switched from secrets 2026-10-23 — public values belong in the `vars.` context); local `.env` from `.env.example` | 🟡 Local `.env` created 2026-10-23 (values known; `GITEA_TOKEN` left as shell env as before); Gitea variables TODO — owner-side | | 7 | Owner-side: Gitea Actions **variables** `SITE_URL`, `SITE_NAME` (rev.: switched from secrets 2026-10-23 — public values belong in the `vars.` context); local `.env` from `.env.example` | 🟡 Local `.env` created 2026-10-23 (values known; `GITEA_TOKEN` left as shell env as before); Gitea variables TODO — owner-side |
| 10 | D14 implementation: HTTP/2 upstream for `/api/content/` | ✅ Repo side Done 2026-10-24 — `nginx.conf:51-60` (`proxy_http_version 2` + `proxy_set_header Connection ""`), `proxy_pass ${GITEA_CONTENTS_API}` untouched. The env contract is unchanged: the template still references only `${GITEA_TOKEN}` and `${GITEA_CONTENTS_API}` (grep-verified), so `NGINX_ENVSUBST_FILTER` in `compose.yaml:25` and in the workflow's test step need no edit, and `compose.yaml` / `deploy/htpasswd` are not touched. Not checkable on the dev machine (no nginx binary, Docker daemon off) — the acceptance check is the pipeline's own test-before-touch step plus a live edit-mode load. ⬜ CI: the next `deploy-infra` run — its throwaway `nginx -t` is what proves the image accepts `proxy_http_version 2` (if it does not, D14's fallback is to drop the two lines); then `docker exec dong-site nginx -t` and an edit-mode load on the deployed site |
+2 -1
View File
@@ -331,7 +331,7 @@ Type changes in `src/types/index.ts`: every `*En` optional is deleted from the 6
The site itself gains an edit mode. There is no second preview machinery — the seven routes *are* the preview. The site itself gains an edit mode. There is no second preview machinery — the seven routes *are* the preview.
- **Entry:** edit mode activates only for the authenticated owner (handshake against the protected proxy endpoint, §6.2; activation stored in `sessionStorage`). A `?edit` query on any route opens the mode; from there the session flag **is** the mode — every internal navigation carries `?edit` again and a reload reopens the same session (row 24). The query is stripped from the URL on exit so shared/canonical URLs stay clean. Anonymous visitors never see edit affordances. - **Entry:** edit mode activates only for the authenticated owner (handshake against the protected proxy endpoint, §6.2; activation stored in `sessionStorage`). A `?edit` query on any route opens the mode; from there the session flag **is** the mode — every internal navigation carries `?edit` again and a reload reopens the same session (row 24). The query is stripped from the URL on exit so shared/canonical URLs stay clean. Anonymous visitors never see edit affordances.
- **Draft initialization:** the draft is initialized from **live repository files fetched through the proxy** (`GET` per document + its blob `sha`), not from the bundle — the bundle may be older than master if anyone edited via Gitea web since the last build, and a bundle-seeded draft would silently revert those edits. The static bundle is used only as an offline fallback, with a visible "stale" warning. - **Draft initialization:** the draft is initialized from **live repository files fetched through the proxy** (`GET` per document + its blob `sha`), not from the bundle — the bundle may be older than master if anyone edited via Gitea web since the last build, and a bundle-seeded draft would silently revert those edits. The static bundle is used only as an offline fallback, with a visible "stale" warning. The 12 documents and the 2 label files are issued as **one concurrent wave**, not one after another (row 25); the offline fallback and the labels-unavailable path are the same two failure branches as before.
- **Mechanism:** edit mode wraps `<Layout>` in `<I18nProvider override={draft}>`. All pages, all components, both languages render the draft — text **and** structure. - **Mechanism:** edit mode wraps `<Layout>` in `<I18nProvider override={draft}>`. All pages, all components, both languages render the draft — text **and** structure.
- **Inline text editing:** rendered text nodes bound to a text-document path become editable on focus (`contentEditable`); blur writes `{ path, value }` into the draft. Editing `projects['iot-dws-integration'].title` updates the card on `/projects`, the header on `/projects/:id`, and the featured block on the home page **simultaneously** — one draft, every consumer. - **Inline text editing:** rendered text nodes bound to a text-document path become editable on focus (`contentEditable`); blur writes `{ path, value }` into the draft. Editing `projects['iot-dws-integration'].title` updates the card on `/projects`, the header on `/projects/:id`, and the featured block on the home page **simultaneously** — one draft, every consumer.
- **Editable surface (curated scope):** inline editing covers **text documents only** — profile bio and tagline (each tagline segment is an individually editable span), profile subtitle / career TL;DR / philosophy quote titles+paragraphs (row 18), project titles/summaries/section content/role, experience titles/companies/durations/responsibilities (row 19), skill group titles, philosophy titles/descriptions. `ui.json` is **read-only** in v4 (labels/aria are low-frequency chrome). This bounds the wrapping work to the ~40 content render sites, not the 130+ UI-string sites. Adjacent tagline segments are separate edit targets — the caret does not cross a segment boundary; intended behavior (D9), not a bug. *Superseded 2026-10-23 by `spec-v4-inline-editing.md`: editing is triggered by a per-field pencil icon, never by text focus; tag arrays (`currentInterests`, `roles`, `keywords`, `metrics`, `technologies`, tagline segments + emphasis toggle) become chip-level edit units with add/delete/move.* - **Editable surface (curated scope):** inline editing covers **text documents only** — profile bio and tagline (each tagline segment is an individually editable span), profile subtitle / career TL;DR / philosophy quote titles+paragraphs (row 18), project titles/summaries/section content/role, experience titles/companies/durations/responsibilities (row 19), skill group titles, philosophy titles/descriptions. `ui.json` is **read-only** in v4 (labels/aria are low-frequency chrome). This bounds the wrapping work to the ~40 content render sites, not the 130+ UI-string sites. Adjacent tagline segments are separate edit targets — the caret does not cross a segment boundary; intended behavior (D9), not a bug. *Superseded 2026-10-23 by `spec-v4-inline-editing.md`: editing is triggered by a per-field pencil icon, never by text focus; tag arrays (`currentInterests`, `roles`, `keywords`, `metrics`, `technologies`, tagline segments + emphasis toggle) become chip-level edit units with add/delete/move.*
@@ -607,3 +607,4 @@ Deferred (not v4):
| 22 | Union balance on delete: a record removed in edit mode prunes its id out of `src/types/index.ts` (the `TS2741` after the `logistics-technology` skill group was deleted) | 3 | ✅ Done 2026-10-24 (automated) — `draft.ts`: `readUnionBlock` reads a union as its exact declaration span (CRLF- and LF-safe, `never` round-trips), `diffIdsWithUnions` reports missing **and** stale members against `committedStructures()`, `applyUnionChanges` rewrites only that member list (survivors keep their order), one PUT with the message `content: update id union members (+id, -id)`; `newIdsInCommitted` / `patchUnionSource` deleted; `types/index.ts` `SkillGroupId` no longer lists `logistics-technology`; `ui/edit.json` `unionNote` reworded for both directions. Verified: `pnpm tsx scripts/smoke-draft.ts` 12/12 — new checks 9–12 (shipped documents ↔ shipped unions agree, a delete prunes exactly one line, an id colliding with a `PageId` member is still appended, `never` round-trip), `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build`. **Superseded the same day by row 23**: the whole union leg — `saveIdUnions`, `diffIdsWithUnions`, `applyUnionChanges`, `unionNote`, `unionError`, `UnionLogEntry`, `onUnionsSaved` — was deleted with spec-v5; the `TS2741` it fixed is now prevented by regenerating the unions, and the delete case is covered by `smoke-generated-ids.ts` + the `tsc` re-check | | 22 | Union balance on delete: a record removed in edit mode prunes its id out of `src/types/index.ts` (the `TS2741` after the `logistics-technology` skill group was deleted) | 3 | ✅ Done 2026-10-24 (automated) — `draft.ts`: `readUnionBlock` reads a union as its exact declaration span (CRLF- and LF-safe, `never` round-trips), `diffIdsWithUnions` reports missing **and** stale members against `committedStructures()`, `applyUnionChanges` rewrites only that member list (survivors keep their order), one PUT with the message `content: update id union members (+id, -id)`; `newIdsInCommitted` / `patchUnionSource` deleted; `types/index.ts` `SkillGroupId` no longer lists `logistics-technology`; `ui/edit.json` `unionNote` reworded for both directions. Verified: `pnpm tsx scripts/smoke-draft.ts` 12/12 — new checks 9–12 (shipped documents ↔ shipped unions agree, a delete prunes exactly one line, an id colliding with a `PageId` member is still appended, `never` round-trip), `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build`. **Superseded the same day by row 23**: the whole union leg — `saveIdUnions`, `diffIdsWithUnions`, `applyUnionChanges`, `unionNote`, `unionError`, `UnionLogEntry`, `onUnionsSaved` — was deleted with spec-v5; the `TS2741` it fixed is now prevented by regenerating the unions, and the delete case is covered by `smoke-generated-ids.ts` + the `tsc` re-check |
| 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 | | 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 | | 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 |
+10
View File
@@ -48,6 +48,16 @@ server {
auth_basic "Editor"; auth_basic "Editor";
auth_basic_user_file /etc/nginx/htpasswd; auth_basic_user_file /etc/nginx/htpasswd;
# HTTP/2 to the upstream (nginx >= 1.29.4; the stack runs 1.31.x). The
# edit-mode client issues its 12 document reads + 2 label reads as one
# concurrent wave, and the Gitea host answers h2, so those requests
# multiplex over a single upstream connection instead of one HTTP/1.1
# connection each. Upstream keepalive caching is already the default
# since 1.29.7; the docs still require the Connection header to be
# cleared for a reused upstream connection.
proxy_http_version 2;
proxy_set_header Connection "";
proxy_pass ${GITEA_CONTENTS_API}; proxy_pass ${GITEA_CONTENTS_API};
proxy_ssl_server_name on; proxy_ssl_server_name on;
proxy_set_header Authorization "token ${GITEA_TOKEN}"; proxy_set_header Authorization "token ${GITEA_TOKEN}";
+28 -10
View File
@@ -155,10 +155,31 @@ export default function EditModeShell({ children }: { children: ReactNode }) {
// (§5.1); the bundle is only the offline fallback, flagged stale. // (§5.1); the bundle is only the offline fallback, flagged stale.
let offline = false; let offline = false;
let bases: Record<DraftDocId, DocBase> | null = null; let bases: Record<DraftDocId, DocBase> | null = null;
try { // One concurrent wave instead of 14 serialized round-trips. The handlers
// are attached in the same tick the requests are made, so a label
// rejection that lands while the documents are still in flight is not an
// unhandled rejection; the two failure paths stay separate — a document
// failure is the offline state, a label failure only disables rule 7.
const docsRequest = Promise.all(
DRAFT_DOCS.map((meta) => fetchDoc(meta.file, branch)),
).then(
(docs) => ({ ok: true as const, docs }),
() => ({ ok: false as const }),
);
const labelsRequest = Promise.all([
fetchDoc(LABEL_FILES.vi, branch),
fetchDoc(LABEL_FILES.en, branch),
]).then(
([vi, en]) => ({ ok: true as const, vi, en }),
() => ({ ok: false as const }),
);
const docs = await docsRequest;
if (docs.ok) {
bases = {} as Record<DraftDocId, DocBase>; bases = {} as Record<DraftDocId, DocBase>;
for (const meta of DRAFT_DOCS) bases[meta.id] = await fetchDoc(meta.file, branch); DRAFT_DOCS.forEach((meta, index) => {
} catch { bases![meta.id] = docs.docs[index];
});
} else {
offline = true; offline = true;
} }
if (!bases) bases = bundledBase(); if (!bases) bases = bundledBase();
@@ -167,13 +188,10 @@ export default function EditModeShell({ children }: { children: ReactNode }) {
// says the label check could not run, and the rule is skipped rather // says the label check could not run, and the rule is skipped rather
// than guessed at from a bundle that may predate the branch. // than guessed at from a bundle that may predate the branch.
let labels: CategoryLabels | null = null; let labels: CategoryLabels | null = null;
try { const labelDocs = await labelsRequest;
const [viLabels, enLabels] = await Promise.all([ if (labelDocs.ok) {
fetchDoc(LABEL_FILES.vi, branch), labels = { vi: categoryMap(labelDocs.vi.data), en: categoryMap(labelDocs.en.data) };
fetchDoc(LABEL_FILES.en, branch), } else {
]);
labels = { vi: categoryMap(viLabels.data), en: categoryMap(enLabels.data) };
} catch {
setLabelsUnavailable(true); setLabelsUnavailable(true);
} }