wicked-interactive 0.4.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "wicked-interactive",
+  "description": "Interactive HTML & presentation builder with an in-browser feedback loop for non-technical business users. Highlight blocks, attach plain-language feedback, regenerate live with the supervising Claude session in the loop. Versioned, forkable, exportable to self-contained HTML/PDF.",
+  "owner": {
+    "name": "Mike Parcewski",
+    "url": "https://github.com/mikeparcewski"
+  },
+  "plugins": [
+    {
+      "name": "wicked-interactive",
+      "description": "Interactive HTML & presentation builder with an in-browser feedback loop. One command starts the service, opens the browser, and puts the running Claude session into the supervising-agent loop. Deterministic edits apply instantly; structural edits are delegated to the agent through a data-wid-preserving request/response protocol. Requires sibling plugins wicked-prezzie, wicked-garden, and wicked-brain.",
+      "version": "0.4.0",
+      "source": "./",
+      "author": {
+        "name": "Mike Parcewski",
+        "url": "https://github.com/mikeparcewski"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "wicked-interactive",
+  "version": "0.4.0",
+  "description": "Interactive HTML & presentation builder with an in-browser feedback loop for non-technical business users. Build a draft, review it in the browser, highlight any block, attach plain-language feedback, and watch it regenerate live — with the supervising Claude session as the intelligence in the loop. Versioned, forkable, and exportable to self-contained HTML or PDF.",
+  "author": {
+    "name": "Mike Parcewski",
+    "url": "https://github.com/mikeparcewski"
+  },
+  "repository": "https://github.com/mikeparcewski/wicked-interactive",
+  "license": "MIT",
+  "keywords": [
+    "interactive-html",
+    "presentation-builder",
+    "in-browser-feedback",
+    "live-reload",
+    "data-wid-anchoring",
+    "versioned-documents",
+    "structural-editing",
+    "agent-in-the-loop",
+    "self-contained-export",
+    "html-to-pdf",
+    "business-users",
+    "wicked-prezzie",
+    "wicked-bus"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Parcewski
+
+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,76 @@
+```
+           _      _            _       _       _                      _   _           
+ __      _(_) ___| | _____  __| |     (_)_ __ | |_ ___ _ __ __ _  ___| |_(_)_   _____ 
+ \ \ /\ / / |/ __| |/ / _ \/ _` |_____| | '_ \| __/ _ \ '__/ _` |/ __| __| \ \ / / _ \
+  \ V  V /| | (__|   <  __/ (_| |_____| | | | | ||  __/ | | (_| | (__| |_| |\ V /  __/
+   \_/\_/ |_|\___|_|\_\___|\__,_|     |_|_| |_|\__\___|_|  \__,_|\___|\__|_| \_/ \___|
+```
+
+## It's 11pm. The deck's due tomorrow. You haven't opened PowerPoint.
+
+Good news: you don't have to. Just tell it what you need — out loud, like you'd tell a coworker — and watch it build the thing in your browser. The board deck. The launch one-pager. The sales page. A narrated demo video of your product. Then point at anything you don't like and say what to fix.
+
+No code. No design tickets. No "let me loop in the team." Just you, describing what's in your head, watching it appear.
+
+```
+Describe it  →  Watch it build  →  Point at what to change  →  Ship it (HTML · PDF · video)
+```
+
+If you can say it, you can make it.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mikeparcewski/wicked-interactive/main/assets/wicked-interactive-demo.gif" alt="wicked-interactive in action: describe a launch page in chat, watch it build live, point at text to change it, remove a block, ask to make it premium, and rewind any version — all in the browser" width="100%">
+</p>
+
+---
+
+## Stuff you'd normally dread making
+
+- 📊 **Decks** — board updates, pitch decks, QBRs. On-brand and export-ready, not a sad bulleted list.
+- 📄 **Docs & one-pagers** — reports, briefs, proposals, the FAQ nobody wants to write.
+- 📣 **Marketing** — landing pages, launch posts, sales pages, anything that lives on the web.
+- 🎬 **Demo videos** — point it at your live app, say what to show, get a narrated walkthrough with clickable chapter thumbnails.
+
+Under the hood it's all real, interactive HTML — built, polished, and exported without you ever leaving the browser.
+
+## Try it in 30 seconds
+
+Talk to it like this:
+
+> *"Build me a deck about our Q3 results from scratch."*
+> *"Make a landing page for the new pricing tier."*
+> *"Record a walkthrough of my app showing sign-up and the dashboard."*
+> *"Make this headline punchier — and that number's $4.2M, not $4M."*
+> *"Honestly? Make the whole thing feel more expensive."*
+
+It hands you a first draft. You click a thing, say what's wrong, and watch it fix itself — live, while you're looking at it. Every version quietly saves, so you can rewind to that one you liked three changes ago — or **fork** it and chase two ideas at once without losing either. When it looks right, export clean HTML or PDF, or grab the video. Done. Go to bed.
+
+## Why people get hooked
+
+- 🪄 **Just start talking.** Give it a topic, get a real first draft back. No blank page, ever.
+- 🖱️ **Fix it by pointing.** See something off? Highlight it, say what you want in plain English, done.
+- 📎 **It uses your actual numbers.** Drop in your files and folders; it reads them so the real figures show up — no copy-paste.
+- 🎬 **Your app becomes a video.** Narrated walkthrough with YouTube-style chapters. Want a different take? Just ask again.
+- ⏪ **You literally cannot lose work.** Every change is a saved version. Rewind to any of them, anytime.
+- 🍴 **Can't decide? Don't.** Fork any version and keep both, side by side.
+- 📤 **Send it to anyone.** One self-contained file — HTML, PDF, or video. Nothing for them to download or figure out.
+- 🙅 **No scary black terminal.** Once it's going, it all happens in your browser.
+
+## Get it running
+
+First, a one-time bit of setup. You'll need [Claude Code](https://claude.com/claude-code) — install it, then paste these two lines where it asks:
+
+```
+/plugin marketplace add mikeparcewski/wicked-interactive
+/plugin install wicked-interactive
+```
+
+And from then on, the only thing you ever type is:
+
+> **"start wicked-interactive"**
+
+That's genuinely it. The first time, it sets up a few helper tools behind the scenes — it'll show you exactly what it's installing, nothing sneaky — then your browser pops open and you're off. (Rather install the helpers yourself? Set `WI_NO_AUTOINSTALL=1` and it'll just tell you what to run.)
+
+---
+
+MIT licensed — see [LICENSE](LICENSE). Built on [wicked-prezzie](https://github.com/mikeparcewski/wicked-prezzie), [wicked-garden](https://github.com/mikeparcewski/wicked-garden), and [wicked-brain](https://github.com/mikeparcewski/wicked-brain).

package/bin/ensure-siblings.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// ensure-siblings.mjs — set up the helper tools wicked-interactive needs (ADR-0016).
+//
+// Run once at startup by the `serve` skill. For each MISSING sibling it runs the real
+// install command — transparently: every command is printed before it runs, so the user
+// always sees exactly what's happening on their machine. Nothing is installed silently.
+//
+//   node bin/ensure-siblings.mjs           # auto-install anything missing
+//   node bin/ensure-siblings.mjs --check   # report only, install nothing
+//   WI_NO_AUTOINSTALL=1 node …               # same as --check (opt out of auto-install)
+//
+// Cross-platform: spawnSync(..., { shell:true }) resolves `claude`/`npx` via PATH on
+// macOS, Linux, and Windows.
+
+import { spawnSync } from "node:child_process";
+import { preflight, playwrightInstalled } from "../src/service/preflight.js";
+
+// Playwright (ADR-0018) powers demo recording. It's an npm dependency, not a Claude plugin,
+// so it installs differently: pull the package + browser binaries, then the skills (the
+// supervising agent uses these to learn the target app). `playwright-cli install --skills`
+// relies on the softlinked skill dirs in the standard locations.
+const PLAYWRIGHT_STEPS = [
+  "npm install playwright",
+  "npx playwright install",
+  "playwright-cli install --skills",
+];
+
+// Each sibling installs differently — an ordered list of shell commands per plugin.
+//   prezzie / garden → Claude Code plugins (marketplace add, then install)
+//   brain            → npm package, run via npx
+const INSTALL_STEPS = {
+  "wicked-prezzie": [
+    "claude plugin marketplace add mikeparcewski/wicked-prezzie",
+    "claude plugin install wicked-prezzie",
+  ],
+  "wicked-garden": [
+    "claude plugin marketplace add mikeparcewski/wicked-garden",
+    "claude plugin install wicked-garden",
+  ],
+  "wicked-brain": [
+    "npx -y wicked-brain",
+  ],
+};
+
+function run(cmd) {
+  console.log(`  $ ${cmd}`);
+  return spawnSync(cmd, { stdio: "inherit", shell: true }).status === 0;
+}
+
+const checkOnly = process.argv.includes("--check") || process.env.WI_NO_AUTOINSTALL === "1";
+
+let pf = preflight();
+const pwMissing = !playwrightInstalled();
+if (pf.ok && !pwMissing) {
+  console.log("Helper tools: all present. Nothing to install.");
+  process.exit(0);
+}
+
+const wanted = [...pf.missing, ...(pwMissing ? ["playwright (demo recorder)"] : [])];
+console.log(`wicked-interactive needs ${wanted.length} helper tool(s): ${wanted.join(", ")}`);
+
+if (checkOnly) {
+  console.log("\nAuto-install is off. Install these yourself, then restart:");
+  if (pf.install_hint) console.log(pf.install_hint);
+  if (pwMissing) console.log(pf.playwright.install_hint);
+  process.exit(1);
+}
+
+console.log("\nSetting them up for you now (one time). Each command is shown before it runs:");
+for (const name of pf.missing) {
+  console.log(`\n• ${name}`);
+  for (const cmd of INSTALL_STEPS[name]) {
+    if (!run(cmd)) console.error(`  ! '${cmd}' did not succeed — continuing.`);
+  }
+}
+if (pwMissing) {
+  console.log(`\n• playwright (demo recorder)`);
+  for (const cmd of PLAYWRIGHT_STEPS) {
+    if (!run(cmd)) console.error(`  ! '${cmd}' did not succeed — continuing.`);
+  }
+}
+
+pf = preflight();
+if (pf.ok && playwrightInstalled()) {
+  console.log("\nAll set — every helper tool is installed.");
+  process.exit(0);
+}
+
+const stillMissing = [...pf.missing, ...(playwrightInstalled() ? [] : ["playwright"])];
+console.error(`\nStill missing: ${stillMissing.join(", ")}. Finish these by hand, then restart:`);
+if (pf.install_hint) console.error(pf.install_hint);
+if (!playwrightInstalled()) console.error(pf.playwright.install_hint);
+console.error("\n(If 'claude' isn't found, run this from inside Claude Code — that's where the plugin CLI lives.)");
+process.exit(1);

package/bin/wi-watch.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// wi-watch.mjs — operator-facing event tail for the multi-doc service.
+//
+// Connects to GET /api/events/all (added in ADR-0015 follow-up) and prints one event
+// per stdout line: `HH:MM:SS doc event {json}`. Each line is one event so it composes
+// with the Monitor tool's line-as-event model.
+//
+// Resilience (after the 2026-05-28 silent-watcher incident):
+//   - Reconnects on every terminal signal the socket can emit: end, error, close,
+//     AND socket-level error/close. The earlier version only handled end+error and
+//     went silent when an abrupt service kill emitted `close` first.
+//   - Stream watchdog: if no bytes (not even a heartbeat) arrive for STALL_MS, treat
+//     the connection as dead and reconnect. Catches the case where the socket is
+//     half-open (kernel never delivers an EOF).
+//   - 30s server-side heartbeat ping keeps proxies + the watchdog happy.
+//   - Reconnect is idempotent — only one reconnect timer fires per disconnect.
+//   - Backs off briefly between retries (250ms / 1s) so a crash-looping service doesn't
+//     melt the watcher.
+//   - Long-lived: never exits on its own. Stop it with SIGINT/SIGTERM or Monitor TaskStop.
+
+import http from "node:http";
+import { parseArgs } from "node:util";
+
+const { values: argv } = parseArgs({
+  options: {
+    base:   { type: "string", default: process.env.WI_BASE || "http://localhost:4400" },
+    quiet:  { type: "boolean", default: false },  // suppress connect/reconnect lines
+  },
+});
+
+const url = new URL("/api/events/all", argv.base);
+// 60s was too tight in practice — long-lived loopback streams occasionally go quiet for
+// ~1 min even with 15s heartbeats. 180s catches genuine dead sockets without false-tripping
+// every ~17 min. Real drops fire socket-close events immediately anyway.
+const STALL_MS = 180_000;
+
+function ts() { return new Date().toISOString().slice(11, 19); }
+function note(msg) { if (!argv.quiet) console.log(`${ts()} watcher ${msg}`); }
+
+let activeReq = null;     // the in-flight request; destroyed before each reconnect to
+                          // prevent parallel SSE streams (event-spam after a stall reconnect)
+
+function connect() {
+  let scheduled = false;
+  let stallTimer = null;
+  function scheduleReconnect(reason, delayMs) {
+    if (scheduled) return;            // first signal wins; ignore the others
+    scheduled = true;
+    if (stallTimer) { clearTimeout(stallTimer); stallTimer = null; }
+    if (activeReq) { try { activeReq.destroy(); } catch {} activeReq = null; }
+    note(`${reason} — reconnecting in ${delayMs}ms`);
+    setTimeout(connect, delayMs);
+  }
+  function bumpWatchdog() {
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => scheduleReconnect(`no traffic for ${STALL_MS}ms`, 250), STALL_MS);
+  }
+
+  const req = http.get(url, (res) => {
+    if (res.statusCode !== 200) {
+      note(`http ${res.statusCode}`);
+      res.resume();
+      scheduleReconnect("non-200", 1000);
+      return;
+    }
+    note(`connected ${url.href}`);
+    bumpWatchdog();
+    let buf = "";
+    res.setEncoding("utf8");
+    res.on("data", (chunk) => {
+      bumpWatchdog();
+      buf += chunk;
+      let i;
+      while ((i = buf.indexOf("\n\n")) !== -1) {
+        const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+        let ev = "?", data = "";
+        for (const line of frame.split("\n")) {
+          if (line.startsWith("event: ")) ev = line.slice(7);
+          else if (line.startsWith("data: ")) data += line.slice(6);
+        }
+        if (ev === "ready") continue;
+        // SSE comment frames (server-side heartbeats start with `:`) have no event:/data:
+        // lines, so ev/data stay empty. Skip them — they keep the connection warm but
+        // shouldn't surface as conversation notifications.
+        if (ev === "?" && !data) continue;
+        let parsed = data;
+        try { parsed = JSON.stringify(JSON.parse(data)); } catch { /* keep raw */ }
+        let doc = "?";
+        try { const o = JSON.parse(data); if (o.doc) doc = o.doc; } catch {}
+        console.log(`${ts()} ${doc} ${ev} ${parsed.slice(0, 280)}`);
+      }
+    });
+    res.on("end",   ()  => scheduleReconnect("stream end", 250));
+    res.on("close", ()  => scheduleReconnect("stream close", 250));
+    res.on("error", (e) => scheduleReconnect(`stream error: ${e.message}`, 1000));
+    // Socket-level events catch abrupt TCP resets that don't surface as response events.
+    if (res.socket) {
+      res.socket.on("error", (e) => scheduleReconnect(`socket error: ${e.message}`, 1000));
+      res.socket.on("close",  ()  => scheduleReconnect("socket close", 250));
+    }
+  });
+  req.setTimeout(0);
+  req.on("error", (e) => scheduleReconnect(`http error: ${e.message}`, 1000));
+  activeReq = req;
+}
+
+process.on("SIGINT",  () => { note("SIGINT — bye"); process.exit(0); });
+process.on("SIGTERM", () => { note("SIGTERM — bye"); process.exit(0); });
+
+note(`starting; tailing ${url.href}`);
+connect();

package/bin/wicked-interactive.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// wicked-interactive CLI — the one command a business user runs (INV-6).
+//
+//   wicked-interactive serve --root <docs-dir> [--port N] [--watch]
+//       Multi-document mode (ADR-0015). Hosts every workspace under <docs-dir>;
+//       new docs are created from the UI ("New document" modal). Preferred.
+//       --watch also tails /api/events/all in the same terminal — operator visibility
+//       into every per-doc broadcast.
+//
+//   wicked-interactive serve --dir <workspace> [--html <file>] [--port N]
+//       Legacy single-document mode. Workspace must exist; --html seeds _v0.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { createServer, createMultiServer } from "../src/service/server.js";
+import { initWorkspace } from "../src/service/workspace.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) { args._.push(a); continue; }
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    // Boolean flag if the next arg is missing or itself another --flag; otherwise consume it.
+    if (next === undefined || next.startsWith("--")) args[key] = true;
+    else { args[key] = next; i++; }
+  }
+  return args;
+}
+
+/** Spawn wi-watch.mjs (sibling in bin/) as a child and pipe its lines into the parent's stdout. */
+function spawnWatcher(base) {
+  const script = resolve(HERE, "wi-watch.mjs");
+  const child = spawn(process.execPath, [script, "--base", base], { stdio: ["ignore", "inherit", "inherit"] });
+  child.on("exit", (code, sig) => console.log(`[watch] exited (code=${code} sig=${sig})`));
+  return child;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  if (cmd !== "serve") {
+    console.error("usage: wicked-interactive serve { --root <docs-dir> | --dir <workspace> [--html <file>] } [--port N]");
+    process.exit(1);
+  }
+
+  const port = args.port ? Number(args.port) : 4400;
+
+  if (args.root) {
+    const svc = createMultiServer({ root: args.root });
+    const actualPort = await svc.start(port);
+    const base = `http://localhost:${actualPort}`;
+    console.log(`wicked-interactive (multi-doc) serving ${args.root} on ${base}`);
+    console.log(`  docs:   ${base}/api/docs`);
+    console.log(`  open:   ${base}/?doc=<name>`);
+    console.log(`  tail:   ${base}/api/events/all`);
+    let watcher = null;
+    if (args.watch) {
+      console.log("  --watch: tailing events in this terminal");
+      watcher = spawnWatcher(base);
+    }
+    const shutdown = async () => { if (watcher) watcher.kill(); await svc.stop(); process.exit(0); };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return;
+  }
+
+  if (!args.dir) {
+    console.error("error: pass --root <docs-dir> (multi-doc) or --dir <workspace> (legacy)");
+    process.exit(1);
+  }
+  const dir = args.dir;
+  if (!existsSync(join(dir, "versions.json"))) {
+    if (!args.html) {
+      console.error(`error: workspace ${dir} is not initialised; pass --html <file> to seed it`);
+      process.exit(1);
+    }
+    initWorkspace(dir, readFileSync(args.html, "utf-8"));
+    console.log(`initialised workspace at ${dir} from ${args.html}`);
+  }
+  const svc = createServer({ dir, documentId: dir });
+  const actualPort = await svc.start(port);
+  console.log(`wicked-interactive (single-doc) serving ${dir} on http://localhost:${actualPort}`);
+  console.log(`  head:   http://localhost:${actualPort}/doc`);
+  console.log(`  events: http://localhost:${actualPort}/events`);
+  const shutdown = async () => { await svc.stop(); process.exit(0); };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });