Skip to main content
An HTML artifact can keep data with window.openArtifacts. Polls, trackers, and checklists all work this way. The data belongs to the artifact, not a version, so a new version sees the same data.

Ready and theme

openArtifacts.ready is a promise that resolves once the viewer shell has connected; wait for it before your first call. Outside the viewer, with no shell, it resolves at once. openArtifacts.theme is "light" or "dark". It starts from the viewer’s system setting and follows the shell’s theme once it connects. onTheme(callback) calls back whenever it changes and returns a function that stops listening.

Capabilities

An artifact declares what it uses when it’s published, for example capabilities: { db: true, viewer: true }. Calls to anything it didn’t declare are rejected.

Shared data: db

db.collection(name) returns a collection with:
  • get(id) to read one document, or null
  • list({ cursor, limit }) and query(filter) to read many. Each returns a page, { items, nextCursor }; pass nextCursor back as cursor for the next page.
  • query({ where, orderBy, order, limit, cursor }) filters on equal values and sorts by one field. With where or orderBy, it reads the whole collection, so it works only while the collection holds up to 2 MB; past that it fails with query_too_large. For bigger data, use list() and filter in the page, or split it into smaller collections (for example, one per day).
  • set(id, doc), update(id, patch), and delete(id) to write
  • subscribe(callback) for live updates when anyone changes the collection. It returns a function that unsubscribes.
Each document is { id, data, updatedAt, updatedBy }, with your value in data. Each subscribe callback gets { docs, deleted }: the documents that changed and the ids of those deleted. If the live connection drops and reconnects, changes may have been missed, so the callback gets { docs: [], deleted: [], resync: true } instead. On resync, refetch with list() or query(). If the live connection is refused or keeps failing, the callback gets { docs: [], deleted: [], offline: true }, once per outage: live changes are paused. Tell the viewer (for example, “Live updates paused. Reload to retry.”). When the connection comes back, the callback gets resync.

The viewer: viewer

viewer.get() returns { email, name }, or null for an anonymous viewer of a public artifact. viewer.anonId() returns an anonymous viewer’s id on an artifact whose viewers can change its data (dataWriters: "viewers"), and null otherwise (logged-in viewers included).

Anonymous ids

On a public artifact that lets viewers change its data, each anonymous browser gets an id from viewer.anonId(), so a game or poll can tell two anonymous players apart. Their documents carry updatedBy: "anon:<anonId>". Only documents written before anonymous ids existed still say "anon".
  • It belongs to one browser on one device. Another browser or device gets a different id, and clearing site data resets it.
  • Each artifact sees a different id for the same browser, so ids can’t be matched across artifacts.
  • It is not a person or an account, so don’t treat it as proof of who someone is.
  • It is signed by the server: no one can forge someone else’s id, but anyone can reset their own.
  • It expires after a fixed period, but a write after about half of that period renews it with the same id, so a guest who keeps using the page keeps their id. An expired (or legacy) token is never renewed: the browser’s next write gets a new id, and it can no longer edit or delete comments it wrote under the old one (they stay visible with their display name). This is how a leaked token stops working.
  • It is only issued on artifacts with dataWriters: "viewers". Logged-in viewers never get one.
An anonId is a label, not a permission. Any anonymous viewer can still overwrite or delete any document, so use it to show who did what (for example, a seat claimed by anonId) and expect conflicts.

Per-viewer data: storage

storage keeps documents keyed to the current viewer, such as which boxes they ticked, with get(key), set(key, value), delete(key), and list(), which returns the viewer’s keys.

Who can write

  • Anyone who can view the artifact can read and change its live data.
  • Set dataWriters: "editors" to limit writes to its editors. Other viewers can still read, and their writes fail with data_editors_only.
  • Writes from anonymous viewers of a public artifact are rate-limited per IP address.

Public live pages checklist

Before you share a public page that writes data, check each item:
  1. Published public with every capability the page calls (db, viewer). Anyone who can see it can change its data by default; a page only its editors or the owner’s agent should change (a dashboard, a scoreboard fed by an agent) gets dataWriters: "editors".
  2. Every write has a rejection path the visitor can see: data_editors_only or unauthorized (show the page as read-only), capability_denied, rate_limited, quota_exceeded, no_shell, and a generic “didn’t save” for anything else. Never catch and ignore a write.
  3. The visitor’s id comes from viewer.anonId(), read once at start and retried a few times if it rejects. A made-up fallback id changes on reload, so the visitor loses their vote or seat.
  4. Two tabs of one browser share one anonId: treat them as the same visitor.
  5. Anonymous writes are limited per network, shared by everyone behind it (an office, a classroom). Write on user actions only.
  6. The page subscribes, refetches when resync is true, shows that live updates are paused when offline is true, and adopts the doc its own write returns.
  7. Tested as an anonymous visitor in two separate browsers (not two tabs): writes show up in both, a refused write shows its message, and the page works at phone width.

Limits

Errors

Every call returns a promise. A failed call rejects with an error that has a code and a message: Handle no_shell by showing the page without live data:

How it works

The artifact runs in a sandboxed iframe with no credentials. Each call goes by postMessage to the viewer shell around it, which checks the call and makes it with the viewer’s session. Opened outside the viewer, the artifact has no shell, so every call rejects at once with no_shell. Live data works on the page the viewer first opens. If the artifact navigates its own frame to another page, for example through a link to another of its files, calls on that page fail with no_shell, and reloading the viewer restores them. If a multi-page artifact needs live data, switch views within one page instead of linking between files. Links: a link to another site, or to another artifact by its /a/<id> page, takes target="_blank" rel="noopener" and opens in a new tab. A link to another of the artifact’s own files is relative and takes no target: it loads in the frame, where live data stops (see above). Never link the dashboard or settings pages, or another artifact’s or version’s /p/ or /c/ URL: a plain one is refused with a notice, and with a target it opens instead, landing on the wrong page.