From df95e239218fb1255c7b764063b9edafc5b725d5 Mon Sep 17 00:00:00 2001
From: tamnd <1218621+tamnd@users.noreply.github.com>
Date: Sat, 29 Aug 2026 08:07:40 +0700
Subject: [PATCH] Add xraywidgets, and the disassembler that goes in the pilot
 lesson

The first of the interactive components issue #14 lists. Type Python, see the
bytecode, and turn on the four things dis leaves out: the specialized opcodes the
interpreter installed, the inline cache entries sitting between the instructions,
the stack depth either side of each one, and the exception table.

Every widget renders twice from one piece of code. With nothing installed it draws
plain HTML with the real numbers in it and the buttons switched off, which is what
a reader gets on GitHub, in an nbconvert render, in a PDF, and while Pyodide is
still starting. With anywidget installed it draws the same picture with the buttons
working. The front end holds no bytecode logic at all: Python computes the rows and
renders the markup, the JavaScript puts it on the page and hands clicks back. So
the two pictures cannot disagree, and there is a test that greps the module for
opcode names to keep it that way.

Two rules are enforced rather than remembered. parts.chip will not build a coloured
badge without words in it, so colour is never the only signal, and style.py reads
the palette out of pyxray.theme with a test that fails on a hand written hex
colour, so the widgets cannot fork away from the diagrams beside them.

Also adds pyxray.bytecode.exception_table, which the exception toggle needs and
which nothing exposed before, and installs the live extra in the CI test job so the
interactive half is exercised on every pull request.
---
 .github/workflows/ci.yml                      |   6 +-
 README.md                                     |   3 +-
 pyproject.toml                                |  22 +-
 pyxray/src/pyxray/bytecode.py                 |  53 ++++
 pyxray/tests/test_bytecode.py                 |  54 ++++
 uv.lock                                       |  91 +++++-
 xraywidgets/README.md                         |  73 +++++
 xraywidgets/pyproject.toml                    |  25 ++
 xraywidgets/src/xraywidgets/__init__.py       |  18 ++
 xraywidgets/src/xraywidgets/base.py           | 144 +++++++++
 xraywidgets/src/xraywidgets/disassembler.py   | 296 ++++++++++++++++++
 xraywidgets/src/xraywidgets/html.py           |  88 ++++++
 xraywidgets/src/xraywidgets/parts.py          | 102 ++++++
 .../src/xraywidgets/static/disassembler.js    |  88 ++++++
 xraywidgets/src/xraywidgets/strings.py        |  57 ++++
 xraywidgets/src/xraywidgets/style.py          | 167 ++++++++++
 xraywidgets/tests/test_xraywidgets_base.py    |  75 +++++
 .../tests/test_xraywidgets_disassembler.py    | 197 ++++++++++++
 xraywidgets/tests/test_xraywidgets_html.py    |  72 +++++
 xraywidgets/tests/test_xraywidgets_live.py    |  79 +++++
 xraywidgets/tests/test_xraywidgets_parts.py   |  80 +++++
 xraywidgets/tests/test_xraywidgets_strings.py |  50 +++
 xraywidgets/tests/test_xraywidgets_style.py   |  52 +++
 23 files changed, 1888 insertions(+), 4 deletions(-)
 create mode 100644 xraywidgets/README.md
 create mode 100644 xraywidgets/pyproject.toml
 create mode 100644 xraywidgets/src/xraywidgets/__init__.py
 create mode 100644 xraywidgets/src/xraywidgets/base.py
 create mode 100644 xraywidgets/src/xraywidgets/disassembler.py
 create mode 100644 xraywidgets/src/xraywidgets/html.py
 create mode 100644 xraywidgets/src/xraywidgets/parts.py
 create mode 100644 xraywidgets/src/xraywidgets/static/disassembler.js
 create mode 100644 xraywidgets/src/xraywidgets/strings.py
 create mode 100644 xraywidgets/src/xraywidgets/style.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_base.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_disassembler.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_html.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_live.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_parts.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_strings.py
 create mode 100644 xraywidgets/tests/test_xraywidgets_style.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2502c28..1b60246 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,7 +44,11 @@ jobs:
       # rather than sit next to it, or both legs of the matrix run the same interpreter
       # and the job quietly stops testing what it says it tests.
       - run: uv python pin ${{ matrix.python }}
-      - run: uv sync --all-packages
+      # The `live` extra brings anywidget, which is what the widgets use when a reader can
+      # click on them. It is installed here rather than only in a developer's environment
+      # because the alternative is that the live half of every widget is never run by CI,
+      # and the static half is the half that is easy to keep working.
+      - run: uv sync --all-packages --extra live
       - run: uv run python -c "import sys; print(sys.version)"
       - run: uv run pytest
 
diff --git a/README.md b/README.md
index 5bd1f43..01b32b8 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,7 @@ Pinned to `v3.15.0rc1` today and moving to `v3.15.0` when it ships on 1 October
 | `nbdiagram` | Every picture in a lesson is an Excalidraw scene drawn from Python, written out as an editable `.excalidraw` and as the `.svg` GitHub and Colab display. Colours, type and spacing come from one shared theme, so the diagrams, the charts and the animations look like one project | [tools/nbdiagram](tools/nbdiagram) |
 | `bpcheck` | The shape a blueprint has to have before somebody can implement from it: the nine sections in order, the header block, the invariant numbering, and no fact deferred to a lesson | [tools/bpcheck](tools/bpcheck) |
 | `xraymanim` | The animations, and the fifteen shapes they are allowed to be made of. Each one is planned as a storyboard that is checked in milliseconds, so a mistake is caught before anybody pays for a render | [xraymanim](xraymanim) |
+| `xraywidgets` | The parts of a lesson you can click, starting with a disassembler that shows what `dis` hides. Each one renders twice from one piece of code: plain HTML with nothing installed, and the same picture with working buttons when anywidget is there | [xraywidgets](xraywidgets) |
 
 ## The lessons
 
@@ -124,7 +125,7 @@ blueprints/     the normative specification, mechanical sections generated
 anim/           manim scenes, built from one shared mobject library
 apps/           the Gradio playgrounds
 pyxray/         the instrumentation toolkit every lesson imports
-xraywidgets/    anywidget components, one implementation for marimo and Jupyter
+xraywidgets/    the widgets a reader clicks, which still draw with nothing installed
 xraymanim/      the visual grammar, so a hundred animations look like one project
 conformance/    the differential harness, the golden corpora and the scorecard
 reimpl/go/      the Go reference implementation, which is the specification's test suite
diff --git a/pyproject.toml b/pyproject.toml
index 84cae33..53524df 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,6 +14,7 @@ dependencies = [
     "pyxray",
     "refcheck",
     "xraymanim",
+    "xraywidgets",
 ]
 
 # Installing the renderer. Manim brings cairo, pango, numpy and scipy with it, which is a
