ugly-app 0.1.948 → 0.1.949

package/README.md

@@ -1,15 +1,15 @@
 # ugly-app
 
-A full-stack TypeScript framework for shipping production web apps. Scaffold
-with `npx ugly-app init my-app` and get an opinionated Node + React + Postgres
-stack with type-safe RPC over WebSocket and HTTP, real-time doc subscriptions,
-built-in auth, AI generation, storage, workers, cron, and a CLI for every
-workflow.
+A full-stack TypeScript framework for shipping production web apps.
+Scaffold with `npx ugly-app init my-app` and get an opinionated Node +
+React + Postgres stack with type-safe RPC over WebSocket and HTTP,
+real-time doc subscriptions, built-in auth, AI generation, storage,
+workers, cron, and a CLI for every workflow.
 
 ugly-app is designed to run against [ugly.bot](https://ugly.bot), which
-provides auth, infra (Postgres, Qdrant, NATS, S3-compatible object storage),
-AI provider keys, push, email, and deployment. Your app talks to all of it
-through the project's dev tunnel and its `UGLY_BOT_TOKEN`.
+provides auth, infra (Postgres, Qdrant, NATS, S3-compatible object
+storage), AI provider keys, push, email, and deployment. Your app talks
+to all of it through the project's dev tunnel and its `UGLY_BOT_TOKEN`.
 
 ```bash
 npx ugly-app init my-app
@@ -44,8 +44,8 @@ npm run dev
 
 ## Server — `createApp()`
 
-Single server entry point. Returns an `App` that owns Express, the WebSocket
-server, the typed DB, and the RPC dispatcher.
+Single server entry point. Returns an `App` that owns Express, the
+WebSocket server, the typed DB, and the RPC dispatcher.
 
 ```ts
 // server/index.ts
@@ -103,31 +103,29 @@ function createApp<
 ): App<CollectionMap<typeof BUILTIN_DEFS & Defs>, RegistryPages<R>>;
 ```
 
-Passing `pages` in the registry (`{ requests, messages, pages }`) upgrades
-`app.pushSend()` to a per-route typed API. `pages` is optional; apps that only
-call `configurator.setPages()` still work — they just get the loose
-`PageRegistry` typing on `pushSend`.
+Passing `pages` in the registry (`{ requests, messages, pages }`)
+upgrades `app.pushSend()` to a per-route typed API. `pages` is optional;
+apps that only call `configurator.setPages()` still work — they just get
+the loose `PageRegistry` typing on `pushSend`.
 
 ### The returned `App`
 
-`App` extends `AppRouter`, so `dispatch(name, input, userId)` is available for
-in-process invocation of any registered handler.
-
-| Member | Description |
-|--------|-------------|
+| Field | Description |
+|-------|-------------|
 | `start(port?)` | Start the server (default 3000; templates use 4321). |
-| `db` | `TypedDB<Map>` — map inferred from your collections + framework built-ins. |
+| `db` | The `TypedDB<Map>` (map inferred from your collections + framework built-ins). |
 | `httpServer` | The underlying Node `http.Server`. |
 | `wss` | The main `WebSocketServer` (path set via `setWsPath`, default `/rpc`). |
-| `dispatch(name, input, userId)` | `Promise<unknown>` — invoke any registered RPC handler programmatically. |
+| `dispatch(name, input, userId)` | Invoke a registered RPC handler programmatically (inherited from `AppRouter`). |
 | `registerRoutes(fn)` | Mount additional Express routes after creation. |
-| `pushSend(input)` | Typed push whose click-through target is a route from this app's `pages`. Mints a `https://ugly.bot/l/<code>` short link so the URL is always absolute and dock-app-routable. |
+| `pushSend(input)` | Typed push whose click-through target is a route from this app's `pages`. The framework mints a `https://ugly.bot/l/<code>` short link so the click-through is always absolute and dock-app-routable. |
 
-Framework services start inside `app.start()`: schema drift check, NATS
-connection + KV buckets, data-proxy connection, event-counter flush, TTL
-cleanup for log tables, console/error capture, and ugly.bot log forwarding.
-Postgres, NATS, storage, and AI clients load **lazily** — a host without
-`DATABASE_URL` / `NATS_URL` / `R2_BUCKET` doesn't pay their startup cost.
+Framework services start automatically inside `app.start()`: schema
+drift check, NATS connection + KV buckets, data-proxy connection,
+event-counter flush, TTL cleanup for log tables, console/error capture,
+and ugly.bot log forwarding. Postgres, NATS, storage, and AI clients
+are loaded **lazily** — a host without `DATABASE_URL` / `NATS_URL` /
+`R2_BUCKET` doesn't pay their startup cost.
 
 ### `AppConfigurator`
 
@@ -158,8 +156,8 @@ Every method is optional; `setPages` is what mounts the SPA.
 
 ### Handler signatures
 
