@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/xlsx-react/canonical-workbook-model-and-commands.md

@@ -1,948 +0,0 @@
-# Canonical Workbook Model, Selection Semantics, and Command/Transaction Design
-
-This research paper is source material.
-
-Canonical repo-aligned planned doc:
-
-- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-
-## Interpretation of the problem
-
-You want an XLSX sibling to an existing React-based OOXML DOCX editor, with the same “runtime-owned truth + rigorous preservation” posture, but without pretending spreadsheets are “rich text with cells bolted on.”
-
-Concretely, this document defines an implementation-ready canonical workbook model and the mutation pipeline for an embeddable React spreadsheet editor that:
-
-- Treats `.xlsx` as an **OOXML/Open Packaging Conventions (OPC)** package with parts + relationships + content types, not as a handful of XML files.
-- Keeps a **runtime-owned canonical state** as the source of truth; React renders a projection and never owns or mutates the canonical workbook directly.
-- Routes all changes through **commands → transactions → commit**, with explicit mapping/remapping so anchors and references remain stable and auditable.
-- Never silently drops unsupported content; instead it classifies features and actions explicitly: **preserve, lock, warn, block, fail**, with export safety gated by real Excel reopen behavior (not just schema validation).
-
-The goal here is not to spec *every* Excel feature. The goal is the **core internal model** that makes an Excel-compatible grid editor safe, testable, and extensible—plus the command/transaction structure that makes correctness enforceable.
-
-## Research plan
-
-Information needs to answer this well:
-
-1. **OPC + SpreadsheetML structure requirements** (parts, relationships, content types, minimal workbook requirements, what must exist for a valid workbook).
-2. **Cell value + formula storage semantics** (how values, shared strings, formulas, cached formula results, shared formulas, merges are represented).
-3. **Anchorable objects** (comments/notes, hyperlinks, drawings/images, defined names) and how they bind to cells/ranges and to worksheet/workbook relationships.
-4. **Observed Excel behavior that affects safety** (row/column limits, merge semantics deleting non-top-left contents, reference adjustment rules, R1C1 concepts, deletion producing `#REF!`, structured references).
-5. **Proven architecture patterns from your DOCX editor** (runtime snapshot projection, selection/anchor mapping model, transactions/history boundaries, explicit compatibility taxonomy).
-
-Execution approach:
-
-- Start from your existing repo’s “non‑negotiables” and runtime/transaction patterns, treating them as the baseline for the XLSX sibling’s philosophy and host contract.
-- Use official/primary references for spreadsheet package structure and markup behavior, especially Microsoft Learn’s Open XML SDK docs (which quote ISO/IEC 29500 sections) and Microsoft’s Open Specifications for Excel extensions that drive modern Excel behavior.
-- Separate **normative format/markup constraints** from **observed Excel UX/behavior constraints**, and call out when something is a design decision rather than a guaranteed Excel rule.
-- Convert findings into repo-ready outputs: module boundaries, canonical types, command taxonomy, mapping rules, invariants, undo/redo boundaries, fixture + test matrices, and release gates.
-
-## Findings
-
-### Normative and spec-adjacent constraints (format correctness)
-
-A `.xlsx` workbook is an OPC ZIP container whose contents are discovered and understood via **part names, content types, and relationships**, including a package-level relationships part (`_rels/.rels`) and a content types part (`[Content_Types].xml`).
-
-A minimum SpreadsheetML workbook requires (at least) a workbook part and at least one worksheet part connected through relationships. The Open XML SDK documentation’s “minimum workbook scenario” description (and its generated `workbook.xml` + `workbook.xml.rels` examples) makes this concrete: `workbook.xml` contains `<sheets><sheet ... r:id="..."/></sheets>`, and `workbook.xml.rels` maps that relationship ID to the worksheet part.
-
-Cell values are stored in the `v` (Cell Value) element. If the cell stores a string via the shared string table, `v` stores an index into the shared string table; otherwise `v` stores the value directly. Cells with formulas store the formula in `f` and the **last calculated result** in `v`.
-
-Shared strings are a workbook-level construct (`<sst/>`) containing de-duplicated string instances; strings can also be stored as inline strings under `<c>` using `<is>` instead of `<v>`. Rich text within strings is represented as multiple runs in the shared string table (`<si>` with rich text runs) rather than “cell formatting.”
-
-Merged cells are represented as a worksheet-level collection `<mergeCells>` containing `<mergeCell ref="...">` ranges, and SpreadsheetML stores the merged range’s formatting and content “in the top left cell.”
-
-Hyperlinks are represented in a worksheet as a `<hyperlinks>` collection containing `<hyperlink ref="A11" r:id="rId1" .../>`, where the `r:id` targets a relationship from the worksheet to the hyperlink target resource.
-
-Legacy (non-threaded) comments for a worksheet are stored in a separate comments part whose root is `<comments>`, and the worksheet’s relationships part links to the correct comments part for that sheet. Individual comments have an author and can contain richly formatted text.
-
-Defined names are workbook-level entities (`definedName` elements) representing a cell, range, formula, or constant; they can be scoped to a sheet (`localSheetId`) and can refer across workbooks. The spec-adjacent guidance also notes that a defined name ambiguous with a cell reference can override it, and that a compliant producer/consumer should treat a defined name *in the A1–XFD1048576 range* as an error (i.e., names that look like cell references are special).
-
-Modern Excel includes additional part types and relationships beyond base SpreadsheetML—e.g., **threaded comments** (worksheet-level threaded comment parts) and a workbook-level **persons** part. The Excel extensions spec (MS-XLSX) describes these part content types and mandatory implicit relationships (e.g., persons part from workbook; threaded comments part from worksheet).
-
-Modern Excel also introduces newer workbook constructs such as rich value data and related “rich” part families (rich value data, rich styles, supporting property bag structures, etc.), with required part presence and required implicit relationship chains. These are high-risk for an editor that doesn’t implement them because they can be semantically linked to cell values and metadata.
-
-### Observed Excel behavior constraints (host correctness)
-
-Excel has hard worksheet size limits: 16,384 columns (up to XFD) by 1,048,576 rows. This matters for canonical bounds, validations, and for defining “illegal operations” that should fail or block early.
-
-When merging cells in Excel UI, **only one cell’s contents remain**—for left-to-right locales, the upper-left cell’s contents are kept and the other merged cells’ contents are deleted. This is destructive both in UI and in export semantics, so merge needs explicit warn/block behavior.
-
-Relative vs absolute references: Excel’s default is relative referencing, and copying formulas adjusts relative references; absolute references (with `$`) do not adjust. This drives copy/paste logic and formula AST representation.
-
-Excel supports both A1 and R1C1 reference styles; R1C1 is explicitly described as useful for computing row/column positions and is a first-class concept in Excel options and macro recording. This impacts how you normalize formulas and how you define “same formula” for shared-formula classification (shared formulas are defined relative to R1C1 equivalence in spec-adjacent docs).
-
-Inserting rows/columns/cells shifts cells, and cell references “automatically adjust to match the location of the shifted cells” (explicitly stated in official Excel for Mac guidance). This makes reference remapping a **must**, not a nice-to-have.
-
-Deleting referenced rows/columns can produce `#REF!` because the formula refers to an invalid cell. Excel’s support guidance shows this specifically with deleting a referenced column and Excel rewriting the formula to include `#REF!`. This is a key failure mode for partial editors that do not remap or that incorrectly remap references during structural edits.
-
-Modern Excel has two distinct annotation models: threaded **comments** vs legacy **notes**. Notes behave like older comments; comments are threaded discussions. This has direct implications for “comment/note” modeling and for preserve-only decisions around threaded comments if you don’t implement the persons + threaded comments structures.
-
-### Architecture constraints inherited from your DOCX editor
-
-Your DOCX editor’s compliance stance is explicit: treat the document as an OPC package, preserve unknown parts/relationships, classify every feature as supported-roundtrip vs preserve-only vs unsupported-fatal, and never silently discard preservable content.
-
-The DOCX editor’s runtime takes full ownership of the live session; React consumes a derived render snapshot via `useSyncExternalStore`, and all changes flow through runtime dispatch and transactions.
-
-The repo implements a clear command/transaction separation: commands are executed against the runtime state to produce a transaction containing `nextState`, a `mapping` (used to remap anchors), explicit `effects`, and a history boundary (`push` or `skip`), then committed into runtime history.
-
-Selection/anchor remapping in the DOCX editor is implemented as a deterministic “mapping steps” pipeline with explicit detached-anchor outcomes for deleted/invalidated structures. This is a strong reusable pattern for spreadsheet anchors (selection ranges, comments, hyperlinks, drawings) that must survive structural edits.
-
-## Recommended design / decisions
-
-This section is the core “implementation-ready spec” for the canonical workbook model, selection semantics, and command/transaction design. Where decisions reflect unavoidable Excel behavior, the rationale ties back to the findings; where the decision is an architectural choice, the tradeoffs and failure modes are called out explicitly.
-
-### Canonical state boundaries
-
-**Decision: the runtime owns exactly one canonical workbook state (“WorkbookState”). React owns only transient UI state.** This matches the proven pattern in your DOCX editor: UI renders from a runtime snapshot projection and never mutates canonical state.
-
-Canonical state MUST include everything required to:
-
-- deterministically project the visible grid (values, formats, merges, row/col properties, selection-relevant constraints), and
-- export an `.xlsx` that reopens in modern Excel without repair prompts or silent loss of content the editor claims to support.
-
-Non-canonical (derived) data MUST be recomputable from canonical state: indexes, dependency graphs, render caches, tile caches, etc.
-
-UI state MUST NOT be used as persistence, and MUST NOT become a second “truth” (e.g., don’t let React local state “remember” cell values).
-
-### Stable identity strategy
-
-Spreadsheets force a split between “identity by address” and “identity by object.”
-
-**Decision:**
-- Use **stable IDs** for objects that are not intrinsically identified by grid position (sheets, defined names, styles, comments/notes, hyperlink objects, drawing objects, preservation fragments).
-- Use **address identity** for cell occupancy in the grid (sheetId + row + col) because SpreadsheetML and Excel semantics are fundamentally address-based for most core behavior (formulas, merges, hyperlinks, comment anchors).
-
-This yields a clean rule: a cell “record” is the content currently occupying that address; structural edits *move* those records by remapping addresses (not by generating new per-cell IDs).
-
-**Failure mode avoided:** per-cell UUID identity encourages treating content as a “floating object” that can detach from the grid, which diverges from how Excel persists the core grid and how formulas/anchors refer to it.
-
-### Sparse vs dense storage
-
-Excel’s grid is huge (up to 1,048,576 × 16,384), but real workbooks are sparse.
-
-**Decision: canonical sheet storage is sparse by default.**
-- Store only non-empty or non-default cells.
-- Store row/column properties only where they differ from defaults.
-- Maintain merges, hyperlinks, comments, and drawings as separate sparse collections indexed by ranges/anchors (not as “cell subfields everywhere”).
-
-**Tradeoff:** A sparse model complicates “iterate contiguous ranges” operations and rendering. Solve this with derived indexes and tile caches (non-canonical) rather than densifying canonical state.
-
-### Cell value typing
-
-SpreadsheetML differentiates types via the cell’s `t` attribute and value representation (`<v>` vs `<is>`).
-
-**Decision: canonical value is a discriminated union that preserves both semantic type and roundtrip-critical raw representation.**
-
-Key rule: **do not coerce values “for convenience”** (e.g., do not convert everything into JS numbers/Date objects in canonical state). The canonical state must be export-safe, and export safety depends on preserving certain lexical and structural distinctions (shared strings vs inline strings, cached formula results, date typing when used, error values).
-
-Recommended canonical union:
-
-- `empty` (cell record absent in sparse map)
-- `number` (store as string + optional parsed double in derived cache)
-- `boolean`
-- `error` (`#REF!`, `#DIV/0!`, etc.)
-- `text` (plain string)
-- `richText` (SpreadsheetML rich runs; preserve-only if you don’t implement rich text editing)
-- `dateIso` (only if imported/created using `t="d"` semantics; keep ISO string)
-- `formula` (see next section)
-
-**Explicit honesty requirement:** if you can’t roundtrip rich text edits safely, mark those cells as **preserve-only** and lock editing, rather than flattening rich runs into plain strings and silently losing formatting.
-
-### Formula storage and reference representation
-
-SpreadsheetML stores formula text in `<f>` and cached last result in `<v>`.
-Excel supports shared formulas (`t="shared"` with shared index `si` and applied range `ref`) and considers formulas “the same” based on R1C1 equivalence.
-
-Your editor needs formula handling for two distinct reasons:
-
-1. **Editing** (user changes formula text).
-2. **Structural remapping** (insert/delete rows/cols, rename sheets, copy/paste) — Excel adjusts references automatically and will emit `#REF!` when references become invalid.
-
-**Decision: store formulas as both syntax and structured reference tokens (not as a computed semantic graph), and treat the dependency graph as derived index only.**
-
-- **Syntax layer (canonical):** original formula string (normalized) + a token stream preserving unrecognized segments (“lossless tokenization”).
-- **Reference layer (canonical):** extracted reference tokens represented as typed nodes with explicit absolute/relative flags and sheet binding.
-- **Semantic graph (derived):** dependency edges computed from recognized reference tokens for UI affordances only (precedents/dependents highlighting, recalculation “dirty” marking), not for full calculation.
-
-This is directly aligned with your “don’t pretend you can safely edit what you can’t represent” posture: if a formula cannot be tokenized into a lossless structure that supports remapping, structural edits that require remapping become block/export-block (or preserve-only with locked structural ops).
-
-**A1 vs R1C1:**
-- **Canonical internal references should be sheetId + row/col with absolute/relative flags**, because that is what you must update under copy/paste and row/col edits.
-- Formula strings can be normalized to A1 for display/editing, but you should be able to derive an R1C1 representation when needed for equivalence checks (e.g., shared-formula grouping) and for some API surfaces.
-
-**Shared formulas:**
-- Editing shared formulas correctly is complex because `si` groups and relative expansion can be invalidated by intermediate explicit formulas.
-- **Decision: runtime canonical form stores per-cell explicit formulas**, and shared-formula storage is treated as an export optimization only (optional). If you can’t prove your shared-formula encoder matches Excel behavior for all formula forms you support, export explicit formulas instead.
-  - **Tradeoff:** larger files.
-  - **Benefit:** reduced risk of “Excel repaired content” prompts due to invalid shared-formula semantics.
-  - Compatibility posture: size is cheap; trust is expensive.
-
-### Selection model
-
-Spreadsheets need a selection model that supports:
-- active sheet, active cell
-- rectangular range selection
-- row/column/sheet selection
-- optional multi-range selection (Excel supports discontiguous selections)
-
-Separately, SpreadsheetML may persist view selection in `sheetViews`/`selection` markup, but your runtime selection is primarily for correctness of edit semantics, not just UI.
-
-**Decision: represent selection ranges as rectangles in “gridline coordinates” (half-open intervals), not as inclusive cell pairs.**
-
-Rationale: insertion/deletion acts on boundaries between rows/cols. Using half-open intervals makes remapping deterministic and avoids ambiguous boundary behavior (the same design principle as your DOCX editor’s position mapping and anchor association model).
-
-Terminology:
-
-- `Row` is 1..1,048,576; `RowLine` is 1..1,048,577 (lines between rows, including after last row).
-- `Col` is 1..16,384; `ColLine` is 1..16,385.
-
-A single cell `(r,c)` is the rectangle `[r, r+1) × [c, c+1)` in lines.
-
-Selection shape:
-
-- `activeSheetId: SheetId`
-- `activeCell: CellAddr` (always a single cell)
-- `primary: RectRange` (gridline rectangle)
-- `ranges?: RectRange[]` (optional multi-range; if unsupported in v1, treat as singleton array and explicitly block Ctrl+multi-select UI)
-- `mode: "cells" | "rows" | "cols" | "sheet"`
-- `anchor: CellAddr` (for keyboard extend; analogous to DOCX anchor/head)
-
-**Merged cells and selection:**
-- SpreadsheetML stores merged ranges but content is top-left.
-- Excel UI merge behavior deletes non-top-left values.
-- **Decision:** runtime selection always “snaps” into a merged region:
-  - If activeCell is inside a merged range, selection primary becomes exactly the merge rectangle, and activeCell becomes the merge’s top-left cell.
-  - Editing within a merge writes to the top-left cell only; other cells in the merge are not independently editable.
-  - Any command that would partially cut a merge (delete only some cells inside) is either escalated to a merge-aware operation (unmerge first) or blocked depending on your feature commitments.
-
-**Failure mode avoided:** allowing a selection that targets a non-top-left merged cell and writing value there produces an export that disagrees with Excel’s interpretation and can create “lost” user edits.
-
-### Comments/notes anchors
-
-Legacy comments/notes are stored per worksheet in a comments part linked by worksheet relationships, and each comment is anchored conceptually to a cell reference.
-Modern Excel comments are threaded and require additional parts (threaded comments part per sheet; persons part per workbook).
-
-**Decision: canonical model supports two annotation concepts:**
-- `Note` (legacy, single-cell anchored; “what older Excel called comments”)
-- `CommentThread` (threaded, single-cell anchored), but default v1 stance should be **preserve-only** unless you implement persons + threaded comments export fully.
-
-If you do not implement threaded comments as supported-roundtrip, you still must:
-- preserve threaded comment parts and persons part, and
-- block edits that would require you to semantically rewrite those threads or their anchors (e.g., deleting cells that contain threaded comments).
-
-Anchor representation:
-
-- `CellAnchor = { sheetId, cell: CellAddr }`
-- When row/col insert/delete shifts the anchored cell, remap the anchor via transaction mapping. This is identical in spirit to remapping DOCX comment anchors through content mappings.
-
-Detach semantics:
-- If the anchor cell is deleted, the note/comment becomes `detached` (retained in preservation store) or deleted depending on feature class:
-  - supported-roundtrip notes: either delete (matching Excel likely behavior) or detach with explicit warning; pick one and test fixtures.
-  - preserve-only threaded comments: **detach + warn + preserve**, because deleting them silently is forbidden.
-
-### Hyperlinks anchors
-
-Hyperlinks are stored as worksheet `hyperlinks` with `ref` and relationship target.
-
-**Decision: represent hyperlinks as distinct objects with range anchors**:
-- `Hyperlink = { id, sheetId, range: RectRange, target: ExternalUrl | InternalLocation, tooltip?, display? }`
-
-Remap `range` through transactions. If a structural edit splits the hyperlink range into disjoint ranges, decide:
-- If you support multi-range hyperlinks: split into multiple hyperlinks.
-- If not: block the operation or collapse to intersection with warn (explicit).
-Given Excel’s object model is range-based but UI is cell-based, safest is: **block** disjoint splits in v1 unless you prove Excel’s behavior and replicate it.
-
-### Images/drawings references
-
-Drawings are high risk: they involve additional parts and coordinate anchors that must remap under row/col operations. Even the Open XML SDK surface treats drawings as separate parts linked from worksheets.
-
-**Decision: include drawings/images only as preserve-only objects in canonical state in v1**, unless you explicitly commit to supporting anchor remapping and safe export for at least one drawing anchor type.
-
-Canonical representation should still exist so the runtime can:
-- detect overlap with user operations,
-- lock regions/operations that would break them, and
-- preserve parts and relationships.
-
-Minimal representation:
-- `DrawingObject = { drawingId, sheetId, kind, anchor: CellOrRangeAnchor (approx), rels: { partName, rId }, preserveRef }`
-- `preserveRef` binds to the preservation store which keeps the original parts/relationships intact.
-
-**Honesty rule:** if you cannot prove remapping of drawing anchors under insert/delete, you must treat row/col structural edits that intersect drawing anchor bands as **block export** or **block operation** (not “best effort”), because Excel reopen correctness is the standard.
-
-### Preserve-only regions and unsupported content binding
-
-Modern Excel workbooks can include advanced part families (threaded comments, persons, rich values, named sheet views, etc.) that may be present even when the visible grid looks simple.
-
-**Decision: introduce a first-class `PreservedFeature` and `PreserveOnlyRegion` model** that binds unknown/unsupported semantics back to canonical state as locked placeholders or constraints.
-
-Core requirements, directly inherited from your DOCX editor’s compliance model:
-
-- Feature classes: `supported-roundtrip`, `preserve-only`, `unsupported-fatal`.
-- Response model: preserve, lock, warn, block, fail.
-
-In spreadsheets, preserve-only must cover both:
-- **Package-level preserved parts and relationships** (unknown parts, future extLst, vendor namespaces).
-- **Grid-affecting preserved regions** where edits would require semantic rewrites you don’t support (tables, pivot caches, rich value bindings, threaded comments anchors).
-
-Model them explicitly as constraints:
-- `PreserveOnlyRegion = { id, sheetId, range: RectRange, featureKey, severity, behaviorOnEdit }`
-- `behaviorOnEdit` ∈ { lock, warn, block, fail } with a message string and exportBlock flag if necessary.
-
-This makes “host honesty” enforceable: if you haven’t implemented a feature’s semantics, the runtime can still prevent destructive edits and still preserve the underlying bytes/markup.
-
-### Command taxonomy
-
-Follow the DOCX editor’s proven pattern: a discriminated union of commands, executed against runtime state to yield deterministic transactions.
-
-Recommended command categories (v1 scope-focused):
-
-**Selection + navigation**
-- `selection.set` (set active sheet/cell + ranges + mode)
-- `sheet.activate`
-
-**Cell content**
-- `cell.setValue`
-- `cell.clear`
-- `cell.setFormula`
-- `range.paste` (with paste payload + mode: values/formulas/formats)
-
-**Structural (high risk; must be mapping-backed)**
-- `rows.insert`, `rows.delete`
-- `cols.insert`, `cols.delete`
-- `cells.insertShiftRight`, `cells.insertShiftDown` (optional)
-- `cells.deleteShiftLeft`, `cells.deleteShiftUp` (optional)
-
-**Formatting**
-- `cell.setStyle`, `range.setStyle`, `row.setProps`, `col.setProps`
-
-**Merges**
-- `merge.apply`, `merge.remove`, `merge.toggle`
-
-**Objects/anchors (initially preserve-only or limited)**
-- `note.add/edit/remove` (legacy note)
-- `hyperlink.add/edit/remove`
-- `commentThread.*` (threaded comments: preserve-only unless fully supported)
-
-**Workbook structure**
-- `sheet.add`, `sheet.delete`, `sheet.rename`, `sheet.reorder`
-- `name.define`, `name.delete`, `name.rename`
-
-**Runtime/diagnostics/history**
-- `warning.add/clear`, `runtime.setReadOnly`, `history.undo/redo` (pattern-aligned with DOCX editor).
-
-### Transaction structure
-
-Adopt the DOCX editor’s transaction contract shape, but replace “document mapping” with “workbook mapping” that spans sheets + rows + cols + rectangle anchors.
-
-**Decision: every mutating command produces exactly one `WorkbookTransaction`.** Batching is handled by a single command producing a transaction with multiple low-level ops, not by multiple commits.
-
-Transaction fields (recommended):
-
-- `nextState: WorkbookState`
-- `mapping: WorkbookMapping` (used to remap selection, anchors, formulas, names)
-- `effects: TransactionEffects` (e.g., “selection changed”, “warnings added”, “export blocked changed”)
-- `historyBoundary: "push" | "skip"`
-- `markDirty: boolean`
-
-This parallels the DOCX runtime’s commit behavior and history boundaries.
-
-**Undo/redo boundary rule:** undo/redo happens at transaction granularity, not per keystroke unless you intentionally coalesce commands into a single transaction (e.g., typing in formula bar). This matches the DOCX editor’s `historyBoundary` semantics.
-
-### Mapping/remap rules
-
-Excel’s documented behavior requires reference adjustment when inserting cells/rows/cols, and invalid references yield `#REF!`.
-
-**Decision: mapping is first-class and explicit, and is applied to:**
-- selection rectangles
-- merged ranges
-- hyperlink ranges
-- comment/note anchors
-- defined name formulas
-- cell formula reference tokens (not raw strings)
-
-#### Mapping model
-
-Borrow the DOCX mapping “steps” model, but apply it per axis and per sheet. The DOCX editor maps positions through a list of `{from,to,insertSize}` steps and can detach anchors when deleted/invalidated.
-
-Spreadsheet version:
-
-- `RowLineMappingSteps[]` and `ColLineMappingSteps[]` per affected sheet
-- `SheetMapping` for renames/reorders (sheetId stable; name changes tracked for formula string regeneration)
-- `CellMoveMapping` for copy/paste “relative reference translation” operations (optional explicit representation; often derived from source/dest addresses)
-
-Anchor mapping returns:
-- updated anchor, or
-- detached anchor with reason `deleted` or `invalidatedByStructureChange` (mirror DOCX).
-
-#### Specific remap rules you must implement
-
-**Row/column insert/delete**
-- Shift cells’ addresses in sparse cell map.
-- Remap:
-  - selection
-  - merges (`mergeCell ref`)
-  - hyperlinks (`hyperlink ref`)
-  - legacy note/comment anchors (comments part references)
-  - formula reference tokens and defined name formulas
-- If a referenced cell/range is deleted, rewrite reference node to `#REF!` at export and mark formula as having an invalid reference (and surface warning). This matches Excel’s `#REF!` behavior when referenced cells are deleted.
-
-**Sheet rename**
-- Keep `sheetId` stable; update `sheet.name`.
-- Formula internal references should use `sheetId` where resolvable, so renames do not require semantic remapping—only formula string regeneration on export.
-- If a formula references a sheet by name that cannot be resolved at import (external workbook, missing sheet), keep it as an “external sheet reference token” and treat rename as non-applicable.
-
-**Merge/unmerge**
-- `merge.apply`:
-  - If merging a range where multiple cells contain values, Excel deletes all but top-left.
-  - Therefore:
-    - default action should be **warn** (explicit consent) or **block** (if host says “no destructive merges”) unless the range is value-empty except top-left.
-- `merge.remove`:
-  - Unmerge does not restore deleted values; it only changes structure.
-- Structural ops interacting with merges:
-  - Partial delete of a merge region is either blocked or requires “unmerge then apply operation” behavior, depending on your supported-roundtrip commitments.
-
-**Copy/paste**
-- Values: straightforward copy of `CellValue` union.
-- Formulas: apply translation vector `(dRow, dCol)` from source cell to destination cell to adjust **relative** references; do not change absolute references.
-- Formats: style references copied, but style records deduplicated via style IDs (see style model below).
-
-**Formula edits**
-- Parsing must be at least reference-token aware. If you can’t parse/roundtrip a formula without risk, classify that formula as preserve-only and lock structural operations that would require token rewriting (row/col insert/delete, range paste that shifts). This is the same strictness rule your DOCX editor applies to unsupported OOXML: no “best effort” silent corruption.
-
-### Invariants (must always hold)
-
-These are runtime-enforced invariants; violating them is an internal error and should surface as `internal_invariant` error and block export, consistent with your DOCX error posture.
-
-Core invariants:
-
-- Sheet bounds: all row/col indexes in canonical state are within Excel limits (1..1,048,576 rows; 1..16,384 cols).
-- Sheet IDs are stable and unique; sheet names are unique (Excel requirement; enforce at runtime).
-- Sparse cell map contains no duplicate addresses and no cells outside bounds.
-- Merge ranges do not overlap within a sheet; each merge is a valid rectangle within bounds; merge content exists only in top-left cell (content in other cells is either empty or treated as “masked by merge”).
-- Hyperlink ranges do not overlap in ways your exporter cannot represent (if overlapping is possible in OOXML, still decide if your editor supports it; otherwise mark preserve-only and block edits).
-- Comments/notes anchors point to valid cells or are explicitly detached with a reason.
-- Defined names that conflict with cell references are validated according to the spec-adjacent rule that names in A1–XFD1048576 are treated as an error.
-- Unsupported/preserve-only parts and regions have explicit feature entries and are never silently discarded.
-
-### Serialization to persistence snapshot
-
-Follow the DOCX editor’s distinction between a persisted snapshot and runtime render snapshots: persisted snapshot stores canonical state + compatibility/warnings; render snapshots are derived for UI and are not a persistence contract.
-
-**Decision: persisted snapshot includes:**
-- `canonicalWorkbook` (WorkbookState)
-- preservation store (package parts/relationships and opaque fragments required for non-dropping guarantee)
-- compatibility report + warning log (explicit feature entries, export-block flags)
-
-**Export rule:** for “package-first” fidelity, exporter rewrites only editor-owned parts and reattaches preserved parts/relationships, matching your DOCX package-first rules.
-
-### What belongs where (canonical vs derived vs UI)
-
-**Canonical state (must persist, must roundtrip):**
-- workbook metadata and settings that affect meaning (date system if you choose to support; calculation settings if you touch them)
-- sheets, rows, columns, cells, merges
-- style references (not necessarily fully expanded style tables; see below)
-- defined names
-- notes/comments/hyperlinks that you claim supported-roundtrip
-- preservation store + preserve-only region constraints
-- compatibility feature entries + warnings that affect export (block/warn state)
-
-**Derived indexes (rebuildable):**
-- used-range bounding boxes
-- row/col property interval indexes
-- merge overlap index (interval tree)
-- formula dependency edges (from reference tokens)
-- render tiles (viewport cell matrices), text measurement caches, style resolution caches
-
-**UI state (ephemeral):**
-- scroll offsets; viewport size; zoom
-- editing mode (formula bar active, in-cell edit)
-- selection handles/drag state; clipboard UI state
-- hover/active menus, open panels
-
-This is exactly the separation your DOCX editor enforces: UI local state exists, but it never becomes a parallel document truth.
-
-## Risks and open questions
-
-### Formula completeness is the biggest correctness cliff
-
-Excel formulas span huge surface area: shared formulas, structured references (tables), external references, dynamic arrays, newer “rich values,” etc. The risk is not “we can’t calculate”—you can ship without a calc engine—but “we can’t **remap** references safely under structural edits.” Excel explicitly adjusts references on cell shifts, and invalid refs become `#REF!`.
-
-Open question you must answer early (release gate): **What formula grammar is supported-roundtrip?** Everything else must be preserve-only or unsupported-fatal, and structural operations that would require rewriting unsupported formulas must be blocked with explicit reason.
-
-### Merges are inherently destructive and need explicit UX+API policy
-
-Excel merge deletes non-top-left data. That is not “user error,” it is the product’s behavior.
-If your editor allows merge across non-empty cells without an explicit warn/confirm gate, you will violate the “response model must stay explicit” requirement.
-
-### Threaded comments, persons part, and modern Excel part families
-
-Threaded comments require additional parts and implicit relationships (worksheet threaded comments part, workbook persons part).
-If you don’t implement them fully, treat them as preserve-only and block destructive edits to their anchors. Otherwise, you risk silent supported-content loss.
-
-Similarly, rich value data and supporting property bag parts indicate modern semantic payloads that may bind into cell metadata.
-If present, they are likely preserve-only at first—and may force you to block some edits.
-
-### Drawings/images are a structural-edit trap
-
-Drawings are separate parts and may have anchors that must move under insert/delete.
-If you can preserve them but not remap anchors, you must block structural operations that intersect them (or treat workbook as export-blocked after such operations). “Best effort” will produce broken layouts or Excel repairs.
-
-### Performance + undo/redo memory pressure
-
-Unlike DOCX text, spreadsheet edits can touch thousands of sparse cells at once (pastes, fills). The DOCX runtime history stores whole previous states in memory stacks. That approach will not scale for large sheets.
-You need either persistent data structures or patch/inverse-patch storage to keep undo feasible.
-
-### Validation gate ambiguity: schema-valid vs Excel-correct
-
-Open XML SDK schema validation helps but is not sufficient; your DOCX editor explicitly states host behavior is authoritative and SDK validation is necessary-but-not-sufficient.
-Same applies here: your release gates must include Excel reopen tests on a fixture corpus.
-
-## Concrete deliverable in the requested format
-
-This section is intentionally “repo-ready”: module boundaries, canonical type sketches, command & transaction types, mapping rules, invariants, and example transactions.
-
-### Proposed module boundaries
-
-A minimal but clean separation (mirrors your DOCX repo’s separation of model/core/runtime/io/preservation/validation).
-
-- `src/model/`
-  - `workbook-types.ts` (canonical types)
-  - `formula-types.ts` (token + ref nodes)
-  - `style-types.ts`
-  - `anchors.ts` (grid anchors + mapping)
-- `src/core/`
-  - `commands.ts` (public command union)
-  - `transaction.ts` (transaction shape + commit helpers)
-  - `mapping.ts` (row/col line mapping, anchor remap, reference remap)
-  - `invariants.ts` (assertions + validators)
-- `src/runtime/`
-  - `workbook-runtime.ts` (subscribe, dispatch, undo/redo, getSnapshot, export)
-  - `render-snapshot.ts` (derived UI projection; viewport slicing)
-- `src/io/`
-  - `xlsx-import.ts` (OPC parse → canonical + preservation)
-  - `xlsx-export.ts` (canonical + preserved package → OPC)
-- `src/preservation/`
-  - `package-preservation.ts` (parts/relationships/content types)
-  - `preserve-only-regions.ts` (feature constraints + overlap checks)
-- `src/validation/`
-  - `compatibility-engine.ts` (feature entries, export-block decisions)
-
-### Canonical data model sketches (TypeScript)
-
-These are sketches meant to be copied into code and refined. They intentionally mirror your DOCX editor’s “canonical + preservation + diagnostics” structure.
-
-```ts
-// identifiers
-export type WorkbookId = string;
-export type SheetId = string;
-export type StyleId = string;
-export type NameId = string;
-export type NoteId = string;
-export type CommentThreadId = string;
-export type HyperlinkId = string;
-export type DrawingId = string;
-export type PreserveId = string;
-
-// bounds per Excel limits
-export type Row = number;      // 1..1_048_576
-export type Col = number;      // 1..16_384
-export type RowLine = number;  // 1..1_048_577 (half-open ranges)
-export type ColLine = number;  // 1..16_385
-
-export interface CellAddr { row: Row; col: Col; }
-
-export interface RectRange {
-sheetId: SheetId;
-row0: RowLine; // inclusive
-row1: RowLine; // exclusive
-col0: ColLine; // inclusive
-col1: ColLine; // exclusive
-}
-
-export type FeatureClass = "supported-roundtrip" | "preserve-only" | "unsupported-fatal";
-
-export type ResponseMode = "preserve" | "lock" | "warn" | "block" | "fail";
-
-export interface CompatibilityFeatureEntry {
-featureEntryId: string;
-featureKey: string;                 // e.g. "threaded_comments", "rich_values"
-featureClass: FeatureClass;
-response: ResponseMode;
-message: string;
-affectedRange?: RectRange;
-details?: Record<string, unknown>;
-}
-
-export interface PreservationStore {
-  // Package-level (OPC) preservation
-  // parts include unknown parts + any parts we choose to preserve raw
-packageParts: Record<string, {
-partName: string;          // OPC part name (e.g. "/xl/threadedComments/threadedComment1.xml")
-contentType: string;
-bytesBase64: string;       // or Uint8Array in runtime, base64 in persisted snapshot
-relationships?: Array<{ id: string; type: string; target: string; targetMode?: "Internal"|"External" }>;
-  }>;
-
-  // Opaque XML fragments inside parts we rewrite (if you implement fragment placeholders)
-opaqueFragments: Record<string, {
-fragmentId: PreserveId;
-owningPartName: string;
-xml: string;               // original markup
-featureKey: string;
-bindsTo?: { sheetId?: SheetId; range?: RectRange; cell?: CellAddr };
-  }>;
-}
-
-export type CellValue =
-  | { kind: "number"; raw: string } // preserve lexical; parse in derived cache
-  | { kind: "boolean"; value: boolean }
-  | { kind: "error"; code: "#REF!" | "#DIV/0!" | "#VALUE!" | "#NAME?" | "#N/A" | "#NUM!" | "#NULL!" }
-  | { kind: "text"; text: string }
-  | { kind: "richText"; runs: Array<{ text: string; style?: unknown }> } // preserve-only unless you implement editing
-  | { kind: "dateIso"; iso: string }; // used when cell t="d"
-
-export interface FormulaRef {
-  // A reference token inside a formula
-kind: "cell" | "range";
-sheet: { kind: "localSheet"; sheetId: SheetId } | { kind: "external"; workbook?: string; sheetName?: string };
-  // absolute/relative flags follow Excel copy semantics
-colAbs: boolean;
-rowAbs: boolean;
-  // for kind==="cell"
-col?: Col;
-row?: Row;
-  // for kind==="range"
-col2?: Col;
-row2?: Row;
-}
-
-export interface CellFormulaModel {
-  // The original normalized formula text (e.g. without leading '=' in storage, add on render)
-text: string;
-  // Lossless tokenization so we can rewrite refs without rewriting everything
-tokens: Array<
-    | { kind: "literal"; text: string }
-    | { kind: "ref"; ref: FormulaRef; sourceText: string }
-  >;
-  // Cached last calculated result from <v> (we do not calculate; Excel will on load)
-cachedResult?: CellValue;
-  // If tokenization failed, we cannot safely remap => preserve-only
-parseState: "ok" | "lossy" | "failed";
-preserveOnlyReason?: string;
-}
-
-export interface CellModel {
-addr: CellAddr;
-value?: CellValue;          // absent implies empty
-formula?: CellFormulaModel; // if present, value is cachedResult semantics
-styleId?: StyleId;
-  // Additional low-level flags that map to cell attributes (kept minimal in canonical)
-  // e.g. "cm", "ph" could be preserve-only until fully supported.
-flags?: Record<string, unknown>;
-}
-
-export interface RowProps { height?: number; hidden?: boolean; outlineLevel?: number; styleId?: StyleId; }
-export interface ColProps { width?: number; hidden?: boolean; outlineLevel?: number; styleId?: StyleId; }
-
-export interface MergeModel { id: string; range: RectRange; }
-
-export interface SheetModel {
-sheetId: SheetId;
-name: string;
-  // Sparse cells keyed by "R{row}C{col}" or similar
-cells: Record<string, CellModel>;
-
-  // Sparse row/col properties
-rows: Record<Row, RowProps>;
-cols: Array<{ colMin: Col; colMax: Col; props: ColProps }>; // interval representation
-
-merges: Record<string, MergeModel>;
-hyperlinks: Record<HyperlinkId, {
-id: HyperlinkId;
-range: RectRange;
-target: { kind: "externalUrl"; url: string } | { kind: "internal"; location: string };
-tooltip?: string;
-display?: string;
-  }>;
-
-  // “Notes” (legacy comments) and threaded comments.
-  // Threaded comments should be preserve-only unless fully implemented with persons + part rules.
-notes: Record<NoteId, { id: NoteId; cell: CellAddr; author: string; body: string; richText?: boolean; status: "active" | "detached"; detachedReason?: string }>;
-threadedComments: Record<CommentThreadId, { id: CommentThreadId; cell: CellAddr; status: "preserve-only" | "detached"; preserveRef: PreserveId }>;
-
-drawings: Record<DrawingId, { id: DrawingId; status: "preserve-only"; preserveRef: PreserveId; approxAnchor?: RectRange }>;
-
-preserveOnlyRegions: Record<string, { id: string; range: RectRange; featureKey: string; response: ResponseMode; message: string }>;
-}
-
-export interface DefinedNameModel {
-id: NameId;
-name: string;
-scope: "workbook" | { sheetId: SheetId };
-  // DefinedName text is itself formula-like (ranges/formulas/constants)
-formula: CellFormulaModel;
-}
-
-export interface StyleModel {
-id: StyleId;
-  // canonical style is normalized; exporter maps to styles.xml tables
-  // keep minimal in v1: number format, font, fill, border, alignment
-def: {
-numFmt?: string;
-font?: unknown;
-fill?: unknown;
-border?: unknown;
-alignment?: unknown;
-  };
-  // preserve unknown style features here (extLst etc)
-preserved?: PreserveId[];
-}
-
-export interface WorkbookModel {
-workbookId: WorkbookId;
-  // workbook-level settings that affect meaning
-  // (date system, calc mode, etc) should be explicit if you support editing them.
-settings: Record<string, unknown>;
-
-sheets: SheetModel[];
-definedNames: Record<NameId, DefinedNameModel>;
-styles: Record<StyleId, StyleModel>;
-
-preservation: PreservationStore;
-
-diagnostics: {
-compatibility: {
-blockExport: boolean;
-featureEntries: CompatibilityFeatureEntry[];
-    };
-warnings: Array<{ warningId: string; code: string; message: string; affectedRange?: RectRange }>;
-errors: Array<{ errorId: string; code: string; message: string; isFatal: boolean }>;
-  };
-}
-```
-
-Design notes tied to sources:
-
-- Cell values and formulas mirror SpreadsheetML’s separation of `<f>` and cached `<v>` value.
-- Shared strings vs inline strings must be preserved at IO boundaries; canonical may normalize but must not silently drop rich text.
-- Merges are explicitly modeled because SpreadsheetML stores merges separately and content lives in top-left.
-- Comments/notes and threaded comments are separated because Excel treats them as different features and the OOXML packaging uses different part families.
-
-### Selection model sketch
-
-```ts
-export type SelectionMode = "cells" | "rows" | "cols" | "sheet";
-
-export interface WorkbookSelection {
-activeSheetId: SheetId;
-
-  // Always a single cell, snapped to merge top-left if within a merge.
-activeCell: CellAddr;
-
-  // Primary selection rectangle in gridline coordinates (half-open).
-primary: RectRange;
-
-  // Optional multi-range selection (Excel supports discontiguous selections).
-  // If not in v1: keep empty and block multi-select UI actions.
-ranges?: RectRange[];
-
-  // Controls behavior of row/col header clicks, Ctrl+Space, Shift+Space, etc.
-mode: SelectionMode;
-
-  // Anchor cell for keyboard extension, analogous to anchor/head in DOCX.
-anchorCell: CellAddr;
-}
-```
-
-### Commands + transactions (shape aligned to your DOCX runtime)
-
-Your DOCX runtime uses a `dispatch(command)` that executes a command into a transaction and commits, with undo/redo via history stacks.
-
-```ts
-export interface CommandOrigin {
-source: "keyboard" | "toolbar" | "context_menu" | "formula_bar" | "api" | "runtime";
-timestamp: string;
-}
-
-export type WorkbookCommand =
-  | { type: "selection.set"; selection: WorkbookSelection; origin?: CommandOrigin }
-  | { type: "cell.setValue"; sheetId: SheetId; addr: CellAddr; value: CellValue; origin?: CommandOrigin }
-  | { type: "cell.setFormula"; sheetId: SheetId; addr: CellAddr; formulaText: string; origin?: CommandOrigin }
-  | { type: "rows.insert"; sheetId: SheetId; atRow: Row; count: number; origin?: CommandOrigin }
-  | { type: "rows.delete"; sheetId: SheetId; fromRow: Row; count: number; origin?: CommandOrigin }
-  | { type: "cols.insert"; sheetId: SheetId; atCol: Col; count: number; origin?: CommandOrigin }
-  | { type: "cols.delete"; sheetId: SheetId; fromCol: Col; count: number; origin?: CommandOrigin }
-  | { type: "merge.apply"; sheetId: SheetId; range: RectRange; origin?: CommandOrigin }
-  | { type: "merge.remove"; sheetId: SheetId; mergeId: string; origin?: CommandOrigin }
-  | { type: "hyperlink.add"; sheetId: SheetId; range: RectRange; target: string; origin?: CommandOrigin }
-  | { type: "note.add"; sheetId: SheetId; cell: CellAddr; body: string; origin?: CommandOrigin }
-  | { type: "sheet.rename"; sheetId: SheetId; name: string; origin?: CommandOrigin }
-  | { type: "name.define"; name: string; scope: "workbook" | { sheetId: SheetId }; formula: string; origin?: CommandOrigin }
-  | { type: "runtime.setReadOnly"; readOnly: boolean; origin?: CommandOrigin }
-  | { type: "history.undo"; origin?: CommandOrigin }
-  | { type: "history.redo"; origin?: CommandOrigin };
-
-export interface AxisMappingStep {
-  // Gridline coordinates, not cell coords.
-from: number;
-to: number;
-insertSize: number;
-}
-
-export interface WorkbookMapping {
-sheets?: Record<SheetId, {
-rowSteps?: AxisMappingStep[];
-colSteps?: AxisMappingStep[];
-    // optional: rename info for formula string regeneration
-renamedFrom?: string;
-renamedTo?: string;
-  }>;
-metadata?: {
-invalidatesStructures?: boolean;
-affectsFormulas?: boolean;
-affectsNotes?: boolean;
-affectsHyperlinks?: boolean;
-affectsMerges?: boolean;
-affectsPreserveOnlyRegions?: boolean;
-  };
-}
-
-export interface TransactionEffects {
-warningsAdded: string[];
-warningsCleared: string[];
-exportBlockChanged?: boolean;
-selectionChanged?: boolean;
-}
-
-export interface WorkbookTransaction {
-nextState: WorkbookModel;
-mapping: WorkbookMapping;
-effects: TransactionEffects;
-historyBoundary: "push" | "skip";
-markDirty: boolean;
-}
-```
-
-The point here is structural: it is the same “command → transaction → commit” skeleton your DOCX editor uses, with a mapping object that exists to remap anchors reliably.
-
-### Transaction examples
-
-#### Example: insert one row at row 10
-
-Intent: insert a row, shift everything below down, adjust references, remap merges/hyperlinks/notes, and update selection.
-
-Key constraint: Excel states references automatically adjust when inserting rows/cells.
-
-Transaction sketch (illustrative JSON):
-
-```json
-{
-  "command": { "type": "rows.insert", "sheetId": "S1", "atRow": 10, "count": 1 },
-  "mapping": {
-    "sheets": {
-      "S1": {
-        "rowSteps": [{ "from": 10, "to": 10, "insertSize": 1 }]
-      }
-    },
-    "metadata": {
-      "affectsFormulas": true,
-      "affectsNotes": true,
-      "affectsHyperlinks": true,
-      "affectsMerges": true
-    }
-  },
-  "historyBoundary": "push",
-  "markDirty": true
-}
-```
-
-Remap consequences:
-- All cell addresses with row ≥ 10 shift by +1 (sparse map key rewrite).
-- Any formula ref token with row ≥ 10 shifts if that token is absolute to sheet coords; relative tokens are handled by copy/paste rules, not insert rules.
-- Merges/hyperlinks anchored below shift their `row0/row1`.
-- Notes/comments anchored to a cell below shift.
-
-#### Example: merge A1:C1 with non-empty B1
-
-Excel merge deletes non-top-left contents.
-
-So `merge.apply` must produce either:
-- `warn` requiring explicit user acknowledgement, or
-- `block` if host policy forbids destructive operations.
-
-Transaction outline:
-
-```json
-{
-  "command": { "type": "merge.apply", "sheetId": "S1", "range": "S1:[row0=1,row1=2,col0=1,col1=4]" },
-  "preflight": {
-    "nonTopLeftNonEmptyCells": ["B1"],
-    "response": "warn",
-    "message": "Merging will delete values in B1 and C1. Excel keeps only the top-left cell’s contents."
-  }
-}
-```
-
-If user accepts:
-- clear B1/C1 values in canonical state,
-- add merge range,
-- snap selection activeCell to A1 and primary range to merge.
-
-This matches SpreadsheetML’s “top-left stores content” and Excel UI behavior.
-
-### Release gates and fixture plan (minimum)
-
-Your DOCX editor’s release gates include: fixture-based import/export tests, package integrity checks, Open XML SDK validation in CI/services, preserve-only survival checks, and host application reopen certification.
-
-Spreadsheet v1 needs the same, adapted:
-
-- **Fixture corpus** (frozen “gate fixtures”):
-  - F01: minimum workbook (1 sheet, blank) proof (structure + reopen).
-  - F02: shared strings + inline strings (including rich runs) preserve-only behavior.
-  - F03: formulas with cached results; ensure export preserves `<f>` + cached `<v>` and reopens.
-  - F04: insert row/col remaps references (validated by Excel reopen and correct formula updates).
-  - F05: merge with multi-values surfaces warn; merge export matches Excel semantics.
-  - F06: hyperlinks roundtrip (`hyperlink ref` + rel).
-  - F07: legacy notes preserved + moved under row insert (or explicitly blocked if not supported).
-  - F08: threaded comments present ⇒ preserve-only parts survive; destructive edits blocked.
-  - F09: defined names remap with sheet rename and row insert, or are preserved/blocked if formula parsing fails.
-  - F10: rich value parts present ⇒ preserve-only; verify survival.
-
-- **Export certification gate**: Excel desktop reopen with no repair prompts and no silent supported-content loss for fixtures you classify as supported-roundtrip.
-
-- **Preserve-only survival gate**: for preserve-only fixtures, verify byte-level retention (or semantically equivalent retention) of preserved parts/relationships + clear warnings surfaced to host.
-
-## Sources
-
-Your DOCX runtime architecture and compliance philosophy (primary internal reference):
-
-- DOCX compliance taxonomy, package-first preservation rules, and the explicit preserve/lock/warn/block/fail response model.
-- Public API posture: uncontrolled component, runtime-owned live session, persisted snapshot vs render snapshot separation.
-- Frontend architecture: runtime emits render snapshots consumed via `useSyncExternalStore`; UI never holds canonical truth; mutations flow through runtime callbacks.
-- Runtime + command pipeline: `executeEditorCommand` returns transaction with mapping/history boundary; runtime commits, maintains undo/redo, and remaps anchors through mapping.
-- Mapping tests showing the intended semantics of mappings and remapping stored anchors through document replacement.
-- Repo agent guidance emphasizing: OPC-first, canonical state not DOM, commands/transactions only, no silent dropping.
-
-OOXML / SpreadsheetML structure and markup references:
-
-- SpreadsheetML document structure, minimum workbook scenario, and example workbook.xml/workbook.xml.rels/worksheet.xml structure from Learn (Open XML SDK documentation).
-- OPC packaging overview and requirements excerpted in Library of Congress format description (content types part, relationships parts, discoverability of parts).
-- Cell value semantics (`<v>` as shared string index vs direct value; cached formula result stored in `<v>`; inline string `<is>` alternative).
-- Cell value type enum mapping to XML `t` values (b/n/e/s/str/inlineStr/d).
-- MergeCells semantics (“formatting and content always stored in top left cell”).
-- Hyperlinks markup and relationship-based target linking.
-- Comments markup: comments part per sheet, wired via sheet relationships; single comment has author and may contain rich formatted text.
-- Defined names semantics and constraints (scope, formula/value use, ambiguity with cell references, A1–XFD1048576 rule).
-
-Modern Excel extension part families (MS-XLSX, Microsoft Open Specifications):
-
-- MS-XLSX introduction (normative sections statement) and part definitions including threaded comments, persons, named sheet views, rich value data, and related relationship requirements.
-
-Observed Excel behavior (host correctness constraints):
-
-- Excel row/column limits and inserted-row formatting behavior.
-- Merge UI behavior deleting non-top-left values (destructive merge semantics).
-- Relative/absolute/mixed references and copy-adjust behavior.
-- R1C1 reference style explanation and examples.
-- Insert cells/rows/cols shifts and automatic adjustment of cell references (Excel for Mac guidance).
-- `#REF!` error caused by deleting referenced columns (Excel rewrites to `#REF!`).
-- Structured references behavior and how table edits/renames adjust structured references.