@ultimat3/admin 22.15.0 → 24.0.0

package/src/resource-layout.ts

@@ -0,0 +1,89 @@
+// How a resource's fields are ARRANGED: the detail page's sections and the form's groups. One
+// normaliser for both, and one rule that makes it safe to declare either — a field named in no
+// group falls into a default one, so adding a column to the entity never hides it from a screen.
+
+import { AdminFieldUnsupportedError } from './errors';
+import type { AdminField } from './fields';
+
+/** One declared group: a titled run of fields, in the order they are named. */
+export interface AdminSectionOptions {
+  /** i18n key of the heading. */
+  readonly titleKey: string;
+  readonly fields: readonly string[];
+}
+
+/** The form's spelling of the same thing. One shape, so a detail and its form can share a list. */
+export type AdminFormGroupOptions = AdminSectionOptions;
+
+export interface AdminSection {
+  /** `null` only for the single group of a resource that declared none: it has no heading. */
+  readonly titleKey: string | null;
+  readonly fields: readonly AdminField[];
+  /** The group the undeclared fields fell into. Drawn last. */
+  readonly default: boolean;
+}
+
+/** The heading of the default group, when declared groups sit above it. */
+export const DEFAULT_SECTION_KEY = 'admin.section.other';
+
+interface Layout {
+  readonly entity: string;
+  /** `sections` or `formGroups` — what a refusal names. */
+  readonly option: 'sections' | 'formGroups';
+  /** The fields this layout may arrange, in derived order. */
+  readonly fields: readonly AdminField[];
+  /** Why a named field that is a column is still not one of `fields`. */
+  readonly excluded: string;
+}
+
+/**
+ * Declared groups in declaration order, then the default group holding every field nobody named —
+ * in derived order — when there is one. A name that is not a field of this layout, or that two
+ * groups both claim, is refused where it is written.
+ */
+export function layoutOf(
+  layout: Layout,
+  declared: readonly AdminSectionOptions[] | undefined,
+): readonly AdminSection[] {
+  if (declared === undefined || declared.length === 0) {
+    return [{ titleKey: null, fields: layout.fields, default: true }];
+  }
+  const claimed = new Map<string, string>();
+  const groups = declared.map((group): AdminSection => {
+    const fields = group.fields.map((name) => {
+      const field = layout.fields.find((known) => known.name === name);
+      const refuse = (cause: string, fix: string): never => {
+        throw new AdminFieldUnsupportedError({ entity: layout.entity, field: name, cause, fix });
+      };
+      if (field === undefined) {
+        return refuse(
+          `named in ${layout.option} ("${group.titleKey}") and ${layout.excluded}`,
+          `remove "${name}" from resources.${layout.entity}.${layout.option} — it may name: ${layout.fields.map((known) => known.name).join(', ')}`,
+        );
+      }
+      const owner = claimed.get(name);
+      if (owner !== undefined) {
+        return refuse(
+          `named in two ${layout.option} groups ("${owner}" and "${group.titleKey}")`,
+          `keep "${name}" in one group of resources.${layout.entity}.${layout.option}`,
+        );
+      }
+      claimed.set(name, group.titleKey);
+      return field;
+    });
+    return { titleKey: group.titleKey, fields, default: false };
+  });
+  const rest = layout.fields.filter((field) => !claimed.has(field.name));
+  return rest.length === 0
+    ? groups
+    : [...groups, { titleKey: DEFAULT_SECTION_KEY, fields: rest, default: true }];
+}
+
+/** The fields of one group a form in `mode` draws: a field declared for the other side is left out. */
+export function fieldsFor(
+  fields: readonly AdminField[],
+  mode: 'create' | 'edit',
+): readonly AdminField[] {
+  const side = mode === 'create' ? 'create' : 'update';
+  return fields.filter((field) => field.on === undefined || field.on === side);
+}

package/src/resource-list.ts

