` — from `layouts/default.html`. **Ceremony screens** — the login page and the forced-password-change gate — use `layouts/auth.html`: a header with the brand mark and Documentation link, a content main and a footer, with the resolved theme, font preloads, progress bar, htmx and the toast stack. The login main holds the two-column story/preview and sign-in composition (#619); the forced-password-change gate keeps its centred card. No menu, no resource browser, no top bar, no workspace switcher, no `#app-main`, no `hx-boost` anywhere in the layout. A ceremony screen exists to move a visitor across the session boundary; until that move completes there is nothing to navigate to, so a shell around it is a menu of dead ends — and, since `#app-main` is the boosted swap target, a shell around it is also a screen that can be swapped into an app page. `AuthLayoutRenderTest` pins both layouts, including that the login page renders no shell even when handed an authenticated model. *Before 090 the login page decorated with `layouts/default`, which renders the shell whenever `authenticated` is true, so a signed-in visitor who opened `/login` in a second tab got the sign-in form inside a working app (owner's walk, 2026-09-07). Both halves are closed: the layout above, and the redirect in §4.1.* 5. **Three URL spaces, never mixed.** Pages, HTML fragments, and JSON live under distinct prefixes — see §2.1. 6. **The server holds no UI state.** The app is stateless behind a load balancer with no sticky sessions ([Deployment](/docs/deployment.md)); every user preference that must survive a request lives on the `users` row, never in an `HttpSession`. 7. **Scopes are not asserted here.** The per-screen scope column in §4 is a convenience view of the authoritative matrix in [Auth §7.6](/docs/auth.md#76-operation-matrix--the-permission-catalog-authoritative). 8. **Structure must survive a bad monitor — non-text contrast floors (WCAG 1.4.11).** Boundaries a user needs to identify a component are NOT text and have their own floors, enforced by the design-system audit (its `npm run build` runs it first; the vendored copy is guarded here by `VendoredNonTextContrastTest` in `modules/web`): `border-default`/`border-hover`/`border-focus` at **3:1** on the surface they are drawn on (inputs, panes, cards), `border-subtle` at **2:1** (separators — 3:1 makes every table heavy), `surface-selected` at **1.5:1** with a left accent bar of `border-focus` width `3px` (a tint alone cannot reach 3:1 without turning grey). A pane or card boundary is a `border-default` line, never a tint alone. Text keeps its 4.5:1 floors, unchanged. #606 distinguishes those boundaries from required separators (`--border-subtle`, 2:1) and nonessential decoration (`--app-line-decorative`, derived from the separator and panel surface); nothing required may rely on the decorative role. Where the approved prototype draws no line, the app draws none. 9. **Every table is the data table (282, §3.7).** One house component — `.dt-frame` › `.dt-viewport` › `table.ds-table`, one rule set (`data-table.css`) and one enhancer (`data-table.js`) — draws every table in the app: the header stays while the rows scroll, the scrollbar starts under the header (the cap), columns sort and resize, a wide table's first column can hold, and loading and empty are rows of the same table. No screen styles a table of its own; a new table is framed or `DataTableCssTokenTest` names it. A grid library was assessed and set aside (#282: AG Grid's theming injects styles at runtime, and the CSP is `style-src 'self'` with no nonce). ### 2.1 Route Convention Three disjoint URL spaces, plus one shape that lives on the first of them. A given URL belongs to exactly one space, and the response media type follows from the space — not from the caller. | Space | Prefix | Returns | Called by | |---|---|---|---| | **UI pages** | root paths — `/`, `/pipelines`, `/pipelines/{id}`, `/executions/{id}`, `/settings/api-keys`, `/admin/users` | full HTML document (Thymeleaf layout + content) | browser navigation | | **Page-route mutation (PRG)** | a POST on a root path — `/workspaces/create`, `/workspaces/{name}/join\|members\|members/{id}/remove\|delete`, `/workspace/switch`, `/promotion/promote`, `/login` | a **redirect** back to the page it came from (Spring's `redirect:` view — 302), carrying `?ok=`/`?error=` | a plain `

