ui: the web interface

.dockerignore

@@ -7,5 +7,4 @@ node_modules
 .env
 test
 docs
-brand
 *.md

.github/workflows/ci.yml

@@ -88,9 +88,10 @@ jobs:
   # `durability` both call `down -v`.
   stack:
     runs-on: ubuntu-latest
-    # Six suites now, each bringing the stack up for itself, one of them
-    # obtaining certificates from a local authority. Three and a half minutes
-    # with warm images locally; a cold runner builds the image first.
+    # Seven suites now, each bringing the stack up for itself, one of them
+    # obtaining certificates from a local authority and one driving a browser
+    # from Playwright's image. Four minutes with warm images locally; a cold
+    # runner builds the image first and pulls the browser's (about 1 GB).
     timeout-minutes: 40
     steps:
       - uses: actions/checkout@v7

.gitignore

@@ -46,3 +46,8 @@ docker-compose.override.yml
 # The TLS suite writes the local certificate authority root and the test DNS
 # zone here before it starts the stack.
 test/stack/tmp/
+
+# tsc -b's own incremental build output for the interface package. Vite owns
+# dist/ (already ignored above); this is a separate directory so the two
+# builds never delete each other's output, and nothing reads it.
+packages/ui/dist-ts/

.gitleaksignore

@@ -0,0 +1,6 @@
+# Test fixtures that look like secrets and are not: a made-up API key whose
+# secret part is base64 of "secret-secret-…", and a DNS verification token of
+# hex digits in order. Each line is gitleaks' fingerprint of the commit that
+# introduced the fixture; history is kept, so the fingerprint is the only fix.
+d0334a0c90754bdca095ee6967253ae30ca60d43:packages/ui/src/screens/account/ApiKeys.test.tsx:generic-api-key:8
+792d0fb97eafb920a7857ca969d10bea93ee45e4:packages/ui/src/screens/domains/Domains.test.tsx:generic-api-key:11

CLAUDE.md

@@ -50,10 +50,12 @@ pass), the admin
 API (one account, sessions, TOTP with recovery codes, API keys, domain/link/settings
 CRUD, answering on `CLICKMONK_ADMIN_HOST` alone — unset, every route but `/health` is a
 503 and links serve exactly as before), reporting over that API (a summary, a chart by
-hour or day, a breakdown over nine dimensions, the raw click log and a streamed CSV of it,
-all reading hourly rollups except the log and its export), retention (two periods on the
-settings row, enforced hourly by the worker, dropping raw clicks a partition at a time and
-blanking the address on a click in place), the CLI (`migrate`,
+hour or day, a breakdown over ten dimensions, the raw click log and a streamed CSV of it,
+all reading hourly rollups except the log and its export), the web interface (a React app
+the admin service serves from that same host, behind the same host guard — every screen
+built on the admin API and nothing it can reach that a script cannot), retention (two
+periods on the settings row, enforced hourly by the worker, dropping raw clicks a partition
+at a time and blanking the address on a click in place), the CLI (`migrate`,
 `domain add|list|verify`, `link add`, `settings show|set`, `ipdata status|update`,
 `admin create|passwd`, `admin totp disable`, `apikey create|list|revoke`), `install.sh`, a
 Compose stack, and the restart durability and stack test suites.
@@ -75,31 +77,28 @@ mistyped host name is not a reason to take every link on the install down.
 
 What does not exist yet, and must not be implied by any documentation:
 
-- **A web UI.** There is an admin API; nothing draws it yet, and it cannot be reached over
-  plain HTTP at all — the admin host answers 308, and the session cookie is `Secure` with
-  the `__Host-` prefix — so unlike a link domain it cannot be tried on a laptop.
 - **More than one admin account.** One account is the whole of the access control: no
   roles, no second person, no attribution of who did what. An API key is the only
   credential that can be handed out and revoked on its own, and it is not a person.
 - **A way back in over the API when both factors are lost.** Removing the second factor
   there requires the second factor. `clickmonk admin totp disable` is the answer, and it is
   a command on the server for that reason.
