@pablozaiden/webapp 0.5.8 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @pablozaiden/webapp
 
-Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, realtime websocket state, scoped settings, binary builds and Docker images.
+Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, stateless CLI API-key auth, realtime websocket state, scoped settings, binary builds and Docker images.
 
 ## Quick start
 
@@ -14,6 +14,10 @@ bun run dev:kitchen-sink
 
 Both examples run with Bun native hot reload through `bun --hot`, with no standalone frontend build server and no external `WEB_DIST_DIR`.
 
+## Application dependencies
+
+Each application package must declare `react` and `react-dom`; they are peer dependencies of the framework. Bun resolves `react-dom/client` from the application package context, so workspace installs do not need to hoist React packages to a repository root. Native startup and binary builds fail early with the application context when `react-dom` is not installed.
+
 ## Main exports
 
 | Export | Use |
@@ -21,7 +25,11 @@ Both examples run with Bun native hot reload through `bun --hot`, with no standa
 | `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
 | `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
-| `@pablozaiden/webapp/cli` | One-binary command helpers, device-auth credentials and generic API CLI caller |
+| `@pablozaiden/webapp/cli` | One-binary command helpers, device/environment auth credentials and generic API CLI caller |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |
 
-See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Use `bun run screenshots` for reproducible manual visual captures. Release/publishing details for this package are in `docs/release.md`.
+See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Release/publishing details for this package are in `docs/release.md`.
+
+CLI API callers can use a stored device session or the stateless
+`${PREFIX}_BASE_URL` and `${PREFIX}_API_KEY` environment pair; see
+`docs/cli.md` for precedence and anonymous fallback behavior.

package/docs/auth-validation.md

@@ -40,6 +40,17 @@ Run this checklist before releasing a framework app or cutting a checkpoint.
 4. Delete the key from Settings and confirm the confirmation dialog appears.
 5. Confirm the deleted token no longer authenticates.
 
+## CLI API-key authentication
+
+1. Set `${PREFIX}_BASE_URL` and `${PREFIX}_API_KEY` for an app whose CLI passes
+   its `envPrefix` to `runApiCliCommand()`.
+2. Run a protected API command and confirm it reaches the configured server
+   without starting an interactive device flow.
+3. Remove either variable and confirm the request falls back to anonymous
+   behavior.
+4. Use an expired, invalid, or insufficient-scope key and confirm the CLI
+   reports the server rejection without refreshing or retrying the key.
+
 ## Device auth
 
 1. Call `POST /api/auth/device` with `client_id` and `scope`.

package/docs/auth.md

@@ -59,3 +59,28 @@ Device codes are one-use. Device sessions are self-only in Settings, and only ac
 ## Same-origin policy
 
 Cookie/browser mutations require matching `Origin` or `Referer` by default. Use `sameOrigin: "never"` only for deliberate public/server-to-server routes; use `sameOrigin: "always"` for especially sensitive endpoints even when bearer tokens are used.
+
+## Reverse-proxy request trust
+
+Forwarded request headers are ignored by default. When
+`{PREFIX}_TRUST_PROXY=true` is enabled, the policy explicitly selects the
+supported `X-Forwarded-Proto`, `X-Forwarded-Host`, and
+`X-Forwarded-Prefix` values through `{PREFIX}_TRUST_PROXY_HEADERS`. Comma
+chains use the configured `{PREFIX}_TRUST_PROXY_CHAIN` value (`first` for the
+left-most non-empty value or `last` for the right-most non-empty value).
+Malformed or missing request values fall back to the direct request.
+
+The same normalized request context drives expected same-origin origins,
+WebSocket origin checks, passkey expected origins and RP IDs, the `Secure`
+cookie attribute, cookie paths, setup links, and device/discovery URLs.
+`{PREFIX}_PUBLIC_BASE_URL` is authoritative for origin, hostname, and secure
+state even when forwarded headers are present; trusted prefixes remain
+policy-controlled for path-bearing cookies and links.
+
+Trust mode is a deployment boundary setting, not a way to trust arbitrary
+client input. The reverse proxy must strip client-supplied forwarded headers
+and overwrite only the values configured above, preferably as sanitized
+single-value headers. Do not expose the application directly to untrusted
+clients when trust mode is enabled. This release does not implement a
+proxy-address allowlist, so the network boundary and proxy sanitization are
+required.