@@ -0,0 +1,194 @@
+// The list half of a resource declaration: scopes, the row scope and computed columns — each
+// normalised once and validated where it is written, so a list screen, the search, the lookup and
+// the MCP tool all read the same three values and none of them re-reads the options.
+
+import type { JSX } from 'solid-js';
+import type { AdminActor } from './authz';
+import { AdminFieldUnsupportedError, AdminFilterInvalidError } from './errors';
+import { declaredFilters } from './list-filters';
+import type { AdminEntity, AdminFilter, AdminRepo, AdminRow } from './registry';
+import type { WidgetContext } from './widget-value';
+
+/**
+ * The path segment a resource's lookup is mounted under: `/admin/<resource>/lookup`. A literal
+ * segment outranks `:id`, exactly as `new` does, so no row can be shadowed by it.
+ */
+export const LOOKUP_SEGMENT = 'lookup';
+
+/** Predicates, or predicates of the acting actor (`mine`, `my team's`). */
+export type AdminScopeWhere =
+  | readonly AdminFilter[]
+  | ((actor: AdminActor) => readonly AdminFilter[]);
+
+export interface AdminScopeOptions {
+  readonly where: AdminScopeWhere;
+  /** The scope a bare list URL applies. At most one; with none, the bare list is unscoped. */
+  readonly default?: boolean;
+  /** Show the row count on the tab. Opt-in: a count is a query, on a big table a slow one. */
+  readonly count?: boolean;
+  /** Omitted: `admin.<entity>.scope.<name>`. */
+  readonly labelKey?: string;
+}
+
+/** A declared scope, normalised. `where` is checked on every call — it may depend on the actor. */
+export interface AdminScope {
+  readonly name: string;
+  readonly labelKey: string;
+  readonly default: boolean;
+  readonly count: boolean;
+  where(actor: AdminActor): readonly AdminFilter[];
+}
+
+/**
+ * Which rows of a resource one actor may see at all. One declaration, applied by every read the
+ * admin issues for the resource — list, search, detail, lookup, label, the MCP tools — so a second
+ * audience is a function of the actor and never a second copy of the resource.
+ */
+export type AdminRowScope = (actor: AdminActor) => readonly AdminFilter[];
+
+/** The closed set. An app needing a seventh passes a component for that column. */
+export const ADMIN_RENDERERS = [
+  'badge',
+  'relative-time',
+  'money',
+  'truncate',
+  'link',
+  'json',
+] as const;
+
+export type AdminRenderer = (typeof ADMIN_RENDERERS)[number];
+
+export interface AdminColumnRenderProps<Row extends AdminRow = AdminRow> {
+  readonly value: unknown;
+  readonly row: Row;
+  readonly ctx: WidgetContext;
+}
+
+export type AdminColumnComponent<Row extends AdminRow = AdminRow> = (
+  props: AdminColumnRenderProps<Row>,
+) => JSX.Element;
+
+export interface AdminComputedColumnOptions<Row extends AdminRow = AdminRow> {
+  /**
+   * The cell's value, from the row. The row it is handed carries no sealed column: a computed
+   * column is rendered, and a sealed value is never rendered.
+   */
+  readonly value: (row: Row) => unknown;
+  readonly render: AdminRenderer | AdminColumnComponent<Row>;
+  /** Omitted: `admin.<entity>.column.<name>`. */
+  readonly labelKey?: string;
+}
+
+/**
+ * A declared column, normalised — and typed over `AdminRow`, never the app's own `Row`: a resource
+ * that carried `(row: Row) => …` would be invariant in `Row`, and every function taking "any
+ * resource" would stop accepting one. The narrowing back happens once, in `computedColumnsOf`.
+ */
+export interface AdminComputedColumn extends AdminComputedColumnOptions<AdminRow> {
+  readonly name: string;
+  readonly labelKey: string;
+}
+
+interface Declared {
+  readonly name: string;
+  readonly entity: AdminEntity;
+}
+
+/**
+ * The list URL's spelling of "no scope, not even the default" — `?scope=*`, what a related card's
+ * "all" link opens. Reserved: a scope declared under it is refused, so the word means one thing.
+ */
+export const NO_SCOPE = '*';
+
+/** The declared scopes, in declaration order — which is the order the tabs are drawn in. */
+export function scopesOf(
+  resource: Declared,
+  scopes: Readonly<Record<string, AdminScopeOptions>> | undefined,
+  repo: AdminRepo<AdminRow> | undefined,
+): readonly AdminScope[] {
+  const entries = Object.entries(scopes ?? {});
+  const names = entries.map(([name]) => name);
+  const refuse = (asked: string, cause: string): never => {
+    throw new AdminFilterInvalidError({ entity: resource.name, asked, cause, known: names });
+  };
+  if (Object.hasOwn(scopes ?? {}, NO_SCOPE)) {
+    refuse(`scopes.${NO_SCOPE}`, `is the list URL's word for "no scope" and cannot name one`);
+  }
+  const defaults = entries.filter(([, scope]) => scope.default === true).map(([name]) => name);
+  if (defaults.length > 1) {
+    refuse(
+      `scopes: ${defaults.join(', ')}`,
+      'marks more than one scope `default: true`; a bare list URL applies exactly one',
+    );
+  }
+  return entries.map(([name, scope]) => {
+    const declaredAs = `scopes.${name}.where`;
+    // A tab's count is `AdminRepo.count`, which a hand-written repo may leave out: refused where
+    // the scope is declared, rather than drawn as a tab whose number silently never appears.
+    if (scope.count === true && repo !== undefined && repo.count === undefined) {
+      refuse(
+        `scopes.${name}.count`,
+        'asks for a count, and the repo this resource reads through has no count()',
+      );
+    }
+    const where = scope.where;
+    if (typeof where !== 'function') declaredFilters(resource, where, declaredAs);
+    return {
+      name,
+      labelKey: scope.labelKey ?? `admin.${resource.name}.scope.${name}`,
+      default: scope.default === true,
+      count: scope.count === true,
+      where: (actor) =>
+        typeof where === 'function' ? declaredFilters(resource, where(actor), declaredAs) : where,
+    };
+  });
+}
+
+/** `rows`, checked on every call. Absent stays absent: an unscoped resource asks no predicate. */
+export function rowScopeOf(
+  resource: Declared,
+  rows: AdminRowScope | undefined,
+): AdminRowScope | undefined {
+  if (rows === undefined) return undefined;
+  return (actor) => declaredFilters(resource, rows(actor), 'rows');
+}
+
+const isRenderer = (value: unknown): value is AdminRenderer =>
+  (ADMIN_RENDERERS as readonly unknown[]).includes(value);
+
+/** Declaration order, after the entity's own list fields. */
+export function computedColumnsOf<Row extends AdminRow>(
+  resource: Declared,
+  columns: Readonly<Record<string, AdminComputedColumnOptions<Row>>> | undefined,
+): readonly AdminComputedColumn[] {
+  return Object.entries(columns ?? {}).map(([name, column]) => {
+    if (Object.hasOwn(resource.entity.$columns, name)) {
+      throw new AdminFieldUnsupportedError({
+        entity: resource.name,
+        field: name,
+        cause: 'is declared in `columns:` and is also a column of the entity',
+        fix: `rename the computed column in resources.${resource.name}.columns — e.g. ${name}Label — or drop it and let the admin render the column itself`,
+      });
+    }
+    if (typeof column.render !== 'function' && !isRenderer(column.render)) {
+      throw new AdminFieldUnsupportedError({
+        entity: resource.name,
+        field: name,
+        cause: `names a renderer the admin does not have (it has: ${ADMIN_RENDERERS.join(', ')})`,
+        fix: `set resources.${resource.name}.columns.${name}.render to one of those, or pass a component: render: (props) => <YourCell {...props} />`,
+      });
+    }
+    const render = column.render;
+    return {
+      name,
+      labelKey: column.labelKey ?? `admin.${resource.name}.column.${name}`,
+      // The rows a resource's list hands these ARE its `Row`s: the declaration's own type is
+      // restored here, at the one place the two meet.
+      value: (row) => column.value(row as Row),
+      render:
+        typeof render === 'function'
+          ? (props) => render({ ...props, row: props.row as Row })
+          : render,
+    };
+  });
+}

