@beyondwork/docx-react-component 1.0.22 → 1.0.23

package/README.md

@@ -1,14 +1,33 @@
+---
+title: React OOXML Office
+summary: Shipped docx package landing page and primary router into consumer, wrapper, agent, and maintainer documentation.
+audience: consumer, wrapper, agent, maintainer
+stability: main-path
+docRole: main-path
+canonical: true
+---
+
 # React OOXML Office
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-`@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.
+`@beyondwork/docx-react-component` is the shipped product in this repository: a fidelity-first React docx editor centered on `WordReviewEditor`.
+
+## Use This README For
+
+- confirming what is shipped today
+- installing the package
+- finding the right documentation lane quickly
+
+Do not use this README as the full package contract. The canonical consumer path starts in `docs/README.md`, `docs/reference/public-api.md`, and `docs/reference/integration-guide.md`.
+
+## Current Package Reality
 
-The broader repository is still evolving toward a layered `react-ooxml-office` platform, but the source reality is unchanged:
+The repository may also carry broader branch-local work, but the shipped contract today is still docx-first:
 
 - `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
+- `xlsx` is planned work, not part of the current package contract
+- `pdf` remains future work outside the current package boundary
 
 ## Install
 
@@ -54,12 +73,27 @@ 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
+The current shipped ESM exports include:
+
+- stable default entrypoints:
+  - `@beyondwork/docx-react-component`
+  - `@beyondwork/docx-react-component/public-types`
+  - `@beyondwork/docx-react-component/ui-tailwind`
+  - `@beyondwork/docx-react-component/legal`
+  - `@beyondwork/docx-react-component/compare`
+  - `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css`
+- advanced-supported subpaths for wrapper teams and package-adjacent integrations:
+  - `@beyondwork/docx-react-component/runtime/document-runtime`
+  - `@beyondwork/docx-react-component/io/docx-session`
+  - `@beyondwork/docx-react-component/core/commands/*`
+  - `@beyondwork/docx-react-component/core/selection/mapping`
+  - `@beyondwork/docx-react-component/core/state/editor-state`
+  - `@beyondwork/docx-react-component/ui-tailwind/editor-surface/search-plugin`
+- alias subpaths:
+  - `@beyondwork/docx-react-component/tailwind`
+  - `@beyondwork/docx-react-component/api/public-types`
+
+Use `docs/reference/public-api.md` and `docs/reference/public-api.manifest.json` for the current contract inventory and stability guidance.
 
 ## Product Contract
 
@@ -74,48 +108,56 @@ For the current shipped `docx` implementation, that specifically means:
 - preserve unsupported but preservable OOXML
 - remain editable in Word after export
 
-## Repository Direction
+For the normative API and host contract, use:
+
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
+- [`docs/reference/ooxml-compliance.md`](docs/reference/ooxml-compliance.md)
 
-This repo is broadening from the original docx-first editor into a layered shared-OOXML story:
+## Documentation Map
 
-- 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
+### Start Here
 
-The canonical shared-platform overview lives in `docs/architecture/platform/shared-openxml-editor-platform.md`.
+- [`docs/README.md`](docs/README.md)
 
