Make it easier to statically embed buckaroo

[paddymul]

Checks

• I have checked that this enhancement has not already been requested

How would you categorize this request. You can select multiple if not sure

Other (please describe in Issue Description)

Enhancement Description

Currently to get the real buckaroo experience you need the notebook or a tornado server. This is a heavyweight ask for embedding. For many usecases notably streamlit and xorq integration a simpler experience is desired. This will be a static only buckaroo expreience

Note, initially search, sort, postprocessing functions and the lwocode ui wont work on this experience. search and sort are probably easy to add back in as JS only features.

Pseudo Code Implementation

the user should call prepare_buckaroo_artifact(df:pd.DataFrame|pl.DataFrame|Path('parquet_file')) which produces a single json or b64 encoded string to be served to buckaroo by the frontend.

on the frontend you should be able to call a react component with
<BuckarooTable config={...} artifact={prepared_artifact}/>

Prior Art

I'll just use this for questions.

I have a PR exploring apache flechette and removing hyparquet. #546
I would imagine that parquet is a notably better storage format than flechette, but this needs to be proven out.

Summary stats need to be packaged into the same object.

[paddymul]

Implementation Plan

Overview

Add a to_html() method that produces a self-contained HTML file embedding Buckaroo's JS and the serialized DataFrame data.

Steps

1. Python: to_html() method on BuckarooWidget / BuckarooInfiniteWidget:

   • Serialize the DataFrame to JSON or Parquet (base64-encoded)
   • Serialize column configs, pinned rows, summary stats
   • Generate an HTML template with:
     • Inline <script> tag containing bundled Buckaroo JS (or a CDN link)
     • Inline <script> tag with the serialized data as a JS variable
     • A <div id="buckaroo-root"> mount point
   • Return the HTML string or write to file

2. JS: Standalone entry point — create a standalone.js bundle (may already exist in public/) that:

   • Reads data from a global variable or inline script
   • Renders the AG Grid table into the mount point
   • No WebSocket/server dependency

3. CDN option — optionally reference Buckaroo JS from a CDN (unpkg/jsdelivr) instead of inlining, to reduce file size. Make this configurable.

4. Tests:

   • Unit test: to_html() returns valid HTML with expected structure
   • Integration: open the HTML in a headless browser (Playwright), verify the table renders

Files to modify

• buckaroo/buckaroo_widget.py — to_html() method
• packages/buckaroo-js-core/ — standalone bundle entry point
• Templates / HTML generation

@codex

[chatgpt-codex-connector]

Summary

• Added a new standalone export path on BuckarooWidgetBase:
  • _build_static_state() now assembles a websocket-free payload containing dataframe rows, display args, summary stats, and buckaroo runtime state.
  • to_html() now generates a full HTML document, supports returning a string or writing to disk, supports inline vs CDN JS, and can inline CSS for a self-contained artifact. buckaroo/buckaroo_widget.pyL248-L320
• Updated the standalone browser entrypoint to support a static boot mode:
  • Introduced a StaticModel implementing the same minimal model API shape used by the React components.
  • main() now checks window.__BUCKAROO_STATIC_STATE__ and renders from that payload without requiring a websocket connection, while keeping the existing websocket flow as fallback. packages/js/standalone.tsxL8-L44 packages/js/standalone.tsxL239-L302
• Added unit tests for the new HTML export behavior, including coverage for both regular and infinite widgets embedding static state into generated HTML. tests/unit/to_html_test.pyL6-L25

Testing

• ✅ python -m py_compile buckaroo/buckaroo_widget.py
• ⚠️ pytest -q tests/unit/to_html_test.py (environment limitation: system Python in this container does not have pandas installed)
• ⚠️ ./.venv/bin/pytest -q tests/unit/to_html_test.py (environment limitation: anywidget import expects buckaroo/static/widget.js, which is not present in this checkout/build state)
• ⚠️ cd packages/js && npm run build:standalone (environment limitation: JS workspace dependency buckaroo-js-core dist/workspace resolution is unavailable in this container state)

Committed on the current branch and created a PR via make_pr with title: “Add static to_html() export path and standalone bootstrap fallback”.

View task →

[paddymul]

Related: Open PR #560

PR #560 (feat: static embedding for serverless buckaroo rendering) implements this feature on a branch. It includes:

• buckaroo/artifact.py with prepare_buckaroo_artifact() and to_html() methods
• JS component: BuckarooStaticTable.tsx
• Playwright tests: static-embed.spec.ts

This PR needs review/merge to close this issue.