@ui-annotate/react-vite 0.1.0

package/dist/code-open.d.ts

@@ -0,0 +1,17 @@
+export type OpenCodeRequest = {
+    path: string;
+};
+export type OpenCodeResponse = {
+    path: string;
+    absolutePath: string;
+};
+export type CodeGotoLocation = {
+    relativePath: string;
+    absolutePath: string;
+    line: number;
+    column: number;
+    gotoArg: string;
+};
+export declare function openCodeLocation(root: string, request: unknown): Promise<OpenCodeResponse>;
+export declare function validateOpenCodeRequest(input: unknown): OpenCodeRequest;
+export declare function resolveCodeGotoLocation(root: string, sourcePath: string): CodeGotoLocation;

package/dist/code-open.js

@@ -0,0 +1,82 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { normalizeProjectRelativePath } from "./protocol/index.js";
+export async function openCodeLocation(root, request) {
+    const body = validateOpenCodeRequest(request);
+    const location = resolveCodeGotoLocation(root, body.path);
+    await runCodeGoto(location.gotoArg);
+    return {
+        path: `${location.relativePath}:${location.line}:${location.column}`,
+        absolutePath: location.absolutePath
+    };
+}
+export function validateOpenCodeRequest(input) {
+    if (!isRecord(input)) {
+        throw new Error("Code open body must be a JSON object.");
+    }
+    return {
+        path: requireString(input.path, "path")
+    };
+}
+export function resolveCodeGotoLocation(root, sourcePath) {
+    const match = /^(.*):(\d+):(\d+)$/.exec(sourcePath);
+    if (!match) {
+        throw new Error('path must use "relative/path.tsx:line:column" format.');
+    }
+    const relativePath = normalizeProjectRelativePath(match[1] ?? "");
+    const line = requirePositiveInteger(Number.parseInt(match[2] ?? "0", 10), "path line");
+    const column = requirePositiveInteger(Number.parseInt(match[3] ?? "0", 10), "path column");
+    const absoluteRoot = path.resolve(root);
+    const absolutePath = path.resolve(absoluteRoot, relativePath);
+    const relativeFromRoot = path.relative(absoluteRoot, absolutePath);
+    if (relativeFromRoot.startsWith("..") || path.isAbsolute(relativeFromRoot)) {
+        throw new Error(`Source file must stay inside the project: ${sourcePath}`);
+    }
+    return {
+        relativePath,
+        absolutePath,
+        line,
+        column,
+        gotoArg: `${absolutePath}:${line}:${column}`
+    };
+}
+function runCodeGoto(gotoArg) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("code", ["--goto", gotoArg], {
+            stdio: "ignore",
+            shell: false
+        });
+        child.on("error", (error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                reject(new Error('Unable to open VS Code. Make sure the "code" command is installed in PATH.'));
+                return;
+            }
+            reject(error);
+        });
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`VS Code exited with status ${code ?? "unknown"}.`));
+        });
+    });
+}
+function requireString(input, label) {
+    if (typeof input !== "string") {
+        throw new Error(`${label} must be a string.`);
+    }
+    return input;
+}
+function requirePositiveInteger(input, label) {
+    if (!Number.isInteger(input) || input < 1) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return input;
+}
+function isRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { UI_ANNOTATE_INSPECTOR_ATTRIBUTE, createUiAnnotateInspectorPlugin, transformUiAnnotateInspectorSource } from "./inspector-transform.js";
+export type { UiAnnotateInspectorPluginOptions, UiAnnotateInspectorTransformOptions, UiAnnotateInspectorTransformResult } from "./inspector-transform.js";
+export { createUiAnnotatePlugin, uiAnnotate } from "./ui-annotate-plugin.js";
+export type { UiAnnotatePluginOptions } from "./ui-annotate-plugin.js";
+export { openCodeLocation, resolveCodeGotoLocation, validateOpenCodeRequest } from "./code-open.js";
+export type { CodeGotoLocation, OpenCodeRequest, OpenCodeResponse } from "./code-open.js";
+export { createAnnotateApiServer, handleUiAnnotateRequest, readAnnotateTask, resolveAnnotateTaskPath, validateAnnotateTaskFile, writeAnnotateTask } from "./task-api.js";
+export type { AnnotateApiServerOptions, AnnotateApiServerResult } from "./task-api.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { UI_ANNOTATE_INSPECTOR_ATTRIBUTE, createUiAnnotateInspectorPlugin, transformUiAnnotateInspectorSource } from "./inspector-transform.js";
+export { createUiAnnotatePlugin, uiAnnotate } from "./ui-annotate-plugin.js";
+export { openCodeLocation, resolveCodeGotoLocation, validateOpenCodeRequest } from "./code-open.js";
+export { createAnnotateApiServer, handleUiAnnotateRequest, readAnnotateTask, resolveAnnotateTaskPath, validateAnnotateTaskFile, writeAnnotateTask } from "./task-api.js";

