Two-way data sync

Try it, without a Notion token

Everything below runs against a demo workspace that implements the same adapter interface as the Notion API, including its rate limits and its Free-plan block cap. Two renderers are shown side by side because that is the honest picture of the design: the left frame is the hosted embed, the right frame is the downloaded artifact running the way Notion runs an HTML block, in a sandbox with an opaque origin and no network at all.

Ten components, bound for real

Ten components are wired, not illustrated: the playground above binds any of them in one click, and each one carries a schema that has been driven through the whole loop by npm run check:components (138 assertions, one component at a time: bind, write, find the row, edit the row in Notion, find the value in what a device renders, trash the row, find the tombstone). They were picked the way a test suite is picked, so between them they cover every state shape the other 182 widgets use and every property type the mapping layer can write.

The star marks a key field. A row is identified by its key columns and nothing else, which is why those columns matter more than they look: a widget that mints its own id (the SPEC family, so the three on the bottom row) gives every record an identity, so two invoices that happen to look identical are two rows. A widget that does not gives its records a key built from their own fields, so two identical expenses on the same day are one row. Each component says which of the two it is, above and in the playground, instead of leaving a user to find out by losing a row.

The ten are curated, not the limit. The palette above lists all 192 widgets, and 147 of them can be bound right now: 10 carry a hand-written first document, 81 are generated from a field list the widget itself carries, and 56 were measured by running the widget headlessly and asking it what it persists —45 persist nothing a table could hold, and the palette says so on the card instead of offering a button that would create an empty table.

Two commands keep that number honest, and both need npm run dev:

• npm run check:coverage — binds every widget that can produce a first document (147 of them), provisions its table, uploads the document, reads it back and compares, then pushes the same document again to prove the second push adds no row. 585 assertions, and the 45 widgets it cannot bind are listed by name rather than skipped in silence.
• npm run check:components — the ten above, driven the long way: write from the widget, find the row, edit the row in Notion, find the value in what a device renders, trash the row, find the tombstone. 138 assertions.

Of the 166 widgets that persist state, ten do not use the notion-arena.<slug>.v1 key they look like they should, and the bind reads the key out of the file rather than assuming it, because adopting the wrong key is invisible until a device renders empty.

The model, in four sentences

• Notion is the source of truth. Arena stores bindings, a sealed instance key, and a cache. Delete Arena and the data is still a database in your workspace, readable by any Notion client.
• An instance is one component, in one configuration, bound to one data source. It has an id and a capability key, and both live in the URL, so identity travels with the link and never depends on cookies or browser storage.
• A renderer is anything that draws that instance: the hosted embed, the HTML block, a standalone page, an integrator's site. Every renderer is the same file with a different transport.
• Widgets keep their own state shape and their own code. The mapping layer, not the widget, decides whether that shape becomes typed rows (records) or one JSON cell (kv-blob).

Two drawings carry this section better than prose does: figure 01 is the problem, three devices and three separate copies with no channel between them, and figure 02 is the shape that replaces it. Both are in the gallery, with the rest of them.

Two channels, one instance

The same instance is reachable two ways. They differ in transport and in what the browser is allowed to do, not in what they show.

The sync code

An offline renderer cannot reach Arena, but a person can carry text between two machines, so that is the bridge. The bridge exposes a sync code: instance id, base revision, and the queued operations, encoded and shown as a short string. Paste it into any reachable renderer on the same instance and the ops are pushed from there, with the same idempotency keys they were born with, so replaying the same code twice cannot double-write.

ARC1.eyJ2IjoxLCJpIjoiaW5zXzAxaDkiLCJiYXNlIjo0MSwib3BzIjpbeyJpZCI6Im9wXzdmMiIsImtleSI6IndhdGVyIiwicGF0aCI6WyIyMDI2LTEwLTEyIl0sInZhbHVlIjoyLCJhdCI6MTc2MDMyMTA0Mn1dfQ

The server-side refresh is the other half: the publish endpoint re-renders the instance with the current revision and swaps the block's file through a single PATCH /v1/blocks/{id} with a fresh file upload, so an offline reader picks up changes without an extra block appearing on the page every time.

Binding a component to your data

Binding answers two questions: which data source, and how does the widget's state become rows. The mapping layer infers the second by default, from the sample document in the widget's own registry entry, and a declared schema overrides it where inference guesses wrong.

A record's identity is a business key, not a row id: the widget says "water" and "2026-10-12" and the engine finds the row that matches. Renaming a component or re-binding it to a different database therefore does not orphan data, and a person editing the table by hand cannot break the link by touching a hidden column.

Conflicts

Two writers can touch one field within the same minute, and the workspace is the only place that knows what actually happened, so the rule is per-field last-writer-wins ordered by last_edited_time, with our own monotonic counter breaking ties. Nothing is silently dropped: the losing value is written to an append-only conflict log and shown as a notice in the widget. Event-shaped data is the exception, where the right answer is keep-both rather than last-writer-wins.

Connections and credentials

Two ways in, because they fail in different places. The public connection (OAuth) is the default for anything a user gives to other people: it can create databases anywhere the user installs it, and it survives nothing on our side, which is the point. A pasted token (an internal connection or a personal access token) is the escape hatch for local work, air-gapped installs and self-hosting.

A user's Notion token is never placed in a widget URL. It is validated on the way in by reading its own identity, sealed with AES-256-GCM, and stored server-side. What reaches the browser is a capability key scoped to one instance, revocable, rotatable, and useless against anything else in the workspace.

What the platform will refuse

Three limits shape the design, and each one is handled rather than retried.

• The Free-plan block cap. A multi-member workspace on Free has a lifetime block allowance, and deleting blocks does not give it back. The API says so precisely: a 403 restricted_resource carrying additional_data.block_limit. Retrying will never succeed, so the engine stops and explains. Personal access tokens and any-workspace OAuth installations are exempt.
• Rate limits per connection. 180 requests per minute on Free and Plus, 600 on Business and above, shared across the whole workspace, with Retry-After that can exceed a minute. Every adapter call goes through one token bucket, and only 429 and 529 are retried, because those are the only two that mean "later".
• Record size. A page that gets too large is rejected outright, so a blob-mode instance keeps a size ceiling and warns well before it, instead of an unexplained 400 on the next save.

The endpoints

/embed/{slug} stays what it always was, and gains the bound form: ?i=<instance>&k=<key> renders that instance live, no key renders the query-string configuration as before.

Still open, and how to close it

Four questions cannot be answered from documentation, because they depend on which Notion client is rendering the page. The probe file measures the environment it is running in, so it answers them from inside a real workspace: upload it as an HTML block, or open the URL in an embed block, and read the table.

The whole loop, one write end to end, is figure 03; the identity that makes the same instance render the same rows on a second device is figure 06. All six are collected at the sync in figures, each with a PNG to take away.

The deeper research, including the direct citations for every platform limit quoted above and the survey of what two-way-sync vendors do and do not do, is in docs/DATA_SYNC_RESEARCH.md. The phased build order is in docs/SYNC_PLAN.md.