interactive-bun-artifacts

name	interactive-bun-artifacts
description	Use when a static HTML artifact is not enough for iterative feedback — you need to annotate elements in-place, hot-reload changes, capture structured comments, or build an interactive concept explorer. Triggers include: "make it interactive", "I want to click and leave comments", "hot reload", "annotate the design", or when the feedback loop between viewing and editing feels too slow.

Interactive Bun Artifacts

Overview

Promote a static HTML artifact to a live interactive local app using Bun as a zero-config local server with hot reload. The artifact gains: click-to-comment, editable regions, structured JSON export, and automatic reload on file change.

Core principle: Annotate decisions directly in the UI → export structured feedback → Claude reads it → hot reload shows the result.

This closes the loop between human judgment and Claude's edits without copy-pasting descriptions.

REQUIRED PREREQUISITE: Understand static-html-artifacts (Layer 1) first. Layer 2 builds on it.

When to Use

• Static inspection not enough — you want to click directly on what needs changing
• High-volume feedback: many small annotations across a large design
• Concept learning: want interactive buttons, levels, animations to explore ideas
• Iteration speed matters: avoid the describe→generate→open→repeat cycle
• You want Claude to see your feedback structurally (not as freeform prose)

Do NOT use when:

• A single round of changes is needed (Layer 1 suffices)
• You don't have Bun installed
• You need live external data (use Layer 3 instead)

Prerequisites

Install Bun (if not already installed):

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

Verify: bun --version

The Workflow

1. Start from a static HTML artifact (Layer 1) or ask Claude to make one
2. Ask Claude to promote it to a Bun interactive server
3. Claude creates: server.ts + updated artifact.html
4. Run: bun run server.ts  (Claude gives you the exact command)
5. Open browser at localhost:[port]
6. Click elements to leave comments
7. Press "Export to JSON" — feedback copied to clipboard
8. Paste JSON into Claude
9. Claude updates artifact.html
10. Browser hot-reloads automatically — no manual refresh

Promotion Prompt: Static → Interactive

Use this prompt to upgrade any existing HTML artifact:

Take the existing [artifact-name].html and make it interactive using Bun 
as a lightweight local server with hot reload. Specifically:

1. Create a Bun server (server.ts) that serves the HTML and watches for 
   file changes, sending a reload signal to the browser.
2. Add click-to-comment: clicking anywhere on the page opens a small 
   comment bubble anchored to that element.
3. Add an "Export to JSON" button fixed in the top-right corner. 
   Clicking it copies all comments to the clipboard as structured JSON:
   { element: "<css selector or description>", comment: "..." }[]
4. Serve everything on localhost:3000 (or next available port).
5. Tell me the exact command to run it.

Fresh Interactive Artifact Prompt

When starting from scratch (no existing static artifact):

Create an interactive Bun artifact for [purpose]. 

Requirements:
- Bun server (server.ts) with hot reload via WebSocket
- HTML file with: [describe content — design, explainer, dashboard, etc.]
- Click anywhere to leave inline comments
- "Export to JSON" button (top-right, fixed) copies all feedback to clipboard
- Run on localhost:3000

Give me the exact command to start it.

Complete Example: Design Refinement Loop

Scenario: You have 20 card variations from Layer 1. You want to annotate them and get Claude to iterate.

Step 1 — Promote to interactive:

Take pricing-card-variations.html and make it interactive with Bun. 
Add click-to-comment on each variation, hot reload, and Export to JSON. 
Serve on localhost:3000. Give me the run command.

Step 2 — Claude produces:

server.ts
pricing-card-variations.html  (updated with comment + export JS)

Run with:  bun run server.ts

Step 3 — You open localhost:3000, click on Variation 3:

Comment: "Layout is right but the whitespace above the CTA is too large"

Click on Variation 11:

Comment: "Typography weight perfect here — use this font scale everywhere"

Click on Variation 7:

Comment: "Remove this entirely — too much visual noise"

Step 4 — Press "Export to JSON". Clipboard now contains:

[
  {
    "element": "variation-3 .cta-section",
    "comment": "Layout is right but the whitespace above the CTA is too large"
  },
  {
    "element": "variation-11 .heading",
    "comment": "Typography weight perfect here — use this font scale everywhere"
  },
  {
    "element": "variation-7",
    "comment": "Remove this entirely — too much visual noise"
  }
]

