@ultimat3/admin 1.0.0

package/src/dev/panel-jobs.ts

@@ -0,0 +1,66 @@
+// Panel: Jobs.
+// Kills: "is the queue moving, and which step failed?" — queue depth, per-run step traces,
+// the retry-from-step target, and the dead letter.
+
+import type { JobDefFact, JobRunFact, QueueFact, TaskFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface RetryTarget {
+  readonly runId: string;
+  readonly job: string;
+  /** The first failed step: retrying from here replays nothing that already succeeded. */
+  readonly fromStep: string;
+  readonly attempt: number;
+  readonly error: string;
+}
+
+export interface JobsPanelData {
+  readonly queues: readonly QueueFact[];
+  readonly jobs: readonly JobDefFact[];
+  readonly tasks: readonly TaskFact[];
+  readonly runs: readonly JobRunFact[];
+  readonly deadLetter: readonly JobRunFact[];
+  readonly retryTargets: readonly RetryTarget[];
+  readonly totalDepth: number;
+}
+
+const firstFailedStep = (run: JobRunFact): RetryTarget | null => {
+  const step = run.steps.find((candidate) => candidate.status === 'failed');
+  if (step === undefined) return null;
+  return {
+    runId: run.id,
+    job: run.job,
+    fromStep: step.name,
+    attempt: step.attempt,
+    error: step.error ?? '',
+  };
+};
+
+export const jobsPanel: DevPanel<JobsPanelData> = {
+  key: 'jobs',
+  titleKey: 'dev.panel.jobs',
+  question: 'is the queue moving, and which step failed?',
+  async data(sources, params): Promise<JobsPanelData> {
+    const [queues, jobs, tasks, runs] = await Promise.all([
+      sources.queues(),
+      sources.jobDefs(),
+      sources.tasks(),
+      sources.jobRuns(),
+    ]);
+    const queueFilter = params.get('queue');
+    const scoped = queueFilter === null ? runs : runs.filter((run) => run.queue === queueFilter);
+
+    return {
+      queues,
+      jobs,
+      tasks,
+      runs: scoped,
+      deadLetter: scoped.filter((run) => run.status === 'dead'),
+      retryTargets: scoped
+        .filter((run) => run.status === 'failed' || run.status === 'dead')
+        .map(firstFailedStep)
+        .filter((target): target is RetryTarget => target !== null),
+      totalDepth: queues.reduce((sum, queue) => sum + queue.depth, 0),
+    };
+  },
+};

package/src/dev/panel-live.ts

@@ -0,0 +1,46 @@
+// Panel: Live query inspector.
+// Kills: "why did (or didn't) this subscriber get that row?" — every subscriber, what it
+// received, and the matcher's decision trace beside it.
+
+import type { LiveQueryFact, LiveSubscriberFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface LivePanelData {
+  readonly queries: readonly LiveQueryFact[];
+  readonly subscribers: readonly LiveSubscriberFact[];
+  /** Registered live queries with nobody attached — usually a client that never subscribed. */
+  readonly idleQueries: readonly string[];
+  /** Subscribers the matcher rejected, with the reason kept next to them. */
+  readonly rejected: readonly {
+    readonly id: string;
+    readonly query: string;
+    readonly trace: readonly string[];
+  }[];
+  readonly note: string | null;
+}
+
+export const livePanel: DevPanel<LivePanelData> = {
+  key: 'live',
+  titleKey: 'dev.panel.live',
+  question: 'what does each subscriber receive, and why?',
+  async data(sources, params): Promise<LivePanelData> {
+    const queries = (await sources.liveQueries()).filter((query) => query.live);
+    // The subscriber list needs a running sync node; without one the panel still shows the
+    // registered live queries rather than an empty tab.
+    const subscribers = await sources.subscribers().catch((): readonly LiveSubscriberFact[] => []);
+    const wanted = params.get('query');
+    const scoped =
+      wanted === null ? subscribers : subscribers.filter((sub) => sub.query === wanted);
+    const attached = new Set(subscribers.map((sub) => sub.query));
+
+    return {
+      queries,
+      subscribers: scoped,
+      idleQueries: queries.filter((query) => !attached.has(query.name)).map((query) => query.name),
+      rejected: scoped
+        .filter((sub) => !sub.matched)
+        .map((sub) => ({ id: sub.id, query: sub.query, trace: sub.trace })),
+      note: subscribers.length === 0 ? 'dev.live.no-sync-node' : null,
+    };
+  },
+};

package/src/dev/panel-mail.ts

@@ -0,0 +1,51 @@
+// Panel: Mail.
+// Kills: "what did that email actually look like, in that locale?" — every caught message,
+// rendered, grouped per locale so a missing translation is visible instead of inferred.
+
+import type { MailFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface MailPanelData {
+  readonly messages: readonly MailFact[];
+  readonly selected: MailFact | null;
+  readonly locales: readonly string[];
+  /** Subjects that exist in one locale but not another — a catalog gap, shown as one. */
+  readonly missingLocales: readonly {
+    readonly subject: string;
+    readonly missing: readonly string[];
+  }[];
+}
+
+export const mailPanel: DevPanel<MailPanelData> = {
+  key: 'mail',
+  titleKey: 'dev.panel.mail',
+  question: 'what did that email look like, in that locale?',
+  async data(sources, params): Promise<MailPanelData> {
+    const all = await sources.mail();
+    const locale = params.get('locale');
+    const messages = locale === null ? all : all.filter((mail) => mail.locale === locale);
+    const wanted = params.get('id');
+    const selected =
+      (wanted === null ? messages[0] : messages.find((mail) => mail.id === wanted)) ?? null;
+
+    const locales = [...new Set(all.map((mail) => mail.locale))].sort();
+    const bySubject = new Map<string, Set<string>>();
+    for (const mail of all) {
+      const seen = bySubject.get(mail.subject) ?? new Set<string>();
+      seen.add(mail.locale);
+      bySubject.set(mail.subject, seen);
+    }
+
+    return {
+      messages,
+      selected,
+      locales,
+      missingLocales: [...bySubject.entries()]
+        .map(([subject, seen]) => ({
+          subject,
+          missing: locales.filter((candidate) => !seen.has(candidate)),
+        }))
+        .filter((entry) => entry.missing.length > 0),
+    };
+  },
+};

package/src/dev/panel-manifest.ts

@@ -0,0 +1,39 @@
+// Panel: Manifest.
+// Kills: "is x.manifest.json current?" — the emitted manifest diffed against the committed
+// one, so a forgotten `x manifest` is visible before CI says it.
+
+import type { ManifestFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface ManifestPanelData {
+  readonly manifest: ManifestFact;
+  readonly drifted: boolean;
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly changed: readonly string[];
+  /** The command that makes the diff go away. Printed in the panel and in `--json`. */
+  readonly fix: string;
+}
+
+export const manifestPanel: DevPanel<ManifestPanelData> = {
+  key: 'manifest',
+  titleKey: 'dev.panel.manifest',
+  question: 'is the committed x.manifest.json current?',
+  async data(sources): Promise<ManifestPanelData> {
+    const manifest = await sources.manifest();
+    return {
+      manifest,
+      drifted: manifest.diff.length > 0,
+      added: manifest.diff
+        .filter((entry) => entry.committed === undefined)
+        .map((entry) => entry.path),
+      removed: manifest.diff
+        .filter((entry) => entry.emitted === undefined)
+        .map((entry) => entry.path),
+      changed: manifest.diff
+        .filter((entry) => entry.emitted !== undefined && entry.committed !== undefined)
+        .map((entry) => entry.path),
+      fix: 'x manifest',
+    };
+  },
+};

package/src/dev/panel-policy.ts

@@ -0,0 +1,61 @@
+// Panel: Policy.
+// Kills: "can this actor do that, and why?" — the permission matrix per actor, every cell
+// carrying the decision trace that produced it.
+
+import type { PolicyFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface PolicyRow {
+  readonly permission: string;
+  /** actorId → allowed. The matrix as the panel draws it. */
+  readonly byActor: Readonly<Record<string, boolean>>;
+}
+
+export interface PolicyPanelData {
+  readonly actors: readonly string[];
+  readonly permissions: readonly string[];
+  readonly matrix: readonly PolicyRow[];
+  readonly facts: readonly PolicyFact[];
+  /** The selected cell's trace: `?permission=post:publish&actor=u_1`. */
+  readonly trace: readonly string[];
+  /** Permissions no actor holds — usually a policy nobody can satisfy. */
+  readonly unreachable: readonly string[];
+}
+
+export const policyPanel: DevPanel<PolicyPanelData> = {
+  key: 'policy',
+  titleKey: 'dev.panel.policy',
+  question: 'can this actor do that, and why?',
+  async data(sources, params): Promise<PolicyPanelData> {
+    const facts = await sources.policyMatrix();
+    const actors = [...new Set(facts.map((fact) => fact.actorId))].sort();
+    const permissions = [...new Set(facts.map((fact) => fact.permission))].sort();
+
+    const matrix = permissions.map((permission) => {
+      const byActor: Record<string, boolean> = {};
+      for (const actor of actors) {
+        byActor[actor] =
+          facts.find((fact) => fact.permission === permission && fact.actorId === actor)?.allowed ??
+          false;
+      }
+      return { permission, byActor };
+    });
+
+    const wantedPermission = params.get('permission');
+    const wantedActor = params.get('actor');
+    const selected = facts.find(
+      (fact) => fact.permission === wantedPermission && fact.actorId === wantedActor,
+    );
+
+    return {
+      actors,
+      permissions,
+      matrix,
+      facts,
+      trace: selected?.trace ?? [],
+      unreachable: matrix
+        .filter((row) => Object.values(row.byActor).every((allowed) => !allowed))
+        .map((row) => row.permission),
+    };
+  },
+};

package/src/dev/panel-routes.ts

@@ -0,0 +1,43 @@
+// Panel: Routes.
+// Kills: "which handler serves this?" — the route table with render mode, offline strategy,
+// budget, and whether the route declares meta.
+
+import type { RouteFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface RoutesPanelData {
+  readonly routes: readonly RouteFact[];
+  /** Counts per render mode: an app that is all `ssr` has a caching problem to find. */
+  readonly byRenderMode: Readonly<Record<string, number>>;
+  readonly missingMeta: readonly string[];
+  readonly overBudget: readonly string[];
+}
+
+const BUDGET_LIMIT_KB = 40;
+
+const kb = (budget: string | undefined): number => {
+  if (budget === undefined) return 0;
+  const parsed = Number.parseFloat(budget);
+  return Number.isNaN(parsed) ? 0 : budget.toLowerCase().endsWith('mb') ? parsed * 1024 : parsed;
+};
+
+export const routesPanel: DevPanel<RoutesPanelData> = {
+  key: 'routes',
+  titleKey: 'dev.panel.routes',
+  question: 'which handler serves this?',
+  async data(sources): Promise<RoutesPanelData> {
+    const routes = await sources.routes();
+    const byRenderMode: Record<string, number> = {};
+    for (const route of routes) {
+      byRenderMode[route.render] = (byRenderMode[route.render] ?? 0) + 1;
+    }
+    return {
+      routes: [...routes].sort((a, b) => a.path.localeCompare(b.path)),
+      byRenderMode,
+      missingMeta: routes.filter((route) => !route.hasMeta).map((route) => route.path),
+      overBudget: routes
+        .filter((route) => kb(route.budget.js) > BUDGET_LIMIT_KB)
+        .map((route) => route.path),
+    };
+  },
+};

package/src/dev/panel-timeline.ts

@@ -0,0 +1,82 @@
+// Panel: Request timeline.
+// Kills: "where did the 800ms go?" — a flamegraph of one request: SQL, cache hits, action
+// calls, and policy decisions on one axis, with the N+1 already counted for you.
+
+import type { RequestTrace, SpanKind, TimelineSpan } from './facts';
+import type { DevPanel } from './panel';
+
+export interface FlameRow {
+  readonly span: TimelineSpan;
+  readonly depth: number;
+  /** 0..1 of the request's total duration — the bar's width, computed once, server-side. */
+  readonly offset: number;
+  readonly width: number;
+}
+
+export interface TimelinePanelData {
+  readonly requests: readonly {
+    readonly requestId: string;
+    readonly path: string;
+    readonly totalMs: number;
+  }[];
+  readonly selected: RequestTrace | null;
+  readonly flame: readonly FlameRow[];
+  readonly totalsByKind: Readonly<Record<string, number>>;
+  /** Same SQL text more than once in one request. The N+1 detector. */
+  readonly repeatedSql: readonly { readonly sql: string; readonly count: number }[];
+}
+
+function flatten(trace: RequestTrace): readonly FlameRow[] {
+  const byParent = new Map<string | null, TimelineSpan[]>();
+  for (const span of trace.spans) {
+    const bucket = byParent.get(span.parentId) ?? [];
+    bucket.push(span);
+    byParent.set(span.parentId, bucket);
+  }
+  const total = trace.totalMs === 0 ? 1 : trace.totalMs;
+  const rows: FlameRow[] = [];
+
+  const walk = (parentId: string | null, depth: number): void => {
+    for (const span of (byParent.get(parentId) ?? []).sort((a, b) => a.startMs - b.startMs)) {
+      rows.push({ span, depth, offset: span.startMs / total, width: span.durationMs / total });
+      walk(span.id, depth + 1);
+    }
+  };
+  walk(null, 0);
+  return rows;
+}
+
+export const timelinePanel: DevPanel<TimelinePanelData> = {
+  key: 'timeline',
+  titleKey: 'dev.panel.timeline',
+  question: 'where did the time go in this request?',
+  async data(sources, params): Promise<TimelinePanelData> {
+    const traces = await sources.traces();
+    const wanted = params.get('requestId');
+    const selected =
+      (wanted === null ? traces[0] : traces.find((trace) => trace.requestId === wanted)) ?? null;
+
+    const totalsByKind: Record<string, number> = {};
+    const sqlCounts = new Map<string, number>();
+    for (const span of selected?.spans ?? []) {
+      const kind: SpanKind = span.kind;
+      totalsByKind[kind] = (totalsByKind[kind] ?? 0) + span.durationMs;
+      if (kind === 'sql') sqlCounts.set(span.detail, (sqlCounts.get(span.detail) ?? 0) + 1);
+    }
+
+    return {
+      requests: traces.map((trace) => ({
+        requestId: trace.requestId,
+        path: trace.path,
+        totalMs: trace.totalMs,
+      })),
+      selected,
+      flame: selected === null ? [] : flatten(selected),
+      totalsByKind,
+      repeatedSql: [...sqlCounts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([sql, count]) => ({ sql, count }))
+        .sort((a, b) => b.count - a.count),
+    };
+  },
+};

package/src/dev/panel.ts

@@ -0,0 +1,58 @@
+// What a /_x panel is. One panel per file, each one an introspection call plus the shape it
+// draws — and because `data()` returns plain JSON, `--json` and the rendered tab are the
+// same facts by construction.
+
+import type { DevSources } from './facts';
+
+export interface DevPanel<Data = unknown> {
+  /** URL segment and `--json` selector: `x dev --panel routes --json`. */
+  readonly key: string;
+  readonly titleKey: string;
+  /** The question this panel exists to kill. Rendered as the tab's subtitle. */
+  readonly question: string;
+  data(sources: DevSources, params: URLSearchParams): Promise<Data>;
+}
+
+export type PanelPayload =
+  | { readonly panel: string; readonly ok: true; readonly data: unknown }
+  | {
+      readonly panel: string;
+      readonly ok: false;
+      readonly error: { readonly code: string; readonly cause: string; readonly fix: string };
+    };
+
+interface ErrorFields {
+  readonly code?: unknown;
+  readonly cause?: unknown;
+  readonly fix?: unknown;
+}
+
+/**
+ * A panel whose source is not wired must say so in the panel, with the fix line — the same
+ * payload the CLI prints. A blank tab would read as "nothing is happening".
+ */
+export async function panelPayload(
+  panel: DevPanel,
+  sources: DevSources,
+  params: URLSearchParams,
+): Promise<PanelPayload> {
+  try {
+    return { panel: panel.key, ok: true, data: await panel.data(sources, params) };
+  } catch (error) {
+    const fields = (error ?? {}) as ErrorFields;
+    return {
+      panel: panel.key,
+      ok: false,
+      error: {
+        code: typeof fields.code === 'string' ? fields.code : 'X_NOT_IMPLEMENTED',
+        cause:
+          typeof fields.cause === 'string'
+            ? fields.cause
+            : error instanceof Error
+              ? error.message
+              : String(error),
+        fix: typeof fields.fix === 'string' ? fields.fix : 'x dev --help',
+      },
+    };
+  }
+}

package/src/dev/server.ts

@@ -0,0 +1,189 @@
+// Mounts the /_x panels — and refuses to mount in production, because these panels print
+// SQL, policy traces, and caught mail. The refusal is a throw at construction, not a 404 at
+// request time: an app that boots with /_x mounted in prod has already lost.
+
+import { DevDashboardInProdError } from '../errors';
+import { defaultDevSources } from './data';
+import type { DevSources } from './facts';
+import { type DevPanel, type PanelPayload, panelPayload } from './panel';
+import { cachePanel } from './panel-cache';
+import { dbPanel } from './panel-db';
+import { jobsPanel } from './panel-jobs';
+import { livePanel } from './panel-live';
+import { mailPanel } from './panel-mail';
+import { manifestPanel } from './panel-manifest';
+import { policyPanel } from './panel-policy';
+import { routesPanel } from './panel-routes';
+import { timelinePanel } from './panel-timeline';
+
+export const DEV_PANELS: readonly DevPanel[] = [
+  routesPanel,
+  timelinePanel,
+  livePanel,
+  jobsPanel,
+  dbPanel,
+  mailPanel,
+  cachePanel,
+  policyPanel,
+  manifestPanel,
+];
+
+export const DEV_BASE_PATH = '/_x';
+
+export interface DevDashboardOptions {
+  /** `ROLE` for this process. Defaults to `process.env.ROLE`. */
+  readonly role?: string;
+  /** `NODE_ENV` (or `X_ENV`). Defaults to the environment. */
+  readonly env?: string;
+  readonly basePath?: string;
+  readonly sources?: DevSources;
+  readonly panels?: readonly DevPanel[];
+}
+
+const envOf = (name: string): string | undefined => {
+  const value = process.env[name];
+  return value === undefined || value === '' ? undefined : value;
+};
+
+/**
+ * One rule: anything that says "production" refuses. Checked against both the framework's
+ * `ROLE`-adjacent env and `NODE_ENV`, since a container may set only one of them.
+ */
+export function assertDevOnly(input: {
+  role?: string | undefined;
+  env?: string | undefined;
+}): void {
+  const role = input.role ?? envOf('ROLE') ?? 'dev';
+  const env = input.env ?? envOf('X_ENV') ?? envOf('NODE_ENV') ?? 'development';
+  if (env === 'production' || env === 'prod' || role === 'production' || role === 'prod') {
+    throw new DevDashboardInProdError({ role, env });
+  }
+}
+
+export interface DevDashboard {
+  readonly basePath: string;
+  readonly panels: readonly DevPanel[];
+  /** The `--json` payload for one panel: exactly what the tab renders. */
+  json(key: string, params?: URLSearchParams): Promise<PanelPayload>;
+  /** `null` when the request is not ours, so a host router can fall through. */
+  handle(request: Request): Promise<Response | null>;
+}
+
+const jsonResponse = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body, null, 2), {
+    status,
+    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;');
+
+/** Tokens are defined inline: /_x is a standalone page and still owes both themes. */
+const SHELL_STYLE = `
+:root {
+  --x-color-bg: 253 246 240; --x-color-surface: 255 255 255; --x-color-fg: 38 34 31;
+  --x-color-fg-muted: 110 102 94; --x-color-line: 224 216 208; --x-color-accent: 34 122 197;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --x-color-bg: 18 18 20; --x-color-surface: 34 34 39; --x-color-fg: 228 226 222;
+    --x-color-fg-muted: 150 146 140; --x-color-line: 54 54 60; --x-color-accent: 96 170 240;
+  }
+}
+html[data-theme="light"] {
+  --x-color-bg: 253 246 240; --x-color-surface: 255 255 255; --x-color-fg: 38 34 31;
+  --x-color-fg-muted: 110 102 94; --x-color-line: 224 216 208; --x-color-accent: 34 122 197;
+}
+html[data-theme="dark"] {
+  --x-color-bg: 18 18 20; --x-color-surface: 34 34 39; --x-color-fg: 228 226 222;
+  --x-color-fg-muted: 150 146 140; --x-color-line: 54 54 60; --x-color-accent: 96 170 240;
+}
+body { margin: 0; background: rgb(var(--x-color-bg)); color: rgb(var(--x-color-fg));
+  font: 14px/1.5 ui-monospace, monospace; }
+header { display: flex; gap: 1rem; padding: .75rem 1rem;
+  border-bottom: 1px solid rgb(var(--x-color-line)); flex-wrap: wrap; }
+a { color: rgb(var(--x-color-accent)); }
+main { padding: 1rem; }
+h1 { font-size: 1rem; margin: 0 1rem 0 0; }
+p.question { color: rgb(var(--x-color-fg-muted)); margin: 0 0 1rem; }
+pre { background: rgb(var(--x-color-surface)); 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; }
+`;
+
+function shell(
+  basePath: string,
+  panels: readonly DevPanel[],
+  active: DevPanel,
+  payload: PanelPayload,
+): string {
+  const tabs = panels
+    .map(
+      (panel) =>
+        `<a href="${basePath}/${panel.key}"${panel.key === active.key ? ' aria-current="page"' : ''}>${panel.key}</a>`,
+    )
+    .join(' ');
+
+  return `<!doctype html>
+<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>${SHELL_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(active.question)}</p>
+<pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre></main></body></html>`;
+}
+
+/** Build the dashboard. Throws X_DEV_DASHBOARD_IN_PROD before anything else happens. */
+export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
+  assertDevOnly({ role: opts.role, env: opts.env });
+
+  const basePath = opts.basePath ?? DEV_BASE_PATH;
+  const panels = opts.panels ?? DEV_PANELS;
+  const sources = opts.sources ?? defaultDevSources();
+  const byKey = new Map(panels.map((panel) => [panel.key, panel]));
+
+  const json = async (key: string, params = new URLSearchParams()): Promise<PanelPayload> => {
+    const panel = byKey.get(key);
+    if (panel === undefined) {
+      return {
+        panel: key,
+        ok: false,
+        error: {
+          code: 'X_ADMIN_ENTITY_UNKNOWN',
+          cause: `no /_x panel named "${key}" (have: ${[...byKey.keys()].join(', ')})`,
+          fix: `x dev --panel ${[...byKey.keys()][0] ?? 'routes'}`,
+        },
+      };
+    }
+    return panelPayload(panel, sources, params);
+  };
+
+  return {
+    basePath,
+    panels,
+    json,
+
+    async handle(request: Request): Promise<Response | null> {
+      const url = new URL(request.url);
+      if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) return null;
+
+      const key = url.pathname.slice(basePath.length).replace(/^\//, '');
+      const panel = byKey.get(key === '' ? (panels[0]?.key ?? '') : key);
+      if (panel === undefined) return jsonResponse(await json(key, url.searchParams), 404);
+
+      const payload = await json(panel.key, url.searchParams);
+      const wantsJson =
+        url.searchParams.has('json') ||
+        (request.headers.get('accept') ?? '').includes('application/json');
+
+      return wantsJson
+        ? jsonResponse(payload, payload.ok ? 200 : 500)
+        : new Response(shell(basePath, panels, panel, payload), {
+            status: 200,
+            headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+          });
+    },
+  };
+}