@fairfox/polly

Reactive state for multi-context apps — from single-process signals to peer-to-peer encrypted mesh — with formal verification.

The pitch

Define state once. Read it anywhere. Polly keeps them in sync.

// src/shared/state.ts
import { $sharedState } from "@fairfox/polly/state";

export const counter = $sharedState("counter", 0);

// src/background/index.ts — service worker, extension background, Node process
import { createBackground } from "@fairfox/polly/background";
import { counter } from "../shared/state";

const bus = createBackground();

bus.on("INCREMENT", () => {
  counter.value++;
  return { count: counter.value };
});

// src/popup/index.tsx — browser popup, any Preact/React UI
import { render } from "preact";
import { counter } from "../shared/state";

function App() {
  return (
    <div>
      <p>Count: {counter.value}</p>
      <button onClick={() => counter.value++}>+</button>
    </div>
  );
}

render(<App />, document.getElementById("root")!);

The background writes counter. The popup reads it. Both stay in sync — no message passing, no subscriptions to manage. State is a Preact Signal, so the UI re-renders automatically when the value changes.

State that syncs everywhere

Modern apps run code in multiple isolated contexts: service workers, content scripts, server processes. Keeping state consistent across them means writing sync logic for every piece of data. Polly replaces that with four primitives:

Primitive	Syncs	Persists	Use for
$sharedState	yes	yes	User data, settings, auth — anything that should survive a restart and stay consistent
$syncedState	yes	no	Ephemeral shared state: connection status, live collaboration flags
$persistedState	no	yes	Per-context settings, form drafts
$state	no	no	Local UI state: loading spinners, modal visibility

All four return Preact Signals. Read with .value, write with .value =.

import { $sharedState, $syncedState, $persistedState, $state } from "@fairfox/polly/state";

const user = $sharedState("user", { name: "Guest", loggedIn: false });
const wsConnected = $syncedState("ws", false);
const draft = $persistedState("draft", "");
const loading = $state(false);

For async data, $resource fetches and re-fetches automatically when its dependencies change:

import { $resource } from "@fairfox/polly/resource";

const todos = $resource("todos", {
  source: () => ({ userId: user.value.id }),
  fetcher: async ({ userId }) => {
    const res = await fetch(`/api/todos?userId=${userId}`);
    return res.json();
  },
  initialValue: [],
});

todos.data;   // Signal<Todo[]>
todos.status; // Signal<"idle" | "loading" | "success" | "error">
todos.refetch();

Peer-first state (v0.21.0)

The four primitives above keep state consistent inside a single deployment. But some applications need state that survives the server going away, or state that the server never sees at all. Polly now offers three resilience tiers, each a distinct primitive family:

Tier	Primitive	Server's role	Resilience
Weakest	$sharedState	Source of truth	Server backups
Middle	$peerState	Full peer on the data path	Any device can rehydrate the server
Strongest	$meshState	Not on the data path	App works with zero server uptime

$peerState — every device holds a full Automerge CRDT replica. The server holds one too, so cron and HTTP handlers can read and mutate documents. If the server loses its storage, any reconnecting client repopulates it through the normal sync protocol.

import { createPeerStateClient, configurePeerState, $peerState } from "@fairfox/polly/peer";

const client = createPeerStateClient({ url: "wss://yourapp.com/polly/peer" });
configurePeerState(client.repo);

const settings = $peerState("settings", { theme: "dark" });
await settings.loaded;
settings.value = { theme: "light" }; // syncs to every peer

$meshState — peers exchange operations directly over WebRTC data channels, signed with Ed25519 and encrypted with XSalsa20-Poly1305. No server sees the data. A small stateless signalling server helps peers find each other; removing it does not affect running connections.

import { configureMeshState, $meshState, MeshNetworkAdapter, MeshWebRTCAdapter } from "@fairfox/polly/mesh";

