ugly-app 0.1.869 → 0.1.871

package/README.md

@@ -2,18 +2,18 @@
 
 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.
 
-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 handles auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of it 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`
+- **Auth**: HttpOnly cookies + JWT, ugly.bot OAuth out of the box, magic-link + Google when self-hosting sessions
 - **AI**: Text, 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`)
+- **Realtime**: NATS pub/sub and live document 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
+- **Workers & cron**: `setWorkers()` registers named async tasks with optional Zod schemas and cron schedules
 - **Localization**: Strings tables with critical-string SSR injection
 - **Experiments**: Deterministic A/B bucketing tied to event logging
 - **CLI**: `ugly-app` commands for dev, build, deploy, migrations, logs, AI, and auth
@@ -26,7 +26,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 ~20 other test pages.
 
 ---
 
@@ -43,6 +43,7 @@ import {
   type RequestHandlers,
 } from 'ugly-app';
 import { dbDefaults } from 'ugly-app/shared';
+import { nanoid } from 'nanoid';
 import { requests, messages } from '../shared/api';
 import { collections } from '../shared/collections';
 import { pages } from '../shared/pages';
@@ -51,7 +52,7 @@ const app = createApp(
   { requests, messages },
   {
     createTodo: async (userId, { text }) => {
-      const _id = crypto.randomUUID();
+      const _id = nanoid();
       await app.db.setDoc(collections.todo, { _id, userId, text, done: false, ...dbDefaults() });
       return { id: _id };
     },
@@ -69,24 +70,24 @@ await app.start(parseInt(process.env['PORT'] ?? '4321'));
 
 ```typescript
 function createApp<R extends AppRegistryBase, Defs extends CollectionDefRegistry>(
-  registry: R,                                       // { requests, messages }
+  registry: R,                                       // { requests, messages, pages? }
   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:
+The returned `App`:
 - `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.
+- `registerRoutes(fn)` — mount additional Express routes after creation
+- `pushSend({ userId, page, query, ...notification })` — send a push notification whose click-through target is a route in this app's `pages` table. `page` is type-checked against route keys (when `pages` is on the createApp registry), `query` against that route's params.
 
-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: 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.
 
 ### `AppConfigurator`
 
@@ -94,23 +95,23 @@ Passed to the optional fourth argument of `createApp`. Every method is optional.
 
 | 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)`. |
+| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. In dev runs Vite in middleware mode; in prod serves `dist/client`. Provide `renderPage` to SSR routes with `ssr: true`. |
+| `setUserHelper(helper)` | Customize how the framework reads/writes the `user` collection during WebSocket auth. |
+| `setOnUserCreate(handler)` | Called on first login with `(userId, { email?, phone? }, db)`. |
+| `setAuth(provider)` | Replace the default auth provider (must implement `verify(code)` and `authUrl(origin)`). |
 | `setOnSocketMessage(handler)` | Single raw-WebSocket message handler. 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. |
 | `setOnAfterStart(handler)` | `(db) => Promise<void>` — called once after data-proxy + NATS are ready. |
-| `setOnMinuteTick(fn)` / `setOnHourlyTick(fn)` | Framework-managed periodic callbacks. Only fire when `CLOCK_ENABLED=true`. |
+| `setOnMinuteTick(fn)` / `setOnHourlyTick(fn)` | Periodic callbacks. Only fire when `CLOCK_ENABLED=true`. |
 | `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). |
+| `setIsAdmin(fn)` | `(userId, db) => boolean \| Promise<boolean>` — gate for admin-only framework requests. Defaults to matching `MAINTAIN_BOT_USER_ID`. |
+| `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot`. |
 | `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. |
-| `setStrings(config)` | Localization config — framework injects language + critical strings into SSR HTML and exposes `resolveLanguage` / `getCriticalStrings`. |
+| `setStrings(config)` | Localization config — framework injects language + critical strings into SSR HTML. |
 | `registerRoutes(fn)` | Mount custom Express routes. |
 | `setWorkerQueue(queue)` | Register a `WorkerQueue` with `start()` / `stop()` for app lifecycle management. |
 
@@ -130,7 +131,7 @@ Inside a handler, access state via captured imports — `app.db`, `storage`, `pg
 
 ### 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, reachable from any client via the normal RPC pipeline:
 
 | Name | Purpose |
 |------|---------|
