@flemo/devtools 0.4.0 → 0.6.0

package/dist/reactNoop.d.ts

@@ -0,0 +1,4 @@
+import { FlemoDevtoolsProps } from './react';
+export type { FlemoDevtoolsProps } from './react';
+export declare function FlemoDevtools(_props?: FlemoDevtoolsProps): null;
+export default FlemoDevtools;

package/dist/reactNoop.mjs

@@ -0,0 +1,6 @@
+//#region src/reactNoop.ts
+function e(e = {}) {
+	return null;
+}
+//#endregion
+export { e as FlemoDevtools, e as default };

package/dist/recorder.d.ts

@@ -1,11 +1,13 @@
+import { clearTrace } from './persistence';
 import { FlemoReport, FlightRecord, FlightRecorderHandle, FlightRecorderOptions } from './types';
-export declare const REPORT_SCHEMA_VERSION = "2";
+export declare const REPORT_SCHEMA_VERSION = "3";
 /** The API installed at window.flemo (guarded — see attachFlightRecorder). */
 export interface FlemoGlobal {
     /** Marker distinguishing this recorder's global from foreign occupants. */
     __flemoDevtools: true;
     report: () => FlemoReport;
     flights: () => FlightRecord[];
+    mark: (bucket: string | null) => string | null;
     detach: () => void;
 }
 /**
@@ -15,3 +17,4 @@ export interface FlemoGlobal {
  * the schema constants.
  */
 export declare const attachFlightRecorder: (options?: FlightRecorderOptions) => FlightRecorderHandle;
+export { clearTrace };

package/dist/sampling.d.ts

@@ -1,4 +1,5 @@
-import { FlightDriver, FlightKind, FramePhaseStats, FrameSampleStats, PlayerGapStats } from './types';
+import { DriverEvidence } from './frameProbe';
+import { FlightDriver, FlightKind, FramePhaseStats, FrameSampleStats } from './types';
 export declare const computePhaseStats: (gaps: readonly number[]) => FramePhaseStats;
 /**
  * Combined frame stats: `heldGaps` are frames sampled while any transitional
@@ -7,16 +8,13 @@ export declare const computePhaseStats: (gaps: readonly number[]) => FramePhaseS
  * ordered gap list is their concatenation.
  */
 export declare const computeFrameStats: (heldGaps: readonly number[], releasedGaps?: readonly number[]) => FrameSampleStats;
-export declare const computePlayerGapStats: (gaps: readonly number[]) => PlayerGapStats | null;
-/** Driver evidence gathered by the rAF sampler during a flight. */
-export interface DriverEvidence {
-    /** A running CSSAnimation named flemo-* was observed on a participant. */
-    compiledAnimation: boolean;
-    /** A participant carried inline `animation` suppression (player stake). */
-    playerSuppression: boolean;
-    /** Inline transform/opacity advanced between sampled frames. */
-    playerAdvance: boolean;
-}
+/**
+ * Which tier drove the flight.
+ *
+ * The library compiles every animation, so `inline` never comes from flemo:
+ * it means SOMETHING ELSE was writing frames onto a participant, which is
+ * worth knowing and is why the signature is still watched for.
+ */
 export declare const classifyDriver: (evidence: DriverEvidence) => FlightDriver;
 export declare const kindFromStatus: (status: string) => FlightKind | null;
 /**

package/dist/surface.d.ts

@@ -0,0 +1,30 @@
+import { FlightRecorderHandle } from './types';
+/** Any screen mid-transition: while this matches, every surface stays frozen. */
+export declare const IN_FLIGHT_SELECTOR: string;
+export declare const flightInProgress: () => boolean;
+export interface ShadowHost {
+    host: HTMLElement;
+    root: HTMLElement;
+}
+/**
+ * A fixed, zero-sized host with an open shadow root.
+ *
+ * Zero-sized so it participates in no layout, and its fixed children position
+ * against the viewport instead. It carries the devtools marker and NO
+ * `data-flemo-*` screen attribute, so the recorder can never mistake its own
+ * surface for a flight participant.
+ */
+export declare const createShadowHost: (css: string) => ShadowHost;
+/**
+ * Which recorder a surface reads.
+ *
+ * Three cases, and the ownership question is the point of each: a recorder
+ * handed in is the caller's and is never detached here; this package's own
+ * `window.flemo` (usually an app's own recorder) is read but never taken down;
+ * anything else means the surface attaches one and owns it. Getting this wrong
+ * detaches the app's recorder when a panel closes, which loses the trace.
+ */
+export declare const resolveRecorder: (provided?: FlightRecorderHandle) => {
+    recorder: FlightRecorderHandle;
+    ownsRecorder: boolean;
+};

