@ui-annotate/react-vite 0.1.0

package/dist/runtime/app/AnnotateWindows.d.ts

@@ -0,0 +1,28 @@
+import type { PointerEvent as ReactPointerEvent, ReactNode } from "react";
+import type { AnnotateTarget, TraceNodeRef } from "../../protocol/task-model.js";
+import { type AnnotateWindowResizeDirection } from "../windows/AnnotateWindowFrame.js";
+import type { AnnotateSettings, AnnotateWindowId, AnnotateWindowMap } from "../shared/annotate-types.js";
+import type { SaveStatus, TaskStatus } from "../windows/window-shared.js";
+export declare function AnnotateWindows({ activeTargetId, saveError, saveStatus, settings, targets, taskError, taskStatus, windows, onActiveTargetChange, onAddComment, onBeginMove, onBeginResize, onChangeComment, onClose, onDeleteComment, onDeleteTarget, onGetAnnotateTraceNodeElement, onHoverAnnotateTraceNode, onOpenCodePath, onResetTargets, onShowNativeTraceNodesChange }: {
+    activeTargetId: string | null;
+    saveError: string | null;
+    saveStatus: SaveStatus;
+    settings: AnnotateSettings;
+    targets: AnnotateTarget[];
+    taskError: string | null;
+    taskStatus: TaskStatus;
+    windows: AnnotateWindowMap;
+    onActiveTargetChange(targetId: string): void;
+    onAddComment(targetId: string): void;
+    onBeginMove(id: AnnotateWindowId, event: ReactPointerEvent<HTMLElement>): void;
+    onBeginResize(id: AnnotateWindowId, direction: AnnotateWindowResizeDirection, event: ReactPointerEvent<HTMLDivElement>): void;
+    onChangeComment(targetId: string, index: number, value: string): void;
+    onClose(id: AnnotateWindowId): void;
+    onDeleteComment(targetId: string, index: number): void;
+    onDeleteTarget(targetId: string): void;
+    onGetAnnotateTraceNodeElement(targetId: string, node: TraceNodeRef): Element | null;
+    onHoverAnnotateTraceNode(targetId: string, node: TraceNodeRef | null): void;
+    onOpenCodePath(path: string): void;
+    onResetTargets(): void;
+    onShowNativeTraceNodesChange(value: boolean): void;
+}): ReactNode;

package/dist/runtime/app/AnnotateWindows.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { BugIcon, SettingsIcon } from "lucide-react";
+import { AnnotateWindow } from "../windows/AnnotateWindow.js";
+import { AnnotateSettingsWindow } from "../windows/AnnotateSettingsWindow.js";
+import { AnnotateWindowFrame } from "../windows/AnnotateWindowFrame.js";
+export function AnnotateWindows({ activeTargetId, saveError, saveStatus, settings, targets, taskError, taskStatus, windows, onActiveTargetChange, onAddComment, onBeginMove, onBeginResize, onChangeComment, onClose, onDeleteComment, onDeleteTarget, onGetAnnotateTraceNodeElement, onHoverAnnotateTraceNode, onOpenCodePath, onResetTargets, onShowNativeTraceNodesChange }) {
+    return (_jsxs(_Fragment, { children: [windows.annotate.open ? (_jsx(AnnotateWindowFrame, { id: "annotate", label: "Annotate component", icon: BugIcon, title: "Annotate component", state: windows.annotate, onBeginMove: onBeginMove, onBeginResize: onBeginResize, onClose: onClose, children: _jsx(AnnotateWindow, { activeTargetId: activeTargetId, saveError: saveError, saveStatus: saveStatus, targets: targets, taskError: taskError, taskStatus: taskStatus, getTraceNodeElement: (targetId) => (node) => onGetAnnotateTraceNodeElement(targetId, node), onActiveTargetChange: onActiveTargetChange, onAddComment: onAddComment, onChangeComment: onChangeComment, onDeleteComment: onDeleteComment, onDeleteTarget: onDeleteTarget, onHoverTraceNode: onHoverAnnotateTraceNode, onOpenPath: onOpenCodePath, onResetTargets: onResetTargets }) })) : null, windows.settings.open ? (_jsx(AnnotateWindowFrame, { id: "settings", label: "Settings", icon: SettingsIcon, title: "Settings", state: windows.settings, onBeginMove: onBeginMove, onBeginResize: onBeginResize, onClose: onClose, children: _jsx(AnnotateSettingsWindow, { settings: settings, onShowNativeTraceNodesChange: onShowNativeTraceNodesChange }) })) : null] }));
+}

