Skip to content

Show the prose readers were missing, fix the run loop, and stop loading third-party scripts - #44

Merged
adewale merged 14 commits into
mainfrom
claude/funny-thompson-k7lta5
Nov 14, 2026
Merged

adewale merged 14 commits into
mainfrom
claude/funny-thompson-k7lta5

Conversation

@adewale

@adewale adewale commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

This branch fixes the findings of an independent whole-project review: things a reader or crawler hits that no existing gate measured.

Reader-facing

  • Intro paragraphs render. Every example opens with 2–3 paragraphs that the loader parsed and the template dropped: 8,823 words, more than all the cell prose. They now render under the summary and are part of search.
  • New files-and-pathlib example, with its figure, journey placement and social card.
  • Python 3.13 content.
    • generics-and-typevar leads with PEP 695 syntax and shows TypeVar as the legacy spelling.
    • Four pages use real 3.13 features: type parameter defaults, copy.replace(), ReadOnly and warnings.deprecated.
  • Learning order. Pages before functions no longer use def, class or try.
    • operators no longer defines a class to demo @; that demo moved to operator-overloading.
    • exceptions and guard-clauses now follow functions; assignment-expressions and sentinel-iteration now follow while-loops.
  • Phone figures. Figures fill the banner and scroll sideways rather than shrinking. The smallest label at 390px went from about 5.6px to about 9.2px.
  • Journey pages render inline code instead of literal backticks.
  • Wording. The home hero, About and privacy pages describe what the site does now.

Runner and editor

  • Tracebacks show only the learner's frames, with source lines (File "example.py", line 3).
  • exit() / sys.exit() end the program instead of producing "Internal Server Error".
  • stderr is shown in program order.
  • input() explains that the sandbox has no terminal.
  • Pages the sandbox can't run say so when Run fails. The new sandbox_limit frontmatter field marks the four of them: venv, subprocesses, threads, sockets.
  • Editor has undo history, auto-indent, Tab indentation (Esc then Tab leaves the editor; a hint says so), bracket matching, and Ctrl/⌘+Enter to run.

Supply chain and HTTP

  • No more esm.sh. CodeMirror and Shiki are bundled from npm packages pinned in package-lock.json. Sources are in web/; make browser-bundles builds them, and make build runs it.
    • Example pages make no third-party request before Run.
    • The CSP drops esm.sh and wasm-unsafe-eval.
    • Dependabot can now update these libraries.
  • HTTP behaviour.
    • HEAD works on every page.
    • Trailing-slash URLs 308-redirect to the canonical path.
    • Cache hits are re-stamped with max-age=300; production showed a 4-hour browser lifetime.
  • Turnstile cookie is bound to CF-Connecting-IP, so a copied cookie fails elsewhere.
  • New endpoints: /llms.txt and /examples/<slug>.md.
  • Search finds pages by everyday words ("dictionary", "mutable", "regex") and by names used in prose or code (zip, join, docstring).