-Handlers are plain async functions — no context object. Access state via
-captured imports (`app.db`, `storage`, `pgQuery`, `uglyBotRequest`, …).
+Handlers are plain async functions — no context object. Access state
+via captured imports (`app.db`, `storage`, `pgQuery`, `uglyBotRequest`, …).
 
 ```ts
 // req() — public, userId may be null
@@ -171,37 +169,30 @@ getMe: async (userId: string, input) => { /* … */ }
 
 ### Built-in framework requests
 
-`createApp` registers several framework handlers reachable from any client via
-the normal RPC pipeline. App-provided handlers with the same name override the
-framework's defaults. Rate-limited handlers are marked below.
+`createApp` registers several framework handlers reachable from any
+client via the normal RPC pipeline. App-provided handlers with the same
+name override the framework's defaults.
 
-| Name | Notes |
-|------|-------|
+| Name | Purpose |
+|------|---------|
 | `userGet` | Returns `{ userId, name, avatarUri }` for the given user (or caller). |
 | `initSession` / `captureEvent` | Session + event logging tagged with experiment branches (public — no auth). |
-| `textGen` | AI text proxy — server-validated, billed through ugly.bot. Rate-limited 20/60s. |
-| `imageGen` | AI image proxy. Rate-limited 10/60s. |
-| `kagiSearch` / `kagiEnrichWeb` / `kagiEnrichNews` | Web search via ugly.bot. Rate-limited 20/60s. |
-| `kagiSummarize` | URL / text summary. Rate-limited 10/60s. |
+| `textGen` / `imageGen` | AI proxies — server-validated, billed through ugly.bot. |
+| `kagiSearch` / `kagiSummarize` / `kagiEnrichWeb` / `kagiEnrichNews` | Web search via ugly.bot. |
 | `uploadUrl` | Issues a presigned PUT for the `temp` bucket. |
-| `shareLink` | Mint a `https://ugly.bot/l/<code>` short link with OG metadata. Rate-limited 60/60s. |
-| `feedbackReportCreateNoAuth` | Public, same-origin feedback endpoint used by browser telemetry. Rate-limited 10/60s. |
-| `errorLogCaptureNoAuth` | Public error-log capture. |
-| `perfSnapshotCaptureNoAuth` | Public perf snapshot capture. Rate-limited 60/60s. |
-| `submitFeedbackBot` | Bot-persona feedback submission. |
-| `feedbackReportResolve` | Admin resolve/decline. Rate-limited 120/60s. |
+| `shareLink` | Mint a `https://ugly.bot/l/<code>` short link with OG metadata. |
+| `feedbackReportCreateNoAuth` / `errorLogCaptureNoAuth` / `perfSnapshotCaptureNoAuth` | Same-origin, public endpoints used by browser telemetry. |
+| `submitFeedbackBot` / `feedbackReportResolve` | Bot-persona feedback submission; admin resolve/decline. |
 | `adminGetPerfLogs` | Admin-only perf telemetry read. |
 | `adminCreateTestUser` / `adminListTestUsers` / `adminDeleteTestUser` | Admin-only synthetic-user management. Gated by `setIsAdmin()`. |
 | `projectPlanList` / `projectPlanCreate` / `projectPlanUpdate` / `projectPlanDelete` | Project plan CRUD used by Studio. |
 
-Add per-endpoint rate limits on your own handlers with `rateLimit: { max, window }` on the request definition (see below).
-
 ---
 
 ## Shared API definitions
 
-`shared/` is consumed by both server and client. Keep all Zod schemas, types,
-collections, and route declarations here.
+`shared/` is consumed by both server and client. Keep all Zod schemas,
+types, collections, and route declarations here.
 
 ### Requests (`shared/api.ts`)
 
