semantic-inspector 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 semantic-inspector contributors
+Copyright (c) 2026 ghost-vk and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,13 +1,23 @@
 # semantic-inspector
 
-A dev-only React inspector for vibe-coding. Hit a hotkey to enter inspect mode:
-hovering highlights the element under the cursor and shows its component name +
-`file:line`. **Click** copies that text identifier to the clipboard;
-**Shift+click** copies a PNG screenshot of just that element. Built for pasting
-precise UI context into an AI chat in seconds.
+[![npm version](https://img.shields.io/npm/v/semantic-inspector.svg)](https://www.npmjs.com/package/semantic-inspector)
+[![CI](https://github.com/ghost-vk/semantic-inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/ghost-vk/semantic-inspector/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/semantic-inspector.svg)](./LICENSE)
 
-Stack: Vite + `@vitejs/plugin-react` + React 18/19. Zero runtime cost in
-production — you gate where it mounts.
+A dev-only React inspector for vibe-coding. Hit a hotkey to enter inspect mode: hovering highlights
+the element under the cursor and shows its component name + `file:line:col`. **Click** copies that
+text identifier to the clipboard; **Shift+click** copies a PNG screenshot of just that element.
+Built for pasting precise UI context into an AI chat in seconds.
+
+Stack: Vite + `@vitejs/plugin-react` + React 18/19. Designed to add **no production runtime cost
+when you gate and lazy-load it** (see [Mount it](#2-mount-it-behind-your-own-dev-flag-ideally-lazy)) —
+`modern-screenshot` is loaded lazily and the source-stamping plugin runs only on the dev server.
+
+## Demo
+
+<video src="https://github.com/ghost-vk/semantic-inspector/raw/main/docs/demo.mp4" controls muted loop width="600"></video>
+
+_Player not loading? [Watch the demo.](https://github.com/ghost-vk/semantic-inspector/raw/main/docs/demo.mp4)_
 
 ## Install
 
@@ -15,31 +25,49 @@ production — you gate where it mounts.
 npm i -D semantic-inspector
 ```
 
-`react` / `react-dom` are peer deps (>=18). `vite` is an optional peer — only
-needed if you use the Vite plugin entry point.
+Peer dependencies:
+
+- `react` / `react-dom` (`>=18`) — required.
+- `vite` (`>=5`) — optional, only for `semantic-inspector/vite`.
+- `@babel/core` (`>=7.25`) — optional, only for `semantic-inspector/vite` or
+  `semantic-inspector/babel`. Most Vite + React projects already have it; if not:
+  ```sh
+  npm i -D @babel/core
+  ```
+  Pure-runtime consumers (`<SemanticInspector/>` only) don't need it.
 
 ## How it works
 
-Source locations come from a **build-time stamp**, not React internals. A Babel
-pass adds `data-loc="<path>:<line>"` and `data-comp="<Component>"` to JSX host
-elements (`div`, `section`, …). The runtime reads those DOM attributes, so it
-stays robust across React versions. If a node isn't stamped (prod build, foreign
-node), it degrades gracefully: fiber `displayName` → filename → tag name.
+Source locations come from a **build-time stamp**, not React internals. A Babel pass adds
+`data-loc="<path>:<line>:<col>"` and `data-comp="<Component>"` to JSX host elements (`div`,
+`section`, …). The runtime reads those DOM attributes, so it stays robust across React versions. If
+a node isn't stamped (prod build, foreign node), it degrades gracefully: fiber `displayName` →
+filename → tag name.
+
+```mermaid
+flowchart LR
+  A[".tsx source"] -->|"Babel: stampLocVite / stampLocBabel<br/>(dev only)"| B["DOM with data-loc / data-comp"]
+  B -->|"hover → elementFromPoint"| C["resolveTarget<br/>closest([data-loc])"]
+  C --> D["Overlay highlight + tip"]
+  C -->|"click"| E["clipboard: text"]
+  C -->|"Shift+click"| F["clipboard: PNG (modern-screenshot)"]
+```
 
 ## Three entry points
 
-| Import                          | What it is                                                              |
-| ------------------------------- | ---------------------------------------------------------------------- |
-| `semantic-inspector`            | `<SemanticInspector/>` — the overlay + hotkey + clipboard runtime.     |
-| `semantic-inspector/vite`       | `stampLocVite()` — Vite plugin that stamps `data-loc` / `data-comp`.   |
-| `semantic-inspector/babel`      | Raw Babel plugin, for the babel variant of `@vitejs/plugin-react`.     |
+| Import                     | What it is                                                          |
+| -------------------------- | ------------------------------------------------------------------ |
+| `semantic-inspector`       | `<SemanticInspector/>` + `useInspector()` — overlay/hotkey/clipboard runtime. |
+| `semantic-inspector/vite`  | `stampLocVite()` — Vite plugin that stamps `data-loc` / `data-comp`. |
+| `semantic-inspector/babel` | `{ stampLocBabel }` — raw Babel plugin, for the Babel variant of `@vitejs/plugin-react`. |
 
 ## Usage
 
 ### 1. Stamp source locations (Vite plugin)
 
-`@vitejs/plugin-react` **v6** transpiles via oxc (no Babel hook), so stamp with a
-separate `pre` plugin:
+`@vitejs/plugin-react` **v6** transpiles via oxc (no Babel hook), so stamp with a separate `pre`
+plugin. **This is the recommended path.** The plugin runs only on the dev server (`apply: 'serve'`),
+so `data-loc` / `data-comp` never reach a production build.
 
 ```ts
 import react from '@vitejs/plugin-react';
@@ -52,15 +80,24 @@ export default defineConfig({
 });
 ```
 
-`rootDir` is the base for the relative path written into `data-loc`.
-
-On the **Babel variant** of plugin-react you can skip the separate pre-pass:
+On the **Babel variant** of plugin-react you can skip the separate pre-pass by adding the plugin to
+plugin-react's Babel options instead. Use **one** approach, not both. Note this forces plugin-react
+onto Babel for all files (slower than the oxc + pre-pass above), so prefer option 1 unless you're
+already on the Babel variant. Gate it to development so stamps stay out of production:
 
 ```ts
 import react from '@vitejs/plugin-react';
-import stampLoc from 'semantic-inspector/babel';
-
-react({ babel: { plugins: [[stampLoc, { rootDir: process.cwd() }]] } });
+import { stampLocBabel } from 'semantic-inspector/babel';
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    react({
+      babel: {
+        plugins: command === 'serve' ? [[stampLocBabel, { rootDir: process.cwd() }]] : []
+      }
+    })
+  ]
+}));
 ```
 
 ### 2. Mount it (behind your own dev flag, ideally lazy)
@@ -81,33 +118,67 @@ const SemanticInspector = lazy(() =>
 }
 ```
 
-## Props
+## API
 
-| prop         | default                  | purpose                                  |
-| ------------ | ------------------------ | ---------------------------------------- |
-| `hotkey`     | `'Alt+Shift+S'`          | toggle inspect mode (Esc exits)          |
-| `formatText` | `` `${comp} — ${loc}` `` | format of the text copied on click       |
-| `onCopy`     | —                        | callback after a copy (telemetry/toasts) |
-| `onError`    | —                        | callback on clipboard/screenshot failure |
+### `<SemanticInspector>` props
 
-## Notes
+| prop         | default                  | purpose                                   |
+| ------------ | ------------------------ | ----------------------------------------- |
+| `hotkey`     | `'Alt+Shift+S'`          | toggle inspect mode (Esc always exits)    |
+| `formatText` | `` `${comp} — ${loc}` `` | format of the text copied on click; receives `{ comp, loc }` (`loc` may be `null`) |
+| `onCopy`     | —                        | called after a successful copy            |
+| `onError`    | —                        | called on a clipboard/screenshot failure  |
 
-- `navigator.clipboard` requires a secure context (localhost / https) and a
-  user gesture — that's why copy happens on **click**, not hover.
-- Screenshots use `modern-screenshot` (DOM→canvas): cross-origin `<img>` without
-  CORS and some exotic CSS may not render.
-- On a prod React build without `data-loc`, the name falls back to the fiber
-  (minified) or tag — degraded mode. Full mode needs the build-time stamp.
+`useInspector(props)` is also exported for building a custom overlay; it returns
+`{ active, target }`. Note: used raw (not via `<SemanticInspector>`), it has no default `onError`,
+so failures only surface via `console.warn` unless you pass one.
 
-## Development
+#### Callback payloads
 
-```sh
-npm install
-npm test         # vitest
-npm run typecheck
-npm run build    # tsup -> dist/ (esm + cjs + d.ts)
-```
+- `onCopy('text', payload)` — `payload` is the copied string.
+- `onCopy('screenshot', payload)` — `payload` is the **component name** (the PNG goes to the
+  clipboard, not to the callback).
+- `onError(kind, err)` — `err` is the underlying error (`unknown`).
+
+### Plugin options (`stampLocVite` / `stampLocBabel`)
+
+| option     | default          | applies to   | purpose                                        |
+| ---------- | ---------------- | ------------ | ---------------------------------------------- |
+| `rootDir`  | `process.cwd()`  | both         | base for the relative path written into `data-loc` |
+| `include`  | `/\.[jt]sx$/`    | `/vite` only | which module ids get stamped                   |
+| `attrLoc`  | `'data-loc'`     | both         | attribute name for `path:line:col`             |
+| `attrComp` | `'data-comp'`    | both         | attribute name for the component name          |
+
+Files outside `rootDir` degrade to their basename, so an absolute filesystem path never leaks into
+the stamped DOM.
+
+## Hotkey format
+
+`Modifier+...+Key`. Modifiers: `Alt`, `Shift`, `Ctrl` (or `Control`), `Meta` (or `Cmd`). The final
+token is the key. Matching is case-insensitive and also matches the physical `event.code`, so
+layout-shifted glyphs work (e.g. `Ctrl+Shift+/` matches even though Shift produces `?`). Digit and
+punctuation keys are supported (`Alt+1`, `Ctrl+/`). `Esc` always exits inspect mode.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Nothing copies, no error | `navigator.clipboard` needs a secure context | Use `localhost` or `https://`, not `http://192.168.x.x` |
+| Screenshot is blank/partial | CORS-tainted canvas / unsupported CSS | Serve images with CORS headers; some CSS (cross-origin `<img>`, exotic filters) won't rasterize |
+| `loc` shows `no source` / name is minified | Node wasn't stamped (prod build, or plugin not registered) | Register the stamper (Usage 1) and confirm it isn't gated out in dev |
+| Hotkey does nothing | Focus is in an input, or a typo in the combo | Use a `Modifier+Key` combo (see above); try the default `Alt+Shift+S` |
+
+## Browser support
+
+Works in current Chromium, Edge, Firefox, and Safari. Image-clipboard (Shift+click screenshot)
+requires a `ClipboardItem`-capable browser; text copy works everywhere with a secure context.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). In short: `npm ci`, then
+`npm run lint && npm run typecheck && npm test && npm run build`. `dist/` is generated — build once
+after cloning before `npm link`.
 
 ## License
 
-MIT
+[MIT](./LICENSE) © ghost-vk

package/dist/babel.cjs

@@ -1,64 +1,12 @@
 'use strict';
 
-// src/stampLocBabel.ts
-function isHostElement(name) {
-  return name.type === "JSXIdentifier" && /^[a-z]/.test(name.name);
-}
-function hasAttr(el, attrName) {
-  return el.attributes.some(
-    (a) => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && a.name.name === attrName
-  );
-}
-function nearestComponentName(path) {
-  let p = path;
-  while (p) {
-    const node = p.node;
-    if (node.type === "FunctionDeclaration" && node.id && /^[A-Z]/.test(node.id.name)) {
-      return node.id.name;
-    }
-    if (node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
-      const parent = p.parentPath?.node;
-      if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier" && /^[A-Z]/.test(parent.id.name)) {
-        return parent.id.name;
-      }
-    }
-    p = p.parentPath;
-  }
-  return null;
-}
-function stampLocBabel(babel, opts = {}) {
-  const t = babel.types;
-  const attrLoc = opts.attrLoc ?? "data-loc";
-  const attrComp = opts.attrComp ?? "data-comp";
-  const rootDir = opts.rootDir ?? process.cwd();
-  const attr = (name, value) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));
-  const toRel = (file) => {
-    let root = rootDir;
-    while (root.endsWith("/")) root = root.slice(0, -1);
-    const rel = file.startsWith(root + "/") ? file.slice(root.length + 1) : file;
-    return rel.split("\\").join("/");
-  };
-  return {
-    name: "stamp-loc",
-    visitor: {
-      JSXOpeningElement(path, state) {
-        const node = path.node;
-        if (!isHostElement(node.name)) return;
-        const filename = state.file.opts.filename;
-        const loc = node.loc;
-        if (!filename || !loc) return;
-        if (!hasAttr(node, attrLoc)) {
-          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}`));
-        }
-        if (!hasAttr(node, attrComp)) {
-          const comp = nearestComponentName(path);
-          if (comp) node.attributes.push(attr(attrComp, comp));
-        }
-      }
-    }
-  };
-}
+var chunkX6NMJJ2M_cjs = require('./chunk-X6NMJJ2M.cjs');
 
-module.exports = stampLocBabel;
+
+
+Object.defineProperty(exports, "stampLocBabel", {
+  enumerable: true,
+  get: function () { return chunkX6NMJJ2M_cjs.stampLocBabel; }
+});
 //# sourceMappingURL=babel.cjs.map
 //# sourceMappingURL=babel.cjs.map

package/dist/babel.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/stampLocBabel.ts"],"names":[],"mappings":"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","file":"babel.cjs","sourcesContent":["import type { NodePath, PluginObj, types as BabelTypes } from '@babel/core';\n\nexport interface StampLocOptions {\n  /** Имя атрибута пути. Default 'data-loc'. */\n  attrLoc?: string;\n  /** Имя атрибута компонента. Default 'data-comp'. */\n  attrComp?: string;\n  /** База для относительного пути в data-loc. Default process.cwd(). */\n  rootDir?: string;\n}\n\nfunction isHostElement(name: BabelTypes.JSXOpeningElement['name']): boolean {\n  return name.type === 'JSXIdentifier' && /^[a-z]/.test(name.name);\n}\n\nfunction hasAttr(el: BabelTypes.JSXOpeningElement, attrName: string): boolean {\n  return el.attributes.some(\n    (a) => a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === attrName\n  );\n}\n\n// Ближайшая функция-компонент с PascalCase-именем вверх по дереву:\n//   function Foo() {}  |  const Foo = () => {}  |  const Foo = function () {}\nfunction nearestComponentName(path: NodePath): string | null {\n  let p: NodePath | null = path;\n  while (p) {\n    const node = p.node;\n    if (node.type === 'FunctionDeclaration' && node.id && /^[A-Z]/.test(node.id.name)) {\n      return node.id.name;\n    }\n    if (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {\n      const parent = p.parentPath?.node;\n      if (parent?.type === 'VariableDeclarator' && parent.id.type === 'Identifier' && /^[A-Z]/.test(parent.id.name)) {\n        return parent.id.name;\n      }\n    }\n    p = p.parentPath;\n  }\n  return null;\n}\n\n/**\n * Babel-плагин: вешает data-loc=\"<path>:<line>\" и data-comp=\"<Component>\" на\n * JSX host-элементы (div, section, ...). Рантайм-инспектор читает эти DOM-атрибуты\n * (не React-internals), поэтому устойчив к версии React. Компонентные теги\n * (PascalCase) пропускаем — они не дают собственного DOM-узла.\n */\nexport default function stampLocBabel(babel: { types: typeof BabelTypes }, opts: StampLocOptions = {}): PluginObj {\n  const t = babel.types;\n  const attrLoc = opts.attrLoc ?? 'data-loc';\n  const attrComp = opts.attrComp ?? 'data-comp';\n  const rootDir = opts.rootDir ?? process.cwd();\n\n  const attr = (name: string, value: string) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));\n\n  // path.relative без node:path, чтобы плагин не тянул узловые модули в чужих средах.\n  const toRel = (file: string): string => {\n    let root = rootDir;\n    while (root.endsWith('/')) root = root.slice(0, -1);\n    const rel = file.startsWith(root + '/') ? file.slice(root.length + 1) : file;\n    return rel.split('\\\\').join('/');\n  };\n\n  return {\n    name: 'stamp-loc',\n    visitor: {\n      JSXOpeningElement(path, state) {\n        const node = path.node;\n        if (!isHostElement(node.name)) return;\n\n        const filename = state.file.opts.filename;\n        const loc = node.loc;\n        if (!filename || !loc) return;\n\n        if (!hasAttr(node, attrLoc)) {\n          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}`));\n        }\n        if (!hasAttr(node, attrComp)) {\n          const comp = nearestComponentName(path);\n          if (comp) node.attributes.push(attr(attrComp, comp));\n        }\n      }\n    }\n  };\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"babel.cjs"}

