saccade 0.0.1

package/dist/core.d.ts

@@ -0,0 +1,276 @@
+type ExportFilter = 'active' | 'all-animations' | 'all-elements';
+type OutputDetailLevel = 'compact' | 'standard' | 'detailed' | 'forensic';
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type AnimationInfo = {
+    id: string;
+    name: string;
+    selector: string;
+    elementLabel: string;
+    duration: number;
+    delay: number;
+    easing: string;
+    type: string;
+    source: string | null;
+    resolvedVars: Record<string, string> | null;
+    conflicts: string[] | null;
+    layoutAnimation?: boolean;
+};
+type PropertySnapshot = {
+    property: string;
+    value: string;
+    from: string | null;
+    to: string | null;
+};
+type FrameAnimation = {
+    animationId: string;
+    currentTime: number;
+    progress: number;
+    properties: PropertySnapshot[];
+};
+type ElementSnapshot = {
+    __styles: Record<string, string>;
+    __attrs: Record<string, string | null>;
+    __afterOpacity?: string;
+    __beforeOpacity?: string;
+};
+type FrameSnapshot = {
+    time: number;
+    animations: FrameAnimation[];
+    elementSnapshots: Record<string, ElementSnapshot>;
+    activePortalIds: string[];
+    hoveredSels: string[];
+    focusSel: string | null;
+    pointer: {
+        x: number;
+        y: number;
+        buttons: number;
+    };
+    scrollPositions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+};
+type TimelineCapture = {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    animations: AnimationInfo[];
+    frames: FrameSnapshot[];
+    boundingBox: Rect | null;
+};
+type TimelineExport = {
+    timestamp: string;
+    duration: string;
+    scrubPosition: number;
+    hoveredElements: string[];
+    focusedElement: string | null;
+    animations: {
+        element: string;
+        elementLabel: string;
+        name: string;
+        type: string;
+        timing: string;
+        progress: string;
+        properties: {
+            property: string;
+            value: string;
+            range: string;
+        }[];
+        source: string | null;
+        resolvedVars: Record<string, string> | null;
+        conflicts: string[] | null;
+    }[];
+};
+
+type LapseState = 'idle' | 'recording' | 'scrubbing';
+declare class LapseEngine {
+    private timing;
+    private recorder;
+    private scrubber;
+    private capture;
+    private _state;
+    private listeners;
+    get state(): LapseState;
+    getCapture(): TimelineCapture | null;
+    setSpeed(speed: number): void;
+    getSpeed(): number;
+    startRecording(boundingBox?: Rect | null): void;
+    stopRecording(): TimelineCapture;
+    seekTo(timeMs: number): void;
+    release(): void;
+    generateExport(timeMs: number, filter?: ExportFilter): TimelineExport | null;
+    exportForLLM(timeMs: number, filter?: ExportFilter, detail?: OutputDetailLevel): string;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    destroy(): void;
+}
+
+/**
+ * Timing controller — patches all JS timing APIs to respect a speed factor.
+ *
+ * At 0.5x speed, a 100ms setTimeout becomes 200ms real time, and
+ * performance.now() / rAF timestamps advance at half rate.
+ */
+declare class TimingController {
+    private speed;
+    private realBaseline;
+    private virtualBaseline;
+    private intervalMap;
+    private nextIntervalId;
+    private mediaObserver;
+    private animObserver;
+    private _origAnimate;
+    private installed;
+    private _raf;
+    private _caf;
+    private _setTimeout;
+    private _clearTimeout;
+    private _setInterval;
+    private _clearInterval;
+    private _perfNow;
+    private _dateNow;
+    constructor();
+    private getVirtualTime;
+    private reanchor;
+    /** Install timing patches. Safe to call multiple times. */
+    install(): void;
+    /** Set playback speed. Requires install() first. */
+    setSpeed(newSpeed: number): void;
+    /** Patch playbackRate on all active CSS transitions/animations via WAAPI. */
+    private patchAnimations;
+    getSpeed(): number;
+    /** Restore all patched APIs to originals. */
+    destroy(): void;
+}
+
+declare global {
+    interface Window {
+        __LAPSE_ORIGINAL_RAF__?: typeof requestAnimationFrame;
+    }
+}
+/**
+ * Build a stable structural selector for `el` (up to 5 ancestors).
+ * Used as the element identity key throughout recording & scrubbing.
+ */
+declare function getSelector(el: Element): string | null;
+declare class TimelineRecorder {
+    private recording;
+    private startTime;
+    private boundingBox;
+    /** Structural-selector -> live DOM element. */
+    readonly elements: Map<string, HTMLElement>;
+    /** Animation id -> info. */
+    readonly animations: Map<string, AnimationInfo>;
+    /** Original inline style per element (captured on first encounter). */
+    private originalStyles;
+    /** Captured frames. */
+    private frames;
+    private activePortals;
+    private portalIdCounter;
+    private currentPortalIds;
+    private capturedPortals;
+    private prevInlineStyles;
+    private jsAnimStartTimes;
+    private jsAnimLastSeen;
+    private jsAnimFromValues;
+    private jsAnimChangeCount;
+    private currentHoverEls;
+    private currentFocusSel;
+    private currentPointer;
+    private attrObserver;
+    private portalObserver;
+    private exitObserver;
+    private onMouseOver;
+    private onMouseOut;
+    private onFocusIn;
+    private onFocusOut;
+    private onPointerMove;
+    private onPointerDown;
+    private onPointerUp;
+    /** Animations captured via Element.prototype.animate monkey-patch. */
+    readonly interceptedAnimations: {
+        animation: Animation;
+        target: Element;
+    }[];
+    private static readonly MAX_DURATION_MS;
+    private static readonly MAX_FRAMES;
+    private hiddenSince;
+    private onVisibilityChange;
+    /** Set to true when the capture loop self-terminates due to limits. */
+    autoStopped: boolean;
+    /** Called when recording auto-stops. Set by the engine. */
+    onAutoStop: (() => void) | null;
+    private _removeChild;
+    private _remove;
+    private _elementAnimate;
+    /** `<style>` that disables all transitions/animations after recording. */
+    noTransitionsEl: HTMLStyleElement | null;
+    /** Full-screen overlay blocking interaction during scrub. */
+    blockerEl: HTMLDivElement | null;
+    /** `<style>` with cloned :hover / :focus rules rewritten as `[data-lapse-*]`. */
+    lapseStyleEl: HTMLStyleElement | null;
+    private get _raf();
+    getSelector: typeof getSelector;
+    get SAFE_PROPS_SET(): Set<string>;
+    get capturedPortalIds(): Set<string>;
+    startRecording(boundingBox?: Rect | null): void;
+    stopRecording(): TimelineCapture;
+}
+
+/**
+ * Represents a WAAPI Animation intercepted during recording.
+ * The recorder monkey-patches Element.prototype.animate to capture these.
+ */
+interface InterceptedAnimation {
+    animation: Animation;
+    target: Element;
+}
+/**
+ * State handed from the recorder after stopRecording().
+ * This is everything the scrubber needs to replay frames.
+ */
+interface ScrubberState {
+    /** Selector string -> live DOM element */
+    elements: Map<string, HTMLElement>;
+    /** Captured frame snapshots from the recording */
+    frames: FrameSnapshot[];
+    /** All portal IDs ever captured (for show/hide management) */
+    capturedPortals: Set<string>;
+    /** WAAPI animations intercepted via Element.prototype.animate patch */
+    interceptedAnimations: InterceptedAnimation[];
+    /** Set of CSS properties that are safe (visual-only, no layout side-effects) */
+    SAFE_PROPS_SET: Set<string>;
+}
+/**
+ * Timeline scrubber — applies captured frame snapshots to the live DOM.
+ *
+ * Ported from the inline JS that the Electron version injected via
+ * executeJavaScript() in timeline-controller.ts (seekTo / releaseAnimations).
+ */
+declare class TimelineScrubber {
+    private elements;
+    private frames;
+    private capturedPortals;
+    private interceptedAnimations;
+    private SAFE_PROPS_SET;
+    /** Saved originals for restore on release */
+    private _originalAnimate;
+    private _originalRaf;
+    private _originalRemoveChild;
+    private _originalRemove;
+    constructor(state: ScrubberState);
+    private getSelector;
+    seekTo(timeMs: number): void;
+    release(): void;
+}
+
+declare function getFrameAtTime(frames: FrameSnapshot[], timeMs: number): FrameSnapshot | null;
+declare function generateExport(animations: AnimationInfo[], frames: FrameSnapshot[], timeMs: number, filter?: ExportFilter): TimelineExport;
+declare function formatExportForLLM(exp: TimelineExport, detail?: OutputDetailLevel): string;
+
+export { type AnimationInfo, type ElementSnapshot, type ExportFilter, type FrameAnimation, type FrameSnapshot, type InterceptedAnimation, LapseEngine, type LapseState, type OutputDetailLevel, type PropertySnapshot, type Rect, type ScrubberState, type TimelineCapture, type TimelineExport, TimelineRecorder, TimelineScrubber, TimingController, formatExportForLLM, generateExport, getFrameAtTime };