Gates and quality machinery

  • make runtime-examples-test is new and part of make verify. It posts every program to the local Worker sandbox and compares the output. Until now the catalog had only run under host CPython. It adds about 3½ minutes.
  • Browser check now also covers editor keys, figure label size on a phone, and no third-party requests before Run.
  • hello-world waiver is permanent. It would have expired on 2026-12-01 and failed every PR.
  • Scoring heuristic no longer credits print( or name strings.
  • Social cards now fit their own text in the browser that renders them, and the build fails if a card still doesn't fit. Before, Comprehensions' title ran into its figure and three journey summaries ran into the brand line. All 121 cards were re-rasterised.
  • Strategy doc drops the Atom feed and records why.

Behaviour changes to accept

  • Tab indents in the editor.
  • A learner whose IP changes will be re-challenged by Turnstile.
  • The privacy notice's effective date moves to 14 November 2026.

Verification

Local runs used a cloud container against a local pywrangler dev Worker (Chromium, Node 22, Python 3.13), on the merged tree with current main, including #28. CI then ran the full gate on the same head.

  • make verify: passed in CI on cb8b029 (verify run), including runtime-examples-test (110/110 in the sandbox) and browser-layout-test. Every target also passed locally.
  • scripts/format_examples.py --check
  • make verify-python-version VERSION=3.13: passed in the same CI run.
  • git diff --check
  • Regression tests: added (tests/test_runner_and_http.py and browser-check assertions), but I did not confirm each one fails with its fix reverted.
  • Manual verification:
    • Posted error, exit(), stderr, input() and syntax-error programs to /examples/values on the local Worker and read the output panel.
    • curl for HEAD, the trailing-slash redirect, /llms.txt and .md.
    • Measured every social card's layout in Chromium.
    • Checked every sitemap page's og: and twitter: tags and that its card is served as image/jpeg.

Only verifiable after deploy: cache re-stamping and cookie binding on real Cloudflare, and how the cards look in real link previews.

Visual evidence (required for UI changes)

Screenshots were captured in the session but are not attached here.

Before (phone figures): at 390px, the string-formatting figure's labels rendered at about 5.6px.

After (phone figures): the same figure renders its smallest label at 9.2px and scrolls inside its own box; the page does not scroll sideways.

Before (example page): the closures page started at the first cell; "A closure is a function that remembers names…" appeared nowhere.

After (example page): that text renders under the summary.

Reproduction: make dev, then load /examples/string-formatting and /examples/closures at 390×844. Base: 866c8aa; head: cb8b029.

Example changes

  • Updated files under src/example_sources/*.md
  • Kept exactly one :::program block per example
  • Kept :::cell source/output deterministic and executable
  • Ran make verify-examples
  • Ran make check-generated

🤖 Generated with Claude Code

https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc

The hello-world waiver's reason (a first example is intentionally tiny)
cannot lapse, but its 2026-12-01 expiry would have failed make verify on
every pull request. A waiver may now set permanent = true instead of
expires; the two are mutually exclusive and permanent must be the boolean.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
The criterion heuristic awarded accuracy for containing print( and
practical usefulness for identifiers such as Ada, price, or config.
Neither can be observed from page text, so the credit is withheld and
the two criteria only penalise metasyntactic names. The heuristic only
bounds curated scores from above; the largest curated-minus-heuristic
gap moves from 0.3 to 0.5 against a 1.5 limit, so no page changes state.
The rubric snapshot also prints permanent waivers correctly.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
Pages before functions no longer define functions, classes, or handlers:
booleans, operators, none, object-lifecycle, iterator-vs-iterable,
sentinel-iteration, advanced-match-patterns, and unpacking are rewritten
with constructs already taught, and point at the later page with an
inline link where a later idea is named. The @ operator demo moves from
operators to operator-overloading as a Vector dot product.

Manifest order: guard-clauses and exceptions now follow functions (so
try is taught before the signature pages, properties, descriptors,
context-managers, and metaclasses use it), and sentinel-iteration
follows while-loops, which it contrasts itself with.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
…ix HTTP edges

Reader-facing:
- Example pages now render the intro paragraphs every source file has; they
  were parsed and then dropped.
- Journey pages render inline code instead of literal backticks.
- Figures keep readable labels on phones: they fill the banner and scroll
  sideways rather than shrinking below 72% of their intrinsic width.
- Home hero, About and privacy wording match what the site does.

Runner and editor:
- Tracebacks show only the learner's frames, with source lines.
- exit()/sys.exit() end the program instead of returning HTTP 500, stderr is
  captured, and input() explains why it is unavailable.
- Pages that teach something the sandbox lacks say so when Run fails.
- The editor gains undo history, auto-indent, Tab indentation, bracket
  matching and Ctrl/Cmd+Enter to run.
- CodeMirror and Shiki are bundled from pinned npm packages; esm.sh is gone
  from the pages and from the CSP.

HTTP:
- HEAD is answered for every page, trailing-slash URLs redirect, cache hits
  are re-stamped with the intended browser lifetime, and the Turnstile
  clearance cookie is bound to the client address.
- /llms.txt and /examples/<slug>.md are served.

Search indexes page prose and code and knows everyday synonyms.
make runtime-examples-test runs every program in the real sandbox.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
…e browser gate

The pending-download test now holds the self-hosted editor and highlighter
bundles instead of esm.sh requests.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
…mpson-k7lta5

# Conflicts:
#	public/prototyping/marginalia-gestalt.html
#	public/prototyping/production-figures-gestalt.html
#	public/search-index.json
#	src/asset_manifest.py
#	src/example_sources_data.py
…they fit

- generics-and-typevar: type parameter syntax first, TypeVar as the legacy
  spelling, plus 3.13 type parameter defaults.
- dataclasses: copy.replace(); typed-dicts: ReadOnly; warnings:
  warnings.deprecated.
- The inline-link check ignores code spans, so `first[T](items)` is not
  mistaken for a link.

All four pages were run in the local Worker sandbox.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
Teaches Path joining, whole-file and line-by-line text I/O, directory
listing and the missing-file boundary inside a temporary directory. The
program was run in the local Worker sandbox and matches its expected
output. Adds the page's figure, registry scores, journey placement and
social card.

Social cards were re-rasterised because every figure's SVG now carries its
intrinsic width for the phone layout.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
…m feed

- constants and strings no longer use for loops, f-strings or
  comprehensions before those pages; assignment-expressions moves after
  while-loops, since its examples use both loop forms.
- Social cards are rasterised with whatever fonts the machine has, so a
  fixed font size let the Comprehensions title run into its figure and three
  journey summaries run into the brand line. Each card now fits its eyebrow,
  title and summary in the rendering browser, and the rasteriser refuses to
  write a card whose text still does not fit.
- The strategy doc drops the Atom feed and records why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4DAa9EdQbgyvwGUWyEBAc
@adewale
adewale merged commit c4dd363 into main Nov 14, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants