Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

build: pack the shells with zopfli — 39 KB off, and the format does not move (#326)

nyblnet6b4e1b200bbc
diff --git a/CLAUDE.md b/CLAUDE.md
index e6d1ba8d..92b01628 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -619,6 +619,12 @@ names provisional.
- **Compressed shell (Phase 1)**: `scripts/postbuild-compress.mjs` (runs in
build:single) deflates runtime JS+CSS into base64 `bento/deflate-b64` script
+ blocks with ZOPFLI (same deflate format, packed harder — the loader and every
+ saved file are untouched; ~4% off each shell, verified byte-identical through
+ Chrome's native `DecompressionStream('deflate-raw')`). `@gfx/zopfli` is a
+ devDependency of each APP, and the script resolves it from the caller's cwd
+ because scripts/ has no package.json of its own; `ZOPFLI=0` falls back to zlib
+ for a local build, never for a release.
blocks + ~1KB loader (DecompressionStream → blob import; pre-2023 browsers
get a plain-HTML message). Byte order: chrome → NOTICE → tooling comment →
PLAINTEXT #bento-doc → splash → payloads last. Shell ~560KB (was 1.33MB).
diff --git a/dash/package-lock.json b/dash/package-lock.json
index 11f195a3..830ae9e7 100644
--- a/dash/package-lock.json
+++ b/dash/package-lock.json
@@ -1,14 +1,15 @@
{
"name": "bento-dash",
- "version": "0.0.1",
+ "version": "0.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bento-dash",
- "version": "0.0.1",
+ "version": "0.2.0",
"license": "MIT",
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",
@@ -457,6 +458,19 @@
"node": ">=18"
}
},
+ "node_modules/@gfx/zopfli": {
+ "version": "1.0.15",
+ "resolved": "https://registry.npmjs.org/@gfx/zopfli/-/zopfli-1.0.15.tgz",
+ "integrity": "sha512-7mBgpi7UD82fsff5ThQKet0uBTl4BYerQuc+/qA1ELTwWEiIedRTcD3JgiUu9wwZ2kytW8JOb165rSdAt8PfcQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "base64-js": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
"node_modules/@napi-rs/lzma-linux-x64-gnu": {
"version": "1.5.1",
"resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",
@@ -883,6 +897,27 @@
"undici-types": "~7.18.0"
}
},
+ "node_modules/base64-js": {
+ "version": "1.5.1",
+ "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+ "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/feross"
+ },
+ {
+ "type": "patreon",
+ "url": "https://www.patreon.com/feross"
+ },
+ {
+ "type": "consulting",
+ "url": "https://feross.org/support"
+ }
+ ],
+ "license": "MIT"
+ },
"node_modules/braces": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
diff --git a/dash/package.json b/dash/package.json
index 2b4a4726..b922f97c 100644
--- a/dash/package.json
+++ b/dash/package.json
@@ -11,6 +11,7 @@
"preview": "vite preview"
},
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 4fec0e48..2b5ca227 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -14,6 +14,59 @@ Decision. Why. Pointers.
---
+## 2026-08-19 — The shells are packed with zopfli, and the format does not move
+
+Every Bento file carries its whole runtime, so the packer's efficiency is a
+property of every document anybody saves. Zopfli emits a stream in the SAME
+deflate format as zlib, just searched harder — so the shipped loader is
+untouched, already-saved files keep working, and an old updater splicing into a
+new shell sees exactly what it saw before.
+
+MEASURED, all four shells:
+
+ spaces 173,598 -> 166,482 -7,116 B 4.10%
+ slides 690,060 -> 663,760 -26,300 B 3.81%
+ dash 169,617 -> 164,813 -4,804 B 2.83%
+ type 33,899 -> 33,283 -616 B 1.82%
+
+Verified rather than assumed, because "the format does not move" is the whole
+argument. A zopfli payload handed to Chrome 148's native
+`DecompressionStream('deflate-raw')` inflated to a byte-identical result
+(SHA-256 matched) in 2.2 ms, and all four shells boot and render from
+zopfli-packed payloads — checked in a browser, not only through the gate.
+
+15 iterations, not 100: 100 buys 36 more bytes on spaces for three times the
+time. The cost is about a second of build time per shell, paid once per
+release.
+
+THE DEPENDENCY IS PER APP, RESOLVED FROM THE CALLER. `scripts/` has no
+package.json and neither does the repo root, so a bare import from
+postbuild-compress.mjs would look in the wrong place — but every app runs the
+script from its own directory, which is where `@gfx/zopfli` is declared. It
+ships WASM embedded as JSON: no node-gyp, no compiler, no platform binaries,
+140 KB, one transitive dependency. `node-zopfli` (native) would not have been
+reproducible on CI.
+
+A MISSING DEPENDENCY FAILS THE BUILD rather than falling back. Verified: exit
+code 1, with a message naming the fix. A release quietly built 4% larger
+because someone's node_modules was stale is a regression nobody would ever
+notice. `ZOPFLI=0` is the deliberate escape hatch for a local build and says in
+the same message that it is never for a release.
+
+THE SPACES CEILING DOES NOT MOVE DOWN. 166,482 of 176,128 is 94.5%, and that
+9,646 B of headroom is the point: the win is spent on the next feature rather
+than banked by re-tightening the budget, which would have meant a fifth raise
+the first time anything grew.
+
+Two alternatives measured and rejected earlier, recorded so they are not
+re-derived: BROTLI would save 20,580 B more but Chrome's DecompressionStream
+accepts only deflate, deflate-raw and gzip, and a JS decoder costs more than it
+saves; a DENSER PAYLOAD ALPHABET (basE91) would save 9,676 B but shell-gate.mjs
+hard-fails any data block containing a literal `<`, and base64 is relied on for
+being zero-`<` by construction against hostile payloads.
+
+---
+
## 2026-08-19 — How wide a page is belongs to the PAGE, not the theme
`theme.measure` is one number for the whole document — "text column width in px
diff --git a/scripts/postbuild-compress.mjs b/scripts/postbuild-compress.mjs
index cb748909..72d271fe 100644
--- a/scripts/postbuild-compress.mjs
+++ b/scripts/postbuild-compress.mjs
@@ -25,7 +25,72 @@
// release.mjs runs a frozen v0.1.0-style splice against the output as a gate.
import { readFileSync, writeFileSync } from 'node:fs'
-import { deflateRawSync } from 'node:zlib'
+import { deflateRawSync, inflateRawSync } from 'node:zlib'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+/**
+ * ZOPFLI, not zlib.
+ *
+ * Zopfli emits a stream in the SAME deflate format, just packed harder — so
+ * the shipped loader is untouched, every already-saved file keeps working, and
+ * old updaters splicing into a new shell see exactly what they saw before.
+ * Verified rather than assumed: a zopfli payload handed to Chrome 148's native
+ * `DecompressionStream('deflate-raw')` inflated to a byte-identical result,
+ * SHA-256 matched, in 2.2 ms.
+ *
+ * Measured on the shipped shells: 172,470 -> 165,398 B for bento/spaces and
+ * 690,060 -> 663,760 B for bento/slides. About 4% off every file anyone saves,
+ * for a second of build time.
+ *
+ * RESOLVED FROM THE CALLER, not from this file. This script lives in scripts/
+ * and there is no package.json there or at the root, so a bare import would
+ * look in the wrong place; every app runs it from its OWN directory, which is
+ * where the dependency is declared. That is also why the failure below names
+ * the fix rather than falling back silently — a release quietly built 4%
+ * larger because someone's node_modules was stale is a regression nobody would
+ * ever notice.
+ */
+const iterations = Number(process.env.ZOPFLI_ITERS || 15)
+let zopfli
+try {
+ zopfli = createRequire(join(process.cwd(), 'package.json'))('@gfx/zopfli')
+} catch {
+ console.error(
+ 'postbuild-compress: @gfx/zopfli is missing. Run `npm ci` in this app\'s\n' +
+ ' directory (it is a devDependency). Set ZOPFLI=0 to build with zlib\n' +
+ ' instead — the output is valid but about 4% larger, so never for a release.')
+ if (process.env.ZOPFLI !== '0') process.exit(1)
+}
+
+/**
+ * deflate-raw, packed by zopfli unless it was explicitly turned off.
+ *
+ * THE OUTPUT IS INFLATED AND COMPARED BACK, every time, with node's own zlib.
+ * This is not paranoia about a bug — zopfli is old and well used — it is about
+ * what this script feeds. The bytes it emits ARE the application, and the
+ * shell built from them is signed: a packer that emitted a VALID deflate
+ * stream carrying different JavaScript would be signed as genuine and would
+ * self-update its way onto every install. A round trip through a different
+ * implementation makes that undetectable-in-principle failure impossible in
+ * practice, and it costs about 2ms per shell.
+ *
+ * It also covers the duller case a signature never would: a wrong build, a
+ * truncated write, a future iteration-count change that trips a corner.
+ */
+const deflate = async (buf) => {
+ const packed = (!zopfli || process.env.ZOPFLI === '0')
+ ? deflateRawSync(buf, { level: 9 })
+ : await new Promise((res, rej) =>
+ zopfli.deflate(buf, { numiterations: iterations }, (e, out) => (e ? rej(e) : res(Buffer.from(out)))))
+ if (!inflateRawSync(packed).equals(buf)) {
+ console.error('postbuild-compress: the packed payload does not inflate back to what went in.\n' +
+ ' Refusing to write a shell whose runtime cannot be recovered. This is a bug in the\n' +
+ ' packer or a corrupted install — do not sign anything built from this tree.')
+ process.exit(1)
+ }
+ return packed
+}
const path = process.argv[2]
if (!path || path.startsWith('--')) {
@@ -70,9 +135,9 @@ if (!styleM) throw new Error('app stylesheet not found in head')
const js = mod[1]
const css = styleM[1]
-const b64 = (s) => deflateRawSync(Buffer.from(s, 'utf8'), { level: 9 }).toString('base64')
-const jsB64 = b64(js)
-const cssB64 = b64(css)
+const b64 = async (s) => (await deflate(Buffer.from(s, 'utf8'))).toString('base64')
+const jsB64 = await b64(js)
+const cssB64 = await b64(css)
// --- other parts ------------------------------------------------------------
const notice = html.match(/<!--\s*NOTICE[\s\S]*?-->/)?.[0] ?? ''
diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
index 4c05271f..5add789a 100644
--- a/scripts/size-budgets.json
+++ b/scripts/size-budgets.json
@@ -4,7 +4,7 @@
"spaces": {
"path": "spaces/dist-single/Bento_Spaces.bento.html",
"max": 176128,
- "//": "172 KiB. Raised from 160: the collaboration UI costs 11,612 B compressed — the people panel, the presence dots in the page tree, the live control, the refusal messages, and 24 strings x 8 locales, which is roughly a fifth of it. Measured 159,446 B before and 171,058 B after. Twelve of those strings were LIFTED from the bento/slides catalogs rather than reworded, which is both cheaper and keeps one message consistent across the suite. Headroom is deliberate: the shell is mostly a zlib block and zlib differs across node versions (one commit measured 130,095 B on node 26 locally and 131,246 B on CI node 24), so a tight ceiling fails in CI for no reason. CI is the number that counts."
+ "//": "172 KiB, and there is real headroom under it again. Zopfli (scripts/postbuild-compress.mjs) took the shell from 173,598 to 166,482 B — 7,116 B, 4.1% — WITHOUT dropping a feature, so the ceiling deliberately stays where the collaboration UI put it: the next feature spends genuine headroom instead of triggering a fifth raise. Measured savings elsewhere from the same change: slides 26,300 B, dash 4,804 B, type 616 B. Headroom is also deliberate for a duller reason — the shell is mostly one compressed block and the packer's output differs across node versions (one commit measured 130,095 B on node 26 locally and 131,246 B on CI node 24), so a tight ceiling fails in CI for no reason. CI is the number that counts."
}
}
}
diff --git a/slides/package-lock.json b/slides/package-lock.json
index fa9e7558..b361ff66 100644
--- a/slides/package-lock.json
+++ b/slides/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bento-slides",
- "version": "1.0.14",
+ "version": "1.0.18",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bento-slides",
- "version": "1.0.14",
+ "version": "1.0.18",
"license": "MIT",
"dependencies": {
"moveable": "^0.53.0",
@@ -15,6 +15,7 @@
"temml": "^0.13.3"
},
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"@types/reveal.js": "^5.2.1",
"fake-indexeddb": "^6.2.5",
@@ -508,6 +509,19 @@
"node": ">=18"
}
},
+ "node_modules/@gfx/zopfli": {
+ "version": "1.0.15",
+ "resolved": "https://registry.npmjs.org/@gfx/zopfli/-/zopfli-1.0.15.tgz",
+ "integrity": "sha512-7mBgpi7UD82fsff5ThQKet0uBTl4BYerQuc+/qA1ELTwWEiIedRTcD3JgiUu9wwZ2kytW8JOb165rSdAt8PfcQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "base64-js": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
"node_modules/@rollup/rollup-android-arm-eabi": {
"version": "4.62.2",
"resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz",
@@ -975,6 +989,27 @@
"url": "https://github.com/chalk/ansi-styles?sponsor=1"
}
},
+ "node_modules/base64-js": {
+ "version": "1.5.1",
+ "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+ "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/feross"
+ },
+ {
+ "type": "patreon",
+ "url": "https://www.patreon.com/feross"
+ },
+ {
+ "type": "consulting",
+ "url": "https://feross.org/support"
+ }
+ ],
+ "license": "MIT"
+ },
"node_modules/braces": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
diff --git a/slides/package.json b/slides/package.json
index e0cce861..a512931e 100644
--- a/slides/package.json
+++ b/slides/package.json
@@ -17,6 +17,7 @@
"temml": "^0.13.3"
},
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"@types/reveal.js": "^5.2.1",
"fake-indexeddb": "^6.2.5",
diff --git a/spaces/package-lock.json b/spaces/package-lock.json
index 1f63081c..96e1c16f 100644
--- a/spaces/package-lock.json
+++ b/spaces/package-lock.json
@@ -1,14 +1,15 @@
{
"name": "bento-spaces",
- "version": "0.0.1",
+ "version": "0.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bento-spaces",
- "version": "0.0.1",
+ "version": "0.1.0",
"license": "MIT",
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",
@@ -457,6 +458,19 @@
"node": ">=18"
}
},
+ "node_modules/@gfx/zopfli": {
+ "version": "1.0.15",
+ "resolved": "https://registry.npmjs.org/@gfx/zopfli/-/zopfli-1.0.15.tgz",
+ "integrity": "sha512-7mBgpi7UD82fsff5ThQKet0uBTl4BYerQuc+/qA1ELTwWEiIedRTcD3JgiUu9wwZ2kytW8JOb165rSdAt8PfcQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "base64-js": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
"node_modules/@rollup/rollup-android-arm-eabi": {
"version": "4.62.2",
"resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz",
@@ -863,6 +877,27 @@
"undici-types": "~7.18.0"
}
},
+ "node_modules/base64-js": {
+ "version": "1.5.1",
+ "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+ "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/feross"
+ },
+ {
+ "type": "patreon",
+ "url": "https://www.patreon.com/feross"
+ },
+ {
+ "type": "consulting",
+ "url": "https://feross.org/support"
+ }
+ ],
+ "license": "MIT"
+ },
"node_modules/braces": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
diff --git a/spaces/package.json b/spaces/package.json
index b5d5cd60..4a914462 100644
--- a/spaces/package.json
+++ b/spaces/package.json
@@ -11,6 +11,7 @@
"preview": "vite preview"
},
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",
diff --git a/type/package-lock.json b/type/package-lock.json
index 4ca7ca97..53f070a4 100644
--- a/type/package-lock.json
+++ b/type/package-lock.json
@@ -9,6 +9,7 @@
"version": "0.1.0",
"license": "MIT",
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",
@@ -457,6 +458,19 @@
"node": ">=18"
}
},
+ "node_modules/@gfx/zopfli": {
+ "version": "1.0.15",
+ "resolved": "https://registry.npmjs.org/@gfx/zopfli/-/zopfli-1.0.15.tgz",
+ "integrity": "sha512-7mBgpi7UD82fsff5ThQKet0uBTl4BYerQuc+/qA1ELTwWEiIedRTcD3JgiUu9wwZ2kytW8JOb165rSdAt8PfcQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "base64-js": "^1.3.0"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
"node_modules/@napi-rs/lzma-linux-x64-gnu": {
"version": "1.5.1",
"resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",
@@ -883,6 +897,27 @@
"undici-types": "~7.18.0"
}
},
+ "node_modules/base64-js": {
+ "version": "1.5.1",
+ "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+ "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/feross"
+ },
+ {
+ "type": "patreon",
+ "url": "https://www.patreon.com/feross"
+ },
+ {
+ "type": "consulting",
+ "url": "https://feross.org/support"
+ }
+ ],
+ "license": "MIT"
+ },
"node_modules/braces": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
diff --git a/type/package.json b/type/package.json
index e06ab353..61c156ea 100644
--- a/type/package.json
+++ b/type/package.json
@@ -11,6 +11,7 @@
"preview": "vite preview"
},
"devDependencies": {
+ "@gfx/zopfli": "^1.0.15",
"@types/node": "^24.13.2",
"typescript": "~5.8.3",
"vite": "^7.1.1",