Format & Branding — the .rewind contract

ExcelRewind architecture documentation · packages/format + packages/branding + scripts/rewind_writer.py

1. Overview

packages/format (npm workspace @excelrewind/format) is the contract of the ExcelRewind product: the TypeScript types, binary container codec, replay reducer, encryption envelope, and pure spreadsheet-formula utilities that define what a .rewind file is. It ships no server and no UI — it is a dependency-light library (only @msgpack/msgpack and fflate) imported by every surface that reads or writes a .rewind file: the Excel add-in (apps/addin-excel), the zero-backend web viewer (apps/viewer), the Team console (apps/team), and the Google Sheets add-on (apps/addon-sheets). Per CLAUDE.md: "change the format here and only here."

packages/branding (@excelrewind/branding) is a one-file constants module: every user-facing string (product name, file extension, support email, the tamper-error copy) plus BUILD_TAG, the version string every UI surface displays and that scripts/smoke.mts greps for in a deployed bundle to catch a stale Cloudflare Pages deploy.

Nothing in either package makes a network call, touches the DOM, or calls Office.js — they run identically in a browser tab, a WebView2 Office.js task pane, a Cloudflare Worker, and Node 18+ (crypto.ts and hash.ts key off globalThis.crypto.subtle, which all four environments provide). Build: no bundler step of its own — each package is "main": "src/index.ts" and consumers' Vite/tsc configs compile it in-place as part of their own build. Tests run via npx vitest run from packages/format (13 test files) and are included in the root npm test. scripts/rewind_writer.py is a companion stdlib-only Python re-implementation of the write path, used only as a cross-language contract oracle (§6) — it is not part of the shipped product.

2. Architecture diagram

flowchart TB
  subgraph TYPES["packages/format/src/types.ts"]
    T1["RewindDocument / RewindMeta"]
    T2["CellChangeEvent / Annotation"]
    T3["EncryptSpec / UnlockOptions / EncDescriptor"]
    T4["Recipient (passphrase / org / rsa)"]
    T5["Baseline / GalleryItem / Lineage"]
  end

  subgraph CODEC["container.ts — the ZIP codec"]
    C1["packEntry / unpackEntry (deflate + MessagePack)"]
    C2["writeRewind()"]
    C3["readRewind() / peekRewind()"]
    C4["encryptContainer() / decryptContainer()"]
    C5["boundedFilter() — decompression-bomb caps"]
  end

  subgraph CRYPTO["crypto.ts — pure WebCrypto primitives"]
    X1["encryptBytes / decryptBytes (AES-256-GCM)"]
    X2["wrapKey / unwrapKey"]
    X3["deriveKek (PBKDF2-SHA256, 310k iters)"]
    X4["genRsaKeyPair / rsaWrapKey / rsaUnwrapKey (RSA-OAEP-3072)"]
    X5["makeRecoveryCode()"]
  end

  subgraph KEYRING["keyring.ts — key-row lifecycle"]
    K1["createKeyRow()"]
    K2["unlockKeyRow() / privFromRow()"]
    K3["escrowFromRow() / rewrapPass() / newRecovery()"]
  end

  subgraph PASS["passphrase.ts"]
    P1["checkPassphrase() — length/variety/blocklist gate"]
  end

  subgraph REPLAY["Pure spreadsheet-domain modules"]
    R1["replay.ts — applyEvent / replayTo / GridState"]
    R2["fill.ts — toR1C1 / fromR1C1 / detectFill / expandFill"]
    R3["history.ts — cellHistory()"]
    R4["branch.ts — branchPoint / branchDiff / mergeBranches"]
    R5["extrefs.ts — hasExternalRef / normalizeExternalRefs"]
    R6["spotlight.ts — spotlightCues()"]
    R7["a1.ts — A1 <-> index helpers"]
    R8["hash.ts — sha256Hex()"]
  end

  IDX["index.ts (barrel export = package public API)"]

  subgraph BRAND["packages/branding/src/index.ts"]
    B1["PRODUCT_NAME / FILE_EXTENSION / FILE_NOUN"]
    B2["ERR_TAMPERED / MS_DISCLAIMER"]
    B3["BUILD_TAG"]
  end

  PYORACLE["scripts/rewind_writer.py — stdlib MsgPack+ZIP re-implementation"]

  CODEC --> TYPES
  CODEC --> CRYPTO
  CODEC --> R8
  R1 --> R2
  R2 --> R7
  R3 --> R2
  R3 --> R7
  R4 --> R1
  R6 --> R5
  KEYRING --> CRYPTO
  IDX --> TYPES
  IDX --> CODEC
  IDX --> REPLAY
  IDX --> CRYPTO
  IDX --> KEYRING
  IDX --> PASS
  PYORACLE -. "byte-for-byte mirrors" .-> CODEC

