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

package/CHANGELOG.md

@@ -20,6 +20,74 @@ 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).
@@ -156,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.3",
-    "@terreno/syncdb": "58.0.0-beta.3",
-    "@terreno/ui": "58.0.0-beta.3",
+    "@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.3",
-    "@terreno/test": "58.0.0-beta.3",
+    "@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.3"
+    "@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.3"
+  "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;

package/src/dist/gate.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdminSpaGate = void 0;
+const api_1 = require("@terreno/api");
+const returnTo_1 = require("./returnTo");
+const serverContext_1 = require("./serverContext");
+const signedInOnlyRoutes_1 = require("./signedInOnlyRoutes");
+/** Longest the gate waits on any of its loopback reads before failing closed. */
+const UPSTREAM_TIMEOUT_MS = 5000;
+/** Where Expo's client fetches route loader data, at the site root and under `basePath`. */
+const LOADERS_PATH = "/_expo/loaders";
+/** Paths under `basePath` that are never gated: hashed assets and the runtime config. */
+const UNGATED_PREFIXES = ["/_expo/static", "/assets", "/app-config.json"];
+/** Routes an anonymous or forbidden visitor may render (and load data for). */
+const PUBLIC_ROUTES = new Set(["/login", "/forbidden"]);
+/** Statuses the gate understands; anything else fails closed. */
+const KNOWN_STATUSES = new Set([200, 401, 403]);
+const ANONYMOUS = {
+    access: "anonymous",
+    adminConfig: null,
+    adminConfigStatus: null,
+    profile: null,
+    session: null,
+};
+/** Thrown when an upstream read fails in a way the gate cannot decide on. */
+class GateUnavailableError extends Error {
+}
+/** Base for resolving a request URL on its own. */
+const URL_BASE = "http://gate.invalid";
+/** Characters RFC 3986 calls unreserved: an escape of one of them means the character itself. */
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+/**
+ * RFC 3986 percent-encoding normalization: decode escapes of unreserved characters and
+ * uppercase the hex of the rest. `/console/User/%36ae…` and `/console/User/6ae…` name the same
+ * record, and Expo keys loader data by the raw path while the router looks it up by the decoded
+ * params, so only the canonical form renders with its data. The URL parser already treats `%2E`
+ * as a dot, so this changes no dot-segment decision.
+ */
+const canonicalizeEscapes = (url) => {
+    return url.replace(/%([0-9A-Fa-f]{2})/g, (match, hex) => {
+        const character = String.fromCharCode(Number.parseInt(hex, 16));
+        return UNRESERVED.test(character) ? character : match.toUpperCase();
+    });
+};
+/**
+ * Classify a request by its normalized path: dot segments, including encoded ones, resolved
+ * the way Expo will resolve them. Deciding on the raw path would let `/console/assets/../Todo`
+ * pass as an asset and then render as `/Todo`.
+ */
+const classify = (method, requestPath, basePath) => {
+    const isRead = method === "GET" || method === "HEAD";
+    if (requestPath.startsWith(`${LOADERS_PATH}/`)) {
+        return isRead
+            ? { kind: "loader", route: requestPath.slice(LOADERS_PATH.length) }
+            : { kind: "write" };
+    }
+    if (requestPath !== basePath && !requestPath.startsWith(`${basePath}/`)) {
+        return { kind: "outside" };
+    }
+    if (!isRead) {
+        return { kind: "write" };
+    }
+    const inner = requestPath.slice(basePath.length) || "/";
+    if (inner.startsWith(`${LOADERS_PATH}/`)) {
+        return { kind: "loader", route: inner.slice(LOADERS_PATH.length) };
+    }
+    if (UNGATED_PREFIXES.some((prefix) => inner === prefix || inner.startsWith(`${prefix}/`))) {
+        return { kind: "static" };
+    }
+    return { kind: "page", route: inner };
+};
+/** One loopback read with the visitor's cookie. Only a 200 body is read. */
+const readUpstream = async (url, cookie) => {
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: cookie ? { Accept: "application/json", Cookie: cookie } : { Accept: "application/json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.name : "unknown error";
+        throw new GateUnavailableError(`${new URL(url).pathname} failed: ${reason}`);
+    }
+    if (!KNOWN_STATUSES.has(response.status)) {
+        throw new GateUnavailableError(`${new URL(url).pathname} answered ${response.status}`);
+    }
+    if (response.status !== 200) {
+        return { body: null, status: response.status };
+    }
+    try {
+        return { body: await response.json(), status: 200 };
+    }
+    catch {
+        throw new GateUnavailableError(`${new URL(url).pathname} answered a body that is not JSON`);
+    }
+};
+/** The session snapshot from a Better Auth `get-session` body, or null when signed out. */
+const sessionSnapshotOf = (body) => {
+    const value = body;
+    const userId = value?.session?.userId;
+    if (typeof userId !== "string" || !value?.user) {
+        return null;
+    }
+    return { user: value.user, userId };
+};
+/** Read the session, profile and admin config in parallel and decide the visitor's access. */
+const loadShellPayload = async (req, { adminApiBasePath, appConfig, internalOrigin }) => {
+    const cookie = req.headers.cookie;
+    const authBasePath = appConfig.authBasePath ?? "/api/auth";
+    const [session, profile, config] = await Promise.all([
+        readUpstream(`${internalOrigin}${authBasePath}/get-session`, cookie),
+        readUpstream(`${internalOrigin}/auth/me`, cookie),
+        readUpstream(`${internalOrigin}${adminApiBasePath}/config`, cookie),
+    ]);
+    const snapshot = session.status === 200 ? sessionSnapshotOf(session.body) : null;
+    if (!snapshot || profile.status === 401 || config.status === 401) {
+        return ANONYMOUS;
+    }
+    const profileBody = profile.status === 200 ? profile.body : null;
+    if (config.status === 403) {
+        return {
+            access: "forbidden",
+            adminConfig: null,
+            adminConfigStatus: 403,
+            profile: profileBody,
+            session: snapshot,
+        };
+    }
+    return {
+        access: "admin",
+        adminConfig: config.body,
+        adminConfigStatus: 200,
+        profile: profileBody,
+        session: snapshot,
+    };
+};
+/**
+ * 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.
+ */
+const createAdminSpaGate = (options) => {
+    const { appConfig, handler } = options;
+    const basePath = options.basePath === "/" ? "" : options.basePath;
+    const render = (req, res, next, payload) => {
+        const scope = {
+            adminConfig: payload.adminConfig,
+            adminConfigStatus: payload.adminConfigStatus,
+            appConfig,
+            basePath: options.basePath,
+            profile: payload.profile,
+            session: payload.session,
+        };
+        (0, serverContext_1.runInAdminSpaRequest)(scope, () => handler(req, res, next));
+    };
+    // Every decision depends on the visitor's session, so no redirect may be cached or shared.
+    const redirect = (res, location) => {
+        res.set("Cache-Control", "no-store, private").redirect(302, location);
+    };
+    const deny = (res, status) => {
+        res
+            .status(status)
+            .set("Cache-Control", "no-store, private")
+            .json({ title: status === 401 ? "Unauthorized" : "Forbidden" });
+    };
+    return (req, res, next) => {
+        const normalized = new URL(canonicalizeEscapes(req.url), URL_BASE);
+        const classified = classify(req.method, normalized.pathname, basePath);
+        // Static paths are served by the static middleware mounted before the gate. A miss must
+        // never reach the page renderer, which would render it as a route (`/assets/Todo` matches
+        // `[model]/[id]`) without an access decision.
+        if (classified.kind === "outside" || classified.kind === "static") {
+            next();
+            return;
+        }
+        // Hand the renderer exactly the path the gate decided on.
+        req.url = `${normalized.pathname}${normalized.search}`;
+        // The admin SPA serves only reads: a write never reaches the renderer or a loader.
+        if (classified.kind === "write") {
+            next();
+            return;
+        }
+        const decide = async () => {
+            const payload = req.user ? await loadShellPayload(req, options) : ANONYMOUS;
+            const { route } = classified;
+            const isPublic = PUBLIC_ROUTES.has(route);
+            // Signed-in-only routes (MCP OAuth consent) render for any signed-in user.
+            const isOpenToVisitor = isPublic || (payload.access !== "anonymous" && (0, signedInOnlyRoutes_1.isSignedInOnlyRoute)(route));
+            if (classified.kind === "loader") {
+                if (payload.access === "admin" || isOpenToVisitor) {
+                    render(req, res, next, payload);
+                    return;
+                }
+                deny(res, payload.access === "anonymous" ? 401 : 403);
+                return;
+            }
+            if (payload.access === "anonymous") {
+                if (route === "/login") {
+                    render(req, res, next, payload);
+                    return;
+                }
+                const search = req.url.includes("?") ? req.url.slice(req.url.indexOf("?")) : "";
+                const returnTo = encodeURIComponent(`${route}${search}`);
+                redirect(res, `${basePath}/login?returnTo=${returnTo}`);
+                return;
+            }
+            if (payload.access === "forbidden") {
+                // Like the client gate: a signed-in user on /login goes to a safe returnTo, which
+                // renders when signed-in-only (the MCP consent flow) and otherwise redirects again.
+                const forbiddenTarget = route === "/login"
+                    ? (0, returnTo_1.sanitizeReturnTo)(req.query.returnTo)
+                    : null;
+                if (forbiddenTarget) {
+                    redirect(res, `${basePath}${forbiddenTarget}`);
+                    return;
+                }
+                if (isOpenToVisitor) {
+                    render(req, res, next, payload);
+                    return;
+                }
+                redirect(res, `${basePath}/forbidden`);
+                return;
+            }
+            if (route === "/login") {
+                const target = (0, returnTo_1.sanitizeReturnTo)(req.query.returnTo);
+                redirect(res, `${basePath}${target ?? "/"}`);
+                return;
+            }
+            if (route === "/forbidden") {
+                redirect(res, `${basePath}/`);
+                return;
+            }
+            render(req, res, next, payload);
+        };
+        decide().catch((error) => {
+            if (!(error instanceof GateUnavailableError)) {
+                next(error);
+                return;
+            }
+            api_1.logger.warn(`Admin SPA gate failed closed for ${req.path}`, { reason: error.message });
+            res
+                .status(503)
+                .set("Cache-Control", "no-store, private")
+                .type("text")
+                .send("Admin SPA unavailable");
+        });
+    };
+};
+exports.createAdminSpaGate = createAdminSpaGate;