package/src/resource.ts

@@ -4,25 +4,33 @@
 // field, but the zero-config result is the one the generator emits and the one the docs show.
 
 import { finiteCount } from '@ultimat3/core';
-import { type AdminColumnFacts, adminColumnsOf } from './entity-columns';
+import { type AdminColumnFacts, adminColumnsOf, adminSealedColumnsOf } from './entity-columns';
 import {
   AdminEntityUnknownError,
   AdminFieldUnsupportedError,
   AdminPolicyMissingError,
+  AdminRepoUnboundError,
 } from './errors';
-import {
-  type AdminField,
-  type AdminFieldType,
-  type AdminWidget,
-  fieldTypeFromColumn,
-  filterable,
-  listable,
-  searchable,
-  sortable,
-  widgetFor,
-} from './fields';
+import type { AdminField } from './fields';
 import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
 import type { AdminAction, AdminEntity, AdminRepo, AdminRow, AdminSort } from './registry';
+import { type AdminFieldOverride, deriveField, secretField } from './resource-fields';
+import {
+  type AdminFormGroupOptions,
+  type AdminSection,
+  type AdminSectionOptions,
+  layoutOf,
+} from './resource-layout';
+import {
+  type AdminComputedColumn,
+  type AdminComputedColumnOptions,
+  type AdminRowScope,
+  type AdminScope,
+  type AdminScopeOptions,
+  computedColumnsOf,
+  rowScopeOf,
+  scopesOf,
+} from './resource-list';
 
 /** Six columns is what fits a laptop viewport without horizontal scroll. */
 const MAX_LIST_FIELDS = 6;
