@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/xlsx-react/xlsx-editor-research-pack.md

@@ -1,871 +0,0 @@
-# Excel-Compatible XLSX Editor Research Pack
-
-Table of contents
-
-- Interpretation of the problem
-- Research plan
-- Findings
-- Recommended design / decisions
-- Risks and open questions
-- Concrete deliverable in the requested format
-  - Spreadsheet Compatibility and Testing Specification
-  - XLSX OOXML Compliance
-  - React Component Architecture and Front-End Structure Specification for an Excel-Compatible Spreadsheet Editor
-  - SpreadsheetEditor UX Guide
-  - Spreadsheet Editor — Frontend Architecture
-  - Canonical Workbook Model, Selection Semantics, and Command/Transaction Design
-  - Formula Engine, Recalculation Strategy, and Reference Integrity for an Excel-Compatible Editor
-  - Review, Comment, Diff, and Change-Inspection Model for an Excel-Compatible Editor
-  - Performance Strategy for a Main-Thread Excel-Compatible Spreadsheet Editor
-  - XLSX Fixture Corpus, Scenario Program, and Certification Plan
-  - Shared OpenXML Editor Platform for DOCX and XLSX
-  - Agent / LLM Interaction Layer for DOCX and XLSX Editors
-- Sources
-
-## Interpretation of the problem
-
-You are building an embeddable React spreadsheet editor that can import an `.xlsx`, allow runtime-driven edits, and export an `.xlsx` that reopens in modern Excel without repair prompts or silent supported-content loss. The workbook is the product; the UI is a projection of runtime-owned canonical state and must never become the canonical truth. All mutations must flow `command -> transaction -> commit`, not direct UI mutation.
-
-The file format must be treated as an OOXML/Open Packaging Conventions (OPC) package (parts + content types + relationships), not “some XML files in a zip”. In practice, that means correctness is (at least) three layers:
-
-- Package correctness (OPC invariants: `[Content_Types].xml`, `/_rels/.rels`, part-level `.rels`, URI/part-name rules, relationship resolution).
-- Markup correctness (SpreadsheetML + related schemas, plus markup compatibility / extensibility for unknown namespaces and future features).
-- Host correctness (Excel’s behavior, including its extensions beyond baseline OOXML, is the final standard).
-
-Unsupported-but-preservable content must be preserved byte-for-byte and relationship-for-relationship unless an explicit response policy says otherwise (preserve / lock / warn / block / fail). Excel-specific extension parts (threaded comments, persons, rich values, named sheet views, slicers, etc.) exist in real-world files and must not be dropped.
-
-A key reality constraint: the GitHub connector available in this environment does not expose the specified repository (`bwllaming/docx-react-component`), so I could not directly mirror your DOCX sibling’s existing repo-level architectural documents. The pack below is therefore written as a “repo-seeding” doc set that follows your framing constraints and cites primary/official XLSX sources, but it does not quote or align to any unobservable implementation details from your existing DOCX repo.
-
-## Research plan
-
-Information needs (what must be true to ship a real Excel-compatible editor):
-
-- OPC invariants and operational consequences for a package-preserving editor: relationships, content types, part naming, and safe rewrite rules.
-- SpreadsheetML “minimum workbook” and core parts/relationships (workbook.xml, worksheets, shared strings, styles, calc chain), plus what is optional vs required.
-- Excel host limits that affect UI and engine design (rows/cols, cell text length, formula length, format limits), plus how those constraints influence virtualization and data structures.
-- Excel extensions to OOXML you will encounter in modern workbooks (threaded comments/persons/mentions, named sheet views, rich values, slicers), and explicit preservation requirements inside those extensions.
-- Encrypted/protected documents: when `.xlsx` is not an OPC zip at all (EncryptedPackage) and must be treated as unsupported-fatal unless you implement the cryptography structure.
-
-Execution approach:
-
-- Attempted to start with GitHub connector review (required by your instructions), but the configured GitHub account here does not list or search the specified repo, so no repo-derived evidence could be incorporated.
-- Performed web research prioritizing primary/official sources: Microsoft Learn (Open XML SDK docs; Microsoft Open Specifications PDFs for MS-XLSX; Office cryptography structure), and Excel limits from Microsoft Support.
-- Treated normative standards vs observed Excel behavior explicitly: “normative” for schema/package requirements reported as ISO/IEC/OOXML requirements; “host behavior” as Microsoft Excel behavior and Microsoft’s extension specs.
-
-## Findings
-
-Package and document structure facts (normative baseline)
-
-- OPC packages model a document as a set of parts with typed content and explicit relationships; relationships can be package-level (source = the package) or part-level (source = a part), and relationship targets can be internal parts or external resources.
-- In SpreadsheetML, a workbook’s logical structure centers on `<workbook>` containing `<sheets>` and `<sheet>` elements; the `<sheet>` elements reference worksheet parts via relationship IDs, and each worksheet is stored as a separate XML part.
-- A “minimum workbook” requires at least one sheet with a unique `sheetId` and a relationship ID pointing to the worksheet definition; the workbook relationships part (`workbook.xml.rels`) binds those IDs to worksheet part targets.
-- A worksheet part contains the sheet grid data in `<sheetData>`; cells are stored with references like `A1` and can contain values and/or formulas.
-- Shared strings: a shared string table part (`sharedStrings.xml`) is the canonical deduplication mechanism for strings; a workbook can reference strings by index rather than inline storage, and Excel typically writes a shared string table when it saves files (though it is not required for validity).
-- Formulas: formula text is stored in `<f>` within a cell; cached results may be stored in `<v>`, and the cached value can be omitted (in which case the reader can recompute based on the formula).
-- Calculation chain (`calcChain.xml`): at most one calculation-chain part can exist; it records an ordered set of formula cells last calculated, but calculation chain information is not required because an application can construct dependencies at load-time.
-
-Host behavior and “real-world Excel” constraints
-
-- Excel hard limits that materially affect editor design include: 1,048,576 rows × 16,384 columns, 32,767 characters per cell, ~8,192 characters per formula, and constraints on format/style counts.
-- Excel extension specifications exist beyond baseline OOXML, and Microsoft explicitly frames MS-XLSX as extensions to ISO/IEC 29500-1/3; only certain sections are normative within that extension spec.
-- Modern Excel workbooks may include advanced extension parts like threaded comments, persons/mentions, named sheet views, slicers, rich value structures, etc.
-- Threaded comments vs legacy comments: MS-XLSX describes threaded comments as a system that “replaces and/or works in addition to legacy comments”; it specifies legacy comment placeholders used for backward compatibility and details reconciliation behavior.
-- Named Sheet Views: MS-XLSX specifies that the presence of a Named Sheet Views part indicates at least one named sheet view and that it must be the target of an implicit relationship from the worksheet part.
-- Rich values: MS-XLSX specifies “rich value” types (including spill/timeout/external errors and other structures) and explicitly states that if a rich value has an unknown rich value type, it must be preserved.
-
-Edge cases that force explicit “fail” classification
-
-- Encrypted Office documents are not editable as normal OPC packages because the document can be wrapped in the Office Document Cryptography Structure; specifically, the `\EncryptedPackage` stream contains the entire ECMA-376 source file in compressed, encrypted form, with encryption parameters found in `\EncryptionInfo`.
-This means “open with zip -> parse XML” fails for such files unless you implement decryption, so “unsupported-fatal” (fail) is the honest v1 stance.
-
-## Recommended design / decisions
-
-Core principle decisions (to keep the architecture honest and “Excel-reopen safe”)
-
-- Use a package-preserving runtime that owns (a) canonical workbook state and (b) a preservation-grade representation of the OPC package graph (parts + relationships + content types + unknown bytes). Do not model “the workbook” as a React state tree. The React component subscribes to runtime projections.
-- Build a command/transaction system where every UI action is translated into a typed command, validated into a transaction, then committed atomically to the runtime state. This enables: undo/redo, deterministic diffs, invariants enforcement, and compatibility-aware blocking/warning.
-- Make “compatibility posture” first-class. Every feature/part category is either:
-  - Supported-editable (safe import → runtime edit → export → reopen),
-  - Preserve-only (round-trip but no semantic edits), or
-  - Unsupported-fatal (cannot safely open or cannot safely export).
-Micro-stances for operations: preserve / lock / warn / block / fail.
-- Default: never drop unknown content. When you must remove or regenerate derived artifacts (like calc chain), do it explicitly and document it as a controlled, compatibility-motivated transformation (typically “warn” or “preserve-with-normalization”), with fixtures proving Excel accepts the result.
-- Certify on Excel behavior, but gate earlier with Open XML structural/schema validation where possible (Open XML SDK validation in CI, plus custom OPC invariant checks).
-
-Pragmatic v1 scope choices (blunt, on purpose)
-
-- v1 should focus on “grid-editing” and the minimal set of workbook features that can be made Excel-reopen safe with high confidence: cell values, basic formulas-as-strings (plus reference updating), row/column sizing, frozen panes and basic sheet view selection state, basic styles/number formats, merges, basic data types, sheet add/rename/reorder, and defined names (if included).
-- Treat most higher-order Excel objects as preserve-only in v1: pivot tables/caches, charts, slicers, timelines, external connections/data model, rich values, named sheet views, conditional formatting, and threaded comments (unless you commit to implementing their multi-part invariants).
-- Treat encrypted/IRM-protected documents as unsupported-fatal in v1, with a clear failure message and optional “export untouched bytes” path only if you are not required to modify.
-
-## Risks and open questions
-
-- Standards availability vs practical implementation: ISO/ECMA specs are authoritative but not always freely retrievable programmatically (license acceptance flows blocked access here), so reliance shifts to Microsoft Learn summaries and Microsoft Open Specifications where accessible. This introduces the risk of missing a subtle normative constraint that Excel enforces.
-- Excel host behavior is the final standard, but some behaviors are underspecified publicly. Your certification plan must include Excel Desktop automation (Windows) to catch repair prompts and silent repairs that schema validation will not detect.
-- “Preserve-only” is deceptively hard: even if you don’t “edit a feature,” other edits (row insertion, copy/paste, range move) can implicitly require updating references inside that preservable feature. If you can’t update those internal references safely, you must lock/block range mutations that intersect them.
-- Formula engine scope: fully replicating Excel calculation semantics is enormous; v1 likely needs a staged approach (reference-parsing and dependency graph first; partial evaluation second; full function parity never). Any mismatch can cause confusing UI vs exported recalculation. Excel’s own limits and function lists shape what you can reasonably support.
-- Rich values, new function families, and “future features”: the MS-XLSX extension spec is updated frequently and includes modern features (rich values, external code service errors, etc.). If you parse/serialize incorrectly, you will break files users expect Excel to open cleanly. The safe stance is preserve-only with strong invariants.
-- Tooling limitation: the PDF screenshot requirement could not be satisfied in this environment due to safe-URL redirects when attempting screenshot extraction on MS-XLSX. The pack relies on the PDF’s extracted text plus Microsoft Learn pages rather than page-image verification.
-
-## Concrete deliverable in the requested format
-
-Below are the requested documents. Each includes a suggested repo filename, a short purpose statement, and full markdown content. Terminology is consistent across the full set:
-
-- **Runtime**: non-React canonical state machine (workbook truth).
-- **Package Graph**: OPC parts/relationships/content types + preserved bytes.
-- **Projection**: derived view model for UI (viewport, formatting for paint, etc.).
-- **Command → Transaction → Commit**: the only mutation path.
-- **Posture**: preserve / lock / warn / block / fail (operation-level responses).
-
----
-
-**File:** `docs/spreadsheet-compatibility-and-testing-spec.md`
-**Purpose:** Define Excel-compatibility targets, posture taxonomy, certification gates, and the test matrix that proves “reopen in Excel without repair prompts or silent loss.”
-
-### Spreadsheet Compatibility and Testing Specification
-
-**Status:** Draft v1
-**Non-negotiable standard:** Files exported by this editor must reopen in recent Excel environments without repair prompts and without silent loss of **supported** content.
-
-**Normative vs host correctness**
-
-- **Spec-level correctness (normative):** We satisfy OPC and SpreadsheetML structural requirements as described in ISO/IEC 29500 and related specifications; for practical implementation details, Microsoft’s Open XML SDK guidance and Microsoft Open Specifications are treated as strong references.
-- **Application-level correctness (host):** Microsoft Excel’s behavior is the final arbiter; passing schema validation but triggering Excel repair is a fail.
-
-**Compatibility posture model (global)**
-
-Every *feature area* and every *operation attempt* yields an explicit posture result:
-
-- **preserve**: The editor round-trips the content without semantic understanding; no user-visible mutation occurs; export must be byte/graph-preserving for that content.
-- **lock**: Content is visible/selectable but is read-only; attempts to modify return lock with an explanation.
-- **warn**: Operation proceeds but may alter semantics or cause Excel to recalc/normalize; warn must be surfaced to host and (optionally) UI.
-- **block**: Operation is prevented because it would risk producing a workbook that Excel repairs or that loses supported content; document state remains unchanged.
-- **fail**: The document cannot be opened or saved safely. Example: encrypted package without decryption support.
-
-**Supported / preserve-only / unsupported-fatal categories**
-
-- **Supported-editable**: import → runtime edit → export → reopen in Excel with no repair AND with preserved supported semantics.
-- **Preserve-only**: import → no semantic edits (or only cosmetic/metadata edits that are proven safe) → export → reopen; editor must not drop or corrupt.
-- **Unsupported-fatal**: cannot open or cannot export safely (e.g., encrypted/IRM docs).
-
-**Target Excel environments (certification set)**
-
-We certify against at least:
-
-- Excel for Microsoft 365 (current channel) on Windows
-- Excel 2021+ on Windows
-- Excel for Microsoft 365 on macOS
-- Excel for the web (smoke validation: open, validate calculations/visuals minimally)
-
-Rationale: Excel limits/specs are documented across versions and apply broadly; our exported files must align with these constraints.
-
-**Definition of “repair prompt” failure**
-
-Fail if any of these occur when opening export output:
-
-- Excel displays “We found a problem with some content…” and repairs.
-- Excel opens but silently removes/rewrites **supported** features (e.g., our supported cell values disappear, formatting disappears, sheet structure changes).
-- Excel writes a repair log indicating removed records in supported areas.
-
-**Test strategy tiers**
-
-1) **Static package invariants tests (fast, required in CI)**
-   - OPC graph traversal: all parts reachable via relationships; `[Content_Types].xml` contains entries for all parts; relationship targets resolve; no dangling relationship IDs.
-   - SpreadsheetML minimum structure checks (workbook.xml, workbook rels, at least one worksheet).
-
-2) **Schema and markup validation (CI, required)**
-   - Use Open XML SDK validation tooling in CI to validate produced packages against known schemas where possible; failures block release. (Open XML SDK provides strongly-typed parts and is a standard reference toolchain.)
-
-3) **Round-trip invariants (CI, required)**
-For each fixture: `import -> no-op export` must satisfy:
-   - Byte preservation for preserve-only parts (exact bytes) OR documented normalization that is proven Excel-safe.
-   - Relationship graph preservation (IDs may change only if we fully rewrite consistent references).
-
-4) **Excel host automation (release gate; nightly + release candidates)**
-   - Open exported workbook in Excel Desktop automation (Windows runner) with alerts captured.
-   - Save-as and reopen to ensure Excel can write it back without further repair.
-
-5) **Scenario-based functional tests (CI + nightly)**
-   - UI-level automation: edit operations, undo/redo, copy-paste, row/column insert/delete, formatting, multi-sheet edits.
-
-**Compatibility test matrix**
-
-Each row = (feature) × (operation) × (expected posture) × (evidence fixture)
-
-Examples:
-
-- Cell value edit (number/string/bool/error): Supported-editable
-- Formula edit (string-level): Supported-editable for syntax-preserving edits; warn if function unsupported for evaluation but preserve formula text; block if reference rewriting can’t be guaranteed.
-- Shared strings conversion: warn if converting inline strings to shared strings or vice versa; Excel typically writes sharedStrings on save, so normalization toward shared strings is usually Excel-aligned, but must be proven in fixtures.
-- Calc chain: warn if dropping calcChain to force Excel rebuild; calcChain is not required and can be recomputed by the application.
-- Threaded comments: preserve-only in v1 unless we implement the multi-part invariants and reconciliation behavior.
-- Named sheet views: preserve-only; block operations that require rewriting their internal references unless implemented.
-- EncryptedPackage: fail on open (unsupported-fatal).
-
-**Release gates**
-
-- Gate A (CI): package invariants + schema validation + round-trip no-op export.
-- Gate B (Nightly): scenario edits across fixture corpus + Excel automation open/reopen.
-- Gate C (Release): full corpus Excel automation + manual spot-check for top customer files.
-
----
-
-**File:** `docs/xlsx-ooxml-compliance.md`
-**Purpose:** Define OPC and SpreadsheetML compliance boundaries, rewrite rules, normalization policy, and strict vs transitional behavior.
-
-### XLSX OOXML Compliance
-
-**Status:** Draft v1
-
-**Baseline definition**
-
-An `.xlsx` is an OPC package: a zip-based physical container representing a logical graph of typed parts connected by relationships. Relationships exist at package level (`/_rels/.rels`) and at part level (`<partname>.rels`), and targets can be internal parts or external resources.
-
-**Compliance objectives**
-
-- Produce packages that Excel opens without repair prompts.
-- Preserve unknown but valid content.
-- Maintain relationship integrity, content types correctness, and markup compatibility behavior.
-
-**OPC invariants we enforce**
-
-- **Content types:** `[Content_Types].xml` must declare default/override content types for parts; new parts require updating content types.
-- **Relationships:**
-  - Package relationships stored in `/_rels/.rels`.
-  - Part relationships stored in `_rels/<part>.rels`.
-  - Targets must resolve to existing parts when internal.
-- **Graph discoverability:** all meaningful parts must be discoverable by traversing relationships from the package root(s). (We treat this as a “must” for our editor even if some producers violate it; we preserve violations but do not create new ones.)
-
-**SpreadsheetML minimal structure invariants**
-
-- Workbook must contain sheets and each `<sheet>` references a worksheet part via relationship ID; workbook relationships bind IDs to worksheet targets.
-- Each worksheet contains `<sheetData>` as the cell table container.
-- Shared strings: if present, there is exactly one shared string table part for the workbook.
-- Calculation chain: if present, there is no more than one calculation chain part.
-
-**Strict vs Transitional**
-
-- We accept both strict and transitional content as input.
-- We default to exporting transitional-compatible structures unless a customer explicitly requires strict and we can prove strict correctness in Excel (because many Excel-produced files are transitional in practice and include Microsoft extension namespaces).
-
-**Markup compatibility / extensibility policy**
-
-- Preserve unknown namespace declarations, `mc:Ignorable` attributes, and unknown elements/attributes in ignorable namespaces. (Example worksheets may include `mc:Ignorable="x14ac"` and related namespaces.)
-- Never drop `extLst` or extension payloads; treat them as preserve-only unless explicitly supported.
-
-**Normalization policy (explicit and limited)**
-
-We allow a small set of “safe normalizations” that are validated by Excel fixtures:
-
-- **calcChain handling:** we may remove or rebuild `calcChain.xml` if it becomes inconsistent after edits; because calc chain is not required and does not dictate runtime calculation order, Excel can rebuild. This must be a **warn** posture and must be covered by fixtures.
-- **Shared strings handling:** we may normalize to shared strings on export (because Excel typically does), but only if we correctly rewrite indices and preserve rich text runs, and only after fixture proof.
-- **Relationship ID regeneration:** allowed only when we fully rewrite all referencing attributes. Otherwise, preserve existing IDs.
-
-Any normalization outside this list requires a design review and certification fixtures.
-
-**Unsupported-fatal compliance cases**
-
-- Office cryptography wrapper (EncryptedPackage): fail to open unless we implement decryption; this is not an OPC zip file we can parse directly.
-
----
-
-**File:** `docs/react-component-architecture-spec.md`
-**Purpose:** Specify the embeddable React component, typed public API, runtime ownership model, and front-end module boundaries.
-
-### React Component Architecture and Front-End Structure Specification for an Excel-Compatible Spreadsheet Editor
-
-**Status:** Draft v1
-
-**Non-negotiable architecture rules**
-
-- React does not own workbook truth. Runtime owns canonical workbook state and all mutations.
-- UI is a projection (derived view model) that is fully reproducible from runtime state.
-- All mutations go through `command -> transaction -> commit`.
-- Unsupported content is preserved; operations that would affect it must return explicit posture results.
-
-**Suggested package layout**
-
-- `packages/ooxml-opc/` (shared)
-  - Zip IO, content types, relationships, part addressing, graph traversal, byte preservation.
-- `packages/ooxml-mc/` (shared)
-  - Markup compatibility helpers: preserve unknown namespaces, ignore rules, safe parse/serialize.
-- `packages/spreadsheet-runtime/` (xlsx-specific)
-  - Canonical workbook model, command/transaction system, projections, export pipeline.
-- `packages/spreadsheet-react/` (xlsx-specific)
-  - React component, event adapters, input system, virtualized grid renderer.
-- `packages/editor-platform/` (shared)
-  - Command bus interfaces, transaction log, undo/redo framework, diagnostics/events.
-- `packages/fixtures/` (shared)
-  - Fixture corpus and golden exports, validation harness.
-
-**Public API shape (TypeScript)**
-
-Core design goals:
-- Host can supply an input package, receive runtime instance, subscribe to events, and request export.
-- Host can inject policy decisions (posture handling) and integrate with persistence.
-
-Sketch:
-
-```ts
-export type Posture = "preserve" | "lock" | "warn" | "block" | "fail";
-
-export interface PostureResult {
-posture: Posture;
-code: string;
-message: string;
-details?: Record<string, unknown>;
-}
-
-export interface SpreadsheetEditorHostCallbacks {
-onReady?: (runtime: SpreadsheetRuntimeHandle) => void;
-onEvent?: (event: SpreadsheetRuntimeEvent) => void;
-onPosture?: (result: PostureResult) => void;
-}
-
-export interface SpreadsheetEditorProps {
-input?: ArrayBuffer; // .xlsx bytes
-readOnly?: boolean;
-
-  // Host policy hooks
-policy?: SpreadsheetPolicy;
-
-  // Callbacks
-host?: SpreadsheetEditorHostCallbacks;
-
-  // UI configuration
-theme?: SpreadsheetTheme;
-initialViewport?: { sheetId?: string; topRow?: number; leftCol?: number };
-
-  // Optional: external persistence hooks
-persistence?: {
-requestSave?: (bytes: Uint8Array) => Promise<void>;
-  };
-}
-```
-
-**Runtime handle**
-
-```ts
-export interface SpreadsheetRuntimeHandle {
-getDocId(): string;
-getStateVersion(): number;
-
-  // Query / projection
-getWorkbookSummary(): WorkbookSummary;
-getSheetProjection(request: SheetProjectionRequest): SheetProjection;
-
-  // Commands
-dispatch(cmd: SpreadsheetCommand): CommandDispatchResult;
-
-  // Export
-exportXlsx(options?: ExportOptions): Promise<Uint8Array>;
-
-  // Undo/redo
-undo(): CommandDispatchResult;
-redo(): CommandDispatchResult;
-
-  // Diagnostics
-getDiagnostics(): DiagnosticItem[];
-}
-```
-
-**Command dispatch result (explicit posture)**
-
-```ts
-export interface CommandDispatchResult {
-ok: boolean;
-posture?: PostureResult; // present when ok=false or when ok=true with warn
-transactionId?: string;
-appliedVersion?: number;
-}
-```
-
-**React component behavior**
-
-- `SpreadsheetEditor` mounts, instantiates runtime (or uses provided runtime), loads input bytes, builds initial projection, renders.
-- UI events (mouse/keyboard) are translated into commands (e.g., `SetCellValue`, `MoveSelection`, `Paste`, `InsertRow`) and dispatched.
-- Runtime emits events; React subscribes and updates projections via selectors keyed by version + viewport.
-
-**Rendering strategy**
-
-- Virtualized grid (rows/cols) is mandatory due to Excel-scale constraints.
-- Rendering uses a “cell paint model” projection: visible cells are materialized with computed format tokens, display value, and interaction flags.
-- Fine-grained invalidation: projection computed per-tile (e.g., 64×64 cells) to avoid repainting entire viewport.
-
----
-
-**File:** `docs/spreadsheeteditor-ux-guide.md`
-**Purpose:** Define UX rules for selection, editing, copy/paste, warnings/locks, and how preserve-only content is presented honestly.
-
-### SpreadsheetEditor UX Guide
-
-**Status:** Draft v1
-
-**Core UX stance**
-
-- This is a spreadsheet editor, not a rich-text editor in a grid.
-- The grid’s semantics (addressing, dependencies, range operations) are first-class.
-- UX must surface when the runtime is preserving/locking/warning/blocking/failing.
-
-**Selection semantics (user-visible)**
-
-- Active cell + selection range are distinct:
-  - Active cell: caret focus target (for formula bar and direct typing).
-  - Selection: rectangular and/or multi-range selection (v1 can restrict to single range; multi-range is an explicit scope add).
-- Range operations (insert/delete rows/cols, sort/filter, fill handle, paste) operate on the selection, not on DOM state.
-
-**Direct editing flows**
-
-- Typing with a single cell selected enters “cell edit” mode.
-- Formula bar shows raw formula text (`<f>`) when present; display layer shows cached or computed value.
-- When formula evaluation isn’t supported for a function, UI still shows formula text and cached value (if available), and marks cell as “not locally recalculated” (warn badge).
-
-**Copy/paste flows**
-
-- Copy creates a structured clipboard payload (internal JSON) plus plain text/TSV for interoperability.
-- Paste dispatches a `PasteRange` command; runtime resolves relative references and updates targets.
-
-**Preserve-only content UX**
-
-Examples: charts, pivots, slicers, data model, threaded comments (v1 preserve-only unless fully supported).
-
-- Preserve-only objects must be visible as “objects” anchored to grid positions when possible.
-- Any attempt to edit a preserve-only object returns `lock` (read-only) or `block` (operation unsafe) with explanation.
-- “Export compatibility” panel lists preserved objects and any warnings emitted during session.
-
-**Warnings and blocks**
-
-- Warnings are non-modal by default but persistent in a session log; host can choose to elevate to modal.
-- Blocks are immediate and must explain *why* (e.g., “Row insertion intersects a preserve-only pivot cache mapping; operation blocked to avoid breaking Excel reopen.”).
-
-**Excel limits UX constraints**
-
-- UI must prevent selecting beyond max row/col bounds and must not create out-of-range references.
-- Pasting content bigger than max rows/cols results in `block` with an actionable message.
-
----
-
-**File:** `docs/spreadsheet-editor-frontend-architecture.md`
-**Purpose:** Describe the browser-side architecture: input system, projection pipeline, rendering, command creation, and event/diagnostics surfaces.
-
-### Spreadsheet Editor — Frontend Architecture
-
-**Status:** Draft v1
-
-**High-level data flow**
-
-- DOM events → Input Router → Intent Model → Command Builder → Runtime Dispatch
-- Runtime Commit → Event Stream → Projection Selectors → React Render
-
-**Key modules (frontend)**
-
-- Input Router
-  - Normalizes pointer/keyboard events, handles platform differences, IME entry, composition events.
-- Intent Model
-  - Converts low-level events into semantic intents: “select range”, “edit cell”, “drag fill”, “resize column”, “open context menu”.
-- Command Builder
-  - Constructs typed commands from intents, always referencing runtime IDs (sheetId, range, cellRef), never DOM indices.
-- Projection Selectors
-  - Memoized selectors keyed by runtime version and viewport window; compute:
-    - cell display strings (cached/computed)
-    - format tokens
-    - selection overlays
-    - row/col header state
-- Renderer
-  - Virtualized grid, overlays, and editor subcomponents (formula bar, name box, sheet tabs, panels).
-
-**Projection contracts**
-
-- A projection must be reproducible from runtime state; it is disposable.
-- Projections must not contain opaque function closures that must be preserved across frames; use IDs and stable handles only.
-
-**Diagnostics + telemetry**
-
-- Runtime emits:
-  - posture events (warn/block/fail)
-  - performance spans (projection time, commit time)
-  - compatibility events (normalization happened, preserve-only encountered)
-
----
-
-**File:** `docs/canonical-workbook-model-and-command-system.md`
-**Purpose:** Define the canonical workbook state model, addressing and selection semantics, and the command/transaction/commit architecture (including undo/redo and invariants).
-
-### Canonical Workbook Model, Selection Semantics, and Command/Transaction Design
-
-**Status:** Draft v1
-
-**Design constraints from OOXML + Excel**
-
-- Grid scale demands sparse storage and virtualization.
-- Formulas and cached results are separate concerns; formulas live in `<f>`, cached value in `<v>`.
-- Workbook structure is sheet-driven; workbook references worksheets via relationships.
-
-**Canonical workbook model (runtime-owned)**
-
-Key properties:
-
-- Canonical state must be independent of the source file’s XML layout while still being able to re-emit valid OOXML.
-- Canonical state must include a preservation envelope for unknown parts and unmodeled elements.
-
-Suggested core entities:
-
-- Document
-  - docId
-  - packageGraph (OPC parts + relationships + content types + raw bytes for unknown parts)
-  - workbook (canonical model)
-  - diagnostics log
-- Workbook
-  - workbookId
-  - sheets: ordered list
-  - definedNames
-  - calcSettings
-  - styleTable (canonical)
-- Sheet
-  - sheetId, name
-  - gridModel (sparse)
-  - rowColModel (sizes, hidden flags)
-  - merges
-  - sheetView (freeze panes, selection, zoom, etc.)
-  - sheetObjects (preserve-only anchors: charts, slicers, etc.)
-- Cell
-  - address (row, col)
-  - value (typed)
-  - formula (optional)
-  - styleRef
-  - dataValidationRef (optional; v1 can preserve-only)
-
-**Sparse grid storage**
-
-- Use chunked sparse tiles (e.g., Map<tileKey, Tile> where Tile is fixed-size).
-- Each Tile stores:
-  - values map
-  - formula map
-  - style indices map
-  - dirty flags (for projections and recalculation)
-
-**Selection model**
-
-- SelectionState
-  - activeCell (sheetId + address)
-  - selectionRanges[] (v1: length 1)
-  - mode: “normal” | “edit” | “formula-entry” | “dragging”
-- This is canonical runtime state because export can embed sheet view selection state, and Excel can persist it in sheet view elements.
-
-**Command / Transaction / Commit**
-
-- **Command**: user intent, declarative, typed. Examples:
-  - `SetCellValue(sheetId, addr, newValue)`
-  - `SetCellFormula(sheetId, addr, formulaText)`
-  - `InsertRows(sheetId, startRow, count)`
-  - `InsertCols(sheetId, startCol, count)`
-  - `DeleteRows(...)`, `DeleteCols(...)`
-  - `SetRangeStyle(sheetId, range, styleDelta)`
-  - `MergeCells(sheetId, range)` / `UnmergeCells(...)`
-  - `RenameSheet(sheetId, newName)`
-- **Transaction**: validated, normalized set of operations with explicit invariants and posture results.
-- **Commit**: applies transaction atomically, emits events, updates version.
-
-**Invariant enforcement examples**
-
-- Prevent out-of-bound writes (rows > 1,048,576; cols > 16,384).
-- Prevent operations that would require rewriting preserve-only objects’ internal references unless implemented → `block`.
-- If we must normalize derived parts (calcChain), emit `warn`.
-
-**Undo/redo**
-
-- Store transaction log with inverse operations:
-  - Each operation provides `apply()` and `invert()`.
-- Undo/redo is runtime-level, not UI-level.
-
----
-
-**File:** `docs/formula-engine-and-recalc.md`
-**Purpose:** Define formula parsing, reference semantics, recalculation strategy, and how to keep reference integrity without pretending to fully replicate Excel.
-
-### Formula Engine, Recalculation Strategy, and Reference Integrity for an Excel-Compatible Editor
-
-**Status:** Draft v1
-
-**Spec-grounded facts we rely on**
-
-- Formula text is stored in `<f>` and cached value in `<v>`; cached value can be omitted, and readers can recompute.
-- Calculation chain (`calcChain.xml`) can exist but is not required; it records last calculation order and does not dictate runtime calculation order.
-- Excel imposes limits on formula length and function semantics in practice.
-
-**Design stance**
-
-Do not commit to full Excel parity in v1. Instead:
-
-- **Always preserve formula text exactly** (including functions we don’t evaluate).
-- **Always maintain reference integrity** for supported range operations (copy/paste, insert/delete rows/cols, move range) for the subset of reference grammar we claim to support.
-- Evaluation is pluggable and explicitly partial.
-
-**Formula capabilities taxonomy**
-
-- **Supported (reference integrity + parse + rewrite):**
-  - A1 references: `A1`, `$A$1`, `A$1`, `$A1`
-  - Ranges: `A1:B5`
-  - Sheet-qualified: `Sheet1!A1`
-  - 3D references (v1 preserve-only unless implemented)
-  - Structured references (tables): preserve-only in v1 unless table engine implemented; grammar exists and is non-trivial.
-- **Supported evaluation (v1 optional):** limited function set (SUM, AVERAGE, MIN/MAX, IF, basic arithmetic), with clear “unsupported function” behavior.
-- **Preserve-only:** dynamic arrays, rich value functions, new/copilot-related functions, external code service functions; preserve text and cached result.
-
-**Recalculation modes**
-
-- Mode 0 (Display cached): show cached `<v>` values where present.
-  - Pros: faithful to file state; minimal complexity.
-  - Cons: edits don’t update dependent cells visually.
-- Mode 1 (Incremental partial): evaluate only supported formula subset; mark others as “not locally recalculated.”
-- Mode 2 (Full engine): out of v1 scope.
-
-**Reference rewrite strategy**
-
-- Parse formula into AST with tokens preserving original string slices.
-- Reference nodes carry:
-  - kind (cell/range/structured/name)
-  - absolute flags
-  - sheet scope
-- Range operations produce a “reference transform” mapping and rewrite AST accordingly.
-
-**calcChain policy**
-
-- If we can maintain calcChain consistently, preserve.
-- If operations invalidate calcChain and we cannot update it safely, remove it and emit `warn`, relying on Excel to rebuild (allowed because calcChain is optional and does not define dependencies).
-
----
-
-**File:** `docs/review-comment-diff-model.md`
-**Purpose:** Define how comments (legacy and threaded), diffing, and change inspection work, with honest v1 scope and preserve-only posture for complex Excel collaboration features.
-
-### Review, Comment, Diff, and Change-Inspection Model for an Excel-Compatible Editor
-
-**Status:** Draft v1
-
-**Key reality**
-
-Excel has multiple comment systems and collaboration metadata:
-
-- Legacy comments are defined in ISO/IEC 29500 (referenced by MS-XLSX).
-- Threaded comments are specified as an extension with associated parts, persons, mentions, and compatibility placeholders; reconciliation behavior is described in MS-XLSX.
-
-**v1 stance**
-
-- Legacy comments: preserve-only (visible if we can anchor to cell; editing optional).
-- Threaded comments/persons/mentions: preserve-only in v1 unless we implement the full multi-part invariants:
-  - Threaded Comments part presence implies at least one threaded comment; part has a specific content type and relationship.
-  - Persons and mentions have required ID correspondence rules.
-  - Legacy placeholders must align with threaded comments for backward compatibility.
-
-**Diff model (editor-internal, not Excel track changes)**
-
-We implement an internal, deterministic diff for:
-
-- Workbook structure changes (sheets added/removed/renamed/reordered)
-- Range edits (cells changed, formulas changed, formats changed)
-- Named range edits
-
-Diff representation:
-
-- Based on committed transactions, not on UI events.
-- Each transaction includes “semantic change entries”:
-  - `CellValueChanged`, `CellFormulaChanged`, `RangeShifted`, `StyleChanged`, etc.
-
-**Change inspection UI**
-
-- A “Changes” panel lists transactions with:
-  - author (host-provided)
-  - time
-  - affected ranges
-  - posture warnings
-- Clicking a change navigates to affected range and highlights before/after.
-
-**Preserve-only collision rules**
-
-If the user edits a range that intersects preserve-only objects anchored to those cells:
-
-- Default: `block` unless we can prove safe rewrite of the preserve-only object references.
-- Alternative: `warn` and proceed only if we can guarantee object remains valid and Excel opens. (This requires fixtures; do not do in v1 by default.)
-
----
-
-**File:** `docs/performance-strategy-main-thread.md`
-**Purpose:** Provide a performance plan that works on the main thread, with explicit budgets, data structures, and regression gates.
-
-### Performance Strategy for a Main-Thread Excel-Compatible Spreadsheet Editor
-
-**Status:** Draft v1
-
-**Constraints**
-
-- Excel scale: grid bounds are huge; we must virtualize and avoid full materialization.
-- JavaScript main-thread: avoid long tasks; projection must be incremental and tile-based.
-
-**Performance budgets (targets)**
-
-- Input latency:
-  - typing to cell display update: < 16ms average
-  - selection movement: < 8ms average
-- Scroll: maintain 60fps under typical viewport sizes
-- Large file load (e.g., 10MB workbook): usable first paint in < 1s on modern laptop (stretch goal; dependent on parsing strategy)
-
-**Core techniques**
-
-- Tile-based sparse grid and tile-based projection cache (64×64 or 128×32).
-- Incremental XML parsing: parse packages and worksheets on demand (sheet-level lazy load).
-- Avoid allocating per-cell objects for empty cells.
-- String interning and shared string handling must be memory-aware; Excel uses shared strings to optimize repeated strings.
-- Commit batching: multiple UI micro-events coalesce into one transaction per user action when possible.
-
-**Regression gates**
-
-- Performance benchmarks in CI: load fixtures, simulate scroll, simulate 10k cell edits, record long tasks.
-- Fail build if median exceeds targets by threshold.
-
----
-
-**File:** `docs/xlsx-fixture-corpus-and-certification-plan.md`
-**Purpose:** Define the fixture corpus, scenario program, and the certification process (CI + nightly + release) for Excel reopen safety.
-
-### XLSX Fixture Corpus, Scenario Program, and Certification Plan
-
-**Status:** Draft v1
-
-**Fixture corpus structure**
-
-- `fixtures/input/`
-  - `minimal/` (minimum workbook, one sheet, basic cells)
-  - `strings/` (shared strings, inline strings, rich text in shared string items)
-  - `formulas/` (simple formulas, references, cross-sheet references; cached values present/absent)
-  - `calcchain/` (with/without calcChain; broken calcChain cases)
-  - `styles/` (num formats, fonts/fills/borders; many styles; edge counts)
-  - `objects-preserve-only/` (charts, pivots, slicers, named sheet views, threaded comments, rich values)
-  - `encrypted/` (encrypted package samples → must fail)
-
-**Scenario program**
-
-Each scenario is a deterministic script:
-
-- Load fixture
-- Apply commands
-- Export
-- Run validators
-- Run Excel automation open/reopen on nightly/release tiers
-
-Example scenarios:
-
-- `no-op round trip` for every fixture
-- `edit cells + undo/redo`
-- `insert rows/cols`, `delete rows/cols`
-- `copy/paste range`
-- `sheet rename/reorder`
-- `format range`
-- `formula rewrite on insert row`
-
-**Certification outcomes**
-
-- **Pass**: Excel opens without repair; supported changes preserved; preserve-only parts preserved.
-- **Warn-pass**: Excel opens and supported changes preserved, but a documented normalization happened (e.g., calcChain dropped).
-- **Fail**: repair prompt or supported loss or structural invalidity.
-
----
-
-**File:** `docs/shared-openxml-editor-platform.md`
-**Purpose:** Define the shared platform modules and contracts reused across DOCX and XLSX editors (OPC package graph, markup compatibility, command/transaction framework, preservation envelope).
-
-### Shared OpenXML Editor Platform for DOCX and XLSX
-
-**Status:** Draft v1
-
-**Shared platform responsibilities**
-
-- OPC Package Graph abstraction
-  - parts (URI, content type, raw bytes, parsed trees where relevant)
-  - relationships (package/part relationships; internal/external)
-  - content types (`[Content_Types].xml`) management
-- Preservation Envelope
-  - store unknown parts + unknown XML payloads as raw bytes
-  - preserve relationship graph even when content is not understood
-- Markup compatibility utilities
-  - preserve unknown namespaces and extension lists
-  - do not drop `extLst`-style future feature payloads
-- Command/Transaction framework
-  - typed commands
-  - validation and posture results
-  - transaction log + undo/redo + diff
-
-**Shared contracts**
-
-- `IOoxmlPackageGraph`
-- `IPreservationStore`
-- `ICommandBus` / `ITransactionEngine`
-- `IPosturePolicy` (host-configurable)
-
-**Preservation rules (shared)**
-
-- Never silently drop unknown parts.
-- Never silently drop unknown relationship types.
-- If we must normalize a derived artifact, we do it explicitly with posture `warn` and fixture coverage.
-
----
-
-**File:** `docs/agent-llm-interaction-layer.md`
-**Purpose:** Specify a safe “agent interface” for both DOCX and XLSX editors: bounded command generation, explainable diffs, and posture-aware tool use.
-
-### Agent / LLM Interaction Layer for DOCX and XLSX Editors
-
-**Status:** Draft v1
-
-**Principles**
-
-- The agent does not mutate state directly. It proposes commands.
-- Every command is validated by runtime; posture outcomes must be returned to the agent.
-- The agent must be able to explain what changed and why something was blocked.
-
-**Core abstractions**
-
-- `EditorAgentSession`
-  - has a runtime handle
-  - can request projections (read-only)
-  - can propose a command batch
-- `AgentCommandPlan`
-  - list of commands
-  - expected outcomes (optional)
-  - rollback strategy
-
-**Security + safety constraints**
-
-- No arbitrary code execution in formulas or macros via agent.
-- For encrypted/protected files, agent must receive `fail` and can only advise user on next steps (e.g., decrypt outside the editor).
-
-**Agent-facing schemas**
-
-- Workbook summary
-- Sheet projection (viewport)
-- Cell inspection (raw stored value, formula text, style tokens)
-- Diagnostics log (warnings, preserve-only objects)
-
-**Example agent flow**
-
-1) Agent requests visible viewport projection.
-2) Agent proposes commands: set values, set formulas, format a range.
-3) Runtime returns {ok, posture, transactionId}.
-4) Agent requests diff summary for transaction; explains to user.
-5) If blocked, agent suggests alternative (e.g., edit a different range, or accept preserve-only lock).
-
----
-
-## Sources
-
-- OPC relationships and packaging fundamentals (relationships as links from package or part; target modes; relationship markup).
-- Microsoft MSDN Magazine on OPC: `[Content_Types].xml`, `/_rels/.rels`, relationship serialization examples.
-- Microsoft Learn: Structure of a SpreadsheetML document (minimum workbook scenario; workbook.xml, workbook rels, worksheet parts).
-- Microsoft Learn: Working with sheets (worksheet part semantics; statement that a package contains one worksheet part per worksheet).
-- Microsoft Learn: Shared string table (sharedStrings part; “Excel always creates a shared string table when it saves a file”; optionality).
-- Microsoft Learn: Working with formulas (`<f>` for formula, `<v>` cached value; cached value can be omitted).
-- Microsoft Learn: Working with the calculation chain (calcChain optionality; at most one; semantics).
-- Open XML SDK reference: SpreadsheetDocument class (package/part model; relationship traversal tools; calc chain ignore helper).
-- Microsoft Support: Excel specifications and limits (grid size, cell text limits, formula length limits, style limits).
-- Microsoft Open Specifications PDF: MS-XLSX (Excel `.xlsx` extensions; threaded comments/persons/mentions; named sheet views; rich values and “unknown rich value MUST be preserved”; slicers).
-- Microsoft Open Specifications: Office Document Cryptography Structure (EncryptedPackage contains entire ECMA-376 source file in compressed encrypted form; EncryptionInfo stream details).