Make Pages Interactive

Make Pages Interactive

Turns any folder of HTML files into a place the user can leave inline comments on (text selections, element selections, page-level notes). Comments POST to a local JSONL inbox; you (the agent) Monitor that inbox, edit the HTML in response, append to feedback/history.json, and the page auto-reloads with a walkthrough of what changed.

When to invoke

User says any of:

• "make this page interactive" / "make these pages interactive" → Setup flow
• "add feedback to this page" / "let me comment on this page" → Setup flow
• "set up feedback on <dir>" → Setup flow
• "stop the feedback server" / "kill the server" / "shut it down" → Stop flow
• "remove the feedback layer" / "make pages static again" → Removal flow
• "update the make-pages-interactive skill" → Update flow

Setup flow (when user wants to make pages interactive)

1. Identify the target directory. Usually the user's current working directory or a folder they named. If ambiguous, ask.
2. Inject the feedback tags into every *.html in that directory:

   python ~/.claude/skills/make-pages-interactive/scripts/inject.py <dir>

   Add --recursive if the pages live in subfolders. The script is idempotent — safe to re-run. It also creates <dir>/feedback/inbox.jsonl and <dir>/feedback/history.json if missing.
3. Pick a port. Default 5050. Before starting, check what's there:

   curl -s --max-time 2 http://localhost:5050/info

   • JSON with artifact_dir matching this <dir> → reuse it, skip to step 5.
   • JSON with a different artifact_dir → port is held by another exploration. Either ask the user to free it (lsof -ti:5050 | xargs kill) or use port 5051, 5052, … (try the next port; tell the user the URL).
   • No response → port 5050 is free.
4. Start the server in the background via Bash with run_in_background: true:

   python ~/.claude/skills/make-pages-interactive/lib/server.py <dir> --port <chosen>

   The server auto-shuts-down on parent death or 10 min of idle, so you don't need to manage its lifecycle.
5. Tell the user the URL. For example: http://localhost:5050/index.html (use whatever filename they actually have — index.html, report.html, etc.). If they have multiple pages, list the top-level ones.
6. Start a Monitor on the inbox so new comments notify you immediately:

   Monitor on path: <dir>/feedback/inbox.jsonl

   Do NOT poll — let the Monitor notification arrive.

Responding to a feedback batch

When a new batch arrives in inbox.jsonl:

• Read the entry. Each comment has a stable cf_id and a selector pointing to the exact element/text the user commented on.
• Edit the relevant HTML files to address each comment. Wrap each modified region with <span data-cf-change="ch-<short-slug>">…</span> (or add data-cf-change to an existing wrapping element) so the post-reload walkthrough can find the change. One anchor per change.
• Append a new batch object to the end of <dir>/feedback/history.json (newest = last; the library walks from the end to find the latest batch). Schema:

  {
    "batch_id": "b-<timestamp-or-slug>",
    "timestamp": "<ISO 8601>",
    "comments": [ /* echo back the inbox comments you addressed */ ],
    "changes": [
      {
        "id": "ch-<slug>",
        "in_response_to": ["<cf_id from inbox>"],
        "anchor": "ch-<slug>",   // must match a data-cf-change in the HTML
        "title": "short, concrete",
        "description": "longer prose (hidden in UI, just for the record)"
      }
    ]
  }

• The page polls history.json, sees the new batch, auto-reloads (scroll position preserved), and offers the user a walkthrough of the changes. The "processing…" banner clears automatically when any in_response_to matches a submitted comment id.

Post in-flight status while you work

When you receive feedback and start working, POST a short status string so the user sees what you're doing instead of just a generic spinner:

POST /status
{"comment_id": "<cf_id from inbox>", "message": "Filing 2 receipts to Google Sheet (~30s)"}

To clear an entry early, POST the same comment_id with message: null or "". Entries are auto-pruned by the server after 10 min so a crashed agent never leaves a stuck "working" message.

history.json remains the source of truth for "done" — the status message is decoration only. The banner clears the moment a matching batch lands in history.json, regardless of whether you cleared the status entry.