The Boardflare Add-in

Add-in installation, task pane, Edit vs. App mode, and shared runtime cold start.

This section describes the installation, user interface, execution model, task pane, and lifecycle of the Boardflare Office Add-in in Microsoft Excel.

Installing and Opening the Add-in

The Boardflare add-in runs as an Office Web Add-in in Microsoft Excel desktop (Windows and macOS) and Excel on the web.

Installation

• Microsoft AppSource / Office Store: In Excel, go to Home > Add-ins > More Add-ins, search for Boardflare, and select Add.
• Admin Deployment: Organizations can deploy Boardflare centrally through the Microsoft 365 Admin Center to users or groups.

Opening the Add-in

• Click the Boardflare button in the Excel ribbon (typically on the Home tab) to open the task pane.

Task Pane Navigation

The task pane provides three main tabs: 1. Notebook Tab: The primary interactive surface. Houses the reactive Marimo authoring interface (Edit mode) or the full-pane application view (App mode). 2. Templates Tab: A gallery of pre-built workbook templates published by Boardflare. Cards allow previewing templates and downloading them directly. Opening or switching to Templates does not disrupt background calculation. 3. Support Tab: Documentation links, access to the copyable llms.txt URL, diagnostic status, and legacy editor preferences.

Operating Modes: Edit vs. App Mode

• Edit Mode: Displays the standard Marimo authoring UI with code cells, cell controls, run controls, error messages, and package status. Used by developers and AI agents to author and modify notebook logic.
• App Mode: Presents a clean, full-pane interactive application UI. Code cells are hidden, and only UI widgets (inputs, dropdowns, charts, sliders, markdown text) are displayed. The Boardflare status footer is collapsed, offering a native application experience for end users.

Switching and Persisting the Mode

• In Edit mode, the footer selector allows toggling Open as: Edit or Open as: App.
• Selecting a mode stages the preference without remounting the active notebook; the footer displays Save required. Saving the notebook persists this preference to the workbook so that future sessions open in the selected mode. Choosing the already-saved mode again clears the staged change without requiring a save.
• The selector is disabled until the notebook is ready, has been saved at least once, has no unsaved source changes, and has no save in progress. Save the notebook before changing the mode.
• In App mode, users can click the small pencil icon (Edit notebook) to switch temporarily to Edit mode for the current session without altering the saved workbook preference. The edit session starts fresh from the saved source.
• The embedded notebook offers no AI features. AI assistants edit the notebook through the code sheet, as described in Workbook Editing.

Saving and Persistence Lifecycle

Saving a Boardflare notebook involves two distinct stages: 1. Marimo Serialization: The Marimo kernel serializes all code cells and sends them to Boardflare’s FileStore. 2. Workbook Persistence: Boardflare writes the source cells into the hidden _BOARDFLARE worksheet and verifies the stored content.

What Triggers a Save

• In Edit mode, Marimo autosaves an edited notebook about one second after the last edit, and the user can also save with Marimo’s Save control or its keyboard shortcut. Marimo saves only a notebook it considers edited, so opening a notebook never writes to the workbook.
• Autosave keeps the code sheet in step with the pane, so an AI assistant reading the sheet sees pane edits. A reload requested through the request counter (H1) waits for saves already in progress but not for an edit still inside the one-second autosave delay.
• If the code sheet was changed outside the editor (for example by undo, another user, or an AI assistant) after the pane loaded it, the next save does not overwrite it. The pane shows Notebook changed outside the editor once, with the choice to reload the changed notebook (discarding the pane’s unsaved edits) or to overwrite it with the pane’s version.
• Restarting the notebook, replacing the mode, or closing the pane saves what Marimo has already handed over; it cannot recover edits Marimo has not yet saved.

Status Footer Indicators

The footer at the bottom of the task pane reflects the authoritative persistence state. Marimo’s own clean indicator only means the source was handed to Boardflare, so rely on the footer: - Starting: The runtime frontend is booting. - Startup failed: Runtime initialization encountered a fatal error. - Not saved: No durable notebook source has been persisted to this workbook yet. - Saving…: Source was received and is being written and verified in the workbook. - Unsaved: There are unsaved edits and autosave is off (for example ?autosave=off), so they wait for a manual save. - Saved: The notebook was successfully written to the worksheet and verified. - Save failed: Persistence or verification failed. - Save required: An opening mode (Edit/App) change has been staged but not yet saved. - Session saved: A website demo notebook was saved in the page’s memory only (see Website demos).

The footer also holds a button to download the notebook as a Marimo .py file and, in Excel and Google Sheets, a button to upload one (see Uploading and Importing Python Scripts). App mode hides the footer.

Always wait for Saved before closing the workbook or relying on persisted changes.

Reset and Recovery

A recovery strip appears when the notebook cannot load or start, or when a reset fails. Ordinary save failures stay in the footer and the error strip, and do not discard the current session.

