@flemo/devtools 0.3.0 → 0.5.0

package/dist/frameProbe.d.ts

@@ -0,0 +1,53 @@
+import { MotionProgress } from './types';
+/** 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. */
+    inlineSuppression: boolean;
+    /** Inline transform/opacity advanced between sampled frames. */
+    inlineAdvance: boolean;
+}
+/** Everything the frame probe accumulates for one flight. */
+export interface FrameProbeState {
+    /** Frame gaps while any participant still carried an active anim-hold. */
+    heldGaps: number[];
+    /** Frame gaps after every hold released (the visible-motion phase). */
+    releasedGaps: number[];
+    lastFrameAt: number | null;
+    evidence: DriverEvidence;
+    lastPose: Map<Element, string>;
+    /** Cached compiled animations, so the clock read never re-queries per frame. */
+    clocks: Map<Element, Animation>;
+    lastClock: Map<Element, number>;
+    releasedFrames: number;
+    stalledFrames: number;
+    tailFrames: number;
+    stallRunMs: number;
+    longestStallMs: number;
+    pausedAfterRelease: boolean;
+    holdReassertedAtMs: number | null;
+}
+export declare const createFrameProbeState: () => FrameProbeState;
+/**
+ * A hold is active while ANY participating element still carries an active
+ * `data-flemo-anim-hold` value; the flight is "released" once every one of
+ * them reads "false" (or drops the attribute). The engine deliberately absorbs
+ * heavy commits INTO the hold — the screen is posed, not moving — so gaps and
+ * long tasks are segmented on this boundary.
+ */
+export declare const holdActive: (elements: readonly Element[]) => boolean;
+/**
+ * Did this frame MOVE? Read from the cheapest honest source per tier: a
+ * compiled flight's own animation clock (getAnimations, no style flush) and an
+ * inline-driven flight's pose (already in the style attribute). A frame where
+ * neither moved is a stall — the signature that timing metrics miss.
+ */
+export declare const sampleProgress: (state: FrameProbeState, elements: readonly Element[], frameGapMs: number) => void;
+export declare const sampleDriverEvidence: (state: FrameProbeState, elements: readonly Element[]) => void;
+/**
+ * Everything the frame probe knows about the motion. `firstAnimationAtMs` is
+ * deliberately NOT here: it comes from the browser's own `animationstart`
+ * event, which is a tripwire, and the orchestrator joins the two.
+ */
+export declare const motionProgress: (state: FrameProbeState) => Omit<MotionProgress, "firstAnimationAtMs">;

package/dist/hud.d.ts

@@ -0,0 +1,18 @@
+import { FlightRecorderHandle } from './types';
+export interface DevtoolsHudOptions {
+    /** Recorder to read. Defaults to this package's `window.flemo`, else its own. */
+    recorder?: FlightRecorderHandle;
+    /** Where the strip sits. Default "top". */
+    position?: "top" | "bottom";
+    /** Start expanded. Default false (the one-line summary). */
+    initialExpanded?: boolean;
+    /** Labels the long-press cycles through. Default ["A", "B"]. */
+    buckets?: string[];
+}
+export interface DevtoolsHudHandle {
+    detach: () => void;
+}
+/**
+ * Mount the on-device readout. Idempotent while mounted; inert without a DOM.
+ */
+export declare const attachDevtoolsHud: (options?: DevtoolsHudOptions) => DevtoolsHudHandle;

package/dist/imageProbe.d.ts

@@ -0,0 +1,23 @@
+import { ImageActivity } from './types';
+export interface ImageProbeState {
+    /** Images being tracked for this flight: loading at t0, plus arrivals. */
+    tracked: Set<HTMLImageElement>;
+    loadingAtStart: number;
+    addedDuringFlight: number;
+    held: Set<Element>;
+}
+export declare const createImageProbeState: (screens: readonly Element[]) => ImageProbeState;
+/**
+ * Images that arrive DURING the flight — a data commit landing mid-navigation,
+ * which is the case core's image hold watches for with its own observer.
+ * Without this the probe would only ever see the screens as they looked at t0.
+ */
+export declare const trackAddedImages: (state: ImageProbeState, elements: readonly Element[], added: NodeList) => void;
+/** One query per flight, on the first moving frame: which images the engine parked. */
+export declare const snapshotHeldImages: (state: ImageProbeState, elements: readonly Element[]) => void;
+/**
+ * Per-image accounting. Counting completions and holds separately and
+ * subtracting would cancel a held-but-still-loading image against an unheld
+ * completed one, hiding the exact regression this exists to catch.
+ */
+export declare const imageActivity: (state: ImageProbeState) => ImageActivity;

