Harden Druks UI and make it the scaffold default

[czpython]

ENG-906

Server-driven pages are now the path a new app takes by default, and the
surface is held to its own contract by tests that read the same wire snapshot
from both sides.

The scaffold

druks create app writes pages.py with a landing page, navigation naming
it, and no JavaScript: no Node, no React, no dist/. The generated AGENTS.md
states the page-purity contract and points at the UI contract, and the
generated suite renders the landing page. An app that needs full control of its
interface still ships an ESM frontend, which the author guide now describes as
the escape hatch it is — and says the author creates that dist/ themselves.

When a page fails

A page read that goes wrong answers PAGE_FAILED and names the app and the
page. What the app's own code said never reaches the browser — not its message
and not its type, either of which can carry a query, a URL, a credential, or
the name of a library. That stays in the process log. Druks says which of three
things happened: the page raised, it answered with something that is not a
Page, or it named an operation the app does not declare. The shell keeps all
three inside the app surface with a retry.

An Action exists only once a page function has run, so its reference is
checked when Druks builds the page — the earliest moment it exists. Everything
knowable earlier still fails the load: a repeated operation_id, one route
answering two methods, a page table no request could resolve, a navigation
entry that is not a static top-level page, a nested child, and a router on a
reserved segment.

Held to the contract

The proof app gained a catalog page carrying one of every block, value, and
field, and the exact wire it serializes is checked in as
frontend/src/druksui/catalog.json. The backend suite compares the live HTTP
response against that file and against the unions themselves, so a name added
to druks.ui with no example fails. The renderer's own suite renders that same
file. A field renamed on one side and not the other fails a suite instead of a
browser, and the backend workflow now runs when the renderer or the wire types
change.

That suite also holds every V1 renderer to alternative text, labelled inputs,
controls that are named and take focus, a spoken progress state, the chart's
numbers in a table, real column headers, and form-scoped control ids so two
forms sharing a field name keep their labels and radio groups apart.

How it is verified

Gates run: uv run ruff check backend, uv run ruff format --check backend,
npm --prefix frontend run lint, npm --prefix frontend test (209 tests
pass), npm --prefix frontend run build. uv run pytest backend/ did not run:
this machine has no Postgres or Redis. The scaffold, page-table, block, action,
and page-failure tests that need no database were run directly, and all pass.

Two limits worth naming. The accessibility suite runs in jsdom, so it holds
focus order, names, and roles, but a browser is still what would prove visible
focus, the dark theme, and a narrow viewport. And the proof app is the
standalone package fixture the contract tests read: this repository still ships
it, so a second one would only duplicate it.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
druks	🟢 Ready	View Preview	Aug 30, 2026, 12:25 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.