Skip to content

book: Handwired (handwired) - #155

Merged
BLamy merged 1 commit into
mainfrom
book/handwired
Oct 15, 2026
Merged

BLamy merged 1 commit into
mainfrom
book/handwired

Conversation

@BLamy

@BLamy BLamy commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Handwired — a new O'RLY? book

Five narrated, animated chapters on chenglou/handwired by Cheng Lou (MIT), pinned at 4ea7fcb2: how a program's if/else, loops and state are written by hand as a fixed program of weighted sums and relu over 32-bit floats.

  • Reader: https://orly.brett-lamy.workers.dev/?bundle=handwired · Blog: https://orly.brett-lamy.workers.dev/?blog=handwired
  • Chapters: 1 Both Branches Run · 2 A Switch of Arithmetic · 3 The Host Loop · 4 Loops That Cannot Stop · 5 Exact, Trainable, Wide (about 9.5 min narrated in total)
  • Scenes: apps/bookshelf/src/viz/books/handwired/chapter-1..5.tsx (+ stories). Book data: public/generated/handwired/.
  • Sources: sources.json has 78 claims and 175 links, all pinned to 4ea7fcb2. Every repo quote is checked against the clone.
  • Cover: title-only. The gpt-image call failed with insufficient_quota. No animal.webp ships, and the manifest and library.json carry no animal field. Note: the shelf's resolveAnimal borrows another book's animal (picked by a hash of the slug) for books without one.
  • Music: none (silent book).
  • Pipeline change: opt-in video.mjs --speed <0.7–1.2> (ElevenLabs voice_settings.speed). It merges onto the voice's stored settings when they can be read. This key lacks voices_read, so it falls back to a speed-only override with a warning. Default requests are unchanged. Tests are in generator/tts-speed.test.mjs. The book was narrated at 0.94, recorded as voiceSpeed in the manifest.

Models (requested → actual)

pass requested actual
research ledger, blog prose, blog edits claude-haiku-5-5 claude-haiku-5-5
visual plan + narration claude-sonnet-5-5 claude-sonnet-5-5
--speed pipeline flag (2 passes) claude-sonnet-5-5 claude-sonnet-5-5
scenes ch1–5 (5 parallel sessions) + 5 fix rounds claude-opus-5-5 claude-opus-5-5
pre-narration review, 3 rubric grades claude-haiku-5-5 claude-haiku-5-5
Sol fallback — not used (no Opus limit hit)

Every run went through generator/run-fable.mjs, and each result's modelUsage was checked.

Checks run

npm run typecheck ✓ · npm run build -- --skip-nx-cache ✓ · npm run book:sources -- --slug handwired ✓ · ORLY_VERIFY_PORT=5277 node generator/verify-book.mjs --slug handwired ✓ (all 5 chapters) · node generator/blog-viz.mjs --slug handwired ✓ · node --test generator/tts-speed.test.mjs generator/pronunciation.test.mjs generator/narration-timing.test.mjs ✓

Self-grade (fresh-eyes Haiku reviewer, docs/book-quality.md §4)

dimension score evidence
accuracy 8 27 narration claims checked in the clone, none contradicted. A few captions lose scope (e.g. "fifteen operations" holds for >= within 0..16,384).
depth 8 Real edge cases with numbers: the monotone-count counterexample, comparison costs by construction, backprop exceptions, CPU vs GPU trees, the write-back policy.
clarity 7 Terms are defined before use. The grader flagged that 32-bit floats were never named in the narration; this was fixed after grading (ch1 now says "Every result is a thirty-two-bit float", ch5 says "sixty-four-bit floats"), but not re-graded. Some captions are dense.
story 8 The chapter 1 question "what happens to a loop?" is paid off in chapter 4. The closing line is "The program never decides anything."
visual 7 Legible frames with real centerpieces (ramp→step morph, wire tape, sandwich, log-log scatter). Ch5's desktop frame is a labelled sketch, and the ch4 scatter compares different row counts.
sync 6.5 Captions are retimed to cues by the player. The authored-to-recorded warp per caption runs 0.6–1.4. ElevenLabs' alignment puts a few cues up to about 1 s early (ch2 cue 10). Rubric band; nobody has watched it.
sound 7 Chapter pace is 142–159 wpm after the 0.94 speed. Some short or final captions measure fast, partly from alignment noise. Nobody has listened.
curiosity 8 Ends on a usable mental model; every claim links to file and line.

Mean 7.44: FAIL against the bar (every dimension ≥ 8, mean ≥ 8.5). No critical issue. Per the rubric, sync and sound stay at 6.5–7.5 until a person watches and listens, so the self-grade cannot pass without that.

