@flemo/devtools 0.3.0 → 0.4.0

package/README.md

@@ -1,69 +1,36 @@
 # @flemo/devtools
 
-Zero-config flight recorder for [flemo](https://flemo.dev) screen transitions.
+Zero-dependency flight recorder and optional visual panel for [flemo](https://flemo.dev) transitions. It observes existing `data-flemo-*` surfaces, `window.__flemoPlayerGaps`, leftover `flemo:*` keys, `MutationObserver`, `PerformanceObserver("longtask")`, and rAF. It imports neither `@flemo/core` nor `@flemo/react` and does not alter measured motion.
 
-It watches the DOM surfaces flemo already exposes — `data-flemo-*` attributes,
-`window.__flemoPlayerGaps`, the `flemo:*` storage registry — plus standard
-observers (`MutationObserver`, `PerformanceObserver("longtask")`, rAF), and
-condenses every navigation into one structured JSON report. The goal: a coding
-agent can diagnose a transition problem from the report alone, without
-round-tripping through the user ("which browser? was DevTools open? did you
-leave a toggle set?").
+## Quickstart
 
-Zero dependencies. No imports from `@flemo/core` or `@flemo/react`; attaching
-the recorder never changes the motion it measures.
+```ts
+import { attachFlightRecorder } from "@flemo/devtools";
+
+const recorder = attachFlightRecorder({ log: true });
+// ...navigate...
+const report = recorder.report(); // JSON-serializable FlemoReport
+recorder.detach();
+```
+
+Unless `installGlobal: false` or the name is already owned, the recorder installs `window.flemo`:
+
+```js
+copy(JSON.stringify(window.flemo.report(), null, 2));
+```
+
+Use `/playground?devtools=on` to enable the playground recorder. `flemo:devtools` persists in `sessionStorage`; `?devtools=off` disables it. `attachFlightRecorder()` is idempotent while attached and returns an inert handle during SSR.
 
 ## Production safety
 
-`@flemo/devtools` resolves to an inert entry when your bundler builds for
-production, so the ordinary import is the safe one:
+Normal imports use `development` and `production` export conditions. The production implementation is inert and records nothing:
 
 ```ts
 import { attachFlightRecorder } from "@flemo/devtools";
-
-// Development: the real recorder. Production: a no-op that records nothing
-// and whose implementation never enters the bundle.
 const { detach } = attachFlightRecorder({ log: true });
 ```
 
-This is done with the `development` / `production` export conditions rather
-than left to the caller, because the failure is silent: a normal import of a
-dev-time tool builds clean, warns about nothing, and ships to every visitor.
-It happened to this project — the recorder's strings were found in a
-production chunk of flemo.dev and had to be removed.
-
-Two things to know:
-
-- **Not every bundler sets those conditions.** Vite and Next do. If yours does
-  not, keep the module behind a dynamic import guarded by a build-time
-  constant (`process.env.NODE_ENV !== "production"`, Vite's
-  `import.meta.env.DEV`) so the branch — and the module behind it — is
-  eliminated. There is no automatic fallback for that case, and the shape of
-  this package is why: `@tanstack/react-query-devtools` gets one by importing
-  its implementation statically and swapping it on `process.env.NODE_ENV`, so
-  the bundler folds the constant and drops the now-unreferenced module. That
-  works because their implementation stays a separate module file. Ours cannot
-  — `dist/index.mjs` is self-contained on purpose, so it can be loaded
-  directly in a page — and measured with esbuild (which sets neither
-  condition), the same swap strips nothing: production and development bundles
-  came out byte-identical in size with the recorder present in both. The guard
-  is the answer there, not a trick inside the package.
-- **`@flemo/devtools/force` is the escape hatch.** It resolves to the real
-  tool whatever the build mode, for when you deliberately want the recorder in
-  a production build (a staging deploy, an e2e suite that must run against a
-  production build). Import it dynamically behind your own opt-in flag.
-
-## Keeping it out of your production bundle
-
-Install it as a **devDependency** — and know that this alone is not enough.
-`devDependencies` decides what gets INSTALLED (consumers of _your_ package do
-not receive it); it does not decide what gets BUNDLED. A plain top-level import
-of a package you call at runtime ships to every visitor regardless of which
-dependency field it sits in. We measured exactly that on the flemo docs site
-before fixing it.
-
-What actually removes it is a **dynamic import behind a build-time constant**,
-which bundlers replace before dead-code elimination:
+Vite and Next set these conditions. For bundlers that do not, guard a dynamic import with a build-time constant:
 
 ```ts
 // Vite
@@ -79,270 +46,80 @@ if (process.env.NODE_ENV !== "production") {
 }
 ```
 
-The package ships `"sideEffects": false` and has no import-time side effects,
-so nothing is pulled in by the import statement itself — but a binding you
-actually call cannot be shaken out. Verify with a production build: the string
-`present-pipeline pacing` (from the blind-spot list) must not appear in it.
+Install as a devDependency, but do not rely on dependency fields for bundle exclusion. A used top-level import can ship even though the package has `"sideEffects": false` and no import-time effects. `dist/index.mjs` is self-contained; an internal `process.env.NODE_ENV` substitution did not reduce measured esbuild bundles when no export condition was set. Use the guarded import and verify production output lacks `present-pipeline pacing`. See `apps/web/app/[lang]/playground/_hooks/useDevtoolsRecorder`.
 
-`apps/web/app/[lang]/playground/_hooks/useDevtoolsRecorder` in this repo is a
-working reference.
+`@flemo/devtools/force` always loads the recorder. Import it dynamically behind an explicit opt-in only for staging or production-build E2E.
 
-## Quickstart
+## Visual panel
 
 ```ts
-import { attachFlightRecorder } from "@flemo/devtools";
+import { attachDevtoolsPanel } from "@flemo/devtools";
+const panel = attachDevtoolsPanel();
+// panel.detach();
+```
 
-const recorder = attachFlightRecorder({ log: true });
+Consumers must opt in behind a development-only flag; flemo and its playground neither attach nor ship the panel automatically. The floating toggle shows flight count and an anomaly dot. The drawer shows flights, details, active overrides, and blind spots.
 
-// ...navigate around...
+Options are `recorder`, `initialOpen` (`false`), and `position` (`"bottom-right"` or `"bottom-left"`). Without `recorder`, the panel reuses this package's `window.flemo` or owns a new recorder. It is idempotent while mounted and inert without a DOM.
 
-const report = recorder.report(); // JSON-serializable FlemoReport
-recorder.detach();
-```
+The framework-free panel uses an open shadow root. Its fixed, zero-sized host has `data-flemo-devtools-panel`, no screen `data-flemo-*` attributes, and cannot join a flight. Drawer height persists as `flemo:devtools-panel-height` in `sessionStorage`.
 
-The recorder also installs `window.flemo` (unless something else already owns
-that name, or you pass `installGlobal: false`):
+The panel must not repaint during a flight:
 
-```js
-copy(JSON.stringify(window.flemo.report(), null, 2)); // DevTools console
-```
+- Refresh with a `setTimeout` chain about three times per second while open and once every two seconds while closed; never keep an rAF loop.
+- Skip refreshes and deferred actions while any screen has transitional `data-flemo-status`, then retry next tick.
+- Render only the toggle while closed.
+- Add no CSS transitions, keyframes, or live-dashboard behavior.
 
-In the flemo playground it is pre-wired: visit `/playground?devtools=on` (the
-toggle is stored in `sessionStorage` under `flemo:devtools`, so it survives
-navigation; `?devtools=off` disarms it).
+## Report schema v2
 
-`attachFlightRecorder()` is idempotent — while a recorder is attached, further
-calls return the same handle. In non-DOM environments (SSR) it returns an
-inert handle.
+Reports contain:
 
-## Visual panel
+- `generatedAt`, `version: "2"`, and `environment`: user agent and brands, engine, platform, touch count, DPR, screen and viewport sizes, visual viewport scale, idle `rafCadence`, reduced motion, emulation suspicion, and support for long tasks, element animations, and the player-gap mirror.
+- `overrides.active`: all `flemo:*` keys in both storages, unknown keys, keys cleared since attachment, and retired persisted keys marked inert. Since 2026-08-31, flemo reads no `flemo:*` engine key; `overrides.warnings` explains each residue key.
+- `flights[]`: identity, router, navigation kind, timestamps, duration, detected driver, participants, holds, frame and phase statistics, motion, images, player gaps, long tasks, landing checks, and stable anomaly strings.
+- Session `anomalies`, constant `blindSpots`, and constant `judgingProtocol`.
 
-The same data, on screen. `attachDevtoolsPanel()` mounts a floating `flemo`
-toggle (flight count, plus a red dot when any flight carries an anomaly) and a
-bottom drawer with the flight list, the per-flight detail, the active
-overrides, and the blind-spot list.
+`driver` is classified per flight as `compiled`, `player`, `mixed`, or `unknown`; never infer it from platform policy. `holds.releasedAtMs` is the last release relative to `t0`. Held work is intentionally absorbed, so frame gaps and long tasks are separated into held and released phases; held gaps do not raise anomalies.
 
-```ts
-import { attachDevtoolsPanel } from "@flemo/devtools";
+`motion` measures pose advancement independently of frame arrival. It records sampled and stalled frames, `longestStallMs` with an anomaly threshold of 48 ms, `pausedAfterRelease`, and `holdReassertedAtMs`, using animation clocks or inline poses without a style flush. Stationary closing frames are tails, not mid-flight stalls.
 
-const panel = attachDevtoolsPanel(); // reads window.flemo, or attaches its own
-// panel.detach();
-```
+`images` records loading at start, additions, completions, held images, and `completedUnheld`; count per image so a held loading image cannot cancel an unheld completion. `longTasks` covers visible motion and `holdLongTasks` covers absorbed work. Landing is audited two rAFs after `COMPLETED` for residual inline transforms, off-viewport rest, statuses stuck over 10 seconds, and orphaned holds. Skip orphan auditing when another flight is running.
 
-The panel is opt-in and mounted by the consumer: nothing in flemo attaches it
-for you, and the flemo playground deliberately arms the recorder only (the
-site should not ship a debug UI). Mount it behind your own dev-only flag.
-
-Options: `recorder` (a handle from `attachFlightRecorder`; defaults to this
-package's `window.flemo`, otherwise the panel attaches — and owns — one),
-`initialOpen` (default false), `position` (`"bottom-right"` default, or
-`"bottom-left"`). Zero dependencies, no framework: vanilla DOM inside an open
-shadow root, so no consumer CSS reaches in and none of the panel's reaches
-out. The host is `position: fixed`, zero-sized, marked
-`data-flemo-devtools-panel`, and carries no `data-flemo-*` screen attributes —
-the recorder never sees the panel as a flight participant. Drag the drawer's
-top edge to resize; the height persists in `sessionStorage` under
-`flemo:devtools-panel-height`.
-
-**It never repaints during a flight.** That is the design constraint, not a
-nicety: this project once spent weeks chasing stutter that turned out to be
-_DevTools being open_, and a measurement surface
-that repaints mid-transition reproduces that artifact and then reports it as a
-finding. So the panel
-
-- refreshes on a `setTimeout` chain (~3×/s open, once per 2s closed) — never a
-  persistent `requestAnimationFrame` loop competing with the motion,
-- **skips any refresh while a screen carries a transitional
-  `data-flemo-status`** and retries on the next tick — deferred user actions
-  (open/close, row selection) included,
-- renders only the toggle button while closed,
-- ships no CSS transitions and no keyframes at all.
-
-Do not turn it into a live-updating dashboard.
-
-## Report schema (version "2")
-
-```jsonc
-{
-  "generatedAt": "2026-08-17T09:00:00.000Z",
-  "version": "2",
-  "environment": {
-    "userAgent": "…",
-    "uaBrands": [{ "brand": "Chromium", "version": "126" }],
-    "engine": "blink", // blink | webkit | gecko | unknown
-    "platform": "MacIntel",
-    "maxTouchPoints": 0,
-    "devicePixelRatio": 2,
-    "screen": { "width": 1728, "height": 1117 },
-    "viewport": { "width": 1280, "height": 720 },
-    "visualViewportScale": 1,
-    "rafCadence": { "medianGapMs": 16.67, "sampleCount": 20 }, // idle sample at attach
-    "reducedMotion": false,
-    "emulationSuspected": false, // DevTools device-toolbar signature
-    "observation": { "longTasks": true, "elementAnimations": true, "playerGapMirror": false }
-  },
-  "overrides": {
-    // Every flemo:* storage key currently set (both storages), including
-    // unknown keys and keys present at attach but cleared since (marked).
-    // Retired keys still persisted on the device are listed too, marked
-    // "(retired — the library no longer reads this)", so residue is ruled out
-    // rather than chased.
-    "active": { "flemo:layers": "resident" },
-    // Read these FIRST. A non-empty warnings list means the session does not
-    // run stock behavior.
-    "warnings": ["flemo:layers=resident — opt-in diagnostic active (…)"]
-  },
-  "flights": [
-    {
-      "id": "flight-1",
-      "routerId": "…", // when the screen stamps data-flemo-router
-      "kind": "PUSH", // PUSH | POP | REPLACE
-      "t0": { "ms": 1234.5, "iso": "…" }, // performance.now + wall clock
-      "t1": { "ms": 1834.5, "iso": "…" },
-      "durationMs": 600,
-      // compiled | player | mixed | unknown — detected per flight from the
-      // DOM signature (inline animation suppression + advancing inline pose
-      // = player; a running flemo-* CSSAnimation = compiled). Never assume a
-      // platform always routes one tier; routing policies evolve.
-      "driver": "compiled",
-      "participants": { "screens": 2, "bars": 0, "decorators": 1, "parts": 0 },
-      // data-flemo-anim-hold: releasedAtMs = when the LAST hold released,
-      // relative to t0. The engine absorbs heavy commits INTO the hold (the
-      // screen is posed, not moving), so everything below is segmented on
-      // this boundary.
-      "holds": { "kind": "park-under", "releasedAtMs": 120 },
-      "frameSamples": {
-        "count": 36,
-        "medianGapMs": 16.7,
-        "maxGapMs": 17.2,
-        "longGaps": [],
-        // held-phase gaps are absorbed by design — no anomaly ever fires on them;
-        "held": { "count": 7, "medianGapMs": 18.1, "maxGapMs": 45.0, "over30Count": 1 },
-        // released-phase gaps are visible motion — the anomaly rules key on these.
-        "released": { "count": 29, "medianGapMs": 16.7, "maxGapMs": 17.2, "over30Count": 0 }
-      },
-      // Did it MOVE — a different question from "did frames arrive". A
-      // compiled flight is read off its own animation clock, a player flight
-      // off the inline pose it writes; neither forces a style flush.
-      "motion": {
-        "sampledFrames": 29,
-        "stalledFrames": 0, // released frames where neither clock nor pose moved
-        "longestStallMs": 0, // >= 48ms raises an anomaly
-        "pausedAfterRelease": false, // playState went "paused" mid-motion
-        "holdReassertedAtMs": null // a hold went back ON after releasing
-      },
-      // Images inside the participants. One still-loading <img> completing
-      // mid-flight costs one skipped present (glass-measured 1:1), which is
-      // why the engine holds them; an unheld completion is that regression.
-      // completedUnheld is the number that matters, counted PER IMAGE: a
-      // held-but-still-loading image must not cancel out an unheld completed
-      // one. addedDuringFlight covers images a data commit inserts mid-
-      // navigation, which is the case core's image hold also watches for.
-      "images": {
-        "loadingAtStart": 12,
-        "addedDuringFlight": 0,
-        "completedDuringFlight": 0,
-        "heldDuringFlight": 12,
-        "completedUnheld": 0
-      },
-      "playerGaps": { "maxMs": 42.3, "over30Count": 1 }, // only if the player mirror grew
-      "longTasks": [{ "startMs": 1200.0, "durationMs": 180.0 }], // intersecting visible motion
-      "holdLongTasks": [], // fully absorbed by the hold — engine working as designed
-      "landing": {
-        // Audited 2 rAF after COMPLETED:
-        "residualInlineTransforms": [], // inline transform/opacity leftovers
-        "offViewportAtRest": false, // the blank-viewport (PR #259) signature
-        "stuckStatuses": [], // transitional statuses >10s old
-        // Hold markers still on the page at rest. Skipped (left empty) when
-        // another flight is already running: two frames after a landing, a
-        // fast back-to-back navigation legitimately owns holds of its own.
-        "orphanedHolds": []
-      },
-      "anomalies": ["long task 180ms overlapped flight start (opening-swallow risk)"]
-    }
-  ],
-  "anomalies": [], // session-level: active pins, emulation, stuck flights
-  "blindSpots": ["…"], // constant — see below
-  "judgingProtocol": ["…"] // constant — the preconditions a verdict needs
-}
-```
+## Detected defects
+
+Stable anomaly signatures include:
+
+- `hold re-asserted …ms into the flight`: a stale paused hold was rewritten during motion.
+- `motion stalled …ms mid-flight`: motion froze or froze then leapt despite continuing rAF.
+- `playState=paused`: posed motion stopped rather than suffering frame starvation.
+- `image(s) finished loading mid-flight without a hold`: decode rastered on the moving layer.
+- `hold markers left on the page at rest`: hidden content has no owner to reveal it.
+- `screen resting at from-pose while COMPLETED+active`: blank-viewport landing.
+- `long task …ms overlapped the visible-motion start`: swallowed opening.
+- `transitional status stuck >10s`: the navigation queue remains locked.
+- `active force pin flemo:motion-driver-force=…`: diagnostic residue pins a driver.
+
+These defects have occurred with clean frame timing.
+
+## Judging protocol and blind spots
+
+A valid verdict requires DevTools closed, no capture, real input, emulation off, and known display, refresh rate, HiDPI scaling, and Low Power Mode state. The page cannot verify these, so every report includes `judgingProtocol`. Open DevTools caused 2026-08 residual stutter; capture can suppress symptoms; synthetic dispatch bypasses `pointerdown` gesture behavior.
+
+In-page tools cannot observe macOS Chrome present-pipeline pacing on 120 Hz ProMotion (Chromium issues 40062488/345275139), display hardware, compositor-internal present skips, or the post-scale DevTools emulation surface. These remain in `blindSpots`. If a correctly judged report is clean but jank is visible, investigate those layers instead of adding in-page instrumentation.
+
+## Hand a report to an agent
+
+1. Reproduce once with the recorder attached.
+2. Run `copy(JSON.stringify(window.flemo.report(), null, 2))`.
+3. Paste the JSON into the issue or conversation.
 
-## What it is built to catch
-
-Every rule below exists because the matching defect actually shipped, was
-lived with, and cost days. They share one property: **frame timing was clean
-through all of them.** A recorder that only measured gaps would have called
-each of these sessions healthy.
-
-| Signature in `anomalies`                              | The defect it guards against                                                                                              |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `hold re-asserted …ms into the flight`                | An interleaved commit writing the stale paused hold attribute over a running flight — froze motion ~250ms, intermittently |
-| `motion stalled …ms mid-flight`                       | Any freeze / freeze-then-leap: the pose stopped advancing while rAF kept ticking                                          |
-| `playState=paused`                                    | The flight was posed and then stopped, rather than starved of frames                                                      |
-| `image(s) finished loading mid-flight without a hold` | Warm-side image decode rastering on the sliding layer — one skipped present per decode                                    |
-| `hold markers left on the page at rest`               | Orphaned image/arrival holds: content hidden with no owner left to reveal it (the permanently-blank-avatar class)         |
-| `screen resting at from-pose while COMPLETED+active`  | The blank-viewport landing (PR #259)                                                                                      |
-| `long task …ms overlapped the visible-motion start`   | The swallowed opening (씹힘)                                                                                              |
-| `transitional status stuck >10s`                      | A locked navigation queue — every later navigation is silently ignored                                                    |
-| `active force pin flemo:motion-driver-force=…`        | A/B residue pinning the whole session to one driver (this one burned a multi-day investigation)                           |
-
-## The judging protocol
-
-Every report also carries `judgingProtocol`. It is not derived — the page
-cannot check it — so it is stated instead:
-
-- **DevTools closed.** The 2026-08 campaign's entire residual "stutter" was
-  the open inspector, verified bidirectionally on the reporting machine. A
-  clean report from a DevTools-open session proves nothing.
-- **No screen capture running.** A capture client forces the compositor to a
-  steady cadence and _suppresses_ the symptom.
-- **Real input.** Synthetic dispatch never fires `pointerdown`, so it bypasses
-  the gesture machinery a real navigation goes through.
-- **Known viewing configuration.** Emulation off; which display, refresh rate,
-  HiDPI scaling, Low Power Mode.
-
-## Blind spots
-
-Every report ends with a constant `blindSpots` list: the layers **no in-page
-instrument can see**, each of which once consumed a real investigation:
-
-- macOS Chrome present-pipeline pacing (Chromium issues 40062488/345275139) —
-  frames judder on 120Hz ProMotion while every in-page metric reads clean;
-  proven with a no-script pure-CSS control page.
-- Display-hardware effects (local dimming, backlight modulation).
-- Compositor-internal present skips invisible to rAF.
-- DevTools device emulation composites to a rescaled surface — instruments
-  read the pre-scale surface, the eye watches the post-scale one.
-
-If the report is clean and the user still sees jank, the cause lives in one of
-these. Do not chase them with in-page tooling.
-
-## Handing a report to an agent
-
-1. Reproduce the problem once with the recorder attached (playground:
-   `/playground?devtools=on`).
-2. `copy(JSON.stringify(window.flemo.report(), null, 2))` in the console.
-3. Paste the JSON into the issue/conversation.
-
-Reading order for the agent: `overrides.warnings` (is this session even
-stock?) → `environment.emulationSuspected` + `rafCadence` (is the observation
-trustworthy? what display cadence?) → per-flight `driver` + `anomalies`
-(which tier ran, what went wrong, when) → `blindSpots` (what not to chase).
-All anomaly strings are stable, grep-friendly signatures.
+Read `overrides.warnings`, `environment.emulationSuspected`, `rafCadence`, each flight's `driver` and `anomalies`, then `blindSpots`.
 
 ## API
 
-- `attachFlightRecorder(options?)` → `{ report(), detach() }` — options:
-  `maxFlights` (default 50), `log` (default false), `installGlobal`
-  (default true).
-- `attachDevtoolsPanel(options?)` → `{ detach() }` — options: `recorder`,
-  `initialOpen` (default false), `position` (default `"bottom-right"`).
-  Idempotent while mounted; inert without a DOM.
-- Pure helpers (unit-testable, no DOM): `deriveFlightAnomalies`,
-  `deriveReportAnomalies`, `deriveOverrideWarnings`, `classifyDriver`,
-  `computeFrameStats`, `computePlayerGapStats`, `parseTranslateX`,
-  `kindFromStatus`.
-- Constants/registries: `BLIND_SPOTS`, `FLAG_REGISTRY`, `LONG_GAP_MS`,
-  `STUCK_STATUS_MS`, `REPORT_SCHEMA_VERSION`.
-- Environment probes: `captureEnvironment`, `detectEngine`,
-  `isEmulationSuspected`, `sampleRafCadence`.
+- `attachFlightRecorder(options?)` returns `{ report(), detach() }`; options: `maxFlights` (50), `log` (`false`), `installGlobal` (`true`).
+- `attachDevtoolsPanel(options?)` returns `{ detach() }`; options: `recorder`, `initialOpen` (`false`), `position` (`"bottom-right"`).
+- Pure helpers: `deriveFlightAnomalies`, `deriveReportAnomalies`, `deriveOverrideWarnings`, `classifyDriver`, `computeFrameStats`, `computePlayerGapStats`, `parseTranslateX`, `kindFromStatus`.
+- Constants and registries: `BLIND_SPOTS`, `FLAG_REGISTRY`, `LONG_GAP_MS`, `STUCK_STATUS_MS`, `REPORT_SCHEMA_VERSION`.
+- Environment probes: `captureEnvironment`, `detectEngine`, `isEmulationSuspected`, `sampleRafCadence`.