feat(wasm): render documents in the browser, with no server

[andiwand]

opendocument.app is a page that links to the apps. This makes it able to open
a document — rendered in the browser, no upload, no server, nothing to operate,
and the bytes never leave the machine.

Most of the work was already done. Every renderer writes to a stream, the css
and js are compiled into the library since #648, and one view already comes out
as a complete self-contained document with no fetch in it. So this is the
toolchain, the binding and the package, not new rendering.

Draft because two things need a human decision — see the end.

What it looks like

import { Odr } from '@opendocument/odr-core';

const odr = await Odr.load();
const doc = odr.open(new Uint8Array(await file.arrayBuffer()));
try {
  const { html } = doc.render(0);
  iframe.src = URL.createObjectURL(new Blob([html], { type: 'text/html' }));
} finally {
  doc.close();
}

A blob: iframe keeps the same origin, so the page can still reach
iframe.contentWindow.odr and drive search() / generateDiff() — the same
host API droid and ios use from their WebViews.

Measured, not argued about

Every dependency cross-compiles, cryptopp unpatched. This was the risk that
could have sunk the approach: the recipe has no Emscripten branch and probes CPU
features by compiling assembly. CRYPTOPP_DISABLE_ASM turned out not to be
needed, so #655's removal of conan-odr-index stands.

Output is byte-identical to the native build across odt, docx, ods, xlsx,
odp, pptx, doc, xls, ppt, pdf, odg, csv and txt, and for encrypted docx/ods/odt
with their passwords — which exercises the cryptopp AES/PBKDF2 path and the
in-tree argon2id. One diff -r covers endianness, float formatting, hash
ordering and locale drift, so it is now a CI step with a known-good baseline
rather than an aspiration.

Size is a non-issue. 2.9 M raw, 831 K brotli, at -O3 before any
tuning. That is the whole library — every engine, PDF, crypto. It retires the
contingency plan to split PDF into a lazily loaded second bundle, so no
per-format compile-time gating is introduced. CI ratchets at 1.5 M brotli.
-Oz and -flto are still untried.

The stack

Everything that is useful without wasm was split out and has now landed, so this
PR sits directly on main and what is left in it is the toolchain, the binding
and the package:

#662 ✅ merged	feat(api) open a file from memory, and take a File wherever a path is taken
#663 ✅ merged	feat(html) translate without a cache path
#664 ✅ merged	refactor(csv) scan for csv in-tree, dropping vincentlaucsb-csv-parser
this	build(wasm) emscripten conan profile · feat(wasm) embind bindings, packaged for npm · ci(wasm) build, test and publish

Why each of those had to come first, since it is no longer visible from the
branch: #662 is what gives a browser a way in at all — it has an ArrayBuffer
and no path, and internal::MemoryFile existed but binding the internals is
what the bindings are told not to do. #663 makes "no renderer writes to disk"
structural rather than coincidental, which is what lets this build skip a MEMFS
mount entirely. #664 removes the last thread in the library — CSVReader::begin()
constructed a std::thread and immediately joined it, with no way to switch it
off — and that matters here because -pthread implies SharedArrayBuffer, which
implies COOP/COEP headers on whoever hosts the viewer, which rules out plain
GitHub Pages.

feat(wasm) — the binding

Three things are unlike python/jni/apple, all following from the binding being
driven from a Web Worker where everything crossing is structured-cloned:

• Nothing throws across the boundary. Entry points return
  {ok, value | error}. The worker protocol has to serialise failures anyway,
  and an unconverted C++ exception reaches JS as an opaque pointer.
  js/index.js turns envelopes back into thrown OdrErrors, so only the wire
  carries them.
• Nothing escapes as an embind handle, because a bound wrapper cannot be
  cloned. A document is a uint32_t into a registry. This also dissolves the
  keep-alive problem the other three each hand-built: HtmlView holds a bare
  pointer into its service and Element into the document adapter, and neither
  is ever handed out — Session owns file, service and views together.
• Config crosses as a plain object, same reason.

Enums are derived where the library has a runtime table (FileType,
FileCategory, DocumentType) so they cannot drift, and pinned by a snapshot
test where it does not. Appending stays silent, reordering goes loud — the rule
the headers state and that every binding so far left to hope.

The package is plain JavaScript with a hand-written .d.ts: a TypeScript source
tree would drag tsc and a build step into a C++ repository to produce one file
of declarations.

Testing

• Native suite green: 762 passed, 9 skipped, same skip list as before.
• 26 node tests via ctest. Inputs are built in memory — including a
  hand-rolled zip writer for a minimal odt — following python/AGENTS.md; the
  two fixtures on disk are a document with real layout and an encrypted one.
• The lifetime cases are the point of that suite: use-after-close, double close,
  and that a handle survives structuredClone while the wrapper silently does
  not.
• The packed tarball was installed into a clean project and rendered a document.

Two of my own tests failed and were right to. Random bytes open as text, not
an error — text is the fallback, so a viewer shows junk rather than refusing.
And structuredClone(document) does not throw, it yields {} — silently
useless, which is worse than throwing. Both are now pinned as documented
behaviour. A third failure was a real bug: the logger never reached the decode
path.

CI is green on the rebased branch: the wasm build, the node suite, the
byte-identical render comparison and the size ratchet all pass against the
merged main.

One decision before this leaves draft

conan.lock has no emsdk entry, so the wasm profile needs
--lockfile-partial. Adding it properly means a lockfile regen, which drifts
unrelated pins — worth doing deliberately rather than in passing.

The npm scope is settled: @opendocument is ours, reserved by the npm account
of the same name, so wasm/js/package.json needs no change. Publishing is
gated only on the first manual publish, which is what makes npm expose the
trusted-publisher settings a package needs.

Also worth a look: wasm/AGENTS.md states the three rules above as the contract
for anyone touching this next, and records what the spike measured so the
numbers do not have to be rediscovered.

The viewer itself belongs in its own repository and is not here.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64b791c776

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".