package/dist/tripwires.d.ts

@@ -0,0 +1,37 @@
+import { InputEvidence, TripwireHit } from './types';
+/** How long before a flight opens an input event still counts as its cause. */
+export declare const INPUT_WINDOW_MS = 2000;
+export interface TripwireHandle {
+    detach: () => void;
+    /** True once any flemo-named CSS animation event has been observed. */
+    sawAnimationEvent: () => boolean;
+    /** Input observed in [from - INPUT_WINDOW_MS, to]. */
+    inputBetween: (fromMs: number, toMs: number) => InputEvidence;
+}
+export interface TripwireOptions {
+    /**
+     * Called with each hit, on the frame it happened. `atMs` is
+     * `performance.now()`, absolute — the recorder makes it flight-relative,
+     * because a hit can land while no flight is open and must not be silently
+     * attributed to the previous one.
+     */
+    onHit: (hit: {
+        kind: TripwireHit["kind"];
+        detail: string;
+        atMs: number;
+    }) => void;
+    /** Called with the moment the first flemo animation of a flight started. */
+    onAnimationStart: (atMs: number) => void;
+}
+/**
+ * Wire the tripwires onto the document.
+ *
+ * Returns an inert handle where there is no document to wire onto, so a caller
+ * never has to branch on the environment.
+ */
+export declare const attachTripwires: (options: TripwireOptions) => TripwireHandle;
+export declare const relativeHit: (hit: {
+    kind: TripwireHit["kind"];
+    detail: string;
+    atMs: number;
+}, t0Ms: number) => TripwireHit;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /** How a flight's motion was driven, judged from DOM signatures alone. */
-export type FlightDriver = "player" | "compiled" | "mixed" | "unknown";
+export type FlightDriver = "inline" | "compiled" | "mixed" | "unknown";
 /** Navigation kind, from the transitional `data-flemo-status` value. */
 export type FlightKind = "PUSH" | "POP" | "REPLACE";
 /** A single moment on both clocks: monotonic performance.now + wall clock. */
@@ -53,11 +53,6 @@ export interface FrameSampleStats {
     /** Frames after every hold released — the phase the eye watches. */
     released: FramePhaseStats;
 }
