@ultimat3/admin 22.15.0 → 24.0.0

package/src/detail.tsx

@@ -1,16 +1,21 @@
-// The detail view: every field as a labelled read-only row, the audit trail for this row,
-// and the actions this actor may run on it. Loading and error states are first-class, not an
-// afterthought — a detail page with no row is a state, not a blank card.
+// The detail view: the row's fields in their sections, the related resources' own lists filtered
+// to this row, the row's history, and the actions this actor may run on it — each a link or a
+// native form, so the screen ships no script. A detail page with no row is a state, not a card.
 
 import { t } from '@ultimat3/i18n';
-import { Card, ErrorState } from '@ultimat3/ui';
+import { Button, Card, DataTable, ErrorState, Link } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
-import type { AdminActionButton } from './action-gate';
-import { AdminActions } from './actions';
-import type { AuditEntry } from './audit';
+import { AdminActions, ConfirmationField, DELETE_OPERATION, OPERATION_FIELD } from './actions';
+import styles from './admin.module.scss';
+import type { AuditCursor, AuditEntry } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
 import { type AdminErrorParts, adminErrorFrom } from './errors';
+import { valueText } from './json-text';
+import { resourceColumns } from './list-columns';
+import { confirmationToken } from './permissions';
 import type { AdminRow } from './registry';
+import { rowId } from './registry';
+import type { AdminRelatedList } from './related';
 import type { AdminResource } from './resource';
 import type { WidgetContext } from './widget-value';
 import { Widget } from './widgets';