@@ -30,27 +38,15 @@ const DEFAULT_PAGE_SIZE = 25;
 const LABEL_CANDIDATES = ['name', 'title', 'slug', 'label', 'email'] as const;
 const SORT_CANDIDATES = ['createdAt', 'created_at', 'updatedAt', 'updated_at'] as const;
 
-export interface AdminFieldOverride {
-  readonly type?: AdminFieldType;
-  readonly widget?: AdminWidget;
-  readonly labelKey?: string;
-  /** Out of every surface: list, detail, form, MCP schema. */
-  readonly hidden?: boolean;
-  readonly inList?: boolean;
-  readonly readOnly?: boolean;
-  readonly required?: boolean;
-  readonly sensitive?: boolean;
-  readonly filterable?: boolean;
-  readonly sortable?: boolean;
-  readonly searchable?: boolean;
-  readonly currency?: string;
-  readonly values?: readonly string[];
-  readonly relation?: { readonly entity: string; readonly labelField?: string };
-}
-
 export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
   readonly repo?: AdminRepo<Row>;
   readonly path?: string;
+  /**
+   * The noun this resource's permissions are named after — `<permission>:read|write|delete`.
+   * Default: the entity's name. Several resources that are one subject to an operator share one
+   * (the jobs screens are all `job:read`), so a role map grants a subject once, not per table.
+   */
+  readonly permission?: string;
   readonly titleKey?: string;
   readonly group?: string;
   /**
@@ -62,6 +58,35 @@ export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
   readonly fields?: Readonly<Record<string, AdminFieldOverride>>;
   /** Explicit list columns, in order. Omit to let the derivation pick. */
   readonly listFields?: readonly string[];
