@zerotal/inertia 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -8,6 +8,41 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.6.0] — 2026-08-15
+
+### Added
+
+- **Inertia DevTools support.** Zerotal now implements the server half of the
+  [Inertia DevTools protocol](https://inertiajs.com/docs/v3/advanced/devtools-protocol), so the
+  browser extension shows a timeline of every request: the component that rendered, the route
+  that matched by name, every prop tagged with the wrapper that produced it (`defer` and its
+  group, `optional`, `always`, `merge` and its direction, `once`, `scroll`, and which props came
+  from `share()`), the resolved values, headers, status, and server time. Follow-up requests are
+  grouped with the navigation that caused them, so a page whose deferred props arrive in three
+  later requests reads as one batch.
+
+  On in development, off everywhere else — it follows `devSurfacesEnabled()`, the same gate as the
+  stack-trace error page, so a production deploy records nothing and registers no endpoints.
+  `INERTIA_DEVTOOLS_ENABLED` or `inertia.devtools.enabled` overrides it.
+
+  Sensitive values are redacted **before** an entry is stored rather than when it is served, so a
+  withheld value is never written down: any key containing `password`, `token`, `secret`, and the
+  rest of the built-in list, plus the `authorization` and `cookie` headers. Matching is a
+  case-insensitive substring, so `password` also covers `password_confirmation`. Uploads are
+  summarised instead of inlined, and a prop graph with a cycle records `[Circular]` rather than
+  failing the request. Add your own patterns with `devtools.redact` / `devtools.redactHeaders`.
+
+  Entries live in a bounded in-memory ring (`devtools.maxEntries`, default 200) in the process
+  that recorded them — no disk IO on the request path, no pruning job, and nothing to leak from a
+  directory later. `devtools.except` keeps chosen paths out of the timeline; the read API always
+  excludes itself. Enabling the recorder outside a development process requires a `devtools.gate`,
+  and without one the read API refuses every request rather than defaulting to open.
+
+- **`route()` for pages.** `route`, `defineRoutes`, and `hasRoute` are re-exported from this
+  package, so a page component imports the URL helper from the package it already uses. See
+  `@zerotal/core`'s entry for the full feature. Note that `inertiaRoute()` is a different thing:
+  it **registers** a page route on the server, where `route()` **generates a URL** for one.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,7 +32,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.5.1"
+    "@zerotal/core": "1.6.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/config.ts

@@ -44,6 +44,56 @@ export interface InertiaConfigShape {
    * per request via `Inertia.encryptHistory()` / `clearHistory()`. Default: false.
    */
   encryptHistory: boolean;
+  /** DevTools recorder settings. See {@link InertiaDevtoolsConfig}. */
+  devtools: InertiaDevtoolsConfig;
+}
+
+/**
+ * Server-side recorder for the Inertia DevTools browser extension.
+ *
+ * Off unless this process already exposes dev surfaces (`devSurfacesEnabled()` —
+ * the same gate as the stack-trace error page). The recorder holds resolved
+ * props and request headers in memory and serves them over an unauthenticated
+ * local endpoint, so it has to fail closed: a production deploy that sets no
+ * `APP_ENV` records nothing and registers no routes.
+ *
+ * @see https://inertiajs.com/docs/v3/advanced/devtools
+ */
+export interface InertiaDevtoolsConfig {
+  /**
+   * Turn the recorder on or off explicitly. `null` (the default) follows
+   * `devSurfacesEnabled()`, which is what `INERTIA_DEVTOOLS_ENABLED` sets when
+   * present. Setting `true` here enables it even in production — do that only
+   * behind {@link InertiaDevtoolsConfig.gate}.
+   */
+  enabled: boolean | null;
+  /** How many entries to keep before the oldest is dropped. Default: 200. */
+  maxEntries: number;
+  /**
+   * Extra prop/body key patterns to redact, on top of the built-in list
+   * (`password`, `token`, `secret`, …). Matched as case-insensitive substrings.
+   */
+  redact: string[];
+  /**
+   * Extra header names to redact, on top of the built-in list (`authorization`,
+   * `cookie`, …). Matched case-insensitively.
+   */
+  redactHeaders: string[];
+  /**
+   * Path prefixes that are never recorded. The DevTools read API excludes
+   * itself regardless; this is for the health checks, metrics scrapes, and
+   * dashboards that would otherwise bury the timeline in noise.
+   */
+  except: string[];
+  /**
+   * Authorisation for the read API when the recorder runs outside a dev
+   * process. Receives the request; return `true` to allow.
+   *
+   * Never consulted while `devSurfacesEnabled()` is true, so a developer cannot
+   * lock themselves out of their own machine — which is also why enabling the
+   * recorder in production without setting this is refused at boot.
+   */
+  gate: ((request: Request) => boolean | Promise<boolean>) | null;
 }
 
 /** Default directory (relative to the project root) for Inertia page components. */
@@ -57,8 +107,26 @@ const defaults: InertiaConfigShape = {
   ssr: false,
   ssrSecret: "",
   encryptHistory: false,
+  devtools: {
+    // `null`, not `false`: the recorder follows the process's dev-surface gate
+    // unless an app overrides it, so it is on for `zt dev` and off in
+    // production without anyone configuring anything.
+    enabled: _envFlag("INERTIA_DEVTOOLS_ENABLED"),
+    maxEntries: 200,
+    redact: [],
+    redactHeaders: [],
+    except: [],
+    gate: null,
+  },
 };
 
+/** Read a tri-state boolean env var: unset stays `null` so the dev-surface gate decides. */
+function _envFlag(name: string): boolean | null {
+  const raw = Bun.env[name];
+  if (raw === undefined || raw === "") return null;
+  return !["0", "false", "off", "no"].includes(raw.toLowerCase());
+}
+
 /**
  * Create a typed Inertia configuration object with defaults.
  *

package/src/devtools/api.ts

@@ -0,0 +1,68 @@
+/**
+ * The read API the extension polls: two endpoints, both JSON, both gated.
+ *
+ * Registered as raw routes — no middleware pipeline. These are read by a browser
+ * extension rather than by the application, so the session, CSRF, and Inertia
+ * middleware have nothing to contribute, and running `InertiaDevtoolsMiddleware`
+ * over them would record the act of reading the recordings.
+ */
+import { Router } from "@zerotal/core";
+import { devtoolsAuthorized } from "./enabled.ts";
+import { getEntry, listEntries, parseListQuery, clearEntries } from "./store.ts";
+import { DEVTOOLS_API_PREFIX } from "./types.ts";
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      // The timeline changes every request; a cached copy is always the wrong one.
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+/**
+ * Register `GET /_inertia/devtools/entries` and `.../entries/:id`.
+ *
+ * Called by `InertiaProvider` only when the recorder is enabled, so a production
+ * process that records nothing also serves nothing — the endpoints do not exist
+ * to be probed.
+ */
+export function registerDevtoolsApi(): void {
+  Router.raw(
+    "GET",
+    `${DEVTOOLS_API_PREFIX}/entries`,
+    async (request: Request): Promise<Response> => {
+      if (!(await devtoolsAuthorized(request))) return json({ error: "Forbidden" }, 403);
+      const url = new URL(request.url);
+      return json(listEntries(parseListQuery(url.searchParams)));
+    },
+  );
+
+  Router.raw(
+    "GET",
+    `${DEVTOOLS_API_PREFIX}/entries/:id`,
+    async (request: Request): Promise<Response> => {
+      if (!(await devtoolsAuthorized(request))) return json({ error: "Forbidden" }, 403);
+
+      // Read the id from the URL rather than from route params: this is a raw
+      // route, so nothing has parsed the pattern for us.
+      const id = new URL(request.url).pathname.slice(`${DEVTOOLS_API_PREFIX}/entries/`.length);
+      const entry = getEntry(decodeURIComponent(id));
+      return entry ? json(entry) : json({ error: "Not found" }, 404);
+    },
+  );
+
+  // Not in the protocol, but the panel's "clear" action needs somewhere to go,
+  // and a recorder you cannot reset is one you restart the server to clear.
+  Router.raw(
+    "DELETE",
+    `${DEVTOOLS_API_PREFIX}/entries`,
+    async (request: Request): Promise<Response> => {
+      if (!(await devtoolsAuthorized(request))) return json({ error: "Forbidden" }, 403);
+      clearEntries();
+      return new Response(null, { status: 204 });
+    },
+  );
+}

package/src/devtools/enabled.ts

@@ -0,0 +1,64 @@
+/**
+ * One place that answers "is the recorder on, and for whom".
+ *
+ * Separated from the middleware and the read API because both need the same
+ * answer, and two gates that can disagree is how a dev-only surface ends up
+ * serving request headers in production.
+ */
+import { config, devSurfacesEnabled } from "@zerotal/core";
+import type { InertiaDevtoolsConfig } from "../config.ts";
+import { DEVTOOLS_API_PREFIX } from "./types.ts";
+
+const FALLBACK: InertiaDevtoolsConfig = {
+  enabled: null,
+  maxEntries: 200,
+  redact: [],
+  redactHeaders: [],
+  except: [],
+  gate: null,
+};
+
+/** The `inertia.devtools` config block, with defaults when config is not loaded. */
+export function devtoolsSettings(): InertiaDevtoolsConfig {
+  return { ...FALLBACK, ...config.safe("inertia.devtools", FALLBACK) };
+}
+
+/**
+ * Whether the recorder should run at all.
+ *
+ * `enabled: null` (the default) defers to `devSurfacesEnabled()` — the same gate
+ * as the stack-trace error page — so the recorder is on under `zt dev` and off
+ * in a production deploy without anyone configuring it. An explicit `true` or
+ * `false` wins, which is what makes the recorder testable and what lets an app
+ * run it on a staging box behind a gate.
+ */
+export function devtoolsEnabled(): boolean {
+  return devtoolsSettings().enabled ?? devSurfacesEnabled();
+}
+
+/**
+ * Whether this path is recorded.
+ *
+ * The read API always excludes itself: the extension polls it, and recording
+ * those polls would fill the timeline with the act of reading the timeline.
+ */
+export function isRecordablePath(pathname: string): boolean {
+  if (pathname.startsWith(DEVTOOLS_API_PREFIX)) return false;
+  return !devtoolsSettings().except.some((prefix) => pathname.startsWith(prefix));
+}
+
+/**
+ * Whether this request may read the recorded entries.
+ *
+ * A dev process always may — a gate that can lock a developer out of their own
+ * machine gets switched off, and then nothing is gated. Anywhere else the app's
+ * `gate` decides, and the absence of one is a refusal rather than a default
+ * allow: an app that turned the recorder on in production without saying who
+ * may read it has not made a decision this code should make for it.
+ */
+export async function devtoolsAuthorized(request: Request): Promise<boolean> {
+  if (devSurfacesEnabled()) return true;
+  const gate = devtoolsSettings().gate;
+  if (!gate) return false;
+  return await gate(request);
+}

package/src/devtools/middleware.ts

@@ -0,0 +1,84 @@
+/**
+ * The middleware half of the DevTools protocol: open a recording, stamp the
+ * correlation headers on the way out, and inject the discovery script tag into
+ * the initial HTML.
+ *
+ * Registered automatically by `InertiaProvider` when the recorder is enabled, so
+ * an app adds nothing to its middleware stack. It sits outside `InertiaMiddleware`
+ * so the status it records is the one actually sent — the 302→303 rewrite and the
+ * version-mismatch 409 both happen in there.
+ */
+import type { HttpContext, NextFn } from "@zerotal/core";
+import { BaseMiddleware } from "@zerotal/core";
+import { beginRecording, finishRecording } from "./recorder.ts";
+import { devtoolsEnabled, isRecordablePath } from "./enabled.ts";
+import { DEVTOOLS_REQUEST_HEADERS, DEVTOOLS_RESPONSE_HEADERS } from "./types.ts";
+
+/**
+ * The discovery script tag for the initial full-page response.
+ *
+ * The extension needs the entry id before any XHR happens, and the first
+ * document load has no earlier response to have carried it. The id is a UUID,
+ * so it needs no escaping — but it is JSON-encoded anyway, because the protocol
+ * specifies a JSON string and a bare id would not parse as one.
+ */
+export function devtoolsScriptTag(id: string): string {
+  return `<script data-inertia-devtools-id type="application/json">${JSON.stringify(id)}</script>`;
+}
+
+/** Insert the discovery tag before `</head>`, or before `</body>` if there is no head. */
+function injectScriptTag(html: string, id: string): string {
+  const tag = devtoolsScriptTag(id);
+  if (html.includes("</head>")) return html.replace("</head>", `${tag}</head>`);
+  if (html.includes("</body>")) return html.replace("</body>", `${tag}</body>`);
+  return html + tag;
+}
+
+/**
+ * Records each request for the Inertia DevTools extension.
+ *
+ * @see https://inertiajs.com/docs/v3/advanced/devtools-protocol
+ */
+export class InertiaDevtoolsMiddleware extends BaseMiddleware {
+  protected options: Record<string, never> = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    if (!devtoolsEnabled() || !isRecordablePath(http.url.pathname)) return next();
+
+    const id = beginRecording(http);
+
+    // The batch root: the id the client says started this chain, or this entry
+    // itself when it is the start. Echoing it back lets the extension group a
+    // navigation with the deferred-prop requests it triggers.
+    const parentOut = http.request.headers.get(DEVTOOLS_REQUEST_HEADERS.parent) ?? id;
+
+    const response = await next();
+    if (!response) return;
+
+    const contentType = response.headers.get("Content-Type") ?? "";
+
+    // Never touch a stream: rebuilding the Response to add a header would
+    // transfer the body and can stall a long-lived SSE connection.
+    if (contentType.startsWith("text/event-stream")) return response;
+
+    let out = response;
+
+    // Inject discovery into the initial document. Reading the body is safe here
+    // — an HTML page is buffered, not streamed — and it is the only way the
+    // extension learns the id before the first XHR.
+    if (contentType.includes("text/html")) {
+      const html = await response.text();
+      out = new Response(injectScriptTag(html, id), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    }
+
+    out.headers.set(DEVTOOLS_RESPONSE_HEADERS.id, id);
+    out.headers.set(DEVTOOLS_RESPONSE_HEADERS.parentOut, parentOut);
+
+    finishRecording(http, out, parentOut);
+    return out;
+  }
+}

package/src/devtools/recorder.ts

@@ -0,0 +1,270 @@
+/**
+ * The recorder: turns one request/response pair into one {@link DevtoolsEntry}.
+ *
+ * Recording is split across the request because the data is. The middleware
+ * knows the method, URL, timing and status; only `buildPageObject` knows the
+ * component and which prop wrapper produced which key, and it runs in the
+ * middle. So the middleware opens a recording, the page builder enriches it
+ * while it has the props in hand, and the middleware closes and stores it.
+ *
+ * The in-flight recording is parked on the `HttpContext`, not in a module
+ * variable: concurrent requests share this process, and a module-level "current
+ * entry" would attribute one request's props to another's response under any
+ * real load.
+ */
+import { RequestContext, Router, config } from "@zerotal/core";
+import type { HttpContext } from "@zerotal/core";
+import {
+  AlwaysProp,
+  DeferProp,
+  InertiaProp,
+  InfiniteScrollProp,
+  MergeProp,
+  OptionalProp,
+} from "../props/PropTypes.ts";
+import { allSharedKeys } from "../share.ts";
+import {
+  DEFAULT_REDACTED_HEADERS,
+  DEFAULT_REDACTED_KEYS,
+  redactHeaders,
+  redactValue,
+} from "./redact.ts";
+import { putEntry } from "./store.ts";
+import { DEVTOOLS_REQUEST_HEADERS, type BodyCapture } from "./types.ts";
+import type { DevtoolsEntry, DevtoolsRequestType, PropMeta } from "./types.ts";
+import { devtoolsSettings } from "./enabled.ts";
+
+/** Key under which the in-flight recording is parked on the HttpContext. */
+const RECORDING_KEY = "inertia:devtools:recording";
+
+/** The mutable half of an entry, filled in as the request proceeds. */
+interface Recording {
+  id: string;
+  startedAt: number;
+  timestamp: string;
+  utime: number;
+  component: string | null;
+  props: Record<string, PropMeta>;
+  propValues: Record<string, unknown>;
+}
+
+/**
+ * A collision-resistant id. `crypto.randomUUID()` rather than a ULID: the
+ * protocol asks only for collision resistance, and this needs no dependency.
+ */
+function newId(): string {
+  return crypto.randomUUID();
+}
+
+/** Classify the request from the headers the client sent. */
+function requestTypeOf(request: Request, headers: Headers): DevtoolsRequestType {
+  if (headers.get(DEVTOOLS_REQUEST_HEADERS.deferred) === "1") return "deferred";
+  if (headers.get(DEVTOOLS_REQUEST_HEADERS.poll) === "1") return "poll";
+  if (headers.get("X-Inertia-Precognition") === "true") return "precognition";
+  if (headers.get("X-Inertia-Prefetch") === "true") return "prefetch";
+  if (headers.get("X-Inertia-Partial-Component")) return "partial";
+  // No `X-Inertia` at all means the browser asked for the document itself —
+  // the first load, before the client adapter exists to set the header.
+  if (headers.get("X-Inertia") !== "true") return "initial";
+  return request.method === "GET" ? "navigate" : "http";
+}
+
+/** Begin recording. Returns the entry id, which the caller sets as a response header. */
+export function beginRecording(http: HttpContext): string {
+  const now = Date.now();
+  const recording: Recording = {
+    id: newId(),
+    startedAt: performance.now(),
+    timestamp: new Date(now).toISOString(),
+    utime: now / 1000,
+    component: null,
+    props: {},
+    propValues: {},
+  };
+  http.setInternal(RECORDING_KEY, recording);
+  return recording.id;
+}
+
+/** The in-flight recording for this request, if one was opened. */
+function currentRecording(): Recording | undefined {
+  return RequestContext.tryGet()?.getInternal<Recording>(RECORDING_KEY);
+}
+
+/**
+ * Describe one prop from the wrapper that produced it.
+ *
+ * Mirrors the branches in `resolveProps`; a prop the resolver treats specially
+ * and this does not would show up in the panel as an ordinary prop, which is
+ * the kind of quiet wrongness a debugging tool must not have.
+ */
+function describeProp(value: unknown, key: string, shared: Set<string>): PropMeta {
+  const meta: PropMeta = {};
+  if (shared.has(key)) meta.shared = true;
+
+  if (!(value instanceof InertiaProp)) return meta;
+
+  if (value instanceof AlwaysProp) meta.inertiaType = "always";
+  else if (value instanceof DeferProp) {
+    meta.inertiaType = "defer";
+    meta.deferGroup = value.group;
+  } else if (value instanceof InfiniteScrollProp) meta.inertiaType = "scroll";
+  else if (value instanceof MergeProp) meta.inertiaType = "merge";
+  else if (value instanceof OptionalProp) meta.inertiaType = "optional";
+
+  if (value.isOnce) {
+    // `once` is a modifier, not a wrapper — a prop can be both `merge()` and
+    // `once()`. Recorded as the flag so the wrapper's own type survives, and
+    // only claimed as the *type* when nothing else did.
+    meta.once = true;
+    meta.inertiaType ??= "once";
+  }
+
+  if (value.shouldMerge) {
+    const cfg = value.mergeConfig();
+    if (cfg.deep) meta.deepMerge = true;
+    meta.mergeDirection = cfg.prependRoot || cfg.prependPaths.length > 0 ? "prepend" : "append";
+  }
+
+  return meta;
+}
+
+/**
+ * Attach the component and prop metadata to the in-flight recording.
+ *
+ * Called from `buildPageObject`, which is the only place that sees the raw prop
+ * wrappers *and* the resolved values. A no-op when nothing is recording, so the
+ * call site needs no guard of its own.
+ *
+ * @param component - The page component name.
+ * @param raw - The unresolved prop map (shared + controller), wrappers intact.
+ * @param resolved - The resolved values actually sent to the client.
+ * @param rescued - Keys reported in `rescuedProps`.
+ */
+export function recordPage(
+  component: string,
+  raw: Record<string, unknown>,
+  resolved: Record<string, unknown>,
+  rescued: readonly string[] = [],
+): void {
+  const recording = currentRecording();
+  if (!recording) return;
+
+  const settings = devtoolsSettings();
+  const keyPatterns = [...DEFAULT_REDACTED_KEYS, ...settings.redact];
+  const shared = new Set(allSharedKeys());
+  const rescuedSet = new Set(rescued);
+
+  recording.component = component;
+
+  for (const [key, value] of Object.entries(raw)) {
+    const meta = describeProp(value, key, shared);
+    if (rescuedSet.has(key)) meta.rescued = true;
+    recording.props[key] = meta;
+  }
+
+  for (const [key, value] of Object.entries(resolved)) {
+    recording.propValues[key] = redactValue(value, keyPatterns);
+  }
+}
+
+/** Look up the matched route by path, for the entry's `route` block. */
+function routeInfoFor(http: HttpContext): DevtoolsEntry["route"] {
+  const pathname = http.url.pathname;
+
+  // `namedRoutes` is name → pattern; the panel wants the reverse. Prefer an
+  // exact pattern match, then the first pattern whose params fit — a named
+  // route is more useful in the panel than a bare URI, and the lookup happens
+  // once per recorded request.
+  let name: string | null = null;
+  let uri = pathname;
+  for (const [routeName, pattern] of Router.namedRoutes) {
+    if (pattern === pathname) {
+      name = routeName;
+      uri = pattern;
+      break;
+    }
+    const regex = new RegExp(
+      `^${pattern.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, "[^/]+").replace(/\*/g, ".*")}$`,
+    );
+    if (name === null && regex.test(pathname)) {
+      name = routeName;
+      uri = pattern;
+    }
+  }
+
+  return { uri, name, action: null };
+}
+
+/** Capture a response body, refusing anything that should not be inlined. */
+function captureResponseBody(response: Response, isInertia: boolean): BodyCapture {
+  if (!isInertia) return { status: "omitted", reason: "non-inertia-response" };
+
+  const type = response.headers.get("Content-Type") ?? "";
+  if (type.startsWith("text/event-stream")) return { status: "omitted", reason: "streamed" };
+  if (!type.includes("json")) return { status: "omitted", reason: "non-textual" };
+
+  // The body is not read here: consuming the stream would empty it before the
+  // client got it, and cloning a response on every request costs more than the
+  // panel gains. The page object is already recorded field-by-field in `props`
+  // and `propValues`, which is the part anyone actually reads.
+  return { status: "empty" };
+}
+
+/**
+ * Close the recording and store it.
+ *
+ * @param http - The request context the recording was opened on.
+ * @param response - The response about to be returned.
+ * @param parentOut - The batch root id, echoed into `__meta.batchId`.
+ */
+export function finishRecording(
+  http: HttpContext,
+  response: Response,
+  parentOut: string | null,
+): void {
+  const recording = currentRecording();
+  if (!recording) return;
+
+  const settings = devtoolsSettings();
+  const headerPatterns = [...DEFAULT_REDACTED_HEADERS, ...settings.redactHeaders];
+  const requestHeaders = http.request.headers;
+  const isInertia =
+    requestHeaders.get("X-Inertia") === "true" ||
+    (response.headers.get("Content-Type") ?? "").includes("json");
+
+  const entry: DevtoolsEntry = {
+    __meta: {
+      id: recording.id,
+      method: http.request.method,
+      url: http.url.href,
+      status: response.status,
+      requestType: requestTypeOf(http.request, requestHeaders),
+      component: recording.component,
+      timestamp: recording.timestamp,
+      utime: recording.utime,
+      tabUuid: requestHeaders.get(DEVTOOLS_REQUEST_HEADERS.tab),
+      batchId: parentOut,
+      serverTimingMs: Math.round((performance.now() - recording.startedAt) * 1000) / 1000,
+      redirectLocation: response.headers.get("Location"),
+      visitId: requestHeaders.get(DEVTOOLS_REQUEST_HEADERS.visit),
+    },
+    http: {
+      requestHeaders: redactHeaders(requestHeaders, headerPatterns),
+      responseHeaders: redactHeaders(response.headers, headerPatterns),
+      // Same reasoning as the response body: reading the request stream here
+      // would consume it, and by this point the handler has already had it.
+      requestBody: { status: "omitted", reason: "non-inertia-request" },
+      responseBody: captureResponseBody(response, isInertia),
+    },
+    props: recording.props,
+    route: routeInfoFor(http),
+    renderSource: null,
+    componentPath: recording.component
+      ? `${config.safe("inertia.pagesDir", "resources/js/pages")}/${recording.component}`
+      : null,
+  };
+
+  if (Object.keys(recording.propValues).length > 0) entry.propValues = recording.propValues;
+
+  putEntry(entry);
+}

package/src/devtools/redact.ts

@@ -0,0 +1,129 @@
+/**
+ * Redaction — the part of the recorder that decides what never reaches the panel.
+ *
+ * DevTools entries are readable by anyone who can reach the read API, and they
+ * are recorded from live requests, so they would otherwise contain the session
+ * cookie, the `Authorization` header, and whatever a login form just posted.
+ * Redaction runs before an entry is stored, not when it is served: an entry that
+ * was never written cannot leak from a store that is later exposed by mistake.
+ */
+
+/** The marker the protocol uses for a value that was withheld. */
+export const REDACTED = "[REDACTED]";
+
+/**
+ * Header names always withheld. Compared case-insensitively — HTTP header names
+ * are case-insensitive and `Headers` normalises to lower case, but an adapter
+ * that only matched the canonical spelling would be one `AUTHORIZATION` away
+ * from leaking a bearer token.
+ */
+export const DEFAULT_REDACTED_HEADERS: readonly string[] = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+  "x-api-key",
+  "x-csrf-token",
+  "x-xsrf-token",
+];
+
+/**
+ * Prop and body keys always withheld. Matched as case-insensitive *substrings*
+ * so `password`, `password_confirmation`, and `currentPassword` are all caught
+ * by one entry — an exact-match list is a list of the spellings someone thought
+ * of, and the one that leaks is always the one they did not.
+ */
+export const DEFAULT_REDACTED_KEYS: readonly string[] = [
+  "password",
+  "secret",
+  "token",
+  "authorization",
+  "api_key",
+  "apikey",
+  "credit_card",
+  "card_number",
+  "cvv",
+  "ssn",
+  "private_key",
+];
+
+/** True when `key` matches any of `patterns` as a case-insensitive substring. */
+export function isSensitiveKey(key: string, patterns: readonly string[]): boolean {
+  const lower = key.toLowerCase();
+  return patterns.some((pattern) => lower.includes(pattern.toLowerCase()));
+}
+
+/**
+ * Copy a `Headers` into a plain object, replacing sensitive values.
+ *
+ * @param headers - The request or response headers.
+ * @param patterns - Header names to withhold, case-insensitive.
+ */
+export function redactHeaders(
+  headers: Headers,
+  patterns: readonly string[] = DEFAULT_REDACTED_HEADERS,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    out[key] = isSensitiveKey(key, patterns) ? REDACTED : value;
+  });
+  return out;
+}
+
+/**
+ * Deep-copy a value, replacing sensitive keys and summarising things that must
+ * not be inlined.
+ *
+ * Guards three separate hazards, all of which have to be handled before the
+ * value is serialised:
+ *
+ *  - **Sensitive keys** become `[REDACTED]`, at any depth.
+ *  - **Cycles** become `"[Circular]"`. A prop bag holding a model with a
+ *    back-reference to its parent is ordinary, and `JSON.stringify` throws on it.
+ *  - **Files and blobs** become a short summary. A 4 MB upload does not belong
+ *    in a debug entry, and `File` does not survive `JSON.stringify` anyway.
+ *
+ * @param value - Any prop value.
+ * @param patterns - Key patterns to withhold.
+ * @param seen - Internal: the ancestor set for cycle detection.
+ * @param depth - Internal: current depth, bounded to keep a deep graph from stalling the request.
+ */
+export function redactValue(
+  value: unknown,
+  patterns: readonly string[] = DEFAULT_REDACTED_KEYS,
+  seen: WeakSet<object> = new WeakSet(),
+  depth = 0,
+): unknown {
+  if (value === null || typeof value !== "object") return value;
+
+  // Bounded rather than unbounded: recording is on the request path, and a
+  // pathological object graph should slow nothing down.
+  if (depth > 12) return "[Max depth]";
+
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof File) {
+    return `[File: ${value.name}, ${value.size} bytes, ${value.type || "unknown"}]`;
+  }
+  if (value instanceof Blob) return `[Blob: ${value.size} bytes, ${value.type || "unknown"}]`;
+
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item) => redactValue(item, patterns, seen, depth + 1));
+    }
+
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = isSensitiveKey(key, patterns)
+        ? REDACTED
+        : redactValue(entry, patterns, seen, depth + 1);
+    }
+    return out;
+  } finally {
+    // Released on the way out so a value that legitimately appears twice as a
+    // sibling is not mistaken for a cycle — only true ancestors count.
+    seen.delete(value);
+  }
+}

