snapshot-trace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snapshot-trace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# snapshot-trace
+
+Runtime diagnostic recorder for any web app, designed for AI-assisted debugging.
+Any code calls `emit(...)`; a ●REC button in your UI buffers the events; ■STOP
+writes them as JSON to `/tmp/snapshot-trace.json` — a fixed path your coding
+agent reads directly. No console-log copy-paste.
+
+Framework-agnostic: one zero-dependency browser module + one standalone Node
+listener. Works on Vite, Next, webpack, CRA, or a static page.
+
+## Install
+
+```bash
+npm i -D snapshot-trace
+```
+
+## Setup (the one manual step)
+
+Run the listener alongside your dev server:
+
+```jsonc
+// package.json
+"scripts": { "snapshot:serve": "snapshot-trace serve" }
+```
+
+```bash
+npm run snapshot:serve   # second terminal
+```
+
+Then add a ●REC button (Vue/React/vanilla snippets in `templates/`, or ask your
+AI — `npx snapshot-trace skill`). The recorder disables itself outside dev.
+
+## Use
+
+```ts
+import { emit } from 'snapshot-trace'
+emit('checkout:submit', { cartId, total })
+```
+
+Click ●REC → reproduce → ■STOP. The snapshot lands at `/tmp/snapshot-trace.json`.
+
+## AI skill
+
+```bash
+npx snapshot-trace skill            # print the skill
+npx snapshot-trace skill --install  # install into .claude/skills/
+```
+
+## Config
+
+| Flag | Env | Default |
+|---|---|---|
+| `--port` | `SNAPSHOT_TRACE_PORT` | `7878` |
+| `--out` | `SNAPSHOT_TRACE_OUT` | `/tmp/snapshot-trace.json` |
+
+## License
+
+MIT

package/dist/cli.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// src/cli.mjs
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join } from 'node:path'
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs'
+import { startFromArgv } from './server.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// In dist/, SKILL.md sits at ../skill/SKILL.md relative to the bin; in src/ too.
+function skillPath() {
+  return join(HERE, '..', 'skill', 'SKILL.md')
+}
+
+export async function run(argv) {
+  const [cmd, ...rest] = argv
+  if (cmd === 'serve') {
+    startFromArgv(rest)
+    return 0
+  }
+  if (cmd === 'skill') {
+    const text = readFileSync(skillPath(), 'utf8')
+    if (rest.includes('--install')) {
+      const dest = join(process.cwd(), '.claude', 'skills', 'snapshot-trace', 'SKILL.md')
+      mkdirSync(dirname(dest), { recursive: true })
+      writeFileSync(dest, text, 'utf8')
+      process.stdout.write(`installed skill to ${dest}\n`)
+    } else {
+      process.stdout.write(text)
+    }
+    return 0
+  }
+  process.stderr.write(
+    'usage: snapshot-trace <serve|skill> [options]\n' +
+    '  serve [--port N] [--out PATH]\n' +
+    '  skill [--install]\n',
+  )
+  return 1
+}
+
+// Only auto-run when invoked directly (incl. through the npm bin symlink),
+// not when imported by tests. Resolve argv[1] through realpath so the
+// .bin symlink (and macOS /tmp→/private/tmp) collapses before comparing.
+const invokedDirectly =
+  process.argv[1] &&
+  pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url
+if (invokedDirectly) {
+  run(process.argv.slice(2)).then((code) => { if (code) process.exit(code) })
+}

package/dist/recorder.cjs

