Architecture

One format engine, one shared rendering path, and a small lifecycle boundary for every host framework.

Separate format from presentation

The viewer imports the public ooxml-core/visio entry point. Parsing and document semantics stay in the sibling engine, so a future renderer or headless consumer does not need a UI dependency.

Document flow

1. A local File or byte buffer enters the viewer.
2. The core checks package structure and resource limits, then resolves the relevant parts.
3. Shapes, styles and cached geometry normalize into a typed model with diagnostics.
4. The shared SVG renderer draws a selected page, including supported background content.
5. The controller owns navigation, zoom, loading, selection and events.

Framework contract

mountViewer(host, options) creates the custom element and manages common event forwarding. Framework integrations should own only mount/update/unmount wiring. The same properties and events are declared in src/contract.ts.

• src/controller.ts: document/view state and latest-load-wins handling.
• src/render-svg.ts: geometry-to-SVG presentation and visual warnings.
• src/render-text.ts: browser text rendering and run styling.
• src/export-svg.ts: bounded static serialization through the shared renderer, with local raster resources and diagnostics.
• src/viewer-element.ts: shared browser view and controls.
• src/binding.ts: lifecycle, properties, events and cleanup.

The six native adapters in packages/bindings delegate to this surface. A behavior fixed in one wrapper must be checked across the others. Successful compilation alone does not verify a framework's runtime lifecycle.

Shared appearance

All framework hosts use the same custom element styling. Set --vv-background, --vv-surface, --vv-secondary, --vv-ink, --vv-muted, --vv-border, --vv-accent, and --vv-accent-soft on the host to fit your application. Keep text and control contrast accessible.

The playground and documentation share one local light/dark preference. An embedded live demo follows the containing page without replacing the document or resetting edits.

Safety boundaries

• No raw document XML or HTML is inserted into the DOM. SVG elements are created through DOM APIs, and text is assigned as text.
• No document uploads, telemetry, or remote-document fetch API.
• ZIP/XML limits and relationship checks belong to the core. These are defenses, not a claim of complete security certification.
• Unimplemented visual features generate diagnostics where detected; warnings are not exhaustive.
• Experimental source-backed local plain-text edits run in an isolated worker and use bounded undo/redo history. Opening a file does not modify it; VSDX copies download only through an explicit action. Core rejects master-linked/rich text, fields, signed and macro packages. Formula caches are not recalculated, and native Visio reopening remains unverified.

Testing layers

Site architecture

The documentation is a lightweight static, multi-page Vite site. Relative links and bundled local assets allow it to run under a repository-prefixed path. It uses system fonts and no third-party scripts or font requests. The home embeds one same-origin playground only after you choose Load live demo. The preview illustration is distinct from the actual shared component; your files open only when you select or drop them.

The visual structure takes inspiration from pptx-viewer: warm paper and rust colors, a dot-grid hero, an embedded live playground, monospaced controls, framework quickstart, and task-oriented documentation. Light and dark modes share the same preference with the application. The local review in docs/research/pptx-pages-design-review.md records the detailed findings.

Publication is separate

The seven npm packages ship the shared viewer and native framework adapters over the released ooxml-core/visio API. The release workflow validates packed consumers and browser behavior before publishing with provenance. The GitHub Pages workflow deploys the verified demo.