agent-ui-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arsen-ask-lx
+
+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,96 @@
+# agent-ui-kit
+
+**Point at an element in your running app, say what is wrong — the note lands
+in a file your coding agent reads.**
+
+Between "this button here" and `Rail.tsx:69` somebody has to build a bridge.
+Without one, every conversation about the UI is made of prose descriptions,
+and prose is read two ways.
+
+It is a Vite plugin: it lives in the dev server and there is
+nothing to import in your source.
+
+```bash
+npm i -D agent-ui-kit
+```
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { agentUiKit } from "agent-ui-kit";
+
+export default defineConfig({
+  plugins: [react(), agentUiKit()],
+});
+```
+
+That is the whole installation. Hold **Alt** — the element under the cursor
+lights up. Click — a field opens. Type, press **Enter**.
+
+```markdown
+## the channel list slides under the profile instead of scrolling
+
+- **where:** `ChatScreen › Rail › RoomList › SidebarSection`
+- **what:** `<button>` — «Channels»
+- **classes:** `flex min-w-0 flex-1 items-center gap-1 rounded px-2.5 py-1 …`
+- **page:** `/c/01a0814d-3bd0-708e-bed0-b1be60d2bbee`
+- **when:** 2026-09-08 18:20:30
+```
+
+Then you say to your agent: *"work through NOTES.md"*. The component chain
+plus the class list is enough to find the source line with a single search.
+
+## Why it is a file and not an MCP server
+
+An MCP server would mean either the agent polling for notes or another daemon
+to keep running. A file needs neither: the agent reads it when it looks, and
+**any** agent can — Claude Code, Cursor, Codex, Copilot, or a human with
+`git diff`. Nothing here is tied to one vendor.
+
+You walk the screen and leave ten notes in a row; nobody should wait while
+each one is processed. The file collects, the agent works through the list
+afterwards.
+
+## Options
+
+```js
+agentUiKit({
+  file: "NOTES.md",   // where notes are collected
+  key: "alt",         // "alt" | "ctrl" | "meta"
+  color: "#e5484d",   // highlight colour
+  placeholder: "what is wrong? Enter — save, Esc — cancel",
+  route: "/__agent-ui-kit",  // change only on a collision
+})
+```
+
+## What it reads off the element
+
+- **the component chain** — pulled from React's own fibers on the DOM node
+  (`ChatScreen › Rail › RoomList`). React only, and only in dev;
+- **tag, classes, `id`, `data-testid`, a little text** — for everything else
+  and for every other framework.
+
+If no component names are found the note is still recorded, with the tag, the
+classes and the text. Tooling that dies together with somebody else's
+undocumented detail is worse than no tooling at all.
+
+## Dev only
+
+The plugin declares `apply: "serve"`. The client is injected by the dev
+server as a virtual module, so there is nothing to import in your source and
+nothing to remember to strip from a production build.
+
+## Three things learned the hard way
+
+They are in the source as comments, and they are why this is a package rather
+than a snippet:
+
+- **no `prompt()` / `confirm()`** — a native dialog freezes the page and
+  breaks any automation driving the browser from outside;
+- **the modifier-click belongs to the plugin entirely** — otherwise a note
+  about a button also presses that button;
+- **the field closes on click-outside, not on blur** — `blur` fires before
+  Enter gets a chance to run, and ate what was typed.
+
+MIT.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agent-ui-kit",
+  "version": "0.1.0",
+  "description": "Point at an element in your running app, say what is wrong — the note lands in a file your coding agent reads.",
+  "keywords": [
+    "vite-plugin",
+    "ai",
+    "agent",
+    "feedback",
+    "annotate",
+    "claude",
+    "cursor",
+    "devtools"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arsen-ask-lx/agent-ui-kit.git"
+  },
+  "homepage": "https://github.com/arsen-ask-lx/agent-ui-kit#readme",
+  "bugs": {
+    "url": "https://github.com/arsen-ask-lx/agent-ui-kit/issues"
+  }
+}

package/src/client.js

@@ -0,0 +1,261 @@
+/**
+ * Browser side of agent-ui-kit.
+ *
+ * Hold the modifier key — the element under the cursor lights up.
+ * Click — a small field opens. Type, press Enter — the note is appended
+ * to a file on disk, together with a description of what you pointed at.
+ *
+ * WHY THIS EXISTS. Between "this button here" and `Rail.tsx:69` somebody
+ * has to build a bridge. Without one, every conversation about the UI is
+ * made of prose descriptions, and prose is read two ways.
+ *
+ * ⚠️ DEV SERVER ONLY. The plugin declares `apply: "serve"`, so nothing
+ * here reaches a production bundle.
+ *
+ * ⚠️ NO `prompt()` / `confirm()`. A native dialog freezes the whole page
+ * and breaks automation that drives the browser from outside — which is
+ * exactly the audience this tool serves.
+ */
+
+/* global __AGENT_UI_KIT_OPTIONS__ */
+const OPTIONS = __AGENT_UI_KIT_OPTIONS__;
+
+/**
+ * Whose node is this — the chain of framework components, read off the
+ * DOM node itself.
+ *
+ * ⚠️ READ FROM THE FRAMEWORK, NOT FROM THE BUILD. The first attempt wrote
+ * source positions into the markup with a Babel plugin, and broke against
+ * `@vitejs/plugin-react` 6, which is built on oxc — the Babel hook points
+ * are simply gone.
+ *
+ * React in dev mode hangs a `__reactFiber$…` property (random suffix) on
+ * every DOM node. Walking it upwards yields `ChatScreen › Rail › RoomList`
+ * which, together with the class list, is enough to find the source line
+ * with a single search.
+ *
+ * ⚠️ THESE ARE FRAMEWORK INTERNALS AND THEY MAY VANISH. That is why there
+ * is not one "just in case" guard here: if no names are found, the note is
+ * still recorded — with the tag, the classes and the text. Tooling that
+ * dies together with somebody else's undocumented detail is worse than no
+ * tooling at all.
+ */
+function fiberOf(node) {
+  const key = Object.keys(node).find((one) => one.startsWith("__reactFiber$"));
+  return key ? (node[key] ?? null) : null;
+}
+
+function nameOf(fiber) {
+  if (typeof fiber.type !== "function") return undefined;
+  return fiber.type.displayName ?? fiber.type.name;
+}
+
+function ownersOf(node) {
+  const names = [];
+  let fiber = fiberOf(node);
+  // A depth limit on purpose: trees get deep and we only want the nearest.
+  for (let step = 0; fiber && step < 40 && names.length < 4; step++) {
+    const name = nameOf(fiber);
+    if (name && !names.includes(name)) names.unshift(name);
+    fiber = fiber.return ?? null;
+  }
+  return names.length > 0 ? names.join(" › ") : null;
+}
+
+/** How the element is recognised by eye: tag, a little text, classes. */
+function describe(node) {
+  return {
+    tag: node.tagName.toLowerCase(),
+    classes: node.getAttribute("class") ?? "",
+    sample: (node.textContent ?? "").trim().slice(0, 60),
+    id: node.id || "",
+    testId: node.getAttribute("data-testid") ?? "",
+  };
+}
+
+/**
+ * ⚠️ COLOURS ARE SELF-CONTAINED, NOT TAKEN FROM THE HOST'S THEME.
+ * An earlier version used the host project's CSS custom properties. That
+ * is right inside one project and wrong in a package: in a project that
+ * has no such tokens the highlight is invisible, and an invisible
+ * highlight is indistinguishable from a broken plugin.
+ */
+function frameFor(node) {
+  const frame = document.createElement("div");
+  const at = node.getBoundingClientRect();
+  frame.style.cssText = [
+    "position:fixed",
+    `left:${at.left}px`,
+    `top:${at.top}px`,
+    `width:${at.width}px`,
+    `height:${at.height}px`,
+    `border:2px solid ${OPTIONS.color}`,
+    "border-radius:4px",
+    `background:${OPTIONS.color}1a`,
+    "pointer-events:none",
+    "z-index:2147483646",
+  ].join(";");
+  return frame;
+}
+
+/**
+ * The note field, next to the element. Resolves with the text or null.
+ *
+ * ⚠️ ENTER IS HANDLED EXPLICITLY, NOT THROUGH IMPLICIT FORM SUBMISSION.
+ * Implicit submit depends on how many fields the form has and whether it
+ * has a button; an end-to-end run caught this — the field closed and the
+ * note went nowhere.
+ *
+ * ⚠️ CLOSING IS ON CLICK-OUTSIDE, NOT ON BLUR. `blur` fires before Enter
+ * gets a chance to run and ate what was typed. Same defect, other half.
+ */
+function ask(node) {
+  return new Promise((done) => {
+    const at = node.getBoundingClientRect();
+    const box = document.createElement("div");
+    box.style.cssText = [
+      "position:fixed",
+      `left:${Math.max(8, Math.min(at.left, window.innerWidth - 348))}px`,
+      `top:${Math.min(at.bottom + 8, window.innerHeight - 90)}px`,
+      "z-index:2147483647",
+      "padding:8px",
+      "border-radius:12px",
+      "background:#1b1b1e",
+      "box-shadow:0 8px 24px rgb(0 0 0 / 40%)",
+      "font:14px system-ui,sans-serif",
+    ].join(";");
+
+    const field = document.createElement("input");
+    field.placeholder = OPTIONS.placeholder;
+    field.style.cssText = [
+      "width:300px",
+      "padding:8px 10px",
+      "border:0",
+      "border-radius:8px",
+      "background:#0f0f11",
+      "color:#f1f1f3",
+      "font:inherit",
+      "outline:none",
+    ].join(";");
+
+    box.append(field);
+    document.body.append(box);
+    field.focus();
+
+    let closed = false;
+    const close = (answer) => {
+      if (closed) return;
+      closed = true;
+      box.remove();
+      document.removeEventListener("mousedown", outside, true);
+      done(answer);
+    };
+    function outside(event) {
+      if (!box.contains(event.target)) close(null);
+    }
+
+    field.addEventListener("keydown", (event) => {
+      // Swallow everything: the page underneath must neither hear the
+      // typing nor read Escape as "close the menu".
+      event.stopPropagation();
+      if (event.key === "Enter") {
+        event.preventDefault();
+        close(field.value.trim() || null);
+      }
+      if (event.key === "Escape") close(null);
+    });
+
+    document.addEventListener("mousedown", outside, true);
+  });
+}
+
+/**
+ * ⚠️ ARMED EXACTLY ONCE PER PAGE LIFETIME. Hot reload re-executes the
+ * module, and without this mark the handlers stacked up: one click opened
+ * three fields on top of each other and the page eventually locked up.
+ *
+ * The mark lives on `window`, not in the module: after a reload the module
+ * is new and so are its variables. Only what lives outside survives.
+ */
+const ONCE = "__agentUiKitStarted";
+
+function held(event) {
+  return OPTIONS.key === "alt"
+    ? event.altKey
+    : OPTIONS.key === "ctrl"
+      ? event.ctrlKey
+      : event.metaKey;
+}
+
+function start() {
+  if (window[ONCE]) return;
+  window[ONCE] = true;
+
+  let frame = null;
+  let asking = false;
+
+  const clear = () => {
+    frame?.remove();
+    frame = null;
+  };
+
+  document.addEventListener(
+    "mousemove",
+    (event) => {
+      if (asking) return;
+      if (!held(event)) return clear();
+      const node = document.elementFromPoint(event.clientX, event.clientY);
+      clear();
+      if (!node) return;
+      frame = frameFor(node);
+      document.body.append(frame);
+    },
+    true,
+  );
+
+  document.addEventListener("keyup", () => {
+    if (!asking) clear();
+  });
+
+  document.addEventListener(
+    "click",
+    (event) => {
+      if (!held(event) || asking) return;
+      const node = event.target;
+      if (!node) return;
+
+      // The modifier-click belongs to us entirely: the application must not
+      // hear it, or a note about a button would also press that button.
+      event.preventDefault();
+      event.stopPropagation();
+
+      asking = true;
+      void (async () => {
+        const text = await ask(node);
+        asking = false;
+        clear();
+        if (!text) return;
+
+        const note = { text, where: ownersOf(node), url: location.pathname, ...describe(node) };
+        try {
+          const answer = await fetch(OPTIONS.route, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(note),
+          });
+          // Say it out loud on success too: silence is indistinguishable
+          // from loss, and loss is precisely what we already missed once.
+          if (answer.ok) console.info(`[agent-ui-kit] noted: ${text} → ${note.where ?? note.tag}`);
+          else console.warn(`[agent-ui-kit] not saved: server answered ${answer.status}`);
+        } catch {
+          console.warn("[agent-ui-kit] not sent: the dev server did not answer");
+        }
+      })();
+    },
+    true,
+  );
+
+  console.info(`[agent-ui-kit] on — hold ${OPTIONS.key} to highlight, ${OPTIONS.key}+click to leave a note`);
+}
+
+start();

package/src/index.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "vite";
+
+export interface AgentUiKitOptions {
+  /** Where notes are collected. Default: `NOTES.md` in the project root. */
+  file?: string;
+  /** Which key to hold while pointing. Default: `alt`. */
+  key?: "alt" | "ctrl" | "meta";
+  /** Highlight colour. Default: `#e5484d`. */
+  color?: string;
+  /** Placeholder in the note field. */
+  placeholder?: string;
+  /** Where the browser posts notes. Change only on a collision. */
+  route?: string;
+}
+
+export function agentUiKit(options?: AgentUiKitOptions): Plugin;
+export default agentUiKit;

