By default, InkRider stores notebooks in your browser's IndexedDB. While IndexedDB allows local storage to grow very large, it is tied to your local browser profile and subject to manual, automatic, or policy-based browser cache erasure (particularly in Microsoft Edge WebView2 environments used by Office Add-ins). If a user clears their browser cache or an IT cleanup policy runs, local IndexedDB assets can be wiped without warning.

Embedding a notebook writes a complete copy of it directly into the .docx file itself using CustomXML. This makes the notebook a permanent part of the document, protecting it from browser cache erasure and ensuring it travels with the document.

---

How Embedding Works

Word documents (.docx) are ZIP archives internally. They contain a CustomXML section where applications can store structured data alongside the document content. InkRider uses this section to store notebook JSON, compressed and checksummed.

When you embed a notebook:

1. InkRider serializes the notebook to JSON (full content: cells, outputs, metadata).
2. If the notebook is large, the JSON is GZIP-compressed and encoded as base64 before storage.
3. A SHA-256 checksum of the uncompressed content is computed and stored alongside the data.
4. The result is written as a CustomXML part inside the DOCX.

Opening the document on another machine, InkRider reads the CustomXML, verifies the checksum, decompresses the data if needed, and loads the notebook into the local IndexedDB.

---

Integrity Checks

Every embedded notebook carries a sha256: checksum in its metadata. InkRider verifies the checksum in two situations:

• On load: when the document is opened, InkRider reads the embedded data and confirms the checksum matches before loading it. A mismatch means the file was modified outside InkRider (e.g., an external tool corrupted the CustomXML). InkRider reports the failure and does not overwrite working local data with potentially corrupt data.

• Before push: when you push a local update to the embedded copy, InkRider computes the checksum of what it is about to write and stores it, so the next load can verify it.

Checksums also act as a fast-skip mechanism: if the checksum of the local copy matches the checksum of the embedded copy, InkRider skips the push because nothing changed.

What this check does and does not do. The SHA-256 checksum detects accidental corruption and edits made by tools that are unaware of the InkRider format. It is not a security guarantee against a determined attacker who also has InkRider: they could use InkRider itself to modify the notebook and the checksum would update legitimately. For stronger guarantees, use Passphrase Protection (see below).

---

Passphrase Protection

Passphrase protection adds cryptographic authentication on top of the basic checksum. When enabled, every embedded copy of the notebook is signed with an HMAC-SHA256 tag derived from a passphrase you choose. A recipient (or attacker) who does not know the passphrase cannot modify the notebook in a way that goes undetected, even when using InkRider itself.

How it works:

1. When you enable protection, InkRider asks you to create a passphrase for the document.
2. On every push, InkRider uses PBKDF2 (310 000 iterations, SHA-256) to derive a key from the passphrase and a fresh random salt, then computes an HMAC-SHA256 over the notebook content.
3. The HMAC and the salt are stored in the CustomXML alongside the checksum.
4. On load, if a protection tag is present, InkRider asks for the passphrase and verifies the HMAC before loading the content. A mismatch means the content was altered by someone who did not know the passphrase.

Collaboration: All people who are allowed to edit the embedded notebook must know the passphrase. Share it out-of-band (e.g., a secure messaging channel). Any legitimate collaborator who makes a change uses their copy of InkRider, enters the passphrase, and the new HMAC is stored automatically on push.

Removing protection: Open the asset inspector, click Manage Protection, verify the current passphrase, then choose Remove. The next push will embed the notebook without an HMAC tag.

⚠️ The passphrase cannot be recovered. InkRider never sends it to any server. If you forget it, the content remains in your local IndexedDB, but the embedded DOCX copy becomes unreadable to InkRider's protection check. Treat it with the same care as a file encryption key.

---

Sync States

Each embedded asset has a sync state visible in the VFS Explorer:

State	Meaning
Local only	The asset exists in IndexedDB but has never been embedded.
Synced	IndexedDB and DOCX copies have matching checksums.
Pending push	The local copy is newer. Push to update the DOCX.
Remote ahead	The DOCX copy is newer (e.g., the document came from a colleague). Pull to update locally.
Conflict	Both copies were modified independently. Resolve manually.

---

Pushing and Pulling

Push (local → DOCX)

Click Push in the VFS Explorer or the asset inspector to write the current local version into the DOCX. This is what you do when you have been editing a notebook locally and want to save it into the document before sharing.

InkRider also auto-pushes on certain saves if the notebook has the auto-embed option enabled.

Pull (DOCX → local)

Click Pull to overwrite the local IndexedDB copy with whatever is embedded in the DOCX. This is what you do after receiving a document from a colleague who edited notebooks on their machine.

InkRider warns before overwriting local changes.

Conflict Resolution

When both copies differ (conflict state), InkRider shows a side-by-side diff view and asks which version to keep. Choose local to keep your version, remote to take the DOCX version, or cancel to leave the conflict unresolved.

---

Embedding a Notebook Folder

The standard embed stores a single notebook file. If you want a notebook's entire data folder (scripts, data files, binary assets it depends on) to travel with the document too, enable Embed folder in the embed dialog.

This embeds every asset under the notebook's VFS folder as separate CustomXML parts, reconstructing the full working environment when the document is opened on another machine.

---

When to Use Embedding

Embedding makes sense when:

• you share the document with someone who will also use InkRider and needs to be able to rerun the code
• you want a single portable file that is fully self-contained (no cloud, no separate file transfer)
• you are archiving a document and want the computation record to stay with it

Embedding is optional. If you work on a single machine and never share documents that need to be re-executed, you do not need to embed anything.

---

Size Considerations

Embedded notebooks add to the .docx file size. InkRider compresses large notebooks automatically, which keeps the overhead manageable in most cases. Very large notebooks (with many large outputs, especially images or data frames) can grow significantly. The Storage Monitor tool shows the current embedded size breakdown per document.

If a notebook exceeds the safe size limit for CustomXML storage, InkRider warns before embedding and suggests reducing output size (for example, by clearing old outputs before embedding).

---

Change Detection

InkRider's DOCX change poller monitors the document in the background and detects when the embedded CustomXML is modified by an external process (a sync tool, an antivirus scanner, or Word's own recovery mechanism). When a change is detected, the relevant assets transition to remote ahead state and the user is notified.