kairos-chain 3.81.0 → 3.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc251869ebf7ce64e94fbae5baf21ef0eea655b6d1c42d55dfb2f7ee7c2ccc0
-  data.tar.gz: aea009fc75974ff42a05e2bc54a352c19b1192157b9fe8eefa311ae9fd096c65
+  metadata.gz: e601238b25375836907f7eec155beb0297e940cd5fd419ea855b7d48a3335993
+  data.tar.gz: 1c720eaa88d3204eedc436e38cdabaa3e79df3b9b5aca6260c925ec4173c6e62
 SHA512:
-  metadata.gz: 498212b88feb4e563e745be00467f8e206aff2c2103761c12d21695a1829201f2edae98295f61e2aaf6695f9d5e82be4f9f24a2c3ff10e868965a8cc1f1eae91
-  data.tar.gz: efe4a6d07531e77648bd175452e72036a0261d0bfb3b426b5f571b54b14a1f3f1695acc3b7d0136b64f04c33eac0e9c04dcebfb58481373af0ddbed355a8d1c4
+  metadata.gz: d13dbb392110ebc2f5f913bc38e370f7c4c36ee8067d69d060ab4379f1a34cc9db98a37ee09b845d633a4c76821194bb5aa8eaeef6db6c77e43784f7831150f7
+  data.tar.gz: 34eca89babce68b01e805b6510967f0d1e2dca0faa0a856d1ec7a8881fd7e4a00cf90932c69ed7685cefe89e482144566ca4733d1efc433c2bf0b0038d9080af

data/CHANGELOG.md