@@ -140,10 +141,10 @@ Inside a handler, access state via captured imports — `app.db`, `storage`, `pg
 | `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` | Same-origin, public endpoints used by the built-in browser telemetry (feedback + client-side error capture) to write into the project's own Postgres. |
+| `shareLink` | Mint a `https://ugly.bot/l/<code>` short link with OpenGraph metadata. |
+| `feedbackReportCreateNoAuth` / `errorLogCaptureNoAuth` | Same-origin, public endpoints used by the built-in browser telemetry. |
 | `submitFeedbackBot` | Forwards `db.captureFeedback` writes for the maintain-bot persona. |
-| `feedbackReportResolve` | Admin-only — resolve or decline a feedback report (Workers-only via D1 telemetry). |
+| `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`). |
 
 App-provided handlers with the same name override the framework's defaults.
@@ -160,7 +161,7 @@ App-provided handlers with the same name override the framework's defaults.
 import { authReq, defineRequests, req, z } from 'ugly-app/shared';
 
 export const requests = defineRequests({
-  // Public — handler signature: (userId: string | null, input) => Promise<output>
+  // Public — handler: (userId: string | null, input) => Promise<output>
   getPublicData: req({
     input: z.object({ id: z.string() }),
     output: z.object({ data: z.string() }),
@@ -172,7 +173,7 @@ export const requests = defineRequests({
     output: z.object({ userId: z.string(), email: z.string().optional() }),
   }),
 
-  // With per-endpoint rate limiting (enforced before handler runs)
+  // Per-endpoint rate limiting (enforced before handler runs)
   submitFeedback: authReq({
     input: z.object({ type: z.enum(['bug', 'design', 'feature']), message: z.string() }),
     output: z.object({ id: z.string() }),
@@ -213,9 +214,9 @@ 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, and `nanoid()` for `_id` — never `crypto.randomUUID()`, `Date.now()`, or a counter.
 
-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).
+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).
 
 ### Pages (`shared/pages.ts`)
 
@@ -232,8 +233,10 @@ 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`.
+- The generic on `definePage<Params>()` is **phantom** — never set at runtime, used purely 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.
 
 ---
@@ -267,12 +270,12 @@ bootstrapApp({
 | `messages?` | Your `MessageRegistry` (merged with framework messages). |
 | `RouterProvider` | The `RouterProvider` 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"). |
+| `root?` | Root element / CSS selector (default `'#root'`). |
+| `fallback?` | UI for unmatched routes (default: a tiny 404). |
 | `socketUrl?` | Override the WebSocket path (default `/rpc`). |
-| `strings?` | Localization config — when present, wraps the tree with `<StringsProvider>`. |
+| `strings?` | Localization config — wraps the tree with `<StringsProvider>` when present. |
 | `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 non-blocking top-level SSO redirect to adopt an existing ugly.bot session. Leave unset for `*.ugly.bot` subdomains and Mode B 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) when a user opens a protected route. If the token is present, it connects the socket, mounts `<AppProvider>`, and renders.
 
@@ -288,18 +291,36 @@ import { createRouter } from 'ugly-app/client';
 import { pages } from '../shared/pages';
 import { allPages } from './allPages';
 
-export const { RouterProvider, RouterView, useRouter } = createRouter({
+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).
+
 `createRouter` returns:
 
-- **`RouterProvider`** — props: `children`, `fallback?`, `isAuthenticated?`. 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 now happens in `bootstrapApp`, not in the router — the previous first-paint-blocking `<AutoLoginGate>` iframe was removed so logged-out landing pages paint immediately.)
+- **`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 synchronously in place of the page — apps cannot override this fallback.
 - **`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).
 - **`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.
+
+### `definePage` — page metadata
+
+Re-exported from `ugly-app/shared`. Runtime shape:
+
+```typescript
+interface PageMeta {
+  auth: boolean;                // default: true
+  ssr: boolean;                 // default: false
+  cacheQuery?: string[];        // edge-cache key participants
+  ssrCacheTimeout?: number;     // seconds; default 31_536_000 (1yr)
+}
+```
+
+The `<Params>` generic on `definePage<Params>()` is a phantom type — used only by TypeScript for route-param inference in `useRouter()`, `Link`, and `pushSend`.
 
 ### Page map — `lazyPage` / `lazyPageLoader`
 
@@ -319,6 +340,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 wrap the `import()` in a one-shot reload guard: on a stale-deploy chunk 404 the framework reloads the page once (guarded by sessionStorage) so cached `index.html` picks up the new chunk hashes instead of wedging the SPA.
+
 Example loader:
 
 ```typescript
@@ -352,11 +375,11 @@ 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`).
+All route names and params are fully typed against `pages`. Internally `push` / `replace` log a `console.error` (no-op) 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.
+Always 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();
@@ -368,7 +391,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
@@ -383,7 +406,7 @@ Modes:
 
 ### `AppProvider` & `useApp()`
 
-`bootstrapApp` mounts `<AppProvider>` automatically after socket connect. Use `useApp()` inside any page to access the active user and socket.
+`bootstrapApp` mounts `<AppProvider>` automatically after the socket connects. Use `useApp()` inside any page to reach the active user and socket:
 
 ```typescript
 const {
@@ -394,21 +417,20 @@ const {
   showPopup,     // legacy popup API (prefer useRouter().openPopup)
   hidePopup,
   hideAllPopups,
-  runAsync,      // runAsync(label, async () => { ... }, options?) — shows loading overlay while pending
+  runAsync,      // runAsync(label, async () => {...}, options?) — shows loading overlay while pending
   splashDone,    // mark a splash-screen step complete
-  localizer,     // (key, params?) => string — alias for useLocalizer
+  localizer,     // (key, params?) => string
 } = 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.
+`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()` 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.
+Prefer the typed `Link` returned by `createRouter()` — no `router` prop, `to` / `params` checked against your pages, 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>
 ```
 
@@ -425,7 +447,7 @@ 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. |
+| `trackDoc(collection, id, cb)` | Live subscription — returns unsubscribe. Sends an initial snapshot then relays mutations. |
 | `trackDocs(collection, params, cb)` | Live filtered subscription. |
 | `uploadFile(file, key)` | Presigned upload to the `temp` bucket. |
 | `connectionState` | `'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`. |
@@ -444,22 +466,22 @@ 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 (`<AuthRoot>`, magic-link form, silent-SSO iframe) 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.
-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.
+3. Background account-sync (always): `bootstrapApp` opens a hidden iframe to `${UGLY_BOT_URL}/oauth/silent`. 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`): if the hidden iframe can't read ugly.bot's cookie (Safari / third-party-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.
+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=…`.
 
 ### 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.
 
 - `<AuthRoot>` renders `<MagicLinkForm>` (plus the Google button when configured) instead of `<LoginPopup>`.
-- Background ugly.bot silent SSO is a no-op — the ugly.bot iframe would either silently fail or set a cookie that won't verify against the local session.
+- Background ugly.bot silent SSO is a no-op — the ugly.bot iframe would either silently fail or set a cookie that wouldn't verify against the local session.
 - `POST /auth/magic-link/request` accepts an email, mints a one-time token (default 15 min lifetime, configurable via `auth.magicLinkExpiresMin`), and emails a link.
 - `GET /auth/magic-link/verify?token=…` validates the token, calls `onUserCreate` on first login, sets the session cookie, and redirects.
 - Google login lives at `GET /auth/google/url` + `POST /auth/google/callback` when enabled.
@@ -501,7 +523,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
 
@@ -572,9 +594,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);
@@ -594,7 +617,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 an AI provider key. Set `UGLY_BOT_TOKEN` in the environment and the framework handles routing, balance tracking, retries, and per-user billing.
 
 ### Server-side text generation
 
@@ -772,6 +795,28 @@ Bucketing is deterministic: `hash(experimentId + userId)` (or `sessionId` for un
 
 ---
 
+## Sharing links
+
+Never hand-build outbound URLs. Mint through the central helper — the returned `https://ugly.bot/l/<code>` short link deep-links into native + dock apps, renders an OpenGraph card, and can optionally gate humans behind login:
+
+```typescript
+import { shareLink } from 'ugly-app';   // server
+const url = await shareLink({
+  target: `/article/${id}`,
+  og: { title, description, image },
+  requireAuth: false,
+});
+```
+
+```typescript
+import { shareLink } from 'ugly-app/client';   // client
+const url = await shareLink({ target: location.pathname, og: { title } });
+```
+
+Do **not** route unsubscribe or other single-use, token-bearing URLs through `shareLink()` — those must remain direct app URLs.
+
+---
+
 ## Built-in endpoints
 
 | Endpoint | Description |
@@ -798,14 +843,14 @@ 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/client` | React: `bootstrapApp`, `createRouter`, `lazyPage`, `lazyPageLoader`, `AppProvider`, components, animations, audio, AI helpers. |
 | `ugly-app/conversation/{shared,server,client}` | 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/webrtc`, `ugly-app/webrtc/server` | WebRTC video rooms. |
 | `ugly-app/three/{server,client}` | Three.js scene helpers. |
 | `ugly-app/worker` | Worker queue runtime. |
-| `ugly-app/playwright` | Test utilities. |
+| `ugly-app/playwright` | Test utilities (`inspectWindow`, `expectClean`, `simulateKeyboard`, `waitForApp`). |
 | `ugly-app/vite`, `ugly-app/eslint` | Build-tool plugins. |
 
 ---
@@ -825,7 +870,7 @@ 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 (fallback when `setIsAdmin` 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. |
@@ -856,9 +901,9 @@ Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta
 | `ugly-app error:dev` / `error:prod` | Query error logs (your tunnel / production). |
 | `ugly-app perf:dev` / `perf:prod` | Query performance metrics. |
 | `ugly-app feedback:dev` / `feedback:prod` | Query user feedback. |
-| `ugly-app feedback:submit` / `feedback:resolve` | Manage feedback (run with `--help` for flags). |
+| `ugly-app feedback:submit` / `feedback:resolve` | Manage feedback (`--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.
 
 ---
 

package/dist/agent/client/runAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runAgent.d.ts","sourceRoot":"","sources":["../../../src/agent/client/runAgent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runAgent.d.ts","sourceRoot":"","sources":["../../../src/agent/client/runAgent.ts"],"names":[],"mappings":"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"}

package/dist/agent/client/runAgent.js

@@ -44,8 +44,9 @@ export function runAgent(config) {
     try {
         unsub = config.socket.trackDocs(AGENT_STREAM_COLLECTION, { keys: { [AGENT_STREAM_KEY_FIELD]: streamId } }, () => { }, (raw) => {
             const env = raw;
-            const frame = env.frame ?? env;
-            if (!frame || typeof (frame).type !== 'string')
+            const frame = env.frame ??
+                env;
+            if (!frame || typeof frame.type !== 'string')
                 return;
             config.onFrame?.(frame);
             if (frame.type === 'msg:delta')
@@ -118,7 +119,10 @@ export function runAgent(config) {
                     }, { signal: aborter.signal }));
                     return resp;
                 }
-                const resp = (await config.socket.request(requestName, turnInput, { timeoutMs: null, signal: aborter.signal }));
+                const resp = (await config.socket.request(requestName, turnInput, {
+                    timeoutMs: null,
+                    signal: aborter.signal,
+                }));
                 return resp;
             }
             catch (err) {
@@ -129,7 +133,9 @@ export function runAgent(config) {
                     await sleep(300 * 2 ** (attempt - 1));
             }
         }
-        throw lastErr instanceof Error ? lastErr : new Error('agent turn request failed');
+        throw lastErr instanceof Error
+            ? lastErr
+            : new Error('agent turn request failed');
     }
     async function runTool(use) {
         try {
@@ -186,10 +192,16 @@ export function runAgent(config) {
             const prior = Array.isArray(last.content)
                 ? last.content
                 : [{ type: 'text', text: String(last.content) }];
-            messages = [...messages.slice(0, -1), { role: 'user', content: [...prior, { type: 'text', text }] }];
+            messages = [
+                ...messages.slice(0, -1),
+                { role: 'user', content: [...prior, { type: 'text', text }] },
+            ];
         }
         else {
-            messages = [...messages, { role: 'user', content: [{ type: 'text', text }] }];
+            messages = [
+                ...messages,
+                { role: 'user', content: [{ type: 'text', text }] },
+            ];
         }
         config.onEvent?.({ type: 'steer', text });
         return true;
@@ -217,7 +229,9 @@ export function runAgent(config) {
                         const cont = await config.onSettle();
                         if (cont && !aborter.signal.aborted) {
                             verifyGrace += VERIFY_GRACE_STEP;
-                            const content = typeof cont === 'string' ? [{ type: 'text', text: cont }] : cont;
+                            const content = typeof cont === 'string'
+                                ? [{ type: 'text', text: cont }]
+                                : cont;
                             messages = [...messages, { role: 'user', content }];
                             await persist('running');
                             continue;
@@ -244,9 +258,16 @@ export function runAgent(config) {
                 // the model reacts to it THIS turn instead of after the whole turn ends.
                 drainSteers();
                 const msgId = mintId();
-                config.onEvent?.({ type: 'turn_start', msgId, turnIndex: totals.turns });
+                config.onEvent?.({
+                    type: 'turn_start',
+                    msgId,
+                    turnIndex: totals.turns,
+                });
                 const resp = await requestTurn(msgId);
-                const assistantTurn = { role: 'assistant', content: resp.content };
+                const assistantTurn = {
+                    role: 'assistant',
+                    content: resp.content,
+                };
                 messages = [...messages, assistantTurn];
                 if (resp.telemetry) {
                     totals = accrueTelemetry(totals, {
@@ -271,7 +292,10 @@ export function runAgent(config) {
                 });
                 await persist(resp.stopReason === 'tool_use' ? 'running' : 'idle');
                 if (resp.stopReason === 'error') {
-                    config.onEvent?.({ type: 'error', message: resp.error ?? 'agent turn error' });
+                    config.onEvent?.({
+                        type: 'error',
+                        message: resp.error ?? 'agent turn error',
+                    });
                     return;
                 }
                 if (resp.stopReason !== 'tool_use') {
@@ -287,7 +311,9 @@ export function runAgent(config) {
                     if (config.onSettle && !aborter.signal.aborted) {
                         const cont = await config.onSettle();
                         if (cont && !aborter.signal.aborted) {
-                            const content = typeof cont === 'string' ? [{ type: 'text', text: cont }] : cont;
+                            const content = typeof cont === 'string'
+                                ? [{ type: 'text', text: cont }]
+                                : cont;
                             messages = [...messages, { role: 'user', content }];
                             await persist('running');
                             continue;
@@ -310,7 +336,10 @@ export function runAgent(config) {
                 await persist('idle');
                 return;
             }
-            config.onEvent?.({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            config.onEvent?.({
+                type: 'error',
+                message: err instanceof Error ? err.message : String(err),
+            });
             await persist('error');
         }
         finally {