Code cells nested in a directive are never registered with the kernel, so they render a run button that does nothing

[mmcky]

A code cell inside any directive — {exercise}, {solution}, {note} — renders with run controls but is never registered with the kernel. Clicking gives no output and no error, and any later cell depending on it raises NameError.

Found while debugging QuantEcon/lecture-wasm#64, where it makes the short_path exercise impossible to complete in the browser.

Root cause

@myst-theme/jupyter/dist/execute/utils.js (this repo depends on @myst-theme/jupyter: ^1.3.0):

export function executableNodesFromBlock(block) {
    if (!block || block.type !== 'block') return;
    let target = block;
    if (block.children?.length === 1 && block.children[0].type === 'container') target = block.children[0];
    if (target.children?.length >= 2 && target.children[0].type === 'code') {
        return { codeCell: target.children[0], output: target.children[1] };
    }
}

notebook.cells = mdast.children.map((block) => { ... executableNodesFromBlock(block) ... });

Two things combine:

1. notebook.cells = mdast.children.map(...) walks only the root's direct children — no recursion.
2. executableNodesFromBlock requires the code node to be children[0] of a top-level block, with a single special case for a lone container (the figure path).

A cell inside an exercise sits at root > block > exercise > block > code. The outer block's children[0] is the exercise node, so the check fails and the cell never enters notebook.cells.

Rendering and execution-registration are separate paths, which is why the cell still draws a ▶ button. That is the part that makes this expensive to diagnose.

This is not a directive bug

myst-ext-exercise is behaving correctly: it nests the body under the exercise node, which is semantically right, and exercise-start is literally alias: ["exercise"] in the directive spec. The gated -start/-end form is a parsing convenience for content that cannot be indented — it was never a hoist. Changing that would break cross-referencing and numbering, so the fix belongs here in the execution layer.

Reproduction

Six cells in one page, each appending a marker to a list, with a top-level REPORT cell printing what actually ran. Measured on a live preview:

EXECUTED : ['A_toplevel_setup', 'C_toplevel_after_magic']
MISSING  : ['D_in_gated_exercise', 'E_in_gated_solution', 'F_in_note']
%%file worked at top level: True

Position	Ran?
top level	✅
top level, %%file magic	✅ (proves magics and the FS are fine)
gated {exercise-start}	❌
gated {solution-start}	❌
plain {note}	❌

Full probe page and method: QuantEcon/lecture-wasm#65.

The marker-and-report pattern is the important part of that reproduction. A stranded cell produces no output and no error — and for an assignment cell, no output is also the correct result. The two are indistinguishable by eye, which is why this was misdiagnosed twice as a %%file problem before the pattern was used.

Suggested fix

Make cell collection recurse into container children so any block holding a code node is registered regardless of depth. Two constraints:

• Preserve document order — notebook.cells order determines execution sequence, so a recursive walk must be depth-first in document order, not appended.
• Keep the existing figure special-case working (block > container > code).

Why this repo can ship it before upstream

This repo already uses patch-package — "postinstall": "patch-package --patch-dir patches", with existing patches for @jupyter-widgets/controls and jupyterlab-plotly. A third patch against @myst-theme/jupyter would land in the theme build immediately, and the same diff is the upstream PR to jupyter-book/myst-theme.

I searched jupyter-book/myst-theme, jupyter-book/mystmd and jupyter-book/thebe and found no existing report, though those searches were not exhaustive.

Impact today

Small, but not zero. An audit of all 42 published pages of lecture-wasm — walking every ancestor type that wraps an executable cell, not a guessed list — found exactly two stranded cells on one page (short_path, both inside {exercise-start}). Every page is kind: Notebook, so no kernelspec problems.

The reason it matters beyond that count is that the failure is silent and invisible to CI: lecture-wasm's ci.yml runs myst build --html with no execution, so a stranded cell builds green and only fails for a reader. Any lecture author who puts a code cell inside an admonition or exercise gets a page that looks correct and cannot be run.

