@ui-annotate/react-vite 0.1.0

package/dist/runtime/overlay/SelectionOverlay.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useState } from "react";
+import { MessageSquareIcon, Trash2Icon } from "lucide-react";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../ui/components/tooltip.js";
+import { cn } from "../../ui/lib/utils.js";
+const highlightRoleClasses = {
+    "target-primary": "border-ui-annotate-highlight-target",
+    "trace-node": "border-ui-annotate-highlight-trace",
+    "annotate-hover": "border-ui-annotate-highlight-annotate"
+};
+const highlightIntentClasses = {
+    selected: "opacity-ui-annotate-highlight-selected",
+    active: "opacity-100 shadow-ui-annotate-highlight-active"
+};
+const activeHighlightRoleClasses = {
+    "target-primary": "shadow-ui-annotate-highlight-target-active",
+    "trace-node": "shadow-ui-annotate-highlight-trace-active",
+    "annotate-hover": "shadow-ui-annotate-highlight-annotate-active"
+};
+const highlightLabelRoleClasses = {
+    "target-primary": "bg-ui-annotate-highlight-target",
+    "trace-node": "bg-ui-annotate-highlight-trace",
+    "annotate-hover": "bg-ui-annotate-highlight-annotate"
+};
+const commentIconColor = "#451a03";
+export function SelectionOverlay({ highlights, onEditTarget, onDeleteAnnotateTarget }) {
+    const [rects, setRects] = useState([]);
+    useLayoutEffect(() => {
+        let frameId = 0;
+        const updateRects = () => {
+            frameId = 0;
+            const nextRects = [];
+            for (const highlight of highlights) {
+                const rect = highlight.element.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0) {
+                    continue;
+                }
+                nextRects.push({
+                    key: highlight.key,
+                    ...(highlight.label ? { label: highlight.label } : {}),
+                    ...(highlight.targetId ? { targetId: highlight.targetId } : {}),
+                    ...(highlight.comments ? { comments: highlight.comments } : {}),
+                    role: highlight.role,
+                    intent: highlight.intent,
+                    top: rect.top,
+                    left: rect.left,
+                    width: rect.width,
+                    height: rect.height
+                });
+            }
+            setRects(nextRects);
+        };
+        const scheduleUpdate = () => {
+            if (frameId) {
+                return;
+            }
+            frameId = window.requestAnimationFrame(updateRects);
+        };
+        updateRects();
+        window.addEventListener("scroll", scheduleUpdate, true);
+        window.addEventListener("resize", scheduleUpdate);
+        return () => {
+            if (frameId) {
+                window.cancelAnimationFrame(frameId);
+            }
+            window.removeEventListener("scroll", scheduleUpdate, true);
+            window.removeEventListener("resize", scheduleUpdate);
+        };
+    }, [highlights]);
+    if (rects.length === 0) {
+        return null;
+    }
+    return (_jsx("div", { className: "pointer-events-none fixed inset-0 z-[9998]", children: rects.map((rect) => (_jsx("div", { className: cn("fixed rounded-md border-2 border-ring shadow-ui-annotate-highlight", highlightRoleClasses[rect.role], highlightIntentClasses[rect.intent], rect.intent === "active" && activeHighlightRoleClasses[rect.role]), style: {
+                top: rect.top,
+                left: rect.left,
+                width: rect.width,
+                height: rect.height
+            }, children: rect.label ? (_jsxs("span", { className: cn("absolute -top-ui-annotate-highlight-label-top -left-0.5 inline-flex min-w-7 items-center gap-1 rounded-md rounded-bl-none bg-ring px-ui-annotate-highlight-label-x py-ui-annotate-highlight-label-y text-xs leading-ui-annotate-highlight-label font-bold text-primary-foreground shadow-ui-annotate-highlight-label", highlightLabelRoleClasses[rect.role]), children: [rect.label, rect.targetId ? (_jsxs("span", { className: "pointer-events-auto ml-1 inline-flex items-center gap-0.5", "aria-label": `${rect.targetId} tools`, children: [_jsx(CommentTooltip, { comments: rect.comments ?? [], children: _jsx("button", { type: "button", className: "inline-flex shrink-0 items-center justify-center rounded-[3px] border-0 p-0 hover:bg-ui-annotate-highlight-toolbar-hover", style: {
+                                        width: "var(--spacing-ui-annotate-highlight-toolbar-button)",
+                                        height: "var(--spacing-ui-annotate-highlight-toolbar-button)"
+                                    }, "aria-label": `Open ${rect.targetId} target comments`, onClick: () => onEditTarget(rect.targetId), children: _jsx(MessageSquareIcon, { style: {
+                                            width: "var(--spacing-ui-annotate-highlight-toolbar-icon)",
+                                            height: "var(--spacing-ui-annotate-highlight-toolbar-icon)",
+                                            ...(rect.comments?.length ? { color: commentIconColor } : {})
+                                        }, "data-icon": "inline-start", "aria-hidden": "true" }) }) }), _jsx("button", { type: "button", className: "inline-flex shrink-0 items-center justify-center rounded-[3px] border-0 p-0 hover:bg-ui-annotate-highlight-toolbar-hover", style: {
+                                    width: "var(--spacing-ui-annotate-highlight-toolbar-button)",
+                                    height: "var(--spacing-ui-annotate-highlight-toolbar-button)"
+                                }, "aria-label": `Delete ${rect.targetId}`, onClick: () => onDeleteAnnotateTarget(rect.targetId), children: _jsx(Trash2Icon, { style: {
+                                        width: "var(--spacing-ui-annotate-highlight-toolbar-icon)",
+                                        height: "var(--spacing-ui-annotate-highlight-toolbar-icon)"
+                                    }, "data-icon": "inline-start", "aria-hidden": "true" }) })] })) : null] })) : null }, rect.key))) }));
+}
+function CommentTooltip({ children, comments }) {
+    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: children }), _jsx(TooltipContent, { side: "top", className: "max-w-72 p-2 text-left text-xs leading-5 text-background", children: comments.length > 0 ? (_jsx("ol", { className: "m-0 flex list-decimal flex-col gap-1 pl-4", children: comments.map((comment, index) => (_jsx("li", { className: "whitespace-pre-wrap break-words", children: comment }, `${index}:${comment}`))) })) : (_jsx("span", { children: "No comments yet." })) })] }));
+}

