kapi-ui 0.3.1 → 0.3.2

package/README.md

@@ -1 +1,72 @@
-# kapi
+Kapi UI is a visual commenting tool. Click on an element, leave a comment, and send to your agent. No need for copy-pasting file paths or describing your target element. 
+
+It currently works with Vue projects (Vite + Vue or Nuxt) paired with Claude Code or Codex. Support for other frameworks and agents coming soon.
+
+## Requirements
+---
+- A Vue project (Vite + Vue or Nuxt)
+- Claude Code/Codex CLI
+
+## How it works
+---
+At its core, Kapi UI is a Vite plugin. It injects the UI overlay into your dev app and uses the HMR websocket to send your comments to your agent. You can also opt to manually copy your comments and paste them into any coding agent of your choice.
+
+## Automatic Installation
+---
+From your project root:
+```bash
+npx kapi-ui
+```
+
+Useful flags:
+```bash
+npx kapi-ui --vite              # force Vite + Vue setup (skip auto-detection)
+npx kapi-ui --nuxt              # force Nuxt setup
+npx kapi-ui --agent=claude      # force Claude Code
+npx kapi-ui --agent=codex       # force Codex (experimental)
+npx kapi-ui --manual            # copy/paste workflow, no agent
+```
+
+## Manual Installation
+---
+1. Install the package as a dev dependency:
+```bash
+npm install kapi-ui -D
+```
+2. Wire it into your config
+
+   **Vite + Vue** (`vite.config.ts`):
+
+   ```ts
+   import kapi from 'kapi-ui/vite-plugin'
+
+   export default defineConfig({
+     plugins: [kapi({ agent: 'claude' })],
+   })
+   ```
+
+   **Nuxt** (`nuxt.config.ts`):
+
+   ```ts
+   export default defineNuxtConfig({
+     modules: ['kapi-ui/nuxt'],
+     kapi: { agent: 'claude' },
+   })
+   ```
+
+   The `agent` option is required — use `'claude'`, `'codex'`, or `false` (copy/paste only, no agent spawned).
+
+2. Run your dev server as usual. The UI overlay is injected and your agent session starts automatically.
+
+## Configuration
+---
+The only option, on both the Vite plugin and the Nuxt module:
+
+| Option  | Type                           | Default      | What it does                                                         |
+| ------- | ------------------------------ | ------------ | -------------------------------------------------------------------- |
+| `agent` | `'claude' \| 'codex' \| false` | — (required) | Which agent Kapi drives. `false` = copy/paste only, no agent spawned |
+Kapi UI uses Vite's HMR websocket to start a Claude Code and Codex Sessions.
+
+## License
+---
+[MIT](https://github.com/jcebermudo/kapi-ui/blob/main/LICENSE)

package/dist/browser/comments.js

@@ -101,6 +101,23 @@ function ensureRoot() {
 function clamp(value, min, max) {
     return Math.min(Math.max(value, min), max);
 }
+const PANEL_MARGIN = 8;
+// The tooltip/composer defaults to the marker's right, vertically centered
+// on it. Flips it to the marker's left if that would run past the right
+// edge of the viewport, and clamps its vertical centering so it can't run
+// past the top/bottom edge either — both are recalculated on every reveal
+// and on scroll/resize (see repositionAll), since the marker's on-screen
+// position can move independently of the panel's fixed size.
+function adjustPanelPosition(marker, panel) {
+    const markerRect = marker.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+    const overflowsRight = markerRect.right + 8 + panelRect.width + PANEL_MARGIN > window.innerWidth;
+    panel.classList.toggle('kapi-comment-panel-left', overflowsRight);
+    const idealTop = markerRect.top + markerRect.height / 2 - panelRect.height / 2;
+    const clampedTop = clamp(idealTop, PANEL_MARGIN, window.innerHeight - panelRect.height - PANEL_MARGIN);
+    panel.style.top = `${clampedTop - markerRect.top}px`;
+    panel.style.transform = 'none';
+}
 function position(target, wrapper) {
     const rect = target.el.getBoundingClientRect();
     const x = rect.left + target.ratioX * rect.width;
@@ -156,7 +173,10 @@ function renderMarker(entry, label) {
         countEl.textContent = `applies to ${entry.targets.length} elements`;
         tooltip.appendChild(countEl);
     }
-    marker.addEventListener('mouseenter', () => wrapper.classList.add('kapi-hovering'));
+    marker.addEventListener('mouseenter', () => {
+        wrapper.classList.add('kapi-hovering');
+        adjustPanelPosition(marker, tooltip);
+    });
     marker.addEventListener('mouseleave', () => wrapper.classList.remove('kapi-hovering'));
     marker.addEventListener('click', () => beginEdit(entry));
     wrapper.append(marker, tooltip);
@@ -221,10 +241,11 @@ function renderComposer(label, target, initialText = '') {
         input.focus();
         input.setSelectionRange(input.value.length, input.value.length);
         autoGrow();
-        // Lock the composer's vertical position to its initial (single-line) height,
-        // centered on the marker, so later growth only extends it downward instead
-        // of continuously re-centering (which would grow it upward too).
-        composer.style.top = `${MARKER_RADIUS - composer.getBoundingClientRect().height / 2}px`;
+        // Lock the composer's position to its initial (single-line) height and
+        // whichever side/vertical offset fits the viewport, so later growth only
+        // extends it downward instead of continuously re-centering (which would
+        // grow it upward too) or re-flipping sides mid-type.
+        adjustPanelPosition(marker, composer);
     });
     return wrapper;
 }
@@ -281,6 +302,19 @@ function repositionAll() {
         const target = targets[i];
         if (target)
             position(target, wrapper);
+        // Re-flip/re-clamp any panel currently on screen — the marker's position
+        // just moved, so a fit that held before this scroll/resize might not now.
+        const marker = wrapper.querySelector('.kapi-comment-marker');
+        if (!marker)
+            return;
+        const composer = wrapper.querySelector('.kapi-comment-composer');
+        if (composer) {
+            adjustPanelPosition(marker, composer);
+            return;
+        }
+        const tooltip = wrapper.querySelector('.kapi-comment-tooltip');
+        if (tooltip && wrapper.classList.contains('kapi-hovering'))
+            adjustPanelPosition(marker, tooltip);
     });
 }
 window.addEventListener('resize', repositionAll);