@@ -0,0 +1,128 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/recorder.ts
+var recorder_exports = {};
+__export(recorder_exports, {
+  createRecorder: () => createRecorder,
+  emit: () => emit,
+  resolveEnabled: () => resolveEnabled
+});
+module.exports = __toCommonJS(recorder_exports);
+var import_meta = {};
+function win() {
+  return typeof window !== "undefined" ? window : void 0;
+}
+function emit(event, detail) {
+  win()?.__snapshotTraceBus?.(event, detail);
+}
+function createRecorder(options = {}) {
+  const endpoint = options.endpoint ?? "http://localhost:7878/snapshot";
+  const enabled = resolveEnabled(options.enabled);
+  let recording = false;
+  let frames = [];
+  let startTs = 0;
+  let bus = null;
+  let reclaim = null;
+  const subs = /* @__PURE__ */ new Set();
+  const notify = () => subs.forEach((c) => c());
+  function installBus() {
+    bus = (event, detail) => {
+      if (!recording) return;
+      frames.push({ t: Date.now() - startTs, event, detail });
+    };
+    const w = win();
+    if (w) w.__snapshotTraceBus = bus;
+  }
+  function start() {
+    if (!enabled || recording) return;
+    frames = [];
+    startTs = Date.now();
+    recording = true;
+    installBus();
+    reclaim = setInterval(() => {
+      if (win()?.__snapshotTraceBus !== bus) installBus();
+    }, 500);
+    notify();
+  }
+  async function stop() {
+    if (!recording) return;
+    recording = false;
+    if (reclaim) {
+      clearInterval(reclaim);
+      reclaim = null;
+    }
+    const snapshot = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "snapshot-trace",
+      frameCount: frames.length,
+      frames
+    };
+    const payload = JSON.stringify(snapshot, null, 2);
+    notify();
+    await flush(endpoint, payload);
+  }
+  function toggle() {
+    recording ? void stop() : start();
+  }
+  return {
+    start,
+    stop,
+    toggle,
+    isRecording: () => recording,
+    subscribe(cb) {
+      subs.add(cb);
+      return () => subs.delete(cb);
+    }
+  };
+}
+async function flush(endpoint, payload) {
+  if (typeof navigator !== "undefined" && navigator.clipboard) {
+    navigator.clipboard.writeText(payload).catch(() => {
+    });
+  }
+  try {
+    await fetch(endpoint, { method: "POST", body: payload });
+  } catch {
+  }
+}
+function viteDev() {
+  try {
+    const env = import_meta.env;
+    return env ? Boolean(env.DEV) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveEnabled(explicit, devSignal = viteDev) {
+  if (typeof explicit === "boolean") return explicit;
+  const vd = devSignal();
+  if (typeof vd === "boolean") return vd;
+  if (typeof process !== "undefined" && process.env && process.env.NODE_ENV) {
+    return process.env.NODE_ENV !== "production";
+  }
+  const host = win()?.location?.hostname;
+  return host === "localhost" || host === "127.0.0.1";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRecorder,
+  emit,
+  resolveEnabled
+});

package/dist/recorder.d.cts

@@ -0,0 +1,21 @@
+type Frame = {
+    t: number;
+    event: string;
+    detail: unknown;
+};
+type Recorder = {
+    start(): void;
+    stop(): Promise<void>;
+    toggle(): void;
+    isRecording(): boolean;
+    subscribe(cb: () => void): () => void;
+};
+/** Drop anywhere in app code. No-ops unless a recorder is active and recording. */
+declare function emit(event: string, detail?: unknown): void;
+declare function createRecorder(options?: {
+    endpoint?: string;
+    enabled?: boolean;
+}): Recorder;
+declare function resolveEnabled(explicit?: boolean, devSignal?: () => boolean | undefined): boolean;
+
+export { type Frame, type Recorder, createRecorder, emit, resolveEnabled };

package/dist/recorder.d.ts

@@ -0,0 +1,21 @@
+type Frame = {
+    t: number;
+    event: string;
+    detail: unknown;
+};
+type Recorder = {
+    start(): void;
+    stop(): Promise<void>;
+    toggle(): void;
+    isRecording(): boolean;
+    subscribe(cb: () => void): () => void;
+};
+/** Drop anywhere in app code. No-ops unless a recorder is active and recording. */
+declare function emit(event: string, detail?: unknown): void;
+declare function createRecorder(options?: {
+    endpoint?: string;
+    enabled?: boolean;
+}): Recorder;
+declare function resolveEnabled(explicit?: boolean, devSignal?: () => boolean | undefined): boolean;
+
+export { type Frame, type Recorder, createRecorder, emit, resolveEnabled };

package/dist/recorder.js

@@ -0,0 +1,100 @@
+// src/recorder.ts
+function win() {
+  return typeof window !== "undefined" ? window : void 0;
+}
+function emit(event, detail) {
+  win()?.__snapshotTraceBus?.(event, detail);
+}
+function createRecorder(options = {}) {
+  const endpoint = options.endpoint ?? "http://localhost:7878/snapshot";
+  const enabled = resolveEnabled(options.enabled);
+  let recording = false;
+  let frames = [];
+  let startTs = 0;
+  let bus = null;
+  let reclaim = null;
+  const subs = /* @__PURE__ */ new Set();
+  const notify = () => subs.forEach((c) => c());
+  function installBus() {
+    bus = (event, detail) => {
+      if (!recording) return;
+      frames.push({ t: Date.now() - startTs, event, detail });
+    };
+    const w = win();
+    if (w) w.__snapshotTraceBus = bus;
+  }
+  function start() {
+    if (!enabled || recording) return;
+    frames = [];
+    startTs = Date.now();
+    recording = true;
+    installBus();
+    reclaim = setInterval(() => {
+      if (win()?.__snapshotTraceBus !== bus) installBus();
+    }, 500);
+    notify();
+  }
+  async function stop() {
+    if (!recording) return;
+    recording = false;
+    if (reclaim) {
+      clearInterval(reclaim);
+      reclaim = null;
+    }
+    const snapshot = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "snapshot-trace",
+      frameCount: frames.length,
+      frames
+    };
+    const payload = JSON.stringify(snapshot, null, 2);
+    notify();
+    await flush(endpoint, payload);
+  }
+  function toggle() {
+    recording ? void stop() : start();
+  }
+  return {
+    start,
+    stop,
+    toggle,
+    isRecording: () => recording,
+    subscribe(cb) {
+      subs.add(cb);
+      return () => subs.delete(cb);
+    }
+  };
+}
+async function flush(endpoint, payload) {
+  if (typeof navigator !== "undefined" && navigator.clipboard) {
+    navigator.clipboard.writeText(payload).catch(() => {
+    });
+  }
+  try {
+    await fetch(endpoint, { method: "POST", body: payload });
+  } catch {
+  }
+}
+function viteDev() {
+  try {
+    const env = import.meta.env;
+    return env ? Boolean(env.DEV) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveEnabled(explicit, devSignal = viteDev) {
+  if (typeof explicit === "boolean") return explicit;
+  const vd = devSignal();
+  if (typeof vd === "boolean") return vd;
+  if (typeof process !== "undefined" && process.env && process.env.NODE_ENV) {
+    return process.env.NODE_ENV !== "production";
+  }
+  const host = win()?.location?.hostname;
+  return host === "localhost" || host === "127.0.0.1";
+}
+export {
+  createRecorder,
+  emit,
+  resolveEnabled
+};

package/dist/server.mjs

@@ -0,0 +1,63 @@
+import { createServer as httpCreate } from 'node:http'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const CORS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+}
+
+export function createServer({ port = 7878, out = '/tmp/snapshot-trace.json' } = {}) {
+  const server = httpCreate((req, res) => {
+    if (req.url !== '/snapshot') {
+      res.writeHead(404, CORS).end('not found')
+      return
+    }
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, CORS).end()
+      return
+    }
+    if (req.method !== 'POST') {
+      res.writeHead(405, CORS).end('POST only')
+      return
+    }
+    const chunks = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      try {
+        const body = Buffer.concat(chunks).toString('utf8')
+        mkdirSync(dirname(out), { recursive: true })
+        writeFileSync(out, body, 'utf8')
+        res.writeHead(200, { ...CORS, 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: true, path: out, bytes: Buffer.byteLength(body) }))
+      } catch (err) {
+        res.writeHead(500, CORS).end(String(err))
+      }
+    })
+  })
+  return server
+}
+
+export function startFromArgv(argv) {
+  const opts = parseArgs(argv)
+  const port = opts.port ?? (Number(process.env.SNAPSHOT_TRACE_PORT) || 7878)
+  const out = opts.out ?? process.env.SNAPSHOT_TRACE_OUT ?? '/tmp/snapshot-trace.json'
+  const server = createServer({ port, out })
+  server.listen(port, '127.0.0.1', () => {
+    process.stdout.write(
+      `snapshot-trace listening on http://localhost:${port}\n` +
+      `  writing snapshots to ${out}\n`,
+    )
+  })
+  return server
+}
+
+export function parseArgs(argv) {
+  const out = {}
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--port') out.port = Number(argv[++i])
+    else if (argv[i] === '--out') out.out = argv[++i]
+  }
+  return out
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "snapshot-trace",
+  "version": "0.1.0",
+  "description": "Framework-agnostic runtime diagnostic recorder whose output a coding agent reads directly.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["debugging", "diagnostics", "recorder", "tracing", "devtools", "ai", "agent", "vite", "framework-agnostic"],
+  "repository": { "type": "git", "url": "git+https://github.com/nachogames/snapshot-trace.git" },
+  "homepage": "https://github.com/nachogames/snapshot-trace#readme",
+  "bugs": { "url": "https://github.com/nachogames/snapshot-trace/issues" },
+  "bin": { "snapshot-trace": "./dist/cli.mjs" },
+  "main": "./dist/recorder.cjs",
+  "module": "./dist/recorder.js",
+  "types": "./dist/recorder.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/recorder.d.ts",
+      "import": "./dist/recorder.js",
+      "require": "./dist/recorder.cjs"
+    }
+  },
+  "files": ["dist", "skill", "templates", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: snapshot-trace
+description: Add ad-hoc diagnostic events to a global recorder so the user captures them with a ●REC button and hands back a JSON file you read directly. Use when a frontend bug is reproducible but code-reading can't tell what's actually firing — instead of console.log spam, emit() to the bus and have the user record a ●REC→reproduce→■STOP cycle.
+---
+
+# snapshot-trace
+
+A framework-agnostic runtime recorder. Any code calls `emit('event', detail)`; a ●REC button buffers events; ■STOP flushes them as JSON to `/tmp/snapshot-trace.json`, which you read directly. Prefer this over `console.log` for runtime debugging — it's structured, ordered, and needs no copy-paste.
+
+## One-time setup (do this when the project isn't wired yet)
+
+1. Install: `npm i -D snapshot-trace` (or pnpm/yarn equivalent).
+2. Add a dev script so the listener runs during development:
+   ```jsonc
+   "scripts": { "snapshot:serve": "snapshot-trace serve" }
+   ```
+   The user runs `npm run snapshot:serve` in a second terminal alongside their dev server. (Do NOT auto-edit their existing `dev` script.)
+3. Add a ●REC button in the project's framework. Pick the matching template and place it somewhere visible in dev:
+   - Vue → `templates/vue.txt`
+   - React → `templates/react.txt`
+   - Plain DOM → `templates/vanilla.txt`
+
+   The button just wraps `createRecorder()`; it self-disables outside dev.
+4. Confirm `emit` is importable: `import { emit } from 'snapshot-trace'`.
+
+## The debugging loop
+
+1. Form a hypothesis about what's firing.
+2. Drop `emit` calls at suspected hot spots. One line, safe anywhere:
+   ```ts
+   import { emit } from 'snapshot-trace'
+   emit('source:phase', { /* small serializable detail */ })
+   ```
+   Include a stack when you need to know the caller:
+   ```ts
+   emit('updateThing:call', { id, stack: new Error().stack?.split('\n').slice(2, 12).join('\n') })
+   ```
+3. Hand off precisely:
+   > Make sure `npm run snapshot:serve` is running. Hard-refresh, click ●REC, reproduce the bug, click ■STOP.
+4. Read `/tmp/snapshot-trace.json` directly. Cite frames by `t` and `event`.
+5. Apply the fix.
+6. **Strip the `emit` hooks you added before committing:**
+   ```bash
+   grep -rn "emit('" src/   # find the ones you added; remove them
+   ```
+
+## Naming convention
+
+`<source>:<phase>` so the snapshot greps cleanly: `updateTask:PUT`, `dragStart:enter`, `onSelect:fire`.
+
+## Snapshot shape
+
+```json
+{ "ts": "<ISO>", "source": "snapshot-trace", "frameCount": 12,
+  "frames": [ { "t": 0, "event": "a:b", "detail": { } } ] }
+```
+`t` is ms since ●REC. Frames are in insertion order.
+
+## Red flags
+
+- Asking the user to copy-paste console output — wrong; the file handoff exists for this.
+- Auto-editing their dev-server config — never. The listener is a separate process.
+- Forgetting to remove your `emit` hooks before commit.
+- Hooking a path the user can't reach — verify your hook is on the reproducible path first.

package/templates/react.txt

@@ -0,0 +1,12 @@
+import { useSyncExternalStore, useRef } from 'react'
+import { createRecorder } from 'snapshot-trace'
+
+export function SnapshotRecButton() {
+  const rec = useRef(createRecorder()).current
+  const recording = useSyncExternalStore(rec.subscribe, rec.isRecording, () => false)
+  return (
+    <button onClick={() => rec.toggle()} style={{ color: recording ? 'red' : undefined }}>
+      {recording ? '■STOP' : '●REC'}
+    </button>
+  )
+}

package/templates/vanilla.txt

@@ -0,0 +1,13 @@
+<!-- Plain-DOM REC button. Renders only in dev (createRecorder gates itself). -->
+<button id="snapshot-rec">●REC</button>
+<script type="module">
+  import { createRecorder } from 'snapshot-trace'
+  const rec = createRecorder()
+  const btn = document.getElementById('snapshot-rec')
+  const paint = () => {
+    btn.textContent = rec.isRecording() ? '■STOP' : '●REC'
+    btn.style.color = rec.isRecording() ? 'red' : ''
+  }
+  rec.subscribe(paint); paint()
+  btn.addEventListener('click', () => rec.toggle())
+</script>

package/templates/vue.txt

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { ref, onUnmounted } from 'vue'
+import { createRecorder } from 'snapshot-trace'
+
+const rec = createRecorder()
+const recording = ref(rec.isRecording())
+const off = rec.subscribe(() => { recording.value = rec.isRecording() })
+onUnmounted(off)
+</script>
+
+<template>
+  <button :style="{ color: recording ? 'red' : undefined }" @click="rec.toggle()">
+    {{ recording ? '■STOP' : '●REC' }}
+  </button>
+</template>