package/dist/runtime/shared/annotate-constants.d.ts

@@ -0,0 +1,13 @@
+export declare const ANNOTATE_ROOT_ID = "__ui_annotate_root__";
+export declare const INSPECTOR_ATTRIBUTE = "data-ui-annotate-inspector";
+export declare const ANNOTATE_WINDOW_STORAGE_KEY = "ui-annotate.windows.v1";
+export declare const ANNOTATE_TOOLBAR_STORAGE_KEY = "ui-annotate.toolbar.v1";
+export declare const ANNOTATE_SETTINGS_STORAGE_KEY = "ui-annotate.settings.v1";
+export declare const SAVE_DEBOUNCE_MS = 650;
+export declare const TOOLBAR_WIDTH = 112;
+export declare const TOOLBAR_HEIGHT = 48;
+export declare const WINDOW_MIN_WIDTH = 320;
+export declare const WINDOW_MIN_HEIGHT = 260;
+export declare const WINDOW_VIEWPORT_MARGIN = 8;
+export declare const WINDOW_MAX_SIZE_INSET = 24;
+export declare const ANNOTATE_PORTAL_Z_INDEX = 2147483647;

package/dist/runtime/shared/annotate-constants.js

@@ -0,0 +1,13 @@
+export const ANNOTATE_ROOT_ID = "__ui_annotate_root__";
+export const INSPECTOR_ATTRIBUTE = "data-ui-annotate-inspector";
+export const ANNOTATE_WINDOW_STORAGE_KEY = "ui-annotate.windows.v1";
+export const ANNOTATE_TOOLBAR_STORAGE_KEY = "ui-annotate.toolbar.v1";
+export const ANNOTATE_SETTINGS_STORAGE_KEY = "ui-annotate.settings.v1";
+export const SAVE_DEBOUNCE_MS = 650;
+export const TOOLBAR_WIDTH = 112;
+export const TOOLBAR_HEIGHT = 48;
+export const WINDOW_MIN_WIDTH = 320;
+export const WINDOW_MIN_HEIGHT = 260;
+export const WINDOW_VIEWPORT_MARGIN = 8;
+export const WINDOW_MAX_SIZE_INSET = 24;
+export const ANNOTATE_PORTAL_Z_INDEX = 2147483647;