const repo = new Repo({ network: [new MeshNetworkAdapter({ base: webrtcAdapter, keyring })] });
configureMeshState(repo);

const notes = $meshState("notes", { entries: [] });
// Operations flow peer-to-peer, signed and encrypted

First-time key exchange between devices uses a pairing token displayed as a QR code. Compromised devices are revoked via signed revocation records that propagate to every peer.

The three tiers coexist in one application — public settings in $sharedState, collaborative documents in $peerState, private notes in $meshState. See docs/STATE.md for the full decision tree and docs/RFC-041-choosing.md for the design rationale.

Node and Bun are first-class mesh peers

Archival cron, LLM proxies, admin CLIs, headless bridges — every always-on participant gets the same state primitives as the browser, without monkey-patching globals or writing bespoke transport wiring. Polly ships a factory that accepts injectable transport and storage:

import { createMeshClient, $meshState } from "@fairfox/polly/mesh";
import { bootstrapCliKeyring, fileKeyringStorage } from "@fairfox/polly/mesh/node";
import { RTCPeerConnection } from "werift";              // or '@roamhq/wrtc'

const storage = fileKeyringStorage("~/.fairfox/keyring.json");
const keyring = await bootstrapCliKeyring({ storage });   // first run prompts for a pairing token

const client = await createMeshClient({
  signaling: { url: "wss://example.com/polly/signaling", peerId: "cli-a1b2" },
  rtc:       { RTCPeerConnection },
  keyring,
});

const doc = $meshState("agenda", { items: [] });
await doc.loaded;
await client.close();

createMeshClient is runtime-agnostic — in a browser the rtc option is optional because globalThis.RTCPeerConnection exists. The @fairfox/polly/mesh/node subpath adds filesystem-backed keyring storage, atomic writes with 0600 permissions, and the stdin bootstrap flow. Neither werift nor @roamhq/wrtc is bundled; both are declared as optional peer dependencies. Pick the one that fits your deployment — werift installs cleanly anywhere (pure TypeScript, no native deps), @roamhq/wrtc is faster but needs prebuilt binaries for your platform.

Blob storage for large files

CRDT documents shouldn't carry binary payloads — the op history grows with every sync. Polly ships a content-addressed blob store that transfers files peer-to-peer over the same WebRTC channels as $meshState, with no server storage. Documents hold lightweight BlobRef values; the bytes live in a local IndexedDB cache and move between peers in 64 KiB chunks.

import { createBlobStore, createBlobRef } from "@fairfox/polly/mesh";

const blobs = createBlobStore(webrtcAdapter, { encrypt: { key: docKey } });

// Sender
const bytes = new Uint8Array(await file.arrayBuffer());
const ref = await createBlobRef({ bytes, filename: file.name, mimeType: file.type });
await blobs.put(ref, bytes);       // caches locally, announces to peers
doc.value = { ...doc.value, attachment: ref };

// Receiver (on any connected peer)
const received = await blobs.get(ref.hash);  // fetches from peers, verifies hash
const url = await blobs.url(ref.hash);        // object URL for <img src>

SHA-256 content addressing deduplicates across peers and documents. Encryption is optional — when configured, the sender encrypts once (XSalsa20-Poly1305) and chunks the ciphertext; the receiver reassembles, decrypts, and verifies the plaintext hash against the BlobRef. See docs/RFC-042-blob-sync.md for the design.

Verification that plugs in

A popup and a background script both write to the same state. A content script reads it mid-update. Tests miss these bugs because they depend on timing.

Polly generates TLA+ specifications from your existing state and handlers, then model-checks them with TLC. You don't learn a new language. You annotate what you already wrote.

Step 1: Add contracts to handlers

requires() and ensures() are runtime no-ops. polly verify reads them statically.

import { createBackground } from "@fairfox/polly/background";
import { requires, ensures } from "@fairfox/polly/verify";
import { user, todos } from "./state";