@@ -4,6 +4,108 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.83.0] - 2026-09-01
+
+### Added — readable_gate measures sentence length
+
+`kairos_hook_projector` 0.6.0 → 0.7.0. The gate now reports three sentence
+metrics on every turn (`sentences`, `sentence_p90`, `sentence_max`) and honours
+two new thresholds, both off unless a mode names them:
+`max_sentence_chars_p90` and `sentence_min_count`.
+
+Why it was missing: the readable-output norm this gate exists to enforce names
+long sentences as its first observed failure form, and says "split overlong
+sentences" outright. Nothing in `measure()` was sentence-aware. The one symptom
+the norm names by hand was the one nothing measured, while the line cap — which
+the same norm calls a soft target rather than a gate — was enforced as a hard
+block.
+
+The cap is on the 90th percentile, not the mean and not the maximum: a mean
+hides the tail that does the damage, and a maximum fails a good answer for its
+one long sentence. Nearest-rank, so the number reported is the length of a
+sentence actually in the message. The length announcement does not clear it,
+for the diagram floor's reason — announcing that a message is long says nothing
+about whether its sentences are.
+
+`sentence_min_count` is not a convenience. Nearest-rank puts the 90th
+percentile at the last element for every count under ten, so below that floor
+the cap would be a maximum cap under another name.
+
+What counts as a sentence, each rule with a killed mutation behind it:
+
+- Sentences never span a line. A bullet with no terminating punctuation is one
+  sentence the length of its line, which is what it costs to read rather than
+  an artefact of the author's punctuation.
+- Headings, table rows, horizontal rules and blockquotes are not sentences. A
+  seven-column table row measured as one reads as a single 200-character
+  sentence and takes over every percentile in the message; and a quotation
+  cannot be shortened without cutting quoted facts, which a mode's own rewrite
+  instruction is likely to forbid — leaving "stop quoting sources" as the only
+  compliance.
+- A list marker is stripped rather than skipped. The text after it is prose the
+  reader reads, and skipping list items would exempt most bullet-written output.
+- A URL collapses to one character: it is clicked, not read.
+- An ASCII full stop splits only before whitespace. Without that condition
+  `readable_gate.rb`, `v0.4.6` and `3.82.0` shatter into fragments and the
+  measured tail collapses towards zero — a metric reporting every message as
+  readable.
+
+Declared and not closed: prose moved inside a fenced block is not measured.
+That is the hole the line count has always had, and closing it for one metric
+only would leave the two disagreeing about what the message contains.
+
+The core ships no number. `--report` gained `sent`, `sent_p90` and `sent_max`
+columns and is where a mode's cap comes from; `mode_hooks/_EXAMPLE.json`
+documents both keys and deliberately omits values, since the right one depends
+on what the author writes and in which script.
+
+- Cost: 0.9 ms of a 3.2 ms full measurement on a 25,719-character message,
+  against the hook's 9.5 s budget.
+- Tests: 168 runs, 997 assertions, 0 failures (was 152 runs; 16 new fixtures).
+  Mutation sweep filtered to the new family — 19/19 killed, 0 survived, 0
+  anchor-not-found, source restored byte-identical, 11-file baseline green at
+  325 runs.
+- One existing mutation anchor (M39) was retargeted: the sentence columns were
+  inserted into the argument list it points at, and a stale anchor reports
+  ANCHOR NOT FOUND rather than a survivor.
+
+## [3.82.0] - 2026-08-31
+
+### Added — L1 knowledge: html_slide_deck_authoring
+
+New gem-bundled L1 knowledge entry `html_slide_deck_authoring` (v1.0), written
+by the operator from the 2026-08 build of a bilingual lab-meeting deck: 24 main
+slides plus a 58-slide appendix, ja/en generated from one source, click-driven
+builds, a searchable index, and a handout PDF.
+
+Contents: the five-module split (`kit` / `txt_*` / `viz_*` / `make_*` /
+`check_*`) and why kit and viz must not merge — they constrain different units
+(viewport height vs SVG user units); the one-slide budget; the rule that every
+number on a slide is read from the same context the report reads, never written
+into prose, with the sibling deck that still said "sweep in progress" after the
+sweep finished as the counter-example; the three ways a number was actually
+misread on the day (missing denominator, two axes in one sentence, a range
+whose span was not named); inline SVG rather than rasterised PNG (CJK fonts,
+scaling, tooltips); the animation safety direction — draw the finished state
+and animate backwards from it, so print, `prefers-reduced-motion`, CSS-off and
+JS-off all render something true; two checkers with different jurisdictions
+(inside the SVG vs the slide's vertical budget); the handout-PDF variant and
+the values a JS-free build leaves blank; and a searchable index whose filter
+must listen on the `input` event, since CJK IME text never reaches `keydown`.
+
+- Shipped to both `knowledge/` and `templates/knowledge/`, byte-identical, so
+  the next `system_upgrade` on the authoring instance reports UNCHANGED rather
+  than `user_modified` — a divergent instance copy wins silently over every
+  later template update.
+- Two neighbouring entries (`frontend_design`, `html_to_pdf_conversion`) are
+  instance-local and do not ship, so the `[[...]]` links to them dangle on a
+  fresh install. Same convention as `loop_engineering_patterns`.
+- Not multi-LLM reviewed. This is a record of what was measured while building,
+  not a design under review. It ships as written apart from a `version` field,
+  a folded-scalar fix (`>` to `>-`) so the description does not carry a
+  trailing newline into the `knowledge_list` table, and one paragraph stating
+  the boundary against the two neighbours.
+
 ## [3.81.0] - 2026-08-27
 
 ### Changed

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.81.0"
+  VERSION = "3.83.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/knowledge/html_slide_deck_authoring/html_slide_deck_authoring.md

@@ -0,0 +1,401 @@
+---
+name: html_slide_deck_authoring
+description: >-
+  Use when building a presentation deck as generated HTML — a self-contained, CDN-free,
+  16:9 deck with inline-SVG figures, two languages from one source, PowerPoint-style
+  click-driven builds, mechanical layout checkers, a searchable slide index for a large
+  appendix, and a handout PDF. Covers the module split, the one-slide budget, the
+  "numbers come from the reader, never the prose" rule, how a number on a slide gets
+  misread, the animation safety direction, why a regex checker over your own output
+  fails silently, and the traps that cost real time. NOT for Markdown slide tools
+  (Marp/reveal.js) or for writing the talk's content.
+version: "1.0"
+tags: [slides, presentation, html, svg, bilingual, i18n, ime, animation, pdf, playwright, checker, search, authoring]
+---
+
+# HTML スライドデッキの作り方
+
+生成 HTML でプレゼン資料を作るときの設計方針と手順。2026-08 にラボミーティング用
+デッキ（本編 24 枚＋Appendix 58 枚、日英 2 言語、クリック送り、索引、配布 PDF）を
+作り切った経験から。
+
+## いつ使うか
+
+- 図が主役で、**数値が別の成果物（レポート・解析結果）と一致していないと困る**とき
+- **同じ内容を2言語**で出すとき
+- 発表用と**配布用 PDF** の両方が要るとき
+- PowerPoint を開けない環境で作るとき、あるいは図をコードで生成したいとき
+
+使わない場合: Marp / reveal.js で足りるとき。話す内容そのものを考える段階。
+
+隣の entry: [[frontend_design]] は見た目の原則と JSON から組む簡易デッキ生成器
+（枚数が少なく図が単純なとき）。[[html_to_pdf_conversion]] は Playwright で PDF に
+焼く手順だけ。ここは**図をコードで生成し、枚数が数十枚に育つ場合**を扱う。
+
+---
+
+## 1. モジュールの分け方
+
+5 つに分ける。**混ぜると必ず壊れる。**
+
+    kit.py        CSS・JS・1枚を組む関数（slide / table / tiles / panes / figure）
+    txt_*.py      本文。1枚ずつ並べるだけ。ここに geometry を書かない
+    viz_*.py      図。インライン SVG を返す関数の集まり
+    make_*.py     入口。context を作り、言語を切り替えて両方を出す
+    check_*.py    機械検査（後述）
+
+**kit と viz を混ぜないこと。** kit は「1枚に置けるもの」を構造として制限する係で、
+viz は「1つの図の中の座標」を持つ係。制限が違う（前者は vh、後者は SVG ユーザー単位）。
+
+### 1枚の予算
+
+**要点1行 ＋ 図か表1つ ＋ 断片3つまで。** それ以上は Appendix に回す。
+`slide()` で 4 個目の断片を受けたら例外で落とす、くらい強制してよい。制限が無いと
+必ず溢れる。Appendix は枚数無制限にしておくと、本編の圧が逃げる。
+
+---
+
+## 2. 数値を地の文に書かない
+
+**成果物が2つ以上あるなら、数値は必ず共通の reader から来させる。**
+
+    from make_report import build_context     # レポートと同じ reader
+    C = build_context()
+    ...  f"偶然の {C['B']['gf_lo']:.1f} 倍"
+
+こうすると「レポートだけ更新してスライドが古いまま」が構造的に起こらない。
+
+失敗例が実在する: 同じ repo の別デッキは地の文ハードコードで、解析が終わった後も
+「掃引中」と書いたままになっていた。**同じ轍を踏まない。**
+
+派生値もヘルパにする。「約 100 倍」と手で書いた箇所が、実際にはモデルごとに
+71〜1,101 倍と桁が違っていた（元資料のモデル横断の丸めを転記していた）。
+`_ratio(C, model)` のような関数にして毎回そこから出す。
+
+### 2.1 数値は「軸」と「分母」を言わないと誤読される
+
+聞き手は数値を**自分が知っている種類の数値**として読む。実際に起きたこと。
+
+- **「53%」を「50% の改善」と読まれた。** 実際は増分の内訳で、追加学習で得た
+  0.64 のうち 0.34 がその情報そのもの、という意味。倍率の伸びは +19% だった。
+  棒グラフが 50% 伸びて見えないのは正しく、読み手の指摘が正しかった。
+  → タイルの中に**元の3値**（3.40 → 4.05、同じ計算量の対照 3.70）を並べたら通じた。
+- **1つの要点に軸を2つ入れていた。** 「対照の 8.5〜11.7 倍動く」と
+  「KEGG は偶然の 2.26 倍」を1文に並べていた。前者は動いた量そのもの、後者は
+  その並びの当たり方で、別の軸。単独では何のことか読めない。
+  → 片方を落とし、Appendix に図解で分けた。
+- **「8.5〜11.7 倍」を複数モデルの幅と読まれた。** 実際は**1モデルを2条件で**
+  測った幅。もう1つのモデルは 93〜96 倍で、範囲の外にあった。
+
+規則にすると:
+
+1. **割合を出すなら分母も出す。** 「増分のうち」「最良モデル比」まで書く。
+2. **1文に軸を2つ入れない。**
+3. **範囲を出すなら、何をまたいだ範囲か言う**（モデル／条件／seed）。
+4. 丸めた元値を並べると、聞き手の再計算が**最終桁でずれる**ことがある
+   （3.40・3.70・4.05 から計算すると 54%、表示は 53%）。増分の形で出すか、断る。
+
+### 2.2 参考文献はその枚のフッターに1回だけ
+
+一覧を付録に置くだけだと、聞き手は話を離れて探しに行くことになる。
+**その文献が初めて意味を持つ枚**のフッターに出す。
+
+- **出てくるたびに書かない。** ベンチマークの名前は本編の大半の枚に出るので、
+  毎回書くと雑音になる。導入する枚に1回だけ。
+- **著者・年までに留める。** 掲載誌まで入れると、注意書きのある枚で行が
+  折り返し、ページ番号まで2行に割れる。番号 `[n]` が付録の一覧を指す。
+- 付録にあって本編で使っていない文献は、付録だけに置いたままにする。
+
+---
+
+## 3. 2言語を1つのソースから
+
+図のラベルも本文も、同じ `T(ja, en)` を通す。
+
+    LANG = "ja"
+    def set_lang(lang): global LANG; LANG = "en" if lang == "en" else "ja"
+    def T(ja, en):      return en if LANG == "en" else ja
+
+`T` はリストも受けられる（`T(["a","b"], ["x","y"])`）ので、箇条書きにも使える。
+入口は言語ごとに `set_lang()` → 全枚を組む、を繰り返すだけ。
+
+**英語は同じ意味でも横に伸びる。** 日本語で収まっても英語で溢れる、が何度も起きた。
+検査は必ず**両言語**に掛ける。最後に `set_lang("ja")` で既定に戻すこと（同じ
+プロセスで他の生成物を作ると英語で出てしまう）。
+
+UI 側の文字列（索引の見出しなど）は `document.documentElement.lang` から出す。
+JS に日本語を直書きすると、英語版に日本語が出る。
+
+---
+
+## 4. 図はインライン SVG
+
+matplotlib で PNG に焼かない。理由は3つ。
+
+1. **CJK フォントが無い環境では日本語が全部豆腐になる。** SVG ならテキストは
+   ブラウザ側のフォントで描かれる。
+2. 拡大しても劣化しない（投影・PDF の両方で効く）。
+3. hover の tooltip を付けられる。
+
+代償は「自動レイアウトが無い」こと。折り返しも自分で書く。日本語は文字数、
+英語は単語境界で折る **別々の幅**を持たせないと、どちらかが必ず溢れる
+（CJK 約 1.0em、英小文字 約 0.52em）。
+
+### 図を大きく見せる
+
+表示高は `min(余白の高さ, 横幅 × h/w)` で決まる。**viewBox の h を詰めると、
+同じ表示高でも中の文字が大きく描かれる。** 断片を削って情報を捨てるより、
+viewBox を詰めるほうがよい。要点（take）を削るのも余白が増えて効く。
+
+図を2枚並べたいときは、本文の器を `display:flex` にして `figure{flex:1}` に
+しておけば `figure(a) + figure(b)` で半分ずつになる。1枚に詰めるより文字が
+1.4 倍ほど大きくなる。
+
+### 図の中の説明箱は縦の予算を使わない
+
+スライドの縦は常に足りない。**説明を1行足したいとき、図の中の箱に入れれば
+図の高さも断片の数も変わらない。** 枚の外に足すと図が縮む。
+逆に、図の中の箱を差し替えるのは「無料」の変更になる。
+
+### 図を2つの文書で共有する
+
+同じ図をスライドと文書（レポート）で共有していると、片方だけ変えたいときに困る。
+**図を複製せず、変えたい部分を引数にする。**
+
+    def fig_pipeline(..., box="rank"):    # 既定は文書側のまま
+        if box == "cooc": ...             # スライドだけ差し替える
+
+複製すると、次に数値が変わったとき片方だけ古くなる。§2 と同じ理屈。
+
+---
+
+## 5. アニメーション
+
+2つの方式を用意し、**同じ図で混ぜない**。
+
+### ループ（CSS のみ、JS を使わない）
+
+    .anim-fade{...}
+    .slide.on .anim-fade{animation:... infinite; animation-delay:var(--d,0s)}
+
+`--d` で段差をつける。`.slide.on` の中だけで回す（裏で全枚ぶん回さない）。
+
+### クリック送り（PowerPoint 風）
+
+    図側:  <g data-step="auto">        ← 番号は書かない
+    枚側:  slide(..., build=True)      ← 出現順に採番し、断片はその続き
+    JS:    next() が段を1つ進め、出しきってから次の枚へ
+
+`tiles` / `panes` / `table` にも `build=True` を通して、タイル・対比・表の行を
+1つずつ出せるようにしておくとよい。**要点（take）は段に載せない** — その枚の
+主張なので最初から出ていないと聞き手が迷う。
+
+締めの一段落のように「表を読み終えてから出したいもの」は、段の最後に置く。
+結論が最初から画面にあると、表を追う意味が無くなる。
+
+### 両方に共通する安全の向き（最重要）
+
+**図は「終わった状態」を描く。アニメは始点にずらして戻すだけ。**
+
+こうしておけば、印刷・`prefers-reduced-motion`・CSS 無効・JS 無効のどれでも
+静止画が正しい。逆向き（始点を描いてアニメで終点に持っていく）にすると、
+効かない環境で**間違った図**が出る。
+
+クリック送りも、隠すのは JS が `body.built` を付けてから。JS が落ちたら
+全部見えたままになる。
+
+### 隠すのは opacity だけ
+
+`display:none` にすると段が進むたびに版が動く。`opacity` なら場所は取ったまま
+なので、レイアウトが跳ねない。縦の予算も「全段出した状態」で一度測れば済む。
+
+---
+
+## 6. 機械検査を2本用意する
+
+ブラウザで目視できない環境では、検査が唯一の防壁になる。**性質の違う2本**が要る。
+
+| 検査 | 見るもの | 捕まえるもの |
+|---|---|---|
+| geometry | SVG の**内側** | テキストのはみ出し、要素どうしの重なり |
+| fit | スライドの**箱** | 本文がタイトル・フッターに被る、図が小さくなりすぎ |
+
+実際に起きた崩れは geometry では**1件も捕まらなかった**。縦の予算を数える
+fit のほうが必要だった。逆に fit は SVG の中身を見ない。両方要る。
+
+太字は幅 ×1.06 で見積もる。これを入れた途端に実在の欠陥が 11 件出た。
+
+**検査が見ないもの**も明示しておく: 段（アニメ）の動き、色、実フォントの字幅。
+
+### 6.1 自分の出力を正規表現で読む検査は、黙って壊れる（最重要）
+
+**生成側のマークアップを変えた日に、検査が静かに測らなくなる。**
+
+実例。断片を `<li class="hi">` から `<li class="hi" data-step="2">` に変えたところ、
+検査の正規表現 `<li class="[^"]*">` が当たらなくなり、**本編 24 枚の断片 42 個が
+縦の予算に 0 として入り続けた。** それでも ALL CLEAR は出ていた。
+同じ日に、`class="slide title"` の表題枚も `<section class="slide"` に当たらず、
+まるごと検査対象から漏れていた。**どちらも数か月ぶん気づかれなかった。**
+
+対策は2つ。
+
+1. **数えた個数を検査自身に出させる。** 「断片 0 個」が異常だと分かるように
+   する。生成側が出した個数と突き合わせるのが理想。
+2. **属性やクラスを1つ足したら、検査の正規表現を見に行く。** 手順に入れる。
+
+### 6.2 ALL CLEAR は「見た」ことにならない
+
+ブラウザが使える環境でも同じ。矢印の右に置いた注記が viewBox の右端で切れて
+いたのに、幾何の検査は通した。近似モデルは境界で外す。
+**枚を触ったら必ず1枚撮って目で見る。** そのために「この枚だけ撮る」機能を
+先に作っておく（後述）。
+
+---
+
+## 7. PDF にする
+
+### 配布用の変種を作る
+
+発表用デッキとは別に、**JS を積まない1枚1ページの HTML** を出す。
+
+- `.slide{display:flex!important; page-break-after:always}`
+- `[data-step]` と `.anim-*` は全部見せて止める
+- Appendix を入れるかは選べるようにする（配布は本編だけ、が多い）
+
+同じ `main(C)` から作れば、発表用と中身がずれない。
+
+### JS が埋める値は、配布版では生成時に埋める
+
+画面版のページ番号を JS で入れていると、**JS を積まない配布版は空欄のまま**
+印刷される。配布用を組む関数の中で埋めてしまうのが確実（配布は本編だけなので
+通し番号でよい）。画面版は JS が上書きするので二重にならない。
+
+同じ罠は「JS で入れている表示」すべてに当てはまる。配布版を作ったら、
+**空になっている要素が無いか出力を数える。**
+
+### ヘッドレス Chromium で焼く
+
+    playwright + chromium → page.pdf(width=..., height=..., print_background=True)
+
+**紙もスライドと同じ 16:9 にする。** A4 に入れると上下に余白が出るだけ。
+
+共有環境に入れないこと。`pip install --user` と `~/.cache` に閉じる。root が無くて
+`playwright install-deps` が使えない場合は、足りない共有ライブラリを他の環境から
+**home にコピー**して `LD_LIBRARY_PATH` を通す。他人の環境を直接参照すると、
+その環境が消えた日に黙って壊れる。
+
+**CJK フォントが無いホストでは日本語版を PDF にできない**（豆腐になる）。
+版組みの確認には使える（箱の位置と行数は正しく出る）。配布が要るなら
+`~/.fonts` にフォントを置くか、operator のブラウザで印刷してもらう。
+
+### 「この枚だけ撮る」を最初に作る
+
+1枚ずつ直す作業では、毎回これを使う。
+
+    render.py <html> -o out.png --png --slide 12
+
+中では `?still` で全段を出した状態に固定し、**枚送りの関数を直接呼ぶ**。
+ハッシュ（`#12`）を変えて `goto` するだけでは same-document navigation になり、
+JS が再実行されず1枚目のまま撮れる。
+
+配布用 HTML には枚送りの JS が無いので、`--slide` は使えない。
+**何が違うのかを1行で言って止める**（`ReferenceError` を出さない）。
+
+---
+
+## 8. 大きな Appendix を引く索引
+
+Appendix が数十枚になると、矢印で送って探すのは実用にならない。
+**キー1つで一覧を出し、語で絞り込んで飛ぶ**仕組みを入れる。
+
+### サムネイルは選ばない
+
+reveal.js 風に全枚を縮小して並べる案は、**図が主体のデッキでは機能しない。**
+82 枚を1画面に入れるには 1/6 前後まで縮める必要があり、本文が 3px 相当になって
+読めない。結果、見分けのつかない矩形が並ぶだけになる。
+**探しているのは語**なので、番号・見出し・題名の一覧＋絞り込みのほうが速い。
+
+### 実装で外せない4点
+
+1. **絞り込みは `<input>` の `input` イベントで受ける。**
+   `keydown` の `e.key` を拾う実装は **CJK の IME で動かない** — 確定前の文字は
+   `e.key` に来ず、composition イベントを経由する。英語版だけ絞り込みが効いて
+   日本語版で 0 件、という形で出る。**2言語のデッキなら必ず両方で試す。**
+2. **探すのは題名ではなく、その枚の全文。** 題名だけだと、本文で論じている語で
+   見つからない（ある語で 1 枚しか出ず、それを扱う本編 4 枚が漏れた。全文なら
+   12 枚出た）。表示は題名のままでよい。索引だけ全文にする。
+3. **既存のハンドラに触らない。** 新しいハンドラを **capture 段**で登録し、
+   一覧が開いている間だけ `stopPropagation` する。クリックは既に「次へ進む」に
+   割り当てられているので、これをしないと選ぶ操作が枚送りになる。
+4. **一覧は grid にする。** CSS の段組み（`column-count`）は高さが尽きると
+   **右へ**伸びるので、行数が多いと横スクロールになる。grid なら溢れは縦。
+
+### 操作の細部
+
+- **矢印は並んで見えている位置で動かす。** 文書順にすると3段の格子で ↓ が
+  右隣に飛ぶ。段数は書かずに `offsetTop` が揃う要素を数えて**実測**する
+  （スタイルシートの段数を変えても追従する）。
+- `←→` を格子の移動に使うなら、入力欄のカーソル移動は諦める。絞り込みの語は
+  短いので `Backspace` で足りる。
+- **閉じるのは Esc だけ。** 開くキーで閉じられるようにすると、その文字から
+  始まる語（"ortholog" の o）を打った瞬間に閉じる。
+- 見出しの接頭辞（「付録 —」）は一覧では落とす。番号が言っているので重複で、
+  残すと見出し列が全部同じ文字で埋まって省略記号で切れる。
+- 該当0件で Enter を押しても何も起きないようにする。
+- 配布用 HTML は JS を積まないので索引も入らない。PDF の頁数は変わらない。
+
+---
+
+## 9. 実際に踏んだ罠
+
+| 罠 | 症状 | 対処 |
+|---|---|---|
+| 表の折り返しの既定が逆 | 文字列の列だけが最小幅に潰れる | 折り返しを既定にし、**数値セルだけ** nowrap |
+| 図の高さが縛れていない | 図が箱から溢れてタイトルの上に描かれる | SVG を包む箱に `width/height:auto` ＋ `max-*:100%` |
+| フッターがページ基準に置かれる | 1枚目だけ偶然合っている | 枚の器に `position:relative` |
+| 横棒グラフのラベル欄 | 長いラベルが**左に**はみ出す（右揃えなので） | 欄幅から字数上限を決める。長い説明は tooltip か断片へ |
+| 関数名の衝突 | `TypeError: 'int' object is not callable` | ドメイン語（`step`＝窓の刻み幅）と被らない名前にする |
+| **CSS クラス名の衝突** | 指定した font-size と色が効かない | 後ろの規則が勝つ。名前を付ける前に**スタイルシートを grep** |
+| **本文の器が flex 行** | 表と段落を渡すと左右に割れる | 縦に積む器で包む。`flex:1;min-width:0` が無いと `table{width:100%}` が解決しない |
+| **フッターにもう1行足す** | 行が折り返し、ページ番号が「6 /」「24」に割れる | 番号に `white-space:nowrap`。中身は1行に収まる短さに切る |
+| **`::before` の区切り記号** | 地のテキストがあるのに最初の1つだけ区切りが出ない | 地のテキストは要素ではないので `:first-child` が当たる。区切りは生成側で入れる |
+| **`column-count` の溢れ** | 行数が多いと**横**スクロールになる | 高さが尽きると右へ伸びる。縦に溢れさせたいなら grid |
+| **矢印キーを文書順に割り当てる** | 3段の格子で ↓ が右隣に飛ぶ | 並んで見えている位置で動かす。段数は `offsetTop` から実測 |
+| **CJK の IME を keydown で受ける** | 英語版だけ絞り込みが動き、日本語版で 0 件 | 確定前の文字は `e.key` に来ない。`<input>` の `input` イベントで受ける |
+| **JS が埋める要素** | JS 無しの配布版で空欄になる（ページ番号） | 生成時に埋める。画面版は JS が上書きするだけ |
+| ハッシュだけ変えて `goto` | ヘッドレスで撮ると全部1枚目になる | same-document navigation で JS が再実行されない。関数を直接呼ぶ |
+| 段番号を手で振る | 図を1つ足すと以降が全部ずれる | `"auto"` の印だけ置いて、組むときに一括採番 |
+| 生成後の grep をしない | 分割された文字列リテラルが grep に掛からない | ソースではなく**出力 HTML** を grep して確認 |
+
+---
+
+## 10. 進め方
+
+operator が1枚ずつ見て指示する形が一番回った。そのとき効いたこと。
+
+- **枚数表を引き継ぎ資料に置く。** 枚を出し入れすると番号がずれ、口頭の
+  「S18 が」が指すものが変わる。番号はその表で確認する約束にする。
+- **本編とスライド番号で相互参照しない。** 「S12 と同じ」ではなく
+  「先ほどの KEGG 採点と同じ」と内容で指す。番号は必ずずれる。
+- **落とした情報の行き先を記録する。** 「本編から削除」ではなく
+  「Appendix のどこへ移した」。あとで必ず聞かれる。
+- **本編で語らないことは結論スライドにも出さない。** 文脈の無い数値が
+  まとめに残ると、そこだけ質問が集中する。
+- **前方参照を作らない。** まだ説明していない実験の数値を先の枚で使わない。
+- **「この数値はどこから出たのか」と聞かれたら、それは枚の欠陥である。**
+  聞かれた場所を直し、根拠は Appendix に図解で1枚足す。使われていない図が
+  ソースに眠っていることがある（書いたが置き忘れた図が実際にあった）。
+- **1枚直したら、ビルド → 検査2本 → その枚を撮る、まで回す。** 直した枚だけ
+  でなく検査は全枚に掛ける（1箇所の変更が他の枚の余白を変えることがある）。
+
+---
+
+## 11. 最小の骨格
+
+    kit.py        CSS（vh 単位・明色固定）、JS（枚送り＋段送り＋索引）、slide()/table()/tiles()
+    txt_deck.py   main(C) が本編、appendix(C) が付録。slide() を並べるだけ
+    viz_deck.py   図。T() でラベルを2言語に
+    make_deck.py  build_context() → set_lang → 両言語 → 配布 HTML
+    check_geom.py SVG の内側
+    check_fit.py  枚の縦の予算（**生成側を変えたら正規表現を見る**）
+    render_pdf.py ヘッドレス Chromium（`--slide N` で1枚だけ）