+  /**
+   * Computed list columns, drawn after `listFields` in declaration order:
+   * `age: { value: (row) => row.createdAt, render: 'relative-time' }`. `render` is one of the six
+   * built-in renderers or a component. A name that is also an entity column is refused.
+   */
+  readonly columns?: Readonly<Record<string, AdminComputedColumnOptions<Row>>>;
+  /**
+   * Named predicates, drawn as tabs: `open: { where: [...] }`, `mine: { where: (actor) => [...] }`.
+   * At most one `default: true`; `count: true` is one extra query per tab that asks for it.
+   */
+  readonly scopes?: Readonly<Record<string, AdminScopeOptions>>;
+  /**
+   * The rows this ACTOR may see at all. Applied to every read of the resource — list, search,
+   * detail, lookup, labels, MCP — so it is the one place a second audience is declared.
+   */
+  readonly rows?: AdminRowScope;
+  /**
+   * The detail page, as titled groups of fields. A field named in none falls into a default
+   * section drawn last, so a column added to the entity is never hidden by this list.
+   */
+  readonly sections?: readonly AdminSectionOptions[];
+  /** The same arrangement for the create and edit form. Independent of `sections`. */
+  readonly formGroups?: readonly AdminFormGroupOptions[];
+  /**
+   * `hasMany` relations of the entity, by name — `['comments']` — drawn on the detail page as the
+   * RELATED resource's own list (its columns, its row scope, its policy) filtered to this row.
+   * The names are `@ultimat3/entity`'s: the one a preload names.
+   */
+  readonly related?: readonly string[];
   readonly defaultSort?: AdminSort;
   readonly pageSize?: number;
   readonly operations?: readonly AdminOperation[];
@@ -81,6 +106,8 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
    * the framework can own (axiom 8) — `path:` is how an app spells its own.
    */
   readonly path: string;
+  /** The permission noun — `<permission>:read` lists it. The entity's name unless declared. */
+  readonly permission: string;
   readonly titleKey: string;
   readonly group: string;
   readonly idField: string;
@@ -90,8 +117,31 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   readonly fields: readonly AdminField[];
   readonly listFields: readonly AdminField[];
   readonly formFields: readonly AdminField[];
+  /**
+   * The entity's `.sealed()` columns, as WRITE-ONLY inputs: a form posts them, nothing reads them.
+   * Deliberately a list of its own and in none of the others — `fields`, `listFields`,
+   * `formFields`, `filters` and `searchFields` are all read back by column name somewhere, and a
+   * sealed property answers that read with its plaintext.
+   */
+  readonly secretFields: readonly AdminField[];
+  /**
+   * The label field first — a list's search box is its `contains` filter — then every field the
+   * derivation offers. What a URL's `f.<field>` may name, and nothing else.
+   */
   readonly filters: readonly AdminField[];
   readonly searchFields: readonly AdminField[];
+  /** Computed list columns, in declaration order. */
+  readonly columns: readonly AdminComputedColumn[];
+  /** Declared scopes, in tab order. Empty for a resource that declares none. */
+  readonly scopes: readonly AdminScope[];
+  /** `rows`, validated per call. Absent for a resource every permitted actor sees whole. */
+  readonly rowScope?: AdminRowScope;
+  /** The detail page's groups. Always at least one: undeclared fields have a default section. */
+  readonly sections: readonly AdminSection[];
+  /** The form's groups, over `formFields` and `secretFields` both. */
+  readonly formGroups: readonly AdminSection[];
+  /** Declared `related` relation names, in order. `related.ts` resolves each against the admin. */
+  readonly related: readonly string[];
   readonly defaultSort: AdminSort;
   readonly pageSize: number;
   readonly operations: readonly AdminOperation[];
@@ -100,48 +150,6 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   field(name: string): AdminField;
 }
 
