@ultimat3/admin 27.0.0 → 27.1.0

package/CLAUDE.md

@@ -11,7 +11,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **The MCP caller is the ambient actor for the whole call, tenant included.** `mcp.ts` wraps `callAdminTool` in a child context (a fresh root one over stdio); `resolveToken` and `adminActorOf` both carry `orgId`. Pinned in `mcp-context.test.ts`, `mcp-tenant.test.ts`.
 - **`defineAdmin({ entities, db })` is a served admin; a host writes nothing.** `routes.ts` gives EVERY route a screen (`screens.ts` — a `Record<AdminView, …>`, so a new view cannot mount with nothing behind it) and `AdminRouteConfig.respond(request)` is the only way in: GET or a posted form in, `{ status, body }` or a 303 out. `repo-entity.ts` is the ONE adapter from the typed handle to `AdminRepo`; it adds no predicate (tenancy, soft delete, sealing and invariants are the handle's) and never spreads a row. A resource with neither a table in `db` nor a `repo:` is `X_ADMIN_REPO_UNBOUND` at `defineAdmin`. Pinned in `mounted-screens.test.ts`, `repo-entity.test.ts`, `admin-bind.test.ts`.
 - **A screen's guard is composed, never written.** A resource screen asks `crud.ts` FIRST and renders what it answered — only it holds the row a row-level rule reads. Every other screen (a `pages:` entry, dashboard, jobs, audit, search) is built through `guardedScreen()` (`screen-frame.tsx`): `decideAll` over the route's permissions, the refusal audited (`auditRefusal`), answered 403. `pages.ts` composes `[admin:read, …declared]`; `AdminPageProps.ctx` is required by the type; an empty permission list is `X_ADMIN_PAGE_UNGUARDED` at `defineAdmin`.
-- **No screen ships a script.** Every route is `ssr` + `hydrate: 'never'`, so a control is a link or a native form: `<Pagination hrefFor>`, `<DataTable sortHrefFor>`, scope tabs as links, the filter bar one GET form, a form posted at the URL that rendered it, an action posted at its ROW's URL (`_operation`). `form-decode.ts` is the one place posted strings become typed input, per widget — an empty box of a typed widget (money, number, instant, JSON) is `null`, never `''`.
+- **No screen ships a script; an app file that CLAIMED its route may** (`claimAdminRoute`: a `pages:` entry or the dashboard; `load` = `screenFor`, `frame: 'none'`). Only a config `claims.ts` issued for that path passes `claimable`, else `X_ROUTE_DUPLICATE`. Every admin route is `ssr` + `hydrate: 'never'`, so a control is a link or a native form: `<Pagination hrefFor>`, `<DataTable sortHrefFor>`, scope tabs as links, the filter bar one GET form, a form posted at the URL that rendered it, an action posted at its ROW's URL (`_operation`). `form-decode.ts` is the one place posted strings become typed input, per widget — an empty box of a typed widget (money, number, instant, JSON) is `null`, never `''`.
 - **A list's state is its URL, and a parameter the resource does not derive is REFUSED.** `list-request.ts` is the one parser and builder — `?cursor=`, `?sort=<field>:<asc|desc>`, `?scope=<name>` (`*` = none, not even the default; undeclarable), `?f.<field>[.<op>]=<value>` (repeat for `in`; empty = absent). `list-filters.ts` owns the operators per filter shape and the ONE validator (`checkedFilter`) the URL and the MCP list tool's `where` both pass. Unknown field, operator, sort, scope or parameter, or a value that is not the column's type: `X_ADMIN_FILTER_INVALID`, a 400 naming what the list answers — never the unfiltered list.
 - **One composition of predicates** (`list-scope.ts`): row scope (`rows`), then scope, then filters. Every read of a resource builds its `where` there, and every read of ONE row is `findRow` — never `repo.find` from a screen, `crud.ts` or `mcp.ts` — so a row outside `rows(actor)` is "not found" on list, search, detail, edit, action, lookup, labels and MCP alike (`row-scope.test.ts`). App-declared predicates (`scopes`, `rows`) pass `declaredFilters`: any column, never a sealed one.
 - **A widget never reads a row.** What a page shows of the resources it references is read ONCE per target by `relations.ts` (`relationDataFor`: one statement, two for a picked target over `LOOKUP_SELECT_MAX`) and handed down as `WidgetContext.labelFor` / `optionsFor` / `lookupHref`. A target the actor may not list is an id with no name. `list-relations.test.ts` asserts the statement count at the driver. The picker is server-rendered: a `<select>` for a small target, else an id box + the target's lookup screen (`/admin/<resource>/lookup`, `screen-lookup.tsx`, `return` held to the admin's own paths).