package/docs/cli.md

@@ -25,7 +25,9 @@ const result = await dispatchCliCommand({
 process.exitCode = printCliResult(result);
 ```
 
-Device-auth CLI helpers can be composed into apps that need authenticated CLI calls. Public-token commands, such as webhook notification commands, can stay app-owned and do not need framework auth.
+Device-auth and environment API-key helpers can be composed into apps that
+need authenticated CLI calls. Public-token commands, such as webhook
+notification commands, can stay app-owned and do not need framework auth.
 
 Route metadata can power generic API commands:
 
@@ -37,9 +39,77 @@ const catalog = createRouteCatalog(routes);
 const result = await runApiCliCommand({
   catalog,
   args,
-  baseUrl: "http://localhost:3000",
+  envPrefix: "MY_APP",
   credentials,
+  // Optional explicit override; stored credentials provide the default URL.
+  // baseUrl: "https://app.example.test",
 });
 ```
 
-`runApiCliCommand` can list endpoints, print schema metadata, call endpoints with `--method` and `--payload`, attach bearer credentials, and refresh once on `401`.
+`runApiCliCommand` can list endpoints, print schema metadata, call endpoints
+with `--method` and `--payload`, attach bearer credentials, and refresh stored
+device credentials once on `401`.
+When stored device credentials are available, their `baseUrl` is used by
+default; pass `baseUrl` only to intentionally override that server. Without
+stored credentials, the environment API-key rules below determine the request
+URL.
+
+## Stateless API-key authentication
+
+An app that passes its validated `envPrefix` to `runApiCliCommand` can make
+non-interactive authenticated requests with an API key:
+
+```bash
+export MY_APP_BASE_URL=https://app.example.test
+export MY_APP_API_KEY='key-from-settings'
+my-app api items
+```
+
+The helper derives exactly `${PREFIX}_BASE_URL` and `${PREFIX}_API_KEY` from
+the supplied prefix. When no stored device credentials are available, an
+explicit `baseUrl` plus `${PREFIX}_API_KEY` takes precedence; otherwise the
+complete environment pair supplies the request URL and bearer key. Values are
+trimmed, and the base URL must use `http` or `https`; trailing slashes are
+removed.
+
+If either environment variable is missing or empty, the pair is ignored and
+the request remains anonymous, using an explicit `baseUrl` or
+`http://localhost:3000`. A partial pair is not an error. Stored device
+credentials remain highest priority and continue to use their existing refresh
+and `401` retry behavior.
+
+The environment API-key path does not run interactive login or device
+authorization, refresh tokens, write credential files, or retry rejected
+requests. The key is supplied by the environment and kept in memory for the
+request; it is not printed or persisted by the CLI. The server remains
+responsible for API-key validity, expiry, and route scopes.
+
+## Concurrent credential refreshes
+
+`createJsonFileStore()` and `createDeviceCredentialsStore()` coordinate refreshes for
+the same credential path with an adjacent lock file. When credentials are expired,
+`refreshDeviceCredentials()` acquires that lock before calling the token endpoint,
+reads the store again, and reuses credentials another process may have refreshed.
+The write of newly refreshed credentials happens while the lock is held.
+
+The `JsonFileStore<T>.withLock()` method is optional so existing custom stores that
+only implement `path`, `read`, `write` and `clear` remain source-compatible. A
+custom store must provide `read` and `withLock` to receive the same cross-process
+refresh guarantee; otherwise the legacy refresh path is retained.
+
+```ts
+await store.withLock(async () => {
+  // Work serialized for this store path.
+}, {
+  timeoutMs: 30_000,
+  staleAfterMs: 300_000,
+  pollIntervalMs: 25,
+});
+```
+
+The defaults are a 30-second acquisition timeout, a five-minute stale threshold
+and a 25-millisecond polling interval. A timeout throws `JsonFileStoreLockError`
+with `code === "timeout"`. Release failures use `code === "release"`. Lock
+metadata contains only ownership information (PID, timestamp and nonce), never
+access or refresh tokens. The credentials directory and file retain `0700` and
+`0600` permissions respectively.

package/docs/deployment.md

@@ -17,6 +17,10 @@ await buildWebAppBinary({
 });
 ```
 
+The application package must declare both `react` and `react-dom` to satisfy the framework peer dependencies. The builder resolves `react-dom/client` through Bun from the application entrypoint, so strict or non-hoisted workspace layouts are supported. The browser dependency is bundled into the compiled binary; the build reports the application context and setup guidance before generating client output when `react-dom` cannot be resolved.
+
+`getBunCompileTargetFromArgs` accepts at most one `--target=<value>` argument. Supported compile targets come from the `BUN_COMPILE_TARGETS` export from `@pablozaiden/webapp/build`; use that collection when selecting a target. Empty, malformed, duplicate, and unsupported values fail before the builder creates output directories or invokes Bun. Omit the option for the default local Bun binary.
+
 The binary builder compiles the browser bundle with the framework defaults needed for `webapp` apps, including Tailwind CSS v4 processing. If an app needs extra browser build behavior, add Bun plugins or browser-only defines under `web.build`:
 
 ```ts
@@ -49,24 +53,97 @@ Keep server and CLI modes in the same binary. App-specific commands and framewor
 
 ## Docker
 
-Examples include Dockerfiles that copy a Bun-compiled Linux binary into a runtime image. Build the binary for the container architecture first, then build the image:
+The example Dockerfiles copy a Bun-compiled Linux binary into a runtime image. They intentionally require `APP_BINARY`; there is no architecture-specific default. Build the binary for the container architecture first, then pass both the Docker platform and matching binary path:
 
 ```bash
-bun run --cwd examples/notes-todo build --target=bun-linux-arm64
-docker build -f examples/notes-todo/Dockerfile -t webapp-notes-todo:local .
-
+# Linux amd64 (Bun calls this target x64)
+bun run --cwd examples/notes-todo build --target=bun-linux-x64
+docker buildx build \
+  --platform linux/amd64 \
+  --build-arg APP_BINARY=examples/notes-todo/dist/notes-todo-linux-x64 \
+  --file examples/notes-todo/Dockerfile \
+  --tag webapp-notes-todo:local \
+  --load \
+  .
+
+# Linux arm64
 bun run --cwd examples/kitchen-sink build --target=bun-linux-arm64
-docker build -f examples/kitchen-sink/Dockerfile -t webapp-kitchen-sink:local .
+docker buildx build \
+  --platform linux/arm64 \
+  --build-arg APP_BINARY=examples/kitchen-sink/dist/kitchen-sink-linux-arm64 \
+  --file examples/kitchen-sink/Dockerfile \
+  --tag webapp-kitchen-sink:local \
+  --load \
+  .
 ```
 
-The example Dockerfiles default to `node:22-bookworm` as a readily available Linux runtime base because the app itself is already a self-contained Bun binary. Use `--target=bun-linux-x64` and pass `--build-arg APP_BINARY=examples/notes-todo/dist/notes-todo-linux-x64` when building an x64 container from a different host. The container should set:
+Use the same mapping for either example: Docker `linux/amd64` requires the Bun `bun-linux-x64` build and `*-linux-x64` artifact, while Docker `linux/arm64` requires `bun-linux-arm64` and `*-linux-arm64`. To build an x64 image from an ARM64 host, select `--platform linux/amd64` and the x64 artifact explicitly; Docker Desktop or Buildx may need emulation enabled. Omitting `APP_BINARY`, selecting an unsupported target, or pairing the wrong artifact with the target fails during the image build.
+
+The example Dockerfiles default to `node:22-bookworm` as a readily available Linux runtime base because the app itself is already a self-contained Bun binary. The container writes both framework and example application data to `/app/data`; mount a Docker volume there when data must persist beyond the container.
+
+### Example application data files
+
+Each example uses the configured data directory for two separate persistence
+boundaries:
+
+| Application | Framework database | Application database |
+| --- | --- | --- |
+| Notes TODO | `webapp.sqlite` | `notes-todo.sqlite` |
+| Kitchen Sink | `webapp.sqlite` | `kitchen-sink.sqlite` |
+
+`webapp.sqlite` contains framework authentication and settings state. The
+example database contains only that example's sections, notes, todos, or
+projects; application-specific tables are not added to the framework store.
+The example starts by creating or migrating its schema, and owner seed data is
+transactional and idempotent across restarts.
+
+Persist the complete `/app/data` directory, not just `webapp.sqlite`, when
+deploying an example. A container filesystem, process restart, replacement
+deployment, or reverse proxy does not provide durability by itself. Retain
+and back up the volume mounted at `/app/data`; changing the data directory
+intentionally starts a new application state.
+
+The container should set:
 
 ```dockerfile
 ENV MY_APP_HOST=0.0.0.0
 ENV MY_APP_PORT=3000
-ENV MY_APP_DATA_DIR=/data
+ENV MY_APP_DATA_DIR=/app/data
 ```
 
 The framework has no external frontend asset directory, so the compiled binary contains the server and Bun HTML import graph.
 
+## Reverse proxy and forwarded headers
+
+When TLS or a public path is terminated by a reverse proxy, keep the
+application port reachable only from that proxy and configure the trust policy
+explicitly:
+
+```bash
+MY_APP_TRUST_PROXY=true
+MY_APP_TRUST_PROXY_HEADERS=proto,host,prefix
+MY_APP_TRUST_PROXY_CHAIN=first
+MY_APP_PUBLIC_BASE_URL=https://app.example.test
+```
+
+The proxy must strip any client-provided `X-Forwarded-Proto`,
+`X-Forwarded-Host`, and `X-Forwarded-Prefix` values before overwriting the
+headers it is responsible for. Only enable the corresponding symbolic
+headers in `MY_APP_TRUST_PROXY_HEADERS`. Sanitized single-value headers are
+recommended; `MY_APP_TRUST_PROXY_CHAIN` exists only to make a comma-separated
+chain deterministic. The framework does not infer trust from header presence,
+does not parse the RFC `Forwarded` header, and does not provide a
+proxy-address allowlist in this release.
+
+Use `MY_APP_PUBLIC_BASE_URL` when the external origin must remain deterministic
+regardless of request headers. A trusted prefix controls cookie paths and
+framework-generated setup/device links. If trust is disabled, the framework
+uses the direct request URL and host, which is the correct default for a
+direct deployment.
+
+Proxy configuration does not make application data persistent. Set
+`MY_APP_DATA_DIR` to a durable directory and mount a persistent volume for
+container deployments; the SQLite data must survive independently of the
+reverse proxy or application process.
+
 For full application CI/CD templates, including a production Dockerfile, PR checks, GHCR publishing on `main`, binary releases and Docker release images, see `docs/github-actions.md`.

package/docs/getting-started.md

@@ -3,20 +3,23 @@
 Apps are one Bun application: backend routes, websocket, React UI and static assets are served by the same server. The framework does not support or require a standalone client dist directory.
 
 ```ts
+import { z } from "zod";
 import { createWebAppServer, defineRoutes, jsonResponse, parseJson } from "@pablozaiden/webapp/server";
 
 const items: Array<{ id: string; userId: string; title: string }> = [];
+const itemCreateSchema = z.object({ title: z.string() });
 
 const routes = defineRoutes({
   "/api/items": {
     auth: "user",
+    requestSchema: itemCreateSchema,
     description: "List or create items.",
     cliPath: "items",
     tags: ["items"],
     GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items)),
     async POST(req, ctx) {
       const user = ctx.requireUser();
-      const body = await parseJson<{ title: string }>(req);
+      const body = await parseJson(req, itemCreateSchema);
       const item = { id: crypto.randomUUID(), userId: user.id, title: body.title };
       items.push(item);
       ctx.userRealtime.publishEntityChanged("items", item.id);
@@ -80,6 +83,18 @@ my-app api items
 my-app notify --message "optional app-owned command"
 ```
 
+For a non-interactive authenticated API command, pass the app's `envPrefix`
+to `runApiCliCommand()` and provide the exact environment pair:
+
+```bash
+export MY_APP_BASE_URL=https://app.example.test
+export MY_APP_API_KEY='key-from-settings'
+my-app api items
+```
+
+The pair is used when no stored device credentials are available. A missing
+or partial pair preserves anonymous CLI requests.
+
 See `docs/cli.md` for framework CLI helpers and generic API command support.
 
 Frontend entrypoints should use `renderWebApp` so Bun/browser hot reload reuses the existing React root instead of calling `createRoot()` twice. Import the framework CSS explicitly so Bun hot reload observes style changes:
@@ -107,7 +122,19 @@ renderWebApp(
 ```
 
 `renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
-`WebAppRoot` owns the shell and `.wapp-main-content`; each route component should return a `Page` wrapper so standard content margins, mobile padding and scroll behavior stay consistent.
+`WebAppRoot` owns the shell and `.wapp-main-content`; each route component should return a `Page` wrapper so standard content margins, mobile padding and scroll behavior stay consistent. `Page` uses the padded layout by default. For routes whose child content fills the available shell viewport and owns its own spacing or scrolling, use the framework full layout instead of overriding framework CSS:
+
+```tsx
+function TerminalRoute() {
+  return (
+    <Page layout="full">
+      <Terminal />
+    </Page>
+  );
+}
+```
+
+The `full` layout removes the page gutters and provides a flex-sized, overflow-contained surface for viewport-sized content. Use it for terminals, editors, previews and similar surfaces; the child should provide any internal padding and scrolling it needs.
 
 Use the framework URL helpers for browser API calls, websocket URLs and app-local links instead of deriving paths from `window.location` in each app. They honor `<base>`, explicit `publicBasePath` config, and reverse-proxy subpaths for direct path deep links such as `/workspaces`:
 
@@ -115,6 +142,7 @@ Use the framework URL helpers for browser API calls, websocket URLs and app-loca
 import {
   appAbsoluteUrl,
   appFetch,
+  appJson,
   appPath,
   appRequest,
   appWebSocketUrl,
@@ -124,7 +152,7 @@ import {
 
 configureWebAppClient();
 
-const config = await appFetch("/api/config").then((res) => res.json());
+const config = await appJson("/api/config");
 setWebAppPublicBasePath(config.publicBasePath);
 
 const downloadUrl = appPath("/api/items/export");
@@ -133,7 +161,7 @@ const socket = new WebSocket(appWebSocketUrl("/api/ws"));
 const rawResponse = await appRequest("/api/items");
 ```
 
-`appFetch` is the framework JSON API helper and throws `WebAppApiError` for non-OK responses. Use `appRequest` when the app needs a raw `Response`, such as downloads, custom error handling, or compatibility wrappers.
+`appJson` is the framework helper for successful JSON responses and builds on `appFetch`. Both `appJson` and `appFetch` honor configured URLs, credentials, auth-required events, and `WebAppApiError` responses. Use `appFetch` when a successful response body does not need to be parsed, and use `appRequest` when the app needs a raw response without the framework's error normalization, such as downloads or custom error handling. `appJson` intentionally rejects successful empty or non-JSON responses instead of fabricating a default value.
 
 Recommended dev script:
 
@@ -151,11 +179,46 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 | --- | --- | --- |
 | `{PREFIX}_HOST` | `localhost` | Bind host |
 | `{PREFIX}_PORT` | `3000` | Bind port |
-| `{PREFIX}_DATA_DIR` | `./data` | SQLite persistence directory |
+| `{PREFIX}_DATA_DIR` | `./data` | Durable SQLite persistence directory for framework auth and app data |
 | `{PREFIX}_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`; locks settings log-level control when set |
 | `{PREFIX}_DISABLE_PASSKEY` | unset | Emergency bypass that logs in as the existing owner; it does not create users |
 | `{PREFIX}_DISABLE_SAME_ORIGIN_CHECK` | unset | Development/testing escape hatch |
-| `{PREFIX}_PUBLIC_BASE_URL` | request origin | External URL for device auth links |
+| `{PREFIX}_TRUST_PROXY` | `false` | Explicitly trust the documented `X-Forwarded-*` headers; keep disabled for direct deployments |
+| `{PREFIX}_TRUST_PROXY_HEADERS` | `proto,host,prefix` when enabled | Comma-separated subset of supported forwarded values: `proto`, `host`, `prefix` |
+| `{PREFIX}_TRUST_PROXY_CHAIN` | `first` | Select the left-most (`first`) or right-most (`last`) non-empty value from comma-separated forwarded headers |
+| `{PREFIX}_PUBLIC_BASE_URL` | request origin | Authoritative external origin for auth/device URLs; it overrides forwarded protocol and host values |
 | `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |
 
+The configured data directory contains the framework-owned
+`webapp.sqlite`. The example applications keep their application entities in
+separate files in that same directory: Notes TODO uses `notes-todo.sqlite`
+for sections, notes and todos, while Kitchen Sink uses `kitchen-sink.sqlite`
+for projects. Keeping these files separate prevents example-specific tables
+from being added to the framework authentication store.
+
+Example application databases create or migrate their schema during startup.
+Owner seed data is written transactionally and is idempotent across repeated
+starts. Point the prefixed `*_DATA_DIR` at storage that survives process
+restarts and redeployments; deleting or changing the directory intentionally
+starts a new application state.
+
+For a reverse-proxy deployment that strips and overwrites the forwarded
+headers, configure the trust policy explicitly:
+
+```bash
+MY_APP_TRUST_PROXY=true
+MY_APP_TRUST_PROXY_HEADERS=proto,host,prefix
+MY_APP_TRUST_PROXY_CHAIN=first
+MY_APP_PUBLIC_BASE_URL=https://app.example.test
+```
+
+The default is fail-closed: forwarded headers are ignored unless
+`TRUST_PROXY=true`. The framework recognizes only `X-Forwarded-Proto`,
+`X-Forwarded-Host`, and `X-Forwarded-Prefix`; it does not infer trust from
+their presence and does not parse the RFC `Forwarded` header. A trusted prefix
+is used for cookie paths and externally generated links. The proxy must remove
+client-supplied values before writing these headers, and direct untrusted
+access to the application port must be blocked. This configuration does not
+provide a proxy-address allowlist.
+
 For CI/CD setup in apps built with the framework, use `docs/github-actions.md`. It includes copy-paste GitHub Actions and a production Dockerfile template.

package/docs/github-actions.md

@@ -75,6 +75,39 @@ CMD ["/app/my-app", "serve"]
 
 For apps that need extra OS packages, add them to the runtime `apt-get install` list. Keep `ca-certificates`, `curl` and `tini`.
 
+### Prebuilt-binary Dockerfiles
+
+The Dockerfile above builds the binary inside Docker, so it does not use `APP_BINARY`. The repository examples use a different pattern: they copy a prebuilt binary and require the caller to provide the artifact explicitly. Keep the platform and artifact mapping below in local commands and GitHub Actions:
+
+| Docker platform | Bun build target | Required artifact suffix |
+| --- | --- | --- |
+| `linux/amd64` | `bun-linux-x64` | `linux-x64` |
+| `linux/arm64` | `bun-linux-arm64` | `linux-arm64` |
+
+For a prebuilt-binary Dockerfile, do not add an architecture-specific `APP_BINARY` default. Build and image commands should select the same platform and artifact, for example:
+
+```bash
+bun run --cwd examples/notes-todo build --target=bun-linux-x64
+docker buildx build \
+  --platform linux/amd64 \
+  --build-arg APP_BINARY=examples/notes-todo/dist/notes-todo-linux-x64 \
+  --file examples/notes-todo/Dockerfile \
+  --tag webapp-notes-todo:amd64 \
+  --load \
+  .
+
+bun run --cwd examples/notes-todo build --target=bun-linux-arm64
+docker buildx build \
+  --platform linux/arm64 \
+  --build-arg APP_BINARY=examples/notes-todo/dist/notes-todo-linux-arm64 \
+  --file examples/notes-todo/Dockerfile \
+  --tag webapp-notes-todo:arm64 \
+  --load \
+  .
+```
+
+Validate `TARGETOS` and `TARGETARCH` in the Dockerfile before copying the artifact, so omitted, unsupported, or mismatched inputs fail during the build rather than at container startup. When building ARM64 images on an x64 GitHub runner, configure QEMU and Buildx before the build.
+
 ## Pull request workflow
 
 Place this at `.github/workflows/pr.yml`.
@@ -209,6 +242,8 @@ Place this at `.github/workflows/docker-main.yml`.
 
 It publishes `ghcr.io/<owner>/<repo>:main` after merges to `main`, updates `package.json` to a pre-release version based on the latest GitHub release, and runs a container health smoke test.
 
+Keep the `platforms` value explicit. The sample uses `linux/amd64` because `load: true` loads one runnable image for the smoke test; do not omit the value and rely on the runner architecture. To publish a multi-platform `main` image, configure QEMU, use `platforms: linux/amd64,linux/arm64`, and smoke-test platform-specific loaded images before pushing the multi-platform manifest, because Docker cannot load a multi-platform result into the local image store as one runnable tag.
+
 ```yaml
 name: Docker Main
 
@@ -332,6 +367,8 @@ Place this at `.github/workflows/docker-release.yml`.
 
 It publishes versioned GHCR images when a GitHub release is published:
 
+This release workflow is intentionally multi-platform. Keep both QEMU and Buildx setup steps and keep `platforms: linux/amd64,linux/arm64` explicit; the target platform, not the runner's architecture, determines the image binary.
+
 ```yaml
 name: Docker Release
 
@@ -415,6 +452,8 @@ await buildWebAppBinary({
 });
 ```
 
+`getBunCompileTargetFromArgs` accepts one `--target=<value>` option and validates it against the framework's exported `BUN_COMPILE_TARGETS` list before the build starts. Omitted targets build for the local Bun runtime; malformed, duplicate, empty, or unsupported target options fail immediately.
+
 `buildWebAppBinary` includes the framework browser build defaults, including Tailwind CSS v4 processing. Apps that need additional browser-only transforms can pass Bun plugins or defines through `web.build.plugins` and `web.build.define`; app plugins run before the framework defaults.
 
 ## Adaptation checklist

package/docs/release.md

@@ -14,10 +14,11 @@
 
 `Main Docker Smoke` runs after merges to `main`:
 
-1. Build Linux x64 binaries for both examples.
-2. Build Docker images from `examples/*/Dockerfile`.
-3. Run both containers.
-4. Smoke-test `/api/health` plus one app endpoint through the published container ports.
+1. Build Linux x64 and Linux arm64 binaries for both examples.
+2. Build each Docker image with an explicit `linux/amd64` or `linux/arm64` platform and matching `APP_BINARY` path.
+3. Validate missing, unsupported, and mismatched Docker arguments fail during the image build.
+4. Run both architecture variants of both containers.
+5. Smoke-test `/api/health` plus one app endpoint through the published container ports.
 
 ## NPM releases
 
@@ -61,4 +62,3 @@ For the first publish, npm may require a local manual publish before trusted pub
    - Workflow: `release-npm-package.yml`
    - Environment: leave empty unless an environment is added later
 7. After that, publish future versions by creating and publishing GitHub releases with tags like `v0.1.1`.
-

package/docs/server.md

@@ -3,9 +3,15 @@
 Use `createWebAppServer` with `defineRoutes`. Route patterns support exact path segments and `:params`.
 
 ```ts
+import { z } from "zod";
+
+const projectCreateSchema = z.object({ name: z.string() });
+const projectUpdateSchema = z.object({ name: z.string().optional() });
+
 const routes = defineRoutes<AppEvent>({
   "/api/projects": {
     auth: "user",
+    requestSchema: projectCreateSchema,
     description: "List or create projects.",
     cliPath: "projects",
     tags: ["projects"],
@@ -14,7 +20,7 @@ const routes = defineRoutes<AppEvent>({
     },
     async POST(req, ctx) {
       const user = ctx.requireUser();
-      const body = await parseJson<{ name: string }>(req);
+      const body = await parseJson(req, projectCreateSchema);
       const project = createProject(user.id, body.name);
       ctx.userRealtime.publishEntityChanged("projects", project.id);
       return jsonResponse(project);
@@ -23,9 +29,12 @@ const routes = defineRoutes<AppEvent>({
   "/api/projects/:id": {
     auth: "user",
     scopes: ["projects:write"],
+    requestSchema: projectUpdateSchema,
     async PATCH(req, ctx) {
       const project = ctx.requireOwned(await findProject(ctx.params.id));
-      Object.assign(project, await parseJson<Partial<Project>>(req));
+      const body = await parseJson(req, projectUpdateSchema);
+      if (body.name !== undefined) project.name = body.name;
+      project.updatedAt = new Date().toISOString();
       ctx.userRealtime.publishEntityChanged("projects", project.id);
       return jsonResponse(project);
     },
@@ -37,6 +46,27 @@ const routes = defineRoutes<AppEvent>({
 });
 ```
 
+Request schemas define the writable input fields, but handlers should still assign
+those fields explicitly rather than spreading or merging parsed input into a
+stored record. The example schemas use Zod's default object behavior, so
+unknown properties are ignored and never persisted; keep `id`, `userId`,
+timestamps, and other server-managed fields under application control.
+
+`parseJson(req, schema)` parses and validates the body at runtime. Malformed JSON
+returns a 400 `invalid_json` response, while a JSON value that does not satisfy
+the schema returns a 400 `invalid_request_body` response with field details.
+Use `parseOptionalJson(req, schema)` only for endpoints that deliberately allow
+an empty body. Only a zero-byte body is considered absent; whitespace-only
+content is non-empty malformed JSON and is rejected just like any other
+malformed body. `parseUnknownJson` returns `unknown` and is intentionally
+unvalidated, so application handlers should prefer a schema-backed parser.
+
+The Notes TODO webhook uses an absent body (or an object without `title`) to
+apply its source-based fallback title. When an owner does not exist, that
+accepted delivery returns 202 with `accepted: false`; malformed or
+schema-invalid bodies are rejected before this ownerless response or any
+mutation is reached.
+
 Route defaults are intentionally secure:
 
 | Setting | Default | Meaning |
@@ -55,7 +85,7 @@ Route definitions can include optional metadata. This keeps the API route table
 | `description` | Human-readable route description |
 | `cliPath` | CLI-friendly path; defaults to the API path without `/api/` |
 | `tags` | Grouping labels for docs/CLI |
-| `requestSchema`, `querySchema`, `responseSchema` | Optional schema objects for CLI/docs |
+| `requestSchema`, `querySchema`, `responseSchema` | Optional schema objects for CLI/docs; use the same runtime `requestSchema` with `parseJson` when a route accepts a body |
 | `catalog: false` | Exclude a route from generated catalogs |
 
 Use `createRouteCatalog(routes)` and `findRouteCatalogEntry(catalog, input)` to power app CLI commands without maintaining a second route catalog.
@@ -96,7 +126,7 @@ Built-in endpoints include:
 
 ## Framework-owned web document and PWA metadata
 
-`createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file. The generated viewport keeps the app at `initial-scale=1` with `maximum-scale=1` and `user-scalable=no`; clients and mobile browsers that honor those viewport scaling tokens, including iPhone and iPad, cannot change the app scale with pinch-to-zoom while normal scrolling remains enabled. Clients that ignore the tokens are unaffected.
+`createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file. The generated document also initializes the shared `data-wapp-mobile` state before client styles load so CSS and `WebAppRoot` use the same mobile breakpoint. The generated viewport keeps the app at `initial-scale=1` with `maximum-scale=1` and `user-scalable=no`; clients and mobile browsers that honor those viewport scaling tokens, including iPhone and iPad, cannot change the app scale with pinch-to-zoom while normal scrolling remains enabled. Clients that ignore the tokens are unaffected.
 
 Do not replace this behavior with global touch event handlers, `preventDefault()` calls, or `touch-action: none`: those approaches can disable scrolling and other touch interactions. Applications should keep the document framework-owned rather than adding an app-owned `index.html`.
 

package/docs/settings.md

@@ -11,6 +11,11 @@ Settings is framework-owned so apps stay consistent. It includes:
 - Admin server kill
 - Version/about
 
+The local-storage or system theme is applied immediately while the signed-in
+user preference loads in the background. If that request fails, the current
+theme remains active and Display Settings shows a non-blocking error with a
+retry action; the rest of Settings remains usable.
+
 Security lists only show useful active credentials. Expired API keys are purged before listing, and revoked or expired device-auth refresh sessions are not shown. Revoked refresh sessions may remain in storage when needed for token-reuse protection, but they are hidden from Settings.
 
 Destructive actions in Settings use the framework `ConfirmDialog` before mutating. This includes deleting users, deleting API keys, deleting passkeys, revoking device-auth sessions, and killing the server.