liteagents 2.6.0 → 2.8.0

package/packages/claude/skills/live-canvas/SKILL.md

@@ -17,114 +17,117 @@ This skill implements a complete design exploration workflow: interview, generat
 
 ---
 
-## Feedback Modes (host-tool aware)
+## Feedback Modes — always ask the user
 
-Live Canvas supports two feedback transports. The skill auto-selects at runtime — the user never toggles modes manually.
+Live Canvas supports two feedback transports. **The user picks every time** — never auto-select.
 
-- **Mode A — Batch (universal, works everywhere):** each Save writes to `.claude-design/feedback.jsonl`. User types "check" (or any message) to have the assistant read and act on the batch. Works in Claude Code, Droid, Amp, and Opencode identically.
-- **Mode B — Live (Claude Code only):** the overlay POSTs each Save to a local MCP channel server; feedback arrives in the active session as a `<channel source="live-canvas" ...>` tag. Edits land without the user switching windows.
+- **Live channel (Claude Code only):** the overlay POSTs each Save to a local MCP channel server; feedback arrives in the active session as a `<channel source="live-canvas" ...>` tag. Requires the session was launched with `live-claude` (or `claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace`) — channels are still an experimental Claude Code feature and a plain `claude` session silently drops the notifications. Any qualifying session can claim the channel by calling `mcp__live-canvas__channel_open`; only one holds it at a time.
+- **JSON file (universal):** each Save accumulates locally; Submit writes `.claude-design/feedback.jsonl` (or downloads the JSON). User says "check" or pastes the file when ready. Works in any host.
 
-**Host-tool guidance — follow exactly:**
+### Host detection — do this first
 
-| Host | Modes available | What to do |
-|---|---|---|
-| Claude Code | A + B | Probe channel at Phase 0. If up → Live. If down → announce Batch and print the one-time setup block below. |
-| Droid, Amp, Opencode | A only | Never probe the channel, never mention Live mode, never offer to install a plugin. Use Batch exclusively and collect feedback via paste-in-terminal (Phase 5). |
+This SKILL.md is the Claude Code variant of the skill. Same content is mirrored as docs for Droid/Amp/Opencode under `packages/<tool>/commands/live-canvas/`, but those tools don't support the MCP channel.
 
-### Channel activation — run this BEFORE starting the interview
+**If running under Droid, Amp, or Opencode (not Claude Code):**
+- Skip the mode question entirely.
+- Announce: `📝 JSON mode (Live channel requires Claude Code)`.
+- Proceed to Phase 1 with `channelUrl` omitted in the overlay init.
+- Never mention the channel plugin.
 
-Users invoke `/live-canvas` from an ordinary Claude Code session most of the time. They won't have started with the dev-channels flag unless they remembered. The skill's job is to figure out what state they're in and guide them without making them read docs.
+How to tell which host you're in: the environment variable `CLAUDECODE=1` is set by Claude Code. If unset, assume non-Claude and go straight to JSON.
 
-**Step A — Probe the channel:**
+### Mode selection (Claude Code only)
 
