ugly-app 0.1.923 → 0.1.925

package/README.md

@@ -1,30 +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`.
-
-## What's included
-
-- **Server** — Express + WebSocket with typed RPC and Zod validation.
-- **Client** — React 19 + Vite with typed routing, lazy pages, animated transitions, and a router-owned popup layer.
-- **Database** — `TypedDB` over Postgres (JSONB) or Cloudflare D1, with full-text and vector search.
-- **Auth** — HttpOnly cookies + JWT. ugly.bot OAuth by default; magic-link / Google in `mode: 'self'`.
-- **AI** — Text, JSON, image, embeddings, web search — proxied through ugly.bot.
-- **Realtime** — NATS pub/sub and doc change subscriptions (`trackDoc` / `trackDocs`).
-- **Storage** — S3-compatible buckets with presigned uploads.
-- **Workers & cron** — `setWorkers()` registers named async tasks with optional Zod schemas and cron schedules.
-- **Two-adapter deploy** — Same source runs on Node (Express) or Cloudflare Workers (Hono + Durable Objects).
-- **CLI** — `ugly-app` commands for dev, build, deploy, migrations, logs, AI, and auth.
-
-## Quick start
+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
@@ -32,16 +17,35 @@ cd my-app
 npm run dev
 ```
 
-The scaffold gives you a working app at `http://localhost:4321` with todo CRUD,
-AI chat, file upload, auth demo, collab editing, and other test pages already
-wired up.
+## Package entry points
+
+| 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/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/testing` | Test-mode helpers. |
+| `ugly-app/vite`, `ugly-app/eslint` | Build-tool plugins. |
 
 ---
 
 ## 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
@@ -74,7 +78,7 @@ const app = createApp(
       defaultLang: stringsDef.defaultLang,
       langs: stringsDef.langs,
       criticalKeys: stringsDef.criticalKeys,
-      getTable: (lang) => ({ en, es } as Record<string, unknown>)[lang] ?? en,
+      getTable: (lang) => (lang === 'es' ? es : en),
     });
     configurator.setWorkers(cronTasks, cronHandlers);
     configurator.setOnEmail(async (inbound: InboundEmail) => { /* … */ });
@@ -99,10 +103,10 @@ 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`
 
@@ -114,21 +118,21 @@ call `configurator.setPages()` still work — they just get the loose
 | `wss` | The main `WebSocketServer` (path set via `setWsPath`, default `/rpc`). |
 | `dispatch(name, input, userId)` | Invoke a registered RPC handler programmatically (inherited from `AppRouter`). |
 | `registerRoutes(fn)` | Mount additional Express routes after creation. |
-| `pushSend(input)` | Send a push whose click-through target is a route from this app's `pages`. `page` and `query` are type-checked when the registry carries `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`. 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 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 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`
 
 Every method is optional; `setPages` is what mounts the SPA.
 
-| Method | Description |
-|--------|-------------|
+| Method | Purpose |
+|--------|---------|
 | `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. Dev runs Vite in middleware mode; prod serves `clientDistPath` (default `dist/client`). Provide `renderPage(routeName, params) => Promise<string>` to SSR any `ssr: true` pages. |
 | `setUserHelper(helper)` | A `UserHelper<UserBase>` the framework uses to look up / create users on WebSocket auth. Falls back to a minimal shim if unset. |
 | `setOnUserCreate(handler)` | `(userId, { email?, phone? }, db) => Promise<void>` — called on first login; create the user record. |
@@ -138,11 +142,11 @@ Every method is optional; `setPages` is what mounts the SPA.
 | `setWsPath(path)` | Override the WebSocket path (default `/rpc`). |
 | `setOnWsAuth(handler)` | `(ws, userId, req) => void` — fires after a socket session authenticates. |
 | `setOnAfterStart(handler)` | `(db) => Promise<void>` — called once after data-proxy + NATS are ready. |
-| `setOnMinuteTick(fn)` / `setOnHourlyTick(fn)` | Framework-managed periodic callbacks. Fire only when `CLOCK_ENABLED=true`. |
+| `setOnMinuteTick(fn)` / `setOnHourlyTick(fn)` | Framework-managed periodic callbacks. Fire only when `CLOCK_ENABLED=true`. The hourly handler receives `(now, currentHour)`. |
 | `setHealthHandler(fn)` | Override the default `GET /health`. |
 | `setExperiments(experiments)` | Register `Experiment` definitions for `initSession` / `captureEvent` bucketing. |
 | `setIsAdmin(fn)` | `(userId, db) => boolean \| Promise<boolean>` — gate for admin-only framework requests. Defaults to matching `MAINTAIN_BOT_USER_ID`. |
-| `setZeroTestUserBalance(fn)` | `(userId) => Promise<void>` — how to zero a synthetic test user's balance so the out-of-credit path can be exercised. Only apps that own the balance ledger (i.e. ugly.bot itself) should register this. |
+| `setZeroTestUserBalance(fn)` | How to zero a synthetic test user's balance so the out-of-credit path can be exercised. Only apps that own the balance ledger (i.e. ugly.bot itself) should register this. |
 | `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot` (delivered as internal HTTP). |
 | `setCronTasks(tasks, handlers)` | **Deprecated.** Legacy cron-only registry — prefer `setWorkers()`. |
 | `setWorkers(workers, handlers)` | Register named async tasks with optional Zod input schema and cron schedule. Powers `GET /_workers/manifest`, `POST /_workers/run`, and the cron orchestrator. Scheduled workers are mirrored into the cron registry automatically. |
@@ -152,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`, etc.).
+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
@@ -165,9 +169,9 @@ 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.
 
 | Name | Purpose |
 |------|---------|
@@ -176,19 +180,19 @@ framework's defaults.
 | `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 (see the "sharing links" rule in `CLAUDE.md`). |
-| `feedbackReportCreateNoAuth` / `errorLogCaptureNoAuth` / `perfSnapshotCaptureNoAuth` | Same-origin, public endpoints used by browser telemetry to write into the project's Postgres. |
+| `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()` (or `MAINTAIN_BOT_USER_ID`). |
+| `adminCreateTestUser` / `adminListTestUsers` / `adminDeleteTestUser` | Admin-only synthetic-user management. Gated by `setIsAdmin()`. |
 | `projectPlanList` / `projectPlanCreate` / `projectPlanUpdate` / `projectPlanDelete` | Project plan CRUD used by Studio. |
 
 ---
 
 ## 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`)
 
@@ -218,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`)
 
@@ -238,7 +242,7 @@ export const collections = defineCollections({
   todo: {
     schema: TodoSchema,
     meta: {
-      db: neon,                // REQUIRED — `neon` (Postgres) or `d1` (SQLite / Cloudflare D1)
+      db: neon,                // REQUIRED — `neon` (Postgres) or `d1` (SQLite / D1)
       cache: true,             // or { ttlMs: 60_000 }
       trackable: true,
       public: false,
@@ -249,7 +253,7 @@ export const collections = defineCollections({
 ```
 
 **`CollectionMeta`:**
-- `db` — **required.** `neon` (Postgres) or `d1` (Cloudflare D1 / SQLite). Both handles are exported from `ugly-app/shared`. Omitting it is a compile error and runtime throw. A `d1` collection may also declare `search` (SQLite FTS5) and/or `vector` (Cloudflare Vectorize).
+- `db` — **required.** `neon` (Postgres) or `d1` (Cloudflare D1 / SQLite). Both handles are exported from `ugly-app/shared`. Omitting it is a compile error and runtime throw.
 - `cache` — `true` / `false` / `{ ttlMs }`. When enabled, `getDoc` / `getByIds` read from an LRU cache; writes invalidate it.
 - `trackable` — enables real-time `trackDoc` / `trackDocs` via change-stream NATS notifications.
 - `public` — allow unauthenticated client reads.
