410 lines
25 KiB
Markdown
410 lines
25 KiB
Markdown
# Milestone 9: React SPA admin UI (PLAN §14, §3.14)
|
||
|
||
Goal: the complete admin UI — ten pages per PLAN.md:560, login, pause control, restart
|
||
banner — built with Vite + React + TypeScript + Tailwind + TanStack Router/Query,
|
||
embedded in the binary via the existing `-Dweb-dist` pipeline, with a frontend CI job.
|
||
|
||
Ground truth: PLAN.md:118-120 (auth UX), :138-140 (stack + embedding), :145/:579 (CI),
|
||
:454-456 (live view), :531 (restart banner), :560-562 (pages + requirements), :639 (size
|
||
budget), :641 (upstream health in UI); specs/milestone-8.md W8/W9 As-built (asset
|
||
pipeline, SPA fallback, --web-dev); src/web/openapi.yaml (the API contract — authorative
|
||
for every body shape; do NOT guess fields, read it).
|
||
|
||
## Rulings (binding)
|
||
|
||
1. **Stack per PLAN.md:138, not house style**: Vite + React 19 + TypeScript + Tailwind
|
||
v4 (CSS-first config, no tailwind.config.js) + TanStack Router + TanStack Query. The
|
||
reference repos use StyleX and no TanStack; PLAN is the source of truth here. SPA, no
|
||
SSR, base `/`.
|
||
2. **Location**: everything under `web/` (PLAN.md:234): `web/package.json`, `web/src/`,
|
||
`web/index.html`, build output `web/dist/` (gitignored). `web/dist-placeholder/`
|
||
stays untouched and stays the `-Dweb-dist` default.
|
||
3. **Toolchain**: node >= 24 (`engines`), npm with committed `web/package-lock.json`.
|
||
Dependencies exact-pinned (house style). Checks: `tsc --noEmit`, Prettier (house
|
||
config: tabs, tabWidth 4, printWidth 120, semi, double quotes, trailing commas all),
|
||
oxlint (zero-config), vitest + @testing-library/react + jsdom for tests. No ESLint,
|
||
no Biome, no msw — tests stub `fetch`/`EventSource` by hand.
|
||
4. **No charting dependency.** The dashboard chart is a hand-rolled SVG component
|
||
(stacked bars for queries/blocked/cached over the fixed zero-filled buckets, axis
|
||
labels, hover tooltip via native `<title>` + a hover state). The data is small
|
||
(60-168 buckets) and fixed-shape; a chart library is a liability with no payoff.
|
||
This is complete, not a stub: axes, tooltip, empty state, responsive width.
|
||
5. **Router**: code-based route tree (no file-based codegen plugin). Every data route
|
||
uses a TanStack Router loader that primes TanStack Query (`ensureQueryData`) —
|
||
PLAN.md:562 "route loaders for initial fetch". Pending/error components on every
|
||
route; TanStack Query handles cache/retry (no retry on 4xx; retry 429 after
|
||
Retry-After).
|
||
6. **API layer**: one `src/lib/api.ts` typed client over `fetch` with
|
||
`credentials: "same-origin"`. Types in `src/lib/types.ts` transcribed by hand from
|
||
openapi.yaml (snake_case preserved; no codegen dependency). Error model:
|
||
`ApiError{status, message, retryAfter?}` from the `{error}` envelope; 503 rendered
|
||
distinctly from 500 ("server starting/degraded" vs "internal error").
|
||
7. **Auth flow**: `/login` route outside the app shell. On any 401 the query layer
|
||
redirects to `/login?redirect=<path>`. Login POST with `auth_required=false` in the
|
||
response → auth is off → navigate straight in (the login page short-circuits by
|
||
probing once). Logout button in the shell (hidden when auth is off). Session state
|
||
lives in a tiny auth store fed by responses, not a poll. Works with auth on AND off
|
||
(PLAN.md:562) — with auth off the SPA never shows login.
|
||
8. **Pause control is global**: a shell-header widget (pause/resume with duration
|
||
presets 60s/5m/30m/indefinite, countdown from `until`, `paused` disambiguates null
|
||
`until`). Not a page.
|
||
9. **Live log page**: `EventSource` on `/api/queries/live`; ring buffer of 500 rows in
|
||
memory, newest first; rows keyed by a monotonically increasing client counter (the
|
||
SSE payload has NO id). On `error`/close the browser auto-reconnects (server sends
|
||
`retry: 3000`); on reconnect the page re-syncs the gap via `GET /api/queries`
|
||
(since = last seen ts) and shows a "stream resumed, N missed" notice. Pause-stream
|
||
button (client-side freeze) included. 429 from the SSE cap → visible "too many live
|
||
viewers" state, retry button.
|
||
10. **Query log page**: keyset pagination exactly per contract (`limit`, `before`,
|
||
follow `next_before` until null; newest first). Filters: domain substring, client
|
||
exact, blocked tri-state, since/until (datetime-local inputs → unix seconds).
|
||
"Load more" appends; filter change resets the cursor.
|
||
11. **Settings page**: sections rendered from the GET envelope; a diff-based PUT sends
|
||
ONLY changed fields (partial patch per contract). Every key is restart-required
|
||
today: after a successful PUT of anything except `web.password`, set a persistent
|
||
"restart to apply" banner (dismiss resets on next change; PLAN.md:531).
|
||
`web.password` is a write-only field with confirm input; on change the API kills
|
||
all sessions — the SPA expects the next request to 401 and routes to login.
|
||
`web.auth_enabled` is read-only derived. `web.password_hash` is never sent.
|
||
12. **Blocklists page** shows per-source `skipped_regex_count` (PLAN.md:38) and source
|
||
status (state, last_success, counts, last_error). "Update now" calls
|
||
`POST /api/blocklists/update`, REPLACES list state from the 202 snapshot, disables
|
||
the button while in flight.
|
||
13. **Dashboard**: stats totals + timeseries chart (period picker 1h/24h/7d/30d),
|
||
upstream health table (PLAN.md:641), disk card from `/api/health`
|
||
(state/free/db/log bytes) with the warning banner when `disk.state != "ok"`
|
||
(PLAN.md:465), plus queries_dropped/writer_failed indicators. Auto-refresh via
|
||
Query `refetchInterval` 30s (health 10s).
|
||
14. **Groups page** includes the group↔sources assignment editor
|
||
(`PUT /api/groups/{id}/sources`, full-set checkboxes) and safe_search toggle.
|
||
Default group (id 1) shows but blocks rename/delete client-side too (server 409s).
|
||
15. **Clients page**: table of all clients (`hand_edited` badge), edit name/group, no
|
||
create (rows appear from DNS activity — say so in the empty state), delete with
|
||
"re-materializes on next query" note. Client-prefixes editor on the same page:
|
||
whole-list editing per the PUT contract.
|
||
16. **Local DNS page**: two tabs (records, forward zones), CRUD forms per contract.
|
||
**Domain lookup page**: domain + group select → renders the full pipeline verdict
|
||
(local_records, forward_zone, blocked/reason/matched/source_url,
|
||
safe_search_rewrite).
|
||
17. **Errors and loading**: every route has skeleton/pending UI and an error boundary
|
||
with the ApiError message + retry (PLAN.md:562). Mutations surface 400/409 messages
|
||
inline at the form, 429 with countdown, 401 via the global redirect.
|
||
18. **Responsive**: sidebar nav collapses to a top bar + drawer under `md:`; tables get
|
||
`overflow-x-auto` wrappers; the dashboard grid stacks. Desktop and mobile per
|
||
PLAN.md:562 — no separate mobile pages.
|
||
19. **Formatting/l10n**: timestamps rendered in the browser locale from unix seconds
|
||
(`Intl.DateTimeFormat`), byte counts humanized (KiB/MiB/GiB), µs durations shown as
|
||
ms with one decimal. One `src/lib/format.ts`, tested.
|
||
20. **Size budget**: PLAN.md:639 — stripped static binary < 15 MB with assets (< 10 MB
|
||
without → SPA budget ≈ 5 MB embedded, plain + .gz both count). React+TanStack+
|
||
Tailwind lands far under that; CI asserts the final cross binaries < 15 MB.
|
||
21. **Zig side is frozen.** No changes to src/, build.zig, tools/, or openapi.yaml. If
|
||
the SPA reveals an API bug, STOP and report — do not work around silently. The only
|
||
Zig-adjacent deliverables are ci.yml additions and `.gitignore` entries.
|
||
22. **CI**: new `frontend` job (setup-node@v4, `NODE_VERSION: "24"` env pin,
|
||
`cache: npm`, `cache-dependency-path: web/package-lock.json`; `npm ci` →
|
||
`prettier --check` → oxlint → `tsc --noEmit` → `vitest run` → `vite build`),
|
||
uploading `web/dist` as an artifact is NOT needed — instead the existing `cross`
|
||
job gains: setup-node, `npm ci && npm run build` (prefix web), then
|
||
`zig build cross -Dweb-dist=web/dist`, then the existing static assert plus a
|
||
size assert (< 15 MB per exe). The `test` job stays Zig-only.
|
||
23. **Accessibility floor**: semantic elements, labeled inputs, focus-visible styles,
|
||
buttons not divs. No ARIA deep-dive beyond what semantics give.
|
||
24. **No new pages, no dark-mode toggle bikeshed** (Tailwind default palette, system
|
||
`prefers-color-scheme` via CSS only), no i18n framework, no state library beyond
|
||
TanStack Query + two tiny stores (auth, restart-banner) in React context.
|
||
|
||
## Sessions
|
||
|
||
F1 first (scaffold), then F2 (api/lib) sequential on F1, then F3-F8 parallel (pages;
|
||
disjoint files), then F9 (CI + embed + smoke) after all.
|
||
|
||
---
|
||
|
||
## Session F1: scaffold + shell
|
||
|
||
Owns: `web/package.json`, `web/package-lock.json`, `web/index.html`,
|
||
`web/vite.config.ts`, `web/tsconfig*.json`, `web/.oxlintrc.json` (only if needed),
|
||
`web/src/main.tsx`, `web/src/routes.tsx` (route tree with lazy page imports and
|
||
placeholder page stubs F3-F8 replace), `web/src/shell/` (layout, sidebar/topbar nav,
|
||
`PauseWidget` SLOT — an import of `../features/pause/PauseWidget` that F8 fills; F1
|
||
ships the real widget file with a disabled placeholder), `web/src/styles.css`
|
||
(tailwind), `.gitignore` additions (web/dist, web/node_modules), Prettier config in
|
||
package.json (house values), scripts: dev/build/typecheck/lint/format/test.
|
||
|
||
Vite: `@vitejs/plugin-react`, tailwind v4 via `@tailwindcss/vite`, build target
|
||
baseline-widely-available (vite 8 default), no proxy needed for build; dev proxy
|
||
`/api` + `/metrics` → `http://127.0.0.1:8080` for `vite dev` against a running nxdns.
|
||
Route tree: `/login` bare; shell routes `/`, `/queries`, `/live`, `/clients`,
|
||
`/groups`, `/blocklists`, `/rules`, `/local-dns`, `/lookup`, `/settings`.
|
||
|
||
Acceptance: `npm ci && npm run build` produces `web/dist` with `/index.html`;
|
||
typecheck/lint/format clean; placeholder pages render; nav works with keyboard.
|
||
|
||
### F1 As built
|
||
|
||
Pinned: react 19.2.8, @tanstack/react-router 1.170.18, @tanstack/react-query 5.101.4,
|
||
vite 8.1.5, typescript 6.0.3, tailwindcss 4.3.3 (@tailwindcss/vite), vitest 4.1.10,
|
||
@testing-library/react 16.3.2, jsdom 29.1.1, prettier 3.9.6, oxlint 1.75.0. All exact.
|
||
~/.npmrc enforces min-release-age=7 (newest gate-clearing versions chosen) and
|
||
ignore-scripts=true (works; native bins are optionalDependencies). TS6 deprecates
|
||
baseUrl — tsconfig.app.json uses `paths` without it. Dist: 344K (main chunk 278.5 kB /
|
||
88.2 kB gz, 11 lazy page chunks, CSS 8.8 kB). `zig build -Dweb-dist=web/dist` exit 0.
|
||
- Alias `@/*` → `web/src/*` (tsconfig paths + vite resolve.alias).
|
||
- Router: code-based in src/routes.tsx; `createAppRouter(history?)` exported (tests
|
||
pass createMemoryHistory); `Register` declared so `Link to` is typed; pages wired
|
||
via lazyRouteComponent at stable paths — every page keeps a default export at its
|
||
path; page sessions never edit routes.tsx. Shell = pathless layout route id "shell";
|
||
/login hangs off root outside it; defaultPreload "intent".
|
||
- Shell: AppShell renders PauseWidget (default export, no props) from
|
||
features/pause/PauseWidget, header right; F8 replaces the file in place.
|
||
VersionFooter inside AppShell.tsx (F2 wires /api/version). Restart banner has no
|
||
premade slot — F8 mounts it in AppShell (sequential edit). Nav: aria-current +
|
||
activeProps; drawer under md: with aria-expanded/controls.
|
||
- Vitest lives in vite.config.ts (jsdom, globals: true; tsconfig types include
|
||
vitest/globals). lint = `oxlint src vite.config.ts`; prettier ignores dist/,
|
||
dist-placeholder/, package-lock.json (.prettierignore).
|
||
- Page filenames: QueryLogPage/LiveLogPage per F4 naming; LoginPage placeholder in
|
||
src/auth/ (F2 replaces).
|
||
|
||
---
|
||
|
||
## Session F2: API layer + auth + query plumbing
|
||
|
||
Owns: `web/src/lib/` (`api.ts`, `types.ts`, `format.ts`, `queryClient.ts`,
|
||
`queries.ts` — queryOptions per resource, mutation helpers with invalidation),
|
||
`web/src/auth/` (store, `LoginPage`, 401 redirect wiring), tests for api/format/
|
||
pagination/settings-diff helpers.
|
||
|
||
types.ts transcribed from src/web/openapi.yaml — every shape the pages consume
|
||
(QueryRow, QueriesPage, StatsTotals, Timeseries, Lookup, UpstreamHealth, Health,
|
||
Version, Group, Blocklist, SourceStatus, Rule, LocalRecord, ForwardZone, Client,
|
||
ClientPrefix, Upstream, SettingsEnvelope, Pause, Login). ApiError per ruling 6;
|
||
401 hook per ruling 7; 429 retry per ruling 5; settings diff builder per ruling 11
|
||
(pure function, tested).
|
||
|
||
Acceptance: vitest green; typecheck clean; login/logout round trip works against a
|
||
live `nxdns run` (manual smoke; document the transcript).
|
||
|
||
### F2 As built
|
||
|
||
lib/{types,api,queryClient,queries,format,settingsDiff}.ts + tests (22 green);
|
||
auth/{store.tsx,LoginPage.tsx}; routes.tsx gained context+loaders+default
|
||
pending/error components; main.tsx providers; AppShell gained logout button + live
|
||
VersionFooter. Live-server smoke verified every consumed shape with auth on AND off;
|
||
no API bugs. Main chunk 319 kB (100 kB gz).
|
||
- api.ts: `request<T>` core (same-origin, 204→void, `{error}` envelope, Retry-After on
|
||
429), `requestText`, functions for all 55 route-method pairs, list envelopes
|
||
unwrapped to arrays, `liveQueriesUrl` for F4.
|
||
- queryClient: staleTime 30s; no retry on 4xx except 429 (max 2, delay=retryAfter);
|
||
QueryCache+MutationCache onError → `/login?redirect=<path+search>` on 401 (skipped
|
||
on /login).
|
||
- queries.ts factories: healthQuery (10s refetch), versionQuery, statsQuery/
|
||
timeseriesQuery(period), upstreamHealthQuery (30s), queriesQuery(filter),
|
||
lookupQuery(domain, groupId?), groupsQuery, groupSourcesQuery(id), blocklistsQuery,
|
||
rulesQuery, localRecordsQuery, forwardZonesQuery, clientsQuery, clientPrefixesQuery,
|
||
upstreamsQuery, pauseQuery, settingsQuery. Mutations: `xxxMutation(queryClient)` →
|
||
useMutation options; invalidation map in the F2 report; NOTE
|
||
`blocklistsUpdateNowMutation` seeds `queryKeys.blocklistSources` from the 202
|
||
snapshot — the ONLY feed for source status (no GET exists); F6 reads that key.
|
||
- Auth store: `useAuth()` → {authRequired: bool|null, probe(), login(password),
|
||
logout()}. Probe = POST login with empty password (no status GET), StrictMode-deduped;
|
||
authRequired mirrored in sessionStorage `nxdns_auth_required`.
|
||
- Loaders prime: dashboard stats+timeseries("24h")+health+upstreamHealth; queries
|
||
`queriesQuery({})` (F4 "load more" calls api.getQueries imperatively and appends);
|
||
clients clients+prefixes+groups; groups groups+blocklists; rules rules+groups;
|
||
local-dns records+zones; lookup groups; settings settings; live none. Pages use the
|
||
same factory the loader primed (useSuspenseQuery/useQuery).
|
||
- Router error component is ApiError-aware (503 "starting or degraded", 429 countdown,
|
||
≥500 generic); Retry = router.invalidate().
|
||
- Page-test pattern: wrap in AuthProvider+QueryClientProvider, pass the same qc to
|
||
`createAppRouter(history, qc)`, stub fetch per-URL (see AppShell.test.tsx).
|
||
- api.ts sends `{}` on bodyless POSTs (logout, blocklists/update) — belt-and-braces
|
||
over the W9 server fix.
|
||
|
||
---
|
||
|
||
## Session F3: Dashboard + SVG chart
|
||
|
||
Owns: `web/src/features/dashboard/` (page, StatCards, TimeseriesChart (SVG, ruling 4),
|
||
UpstreamHealthTable, DiskCard, HealthBanners) + chart unit tests (bucket→bar math,
|
||
empty state).
|
||
|
||
## Session F4: Query log + Live log
|
||
|
||
Owns: `web/src/features/queries/` (QueryLogPage, filters, cursor pagination per ruling
|
||
10) and `web/src/features/live/` (LiveLogPage per ruling 9: EventSource wrapper hook
|
||
with injected EventSource for tests, ring buffer, gap re-sync, freeze, cap-hit state).
|
||
Tests: ring buffer, gap-resync math, EventSource hook with a fake.
|
||
|
||
## Session F5: Clients + Groups
|
||
|
||
Owns: `web/src/features/clients/` (table, edit dialog, prefixes editor per ruling 15)
|
||
and `web/src/features/groups/` (list, create/rename/delete, safe_search, sources
|
||
assignment per ruling 14).
|
||
|
||
## Session F6: Blocklists + Rules
|
||
|
||
Owns: `web/src/features/blocklists/` (ruling 12) and `web/src/features/rules/`
|
||
(table with group/kind/action columns, create form with pattern kind select, delete).
|
||
|
||
## Session F7: Local DNS + Lookup
|
||
|
||
Owns: `web/src/features/local/` (records + zones tabs, CRUD forms) and
|
||
`web/src/features/lookup/` (ruling 16).
|
||
|
||
## Session F8: Settings + Pause widget
|
||
|
||
Owns: `web/src/features/settings/` (ruling 11: section forms, diff PUT, restart
|
||
banner store + banner component mounted in the shell via F1's slot, password flow)
|
||
and `web/src/features/pause/PauseWidget.tsx` (REPLACES F1's placeholder; ruling 8).
|
||
Tests: diff builder edge cases (nested partial, password only, no-op), banner logic.
|
||
|
||
### F3-F8 As built (page wave)
|
||
|
||
All six sessions green; 100 web tests total after the wave; main chunk 318 kB
|
||
(99 kB gz), pages as lazy chunks.
|
||
- **F3 Dashboard**: chartLayout.ts pure layout (layoutTimeseries, niceTicks 1/2/5) +
|
||
TimeseriesChart({data}) — self-measuring SVG stacked bars (blocked/cached/other,
|
||
other = queries−blocked−cached clamped ≥0), sr-only data table, role="img".
|
||
Axis ticks use a short Intl formatter (formatTime is tooltip/sr-only only).
|
||
UpstreamHealthTable shows total_failures; success_rate ×100 (0..1 verified in
|
||
pool.zig). HealthBanners: disk warn/critical (critical text per PLAN.md:466),
|
||
writer_failed, queries_dropped>0, all role="alert". 12 tests.
|
||
- **F4 Query/Live**: QueryLogPage exports QueryCells/QueryTableHead/BlockedCell,
|
||
reused by LiveLogPage (both F4-owned). qtype.ts names 19 codes, TYPE<n> fallback.
|
||
Filters in component state (not URL). ringBuffer.ts: 500 newest-first + mergeGap
|
||
(dedup key ts|domain|client_ip|qtype|blocked|upstream — SSE rows have no id;
|
||
same-second identical queries can over-dedup, accepted at household scale).
|
||
useLiveQueries hook (injected EventSourceLike factory + fetchSince): states
|
||
connecting/open/retrying/capped, gap re-sync getQueries({since, limit:500}) —
|
||
gaps >500 replace the buffer wholesale; CAP_ERROR_THRESHOLD=3 consecutive errors
|
||
→ capped state (EventSource cannot see 429; message says cap OR unreachable),
|
||
open resets the counter. Freeze = display-only snapshot; the ring keeps filling;
|
||
Resume swaps to current. 25 tests.
|
||
- **F5 Clients/Groups**: prefixEditor.ts pure reducer (priority "" omitted → server
|
||
default 100); baseline resets only on save/discard (dirty edits never clobbered by
|
||
refetch). clientUpdateMutation takes {id, edit} (spec prompt said input — code
|
||
wins). Groups: safe_search toggle PUTs with unchanged name (server 409s only on
|
||
actual rename of default — verified in groups.zig); default group protections
|
||
client-side + visible note; sourceSet.ts toggle/sameSet. 18 tests.
|
||
- **F6 Blocklists/Rules**: rule enums confirmed kind=[exact,wildcard],
|
||
action=[allow,block]. Status section reads queryKeys.blocklistSources via
|
||
queryClient.getQueryData at render (no GET exists; mutation setQueryData
|
||
re-renders); edit PUT preserves is_suggested. 3 tests.
|
||
- **F7 Local/Lookup**: rtype=[A,AAAA,CNAME], ttl optional default 300. SPEC
|
||
CORRECTION: Lookup.local_records is a BOOLEAN (ruling 16 said "list" loosely) —
|
||
rendered Yes/No; verdict priority local > blocked > forwarded > allowed (pipeline
|
||
order per lookup.zig), verdictOf exported. Local mutations live, no banner.
|
||
4 tests.
|
||
- **F8 Settings/Pause**: patchRequiresRestart(patch) exported — banner raised for
|
||
any patch except bare web.password; restartBanner.ts is a useSyncExternalStore
|
||
MODULE store (accepted deviation from ruling 24's "context": keeps the AppShell
|
||
edit to import + mount). Number inputs NaN-guard blocks Save. PauseWidget:
|
||
refetchInterval 5s only while paused, 1s countdown, formatRemaining exported.
|
||
16 tests.
|
||
- **Orchestrator integration**: the wave produced three near-identical inline-error
|
||
components (clients+groups InlineError, local FormError) — hoisted post-wave to
|
||
`src/lib/InlineError.tsx` (the richer variant: 400/409 verbatim, 429 countdown,
|
||
503 distinct, non-Error → "could not reach"), seven imports updated, duplicates
|
||
deleted. Dashboard's InlineError (query-level, onRetry) is a different component
|
||
and stays local. Full chain re-verified green after the hoist.
|
||
|
||
---
|
||
|
||
## Session F9: CI + embed + smoke (after F3-F8)
|
||
|
||
Owns: `.gitea/workflows/ci.yml` (ruling 22). Steps: verify `npm ci` reproducibility,
|
||
frontend job, cross-job additions with `-Dweb-dist=web/dist` + size assert.
|
||
Smoke (report transcript): `npm run build`; `zig build -Dweb-dist=web/dist`; boot;
|
||
curl `/` returns the SPA index (not the placeholder); a deep link (`/settings`)
|
||
returns 200 index; an asset serves gzip with ETag/304; login via browser-shaped curl
|
||
flow still works; SIGTERM 0. Also `zig build test` and `-Dintegration` still green
|
||
(the Zig tests embed the dist too — W10 static tests must still pass against the SPA
|
||
dist; if one pins placeholder content, report it, do not edit Zig).
|
||
|
||
### F9 As built
|
||
|
||
ci.yml +77/-5: top-level `NODE_VERSION: "24"`; new `frontend` job (setup-node@v4,
|
||
cache npm on web/package-lock.json; npm ci → format:check → lint → typecheck →
|
||
`npm test` → build); `cross` job builds the SPA then
|
||
`zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe` — RULED deviation:
|
||
build.zig has no strip option and Debug exes are 87/32 MB (25.6 MB stripped), so the
|
||
PLAN:639 budget is only meaningful for release builds; PLAN:50 calls these release
|
||
binaries. Size assert strips COPIES via binutils (zig objcopy --strip-all is
|
||
unimplemented in 0.16; aarch64 needs binutils-aarch64-linux-gnu, apt-installed
|
||
conditionally). Measured ReleaseSafe: raw ~24.2 MB each; stripped x86_64 5,501,624
|
||
bytes (PASS < 15 MB), aarch64 PT_LOAD total 4.87 MB (~5 MB stripped, asserted in CI).
|
||
`test` job stays Zig-only on the placeholder dist.
|
||
Smoke (embedded SPA): / serves the vite index (not the placeholder), /settings deep
|
||
link 200, main chunk served gzip with ETag then 304 on If-None-Match, login round
|
||
trip (401 → cookie → 200 → logout → 401), SIGTERM exit 0.
|
||
Finding, fixed post-session under an orchestrator ruling (narrow Zig-freeze
|
||
exception): the W8 test at static.zig:413 pinned placeholder strings and failed with
|
||
any real dist — rewritten dist-agnostic (structural asserts: /index.html exists,
|
||
text/html, gz siblings have base entries, quoted etags, no duplicate paths).
|
||
Import CLI note: the config file is positional on `nxdns import` (no --config flag).
|
||
|
||
---
|
||
|
||
## Module layout (new)
|
||
|
||
web/{package.json, package-lock.json, index.html, vite.config.ts, tsconfig*.json},
|
||
web/src/{main.tsx, routes.tsx, styles.css}, web/src/shell/*, web/src/lib/*,
|
||
web/src/auth/*, web/src/features/{dashboard,queries,live,clients,groups,blocklists,
|
||
rules,local,lookup,settings,pause}/*.
|
||
|
||
## File ownership
|
||
|
||
F1 scaffold+shell+routes; F2 lib+auth; F3-F8 exactly their feature dirs (routes.tsx
|
||
lazy imports point at stable paths F1 fixes up-front, so page sessions never edit
|
||
routes.tsx; F8 alone replaces the PauseWidget file F1 created); F9 ci.yml. Orchestrator:
|
||
spec, integration wiring if any. Parallel sessions never share a file.
|
||
|
||
## Acceptance (milestone complete)
|
||
|
||
- [ ] `npm ci`, format/lint/typecheck/vitest, `vite build` all green in web/.
|
||
- [ ] All ten pages implemented per rulings; login + pause + restart banner work.
|
||
- [ ] `zig build cross -Dweb-dist=web/dist` green; exes < 15 MB; W10 suite still green.
|
||
- [ ] F9 smoke transcript: SPA served embedded, deep link 200, gzip+ETag, SIGTERM 0.
|
||
- [ ] CI has the frontend job and the cross-job embed per ruling 22.
|
||
- [ ] Spec As-built synced per session.
|
||
|
||
## Review (Codex, As built)
|
||
|
||
Round 1: 7 important + 4 minor, all fixed.
|
||
- auth: AuthProvider probes once on mount when authRequired is null (dedupe kept;
|
||
sessionStorage fast path, probe overwrites); logout swallows ONLY 401 — other errors
|
||
rethrow and AppShell's LogoutButton renders them via InlineError, navigating only on
|
||
success; LoginPage 429 is a ticking lockout (submit + Enter disabled until zero).
|
||
- queries: load-more generation counter — filter apply/clear increments; then/catch/
|
||
finally discard stale completions (no old-filter rows, no stale cursor); imperative
|
||
401s route through `handleUnauthorized` (newly exported from lib/queryClient).
|
||
- live: gap-resync 401 → handleUnauthorized (never resyncFailed); entering capped
|
||
fires a one-shot injectable probeSession (default GET /api/pause) so an expired
|
||
session redirects to login instead of reading as "capped".
|
||
- settings: fieldset disabled while the PUT is pending (no silently dropped edits);
|
||
errors via InlineError.
|
||
- pause: mutation errors rendered via InlineError in both branches (were silent);
|
||
stale error resets on pause-state flip.
|
||
- blocklists/rules: all mutation errors via InlineError (429 countdown); form error
|
||
props are Error|null now.
|
||
- Ripple: the auth mount probe legitimately fires POST /api/auth/login before page
|
||
fetches — LocalDnsPage.test's first-POST assertion narrowed to match by URL.
|
||
After fixes: 24 files / 120 web tests green; Zig suite with the fresh dist 0 failed.
|
||
|
||
Round 2: 1 important + 1 minor, both fixed. (a) keepPreviousData left the OLD
|
||
filter's cursor clickable during the placeholder window — loadMore and the button now
|
||
bail on base.isPlaceholderData (chosen over isFetching so background refetches of the
|
||
current key stay usable); regression test proves no new-filter/old-cursor request.
|
||
(b) safeRedirect accepted backslash network paths — now
|
||
`/^\/(?![/\\])/.test(raw) && !raw.includes("\\")`, with unit cases.
|
||
|
||
Round 3: no findings. Final: 121 web tests green.
|
||
|
||
## Anti-requirements
|
||
|
||
No SSR, no chart library, no codegen (openapi→TS), no msw, no ESLint, no i18n, no
|
||
dark-mode toggle, no WebSocket, no service worker/PWA, no Zig changes, no docs/api
|
||
rendering (Phase 10), no DoH/DoT UI (Phase 9 adds settings sections it already has).
|