Build an app for Atomics

An Atomics app is a small web page that runs on a card on a shared board. It draws its own interface, keeps its state on its card, and asks the space for anything else through one global, atomics. This page is the whole contract.

Quickstart

1. Write app.js: one plain script, no imports and no build step. Wrap it in a function so nothing leaks into the page.
2. Put it in a zip, with a manifest.json beside it if you want to name the app, its permissions or its size.
3. Open Studio, choose Import a zip, and pick the file. Studio checks it and shows you what it found.
4. Add the app to one of your spaces. It arrives as a card, and everyone in the space sees the same card.

A counter that everyone in the space shares:

(() => {
  const button = document.createElement('button')
  document.body.append(button)
  const draw = (state) => (button.textContent = `Clicked ${state.count || 0} times`)

  atomics.call('card.read').then(({ state }) => draw(state))
  atomics.on('card', ({ state }) => draw(state))

  button.onclick = async () => {
    const { state } = await atomics.call('card.read')
    await atomics.call('card.write', { set: { count: String(Number(state.count || 0) + 1) } })
  }
})()

{
  "name": "Counter",
  "permissions": ["card.state"],
  "size": { "width": 320, "height": 200 },
  "glyph": "timer"
}

The manifest

Every field is optional in a Studio zip. Studio sets the app's id, version, entry and hash itself.

The sandbox

The app runs in an iframe with no origin of its own and a strict content security policy. Atomics checks the app's permissions on every call it makes, not only when it opens.

• Network. fetch reaches only the hosts the manifest lists. Pictures, sound and fonts load only from data: and blob: addresses, so fetch a picture from a listed host and show it with URL.createObjectURL.
• Storage. No cookies, localStorage or IndexedDB. Keep state on the card with card.write.
• Code. Inline script and blob: workers run; eval and new Function are refused, and so is WebAssembly in a Studio app.
• The page. No navigation, popups, forms or nested frames. Use embeds.add to put a page or player beside the card.
• Devices. No camera, microphone, location, clipboard, passkeys or payments.
• Size. A Studio app is one script of at most 200 KB, in a zip of at most 2 MB.

What a person is told about all this is on What apps can reach.

Talking to the space

• atomics.call(method, params) returns a promise of the answer. A method the app has no permission for is refused.
• atomics.on(event, listener) calls the listener each time the host sends that event.
• The host sets --atomics-ink, --atomics-paper, --atomics-accent, --atomics-font and color-scheme on <html>. Use them with fallbacks so the app matches the board in light and dark.
• Card state is shared by everyone in the space. When two people may write at once, give each person their own key, such as vote.<member id>, and redraw on card events rather than assuming your write was the last.

Methods

Events

Permissions

Each permission is shown to the person adding the app, in these words.

Server code

An app can carry code that runs on the server, for work a frame cannot do alone: keeping data that only the app writes, per space or per person, and calling sites the frame should not call itself. Put a server.js beside app.js in the zip. It is an ES module with a default fetch handler, and it runs in an isolated worker of its own.

export default {
  async fetch(request, env) {
    const { data: count } = await env.SPACE.call('storage.get', { key: 'count' })
    const next = (count || 0) + 1
    await env.SPACE.call('storage.set', { key: 'count', value: next })
    return Response.json({ count: next })
  }
}

The frame calls it with app.fetch:

const { status, text } = await atomics.call('app.fetch', { path: '/count', method: 'POST' })
const { count } = JSON.parse(text)

• Approval. Server code runs in a space only once the space’s owner approves that version. A new version is a new approval. Until then app.fetch is refused unapproved, so tell people who has to approve it.
• Who calls. Only people signed in who can open the card. The request’s x-firebrand-app-caller header is the id the app knows them by in this space, the same as members.list. Their cookies and credentials are never forwarded.
• The space. env.SPACE.call(method, params) answers { ok: true, data } or { ok: false, problem, message }. It reaches only this card and the app’s own storage in this space. For somebody who may only watch the space, every write is refused read-only.
• Network. fetch reaches only the hosts the manifest lists, and redirects are not followed.
• Limits. A request or answer of at most 1 MB. A response cannot set cookies, and is served with Content-Security-Policy: sandbox.