package/dist/runtime/app/UiAnnotate.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from "react";
+export declare function UiAnnotate({ portalContainer, rootElement }: {
+    portalContainer?: HTMLElement | null;
+    rootElement?: HTMLElement | null;
+}): ReactNode;

package/dist/runtime/app/UiAnnotate.js

@@ -0,0 +1,540 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { isSameTargetTrace } from "../../protocol/task-model.js";
+import { PortalContainerProvider } from "../../ui/portal/portal-container.js";
+import { TooltipProvider } from "../../ui/components/tooltip.js";
+import { findElementForTarget, findElementForTraceNode, findSelectableTarget, isEditableEventTarget } from "../inspector/target-inspection.js";
+import { useAnnotateLayout } from "../layout/use-annotate-layout.js";
+import { SelectionOverlay } from "../overlay/SelectionOverlay.js";
+import { ANNOTATE_PORTAL_Z_INDEX, ANNOTATE_ROOT_ID } from "../shared/annotate-constants.js";
+import { deleteAllTargets, deleteTarget, registerAnnotateTarget, updateTargetComments } from "../task/annotate-task.js";
+import { useAnnotateTask } from "../task/use-annotate-task.js";
+import { AnnotateToolbar } from "./AnnotateToolbar.js";
+import { AnnotateWindows } from "./AnnotateWindows.js";
+const HOVER_MATCH_INTERVAL_MS = 80;
+const TARGET_MATCH_DELAY_MS = 160;
+export function UiAnnotate({ portalContainer, rootElement }) {
+    const annotateRootRef = useRef(rootElement ?? null);
+    const [hoverTarget, setHoverTarget] = useState(null);
+    const [frozenHoverTarget, setFrozenHoverTarget] = useState(null);
+    const [codeOpenMode, setCodeOpenMode] = useState(false);
+    const [annotateMode, setAnnotateMode] = useState(false);
+    const [activeTargetId, setActiveTargetId] = useState(null);
+    const [traceNodeHover, setTraceNodeHover] = useState(null);
+    const [targetElementMatches, setTargetElementMatches] = useState([]);
+    const hoverTargetRef = useRef(null);
+    const frozenHoverTargetRef = useRef(null);
+    const annotateModeRef = useRef(false);
+    const codeOpenModeRef = useRef(false);
+    const codeOpenPointerUpHandledRef = useRef(false);
+    const hoverMatchFrameRef = useRef(null);
+    const lastHoverMatchTimeRef = useRef(0);
+    const lastHoverElementRef = useRef(null);
+    const { commitTask, flushTaskSave, saveError, saveStatus, task, taskError, taskRef, taskStatus, taskStatusRef } = useAnnotateTask();
+    const { beginToolbarDrag, beginWindowMove, beginWindowResize, closeWindow, openWindow, setSettings, settings, toolbarPosition, windows } = useAnnotateLayout();
+    const activeHoverTarget = frozenHoverTarget ?? hoverTarget;
+    const activeAnnotateTarget = task.targets.find((target) => target.id === activeTargetId) ?? task.targets[0] ?? null;
+    const showCodeOpenCursor = annotateMode && codeOpenMode;
+    const targetMatchKey = useMemo(() => createTargetMatchKey(task.targets), [task.targets]);
+    useEffect(() => {
+        annotateRootRef.current = rootElement ?? document.getElementById(ANNOTATE_ROOT_ID);
+    }, [rootElement]);
+    useEffect(() => {
+        hoverTargetRef.current = hoverTarget;
+    }, [hoverTarget]);
+    useEffect(() => {
+        frozenHoverTargetRef.current = frozenHoverTarget;
+    }, [frozenHoverTarget]);
+    useEffect(() => {
+        annotateModeRef.current = annotateMode;
+    }, [annotateMode]);
+    useEffect(() => {
+        codeOpenModeRef.current = codeOpenMode;
+    }, [codeOpenMode]);
+    useEffect(() => {
+        const styleElement = ensureCodeOpenCursorStyle();
+        styleElement.disabled = !showCodeOpenCursor;
+        return () => {
+            styleElement.disabled = true;
+        };
+    }, [showCodeOpenCursor]);
+    useEffect(() => {
+        if (!import.meta.hot) {
+            return;
+        }
+        const resetTraceHover = () => {
+            setTraceNodeHover(null);
+        };
+        import.meta.hot.on("vite:afterUpdate", resetTraceHover);
+        return () => {
+            import.meta.hot?.off("vite:afterUpdate", resetTraceHover);
+        };
+    }, []);
+    useEffect(() => {
+        const previewRoot = document.body;
+        function handlePointerMove(event) {
+            if (!annotateModeRef.current || isInsideAnnotateRoot(event.target)) {
+                return;
+            }
+            if (!(event.target instanceof Element)) {
+                scheduleHoverMatch(null, false);
+                return;
+            }
+            scheduleHoverMatch(event.target, event.ctrlKey || event.metaKey);
+        }
+        function runHoverMatch(target, modifierPressed) {
+            if (!annotateModeRef.current) {
+                clearHoverState();
+                return;
+            }
+            if (modifierPressed) {
+                let targetToFreeze = frozenHoverTargetRef.current ?? hoverTargetRef.current;
+                if (!targetToFreeze && target) {
+                    const selectableTarget = findSelectableTarget(target, previewRoot, null, settings.showNativeTraceNodes);
+                    if (selectableTarget && !isInsideAnnotateRoot(selectableTarget.element)) {
+                        targetToFreeze = selectableTarget;
+                        hoverTargetRef.current = selectableTarget;
+                        setHoverTarget(selectableTarget);
+                    }
+                }
+                if (targetToFreeze && !frozenHoverTargetRef.current) {
+                    frozenHoverTargetRef.current = targetToFreeze;
+                    setFrozenHoverTarget(targetToFreeze);
+                }
+                codeOpenModeRef.current = targetToFreeze !== null;
+                setCodeOpenMode(codeOpenModeRef.current);
+                return;
+            }
+            if (!modifierPressed && frozenHoverTargetRef.current) {
+                frozenHoverTargetRef.current = null;
+                setFrozenHoverTarget(null);
+            }
+            if (!target) {
+                clearHoverState();
+                return;
+            }
+            const selectableTarget = findSelectableTarget(target, previewRoot, null, settings.showNativeTraceNodes);
+            if (!selectableTarget || isInsideAnnotateRoot(selectableTarget.element)) {
+                clearHoverState();
+                return;
+            }
+            hoverTargetRef.current = selectableTarget;
+            setHoverTarget(selectableTarget);
+            codeOpenModeRef.current = modifierPressed;
+            setCodeOpenMode(codeOpenModeRef.current);
+        }
+        function scheduleHoverMatch(target, modifierPressed) {
+            const now = window.performance.now();
+            const isRepeatTarget = target !== null && target === lastHoverElementRef.current;
+            if (isRepeatTarget && now - lastHoverMatchTimeRef.current < HOVER_MATCH_INTERVAL_MS) {
+                return;
+            }
+            lastHoverElementRef.current = target;
+            if (hoverMatchFrameRef.current !== null) {
+                window.cancelAnimationFrame(hoverMatchFrameRef.current);
+            }
+            hoverMatchFrameRef.current = window.requestAnimationFrame(() => {
+                hoverMatchFrameRef.current = null;
+                lastHoverMatchTimeRef.current = window.performance.now();
+                runHoverMatch(target, modifierPressed);
+            });
+        }
+        function handlePointerLeave() {
+            if (codeOpenModeRef.current && frozenHoverTargetRef.current) {
+                return;
+            }
+            clearHoverState();
+        }
+        previewRoot.addEventListener("pointermove", handlePointerMove);
+        window.addEventListener("pointerleave", handlePointerLeave);
+        return () => {
+            if (hoverMatchFrameRef.current !== null) {
+                window.cancelAnimationFrame(hoverMatchFrameRef.current);
+                hoverMatchFrameRef.current = null;
+            }
+            previewRoot.removeEventListener("pointermove", handlePointerMove);
+            window.removeEventListener("pointerleave", handlePointerLeave);
+        };
+    }, [settings.showNativeTraceNodes]);
+    useEffect(() => {
+        if (!annotateMode) {
+            return;
+        }
+        let cancelled = false;
+        const timeoutId = window.setTimeout(() => {
+            const matches = [];
+            for (const target of taskRef.current.targets) {
+                const element = findElementForTarget(document.body, target, null, settings.showNativeTraceNodes);
+                if (!element || isInsideAnnotateRoot(element)) {
+                    continue;
+                }
+                matches.push({
+                    targetId: target.id,
+                    element
+                });
+            }
+            if (!cancelled) {
+                setTargetElementMatches(matches);
+            }
+        }, TARGET_MATCH_DELAY_MS);
+        return () => {
+            cancelled = true;
+            window.clearTimeout(timeoutId);
+        };
+    }, [annotateMode, settings.showNativeTraceNodes, targetMatchKey]);
+    useEffect(() => {
+        const previewRoot = document.body;
+        const stopPreviewInteraction = (event) => {
+            if (!annotateModeRef.current || isInsideAnnotateRoot(event.target)) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+        };
+        const handleClick = (event) => {
+            if (!annotateModeRef.current || isInsideAnnotateRoot(event.target)) {
+                return;
+            }
+            stopPreviewInteraction(event);
+            if (codeOpenPointerUpHandledRef.current) {
+                codeOpenPointerUpHandledRef.current = false;
+                return;
+            }
+            if (!(event.target instanceof Element)) {
+                return;
+            }
+            if (event.ctrlKey || event.metaKey) {
+                void handleOpenCodeFromElementAndExitAnnotate(event.target, "frozen-first");
+                return;
+            }
+            if (handleAnnotateTargetFromElement(event.target)) {
+                setAnnotateMode(false);
+            }
+        };
+        const handlePointerUp = (event) => {
+            if (!annotateModeRef.current ||
+                isInsideAnnotateRoot(event.target) ||
+                event.button !== 0 ||
+                (!event.ctrlKey && !event.metaKey)) {
+                return;
+            }
+            stopPreviewInteraction(event);
+            if (event.target instanceof Element) {
+                codeOpenPointerUpHandledRef.current = true;
+                void handleOpenCodeFromElementAndExitAnnotate(event.target, "frozen-first");
+            }
+        };
+        const handleFocusIn = (event) => {
+            if (!annotateModeRef.current || isInsideAnnotateRoot(event.target)) {
+                return;
+            }
+            stopPreviewInteraction(event);
+            if (event.target instanceof HTMLElement) {
+                event.target.blur();
+            }
+        };
+        previewRoot.addEventListener("pointerup", handlePointerUp, true);
+        previewRoot.addEventListener("click", handleClick, true);
+        previewRoot.addEventListener("dblclick", stopPreviewInteraction, true);
+        previewRoot.addEventListener("contextmenu", stopPreviewInteraction, true);
+        previewRoot.addEventListener("submit", stopPreviewInteraction, true);
+        previewRoot.addEventListener("dragstart", stopPreviewInteraction, true);
+        previewRoot.addEventListener("focusin", handleFocusIn, true);
+        return () => {
+            previewRoot.removeEventListener("pointerup", handlePointerUp, true);
+            previewRoot.removeEventListener("click", handleClick, true);
+            previewRoot.removeEventListener("dblclick", stopPreviewInteraction, true);
+            previewRoot.removeEventListener("contextmenu", stopPreviewInteraction, true);
+            previewRoot.removeEventListener("submit", stopPreviewInteraction, true);
+            previewRoot.removeEventListener("dragstart", stopPreviewInteraction, true);
+            previewRoot.removeEventListener("focusin", handleFocusIn, true);
+        };
+    }, [settings.showNativeTraceNodes]);
+    useEffect(() => {
+        function handleKeyDown(event) {
+            if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "s") {
+                event.preventDefault();
+                void flushTaskSave();
+                return;
+            }
+            if (isEditableEventTarget(event.target)) {
+                return;
+            }
+            if (!event.metaKey &&
+                !event.ctrlKey &&
+                !event.altKey &&
+                event.key.toLowerCase() === "d") {
+                event.preventDefault();
+                toggleAnnotateModeFromShortcut();
+                return;
+            }
+            if (event.key === "Escape") {
+                clearHoverState();
+                setTraceNodeHover(null);
+                setAnnotateMode(false);
+            }
+        }
+        window.addEventListener("keydown", handleKeyDown);
+        return () => {
+            window.removeEventListener("keydown", handleKeyDown);
+        };
+    }, [flushTaskSave]);
+    useEffect(() => {
+        const updateCodeOpenMode = (event) => {
+            const target = frozenHoverTargetRef.current ?? hoverTargetRef.current;
+            const enabled = target !== null && (event.ctrlKey || event.metaKey);
+            if (enabled && target && !frozenHoverTargetRef.current) {
+                frozenHoverTargetRef.current = target;
+                setFrozenHoverTarget(target);
+            }
+            if (!enabled && frozenHoverTargetRef.current) {
+                frozenHoverTargetRef.current = null;
+                setFrozenHoverTarget(null);
+            }
+            codeOpenModeRef.current = enabled;
+            setCodeOpenMode(enabled);
+        };
+        window.addEventListener("keydown", updateCodeOpenMode);
+        window.addEventListener("keyup", updateCodeOpenMode);
+        return () => {
+            window.removeEventListener("keydown", updateCodeOpenMode);
+            window.removeEventListener("keyup", updateCodeOpenMode);
+        };
+    }, []);
+    function isInsideAnnotateRoot(target) {
+        return target instanceof Node && Boolean(annotateRootRef.current?.contains(target));
+    }
+    function clearHoverState() {
+        lastHoverElementRef.current = null;
+        hoverTargetRef.current = null;
+        frozenHoverTargetRef.current = null;
+        codeOpenModeRef.current = false;
+        setHoverTarget(null);
+        setFrozenHoverTarget(null);
+        setCodeOpenMode(false);
+    }
+    function toggleAnnotateModeFromShortcut() {
+        setAnnotateMode((current) => !current);
+    }
+    function toggleAnnotateModeFromToolbar() {
+        setAnnotateMode((current) => {
+            const next = !current;
+            if (next) {
+                openWindow("annotate");
+            }
+            return next;
+        });
+    }
+    function handleShowNativeTraceNodesChange(showNativeTraceNodes) {
+        clearHoverState();
+        setSettings((current) => ({
+            ...current,
+            showNativeTraceNodes
+        }));
+    }
+    function handleAnnotateTargetFromElement(element) {
+        if (taskStatusRef.current !== "ready") {
+            return false;
+        }
+        const selectableTarget = findSelectableTarget(element, document.body, null, settings.showNativeTraceNodes);
+        const trace = getAnnotateTargetTrace(selectableTarget);
+        if (!selectableTarget || !trace || isInsideAnnotateRoot(selectableTarget.element)) {
+            return false;
+        }
+        const result = registerAnnotateTarget(taskRef.current, { trace });
+        setTargetElementMatches((current) => [
+            ...current.filter((match) => match.targetId !== result.targetId),
+            {
+                targetId: result.targetId,
+                element: selectableTarget.element
+            }
+        ]);
+        openWindow("annotate");
+        commitTask(result.task, "immediate");
+        setActiveTargetId(result.targetId);
+        return true;
+    }
+    function handleActiveTargetChange(targetId) {
+        if (!taskRef.current.targets.some((target) => target.id === targetId)) {
+            return;
+        }
+        setTraceNodeHover(null);
+        setActiveTargetId(targetId);
+    }
+    function handleOpenTarget(targetId) {
+        if (!taskRef.current.targets.some((target) => target.id === targetId)) {
+            return;
+        }
+        setActiveTargetId(targetId);
+        openWindow("annotate");
+    }
+    function handleAddTargetComment(targetId) {
+        const target = taskRef.current.targets.find((candidate) => candidate.id === targetId);
+        if (!target) {
+            return;
+        }
+        commitTask(updateTargetComments(taskRef.current, targetId, [...target.comments, ""]), "immediate");
+    }
+    function handleTargetCommentChange(targetId, index, value) {
+        const target = taskRef.current.targets.find((candidate) => candidate.id === targetId);
+        if (!target) {
+            return;
+        }
+        const comments = target.comments.map((comment, commentIndex) => commentIndex === index ? value : comment);
+        commitTask(updateTargetComments(taskRef.current, targetId, comments), "debounced");
+    }
+    function handleDeleteTargetComment(targetId, index) {
+        const target = taskRef.current.targets.find((candidate) => candidate.id === targetId);
+        if (!target) {
+            return;
+        }
+        const comments = target.comments.filter((_, commentIndex) => commentIndex !== index);
+        commitTask(updateTargetComments(taskRef.current, targetId, comments), "immediate");
+    }
+    function handleDeleteTarget(targetId) {
+        const targetIndex = taskRef.current.targets.findIndex((target) => target.id === targetId);
+        if (targetIndex < 0) {
+            return;
+        }
+        const nextTargets = taskRef.current.targets.filter((target) => target.id !== targetId);
+        const nextActiveTarget = nextTargets[Math.min(targetIndex, nextTargets.length - 1)] ??
+            nextTargets[targetIndex - 1] ??
+            null;
+        setActiveTargetId((currentActiveTargetId) => currentActiveTargetId === targetId ? nextActiveTarget?.id ?? null : currentActiveTargetId);
+        setTraceNodeHover((currentHover) => currentHover?.targetId === targetId ? null : currentHover);
+        setTargetElementMatches((current) => current.filter((match) => match.targetId !== targetId));
+        commitTask(deleteTarget(taskRef.current, targetId), "immediate");
+    }
+    function handleResetTargets() {
+        if (taskRef.current.targets.length === 0) {
+            return;
+        }
+        setActiveTargetId(null);
+        setTraceNodeHover(null);
+        setTargetElementMatches([]);
+        commitTask(deleteAllTargets(taskRef.current), "immediate");
+    }
+    function handleAnnotateTraceNodeHover(targetId, node) {
+        setTraceNodeHover(node ? { source: "annotate", targetId, node } : null);
+    }
+    async function handleOpenCodeFromElement(element, mode = "element") {
+        if (mode === "frozen-first" && frozenHoverTargetRef.current) {
+            await handleOpenCodePath(frozenHoverTargetRef.current.path);
+            return true;
+        }
+        const selectableTarget = findSelectableTarget(element, document.body, null, settings.showNativeTraceNodes);
+        if (!selectableTarget) {
+            return false;
+        }
+        await handleOpenCodePath(selectableTarget.path);
+        return true;
+    }
+    async function handleOpenCodeFromElementAndExitAnnotate(element, mode) {
+        if (await handleOpenCodeFromElement(element, mode)) {
+            setAnnotateMode(false);
+        }
+    }
+    async function handleOpenCodePath(path) {
+        const response = await fetch("/__ui-annotate/code/open", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ path })
+        });
+        if (!response.ok) {
+            throw new Error(`UI Annotate code open failed with ${response.status}.`);
+        }
+    }
+    function handleGetAnnotateTraceNodeElement(targetId, node) {
+        const target = taskRef.current.targets.find((candidate) => candidate.id === targetId);
+        if (!target) {
+            return null;
+        }
+        return findElementForTraceNode(document.body, target, node, null, settings.showNativeTraceNodes);
+    }
+    const overlayHighlights = useMemo(() => {
+        const highlights = [];
+        const targetsById = new Map(task.targets.map((target) => [target.id, target]));
+        for (const match of targetElementMatches) {
+            const target = targetsById.get(match.targetId);
+            if (!target || isInsideAnnotateRoot(match.element)) {
+                continue;
+            }
+            highlights.push({
+                key: `annotate:${target.id}`,
+                element: match.element,
+                intent: "selected",
+                role: "target-primary",
+                label: target.id,
+                targetId: target.id,
+                comments: getVisibleComments(target.comments)
+            });
+        }
+        if (annotateMode && activeHoverTarget && !isInsideAnnotateRoot(activeHoverTarget.element)) {
+            const activeHoverTrace = getAnnotateTargetTrace(activeHoverTarget);
+            if (activeHoverTrace) {
+                const knownTarget = task.targets.find((target) => isSameTargetTrace(target.trace, activeHoverTrace));
+                highlights.push({
+                    key: "hover",
+                    element: activeHoverTarget.element,
+                    intent: "active",
+                    role: "annotate-hover",
+                    label: knownTarget?.id,
+                    ...(knownTarget
+                        ? {
+                            targetId: knownTarget.id,
+                            comments: getVisibleComments(knownTarget.comments)
+                        }
+                        : {})
+                });
+            }
+        }
+        if (traceNodeHover) {
+            const element = handleGetAnnotateTraceNodeElement(traceNodeHover.targetId, traceNodeHover.node);
+            if (element && !isInsideAnnotateRoot(element)) {
+                highlights.push({
+                    key: `trace-hover:${traceNodeHover.targetId}:${traceNodeHover.node.kind}:${traceNodeHover.node.frameIndex}:${traceNodeHover.node.kind === "call" ? traceNodeHover.node.callIndex : "file"}`,
+                    element,
+                    intent: "active",
+                    role: "annotate-hover",
+                    label: traceNodeHover.targetId
+                });
+            }
+        }
+        return highlights;
+    }, [
+        activeHoverTarget,
+        annotateMode,
+        settings.showNativeTraceNodes,
+        targetElementMatches,
+        task.targets,
+        traceNodeHover
+    ]);
+    return (_jsx(PortalContainerProvider, { container: portalContainer, zIndex: ANNOTATE_PORTAL_Z_INDEX, children: _jsx(TooltipProvider, { children: _jsxs("div", { className: showCodeOpenCursor
+                    ? "ui-annotate-root pointer-events-none !cursor-pointer text-foreground [&_*]:!cursor-pointer"
+                    : "ui-annotate-root pointer-events-none text-foreground", children: [_jsx(SelectionOverlay, { highlights: overlayHighlights, onEditTarget: handleOpenTarget, onDeleteAnnotateTarget: handleDeleteTarget }), _jsx(AnnotateToolbar, { annotateMode: annotateMode, position: toolbarPosition, onBeginDrag: beginToolbarDrag, onToggleAnnotateMode: toggleAnnotateModeFromToolbar, onOpenWindow: openWindow }), _jsx(AnnotateWindows, { activeTargetId: activeAnnotateTarget?.id ?? null, saveError: saveError, saveStatus: saveStatus, settings: settings, targets: task.targets, taskError: taskError, taskStatus: taskStatus, windows: windows, onActiveTargetChange: handleActiveTargetChange, onAddComment: handleAddTargetComment, onBeginMove: beginWindowMove, onBeginResize: beginWindowResize, onChangeComment: handleTargetCommentChange, onClose: closeWindow, onDeleteComment: handleDeleteTargetComment, onDeleteTarget: handleDeleteTarget, onResetTargets: handleResetTargets, onGetAnnotateTraceNodeElement: handleGetAnnotateTraceNodeElement, onHoverAnnotateTraceNode: handleAnnotateTraceNodeHover, onOpenCodePath: (path) => void handleOpenCodePath(path), onShowNativeTraceNodesChange: handleShowNativeTraceNodesChange })] }) }) }));
+}
+function getAnnotateTargetTrace(target) {
+    return target?.annotateTrace ?? target?.trace ?? null;
+}
+function getVisibleComments(comments) {
+    return comments.map((comment) => comment.trim()).filter(Boolean);
+}
+function createTargetMatchKey(targets) {
+    return targets
+        .map((target) => `${target.id}:${JSON.stringify(target.trace)}`)
+        .join("|");
+}
+const CODE_OPEN_CURSOR_STYLE_ID = "ui-annotate-code-open-cursor-style";
+function ensureCodeOpenCursorStyle() {
+    const existingStyle = document.getElementById(CODE_OPEN_CURSOR_STYLE_ID);
+    if (existingStyle instanceof HTMLStyleElement) {
+        return existingStyle;
+    }
+    const styleElement = document.createElement("style");
+    styleElement.id = CODE_OPEN_CURSOR_STYLE_ID;
+    styleElement.textContent = "body, body * { cursor: pointer !important; }";
+    document.head.append(styleElement);
+    return styleElement;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,5 @@
+export { UiAnnotate } from "./app/UiAnnotate.js";
+export { AnnotateWindow } from "./windows/AnnotateWindow.js";
+export { TargetTraceTree } from "./windows/TargetTraceTree.js";
+export type { TraceNodeElementResolver } from "./windows/TargetTraceTree.js";
+export * from "./shared/annotate-types.js";

package/dist/runtime/index.js

@@ -0,0 +1,4 @@
+export { UiAnnotate } from "./app/UiAnnotate.js";
+export { AnnotateWindow } from "./windows/AnnotateWindow.js";
+export { TargetTraceTree } from "./windows/TargetTraceTree.js";
+export * from "./shared/annotate-types.js";

package/dist/runtime/inspector/target-inspection.d.ts

@@ -0,0 +1,10 @@
+import { type AnnotateTarget, type TraceFrame, type TraceNodeRef } from "../../protocol/task-model.js";
+import type { SelectableTarget } from "../shared/annotate-types.js";
+export declare function findSelectableTarget(start: Element, previewRoot: HTMLElement, annotateFile: string | null, showNativeTraceNodes: boolean): SelectableTarget | null;
+export declare function createTraceFromSelectableTarget(target: SelectableTarget): TraceFrame[] | null;
+export declare function createTargetName(target: SelectableTarget): string;
+export declare function findElementForTarget(previewRoot: HTMLElement, target: AnnotateTarget, annotateFile: string | null, showNativeTraceNodes: boolean): Element | null;
+export declare function findElementForTraceNode(previewRoot: HTMLElement, target: AnnotateTarget, node: TraceNodeRef, annotateFile: string | null, showNativeTraceNodes: boolean): Element | null;
+export declare function findElementForTraceNodeInTrace(previewRoot: HTMLElement, trace: TraceFrame[], node: TraceNodeRef, annotateFile: string | null, showNativeTraceNodes: boolean, contextElement?: Element): Element | null;
+export declare function getHighlightRole(annotateFile: string, target: AnnotateTarget): "target-primary";
+export declare function isEditableEventTarget(target: EventTarget | null): boolean;