uivisor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kazbek Kabdulov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+<div align="center">
+
+<img src="./uivisor.jpg" alt="uivisor" width="100%" />
+
+<h3>Point at any element in your running app, tweak it by hand, and copy a precise,<br/>breakpoint-aware prompt for your AI agent — without ever touching your code.</h3>
+
+<p>
+  <img alt="dev only" src="https://img.shields.io/badge/dev--only-never%20ships%20to%20prod-22c55e?style=flat-square" />
+  <img alt="stack" src="https://img.shields.io/badge/React%20·%20Next.js%20·%20Vite-4f46e5?style=flat-square" />
+  <img alt="prompt only" src="https://img.shields.io/badge/prompt--only-no%20code%20mutation-06b6d4?style=flat-square" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-3f3f46?style=flat-square" />
+</p>
+
+</div>
+
+---
+
+## The problem
+
+You spot a small UI nit in your running app — this padding's too tight, that heading wants a heavier
+weight, those cards need more radius at `lg`. Two bad options:
+
+1. **Dig into the code** yourself for a one-line change, or
+2. **Burn agent tokens** describing it in prose — *"on the pricing page, the middle card's button…"* — and hope the agent finds the right element.
+
+**uivisor** is a third option. Turn it on, **click the element, nudge it with your mouse**, and it hands you a
+copy-paste instruction that pins the **exact file & line**, the **styling mechanism**, the **breakpoint**, and
+**what to change** — so your agent makes the edit in one shot. uivisor itself **never writes to your source**;
+your tweaks are throwaway inline overrides in the browser.
+
+## What you get
+
+Click a button, bump its padding and color, hit **Copy prompt for agent**, and you get:
+
+```md
+# uivisor — apply these UI tweaks (2 changes across 1 element)
+
+## 1. <button> "Get started" — src/components/PricingCard.tsx:26:7
+- Identify by: component <PricingCard>, data-testid="buy-pro", selector `button[data-testid="buy-pro"]`
+- Styling: tailwind (current classes: `mt-6 w-full rounded-md px-4 py-2 bg-indigo-600 text-white`)
+- At lg breakpoint (≥1024px):
+    - padding: 16px → 24px  → `lg:p-6`
+    - background-color: rgb(79,70,229) → #16a34a  → `lg:bg-[#16a34a]`
+
+### Rules
+- Edit the EXISTING className/styles. Do NOT add inline styles or duplicate the component.
+- Scope each change to its breakpoint with a responsive variant (e.g. `lg:`).
+- Confirm the element by its source location, text and data-testid before editing.
+```
+
+Paste that into Claude Code / Cursor / whatever — done. No more *"page 55, that thing"*.
+
+---
+
+## Quick start
+
+> uivisor runs **only in dev** (`apply: 'serve'` / gated to `next dev`). It is **physically absent from your
+> production build.**
+
+It isn't on npm yet, so for a real project link it locally (rebuild + restart picks up changes — no reinstall):
+
+```bash
+# in the uivisor folder
+npm install && npm run build
+
+# in YOUR project
+npm i -D file:/absolute/path/to/uivisor
+```
+
+### Vite + React
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import uivisor from 'uivisor/vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [uivisor(), react()], //  ⚠️  uivisor() BEFORE react()
+})
+```
+
+### Next.js
+
+```js
+// next.config.js
+const { withUivisor } = require('uivisor/next')
+
+/** @type {import('next').NextConfig} */
+const nextConfig = { reactStrictMode: true }
+
+module.exports = withUivisor(nextConfig)
+```
+
+> Use plain `next dev` (webpack). Turbopack (`--turbo`) ignores `webpack()` config, so source locations
+> won't be injected under it yet.
+
+Then `npm run dev` and press **`Alt`+`U`** (or click the **◎** button bottom-right).
+
+#### Keeping it updated while we iterate
+
+Linked with `file:` → after any change to uivisor, just `npm run build` in the uivisor folder and **restart your
+dev server**. No reinstall. (For Next, clear `.next/` if HMR doesn't pick it up.)
+
+---
+
+## Using the panel
+
+1. **`Alt`+`U`** toggles uivisor · **Esc** deselects.
+2. **Click any element.** A Figma-like inspector fills with its spacing / border / typography / fill —
+   only the controls that are relevant (Typography shows on text elements, Gap on flex/grid containers).
+3. **Tweak:**
+   - **Combined-by-default** — Padding / Margin / Radius show one "all sides" input; click **▦** to split into
+     individual sides/corners.
+   - **Drag-to-scrub** — drag the icon on the left of any number field (cursor → ↔) to change it live.
+   - **Units** — line-height & letter-spacing have a px / % / em / × selector and always show the current number.
+4. **Screen / breakpoint** — click `md` / `lg` / … and the app loads in a **virtual screen at that width**
+   (real CSS media queries reflow); drag the frame edge to fine-tune. Only your project's **real breakpoints**
+   are shown. Edits are scoped to the chosen breakpoint (`lg:p-6`). `Live` = your real window.
+5. **Apply changes to** — pick the edit target:
+   - **All N like this** — when the element is a repeated sibling (same component/source, e.g. 3 cards), the
+     change previews on *all* of them and the prompt tells the agent to edit the shared component/source.
+   - **Only this one** · an existing **`.class`** · or **a new class you name** (agent creates it, leaves the rest).
+6. **Copy prompt for agent** (or **Copy JSON** for the machine-readable spec).
+
+Nothing is written to disk — tweaks live in the browser and vanish on reload.
+
+---
+
+## For your AI agent
+
+uivisor's output is a **self-contained instruction**, designed to be acted on without extra context. When you
+receive a uivisor prompt:
+
+- **Go to the `file:line:col`** it names — that's the authoritative anchor (injected in dev, React-19 safe).
+- **Edit the existing styling mechanism** it identifies (`tailwind` / `css-modules` / `styled-components` /
+  `inline` / `plain-css`) — not inline styles, and don't duplicate the component.
+- **Respect the breakpoint scope** — emit the responsive variant (`lg:…`), don't make it global.
+- **Respect the target** — `All N like this` means edit the shared component/class so every instance updates;
+  `new class` means create it and leave existing classes untouched; a positional `nth-of-type` selector is a
+  last-resort locator, never the thing to hard-code against.
+
+---
+
+## How it works
+
+- **Source mapping** — a tiny dev-only Babel pass tags host JSX with `data-uiv-src="file:line:col"`
+  (Vite plugin runs it `enforce: 'pre'`; Next runs it as a webpack pre-loader, keeping SWC).
+- **Identity, layered** — file:line → component name (from the file) → `data-testid` / id / stable selector / text.
+- **Mechanism + tokens** — detects how the element is styled and reverse-maps px to Tailwind tokens
+  (`24px → p-6`, `leading-normal`, `tracking-tight`), with arbitrary-value fallback.
+- **Breakpoints** — detected from the `@media` rules in your CSS, so the bar shows *your* breakpoints.
+- **Responsive preview** — the app is loaded in a resizable iframe so real media queries reflow; the inspector
+  operates inside it.
+
+## Limitations
+
+- **Dev builds only** — production strips source info and mangles classes.
+- **React-first** — the DOM/CSS/breakpoint core is framework-agnostic; only source mapping is React-specific today.
+- **Tailwind-tuned tokens** — non-Tailwind stacks get raw px + selector guidance (the prompt says which
+  CSS-module / styled rule to edit).
+
+## Develop
+
+```bash
+npm install
+npm run build        # tsup → dist/{vite,babel,overlay,next}
+npm test             # vitest (pure logic + babel transform)
+npm run demo         # Vite + React playground on :5180
+# demo-next/         # Next.js (app router) playground on :5181
+```
+
+<div align="center"><sub>MIT · dev-only · prompt-only</sub></div>

package/dist/babel/index.d.ts

@@ -0,0 +1,21 @@
+import { types, PluginObj } from '@babel/core';
+
+interface BabelAPI {
+    types: typeof types;
+}
+interface PluginState {
+    filename?: string;
+    cwd?: string;
+    opts: {
+        attr?: string;
+    };
+}
+/**
+ * Babel plugin: tag every intrinsic (host) JSX element with
+ * `data-uiv-src="relative/path.tsx:line:col"` so the overlay can resolve a
+ * clicked DOM node back to its exact source location. Dev-only; React-19 safe
+ * (does not rely on the removed fiber `_debugSource`).
+ */
+declare function uivisorBabel({ types: t }: BabelAPI): PluginObj<PluginState>;
+
+export { uivisorBabel as default };

package/dist/babel/index.js

@@ -0,0 +1,6 @@
+import {
+  uivisorBabel
+} from "../chunk-4XKGGP26.js";
+export {
+  uivisorBabel as default
+};

package/dist/chunk-4XKGGP26.js

@@ -0,0 +1,32 @@
+// src/babel/index.ts
+import * as path from "path";
+function uivisorBabel({ types: t }) {
+  return {
+    name: "uivisor-source",
+    visitor: {
+      JSXOpeningElement(nodePath, state) {
+        const node = nodePath.node;
+        const name = node.name;
+        if (!t.isJSXIdentifier(name)) return;
+        if (!/^[a-z]/.test(name.name)) return;
+        if (!node.loc) return;
+        const attrName = state.opts.attr || "data-uiv-src";
+        const already = node.attributes.some(
+          (a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName
+        );
+        if (already) return;
+        const filename = state.filename || "unknown";
+        const cwd = state.cwd || process.cwd();
+        const rel = filename === "unknown" ? filename : path.relative(cwd, filename);
+        const value = `${rel}:${node.loc.start.line}:${node.loc.start.column + 1}`;
+        node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(attrName), t.stringLiteral(value))
+        );
+      }
+    }
+  };
+}
+
+export {
+  uivisorBabel
+};

package/dist/next/index.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next/index.ts
+var next_exports = {};
+__export(next_exports, {
+  default: () => next_default,
+  withUivisor: () => withUivisor
+});
+module.exports = __toCommonJS(next_exports);
+var path = __toESM(require("path"), 1);
+function withUivisor(nextConfig = {}, options = {}) {
+  const attr = options.attr || "data-uiv-src";
+  const loaderPath = path.join(__dirname, "loader.cjs");
+  const overlayPath = path.join(__dirname, "..", "overlay", "index.js");
+  return {
+    ...nextConfig,
+    webpack(config, ctx) {
+      if (typeof nextConfig.webpack === "function") {
+        config = nextConfig.webpack(config, ctx);
+      }
+      if (!ctx.dev) return config;
+      config.module = config.module || {};
+      config.module.rules = config.module.rules || [];
+      config.module.rules.push({
+        test: /\.(jsx|tsx)$/,
+        exclude: /node_modules/,
+        enforce: "pre",
+        use: [{ loader: loaderPath, options: { attr } }]
+      });
+      if (!ctx.isServer) {
+        const prevEntry = config.entry;
+        config.entry = async () => {
+          const entries = typeof prevEntry === "function" ? await prevEntry() : prevEntry;
+          for (const key of ["main-app", "main.js", "main"]) {
+            const e = entries[key];
+            if (!e) continue;
+            if (Array.isArray(e)) {
+              if (!e.includes(overlayPath)) e.unshift(overlayPath);
+            } else if (e && Array.isArray(e.import)) {
+              if (!e.import.includes(overlayPath)) e.import.unshift(overlayPath);
+            }
+          }
+          return entries;
+        };
+      }
+      return config;
+    }
+  };
+}
+var next_default = withUivisor;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  withUivisor
+});