` | | **htmx partials** | `/partials/**` | HTML **fragment** (no layout, no envelope) | htmx `hx-get`/`hx-post`/`hx-patch`/`hx-delete` | | **JSON API** | `/api/v1/**` | JSON [response envelope](/docs/rest-api.md#4-response-envelopes) | agents, MCP, programmatic clients, the pipeline editor's `fetch` calls | **Page-route mutations are the exception, and the list above is closed.** A mutation may live on a page route for exactly two reasons: its success changes the **SHELL** — the workspace switch re-mints the session cookie, a new or deleted workspace changes the switcher, a promotion changes the deployment the whole screen describes — or it must work **without JS**, which is what makes workspace administration and sign-in usable when the app is misbehaving. Everything else mutates at `/partials` and reports through a §5.1 toast. Its response contract, so the idiom cannot drift into a third one: - **A redirect back to the page**, never a rendered body. Post/redirect/get is what makes a reload harmless, and it is what lets the whole shell re-render around a changed identity. - **`?ok=` / `?error=` KEYS, never free text**: a short token (`?ok=created`, `?error=user_not_found`) that the layout maps to copy. A message passed through the query string is untranslatable, unstylable, and forgeable by anyone who can hand a user a link. - **The outcome is still a §5.1 toast** — this space has no second error idiom. The layout renders the key into the hidden `#toast-flash` bin inside `#app-main` (076 §B) and `toast.js` adopts it into the persistent `#toast` stack, so a redirect flash and an htmx refusal reach the user as the same object. The key→copy table lives in `layouts/default.html` beside the bin: an unmapped key renders nothing, which is the safe direction. - Every one of these handlers is **session-only** where it changes privilege or identity, and each is listed with its reason in `MutatingHandlerScopeFloorTest.PAGE_ROUTE_MUTATIONS`. A new one fails that test until the reason is written down. **htmx never calls `/api/v1`.** A JSON envelope is not a swappable fragment; pointing `hx-*` at the REST API would require client-side rendering, which principle 1 rules out. Every htmx interaction in §4 targets `/partials/**`. **Partials are a presentation layer, not a second implementation.** A `/partials/**` controller calls the *same* application service as its REST counterpart and renders the result into a Thymeleaf fragment. `POST /partials/api-keys` and `POST /api/v1/auth/api-keys` ([REST §16.1](/docs/rest-api.md#161-api-keys-creation-is-on-the-keys-page--keys-v2)) differ only in how the response is serialized — same service, same validation, same refusal. **Auth on partials.** `/partials/**` is authenticated by the `dp_session` JWT cookie (never by `DP-API-Key` — API keys are for agents). State-changing partial requests (`POST`/`PATCH`/`DELETE`) are CSRF-protected: the frontend sends the `dp_csrf` cookie value in the `DP-CSRF-Token` header ([Auth §8.4](/docs/auth.md#84-api-endpoints-auth-via-api-key-or-jwt)). This is wired once in the layout (§3), not per-screen. **The one carve-out — file downloads.** Result downloads (§4.9) are plain `` full-page navigations to the REST cursor endpoint, because the response is a file (CSV/Arrow/JSON), not a fragment. That is a browser navigation, not an htmx swap, so it does not violate the rule above; it authenticates with the same `dp_session` cookie. --- ## 3. Common Layout All authenticated pages use a shared layout: ``` ┌──────────────┬──────────────────────┬──────────────────────────────────────┐ │ ▣ datapipe… │ Pipelines 9 ⟨⟨ │ Build / Pipelines 📁 [⌘K] ☀ (MS) │ --app-header-h (58px) │ ┌──────────┐ ├──────────────────────┼──────────────────────────────────────┤ │ │TS workspc│ │ [search] ✕ ↻ │ │ │ └──────────┘ │ ▸ acme │ │ │ Home │ ▸ mobility │ Page content │ │ BUILD │ daily_by_zone │ (

, the │ │ Pipelines │ ▸ finance │ one scroll container) │ │ Templates │ │ │ │ Datasources │ │ │ │ EXPLORE │ │ │ │ Dashboards │ │ │ │ Visualiz… │ │ │ │ Param. Sets │ │ │ │ OPERATE … │ │ │ │ ORGANISAT… │ View all pipelines ⟲ │ │ │ ◀ Collapse │ ┆ ← #browser-boundary (resize) │ └──────────────┴──────────────────────┴──────────────────────────────────────┘ menu: 202px browser: 340 / 320 / 270 by band, main: minmax(0, 1fr), (64px compact) 280–480 by the user; hidden off a never under 320px family page (its width goes to main) ``` Thymeleaf layout: `layouts/default.html` — includes navbar, design system CSS, htmx, theme switcher. The layout also wires these once, for every shell page (`ShellPage`, #652): the four `@ControllerAdvice`s below select on that marker, so a JSON (`@RestController`) handler never pays the shell's reads (§3.4). - **Theme resolution.** The active design-system theme is `users.theme_preference` when set, otherwise the deployment default `datapipelines.ui.theme` ([Configuration §3.10](/docs/configuration.md#310-ui)). `UiWorkspaceAdvice` resolves it per request into `${activeTheme}` for every shell screen (#652; a controller that forgets it renders a `themes/null.css` URL that 404s, leaving every design token unresolved — no borders, no surfaces); individual controllers may still set it explicitly, which simply overrides the advice's value with the same one. Emitted as the `href` of the `#theme-link` stylesheet element ([Pipeline Editor §3.4](/docs/pipeline-editor.md#34-design-system-acmedesign-tokens)) — see §4.11. The deployment setting is the default, not a ceiling: a user preference overrides it for that user only, and an unset preference is indistinguishable from today's config-only behaviour. - **Nav chrome (027 UI pass).** The navbar is a sticky, full-width bar whose links and Logout render only for authenticated requests (`UiWorkspaceAdvice.authenticated` — anonymous screens like Login see the brand only). The active section is highlighted from `UiWorkspaceAdvice.currentPath` on first paint, and mirrored client-side by `shell.js` after boosted swaps (§3.2). Nav and content share the `.app-container` shell (app.css) — full-bleed with one gutter since 076 (§3.1). App-level chrome and table polish live in `static/css/app.css` — the vendored design system files are synced from design-system-starter and are never edited in this repo. - **CSRF for htmx.** `hx-headers` on `` carries the `dp_csrf` cookie value as `DP-CSRF-Token`; because `hx-headers` is inherited, every descendant htmx request is covered ([Auth §8.4](/docs/auth.md#84-api-endpoints-auth-via-api-key-or-jwt)). - **Workspace switcher + context (workspaces design §9).** The navbar carries a `