@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,809 +0,0 @@
-# React Component Architecture and Front-End Structure Specification for an Excel-Compatible Spreadsheet Editor
-
-## Interpretation of the problem
-
-You want an XLSX sibling to an existing React OpenXML DOCX editor, with the same “architectural rigor and product honesty,” but with spreadsheet-native thinking rather than “rich text + cells.” The end product must be a single embeddable React component whose UI is a projection of a runtime-owned canonical workbook state. All edits must flow through commands → transactions → commit, never via direct UI mutation.
-
-The file format must be treated as an OOXML/Open Packaging Conventions package: not “a handful of XML files,” but a ZIP-based part + relationship graph with content types, implicit/explicit relationships, extension parts, and Excel’s documented deviations/constraints.
-
-Round-trip safety is the bar: import → runtime edit → export → reopen in modern Excel must work without repair prompts and without silently losing supported content. Anything that cannot meet that standard must be explicitly classified as preserve-only or unsupported-fatal (blocked). This is especially important because Excel relies heavily on extension lists, markup compatibility, and product-specific restrictions that go beyond XSD permissiveness.
-
-## Research plan
-
-The research goal was to produce implementation-ready architecture + product boundary specs grounded in primary standards and Excel behavior notes, with explicit separation between normative format rules and Excel-specific processing constraints.
-
-**Information needs prioritized**
-- What is structurally *required* for a valid XLSX package (OPC part graph, relationship rules, minimum workbook parts), and what is optional but common in real Excel files.
-- How core SpreadsheetML constructs map to runtime state: workbook → sheets → rows/cols → sparse cells; cell value typing; shared strings; formulas and cached values; merge semantics; views/panes; comments (legacy + threaded) and their part graph.
-- Where Excel’s real behavior diverges from ISO/ECMA descriptions: cell value restrictions, pane semantics, calc-chain behavior, formula/data-table restrictions, and “schema allows but Office forbids.”
-- What must be preserved to avoid silent loss: extension lists (`extLst`), ignorable namespaces, and Excel extension parts (threaded comments, rich data, feature property bags, etc.).
-- Safety + robustness considerations for ZIP/OPC parsing and export (duplicate entries, path traversal).
-
-**Source strategy**
-- OOXML packaging + structure: ECMA/c-rex OPC material and Microsoft Learn SpreadsheetML structure docs.
-- “Office Implementation” notes against ISO: Microsoft Open Specifications for Office (notably MS-OI29500 and MS-OE376).
-- Excel-specific extensions: Microsoft’s [MS-XLSX] spec PDF and pages on threaded comments/legacy placeholders.
-- Open XML SDK references for part names and schema attribute mapping (useful for validation tooling and CI gates, not for runtime).
-
-Primary standards provenance (for clarity): publishes ECMA-376; and publish ISO/IEC 29500; and publishes Office Open Specifications and Open XML SDK documentation.
-
-## Findings
-
-**XLSX is an OPC package with a relationship graph, not “files in a ZIP.”** In OPC, the package has a content type manifest (`/[Content_Types].xml`) and relationship parts that form a directed graph. Package-level relationships live in `/_rels/.rels`, and each part `/a/b/c.xml` has relationships in `/a/b/_rels/c.xml.rels`. Relationship IDs and relationship types are first-class; they are how parts refer to each other without hardcoding paths.
-
-**A minimum SpreadsheetML workbook is workbook-centric and sheet parts are referenced by relationship IDs.** The `<workbook/>` contains `<sheets/>` with `<sheet/>` entries that refer to worksheet parts via `r:id` relationship IDs. Each worksheet is its own part, and the workbook’s relationships part binds those IDs to targets. This is the base that must survive round-trip unchanged unless intentionally modified.
-
-**Cell storage is typed and has Excel-specific restrictions beyond the base standard.** SpreadsheetML represents a cell as `<c>` with a reference `r`, optional style index `s`, value element `<v>`, optional formula `<f>`, and (for inline strings) `<is>` instead of `<v>`. If `t="inlineStr"`, `<is>` is used rather than `<v>`.
-Office imposes tight constraints on `<v>`: strings stored via shared strings must have `<v>` be a 0-based shared-string index; booleans must be `0/1`; errors must be one of the canonical error strings; formula cells store the last calculated result in `<v>`. Excel also enforces a maximum of 32,767 characters for the `<v>` text.
-
-**Shared strings are a cross-workbook table with strict cardinality.** The shared string table (`<sst/>`) exists to deduplicate strings; SpreadsheetML expects exactly one shared string table part per workbook when shared-string storage is used.
-Practically: a runtime must be able to map between shared-string indices and actual string content, and must not casually rewrite the SST unless it can do so without breaking indices, preserving ordering, and preserving unused-but-referenced entries.
-
-**Formulas are not just strings: shared formulas, arrays, and data tables exist, and Excel adds extra restrictions.** The `<f>` element encodes the formula expression and has attributes such as `t` (normal/shared/array/dataTable) and `si` for shared formula groups; shared formulas use a “master formula” plus relative offsets for dependent cells.
-Excel places additional constraints around data-table formulas (input cell restrictions, `bx` usage, etc.), and those constraints matter for export fidelity if your editor touches these structures.
-
-**Calculation metadata is both spec-level and Excel-version-level.** Spreadsheet calculation metadata includes workbook and sheet calculation properties (e.g., `fullCalcOnLoad`). The `fullCalcOnLoad` attribute exists at least at the worksheet calculation property layer, and its semantics are explicitly “force full calculate on load.”
-Excel has additional calculation-engine versioning mechanisms (e.g., `calcId` + calc feature lists) that affect when Excel decides to recalculate on open. The [MS-XLSX] spec describes calc feature lists that add granularity and can trigger recalculation if features are missing.
-
-**Merged cells have a real semantic constraint: only the top-left cell owns content/formatting.** The merged cell ranges are expressed under `<mergeCells>` with `<mergeCell ref="C2:F2"/>` etc, and the merged range’s content/format is stored in the top-left cell; other cells in the merge are effectively ignored for content. This is not optional behavior; Excel relies on it.
-
-**Comments/notes are structurally multi-part, and Excel’s modern threaded comments layer adds more complexity.**
-Legacy cell comments (“notes”) are stored in a dedicated comments part (`application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml`) with authors + comment list, and each worksheet that has comments has exactly one comments part.
-The *visual comment box* is persisted via VML and linked from the worksheet via `legacyDrawing` relationships to a `.vml` drawing part; this makes “editing comments safely” inherently a multi-part edit (comments XML + VML + relationships).
-Threaded comments are separate parts with their own content types and relationship expectations, and Excel often creates legacy comment placeholders to support backward compatibility; those placeholders have formatting/author conventions (e.g., `author` containing `tc={uid}`) that are part of real Excel behavior.
-
-**View metadata and frozen panes are a place where Office behavior diverges from the written standard.** Microsoft’s standards-support notes document that pane attributes in the standard are underspecified or reversed relative to Office behavior (e.g., xSplit/ySplit reversed, TopLeftCell treated as required in some cases, and xSplit/ySplit not supported as zero in SheetView). If you write panes naïvely “by the book,” you can create files that Excel “repairs” or “interprets differently.”
-
-**Extension lists and markup compatibility are not edge cases in Excel; they’re normal.** The [MS-XLSX] PDF contains many cases of extensions to existing elements via `extLst`, including requirements that extension namespaces be marked ignorable to maintain compatibility. If you reserialize without preserving `extLst` or `mc:Ignorable` semantics, you’ll silently drop content that Excel cares about (slicers/timelines/rich features, etc.).
-
-**Security/robustness note: ZIP parsing must defend against duplicate-entry attacks.** OOXML files are ZIPs. If a ZIP contains duplicate file names/paths, different consumers might pick different entries, which creates both security and interoperability hazards. A GitHub-reviewed advisory for Apache POI highlights this exact class of issue for OOXML formats. Your editor must treat this as unsafe input and fail fast.
-
-## Recommended design / decisions
-
-**Design stance**
-- Treat the runtime’s workbook model as a spreadsheet-native data structure: sheets, rows/cols, ranges, formula graphs, styles, and view metadata. The UI is a projection of this state, not the owner of it.
-- Treat the XLSX package as a preserved graph: you must track parts, relationships, and content types, and decide—explicitly—what you own vs. what you only preserve. That’s the difference between “edits spreadsheets” and “exports spreadsheets that Excel trusts.”
-
-**Shared vs spreadsheet-specific architecture**
-- **Shareable platform layer (should be common with your DOCX editor):** command bus and transaction boundaries; undo/redo journal; runtime subscription (`useSyncExternalStore` integration); compatibility report and response taxonomy (preserve/lock/warn/block/fail); persistence/autosave adapters; and a generic OPC package store that can preserve unknown parts/relationships without loss. OPC is common across DOCX/XLSX/PPTX.
-- **Spreadsheet-specific (must not be forced into a rich-text-shaped abstraction):** cell grid model; selection semantics; formula parsing, dependency graphs, and reference rewrite rules; sheet views/panes; sheet tab metadata; row/column structural edits; merged cell topology; and spreadsheet styling/number formats.
-
-**Scope honesty decisions (v1 defaults)**
-- **Supported-roundtrip (must pass import→edit→export→reopen without repair prompts):** cell values (string/number/bool/error), shared strings and inline strings, basic styles (fonts/fills/borders + cellXfs references), number formats (custom + a sane built-in subset), merges, row/column insert/delete with reference rewrites, sheet creation/rename/reorder, and frozen panes basic support.
-- **Preserve-only (must preserve bytes/markup, can render read-only, but runtime cannot safely mutate):** chartsheet, pivot tables/caches, slicers/timelines, rich value types, external data models, any `extLst` content not explicitly modeled, threaded comments (edit), and most advanced conditional formatting and table features unless specifically implemented. This is aligned with the reality that Excel’s extension ecosystem is huge and frequently uses extension parts.
-- **Unsupported-fatal (block import or block export):** encrypted/protected workbooks if you can’t decrypt; invalid OPC packages (duplicate part names, illegal paths, broken relationship graph); and any workbook where editing would require reserializing unknown extensions in ways you can’t preserve.
-
-**Formula stance (practical and Excel-compatible)**
-- Do not promise a full Excel-compatible calc engine in-browser. That’s a multi-year project because function semantics and calc-engine versioning are deep.
-- Still treat formulas as first-class runtime entities: parse, index dependencies, and rewrite references on structural edits; allow editing formula text with solid validation and clear error states. Shared-formula groups (`t="shared"`, `si`, `ref`) must be preserved and updated correctly when edits intersect their ranges, or you should degrade them to explicit formulas as a deliberate, visible transaction decision (with a warning).
-- Export strategy for calc correctness: set `fullCalcOnLoad` (workbook and/or sheet-level as appropriate) when any formula-affecting change occurs, and treat cached `<v>` values as best-effort display data rather than authoritative. This keeps Excel as the computation authority and reduces the risk of stale cached results being interpreted as “truth.”
-
-**Comments stance (honest and safe)**
-- v1: **support legacy comments/notes editing** only if you implement the multi-part update correctly (comments XML + VML drawing + relationships), and you have fixtures across Excel versions. Otherwise, make comments preserve-only. The format literally stores the visible comment box in VML, so “edit comments” is not a single XML edit.
-- Threaded comments: preserve-only in v1; editing them safely requires also maintaining placeholders and associated structures described in [MS-XLSX].
-
-## Risks and open questions
-
-**Excel compatibility debt is mostly in the “unknown unknowns” of extensions and application behavior.** The [MS-XLSX] document explicitly warns that schema/XSD may be less restrictive than application processing rules, and then layers product-specific restrictions on top. This means “XSD-valid” is not the same as “Excel-opens-without-repair.” Your validation gates must target Excel behavior, not just XML well-formedness.
-
-**Pane/view metadata is a known trap.** If you write frozen panes based on a naïve reading of standard text, Office can interpret xSplit/ySplit differently, treat TopLeftCell differently, and reject “zero” splits in some contexts. This is exactly the kind of thing that causes repair prompts.
-
-**Formula engine scope creep is real.** Even if you don’t compute values, you still must correctly track dependencies, update references on inserts/deletes, handle shared formulas, and avoid corrupting calcChain/calc metadata. The calc engine feature/version metadata in [MS-XLSX] is another area where you can inadvertently force full recalc or create mismatch warnings.
-
-**Preservation correctness is harder than parsing correctness.** It’s easy to “read enough to show a grid.” It’s hard to guarantee you won’t drop `extLst`, ignorable namespaces, or parts you didn’t even know existed, especially when reserializing. The architecture must treat preservation as a first-class subsystem, not an afterthought.
-
-**ZIP/OPC security and determinism.** Duplicate entries and path confusion can lead to different consumers reading different data. You need strict input validation (reject duplicates after canonicalization; reject `..`; reject odd unicode normalization issues in part names) and deterministic export ordering.
-
-**Open question: snapshot persistence strategy.** If snapshots do not preserve the original unknown parts, you cannot guarantee “preserve-only means preserved.” But storing full package bytes in every snapshot may be expensive. You likely need a two-tier persistence model (store base XLSX blob once; store incremental runtime state + a preservation index keyed to the base blob). This is an architectural decision that impacts autosave, collaboration, and storage budgets.
-
-## Concrete deliverable in the requested format
-
-**File: `docs/specs/spreadsheet-editor-architecture.md`**
-
-**Purpose and architectural goals**
-- Deliver a single embeddable React component (`<SpreadsheetEditor />`) that can import XLSX, allow controlled spreadsheet editing, and export XLSX that reopens in modern Excel without repair prompts.
-- Canonical truth lives in a runtime-controlled workbook state model. React is a subscriber/projection layer only.
-- Every mutation flows through `Command → Transaction → Commit`, producing deterministic patches for undo/redo, auditing, and testability.
-- Preservation is mandatory: unsupported but preservable content must not be dropped; it must be retained at the OPC part/relationship level and, where applicable, at XML subtree level inside editor-owned parts.
-- “Response model stays explicit”: preserve, lock, warn, block, fail.
-
-**Normative vs observed behavior policy**
-- **Normative sources**: OPC and SpreadsheetML structural rules (package relationships, part naming, basic SpreadsheetML element semantics).
-- **Observed Excel behavior** (treated as correctness constraints for export): Microsoft “standards support” notes and [MS-XLSX] processing restrictions, including pane interpretation, `<v>` typing/length, and various “schema allows but Office forbids” cases.
-
----
-
-**Public component contract**
-
-```ts
-export type SpreadsheetEditorPhase =
-  | "booting"
-  | "loading"
-  | "ready"
-  | "diagnostics"
-  | "error";
-
-export interface SpreadsheetEditorProps {
-documentId: string;
-
-  /** Host-supplied user identity for audit/events, not for Excel file authorship unless you implement it */
-currentUser: { id: string; displayName: string };
-
-  /** Uncontrolled by default: provide initial XLSX bytes or an editor snapshot. */
-initialXlsx?: ArrayBuffer | Uint8Array;
-initialSnapshot?: PersistedSpreadsheetSnapshot;
-
-  /** If provided, host owns persistence; runtime calls adapter for autosave/export workflows. */
-datastore?: SpreadsheetDatastoreAdapter;
-
-  /** Runtime config */
-readOnly?: boolean;
-locale?: string; // default: "en-US"
-timeZone?: string; // default: host TZ; used for display only
-featureFlags?: Partial<SpreadsheetFeatureFlags>;
-
-  /** UI config (projection only) */
-ui?: Partial<SpreadsheetEditorUiConfig>;
-
-  /** Events are low-volume and semantic (no per-cell keystroke spam). */
-onEvent?: (ev: SpreadsheetEditorEvent) => void;
-}
-
-export interface SpreadsheetEditorRef {
-focus(): void;
-blur(): void;
-
-undo(): void;
-redo(): void;
-
-  /** Programmatic selection (still goes through runtime). */
-setSelection(sel: SelectionSpec): void;
-
-  /** Export uses runtime-owned state + preserved package graphs. */
-exportXlsx(options?: ExportOptions): Promise<ExportResult>;
-
-  /** Snapshot includes runtime state + preservation index. */
-getSnapshot(): PersistedSpreadsheetSnapshot;
-
-  /** Useful for hosts that want to drive commands directly. */
-dispatch(cmd: SpreadsheetCommand): void;
-}
-```
-
-**Contract design notes**
-- The component is “uncontrolled” with respect to workbook content. Host can replace the document only by explicit ref methods or by mounting a new `documentId`.
-- The host API is typed and imperative for correctness: spreadsheets have too many coordinated invariants (references, merge topology, styles) to safely expose “mutable props” patterns.
-- The event model is explicit about diagnostic severity and export gating.
-
----
-
-**Imperative ref API and command surface**
-
-```ts
-export type SpreadsheetCommand =
-  | { type: "cell.setValue"; sheetId: SheetId; addr: CellAddr; value: CellInputValue }
-  | { type: "cell.setFormula"; sheetId: SheetId; addr: CellAddr; formula: string }
-  | { type: "range.paste"; sheetId: SheetId; target: CellAddr; payload: PastePayload }
-  | { type: "row.insert"; sheetId: SheetId; rowIndex: number; count: number }
-  | { type: "row.delete"; sheetId: SheetId; rowIndex: number; count: number }
-  | { type: "col.insert"; sheetId: SheetId; colIndex: number; count: number }
-  | { type: "col.delete"; sheetId: SheetId; colIndex: number; count: number }
-  | { type: "cells.merge"; sheetId: SheetId; range: A1Range }
-  | { type: "cells.unmerge"; sheetId: SheetId; range: A1Range }
-  | { type: "sheet.add"; name: string; afterSheetId?: SheetId }
-  | { type: "sheet.rename"; sheetId: SheetId; name: string }
-  | { type: "sheet.reorder"; sheetId: SheetId; afterSheetId?: SheetId }
-  | { type: "sheet.delete"; sheetId: SheetId }
-  | { type: "view.freezePanes"; sheetId: SheetId; freeze: { rows: number; cols: number } | null }
-  | { type: "comment.setNote"; sheetId: SheetId; addr: CellAddr; note: string | null }
-  | { type: "styles.apply"; sheetId: SheetId; range: A1Range; style: StyleDelta };
-```
-
-**Command semantics**
-- Commands are the *only* mutation entrypoint.
-- Each command is validated against both runtime invariants and “Excel export invariants” (see validation layer).
-- Commands can be refused with explicit outcomes: preserve/lock/warn/block/fail.
-
----
-
-**Runtime/controller architecture**
-
-```ts
-export interface WorkbookRuntime {
-  /** React uses useSyncExternalStore */
-subscribe(cb: () => void): () => void;
-getRenderSnapshot(): RuntimeRenderSnapshot;
-
-  /** Commands only */
-dispatch(cmd: SpreadsheetCommand): void;
-
-  /** Export / persistence */
-exportXlsx(options?: ExportOptions): Promise<ExportResult>;
-getSnapshot(): PersistedSpreadsheetSnapshot;
-
-  /** Diagnostics */
-getCompatibilityReport(): CompatibilityReport;
-}
-
-export interface RuntimeRenderSnapshot {
-phase: SpreadsheetEditorPhase;
-activeSheetId: SheetId;
-
-viewport: {
-topRow: number;
-leftCol: number;
-rowCount: number;
-colCount: number;
-  };
-
-selection: SelectionState;
-
-  /** Render-ready cells for the visible region only. */
-visibleCells: RenderCell[][];
-
-  /** UI-facing derived state */
-canUndo: boolean;
-canRedo: boolean;
-isDirty: boolean;
-
-diagnostics: {
-warnings: SpreadsheetWarning[];
-errors: SpreadsheetError[];
-compatibility: CompatibilityReportSummary;
-  };
-}
-```
-
-**Key architectural constraints enforced**
-- Canonical workbook truth (`WorkbookState`) is runtime-owned.
-- React reads `RuntimeRenderSnapshot` via `useSyncExternalStore`.
-- UI-local state is allowed only for presentation toggles (panel open/closed, theme, active tab), never for workbook truth.
-
----
-
-**Internal module boundaries**
-
-Recommended top-level package boundaries (names are illustrative, align to your repo conventions):
-
-- `src/opc/`
-  - ZIP ingestion/export, part naming and canonicalization, `[Content_Types].xml` management, relationships graph, deterministic export.
-  - **Must** reject unsafe packages (duplicate part names, illegal paths).
-
-- `src/xlsx/import/`
-  - SpreadsheetML parsing into `WorkbookState` + `PreservationStore`.
-  - Part discovery based on relationships, not assumed paths.
-
-- `src/xlsx/model/`
-  - Canonical workbook/sheet/cell/range state.
-  - Row/col metadata, merges, defined names (if supported), styles references, view metadata.
-
-- `src/xlsx/formulas/`
-  - Lexer/parser → AST; dependency graph; reference rewrite engine for inserts/deletes.
-  - Export (string) + import (string) round-trip; shared formula group handling.
-
-- `src/xlsx/styles/`
-  - Styles table model, number format model (custom + built-in subset), style deduplication, display formatting.
-
-- `src/preservation/`
-  - Part-level preservation (unknown parts, relationships) + subtree-level preservation inside partially-owned parts.
-  - `extLst` + `mc:Ignorable` preservation is explicitly tested.
-
-- `src/validation/`
-  - Fast runtime invariants + export gate validations.
-  - CI-only validation adapters (Open XML SDK / Excel open tests).
-
-- `src/runtime/`
-  - `WorkbookRuntimeImpl`, command dispatcher, transaction engine, undo/redo journal, snapshot builder, autosave orchestrator.
-
-- `src/ui/`
-  - Presentational components (grid viewport, sheet tabs, formula bar, status/diagnostics panels).
-  - `src/ui/headless/` for selection math, keyboard mapping, pointer-to-cell addressing, clipboard normalization.
-
----
-
-**Canonical workbook state model**
-
-A spreadsheet-native canonical model that can survive large sheets must be sparse and normalized.
-
-```ts
-export type WorkbookId = string;
-export type SheetId = string;
-
-export interface WorkbookState {
-workbookId: WorkbookId;
-
-  /** Workbook-level metadata we may preserve but not necessarily edit. */
-metadata: {
-calc: {
-      /** If formulas changed and we can't compute accurate cached values, set recalc on load. */
-fullCalcOnLoad: boolean;
-      /** Preserve calcId/calcFeatures if present; treat as preserve-only unless explicitly supported. */
-calcId?: number;
-calcFeatures?: string[];
-    };
-
-    /** Sheet order is explicit and stable. */
-sheetOrder: SheetId[];
-  };
-
-sheets: Record<SheetId, SheetState>;
-
-  /** Global tables */
-sharedStrings: SharedStringTableState;
-styles: StylesState;
-
-  /** Preservation of parts and unknown markup. */
-preservation: PreservationStore;
-
-  /** Diagnostics derived from last import + ongoing edits. */
-compatibility: CompatibilityReport;
-}
-
-export interface SheetState {
-sheetId: SheetId;
-name: string;
-
-grid: {
-    /** Sparse cell map by numeric row/col key. */
-cells: SparseCellMap;
-rowMeta: RowMetaMap;
-colMeta: ColMetaMap;
-
-merges: MergeModel;
-  };
-
-view: SheetViewState;
-
-comments: SheetCommentsState;
-}
-
-export interface CellAddr {
-row: number; // 1-based to match SpreadsheetML and A1 mental model
-col: number; // 1-based
-}
-
-export type CellValue =
-  | { kind: "blank" }
-  | { kind: "number"; value: number }
-  | { kind: "string"; value: string; storage: "sharedString" | "inlineString" }
-  | { kind: "boolean"; value: boolean }
-  | { kind: "error"; value: "#NULL!" | "#DIV/0!" | "#VALUE!" | "#REF!" | "#NAME?" | "#NUM!" | "#N/A" }
-  | { kind: "date"; iso8601: string }; // support only if safely round-trippable in Excel
-
-export interface CellState {
-addr: CellAddr;
-
-  /** Style index references cellXfs; do not embed large style objects per cell. */
-styleRef?: { xfIndex: number };
-
-  /** Either value or formula (or both, where value is cached display). */
-value?: CellValue;
-formula?: FormulaState;
-
-  /** Provenance and preservation */
-origin: "imported" | "runtime";
-preservedXml?: PreservedCellXml; // for unknown attributes/elements like extLst, vm, cm, etc.
-}
-
-export interface FormulaState {
-text: string; // e.g. "SUM(C4:E4)"
-ast?: FormulaAst; // optional, for editing/rewrites
-kind: "normal" | "shared" | "array" | "dataTable";
-shared?: { si: number; ref?: A1Range }; // when kind === "shared"
-}
-```
-
-**Key invariants**
-- Cell values must obey Excel’s typing restrictions on `<v>` based on `t`, and must respect Excel’s string length constraints.
-- Inline strings (`t="inlineStr"`) do not use `<v>`, and must be represented as `<is>` / rich text inline structures.
-- Merged regions store content/format in the top-left cell; runtime must enforce this to avoid generating semantically-invalid merges.
-
----
-
-**Selection model**
-
-Selection must be spreadsheet-native (Excel-like), not text-selection-like.
-
-```ts
-export type A1Range = { a1: string; }; // serialized form for API boundaries
-export type NormalizedRange = { r1: number; c1: number; r2: number; c2: number };
-
-export interface SelectionState {
-activeCell: CellAddr;
-  /** The “primary” selection is what fill-handle / editing uses. */
-primary: NormalizedRange;
-  /** Multi-range selections (Ctrl+click) */
-additional: NormalizedRange[];
-mode: "cell" | "row" | "col" | "range";
-isEditingCell: boolean;
-}
-
-export interface SelectionSpec {
-sheetId: SheetId;
-activeCell: CellAddr;
-primary: NormalizedRange;
-additional?: NormalizedRange[];
-}
-```
-
-**Behavioral requirements**
-- Arrow keys move active cell; Shift extends primary range; Ctrl/Command changes navigation granularity depending on platform conventions.
-- Editing state is separate: when `isEditingCell`, keystrokes go to the cell editor overlay; otherwise, they are navigation/commands.
-- Selection is not stored in React; it’s runtime state so that undo/redo and command replay are deterministic.
-
----
-
-**Command and transaction system**
-
-```ts
-export interface Transaction {
-id: string;
-label: string;
-timestamp: number;
-commands: SpreadsheetCommand[];
-  /** Atomic patch results */
-patch: WorkbookPatch;
-inversePatch: WorkbookPatch;
-diagnostics: TransactionDiagnostics;
-}
-
-export interface TransactionDiagnostics {
-warnings: SpreadsheetWarning[];
-errors: SpreadsheetError[];
-  /** Explicit export gate */
-exportDisposition: "allow" | "block";
-}
-
-export interface WorkbookPatch {
-  /** Structural ops in a compact, replayable form */
-ops: PatchOp[];
-}
-
-export type PatchOp =
-  | { op: "cell.upsert"; sheetId: SheetId; cell: CellState }
-  | { op: "cell.delete"; sheetId: SheetId; addr: CellAddr }
-  | { op: "row.insert"; sheetId: SheetId; rowIndex: number; count: number }
-  | { op: "row.delete"; sheetId: SheetId; rowIndex: number; count: number }
-  | { op: "col.insert"; sheetId: SheetId; colIndex: number; count: number }
-  | { op: "col.delete"; sheetId: SheetId; colIndex: number; count: number }
-  | { op: "merge.set"; sheetId: SheetId; merges: MergeModel }
-  | { op: "view.set"; sheetId: SheetId; view: SheetViewState }
-  | { op: "styles.set"; styles: StylesState }
-  | { op: "sharedStrings.set"; sharedStrings: SharedStringTableState }
-  | { op: "preservation.update"; delta: PreservationDelta };
-```
-
-**Transaction rules**
-- Validate command preconditions before applying.
-- Apply commands to a draft state, computing:
-  - reference rewrite deltas (formulas, defined names, charts ranges if owned),
-  - merge topology adjustments,
-  - style/shared-string table updates.
-- Commit as a single transaction:
-  - update canonical state,
-  - update derived caches (dependency graph, visible cell projection cache),
-  - append transaction to undo journal,
-  - publish render snapshot.
-
----
-
-**Import pipeline**
-
-**Input safety gates (fail fast)**
-- Reject ZIPs with duplicate entry names (after canonicalization), illegal `..` traversal, or ambiguous unicode-normalized paths.
-- Reject packages that cannot be represented as a coherent OPC graph (missing content types or unreadable relationships).
-
-**Package parsing**
-- Build `OpcPackage`:
-  - `parts: Map<PartName, Uint8Array>`
-  - `contentTypes: ContentTypesManifest`
-  - `relationships: RelationshipGraph` for package + per-part relationships
-- Discover workbook part via package relationships (do not assume `/xl/workbook.xml`, though it’s typical).
-
-**SpreadsheetML parsing into canonical state**
-- Parse workbook.xml: sheet list, sheet ordering, sheet relationship bindings.
-- Parse worksheet parts:
-  - `sheetData` rows/cells into sparse grid map
-  - merges
-  - row/col metadata
-  - sheetViews/panes
-  - relationships to comments, drawings, tables, etc. (preserve unknown)
-- Parse shared strings: build stable index map; do **not** reorder.
-- Parse styles: `cellXfs`, number formats, and preserve `extLst`.
-
-**Preservation capture**
-- Preserve all unknown parts as raw bytes.
-- For editor-owned parts that contain unknown subtrees (extensions, drawings, data validation, conditional formatting, etc.), store preserved XML subtrees with stable re-insertion points.
-
----
-
-**Export pipeline**
-
-**Export principle**
-- Export regenerates only editor-owned structures and preserves untouched parts and unknown markup/relationships where possible.
-- Export must be deterministic: stable part ordering, stable relationship IDs when feasible, and stable sheet IDs unless deliberately changed.
-
-**Owned vs preserved classification**
-- Owned parts (v1 typical):
-  - workbook.xml (+ workbook rels if you add/remove sheets)
-  - worksheets/sheetN.xml for sheets you touched (but reinsert preserved subtrees)
-  - sharedStrings.xml if you touched any shared strings
-  - styles.xml if you changed/created styles
-  - comments + VML parts only if you fully implement legacy comment editing
-- Preserved parts:
-  - any part not explicitly owned, including MS-XLSX extension parts, charts, pivot caches, rich data, etc.
-
-**Recalculation policy**
-- If any formula-bearing structure changes and you do not provide Excel-equivalent cached results, set calc recalculation-on-load flags (workbook and/or sheet) to ensure Excel recomputes.
-- If you cannot correctly maintain calcChain semantics, treat calcChain as preserve-only or remove it deliberately and force full calculation on load, but never silently keep a broken calcChain. (This is a release gate item: you must empirically validate with Excel opening behavior.)
-
----
-
-**Preservation layer**
-
-```ts
-export interface PreservationStore {
-  /** Whole-part preservation */
-preservedParts: Record<string /* partName */, PreservedPart>;
-
-  /** For parts we rewrite but need to keep unknown content */
-preservedSubtrees: Record<string /* partName */, PreservedXmlSubtree[]>;
-}
-
-export interface PreservedPart {
-partName: string; // e.g. "/xl/drawings/drawing1.xml"
-contentType: string;
-bytes: Uint8Array;
-relationships?: Relationship[];
-}
-
-export interface PreservedXmlSubtree {
-  /** Stable insertion anchor */
-parentPath: string; // e.g. "worksheet"
-beforeChild?: string; // e.g. "sheetData"
-afterChild?: string;  // e.g. "sheetData"
-rawXml: string;       // exact subtree text
-namespaces: Record<string, string>;
-}
-```
-
-**Preservation guarantees**
-- Unknown parts are re-emitted byte-identical unless a spec-required relocation occurs (rare; should be a “warn + test” event).
-- `extLst` subtrees survive intact, including extension URIs.
-- Markup compatibility (`mc:Ignorable`) and ignorable prefixes survive intact.
-
----
-
-**Validation layer**
-
-Validation exists at three levels:
-
-**Runtime invariants (fast, on every transaction)**
-- Cell typing rules (string indices, booleans, errors).
-- Merge topology: no overlaps, top-left ownership enforced.
-- References: any formula rewrite must keep references in valid A1 form, and shared formula group invariants must hold.
-
-**Export gate checks (before producing bytes)**
-- OPC graph completeness: content types and relationship parts exist and match emitted parts.
-- Excel behavior checks for known traps:
-  - pane/frozen panes attributes written according to Office behavior notes (not just XSD).
-  - comment graph correctness if comments are edited (comments part + VML + worksheet rels).
-- Compatibility report must be “exportDisposition=allow” or export is blocked with explicit reasons.
-
-**CI gates (slow, external tooling)**
-- Open XML SDK validation in CI (schema/part sanity), used as a gate for PRs/releases.
-- Excel open-and-save smoke tests (manual or automated harness) verifying no repair prompt and no loss of supported features.
-
----
-
-**Warning/error model**
-
-```ts
-export type ContentDisposition = "supported-roundtrip" | "preserve-only" | "unsupported-fatal";
-
-export type EditorResponse = "preserve" | "lock" | "warn" | "block" | "fail";
-
-export interface CompatibilityItem {
-id: string;
-disposition: ContentDisposition;
-response: EditorResponse;
-title: string;
-details: string;
-
-  /** Where it lives */
-location?: { sheetId?: SheetId; rangeA1?: string; partName?: string };
-
-  /** Whether it blocks export */
-blocksExport: boolean;
-}
-
-export interface CompatibilityReport {
-items: CompatibilityItem[];
-summary: {
-supportedRoundtripCount: number;
-preserveOnlyCount: number;
-unsupportedFatalCount: number;
-exportBlocked: boolean;
-  };
-}
-
-export interface SpreadsheetWarning {
-code: string;
-message: string;
-location?: CompatibilityItem["location"];
-}
-
-export interface SpreadsheetError {
-code: string;
-message: string;
-location?: CompatibilityItem["location"];
-fatal: boolean;
-}
-```
-
-**Policy**
-- Preserve-only content must be surfaced (warn) at least once per document, and export must guarantee preservation.
-- Unsupported-fatal must block export (and often block import), never silently degrade.
-
----
-
-**Persistence and autosave**
-
-```ts
-export interface PersistedSpreadsheetSnapshot {
-schemaVersion: 1;
-documentId: string;
-createdAt: number;
-
-  /** Canonical runtime state */
-workbook: WorkbookState;
-
-  /** Preservation index. Host can store big blobs separately if desired. */
-preservationIndex: {
-baseXlsxFingerprint: string;
-preservedParts: Array<{
-partName: string;
-contentType: string;
-sha256: string;
-      /** Either embedded or referenced */
-bytesBase64?: string;
-externalRef?: string;
-    }>;
-  };
-}
-
-export interface SpreadsheetDatastoreAdapter {
-saveSnapshot(docId: string, snapshot: PersistedSpreadsheetSnapshot): Promise<void>;
-loadSnapshot?(docId: string): Promise<PersistedSpreadsheetSnapshot | null>;
-
-  /** Optional: store base XLSX bytes once, refer by fingerprint in snapshots */
-storeBaseXlsx?(docId: string, bytes: Uint8Array): Promise<{ fingerprint: string }>;
-loadBaseXlsx?(fingerprint: string): Promise<Uint8Array>;
-
-  /** Optional: export artifact storage */
-storeExport?(docId: string, bytes: Uint8Array): Promise<{ url?: string; id?: string }>;
-}
-```
-
-**Autosave behavior**
-- Autosave stores snapshots (small-ish JSON + referenced preserved blobs) on a timer and/or idle boundary, never on every keystroke.
-- Autosave never exports XLSX unless explicitly configured; export is heavier and should be user- or host-triggered.
-
----
-
-**Performance strategy**
-
-- Parsing:
-  - Parse ZIP once on import; do not reparse the full workbook on each edit.
-  - For large worksheets, parse `sheetData` into a sparse structure; avoid allocating a 1,048,576×16,384 grid.
-- Rendering:
-  - Virtualize viewport: only compute and render visible cells.
-  - Use a single overlay input for cell editing to avoid mounting thousands of editable inputs.
-- Computation:
-  - Dependency graph updates are incremental: rerun only on impacted formula cells/ranges.
-  - Style and shared-string updates are incremental with stable indexing.
-- Export:
-  - Only serialize dirty parts.
-  - Preserve untouched parts byte-identical.
-
----
-
-**Clipboard and paste normalization boundaries**
-
-- Support two clipboard tiers:
-  - **External clipboard**: plain text and TSV/CSV parsing into a rectangular paste payload.
-  - **Internal clipboard**: a custom MIME (e.g., `application/x-editor-grid`) for rich copy/paste within the editor, including formulas and styles, but only when pasted back into the same editor runtime.
-- Paste normalization rules are explicit:
-  - Values: normalize numeric parsing by locale (optional), keep raw string if ambiguous.
-  - Formulas: only treat leading `=` as formula in “formula-aware” paste mode; otherwise paste literal.
-  - Styles: apply only in internal paste mode; external paste ignores formatting unless you explicitly implement HTML clipboard parsing.
-
----
-
-**Spreadsheet-specific feature requirements and scope classification**
-
-- Workbook/sheet/cell/range-native model: supported-roundtrip.
-- Grid viewport and selection behavior: supported-roundtrip (runtime-owned).
-- Formulas:
-  - Parse + rewrite references: supported-roundtrip.
-  - Full function evaluation parity with Excel: preserve-only (do not claim otherwise).
-  - Recalc-on-load flags: supported-roundtrip.
-- Merged cells: supported-roundtrip.
-- Row/column insertion/deletion: supported-roundtrip, but only if reference rewrite passes fixtures (see tests).
-- Styles and number/date formatting:
-  - Preserve all styles: at minimum preserve-only unless you implement editing.
-  - Basic editing into `cellXfs` with stable indices: supported-roundtrip when implemented.
-  - Date typing must respect Office limitations; treat ambiguous cases as preserve-only.
-- Comments/notes:
-  - Legacy notes editing: supported-roundtrip only if multi-part update is implemented and tested.
-  - Threaded comments editing: preserve-only.
-- Sheet tabs and workbook metadata: sheet add/rename/reorder supported-roundtrip; deep workbook metadata preserve-only unless modeled.
-- Preserve-only workbook features: charts/pivots/slicers/timelines/rich data models/unknown extensions preserve-only.
-- Large-sheet virtualization: supported-roundtrip at UI level; must be designed in from day one.
-- Frozen panes and view metadata:
-  - Preserve existing: supported-roundtrip.
-  - Edit freeze/unfreeze: supported-roundtrip only if written to match Office behavior notes.
-
----
-
-**Implementation phases**
-
-- Phase A: OPC package engine + security gates + deterministic export scaffold.
-- Phase B: Minimal workbook import/export (workbook + one sheet + basic sheetData) + viewport rendering.
-- Phase C: Selection model + keyboard navigation + cell edit overlay + undo/redo journal.
-- Phase D: Formulas (parse + dependency graph + reference rewrite on row/col ops) + recalc-on-load policy wiring.
-- Phase E: Merges + row/col insertion/deletion semantics + export gate checks.
-- Phase F: Styles + number formats (preserve-first, then edit support) + formatting display.
-- Phase G: Comments (legacy notes) if in scope, with rigorous fixtures; otherwise preserve-only with diagnostics UI.
-- Phase H: CI validation gates (Open XML SDK + Excel reopen acceptance suite).
-
----
-
-**Non-goals**
-
-- Full Excel calculation engine parity (functions, volatile behavior, engine-version semantics). This is not realistic for v1; the product must not claim it.
-- Editing of pivot tables, charts, slicers, timelines, data model, rich values, or other MS-XLSX extension features unless explicitly implemented and validated.
-- Macro-enabled workbooks (.xlsm) unless explicitly supported (not covered here).
-- “Excel ribbon clone” UI: the UI should be workflow-focused, not feature-exhaustive.
-
----
-
-**Quality bar**
-
-A feature is “supported-roundtrip” only when all are true:
-- It survives import → edit → export → reopen in modern Excel with **no repair prompt**.
-- It does not silently drop related content in any part/relationship.
-- It passes:
-  - deterministic unit tests (command → patch/inverse patch),
-  - fixture round-trip tests (byte-level preservation for preserve-only parts),
-  - CI validation (Open XML SDK),
-  - manual or automated Excel reopen gates for representative files.
-
-## Sources
-
-OPC and SpreadsheetML structure
-- OPC package rules, content types, and relationships part naming:
-- SpreadsheetML workbook/sheet relationship structure:
-- XLSX as “SpreadsheetML in an OOXML/OPC package,” and conformance context (Transitional usage):
-
-Cell/value/formula semantics and Excel-specific constraints
-- Cell element structure and inline string behavior:
-- Formula element attributes and shared formula semantics:
-- Excel restrictions on `<v>` values (type-based constraints and 32,767-char limit):
-- Office constraints on formula data tables and related attributes:
-- Calc and recalc semantics (`fullCalcOnLoad`) mappings:
-
-Merges, views, comments
-- MergeCells semantics, including top-left ownership of content/format:
-- Office behavior differences for panes (xSplit/ySplit, TopLeftCell, etc.):
-- Comments part rules (one comments part per commented worksheet) and relationship expectations:
-- VML-based visual persistence for legacy comments/notes:
-- Threaded comments part and legacy placeholder behavior for backward compatibility:
-
-Extensions and preservation requirements
-- [MS-XLSX] PDF (Excel extensions, extLst usage patterns, calc feature metadata, and extension part ecosystem):
-- [MS-XLSX] introduction statement on normative vs informative sections:
-
-Tooling references and security
-- Open XML SDK SpreadsheetDocument class reference (useful for CI validation tooling):
-- ZIP duplicate-entry vulnerability class in OOXML parsing (motivation for strict input validation):