Essays: split score engineering into tour + puzzles

The original five-essay scaffold treated «frozen header» and «audio
sync» as standalone deep dives. After looking across all of them, the
real shape of the engineering work is two voices: an architectural
tour and a curated set of puzzles whose only common thread is "the
first ruler I picked turned out not to be measuring what I needed."

Restructure:
- gun-pu-de-zha-fa  — rewrite as the «tour» essay: how the component
  hangs together end to end (Verovio → DOM layers → ticking).
  Outline cues now follow that arc.
- kan-cuo-de-chi    — new «看错的尺» (the mismeasured rule). Five
  puzzles, all sharing the same shape: staff-anchor sizing, GPU tile
  slicing, per-axis chrome dedup, SMuFL small→full clef, audio clock
  retiming. Each section is self-contained.
- dong-jie-de-bao-tou — deleted; content folded into the «source» and
  «glyph» sections of kan-cuo-de-chi.
- xi-tong-pai-zhun  — deleted; content folded into the «clocks»
  section of kan-cuo-de-chi.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: RuitingMa

src/content/essays/dong-jie-de-bao-tou.mdx

@@ -2,80 +2,96 @@
 title: 滚谱的扎法
 date: "2026-05-04"
 kind: ESSAY
-summary: 从 MEI 到一个能在网页里横向滚动、声音同步的乐谱组件。
+summary: 一份能在网页里横向滚动、声音同步的乐谱组件，从 MEI 到 DOM 怎么一步步扎起来的。
 tint: dune
 ---
 
 import Score from '../../components/Score.astro';
 
 {/*
-  起草大纲（按 cue 顺序）：
-
-  why-mei         — MEI / MusicXML 是什么。为什么不画 PNG。
-                    Verovio 把 MEI 渲到 SVG 是个起点，但只是起点。
-  one-system      — `breaks: 'none'` 把一首曲子排成一整条横向系统。
-                    天然给"横向滚动"提供了画布。
-                    `pageWidth: 100000, adjustPageHeight: true`。
-  staff-anchor    — viewBox 的坑：bbox 含装饰，装饰多 → staff 被压扁。
-                    解：以 staff body 为锚反推舞台高度（measure 一次，
-                    重设 --score-h，回流，继续）。
-                    本博客的 staffHeight = 40 默认。
-  tile            — Ravel 全曲 SVG 宽 ~37k px，撞 GPU 单纹理上限。
-                    沿小节切 tile（≤4096px），每片自己一个 viewBox
-                    crop，外层 GPU 各管各的。
-  anchors         — 把每个音符的 onset ms 映射到屏幕 x。线性插值 +
-                    游标缓存（O(1) 稳态）。msAtX/xAtMs 双向。
-  loop            — 多份 SVG 副本贴边铺开 + 幻影前导 tile。看到的
-                    seam 都是设计过的。
-  recap           — 整套架构是写给一个人的：作者读自己的谱子的时候
-                    不应该被装饰量影响视觉权重，不应该被 GPU 限制
-                    打到 10fps，不应该听一段需要按 5 个键。
+  起草大纲（按 cue 顺序）—— 全流程组件思路。
+  这篇是「形状」的故事，不是「难题」的故事；难题留给《看错的尺》。
+
+  empty      — 起。把谱子嵌进文章不是新事，但「能跟着读、能听一段、能拖
+               一格」的谱子是。一句话引出 MEI / MusicXML / Verovio。这篇讲
+               的不是怎么把音符画出来——讲的是怎么把它扎成一个组件。
+
+  strip      — 整套架构的地基：`breaks: 'none'` + 巨大 pageWidth +
+               adjustPageHeight。一句 setOption 决定后面的一切：曲子
+               摊成一条横向的带子。如果分页了，所有后续逻辑都不一样。
+
+  pipeline   — MEI → Verovio → SVG → DOM 注入。每一段的职责。
+               静态的（曲子结构、装饰、调号变化）一次性烧进 SVG；
+               动态的（播放头位置、tempo overlay 切换）由运行时处理。
+               所以渲染发生一次，播放发生千次。
+
+  layers     — 舞台里的几层叠在一起，互不干扰：
+                 pan         — Verovio 出的 SVG，每帧靠 translate3d 平移
+                 staff-lines — 单独画 5 条横线，单一来源避免双笔加粗
+                 chrome      — 「冻结的报头」(clef/keysig/meter)，假装不动
+                 playhead    — 一根固定的竖线
+                 hint        — "click to play"
+               这是为什么 chrome 能假装不动而 pan 在动——它们物理上分层。
+
+  lifecycle  — 不一上来就挂。IntersectionObserver 等到滚到视口附近才
+               让 Verovio 醒来；离开页面（astro:before-swap）拆得干净。
+               WASM 是大件，缓存（in-memory + IndexedDB）让重访免重渲。
+
+  ticking    — 演奏时两只钟一起转：
+                 视觉钟 (rAF)        ——  从音频钟读 ms → 锚点查 x →
+                                        translate3d 设位置
+                 音频钟 (AudioContext) —— 100ms tick + 250ms lookahead
+                                        独立排音符，一个游标记到哪了
+               两只钟在同一首曲子上跳同一支舞，谁也不主导。
+
+  recap      — 整套的形：一条带子 + 几层平行的 view + 一只眼盯着时间。
+               这是写给「一个人想看自己谱子」的，不是「任何人想用一个
+               通用乐谱播放器」的——所以它的边界设得很死，但里面的每
+               一处都是为这一个用例选的。
 */}
 