package/src/devtools/store.ts

@@ -0,0 +1,126 @@
+/**
+ * Where recorded entries live between being written and being read.
+ *
+ * A bounded in-memory ring, not a directory of files. The Laravel adapter
+ * persists to `storage/inertia-devtools` because a PHP process does not outlive
+ * the request that created the entry; a Bun server does, so the entries are
+ * simply kept in the process that recorded them. That removes disk IO from the
+ * request path, removes a pruning job, and removes the question of what happens
+ * when two workers write the same directory.
+ *
+ * What it costs: entries do not survive a restart, so a crash takes its own
+ * timeline with it. For a tool you read while the server is up, that is the
+ * right trade — and `zt dev` restarts on every save, which would invalidate a
+ * persisted timeline anyway.
+ *
+ * The store is capped by count. An unbounded recorder is a memory leak with a
+ * friendly name: a long-lived dev server serving a busy SPA would hold every
+ * prop bag it ever rendered.
+ */
+import type { DevtoolsEntry, DevtoolsListQuery, DevtoolsRequestType } from "./types.ts";
+
+/** How many entries are kept before the oldest is dropped. */
+export const DEFAULT_MAX_ENTRIES = 200;
+
+let _entries: DevtoolsEntry[] = [];
+let _max = DEFAULT_MAX_ENTRIES;
+
+/** Set the cap and drop anything already over it. */
+export function setMaxEntries(max: number): void {
+  _max = Math.max(1, Math.floor(max));
+  if (_entries.length > _max) _entries = _entries.slice(-_max);
+}
+
+/** The current cap. */
+export function maxEntries(): number {
+  return _max;
+}
+
+/** Store an entry, dropping the oldest once the cap is reached. */
+export function putEntry(entry: DevtoolsEntry): void {
+  _entries.push(entry);
+  if (_entries.length > _max) _entries.shift();
+}
+
+/** Look one entry up by id. */
+export function getEntry(id: string): DevtoolsEntry | undefined {
+  return _entries.find((entry) => entry.__meta.id === id);
+}
+
+/** Drop everything. Used between tests and by the panel's "clear" action. */
+export function clearEntries(): void {
+  _entries = [];
+}
+
+/** How many entries are currently held. */
+export function entryCount(): number {
+  return _entries.length;
+}
+
+/**
+ * List entries newest-first, applying the read API's filters.
+ *
+ * `exclude` is applied after `type` so a request naming both keeps the
+ * intersection, which is what the extension expects when it asks for "all
+ * navigations except prefetches".
+ *
+ * @param query - Filters from the request's query string.
+ */
+export function listEntries(query: DevtoolsListQuery = {}): DevtoolsEntry[] {
+  let out = _entries.slice().reverse();
+
+  if (query.component !== undefined) {
+    out = out.filter((entry) => entry.__meta.component === query.component);
+  }
+  if (query.type && query.type.length > 0) {
+    const keep = new Set<string>(query.type);
+    out = out.filter((entry) => keep.has(entry.__meta.requestType));
+  }
+  if (query.exclude && query.exclude.length > 0) {
+    const drop = new Set<string>(query.exclude);
+    out = out.filter((entry) => !drop.has(entry.__meta.requestType));
+  }
+
+  // Slice last: offset and limit page the *filtered* list, so paging through a
+  // filtered view does not skip entries the filter already removed.
+  const offset = Math.max(0, query.offset ?? 0);
+  const limit = query.limit;
+  return limit === undefined ? out.slice(offset) : out.slice(offset, offset + Math.max(0, limit));
+}
+
+/** Parse the read API's query string into a {@link DevtoolsListQuery}. */
+export function parseListQuery(params: URLSearchParams): DevtoolsListQuery {
+  const query: DevtoolsListQuery = {};
+
+  const component = params.get("component");
+  if (component !== null) query.component = component;
+
+  const csv = (value: string | null): string[] | undefined => {
+    if (value === null) return undefined;
+    const parts = value
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+  };
+
+  // Cast to the element type, not to `DevtoolsListQuery["type"]` — that includes
+  // `undefined`, which re-widens the value the `if` just narrowed.
+  const type = csv(params.get("type"));
+  if (type) query.type = type as DevtoolsRequestType[];
+  const exclude = csv(params.get("exclude"));
+  if (exclude) query.exclude = exclude as DevtoolsRequestType[];
+
+  const num = (value: string | null): number | undefined => {
+    if (value === null) return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  };
+
+  const offset = num(params.get("offset"));
+  if (offset !== undefined) query.offset = offset;
+  const limit = num(params.get("limit"));
+  if (limit !== undefined) query.limit = limit;
+
+  return query;
+}