@@ -29,13 +29,12 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describePages()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
 - **The admin's stylesheets are claimed for `app/`** (`stylesheet-scope.ts`, `claimStylesheets`). `stylesheet-scope.test.ts`.
 - **Importing this package declares NO permission.** `defineAdmin()` calls `declareAdminPermissions`, which registers `ADMIN_PERMISSIONS` plus what the mount derives (`policy-bridge.test.ts`).
-- **One bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes`; `mcp.ts` → `defineAppMcp`; `dev/data.ts` → introspection, dynamically. A test declares its own fixtures' permissions and calls `defineAdmin()` in `beforeAll`, never at module scope.
+- **One bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes` (+ `claim-route.ts`, the `@ultimat3/http` bridge); `mcp.ts` → `defineAppMcp`; `dev/data.ts` → introspection, dynamically. A test declares its own fixtures' permissions and calls `defineAdmin()` in `beforeAll`, never at module scope.
 - **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
 - **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
 - **A deliberate query loop declares itself** — `expectedQueryLoop()` from `@ultimat3/db`, with a `reason` (`search.ts`, `batch.ts`, `relations.ts`). Never a comment pragma, never an exempt list; an undeclared loop is an N+1.
 - **The timeline panel renders the detector's verdicts** (`DevSources.statementLoops()`), never a second count; none wired is `null`, never `[]`.
 - **This catalog is the framework's one opt-OUT MCP surface, deliberately**: `mcp-tools.ts` does not call `isMcpExposed` — every tool is already gated on an admin permission. `mcp: { expose: false }` withdraws one. A *second* exception anywhere is the bug.
-- **`dev/panel-db.ts`'s `sanitize` decides "did they type a statement", not "is it safe"** — never cite it as a security property.
 - **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider — in `panel-live`, `panel-db`, `panel-timeline` and `panel-cache` alike (`dev/panel-degrade.test.ts`). Everything else reaches `panelPayload`, which renders its code and its fix.
 - **What an entity does not declare, the admin does not invent.** `sensitive`, a fixed `currency` and `labelField` come from `AdminResourceOptions` or they are absent. Same rule for a URL: the reference widget links through `WidgetContext.hrefFor` or renders plain text — the route table is `AdminApp`'s.
 - **`panel-db.ts` executes the string `assertReadOnlyQuery` RETURNS**, never the textarea's bytes (`ReadOnlyVerdict`).
@@ -82,6 +81,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `admin.ts` / `mounts.ts` / `actor.ts` | `defineAdmin` → resources, repos, nav, route table, audit, authz / the registry a host mounts from / the default actor |
 | `pages.ts` / `page-guard.tsx` | a `pages:` entry → route + nav item (pure) / the refusal a screen renders and audits |
 | `route-config.ts` / `routes.ts` / `screens.ts` | the render bridge: `defineRoute`, `registerMountedRoutes` / route → screen, `adminRouteMatch` / view → screen |
