npm - glimpseui - Versions diffs - 0.1.0 - Mend

glimpseui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,352 @@
+# Glimpse
+Native macOS micro-UI for scripts and agents.
+Glimpse opens a native WKWebView window in under 50ms and speaks a bidirectional JSON Lines protocol over stdin/stdout. No Electron, no browser, no runtime dependencies — just a tiny Swift binary and a Node.js wrapper.
+## Requirements
+- macOS (any recent version)
+- Xcode Command Line Tools: `xcode-select --install`
+- Node.js 18+
+## Install
+```bash
+npm install glimpse
+```
+`npm install` automatically compiles the Swift binary via a `postinstall` hook (~2 seconds). See [Compile on Install](#compile-on-install) for details.
+**Manual build:**
+```bash
+npm run build
+# or directly:
+swiftc src/glimpse.swift -o src/glimpse
+```
+## Quick Start
+```js
+import { open } from 'glimpse';
+const win = open(`
+  <html>
+    <body style="font-family:sans-serif; padding:2rem;">
+      <h2>Hello from Glimpse</h2>
+      <button onclick="glimpse.send({ action: 'greet' })">Say hello</button>
+    </body>
+  </html>
+`, { width: 400, height: 300, title: 'My App' });
+win.on('message', (data) => {
+  console.log('Received:', data); // { action: 'greet' }
+  win.close();
+});
+win.on('closed', () => process.exit(0));
+```
+## Window Modes
+Glimpse supports several window style flags that can be combined freely:
+| Flag | Effect |
+|------|--------|
+| `frameless` | Removes the title bar — use your own HTML chrome |
+| `floating` | Always on top of other windows |
+| `transparent` | Clear window background — HTML body needs `background: transparent` |
+| `clickThrough` | Window ignores all mouse events |
+Common combinations:
+- **Floating HUD**: `floating: true` — status panels, agent indicators
+- **Custom dialog**: `frameless: true` — clean UI with no system chrome
+- **Overlay**: `frameless + transparent` — shaped widgets that float over content
+- **Companion widget**: `frameless + transparent + floating + clickThrough` — visual-only overlays that don't interfere with the desktop
+## Follow Cursor
+Attach a window to the cursor. Combined with `transparent + frameless + floating + clickThrough`, this creates visual companions that follow the mouse without interfering with normal usage.
+```js
+import { open } from './src/glimpse.mjs';
+const win = open(`
+  <body style="background: transparent; margin: 0;">
+    <svg width="60" height="60" style="filter: drop-shadow(0 0 8px rgba(0,255,200,0.6));">
+      <circle cx="30" cy="30" r="20" fill="none" stroke="cyan" stroke-width="2">
+        <animateTransform attributeName="transform" type="rotate"
+          from="0 30 30" to="360 30 30" dur="1s" repeatCount="indefinite"/>
+      </circle>
+    </svg>
+  </body>
+`, {
+  width: 60, height: 60,
+  transparent: true,
+  frameless: true,
+  followCursor: true,
+  clickThrough: true,
+  cursorOffset: { x: 20, y: -20 }
+});
+```
+The window tracks the cursor in real-time across all screens. `followCursor` implies `floating` — the window stays on top automatically.
+You can also toggle tracking dynamically after the window is open:
+```js
+win.followCursor(false); // stop tracking
+win.followCursor(true);  // resume tracking
+```
+**Use cases:** animated SVG companions, agent "thinking" indicators, floating tooltips, custom cursor replacements.
+## API Reference
+### `open(html, options?)`
+Opens a native window and returns a `GlimpseWindow`. The HTML is displayed once the WebView signals ready.
+```js
+import { open } from 'glimpse';
+const win = open('<html>...</html>', {
+  width:  800,    // default: 800
+  height: 600,    // default: 600
+  title:  'App',  // default: "Glimpse"
+});
+```
+**All options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `width` | number | `800` | Window width in pixels |
+| `height` | number | `600` | Window height in pixels |
+| `title` | string | `"Glimpse"` | Title bar text (ignored when frameless) |
+| `x` | number | — | Horizontal screen position (omit to center) |
+| `y` | number | — | Vertical screen position (omit to center) |
+| `frameless` | boolean | `false` | Remove the title bar |
+| `floating` | boolean | `false` | Always on top of other windows |
+| `transparent` | boolean | `false` | Transparent window background |
+| `clickThrough` | boolean | `false` | Window ignores all mouse events |
+| `followCursor` | boolean | `false` | Track cursor position in real-time |
+| `cursorOffset` | `{ x?, y? }` | `{ x: 20, y: -20 }` | Pixel offset from cursor when `followCursor` is on |
+| `autoClose` | boolean | `false` | Close the window automatically after the first `message` event |
+### `prompt(html, options?)`
+One-shot helper — opens a window, waits for the first message, then closes it automatically. Returns a `Promise<data | null>` where `data` is the first message payload and `null` means the user closed the window without sending anything.
+```js
+import { prompt } from 'glimpse';
+const answer = await prompt(`
+  <h2>Delete this file?</h2>
+  <button onclick="window.glimpse.send({ok: true})">Yes</button>
+  <button onclick="window.glimpse.send({ok: false})">No</button>
+`, { width: 300, height: 150, title: 'Confirm' });
+if (answer?.ok) console.log('Deleted!');
+```
+Accepts the same `options` as `open()`. Optional `options.timeout` (ms) rejects the promise if no message arrives in time.
+### GlimpseWindow
+`GlimpseWindow` extends `EventEmitter`.
+#### Events
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `ready` | — | WebView is loaded and ready to receive commands |
+| `message` | `data: object` | Message sent from the page via `window.glimpse.send(data)` |
+| `closed` | — | Window was closed (by user or via `.close()`) |
+| `error` | `Error` | Process error or malformed protocol line |
+```js
+win.on('ready',   ()    => console.log('window ready'));
+win.on('message', (msg) => console.log('from page:', msg));
+win.on('closed',  ()    => process.exit(0));
+win.on('error',   (err) => console.error(err));
+```
+#### Methods
+**`win.send(js)`** — Evaluate JavaScript in the WebView.
+```js
+win.send(`document.body.style.background = 'coral'`);
+win.send(`document.getElementById('status').textContent = 'Done'`);
+```
+**`win.setHTML(html)`** — Replace the entire page content.
+```js
+win.setHTML('<html><body><h1>Step 2</h1></body></html>');
+```
+**`win.followCursor(enabled)`** — Start or stop cursor tracking at runtime.
+```js
+win.followCursor(true);   // attach to cursor
+win.followCursor(false);  // detach
+```
+**`win.loadFile(path)`** — Load a local HTML file into the WebView by absolute path.
+```js
+win.loadFile('/path/to/page.html');
+```
+**`win.close()`** — Close the window programmatically.
+```js
+win.close();
+```
+### JavaScript Bridge (in-page)
+Every page loaded by Glimpse gets a `window.glimpse` object injected at document start:
+```js
+// Send any JSON-serializable value to Node.js → triggers 'message' event
+window.glimpse.send({ action: 'submit', value: 42 });
+// Close the window from inside the page
+window.glimpse.close();
+```
+## Protocol
+Glimpse uses a newline-delimited JSON (JSON Lines) protocol. Each line is a complete JSON object. This makes it easy to drive the binary from any language.
+### Stdin → Glimpse (commands)
+**Set HTML** — Replace page content. HTML must be base64-encoded.
+```json
+{"type":"html","html":"<base64-encoded HTML>"}
+```
+**Eval JavaScript** — Run JS in the WebView.
+```json
+{"type":"eval","js":"document.title = 'Updated'"}
+```
+**Follow Cursor** — Toggle cursor tracking at runtime.
+```json
+{"type":"follow-cursor","enabled":true}
+{"type":"follow-cursor","enabled":false}
+```
+**Load File** — Load a local HTML file by absolute path.
+```json
+{"type":"file","path":"/path/to/page.html"}
+```
+**Close** — Close the window and exit.
+```json
+{"type":"close"}
+```
+### Stdout → Host (events)
+**Ready** — WebView finished loading initial blank page. Send HTML after this.
+```json
+{"type":"ready"}
+```
+**Message** — Data sent from the page via `window.glimpse.send(...)`.
+```json
+{"type":"message","data":{"action":"submit","value":42}}
+```
+**Closed** — Window closed (by user or via close command).
+```json
+{"type":"closed"}
+```
+Diagnostic logs are written to **stderr** (prefixed `[glimpse]`) and do not affect the protocol.
+## CLI Usage
+Drive the binary directly from any language — shell, Python, Ruby, etc.
+```bash
+# Basic usage
+echo '{"type":"html","html":"PGh0bWw+PGJvZHk+SGVsbG8hPC9ib2R5PjwvaHRtbD4="}' \
+  | ./src/glimpse --width 400 --height 300 --title "Hello"
+```
+Available flags:
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--width N` | `800` | Window width in pixels |
+| `--height N` | `600` | Window height in pixels |
+| `--title STR` | `"Glimpse"` | Window title bar text |
+| `--x N` | — | Horizontal screen position (omit to center) |
+| `--y N` | — | Vertical screen position (omit to center) |
+| `--frameless` | off | Remove the title bar |
+| `--floating` | off | Always on top of other windows |
+| `--transparent` | off | Transparent window background |
+| `--click-through` | off | Window ignores all mouse events |
+| `--follow-cursor` | off | Track cursor position in real-time |
+| `--cursor-offset-x N` | `20` | Horizontal offset from cursor |
+| `--cursor-offset-y N` | `-20` | Vertical offset from cursor |
+| `--auto-close` | off | Exit after receiving the first message from the page |
+**Shell example — encode HTML and pipe it in:**
+```bash
+HTML=$(echo '<html><body><h1>Hi</h1></body></html>' | base64)
+{
+  echo "{\"type\":\"html\",\"html\":\"$HTML\"}"
+  cat  # keep stdin open so the window stays up
+} | ./src/glimpse --width 600 --height 400
+```
+**Python example:**
+```python
+import subprocess, base64, json
+html = b"<html><body><h1>Hello from Python</h1></body></html>"
+proc = subprocess.Popen(
+    ["./src/glimpse", "--width", "500", "--height", "400"],
+    stdin=subprocess.PIPE, stdout=subprocess.PIPE
+)
+cmd = json.dumps({"type": "html", "html": base64.b64encode(html).decode()})
+proc.stdin.write((cmd + "\n").encode())
+proc.stdin.flush()
+for line in proc.stdout:
+    msg = json.loads(line)
+    if msg["type"] == "ready":
+        print("Window is ready")
+    elif msg["type"] == "message":
+        print("From page:", msg["data"])
+    elif msg["type"] == "closed":
+        break
+```
+## Compile on Install
+Every Mac ships with `swiftc` once Xcode Command Line Tools are installed — no Xcode IDE required. Glimpse takes advantage of this: running `npm install` triggers a `postinstall` script that compiles `src/glimpse.swift` into a native binary in about 2 seconds.
+```
+> glimpse@0.1.0 postinstall
+> npm run build
+swiftc src/glimpse.swift -o src/glimpse  ✓
+```
+**If compilation fails**, the most common cause is missing Xcode CLT:
+```bash
+xcode-select --install
+```
+To recompile manually at any time:
+```bash
+npm run build
+```
+## License
+MIT

package/bin/glimpse.mjs ADDED Viewed

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { open } from '../src/glimpse.mjs';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+const args = process.argv.slice(2);
+// Parse flags and collect positional args
+const flags = {};
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--help' || arg === '-h') { flags.help = true; }
+  else if (arg === '--demo') { flags.demo = true; }
+  else if (arg === '--frameless') { flags.frameless = true; }
+  else if (arg === '--floating') { flags.floating = true; }
+  else if (arg === '--transparent') { flags.transparent = true; }
+  else if (arg === '--click-through') { flags.clickThrough = true; }
+  else if (arg === '--follow-cursor') { flags.followCursor = true; }
+  else if (arg === '--auto-close') { flags.autoClose = true; }
+  else if (arg === '--width' && args[i + 1]) { flags.width = parseInt(args[++i]); }
+  else if (arg === '--height' && args[i + 1]) { flags.height = parseInt(args[++i]); }
+  else if (arg === '--title' && args[i + 1]) { flags.title = args[++i]; }
+  else if (arg === '--x' && args[i + 1]) { flags.x = parseInt(args[++i]); }
+  else if (arg === '--y' && args[i + 1]) { flags.y = parseInt(args[++i]); }
+  else if (arg === '--cursor-offset-x' && args[i + 1]) { flags.cursorOffset = { ...flags.cursorOffset, x: parseInt(args[++i]) }; }
+  else if (arg === '--cursor-offset-y' && args[i + 1]) { flags.cursorOffset = { ...flags.cursorOffset, y: parseInt(args[++i]) }; }
+  else if (!arg.startsWith('-')) { positional.push(arg); }
+  else { console.error(`Unknown flag: ${arg}`); process.exit(1); }
+}
+if (flags.help) {
+  console.log(`
+glimpseui — Native macOS micro-UI for scripts and agents
+Usage:
+  glimpseui [options] [file.html]    Open an HTML file
+  echo '<h1>Hi</h1>' | glimpseui    Pipe HTML from stdin
+  glimpseui --demo                   Show a demo window
+Options:
+  --width <n>          Window width (default: 800)
+  --height <n>         Window height (default: 600)
+  --title <text>       Window title (default: "Glimpse")
+  --frameless          No title bar
+  --floating           Always on top
+  --transparent        Transparent background
+  --click-through      Mouse passes through
+  --follow-cursor      Window follows cursor
+  --cursor-offset-x <n>  Cursor X offset (default: 20)
+  --cursor-offset-y <n>  Cursor Y offset (default: -20)
+  --auto-close         Close after first window.glimpse.send()
+  --x <n>              Window X position
+  --y <n>              Window Y position
+  --demo               Show a demo window
+  --help, -h           Show this help
+`);
+  process.exit(0);
+}
+const DEMO_HTML = `
+<body style="margin: 0; font-family: system-ui; background: transparent !important;">
+  <style>
+    .container {
+      padding: 32px; height: 100vh; box-sizing: border-box;
+      background: rgba(20, 20, 35, 0.9); backdrop-filter: blur(30px); -webkit-backdrop-filter: blur(30px);
+      border-radius: 16px; border: 1px solid rgba(255,255,255,0.1);
+      display: flex; flex-direction: column; gap: 16px;
+    }
+    h1 { margin: 0; font-size: 22px; color: white; }
+    h1 span { background: linear-gradient(135deg, #e94560, #4299e1); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+    p { margin: 0; color: #888; font-size: 14px; line-height: 1.5; }
+    code { background: rgba(255,255,255,0.1); padding: 2px 6px; border-radius: 4px; font-size: 13px; color: #ccc; }
+    .buttons { display: flex; gap: 10px; margin-top: auto; }
+    button {
+      flex: 1; padding: 12px; font-size: 14px; font-weight: 600; border: none;
+      border-radius: 10px; cursor: pointer; transition: all 0.15s;
+    }
+    button:hover { transform: scale(1.03); }
+    button:active { transform: scale(0.97); }
+    .primary { background: linear-gradient(135deg, #e94560, #c23152); color: white; }
+    .primary:hover { box-shadow: 0 0 20px rgba(233,69,96,0.4); }
+    .secondary { background: rgba(255,255,255,0.1); color: #ccc; }
+    .secondary:hover { background: rgba(255,255,255,0.15); }
+    .features { display: flex; flex-wrap: wrap; gap: 6px; }
+    .tag { background: rgba(66,153,225,0.15); color: #4299e1; padding: 4px 10px; border-radius: 6px; font-size: 12px; }
+  </style>
+  <div class="container">
+    <h1>👁️ <span>Glimpse</span></h1>
+    <p>Native macOS micro-UI. Sub-50ms windows with WKWebView.<br>
+       Bidirectional communication via <code>window.glimpse.send()</code></p>
+    <div class="features">
+      <span class="tag">Frameless</span>
+      <span class="tag">Transparent</span>
+      <span class="tag">Floating</span>
+      <span class="tag">Follow Cursor</span>
+      <span class="tag">Keyboard</span>
+      <span class="tag">Auto-close</span>
+    </div>
+    <div class="buttons">
+      <button class="secondary" onclick="window.glimpse.send({action:'docs'})">📖 Docs</button>
+      <button class="primary" onclick="window.glimpse.send({action:'cool'})">🚀 Cool!</button>
+    </div>
+  </div>
+  <script>
+    document.addEventListener('keydown', e => {
+      if (e.key === 'Escape' || e.key === 'Enter') window.glimpse.send({action:'close'});
+    });
+  </script>
+</body>`;
+async function main() {
+  let html;
+  if (flags.demo) {
+    html = DEMO_HTML;
+    flags.frameless = flags.frameless ?? true;
+    flags.transparent = flags.transparent ?? true;
+    flags.width = flags.width ?? 380;
+    flags.height = flags.height ?? 320;
+  } else if (positional.length > 0) {
+    // Load from file
+    const file = resolve(positional[0]);
+    if (!existsSync(file)) {
+      console.error(`File not found: ${file}`);
+      process.exit(1);
+    }
+    html = readFileSync(file, 'utf-8');
+  } else if (!process.stdin.isTTY) {
+    // Read from stdin
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    html = Buffer.concat(chunks).toString('utf-8');
+  } else {
+    console.error('Usage: glimpseui [options] [file.html]');
+    console.error('       echo "<h1>Hi</h1>" | glimpseui');
+    console.error('       glimpseui --demo');
+    console.error('');
+    console.error('Run glimpseui --help for all options.');
+    process.exit(1);
+  }
+  const win = open(html, flags);
+  win.on('message', data => {
+    console.log(JSON.stringify(data));
+  });
+  win.on('closed', () => {
+    process.exit(0);
+  });
+}
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json ADDED Viewed

@@ -0,0 +1,52 @@
+{
+  "name": "glimpseui",
+  "version": "0.1.0",
+  "description": "Native macOS micro-UI for scripts and agents — sub-50ms WKWebView windows with bidirectional JSON communication",
+  "type": "module",
+  "main": "src/glimpse.mjs",
+  "exports": {
+    ".": "./src/glimpse.mjs"
+  },
+  "bin": {
+    "glimpseui": "bin/glimpse.mjs"
+  },
+  "scripts": {
+    "build": "swiftc -O src/glimpse.swift -o src/glimpse",
+    "postinstall": "npm run build",
+    "test": "node test.mjs",
+    "publish:check": "./scripts/publish.sh --dry-run",
+    "publish:npm": "./scripts/publish.sh"
+  },
+  "files": [
+    "src/glimpse.swift",
+    "src/glimpse.mjs",
+    "bin/glimpse.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "keywords": [
+    "macos",
+    "webview",
+    "native",
+    "ui",
+    "webkit",
+    "wkwebview",
+    "swift",
+    "gui",
+    "agent",
+    "dialog",
+    "prompt",
+    "overlay"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hjanuschka/glimpse"
+  },
+  "author": "hjanuschka",
+  "license": "MIT"
+}

package/src/glimpse.mjs ADDED Viewed

@@ -0,0 +1,159 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BINARY = join(__dirname, 'glimpse');
+class GlimpseWindow extends EventEmitter {
+  #proc;
+  #closed = false;
+  #pendingHTML = null;
+  constructor(proc, initialHTML) {
+    super();
+    this.#proc = proc;
+    this.#pendingHTML = initialHTML;
+    proc.stdin.on('error', () => {}); // Swallow EPIPE if Swift exits first
+    const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
+    rl.on('line', (line) => {
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        this.emit('error', new Error(`Malformed protocol line: ${line}`));
+        return;
+      }
+      switch (msg.type) {
+        case 'ready':
+          if (this.#pendingHTML) {
+            // First ready = blank page loaded. Send the queued HTML.
+            this.setHTML(this.#pendingHTML);
+            this.#pendingHTML = null;
+          } else {
+            // Subsequent ready = user HTML loaded. Notify caller.
+            this.emit('ready');
+          }
+          break;
+        case 'message':
+          this.emit('message', msg.data);
+          break;
+        case 'closed':
+          if (!this.#closed) {
+            this.#closed = true;
+            this.emit('closed');
+          }
+          break;
+        default:
+          break;
+      }
+    });
+    proc.on('error', (err) => this.emit('error', err));
+    proc.on('exit', () => {
+      if (!this.#closed) {
+        this.#closed = true;
+        this.emit('closed');
+      }
+    });
+  }
+  #write(obj) {
+    if (this.#closed) return;
+    this.#proc.stdin.write(JSON.stringify(obj) + '\n');
+  }
+  send(js) {
+    this.#write({ type: 'eval', js });
+  }
+  setHTML(html) {
+    this.#write({ type: 'html', html: Buffer.from(html).toString('base64') });
+  }
+  close() {
+    this.#write({ type: 'close' });
+  }
+  loadFile(path) {
+    this.#write({ type: 'file', path });
+  }
+  followCursor(enabled) {
+    this.#write({ type: 'follow-cursor', enabled });
+  }
+}
+export function open(html, options = {}) {
+  if (!existsSync(BINARY)) {
+    throw new Error(
+      "Glimpse binary not found. Run 'npm run build' or 'swiftc src/glimpse.swift -o src/glimpse'"
+    );
+  }
+  const args = [];
+  if (options.width != null)  args.push('--width',  String(options.width));
+  if (options.height != null) args.push('--height', String(options.height));
+  if (options.title != null)  args.push('--title',  options.title);
+  if (options.frameless)    args.push('--frameless');
+  if (options.floating)     args.push('--floating');
+  if (options.transparent)  args.push('--transparent');
+  if (options.clickThrough) args.push('--click-through');
+  if (options.followCursor) args.push('--follow-cursor');
+  if (options.autoClose)   args.push('--auto-close');
+  if (options.x != null) args.push('--x', String(options.x));
+  if (options.y != null) args.push('--y', String(options.y));
+  if (options.cursorOffset?.x != null) args.push('--cursor-offset-x', String(options.cursorOffset.x));
+  if (options.cursorOffset?.y != null) args.push('--cursor-offset-y', String(options.cursorOffset.y));
+  const proc = spawn(BINARY, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+  return new GlimpseWindow(proc, html);
+}
+export function prompt(html, options = {}) {
+  return new Promise((resolve, reject) => {
+    const win = open(html, { ...options, autoClose: true });
+    let resolved = false;
+    const timer = options.timeout
+      ? setTimeout(() => {
+          if (!resolved) { resolved = true; win.close(); reject(new Error('Prompt timed out')); }
+        }, options.timeout)
+      : null;
+    win.once('message', (data) => {
+      if (!resolved) {
+        resolved = true;
+        if (timer) clearTimeout(timer);
+        resolve(data);
+      }
+    });
+    win.once('closed', () => {
+      if (timer) clearTimeout(timer);
+      if (!resolved) {
+        resolved = true;
+        resolve(null); // User closed window without sending a message
+      }
+    });
+    win.once('error', (err) => {
+      if (timer) clearTimeout(timer);
+      if (!resolved) {
+        resolved = true;
+        reject(err);
+      }
+    });
+  });
+}

package/src/glimpse.swift ADDED Viewed

@@ -0,0 +1,355 @@
+import Cocoa
+import WebKit
+import Foundation
+// MARK: - Stdout Helper
+func writeToStdout(_ dict: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: dict),
+          let line = String(data: data, encoding: .utf8) else { return }
+    let output = line + "\n"
+    FileHandle.standardOutput.write(output.data(using: .utf8)!)
+    fflush(stdout)
+}
+func log(_ message: String) {
+    fputs("[glimpse] \(message)\n", stderr)
+}
+// MARK: - CLI Config
+struct Config {
+    var width: Int = 800
+    var height: Int = 600
+    var title: String = "Glimpse"
+    var frameless: Bool = false
+    var floating: Bool = false
+    var transparent: Bool = false
+    var x: Int? = nil
+    var y: Int? = nil
+    var followCursor: Bool = false
+    var cursorOffsetX: Int = 20
+    var cursorOffsetY: Int = -20
+    var clickThrough: Bool = false
+    var autoClose: Bool = false
+}
+func parseArgs() -> Config {
+    var config = Config()
+    let args = CommandLine.arguments
+    var i = 1
+    while i < args.count {
+        switch args[i] {
+        case "--width":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.width = v }
+        case "--height":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.height = v }
+        case "--title":
+            i += 1
+            if i < args.count { config.title = args[i] }
+        case "--frameless":
+            config.frameless = true
+        case "--floating":
+            config.floating = true
+        case "--transparent":
+            config.transparent = true
+        case "--x":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.x = v }
+        case "--y":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.y = v }
+        case "--follow-cursor":
+            config.followCursor = true
+        case "--cursor-offset-x":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.cursorOffsetX = v }
+        case "--cursor-offset-y":
+            i += 1
+            if i < args.count, let v = Int(args[i]) { config.cursorOffsetY = v }
+        case "--click-through":
+            config.clickThrough = true
+        case "--auto-close":
+            config.autoClose = true
+        default:
+            break
+        }
+        i += 1
+    }
+    return config
+}
+// MARK: - Window Subclass (keyboard support for frameless windows)
+class GlimpsePanel: NSWindow {
+    override var canBecomeKey: Bool { true }
+    override var canBecomeMain: Bool { true }
+}
+// MARK: - AppDelegate
+@MainActor
+class AppDelegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKScriptMessageHandler, NSWindowDelegate {
+    var window: NSWindow!
+    var webView: WKWebView!
+    let config: Config
+    // Mouse monitor references for follow-cursor mode
+    var globalMouseMonitor: Any?
+    var localMouseMonitor: Any?
+    nonisolated init(config: Config) {
+        self.config = config
+    }
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        setupWindow()
+        setupWebView()
+        if config.followCursor {
+            startFollowingCursor()
+        }
+        startStdinReader()
+    }
+    // MARK: - Setup
+    private func setupWindow() {
+        let rect = NSRect(x: 0, y: 0, width: config.width, height: config.height)
+        let styleMask: NSWindow.StyleMask = config.frameless
+            ? [.borderless]
+            : [.titled, .closable, .miniaturizable, .resizable]
+        window = GlimpsePanel(
+            contentRect: rect,
+            styleMask: styleMask,
+            backing: .buffered,
+            defer: false
+        )
+        window.title = config.title
+        if config.frameless {
+            window.isMovableByWindowBackground = true
+        }
+        if config.floating || config.followCursor {
+            window.level = .floating
+        }
+        if config.clickThrough {
+            window.ignoresMouseEvents = true
+        }
+        if config.transparent {
+            window.isOpaque = false
+            window.backgroundColor = .clear
+        }
+        if config.followCursor {
+            let mouse = NSEvent.mouseLocation
+            let x = mouse.x + CGFloat(config.cursorOffsetX)
+            let y = mouse.y + CGFloat(config.cursorOffsetY)
+            window.setFrameOrigin(NSPoint(x: x, y: y))
+        } else if let x = config.x, let y = config.y {
+            window.setFrameOrigin(NSPoint(x: x, y: y))
+        } else {
+            window.center()
+        }
+        window.delegate = self
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+    private func setupWebView() {
+        let ucc = WKUserContentController()
+        let bridgeJS = """
+        window.glimpse = {
+            send: function(data) {
+                window.webkit.messageHandlers.glimpse.postMessage(JSON.stringify(data));
+            },
+            close: function() {
+                window.webkit.messageHandlers.glimpse.postMessage(JSON.stringify({__glimpse_close: true}));
+            }
+        };
+        """
+        let script = WKUserScript(source: bridgeJS, injectionTime: .atDocumentStart, forMainFrameOnly: true)
+        ucc.addUserScript(script)
+        ucc.add(self, name: "glimpse")
+        let wkConfig = WKWebViewConfiguration()
+        wkConfig.userContentController = ucc
+        webView = WKWebView(frame: window.contentView!.bounds, configuration: wkConfig)
+        webView.autoresizingMask = [.width, .height]
+        webView.navigationDelegate = self
+        if config.transparent {
+            webView.underPageBackgroundColor = .clear
+            webView.setValue(false, forKey: "drawsBackground")
+        }
+        window.contentView?.addSubview(webView)
+        // Load blank page so didFinish fires and we emit "ready"
+        webView.loadHTMLString("<html><body></body></html>", baseURL: nil)
+    }
+    // MARK: - Follow Cursor
+    func startFollowingCursor() {
+        guard globalMouseMonitor == nil else { return }
+        window.level = .floating
+        let moveHandler: (NSEvent) -> Void = { [weak self] _ in
+            guard let self else { return }
+            let mouse = NSEvent.mouseLocation
+            let x = mouse.x + CGFloat(self.config.cursorOffsetX)
+            let y = mouse.y + CGFloat(self.config.cursorOffsetY)
+            self.window.setFrameOrigin(NSPoint(x: x, y: y))
+        }
+        globalMouseMonitor = NSEvent.addGlobalMonitorForEvents(
+            matching: [.mouseMoved, .leftMouseDragged, .rightMouseDragged],
+            handler: moveHandler
+        )
+        localMouseMonitor = NSEvent.addLocalMonitorForEvents(matching: [.mouseMoved, .leftMouseDragged, .rightMouseDragged]) { [weak self] event in
+            guard let self else { return event }
+            let mouse = NSEvent.mouseLocation
+            let x = mouse.x + CGFloat(self.config.cursorOffsetX)
+            let y = mouse.y + CGFloat(self.config.cursorOffsetY)
+            self.window.setFrameOrigin(NSPoint(x: x, y: y))
+            return event
+        }
+    }
+    func stopFollowingCursor() {
+        if let monitor = globalMouseMonitor {
+            NSEvent.removeMonitor(monitor)
+            globalMouseMonitor = nil
+        }
+        if let monitor = localMouseMonitor {
+            NSEvent.removeMonitor(monitor)
+            localMouseMonitor = nil
+        }
+    }
+    // MARK: - Stdin Reader
+    private func startStdinReader() {
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            while let line = readLine() {
+                let trimmed = line.trimmingCharacters(in: .whitespaces)
+                guard !trimmed.isEmpty else { continue }
+                guard let data = trimmed.data(using: .utf8),
+                      let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                      let type = json["type"] as? String
+                else {
+                    log("Skipping invalid JSON: \(trimmed)")
+                    continue
+                }
+                DispatchQueue.main.async {
+                    MainActor.assumeIsolated {
+                        self?.handleCommand(type: type, json: json)
+                    }
+                }
+            }
+            // stdin EOF — close window
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated {
+                    self?.closeAndExit()
+                }
+            }
+        }
+    }
+    // MARK: - Command Dispatch
+    func handleCommand(type: String, json: [String: Any]) {
+        switch type {
+        case "html":
+            guard let base64 = json["html"] as? String,
+                  let htmlData = Data(base64Encoded: base64),
+                  let html = String(data: htmlData, encoding: .utf8)
+            else {
+                log("html command: missing or invalid base64 payload")
+                return
+            }
+            webView.loadHTMLString(html, baseURL: nil)
+        case "eval":
+            guard let js = json["js"] as? String else {
+                log("eval command: missing js field")
+                return
+            }
+            webView.evaluateJavaScript(js, completionHandler: nil)
+        case "follow-cursor":
+            let enabled = json["enabled"] as? Bool ?? true
+            if enabled {
+                startFollowingCursor()
+            } else {
+                stopFollowingCursor()
+            }
+        case "file":
+            guard let path = json["path"] as? String else {
+                log("file command: missing path field")
+                return
+            }
+            let fileURL = URL(fileURLWithPath: path)
+            guard FileManager.default.fileExists(atPath: path) else {
+                log("file command: file not found: \(path)")
+                return
+            }
+            webView.loadFileURL(fileURL, allowingReadAccessTo: fileURL.deletingLastPathComponent())
+        case "close":
+            closeAndExit()
+        default:
+            log("Unknown command type: \(type)")
+        }
+    }
+    func closeAndExit() {
+        writeToStdout(["type": "closed"])
+        exit(0)
+    }
+    // MARK: - WKNavigationDelegate
+    nonisolated func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        MainActor.assumeIsolated {
+            window.makeFirstResponder(webView)
+            writeToStdout(["type": "ready"])
+        }
+    }
+    // MARK: - WKScriptMessageHandler
+    nonisolated func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        MainActor.assumeIsolated {
+            guard let body = message.body as? String,
+                  let data = body.data(using: .utf8),
+                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+            else {
+                log("Received invalid message from webview")
+                return
+            }
+            if json["__glimpse_close"] as? Bool == true {
+                closeAndExit()
+                return
+            }
+            writeToStdout(["type": "message", "data": json])
+            if config.autoClose {
+                closeAndExit()
+            }
+        }
+    }
+    // MARK: - NSWindowDelegate
+    func windowWillClose(_ notification: Notification) {
+        writeToStdout(["type": "closed"])
+        exit(0)
+    }
+}
+// MARK: - Entry Point
+let config = parseArgs()
+let app = NSApplication.shared
+let delegate = AppDelegate(config: config)
+app.delegate = delegate
+app.setActivationPolicy(.regular)
+app.run()