package/src/devtools/types.ts

@@ -0,0 +1,165 @@
+/**
+ * The Inertia DevTools protocol, as types.
+ *
+ * These names are not ours to choose — they are the wire contract the browser
+ * extension reads, so every key here matches the published protocol exactly,
+ * including the `__meta` prefix and the `snake`/`camel` inconsistencies. When
+ * something looks oddly named, that is why; do not tidy it.
+ *
+ * @see https://inertiajs.com/docs/v3/advanced/devtools-protocol
+ */
+
+/** Request headers the extension sets so entries can be correlated into one timeline. */
+export const DEVTOOLS_REQUEST_HEADERS = {
+  /** Per-tab UUID; recorded as `__meta.tabUuid`. */
+  tab: "X-Inertia-Devtools-Tab",
+  /** Client visit id; recorded as `__meta.visitId`. */
+  visit: "X-Inertia-Devtools-Visit",
+  /** Id of the entry that started this batch; becomes `__meta.batchId`. */
+  parent: "X-Inertia-Devtools-Parent",
+  /** `"1"` when this request is a deferred-prop follow-up. */
+  deferred: "X-Inertia-Devtools-Deferred",
+  /** `"1"` when this request is a polling tick. */
+  poll: "X-Inertia-Devtools-Poll",
+} as const;
+
+/** Response headers the adapter sets so the extension can find the entry it just caused. */
+export const DEVTOOLS_RESPONSE_HEADERS = {
+  /** The id generated for this entry. Set on every response. */
+  id: "X-Inertia-Devtools-Id",
+  /** The batch root id, so the extension can chain follow-up requests to their origin. */
+  parentOut: "X-Inertia-Devtools-Parent-Out",
+} as const;
+
+/** Path prefix of the read API the extension polls. */
+export const DEVTOOLS_API_PREFIX = "/_inertia/devtools";
+
+/**
+ * How the request reached the adapter. The client-only values (`client-visit`,
+ * `cache-hit`) never originate here — they are listed because the extension
+ * merges client-recorded entries into the same timeline, and a reader of this
+ * type should not think the set is smaller than it is.
+ */
+export type DevtoolsRequestType =
+  | "precognition"
+  | "initial"
+  | "http"
+  | "deferred"
+  | "poll"
+  | "partial"
+  | "prefetch"
+  | "navigate"
+  | "client-visit"
+  | "cache-hit";
+
+/** A source location, where one could be resolved. */
+export interface SourceLocation {
+  file: string;
+  line: number;
+}
+
+/**
+ * What the adapter knows about one prop, keyed in `Entry.props` by its dotted
+ * path. Every field is optional: a plain prop with nothing special about it is
+ * recorded as `{}`, which is meaningfully different from being absent.
+ */
+export interface PropMeta {
+  /** Which prop wrapper produced it, if any. */
+  inertiaType?: "always" | "defer" | "optional" | "merge" | "scroll" | "once";
+  /** True when the prop came from `share()` rather than the controller. */
+  shared?: boolean;
+  /** The `defer()` group this prop loads with. */
+  deferGroup?: string;
+  /** True when the client asked for this prop to be reset rather than merged. */
+  reset?: boolean;
+  /** True for a `once()` prop. */
+  once?: boolean;
+  /** Which end of the existing value a merge prop is applied to. */
+  mergeDirection?: "append" | "prepend";
+  /** True when the merge is deep rather than shallow. */
+  deepMerge?: boolean;
+  /** True when a `defer(..., { rescue: true })` prop threw and was omitted. */
+  rescued?: boolean;
+  /** Where the prop's value was produced. */
+  renderSource?: SourceLocation;
+  /** Where a shared prop was registered. */
+  shareSource?: SourceLocation;
+}
+
+/** Why a body was not captured. */
+export type BodyOmittedReason =
+  | "non-inertia-response"
+  | "non-inertia-request"
+  | "non-textual"
+  | "streamed"
+  | "too-large"
+  | "unserializable"
+  | "binary";
+
+/**
+ * A captured request or response body. A tagged union rather than a nullable
+ * value so the panel can say *why* something is missing — "too large" and
+ * "there was no body" look identical otherwise.
+ */
+export type BodyCapture =
+  | { status: "empty" }
+  | { status: "present"; value: unknown }
+  | { status: "omitted"; reason: BodyOmittedReason };
+
+/** The route that matched, as far as the adapter can describe it. */
+export interface RouteInfo {
+  /** The URL pattern, e.g. `/posts/:slug`. */
+  uri: string;
+  /** The registered route name, or `null` for an unnamed route. */
+  name: string | null;
+  /** The controller/handler, e.g. `PostController@show`. */
+  action: string | null;
+  /** Where the handler is defined, when it can be resolved. */
+  actionSource?: SourceLocation;
+}
+
+/** Everything the panel shows about one recorded request. */
+export interface DevtoolsEntry {
+  __meta: {
+    id: string;
+    method: string;
+    url: string;
+    status: number;
+    requestType: DevtoolsRequestType;
+    component: string | null;
+    /** ISO 8601. */
+    timestamp: string;
+    /** Unix time in float seconds. */
+    utime: number;
+    tabUuid: string | null;
+    batchId: string | null;
+    serverTimingMs: number | null;
+    redirectLocation?: string | null;
+    visitId?: string | null;
+  };
+  http: {
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody: BodyCapture;
+    responseBody: BodyCapture;
+  };
+  /** Dotted prop path → what is known about it. */
+  props: Record<string, PropMeta>;
+  /** Dotted prop path → the resolved value, redacted. */
+  propValues?: Record<string, unknown>;
+  route: RouteInfo;
+  renderSource: SourceLocation | null;
+  componentPath: string | null;
+}
+
+/** Filters accepted by `GET /_inertia/devtools/entries`. */
+export interface DevtoolsListQuery {
+  /** Exact component-name match. */
+  component?: string;
+  /** Request types to keep. */
+  type?: DevtoolsRequestType[];
+  /** Request types to drop; applied after `type`. */
+  exclude?: DevtoolsRequestType[];
+  offset?: number;
+  limit?: number;
+}

