iterate-ui-overlay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor White
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { SelectedElement, TextSelection, DrawingData, Rect, ClientMessage, ServerMessage, IterationInfo } from 'iterate-ui-core';
+
+type ToolMode = "select" | "move" | "draw" | "browse";
+interface IterateOverlayProps {
+    /** Which tool mode is active */
+    mode: ToolMode;
+    /** Name of the current iteration being viewed */
+    iteration: string;
+    /** WebSocket URL for daemon connection (auto-detected if omitted) */
+    wsUrl?: string;
+    /** Reference to the iteration iframe */
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    /** Current pending change count (passed up for toolbar badge) */
+    onBatchCountChange?: (count: number) => void;
+    /** Current pending move count (passed up for toolbar badge) */
+    onMoveCountChange?: (count: number) => void;
+    /** Whether any changes are currently being processed (in-progress) */
+    onProcessingChange?: (processing: boolean) => void;
+    /** Whether live preview is enabled */
+    previewMode?: boolean;
+    /** Whether the toolbar is visible — when false, badges are hidden and tools are disabled */
+    visible?: boolean;
+}
+/**
+ * Main overlay component for iterate.
+ * Renders element selection tools, change panel, and drag handler
+ * on top of an iteration's iframe.
+ *
+ * Changes and DOM changes are pushed to the daemon immediately on creation
+ * (no local batching). The daemon is the source of truth — state is synced via
+ * WebSocket and badges are removed when the agent implements them.
+ */
+declare function IterateOverlay({ mode, iteration, wsUrl, iframeRef, onBatchCountChange, onMoveCountChange, onProcessingChange, previewMode, visible, }: IterateOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface PickedElement extends SelectedElement {
+    /** The raw DOM element (not serialized) */
+    domElement: Element;
+}
+interface ElementPickerProps {
+    active: boolean;
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    selectedElements: PickedElement[];
+    onSelect: (elements: PickedElement[], clickPosition?: {
+        x: number;
+        y: number;
+    }) => void;
+    /** When true, suppress hover highlight (e.g. during marquee drag) */
+    suppressHover?: boolean;
+    /** Shared ref — when true, a marquee drag just finished and the click should be swallowed */
+    justFinishedDragRef?: React.RefObject<boolean>;
+}
+/**
+ * Overlay that highlights elements on hover and captures clicks.
+ * Supports multi-select with Ctrl/Cmd+Click.
+ * Shows React component names and source file paths when available.
+ */
+declare function ElementPicker({ active, iframeRef, selectedElements, onSelect, suppressHover, justFinishedDragRef, }: ElementPickerProps): react_jsx_runtime.JSX.Element | null;
+
+interface MarqueeSelectProps {
+    active: boolean;
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    onSelect: (elements: PickedElement[]) => void;
+    /** Called when marquee drag starts/stops */
+    onDragStateChange?: (isDragging: boolean) => void;
+    /** Shared ref — set to true after a successful drag so ElementPicker can swallow the click */
+    justFinishedDragRef?: React.RefObject<boolean>;
+}
+/**
+ * Rubber-band / marquee multi-select overlay.
+ * Click-drag on empty space to draw a selection rectangle,
+ * then select all elements within the rectangle.
+ * Highlights contained elements live during drag.
+ */
+declare function MarqueeSelect({ active, iframeRef, onSelect, onDragStateChange, justFinishedDragRef, }: MarqueeSelectProps): react_jsx_runtime.JSX.Element | null;
+
+interface TextSelectProps {
+    active: boolean;
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    onTextSelect: (selection: TextSelection | null) => void;
+}
+/**
+ * Captures text selections within the iframe.
+ * When the user highlights text using native browser selection,
+ * captures the text, containing element, and range offsets.
+ */
+declare function TextSelect({ active, iframeRef, onTextSelect, }: TextSelectProps): react_jsx_runtime.JSX.Element | null;
+
+interface MarkerDrawProps {
+    active: boolean;
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    /** Called when drawing is complete — returns nearby elements + drawing data */
+    onDrawComplete: (elements: PickedElement[], drawing: DrawingData) => void;
+}
+/**
+ * Freehand drawing overlay (marker tool).
+ *
+ * When active, the user can draw on the screen. On mouseup, the drawing
+ * is captured as an SVG path, nearby/underlying elements are identified,
+ * and the annotation panel is opened.
+ */
+declare function MarkerDraw({ active, iframeRef, onDrawComplete, }: MarkerDrawProps): react_jsx_runtime.JSX.Element | null;
+
+interface SelectionPanelProps {
+    selectedElements: PickedElement[];
+    textSelection: TextSelection | null;
+    onRemoveElement: (index: number) => void;
+    onAddToBatch: (comment: string) => void;
+    onClearSelection: () => void;
+    clickPosition?: {
+        x: number;
+        y: number;
+    } | null;
+    /** When true, the header shows "Path" with no dropdown (marker/draw tool) */
+    isDrawing?: boolean;
+    /** Pre-fill comment when editing an existing change */
+    initialComment?: string;
+    /** Shown as a left-aligned trash button in the toolbar (for editing existing changes) */
+    onDelete?: () => void;
+    /** Reference to the iteration iframe (for click-outside detection) */
+    iframeRef?: React.RefObject<HTMLIFrameElement | null>;
+}
+/**
+ * Flat, greyscale popup with a layered card effect.
+ *
+ * The header (component name + CSS drawer) sits on a recessed lower layer.
+ * The main card (textarea + buttons) floats on top with rounded top corners,
+ * so the CSS drawer feels like it slides out from behind the main card.
+ *
+ * Animates in with a springy scale-up and fades out on dismiss.
+ */
+declare function SelectionPanel({ selectedElements, textSelection, onAddToBatch, onClearSelection, clickPosition, isDrawing, initialComment, onDelete, iframeRef, }: SelectionPanelProps): react_jsx_runtime.JSX.Element | null;
+
+/** A completed move with rollback info for live preview */
+interface PendingMove {
+    iteration?: string;
+    /** Page URL where this move was made */
+    url?: string;
+    selector: string;
+    from: Rect;
+    to: Rect;
+    computedStyles: Record<string, string>;
+    componentName: string | null;
+    sourceLocation: string | null;
+    /** Whether the element is the root of its React component (vs a child inside it) */
+    isComponentRoot?: boolean;
+    /** For flex/grid reordering: the target sibling index */
+    reorderIndex?: number;
+    /** For flex/grid reordering: the original sibling index before drag */
+    originalSiblingIndex?: number;
+    /** The original parent selector for reorder context */
+    parentSelector?: string;
+    /** The destination parent selector (for cross-parent reparenting) */
+    targetParentSelector?: string;
+    /** Window scroll offset when this move was created (for scroll-aware rendering) */
+    scrollOffset?: {
+        x: number;
+        y: number;
+    };
+}
+interface DragHandlerProps {
+    active: boolean;
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    /** Called when a drag completes with full move data */
+    onMove: (move: PendingMove) => void;
+    /** Pending moves to visualize origin markers for */
+    pendingMoves: PendingMove[];
+    /** Whether to show the live preview (transforms applied) vs original positions */
+    previewMode: boolean;
+    /** Called when user deletes a pending move via its badge popup */
+    onDeleteMove?: (index: number) => void;
+    /** @deprecated No longer used — deltas applied via direct DOM mutation in IterateOverlay */
+    moveDeltas?: Record<number, {
+        dx: number;
+        dy: number;
+    }>;
+}
+/**
+ * Drag-to-move handler with two behaviors:
+ *
+ * 1. Flex/grid children: Live DOM reordering — the element physically moves
+ *    among its siblings as the user drags. A drop indicator line shows the
+ *    target gap. On mouseup the reorder is recorded as a dom-change.
+ *
+ * 2. All other elements: Records a positional move intent. Element stays in place,
+ *    a dotted border shows current position, and an arrow points to where it was
+ *    dragged.
+ */
+declare function DragHandler({ active, iframeRef, onMove, pendingMoves, previewMode, onDeleteMove, moveDeltas, }: DragHandlerProps): react_jsx_runtime.JSX.Element;
+
+type MessageHandler = (msg: ServerMessage) => void;
+type IterationsChangeHandler = (iterations: Record<string, IterationInfo>) => void;
+type ToolModeHandler = (mode: string) => void;
+/**
+ * WebSocket connection to the iterate daemon.
+ * Handles reconnection, message dispatch, and iteration state tracking.
+ */
+declare class DaemonConnection {
+    private ws;
+    private handlers;
+    private iterationsHandlers;
+    private toolModeHandlers;
+    private url;
+    private reconnectTimer;
+    private _iterations;
+    constructor(url?: string);
+    connect(): void;
+    disconnect(): void;
+    send(msg: ClientMessage): void;
+    onMessage(handler: MessageHandler): () => void;
+    /** Subscribe to iteration list changes */
+    onIterationsChange(handler: IterationsChangeHandler): () => void;
+    /** Current iterations snapshot */
+    get iterations(): Record<string, IterationInfo>;
+    get connected(): boolean;
+    /** Send a tool mode change to the daemon for relay to all clients */
+    sendToolMode(mode: string): void;
+    /** Subscribe to tool mode changes relayed from other clients */
+    onToolModeChange(handler: ToolModeHandler): () => void;
+    /** Dispatch tool mode changes from server messages */
+    private trackToolMode;
+    /** Update internal iterations state from server messages */
+    private trackIterations;
+}
+
+interface FloatingPanelProps {
+    mode: ToolMode;
+    onModeChange: (mode: ToolMode) => void;
+    visible: boolean;
+    onVisibilityChange: (visible: boolean) => void;
+    /** Number of annotations in the pending batch */
+    batchCount?: number;
+    /** Number of pending moves */
+    moveCount?: number;
+    /** Called when user clicks Trash (clear all annotations and moves) */
+    onClearBatch?: () => void;
+    /** Called when user clicks Copy (copy annotations to clipboard) */
+    onCopyBatch?: () => void;
+    /** Called when user clicks Undo (revert last move) */
+    onUndoMove?: () => void;
+    /** Available iterations (from daemon state) */
+    iterations?: Record<string, IterationInfo>;
+    /** Currently active iteration name */
+    activeIteration?: string;
+    /** Called when user switches iteration */
+    onIterationChange?: (name: string) => void;
+    /** Called when user wants to create iterations (fork) */
+    onFork?: () => void;
+    /** Called when user wants to pick the active iteration */
+    onPick?: (name: string) => void | Promise<void>;
+    /** Called when user wants to discard all iterations and keep original */
+    onDiscard?: () => void | Promise<void>;
+    /** Whether currently viewing an iteration (not Original) */
+    isViewingIteration?: boolean;
+    /** Badge counts per tab (tab name → total pending changes) */
+    tabBadgeCounts?: Record<string, number>;
+    /** Set of iteration names whose iframes have sent a "ready" postMessage */
+    readyIframes?: Set<string>;
+    /** Whether any changes are currently being processed (in-progress) */
+    processing?: boolean;
+}
+/**
+ * Floating toolbar panel with icon-based tools and iteration selector.
+ * Single container that animates between collapsed (logo only) and expanded states.
+ * Can be dragged to any corner of the screen.
+ *
+ * All collapsible tools live in a single ToolGroup for consistent flex spacing.
+ * Sections (separated by dividers):
+ * 1. Annotation tools (select, draw, move)
+ * 2. Change tools (undo, trash, copy, send) — no internal divider
+ * 3. Branching tools (fork/iterate, merge/pick, discard)
+ * 4. Close/open toggle (always visible)
+ */
+declare function FloatingPanel({ mode, onModeChange, visible, onVisibilityChange, batchCount, moveCount, onClearBatch, onCopyBatch, onUndoMove, iterations, activeIteration, onIterationChange, onFork, onPick, onDiscard, isViewingIteration, tabBadgeCounts, readyIframes, processing, }: FloatingPanelProps): react_jsx_runtime.JSX.Element;
+
+interface ThemeTokens {
+    panelBg: string;
+    cardBg: string;
+    toolbarBg: string;
+    drawerBg: string;
+    hoverBg: string;
+    activeBg: string;
+    border: string;
+    textPrimary: string;
+    textSecondary: string;
+    textTertiary: string;
+    textDisabled: string;
+    iconDefault: string;
+    iconHover: string;
+    suspenseOverlay: string;
+    spinnerBg: string;
+    spinnerFg: string;
+    tooltipBg: string;
+    tooltipText: string;
+    tooltipKeyBg: string;
+    tooltipKeyText: string;
+    buttonBg: string;
+    buttonText: string;
+}
+declare function useTheme(): ThemeTokens;
+declare function ThemeProvider({ children, targetDocument, }: {
+    children: React.ReactNode;
+    /** Optional document to detect theme from (e.g. an iteration iframe's contentDocument).
+     *  Falls back to the current document when null/undefined. */
+    targetDocument?: Document | null;
+}): React.FunctionComponentElement<React.ProviderProps<ThemeTokens>>;
+
+/**
+ * Generate a unique CSS selector for a DOM element.
+ * Produces a human-readable path like: article > section.hero > h1
+ */
+declare function generateSelector(element: Element): string;
+/**
+ * Build a human-readable ancestor path (up to maxDepth ancestors).
+ * Example: "main > section > div.card"
+ */
+declare function buildAncestorPath(element: Element, maxDepth?: number): string;
+/**
+ * Generate a human-readable label for an element.
+ */
+declare function describeElement(element: Element): string;
+/** Capture text content near the element (own + sibling text) */
+declare function captureContextText(element: Element): string;
+/**
+ * Get the nearest React component name for a DOM element by walking the
+ * fiber tree. Returns just the innermost user component (e.g. "Header"),
+ * not the full ancestry chain.
+ *
+ * Falls back to data-iterate-component/data-iterate-source attributes
+ * if the babel plugin injected them.
+ */
+declare function getComponentInfo(element: Element): {
+    component: string | null;
+    source: string | null;
+    isComponentRoot: boolean;
+};
+/**
+ * Extract computed styles relevant to the element's type.
+ * Text elements get typography props, containers get layout props, etc.
+ */
+declare function getRelevantStyles(element: Element): Record<string, string>;
+
+export { DaemonConnection, DragHandler, ElementPicker, FloatingPanel, IterateOverlay, type IterateOverlayProps, MarkerDraw, MarqueeSelect, type PendingMove, type PickedElement, SelectionPanel, TextSelect, ThemeProvider, type ThemeTokens, type ToolMode, buildAncestorPath, captureContextText, describeElement, generateSelector, getComponentInfo, getRelevantStyles, useTheme };