package/dist/inspector-transform.d.ts

@@ -0,0 +1,59 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const UI_ANNOTATE_INSPECTOR_ATTRIBUTE = "data-ui-annotate-inspector";
+export type UiAnnotateInspectorTransformOptions = {
+    enabled?: boolean;
+    projectRelativePath?: string;
+    root?: string;
+};
+export type UiAnnotateInspectorTransformResult = {
+    code: string;
+    map: null;
+};
+export type UiAnnotateInspectorPluginOptions = {
+    enabled?: boolean;
+    root?: string;
+};
+type ViteConfig = {
+    root: string;
+};
+type VitePluginLike = {
+    name: string;
+    enforce: "pre";
+    apply: "serve";
+    configResolved(config: ViteConfig): void;
+    configureServer(server: ViteDevServerLike): void;
+    transform(code: string, id: string): UiAnnotateInspectorTransformResult | null;
+};
+type ConnectNext = (error?: unknown) => void;
+type ViteDevServerLike = {
+    middlewares: {
+        use(handler: (request: IncomingMessage, response: ServerResponse, next: ConnectNext) => void): void;
+    };
+};
+/**
+ * 创建 Vite 插件，核心职责有两个：
+ *
+ * 1. 拦截 UI Annotate runtime 的 /__ui-annotate/* 请求
+ *    - UI Annotate runtime 通过这些 API 读写 ui.annotate.json 并打开源码位置
+ *
+ * 2. 在 transform 阶段为项目内的每个 JSX 元素注入 data-ui-annotate-inspector 属性
+ *    - 这样 UI Annotate runtime 就能通过 DOM 属性拿到源码定位
+ *    - 注入只在内存 bundle 中进行，不修改磁盘上的源文件
+ *    - 只在 dev server (apply: "serve") 中生效，生产构建完全不执行
+ */
+export declare function createUiAnnotateInspectorPlugin(options?: UiAnnotateInspectorPluginOptions): VitePluginLike;
+/**
+ * 核心转换逻辑：用 TypeScript AST 遍历源码中的所有 JSX 元素，
+ * 为每个元素计算一个形如 "src/components/Button.tsx:12:5" 的定位字符串，
+ * 然后作为 data-ui-annotate-inspector 属性注入到元素的标签上。
+ *
+ * 整体流程：
+ * 1. 判断文件是否属于项目可写源码（排除 node_modules 等）
+ * 2. 解析为 TypeScript AST
+ * 3. 递归访问所有 JSX 元素，收集需要插入属性的位置
+ * 4. 从后往前执行字符串插入，生成最终的代码
+ *
+ * 注意：这里只修改 Vite 内存中的 bundle 输出，不会写入磁盘文件。
+ */
+export declare function transformUiAnnotateInspectorSource(code: string, id: string, options?: UiAnnotateInspectorTransformOptions): UiAnnotateInspectorTransformResult | null;
+export {};

