Skip to content

Advisory review: the language guide — from buried markdown to a self-verifying page - #8

Open
mparrett wants to merge 12 commits into
attribution-tipfrom
guide-live-tip
Open

Advisory review: the language guide — from buried markdown to a self-verifying page#8
mparrett wants to merge 12 commits into
attribution-tipfrom
guide-live-tip

Conversation

@mparrett

@mparrett mparrett commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Advisory PR — review only, do not merge. Per the convention from #1/#5/#6/#7, the base branch attribution-tip is deliberately frozen at the prior phase's tip (fc273c8) so this phase reads as one diff. Merging would fast-forward the pin and destroy the "before" snapshot. Close after review.

The arc

Norman's TUTORIAL.md and DEMO.md were correct (CI executes every fmpl block) but buried — plain markdown at the repo root, unreachable from the Pages site. This phase turns them into a first-class web surface that can prove its own claims:

  1. docs/fmpl-guide.html (96e6711) — web rendering of the tutorial, DEMO's stream/cursor material folded in as its own section, same design system as the tour. Sketches and network-only examples labeled; the markdown files remain the CI-verified sources of truth.
  2. Links (722e255) — landing-page card ("learn it"), tour §7 hyperlink, README.
  3. REPL deep links (75eb405) — repl.html#code=… prefill; every runnable block gets a link. The hash-runner smooths two REPL line-at-a-time gotchas at intake: multi-line @{…} match blocks join to the documented single-line idiom, and multi-line if/then/else chains join so the else doesn't dangle.
  4. Size-tuned wasm (a637c37) — [profile.wasm-release] (opt-level=z, fat LTO, panic=abort) + wasm-opt -Oz: 2.1 MB / 580 KB-gzip → 1.13 MB / 373 KB-gzip. panic=abort is safe because VM errors are Results by design; probed in-browser (overflow → clean error, no trap).
  5. ReplVm (2415a61) — the wasm gains a VM class alongside the global session functions, so a page can hold independent VM instances.
  6. Run-in-place (19b7ea7) — the payoff. Every block gets ▸ run / edit / reset; run executes in a fresh ReplVm (exactly the doctest harness's per-block semantics), live results replace the documented -- Returns: lines with ✓/✗ verdicts, and a masthead "run all blocks" re-verifies the entire page client-side. edit makes any block a scratchpad. The line-handling and annotation-checking logic lives once, in shared docs/fmpl-live.js.

Verification

  • All 29 runnable blocks execute clean in the wasm VM (Playwright click-through, value assertions on 11)
  • "run all blocks" → 29/29 blocks verified in your browser locally; re-verified on the deployed site after merge to main
  • Edit flow (factorial 5→6 → 720), reset, deep-link regression, dark mode, zero mobile overflow, zero console errors
  • just test green; clippy clean workspace-wide including the wasm target

🤖 Generated with Claude Code

mparrett and others added 7 commits July 22, 2026 19:08
@mparrett @claude
docs(pages): language guide — web rendering of Norman's TUTORIAL.md +…
96e6711 
… DEMO.md

Companion page to the engineering tour, same design system. Tutorial is
the spine; DEMO.md's stream/cursor material becomes its own section.
Sketches and network-only examples are labeled; the sources of truth
remain TUTORIAL.md / DEMO.md, which CI executes on every push.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
docs: link the language guide from landing page, tour §7, and README
722e255 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
feat(pages): REPL deep links — #code= prefill + run-it links on the g…
75eb405 
…uide

repl.html gains a hash runner: #code=<URI-encoded source> is fed through
the normal submit path after wasm init (echoed like typed input, history
populated). Two REPL line-at-a-time gotchas are smoothed at intake:
multi-line @{...} match blocks join to the documented single-line idiom,
and multi-line if/then/else chains join so the else doesn't dangle.

The guide marks browser-safe blocks with pre.run; a small script builds
each link from the block's own text (annotation-only lines dropped), so
no snippet is hand-copied. Network examples, sketches, and the comment
demo are unmarked. Verified: all 29 links execute error-free in the wasm
VM via Playwright, with value assertions on 11.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
build(pages): size-tuned wasm — dedicated profile + wasm-opt (-36% wire)
a637c37 
[profile.wasm-release]: opt-level=z, fat LTO, 1 CGU, panic=abort, strip.
panic=abort is safe here: VM errors are Results by design (no catch_unwind
in-tree; overflow probed in-browser — clean error, no trap). wasm-opt -Oz
needs --enable-bulk-memory since Rust emits bulk-memory ops by default.

2.1MB/580KB-gzip -> 1.13MB/373KB-gzip, verified against the pinned
wasm-bindgen 0.2.114 locally.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
feat(wasm): ReplVm class — independent VM instances for the browser
2415a61 
The globals expose one persistent session VM; the language guide's
run-in-place blocks need a fresh VM per run (the doctest harness's
semantics) without nuking the session. Exports a constructor plus
eval/is_complete with the same output contract as the globals.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
feat(pages): run-in-place — the guide executes and verifies itself in…
19b7ea7 
…-browser

Every runnable block gets ▸ run / edit / reset controls. Run executes
the block in a fresh ReplVm (CI doctest semantics); live results replace
the documented '-- Returns:' lines with ✓/✗ verdicts, and a masthead
'run all blocks' re-verifies the whole page client-side (29/29 locally).
edit swaps the block for a textarea; deep links remain for sharing.

The REPL line-handling logic (multi-line @{} and if/else joining) moves
to a shared docs/fmpl-live.js module used by both repl.html and the
guide, along with the annotation-checking block runner (same conventions
as fmpl-core/tests/doc_examples.rs, including order-insensitive top-level
map compare). wasm loads lazily on first run; prefetch warms the cache.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
fix(pages): pin binaryen 129 — apt's wasm-opt rejects Rust's sign-ext…
e8d2dbd 
… ops

First CI run of the shrink step failed validation on i32.extend8_s:
ubuntu's packaged binaryen predates default sign-ext support. Pin the
release that matches the locally verified build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
feat(pages): guide UX pass — live steppable hero, step-first blocks, …
c70c10d 
…quiet exits

Assessment findings from a first-visitor walkthrough, addressed:

- The hero looked like a REPL but was frozen — now it IS one: ▸ run
  steps through the demo session statement by statement, and the prompt
  is a real input (same session VM; reset restarts). The affordance no
  longer lies.
- 'run all blocks' was a verification feature posing as the page's first
  CTA, and it spent the one-by-one experience. Split: per-block ▸ run
  now STEPS one statement at a time (≫ finish drains the rest), while
  §13 gains '✓ verify this page' — non-destructive, fresh VM per block,
  per-block verdict chips + badge, no text rewritten. reset-all included.
- Exit-sign demotion: the caption's 'run in your browser' link is gone
  (the page runs in the browser); per-block REPL links shrink to a quiet
  ↗ glyph for sharing.
- Caption diet; 'edit' appears only after a block has been run.

fmpl-live.js: runBlock refactored into createRunner (statement stepper);
runBlock drains it, so verify and stepping share one implementation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
fix(pages): hero hint persists as a session comment — no first-step jump
7a4ec17 
Clearing the hint on boot made the first ▸ run visually jarring: the
instruction vanished and the transcript shifted up. The hint is already
written as an FMPL comment, so it simply stays in the scrollback and the
session grows beneath it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
fix(pages): masthead reads intro-then-terminal; quick start stays on …
ba17a49 
…the page

The provenance caption moves above the hero — it sets up the terminal
rather than captioning it after the fact. §1's opening no longer sends
readers to the standalone REPL: the fastest path is this page; the
toolchain block covers local installs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
feat(pages): quick start recommends the page; REPL links open in new …
37f9673 
…tabs

The full browser REPL gets one subtle mention in §1 (blank-slate scratch
sessions) with a recommendation to keep learning in place. It and the
per-block ↗ links now open in a new tab so the guide is never navigated
away from.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mparrett @claude
fix(pages): hero placeholder retires once the session starts
fd6c4b4 
'…or type FMPL here' kept reappearing after every submitted line. Once
the session is going — stepped or typed — an empty prompt is just an
empty prompt; reset restores the invitation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 25, 2026
Open
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mparrett