Virtual Filesystem
How InkRider's virtual filesystem works, how to navigate it with VFS Explorer, and how Python code accesses files at runtime.
InkRider maintains a virtual filesystem (VFS) for every Word document you work in. The VFS stores your notebooks, scripts, data files, and binary assets in an organized folder tree. It is the primary way the add-in manages files between editing sessions.
Two Storage Layers & Reliability Best Practices
The VFS has two storage backends that work together:
Local VFS (IndexedDB)
The primary storage is IndexedDB, a browser-native database that persists across page reloads. All of your notebooks and files are stored here by default. The local VFS is:
- fast to read and write (no network round-trip)
- private to your browser profile
- capable of growing very large to support heavy project workspaces and large local datasets
- available offline
⚠️ CRITICAL WARNING ON STORAGE RELIABILITY: Because IndexedDB storage is tied to your local browser profile, it is subject to manual, automatic, or policy-based browser cache erasure in Microsoft Edge WebView2 environments used by Office Add-ins. For example, a user manually clearing browser storage, using the browser's 'Clear browsing data' feature, or automated IT policy enforcement, or cleanup tools can wipe browser storage without warning.
Therefore, InkRider's local VFS should NEVER be relied upon for permanent, reliable storage.
Recommended Storage Strategy
To protect your work from unexpected browser cache erasure, you can adopt the following dual-layer strategy:
- Document Embedding (for Small Assets & Notebooks): Use the Embedded VFS to store notebooks, scripts, and lightweight configuration files directly inside the
.docxCustomXML structure. This ensures your code travels reliably with the document. - OneDrive Integration (for Large Files & Datasets): Use OneDrive Integration (
/drive/cloud/) for large CSVs, heavy Excel spreadsheets, and binary archives. Cloud storage guarantees persistence and enterprise backup protection.
Folder Structure
The VFS uses POSIX-style paths. Each document starts with the following conventional folders:
| Path | Contents |
|---|---|
/notebooks/ |
.ipynb notebooks |
/scripts/ |
.py Python scripts |
/data/ |
Data files used by notebooks |
/assets/ |
Images and other binary assets |
/jupyter/ |
Mount point for JupyterLite (see below) |
You can create additional folders, rename folders, and move files freely. Folders are virtual (represented by a marker file internally) and require no special creation step. Creating a file at a new path creates the folder automatically.
Asset Types
| Type | Extension(s) | Executable | Notes |
|---|---|---|---|
| Notebook | .ipynb |
Yes | Visual cell grid; full execution support |
| Script | .py |
Yes | Raw editor; # %% cell markers |
| QMD | .qmd |
Yes | Quarto Markdown; visual/raw toggle |
| Text | .md, .txt, .csv, .json, … |
No | Raw text editor |
| Binary | .png, .jpg, .xlsx, … |
No | Stored as bytes; accessible from Python |
| Folder | (marker) | N/A | Organizational container |
VFS Explorer
The VFS Explorer is the main UI for browsing and managing files. Open it from the tools panel (folder icon in the add-in header).
Tree Navigation
The left pane shows a collapsible folder tree for each open document. Click any folder to expand it. Click a file to select it and show details in the inspector panel on the right.
Double-click a notebook or script to open it in an editor tab.
Search and Filter
Use the search box at the top of the Explorer to filter visible files by name. The tree collapses to show only matching paths.
Context Menu
Right-click any file or folder to access:
| Action | Description |
|---|---|
| Open | Open in editor tab |
| Rename | Rename in place |
| Delete | Delete permanently |
| Embed in document | Copy asset to DOCX CustomXML storage |
| Push to document | Push local changes to the embedded copy |
| Pull from document | Overwrite local copy with the embedded version |
| Download | Download as a file to your OS |
| Move to folder | Move to a different VFS folder |
Inspector Panel
Selecting a file opens the Inspector on the right side of the Explorer. The Inspector shows:
- file name, path, type, and size
- creation and last-modified timestamps
- sync status (see below)
- checksum (SHA-256, for embedded assets)
- quick actions (open, embed, download)
Sync Status Badges
Each asset displays a badge indicating its sync state with the DOCX embedded storage:
| Badge | Meaning |
|---|---|
| Local only | In IndexedDB; not yet embedded in DOCX |
| Synced | IndexedDB and DOCX copies match |
| Pending push | Local version is newer; push to update DOCX |
| Remote ahead | DOCX version is newer; pull to update locally |
| Conflict | Both versions changed independently |
Drag-and-Drop in the Explorer
You can drag files between folders within the VFS Explorer to move them. You can also drag OS files from Windows Explorer into the Explorer panel to trigger the import flow.
Multi-Select
Hold Shift or Ctrl and click to select multiple files. The context menu then applies actions to all selected items at once (delete, move, embed).
Accessing VFS Files from Python
When running code in the JupyterLite runtime, InkRider mounts the VFS as a Jupyter contents provider. This means your Python code can read and write VFS assets using ordinary file paths under /jupyter/:
# Read a CSV file from the VFS
import pandas as pd
df = pd.read_csv("/jupyter/data/sales.csv")
# Write a result back to the VFS
df.to_csv("/jupyter/data/sales_cleaned.csv", index=False)
Changes written to /jupyter/ paths are reflected immediately in the VFS Explorer. Binary assets can also be read as bytes:
with open("/jupyter/assets/logo.png", "rb") as f:
image_bytes = f.read()
The Pyodide (browser) runtime uses the same mounting mechanism through the same custom contents provider.
Cloud Files via OneDrive
The VFS Explorer also shows a Cloud section that lists files accessible through connected OneDrive storage. These files live in OneDrive (not in the local VFS) and are accessible from Python at /drive/cloud/. See OneDrive Integration for details.
Storage and Limits
InkRider monitors the size of your virtual filesystem and warns when assets approach size limits. Very large notebooks are automatically chunked into multiple IndexedDB records to stay within browser storage limits, then reassembled transparently when you open them.
You can view storage usage in the Storage Monitor tool (available from the developer tools panel).