@ultimat3/admin 24.0.0 → 25.1.0

package/src/dev/dev-t.ts

@@ -0,0 +1,9 @@
+// The `/_x` translator: the framework catalog in the framework's own locale, whatever the app's
+// default is. Every `/_x` string is registered under `DEFAULT_LOCALE` only, so the
+// AMBIENT locale — an `es-co` app's — answered `⟦dev.panel.mail.title⟧` for every tab.
+
+import { DEFAULT_LOCALE } from '@ultimat3/core';
+import { type TranslateVars, translatorFor } from '@ultimat3/i18n';
+
+export const t = (key: string, vars?: TranslateVars): string =>
+  translatorFor(DEFAULT_LOCALE)(key, vars);

package/src/dev/jobs-state-chart.tsx

@@ -0,0 +1,38 @@
+// The `/_x` jobs tab's opening ring: the recent runs this panel read, by state — ui's own
+// `DonutChart`, server markup with a hidden data table. Only ever reached by `panel-jobs.ts`'s
+// dynamic `import()`, so `/_x`'s mount graph loads no Solid until the jobs tab is opened.
+
+import { ctxOf, runWithContext } from '@ultimat3/core';
+import { renderToHtml } from '@ultimat3/render/server';
+import { DonutChart } from '@ultimat3/ui';
+import { t } from './dev-t';
+import type { JobRunFact } from './facts';
+import type { JobsPanelData } from './panel-jobs';
+
+/** Every state a run can be in, in the order the ring and its legend draw them. */
+const RUN_STATES: readonly JobRunFact['status'][] = ['ok', 'running', 'failed', 'dead'];
+
+/**
+ * The ring as HTML, or `''` when no run has been recorded: an empty circle reads as a broken chart,
+ * and the overview below already says the queue is idle. The framework's locale and UTC, stated
+ * rather than ambient — `/_x` is the framework's tool.
+ */
+export async function jobsStateHtml(data: JobsPanelData): Promise<string> {
+  if (data.runs.length === 0) return '';
+  const counts = RUN_STATES.map((state) => ({
+    label: t(`dev.panel.jobs.state.${state}`),
+    value: data.runs.filter((run) => run.status === state).length,
+  }));
+  return runWithContext(ctxOf({ locale: 'en', tz: 'UTC' }), () =>
+    renderToHtml(
+      <DonutChart
+        label={t('dev.panel.jobs.chart.label')}
+        showCaption
+        segments={counts}
+        centreLabel={t('dev.panel.jobs.chart.total')}
+        keyLabel={t('dev.panel.jobs.chart.state')}
+        valueLabel={t('dev.panel.jobs.chart.runs')}
+      />,
+    ),
+  );
+}

package/src/dev/panel-jobs.ts

@@ -75,11 +75,16 @@ export const jobsPanel: DevPanel<JobsPanelData> = {
     };
   },
   /**
-   * One jobs UI: the tab draws the admin's own overview component over this process's queue.
-   * Dynamic, so `/_x`'s mount graph loads no view until this tab is opened.
+   * One jobs UI: the tab draws the admin's own overview component over this process's queue,
+   * under a ring of the runs this panel read by state. Dynamic, so `/_x`'s mount graph loads no
+   * view until this tab is opened.
    */
-  async html(params, tabPath) {
-    const { jobsTabHtml } = await import('../jobs/overview-tab');
-    return jobsTabHtml(tabPath, params);
+  async html(params, tabPath, data) {
+    const [{ jobsTabHtml }, { jobsStateHtml }] = await Promise.all([
+      import('../jobs/overview-tab'),
+      import('./jobs-state-chart'),
+    ]);
+    const ring = data === undefined ? '' : await jobsStateHtml(data);
+    return `${ring}${await jobsTabHtml(tabPath, params)}`;
   },
 };

package/src/dev/panel-timeline.ts

@@ -1,11 +1,12 @@
 // Panel: Request timeline.