-function deriveField(
-  entity: AdminEntity,
-  column: AdminColumnFacts,
-  override: AdminFieldOverride | undefined,
-): AdminField {
-  const name = column.name;
-  const type = override?.type ?? fieldTypeFromColumn(entity.$name, name, column);
-  const widget = override?.widget ?? widgetFor(type);
-  const generated = column.generated || column.primaryKey;
-  // An entity has no notion of a secret column, and a currency belongs to the value rather
-  // than the column, so both are admin-side declarations or they are absent. Never guessed.
-  const sensitive = override?.sensitive ?? false;
-  const currency = override?.currency;
-  const values = override?.values ?? column.values;
-  const relation =
-    override?.relation ??
-    // The FK's value IS the target column's value, so that column is the honest default label.
-    (column.references === undefined
-      ? undefined
-      : { entity: column.references.entity, labelField: column.references.column });
-
-  return {
-    entity: entity.$name,
-    name,
-    type,
-    widget,
-    labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${name}`,
-    required: override?.required ?? (!column.nullable && !generated),
-    readOnly: override?.readOnly ?? generated,
-    sensitive,
-    inList: override?.inList ?? (listable(type) && !sensitive),
-    filterable: override?.filterable ?? filterable(type, column),
-    sortable: override?.sortable ?? sortable(type, column),
-    // Generated columns are excluded from search: an id is found by exact lookup, and a
-    // `contains` over a uuid column is a scan that returns nothing useful.
-    searchable: override?.searchable ?? (searchable(type, column) && !sensitive && !generated),
-    ...(values === undefined ? {} : { values }),
-    ...(currency === undefined ? {} : { currency }),
-    ...(relation === undefined ? {} : { relation }),
-  };
-}
-
 /**
  * The declared key wins — but a composite one is refused outright, never silently reduced to
  * its first member: a route id and an `AdminRepo` id both carry exactly one string, so two rows
@@ -230,6 +238,18 @@ function pickListFields(
   return [...label, ...rest].slice(0, MAX_LIST_FIELDS);
 }
 
+/**
+ * The label first, whether or not it is indexed: a list's search box IS the label's `contains`
+ * filter, and a list an operator cannot search by name is the one they leave for a SQL console.
+ * Only a text label qualifies — a `contains` over a uuid is a database error, not an empty result.
+ */
+function filtersOf(fields: readonly AdminField[], labelField: string): readonly AdminField[] {
+  const label = fields.filter(
+    (field) => field.name === labelField && field.filterKind === 'text' && !field.sensitive,
+  );
+  return [...label, ...fields.filter((field) => field.filterable && !label.includes(field))];
+}
+
 function assertActionsHavePolicies(actions: readonly AdminAction[]): void {
   for (const action of actions) {
     // Widened because the registry is JSON at the boundary: a hand-written action object
@@ -264,10 +284,18 @@ export function adminResource<Row extends AdminRow = AdminRow>(
   const labelField = labelFieldOf(entity, fields, idField, opts.labelField);
   const actions = opts.actions ?? [];
   assertActionsHavePolicies(actions);
+  const declared = { name: entity.$name, entity };
+  const rowScope = rowScopeOf(declared, opts.rows);
+
+  const formFields = fields.filter((field) => !field.readOnly && !field.sensitive);
+  const secretFields = adminSealedColumnsOf(entity)
+    .filter((column) => overrides[column.name]?.hidden !== true)
+    .map((column) => secretField(entity, column, overrides[column.name]));
 
   const resource: AdminResource<Row> = {
     name: entity.$name,
     path: opts.path ?? `/${entity.$name}`,
+    permission: opts.permission ?? entity.$name,
     titleKey: opts.titleKey ?? `admin.${entity.$name}.title`,
     group: opts.group ?? 'admin.group.data',
     idField,
@@ -275,9 +303,35 @@ export function adminResource<Row extends AdminRow = AdminRow>(
     entity,
     fields,
     listFields: pickListFields(fields, labelField, opts.listFields, entity.$name),
-    formFields: fields.filter((field) => !field.readOnly && !field.sensitive),
-    filters: fields.filter((field) => field.filterable),
+    formFields,
+    secretFields,
+    filters: filtersOf(fields, labelField),
     searchFields: fields.filter((field) => field.searchable),
+    columns: computedColumnsOf(declared, opts.columns),
+    scopes: scopesOf(declared, opts.scopes, opts.repo),
+    ...(rowScope === undefined ? {} : { rowScope }),
+    sections: layoutOf(
+      {
+        entity: entity.$name,
+        option: 'sections',
+        // What the detail page draws: every field but a `sensitive` one. A sealed column is in no
+        // list a reader iterates, so it cannot be named here either.
+        fields: fields.filter((field) => !field.sensitive),
+        excluded:
+          'is not a field the detail page draws (hidden, sensitive, sealed, or not a column)',
+      },
+      opts.sections,
+    ),
+    formGroups: layoutOf(
+      {
+        entity: entity.$name,
+        option: 'formGroups',
+        fields: [...formFields, ...secretFields],
+        excluded: 'is not a form input (read-only, generated, sensitive, hidden, or not a column)',
+      },
+      opts.formGroups,
+    ),
+    related: opts.related ?? [],
     defaultSort: opts.defaultSort ?? defaultSortOf(fields, idField),
     // Refused here rather than at the first listing, because `pagination.ts` clamps with
     // `Math.max(1, Math.min(x, 200))` and neither of those validates: a `NaN` survives both, so
@@ -306,11 +360,7 @@ export function adminResource<Row extends AdminRow = AdminRow>(
 /** The bound repo, or the one error that says which resource forgot it. */
 export function repoOf<Row extends AdminRow>(resource: AdminResource<Row>): AdminRepo<Row> {
   if (resource.repo === undefined) {
-    throw new AdminEntityUnknownError({
-      entity: resource.name,
-      known: [],
-      cause: `resource "${resource.name}" has no repo bound, so the admin cannot read or write rows`,
-    });
+    throw new AdminRepoUnboundError({ entity: resource.name, handles: [] });
   }
   return resource.repo;
 }

package/src/route-config.ts

@@ -0,0 +1,71 @@
+// The one bridge from the admin's route table to @ultimat3/render's: the `defineRoute` config
+// every admin route is served under, and the declaration that puts those routes in the framework's
+// one route list. No screen is reached from here, so `defineAdmin()` can declare its routes
+// without loading a view — `routes.ts` binds each route to its screen.
+
+import { t } from '@ultimat3/i18n';
+import {
+  defineRoute,
+  type RouteConfig,
+  type RouteGuard,
+  registerMountedRoutes,
+} from '@ultimat3/render';
+import type { AdminRoute } from './admin';
+import { AdminPageUnguardedError } from './errors';
+
+/** What `RouteDescriptor.file` reads for an admin route: the package, since no app file is one. */
+export const ADMIN_ROUTE_FILE = '@ultimat3/admin';
+
+export interface AdminRouteDefinition {
+  /** The coarse gate — the SAME object `config.policy` carries. */
+  readonly policy: RouteGuard;
+  readonly config: RouteConfig;
+}
+
+/**
+ * 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.
+ */
+export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+  const permission = route.permissions[0];
+  if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
+  const policy: RouteGuard = { permission };
+  return {
+    policy,
+    config: defineRoute({
+      // One mode for every admin route, never an author's choice. `ssr` renders the rows behind
+      // the guard, once per request, and `hydrate: 'never'` means the screen ships no JS at all:
+      // 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.
+      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 } }),
+    }),
+  };
+}
+
+/**
+ * Declare an admin's routes to the framework's route table — as MOUNTED routes, each with every
+ * permission that gates it — so `x routes`, the `/_x` routes panel, the manifest and `sw.js` list
+ * them from the one projection everything else is listed from. Keyed by base path: re-declaring
+ * the admin (a save under `x dev`) replaces its set.
+ */
+export function mountAdminRoutes(basePath: string, routes: readonly AdminRoute[]): void {
+  registerMountedRoutes(
+    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app' },
+    routes.map((route) => ({
+      path: route.path,
+      config: adminRouteDefinition(route).config,
+      permissions: route.permissions,
+    })),
+  );
+}