ugly-app 0.1.949 → 0.1.950

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,29 +103,31 @@ 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`
 
-| Field | Description |
-|-------|-------------|
+`App` extends `AppRouter`, so `dispatch(name, input, userId)` is available for
+in-process invocation of any registered handler.
+
+| Member | Description |
+|--------|-------------|
 | `start(port?)` | Start the server (default 3000; templates use 4321). |
-| `db` | The `TypedDB<Map>` (map inferred from your collections + framework built-ins). |
+| `db` | `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)` | Invoke a registered RPC handler programmatically (inherited from `AppRouter`). |
+| `dispatch(name, input, userId)` | `Promise<unknown>` — invoke any registered RPC handler programmatically. |
 | `registerRoutes(fn)` | Mount additional Express routes after creation. |
-| `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. |
+| `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. |
 
-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.
+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.
 
 ### `AppConfigurator`
 
@@ -156,8 +158,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
@@ -169,30 +171,37 @@ 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.
+`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.
 
-| Name | Purpose |
-|------|---------|
+| Name | Notes |
+|------|-------|
 | `userGet` | Returns `{ userId, name, avatarUri }` for the given user (or caller). |
 | `initSession` / `captureEvent` | Session + event logging tagged with experiment branches (public — no auth). |
-| `textGen` / `imageGen` | AI proxies — server-validated, billed through ugly.bot. |
-| `kagiSearch` / `kagiSummarize` / `kagiEnrichWeb` / `kagiEnrichNews` | Web search via ugly.bot. |
+| `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. |
 | `uploadUrl` | Issues a presigned PUT for the `temp` bucket. |
-| `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. |
+| `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. |
 | `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`)
 
@@ -222,8 +231,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`)
 
@@ -259,20 +268,19 @@ 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 (framework pattern; e.g. `userPublic` resolves via ugly.bot).
+- `getter?(ids)` — batch resolver for collections with no local table (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).
 
 ---
 
@@ -295,23 +303,20 @@ 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.
-
-**Options** (all optional):
+`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime object
+carrying `PageMeta` plus a phantom `_params` used only for TypeScript
+inference. `PageMeta` fields:
 
-- `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.
+- `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.
 - `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 effectively 1 year (`DEFAULT_SSR_CACHE_TIMEOUT`) because the `buildId` is part of the cache key. Override only for pages that drift between deploys.
+- `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.
 
 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 give the
-registry a name.
+`definePages<T>(p)` is a pass-through identity — use it to name the registry.
 
 ### `createRouter()` (`ugly-app/client`)
 
@@ -332,23 +337,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?` — `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?: 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.
 
 **Returns:**
 
-- **`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`).
+- **`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).
 - **`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`
 
@@ -369,10 +374,9 @@ 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 the fresh `index.html` with
-new 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 fresh chunk hashes.
 
 ```ts
 // pages/SlowPageLoader.tsx
@@ -402,15 +406,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();
@@ -435,20 +439,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`.
 
 ---
 
@@ -471,6 +475,9 @@ bootstrapApp({
 });
 ```
 
+`bootstrapApp(options): void` — returns nothing; it renders directly to the
+DOM.
+
 **`BootstrapAppOptions`:**
 
 | Field | Description |
@@ -488,28 +495,28 @@ bootstrapApp({
 | `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 {
@@ -517,28 +524,26 @@ const {
   user,          // UserBase doc
   socket,        // AppSocket — typed RPC client
   uglyBotSocket, // UglyBotSocket | null — direct platform socket for STT/TTS
-  showPopup,     // flat overlay layer (see note) — returns popup id
-  hidePopup,
-  hideAllPopups,
+  showPopup,     // (content: ReactElement) => id — flat overlay layer (see note)
+  hidePopup,     // (id: string) => void
+  hideAllPopups, // () => void
   runAsync,      // (label, async () => {…}, options?) — shows loading overlay
-  splashDone,    // (step: string) — mark a splash-screen step complete
+  splashDone,    // (step: string) => void — 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.
-`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.
+`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.
 
 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
 
@@ -565,14 +570,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.
+`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.
 
 ### Mode A — ugly.bot OAuth (default)
 
@@ -584,9 +589,9 @@ code (incl. `<AuthRoot>`) can branch correctly.
 
 ### 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.
@@ -596,9 +601,9 @@ configured it adds 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
 
@@ -632,8 +637,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
 
@@ -658,10 +663,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
 
@@ -695,8 +700,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
 
@@ -745,10 +750,9 @@ 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
 
@@ -770,9 +774,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
 
@@ -783,8 +787,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
 
@@ -809,8 +813,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';
@@ -822,9 +826,8 @@ 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';
@@ -858,24 +861,23 @@ 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'
@@ -885,15 +887,14 @@ 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. (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.
+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.
 
 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
@@ -903,8 +904,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
 
@@ -919,19 +920,20 @@ 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.
 
 ---
 
@@ -963,16 +965,15 @@ 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).
 
 ---
 
@@ -987,9 +988,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.
 
 ---
 
@@ -1014,10 +1015,9 @@ 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,17 +1043,15 @@ 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.
 
 ---
 
@@ -1108,8 +1106,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`.
 
 ---