package/dist/runtime/shared/annotate-types.d.ts

@@ -0,0 +1,36 @@
+import type { TraceFrame, TraceNodeRef } from "../../protocol/task-model.js";
+import type { AnnotateWindowFrameState } from "../windows/AnnotateWindowFrame.js";
+export type SelectableTarget = {
+    element: Element;
+    path: string;
+    name: string;
+    elementName: string;
+    trace?: TraceFrame[];
+    annotateTrace?: TraceFrame[];
+};
+export type HighlightIntent = "selected" | "active";
+export type OverlayHighlightRole = "target-primary" | "trace-node" | "annotate-hover";
+export type OverlayHighlight = {
+    key: string;
+    element: Element;
+    intent: HighlightIntent;
+    role: OverlayHighlightRole;
+    label?: string;
+    targetId?: string;
+    comments?: string[];
+};
+export type AnnotateWindowId = "annotate" | "settings";
+export type AnnotateWindowState = AnnotateWindowFrameState;
+export type AnnotateWindowMap = Record<AnnotateWindowId, AnnotateWindowState>;
+export type AnnotateSettings = {
+    showNativeTraceNodes: boolean;
+};
+export type TraceNodeHover = {
+    source: "annotate";
+    targetId: string;
+    node: TraceNodeRef;
+};
+export type ToolbarPosition = {
+    x: number;
+    y: number;
+};

package/dist/runtime/shared/annotate-types.js

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

package/dist/runtime/shared/clipboard.d.ts

@@ -0,0 +1 @@
+export declare function writeClipboardText(text: string): Promise<boolean>;

package/dist/runtime/shared/clipboard.js

@@ -0,0 +1,33 @@
+export async function writeClipboardText(text) {
+    if (window.navigator.clipboard) {
+        try {
+            await window.navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            // Fall through to the textarea fallback for older or restricted contexts.
+        }
+    }
+    return writeClipboardTextWithTextarea(text);
+}
+function writeClipboardTextWithTextarea(text) {
+    if (typeof document.execCommand !== "function") {
+        return false;
+    }
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.top = "-9999px";
+    document.body.append(textarea);
+    textarea.select();
+    try {
+        return document.execCommand("copy");
+    }
+    catch {
+        return false;
+    }
+    finally {
+        textarea.remove();
+    }
+}

package/dist/runtime/style.css

