@zerotal/devtools 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -6,7 +6,239 @@ follows the Zerotal monorepo's unified versioning.
 
 **Maturity: `stable`**
 
-## [Unreleased]
+## [1.7.0] — 2026-08-16
+
+### Added
+
+- **An App section: the framework as it _is_, not only as it just behaved.** Every surface
+  until now read the trace stream — what one request did. The framework's own registries
+  were CLI-only or invisible, so "is that route even registered", "who bound `cache`",
+  "which provider is costing 200ms of boot" and "does anything actually listen to
+  `OrderPlaced`" were all answered by reading source.
+
+  Six tabs behind a **Requests | App** switch in the tab strip — two sections rather than
+  fifteen tabs in one scrolling strip, because they answer different questions:
+
+  - **Routes** — method, path, name, handler, middleware. GETs are clickable.
+  - **Config** — the resolved tree, flattened to dotted paths, with secrets masked.
+  - **Container** — every binding, its kind, and **which provider bound it**.
+  - **Providers** — boot order and per-provider cost.
+  - **Events** — application listeners and framework subscribers in one list.
+  - **Commands** — console commands and scheduled tasks. A task that fails at 03:00 used
+    to leave no trace in the tool whose job is to show you what your app did.
+
+  One read of one map shared by all six, since six requests for it would be six answers
+  that can disagree. Behind the same gate as everything else.
+
+- **Every location in the panel is a link into your editor.** A repo-wide search for any
+  editor URL scheme used to return nothing: no stack frame, query, log line, or prop in any
+  Zerotal surface was clickable to source. Going from "this query is slow" to the line that
+  ran it is the most frequent move in a debugging session, and it was two manual searches.
+
+  `editor` in `config/devtools.ts` takes `vscode`, `vscode-insiders`, `cursor`, `windsurf`,
+  `zed`, or `webstorm`; `editorPathMap` rewrites paths for editing on a machine that is not
+  the one running the code.
+
+- **Queries and log lines know where they came from.** One stack walk per recorded event,
+  filtered to application frames — the first frame that is _not_ framework code is the
+  answer, and every frame above it is noise.
+
+  This was the plan's one item of genuinely unknown viability, so it was measured before it
+  was built: **~2µs per capture, flat from stack depth 5 to 80**, because the engine builds
+  the trace lazily. A request running forty queries pays about 0.08ms. On by default;
+  `captureSource: false` turns it off.
+
+- **An Exception tab.** Type, message, and the full stack with every frame a link. Framework
+  frames are kept and dimmed rather than dropped — you read a stack trace to find out how you
+  got somewhere, and a trace with the middle removed does not tell you that.
+
+- **Three more tabs, from events already on the bus and going nowhere.** **Models**
+  (`ModelChanged`, grouped per model — a request that wrote four rows and one that wrote none
+  looked identical), **Transactions** (`TransactionCommitted` / `RolledBack` — a rollback
+  showed only as queries that appeared to succeed), and **Outgoing** (`OutgoingRequestCompleted`).
+
+- **The Request tab shows the whole exchange.** Response headers and the status line
+  alongside the request, plus **session key names** — "is the CSRF token there, did the flash
+  survive the redirect" are answered by the keys, and the values are the request's real state
+  on a trace kept for a day. `headers: ["x-tenant"]` (or `["*"]`) opens up the request headers
+  the built-in allowlist withholds; `cookie` and `authorization` are never recorded whatever
+  you ask for.
+
+- **What the browser measured, on the Timeline.** The panel reported server duration as
+  though it were the user's experience. A 12ms response the browser spends 900ms painting is
+  a slow page, and nothing in the trace said so — so TTFB, parse, load, and first paint now
+  sit above the waterfall, labelled as the page's rather than this request's.
+
+### Security
+
+- **The Config tab masks a bare `key`, which the shared rule does not.** `app.key` is the
+  application's encryption key; the package-wide list covers `api_key` and `private_key` but
+  not `key` alone, which is right for a query binding — a column called `key` is usually a
+  lookup key — and wrong for config, where secrets are _supposed_ to live. Config gets the
+  stricter rule, `dsn` with it, on top of whatever the app's own `allow`/`deny` say.
+
+- **An access gate, so running the inspector outside development is a supported thing to do
+  rather than a lie about `APP_ENV`.** It was all-or-nothing on the dev-surface check, which
+  is the right default and the only option — and Phase 4 widens what it exposes considerably.
+
+  ```ts
+  export default DevtoolsConfig({
+    enabled: null,          // null → follow the dev-surface gate (unchanged default)
+    gate: async (req) => …, // required anywhere else; absent is a refusal
+  });
+  ```
+
+  A development process always passes — a gate that can lock a developer out of their own
+  machine gets switched off, and then nothing is gated. Anywhere else the absence of a gate
+  is a **refusal**, a throwing gate is a refusal, and one gate answers for every endpoint:
+  the stream, the trace JSON, the dashboard, and the panel bundle are the same secret.
+  Unauthorised requests get 404, not 403 — outside development the honest answer to a
+  stranger is that there is nothing here.
+
+  Auto-injection of the panel script is now dev-only. On a gated environment it would go into
+  every visitor's HTML and then 404 in their console; there the way in is the dashboard.
+
+- **The panel remembers, follows, and gets out of the way.** Five things it could not do:
+
+  - **Resize.** The height was 380px, which is either too little to read a stack trace in or
+    too much to see the page under. Drag the strip above the tab row; the height is kept.
+  - **Light theme.** Follows `prefers-color-scheme` by default, with a toggle in the bar
+    cycling auto → dark → light for when the panel and the page you are debugging disagree.
+  - **Facets.** Method chips (only the verbs actually recorded), status-class chips, and
+    `errors` / `slow` / `n+1` toggles, composing with the text box rather than replacing it.
+    `POST` plus `5xx` means failing writes, not writes-or-failures.
+  - **Keyboard navigation.** `j`/`k` through the filtered list, `1`–`9` for tabs, `/` to
+    focus the filter, `Esc` to close. Only while the panel has focus — it is an overlay on
+    somebody's application, and binding `j` globally would navigate the trace list every time
+    a developer typed into their own form.
+  - **Copy buttons** on every SQL statement (and the whole statement list), log line, header
+    block, channel entry, and prop path.
+
+- **New traces are offered, not forced.** While pinned, the bar shows `⤒ N new` instead of
+  silently accumulating. A list that scrolls away from what you were reading is the one
+  thing a request inspector must not do.
+
+### Changed
+
+- **The browser client is a directory, not a 1,400-line closure.** `client.ts` held its
+  state, its transport, its styles, eight renderers, and every helper in one function scope
+  — which made adding a tab an edit to the middle of it, and made none of its logic reachable
+  from a test. It is now `src/client/`: a store, a transport, a shell, and one file per tab.
+  Adding a tab is adding a file.
+
+  No behaviour was dropped. Both mount modes still run one set of renderers, both extension
+  doors are unchanged, and `@zerotal/devtools/client` still resolves — the subpath now points
+  at `src/client/index.ts`.
+
+- **Rows are reconciled rather than rebuilt.** Every arriving request used to replace the
+  whole content pane, which threw away the scroll position, every open `<details>`, every
+  loaded mail-preview iframe, and the caret in the filter box — the last of which the old
+  panel worked around by re-focusing and re-selecting the field after each keystroke. A keyed
+  list diff (about sixty lines, no dependency) now inserts one node and touches nothing else,
+  and tabs that read a single trace are not redrawn at all until that trace changes.
+
+- **The request list is windowed above 200 rows**, so `DevtoolsConfig({ capacity: 5000 })` is
+  a list you can scroll rather than five thousand nodes.
+
+### Fixed
+
+- **A negative render window.** Whenever the request list shrank under a scrolled viewport —
+  which is every "clear" — the windowing arithmetic asked for a slice starting past the end
+  of the list. Found by the test that could finally be written for it.
+
+- **An Inertia tab, with the prop tree.** `@zerotal/inertia` has always resolved the richest
+  data in the framework — per-prop metadata, request classification, batch correlation — and
+  shipped no UI for it, while this panel shipped the UI and knew nothing about Inertia. A
+  developer got a panel that could not show a prop and an extension that could not show a
+  query, and neither could answer "this page is slow — is it the query or the deferred prop?"
+
+  Inertia now contributes a channel, and one row shows the component, its props, **and** the
+  SQL that produced them. Nothing matches a key: the entry is recorded against the same
+  request context as the queries, so the two cannot disagree about which request they
+  describe.
+
+- **Channels choose how they are drawn.** A flat list of rows is right for an audit feed and
+  wrong for a prop map or a route table, and a package that needs a tree should not have to
+  ship a renderer into devtools to get one. `TraceChannelDescriptor` gains `render` —
+  `"rows"` (the default, unchanged), `"tree"`, `"table"`, `"kv"`, `"grouped"` — plus
+  `treeField`, `treeBadge`, `groupBy`, and `flags`. All of it crosses the wire as data, so
+  this remains the only channel-rendering code in the panel however many packages contribute.
+
+- **Correlated requests fold together on the All tab.** A channel names the field that
+  relates traces (`traceGroup`); everything sharing a value there collapses under the oldest
+  member with a `+N` toggle. One thing you did is often several requests — a visit and the
+  deferred props that follow it — and listing them as unrelated siblings is how the request
+  you are reading gets pushed off the top.
+
+- **Badge chips are accented by hashing their own text**, so `partial` and `deferred` are
+  tellable apart at a glance without devtools holding a list of every value any package
+  might use. Stable per value, so a badge keeps its colour between requests.
+
+- `buildPathTree` and `traceGroupKey` are exported from `@zerotal/devtools/client`, for the
+  same reason `matchesFilter` is: they are the parts of the panel that are logic rather than
+  markup, and they are worth testing without a DOM.
+
+### Changed
+
+- **The redaction walk moved to `redactGraph` in `@zerotal/core/security`**, and the Inertia
+  recorder runs the same one. Both had independently solved the same three problems — cycles,
+  depth, and values that read better flat than walked — and only one of them had to.
+  Markers are still each caller's own: a panel's `‹redacted›` is a display choice, while an
+  adapter implementing a published protocol has `[REDACTED]` specified for it. Sharing the
+  traversal does not mean agreeing on the words. No behaviour change.
+
+- **Failed requests say what failed.** `RequestFailed` has always carried the error
+  message; the trace dropped it, so a request that threw showed as a red status code with
+  nothing to read beside it. Traces now carry an `exception` (`message` and `status`), the
+  Queries tab leads with it, and the All tab marks the row and shows the message inline —
+  so you can find the request that broke without opening each one in turn.
+
+- **Mail previews.** The rendered HTML of every captured email has crossed the wire on
+  every request since mail capture landed, and has never been shown. Each mail now has a
+  **Preview**, collapsed by default, rendered in a fully sandboxed frame — no scripts, no
+  same-origin access, no navigation. The sandbox is not optional hardening: the panel lives
+  in a shadow root on the app's own origin, so inserting a template's markup inline would
+  make any user input inside a mail a self-XSS on every dev machine.
+
+- **N+1 warnings say what to do about them again.** Each warning now carries the eager-load
+  that removes it and the `DB.allowNPlusOne(…)` call that suppresses it when the repetition
+  is intended. A warning without a remedy is half a feature.
+
+- **The panel remembers where you were.** Whether it was open, which tab you were on, and
+  what you had filtered to survive a reload. On a page you are reloading _because_ you are
+  debugging it, that was the wrong moment to lose your place.
+
+### Fixed
+
+- **`capacity` did not do what it said.** The browser panel trimmed its list at a hardcoded
+  100 regardless of config, so an app with `DevtoolsConfig({ capacity: 250 })` received 250
+  traces in the opening frame and then silently lost everything past 100 as soon as the next
+  request arrived. The stream now sends the store's capacity and the panel trims to it.
+
+- **A circular argument to `console.log` threw out of the log capture** and into the
+  caller. The capture ran `JSON.stringify` on the raw argument, so anything
+  self-referential — a model with a loaded relation back to its parent, a request object —
+  raised `Converting circular structure to JSON` from inside a patched `console.log`.
+
+### Security
+
+- **Redaction covered query bindings only.** Console log arguments, channel entries, and
+  cache keys were streamed to the browser and written to `.zerotal/devtools.sqlite`
+  unredacted, where they sat for a day — so one `console.log(user)` during a debug session
+  wrote a full user record, password hash included, to disk.
+
+  All four are now masked at the sink, where the value enters the trace rather than where
+  the panel draws it: redacting in a renderer protects nothing, because the unredacted copy
+  is already persisted by then. One rule decides all four, so `allow` and `deny` in
+  `config/devtools.ts` mean the same thing everywhere. A cache key keeps its name and loses
+  only what follows it, so the Cache tab stays legible.
+
+  New exports: `redactValue`, `redactCacheKey`, and `isSensitiveName`.
+
+### Removed
+
+- **`src/panel-app.js`** — ~500 lines of the pre-`client.ts` panel, unimported, unbundled,
+  and unserved since the rewrite.
 
 ## [1.6.2] — 2026-08-15
 