-// Kills: "where did the 800ms go?" — a flamegraph of one request: SQL, cache hits, action
+// Kills: "where did the 800ms go?" — a waterfall of one request: SQL, cache hits, action
 // calls, and policy decisions on one axis, with the N+1 already counted for you — counted by
 // `x dev`'s statement ledger and read here through `statementLoops()`, never re-derived.
 
 import { DevSourceUnavailableError } from '../errors';
 import type { RequestTrace, SpanKind, StatementLoopFact, TimelineSpan } from './facts';
 import type { DevPanel } from './panel';
+import { timelineHtml } from './timeline-waterfall';
 
 export interface FlameRow {
   readonly span: TimelineSpan;
@@ -105,4 +106,11 @@ export const timelinePanel: DevPanel<TimelinePanelData> = {
         loops === null ? null : loops.filter((loop) => loop.requestId === selected?.requestId),
     };
   },
+  /**
+   * The waterfall, drawn from the data above — never a second read of the traces. With no data
+   * handed there is nothing to draw, and the server folds the payload under an empty body.
+   */
+  async html(_params, tabPath, data) {
+    return data === undefined ? '' : timelineHtml(data, tabPath);
+  },
 };

package/src/dev/panel.ts

@@ -18,10 +18,13 @@ export interface DevPanel<Data = unknown> {
   data(sources: DevSources, params: URLSearchParams): Promise<Data>;
   /**
    * The tab's body as HTML, when the panel draws one — the jobs tab renders the admin's own
-   * jobs overview. Absent: the tab is its `--json` payload in a `<pre>`. Asked only once `data`
-   * answered, so an unwired source is still the payload's own error with its fix.
+   * jobs overview, the timeline its waterfall. Absent: the tab is its `--json` payload in a
+   * `<pre>`. Asked only once `data` answered, and handed that answer, so the drawing and the
+   * `--json` payload are the same facts and an unwired source is still the payload's own error.
+   * Optional only for a caller that draws a tab outside the server (a test of the jobs tab); the
+   * server always hands it.
    */
-  html?(params: URLSearchParams, tabPath: string): Promise<string>;
+  html?(params: URLSearchParams, tabPath: string, data?: Data): Promise<string>;
 }
 
 export type PanelPayload =

package/src/dev/server.ts

@@ -5,10 +5,10 @@
 // Type-only, so it is erased and the 46-component barrel stays out of the mount graph — the
 // values arrive through the dynamic `import()` in `devShellStyle()`, same reason as `data.ts`.
 import { DEFAULT_ENVIRONMENT, escapeHtml, tryResolveEnvironment } from '@ultimat3/core';
-import { FRAMEWORK_CATALOG_LOCALE, translatorFor } from '@ultimat3/i18n';
 import type { ColorRole } from '@ultimat3/ui';
 import { DevDashboardInProdError } from '../errors';
 import { defaultDevSources } from './data';
+import { t } from './dev-t';
 import type { DevSources } from './facts';
 import { type DevPanel, type PanelPayload, panelPayload } from './panel';
 import { cachePanel } from './panel-cache';
@@ -20,6 +20,7 @@ import { manifestPanel } from './panel-manifest';
 import { policyPanel } from './panel-policy';
 import { routesPanel } from './panel-routes';
 import { timelinePanel } from './panel-timeline';
+import { WATERFALL_STYLE } from './timeline-style';
 
 export const DEV_PANELS: readonly DevPanel[] = [
   routesPanel,
@@ -43,6 +44,13 @@ export interface DevDashboardOptions {
   readonly basePath?: string;
   readonly sources?: DevSources;
   readonly panels?: readonly DevPanel[];
+  /**
+   * The app surface's stylesheet URL — what `<link rel="stylesheet">` on an `app/` document carries.
+   * A drawn panel (the jobs tab) renders ui's own components, whose rules live there and not in the
+   * inlined shell; the host that mounts `/_x` is the one that knows the content-hashed URL. Asked
+   * per request, because a rebuild under `x dev` moves the hash. Absent or `undefined`: no link.
+   */
+  readonly stylesheetHref?: () => string | undefined;
 }
 
 const envOf = (name: string): string | undefined => {
@@ -85,7 +93,11 @@ const jsonResponse = (body: unknown, status = 200): Response =>
     headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
   });
 
