jskelet 0.1.1 → 0.1.3

package/docs/en/08-build.md

@@ -0,0 +1,383 @@
+# 08 — Build
+
+This document describes every job `jskelet build` does and the order it does them
+in: font copying, icon sprite generation, Tailwind CSS compilation, the island
+bundle via esbuild, image optimisation, writing the manifest and precompression.
+It also covers how hashed assets reach the templates through
+`asset()`/`hasAsset()`, why Tailwind's `@source` directives are mandatory and how
+optional peer dependencies behave. How the output is served at runtime is in
+[02-architecture.md](./02-architecture.md), and the watch flow that triggers the
+build is in [09-dev-tools.md](./09-dev-tools.md).
+
+## The pipeline and its order
+
+```
+1. Fonts          if config.fonts is set
+2. Icon sprite    if config.icons !== false
+3. CSS            if the styles entry file exists
+4. Client JS      if client/entries/ exists
+5. Images         if config.images !== false, not watch, and sharp is installed
+6. Manifest       .jskelet/manifest.json
+7. Precompress    if not watch
+```
+
+The order is not arbitrary:
+
+- **CSS comes after the icon sprite.** The sprite is an asset and produces no
+  classes, but it does give a manifest key.
+- **Precompress is last:** everything that gets compressed must already be
+  produced.
+- **Images never run on a watch pass:** re-encoding with `sharp` is expensive.
+
+Tasks only run if the relevant configuration exists. A project that does not
+define any fonts never sees the font step; this is the build-side counterpart of
+the principle that "the framework does not impose its own assumptions on every
+project".
+
+The terminal output gives aligned step lines and an `output` block at the end:
+the raw and brotli size of every asset, largest to smallest.
+
+## The manifest and hashed assets
+
+The build output is written under `public/assets/` with **content-hashed** names,
+and the logical name → public URL mapping is put in the `.jskelet/manifest.json`
+file:
+
+```json
+{
+  "app.css": "/assets/app.4f2a1b9c07.css",
+  "sprite.svg": "/assets/sprite.dc973997bd.svg",
+  "main.js": "/assets/js/main.9E1AB2C3.js",
+  "inter-400.woff2": "/fonts/inter-400.woff2"
+}
+```
+
+The hash is the first 10 hex characters of sha256: more than enough against
+collisions and it keeps file names readable. Because they are hashed, these files
+can be given `Cache-Control: public, max-age=31536000, immutable`.
+
+### `asset(name)` and `hasAsset(name)`
+
+They are passed to templates automatically; in server code,
+`import { asset, hasAsset } from "jskelet"`.
+
+```ejs
+<% if (hasAsset('app.css')) { %>
+<link rel="stylesheet" href="<%= asset('app.css') %>">
+<% } %>
+```
+
+- `asset(name)` returns the hashed URL if it is in the manifest, otherwise
+  `/assets/<name>`.
+- `hasAsset(name)` tells you whether it is in the manifest.
+
+If the build has not run, the application still comes up: `hasAsset()` is false
+and the layout never emits the stylesheet and script tags. When `jskelet build`
+is forgotten you get an unstyled but working page instead of an error. If the
+manifest is missing entirely, a warning is printed once:
+``[assets] no manifest — run `jskelet build`.``
+
+The manifest is re-read **on every request in dev** (watch builds change the
+hashes) and once in prod.
+
+### Manifest consistency in watch mode
+
+On a watch pass, a recompiled asset is written to a new hash and the old one is
+deleted. That is why the manifest has to be updated too (`patchManifest`):
+otherwise the HTML asks for the deleted file, gets a 404, and the page stays
+unstyled or JS-less for the rest of the dev session. Both the CSS and the client
+tasks patch their own key on every pass; the other keys are preserved.
+
+## CSS — Tailwind v4
+
+The entry file is `paths.styles` (default `styles/globals.css`). If the file does
+not exist, the step is skipped with a warning.
+
+The pipeline: PostCSS + `@tailwindcss/postcss` → minification with lightningcss
+(if present) → `writeAsset("app.css", …)`.
+
+- **The PostCSS pipeline is set up once:** Tailwind's own cache lives in the
+  plugin instance; recreating it on every compile slows watch passes down
+  noticeably.
+- **lightningcss is optional:** without it, Tailwind's own output is used, and it
+  is only a few kB bigger.
+- The output is a single file and the layout loads it render-blocking. The
+  measurement-based reasoning for not producing a separate "critical CSS" is in
+  [02-architecture.md](./02-architecture.md).
+
+### `@source` directives are mandatory
+
+Tailwind v4's class scanning depends on the `@source` directives inside
+`globals.css`. Automatic detection only scans the directory the stylesheet lives
+in, so the variants used in templates (things like `data-[active=false]:…`) get
+**silently dropped**.
+
+```css
+@import "tailwindcss" source(none);
+
+@source "../views";
+@source "../client";
+@source "../routes";
+
+.wrapper {
+  max-width: 48rem;
+  margin-inline: auto;
+  padding-inline: 1rem;
+  padding-block: 2rem;
+}
+```
+
+`source(none)` turns automatic detection off and makes the scanning fully
+explicit. **When you add a new top-level directory, add the `@source` line as
+well** — this is the most common reason for classes "sometimes not working".
+
+### CSS watch scope
+
+In watch mode three targets are watched: the directory the stylesheet lives in,
+`views` and `client`. Template and island files are watched too because the
+Tailwind classes come from there; watching only `styles/` would not rebuild when
+a new utility is written. Changes are coalesced over 120 ms.
+
+## Client JS — esbuild
+
+Every `.js` file inside `client/entries/*.js` is an entry. If the directory does
+not exist or is empty, the step is skipped.
+
+esbuild settings:
+
+| Setting | Value | Reason |
+| --- | --- | --- |
+| `bundle`, `splitting` | `true` | Shared modules move into a shared chunk |
+| `format` | `esm` | `type="module"` scripts |
+| `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | The lower bound of the ESM + dynamic import + `IntersectionObserver` island model; transpiling to anything older grows the output without winning a single visitor |
+| `minify` | `true` | — |
+| `sourcemap` | `true` | Diagnostics in the browser |
+| `entryNames` | `[name].[hash]` | `immutable` cache |
+| `chunkNames` | `chunks/[name].[hash]` | — |
+| `legalComments` | `none` | — |
+
+The output lands under `public/assets/js/` and is cleaned first on every pass.
+`browserslist` is not read; the target list is hard-coded.
+
+### The `@/` alias
+
+On the esbuild side, `@/` resolves to the project root and extension completion
+is performed (`.js`, `.mjs`, `.json`, `/index.js`). The same behaviour as
+`alias-hooks.mjs` on the Node side, so the modules under `lib/` can use the same
+import style both on the server and in the browser.
+
+### Inlining `clientEnv`
+
+There is no `process` in the browser; modules shared with the server still read
+`process.env`. The keys declared through `config.clientEnv` plus `NODE_ENV` are
+defined as a single object at build time, which means that reading a key not in
+the list returns `undefined` instead of crashing. Details:
+[07-configuration.md](./07-configuration.md).
+
+### Manifest keys
+
+Only **real entries** go into the manifest: dynamic imports also carry an
+`entryPoint`, and if they were not filtered out every island would become a
+separate manifest key. The key is the file name itself (`main.js`, `chart.js`),
+the value is the hashed URL.
+
+That is why a controller writing `entries: ["chart.js"]` does not have to know
+the hash ([05-islands.md](./05-islands.md)).
+
+### `metafile.json`
+
+The esbuild metafile is written to the `.jskelet/metafile.json` file; the chunk
+analysis in the dev panel reads the input/output breakdown from there. If the
+write fails, the build does not go down — the analysis data is best-effort. **The
+runtime does not depend on this file.**
+
+## Fonts
+
+Self-hosted font files instead of `next/font/google`.
+
+The files sit under `public/fonts/` with **fixed names** (no hash), because the
+`url()` paths inside `@font-face` are written by hand; hashing them would force
+the stylesheet to change on every build too.
+
+If a file is missing, it is downloaded from Google Fonts **once** and is
+**expected to be committed**: having the build depend on the network is fragile
+in CI. If the download fails, a warning is printed and the page falls back to the
+system font stack — the build does not stop.
+
+Only the latin subset (`U+0000-00FF`) is downloaded: the others are dead weight
+for most sites, and without `unicode-range` downloading all of them multiplies
+the font size.
+
+Usage is written by hand in the stylesheet:
+
+```css
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/fonts/inter-400.woff2") format("woff2");
+}
+```
+
+Because the `.woff2` extension and the `/fonts/` prefix are in the default
+`static` rules, these files automatically get an `immutable` cache.
+
+## Icon sprite
+
+From the individual SVGs inside `@phosphor-icons/core`, it produces a `<symbol>`
+set for **only the icons actually used in the source**. Shipping the whole set
+means 1500+ icons, i.e. several megabytes; usage scanning typically keeps the
+sprite at 10-30 symbols.
+
+- Symbol id: `<kebab-name>-<weight>`, e.g. `arrow-right-bold`.
+- The package is resolved from the **application's** `node_modules` (the icon set
+  is the application's devDependency); if it is not installed, the step is
+  silently skipped.
+- The scanned directories default to `views`, `client`, `routes`, `lib`; they can
+  be changed with `icons.scan`. Scanned extensions: `.ejs`, `.js`, `.mjs`.
+- Weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. An
+  unrecognised weight counts as `regular`.
+
+### What the scan finds
+
+| Form in the source | Is it found |
+| --- | --- |
+| `icon({ name: "ArrowRight", weight: "bold" })` | ✓ name + weight |
+| `icon({ name: cond ? "A" : "B" })` | ✓ both constant names |
+| `data-icon="flag:fill"` or `"data-icon": "flag:fill"` | ✓ |
+| `icon: "XLogo"` / `iconName: "XLogo"` (in configuration lists) | ✓ name; weights are the ones collected from indirect calls |
+| `icon({ name: item.icon })` | ✗ the name is not statically visible |
+
+There are two safety nets for the last row: configuration fields that carry a
+name (`icon: "XLogo"`) are also searched, and in development `icon()` reads the
+symbols in the sprite and prints a one-off warning for a missing one:
+
+```
+[icon] missing from sprite: x-logo-regular — write the name as a literal or add
+it to the build/tasks/icons.mjs scan.
+```
+
+If you see this warning, either write the name as a constant, or add the relevant
+directory to the `icons.scan` list, or keep the name in a configuration field in
+the form `icon: "XLogo"`.
+
+Names that cannot be found in Phosphor are warned about as a summary at the end
+of the build: `N icons missing → …`
+
+## Image optimisation
+
+The build-time counterpart of the `next/image` optimizer. For the png/jpg files
+placed by hand under `public/`, it produces webp at a few widths and writes them
+to the `.jskelet/images.json` manifest. `image()` looks at that manifest and adds
+`srcset` plus intrinsic `width`/`height`; the calling side changes nothing
+([04-rendering.md](./04-rendering.md)).
+
+- The outputs land hashed under `public/assets/img/`, which means they fall
+  within the scope of the `immutable` cache and precompression.
+- **The source files stay where they are:** an image not in the manifest is
+  always served as the original.
+- The `assets` and `fonts` directories are always skipped; additional ones with
+  `images.skip`.
+- The widths are used with the ones larger than the source dropped, and the
+  source's own width (at most 1920) always makes it into the list. Above 1920 is
+  wasteful even on retina screens.
+- The variant hash is derived from the **source + the width**: the same content
+  gives the same file name on every build, so the `immutable` cache does not go
+  stale.
+- The encoder signature is written into the manifest (`webp-q78-e4`). When the
+  quality setting changes, the signature changes with it and every image is
+  re-encoded; otherwise outputs produced with the old setting would silently
+  remain.
+- If the source has not changed and the outputs are still in place, nothing is
+  re-encoded. In a large `public/` directory this brings the build time down from
+  minutes to seconds.
+- A single corrupt/unreadable image does not bring the build down: a warning is
+  printed and, because it is not in the manifest, the original file continues to
+  be served.
+- Old outputs that no longer appear in the manifest are deleted.
+
+This step requires `sharp`. If it is not installed the step is silently skipped
+and `image()` falls back to the original file. It never runs on a watch pass.
+
+## Precompress
+
+Produces brotli (quality 11) and gzip (level 9) copies of the built assets:
+`app.<hash>.css.br`, `app.<hash>.css.gz`, …
+
+- Only `public/assets/` is covered: the files there are hashed and `immutable`,
+  meaning their contents never change and recompressing them on every request is
+  wasted CPU. Compressing once at build time with quality 11 both zeroes out the
+  server load and gives a ratio you could never afford at runtime (as against
+  quality 5 at request time).
+- Files placed by hand under `public/` are left to runtime compression, because
+  they are small and requested rarely.
+- Compressed extensions: `.css`, `.js`, `.mjs`, `.svg`, `.json`, `.xml`,
+  `.txt`, `.map`. Already-compressed formats (woff2, png, jpg, webp) are skipped.
+- Files under 1 KB are skipped: the gain does not cover the header cost.
+- `.br`/`.gz` copies left over from the previous pass are deleted first, so they
+  cannot go stale.
+- It does not run in watch mode: quality-11 brotli on every change is slow.
+
+These files are served by the `staticPrecompressed` middleware; if there is no
+copy, the request is handed over to `express.static`
+([02-architecture.md](./02-architecture.md)).
+
+## Optional peer dependencies
+
+| Package | The step that needs it | What happens without it |
+| --- | --- | --- |
+| `postcss` | CSS | The CSS step **throws** (a required import) |
+| `@tailwindcss/postcss` | CSS | The CSS step **throws** |
+| `tailwindcss` | CSS (peer) | Tailwind directives cannot be resolved |
+| `lightningcss` | CSS minification | Tailwind's output is used, a few kB bigger |
+| `sharp` | Image optimisation | The step is skipped; `image()` uses the original |
+| `@phosphor-icons/core` | Icon sprite | The step is skipped; `icon()` produces an empty `<use>` |
+
+If you are not going to use CSS, simply never create the `paths.styles` file: the
+step is skipped with a warning and postcss is not needed.
+
+The packages are resolved from the **application's** `node_modules`, not the
+framework's own. If the framework is installed via a `file:` or workspace link,
+its source files run in their own directory and a plain `import "postcss"` looks
+at the framework's tree — not yours. That is why resolution is started from the
+application root.
+
+## Suggested `.gitignore`
+
+```
+node_modules/
+.jskelet/
+public/assets/
+.env
+```
+
+`public/fonts/` **should be committed** (so the build does not depend on the
+network), `public/assets/` should not be (it is regenerated on every build).
+
+## `jskelet start` and a missing build
+
+`jskelet start` first looks at the `.jskelet/manifest.json` file; if it is
+missing, it runs the build itself. In a Docker image the build has already
+happened so this is a no-op; the point is that someone running `npm start`
+directly does not end up facing an unstyled page.
+
+## Diagnostics: common situations
+
+- **No styles at all.** The build has not run (`hasAsset('app.css')` is false) or
+  the `paths.styles` file does not exist. Check the `CSS` line in the build
+  output.
+- **Some Tailwind classes do not work.** They were written in a directory whose
+  `@source` directive is missing.
+- **An icon looks empty.** That symbol is not in the sprite; in dev, look for the
+  `[icon] missing from sprite` warning.
+- **The islands never open.** `main.js` is not in the manifest (the entry
+  directory is empty or the build was skipped) or there is a build error.
+- **The page suddenly went unstyled in dev.** The manifest and the file on disk
+  have diverged; restarting `jskelet dev` is enough.
+
+## What's next
+
+- The watch flow and CSS hot-swap: [09-dev-tools.md](./09-dev-tools.md)
+- Prod build + start and Docker: [10-deployment.md](./10-deployment.md)
+- Using `entries` and the island bundle: [05-islands.md](./05-islands.md)

package/docs/en/09-dev-tools.md

@@ -0,0 +1,314 @@
+# 09 — Development tools
+
+This document explains what `jskelet dev` does and why it does it that way: how
+the two child processes are managed, the shape of the terminal output, the
+watched directories and the reason a custom watcher was written instead of using
+`node --watch`, the distinction between CSS hot-swap and a full reload, the
+devtools overlay opened with `Alt+D`, the detailed report page, and the dev gate
+built on `DEV_TOKEN`. The build steps themselves are in
+[08-build.md](./08-build.md).
+
+## The `jskelet dev` flow
+
+The command manages two long-lived child processes in a single terminal:
+
+```
+jskelet dev
+├─ build watch   node src/build/build.mjs --watch
+└─ server        node [--env-file=.env] --import <register.mjs> src/start.mjs
+```
+
+`NODE_ENV=development` is assigned here in a platform-independent way — no
+`cross-env` needed. The child processes also receive `JSKELET_CHILD=1`
+(suppresses the build banner) and, if a TTY is present, `JSKELET_COLOR=1`
+(forces color on piped output).
+
+Startup order: banner → build steps → server ready → `Ready` summary. The
+summary is printed once both the build and the server are ready; otherwise it
+got buried among the build lines arriving afterwards.
+
+The server signals readiness with a single line inside `startServer`:
+
+```
+jskelet → http://localhost:3000 (development)
+```
+
+The shape of this line is a contract; the dev script parses it and prints the
+summary line accordingly.
+
+### The shape of the terminal output
+
+Child process output does not stream through as-is. There are two regions and
+they never mix:
+
+1. **Startup:** banner, aligned build lines, `Ready` summary.
+2. **Runtime:** timestamped, single-line events (HTTP requests, CSS rebuild,
+   server restart).
+
+Error stacks are turned into a framed box: because stack lines arrive in
+fragments, they are collected after a short silence (60 ms), the error name and
+message are parsed, the first three frames are shown, and the project root is
+shortened to `.`. When you are developing your own framework, not losing the
+error in the stream is the detail that genuinely makes a difference.
+
+Color carries meaning: `✓` green, `✖` red, `⚠` yellow, `↻` cyan; durations and
+paths gray. No decorative color is used. If `NO_COLOR` is set, no color is used
+at all.
+
+`Ctrl+C` (SIGINT/SIGTERM) shuts down all child processes. If a child exits with
+a non-zero code (other than an expected restart), an error is printed and the
+dev process exits too.
+
+## Watch directories
+
+Server restarts are managed by the framework's own watcher.
+
+```js
+WATCH_DIRS = [
+  config.dirs.routes,
+  config.dirs.views,
+  <root>/lib,
+  ...config.watch,   // jskelet.config.mjs → watch
+]
+```
+
+The `jskelet.config.mjs` file itself is watched as well: when the config
+changes, both the server and the build must come up with the new settings.
+
+Watched extensions: `.js`, `.mjs`, `.json`, `.ejs`.
+
+`views` is watched too, because most components live in
+`views/components/**.js` and, since those modules are imported into the server
+once, changes made without a restart never reached the browser (that "I edited
+the template and nothing changed" feeling comes from here).
+
+`client/` and `styles/` are **not** in this list: esbuild and the CSS watchers
+handle them on their own ([08-build.md](./08-build.md)).
+
+If a directory cannot be watched, a warning is printed and no automatic restart
+happens for that directory; everything else keeps working.
+
+### Why `node --watch` was not used
+
+Even when given `--watch-path`, Node watched the project root in this setup.
+Whenever build output (`public/assets`, `manifest.json`) or the dev tooling log
+was written, the server restarted for nothing — in fact a self-feeding loop was
+set up: restart → startup warning → write → restart.
+
+The custom watcher does three things:
+
+1. **Watches only server sources.**
+2. **Coalesces changes** (250 ms) and reports which files changed.
+3. **Filters out phantom events.** On Windows, `fs.watch` can emit events for a
+   file's neighbors when it is written; without comparing `mtime`, a single save
+   turned into two restarts. Current timestamps are read up front at startup, so
+   the first phantom event is filtered out as well.
+
+The restart line shows the changed file, or how many changed:
+
+```
+21:04:12 ↻ server  restarting…  routes/10-pages.mjs
+21:04:12   server  restarted    412ms
+```
+
+If `JSKELET_VERBOSE=1` is set, all files are listed when more than one changed.
+
+## CSS hot-swap and full reload
+
+The dev server watches `.jskelet/manifest.json` and broadcasts events to the
+browser over an SSE channel (`<devBasePath>/events`). Since the manifest is
+rewritten on every build round, change detection is done through the manifest.
+
+| What changed | Behavior |
+| --- | --- |
+| Only `app.css` | **CSS hot-swap:** the stylesheet is swapped, the page is not reloaded. State and scroll position are preserved. |
+| `main.js`, the sprite, another asset, or more than one key | **Full reload** |
+
+In both cases the HTML cache is cleared first: the stored HTML carries the old
+hashed asset URLs and, if not cleared, the page keeps asking for a deleted file.
+
+Manifest events are coalesced over 120 ms. If watching is not supported, live
+reload is disabled and everything else keeps working.
+
+When the server restarts, the overlay figures it out from the **boot id**: every
+process broadcasts a unique `boot` value, the overlay sees the change, shows the
+"restarted" note and does not reset its own state.
+
+## Devtools overlay
+
+A floating bubble in the bottom right; opened with `Alt+D`, closed with `Esc` or
+by clicking the backdrop. It is only emitted by the layout when
+`NODE_ENV=development`:
+
+```ejs
+<% if (devtools) { %>
+<script type="module" src="<%= devBasePath %>/overlay.js"></script>
+<% } %>
+```
+
+The overlay file is **not part of the build.** The server serves it raw from the
+framework package; that is why there is no bundler involved, it works as a
+single file, and it adds nothing to the production output. The entire UI lives
+inside a shadow DOM and does not mix with the page's CSS.
+
+What it shows:
+
+- **Errors:** browser-side JS errors, resource loading errors
+  (`img`/`script`/`link`), and the server's `console.error` / `console.warn`
+  output. On the server side `console` is wrapped so warnings do not get lost in
+  the terminal.
+- **Requests:** the method, path, status, duration and `X-JSkelet-Cache` value
+  of every HTML request. The same lines are printed to the terminal too.
+- **Web Vitals:** TTFB, FCP, LCP, CLS, INP, DCL, load, long task count and
+  blocking time.
+- **Prewarm:** the progress of the warming round; it can be triggered manually
+  from the panel, and individual paths can be retried.
+- **Process:** pid, Node version, uptime, RSS and heap usage.
+- **Version:** the installed JSkelet version compared against the `latest` tag
+  on npm. When a newer release exists, the **Server** tab grows an `update` chip
+  and a line that copies the upgrade command. The lookup runs once, 1.5 seconds
+  after boot, is cached for six hours in `os.tmpdir()` and is skipped silently
+  when the registry is unreachable. Set `JSKELET_VERSION_CHECK=0` to disable it.
+
+Warming requests (`user-agent: jskelet-prewarm`) are filtered out of both the
+terminal and the request list: hundreds of requests should not flood the view.
+Progress appears in the badge next to the bubble.
+
+### Why state is written to `os.tmpdir()`
+
+If request and error records lived in process memory, history would be erased on
+every restart and the overlay would come up empty. So the records are carried
+across restarts in a file.
+
+The file is **not written into the project tree**: every write triggered the
+watcher and restarted the server, which set up a self-feeding loop (restart →
+startup warning → write → restart). Instead, the file is written to
+`os.tmpdir()/jskelet-devtools-<hash of the project root>.json`; thanks to the
+hash, multiple JSkelet projects on the same machine do not overwrite each
+other's records.
+
+The write happens after 300 ms of silence rather than on every request, and its
+failure does not stop the dev flow. At most 50 requests and 50 errors are kept.
+
+The panel's open/closed state, its active tab and the browser error log are kept
+in tab memory (`sessionStorage`), so after a reload the panel comes back with
+the same tab.
+
+## Report page
+
+The bubble shows the current state; the report page produces a view of the whole
+site. The address:
+
+```
+http://localhost:3000/__jskelet/dev/report
+```
+
+(Or wherever `brand.devBasePath` points, if you changed it.)
+
+Its contents:
+
+- **Pages:** the Web Vitals measurements of every visited page, resource count
+  and total bytes (broken down by type), island status (how many are ready, and
+  their names), API calls made in the browser, and the size/duration/cache
+  status of the SSR output. Pages that were never visited but were warmed are
+  listed too: the SSR side is known, the client measurements stay empty.
+- **Server API calls:** outbound `fetch` calls made during SSR — URL, host,
+  method, status, duration, bytes. `globalThis.fetch` is only wrapped in
+  development; the production path is left untouched. Requests to our own server
+  (warming, health check) do not count as API calls.
+- **Build output:** the raw/gzip/brotli size of every asset in the manifest, and
+  chunk analysis from esbuild's metafile — the size of each output, which
+  sources it is made of, which chunks it imports. Sources are reduced to
+  readable groups (package name or parent folder), so the question "which
+  library accounts for 40 kB of this chunk" can be answered.
+- **HTML cache:** entry count and a dump (key, bytes, status, whether it is
+  stale, how many seconds until it expires, which encodings are stored).
+- **Prewarm:** the full result of the last round.
+- **Request and error logs.**
+
+Measurements live on the server, not in the browser tab; resetting is done from
+the server as well. Size calculations are not repeated unless the file changed.
+
+The report layer is only loaded in development and never enters the production
+output.
+
+## Dev endpoints
+
+Under `brand.devBasePath` (default `/__jskelet/dev`):
+
+| Path | Method | Job |
+| --- | --- | --- |
+| `/overlay.js` | GET | The overlay script |
+| `/logo.png` | GET | The overlay logo |
+| `/events` | GET | SSE: live reload and CSS hot-swap events |
+| `/stats` | GET | Current statistics (the overlay polls every 2 seconds) |
+| `/report` | GET | The report page (HTML) |
+| `/report.js` | GET | The report page's script |
+| `/report/data` | GET | The report's single data source (JSON) |
+| `/vitals` | POST | The measurement bundle sent by the overlay |
+| `/report/clear` | POST | Resets page measurements and server API records |
+| `/prewarm` | POST | Triggers warming manually. If the body has `paths`, only those paths; 409 if warming is already running. |
+| `/clear` | POST | Resets the request and error logs |
+
+All of these endpoints are mounted by `mountDevtools()` only when
+`NODE_ENV=development`; thanks to the dynamic import, nothing is loaded into the
+production process.
+
+## Dev gate — `DEV_TOKEN`
+
+To hide an environment that is not public yet: while `DEV_TOKEN` is set,
+**every** request without the token gets a 404.
+
+```bash
+DEV_TOKEN=a-long-random-string npm start
+```
+
+Access:
+
+```
+https://staging.example.com/?dev_token=a-long-random-string
+```
+
+Behavior:
+
+- **404, not 403.** A 403 confirms the environment exists; a 404 acts as if it
+  never did.
+- Once the token arrives as a query parameter, it is written to a cookie
+  (`Path=/`, `SameSite=Lax`, 14 days), so sharing the link is enough. The cookie
+  and parameter name is `brand.devTokenCookie` (default `dev_token`).
+- The **exact** paths in the `devGateBypass` list are open under all conditions.
+  Default: `/api/healthcheck`, `/robots.txt`, `/sitemap.xml`,
+  `/site.webmanifest`, `/favicon.ico`. If your health check lives at a different
+  path, remember to add it to this list, otherwise your orchestrator will see a
+  404.
+- Without `DEV_TOKEN` the middleware is entirely disabled and costs nothing in
+  production.
+- Since warming makes requests to its own server, it carries the token as a
+  cookie; without it every page gets a 404 and the cache never fills up
+  ([06-caching.md](./06-caching.md)).
+
+In the middleware chain the gate sits after `headers` and **before**
+`redirects`: an environment that is not public yet should not leak even its
+redirect rules.
+
+## Differences between development and production
+
+| Topic | Development | Production |
+| --- | --- | --- |
+| EJS template cache | Off | On |
+| Manifest reading | On every request | Once |
+| Image manifest | On every call | Once |
+| Broken route module | Warn + skip | Throw |
+| Devtools and report | Mounted | Never loaded |
+| `globalThis.fetch` | Wrapped (measurement) | Untouched |
+| Prewarm concurrency | 2 | 4 |
+| Prewarm delay | 3000 ms | 500 ms |
+| Missing icon warning | Emitted | Not emitted |
+| Precompress | Does not run in watch | Runs |
+| Image optimization | Does not run in watch | Runs |
+
+## What's next
+
+- Details of the build steps: [08-build.md](./08-build.md)
+- Going to production: [10-deployment.md](./10-deployment.md)
+- Reading and clearing the cache: [06-caching.md](./06-caching.md)