• Retry stops the failed session and starts another from the current saved source. A failed App startup retries in Edit mode so the source can be inspected.
• Reset saved notebook clears the notebook from the workbook, verifies that, and opens the starter notebook in Edit mode. Marimo edits not saved with Save are lost, so an active Edit session asks for confirmation first.
• Restore saved notebook appears instead after an uploaded file fails to load; it discards the upload and restores the last saved notebook.
• Reset and Retry do not preserve live inputs, outputs, functions, or kernel state; running the notebook rebuilds them.

Shared-Runtime Cold Start

Excel custom functions (=BF.OUTPUT(...) and =BF.FUNCTION(...)) and the task pane share a single long-lived Office shared runtime (taskpane.html).

Key Invariants

• Background Execution: When a workbook opens or recalculates, Excel automatically initializes the shared runtime in the background to evaluate BF.OUTPUT and BF.FUNCTION formulas. The user does not need to click the ribbon icon or open the task pane.
• Calculation Without Visible UI: The notebook runtime initializes Pyodide, restores the saved notebook from the worksheet, executes the cells, and registers published outputs behind the scenes.
• Formulas Wait for Ready State: While the runtime initializes, formulas remain in Excel’s native #BUSY! state. Once the notebook finishes evaluating and publishes its outputs, formulas resolve to their calculated values automatically. If the user later opens the task pane, it connects to the exact same running session.

Website Demos (Web Host)

Template pages on boardflare.com run notebooks in a browser-hosted spreadsheet with the same notebook surface as Excel.

• Session-only saves: Save keeps the notebook in the page’s memory and the footer shows Session saved. Reloading the page restores the notebook the template shipped with.
• Reset template notebook restores the template’s notebook and its configured opening mode.
• Opening mode: A template opens in Edit or App mode as configured.
• Cell number formats: A published date or time arrives as a serial number and shows with the destination cell’s own number format, so format those cells as dates. Text results that parse as numbers, dates, percentages, or currency (such as "2026-06-22" or "12%") are converted to numbers by the website spreadsheet, whereas Excel keeps them as text.
• BF.FUNCTION: Calls run once per formula evaluation rather than as a streaming subscription. publication.consumers lists each formula cell that uses a published name.
• Error results: A failing formula shows text that starts with #ERROR: instead of an Excel error value. An unpublished name gives #ERROR: Unknown notebook output: <name> or #ERROR: Unknown notebook function: <name>, and a function or output that does not answer in time gives #ERROR: Notebook function timed out or #ERROR: Notebook output timed out.

Sharing Workbooks

• Self-Contained in .xlsx: The entire Marimo notebook source, dependency header, and opening mode preference are stored inside the hidden _BOARDFLARE worksheet. The application travels with the workbook without requiring external .py script files or cloud notebooks.
• Recipients with Boardflare: Anyone opening the workbook with the Boardflare add-in installed can immediately run, interact with, and edit the notebook.
• Recipients without Boardflare: If a recipient opens the workbook without Boardflare installed, Excel displays the last saved calculated cell values. If the sheet is recalculated, cells containing =BF.OUTPUT(...) or =BF.FUNCTION(...) will display #NAME? until the Boardflare add-in is enabled.

Legacy Editor Compatibility

The legacy Editor (BOARDFLARE.EXEC) is an individual-function Python editor. - Legacy Editor workbooks remain fully supported. The Editor tab appears automatically if the workbook contains legacy functions or if Always show legacy editor is enabled in Support preferences. - The legacy execution path is completely isolated from the Notebook runtime. - All new development should use the reactive Marimo Notebook environment.

Google Sheets

Boardflare is also available as an Editor add-on for Google Sheets, powered by the hosted web runtime and Apps Script container integration.

Supported Capabilities

• Marimo Notebook Surface: Authors and users have access to the standard reactive Marimo notebook environment directly inside the Google Sheets sidebar.
• Workbook Source Persistence: Notebook source is saved within Google Sheets DocumentProperties, traveling with the document across copies and shares.
• Workbook Inputs (bf.inputs): Read data into Python using bf.inputs(). Supports active-sheet A1 addresses, sheet-qualified A1 addresses (e.g. "Sheet1!A1:D100"), and Google Sheets named ranges.
• Manual Refresh: Active bf.inputs() bindings rehydrate via a manual Refresh button in the sidebar.
• Pre-Bundled Companion Packages: All 15 pre-bundled pure-Python companion wheels (seaborn, plotly, humanize, openpyxl, babel, etc.) are available for immediate import without external network calls.
• Security Sandbox: Notebook code runs in the same zero-network Pyodide WebAssembly child iframe under a strict connect-src 'self' Content Security Policy.

Unsupported Capabilities

Google Sheets does not support: - bf.selection() table selections. - bf.publish() and =BF.OUTPUT(). - BF.FUNCTION() or calling Python functions directly from Google Sheets worksheet formulas. - Automatic background polling or change triggers (updates require clicking the Refresh button). - Direct workbook range writes from Python.

Unsupported features fail explicitly rather than silently altering semantics.