@@ -0,0 +1,206 @@
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./**/*.{js,ts,tsx}";
+@source "../ui/**/*.{js,ts,tsx}";
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-ui-annotate-highlight-target: oklch(0.627 0.194 149.214);
+  --color-ui-annotate-highlight-context: oklch(0.623 0.214 259.815);
+  --color-ui-annotate-highlight-trace: oklch(0.704 0.191 47.604);
+  --color-ui-annotate-highlight-annotate: oklch(0.656 0.241 354.308);
+  --color-ui-annotate-highlight-toolbar-hover: color-mix(in oklab, var(--foreground) 24%, transparent);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --shadow-ui-annotate-highlight: 0 0 0 2px color-mix(in oklab, var(--background) 74%, transparent);
+  --shadow-ui-annotate-highlight-active: 0 0 0 2px color-mix(in oklab, var(--background) 82%, transparent), 0 0 0 5px color-mix(in oklab, var(--ring) 20%, transparent);
+  --shadow-ui-annotate-highlight-target-active: 0 0 0 2px color-mix(in oklab, var(--background) 82%, transparent), 0 0 0 5px color-mix(in oklab, var(--color-ui-annotate-highlight-target) 22%, transparent);
+  --shadow-ui-annotate-highlight-trace-active: 0 0 0 2px color-mix(in oklab, var(--background) 82%, transparent), 0 0 0 5px color-mix(in oklab, var(--color-ui-annotate-highlight-trace) 24%, transparent);
+  --shadow-ui-annotate-highlight-annotate-active: 0 0 0 2px color-mix(in oklab, var(--background) 82%, transparent), 0 0 0 5px color-mix(in oklab, var(--color-ui-annotate-highlight-annotate) 24%, transparent);
+  --shadow-ui-annotate-highlight-label: 0 8px 20px color-mix(in oklab, var(--foreground) 18%, transparent);
+  --spacing-ui-annotate-highlight-label-top: 23px;
+  --spacing-ui-annotate-highlight-label-x: 7px;
+  --spacing-ui-annotate-highlight-label-y: 3px;
+  --spacing-ui-annotate-highlight-toolbar-button: 18px;
+  --spacing-ui-annotate-highlight-toolbar-icon: 11px;
+  --opacity-ui-annotate-highlight-selected: 0.62;
+  --leading-ui-annotate-highlight-label: 1.2;
+}
+
+#__ui_annotate_root__,
+:host {
+  --background: oklch(0.985 0.002 247.839);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.5rem;
+  color-scheme: light;
+}
+
+@layer base {
+  :host,
+  :host *,
+  :host ::before,
+  :host ::after,
+  :host ::backdrop,
+  :host ::file-selector-button,
+  #__ui_annotate_root__,
+  #__ui_annotate_root__ *,
+  #__ui_annotate_root__ ::before,
+  #__ui_annotate_root__ ::after,
+  #__ui_annotate_root__ ::backdrop,
+  #__ui_annotate_root__ ::file-selector-button {
+    box-sizing: border-box;
+    border: 0 solid;
+    margin: 0;
+    padding: 0;
+  }
+
+  :host,
+  :host *,
+  #__ui_annotate_root__,
+  #__ui_annotate_root__ * {
+    @apply border-border outline-ring/50;
+  }
+
+  :host,
+  #__ui_annotate_root__ {
+    @apply text-foreground;
+    font-family:
+      Inter,
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      BlinkMacSystemFont,
+      "Segoe UI",
+      sans-serif;
+  }
+
+  :host button,
+  :host input,
+  :host select,
+  :host optgroup,
+  :host textarea,
+  :host ::file-selector-button,
+  #__ui_annotate_root__ button,
+  #__ui_annotate_root__ input,
+  #__ui_annotate_root__ select,
+  #__ui_annotate_root__ optgroup,
+  #__ui_annotate_root__ textarea,
+  #__ui_annotate_root__ ::file-selector-button {
+    font: inherit;
+    font-feature-settings: inherit;
+    font-variation-settings: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    border-radius: 0;
+    background-color: transparent;
+    opacity: 1;
+  }
+
+  :host button,
+  :host input:where([type="button"], [type="reset"], [type="submit"]),
+  :host ::file-selector-button,
+  #__ui_annotate_root__ button,
+  #__ui_annotate_root__ input:where([type="button"], [type="reset"], [type="submit"]),
+  #__ui_annotate_root__ ::file-selector-button {
+    appearance: button;
+  }
+
+  :host button,
+  #__ui_annotate_root__ button {
+    cursor: pointer;
+  }
+
+  :host button:disabled,
+  #__ui_annotate_root__ button:disabled {
+    cursor: not-allowed;
+  }
+
+  :host code,
+  #__ui_annotate_root__ code {
+    font-family:
+      "SFMono-Regular",
+      Consolas,
+      "Liberation Mono",
+      monospace;
+  }
+
+  :host ol,
+  :host ul,
+  :host menu,
+  #__ui_annotate_root__ ol,
+  #__ui_annotate_root__ ul,
+  #__ui_annotate_root__ menu {
+    list-style: none;
+  }
+
+  :host img,
+  :host svg,
+  :host video,
+  :host canvas,
+  :host audio,
+  :host iframe,
+  :host embed,
+  :host object,
+  #__ui_annotate_root__ img,
+  #__ui_annotate_root__ svg,
+  #__ui_annotate_root__ video,
+  #__ui_annotate_root__ canvas,
+  #__ui_annotate_root__ audio,
+  #__ui_annotate_root__ iframe,
+  #__ui_annotate_root__ embed,
+  #__ui_annotate_root__ object {
+    display: block;
+    vertical-align: middle;
+  }
+
+  :host img,
+  :host video,
+  #__ui_annotate_root__ img,
+  #__ui_annotate_root__ video {
+    max-width: 100%;
+    height: auto;
+  }
+
+  :host [hidden]:where(:not([hidden="until-found"])),
+  #__ui_annotate_root__ [hidden]:where(:not([hidden="until-found"])) {
+    display: none !important;
+  }
+}