@@ -18,19 +23,24 @@ import { Widget } from './widgets';
 export interface AdminDetailProps<Row extends AdminRow> {
   readonly resource: AdminResource<Row>;
   readonly row: Row | null;
-  readonly loading: boolean;
   readonly error: AdminErrorParts | null;
   readonly ctx: WidgetContext;
   readonly actor: AdminActor;
   readonly authz: AdminAuthz;
+  /** This row's history, newest first: one keyset page of what changed it or was refused. */
   readonly audit: readonly AuditEntry[];
+  /** The URL of the next, older page of the history, or `null` when this page is the last. */
+  readonly olderHref?: string | null;
+  /** Each declared related resource's own list, filtered to this row. */
+  readonly related?: readonly AdminRelatedList[];
+  /** The URL of a related resource's list, filtered to this row — "everything", one link away. */
+  readonly relatedHref?: (list: AdminRelatedList) => string;
   readonly basePath: string;
-  readonly pending?: AdminActionButton | null;
-  readonly confirmation?: string;
-  readonly onRun?: (button: AdminActionButton, confirmation: string) => void;
-  readonly onRequestConfirm?: (button: AdminActionButton) => void;
-  readonly onConfirmationInput?: (value: string) => void;
-  readonly onCancel?: () => void;
+  /**
+   * What the gate already decided about THIS row, so the view renders a control only for an
+   * operation the POST behind it would allow. Absent reads as "not allowed".
+   */
+  readonly may?: { readonly update: boolean; readonly delete: boolean };
 }
 
 /**
@@ -49,13 +59,6 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
   if (props.error !== null) {
     return <ErrorState error={adminErrorFrom(props.error)} />;
   }
-  if (props.loading) {
-    return (
-      <Card header={<h2>{t(props.resource.titleKey)}</h2>}>
-        <p aria-busy="true">{t('admin.detail.loading')}</p>
-      </Card>
-    );
-  }
   if (props.row === null) {
     return (
       <ErrorState
@@ -73,6 +76,7 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
 
   const row = props.row;
   const id = String(row[props.resource.idField] ?? '');
+  const href = `${props.basePath}${props.resource.path}/${id}`;
 
   return (
     <>
@@ -81,31 +85,76 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
           actions={props.resource.actions}
           actor={props.actor}
           authz={props.authz}
-          subject={{ entity: props.resource.name, id }}
-          pending={props.pending ?? null}
-          confirmation={props.confirmation ?? ''}
-          onRun={props.onRun}
-          onRequestConfirm={props.onRequestConfirm}
-          onConfirmationInput={props.onConfirmationInput}
-          onCancel={props.onCancel}
+          subject={{ entity: props.resource.name, id, row }}
+          sealed={props.resource.secretFields.map((field) => field.name)}
+          href={href}
         />
 
-        <dl class="x-admin-detail">
-          {props.resource.fields
-            .filter((field) => !field.sensitive)
-            .map((field) => (
-              <>
-                <dt>{t(field.labelKey)}</dt>
-                <dd>
-                  <Widget field={field} value={row[field.name]} ctx={props.ctx} mode="read" />
-                </dd>
-              </>
-            ))}
-        </dl>
+        {props.resource.sections.map((section) => (
+          <section class={styles['section']}>
+            {section.titleKey === null ? null : <h3>{t(section.titleKey)}</h3>}
+            <dl class={styles['fields']}>
+              {section.fields.map((field) => (
+                <>
+                  <dt>{t(field.labelKey)}</dt>
+                  <dd>
+                    <Widget field={field} value={row[field.name]} ctx={props.ctx} mode="read" />
+                  </dd>
+                </>
+              ))}
+            </dl>
+          </section>
+        ))}
 
-        <a href={`${props.basePath}${props.resource.path}/${id}/edit`}>{t('admin.detail.edit')}</a>
+        <div class={styles['actions']}>
+          {props.may?.update === true ? (
+            <Link appearance="button" variant="secondary" tone="neutral" href={`${href}/edit`}>
+              {t('admin.detail.edit')}
+            </Link>
+          ) : null}
+          {props.may?.delete === true ? (
+            // Destructive, so it re-confirms: the token is on screen to be copied, and typing it
+            // is the deliberate act. A native POST — the row's own URL is the subject.
+            <form class={styles['actionForm']} method="post" action={href}>
+              <input type="hidden" name={OPERATION_FIELD} value={DELETE_OPERATION} />
+              <ConfirmationField token={confirmationToken(props.resource.name, id)} />
+              <Button type="submit" size="sm" variant="secondary" tone="danger">
+                {t('admin.detail.delete')}
+              </Button>
+            </form>
+          ) : null}
+        </div>
       </Card>
 
+      {(props.related ?? []).map((list) => {
+        const target = list.related.resource;
+        const base = `${props.basePath}${target.path}`;
+        return (
+          <Card header={<h2>{t(target.titleKey)}</h2>}>
+            {list.page.rows.length === 0 ? (
+              <p class="x-admin-empty">{t('admin.list.empty')}</p>
+            ) : (
+              <DataTable
+                caption={t(target.titleKey)}
+                // The related resource's OWN columns, minus the key every row here shares.
+                columns={resourceColumns({
+                  resource: target,
+                  ctx: props.ctx,
+                  hrefOf: (rowKey) => `${base}/${rowKey}`,
+                  omit: list.related.field,
+                })}
+                rows={list.page.rows}
+                rowKey={(one) => rowId(one, target.idField)}
+                hrefFor={() => props.relatedHref?.(list) ?? base}
+              />
+            )}
+            {list.page.hasMore && props.relatedHref !== undefined ? (
+              <Link href={props.relatedHref(list)}>{t('admin.related.all')}</Link>
+            ) : null}
+          </Card>
+        );
+      })}
+
       <Card header={<h2>{t('admin.audit.title')}</h2>}>
         {props.audit.length === 0 ? (
           <p class="x-admin-empty">{t('admin.audit.empty')}</p>
@@ -121,8 +170,8 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
                 <ul>
                   {entry.diff.map((change) => (
                     <li>
-                      <code>{change.field}</code>: <del>{String(change.before ?? '')}</del>{' '}
-                      <ins>{String(change.after ?? '')}</ins>
+                      <code>{change.field}</code>: <del>{valueText(change.before)}</del>{' '}
+                      <ins>{valueText(change.after)}</ins>
                     </li>
                   ))}
                 </ul>
@@ -130,7 +179,30 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
             ))}
           </ol>
         )}
+        {props.olderHref === null || props.olderHref === undefined ? null : (
+          <Link href={props.olderHref}>{t('admin.audit.older')}</Link>
+        )}
       </Card>
     </>
   );
 }
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The query parameter an older page of a row's history is asked for by: `?history=<at>~<id>`. */
+export const HISTORY_PARAM = 'history';
+
+/** The cursor as one parameter value — an ISO instant holds no `~`, a uuid neither. */
+export const historyCursorText = (cursor: AuditCursor): string => `${cursor.at}~${cursor.id}`;
+
+/** A posted-back cursor, or `undefined` for anything that is not one: page one, never an error. */
+export function historyCursorOf(raw: string | null): AuditCursor | undefined {
+  if (raw === null) return undefined;
+  const at = raw.indexOf('~');
+  if (at <= 0) return undefined;
+  const instant = raw.slice(0, at);
+  const id = raw.slice(at + 1);
+  // A uuid, because the durable log compares it as one: anything else would be a cast error from
+  // the database where a hand-edited URL deserves page one.
+  return Number.isNaN(Date.parse(instant)) || !UUID.test(id) ? undefined : { at: instant, id };
+}

