@terreno/mcp 57.3.0 → 57.4.0

package/dist/docs/versioned/next/reference/syncdb.md

@@ -23,7 +23,7 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 ## Key exports
 
 - `createSyncDb`, `SyncDb`, `SyncDbConfig`, `MutateArgs`
-- `betterAuthAdapter`, `AuthProvider`
+- `betterAuthAdapter`, `bridgeBetterAuthReactClient`, `AuthProvider`
 - `listConflicts`, `wipeLocalData`, `generateMutationId`
 - React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
 - CLI: `terreno-syncdb-codegen` (generates `SYNC_COLLECTIONS` + friendly hooks from OpenAPI)
@@ -108,6 +108,7 @@ const todoRouter = modelRouter("/todos", Todo, {
   queryFilter: OwnerQueryFilter,
   sync: {
     scope: {type: "owner"}, // stream = todos|owner:{ownerId}
+    // adminBroadcast: true, // also emit sync:delta to todos|admin (default false)
   },
 });
 ```
@@ -126,7 +127,7 @@ new TerrenoApp({userModel: User})
 
 - **`SyncApp`** — HTTP sync routes (`/sync/snapshot`, `/sync/mutate`, `/sync/mutate/batch`, `/sync/key`, `/sync/streams`, `/sync/entities`).
 - **`RealtimeApp`** — Socket.io server with change-stream-driven `sync:delta` emission. Requires a **MongoDB replica set** (change streams). `modelRouter` `realtime` (RTK `sync` events) is deprecated and removed in Terreno 58; do not add it to new models.
-- **`ensureSyncIndexes`** — `TerrenoApp.start()` awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
+- **`ensureSyncIndexes`** — `TerrenoApp.start()` binds the HTTP port first (or attaches to `httpServer` if the process already listened), then awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
 
 Socket auth requires at least one configured authentication method. It enables legacy JWT
 validation when `tokenSecret` or `TOKEN_SECRET` is available. Better Auth can be used without
@@ -142,20 +143,29 @@ is the fallback.
 ## createSyncDb configuration
 
 ```typescript
-import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthAdapter, bridgeBetterAuthReactClient, createSyncDb} from "@terreno/syncdb";
 
 export const syncDb = createSyncDb({
   name: "myapp",
   collections: ["todos"],
-  authProvider: betterAuthAdapter(authClient),
+  authProvider: betterAuthAdapter(bridgeBetterAuthReactClient(authClient)),
   baseUrl: "http://localhost:4000",
 });
 ```
 
+Wrap a Better Auth **react** client in `bridgeBetterAuthReactClient`. Its `useSession` is a React
+hook rather than the `.subscribe` surface the adapter watches, so without the bridge the adapter
+falls back to polling `getSession()` and produces constant `/api/auth/get-session` traffic. The
+bridge exposes the client's `$store.atoms.session` atom and degrades to the polling fallback when
+that atom is absent. Clients that already expose `getSession` plus a subscribable `useSession` can
+be passed to `betterAuthAdapter` directly.
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `name` | `string` | — (required) | Persisted database name |
 | `collections` | `string[]` | — (required) | Collection names to sync (local tables + subscriptions) |
+| `windowCollections` | `string[]` | `[]` | Collections that join `{collection}\|admin`, skip snapshots/reconcile, and hydrate only known REST membership ids |
+| `organizationIdProvider` | `() => string \| undefined` | — | Read at send time: sets `X-Organization-Id` on HTTP sync calls and `organizationId` on socket mutate payloads |
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
 | `transport` | `SyncTransport` | socket transport from `baseUrl` | Override for tests or custom wiring |
@@ -189,6 +199,7 @@ export const syncDb = createSyncDb({
 | `goOnline()` | End simulated outage; reconnect triggers reconcile + outbox replay. |
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
 | `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
+| `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
 | `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
@@ -340,7 +351,7 @@ In React, prefer `useConflicts()`.
 | Strategy | Behavior |
 |----------|----------|
 | `"useServer"` | Overwrite local entity with canonical server data/seq; clear pending state; discard conflicted outbox row. Writes a **tombstone** when the server side is deleted. |