package/dist/runtime/task/annotate-task.d.ts

@@ -0,0 +1,16 @@
+import { type AnnotateTaskFile, type TraceFrame } from "../../protocol/task-model.js";
+export type AnnotateTargetInput = {
+    trace: TraceFrame[];
+};
+export type RegisterAnnotateTargetResult = {
+    task: AnnotateTaskFile;
+    targetId: string;
+    targetCreated: boolean;
+};
+export declare const EMPTY_ANNOTATE_TASK_FILE: AnnotateTaskFile;
+export declare function loadAnnotateTask(): Promise<AnnotateTaskFile>;
+export declare function saveAnnotateTask(task: AnnotateTaskFile): Promise<AnnotateTaskFile>;
+export declare function registerAnnotateTarget(task: AnnotateTaskFile, target: AnnotateTargetInput): RegisterAnnotateTargetResult;
+export declare function updateTargetComments(task: AnnotateTaskFile, targetId: string, comments: string[]): AnnotateTaskFile;
+export declare function deleteTarget(task: AnnotateTaskFile, targetId: string): AnnotateTaskFile;
+export declare function deleteAllTargets(task: AnnotateTaskFile): AnnotateTaskFile;

package/dist/runtime/task/annotate-task.js

@@ -0,0 +1,85 @@
+import { getNextTargetId } from "../../protocol/index.js";
+import { isSameTargetTrace } from "../../protocol/task-model.js";
+import { ANNOTATE_TASK_AGENT_INSTRUCTIONS } from "../../protocol/constants.js";
+export const EMPTY_ANNOTATE_TASK_FILE = {
+    agentInstructions: [...ANNOTATE_TASK_AGENT_INSTRUCTIONS],
+    targets: []
+};
+export async function loadAnnotateTask() {
+    return readAnnotateTaskResponse(await fetch("/__ui-annotate/annotate-task"));
+}
+export async function saveAnnotateTask(task) {
+    return readAnnotateTaskResponse(await fetch("/__ui-annotate/annotate-task", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(task)
+    }));
+}
+export function registerAnnotateTarget(task, target) {
+    const existingTarget = task.targets.find((candidate) => isSameTargetTrace(candidate.trace, target.trace));
+    if (existingTarget) {
+        return {
+            task,
+            targetId: existingTarget.id,
+            targetCreated: false
+        };
+    }
+    const targetId = getNextTargetId(task.targets);
+    const nextTarget = {
+        id: targetId,
+        comments: [],
+        trace: target.trace.map(cloneTraceFrame)
+    };
+    return {
+        task: {
+            ...task,
+            targets: [...task.targets, nextTarget]
+        },
+        targetId,
+        targetCreated: true
+    };
+}
+export function updateTargetComments(task, targetId, comments) {
+    return {
+        ...task,
+        targets: task.targets.map((target) => target.id === targetId ? { ...target, comments: [...comments] } : target)
+    };
+}
+export function deleteTarget(task, targetId) {
+    return {
+        ...task,
+        targets: task.targets.filter((target) => target.id !== targetId)
+    };
+}
+export function deleteAllTargets(task) {
+    return {
+        ...task,
+        targets: []
+    };
+}
+function cloneTraceFrame(frame) {
+    return {
+        ...frame,
+        calls: frame.calls.map((call) => ({ ...call }))
+    };
+}
+async function readAnnotateTaskResponse(response) {
+    if (!response.ok) {
+        throw new Error(await readErrorMessage(response));
+    }
+    return (await response.json());
+}
+async function readErrorMessage(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.error === "string") {
+            return body.error;
+        }
+    }
+    catch {
+        // JSON parse failed; fall back to the generic status message.
+    }
+    return `UI Annotate task request failed with ${response.status}.`;
+}

