@terreno/admin-spa 58.0.0-beta.2 → 58.0.0-beta.4

package/CHANGELOG.md

@@ -20,6 +20,121 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
 
 Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
 
+## [58.0.0-beta.4] - 2026-11-04
+
+Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.4.md`](mcp-server/src/docs/upgrades/58.0.0-beta.4.md).
+
+### Breaking
+
+- `@terreno/admin-spa` now server-renders every admin page in the backend's Express process, behind an access gate that runs before anything renders. The first HTML holds the login form, the shell and the screen's data. Upgrade steps: [Upgrade to the server-rendered admin SPA](docs/how-to/upgrade-admin-spa-ssr.md).
+- `AdminSpaServeApp`'s `distDir` (and example-backend's `ADMIN_SPA_DIST_DIR`) now names the export root, which holds `client/` and `server/`. `build:web` no longer writes `dist/index.html`. Rebuild, and copy the whole `dist` into images. Without `dist/server` the plugin answers 503 on `/console/*`.
+- `basePath` must equal the `experiments.baseUrl` baked into the bundle (`/console` by default), or `register()` throws. Any other mount needs `experiments.baseUrl` set in `admin-spa/app.json` and a rebuild from source; the published package ships only the `/console` build. Mounting at the site root (`basePath: "/"`) is no longer supported.
+- Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
+- Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
+- Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
+- React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
+- `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
+- The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
+- `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
+- `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
+- `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
+- `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
+- Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
+- `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
+- `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
+- Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
+- `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`), `@terreno/syncdb/mcp` (`useMCPTools`), and `@terreno/syncdb/buildNumber`.
+- `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
+- `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
+- `GptHistory` (`gpt/histories`) is a synced collection and keeps its ObjectId `_id` (no migration). `McpServiceToken` (`mcp/service-tokens`, read-only) is a synced collection with String ids; run `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
+- `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
+- `@terreno/syncdb`: `useMCPTools` (and `MCPToolInfo`, `UseMCPToolsOptions`, `UseMCPToolsResult`) moved from `@terreno/syncdb/app` to the new `@terreno/syncdb/mcp` entry point. Change `import {useMCPTools} from "@terreno/syncdb/app"` to `import {useMCPTools} from "@terreno/syncdb/mcp"`. The hook imports the optional `@modelcontextprotocol/client` peer at the top level, so exporting it from `/app` broke every app that imported `/app` without that package installed, including apps scaffolded by `create-terreno-app`, which import `installDevConsoleLogger` from `/app`.
+
+### Added
+
+- `AdminSpaServeApp` options `internalOrigin` (where server renders fetch API data, default `http://127.0.0.1:${PORT ?? 4000}`) and `ssrApiPrefixes` (API paths a render may fetch). The plugin also serves Expo's root `/_expo/loaders/*`, with `Cache-Control: no-store, private` on pages and loader data.
+- `@terreno/syncdb`: `SessionProvider` / session store `initialSession`, and the request client's `primeQuery(args, data)`, to start from data a server render already read.
+- `@terreno/admin-frontend`: `AdminRpcSeed` and `adminRpcSeedKey` seed `useAdminRpcQuery` with server-fetched bodies; `buildAdminReadUrl`, `buildAdminListQueryParams`, `buildAdminApiListQueryRequest` and `homeWidgetUrls` build the exact URLs the screens request.
+- `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
+- `@terreno/syncdb` `createSyncDb({idFormats})` mints 24-hex ObjectIds for a collection set to `"objectId"`, so a model that keeps Mongoose's default ObjectId `_id` can sync without migrating its ids. `mutate()` throws on an explicit non-hex id for such a collection. `generateObjectId` and the `SyncIdFormat` type are exported.
+- Sync `validation` nacks carry an optional `reason`: `invalid_id` when an ObjectId-keyed collection gets a non-hex id (rejected before the mutation is claimed), and `id_collision` when a create names an `_id` another document holds. A collision never touches the existing document and its message never names the holder. The ledger records the reason (`SyncMutation.nackReason`) so a redelivery replays it.
+- `GET /sync/entities` leaves out non-hex ids for an ObjectId-keyed model instead of answering 400, so a rejected create queued for repair cannot fail the rest of the repair batch.
+
+### Changed
+
+- The admin comms dashboard's default 7-day range now ends at the next whole minute, so a server render and the hydrating browser request the same URL.
+
+  `useAdminRpcQuery` treats the request's `X-Organization-Id` as part of its key. When the selected organization changes on the same URL, it drops the previous organization's data and loads again, even with `keepPreviousData`, so one organization's rows never show under another.
+
+  `useAdminModelApi`'s `useReadQuery` builds its URL with `buildAdminReadUrl`, which encodes the id.
+- The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
+- `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
+
+### Deprecated
+
+- `@terreno/admin-spa` `rewriteIndexHtml` and `injectBaseGlobal` are deprecated: the server-rendered build has no `index.html`, and `app/+html.tsx` writes `window.__ADMIN_SPA_BASE__` itself. They will be removed in the next major release.
+
+### Removed
+
+- `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
+
+### Fixed
+
+- The admin configuration screen shows stored values again: `useConfigurationApi`'s values query unwraps the API's `{data}` envelope.
+- syncdb window hydration no longer lets a REST page overwrite a newer synced entity. REST rows only fill ids the store lacks, and a stored entity at least as new as the fetched one is kept, so a live delta is never skipped.
+- `@terreno/api`: `modelRouter("/path", Model, options)` no longer builds a router at registration. `TerrenoApp` mounts the router from `_buildWithContext`, which has OpenAPI wired in, so the eager one was built for nothing and logged "No options.openApi provided" for every model at import. `registration.router` now builds on first read, for code that mounts a registration by hand.
+- `@terreno/api`: admin responses keep ObjectId, Date and other non-plain values intact. `scrubAdminFields` used to copy the own keys of every object it reached, so an ObjectId in an array field (or a bare ObjectId ref) came back as a plain `{i0, i1, i2, i3}` object and a Date became `{}`. It now scrubs only plain objects and Mongoose documents, and never treats a bare ObjectId as a populated document.
+- `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
+- `@terreno/syncdb`: a record you create now gets the server's copy, including `_id` and other server-added fields. Before, the mutation ACK stamped the row's seq before the server's delta for that seq arrived, so the delta was dropped as a duplicate and the row kept only its optimistic data. Filters on real ids and anything else that reads server fields failed for that row. The ACK sets a marker on that row; the equal-seq delta applies only while the marker is set, and a later local edit clears it. Deltas older than the row's seq, and repeats of a delta the row already took, are still skipped.
+- `@terreno/ui`: the `DateTimeActionSheet` time wheels show their numbers on physical iPhones. iOS now uses UIPickerView's natural 216pt height. The forced 104pt height looked fine in the simulator but showed empty rows on devices. Wheel items also take the theme's text color on iOS, not just Android, so they're no longer white on white on a dark-mode phone.
+
+## [58.0.0-beta.3] - 2026-11-03
+
+Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.3.md`](mcp-server/src/docs/upgrades/58.0.0-beta.3.md).
+
+### Breaking
+
+- Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
+- Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
+- Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
+- React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
+- `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
+- The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
+- `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
+- `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
+- `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
+- `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
+- Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
+- `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
+- `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
+- Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
+- Apps upgrading from `@terreno/rtk` must install `expo-constants` and `expo-network` themselves (rtk depended on them; `@terreno/syncdb` lists them as optional peers), plus the optional peers for the features they use: `better-auth`, `@better-auth/expo`, `@better-auth/passkey`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@modelcontextprotocol/client`. See the upgrade note.
+- `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
+- `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
+- `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
+- `GptHistory` (`gpt/histories`) is a synced collection and keeps its ObjectId `_id` (no migration). `McpServiceToken` (`mcp/service-tokens`, read-only) is a synced collection with String ids; run `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
+- `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
+
+### Added
+
+- `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
+- `@terreno/syncdb` `createSyncDb({idFormats})` mints 24-hex ObjectIds for a collection set to `"objectId"`, so a model that keeps Mongoose's default ObjectId `_id` can sync without migrating its ids. `mutate()` throws on an explicit non-hex id for such a collection. `generateObjectId` and the `SyncIdFormat` type are exported.
+- Sync `validation` nacks carry an optional `reason`: `invalid_id` when an ObjectId-keyed collection gets a non-hex id (rejected before the mutation is claimed), and `id_collision` when a create names an `_id` another document holds. A collision never touches the existing document and its message never names the holder. The ledger records the reason (`SyncMutation.nackReason`) so a redelivery replays it.
+- `GET /sync/entities` leaves out non-hex ids for an ObjectId-keyed model instead of answering 400, so a rejected create queued for repair cannot fail the rest of the repair batch.
+
+### Changed
+
+- The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
+- `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
+
+### Removed
+
+- `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
+
+### Fixed
+
+- `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
+
 ## [58.0.0-beta.2] - 2026-11-03
 
 Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.2.md`](mcp-server/src/docs/upgrades/58.0.0-beta.2.md).
@@ -109,6 +224,37 @@ Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.1.md`](mcp-server/src/d
 
 - `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
 
+## [57.22.0] - 2026-11-03
+
+Upgrade note: [`mcp-server/src/docs/upgrades/57.22.0.md`](mcp-server/src/docs/upgrades/57.22.0.md).
+
+### Breaking
+
+- `@terreno/ai` no longer integrates with Langfuse. The built-in observability prompt registry, traces, and review queue (`ObservabilityApp` with `createLocalObservabilityPlugin()`) replace it. Removed exports: `LangfuseApp`, `LangfuseCache`, `getCached`, `setCached`, `invalidateCache`, `initLangfuseClient`, `getLangfuseClient`, `isLangfuseInitialized`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `invalidatePromptCache`, `initTracing`, `shutdownTracing`, `createTelemetryConfig`, `preparePromptForAI`, and the types `ChatMessage`, `GetPromptOptions`, `LangfuseAppOptions`, `LangfuseCachedPrompt`, `PaginatedResult`, `PreparePromptResult`, `PromptListItem`, `ScoreSubmission`, `ScoringFunction`, `TelemetrySettings`, `TraceListItem`. The `@terreno/ai/langfuseApp` and `@terreno/ai/langfuseClient` subpath exports are gone, along with the `@langfuse/client`, `@langfuse/otel`, and `@opentelemetry/*` dependencies of `@terreno/ai`.
+- `addGptRoutes` drops `langfuseSystemPromptName`; use `systemPromptName` (a registry prompt) instead. Chat turns no longer set `experimental_telemetry`.
+- `ControlPrimary` is now only `"local"`.
+- The example backend no longer reads `LANGFUSE_SECRET_KEY`, `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_BASE_URL`, `LANGFUSE_ORGANIZATION`, `LANGFUSE_PROJECT`, or `LANGFUSE_PROJECT_ID`. Deploys (`.github/workflows/cd.yml`, `scripts/ci/gcp-deploy.sh`) no longer mount the Langfuse secrets, and `infra/flourish/main.tf` drops the `backend_secret_langfuse_secret_key` and `backend_secret_langfuse_public_key` modules, so the next `terraform apply` deletes those two Secret Manager secrets. Deploy a revision without the mounts before applying.
+
+### Added
+
+- `addGptRoutes` accepts `systemPromptName` and `systemPromptLabel`. A chat turn prepends that observability registry prompt to the system prompt and records its version on the trace.
+- The example chat reads `chat-assistant` and the `generate_joke` tool reads `joke-generator` from the observability prompt registry.
+- `bun run backend:seed` fills every AI Observability screen: labelled prompt versions for `example-summarize`, `joke-generator`, and `chat-assistant`, golden datasets, finished experiments, traces with scores, and review items in every status. Run it on an existing database with the `seedAiObservabilityDemo` admin script.
+- Review batches: pick a human question set and press **Grab 10 recent traces** to give reviewers a fixed set of inputs and outputs (`POST /ai/observability/review/batches`).
+- The review item screen shows one input, one output, and every question as Yes / No rows. On web, `Y` / `N` answer the highlighted question, `Enter` submits and moves to the next batch item, and `S` skips. Evaluator dimensions accept a reviewer `question`.
+- Run any LLM judge over a batch and see overall and per-question agreement with the human answers, plus a list of disagreements (`POST /ai/observability/review/batches/:id/judgeRuns`).
+- The AI observability seed adds the `summary-review-questions` question set, two judges for it, and a 10-item batch with 8 answers where one judge agrees 97% and the other 78%.
+- Observability registry prompts can reference other prompts with `{{> base-rules}}`, `{{> base-rules label=staging}}`, or `{{> base-rules version=3}}` (default label `production`). Shared instructions live in one prompt; `PromptRegistry.get`, the playground, experiments, and judges use the resolved text.
+- Every reference must resolve when it is saved. Creating a prompt, saving a version, and moving a label return 400 `Invalid prompt reference` for a malformed tag, an unknown prompt or version, or a label the referenced prompt does not have yet, 400 `Prompt reference cycle` when the change would make prompts include each other, and 400 `Prompt references nested too deeply` when it would nest the prompt, or any prompt that includes it, more than 5 levels.
+- Traces stay named after the called prompt. `ObsTrace.prompts` lists it first, then each shared prompt version it pulled in, marked with `includedBy`. `PromptVersionRef.includes` and harness prompt refs carry the same list.
+
+### Fixed
+
+- Review queue: `Y` and `N` answer the highlighted question when a Yes/No segment is focused. **What the AI was given** and **What the AI wrote** are headings above the field cards.
+- Review batches: **Save batch** sits on the New batch card. Search and **More filters** share a baseline.
+- Prompt hub: description, folder, and tags sit on the Versions screen with the editor. System and template fields explain what to write.
+- Evaluator detail loads the judge prompt `outputSchema` (so helpfulness no longer reports a missing dimension) and experiment rows open that experiment.
+
 ## [57.21.0] - 2026-11-01
 
 Upgrade note: [`mcp-server/src/docs/upgrades/57.21.0.md`](mcp-server/src/docs/upgrades/57.21.0.md).

package/README.md

@@ -2,7 +2,7 @@
 
 Opt-in admin SPA (Expo Router web app) plus an Express plugin that serves it from a Terreno backend.
 
-Opt-in package that lets any Terreno backend serve a pre-built admin SPA from the
+Opt-in package that lets any Terreno backend server-render a pre-built admin SPA from the
 same Node process — no separate static-site deploy to GCS/Netlify/Cloudflare Pages.
 
 The default backend image stays small: React/Expo assets only ship in the npm
@@ -12,14 +12,18 @@ does) remains supported and unchanged.
 
 ## What's here
 
-- **Backend serving plugin** (`src/`, `AdminSpaServeApp`): serves the pre-built Expo
-  Router static export (`dist/`) and a runtime `app-config.json` from a Terreno backend.
+- **Backend serving plugin** (`src/`, `AdminSpaServeApp`): server-renders the pre-built
+  Expo Router export (`dist/client` + `dist/server`) behind an access gate, and serves a
+  runtime `app-config.json`, from a Terreno backend.
+- **Route loaders** (`server/`): fetch each screen's data with the visitor's cookie, so the
+  first HTML holds the page and its data.
 - **The SPA frontend** (`app/`, `store/`, `components/`): an Expo Router web app that
   wires `@terreno/admin-frontend`'s screens with a Better-Auth session gate. It uses the
   `@terreno/admin-frontend` `apiBase`/`routeBase` prop split so API calls go to `/admin`
   while in-app navigation stays inside the SPA.
 
-Boot flow: `AppConfigGate` fetches `app-config.json` → `StoreProvider` builds the
+Boot flow: the Express gate decides access and the server renders the page →
+`AppConfigGate` hydrates from the config written into the page → `StoreProvider` builds the
 Better-Auth client and a same-origin request client and mounts `SessionProvider` from
 `@terreno/syncdb/auth` → `AdminGate` reads `useSession()` and redirects
 anonymous users to `/login` and non-admins (admin API returns 403) to `/forbidden`,
@@ -64,6 +68,9 @@ bun add @terreno/admin-spa
 
 ## Register with a backend
 
+Register `BetterAuthApp` before `AdminSpaServeApp`: the gate reads `req.user`, which the
+Better Auth session middleware sets.
+
 ```typescript
 import {AdminSpaServeApp} from "@terreno/admin-spa";
 import {AdminApp} from "@terreno/admin-backend";
@@ -95,8 +102,10 @@ cookies attach automatically, no CORS.
 |---|---|---|
 | `basePath` | `/console` | Path the SPA mounts at. The `/admin` API is untouched. |
 | `appConfig` | see below | Runtime config served at `${basePath}/app-config.json`. Merged over defaults. |
-| `distDir` | `<pkg>/dist` | Override the pre-built bundle directory (tests / custom builds). |
-| `devProxyTarget` | — | In dev, proxy all SPA paths to a running `expo start --web`, e.g. `http://localhost:8083`. |
+| `distDir` | `<pkg>/dist` | The export root holding `client/` and `server/` (compiled binaries, custom builds, tests). |
+| `devProxyTarget` | — | In dev, proxy all SPA paths to a running `expo start --web`, e.g. `http://localhost:8083`. No gate or server render is mounted. |
+| `internalOrigin` | `http://127.0.0.1:${PORT ?? 4000}` | Where server renders fetch API data, with the visitor's cookie. Never taken from `Host` or `X-Forwarded-*`. |
+| `ssrApiPrefixes` | admin API base, `/auth/me`, `/orgs`, `/jobs`, `/comms`, `/configuration`, `/rbac` | API prefixes a render may fetch. Replaces the defaults; keep the admin API base. |
 
 ### App config
 
@@ -115,34 +124,42 @@ auth/admin API paths per consumer without rebuilding. Defaults:
 
 ## How serving works
 
-- `${basePath}/_expo` and `${basePath}/assets` are served with
-  `Cache-Control: public, max-age=31536000, immutable`.
-- `${basePath}/app-config.json` and `index.html` are served with
-  `Cache-Control: no-store`.
-- `index.html`'s absolute `/_expo/` and `/assets/` references are rewritten once at
-  boot to `${basePath}/...` (a no-op when the bundle was already built for that base).
-- The serve plugin injects `window.__ADMIN_SPA_BASE__ = "${basePath}"` into `index.html`
-  so the SPA can resolve `app-config.json` on deep refreshes.
-- SPA fallback: both the bare `${basePath}` and `${basePath}/*splat` return
-  `index.html` (Express 5 named-splat convention).
+| Path | `Cache-Control` |
+|---|---|
+| `${basePath}/_expo/*`, `${basePath}/assets/*` (from `dist/client`) | `public, max-age=31536000, immutable` |
+| `${basePath}/app-config.json` | `no-store` |
+| Pages under `${basePath}` and loader data at `${basePath}/_expo/loaders/*` and root `/_expo/loaders/*` | `no-store, private` |
+
+- Pages and loader data can hold PHI. Never cache them in a proxy or CDN.
+- Expo SDK 58's client fetches loader data from the site root, `/_expo/loaders/<route>`,
+  ignoring the baked base URL. The plugin claims that root path too; route it to the backend.
+- The gate runs before any render. Anonymous visitors get `/login` (other pages redirect to
+  it; loaders answer 401). Signed-in non-admins get `/forbidden` (loaders answer 403). If a
+  loopback read fails or takes over 5 s, the gate answers 503 and renders nothing.
+- Each signed-in page makes 3 gate calls (`get-session`, `/auth/me`, `/admin/config`) plus its
+  loader's calls to `internalOrigin` (1 to 3 on most screens; on the home page one per model plus
+  up to 3), counted in the visitor's own rate-limit bucket.
+- Without `dist/server`, the plugin logs a warning and answers 503 on `${basePath}/*`.
+- `rewriteIndexHtml` and `injectBaseGlobal` are deprecated and will be removed in the next
+  major release.
 
 ### Mount path / `baseUrl`
 
-Client-side routing under a sub-path requires the bundle to be built with a matching
-router base. `app.json` sets `experiments.baseUrl: "/console"`, so the default build is
-served at `/console` and `basePath` must match. To mount elsewhere, rebuild with the
-matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath`
-accordingly. Mounting at the origin root (`basePath: "/"`) needs no base.
+`app.json` sets `experiments.baseUrl: "/console"`, and that value is baked into the build.
+`basePath` must equal it, or `register()` throws. To mount elsewhere, change
+`experiments.baseUrl` in `app.json`, run `bun run build:web`, and set `basePath` to match.
+`EXPO_BASE_URL` in the shell has no effect: Metro reads the app config. The published
+package ships the `/console` build only. Mounting at the origin root is not supported.
 
 ## Develop, build, and test
 
 ```bash
 bun run compile      # compile the server plugin (src/ -> src/dist, CommonJS)
-bun run build:web    # produce the static export in dist/
+bun run build:web    # produce the server export in dist/ (client/ + server/)
 bun run dev          # expo start --web for local SPA development
 bun run test:ci      # serve-plugin unit tests (supertest)
-bun run smoke        # backend-free smoke: compiled serve plugin + built dist/
-bun run test:e2e     # Playwright e2e (anonymous -> login) over the built dist/
+bun run smoke        # backend-free smoke: compiled serve plugin over the built dist/ (SSR login, root loader, redirect)
+bun run test:e2e     # Playwright e2e (SSR, login, shell hydration) over the built dist/
 ```
 
 `dist/` is produced by `bun run build:web` and shipped via
@@ -162,6 +179,8 @@ populated.
 
 Full API reference: [docs/reference/admin-spa.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/admin-spa.md)
 
+Upgrading from the static export: [docs/how-to/upgrade-admin-spa-ssr.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/upgrade-admin-spa-ssr.md)
+
 ## License and Contributing
 
 Licensed under the [MIT License](https://github.com/TerrenoLabs/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/TerrenoLabs/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.

package/package.json

@@ -7,9 +7,9 @@
     "@better-auth/expo": "^1.6.25",
     "@expo/vector-icons": "^15.1.1",
     "@react-native-async-storage/async-storage": "2.2.0",
-    "@terreno/admin-frontend": "58.0.0-beta.2",
-    "@terreno/syncdb": "58.0.0-beta.2",
-    "@terreno/ui": "58.0.0-beta.2",
+    "@terreno/admin-frontend": "58.0.0-beta.4",
+    "@terreno/syncdb": "58.0.0-beta.4",
+    "@terreno/ui": "58.0.0-beta.4",
     "better-auth": "^1.6.25",
     "expo": "~58.0.14",
     "expo-constants": "~58.0.12",
@@ -18,6 +18,7 @@
     "expo-network": "~58.0.3",
     "expo-router": "~58.0.23",
     "expo-secure-store": "~58.0.2",
+    "expo-server": "~58.0.5",
     "expo-splash-screen": "~58.0.10",
     "expo-status-bar": "~58.0.3",
     "express": "^5.2.1",
@@ -36,8 +37,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
     "@playwright/test": "^1.58.2",
-    "@terreno/api": "58.0.0-beta.2",
-    "@terreno/test": "58.0.0-beta.2",
+    "@terreno/api": "58.0.0-beta.4",
+    "@terreno/test": "58.0.0-beta.4",
     "@types/bun": "^1.4.0",
     "@types/express": "^5.0.6",
     "@types/luxon": "^3.7.1",
@@ -78,7 +79,7 @@
   "main": "expo-router/entry",
   "name": "@terreno/admin-spa",
   "peerDependencies": {
-    "@terreno/api": "58.0.0-beta.2"
+    "@terreno/api": "58.0.0-beta.4"
   },
   "publishConfig": {
     "access": "public"
@@ -92,13 +93,13 @@
     "compile": "tsc -p tsconfig.server.json",
     "compile:watch": "tsc -p tsconfig.server.json -w",
     "dev": "expo start --web --port 8083",
-    "lint": "biome check ./src ./app ./store ./components ./e2e playwright.config.ts playwright.integration.config.ts",
-    "lint:fix": "biome check --write ./src ./app ./store ./components ./e2e playwright.config.ts playwright.integration.config.ts",
+    "lint": "biome check ./src ./app ./store ./components ./server ./e2e playwright.config.ts playwright.integration.config.ts",
+    "lint:fix": "biome check --write ./src ./app ./store ./components ./server ./e2e playwright.config.ts playwright.integration.config.ts",
     "smoke": "bun e2e/smoke.ts",
     "start": "expo start",
-    "test": "bun test ./src ./store ./components",
-    "test:agent": "AGENT=1 bun test --only-failures ./src ./store ./components",
-    "test:ci": "bun test ./src ./store ./components",
+    "test": "bun test ./src ./store ./components ./server",
+    "test:agent": "AGENT=1 bun test --only-failures ./src ./store ./components ./server",
+    "test:ci": "bun test ./src ./store ./components ./server",
     "test:coverage": "bun run ../scripts/check-coverage.ts",
     "test:e2e": "playwright test",
     "test:integration": "playwright test --config playwright.integration.config.ts",
@@ -106,5 +107,5 @@
     "web": "expo start --web --port 8083"
   },
   "types": "./src/dist/index.d.ts",
-  "version": "58.0.0-beta.2"
+  "version": "58.0.0-beta.4"
 }

package/src/dist/gate.d.ts

@@ -0,0 +1,31 @@
+import type express from "express";
+import type { AdminSpaAppConfig } from "./appConfig";
+export interface AdminSpaGateOptions {
+    /** Base path of the admin API on this origin (`/admin`). */
+    adminApiBasePath: string;
+    appConfig: AdminSpaAppConfig;
+    /** Where the SPA is mounted (`/console`). */
+    basePath: string;
+    /** Renders the page or loader; called inside the request scope. */
+    handler: express.RequestHandler;
+    /** Origin of this backend for loopback reads. Never derived from the request. */
+    internalOrigin: string;
+}
+/**
+ * Express middleware that decides access before the admin SPA renders anything. Mounted at
+ * the site root, it gates `GET` page and loader requests under `basePath` and loader requests
+ * at the root `/_expo/loaders`, and passes every other path through.
+ *
+ * - Anonymous: pages other than `/login` redirect to `{basePath}/login?returnTo=<path>`;
+ *   loaders answer 401 JSON (the `login` and `forbidden` loaders run).
+ * - Signed in but not an admin (`/admin/config` 403): signed-in-only routes (`/oauth/consent`)
+ *   render, `/login` with a safe `returnTo` redirects there; other pages redirect to
+ *   `{basePath}/forbidden`;
+ *   loaders answer 403 JSON.
+ * - Admin: `/login` redirects to a safe `returnTo` (or `{basePath}/`); everything else renders
+ *   inside a request scope holding the session, profile and admin config, so the page renders
+ *   with its shell instead of a spinner.
+ * - An upstream answer other than 200 / 401 / 403, a network error or a 5 s timeout answers
+ *   503 without rendering. A 401 counts as anonymous.
+ */
+export declare const createAdminSpaGate: (options: AdminSpaGateOptions) => express.RequestHandler;