Linguaggi e compilatori

Silurus/ooxml: documenti Office con fedeltà al pixel, visualizzati nel browser

07 giugno 2026

Sintesi redazionale: URL dell'articolo: https://github.com/yukiyokotani/office-open-xml-viewer URL dei commenti: https://news.ycombinator.com/item?id=48436863 Punti: 54 # Commenti: 21. Fonte originale: https://github.com/yukiyokotani/office-open-xml-viewer

Note**This entire codebase — Rust parsers, TypeScript renderers, tests, and tooling — is implemented by AI coding agents, primarily Claude and Codex**, through iterative prompting. No human-written application code exists in this repository.**Why this project exists — a note from the author**OOXML's behavior is defined by a written specification (ECMA-376 / ISO-29500), and there is a clear answer to compare against: Word, Excel, and PowerPoint themselves. In principle, anyone with enough patience could have built a faithful viewer — the spec says what to implement, and the Office applications show whether you got it right.In practice, it didn't happen. For more than a decade, no free, open-source library reached a rendering quality good enough for real use. There are a few commercial libraries with decent fidelity (and editing support), but their pricing makes them hard to adopt casually. I think the reason is simply cost: the specification is huge, and reading and implementing it faithfully takes far more effort than volunteers can afford.Generative AI changed that. A viewer is an unusually good fit for AI-driven iterative development ("vibe coding"): there is a spec to read and a correct output to aim for, so the work comes down to interpreting the specification and refining the rendering until it matches. Limiting the scope to viewing also avoids the most serious risk an Office library can carry — corrupting a user's files.So I'm building this library with AI coding agents, spec-first, and keeping it free to use. For some documents it already reproduces the desktop Office applications more faithfully than commercial libraries — and sometimes even the official Microsoft 365 web apps.A browser-based viewer for Office Open XML documents that renders to an HTML Canvas element. The parsers are written in Rust and compiled to WebAssembly; the renderers use the Canvas 2D API. Each format also exposes a headless engine (`DocxDocument`/ `XlsxWorkbook`/ `PptxPresentation`) that renders into any caller-supplied canvas, so you can compose your own UI — scroll views, thumbnail grids, master-detail panes — instead of being locked into the built-in viewer. See the live framework examples for runnable React, Vue, Svelte, and Solid projects.This project is intentionally a **read-only viewer**. Editing interfaces, mutation APIs, editable or lossless document models, saving / round-tripping, and partial editing of DOCX, XLSX, or PPTX files are out of scope. Read-only interactions such as selection, copy, search, shape IDs, hit testing, and annotation or external-tool integrations remain in scope, and editing-focused forks are welcome. See #496 for the rationale.| DOCX | XLSX | PPTX | |---|---|---|``` npm install @silurus/ooxml # or pnpm add @silurus/ooxml ```Bundler note: the Rust parsers ship as real`.wasm`asset files next to the JavaScript, referenced with the standard`new URL('…', import.meta.url)`form and fetched (streaming-compiled) at load time. Verified to work with zero config:webpack 5,Next.js(Turbopack, dev and build),Vite 8(dev and build),Vite 7 production builds, and a plain`<script type="module">`with no bundler at all. Two setups need a hand:Vite 7 dev server: the dependency optimizer rewrites the asset reference into its own cache path and the load fails (fixed in Vite 8). Add`optimizeDeps: { exclude: ['@silurus/ooxml'] }`to your`vite.config`— production builds are unaffected.esbuild / Angular CLI(whose application builder is esbuild-based):`new URL`asset references are not processed (esbuild#795). Copy the`.wasm`into your served output and point the viewer at it with the`wasmUrl`load option. For Angular CLI, copy the required`*_parser_bg.wasm`asset from`node_modules/@silurus/ooxml/dist`into the served output and pass its public URL to the viewer.`wasmUrl`also serves the parser WASM from a CDN or any path you control:new DocxViewer(canvas, { wasmUrl: 'https://cdn.example.com/docx_parser_bg.wasm' });Bundle size note: the package is ESM-only (`.mjs`). npm'sUnpacked Sizeincludes every entry and optional asset, so it is not the size of a format-specific application graph. See the current production measurements on the stable Bundle size page. Import only the format and optional renderer entries your application needs. In main mode, MathJax, ChartEx, 3-D, Region Map and TIFF implementations remain outside the graph unless imported; the separately loaded worker asset is self-contained.``` import { DocxViewer } from '@silurus/ooxml/docx'; import { XlsxSheetViewer, XlsxViewer, XlsxWorkbook } from '@silurus/ooxml/xlsx'; import { PptxViewer } from '@silurus/ooxml/pptx'; // DOCX — caller provides the <canvas> const docxCanvas = document.getElementById('docx-canvas') as HTMLCanvasElement; const docx = new DocxViewer(docxCanvas); await docx.load('/document.docx'); docx.nextPage(); // XLSX — viewer manages its own <canvas> + tab bar const container = document.getElementById('xlsx-container') as HTMLElement; const xlsx = new XlsxViewer(container); await xlsx.load('/workbook.xlsx'); xlsx.setSelection('B2:D5'); // A1 strings describe geometry; the normalized upper-left is ActiveCell // Excel keeps Selection and ActiveCell separate. Use structured state when the // active cell or Shift-extension anchor is not the area's upper-left cell. xlsx.setSelection({ areas: [{ kind: 'cells', top: 2, left: 2, bottom: 5, right: 4 }], activeAreaIndex: 0, activeCell: { row: 3, col: 3 }, extensionAnchor: { row: 2, col: 2 }, }); // Read-only, serializable context for an AI/MCP request. Populated cells are // bounded and detached; formulas and Viewer-formatted display text are retained. const context = xlsx.getSelectionContext({ maxCells: 1_000, maxTextCharacters: 1_048_576, }); // XLSX active-sheet surface only — caller provides the <canvas> const sheetCanvas = document.getElementById('xlsx-canvas') as HTMLCanvasElement; const sheet = new XlsxSheetViewer(sheetCanvas); await sheet.load('/workbook.xlsx'); await sheet.goToSheet(1); // Share one parsed workbook across independently scrollable sheet canvases, // including canvases created in same-origin popup windows. const workbook = await XlsxWorkbook.load('/workbook.xlsx'); const firstCanvas = document.getElementById('xlsx-first-canvas') as HTMLCanvasElement; const secondCanvas = document.getElementById('xlsx-second-canvas') as HTMLCanvasElement; const firstSheet = XlsxSheetViewer.fromWorkbook(firstCanvas, workbook); const secondSheet = XlsxSheetViewer.fromWorkbook(secondCanvas, workbook); await Promise.all([ firstSheet.goToSheet(0), secondSheet.goToSheet(1), ]); // Each viewer borrows the workbook; the caller closes it after the viewers. firstSheet.destroy(); secondSheet.destroy(); workbook.destroy(); // PPTX — caller provides the <canvas> const pptxCanvas = document.getElementById('pptx-canvas') as HTMLCanvasElement; const pptx = new PptxViewer(pptxCanvas); await pptx.load('/deck.pptx'); pptx.nextSlide(); ````XlsxSheetViewer`also offers a deliberately small delimited-text preview convenience that reuses the Excel-style sheet surface. It has the same source and ownership lifecycle as XLSX loading: a string is fetched as a URL, an `ArrayBuffer`is caller-owned, a successful reload replaces and disposes the previous source, and `destroy()`releases the active source. There is no format auto-detection or general-purpose tabular model, and `XlsxWorkbook`/ `XlsxViewer`remain OOXML-only. Every delimited field stays text, so leading zeroes, long identifiers, dates, and `=...`values are displayed without type or formula inference. This convenience covers delimiter-based text regardless of filename extension; fixed-width PRN, DIF, and SYLK remain separate formats and are not parsed here.``` const csvFile = document.querySelector('input[type=file]') as HTMLInputElement; const csvBytes = await (csvFile.files?.[0] as File).arrayBuffer(); await sheet.load(csvBytes, { format: 'csv' }); // String sources are URLs, just like sheet.load('/workbook.xlsx'). await sheet.load('/export.tsv', { format: 'tsv', encoding: 'windows-1252' }); // Extensions such as .txt, .dat, and .psv do not imply one delimiter. await sheet.load('/report.dat', { format: 'delimited-text', delimiter: '|' }); ```OMML equations (`m:oMath`/ `m:oMathPara`) in `.docx`, `.pptx`and `.xlsx`are rendered with MathJax + STIX Two Math. That engine is ~4 MB, so it is **opt-in**: import the `math`engine from the separate `@silurus/ooxml/math`entry and pass it to the viewer. Pass it and equations render; omit it and the engine asset is not fetched or evaluated (equations are simply skipped; the on-demand render-worker asset retains a small loader). When you *do* pass it, the ~4 MB engine ships as a **standalone asset file** next to the bundle rather than an inline data URL, and is fetched **on demand — only the first time a document actually contains an equation**, so equation-free documents never pay for it. It is fully self-contained: served from your own origin, no cross-origin requests.Accented Latin letters use STIX Two Math paths in normal, italic, bold and bold-italic equations. Less common Cyrillic, phonetic and dingbat characters use a system-font fallback, so their appearance can vary by platform.``` import { DocxViewer } from '@silurus/ooxml/docx'; import { math } from '@silurus/ooxml/math'; const canvas = document.getElementById('docx-canvas') as HTMLCanvasElement; const docx = new DocxViewer(canvas, { math }); // ← equations now render await docx.load('/paper-with-equations.docx'); ```The same `math`engine works for every viewer (`DocxViewer`, `PptxViewer`, `XlsxViewer`) and every headless engine (`DocxDocument`, `PptxPresentation`, `XlsxWorkbook`). You inject it **once** where you create the object — the viewer constructor or the `.load()`options — and every render reuses it; it is never a per-render argument. (Excel stores "Insert > Equation" as OMML inside the shared DrawingML `<xdr:txBody>`grammar, so `XlsxViewer`renders equations embedded in shapes / text boxes the same way.)Legacy binary Office files can be read directly into the ordinary workbook and presentation models through **model sources**, a format-generic `modelSources`load option. The legacy readers are separate opt-in entries, one per format; each returns a model source for the matching loader or viewer:``` import { PptxViewer } from '@silurus/ooxml/pptx'; import { legacyPptSource } from '@silurus/ooxml/legacy-ppt'; const canvas = document.querySelector('canvas') as HTMLCanvasElement; const viewer = new PptxViewer(canvas, { modelSources: [legacyPptSource()] }); await viewer.load(pptOrPptxBytes); ````legacyXlsSource()`(`@silurus/ooxml/legacy-xls`) works the same way for XLSX. A source claims only its own binary family; every other input takes the unchanged OOXML path, and without a source a legacy file still rejects with the typed `legacy-binary-format`error. Creating a source fetches nothing: its self-contained source module and WASM load in the parser worker (or in Node) only when a claimed file is opened, and no OOXML package is generated. The readers are narrow and experimental and reject unsupported content rather than guessing; see Experimental legacy Office sources.Classic DrawingML 2-D chart families are included in every format entry. Microsoft ChartEx, model-space 3-D charts and offline country-level Region Maps are separate entries. TIFF decoding is also a separate entry shared by DOCX, XLSX and PPTX. Inject the modules once in the same load options object as `math`; omitting one keeps its main-mode implementation out of the ordinary format graph. The built-in modules work in both main and worker modes. Without `chartEx`, ChartEx families show the standard unsupported-chart placeholder. Without `threeD`, 3-D chart groups fall back to their canonical 2-D family. Without `regionMap`_(testo troncato)_