package/dist/runtime/task/use-annotate-task.d.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from "react";
+import type { AnnotateTaskFile } from "../../protocol/index.js";
+import type { SaveStatus, TaskStatus } from "../windows/window-shared.js";
+type UseAnnotateTaskResult = {
+    commitTask: (nextTask: AnnotateTaskFile, mode: "debounced" | "immediate") => void;
+    flushTaskSave: () => Promise<boolean>;
+    saveError: string | null;
+    saveStatus: SaveStatus;
+    task: AnnotateTaskFile;
+    taskError: string | null;
+    taskRef: RefObject<AnnotateTaskFile>;
+    taskStatus: TaskStatus;
+    taskStatusRef: RefObject<TaskStatus>;
+};
+export declare function useAnnotateTask(): UseAnnotateTaskResult;
+export {};

package/dist/runtime/task/use-annotate-task.js

@@ -0,0 +1,115 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { SAVE_DEBOUNCE_MS } from "../shared/annotate-constants.js";
+import { EMPTY_ANNOTATE_TASK_FILE, loadAnnotateTask, saveAnnotateTask } from "./annotate-task.js";
+export function useAnnotateTask() {
+    const [taskStatus, setTaskStatus] = useState("loading");
+    const [task, setTask] = useState(EMPTY_ANNOTATE_TASK_FILE);
+    const [saveStatus, setSaveStatus] = useState("idle");
+    const [saveError, setSaveError] = useState(null);
+    const [taskError, setTaskError] = useState(null);
+    const saveTimerRef = useRef(null);
+    const saveSequenceRef = useRef(0);
+    const taskRef = useRef(task);
+    const taskStatusRef = useRef(taskStatus);
+    useEffect(() => {
+        let cancelled = false;
+        setTaskStatus("loading");
+        setTaskError(null);
+        setSaveStatus("idle");
+        setSaveError(null);
+        const loadTask = async () => {
+            try {
+                const loadedTask = await loadAnnotateTask();
+                if (cancelled) {
+                    return;
+                }
+                setTask(loadedTask);
+                taskRef.current = loadedTask;
+                setTaskStatus("ready");
+            }
+            catch (error) {
+                if (cancelled) {
+                    return;
+                }
+                setTaskStatus("error");
+                setTaskError(error instanceof Error ? error.message : "Failed to load annotate task file.");
+            }
+        };
+        void loadTask();
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    useEffect(() => {
+        taskRef.current = task;
+    }, [task]);
+    useEffect(() => {
+        taskStatusRef.current = taskStatus;
+    }, [taskStatus]);
+    const performSave = useCallback(async (nextTask) => {
+        const saveSequence = saveSequenceRef.current + 1;
+        saveSequenceRef.current = saveSequence;
+        setSaveStatus("saving");
+        setSaveError(null);
+        try {
+            const savedTask = await saveAnnotateTask(nextTask);
+            if (saveSequenceRef.current !== saveSequence) {
+                return true;
+            }
+            setTask(savedTask);
+            taskRef.current = savedTask;
+            setSaveStatus("saved");
+            return true;
+        }
+        catch (error) {
+            if (saveSequenceRef.current !== saveSequence) {
+                return false;
+            }
+            setSaveStatus("error");
+            setSaveError(error instanceof Error ? error.message : "Failed to save annotate task file.");
+            return false;
+        }
+    }, []);
+    const commitTask = useCallback((nextTask, mode) => {
+        setTask(nextTask);
+        taskRef.current = nextTask;
+        if (saveTimerRef.current !== null) {
+            window.clearTimeout(saveTimerRef.current);
+        }
+        if (mode === "immediate") {
+            void performSave(nextTask);
+            return;
+        }
+        setSaveStatus("dirty");
+        setSaveError(null);
+        saveTimerRef.current = window.setTimeout(() => {
+            saveTimerRef.current = null;
+            void performSave(taskRef.current);
+        }, SAVE_DEBOUNCE_MS);
+    }, [performSave]);
+    const flushTaskSave = useCallback(async () => {
+        if (saveTimerRef.current !== null) {
+            window.clearTimeout(saveTimerRef.current);
+            saveTimerRef.current = null;
+        }
+        return performSave(taskRef.current);
+    }, [performSave]);
+    useEffect(() => {
+        return () => {
+            if (saveTimerRef.current !== null) {
+                window.clearTimeout(saveTimerRef.current);
+            }
+        };
+    }, []);
+    return {
+        commitTask,
+        flushTaskSave,
+        saveError,
+        saveStatus,
+        task,
+        taskError,
+        taskRef,
+        taskStatus,
+        taskStatusRef
+    };
+}

package/dist/runtime/windows/AnnotateSettingsWindow.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+import type { AnnotateSettings } from "../shared/annotate-types.js";
+export declare function AnnotateSettingsWindow({ settings, onShowNativeTraceNodesChange }: {
+    settings: AnnotateSettings;
+    onShowNativeTraceNodesChange(value: boolean): void;
+}): ReactNode;

package/dist/runtime/windows/AnnotateSettingsWindow.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Switch } from "../../ui/components/switch.js";
+export function AnnotateSettingsWindow({ settings, onShowNativeTraceNodesChange }) {
+    return (_jsx("div", { className: "flex flex-col gap-3 text-sm", children: _jsxs("label", { className: "flex items-center justify-between gap-3 rounded-md border bg-background p-3", children: [_jsx("span", { className: "min-w-0 font-medium text-foreground", children: "Show native trace nodes" }), _jsx(Switch, { checked: settings.showNativeTraceNodes, onCheckedChange: onShowNativeTraceNodesChange })] }) }));
+}

package/dist/runtime/windows/AnnotateWindow.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+import type { AnnotateTarget, TraceNodeRef } from "../../protocol/task-model.js";
+import { type TraceNodeElementResolver } from "./TargetTraceTree.js";
+import { type SaveStatus, type TaskStatus } from "./window-shared.js";
+export declare function AnnotateWindow({ activeTargetId, saveError, saveStatus, targets, taskError, taskStatus, getTraceNodeElement, onActiveTargetChange, onAddComment, onChangeComment, onDeleteComment, onDeleteTarget, onHoverTraceNode, onOpenPath, onResetTargets }: {
+    activeTargetId: string | null;
+    saveError: string | null;
+    saveStatus: SaveStatus;
+    targets: AnnotateTarget[];
+    taskError: string | null;
+    taskStatus: TaskStatus;
+    getTraceNodeElement(targetId: string): TraceNodeElementResolver;
+    onActiveTargetChange(targetId: string): void;
+    onAddComment(targetId: string): void;
+    onChangeComment(targetId: string, index: number, value: string): void;
+    onDeleteComment(targetId: string, index: number): void;
+    onDeleteTarget(targetId: string): void;
+    onHoverTraceNode(targetId: string, node: TraceNodeRef | null): void;
+    onOpenPath(path: string): void;
+    onResetTargets(): void;
+}): ReactNode;