@@ -21,6 +22,9 @@ dependencies = [
 # thing here you have to opt into: `uv sync --extra anim`, or `just build-animations`.
 [project.optional-dependencies]
 anim = ["xraymanim[render]"]
+# The widgets that respond to a click. Everything in `xraywidgets` renders as plain HTML
+# without this, so a reader who skips it still gets the picture, just not the buttons.
+live = ["xraywidgets[live]"]
 
 [dependency-groups]
 dev = [
@@ -38,6 +42,7 @@ members = [
     "tools/nbdiagram",
     "tools/refcheck",
     "xraymanim",
+    "xraywidgets",
 ]
 
 [tool.uv.sources]
@@ -48,6 +53,7 @@ nbdiagram = { workspace = true }
 pyxray = { workspace = true }
 refcheck = { workspace = true }
 xraymanim = { workspace = true }
+xraywidgets = { workspace = true }
 
 [tool.pytest.ini_options]
 testpaths = [
@@ -58,6 +64,7 @@ testpaths = [
     "tools/nbdiagram/tests",
     "tools/refcheck/tests",
     "xraymanim/tests",
+    "xraywidgets/tests",
 ]
 addopts = "-q --strict-markers --strict-config"
 markers = [
@@ -80,7 +87,16 @@ filterwarnings = [
 ]
 
 [tool.ruff.lint.isort]
-known-first-party = ["bpcheck", "nbbuild", "nbcheck", "nbdiagram", "pyxray", "refcheck", "xraymanim"]
+known-first-party = [
+    "bpcheck",
+    "nbbuild",
+    "nbcheck",
+    "nbdiagram",
+    "pyxray",
+    "refcheck",
+    "xraymanim",
+    "xraywidgets",
+]
 
 [tool.ruff]
 line-length = 100
@@ -103,6 +119,10 @@ ignore = [
 # The glossary is the same thing without the notebook around it: definitions written as
 # one paragraph per line, so that a sentence is never split across two of them.
 "pyxray/src/pyxray/glossary.py" = ["E501"]
+# Every word a widget shows a reader lives in one dictionary, written one sentence per line.
+# Splitting a sentence across two source lines to please a line length rule would leave the
+# sentence looking wrapped in the source and identical on screen, which helps nobody.
+"xraywidgets/src/xraywidgets/strings.py" = ["E501"]
 "lessons/**/diagrams.py" = ["E501"]
 # The lesson notebooks are the one thing here that runs on an interpreter we do not choose.
 # A reader in Colab is on whatever Google installed, so a version check the linter thinks
diff --git a/pyxray/src/pyxray/bytecode.py b/pyxray/src/pyxray/bytecode.py
index e71dd7c..b2049f3 100644
--- a/pyxray/src/pyxray/bytecode.py
+++ b/pyxray/src/pyxray/bytecode.py
@@ -275,3 +275,56 @@ def line_table(target: CodeLike) -> list[tuple[int, int, int | None]]:
     own lesson; this is the decoded view a reader needs long before then.
     """
     return list(code_of(target).co_lines())
+
+
+@dataclass(frozen=True)
+class Handler:
+    """One row of the exception table: a protected range and where it lands.
+
+    `start` and `end` are offsets into `co_code`, and the range is half open, so an
+    instruction at `end` is not covered. `depth` is how deep the value stack is unwound to
+    before the handler runs, and `lasti` says whether the offset of the instruction that
+    raised is pushed as well, which a bare `raise` inside the handler needs in order to know
+    what it is re-raising.
+    """
+
+    start: int
+    end: int
+    target: int
+    depth: int
+    lasti: bool
+
+    def covers(self, offset: int) -> bool:
+        """Whether an instruction at this offset is inside the protected range."""
+        return self.start <= offset < self.end
+
+
+def exception_table(target: CodeLike) -> list[Handler]:
+    """The exception table, decoded.
+
+    Since 3.11 there are no `SETUP_FINALLY` instructions in the bytecode. A `try` costs
+    nothing at all until something raises, and what replaced the instructions is this table,
+    which is consulted only while unwinding. That is the single biggest reason a modern
+    disassembly looks different from one a reader may have seen in an older book, and it is
+    invisible unless something prints the table.
+
+    The decoding is `dis._parse_exception_table`, which is private, and the alternative is
+    decoding the varint format in `co_exceptiontable` by hand. That format deserves the
+    lesson it gets rather than a helper function nobody reads, and CPython's own account of
+    it is in `InternalDocs/exception_handling.md`. An interpreter without that private
+    function gives an empty list rather than raising, because a missing extra view of the
+    code is not a reason for a lesson to stop.
+    """
+    parse = getattr(dis, "_parse_exception_table", None)
+    if parse is None:  # pragma: no cover - every supported version has it
+        return []
+    return [
+        Handler(
+            start=entry.start,
+            end=entry.end,
+            target=entry.target,
+            depth=entry.depth,
+            lasti=bool(entry.lasti),
+        )
+        for entry in parse(code_of(target))
+    ]
diff --git a/pyxray/tests/test_bytecode.py b/pyxray/tests/test_bytecode.py
index d3d7265..3b0c145 100644
--- a/pyxray/tests/test_bytecode.py
+++ b/pyxray/tests/test_bytecode.py
@@ -207,3 +207,57 @@ def test_the_jump_table_writes_the_arithmetic_out():
 def test_a_loop_jumps_both_ways():
     directions = {jump.backwards for jump in bytecode.jumps(LOOP)}
     assert directions == {True, False}
+
+
+#: A `try` with both an `except` and a `finally`, which is the smallest piece of Python that
+#: produces more than one handler row. The `finally` body is compiled twice, once for the
+#: path where nothing went wrong and once for the path where something did.
+GUARDED = """
+try:
+    risky()
+except ValueError:
+    handled()
+finally:
+    always()
+"""
+
+
+def test_code_that_cannot_raise_has_no_exception_table():
+    assert bytecode.exception_table("x = 1") == []
+
+
+def test_a_try_produces_handlers():
+    assert bytecode.exception_table(GUARDED)
+
+
+def test_the_handlers_are_the_ones_dis_parses():
+    parsed = dis._parse_exception_table(bytecode.code_of(GUARDED))
+    ours = bytecode.exception_table(GUARDED)
+    assert [(one.start, one.end, one.target) for one in ours] == [
+        (one.start, one.end, one.target) for one in parsed
+    ]
+
+
+def test_a_handler_covers_the_offsets_between_its_ends():
+    first = bytecode.exception_table(GUARDED)[0]
+    assert first.covers(first.start)
+    assert first.covers(first.end - 1)
+    assert not first.covers(first.end)
+    assert not first.covers(first.start - 1)
+
+
+def test_the_protected_range_holds_the_call_that_can_raise():
+    first = bytecode.exception_table(GUARDED)[0]
+    inside = [item.opname for item in bytecode.disassemble(GUARDED) if first.covers(item.offset)]
+    assert "CALL" in inside
+
+
+def test_a_handler_target_is_a_real_offset_in_the_code():
+    offsets = {item.offset for item in bytecode.disassemble(GUARDED)}
+    for handler in bytecode.exception_table(GUARDED):
+        assert handler.target in offsets
+
+
+def test_the_handlers_come_back_in_offset_order():
+    starts = [one.start for one in bytecode.exception_table(GUARDED)]
+    assert starts == sorted(starts)
diff --git a/uv.lock b/uv.lock
index ffca51b..f48e7e9 100644
--- a/uv.lock
+++ b/uv.lock
@@ -12,6 +12,21 @@ members = [
     "pyxray",
     "refcheck",
     "xraymanim",
+    "xraywidgets",
+]
+
+[[package]]
+name = "anywidget"
+version = "0.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "ipywidgets" },
+    { name = "psygnal" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/79/31/0491d707c674b34267f55d96d6a7148e55e7b6718a271686232cf295fbe2/anywidget-0.11.0.tar.gz", hash = "sha256:6695fbef9449cf8c27f421b96c5837aa37f909ec1f60cfa33add333e1b70b169", size = 426999, upload-time = "2026-04-27T23:42:09.576Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8e/c2/8fec8e8e2eb920cc2280f569144080cd58622a2eda83bfa4c0c354a63264/anywidget-0.11.0-py3-none-any.whl", hash = "sha256:c574d9acc6503ad27b37a9acea48f957a8ba7c9c9876cfcb37898931c098ce9d", size = 317341, upload-time = "2026-04-27T23:42:08.356Z" },
 ]
 
 [[package]]
@@ -304,12 +319,16 @@ dependencies = [
     { name = "pyxray" },
     { name = "refcheck" },
     { name = "xraymanim" },
+    { name = "xraywidgets" },
 ]
 
 [package.optional-dependencies]
 anim = [
     { name = "xraymanim", extra = ["render"] },
 ]
+live = [
+    { name = "xraywidgets", extra = ["live"] },
+]
 
 [package.dev-dependencies]
 dev = [
@@ -328,8 +347,10 @@ requires-dist = [
     { name = "refcheck", editable = "tools/refcheck" },
     { name = "xraymanim", editable = "xraymanim" },
     { name = "xraymanim", extras = ["render"], marker = "extra == 'anim'", editable = "xraymanim" },
+    { name = "xraywidgets", editable = "xraywidgets" },
+    { name = "xraywidgets", extras = ["live"], marker = "extra == 'live'", editable = "xraywidgets" },
 ]
-provides-extras = ["anim"]
+provides-extras = ["anim", "live"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -462,6 +483,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d9/33/1f075bf72b0b747cb3288d011319aaf64083cf2efef8354174e3ed4540e2/ipython_pygments_lexers-1.1.1-py3-none-any.whl", hash = "sha256:a9462224a505ade19a605f71f8fa63c2048833ce50abc86768a0d81d876dc81c", size = 8074, upload-time = "2025-01-17T11:24:33.271Z" },
 ]
 
+[[package]]
+name = "ipywidgets"
+version = "8.1.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "comm" },
+    { name = "ipython" },
+    { name = "jupyterlab-widgets" },
+    { name = "traitlets" },
+    { name = "widgetsnbextension" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c9/7c/6db60eddf38547353b06d57941f5eee22a990640ce30479fd71a810507f2/ipywidgets-8.1.9.tar.gz", hash = "sha256:bcccba38a6ec3253f7a39c943cea5b9ad01999ce071396171adbc51c6a6a8613", size = 117252, upload-time = "2026-08-18T08:54:24.123Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c3/55/298e9b3b864a198234997e87a1471c1b17d7f3546ace6d18fb5cf1ce24b2/ipywidgets-8.1.9-py3-none-any.whl", hash = "sha256:f2b8cbcaae10252b809fbe4d7470db75c09b769a32cbf816d20e5ca6d3c5a79d", size = 140101, upload-time = "2026-08-18T08:54:22.339Z" },
+]
+
 [[package]]
 name = "isosurfaces"
 version = "0.1.2"
@@ -543,6 +580,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e7/e7/80988e32bf6f73919a113473a604f5a8f09094de312b9d52b79c2df7612b/jupyter_core-5.9.1-py3-none-any.whl", hash = "sha256:ebf87fdc6073d142e114c72c9e29a9d7ca03fad818c5d300ce2adc1fb0743407", size = 29032, upload-time = "2025-10-16T19:19:16.783Z" },
 ]
 
+[[package]]
+name = "jupyterlab-widgets"
+version = "3.0.17"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/8b/e739cf9066ad5037a2d4b0a403f06da374fdccb9748221661c8b492d3dbc/jupyterlab_widgets-3.0.17.tar.gz", hash = "sha256:6e61fe21ca8a66039180a5cc52a433e07279d2fee79c8be963e00d55193f17a8", size = 213919, upload-time = "2026-08-18T08:52:17.511Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/ef/6d27fc118f58cb24886da413545a7efb0853d405fddbfd8b2d9ac09fbed4/jupyterlab_widgets-3.0.17-py3-none-any.whl", hash = "sha256:40ac1e9955acf116c4d995d9bfa082d86ad9ec6d91c4f134827cf5e0a5eb75e0", size = 217292, upload-time = "2026-08-18T08:52:15.47Z" },
+]
+
 [[package]]
 name = "manim"
 version = "0.21.0"
@@ -952,6 +998,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8c/c7/7bb2e321574b10df20cbde462a94e2b71d05f9bbda251ef27d104668306a/psutil-7.2.2-cp37-abi3-win_arm64.whl", hash = "sha256:8c233660f575a5a89e6d4cb65d9f938126312bca76d8fe087b947b3a1aaac9ee", size = 134617, upload-time = "2026-01-28T18:15:36.514Z" },
 ]
 
+[[package]]
+name = "psygnal"
+version = "0.15.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4e/79/20c3e23e75272e9ddf018097cf872ab088bccba978888472656629efa4a3/psygnal-0.15.1.tar.gz", hash = "sha256:f64f62dee2306fc1c22050a59b6c6cdad126e04b0cf50e393ff858a1da719096", size = 123147, upload-time = "2026-01-04T16:38:41.959Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/2e/975bd61727578d88df62797f78390965ca7905780cf01eb59cb095a13638/psygnal-0.15.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:803fc33c4280c822c6f4b22e6c3ea7c4483e190f3cc69e69350098b3799476f3", size = 595706, upload-time = "2026-01-04T16:38:34.139Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/55/e487f1d91497eb75e86c3fdfef69a21b1cab24d023383dd7648b08797d6a/psygnal-0.15.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4f53b4b83355b0a785b745987fd04e59bbf169a9028ed81a68ca7e05fb76d458", size = 575133, upload-time = "2026-01-04T16:38:35.448Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/2f/f286355accd0e68d3eef52e63c8b9ab6ba33ec3107177719a036b3319657/psygnal-0.15.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bcbca12190f5aa65c1f8fb04a81fa6f4463c5f5dde25cd74c3a56ceff6f37b02", size = 889565, upload-time = "2026-01-04T16:38:37.003Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/dc/40c6026c88d7f9220ecc913afe0501045a512c9b82f9b7e036bb089dc287/psygnal-0.15.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:1ac399566852fe4354ce26a1acbe12319232e8c2b615fe5ad1e114c547095cf6", size = 880863, upload-time = "2026-01-04T16:38:38.381Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/85/b4f45ec3057c473b5622fc002b3a636a698c34d3a0917a064ff5247f1984/psygnal-0.15.1-cp314-cp314-win_amd64.whl", hash = "sha256:d3a03055f331ce91d44581c71edb79938ccc133a94af2ce7ad3a18fa57ac7be5", size = 423654, upload-time = "2026-01-04T16:38:39.7Z" },
+    { url = "https://files.pythonhosted.org/packages/46/49/7742544684bee728ec123515d2694cee859aa2a705951a461230b00f18cc/psygnal-0.15.1-py3-none-any.whl", hash = "sha256:4221140e633e45b076953c64bcb9b41a744833527f9a037c1ca98bc270798cbf", size = 90638, upload-time = "2026-01-04T16:38:40.841Z" },
+]
+
 [[package]]
 name = "ptyprocess"
 version = "0.7.0"
@@ -1499,6 +1559,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/96/42/3e5985a0a7e57de470b320c6d6a1a67c844f6737a587f3d44dd13d1819e7/wcwidth-0.8.2-py3-none-any.whl", hash = "sha256:d63947694a0539a1d51e01eda7caf800c291020e6cdd7e28ad7b14dd33ad4f85", size = 323166, upload-time = "2026-06-29T18:11:09.888Z" },
 ]
 
+[[package]]
+name = "widgetsnbextension"
+version = "4.0.16"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/60/bc7a980fc78837d6ef8f5940cca4cadc433364503a4c4d42e2a7a0de3231/widgetsnbextension-4.0.16.tar.gz", hash = "sha256:adeea0ae78f0856ee4945f413299801b82a0a01416303301f39a704282a37b73", size = 1111094, upload-time = "2026-08-18T08:52:55.859Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/34/95/40e17e20046b7bc820d29d09ae84ec157ec8dd6e6f6cd722626292c31b2e/widgetsnbextension-4.0.16-py3-none-any.whl", hash = "sha256:a31a8774885b96fe825462f5d6496166f0c7cae111195b6465c801d230eb5a4e", size = 2225148, upload-time = "2026-08-18T08:52:53.736Z" },
+]
+
 [[package]]
 name = "xraymanim"
 version = "0.1.0"
@@ -1518,3 +1587,23 @@ requires-dist = [
     { name = "pyxray", editable = "pyxray" },
 ]
 provides-extras = ["render"]
+
+[[package]]
+name = "xraywidgets"
+version = "0.1.0"
+source = { editable = "xraywidgets" }
+dependencies = [
+    { name = "pyxray" },
+]
+
+[package.optional-dependencies]
+live = [
+    { name = "anywidget" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "anywidget", marker = "extra == 'live'", specifier = ">=0.9" },
+    { name = "pyxray", editable = "pyxray" },
+]
+provides-extras = ["live"]
diff --git a/xraywidgets/README.md b/xraywidgets/README.md
new file mode 100644
index 0000000..ac1c0f0
--- /dev/null
+++ b/xraywidgets/README.md
@@ -0,0 +1,73 @@
+# xraywidgets
+
+The interactive parts of a lesson. Type some Python, see what the compiler made of it, and turn on the things `dis` leaves out.
+
+Every widget here renders twice from one piece of code. Without anywidget installed you get plain HTML: a real picture with real numbers in it, just with the buttons switched off. With anywidget installed you get the same picture with the buttons working. That is not a fallback bolted on at the end, it is how the package is built, and there is a section below on why.
+
+## The disassembler
+
+```python
+from xraywidgets import Disassembler
+
+Disassembler("total = sum(values)")
+```
+
+In a notebook that prints the bytecode as a table. Four things are off by default and can be turned on, either by passing them in or by clicking:
+
+| Toggle | What it adds |
+|---|---|
+| Specialized opcodes | The rewritten forms the interpreter installs after it has watched an instruction run a few times, so `LOAD_ATTR` shows up as `LOAD_ATTR_INSTANCE_VALUE` once it has settled |
+| Inline caches | The cache entries sitting between the instructions. They take up real bytes in the code object, and `dis` hides them by default, which is why offsets appear to skip |
+| Stack depth | How tall the value stack is before and after each instruction, which is the fastest way to see why an expression compiles the way it does |
+| Exception table | Where a `try` went. Since 3.11 there are no `SETUP_FINALLY` instructions to look at, and the handlers live in a side table instead |
+
+They are off to start with because a first disassembly with all four on is a wall of numbers, and a reader who has not yet worked out what an offset is will not get past it.
+
+```python
+Disassembler(some_function, depths=True).live()  # buttons work, needs `uv sync --extra live`
+```
+
+The argument can be a string, a function, a method or a code object, so a lesson can hand it the function it was just talking about rather than a copy of the text of it.
+
+## Why the browser decides nothing
+
+Python computes the rows and renders the HTML. The JavaScript puts that HTML on the page, listens for a click on a toggle and a keystroke in the source box, and hands both back to Python. It contains no opcode names, no cache arithmetic and no idea what an exception table is, and there is a test that greps it for opcode names to keep it that way.
+
+The reason is not tidiness. If the front end worked out which opcodes were specialized, there would be two answers to that question in this repository, and the one written in JavaScript is the one nobody runs a test against. It would drift, and it would drift in the direction of looking right, because the person who noticed would be a reader who trusted the widget over `dis` and got the wrong idea about CPython. Keeping the logic on one side means the picture in a rendered notebook and the picture you can click are the same picture by construction.
+
+It is also what makes the static rendering real. There is no code path where a widget is only correct once a browser is involved, so the version a reader sees on GitHub, in an nbconvert render, in a PDF export, or in the seconds before Pyodide has finished starting is a version with the right numbers in it.
+
+## Colour is never the only signal
+
+Every coloured thing in a widget is a chip, and `parts.chip` will not build one without a label. So the badge on a specialized opcode says the word "specialized" and not just a blue tint, which is what a reader with any of the common kinds of colour blindness needs, and also what survives a printed handout or a screenshot pasted into a chat with the saturation eaten by compression. Making the label a required argument is cheaper than writing that review comment every time.
+
+The toggles are real `<button>` elements with `aria-pressed`, not styled `<div>`s, so they are reachable by tab and operable by space bar without a line of JavaScript, and a screen reader can say whether one is on. The static rendering marks them disabled, because a button that looks live and does nothing is worse than one that admits it.
+
+## The palette comes from one place
+
+There is no hex colour written in this package. `style.py` reads `pyxray.theme`, the same module the Excalidraw diagrams, the matplotlib charts and the manim animations read, and writes it out as CSS custom properties. A test greps the stylesheet for hand written colours and fails if it finds one, so a widget cannot quietly fork away from the diagrams next to it.
+
+Dark mode swaps the neutrals and leaves the tones alone. The tones are pale fills with dark strokes and they read as chips sitting on the page rather than as page colour, so they work against either background. Giving them a second set of values would mean a second palette to keep in step with the diagrams, and an SVG committed to a repository has one set of colours in it.
+
+## Layout
+
+```
+src/xraywidgets/
+  html.py         building HTML in about eighty lines, with escaping that is not optional
+  strings.py      every word a widget shows, in one dictionary
+  style.py        the stylesheet, generated from pyxray.theme
+  parts.py        the markup more than one widget needs, so it only looks one way
+  base.py         what a widget is, and its two forms
+  disassembler.py the first one
+  static/         one front end module per widget, named after its slug
+```
+
+## Installing
+
+Nothing to do: it comes with the workspace, and `pyxray` is its only dependency. For the version with working buttons:
+
+```
+uv sync --extra live
+```
+
+CI installs that extra when it runs the tests, so the live path is exercised on every pull request rather than only on the machine of whoever happened to have anywidget installed.
diff --git a/xraywidgets/pyproject.toml b/xraywidgets/pyproject.toml
new file mode 100644
index 0000000..2d74381
--- /dev/null
+++ b/xraywidgets/pyproject.toml
@@ -0,0 +1,25 @@
+[project]
+name = "xraywidgets"
+version = "0.1.0"
+description = "The interactive components the lessons embed, in marimo, in Jupyter and in the browser"
+requires-python = ">=3.14"
+license = "MIT"
+dependencies = ["pyxray"]
+
+# anywidget is optional, and that is the whole design rather than a packaging convenience.
+# Every widget here renders to plain HTML with no dependency at all, which is what a reader
+# sees on GitHub, in an nbconvert render, and in the seconds before Pyodide has finished
+# booting. Installing this extra adds the live version on top of that picture. If it were a
+# hard dependency the fallback would be a promise nobody ever tests.
+[project.optional-dependencies]
+live = ["anywidget>=0.9"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xraywidgets"]
+
+[tool.uv.sources]
+pyxray = { workspace = true }
diff --git a/xraywidgets/src/xraywidgets/__init__.py b/xraywidgets/src/xraywidgets/__init__.py
new file mode 100644
index 0000000..d3ede99
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/__init__.py
@@ -0,0 +1,18 @@
+"""Small interactive widgets for the lessons, which also work with nothing installed.
+
+Every widget here draws itself as plain HTML with no dependency beyond `pyxray`, so it shows
+up on GitHub, in an nbconvert render, in a PDF, and while Pyodide is still starting. Call
+`.live()` on one to get the version with working buttons, which needs anywidget.
+
+    from xraywidgets import Disassembler
+
+    Disassembler("total = sum(values)", depths=True)   # a still picture
+    Disassembler("total = sum(values)").live()          # the same thing, clickable
+
+See `base.Widget` for why the truth lives in Python and the browser only draws.
+"""
+
+from .base import Widget
+from .disassembler import Disassembler
+
+__all__ = ["Disassembler", "Widget"]
diff --git a/xraywidgets/src/xraywidgets/base.py b/xraywidgets/src/xraywidgets/base.py
new file mode 100644
index 0000000..c5dc6af
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/base.py
@@ -0,0 +1,144 @@
+"""What every widget in this package is, and the two ways it can be shown.
+
+A widget here is a plain Python object that knows how to compute its own state and how to
+draw that state as HTML. It is not an `ipywidgets` subclass, it does not import anywidget,
+and it works with nothing installed beyond `pyxray`. That is what `_repr_html_` gives you,
+and it is what a reader gets on GitHub, in an nbconvert render of a lesson, in a PDF export,
+and in the seconds before Pyodide has finished starting up.
+
+Calling `.live()` on one asks for the interactive version, which needs anywidget, and which
+is the same state drawn by a small piece of JavaScript that can also send changes back. The
+important part of that arrangement is which side owns the truth: Python does. The front end
+holds no bytecode logic at all, it draws rows that Python computed and it asks Python to
+compute new ones when a toggle changes. So the static picture and the live one cannot say
+different things, because there is only one implementation of what they say.
+
+This is also why the fallback is real rather than a promise. There is no code path where a
+widget is only correct once a browser is involved.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import ClassVar
+
+from .html import Raw, element, raw
+from .strings import text
+from .style import PREFIX, stylesheet
+
+#: Where the front end modules live. One file per widget, named after its slug.
+STATIC = Path(__file__).resolve().parent / "static"
+
+
+class Widget:
+    """One component, in its two forms.
+
+    A subclass sets `slug`, implements `state` and implements `body`. Everything else here
+    is the same for all of them, which is the point of having a base class at all: a second
+    widget that draws its own outer frame is a second widget that gets the padding wrong.
+    """
+
+    #: The name of the widget, used for its front end file and its root element id. Lower
+    #: case with hyphens, matching the animation slugs, for one convention rather than two.
+    slug: ClassVar[str]
+
+    def state(self) -> dict[str, object]:
+        """Everything the picture is drawn from, as plain data.
+
+        Plain data, and not objects, because this is exactly what crosses to the front end
+        when the widget is live. Keeping it to things that survive a round trip through JSON
+        means the static path and the live path are drawing the same thing rather than two
+        things that agree today.
+        """
+        raise NotImplementedError
+
+    def markup(self, state: dict[str, object], *, live: bool = False) -> Raw:
+        """The picture itself, without the outer frame or the stylesheet.
+
+        One method for both forms, with `live` saying whether the controls work. That is
+        deliberate. Two render methods would be two things to keep in step, and the one that
+        nobody looks at is the static one, which is the one most readers see.
+        """
+        raise NotImplementedError
+
+    def body(self, state: dict[str, object]) -> Raw:
+        """The still picture, with its controls switched off and the notice underneath."""
+        return self.markup(state, live=False)
+
+    def view(self) -> dict[str, object]:
+        """What crosses to the front end: the state, and the markup drawn from it.
+
+        The markup travels with the data because the front end does not build any. It puts
+        this string on the page and attaches listeners to the buttons and the box you type
+        in, and when one of those changes it hands the change back to Python and gets a new
+        string. So there is one renderer, written in Python, and the live widget cannot drift
+        away from the static one.
+        """
+        state = self.state()
+        return {**state, "html": str(self.markup(state, live=True))}
+
+    def render(self) -> str:
+        """The whole widget as a standalone block of HTML.
+
+        The stylesheet goes in with it. That is a duplicated sheet per widget on a page with
+        several, which is a few kilobytes and is worth it: a widget that depends on a style
+        tag somewhere else on the page is a widget that renders unstyled the first time
+        somebody embeds one on its own.
+        """
+        return str(
+            element(
+                "div",
+                element("style", raw(stylesheet())),
+                self.body(self.state()),
+                class_=PREFIX,
+                data_widget=self.slug,
+            )
+        )
+
+    def _repr_html_(self) -> str:
+        """What Jupyter, marimo and nbconvert call. The static picture, always."""
+        return self.render()
+
+    @classmethod
+    def esm(cls) -> str:
+        """The front end module for this widget, as source.
+
+        Read off disk rather than embedded in a Python string, so that it is a `.js` file
+        an editor will highlight and a linter could be pointed at.
+        """
+        path = STATIC / f"{cls.slug}.js"
+        if not path.is_file():
+            raise FileNotFoundError(f"{cls.slug} has no front end module at {path}")
+        return path.read_text(encoding="utf-8")
+
+    @classmethod
+    def css(cls) -> str:
+        """The stylesheet, for anywidget, which wants it separately rather than inline."""
+        return stylesheet()
+
+    def live(self) -> object:
+        """The interactive version, which needs anywidget.
+
+        Raises with something a reader can act on rather than an `ImportError` from three
+        frames down, because the person who hits this is a reader following a lesson and not
+        a developer reading a traceback.
+        """
+        try:
+            import anywidget
+            import traitlets
+        except ImportError as missing:  # pragma: no cover - depends on the environment
+            raise RuntimeError(
+                "the live version needs anywidget, which is the `live` extra: "
+                "`uv sync --extra live`, or `pip install anywidget`. "
+                "The picture you already have is the static one and is not wrong, "
+                "it just does not have buttons."
+            ) from missing
+        return self._anywidget(anywidget, traitlets)
+
+    def _anywidget(self, anywidget: object, traitlets: object) -> object:
+        """Build the anywidget instance. Subclasses say which traits they have."""
+        raise NotImplementedError
+
+    def notice(self) -> Raw:
+        """The line that says this is the still picture and where the moving one is."""
+        return element("p", text("common.static_notice"), class_=f"{PREFIX}-note")
diff --git a/xraywidgets/src/xraywidgets/disassembler.py b/xraywidgets/src/xraywidgets/disassembler.py
new file mode 100644
index 0000000..c49fc03
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/disassembler.py
@@ -0,0 +1,296 @@
+"""Type Python, see the bytecode, and turn on the parts that are usually hidden.
+
+`dis.dis` prints a good table and stops there. The four things a reader keeps needing next
+are not in it: which opcodes the interpreter has rewritten into specialized forms, the
+inline cache entries that take up real bytes between the instructions, how deep the value
+stack is at each point, and the exception table, which is where a `try` went after 3.11.
+Each of those is a toggle here, off by default, because a first disassembly with all four
+on is a wall.
+
+Every number here comes from `pyxray`, which is the same module the lessons import when they
+print a disassembly into a plain cell. That matters more than it sounds. A reader who checks
+a widget against `dis` and finds a disagreement has not found a rendering bug, they have
+learned that the material cannot be trusted, and they are right to.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import ClassVar
+
+from pyxray import bytecode, stack
+
+from .base import Widget
+from .html import Raw, element, join
+from .parts import chip, error, head, source, table, toggles
+from .strings import text
+from .style import PREFIX
+
+#: The toggles, in the order they appear, with the string that labels each one. The order is
+#: the order they become useful: what the interpreter did to the code, then what is between
+#: the instructions, then what the stack is doing, then what happens when it all goes wrong.
+FLAGS: tuple[tuple[str, str], ...] = (
+    ("adaptive", "disassembler.adaptive"),
+    ("caches", "disassembler.caches"),
+    ("depths", "disassembler.depths"),
+    ("exceptions", "disassembler.exceptions"),
+)
+
+
+@dataclass
+class Disassembler(Widget):
+    """One block of Python and its bytecode, with four things you can turn on.
+
+    The source can be a string, a function, a method or a code object, which is whatever
+    `pyxray.bytecode.code_of` accepts, so a lesson can hand it the function it was just
+    talking about rather than the text of it.
+    """
+
+    slug: ClassVar[str] = "disassembler"
+
+    code: str = "answer = 6 * 7"
+    adaptive: bool = False
+    caches: bool = False
+    depths: bool = False
+    exceptions: bool = False
+    title: str = ""
+
+    def state(self) -> dict[str, object]:
+        """The rows, the toggles and the version, as plain data.
+
+        A source string that does not compile is a state and not an exception. The reader is
+        typing, and half typed Python does not compile most of the time, so a widget that
+        raised would spend most of its life as a traceback.
+        """
+        try:
+            rows = self.rows()
+        except SyntaxError as broken:
+            return {
+                "code": self.code,
+                "title": self.title or text("disassembler.title"),
+                "flags": self.flags(),
+                "version": text("common.python", version=self.version()),
+                "error": text("common.error", reason=str(broken.msg)),
+                "rows": [],
+                "handlers": [],
+            }
+        return {
+            "code": self.code,
+            "title": self.title or text("disassembler.title"),
+            "flags": self.flags(),
+            "version": text("common.python", version=self.version()),
+            "error": "",
+            "rows": rows,
+            "handlers": self.handlers(),
+        }
+
+    def version(self) -> str:
+        """The interpreter this disassembly came from, which is not always the reader's.
+
+        Written next to the table because bytecode changes between versions more than almost
+        anything else in Python, and a listing without a version on it is a listing somebody
+        will quote in three years.
+        """
+        return ".".join(str(part) for part in sys.version_info[:3])
+
+    def flags(self) -> list[dict[str, object]]:
+        """The toggle row as data, so the static and live versions cannot disagree on it."""
+        return [
+            {"name": name, "label": text(key), "on": bool(getattr(self, name))}
+            for name, key in FLAGS
+        ]
+
+    def rows(self) -> list[dict[str, object]]:
+        """One entry per instruction, plus one per run of inline caches when those are on.
+
+        The stack heights are looked up by offset rather than zipped, because `stack.walk`
+        leaves out instructions it cannot reach and zipping two lists of different lengths
+        silently shifts every row after the first gap.
+        """
+        instructions = bytecode.disassemble(self.code, adaptive=self.adaptive)
+        heights = {}
+        if self.depths:
+            heights = {step.offset: (step.before, step.after) for step in stack.walk(self.code)}
+        rows: list[dict[str, object]] = []
+        for item in instructions:
+            before, after = heights.get(item.offset, (None, None))
+            rows.append(
+                {
+                    "kind": "instruction",
+                    "offset": item.offset,
+                    "opname": item.opname,
+                    "arg": "" if item.arg is None else str(item.arg),
+                    "argrepr": item.argrepr,
+                    "meaning": bytecode.argument_meaning(item.base_opname),
+                    "specialized": item.specialized,
+                    "base": item.base_opname,
+                    "jump_target": item.jump_target,
+                    "is_target": item.is_jump_target,
+                    "before": before,
+                    "after": after,
+                }
+            )
+            if self.caches and item.caches:
+                rows.append(
+                    {
+                        "kind": "cache",
+                        "offset": item.offset + 2,
+                        "text": text("disassembler.cache_row", count=item.caches),
+                        "bytes": 2 * item.caches,
+                    }
+                )
+        return rows
+
+    def handlers(self) -> list[dict[str, object]]:
+        """The exception table as sentences, because the raw five numbers mean nothing yet."""
+        if not self.exceptions:
+            return []
+        return [
+            {
+                "start": one.start,
+                "end": one.end,
+                "target": one.target,
+                "depth": one.depth,
+                "lasti": one.lasti,
+                "text": text(
+                    "disassembler.exception_range",
+                    start=one.start,
+                    end=one.end,
+                    target=one.target,
+                    depth=one.depth,
+                    lasti=text("disassembler.lasti") if one.lasti else "",
+                ),
+            }
+            for one in bytecode.exception_table(self.code)
+        ]
+
+    def markup(self, state: dict[str, object], *, live: bool = False) -> Raw:
+        """The source, the toggles, the table, the exception table, and the notice."""
+        count = text("disassembler.count", count=len(state["rows"]))
+        parts = [
+            head(state["title"], state["version"], count),
+            source(state["code"], live=live),
+            toggles([(one["name"], one["label"], one["on"]) for one in state["flags"]], live=live),
+        ]
+        if state["error"]:
+            parts.append(error(state["error"]))
+        elif not state["rows"]:
+            parts.append(element("p", text("common.nothing"), class_=f"{PREFIX}-note"))
+        else:
+            parts.append(table(self.headings(), [self.row(one) for one in state["rows"]]))
+        if self.exceptions:
+            parts.append(self.exception_block(state["handlers"]))
+        if not live:
+            parts.append(self.notice())
+        return join(parts)
+
+    def headings(self) -> list[str]:
+        """The column names, with the stack column present only when it is turned on."""
+        names = [
+            text("disassembler.offset"),
+            text("disassembler.instruction"),
+            text("disassembler.argument"),
+            text("disassembler.meaning"),
+        ]
+        if self.depths:
+            names.insert(2, text("disassembler.depth"))
+        return names
+
+    def row(self, entry: dict[str, object]) -> Raw:
+        """One table row, either an instruction or a run of caches between two of them."""
+        if entry["kind"] == "cache":
+            return element(
+                "tr",
+                element("td", entry["offset"], class_=f"{PREFIX}-mono"),
+                element("td", entry["text"], colspan=str(len(self.headings()) - 1)),
+                class_=f"{PREFIX}-cache",
+            )
+        cells = [
+            element("td", entry["offset"], class_=f"{PREFIX}-mono"),
+            element("td", self.instruction(entry), class_=f"{PREFIX}-mono"),
+            element("td", entry["argrepr"] or entry["arg"], class_=f"{PREFIX}-mono"),
+            element("td", self.meaning(entry)),
+        ]
+        if self.depths:
+            cells.insert(2, element("td", self.depth(entry), class_=f"{PREFIX}-mono"))
+        return element("tr", join(cells))
+
+    def instruction(self, entry: dict[str, object]) -> Raw:
+        """The opcode name, with a chip beside it when the interpreter rewrote it.
+
+        The chip says the word "specialized" and names the opcode it came from. It is not
+        just a colour, and it is not just a symbol, because a reader meeting their first
+        specialized opcode needs the word before the colour means anything to them.
+        """
+        if not entry["specialized"]:
+            return element("span", entry["opname"])
+        return join(
+            [
+                element("span", entry["opname"]),
+                " ",
+                chip(
+                    text("disassembler.specialized"),
+                    "focus",
+                    title=f"{entry['opname']} is a specialized form of {entry['base']}",
+                ),
+            ]
+        )
+
+    def depth(self, entry: dict[str, object]) -> str:
+        """The stack height either side of the instruction, or a dash where it is unknown.
+
+        A dash rather than a blank. An instruction the walk never reached has no honest
+        height, and an empty cell reads as zero.
+        """
+        if entry["before"] is None:
+            return "-"
+        return f"{entry['before']} to {entry['after']}"
+
+    def meaning(self, entry: dict[str, object]) -> Raw:
+        """What the argument is for, plus where a jump goes if it is one."""
+        parts = [entry["meaning"]]
+        if entry["jump_target"] is not None:
+            parts.append(" ")
+            parts.append(
+                chip(text("disassembler.jump", target=entry["jump_target"]), "intermediate")
+            )
+        return join(parts)
+
+    def exception_block(self, handlers: list[dict[str, object]]) -> Raw:
+        """The exception table, as sentences, or the sentence that says there is not one."""
+        if not handlers:
+            return element("p", text("disassembler.no_exceptions"), class_=f"{PREFIX}-note")
+        return element(
+            "ul",
+            join(element("li", one["text"]) for one in handlers),
+            class_=f"{PREFIX}-note",
+        )
+
+    def _anywidget(self, anywidget: object, traitlets: object) -> object:
+        """The live version: the same state, with traits the front end can change.
+
+        Only the toggles and the source are traits the front end writes. `state` is written
+        by Python whenever one of those changes, and the front end never computes a row, so
+        there is no second implementation of what a disassembly says.
+        """
+        owner = self
+
+        class LiveDisassembler(anywidget.AnyWidget):
+            _esm = owner.esm()
+            _css = owner.css()
+            code = traitlets.Unicode(owner.code).tag(sync=True)
+            adaptive = traitlets.Bool(owner.adaptive).tag(sync=True)
+            caches = traitlets.Bool(owner.caches).tag(sync=True)
+            depths = traitlets.Bool(owner.depths).tag(sync=True)
+            exceptions = traitlets.Bool(owner.exceptions).tag(sync=True)
+            view = traitlets.Dict(owner.view()).tag(sync=True)
+
+            @traitlets.observe("code", "adaptive", "caches", "depths", "exceptions")
+            def _recompute(self, _change):
+                owner.code = self.code
+                for name, _ in FLAGS:
+                    setattr(owner, name, getattr(self, name))
+                self.view = owner.view()
+
+        return LiveDisassembler()
diff --git a/xraywidgets/src/xraywidgets/html.py b/xraywidgets/src/xraywidgets/html.py
new file mode 100644
index 0000000..bb382f9
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/html.py
@@ -0,0 +1,88 @@
+"""Building HTML by hand, in about eighty lines, because the alternative is worse.
+
+A template engine would be a dependency, and a dependency here is a dependency in the WASM
+build, where every wheel is a download the reader waits through. The widgets emit small,
+regular structures, so the amount of templating actually needed is one function that joins
+tags and one that escapes text.
+
+Escaping is not optional and it is not a detail. A `Disassembler` renders whatever source
+the reader typed, and the reader is going to type `<`, because they are learning a language
+that uses it. Everything that goes into a document goes through `escape` on the way, and
+the only way to put raw markup in is `raw`, which is deliberately awkward to write.
+"""
+
+from __future__ import annotations
+
+import html
+from collections.abc import Iterable
+
+#: Tags that have no closing half. There are more in HTML, but a widget that needs `<embed>`
+#: has gone somewhere this module should not follow it to.
+VOID = frozenset({"br", "hr", "img", "input", "meta", "link"})
+
+
+class Raw(str):
+    """Markup that is already safe, which `element` will not escape again.
+
+    A separate type rather than a flag, so that passing a string somewhere it will be
+    escaped is the default and passing one somewhere it will not needs the word `raw` in
+    the source. That is the right way round: the mistake to make hard is the unsafe one.
+    """
+
+    __slots__ = ()
+
+
+def raw(markup: str) -> Raw:
+    """Mark a string as markup rather than text. Read the call site twice."""
+    return Raw(markup)
+
+
+def escape(text: object) -> Raw:
+    """Anything at all, as text that cannot become markup.
+
+    Quotes are escaped too, because the same function is used for attribute values, and a
+    version that only handles `<` and `&` works right up until somebody puts a title on a
+    button.
+    """
+    if isinstance(text, Raw):
+        return text
+    return Raw(html.escape(str(text), quote=True))
+
+
+def attribute_name(name: str) -> str:
+    """A Python keyword argument as an HTML attribute name.
+
+    `class_` becomes `class` and `aria_label` becomes `aria-label`, which covers everything
+    the widgets need. The trailing underscore is the escape hatch for the handful of
+    attribute names that are Python keywords.
+    """
+    return name.rstrip("_").replace("_", "-")
+
+
+def element(tag: str, *children: object, **attributes: object) -> Raw:
+    """One element, with its attributes and its children.
+
+    An attribute whose value is `None` or `False` is left out entirely rather than written
+    as the string "None", which is how `disabled=False` ends up disabling a button. An
+    attribute whose value is `True` is written bare, which is what HTML means by a boolean
+    attribute.
+    """
+    parts = []
+    for name, value in attributes.items():
+        if value is None or value is False:
+            continue
+        if value is True:
+            parts.append(f" {attribute_name(name)}")
+        else:
+            parts.append(f' {attribute_name(name)}="{escape(value)}"')
+    opened = f"<{tag}{''.join(parts)}>"
+    if tag in VOID:
+        if children:
+            raise ValueError(f"<{tag}> cannot have children, and was given {len(children)}")
+        return Raw(opened)
+    return Raw(f"{opened}{join(children)}</{tag}>")
+
+
+def join(children: Iterable[object]) -> Raw:
+    """Several children in a row, each escaped unless it is already markup."""
+    return Raw("".join(str(escape(child)) for child in children))
diff --git a/xraywidgets/src/xraywidgets/parts.py b/xraywidgets/src/xraywidgets/parts.py
new file mode 100644
index 0000000..0b23612
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/parts.py
@@ -0,0 +1,102 @@
+"""The bits of markup more than one widget needs, so they only look one way.
+
+There is one rule enforced here rather than remembered, and it is `chip`. Every coloured
+thing in a widget is a chip, and a chip cannot be made without words in it. Colour never
+carries information on its own in this project: not for a reader with any of the common
+kinds of colour blindness, not in a printed handout, and not in a screenshot somebody pasted
+into a chat with the saturation eaten by compression. Making the label a required argument
+is the cheapest way to keep that true, because the alternative is a review comment that has
+to be written every time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pyxray import theme
+
+from .html import Raw, element, join
+from .style import PREFIX
+
+
+def chip(label: str, tone: str = "quiet", *, title: str = "") -> Raw:
+    """A small coloured badge, which always has words in it.
+
+    The tone is checked against the theme rather than pasted into a class name, so a typo is
+    an error here instead of an unstyled grey pill in a notebook.
+    """
+    if not label.strip():
+        raise ValueError("a chip has to have a label, because colour is never the only signal")
+    theme.tone(tone)
+    return element("span", label, class_=f"{PREFIX}-chip {PREFIX}-{tone}", title=title or None)
+
+
+def head(title: str, *notes: object) -> Raw:
+    """The title line, with whatever short remarks belong beside it."""
+    return element(
+        "div",
+        element("span", title, class_=f"{PREFIX}-title"),
+        join(element("span", note, class_=f"{PREFIX}-note") for note in notes),
+        class_=f"{PREFIX}-head",
+    )
+
+
+def source(code: str, *, live: bool = False) -> Raw:
+    """The reader's own code, in the input tone, typed into or just shown back to them.
+
+    A `<textarea>` when the widget is live and a plain block when it is not. Not a `<div>`
+    with `contenteditable`, which looks the same and behaves differently in every browser,
+    and which a screen reader does not announce as somewhere to type.
+    """
+    if live:
+        return element(
+            "textarea",
+            code,
+            class_=f"{PREFIX}-source",
+            data_role="code",
+            spellcheck="false",
+            rows=str(max(code.count("\n") + 1, 2)),
+        )
+    return element("div", code, class_=f"{PREFIX}-source")
+
+
+def error(message: str) -> Raw:
+    """Something did not work, said in the warning tone with the reason in it."""
+    return element("div", message, class_=f"{PREFIX}-error")
+
+
+def toggles(options: Sequence[tuple[str, str, bool]], *, live: bool = False) -> Raw:
+    """The row of on and off buttons above a widget.
+
+    Real `<button>` elements with `aria-pressed`, not styled `<div>`s. That is what makes
+    them reachable by tab and operable by space bar without a line of JavaScript, and it is
+    what a screen reader needs in order to say whether one is on. The static rendering
+    disables them, because a button that looks live and does nothing is worse than one that
+    says it is not.
+    """
+    return element(
+        "div",
+        join(
+            element(
+                "button",
+                label,
+                type="button",
+                class_=f"{PREFIX}-toggle",
+                data_flag=name,
+                aria_pressed="true" if on else "false",
+                disabled=not live,
+            )
+            for name, label, on in options
+        ),
+        class_=f"{PREFIX}-toggles",
+        role="group",
+    )
+
+
+def table(headings: Sequence[str], rows: Sequence[Raw]) -> Raw:
+    """A table with a real header row, so the columns are announced with the cells."""
+    return element(
+        "table",
+        element("thead", element("tr", join(element("th", one, scope="col") for one in headings))),
+        element("tbody", join(rows)),
+    )
diff --git a/xraywidgets/src/xraywidgets/static/disassembler.js b/xraywidgets/src/xraywidgets/static/disassembler.js
new file mode 100644
index 0000000..3efe44c
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/static/disassembler.js
@@ -0,0 +1,88 @@
+// The front end for the disassembler widget.
+//
+// This file draws nothing and decides nothing. Python sends over a `view` object with the
+// finished markup in it, this puts the markup on the page, and it listens for the two things
+// a reader can do: type in the source box and press a toggle. Both of those write a trait,
+// Python recomputes, and a new `view` comes back.
+//
+// It is written this way on purpose. The moment the browser starts working out which opcodes
+// are specialized, there are two answers to that question in the repository, and the one in
+// JavaScript is the one nobody tests. Keeping the logic on one side means the widget you can
+// click and the picture in a rendered notebook are the same picture.
+
+// How long to wait after the last keystroke before asking Python for a new disassembly.
+// Long enough that typing a word does not send a message per letter, short enough that it
+// still feels like the table is following you.
+const SETTLE_MS = 250;
+
+function render(root, model) {
+  const view = model.get("view") || {};
+  root.innerHTML = view.html || "";
+  wireSource(root, model);
+  wireToggles(root, model);
+}
+
+function wireSource(root, model) {
+  const box = root.querySelector('[data-role="code"]');
+  if (!box) return;
+
+  let timer = null;
+  box.addEventListener("input", () => {
+    window.clearTimeout(timer);
+    timer = window.setTimeout(() => {
+      model.set("code", box.value);
+      model.save_changes();
+    }, SETTLE_MS);
+  });
+
+  // Tab indents rather than leaving the box. Python is indented, and a reader who wants to
+  // type a two line function should not have to hunt for the space bar four times.
+  box.addEventListener("keydown", (event) => {
+    if (event.key !== "Tab" || event.shiftKey) return;
+    event.preventDefault();
+    const at = box.selectionStart;
+    box.value = box.value.slice(0, at) + "    " + box.value.slice(box.selectionEnd);
+    box.selectionStart = box.selectionEnd = at + 4;
+    box.dispatchEvent(new Event("input"));
+  });
+}
+
+function wireToggles(root, model) {
+  for (const button of root.querySelectorAll("[data-flag]")) {
+    button.addEventListener("click", () => {
+      const flag = button.dataset.flag;
+      model.set(flag, !model.get(flag));
+      model.save_changes();
+    });
+  }
+}
+
+export default {
+  render({ model, el }) {
+    const root = document.createElement("div");
+    root.className = "xw";
+    root.dataset.widget = "disassembler";
+    el.appendChild(root);
+
+    render(root, model);
+
+    // Only the view is watched. The traits the buttons write are watched by Python, which
+    // sends back a new view, so redrawing on both would draw twice for one click.
+    // Replacing the markup throws the caret away, so where it was is saved first and put
+    // back after. Without this, a box that sends you to the end of the line a quarter of a
+    // second after you stop typing is unusable for anything longer than one line.
+    const redraw = () => {
+      const active = document.activeElement;
+      const typing = active && active.dataset && active.dataset.role === "code";
+      const caret = typing ? active.selectionStart : null;
+      render(root, model);
+      if (caret === null) return;
+      const box = root.querySelector('[data-role="code"]');
+      if (!box) return;
+      box.focus();
+      box.selectionStart = box.selectionEnd = Math.min(caret, box.value.length);
+    };
+    model.on("change:view", redraw);
+    return () => model.off("change:view", redraw);
+  },
+};
diff --git a/xraywidgets/src/xraywidgets/strings.py b/xraywidgets/src/xraywidgets/strings.py
new file mode 100644
index 0000000..151f2be
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/strings.py
@@ -0,0 +1,57 @@
+"""Every word a widget puts on screen, in one file.
+
+Not because a translation is planned, but because one might be, and the cost of collecting
+the strings later is that somebody reads thirty templates looking for text. The cost of
+collecting them now is this file. It is also a useful discipline on its own: a label written
+here, away from the layout, tends to get read as a sentence rather than as a gap in a table.
+
+The keys are dotted and start with the widget they belong to, so that a widget's whole
+vocabulary is one grep. `common.*` is for words shared across widgets, and a word that ends
+up in two widgets should move there rather than being written twice with a comma
+different in one of them.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+STRINGS: dict[str, str] = {
+    # Shared.
+    "common.python": "Python {version}",
+    "common.static_notice": "This is the static picture. Install the live extra and call .live() to click on it.",
+    "common.nothing": "Nothing to show yet.",
+    "common.error": "That did not compile: {reason}",
+    # The disassembler.
+    "disassembler.title": "Bytecode",
+    "disassembler.source": "Source",
+    "disassembler.offset": "Offset",
+    "disassembler.instruction": "Instruction",
+    "disassembler.argument": "Argument",
+    "disassembler.meaning": "What the argument means",
+    "disassembler.depth": "Stack",
+    "disassembler.adaptive": "Specialized opcodes",
+    "disassembler.caches": "Inline caches",
+    "disassembler.depths": "Stack depth",
+    "disassembler.exceptions": "Exception table",
+    "disassembler.cache_row": "{count} cache entries",
+    "disassembler.specialized": "specialized",
+    "disassembler.jump": "jumps to {target}",
+    "disassembler.no_exceptions": "This code has no exception table, which means nothing in it can catch anything.",
+    "disassembler.exception_range": "offsets {start} to {end} jump to {target}, depth {depth}{lasti}",
+    "disassembler.lasti": ", and the instruction that raised is pushed",
+    "disassembler.count": "{count} instructions",
+}
+
+
+def text(key: str, **values: object) -> str:
+    """One string, with its placeholders filled in.
+
+    An unknown key raises, and says what it thinks you meant. A widget asking for a string
+    that is not here is a widget that would otherwise render the key, and a table with
+    `disassembler.ofset` written across the top of a column is a bug that ships.
+    """
+    if key not in STRINGS:
+        close = difflib.get_close_matches(key, STRINGS, n=3)
+        hint = f", did you mean {' or '.join(close)}" if close else ""
+        raise KeyError(f"no string called {key!r}{hint}")
+    return STRINGS[key].format(**values)
diff --git a/xraywidgets/src/xraywidgets/style.py b/xraywidgets/src/xraywidgets/style.py
new file mode 100644
index 0000000..deee17d
--- /dev/null
+++ b/xraywidgets/src/xraywidgets/style.py
@@ -0,0 +1,167 @@
+"""The stylesheet, generated from `pyxray.theme` rather than written next to it.
+
+The palette is decided once, in `pyxray.theme`, and the Excalidraw diagrams, the matplotlib
+charts and the manim animations all read it. A widget that hardcoded `#1971c2` would look
+right on the day it was written and would drift the first time a tone changed, which is
+exactly the failure the theme module exists to prevent. So the colours here are read out of
+the theme and written into CSS custom properties, and everything else in the sheet is
+written against those properties.
+
+Dark mode keeps the tone colours and swaps the neutrals. That is not laziness. The tones
+are pale fills with dark strokes, and they read as chips sitting on the page rather than as
+page colour, so they work against either background as long as the text on them stays dark.
+Recolouring six tones for a second theme would mean six more decisions and a second palette
+to keep in step with the diagrams, which cannot follow it, because an SVG committed to the
+repository has one set of colours in it.
+"""
+
+from __future__ import annotations
+
+from pyxray import theme
+
+#: The prefix on every class name and custom property this package emits. Widgets get
+#: dropped into notebooks next to other people's CSS, and two letters is cheap insurance.
+PREFIX = "xw"
+
+
+def variables() -> str:
+    """The palette as CSS custom properties, one block, read from the theme."""
+    lines = [
+        f"  --{PREFIX}-ink: {theme.INK};",
+        f"  --{PREFIX}-muted: {theme.MUTED};",
+        f"  --{PREFIX}-line: {theme.LINE};",
+        f"  --{PREFIX}-paper: {theme.PAPER};",
+        f"  --{PREFIX}-sans: {theme.SANS};",
+        f"  --{PREFIX}-mono: {theme.MONO};",
+    ]
+    for name, tone in theme.TONES.items():
+        lines.append(f"  --{PREFIX}-{name}-stroke: {tone.stroke};")
+        lines.append(f"  --{PREFIX}-{name}-fill: {tone.fill};")
+    return "\n".join(lines)
+
+
+#: The layout half of the sheet, which has no colours in it, only references to the
+#: properties above. Kept as one string rather than assembled, because CSS read as CSS is
+#: easier to check than CSS read as a list of Python strings.
+LAYOUT = f"""
+.{PREFIX} {{
+  font-family: var(--{PREFIX}-sans);
+  color: var(--{PREFIX}-ink);
+  background: var(--{PREFIX}-paper);
+  border: 1px solid var(--{PREFIX}-line);
+  border-radius: 12px;
+  padding: 16px;
+  line-height: 1.4;
+  font-size: 14px;
+}}
+.{PREFIX} * {{ box-sizing: border-box; }}
+.{PREFIX}-head {{
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  flex-wrap: wrap;
+  margin-bottom: 12px;
+}}
+.{PREFIX}-title {{ font-weight: 700; font-size: 16px; }}
+.{PREFIX}-note {{ color: var(--{PREFIX}-muted); font-size: 12px; }}
+.{PREFIX}-source {{
+  font-family: var(--{PREFIX}-mono);
+  white-space: pre;
+  overflow-x: auto;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid var(--{PREFIX}-input-stroke);
+  background: var(--{PREFIX}-input-fill);
+  color: {theme.INK};
+  margin-bottom: 12px;
+}}
+textarea.{PREFIX}-source {{
+  display: block;
+  width: 100%;
+  resize: vertical;
+  font-size: 13px;
+  line-height: 1.5;
+}}
+.{PREFIX}-source:focus-visible {{
+  outline: 2px solid var(--{PREFIX}-focus-stroke);
+  outline-offset: 1px;
+}}
+.{PREFIX}-toggles {{ display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; }}
+.{PREFIX}-toggle {{
+  font: inherit;
+  font-size: 12px;
+  cursor: pointer;
+  padding: 4px 10px;
+  border-radius: 999px;
+  border: 1px solid var(--{PREFIX}-line);
+  background: transparent;
+  color: inherit;
+}}
+.{PREFIX}-toggle[aria-pressed="true"] {{
+  border-color: var(--{PREFIX}-focus-stroke);
+  background: var(--{PREFIX}-focus-fill);
+  color: {theme.INK};
+  font-weight: 700;
+}}
+.{PREFIX}-toggle:focus-visible {{
+  outline: 2px solid var(--{PREFIX}-focus-stroke);
+  outline-offset: 2px;
+}}
+.{PREFIX}-toggle[disabled] {{ cursor: default; opacity: 0.75; }}
+.{PREFIX} table {{ border-collapse: collapse; width: 100%; font-size: 13px; }}
+.{PREFIX} th {{
+  text-align: left;
+  font-weight: 700;
+  color: var(--{PREFIX}-muted);
+  border-bottom: 1px solid var(--{PREFIX}-line);
+  padding: 4px 8px 6px 0;
+  white-space: nowrap;
+}}
+.{PREFIX} td {{ padding: 3px 8px 3px 0; vertical-align: top; }}
+.{PREFIX} td.{PREFIX}-mono {{ font-family: var(--{PREFIX}-mono); white-space: nowrap; }}
+.{PREFIX} tr.{PREFIX}-cache td {{ color: var(--{PREFIX}-muted); font-size: 12px; }}
+.{PREFIX}-chip {{
+  display: inline-block;
+  font-size: 11px;
+  font-family: var(--{PREFIX}-sans);
+  padding: 1px 7px;
+  border-radius: 999px;
+  border: 1px solid currentColor;
+  white-space: nowrap;
+}}
+.{PREFIX}-error {{
+  border: 1px solid var(--{PREFIX}-warning-stroke);
+  background: var(--{PREFIX}-warning-fill);
+  color: {theme.INK};
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-family: var(--{PREFIX}-mono);
+  font-size: 12px;
+}}
+"""
+
+#: One rule per tone, so a chip picks its colours by class name. Written as a loop because
+#: six near identical CSS blocks written out by hand are six chances to paste the wrong hue.
+TONE_RULES = "\n".join(
+    f".{PREFIX}-{name} {{ color: var(--{PREFIX}-{name}-stroke); "
+    f"background: var(--{PREFIX}-{name}-fill); }}"
+    for name in theme.TONES
+)
+
+#: Dark mode. Only the neutrals move: the page goes dark and the text goes light, and the
+#: tone chips keep their own colours because they carry their own background with them.
+DARK = f"""
+@media (prefers-color-scheme: dark) {{
+  .{PREFIX} {{
+    --{PREFIX}-ink: #e9ecef;
+    --{PREFIX}-muted: #adb5bd;
+    --{PREFIX}-line: #495057;
+    --{PREFIX}-paper: #1a1b1e;
+  }}
+}}
+"""
+
+
+def stylesheet() -> str:
+    """The whole sheet, ready to drop into a `<style>` tag or hand to anywidget."""
+    return f".{PREFIX} {{\n{variables()}\n}}\n{LAYOUT}\n{TONE_RULES}\n{DARK}"
diff --git a/xraywidgets/tests/test_xraywidgets_base.py b/xraywidgets/tests/test_xraywidgets_base.py
new file mode 100644
index 0000000..2c0f6bb
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_base.py
@@ -0,0 +1,75 @@
+"""What every widget promises: it renders with nothing installed, and it says so."""
+
+from __future__ import annotations
+
+import pytest
+
+from xraywidgets.base import STATIC, Widget
+from xraywidgets.html import Raw, element
+from xraywidgets.style import PREFIX
+
+
+class Toy(Widget):
+    """A widget with one number in it, for testing the parts that are not any one widget."""
+
+    slug = "toy"
+
+    def state(self) -> dict[str, object]:
+        return {"answer": 42}
+
+    def markup(self, state: dict[str, object], *, live: bool = False) -> Raw:
+        return element("p", state["answer"], class_="live" if live else "still")
+
+
+def test_a_widget_renders_to_html_with_nothing_installed():
+    assert "42" in Toy().render()
+
+
+def test_the_stylesheet_travels_with_the_widget():
+    assert "<style>" in Toy().render()
+
+
+def test_the_outer_element_says_which_widget_it_is():
+    assert 'data-widget="toy"' in Toy().render()
+
+
+def test_the_outer_element_carries_the_prefix_class():
+    assert f'class="{PREFIX}"' in Toy().render()
+
+
+def test_jupyter_gets_the_still_picture():
+    assert Toy()._repr_html_() == Toy().render()
+
+
+def test_the_still_picture_is_the_one_with_the_controls_off():
+    assert 'class="still"' in Toy().render()
+
+
+def test_the_view_carries_the_state_and_the_markup_for_the_live_one():
+    view = Toy().view()
+    assert view["answer"] == 42
+    assert view["html"] == '<p class="live">42</p>'
+
+
+def test_a_widget_with_no_front_end_file_says_which_file_is_missing():
+    with pytest.raises(FileNotFoundError, match=r"toy\.js"):
+        Toy.esm()
+
+
+def test_the_widgets_that_do_have_a_front_end_file_can_read_it():
+    for path in STATIC.glob("*.js"):
+        assert path.read_text(encoding="utf-8").strip()
+
+
+def test_the_base_class_makes_a_subclass_say_what_it_shows():
+    class Empty(Widget):
+        slug = "empty"
+
+    with pytest.raises(NotImplementedError):
+        Empty().state()
+    with pytest.raises(NotImplementedError):
+        Empty().markup({})
+
+
+def test_the_notice_tells_a_reader_where_the_moving_version_is():
+    assert ".live()" in str(Toy().notice())
diff --git a/xraywidgets/tests/test_xraywidgets_disassembler.py b/xraywidgets/tests/test_xraywidgets_disassembler.py
new file mode 100644
index 0000000..5617c72
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_disassembler.py
@@ -0,0 +1,197 @@
+"""The disassembler widget, checked against `dis` rather than against itself.
+
+The point of most of these is agreement. The widget is only worth having if a reader can put
+`dis.dis` next to it and see the same thing, so the tests compare the two directly instead of
+freezing whatever the widget happens to print today.
+"""
+
+from __future__ import annotations
+
+import dis
+import re
+import sys
+
+import pytest
+
+from pyxray import bytecode
+from xraywidgets import Disassembler
+from xraywidgets.disassembler import FLAGS
+
+#: A `try` with two arms, so there is a real exception table to look at.
+GUARDED = """
+try:
+    risky()
+except ValueError:
+    handled()
+finally:
+    always()
+"""
+
+
+def opnames(widget: Disassembler) -> list[str]:
+    return [one["opname"] for one in widget.state()["rows"] if one["kind"] == "instruction"]
+
+
+def test_the_instructions_are_the_ones_dis_gives():
+    code = "total = sum(values)"
+    assert opnames(Disassembler(code)) == [one.opname for one in dis.get_instructions(code)]
+
+
+def test_a_widget_with_no_toggles_on_has_one_row_per_instruction():
+    widget = Disassembler("total = sum(values)")
+    assert all(one["kind"] == "instruction" for one in widget.state()["rows"])
+
+
+def test_the_cache_rows_count_the_bytes_dis_hides():
+    widget = Disassembler("total = sum(values)", caches=True)
+    caches = [one for one in widget.state()["rows"] if one["kind"] == "cache"]
+    expected = [one.caches for one in bytecode.disassemble("total = sum(values)") if one.caches]
+    assert [one["bytes"] // 2 for one in caches] == expected
+
+
+def test_turning_caches_on_does_not_change_the_instructions():
+    code = "total = sum(values)"
+    assert opnames(Disassembler(code)) == opnames(Disassembler(code, caches=True))
+
+
+def test_the_stack_column_only_exists_when_it_is_turned_on():
+    column = '<th scope="col">Stack</th>'
+    assert column not in Disassembler("x = 1").render()
+    assert column in Disassembler("x = 1", depths=True).render()
+
+
+def test_the_stack_heights_are_the_ones_pyxray_walked():
+    from pyxray import stack
+
+    code = "total = sum(values)"
+    widget = Disassembler(code, depths=True)
+    walked = {one.offset: (one.before, one.after) for one in stack.walk(code)}
+    for row in widget.state()["rows"]:
+        if row["offset"] in walked:
+            assert (row["before"], row["after"]) == walked[row["offset"]]
+
+
+def test_an_instruction_the_walk_never_reached_gets_a_dash_and_not_a_zero():
+    widget = Disassembler("x = 1", depths=True)
+    assert widget.depth({"before": None, "after": None}) == "-"
+
+
+def test_the_exception_table_is_the_one_the_code_object_carries():
+    widget = Disassembler(GUARDED, exceptions=True)
+    assert len(widget.state()["handlers"]) == len(bytecode.exception_table(GUARDED))
+    assert widget.state()["handlers"][0]["start"] == bytecode.exception_table(GUARDED)[0].start
+
+
+def test_the_exception_table_is_left_out_until_it_is_asked_for():
+    assert Disassembler(GUARDED).state()["handlers"] == []
+
+
+def test_code_that_cannot_raise_says_so_rather_than_showing_an_empty_list():
+    markup = Disassembler("x = 1", exceptions=True).render()
+    assert "no exception table" in markup
+
+
+def test_a_handler_is_described_as_a_sentence_and_not_five_numbers():
+    handler = Disassembler(GUARDED, exceptions=True).state()["handlers"][0]
+    assert "jump to" in handler["text"]
+    assert str(handler["target"]) in handler["text"]
+
+
+def test_broken_code_is_a_message_and_not_a_traceback():
+    widget = Disassembler("def (")
+    assert "did not compile" in widget.state()["error"]
+    assert widget.state()["rows"] == []
+    assert "did not compile" in widget.render()
+
+
+def test_broken_code_still_shows_the_toggles_so_the_widget_does_not_vanish():
+    markup = Disassembler("def (").render()
+    for name, _ in FLAGS:
+        assert f'data-flag="{name}"' in markup
+
+
+def test_the_source_the_reader_typed_is_shown_back_escaped():
+    assert "&lt;" in Disassembler("ok = 1 < 2").render()
+    assert "<script" not in Disassembler("<script>alert(1)</script>").render()
+
+
+def test_the_version_is_written_next_to_the_table():
+    assert ".".join(str(part) for part in sys.version_info[:3]) in Disassembler("x = 1").render()
+
+
+def test_every_flag_is_a_field_you_can_set_in_the_constructor():
+    widget = Disassembler("x = 1", **{name: True for name, _ in FLAGS})
+    assert all(one["on"] for one in widget.state()["flags"])
+
+
+def test_the_toggles_come_back_in_the_order_they_are_listed():
+    names = [one["name"] for one in Disassembler("x = 1").state()["flags"]]
+    assert names == [name for name, _ in FLAGS]
+
+
+def test_a_specialized_opcode_is_labelled_with_a_word_and_not_only_a_colour():
+    def warm(values):
+        return sum(values)
+
+    for _ in range(200):
+        warm([1, 2, 3])
+    widget = Disassembler(warm.__code__, adaptive=True)
+    if not any(one["specialized"] for one in widget.state()["rows"]):
+        pytest.skip("this build did not specialize anything in that loop")
+    assert "specialized" in widget.render()
+
+
+def test_the_widget_takes_a_function_and_not_only_a_string():
+    def add(left, right):
+        return left + right
+
+    assert "BINARY_OP" in opnames(Disassembler(add))
+
+
+def test_a_jump_says_where_it_goes():
+    widget = Disassembler("x = 1 if flag else 2")
+    jumps = [one for one in widget.state()["rows"] if one["jump_target"] is not None]
+    assert jumps
+    assert f"jumps to {jumps[0]['jump_target']}" in widget.render()
+
+
+def test_the_still_picture_has_its_buttons_switched_off():
+    assert "disabled" in Disassembler("x = 1").render()
+
+
+def test_the_live_markup_has_them_switched_on_and_somewhere_to_type():
+    html = Disassembler("x = 1").view()["html"]
+    assert "disabled" not in html
+    assert 'data-role="code"' in html
+
+
+def test_the_live_markup_drops_the_line_about_being_static():
+    assert ".live()" not in Disassembler("x = 1").view()["html"]
+
+
+def test_the_front_end_module_reads_the_traits_python_actually_syncs():
+    module = Disassembler.esm()
+    for name, _ in FLAGS:
+        assert name in module or "data-flag" in module
+    assert "change:view" in module
+
+
+def test_the_front_end_module_works_out_no_bytecode_of_its_own():
+    """No opcode name appears in the JavaScript, in a rule or in a table or anywhere else.
+
+    This is the one that keeps the promise in the module docstring honest. The day somebody
+    adds `if (op.startsWith("LOAD"))` to the front end there are two implementations of what
+    a disassembly means, and only one of them is tested.
+    """
+    module = Disassembler.esm()
+    named = {one for one in re.findall(r"\b[A-Z][A-Z_]{3,}\b", module)}
+    assert named & set(dis.opmap) == set()
+
+
+def test_the_headings_line_up_with_the_cells():
+    for depths in (False, True):
+        widget = Disassembler("total = sum(values)", depths=depths)
+        markup = str(widget.markup(widget.state()))
+        body = markup.split("<tbody>")[1]
+        for row in re.findall(r"<tr>(.*?)</tr>", body):
+            assert row.count("<td") == len(widget.headings())
diff --git a/xraywidgets/tests/test_xraywidgets_html.py b/xraywidgets/tests/test_xraywidgets_html.py
new file mode 100644
index 0000000..e6687a9
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_html.py
@@ -0,0 +1,72 @@
+"""The escaping and the attribute rules, which is the part that has to be right."""
+
+from __future__ import annotations
+
+import pytest
+
+from xraywidgets.html import Raw, element, escape, join, raw
+
+
+def test_text_is_escaped():
+    assert str(element("p", "<script>alert(1)</script>")) == (
+        "<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>"
+    )
+
+
+def test_quotes_are_escaped_in_attributes_too():
+    assert 'title="a &quot;quoted&quot; word"' in str(element("p", "x", title='a "quoted" word'))
+
+
+def test_raw_is_not_escaped_twice():
+    inner = element("b", "6 < 7")
+    assert str(element("p", inner)) == "<p><b>6 &lt; 7</b></p>"
+
+
+def test_raw_lets_a_caller_pass_markup_through():
+    assert (
+        str(element("style", raw("a > b { color: red }"))) == "<style>a > b { color: red }</style>"
+    )
+
+
+def test_a_trailing_underscore_is_taken_off_the_attribute_name():
+    assert 'class="x"' in str(element("p", "text", class_="x"))
+
+
+def test_underscores_become_hyphens():
+    markup = str(element("p", "text", data_flag="caches", aria_label="a label"))
+    assert 'data-flag="caches"' in markup
+    assert 'aria-label="a label"' in markup
+
+
+def test_none_and_false_attributes_are_left_out():
+    assert str(element("p", "text", title=None, hidden=False)) == "<p>text</p>"
+
+
+def test_true_is_written_bare():
+    assert str(element("button", "press", disabled=True)) == "<button disabled>press</button>"
+
+
+def test_void_tags_close_themselves():
+    assert str(element("br")) == "<br>"
+
+
+def test_a_void_tag_with_children_is_a_mistake():
+    with pytest.raises(ValueError, match="br"):
+        element("br", "text")
+
+
+def test_join_keeps_the_pieces_in_order():
+    assert str(join(["a", element("b", "c")])) == "a<b>c</b>"
+
+
+def test_join_escapes_plain_strings():
+    assert str(join(["<"])) == "&lt;"
+
+
+def test_escape_leaves_ordinary_text_alone():
+    assert escape("plain words") == "plain words"
+
+
+def test_raw_is_a_string_so_it_can_go_anywhere_a_string_can():
+    assert isinstance(raw("x"), Raw)
+    assert isinstance(raw("x"), str)
diff --git a/xraywidgets/tests/test_xraywidgets_live.py b/xraywidgets/tests/test_xraywidgets_live.py
new file mode 100644
index 0000000..f3a9617
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_live.py
@@ -0,0 +1,79 @@
+"""The half that needs anywidget, which is the half most likely to rot quietly.
+
+Everything else in this package works with nothing installed, so it is exercised by every
+run. This file is the only place the live path is touched at all, which is why CI installs
+the extra rather than leaving it to whoever happens to have anywidget on their machine.
+
+The tests here are all the same shape: change a trait the way a click would, and check that
+what comes back is what Python would have computed on its own. Nothing here opens a browser,
+because the thing worth testing is that the browser is not being asked to decide anything.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from xraywidgets import Disassembler
+
+pytest.importorskip("anywidget", reason="the live version needs the `live` extra")
+
+
+@pytest.fixture
+def live():
+    return Disassembler("total = sum(values)").live()
+
+
+def test_the_live_widget_starts_showing_what_the_static_one_shows(live):
+    assert live.view["html"] == Disassembler("total = sum(values)").view()["html"]
+
+
+def test_every_toggle_is_a_trait_the_front_end_can_write(live):
+    for name in ("adaptive", "caches", "depths", "exceptions"):
+        assert live.has_trait(name)
+
+
+def test_turning_a_toggle_on_gets_a_new_picture_back(live):
+    before = live.view["html"]
+    live.caches = True
+    assert live.view["html"] != before
+    assert live.view["html"] == Disassembler("total = sum(values)", caches=True).view()["html"]
+
+
+def test_turning_a_toggle_back_off_gets_the_first_picture_back(live):
+    first = live.view["html"]
+    live.depths = True
+    live.depths = False
+    assert live.view["html"] == first
+
+
+def test_typing_new_code_recomputes_the_rows(live):
+    live.code = "x = 1"
+    assert [one["opname"] for one in live.view["rows"]] == [
+        one["opname"] for one in Disassembler("x = 1").state()["rows"]
+    ]
+
+
+def test_typing_half_a_line_shows_a_message_and_keeps_the_widget_on_screen(live):
+    live.code = "def ("
+    assert "did not compile" in live.view["error"]
+    assert 'data-flag="caches"' in live.view["html"]
+
+
+def test_typing_the_rest_of_the_line_brings_the_table_back(live):
+    live.code = "def ("
+    live.code = "def f(): pass"
+    assert live.view["error"] == ""
+    assert live.view["rows"]
+
+
+def test_the_live_picture_has_working_buttons_and_somewhere_to_type(live):
+    assert "disabled" not in live.view["html"]
+    assert 'data-role="code"' in live.view["html"]
+
+
+def test_the_stylesheet_goes_over_with_it(live):
+    assert "--xw-ink" in live._css
+
+
+def test_the_front_end_module_goes_over_with_it(live):
+    assert "export default" in live._esm
diff --git a/xraywidgets/tests/test_xraywidgets_parts.py b/xraywidgets/tests/test_xraywidgets_parts.py
new file mode 100644
index 0000000..646b0a1
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_parts.py
@@ -0,0 +1,80 @@
+"""The shared markup, and the one rule it enforces: colour never speaks on its own."""
+
+from __future__ import annotations
+
+import pytest
+
+from xraywidgets.parts import chip, error, head, source, table, toggles
+from xraywidgets.style import PREFIX
+
+
+def test_a_chip_carries_its_words():
+    assert ">specialized<" in str(chip("specialized", "focus"))
+
+
+def test_a_chip_without_words_is_refused():
+    with pytest.raises(ValueError, match="colour is never the only signal"):
+        chip("   ", "focus")
+
+
+def test_an_unknown_tone_is_refused_here_rather_than_showing_up_grey():
+    with pytest.raises(KeyError):
+        chip("words", "chartreuse")
+
+
+def test_a_chip_names_its_tone_in_a_class():
+    assert f"{PREFIX}-warning" in str(chip("careful", "warning"))
+
+
+def test_a_title_is_left_off_when_there_is_none():
+    assert "title=" not in str(chip("words"))
+
+
+def test_the_source_is_a_box_when_it_is_not_live():
+    markup = str(source("x = 1"))
+    assert markup.startswith("<div")
+    assert "textarea" not in markup
+
+
+def test_the_source_is_something_you_can_type_in_when_it_is_live():
+    markup = str(source("x = 1", live=True))
+    assert markup.startswith("<textarea")
+    assert 'data-role="code"' in markup
+
+
+def test_the_source_box_grows_with_the_code():
+    assert 'rows="4"' in str(source("a\nb\nc\nd", live=True))
+
+
+def test_source_code_is_escaped():
+    assert "&lt;" in str(source("x = 1 < 2", live=True))
+
+
+def test_toggles_are_real_buttons_that_say_whether_they_are_on():
+    markup = str(toggles([("caches", "Inline caches", True)], live=True))
+    assert 'type="button"' in markup
+    assert 'aria-pressed="true"' in markup
+    assert 'data-flag="caches"' in markup
+
+
+def test_a_static_toggle_says_it_does_not_work():
+    assert "disabled" in str(toggles([("caches", "Inline caches", False)]))
+
+
+def test_a_live_toggle_does_not_say_that():
+    assert "disabled" not in str(toggles([("caches", "Inline caches", False)], live=True))
+
+
+def test_the_table_has_a_real_header_row():
+    markup = str(table(["Offset", "Instruction"], []))
+    assert "<thead>" in markup
+    assert 'scope="col"' in markup
+
+
+def test_the_head_puts_the_notes_after_the_title():
+    markup = str(head("Bytecode", "Python 3.15.0", "9 instructions"))
+    assert markup.index("Bytecode") < markup.index("Python") < markup.index("9 instructions")
+
+
+def test_an_error_says_what_went_wrong():
+    assert "invalid syntax" in str(error("That did not compile: invalid syntax"))
diff --git a/xraywidgets/tests/test_xraywidgets_strings.py b/xraywidgets/tests/test_xraywidgets_strings.py
new file mode 100644
index 0000000..112bf2a
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_strings.py
@@ -0,0 +1,50 @@
+"""Every word on screen comes from one file, and this checks the file is usable."""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from xraywidgets.strings import STRINGS, text
+
+#: The placeholders in a string, so a caller can be checked against them.
+SLOT = re.compile(r"\{(\w+)\}")
+
+
+def test_a_string_comes_back_with_its_slots_filled():
+    assert text("common.python", version="3.15.0") == "Python 3.15.0"
+
+
+def test_an_unknown_key_raises_rather_than_rendering_the_key():
+    with pytest.raises(KeyError, match="no string called"):
+        text("disassembler.nothing_like_this_at_all")
+
+
+def test_a_near_miss_gets_told_what_it_probably_meant():
+    with pytest.raises(KeyError, match=r"disassembler\.offset"):
+        text("disassembler.ofset")
+
+
+def test_every_key_is_dotted_and_starts_with_something_that_owns_it():
+    for key in STRINGS:
+        owner, _, rest = key.partition(".")
+        assert rest, key
+        assert owner in {"common", "disassembler"}, key
+
+
+def test_no_string_has_a_dash_that_should_have_been_a_hyphen():
+    for key, value in STRINGS.items():
+        assert "\u2014" not in value, key
+        assert "\u2013" not in value, key
+
+
+def test_no_string_has_a_newline_in_the_middle_of_it():
+    for key, value in STRINGS.items():
+        assert "\n" not in value, key
+
+
+def test_every_string_can_be_formatted_with_its_own_placeholders():
+    for key, value in STRINGS.items():
+        filled = text(key, **{name: 0 for name in SLOT.findall(value)})
+        assert "{" not in filled, key
diff --git a/xraywidgets/tests/test_xraywidgets_style.py b/xraywidgets/tests/test_xraywidgets_style.py
new file mode 100644
index 0000000..bf04bd1
--- /dev/null
+++ b/xraywidgets/tests/test_xraywidgets_style.py
@@ -0,0 +1,52 @@
+"""The stylesheet, and the reason it is generated: no colour is written twice.
+
+The test that matters here is the last one. It reads the sheet looking for hex colours that
+are not inside a custom property definition, which is what stops somebody pasting a nice
+blue into a rule six months from now and quietly forking the palette away from the diagrams.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pyxray import theme
+from xraywidgets.style import DARK, LAYOUT, PREFIX, TONE_RULES, stylesheet
+
+#: Any hex colour, so the sheet can be checked for ones written by hand.
+COLOUR = re.compile(r"#[0-9a-fA-F]{3,8}\b")
+
+
+def test_every_tone_in_the_theme_has_a_rule():
+    for name in theme.TONES:
+        assert f".{PREFIX}-{name} {{" in TONE_RULES
+
+
+def test_the_palette_is_read_from_the_theme():
+    sheet = stylesheet()
+    assert f"--{PREFIX}-ink: {theme.INK};" in sheet
+    assert f"--{PREFIX}-focus-stroke: {theme.TONES['focus'].stroke};" in sheet
+
+
+def test_dark_mode_only_moves_the_neutrals():
+    for name in theme.TONES:
+        assert f"--{PREFIX}-{name}-stroke" not in DARK
+
+
+def test_dark_mode_swaps_the_page_and_the_text():
+    assert f"--{PREFIX}-paper:" in DARK
+    assert f"--{PREFIX}-ink:" in DARK
+
+
+def test_the_layout_half_writes_its_colours_as_properties():
+    written = [one for one in COLOUR.findall(LAYOUT) if one != theme.INK]
+    assert written == []
+
+
+def test_the_sheet_names_everything_after_the_package():
+    for rule in re.findall(r"^\.[a-z-]+", stylesheet(), flags=re.MULTILINE):
+        assert rule.startswith(f".{PREFIX}")
+
+
+def test_the_sheet_is_valid_enough_to_have_balanced_braces():
+    sheet = stylesheet()
+    assert sheet.count("{") == sheet.count("}")