+| `claim-route.ts` / `claims.ts` | an app file serving a route in the catch-all's place / the configs issued, by identity |
 | `screen-frame.tsx` / `screen-resource.tsx` / `screen-lookup.tsx` / `screen-home.tsx` / `screen-system.tsx` | request/response shape, shell, `guardedScreen` (a body's refused URL is a 400), `widgetContextOf` / list·detail·create·edit and their writes / the picker / dashboard / audit·search |
 | `list-request.ts` / `list-filters.ts` / `list-scope.ts` | URL ⇄ list request / operators per shape + the validator / row scope → scope → filters, `findRow`, `scopeCounts` |
 | `list.tsx` / `list-filter-bar.tsx` / `list-scope-tabs.tsx` / `renderers.tsx` | the list view / one GET form / tabs as links / computed cells |

package/README.md

@@ -91,7 +91,7 @@ admin.
 
 ### No script
 
-Every route is `ssr`, `hydrate: 'never'`, and every control is a link or a native form: the pager
+Every route is `ssr`, `hydrate: 'never'` (unless an app file claimed it — Custom pages, below), and every control is a link or a native form: the pager
 is `<Pagination hrefFor>`, a sort header is a link, scope tabs are links, the filter bar is one
 GET form, a form posts at the URL that rendered it and a refused one comes back 422 with what was
 typed. A write that worked is a 303. Every admin document is `noindex, nofollow`, and carries no
@@ -377,6 +377,15 @@ that shadows a generated screen throws `X_ADMIN_PAGE_PATH_INVALID` the same way.
 Custom pages are `render: 'ssr'`, `hydrate: 'never'`: the guard runs on the server, so there is
 nothing to ship and nothing to decide twice. A refused one answers 403.
 
+**In your own shell, with an island: claim the route.** A `page.tsx` at the page's path whose
+config is `claimAdminRoute(admin, path, { load?, hydrate?, budget?, navigation? })` serves it in
+the catch-all's place — a file route, so its islands hydrate. The claim keeps the gate, `meta` and
+a `load` that answers through the same screen (`frame: 'none'`, no `AdminLayout`); the page
+component renders `data.body` (decided: the page or the refusal) inside the app's shell, beside
+`data.nav` and `data.app` (what `load` returned). Only a `pages:` entry or the dashboard; only the
+config issued for that path (else `X_ROUTE_DUPLICATE`). [Admin Dashboard → An admin page in your
+own shell](https://github.com/developerz-ai/ultimate/wiki/Admin-Dashboard#an-admin-page-in-your-own-shell).
+
 ### Splitting the admin across files
 
 `defineAdmin` takes **plain values** — `entities`, `db`, `resources`, `actions`, `jobs`, `pages`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "27.0.0",
+  "version": "27.1.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -34,20 +34,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.0.0",
-    "@ultimat3/ai": "27.0.0",
-    "@ultimat3/cache": "27.0.0",
-    "@ultimat3/core": "27.0.0",
-    "@ultimat3/db": "27.0.0",
-    "@ultimat3/entity": "27.0.0",
-    "@ultimat3/i18n": "27.0.0",
-    "@ultimat3/jobs": "27.0.0",
-    "@ultimat3/mcp": "27.0.0",
-    "@ultimat3/money": "27.0.0",
-    "@ultimat3/policy": "27.0.0",
-    "@ultimat3/query": "27.0.0",
-    "@ultimat3/render": "27.0.0",
-    "@ultimat3/schema": "27.0.0",
-    "@ultimat3/ui": "27.0.0"
+    "@ultimat3/action": "27.1.0",
+    "@ultimat3/ai": "27.1.0",
+    "@ultimat3/cache": "27.1.0",
+    "@ultimat3/core": "27.1.0",
+    "@ultimat3/db": "27.1.0",
+    "@ultimat3/entity": "27.1.0",
+    "@ultimat3/http": "27.1.0",
+    "@ultimat3/i18n": "27.1.0",
+    "@ultimat3/jobs": "27.1.0",
+    "@ultimat3/mcp": "27.1.0",
+    "@ultimat3/money": "27.1.0",
+    "@ultimat3/policy": "27.1.0",
+    "@ultimat3/query": "27.1.0",
+    "@ultimat3/render": "27.1.0",
+    "@ultimat3/schema": "27.1.0",
+    "@ultimat3/ui": "27.1.0"
   }
 }

package/src/claim-route.ts