package/src/index.ts

@@ -43,6 +43,13 @@ import "./augment.ts";
 
 export { inertiaRoute } from "./route.ts";
 
+// `route()` for pages — the browser/SSR helper from `@zerotal/core/routes`,
+// re-exported so a page component imports it from the package it already uses.
+// Note the two are different things: `inertiaRoute()` above *registers* a page
+// route on the server, `route()` *generates a URL* for one.
+export { route, defineRoutes, hasRoute, resetRoutes } from "@zerotal/core/routes";
+export type { RouteTable } from "@zerotal/core/routes";
+
 export {
   inertia,
   inertiaStream,
@@ -106,7 +113,16 @@ export { location } from "./location.ts";
 
 // Config factory
 export { InertiaConfig } from "./config.ts";
-export type { InertiaConfigShape } from "./config.ts";
+export type { InertiaConfigShape, InertiaDevtoolsConfig } from "./config.ts";
+
+// ── DevTools ─────────────────────────────────────────────────────────────────
+// Server-side recorder for the Inertia DevTools browser extension. InertiaProvider
+// wires all of this up when the recorder is enabled; an app needs none of it
+// unless it is registering the recorder itself.
+export { InertiaDevtoolsMiddleware } from "./devtools/middleware.ts";
+export { devtoolsEnabled } from "./devtools/enabled.ts";
+export { DEVTOOLS_API_PREFIX } from "./devtools/types.ts";
+export type { DevtoolsEntry } from "./devtools/types.ts";
 
 // SSR handler (for direct use or testing)
 export { SsrHandler } from "./SsrHandler.ts";

package/src/inertia.ts

@@ -7,6 +7,7 @@ import { assetVersion } from "./version.ts";
 import { resolveProps } from "./props/resolveProps.ts";
 import { readHistoryFlags } from "./historyState.ts";
 import { allSharedKeys } from "./share.ts";
+import { recordPage } from "./devtools/recorder.ts";
 import { resolvePageModule, renderInertiaPage } from "./ssr/renderPage.ts";
 import type { PageObject } from "./types.ts";
 import type { PageTarget, RenderArgs } from "./pages.ts";
@@ -76,6 +77,10 @@ export async function buildPageObject(
   const sharedPresent = allSharedKeys().filter((k) => k in resolved.props);
   if (sharedPresent.length) page.sharedProps = sharedPresent;
 
+  // The only point that sees the raw wrappers and the resolved values together;
+  // a no-op unless the DevTools recorder opened a recording for this request.
+  recordPage(component, merged, resolved.props, resolved.rescuedProps);
+
   const history = readHistoryFlags();
   if (history.encryptHistory) page.encryptHistory = true;
   if (history.clearHistory) page.clearHistory = true;

package/src/provider/InertiaProvider.ts

@@ -12,6 +12,10 @@ import { detectCssPlugins } from "../css.ts";
 import { detectVuePlugin, registerVueRuntimeLoader } from "../vuePlugin.ts";
 import { InertiaMiddleware } from "../middleware/InertiaMiddleware.ts";
 import { inertiaRoute } from "../route.ts";
+import { InertiaDevtoolsMiddleware } from "../devtools/middleware.ts";
+import { devtoolsEnabled, devtoolsSettings } from "../devtools/enabled.ts";
+import { registerDevtoolsApi } from "../devtools/api.ts";
+import { setMaxEntries } from "../devtools/store.ts";
 
 export class InertiaProvider extends ServiceProvider {
   static override environments: AppEnvironment[] = ["web", "console", "test"];
@@ -22,7 +26,18 @@ export class InertiaProvider extends ServiceProvider {
   }
 
   override async onBooting(): Promise<void> {
-    this.app.useOnce(InertiaMiddleware as never);
+    this.app.useOnce(InertiaMiddleware);
+
+    // DevTools recorder. Registered before InertiaMiddleware runs its response
+    // rewrites so the status it records is the one the client actually sees
+    // (302→303, and the version-mismatch 409, both happen in there). Nothing is
+    // registered at all when the recorder is off, so a production process has
+    // no read API to probe.
+    if (devtoolsEnabled()) {
+      setMaxEntries(devtoolsSettings().maxEntries);
+      this.app.useOnce(InertiaDevtoolsMiddleware);
+      registerDevtoolsApi();
+    }
 
     const config = this.app.container.makeSync("config") as ConfigManager;