ui

Files (3)

• SKILL.md
• chat-popover.html · references/
• server.py · references/

SKILL.md (first lines)

# UI — browser-side collaboration surface (Experimental)

A side-channel for tasks that would otherwise look like "ok, next… ok, next…" in
chat, *or* for chat itself when the user wants to see your replies in a browser
popover and reply from there.

Two surfaces, mix and match per task:

1. **Structured UI** — the main page content (table, form, list, etc.).
  Browser ↔ you via `in.json` / `out.json`.
2. **Chat popover** — floating chat panel in the corner. **Always embedded by
  default**, even alongside a structured-UI page. Only omit it if the user
   explicitly asks you to (e.g. "no chat popover", "skip the chat panel").
   Browser ↔ you via `chat-in.json` / `chat-out.json`. Same plumbing; separate
   files.

## When to reach for it

When the user explicitly invokes it.

## Setup

1. Create a randomly-named serve dir. Its name is the only thing keeping random network neighbours off the page, so don't print it anywhere public:
  ```sh
   SERVE_DIR=/tmp/ui-$(python3 -c 'import secrets; print(secrets.token_hex(12))')
   mkdir -p "$SERVE_DIR"
  ```
2. Write a self-contained page at `$SERVE_DIR/index.html`. Inline CSS and JS, no build step, no external assets, no file picker. The server will hand it to the browser at `http://127.0.0.1:<port>/`.
  In the page JS, talk to the server over same-origin HTTP:
   Debounce `saveInput` ~400ms. Poll `pollOutput` every 1–2s.
   Embed the chat popover template by default — see **Chat popover** below.
   Skip it only if the user explicitly opted out.
3. Start the bundled server scoped to that dir, on an OS-assigned port, in the background:
  ```sh
   SERVE_ROOT=$SERVE_DIR python3 .claude/skills/ui/references/server.py
  ```
   Run via Bash with `run_in_background: true`. Read the first stdout line from the task output file to find the assigned port (`serving … at http://127.0.0.1:<port>`).
4. Tell the user: open `http://127.0.0.1:<port>/`. No Connect button, no file picker — the page is already wired to the server it came from.

## Event shape

You decide per task. Defaults that work:

- **In** (`in.json`, browser → you): one JSON object, fully rewritten on every save. Keys are row/item ids, values are whatever the user is filling. Easy to diff between writes.
- **Out** (`out.json`, you → browser): a JSON array of events, append-only. Each entry: `{ id, type, payload }`. Browser tracks last-seen id and only acts on new ones.

Pick `type` names that match what the UI does — `highlight`, `markDone`, `setNote`, `toast`, `finish`, etc. Build the browser-side handler for each type before you start using it. The browser ignores unknown types.

## Chat popover

A floating panel that lets the user read your replies and write back from the
browser. Reuses the same server; just adds two more files.

**Default-on.** Every page you generate under this skill should include the
popover unless the user explicitly told you not to. It's the fallback chat
channel when the structured UI doesn't have a natural place to ask a question.

**Files (relative to `$SERVE_DIR`):**

- `chat-in.json` — full array of user messages, browser rewrites via `/write` on each send.
- `chat-out.json` — full array of your messages, you rewrite via the Write tool when you reply.

Each entry: `{ id: number, text: string, ts: number }` where `ts` is `Date.now()`
at write time. The page merges both arrays by `ts` to render the conversation
in order.

**Embedding the popover:**

The template lives at `.claude/skills/ui/references/chat-popover.html`. It contains three
blocks (`<style>`, two DOM nodes, `<script>`) — paste them straight into the
`<head>`/`<body>` of your generated `index.html`. The template is same-origin
and self-wires; no init call needed.

For chat-only sessions, the popover can be your entire UI — start it open by
default (`data-open="true"` on `#uiChatPanel`) and skip rendering anything
else in the page body.

**"Claude is thinking" indicator.** The template renders a pulsing-dots bubble
at the bottom of the log whenever the latest user message has no later
assistant reply — i.e. the user has spoken and you haven't answered yet. It
auto-clears as soon as you write a reply to `chat-out.json` with a `ts` newer
than the user's last message (this is one of the reasons real system-clock
timestamps matter — see **Sending a reply** below). A 90-second safety timeout
hides it if no reply lands, so the UI doesn't get stuck when you're not
monitoring.

**Watching incoming chat:**

Run a second persistent Monitor command alongside the task one, watching
`$SERVE_DIR/chat-in.json` for new entries:

```sh
last=""
while sleep 1; do
  cur=$(jq -r '.[] | "\(.id)\t\(.text)"' "$SERVE_DIR/chat-in.json" 2>/dev/null || true)
  if [ "$cur" != "$last" ]; then
    diff <(printf '%s\n' "$last") <(printf '%s\n' "$cur") | grep '^>' || true
    last="$cur"
  fi
done
```

Each notification batch carries any new user lines; respond when they land.

**Sending a reply:**

When you have something to say, append your message to `chat-out.json` (read it
first if it exists, append, write the full array back). Keep ids monotonic and
unique. The browser's poller picks it up within ~1.5s and renders it in the
panel; if the panel is closed the FAB shows an unread badge.

**Timestamps must come from the real system clock**, not from your head. The
browser merges user and assistant messages by `ts`, so a stale or invented value
re-orders the conversation. Always fetch the current epoch-ms with the shell
before composing the entry:

```sh
python3 -c 'import time;print(int(time.time()*1000))'
```

From micmania1/ai, MIT.

More from micmania1/ai