package/dist/inspector-transform.js

@@ -0,0 +1,218 @@
+import path from "node:path";
+import ts from "typescript";
+import { isWritableProjectSource, normalizeProjectRelativePath } from "./protocol/index.js";
+import { handleUiAnnotateRequest } from "./task-api.js";
+// 注入到每个 JSX 元素上的 HTML 属性名，值为 "相对路径:行号:列号" 格式的源码定位信息。
+// UI Annotate runtime 在用户 hover/click 时读取这个属性，就能知道当前元素对应哪一行源码。
+// 这个属性只在 dev server 的内存 bundle 中存在，不会写入真实文件，也不会进入生产构建。
+export const UI_ANNOTATE_INSPECTOR_ATTRIBUTE = "data-ui-annotate-inspector";
+/**
+ * 创建 Vite 插件，核心职责有两个：
+ *
+ * 1. 拦截 UI Annotate runtime 的 /__ui-annotate/* 请求
+ *    - UI Annotate runtime 通过这些 API 读写 ui.annotate.json 并打开源码位置
+ *
+ * 2. 在 transform 阶段为项目内的每个 JSX 元素注入 data-ui-annotate-inspector 属性
+ *    - 这样 UI Annotate runtime 就能通过 DOM 属性拿到源码定位
+ *    - 注入只在内存 bundle 中进行，不修改磁盘上的源文件
+ *    - 只在 dev server (apply: "serve") 中生效，生产构建完全不执行
+ */
+export function createUiAnnotateInspectorPlugin(options = {}) {
+    let root = path.resolve(options.root ?? process.cwd());
+    return {
+        name: "ui-annotate-inspector-transform",
+        enforce: "pre", // 在其他插件（如 @vitejs/plugin-react）之前执行，确保注入的是原始源码位置
+        apply: "serve", // 只在 dev server 生效，生产构建不加载这个插件
+        configResolved(config) {
+            // 优先使用插件选项中的 root，其次使用 Vite 解析出的项目根目录
+            root = path.resolve(options.root ?? config.root);
+        },
+        configureServer(server) {
+            // 挂载中间件：拦截所有 /__ui-annotate/* 路径的 UI Annotate runtime 请求。
+            server.middlewares.use(async (request, response, next) => {
+                const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+                if (!pathname.startsWith("/__ui-annotate/")) {
+                    next();
+                    return;
+                }
+                try {
+                    const handled = await handleUiAnnotateRequest(root, request, response);
+                    if (!handled) {
+                        next();
+                    }
+                }
+                catch (error) {
+                    next(error);
+                }
+            });
+        },
+        transform(code, id) {
+            return transformUiAnnotateInspectorSource(code, id, {
+                enabled: options.enabled,
+                root
+            });
+        }
+    };
+}
+/**
+ * 核心转换逻辑：用 TypeScript AST 遍历源码中的所有 JSX 元素，
+ * 为每个元素计算一个形如 "src/components/Button.tsx:12:5" 的定位字符串，
+ * 然后作为 data-ui-annotate-inspector 属性注入到元素的标签上。
+ *
+ * 整体流程：
+ * 1. 判断文件是否属于项目可写源码（排除 node_modules 等）
+ * 2. 解析为 TypeScript AST
+ * 3. 递归访问所有 JSX 元素，收集需要插入属性的位置
+ * 4. 从后往前执行字符串插入，生成最终的代码
+ *
+ * 注意：这里只修改 Vite 内存中的 bundle 输出，不会写入磁盘文件。
+ */
+export function transformUiAnnotateInspectorSource(code, id, options = {}) {
+    if (options.enabled === false) {
+        return null;
+    }
+    const relativePath = resolveInspectableRelativePath(id, options);
+    if (!relativePath) {
+        return null;
+    }
+    const inspectorRelativePath = relativePath;
+    // 用 TypeScript 编译器解析源码为 AST，开启 parent 节点引用以便后续遍历
+    const sourceFile = ts.createSourceFile(stripViteQuery(id), code, ts.ScriptTarget.Latest, true, getScriptKind(id));
+    // 收集所有需要插入 inspector 属性的位置
+    const insertions = [];
+    // 递归遍历 AST，找到所有 JSX 开标签和自闭合标签
+    function visit(node) {
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+            collectInspectorInsertion(sourceFile, code, inspectorRelativePath, node, insertions);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    if (insertions.length === 0) {
+        return null;
+    }
+    return {
+        code: applyInsertions(code, insertions),
+        map: null
+    };
+}
+/**
+ * 为单个 JSX 元素收集 inspector 属性的插入计划。
+ *
+ * 跳过两种情况：
+ * - Fragment 标签（它不产生真实 DOM，注入属性没有意义）
+ * - 已经有 data-ui-annotate-inspector 的标签（避免重复注入）
+ *
+ * 对于其他标签，计算它在源码中的 "文件路径:行号:列号" 定位，
+ * 然后记录一个 Insertion，表示在标签的合适位置插入属性文本。
+ */
+function collectInspectorInsertion(sourceFile, code, relativePath, node, insertions) {
+    if (isFragmentTag(sourceFile, node.tagName)) {
+        return;
+    }
+    if (hasAttribute(sourceFile, node.attributes, UI_ANNOTATE_INSPECTOR_ATTRIBUTE)) {
+        return;
+    }
+    const insertAt = getAttributeInsertionIndex(code, node);
+    if (insertAt === null) {
+        return;
+    }
+    // 将 AST 节点的起始位置转换为 "行号:列号" 格式（均为 1-based）
+    // 最终生成形如 "src/components/Button.tsx:12:5" 的定位字符串
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    const inspector = `${relativePath}:${line + 1}:${character + 1}`;
+    insertions.push({
+        index: insertAt,
+        text: ` ${UI_ANNOTATE_INSPECTOR_ATTRIBUTE}="${escapeJsxAttribute(inspector)}"`
+    });
+}
+/**
+ * 计算在标签的哪个位置插入新属性最合适。
+ *
+ * 对于自闭合标签 <Foo />：在 "/>" 之前插入
+ *   例如 <Foo bar /> → <Foo bar data-ui-annotate-inspector="..." />
+ *
+ * 对于开标签 <Foo>：在 ">" 之前插入
+ *   例如 <Foo bar> → <Foo bar data-ui-annotate-inspector="...">
+ *
+ * 如果 "/" 或 ">" 不在标签范围内，返回 null 表示无法安全插入。
+ */
+function getAttributeInsertionIndex(code, node) {
+    if (ts.isJsxSelfClosingElement(node)) {
+        // 自闭合标签：从标签末尾往前找 "/>"，属性插在它前面
+        const closeIndex = code.lastIndexOf("/>", node.end);
+        if (closeIndex < node.getStart()) {
+            return null;
+        }
+        // 如果 "/>" 前面已经有空格（如 <Foo bar />），直接插在 "/" 前面；
+        // 如果没有空格（如 <Foo/>），也插在 "/" 前面（Insertion text 自带前导空格）。
+        return /\s/.test(code[closeIndex - 1] ?? "") ? closeIndex - 1 : closeIndex;
+    }
+    // 开标签（非自闭合）：从标签末尾往前找 ">"，属性插在它前面
+    const closeIndex = code.lastIndexOf(">", node.end);
+    return closeIndex >= node.getStart() ? closeIndex : null;
+}
+// 检查 JSX 元素是否已经有指定名称的属性，用于避免重复注入
+function hasAttribute(sourceFile, attributes, name) {
+    return attributes.properties.some((property) => {
+        return ts.isJsxAttribute(property) && property.name.getText(sourceFile) === name;
+    });
+}
+// Fragment 不产生真实 DOM 节点，注入属性没有意义，需要跳过
+function isFragmentTag(sourceFile, tagName) {
+    const text = tagName.getText(sourceFile);
+    return text === "Fragment" || text === "React.Fragment";
+}
+/**
+ * 将收集到的所有 Insertion 按位置从后往前依次应用到源码上。
+ *
+ * 为什么要从后往前？
+ * 因为每次插入都会让后面的字符位置向后偏移。从后往前插入，
+ * 前面已记录的位置不会受到影响，避免了重新计算偏移量的问题。
+ */
+function applyInsertions(code, insertions) {
+    let nextCode = code;
+    for (const insertion of [...insertions].sort((a, b) => b.index - a.index)) {
+        nextCode = `${nextCode.slice(0, insertion.index)}${insertion.text}${nextCode.slice(insertion.index)}`;
+    }
+    return nextCode;
+}
+/**
+ * 判断一个文件是否需要注入 inspector 信息。
+ *
+ * 只对"项目内可写源码"注入，排除 node_modules、dist、generated 等不可写路径。
+ * 这样做的原因：
+ * - 第三方库的 DOM 元素没有项目源码可以定位，注入了也没用
+ * - UI Annotate runtime 需要根据这个定位信息找到对应的源码
+ */
+function resolveInspectableRelativePath(id, options) {
+    try {
+        const relativePath = options.projectRelativePath ?? toProjectRelativePath(stripViteQuery(id), options.root);
+        const normalized = normalizeProjectRelativePath(relativePath);
+        return isWritableProjectSource(normalized) ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+// 将绝对路径转为相对于项目根目录的路径，已经是相对路径则直接返回
+function toProjectRelativePath(id, root = process.cwd()) {
+    if (!path.isAbsolute(id)) {
+        return id;
+    }
+    return path.relative(path.resolve(root), id);
+}
+// 去掉 Vite 在模块 ID 后面追加的查询参数，例如 "/src/App.tsx?vue&type=script" → "/src/App.tsx"
+function stripViteQuery(id) {
+    const queryIndex = id.indexOf("?");
+    return queryIndex === -1 ? id : id.slice(0, queryIndex);
+}
+// 根据文件扩展名判断 TypeScript 解析模式（.jsx 用 JSX 模式，其余默认用 TSX 模式）
+function getScriptKind(id) {
+    const cleanId = stripViteQuery(id);
+    return cleanId.endsWith(".jsx") ? ts.ScriptKind.JSX : ts.ScriptKind.TSX;
+}
+// 转义 JSX 属性值中的特殊字符，防止注入的属性值破坏 JSX 语法
+function escapeJsxAttribute(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}

package/dist/protocol/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const ANNOTATE_TASK_FILE_NAME = "ui.annotate.json";
+export declare const ANNOTATE_TASK_AGENT_INSTRUCTIONS: readonly ["This task file was created from UI Annotate runtime on host pages.", "Read targets first.", "Each target contains its own comments. Use target.comments as the implementation requirements attached to that target.", "Each item in target.comments is an independent requirement for the same target.", "Use target.trace as the primary navigation path from the host page to the selected target.", "target.trace is ordered from the farthest entry component to the nearest selected target.", "Each trace frame represents one continuous segment of calls within a source file.", "The same file may appear multiple times in trace if the navigation path enters it multiple times.", "Within each trace frame, calls are ordered from file entry to file exit.", "The last trace frame contains the selected target file, and its last call item is the selected target.", "If target.trace contains a single call item, that call is both the entry and the selected target.", "A call item line is a 1-based source line number.", "Use line numbers as navigation hints, not exact edit ranges.", "Line numbers may become stale after code edits or formatting changes.", "Treat each target as a location hint, not always the exact edit range; comments may refer to content inside the target or nearby UI.", "Decide whether to edit the selected element, parent layout, or referenced project component."];
+export declare const EMPTY_ANNOTATE_TASK_FILE: {
+    readonly agentInstructions: readonly ["This task file was created from UI Annotate runtime on host pages.", "Read targets first.", "Each target contains its own comments. Use target.comments as the implementation requirements attached to that target.", "Each item in target.comments is an independent requirement for the same target.", "Use target.trace as the primary navigation path from the host page to the selected target.", "target.trace is ordered from the farthest entry component to the nearest selected target.", "Each trace frame represents one continuous segment of calls within a source file.", "The same file may appear multiple times in trace if the navigation path enters it multiple times.", "Within each trace frame, calls are ordered from file entry to file exit.", "The last trace frame contains the selected target file, and its last call item is the selected target.", "If target.trace contains a single call item, that call is both the entry and the selected target.", "A call item line is a 1-based source line number.", "Use line numbers as navigation hints, not exact edit ranges.", "Line numbers may become stale after code edits or formatting changes.", "Treat each target as a location hint, not always the exact edit range; comments may refer to content inside the target or nearby UI.", "Decide whether to edit the selected element, parent layout, or referenced project component."];
+    readonly targets: readonly [];
+};
+export declare const BLOCKED_WRITE_PATH_SEGMENTS: readonly ["node_modules", "dist", "build", ".next", "generated", "vendor"];

package/dist/protocol/constants.js

@@ -0,0 +1,31 @@
+export const ANNOTATE_TASK_FILE_NAME = "ui.annotate.json";
+export const ANNOTATE_TASK_AGENT_INSTRUCTIONS = [
+    "This task file was created from UI Annotate runtime on host pages.",
+    "Read targets first.",
+    "Each target contains its own comments. Use target.comments as the implementation requirements attached to that target.",
+    "Each item in target.comments is an independent requirement for the same target.",
+    "Use target.trace as the primary navigation path from the host page to the selected target.",
+    "target.trace is ordered from the farthest entry component to the nearest selected target.",
+    "Each trace frame represents one continuous segment of calls within a source file.",
+    "The same file may appear multiple times in trace if the navigation path enters it multiple times.",
+    "Within each trace frame, calls are ordered from file entry to file exit.",
+    "The last trace frame contains the selected target file, and its last call item is the selected target.",
+    "If target.trace contains a single call item, that call is both the entry and the selected target.",
+    "A call item line is a 1-based source line number.",
+    "Use line numbers as navigation hints, not exact edit ranges.",
+    "Line numbers may become stale after code edits or formatting changes.",
+    "Treat each target as a location hint, not always the exact edit range; comments may refer to content inside the target or nearby UI.",
+    "Decide whether to edit the selected element, parent layout, or referenced project component."
+];
+export const EMPTY_ANNOTATE_TASK_FILE = {
+    agentInstructions: ANNOTATE_TASK_AGENT_INSTRUCTIONS,
+    targets: []
+};
+export const BLOCKED_WRITE_PATH_SEGMENTS = [
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    "generated",
+    "vendor"
+];

package/dist/protocol/ids.d.ts

@@ -0,0 +1,3 @@
+import type { AnnotateTarget } from "./task-model.js";
+export declare function parseTargetIndex(id: string): number | null;
+export declare function getNextTargetId(targets: Pick<AnnotateTarget, "id">[]): string;

package/dist/protocol/ids.js

@@ -0,0 +1,15 @@
+// 辅助逻辑：解析以 # 开头的目标 ID，例如 "#1" -> 1。
+export function parseTargetIndex(id) {
+    if (!/^#[1-9]\d*$/.test(id)) {
+        return null;
+    }
+    return Number(id.slice(1));
+}
+// 交互执行流程：当用户圈选一个新目标时，遍历现有 target 集合，提取最大序号并 +1。
+export function getNextTargetId(targets) {
+    const maxIndex = targets.reduce((max, target) => {
+        const index = parseTargetIndex(target.id);
+        return index === null ? max : Math.max(max, index);
+    }, 0);
+    return `#${maxIndex + 1}`;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./constants.js";
+export * from "./ids.js";
+export * from "./paths.js";
+export * from "./task-model.js";

package/dist/protocol/index.js

@@ -0,0 +1,4 @@
+export * from "./constants.js";
+export * from "./ids.js";
+export * from "./paths.js";
+export * from "./task-model.js";

package/dist/protocol/paths.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeProjectRelativePath(input: string): string;
+export declare function isBlockedWritePath(relativePath: string): boolean;
+export declare function isWritableProjectSource(relativePath: string): boolean;

package/dist/protocol/paths.js

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { BLOCKED_WRITE_PATH_SEGMENTS } from "./constants.js";
+// 关键算法逻辑：将任意路径标准化为基于项目根目录的相对路径，并阻止跨目录逃逸。
+export function normalizeProjectRelativePath(input) {
+    if (path.isAbsolute(input)) {
+        throw new Error(`Expected a project-relative path, received absolute path: ${input}`);
+    }
+    const normalized = input.replaceAll("\\", "/");
+    const collapsed = path.posix.normalize(normalized);
+    if (collapsed === "." || collapsed.startsWith("../") || collapsed === "..") {
+        throw new Error(`Path must stay inside the project: ${input}`);
+    }
+    return collapsed.replace(/^\.\/+/, "");
+}
+export function isBlockedWritePath(relativePath) {
+    try {
+        const normalized = normalizeProjectRelativePath(relativePath);
+        const segments = normalized.split("/");
+        return BLOCKED_WRITE_PATH_SEGMENTS.some((blocked) => segments.includes(blocked));
+    }
+    catch {
+        return true;
+    }
+}
+export function isWritableProjectSource(relativePath) {
+    try {
+        const normalized = normalizeProjectRelativePath(relativePath);
+        if (isBlockedWritePath(normalized)) {
+            return false;
+        }
+        return /\.(tsx|jsx)$/.test(normalized);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/protocol/task-model.d.ts

@@ -0,0 +1,35 @@
+export type AnnotateTaskFile = {
+    agentInstructions: string[];
+    targets: AnnotateTarget[];
+};
+export type AnnotateTarget = {
+    id: string;
+    comments: string[];
+    trace: TraceFrame[];
+};
+export type TraceFrame = {
+    file: string;
+    calls: TraceCall[];
+};
+export type TraceCall = {
+    line: number;
+    component: string;
+    role?: "entry" | "target";
+};
+export type TraceNodeRef = {
+    kind: "file";
+    frameIndex: number;
+} | {
+    kind: "call";
+    frameIndex: number;
+    callIndex: number;
+};
+export type ParsedSourceLocation = {
+    relativePath: string;
+    line: number;
+    column: number;
+};
+export declare function parseInspectorPath(path: string): ParsedSourceLocation;
+export declare function getTargetSourceLocation(target: Pick<AnnotateTarget, "id" | "trace">): Omit<ParsedSourceLocation, "column">;
+export declare function isSameTargetTrace(left: TraceFrame[], right: TraceFrame[]): boolean;
+export declare function normalizeTraceRoles(trace: TraceFrame[]): TraceFrame[];

package/dist/protocol/task-model.js

@@ -0,0 +1,68 @@
+export function parseInspectorPath(path) {
+    const match = /^(.*):(\d+):(\d+)$/.exec(path);
+    if (!match) {
+        throw new Error(`Invalid source path: ${path}`);
+    }
+    return {
+        relativePath: match[1] ?? "",
+        line: Number.parseInt(match[2] ?? "0", 10),
+        column: Number.parseInt(match[3] ?? "0", 10)
+    };
+}
+export function getTargetSourceLocation(target) {
+    const lastFrame = target.trace[target.trace.length - 1];
+    const lastCall = lastFrame?.calls[lastFrame.calls.length - 1];
+    if (!lastFrame || !lastCall) {
+        throw new Error(`Target ${target.id} does not include a trace target.`);
+    }
+    return {
+        relativePath: lastFrame.file,
+        line: lastCall.line
+    };
+}
+export function isSameTargetTrace(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index]?.file !== right[index]?.file) {
+            return false;
+        }
+    }
+    for (let frameIndex = 0; frameIndex < left.length; frameIndex += 1) {
+        const leftCalls = left[frameIndex]?.calls ?? [];
+        const rightCalls = right[frameIndex]?.calls ?? [];
+        if (leftCalls.length !== rightCalls.length) {
+            return false;
+        }
+        for (let callIndex = 0; callIndex < leftCalls.length; callIndex += 1) {
+            const leftCall = leftCalls[callIndex];
+            const rightCall = rightCalls[callIndex];
+            if (leftCall?.line !== rightCall?.line ||
+                leftCall?.component !== rightCall?.component ||
+                leftCall?.role !== rightCall?.role) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+export function normalizeTraceRoles(trace) {
+    const normalized = trace.map((frame) => ({
+        ...frame,
+        calls: frame.calls.map((call) => {
+            const { role: _role, ...rest } = call;
+            return rest;
+        })
+    }));
+    const calls = normalized.flatMap((frame) => frame.calls);
+    const firstCall = calls[0];
+    const lastCall = calls[calls.length - 1];
+    if (firstCall) {
+        firstCall.role = "entry";
+    }
+    if (lastCall) {
+        lastCall.role = "target";
+    }
+    return normalized;
+}

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

@@ -0,0 +1,9 @@
+import { type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
+import type { AnnotateWindowId, ToolbarPosition } from "../shared/annotate-types.js";
+export declare function AnnotateToolbar({ annotateMode, position, onBeginDrag, onOpenWindow, onToggleAnnotateMode }: {
+    annotateMode: boolean;
+    position: ToolbarPosition;
+    onBeginDrag(event: ReactPointerEvent<HTMLDivElement>): void;
+    onOpenWindow(id: AnnotateWindowId): void;
+    onToggleAnnotateMode(): void;
+}): ReactNode;

package/dist/runtime/app/AnnotateToolbar.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BugIcon, GripHorizontalIcon, SettingsIcon } from "lucide-react";
+import { Button } from "../../ui/components/button.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../ui/components/tooltip.js";
+export function AnnotateToolbar({ annotateMode, position, onBeginDrag, onOpenWindow, onToggleAnnotateMode }) {
+    const style = {
+        left: position.x,
+        top: position.y
+    };
+    return (_jsxs("div", { className: "pointer-events-auto fixed z-[10000] flex min-h-12 w-28 items-center gap-1.5 rounded-lg border bg-background/95 p-1.5 text-foreground shadow-xl backdrop-blur", style: style, onPointerDown: onBeginDrag, "aria-label": "UI Annotate toolbar", children: [_jsx(ToolbarButton, { active: annotateMode, icon: BugIcon, label: "Annotate mode", onClick: onToggleAnnotateMode }), _jsx(ToolbarButton, { icon: SettingsIcon, label: "Settings", onClick: () => onOpenWindow("settings") }), _jsx(GripHorizontalIcon, { "aria-hidden": "true", className: "ml-auto size-4 text-muted-foreground" })] }));
+}
+function ToolbarButton({ active = false, icon: Icon, label, onClick }) {
+    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx(Button, { type: "button", variant: active ? "default" : "ghost", size: "icon", "aria-label": label, "aria-pressed": active, onClick: onClick, children: _jsx(Icon, { "data-icon": "inline-start", "aria-hidden": "true" }) }) }), _jsx(TooltipContent, { side: "top", children: label })] }));
+}