-/** Stats over the transition player's own gap mirror (__flemoPlayerGaps). */
-export interface PlayerGapStats {
-    maxMs: number;
-    over30Count: number;
-}
 /** A PerformanceObserver("longtask") entry overlapping the flight window. */
 export interface LongTaskSpan {
     startMs: number;
@@ -71,8 +66,8 @@ export interface LongTaskSpan {
  * running flight paused the animation for ~250ms while rAF kept ticking at a
  * perfect 16.7ms — every timing metric clean, the screen frozen. The decisive
  * instrument was a pose encoder, so the recorder carries one: for a compiled
- * flight it reads the animation's own clock, for a player flight the inline
- * pose it writes. Neither forces a style flush.
+ * flight it reads the animation's own clock, for an inline-driven one the pose
+ * being written. Neither forces a style flush.
  */
 export interface MotionProgress {
     /** Frames sampled during the RELEASED (visible-motion) phase. */
@@ -94,6 +89,16 @@ export interface MotionProgress {
      * flights, always exactly 3 frames).
      */
     tailFrames: number;
+    /**
+     * When the first flemo keyframe actually STARTED, relative to t0 — reported
+     * by the browser's own `animationstart`, not sampled.
+     *
+     * The status flip and the first moving frame are different moments: a React
+     * 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. Null means no flemo animation reported a start for this flight.
+     */
+    firstAnimationAtMs: number | null;
 }
 /**
  * Images inside the flight's participants. A still-loading <img> that
@@ -123,6 +128,100 @@ export interface ImageActivity {
      */
     completedUnheld: number;
 }
+/**
+ * The shared elements on this flight, and whether they actually flew.
+ *
+ * WHY THIS IS ITS OWN SECTION. A morph that does not pair produces no error,
+ * no attribute, no animation and no console line: the element simply appears
+ * where it belongs and the navigation looks like one without a shared element
+ * at all. Four separate investigations began by hand-building a private tracer
+ * to answer the one question "did these two ends find each other", and each
+ * one was deleted when it was over. The runtime writes the pairing key onto
+ * every registered morph (`data-flemo-morph-id`) precisely so this section can
+ * answer it from outside, permanently.
+ */
+export interface MorphActivity {
+    /** Registered morphs seen anywhere in the document as the flight opened. */
+    registered: number;
+    /**
+     * Pairing keys carried by ends in TWO different screens: a pair that had
+     * everything it needs to fly.
+     */
+    pairable: string[];
+    /** Pairing keys whose end was stamped with a flight role (it flew). */
+    flew: string[];
+    /**
+     * Pairable keys that never took a role. This is the morph-skip signature —
+     * the pair existed and the flight did not happen.
+     */
+    skipped: string[];
+    /** A screen was driven as a camera (`carry: "screen"`) on this flight. */
+    camera: boolean;
+    /** Ghosts (copies of the replaced element) seen during the flight. */
+    ghosts: number;
+    /**
+     * Morph elements still stamped with a role once the flight landed. A role
+     * outliving its flight is the stranded-participant class: it stays in the
+     * layer and poisons the NEXT pairing, which is how one interrupted swipe
+     * turned into every later pop losing its camera.
+     */
+    strandedRoles: number;
+    /** Stand-ins left in the layout at rest — a hole where the element belongs. */
+    strandedStandIns: number;
+    /** Ghosts left in the document at rest. */
+    strandedGhosts: number;
+    /**
+     * Morph keyframe rules left in the per-flight sheet at rest, over what the
+     * flight started with. One `<style>` element holds them all and outlives
+     * every flight, so the rules are the leak, not the element.
+     */
+    leakedSheetRules: number;
+    /**
+     * Pairing keys used by more than one end inside a SINGLE screen. Not a
+     * runtime failure: two ends under one screen are not a pair, so one of them
+     * can never fly. Reported because the symptom (an element that morphs only
+     * sometimes) reads exactly like a library defect.
+     */
+    duplicatedKeys: string[];
+    /** Elements left inside a flight layer at rest (the corpse class). */
+    layerResidue: number;
+}
+/**
+ * A tripwire hit: something the recorder was TOLD about rather than something
+ * it sampled.
+ *
+ * The distinction is the whole reason this exists. Three of this project's
+ * hardest defects lasted exactly one frame — a false `animationend` carrying
+ * `elapsedTime` 0, an `animationcancel` from a re-parent that let a negative
+ * delay overwrite the authored one, a ghost cut a frame before its fade — and
+ * a sampler that looks three times a second sees none of them. These are
+ * event listeners: they cost nothing while nothing happens, and they cannot
+ * miss the frame when it does.
+ */
+export interface TripwireHit {
+    kind: "animation-cancel" | "zero-length-animation-end" | "hold-reassert" | "ghost-cut";
+    /** Offset from the flight's t0, in ms. */
+    atMs: number;
+    /** The animation or element involved, and what the hit means. */
+    detail: string;
+}
+/**
+ * What drove this navigation, as the browser reports it.
+ *
+ * `isTrusted` and `pointerType` are cheap and decisive. A build whose touch
+ * path was broken outright once passed every automated layer green because
+ * every probe drove it with a mouse, and synthetic dispatch never fires
+ * `pointerdown` at all — so a session that only ever saw untrusted or
+ * mouse-only input has not tested what a phone does, however clean it reads.
+ */
+export interface InputEvidence {
+    /** Trusted pointer/click events observed shortly before the flight opened. */
+    trusted: number;
+    /** Untrusted (script-dispatched) ones. */
+    synthetic: number;
+    /** Distinct `pointerType` values seen ("touch", "mouse", "pen"). */
+    pointerTypes: string[];
+}
 /** Post-landing residue audit, taken 2 rAF after the flight completed. */
 export interface LandingAudit {
     /**
@@ -152,6 +251,8 @@ export interface FlightRecord {
     id: string;
     /** data-flemo-router of the first participating screen, if stamped. */
     routerId?: string;
+    /** The comparison bucket armed when this flight ran (see `mark`). */
+    bucket?: string;
     kind: FlightKind;
     t0: FlightTimestamp;
     t1: FlightTimestamp;
@@ -164,8 +265,12 @@ export interface FlightRecord {
     motion: MotionProgress;
     /** Image load/hold activity inside the participants during the flight. */
     images: ImageActivity;
-    /** Present only when the player's gap mirror grew during the flight. */
-    playerGaps?: PlayerGapStats;
+    /** Shared elements: which paired, which flew, what they left behind. */
+    morphs: MorphActivity;
+    /** One-frame events the recorder was notified of rather than sampled. */
+    tripwires: TripwireHit[];
+    /** What drove the navigation (trusted finger, mouse, or a script). */
+    input: InputEvidence;
     /**
      * Long tasks intersecting the RELEASED phase (visible motion) — these
      * drive the anomaly rules.
@@ -191,8 +296,16 @@ export interface ObservationCapabilities {
     longTasks: boolean;
     /** Element.getAnimations available — compiled-tier detection is direct. */
     elementAnimations: boolean;
-    /** window.__flemoPlayerGaps present (the player has driven >= 1 flight). */
-    playerGapMirror: boolean;
+    /**
+     * A flemo-named CSS animation event reached the tripwires at least once.
+     *
+     * This is the instrument checking ITSELF. A probe that never fires reads
+     * exactly like a page with nothing to report, and a build whose probe was
+     * silently broken once passed every layer green. If flights were recorded
+     * and this is false, the animation channel saw nothing — treat every
+     * animation-derived field in this report as unmeasured, not as clean.
+     */
+    animationEvents: boolean;
 }
 export interface EnvironmentFingerprint {
     userAgent: string;
@@ -202,6 +315,8 @@ export interface EnvironmentFingerprint {
     platform: string;
     maxTouchPoints: number;
     devicePixelRatio: number;
+    /** navigator.hardwareConcurrency, for reading a contention number in scale. */
+    hardwareConcurrency: number;
     screen: {
         width: number;
         height: number;
@@ -217,6 +332,14 @@ export interface EnvironmentFingerprint {
         sampleCount: number;
     };
     reducedMotion: boolean;
+    /**
+     * Development-server globals found on `window` (HMR clients, framework dev
+     * hooks). A development build is a different program: unminified, double-
+     * invoking, hot-reload-instrumented. A verdict taken on one says nothing
+     * about what ships, and a whole day of "regression ladder" measurements
+     * once turned out to be measuring the build itself.
+     */
+    developmentHints: string[];
     /**
      * DevTools device-emulation signature: Blink + desktop platform + touch
      * points. Emulation composites the page to a scaled surface, so VISUAL
@@ -227,6 +350,22 @@ export interface EnvironmentFingerprint {
     emulationSuspected: boolean;
     observation: ObservationCapabilities;
 }
+/** Whether one judging precondition held, as far as the page can tell. */
+export type PreconditionStatus = "ok" | "violated" | "unknown";
+/**
+ * One precondition of a motion verdict, and what the page could observe about
+ * it. `unknown` is a first-class answer: several of the traps that cost this
+ * project weeks are not visible from inside a page at all, and saying so is
+ * the honest report — an agent must then confirm them with the user rather
+ * than read silence as consent.
+ */
+export interface Precondition {
+    id: string;
+    status: PreconditionStatus;
+    detail: string;
+    /** Numbers behind the verdict, when there are any. */
+    metrics?: Record<string, number>;
+}
 export interface OverridesSection {
     /**
      * Every `flemo:*` storage key found (sessionStorage + localStorage),
@@ -238,13 +377,59 @@ export interface OverridesSection {
     /** Derived, prominent warnings — read these before trusting anything. */
     warnings: string[];
 }
+/**
+ * One comparison bucket: every flight recorded while that label was armed.
+ *
+ * The A/B ladder is this project's standard move and it has been run by hand
+ * every time — navigate five times, read five numbers off a console, change
+ * one thing, repeat. Doing it in the recorder removes the two ways that went
+ * wrong: numbers copied out of order, and a "candidate fix" build that changed
+ * more than one thing at once and made the whole judgement void.
+ */
+export interface BucketSummary {
+    bucket: string;
+    flights: number;
+    medianDurationMs: number;
+    medianReleasedGapMs: number;
+    worstReleasedGapMs: number;
+    longGapCount: number;
+    anomalyCount: number;
+    /** Flights whose motion stalled at least once (see MotionProgress). */
+    stalledFlights: number;
+}
+/**
+ * Flights carried over from before the last full page load.
+ *
+ * A development session reloads constantly — HMR, a rebuild, a hard refresh to
+ * clear state — and each reload used to take the trace with it, including the
+ * one flight the user had just seen go wrong. Kept apart from the live flights
+ * rather than merged: they came from a different page instance, possibly a
+ * different build.
+ */
+export interface PreviousSession {
+    savedAt: string;
+    flights: FlightRecord[];
+    note: string;
+}
 export interface FlemoReport {
     generatedAt: string;
     /** Report schema version (not the package version). */
     version: string;
+    /**
+     * The recorder's own reading of the session, most important first, in plain
+     * sentences. Read this before anything else: it says whether this session
+     * can be used as evidence at all, and then what it found.
+     */
+    verdict: string[];
     environment: EnvironmentFingerprint;
+    /** The observable half of the judging protocol, checked. */
+    preconditions: Precondition[];
     overrides: OverridesSection;
     flights: FlightRecord[];
+    /** Per-bucket summaries; empty unless `mark()` armed at least one. */
+    comparison: BucketSummary[];
+    /** Flights restored from the previous page instance, or null. */
+    previousSession: PreviousSession | null;
     /** Session-level findings (observation traps, active pins, stuck flights). */
     anomalies: string[];
     /**
@@ -255,9 +440,9 @@ export interface FlemoReport {
     blindSpots: string[];
     /**
      * Constant list of preconditions a motion verdict is only valid under (see
-     * judging.ts). The report cannot verify them from inside the page — an
-     * agent must confirm them with the user before trusting any judgement,
-     * including a clean one.
+     * judging.ts). The ones the page CAN check appear in `preconditions`; these
+     * are the rest, which an agent must confirm with the user before trusting
+     * any judgement, including a clean one.
      */
     judgingProtocol: string[];
 }
@@ -266,10 +451,22 @@ export interface FlightRecorderOptions {
     maxFlights?: number;
     /** console.info a one-line summary per completed flight. Default false. */
     log?: boolean;
-    /** Install window.flemo = { report, flights, detach }. Default true. */
+    /** Install window.flemo = { report, flights, mark, detach }. Default true. */
     installGlobal?: boolean;
+    /**
+     * Carry flights across a full page load through sessionStorage. Default
+     * true — a development session reloads constantly and the flight worth
+     * reading is usually the one before the reload. Written only while no
+     * flight is running.
+     */
+    persist?: boolean;
 }
 export interface FlightRecorderHandle {
     detach: () => void;
     report: () => FlemoReport;
+    /**
+     * Arm a comparison bucket. Every flight recorded from here on carries the
+     * label until it is changed; `null` clears it. Returns the label in force.
+     */
+    mark: (bucket: string | null) => string | null;
 }

package/dist/verdict.d.ts

@@ -0,0 +1,7 @@
+import { FlightRecord, ObservationCapabilities, Precondition } from './types';
+export interface VerdictInput {
+    preconditions: readonly Precondition[];
+    flights: readonly FlightRecord[];
+    observation: ObservationCapabilities;
+}
+export declare const deriveVerdict: (input: VerdictInput) => string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flemo/devtools",
-  "version": "0.4.0",
-  "description": "Zero-config flight recorder for flemo screen transitions: captures per-flight driver routing, frame pacing, long tasks, landing residues, active debug overrides, and environment/observation-trap fingerprints into one JSON report readable by humans and coding agents.",
+  "version": "0.6.0",
+  "description": "Zero-config flight recorder, on-device readout and visual panel for flemo screen transitions: captures per-flight driver routing, frame pacing, long tasks, shared-element pairing, landing residues and judging preconditions into one JSON report readable by humans and coding agents.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -34,13 +34,17 @@
   "homepage": "https://flemo.dev",
   "license": "MIT",
   "devDependencies": {
-    "@flemo/core": "2.2.0",
+    "@flemo/core": "2.3.1",
     "@flemo/eslint-config": "0.0.0",
     "@flemo/tsconfig": "0.0.0",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^24.13.1",
+    "@types/react": "^19.2.18",
     "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9.39.5",
     "jsdom": "^29.1.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "vite": "^8.2.2",
     "vite-plugin-dts": "^5.0.3",
@@ -56,16 +60,30 @@
       "production": "./dist/noop.mjs",
       "default": "./dist/index.mjs"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "development": "./dist/react.mjs",
+      "production": "./dist/reactNoop.mjs",
+      "default": "./dist/react.mjs"
+    },
     "./force": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },
+  "peerDependencies": {
+    "react": "^19.2.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "vite build && DEVTOOLS_ENTRY=noop vite build",
-    "watch": "vite build --watch",
-    "dev": "vite build --watch",
+    "build": "rm -rf dist && vite build && DEVTOOLS_ENTRY=noop vite build && DEVTOOLS_ENTRY=react vite build && DEVTOOLS_ENTRY=reactNoop vite build",
+    "watch": "vite build --watch & DEVTOOLS_ENTRY=noop vite build --watch & DEVTOOLS_ENTRY=react vite build --watch & DEVTOOLS_ENTRY=reactNoop vite build --watch & wait",
+    "dev": "vite build --watch & DEVTOOLS_ENTRY=noop vite build --watch & DEVTOOLS_ENTRY=react vite build --watch & DEVTOOLS_ENTRY=reactNoop vite build --watch & wait",
     "lint": "eslint \"**/*.{js,mjs,ts,jsx,tsx,mts}\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",