ugly-app 0.1.956 → 0.1.958

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
@@ -21,31 +21,25 @@ npm run dev
 
 | Import path | Contents |
 |-------------|----------|
-| `ugly-app` | Server: `createApp`, `TypedDB`, auth, AI clients, NATS, storage, email, push, workers. |
-| `ugly-app/shared` | Cross-tier: `defineRequests`, `defineCollections`, `definePage`, `defineWorkers`, Zod, experiments, time constants. |
+| `ugly-app` | Server: `createApp`, `TypedDB`, auth, AI clients, storage, NATS, workers. |
+| `ugly-app/shared` | Cross-tier: `defineRequests`, `defineCollections`, `definePage`, `defineWorkers`, Zod, experiments. |
 | `ugly-app/client` | React: `bootstrapApp`, `createRouter`, `lazyPage`, `AppProvider`, components, animations, audio, AI helpers. |
 | `ugly-app/server/adapter/workers` | Cloudflare Workers entry (Hono router + Durable Objects + Neon HTTP driver + R2). |
 | `ugly-app/server/ssr` | SSR renderer used by the Workers adapter. |
-| `ugly-app/conversation/{shared,server,client,engine}` | AI chat sessions with persisted history. |
-| `ugly-app/collab/{server,client}` | Yjs-based collaborative editing. |
-| `ugly-app/markdown/{shared,client}` | Markdown rendering + editor. |
-| `ugly-app/search/{shared,server}` | Search primitives. |
-| `ugly-app/agent/{shared,server,client}` | Agent-mode SSE + tool orchestration. |
-| `ugly-app/webrtc`, `ugly-app/webrtc/server` | WebRTC video rooms. |
-| `ugly-app/three/{server,client}` | Three.js scene helpers. |
-| `ugly-app/native`, `ugly-app/native/server` | Native task host + conformance harness. |
-| `ugly-app/inspect`, `ugly-app/inspect/agent`, `ugly-app/inspect/ui` | UX inspection agent + host bundle. |
-| `ugly-app/worker` | Worker queue runtime. |
-| `ugly-app/playwright` | E2E test utilities (`inspectWindow`, `expectClean`, `setDevice`, …). |
+| `ugly-app/playwright` | E2E test utilities. |
 | `ugly-app/testing` | Test-mode helpers. |
 | `ugly-app/vite`, `ugly-app/eslint` | Build-tool plugins. |
 
+Additional per-feature bundles: `conversation`, `character`, `collab`,
+`markdown`, `search`, `agent`, `webrtc`, `three`, `native`, `inspect`,
+`worker` — each with its own `shared` / `server` / `client` split.
+
 ---
 
 ## Server — `createApp()`
 
-Single server entry point. Returns an `App` that owns Express, the
-WebSocket server, the typed DB, and the RPC dispatcher.
+`createApp` is the single server entry. It owns Express, the WebSocket
+server, the typed DB, and the RPC dispatcher.
 
 ```ts
 // server/index.ts
@@ -103,29 +97,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 +152,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,23 +165,27 @@ 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. |
-| `adminGetPerfLogs` | Admin-only perf telemetry read. |
+| `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. |
 | `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.
 
 ---
 
@@ -222,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`)
 
@@ -259,20 +259,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).
 
 ---
 
@@ -297,21 +296,19 @@ 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.
+TypeScript inference. `PageMeta` fields:
 
-**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 (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,19 +329,19 @@ 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
@@ -369,10 +366,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 +398,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,8 +431,8 @@ 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
+`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.
 
@@ -445,10 +441,10 @@ The default layer animates open with `easeOut` (250 ms) and closed with
 `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`.
+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 +467,9 @@ bootstrapApp({
 });
 ```
 
+`bootstrapApp(options): void` — returns nothing; it renders directly to the
+DOM.
+
 **`BootstrapAppOptions`:**
 
 | Field | Description |
@@ -488,28 +487,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.
 
 ### `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 +516,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
 
@@ -555,8 +552,8 @@ router's.
 | `connectionState` | `'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`. |
 | `disconnect()` | Close the connection. |
 
-For pure HTTP (no WebSocket), use `createHttpClient({ requests, token?, baseUrl? })`
-from `ugly-app/client`.
+For pure HTTP (no WebSocket), use
+`createHttpClient({ requests, token?, baseUrl? })` from `ugly-app/client`.
 
 ---
 
@@ -565,14 +562,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)
 
@@ -596,9 +593,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 +629,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 +655,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
 
@@ -745,10 +742,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 +766,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
 
@@ -858,24 +854,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).
+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,26 +880,25 @@ 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
-nothing serves. Configure in `.uglyapp`:
+Requires a provisioned app domain — publish fails rather than emitting
+URLs nothing serves. Configure in `.uglyapp`:
 
 ```json
 "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
 
@@ -913,25 +907,26 @@ before it has ever been published.
 ```
 
 Opt-in. Publish provisions `static.<zone>` (or `<app>-static.<zone>` for a
-subdomain app), persists the `baseUrl`, and vite then emits every asset URL
-against it. Because the URLs are content-addressed rather than build-id
-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.
+subdomain app), persists the `baseUrl`, and vite then emits every asset
+URL against it. Because the URLs are content-addressed rather than
+build-id 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.
 
 ---
 
@@ -963,16 +958,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 +981,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 +1008,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.
 
 ---
 
@@ -1050,10 +1043,10 @@ The same developer source compiles for two runtimes via
 - **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.
+`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 +1101,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`.
 
 ---