@flemo/devtools 0.3.0 → 0.5.0

package/README.md

@@ -1,69 +1,41 @@
 # @flemo/devtools
 
-Zero-config flight recorder for [flemo](https://flemo.dev) screen transitions.
+Zero-dependency flight recorder, on-device readout and visual panel for [flemo](https://flemo.dev) transitions. It observes existing `data-flemo-*` surfaces, leftover `flemo:*` keys, CSS animation events, pointer events, `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?").
+Everything in it is one probe module per question — pacing, motion, images, shared elements, one-frame events, landing residue — behind a small orchestrator. Adding a measurement means adding a probe.
 
-Zero dependencies. No imports from `@flemo/core` or `@flemo/react`; attaching
-the recorder never changes the motion it measures.
+## Quickstart
+
+```ts
+import { attachFlightRecorder } from "@flemo/devtools";
+
+const recorder = attachFlightRecorder({ log: true });
+// ...navigate...
+const report = recorder.report(); // JSON-serializable FlemoReport
+recorder.mark("A"); // label the flights that follow, for a comparison
+recorder.detach();
+```
+
+Read `report.verdict` first. It is the recorder's own reading of the session in plain sentences, and it refuses to summarise data from a session that was not allowed to produce evidence.
+
+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 and its surfaces. `flemo:devtools` persists in `sessionStorage`; `?devtools=off` disables it. Armed, the playground imports `@flemo/devtools/force`, and that is the part worth copying: a plain import of this package resolves to the inert production entry, so an instrument wired the ordinary way exists only in the builds whose numbers the judging protocol below says do not count. `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 +51,113 @@ 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
+## On-device readout
 
 ```ts
-import { attachFlightRecorder } from "@flemo/devtools";
-
-const recorder = attachFlightRecorder({ log: true });
-
-// ...navigate around...
-
-const report = recorder.report(); // JSON-serializable FlemoReport
-recorder.detach();
+import { attachDevtoolsHud } from "@flemo/devtools";
+const hud = attachDevtoolsHud({ position: "top" });
+// hud.detach();
 ```
 
-The recorder also installs `window.flemo` (unless something else already owns
-that name, or you pass `installGlobal: false`):
+A phone has no console. The readout is one monospaced line, high contrast and readable in a photograph of the device:
 
-```js
-copy(JSON.stringify(window.flemo.report(), null, 2)); // DevTools console
+```
+POP 412ms  gap 33.4  drop 1  !2
 ```
 
-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).
+Tap it for the detail block (frames, motion, holds, shared elements, what drove the navigation, and the flight's anomalies); long-press to cycle the comparison bucket. Options are `recorder`, `position` (`"top"` or `"bottom"`), `initialExpanded` (`false`) and `buckets` (`["A", "B"]`).
 
-`attachFlightRecorder()` is idempotent — while a recorder is attached, further
-calls return the same handle. In non-DOM environments (SSR) it returns an
-inert handle.
+It obeys the same rules the panel does: it repaints only between flights, its stylesheet carries no transition and no keyframe, and its host is a zero-sized fixed element that cannot join a flight.
 
 ## Visual panel
 
-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.
-
 ```ts
 import { attachDevtoolsPanel } from "@flemo/devtools";
-
-const panel = attachDevtoolsPanel(); // reads window.flemo, or attaches its own
+const panel = attachDevtoolsPanel();
 // panel.detach();
 ```
 
-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
-}
-```
+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.
+
+Options are `recorder`, `initialOpen` (`false`), `position` (`"bottom-right"` or `"bottom-left"`) and `buckets` (`["A", "B"]`). 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. The header leads with the verdict and every failed precondition, and carries an A/B button that arms the comparison buckets.
+
+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 panel must not repaint during a flight:
+
+- 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.
+
+## Report schema v3
+
+Reports contain:
+
+- `generatedAt`, `version: "3"`, and `verdict`: the session read back in sentences, most important first.
+- `preconditions[]`: the observable half of the judging protocol, each `ok`, `violated` or `unknown` with the reasoning and its numbers. The traps a page cannot see stay `unknown` forever rather than being guessed at.
+- `environment`: user agent and brands, engine, platform, touch count, DPR, hardware concurrency, screen and viewport sizes, visual viewport scale, idle `rafCadence`, reduced motion, development-server globals, emulation suspicion, and what the recorder could observe (long tasks, element animations, and whether its own animation channel ever fired).
+- `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, bucket, navigation kind, timestamps, duration, detected driver, participants, holds, frame and phase statistics, motion, images, shared elements, tripwire hits, what drove it, long tasks, landing checks, and stable anomaly strings.
+- `comparison[]`: per-bucket medians, worst gaps, drops, anomalies and stalls; empty until `mark()` arms a label.
+- `previousSession`: flights carried across the last full page load, kept apart from the live ones.
+- Session `anomalies`, constant `blindSpots`, and constant `judgingProtocol`.
+
+`driver` is classified per flight as `compiled`, `inline`, `mixed`, or `unknown`; never infer it from platform policy. flemo compiles every animation, so `inline` means something else is writing frames onto a participant. `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.
+
+`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.
+
+`morphs` answers the question a shared element cannot answer for itself. A morph that does not pair produces no error, no attribute and no animation, so the runtime writes the pairing key onto every registered morph (`data-flemo-morph-id`) and this section groups the ends: `pairable` had everything they needed, `flew` were stamped with a flight role, and `skipped` is the difference. It also reports duplicate keys inside one screen (a consumer mistake, not a runtime one) and the residue a landing left behind: roles, stand-ins, ghosts, elements stranded in a flight layer, and keyframe rules never dropped.
+
+`tripwires` are events the browser REPORTED rather than samples the recorder took: a cancelled flemo animation, an `animationend` carrying `elapsedTime` 0, a hold re-asserted after its release, a ghost cut inside a frame. A sampler cannot see a defect that lasts one frame; a listener cannot miss it.
+
+`input` records the trusted and synthetic pointer events around the flight and the pointer types among them. A session driven only by script never fires the gesture machinery, and a session driven only by a mouse never exercises the touch path.
+
+`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.
+
+## 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.
+- `shared element(s) did not fly`: both ends were registered on two screens and neither took a flight role.
+- `morph element(s) still carry a flight role at rest`: a stranded participant that poisons the next pairing.
+- `tripwire zero-length-animation-end`: something landed on an animation that never ran.
+- `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, a production build, an idle machine, and known display, refresh rate, HiDPI scaling and Low Power Mode state. The ones a page CAN check are checked and appear in `preconditions` — emulation, display cadence, foreground, machine contention, build mode, real and touch input, reduced motion. The rest stay `unknown` there and are stated in `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 `verdict`, then `preconditions`, then each flight's `anomalies`, then `blindSpots`. A number from a session with a violated precondition is not evidence.
 
 ## 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(), mark(), detach() }`; options: `maxFlights` (50), `log` (`false`), `installGlobal` (`true`), `persist` (`true`).
+- `attachDevtoolsHud(options?)` returns `{ detach() }`; options: `recorder`, `position` (`"top"`), `initialExpanded` (`false`), `buckets`.
+- `attachDevtoolsPanel(options?)` returns `{ detach() }`; options: `recorder`, `initialOpen` (`false`), `position` (`"bottom-right"`), `buckets`.
+- Pure helpers: `deriveFlightAnomalies`, `deriveReportAnomalies`, `deriveOverrideWarnings`, `derivePreconditions`, `deriveVerdict`, `summariseBuckets`, `classifyDriver`, `computeFrameStats`, `parseTranslateX`, `kindFromStatus`.
+- Constants and registries: `BLIND_SPOTS`, `JUDGING_PROTOCOL`, `FLAG_REGISTRY`, `LONG_GAP_MS`, `STALL_MS`, `STUCK_STATUS_MS`, `REPORT_SCHEMA_VERSION`.
+- Environment probes: `captureEnvironment`, `detectEngine`, `developmentHints`, `isEmulationSuspected`, `sampleRafCadence`.
+- Trace storage: `loadTrace`, `saveTrace`, `clearTrace`, `TRACE_KEY`.

package/dist/__tests__/hud.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/imageProbe.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/morphProbe.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/persistence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/preconditions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/recorder.session.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tripwires.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/verdict.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/anomalies.d.ts

@@ -1,4 +1,4 @@
-import { FlightDriver, FrameSampleStats, ImageActivity, LandingAudit, LongTaskSpan, MotionProgress, PlayerGapStats } from './types';
+import { FlightDriver, FrameSampleStats, ImageActivity, LandingAudit, LongTaskSpan, MorphActivity, MotionProgress, TripwireHit } from './types';
 /** A gap at/over this is at least one missed 60Hz frame (mirrors core). */
 export declare const LONG_GAP_MS = 30;
 /** A transitional status older than this is a stuck flight. */
@@ -19,7 +19,6 @@ export interface FlightAnomalyInput {
     t1Ms: number;
     driver: FlightDriver;
     frameSamples: FrameSampleStats;
-    playerGaps: PlayerGapStats | null;
     /** Long tasks intersecting the RELEASED (visible-motion) phase. */
     longTasks: LongTaskSpan[];
     /** Long tasks fully absorbed by the hold phase (informational only). */
@@ -29,6 +28,8 @@ export interface FlightAnomalyInput {
     landing: LandingAudit;
     motion: MotionProgress;
     images: ImageActivity;
+    morphs: MorphActivity;
+    tripwires: TripwireHit[];
 }
 export declare const deriveFlightAnomalies: (input: FlightAnomalyInput) => string[];
 export interface ReportAnomalyInput {

package/dist/buckets.d.ts

@@ -0,0 +1,2 @@
+import { BucketSummary, FlightRecord } from './types';
+export declare const summariseBuckets: (flights: readonly FlightRecord[]) => BucketSummary[];

package/dist/domProtocol.d.ts

@@ -10,6 +10,28 @@ export declare const DECORATOR_ATTR = "data-flemo-decorator";
 export declare const BAR_ATTR = "data-flemo-bar";
 export declare const BAR_STATUS_ATTR = "data-flemo-bar-status";
 export declare const BAR_RIDING_ATTR = "data-flemo-bar-riding";
+/** A registered morph. The value is the role while it flies: "enter"/"exit". */
+export declare const MORPH_ATTR = "data-flemo-morph";
+/** The pairing key (the binding's `layoutId`), so the two ends can be grouped. */
+export declare const MORPH_ID_ATTR = "data-flemo-morph-id";
+/** The registered morph-transition name, absent/empty meaning the default preset. */
+export declare const MORPH_NAME_ATTR = "data-flemo-morph-name";
+/** The per-Router flight layer a staged morph is lifted into. */
+export declare const MORPH_LAYER_ATTR = "data-flemo-morph-layer";
+/** The copy left in the layout holding the flying element's place. */
+export declare const MORPH_STAND_IN_ATTR = "data-flemo-morph-stand-in";
+/** The copy of the replaced element carried inside the flight. */
+export declare const MORPH_GHOST_ATTR = "data-flemo-morph-ghost";
+/** A screen being driven as a camera by a morph, stamped with the flight id. */
+export declare const MORPH_CAMERA_ATTR = "data-flemo-morph-camera";
+/** The `<style>` element a morph writes its per-flight keyframes into. */
+export declare const MORPH_SHEET_ATTR = "data-flemo-morph-sheet";
+/** The values MORPH_ATTR takes while an element is in the air. */
+export declare const MORPH_ROLES: readonly ["enter", "exit"];
+/** Every flemo keyframe name starts with this. */
+export declare const FLEMO_ANIMATION_PREFIX = "flemo-";
+/** A morph's per-flight keyframes are namespaced again under this. */
+export declare const MORPH_ANIMATION_PREFIX = "flemo-morph-";
 /** This package's own marker — core reserves the name but never writes it. */
 export declare const DEVTOOLS_PANEL_ATTR = "data-flemo-devtools-panel";
 /** The statuses during which a flight is moving. */

package/dist/environment.d.ts

@@ -25,7 +25,10 @@ export declare const sampleRafCadence: (frames?: number) => Promise<{
     medianGapMs: number | null;
     sampleCount: number;
 }>;
+export declare const developmentHints: () => string[];
 export declare const captureEnvironment: (rafCadence: {
     medianGapMs: number | null;
     sampleCount: number;
-}) => EnvironmentFingerprint;
+}, 
+/** Whether the tripwires have seen a flemo animation event (see types). */
+animationEvents?: boolean) => EnvironmentFingerprint;

package/dist/flight.d.ts

@@ -0,0 +1,40 @@
+import { FrameProbeState } from './frameProbe';
+import { ImageProbeState } from './imageProbe';
+import { MorphProbeState } from './morphProbe';
+import { FlightKind, FlightRecord, TripwireHit } from './types';
+/**
+ * The mutable state of one flight while it is in the air.
+ *
+ * Composed of one field per probe rather than a flat bag: every probe owns its
+ * own state shape, the orchestrator owns only the lifecycle fields, and adding
+ * a measurement means adding a field and a module beside it rather than
+ * growing a closure nobody can hold in their head.
+ */
+export interface ActiveFlight {
+    id: string;
+    kind: FlightKind;
+    routerId?: string;
+    /** The comparison bucket armed when this flight opened, if any. */
+    bucket: string | null;
+    t0Ms: number;
+    t0Iso: string;
+    elements: Element[];
+    participants: FlightRecord["participants"];
+    holdKind: string | null;
+    holdReleasedAtMs: number | null;
+    /**
+     * When the first flemo keyframe actually STARTED, relative to t0.
+     *
+     * The status flip and the first moving frame are not the same moment: a
+     * commit, a style recalculation and a present sit between them, and on a
+     * phone that gap has measured 90-165ms while every other number stayed
+     * clean. It is reported rather than judged, because the gap is React's and
+     * the browser's, not the transition's.
+     */
+    firstAnimationAtMs: number | null;
+    frames: FrameProbeState;
+    images: ImageProbeState;
+    morphs: MorphProbeState;
+    tripwires: TripwireHit[];
+    rafId: number | null;
+}