package/src/dev/data.ts

@@ -155,15 +155,18 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         hydrate: route.hydrate,
         // A descriptor has no `handler`: the FILE is what names the row.
         handler: route.file,
-        // Two flat fields on the descriptor, one nested bag on the fact — the panel's budget
-        // check reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
-        budget: {
-          ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
-          ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
-        },
+        // A flat field on the descriptor, a nested bag on the fact — the panel's budget check
+        // reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
+        budget: route.budgetJs === null ? {} : { js: route.budgetJs },
         // `revalidateTags`, already flattened to keys — never `revalidate.tags`, a shape the
         // descriptor does not have and which answered `[]` for every ISR route in the app.
         revalidateTags: route.revalidateTags,
+        // Present only on a route a package mounted. Copied, never aliased: the fact is a panel
+        // payload, and the registry's own list must not be reachable through it.
+        mount:
+          route.mount === undefined
+            ? null
+            : { by: route.mount.by, permissions: [...route.mount.permissions] },
       }));
     },
 
@@ -211,24 +214,27 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         // field on a descriptor that never carried it, so every job on the panel reported
         // non-idempotent — the opposite of what `job()` refuses to register without.
         idempotent: job.idempotent,
+        concurrency: job.concurrency,
+        onSettled: job.onSettled,
       }));
     },
 
     async queues(): Promise<readonly QueueFact[]> {
-      const { inspectJobList, inspectQueues, jobDriver } = await import('@ultimat3/jobs');
+      const { inspectQueues, jobDriver } = await import('@ultimat3/jobs');
       const driver = jobDriver();
       if (driver === undefined) throw unavailable('queues', 'jobs');
       const report = await inspectQueues(driver);
-      // `stats()` counts states, and a failed job is one of them only until it is retried or
-      // dead-lettered; the honest count comes from the job list, which needs introspection.
-      const failed =
-        driver.introspect === undefined ? [] : await inspectJobList(driver, { state: 'failed' });
+      // A driver with no introspection has nothing to pause a queue with.
+      const paused = new Set((await driver.introspect?.pausedQueues())?.map((entry) => entry.name));
       return report.queues.map((queue) => ({
         name: queue.queue,
         depth: queue.ready + queue.delayed,
         running: queue.running,
-        failed: failed.filter((record) => record.queue === queue.queue).length,
+        // `stats()` has its own `failed` bucket: it was counted off the job LIST, one page of it,
+        // so a queue with more failed rows than a page holds reported the page size.
+        failed: queue.failed,
         deadLetter: queue.dead,
+        paused: paused.has(queue.queue),
       }));
     },
 
@@ -248,6 +254,15 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
           queue: trace.queue,
           status: RUN_STATUS[trace.state],
           attempt: trace.attempt,