-- **Anything drawn.** The reports are JSON and nothing plots them. There is no dashboard,
-  so how fresh the numbers are is `newestHour` in the summary and the chart rather than
-  something on a screen.
-- **A CSV of a report.** The export is the click log. A summary or a breakdown is one small
-  answer already, and turning it into a file belongs to the web interface.
-- **A time zone.** Every window, bucket and retention period is UTC, and a preset like
-  "yesterday" is the caller's to compute. The hourly grain leaves a whole-hour offset
-  possible later without a schema change; a half-hour zone would need one.
+- **A CSV of a report, from the API itself.** `GET /api/clicks.csv` streams the click log
+  only. A summary or a breakdown is one small answer already, and turning one into a file is
+  the web interface's own doing, client-side, not a route the API streams.
+- **A time zone, on the API.** Every window and retention period it takes is UTC, and so is a
+  chart's bucket size — `offset` only moves where a day bucket begins, in whole hours, and does
+  nothing for an hourly one. The web interface computes a preset like "yesterday" from the
+  browser's own zone; a caller of the API directly still has to — see
+  `packages/ui/src/window/range.ts`.
 - **Notifications of any kind.** No mail configuration exists; `GET /api/alerts` is what
   an operator reads instead.
 - **Most link settings in the CLI.** `link add` takes `--target`, `--backup`, `--cap`,
   `--expires`, `--no-passthrough` and `--action` only, and no command changes a link
   after `link add`. `settings set` sets the install-wide traffic actions, the safe URL,
   the abuser threshold and the two retention periods. Device URLs, a returning URL,
-  country rules, a name, a password and the disabled state are the admin API's, or
-  hand-written SQL without it.
+  country rules, a name, a password and the disabled state are the admin API's and the web
+  interface's, or hand-written SQL without it.
   A returning URL also needs HTTPS to do anything: its cookie is marked `Secure`, so a
   browser drops it over plain HTTP.
 - **Proxy/VPN detection beyond Tor exits, cloud providers' published ranges, and region
@@ -161,6 +160,11 @@ packages/worker/    ships the spool into ClickHouse; runs migrations on boot;
                     writer of the settings row that the CLI and the admin API share.
 packages/admin/     the admin API: sessions, API keys, TOTP, domain/link/settings CRUD,
                     the reports, the click log and its CSV export.
+packages/ui/        the web interface: React 19, Tailwind 4, a Vite build the admin
+                    service serves from its own host and dist/. No colour in source, no
+                    Radix overlay primitive, no runtime import from a service package,
+                    one <h1> per screen. Every time shown is the browser's own zone, except a
+                    click's raw fields, which are labelled UTC.
 packages/cli/       `clickmonk migrate | domain | link add | settings | ipdata | admin | apikey`.
                     Two commands here are deliberately not API routes: `admin create`,
                     because nothing can authenticate before the account exists, and
@@ -178,7 +182,9 @@ test/stack/         brings the whole stack up against a local certificate author
                     certificate, a sign-in over HTTPS, a password-protected link
                     answered end to end, a click driven through the whole stack and
                     read back as a report, a log page and a CSV, and a retention
-                    period lowered and then enforced.
+                    period lowered and then enforced. `ui.test.ts` drives the web
+                    interface itself in a real browser, on that same stack, and fails
+                    on any content security policy violation on any screen.
 ```
 
 Three properties of the product shape every change:
@@ -200,6 +206,12 @@ pnpm build        # required before the first `pnpm test`
 pnpm test
 ```
 
+**`pnpm test` is two suites, run one after the other: the service packages' own Vitest run,
+then `packages/ui`'s** (`vitest run && pnpm --filter @clickmonk/ui test`). The interface's
+suite has its own config and runs in `Australia/Adelaide`; see `packages/ui/vitest.config.ts`
+and CONTRIBUTING.md. Neither talks to the browser suite in `test/stack/`, which is part of
+the stack suites below.
+
 **Build before the first test run, and after changing `core`, `db`, `ipdata`, `worker` or
 `admin`.**
 Packages import each other by name, which resolves to the *built* `dist/`, and `dist/`
@@ -288,6 +300,13 @@ These hold from the first line of code, whatever the stack turns out to be:
   migration changes fresh installs only. Fix it forward in a new one.
 - **A redirect never waits on reporting.** Recording a click is not allowed to add
   latency to, or a failure mode to, sending the visitor on.