package/dist/next/loader.cjs

@@ -0,0 +1,96 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next/loader.ts
+var loader_exports = {};
+__export(loader_exports, {
+  default: () => uivisorNextLoader
+});
+module.exports = __toCommonJS(loader_exports);
+var import_core = require("@babel/core");
+
+// src/babel/index.ts
+var path = __toESM(require("path"), 1);
+function uivisorBabel({ types: t }) {
+  return {
+    name: "uivisor-source",
+    visitor: {
+      JSXOpeningElement(nodePath, state) {
+        const node = nodePath.node;
+        const name = node.name;
+        if (!t.isJSXIdentifier(name)) return;
+        if (!/^[a-z]/.test(name.name)) return;
+        if (!node.loc) return;
+        const attrName = state.opts.attr || "data-uiv-src";
+        const already = node.attributes.some(
+          (a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName
+        );
+        if (already) return;
+        const filename = state.filename || "unknown";
+        const cwd = state.cwd || process.cwd();
+        const rel = filename === "unknown" ? filename : path.relative(cwd, filename);
+        const value = `${rel}:${node.loc.start.line}:${node.loc.start.column + 1}`;
+        node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(attrName), t.stringLiteral(value))
+        );
+      }
+    }
+  };
+}
+
+// src/next/loader.ts
+function uivisorNextLoader(source, inMap) {
+  const callback = this.async();
+  const resourcePath = this.resourcePath || "";
+  if (!/\.[jt]sx$/.test(resourcePath) || !source.includes("<")) {
+    callback(null, source, inMap);
+    return;
+  }
+  const attr = this.getOptions?.().attr || "data-uiv-src";
+  try {
+    const result = (0, import_core.transformSync)(source, {
+      filename: resourcePath,
+      cwd: this.rootContext || process.cwd(),
+      babelrc: false,
+      configFile: false,
+      sourceMaps: true,
+      parserOpts: { plugins: ["jsx", "typescript"], sourceType: "module" },
+      generatorOpts: { retainLines: true },
+      plugins: [[uivisorBabel, { attr }]]
+    });
+    if (!result?.code) {
+      callback(null, source, inMap);
+      return;
+    }
+    callback(null, result.code, result.map ?? inMap);
+  } catch {
+    callback(null, source, inMap);
+  }
+}
+if (module.exports && module.exports.default) module.exports = module.exports.default;

package/dist/overlay/index.d.ts

@@ -0,0 +1,3 @@
+declare function start(): void;
+
+export { start };