Step 5 — Paste into Claude:

Here is my feedback from the design review:
[paste JSON]

Please apply these changes to the artifact and also create a final 
"Winner" variation at the bottom that combines the best elements.

Step 6 — Claude edits pricing-card-variations.html. Browser hot-reloads. You see the updated version without refreshing.

Complete Example: Interactive Concept Explainer

Scenario: Claude Code added PgBouncer to your stack. You want to understand how it works.

Make me an interactive Bun artifact that explains how PgBouncer works. Include:
- An animated diagram showing: client → PgBouncer → Postgres pool → DB
- Three tabs: "Without PgBouncer", "With PgBouncer", "Transaction Pooling Mode"
- Clickable connection objects in the diagram (click to see what each does)
- A "stress test" button that animates many concurrent connections arriving 
  and shows how PgBouncer queues them
- Hot reload via Bun server
- Click-to-comment + Export to JSON on all elements

Run on localhost:3001.

What you get: A visual, clickable explainer you can interact with, annotate, and ask Claude to deepen any section of.

Complete Example: LinkedIn Post Editor

Scenario: You're iterating on a LinkedIn post and want to edit it in place.

Create a Bun interactive artifact for my LinkedIn post editing workflow:

- Left panel: editable post text (contenteditable div styled like LinkedIn)
- Right panel: live preview of how it renders (LinkedIn desktop layout sim)
- The preview updates as I type
- "Suggest 3 alternatives" button: clicking it sends the current text 
  to me as JSON so I can paste to Claude
- Export to JSON captures both the current text and any inline comments 
  I've left on the preview
- Bun server with hot reload on localhost:3002

The server.ts Pattern

Claude should generate something like this (reference for debugging):

import { serve } from "bun";
import { statSync } from "fs";
import { resolve } from "path";

const ARTIFACT = resolve("./artifact.html");
const clients = new Set<any>();
let lastMod: number = statSync(ARTIFACT).mtimeMs;

const server = serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);

    // WebSocket upgrade for hot reload
    if (url.pathname === "/__reload") {
      if (server.upgrade(req)) return undefined;
    }

    // Serve the HTML artifact
    if (url.pathname === "/" || url.pathname === "/index.html") {
      return new Response(Bun.file(), {
        : { :  },
      });
    }

      (, { :  });
  },
  : {
    () { clients.(ws); },
    () { clients.(ws); },
    () {},
  },
});



( {
   {
     mtime = ().;
     (mtime !== lastMod) {
      lastMod = mtime;
       ( ws  clients) ws.();
      .();
    }
  }  {}
}, );

.();

The HTML artifact includes a small <script> that connects to /__reload and calls location.reload() on message.

Windows note: Run the server in a dedicated terminal window — do NOT use & to background it in Git Bash, as job control will suspend the process and prevent the polling interval from firing.

The Export JSON Schema

Standardize what Claude generates so your feedback is machine-readable:

[
  {
    "element": "string — CSS selector, variation label, or visual description",
    "position": { "x": 120, "y": 340 },
    "comment": "string — your annotation",
    "timestamp": "ISO 8601"
  }
]

Iterating with Pasted Feedback

After pasting JSON back to Claude, always frame it like this:

Here is structured feedback from my annotation session on [artifact-name]:

[paste JSON]

Please:
1. Apply each change to the artifact
2. Add a changelog section at the bottom of the HTML listing what changed
3. Keep the Export to JSON button and hot reload intact

Tips

• Run Bun server in a separate terminal — keep it running while you work in Claude Code
• Port collisions: if 3000 is taken, ask Claude to try 3001, 3002 etc.
• Save your JSON exports to a file before pasting — you may want to revisit earlier feedback
• Comment specificity matters: "too much whitespace" is vague; "padding-top on .cta is too large" gets a better edit
• Use the concept explainer pattern for anything you don't understand in your codebase

Common Mistakes

Mistake	Fix
Forgetting to run the server	Always run bun run server.ts first, then open browser
Hot reload not working	Ask Claude: "add a WebSocket-based reload signal to server.ts"
Comments not exporting	Check browser console — likely a clipboard permissions issue
Losing feedback between sessions	Save JSON to feedback-[date].json before closing browser
Bun not installed	curl -fsSL https://bun.sh/install | bash or irm bun.sh/install.ps1 | iex