@@ -260,21 +264,22 @@ export const collections = defineCollections({
 - `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`).
+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`).
 
-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).
 
 ---
 
 ## Routing
 
-Route definitions live in `shared/pages.ts`; the client-side router is created
-by `createRouter({ pages, allPages?, ssrPages? })`.
+Route definitions live in `shared/pages.ts`; the client-side router is
+created by `createRouter({ pages, allPages?, ssrPages? })`.
 
 ### `definePage` / `definePages` (`shared/pages.ts`)
 
@@ -282,17 +287,17 @@ by `createRouter({ pages, allPages?, ssrPages? })`.
 import { definePage, definePages } from 'ugly-app/shared';
 
 export const pages = definePages({
-  '':              definePage<{}>({ auth: false }),             // /
-  'user/:userId':  definePage<{ userId: string }>(),            // /user/abc
+  '':              definePage<{}>({ auth: false }),                     // /
+  'user/:userId':  definePage<{ userId: string }>(),                    // /user/abc
   'search':        definePage<{ q?: string }>({ auth: false, cacheQuery: ['q'] }),
   'blog/*slug':    definePage<{ slug: string }>({ ssr: true, auth: false }),
 });
 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.
+`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime
+object carrying `PageMeta` plus a phantom `_params` used only for
+TypeScript inference.
 
 **Options** (all optional):
 
@@ -302,11 +307,11 @@ inference.
 - `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 give the registry a
-name.
+`definePages<T>(p)` is a pass-through identity — use it to give the
+registry a name.
 
 ### `createRouter()` (`ugly-app/client`)
 
@@ -329,21 +334,21 @@ export const {
 - `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.
 
-**`createRouter` returns:**
+**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`).
-- **`useRouter()`** — returns the `RouterContextValue<Pages>` (typed navigation + popup API). Throws if used outside `<RouterProvider>`.
+- **`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`
 
@@ -364,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 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 the fresh `index.html` with
+new chunk hashes.
 
 ```ts
 // pages/SlowPageLoader.tsx
@@ -393,18 +399,18 @@ const {
 
 push('user/:userId', { userId: '123' });   // → /user/123
 replace('search', { q: 'hello' });         // → /search?q=hello
-back();                                     // browser history back
+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();
@@ -416,7 +422,7 @@ const handle = openPopup(<MyContent />, {
   containerStyle: { /* CSS for the content wrapper */ },
   backgroundStyle: { /* CSS for the backdrop */ },
   animConfig: { duration: 300, easing: myEasingFn },
-  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the layer renderer
+  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the layer
 });
 
 handle.hide(); // dismiss programmatically — same as router.closePopup(handle.id)
@@ -429,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`.
 
 ---
 
@@ -473,7 +479,7 @@ bootstrapApp({
 | `messages?` | Your `MessageRegistry` (merged with framework messages). |
 | `RouterProvider` | The `RouterProvider` component returned from `createRouter()`. |
 | `render` | Callback returning the app's UI tree (typically `<RouterView />`). |
-| `root?` | Root element / selector (default `'#root'`). |
+| `root?` | Root element or CSS selector (default `'#root'`). |
 | `fallback?` | UI for unmatched routes (default: tiny "404"). |
 | `socketUrl?` | Override the WebSocket path (default `/rpc`). |
 | `strings?` | Localization config — when present, wraps the tree with `<StringsProvider>`. |
@@ -482,54 +488,57 @@ 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.
+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.
 
-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 {
   userId,        // current user id (string)
   user,          // UserBase doc
   socket,        // AppSocket — typed RPC client
-  uglyBotSocket, // UglyBotSocket | null — direct platform socket for STT/TTS, etc.
-  showPopup,     // AppProvider-owned popup layer (see note below) — returns popup id
+  uglyBotSocket, // UglyBotSocket | null — direct platform socket for STT/TTS
+  showPopup,     // flat overlay layer (see note) — returns popup id
   hidePopup,
   hideAllPopups,
-  runAsync,      // (label, async () => {…}, options?) — shows loading overlay while pending
+  runAsync,      // (label, async () => {…}, options?) — shows loading overlay
   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. `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.
+`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
 
@@ -556,13 +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.
+`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client
+code (incl. `<AuthRoot>`) can branch correctly.
 
 ### Mode A — ugly.bot OAuth (default)
 
@@ -574,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.
@@ -586,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
 
@@ -622,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
 
@@ -648,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
 
@@ -685,18 +695,18 @@ 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
 
 ```ts
-// Full-text search — requires `search: { fields, language? }` on the collection
+// Full-text — requires `search: { fields, language? }` on the collection
 const hits = await db.searchDocs(collections.note, 'react hooks', { limit: 10 });
 
-// Vector search — requires `vector: { dimensions }` on the collection; vector supplied at write time
+// Vector — requires `vector: { dimensions }` on the collection; vector supplied at write time
 const similar = await db.vectorSearch(collections.note, embeddingVector, { limit: 10 });
-const vecs    = await db.getVecs(collections.note, ids);                   // pull raw stored vectors
+const vecs    = await db.getVecs(collections.note, ids);
 ```
 
 ### Caching
@@ -733,11 +743,12 @@ Imports available from `ugly-app`:
 
 ---
 
-## AI
+## 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
 
@@ -759,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
 
@@ -772,14 +783,14 @@ 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
 
 ```ts
 import { createEmbeddingClient, cosineSimilarity } from 'ugly-app';
-const embeddings = createEmbeddingClient();       // optional providerName arg
+const embeddings = createEmbeddingClient();
 const vector = await embeddings.embed('hello world');
 const sim    = cosineSimilarity(vectorA, vectorB);
 ```
@@ -798,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';
@@ -811,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';
@@ -846,15 +858,17 @@ 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).
 
 ---
 
@@ -886,15 +900,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).
 
 ---
 
@@ -909,9 +924,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.
 
 ---
 
@@ -936,9 +951,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.
 
 ---
 
@@ -962,42 +978,19 @@ requests automatically tag events with the user's branch assignments.
 
 ---
 
-## Package entry points
-
-| Import path | Description |
-|-------------|-------------|
-| `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/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/testing` | Test-mode helpers. |
-| `ugly-app/vite`, `ugly-app/eslint` | Build-tool plugins. |
-
----
-
 ## 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.
 
 ---
 
@@ -1052,8 +1045,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`.
 
 ---
 
@@ -1074,5 +1067,5 @@ The framework refuses to start when drift is detected (set
 ## Tech stack
 
 Node.js · TypeScript · Express · React 19 · Vite · PostgreSQL (JSONB) ·
-Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · Cloudflare Workers +
-Durable Objects (Adapter B) · ugly.bot platform
+Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · Cloudflare
+Workers + Durable Objects (Adapter B) · ugly.bot platform