-/** The six roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. */
+/**
+ * The roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. The chart
+ * series are the timeline's span kinds — `chart-*` is contrast-gated against both surfaces, and
+ * every kind is named in text beside its bar, so colour is never the only key.
+ */
 const SHELL_ROLES = [
   'bg',
   'surface-raised',
@@ -93,6 +105,13 @@ const SHELL_ROLES = [
   'fg-muted',
   'line',
   'accent',
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'chart-6',
+  'chart-7',
 ] as const satisfies readonly ColorRole[];
 
 const SHELL_LAYOUT = `
@@ -107,7 +126,7 @@ p.question { color: rgb(var(--x-color-fg-muted)); margin: 0 0 1rem; }
 pre { background: rgb(var(--x-color-surface-raised)); border: 1px solid rgb(var(--x-color-line));
   padding: 1rem; overflow: auto; }
 :focus-visible { outline: 2px solid rgb(var(--x-color-accent)); outline-offset: 2px; }
-`;
+${WATERFALL_STYLE}`;
 
 let stylePromise: Promise<string> | undefined;
 
@@ -154,15 +173,10 @@ html[data-theme="dark"] { ${block('dark')} }
 ${SHELL_LAYOUT}`;
 }
 
-/**
- * /_x is the framework's own tool, in the framework's own locale (`<html lang="en">` below): its
- * strings are registered under `FRAMEWORK_CATALOG_LOCALE` only, so the AMBIENT locale — the app's,
- * `es-co` for an app that defaults to it — answered `⟦dev.panel.mail.title⟧` for every tab.
- */
-const t = (key: string): string => translatorFor(FRAMEWORK_CATALOG_LOCALE)(key);
-
 function shell(
   style: string,
+  /** The app surface's stylesheet, linked BEFORE the shell's `<style>` so the shell wins ties. */
+  stylesheetHref: string | undefined,
   basePath: string,
   panels: readonly DevPanel[],
   active: DevPanel,
@@ -181,7 +195,11 @@ function shell(
 <html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex, nofollow">
-<title>_x · ${escapeHtml(active.key)}</title><style>${style}</style></head>
+<title>_x · ${escapeHtml(active.key)}</title>${
+    stylesheetHref === undefined
+      ? ''
+      : `<link rel="stylesheet" href="${escapeHtml(stylesheetHref)}">`
+  }<style>${style}</style></head>
 <body><header><h1>_x</h1><nav>${tabs}</nav>
 <a href="${basePath}/${active.key}?json=1">--json</a></header>
 <main><p class="question">${escapeHtml(t(active.questionKey))}</p>
@@ -238,8 +256,19 @@ export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
       if (wantsJson) return jsonResponse(payload, payload.ok ? 200 : 500);
       const tabPath = `${basePath}/${panel.key}`;
       const drawn =
-        payload.ok && panel.html !== undefined ? await panel.html(url.searchParams, tabPath) : null;
-      return new Response(shell(await devShellStyle(), basePath, panels, panel, payload, drawn), {
+        payload.ok && panel.html !== undefined
+          ? await panel.html(url.searchParams, tabPath, payload.data)
+          : null;
+      const page = shell(
+        await devShellStyle(),
+        opts.stylesheetHref?.(),
+        basePath,
+        panels,
+        panel,
+        payload,
+        drawn,
+      );
+      return new Response(page, {
         status: 200,
         headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
       });

package/src/dev/timeline-style.ts

@@ -0,0 +1,47 @@
+// The `/_x` timeline waterfall's rules, inlined into the shell's one `<style>` (`server.ts`) — /_x
+// has no stylesheet pipeline, and the CSP hash a host computes is of that whole text. Colours are
+// the shell's `--x-color-*` tokens only; each span kind takes one `chart-*` series role.
+
+import { SPAN_KINDS } from './timeline-waterfall';
+
+/**
+ * The timeline's waterfall (`timeline-waterfall.ts`): a label column, a track whose bar is placed
+ * by the row's own `--offset`/`--width` (server-computed shares), and the duration. Below 720px the
+ * label takes its own line, so a long SQL text never squeezes the track to nothing on a phone.
+ */
+export const WATERFALL_STYLE = `
+h2 { font-size: .875rem; margin: 0 0 .5rem; }
+.tl { display: grid; gap: 1.5rem; }
+@media (min-width: 1024px) { .tl { grid-template-columns: minmax(12rem, 18rem) minmax(0, 1fr); } }
+.tl-requests ol, .tl-kinds, .tl-flame, .tl-loops ul { list-style: none; margin: 0; padding: 0; }
+.tl-requests li { display: flex; justify-content: space-between; gap: .5rem; padding: .25rem 0;
+  border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-requests a { overflow-wrap: anywhere; }
+.tl-requests a[aria-current] { color: rgb(var(--x-color-fg)); font-weight: 700; }
+.tl-ms { color: rgb(var(--x-color-fg-muted)); white-space: nowrap; font-variant-numeric: tabular-nums; }
+.tl-kinds { display: flex; flex-wrap: wrap; gap: .25rem 1rem; margin-bottom: 1rem; }
+.tl-swatch { display: inline-block; inline-size: .75rem; block-size: .75rem; border-radius: 2px;
+  margin-inline-end: .375rem; vertical-align: -1px; background: rgb(var(--tl-color)); }
+.tl-row { display: grid; grid-template-columns: minmax(0, 1fr) 4.5rem; gap: .125rem .75rem;
+  align-items: center; padding: .25rem 0; border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-label { grid-column: 1 / -1; display: flex; gap: .5rem; align-items: baseline; min-inline-size: 0;
+  padding-inline-start: calc(var(--depth) * .75rem); }
+@media (min-width: 720px) {
+  .tl-row { grid-template-columns: minmax(0, 22rem) minmax(0, 1fr) 4.5rem; }
+  .tl-label { grid-column: auto; }
+}
+.tl-kind { flex: none; padding: 0 .375rem; border-radius: 2px; font-size: .75rem;
+  border: 1px solid rgb(var(--tl-color)); color: rgb(var(--x-color-fg)); }
+.tl-name { flex: none; }
+.tl-detail { min-inline-size: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  color: rgb(var(--x-color-fg-muted)); }
+.tl-track { position: relative; block-size: .875rem; border-radius: 2px;
+  background: rgb(var(--x-color-line) / .35); }
+.tl-bar { position: absolute; inset-block: 0; inset-inline-start: var(--offset);
+  inline-size: max(var(--width), 2px); border-radius: 2px; background: rgb(var(--tl-color)); }
+.tl-row > .tl-ms { text-align: end; }
+.tl-loops { margin-top: 1.5rem; }
+.tl-loops li { padding: .5rem 0; border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-empty { color: rgb(var(--x-color-fg-muted)); }
+${SPAN_KINDS.map((kind, index) => `[data-kind="${kind}"] { --tl-color: var(--x-color-chart-${index + 1}); }`).join('\n')}
+`;

package/src/dev/timeline-waterfall.ts

@@ -0,0 +1,96 @@
+// The `/_x` timeline tab, drawn: the selected request's spans as a waterfall — one row per span,
+// indented under its parent, its bar placed and sized by the server from the payload's own
+// `offset`/`width` — beside the recent requests, the time per kind and the N+1 verdicts. Plain
+// escaped HTML on the shell's tokens: `/_x` loads no Solid and no stylesheet pipeline to draw it.
+
+import { escapeHtml } from '@ultimat3/core';
+import { t } from './dev-t';
+import type { SpanKind, StatementLoopFact } from './facts';
+import type { FlameRow, TimelinePanelData } from './panel-timeline';
+
+/** Every kind a span can be, in the order the legend lists them — and the colour slot each takes. */
+export const SPAN_KINDS: readonly SpanKind[] = [
+  'http',
+  'render',
+  'action',
+  'policy',
+  'sql',
+  'cache',
+  'job',
+];
+
+/** `/_x` is the framework's English tool; a duration reads to a tenth of a millisecond. */
+const MS = new Intl.NumberFormat('en', { maximumFractionDigits: 1 });
+const ms = (value: number): string => t('dev.panel.timeline.ms', { ms: MS.format(value) });
+
+/** A 0..1 share as a CSS percentage: two decimals at most, never `-0`, clamped to the track. */
+const percent = (share: number): string => {
+  const clamped = Number.isFinite(share) ? Math.min(1, Math.max(0, share)) : 0;
+  const text = (clamped * 100).toFixed(2).replace(/\.?0+$/, '');
+  return `${text === '-0' ? '0' : text}%`;
+};
+
+const kindLabel = (kind: SpanKind): string => t(`dev.panel.timeline.kind.${kind}`);
+
+const kindTag = (kind: SpanKind): string =>
+  `<span class="tl-kind">${escapeHtml(kindLabel(kind))}</span>`;
+
+function requestList(data: TimelinePanelData, tabPath: string): string {
+  const shown = data.selected?.requestId;
+  const items = data.requests
+    .map((request) => {
+      const href = `${tabPath}?requestId=${encodeURIComponent(request.requestId)}`;
+      const current = request.requestId === shown ? ' aria-current="true"' : '';
+      return `<li><a href="${escapeHtml(href)}"${current}>${escapeHtml(request.path)}</a> <span class="tl-ms">${escapeHtml(ms(request.totalMs))}</span></li>`;
+    })
+    .join('');
+  const title = escapeHtml(t('dev.panel.timeline.requests'));
+  return `<nav class="tl-requests" aria-label="${title}"><h2>${title}</h2><ol>${items}</ol></nav>`;
+}
+
+function kindTotals(data: TimelinePanelData): string {
+  const items = SPAN_KINDS.filter((kind) => Object.hasOwn(data.totalsByKind, kind))
+    .map(
+      (kind) =>
+        `<li><span class="tl-swatch" data-kind="${kind}" aria-hidden="true"></span>${escapeHtml(kindLabel(kind))} <span class="tl-ms">${escapeHtml(ms(data.totalsByKind[kind] ?? 0))}</span></li>`,
+    )
+    .join('');
+  return `<ul class="tl-kinds" aria-label="${escapeHtml(t('dev.panel.timeline.byKind'))}">${items}</ul>`;
+}
+
+function row(flame: FlameRow): string {
+  const { span } = flame;
+  const style = `--depth:${flame.depth};--offset:${percent(flame.offset)};--width:${percent(flame.width)}`;
+  const detail =
+    span.detail === ''
+      ? ''
+      : `<code class="tl-detail" title="${escapeHtml(span.detail)}">${escapeHtml(span.detail)}</code>`;
+  return `<li class="tl-row" data-kind="${span.kind}" style="${style}"><span class="tl-label">${kindTag(span.kind)} <span class="tl-name">${escapeHtml(span.name)}</span>${detail}</span><span class="tl-track" aria-hidden="true"><span class="tl-bar"></span></span><span class="tl-ms">${escapeHtml(ms(span.durationMs))}</span></li>`;
+}
+
+function verdicts(loops: readonly StatementLoopFact[] | null): string {
+  const title = `<h2>${escapeHtml(t('dev.panel.timeline.nPlusOne.title'))}</h2>`;
+  if (loops === null) {
+    return `<section class="tl-loops">${title}<p class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.unwired'))}</p></section>`;
+  }
+  if (loops.length === 0) {
+    return `<section class="tl-loops">${title}<p class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.clean'))}</p></section>`;
+  }
+  const items = loops
+    .map(
+      (loop) =>
+        `<li><strong>${escapeHtml(loop.code)}</strong> ${escapeHtml(loop.cause)}<br><span class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.fix'))}</span> <code>${escapeHtml(loop.fix)}</code></li>`,
+    )
+    .join('');
+  return `<section class="tl-loops">${title}<ul>${items}</ul></section>`;
+}
+
+/** The tab body. Pure over the panel's data, so the `--json` payload and the drawing agree. */
+export function timelineHtml(data: TimelinePanelData, tabPath: string): string {
+  const selected = data.selected;
+  if (selected === null) {
+    return `<p class="tl-empty">${escapeHtml(t('dev.panel.timeline.empty'))}</p>`;
+  }
+  const heading = `${selected.method} ${selected.path} · ${selected.status} · ${ms(selected.totalMs)}`;
+  return `<div class="tl">${requestList(data, tabPath)}<section class="tl-trace" aria-labelledby="tl-heading"><h2 id="tl-heading">${escapeHtml(heading)}</h2>${kindTotals(data)}<ol class="tl-flame" aria-label="${escapeHtml(t('dev.panel.timeline.spans'))}">${data.flame.map(row).join('')}</ol>${verdicts(data.nPlusOne)}</section></div>`;
+}

package/src/form-decode.ts

@@ -5,6 +5,7 @@
 // It converts and never validates: a value that will not convert is passed through as the string
 // that was typed, so the schema refuses it in its own words against the field that carried it.
 
+import { numeric } from '@ultimat3/schema';
 import type { AdminField } from './fields';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
@@ -72,10 +73,15 @@ const TYPED: ReadonlySet<AdminField['widget']> = new Set([
 const blank = (field: AdminField): unknown =>
   field.required && !TYPED.has(field.widget) ? '' : null;
 
-const numberOf = (raw: string): unknown => {
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) ? parsed : raw;
-};
+/**
+ * Schema's own decimal reader, never `Number(raw)`: that reads hex, binary and octal too, so `0x10`
+ * in a money box was stored as `minor: 16`. Anything else is handed on as typed for the schema to
+ * refuse against the field. Whitespace never reaches here — `decodeField` blanks it first.
+ */
+const numberOf = (raw: string): unknown => numeric(raw) ?? raw;
+
+/** The widgets that hold a number: a box of only whitespace is as empty as `''` for them. */
+const NUMERIC: ReadonlySet<AdminField['widget']> = new Set(['money', 'number-input']);
 
 const jsonOf = (raw: string): unknown => {
   try {
@@ -91,6 +97,9 @@ function decodeField(field: AdminField, form: Posted): unknown {
   // An unchecked box posts nothing at all, so absence IS the answer for a checkbox.
   if (field.widget === 'checkbox') return raw !== undefined && raw !== 'false';
   if (raw === undefined || raw === '') return blank(field);
+  // `Number(' ')` is 0, so a space in an untouched optional number box was a write of 0 over a
+  // stored null — a change the audit diff then attributed to the operator.
+  if (NUMERIC.has(field.widget) && raw.trim() === '') return blank(field);
   switch (field.widget) {
     case 'number-input':
       return numberOf(raw);

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   type AdminActionButton,
   actionButtons,
   actionDecisions,
+  adminPermissionForAction,
   decideAction,
   type InvokeInput,
   type InvokeResult,
@@ -77,24 +78,22 @@ export {
   deniedDraft,
   diffRows,
   memoryAuditLog,
-  REDACTED,
 } from './audit';
 export {
   type PostgresAuditLogOptions,
   postgresAuditLog,
-  SQL_ADMIN_AUDIT_INSERT,
 } from './audit-pg';
-export { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from './audit-schema';
+// The audit table's DDL is `@ultimat3/admin/schema`'s alone — one import path for one statement.
 export {
   type AdminActor,
   type AdminAuthz,
   type AdminAuthzQuery,
   type AdminDecision,
   type AdminSubject,
-  allowed,
+  adminAllowed,
+  adminDenied,
   anonymousAuthz,
   decideAll,
-  denied,
   expandPermissions,
   isAllowed,
   staticAuthz,
@@ -198,7 +197,7 @@ export { currencyFieldOf, decodeForm, posted } from './form-decode';
 export { JOB_MANAGE, JOB_READ } from './jobs/job-actions';
 export { JOB_ENTITY } from './jobs/job-entities';
 export { JOBS_PATH, jobRowScope } from './jobs/job-resources';
-export { AdminLayout, type AdminLayoutProps, actorLabel } from './layout';
+export { AdminLayout, type AdminLayoutProps, adminActorLabel } from './layout';
 export { AdminList, type AdminListProps } from './list';
 export { type ResourceColumnsInput, resourceColumns } from './list-columns';
 export { AdminFilterBar, type AdminFilterBarProps } from './list-filter-bar';
@@ -230,12 +229,14 @@ export {
 } from './list-scope';
 export { AdminScopeTabs, type AdminScopeTabsProps } from './list-scope-tabs';
 export {
+  type AdminMcpActor,
   type AdminMcpOptions,
   type AdminToolResult,
   adminMcp,
   callAdminTool,
   type McpInput,
 } from './mcp';
+export { adminTokenScopes, adminToolScopes } from './mcp-scopes';
 export {
   type AdminMcpTool,
   type AdminToolField,
@@ -341,8 +342,8 @@ export {
   labelOf,
   type RelationData,
   type RelationNeed,
+  relationDataFor,
   relationNeeds,
-  relationsFor,
 } from './relations';
 export { ComputedCell, TRUNCATE_AT } from './renderers';
 export { adminEntitiesOf, adminRepoFor, adminTablesOf } from './repo-entity';

package/src/jobs/operator.ts

@@ -21,13 +21,13 @@ export function jobsOperator(): JobsOperator {
     throw new DriverUnavailableError({
       driver: 'none',
       cause: 'the jobs dashboard was asked for rows and this process installed no queue',
-      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: setJobDriver(createMemoryDriver())',
+      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: setJobDriver(memoryJobDriver())',
     });
   }
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — the pg and memory drivers implement introspect',
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg and memory drivers implement introspect',
     });
   }
   return { driver, introspect: driver.introspect };

package/src/jobs/overview-tab.tsx

@@ -2,7 +2,7 @@
 // own queue (the dev driver under `x dev`) — one jobs UI, not a second one in the dev panel. Only
 // ever reached by `dev/panel-jobs.ts`'s dynamic `import()`, so `/_x`'s mount graph stays free of it.
 
-import { createContext, runWithContext } from '@ultimat3/core';
+import { ctxOf, runWithContext } from '@ultimat3/core';
 import { renderToHtml } from '@ultimat3/render/server';
 import { listHref } from '../list-request';
 import { adminMounts } from '../mounts';
@@ -33,7 +33,7 @@ export async function jobsTabHtml(tabPath: string, params: URLSearchParams): Pro
   const json = `${tabPath}?json=1`;
   const data = await overviewData(range, Date.now());
   // The framework catalog's locale for every label, whatever the app's default is.
-  return runWithContext(createContext({ locale: 'en', tz: 'UTC' }), () =>
+  return runWithContext(ctxOf({ locale: 'en', tz: 'UTC' }), () =>
     renderToHtml(
       <JobsOverview
         data={data}

package/src/layout.tsx

@@ -1,14 +1,18 @@
 // The admin shell: skip link, sidebar (brand, who is acting, search, permission-filtered nav, the
 // way back to the app), main region. Landmarks and a visible focus order are the accessibility
 // contract; the theme attributes come from the token system, so nothing here knows a colour.
-// Every control is a link or a native form — the shell ships no script.
+// Every control is a link, a native form or a native popover — the shell ships no script: below
+// `md` the sidebar is a `popover` panel the menu button opens by `popovertarget`, and an engine
+// with no popovers keeps it as a block above the screen (`admin.module.scss`).
 
 // why: `*.module.scss` is typed by ONE ambient declaration, and it is `@ultimat3/ui`'s. A copy
 // here would be a `.d.ts` in `src/`, which the package-shape gate reads as a build artifact.
 /// <reference path="../../ui/src/scss.d.ts" />
 
 import { t } from '@ultimat3/i18n';
-import { Input } from '@ultimat3/ui';
+import { Icon, Input, UI_KEYS } from '@ultimat3/ui';
+import { iconMenu } from '@ultimat3/ui/icons/menu';
+import { iconX } from '@ultimat3/ui/icons/x';
 import type { JSX } from 'solid-js';
 import type { AdminApp } from './admin';
 import styles from './admin.module.scss';
@@ -27,8 +31,11 @@ export interface AdminLayoutProps {
   readonly children: JSX.Element;
 }
 
+/** The panel's id: the menu button and the close button both name it. */
+const SIDE_ID = 'x-admin-side';
+
 /** The one rendering of "who am I acting as", so no two screens can disagree about it. */
-export const actorLabel = (actor: AdminActor | null | undefined): string =>
+export const adminActorLabel = (actor: AdminActor | null | undefined): string =>
   actor === null || actor === undefined || actor.id === 'anonymous'
     ? t('admin.actor.anonymous')
     : t('admin.actor.signedIn', { id: actor.id, roles: (actor.roles ?? []).join(', ') });
@@ -44,10 +51,29 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
       data-density={theme['data-density']}
       style={theme.style}
     >
-      <aside class={styles['side']}>
-        <a class={styles['skip']} href="#x-admin-main">
-          {t('admin.a11y.skip-to-content')}
-        </a>
+      {/* Ahead of the panel, not inside it: a closed panel is `display: none`, and so would be
+          the first Tab stop on every admin screen. */}
+      <a class={styles['skip']} href="#x-admin-main">
+        {t('admin.a11y.skip-to-content')}
+      </a>
+
+      <div class={styles['bar']}>
+        <button type="button" class={styles['menuButton']} popovertarget={SIDE_ID}>
+          <Icon glyph={iconMenu} size="md" />
+          {t(UI_KEYS.menu)}
+        </button>
+      </div>
+
+      <aside id={SIDE_ID} class={styles['side']} popover="auto">
+        <button
+          type="button"
+          class={styles['close']}
+          popovertarget={SIDE_ID}
+          popovertargetaction="hide"
+          aria-label={t(UI_KEYS.close)}
+        >
+          <Icon glyph={iconX} size="md" />
+        </button>
 
         <a class={styles['brand']} href={base}>
           {props.app.branding.logo === undefined ? null : (
@@ -59,7 +85,7 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           )}
           <span>{t(props.app.branding.nameKey)}</span>
         </a>
-        <p class={styles['actor']}>{actorLabel(props.actor)}</p>
+        <p class={styles['actor']}>{adminActorLabel(props.actor)}</p>
 
         {/* A native GET at the search route: the term rides the URL, so a result page is a link
             an operator can send and the form needs no handler. */}

package/src/list.tsx

@@ -139,7 +139,7 @@ export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX
           rows={page.rows}
           rowKey={idOf}
           sort={{ key: page.sort.field, direction: page.sort.direction }}
-          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          nextCursor={page.hasMore ? page.nextCursor : undefined}
           prevCursor={page.prevCursor ?? undefined}
           hrefFor={(cursor) => props.hrefFor({ ...state, cursor })}
           // The header's NEXT state, as a URL. "Unsorted" is the list with no sort in it — the

package/src/mcp-scopes.ts

@@ -0,0 +1,36 @@
+// The admin MCP surface's scopes: which admin permission each tool needs as a token scope, and
+// what a resolved token carries. The gate itself is `@ultimat3/mcp`'s registry — this file only
+// declares the cut (`defineAppMcp({ scopes })`) and the token's half of it.
+
+import type { McpScopes } from '@ultimat3/mcp';
+import { expandPermissions } from './authz';
+import type { AdminMcpTool } from './mcp-tools';
+import { ADMIN_DESTROY, ADMIN_PERMISSIONS } from './permissions';
+
+const isAdminPermission = (scope: string): boolean =>
+  (ADMIN_PERMISSIONS as readonly string[]).includes(scope);
+
+/**
+ * The scopes a token resolved to, as the registry checks them: by string membership, so the
+ * admin's implications are expanded here (`admin:destroy` ⇒ `admin:write` ⇒ `admin:read`) and a
+ * token granted `admin:write` is not refused a read.
+ *
+ * `undefined` — the app's resolver stated no scopes — is a token as strong as its actor: every
+ * admin scope, with the actor's own policy still deciding each tool. That is what every admin MCP
+ * token was before tools carried a scope, so an app that never issued a narrower token is
+ * unchanged. An EMPTY list is a token granted nothing, never "unstated". A scope that is no admin
+ * permission (`posts:write`) is dropped: the admin's tools are gated on its own vocabulary only.
+ */
+export function adminTokenScopes(granted: readonly string[] | undefined): ReadonlySet<string> {
+  return new Set(expandPermissions(granted ?? [ADMIN_DESTROY]).filter(isAdminPermission));
+}
+
+/**
+ * Scope → the tools it covers, for `defineAppMcp({ scopes })`. Every tool is in exactly one entry
+ * (its `scope`), so the map is total by construction and `X_MCP_SCOPE_UNCOVERED` cannot fire.
+ */
+export function adminToolScopes(tools: readonly AdminMcpTool[]): McpScopes {
+  const by = new Map<string, string[]>();
+  for (const tool of tools) by.set(tool.scope, [...(by.get(tool.scope) ?? []), tool.name]);
+  return Object.fromEntries(by);
+}