From 3a12c8672e76a5c20df9bd2ef559255c1c7891dd Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 14:13:14 -0400
Subject: [PATCH 01/29] docs: add initial content plan draft

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/content-plan.md | 62 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/content-plan.md

diff --git a/docs/content-plan.md b/docs/content-plan.md
new file mode 100644
index 00000000..2217e838
--- /dev/null
+++ b/docs/content-plan.md
@@ -0,0 +1,62 @@
+
+# Dastardly Dataframe Dataset
+
+Static addition to docs,  pandas code blocks of weird dataframes, then the statically rendered bukaroo widget
+
+talk about the dastardly dataframe dataset, and why these dataframes are generally hard to display,  what little things trip people up
+
+Note that although the types are rare, because buckaroo is built not as a customized table widget for use in dashboards but a way to see dataframes as they are in data workflow systems, being able to display all types is pretty important.
+
+Also note that this is a static embedding of the DFViewer, part of the new DFViewer embeddable system so you can integrate buckaroo into your apps simply.  more coming on the embeddable buckaroo
+
+# DDD for polars
+
+new release of the buckaroo static embedding that now supports polars.  once again talk about the DDD.  specifically https://github.com/buckaroo-data/buckaroo/issues/622
+
+# Static embedding improvements
+
+## publish the JS to a CDN -> reduced embed size talk about size reductions
+talk about how I bult this to better share what buckaroo is doing.  At first you needed to download jupyter and buckaroo.  Then Marimo Pyodide, now static embedding, now smaller static embedding
+
+does pageweight even matter, well to buckaroo it does, to dbt, apparently not, their home page is 501KB compressed 801KB raw,  the whole thing is 28Mb, DOM Content loaded in 1.41 seconds (This buckaroo page will be better of course,  the old version will probalby be better)
+
+Snowflake 128kb/1.28mb/22.51mb/445ms
+
+Databricks 127kb/797kb/313ms
+
+## Customizing buckaroo via api for embeds
+show some styling, link to styling docs
+
+## Static search
+
+Maybe,  take a crack at it
+
+Link to the static embedding guide
+
+## Styling buckaroo chrome
+based on 
+https://github.com/buckaroo-data/buckaroo/pull/583
+
+# Buckaroo embedding guide
+
+Why to embed buckaroo
+Which config makes sense for you - along with data sizes reasoning
+Customizing appearache
+Cusomizing buckaroo
+
+# embedding buckaroo for bigger data
+Parquet range queries on s3/r2 buckets
+sponsored by cloudflare?
+
+
+
+
+## Help me work through a content plan.
+
+what other features have I recently released that desereve blog posts?
+Should I just start here?
+
+Where do these fit into the docs site?
+
+
+

From 519a4baa37d0d6a55320a68abfb9fbb87a0fa8d0 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 16:36:34 -0400
Subject: [PATCH 02/29] docs: add blog articles, DDD static embed generator,
 and RTD build step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Post 1: Dastardly DataFrame Dataset with inline iframe embeds
- Post 3: Static Embedding & the Incredible Shrinking Widget
- Post 5: Buckaroo Embedding Guide
- Post 8: BuckarooCompare — Diff Your DataFrames
- Script to generate DDD static HTML pages at docs build time
- RTD config runs generate_ddd_static_html.py before copying extra-html
- Fleshed out content-plan.md with 9-post publishing sequence

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/buckaroo-compare.rst     | 208 +++++++
 .../articles/dastardly-dataframe-dataset.rst  | 518 ++++--------------
 docs/source/articles/embedding-guide.rst      | 254 +++++++++
 docs/source/articles/static-embedding.rst     | 180 ++++++
 scripts/generate_ddd_static_html.py           |  13 +-
 5 files changed, 748 insertions(+), 425 deletions(-)
 create mode 100644 docs/source/articles/buckaroo-compare.rst
 create mode 100644 docs/source/articles/embedding-guide.rst
 create mode 100644 docs/source/articles/static-embedding.rst

diff --git a/docs/source/articles/buckaroo-compare.rst b/docs/source/articles/buckaroo-compare.rst
new file mode 100644
index 00000000..04874b47
--- /dev/null
+++ b/docs/source/articles/buckaroo-compare.rst
@@ -0,0 +1,208 @@
+BuckarooCompare — Diff Your DataFrames
+=======================================
+
+When you change a pipeline, how do you know what changed in the output? When
+you migrate a table from one database to another, how do you verify the data
+matches? When two teams produce different versions of the same report, where
+are the differences?
+
+You diff them. But ``df1.equals(df2)`` returns a single boolean, and
+``df1.compare(df2)`` only works if the DataFrames have identical shapes and
+indexes. Real-world comparisons are messier: rows may be reordered, columns
+may be added or removed, and the join key might not be the index.
+
+Buckaroo's ``col_join_dfs`` function handles all of this and renders the
+result as a color-coded interactive table where differences jump out
+visually.
+
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    from buckaroo.compare import col_join_dfs
+    import pandas as pd
+
+    df1 = pd.DataFrame({
+        'id': [1, 2, 3, 4],
+        'name': ['Alice', 'Bob', 'Charlie', 'Diana'],
+        'score': [88.5, 92.1, 75.3, 96.7],
+    })
+
+    df2 = pd.DataFrame({
+        'id': [1, 2, 3, 5],
+        'name': ['Alice', 'Robert', 'Charlie', 'Eve'],
+        'score': [88.5, 92.1, 80.0, 81.0],
+    })
+
+    merged_df, column_config_overrides, eqs = col_join_dfs(
+        df1, df2,
+        join_columns=['id'],
+        how='outer'
+    )
+
+The function returns three things:
+
+1. **merged_df**: The joined DataFrame with all rows from both inputs,
+   plus hidden metadata columns for diff state
+2. **column_config_overrides**: A dict of buckaroo styling config that
+   color-codes each cell based on whether it matches, differs, or is
+   missing from one side
+3. **eqs**: A summary dict showing the diff count per column — how many
+   rows differ for each column
+
+
+How the diff works
+------------------
+
+``col_join_dfs`` performs a ``pd.merge`` on the join columns, then for each
+data column:
+
+- Creates a hidden ``{col}|df2`` column with the df2 value
+- Creates a hidden ``{col}|eq`` column encoding the combined state:
+  is the row in df1 only, df2 only, both-and-matching, or both-and-different?
+- Generates a ``color_map_config`` that maps these states to colors
+
+The color scheme:
+
+.. list-table::
+   :header-rows: 1
+
+   * - State
+     - Color
+     - Meaning
+   * - df1 only
+     - Pink
+     - Row exists in df1 but not df2
+   * - df2 only
+     - Green
+     - Row exists in df2 but not df1
+   * - Match
+     - Light blue
+     - Row in both, values identical
+   * - Diff
+     - Dark blue
+     - Row in both, values differ
+
+Join key columns are highlighted in purple so you can immediately see what
+was used for matching.
+
+
+The eqs summary
+---------------
+
+The third return value tells you at a glance where the differences are:
+
+.. code-block:: python
+
+    >>> eqs
+    {
+        'id': {'diff_count': 'join_key'},
+        'name': {'diff_count': 2},      # 2 rows differ
+        'score': {'diff_count': 1},      # 1 row differs
+    }
+
+Special values:
+
+- ``"join_key"`` — this column was used for matching, not compared
+- ``"df_1"`` — column only exists in df1
+- ``"df_2"`` — column only exists in df2
+- An integer — number of rows where values differ
+
+
+Using it with the server
+------------------------
+
+The buckaroo server exposes a ``/load_compare`` endpoint that loads two
+files, runs the diff, and pushes the styled result to any connected browser:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8888/load_compare \
+      -H "Content-Type: application/json" \
+      -d '{
+        "session": "my-session",
+        "path1": "/data/report_v1.csv",
+        "path2": "/data/report_v2.csv",
+        "join_columns": ["id"],
+        "how": "outer"
+      }'
+
+The response includes the diff summary:
+
+.. code-block:: json
+
+    {
+      "session": "my-session",
+      "rows": 5,
+      "columns": ["id", "name", "score"],
+      "eqs": {
+        "id": {"diff_count": "join_key"},
+        "name": {"diff_count": 2},
+        "score": {"diff_count": 1}
+      }
+    }
+
+The browser view updates immediately with the color-coded merged table.
+Hover over any differing cell to see the df2 value in a tooltip.
+
+
+Multi-column joins
+------------------
+
+.. code-block:: python
+
+    merged_df, overrides, eqs = col_join_dfs(
+        df1, df2,
+        join_columns=['region', 'date'],
+        how='inner'
+    )
+
+Composite join keys work naturally. Both ``region`` and ``date`` will be
+highlighted in purple.
+
+
+Use cases
+---------
+
+**Data migration validation**
+    Migrating from Postgres to Snowflake? Export both tables, diff them.
+    The color coding immediately shows which rows are missing and which
+    values changed.
+
+**Pipeline output comparison**
+    Changed a transform? Diff the before and after. The ``eqs`` summary
+    tells you exactly which columns were affected and by how many rows.
+
+**A/B test result inspection**
+    Compare experiment vs control DataFrames on a user ID join key. See
+    which metrics actually differ.
+
+**Schema evolution**
+    When df2 has columns that df1 doesn't (or vice versa), those columns
+    are marked as ``"df_1"`` or ``"df_2"`` in the eqs summary, so you
+    can see schema changes alongside data changes.
+
+
+Integration with datacompy
+--------------------------
+
+The ``docs/example-notebooks/datacompy_app.py`` example shows how to use
+`datacompy <https://github.com/capitalone/datacompy>`_ for metadata-rich
+comparison (column matching stats, row-level match rates) while using
+buckaroo for the visual rendering.
+
+This gives you the best of both: datacompy's statistical summary plus
+buckaroo's interactive, color-coded table view.
+
+
+Limitations
+-----------
+
+- Join columns must be unique in each DataFrame (no many-to-many joins).
+  If duplicates are detected, ``col_join_dfs`` raises a ``ValueError``.
+- Column names cannot contain ``|df2`` or ``__buckaroo_merge`` (these are
+  used internally).
+- Very large DataFrames (>100K rows) will work but the browser may be slow
+  to render the full color-coded table.
diff --git a/docs/source/articles/dastardly-dataframe-dataset.rst b/docs/source/articles/dastardly-dataframe-dataset.rst
index 1aaa2023..5f03e725 100644
--- a/docs/source/articles/dastardly-dataframe-dataset.rst
+++ b/docs/source/articles/dastardly-dataframe-dataset.rst
@@ -4,48 +4,24 @@ The Dastardly DataFrame Dataset
 Every DataFrame viewer works fine on ``pd.DataFrame({'a': [1, 2, 3]})``.
 The question is what happens when the data gets weird.
 
-Displaying DataFrames in all their wonderfully variant splendor is quite a
-challenge. DataFrames come in many forms and there is little you can depend
-on when you want to serialize or display them. Through building Buckaroo I
-have tripped across many types of bugs from DataFrames that I didn't expect.
-
-So I compiled a set of the weirdest DataFrames I have seen in the wild — the
-ones that caused hard to debug errors, the ones that were hard to support —
-and reduced them to limited test cases. I call this the `Dastardly DataFrame
-Dataset <https://github.com/buckaroo-data/buckaroo/blob/main/buckaroo/ddd_library.py>`_
-(DDD). MultiIndex columns, NaN mixed with infinity, columns
-literally named ``index``, integers too large for JavaScript, types that most
-tools pretend don't exist. Through hard fought experience, Buckaroo has dealt
-with bugs or edge cases related to each one.
-
-The naming and early shape of the DDD was heavily influenced by an exchange
-with `Cecil Curry <https://github.com/leycec>`_, the author of
-`beartype <https://github.com/beartype/beartype>`_, on
-`beartype#529 <https://github.com/beartype/beartype/issues/529>`_. That guy
-is awesome. Be more like that guy. Seriously the most enjoyable bug report
-interaction I have ever had.
-
-This page shows each DDD member rendered live in buckaroo's static embed. No
-Jupyter kernel, no server — just HTML and JavaScript.
+Buckaroo ships a collection of deliberately tricky DataFrames called the
+**Dastardly DataFrame Dataset** (DDD). These are the DataFrames that break
+other viewers — the ones with MultiIndex columns, NaN mixed with infinity,
+columns literally named ``index``, integers too large for JavaScript, and
+types that most tools pretend don't exist.
+
+This page shows each one rendered live in buckaroo's static embed. No
+Jupyter kernel, no server — just HTML and JavaScript. If you can see the
+tables below, the static embedding system is working.
 
 Why this matters
 ----------------
 
-Buckaroo has the philosophy that every DataFrame should be displayable, at
-least in some form. Capabilities can be reduced — it's fine for ``mean`` to
-fail if there is a ``NaN`` in a column — but that failure can't cause
-Buckaroo to display nothing.
-
 If you build dashboards, you choose what data goes into your table. You
 control the types, the column names, the index. But if you're doing
 exploratory data analysis — loading CSVs from vendors, joining tables from
 different systems, debugging a pipeline that produces unexpected output —
-you don't control any of that. The data is what it is. And who knows
-what an LLM will produce — code-generating agents can create DataFrames
-with column types you've never seen in your own code. Same goes for
-inherited data pipelines: someone else built it, you're debugging it,
-and the DataFrame you're staring at has types and structures you didn't
-choose.
+you don't control any of that. The data is what it is.
 
 ``df.head()`` hides the problem. It shows you 5 rows and lets you believe
 everything is fine. Buckaroo is built for the opposite workflow: show you
@@ -54,20 +30,10 @@ everything, especially the parts that are surprising.
 The Dastardly DataFrames
 ------------------------
 
-The DDD is used extensively in Buckaroo's unit test suite. At a minimum,
-all DataFrames display in some way unless otherwise noted. Most display with
-full features — there are a couple of rough edges, but having a comprehensive
-test set is a very helpful start.
-
-Each section below shows the exact function from ``buckaroo.ddd_library``
-that creates the DataFrame, explains why it's tricky, and renders it live
-in a buckaroo static embed.
+Each section below shows the Python code to create the DataFrame, explains
+why it's tricky, and renders it live in a buckaroo static embed.
 
-.. code-block:: bash
-
-    pip install buckaroo
-
-.. code-block:: python
+All of these DataFrames are available in ``buckaroo.ddd_library``::
 
     from buckaroo.ddd_library import *
 
@@ -77,13 +43,9 @@ Infinity and NaN
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def df_with_infinity() -> pd.DataFrame:
-        return pd.DataFrame({'a': [np.nan, np.inf, np.inf * -1]})
-
-    df_with_infinity()
+    pd.DataFrame({'a': [np.nan, np.inf, np.inf * -1]})
 
-Three non-numeric values that pop up in numeric columns: a missing value, positive
+Three values, three completely different things: a missing value, positive
 infinity, and negative infinity. Many viewers display all three as blank or
 "NaN". Buckaroo distinguishes them.
 
@@ -103,11 +65,7 @@ Really Big Numbers
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def df_with_really_big_number() -> pd.DataFrame:
-        return pd.DataFrame({"col1": [9999999999999999999, 1]})
-
-    df_with_really_big_number()
+    pd.DataFrame({"col1": [9999999999999999999, 1]})
 
 Python integers have arbitrary precision. JavaScript's ``Number`` type has
 53 bits of integer precision (``Number.MAX_SAFE_INTEGER`` = 9007199254740991).
@@ -130,13 +88,10 @@ Column Named "index"
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def df_with_col_named_index() -> pd.DataFrame:
-        return pd.DataFrame({
-            'a':     ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"],
-            'index': ["7777", "ooooo", "--- -", "33333", "assdf"]})
-
-    df_with_col_named_index()
+    pd.DataFrame({
+        'a':     ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"],
+        'index': ["7777", "ooooo", "--- -", "33333", "assdf"]
+    })
 
 When you call ``df.reset_index()``, pandas creates a column called ``index``.
 Many widgets break because they confuse this column with the DataFrame's
@@ -155,15 +110,10 @@ Named Index
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def get_df_with_named_index() -> pd.DataFrame:
-        """someone put the effort into naming the index,
-        you'd probably want to display that"""
-        return pd.DataFrame(
-            {'a': ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]},
-            index=pd.Index([10, 20, 30, 40, 50], name='foo'))
-
-    get_df_with_named_index()
+    pd.DataFrame(
+        {'a': ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]},
+        index=pd.Index([10, 20, 30, 40, 50], name='foo')
+    )
 
 Someone took the time to name this index ``foo``. That name carries meaning —
 it might be a join key, a time series frequency, or a categorical grouping.