@@ -434,6 +468,22 @@ export function beginComment(el, clientX, clientY) {
     lockHighlightOn(el);
     render();
 }
+// Tracks whether Shift is currently held so the composer can stay hidden
+// while the user is still shift-clicking to grow the multi-selection —
+// opening/refreshing it on every click steals focus and discards typing.
+// The composer only appears once Shift is released, showing the final batch.
+let shiftHeld = false;
+document.addEventListener('keydown', (e) => {
+    if (e.key === 'Shift')
+        shiftHeld = true;
+});
+document.addEventListener('keyup', (e) => {
+    if (e.key !== 'Shift')
+        return;
+    shiftHeld = false;
+    if (draft?.els)
+        render();
+});
 // Called on every shift-click/drag-select change in inspector.ts. Keeps one
 // shared composer live as the selection grows or shrinks, so no separate
 // "commit" click is needed. On submit, one CommentEntry per selected element
@@ -463,6 +513,8 @@ export function updateSelection(els) {
         draft = { el: anchor, ratioX: 0.5, ratioY: 0.5, els };
     }
     lockWithoutHighlight();
+    if (shiftHeld)
+        return;
     render();
 }
 function deleteComment(id) {

package/dist/browser/styles/comments.css

@@ -74,8 +74,11 @@
   display: none;
   position: absolute;
   left: calc(var(--kapi-marker-size) + 8px);
-  top: 50%;
-  transform: translateY(-50%);
+  /* top/transform are set in JS on every reveal (see adjustPanelPosition in
+     comments.ts), which vertically centers on the marker by default and
+     clamps within the viewport otherwise — these are just a pre-JS fallback. */
+  top: 0;
+  transform: none;
   width: var(--kapi-panel-width);
   box-sizing: border-box;
   border-radius: 12px;
@@ -87,6 +90,15 @@
   pointer-events: auto;
 }
 
+/* Flips the panel to the marker's left — set in JS (see adjustPanelPosition
+   in comments.ts) when the default right-of-marker position would run past
+   the right edge of the viewport. */
+.kapi-comment-tooltip.kapi-comment-panel-left,
+.kapi-comment-composer.kapi-comment-panel-left {
+  left: auto;
+  right: calc(var(--kapi-marker-size) + 8px);
+}
+
 .kapi-comment-tooltip {
   flex-direction: column;
   gap: 2px;
@@ -102,11 +114,11 @@
 @keyframes kapi-tooltip-in {
   from {
     opacity: 0;
-    transform: translateY(-50%) translateY(8px);
+    transform: translateY(8px);
   }
   to {
     opacity: 1;
-    transform: translateY(-50%);
+    transform: translateY(0);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kapi-ui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Visually prompt your UI",
   "scripts": {
     "build": "tsc && npm run copy:css",