microsoft/Snapfeed

microsoft/Snapfeed

Description: Web UX snapshot and feedback loop for agentic development

Language: TypeScript

License: MIT

Stars: 11

Forks: 1

Open issues: 14

Created: 2026-03-19T17:35:47Z

Pushed: 2026-06-20T03:36:14Z

Default branch: main

Fork: no

Archived: no

README:

---

Why Snapfeed?

AI agents can write UI code, but they can't _see_ the result. Snapfeed gives them eyes. Drop one line into your app and every interaction — clicks, navigation, errors, and annotated screenshots — flows into a structured telemetry feed that an agent (or a human) can query.

Use Case 1 — Agentic Dev Loop

The agent writes code. You test. When something's off, Cmd+Click anywhere to capture an annotated screenshot with full page context. The agent reads the feedback, fixes the code, and you test again.

graph LR
A["Agent\nwrites code"] --> B["Your UI\n(with snapfeed)"]
B --> C["You test it\nCmd+Click feedback"]
C --> D["Agent\nreads feedback"]
D -- "fixes & iterates" --> A

Use Case 2 — User → Queue → Agent

Ship snapfeed in your production app. Real users submit annotated screenshots and text feedback. Feedback accumulates in a queue. An agent — or your dev team — triages and acts on it.

graph LR
A["Users\nin prod"] --> B["Snapfeed\nserver"]
B --> C["Queue\n(SQLite)"]
C --> D["Agent /\nDev team"]

---

Quick Start

Requires Node.js 20.19.0+ or 22.12.0+.

1. Add the client (one line)

npm install @microsoft/snapfeed

import { initSnapfeed } from "@microsoft/snapfeed";

initSnapfeed(); // that's it — Cmd+Click to send feedback

Snapfeed auto-captures clicks, navigation, errors, and API failures. No config needed for local dev — events POST to /api/telemetry/events by default.

2. Start a server

TypeScript (Hono + SQLite):

npx snapfeed-server
# 🔭 snapfeed-server listening on http://localhost:8420

Python (FastAPI + SQLite):

cd examples/python && pip install -r requirements.txt
uvicorn server:app --port 8420

Or mount into your own app:

import { snapfeedRoutes, openDb } from "@microsoft/snapfeed-server";
import { Hono } from "hono";

const app = new Hono();
app.route("/", snapfeedRoutes(openDb({ path: "./feedback.db" })));

3. Query the feedback

# List sessions
curl localhost:8420/api/telemetry/sessions

# Get events for a session
curl localhost:8420/api/telemetry/events?session_id=abc-123

# Get only feedback (Cmd+Click) events
curl localhost:8420/api/telemetry/events?event_type=feedback

# View a screenshot
curl localhost:8420/api/telemetry/events/42/screenshot --output feedback.jpg

---

What Gets Captured

| Event | Trigger | Detail | | --------------- | ----------------- | -------------------------------------------------------------------------- | | session_start | initSnapfeed() | Viewport, URL, user agent, plugins | | click | Any click | Element tag, role, CSS path, coordinates, component name (via plugins) | | feedback | Cmd+Click | Annotated screenshot, user message, console errors, page context | | navigation | SPA route change | Path, hash, search params | | error | window.onerror | Message, filename, line, stack trace | | api_error | fetch() non-2xx | URL, status, method | | network_error | fetch() failure | URL, error message, method |

All events include session_id, seq, ts, page, and target.

---

Packages

| Package | Description | | ------------------------------------------------- | ---------------------------------------------------------------- | | [@microsoft/snapfeed](./packages/client) | Client library — drop-in, framework-agnostic, zero config | | [@microsoft/snapfeed-server](./packages/server) | Reference backend — Hono + SQLite, pluggable or standalone | | [examples/react](./examples/react) | React integration example and Playwright-backed verification lab | | [examples/python](./examples/python) | Python backend example — FastAPI + SQLite (~100 lines) |

React E2E Lab

The repo now includes a dedicated React app for end-to-end validation in [examples/react](./examples/react). It is intentionally not a polished product demo. Its job is to exercise the full browser-to-database flow against a real SQLite file and make that flow easy to automate while also serving as a concrete React integration example.

The app covers:

• session_start on boot
• click events from regular UI interaction
• navigation events from SPA route changes
• api_error and network_error via explicit failing fetch flows
• error via uncaught errors and unhandled rejections
• feedback via the real Cmd/Ctrl-click dialog with screenshot and context

Run it manually

Use two terminals from the repo root:

npm run dev:react-e2e:server
npm run dev:react-e2e

Open the Vite app URL that prints in the terminal. The API server listens on http://127.0.0.1:8420 by default and writes to a local SQLite file under examples/react/.tmp/.

Run the automated browser suite

npm run test:react-e2e

The Playwright suite starts both the React app and the server harness, runs the browser flows, and verifies persisted DB rows.

Runtime note

The harness prefers the real [@microsoft/snapfeed-server](./packages/server) implementation. If the local better-sqlite3 native binding is unavailable, the dev server falls back to a node:sqlite compatibility server that preserves the same schema and endpoints so the React E2E workflow can still run on supported Node environments that expose the built-in SQLite module.

---

Server API

Both the TypeScript and Python servers implement the same 4 endpoints:

| Method | Endpoint | Description | | ------ | -------------------------------------- | -------------------------------------------------------- | | POST | /api/telemetry/events | Ingest a batch of events | | GET | /api/telemetry/events | Query events (?session_id=, ?event_type=, ?limit=) | | GET | /api/telemetry/sessions | List sessions with event counts | | GET | /api/telemetry/events/:id/screenshot | Serve feedback screenshot as JPEG |

Building your own backend? Implement POST /api/telemetry/events accepting:

{
"events": [
{
"session_id": "a1b2c3",
"seq": 1,
"ts": "2026-03-19T18:00:00.000Z",
"event_type": "click",
"page": "/dashboard",
"target": "button.save",
"detail": { "tag": "button", "x": 420, "y": 300 },...