package/api-surface.md

@@ -0,0 +1,296 @@
+# @zerotal/devtools — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class DevtoolsInjectionMiddleware = {
+  new (): DevtoolsInjectionMiddleware
+  static with: <T extends new (...args: any[]) => BaseMiddleware<any>, Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object>(this: T, options: DeepPartial<NoInfer<Opts>>) => new () => InstanceType<T>
+  afterResponse?: (ctx: HttpContext) => Promise<void>
+  handle: (http: HttpContext, next: NextFn) => Promise<Response | void>
+  onError?: (ctx: HttpContext, error: Error) => Promise<void>
+}
+
+class DevtoolsProvider = {
+  new (app: Application): DevtoolsProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly []
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class TraceStore = {
+  new (options?: TraceStoreOptions | number): TraceStore
+  all: () => RequestTrace[]
+  capacity: number
+  clear: () => void
+  dispose: () => void
+  persisting: boolean
+  push: (trace: RequestTrace) => void
+  subscribe: (fn: Subscriber) => () => void
+}
+
+const traceSink = TraceSink
+
+function _setTraceStore = (store: TraceStore | null) => void
+
+function attributeBindings = (sql: string, count: number) => Array<string | undefined>
+
+function DevtoolsConfig = (options?: Partial<DevtoolsConfigShape>) => DevtoolsConfigShape
+
+function devtoolsEnabled = () => boolean
+
+function isSensitiveName = (name: string, options?: RedactionOptions) => boolean
+
+function redactBindings = (sql: string, bindings: unknown[], options?: RedactionOptions) => unknown[]
+
+function redactCacheKey = (key: string, options?: RedactionOptions) => string
+
+function redactValue = (value: unknown, options?: RedactionOptions) => unknown
+
+function startDevtoolsStream = () => () => void
+
+function traceChannels = () => TraceChannelDescriptor[]
+
+function traceStore = () => TraceStore
+
+interface AuthInfo = {
+  email?: unknown
+  id: unknown
+  name?: unknown
+}
+
+interface CacheEntry = {
+  durationMs: number
+  key: string
+  offsetMs: number
+  op: 'hit' | 'miss' | 'write' | 'forget' | 'flush' | 'has'
+  ttl?: number | undefined
+}
+
+interface DevtoolsConfigShape = {
+  capacity: number
+  captureSource: boolean
+  dbPath: string | null
+  editor: EditorName | null
+  editorPathMap: Record<string, string>
+  enabled: boolean | null
+  gate: DevtoolsGate | null
+  headers: string[]
+  pruneHours: number
+  redact: RedactionOptions
+}
+
+interface DevtoolsInjectionOptions = {}
+
+interface DevtoolsPanelPlugin = {
+  badge?: () => number | string | undefined
+  id: string
+  render: (el: HTMLElement) => void
+  title: string
+}
+
+interface ExceptionInfo = {
+  frames?: SourceLocation[]
+  message: string
+  status: number
+  type?: string
+}
+
+interface JobEntry = {
+  className: string
+  durationMs: number
+  error?: string
+  offsetMs: number
+  queue: string
+  status: 'dispatched' | 'completed' | 'failed'
+}
+
+interface LogEntry = {
+  args: string[]
+  level: 'error' | 'info' | 'log' | 'warn' | 'debug'
+  offsetMs: number
+  source?: SourceLocation
+}
+
+interface MailEntry = {
+  className: string
+  durationMs: number
+  html: string
+  offsetMs: number
+  queued: boolean
+  subject: string
+  to: string[]
+}
+
+interface NPlusOneWarning = {
+  count: number
+  sql: string
+}
+
+interface QuerySpan = {
+  bindings: unknown[]
+  durationMs: number
+  rowCount: number
+  source?: SourceLocation
+  sql: string
+  startMs: number
+}
+
+interface RedactionOptions = {
+  allow?: string[]
+  deny?: string[]
+  enabled?: boolean
+}
+
+interface RequestTrace = {
+  auth: AuthInfo | null
+  cache: CacheEntry[]
+  channels: Record<string, TraceChannelEntry[]>
+  durationMs: number
+  exception: ExceptionInfo | null
+  headers: Record<string, string>
+  id: string
+  jobs: JobEntry[]
+  logs: LogEntry[]
+  mail: MailEntry[]
+  memory: number
+  method: string
+  path: string
+  queries: QuerySpan[]
+  queryParams: Record<string, string>
+  requestId: string
+  responseHeaders: Record<string, string>
+  route: RouteInfo | null
+  session: string[]
+  startMs: number
+  statusCode: number
+  warnings: NPlusOneWarning[]
+}
+
+interface RouteInfo = {
+  action: string
+  controller: string
+  pattern: string
+}
+
+interface SourceLocation = {
+  column?: number
+  file: string
+  function?: string
+  line: number
+}
+
+interface TraceChannelDescriptor = {
+  badge?: string
+  flags?: string[]
+  groupBy?: string
+  id: string
+  label: string
+  meta?: string[]
+  order?: number
+  render?: 'table' | 'rows' | 'tree' | 'kv' | 'grouped'
+  title?: string
+  traceGroup?: string
+  treeBadge?: string
+  treeField?: string
+  warn?: string
+}
+
+interface TraceChannelEntry = {
+  [key: string]: unknown
+  offsetMs: number
+}
+
+interface TraceSink = {
+  bufferCache: (ctx: object, c: Omit<CacheEntry, 'offsetMs'>) => void
+  bufferJob: (ctx: object, j: Omit<JobEntry, 'offsetMs'>) => void
+  bufferMail: (ctx: object, m: Omit<MailEntry, 'offsetMs'>) => void
+  bufferQuery: (ctx: object, q: QuerySpan) => void
+  bufferWarning: (ctx: object, w: NPlusOneWarning) => void
+  channel: (descriptor: TraceChannelDescriptor) => void
+  record: (ctx: object, channel: string, entry: Record<string, unknown>) => void
+}
+
+interface TraceStoreOptions = {
+  capacity?: number
+  dbPath?: string | null
+  pruneHours?: number
+}
+
+type DevtoolsGate = (request: Request) => boolean | Promise<boolean>
+
+type EditorName = 'vscode' | 'vscode-insiders' | 'cursor' | 'windsurf' | 'zed' | 'webstorm'
+
+## ./client  `(./src/client/index.ts)`
+
+const DevTools = {    start(opts?: DevtoolsClientOptions): void;}
+
+const SLOW_MS = 300
+
+function buildPathTree = (paths: Array<[string, unknown]>) => Map<string, PathTreeNode>
+
+function facetsActive = (f: Facets) => boolean
+
+function foldTraceRows = (matches: Array<{    trace: RequestTrace;    index: number;}>, channels: TraceChannelDescriptor[], expanded: ReadonlySet<string>) => TraceRow[]
+
+function matchesFacets = (trace: RequestTrace, f: Facets) => boolean
+
+function matchesFilter = (trace: RequestTrace, query: string) => boolean
+
+function methodsPresent = (traces: RequestTrace[]) => string[]
+
+function noFacets = () => Facets
+
+function traceGroupKey = (trace: RequestTrace, channels: TraceChannelDescriptor[]) => string | null
+
+function traceMatches = (trace: RequestTrace, query: string, f: Facets) => boolean
+
+interface DevtoolsClientOptions = {
+  endpoint?: string
+  mode?: 'floating' | 'standalone'
+  mount?: HTMLElement
+}
+
+interface DevtoolsPanelPlugin = {
+  badge?: () => number | string | undefined
+  id: string
+  render: (el: HTMLElement) => void
+  title: string
+}
+
+interface Facets = {
+  errors: boolean
+  methods: string[]
+  nPlusOne: boolean
+  slow: boolean
+  statusClasses: string[]
+}
+
+interface PathTreeNode = {
+  attrs: Record<string, unknown> | null
+  children: Map<string, PathTreeNode>
+}
+
+interface TraceRow = {
+  child: boolean
+  groupKey?: string
+  groupSize?: number
+  index: number
+  trace: RequestTrace
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/devtools",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -9,10 +9,11 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./client": "./src/client.ts"
+    "./client": "./src/client/index.ts"
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -30,11 +31,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.2"
+    "@zerotal/core": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.6.2"
+    "@zerotal/orm": "1.7.0"
   },
   "description": "In-browser developer tools for Zerotal — request traces, an inspector panel, and an extensible tab registry.",
   "keywords": [

package/src/DevtoolsInjectionMiddleware.ts

@@ -1,8 +1,11 @@
 import { fileURLToPath } from "node:url";
 import type { NextFn, HttpContext } from "@zerotal/core";
-import { BaseMiddleware } from "@zerotal/core";
+import { BaseMiddleware, tryCurrentApp } from "@zerotal/core";
 import { traceStore } from "./TraceStore.ts";
 import { traceChannels } from "./tracing.ts";
+import { devtoolsAuthorized, devtoolsSettings } from "./enabled.ts";
+import { buildFrameworkMap } from "./map.ts";
+import { activityFeed } from "./activity.ts";
 
 // ── Injected browser client bundle ────────────────────────────────────────────
 // The in-page devtools panel is bundled for the browser on first request and
@@ -44,6 +47,9 @@ export interface DevtoolsInjectionOptions {
   // reserved for future use
 }
 
+/** Everything the inspector serves lives under here, and is gated as one thing. */
+const DEVTOOLS_PREFIX = "/__zerotal/devtools";
+
 // ── SSE subscribers ───────────────────────────────────────────────────────────
 
 const _sseClients = new Set<ReadableStreamDefaultController<Uint8Array>>();
@@ -130,10 +136,34 @@ export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectio
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
     const { pathname } = http.url;
 
+    // Everything under the prefix is one secret. The stream, the trace JSON, the
+    // dashboard, and the panel bundle all expose the same request data, so they
+    // are gated together and before anything is read — checking per endpoint is
+    // how one of them ends up ungated.
+    if (pathname.startsWith(DEVTOOLS_PREFIX)) {
+      if (!(await devtoolsAuthorized(http.request))) {
+        // 404, not 403: outside development the honest answer to an
+        // unauthenticated stranger is that there is nothing here.
+        return new Response("Not Found", { status: 404 });
+      }
+    }
+
     if (pathname === "/__zerotal/devtools/api/traces") {
       return Response.json(traceStore().all());
     }
 
+    // The framework map: read fresh, never cached. The registries are small and
+    // static, and a cached map is one that disagrees with the app the moment a
+    // provider registers a route late.
+    if (pathname === "/__zerotal/devtools/api/map") {
+      const app = tryCurrentApp();
+      if (!app) return Response.json({ error: "No application in scope" }, { status: 503 });
+      return Response.json({
+        ...buildFrameworkMap(app, devtoolsSettings().redact),
+        activity: activityFeed(),
+      });
+    }
+
     if (pathname === "/__zerotal/devtools/api/channels") {
       return Response.json(traceChannels());
     }
@@ -149,15 +179,22 @@ export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectio
         start(c) {
           ctrl = c;
           _sseClients.add(ctrl);
-          // The opening frame carries the channel descriptors alongside the
-          // history, so a panel can render a package's tab on first paint
-          // instead of waiting for that package's next entry.
+          // The opening frame carries everything the panel needs at first paint
+          // rather than making it ask three more times: the channel descriptors,
+          // so a package's tab is there before that package's next entry; the
+          // store's capacity, so the list trims to the depth the app asked for;
+          // and the editor settings, so a `file:line` is a link on the first
+          // trace rather than the second.
+          const settings = devtoolsSettings();
           ctrl.enqueue(
             _enc.encode(
               `data: ${JSON.stringify({
                 type: "history",
                 data: traceStore().all(),
                 channels: traceChannels(),
+                capacity: traceStore().capacity,
+                editor: settings.editor,
+                editorPathMap: settings.editorPathMap,
               })}\n\n`,
             ),
           );