3. Data-flow diagrams

3a. Plaintext write / read round trip

flowchart LR
  DOC["RewindDocument (in memory:
meta, timeline[], annotations[],
baseline?, media?, refs?)"] -->|"writeRewind(doc)"| SORT["sort timeline & annotations by t"]
  SORT --> PACK["packEntry() per component
= deflate(MessagePack(value))"]
  PACK --> HASH["sha256Hex() each entry -> meta.integrity map"]
  HASH --> META["meta.bin = packEntry(RewindMeta incl. integrity)"]
  META --> ZIP["zipSync(entries, level:0)
= .rewind bytes"]
  ZIP -->|"file save (add-in) / download (viewer)"| DISK[(".rewind file on disk
or attached to email/Slack")]
  DISK -->|"readRewind(bytes)"| UNZIP["unzipSync() -> entries map"]
  UNZIP --> METAR["inflate + decode meta.bin"]
  METAR --> VERGATE{"formatVersion <= FORMAT_VERSION?"}
  VERGATE -- no --> ERRV["throw Unsupported format version"]
  VERGATE -- yes --> INTCHK["recompute sha256Hex per entry,
compare to meta.integrity"]
  INTCHK -- mismatch --> ERRT["throw Integrity check failed
(surfaced as ERR_TAMPERED)"]
  INTCHK -- match --> UNPACK["unpackEntry() timeline/annotations/baseline/gallery"]
  UNPACK --> DOC2["RewindDocument back in memory"]

3b. Encrypted container (OPS-6) write / read

flowchart LR
  DOC["RewindDocument"] -->|"writeRewind(doc, encSpec)"| ENTRIES["same plaintext entries as 3a
(timeline.bin, annotations.bin, media/*, refs/*, meta.bin)"]
  ENTRIES --> CEK["randomKey() -> fresh 256-bit CEK"]
  CEK --> WRAP["wrapCek(cek, spec):
wrap CEK per recipient
(passphrase->PBKDF2 KEK, org->OMK, rsa->pubkey)"]
  WRAP --> ENV["EncEnvelope { enc, recipients[], escrows? }"]
  ENTRIES --> SEALFULL["encryptBytes(meta.bin bytes, cek, aad='meta-full.bin')
-> meta-full.bin"]
  ENTRIES --> SEALREST["encryptBytes(each entry, cek, aad=entryName)
-> sealed timeline.bin / annotations.bin / media/* / refs/*"]
  ENV --> METAOUT["meta.bin = packEntry(envelope) -- PLAINTEXT"]
  METAOUT --> ZIPE["zipSync(...) = encrypted .rewind bytes"]
  SEALFULL --> ZIPE
  SEALREST --> ZIPE
  ZIPE -->|"readRewind(bytes, {unlock})"| UNZIPE["unzipSync()"]
  UNZIPE --> READENV["decode meta.bin -> EncEnvelope (plaintext, readable without unlocking)"]
  READENV --> UNWRAP["unwrapCek(envelope, unlock):
try passphrase -> org OMK -> cached RSA priv -> escrow chain"]
  UNWRAP -- "no material / wrong secret" --> ERRU["throw: encrypted / wrong passphrase"]
  UNWRAP -- ok --> CEK2["CEK CryptoKey"]
  CEK2 --> DECALL["decryptBytes() every non-meta.bin entry;
GCM auth fail on any entry -> Integrity check failed"]
  DECALL --> DECFULL["decrypt meta-full.bin -> real RewindMeta"]
  DECFULL --> REST["rest of readRewind runs on now-plaintext entries
(identical to 3a from the integrity sweep onward)"]

3c. Crash-recovery buffer (add-in, IndexedDB)

flowchart LR
  START["recording starts, encryption enabled"] -->|"newBufferKey(spec) in buffer-crypto.ts"| BCEK["fresh buffer-CEK
wrapped to same recipients as the eventual save"]
  BCEK -->|"persist ONCE"| IDB[("IndexedDB:
rewind.active-session envelope")]
  LOOP["every ~1s: draft SessionDraft +
audio/video chunk"] -->|"sealBuffer(bytes, cek)
= encryptBytes(bytes, cek, aad='rewind.recovery-buffer')"| IDB
  CRASH["Excel / tab crash, reopen"] -->|"unlockBufferKey(envelope, unlock)
= unwrapCek() -- same code path as file unlock"| BCEK2["recovered buffer-CEK"]
  BCEK2 -->|"openBuffer(blob, cek) per chunk"| RESTORE["SessionDraft + chunks
restored to resume recording"]

4. Process / sequence diagrams

4a. Record → encrypt → save (add-in)

sequenceDiagram
  participant User
  participant Rec as "addin-excel recorder.ts"
  participant App as "addin-excel App.tsx"
  participant Persist as "persistence.ts / buffer-crypto.ts"
  participant Format as "@excelrewind/format container.ts"
  participant Disk as "local .rewind file"

  User->>Rec: edits cells (Office.js onChanged)
  Rec->>App: normalized CellChangeEvent[]
  App->>Persist: buffer to IndexedDB (sealed, 3c)
  User->>App: click "Stop & Save"
  App->>Format: writeRewind(doc, encSpec?)
  alt encryption OFF (free/starter tier or user opt-out)
    Format-->>Format: zipSync(plaintext entries)
  else encryption ON
    Format->>Format: randomKey() CEK, wrapCek(spec)
    Format->>Format: encryptBytes() every entry, aad=entry name
  end
  Format-->>App: .rewind bytes (Uint8Array)
  App->>Disk: File System Access API / download save
  App->>Persist: clear IndexedDB crash-recovery buffer

4b. Open & unlock an encrypted file (viewer)

sequenceDiagram
  participant User
  participant Viewer as "apps/viewer App.tsx"
  participant Format as "@excelrewind/format container.ts"
  participant Dialog as "UnlockDialog.tsx"

  User->>Viewer: open .rewind (drag/drop or link)
  Viewer->>Format: peekRewind(bytes)
  Format-->>Viewer: {encrypted:true, audioBytes, videoBytes, ...}
  Viewer->>Viewer: getCachedSecret() -- last working secret this session
  alt cached secret matches (same org key)
    Viewer->>Format: readRewind(bytes, {limited:true, unlock:cached})
    Format-->>Viewer: RewindDocument -- silent unlock, no dialog
  else no cached secret / cached secret fails
    Viewer->>Dialog: show unlock prompt
    User->>Dialog: enters passphrase (or recovery code)
    Dialog->>Format: readRewind(bytes, {limited:true, unlock:{passphrase}})
    Format->>Format: unwrapCek() tries recipients, then escrow chain
    alt wrong passphrase
      Format-->>Dialog: throws "Wrong passphrase or key"
      Dialog-->>User: inline error, retry
    else correct
      Format->>Format: decryptContainer() + integrity sweep (bounded, limited:true)
      Format-->>Dialog: RewindDocument
      Dialog->>Dialog: setCachedSecret() -- remember for next file this session
    end
  end
  Viewer->>Viewer: replayTo() renders grid at t=0

4c. Branch merge (add-in App.tsx, rendering BranchMerge.tsx)

sequenceDiagram
  participant User
  participant App as "addin-excel App.tsx"
  participant UI as "BranchMerge.tsx (presentation only)"
  participant Branch as "branch.ts"
  participant Replay as "replay.ts"

  User->>App: pick two same-family .rewind files (a, b)
  App->>Branch: sameFamily(a, b)
  Branch-->>App: false -> abort, "not related sessions"
  App->>Branch: branchDiff(a, b)
  Branch->>Branch: branchPoint(a, b) internally --
walk sorted timelines pairwise until first mismatch
  Branch->>Replay: replayTo(timeline, Infinity, baseline) for both a and b
  Branch-->>App: {branchPointT, per-cell {aFinal, bFinal, conflict}}
  App->>UI: render diff, collect conflict choices
  User->>UI: resolve each conflict (keep a / keep b)
  UI-->>App: choices map
  App->>Branch: mergeBranches(a, b, choices)
  Branch->>Branch: time-shift b's suffix past a's end,
rewrite contradicting from-values against a's final grid,
tag deciding writes source:'merge'
  Branch-->>App: merged RewindDocument (new sessionId "merge-...", lineage set)
  App->>App: writeRewind(merged) -> save new .rewind

4d. Cross-language contract test (LibreOffice port gate)

sequenceDiagram
  participant CI as "vitest (crosslang.test.ts)"
  participant Py as "scripts/rewind_writer.py"
  participant Format as "readRewind() (TS)"

  CI->>CI: pythonAvailable()? (execFileSync python --version)
  alt python missing
    CI-->>CI: describe.skipIf -> suite skipped, CI stays green
  else python present
    CI->>Py: execFileSync python rewind_writer.py <tmpfile>
    Py->>Py: raw-deflate(msgpack(value)) per entry, sha256 integrity map,
ZIP_STORED (no zip-level compression)
    Py-->>CI: session.rewind bytes written to temp dir
    CI->>Format: readRewind(bytes)
    Format->>Format: unzip, verify integrity, decode msgpack
    alt any mismatch (deflate/msgpack framing diverges)
      Format-->>CI: throws -> test fails, port gate blocks merge
    else byte contract honored
      Format-->>CI: RewindDocument matching Python's deterministic_session()
      CI->>CI: assert meta/timeline/annotations/baseline round-trip exactly
    end
  end

5. Interconnections

packages/format and packages/branding perform no I/O of their own — no network calls, no filesystem access beyond what a caller hands them as bytes. Every "interconnection" below is an in-process library import by another workspace package (a monorepo edge, not a wire protocol), except the Python oracle (a subprocess) and the DB-schema mirror (a data-shape contract, not a live call from this package).

flowchart LR
  FMT["packages/format
+ packages/branding"]
  ADDIN["apps/addin-excel"]
  VIEWER["apps/viewer"]
  TEAM["apps/team"]
  SHEETS["apps/addon-sheets"]
  SMOKE["scripts/smoke.mts"]
  PY["scripts/rewind_writer.py"]
  DB[("Supabase org_keys / user_keys
(backend-data)")]

  FMT -->|"writeRewind / readRewind / peekRewind / branch.ts / keyring.ts (via keyring-client.ts) / wrapCek / unwrapCek (buffer-crypto.ts)"| ADDIN
  FMT -->|"readRewind(limited:true) / peekRewind / replayTo / branchDiff / spotlightCues / UnlockOptions"| VIEWER
  FMT -->|"createKeyRow / unlockKeyRow / rewrapPass / newRecovery (keyring.ts, Encryption.tsx only)"| TEAM
  FMT -->|"CellChangeEvent / Annotation types, writeRewind (bundled sidebar.html)"| SHEETS
  FMT -->|"BUILD_TAG (branding)"| SMOKE
  PY -.->|"byte-for-byte mirrors container.ts; verified by crosslang.test.ts"| FMT
  FMT -.->|"KeyRowFields column-neutral shape matches"| DB

6. Key functions & files

7. Invariants & gotchas