ugly-app 0.1.873 → 0.1.875

package/README.md

@@ -1,21 +1,22 @@
 # ugly-app
 
-A full-stack TypeScript framework for shipping production web apps with one CLI. Scaffold with `npx ugly-app init my-app` and get an opinionated Express + React + PostgreSQL stack with built-in auth, type-safe RPC over WebSocket and HTTP, real-time document tracking, AI generation, storage, and a CLI for every workflow.
+A full-stack TypeScript framework for shipping production web apps with one CLI. Scaffold with `npx ugly-app init my-app` and get an opinionated Express + React + PostgreSQL stack with built-in auth, type-safe RPC over WebSocket and HTTP, real-time document tracking, AI generation, storage, cron/workers, and a CLI for every workflow.
 
-ugly-app is designed to be deployed and operated through [ugly.bot](https://ugly.bot) — the platform handles auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of this through the project's dev tunnel and the per-app `UGLY_BOT_TOKEN`.
+ugly-app is designed to be deployed and operated through [ugly.bot](https://ugly.bot) — the platform provides auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of this through the project's dev tunnel and the per-app `UGLY_BOT_TOKEN`.
 
 ## What's included
 
 - **Server**: Express + WebSocket with type-safe RPC and Zod validation
-- **Client**: React + Vite with typed routing, lazy pages, animated transitions, popup management
-- **Database**: PostgreSQL (JSONB) via the data proxy, with full-text search (`search`) and vector search (Qdrant `vector`)
-- **Auth**: HttpOnly cookies + JWT, ugly.bot OAuth out of the box, extensible via `AuthProvider`
-- **AI**: Text, image, embeddings, web search — all proxied through ugly.bot (no per-provider keys in your app)
+- **Client**: React + Vite with typed routing, lazy pages, animated transitions, popup layer
+- **Database**: PostgreSQL (JSONB) via the data proxy, with full-text search and vector search (Qdrant)
+- **Auth**: HttpOnly cookies + JWT; ugly.bot OAuth out of the box, magic-link / Google via `mode: 'self'`
+- **AI**: Text, JSON, image, embeddings, web search — all proxied through ugly.bot (no per-provider keys in your app)
 - **Realtime**: NATS pub/sub and document change subscriptions (`trackDoc` / `trackDocs`)
 - **Storage**: S3-compatible buckets with presigned uploads
 - **Workers & cron**: `setWorkers()` registers named async tasks with optional Zod input schemas and cron schedules
 - **Localization**: Strings tables with critical-string SSR injection
 - **Experiments**: Deterministic A/B bucketing tied to event logging
+- **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
@@ -26,7 +27,7 @@ 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 ~20 other test pages wired up.
+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 wired up.
 
 ---
 
@@ -40,10 +41,11 @@ The single server entry point. Returns an `App` that owns Express, the WebSocket
 import {
   createApp,
   type AppConfigurator,
+  type InboundEmail,
   type RequestHandlers,
 } from 'ugly-app';
-import { dbDefaults } from 'ugly-app/shared';
 import { nanoid } from 'nanoid';
+import { dbDefaults } from 'ugly-app/shared';
 import { requests, messages } from '../shared/api';
 import { collections } from '../shared/collections';
 import { pages } from '../shared/pages';
@@ -53,7 +55,9 @@ const app = createApp(
   {
     createTodo: async (userId, { text }) => {
       const _id = nanoid();
-      await app.db.setDoc(collections.todo, { _id, userId, text, done: false, ...dbDefaults() });
+      await app.db.setDoc(collections.todo, {
+        _id, userId, text, done: false, ...dbDefaults(),
+      });
       return { id: _id };
     },
   } satisfies RequestHandlers<typeof requests>,
@@ -69,37 +73,43 @@ await app.start(parseInt(process.env['PORT'] ?? '4321'));
 **Signature:**
 
 ```typescript
-function createApp<R extends AppRegistryBase, Defs extends CollectionDefRegistry>(
+function createApp<
+  R extends AppRegistryBase,
+  Defs extends CollectionDefRegistry,
+>(
   registry: R,                                       // { requests, messages }
   requests: Partial<RequestHandlers<R['requests']>>, // handler implementations
   appDefs: Defs,                                     // collections from defineCollections()
   configure?: (c: AppConfigurator) => void,
   deleteHandlers?: DeleteHandlers<Defs>,             // per-collection onDelete hooks
-): App<CollectionMap<typeof BUILTIN_DEFS & Defs>>;
+): App<CollectionMap<typeof BUILTIN_DEFS & Defs>, RegistryPages<R>>;
 ```
 
-The returned `App` object has:
-- `start(port?)` — start the server (default port 3000; templates use 4321)
-- `db` — the `TypedDB` instance
-- `httpServer` — the underlying Node `http.Server`
-- `wss` — the main `WebSocketServer` (path set by `setWsPath`, default `/rpc`)
-- `dispatch(name, input, userId)` — invoke an RPC handler programmatically
-- `registerRoutes(fn)` — mount more Express routes after creation
-- `pushSend({ userId, page, query, ...notification })` — send a push notification whose click-through target is a route from this app's `pages` table. `page` is type-checked against route keys (when `pages` is provided on the createApp registry), `query` against that route's params. The framework builds the absolute URL and stamps project identity so the client can open the dock app.
+The returned `App` object exposes:
+
+| Field | Description |
+|-------|-------------|
+| `start(port?)` | Start the server (default port 3000; templates use 4321). |
+| `db` | The `TypedDB<Map>` instance (map is inferred from your collections + framework built-ins). |
+| `httpServer` | The underlying Node `http.Server`. |
+| `wss` | The main `WebSocketServer` (path set by `setWsPath`, default `/rpc`). |
+| `dispatch(name, input, userId)` | Invoke an RPC handler programmatically (inherited from `AppRouter`). |
+| `registerRoutes(fn)` | Mount more Express routes after creation. |
+| `pushSend(input)` | Send a push notification whose click-through target is a route from this app's `pages` table. `page` is type-checked against route keys (when `pages` is provided on the registry), `query` against that route's params. The framework builds the absolute URL and stamps project identity so the client can open the dock app. |
 
-Framework-managed background services start automatically: schema drift check, NATS connection + KV buckets (`TTS`, `RATELIMIT`), data-proxy connection, event counter flush, TTL cleanup for log tables, console / error capture, and ugly.bot log forwarding.
+Framework-managed background 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. Individual subsystems (Postgres, NATS, storage, AI providers) are loaded lazily so a host without `DATABASE_URL` / `NATS_URL` / `R2_BUCKET` doesn't pay their startup cost.
 
 ### `AppConfigurator`
 
-Passed to the optional fourth argument of `createApp`. Every method is optional.
+Passed to the optional 4th argument of `createApp`. Every method is optional (except `setPages` if you want the SPA served).
 
 | Method | Description |
 |--------|-------------|
-| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. In dev, runs Vite in middleware mode; in prod, serves `dist/client`. Provide `renderPage` for SSR on pages with `ssr: true`. |
-| `setUserHelper(helper)` | Customize how the framework reads / writes the `user` collection during WebSocket auth (default looks up by id in a generic `user` collection). |
-| `setOnUserCreate(handler)` | Called on first login with `(userId, { email?, phone? }, db)` — your chance to create the user record. |
-| `setAuth(provider)` | Replace the default ugly.bot OAuth provider. Must implement `verify(code)` and `authUrl(origin)`. |
-| `setOnSocketMessage(handler)` | Single raw-WebSocket message handler. Return `true` to consume, `false` to fall through. |
+| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. In dev, runs Vite in middleware mode; in prod, serves `dist/client`. Provide `renderPage(routeName, params) => Promise<string>` for SSR on pages marked `ssr: true`. |
+| `setUserHelper(helper)` | Customize how the framework reads/writes the `user` collection during WebSocket auth (default looks up by id in a generic `user` collection). |
+| `setOnUserCreate(handler)` | Called on first login with `(userId, { email?, phone? }, db)` — the app's chance to create the user record. |
+| `setAuth(provider)` | Replace the default auth provider. Must implement `verify(code)`, `authUrl(origin)`, optional `registerRoutes(router, { db, onUserCreate })`. |
+| `setOnSocketMessage(handler)` | Single raw-WebSocket message handler. `(ws, userId, msg) => boolean` — return `true` to consume, `false` to fall through. |
 | `addSocketMessageHandler(handler)` | Append to the handler chain; first to return `true` wins. |
 | `setWsPath(path)` | Override the WebSocket path (default `/rpc`). |
 | `setOnWsAuth(handler)` | `(ws, userId, req) => void` — fires after a socket session authenticates. |
@@ -108,16 +118,16 @@ Passed to the optional fourth argument of `createApp`. Every method is optional.
 | `setHealthHandler(fn)` | Override the default `GET /health` response. |
 | `setExperiments(experiments)` | Register `Experiment` definitions for `initSession` / `captureEvent` bucketing. |
 | `setIsAdmin(fn)` | `(userId, db) => boolean \| Promise<boolean>` — gate for admin-only framework requests (`adminCreateTestUser` / `list` / `delete`). Defaults to matching `MAINTAIN_BOT_USER_ID`. |
-| `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot` (called via internal HTTP). |
+| `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot` (delivered via internal HTTP). |
 | `setCronTasks(tasks, handlers)` | Legacy cron-only registry. Prefer `setWorkers()`. |
-| `setWorkers(workers, handlers)` | Register named async tasks with optional Zod input schema and cron schedule. Powers `/_workers/manifest`, `POST /_workers/run`, and the cron orchestrator. |
+| `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. |
 | `setStrings(config)` | Localization config — framework injects language + critical strings into SSR HTML and exposes `resolveLanguage` / `getCriticalStrings`. |
 | `registerRoutes(fn)` | Mount custom Express routes. |
 | `setWorkerQueue(queue)` | Register a `WorkerQueue` with `start()` / `stop()` for app lifecycle management. |
 
 ### Handler signatures
 
-Handlers are plain async functions — no context object:
+Handlers are plain async functions — no context object. Access state via captured imports (`app.db`, `storage`, `pgQuery`, `uglyBotRequest`, etc.).
 
 ```typescript
 // req() — public, userId may be null
@@ -127,11 +137,9 @@ getPublicData: async (userId: string | null, input) => { ... }
 getMe: async (userId: string, input) => { ... }
 ```
 
-Inside a handler, access state via captured imports — `app.db`, `storage`, `pgQuery`, `uglyBotRequest`, etc. There is no injected context.
-
 ### Built-in framework requests
 
-`createApp` automatically registers several framework handlers, accessible from any client via the normal RPC pipeline:
+`createApp` automatically registers several framework handlers, accessible from any client via the normal RPC pipeline. App-provided handlers with the same name override the framework's defaults.
 
 | Name | Purpose |
 |------|---------|
@@ -142,12 +150,10 @@ Inside a handler, access state via captured imports — `app.db`, `storage`, `pg
 | `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` | Same-origin, public endpoints used by the built-in browser telemetry (feedback + client-side error capture) to write into the project's own Postgres. |
+| `feedbackReportCreateNoAuth` / `errorLogCaptureNoAuth` | Same-origin, public endpoints used by the built-in browser telemetry to write into the project's own Postgres. |
 | `submitFeedbackBot` | Forwards `db.captureFeedback` writes for the maintain-bot persona. |
-| `feedbackReportResolve` | Admin-only — resolve or decline a feedback report (Workers-only via D1 telemetry). |
-| `adminCreateTestUser` / `adminListTestUsers` / `adminDeleteTestUser` | Admin-only — synthetic-user management. Gated by `setIsAdmin()` (or `MAINTAIN_BOT_USER_ID`). |
-
-App-provided handlers with the same name override the framework's defaults.
+| `feedbackReportResolve` | Admin-only — resolve or decline a feedback report. |
+| `adminCreateTestUser` / `adminListTestUsers` / `adminDeleteTestUser` | Admin-only synthetic-user management. Gated by `setIsAdmin()` (or `MAINTAIN_BOT_USER_ID`). |
 
 ---
 
@@ -214,7 +220,7 @@ export const collections = defineCollections({
 - `search?: { fields, language? }` — PostgreSQL full-text search columns.
 - `vector?: { dimensions, source }` — Qdrant vector index over the named JSONB path.
 
-All documents extend `DBObject`: `{ _id, version, created, updated }`. Use `dbDefaults()` to stamp the latter three on inserts.
+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` and then `npm run db:migrate`. The app refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true` only as a last resort).
 
@@ -226,18 +232,22 @@ import { definePage, definePages } from 'ugly-app/shared';
 export const pages = definePages({
   '':              definePage<{}>({ auth: false }),             // /
   'user/:userId':  definePage<{ userId: string }>(),            // /user/abc
-  'search':        definePage<{ q?: string }>({ auth: false }), // /search?q=foo
+  'search':        definePage<{ q?: string }>({ auth: false, cacheQuery: ['q'] }),
   'blog/*slug':    definePage<{ slug: string }>({ ssr: true }), // /blog/any/path
 });
 export type AppPages = typeof pages;
 ```
 
-- `:param` matches a single path segment; `*param` is greedy (captures slashes).
-- The generic on `definePage<Params>()` is **phantom** — never set at runtime, used for client-side type inference.
-- `auth` defaults to `true`. `ssr` defaults to `false`. `{ auth: true, ssr: true }` is dropped to `ssr: false` with a warning — SSR output 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. Unlisted params bypass the cache rather than poison it (e.g. `cacheQuery: ['q']` on a search page).
-- `ssrCacheTimeout?: number` — override the default 1-year edge TTL for pages whose content drifts between deploys.
-- Query-string params are declared in `Params` but never appear in the path template.
+`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime object carrying `PageMeta` plus a phantom `_params` used only for TypeScript inference. Options:
+
+- `auth` (default `true`) — protected route; router surfaces the framework's `<AuthRoot>` on the client and the server injects `window.__AUTH_TOKEN__` only for a verified cookie.
+- `ssr` (default `false`) — server-render the page for SEO. `{ auth: true, ssr: true }` is dropped to `ssr: false` with a warning: the SSR document is served from a shared edge cache and must not depend on the viewer.
+- `cacheQuery?: string[]` — query params that participate in the SSR edge-cache key. Anything NOT listed bypasses the cache instead of poisoning it (e.g. `cacheQuery: ['q']` on a search page).
+- `ssrCacheTimeout?: number` — edge cache lifetime in seconds. Default is 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.
+
+`definePages<T>(p)` is a pass-through identity function that widens no types — use it to give the registry a name.
 
 ---
 
@@ -268,20 +278,22 @@ bootstrapApp({
 |-------|-------------|
 | `requests` | Your `RequestRegistry` (merged with framework requests internally). |
 | `messages?` | Your `MessageRegistry` (merged with framework messages). |
-| `RouterProvider` | The `RouterProvider` returned from `createRouter()`. |
+| `RouterProvider` | The `RouterProvider` component returned from `createRouter()`. |
 | `render` | Callback returning the app's UI tree (typically `<RouterView />`). |
 | `root?` | Root element / 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>`. |
 | `keyboard?: false` | Disable the framework `<KeyboardProvider>` wrapper. |
-| `silentSso?` | Apex-domain apps (ugly.chat, ugly.press, …) that use ugly.bot as their auth authority but don't share its cookie. When true, a logged-out boot attempts a non-blocking top-level SSO redirect to adopt an existing ugly.bot session. Leave unset for `*.ugly.bot` subdomains and Mode B (self-auth) apps. |
+| `silentSso?` | Apex-domain apps (ugly.chat, ugly.press, …) 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, guarded) to adopt an existing ugly.bot session. Leave unset for `*.ugly.bot` subdomains and Mode B (self-auth) apps. |
+
+`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 the framework's `<AuthRoot>` (Mode A → `<LoginPopup>`; Mode B → magic-link form + optional Google button) 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 the framework's `<AuthRoot>` (Mode A → `<LoginPopup>`; Mode B → magic-link form + optional Google button) when a user opens a protected route. If the token is present, it connects the socket, mounts `<AppProvider>`, and renders.
+After render (both logged-in and logged-out), 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=…` on the URL (redirect-fallback OAuth code from ugly.bot) is redeemed at the very top of bootstrap before anything renders.
 
-After render (both logged-in and logged-out), a hidden iframe silently talks to `${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. `?ugly_oauth_code=…` on the URL (a 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 — that path is the fallback target when the server route is shadowed by a static-assets handler.
 
-If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it renders the `<MagicLinkCallback>` component instead of the regular app shell — that path is the fallback target when the server route is shadowed by a static-assets handler.
+The previous first-paint-blocking `<AutoLoginGate>` iframe was removed: logged-out landing pages now paint immediately.
 
 ### Routing — `createRouter()`
 
@@ -291,21 +303,31 @@ import { createRouter } from 'ugly-app/client';
 import { pages } from '../shared/pages';
 import { allPages } from './allPages';
 
-export const { RouterProvider, RouterView, useRouter } = createRouter({
-  pages,
-  allPages,
-});
+export const {
+  RouterProvider,
+  RouterView,
+  useRouter,
+  Link,
+  setAllPages,
+} = createRouter({ pages, allPages });
 ```
 
-Config: `pages` (required), `allPages?` (lazy route → element map; may be registered later via `setAllPages`), `ssrPages?` (a `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).
+**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.
 
-`createRouter` returns:
+**`createRouter` returns:**
 
-- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?`, `initialUrl?` (`{ pathname, search }`; required for SSR, used on the client during hydration so the first render matches the server's). Manages route state, browser history, and the popup layer. When `isAuthenticated()` returns false and the current route declares `auth: true`, the framework's `<AuthRoot>` renders in place of the page synchronously — apps cannot override this fallback. (Silent SSO happens in `bootstrapApp`, not in the router — the previous first-paint-blocking `<AutoLoginGate>` iframe was removed so logged-out landing pages paint immediately.)
-- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (replaces `ViewFlipper`), `renderPage?` (sync alternative to `allPages` loaders, called with `RouterStateRaw`).
-- **`useRouter()`** — returns the router context (see below).
+- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?`, `initialUrl?` (`{ pathname, search }`, required for SSR + hydration). Manages route state, browser history, and the popup layer. When `isAuthenticated()` returns false on a route with `auth: true`, the framework's `<AuthRoot>` renders synchronously in place of the page — apps cannot override this fallback (the framework owns the login UX so an app can't accidentally ship an auth-required route with no working login button).
+- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (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>`.
 - **`Link`** — typed SPA link bound to this router's pages. 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 the usual anchor attrs.
-- **`setAllPages(map)`** — register the lazy `PageMap<Pages>` after construction (typically from the browser entry). Lets the Worker bundle skip every lazy page's import graph while the client still gets code-split routes.
+- **`setAllPages(map)`** — register the lazy `PageMap<Pages>` after construction (typically from the browser entry). Keeps the Worker's import graph free of every lazy page while the client still gets code-split routes.
+
+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`.
 
 ### Page map — `lazyPage` / `lazyPageLoader`
 
@@ -325,6 +347,8 @@ export const allPages = {
 - **`lazyPage(factory)`** — lazy-imports a default-exported `React.ComponentType<Params>`. The page receives route params as props.
 - **`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.
+
 Example loader:
 
 ```typescript
@@ -340,7 +364,7 @@ export default async function PageLoader({ id }: { id: string }) {
 
 ```typescript
 const {
-  current,           // { routeName, params } for the active route (typed)
+  current,           // { routeName, params } — typed union over all pages
   transitionType,    // 'PUSH' | 'REPLACE' | 'POP' | 'NONE' — how we got here
   push,
   replace,
@@ -353,16 +377,13 @@ const {
 push('user/:userId', { userId: '123' });   // → /user/123
 replace('search', { q: 'hello' });         // → /search?q=hello
 back();                                     // browser history back
-
-current.routeName; // typed union of all route keys
-current.params;    // typed params for the current route
 ```
 
-All route names and params are fully typed against `pages`. Internally `push` / `replace` are no-ops when `buildUrl()` produces a URL that doesn't match a registered route (and emit a `console.error`).
+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()`
 
-Always use `useRouter().openPopup()` for modals, sheets, and menus. The router owns the popup layer, manages the spring animation, and stacks popups z-index-correctly.
+Use `useRouter().openPopup()` for modals, sheets, and menus. The router owns the popup layer, drives the spring animation, and stacks popups z-index-correctly.
 
 ```tsx
 const { openPopup } = useRouter();
@@ -380,12 +401,13 @@ const handle = openPopup(<MyContent />, {
 handle.hide(); // dismiss programmatically
 ```
 
-Modes:
+`openPopup` returns a `PopupHandle = { id, hide }`. Modes:
+
 - **`block`** (default) — 40% opacity backdrop, **does not** dismiss on backdrop click.
 - **`transient`** — 20% opacity backdrop, **dismisses** on backdrop click.
 - **`contextMenu`** — same as transient, intended for menus and pickers.
 
-`renderLayer` receives `{ content, spring, hide }` — `spring` is an `AnimatedValueRef` driving 0 → 1, `hide` closes the popup.
+`renderLayer` receives `{ content, spring, hide }`: `spring` is a `createAnimatedValue()` result driving 0 → 1, `hide` closes the popup.
 
 ### `AppProvider` & `useApp()`
 
@@ -393,34 +415,20 @@ Modes:
 
 ```typescript
 const {
-  userId,        // current user id
+  userId,        // current user id (string)
   user,          // UserBase doc
   socket,        // AppSocket — typed RPC client
-  uglyBotSocket, // optional UglyBotSocket for direct platform calls (STT/TTS, etc.)
+  uglyBotSocket, // UglyBotSocket | null — for direct platform calls (STT/TTS, etc.)
   showPopup,     // legacy popup API (prefer useRouter().openPopup)
   hidePopup,
   hideAllPopups,
-  runAsync,      // runAsync(label, async () => { ... }, options?) — shows loading overlay while pending
-  splashDone,    // mark a splash-screen step complete
-  localizer,     // (key, params?) => string — alias for useLocalizer
+  runAsync,      // (label, async () => {...}, options?) — shows loading overlay while pending
+  splashDone,    // (step: string) — mark a splash-screen step complete
+  localizer,     // (key, params?) => string — alias for useLocalizer()
 } = useApp();
 ```
 
-`useApp` is generic in `TAsyncOptions` so apps can pass an option type through to a custom `loadingOverlay` element. `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.
-
-### `Link` component
-
-Prefer the typed `Link` returned by `createRouter()` — no `router` prop, `to` / `params` are checked against your pages, and it uses the enclosing `<RouterProvider>` context automatically.
-
-```tsx
-// Typed Link — from your `client/router.ts`
-const { Link } = createRouter({ pages, allPages });
-<Link to="user/:userId" params={{ userId: '123' }}>View profile</Link>
-```
-
-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). `Link` intercepts plain left-clicks and lets `ctrl/cmd+click` open in a new tab as expected.
+`useApp<TAsyncOptions>()` is generic in the async-options type so apps can pass a custom option through to a custom `loadingOverlay` element (accepted as an `AppProvider` prop). `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.
 
 ### Direct socket access
 
@@ -431,8 +439,8 @@ Never use a bare `<a href="/route">` for internal navigation — it triggers a f
 | `request(name, input)` | Invoke a typed RPC handler. |
 | `getDoc(collection, id)` | Server-mediated doc fetch. |
 | `getDocs(collection, filter?, opts?)` | Filtered query. |
-| `trackDoc(collection, id, cb)` | Live subscription — returns unsubscribe. |
-| `trackDocs(collection, params, cb)` | Live filtered subscription. |
+| `trackDoc(collection, id, cb)` | Live subscription (with initial snapshot) — returns unsubscribe. |
+| `trackDocs(collection, params, cb)` | Live filtered subscription (with initial snapshot). |
 | `uploadFile(file, key)` | Presigned upload to the `temp` bucket. |
 | `connectionState` | `'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`. |
 | `disconnect()` | Close the connection. |
@@ -450,17 +458,17 @@ 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>` and the router's `<AutoLoginGate>`) 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)
 
 1. Every page request: the server checks the `auth_token` cookie. If it verifies through `${UGLY_BOT_URL}/verify`, the server injects `window.__AUTH_TOKEN__` into the HTML.
 2. Client boot: if `__AUTH_TOKEN__` is present, `bootstrapApp` opens the WebSocket with the token. Otherwise it renders logged-out immediately (no first-paint block).
-3. Background account-sync (always): `bootstrapApp` opens a hidden iframe to `${UGLY_BOT_URL}/oauth/silent` on every load. If it returns a one-time code, the client POSTs `/auth/verify` to refresh the cookie. If the refreshed account's `userId` differs from the current session, the client calls `/auth/logout` and reloads onto the live account (guarded once per from→to pair to prevent loops).
-4. Apex apps (`silentSso: true` in `bootstrapApp`): if the hidden iframe can't read ugly.bot's cookie (Safari / 3p-cookie blocking), a **top-level** redirect to `/oauth/silent` (first-party, bypasses 3p blocking) runs instead — one-shot, marked done so it can't loop. Skipped for accounts already confirmed live.
+3. Background account-sync (always): `bootstrapApp` opens a hidden iframe to `${UGLY_BOT_URL}/oauth/silent` on every load. If it returns a one-time code, the client POSTs `/auth/verify` to refresh the cookie. If the refreshed account's `userId` differs from the current session, the client calls `/auth/logout` and reloads onto the live account (guarded once per from→to pair).
+4. Apex apps (`silentSso: true`): if the hidden iframe can't read ugly.bot's cookie (Safari / 3p-cookie blocking), a **top-level** redirect to `/oauth/silent` (first-party, bypasses 3p blocking) runs instead — one-shot, marked done in `localStorage` so it can't loop. Skipped for accounts already confirmed live.
 5. Manual login: on protected routes, the per-route auth guard surfaces `<AuthRoot>` → `<LoginPopup>`, which opens `${UGLY_BOT_URL}/oauth` in a popup. On completion, the platform redirects back with either a `postMessage` code or `?ugly_oauth_code=…`; `bootstrapApp` redeems either at the top of boot.
 
-### Mode B — Self-issued sessions
+### 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.
 
@@ -498,7 +506,7 @@ configurator.setAuth({
 });
 ```
 
-### Server-side helpers (`ugly-app`)
+### Server-side helpers
 
 - `verifyToken(token)` — verifies a token against ugly.bot and returns the `userId`.
 - `getRequestUser(req)` — synchronous decode of the per-project `UGLY_PROJECT_TOKEN` cookie set by ugly.bot's wake-on-traffic gate. Returns `{ userId } | null` without a network round-trip; safe to use as the primary auth check in deployed-app handlers.
@@ -507,7 +515,7 @@ configurator.setAuth({
 
 ## Database — `TypedDB`
 
-Access via `app.db` or via `import { app } from './your-app-module'`. All methods accept a `CollectionDef` (from `defineCollections`) or a plain collection name string.
+Access via `app.db`. All methods accept a `CollectionDef` (from `defineCollections()`) or a plain collection name string.
 
 ### Writing
 
@@ -523,7 +531,7 @@ await db.setDocOp(collections.note, id, { $inc: { views: 1 } });         // Mong
 await db.setDocOpOrIgnore(collections.note, id, { $inc: { views: 1 } });
 ```
 
-Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`, `$set`. All keys are dot-notation, fully typed against the collection's schema.
+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
 
@@ -532,8 +540,8 @@ const doc  = await db.getDoc(collections.note, id);
 const docs = await db.getDocs(collections.note, { userId }, { sort: { created: -1 }, limit: 20 });
 
 // Typed SQL-native query API (preferred for new code)
-const notes = await db.find(collections.note, { userId, done: { $ne: true } }, { sort: { created: -1 }, limit: 20 });
-const count = await db.findCount(collections.note, { userId });
+const notes  = await db.find(collections.note, { userId, done: { $ne: true } }, { sort: { created: -1 }, limit: 20 });
+const count  = await db.findCount(collections.note, { userId });
 const sample = await db.findRandom(collections.note, { userId }, 5);
 
 // Aggregation pipelines (legacy / advanced)
@@ -578,9 +586,10 @@ const k = db.cacheKey('prefix', id);
 
 ```typescript
 import { createUserHelper, dbDefaults } from 'ugly-app';
+import { nanoid } from 'nanoid';
 
-const newDoc = { _id: crypto.randomUUID(), ...dbDefaults(), title: 'Hi' };
-//                                          ^^^^^^^^^^^^^^^ { version: 1, created, updated }
+const newDoc = { _id: nanoid(), ...dbDefaults(), title: 'Hi' };
+//                              ^^^^^^^^^^^^^^^ { version: 1, created, updated }
 
 const userHelper = createUserHelper<User>(collections.user);
 const user = await userHelper.get(db, userId);
@@ -600,7 +609,7 @@ Imports available from `ugly-app`:
 
 ## AI
 
-AI calls are proxied through ugly.bot — your app never holds an AI 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
 
@@ -704,6 +713,8 @@ Client-side, use `socket.uploadFile(file, key)` — it requests a presigned URL
 
 `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).
+
 ---
 
 ## Workers & cron
@@ -736,6 +747,8 @@ 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.
 
+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).
+
 ---
 
 ## Localization
@@ -805,17 +818,34 @@ Bucketing is deterministic: `hash(experimentId + userId)` (or `sessionId` for un
 | `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/conversation/{shared,server,client}` | AI chat sessions with persisted history. |
+| `ugly-app/server/adapter/workers` | Cloudflare Workers entry (Hono router + Durable Objects + Neon HTTP driver + R2). |
+| `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` | Test utilities. |
+| `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/`:
+
+- **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.
+
+---
+
 ## Environment variables
 
 | Variable | Description |
@@ -831,13 +861,15 @@ Bucketing is deterministic: `hash(experimentId + userId)` (or `sessionId` for un
 | `NATS_PREFIX` / `COMPOSE_PROJECT_NAME` | NATS subject prefix for per-env isolation. |
 | `CLOCK_ENABLED` | `true` to enable `setOnMinuteTick` / `setOnHourlyTick`. |
 | `CRON_SECRET` | Bearer secret for `POST /api/_cron/:taskName` and prod `POST /_workers/run`. |
-| `MAINTAIN_BOT_USER_ID` | User id allowed to access admin-only handlers. |
+| `MAINTAIN_BOT_USER_ID` | User id allowed to access admin-only handlers when `setIsAdmin()` is unset. |
 | `INTERNAL_EMAIL_SECRET` | Shared secret for `/internal/email-callback`. |
 | `JWT_SECRET` | Required when using `getRequestUser()` for the per-project session cookie. |
 | `APP_DOMAIN` | App domain; combined with `NATS_PREFIX` for `getRequestUser()` validation. |
 | `LOG_CAPTURE_URL` | Studio override for client log capture (empty → ugly.bot default). |
 | `UGLY_APP_HMR` | Set to `false` to disable Vite HMR in dev. |
 | `SCHEMA_CHECK_SKIP` | `true` to start despite schema drift (unsafe). |
+| `NEON_PROXY_URL` | Set by `dev:workers` — Neon-wire endpoint the local Neon HTTP driver dials. |
+| `CLOUDFLARE_WORKERS` | Set to `1` inside the Workers adapter for runtime detection. |
 
 Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta.env.VITE_*`.
 
@@ -864,7 +896,7 @@ Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta
 | `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` for the full list.
+Inside a scaffolded project, the same commands are available via `npm run …` scripts — see `templates/CLAUDE.md`.
 
 ---
 
@@ -883,4 +915,4 @@ The framework refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=tr
 
 ## Tech stack
 
-Node.js · TypeScript · Express · React 19 · Vite · PostgreSQL (JSONB) · Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · ugly.bot platform
+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

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.873";
+export declare const CLI_VERSION = "0.1.875";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.873";
+export const CLI_VERSION = "0.1.875";
 //# sourceMappingURL=version.js.map

package/dist/client/components/DeviceSimulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeviceSimulator.d.ts","sourceRoot":"","sources":["../../../src/client/components/DeviceSimulator.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAwDhF,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,KAAK,CAAC,SAAS,CA0KlB"}
+{"version":3,"file":"DeviceSimulator.d.ts","sourceRoot":"","sources":["../../../src/client/components/DeviceSimulator.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AA6ChF,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,KAAK,CAAC,SAAS,CA0KlB"}

package/dist/client/components/DeviceSimulator.js

@@ -1,17 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
-const SIMULATOR_PROFILES = {
-    ios: {
-        safeArea: { top: 59, right: 0, bottom: 34, left: 0 },
-        keyboardHeight: 320,
-        viewport: { width: 390, height: 844 },
-    },
-    android: {
-        safeArea: { top: 25, right: 0, bottom: 48, left: 0 },
-        keyboardHeight: 300,
-        viewport: { width: 360, height: 780 },
-    },
-};
+import { SIMULATOR_PROFILES, } from '../deviceProfiles.js';
 function isKeyboardInput(el) {
     if (!el)
         return false;