package/src/index.js

@@ -0,0 +1,144 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * agent-ui-kit — point at an element, say what is wrong, the note lands
+ * in a file your coding agent reads.
+ *
+ * WHY A FILE AND NOT A CONSOLE LINE. You walk the screen and leave ten notes
+ * in a row; nobody should wait while each is processed. The file collects
+ * them, the agent works through the list afterwards.
+ *
+ * WHY NOT MCP. An MCP server would mean the agent polling, or another daemon
+ * to run. A file needs neither: the agent reads it when it looks, and any
+ * agent can — this is not tied to one vendor.
+ *
+ * ⚠️ DEV SERVER ONLY (`apply: "serve"`). Nothing here reaches a production
+ * build: the client is injected by the dev server and the route lives in its
+ * middleware.
+ */
+
+const CLIENT = "\0virtual:agent-ui-kit/client";
+
+const DEFAULTS = {
+  /** Where notes are collected. Markdown: read by a human and by an agent. */
+  file: "NOTES.md",
+  /** Which key to hold. `alt` | `ctrl` | `meta`. */
+  key: "alt",
+  /** Highlight colour. Self-contained on purpose — see client.js. */
+  color: "#e5484d",
+  /** Placeholder in the note field. */
+  placeholder: "what is wrong? Enter — save, Esc — cancel",
+  /** Where the browser posts notes. Change only on a collision. */
+  route: "/__agent-ui-kit",
+};
+
+/**
+ * One note, one entry.
+ *
+ * Components come first and on their own line: they are what you open the
+ * file by, so they must be findable by eye rather than read out of a
+ * paragraph. Classes are the second key — they locate the exact line inside
+ * the file.
+ */
+function entry(note) {
+  const when = new Date().toISOString().replace("T", " ").slice(0, 19);
+  const where = note.where || "component not identified";
+  const what = `\`<${note.tag}>\`${note.sample ? ` — «${note.sample}»` : ""}`;
+  return [
+    ``,
+    `## ${note.text}`,
+    ``,
+    `- **where:** \`${where}\``,
+    `- **what:** ${what}`,
+    `- **classes:** \`${note.classes || "—"}\``,
+    note.id ? `- **id:** \`${note.id}\`` : null,
+    note.testId ? `- **data-testid:** \`${note.testId}\`` : null,
+    `- **page:** \`${note.url}\``,
+    `- **when:** ${when}`,
+    ``,
+  ]
+    .filter((line) => line !== null)
+    .join("\n");
+}
+
+async function readBody(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(chunk);
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+/**
+ * @param {Partial<typeof DEFAULTS>} [options]
+ */
+export function agentUiKit(options = {}) {
+  const settings = { ...DEFAULTS, ...options };
+  const notes = resolve(process.cwd(), settings.file);
+
+  return {
+    name: "agent-ui-kit",
+    apply: "serve",
+
+    // The client is a virtual module: nothing to copy into the host project,
+    // and nothing to keep in sync with it.
+    resolveId(id) {
+      return id === CLIENT.slice(1) ? CLIENT : null;
+    },
+
+    async load(id) {
+      if (id !== CLIENT) return null;
+      const source = await readFile(new URL("./client.js", import.meta.url), "utf8");
+      const runtime = {
+        key: settings.key,
+        color: settings.color,
+        placeholder: settings.placeholder,
+        route: settings.route,
+      };
+      return source.replace("__AGENT_UI_KIT_OPTIONS__", JSON.stringify(runtime));
+    },
+
+    // ⚠️ INJECTED BY THE PLUGIN, NOT IMPORTED BY THE HOST. One line in the
+    // config is the whole installation; a project that has to import a client
+    // file also has to remember to strip it from production.
+    transformIndexHtml() {
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module", src: `/@id/${CLIENT.slice(1)}` },
+          injectTo: "body",
+        },
+      ];
+    },
+
+    configureServer(server) {
+      server.middlewares.use(settings.route, (request, response) => {
+        if (request.method !== "POST") {
+          response.statusCode = 405;
+          response.end();
+          return;
+        }
+        void (async () => {
+          try {
+            const note = await readBody(request);
+            await mkdir(dirname(notes), { recursive: true });
+            await appendFile(notes, entry(note), "utf8");
+            // Say it in the dev-server log too: the person sees the note did
+            // not fly off into nowhere without opening the file.
+            server.config.logger.info(`[agent-ui-kit] ${note.text} → ${note.where || note.tag}`);
+            response.statusCode = 204;
+            response.end();
+          } catch (error) {
+            // Not swallowed: a note that failed to save must say so, or the
+            // person will believe it was taken into account.
+            server.config.logger.error(`[agent-ui-kit] not saved: ${String(error)}`);
+            response.statusCode = 500;
+            response.end();
+          }
+        })();
+      });
+    },
+  };
+}
+
+export default agentUiKit;