@@ -0,0 +1,146 @@
+// `claimAdminRoute()` — an app FILE serves one admin path in the catch-all's place, so the page
+// keeps the app's own shell and its islands (`hydrate`, budget and island bundle are a file
+// route's). The guard is not the app's: the route's gate, its `meta`, and a `load` that answers
+// through the SAME screen the catch-all serves (`screenFor`), unframed. `claims.ts` records the
+// config issued, and the route table accepts no other on that path.
+
+import { type HydrateStrategy, hasContext, isUltimateError } from '@ultimat3/core';
+import { setRedirect, useRequestHeaders } from '@ultimat3/http';
+import {
+  defineRoute,
+  type RouteBudget,
+  type RouteConfig,
+  type RouteNavigationMode,
+  routeStatusOf,
+  withStatus,
+} from '@ultimat3/render';
+import type { JSX } from 'solid-js';
+import type { AdminApp, AdminView } from './admin';
+import { issueClaim } from './claims';
+import type { CrudCtx } from './crud';
+import { AdminPagePathInvalidError } from './errors';
+import type { NavGroup } from './nav';
+import { adminRouteGuard, adminRouteMeta } from './route-config';
+import { screenFor } from './screens';
+
+/** What the app's own `load` is handed — called for every visitor the screen answered. */
+export interface AdminClaimLoadArgs {
+  readonly ctx: CrudCtx;
+  readonly params: Readonly<Record<string, string>>;
+  readonly url: string;
+  /** The body is the refusal (403), which carries its own `<h1>`. */
+  readonly denied: boolean;
+}
+
+export interface ClaimAdminRouteOptions<TApp> {
+  /** Absent: derived from the islands declared above the call, as for any route. */
+  readonly hydrate?: HydrateStrategy;
+  readonly budget?: RouteBudget;
+  readonly navigation?: RouteNavigationMode;
+  /**
+   * The app's half of the page data — its shell's role, locale and enrolment flag; a claimed
+   * dashboard's own figures. Runs AFTER the screen decided, the refused included: when `denied`
+   * it may read the visitor, never what the page guards. Answering `withStatus(404, …)` sets the
+   * page's status when the screen answered 200.
+   */
+  readonly load?: (args: AdminClaimLoadArgs) => TApp | Promise<TApp>;
+}
+
+/** What the claimed route's `load` hands the app's page component. */
+export interface AdminClaimData<TApp = undefined> {
+  /** The screen's body, decided and unframed: the page, or the refusal naming the permission. */
+  readonly body: JSX.Element;
+  readonly status: number;
+  readonly denied: boolean;
+  /** The route's title key; the body of a refusal carries its own heading. */
+  readonly titleKey: string;
+  /** The nav this actor may see — the admin's `navFor`. */
+  readonly nav: readonly NavGroup[];
+  /** What `options.load` returned; `undefined` without one. */
+  readonly app: TApp;
+}
+
+/**
+ * A `pages:` entry and the dashboard only. A generated screen posts its forms back to its own URL
+ * and re-renders a refused write there — in the admin's layout, from the catch-all — so a claim
+ * would split one screen across two shells.
+ */
+const CLAIMABLE: ReadonlySet<AdminView> = new Set<AdminView>(['page', 'dashboard']);
+
+/**
+ * The route config for the app file at `path` (the table's full path, base included). Call it
+ * BELOW the module's `island()` declarations, as `export const config = claimAdminRoute(…)`: its
+ * `defineRoute` drains them, which is how the page hydrates.
+ */
+export function claimAdminRoute<TApp = undefined>(
+  admin: AdminApp,
+  path: string,
+  options: ClaimAdminRouteOptions<TApp> = {},
+): RouteConfig<AdminClaimData<TApp>> {
+  const route = admin.routes.find((candidate) => candidate.path === path);
+  if (route === undefined) {
+    throw new AdminPagePathInvalidError({
+      path,
+      cause: 'is not a route this admin declares',
+      fix: `claimAdminRoute(admin, '<path>') with one of ${claimablePaths(admin)} — or add { path, titleKey, permissions, component } to pages: on defineAdmin()`,
+    });
+  }
+  if (!CLAIMABLE.has(route.view)) {
+    throw new AdminPagePathInvalidError({
+      path,
+      cause: `is the generated ${route.view} screen, which only the admin serves`,
+      fix: `claimAdminRoute(admin, '<path>') with one of ${claimablePaths(admin)}: a pages: entry or the dashboard`,
+    });
+  }
+  const screen = screenFor(admin, route);
+  const config = defineRoute<AdminClaimData<TApp>>({
+    render: 'ssr',
+    offline: 'network-only',
+    policy: adminRouteGuard(route),
+    meta: adminRouteMeta(route),
+    ...(options.hydrate === undefined ? {} : { hydrate: options.hydrate }),
+    ...(options.budget === undefined ? {} : { budget: options.budget }),
+    ...(options.navigation === undefined ? {} : { navigation: options.navigation }),
+    load: async ({ params, url }) => {
+      // The actor exactly as the catch-all resolves it: the admin's `auth.actor` over this request.
+      const ctx = await admin.requestCtx(new Request(url, { headers: requestHeaders() }));
+      const response = await screen({ ctx, params, url, method: 'GET', form: null, frame: 'none' });
+      if (response.kind === 'redirect') setRedirect(response.location, 303);
+      const body = response.kind === 'document' ? response.body : null;
+      const answered = response.kind === 'document' ? response.status : 200;
+      const denied = answered === 403;
+      const own = (await options.load?.({ ctx, params, url, denied })) as TApp;
+      const status = answered === 200 ? routeStatusOf(own) : answered;
+      const data: AdminClaimData<TApp> = {
+        body,
+        status,
+        denied,
+        titleKey: route.titleKey,
+        nav: admin.navFor(ctx),
+        app: own,
+      };
+      return status === 200 ? data : withStatus(status, data);
+    },
+  });
+  return issueClaim(route.path, config);
+}
+
+/**
+ * The headers of the request being rendered — the session cookie `auth.actor` reads. Outside a
+ * request (a test rendering the route) there are none, and the actor resolves as nobody: refused.
+ */
+function requestHeaders(): Headers {
+  if (!hasContext()) return new Headers();
+  try {
+    return useRequestHeaders();
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_NO_REQUEST') return new Headers();
+    throw error;
+  }
+}
+
+const claimablePaths = (admin: AdminApp): string =>
+  admin.routes
+    .filter((route) => CLAIMABLE.has(route.view))
+    .map((route) => route.path)
+    .join(', ');