const bus = createBackground();

bus.on("TODO_ADD", (payload: { text: string }) => {
  requires(user.value.loggedIn === true, "Must be logged in");
  requires(payload.text !== "", "Text must not be empty");

  todos.value = [...todos.value, {
    id: Date.now().toString(),
    text: payload.text,
    completed: false,
  }];

  ensures(todos.value.length > 0, "Todos must not be empty after add");

  return { success: true };
});

Step 2: Define state bounds

A verification config tells TLC what values to explore:

// specs/verification.config.ts
import { defineVerification } from "@fairfox/polly/verify";

export const verificationConfig = defineVerification({
  state: {
    "user.loggedIn": { type: "boolean" },
    "user.role": { type: "enum", values: ["guest", "user", "admin"] },
    todos: { maxLength: 1 },
  },
  messages: {
    maxInFlight: 2,
    maxTabs: 1,
  },
});

Step 3: Run it

$ polly verify

Generating TLA+ specification...
Running TLC model checker...

  Model checking complete.
  States explored: 1,247
  Distinct states: 312
  No errors found.

All properties verified.

If a requires() can be violated — say, a logout races with a todo add — TLC finds the exact sequence of steps that triggers it.

For larger apps, subsystem-scoped verification splits the state space so checking stays fast.

Step 4: Catch the path the model never sees

Every run also reports model coverage — which declared field each handler writes, and the fields nothing modelled touches. The bug it catches is a capability granted off the message bus: a register() method that sets canSend directly instead of through a dispatched, guarded handler. TLC has no transition for it, mutation testing has no modelled line to mutate, and a green run says nothing.

A field no handler writes is flagged as unreachable state. A field a non-dispatched function or method writes — even one a real handler also writes — is flagged as mutated outside any modelled transition. Add --strict to fail closed, so an unmodelled write can't slip through green.

$ polly verify --strict

⚠️  1 declared state field write(s) outside any modelled transition:
   • session.canSend mutated in RecoveryFlow.register() — src/background/index.ts:42

❌ Strict mode: model coverage incomplete

Executable specs that link to the model

polly bdd adds a third verification stratum alongside verify (TLA+) and mutate (Stryker): acceptance examples written from the user's perspective, as Gherkin, run across the real factory boundary — the same createBackground your extension boots, never a hand-wired bus that quietly papers over a gap the real path has.

# features/auth.feature
Feature: Signing in
  Scenario: A signed-out user can sign in
    Given the user is signed out
    When the user signs in as "admin"
    Then the user is signed in
    And their role is "admin"

One defineStep binding is dual-use, the same trick that makes requires()/ensures() work: its given/when/then drive the runtime, while its message/stateExpr are read statically. So the example layer, the formal layer and the mutation layer all describe the same handlers and state.

polly bdd          Run the scenarios across the real boundary (red before green)
polly bdd check    Cross-check every scenario against the verification config (Docker-free)
polly bdd new      Scaffold a feature stub seeded from the verify vocabulary

Drop .feature files into your project and polly test discovers a bdd tier automatically.

Reachability witnesses

polly verify --witness closes the loop between the example layer and the model. It turns each scenario's outcome into a per-scenario TLC reachability check: a scenario the exhaustive model proves unreachable is one that lies — green in the runner, impossible in the model — and it fails the run. The honest ones come back reachable, and the counterexample trace is the path a user would take to get there. Outcomes that aren't state-observable (a response-only check) are reported as skipped, never silently passed.

Tag a scenario @forbidden to assert the opposite: a state that must never happen. The witness then passes only when the model proves that state unreachable, and fails — with the trace to the defect — if it can reach it. Desirable outcomes proven possible, undesirable ones proven impossible, from the same Gherkin.

$ polly verify --witness

Reachability witnesses (--witness)
  ✓ reachable   Signing in › A signed-out user can sign in
  ✓ reachable   Signing in › Signing out returns the user to a guest session
  · skipped     Todos › Completing a todo that does not exist is refused

