@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/xlsx-react/spreadsheet-editor-frontend-architecture.md

@@ -1,537 +0,0 @@
-# Spreadsheet Editor — Frontend Architecture
-
-This research paper is source material.
-
-Canonical repo-aligned planned doc:
-
-- `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md`
-
-## Interpretation of the problem
-
-You’re building an XLSX sibling to an existing React OOXML DOCX editor, and you want comparable architectural rigor and product honesty: one embeddable React component, a runtime-owned canonical workbook state, and a typed public API surface. The UI must be a projection of runtime state—React is a subscriber and dispatcher only—mirroring the runtime/UI boundary and “render snapshot vs persisted snapshot” split used in the DOCX editor architecture.
-
-The central correctness constraints are: treat `.xlsx` as an OOXML/Open Packaging Conventions (OPC) package (parts + relationships + content types), not as “some XML files”; ensure all mutations flow through commands → transactions → commit; never silently drop unsupported-but-preservable content; and make host behavior the ultimate spec (exported files reopen in modern Excel without repair prompts or silent, *supported-content* loss).
-
-This document therefore defines an implementation-ready frontend architecture: module boundaries, runtime state model, command/transaction pipeline, virtualization strategy, selection + decoration model, theming, trust surfaces, accessibility, responsive behavior, test matrices, fixtures, and release gates—explicitly distinguishing spec-level correctness from observed Excel behavior.
-
-## Research plan
-
-The research focused on five non-negotiable information needs.
-
-First, mirror proven architectural seams from the DOCX editor: runtime contracts, render-snapshot vs persisted-snapshot boundary, module dependency rules, preservation rules, capability derivation, and UX composition patterns.
-
-Second, establish normative package-level truths: OPC’s content types stream, relationships parts, part naming/relationship discovery model, and markup compatibility (forward-compatibility) mechanisms that affect “preserve unknown content” design.
-
-Third, establish SpreadsheetML core structures needed for safe import → edit → export: workbook/worksheets part relationships, shared strings, styles part semantics, merged-cell semantics, and calculation-related parts.
-
-Fourth, collect observed Excel behavior and practical constraints that affect editor honesty and export safety (e.g., calculation chain being a cache, and “recalculate on open” settings).
-
-Fifth, define interaction and platform constraints for a grid editor: accessibility expectations for a spreadsheet-like grid, clipboard event boundaries, and performance implications of Excel’s grid limits (over 17 billion addressable cells).
-
-## Findings
-
-**Normative: `.xlsx` is an OPC package, not “XML files.”** OPC requires a content types stream (`[Content_Types].xml`) mapping part names/extensions to MIME content types, and relationship parts (e.g., `/_rels/.rels` and per-part `*_rels/*.rels`) used to discover and traverse parts via relationship graphs. The canonical implication for an editor is that correctness is primarily **package-level**: you must preserve/repair relationships, content type overrides, and untouched parts, not only rewrite `xl/worksheets/sheet1.xml`.
-
-**Normative: markup compatibility exists to support forward compatibility.** ISO/OOXML markup compatibility defines conventions like “ignorable namespaces,” “process content,” and “must understand,” enabling newer producers and older consumers to interoperate without losing essential data. For an editor, this means unknown/extensible markup is not exceptional; it’s expected—and must be preserved with explicit user-facing classification rather than dropped or flattened.
-
-**SpreadsheetML structure is workbook-centric with per-sheet parts.** Microsoft’s Open XML guidance describes a SpreadsheetML document as a workbook (`<workbook/>`) referencing sheets (`<sheets/>` / `<sheet/>`), with a distinct XML part per worksheet. This maps cleanly to runtime design: workbook metadata and cross-sheet registries (styles, shared strings, name definitions, calculation settings) belong at the workbook layer; sheet grids are separate sparse stores, loaded and rendered independently.
-
-**Shared strings and styles are global performance/consistency structures.** SpreadsheetML often stores repeated strings in a shared string table (`sharedStrings.xml`), with cells referencing strings by index; Excel typically writes a shared string table, but valid documents can also use inline strings in sheet cells. Cell formatting is stored primarily in a workbook-level Styles part (`styles.xml`) that contains collections for number formats, fonts, fills, borders, and cell format records—separate from sheet content—so the editor must treat styles as a global catalog with stable indices and preserve unknown style subtrees.
-
-**Merged cells have “top-left owns value” semantics that affect rendering and editing.** The SpreadsheetML merge model expresses merged ranges via `mergeCells/mergeCell ref="A1:B2"`; the merged range’s content and formatting are stored in the top-left cell, and that reality must be enforced by the editor’s canonical model and UI hit-testing.
-
-**Calculation chain is a cache; it’s not required for correctness, and it’s commonly inconsistent in the wild.** Microsoft’s Office file format specs describe the calculation chain as an application-specific cache that can be rebuilt and even recommends packages not contain it; it must appear at most once if present and is the target of an implicit relationship from the workbook. The Open XML SDK includes an explicit helper to ignore missing `CalculationChainPart` relationships—strong evidence you must tolerate “workbook has relationship but part missing” scenarios without failing import.
-
-**Excel’s grid limits force virtualization and “sparse truth.”** Excel supports 1,048,576 rows and 16,384 columns per sheet, i.e., an address space far beyond what any DOM-based “render the grid” approach can manage. Any serious editor must: (a) store sheets sparsely, (b) virtualize both axes, and (c) avoid React-per-cell ownership of canonical cell state.
-
-**Excel has two comment systems with different UX expectations.** Excel distinguishes threaded comments (discussion-oriented) from notes (legacy, annotation-oriented). This matters for format scope: if you can’t safely round-trip *both* comment systems, you must treat the unsupported one as preserve-only (display/lock/warn) rather than “best-effort edit” that risks rewriting incompatible parts.
-
-**Accessibility for a spreadsheet UI maps to the WAI-ARIA grid pattern.** W3C ARIA guidance explicitly calls out grids as suitable for spreadsheet-like applications and describes required keyboard interaction and focus-management properties (single tab stop into the grid, arrow navigation, home/end/page keys, selection expansion). This pushes architecture toward a single focusable grid surface with roving internal focus and an imperative interaction layer that coordinates selection, editing mode, and announcements.
-
-**Clipboard integration is constrained by browser event APIs.** Clipboard operations flow through `copy/cut/paste` events, where `ClipboardEvent.clipboardData` exposes a `DataTransfer` object for reading/writing MIME-typed payloads. Consequently, spreadsheet clipboard boundaries must be defined in terms of `text/plain` and (optionally) `text/html` payloads, with strict sanitization and explicit “blocked/preserve-only” behavior when formats can’t be interpreted safely.
-
-## Recommended design / decisions
-
-**Adopt the DOCX editor’s hard boundary: runtime owns truth; React subscribes via an external-store interface.** Implement `SpreadsheetRuntime` as the single mutation authority and make the React component a projection and command dispatcher only, using the `subscribe/getSnapshot` pattern that React formalizes via `useSyncExternalStore`.
-
-**Preserve the “two snapshots” discipline: render snapshot vs persisted snapshot.** Maintain (a) `RuntimeRenderSnapshot` for UI convenience and command enablement and (b) `PersistedWorkbookSnapshot` as the sole durable host artifact, mirroring the DOCX editor contract. This prevents React-friendly denormalizations (e.g., flattened visible cells) from becoming accidental persistence truth.
-
-**Make OPC package preservation a first-class subsystem, not an import/export afterthought.** Treat import as “package → canonical workbook + preservation manifest + compatibility report,” and export as “canonical diffs → regenerate owned parts + reattach preserved parts + validate.” This directly mirrors the DOCX editor’s component boundary rules and explicit preservation subsystem.
-
-**Define an explicit response model per feature region: preserve, lock, warn, block, fail.** Keep the DOCX editor’s taxonomy (`supported-roundtrip`, `preserve-only`, `unsupported-fatal`) as the underlying classification and expose it through UI surfaces and export gates. This yields predictable behavior: preserve-only content is retained and visible but non-editable; unsupported-fatal blocks export (or even blocks editing) with explicit reporting.
-
-**Choose an imperative grid surface for performance and correctness, with React rendering only chrome and overlays.** Given Excel’s grid limits and ARIA grid keyboard requirements, the central grid should be driven by a framework-agnostic `GridSurfaceController` that handles scrolling, hit-testing, selection, editing mode, and clipboard, while React renders (a) the container layout, (b) sheet tabs, (c) formula bar/name box, (d) side panels, and (e) lightweight overlay layers.
-
-**Virtualization must support variable row heights and column widths.** SpreadsheetML supports per-row and per-column sizing (and merges complicate layout), so implement bi-directional virtualization using prefix-sum structures (Fenwick tree / segment tree) for fast “pixel offset → row index” mapping and overscan. This is required to stay responsive as sheet sizes approach Excel’s limits and as users scroll rapidly.
-
-**Treat calculation/calcChain as a compatibility boundary, not “just compute.”** Normatively, `calcChain` is at most one part and is a cache that can be rebuilt; practically, files may contain broken calcChain relationships, so import must tolerate those. Export policy should default to not maintaining `calcChain` (or regenerating only when fully correct) and instead rely on workbook calculation settings (e.g., `calcPr` flags) to force recalculation on open when your runtime cannot guarantee cached results; this must be labeled as observed Excel behavior and gated by tests.
-
-**Merged cells must be enforced at the model and UI layers.** Canonical sheet state must encode merge regions as a sheet-level structure; editing and selection logic must map all cells in a merge to the merge’s anchor cell (top-left semantics) and block unsafe operations that would split a merge without explicit user intent.
-
-**Comments and notes: be honest, pick a v1 authoring target, and preserve the rest.** Excel’s UX and semantics differ substantially between threaded comments and notes. If you cannot safely author both formats end-to-end, explicitly designate one as `supported-roundtrip` and the other as `preserve-only` with display/lock/warn behavior, plus a health panel explanation.
-
-**Session capability derivation must be pure and runtime-driven.** Mirror the DOCX editor’s `deriveCapabilities()` approach: compute `SessionCapabilities` solely from the render snapshot + host props (permissions), and never let UI components invent capability state locally.
-
-## Risks and open questions
-
-**Formula correctness is the biggest “don’t lie” cliff.** Spreadsheet formulas include shared formulas, array formulas, data tables, and table formulas; even the Open XML types describe shared formula grouping semantics via `t="shared"` and `si` indices. If the runtime cannot (a) parse formulas, (b) update dependencies and references under structural edits, and (c) export without corrupting shared-formula groups, you must classify formula editing as preserve-only (or unsupported-fatal for certain constructs). The same applies to recalculation flags: turning on `fullCalcOnLoad` is a common pragmatic strategy, but it is not a substitute for correct reference rewriting.
-
-**OPC/package preservation is easy to get subtly wrong.** Even small relationship or content type mistakes can trigger Excel “repair” prompts or silent removal of parts. OPC’s discovery model and MCE’s forward-compatibility constructs imply you will see unknown parts/markup routinely; designing preservation late will force destructive export logic.
-
-**Comments format split is a product decision with long tail.** Excel’s own guidance frames threaded comments and notes as distinct features with different UI behaviors and capabilities. Supporting only one for authoring is defensible, but you must invest in first-class preserve-only UI, otherwise users will feel “content disappeared” even if it’s technically preserved.
-
-**Large-grid performance failures will surface as UX correctness bugs.** With a 1,048,576 × 16,384 address space, selection, scrolling, and hit-testing must not be O(N) in row/col count, and React must not re-render the world on scroll. This is architectural: if you start with React-per-cell, you will end up rewriting the core renderer.
-
-**Open questions that must be resolved before committing to v1 scope gates:**
-- Which Excel feature set is “supported-roundtrip” vs “preserve-only” vs “unsupported-fatal” for import → edit → export → reopen? This must be codified as a capability matrix and enforced by validation + export gates.
-- Do you require in-browser formula evaluation, or is “edit formulas + force recalc on open” acceptable for your product tier? If the latter, you must still correctly rewrite references under structural edits or block those edits.
-- Which comment system is the authoring target? Threaded comments are the modern default in many Excel contexts, but notes have simpler semantics.
-
-## Concrete deliverable in the requested format
-
-This section is the repo-ready architecture specification for implementing the spreadsheet editor UX and runtime as **one embeddable React component** with a **runtime-owned canonical workbook state**, **command/transaction commits**, and **package-first OOXML preservation**.
-
-### Rendering stack
-
-**Goals:** keep the grid fast, keep React honest, keep accessibility tractable, and keep theming portable.
-
-**Stack recommendation:**
-- React shell: layout composition, panels, toolbar/formula bar, tabs, dialogs, theming provider.
-- Imperative grid surface: one focusable “grid viewport” element implementing ARIA grid keyboard behavior (roving focus, editing mode) and managing virtualization/core interaction.
-- Overlay layers: selection rectangle(s), active cell outline, range highlights, comment indicators, fill-handle, drag selection preview.
-- Styling: CSS custom properties (tokens) scoped under the component root; optional shadow-root isolation in later phases (same overall approach as the DOCX editor frontend architecture).
-
-### Directory structure
-
-Mirror the DOCX editor’s module boundary discipline (api/model/core/io/preservation/validation/runtime/ui), but specialize “core” into spreadsheet domains (grid, formula, styles).
-
-```text
-src/
-api/                 # public contract types only (no runtime imports)
-model/               # canonical workbook model + scalar types (JSON-serializable)
-core/
-commands/          # command handlers -> transactions
-transactions/      # step types, mapping, commit invariants
-selection/         # selection + anchor models (cell/range)
-grid-math/         # A1 addressing, row/col index math, merge math
-styles/            # style catalog + resolution
-formulas/          # formula AST, reference rewriting, dependency graph (scoped)
-io/
-opc/               # package reader/writer (zip, [Content_Types], rels)
-xlsx/              # SpreadsheetML parse/serialize (workbook, sheets, sst, styles)
-normalize/         # translate OOXML -> canonical model + preservation capture
-export/            # canonical model -> SpreadsheetML + package patch plan
-preservation/
-store/             # preserved parts, rels, unknown markup, fragment registry
-mce/               # markup compatibility handling (mc:Ignorable etc) policy
-validation/
-compatibility/     # feature classifier + report builder
-excel/             # Excel-focused structural checks + export gates
-runtime/
-spreadsheet-runtime.ts     # orchestrator: load/import/export, commands, undo/redo
-session-capabilities.ts    # deriveCapabilities(snapshot, props)
-scheduler.ts               # yielding, staging, budgets
-ui/
-react/             # React shell components (tabs, bars, panels) no “truth”
-headless/          # framework-agnostic interaction models (clipboard parsing, etc.)
-grid-surface/      # imperative surface controller + adapters
-grid-surface-controller.ts
-virtualization.ts
-dom-adapter.ts
-aria-grid.ts
-test/
-fixtures/
-xlsx/              # source Excel files (golden fixtures)
-snapshots/         # persisted snapshots (golden JSON)
-export/            # expected exported artifacts / normalization
-harness/
-excel-open-notes/  # manual reopen notes & screenshots (release gate evidence)
-```
-
-Dependency rules should match DOCX boundaries: `src/api` imports nothing; `src/model` imports only `src/api`; `src/ui` must not import `src/io/preservation/validation`; only `runtime` orchestrates them.
-
-### Component hierarchy
-
-The React component hierarchy must not imply ownership of workbook truth; it should be “UI shell around runtime snapshots,” similar to the DOCX editor’s tailwind architecture composition.
-
-```text
-<SpreadsheetEditor />   (public component)
-  <EditorThemeRoot>     (CSS vars + dark/high-contrast toggles)
-    <TopBar>
-      <NameBox />       (A1/name input; transient input state only)
-      <FormulaBar />    (transient text+IME state; commits via runtime)
-      <Toolbar />       (command dispatch only)
-    <MainArea>
-      <GridViewportShell>
-        <GridSurfaceHost />     (mount point for imperative GridSurfaceController)
-        <GridOverlays />        (React overlay render from snapshot+selection)
-      <RightRail>               (optional)
-        <HealthPanel />         (preserve-only + blocked UI)
-        <CommentsPanel />       (notes/comments list; uses runtime projections)
-        <NameManagerPanel />    (optional; driven by runtime state)
-    <SheetTabs />        (sheet switching/rename/add; command dispatch)
-    <StatusBar />        (dirty/export blocked/latency budgets)
-```
-
-### Data flow
-
-**One-way control flow is mandatory:**
-1) React inputs (keyboard/mouse/paste/UI controls) call runtime entry points.
-2) Runtime executes command → builds transaction → commits → remaps anchors.
-3) Runtime notifies subscribers (React) by publishing a new immutable render snapshot.
-4) React re-renders chrome and overlays; the grid surface reconciles visible cells using the snapshot and its own transient viewport state.
-
-Use the external store subscription pattern: `useSyncExternalStore(runtime.subscribe, runtime.getRenderSnapshot)`.
-
-### Editing model
-
-**Core principle:** spreadsheet editing is not rich text. The canonical modellable actions are **cell/range mutations** and **structural sheet mutations**, and they must be captured as transactional steps with remapping and undo/redo semantics.
-
-**Editing states (runtime-owned where it matters):**
-- `selection`: active cell + selection ranges + editing mode (`view` vs `edit`).
-- `editBuffer` (transient): current in-progress cell editor text/IME composition; this may live in UI as transient, but the runtime must be the authority on when a buffer becomes a committed value/formula. (Same concept as “UI local state is transient,” used in the DOCX frontend architecture.)
-- `gridViewport` (transient UI runtime): scroll offsets, overscan window; must not duplicate workbook state.
-
-**Commit semantics:**
-- Typing in the grid in “view mode” starts an editor buffer for the active cell; buffer is owned by a `CellEditorController` associated with the imperative surface, but commits exclusively via `runtime.dispatch(command)`.
-- Enter commits and moves selection (down by default); Tab commits and moves right; Escape cancels buffer without state change.
-- Formula bar editing uses the same buffer/commit path; it should not bypass grid editing rules.
-
-### Command → transaction → commit architecture
-
-Mirror the DOCX runtime’s “every mutating entry point routes through command → transaction → mapping → remap → commit → notify” rule, but adapt mapping to grid coordinates and sheet topology.
-
-#### Public runtime signatures (sketch)
-
-```ts
-export interface SpreadsheetEditorProps {
-workbookId: string;
-currentUser?: { userId: string; displayName: string };
-
-initialXlsx?: Uint8Array | ArrayBuffer;
-initialSnapshot?: PersistedWorkbookSnapshot;
-
-readOnly?: boolean;
-
-onEvent?: (e: SpreadsheetEditorEvent) => void;
-onWarning?: (w: EditorWarning) => void;
-onError?: (err: EditorError) => void;
-
-theme?: Partial<SpreadsheetThemeTokens>;
-colorScheme?: "light" | "dark" | "system";
-}
-
-export interface SpreadsheetEditorRef {
-focusGrid(): void;
-
-undo(): void;
-redo(): void;
-
-exportXlsx(options?: ExportXlsxOptions): Promise<ExportResult>;
-getSnapshot(): PersistedWorkbookSnapshot;
-
-getCompatibilityReport(): CompatibilityReport;
-getWarnings(): EditorWarning[];
-}
-```
-
-This intentionally matches the DOCX contract style: uncontrolled by default, replace-on-change allowed only as full runtime reload; persisted snapshot is host artifact; render snapshot is internal.
-
-#### Canonical transaction step types (minimum viable)
-
-Transactions must be deterministic and must carry a **mapping** that can remap:
-- selection anchors (cell/range),
-- comments anchors (cell/range),
-- preservation bindings (parts tied to a sheet/range),
-- named ranges (if you support authoring them).
-
-```ts
-type SheetId = string;
-
-type GridCoord = { row: number; col: number };       // 1-based (Excel semantics)
-type GridRef = { sheetId: SheetId; at: GridCoord };
-type GridRange = { sheetId: SheetId; from: GridCoord; to: GridCoord };
-
-type TransactionStep =
-  | { type: "cell.setValue"; ref: GridRef; value: CellValue }
-  | { type: "cell.setFormula"; ref: GridRef; formula: FormulaText; cachedValue?: CellValue }
-  | { type: "cell.setStyle"; range: GridRange; xfId: number }      // style index into style catalog
-  | { type: "sheet.insertRows"; sheetId: SheetId; atRow: number; count: number }
-  | { type: "sheet.deleteRows"; sheetId: SheetId; atRow: number; count: number }
-  | { type: "sheet.insertCols"; sheetId: SheetId; atCol: number; count: number }
-  | { type: "sheet.deleteCols"; sheetId: SheetId; atCol: number; count: number }
-  | { type: "range.move"; from: GridRange; toTopLeft: GridCoord; mode: "move" | "copy" }
-  | { type: "merge.add"; sheetId: SheetId; ref: GridRange }
-  | { type: "merge.remove"; sheetId: SheetId; ref: GridRange };
-
-type GridMapping = {
-mapSheetId?(sheetId: SheetId): SheetId;              // for sheet reorder/id changes if needed
-mapCoord(sheetId: SheetId, coord: GridCoord): GridCoord | "detached";
-mapRange(sheetId: SheetId, range: GridRange): GridRange | "detached";
-};
-```
-
-**Key invariant:** commit must remap anchors before notifying subscribers (same as DOCX). Detached anchors must not be silently deleted; they become inspectable “detached” anchors tied to a warning entry.
-
-### Selection and decoration model
-
-Selection must match spreadsheet expectations and ARIA grid navigation semantics.
-
-**Selection model (runtime-owned):**
-- `activeCell`: exactly one cell (sheetId + row/col).
-- `selectionRanges`: 1+ rectangular ranges (start with one; multi-range optional).
-- `mode`: `"view"` | `"edit"` | `"formulaRefPick"` (when editing formula and selecting ranges to insert references).
-- `viewportFocus`: last focused region (`grid`, `formulaBar`, `nameBox`, `sheetTabs`, `rail`). This is *UI transient* but should be fed into keyboard routing.
-
-**Decoration sources:**
-- merge highlights (range boxes),
-- referenced range highlights (during formula edit),
-- error/warning cell markers (compatibility/preservation),
-- comment/note indicators, with hover overlays,
-- selection border, fill handle, active cell outline.
-
-**Implementation rule:** decorations must be computed from runtime state and remapped through transactions, not cached as per-cell arrays in React. (This mirrors the DOCX “decorations computed from anchor overlap” model.)
-
-### Viewport virtualization and overscan strategy
-
-Excel’s sheet size makes virtualization mandatory.
-
-**Core strategy:**
-- Maintain row height and column width models as compact structures:
-  - defaults + sparse overrides for changed rows/cols.
-- Use prefix-sum trees for fast conversions:
-  - `pixelY -> rowIndex`, `rowIndex -> pixelY`,
-  - `pixelX -> colIndex`, `colIndex -> pixelX`.
-- Virtualize both axes:
-  - compute visible row/col window from scroll offsets,
-  - apply overscan (e.g., +4 rows above/below, +2 cols left/right) tuned for wheel/trackpad.
-- Render only:
-  - visible cell rectangles in the viewport,
-  - visible row headers and column headers,
-  - visible merged-cell “top-left” cells as single layout objects spanning multiple rows/cols.
-
-**Overscan policy (implementation-ready default):**
-- Base overscan on scroll velocity:
-  - slow scroll: `overscanRows=4`, `overscanCols=2`,
-  - fast scroll (velocity threshold): `overscanRows=20`, `overscanCols=8`,
-  - during inertial scroll: pause expensive recalculation (styles, text metrics) until settle, but keep selection rendering correct.
-
-### Sheet tabs
-
-Sheet tabs are a structural surface: changing sheet order/name must go through commands and must update workbook-level registries (defined names scope, styles references, etc.). SpreadsheetML stores each worksheet as a separate part referenced by the workbook; the runtime must treat sheets as first-class objects with stable IDs.
-
-**Tab operations (commands):**
-- activate sheet,
-- add sheet,
-- rename sheet,
-- reorder sheets,
-- delete sheet (must be gated: if sheet has preserve-only content tied to it, deletion is destructive and must warn/block).
-
-### Formula bar and name box
-
-**Formula bar (recommended):** This is essential for Excel-like workflows: it provides a stable edit surface for long formulas and prevents “edit-in-cell only” UX traps.
-
-**Name box (recommended):** It supports jumping to A1 references and using defined names; Microsoft’s guidance explicitly describes naming and navigating using the Name Box for defined names.
-
-**Architecture rule:** both inputs maintain only transient text state; commit happens via runtime commands:
-- `selection.setActiveCell` (jump),
-- `name.define` / `name.rename` (if supported),
-- `cell.commitFormulaOrValue`.
-
-### Active-cell renderer and range highlight model
-
-**Active cell** is an overlay box with:
-- focus outline (high-contrast safe),
-- fill handle (optional v1; if unsupported, hide rather than fake).
-
-**Range highlights** (especially for formula reference picking) must:
-- render multiple colored range outlines,
-- be non-color dependent for accessibility (e.g., dashed vs solid patterns), aligning with ARIA grid expectations that focus and selection are perceivable.
-
-### Row/column header behavior
-
-Row/column headers are their own interactive surfaces:
-- click row header selects the row range,
-- click column header selects the column range,
-- drag resize modifies row height/column width via commands.
-
-Keyboard shortcuts like “select row/column” are part of ARIA grid guidance and spreadsheet expectation; implement them in the grid surface controller, not as ad hoc React key handlers.
-
-### Merged-cell rendering
-
-Merged cells are not just a view concern:
-- hit-testing any cell inside a merge maps to the merge anchor cell,
-- editing is allowed only through the anchor cell,
-- splitting merges must be an explicit command.
-
-OOXML semantics explicitly state merged ranges are expressed in `mergeCells` and that formatting/content is stored in the top-left cell.
-
-### Comments/notes overlays
-
-Excel distinguishes threaded comments and notes in user-facing behavior. To avoid lying, implement **one authoring surface** first (recommended: Notes as simpler annotation semantics), and treat the other as preserve-only:
-- preserve underlying parts,
-- render an indicator in the grid,
-- allow viewing (read-only),
-- lock editing with a clear warning.
-
-### Health panel for preserve-only and blocked states
-
-The right rail must include a **Health** panel (same conceptual surface as the DOCX editor) that lists:
-- `preserve-only` features encountered (with affected sheet/range anchors),
-- `unsupported-fatal` blockers,
-- warnings that explain why certain regions are locked.
-
-This panel must drive user trust: it is where “preserved, locked, warned, export blocked” becomes explicit and auditable.
-
-### Performance implications of very large grids
-
-**Hard constraints:** Excel’s sheet size is enormous; you cannot render or store dense grids.
-
-**Performance budgets (v1 defaults you can enforce in CI):**
-- scroll frame budget: <16ms for overlay-only updates,
-- selection movement: <30ms p95,
-- paste of 10k cells: staged, cancelable, with progress UI,
-- initial import: staged with yielding and progressive sheet availability (open workbook quickly, lazy-load sheet XML as user selects tabs).
-
-### Clipboard/paste UI boundaries
-
-Clipboard integration must be implemented at the grid surface layer using `copy/cut/paste` events and `ClipboardEvent.clipboardData` / `DataTransfer`.
-
-**Supported clipboard formats (v1):**
-- Export on copy:
-  - `text/plain`: TSV with `\t` and `\n`,
-  - optional `text/html`: `<table>` representation for richer interop (only if you can safely generate and parse).
-- Import on paste:
-  - prefer `text/html` table when present and trusted,
-  - fallback to `text/plain` TSV.
-
-**Explicit boundaries:**
-- If pasted payload implies constructs you cannot represent (e.g., embedded objects, images, rich cell formatting), either:
-  - paste values only and warn, or
-  - block paste with a clear explanation (depending on host policy).
-
-### Dark mode/high contrast rules for grid-heavy interfaces
-
-Use token-based theming (CSS variables) scoped at the editor root with `.dark` and `data-high-contrast` toggles, following the DOCX editor’s portable theme approach.
-
-Grid-heavy special rules:
-- selection and active-cell indicators must not rely on color alone:
-  - use border styles, thickness, and patterns.
-- comment indicators must remain visible in dark mode and high contrast, with a non-color cue (corner notch + tooltip).
-
-### Review / trust surfaces
-
-Trust surfaces are not optional:
-- status bar always shows:
-  - dirty state,
-  - export blocked/not blocked,
-  - preserve-only count,
-  - last validation timestamp.
-- Health panel and inline lock cards:
-  - “Preserved for Excel round-trip”
-  - “Editing blocked: unsupported feature”
-- Export modal:
-  - shows compatibility report summary and explicit risk state before producing bytes.
-
-### Accessibility
-
-Implement a single tabbable grid root with internal roving focus and keyboard navigation per the W3C grid pattern guidance.
-
-Minimum required behavior:
-- one tab stop into the grid, arrow navigation across cells,
-- Home/End and Page keys per grid guidance,
-- Enter/F2 toggles “actionable/edit mode” inside a cell editor,
-- screen-reader announcements for active cell address, value/formula, and selection changes (use `aria-live` politely throttled).
-
-### Responsive behavior
-
-Follow the proven pattern from the DOCX editor shell:
-- below a width threshold, collapse the right rail into a toggle,
-- keep sheet tabs horizontally scrollable,
-- keep formula bar compact with an “expand” affordance.
-
-### Public API alignment
-
-Align with the DOCX component’s principles: single component entry, typed props + ref, persisted snapshot as the only durable state artifact, and an event stream for telemetry and host workflows.
-
-### Migration path if replacing an older implementation
-
-Adopt the DOCX editor’s migration playbook:
-- dual implementation period behind a host switch,
-- same public API surface while swapping internal renderer/runtime,
-- deprecate legacy entry point only after fixture + reopen gates pass.
-
-For product honesty, track maturity levels using a component cutover matrix style (inventoried → contract-frozen → repo-landed → baseline-proved → …) and require proof artifacts for each promotion.
-
-### Session capability model
-
-Implement `deriveCapabilities(renderSnapshot, props)` as a pure function, matching the DOCX editor’s approach.
-
-```ts
-export interface SessionCapabilities {
-phase: "loading" | "ready" | "diagnostics" | "error";
-canEdit: boolean;
-canUndo: boolean;
-canRedo: boolean;
-
-canCopy: boolean;
-canPaste: boolean;
-
-canEditFormulas: boolean;              // false if formula support is preserve-only
-canExport: boolean;                    // false if export blocked
-exportBlocked: boolean;
-
-preserveOnlyCount: number;
-unsupportedFatalCount: number;
-}
-```
-
-### Spreadsheet-specific capability classification (v1 recommendation)
-
-Use three classes for machine-enforced honesty.
-
-- **supported-roundtrip:** features the runtime can import, edit safely, export, and reopen without repair prompts (must be proven with fixtures + Excel reopen gates).
-- **preserve-only:** features preserved as opaque parts/markup with display/lock/warn; no attempted semantic rewrite.
-- **unsupported-fatal:** features that block export (and possibly block editing) because safe round-trip cannot be guaranteed.
-
-Concrete v1 suggestions grounded in available spec evidence:
-- `calcChain`: treat as non-essential cache; tolerate missing/inconsistent parts and prefer not maintaining it.
-- merges: can be supported-roundtrip if you implement correct top-left semantics.
-- styles: support a conservative subset and preserve unknown `extLst` and style entries; this is feasible because styles are centralized in the Styles part.
-- threaded comments vs notes: pick one authoring target; preserve the other.
-
-### Test matrix, fixture plan, and release gates
-
-**You cannot claim Excel compatibility without fixture-driven proof.** The DOCX editor’s plan explicitly ties maturity promotions to fixture proof and validator runs; reuse that discipline.
-
-**Core fixture classes (minimum):**
-- **P00 package integrity:** `[Content_Types].xml` + rels traversal, unknown parts preserved, relationship round-trip.
-- **S00 shared strings:** import/export shared strings and rich text in shared strings if present.
-- **ST00 styles:** style catalog preservation + a supported subset applied to cells.
-- **M00 merges:** merged ranges render/edit/export correctly (top-left semantics).
-- **C00 calculation:** formulas present + calc settings; calcChain tolerated or omitted; reopen behavior documented.
-- **CM00 comments:** notes and threaded comments present; whichever is preserve-only is verified as preserved and not rewritten.
-- **LG00 large grid:** synthetic workbook near Excel limits (sparse) to validate virtualization and performance budgets.
-
-**Release gates (hard, not aspirational):**
-- Automated:
-  - package integrity validation (relationships resolvable; content types consistent),
-  - deterministic persisted snapshot serialization (stable ordering),
-  - command/transaction invariants (no UI mutation, remap always before notify),
-  - performance smoke for scrolling and paste.
-- Semi-automated:
-  - Open XML SDK-based structural validation in CI (used as validator, not shipped), mirroring the DOCX “validator service” approach.
-- Manual:
-  - reopen in current Excel desktop and Excel web for every release-gate fixture; record “no repair prompt / no silent supported-content loss” notes per fixture. (This mirrors the DOCX project’s explicit manual Word certification gates.)
-
-## Sources
-
-The existing DOCX editor repository provides the architectural baseline for runtime/UI separation, command→transaction discipline, preservation boundaries, capability derivation, and migration patterns, including the frozen runtime contract and component boundary rules.
-
-Normative/primary packaging and compatibility grounding comes from OPC and markup compatibility descriptions and references to ISO/IEC 29500 and ECMA-376, including the ECMA-376 standard landing page and the Library of Congress format descriptions for OPC and MCE/OOXML.
-
-SpreadsheetML structural and element semantics are supported by Microsoft’s Open XML documentation and Open XML SDK API references, including shared strings, workbook/sheet structure, styles part semantics, merged cells, and calculation chain/calcPr properties.
-
-Observed Excel behavior and practical export strategies for recalculation settings are referenced separately from normative rules, using public discussions and SDK attribute documentation (explicitly treated as “observed behavior,” not standard text).
-
-Accessibility and platform constraints are grounded in W3C ARIA grid guidance, React’s external store subscription API, and MDN clipboard event documentation.