@ui-annotate/react-vite 0.1.1 → 0.1.3

package/README.md

@@ -79,7 +79,7 @@ uiAnnotate({
 
 ## Runtime Boundaries
 
-- Supported host apps: React 18 or 19 with Vite 8.
+- Supported host apps: React 18 or 19 with Vite 7 or 8.
 - The runtime is development-only and is injected by the Vite dev server.
 - The runtime creates `#__ui_annotate_root__` under `document.body`; your app does not need to provide a mount point.
 - The UI is isolated in a shadow root.

package/dist/inspector-transform.d.ts

@@ -30,30 +30,6 @@ type ViteDevServerLike = {
         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

@@ -2,33 +2,17 @@ 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 生效，生产构建不加载这个插件
+        enforce: "pre",
+        apply: "serve",
         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/")) {
@@ -54,19 +38,6 @@ export function createUiAnnotateInspectorPlugin(options = {}) {
         }
     };
 }
-/**
- * 核心转换逻辑：用 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;
@@ -76,11 +47,8 @@ export function transformUiAnnotateInspectorSource(code, id, options = {}) {
         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);
@@ -96,16 +64,6 @@ export function transformUiAnnotateInspectorSource(code, id, options = {}) {
         map: null
     };
 }
-/**
- * 为单个 JSX 元素收集 inspector 属性的插入计划。
- *
- * 跳过两种情况：
- * - Fragment 标签（它不产生真实 DOM，注入属性没有意义）
- * - 已经有 data-ui-annotate-inspector 的标签（避免重复注入）
- *
- * 对于其他标签，计算它在源码中的 "文件路径:行号:列号" 定位，
- * 然后记录一个 Insertion，表示在标签的合适位置插入属性文本。
- */
 function collectInspectorInsertion(sourceFile, code, relativePath, node, insertions) {
     if (isFragmentTag(sourceFile, node.tagName)) {
         return;
@@ -117,8 +75,6 @@ function collectInspectorInsertion(sourceFile, code, relativePath, node, inserti
     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({
@@ -126,50 +82,26 @@ function collectInspectorInsertion(sourceFile, code, relativePath, node, inserti
         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)) {
@@ -177,14 +109,6 @@ function applyInsertions(code, insertions) {
     }
     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);
@@ -195,24 +119,20 @@ function resolveInspectableRelativePath(id, options) {
         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/ids.js

@@ -1,11 +1,9 @@
-// 辅助逻辑：解析以 # 开头的目标 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);

package/dist/protocol/paths.js

@@ -1,6 +1,5 @@
 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}`);

package/dist/runtime/inspector/target-inspection.js

@@ -41,8 +41,6 @@ export function findElementForTraceNode(previewRoot, target, node, annotateFile,
     if (!location) {
         return null;
     }
-    // First locate the selected target as context, so matching names elsewhere
-    // in the Annotate UI do not steal the trace hover highlight.
     const targetElement = findElementForTarget(previewRoot, target, annotateFile, showNativeTraceNodes) ??
         findElementForTarget(previewRoot, target, annotateFile, !showNativeTraceNodes);
     if (targetElement) {

package/dist/runtime/shared/clipboard.js

@@ -5,7 +5,6 @@ export async function writeClipboardText(text) {
             return true;
         }
         catch {
-            // Fall through to the textarea fallback for older or restricted contexts.
         }
     }
     return writeClipboardTextWithTextarea(text);

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

@@ -79,7 +79,6 @@ async function readErrorMessage(response) {
         }
     }
     catch {
-        // JSON parse failed; fall back to the generic status message.
     }
     return `UI Annotate task request failed with ${response.status}.`;
 }

package/dist/runtime/windows/AnnotateWindowFrame.js

@@ -49,8 +49,7 @@ export function AnnotateWindowFrame({ children, floating = true, icon: Icon, id,
             width: state.width,
             height: state.height
         };
-    return (_jsxs("section", { className: cn("pointer-events-auto flex flex-col overflow-hidden rounded-xl border bg-card/95 text-card-foreground shadow-xl backdrop-blur", floating ? "fixed z-20" : "relative max-w-full"), style: style, "aria-label": label, children: [_jsxs("header", { className: "flex min-h-9 cursor-move select-none items-center justify-between gap-2 border-b bg-muted/30 py-0.5 pl-2.5 pr-1.5", onPointerDown: (event) => onBeginMove(id, event), children: [_jsxs("div", { className: "flex min-w-0 items-center gap-1.5 text-xs font-semibold text-foreground", children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { className: "min-w-0 truncate", children: title })] }), _jsx(Button, { type: "button", variant: "ghost", size: "icon", className: "size-6" // 覆盖为 size-6（24px），不再被 size="icon" 默认的 size-9（36px）撑开
-                        , "aria-label": `Close ${label}`, onPointerDown: (event) => event.stopPropagation(), onClick: () => onClose(id), children: _jsx(XIcon, { "data-icon": "inline-start", "aria-hidden": "true" }) })] }), _jsx("div", { className: "min-h-0 flex-1 p-3", children: children }), floating
+    return (_jsxs("section", { className: cn("pointer-events-auto flex flex-col overflow-hidden rounded-xl border bg-card/95 text-card-foreground shadow-xl backdrop-blur", floating ? "fixed z-20" : "relative max-w-full"), style: style, "aria-label": label, children: [_jsxs("header", { className: "flex min-h-9 cursor-move select-none items-center justify-between gap-2 border-b bg-muted/30 py-0.5 pl-2.5 pr-1.5", onPointerDown: (event) => onBeginMove(id, event), children: [_jsxs("div", { className: "flex min-w-0 items-center gap-1.5 text-xs font-semibold text-foreground", children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), _jsx("span", { className: "min-w-0 truncate", children: title })] }), _jsx(Button, { type: "button", variant: "ghost", size: "icon", className: "size-6", "aria-label": `Close ${label}`, onPointerDown: (event) => event.stopPropagation(), onClick: () => onClose(id), children: _jsx(XIcon, { "data-icon": "inline-start", "aria-hidden": "true" }) })] }), _jsx("div", { className: "min-h-0 flex-1 p-3", children: children }), floating
                 ? resizeHandles.map((handle) => (_jsx("div", { className: cn("absolute touch-none", handle.className), "aria-hidden": "true", onPointerDown: (event) => onBeginResize(id, handle.direction, event) }, `${handle.direction.horizontal}:${handle.direction.vertical}`)))
                 : null] }));
 }

package/dist/ui-annotate-plugin.js

@@ -37,8 +37,6 @@ function createUiAnnotateRuntimePlugin() {
             appendAnnotateTaskWatchIgnores(config);
             return {
                 resolve: {
-                    // Linked host apps can otherwise load one React from the app and another from
-                    // the embedded UI Annotate runtime, which breaks hooks inside the runtime.
                     dedupe: ["react", "react-dom"],
                     alias: {
                         [UI_ANNOTATE_RUNTIME_STYLE_IMPORT_ID]: runtimeStylePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui-annotate/react-vite",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Annotate React UI issues in Vite apps and hand them off to coding agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "vite": "^8.0.13"
+    "vite": "^7.0.0 || ^8.0.13"
   },
   "devDependencies": {
     "vite": "^8.0.13"