package/dist/babel.d.cts

@@ -1,21 +1,21 @@
-import { types, PluginObj } from '@babel/core';
+import { ConfigAPI, types, PluginObj } from '@babel/core';
 
 interface StampLocOptions {
-    /** Имя атрибута пути. Default 'data-loc'. */
+    /** Path attribute name. Default 'data-loc'. */
     attrLoc?: string;
-    /** Имя атрибута компонента. Default 'data-comp'. */
+    /** Component attribute name. Default 'data-comp'. */
     attrComp?: string;
-    /** База для относительного пути в data-loc. Default process.cwd(). */
+    /** Base for the relative path written into data-loc. Default process.cwd(). */
     rootDir?: string;
 }
 /**
- * Babel-плагин: вешает data-loc="<path>:<line>" и data-comp="<Component>" на
- * JSX host-элементы (div, section, ...). Рантайм-инспектор читает эти DOM-атрибуты
- * (не React-internals), поэтому устойчив к версии React. Компонентные теги
- * (PascalCase) пропускаем — они не дают собственного DOM-узла.
+ * Babel plugin: stamps data-loc="<path>:<line>:<col>" and data-comp="<Component>" onto JSX
+ * host elements (div, section, ...). The runtime inspector reads these DOM attributes (not
+ * React internals), so it stays robust across React versions. Component tags (PascalCase) are
+ * skipped — they don't produce their own DOM node.
  */