+          concurrencyKey: trace.concurrencyKey,
+          progress:
+            trace.progress === null
+              ? null
+              : {
+                  done: trace.progress.done,
+                  total: trace.progress.total,
+                  note: trace.progress.note ?? null,
+                },
           steps: trace.steps.map((step) => ({
             name: step.name,
             status: STEP_STATUS[step.status],

package/src/dev/facts.ts

@@ -20,8 +20,14 @@ export interface RouteFact {
   readonly hydrate: string;
   /** The route's source file: what names the row. A descriptor publishes no handler. */
   readonly handler: string;
-  readonly budget: { readonly js?: string; readonly lcp?: number };
+  readonly budget: { readonly js?: string };
   readonly revalidateTags: readonly string[];
+  /**
+   * `RouteDescriptor.mount` — who mounted a route no surface file declares (`defineAdmin`), and
+   * every permission that gates it. `null` for a file route: nobody mounted it, and `handler` is
+   * then a path an editor can open rather than a package name.
+   */
+  readonly mount: { readonly by: string; readonly permissions: readonly string[] } | null;
 }
 
 /**
@@ -104,6 +110,17 @@ export interface JobDefFact {
    * the app unsafe to retry.
    */
   readonly idempotent: boolean;
+  /**
+   * `JobDescriptor.concurrency` — the declared fleet-wide cap, `null` for none. `keyed` says the
+   * limit holds per `concurrency.key(input)`; the key itself is a RUN's fact (`JobRunFact`).
+   */
+  readonly concurrency: {
+    readonly limit: number;
+    readonly keyed: boolean;
+    readonly whenBusy: 'wait' | 'fail' | null;
+  } | null;
+  /** Whether the job declares an `onSettled` hook — what is told how each run ended. */
+  readonly onSettled: boolean;
 }
 
 export interface QueueFact {
@@ -112,6 +129,8 @@ export interface QueueFact {
   readonly running: number;
   readonly failed: number;
   readonly deadLetter: number;
+  /** A paused queue is claimed by no worker; its depth is work waiting on an operator. */
+  readonly paused: boolean;
 }
 
 export interface JobStepFact {
@@ -128,6 +147,14 @@ export interface JobRunFact {
   readonly queue: string;
   readonly status: 'ok' | 'running' | 'failed' | 'dead';
   readonly attempt: number;
+  /** The concurrency key this run counts under — `null` unless its job declares a keyed cap. */
+  readonly concurrencyKey: string | null;
+  /** What the body last reported through `progress()`; `null` until it reports. */
+  readonly progress: {
+    readonly done: number;
+    readonly total: number;
+    readonly note: string | null;
+  } | null;
   readonly steps: readonly JobStepFact[];
 }
 

package/src/dev/index.ts

@@ -48,3 +48,4 @@ export {
   devDashboard,
   devShellStyle,
 } from './server';
+export { DEV_SQL_MAX_ROWS, readOnlySql } from './sql-runner';

package/src/dev/panel-cache.ts

@@ -2,6 +2,7 @@
 // Kills: "why is this page still stale?" — the tag graph, and the invalidation log showing
 // what busted what.
 
+import { DevSourceUnavailableError } from '../errors';
 import type { CacheEdgeFact, InvalidationFact } from './facts';
 import type { DevPanel } from './panel';
 
@@ -23,11 +24,15 @@ export const cachePanel: DevPanel<CachePanelData> = {
   questionKey: 'dev.panel.cache.question',
   async data(sources): Promise<CachePanelData> {
     const graph = await sources.cacheGraph();
-    // The invalidation log needs a running process that has served a write; the graph alone
-    // is still worth showing.
+    // The invalidation log needs a running process that has served a write; the graph alone is
+    // still worth showing when it is NOT WIRED — and only then. A log that is wired and failed is
+    // a diagnostic, not "no invalidations yet".
     const invalidations = await sources
       .invalidations()
-      .catch((): readonly InvalidationFact[] => []);
+      .catch((error: unknown): readonly InvalidationFact[] => {
+        if (!(error instanceof DevSourceUnavailableError)) throw error;
+        return [];
+      });
 
     const busted = new Set(invalidations.flatMap((event) => event.busted));
     // A `Map`, then `Object.fromEntries` — never `count[key] = (count[key] ?? 0) + 1` on a plain

package/src/dev/panel-db.ts

@@ -8,8 +8,31 @@ import { DevSourceUnavailableError } from '../errors';
 import type { DriftFact, SqlResult, TableFact } from './facts';
 import type { DevPanel } from './panel';
 
+/**
+ * Where the whole schema can be READ, as SQL: the dump `x db gen` writes from the migrations, one
+ * file per table, with the framework's own tables under `framework/`. The table list above it is
+ * what THIS database holds; the dump is what the migrations say every database holds, and the
+ * gate keeps it true (`X_SCHEMA_DUMP_DRIFT`).
+ *
+ * A path and a command, not a URL: `/_x` serves no files, and the panel's job is to say where to
+ * look. The directory is `@ultimat3/cli`'s `SCHEMA_DUMP_DIR` repeated — this package sits below
+ * the CLI and cannot import it — and `packages/cli/src/db-schema-dump.test.ts` holds the two equal.
+ */
+export interface SchemaDumpLink {
+  /** App-root-relative, POSIX. */
+  readonly directory: string;
+  /** The one command that rewrites it. */
+  readonly regenerate: string;
+}
+
+const SCHEMA_DUMP: SchemaDumpLink = Object.freeze({
+  directory: 'packages/db/schema',
+  regenerate: 'x db gen',
+});
+
 export interface DbPanelData {
   readonly tables: readonly TableFact[];
+  readonly schemaDump: SchemaDumpLink;
   /**
    * `null` when no host wired the check — NOT `[]`. Drift is the entities against the database,
    * so it needs the connection this process may not have, and an empty list reads as "the schema
@@ -58,7 +81,7 @@ function sanitize(sql: string): string {
 /**
  * Read-only is enforced here, not just in the UI: /_x runs with the developer's own DB
  * credentials, so "the textarea only sends SELECTs" would be the whole safety story.
- * `x db psql --write` is the deliberate way out.
+ * The developer's own client (`psql "$DATABASE_URL"`) is the deliberate way out.
  *
  * ONE implementation of "is this a read", and it is `@ultimat3/mcp`'s. That guard refuses four
  * things this file's own keyword scan never did — a batch of statements, a call into the
@@ -106,11 +129,11 @@ export function assertReadOnly(sql: string): ReadOnlyVerdict {
     if (!isUltimateError(error)) throw error;
     // Two classes arrive through one code, and the panel cannot tell them apart without reading
     // another package's prose — so the way out is phrased to be true for both. It used to assert
-    // `Run it with: x db psql --write`, which is the wrong instruction for a missing quote: that
-    // flag grants writes, it does not close a delimiter.
+    // `Run it with: x db psql --write`, which is the wrong instruction for a missing quote — and
+    // named a command `x db` never had. The way out for a write is the developer's own client.
     return {
       kind: 'refused',
-      refused: `refused: ${error.cause}. Fix the statement, or — if it is meant to write — run it with: x db psql --write`,
+      refused: `refused: ${error.cause}. Fix the statement, or — if it is meant to write — run it in your own client: psql "$DATABASE_URL"`,
     };
   }
 }
@@ -132,7 +155,15 @@ export const dbPanel: DevPanel<DbPanelData> = {
     ]);
     const sql = params.get('sql');
     if (sql === null || sql.trim() === '') {
-      return { tables, drift, sql: null, result: null, refused: null, readOnly: true };
+      return {
+        tables,
+        schemaDump: SCHEMA_DUMP,
+        drift,
+        sql: null,
+        result: null,
+        refused: null,
+        readOnly: true,
+      };
     }
 
     // `verdict.sql`, never `sql`: what the guard proved read-only is what runs. `sql` below is
@@ -140,6 +171,7 @@ export const dbPanel: DevPanel<DbPanelData> = {
     const verdict = assertReadOnly(sql);
     return {
       tables,
+      schemaDump: SCHEMA_DUMP,
       drift,
       sql,
       result: verdict.kind === 'runnable' ? await sources.runSql(verdict.sql) : null,

package/src/dev/panel-jobs.ts

@@ -74,4 +74,12 @@ export const jobsPanel: DevPanel<JobsPanelData> = {
       backfillsInFlight: backfills.filter((pass) => pass.status === 'running').length,
     };
   },
+  /**
+   * 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.
+   */
+  async html(params, tabPath) {
+    const { jobsTabHtml } = await import('../jobs/overview-tab');
+    return jobsTabHtml(tabPath, params);
+  },
 };

package/src/dev/panel-routes.ts

@@ -13,6 +13,11 @@ export interface RoutesPanelData {
   // no member it could ever hold — and it was published from a `RouteFact.hasMeta` that read a
   // key no descriptor has, which made it name EVERY route instead. See `RouteFact` in `facts.ts`.
   readonly overBudget: readonly string[];
+  /**
+   * Routes no surface file declares, counted per mounting call — `{ defineAdmin: 14 }`. Each row's
+   * own `mount` names its permissions; this is the line that says an admin is mounted at all.
+   */
+  readonly mountedBy: Readonly<Record<string, number>>;
 }
 
 const BUDGET_LIMIT_KB = 40;
@@ -35,6 +40,10 @@ export const routesPanel: DevPanel<RoutesPanelData> = {
     const counts = new Map<string, number>();
     for (const route of routes) counts.set(route.render, (counts.get(route.render) ?? 0) + 1);
     const byRenderMode = Object.fromEntries(counts);
+    const mounts = new Map<string, number>();
+    for (const route of routes) {
+      if (route.mount !== null) mounts.set(route.mount.by, (mounts.get(route.mount.by) ?? 0) + 1);
+    }
     return {
       // Code units, never `localeCompare`: with no locale argument it answers from the runtime's
       // ICU default locale and collation version, so the same route table reads in a different
@@ -46,6 +55,7 @@ export const routesPanel: DevPanel<RoutesPanelData> = {
       overBudget: routes
         .filter((route) => kb(route.budget.js) > BUDGET_LIMIT_KB)
         .map((route) => route.path),
+      mountedBy: Object.fromEntries(mounts),
     };
   },
 };

package/src/dev/panel-timeline.ts

@@ -3,6 +3,7 @@
 // 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';
 
@@ -68,8 +69,12 @@ export const timelinePanel: DevPanel<TimelinePanelData> = {
       (wanted === null ? traces[0] : traces.find((trace) => trace.requestId === wanted)) ?? null;
     // Degrade rather than reject, as `panel-live.ts` does for `subscribers`: a host with traces
     // but no detector installed must still get its flamegraph. `null` carries that difference —
-    // "nobody counted" is not "counted, and this request was clean".
-    const loops = await sources.statementLoops().catch((): null => null);
+    // "nobody counted" is not "counted, and this request was clean". Only for the error that MEANS
+    // unwired: a detector that ran and failed is a diagnostic, never "no detector".
+    const loops = await sources.statementLoops().catch((error: unknown): null => {
+      if (!(error instanceof DevSourceUnavailableError)) throw error;
+      return null;
+    });
 
     const totalsByKind: Record<string, number> = {};
     const sqlCounts = new Map<string, number>();

package/src/dev/panel.ts

@@ -2,7 +2,7 @@
 // draws — and because `data()` returns plain JSON, `--json` and the rendered tab are the
 // same facts by construction.
 
-import { renderThrowable, stringField } from '@ultimat3/core';
+import { InternalError, renderThrowable, stringField } from '@ultimat3/core';
 import type { DevSources } from './facts';
 
 export interface DevPanel<Data = unknown> {
@@ -16,6 +16,12 @@ export interface DevPanel<Data = unknown> {
    */
   readonly questionKey: string;
   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.
+   */
+  html?(params: URLSearchParams, tabPath: string): Promise<string>;
 }
 
 export type PanelPayload =
@@ -47,7 +53,9 @@ export async function panelPayload(
       panel: panel.key,
       ok: false,
       error: {
-        code: stringField(error, 'code') ?? 'X_NOT_IMPLEMENTED',
+        // Core's code for a failure nothing classified. `X_NOT_IMPLEMENTED` was here, and it told
+        // the reader a feature was missing when a source had thrown something with no code at all.
+        code: stringField(error, 'code') ?? InternalError.code,
         cause: stringField(error, 'cause') ?? renderThrowable(error),
         fix: stringField(error, 'fix') ?? 'x dev --help',
       },

package/src/dev/server.ts

@@ -4,7 +4,7 @@
 
 // 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, tryResolveEnvironment } from '@ultimat3/core';
+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';
@@ -85,9 +85,6 @@ const jsonResponse = (body: unknown, status = 200): Response =>
     headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
   });
 
-const escapeHtml = (value: string): string =>
-  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-
 /** The six roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. */
 const SHELL_ROLES = [
   'bg',
@@ -170,6 +167,8 @@ function shell(
   panels: readonly DevPanel[],
   active: DevPanel,
   payload: PanelPayload,
+  /** The panel's own drawing, when it has one; the payload follows it, folded. */
+  drawn: string | null,
 ): string {
   const tabs = panels
     .map(
@@ -186,7 +185,11 @@ function shell(
 <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>
-<pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre></main></body></html>`;
+${
+  drawn === null
+    ? `<pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre>`
+    : `${drawn}<details><summary>--json</summary><pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre></details>`
+}</main></body></html>`;
 }
 
 /** Build the dashboard. Throws X_DEV_DASHBOARD_IN_PROD before anything else happens. */
@@ -232,12 +235,14 @@ export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
         url.searchParams.has('json') ||
         (request.headers.get('accept') ?? '').includes('application/json');
 
-      return wantsJson
-        ? jsonResponse(payload, payload.ok ? 200 : 500)
-        : new Response(shell(await devShellStyle(), basePath, panels, panel, payload), {
-            status: 200,
-            headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
-          });
+      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), {
+        status: 200,
+        headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+      });
     },
   };
 }