React OOXML Office

@beyondwork/docx-react-component is the shipped product in this repository: WordReviewEditor, a fidelity-first React editor for legal-review-safe docx workflows. Waves 20 through 23 land live table editing, package distribution, validator-backed CI, and legal workflow helpers. Wave 24 is the next production-hardening packet.

The broader repository is still evolving toward a layered react-ooxml-office platform, but the source reality is unchanged:

• docx is the only implemented and shipped runtime contract
• xlsx is the next planned OOXML sibling
• pdf is future work and outside the first shared OOXML platform contract

Install

pnpm add @beyondwork/docx-react-component react react-dom tailwindcss \
  prosemirror-commands prosemirror-keymap prosemirror-model \
  prosemirror-state prosemirror-tables prosemirror-transform prosemirror-view

Current packaging truth:

• the package is ESM-only
• exports point at shipped TypeScript source entry points
• types and subpath types entries resolve to the shipped source-backed TypeScript contracts
• consumers need a bundler or runtime that can resolve .ts and .tsx ESM imports
• consumers should import @beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css once and provide a Tailwind v4 CSS pipeline for it
• package and source identifiers remain docx-first until a deliberate rename lands

Shipped Product

The primary shipped surface is:

import { WordReviewEditor } from "@beyondwork/docx-react-component";

<WordReviewEditor />

WordReviewEditor remains uncontrolled by default:

• host passes initialDocx, initialSessionState, or initialSnapshot, or provides hostAdapter.load() / datastore.load()
• runtime owns the live working session
• host receives events, warnings, errors, session state, compatibility snapshots, and exported artifacts

Persistence direction:

• EditorSessionState is the canonical host-facing live-session contract
• EditorHostAdapter is the preferred persistence boundary for load, saveSession, saveExport, and telemetry
• EditorDatastoreAdapter remains the legacy snapshot bridge for hosts that still persist PersistedEditorSnapshot

Snapshot/export note:

• when a session starts from a real .docx, persisted snapshots now carry embedded source-package provenance so later snapshot-origin .docx export can use the same package-backed exporter
• legacy snapshots without that provenance still load, but .docx export is intentionally blocked rather than falling back to a lossy minimal package

The current public ESM exports are:

• @beyondwork/docx-react-component -> WordReviewEditor
• @beyondwork/docx-react-component/public-types -> public TypeScript contracts
• @beyondwork/docx-react-component/ui-tailwind -> current Tailwind UI primitives
• @beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css -> shipped theme variables and Tailwind theme import

Product Contract

For every format the repo eventually ships, the standard is:

Open -> edit -> save -> reopen in the host application without damage.

For the current shipped docx implementation, that specifically means:

• open in recent Microsoft Word without repair prompts
• preserve supported content and review structures
• preserve unsupported but preservable OOXML
• remain editable in Word after export

Repository Direction

This repo is broadening from the original docx-first editor into a layered shared-OOXML story:

• shared platform concerns for package IO, preservation, diagnostics, and validation
• format-specific runtimes with explicit capability boundaries
• host-facing review and editing surfaces for each supported format

The canonical shared-platform overview lives in docs/architecture/platform/shared-openxml-editor-platform.md.

Documentation Map

Start here:

• AGENTS.md
• DESIGN.md
• docs/README.md
• docs/roadmap.md
• docs/plans/current-state.md
• docs/plans/master-plan.md

Current shipped docx contracts:

• docs/reference/public-api.md This doc separates the shipped Waves 20-23 surface from the future Waves 25 through 27 ref expansion.
• docs/reference/ooxml-compliance.md
• docs/reference/word-review-editor-frontend-architecture.md
• docs/reference/word-review-editor-ux-guide.md

Shared platform and planned xlsx docs:

• docs/architecture/platform/shared-openxml-editor-platform.md
• docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md
• docs/architecture/xlsx/canonical-workbook-model-and-commands.md
• docs/reference/xlsx/xlsx-ooxml-compliance.md
• docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md
• docs/xlsx-react/README.md

Packaging And Release

• .github/workflows/publish.yml publishes on v* tags after verifying the tag matches package.json
• pnpm pack --dry-run is the baseline package proof for this wave
• npm provenance is enabled in publishConfig and in the publish workflow invocation
• the published package currently ships source ESM entry points plus TypeScript source-backed types exports
• the Microsoft Open XML SDK remains CI/internal-service only, never part of the shipped browser runtime

Contribution Rules

• respect the runtime-owned state model
• do not bypass commands and transactions
• do not treat the DOM as canonical state
• do not silently drop unknown OOXML
• keep docs honest about shipped versus planned behavior
• add or extend fixtures for compatibility-critical changes
• bash scripts/validate-fixtures.sh now uses the Railway validator service and requires OPENXML_VALIDATOR_AUTH_TOKEN when hitting the public domain

Guiding Principle

This repo is not trying to become a generic office clone.

It is building fidelity-first office-document runtimes with explicit preservation and calm, reviewable UI.