-## Documentation Map
+### Main Consumer Path
+
+- [`docs/reference/quick-start.md`](docs/reference/quick-start.md)
+- [`docs/reference/consumer-matrix.md`](docs/reference/consumer-matrix.md)
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
+
+### Wrapper And Agent Path
+
+- [`docs/reference/consumer-matrix.md`](docs/reference/consumer-matrix.md)
+- [`docs/reference/agent-integration-guide.md`](docs/reference/agent-integration-guide.md)
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/service-wrapper-guidance.md`](docs/reference/service-wrapper-guidance.md)
+- [`docs/reference/agent-capability-map.md`](docs/reference/agent-capability-map.md)
+- [`docs/reference/agent-read-models-and-snapshots.md`](docs/reference/agent-read-models-and-snapshots.md)
+- [`docs/reference/agent-workflow-and-suggestions.md`](docs/reference/agent-workflow-and-suggestions.md)
+- [`docs/reference/scope-aware-selection-tooling.md`](docs/reference/scope-aware-selection-tooling.md)
+- [`docs/reference/editor-integration-style.md`](docs/reference/editor-integration-style.md)
+- [`docs/reference/beyondwork-runtime-environment.md`](docs/reference/beyondwork-runtime-environment.md)
 
-Start here:
+Wrapper and agent docs stay on `main`, but they are downstream integration guidance rather than the canonical package contract.
 
-- `AGENTS.md`
-- `DESIGN.md`
-- `docs/README.md`
-- `docs/roadmap.md`
-- `docs/plans/current-state.md`
-- `docs/plans/master-plan.md`
+Current integration honesty:
 
-Current shipped docx contracts:
+- the shipped React host surface is still `WordReviewEditor`
+- `showReviewPanel={false}` only hides the bundled review rail
+- a distinct public chromeless React surface is not yet shipped
 
-- `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`
+### Maintainer Path
 
-Shared platform and planned xlsx docs:
+- [`docs/maintainers/README.md`](docs/maintainers/README.md)
 
-- `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`
+Maintainer prompts, operator runbooks, and proof/closure material remain important, but they are not the first reading path for package consumers.
 
 ## 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
+- `pnpm pack --dry-run` is the baseline package proof
 - 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
@@ -129,6 +171,7 @@ Shared platform and planned xlsx docs:
 - 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
+- `node scripts/validate-docs-navigation.mjs` enforces the core docs catalog, required indexes, and frontmatter contract
 
 ## Guiding Principle
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -235,6 +235,7 @@ export interface TrackedChangeEntrySnapshot {
   label: string;
   status: "active" | "accepted" | "rejected" | "detached";
   actionability: "actionable" | "preserve-only";
+  storyTarget?: EditorStoryTarget;
   importedRevisionForm?:
     | "run-insertion"
     | "run-deletion"
@@ -552,6 +553,8 @@ export interface SurfaceTableCellSnapshot {
 
 export interface SurfaceTableRowSnapshot {
   cells: SurfaceTableCellSnapshot[];
+  gridBefore?: number;
+  gridAfter?: number;
   height?: number;
   heightRule?: "auto" | "atLeast" | "exact";
   isHeader?: boolean;
@@ -954,7 +957,8 @@ export interface WorkflowBlockedCommandReason {
     | "document_read_only"
     | "document_viewing_mode"
     | "protected_range"
-    | "unsupported_surface";
+    | "unsupported_surface"
+    | "suggesting_unsupported";
   message: string;
   scopeId?: string;
   workItemId?: string;
@@ -971,7 +975,13 @@ export interface WorkflowScopeSnapshot {
   blockedReasons: WorkflowBlockedCommandReason[];
 }
 
+export type EffectiveSelectionMode = WorkflowScopeMode | "blocked";
+
 export interface InteractionGuardSnapshot {
+  effectiveMode: EffectiveSelectionMode;
+  matchedScopeId?: string;
+  matchedScopeMode?: WorkflowScopeMode;
+  disabledReason?: string;
   blockedReasons: WorkflowBlockedCommandReason[];
 }
 
@@ -1064,6 +1074,36 @@ export interface WorkflowMarkupSnapshot {
   opaqueFragments: WorkflowOpaqueFragmentMarkup[];
 }
 
+export type HostAnnotationKind =
+  | "note"
+  | "scope_hint"
+  | "readonly_marker"
+  | "suggestion"
+  | "warning";
+
+export interface HostAnnotationItem {
+  annotationId: string;
+  kind: HostAnnotationKind;
+  label: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  detail?: string;
+  scopeMode?: WorkflowScopeMode;
+  severity?: "low" | "medium" | "high";
+  workItemId?: string;
+  provenance: "host";
+}
+
+export interface HostAnnotationOverlay {
+  overlayVersion: "host-annotation-overlay/1";
+  annotations: HostAnnotationItem[];
+}
+
+export interface HostAnnotationSnapshot {
+  totalCount: number;
+  annotations: HostAnnotationItem[];
+}
+
 export interface WorkflowCandidateRangeOptions {
   kinds?: WorkflowMarkupKind[];
   includeDetached?: boolean;
@@ -1177,6 +1217,17 @@ export type WordReviewEditorEvent =
       documentId: string;
       activeWorkItemId: string | null;
     }
+  | {
+      type: "host_annotation_overlay_changed";
+      documentId: string;
+      snapshot: HostAnnotationSnapshot;
+    }
+  | {
+      type: "change_authored";
+      documentId: string;
+      changeId: string;
+      kind: "insertion" | "deletion";
+    }
   | {
       type: "command_blocked";
       documentId: string;
@@ -1327,6 +1378,9 @@ export interface WordReviewEditorRef {
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
+  clearHostAnnotationOverlay(): void;
+  getHostAnnotationSnapshot(): HostAnnotationSnapshot;
   getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
   replaceWorkflowMarkupText(markupId: string, text: string): void;
 }
@@ -1346,6 +1400,7 @@ export interface WordReviewEditorProps {
   reviewMode?: "editing" | "review";
   markupDisplay?: "clean" | "simple" | "all";
   showReviewPanel?: boolean;
+  chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
   hostAdapter?: EditorHostAdapter;
   datastore?: EditorDatastoreAdapter;
   autosave?: AutosaveConfig;
@@ -1353,3 +1408,13 @@ export interface WordReviewEditorProps {
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
 }
+
+export interface WordReviewEditorChromeVisibility {
+  toolbar: boolean;
+  alerts: boolean;
+  selectionOverlay: boolean;
+  contextToolbars: boolean;
+  pageChrome: boolean;
+  statusBar: boolean;
+  reviewRail: boolean;
+}