@flemo/devtools 0.1.0 → 0.2.0

package/README.md

@@ -13,6 +13,46 @@ leave a toggle set?").
 Zero dependencies. No imports from `@flemo/core` or `@flemo/react`; attaching
 the recorder never changes the motion it measures.
 
+## Production safety
+
+`@flemo/devtools` resolves to an inert entry when your bundler builds for
+production, so the ordinary import is the safe one:
+
+```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.

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

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

package/dist/noop.d.ts

@@ -0,0 +1,13 @@
+import { DevtoolsPanelHandle, DevtoolsPanelOptions } from './panel';
+import { FlightRecorderHandle, FlightRecorderOptions } from './types';
+export * from './anomalies';
+export * from './blindSpots';
+export * from './environment';
+export * from './overrides';
+export * from './sampling';
+export declare const REPORT_SCHEMA_VERSION = "2";
+export declare const attachFlightRecorder: (_options?: FlightRecorderOptions) => FlightRecorderHandle;
+export declare const attachDevtoolsPanel: (_options?: DevtoolsPanelOptions) => DevtoolsPanelHandle;
+export type { FlemoGlobal } from './recorder';
+export type { DevtoolsPanelHandle, DevtoolsPanelOptions } from './panel';
+export type { DriverPolicySection, EnvironmentFingerprint, FlemoReport, FlightDriver, FlightHolds, FlightKind, FlightParticipants, FlightRecord, FlightRecorderHandle, FlightRecorderOptions, FlightTimestamp, FramePhaseStats, FrameSampleStats, LandingAudit, LongTaskSpan, ObservationCapabilities, OverridesSection, PlayerGapStats, UaBrand } from './types';

package/dist/noop.mjs

@@ -0,0 +1,356 @@
+//#region src/anomalies.ts
+var e = 30, t = 1e4, n = 50, r = 120, i = 100, a = 48, o = (e) => {
+	let n = [], { t0Ms: r, driver: i, frameSamples: a, playerGaps: o, longTasks: s, holdLongTasks: c, landing: l } = e, u = r + (e.releasedAtMs ?? 0);
+	if (o && o.over30Count > 0 && n.push(`player frame gap up to ${o.maxMs}ms ×${o.over30Count} during flight (the rAF player missed frames — convergence jank on this navigation)`), a.released.over30Count > 0) {
+		let e = i === "compiled" ? " (compiled/compositor flights can still present cleanly through main-thread gaps)" : "";
+		n.push(`main-thread rAF gap up to ${a.released.maxGapMs}ms ×${a.released.over30Count} during visible motion${e}`);
+	}
+	for (let e of s) e.startMs <= u + 120 && e.startMs + e.durationMs >= u - 50 ? n.push(`long task ${Math.round(e.durationMs)}ms overlapped the visible-motion start (opening-swallow risk: the first presented frames of the transition may have been lost)`) : e.durationMs >= 100 && n.push(`long task ${Math.round(e.durationMs)}ms mid-flight`);
+	for (let e of c) e.durationMs >= 100 && n.push(`long task ${Math.round(e.durationMs)}ms absorbed by the hold (screen posed, not yet moving — the hold doing its job, not user-visible jank)`);
+	let { motion: d, images: f } = e;
+	return d.holdReassertedAtMs !== null && n.push(`hold re-asserted ${d.holdReassertedAtMs}ms into the flight, after it had already released (an interleaved commit wrote the stale paused hold attribute over a running flight — the flemo 2026-08-18 release-race signature; the motion pauses while every timing metric stays clean)`), d.pausedAfterRelease && n.push("compiled animation reported playState=paused after its release (the flight was posed and then stopped mid-motion, not merely starved of frames)"), d.longestStallMs >= 48 && n.push(`motion stalled ${d.longestStallMs}ms mid-flight (${d.stalledFrames}/${d.sampledFrames} released frames advanced neither the animation clock nor the pose — freeze, or freeze-then-leap if the flight still landed on time)`), d.sampledFrames === 0 && e.releasedAtMs !== null && n.push("no released frames were sampled (the flight ended at or before its own hold release — the visible motion, if any, was never observed)"), f.completedUnheld > 0 && n.push(`${f.completedUnheld} image(s) finished loading mid-flight without a hold (${f.completedDuringFlight} completed, ${f.heldDuringFlight} held; ${f.loadingAtStart} were loading at t0, ${f.addedDuringFlight} arrived mid-flight) — each decode rasters on the moving layer and costs a present; this is the warm-side image-hold regression`), l.orphanedHolds.length > 0 && n.push(`hold markers left on the page at rest: ${l.orphanedHolds.join("; ")} (whatever they hide has no owner left to reveal it — the permanently-blank-avatar class)`), l.residualInlineTransforms.length > 0 && n.push(`residual inline style after COMPLETED: ${l.residualInlineTransforms.join("; ")} (landing cleanup failure — the landed scope belongs to the compiled rest rules)`), l.offViewportAtRest && n.push("screen resting at from-pose while COMPLETED+active (blank-viewport signature — the flemo PR #259 class: a residual pose left the landed screen parked off-viewport)"), l.stuckStatuses.length > 0 && n.push(`transitional status stuck >${t / 1e3}s: ${l.stuckStatuses.join(", ")} (navigation queue lock or missed animationend — later navigations will be swallowed)`), i === "unknown" && n.push("driver could not be classified (no running flemo-* CSSAnimation and no player inline-style signature observed — zero-duration flight, or the sampler attached after motion ended)"), n;
+}, s = (e) => {
+	let n = [];
+	if (e.forcePin !== null && n.push(`active force pin flemo:motion-driver-force=${e.forcePin} — every transition this session is pinned to one driver (A/B residue? pins expire after 24h; clear the key before judging behavior)`), e.clearedForcePin !== null && e.forcePin === null && n.push(`force pin flemo:motion-driver-force=${e.clearedForcePin} was present at attach and has since been cleared (the library strips malformed/expired pins on sight) — early driver decisions in this session may still have been shaped by it`), e.legacyLocalForcePin !== null && n.push(`legacy localStorage driver pin present (flemo:motion-driver-force=${e.legacyLocalForcePin}) — never honored, but it marks A/B residue on this profile`), e.emulationSuspected) {
+		let t = /Win/i.test(e.platform) ? " (Windows touch hardware makes this signal ambiguous — confirm the DevTools device toolbar state)" : "";
+		n.push("DevTools device emulation suspected — the page composites to a rescaled surface, so visual reports from this session are untrustworthy; judge motion in a plain window or on a real device" + t);
+	}
+	return e.stuckFlightOpen && n.push(`a flight is still transitional after ${t / 1e3}s — the navigation queue is likely locked; subsequent navigations will be ignored`), e.flightAnomalies.some((e) => e.some((e) => e.includes("blank-viewport"))) && n.push("at least one flight landed with the blank-viewport signature (see that flight's anomalies)"), n;
+}, c = [
+	"macOS Chrome present-pipeline pacing: on 120Hz ProMotion displays Chrome can present frames unevenly even when rAF cadence and this report read perfectly clean (Chromium issues 40062488 / 345275139; proven with a no-script pure-CSS control page that still juddered). Not diagnosable or fixable from page code.",
+	"Display-hardware effects: local dimming, backlight modulation, and panel overdrive alter perceived motion and are invisible to every web API.",
+	"Compositor-internal present skips: a frame can be produced on time (clean rAF, clean player gaps) yet dropped or delayed inside the compositor's present queue; only platform tools (about:tracing, Instruments) see that layer.",
+	"DevTools device emulation composites the page to a rescaled surface: every in-page instrument reads the pre-scale surface and reports clean while the eye watches the post-scale one, so emulated sessions grow shimmer/flash artifacts that do not exist in a plain window or on a real device."
+], l = () => {
+	if (typeof navigator > "u") return null;
+	let e = navigator.userAgentData;
+	return !e || !Array.isArray(e.brands) ? null : e.brands.map((e) => ({
+		brand: String(e.brand ?? ""),
+		version: String(e.version ?? "")
+	}));
+}, u = () => {
+	if (typeof navigator > "u") return "unknown";
+	let e = l();
+	if (e?.some((e) => /Chromium/i.test(e.brand))) return "blink";
+	let t = navigator.userAgent ?? "";
+	return /Firefox|FxiOS/i.test(t) ? "gecko" : e || /AppleWebKit/i.test(t) && !/Chrome|Chromium|Android/i.test(t) ? "webkit" : /Android/i.test(t) ? "blink" : "unknown";
+}, d = () => {
+	if (typeof navigator > "u" || u() !== "blink") return !1;
+	let e = navigator.platform ?? "";
+	return /Mac|Win|Linux/i.test(e) ? /Android/i.test(navigator.userAgent ?? "") && !/Mac|Win/i.test(e) ? /Linux (x86_64|i686)/i.test(e) : (navigator.maxTouchPoints ?? 0) > 0 : !1;
+}, f = (e = 20) => new Promise((t) => {
+	let n = Number.isFinite(e) ? Math.max(1, Math.floor(e)) : 20;
+	if (typeof requestAnimationFrame != "function" || typeof performance > "u") {
+		t({
+			medianGapMs: null,
+			sampleCount: 0
+		});
+		return;
+	}
+	let r = [], i = null, a = () => {
+		let e = performance.now();
+		if (i !== null && r.push(e - i), i = e, r.length >= n) {
+			let e = [...r].sort((e, t) => e - t), n = e[Math.floor(e.length / 2)];
+			t({
+				medianGapMs: Math.round(n * 100) / 100,
+				sampleCount: r.length
+			});
+			return;
+		}
+		requestAnimationFrame(a);
+	};
+	requestAnimationFrame(a);
+}), p = () => {
+	try {
+		return typeof PerformanceObserver < "u" && Array.isArray(PerformanceObserver.supportedEntryTypes) && PerformanceObserver.supportedEntryTypes.includes("longtask");
+	} catch {
+		return !1;
+	}
+}, m = (e) => {
+	let t = typeof navigator < "u" ? navigator : null, n = typeof window < "u" ? window : null, r = !1;
+	try {
+		r = n?.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? !1;
+	} catch {
+		r = !1;
+	}
+	return {
+		userAgent: t?.userAgent ?? "",
+		uaBrands: l(),
+		engine: u(),
+		platform: t?.platform ?? "",
+		maxTouchPoints: t?.maxTouchPoints ?? 0,
+		devicePixelRatio: n?.devicePixelRatio ?? 1,
+		screen: {
+			width: n?.screen?.width ?? 0,
+			height: n?.screen?.height ?? 0
+		},
+		viewport: {
+			width: n?.innerWidth ?? 0,
+			height: n?.innerHeight ?? 0
+		},
+		visualViewportScale: n?.visualViewport?.scale ?? null,
+		rafCadence: e,
+		reducedMotion: r,
+		emulationSuspected: d(),
+		observation: {
+			longTasks: p(),
+			elementAnimations: typeof Element < "u" && typeof Element.prototype.getAnimations == "function",
+			playerGapMirror: Array.isArray(n?.__flemoPlayerGaps)
+		}
+	};
+}, h = [
+	{
+		key: "flemo:motion-driver",
+		storage: "local",
+		kind: "production-state",
+		description: "learned driver ledger ('css' = player demoted on this device, 'raf' = clean probe)"
+	},
+	{
+		key: "flemo:motion-driver-force",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "hard driver pin ('css@<epoch-ms>' / 'raf@<epoch-ms>', 24h TTL) — pins EVERY transition"
+	},
+	{
+		key: "flemo:lpm",
+		storage: "session",
+		kind: "production-state",
+		description: "low-power-mode cadence seed (learned)"
+	},
+	{
+		key: "flemo:sixty",
+		storage: "session",
+		kind: "production-state",
+		description: "steady-60 display verdict seed ('high' latches, a count seeds the streak)"
+	},
+	{
+		key: "flemo:lat",
+		storage: "session",
+		kind: "production-state",
+		description: "LPM release-latency seed (learned)"
+	},
+	{
+		key: "flemo:landing-snap",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "Blink landing pixel-snap easing A/B"
+	},
+	{
+		key: "flemo:imghold",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "flight-scoped <img> reveal hold"
+	},
+	{
+		key: "flemo:settle-gate",
+		storage: "session",
+		kind: "production-default-with-override",
+		description: "render-settle entry gate override"
+	},
+	{
+		key: "flemo:handoff",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "anchored-opening handoff (POP-scoped)"
+	},
+	{
+		key: "flemo:handoffms",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "handoff point override (ms)"
+	},
+	{
+		key: "flemo:apply",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "force the scrub-WAAPI value-application tier"
+	},
+	{
+		key: "flemo:snap",
+		storage: "session",
+		kind: "production-default-with-override",
+		description: "player device-pixel snap policy override"
+	},
+	{
+		key: "flemo:snapband",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "'hybrid' snap jitter-band width (device px)"
+	},
+	{
+		key: "flemo:layers",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "resident screen layers at rest (armed by ?flemo-layers=)"
+	},
+	{
+		key: "flemo:freeze",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "keep the direct prev screen live (armed by ?flemo-freeze=)"
+	},
+	{
+		key: "flemo:preraster",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "promote the entering content layer through the hold"
+	},
+	{
+		key: "flemo:imgoffload",
+		storage: "session",
+		kind: "production-default-with-override",
+		description: "image decode offloader override"
+	},
+	{
+		key: "flemo:devtools",
+		storage: "session",
+		kind: "opt-in-diagnostic",
+		description: "arms this flight recorder in the playground (?devtools=on)"
+	}
+], g = "flemo:motion-driver-force", _ = `${g} (localStorage — legacy location)`, v = (e) => {
+	try {
+		let t = e === "session" ? sessionStorage : localStorage;
+		return t.length, t;
+	} catch {
+		return null;
+	}
+}, y = (e, t) => {
+	try {
+		return e ? e.getItem(t) : null;
+	} catch {
+		return null;
+	}
+}, b = new Set(h.map((e) => e.key)), x = () => {
+	let e = {}, t = v("session"), n = v("local");
+	for (let r of h) {
+		let i = y(r.storage === "session" ? t : n, r.key);
+		i !== null && (e[r.key] = i);
+	}
+	let r = y(n, g);
+	r !== null && (e[_] = r);
+	for (let [r, i] of [[t, "sessionStorage"], [n, "localStorage"]]) if (r) try {
+		for (let t = 0; t < r.length; t += 1) {
+			let n = r.key(t);
+			!n || !n.startsWith("flemo:") || b.has(n) || (e[`${n} (${i}, unknown key)`] = r.getItem(n) ?? "");
+		}
+	} catch {}
+	return e;
+}, S = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e)) {
+		if (n === g) {
+			t.push(`${n}=${r} — A DRIVER PIN IS ACTIVE: every transition this session is forced onto one driver, bypassing measurement and demotion. If you did not set it deliberately just now, it is A/B residue (mobile tab restoration resurrects sessionStorage across days; pins expire after 24h). This exact residue once burned a multi-day investigation — clear the key before judging any behavior.`);
+			continue;
+		}
+		if (n === _) {
+			t.push(`${n}=${r} — legacy localStorage driver pin present. The library removes it on sight and never honors it, but its existence means an old A/B session left residue on this profile.`);
+			continue;
+		}
+		if (n.startsWith(`${g} `)) {
+			t.push(`${n}=${r} — a driver force pin was observed this session (see marker in the key). Even a since-cleared pin may have shaped early driver decisions; treat this session's routing as suspect.`);
+			continue;
+		}
+		let e = h.find((e) => n === e.key || n.startsWith(`${e.key} `));
+		!e || e.key === "flemo:devtools" || (e.kind === "opt-in-diagnostic" ? t.push(`${n}=${r} — opt-in diagnostic active (${e.description}); behavior differs from stock. Possible left-over A/B toggle from an earlier debugging session.`) : e.kind === "production-default-with-override" && t.push(`${n}=${r} — production default overridden for this session (${e.description}).`));
+	}
+	return t;
+}, C = (e) => Math.round(e * 10) / 10, w = (e) => {
+	if (e.length === 0) return {
+		count: 0,
+		medianGapMs: 0,
+		maxGapMs: 0,
+		over30Count: 0
+	};
+	let t = [...e].sort((e, t) => e - t);
+	return {
+		count: e.length,
+		medianGapMs: C(t[Math.floor(t.length / 2)]),
+		maxGapMs: C(t[t.length - 1]),
+		over30Count: e.filter((e) => e >= 30).length
+	};
+}, T = (e, t = []) => {
+	let n = [...e, ...t];
+	return {
+		...n.length === 0 ? {
+			count: 0,
+			medianGapMs: 0,
+			maxGapMs: 0
+		} : (() => {
+			let e = [...n].sort((e, t) => e - t);
+			return {
+				count: n.length,
+				medianGapMs: C(e[Math.floor(e.length / 2)]),
+				maxGapMs: C(e[e.length - 1])
+			};
+		})(),
+		longGaps: n.filter((e) => e >= 30).map(C),
+		held: w(e),
+		released: w(t)
+	};
+}, E = (e) => e.length === 0 ? null : {
+	maxMs: C(Math.max(...e)),
+	over30Count: e.filter((e) => e >= 30).length
+}, D = (e) => {
+	let t = e.playerSuppression || e.playerAdvance;
+	return t && e.compiledAnimation ? "mixed" : t ? "player" : e.compiledAnimation ? "compiled" : "unknown";
+}, O = (e) => e === "PUSHING" ? "PUSH" : e === "POPPING" ? "POP" : e === "REPLACING" ? "REPLACE" : null, k = (e) => {
+	let t = /^matrix3d\(([^)]+)\)$/.exec(e.trim());
+	if (t) {
+		let e = t[1].split(",").map((e) => Number(e.trim()));
+		return e.length === 16 && Number.isFinite(e[12]) ? e[12] : null;
+	}
+	let n = /^matrix\(([^)]+)\)$/.exec(e.trim());
+	if (n) {
+		let e = n[1].split(",").map((e) => Number(e.trim()));
+		return e.length === 6 && Number.isFinite(e[4]) ? e[4] : null;
+	}
+	return null;
+}, A = "2", j = "@flemo/devtools resolved to its production entry: nothing was recorded. Run a development build to collect a real report.", M = () => {}, N = () => ({
+	generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+	version: "inert",
+	environment: {
+		userAgent: "",
+		uaBrands: null,
+		engine: "unknown",
+		platform: "",
+		maxTouchPoints: 0,
+		devicePixelRatio: 0,
+		screen: {
+			width: 0,
+			height: 0
+		},
+		viewport: {
+			width: 0,
+			height: 0
+		},
+		visualViewportScale: null,
+		rafCadence: {
+			medianGapMs: null,
+			sampleCount: 0
+		},
+		reducedMotion: !1,
+		emulationSuspected: !1,
+		observation: {
+			longTasks: !1,
+			elementAnimations: !1,
+			playerGapMirror: !1
+		}
+	},
+	overrides: {
+		active: {},
+		warnings: [j]
+	},
+	driverPolicy: {
+		demotion: null,
+		forcePin: null
+	},
+	flights: [],
+	anomalies: [j],
+	blindSpots: [],
+	judgingProtocol: [j]
+}), P = (e) => ({
+	detach: M,
+	report: N
+}), F = (e) => ({ detach: M });
+//#endregion
+export { c as BLIND_SPOTS, h as FLAG_REGISTRY, _ as LEGACY_LOCAL_PIN_KEY, e as LONG_GAP_MS, i as MID_FLIGHT_TASK_MS, n as OPENING_WINDOW_LEAD_MS, r as OPENING_WINDOW_TAIL_MS, A as REPORT_SCHEMA_VERSION, a as STALL_MS, t as STUCK_STATUS_MS, F as attachDevtoolsPanel, P as attachFlightRecorder, m as captureEnvironment, D as classifyDriver, T as computeFrameStats, w as computePhaseStats, E as computePlayerGapStats, o as deriveFlightAnomalies, S as deriveOverrideWarnings, s as deriveReportAnomalies, u as detectEngine, d as isEmulationSuspected, O as kindFromStatus, k as parseTranslateX, f as sampleRafCadence, x as snapshotOverrides };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/devtools",
-  "version": "0.1.0",
+  "version": "0.2.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.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -48,8 +48,21 @@
   "publishConfig": {
     "access": "public"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./dist/index.mjs",
+      "production": "./dist/noop.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./force": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && DEVTOOLS_ENTRY=noop vite build",
     "watch": "vite build --watch",
     "dev": "vite build --watch",
     "lint": "eslint \"**/*.{js,mjs,ts,jsx,tsx,mts}\"",