vite-plugin-visual-selector 0.1.0

package/README.md

@@ -0,0 +1,795 @@
+# vite-plugin-visual-selector
+
+一个面向 **React / JSX / TSX** 的 Vite 插件，用来实现类似 Base44 可视化编辑器中的“源码同源元素联动高亮”能力。
+
+它提供两部分能力：
+
+1. **编译时注入**：在 JSX 编译阶段给原生 DOM 元素注入 `data-source-location`
+2. **运行时桥接**：在预览页 / iframe 中启用 `setupSelectionBridge()`，实现 hover、高亮、同源元素批量选中、`postMessage` 通知父页面
+
+---
+
+## 一、它解决什么问题
+
+在可视化编辑器里，用户点到页面上的某个元素时，编辑器通常需要知道：
+
+- 这个 DOM 节点来自哪一段源码
+- 页面上还有哪些元素与它来自同一个 JSX 表达式
+- 如何把这些“同源元素”一起高亮出来
+- 如何把选中结果同步给父级编辑器 UI
+
+这个插件就是为这个目标设计的。
+
+典型效果：
+
+```tsx
+{items.map((item) => (
+  <div className="cell">{item.label}</div>
+))}
+```
+
+如果这几个 `div` 都来自同一行 `.map()` JSX，那么点击其中一个时，所有同样带有相同 `data-source-location` 的元素都会一起被高亮。
+
+---
+
+## 二、能力概览
+
+### 编译时
+
+- 只处理 `.jsx` / `.tsx`
+- 只给**原生 DOM 标签**注入属性，例如：`div`、`span`、`button`
+- 不给 React 组件注入，例如：`<Card />`
+- 默认属性名：`data-source-location`
+- 默认值格式：`相对路径:行:列`
+
+示例：
+
+```html
+<div data-source-location="src/App.tsx:12:6">...</div>
+```
+
+### 运行时
+
+- hover 时高亮同 source-location 的元素
+- click 时选中同 source-location 的元素
+- 给每个匹配元素绘制 overlay
+- 向父页面发送 `postMessage`
+- 支持销毁和清空当前高亮状态
+
+---
+
+## 三、安装
+
+```bash
+npm install vite-plugin-visual-selector
+```
+
+如果你要跑本仓库 demo / 本地开发：
+
+```bash
+npm install
+```
+
+---
+
+## 四、最基本的使用方式
+
+### 1）在 `vite.config.ts` 中注册插件
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualSelectorPlugin(),
+  ],
+})
+```
+
+这是最小接入方式。
+
+注册后，插件会在 Vite transform 阶段扫描 JSX / TSX 模块，并给原生 DOM 节点自动插入 `data-source-location`。
+
+---
+
+## 五、进阶配置
+
+插件入口：
+
+```ts
+import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+```
+
+类型定义：
+
+```ts
+interface VisualSelectorPluginOptions {
+  include?: RegExp[]
+  exclude?: RegExp[]
+  attributeName?: string
+  root?: string
+}
+```
+
+### 配置示例
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualSelectorPlugin({
+      include: [/\.[jt]sx$/],
+      exclude: [/node_modules/, /\.test\./],
+      attributeName: 'data-source-location',
+      root: process.cwd(),
+    }),
+  ],
+})
+```
+
+### 配置项说明
+
+#### `include?: RegExp[]`
+
+控制哪些文件会进入 transform。
+
+默认值：
+
+```ts
+[/\.[jt]sx$/]
+```
+
+也就是默认只处理 JSX / TSX 文件。
+
+#### `exclude?: RegExp[]`
+
+控制哪些文件会被跳过。
+
+默认值：
+
+```ts
+[/node_modules/]
+```
+
+#### `attributeName?: string`
+
+自定义注入属性名。
+
+默认值：
+
+```ts
+'data-source-location'
+```
+
+如果你的编辑器协议想用别的名字，可以改。
+
+#### `root?: string`
+
+用于生成相对路径。
+
+例如源码绝对路径是：
+
+```txt
+/Users/me/project/src/App.tsx
+```
+
+如果 `root = /Users/me/project`，最终注入值会变成：
+
+```txt
+src/App.tsx:12:6
+```
+
+---
+
+## 六、运行时接入方式
+
+仅仅注册 Vite 插件还不够。  
+如果你想获得 Base44 那种“点击元素时，同源元素一起高亮”的能力，还需要在预览页中显式启用 runtime bridge。
+
+运行时入口：
+
+```ts
+import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
+```
+
+### 最小接入示例
+
+```ts
+import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
+
+setupSelectionBridge({
+  parentWindow: window.parent,
+  enableHover: true,
+  enableClickSelection: true,
+})
+```
+
+这个调用通常应该放在：
+
+- 预览页入口
+- iframe 内部页面入口
+- 或专门的 preview bootstrap 文件里
+
+---
+
+## 七、runtime API 详细说明
+
+类型定义：
+
+```ts
+interface SelectionBridgeOptions {
+  attributeName?: string
+  targetWindow?: Window
+  parentWindow?: Pick<Window, 'postMessage'>
+  targetOrigin?: string
+  enableHover?: boolean
+  enableClickSelection?: boolean
+}
+```
+
+### 参数说明
+
+#### `attributeName?: string`
+
+要读取的元素标识属性名。
+
+默认值：
+
+```ts
+'data-source-location'
+```
+
+#### `targetWindow?: Window`
+
+bridge 所工作的目标 window。
+
+默认值：
+
+```ts
+window
+```
+
+通常不需要改，除非你在特殊上下文中手动桥接别的 window。
+
+#### `parentWindow?: Pick<Window, 'postMessage'>`
+
+接收消息的父窗口对象。
+
+默认值：
+
+```ts
+window.parent
+```
+
+#### `targetOrigin?: string`
+
+`postMessage` 的目标 origin。
+
+默认值：
+
+```ts
+'*'
+```
+
+生产环境里如果你有固定编辑器域名，建议收紧为明确 origin。
+
+#### `enableHover?: boolean`
+
+是否启用 hover 联动高亮。
+
+默认值：
+
+```ts
+true
+```
+
+#### `enableClickSelection?: boolean`
+
+是否启用点击选中。
+
+默认值：
+
+```ts
+true
+```
+
+---
+
+## 八、`setupSelectionBridge()` 返回什么
+
+当前返回一个控制对象：
+
+```ts
+const bridge = setupSelectionBridge({...})
+
+bridge.destroy()
+bridge.clearSelection()
+```
+
+### `destroy()`
+
+作用：
+
+- 移除事件监听器
+- 删除当前所有 overlay
+- 释放当前激活的 bridge
+
+适合场景：
+
+- 预览页卸载
+- iframe 切换页面
+- 编辑器销毁
+
+### `clearSelection()`
+
+作用：
+
+- 清除 selected overlays
+- 清除 hover overlays
+
+适合场景：
+
+- 父编辑器主动取消选中
+- 切换右侧面板时重置视觉状态
+- 执行删除 / 替换元素后重置高亮
+
+---
+
+## 九、父页面会收到什么消息
+
+当前 runtime 会发出类似下面的消息：
+
+```ts
+{
+  type: 'element-selected',
+  tagName: 'DIV',
+  className: 'box',
+  selectorId: 'src/App.tsx:12:6',
+  dataSourceLocation: 'src/App.tsx:12:6',
+  rect: {
+    top: 120,
+    left: 300,
+    right: 348,
+    bottom: 168,
+    width: 48,
+    height: 48,
+  },
+}
+```
+
+其中：
+
+- `type`
+  - 当前可能值：`element-selected` / `element-hovered`
+- `tagName`
+  - 被命中元素的标签名
+- `className`
+  - 元素的 className
+- `selectorId`
+  - 当前选中的 source 标识
+- `dataSourceLocation`
+  - 当前和 `selectorId` 保持一致
+- `rect`
+  - 元素在 viewport 中的矩形信息
+
+### 父页面接收示例
+
+```ts
+window.addEventListener('message', (event) => {
+  const data = event.data
+
+  if (data?.type === 'element-selected') {
+    console.log('用户选中了元素:', data)
+  }
+})
+```
+
+---
+
+## 十、完整接入示例
+
+### `vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualSelectorPlugin({
+      root: process.cwd(),
+    }),
+  ],
+})
+```
+
+### `src/preview-bridge.ts`
+
+```ts
+import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
+
+setupSelectionBridge({
+  parentWindow: window.parent,
+  enableHover: true,
+  enableClickSelection: true,
+})
+```
+
+### `src/main.tsx`
+
+```ts
+import './preview-bridge'
+```
+
+### 父页面
+
+```ts
+window.addEventListener('message', (event) => {
+  if (event.data?.type === 'element-selected') {
+    // 打开右侧属性面板 / 更新工具栏 / 高亮源码等
+  }
+})
+```
+
+---
+
+## 十一、编译前后效果示例
+
+源码：
+
+```tsx
+{items.map((item) => (
+  <div className="cell">{item.label}</div>
+))}
+```
+
+经过插件 transform 后，效果近似于：
+
+```tsx
+{items.map((item) => (
+  <div
+    data-source-location="src/App.tsx:12:6"
+    className="cell"
+  >
+    {item.label}
+  </div>
+))}
+```
+
+如果页面最终渲染出多个 `div`，它们都会带相同的 `data-source-location`，于是 runtime 就能把它们视为“同源元素组”。
+
+---
+
+## 十二、实现过程详解
+
+这一部分重点解释：这个插件到底是怎么工作的。
+
+### 整体分层
+
+插件分成两层：
+
+```txt
+编译时：JSX -> 注入 data-source-location
+运行时：读 data-source-location -> 查找同源元素 -> 绘制 overlay -> postMessage
+```
+
+也就是：
+
+1. **先在编译时埋点**
+2. **再在运行时消费这些标记**
+
+---
+
+### 1）编译时实现过程
+
+核心文件：
+
+- `src/plugin.ts`
+
+使用到的核心工具：
+
+- `@babel/parser`
+- `@babel/traverse`
+- `@babel/types`
+- `magic-string`
+
+#### 步骤 A：过滤目标文件
+
+插件只处理匹配 `include` 的文件，并跳过 `exclude`。
+
+默认情况就是：
+
+- 处理 `.jsx` / `.tsx`
+- 跳过 `node_modules`
+
+#### 步骤 B：解析 AST
+
+```ts
+const ast = parse(code, {
+  sourceType: 'module',
+  plugins: ['jsx', 'typescript'],
+})
+```
+
+这样插件就能拿到 JSX 节点的结构信息和源码位置信息。
+
+#### 步骤 C：只处理原生标签
+
+插件会检查当前节点是不是原生 DOM 元素。
+
+例如：
+
+- `div` → 处理
+- `span` → 处理
+- `button` → 处理
+- `Card` → 不处理
+- `Layout` → 不处理
+
+原因很简单：
+
+React 组件本身并不一定会直接成为真实 DOM，只有最终的原生标签才适合被 visual selector 消费。
+
+#### 步骤 D：生成 source-location
+
+插件会根据：
+
+- 文件相对路径
+- AST 节点起始行号
+- AST 节点起始列号
+
+生成：
+
+```txt
+src/App.tsx:12:6
+```
+
+这里列号做了 `+1`，是为了输出更符合人类习惯的 1-based 列号。
+
+#### 步骤 E：把属性插回源码
+
+通过 `MagicString` 在 JSX opening tag 中插入属性：
+
+```ts
+magicString.appendLeft(node.name.end, ` ${attributeName}="${location}"`)
+```
+
+这样就不会手写字符串拼接整段 JSX，而是进行更可靠的源码片段注入。
+
+#### 步骤 F：输出 sourcemap
+
+如果文件确实发生了变更，就返回：
+
+```ts
+{
+  code: magicString.toString(),
+  map: magicString.generateMap({ hires: true }),
+}
+```
+
+这样宿主工具链还能继续保持较好的调试体验。
+
+---
+
+### 2）运行时实现过程
+
+核心文件：
+
+- `src/runtime.ts`
+
+#### 步骤 A：安装 bridge
+
+```ts
+setupSelectionBridge({...})
+```
+
+调用后会：
+
+- 绑定 click 监听
+- 绑定 mousemove 监听
+- 维护 selected / hover overlay 状态
+
+而且当前实现会保证：
+
+- 同一个页面只存在一个激活 bridge
+- 再次调用时会先清理上一个 bridge
+
+#### 步骤 B：识别可选元素
+
+runtime 会从事件目标开始向上查找最近的：
+
+```txt
+[data-source-location]
+```
+
+如果事件命中的是 overlay 本身，则会直接跳过，避免“高亮层选中高亮层”的问题。
+
+#### 步骤 C：读取 selectorId
+
+当前 selectorId 本质上就是元素的：
+
+```ts
+element.getAttribute(attributeName)
+```
+
+通常就是 `data-source-location` 的值。
+
+#### 步骤 D：查找所有同源元素
+
+一旦拿到 selectorId，runtime 会执行：
+
+```ts
+document.querySelectorAll(`[data-source-location="..."]`)
+```
+
+从整个文档中找出所有具有相同 source-location 的元素。
+
+这就是“点击一个元素，所有同类一起高亮”的核心。
+
+#### 步骤 E：绘制 overlay
+
+对每一个匹配元素，runtime 都会创建一个新的 overlay：
+
+- `position: absolute`
+- `pointer-events: none`
+- 高 z-index
+- hover / selected 两套样式
+
+然后根据目标元素的 `getBoundingClientRect()`，把 overlay 定位到正确位置。
+
+#### 步骤 F：发消息给父页面
+
+click 时，runtime 会调用：
+
+```ts
+parentWindow.postMessage(message, targetOrigin)
+```
+
+父编辑器收到消息后，就可以：
+
+- 打开元素编辑面板
+- 更新工具栏
+- 选中对应源码节点
+- 做 hover / selection 同步
+
+---
+
+## 十三、为什么这样设计
+
+### 为什么在编译时注入属性？
+
+因为这是最稳定、最轻量的方式。
+
+优点：
+
+- 运行时不需要做源码分析
+- DOM 一渲染出来就带有可追踪标识
+- 同一个 JSX 表达式渲染出的多个元素天然共享同一个标识
+
+### 为什么只给原生 DOM 打标？
+
+因为编辑器最终操作的是浏览器里的真实 DOM，而不是 React 组件抽象层。
+
+### 为什么 overlay 挂在 `document.body`？
+
+因为这样不需要改动原始业务 DOM，侵入性最低，也更容易做绝对定位。
+
+### 为什么 runtime 不自动注入？
+
+因为显式接入更稳：
+
+- 不需要猜宿主应用入口
+- 不污染用户项目结构
+- 容易和 iframe / preview 场景集成
+
+---
+
+## 十四、当前实现的限制
+
+当前版本有这些限制：
+
+1. **只支持 React / JSX / TSX**
+2. **只处理原生 DOM 元素**
+3. **runtime 需要手动调用 `setupSelectionBridge()`**
+4. **当前 overlay 会在 hover 时“先清再画”**
+   - 逻辑简单
+   - 但还没有做更细的性能优化
+5. **当前尚未内建 scroll / resize 自动重定位增强**
+6. **当前消息结构是最小可用版，不是完整编辑器协议**
+
+---
+
+## 十五、推荐接入方式
+
+如果你要把它接入自己的可视化编辑器，我建议这样分工：
+
+### 预览页 / iframe 内部
+
+- 注册 `visualSelectorPlugin()`
+- 启用 `setupSelectionBridge()`
+- 渲染业务页面
+
+### 父编辑器页面
+
+- 监听 `postMessage`
+- 根据 `element-selected` 更新 UI
+- 必要时主动调用 preview 内部能力做状态复位
+
+---
+
+## 十六、本地开发命令
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+运行 demo：
+
+```bash
+npm run demo
+```
+
+---
+
+## 十七、项目结构
+
+```txt
+src/
+  index.ts          # 插件入口导出
+  plugin.ts         # 编译时 JSX 注入逻辑
+  runtime.ts        # 运行时 bridge / overlay / postMessage
+  shared/
+    constants.ts    # 常量
+    types.ts        # 公共类型
+
+demo/
+  vite.config.ts
+  src/
+    App.tsx
+    bridge.ts
+    main.tsx
+
+test/
+  plugin.test.ts
+  runtime.test.ts
+  runtime-api.test.ts
+  package.test.ts
+  demo-docs.test.ts
+```
+
+---
+
+## 十八、导出 API 一览
+
+### 主入口
+
+```ts
+import { visualSelectorPlugin } from 'vite-plugin-visual-selector'
+```
+
+### runtime 入口
+
+```ts
+import { setupSelectionBridge } from 'vite-plugin-visual-selector/runtime'
+```
+
+---
+
+## 十九、总结
+
+如果你只记住一句话，可以记这个：
+
+> 这个插件的核心思想是：**编译时给 DOM 打上源码坐标，运行时再根据这个坐标把同源元素重新聚合起来。**
+
+这样就能用非常简单、非常稳定的方式，做出类似 Base44 那种“点击一个元素，所有同类一起高亮”的可视化编辑体验。

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Plugin } from 'vite';
+import { V as VisualSelectorPluginOptions } from './types-DlgpChn_.js';
+export { S as SelectionBridgeOptions } from './types-DlgpChn_.js';
+
+declare function visualSelectorPlugin(options?: VisualSelectorPluginOptions): Plugin;
+
+export { VisualSelectorPluginOptions, visualSelectorPlugin };

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/plugin.ts
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
+import MagicString from "magic-string";
+import path from "path";
+
+// src/shared/constants.ts
+var DEFAULT_ATTRIBUTE_NAME = "data-source-location";
+
+// src/plugin.ts
+function toRelativeUnixPath(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join("/");
+}
+function isIntrinsicElement(node) {
+  return t.isJSXIdentifier(node.name) && /^[a-z]/.test(node.name.name);
+}
+function hasSourceLocationAttribute(node, attributeName) {
+  return node.attributes.some(
+    (attribute) => t.isJSXAttribute(attribute) && t.isJSXIdentifier(attribute.name) && attribute.name.name === attributeName
+  );
+}
+function visualSelectorPlugin(options = {}) {
+  const attributeName = options.attributeName ?? DEFAULT_ATTRIBUTE_NAME;
+  const root = options.root ?? process.cwd();
+  const include = options.include ?? [/\.[jt]sx$/];
+  const exclude = options.exclude ?? [/node_modules/];
+  return {
+    name: "vite-plugin-visual-selector",
+    enforce: "pre",
+    transform(code, id) {
+      if (!include.some((pattern) => pattern.test(id))) {
+        return null;
+      }
+      if (exclude.some((pattern) => pattern.test(id))) {
+        return null;
+      }
+      const ast = parse(code, {
+        sourceType: "module",
+        plugins: ["jsx", "typescript"]
+      });
+      const magicString = new MagicString(code);
+      let mutated = false;
+      traverse(ast, {
+        JSXOpeningElement(jsxPath) {
+          const node = jsxPath.node;
+          if (!isIntrinsicElement(node)) {
+            return;
+          }
+          if (hasSourceLocationAttribute(node, attributeName)) {
+            return;
+          }
+          if (!node.loc || node.name.end == null) {
+            return;
+          }
+          const location = `${toRelativeUnixPath(root, id)}:${node.loc.start.line}:${node.loc.start.column + 1}`;
+          magicString.appendLeft(node.name.end, ` ${attributeName}="${location}"`);
+          mutated = true;
+        }
+      });
+      if (!mutated) {
+        return code;
+      }
+      return {
+        code: magicString.toString(),
+        map: magicString.generateMap({ hires: true })
+      };
+    }
+  };
+}
+export {
+  visualSelectorPlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts","../src/shared/constants.ts"],"sourcesContent":["import { parse } from '@babel/parser'\nimport traverse from '@babel/traverse'\nimport * as t from '@babel/types'\nimport MagicString from 'magic-string'\nimport path from 'node:path'\nimport type { Plugin } from 'vite'\n\nimport { DEFAULT_ATTRIBUTE_NAME } from './shared/constants'\nimport type { VisualSelectorPluginOptions } from './shared/types'\n\nfunction toRelativeUnixPath(root: string, filePath: string) {\n  return path.relative(root, filePath).split(path.sep).join('/')\n}\n\nfunction isIntrinsicElement(node: t.JSXOpeningElement) {\n  return t.isJSXIdentifier(node.name) && /^[a-z]/.test(node.name.name)\n}\n\nfunction hasSourceLocationAttribute(node: t.JSXOpeningElement, attributeName: string) {\n  return node.attributes.some(\n    (attribute) =>\n      t.isJSXAttribute(attribute) &&\n      t.isJSXIdentifier(attribute.name) &&\n      attribute.name.name === attributeName,\n  )\n}\n\nexport function visualSelectorPlugin(\n  options: VisualSelectorPluginOptions = {},\n): Plugin {\n  const attributeName = options.attributeName ?? DEFAULT_ATTRIBUTE_NAME\n  const root = options.root ?? process.cwd()\n  const include = options.include ?? [/\\.[jt]sx$/]\n  const exclude = options.exclude ?? [/node_modules/]\n\n  return {\n    name: 'vite-plugin-visual-selector',\n    enforce: 'pre',\n    transform(code, id) {\n      if (!include.some((pattern) => pattern.test(id))) {\n        return null\n      }\n\n      if (exclude.some((pattern) => pattern.test(id))) {\n        return null\n      }\n\n      const ast = parse(code, {\n        sourceType: 'module',\n        plugins: ['jsx', 'typescript'],\n      })\n\n      const magicString = new MagicString(code)\n      let mutated = false\n\n      traverse(ast, {\n        JSXOpeningElement(jsxPath) {\n          const node = jsxPath.node\n\n          if (!isIntrinsicElement(node)) {\n            return\n          }\n\n          if (hasSourceLocationAttribute(node, attributeName)) {\n            return\n          }\n\n          if (!node.loc || node.name.end == null) {\n            return\n          }\n\n          const location = `${toRelativeUnixPath(root, id)}:${node.loc.start.line}:${node.loc.start.column + 1}`\n          magicString.appendLeft(node.name.end, ` ${attributeName}=\"${location}\"`)\n          mutated = true\n        },\n      })\n\n      if (!mutated) {\n        return code\n      }\n\n      return {\n        code: magicString.toString(),\n        map: magicString.generateMap({ hires: true }),\n      }\n    },\n  }\n}\n","export const DEFAULT_ATTRIBUTE_NAME = 'data-source-location'\nexport const OVERLAY_ATTRIBUTE_NAME = 'data-visual-selector-overlay'\n"],"mappings":";AAAA,SAAS,aAAa;AACtB,OAAO,cAAc;AACrB,YAAY,OAAO;AACnB,OAAO,iBAAiB;AACxB,OAAO,UAAU;;;ACJV,IAAM,yBAAyB;;;ADUtC,SAAS,mBAAmB,MAAc,UAAkB;AAC1D,SAAO,KAAK,SAAS,MAAM,QAAQ,EAAE,MAAM,KAAK,GAAG,EAAE,KAAK,GAAG;AAC/D;AAEA,SAAS,mBAAmB,MAA2B;AACrD,SAAS,kBAAgB,KAAK,IAAI,KAAK,SAAS,KAAK,KAAK,KAAK,IAAI;AACrE;AAEA,SAAS,2BAA2B,MAA2B,eAAuB;AACpF,SAAO,KAAK,WAAW;AAAA,IACrB,CAAC,cACG,iBAAe,SAAS,KACxB,kBAAgB,UAAU,IAAI,KAChC,UAAU,KAAK,SAAS;AAAA,EAC5B;AACF;AAEO,SAAS,qBACd,UAAuC,CAAC,GAChC;AACR,QAAM,gBAAgB,QAAQ,iBAAiB;AAC/C,QAAM,OAAO,QAAQ,QAAQ,QAAQ,IAAI;AACzC,QAAM,UAAU,QAAQ,WAAW,CAAC,WAAW;AAC/C,QAAM,UAAU,QAAQ,WAAW,CAAC,cAAc;AAElD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,UAAU,MAAM,IAAI;AAClB,UAAI,CAAC,QAAQ,KAAK,CAAC,YAAY,QAAQ,KAAK,EAAE,CAAC,GAAG;AAChD,eAAO;AAAA,MACT;AAEA,UAAI,QAAQ,KAAK,CAAC,YAAY,QAAQ,KAAK,EAAE,CAAC,GAAG;AAC/C,eAAO;AAAA,MACT;AAEA,YAAM,MAAM,MAAM,MAAM;AAAA,QACtB,YAAY;AAAA,QACZ,SAAS,CAAC,OAAO,YAAY;AAAA,MAC/B,CAAC;AAED,YAAM,cAAc,IAAI,YAAY,IAAI;AACxC,UAAI,UAAU;AAEd,eAAS,KAAK;AAAA,QACZ,kBAAkB,SAAS;AACzB,gBAAM,OAAO,QAAQ;AAErB,cAAI,CAAC,mBAAmB,IAAI,GAAG;AAC7B;AAAA,UACF;AAEA,cAAI,2BAA2B,MAAM,aAAa,GAAG;AACnD;AAAA,UACF;AAEA,cAAI,CAAC,KAAK,OAAO,KAAK,KAAK,OAAO,MAAM;AACtC;AAAA,UACF;AAEA,gBAAM,WAAW,GAAG,mBAAmB,MAAM,EAAE,CAAC,IAAI,KAAK,IAAI,MAAM,IAAI,IAAI,KAAK,IAAI,MAAM,SAAS,CAAC;AACpG,sBAAY,WAAW,KAAK,KAAK,KAAK,IAAI,aAAa,KAAK,QAAQ,GAAG;AACvE,oBAAU;AAAA,QACZ;AAAA,MACF,CAAC;AAED,UAAI,CAAC,SAAS;AACZ,eAAO;AAAA,MACT;AAEA,aAAO;AAAA,QACL,MAAM,YAAY,SAAS;AAAA,QAC3B,KAAK,YAAY,YAAY,EAAE,OAAO,KAAK,CAAC;AAAA,MAC9C;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/runtime.d.ts