Witness result: ✓ PASS

Quick start

bun add @fairfox/polly preact @preact/signals

Scaffold a project:

polly init my-app --type=extension  # or: pwa, websocket, generic

Or start from one of the examples:

git clone https://github.com/AlexJeffcott/polly.git
cd polly/examples/minimal
bun install && bun run dev

Examples

Example	What it demonstrates
minimal	Counter with $sharedState — the simplest possible Polly app
todo-list	CRUD with requires()/ensures(), subsystem-scoped verification
full-featured	Production Chrome extension with all framework features
elysia-todo-app	Full-stack web app with Elysia + Bun, offline-first
webrtc-p2p-chat	Peer-to-peer chat over WebRTC data channels
team-task-manager	Role-based collaborative tasks with $constraints() and verified urgent-task counts

CLI

polly init [name] [--type=TYPE]   Scaffold a new project (extension | pwa | websocket | generic)
polly build [--prod]              Build for development or production
polly dev                         Build with watch mode
polly check                       Run all checks (typecheck, lint, test, build)
polly typecheck                   Type-check your code
polly lint [--fix]                Lint (and optionally auto-fix)
polly format                      Format your code
polly test [args]                 Run unit tests (bun test)
polly test:browser [dir]          Run *.browser.{ts,tsx} in Puppeteer
polly verify [--witness]          Run formal verification (TLA+/TLC); --witness adds
                                  per-scenario reachability checks for your BDD outcomes
polly bdd [run|check|new]         Executable Gherkin across the real boundary, linked to the model
polly mutate [run|report]         Mutation testing (Stryker) — prove the tests have teeth
polly visualize                   Generate architecture diagrams (Structurizr DSL)
polly quality [args]              Run conformance checks (no-as-casting, boundaries, secrets,
                                  server-imports, forbidden-deps, banners, marketing, ...)

Quality tooling

Polly ships conformance checks and a browser test harness that consuming applications can adopt directly.

No-as-casting check. Bans TypeScript as type assertions codebase-wide (only as const and the explicit escape hatch as unknown as are allowed). Violations include pattern-specific fix advice. Run as a CLI:

polly quality [--root <dir>] [--exclude-packages <names>] [--exclude-files <names>]

Or import it programmatically for integration into custom check scripts:

import { checkNoAsCasting } from "@fairfox/polly/quality";

const result = await checkNoAsCasting({ rootDir: process.cwd() });
if (result.violations.length > 0) {
  result.print();
  process.exit(1);
}

Browser test harness. A Puppeteer-based harness for testing browser-only code (WebRTC adapters, Preact components, anything needing real DOM). Bundles each test file with Bun.build, serves on an ephemeral port, and collects results:

import { describe, test, expect, done, flush, cleanup } from "@fairfox/polly/test/browser";

describe("my component", () => {
  test("renders", async () => {
    render(<MyComponent />, app);
    await flush();
    expect(app.querySelector("h1")).toHaveTextContent("Hello");
    cleanup(app);
  });
});

done();

Run with bun tools/test/src/browser/run.ts tests/browser.

Use with Claude Code

This repo ships with a Claude Code skill that covers the full Polly API — state primitives, peer-first and mesh state, verification, quality tooling, and the browser test harness. Install it in your project so Claude can help you integrate Polly with full context:

# From your project directory
claude install-skill /path/to/polly/.claude/skills

Then ask Claude things like:

• "How would Polly fit into this project?"
• "Add verification to my handlers"
• "Set up $peerState with an Elysia server"
• "Wire up the no-as-casting conformance check in CI"

If you maintain your own Claude Code skills, consider adding Polly's state-tier decision tree and verification patterns to your project-specific skill so Claude can recommend the right primitive for each piece of state.

Licence

MIT

---

GitHub · Issues · Examples