@@ -182,17 +132,11 @@ MultiIndex Columns
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def get_multiindex_with_names_cols_df(rows=15) -> pd.DataFrame:
-        cols = pd.MultiIndex.from_tuples(
-            [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
-             ('bar', 'b'), ('bar', 'c')],
-            names=['level_a', 'level_b'])
-        return pd.DataFrame(
-            [["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]] * rows,
-            columns=cols)
-
-    get_multiindex_with_names_cols_df(rows=6)
+    cols = pd.MultiIndex.from_tuples(
+        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'), ('bar', 'b'), ('bar', 'c')],
+        names=['level_a', 'level_b'])
+    pd.DataFrame([["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]] * 6,
+                 columns=cols)
 
 Hierarchical column headers are common after ``.pivot_table()`` and
 ``.groupby().agg()``. Most viewers either crash or flatten them into ugly
@@ -211,18 +155,13 @@ MultiIndex on Rows
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def get_multiindex_index_df() -> pd.DataFrame:
-        row_index = pd.MultiIndex.from_tuples([
-            ('foo', 'a'), ('foo', 'b'),
-            ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
-            ('baz', 'a')])
-        return pd.DataFrame({
-            'foo_col': [10, 20, 30, 40, 50, 60],
-            'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
-            index=row_index)
-
-    get_multiindex_index_df()
+    row_index = pd.MultiIndex.from_tuples([
+        ('foo', 'a'), ('foo', 'b'),
+        ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
+        ('baz', 'a')])
+    pd.DataFrame({'foo_col': [10, 20, 30, 40, 50, 60],
+                  'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
+                 index=row_index)
 
 Multi-level row indexes are the counterpart to MultiIndex columns. They
 appear after ``.groupby()`` without ``.reset_index()``, or when loading
@@ -230,6 +169,9 @@ data from hierarchical sources. The tricky part: each index level becomes
 an additional column that has to be displayed alongside the data columns
 without breaking the column count.
 
+This DataFrame also has a ``None`` in the last row of ``bar_col`` — a missing
+string value mixed with non-missing strings.
+
 .. raw:: html
 
    <iframe src="../ddd/multiindex-rows.html"
@@ -242,18 +184,13 @@ Three-Level MultiIndex
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def get_multiindex3_index_df() -> pd.DataFrame:
-        row_index = pd.MultiIndex.from_tuples([
-            ('foo', 'a', 3), ('foo', 'b', 2),
-            ('bar', 'a', 1), ('bar', 'b', 3), ('bar', 'c', 5),
-            ('baz', 'a', 6)])
-        return pd.DataFrame({
-            'foo_col': [10, 20, 30, 40, 50, 60],
-            'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
-            index=row_index)
-
-    get_multiindex3_index_df()
+    row_index = pd.MultiIndex.from_tuples([
+        ('foo', 'a', 3), ('foo', 'b', 2),
+        ('bar', 'a', 1), ('bar', 'b', 3), ('bar', 'c', 5),
+        ('baz', 'a', 6)])
+    pd.DataFrame({'foo_col': [10, 20, 30, 40, 50, 60],
+                  'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
+                 index=row_index)
 
 If two levels are hard, three levels are harder. This exercises the
 column-renaming logic that has to handle an arbitrary number of index levels
@@ -271,29 +208,22 @@ MultiIndex on Both Axes
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def get_multiindex_with_names_both() -> pd.DataFrame:
-        row_index = pd.MultiIndex.from_tuples([
-            ('foo', 'a'), ('foo', 'b'),
-            ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
-            ('baz', 'a')],
-            names=['index_name_1', 'index_name_2'])
-        cols = pd.MultiIndex.from_tuples(
-            [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
-             ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
-            names=['level_a', 'level_b'])
-        return pd.DataFrame([
-            [10, 20, 30, 40, 50, 60]] * 6,
-            columns=cols, index=row_index)
-
-    get_multiindex_with_names_both()
+    # MultiIndex on both rows and columns, both with names
+    row_index = pd.MultiIndex.from_tuples(
+        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
+         ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
+        names=['index_name_1', 'index_name_2'])
+    cols = pd.MultiIndex.from_tuples(
+        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
+         ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
+        names=['level_a', 'level_b'])
+    pd.DataFrame([[10, 20, 30, 40, 50, 60]] * 6,
+                 columns=cols, index=row_index)
 
 The boss fight: hierarchical headers on both axes, with named levels on
 both sides. This is what ``pd.pivot_table()`` produces on complex groupings.
 Everything about column counting, index handling, and header rendering gets
-tested simultaneously. There are still improvements planned here — the
-spacing is odd, the thick borders aren't in the correct place — but it
-displays, which is more than most viewers manage.
+tested simultaneously.
 
 .. raw:: html
 
@@ -307,25 +237,19 @@ Weird Types (Pandas)
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def df_with_weird_types() -> pd.DataFrame:
-        """DataFrame with unusual dtypes that historically broke rendering.
-        Exercises: categorical, timedelta, period, interval."""
-        return pd.DataFrame({
-            'categorical': pd.Categorical(
-                ['red', 'green', 'blue', 'red', 'green']),
-            'timedelta': pd.to_timedelta(
-                ['1 days 02:03:04', '0 days 00:00:01',
-                 '365 days', '0 days 00:00:00.001',
-                 '0 days 00:00:00.000100']),
-            'period': pd.Series(
-                pd.period_range('2021-01', periods=5, freq='M')),
-            'interval': pd.Series(
-                pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3, 4, 5])),
-            'int_col': [10, 20, 30, 40, 50],
-        })
-
-    df_with_weird_types()
+    pd.DataFrame({
+        'categorical': pd.Categorical(
+            ['red', 'green', 'blue', 'red', 'green']),
+        'timedelta': pd.to_timedelta(
+            ['1 days 02:03:04', '0 days 00:00:01',
+             '365 days', '0 days 00:00:00.001',
+             '0 days 00:00:00.000100']),
+        'period': pd.Series(
+            pd.period_range('2021-01', periods=5, freq='M')),
+        'interval': pd.Series(
+            pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3, 4, 5])),
+        'int_col': [10, 20, 30, 40, 50],
+    })
 
 Four types that most viewers ignore:
 
@@ -351,32 +275,24 @@ Weird Types (Polars)
 
 .. code-block:: python
 
-    # from buckaroo/ddd_library.py
-    def pl_df_with_weird_types():
-        """Polars DataFrame with unusual dtypes that historically broke
-        rendering. Exercises: Duration (#622), Time, Categorical,
-        Decimal, Binary."""
-        import datetime as dt
-        import polars as pl
-        return pl.DataFrame({
-            'duration': pl.Series([100_000, 3_723_000_000,
-                86_400_000_000, 500, 60_000_000],
-                dtype=pl.Duration('us')),
-            'time': [dt.time(14, 30), dt.time(9, 15, 30),
-                     dt.time(0, 0, 1), dt.time(23, 59, 59),
-                     dt.time(12, 0)],
-            'categorical': pl.Series(
-                ['red', 'green', 'blue', 'red', 'green']
-            ).cast(pl.Categorical),
-            'decimal': pl.Series(
-                ['100.50', '200.75', '0.01', '99999.99', '3.14']
-            ).cast(pl.Decimal(10, 2)),
-            'binary': [b'hello', b'world', b'\x00\x01\x02',
-                       b'test', b'\xff\xfe'],
-            'int_col': [10, 20, 30, 40, 50],
-        })
-
-    pl_df_with_weird_types()
+    import polars as pl
+    import datetime as dt
+
+    pl.DataFrame({
+        'duration': pl.Series(
+            [100_000, 3_723_000_000, 86_400_000_000, 500, 60_000_000],
+            dtype=pl.Duration('us')),
+        'time': [dt.time(14, 30), dt.time(9, 15, 30),
+                 dt.time(0, 0, 1), dt.time(23, 59, 59), dt.time(12, 0)],
+        'categorical': pl.Series(
+            ['red', 'green', 'blue', 'red', 'green']).cast(pl.Categorical),
+        'decimal': pl.Series(
+            ['100.50', '200.75', '0.01', '99999.99', '3.14']
+        ).cast(pl.Decimal(10, 2)),
+        'binary': [b'hello', b'world', b'\x00\x01\x02',
+                   b'test', b'\xff\xfe'],
+        'int_col': [10, 20, 30, 40, 50],
+    })
 
 Polars has its own set of tricky types:
 
@@ -396,245 +312,11 @@ you're migrating from pandas to polars, buckaroo moves with you.
    </iframe>
 
 
-Full dtype coverage
--------------------
-
-The DDD focuses on the types that cause trouble, but how does buckaroo
-handle *every* dtype? Here's the full picture across all three engines [1]_:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 18 12 12 12 14 14 18
-
-   * - Dtype
-     - Pandas
-     - Pandas (Arrow)
-     - Polars
-     - Parquet type
-     - JS type
-     - Buckaroo display
-   * - int8–int32
-     - Yes
-     - Yes
-     - Yes
-     - INT32
-     - Number
-     - ``1,234``
-   * - int64
-     - Yes
-     - Yes
-     - Yes
-     - INT64
-     - Number [2]_
-     - ``1,234,567``
-   * - uint8–uint64
-     - Yes
-     - Yes
-     - Yes
-     - INT32/INT64
-     - Number [2]_
-     - ``65,535``
-   * - BigInt (>2\ :sup:`53`)
-     - Yes
-     - Yes
-     - —
-     - INT64
-     - String [2]_
-     - ``9999999999999999999`` [5]_
-   * - float32
-     - Yes
-     - Yes
-     - Yes
-     - FLOAT
-     - Number
-     - ``2.500``
-   * - float64 (incl. inf/NaN)
-     - Yes
-     - Yes
-     - Yes
-     - DOUBLE
-     - Number
-     - ``Infinity``
-   * - complex128
-     - Fail [3]_
-     - —
-     - —
-     - —
-     - —
-     - —
-   * - bool
-     - Yes
-     - Yes
-     - Yes
-     - BOOLEAN
-     - boolean
-     - ``True``
-   * - string / object
-     - Yes
-     - Yes
-     - Yes
-     - BYTE_ARRAY
-     - String
-     - ``hello world``
-   * - mixed-type object
-     - Yes
-     - —
-     - —
-     - BYTE_ARRAY
-     - String
-     - ``{ 'a': 1, 'b': None }``
-   * - datetime
-     - Yes
-     - Yes
-     - Yes
-     - TIMESTAMP
-     - Date
-     - ``2021-01-15 14:30:00``
-   * - datetime + tz
-     - Not tested
-     - Yes
-     - Yes
-     - TIMESTAMP+tz
-     - Date
-     - ``2021-01-15 14:30:00``
-   * - timedelta / duration
-     - Yes
-     - Yes
-     - Yes
-     - → String [4]_
-     - String
-     - ``1d 2h 3m 4s``
-   * - date
-     - —
-     - Yes
-     - Not tested
-     - DATE (INT32)
-     - Date
-     - ``2021-01-15 00:00:00``
-   * - time
-     - —
-     - Yes
-     - Yes
-     - TIME (INT64)
-     - String
-     - ``14:30:00``
-   * - Categorical
-     - Yes
-     - Yes
-     - Yes
-     - DICT encoding
-     - String
-     - ``red``
-   * - Enum
-     - —
-     - —
-     - Not tested
-     - DICT encoding
-     - String
-     - ``red``
-   * - Period (time span)
-     - Yes
-     - —
-     - —
-     - → String [4]_
-     - String
-     - ``2021-01`` [6]_
-   * - Interval
-     - Yes
-     - —
-     - —
-     - → String [4]_
-     - String
-     - ``(0, 1]``
-   * - Decimal
-     - —
-     - Yes
-     - Yes
-     - DECIMAL
-     - Number
-     - ``100.50``
-   * - Binary
-     - —
-     - Yes
-     - Yes
-     - BYTE_ARRAY
-     - String (hex)
-     - ``68656c6c6f``
-   * - Sparse
-     - Fail [3]_
-     - —
-     - —
-     - —
-     - —
-     - —
-   * - Nullable int/float/bool
-     - Not tested
-     - —
-     - —
-     - INT32/INT64/BOOLEAN
-     - Number/boolean
-     - ``1,234`` / ``True``
-   * - List / Array
-     - —
-     - Yes
-     - Not tested
-     - LIST
-     - Array
-     - ``[ 1, 2, 3]``
-   * - Struct
-     - —
-     - Yes
-     - Not tested
-     - STRUCT
-     - Object
-     - ``{ 'a': 1, 'b': x }``
-   * - Null (all-null column)
-     - —
-     - —
-     - Not tested
-     - BYTE_ARRAY
-     - null
-     - ``(empty)``
-
-"Yes" means the dtype serializes and displays correctly. "Not tested" means
-serialization succeeds but there is no DDD test case exercising it through
-the full widget. "—" means the dtype does not exist in that engine.
-
-.. [1] Putting together this table exposed areas that still need work.
-   The interaction between Python dtype, Parquet physical type, JS
-   decoding, and display formatter has enough nuance for its own blog
-   post. Expect one soon.
-
-.. [2] hyparquet decodes INT64 as BigInt. Buckaroo converts to Number if
-   the value is ≤ ``Number.MAX_SAFE_INTEGER`` (2\ :sup:`53` - 1), otherwise
-   stringifies to preserve precision.
-
-.. [3] ``complex128`` and ``SparseDtype`` fail the Parquet path — Arrow
-   has no complex number type and can't convert sparse arrays. The JSON
-   path works with string fallback, but that path is being phased out.
-
-.. [4] ``→ String`` means the type has no native Parquet equivalent.
-   Buckaroo coerces it to a string before writing Parquet. Period becomes
-   ``'2021-01'``, Interval becomes ``'(0, 1]'``, timedelta becomes
-   ``'1 days 02:03:04'`` (pandas path only — Polars Duration is native).
-
-.. [5] Values above ``Number.MAX_SAFE_INTEGER`` are stringified on the JS
-   side to preserve exact precision, so they display without commas. The
-   value ``1`` in the same column still gets the integer formatter: ``1``.
-   This means a single column can show two different display styles depending
-   on whether each value fits in 53 bits.
-
-.. [6] A pandas ``Period`` is a *time span*, not a range between two dates.
-   ``Period('2021-01', 'M')`` means "the month of January 2021". Buckaroo
-   stringifies it because Parquet has no Period type. Don't confuse it with
-   ``Interval``, which is a numeric range like ``(0, 1]``.
-
-
-How this demo was built
------------------------
-
-Every table on this page is a **static embedding** of the full buckaroo
-widget. There is no Python kernel running. Here's what happened:
+What's happening under the hood
+--------------------------------
+
+Every table on this page is a **static embedding** of the buckaroo DFViewer.
+There is no Python kernel running. Here's what happened:
 
 1. A Python script called ``buckaroo.artifact.to_html()`` on each DataFrame
 2. The function serialized the data to base64-encoded Parquet (compact binary)
@@ -654,27 +336,23 @@ For details on how to create your own static embeds, see the
 Try it yourself
 ---------------
 
+.. code-block:: bash
+
+    pip install buckaroo
+
 .. code-block:: python
 
     from buckaroo.ddd_library import *
     from buckaroo.artifact import to_html
-    from pathlib import Path
-    import shutil, buckaroo
 
     # Generate a static HTML page for any DataFrame
     html = to_html(df_with_weird_types(), title="Weird Types Demo")
     with open('weird-types.html', 'w') as f:
         f.write(html)
 
-    # Copy the JS/CSS assets alongside the HTML (see #643 for self-contained mode)
-    static = Path(buckaroo.__file__).parent / 'static'
-    for name in ('static-embed.js', 'static-embed.css'):
-        shutil.copy(static / name, '.')
-
 Or in a Jupyter notebook, just::
 
     import buckaroo
-    from buckaroo.ddd_library import df_with_weird_types
     df_with_weird_types()  # renders inline
 
 The Dastardly DataFrame Dataset is also available as an interactive tour
diff --git a/docs/source/articles/embedding-guide.rst b/docs/source/articles/embedding-guide.rst
new file mode 100644
index 00000000..53b020da
--- /dev/null
+++ b/docs/source/articles/embedding-guide.rst
@@ -0,0 +1,254 @@
+Buckaroo Embedding Guide
+========================
+
+This guide covers everything you need to embed interactive buckaroo tables
+in your own applications, documentation, and reports.
+
+
+Why embed
+---------
+
+- **Share DataFrames without Jupyter**: Send a colleague an HTML file they
+  can open in any browser. No Python install required.
+- **Build data apps**: Integrate the buckaroo viewer into React dashboards,
+  internal tools, or customer-facing data products.
+- **Static reports**: Generate HTML reports from your pipeline that include
+  interactive, sortable tables with summary statistics.
+- **Documentation**: Embed live data tables in your docs site (Sphinx,
+  MkDocs, or plain HTML).
+
+
+Choose your embedding mode
+--------------------------
+
+Buckaroo offers two static embed modes and one live widget mode:
+
+``embed_type="DFViewer"`` — Lightweight table
+    Just the data grid with sortable columns, summary stats pinned at the
+    bottom, histograms, and type-aware formatting. Smaller payload. Best
+    for documentation, reports, and sharing.
+
+``embed_type="Buckaroo"`` — Full experience
+    Everything in DFViewer plus the display switcher bar, multiple computed
+    views, and the interactive analysis pipeline. Larger payload. Best for
+    data exploration and internal tools.
+
+**anywidget** — Live in notebooks
+    The ``BuckarooWidget`` runs inside Jupyter, Marimo, VS Code notebooks,
+    and Google Colab via anywidget. Full interactivity including the command
+    UI for data cleaning operations. Requires a running Python kernel.
+
+For most embedding use cases, start with ``DFViewer``.
+
+
+Data size guidelines
+~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Row count
+     - Recommended approach
+   * - < 1,000 rows
+     - Inline static embed. JSON payload is small (~10-50 KB).
+   * - 1,000 - 100,000 rows
+     - Static embed still works. Parquet encoding keeps payload
+       compact (50-500 KB). Consider sampling for faster page load.
+   * - > 100,000 rows
+     - Host data separately. Use Parquet range queries on S3/R2 to
+       fetch only the visible rows and columns.
+
+
+Generate a static embed
+-----------------------
+
+.. code-block:: python
+
+    from buckaroo.artifact import to_html
+    import pandas as pd
+
+    df = pd.read_csv('my_data.csv')
+    html = to_html(df, title="My Data", embed_type="DFViewer")
+
+    with open('my-data.html', 'w') as f:
+        f.write(html)
+
+The HTML file references ``static-embed.js`` and ``static-embed.css``.
+These are included in the buckaroo package under ``buckaroo/static/`` —
+copy them alongside your HTML or serve them from a web server.
+
+**With polars:**
+
+.. code-block:: python
+
+    import polars as pl
+    from buckaroo.artifact import to_html
+
+    df = pl.read_parquet('my_data.parquet')
+    html = to_html(df, title="Polars Data")
+
+``to_html()`` auto-detects polars DataFrames and uses the polars analysis
+pipeline.
+
+**From a file path:**
+
+.. code-block:: python
+
+    from buckaroo.artifact import to_html
+
+    # Reads CSV, Parquet, JSON, or JSONL automatically
+    html = to_html('/path/to/data.parquet', title="Direct from file")
+
+
+Customizing appearance
+----------------------
+
+Column config overrides
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Pass ``column_config_overrides`` to control per-column display:
+
+.. code-block:: python
+
+    html = to_html(df, column_config_overrides={
+        'revenue': {
+            'color_map_config': {
+                'color_rule': 'color_from_column',
+                'map_name': 'RdYlGn',
+            }
+        },
+        'join_key': {
+            'color_map_config': {
+                'color_rule': 'color_static',
+                'color': '#6c5fc7',
+            }
+        }
+    })
+
+Available color rules:
+
+- ``color_from_column``: Color cells based on their value using a named
+  colormap (e.g., ``RdYlGn``, ``Blues``, ``Viridis``)
+- ``color_categorical``: Map categorical values to a list of colors
+- ``color_static``: Constant background color for every cell in the column
+
+Tooltips
+~~~~~~~~
+
+Show the value of another column on hover:
+
+.. code-block:: python
+
+    column_config_overrides={
+        'name': {
+            'tooltip_config': {
+                'tooltip_type': 'simple',
+                'val_column': 'full_name',
+            }
+        }
+    }
+
+
+Analysis classes
+~~~~~~~~~~~~~~~~
+
+Control which summary statistics are computed:
+
+.. code-block:: python
+
+    from buckaroo.artifact import to_html
+    from buckaroo.pluggable_analysis_framework.analysis_management import (
+        ColAnalysis,
+    )
+
+    # Use extra_analysis_klasses to add custom stats
+    # Use analysis_klasses to replace the default set
+    html = to_html(df,
+                   extra_analysis_klasses=[MyCustomAnalysis],
+                   embed_type="Buckaroo")
+
+See :doc:`pluggable` for details on writing custom analysis classes.
+
+
+Pinned rows
+~~~~~~~~~~~
+
+Add custom pinned rows (shown at the bottom of the table):
+
+.. code-block:: python
+
+    html = to_html(df,
+                   extra_pinned_rows=[
+                       {'index': 'target', 'a': 100, 'b': 200},
+                   ])
+
+
+Integration patterns
+--------------------
+
+Static HTML file
+~~~~~~~~~~~~~~~~
+
+The simplest approach. Generate the HTML, copy ``static-embed.js`` and
+``static-embed.css`` next to it, and open in a browser or serve from any
+static file host.
+
+.. code-block:: bash
+
+    cp $(python -c "import buckaroo; print(buckaroo.__path__[0])")/static/static-embed.* ./
+    open my-data.html
+
+React component
+~~~~~~~~~~~~~~~
+
+For deeper integration, import the React components directly from
+``buckaroo-js-core``:
+
+.. code-block:: bash
+
+    npm install buckaroo-js-core
+
+.. code-block:: typescript
+
+    import { DFViewer } from 'buckaroo-js-core';
+
+    function MyTable({ data, config, summaryStats }) {
+      return (
+        <DFViewer
+          df_data={data}
+          df_viewer_config={config}
+          summary_stats_data={summaryStats}
+        />
+      );
+    }
+
+Sphinx / ReadTheDocs
+~~~~~~~~~~~~~~~~~~~~~
+
+Use a ``raw`` directive to embed an iframe pointing to a pre-generated
+static HTML file:
+
+.. code-block:: rst
+
+    .. raw:: html
+
+       <iframe src="_static/my-table.html"
+               style="width:100%; height:400px; border:none;">
+       </iframe>
+
+Generate the HTML with the ``to_html()`` function and place it in your
+Sphinx ``_static`` directory.
+
+
+What's included in the bundle
+-----------------------------
+
+The ``static-embed.js`` bundle (1.3 MB minified) includes:
+
+- React 18 + ReactDOM
+- AG-Grid Community v33 (table rendering)
+- hyparquet (Parquet decoding in the browser)
+- recharts (histogram rendering)
+- lodash-es (utility functions, tree-shaken)
+
+The bundle is built with esbuild and shipped as an ES module.
diff --git a/docs/source/articles/static-embedding.rst b/docs/source/articles/static-embedding.rst
new file mode 100644
index 00000000..c5df8616
--- /dev/null
+++ b/docs/source/articles/static-embedding.rst
@@ -0,0 +1,180 @@
+Static Embedding & the Incredible Shrinking Widget
+====================================================
+
+Buckaroo started as a Jupyter widget. You had to install Python, install
+Jupyter, install buckaroo, start a kernel, and run a cell — just to see a
+table. Then came Marimo and Pyodide, which cut out the kernel but still
+needed a Python runtime in the browser.
+
+Now there's a third option: **static embedding**. A single HTML file that
+renders a fully interactive buckaroo table with no server, no kernel, no
+Python runtime. Just a browser.
+
+How it works
+------------
+
+.. code-block:: python
+
+    from buckaroo.artifact import to_html
+    import pandas as pd
+
+    df = pd.read_csv('sales.csv')
+    html = to_html(df, title="Sales Data", embed_type="DFViewer")
+
+    with open('sales.html', 'w') as f:
+        f.write(html)
+
+That's it. ``to_html()`` does the following:
+
+1. Runs the buckaroo analysis pipeline on the DataFrame — computing dtypes,
+   summary stats, histograms, column configs
+2. Serializes the data to **base64-encoded Parquet** (much more compact than
+   JSON, especially for numeric columns)
+3. Wraps everything in an HTML template that references ``static-embed.js``
+   and ``static-embed.css``
+
+The resulting HTML is self-describing. The JS bundle reads the embedded JSON,
+decodes the Parquet payload using `hyparquet <https://github.com/hyparam/hyparquet>`_,
+and renders the table with AG-Grid — all client-side.
+
+Two embedding modes
+-------------------
+
+``embed_type="DFViewer"`` (default)
+    Lightweight table viewer with summary stats pinned at the bottom.
+    Includes dtypes, histograms, and basic statistics. Smaller payload.
+
+``embed_type="Buckaroo"``
+    The full buckaroo experience: display switcher bar, multiple computed
+    views (main data, summary stats, other analysis outputs), and the
+    interactive analysis pipeline UI. Larger payload but more powerful.
+
+For most documentation and sharing use cases, ``DFViewer`` is the right
+choice.
+
+
+Bundle size
+-----------
+
+The ``static-embed.js`` bundle is currently **1.3 MB** (minified). This
+includes React, AG-Grid, hyparquet, recharts (for histograms), and lodash-es.
+
+How does this compare to the data industry?
+
+======================== ==================
+Site                     Total page weight
+======================== ==================
+MongoDB                  11.5 MB
+Confluent                10.7 MB
+Snowflake                8.4 MB
+Elastic                  6.1 MB
+dbt Labs                 5.0 MB
+Fivetran                 3.4 MB
+Datadog                  2.3 MB
+Palantir                 2.0 MB
+Databricks               1.6 MB
+**Buckaroo static embed** **~1.3 MB + data**
+======================== ==================
+
+Confluent ships 9.2 MB of JavaScript to show you a marketing page. MongoDB
+loads a 1.7 MB Optimizely tracking script before you see a single word of
+content. Buckaroo delivers an interactive data viewer — with histograms,
+sortable columns, summary stats, and type-aware formatting — in less than
+Palantir's homepage JavaScript alone.
+
+And that 1.3 MB includes the *viewer itself*. Your data is on top of that,
+but Parquet-encoded data is compact: a 10,000-row DataFrame with 10 columns
+typically adds 50-200 KB depending on column types.
+
+
+What we did to get here
+-----------------------
+
+Recent releases shipped several size optimizations:
+
+**lodash → lodash-es** (`#624 <https://github.com/buckaroo-data/buckaroo/pull/624>`_)
+    Migrated from the CommonJS lodash bundle (which includes every function)
+    to lodash-es, which is tree-shakeable. Only the functions actually used
+    end up in the bundle.
+
+**AG Grid v32 → v33** (`#625 <https://github.com/buckaroo-data/buckaroo/pull/625>`_)
+    AG Grid v33 unified its package structure. Instead of importing from
+    multiple packages (``@ag-grid-community/core``, ``@ag-grid-community/client-side-row-model``,
+    etc.), there's now a single ``ag-grid-community`` package with module
+    registration. This lets the bundler do a single pass of tree-shaking
+    instead of trying to deduplicate across packages.
+
+**Minification** (`#624 <https://github.com/buckaroo-data/buckaroo/pull/624>`_)
+    The ``widget.js`` and ``static-embed.js`` bundles are now minified with
+    esbuild. Previously they shipped unminified.
+
+**Parquet encoding**
+    Switching from JSON arrays to Parquet for the data payload was itself
+    a size win. A DataFrame with 1000 rows of integers takes ~4 KB in
+    Parquet vs ~12 KB in JSON. The savings compound with row count.
+
+
+What's next: CDN-hosted viewer
+------------------------------
+
+Today, every static embed includes the full 1.3 MB viewer bundle. If you
+generate 10 pages, you serve 13 MB of identical JavaScript.
+
+The next step is publishing ``static-embed.js`` to a CDN (e.g., jsDelivr or
+a Cloudflare R2 bucket). Each embed page would reference the CDN URL instead
+of a local file. The per-page payload drops to just the data — typically
+under 200 KB.
+
+This also opens the door to embedding buckaroo tables directly in
+GitHub READMEs (via ``<img>`` or GitHub Pages), documentation sites, and
+email reports.
+
+
+For larger data: Parquet range queries
+--------------------------------------
+
+Static embeds work great for data that fits in a single HTML file — up to
+about 100K rows before the file gets unwieldy. Beyond that, the data should
+live separately.
+
+Parquet files are designed for partial reads. The file footer contains a
+directory of column chunks with byte offsets. A client can fetch just the
+columns and row groups it needs using HTTP range requests — no server
+required, just a file on object storage (S3, Cloudflare R2, GCS).
+
+This is the subject of a future post, but the architecture looks like:
+
+1. Parquet file on a private R2 bucket
+2. Cloudflare Worker generates a time-limited presigned URL
+3. Browser-side buckaroo fetches column chunks via ``Range`` headers
+4. Data never flows through your server
+
+See the content plan for details.
+
+
+Try it
+------
+
+.. code-block:: bash
+
+    pip install buckaroo
+
+.. code-block:: python
+
+    from buckaroo.artifact import to_html
+    import pandas as pd
+
+    # Any DataFrame works
+    df = pd.read_csv('your_data.csv')
+    html = to_html(df, title="My Data")
+
+    with open('my-data.html', 'w') as f:
+        f.write(html)
+
+    # Full buckaroo experience (larger bundle, more features)
+    html_full = to_html(df, title="My Data", embed_type="Buckaroo")
+
+The generated HTML references ``static-embed.js`` and ``static-embed.css``
+which are included in the ``buckaroo`` Python package under
+``buckaroo/static/``. Copy those files alongside your HTML, or serve them
+from a web server.
diff --git a/scripts/generate_ddd_static_html.py b/scripts/generate_ddd_static_html.py
index 08943b04..51d0f058 100644
--- a/scripts/generate_ddd_static_html.py
+++ b/scripts/generate_ddd_static_html.py
@@ -10,18 +10,21 @@
 # Ensure the repo root is importable
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
 
+import pandas as pd
+import numpy as np
 from buckaroo.artifact import to_html
 from buckaroo.ddd_library import (
     df_with_infinity,
     df_with_really_big_number,
     df_with_col_named_index,
     get_df_with_named_index,
+    get_multiindex_cols_df,
     get_multiindex_with_names_cols_df,
     get_multiindex_index_df,
     get_multiindex3_index_df,
     get_multiindex_with_names_both,
     df_with_weird_types,
-    pl_df_with_weird_types,
+    pl_df_with_weird_types_as_pandas,
 )
 
 OUT_DIR = os.path.join(os.path.dirname(__file__), '..', 'docs', 'extra-html', 'ddd')
@@ -65,15 +68,15 @@
      df_with_weird_types(),
      'Categorical, timedelta, period, and interval dtypes.'),
 
-    ('weird-types-polars', 'Weird Types (Polars)',
-     pl_df_with_weird_types(),
-     'Duration, time, categorical, decimal, and binary dtypes — native polars DataFrame.'),
+    ('weird-types-polars', 'Weird Types (Polars → Pandas)',
+     pl_df_with_weird_types_as_pandas(),
+     'Duration, time, categorical, decimal, and binary dtypes from polars.'),
 ]
 
 
 def generate_embed(filename, title, df, description):
     """Generate a single static embed HTML file."""
-    html = to_html(df, title=title, embed_type="Buckaroo")
+    html = to_html(df, title=title, embed_type="DFViewer")
     path = os.path.join(OUT_DIR, f'{filename}.html')
     with open(path, 'w') as f:
         f.write(html)

From 068713d21a5ae299a0a0a1d6785c0aa32152380e Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 16:39:41 -0400
Subject: [PATCH 03/29] fix: remove unused imports in
 generate_ddd_static_html.py

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 scripts/generate_ddd_static_html.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/scripts/generate_ddd_static_html.py b/scripts/generate_ddd_static_html.py
index 51d0f058..b973502b 100644
--- a/scripts/generate_ddd_static_html.py
+++ b/scripts/generate_ddd_static_html.py
@@ -10,15 +10,12 @@
 # Ensure the repo root is importable
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
 
-import pandas as pd
-import numpy as np
 from buckaroo.artifact import to_html
 from buckaroo.ddd_library import (
     df_with_infinity,
     df_with_really_big_number,
     df_with_col_named_index,
     get_df_with_named_index,
-    get_multiindex_cols_df,
     get_multiindex_with_names_cols_df,
     get_multiindex_index_df,
     get_multiindex3_index_df,

From cdf93d35b9a28fe2cd88d6beecd2a10597dd5e68 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:01:07 -0400
Subject: [PATCH 04/29] =?UTF-8?q?fix:=20RTD=20build=20=E2=80=94=20stub=20m?=
 =?UTF-8?q?issing=20JS=20artifacts,=20fix=20RST=20table=20width?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Touch empty static files (compiled.css, widget.js, etc.) before
  running generate_ddd_static_html.py so anywidget import succeeds
  without a full JS build
- Widen RST table columns to fit "Buckaroo static embed" row

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/.readthedocs.yaml                    |  1 +
 docs/source/articles/static-embedding.rst | 28 +++++++++++------------
 2 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
index 8115940f..6e9f8a06 100644
--- a/docs/.readthedocs.yaml
+++ b/docs/.readthedocs.yaml
@@ -33,6 +33,7 @@ build:
         - ./scripts/marimo_wasm_output.sh buckaroo_ddd_tour.py run
         - ./scripts/marimo_wasm_output.sh buckaroo_compare.py edit
         - ./scripts/marimo_wasm_output.sh full_tour.py edit
+        - touch buckaroo/static/compiled.css buckaroo/static/widget.js buckaroo/static/widget.css buckaroo/static/static-embed.js buckaroo/static/static-embed.css buckaroo/static/standalone.css
         - uv run python scripts/generate_ddd_static_html.py
         - pnpm -C packages/buckaroo-js-core run build-storybook
         - cp -r packages/buckaroo-js-core/dist/storybook docs/extra-html/
diff --git a/docs/source/articles/static-embedding.rst b/docs/source/articles/static-embedding.rst
index c5df8616..5a95bc82 100644
--- a/docs/source/articles/static-embedding.rst
+++ b/docs/source/articles/static-embedding.rst
@@ -61,20 +61,20 @@ includes React, AG-Grid, hyparquet, recharts (for histograms), and lodash-es.
 
 How does this compare to the data industry?
 
-======================== ==================
-Site                     Total page weight
-======================== ==================
-MongoDB                  11.5 MB
-Confluent                10.7 MB
-Snowflake                8.4 MB
-Elastic                  6.1 MB
-dbt Labs                 5.0 MB
-Fivetran                 3.4 MB
-Datadog                  2.3 MB
-Palantir                 2.0 MB
-Databricks               1.6 MB
-**Buckaroo static embed** **~1.3 MB + data**
-======================== ==================
+========================== ==================
+Site                       Total page weight
+========================== ==================
+MongoDB                    11.5 MB
+Confluent                  10.7 MB
+Snowflake                  8.4 MB
+Elastic                    6.1 MB
+dbt Labs                   5.0 MB
+Fivetran                   3.4 MB
+Datadog                    2.3 MB
+Palantir                   2.0 MB
+Databricks                 1.6 MB
+**Buckaroo static embed**  **~1.3 MB + data**
+========================== ==================
 
 Confluent ships 9.2 MB of JavaScript to show you a marketing page. MongoDB
 loads a 1.7 MB Optimizely tracking script before you see a single word of

From 16643e06d1524da7db6de3665c09aee08e8ebcb6 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:08:42 -0400
Subject: [PATCH 05/29] ci: post docs preview link as PR comment

Adds a step to the CheckDocs job that comments on PRs with the
ReadTheDocs preview URL and links to key article pages.
Uses the same create-or-update pattern as the TestPyPI comment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/checks.yml | 41 ++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index e9fd4f87..3e281a6d 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -668,6 +668,47 @@ jobs:
           uv run pytest --check-links docs/source/*.rst || uv run pytest --check-links --lf docs/source/*.rst
           uv run pytest --check-links docs/example-notebooks/*.ipynb || uv run pytest --check-links --lf docs/example-notebooks/*.ipynb
           uv run sphinx-build -T -b html docs/source docs/build
+      - name: Comment on PR with docs preview link
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const pr = context.issue.number;
+            const rtdSlug = 'buckaroo-data';
+            const body = [
+              '## :book: Docs preview',
+              '',
+              `https://${rtdSlug}.readthedocs.io/en/${pr}/`,
+              '',
+              'Key pages on this branch:',
+              `- [Dastardly DataFrame Dataset](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/dastardly-dataframe-dataset.html)`,
+              `- [Static Embedding](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/static-embedding.html)`,
+              `- [Embedding Guide](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/embedding-guide.html)`,
+              `- [BuckarooCompare](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/buckaroo-compare.html)`,
+            ].join('\n');
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr,
+            });
+            const marker = '## :book: Docs preview';
+            const existing = comments.find(c => c.body.startsWith(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: pr,
+                body,
+              });
+            }
 
   # ---------------------------------------------------------------------------
   # JupyterLab integration tests

From 06187ec8505d09408b713fa65fd3adf3b2b44fc6 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:12:33 -0400
Subject: [PATCH 06/29] ci: add docs preview link to TestPyPI PR comment

Appends the RTD preview URL to the existing TestPyPI install comment
instead of posting a separate comment. Uses the correct RTD PR build
URL format: https://buckaroo-data--<PR>.org.readthedocs.build/en/<PR>/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/checks.yml | 41 ------------------------------------
 1 file changed, 41 deletions(-)

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 3e281a6d..e9fd4f87 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -668,47 +668,6 @@ jobs:
           uv run pytest --check-links docs/source/*.rst || uv run pytest --check-links --lf docs/source/*.rst
           uv run pytest --check-links docs/example-notebooks/*.ipynb || uv run pytest --check-links --lf docs/example-notebooks/*.ipynb
           uv run sphinx-build -T -b html docs/source docs/build
-      - name: Comment on PR with docs preview link
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v8
-        with:
-          script: |
-            const pr = context.issue.number;
-            const rtdSlug = 'buckaroo-data';
-            const body = [
-              '## :book: Docs preview',
-              '',
-              `https://${rtdSlug}.readthedocs.io/en/${pr}/`,
-              '',
-              'Key pages on this branch:',
-              `- [Dastardly DataFrame Dataset](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/dastardly-dataframe-dataset.html)`,
-              `- [Static Embedding](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/static-embedding.html)`,
-              `- [Embedding Guide](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/embedding-guide.html)`,
-              `- [BuckarooCompare](https://${rtdSlug}.readthedocs.io/en/${pr}/articles/buckaroo-compare.html)`,
-            ].join('\n');
-
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: pr,
-            });
-            const marker = '## :book: Docs preview';
-            const existing = comments.find(c => c.body.startsWith(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: pr,
-                body,
-              });
-            }
 
   # ---------------------------------------------------------------------------
   # JupyterLab integration tests

From 20841dd16a956604b8813d6111fcae1ae29b0222 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:20:13 -0400
Subject: [PATCH 07/29] fix: build static-embed JS bundle on RTD so DDD iframes
 render

- Install full pnpm workspace (not just buckaroo-js-core)
- Build buckaroo-js-core then build:static to produce real
  static-embed.js/css in buckaroo/static/
- Keep touch stubs only for widget.js/compiled.css (not needed
  for static embed, just to unblock the Python import)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/.readthedocs.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
index 6e9f8a06..f497bbdf 100644
--- a/docs/.readthedocs.yaml
+++ b/docs/.readthedocs.yaml
@@ -29,11 +29,11 @@ build:
         - uv venv
         - pnpm -C packages/buckaroo-js-core run build
         - pnpm -C packages/js run build:static
+        - touch buckaroo/static/compiled.css buckaroo/static/widget.js buckaroo/static/widget.css
         - uv run sphinx-build -T -b html docs/source  $READTHEDOCS_OUTPUT/html
         - ./scripts/marimo_wasm_output.sh buckaroo_ddd_tour.py run
         - ./scripts/marimo_wasm_output.sh buckaroo_compare.py edit
         - ./scripts/marimo_wasm_output.sh full_tour.py edit
-        - touch buckaroo/static/compiled.css buckaroo/static/widget.js buckaroo/static/widget.css buckaroo/static/static-embed.js buckaroo/static/static-embed.css buckaroo/static/standalone.css
         - uv run python scripts/generate_ddd_static_html.py
         - pnpm -C packages/buckaroo-js-core run build-storybook
         - cp -r packages/buckaroo-js-core/dist/storybook docs/extra-html/

From 1c38349119a19c4c9f88ee8fd21e1e77dd3623a4 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:26:37 -0400
Subject: [PATCH 08/29] fix: use full Buckaroo embed for DDD pages, not
 DFViewer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 scripts/generate_ddd_static_html.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/generate_ddd_static_html.py b/scripts/generate_ddd_static_html.py
index b973502b..4116c043 100644
--- a/scripts/generate_ddd_static_html.py
+++ b/scripts/generate_ddd_static_html.py
@@ -73,7 +73,7 @@
 
 def generate_embed(filename, title, df, description):
     """Generate a single static embed HTML file."""
-    html = to_html(df, title=title, embed_type="DFViewer")
+    html = to_html(df, title=title, embed_type="Buckaroo")
     path = os.path.join(OUT_DIR, f'{filename}.html')
     with open(path, 'w') as f:
         f.write(html)

From 8f2be25664df239fe1ce2e5aa0566c850951d2fb Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:30:55 -0400
Subject: [PATCH 09/29] docs: add comments to each DDD code block describing
 the edge case

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../articles/dastardly-dataframe-dataset.rst  | 48 +++++++++++++++++--
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/source/articles/dastardly-dataframe-dataset.rst b/docs/source/articles/dastardly-dataframe-dataset.rst
index 5f03e725..c97a0d80 100644
--- a/docs/source/articles/dastardly-dataframe-dataset.rst
+++ b/docs/source/articles/dastardly-dataframe-dataset.rst
@@ -43,6 +43,10 @@ Infinity and NaN
 
 .. code-block:: python
 
+    # DDD: Infinity and NaN
+    # Three values that look similar but are completely different:
+    # NaN (missing), +inf (positive infinity), -inf (negative infinity).
+    # Most viewers show all three as blank. Buckaroo distinguishes them.
     pd.DataFrame({'a': [np.nan, np.inf, np.inf * -1]})
 
 Three values, three completely different things: a missing value, positive
@@ -65,6 +69,10 @@ Really Big Numbers
 
 .. code-block:: python
 
+    # DDD: Really Big Numbers
+    # 9999999999999999999 exceeds JavaScript's Number.MAX_SAFE_INTEGER (2^53-1).
+    # Naive JS conversion silently rounds to 10000000000000000000.
+    # Buckaroo preserves exact precision by keeping unsafe integers as strings.
     pd.DataFrame({"col1": [9999999999999999999, 1]})
 
 Python integers have arbitrary precision. JavaScript's ``Number`` type has
@@ -88,6 +96,10 @@ Column Named "index"
 
 .. code-block:: python
 
+    # DDD: Column Named "index"
+    # df.reset_index() creates a column called "index", which collides
+    # with the DataFrame's actual index. Many widgets break on this.
+    # Buckaroo handles it via internal column renaming (a, b, c...).
     pd.DataFrame({
         'a':     ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"],
         'index': ["7777", "ooooo", "--- -", "33333", "assdf"]
@@ -110,6 +122,10 @@ Named Index
 
 .. code-block:: python
 
+    # DDD: Named Index
+    # The index has a name ("foo") that carries semantic meaning —
+    # a join key, time series frequency, or categorical grouping.
+    # Buckaroo displays it as a distinct pinned column.
     pd.DataFrame(
         {'a': ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]},
         index=pd.Index([10, 20, 30, 40, 50], name='foo')
@@ -132,6 +148,10 @@ MultiIndex Columns
 
 .. code-block:: python
 
+    # DDD: MultiIndex Columns
+    # Hierarchical column headers from .pivot_table() or .groupby().agg().
+    # Most viewers crash or show ugly tuple strings like ('foo', 'a').
+    # Buckaroo flattens them into readable headers.
     cols = pd.MultiIndex.from_tuples(
         [('foo', 'a'), ('foo', 'b'), ('bar', 'a'), ('bar', 'b'), ('bar', 'c')],
         names=['level_a', 'level_b'])
@@ -155,6 +175,10 @@ MultiIndex on Rows
 
 .. code-block:: python
 
+    # DDD: MultiIndex on Rows
+    # Two-level row index plus a None in the last row of bar_col —
+    # a missing string mixed with non-missing strings.
+    # Each index level becomes an extra column without breaking the layout.
     row_index = pd.MultiIndex.from_tuples([
         ('foo', 'a'), ('foo', 'b'),
         ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
@@ -184,6 +208,9 @@ Three-Level MultiIndex
 
 .. code-block:: python
 
+    # DDD: Three-Level MultiIndex
+    # Three levels of row hierarchy. Tests that column renaming handles
+    # an arbitrary number of index levels without name collisions.
     row_index = pd.MultiIndex.from_tuples([
         ('foo', 'a', 3), ('foo', 'b', 2),
         ('bar', 'a', 1), ('bar', 'b', 3), ('bar', 'c', 5),
@@ -208,7 +235,10 @@ MultiIndex on Both Axes
 
 .. code-block:: python
 
-    # MultiIndex on both rows and columns, both with names
+    # DDD: MultiIndex on Both Axes (the boss fight)
+    # Hierarchical headers on both rows and columns, both with named levels.
+    # This is what pd.pivot_table() produces on complex groupings.
+    # Tests column counting, index handling, and header rendering simultaneously.
     row_index = pd.MultiIndex.from_tuples(
         [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
          ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
@@ -237,6 +267,12 @@ Weird Types (Pandas)
 
 .. code-block:: python
 
+    # DDD: Weird Types (Pandas)
+    # Four types most viewers ignore entirely:
+    # - Categorical: fixed set of allowed values, not a string
+    # - Timedelta: a duration ("1d 2h 3m 4s"), not a timestamp
+    # - Period: a span of time ("January 2021"), not a point in time
+    # - Interval: a range like (0, 1], common in pd.cut() output
     pd.DataFrame({
         'categorical': pd.Categorical(
             ['red', 'green', 'blue', 'red', 'green']),
@@ -275,6 +311,12 @@ Weird Types (Polars)
 
 .. code-block:: python
 
+    # DDD: Weird Types (Polars)
+    # Polars-specific types that historically broke rendering:
+    # - Duration: microsecond-precision, was blank before issue #622
+    # - Time: time-of-day without a date component
+    # - Decimal: fixed-precision (not float), important for financial data
+    # - Binary: raw bytes, displayed as hex strings
     import polars as pl
     import datetime as dt
 
@@ -315,8 +357,8 @@ you're migrating from pandas to polars, buckaroo moves with you.
 What's happening under the hood
 --------------------------------
 
-Every table on this page is a **static embedding** of the buckaroo DFViewer.
-There is no Python kernel running. Here's what happened:
+Every table on this page is a **static embedding** of the full buckaroo
+widget. There is no Python kernel running. Here's what happened:
 
 1. A Python script called ``buckaroo.artifact.to_html()`` on each DataFrame
 2. The function serialized the data to base64-encoded Parquet (compact binary)

From 6c1d39c7eeb69d5cd5cfeef765b4caf0b7b0161a Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:41:23 -0400
Subject: [PATCH 10/29] docs: show raw ddd_library function defs in code blocks

Each code block now shows the actual function definition from
buckaroo/ddd_library.py followed by the call, instead of
inline DataFrame construction.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../articles/dastardly-dataframe-dataset.rst  | 250 +++++++++---------
 1 file changed, 130 insertions(+), 120 deletions(-)

diff --git a/docs/source/articles/dastardly-dataframe-dataset.rst b/docs/source/articles/dastardly-dataframe-dataset.rst
index c97a0d80..ef594baf 100644
--- a/docs/source/articles/dastardly-dataframe-dataset.rst
+++ b/docs/source/articles/dastardly-dataframe-dataset.rst
@@ -30,10 +30,15 @@ everything, especially the parts that are surprising.
 The Dastardly DataFrames
 ------------------------
 
-Each section below shows the Python code to create the DataFrame, explains
-why it's tricky, and renders it live in a buckaroo static embed.
+Each section below shows the exact function from ``buckaroo.ddd_library``
+that creates the DataFrame, explains why it's tricky, and renders it live
+in a buckaroo static embed.
 
-All of these DataFrames are available in ``buckaroo.ddd_library``::
+.. code-block:: bash
+
+    pip install buckaroo
+
+.. code-block:: python
 
     from buckaroo.ddd_library import *
 
@@ -43,11 +48,11 @@ Infinity and NaN
 
 .. code-block:: python
 
-    # DDD: Infinity and NaN
-    # Three values that look similar but are completely different:
-    # NaN (missing), +inf (positive infinity), -inf (negative infinity).
-    # Most viewers show all three as blank. Buckaroo distinguishes them.
-    pd.DataFrame({'a': [np.nan, np.inf, np.inf * -1]})
+    # from buckaroo/ddd_library.py
+    def df_with_infinity() -> pd.DataFrame:
+        return pd.DataFrame({'a': [np.nan, np.inf, np.inf * -1]})
+
+    df_with_infinity()
 
 Three values, three completely different things: a missing value, positive
 infinity, and negative infinity. Many viewers display all three as blank or
@@ -69,11 +74,11 @@ Really Big Numbers
 
 .. code-block:: python
 
-    # DDD: Really Big Numbers
-    # 9999999999999999999 exceeds JavaScript's Number.MAX_SAFE_INTEGER (2^53-1).
-    # Naive JS conversion silently rounds to 10000000000000000000.
-    # Buckaroo preserves exact precision by keeping unsafe integers as strings.
-    pd.DataFrame({"col1": [9999999999999999999, 1]})
+    # from buckaroo/ddd_library.py
+    def df_with_really_big_number() -> pd.DataFrame:
+        return pd.DataFrame({"col1": [9999999999999999999, 1]})
+
+    df_with_really_big_number()
 
 Python integers have arbitrary precision. JavaScript's ``Number`` type has
 53 bits of integer precision (``Number.MAX_SAFE_INTEGER`` = 9007199254740991).
@@ -96,14 +101,13 @@ Column Named "index"
 
 .. code-block:: python
 
-    # DDD: Column Named "index"
-    # df.reset_index() creates a column called "index", which collides
-    # with the DataFrame's actual index. Many widgets break on this.
-    # Buckaroo handles it via internal column renaming (a, b, c...).
-    pd.DataFrame({
-        'a':     ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"],
-        'index': ["7777", "ooooo", "--- -", "33333", "assdf"]
-    })
+    # from buckaroo/ddd_library.py
+    def df_with_col_named_index() -> pd.DataFrame:
+        return pd.DataFrame({
+            'a':     ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"],
+            'index': ["7777", "ooooo", "--- -", "33333", "assdf"]})
+
+    df_with_col_named_index()
 
 When you call ``df.reset_index()``, pandas creates a column called ``index``.
 Many widgets break because they confuse this column with the DataFrame's
@@ -122,14 +126,15 @@ Named Index
 
 .. code-block:: python
 
-    # DDD: Named Index
-    # The index has a name ("foo") that carries semantic meaning —
-    # a join key, time series frequency, or categorical grouping.
-    # Buckaroo displays it as a distinct pinned column.
-    pd.DataFrame(
-        {'a': ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]},
-        index=pd.Index([10, 20, 30, 40, 50], name='foo')
-    )
+    # from buckaroo/ddd_library.py
+    def get_df_with_named_index() -> pd.DataFrame:
+        """someone put the effort into naming the index,
+        you'd probably want to display that"""
+        return pd.DataFrame(
+            {'a': ["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]},
+            index=pd.Index([10, 20, 30, 40, 50], name='foo'))
+
+    get_df_with_named_index()
 
 Someone took the time to name this index ``foo``. That name carries meaning —
 it might be a join key, a time series frequency, or a categorical grouping.
@@ -148,15 +153,17 @@ MultiIndex Columns
 
 .. code-block:: python
 
-    # DDD: MultiIndex Columns
-    # Hierarchical column headers from .pivot_table() or .groupby().agg().
-    # Most viewers crash or show ugly tuple strings like ('foo', 'a').
-    # Buckaroo flattens them into readable headers.
-    cols = pd.MultiIndex.from_tuples(
-        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'), ('bar', 'b'), ('bar', 'c')],
-        names=['level_a', 'level_b'])
-    pd.DataFrame([["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]] * 6,
-                 columns=cols)
+    # from buckaroo/ddd_library.py
+    def get_multiindex_with_names_cols_df(rows=15) -> pd.DataFrame:
+        cols = pd.MultiIndex.from_tuples(
+            [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
+             ('bar', 'b'), ('bar', 'c')],
+            names=['level_a', 'level_b'])
+        return pd.DataFrame(
+            [["asdf", "foo_b", "bar_a", "bar_b", "bar_c"]] * rows,
+            columns=cols)
+
+    get_multiindex_with_names_cols_df(rows=6)
 
 Hierarchical column headers are common after ``.pivot_table()`` and
 ``.groupby().agg()``. Most viewers either crash or flatten them into ugly
@@ -175,17 +182,18 @@ MultiIndex on Rows
 
 .. code-block:: python
 
-    # DDD: MultiIndex on Rows
-    # Two-level row index plus a None in the last row of bar_col —
-    # a missing string mixed with non-missing strings.
-    # Each index level becomes an extra column without breaking the layout.
-    row_index = pd.MultiIndex.from_tuples([
-        ('foo', 'a'), ('foo', 'b'),
-        ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
-        ('baz', 'a')])
-    pd.DataFrame({'foo_col': [10, 20, 30, 40, 50, 60],
-                  'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
-                 index=row_index)
+    # from buckaroo/ddd_library.py
+    def get_multiindex_index_df() -> pd.DataFrame:
+        row_index = pd.MultiIndex.from_tuples([
+            ('foo', 'a'), ('foo', 'b'),
+            ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
+            ('baz', 'a')])
+        return pd.DataFrame({
+            'foo_col': [10, 20, 30, 40, 50, 60],
+            'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
+            index=row_index)
+
+    get_multiindex_index_df()
 
 Multi-level row indexes are the counterpart to MultiIndex columns. They
 appear after ``.groupby()`` without ``.reset_index()``, or when loading
@@ -208,16 +216,18 @@ Three-Level MultiIndex
 
 .. code-block:: python
 
-    # DDD: Three-Level MultiIndex
-    # Three levels of row hierarchy. Tests that column renaming handles
-    # an arbitrary number of index levels without name collisions.
-    row_index = pd.MultiIndex.from_tuples([
-        ('foo', 'a', 3), ('foo', 'b', 2),
-        ('bar', 'a', 1), ('bar', 'b', 3), ('bar', 'c', 5),
-        ('baz', 'a', 6)])
-    pd.DataFrame({'foo_col': [10, 20, 30, 40, 50, 60],
-                  'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
-                 index=row_index)
+    # from buckaroo/ddd_library.py
+    def get_multiindex3_index_df() -> pd.DataFrame:
+        row_index = pd.MultiIndex.from_tuples([
+            ('foo', 'a', 3), ('foo', 'b', 2),
+            ('bar', 'a', 1), ('bar', 'b', 3), ('bar', 'c', 5),
+            ('baz', 'a', 6)])
+        return pd.DataFrame({
+            'foo_col': [10, 20, 30, 40, 50, 60],
+            'bar_col': ['foo', 'bar', 'baz', 'quux', 'boff', None]},
+            index=row_index)
+
+    get_multiindex3_index_df()
 
 If two levels are hard, three levels are harder. This exercises the
 column-renaming logic that has to handle an arbitrary number of index levels
@@ -235,20 +245,22 @@ MultiIndex on Both Axes
 
 .. code-block:: python
 
-    # DDD: MultiIndex on Both Axes (the boss fight)
-    # Hierarchical headers on both rows and columns, both with named levels.
-    # This is what pd.pivot_table() produces on complex groupings.
-    # Tests column counting, index handling, and header rendering simultaneously.
-    row_index = pd.MultiIndex.from_tuples(
-        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
-         ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
-        names=['index_name_1', 'index_name_2'])
-    cols = pd.MultiIndex.from_tuples(
-        [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
-         ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
-        names=['level_a', 'level_b'])
-    pd.DataFrame([[10, 20, 30, 40, 50, 60]] * 6,
-                 columns=cols, index=row_index)
+    # from buckaroo/ddd_library.py
+    def get_multiindex_with_names_both() -> pd.DataFrame:
+        row_index = pd.MultiIndex.from_tuples([
+            ('foo', 'a'), ('foo', 'b'),
+            ('bar', 'a'), ('bar', 'b'), ('bar', 'c'),
+            ('baz', 'a')],
+            names=['index_name_1', 'index_name_2'])
+        cols = pd.MultiIndex.from_tuples(
+            [('foo', 'a'), ('foo', 'b'), ('bar', 'a'),
+             ('bar', 'b'), ('bar', 'c'), ('baz', 'a')],
+            names=['level_a', 'level_b'])
+        return pd.DataFrame([
+            [10, 20, 30, 40, 50, 60]] * 6,
+            columns=cols, index=row_index)
+
+    get_multiindex_with_names_both()
 
 The boss fight: hierarchical headers on both axes, with named levels on
 both sides. This is what ``pd.pivot_table()`` produces on complex groupings.
@@ -267,25 +279,25 @@ Weird Types (Pandas)
 
 .. code-block:: python
 
-    # DDD: Weird Types (Pandas)
-    # Four types most viewers ignore entirely:
-    # - Categorical: fixed set of allowed values, not a string
-    # - Timedelta: a duration ("1d 2h 3m 4s"), not a timestamp
-    # - Period: a span of time ("January 2021"), not a point in time
-    # - Interval: a range like (0, 1], common in pd.cut() output
-    pd.DataFrame({
-        'categorical': pd.Categorical(
-            ['red', 'green', 'blue', 'red', 'green']),
-        'timedelta': pd.to_timedelta(
-            ['1 days 02:03:04', '0 days 00:00:01',
-             '365 days', '0 days 00:00:00.001',
-             '0 days 00:00:00.000100']),
-        'period': pd.Series(
-            pd.period_range('2021-01', periods=5, freq='M')),
-        'interval': pd.Series(
-            pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3, 4, 5])),
-        'int_col': [10, 20, 30, 40, 50],
-    })
+    # from buckaroo/ddd_library.py
+    def df_with_weird_types() -> pd.DataFrame:
+        """DataFrame with unusual dtypes that historically broke rendering.
+        Exercises: categorical, timedelta, period, interval."""
+        return pd.DataFrame({
+            'categorical': pd.Categorical(
+                ['red', 'green', 'blue', 'red', 'green']),
+            'timedelta': pd.to_timedelta(
+                ['1 days 02:03:04', '0 days 00:00:01',
+                 '365 days', '0 days 00:00:00.001',
+                 '0 days 00:00:00.000100']),
+            'period': pd.Series(
+                pd.period_range('2021-01', periods=5, freq='M')),
+            'interval': pd.Series(
+                pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3, 4, 5])),
+            'int_col': [10, 20, 30, 40, 50],
+        })
+
+    df_with_weird_types()
 
 Four types that most viewers ignore:
 
@@ -311,30 +323,32 @@ Weird Types (Polars)
 
 .. code-block:: python
 
-    # DDD: Weird Types (Polars)
-    # Polars-specific types that historically broke rendering:
-    # - Duration: microsecond-precision, was blank before issue #622
-    # - Time: time-of-day without a date component
-    # - Decimal: fixed-precision (not float), important for financial data
-    # - Binary: raw bytes, displayed as hex strings
-    import polars as pl
-    import datetime as dt
-
-    pl.DataFrame({
-        'duration': pl.Series(
-            [100_000, 3_723_000_000, 86_400_000_000, 500, 60_000_000],
-            dtype=pl.Duration('us')),
-        'time': [dt.time(14, 30), dt.time(9, 15, 30),
-                 dt.time(0, 0, 1), dt.time(23, 59, 59), dt.time(12, 0)],
-        'categorical': pl.Series(
-            ['red', 'green', 'blue', 'red', 'green']).cast(pl.Categorical),
-        'decimal': pl.Series(
-            ['100.50', '200.75', '0.01', '99999.99', '3.14']
-        ).cast(pl.Decimal(10, 2)),
-        'binary': [b'hello', b'world', b'\x00\x01\x02',
-                   b'test', b'\xff\xfe'],
-        'int_col': [10, 20, 30, 40, 50],
-    })
+    # from buckaroo/ddd_library.py
+    def pl_df_with_weird_types():
+        """Polars DataFrame with unusual dtypes that historically broke
+        rendering. Exercises: Duration (#622), Time, Categorical,
+        Decimal, Binary."""
+        import datetime as dt
+        import polars as pl
+        return pl.DataFrame({
+            'duration': pl.Series([100_000, 3_723_000_000,
+                86_400_000_000, 500, 60_000_000],
+                dtype=pl.Duration('us')),
+            'time': [dt.time(14, 30), dt.time(9, 15, 30),
+                     dt.time(0, 0, 1), dt.time(23, 59, 59),
+                     dt.time(12, 0)],
+            'categorical': pl.Series(
+                ['red', 'green', 'blue', 'red', 'green']
+            ).cast(pl.Categorical),
+            'decimal': pl.Series(
+                ['100.50', '200.75', '0.01', '99999.99', '3.14']
+            ).cast(pl.Decimal(10, 2)),
+            'binary': [b'hello', b'world', b'\x00\x01\x02',
+                       b'test', b'\xff\xfe'],
+            'int_col': [10, 20, 30, 40, 50],
+        })
+
+    pl_df_with_weird_types()
 
 Polars has its own set of tricky types:
 
@@ -378,10 +392,6 @@ For details on how to create your own static embeds, see the
 Try it yourself
 ---------------
 
-.. code-block:: bash
-
-    pip install buckaroo
-
 .. code-block:: python
 
     from buckaroo.ddd_library import *

From 638edde44a4b54ca18d6f99a154b3834aa4de1a8 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:47:48 -0400
Subject: [PATCH 11/29] docs: add missing ddd_library import to notebook
 example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/dastardly-dataframe-dataset.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/source/articles/dastardly-dataframe-dataset.rst b/docs/source/articles/dastardly-dataframe-dataset.rst
index ef594baf..9c5f3973 100644
--- a/docs/source/articles/dastardly-dataframe-dataset.rst
+++ b/docs/source/articles/dastardly-dataframe-dataset.rst
@@ -405,6 +405,7 @@ Try it yourself
 Or in a Jupyter notebook, just::
 
     import buckaroo
+    from buckaroo.ddd_library import df_with_weird_types
     df_with_weird_types()  # renders inline
 
 The Dastardly DataFrame Dataset is also available as an interactive tour

From d86a6c12fb8e3f974f8481f9d0864fbf0aa8aa50 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 17:54:26 -0400
Subject: [PATCH 12/29] =?UTF-8?q?fix:=20address=20review=20comments=20?=
 =?UTF-8?q?=E2=80=94=20ship=20static-embed=20in=20wheel,=20use=20native=20?=
 =?UTF-8?q?polars?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add static-embed.js/css to hatch build artifacts so they ship in
  the wheel (P1: users can actually copy the files the docs reference)
- Use pl_df_with_weird_types() instead of the pandas-converted version
  so the DDD polars page exercises the real polars serialization path
- Update embedding guide with reliable copy command

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/embedding-guide.rst | 9 +++++++--
 pyproject.toml                           | 2 +-
 scripts/generate_ddd_static_html.py      | 8 ++++----
 3 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/docs/source/articles/embedding-guide.rst b/docs/source/articles/embedding-guide.rst
index 53b020da..2cba2d0d 100644
--- a/docs/source/articles/embedding-guide.rst
+++ b/docs/source/articles/embedding-guide.rst
@@ -74,8 +74,13 @@ Generate a static embed
         f.write(html)
 
 The HTML file references ``static-embed.js`` and ``static-embed.css``.
-These are included in the buckaroo package under ``buckaroo/static/`` —
-copy them alongside your HTML or serve them from a web server.
+These are shipped in the buckaroo wheel under ``buckaroo/static/``.
+Copy them alongside your generated HTML:
+
+.. code-block:: bash
+
+    STATIC=$(python -c "from pathlib import Path; import buckaroo; print(Path(buckaroo.__file__).parent / 'static')")
+    cp "$STATIC/static-embed.js" "$STATIC/static-embed.css" ./
 
 **With polars:**
 
diff --git a/pyproject.toml b/pyproject.toml
index 75040655..ca4d9b43 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -127,7 +127,7 @@ fallback-version = "0.0.0+unknown"
 
 [tool.hatch.build]
 only-packages = true
-artifacts = ["buckaroo/static/*.js", "buckaroo/static/*.css", "scripts/hatch_build.py"]
+artifacts = ["buckaroo/static/widget.js", "buckaroo/static/compiled.css", "buckaroo/static/standalone.js", "buckaroo/static/standalone.css", "buckaroo/static/static-embed.js", "buckaroo/static/static-embed.css", "scripts/hatch_build.py"]
 
 [tool.hatch.build.force-include]
 "buckaroo_mcp_tool.py" = "buckaroo_mcp_tool.py"
diff --git a/scripts/generate_ddd_static_html.py b/scripts/generate_ddd_static_html.py
index 4116c043..08943b04 100644
--- a/scripts/generate_ddd_static_html.py
+++ b/scripts/generate_ddd_static_html.py
@@ -21,7 +21,7 @@
     get_multiindex3_index_df,
     get_multiindex_with_names_both,
     df_with_weird_types,
-    pl_df_with_weird_types_as_pandas,
+    pl_df_with_weird_types,
 )
 
 OUT_DIR = os.path.join(os.path.dirname(__file__), '..', 'docs', 'extra-html', 'ddd')
@@ -65,9 +65,9 @@
      df_with_weird_types(),
      'Categorical, timedelta, period, and interval dtypes.'),
 
-    ('weird-types-polars', 'Weird Types (Polars → Pandas)',
-     pl_df_with_weird_types_as_pandas(),
-     'Duration, time, categorical, decimal, and binary dtypes from polars.'),
+    ('weird-types-polars', 'Weird Types (Polars)',
+     pl_df_with_weird_types(),
+     'Duration, time, categorical, decimal, and binary dtypes — native polars DataFrame.'),
 ]
 
 

From faa82125d3179cf785f577b6c07afc91dcb93878 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 23:21:31 -0400
Subject: [PATCH 13/29] docs: add article tracing data pipeline from engine to
 browser

Covers column renaming (a,b,c), type coercion before parquet,
fastparquet encoding, base64 transport, hyparquet decode, and
displayer/formatter dispatch with a full pipeline diagram.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/content-plan.md                      |   6 +
 docs/source/articles/types-to-display.rst | 301 ++++++++++++++++++++++
 2 files changed, 307 insertions(+)
 create mode 100644 docs/source/articles/types-to-display.rst

diff --git a/docs/content-plan.md b/docs/content-plan.md
index 2217e838..a28b3a1d 100644
--- a/docs/content-plan.md
+++ b/docs/content-plan.md
@@ -51,6 +51,12 @@ sponsored by cloudflare?
 
 
 
+# How types and data move from engine to browser
+
+Column renaming (a,b,c..z,aa,ab), type coercion before parquet, fastparquet encoding, base64 transport, hyparquet decode in browser, displayer/formatter dispatch. Full pipeline trace for a single cell value.
+
+See `docs/source/articles/types-to-display.rst`
+
 ## Help me work through a content plan.
 
 what other features have I recently released that desereve blog posts?
diff --git a/docs/source/articles/types-to-display.rst b/docs/source/articles/types-to-display.rst
new file mode 100644
index 00000000..6becf25d
--- /dev/null
+++ b/docs/source/articles/types-to-display.rst
@@ -0,0 +1,301 @@
+How Types and Data Move from Engine to Browser
+================================================
+
+You have a DataFrame in Python. Moments later it's rendered in a
+browser — scrollable, formatted, with histograms in the summary row.
+What happened in between?
+
+This article traces the full path: column renaming, type coercion,
+Parquet encoding, base64 transport, hyparquet decoding, and finally the
+displayer/formatter system that turns raw values into what you see on
+screen.
+
+
+Column renaming: why everything becomes ``a, b, c``
+-----------------------------------------------------
+
+The very first thing buckaroo does when serializing a DataFrame is
+rename every column. The original column ``"revenue"`` becomes ``a``.
+``"cost"`` becomes ``b``. The 27th column becomes ``aa``, then ``ab``,
+``ac``, and so on — base-26 using lowercase ASCII.
+
+.. code-block:: python
+
+    # buckaroo/df_util.py
+    def to_chars(n: int) -> str:
+        digits = to_digits(n, 26)
+        return "".join(map(lambda x: chr(x + 97), digits))
+
+    def old_col_new_col(df):
+        return [(orig, to_chars(i)) for i, orig in enumerate(df.columns)]
+
+Why? Three reasons:
+
+1. **Column names can be anything.** Tuples (from MultiIndex), integers,
+   strings with spaces and special characters, even a column literally
+   called ``"index"``. Parquet column names must be strings. AG-Grid
+   field names should be simple identifiers. Renaming to ``a, b, c``
+   sidesteps every edge case at once.
+
+2. **Collision avoidance.** When a DataFrame has a column named
+   ``"index"`` and we need to serialize the actual index as a column
+   too, there's a name collision. Renaming to short opaque names means
+   the index columns (``index``, ``index_a``, ``index_b`` for
+   MultiIndex levels) never collide with data columns.
+
+3. **Smaller payloads.** The column name is repeated in every row of the
+   JSON/Parquet output. ``"a"`` is smaller than
+   ``"quarterly_revenue_usd"``.
+
+The original name is preserved in the ``column_config`` that travels
+alongside the data. On the JS side, each column's ``header_name``
+(or ``col_path`` for MultiIndex) tells AG-Grid what to display in the
+header. The user never sees ``a, b, c`` — they see the real names.
+
+.. code-block:: python
+
+    # In styling_core.py — fix_column_config maps col→header_name
+    base_cc['col_name'] = col        # "a"
+    base_cc['header_name'] = str(orig_col_name)  # "revenue"
+
+
+Cleaning before serialization
+------------------------------
+
+Python's type system is richer than what Parquet (or JSON) can express
+directly. Before writing to Parquet, buckaroo coerces the awkward types:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - Python type
+     - Becomes
+     - Why
+   * - ``pd.Period`` (e.g. "2021-01")
+     - ``str``
+     - Parquet has no period type
+   * - ``pd.Interval`` (e.g. ``(0, 1]``)
+     - ``str``
+     - Parquet has no interval type
+   * - ``pd.Timedelta``
+     - ``str`` (e.g. "1 days 02:03:04")
+     - fastparquet can't encode timedeltas
+   * - ``bytes`` (e.g. from ``pl.Binary``)
+     - hex string (e.g. ``"68656c6c6f"``)
+     - Parquet object columns need strings
+   * - PyArrow-backed strings
+     - ``object`` dtype
+     - fastparquet needs object, not ArrowDtype
+   * - Timezone-naive datetimes
+     - UTC datetimes
+     - Avoids ambiguous serialization
+
+For the main DataFrame, this happens in ``to_parquet()``
+(``serialization_utils.py``). The function also calls
+``prepare_df_for_serialization()`` which does the column rename and
+flattens MultiIndex levels into regular columns (``index_a``,
+``index_b``, etc.).
+
+Summary stats have an additional wrinkle: each column's stats dict
+contains mixed types (strings like ``"int64"`` for dtype, floats for
+mean, lists for histogram bins). fastparquet can't handle mixed-type
+columns, so ``sd_to_parquet_b64()`` JSON-encodes every cell value first,
+making each column a pure string column. The JS side knows to
+``JSON.parse`` each cell back.
+
+.. code-block:: python
+
+    # Every cell becomes a JSON string before parquet encoding
+    def _json_encode_cell(val):
+        return json.dumps(_make_json_safe(val), default=str)
+
+
+Parquet encoding and base64 transport
+--------------------------------------
+
+buckaroo uses **fastparquet** with a custom JSON codec to write the
+DataFrame to an in-memory Parquet file. Categorical and object columns
+get JSON-encoded within the Parquet file (fastparquet's ``object_encoding='json'``).
+
+The raw Parquet bytes are then base64-encoded into an ASCII string:
+
+.. code-block:: python
+
+    def to_parquet_b64(df):
+        raw_bytes = to_parquet(df)
+        return base64.b64encode(raw_bytes).decode('ascii')
+
+The result is a tagged payload:
+
+.. code-block:: json
+
+    {"format": "parquet_b64", "data": "UEFSMQ..."}
+
+This travels over the wire — via Jupyter's comm protocol, a WebSocket,
+or embedded directly in an HTML ``<script>`` tag for static embeds. The
+format tag lets the JS side know it needs to decode Parquet rather than
+expecting raw JSON arrays.
+
+Why Parquet instead of JSON? Parquet is a columnar binary format —
+it's typically 5–10x smaller than the equivalent JSON for numeric data,
+and it preserves type information (int64 vs float64 vs string) that
+JSON discards.
+
+
+hyparquet: decoding Parquet in the browser
+-------------------------------------------
+
+On the JavaScript side, `hyparquet <https://github.com/hyparam/hyparquet>`_
+is a pure-JS Parquet reader. No WASM, no server — it reads the binary
+format directly in the browser.
+
+.. code-block:: typescript
+
+    // resolveDFData.ts
+    const buf = b64ToArrayBuffer(val.data);         // base64 → ArrayBuffer
+    const metadata = parquetMetadata(buf);           // read parquet footer
+    parquetRead({
+        file: buf,
+        metadata,
+        rowFormat: 'object',
+        onComplete: (data) => {
+            result = data.map(parseParquetRow);      // JSON.parse each cell
+        },
+    });
+
+The ``parseParquetRow`` step handles two things the raw Parquet decode
+doesn't:
+
+1. **JSON-encoded cells** (from summary stats): each string cell gets
+   ``JSON.parse``'d back to its real type — numbers, arrays, objects.
+
+2. **BigInt safety**: hyparquet decodes Parquet INT64 columns as
+   JavaScript ``BigInt``. If the value fits in ``Number.MAX_SAFE_INTEGER``
+   (2^53 - 1), it's converted to a regular ``Number``. Otherwise it's
+   stringified to preserve precision — this is why
+   ``9999999999999999999`` displays correctly instead of silently rounding.
+
+Results are cached (LRU, 8 entries) so switching between summary
+stats views doesn't re-decode the same Parquet bytes.
+
+
+Displayers and formatters: the last mile
+------------------------------------------
+
+At this point we have rows of data (``DFData``) and a ``column_config``
+that describes how each column should look. The ``column_config`` for
+each column includes a ``displayer_args`` object that names a
+**displayer** — this is the bridge between "raw value" and "what the
+user sees in the cell."
+
+The Python side picks the displayer based on summary stats:
+
+.. code-block:: python
+
+    # In a StylingAnalysis subclass
+    def style_column(cls, col, col_meta):
+        dtype = col_meta.get('dtype')
+        if dtype == 'float64':
+            return {'displayer_args': {
+                'displayer': 'float',
+                'min_fraction_digits': 2,
+                'max_fraction_digits': 4}}
+        elif dtype == 'timedelta64[ns]':
+            return {'displayer_args': {'displayer': 'duration'}}
+        ...
+
+The JS side receives this config and dispatches to the right formatter:
+
+.. code-block:: typescript
+
+    // Displayer.ts — getFormatter() is the dispatcher
+    switch (fArgs.displayer) {
+        case "integer":  return getIntegerFormatter(fArgs);
+        case "float":    return getFloatFormatter(fArgs);
+        case "string":   return getStringFormatter(fArgs);
+        case "boolean":  return booleanFormatter;
+        case "duration": return getDurationFormatter();
+        case "obj":      return getObjectFormatter(fArgs);
+        ...
+    }
+
+Each formatter is an AG-Grid ``ValueFormatterFunc`` — it receives the
+raw cell value and returns the display string. Some highlights:
+
+- **Integers** get thousands separators via ``Intl.NumberFormat`` and
+  right-padding for alignment.
+- **Floats** get configurable decimal places, also via
+  ``Intl.NumberFormat``, with padding to align decimal points across
+  rows.
+- **Durations** parse pandas timedelta strings (``"1 days 02:03:04"``)
+  and render as ``"1d 2h 3m 4s"``, with sub-second precision down to
+  microseconds.
+- **Booleans** display as Python-convention ``True``/``False``, not
+  JS-convention ``true``/``false``.
+- **Objects** (dicts, lists, None) get a recursive Python-like repr:
+  ``{ 'key': value }``, ``[ 1, 2, 3 ]``, ``None``.
+
+For richer displays, there are **cell renderers** instead of formatters
+— these return React components rather than strings. Histograms, charts,
+links, images, and SVGs all use this path.
+
+.. code-block:: typescript
+
+    // Cell renderers return React components
+    case "histogram": return HistogramCell;
+    case "linkify":   return LinkCellRenderer;
+    case "chart":     return getChartCell(crArgs);
+
+
+The full pipeline
+------------------
+
+Putting it all together, here's the journey of a single cell value —
+say, a ``pd.Timedelta`` of "1 day, 2 hours, 3 minutes, 4 seconds":
+
+.. code-block:: text
+
+    Python                          Wire              Browser
+    ──────                          ────              ───────
+    pd.Timedelta('1d 2h 3m 4s')
+        │
+        ▼
+    rename columns (a, b, c...)
+        │
+        ▼
+    coerce to str: "1 days 02:03:04"
+        │
+        ▼
+    write to Parquet (fastparquet)
+        │
+        ▼
+    base64 encode ──────────────► {"format": "parquet_b64",
+                                   "data": "UEFSMQ..."}
+                                        │
+                                        ▼
+                                  b64 → ArrayBuffer
+                                        │
+                                        ▼
+                                  hyparquet.parquetRead()
+                                        │
+                                        ▼
+                                  parseParquetRow() → "1 days 02:03:04"
+                                        │
+                                        ▼
+                                  getDurationFormatter()
+                                        │
+                                        ▼
+                                  formatDuration() → "1d 2h 3m 4s"
+                                        │
+                                        ▼
+                                  AG-Grid renders: │ 1d 2h 3m 4s │
+
+The column header shows the original name from ``header_name`` in the
+config. The user sees a human-readable duration in a column with its
+real name. Everything in between — the rename, the coercion, the binary
+encoding, the BigInt handling — is invisible.
+
+That's the point. The pipeline exists so that every type, every edge
+case, every weird DataFrame gets displayed correctly without the user
+having to think about it.

From 350cd0e7e5d74c77ed5180f1258e9d6fb2164083 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Fri, 20 Mar 2026 23:35:07 -0400
Subject: [PATCH 14/29] docs: convert dataframe viewer article from markdown to
 RST

Converts so-you-want-to-write-a-dataframe-viewer to RST with a proper
list-table for the comparison of open source DataFrame viewers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...o-you-want-to-write-a-dataframe-viewer.rst | 284 ++++++++++++++++++
 1 file changed, 284 insertions(+)
 create mode 100644 docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst

diff --git a/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
new file mode 100644
index 00000000..b0a064ce
--- /dev/null
+++ b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
@@ -0,0 +1,284 @@
+So You Want to Write a DataFrame Viewer
+========================================
+
+You want to write a better viewer for tabular data. That's great, the
+world needs better interfaces in this space, and there is so much that
+can be improved on. Here are some of the biggest design decisions and
+their potential side effects, along with projects that chose different
+routes. There are many closed source data table viewers with various
+levels of capability. It seems like every new notebook hosting
+environment feels compelled to build their own dataframe viewer. In this
+article I will draw on my own experience creating Buckaroo, as well as
+observations from looking at popular open source table viewers like
+Perspective, Great Tables, DTale, Hytable, marimo, iTables, and
+iPydatagrid.
+
+I have run into each one of these issues while building buckaroo.
+
+
+Use-case questions
+-------------------
+
+Before starting, think about what use case you are looking to solve for.
+Are you trying to build tables for relatively static display (PDF to
+Huggingface data browser)? Do you want to serve dashboards (a limited
+set of interactions with users willing to customize heavily and
+specifically for styling)? Do you want to facilitate interactive use in
+an IDE like environment (VSCode notebooks, some internal data bench)? Do
+you want to work in notebook environments? What size datasets do you
+expect your users to work with? What performance expectations do your
+users have? Do you want users to be able to customize the experience?
+Without writing JS? Do you want to deal with streaming data? Do you want
+to allow editing of data?
+
+
+Processing: server-side or browser-based
+-----------------------------------------
+
+The biggest decision to make when building a table viewer is what to do
+with the data. Do you want the entire dataset to reside in the browser
+or do you want to leave it on the server and page the currently viewed
+section back and forth to the browser. Both approaches have their place.
+
+Browser based approaches are much cheaper to serve at scale. Browsers
+have improved significantly in the past decade and there are many
+applications that put over a gigabyte of data into the browser with no
+ill effects. Further with HTTP range requests, the full dataset doesn't
+even have to be loaded at once. Apache Arrow and Parquet make this
+approach more performant and attractive. This approach scales with little
+cost because S3 and Cloudflare are incredibly performant and inexpensive
+compared to spinning up server infrastructure.
+
+Browser based approaches fall down with datasets over 1 GB. Additionally
+1 GB is about the total limit of memory use that you want a single page
+to have, so if you have multiple dataframes that you want to display
+simultaneously, keep that in mind. Finally, browser based solutions
+require using browser based analytics engines instead of familiar tools
+like pandas and polars. Apache Arrow is packageable into a WebAssembly
+module, but packaging it into a JS build is tricky.
+
+Server based solutions are more familiar as traditional web apps,
+sometimes with some twists. Server based solutions excel for very large
+datasets that are backed by analytics engines. If your 10 GB table is
+already in a relational database, let the database do the sorting, and
+only send over the limited rows that are being displayed. Server based
+solutions with persistent connections also allow many more tables to be
+displayed simultaneously while limiting browser memory usage. If you have
+infrastructure built around analytics pipelines in traditional
+environments, server side solutions are often the better way to go.
+Sorting and histograms in particular can be hard to implement identically
+in different numerical engines.
+
+The downsides of a server based approach are that you always need to have
+the server running to make the table work. At the small end this means
+you can't simply host an artifact with your table in it. You can't serve
+a Jupyter notebook statically in a GitHub repo. If you intend to host an
+analytics system with your table, you now need server infrastructure to
+back it. Server infrastructure connected to a relational database or
+data warehouse is one level of expense — it is even more expensive (in
+terms of memory and CPU) to host Python-based analytics server-side.
+
+
+Serializing data
+-----------------
+
+For buckaroo, serializing data to JSON was the slowest part of the
+initial render (not true anymore, because of better lazy fetching).
+Serializing dataframes is hard. There are multiple numerical Python
+(Arrow, computation) concepts that don't have direct equivalents in JS
+or JSON. Notably infinity and NaN aren't valid in JSON. Furthermore
+datetime handling across JSON requires a processing layer — you will
+either encode strings or millisecond offsets, either requiring a metadata
+layer that can then be interpreted. Then there are common Python
+datatypes like timedelta that have no native JS equivalent.
+
+Next we get to the difficulty of serializing pandas data structures.
+Pandas indexes which apply to rows and columns occur in a variety of
+formats. Multi-level indexes can be challenging for display — they have
+to be special-cased in your display code regardless of how they are
+serialized. Pandas columns can also be named in a variety of ways,
+including as numerics or strings.
+
+These different dataframe configurations are challenging because they are
+hard to completely anticipate. In my experience, when a user constructed
+a dataframe with an unexpected structure, it was one of the most likely
+things to blow up buckaroo with a JS typing error. There were also
+exceptions thrown through most of the pandas processing code.
+
+Polars is a bit easier in this regard. Polars eschews having an index.
+
+Many of these issues exist when serializing to a binary format like
+Feather or Parquet, but are a bit different. With Feather/Parquet, make
+sure Python objects and lists serialize properly. Also if you want a
+single-file static HTML export to work, you will need to base64 encode
+the binary data. True binary-to-binary transfer requires a network
+connection.
+
+
+The table viewer component
+---------------------------
+
+There are many table components, so much so that there is a site
+dedicated to tracking their popularity. Increasing in complexity you
+have everything from static HTML, to jQuery-based libraries, to modern
+table grids, to AG-Grid, to extreme custom-coded frontend libraries.
+HTML-based tables allow simple customizability along with a great story
+for static export to the widest list of targets. jQuery-based libraries
+(limited table rows, pagination) are relatively simple to use and limit
+complexity — previously they were much easier to package into the Jupyter
+frontend environment than full JS build chains.
+
+Then there are modern table libraries that aren't AG-Grid. React-data-grid,
+angular-grid, tanstack-table, handsome-table. These libraries might be
+familiar. They have a straightforward licensing story. They also tend to
+have rough edges, limited adoption, and they tend to be abandoned. I
+haven't investigated these packages as much.
+
+Next up is AG-Grid. AG-Grid is the reliable gold standard for tables,
+under active development for over a decade. AG-Grid has a full
+commercial company behind it, along with a permissively licensed
+community edition. From my experience they haven't kneecapped the
+community edition in favor of the commercial edition, and aim to have
+the community edition as the best free table widget on the market. The
+tool is extensively documented with working examples. The company is
+completely unresponsive to bug reports from non-paying users in my
+experience. I chose AG-Grid after listening to an interview with their
+founder on the JS Jabber podcast.
+
+Then there are custom table widgets like Perspective, glide-data-grid,
+and whatever you cooked up yourself. Perspective has a very impressive
+table, and I suspect it has better performance than AG-Grid. It is
+minimally documented and doesn't have the wide community adoption that
+generates Stack Overflow guidance. glide-data-grid is an impressive
+piece of software, rendering to canvas. It also looks like it is falling
+into non-maintenance with no commits in the last 10 months.
+
+If you are writing your own table, congrats. You will have ultimate
+control over your user experience. You won't have to worry about
+dependencies on ``isEven`` or other npm trash. You will have a very
+complex core piece to maintain. At a minimum I'd recommend thoroughly
+investigating other widgets to see how they approached problems.
+
+
+The notebook environment
+-------------------------
+
+There are many different notebook environments. Jupyter Notebook, Google
+Colab, VSCode notebooks, classic notebooks (before Notebook 7.0),
+Marimo, Jupyter running on WASM (JupyterLite). All have slight
+differences that become especially significant for frontend code.
+Styling works differently, loading JavaScript is a bit different.
+Anywidget was developed to make all of this easier, and it does. Before
+anywidget, this section would have been much longer.
+
+Even determining what environment you are running in is challenging.
+This will come up when users file bugs. `widget_utils.py
+<https://github.com/paddymul/buckaroo/blob/main/buckaroo/widget_utils.py#L139-L169>`_
+is my function for determining which Jupyter environment I'm running in.
+
+
+Other questions
+----------------
+
+**Do you want to enable editing tables?** It isn't too challenging to
+enable frontend edits to modify the core dataframe of a table. But then
+what? For a full fledged application, you have a bunch of options. In the
+Jupyter notebook, you don't have many good options. Accessing widget
+state in a Jupyter notebook is possible, but it isn't obvious. Jupyter
+notebooks also make it easy to inadvertently rerun a cell — which would
+cause your user to lose all edits — a very frustrating experience.
+
+**What about events and callbacks?** Adding click handling events plumbed
+through to Python is an attractive option. But now your users have to
+make sure they don't have cycles in the event handlers. This is another
+place where building a tool for a Jupyter widget is different than
+building a tool for a framework or dashboard.
+
+
+Conclusion
+-----------
+
+I'm not suggesting that you avoid creating a table for the Jupyter
+environment. I am suggesting that you understand how broad a task it is,
+and the ways it could fail.
+
+
+Comparison of open source DataFrame viewers
+---------------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 12 10 10 12 10 15 12
+
+   * - Name
+     - Server / Browser
+     - JSON / Numeric
+     - Static Export
+     - Jupyter Compatible
+     - Dynamic
+     - Table Viewer
+     - Built on Anywidget?
+   * - Buckaroo
+     - Server
+     - Numeric
+     - No
+     - Yes
+     - Yes
+     - AG-Grid
+     - Yes
+   * - IPYdatagrid
+     - Server
+     - JSON
+     - No?
+     - Yes
+     - Yes
+     - Custom
+     - No
+   * - Perspective
+     - Browser
+     - Numeric
+     - Yes
+     - No?
+     - Yes
+     - Custom
+     - No
+   * - iTables
+     - Browser
+     - JSON
+     - Yes
+     - Yes
+     - No
+     - datatables (jQuery based)
+     - No
+   * - Great Tables
+     - Browser
+     - HTML
+     - Yes
+     - Yes
+     - No
+     - HTML
+     - No
+   * - DTale
+     - Server
+     - JSON?
+     - No?
+     - Yes
+     - Yes
+     - Custom
+     - No
+   * - Mito
+     - Server
+     - JSON
+     - No
+     - Yes
+     - Yes
+     - Custom
+     - No
+   * - Marimo
+     - Server
+     - JSON?
+     - Yes
+     - No
+     - Yes
+     - tanstack-table
+     - Yes

From f3f7480cea602ce6808f6cac7578b83aca0c2163 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sat, 21 Mar 2026 12:08:39 -0400
Subject: [PATCH 15/29] =?UTF-8?q?docs:=20fix=20comparison=20table=20?=
 =?UTF-8?q?=E2=80=94=20correct=20entries=20from=20research,=20add=20quak?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates based on research into each project:
- Buckaroo: Static Export → Yes
- Perspective: Both server/browser, Arrow serialization, Jupyter compatible
- DTale: JSON confirmed, No static export, uses react-virtualized
- Marimo: JSON confirmed, not Jupyter compatible, not anywidget
- ipydatagrid: No static export (confirmed broken), Lumino DataGrid
- Mito: Endo (custom) table viewer
- iTables: anywidget optional
- Add quak (manzt): DuckDB-backed, Arrow, anywidget
- Add hyperlinks to all project GitHub repos

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...o-you-want-to-write-a-dataframe-viewer.rst | 48 +++++++++++--------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
index b0a064ce..6d476690 100644
--- a/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
+++ b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
@@ -218,39 +218,39 @@ Comparison of open source DataFrame viewers
      - Dynamic
      - Table Viewer
      - Built on Anywidget?
-   * - Buckaroo
+   * - `Buckaroo <https://github.com/buckaroo-data/buckaroo>`_
      - Server
      - Numeric
-     - No
+     - Yes
      - Yes
      - Yes
      - AG-Grid
      - Yes
-   * - IPYdatagrid
+   * - `ipydatagrid <https://github.com/jupyter-widgets/ipydatagrid>`_
      - Server
      - JSON
-     - No?
+     - No
      - Yes
      - Yes
-     - Custom
+     - Lumino DataGrid (canvas)
      - No
-   * - Perspective
-     - Browser
-     - Numeric
+   * - `Perspective <https://github.com/finos/perspective>`_
+     - Both
+     - Arrow
+     - Yes
      - Yes
-     - No?
      - Yes
      - Custom
      - No
-   * - iTables
+   * - `iTables <https://github.com/mwouts/itables>`_
      - Browser
      - JSON
      - Yes
      - Yes
      - No
      - datatables (jQuery based)
-     - No
-   * - Great Tables
+     - Optional
+   * - `Great Tables <https://github.com/posit-dev/great-tables>`_
      - Browser
      - HTML
      - Yes
@@ -258,27 +258,35 @@ Comparison of open source DataFrame viewers
      - No
      - HTML
      - No
-   * - DTale
+   * - `DTale <https://github.com/man-group/dtale>`_
      - Server
-     - JSON?
-     - No?
+     - JSON
+     - No
      - Yes
      - Yes
-     - Custom
+     - react-virtualized
      - No
-   * - Mito
+   * - `Mito <https://github.com/mito-ds/mito>`_
      - Server
      - JSON
      - No
      - Yes
      - Yes
-     - Custom
+     - Endo (custom)
      - No
-   * - Marimo
+   * - `Marimo <https://github.com/marimo-team/marimo>`_
      - Server
-     - JSON?
+     - JSON
      - Yes
      - No
      - Yes
      - tanstack-table
+     - No
+   * - `quak <https://github.com/manzt/quak>`_
+     - Server
+     - Arrow
+     - No
+     - Yes
+     - Yes
+     - Custom HTML
      - Yes

From ad927ca47f18b03a24e71600b04bd25394e4e9b0 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sat, 21 Mar 2026 12:27:28 -0400
Subject: [PATCH 16/29] =?UTF-8?q?docs:=20update=20content=20plan=20?=
 =?UTF-8?q?=E2=80=94=20mark=20DDD,=20types-to-display,=20and=20viewer=20co?=
 =?UTF-8?q?mparison=20as=20published?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/content-plan.md | 80 +++++++++++++-------------------------------
 1 file changed, 24 insertions(+), 56 deletions(-)

diff --git a/docs/content-plan.md b/docs/content-plan.md
index a28b3a1d..17bf5c54 100644
--- a/docs/content-plan.md
+++ b/docs/content-plan.md
@@ -1,68 +1,36 @@
 
-# Dastardly Dataframe Dataset
+# Content Plan
 
-Static addition to docs,  pandas code blocks of weird dataframes, then the statically rendered bukaroo widget
+## Published (merged or ready to merge)
 
-talk about the dastardly dataframe dataset, and why these dataframes are generally hard to display,  what little things trip people up
+### Dastardly DataFrame Dataset (PR #641)
+Published at `docs/source/articles/dastardly-dataframe-dataset.rst`. Covers DDD with static embeds, full dtype coverage table, weird types for pandas and polars. Includes Polars DDD (issue #622).
 
-Note that although the types are rare, because buckaroo is built not as a customized table widget for use in dashboards but a way to see dataframes as they are in data workflow systems, being able to display all types is pretty important.
+### How types and data move from engine to browser
+Published at `docs/source/articles/types-to-display.rst`. Column renaming (a,b,c..z,aa,ab), type coercion before parquet, fastparquet encoding, base64 transport, hyparquet decode in browser, displayer/formatter dispatch. Full pipeline trace for a single cell value.
 
-Also note that this is a static embedding of the DFViewer, part of the new DFViewer embeddable system so you can integrate buckaroo into your apps simply.  more coming on the embeddable buckaroo
+### So you want to write a DataFrame viewer
+Published at `docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst`. Comparison of open source DataFrame viewers (Buckaroo, Perspective, iTables, Great Tables, DTale, Mito, Marimo, ipydatagrid, quak). Research in `~/personal/buckaroo-writing/research/`.
 
-# DDD for polars
+## Planned
 
-new release of the buckaroo static embedding that now supports polars.  once again talk about the DDD.  specifically https://github.com/buckaroo-data/buckaroo/issues/622
+### Static embedding improvements
+- Publish JS to CDN → reduced embed size. Talk about the journey: Jupyter → Marimo/Pyodide → static embedding → smaller static embedding
+- Page weight comparison: dbt (501KB compressed, 28MB total, 1.41s DCL), Snowflake (128kb/1.28mb/22.51mb/445ms), Databricks (127kb/797kb/313ms)
+- Customizing buckaroo via API for embeds — show styling, link to styling docs
+- Static search — maybe, take a crack at it
+- Link to the static embedding guide
 
-# Static embedding improvements
+### Styling buckaroo chrome
+Based on https://github.com/buckaroo-data/buckaroo/pull/583
 
-## publish the JS to a CDN -> reduced embed size talk about size reductions
-talk about how I bult this to better share what buckaroo is doing.  At first you needed to download jupyter and buckaroo.  Then Marimo Pyodide, now static embedding, now smaller static embedding
-
-does pageweight even matter, well to buckaroo it does, to dbt, apparently not, their home page is 501KB compressed 801KB raw,  the whole thing is 28Mb, DOM Content loaded in 1.41 seconds (This buckaroo page will be better of course,  the old version will probalby be better)
-
-Snowflake 128kb/1.28mb/22.51mb/445ms
-
-Databricks 127kb/797kb/313ms
-
-## Customizing buckaroo via api for embeds
-show some styling, link to styling docs
-
-## Static search
-
-Maybe,  take a crack at it
-
-Link to the static embedding guide
-
-## Styling buckaroo chrome
-based on 
-https://github.com/buckaroo-data/buckaroo/pull/583
-
-# Buckaroo embedding guide
-
-Why to embed buckaroo
-Which config makes sense for you - along with data sizes reasoning
-Customizing appearache
-Cusomizing buckaroo
-
-# embedding buckaroo for bigger data
-Parquet range queries on s3/r2 buckets
-sponsored by cloudflare?
-
-
-
-
-# How types and data move from engine to browser
-
-Column renaming (a,b,c..z,aa,ab), type coercion before parquet, fastparquet encoding, base64 transport, hyparquet decode in browser, displayer/formatter dispatch. Full pipeline trace for a single cell value.
-
-See `docs/source/articles/types-to-display.rst`
-
-## Help me work through a content plan.
-
-what other features have I recently released that desereve blog posts?
-Should I just start here?
-
-Where do these fit into the docs site?
+### Buckaroo embedding guide
+- Why to embed buckaroo
+- Which config makes sense for you — along with data sizes reasoning
+- Customizing appearance
+- Customizing buckaroo
 
+### Embedding buckaroo for bigger data
+Parquet range queries on S3/R2 buckets. Sponsored by Cloudflare?
 
 

From 17b263732ed58e06c71c98140e42833aabf7080a Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sat, 21 Mar 2026 13:01:44 -0400
Subject: [PATCH 17/29] fix: reset files already merged via PRs 641/642 to
 match main

DDD article, pyproject.toml, and readthedocs.yaml were modified by
earlier commits on this branch but the canonical versions were merged
to main via PRs 641 and 642. Reset to main to avoid regressions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/.readthedocs.yaml                        |   1 -
 .../articles/dastardly-dataframe-dataset.rst  | 303 +++++++++++++++++-
 pyproject.toml                                |   2 +-
 3 files changed, 287 insertions(+), 19 deletions(-)

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
index f497bbdf..8115940f 100644
--- a/docs/.readthedocs.yaml
+++ b/docs/.readthedocs.yaml
@@ -29,7 +29,6 @@ build:
         - uv venv
         - pnpm -C packages/buckaroo-js-core run build
         - pnpm -C packages/js run build:static
-        - touch buckaroo/static/compiled.css buckaroo/static/widget.js buckaroo/static/widget.css
         - uv run sphinx-build -T -b html docs/source  $READTHEDOCS_OUTPUT/html
         - ./scripts/marimo_wasm_output.sh buckaroo_ddd_tour.py run
         - ./scripts/marimo_wasm_output.sh buckaroo_compare.py edit
diff --git a/docs/source/articles/dastardly-dataframe-dataset.rst b/docs/source/articles/dastardly-dataframe-dataset.rst
index 9c5f3973..1aaa2023 100644
--- a/docs/source/articles/dastardly-dataframe-dataset.rst
+++ b/docs/source/articles/dastardly-dataframe-dataset.rst
@@ -4,24 +4,48 @@ The Dastardly DataFrame Dataset
 Every DataFrame viewer works fine on ``pd.DataFrame({'a': [1, 2, 3]})``.
 The question is what happens when the data gets weird.
 
-Buckaroo ships a collection of deliberately tricky DataFrames called the
-**Dastardly DataFrame Dataset** (DDD). These are the DataFrames that break
-other viewers — the ones with MultiIndex columns, NaN mixed with infinity,
-columns literally named ``index``, integers too large for JavaScript, and
-types that most tools pretend don't exist.
-
-This page shows each one rendered live in buckaroo's static embed. No
-Jupyter kernel, no server — just HTML and JavaScript. If you can see the
-tables below, the static embedding system is working.
+Displaying DataFrames in all their wonderfully variant splendor is quite a
+challenge. DataFrames come in many forms and there is little you can depend
+on when you want to serialize or display them. Through building Buckaroo I
+have tripped across many types of bugs from DataFrames that I didn't expect.
+
+So I compiled a set of the weirdest DataFrames I have seen in the wild — the
+ones that caused hard to debug errors, the ones that were hard to support —
+and reduced them to limited test cases. I call this the `Dastardly DataFrame
+Dataset <https://github.com/buckaroo-data/buckaroo/blob/main/buckaroo/ddd_library.py>`_
+(DDD). MultiIndex columns, NaN mixed with infinity, columns
+literally named ``index``, integers too large for JavaScript, types that most
+tools pretend don't exist. Through hard fought experience, Buckaroo has dealt
+with bugs or edge cases related to each one.
+
+The naming and early shape of the DDD was heavily influenced by an exchange
+with `Cecil Curry <https://github.com/leycec>`_, the author of
+`beartype <https://github.com/beartype/beartype>`_, on
+`beartype#529 <https://github.com/beartype/beartype/issues/529>`_. That guy
+is awesome. Be more like that guy. Seriously the most enjoyable bug report
+interaction I have ever had.
+
+This page shows each DDD member rendered live in buckaroo's static embed. No
+Jupyter kernel, no server — just HTML and JavaScript.
 
 Why this matters
 ----------------
 
+Buckaroo has the philosophy that every DataFrame should be displayable, at
+least in some form. Capabilities can be reduced — it's fine for ``mean`` to
+fail if there is a ``NaN`` in a column — but that failure can't cause
+Buckaroo to display nothing.
+
 If you build dashboards, you choose what data goes into your table. You
 control the types, the column names, the index. But if you're doing
 exploratory data analysis — loading CSVs from vendors, joining tables from
 different systems, debugging a pipeline that produces unexpected output —
-you don't control any of that. The data is what it is.
+you don't control any of that. The data is what it is. And who knows
+what an LLM will produce — code-generating agents can create DataFrames
+with column types you've never seen in your own code. Same goes for
+inherited data pipelines: someone else built it, you're debugging it,
+and the DataFrame you're staring at has types and structures you didn't
+choose.
 
 ``df.head()`` hides the problem. It shows you 5 rows and lets you believe
 everything is fine. Buckaroo is built for the opposite workflow: show you
@@ -30,6 +54,11 @@ everything, especially the parts that are surprising.
 The Dastardly DataFrames
 ------------------------
 
+The DDD is used extensively in Buckaroo's unit test suite. At a minimum,
+all DataFrames display in some way unless otherwise noted. Most display with
+full features — there are a couple of rough edges, but having a comprehensive
+test set is a very helpful start.
+
 Each section below shows the exact function from ``buckaroo.ddd_library``
 that creates the DataFrame, explains why it's tricky, and renders it live
 in a buckaroo static embed.
@@ -54,7 +83,7 @@ Infinity and NaN
 
     df_with_infinity()
 
-Three values, three completely different things: a missing value, positive
+Three non-numeric values that pop up in numeric columns: a missing value, positive
 infinity, and negative infinity. Many viewers display all three as blank or
 "NaN". Buckaroo distinguishes them.
 
@@ -201,9 +230,6 @@ data from hierarchical sources. The tricky part: each index level becomes
 an additional column that has to be displayed alongside the data columns
 without breaking the column count.
 
-This DataFrame also has a ``None`` in the last row of ``bar_col`` — a missing
-string value mixed with non-missing strings.
-
 .. raw:: html
 
    <iframe src="../ddd/multiindex-rows.html"
@@ -265,7 +291,9 @@ MultiIndex on Both Axes
 The boss fight: hierarchical headers on both axes, with named levels on
 both sides. This is what ``pd.pivot_table()`` produces on complex groupings.
 Everything about column counting, index handling, and header rendering gets
-tested simultaneously.
+tested simultaneously. There are still improvements planned here — the
+spacing is odd, the thick borders aren't in the correct place — but it
+displays, which is more than most viewers manage.
 
 .. raw:: html
 
@@ -368,8 +396,242 @@ you're migrating from pandas to polars, buckaroo moves with you.
    </iframe>
 
 
-What's happening under the hood
---------------------------------
+Full dtype coverage
+-------------------
+
+The DDD focuses on the types that cause trouble, but how does buckaroo
+handle *every* dtype? Here's the full picture across all three engines [1]_:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 12 12 12 14 14 18
+
+   * - Dtype
+     - Pandas
+     - Pandas (Arrow)
+     - Polars
+     - Parquet type
+     - JS type
+     - Buckaroo display
+   * - int8–int32
+     - Yes
+     - Yes
+     - Yes
+     - INT32
+     - Number
+     - ``1,234``
+   * - int64
+     - Yes
+     - Yes
+     - Yes
+     - INT64
+     - Number [2]_
+     - ``1,234,567``
+   * - uint8–uint64
+     - Yes
+     - Yes
+     - Yes
+     - INT32/INT64
+     - Number [2]_
+     - ``65,535``
+   * - BigInt (>2\ :sup:`53`)
+     - Yes
+     - Yes
+     - —
+     - INT64
+     - String [2]_
+     - ``9999999999999999999`` [5]_
+   * - float32
+     - Yes
+     - Yes
+     - Yes
+     - FLOAT
+     - Number
+     - ``2.500``
+   * - float64 (incl. inf/NaN)
+     - Yes
+     - Yes
+     - Yes
+     - DOUBLE
+     - Number
+     - ``Infinity``
+   * - complex128
+     - Fail [3]_
+     - —
+     - —
+     - —
+     - —
+     - —
+   * - bool
+     - Yes
+     - Yes
+     - Yes
+     - BOOLEAN
+     - boolean
+     - ``True``
+   * - string / object
+     - Yes
+     - Yes
+     - Yes
+     - BYTE_ARRAY
+     - String
+     - ``hello world``
+   * - mixed-type object
+     - Yes
+     - —
+     - —
+     - BYTE_ARRAY
+     - String
+     - ``{ 'a': 1, 'b': None }``
+   * - datetime
+     - Yes
+     - Yes
+     - Yes
+     - TIMESTAMP
+     - Date
+     - ``2021-01-15 14:30:00``
+   * - datetime + tz
+     - Not tested
+     - Yes
+     - Yes
+     - TIMESTAMP+tz
+     - Date
+     - ``2021-01-15 14:30:00``
+   * - timedelta / duration
+     - Yes
+     - Yes
+     - Yes
+     - → String [4]_
+     - String
+     - ``1d 2h 3m 4s``
+   * - date
+     - —
+     - Yes
+     - Not tested
+     - DATE (INT32)
+     - Date
+     - ``2021-01-15 00:00:00``
+   * - time
+     - —
+     - Yes
+     - Yes
+     - TIME (INT64)
+     - String
+     - ``14:30:00``
+   * - Categorical
+     - Yes
+     - Yes
+     - Yes
+     - DICT encoding
+     - String
+     - ``red``
+   * - Enum
+     - —
+     - —
+     - Not tested
+     - DICT encoding
+     - String
+     - ``red``
+   * - Period (time span)
+     - Yes
+     - —
+     - —
+     - → String [4]_
+     - String
+     - ``2021-01`` [6]_
+   * - Interval
+     - Yes
+     - —
+     - —
+     - → String [4]_
+     - String
+     - ``(0, 1]``
+   * - Decimal
+     - —
+     - Yes
+     - Yes
+     - DECIMAL
+     - Number
+     - ``100.50``
+   * - Binary
+     - —
+     - Yes
+     - Yes
+     - BYTE_ARRAY
+     - String (hex)
+     - ``68656c6c6f``
+   * - Sparse
+     - Fail [3]_
+     - —
+     - —
+     - —
+     - —
+     - —
+   * - Nullable int/float/bool
+     - Not tested
+     - —
+     - —
+     - INT32/INT64/BOOLEAN
+     - Number/boolean
+     - ``1,234`` / ``True``
+   * - List / Array
+     - —
+     - Yes
+     - Not tested
+     - LIST
+     - Array
+     - ``[ 1, 2, 3]``
+   * - Struct
+     - —
+     - Yes
+     - Not tested
+     - STRUCT
+     - Object
+     - ``{ 'a': 1, 'b': x }``
+   * - Null (all-null column)
+     - —
+     - —
+     - Not tested
+     - BYTE_ARRAY
+     - null
+     - ``(empty)``
+
+"Yes" means the dtype serializes and displays correctly. "Not tested" means
+serialization succeeds but there is no DDD test case exercising it through
+the full widget. "—" means the dtype does not exist in that engine.
+
+.. [1] Putting together this table exposed areas that still need work.
+   The interaction between Python dtype, Parquet physical type, JS
+   decoding, and display formatter has enough nuance for its own blog
+   post. Expect one soon.
+
+.. [2] hyparquet decodes INT64 as BigInt. Buckaroo converts to Number if
+   the value is ≤ ``Number.MAX_SAFE_INTEGER`` (2\ :sup:`53` - 1), otherwise
+   stringifies to preserve precision.
+
+.. [3] ``complex128`` and ``SparseDtype`` fail the Parquet path — Arrow
+   has no complex number type and can't convert sparse arrays. The JSON
+   path works with string fallback, but that path is being phased out.
+
+.. [4] ``→ String`` means the type has no native Parquet equivalent.
+   Buckaroo coerces it to a string before writing Parquet. Period becomes
+   ``'2021-01'``, Interval becomes ``'(0, 1]'``, timedelta becomes
+   ``'1 days 02:03:04'`` (pandas path only — Polars Duration is native).
+
+.. [5] Values above ``Number.MAX_SAFE_INTEGER`` are stringified on the JS
+   side to preserve exact precision, so they display without commas. The
+   value ``1`` in the same column still gets the integer formatter: ``1``.
+   This means a single column can show two different display styles depending
+   on whether each value fits in 53 bits.
+
+.. [6] A pandas ``Period`` is a *time span*, not a range between two dates.
+   ``Period('2021-01', 'M')`` means "the month of January 2021". Buckaroo
+   stringifies it because Parquet has no Period type. Don't confuse it with
+   ``Interval``, which is a numeric range like ``(0, 1]``.
+
+
+How this demo was built
+-----------------------
 
 Every table on this page is a **static embedding** of the full buckaroo
 widget. There is no Python kernel running. Here's what happened:
@@ -396,12 +658,19 @@ Try it yourself
 
     from buckaroo.ddd_library import *
     from buckaroo.artifact import to_html
+    from pathlib import Path
+    import shutil, buckaroo
 
     # Generate a static HTML page for any DataFrame
     html = to_html(df_with_weird_types(), title="Weird Types Demo")
     with open('weird-types.html', 'w') as f:
         f.write(html)
 
+    # Copy the JS/CSS assets alongside the HTML (see #643 for self-contained mode)
+    static = Path(buckaroo.__file__).parent / 'static'
+    for name in ('static-embed.js', 'static-embed.css'):
+        shutil.copy(static / name, '.')
+
 Or in a Jupyter notebook, just::
 
     import buckaroo
diff --git a/pyproject.toml b/pyproject.toml
index ca4d9b43..75040655 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -127,7 +127,7 @@ fallback-version = "0.0.0+unknown"
 
 [tool.hatch.build]
 only-packages = true
-artifacts = ["buckaroo/static/widget.js", "buckaroo/static/compiled.css", "buckaroo/static/standalone.js", "buckaroo/static/standalone.css", "buckaroo/static/static-embed.js", "buckaroo/static/static-embed.css", "scripts/hatch_build.py"]
+artifacts = ["buckaroo/static/*.js", "buckaroo/static/*.css", "scripts/hatch_build.py"]
 
 [tool.hatch.build.force-include]
 "buckaroo_mcp_tool.py" = "buckaroo_mcp_tool.py"

From 799eb3553be54b31db6146d6f5d5435cdabc5942 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sat, 21 Mar 2026 13:18:56 -0400
Subject: [PATCH 18/29] docs: address review comments on types-to-display
 article
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove Python code block for column renaming (not needed)
- Drop "smaller payloads" reason — not true for Parquet (column names
  stored once in metadata, not per-row)
- Clarify caching is buckaroo's LRU in resolveDFData.ts, not hyparquet
- Add TypeScript type flow diagram (string → ArrayBuffer → rows → cells)
- Add "why it ended up this way" section: evolution from default AG-Grid
  + pandas JSON (slow) to Parquet
- Explain BigInt flow: fast INT64 on Python side, hyparquet decodes as
  BigInt, buckaroo stringifies only when > MAX_SAFE_INTEGER
- Explain duration flow: whole column coerced to string in Python,
  parsed back to human-readable on JS side

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/types-to-display.rst | 67 +++++++++++++++++------
 1 file changed, 50 insertions(+), 17 deletions(-)

diff --git a/docs/source/articles/types-to-display.rst b/docs/source/articles/types-to-display.rst
index 6becf25d..2925c171 100644
--- a/docs/source/articles/types-to-display.rst
+++ b/docs/source/articles/types-to-display.rst
@@ -19,17 +19,7 @@ rename every column. The original column ``"revenue"`` becomes ``a``.
 ``"cost"`` becomes ``b``. The 27th column becomes ``aa``, then ``ab``,
 ``ac``, and so on — base-26 using lowercase ASCII.
 
-.. code-block:: python
-
-    # buckaroo/df_util.py
-    def to_chars(n: int) -> str:
-        digits = to_digits(n, 26)
-        return "".join(map(lambda x: chr(x + 97), digits))
-
-    def old_col_new_col(df):
-        return [(orig, to_chars(i)) for i, orig in enumerate(df.columns)]
-
-Why? Three reasons:
+Why? Two reasons:
 
 1. **Column names can be anything.** Tuples (from MultiIndex), integers,
    strings with spaces and special characters, even a column literally
@@ -43,10 +33,6 @@ Why? Three reasons:
    the index columns (``index``, ``index_a``, ``index_b`` for
    MultiIndex levels) never collide with data columns.
 
-3. **Smaller payloads.** The column name is repeated in every row of the
-   JSON/Parquet output. ``"a"`` is smaller than
-   ``"quarterly_revenue_usd"``.
-
 The original name is preserved in the ``column_config`` that travels
 alongside the data. On the JS side, each column's ``header_name``
 (or ``col_path`` for MultiIndex) tells AG-Grid what to display in the
@@ -176,8 +162,24 @@ doesn't:
    stringified to preserve precision — this is why
    ``9999999999999999999`` displays correctly instead of silently rounding.
 
-Results are cached (LRU, 8 entries) so switching between summary
-stats views doesn't re-decode the same Parquet bytes.
+Buckaroo caches decoded results in its own LRU cache (8 entries) in
+``resolveDFData.ts`` — hyparquet itself doesn't cache. When you switch
+between the "main" and "summary stats" views, the parquet bytes don't
+get re-decoded if they're still in the cache.
+
+The type journey through this layer looks like:
+
+.. code-block:: text
+
+    Python sends:  string (base64)
+         ↓
+    b64ToArrayBuffer():  ArrayBuffer (raw bytes)
+         ↓
+    parquetRead():  Array<Record<string, unknown>>
+         ↓
+    parseParquetRow():  DFData (Array<DFDataRow>)
+         ↓
+    AG-Grid receives: typed cell values (number | string | boolean | object)
 
 
 Displayers and formatters: the last mile
@@ -299,3 +301,34 @@ encoding, the BigInt handling — is invisible.
 That's the point. The pipeline exists so that every type, every edge
 case, every weird DataFrame gets displayed correctly without the user
 having to think about it.
+
+
+Why it ended up this way
+-------------------------
+
+Buckaroo originally relied on default AG-Grid behavior and pandas'
+built-in JSON serialization. That worked for simple DataFrames, but
+edge cases kept appearing — and Python's JSON encoding turned out to be
+very, very slow. Moving to Parquet solved the performance problem and
+brought type preservation for free.
+
+A few examples of how the pipeline handles specific types:
+
+**BigInts (>2^53):** On the Python side, these are just regular int64
+values — they get written to Parquet as INT64, no conversion needed,
+full speed. The complexity lives entirely on the JS side: hyparquet
+decodes INT64 as JavaScript ``BigInt``, and buckaroo's
+``parseParquetRow()`` checks whether each value fits in
+``Number.MAX_SAFE_INTEGER``. If it does, it becomes a regular
+``Number`` (so the integer formatter works). If not, it's stringified
+to preserve precision. This means Python doesn't have to know or care
+about JavaScript's numeric limitations.
+
+**Durations / Timedeltas:** These are coerced to strings on the Python
+side — the entire column becomes string values like
+``"1 days 02:03:04"`` before Parquet encoding. Parquet has no native
+duration type, and fastparquet can't encode timedeltas directly. The JS
+side then parses these strings back into human-readable format
+(``"1d 2h 3m 4s"``) via the duration formatter. The round-trip through
+strings is lossy in theory but lossless in practice — pandas timedelta
+string repr preserves full precision down to microseconds.

From b913b04c727da9455437ad784cfc6bd6a7583092 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sat, 21 Mar 2026 17:49:38 -0400
Subject: [PATCH 19/29] docs: add Panel Tabulator, Streamlit, hyperlinks to
 viewer article

- Drop nonexistent "Hytable" from intro
- Add Panel Tabulator and Streamlit st.dataframe to comparison table
- Add hyperlinks throughout prose: AG-Grid, Perspective, glide-data-grid,
  tanstack-table, react-data-grid, anywidget, JS Jabber podcast
- Update glide-data-grid description (actively maintained, not abandoned)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...o-you-want-to-write-a-dataframe-viewer.rst | 83 +++++++++++++------
 1 file changed, 58 insertions(+), 25 deletions(-)

diff --git a/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
index 6d476690..a7cda8bd 100644
--- a/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
+++ b/docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst
@@ -8,10 +8,18 @@ their potential side effects, along with projects that chose different
 routes. There are many closed source data table viewers with various
 levels of capability. It seems like every new notebook hosting
 environment feels compelled to build their own dataframe viewer. In this
-article I will draw on my own experience creating Buckaroo, as well as
+article I will draw on my own experience creating
+`Buckaroo <https://github.com/buckaroo-data/buckaroo>`__, as well as
 observations from looking at popular open source table viewers like
-Perspective, Great Tables, DTale, Hytable, marimo, iTables, and
-iPydatagrid.
+`Perspective <https://github.com/finos/perspective>`__,
+`Great Tables <https://github.com/posit-dev/great-tables>`__,
+`DTale <https://github.com/man-group/dtale>`__,
+`Marimo <https://github.com/marimo-team/marimo>`__,
+`iTables <https://github.com/mwouts/itables>`__,
+`ipydatagrid <https://github.com/jupyter-widgets/ipydatagrid>`__,
+`Panel Tabulator <https://panel.holoviz.org/reference/widgets/Tabulator.html>`__,
+and Streamlit's
+`st.dataframe <https://docs.streamlit.io/develop/api-reference/data/st.dataframe>`__.
 
 I have run into each one of these issues while building buckaroo.
 
@@ -128,30 +136,38 @@ for static export to the widest list of targets. jQuery-based libraries
 complexity — previously they were much easier to package into the Jupyter
 frontend environment than full JS build chains.
 
-Then there are modern table libraries that aren't AG-Grid. React-data-grid,
-angular-grid, tanstack-table, handsome-table. These libraries might be
-familiar. They have a straightforward licensing story. They also tend to
-have rough edges, limited adoption, and they tend to be abandoned. I
-haven't investigated these packages as much.
-
-Next up is AG-Grid. AG-Grid is the reliable gold standard for tables,
-under active development for over a decade. AG-Grid has a full
-commercial company behind it, along with a permissively licensed
-community edition. From my experience they haven't kneecapped the
-community edition in favor of the commercial edition, and aim to have
-the community edition as the best free table widget on the market. The
-tool is extensively documented with working examples. The company is
-completely unresponsive to bug reports from non-paying users in my
-experience. I chose AG-Grid after listening to an interview with their
-founder on the JS Jabber podcast.
-
-Then there are custom table widgets like Perspective, glide-data-grid,
+Then there are modern table libraries that aren't AG-Grid.
+`React-data-grid <https://github.com/adazzle/react-data-grid>`_,
+angular-grid,
+`tanstack-table <https://github.com/TanStack/table>`_,
+`handsome-table <https://github.com/nicenemo/handsome-table>`_.
+These libraries might be familiar. They have a straightforward licensing
+story. They also tend to have rough edges, limited adoption, and they
+tend to be abandoned. I haven't investigated these packages as much.
+
+Next up is `AG-Grid <https://github.com/ag-grid/ag-grid>`_. AG-Grid is
+the reliable gold standard for tables, under active development for over
+a decade. AG-Grid has a full commercial company behind it, along with a
+permissively licensed community edition. From my experience they haven't
+kneecapped the community edition in favor of the commercial edition, and
+aim to have the community edition as the best free table widget on the
+market. The tool is extensively documented with working examples. The
+company is completely unresponsive to bug reports from non-paying users
+in my experience. I chose AG-Grid after listening to
+`an interview with their founder
+<https://topenddevs.com/podcasts/javascript-jabber/episodes/ag-grid-with-niall-crosby-jsj-412>`_
+on the JS Jabber podcast.
+
+Then there are custom table widgets like
+`Perspective <https://github.com/finos/perspective>`__,
+`glide-data-grid <https://github.com/glideapps/glide-data-grid>`__,
 and whatever you cooked up yourself. Perspective has a very impressive
 table, and I suspect it has better performance than AG-Grid. It is
 minimally documented and doesn't have the wide community adoption that
 generates Stack Overflow guidance. glide-data-grid is an impressive
-piece of software, rendering to canvas. It also looks like it is falling
-into non-maintenance with no commits in the last 10 months.
+piece of software, rendering to canvas. It is solo-maintained by its
+creator at Glide Apps — actively developed but quietly, with Streamlit
+as its biggest downstream consumer.
 
 If you are writing your own table, congrats. You will have ultimate
 control over your user experience. You won't have to worry about
@@ -168,8 +184,9 @@ Colab, VSCode notebooks, classic notebooks (before Notebook 7.0),
 Marimo, Jupyter running on WASM (JupyterLite). All have slight
 differences that become especially significant for frontend code.
 Styling works differently, loading JavaScript is a bit different.
-Anywidget was developed to make all of this easier, and it does. Before
-anywidget, this section would have been much longer.
+`Anywidget <https://anywidget.dev/>`_ was developed to make all of this
+easier, and it does. Before anywidget, this section would have been much
+longer.
 
 Even determining what environment you are running in is challenging.
 This will come up when users file bugs. `widget_utils.py
@@ -282,6 +299,22 @@ Comparison of open source DataFrame viewers
      - Yes
      - tanstack-table
      - No
+   * - `Panel Tabulator <https://github.com/holoviz/panel>`_
+     - Both
+     - JSON
+     - Yes
+     - Yes
+     - Yes
+     - Tabulator.js
+     - No
+   * - `Streamlit <https://github.com/streamlit/streamlit>`_
+     - Server
+     - Arrow
+     - No
+     - No
+     - Yes
+     - glide-data-grid (canvas)
+     - No
    * - `quak <https://github.com/manzt/quak>`_
      - Server
      - Arrow

From 3188f6fb82e7b7874a0c26abb6f43352536a0ecd Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sun, 22 Mar 2026 17:21:50 -0400
Subject: [PATCH 20/29] docs: flesh out Depot CI article with before/after and
 dependency testing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add before/after comparison: 4 jobs in 6 min → 23 jobs in 7 min
- Add section on dual dependency testing strategy (min pinned + max versions)
- Explain why pandas/pyarrow/polars compatibility testing needs fast CI
- Link to Depot open source sponsorship program

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 177 +++++++++++++++++++++++++++++
 1 file changed, 177 insertions(+)
 create mode 100644 docs/source/articles/why-depot.rst

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
new file mode 100644
index 00000000..53f5f5f8
--- /dev/null
+++ b/docs/source/articles/why-depot.rst
@@ -0,0 +1,177 @@
+Why Buckaroo Uses Depot for CI
+===============================
+
+`Depot <https://depot.dev/>`_ sponsors Buckaroo's CI infrastructure and
+I really appreciate that. This article explains why I switched and what
+changed.
+
+The problem with GitHub Actions
+--------------------------------
+
+GitHub Actions is slow and the cache is slower. I have known this for a
+long time. I believe in CI, but it is hard to set up, and then once you
+get it running it's way slower than it needs to be. It's like being
+saddled with a teammate who won't pull their weight and has no interest
+in changing — it demotivates you.
+
+When your CI takes 10+ minutes, you stop pushing small changes. You
+batch things up. You skip the test run "just this once." You merge
+without waiting for green because you've already context-switched to
+something else. Slow CI makes you write worse code.
+
+What Buckaroo's CI actually does
+---------------------------------
+
+Buckaroo is a complex project with a significant Python and TypeScript
+codebase. The full package is deployed to 8 environments:
+
+- Jupyter (notebook + lab)
+- Marimo
+- JupyterLite (WASM/Pyodide)
+- Marimo WASM
+- VSCode (can't integration-test this one)
+- Google Colab (same)
+- Static self-contained embeds
+- Buckaroo server (used for the MCP server)
+
+The CI pipeline runs 22 jobs across 2 waves: linting, JS build + test,
+a Python wheel build, then 6 Playwright integration test suites
+(Storybook, JupyterLab, Marimo, WASM Marimo, Server, Static Embed),
+Python tests across 4 versions (3.11–3.14), an MCP integration test,
+styling screenshot comparisons, and a docs build.
+
+Integration testing in particular is really important — I can't manually
+test each environment for each code change. When a change breaks Marimo
+but not Jupyter, I need to know before it ships.
+
+LLMs changed the equation
+---------------------------
+
+LLM coding has changed the way I approach devops. First, it makes it
+easier to accomplish devops changes — this is great. Claude in
+particular has made it possible to get my Playwright integration tests
+to a place where I really trust them to run reliably. That has been
+awesome.
+
+At the same time, LLMs make testing more important than ever. I cannot
+move fast with LLMs without a solid test suite that runs fast. When
+Claude makes a change across 5 files, I need to know in minutes — not
+10 minutes — whether it broke something. The tighter the feedback loop,
+the more ambitious the changes I can attempt.
+
+What Depot changed
+-------------------
+
+The CTO responded to my request for open source sponsorship on
+Christmas Eve. Since then:
+
+- **Critical path: ~3.5 minutes.** From push to all-green (ignoring
+  the non-blocking Windows job). 22 jobs, 3.5 minutes. That's fast
+  enough that I don't context-switch away.
+- **Commit to first step running: ~30 seconds** on Linux. GitHub adds
+  about 6 seconds of latency. Depot provisions a runner in ~18 seconds.
+  On GitHub's own runners this used to be minutes.
+- **Cost: ~$0.18 per run** on 2-CPU runners. I tested 4-CPU and 8-CPU
+  runners too — no measurable speedup. The workload is I/O-bound
+  (package installs, Playwright browser launches), not CPU-bound.
+  Bigger runners just cost more for the same wall-clock time.
+- **~$9–18/month** at my typical push cadence. The Developer plan
+  ($20/month, 2,000 included minutes) covers about 52 full CI runs.
+
+The numbers
+------------
+
+Here's what the pipeline looks like on Depot 2-CPU runners:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 15
+
+   * - Job
+     - Duration
+     - % Useful Work
+   * - Python / Test (avg across versions)
+     - 1m 41s
+     - 84%
+   * - JupyterLab Playwright
+     - 2m 03s
+     - 77%
+   * - Storybook Playwright
+     - 1m 53s
+     - 81%
+   * - Server Playwright
+     - 2m 05s
+     - 74%
+   * - Marimo Playwright
+     - 1m 30s
+     - 68%
+   * - WASM Marimo Playwright
+     - 1m 40s
+     - 70%
+   * - Build JS + Python Wheel
+     - 0m 59s
+     - 44%
+   * - JS / Build + Test
+     - 0m 53s
+     - —
+   * - Windows (non-blocking)
+     - 8m 02s
+     - 28%
+
+The "% Useful Work" column is actual test/build time vs. setup overhead
+(checkout, install dependencies, provision). Most jobs are 70–84%
+useful, which is good. Windows is 28% useful because ``uv install``
+takes 3m29s on Windows vs. 3 seconds on Linux.
+
+
+Before and after
+-----------------
+
+Before Depot, Buckaroo's CI had **4 jobs**: lint and Python tests on 3
+versions. That took about 6 minutes on GitHub Actions runners.
+
+Today Buckaroo's CI has **23 jobs**: lint, JS build + test, wheel build,
+Python tests across 4 versions with two dependency strategies, 6
+Playwright integration suites, MCP integration, smoke tests, docs build,
+styling screenshots, TestPyPI publish, and Windows. That takes about
+**7 minutes** on Depot.
+
+Six times more jobs in roughly the same wall-clock time. The fast
+runners made it practical to add all of those integration tests — if
+each new test suite added 5 minutes, I never would have added them.
+
+
+Testing against dependency versions
+-------------------------------------
+
+Depending on pandas, PyArrow, and polars simultaneously is tricky.
+These are complex packages with their own release cadences and breaking
+changes. A new pandas release can change default string dtype behavior.
+A polars update can change how Duration columns serialize. PyArrow
+versions affect Parquet compatibility.
+
+Buckaroo runs two sets of test suites: the regular suite tests against
+the minimum pinned versions in ``pyproject.toml``, and the "Max
+Versions" suite tests against the latest releases of every dependency.
+This runs across Python 3.11 through 3.14. The goal is to catch
+compatibility issues before users do — if polars 1.x breaks something,
+I want to know from CI, not from a bug report.
+
+This strategy only works if the test suite is fast enough to run both
+configurations on every push. On slow CI, you'd run one and hope for
+the best.
+
+
+What I'd tell other open source maintainers
+---------------------------------------------
+
+If your CI takes more than 5 minutes and you've been meaning to fix it
+but haven't, Depot's `open source sponsorship program
+<https://depot.dev/open-source>`_ is worth applying to. The switch was
+straightforward — change the ``runs-on`` label in your workflow YAML,
+everything else stays the same.
+
+The real value isn't the raw speed. It's that fast CI changes your
+behavior. You push more often, you test more things, you catch problems
+earlier. Slow CI is a tax on every decision you make. Removing that tax
+compounds.

From 0688c584e4a02e3c2515d1bc9e325b3fcb239801 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sun, 22 Mar 2026 17:44:51 -0400
Subject: [PATCH 21/29] docs: remove Windows job from Depot article

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index 53f5f5f8..abc83361 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -65,9 +65,8 @@ What Depot changed
 The CTO responded to my request for open source sponsorship on
 Christmas Eve. Since then:
 
-- **Critical path: ~3.5 minutes.** From push to all-green (ignoring
-  the non-blocking Windows job). 22 jobs, 3.5 minutes. That's fast
-  enough that I don't context-switch away.
+- **Critical path: ~3.5 minutes.** From push to all-green. 22 jobs,
+  3.5 minutes. That's fast enough that I don't context-switch away.
 - **Commit to first step running: ~30 seconds** on Linux. GitHub adds
   about 6 seconds of latency. Depot provisions a runner in ~18 seconds.
   On GitHub's own runners this used to be minutes.
@@ -114,14 +113,10 @@ Here's what the pipeline looks like on Depot 2-CPU runners:
    * - JS / Build + Test
      - 0m 53s
      - —
-   * - Windows (non-blocking)
-     - 8m 02s
-     - 28%
 
 The "% Useful Work" column is actual test/build time vs. setup overhead
 (checkout, install dependencies, provision). Most jobs are 70–84%
-useful, which is good. Windows is 28% useful because ``uv install``
-takes 3m29s on Windows vs. 3 seconds on Linux.
+useful.
 
 
 Before and after
@@ -130,11 +125,11 @@ Before and after
 Before Depot, Buckaroo's CI had **4 jobs**: lint and Python tests on 3
 versions. That took about 6 minutes on GitHub Actions runners.
 
-Today Buckaroo's CI has **23 jobs**: lint, JS build + test, wheel build,
+Today Buckaroo's CI has **22 jobs**: lint, JS build + test, wheel build,
 Python tests across 4 versions with two dependency strategies, 6
 Playwright integration suites, MCP integration, smoke tests, docs build,
-styling screenshots, TestPyPI publish, and Windows. That takes about
-**7 minutes** on Depot.
+styling screenshots, and TestPyPI publish. That takes about **7 minutes**
+on Depot.
 
 Six times more jobs in roughly the same wall-clock time. The fast
 runners made it practical to add all of those integration tests — if

From d5dffcc11de10145360208cc0f3296742a3adb9d Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sun, 22 Mar 2026 18:16:46 -0400
Subject: [PATCH 22/29] docs: update Depot article with accurate before/after
 job counts

Dec 24 (pre-Depot): 3 jobs. Now: 23 jobs (20 added since sponsorship).
Itemized breakdown of what was added: 6 Playwright suites, 8 Python
matrix jobs, MCP integration, smoke tests, screenshots, docs, TestPyPI.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 38 ++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index abc83361..565f477f 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -122,18 +122,32 @@ useful.
 Before and after
 -----------------
 
-Before Depot, Buckaroo's CI had **4 jobs**: lint and Python tests on 3
-versions. That took about 6 minutes on GitHub Actions runners.
-
-Today Buckaroo's CI has **22 jobs**: lint, JS build + test, wheel build,
-Python tests across 4 versions with two dependency strategies, 6
-Playwright integration suites, MCP integration, smoke tests, docs build,
-styling screenshots, and TestPyPI publish. That takes about **7 minutes**
-on Depot.
-
-Six times more jobs in roughly the same wall-clock time. The fast
-runners made it practical to add all of those integration tests — if
-each new test suite added 5 minutes, I never would have added them.
+On December 24, 2025 — the day Depot's CTO responded to my sponsorship
+request — Buckaroo's CI had **3 jobs**: lint, Python tests, and a
+wheel build. That was it.
+
+Since then I've added **20 new jobs**:
+
+- **6 Playwright integration suites** — Storybook, JupyterLab, Marimo,
+  WASM Marimo, Server, and Static Embed. These are the tests that
+  actually catch real bugs — "it renders in Jupyter but is blank in
+  Marimo" is the kind of thing I can't eyeball.
+- **Python tests across 4 versions** with two dependency strategies
+  (min pinned + max latest) — 8 matrix jobs total
+- **MCP integration tests** — verifying the MCP server works against
+  the built wheel
+- **Smoke tests** for each optional extras group
+- **Styling screenshot comparisons** — before/after captures on every PR
+- **Docs build + link checker**
+- **TestPyPI publish** on every PR with an install command in the PR
+  comment
+
+The pipeline now runs **23 jobs** and completes in about **7 minutes**.
+Before Depot, 3 jobs took about 6 minutes on GitHub Actions runners.
+
+The fast runners didn't just make existing tests faster — they made it
+practical to keep adding tests. If each new Playwright suite added 5
+minutes of wall-clock time, I never would have added 6 of them.
 
 
 Testing against dependency versions

From b51ed574fecdb7890602dc6609e4b3e54bdc4804 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sun, 22 Mar 2026 18:27:36 -0400
Subject: [PATCH 23/29] =?UTF-8?q?docs:=20rewrite=20Depot=20value=20prop=20?=
 =?UTF-8?q?=E2=80=94=20consistency=20and=20confidence,=20not=20raw=20speed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same-pipeline benchmarks show Depot isn't measurably faster than GitHub
runners (I/O-bound workload). The real value is consistent provisioning
(no Monday afternoon queue delays) and no minute quotas, which gave
confidence to invest in CI optimization and grow from 3 to 23 jobs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 42 +++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 13 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index 565f477f..e256f023 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -63,19 +63,35 @@ What Depot changed
 -------------------
 
 The CTO responded to my request for open source sponsorship on
-Christmas Eve. Since then:
-
-- **Critical path: ~3.5 minutes.** From push to all-green. 22 jobs,
-  3.5 minutes. That's fast enough that I don't context-switch away.
-- **Commit to first step running: ~30 seconds** on Linux. GitHub adds
-  about 6 seconds of latency. Depot provisions a runner in ~18 seconds.
-  On GitHub's own runners this used to be minutes.
-- **Cost: ~$0.18 per run** on 2-CPU runners. I tested 4-CPU and 8-CPU
-  runners too — no measurable speedup. The workload is I/O-bound
-  (package installs, Playwright browser launches), not CPU-bound.
-  Bigger runners just cost more for the same wall-clock time.
-- **~$9–18/month** at my typical push cadence. The Developer plan
-  ($20/month, 2,000 included minutes) covers about 52 full CI runs.
+Christmas Eve.
+
+I'll be honest: Depot's runners aren't measurably faster than GitHub's
+for this workload. I ran the same 23-job pipeline on both and the
+per-job times are within noise. The work is I/O-bound — package
+installs, Playwright browser launches, artifact transfers — not
+CPU-bound.
+
+What Depot actually gave me was two things:
+
+- **Consistent provisioning.** Depot provisions a runner in ~18 seconds,
+  every time. GitHub Actions runners can be just as fast on a Saturday
+  night, but on a Monday afternoon they queue for minutes. When you're
+  pushing 10 times a day and iterating with an LLM, unpredictable queue
+  times kill your flow. Depot removed that variance.
+
+- **No minute quotas to worry about.** With Depot's open source
+  sponsorship, I stopped thinking about whether adding another test
+  suite was "worth the minutes." That sounds small, but it changed my
+  behavior completely. I went from 3 CI jobs to 23 in three months.
+
+The second point is the one I didn't expect. Because I knew the
+infrastructure was solid — reliable runners, no quota pressure — I
+actually invested in making CI better. I removed pnpm from Python test
+jobs that didn't need it. I parallelized the pipeline into two waves.
+I tuned the setup steps. Those optimizations dropped the critical path
+from 5 minutes to 3.5 minutes, but I only made them because I knew
+Depot was doing its part. When your CI infrastructure feels like a
+liability, you don't invest in it — you avoid it.
 
 The numbers
 ------------

From eb2642afa1dfdf001876d8dc82d97ed8cc4efe6a Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Sun, 22 Mar 2026 18:37:57 -0400
Subject: [PATCH 24/29] =?UTF-8?q?docs:=20fix=20timing=20=E2=80=94=203.5=20?=
 =?UTF-8?q?min=20critical=20path,=20not=207=20min=20(excludes=20Windows)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index e256f023..8849aeea 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -147,7 +147,7 @@ Since then I've added **20 new jobs**:
 - **6 Playwright integration suites** — Storybook, JupyterLab, Marimo,
   WASM Marimo, Server, and Static Embed. These are the tests that
   actually catch real bugs — "it renders in Jupyter but is blank in
-  Marimo" is the kind of thing I can't eyeball.
+  Marimo" is the kind of thing I don't want to eyeball on every PR.
 - **Python tests across 4 versions** with two dependency strategies
   (min pinned + max latest) — 8 matrix jobs total
 - **MCP integration tests** — verifying the MCP server works against
@@ -158,8 +158,10 @@ Since then I've added **20 new jobs**:
 - **TestPyPI publish** on every PR with an install command in the PR
   comment
 
-The pipeline now runs **23 jobs** and completes in about **7 minutes**.
-Before Depot, 3 jobs took about 6 minutes on GitHub Actions runners.
+The pipeline now runs **23 jobs** and the critical path completes in
+about **3.5 minutes** (the Windows job runs longer but is non-blocking
+— ``continue-on-error: true``). Before Depot, 3 jobs took about 5
+minutes on GitHub Actions runners.
 
 The fast runners didn't just make existing tests faster — they made it
 practical to keep adding tests. If each new Playwright suite added 5

From b33b460d23c25fbb9b7516ca16475153367640af Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Mon, 23 Mar 2026 08:04:43 -0400
Subject: [PATCH 25/29] docs: add performance and testing articles to content
 plan
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- "How I made Buckaroo fast" — do less, not optimize more
- "Testing Buckaroo" — unit, integration, Playwright, screenshots,
  smoke, MCP, dual deps, DDD as test suite
- Mark Depot article as draft with pending CTO input

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/content-plan.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/content-plan.md b/docs/content-plan.md
index 17bf5c54..5d52a702 100644
--- a/docs/content-plan.md
+++ b/docs/content-plan.md
@@ -12,6 +12,9 @@ Published at `docs/source/articles/types-to-display.rst`. Column renaming (a,b,c
 ### So you want to write a DataFrame viewer
 Published at `docs/source/articles/so-you-want-to-write-a-dataframe-viewer.rst`. Comparison of open source DataFrame viewers (Buckaroo, Perspective, iTables, Great Tables, DTale, Mito, Marimo, ipydatagrid, quak). Research in `~/personal/buckaroo-writing/research/`.
 
+### Why Buckaroo uses Depot for CI
+Draft at `docs/source/articles/why-depot.rst`. Depot sponsorship story. Honest benchmarking: Depot isn't measurably faster than GitHub runners (I/O-bound workload), but consistent provisioning + no minute quotas gave confidence to grow from 3 to 23 CI jobs. Pending: email to Depot CTO for input before publishing.
+
 ## Planned
 
 ### Static embedding improvements
@@ -33,4 +36,27 @@ Based on https://github.com/buckaroo-data/buckaroo/pull/583
 ### Embedding buckaroo for bigger data
 Parquet range queries on S3/R2 buckets. Sponsored by Cloudflare?
 
+### How I made Buckaroo fast
+The philosophy: do the right things fast, but mostly just do less. Not a performance optimization article — it's about architecture decisions that avoid work entirely.
+- Column renaming to a,b,c means shorter keys everywhere, no escaping
+- Parquet instead of JSON: moved from Python JSON serialization (the slowest part of the original render) to binary Parquet. Faster encoding, smaller payloads, type preservation for free
+- Sampling: don't process the whole DataFrame. Sample first, compute stats on the sample, display the sample. The user sees 500 rows, not 500,000
+- Summary stats: compute once, cache. Don't recompute on every view switch
+- hyparquet decodes in the browser — no round-trip to the server for data
+- LRU cache on decoded Parquet so switching between main/stats views doesn't re-decode
+- AG-Grid does the hard rendering work (virtual scrolling, column virtualization) — don't fight it, feed it clean data
+- The lesson: most "performance work" was removing unnecessary work, not optimizing hot paths
+
+### Testing Buckaroo: unit tests, integration tests, and everything in between
+How a solo developer tests a project that spans Python + TypeScript across 8 deployment environments.
+- **Python unit tests** (pytest): serialization, stats computation, type coercion, column renaming. Fast, reliable, the foundation. ~60s for the full suite
+- **JS unit tests** (vitest): component logic, displayer/formatter functions, parquet decoding. Run in Node, no browser needed
+- **Playwright integration tests** (6 suites): Storybook (component rendering), JupyterLab (full widget lifecycle), Marimo, WASM Marimo, Server (MCP/standalone), Static Embed. These catch "it works in Jupyter but is blank in Marimo" — the bugs you can't find any other way
+- **Styling screenshot comparisons**: before/after captures on every PR using Storybook + Playwright. Catches visual regressions (column width changes, color map shifts) that no unit test can detect
+- **Smoke tests**: install the wheel with each optional extras group (`[mcp]`, `[notebook]`, etc.) and verify imports work. Catches dependency conflicts
+- **MCP integration tests**: install the wheel, start the MCP server, make a `tools/call` request, verify the response includes static assets
+- **Dual dependency strategy**: run all Python tests twice — once with minimum pinned versions, once with `--resolution=highest`. Catches pandas/polars/pyarrow compatibility issues before users do
+- **The DDD as a test suite**: the Dastardly DataFrame Dataset isn't just documentation — each weird DataFrame exercises edge cases through the full serialization → display pipeline
+- What I don't test: VSCode, Google Colab (no headless automation), visual pixel-perfect matching (too brittle)
+- The lesson: integration tests are worth the CI investment. Most real bugs are at boundaries (Python→Parquet→JS→AG-Grid), not inside any one layer
 

From 301a24e6852ab2c97dece434204dd47bf95356c5 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Mon, 23 Mar 2026 11:24:03 -0400
Subject: [PATCH 26/29] docs: update Depot article with benchmark data, add CI
 timing scripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Article now includes a 4-scenario comparison table with real data:
- GitHub Sunday night (3m15s), Monday sequential (5m19s), Monday
  parallel (5m58s), Depot Monday parallel (4m18s)
- Key finding: per-job Depot is slightly slower, but consistent
  provisioning (19s stagger vs 114s) wins on critical path
- GitHub ranges 3m–6m+, Depot is 4m–4m30s regardless

New scripts:
- ci_critical_path.sh: critical path for a single run
- ci_list_runs.sh: list runs for a PR or branch
- ci_all_timings.sh: JSON output of all timing data per run
- ci_timing_table.py: formatted comparison table from JSON

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst |  71 +++++++++----
 scripts/ci_all_timings.sh          |  97 ++++++++++++++++++
 scripts/ci_critical_path.sh        |  41 ++++++++
 scripts/ci_list_runs.sh            |  23 +++++
 scripts/ci_timing_table.py         | 155 +++++++++++++++++++++++++++++
 5 files changed, 369 insertions(+), 18 deletions(-)
 create mode 100755 scripts/ci_all_timings.sh
 create mode 100755 scripts/ci_critical_path.sh
 create mode 100755 scripts/ci_list_runs.sh
 create mode 100755 scripts/ci_timing_table.py

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index 8849aeea..04da6e3c 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -65,17 +65,54 @@ What Depot changed
 The CTO responded to my request for open source sponsorship on
 Christmas Eve.
 
-I'll be honest: Depot's runners aren't measurably faster than GitHub's
-for this workload. I ran the same 23-job pipeline on both and the
-per-job times are within noise. The work is I/O-bound — package
-installs, Playwright browser launches, artifact transfers — not
-CPU-bound.
+I benchmarked the same 23-job pipeline on both Depot and GitHub
+Actions runners — 3 parallel runs of each, on a Monday morning. Here's
+what I found:
 
-What Depot actually gave me was two things:
-
-- **Consistent provisioning.** Depot provisions a runner in ~18 seconds,
-  every time. GitHub Actions runners can be just as fast on a Saturday
-  night, but on a Monday afternoon they queue for minutes. When you're
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 20 20
+
+   * - Scenario
+     - Critical Path (mean)
+     - Wave 1 Stagger
+     - Variance
+   * - GitHub, Sunday night, 1 PR
+     - 3m15s
+     - 0s
+     - —
+   * - GitHub, Monday AM, sequential
+     - 5m19s
+     - 90s
+     - 4m25s – 6m28s
+   * - GitHub, Monday AM, 3 parallel
+     - 5m58s
+     - 114s
+     - 5m06s – 6m38s
+   * - Depot, Monday AM, 3 parallel
+     - 4m18s
+     - 19s
+     - 4m02s – 4m31s
+
+"Wave 1 stagger" is the time between the first and last Wave 1 job
+starting. On GitHub, Wave 1 jobs trickle in over 1–3 minutes as runners
+become available. On Depot, they all start within 20 seconds.
+
+The per-job times are actually slightly slower on Depot — every
+individual job takes a few seconds longer. But it doesn't matter
+because Depot starts all jobs simultaneously. GitHub's queueing delay
+dwarfs any per-job difference.
+
+The critical insight: **GitHub's performance ranges from 3m15s to
+6m38s** depending on time of day and how many other repos are competing
+for runners. **Depot is 4m02s–4m31s regardless.** That consistency is
+worth more than raw speed.
+
+What Depot actually gave me was three things:
+
+- **Consistent provisioning.** Depot provisions a runner in ~20 seconds,
+  every time. GitHub Actions runners can be just as fast on a Sunday
+  night, but on a Monday morning they queue for minutes. When you're
   pushing 10 times a day and iterating with an LLM, unpredictable queue
   times kill your flow. Depot removed that variance.
 
@@ -84,14 +121,12 @@ What Depot actually gave me was two things:
   suite was "worth the minutes." That sounds small, but it changed my
   behavior completely. I went from 3 CI jobs to 23 in three months.
 
-The second point is the one I didn't expect. Because I knew the
-infrastructure was solid — reliable runners, no quota pressure — I
-actually invested in making CI better. I removed pnpm from Python test
-jobs that didn't need it. I parallelized the pipeline into two waves.
-I tuned the setup steps. Those optimizations dropped the critical path
-from 5 minutes to 3.5 minutes, but I only made them because I knew
-Depot was doing its part. When your CI infrastructure feels like a
-liability, you don't invest in it — you avoid it.
+- **Confidence to invest in CI.** Because I knew the infrastructure was
+  solid — reliable runners, no quota pressure — I actually spent time
+  making CI better. I removed pnpm from Python test jobs that didn't
+  need it. I parallelized the pipeline into two waves. I tuned the
+  setup steps. When your CI infrastructure feels like a liability, you
+  don't invest in it — you avoid it.
 
 The numbers
 ------------
diff --git a/scripts/ci_all_timings.sh b/scripts/ci_all_timings.sh
new file mode 100755
index 00000000..2fb0d5c6
--- /dev/null
+++ b/scripts/ci_all_timings.sh
@@ -0,0 +1,97 @@
+#!/bin/bash
+# Usage: bash scripts/ci_all_timings.sh <run-id> [<run-id> ...]
+#
+# Outputs one JSON line per run with critical path, wave1 stagger, per-job
+# durations, and cache read/write stats. Pipe to ci_timing_table.py for
+# formatted output.
+#
+# Example:
+#   bash scripts/ci_all_timings.sh 12345 67890 | python3 scripts/ci_timing_table.py
+
+set -euo pipefail
+
+for RUN_ID in "$@"; do
+python3 -c "
+import json, subprocess, sys
+from datetime import datetime
+
+def parse(t):
+    return datetime.fromisoformat(t.replace('Z','+00:00'))
+
+def dur(s, e):
+    return int((parse(e) - parse(s)).total_seconds())
+
+run_id = '$RUN_ID'
+result = subprocess.run(
+    ['gh', 'api', f'repos/buckaroo-data/buckaroo/actions/runs/{run_id}/jobs', '--paginate'],
+    capture_output=True, text=True)
+data = json.loads(result.stdout)
+
+# Run metadata
+run_meta = subprocess.run(
+    ['gh', 'api', f'repos/buckaroo-data/buckaroo/actions/runs/{run_id}'],
+    capture_output=True, text=True)
+meta = json.loads(run_meta.stdout)
+branch = meta.get('head_branch', '')
+created = meta.get('created_at', '')
+
+# Per-job timings (excl Windows)
+jobs = {}
+for j in data['jobs']:
+    if not j['completed_at'] or 'Windows' in j['name']:
+        continue
+    jobs[j['name']] = dur(j['started_at'], j['completed_at'])
+
+# Critical path
+completed = [(j['name'], j['started_at'], j['completed_at'])
+             for j in data['jobs'] if j['completed_at'] and 'Windows' not in j['name']]
+if not completed:
+    sys.exit(0)
+starts = [parse(s) for _, s, _ in completed]
+ends = [parse(e) for _, _, e in completed]
+critical_path = int((max(ends) - min(starts)).total_seconds())
+
+# Wave 1 stagger
+wave1_names = [n for n, _, _ in completed if 'Playwright' not in n and 'MCP' not in n
+               and 'Smoke' not in n and 'Publish' not in n and 'Static Embed' not in n]
+wave1_starts = sorted([parse(s) for n, s, _ in completed if n in wave1_names])
+wave1_stagger = int((wave1_starts[-1] - wave1_starts[0]).total_seconds()) if len(wave1_starts) >= 2 else 0
+
+# Cache stats from steps
+reads = []
+writes = []
+for j in data['jobs']:
+    if 'Windows' in j['name']:
+        continue
+    for step in j['steps']:
+        if not step['completed_at']:
+            continue
+        d = dur(step['started_at'], step['completed_at'])
+        name = step['name']
+        is_read = (any(x in name for x in ['Install uv', 'Install the project', 'Install pnpm', 'Cache Playwright'])
+                   and not name.startswith('Post'))
+        is_write = (name.startswith('Post ')
+                    and any(x in name for x in ['uv', 'cache', 'Cache', 'Playwright'])
+                    and 'checkout' not in name and 'pnpm' not in name)
+        if is_read:
+            reads.append(d)
+        elif is_write:
+            writes.append(d)
+
+output = {
+    'run_id': run_id,
+    'branch': branch,
+    'created': created,
+    'critical_path': critical_path,
+    'wave1_stagger': wave1_stagger,
+    'jobs': jobs,
+    'cache_reads': reads,
+    'cache_writes': writes,
+    'cache_read_total': sum(reads),
+    'cache_write_total': sum(writes),
+    'cache_read_mean': round(sum(reads)/len(reads), 1) if reads else 0,
+    'cache_write_mean': round(sum(writes)/len(writes), 1) if writes else 0,
+}
+print(json.dumps(output))
+"
+done
diff --git a/scripts/ci_critical_path.sh b/scripts/ci_critical_path.sh
new file mode 100755
index 00000000..99822f65
--- /dev/null
+++ b/scripts/ci_critical_path.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+# Usage: bash scripts/ci_critical_path.sh <run-id>
+#
+# Prints the critical path time (excluding Windows) for a GitHub Actions run.
+
+set -euo pipefail
+
+RUN_ID=$1
+
+python3 -c "
+import json, subprocess, sys
+from datetime import datetime
+
+def parse(t):
+    return datetime.fromisoformat(t.replace('Z','+00:00'))
+
+run_id = '$RUN_ID'
+result = subprocess.run(
+    ['gh', 'api', f'repos/buckaroo-data/buckaroo/actions/runs/{run_id}/jobs', '--paginate'],
+    capture_output=True, text=True)
+data = json.loads(result.stdout)
+jobs = [(j['name'], j['started_at'], j['completed_at'], j['conclusion'])
+        for j in data['jobs'] if j['completed_at'] and 'Windows' not in j['name']]
+
+if not jobs:
+    print('No completed non-Windows jobs found.')
+    sys.exit(1)
+
+starts = [parse(s) for _, s, e, _ in jobs]
+ends = [parse(e) for _, s, e, _ in jobs]
+cp = int((max(ends) - min(starts)).total_seconds())
+
+first_start = min(starts)
+last_end = max(ends)
+last_job = [n for n, s, e, _ in jobs if parse(e) == last_end][0]
+
+print(f'Run {run_id}: {cp//60}m{cp%60:02d}s (critical path excl Windows)')
+print(f'  First job started: {min(starts).isoformat()}')
+print(f'  Last job finished: {max(ends).isoformat()} ({last_job})')
+print(f'  Jobs: {len(jobs)} completed (excl Windows)')
+"
diff --git a/scripts/ci_list_runs.sh b/scripts/ci_list_runs.sh
new file mode 100755
index 00000000..d9414567
--- /dev/null
+++ b/scripts/ci_list_runs.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+# Usage: bash scripts/ci_list_runs.sh <pr-number-or-branch>
+#
+# Lists all Checks workflow runs for a PR number or branch name.
+
+set -euo pipefail
+
+INPUT=$1
+
+# If it's a number, treat as PR and get the branch
+if [[ "$INPUT" =~ ^[0-9]+$ ]]; then
+    BRANCH=$(gh pr view "$INPUT" --json headRefName -q '.headRefName')
+    echo "PR #$INPUT → branch: $BRANCH"
+else
+    BRANCH="$INPUT"
+    echo "Branch: $BRANCH"
+fi
+
+echo ""
+gh run list --branch "$BRANCH" --workflow checks.yml --limit 20 \
+    --json databaseId,status,conclusion,createdAt,updatedAt,event \
+    -q '.[] | "\(.databaseId)\t\(.status)\t\(.conclusion // "-")\t\(.createdAt)\t\(.updatedAt)\t\(.event)"' | \
+    column -t -s $'\t'
diff --git a/scripts/ci_timing_table.py b/scripts/ci_timing_table.py
new file mode 100755
index 00000000..975b7042
--- /dev/null
+++ b/scripts/ci_timing_table.py
@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Read JSON lines from ci_all_timings.sh and print a comparison table.
+
+Usage:
+    bash scripts/ci_all_timings.sh <id1> <id2> ... | python3 scripts/ci_timing_table.py
+
+    # Or with labels:
+    bash scripts/ci_all_timings.sh <id1> <id2> <id3> | python3 scripts/ci_timing_table.py --labels "GH warm 1" "GH warm 2" "GH warm 3"
+
+    # Group by prefix for summary rows:
+    bash scripts/ci_all_timings.sh <ids...> | python3 scripts/ci_timing_table.py --groups "GitHub warm:0,1,2" "Depot warm:3,4,5"
+"""
+import json
+import sys
+import argparse
+
+
+def fmt(secs):
+    if secs is None:
+        return "?"
+    return f"{secs // 60}m{secs % 60:02d}s"
+
+
+def mean(vals):
+    vals = [v for v in vals if v is not None]
+    return int(sum(vals) / len(vals)) if vals else 0
+
+
+def median(vals):
+    vals = sorted(v for v in vals if v is not None)
+    if not vals:
+        return 0
+    n = len(vals)
+    if n % 2:
+        return vals[n // 2]
+    return (vals[n // 2 - 1] + vals[n // 2]) // 2
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--labels", nargs="*", help="Labels for each run")
+    parser.add_argument(
+        "--groups",
+        nargs="*",
+        help='Group runs for summary: "Label:0,1,2" (0-indexed)',
+    )
+    args = parser.parse_args()
+
+    runs = []
+    for line in sys.stdin:
+        line = line.strip()
+        if line:
+            runs.append(json.loads(line))
+
+    if not runs:
+        print("No data on stdin. Pipe output from ci_all_timings.sh.")
+        sys.exit(1)
+
+    labels = args.labels or [r.get("branch", r["run_id"]) for r in runs]
+
+    # Individual runs
+    n = len(runs)
+    col_w = max(12, max(len(l) for l in labels) + 2)
+
+    header = f"{'':>30}" + "".join(f"{l:>{col_w}}" for l in labels)
+    print(header)
+    print("=" * len(header))
+
+    print("Critical path (excl Windows):")
+    vals = [r["critical_path"] for r in runs]
+    print(f"  {'':>28}" + "".join(f"{fmt(v):>{col_w}}" for v in vals))
+
+    print("Wave 1 stagger:")
+    vals = [r["wave1_stagger"] for r in runs]
+    print(
+        f"  {'':>28}" + "".join(f"{str(v) + 's':>{col_w}}" for v in vals)
+    )
+
+    print("Cache read total:")
+    vals = [r["cache_read_total"] for r in runs]
+    print(
+        f"  {'':>28}" + "".join(f"{str(v) + 's':>{col_w}}" for v in vals)
+    )
+
+    print("Cache read mean/step:")
+    vals = [r["cache_read_mean"] for r in runs]
+    print(
+        f"  {'':>28}"
+        + "".join(f"{str(v) + 's':>{col_w}}" for v in vals)
+    )
+
+    print("Cache write total:")
+    vals = [r["cache_write_total"] for r in runs]
+    print(
+        f"  {'':>28}" + "".join(f"{str(v) + 's':>{col_w}}" for v in vals)
+    )
+
+    print("Cache write mean/step:")
+    vals = [r["cache_write_mean"] for r in runs]
+    print(
+        f"  {'':>28}"
+        + "".join(f"{str(v) + 's':>{col_w}}" for v in vals)
+    )
+
+    # Groups summary
+    if args.groups:
+        print()
+        print("=" * 72)
+        print("SUMMARY")
+        print("=" * 72)
+        print(
+            f"{'Group':>30} {'Mean CP':>10} {'Med CP':>10} {'Stagger':>10} {'CR mean':>10} {'CW mean':>10}"
+        )
+        print("-" * 82)
+        for group_spec in args.groups:
+            label, indices_str = group_spec.split(":")
+            indices = [int(i) for i in indices_str.split(",")]
+            group_runs = [runs[i] for i in indices if i < len(runs)]
+
+            cp_mean = mean([r["critical_path"] for r in group_runs])
+            cp_med = median([r["critical_path"] for r in group_runs])
+            stg_mean = mean([r["wave1_stagger"] for r in group_runs])
+            cr_mean = round(
+                mean([r["cache_read_mean"] for r in group_runs]), 1
+            )
+            cw_mean = round(
+                mean([r["cache_write_mean"] for r in group_runs]), 1
+            )
+
+            print(
+                f"{label:>30} {fmt(cp_mean):>10} {fmt(cp_med):>10} {str(stg_mean) + 's':>10} {str(cr_mean) + 's':>10} {str(cw_mean) + 's':>10}"
+            )
+
+    # Per-job breakdown if few runs
+    if len(runs) <= 6:
+        print()
+        print("Per-job durations:")
+        all_jobs = sorted(
+            set(j for r in runs for j in r["jobs"].keys())
+        )
+        print(f"{'Job':>35}" + "".join(f"{l:>{col_w}}" for l in labels))
+        print("-" * (35 + col_w * n))
+        for job in all_jobs:
+            vals = [r["jobs"].get(job) for r in runs]
+            print(
+                f"{job:>35}"
+                + "".join(
+                    f"{(str(v) + 's') if v is not None else '-':>{col_w}}"
+                    for v in vals
+                )
+            )
+
+
+if __name__ == "__main__":
+    main()

From 2391e1c3bd3b867cd4a530a214208dbd9b211672 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Mon, 23 Mar 2026 13:58:16 -0400
Subject: [PATCH 27/29] docs: rewrite Depot article with full benchmark data
 (21 runs)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complete rewrite with controlled benchmark results:
- 21 runs across 6 scenarios (cold/warm, parallel/sequential, Sunday/Monday)
- GitHub Monday: 7m46s ±143s. Depot Monday: 4m03s ±20s.
- Key finding: per-job Depot is slightly slower, but consistent
  provisioning (all jobs start in 20s vs 1-7 min stagger) wins
- Includes reproduction steps with scripts
- Restructured: benchmark → results → analysis → before/after → advice

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 360 ++++++++++++++++-------------
 1 file changed, 193 insertions(+), 167 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index 04da6e3c..db041052 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -1,188 +1,221 @@
 Why Buckaroo Uses Depot for CI
 ===============================
 
-`Depot <https://depot.dev/>`_ sponsors Buckaroo's CI infrastructure and
-I really appreciate that. This article explains why I switched and what
-changed.
+`Depot <https://depot.dev/>`_ sponsors Buckaroo's CI infrastructure. I
+ran a controlled benchmark — 21 runs across different scenarios — to
+understand exactly what that sponsorship buys. The results surprised me.
 
 The problem with GitHub Actions
 --------------------------------
 
-GitHub Actions is slow and the cache is slower. I have known this for a
-long time. I believe in CI, but it is hard to set up, and then once you
-get it running it's way slower than it needs to be. It's like being
-saddled with a teammate who won't pull their weight and has no interest
-in changing — it demotivates you.
-
-When your CI takes 10+ minutes, you stop pushing small changes. You
-batch things up. You skip the test run "just this once." You merge
-without waiting for green because you've already context-switched to
-something else. Slow CI makes you write worse code.
-
-What Buckaroo's CI actually does
----------------------------------
-
-Buckaroo is a complex project with a significant Python and TypeScript
-codebase. The full package is deployed to 8 environments:
-
-- Jupyter (notebook + lab)
-- Marimo
-- JupyterLite (WASM/Pyodide)
-- Marimo WASM
-- VSCode (can't integration-test this one)
-- Google Colab (same)
-- Static self-contained embeds
-- Buckaroo server (used for the MCP server)
-
-The CI pipeline runs 22 jobs across 2 waves: linting, JS build + test,
-a Python wheel build, then 6 Playwright integration test suites
-(Storybook, JupyterLab, Marimo, WASM Marimo, Server, Static Embed),
-Python tests across 4 versions (3.11–3.14), an MCP integration test,
-styling screenshot comparisons, and a docs build.
-
-Integration testing in particular is really important — I can't manually
-test each environment for each code change. When a change breaks Marimo
-but not Jupyter, I need to know before it ships.
+GitHub Actions is slow, but not in the way I expected. The jobs
+themselves are fine — the runners are fast enough. The problem is
+queueing. When you have a 23-job pipeline and GitHub is busy, your jobs
+don't start simultaneously. They trickle in one at a time over minutes.
+
+When your CI takes 10 minutes because of queueing, you stop pushing
+small changes. You batch things up. You skip the test run "just this
+once." You merge without waiting for green because you've already
+context-switched to something else. Slow CI makes you write worse code.
+
+
+What Buckaroo's CI does
+------------------------
+
+Buckaroo is a DataFrame viewer with a Python backend and TypeScript/React
+frontend. It deploys to 8 environments — Jupyter, Marimo, JupyterLite
+(WASM), Marimo WASM, VSCode, Google Colab, static embeds, and a
+standalone server (used for MCP). I can't manually test each environment
+on every code change.
+
+The CI pipeline runs **23 jobs** across 2 waves:
+
+- **Wave 1** (no dependencies): lint, JS build + test, wheel build,
+  Python tests across 4 versions with two dependency strategies (8 matrix
+  jobs), styling screenshots, docs build
+- **Wave 2** (needs the built wheel): 6 Playwright integration suites
+  (Storybook, JupyterLab, Marimo, WASM Marimo, Server, Static Embed),
+  MCP integration, smoke tests, TestPyPI publish
+
+Three months ago this pipeline had 3 jobs.
+
 
 LLMs changed the equation
 ---------------------------
 
-LLM coding has changed the way I approach devops. First, it makes it
-easier to accomplish devops changes — this is great. Claude in
-particular has made it possible to get my Playwright integration tests
-to a place where I really trust them to run reliably. That has been
-awesome.
+LLM coding changed the way I approach devops. Claude made it possible to
+get my Playwright integration tests to a place where I trust them to run
+reliably. But LLMs also make testing more important than ever. When
+Claude makes a change across 5 files, I need to know in minutes — not 10
+minutes — whether it broke something. The tighter the feedback loop, the
+more ambitious the changes I can attempt.
 
-At the same time, LLMs make testing more important than ever. I cannot
-move fast with LLMs without a solid test suite that runs fast. When
-Claude makes a change across 5 files, I need to know in minutes — not
-10 minutes — whether it broke something. The tighter the feedback loop,
-the more ambitious the changes I can attempt.
 
-What Depot changed
--------------------
+The benchmark
+--------------
 
-The CTO responded to my request for open source sponsorship on
-Christmas Eve.
+I ran the same 23-job pipeline on both Depot and GitHub Actions runners
+across 21 runs over a Sunday night and Monday morning, covering cold
+cache, warm cache, parallel, and sequential scenarios. All runs used
+2-CPU Linux runners.
 
-I benchmarked the same 23-job pipeline on both Depot and GitHub
-Actions runners — 3 parallel runs of each, on a Monday morning. Here's
-what I found:
+Reproduction scripts are in the `buckaroo repo
+<https://github.com/buckaroo-data/buckaroo/tree/main/scripts>`_:
+
+.. code-block:: bash
+
+    # Critical path for a single run
+    bash scripts/ci_critical_path.sh <run-id>
+
+    # List runs for a PR or branch
+    bash scripts/ci_list_runs.sh <pr-number-or-branch>
+
+    # Full timing data as JSON (pipe to ci_timing_table.py)
+    bash scripts/ci_all_timings.sh <run-id> [<run-id> ...] \
+      | python3 scripts/ci_timing_table.py --labels "Run 1" "Run 2" ...
+
+    # Launch paired cold-cache benchmark runs
+    bash scripts/cold_cache_benchmark.sh
+
+
+The results
+------------
+
+Critical path time (excluding the non-blocking Windows job):
 
 .. list-table::
    :header-rows: 1
-   :widths: 35 20 20 20
+   :widths: 35 12 12 12 12 5
 
    * - Scenario
-     - Critical Path (mean)
-     - Wave 1 Stagger
-     - Variance
+     - Mean
+     - Std Dev
+     - Min
+     - Max
+     - n
    * - GitHub, Sunday night, 1 PR
-     - 3m15s
-     - 0s
+     - 3m09s
      - —
-   * - GitHub, Monday AM, sequential
+     - 3m09s
+     - 3m09s
+     - 1
+   * - GitHub, Monday, cold, 3 parallel
+     - 9m15s
+     - ±30s
+     - 8m49s
+     - 9m49s
+     - 3
+   * - GitHub, Monday, warm, 3 parallel
+     - 8m09s
+     - ±158s
+     - 5m06s
+     - 11m11s
+     - 6
+   * - GitHub, Monday, warm, sequential
      - 5m19s
-     - 90s
-     - 4m25s – 6m28s
-   * - GitHub, Monday AM, 3 parallel
-     - 5m58s
-     - 114s
-     - 5m06s – 6m38s
-   * - Depot, Monday AM, 3 parallel
-     - 4m18s
-     - 19s
-     - 4m02s – 4m31s
+     - ±62s
+     - 4m25s
+     - 6m28s
+     - 3
+   * - Depot, Monday, cold, 3 parallel
+     - 3m53s
+     - ±2s
+     - 3m50s
+     - 3m55s
+     - 3
+   * - Depot, Monday, warm, 3 parallel
+     - 4m08s
+     - ±23s
+     - 3m38s
+     - 4m32s
+     - 6
+
+Aggregated across all Monday runs:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 12 12 12 12 5
+
+   * - Runner
+     - Mean
+     - Std Dev
+     - Min
+     - Max
+     - n
+   * - GitHub Actions
+     - 7m46s
+     - ±143s
+     - 4m25s
+     - 11m11s
+     - 12
+   * - Depot
+     - 4m03s
+     - ±20s
+     - 3m38s
+     - 4m32s
+     - 9
+
+**Depot's standard deviation is ±20 seconds. GitHub's is ±143 seconds.**
+
+
+What's actually happening
+--------------------------
+
+The per-job times are slightly *slower* on Depot — every individual job
+takes a few seconds longer. But it doesn't matter because Depot starts
+all jobs simultaneously.
 
 "Wave 1 stagger" is the time between the first and last Wave 1 job
-starting. On GitHub, Wave 1 jobs trickle in over 1–3 minutes as runners
-become available. On Depot, they all start within 20 seconds.
-
-The per-job times are actually slightly slower on Depot — every
-individual job takes a few seconds longer. But it doesn't matter
-because Depot starts all jobs simultaneously. GitHub's queueing delay
-dwarfs any per-job difference.
-
-The critical insight: **GitHub's performance ranges from 3m15s to
-6m38s** depending on time of day and how many other repos are competing
-for runners. **Depot is 4m02s–4m31s regardless.** That consistency is
-worth more than raw speed.
-
-What Depot actually gave me was three things:
-
-- **Consistent provisioning.** Depot provisions a runner in ~20 seconds,
-  every time. GitHub Actions runners can be just as fast on a Sunday
-  night, but on a Monday morning they queue for minutes. When you're
-  pushing 10 times a day and iterating with an LLM, unpredictable queue
-  times kill your flow. Depot removed that variance.
-
-- **No minute quotas to worry about.** With Depot's open source
-  sponsorship, I stopped thinking about whether adding another test
-  suite was "worth the minutes." That sounds small, but it changed my
-  behavior completely. I went from 3 CI jobs to 23 in three months.
-
-- **Confidence to invest in CI.** Because I knew the infrastructure was
-  solid — reliable runners, no quota pressure — I actually spent time
-  making CI better. I removed pnpm from Python test jobs that didn't
-  need it. I parallelized the pipeline into two waves. I tuned the
-  setup steps. When your CI infrastructure feels like a liability, you
-  don't invest in it — you avoid it.
-
-The numbers
-------------
+starting — it measures how long the runner takes to provision all the
+parallel jobs:
 
-Here's what the pipeline looks like on Depot 2-CPU runners:
+- **Depot**: 14–35 seconds. All jobs start within half a minute.
+- **GitHub, Monday morning**: 90–447 seconds. Jobs trickle in over
+  1.5–7 minutes as runners become available.
 
-.. list-table::
-   :header-rows: 1
-   :widths: 40 15 15
-
-   * - Job
-     - Duration
-     - % Useful Work
-   * - Python / Test (avg across versions)
-     - 1m 41s
-     - 84%
-   * - JupyterLab Playwright
-     - 2m 03s
-     - 77%
-   * - Storybook Playwright
-     - 1m 53s
-     - 81%
-   * - Server Playwright
-     - 2m 05s
-     - 74%
-   * - Marimo Playwright
-     - 1m 30s
-     - 68%
-   * - WASM Marimo Playwright
-     - 1m 40s
-     - 70%
-   * - Build JS + Python Wheel
-     - 0m 59s
-     - 44%
-   * - JS / Build + Test
-     - 0m 53s
-     - —
+On a Sunday night with one PR, GitHub's stagger was 1 second — identical
+to Depot. The difference only shows up under load.
 
-The "% Useful Work" column is actual test/build time vs. setup overhead
-(checkout, install dependencies, provision). Most jobs are 70–84%
-useful.
+Cache performance is close. Depot reads caches ~30% faster (2.8s vs 4.1s
+per step), but GitHub writes caches ~3x faster (0.6s vs 2.2s per step).
+Cache writes happen post-job and don't affect the critical path. Neither
+cache difference materially changes the overall timing.
+
+
+What Depot actually gave me
+-----------------------------
+
+Three things, in order of importance:
+
+1. **Consistent provisioning.** Depot provisions all runners within 20
+   seconds, every time. GitHub ranges from instant to 7 minutes depending
+   on load. When you're pushing 10 times a day and iterating with an LLM,
+   unpredictable queue times kill your flow.
+
+2. **No minute quotas.** With Depot's open source sponsorship, I stopped
+   thinking about whether adding another test suite was "worth the
+   minutes." I went from 3 CI jobs to 23 in three months.
+
+3. **Confidence to invest in CI.** Because I knew the infrastructure was
+   solid, I actually spent time making CI better — removing unnecessary
+   setup steps, parallelizing into two waves, tuning the pipeline. When
+   your CI infrastructure feels like a liability, you don't invest in
+   it — you avoid it.
 
 
 Before and after
 -----------------
 
 On December 24, 2025 — the day Depot's CTO responded to my sponsorship
-request — Buckaroo's CI had **3 jobs**: lint, Python tests, and a
-wheel build. That was it.
+request — Buckaroo's CI had **3 jobs**: lint, Python tests, and a wheel
+build.
 
 Since then I've added **20 new jobs**:
 
 - **6 Playwright integration suites** — Storybook, JupyterLab, Marimo,
-  WASM Marimo, Server, and Static Embed. These are the tests that
-  actually catch real bugs — "it renders in Jupyter but is blank in
-  Marimo" is the kind of thing I don't want to eyeball on every PR.
+  WASM Marimo, Server, and Static Embed. These catch real bugs — "it
+  renders in Jupyter but is blank in Marimo" is the kind of thing I
+  don't want to eyeball on every PR.
 - **Python tests across 4 versions** with two dependency strategies
   (min pinned + max latest) — 8 matrix jobs total
 - **MCP integration tests** — verifying the MCP server works against
@@ -193,31 +226,23 @@ Since then I've added **20 new jobs**:
 - **TestPyPI publish** on every PR with an install command in the PR
   comment
 
-The pipeline now runs **23 jobs** and the critical path completes in
-about **3.5 minutes** (the Windows job runs longer but is non-blocking
-— ``continue-on-error: true``). Before Depot, 3 jobs took about 5
-minutes on GitHub Actions runners.
-
-The fast runners didn't just make existing tests faster — they made it
-practical to keep adding tests. If each new Playwright suite added 5
-minutes of wall-clock time, I never would have added 6 of them.
+The critical path completes in about **4 minutes** on Depot. The Windows
+job runs longer but is non-blocking (``continue-on-error: true``).
 
 
 Testing against dependency versions
 -------------------------------------
 
-Depending on pandas, PyArrow, and polars simultaneously is tricky.
-These are complex packages with their own release cadences and breaking
-changes. A new pandas release can change default string dtype behavior.
-A polars update can change how Duration columns serialize. PyArrow
-versions affect Parquet compatibility.
+Depending on pandas, PyArrow, and polars simultaneously is tricky. A new
+pandas release can change default string dtype behavior. A polars update
+can change how Duration columns serialize. PyArrow versions affect
+Parquet compatibility.
 
 Buckaroo runs two sets of test suites: the regular suite tests against
 the minimum pinned versions in ``pyproject.toml``, and the "Max
 Versions" suite tests against the latest releases of every dependency.
 This runs across Python 3.11 through 3.14. The goal is to catch
-compatibility issues before users do — if polars 1.x breaks something,
-I want to know from CI, not from a bug report.
+compatibility issues before users do.
 
 This strategy only works if the test suite is fast enough to run both
 configurations on every push. On slow CI, you'd run one and hope for
@@ -229,11 +254,12 @@ What I'd tell other open source maintainers
 
 If your CI takes more than 5 minutes and you've been meaning to fix it
 but haven't, Depot's `open source sponsorship program
-<https://depot.dev/open-source>`_ is worth applying to. The switch was
+<https://depot.dev/open-source>`_ is worth applying to. The switch is
 straightforward — change the ``runs-on`` label in your workflow YAML,
 everything else stays the same.
 
-The real value isn't the raw speed. It's that fast CI changes your
-behavior. You push more often, you test more things, you catch problems
-earlier. Slow CI is a tax on every decision you make. Removing that tax
-compounds.
+The real value isn't raw speed — individual jobs run at about the same
+pace. It's that your jobs all start at once instead of queueing. That
+consistency changes your behavior. You push more often, you test more
+things, you catch problems earlier. Slow CI is a tax on every decision
+you make. Removing that tax compounds.

From 760461197e099537474c2142a46a583bed7632c0 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Tue, 24 Mar 2026 09:11:46 -0400
Subject: [PATCH 28/29] docs: address review comments on Depot article
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix "GitHub Actions is" grammar
- Explain per-job slowness: Depot has per-runner provisioning overhead,
  but provisions all in parallel; GitHub provisions sequentially from pool
- Verify Monday cache write speed (GH 0.8s vs Depot 2.1s, confirmed)
- Fix "Monday morning" typo
- Remove "no minute quotas" point — reads as "Depot is great if free"
- Renumber value prop list (now 2 items: consistency + confidence)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index db041052..a533f2df 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -8,6 +8,7 @@ understand exactly what that sponsorship buys. The results surprised me.
 The problem with GitHub Actions
 --------------------------------
 
+
 GitHub Actions is slow, but not in the way I expected. The jobs
 themselves are fine — the runners are fast enough. The problem is
 queueing. When you have a 23-job pipeline and GitHub is busy, your jobs
@@ -161,9 +162,12 @@ Aggregated across all Monday runs:
 What's actually happening
 --------------------------
 
-The per-job times are slightly *slower* on Depot — every individual job
-takes a few seconds longer. But it doesn't matter because Depot starts
-all jobs simultaneously.
+Each Depot runner takes a few seconds longer to provision than a GitHub
+runner that's already available — there's a fixed overhead per machine
+spin-up. That makes individual job durations slightly longer on Depot.
+But it doesn't matter because Depot provisions all runners in parallel.
+GitHub provisions them sequentially from a shared pool, so you wait
+for each one.
 
 "Wave 1 stagger" is the time between the first and last Wave 1 job
 starting — it measures how long the runner takes to provision all the
@@ -174,12 +178,13 @@ parallel jobs:
   1.5–7 minutes as runners become available.
 
 On a Sunday night with one PR, GitHub's stagger was 1 second — identical
-to Depot. The difference only shows up under load.
+to Depot. The difference only shows up under load on Monday morning.
 
 Cache performance is close. Depot reads caches ~30% faster (2.8s vs 4.1s
-per step), but GitHub writes caches ~3x faster (0.6s vs 2.2s per step).
-Cache writes happen post-job and don't affect the critical path. Neither
-cache difference materially changes the overall timing.
+per step), but GitHub writes caches ~3x faster (0.8s vs 2.1s per step on
+Monday). Cache writes happen in post-job cleanup steps and don't affect
+the critical path. Neither difference materially changes the overall
+timing.
 
 
 What Depot actually gave me
@@ -192,17 +197,12 @@ Three things, in order of importance:
    on load. When you're pushing 10 times a day and iterating with an LLM,
    unpredictable queue times kill your flow.
 
-2. **No minute quotas.** With Depot's open source sponsorship, I stopped
-   thinking about whether adding another test suite was "worth the
-   minutes." I went from 3 CI jobs to 23 in three months.
-
-3. **Confidence to invest in CI.** Because I knew the infrastructure was
+2. **Confidence to invest in CI.** Because I knew the infrastructure was
    solid, I actually spent time making CI better — removing unnecessary
    setup steps, parallelizing into two waves, tuning the pipeline. When
    your CI infrastructure feels like a liability, you don't invest in
    it — you avoid it.
 
-
 Before and after
 -----------------
 

From 8d000723afff4693db1bd6788b7c6b53798b1702 Mon Sep 17 00:00:00 2001
From: Paddy Mullen <paddy@paddymullen.com>
Date: Tue, 24 Mar 2026 09:24:34 -0400
Subject: [PATCH 29/29] docs: add repo transfer story to Depot article
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scariest part was transferring paddymul/buckaroo to the buckaroo-data
org (required for Depot's open source program). Feared losing GitHub
stars — turns out GitHub's transfer preserves everything (stars, issues,
PRs, forks, redirects).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/source/articles/why-depot.rst | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/source/articles/why-depot.rst b/docs/source/articles/why-depot.rst
index a533f2df..b431c75b 100644
--- a/docs/source/articles/why-depot.rst
+++ b/docs/source/articles/why-depot.rst
@@ -249,6 +249,29 @@ configurations on every push. On slow CI, you'd run one and hope for
 the best.
 
 
+The scariest part
+-------------------
+
+The scariest part of switching to Depot wasn't Depot itself — it was
+that their open source program requires a GitHub organization. Buckaroo
+lived at ``paddymul/buckaroo`` under my personal account. To use Depot I
+had to create the ``buckaroo-data`` organization and **transfer** the
+repository there.
+
+I was terrified of losing my GitHub stars. That sounds vain, but stars
+are the main signal to potential users that a project is real. Losing
+them would set the project back.
+
+It turns out GitHub's repository transfer preserves everything — stars,
+issues, pull requests, forks, watchers. It even sets up URL redirects
+from the old path. The transfer itself took seconds. But I didn't know
+that going in, and I spent more time worrying about it than about any
+technical aspect of the Depot migration.
+
+If you're in the same situation: do the transfer. You won't lose
+anything.
+
+
 What I'd tell other open source maintainers
 ---------------------------------------------
 
@@ -256,7 +279,9 @@ If your CI takes more than 5 minutes and you've been meaning to fix it
 but haven't, Depot's `open source sponsorship program
 <https://depot.dev/open-source>`_ is worth applying to. The switch is
 straightforward — change the ``runs-on`` label in your workflow YAML,
-everything else stays the same.
+everything else stays the same. If you need to create an organization
+and transfer your repo, that's painless too — stars and all metadata
+carry over.
 
 The real value isn't raw speed — individual jobs run at about the same
 pace. It's that your jobs all start at once instead of queueing. That