Case studyLiveMIT licensed

preview-feedback

A self-hosted, open-source alternative to Vercel Toolbar comments

Built for taking notes and receiving client feedback on pre-production website previews. Reviewers open a link, drop a pin, and comment—no account, browser extension, or proprietary platform required.

preview-feedback browser page with a numbered pin and comment thread
~19 KB
gzipped widget
0
accounts or extensions
117
unit tests
168
browser checks

Role

Product and engineering

Built with

  • Web components
  • Cloudflare Workers
  • Durable Objects
  • TypeScript

The problem

preview-feedback began as part of Goji Health's offer to build websites for acupuncture practices at no cost. Each practice needs a private, pre-production copy where I can take implementation notes and the practitioner can review the site in context before it goes live.

Without a shared feedback layer, those notes come back by email, text message, or a phone call, with no link to the part of the page they were about. "The second thing on the services page looks off" has to be turned back into a place on a page, and then into a change, by hand.

Existing tools solve this well inside one host's ecosystem, or by asking every reviewer to install an extension or sign up. Neither fits a small client reviewing their own site once, on their phone.

Decisions that shaped it

The link is the credential
No logins, no extension. A site key lets whoever holds the preview link read and write that one site's comments and nothing else. It is the same trust model as sharing a private link, and the project deliberately never grows past it.
Honor system, on purpose
"Same author" means the same typed name, trimmed and case-insensitive. That is spoofable by design for a small group sharing a private link, and the docs say so rather than pretending it is stronger.
Comments are untrusted input
Anyone with a preview link can write text that a person or an agent will later read. Comments are never rendered as HTML, never executed or followed as instructions, and are marked as data in any agent-facing output.
A widget that leaves no trace
It is a custom element with its styles in a shadow root, so the host page's CSS cannot touch it and a bad brand color cannot make it unreadable. Everything it registers outside the shadow root is undone when the element is removed, and a browser check proves it. A site built without feedback has no element, no script, and no leftover file.

What's inside

Pins and threads
Numbered pins on the page, threads with replies, resolve and reopen, author-only delete, and deep links that scroll to the exact pin.
A toolbar you can move
Drag it anywhere, fold it into a bubble, and stand it against a side edge. Popovers are placed in the same render so they never flash at a default spot.
An inbox across pages
Every open thread on the site in one list, ordered by the site's own navigation.
A dashboard you host yourself
Every site's threads at /studio/ on the same Worker. Filter by page and width, reply, resolve with a note, and open the preview on the exact pin.
A CLI for you and your agents
Register a site, pull open threads with deep links, then reply, resolve, and reopen from the terminal.
Stable anchors
Comments pin to the nearest section, with a short path and a text snippet that lets the pin be found again after a rebuild.

Under the hood

One Cloudflare Worker with a SQLite-backed Durable Object per site, so a site's comments are small, written rarely, read together, and serialised for free. The widget started as vanilla TypeScript and moved to Lit in steps, with the browser checks passing unchanged, because hand-written render-and-restore-focus code had caused real bugs. Geometry and rules live in pure, unit-tested modules.

A change is only done when typecheck, unit tests, and the real-Chrome end-to-end check all pass. The next step on the roadmap is workspaces, so a second agency can use the same Worker with its data kept strictly separate, one Durable Object per site.

Use it now

preview-feedback is live as a self-hosted, open-source alternative to Vercel Toolbar comments. Deploy the Worker to your own Cloudflare account, add one script tag to a preview, and keep the feedback loop on infrastructure you control.

Next on the roadmap: multi-workspace tenancy, a versioned API, and an apply-feedback skill so an agent can pull open threads, change the site, reply with what changed, and resolve the work.