What I could not judge

  • The audio (pronunciation of "relu", "Brent-Kung", "Adam", "Javascript"; voice quality). Pace figures are words over cue spans.
  • Motion at playback speed, and the last frames in the browser. I looked at the mid-chapter browser previews and at offline renders from the authoring sessions only.
  • Whether the warp from authored to recorded timing reads well (the largest warps are ch2 caption 9 and ch5 captions 5→6).
  • The ch1 "every value: FP32" label added in the last pass was not rendered by its author. The verify-book preview of ch1 lands at a different beat.

Known remaining issues

  • No cover art (provider quota).
  • ElevenLabs alignment places some cues early (e.g. ch2 cue 10 by about 1 s); the CC pill changes slightly ahead of the voice there.
  • Stale "≈ N s" timing comments in a few scene headers.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Added the Handwired book, with five animated chapters exploring how branching, state, loops, and other programming concepts can be represented as arithmetic.
    • Added an optional narration speed setting for generated videos, supporting speeds from 0.7× to 1.2×.

@bolt-new-by-stackblitz

Copy link
Copy Markdown

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

@coderabbitai

coderabbitai Bot commented Oct 15, 2026

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 740a2f8c-31f1-42e9-aa78-098a7360a1dc
📥 Commits

Reviewing files that changed from the base of the PR and between c7828fd and 3c36c46.

⛔ Files ignored due to path filters: 14
  • public/generated/handwired/audio/chapter-1.mp3 is excluded by !**/*.mp3, !**/generated/**
  • public/generated/handwired/audio/chapter-2.mp3 is excluded by !**/*.mp3, !**/generated/**
  • public/generated/handwired/audio/chapter-3.mp3 is excluded by !**/*.mp3, !**/generated/**
  • public/generated/handwired/audio/chapter-4.mp3 is excluded by !**/*.mp3, !**/generated/**
  • public/generated/handwired/audio/chapter-5.mp3 is excluded by !**/*.mp3, !**/generated/**
  • public/generated/handwired/blog.md is excluded by !**/generated/**
  • public/generated/handwired/manifest.json is excluded by !**/generated/**
  • public/generated/handwired/previews/chapter-1.png is excluded by !**/*.png, !**/generated/**
  • public/generated/handwired/previews/chapter-2.png is excluded by !**/*.png, !**/generated/**
  • public/generated/handwired/previews/chapter-3.png is excluded by !**/*.png, !**/generated/**
  • public/generated/handwired/previews/chapter-4.png is excluded by !**/*.png, !**/generated/**
  • public/generated/handwired/previews/chapter-5.png is excluded by !**/*.png, !**/generated/**
  • public/generated/handwired/sources.json is excluded by !**/generated/**
  • public/generated/library.json is excluded by !**/generated/**
📒 Files selected for processing: 14
  • .github/ISSUE_TEMPLATE/tweak-book.yml
  • apps/bookshelf/src/viz/books/handwired/chapter-1.stories.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-1.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-2.stories.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-2.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-3.stories.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-3.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-4.stories.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-4.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-5.stories.tsx
  • apps/bookshelf/src/viz/books/handwired/chapter-5.tsx
  • generator/tts-speed.test.mjs
  • generator/tts.mjs
  • generator/video.mjs
+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Don't program by coincidence. Rely only on reliable things. Beware of accidental complexity, and don't confuse a happy coincidence with a purposeful plan. |
+------------------------------------------------------------------------------------------------------------------------------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       /   づ
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Five narrated chapters on chenglou/handwired @ 4ea7fcb2 (MIT): an if-else as two
ramps and a bit, the toggle template as a fixed program, the host loop, loops as
counts/trees/tables, and exactness, gradients and the three demos.

- Scenes: apps/bookshelf/src/viz/books/handwired/chapter-1..5 (+ stories).
  Visualizations authored by Claude Opus 5.5 from a Claude Sonnet 5.5 plan;
  research, review and blog prose by Claude Haiku 5.5.
- Narration: ElevenLabs default voice at speed 0.94 (manifest voiceSpeed).
- sources.json: 78 claims, 175 links pinned to 4ea7fcb2; every quote checked
  against the clone. Companion blog.md with 10 live viz sections.
- Cover: title-only. The gpt-image call failed with insufficient_quota, so no
  animal.webp ships and the manifest carries no animal field.
- generator: opt-in `video.mjs --speed <0.7-1.2>` (ElevenLabs voice_settings.speed),
  merged onto stored voice settings when readable, speed-only override otherwise;
  default narration requests are unchanged. Tests: generator/tts-speed.test.mjs.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
@BLamy
BLamy merged commit 4d908a1 into main Oct 15, 2026
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.

1 participant