@@ -231,8 +222,8 @@ export const requests = defineRequests({
 ```
 
 Every request is reachable as **both** `socket.request(name, input)`
-(WebSocket) and `POST /api/:name { input }` (HTTP). `z` is re-exported from
-Zod for convenience.
+(WebSocket) and `POST /api/:name { input }` (HTTP). `z` is re-exported
+from Zod for convenience.
 
 ### Collections (`shared/collections.ts`)
 
@@ -268,19 +259,20 @@ export const collections = defineCollections({
 - `public` — allow unauthenticated client reads.
 - `cascadeFrom` — parent collection: when the parent doc is deleted, docs in this collection are cascade-deleted.
 - `trackKeys?` — fields usable as NATS routing keys for scoped `trackDocs` subscriptions.
-- `getter?(ids)` — batch resolver for collections with no local table (e.g. `userPublic` resolves via ugly.bot).
+- `getter?(ids)` — batch resolver for collections with no local table (framework pattern; e.g. `userPublic` resolves via ugly.bot).
 - `skipReadValidation?` — opt out of per-row zod validation on reads for very hot collections. Writes are always validated. Global kill-switch: `UGLY_DB_VALIDATE_READS=0`.
 - `search?: { fields, language? }` — full-text index over the named JSONB paths (Neon: Postgres FTS; D1: SQLite FTS5, ranked by bm25).
 - `vector?: { dimensions, metric?, filterable? }` — ANN index. Vector supplied out-of-band at write time (`setDoc(c, doc, { vec })`) — never stored in the doc JSON. Query with `getDocs(c, filter, { near })`.
 
 All documents extend `DBObject`: `{ _id, version, created, updated }`.
-Use `dbDefaults()` to stamp `version` / `created` / `updated` on inserts.
-**Always generate `_id` with `nanoid()`** — never `crypto.randomUUID()`,
-`Date.now()`, or `Math.random()` (see `CLAUDE.md`).
+Use `dbDefaults()` to stamp `version` / `created` / `updated` on
+inserts. **Always generate `_id` with `nanoid()`** — never
+`crypto.randomUUID()`, `Date.now()`, or `Math.random()` (see
+`CLAUDE.md`).
 
-After schema changes, run `npm run db:schema-gen` then `npm run db:migrate`.
-The app refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true`
-only as a last resort).
+After schema changes, run `npm run db:schema-gen` then `npm run
+db:migrate`. The app refuses to start when drift is detected (set
+`SCHEMA_CHECK_SKIP=true` only as a last resort).
 
 ---
 
@@ -303,20 +295,23 @@ export const pages = definePages({
 export type AppPages = typeof pages;
 ```
 
-`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime object
-carrying `PageMeta` plus a phantom `_params` used only for TypeScript
-inference. `PageMeta` fields:
+`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime
+object carrying `PageMeta` plus a phantom `_params` used only for
+TypeScript inference.
+
+**Options** (all optional):
 
-- `auth` (default `true`) — protected route. When `isAuthenticated()` returns false on this route, the router synchronously renders the framework's `<AuthRoot>` in place of the page (Mode A → `<LoginPopup>`, Mode B → `<MagicLinkForm>` plus optional Google button). Apps cannot override this fallback.
-- `ssr` (default `false`) — server-render the page for SEO. `{ auth: true, ssr: true }` is silently downgraded to `ssr: false` with a warning: the SSR document is served from a shared edge cache and must not depend on the viewer.
+- `auth` (default `true`) — protected route. When `isAuthenticated()` returns false on this route, the router synchronously renders the framework's `<AuthRoot>` in place of the page (dispatches on `window.__UGLY_APP_AUTH_MODE__`: Mode A → `<LoginPopup>`, Mode B → `<MagicLinkForm>` plus optional Google button). Apps cannot override this fallback — the framework owns the login UX so no route can accidentally ship as auth-required with no way to log in.
+- `ssr` (default `false`) — server-render the page for SEO. `{ auth: true, ssr: true }` is silently dropped to `ssr: false` with a warning: the SSR document is served from a shared edge cache and must not depend on the viewer.
 - `cacheQuery?: string[]` — query params that participate in the SSR edge-cache key. Anything NOT listed bypasses the cache instead of poisoning it (e.g. `cacheQuery: ['q']` on a search page).
-- `ssrCacheTimeout?: number` — edge cache lifetime in seconds. Default is `DEFAULT_SSR_CACHE_TIMEOUT` (1 year) because the `buildId` is already part of the cache key. Override only for pages that drift between deploys.
+- `ssrCacheTimeout?: number` — edge cache lifetime in seconds. Default is effectively 1 year (`DEFAULT_SSR_CACHE_TIMEOUT`) because the `buildId` is part of the cache key. Override only for pages that drift between deploys.
 
 Path syntax: `:param` matches a single path segment; `*param` is greedy
-(captures slashes). Query-string params are declared in `Params` but never
-appear in the path template.
+(captures slashes). Query-string params are declared in `Params` but
+never appear in the path template.
 
-`definePages<T>(p)` is a pass-through identity — use it to name the registry.
+`definePages<T>(p)` is a pass-through identity — use it to give the
+registry a name.
 
 ### `createRouter()` (`ugly-app/client`)
 
@@ -337,23 +332,23 @@ export const {
 **Config:**
 - `pages` (required) — the `PageRegistry` from `shared/pages.ts`.
 - `allPages?` — the lazy route → element map (`PageMap<Pages>`). Prefer registering via `setAllPages()` from the browser entry when the app also server-renders — the Worker bundle has no code splitting, so a static import inlines every page (and its deps) into `worker.js`.
-- `ssrPages?: SsrPageMap<Pages>` — `Partial<{ [K]: ComponentType<Params> }>` of statically-imported components for `ssr: true` routes. Used by both the Worker's `renderToString` and the client's first hydration render so the initial paint resolves synchronously and never mismatches the server output.
+- `ssrPages?` — `Partial<{ [K]: ComponentType<Params> }>` of statically-imported components for `ssr: true` routes. Used by both the Worker's `renderToString` and the client's first hydration render so the initial paint resolves synchronously and never mismatches the server output.
 
 **Returns:**
 
-- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?: () => boolean`, `initialUrl?: { pathname, search }` (required for SSR + hydration). Manages route state, browser history, and the popup layer. Runs the per-route auth check synchronously — apps cannot override the login fallback.
-- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?: EasingFunction`, `transitionComponent?: React.ComponentType<RouterTransitionProps>` (replaces the default `ViewFlipper`), `renderPage?(state: RouterStateRaw) => ReactElement` (sync alternative to `allPages` loaders).
+- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?`, `initialUrl?` (`{ pathname, search }`, required for SSR + hydration). Manages route state, browser history, and the popup layer. Runs the per-route auth check synchronously — apps cannot override the login fallback.
+- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (a `React.ComponentType<RouterTransitionProps>` that replaces the default `ViewFlipper`), `renderPage?(state) => ReactElement` (sync alternative to `allPages` loaders, called with `RouterStateRaw`).
 - **`useRouter()`** — returns `RouterContextValue<Pages>` (typed navigation + popup API). Throws if used outside `<RouterProvider>`.
 - **`Link`** — typed SPA link bound to this router. Renders a real `<a>` (right-click / cmd-click / SEO keep working) but intercepts a plain left-click and routes through `push` / `replace`. Props: `to`, `params` (both type-checked against `pages`), `replace?`, `children`, plus common anchor attrs (`className`, `style`, `target`, `aria-label`, `data-id`, `onClick`).
 - **`setAllPages(map)`** — register the lazy `PageMap<Pages>` after construction (typically from the browser entry, so the Worker's import graph stays free of every lazy page).
 
-A standalone `Link` is also exported from `ugly-app/client` for code that
-can't easily reach the typed one; it accepts an optional `router` prop and
-falls back to `<RouterProvider>` context.
+A standalone `Link` is also exported from `ugly-app/client` for code
+that can't easily reach the typed one; it accepts an optional `router`
+prop and falls back to `<RouterProvider>` context.
 
-**Never use a bare `<a href="/route">`** for internal navigation — it triggers
-a full document reload (white flash + repaint). See the "client navigation"
-rule in `CLAUDE.md`.
+**Never use a bare `<a href="/route">`** for internal navigation — it
+triggers a full document reload (white flash + repaint). See the "client
+navigation" rule in `CLAUDE.md`.
 
 ### Page map — `lazyPage` / `lazyPageLoader`
 
@@ -374,9 +369,10 @@ export const allPages = {
 - **`lazyPageLoader(factory)`** — lazy-imports an async loader `(params) => Promise<ReactElement>`. Use when a route needs data fetching before render. The loader file is the chunk boundary, so it can statically import its page component.
 
 Both wrappers recover from stale-deploy chunk 404s ("Failed to fetch
-dynamically imported module"): on the first failure they trigger a single
-`window.location.reload()` (guarded by `sessionStorage` so a genuinely broken
-chunk can't loop) to fetch fresh chunk hashes.
+dynamically imported module"): on the first failure they trigger a
+single `window.location.reload()` (guarded by `sessionStorage` so a
+genuinely broken chunk can't loop) to fetch the fresh `index.html` with
+new chunk hashes.
 
 ```ts
 // pages/SlowPageLoader.tsx
@@ -406,15 +402,15 @@ replace('search', { q: 'hello' });         // → /search?q=hello
 back();                                    // browser history back
 ```
 
-Route names and params are fully typed against `pages`. `push` / `replace`
-no-op with a `console.error` when `buildUrl()` produces a URL that doesn't
-match a registered route.
+Route names and params are fully typed against `pages`. `push` /
+`replace` no-op with a `console.error` when `buildUrl()` produces a URL
+that doesn't match a registered route.
 
 ### Popups — `openPopup()`
 
-`useRouter().openPopup()` is the canonical modal / sheet / menu API. The
-router owns the popup layer, drives a spring animation, and stacks popups
-z-index-correctly above every page.
+`useRouter().openPopup()` is the canonical modal / sheet / menu API.
+The router owns the popup layer, drives a spring animation, and stacks
+popups z-index-correctly above every page.
 
 ```tsx
 const { openPopup } = useRouter();
@@ -439,20 +435,20 @@ handle.hide(); // dismiss programmatically — same as router.closePopup(handle.
 - **`contextMenu`** — same as transient, intended for menus and pickers.
 
 `renderLayer` receives `{ content, spring, hide }`: `spring` is a
-`createAnimatedValue()` result driving 0 → 1; `hide` closes the popup. The
-default layer animates open with `easeOut` (250 ms) and closed with `easeIn`
-(200 ms). Popups render as siblings of the router's children (managed inside
-`RouterProvider`), so they stack above every page.
+`createAnimatedValue()` result driving 0 → 1; `hide` closes the popup.
+The default layer animates open with `easeOut` (250 ms) and closed with
+`easeIn` (200 ms). Popups render as siblings of the router's children
+(managed inside `RouterProvider`), so they stack above every page.
 
 ### Scroll containers
 
 `html, body, #root` are `overflow: hidden` — the document itself never
-scrolls, so a page that just renders tall content is clipped. For pages that
-own their scrolling (or render outside the normal authed chrome — e.g. a
-public page special-cased before the auth gate), wrap the content in
-`SimpleScrollView` (exported from `ugly-app/client`). For long / virtualized
-lists with scroll-position persistence, use the richer `ScrollView`. See the
-"page scrolling" rule in `CLAUDE.md`.
+scrolls, so a page that just renders tall content is clipped. For pages
+that own their scrolling (or render outside the normal authed chrome —
+e.g. a public page special-cased before the auth gate), wrap the
+content in `SimpleScrollView` (exported from `ugly-app/client`). For
+long / virtualized lists with scroll-position persistence, use the
+richer `ScrollView`. See the "page scrolling" rule in `CLAUDE.md`.
 
 ---
 
@@ -475,9 +471,6 @@ bootstrapApp({
 });
 ```
 
-`bootstrapApp(options): void` — returns nothing; it renders directly to the
-DOM.
-
 **`BootstrapAppOptions`:**
 
 | Field | Description |
@@ -495,28 +488,28 @@ DOM.
 | `silentSso?` | Apex-domain apps that use ugly.bot as their auth authority but don't share its cookie. When `true`, a logged-out boot attempts a top-level SSO redirect (once per tab) to adopt an existing ugly.bot session. Leave unset for `*.ugly.bot` subdomains and Mode B apps. |
 | `testMode?` | Skip ugly.bot silent SSO and trust the auth cookie the fixture set. Only honored when `UGLY_APP_TEST_MODE=1`. |
 
-`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server after
-cookie verification). If absent, it renders unauthenticated immediately — the
-router's per-route auth guard surfaces `<AuthRoot>` only when the user opens a
-protected route. If the token is present, it connects the socket, mounts
-`<AppProvider>`, and renders.
+`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server
+after cookie verification). If absent, it renders unauthenticated
+immediately — the router's per-route auth guard surfaces `<AuthRoot>`
+only when the user opens a protected route. If the token is present, it
+connects the socket, mounts `<AppProvider>`, and renders.
 
 After render, a hidden iframe silently calls
-`${UGLY_BOT_URL}/oauth/silent`: if it returns a fresh code, the cookie is
-refreshed via `POST /auth/verify`; if the returned account differs from the
-current session, the page reloads onto the live account (guarded once per
-from→to pair to prevent loops). Any `?ugly_oauth_code=…` in the URL
-(redirect-fallback OAuth code from ugly.bot) is redeemed at the top of
-bootstrap before anything renders.
+`${UGLY_BOT_URL}/oauth/silent`: if it returns a fresh code, the cookie
+is refreshed via `POST /auth/verify`; if the returned account differs
+from the current session, the page reloads onto the live account
+(guarded once per from→to pair to prevent loops). Any
+`?ugly_oauth_code=…` in the URL (redirect-fallback OAuth code from
+ugly.bot) is redeemed at the top of bootstrap before anything renders.
 
-If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it renders
-`<MagicLinkCallback>` instead of the regular app shell.
+If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it
+renders `<MagicLinkCallback>` instead of the regular app shell.
 
 ### `AppProvider` & `useApp()`
 
-`bootstrapApp` mounts `<AppProvider>` automatically after socket connect. Use
-`useApp()` inside any page to access the active user, socket, and app-scoped
-services.
+`bootstrapApp` mounts `<AppProvider>` automatically after socket
+connect. Use `useApp()` inside any page to access the active user,
+socket, and app-scoped services.
 
 ```ts
 const {
@@ -524,26 +517,28 @@ const {
   user,          // UserBase doc
   socket,        // AppSocket — typed RPC client
   uglyBotSocket, // UglyBotSocket | null — direct platform socket for STT/TTS
-  showPopup,     // (content: ReactElement) => id — flat overlay layer (see note)
-  hidePopup,     // (id: string) => void
-  hideAllPopups, // () => void
+  showPopup,     // flat overlay layer (see note) — returns popup id
+  hidePopup,
+  hideAllPopups,
   runAsync,      // (label, async () => {…}, options?) — shows loading overlay
-  splashDone,    // (step: string) => void — mark a splash-screen step complete
+  splashDone,    // (step: string) — mark a splash-screen step complete
   localizer,     // (key, params?) => string — alias for useLocalizer()
 } = useApp();
 ```
 
-`useApp<TAsyncOptions>()` is generic in the async-options type so apps can
-pass a custom option through to a custom `loadingOverlay` element. When
-`runAsync` is pending, `AppProvider` `cloneElement`s the overlay with
-`{ label, asyncOptions }`. `useAppOptional()` returns `null` outside the
-provider; `useLocalizer()` prefers `<StringsProvider>` data, falls back to
-the `AppProvider` `localizer` prop, and finally to identity.
+`useApp<TAsyncOptions>()` is generic in the async-options type so apps
+can pass a custom option through to a custom `loadingOverlay` element.
+`AppProvider` `cloneElement`s the overlay with `{ label, asyncOptions
+}` while `runAsync` is pending. `useAppOptional()` returns `null`
+outside the provider; `useLocalizer()` returns a localizer that prefers
+`<StringsProvider>` data, falls back to the `AppProvider` `localizer`
+prop, and finally to identity.
 
 Two popup APIs coexist: `useRouter().openPopup()` (spring-animated,
-dismissible, mode-aware — **the default choice**) and `useApp().showPopup()`
-(a flat overlay layer returning a string id, for content that must sit
-*outside* the router transition). Prefer the router's.
+dismissible, mode-aware — **the default choice**) and
+`useApp().showPopup()` (a flat overlay layer returning a string id, for
+content that must sit *outside* the router transition). Prefer the
+router's.
 
 ### Direct socket access
 
@@ -570,14 +565,14 @@ from `ugly-app/client`.
 ugly-app uses HttpOnly cookies and server-side JWT injection — no
 `localStorage`, no client-side token handling.
 
-Two modes, picked from the `auth` block in the project's `.uglyapp` config:
+Two modes, picked from the `auth` block in the project's `.uglyapp`
+config:
 
 - **Mode A — `mode: 'uglybot'`** (default when no `auth` block is present). Auth is delegated to ugly.bot OAuth. AI / email / push proxies bill the end user's ugly.bot credits.
 - **Mode B — `mode: 'self'`**. The app issues its own sessions via magic-link email and/or Google OAuth. AI / email / push proxies bill the developer's ugly.bot account using the project's `AI_PROXY_TOKEN`.
 
-`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client code
-(incl. `<AuthRoot>`) can branch correctly. In Mode B with Google configured,
-`window.__UGLY_APP_GOOGLE_CLIENT_ID__` is also injected.
+`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client
+code (incl. `<AuthRoot>`) can branch correctly.
 
 ### Mode A — ugly.bot OAuth (default)
 
@@ -589,9 +584,9 @@ Two modes, picked from the `auth` block in the project's `.uglyapp` config:
 
 ### Mode B — self-issued sessions
 
-When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the magic-link
-provider as primary; if `providers.google.clientId` is configured it adds
-Google as an extra provider on the same router.
+When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the
+magic-link provider as primary; if `providers.google.clientId` is
+configured it adds Google as an extra provider on the same router.
 
 - `<AuthRoot>` renders `<MagicLinkForm>` (plus the Google button when configured) instead of `<LoginPopup>`.
 - Background ugly.bot silent SSO is a no-op.
@@ -601,9 +596,9 @@ Google as an extra provider on the same router.
 
 ### Token-in-URL embed
 
-Any GET request with `?token=<JWT>` will, if the token verifies, set the
-cookie and 302-redirect to the same URL without the token parameter — useful
-for embedding any page in an iframe.
+Any GET request with `?token=<JWT>` will, if the token verifies, set
+the cookie and 302-redirect to the same URL without the token
+parameter — useful for embedding any page in an iframe.
 
 ### Built-in auth routes
 
@@ -637,8 +632,8 @@ configurator.setAuth({
 ## Database — `TypedDB`
 
 Access via `app.db`. All methods accept a `CollectionDef` (from
-`defineCollections()`) or, on the `raw*` / `getQuery*` variants, a plain
-collection name string.
+`defineCollections()`) or, on the `raw*` / `getQuery*` variants, a
+plain collection name string.
 
 ### Writing
 
@@ -663,10 +658,10 @@ await db.batch(async () => {
 });
 ```
 
-Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`, `$set`.
-All keys are dot-notation, fully typed against the collection's schema.
-Partial updates go through optimistic concurrency to prevent lost updates
-on concurrent writers.
+Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`,
+`$set`. All keys are dot-notation, fully typed against the collection's
+schema. Partial updates go through optimistic concurrency to prevent
+lost updates on concurrent writers.
 
 ### Reading
 
@@ -700,8 +695,8 @@ await db.deleteWhere(collections.note, { userId });        // typed bulk delete
 await db.deleteQuery(collections.note, { userId });        // legacy untyped bulk delete
 ```
 
-Pass `deleteHandlers` as the 5th argument to `createApp` to run per-collection
-`onDelete` callbacks.
+Pass `deleteHandlers` as the 5th argument to `createApp` to run
+per-collection `onDelete` callbacks.
 
 ### Search
 
@@ -750,9 +745,10 @@ Imports available from `ugly-app`:
 
 ## AI providers
 
-AI calls are proxied through ugly.bot — your app never holds a provider key.
-Pass `UGLY_BOT_TOKEN` in the environment and the framework handles routing,
-balance tracking, retries, and per-user billing.
+AI calls are proxied through ugly.bot — your app never holds a
+provider key. Pass `UGLY_BOT_TOKEN` in the environment and the
+framework handles routing, balance tracking, retries, and per-user
+billing.
 
 ### Server-side text generation
 
@@ -774,9 +770,9 @@ const { message } = await uglyBotRequest<{ message: { content: string } }>('text
 });
 ```
 
-Available models are exposed via `textGenModels` / `textGenModelData` from
-`ugly-app` — the platform supports Claude, GPT, Gemini, Together, Groq,
-Fireworks, Kimi, and Kie families.
+Available models are exposed via `textGenModels` / `textGenModelData`
+from `ugly-app` — the platform supports Claude, GPT, Gemini, Together,
+Groq, Fireworks, Kimi, and Kie families.
 
 ### Server-side image generation
 
@@ -787,8 +783,8 @@ const imageGen = createImageGen(userId);
 const url = await imageGen.generate('A red panda eating noodles', { model: 'flux_schnell' });
 ```
 
-`imageGenModels` / `imageGenModelData` enumerate available models (Together
-FLUX, FAL, Google Imagen, Wavespeed, Kie Kolors).
+`imageGenModels` / `imageGenModelData` enumerate available models
+(Together FLUX, FAL, Google Imagen, Wavespeed, Kie Kolors).
 
 ### Embeddings
 
@@ -813,8 +809,8 @@ await search.enrichNews({ query: 'topic' });
 
 ### Client-side AI calls
 
-Calls from React components go through the framework RPC pipeline — no token
-plumbing in the browser:
+Calls from React components go through the framework RPC pipeline — no
+token plumbing in the browser:
 
 ```ts
 import { callTextGen, callJsonGen, callImageGen } from 'ugly-app/client';
@@ -826,8 +822,9 @@ const image = await callImageGen({ prompt: 'a corgi astronaut', model: 'flux_sch
 
 ### STT / TTS
 
-Speech goes **directly** from the browser to ugly.bot — never proxied through
-your app server (see the "STT/TTS routes to ugly.bot" rule in `CLAUDE.md`).
+Speech goes **directly** from the browser to ugly.bot — never proxied
+through your app server (see the "STT/TTS routes to ugly.bot" rule in
+`CLAUDE.md`).
 
 ```ts
 import { useSTT, useTTS, AudioPlayer, AudioRecorder } from 'ugly-app/client';
@@ -861,23 +858,24 @@ const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);
 await storage.delete('public', destKey);
 ```
 
-Client-side, use `socket.uploadFile(file, key)` — it requests a presigned URL
-via the built-in `uploadUrl` framework request and streams the upload. In
-dev, uploads go through a same-origin `/_s3` proxy to avoid CORS with local
-MinIO.
+Client-side, use `socket.uploadFile(file, key)` — it requests a
+presigned URL via the built-in `uploadUrl` framework request and
+streams the upload. In dev, uploads go through a same-origin `/_s3`
+proxy to avoid CORS with local MinIO.
 
-`STORAGE_KEY_PREFIX` (env) prefixes all keys — useful for per-environment
-isolation.
+`STORAGE_KEY_PREFIX` (env) prefixes all keys — useful for
+per-environment isolation.
 
-On Cloudflare Workers, storage uses the R2 binding directly; presigned PUTs
-are not exposed (browser uploads must go through a Worker endpoint).
+On Cloudflare Workers, storage uses the R2 binding directly; presigned
+PUTs are not exposed (browser uploads must go through a Worker
+endpoint).
 
 ### Static assets — `static/`
 
 Large, rarely-changing files (3D models, textures, audio, fonts) go in the
 project-root `static/` folder. `ugly-app build:static` hashes them and
-generates `shared/StaticAssets.ts`; publish uploads only the files whose
-bytes changed.
+generates `shared/StaticAssets.ts`; publish uploads only the files whose bytes
+changed.
 
 ```ts
 import { staticUrl } from '../shared/StaticAssets'
@@ -887,14 +885,15 @@ const url = staticUrl('models/char2.ugm')
 ```
 
 The bucket gets its own custom domain, so **Cloudflare's CDN serves these
-directly** — no Worker invocation per request, and R2 answers `Range`
-natively for progressive loaders. Publish also sets the bucket CORS policy
-and a `Cross-Origin-Resource-Policy: cross-origin` response rule, without
-which COEP `require-corp` would silently block them.
+directly** — no Worker invocation per request, and R2 answers `Range` natively
+for progressive loaders. (A Worker reading through the R2 binding bypasses the
+edge cache, which is why these do not go through it.) Publish also sets the
+bucket CORS policy and a `Cross-Origin-Resource-Policy: cross-origin` response
+rule, without which COEP `require-corp` would silently block them.
 
 Unlike `/{buildId}/assets/*`, these URLs do not change when you deploy, so
-returning users do not re-download unchanged files. Assets that no build
-from the last `retentionDays` (default 7) references are deleted from R2
+returning users do not re-download unchanged files. Assets that no build from
+the last `retentionDays` (default 7) references are deleted from R2
 automatically, along with expired `builds/` prefixes.
 
 Requires a provisioned app domain — publish fails rather than emitting URLs
@@ -904,8 +903,8 @@ nothing serves. Configure in `.uglyapp`:
 "staticAssets": { "dir": "static", "retentionDays": 7 }
 ```
 
-Dev serves the same files off disk at same-origin, so a newly added asset
-works before it has ever been published.
+Dev serves the same files off disk at same-origin, so a newly added asset works
+before it has ever been published.
 
 ### `hostBundle` — serve the vite bundle from the CDN too
 
@@ -920,20 +919,19 @@ prefixed, a byte-identical chunk keeps its URL across deploys — so returning
 users re-download only what actually changed, and each deploy uploads a
 handful of KB instead of the whole bundle.
 
-The first deploy only provisions; the bundle moves to the CDN on the next
-one. That is deliberate — a single pass would point the bundle at a hostname
-whose TLS certificate may not have issued yet.
-
-**Workers are handled for you, but know why.** The bundle is then
-cross-origin, and `new Worker(url)` *rejects a cross-origin script URL
-outright* — that is structural, and no CORS or CORP header lifts it.
-`bootstrapApp` installs a shim that routes such URLs through a same-origin
-`blob:` importing the real script, so `new Worker(new URL('./x.worker.ts',
-import.meta.url))` keeps working. `SharedWorker` is **not** shimmed: every
-blob URL is unique, so the same trick would give each caller a private
-worker and break sharing. Register service workers by root-absolute path
-(`/sw.js`) — `register()` resolves against the document, so those stay
-same-origin.
+The first deploy only provisions; the bundle moves to the CDN on the next one.
+That is deliberate — a single pass would point the bundle at a hostname whose
+TLS certificate may not have issued yet.
+
+**Workers are handled for you, but know why.** The bundle is then cross-origin,
+and `new Worker(url)` *rejects a cross-origin script URL outright* — that is
+structural, and no CORS or CORP header lifts it. `bootstrapApp` installs a
+shim that routes such URLs through a same-origin `blob:` importing the real
+script, so `new Worker(new URL('./x.worker.ts', import.meta.url))` keeps
+working. `SharedWorker` is **not** shimmed: every blob URL is unique, so the
+same trick would give each caller a private worker and break sharing. Register
+service workers by root-absolute path (`/sw.js`) — `register()` resolves
+against the document, so those stay same-origin.
 
 ---
 
@@ -965,15 +963,16 @@ const cronHandlers: WorkerHandlers<typeof cronTasks> = {
 configurator.setWorkers(cronTasks, cronHandlers);
 ```
 
-Each worker can have `inputSchema`, `outputSchema`, `schedule`, `timeout`,
-`description`. Workers without a schedule are still invocable via
-`POST /_workers/run` (auth: localhost in dev, `Authorization: Bearer $CRON_SECRET`
-in prod). Scheduled workers also appear in `/_cron/manifest` for the deploy
-orchestrator.
+Each worker can have `inputSchema`, `outputSchema`, `schedule`,
+`timeout`, `description`. Workers without a schedule are still
+invocable via `POST /_workers/run` (auth: localhost in dev,
+`Authorization: Bearer $CRON_SECRET` in prod). Scheduled workers also
+appear in `/_cron/manifest` for the deploy orchestrator.
 
-On the Workers adapter, scheduled workers dispatch through Cloudflare Cron
-Triggers and durable queueing goes through Cloudflare Queues. On the Node
-adapter, `enqueueWorker` runs the handler inline (in-process queues only).
+On the Workers adapter, scheduled workers dispatch through Cloudflare
+Cron Triggers and durable queueing goes through Cloudflare Queues. On
+the Node adapter, `enqueueWorker` runs the handler inline (in-process
+queues only).
 
 ---
 
@@ -988,9 +987,9 @@ configurator.setStrings({
 });
 ```
 
-The framework injects `window.__LANG__`, `window.__STRINGS_VERSION__`, and
-`window.__CRITICAL_STRINGS__` into SSR HTML. Use `useLocalizer()` /
-`useStrings()` / `useLang()` / `useChangeLanguage()` on the client.
+The framework injects `window.__LANG__`, `window.__STRINGS_VERSION__`,
+and `window.__CRITICAL_STRINGS__` into SSR HTML. Use `useLocalizer()`
+/ `useStrings()` / `useLang()` / `useChangeLanguage()` on the client.
 
 ---
 
@@ -1015,9 +1014,10 @@ export const experiments: Experiment[] = [
 configurator.setExperiments(experiments);
 ```
 
-Bucketing is deterministic: `hash(experimentId + userId)` (or `sessionId`
-for unauthenticated users). The framework's `initSession` / `captureEvent`
-requests automatically tag events with the user's branch assignments.
+Bucketing is deterministic: `hash(experimentId + userId)` (or
+`sessionId` for unauthenticated users). The framework's `initSession`
+/ `captureEvent` requests automatically tag events with the user's
+branch assignments.
 
 ---
 
@@ -1043,15 +1043,17 @@ requests automatically tag events with the user's branch assignments.
 
 ## Two-adapter architecture
 
-The same developer source compiles for two runtimes via `src/server/adapter/`:
+The same developer source compiles for two runtimes via
+`src/server/adapter/`:
 
 - **Adapter A — Node + TCP** (`src/server/adapter/node/`): default for `npm run dev` and any non-Workers deploy. Wraps `pg.Pool`, `nats.js`, AWS S3 SDK.
 - **Adapter B — Cloudflare Workers** (`src/server/adapter/workers/`): used when the Studio publish flow deploys to Cloudflare. Hono router + Durable Objects (one `CollectionDO` per project-collection, plus a `SessionDO` per user WS) + `@neondatabase/serverless` HTTP driver + R2 binding + Cloudflare Cron Triggers + Cloudflare Queues.
 
-Developer-facing APIs (`createTypedDB`, `subscribeDoc`, `createStorageClient`,
-`setCronTasks`, `setWorkers`) don't change between adapters. Local Workers dev
-boots via `npm run dev:workers`, which starts a small Node HTTP proxy speaking
-Neon's wire format so the Worker can talk to a real Postgres.
+Developer-facing APIs (`createTypedDB`, `subscribeDoc`,
+`createStorageClient`, `setCronTasks`, `setWorkers`) don't change
+between adapters. Local Workers dev boots via `npm run dev:workers`,
+which starts a small Node HTTP proxy speaking Neon's wire format so
+the Worker can talk to a real Postgres.
 
 ---
 
@@ -1106,8 +1108,8 @@ Browser-visible variables must be prefixed `VITE_` and consumed via
 | `ugly-app feedback:dev` / `feedback:prod` | Query user feedback. |
 | `ugly-app feedback:submit` / `feedback:resolve` | Manage feedback (run with `--help` for flags). |
 
-Inside a scaffolded project, the same commands are available via `npm run …`
-scripts — see `templates/CLAUDE.md`.
+Inside a scaffolded project, the same commands are available via `npm
+run …` scripts — see `templates/CLAUDE.md`.
 
 ---