package/src/dist/returnTo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Accept a post-login destination only when it is an in-app path ("/oauth/consent?request=abc"):
+ * one leading `/`, no second `/` right after it, no backslash, whitespace or control character,
+ * and not the login page itself. Anything else (an absolute URL, a protocol-relative `//host`,
+ * `/\\host`, a relative path) is an open redirect and yields undefined. A repeated query
+ * parameter uses its first value. The server gate and the client share this one rule.
+ */
+export declare const sanitizeReturnTo: (value: unknown) => string | undefined;

package/src/dist/returnTo.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeReturnTo = void 0;
+// Any ASCII control character or whitespace; a valid in-app path never contains one.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+const UNSAFE_RETURN_TO_CHARS = /[\u0000-\u001f\u007f\s\\]/;
+/**
+ * Accept a post-login destination only when it is an in-app path ("/oauth/consent?request=abc"):
+ * one leading `/`, no second `/` right after it, no backslash, whitespace or control character,
+ * and not the login page itself. Anything else (an absolute URL, a protocol-relative `//host`,
+ * `/\\host`, a relative path) is an open redirect and yields undefined. A repeated query
+ * parameter uses its first value. The server gate and the client share this one rule.
+ */
+const sanitizeReturnTo = (value) => {
+    const candidate = Array.isArray(value) ? value[0] : value;
+    if (typeof candidate !== "string" || !candidate.startsWith("/") || candidate.startsWith("//")) {
+        return undefined;
+    }
+    if (UNSAFE_RETURN_TO_CHARS.test(candidate) || candidate.startsWith("/login")) {
+        return undefined;
+    }
+    return candidate;
+};
+exports.sanitizeReturnTo = sanitizeReturnTo;