-<section data-cue="why-mei">
+<section data-cue="empty">
 
-{/* TODO: MEI/MusicXML 简介，Verovio 是什么。 */}
+{/* TODO: 起。MEI/MusicXML/Verovio 一句带过；这篇讲的是组件。 */}
 
 </section>
 
-<section data-cue="one-system">
+<section data-cue="strip">
 
-{/* TODO: `breaks: 'none'` 的决定 */}
+{/* TODO: `breaks:'none'` 决定一切。一句 setOption 选择了所有后续。 */}
 
 <Score slug="jeux-deau" />
 
 </section>
 
-<section data-cue="staff-anchor">
+<section data-cue="pipeline">
 
-{/* TODO: viewBox 含装饰的问题 + staff-anchor 的解。 */}
+{/* TODO: MEI → Verovio → SVG → DOM 的三步走。一次性烧 vs 运行时。 */}
 
 </section>
 
-<section data-cue="tile">
+<section data-cue="layers">
 
-{/* TODO: GPU 纹理上限 + tile 切片。 */}
-
-<Score slug="jeux-deau-ravel" />
+{/* TODO: pan / chrome / staff-lines / playhead / hint 各管各。 */}
 
 </section>
 
-<section data-cue="anchors">
+<section data-cue="lifecycle">
 
-{/* TODO: msAtX/xAtMs，游标缓存。 */}
+{/* TODO: IntersectionObserver 挂载、astro:before-swap 拆除、缓存。 */}
 
 </section>
 
-<section data-cue="loop">
+<section data-cue="ticking">
 
-{/* TODO: 多副本 + 幻影 leader 的实现。 */}
+{/* TODO: rAF 钟 + AudioContext 钟。两只钟同跳一支舞。 */}
 
 <Score slug="jeux-deau" loop />
 
 </section>
 
 <section data-cue="recap">
 
-{/* TODO: 收。整套是为读自己的谱子写的。 */}
+{/* TODO: 收。整套是为一个人读自己谱子写的。 */}
 
 </section>

src/content/essays/gun-pu-de-zha-fa.mdx