Worth noting one trap for whoever fixes short_path in the meantime: its solution cells currently do run, but only because a malformed ```{solution} closer leaves that directive unbalanced and spills its content to root level. Correcting that directive without also moving cells out would take the page from one stranded cell to six — confirmed by the probe, where a correctly gated {solution-start} cell does not run.

[mmcky]

Update from the consumer side: lecture-wasm's one affected page has been worked around, so nothing there is blocked on this — but the workaround is fragile in a way worth knowing before prioritising.

QuantEcon/lecture-wasm#63 moved short_path's data cell out of {exercise-start} to top level. Live site now reports 9 cells, 0 stranded, and the lecture is completable in the browser for the first time.

That only worked because the rest of the page was already at top level by accident. short_path.md:480 is a bare ```{solution} closer that mystmd rejects, leaving the directive unbalanced and spilling its five solution cells to root level. Fixing that directive to the gated pair — an obviously correct tidy-up — re-nests them and takes the page from 0 stranded cells to 5. So the repo is currently one plausible cleanup commit away from re-breaking, and a comment in the source is all that prevents it.

That is the general shape of the risk this issue covers: the failure is silent, and correctness-improving edits can cause it. A stranded cell renders a run button, produces no error and no output, and lecture-wasm's CI runs myst build --html with no execution, so nothing catches it.

An audit of all 42 published lecture-wasm pages found only that one page affected, so the immediate blast radius is small. The exposure is prospective: any author who puts a code cell inside an admonition, exercise or solution gets a page that looks right, builds green, and cannot be run.

QuantEcon/lecture-wasm#65 is a throwaway draft carrying the six-position probe used to characterise this. It is kept open deliberately as the regression test for whatever fix lands here — run it, and the REPORT cell names any position that still fails.

[mmcky]

Independent confirmation from the QuantEcon/workspace-lectures#37 validation (2026-08-12, real Chromium driving the live lecture-wasm site and the QuantEcon/lecture-wasm#65 probe preview), with one build-dependence nuance worth recording on this issue.

Mechanism confirmed at source: @myst-theme/jupyter@1.3.0 (the version this theme's v2.1.0 lockfile resolves, shipped unpatched) builds the page notebook from mdast.children only — notebookFromMdast at dist/execute/utils.js:40 — and executableNodesFromBlock (lines 4–14) returns a code cell only when the block's direct children[0].type === 'code' (or via exactly one container wrapper). A cell nested inside any directive is therefore never registered with the kernel.

Behavior confirmed in-browser on the lecture-wasm#65 probe preview: run-all leaves the nested cells unexecuted (probe REPORT: MISSING: ['D_in_gated_exercise', 'E_in_gated_solution', 'F_in_note'] while top-level cells ran), and clicking a nested cell's run button executes nothing — no output, kernel-side ran-list unchanged, and one console error per click: no cell found on execute {pageSlug: undefined, notebookSlug: undefined, cellId: undefined}.

The nuance: the dead-button symptom is build-dependent. Today's live lecture-wasm build omits the run button on nested cells entirely (verified on lln-clt: 14 code cells, 13 run buttons — the buttonless one is exactly the nested cell), while the newer build on the #65 preview renders the clickable-but-inert button this issue describes. So for lecture-wasm the dead affordance is currently preview-only and arrives with the next theme/build refresh.

Scale if it ships: 42 nested code blocks across 20 of the 41 published lecture-wasm pages (counted twice independently — a rendered-DOM crawl of every toc page and a separate SSR-HTML parse, agreeing).

[mmcky]

Escalation (2026-08-20 tracker audit): the build-dependence nuance above has now resolved in the bad direction — the exposure is live-pending-rebuild.

lecture-wasm was repointed to the v2.3.0 theme release today (lecture-wasm#67, lectures/myst.yml now pins the v2.3.0 zip). Per the 2026-08-12 validation above, builds on the newer theme render the clickable-but-inert run button on nested cells — so the next lecture-wasm site rebuild ships the dead affordance on the 42 nested code blocks across 20 of the 41 published pages, on a site where live compute is enabled and readers will click them.

This was a prospective risk when filed; it is now the top correctness item in the tracker. Two routes, not mutually exclusive: a patch-package entry on @myst-theme/jupyter's executableNodesFromBlock (fast; patches/ already carries two such patches), and an upstream PR to jupyter-book/myst-theme (right long-term). Either way, the lecture-wasm#65 probe remains the regression test: run it and the REPORT cell names any position that still fails.

[mmcky]

Status escalation, second notch: with the #93 scope resolution (2026-08-24, PR #145) making the lecture-series migration all-or-nothing once parity is complete, this defect is now a formal cutover blocker alongside Phases 3–6 (#89–#92) — it is shipped Phase 2 surface that is broken in a user-visible way, and the highest-priority open bug in the tracker.