package/src/dist/routesManifest.d.ts

@@ -0,0 +1,35 @@
+interface RawRoute {
+    page: string;
+    namedRegex: string;
+    [key: string]: unknown;
+}
+/** The parts of an Expo server build's `_expo/routes.json` the serve plugin reads. */
+export interface RawRoutesManifest {
+    assets?: {
+        js?: string[];
+    };
+    htmlRoutes?: RawRoute[];
+    apiRoutes?: RawRoute[];
+    notFoundRoutes?: RawRoute[];
+    redirects?: RawRoute[];
+    rewrites?: RawRoute[];
+    pageHeaders?: RawRoute[];
+    [key: string]: unknown;
+}
+/** Read `_expo/routes.json` from a server build, or undefined when there is no build. */
+export declare const readRoutesManifest: (serverDir: string) => RawRoutesManifest | undefined;
+/**
+ * The baseUrl baked into the build, read from its asset URLs (`/console/_expo/static/...`).
+ * "" for a bundle built for the site root.
+ */
+export declare const bakedBaseUrlOf: (manifest: RawRoutesManifest) => string;
+/**
+ * Prepare the manifest the way expo-server's environment does (regex strings become
+ * `RegExp`s), with HTML routes ordered by specificity. Expo 58 exports `routes.json`
+ * unsorted, and expo-server takes the first regex match, so `/[model]` would shadow `/login`
+ * and render it without its loader data. The router itself already prefers static routes.
+ */
+export declare const prepareRoutesManifest: (raw: RawRoutesManifest, { pageCacheControl }?: {
+    pageCacheControl?: string;
+}) => Record<string, unknown>;
+export {};

