glimpse-cli 0.0.1 → 0.2.0

package/docs/PRD.md

@@ -0,0 +1,356 @@
+# glimpse-cli PRD
+
+## Purpose
+
+`glimpse-cli` is a command-line wrapper around the Glimpse micro-UI runtime. It lets scripts and agents open native UI windows, collect user input, and update existing windows over time without embedding Glimpse runtime code directly in every script.
+
+macOS is the first supported implementation target, but the command and data model should remain platform-neutral.
+
+## Implementation Stack
+
+v1 should use a minimal dependency policy while avoiding custom implementations for well-solved infrastructure.
+
+- Runtime/tooling: Bun with TypeScript.
+- Package identity: publish as `glimpse-cli` with binary name `glimpse`.
+- Binary goal: keep the code compatible with `bun build --compile` so `glimpse` can become a standalone binary.
+- CLI parser: `commander`.
+- JSON validation: `valibot` for command inputs, IPC payloads, command results, and persisted daemon state.
+- Logging: `evlog` for structured daemon/CLI diagnostics.
+- UI runtime: `glimpseui` from npm. Direct Glimpse imports should be isolated behind an internal adapter module so runtime package/API changes do not leak into command logic.
+- File watching: start with built-in file watching for single-file HTML watch mode. If reliability issues appear or directory watching is needed, prefer `@parcel/watcher` over `chokidar`. Avoid `chokidar` by default due to prior memory-leak concerns and because v1 does not need glob-heavy watcher features. Before adopting `@parcel/watcher`, verify compatibility with `bun build --compile` because it uses native components.
+- IPC: built-in Unix domain sockets via `node:net` on macOS, using newline-delimited JSON for request/response framing. IPC methods mirror CLI command names to keep command parsing and daemon dispatch simple.
+- IDs: built-in `node:crypto` UUIDs.
+- URL/DNS checks: built-in `node:url`, `node:dns/promises`, and `node:net`.
+- Duration parsing: small local helper for `ms`, `s`, and `m` suffixes.
+
+Avoid additional dependencies in v1 unless they remove substantial complexity or address a proven reliability issue.
+
+Recommended source layout:
+
+```text
+src/
+  cli.ts
+  daemon-main.ts
+  daemon/
+    daemon.ts
+    window-registry.ts
+    event-queue.ts
+  commands/
+    open.ts
+    prompt.ts
+  ipc/
+    client.ts
+    server.ts
+    protocol.ts
+  platform/
+    paths.ts
+    url-policy.ts
+  runtime/
+    glimpse-adapter.ts
+  schemas/
+    command-results.ts
+    ipc.ts
+  utils/
+    duration.ts
+    json.ts
+```
+
+The layout may be collapsed during early implementation if a separate file would add ceremony without clarity.
+
+Testing uses Bun's built-in test runner (`bun test`). Prioritize unit tests for duration parsing, JSON/Valibot schemas, URL trust policy, CSP generation, event queue semantics, IPC protocol framing, daemon startup path/lock behavior, and command parser smoke tests. Native window tests can start as manual or minimal smoke tests.
+
+## v1 Commands
+
+- `glimpse prompt <html-source>`: one-shot foreground interaction.
+- `glimpse open <html-source>`: open persistent daemon-owned Window.
+- `glimpse open --url <url>`: open URL Source.
+- `glimpse set-html -w <ref> <html-source>`: replace Window HTML.
+- `glimpse navigate -w <ref> --url <url>`: navigate Window to URL Source.
+- `glimpse send -w <ref> --type <type> (--data <json>|--data-file <path|->|--text <text>)`: send structured Page Message.
+- `glimpse eval -w <ref> <js>`: execute raw JavaScript and return JSON-serializable result.
+- `glimpse wait -w <ref> [--type <type>] [--timeout <duration>]`: block until one matching event and consume it.
+- `glimpse read -w <ref> [--type <type>]`: non-blocking event consume.
+- `glimpse events -w <ref>` / `glimpse peek -w <ref>`: inspect queued unconsumed events without consuming.
+- `glimpse close -w <ref> [--force]`: close one Window.
+- `glimpse close --all [--force]`: close all Windows.
+- `glimpse list [--include-closed]`: list open Windows, optionally recent closed tombstones.
+
+No general v1 command mutates Window options after opening.
+
+## HTML and URL Sources
+
+HTML Sources:
+
+- positional file path
+- `-` for stdin
+- `--html <literal>`
+
+HTML is read once by default. `--watch` makes the daemon watch file-based HTML and fully reload Window HTML on changes. Watchers are daemon-owned and live only as long as their Window.
+
+URL Sources require explicit `--url`; positional URLs are not supported in v1.
+
+Existing Windows move to URL Sources via `navigate`, not `set-html`.
+
+## Persistent Windows and Daemon
+
+Persistent Windows are owned by an Ephemeral Daemon:
+
+- starts on first persistent `open`
+- exits after last Window closes
+- may remain alive for up to 30 seconds to serve final close events
+- macOS IPC uses local same-user Unix domain socket
+- daemon discovery uses predictable per-user socket path plus state files under `$TMPDIR/glimpse-cli-$UID/` (`daemon.sock`, `daemon.json`) and an atomic startup lock directory named `daemon.lock`
+- daemon startup uses detached child process launch followed by socket `ping` polling until ready or a 5 second startup timeout
+- concurrent CLI connections are allowed
+- mutations and event queue consumption are serialized per Window
+
+`prompt` is standalone foreground by default and does not require the daemon.
+
+## Window References
+
+Every persistent Window gets an opaque `windowId`.
+
+Users may optionally assign a unique active Window Name:
+
+```fish
+glimpse open ./status.html --name build
+```
+
+Commands address Windows with only:
+
+```fish
+-w, --window <ref>
+```
+
+`<ref>` may be a Window ID or Window Name.
+
+Window Names are case-sensitive, script-safe identifiers and must not use reserved Window ID prefixes. Closed Window names can be reused immediately; close-event tombstones remain addressable only by old Window ID.
+
+`open --name <name>` fails if the name is in use unless `--replace` is passed. Replacement closes the existing Window, discards its event queue, stops watchers, creates a fresh Window with a new ID, and reserves the name during the operation.
+
+## Command Results
+
+Commands default to JSON output.
+
+Success:
+
+```json
+{ "ok": true }
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "window_not_found",
+    "message": "Window build is not open."
+  }
+}
+```
+
+Prompt cancellation/window close is not an error. Explicit in-page cancellation uses a reserved Prompt Result:
+
+```json
+{ "ok": true, "result": { "type": "prompt.canceled" } }
+```
+
+Prompt Window closure without a page-submitted value uses a synthesized Prompt Result:
+
+```json
+{ "ok": true, "result": { "type": "window.closed" } }
+```
+
+Timeouts are technical failures.
+
+Exit codes:
+
+- `0`: success
+- `1`: runtime or command failure with JSON error
+- `2`: usage or validation error
+
+## Prompt Semantics
+
+`prompt` opens a temporary Window, waits for first page-to-CLI message, prints raw submitted value as `result`, closes, and exits. Explicit in-page cancel controls should submit `{ "type": "prompt.canceled" }`. Prompt Window closure without a page-submitted value returns `{ "type": "window.closed" }`. Prompt content should not submit raw `null`; in v1, raw `null` is treated as Window closure.
+
+`prompt --timeout <duration>` fails with `timeout` if no result arrives.
+
+Remote URL prompts require both `--allow-remote` and `--allow-bridge` because prompts need the page bridge.
+
+## Window Events
+
+Persistent Window page-to-CLI messages become queued Window Events.
+
+Event commands in v1 require `-w`.
+
+Event behavior:
+
+- `wait` consumes one matching event.
+- `read` consumes one matching event if present.
+- `events`/`peek` inspect currently queued unconsumed events only.
+- unfiltered `wait`/`read` return oldest queued event, including system events.
+- filtered `wait`/`read` consume only first matching event and preserve non-matching events.
+- `read` with no matching event returns `{ "ok": true, "event": null }`.
+- `wait` blocks indefinitely unless `--timeout` is provided.
+
+Queue size:
+
+- default 1000 events per Window
+- configurable up to 20000 events
+- overflow drops oldest droppable event and reports `glimpse.error`
+
+Untyped page payloads are wrapped as event type `json`.
+
+System prefixes are reserved; page attempts to use them produce `glimpse.error`.
+
+System events include:
+
+- `window.ready`
+- `window.closed`
+- `window.navigated`
+- `html.reloaded`
+- `glimpse.error`
+
+`window.closed` remains readable for up to 30 seconds after closure.
+
+## Page Messages and Eval
+
+`send` sends structured JSON Page Messages to a Window bridge.
+
+Rules:
+
+- explicit `--type` required
+- `--data` is JSON-only
+- `--text` sends string data
+- `--data-file <path|->` supports large/generated JSON
+- success means delivered to the webview bridge, not handled by app code
+- v1 has listener-style delivery only, no built-in request/response protocol
+
+`eval` executes raw JS. It is enabled by default for local CLI use because the command name is explicit. It returns JSON-serializable result values.
+
+Bridge-dependent commands fail clearly against Windows without bridge.
+
+## Window Options
+
+CLI stays close to the Glimpse JavaScript SDK.
+
+- JS SDK option names map to kebab-case CLI flags.
+- SDK options can also be supplied as JSON object using SDK camelCase keys.
+- explicit CLI flags override JSON options, including nested option flags.
+- options files are file-based only in v1; they do not read from stdin.
+
+Example:
+
+```fish
+glimpse open ./ui.html \
+  --click-through \
+  --follow-cursor \
+  --follow-mode spring \
+  --cursor-offset 20,-20 \
+  --options-json '{"width":400,"height":300}'
+```
+
+## URL Security Policy
+
+Trusted local URL Sources are allowed by default with bridge enabled.
+
+Trusted local URLs:
+
+- loopback hosts
+- `file:` URLs
+- `.localhost` hostnames only when they resolve to loopback addresses
+
+Trusted URL algorithm:
+
+1. Parse URL.
+2. If protocol is `file:`, trusted.
+3. If protocol is not `http:` or `https:`, untrusted.
+4. If hostname is `localhost`, trusted.
+5. If hostname is loopback IP (`127.0.0.0/8` or `::1`), trusted.
+6. If hostname ends with `.localhost`, resolve DNS once.
+7. `.localhost` is trusted only if every resolved address is loopback.
+8. Everything else is remote/untrusted.
+
+Trust is checked before loading/navigation. Redirects or in-window navigations to untrusted URLs are blocked unless remote loading is explicitly allowed.
+
+Remote URLs:
+
+- blocked by default
+- `--allow-remote` permits loading remote content in read-only/no-bridge mode
+- `--allow-bridge` additionally permits bridge injection
+- `--allow-bridge` alone does not permit remote loading
+
+Remote bridged Windows allow `send` and `eval` only after explicit remote loading and bridge allowance.
+
+Links opened externally are handled outside the Window.
+
+## HTML CSP Policy
+
+Local and inline HTML Sources receive a default Content Security Policy that blocks remote subresources unless relaxed.
+
+Default CSP intent:
+
+- allow local/inline micro-UI needs
+- allow loopback resources
+- allow literal `localhost`
+- allow broad `.localhost` resources for portless/local-dev workflows
+- block arbitrary remote subresources
+
+Initial v1 default CSP:
+
+```text
+default-src 'self' data: blob:;
+img-src 'self' data: blob: http://localhost:* https://localhost:* http://127.0.0.1:* https://127.0.0.1:* http://*.localhost:* https://*.localhost:*;
+style-src 'self' 'unsafe-inline' data:;
+script-src 'self' 'unsafe-inline' blob:;
+connect-src 'self' http://localhost:* https://localhost:* ws://localhost:* wss://localhost:* http://127.0.0.1:* https://127.0.0.1:* ws://127.0.0.1:* wss://127.0.0.1:* http://*.localhost:* https://*.localhost:* ws://*.localhost:* wss://*.localhost:*;
+font-src 'self' data:;
+media-src 'self' data: blob:;
+```
+
+The implementation may adjust this exact string if WKWebView behavior requires changes while preserving the stated policy intent.
+
+Escape hatches:
+
+- `--allow-remote-resources`
+- explicit `--csp <policy>`
+
+No `--no-csp` in v1.
+
+CSP is part of Window creation policy and persists across `set-html` and watch reloads.
+
+`navigate` uses URL Source policy, not HTML Source CSP.
+
+## Listing
+
+`list` succeeds even when daemon is not running:
+
+```json
+{
+  "ok": true,
+  "daemon": { "running": false },
+  "windows": []
+}
+```
+
+Open Window entries should include state, event queue size, source metadata, and bridge/security metadata.
+
+`--include-closed` includes recently closed entries with expiry time.
+
+## Closure
+
+`close -w <ref>` fails on missing/stale Window by default.
+
+Normal closure emits `window.closed` and keeps tombstone for up to 30 seconds.
+
+Forced closure discards event queues and tombstones, stops watchers, and lets daemon exit immediately when no Windows remain.
+
+`close --all` supports normal and forced closure.
+
+## Deferred Ideas
+
+Tracked as beans:
+
+- `glimpse-cli-pj3z`: Evaluate seamless HMR for watched Glimpse windows.
+- `glimpse-cli-zbfv`: Evaluate global event awaiting across windows.