-declare function stampLocBabel(babel: {
+declare function stampLocBabel(api: ConfigAPI & {
     types: typeof types;
 }, opts?: StampLocOptions): PluginObj;
 
-export { type StampLocOptions, stampLocBabel as default };
+export { type StampLocOptions, stampLocBabel };

package/dist/babel.d.ts

@@ -1,21 +1,21 @@
-import { types, PluginObj } from '@babel/core';
+import { ConfigAPI, types, PluginObj } from '@babel/core';
 
 interface StampLocOptions {
-    /** Имя атрибута пути. Default 'data-loc'. */
+    /** Path attribute name. Default 'data-loc'. */
     attrLoc?: string;
-    /** Имя атрибута компонента. Default 'data-comp'. */
+    /** Component attribute name. Default 'data-comp'. */
     attrComp?: string;
-    /** База для относительного пути в data-loc. Default process.cwd(). */
+    /** Base for the relative path written into data-loc. Default process.cwd(). */
     rootDir?: string;
 }
 /**
- * Babel-плагин: вешает data-loc="<path>:<line>" и data-comp="<Component>" на
- * JSX host-элементы (div, section, ...). Рантайм-инспектор читает эти DOM-атрибуты
- * (не React-internals), поэтому устойчив к версии React. Компонентные теги
- * (PascalCase) пропускаем — они не дают собственного DOM-узла.
+ * Babel plugin: stamps data-loc="<path>:<line>:<col>" and data-comp="<Component>" onto JSX
+ * host elements (div, section, ...). The runtime inspector reads these DOM attributes (not
+ * React internals), so it stays robust across React versions. Component tags (PascalCase) are
+ * skipped — they don't produce their own DOM node.
  */
-declare function stampLocBabel(babel: {
+declare function stampLocBabel(api: ConfigAPI & {
     types: typeof types;
 }, opts?: StampLocOptions): PluginObj;
 
-export { type StampLocOptions, stampLocBabel as default };
+export { type StampLocOptions, stampLocBabel };

package/dist/babel.js

@@ -1,3 +1,3 @@
-export { stampLocBabel as default } from './chunk-AAPCI2HO.js';
+export { stampLocBabel } from './chunk-AQYKTX6L.js';
 //# sourceMappingURL=babel.js.map
 //# sourceMappingURL=babel.js.map

package/dist/{chunk-AAPCI2HO.js → chunk-AQYKTX6L.js}

@@ -1,3 +1,5 @@
+import { relative, isAbsolute, sep } from 'path';
+
 // src/stampLocBabel.ts
 function isHostElement(name) {
   return name.type === "JSXIdentifier" && /^[a-z]/.test(name.name);
@@ -24,17 +26,19 @@ function nearestComponentName(path) {
   }
   return null;
 }
-function stampLocBabel(babel, opts = {}) {
-  const t = babel.types;
+function stampLocBabel(api, opts = {}) {
+  api.assertVersion(7);
+  const t = api.types;
   const attrLoc = opts.attrLoc ?? "data-loc";
   const attrComp = opts.attrComp ?? "data-comp";
   const rootDir = opts.rootDir ?? process.cwd();
   const attr = (name, value) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));
   const toRel = (file) => {
-    let root = rootDir;
-    while (root.endsWith("/")) root = root.slice(0, -1);
-    const rel = file.startsWith(root + "/") ? file.slice(root.length + 1) : file;
-    return rel.split("\\").join("/");
+    const rel = relative(rootDir, file);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+      return file.split(/[\\/]/).pop() ?? "unknown";
+    }
+    return rel.split(sep).join("/");
   };
   return {
     name: "stamp-loc",
@@ -46,7 +50,7 @@ function stampLocBabel(babel, opts = {}) {
         const loc = node.loc;
         if (!filename || !loc) return;
         if (!hasAttr(node, attrLoc)) {
-          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}`));
+          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}:${loc.start.column + 1}`));
         }
         if (!hasAttr(node, attrComp)) {
           const comp = nearestComponentName(path);
@@ -58,5 +62,5 @@ function stampLocBabel(babel, opts = {}) {
 }
 
 export { stampLocBabel };
-//# sourceMappingURL=chunk-AAPCI2HO.js.map
-//# sourceMappingURL=chunk-AAPCI2HO.js.map
+//# sourceMappingURL=chunk-AQYKTX6L.js.map
+//# sourceMappingURL=chunk-AQYKTX6L.js.map

package/dist/chunk-AQYKTX6L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stampLocBabel.ts"],"names":[],"mappings":"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","file":"chunk-AQYKTX6L.js","sourcesContent":["import { isAbsolute, relative, sep } from 'node:path';\nimport type { types as BabelTypes, ConfigAPI, NodePath, PluginObj } from '@babel/core';\n\nexport interface StampLocOptions {\n  /** Path attribute name. Default 'data-loc'. */\n  attrLoc?: string;\n  /** Component attribute name. Default 'data-comp'. */\n  attrComp?: string;\n  /** Base for the relative path written into data-loc. Default process.cwd(). */\n  rootDir?: string;\n}\n\nfunction isHostElement(name: BabelTypes.JSXOpeningElement['name']): boolean {\n  return name.type === 'JSXIdentifier' && /^[a-z]/.test(name.name);\n}\n\nfunction hasAttr(el: BabelTypes.JSXOpeningElement, attrName: string): boolean {\n  return el.attributes.some(\n    (a) => a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === attrName\n  );\n}\n\n// Nearest PascalCase function-component ancestor:\n//   function Foo() {}  |  const Foo = () => {}  |  const Foo = function () {}\nfunction nearestComponentName(path: NodePath): string | null {\n  let p: NodePath | null = path;\n  while (p) {\n    const node = p.node;\n    if (node.type === 'FunctionDeclaration' && node.id && /^[A-Z]/.test(node.id.name)) {\n      return node.id.name;\n    }\n    if (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {\n      const parent = p.parentPath?.node;\n      if (parent?.type === 'VariableDeclarator' && parent.id.type === 'Identifier' && /^[A-Z]/.test(parent.id.name)) {\n        return parent.id.name;\n      }\n    }\n    p = p.parentPath;\n  }\n  return null;\n}\n\n/**\n * Babel plugin: stamps data-loc=\"<path>:<line>:<col>\" and data-comp=\"<Component>\" onto JSX\n * host elements (div, section, ...). The runtime inspector reads these DOM attributes (not\n * React internals), so it stays robust across React versions. Component tags (PascalCase) are\n * skipped — they don't produce their own DOM node.\n */\nexport function stampLocBabel(api: ConfigAPI & { types: typeof BabelTypes }, opts: StampLocOptions = {}): PluginObj {\n  api.assertVersion(7);\n  const t = api.types;\n  const attrLoc = opts.attrLoc ?? 'data-loc';\n  const attrComp = opts.attrComp ?? 'data-comp';\n  const rootDir = opts.rootDir ?? process.cwd();\n\n  const attr = (name: string, value: string) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));\n\n  // Relative POSIX path from rootDir. Files outside rootDir degrade to their basename so an\n  // absolute filesystem path can never leak into the stamped DOM.\n  const toRel = (file: string): string => {\n    const rel = relative(rootDir, file);\n    if (!rel || rel.startsWith('..') || isAbsolute(rel)) {\n      return file.split(/[\\\\/]/).pop() ?? 'unknown';\n    }\n    return rel.split(sep).join('/');\n  };\n\n  return {\n    name: 'stamp-loc',\n    visitor: {\n      JSXOpeningElement(path, state) {\n        const node = path.node;\n        if (!isHostElement(node.name)) return;\n\n        const filename = state.file.opts.filename;\n        const loc = node.loc;\n        if (!filename || !loc) return;\n\n        if (!hasAttr(node, attrLoc)) {\n          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}:${loc.start.column + 1}`));\n        }\n        if (!hasAttr(node, attrComp)) {\n          const comp = nearestComponentName(path);\n          if (comp) node.attributes.push(attr(attrComp, comp));\n        }\n      }\n    }\n  };\n}\n"]}

package/dist/chunk-X6NMJJ2M.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+var path = require('path');
+
+// src/stampLocBabel.ts
+function isHostElement(name) {
+  return name.type === "JSXIdentifier" && /^[a-z]/.test(name.name);
+}
+function hasAttr(el, attrName) {
+  return el.attributes.some(
+    (a) => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && a.name.name === attrName
+  );
+}
+function nearestComponentName(path) {
+  let p = path;
+  while (p) {
+    const node = p.node;
+    if (node.type === "FunctionDeclaration" && node.id && /^[A-Z]/.test(node.id.name)) {
+      return node.id.name;
+    }
+    if (node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
+      const parent = p.parentPath?.node;
+      if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier" && /^[A-Z]/.test(parent.id.name)) {
+        return parent.id.name;
+      }
+    }
+    p = p.parentPath;
+  }
+  return null;
+}
+function stampLocBabel(api, opts = {}) {
+  api.assertVersion(7);
+  const t = api.types;
+  const attrLoc = opts.attrLoc ?? "data-loc";
+  const attrComp = opts.attrComp ?? "data-comp";
+  const rootDir = opts.rootDir ?? process.cwd();
+  const attr = (name, value) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));
+  const toRel = (file) => {
+    const rel = path.relative(rootDir, file);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+      return file.split(/[\\/]/).pop() ?? "unknown";
+    }
+    return rel.split(path.sep).join("/");
+  };
+  return {
+    name: "stamp-loc",
+    visitor: {
+      JSXOpeningElement(path, state) {
+        const node = path.node;
+        if (!isHostElement(node.name)) return;
+        const filename = state.file.opts.filename;
+        const loc = node.loc;
+        if (!filename || !loc) return;
+        if (!hasAttr(node, attrLoc)) {
+          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}:${loc.start.column + 1}`));
+        }
+        if (!hasAttr(node, attrComp)) {
+          const comp = nearestComponentName(path);
+          if (comp) node.attributes.push(attr(attrComp, comp));
+        }
+      }
+    }
+  };
+}
+
+exports.stampLocBabel = stampLocBabel;
+//# sourceMappingURL=chunk-X6NMJJ2M.cjs.map
+//# sourceMappingURL=chunk-X6NMJJ2M.cjs.map

package/dist/chunk-X6NMJJ2M.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stampLocBabel.ts"],"names":["relative","isAbsolute","sep"],"mappings":";;;;;AAYA,SAAS,cAAc,IAAA,EAAqD;AAC1E,EAAA,OAAO,KAAK,IAAA,KAAS,eAAA,IAAmB,QAAA,CAAS,IAAA,CAAK,KAAK,IAAI,CAAA;AACjE;AAEA,SAAS,OAAA,CAAQ,IAAkC,QAAA,EAA2B;AAC5E,EAAA,OAAO,GAAG,UAAA,CAAW,IAAA;AAAA,IACnB,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,KAAS,cAAA,IAAkB,CAAA,CAAE,IAAA,CAAK,IAAA,KAAS,eAAA,IAAmB,CAAA,CAAE,IAAA,CAAK,IAAA,KAAS;AAAA,GACzF;AACF;AAIA,SAAS,qBAAqB,IAAA,EAA+B;AAC3D,EAAA,IAAI,CAAA,GAAqB,IAAA;AACzB,EAAA,OAAO,CAAA,EAAG;AACR,IAAA,MAAM,OAAO,CAAA,CAAE,IAAA;AACf,IAAA,IAAI,IAAA,CAAK,IAAA,KAAS,qBAAA,IAAyB,IAAA,CAAK,EAAA,IAAM,SAAS,IAAA,CAAK,IAAA,CAAK,EAAA,CAAG,IAAI,CAAA,EAAG;AACjF,MAAA,OAAO,KAAK,EAAA,CAAG,IAAA;AAAA,IACjB;AACA,IAAA,IAAI,IAAA,CAAK,IAAA,KAAS,oBAAA,IAAwB,IAAA,CAAK,SAAS,yBAAA,EAA2B;AACjF,MAAA,MAAM,MAAA,GAAS,EAAE,UAAA,EAAY,IAAA;AAC7B,MAAA,IAAI,MAAA,EAAQ,IAAA,KAAS,oBAAA,IAAwB,MAAA,CAAO,EAAA,CAAG,IAAA,KAAS,YAAA,IAAgB,QAAA,CAAS,IAAA,CAAK,MAAA,CAAO,EAAA,CAAG,IAAI,CAAA,EAAG;AAC7G,QAAA,OAAO,OAAO,EAAA,CAAG,IAAA;AAAA,MACnB;AAAA,IACF;AACA,IAAA,CAAA,GAAI,CAAA,CAAE,UAAA;AAAA,EACR;AACA,EAAA,OAAO,IAAA;AACT;AAQO,SAAS,aAAA,CAAc,GAAA,EAA+C,IAAA,GAAwB,EAAC,EAAc;AAClH,EAAA,GAAA,CAAI,cAAc,CAAC,CAAA;AACnB,EAAA,MAAM,IAAI,GAAA,CAAI,KAAA;AACd,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,IAAW,UAAA;AAChC,EAAA,MAAM,QAAA,GAAW,KAAK,QAAA,IAAY,WAAA;AAClC,EAAA,MAAM,OAAA,GAAU,IAAA,CAAK,OAAA,IAAW,OAAA,CAAQ,GAAA,EAAI;AAE5C,EAAA,MAAM,IAAA,GAAO,CAAC,IAAA,EAAc,KAAA,KAAkB,CAAA,CAAE,YAAA,CAAa,CAAA,CAAE,aAAA,CAAc,IAAI,CAAA,EAAG,CAAA,CAAE,aAAA,CAAc,KAAK,CAAC,CAAA;AAI1G,EAAA,MAAM,KAAA,GAAQ,CAAC,IAAA,KAAyB;AACtC,IAAA,MAAM,GAAA,GAAMA,aAAA,CAAS,OAAA,EAAS,IAAI,CAAA;AAClC,IAAA,IAAI,CAAC,OAAO,GAAA,CAAI,UAAA,CAAW,IAAI,CAAA,IAAKC,eAAA,CAAW,GAAG,CAAA,EAAG;AACnD,MAAA,OAAO,IAAA,CAAK,KAAA,CAAM,OAAO,CAAA,CAAE,KAAI,IAAK,SAAA;AAAA,IACtC;AACA,IAAA,OAAO,GAAA,CAAI,KAAA,CAAMC,QAAG,CAAA,CAAE,KAAK,GAAG,CAAA;AAAA,EAChC,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,WAAA;AAAA,IACN,OAAA,EAAS;AAAA,MACP,iBAAA,CAAkB,MAAM,KAAA,EAAO;AAC7B,QAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAClB,QAAA,IAAI,CAAC,aAAA,CAAc,IAAA,CAAK,IAAI,CAAA,EAAG;AAE/B,QAAA,MAAM,QAAA,GAAW,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,QAAA;AACjC,QAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,QAAA,IAAI,CAAC,QAAA,IAAY,CAAC,GAAA,EAAK;AAEvB,QAAA,IAAI,CAAC,OAAA,CAAQ,IAAA,EAAM,OAAO,CAAA,EAAG;AAC3B,UAAA,IAAA,CAAK,WAAW,IAAA,CAAK,IAAA,CAAK,SAAS,CAAA,EAAG,KAAA,CAAM,QAAQ,CAAC,CAAA,CAAA,EAAI,GAAA,CAAI,KAAA,CAAM,IAAI,CAAA,CAAA,EAAI,GAAA,CAAI,MAAM,MAAA,GAAS,CAAC,EAAE,CAAC,CAAA;AAAA,QACpG;AACA,QAAA,IAAI,CAAC,OAAA,CAAQ,IAAA,EAAM,QAAQ,CAAA,EAAG;AAC5B,UAAA,MAAM,IAAA,GAAO,qBAAqB,IAAI,CAAA;AACtC,UAAA,IAAI,MAAM,IAAA,CAAK,UAAA,CAAW,KAAK,IAAA,CAAK,QAAA,EAAU,IAAI,CAAC,CAAA;AAAA,QACrD;AAAA,MACF;AAAA;AACF,GACF;AACF","file":"chunk-X6NMJJ2M.cjs","sourcesContent":["import { isAbsolute, relative, sep } from 'node:path';\nimport type { types as BabelTypes, ConfigAPI, NodePath, PluginObj } from '@babel/core';\n\nexport interface StampLocOptions {\n  /** Path attribute name. Default 'data-loc'. */\n  attrLoc?: string;\n  /** Component attribute name. Default 'data-comp'. */\n  attrComp?: string;\n  /** Base for the relative path written into data-loc. Default process.cwd(). */\n  rootDir?: string;\n}\n\nfunction isHostElement(name: BabelTypes.JSXOpeningElement['name']): boolean {\n  return name.type === 'JSXIdentifier' && /^[a-z]/.test(name.name);\n}\n\nfunction hasAttr(el: BabelTypes.JSXOpeningElement, attrName: string): boolean {\n  return el.attributes.some(\n    (a) => a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === attrName\n  );\n}\n\n// Nearest PascalCase function-component ancestor:\n//   function Foo() {}  |  const Foo = () => {}  |  const Foo = function () {}\nfunction nearestComponentName(path: NodePath): string | null {\n  let p: NodePath | null = path;\n  while (p) {\n    const node = p.node;\n    if (node.type === 'FunctionDeclaration' && node.id && /^[A-Z]/.test(node.id.name)) {\n      return node.id.name;\n    }\n    if (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {\n      const parent = p.parentPath?.node;\n      if (parent?.type === 'VariableDeclarator' && parent.id.type === 'Identifier' && /^[A-Z]/.test(parent.id.name)) {\n        return parent.id.name;\n      }\n    }\n    p = p.parentPath;\n  }\n  return null;\n}\n\n/**\n * Babel plugin: stamps data-loc=\"<path>:<line>:<col>\" and data-comp=\"<Component>\" onto JSX\n * host elements (div, section, ...). The runtime inspector reads these DOM attributes (not\n * React internals), so it stays robust across React versions. Component tags (PascalCase) are\n * skipped — they don't produce their own DOM node.\n */\nexport function stampLocBabel(api: ConfigAPI & { types: typeof BabelTypes }, opts: StampLocOptions = {}): PluginObj {\n  api.assertVersion(7);\n  const t = api.types;\n  const attrLoc = opts.attrLoc ?? 'data-loc';\n  const attrComp = opts.attrComp ?? 'data-comp';\n  const rootDir = opts.rootDir ?? process.cwd();\n\n  const attr = (name: string, value: string) => t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(value));\n\n  // Relative POSIX path from rootDir. Files outside rootDir degrade to their basename so an\n  // absolute filesystem path can never leak into the stamped DOM.\n  const toRel = (file: string): string => {\n    const rel = relative(rootDir, file);\n    if (!rel || rel.startsWith('..') || isAbsolute(rel)) {\n      return file.split(/[\\\\/]/).pop() ?? 'unknown';\n    }\n    return rel.split(sep).join('/');\n  };\n\n  return {\n    name: 'stamp-loc',\n    visitor: {\n      JSXOpeningElement(path, state) {\n        const node = path.node;\n        if (!isHostElement(node.name)) return;\n\n        const filename = state.file.opts.filename;\n        const loc = node.loc;\n        if (!filename || !loc) return;\n\n        if (!hasAttr(node, attrLoc)) {\n          node.attributes.push(attr(attrLoc, `${toRel(filename)}:${loc.start.line}:${loc.start.column + 1}`));\n        }\n        if (!hasAttr(node, attrComp)) {\n          const comp = nearestComponentName(path);\n          if (comp) node.attributes.push(attr(attrComp, comp));\n        }\n      }\n    }\n  };\n}\n"]}