package/src/dist/routesManifest.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareRoutesManifest = exports.bakedBaseUrlOf = exports.readRoutesManifest = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const REGEX_LISTS = [
+    "htmlRoutes",
+    "apiRoutes",
+    "notFoundRoutes",
+    "redirects",
+    "rewrites",
+    "pageHeaders",
+];
+/** Read `_expo/routes.json` from a server build, or undefined when there is no build. */
+const readRoutesManifest = (serverDir) => {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(serverDir, "_expo", "routes.json"), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.readRoutesManifest = readRoutesManifest;
+/**
+ * The baseUrl baked into the build, read from its asset URLs (`/console/_expo/static/...`).
+ * "" for a bundle built for the site root.
+ */
+const bakedBaseUrlOf = (manifest) => {
+    const firstAsset = manifest.assets?.js?.[0] ?? "";
+    const index = firstAsset.indexOf("/_expo/");
+    return index > 0 ? firstAsset.slice(0, index) : "";
+};
+exports.bakedBaseUrlOf = bakedBaseUrlOf;
+/** Expo Router's match priority for one path segment: static, then dynamic, then catch-all. */
+const segmentRank = (segment) => {
+    if (segment.startsWith("[...")) {
+        return 2;
+    }
+    if (segment.startsWith("[")) {
+        return 1;
+    }
+    return 0;
+};
+const routeRanks = (page) => {
+    return page
+        .split("/")
+        .filter((segment) => segment !== "" && !(segment.startsWith("(") && segment.endsWith(")")))
+        .map(segmentRank);
+};
+/** Compare two routes segment by segment: the more specific route sorts first. */
+const compareSpecificity = (a, b) => {
+    const aRanks = routeRanks(a.page);
+    const bRanks = routeRanks(b.page);
+    const length = Math.min(aRanks.length, bRanks.length);
+    for (let index = 0; index < length; index++) {
+        const difference = (aRanks[index] ?? 0) - (bRanks[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
+/**
+ * Replace every `Cache-Control` in the manifest's `pageHeaders` rules. Expo exports a
+ * `no-store` rule for every loader response, and expo-server applies it after Express
+ * middleware, so the plugin's own header would be overwritten.
+ */
+const withCacheControl = (routes, cacheControl) => {
+    return routes.map((route) => {
+        const headers = route.headers;
+        if (!headers) {
+            return route;
+        }
+        const kept = Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== "cache-control"));
+        const hadCacheControl = Object.keys(kept).length !== Object.keys(headers).length;
+        return hadCacheControl ? { ...route, headers: { ...kept, "Cache-Control": cacheControl } } : route;
+    });
+};
+/**
+ * Prepare the manifest the way expo-server's environment does (regex strings become
+ * `RegExp`s), with HTML routes ordered by specificity. Expo 58 exports `routes.json`
+ * unsorted, and expo-server takes the first regex match, so `/[model]` would shadow `/login`
+ * and render it without its loader data. The router itself already prefers static routes.
+ */
+const prepareRoutesManifest = (raw, { pageCacheControl } = {}) => {
+    const prepared = { ...raw };
+    for (const list of REGEX_LISTS) {
+        const exported = raw[list];
+        const routes = list === "pageHeaders" && exported && pageCacheControl
+            ? withCacheControl(exported, pageCacheControl)
+            : exported;
+        if (!routes) {
+            // expo-server defaults every list except `pageHeaders` to empty.
+            if (list !== "pageHeaders") {
+                prepared[list] = [];
+            }
+            continue;
+        }
+        const ordered = list === "htmlRoutes" ? [...routes].sort(compareSpecificity) : routes;
+        prepared[list] = ordered.map((route) => ({ ...route, namedRegex: new RegExp(route.namedRegex) }));
+    }
+    return prepared;
+};
+exports.prepareRoutesManifest = prepareRoutesManifest;

package/src/dist/serve.d.ts

@@ -6,28 +6,49 @@ export interface AdminSpaServeOptions {
     basePath?: string;
     /** Runtime config served at `${basePath}/app-config.json`. Merged with defaults. */
     appConfig?: Partial<AdminSpaAppConfig>;
-    /** Override the directory the pre-built bundle is served from (used by tests/custom builds). */
+    /**
+     * Override the export root the bundle is served from: it holds `client/` (static files)
+     * and `server/` (the Expo server build). Used by tests, custom builds, and compiled binaries.
+     */
     distDir?: string;
     /**
      * In dev, proxy all SPA paths to a running `expo start --web` server, e.g.
      * "http://localhost:8083". Avoids re-running `expo export` per change.
      */
     devProxyTarget?: string;
+    /**
+     * Origin the server render fetches API data from, with the visitor's cookie. Default:
+     * `http://127.0.0.1:${PORT ?? 4000}`, this process. Never derived from `Host` or
+     * `X-Forwarded-*`, so a request cannot point the render at another host.
+     */
+    internalOrigin?: string;
+    /**
+     * API path prefixes a server render may fetch. Default: the admin API base path plus
+     * `/auth/me`, `/orgs`, `/jobs`, `/comms`, `/configuration`, and `/rbac`.
+     */
+    ssrApiPrefixes?: string[];
 }
 /**
+ * @deprecated The server-rendered build no longer serves a static index.html. Kept for
+ * consumers of the static-export API; it will be removed in the next major release.
+ *
  * Rewrite the absolute `/_expo/` and `/assets/` references emitted by Expo's static
  * web export so a single pre-built bundle works when mounted at any `basePath`.
  */
 export declare const rewriteIndexHtml: (rawIndex: string, basePath: string) => string;
 /**
+ * @deprecated `+html.tsx` now writes `window.__ADMIN_SPA_BASE__` into the server-rendered
+ * page. Kept for consumers of the static-export API; it will be removed in the next major.
+ *
  * Inject `window.__ADMIN_SPA_BASE__` so the SPA can build absolute URLs (e.g.
  * `${base}/app-config.json`) regardless of the current deep route. Inserted before
  * `</head>` so it runs before the bundle.
  */
 export declare const injectBaseGlobal: (html: string, basePath: string) => string;
 /**
- * Opt-in Express plugin that serves a pre-built admin SPA (Expo Router static export)
- * from the same Node process as a Terreno backend. Mounts at `/console` by default.
+ * Opt-in Express plugin that server-renders the pre-built admin SPA (Expo Router
+ * `web.output: "server"` export) from the same Node process as a Terreno backend. Mounts at
+ * `/console` by default; `basePath` must equal the baseUrl the bundle was built with.
  *
  * @example
  * ```typescript

package/src/dist/serve.js

@@ -4,16 +4,42 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminSpaServeApp = exports.injectBaseGlobal = exports.rewriteIndexHtml = void 0;
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const api_1 = require("@terreno/api");
-const express_1 = __importDefault(require("express"));
+const express_1 = require("expo-server/adapter/express");
+const express_2 = __importDefault(require("express"));
 const appConfig_1 = require("./appConfig");
-// Compiled (CommonJS) file lives at src/dist/serve.js; the pre-built bundle lives at
-// admin-spa/dist. `__dirname` is the CommonJS module-directory global.
+const gate_1 = require("./gate");
+const routesManifest_1 = require("./routesManifest");
+const serverContext_1 = require("./serverContext");
+// Compiled (CommonJS) file lives at src/dist/serve.js; the export root (`client/` +
+// `server/`) lives at admin-spa/dist. `__dirname` is the CommonJS module-directory global.
 const DIST_DIR = node_path_1.default.resolve(__dirname, "../../dist");
 const NO_STORE = "no-store";
+/** Server-rendered pages and loader data can hold PHI: never cached, never shared. */
+const NO_STORE_PRIVATE = "no-store, private";
+/** API prefixes a server render may fetch, besides the admin API base path. */
+const DEFAULT_SSR_API_PREFIXES = [
+    "/auth/me",
+    "/orgs",
+    "/jobs",
+    "/comms",
+    "/configuration",
+    "/rbac",
+];
 /**
+ * The default SSR allowlist: the admin API base, the fixed API roots, and the RBAC root, which
+ * mounts at the API root (`/internal/admin` puts it at `/internal/rbac`, as `useAdminRoles` does).
+ */
+const defaultSsrApiPrefixes = (adminApiBasePath = "/admin") => {
+    const rbacPrefix = `${adminApiBasePath.replace(/\/admin\/?$/, "")}/rbac`;
+    const prefixes = [adminApiBasePath, ...DEFAULT_SSR_API_PREFIXES];
+    return prefixes.includes(rbacPrefix) ? prefixes : [...prefixes, rbacPrefix];
+};
+/**
+ * @deprecated The server-rendered build no longer serves a static index.html. Kept for
+ * consumers of the static-export API; it will be removed in the next major release.
+ *
  * Rewrite the absolute `/_expo/` and `/assets/` references emitted by Expo's static
  * web export so a single pre-built bundle works when mounted at any `basePath`.
  */
@@ -26,6 +52,9 @@ const rewriteIndexHtml = (rawIndex, basePath) => {
 };
 exports.rewriteIndexHtml = rewriteIndexHtml;
 /**
+ * @deprecated `+html.tsx` now writes `window.__ADMIN_SPA_BASE__` into the server-rendered
+ * page. Kept for consumers of the static-export API; it will be removed in the next major.
+ *
  * Inject `window.__ADMIN_SPA_BASE__` so the SPA can build absolute URLs (e.g.
  * `${base}/app-config.json`) regardless of the current deep route. Inserted before
  * `</head>` so it runs before the bundle.
@@ -39,8 +68,9 @@ const injectBaseGlobal = (html, basePath) => {
 };
 exports.injectBaseGlobal = injectBaseGlobal;
 /**
- * Opt-in Express plugin that serves a pre-built admin SPA (Expo Router static export)
- * from the same Node process as a Terreno backend. Mounts at `/console` by default.
+ * Opt-in Express plugin that server-renders the pre-built admin SPA (Expo Router
+ * `web.output: "server"` export) from the same Node process as a Terreno backend. Mounts at
+ * `/console` by default; `basePath` must equal the baseUrl the bundle was built with.
  *
  * @example
  * ```typescript
@@ -78,31 +108,96 @@ class AdminSpaServeApp {
             api_1.logger.info(`Admin SPA dev-proxied to ${this.opts.devProxyTarget} at ${basePath}/`);
             return;
         }
-        // Read index.html once and rewrite absolute asset refs to the mounted basePath.
-        const indexHtmlPath = node_path_1.default.join(distDir, "index.html");
-        let indexHtml = "";
-        try {
-            indexHtml = (0, exports.injectBaseGlobal)((0, exports.rewriteIndexHtml)(node_fs_1.default.readFileSync(indexHtmlPath, "utf-8"), basePath), basePath);
-        }
-        catch {
-            api_1.logger.warn(`Admin SPA: no pre-built bundle found at ${indexHtmlPath}. ` +
-                "Run `bun run --filter '@terreno/admin-spa' build:web` or set devProxyTarget.");
-        }
-        // 1. Hashed asset directories — long cache, immutable.
+        const context = {
+            appConfig,
+            basePath,
+            internalOrigin: this.opts.internalOrigin ?? `http://127.0.0.1:${process.env.PORT ?? 4000}`,
+            ssrApiPrefixes: this.opts.ssrApiPrefixes ?? defaultSsrApiPrefixes(appConfig.adminApiBasePath),
+            warn: (message, meta) => {
+                api_1.logger.warn(message, meta);
+            },
+        };
+        (0, serverContext_1.publishAdminSpaServerContext)(context);
+        // 1. Hashed client asset directories: long cache, immutable.
+        const clientDir = node_path_1.default.join(distDir, "client");
         const staticOpts = { immutable: true, maxAge: "365d" };
-        app.use(`${basePath}/_expo`, express_1.default.static(node_path_1.default.join(distDir, "_expo"), staticOpts));
-        app.use(`${basePath}/assets`, express_1.default.static(node_path_1.default.join(distDir, "assets"), staticOpts));
-        // 2. Runtime config — never cached.
+        app.use(`${basePath}/_expo`, express_2.default.static(node_path_1.default.join(clientDir, "_expo"), staticOpts));
+        app.use(`${basePath}/assets`, express_2.default.static(node_path_1.default.join(clientDir, "assets"), staticOpts));
+        // 2. Runtime config, never cached.
         app.get(`${basePath}/app-config.json`, (_req, res) => {
             res.set("Cache-Control", NO_STORE).json(appConfig);
         });
-        // 3. SPA fallback. Two registrations: bare basePath (no trailing slash) AND splat,
-        // matching the `/*name` Express 5 convention used elsewhere in the repo.
-        const serveSpa = (_req, res) => {
-            res.set("Cache-Control", NO_STORE).type("html").send(indexHtml);
+        // 3. Server render. Without a server build, answer 503 instead of crashing the backend.
+        const serverDir = node_path_1.default.join(distDir, "server");
+        const rawManifest = (0, routesManifest_1.readRoutesManifest)(serverDir);
+        if (!rawManifest) {
+            api_1.logger.warn(`Admin SPA: no server build found at ${serverDir}. ` +
+                "Run `bun run --filter '@terreno/admin-spa' build:web` or set devProxyTarget.");
+            const unavailable = (_req, res) => {
+                res.status(503).set("Cache-Control", NO_STORE).type("text").send("Admin SPA unavailable");
+            };
+            app.get(basePath, unavailable);
+            app.get(`${basePath}/*splat`, unavailable);
+            return;
+        }
+        const bakedBaseUrl = (0, routesManifest_1.bakedBaseUrlOf)(rawManifest);
+        if (bakedBaseUrl !== basePath) {
+            throw new Error(`Admin SPA basePath "${basePath}" does not match the bundle's baseUrl "${bakedBaseUrl}"`);
+        }
+        const manifest = (0, routesManifest_1.prepareRoutesManifest)(rawManifest, {
+            pageCacheControl: NO_STORE_PRIVATE,
+        });
+        const handler = (0, express_1.createRequestHandler)({ build: serverDir }, { getRoutesManifest: async () => manifest });
+        // Every server render runs in a request scope, so a render reads only its own request's
+        // data. Middleware that set a richer scope earlier (the auth gate) keeps it.
+        // A failed render or loader logs the route path and the error only: never the query string
+        // or response data, which can hold PHI.
+        const renderError = (error, req, res) => {
+            api_1.logger.error(`Admin SPA render failed for ${req.path}`, {
+                error: error instanceof Error ? error.message : String(error),
+                path: req.path,
+            });
+            if (res.headersSent) {
+                res.end();
+                return;
+            }
+            res.status(500).set("Cache-Control", NO_STORE_PRIVATE).type("text").send("Admin SPA error");
+        };
+        const mountPrefix = basePath === "/" ? "" : basePath;
+        // Runs Expo's handler in a request scope (the gate's, or a base one) and catches its errors
+        // here rather than in a root error middleware, which would also see the API's errors.
+        const renderPage = (req, res, next) => {
+            res.set("Cache-Control", NO_STORE_PRIVATE);
+            // Expo matches routes without the mount path; root loader requests have none to strip.
+            if (mountPrefix && (req.path === mountPrefix || req.path.startsWith(`${mountPrefix}/`))) {
+                const rest = req.url.slice(mountPrefix.length);
+                req.url = rest.startsWith("/") ? rest : `/${rest}`;
+            }
+            const run = () => {
+                handler(req, res, (error) => {
+                    if (error) {
+                        renderError(error, req, res);
+                        return;
+                    }
+                    next();
+                });
+            };
+            if ((0, serverContext_1.getAdminSpaRequest)()) {
+                run();
+                return;
+            }
+            (0, serverContext_1.runInAdminSpaRequest)({ appConfig, basePath }, run);
         };
-        app.get(basePath, serveSpa);
-        app.get(`${basePath}/*splat`, serveSpa);
+        // The gate decides access before anything renders, for pages under basePath and for loader
+        // data, which Expo 58's client fetches from the site root regardless of the baked baseUrl
+        // (D11 in the SSR plan).
+        app.use((0, gate_1.createAdminSpaGate)({
+            adminApiBasePath: appConfig.adminApiBasePath ?? "/admin",
+            appConfig,
+            basePath,
+            handler: renderPage,
+            internalOrigin: context.internalOrigin,
+        }));
         api_1.logger.info(`Admin SPA mounted at ${basePath}/`);
     }
 }

package/src/dist/serverContext.d.ts

@@ -0,0 +1,61 @@
+import type { AdminSpaAppConfig } from "./appConfig";
+/** What the serve plugin publishes for `render.js`, `+html.tsx`, and route loaders. */
+export interface AdminSpaServerContext {
+    appConfig: AdminSpaAppConfig;
+    basePath: string;
+    /** Origin loopback SSR fetches go to. Never built from `Host` or `X-Forwarded-*`. */
+    internalOrigin: string;
+    /** API path prefixes a server render may fetch; anything else is rejected. */
+    ssrApiPrefixes: string[];
+    /**
+     * The host's warning logger (`logger.warn` from `@terreno/api`). The render bundle stubs
+     * `@terreno/api`, so server code reaches the host's log pipeline through this.
+     */
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * What one request's server render may read: set by Express before the Expo handler runs,
+ * visible to that request's render and loaders only.
+ */
+export interface AdminSpaRequestScope {
+    appConfig: AdminSpaAppConfig;
+    basePath: string;
+    /** The Better Auth session snapshot, or null for an anonymous visitor. Set by the gate. */
+    session?: AdminSpaSessionSnapshot | null;
+    /** The visitor's `GET /auth/me` body, or null when anonymous. Set by the gate. */
+    profile?: unknown;
+    /** The `GET {adminApiBasePath}/config` body for an admin, else null. Set by the gate. */
+    adminConfig?: unknown;
+    /** Status of the admin config read (200 admin, 403 forbidden), or null when not read. */
+    adminConfigStatus?: number | null;
+}
+/** The Better Auth session as the client's session source reads it. */
+export interface AdminSpaSessionSnapshot {
+    userId: string;
+    user: unknown;
+}
+/** Publish the server context. One admin SPA per process: a later call replaces it. */
+export declare const publishAdminSpaServerContext: (context: AdminSpaServerContext) => void;
+/** Read the published server context, or undefined before the plugin registers. */
+export declare const getAdminSpaServerContext: () => AdminSpaServerContext | undefined;
+/**
+ * Warn from server render code through the host's logger, or `console.warn` before the plugin
+ * has published one. Callers pass paths and reasons only: never a query string, a cookie or a
+ * response body.
+ */
+export declare const warnAdminSpaServer: (message: string, meta?: Record<string, unknown>) => void;
+/**
+ * True while rendering on the server: there is no browser `window`, and the serve plugin has
+ * published its context in this process. A server render reads what it was given and never
+ * starts watchers, sockets or requests of its own.
+ */
+export declare const isAdminSpaServerRender: () => boolean;
+/** Run `fn` with `scope` as the current request scope (server only). */
+export declare const runInAdminSpaRequest: <T>(scope: AdminSpaRequestScope, fn: () => T) => T;
+/** The current request's scope, or undefined outside a request (and always in the browser). */
+export declare const getAdminSpaRequest: () => AdminSpaRequestScope | undefined;
+/**
+ * Serialize a value for embedding in HTML (an inline `<script>` or a JSON script blob): JSON
+ * with every character that could close the script or break a JS string literal escaped.
+ */
+export declare const serializeForHtml: (value: unknown) => string;

package/src/dist/serverContext.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeForHtml = exports.getAdminSpaRequest = exports.runInAdminSpaRequest = exports.isAdminSpaServerRender = exports.warnAdminSpaServer = exports.getAdminSpaServerContext = exports.publishAdminSpaServerContext = void 0;
+/**
+ * Key of the process global the serve plugin publishes for the server render. The Expo
+ * `render.js` bundle and its loaders run in the same process as Express but are bundled
+ * separately, so a process global is the one place both can read. `Symbol.for` keeps the
+ * key identical across the two bundles.
+ */
+const ADMIN_SPA_SERVER_CONTEXT_KEY = Symbol.for("terreno.adminSpa.server");
+/** Key of the one per-request `AsyncLocalStorage`, shared by every bundle in the process. */
+const ADMIN_SPA_REQUEST_STORE_KEY = Symbol.for("terreno.adminSpa.requestStore");
+/** Publish the server context. One admin SPA per process: a later call replaces it. */
+const publishAdminSpaServerContext = (context) => {
+    globalThis[ADMIN_SPA_SERVER_CONTEXT_KEY] = context;
+};
+exports.publishAdminSpaServerContext = publishAdminSpaServerContext;
+/** Read the published server context, or undefined before the plugin registers. */
+const getAdminSpaServerContext = () => {
+    return globalThis[ADMIN_SPA_SERVER_CONTEXT_KEY];
+};
+exports.getAdminSpaServerContext = getAdminSpaServerContext;
+/**
+ * Warn from server render code through the host's logger, or `console.warn` before the plugin
+ * has published one. Callers pass paths and reasons only: never a query string, a cookie or a
+ * response body.
+ */
+const warnAdminSpaServer = (message, meta) => {
+    const warn = (0, exports.getAdminSpaServerContext)()?.warn;
+    if (warn) {
+        warn(message, meta);
+        return;
+    }
+    if (meta) {
+        console.warn(message, meta);
+        return;
+    }
+    console.warn(message);
+};
+exports.warnAdminSpaServer = warnAdminSpaServer;
+/**
+ * True while rendering on the server: there is no browser `window`, and the serve plugin has
+ * published its context in this process. A server render reads what it was given and never
+ * starts watchers, sockets or requests of its own.
+ */
+const isAdminSpaServerRender = () => {
+    return !("window" in globalThis) && (0, exports.getAdminSpaServerContext)() !== undefined;
+};
+exports.isAdminSpaServerRender = isAdminSpaServerRender;
+/**
+ * The process-wide request store, created on first use. `process.getBuiltinModule` keeps
+ * `node:async_hooks` out of the static import graph, because this module is also bundled for
+ * the browser, where there is no request store.
+ */
+const requestStore = () => {
+    const global = globalThis;
+    const existing = global[ADMIN_SPA_REQUEST_STORE_KEY];
+    if (existing) {
+        return existing;
+    }
+    const asyncHooks = process.getBuiltinModule("node:async_hooks");
+    const store = new asyncHooks.AsyncLocalStorage();
+    global[ADMIN_SPA_REQUEST_STORE_KEY] = store;
+    return store;
+};
+/** Run `fn` with `scope` as the current request scope (server only). */
+const runInAdminSpaRequest = (scope, fn) => {
+    return requestStore().run(scope, fn);
+};
+exports.runInAdminSpaRequest = runInAdminSpaRequest;
+/** The current request's scope, or undefined outside a request (and always in the browser). */
+const getAdminSpaRequest = () => {
+    return globalThis[ADMIN_SPA_REQUEST_STORE_KEY]?.getStore();
+};
+exports.getAdminSpaRequest = getAdminSpaRequest;
+/**
+ * Serialize a value for embedding in HTML (an inline `<script>` or a JSON script blob): JSON
+ * with every character that could close the script or break a JS string literal escaped.
+ */
+const serializeForHtml = (value) => {
+    return JSON.stringify(value)
+        .replaceAll("<", "\\u003c")
+        .replaceAll(">", "\\u003e")
+        .replaceAll("&", "\\u0026")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+};
+exports.serializeForHtml = serializeForHtml;

package/src/dist/signedInOnlyRoutes.d.ts

@@ -0,0 +1,2 @@
+/** Whether a route path (`/oauth/consent`, trailing slashes ignored) is signed-in-only. */
+export declare const isSignedInOnlyRoute: (pathname: string) => boolean;

package/src/dist/signedInOnlyRoutes.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSignedInOnlyRoute = void 0;
+/** Routes any signed-in user may open; they skip the admin check and admin bootstrapping. */
+const SIGNED_IN_ONLY_ROUTES = ["/oauth/consent"];
+/** Whether a route path (`/oauth/consent`, trailing slashes ignored) is signed-in-only. */
+const isSignedInOnlyRoute = (pathname) => {
+    return SIGNED_IN_ONLY_ROUTES.includes(pathname.replace(/\/+$/, "") || "/");
+};
+exports.isSignedInOnlyRoute = isSignedInOnlyRoute;