package/docs/npm-staged-trusted-publishing.md

@@ -0,0 +1,44 @@
+# npm staged trusted publishing
+
+This package uses [`danielroe/uppt`](https://github.com/danielroe/uppt) for npm Trusted Publishing plus staged publishing.
+
+## One-time setup
+
+`glimpse-cli` must exist on npm before its Trusted Publisher can be configured. If it is not published yet, create the placeholder package:
+
+```bash
+npx --yes setup-npm-trusted-publish glimpse-cli
+```
+
+Then open:
+
+```text
+https://www.npmjs.com/package/glimpse-cli/access
+```
+
+Configure the Trusted Publisher:
+
+- Provider: GitHub Actions
+- Repository: `bjesuiter/glimpse-cli`
+- Workflow filename: `release.yml`
+- Environment name: `npm`
+- Allowed action: `npm stage publish`
+
+Also configure GitHub:
+
+1. Create a GitHub environment named `npm`.
+2. In repo Settings → Actions → General → Workflow permissions, enable “Allow GitHub Actions to create and approve pull requests”.
+
+Prefer stage-only npm access so CI can submit a release candidate, but a maintainer still approves the final publication with 2FA.
+
+## Release flow
+
+1. Use conventional commits on `main`.
+2. On push to `main`, `uppt/pr` opens or updates a draft `release/vX.Y.Z` PR.
+3. Merge the release PR.
+4. `uppt/release` creates the tag and GitHub Release, then dispatches `release.yml` on the tag.
+5. `uppt/pack` creates the tarball from a Bun-checked build artifact.
+6. `uppt/publish` runs `npm stage publish` with OIDC.
+7. Approve or reject the staged package on npmjs.com or with an interactive npm CLI session.
+
+No `NPM_TOKEN` secret is required. The publish job uses GitHub Actions OIDC via `permissions.id-token: write`.

package/examples/01_prompt.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Self-contained glimpse-cli example: one-shot prompt window.
+# Run from the repo root with: ./examples/01_prompt.sh
+
+GLIMPSE="${GLIMPSE:-bun src/cli.ts}"
+
+HTML=$(cat <<'HTML'
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Glimpse Prompt</title>
+  <style>
+    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: linear-gradient(135deg, #111827, #312e81); color: #f8fafc; }
+    form { width: min(420px, calc(100vw - 32px)); padding: 28px; border: 1px solid rgba(199, 210, 254, .35); border-radius: 24px; background: rgba(15, 23, 42, .82); box-shadow: 0 24px 80px rgba(0, 0, 0, .45); }
+    h1 { margin: 0 0 8px; font-size: 22px; }
+    p { margin: 0 0 18px; color: #cbd5e1; line-height: 1.45; }
+    label { display: block; margin-bottom: 8px; color: #c4b5fd; font-size: 13px; font-weight: 700; }
+    input { box-sizing: border-box; width: 100%; border: 1px solid rgba(199, 210, 254, .35); border-radius: 14px; padding: 13px 14px; color: #f8fafc; background: rgba(2, 6, 23, .65); font: inherit; outline: none; }
+    input:focus { border-color: #818cf8; box-shadow: 0 0 0 4px rgba(129, 140, 248, .18); }
+    .actions { display: flex; gap: 10px; margin-top: 16px; }
+    button { flex: 1; border: 0; border-radius: 14px; padding: 13px 14px; color: #f8fafc; background: #4f46e5; font-weight: 800; cursor: pointer; }
+    button.secondary { background: rgba(100, 116, 139, .55); }
+    button:hover { filter: brightness(1.12); }
+    small { display: block; margin-top: 14px; color: #94a3b8; }
+  </style>
+</head>
+<body>
+  <form id="prompt-form">
+    <h1>Quick prompt</h1>
+    <p>Submit a short value back to the shell. Cancel and window close return explicit result objects.</p>
+    <label for="answer">What should Glimpse say?</label>
+    <input id="answer" name="answer" value="Hello from Glimpse" autofocus />
+    <div class="actions">
+      <button type="button" class="secondary" id="cancel">Cancel</button>
+      <button type="submit">Submit</button>
+    </div>
+    <small>Try editing the text, then press Enter.</small>
+  </form>
+  <script>
+    const form = document.querySelector('#prompt-form');
+    const answer = document.querySelector('#answer');
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      window.glimpse?.send?.({ answer: answer.value, submittedAt: new Date().toISOString() });
+    });
+    document.querySelector('#cancel').addEventListener('click', () => window.glimpse?.send?.({ type: 'prompt.canceled' }));
+    answer.select();
+  </script>
+</body>
+</html>
+HTML
+)
+
+echo "Opening prompt window..."
+$GLIMPSE prompt --width 540 --height 390 --title "Glimpse Prompt" --html "$HTML"

package/examples/02_counter.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Self-contained glimpse-cli example: an interactive counter window.
+# Uses one discrete event per button click.
+# Run from the repo root with: ./examples/02_counter.sh
+
+GLIMPSE="${GLIMPSE:-bun src/cli.ts}"
+WINDOW_NAME="glimpse-counter-example"
+
+HTML=$(cat <<'HTML'
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Glimpse Counter</title>
+  <style>
+    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    *, *::before, *::after { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; overflow-x: hidden; background: radial-gradient(circle at top, #334155, #020617 65%); color: #f8fafc; }
+    main { width: min(360px, calc(100vw - 32px)); padding: 28px; border: 1px solid rgba(148, 163, 184, .35); border-radius: 24px; background: rgba(15, 23, 42, .78); box-shadow: 0 24px 80px rgba(0, 0, 0, .45); text-align: center; }
+    h1 { margin: 0 0 12px; font-size: 18px; font-weight: 650; color: #cbd5e1; }
+    output { display: block; margin: 18px 0 24px; font-size: 72px; font-weight: 800; line-height: 1; letter-spacing: -0.06em; }
+    .buttons { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; }
+    button { border: 0; border-radius: 14px; padding: 14px 12px; color: #f8fafc; background: #2563eb; font-size: 18px; font-weight: 750; cursor: pointer; }
+    button:hover { filter: brightness(1.12); }
+    button.secondary { background: rgba(100, 116, 139, .55); }
+    p { margin: 18px 0 0; color: #94a3b8; font-size: 13px; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Interactive Glimpse Counter</h1>
+    <output id="count">0</output>
+    <div class="buttons">
+      <button id="dec" class="secondary">−</button>
+      <button id="reset" class="secondary">0</button>
+      <button id="inc">+</button>
+    </div>
+    <p>Each click is sent back as one discrete CLI event.</p>
+  </main>
+  <script>
+    let count = 0;
+    const output = document.querySelector('#count');
+    function render() { output.textContent = String(count); }
+    let seq = 0;
+    function emit(action) {
+      seq += 1;
+      window.glimpse?.send?.({ type: 'counter.changed', action, count, seq });
+    }
+    document.querySelector('#inc').addEventListener('click', () => { count += 1; render(); emit('increment'); });
+    document.querySelector('#dec').addEventListener('click', () => { count -= 1; render(); emit('decrement'); });
+    document.querySelector('#reset').addEventListener('click', () => { count = 0; render(); emit('reset'); });
+    render();
+  </script>
+</body>
+</html>
+HTML
+)
+
+open_json=$($GLIMPSE open --name "$WINDOW_NAME" --replace --width 380 --height 430 --title "Glimpse Counter" --html "$HTML")
+echo "$open_json"
+WINDOW_REF=$(printf '%s' "$open_json" | sed -n 's/.*"windowId":"\([^"]*\)".*/\1/p')
+if [[ -z "$WINDOW_REF" ]]; then
+  echo "Failed to open counter window." >&2
+  exit 1
+fi
+
+echo "Opened window '$WINDOW_NAME' ($WINDOW_REF)."
+echo "Waiting for discrete counter events. Press Ctrl-C to stop listening; close the window when done."
+
+# Block until the next event instead of polling with repeated CLI invocations.
+# Waiting without --type lets the same loop handle both button clicks and the
+# window.closed system event.
+while true; do
+  event_json=$($GLIMPSE wait -w "$WINDOW_REF")
+
+  if [[ "$event_json" == *'"type":"window.closed"'* ]]; then
+    echo "$event_json"
+    echo "Window closed; stopping listener."
+    break
+  fi
+
+  if [[ "$event_json" == *'"type":"counter.changed"'* ]]; then
+    echo "$event_json"
+  fi
+done

package/examples/02b_counter_w_state.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Self-contained glimpse-cli example: an interactive counter window.
+# Demonstrates a state-snapshot pattern for consumers that prefer latest-state reconciliation.
+# Run from the repo root with: ./examples/02b_counter_w_state.sh
+
+GLIMPSE="${GLIMPSE:-bun src/cli.ts}"
+WINDOW_NAME="glimpse-counter-example"
+
+HTML=$(cat <<'HTML'
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Glimpse Counter</title>
+  <style>
+    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    *, *::before, *::after { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; overflow-x: hidden; background: radial-gradient(circle at top, #334155, #020617 65%); color: #f8fafc; }
+    main { width: min(360px, calc(100vw - 32px)); padding: 28px; border: 1px solid rgba(148, 163, 184, .35); border-radius: 24px; background: rgba(15, 23, 42, .78); box-shadow: 0 24px 80px rgba(0, 0, 0, .45); text-align: center; }
+    h1 { margin: 0 0 12px; font-size: 18px; font-weight: 650; color: #cbd5e1; }
+    output { display: block; margin: 18px 0 24px; font-size: 72px; font-weight: 800; line-height: 1; letter-spacing: -0.06em; }
+    .buttons { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; }
+    button { border: 0; border-radius: 14px; padding: 14px 12px; color: #f8fafc; background: #2563eb; font-size: 18px; font-weight: 750; cursor: pointer; }
+    button:hover { filter: brightness(1.12); }
+    button.secondary { background: rgba(100, 116, 139, .55); }
+    p { margin: 18px 0 0; color: #94a3b8; font-size: 13px; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Interactive Glimpse Counter</h1>
+    <output id="count">0</output>
+    <div class="buttons">
+      <button id="dec" class="secondary">−</button>
+      <button id="reset" class="secondary">0</button>
+      <button id="inc">+</button>
+    </div>
+    <p>Clicks are sent back, then latest state is repeated briefly.</p>
+  </main>
+  <script>
+    let count = 0;
+    const output = document.querySelector('#count');
+    function render() { output.textContent = String(count); }
+    let seq = 0;
+    let snapshotRetries = 0;
+    function emit(action) {
+      seq += 1;
+      snapshotRetries = 10;
+      window.glimpse?.send?.({ type: 'counter.changed', action, count, seq });
+    }
+    // Reliable state channel: clicks can be bursty and shell polling is coarse.
+    // Repeat each latest snapshot briefly, then stop so the CLI queue cannot
+    // grow forever while waiting for the window to close.
+    setInterval(() => {
+      if (snapshotRetries > 0) {
+        snapshotRetries -= 1;
+        window.glimpse?.send?.({ type: 'counter.snapshot', count, seq });
+      }
+    }, 100);
+    document.querySelector('#inc').addEventListener('click', () => { count += 1; render(); emit('increment'); });
+    document.querySelector('#dec').addEventListener('click', () => { count -= 1; render(); emit('decrement'); });
+    document.querySelector('#reset').addEventListener('click', () => { count = 0; render(); emit('reset'); });
+    render();
+  </script>
+</body>
+</html>
+HTML
+)
+
+open_json=$($GLIMPSE open --name "$WINDOW_NAME" --replace --width 380 --height 430 --title "Glimpse Counter" --html "$HTML")
+echo "$open_json"
+WINDOW_REF=$(printf '%s' "$open_json" | sed -n 's/.*"windowId":"\([^"]*\)".*/\1/p')
+if [[ -z "$WINDOW_REF" ]]; then
+  echo "Failed to open counter window." >&2
+  exit 1
+fi
+
+echo "Opened window '$WINDOW_NAME' ($WINDOW_REF)."
+echo "Waiting for counter state snapshots. Press Ctrl-C to stop listening; close the window when done."
+
+# Block until the next event instead of polling with repeated CLI invocations.
+# This variant shows latest-state reconciliation: the page emits counter.changed
+# per click, then repeats counter.snapshot briefly so consumers can observe the
+# newest state without processing every click as a durable command.
+last_seq=0
+while true; do
+  event_json=$($GLIMPSE wait -w "$WINDOW_REF")
+
+  if [[ "$event_json" == *'"type":"window.closed"'* ]]; then
+    echo "$event_json"
+    echo "Window closed; stopping listener."
+    break
+  fi
+
+  if [[ "$event_json" == *'"type":"counter.snapshot"'* ]]; then
+    seq=$(printf '%s' "$event_json" | sed -n 's/.*"seq":\([0-9][0-9]*\).*/\1/p')
+    if [[ -n "$seq" && "$seq" -gt "$last_seq" ]]; then
+      echo "$event_json"
+      last_seq="$seq"
+    fi
+  fi
+done