@bakery-framework/plugin-dashboard 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/client/parts/utils.ts

@@ -4,7 +4,7 @@
  * The panels were built independently and each grew its own copy of the same
  * four things: an element-text setter, a `results-empty` block, a
  * fetch/`.json()` pair, and a prev/next pager. They are declared once here
- * because this file is compiled into the shipped bundle — a duplicated string
+ * because this file is compiled into the shipped bundle: a duplicated string
  * literal is duplicated bytes, the minifier does not merge them.
  *
  * Shrank when the database editor was retired: `executeAction`, `getJson`,
@@ -26,12 +26,12 @@ export function setText(id: string, value: string) {
  * caller happened to pass a literal or escape first, which is exactly the state
  * a codebase is in right before it stops being true. Every XSS found in this
  * repo came from hand-built DOM strings in these panel files, including a
- * stored-XSS to arbitrary-SQL chain through the database grid — which is gone
+ * stored-XSS to arbitrary-SQL chain through the database grid, which is gone
  * now, but the escaping default it argued for is not, because the sessions and
  * stats panels build markup the same way from data they did not write.
  */
 export function emptyBox(message: string, isError = false): string {
-  const style = isError ? ' style="color: var(--accent-red);"' : ''
+  const style = isError ? ' style="color: var(--danger);"' : ''
   return `<div class="results-empty"${style}><span>${escapeHTML(message)}</span></div>`
 }
 
@@ -45,8 +45,8 @@ export function setEmpty(
 
 /**
  * Inline SVGs, built from the path data alone. Every hand-written copy in the
- * panels carried `width="1em" height="1em"` twice — a duplicate attribute the
- * parser silently drops — and the same ~380-byte markup was pasted once per
+ * panels carried `width="1em" height="1em"` twice (a duplicate attribute the
+ * parser silently drops), and the same ~380-byte markup was pasted once per
  * use site.
  */
 export function icon(d: string, size: string): string {
@@ -57,8 +57,9 @@ export function icon(d: string, size: string): string {
   )
 }
 
-export const ICON_EDIT =
-  'M5 19h1.425L16.2 9.225L14.775 7.8L5 17.575zm-2 2v-4.25L16.2 3.575q.3-.275.663-.425t.762-.15t.775.15t.65.45L20.425 5q.3.275.438.65T21 6.4q0 .4-.137.763t-.438.662L7.25 21zM19 6.4L17.6 5zm-3.525 2.125l-.7-.725L16.2 9.225z'
+// `ICON_EDIT` was here. It drew the pencil on the session key editor's Edit
+// button, and that button went with the editor it could not open. See the
+// note in `sessions.ts`. The path data has no other caller.
 export const ICON_DELETE =
   'M7 21q-.825 0-1.412-.587T5 19V6H4V4h5V3h6v1h5v2h-1v13q0 .825-.587 1.413T17 21zM17 6H7v13h10zM9 17h2V8H9zm4 0h2V8h-2zM7 6v13z'
 /** POST a JSON body to a dashboard endpoint and unwrap the envelope. */
@@ -84,67 +85,20 @@ export function setPager(
   if (nextBtn) nextBtn.disabled = page >= totalPages
 }
 
-export class SegmentedProgress {
-  private container: HTMLElement
-  private percent: number
-  private barWidth: number
-  private barGap: number
-  private resizeObserver: ResizeObserver | null = null
-
-  constructor(
-    container: HTMLElement,
-    percent: number,
-    barWidth = 4,
-    barGap = 6,
-  ) {
-    this.container = container
-    this.percent = percent
-    this.barWidth = barWidth
-    this.barGap = barGap
-    this.init()
-  }
-
-  private init() {
-    this.container.classList.add('segmented-progress-container')
-    if (this.barGap !== 6) {
-      this.container.style.gap = `${this.barGap}px`
-    }
-
-    if (typeof ResizeObserver !== 'undefined') {
-      this.resizeObserver = new ResizeObserver(() => this.draw())
-      this.resizeObserver.observe(this.container)
-    }
-
-    this.draw()
-  }
-
-  public destroy() {
-    if (this.resizeObserver) {
-      this.resizeObserver.disconnect()
-    }
-  }
-
-  public draw() {
-    const containerWidth = this.container.clientWidth
-    if (containerWidth === 0) return
-
-    const count = Math.floor(
-      (containerWidth + this.barGap) / (this.barWidth + this.barGap),
-    )
-    const activeCount = Math.round((this.percent / 100) * count)
-
-    let html = ''
-    for (let i = 0; i < count; i++) {
-      const className = i < activeCount ? 'active' : 'inactive'
-      let styleAttr = ''
-      if (this.barWidth !== 4) {
-        styleAttr = ` style="width: ${this.barWidth}px;"`
-      }
-      html += `<div class="segmented-bar-segment ${className}"${styleAttr}></div>`
-    }
-    this.container.innerHTML = html
-  }
-}
+/*
+ * `SegmentedProgress` was here, and nothing it drew was ever visible.
+ *
+ * It filled a `.segmented-progress-container` with one `div` per 10px of
+ * width and watched the container with a `ResizeObserver`. Neither that
+ * class nor `.segmented-bar-segment` has a rule in the sheet - grep it - so
+ * the container is a bare block with no height and the segments are bare
+ * blocks with no width. Measured against a running console on the Traffic
+ * panel: 10 containers, 98 children each, every one of them 0px tall.
+ *
+ * So it cost 980 nodes and 10 `ResizeObserver`s per render of that panel,
+ * redrawn on every resize, to show nothing. The list it sat under - path and
+ * hit count - works and stays.
+ */
 
 export function getWebSocketUrl(path: string) {
   const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'

package/src/components/DBBrowser.tsx

@@ -9,7 +9,7 @@
  * shipping a second, weaker copy.
  *
  * Rendered **only when nothing serves `/_db`**. With the explorer mounted the
- * nav entry links straight to it and this panel never appears — a tab whose
+ * nav entry links straight to it and this panel never appears: a tab whose
  * whole content is "go there" is a click of ceremony in front of going there.
  * Without it, this is what explains where the editor went.
  *
@@ -24,7 +24,6 @@ export function renderDatabaseBrowser() {
         <div class="browser-header">
           <div class="table-info">
             <h2>
-              <iconify-icon icon="lucide:database"></iconify-icon>
               <span>Database</span>
             </h2>
           </div>
@@ -43,7 +42,6 @@ export function renderDatabaseBrowser() {
           </p>
           <div class="modal-actions">
             <a class="btn btn-primary" href="/_db">
-              <iconify-icon icon="lucide:external-link"></iconify-icon>
               <span>Open Database Explorer</span>
             </a>
           </div>

package/src/components/LogsPanel.tsx

@@ -10,14 +10,12 @@ export function renderLogsPanel() {
               class="btn btn-secondary"
               onclick="toggleLogsPlay()"
               id="btn-logs-play">
-              <iconify-icon icon="lucide:pause"></iconify-icon>
               <span>Pause</span>
             </button>
             <button
               type="button"
               class="btn btn-secondary btn-danger"
               onclick="clearLogs()">
-              <iconify-icon icon="lucide:trash-2"></iconify-icon>
               <span>Clear Logs</span>
             </button>
             <label>

package/src/components/SessionsPanel.tsx

@@ -13,7 +13,6 @@ export function renderSessionsPanel() {
             type="button"
             class="btn btn-secondary"
             onclick="loadSessions()">
-            <iconify-icon icon="lucide:refresh-cw"></iconify-icon>
             <span>Refresh Sessions</span>
           </button>
         </div>
@@ -62,7 +61,6 @@ export function renderSessionsPanel() {
               id="session-page-prev"
               class="btn btn-secondary"
               onclick="prevSessionPage()">
-              <iconify-icon icon="lucide:chevron-left"></iconify-icon>
               <span>Prev</span>
             </button>
             <span id="session-page-info">Page 1 of 1</span>
@@ -72,7 +70,6 @@ export function renderSessionsPanel() {
               class="btn btn-secondary"
               onclick="nextSessionPage()">
               <span>Next</span>
-              <iconify-icon icon="lucide:chevron-right"></iconify-icon>
             </button>
           </div>
           <div class="rows-meta">

package/src/components/StatsPanel.tsx

@@ -54,7 +54,6 @@ export function renderStatsPanel() {
 
       <div class="section-header">
         <h2>
-          <iconify-icon icon="lucide:area-chart"></iconify-icon>
           <span>Performance History</span>
         </h2>
         <div class="timescale-selector">
@@ -223,24 +222,6 @@ export function renderStatsPanel() {
             </span>
           </div>
         </div>
-        <div class="chart-card glass-effect" id="chart-db-hits">
-          <span class="card-title">DB Hits History</span>
-          <span class="card-sub">
-            Database query executions (last 1 min, 1s resolution)
-          </span>
-          <canvas id="canvas-db-hits" class="big-chart"></canvas>
-          <div class="chart-stats">
-            <span>
-              MIN: <strong id="dbHits-min">-</strong>
-            </span>
-            <span>
-              MAX: <strong id="dbHits-max">-</strong>
-            </span>
-            <span>
-              AVG: <strong id="dbHits-avg">-</strong>
-            </span>
-          </div>
-        </div>
         <div class="chart-card glass-effect" id="chart-error-page-hits">
           <span class="card-title">Error Page Hits History</span>
           <span class="card-sub">

package/src/components/TopPagesPanel.tsx

@@ -3,7 +3,6 @@ export function renderTopPagesPanel() {
     <div id="panel-top-pages" class="panel">
       <div class="section-header">
         <h2>
-          <iconify-icon icon="lucide:file-text"></iconify-icon>
           <span>Top Visited Pages</span>
         </h2>
         <div class="timescale-selector">

package/src/endpoints/logs-socket.ts

@@ -0,0 +1,72 @@
+import { WebSocketHandler } from '@bakery-framework/core/handlers'
+import { connectedLoggers } from '@bakery-framework/core/logger'
+import { isAnalyticsAuthorized } from '@bakery-framework/plugin-analytics/stats'
+import type { ServerWebSocket } from 'bun'
+
+/**
+ * The console's log stream.
+ *
+ * **The Logs panel was dead in production**, and only in production. Its client
+ * connected to `/_livereload`, which `LiveReloadHandler` serves, and that
+ * handler is registered only under `DEV` and refuses in `canHandle` besides.
+ * So a production server answered 400 on the upgrade, nothing ever joined
+ * `connectedLoggers`, and the panel sat on "Connecting to server log
+ * stream..." for the life of the process. Measured against `bun run serve`
+ * before this existed: `/_livereload` → 400, console → 200.
+ *
+ * Same shape as the bundle ETag bug and the timescale import before it: a dev
+ * server takes a different branch, so the thing works on the machine where it
+ * is written and nowhere else.
+ *
+ * **Not fixed by registering `LiveReloadHandler` in production.** That socket
+ * is the *watcher's*: it publishes `force_reload` to every subscriber and
+ * echoes `client_log` frames between browsers. Shipping it to production would
+ * be adding a surface, not repairing one. The console owns its own panel, so
+ * it owns its own socket, which is the same split analytics already has with
+ * `/_analytics_ws`.
+ *
+ * Membership is the only thing this does. Core owns the registry
+ * (`logger/clients.ts`) and the dashboard's `setLogCallback` does the
+ * broadcasting; in development `LiveReloadHandler` adds app pages to the same
+ * Set when they forward their console, which is why those lines show up here
+ * too.
+ */
+export class DashboardLogsHandler extends WebSocketHandler {
+  static override readonly namespace = '/_dashboard'
+
+  /**
+   * **The door is checked here because there is nowhere later.**
+   *
+   * `router.ts` attempts the upgrade before `onRoute`, before `onRequest` and
+   * before any fetch handler resolves, so a plugin hook cannot gate a socket.
+   * `AnalyticsWSHandler` carries the same note for the same reason.
+   *
+   * It is the console's own door: `isAnalyticsAuthorized` is what guards
+   * `/_dashboard` itself, so a stream of every server log line is admitted by
+   * exactly what admits the page that renders it. Anything weaker would hand
+   * out log lines to someone who cannot open the console.
+   *
+   * Async because `authorize` may be a predicate the application supplies; the
+   * registry awaits a promise-returning `canHandle`.
+   *
+   * The path sits inside `/_dashboard`, which `DashboardHandler` claims for
+   * *fetch* at priority 120. That is not a collision: the upgrade is dispatched
+   * from a separate registry and runs first, so the fetch handler never sees
+   * this request.
+   */
+  static override async canHandle(
+    path: string,
+    req?: Request,
+  ): Promise<boolean> {
+    if (path !== '/_dashboard/logs') return false
+    return req ? await isAnalyticsAuthorized(req) : false
+  }
+
+  static override open(ws: ServerWebSocket<any>) {
+    connectedLoggers.add(ws)
+  }
+
+  static override close(ws: ServerWebSocket<any>) {
+    connectedLoggers.delete(ws)
+  }
+}

package/src/endpoints/sessions.ts

@@ -46,7 +46,7 @@ export async function handleUpdateSession(
     return response.json.error(400, 'Invalid payload')
 
   // Without this, editing a session could set the dashboard's own auth marker
-  // on any user's session — a permanent backdoor.
+  // on any user's session: a permanent backdoor.
   if (isReservedSessionKey(key)) {
     return response.json.error(403, 'Reserved session key')
   }

package/src/index.ts

@@ -3,7 +3,7 @@ import type { AuthorizeFn } from '@bakery-framework/core/utils/http'
 
 /**
  * Re-exported so the plugin's public surface is unchanged by the guard moving
- * into core. It is the same type either way — an app that imported it from here
+ * into core. It is the same type either way: an app that imported it from here
  * keeps working, and one that reaches for `@bakery-framework/core/utils/http`
  * directly gets the identical declaration rather than a structural twin.
  */
@@ -12,7 +12,7 @@ export type { AuthorizeFn } from '@bakery-framework/core/utils/http'
 export interface DashboardPluginOptions {
   /**
    * Register the dashboard. Defaults to true. Set to false to keep it out of a
-   * build entirely — the documented way to disable it in production.
+   * build entirely: the documented way to disable it in production.
    */
   enabled?: boolean
 
@@ -32,7 +32,7 @@ export interface DashboardPluginOptions {
    * production, so an unconfigured console is never exposed.
    *
    * Handed straight to `@bakery-framework/plugin-analytics`, which owns the
-   * door for both surfaces — so this predicate also admits to
+   * door for both surfaces, so this predicate also admits to
    * `/api/_analytics/stats` and the `/_analytics_ws` socket the console reads.
    */
   authorize?: AuthorizeFn
@@ -46,13 +46,13 @@ export interface DashboardPluginOptions {
    *
    * Presented as `Authorization: Bearer`, an `x-analytics-key` header, or an
    * `?analytics-key=` query. Checked in constant time. Unset or empty means
-   * this path is off — it never means open. Composes with `authorize`: either
+   * this path is off: it never means open. Composes with `authorize`: either
    * admits.
    *
    * It is the *analytics* key, not a second one: the console delegates its
    * authorization to `@bakery-framework/plugin-analytics`, so configuring it
    * here and configuring it on `analyticsPlugin` are the same act. Set it on
-   * either plugin — a bare call never clears what the other one set.
+   * either plugin: a bare call never clears what the other one set.
    */
   credential?: string
 }
@@ -64,7 +64,7 @@ export interface DashboardPluginOptions {
  * companion: the console renders analytics, its client calls
  * `/api/_analytics/reset` and opens `/_analytics_ws`, and registering the
  * dashboard brings analytics' handlers up so those endpoints exist. It follows
- * that they share one door rather than two — see `authorize` and `credential`
+ * that they share one door rather than two. See `authorize` and `credential`
  * above.
  */
 export default function dashboardPlugin(options: DashboardPluginOptions = {}) {

package/src/paths.ts

@@ -3,7 +3,7 @@ import { fs } from '@bakery-framework/core/utils'
 /**
  * Where this plugin's own files live.
  *
- * Not `frameworkPath()` — that anchors to `@bakery-framework/core`, so once the dashboard
+ * Not `frameworkPath()`: that anchors to `@bakery-framework/core`, so once the dashboard
  * became its own package every asset lookup pointed into core and 404'd. Each
  * package that ships files needs its own anchor, derived from its own location.
  */

package/src/setup.ts

@@ -2,7 +2,7 @@ import { bundleModule } from '@bakery-framework/core/compiler'
 import { Bakery } from '@bakery-framework/core/core/bakery'
 import { isDevWorker } from '@bakery-framework/core/core/init'
 import { Handler, mountRoutes } from '@bakery-framework/core/handlers'
-// LiveReloadHandler owns this registry — it adds and removes sockets from it.
+// LiveReloadHandler owns this registry: it adds and removes sockets from it.
 import {
   connectedLoggers,
   errorMsg,
@@ -31,6 +31,7 @@ import {
   handleGetSessions,
   handleUpdateSession,
 } from './endpoints/sessions'
+import { DashboardLogsHandler } from './endpoints/logs-socket'
 import { pluginPath } from './paths'
 import renderDashboardShell from './shell'
 
@@ -42,7 +43,7 @@ let cachedDashboardJsPath: string | null = null
  * `/_dashboard` and `/api/_dashboard` are namespace *roots*, not prefixes.
  *
  * A bare `startsWith` also matches `/api/_dashboard-anything`, and this handler
- * outranks every content handler at priority 120 — so the prefix form silently
+ * outranks every content handler at priority 120, so the prefix form silently
  * claimed, and then 404'd, any application route whose path merely began with
  * those characters. Match the root itself or a segment below it, nothing else.
  */
@@ -57,9 +58,11 @@ function isDashboardPath(path: string): boolean {
 }
 
 export class DashboardHandler extends Handler {
+  static override namespace = '/_dashboard'
+
   static canHandle(path: string) {
     // Deliberately narrow. This handler outranks every content handler, so
-    // anything it claims can never reach the route mount below — assets must
+    // anything it claims can never reach the route mount below: assets must
     // fall through.
     if (inNamespace(path, '/api/_dashboard')) return true
     return path === '/_dashboard' || path === '/_dashboard/dashboard.js'
@@ -82,7 +85,7 @@ export class DashboardHandler extends Handler {
 }
 
 /**
- * The console holds no authorization state of its own — there is no
+ * The console holds no authorization state of its own: there is no
  * `__setTestAuthorize` seam here any more, because there is nothing local to
  * seam. Both options land in analytics, and a test drives the door with
  * `setAnalyticsAuthorize` / `setAnalyticsCredential` from
@@ -94,7 +97,7 @@ export class DashboardHandler extends Handler {
  * the console keeps its documented default of loopback-in-development,
  * because `bun create bakery` scaffolds a bare `dashboardPlugin()` and a
  * console that 404s on the first `bun run dev` is the wrong first impression.
- * Forwarding `defaultAuthorize` can only ever narrow — it denies in
+ * Forwarding `defaultAuthorize` can only ever narrow: it denies in
  * production and admits nothing but this machine in development.
  */
 export function setupDashboard(
@@ -124,9 +127,15 @@ export function setupDashboard(
   })
 
   // The stylesheet is served by the normal static pipeline from this
-  // plugin's own directory — no bespoke asset route, no hand-rolled caching.
+  // plugin's own directory: no bespoke asset route, no hand-rolled caching.
   mountRoutes('/_dashboard', pluginPath('../public'))
 
+  // The console's log stream, and it is registered in every mode. The Logs
+  // panel used to ride on `/_livereload`, which exists only under `DEV`, so
+  // the panel worked on the machine it was written on and answered 400
+  // everywhere else. See `endpoints/logs-socket.ts`.
+  Bakery.handlers.websocket.set(DashboardLogsHandler)
+
   Bakery.handlers.fetch.set(DashboardHandler, 120)
 }
 
@@ -137,10 +146,74 @@ async function handleDashboardView() {
   return injected ? injected : response.html(htmlContent)
 }
 
-async function handleJsAsset() {
+/**
+ * Why the bundle cannot run in a `<script>`, or `null`.
+ *
+ * `bundleModule` marks every *installed* package external, so a bare specifier
+ * survives into the output and resolves through the page's import map. That is
+ * correct for the `/_nm/` bundles, which are loaded as modules. It is fatal
+ * here: this file is served as a classic `<script>`, an import map does not
+ * apply to one, and a top-level `import` is a syntax error, so the *entire*
+ * bundle fails to execute and the console does nothing at all.
+ *
+ * **This asks the engine instead of matching a pattern, and the first version
+ * of it matched a pattern and was wrong.** It anchored on `^import`. In
+ * development the bundle is not minified and the import starts a line, so it
+ * looked right. Production minifies, the import lands mid-line, and the check
+ * that existed to catch exactly this missed it: measured by reintroducing the
+ * bug and watching a production server answer 200 with the import present.
+ *
+ * Against seven shapes, the anchored regex was wrong on three: a minified bare
+ * import, a side-effect-only `import"./x.css"`, and a top-level `await`. A
+ * widened regex got the first two and still missed the third. `new Function`
+ * is wrong on none of them, because it is not approximating the question: a
+ * function body rejects a top-level `import` and a top-level `await` for the
+ * same reasons a classic script does. It also costs less than the widened
+ * regex: 13.0 us against 26.4 on a 24 KB bundle, and 12.0 for the broken one.
+ *
+ * It parses without executing, and only on the build path: the cached branch
+ * returns the file and never reaches here.
+ *
+ * One known difference, and it is in the safe direction: a function body
+ * permits a top-level `return`, which a script does not. `Bun.build` does not
+ * emit one, and a false pass is a missed report rather than a broken page.
+ */
+export function whyUnrunnable(bundle: string): string | null {
+  try {
+    new Function(bundle)
+    return null
+  } catch (error) {
+    return (error as Error).message
+  }
+}
+
+/**
+ * Test seams (convention 9). The cached branch is **production-only** -
+ * `isDevWorker` skips it, and in development the bundle is returned as a
+ * string, which `response.type` does give an ETag. That is why the defect was
+ * invisible to a dev server and had to be reproduced under `bun run serve`,
+ * and why a test has to reach the branch directly rather than through a mode.
+ */
+export function __setCachedDashboardJs(path: string | null): void {
+  cachedDashboardJsPath = path
+}
+
+export async function handleJsAsset() {
   if (cachedDashboardJsPath && !isDevWorker) {
     const cachedFile = Bun.file(cachedDashboardJsPath)
-    if (cachedFile.size > 0) return response.type(cachedFile, 'text/javascript')
+    // **The file, not a `Response` wrapping it.** `processResponse` sends a
+    // `Blob` through `ETag.sendFile`, which computes an ETag from the file,
+    // negotiates a precompressed variant and answers a conditional request
+    // with a 304. A `Response` skips all of that: `ETag.sendResponse` returns
+    // early when there is no ETag header already set, so it gains neither an
+    // ETag nor a `Cache-Control`.
+    //
+    // The first request took this path correctly - it returns the written
+    // file below - and every request after it did not, so the console
+    // re-downloaded 30.6 KB on every load. The content type comes from the
+    // `.js` extension on the cached path, which is what the first request
+    // already relied on.
+    if (cachedFile.size > 0) return cachedFile
   }
 
   const bundleResult = await bundleModule(pluginPath('client/dashboard.ts'))
@@ -155,6 +228,19 @@ async function handleJsAsset() {
     )
   }
 
+  // See `whyUnrunnable`. A build that "succeeded" and cannot run is worse than
+  // one that failed, because it is silent.
+  const unrunnable = whyUnrunnable(bundleResult.content as string)
+  if (unrunnable) {
+    pluginLog.DASHBOARD_BUNDLE_ERR({
+      error: `dashboard.js cannot run as a classic script: ${unrunnable}. The usual cause is an import across a package boundary, which the bundler leaves as a bare specifier for the import map, and an import map does not apply to a classic script.`,
+    })
+    return response.error(
+      `dashboard.js cannot run as a classic script: ${unrunnable}`,
+      500,
+    )
+  }
+
   if (!isDevWorker) {
     const tmpPath = `${Bakery.cacheDir}/_dashboard.js`
     await Bun.write(tmpPath, bundleResult.content)
@@ -171,7 +257,7 @@ async function handleJsAsset() {
 /**
  * One door, and it is analytics'. `isAnalyticsAuthorized` reads the same
  * credential and the same predicate that gate `/api/_analytics/stats` and the
- * `/_analytics_ws` socket — which the console's own client calls, so a console
+ * `/_analytics_ws` socket, which the console's own client calls, so a console
  * admitted by a different key than the data it renders would be half-open by
  * construction.
  *
@@ -184,7 +270,7 @@ async function handleJsAsset() {
  */
 async function checkAuthMiddleware(req: Request, path: string) {
   // Styling and script for the console are not secrets, and letting them
-  // through keeps an unauthorised response from rendering unstyled.
+  // through keeps an unauthorized response from rendering unstyled.
   if (/\.(css|js)$/.test(path)) return null
 
   if (await isAnalyticsAuthorized(req)) return null
@@ -195,7 +281,7 @@ async function checkAuthMiddleware(req: Request, path: string) {
 }
 
 /**
- * `checkCsrf` has exactly one other call site — inside `ApiHandler`, at
+ * `checkCsrf` has exactly one other call site: inside `ApiHandler`, at
  * priority 70. This handler sits at 120 and claims the whole `/api/_dashboard`
  * namespace, so `ApiHandler.handle` never ran for these paths and the check
  * never happened: a cross-origin `<form method=post>` arrived with the
@@ -208,7 +294,7 @@ async function checkAuthMiddleware(req: Request, path: string) {
  * that reason; neither half closes the hole alone.
  *
  * The example used to be `execute-action?action=truncate`, which was the worst
- * of them — a link that emptied a table. That endpoint is gone with the grid
+ * of them: a link that emptied a table. That endpoint is gone with the grid
  * editor, and the two session routes are what is left to protect. The hazard
  * is unchanged; only the blast radius shrank.
  */
@@ -222,11 +308,11 @@ function checkCsrfMiddleware(req: Request, url: URL): DashboardResponse | null {
 }
 
 /**
- * Authenticated routes only — the logout/login cases below run before the auth
+ * Authenticated routes only: the logout/login cases below run before the auth
  * check and are deliberately kept out of this table.
  *
  * Every mutating endpoint is method-qualified. A bare key matches **any**
- * method, which made each of these reachable by GET — and a GET is a safe
+ * method, which made each of these reachable by GET, and a GET is a safe
  * method as far as `checkCsrf` is concerned, so the CSRF guard above cannot
  * see it. `POST /api/_analytics/reset` is the same shape.
  *
@@ -248,8 +334,8 @@ const dispatchDashboardRoute = routeTable(dashboardRoutes)
  * Three genuinely different shapes, so a union rather than a single type: the
  * shell is a `Response`, `dashboard.js` is served straight off disk as a
  * `Bun.BunFile` once it has been bundled and cached, and every `/api/` endpoint
- * answers with the JSON envelope. `processResponse` in `router.ts` serialises
- * all three — `Response` passes through, a `Blob` goes to `ETag.sendFile`, and
+ * answers with the JSON envelope. `processResponse` in `router.ts` serializes
+ * all three: `Response` passes through, a `Blob` goes to `ETag.sendFile`, and
  * a `JsonResponseData` is stamped with the elapsed time and JSON-encoded.
  */
 export type DashboardResponse =
@@ -278,7 +364,7 @@ export async function handleDashboardRequest(
   if (result) return result
 
   // `dispatch` answers `null` for a path no key matched, and a handler
-  // returning `null` means "not mine" — which core turns into **204 No
+  // returning `null` means "not mine", which core turns into **204 No
   // Content**. Every unmatched request under this namespace therefore answered
   // 204: a status that reads as success and carries nothing.
   //
@@ -290,7 +376,7 @@ export async function handleDashboardRequest(
   // **Only under `/api/`, and that boundary is load-bearing.** The stylesheet
   // is served by `mountRoutes`, not by a key in the table above, so `null` is
   // precisely how `/_dashboard/style.css` *falls through* to the static
-  // pipeline. A blanket 404 here claims it and the console loads unstyled —
+  // pipeline. A blanket 404 here claims it and the console loads unstyled,
   // which is what happened when this was first written without the condition.
   if (path.startsWith('/api/')) return response.error('Not Found', 404)
   return null