@@ -0,0 +1,125 @@
+---
+title: 看错的尺
+date: "2026-05-04"
+kind: ESSAY
+summary: 做这个谱子组件，撞到几面看似无关的墙——后来发现每一面的形状都一样：第一直觉的尺子量不出真正想测的东西。
+tint: rust
+---
+
+import Score from '../../components/Score.astro';
+
+{/*
+  起草大纲（按 cue 顺序）—— 几个工程难题，按"形状"排列。
+  整篇的脊梁是：每一节都是「我以为对的单位 → 实际该用的单位」的故事。
+  这个一致性比任何单一的难题都更值得说出来。
+
+  opener     — 引：写组件时撞到的几面墙，一开始看起来八竿子打不着——
+               一个是 SVG 的 viewBox，一个是 GPU 纹理上限，一个是 MEI
+               的元数据，一个是 SMuFL 的字形编码。后来发现它们形状是
+               一样的：每次都是我第一次挑的尺子，量的不是真正想测的东西。
+
+  ruler      — 谁来当尺：staff body，不是 bbox。
+               一开始 SVG 用 `height: 100%` 撑舞台。Verovio 的 bbox
+               包含上下所有装饰（ledger、dynamics、harm、slurs），所以
+               装饰多的曲子 staff 反而被挤扁——视觉权重在曲子之间漂移。
+               真正该量的是 staff body 的 5 线像素跨度。
+               解：先用 200px 临时舞台量第一条 staff 的 5 线，再算
+               比例反推 `--score-h`。多谱表自然变高，不需要额外补偿。
+
+  ceiling    — 谁先撞到天花板：纹理上限，不是带宽。
+               Ravel 全曲 SVG 宽 37,000 像素。Intel 集成显卡单纹理上限
+               8,192px；现代独显 16,384px。超过 → 浏览器掉到 CPU 光栅化
+               → 每一帧拖累整页 → ~10fps。
+               不是网络不够、不是 SVG 太复杂；是那个东西塞不进一张 GPU
+               纹理里。
+               解：沿小节切 tile，每片 ≤4096px，外层 viewBox 做 crop，
+               内层 `definition-scale` viewBox 不动。每片各自上 GPU。
+
+  source     — 信哪个真理源：渲染结果，不是 MEI 元数据。
+               冻结报头在切换 clef/keysig/meter 时，本来想从 MEI 元数据
+               推：解析 `<clef>` 的 shape 和 line，组合签名，用作 dedup
+               key。结果发现 MEI 里 `clef sameas`、courtesy clef 引用、
+               octave displacement、cancel naturals 全是边界情况，每补
+               一个就漏一个。
+               改向下游真理找：把 Verovio 渲染出来的 `<g class="clef">`
+               里的 `<use xlink:href>` 列表（剥掉 cancel naturals 后）
+               作为视觉签名。同样的字形组合 → 同样的签名 → dedup。
+               同时把 (谱表 × clef/keysig/meter) 拆成独立 track，每个
+               独自 binary-search + opacity crossfade，钢琴上层换谱号
+               下层不闪。
+
+  glyph      — 真理源也有边界：SMuFL 大小变体的小坑。
+               即便信渲染结果，Verovio 给 mid-piece 的是 SMuFL "clef
+               change" 小变体（E07A/E07B/E07C），高度只有正版的 ~70%。
+               克隆到 chrome overlay 里就看到谱号每次跨 mid-piece 切换
+               都缩一圈。
+               解：三键映射（E07A→E050, E07B→E05C, E07C→E062），SMuFL
+               规范保证小写大写共享 reference point，所以替换后五线对位
+               不变。
+               这一节是上一节的小注脚——「视觉签名」作为真理源也有它
+               自己的边界，需要再向下走一步看到字形编码层。
+
+  clocks     — 时间也是一把容易看错的尺：rAF 不等于 AudioContext。
+               播放头要走得准，音符要响得准，两边对的是同一个时间——
+               但它们用的不是同一只钟。视觉走 rAF（屏幕刷新率），声音
+               走 AudioContext（硬件采样钟），两只会缓慢漂移。
+               另一个具体的版本：MEI 的 `<tempo>` tstamp 在小节起点，
+               glyph 在小节中段才出现。按 tstamp 触发 overlay 切换 →
+               文字在还没到播放头时就换，几百 ms 的滞后。
+               解：retiming——算 glyph 的实际 x 位置，反推它过播放头
+               的那一刻的 ms，用那个 ms 触发切换。
+
+  recap      — 这些之后留下的不是技术总结，是一种习惯：先怀疑自己
+               用的尺。直到把"我以为在测什么"和"我实际在测什么"对
+               齐了，所有后续修补都是在错的层面打补丁。
+*/}
+
+<section data-cue="opener">
+
+{/* TODO: 引。每个难题的形状都一样：第一直觉的单位错了。 */}
+
+</section>
+
+<section data-cue="ruler">
+
+{/* TODO: staff-anchor 缩放。bbox 不是合理的尺。 */}
+
+<Score slug="jeux-deau-ravel" />
+
+</section>
+
+<section data-cue="ceiling">
+
+{/* TODO: GPU tile 切片。37k 像素 vs 8,192 上限。 */}
+
+</section>
+
+<section data-cue="source">
+
+{/* TODO: per-axis chrome + visual signature dedup。 */}
+
+<Score slug="all-keys" />
+
+</section>
+
+<section data-cue="glyph">
+
+{/* TODO: small→full 谱号映射。SMuFL E07A→E050。 */}
+
+<Score slug="chaos" />
+
+</section>
+
+<section data-cue="clocks">
+
+{/* TODO: rAF 钟 vs AudioContext 钟，tempo overlay retiming。 */}
+
+<Score slug="jeux-deau" />
+
+</section>
+
+<section data-cue="recap">
+
+{/* TODO: 收。先怀疑自己用的尺。 */}
+
+</section>