package/src/claims.ts

@@ -0,0 +1,18 @@
+// The configs `claimAdminRoute` issued, each for the one path it was issued for. A leaf, read by
+// `route-config.ts` (the mount's `claimable`) and written by `claim-route.ts` alone — never
+// exported from the package: an app that could add a config here could put any route on an
+// admin path, guard or none.
+
+import type { RouteConfig } from '@ultimat3/render';
+
+/** By IDENTITY: a spread copy of an issued config — a swapped `load` — is not issued. */
+const issued = new WeakMap<object, string>();
+
+export function issueClaim<TConfig extends object>(path: string, config: TConfig): TConfig {
+  issued.set(config, path);
+  return config;
+}
+
+/** May `config` serve `path` in the admin's place? Only if it was issued for exactly that path. */
+export const claimable = (path: string, config: RouteConfig): boolean =>
+  issued.get(config) === path;

package/src/index.ts

@@ -123,6 +123,12 @@ export {
 } from './batch-job';
 export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
 export { BATCH_QUEUED_REASON } from './batch-queue';
+export {
+  type AdminClaimData,
+  type AdminClaimLoadArgs,
+  type ClaimAdminRouteOptions,
+  claimAdminRoute,
+} from './claim-route';
 export {
   type AdminUpdateOptions,
   adminCreate,

package/src/route-config.ts

@@ -11,6 +11,7 @@ import {
   registerMountedRoutes,
 } from '@ultimat3/render';
 import type { AdminRoute } from './admin';
+import { claimable } from './claims';
 import { AdminPageUnguardedError } from './errors';
 
 /** What `RouteDescriptor.file` reads for an admin route: the package, since no app file is one. */
@@ -23,16 +24,33 @@ export interface AdminRouteDefinition {
 }
 
 /**
- * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
- * which is the whole mechanism. The coarse gate is `permissions[0]` (always `admin:read`, put
- * there by `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per
- * request, in `crud.ts` for a resource screen and in `guardedScreen()` for every other one.
- * An empty list is refused here too: `render: 'ssr'` with no policy is a public dashboard.
+ * The coarse gate of `route`: `permissions[0]` (always `admin:read`, put there by
+ * `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per request, in
+ * `crud.ts` for a resource screen and in `guardedScreen()` for every other one. An empty list is
+ * refused: `render: 'ssr'` with no policy is a public dashboard.
  */
-export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+export function adminRouteGuard(route: AdminRoute): RouteGuard {
   const permission = route.permissions[0];
   if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
-  const policy: RouteGuard = { permission };
+  return { permission };
+}
+
+/**
+ * Never indexed and never followed, whatever the screen answers — a list, a refusal, a 404: an
+ * admin URL in a search result is a row id handed to a crawler. The claimed route
+ * (`claim-route.ts`) is served under the same function.
+ */
+export const adminRouteMeta = (route: AdminRoute) => () => ({
+  title: t(route.titleKey),
+  robots: { index: false, follow: false },
+});
+
+/**
+ * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
+ * which is the whole mechanism.
+ */
+export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+  const policy = adminRouteGuard(route);
   return {
     policy,
     config: defineRoute({
@@ -41,14 +59,13 @@ export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
       // every control on an admin screen is a link or a native form, so there is nothing to
       // hydrate. `never` is a REFUSAL and not just a default — an `island()` rendered on this
       // route throws `X_ISLAND_NOT_HYDRATED` (`@ultimat3/render`'s `island-collector.ts`), and no
-      // admin module declares one.
+      // admin module declares one. An app that needs one serves the path from its own file:
+      // `claimAdminRoute` (`claim-route.ts`).
       render: 'ssr',
       offline: 'network-only',
       hydrate: 'never',
       policy,
-      // Never indexed and never followed, whatever the screen answers — a list, a refusal, a 404:
-      // an admin URL in a search result is a row id handed to a crawler.
-      meta: () => ({ title: t(route.titleKey), robots: { index: false, follow: false } }),
+      meta: adminRouteMeta(route),
     }),
   };
 }
