{"_id":"@coolwork-ai-labs/ui-locator-overlay","name":"@coolwork-ai-labs/ui-locator-overlay","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@coolwork-ai-labs/ui-locator-overlay","version":"0.1.0","description":"Dev-only click-to-source UI locator overlay for React apps","license":"MIT","author":{"name":"sgdream"},"type":"module","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"sideEffects":false,"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit","prepack":"npm run build","prepublishOnly":"npm run typecheck && npm run build","check":"npm run typecheck"},"peerDependencies":{"react":">=18","react-dom":">=18"},"devDependencies":{"@types/node":"^24.3.0","@types/react":"^18.3.12","tsup":"^8.2.4","typescript":"^5.9.2"},"keywords":["react","devtools","ui","debug","overlay","tauri","locator"],"_id":"@coolwork-ai-labs/ui-locator-overlay@0.1.0","gitHead":"bf04bdc7e3ff32c313d02aae55ece65c7c18f5f9","_nodeVersion":"23.5.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-yzmEiB+x601lJkCdtcBHpGjIto8cE6/jKCAdjlpW1istyZbAlv56nrhWL7T9OF9oJwCWrGsBp1o2hHhW6lC9HA==","shasum":"85748fdfb37dc2ce24df8ab4ab4b392ce7d089e9","tarball":"https://registry.npmjs.org/@coolwork-ai-labs/ui-locator-overlay/-/ui-locator-overlay-0.1.0.tgz","fileCount":7,"unpackedSize":36046,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAGYuOBGgulOn66RO6/yWUuI93AwaX5YO2Rsyf/Gbv07AiEAq75rmJuakEhzk6wagtyhHVU1JNH57TtemwzFw+Podao="}]},"_npmUser":{"name":"sgdream","email":"sgdream@foxmail.com"},"directories":{},"maintainers":[{"name":"sgdream","email":"sgdream@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ui-locator-overlay_0.1.0_1771647785501_0.44494650857153295"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-21T04:23:05.392Z","0.1.0":"2026-02-21T04:23:05.644Z","modified":"2026-02-21T04:23:05.902Z"},"maintainers":[{"name":"sgdream","email":"sgdream@foxmail.com"}],"description":"Dev-only click-to-source UI locator overlay for React apps","keywords":["react","devtools","ui","debug","overlay","tauri","locator"],"author":{"name":"sgdream"},"license":"MIT","readme":"# ui-locator-overlay\n\n开发态 UI 定位器：按快捷键进入拾取模式，点击页面元素即可拿到组件名、源码路径、行列号、DOM 选择器与文本预览。\n\n适用场景：Tauri/WebView、Vite、React 管理后台等（不依赖浏览器扩展）。\n\n## 文档导航\n\n- [中文说明（当前）](./README.md)\n- [English README](./README_EN.md)\n- [第三方接入说明（中文）](./README_FOR_USERS.md)\n- [GitHub Repository](https://github.com/coolwork-ai-labs/ui-locator-overlay)\n- [Issues](https://github.com/coolwork-ai-labs/ui-locator-overlay/issues)\n\n## 安装\n\n```bash\nnpm i @coolwork-ai-labs/ui-locator-overlay\n```\n\n## 快速开始（React）\n\n```tsx\nimport { UiLocatorOverlay } from '@coolwork-ai-labs/ui-locator-overlay';\n\nexport default function App() {\n  return (\n    <>\n      {/* your app */}\n      {import.meta.env.DEV ? <UiLocatorOverlay /> : null}\n    </>\n  );\n}\n```\n\n## 默认交互\n\n- `Ctrl + Shift + L`: 开启/关闭定位模式（macOS 支持 `Command + Shift + L`）\n- 点击页面元素：显示定位信息\n- `Esc`: 退出定位模式\n- 面板支持一键复制定位信息\n\n## API\n\n```tsx\n<UiLocatorOverlay\n  enabled={true}\n  devOnly={true}\n  showHintBadge={true}\n  hotkey={{ ctrlOrMeta: true, shift: true, key: 'l' }}\n  zIndex={3000}\n  maxTextLength={120}\n  onInspect={(snapshot) => console.log(snapshot)}\n/>\n```\n\n### Props\n\n- `enabled?: boolean` 是否启用（默认 `true`）\n- `devOnly?: boolean` 仅开发环境启用（默认 `true`）\n- `showHintBadge?: boolean` 非激活态显示右下角提示（默认 `true`）\n- `hotkey?: { ctrlOrMeta?: boolean; shift?: boolean; alt?: boolean; key?: string }` 快捷键配置\n- `zIndex?: number` 覆盖层层级（默认 `3000`）\n- `maxTextLength?: number` 文本预览最大长度（默认 `120`）\n- `onInspect?: (snapshot) => void` 点击定位回调\n- `sourceResolver?: (element) => SourceLocation | null` 自定义源码解析器\n\n### Snapshot 字段\n\n- `elementTag`\n- `selector`\n- `textPreview`\n- `componentName`\n- `fileName`\n- `lineNumber`\n- `columnNumber`\n\n## 关于源码定位\n\n默认实现使用 React Fiber 的开发态调试字段（`_debugSource`）。\n\n- 在 React 开发模式下可获得较好的 `file:line:column`\n- 生产构建或调试字段不可用时，会自动回退（仍可得到选择器与组件名）\n\n## 本地开发\n\n```bash\nnpm install\nnpm run check\nnpm run build\n```\n\n## 发布\n\n```bash\nnpm login --registry=https://registry.npmjs.org --scope=@coolwork-ai-labs --auth-type=legacy\nnpm publish\n```\n","readmeFilename":"README.md","_rev":"1-5ee990b1e9adb1dcdbc843d352adca1c"}