Standard · Source bundle

The source travels inside the file.

Every workbook built with @work.books/cli embeds a gzipped snapshot of its source tree inside the artifact itself. Recipients run workbook unbundle <file> to recover the project and iterate. This is what makes a workbook forkable without infrastructure.

Why

A built HTML artifact is opaque — minified, bundled, hard to read. Without something extra, "send me the workbook" means "send me the compiled output, and separately, the source, and remember to keep them in sync." The source-bundle removes the separately.

Wire format

The bundle is a single <script> tag near the end of <body>: 

<script id="wb-source-bundle"
        type="application/x-workbook-source"
        data-format="json+gzip+base64"
        data-version="1"
        data-root-name="my-thing"
        data-file-count="42"
        data-bundle-size="14823"
        data-uncompressed-size="68421">BASE64_GZIP_JSON</script>

The type is intentionally not application/javascript — browsers ignore unknown script types entirely, so the embedded data has zero parse cost and zero DOM impact. It's data sitting next to the runtime, not part of it.

Manifest

After base64-decode + gunzip, the payload is JSON: 

{
  "version": 1,
  "createdAt": "2026-05-04T...",
  "rootName": "my-thing",
  "files": [
    { "path": "src/index.html", "content": "<base64>", "mode": 420 },
    { "path": "src/main.js",    "content": "<base64>", "mode": 420 }
  ]
}

Truncation

Files larger than maxFileBytes (5 MiB by default) get a { truncated: true, originalSize: N } marker instead of content. This keeps the artifact from ballooning when a project vendors binary blobs or large datasets. Override with workbook build --max-file-bytes 20M.

Unbundling

workbook unbundle my-workbook.html out/
ls out/

Path-traversal defence: entries with .., absolute paths, or null bytes are silently dropped. unbundle will never write outside the target directory.

Opting out

Pass --no-bundle to disable the source bundle for a build. The resulting file is still a valid workbook — just one that can't be unbundled. Useful when shipping a workbook that embeds proprietary logic you don't want recipients to read.

Pass --bundle-git to include the .git/ directory. Off by default because most authors don't want their commit history travelling with the artifact; handy for handoffs where you do.

Encryption. Encrypted-at-rest workbooks (the Signal product, sealed broker uploads) skip the source bundle by default — the artifact is opaque ciphertext, so there's no readable source to embed.
← PreviousThe standard