@@ -61,7 +78,9 @@ export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
  */
 export function mountAdminRoutes(basePath: string, routes: readonly AdminRoute[]): void {
   registerMountedRoutes(
-    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app' },
+    // `claimable`: the one way an app file serves a path of this table — a config
+    // `claimAdminRoute` issued for exactly that path. Anything else on it is X_ROUTE_DUPLICATE.
+    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app', claimable },
     routes.map((route) => ({
       path: route.path,
       config: adminRouteDefinition(route).config,

package/src/screen-frame.tsx

@@ -23,6 +23,12 @@ export interface AdminRouteRequest extends AdminPageProps {
   readonly method: 'GET' | 'POST';
   /** The parsed form. `null` on a GET; a POST with no fields is `{}`. */
   readonly form: Readonly<Record<string, unknown>> | null;
+  /**
+   * Who frames the body. Absent or `'admin'`: the admin's own layout. `'none'`: the body alone,
+   * for an app file that claimed the route (`claimAdminRoute`) and frames it in its own shell.
+   * The decision, the audit and the status are the screen's either way — only the wrapper differs.
+   */
+  readonly frame?: 'admin' | 'none';
 }
 
 export type AdminRouteResponse =
@@ -83,6 +89,7 @@ export function framed(
   body: JSX.Element,
   status = 200,
 ): AdminRouteResponse {
+  if (request.frame === 'none') return { kind: 'document', status, body };
   return {
     kind: 'document',
     status,