package/dist/index.d.ts

@@ -1,13 +1,22 @@
 export { attachFlightRecorder, REPORT_SCHEMA_VERSION } from './recorder';
 export type { FlemoGlobal } from './recorder';
-export { deriveFlightAnomalies, deriveReportAnomalies, LONG_GAP_MS, STUCK_STATUS_MS, OPENING_WINDOW_LEAD_MS, OPENING_WINDOW_TAIL_MS, MID_FLIGHT_TASK_MS } from './anomalies';
+export { deriveFlightAnomalies, deriveReportAnomalies, LONG_GAP_MS, STALL_MS, STUCK_STATUS_MS, OPENING_WINDOW_LEAD_MS, OPENING_WINDOW_TAIL_MS, MID_FLIGHT_TASK_MS } from './anomalies';
 export type { FlightAnomalyInput, ReportAnomalyInput } from './anomalies';
 export { BLIND_SPOTS } from './blindSpots';
+export { JUDGING_PROTOCOL } from './judging';
+export { summariseBuckets } from './buckets';
 export { attachDevtoolsPanel } from './panel';
 export type { DevtoolsPanelHandle, DevtoolsPanelOptions } from './panel';
-export { captureEnvironment, detectEngine, isEmulationSuspected, sampleRafCadence } from './environment';
+export { attachDevtoolsHud } from './hud';
+export type { DevtoolsHudHandle, DevtoolsHudOptions } from './hud';
+export { captureEnvironment, detectEngine, developmentHints, isEmulationSuspected, sampleRafCadence } from './environment';
+export { derivePreconditions } from './preconditions';
+export type { PreconditionInput } from './preconditions';
+export { deriveVerdict } from './verdict';
+export type { VerdictInput } from './verdict';
+export { clearTrace, loadTrace, saveTrace, TRACE_KEY } from './persistence';
 export { CORE_FLAGS, deriveOverrideWarnings, DEVTOOLS_OWNED_FLAGS, FLAG_REGISTRY, PANEL_HEIGHT_KEY, RETIRED_FLAGS, RETIRED_MARKER, snapshotOverrides } from './overrides';
 export type { FlagClass, FlagDescriptor, RetiredFlag } from './overrides';
-export { classifyDriver, computeFrameStats, computePhaseStats, computePlayerGapStats, kindFromStatus, parseTranslateX } from './sampling';
-export type { DriverEvidence } from './sampling';
-export type { EnvironmentFingerprint, FlemoReport, FlightDriver, FlightHolds, FlightKind, FlightParticipants, FlightRecord, FlightRecorderHandle, FlightRecorderOptions, FlightTimestamp, FramePhaseStats, FrameSampleStats, LandingAudit, LongTaskSpan, ObservationCapabilities, OverridesSection, PlayerGapStats, UaBrand } from './types';
+export { classifyDriver, computeFrameStats, computePhaseStats, kindFromStatus, parseTranslateX } from './sampling';
+export type { DriverEvidence } from './frameProbe';
+export type { BucketSummary, EnvironmentFingerprint, FlemoReport, FlightDriver, FlightHolds, FlightKind, FlightParticipants, FlightRecord, FlightRecorderHandle, FlightRecorderOptions, FlightTimestamp, FramePhaseStats, FrameSampleStats, ImageActivity, InputEvidence, LandingAudit, LongTaskSpan, MorphActivity, MotionProgress, ObservationCapabilities, OverridesSection, Precondition, PreconditionStatus, PreviousSession, TripwireHit, UaBrand } from './types';