Standard

The Workbooks standard.

A workbook is one HTML file. Open it in any modern browser and it runs. This page is the prose spec — what makes a file a workbook, what the runtime guarantees, and how recipients run it safely.

File shape

A workbook is a syntactically valid HTML5 document. It MUST be self-contained — no external <script src>, <link href>, or <img> references that the recipient is required to resolve. Everything the workbook needs to run is inlined (CSS, JS, fonts, datasets under ~few MB; larger assets may use a fetch with a permission declaration).

A workbook SHOULD declare its required permissions in a <meta name="wb-permissions"> tag. Studio and the manager UI read this to render a runtime prompt before executing the file.

<meta name="wb-permissions" content="net,storage">

Permission tokens

• none — pure compute, no I/O. Default if the tag is missing.
• net — may make outbound HTTPS requests.
• storage — may persist state via IndexedDB / origin-private FS.
• clipboard — may read or write the clipboard on user gesture.
• env — expects runtime values (Studio injects WB_ENV).

The runtime SDK

@work.books/runtime is the open-source SDK that gives authors a small set of host-agnostic primitives: wb.state, wb.persist, wb.env, wb.share. The SDK degrades gracefully — a workbook running from a plain file system gets no-op persistence; the same workbook running inside Studio's viewer gets real persistence wired to the broker.

Source bundle

Builds embed a gzipped snapshot of the source tree under a non-script <script> tag with type application/x-workbook-source. Browsers don't parse it, so it imposes zero runtime cost; the CLI unpacks it on demand with workbook unbundle. See Source bundle for the wire format.

Security model

Every workbook is untrusted code. The runtime treats agent-authored, hand-authored, and CI-built workbooks identically. The required defences are:

• Cross-origin sandboxed iframe. The workbook runs in an iframe whose origin is distinct from the host page. Studio uses dedicated subdomains; run.workbooks.sh uses ephemeral per-file origins.
• Content Security Policy. A strict CSP is injected by the host. The workbook may connect-src outward only if it declared net.
• Permission gate. The host reads wb-permissions and confirms with the user on first run.

The com.apple.quarantine xattr is stripped by the legacy daemon after content-sniffing classifies a file as a workbook — the sandbox above is the trust call, not Gatekeeper. (The daemon is legacy; see the changelog.)

Versioning

The standard is versioned by the data-version attribute on the source-bundle tag (currently 1) and by SDK semver. Breaking changes to the runtime SDK ship majors; additive features ship minors. The HTML envelope itself is stable and won't change without a major bump and a migration path.