-```bash
-curl -s --max-time 1 http://localhost:8788/health
-```
-
-**Step B — Decide which case you're in:**
-
-| Probe result | Plugin dir exists at `~/.claude/plugins/cache/live-canvas-marketplace/`? | Case |
-|---|---|---|
-| `{"ok":true,...}` | (don't bother checking) | **Case 1 — Live ready** |
-| fails | exists | **Case 2 — Plugin installed, session not in dev mode** |
-| fails | missing | **Case 3 — First-time user** |
+Always ask, never auto-detect. Use `AskUserQuestion`:
 
-**Step C — Act on the case.**
+> **Question: Pick a feedback mode**
+> - **Live channel** — overlay streams each Save straight into this Claude session. **Requires this session to have been started with `live-claude`** (sets the `--dangerously-load-development-channels` flag). If you started with plain `claude`, pick JSON instead — Live mode will refuse to start and tell you to open a new `live-claude` terminal.
+> - **JSON file** — overlay writes feedback to a local JSON file; tell me "check" when ready. Works in any session, plain `claude` included.
 
-### Case 1 — Live ready
+**If the user picks JSON**, try to bind the batch endpoint so submissions write to disk instead of triggering a browser download. Call `mcp__live-canvas__batch_open`:
 
-Announce briefly and proceed to the interview:
+| Tool result | What to do |
+|---|---|
+| Tool not available (no MCP) | Announce `📝 JSON mode — overlay will offer JSON download on Submit`. Proceed to Phase 1 with both `channelUrl` and `batchEndpoint` omitted. |
+| `{status: "opened", ...}` or `{status: "already_listening", ...}` | Announce `📝 JSON mode — submissions write to .claude-design/feedback.jsonl`. Proceed to Phase 1 with `batchEndpoint: 'http://localhost:8788/feedback-jsonl'` and `channelUrl` omitted. |
+| `{status: "in_use", ...}` | Announce `📝 JSON mode — overlay will offer JSON download on Submit (another session holds the port)`. Proceed to Phase 1 with both `channelUrl` and `batchEndpoint` omitted. |
 
-```
-✨ Live mode — your feedback will stream into this session in real time.
-```
+Call `mcp__live-canvas__channel_close` on cleanup/abort to release the port (same teardown as Live mode).
 
-No decision needed. Skip to Phase 1.
+**If the user picks Live**, claim the channel by calling the MCP tool `mcp__live-canvas__channel_open`. Branch on the result:
 
-### Case 2 — Plugin installed but session not in dev mode
+| Tool result | What to do |
+|---|---|
+| Tool not available (no such tool / MCP error) | **Case C: First-time setup needed.** Print the install block (below) and STOP. |
+| `{status: "opened", ...}` (no `took_over`) | **Case A: Ready.** Announce `✨ Live mode — feedback streams into this session`. Proceed to Phase 1 with `channelUrl: 'http://localhost:8788'`. |
+| `{status: "opened", took_over: <pid>, ...}` | **Case A (takeover): Ready.** Announce `✨ Live mode — feedback streams into this session (took over channel from prior live-canvas session pid <pid>)`. Proceed to Phase 1 the same as plain Case A. The prior session's MCP was a sibling instance of this plugin (same user); its `/live-canvas` workflow there is now over, but the lab files on disk are untouched. |
+| `{status: "already_listening", ...}` | **Case A: Ready.** Announce `✨ Live mode — feedback streams into this session`. Proceed to Phase 1 with `channelUrl: 'http://localhost:8788'`. |
+| `{status: "in_use", holder_pid, message, ...}` | **Case B: Foreign process holds the port.** A non-live-canvas process is using port 8788 (e.g., a dev server on the wrong port). Print the busy block (below) and STOP — the plugin won't kill processes it doesn't own. |
+| `{status: "no_channel_capability", message, ...}` | **Case D: Session lacks the channels flag.** Print the relaunch block (below) and STOP. Do NOT proceed to Live mode — notifications would be silently dropped. |
 
-This is the common case for returning users who forgot the dev flag. Use `AskUserQuestion`:
+You must call `mcp__live-canvas__channel_close` later — see Phase 8 (Cleanup) and Abort Handling. The MCP plugin also auto-releases the port on session disconnect as a safety net, but explicit close is cleaner.
 
-> **Question: How do you want to run this session?**
-> - "Batch for now" — continue without live mode. Feedback writes to JSONL; paste or say 'check' when ready.
-> - "Restart for Live mode" — I'll abort here. Close this session, run the command below in your terminal, then `/live-canvas` again in the new one.
+**Case B — busy block (foreign holder):**
 
-If they pick "Restart for Live mode", print:
+Substitute the actual `holder_pid` from the tool response into the message below.
 
 ```
-Close this Claude session, then run:
-
-  claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace
+Port 8788 is held by pid <holder_pid>, which is NOT a live-canvas server
+(it's some other process). I won't kill processes I don't own.
 
-When it reopens, confirm the safety prompt, then run /live-canvas again — I'll be in Live mode.
+To use Live mode:
+  • Find what it is:  ps -fp <holder_pid>
+  • Stop it if it's safe to stop (e.g. a stray dev server on the wrong port).
+  • Then re-run /live-canvas in this session and pick Live.
 
-Tip: save an alias so you don't retype this every time:
-  alias claude-live='claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace'
+Or pick JSON now — JSON mode does not require port 8788.
 ```
 
-Then exit the skill cleanly — do not start the interview. The user is going to close this session.
-
-If they pick "Batch for now", announce Batch mode and proceed to Phase 1 normally.
-
-### Case 3 — First-time user
-
-Channel plugin has never been set up. Use `AskUserQuestion`:
-
-> **Question: Set up Live mode?**
-> - "Yes, walk me through it" — I'll print the one-time setup commands.
-> - "Just use Batch mode" — skip setup, start the skill normally.
-
-If they pick setup, print the full sequence:
+**Case D — relaunch block (no channels flag):**
 
 ```
-One-time setup for Live mode:
-
-1. Install channel plugin dependencies (run in your terminal):
-   bash ~/.claude/plugins/live-canvas-marketplace/setup.sh
-
-   This runs `npm install` in the plugin dir.
-
-2. Inside Claude Code, register and install the plugin:
-   /plugin marketplace add ~/.claude/plugins/live-canvas-marketplace
-   /plugin install live-canvas-channel@live-canvas-marketplace
-
-3. Close this session and reopen with the dev-channels flag:
-   claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace
+This Claude session is plain `claude` — it can't receive Live-mode feedback.
+Live mode needs a session started with `live-claude` (which sets the
+experimental --dangerously-load-development-channels flag). Without it,
+your browser Saves would POST 200 but never appear in chat.
+
+To use Live mode:
+
+  1. Open a NEW terminal (you can keep this one running; it's fine to have
+     both). Do NOT --continue this session — start fresh in the project.
+  2. cd to your project directory.
+  3. Run:  live-claude
+       (if the command isn't found: run `source ~/.zshrc` first, or re-run
+       packages/claude/plugins/live-canvas-marketplace/setup.sh)
+       (literal form: claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace)
+  4. In that NEW session, run /live-canvas and pick Live.
+
+The lab files are written to disk in the project's `.claude-design/lab/`,
+so any session in the right cwd can pick up where another left off.
+
+Or pick JSON now to stay in this session — feedback gets written to a file
+you paste back here. No relaunch needed.
+```
 
-4. Accept the safety prompt, then run /live-canvas again.
+**Case C — first-time setup block:**
 
-Tip: alias for future sessions:
-  alias claude-live='claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace'
 ```
+Live mode needs a one-time install. Two steps:
 
-Exit the skill — don't start the interview. The user has a multi-step setup to do.
+  1. From this repo's root (or wherever liteagents lives):
+       bash packages/claude/plugins/live-canvas-marketplace/setup.sh
+     This copies the marketplace into ~/.claude/plugins/ and runs npm install.
 
-If they pick Batch, announce Batch mode and proceed to Phase 1 normally.
+  2. In any Claude session, register and install the plugin:
+       /plugin marketplace add ~/.claude/plugins/live-canvas-marketplace
+       /plugin install live-canvas-channel@live-canvas-marketplace
 
-### Why not auto-run the setup commands?
+That's it — once the plugin is installed, /live-canvas in any session can
+claim the channel. Re-run /live-canvas and pick Live.
+```
 
-**Do not try to run any of these commands yourself.** Three reasons:
-1. Steps 2 and 3 require Claude Code slash commands and a session restart — you can't do either from inside a running session.
+Do not try to run any of these commands yourself. Three reasons:
+1. The `/plugin` steps are Claude Code slash commands — not doable from inside a running session.
 2. Accepting the research-preview safety prompt must be the user's explicit act.
 3. If something goes wrong mid-install, the user needs to see each step's output to diagnose.
 
@@ -403,12 +406,6 @@ Create all files under `.claude-design/`:
 │   │   └── VariantE.tsx
 │   ├── components/
 │   │   └── LabShell.tsx         # Lab layout wrapper
-│   ├── feedback/                # Interactive feedback system
-│   │   ├── types.ts             # TypeScript interfaces
-│   │   ├── selector-utils.ts    # Element identification
-│   │   ├── format-utils.ts      # Feedback formatting
-│   │   ├── FeedbackOverlay.tsx  # Main overlay component
-│   │   └── index.ts             # Module exports
 │   └── data/
 │       └── fixtures.ts          # Shared mock data
 ├── design-brief.json
@@ -419,61 +416,54 @@ Create all files under `.claude-design/`:
 
 **The overlay is the PRIMARY feature of Live Canvas.** Without it, users cannot provide interactive feedback. NEVER generate a lab without the overlay.
 
-### Choose the right overlay template
-
-The skill ships two overlay templates under `~/.claude/skills/live-canvas/templates/`:
+### The overlay
 
-| Template | When to use |
-|---|---|
-| `feedback-react/FeedbackOverlay.tsx` | React / Next.js / Vite-React projects — integrates via JSX |
-| `overlay-vanilla.js` | Everything else: vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Go templates, etc. One script tag, zero dependencies. |
-
-Detect the host framework in Phase 0 and copy the matching template into the route directory. The vanilla template is the safer default when in doubt — it works in every context the React one does, plus more.
-
-### Required files in the route directory
-
-For **React-based** projects:
-```
-app/live-canvas/           # or app/__live_canvas/
-├── page.tsx              # Main lab page with variants + overlay import
-└── FeedbackOverlay.tsx   # Copy of feedback-react/FeedbackOverlay.tsx
-```
-
-Import: `import { FeedbackOverlay } from './FeedbackOverlay'`
-
-For **non-React** projects:
-```
-<static-dir>/__live_canvas/
-├── index.html             # Or framework-appropriate entry point
-└── overlay-vanilla.js     # Copy of templates/overlay-vanilla.js
-```
+**One template, every framework:** `~/.claude/skills/live-canvas/templates/overlay-vanilla.js`. Single file, zero dependencies, plain DOM. Works in vanilla JS, Vue, Svelte, Rails, Django, Phoenix, plain HTML, Next.js, Vite-React, Remix — anywhere a `<script>` tag runs.
 
-HTML: `<script src="overlay-vanilla.js"></script>` plus an init script that wires up mode + target (see "Wiring the overlay" below).
+Copy it into a directory served by the dev server (e.g. `public/overlay-vanilla.js` for Next.js, `static/overlay-vanilla.js` for Vite, the public dir for Rails/Django). Reference it from the lab page.
 
 ### Wiring the overlay
 
-Every page that renders the lab must initialize the overlay once. Behavior depends on whether Live mode was detected in Phase 0.
+The overlay needs one `init()` call with `target`, `channelUrl` (Live only), and optionally `batchEndpoint`.
 
-**Vanilla (`overlay-vanilla.js`):**
+**Server-rendered / vanilla HTML:**
 
 ```html
-<script src="./overlay-vanilla.js"></script>
+<script src="/overlay-vanilla.js"></script>
 <script>
   LiveCanvas.init({
     target: '<ComponentOrPageName>',
-    // Only include channelUrl when Phase 0 detected a live channel.
-    // If Batch mode, OMIT channelUrl so the overlay skips the probe.
+    // Only include channelUrl when the user picked Live and the probe succeeded.
+    // In JSON mode, OMIT channelUrl so the overlay skips the probe.
     channelUrl: 'http://localhost:8788',
-    // Optional: where to POST batch payloads when channelUrl is missing.
-    // When omitted, a batch Submit downloads a JSON file instead.
+    // Optional: where to POST JSON payloads when channelUrl is missing.
+    // When omitted, Submit downloads a JSON file instead.
     batchEndpoint: '/__live_canvas/feedback',
   });
 </script>
 ```
 
-**React (`FeedbackOverlay.tsx`):**
+**React / Next.js / Vite-React:** load the script with the framework's mechanism and init in a `useEffect`:
 
-Pass the same `targetName` prop plus the mode-appropriate endpoints via its props. Render `<FeedbackOverlay />` at the end of the lab page.
+```tsx
+import Script from 'next/script';
+import { useEffect } from 'react';
+
+export default function Lab() {
+  useEffect(() => {
+    (window as any).LiveCanvas?.init({
+      target: 'PostCard',
+      channelUrl: 'http://localhost:8788', // omit in JSON mode
+    });
+  }, []);
+  return (<>
+    <Script src="/overlay-vanilla.js" strategy="afterInteractive" />
+    {/* variants ... */}
+  </>);
+}
+```
+
+Vite-React: use `<script>` in `index.html` or `useEffect` with a dynamic `import()`. Same `LiveCanvas.init({...})` call.
 
 ### Why the templates live in the route directory
 
@@ -555,6 +545,7 @@ The Live Canvas page must include:
 1. **Header** with:
    - Design Brief summary (target, scope, key requirements)
    - Instructions for reviewing
+   - **Lab banner (REQUIRED)** — paste `~/.claude/skills/live-canvas/templates/lab-banner.html` at the top of the lab page. Same text in any mode. For React/TSX labs, translate the inline style to a JS object: camelCase keys, string values. E.g. `style="border-radius:8px; padding:10px 14px; font-size:13px"` → `style={{ borderRadius: '8px', padding: '10px 14px', fontSize: '13px' }}`. Keep the text and `role="note"`.
 
 2. **Variant Grid** with:
    - Clear labels (A, B, C, D, E)
@@ -575,43 +566,13 @@ The Live Canvas page must include:
 
    ⚠️ **THIS IS THE MOST IMPORTANT REQUIREMENT** ⚠️
 
-   The FeedbackOverlay enables users to click on elements and leave comments. Without it, the Live Canvas is just a static page with no way to collect structured feedback.
-
-   - Create `FeedbackOverlay.tsx` in the SAME directory as `page.tsx`
-   - Import with relative path: `import { FeedbackOverlay } from './FeedbackOverlay'`
-   - Render at the END of the page, after all variants
-   - Pass `targetName` prop with the component/page name
+   The overlay (`overlay-vanilla.js`) enables users to click on elements and leave comments. Without it, the Live Canvas is just a static page with no way to collect structured feedback.
 
-   **Example integration:**
+   - Copy `~/.claude/skills/live-canvas/templates/overlay-vanilla.js` into a directory served by the dev server (e.g. `public/`, `static/`, or wherever the framework serves static assets).
+   - Reference it from the lab page via `<script>` tag and call `LiveCanvas.init({...})` once with `target`, `channelUrl` (Live mode), and optional `batchEndpoint`. See "Wiring the overlay" above for the exact snippets per framework.
+   - Every variant container in the lab page MUST have a `data-variant="X"` attribute (A, B, C, D, E, or F). The overlay uses this to route comments to the right variant file.
 
-```tsx
-import { FeedbackOverlay } from './FeedbackOverlay';  // Relative import - always works
-
-export default function DesignLabPage() {
-  return (
-    <div className="min-h-screen bg-background">
-      <header>...</header>
-
-      <main>
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
-          <div data-variant="A">
-            <VariantA />
-          </div>
-          <div data-variant="B">
-            <VariantB />
-          </div>
-          {/* ... more variants */}
-        </div>
-      </main>
-
-      {/* CRITICAL: FeedbackOverlay must be included */}
-      <FeedbackOverlay targetName="ComponentName" />
-    </div>
-  );
-}
-```
-
-   **If you forget the FeedbackOverlay, the user CANNOT provide feedback.** This defeats the entire purpose of the Live Canvas.
+   **If you forget to wire up the overlay, the user CANNOT provide feedback.** This defeats the entire purpose of the Live Canvas.
 
 ### Code Quality
 
@@ -665,17 +626,17 @@ Make sure your dev server is running, then:
   4. Keep going, or tell me "done" whenever you're ready to synthesize a winner
 ```
 
-**If BATCH mode:**
+**If JSON mode:**
 
 ```
-📝 Live Canvas ready — Batch mode
+📝 Live Canvas ready — JSON mode
 
 Variants are at: http://localhost:3000/__live_canvas
 
 Click "Add Feedback" (bottom-right), comment on elements, fill "Overall Direction", click Submit.
 Then paste the JSON/markdown here, or just tell me your feedback in plain English.
 
-(To enable Live mode next time, see the one-time setup printed at the top.)
+(To use Live mode next time: relaunch with `live-claude` and pick Live when /live-canvas asks.)
 ```
 
 ### Then proceed to Phase 5
@@ -717,7 +678,7 @@ make this more prominent
 
 If multiple `<channel>` tags arrive together, batch the acknowledgments but do each edit one at a time so the user's dev server hot-reloads visibly between changes.
 
-### Batch mode — interactive or pasted
+### JSON mode — interactive or pasted
 
 The Live Canvas includes a Figma-like feedback overlay. When presenting the lab, include these instructions:
 
@@ -910,6 +871,7 @@ When abort is detected:
    - "Are you sure you want to cancel? This will delete all the Live Canvas files I created."
 
 2. **If confirmed, clean up immediately:**
+   - If Live mode was active, call `mcp__live-canvas__channel_close` to release port 8788.
    - Delete `.claude-design/` directory entirely
    - Delete temporary route files (`app/__live_canvas/`, etc.)
    - Do NOT generate any implementation plan
@@ -926,6 +888,8 @@ When user confirms (selected "Yes, finalize it"):
 
 ### 8.1: Cleanup
 
+If Live mode was active, call `mcp__live-canvas__channel_close` to release port 8788 so another session can claim it.
+
 Delete all temporary files:
 - Remove `.claude-design/` directory entirely
 - Remove temporary route files:

package/packages/{ampcode/commands/live-canvas/templates/demo → claude/skills/live-canvas/dev}/post-variants.html

@@ -79,6 +79,9 @@
 <header>
   <h1>Live Canvas — Post card demo</h1>
   <p>5 variations of a social post (likes, retweets, comments). Click <b>Add Feedback</b> bottom-right → click any element → leave a comment. Right-click the pill to submit.</p>
+  <div style="background:#fef3c7;border:1px solid #fbbf24;border-radius:8px;padding:10px 14px;margin-top:12px;font-size:13px;color:#78350f;">
+    <b>This is an overlay-only demo.</b> Feedback events transit through the Live channel (or JSON file, with <code>?json=1</code>) so you can verify the UI works — but there are no <code>.claude-design/lab/variants/</code> files behind these cards, so the Claude session receiving events <em>cannot</em> edit anything. For the full lifecycle, run <code>/live-canvas</code> in a real project.
+  </div>
 </header>
 
 <main>
@@ -193,12 +196,14 @@
 
 </main>
 
-<!-- Overlay (relative path works with file://) -->
-<script src="../overlay-vanilla.js"></script>
+<!-- Overlay (served from sibling templates/ dir; works under any static server rooted at the skill dir) -->
+<script src="../templates/overlay-vanilla.js"></script>
 <script>
+  // ?json=1 forces JSON mode (skip channel probe); default tries Live first.
+  const forceJson = new URLSearchParams(location.search).has('json');
   LiveCanvas.init({
     target: 'PostCard',
-    channelUrl: 'http://localhost:8788',
+    ...(forceJson ? {} : { channelUrl: 'http://localhost:8788' }),
   });
 </script>
 </body>

package/packages/claude/skills/live-canvas/templates/lab-banner.html

@@ -0,0 +1,6 @@
+<div role="note" style="background:#fefce8;border:1px solid #facc15;border-radius:8px;padding:10px 14px;margin:12px 0;font-size:13px;line-height:1.5;color:#854d0e;">
+  <b>This is a temporary design lab.</b> Click any element → leave a comment → Save.
+  Your feedback goes to Claude; the lab is deleted on Finish. The overlay
+  badge (bottom-right) tells you whether feedback is streaming live or being
+  collected as JSON.
+</div>

package/packages/claude/skills/live-canvas/templates/overlay-vanilla.js

@@ -23,7 +23,7 @@
  *   Batch — saves accumulate locally; Submit All POSTs JSONL to batchEndpoint
  *           (or downloads the file if no endpoint configured)
  *
- * Payload schema: v1.0, compatible with the upstream React FeedbackOverlay.
+ * Payload schema: v1.0 (see live-canvas-channel/schema.json).
  */
 (function () {
   'use strict';
@@ -38,11 +38,16 @@
     batchEndpoint: null,
     active: false,
     picking: false,
+    minimized: false,                            // collapsed to a single bubble?
     comments: [],                                // Comment[] — only items pending batch submit
     overall: '',
     pinCounts: Object.create(null),              // `${variant}|${selector}` → placed-pin count
   };
 
+  // Persist collapse state across hot reloads / variant switches.
+  const MIN_KEY = 'lc-minimized';
+  try { state.minimized = sessionStorage.getItem(MIN_KEY) === '1'; } catch (_) {}
+
   // ---------- utilities ----------
 
   const uid = () => `c-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -134,7 +139,8 @@
     const css = `
       [${DATA_OVERLAY}] { font-family: system-ui, sans-serif; box-sizing: border-box; }
       .${PFX}-bar { position: fixed; right: 16px; bottom: 16px; z-index: 2147483646;
-        display: flex; gap: 8px; }
+        display: flex; gap: 8px; align-items: center; }
+      .${PFX}-bar[data-hidden='1'] { display: none; }
       .${PFX}-btn { border: 0; border-radius: 999px; padding: 10px 16px;
         font-weight: 600; font-size: 13px; cursor: pointer;
         box-shadow: 0 4px 12px rgba(0,0,0,.25); font-family: inherit; }
@@ -146,9 +152,22 @@
       .${PFX}-submit .${PFX}-count { display: inline-block; background: #d946ef; color: #fff;
         border-radius: 999px; min-width: 18px; padding: 0 6px; margin-left: 6px;
         font-size: 11px; line-height: 18px; text-align: center; }
+      .${PFX}-min { width: 32px; height: 32px; padding: 0; border-radius: 50%;
+        background: #fff; color: #111; border: 1px solid #e4e4e7; font-size: 16px;
+        line-height: 1; display: flex; align-items: center; justify-content: center; }
+      .${PFX}-bubble { position: fixed; right: 16px; bottom: 16px; z-index: 2147483646;
+        width: 36px; height: 36px; border-radius: 50%; border: 0; cursor: pointer;
+        background: #111; color: #fff; font-size: 14px; font-weight: 700;
+        box-shadow: 0 4px 12px rgba(0,0,0,.25); display: none; }
+      .${PFX}-bubble[data-show='1'] { display: flex; align-items: center; justify-content: center; }
       .${PFX}-mode { position: fixed; right: 16px; bottom: 60px; z-index: 2147483646;
         background: rgba(0,0,0,.75); color: #fff; font-size: 11px;
         padding: 4px 8px; border-radius: 4px; pointer-events: none; }
+      .${PFX}-mode[data-hidden='1'] { display: none; }
+      @media (max-width: 640px) {
+        .${PFX}-popup { left: 8px !important; right: 8px; width: auto !important; max-width: none; }
+        .${PFX}-submit-card { width: 100% !important; max-width: calc(100vw - 24px); }
+      }
       .${PFX}-picking { cursor: crosshair !important; }
       .${PFX}-hover-outline { outline: 2px solid #d946ef !important; outline-offset: 2px; }
       .${PFX}-pin { position: absolute; z-index: 2147483645; width: 24px; height: 24px;
@@ -235,9 +254,33 @@
 
   // ---------- UI ----------
 
-  let toggleBtn, submitBtn, modeBadge, toast, popupNode;
+  let toggleBtn, submitBtn, minBtn, bubbleBtn, barNode, modeBadge, toast, popupNode;
   let hoverEl = null;
 
+  const applyMinimized = () => {
+    if (!barNode) return;
+    barNode.setAttribute('data-hidden', state.minimized ? '1' : '0');
+    modeBadge.setAttribute('data-hidden', state.minimized ? '1' : '0');
+    bubbleBtn.setAttribute('data-show', state.minimized ? '1' : '0');
+    // state.mode can flip live → batch mid-session if a push fails; refresh
+    // the badge each time we re-show it so it doesn't lie.
+    if (!state.minimized) {
+      modeBadge.textContent = `${state.mode === 'live' ? 'LIVE' : 'JSON'} mode`;
+    }
+    // Cancel an active pick when collapsing — otherwise clicks land on the page.
+    if (state.minimized && state.picking) {
+      state.picking = false;
+      setPickingCursor(false);
+      clearHover();
+      toggleBtn.setAttribute('data-active', '0');
+      toggleBtn.textContent = 'Add Feedback';
+    }
+    closePopup();
+    try { sessionStorage.setItem(MIN_KEY, state.minimized ? '1' : '0'); } catch (_) {}
+  };
+
+  const setMinimized = (v) => { state.minimized = !!v; applyMinimized(); };
+
   const pendingCount = () => state.comments.filter(c => !c.delivered).length;
 
   const refreshSubmitBtn = () => {
@@ -442,14 +485,29 @@
     submitBtn = el('button', { class: `${PFX}-btn ${PFX}-submit`, on: {
       click: openSubmitModal,
     }});
+    minBtn = el('button', {
+      class: `${PFX}-btn ${PFX}-min`,
+      title: 'Hide overlay',
+      'aria-label': 'Hide overlay',
+      on: { click: () => setMinimized(true) },
+    }, '−');
     refreshSubmitBtn();
-    const bar = el('div', { class: `${PFX}-bar` }, [submitBtn, toggleBtn]);
-    modeBadge = el('div', { class: `${PFX}-mode` }, `${state.mode === 'live' ? 'LIVE' : 'BATCH'} mode`);
+    barNode = el('div', { class: `${PFX}-bar` }, [minBtn, submitBtn, toggleBtn]);
+    bubbleBtn = el('button', {
+      class: `${PFX}-bubble`,
+      title: 'Show feedback overlay',
+      'aria-label': 'Show feedback overlay',
+      on: { click: () => setMinimized(false) },
+    }, '◐');
+    modeBadge = el('div', { class: `${PFX}-mode` }, `${state.mode === 'live' ? 'LIVE' : 'JSON'} mode`);
     toast = el('div', { class: `${PFX}-toast` });
-    document.body.appendChild(bar);
+    document.body.appendChild(barNode);
+    document.body.appendChild(bubbleBtn);
     document.body.appendChild(modeBadge);
     document.body.appendChild(toast);
 
+    applyMinimized();
+
     document.addEventListener('mousemove', onMouseMove, true);
     document.addEventListener('click', onClick, true);
   };