Surfaces

Static drop-in v0.0.8

A single client-only script that adds the Red Pen overlay to any website at all - static HTML, a built single-page app, or a file opened straight off disk. No server, no build step, no dependencies. Notes live in the browser.

The broadest on-ramp If your project does not run WordPress and is not a Node server, this is the surface for you. It is the simplest way to get Red Pen onto a page - one script tag and you are done - which also makes it the widest front door to the whole family. The trade-off is that, with no server, notes live in the browser's localStorage rather than a shared file or database.

What it is

The static drop-in is red-pen.js - one self-contained file with no dependencies and nothing to install. Drop it onto a page and a floating red button appears in the bottom-right corner. Click it to leave typed, prioritised notes, pin them to elements, and work through them on a cross-page board. It is the client-only sibling of the WordPress plugin and the Express middleware: the same overlay and the same note model, with a browser-local backend instead of a database or a file.

It works anywhere a browser can run a script, including:

Plain static HTML sites.
The built output of any SPA or static-site generator - React, Vue, Svelte, Astro, Hugo, Jekyll, and the rest.
A page opened directly from disk over file://, with no web server at all.
Anything hosted anywhere - the script does not care where the page came from.

Install

Add one line. Copy red-pen.js into your project (or reference it from wherever you keep it) and include it:

<script src="red-pen.js"></script>

That is the entire installation. There is nothing to build, bundle, or configure. The red button appears as soon as the page loads.

Keep it dev-only

Red Pen is a tool for the people building the site, not its visitors. The static drop-in has no built-in login or capability check - it is just a script - so it is on you to make sure it never loads in production or for real users. The recommended pattern is a tiny inline loader that only injects red-pen.js on localhost:

<script>if(['localhost','127.0.0.1'].indexOf(location.hostname)!==-1){var rp=document.createElement('script');rp.src='red-pen.js?v=1';document.body.appendChild(rp);}</script>

This guard checks the page's hostname and loads the overlay only when you are working locally. On a deployed site the condition is false, the script is never fetched, and visitors see nothing. The ?v=1 is a simple cache-buster - bump it when you update red-pen.js so the browser pulls the new version.

Two-layer safety on public sites On sites that real users or players will see, pair the localhost guard with a build convention: gitignore red-pen.js itself so the dev tool is never committed or deployed. The loader line in your HTML stays harmless (it only ever tries to load the file on localhost), and the file simply is not present in production. This is how Red Pen is wired into public-facing sites today.

Using it

Open the red button in the bottom-right and the Red Pen panel slides in. From there you can:

Leave a typed note. Choose a type - note, idea, problem, or question - set a priority, and write the body. See Core concepts for what each field means.
Pin a note to an element. Click Pin, then click any element on the page. Red Pen records an anchor for it and drops a numbered red marker over the element. The markers follow the page as it scrolls and reflows.
Locate a pinned note. From a note, jump straight back to the element it is pinned to - the page scrolls to it and flashes it.
Open the cross-page board. All notes opens a board listing every note across every page of the site, not just the current one, with Export and Import.
Adjust the workspace. A dark-mode toggle and a resizable panel live in the panel header.

Where notes are stored

Because there is no server, notes persist to the browser's localStorage. That means they are scoped to one browser on one origin - they are not shared between machines or browsers automatically, and clearing site data will remove them. Use Export to back them up. The keys Red Pen writes are:

localStorage key	Holds
`redpen.notes.v1`	The array of notes (each with id, body, type, priority, status, url, page, anchor, createdAt, and a `resolvedAt` once resolved).
`redpenTheme`	The light / dark theme preference.
`redpenWidth`	The saved width of the panel.

Notes are scoped per page by location.pathname, so each page shows its own list. The All notes board lifts that scoping and shows every page's notes together.

Export and import

Since the static surface has no server or shared file, JSON export and import are how you move notes around - and they are your backup. From the All notes board:

Export writes every note to a JSON file you can save, commit alongside the project, or hand to someone else.
Import loads a JSON file back in - to restore after clearing site data, to carry notes to another browser or machine, or to merge in someone else's review pass.

Export and import are part of the free core on every surface and are never gated.

Connect to the Hub

The static drop-in can push its notes to the Red Pen Hub so they appear on the combined board alongside every other project. This is the bridge out of browser-local storage. To set it up:

Open the red button, then All notes.
Open the Connect to Hub panel.
Paste your Hub URL (for a local Hub this is http://localhost:3900) and the Hub's shared token.
Click Save and Sync.

From then on the site's notes are pushed to the Hub, where they show up as a connected source. The notes still live in the browser - the Hub holds a synced copy for the combined view. See the Hub page for how connected sources work and where to find the URL and token.

Two-way sync (v0.0.8) The Hub connection is no longer one-way. When you resolve, reopen, or start a note on the Hub board, that status change now flows back to the site: on each push the drop-in reads the status changes the Hub hands back and applies them to its local store, and it also syncs on page load. Before this, push was one-way - the Hub held its own view but the site never saw a Hub-side resolve. Now the Hub is a real control surface for a static site's notes.

Where it is used today

The static drop-in is dogfooded on several real projects, which double as its test cases:

The Path of Grace Elden Ring completion tracker.
tarkov-tracker (Raid Ledger), the Escape from Tarkov PvE companion.
This very product site - the Red Pen marketing page runs Red Pen on itself, so feedback about Red Pen is left with Red Pen.

Try it Open example/index.html from the static surface's folder in any browser and use the red button - that is the whole product, with nothing to install.

Current status

Version 0.0.8 ships the floating button and panel, typed notes (note / idea / problem / question) with priority, a per-page list, resolve / reopen / delete, click-to-pin with numbered markers and Locate, dark mode, a resizable panel, the cross-page All-notes board, JSON export / import, and the Connect to Hub panel. It is ported from the Express widget with a localStorage backend. Two recent additions round out the Hub connection:

v0.0.7 - resolving a note now stamps an ISO resolvedAt (cleared on reopen), so the Hub's Resolved column is populated for notes closed in the on-page overlay.
v0.0.8 - two-way Hub sync: resolving, reopening, or starting a note on the Hub board flows back to the site (the drop-in applies the status changes the Hub returns on each push, and also syncs on page load). Push used to be one-way.

Planned work - replies in the overlay, editing a note in place, three-state status, screenshots, and an agent-feedback lane - is tracked on the Roadmap and broadly tracks the Express feature line.

Previous← Express middleware NextAbleton Live →