-| `"keepMine"` | Re-enqueue the mutation under a **fresh** `mutationId` with `baseVersion` set to the server's seq; local optimistic data is kept. |
+| `"keepMine"` | Re-enqueue the mutation under a **fresh** `mutationId` with `baseVersion` set to the server's seq; local optimistic data is kept. All durable mutation metadata, including `mutationMode: "adminWindow"`, is preserved so retried admin-window writes receive the same RBAC, protected-field, hook, and audit handling. |
 
 Resolve via `client.resolveConflict({mutationId, strategy})` or `useConflicts().resolve(...)`.
 
@@ -382,6 +393,7 @@ sync: {scope: {type: "owner"}}                        // todos|owner:{ownerId}
 sync: {scope: {type: "owner", field: "userId"}}       // todos|owner:{userId}
 sync: {scope: {type: "tenant", field: "organizationId"}} // todos|tenant:{orgId}
 sync: {scope: {type: "broadcast"}}                    // todos|all
+sync: {scope: {type: "owner"}, adminBroadcast: true}  // owner stream + todos|admin
 sync: {
   scope: (doc) => String(doc.workspaceId),
   snapshotFilter: (user) => ({workspaceId: {$in: [...]}}), // required for custom
@@ -390,6 +402,16 @@ sync: {
 
 - **Owner** streams use the authenticated socket's user id (client cannot pick another user's stream).
 - **Tenant/custom** scopes resolve memberships via `SyncApp` `getUserScopes`.
+- **`adminBroadcast`** (default `false`) is an additive fan-in flag on the existing collection `sync` config. When `true`, `sync:delta` emitters also publish to `{collection}|admin`. Do not change the app collection `scope` to broadcast for admin; app clients keep owner/tenant streams. Join `{collection}|admin` with `sync:subscribe {mode: "window"}`. The gate matches the admin UI shell: with `SyncApp({accessControl})`, the caller needs `admin:access`; without RBAC, `user.admin` / `Permissions.IsAdmin` is enough. When `AdminApp` is mounted it also registers that model's list/read permissions and `queryFilter`, so window subscribe, `GET /sync/entities`, and `|admin` live deltas cannot return rows `/admin` REST would hide (product `IsOwner` still treats `user.admin` as owner). Others get `sync:error`. The server confirms `sync:subscribed {mode: "window"}` and does not dump snapshot pages. Clients listed in `createSyncDb({windowCollections})` skip `GET /sync/snapshot` for those collections (startup, subscribe catch-up, and the reconcile timer). Hydrate known ids with `hydrateWindow` (REST rows + `GET /sync/entities`). For that HTTP lookup, an allowed admin-window caller on an `adminBroadcast` collection is not limited to owner/tenant stream membership. Deltas on `{collection}|admin` update or tombstone **ids already in the local window only**; unknown ids are ignored until Refresh or load-more hydrates them (Refresh = current REST query + `hydrateWindow`).
+- `AdminApp({organizations: true})` forces `adminBroadcast: false` for models
+  with `organizationId`. The current admin-window socket protocol has no
+  selected-organization field, so those models use REST with
+  `X-Organization-Id` instead of weakening `OrgQueryFilter` or streaming
+  cross-organization rows.
+- Use a dedicated `createSyncDb` client/store for an admin window when the same app
+  also subscribes to that collection through an owner or tenant stream. One socket
+  subscription has one mode per collection, and a separate store prevents
+  admin-hydrated rows from appearing in the product UI.
 - **`snapshotFilter`** restricts `GET /sync/snapshot` server-side. Auto-derived for owner/tenant; required for custom resolver scopes.
 
 ## Sync protocol
@@ -400,9 +422,9 @@ sync: {
 |----------|---------|
 | `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up per stream |
 | `GET /sync/streams` | Current stream membership for the user |
-| `GET /sync/entities` | Point lookup for entity repair |
-| `POST /sync/mutate` | Single mutation (HTTP fallback) |
-| `POST /sync/mutate/batch` | Batched mutations (max 100, strict order, stop at first non-ack) |
+| `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted |
+| `POST /sync/mutate` | Single mutation (HTTP fallback). Optional `mutationMode: "adminWindow"` validates `adminBroadcast`, admin-window access, and a registered AdminApp write scope, then runs the shared sync executor with **AdminApp** pre/post hooks (not product `modelRouter` hooks), plus the same permission (including org membership), stripping, and audit semantics as `/admin` REST. HTTP mutate binds `X-Organization-Id` into org context |
+| `POST /sync/mutate/batch` | Batched mutations (max 100, strict order, stop at first non-ack). Each mutation may carry `mutationMode: "adminWindow"` under the same AdminApp executor hook path as single mutate |
 | `GET /sync/key` | Per-user encryption key material (web) |
 
 Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
@@ -411,11 +433,11 @@ Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
 
 | Event | Direction | Payload |
 |-------|-----------|---------|
-| `sync:subscribe` / `sync:unsubscribe` | client → server | `{collections: string[]}` |
-| `sync:subscribed` | server → client | `{collection, streams}` — sent after the stream rooms are joined; the client pages each confirmed stream from its cursor so a write landing between the startup snapshot and the join is not missed |
+| `sync:subscribe` / `sync:unsubscribe` | client → server | `{collections: string[], mode?: "window"}` |
+| `sync:subscribed` | server → client | `{collection, streams, mode?: "window"}` — sent after the stream rooms are joined; full-mode clients page each confirmed stream from its cursor. `mode: "window"` joins `{collection}\|admin` only and must not trigger snapshot paging |
 | `sync:error` | server → client | `{collection, message}` |
 | `sync:delta` | server → client | `{collection, id, method, data?, seq, stream, deleted?, frontierSeq?}` |
-| `sync:mutate` | client → server | `{mutationId, collection, operation, id?, data?, baseVersion?}` |
+| `sync:mutate` | client → server | `{mutationId, collection, operation, id?, data?, baseVersion?, mutationMode?}` — validated `mutationMode: "adminWindow"` uses AdminApp executor hooks server-side |
 | `sync:ack` | server → client | `{mutationId, id, seq}` |
 | `sync:nack` | server → client | `{mutationId, code, serverDoc?, serverSeq?, serverDeleted?, message?, retryAfterMs?}` |
 | `sync:mutateBatch` | client → server | `{mutations: SyncMutateRequest[], batchId?}` |
@@ -485,4 +507,8 @@ Backend sync requires a MongoDB replica set (`MONGO_URI` with `replicaSet=`) for
 - **No `bulkWrite` / `updateMany` / `deleteMany`** on synced models — use per-document loops.
 - **Do not write reserved tables** (`_outbox`, `_cursors`, `_conflicts`) directly — use `client.mutate`, hooks, and `resolveConflict`.
 - **User switch wipes local data** — confirmed different-user login clears the previous user's store; bare logout/401 does not (INV-2).
-- **Keep `@terreno/rtk` for non-synced routes** — generated OpenAPI hooks remain the right tool for custom REST endpoints, admin, and auth configuration. See [How to migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+- **Keep `@terreno/rtk` for non-synced routes** — generated OpenAPI hooks remain
+  the right tool for custom REST endpoints, auth, feature flags, and ObjectId
+  admin compatibility CRUD. Eligible admin String-`_id` collection CRUD uses
+  windowed syncdb; framework admin RPC uses its host-bound fetch client. See
+  [How to migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).

package/dist/docs/versioned/next/reference/test.md

@@ -109,8 +109,54 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 
 ## Coverage gates
 
-Package CI uses `scripts/check-coverage.ts` to enforce the package-wide thresholds
-declared in `bunfig.toml`.
+Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
+functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
+`coverageThreshold` before isolated LCOV merges; the script continues when tests
+reported `0 fail` and then enforces 95% on the merged report. Dedicated CircleCI
+jobs (`api-ci`, `ai-ci`,
+`rtk-ci`, `ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
+that script. Published packages without a dedicated workflow
+(`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)
+run the same lint, compile, and coverage commands via the parameterized
+`packages-ci` job. Retained GitHub Actions twins stay in lockstep (`on: []`),
+including `.github/workflows/packages-ci.yml`. Those twins run
+`scripts/ci/check-new-file-coverage-lcov.sh` with `working-directory: .` and
+pass `secrets.CODECOV_TOKEN` into `upload-codecov`.
+
+Each of those jobs then uploads `coverage/lcov.info` to Codecov with a distinct
+flag (`api`, `ui`, `rtk`, …) via `scripts/upload-codecov.sh`. The script
+downloads the linux uploader over HTTPS and refuses to run it unless the
+SHA-256 digest matches the pin in the script (`CODECOV_UPLOADER_SHA256`).
+`codecov.yml` sets per-package flags, `target: auto` with a 1% threshold so
+trivial deltas do not fail PRs, and PR comments for the coverage diff. Uploads
+skip when `CODECOV_TOKEN` is unset. Maintainers set that token in CircleCI
+project env and as a GitHub Actions secret. For a public repo, Codecov still
+requires a token unless the org disables token authentication for public
+repositories (see [Codecov tokens](https://docs.codecov.com/docs/codecov-tokens)).
+
+Demo CI uses `scripts/check-demo-coverage.ts` to fail when a PascalCase component
+exported from `ui/src/index.tsx` has neither a `demo/story-config` registration nor
+an allowlist reason in `DEMO_COVERAGE_ALLOWLIST`. Run it from the repo root:
+
+```bash
+bun run check:demo-coverage
+```
+
+The `demo_lint_and_typecheck` CircleCI command (and the retained
+`.github/workflows/ui-demo-ci.yml` job) runs the unit tests and this check after
+the demo compiles. Add a story plus `demoConfig.tsx` registration for new
+components, or an allowlist entry with a specific reason — not "hard to demo".
+The allowlist is limited to shell/providers, React context objects, thin RN
+list wrappers, subcomponents already exercised by a parent story
+(Filter, Table, DateTimeField, HeightField, ConsentFormScreen), and
+product surfaces that belong in `example-frontend` rather than the isolated
+UI demo (announcements and in-app notifications).
+Standalone picker sheets (`NumberPickerActionSheet`, `DecimalRangeActionSheet`)
+have their own demo stories.
+
+`demo/package.json` `test:ci` runs Bun tests, including a smoke suite that mounts every
+registered `DemoConfig` demo and story through `renderWithTheme` from
+`@terreno/ui`'s test utilities (`demo/storiesSmoke.test.tsx`).
 
 Pull requests also run the `New file coverage` workflow. Every newly added workspace
 `.ts` or `.tsx` implementation file must have at least 90% function coverage and 90%
@@ -118,10 +164,15 @@ line coverage. Test, spec, story, generated OpenAPI SDK, `dist`, isolated-test,
 `src/types` type modules, demo `story-config/*.config.tsx`, and Expo Router route
 files (`index`, `_layout`, `+not-found`, `[param]`, plus example recovery screens
 `forgotPassword` / `resetPassword` / `verifyEmail`) are excluded. A new implementation
-file that is absent from LCOV is treated as 0% covered. The gate runs each package's `bun test` file arguments (or `src` / `*.test.ts`
-globs) so Playwright `*.spec.ts` files are not collected. Globs are expanded in
-the coverage process before `bun test` is spawned, because spawn does not pass
-them through a shell. A glob that matches no files is omitted.
+file that is absent from LCOV is treated as 0% covered. Package CI jobs that
+already produced `coverage/lcov.info` run the 90% check against that report
+(`--package` + `--lcov`) so the dedicated job does not rerun the suite.
+When the dedicated job does rerun a package, it prefers colocated
+`foo.test.ts` / `foo.test.tsx` next to each new `foo.ts` and falls back to
+the package `bun test` paths only when a new file has no sibling test.
+It compiles `@terreno/*` workspace dist deps only when the package imports
+them. The gate still expands globs before spawn so Playwright `*.spec.ts`
+files are not collected. A glob that matches no files is omitted.
 
 Run the same check locally against a base commit:
 

package/dist/docs/versioned/next/reference/ui-performance.md

@@ -137,8 +137,9 @@ time includes dependency evaluation in the Bun test harness. Lower is better.
 
 Changes in this slice:
 
-- Measured heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent/admin tools, and related
+- Measured heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent/admin tools, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related
   exports) now cross lazy root boundaries so their implementation files stay off the cold root import path.
+  `DashboardGrid` stays eager.
 - `MarkdownView`, `DataTable` header info, and `EmojiSelector` defer `react-native-markdown-display` and
   `emoji-datasource` until first use.
 - `RootImportRegression.test.tsx` and `bun run performance:imports` guard the public entrypoints.

package/dist/docs/versioned/next/reference/ui.md

@@ -4,11 +4,12 @@ React Native UI component library (a large component library). Layout (Box, Page
 
 ## Key exports
 
-- Layout: `Box`, `Page`, `SplitPage`, `Card`
+- Layout: `Box`, `Page`, `SplitPage`, `Card`, `DashboardGrid`
 - Forms: `TextField`, `SelectField`, `DateTimeField`, `CheckBox`
-- Display: `Text`, `Heading`, `Badge`, `DataTable`
+- Display: `Text`, `Heading`, `Badge`, `DataTable`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
+- Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
 - Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
@@ -31,8 +32,9 @@ supported and is convenient when startup cost is not material:
 import {Box, DataTable, Icon} from "@terreno/ui";
 ```
 
-Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, and related admin tools) are
+Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
 re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
+their implementation modules load on first render instead of during the initial root import. `DashboardGrid` stays eager.
 their implementation modules load on first render instead of during the initial root import. `MarkdownView` and
 `DataTable` header info defer `react-native-markdown-display`; `EmojiSelector` defers `emoji-datasource` until open.
 
@@ -58,6 +60,115 @@ const customStyle: StyleProp<ViewStyle> = {
 - Ensures type compatibility when passing styles to @terreno/ui components
 - Simplifies imports (one package instead of two)
 
+### DashboardGrid
+
+Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.
+
+```tsx
+<DashboardGrid>
+  <Card>
+    <LineChart data={points} legendLabel="Signups" />
+  </Card>
+</DashboardGrid>
+```
+
+### LineChart
+
+Single-series line chart drawn with `react-native-svg`. Empty data shows `emptyText` (default `"No data"`). `loading` shows a `Spinner`. Press or hover a point for `{label}: {value}`.
+
+```tsx
+<LineChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups"
+/>
+```
+
+Hit targets use `Box` `onClick`, so testIDs are `{testID}.point.{index}-clickable`.
+
+### BarChart
+
+Single-series bar chart on the same owned-SVG contract as `LineChart` (empty, loading, legend, tooltip).
+
+```tsx
+<BarChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups-bar"
+/>
+```
+
+### AreaChart
+
+Filled area plus line on the same owned-SVG contract as `LineChart`.
+
+```tsx
+<AreaChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups-area"
+/>
+```
+
+### DonutChart
+
+One slice per `{label, value}` point. Per-slice `color` overrides the theme paint. Legend is one row per slice (`legendLabel` is ignored).
+
+```tsx
+<DonutChart
+  data={[{label: "Open", value: 3}, {color: "#112233", label: "Closed", value: 5}]}
+  testID="status-donut"
+/>
+```
+
+### Chart visual regression
+
+`bun run ui:charts:compare` screenshots `http://localhost:8085/demo/chart-visual-gallery`
+and diffs each fixture against `demo/rendered-snapshots/<id>.png`.
+`bun run ui:charts:update-snapshots` rewrites those goldens. Fixture ids live in
+`demo/chartVisual/fixtureCatalog.ts`. Operator steps:
+[Compare rendered chart snapshots](../how-to/compare-chart-rendered-snapshots.md).
+
+## Notification components
+
+Presentational only — no syncdb import. Wire data from your app's sync layer.
+These components are not in the isolated UI component demo; see `example-frontend`.
+
+### `NotificationBell`
+
+| Prop | Type | Description |
+|---|---|---|
+| `unreadCount` | `number` | Badge hidden when `0` |
+| `onPress` | `() => void` | Opens the inbox (host owns visibility) |
+| `renderBadge` | `({unreadCount, testID}) => ReactNode` | Replaces the default unread-count badge |
+| `renderIcon` | `({testID}) => ReactNode` | Replaces the default bell icon |
+| `testID` | `string` | Default `notification-bell` |
+
+Custom renderers keep the built-in 40×40 tap target, positioning, toggle callback, and
+accessible unread-count label. `renderBadge` runs only when `unreadCount > 0`.
+
+### `NotificationInbox`
+
+List-only; wrap in `SideDrawer`, `Modal`, or a sheet in the host screen.
+
+| Prop | Type | Description |
+|---|---|---|
+| `items` | `NotificationInboxItem[]` | Rows to render |
+| `isLoading` | `boolean` | Shows spinner |
+| `onMarkRead` / `onMarkUnread` | `(item) => void` | Toggle `readAt` via syncdb |
+| `onDismiss` | `(item) => void` | Archive the row (`archivedAt` via syncdb) |
+| `onOpen` | `(item) => void` | Tap handler (e.g. Expo Router for `href`) |
+
+`NotificationInboxItem.archived` is optional. Archived rows receive an `Archived` label
+and do not expose dismiss or read-state actions.
+
+### `NotificationPreferences`
+
+| Prop | Type | Description |
+|---|---|---|
+| `preferences` | `{inapp, mail, push, sms}` | Current toggles |
+| `onChange` | `(channel, value) => void` | Per-channel updates |
+
 ## Component Behaviors
 
 ### Button Layout Behavior
@@ -78,6 +189,87 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+### TextField password visibility
+
+`type="password"` masks the value and renders a show/hide eye control at the end of the field.
+The control is uncontrolled — the field tracks whether the value is revealed and starts hidden.
+A disabled field cannot be revealed.
+
+``````typescript
+<TextField
+  title="Password"
+  type="password"
+  value={password}
+  onChange={setPassword}
+  autoComplete="current-password"
+/>
+``````
+
+Pass `showVisibilityToggle={false}` where revealing the value is unacceptable, such as a shared or
+on-camera screen:
+
+``````typescript
+<TextField showVisibilityToggle={false} title="Password" type="password" value={password} onChange={setPassword} />
+``````
+
+`Field` with `type="password"` renders the same control, and so do `LoginScreen` and `SignUpScreen`
+password fields.
+
+The toggle's test id defaults to `{testID}.visibility-toggle`, and `testIDs.visibilityToggle`
+overrides it:
+
+| Element | test id |
+| --- | --- |
+| Input | `{testID}` |
+| Label | `{testID}.label` |
+| Error | `{testID}.error` |
+| Helper | `{testID}.helper` |
+| Show/hide toggle | `{testID}.visibility-toggle` |
+
+### GPTChat
+
+Streaming chat surface for `@terreno/ai`. Histories, messages, submit, and optional MCP/tools stay under consumer control.
+
+Pass `mascot` when the app owns a character. Terreno ships none. The node renders only while `currentMessages` is empty, centered in the chat panel above the suggested prompts. The empty hero uses the message viewport height as a minimum so short content stays centered, while taller mascots still scroll. Streaming feedback shares that centered hero instead of creating a second pane. Omit the prop for the default empty chat.
+
+The composer row (attachment picker, tools, input, Send) is vertically centered, so controls stay aligned with the input as it grows. The attachment cell is omitted when `onAttachFiles` is not provided.
+
+```tsx
+<GPTChat
+  currentMessages={[]}
+  histories={histories}
+  mascot={
+    <Box alignItems="center">
+      <Heading size="lg">🦊</Heading>
+    </Box>
+  }
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+/>
+```
+
+Operator steps: [Add a GPT chat mascot](../how-to/add-gpt-chat-mascot.md). Demo story: `GPTChat` → `Mascot`.
+The example AI screen demonstrates a consumer selecting one of four bundled mascot
+images once per mount.
+
+### SplitPage
+
+Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list, and
+`renderContent` for the detail pane. On large screens both panes stay visible. On small
+screens the detail replaces the list until the user goes back.
+
+```typescript
+import {SplitPage, Text} from "@terreno/ui";
+
+<SplitPage
+  listViewData={[{id: "1", name: "Inbox"}]}
+  renderListViewItem={({item}) => <Text>{item.name}</Text>}
+  renderContent={(index) => <Text>{index === undefined ? "Select an item" : "Detail"}</Text>}
+/>
+```
+
 ### Page Back Navigation
 
 Set `backButton` to render the standard header back arrow. By default it calls `router.back()`; provide `onBack` when the screen needs a deterministic destination instead of browser history.
@@ -574,6 +766,68 @@ import {TerrenoProvider} from "@terreno/ui";
 </TerrenoProvider>
 ``````
 
+## DataTable server-side filtering
+
+`DataTable` is data-layer agnostic. Optional filter and search props emit a
+modelRouter-shaped JavaScript object through `onQueryChange`. The parent merges
+that object with `page`, `limit`, and `sort` before calling a list endpoint.
+
+Import the pure helper when building params outside the component:
+
+```typescript
+import {buildDataTableListQuery} from "@terreno/ui/dataTableListQuery";
+```
+
+### Query contract
+
+| UI | Wire param |
+| --- | --- |
+| Toolbar search (`search` + `searchFields`) | `$or: [{field: {$regex, $options: "i"}}, ...]` (user text escaped) |
+| Text column filter | `{field: {$regex, $options: "i"}}` |
+| Boolean column filter | `{field: true \| false}`; unset omits the key |
+| Date range | `field_gte` / `field_lte` ISO strings; either bound may be sent alone |
+| Number range | `{field: {$gte?, $lte?}}` |
+| Choice (one value) | `{field: string}` scalar equality |
+| Choice (many values) | `{field: {$in: string[]}}` |
+| Choice **Empty** (optional fields) | `{field: {$in: ["__empty__"]}}` on the wire; server maps to `null` (matches missing and null) |
+| Choice **Empty** + concrete | `{field: {$in: [...values, "__empty__"]}}` |
+
+`onQueryChange` never includes `page`, `limit`, or `sort`. Search is debounced
+(250ms, same delay as admin list search).
+
+The server accepts only the documented nested operator keys. Text `$regex` values
+must be escaped literals; executable patterns and extra Mongo operators are rejected.
+
+Date range filters collect calendar days, so a range covers whole UTC days: **from**
+opens the chosen day (`00:00:00.000Z`) and **to** closes it (`23:59:59.999Z`), which
+keeps rows recorded later on the end day inside the range.
+
+Pass `emptyContent` to keep the table header, search, and filter controls mounted
+while showing an application-specific empty state below the header.
+Use `additionalFilters` for declared server filters whose fields are not visible
+columns; web shows one **More filters** popover and native includes them in the same sheet.
+
+### Platform chrome
+
+| Platform | Chrome |
+| --- | --- |
+| Web | Toolbar search + per-column `Filter` popovers (`column.filter`) |
+| Native | Toolbar search + one **Filters** sheet (`Modal`) with the same fields |
+
+Column headers use `Filter` with `iconOnly`, which renders a compact icon trigger
+(24px at the default `triggerSize="sm"`, 32px with `triggerSize="default"`) instead
+of a labeled button. Give it an accessible name with `triggerAccessibilityLabel`.
+
+A single-column popover offers only its own **Clear**, so it needs no per-field clear.
+The surfaces that host several filters at once — the **More filters** popover and the
+native **Filters** sheet — add a per-field **Clear filter** for booleans, whose toggle
+cannot otherwise express "unset".
+
+Omit `column.filter`, `searchFields`, and the related callbacks to keep today's
+sort/page-only table.
+
+Demo: `FilterableDataTable` story in the component demo (`demo:start`, port 8085).
+
 ## Related Documentation
 
 - [UI performance benchmarks](ui-performance.md)

package/dist/docs/versioned/next/tasks/admin-scripts-durable-jobs.md

@@ -0,0 +1,10 @@
+# Tasks: Admin scripts via durable jobs
+
+**IP:** [admin-scripts-durable-jobs.md](../implementationPlans/admin-scripts-durable-jobs.md)
+
+- [x] **Task 1**: `admin/script` adapter (`defineAdminScriptJob`, payload parse, dual-write `BackgroundTask`)
+- [x] **Task 2**: `AdminApp` enqueue/cancel when `JobsApp` is registered; in-process fallback
+- [x] **Task 3**: example-backend worker + API share `defineAdminScriptJob(adminScripts)`
+- [x] **Task 4**: Docs (how-to jobs, jobs reference, admin-backend scripts)
+- [x] **Task 5**: Example GCP runtime selects `GcpCloudTasksRunner` and verifies callback OIDC
+- [x] **Task 6**: CD supplies `JOBS_RUNNER=gcp-cloud-tasks` and per-PR callback URLs