+- **`packages/ui/src` writes no colour of its own.** A colour bypasses the measured brand
+  roles; use a semantic class or `var(--color-…)`.
+- **`packages/ui` ships no Radix overlay primitive, no inline script or style, and no
+  runtime import from a service package.** The first two the content security policy
+  refuses outright; the third throws at load in a browser that has no Node behind it.
+- **Every screen in `packages/ui` has exactly one `<h1>`**, asserted by heading level, not
+  by its text.
 
 ## Writing tests here
 

CONTRIBUTING.md

@@ -31,6 +31,40 @@ You need Node 22, Docker with Compose v2, and `corepack` (it ships with Node). T
 
 `CLAUDE.md` explains why the build comes before the tests, and the order CI runs checks in.
 
+### Working on the web interface
+
+`packages/ui` is a React app the admin service serves. From the repo root:
+
+    pnpm --filter @clickmonk/ui test    # unit suite
+    pnpm --filter @clickmonk/ui build   # tsc -b, then the production build
+
+The unit suite runs in `Australia/Adelaide` on purpose — a zone that is not a whole number of
+hours from UTC and observes daylight saving — so time logic that is only right in UTC fails
+here. It runs as part of the root `pnpm test` too.
+
+The browser suite drives a real browser against the shipped stack over HTTPS, so it goes
+through the stack suites (see "The stack suites" above), not `pnpm --filter @clickmonk/ui
+test`. Set `CLICKMONK_SHOTS=1` to have that run also write a screenshot of every screen, in
+both themes and at two widths, to `test/stack/tmp/e2e/shots/`.
+
+Rules the source-rule tests enforce, each with its own reason:
+
+- **No colour in `packages/ui/src`** — no hex, `rgb()`/`hsl()`/`oklch()`, named colour, or
+  Tailwind palette class. A colour that bypasses the measured brand roles can pass contrast in
+  one theme and fail in the other. Use a semantic class (`bg-primary`, `text-destructive`…) or,
+  in SVG, `var(--color-…)`.
+- **No Radix overlay primitive** (`Dialog`, `Select`, `Popover`…) — they inject a `<style>`
+  element at runtime, which the content security policy refuses. Use the native `<dialog>` in
+  `components/ui/modal.tsx`, or a native `<select>`.
+- **No inline script or style in the built output** — the same policy has no exception for one,
+  so it would be silently blocked rather than shown.
+- **No runtime import from `@clickmonk/core`** (`import type` only) — a service package pulls in
+  Node modules that throw when a browser bundle evaluates them, which is a blank page. Restate
+  the value in `api/vocabulary.ts`, whose test checks it against the service's own.
+- **Every screen has exactly one `<h1>`**, through `PageHeader`; a card or section title is an
+  `<h2>`. Tests assert this by heading level, not by text, so a change that demotes a page's
+  only heading is caught.
+
 ## Code of conduct
 
 All participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).

Dockerfile

@@ -3,6 +3,10 @@ WORKDIR /app
 RUN corepack enable
 COPY pnpm-workspace.yaml package.json pnpm-lock.yaml tsconfig.base.json tsconfig.json ./
 COPY packages ./packages
+# The interface's stylesheet imports the brand's tokens from brand/, outside
+# packages/. Only the build stage reads it: Vite writes everything it takes from
+# there into packages/ui/dist, and nothing at runtime reads brand/ again.
+COPY brand ./brand
 # build:image compiles each package without its tests or the database test
 # helpers, which exist only to run the test suite.
 RUN pnpm install --frozen-lockfile && pnpm build:image
@@ -35,6 +39,9 @@ COPY --from=build /app/packages/db/dist packages/db/dist
 COPY --from=build /app/packages/ipdata/dist packages/ipdata/dist
 COPY --from=build /app/packages/redirect/dist packages/redirect/dist
 COPY --from=build /app/packages/admin/dist packages/admin/dist
+# No package.json for the interface: it has no runtime dependencies, only the
+# files the admin service serves, built in the stage above.
+COPY --from=build /app/packages/ui/dist packages/ui/dist
 COPY --from=build /app/packages/worker/dist packages/worker/dist
 COPY --from=build /app/packages/cli/dist packages/cli/dist
 USER clickmonk