@@ -0,0 +1,8 @@
+import { S as SelectionBridgeOptions } from './types-DlgpChn_.js';
+
+declare function setupSelectionBridge(options?: SelectionBridgeOptions): {
+    destroy(): void;
+    clearSelection(): void;
+};
+
+export { setupSelectionBridge };

package/dist/runtime.js

@@ -0,0 +1,150 @@
+// src/shared/constants.ts
+var DEFAULT_ATTRIBUTE_NAME = "data-source-location";
+var OVERLAY_ATTRIBUTE_NAME = "data-visual-selector-overlay";
+
+// src/runtime.ts
+var activeCleanup = null;
+function getElementSelectorId(element, attributeName) {
+  return element.getAttribute(attributeName);
+}
+function isOverlayElement(element) {
+  return element.hasAttribute(OVERLAY_ATTRIBUTE_NAME);
+}
+function getSelectableElement(target, attributeName) {
+  if (!(target instanceof Element)) {
+    return null;
+  }
+  const closestOverlay = target.closest(`[${OVERLAY_ATTRIBUTE_NAME}]`);
+  if (closestOverlay) {
+    return null;
+  }
+  return target.closest(`[${attributeName}]`);
+}
+function findMatchingElements(selectorId, attributeName, root) {
+  return Array.from(
+    root.querySelectorAll(`[${attributeName}="${selectorId}"]`)
+  );
+}
+function createOverlay(mode, doc) {
+  const overlay = doc.createElement("div");
+  overlay.setAttribute(OVERLAY_ATTRIBUTE_NAME, mode);
+  overlay.style.position = "absolute";
+  overlay.style.pointerEvents = "none";
+  overlay.style.zIndex = "9999";
+  overlay.style.transition = "all 0.1s ease-in-out";
+  if (mode === "selected") {
+    overlay.style.border = "2px solid #2563EB";
+  } else {
+    overlay.style.border = "2px solid #95a5fc";
+    overlay.style.backgroundColor = "rgba(99, 102, 241, 0.05)";
+  }
+  return overlay;
+}
+function positionOverlay(overlay, target, view) {
+  const rect = target.getBoundingClientRect();
+  overlay.style.top = `${rect.top + view.scrollY}px`;
+  overlay.style.left = `${rect.left + view.scrollX}px`;
+  overlay.style.width = `${rect.width}px`;
+  overlay.style.height = `${rect.height}px`;
+}
+function createMessage(type, element, attributeName) {
+  const rect = element.getBoundingClientRect();
+  return {
+    type,
+    tagName: element.tagName,
+    className: element.className,
+    selectorId: getElementSelectorId(element, attributeName),
+    dataSourceLocation: getElementSelectorId(element, attributeName),
+    rect: {
+      top: rect.top,
+      left: rect.left,
+      right: rect.right,
+      bottom: rect.bottom,
+      width: rect.width,
+      height: rect.height
+    }
+  };
+}
+function setupSelectionBridge(options = {}) {
+  activeCleanup?.();
+  const targetWindow = options.targetWindow ?? window;
+  const targetDocument = targetWindow.document;
+  const parentWindow = options.parentWindow ?? window.parent;
+  const attributeName = options.attributeName ?? DEFAULT_ATTRIBUTE_NAME;
+  const targetOrigin = options.targetOrigin ?? "*";
+  const enableHover = options.enableHover ?? true;
+  const enableClickSelection = options.enableClickSelection ?? true;
+  let selectedOverlays = [];
+  let hoverOverlays = [];
+  function clearOverlays(overlays) {
+    overlays.forEach((overlay) => overlay.remove());
+  }
+  function renderOverlays(mode, sourceElement) {
+    const selectorId = getElementSelectorId(sourceElement, attributeName);
+    if (!selectorId) {
+      return [];
+    }
+    return findMatchingElements(selectorId, attributeName, targetDocument).map((element) => {
+      const overlay = createOverlay(mode, targetDocument);
+      positionOverlay(overlay, element, targetWindow);
+      targetDocument.body.appendChild(overlay);
+      return overlay;
+    });
+  }
+  function onClick(event) {
+    if (!enableClickSelection) {
+      return;
+    }
+    const selectableElement = getSelectableElement(event.target, attributeName);
+    if (!selectableElement || isOverlayElement(selectableElement)) {
+      return;
+    }
+    clearOverlays(selectedOverlays);
+    selectedOverlays = renderOverlays("selected", selectableElement);
+    parentWindow.postMessage(
+      createMessage("element-selected", selectableElement, attributeName),
+      targetOrigin
+    );
+  }
+  function onMouseMove(event) {
+    if (!enableHover) {
+      return;
+    }
+    const selectableElement = getSelectableElement(event.target, attributeName);
+    clearOverlays(hoverOverlays);
+    hoverOverlays = [];
+    if (!selectableElement || isOverlayElement(selectableElement)) {
+      return;
+    }
+    hoverOverlays = renderOverlays("hover", selectableElement);
+  }
+  targetDocument.addEventListener("click", onClick, true);
+  targetDocument.addEventListener("mousemove", onMouseMove, true);
+  const cleanup = () => {
+    targetDocument.removeEventListener("click", onClick, true);
+    targetDocument.removeEventListener("mousemove", onMouseMove, true);
+    clearOverlays(selectedOverlays);
+    clearOverlays(hoverOverlays);
+    selectedOverlays = [];
+    hoverOverlays = [];
+    if (activeCleanup === cleanup) {
+      activeCleanup = null;
+    }
+  };
+  activeCleanup = cleanup;
+  return {
+    destroy() {
+      cleanup();
+    },
+    clearSelection() {
+      clearOverlays(selectedOverlays);
+      clearOverlays(hoverOverlays);
+      selectedOverlays = [];
+      hoverOverlays = [];
+    }
+  };
+}
+export {
+  setupSelectionBridge
+};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/constants.ts","../src/runtime.ts"],"sourcesContent":["export const DEFAULT_ATTRIBUTE_NAME = 'data-source-location'\nexport const OVERLAY_ATTRIBUTE_NAME = 'data-visual-selector-overlay'\n","import {\n  DEFAULT_ATTRIBUTE_NAME,\n  OVERLAY_ATTRIBUTE_NAME,\n} from './shared/constants'\nimport type {\n  ElementSelectionMessage,\n  SelectionBridgeOptions,\n} from './shared/types'\n\nlet activeCleanup: (() => void) | null = null\n\nfunction getElementSelectorId(element: Element, attributeName: string) {\n  return element.getAttribute(attributeName)\n}\n\nfunction isOverlayElement(element: Element) {\n  return element.hasAttribute(OVERLAY_ATTRIBUTE_NAME)\n}\n\nfunction getSelectableElement(target: EventTarget | null, attributeName: string) {\n  if (!(target instanceof Element)) {\n    return null\n  }\n\n  const closestOverlay = target.closest(`[${OVERLAY_ATTRIBUTE_NAME}]`)\n  if (closestOverlay) {\n    return null\n  }\n\n  return target.closest<HTMLElement>(`[${attributeName}]`)\n}\n\nfunction findMatchingElements(selectorId: string, attributeName: string, root: Document) {\n  return Array.from(\n    root.querySelectorAll<HTMLElement>(`[${attributeName}=\"${selectorId}\"]`),\n  )\n}\n\nfunction createOverlay(mode: 'hover' | 'selected', doc: Document) {\n  const overlay = doc.createElement('div')\n  overlay.setAttribute(OVERLAY_ATTRIBUTE_NAME, mode)\n  overlay.style.position = 'absolute'\n  overlay.style.pointerEvents = 'none'\n  overlay.style.zIndex = '9999'\n  overlay.style.transition = 'all 0.1s ease-in-out'\n\n  if (mode === 'selected') {\n    overlay.style.border = '2px solid #2563EB'\n  } else {\n    overlay.style.border = '2px solid #95a5fc'\n    overlay.style.backgroundColor = 'rgba(99, 102, 241, 0.05)'\n  }\n\n  return overlay\n}\n\nfunction positionOverlay(overlay: HTMLDivElement, target: HTMLElement, view: Window) {\n  const rect = target.getBoundingClientRect()\n  overlay.style.top = `${rect.top + view.scrollY}px`\n  overlay.style.left = `${rect.left + view.scrollX}px`\n  overlay.style.width = `${rect.width}px`\n  overlay.style.height = `${rect.height}px`\n}\n\nfunction createMessage(\n  type: 'element-selected' | 'element-hovered',\n  element: HTMLElement,\n  attributeName: string,\n): ElementSelectionMessage {\n  const rect = element.getBoundingClientRect()\n\n  return {\n    type,\n    tagName: element.tagName,\n    className: element.className,\n    selectorId: getElementSelectorId(element, attributeName),\n    dataSourceLocation: getElementSelectorId(element, attributeName),\n    rect: {\n      top: rect.top,\n      left: rect.left,\n      right: rect.right,\n      bottom: rect.bottom,\n      width: rect.width,\n      height: rect.height,\n    },\n  }\n}\n\nexport function setupSelectionBridge(\n  options: SelectionBridgeOptions = {},\n) {\n  activeCleanup?.()\n\n  const targetWindow = options.targetWindow ?? window\n  const targetDocument = targetWindow.document\n  const parentWindow = options.parentWindow ?? window.parent\n  const attributeName = options.attributeName ?? DEFAULT_ATTRIBUTE_NAME\n  const targetOrigin = options.targetOrigin ?? '*'\n  const enableHover = options.enableHover ?? true\n  const enableClickSelection = options.enableClickSelection ?? true\n\n  let selectedOverlays: HTMLDivElement[] = []\n  let hoverOverlays: HTMLDivElement[] = []\n\n  function clearOverlays(overlays: HTMLDivElement[]) {\n    overlays.forEach((overlay) => overlay.remove())\n  }\n\n  function renderOverlays(mode: 'hover' | 'selected', sourceElement: HTMLElement) {\n    const selectorId = getElementSelectorId(sourceElement, attributeName)\n    if (!selectorId) {\n      return []\n    }\n\n    return findMatchingElements(selectorId, attributeName, targetDocument).map((element) => {\n      const overlay = createOverlay(mode, targetDocument)\n      positionOverlay(overlay, element, targetWindow)\n      targetDocument.body.appendChild(overlay)\n      return overlay\n    })\n  }\n\n  function onClick(event: MouseEvent) {\n    if (!enableClickSelection) {\n      return\n    }\n\n    const selectableElement = getSelectableElement(event.target, attributeName)\n    if (!selectableElement || isOverlayElement(selectableElement)) {\n      return\n    }\n\n    clearOverlays(selectedOverlays)\n    selectedOverlays = renderOverlays('selected', selectableElement)\n    parentWindow.postMessage(\n      createMessage('element-selected', selectableElement, attributeName),\n      targetOrigin,\n    )\n  }\n\n  function onMouseMove(event: MouseEvent) {\n    if (!enableHover) {\n      return\n    }\n\n    const selectableElement = getSelectableElement(event.target, attributeName)\n    clearOverlays(hoverOverlays)\n    hoverOverlays = []\n\n    if (!selectableElement || isOverlayElement(selectableElement)) {\n      return\n    }\n\n    hoverOverlays = renderOverlays('hover', selectableElement)\n  }\n\n  targetDocument.addEventListener('click', onClick, true)\n  targetDocument.addEventListener('mousemove', onMouseMove, true)\n\n  const cleanup = () => {\n    targetDocument.removeEventListener('click', onClick, true)\n    targetDocument.removeEventListener('mousemove', onMouseMove, true)\n    clearOverlays(selectedOverlays)\n    clearOverlays(hoverOverlays)\n    selectedOverlays = []\n    hoverOverlays = []\n    if (activeCleanup === cleanup) {\n      activeCleanup = null\n    }\n  }\n\n  activeCleanup = cleanup\n\n  return {\n    destroy() {\n      cleanup()\n    },\n    clearSelection() {\n      clearOverlays(selectedOverlays)\n      clearOverlays(hoverOverlays)\n      selectedOverlays = []\n      hoverOverlays = []\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types-DlgpChn_.d.ts

@@ -0,0 +1,16 @@
+interface VisualSelectorPluginOptions {
+    include?: RegExp[];
+    exclude?: RegExp[];
+    attributeName?: string;
+    root?: string;
+}
+interface SelectionBridgeOptions {
+    attributeName?: string;
+    targetWindow?: Window;
+    parentWindow?: Pick<Window, 'postMessage'>;
+    targetOrigin?: string;
+    enableHover?: boolean;
+    enableClickSelection?: boolean;
+}
+
+export type { SelectionBridgeOptions as S, VisualSelectorPluginOptions as V };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "vite-plugin-visual-selector",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "demo": "vite --config demo/vite.config.ts"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "@babel/parser": "^7.27.0",
+    "@babel/traverse": "^7.27.0",
+    "@babel/types": "^7.27.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "jsdom": "^26.0.0",
+    "magic-string": "^0.30.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0",
+    "vite": "^6.0.0",
+    "vitest": "^3.0.0"
+  }
+}