Text Chunker 引き継ぎレポート — 分割ソース化・BASELINE-3 到達と Batch 4 修正計画
Text Chunker 引き継ぎレポート
0. 一行サマリ
単一 HTML(約 5,200 行)の Text Chunker を 30 ファイルの分割ソース + ビルド方式に移行。BASELINE-1 → BASELINE-3 で約 30 種の Fix を適用し、bundle モード(dist/text_chunker.html)は完全動作。dev ESM モード(index.html 直開き)には複数の import 不整合が残っており、Batch 4 で完全修復する計画を §7 に示す。
1. 対象プロダクト
- 場所:
public/tools/text-chunker/ - 目的: 文字数上限のある LLM チャット等に長文を分割して渡す、モバイルファーストの単一 HTML ツール
- 構成: index.html + manifest.json + scripts×3 + styles×5 + js×19 = 30 ファイル
- 動作モード:
- bundle モード(本番):
dist/text_chunker.html— 全 import が単一スコープに統合され動作 - dev ESM モード(開発用):
index.html直開き — 現在 import 不整合で動作せず
- bundle モード(本番):
2. 基準点(BASELINE)
| 名称 | 定義 | 状態 |
|---|---|---|
| BASELINE-1 | 単一 HTML(約 5,200 行)。仕様書 v3.2 準拠。動作未検証 | 履歴 |
| BASELINE-2 | 分割ソース 30 ファイル化。round-trip 未達成(18/24 失敗) | 履歴 |
| BASELINE-3(現行) | 全 Fix 適用後。round-trip 完全一致(24/24)。bundle 動作確認済み | current |
| BASELINE-4(目標) | dev ESM 完全動作 + 未解決バグ 0 | 未達 |
3. 完了した作業
3.1 ツール基盤(scripts/)
| ファイル | 役割 |
|---|---|
bundle.mjs | 分割ソース → 単一 HTML |
split.mjs | 単一 HTML → 分割ソース |
verify.mjs | round-trip 検証(bundle 経由) |
設計の要点:
String.replace(re, fn)関数渡しで$特殊展開を回避($$破損バグの根治)exportキーワードを触らない(multiple exports in single module は合法)import行のみ除去、bundle 時に外部 import を hoist</script>を<\/script>にエスケープverify.mjsは末尾改行を正規化してから比較
3.2 ディレクトリ構造
public/tools/text-chunker/├── index.html HTML テンプレート(dev ESM entry)├── manifest.json ビルド設定├── package.json npm scripts├── scripts/│ ├── bundle.mjs│ ├── split.mjs│ └── verify.mjs├── styles/│ ├── 00-base.css│ ├── 10-layout.css│ ├── 20-components.css│ ├── 30-editor.css│ └── 40-theme-light.css├── js/│ ├── 00-main.js entry、boot 呼び出し│ ├── 10-utils.js $, $$, uid, now, debounce, escHtml, ...│ ├── 20-count.js countString│ ├── 30-safe-pos.js isCombiningMark, isSafePosition, ...│ ├── 40-candidates.js buildLineStarts, buildFenceSet, ...│ ├── 50-storage.js STORES, Store, initStorage│ ├── 60-model.js app, defaultParams, migrateParams, ...│ ├── 70-compose.js composeOutput, overheadFor, computeGaps, ...│ ├── 80-split.js chooseEnd, verifyFit, splitGap, ...│ ├── 90-editor.js CodeMirror 6, gutter, plugin, ...│ ├── 100-detail-panel.js 境界詳細パネル│ ├── 110-ui.js toast, dialog, persistNow, ...│ ├── 120-crud.js document / chunk CRUD│ ├── 130-tree.js サイドバー、コンテキストメニュー│ ├── 140-workflow.js 分割・並び替え・fit・copy&mark│ ├── 150-checkpoint.js checkpoint、diff│ ├── 160-dialogs.js 各種ダイアログ│ ├── 170-wireui.js ACTION_MAP、wireUI│ └── 180-boot.js boot└── dist/ └── text_chunker.html bundle 生成物(本番)4. 適用した Fix 一覧(BASELINE-1 → BASELINE-3)
4.1 ツール・構造
| Fix | 内容 |
|---|---|
| 分割ソース化 | 単一 HTML → 30 ファイル |
| bundle/split/verify | round-trip ツール 3 本 |
String.replace 修正 | 関数渡しで $ 特殊展開回避 |
| directive 保持 | @import / @export を原文のまま保持 |
4.2 UI / レイアウト
| Fix | 内容 |
|---|---|
| 3 行ヘッダー | Row1: ☰/Title/File/Chunks/⚙ · Row2: ◀▶/chunkStatus/🔍/? · Row3: ↤↦/Content|Changes/Copy&MarkDone/↶/⋮ |
| footer 安全化 | position: fixed + --app-height(visualViewport)+ env(safe-area-inset-*) |
| ドロップダウン | intrinsic 計測 → 上下左右反転 → 高さ clamp |
| chunkStatus コンパクト化 | 2 行 → 1 行、詳細は footer 右下へ |
| Master merge | File ▾ → Merge master files… |
| Code blocks zip | プレースホルダー + README + index.tsv |
| 短縮ラベル | Copy & Mark Done → Copy & Done(狭幅) |
4.3 機能追加
| Fix | 内容 |
|---|---|
headingPattern | 自由 regex + プリセット(#, ##, ###) |
| Split settings 刷新 | リセットボタン + 並び替え + Auto split チェック |
margin 削除 | limit に統合(migrateParams で自動移行) |
| Auto-split トグル | footer ⚡Auto / ⏸Manual + Split settings |
| テキスト選択可能化 | drawSelection() 除去 + user-select CSS |
| Markdown 色付け | syntaxHighlighting + .tok-* CSS |
| 空白可視化 | Ctrl/Cmd+Shift+W トグル + .cm-ws-* |
| Gap 計測 | computeGaps + footer 表示 + gapWhitespace 設定 |
| Breakdown popover | footer #fChunkStatus クリックで内訳 |
| Legend パネル | ? ボタン → トグルパネル |
| ガター chunk 番号 | #N Title を chunk 開始行に表示 |
| Chunk 並び替え | Move up / Move down(隣接条件付き) |
| ガター cache | chunkLayoutRevField + _ensureLayoutCache + binary search |
| Diff 位置合わせ | font/line-height/padding を CodeMirror と一致 |
4.4 バグ修正・監査
| Fix | 内容 |
|---|---|
| A | 80-split.js の uid import |
| B1 | split.mjs の (?![\w$]) boundary |
| B2 | enforceI2 の zero-length prev |
| B3 | clearAllChunksPrompt で autos = [] |
| B4 | applyMergeMaster の ChangeSet 使用(注: import 未追加、後述 §6.2) |
| B5 | changeFilterFn 拒否 toast |
| C | Code blocks zip プレースホルダー |
| D | テキスト選択可能化 |
| E | dialog backdrop close を pointerdown に |
| J | 180-boot.js の showStorageDialog 参照元(110-ui → 160-dialogs) |
| P3 | autoSplit デフォルト false |
| P4 | autoSplitOnPaste 削除 |
| P5 | #fChunkStatus の DOM キャッシュ |
| P6 | updateEditorTopDebounced(100ms) |
| P7 | 位置変化時のみ dirty 化 |
| P8 | _nameCache 部分 eviction |
| U1 | migrateParams 通知 |
| U5 | footer Sel 空時の二重セパレータ解消 |
| R3 | splitGap の heading 候補 hoist |
| R5 | chunkStateLabel 一元化 |
5. 現状の動作確認
5.1 verify(round-trip)— ✅ 成功
$ node scripts/verify.mjs✓ bundled 5 css + 19 js → tmp\bundled.html✓ split → tmp\recovered (5 css, 19 js)...✓ All files match (24 files)5.2 bundle モード — ✅ 動作確認済み
dist/text_chunker.html を python3 -m http.server 経由でブラウザで開くと動作する。
5.3 dev ESM モード — ❌ 動作せず
index.html を直開きすると Uncaught SyntaxError で停止。詳細は §6。
6. dev ESM の既知バグ一覧
6.1 症状の根本原因
bundle.mjs は import 行を完全に除去して単一 <script> に連結するため、bundle モードでは「スコープが 1 つ」になり import の不整合が隠蔽される。dev ESM では各ファイルが独立モジュールなので、明示的な import が必須。
実装時に「循環依存を避けるため import を意図的に省略」した箇所が複数あり、それらが dev ESM でエラーになる。
6.2 既知のエラー
| # | ファイル:行 | 内容 | 種別 |
|---|---|---|---|
| E1 | 140-workflow.js:23 | buildLineStarts, buildFenceSet を ./80-split.js から import しようとしている。実際は ./40-candidates.js で定義 | parse-time |
| E2 | 160-dialogs.js | ChangeSet を使用(applyMergeMaster)するが未 import | runtime |
| E3 | 170-wireui.js | ACTION_MAP が参照する約 25 関数(downloadChunk, saveAllChunksZip, splitAuto, navNext, undoDone, …)が未 import | runtime |
| E4 | 180-boot.js | renderTree, updateEditorTop, updateFooterCounts, pinChunk, markChunkDirty, recomputeAutoChunks, updateNoRoomBanner, updateDoneEditBanner, positionDropdown が未 import | runtime |
| E5 | 100-detail-panel.js | toast, dialog, pushChunkUndo, selectChunk, markNotDone, setViewMode, Store 等が未 import | runtime |
| E6 | 130-tree.js | closeSidebarIfMobile, previewCheckpoint, refreshOverlaps 等が未 import | runtime |
| E7 | 120-crud.js | persistNow, setViewMode, renderTree, scheduleSaveLastState, setUnsaved, updateFooterCounts, refreshEditorRanges, redrawEditorChunks, invalidateCaches, closeDetailPanelForce, updateCursorInTree, markChunkDirty, toast, confirmAsync, dialog, pushChunkUndo, closeSidebarIfMobile 等が未 import | runtime |
6.3 潜在的な循環依存
明示 import を追加すると、以下の循環が顕在化する可能性がある:
120-crud ──→ 140-workflow ──→ 120-crud (refreshChunkUI / selectChunk)130-tree ──→ 140-workflow ──→ 130-tree (canMoveUp / renderTree)140-workflow ──→ 160-dialogs ──→ 140-workflow (loadJSZip / refreshChunkUI)ESM の循環 import は 関数宣言の遅延解決 で動作する場合がある(呼び出し時に binding が解決される)。ただし:
const/letで宣言された export は循環時に TDZ エラー- モジュールトップレベルで import 値を即時使用すると失敗
10-utils.js の $, $$ は export const だが、循環参照されないため問題なし。
7. Batch 4 修正計画 — dev ESM 完全動作
7.1 目標
- dev ESM モード(
index.html直開き)で Console エラー 0 - bundle モードも引き続き動作(既存の verify が
All files matchを維持) - 新規の循環依存を導入しない
7.2 手順(推奨順序)
Step 1: 静的監査ツールの作成(新規 scripts/audit-imports.mjs)
各 JS ファイルを走査して:
- 宣言済み export 名の一覧
- import 文の一覧
- コード本体で使用されている識別子(関数呼び出し / 変数参照)
- 未 import かつ未宣言の識別子を抽出
出力: js/*.js の不足 import を機械的に列挙。これを元に修正リストを作る。
Step 2: E1 の修正(parse-time エラーを最初に解消)
js/140-workflow.js の 23 行目を修正:
// Before// @import: { recomputeAutoChunks, makePersistedChunk, chooseEnd, verifyFit, buildLineStarts, buildFenceSet, lastSplitError } from './80-split.js';import { recomputeAutoChunks, makePersistedChunk, chooseEnd, verifyFit, buildLineStarts, buildFenceSet, lastSplitError } from './80-split.js';
// After// @import: { recomputeAutoChunks, makePersistedChunk, chooseEnd, verifyFit, lastSplitError } from './80-split.js';// @import: { buildLineStarts, buildFenceSet } from './40-candidates.js';import { recomputeAutoChunks, makePersistedChunk, chooseEnd, verifyFit, lastSplitError } from './80-split.js';import { buildLineStarts, buildFenceSet } from './40-candidates.js';その後 node scripts/verify.mjs で bundle 経由の round-trip が壊れていないことを確認。
Step 3: E2 の修正(160-dialogs.js の ChangeSet)
// @import: { ChangeSet } from '@codemirror/state';import { ChangeSet } from '@codemirror/state';Step 4: E5 / E6 / E7 の修正(100 / 130 / 120)
静的監査ツールの出力を元に、各ファイルの不足 import を追加。
循環依存が顕在化した場合の対処:
120-crud⇄140-workflow:refreshChunkUI/selectChunkを相互に使う- 対処 1:
refreshChunkUIを110-ui.jsへ移動(UI 更新関数) - 対処 2:
140-workflowから120-crudへの依存を関数引数化 - 対処 3: 遅延参照(
window.__refreshChunkUI経由)— 推奨しない
- 対処 1:
Step 5: E3 / E4 の修正(170-wireui / 180-boot)
ACTION_MAP は 25 関数を参照。すべてを import する:
import { saveAllChunksZip, saveMaster, copyAllChunks, copyMaster, splitAuto, splitChapter, manualSplitAtCursor, undoLastChunkOp, promoteAllAuto, removeZeroChunks, clearAllChunksPrompt, copyChunkToClipboard, downloadChunk, copyAndMarkDone, undoDone, copyAndMarkDoneChunk, markNotDone, refitCurrentChunk, manualSplitAtCursor, ...} from './140-workflow.js';import { selectChunk, navPrev, navNext, jumpHead, jumpTail, newDocument, pasteAsNewDoc } from './120-crud.js';import { showChunkContextMenu, renderTree } from './130-tree.js';import { openDetailPanel, openNotesDialog, previewOutput } from './...';同様に 180-boot.js:
import { renderTree, showChunkContextMenu } from './130-tree.js';import { updateEditorTop, updateFooterCounts, refreshChunkUI } from './140-workflow.js';import { pinChunk, openDocument, selectChunk } from './120-crud.js';Step 6: 全ファイルの audit 再実行
scripts/audit-imports.mjs を再実行し、不足 0 を確認。
Step 7: dev ESM 実機確認
cd public/tools/text-chunkerpython3 -m http.server 8000# → http://localhost:8000/index.html を開く確認項目:
- Console エラー 0
- 起動する(“Untitled” ドキュメント表示)
- テキスト貼り付け → auto split(ON 時)
- Copy & Mark Done 動作
- Chunks ▾ メニュー動作
- File ▾ → Merge master files… 動作
- Code blocks… 動作
- Split settings 動作
Step 8: bundle モード回帰確認
node scripts/bundle.mjsnode scripts/verify.mjs # → All files matchdist/text_chunker.html をブラウザで開き、dev ESM と同じ動作を確認。
7.3 落とし穴
| # | 内容 | 対処 |
|---|---|---|
| 1 | 循環 import で const export が TDZ エラー | 関数宣言に変更 or 循環解消 |
| 2 | Store は export let(live binding) | initStorage() 前後で値が変わる。dev ESM で import { Store } した側は初期値 null を保持するため、参照タイミングに注意 |
| 3 | lastSplitError は export let | 同上。80-split.js で書き換え、110-ui.js で読む場合は live binding で動く |
| 4 | ACTION_MAP はモジュールトップレベルで関数参照をキャプチャ | 循環 import で未定義になる可能性 → ACTION_MAP を関数内で構築 or getter 化 |
| 5 | @export directive と実 export の同期 | 修正したら両方更新(verify で検出される) |
| 6 | bundle 後の import 除去 | bundle.mjs は import 行を除去するので、dev ESM 専用 import も bundle で問題なし |
7.4 完了条件
-
scripts/audit-imports.mjsが「不足 import 0」を報告 - dev ESM(
index.html直開き)で Console エラー 0 - dev ESM で起動 + 基本操作(貼り付け / split / copy&mark / menu)が動作
-
node scripts/verify.mjsがAll files match (24 files)を維持 -
dist/text_chunker.htmlの動作が dev ESM と一致 - 受入テスト T1〜T44 が全て pass
7.5 修正ファイル数の見積
| ファイル | 追加 import 数(推定) |
|---|---|
120-crud.js | 10〜20 |
130-tree.js | 5〜10 |
140-workflow.js | 2〜5(E1 + 循環回避) |
160-dialogs.js | 1(ChangeSet) |
170-wireui.js | 25〜30 |
180-boot.js | 8〜12 |
100-detail-panel.js | 5〜10 |
| 合計 | ~60〜90 追加 import |
8. 未解決タスク(Batch 4 以降)
| # | 内容 | 優先度 | 担当 |
|---|---|---|---|
| U-1 | dev ESM 完全動作(§7) | 高 | Batch 4 |
| U-2 | 実機テスト T1〜T44 | 高 | Batch 4 検証 |
| U-3 | Move to... ダイアログ(多段移動) | 中 | Batch 5 |
| U-4 | ファイル肥大化(160-dialogs.js 1000 行超) | 低 | Batch 5 |
| U-5 | rangeGutter / cutLinePlugin の cache 統合 | 低 | Batch 5 |
| U-6 | renderTree の RAF バッチ化 | 低 | Batch 6 |
9. 開発・検証ワークフロー
9.1 通常の作業
# ソース編集vim js/140-workflow.js
# bundle 生成node scripts/bundle.mjs# → dist/text_chunker.html
# round-trip 検証node scripts/verify.mjs# → All files match (24 files)
# bundle 版で動作確認python3 -m http.server 8000# → http://localhost:8000/dist/text_chunker.html9.2 LLM ワークフロー
bundle.mjsでdist/text_chunker.htmlを生成- LLM に単一 HTML を渡して編集させる
- 戻ってきた HTML を
split.mjsで分割ソースに再展開 verify.mjsで整合性確認
9.3 dev ESM 確認(Batch 4 後)
python3 -m http.server 800010. 安全性
| Script | 読む | 書く |
|---|---|---|
bundle.mjs | js/*, styles/*, index.html | dist/text_chunker.html |
split.mjs | dist/text_chunker.html | src-recovered/*(src/ ではない) |
verify.mjs | src/*, dist/* | tmp/* |
src/ を壊す操作は存在しない。 手動で src-recovered/* を src/ にコピーする時だけ注意。手動バックアップは不要。
11. 参考リンク
- 仕様書 v3.3: 2026-09-27-text-chunker-spec
- 分割化指示書: 2026-09-27-text-chunker-splitting-instructions
付録 A: BASELINE-3 到達時点の verify 出力
$ node scripts/verify.mjs▸ bundle into tmp…✓ bundled 5 css + 19 js → tmp\bundled.html (288,040 bytes)✓ split → tmp\recovered (5 css, 19 js)▸ comparing… ✓ css styles/00-base.css ✓ css styles/10-layout.css ✓ css styles/20-components.css ✓ css styles/30-editor.css ✓ css styles/40-theme-light.css ✓ js js/00-main.js ✓ js js/10-utils.js ...(全 24 ファイル)✓ All files match (24 files)付録 B: BASELINE-3 到達時点のエラーログ(dev ESM)
contentscript.js:14083 MaxListenersExceededWarning ... (ブラウザ拡張、無関係)text-chunker/:188 GET cloudflareinsights.com/beacon.min.js (広告ブロッカー、無関係)140-workflow.js:23 Uncaught SyntaxError: The requested module './80-split.js' does not provide an export named 'buildFenceSet'注目: 180-boot.js の showStorageDialog エラーは履歴削除で解消済み。次の層のエラー(140-workflow.js)が露出した状態。
付録 C: 次エージェントへのチェックリスト
Batch 4 開始時:
- §7.2 の Step 1〜8 を順に実行
-
scripts/audit-imports.mjsを新規作成(実装は自由、Node stdlib のみ使用) - E1〜E7 を順に修正(parse-time エラーを先に)
- 循環依存が顕在化したら §7.3 の落とし穴を参照
- 各ステップ後に
node scripts/verify.mjsで bundle 経由の round-trip を確認 - 完了条件 §7.4 を全項目チェック
- 引き継ぎ書(本ファイル)に Batch 4 完了セクションを追記
付録 D: 変更禁止事項
manifest.jsonのmarker文法bundle.mjs/split.mjs/verify.mjsの動作仕様(round-trip 保証)90-editor.jsの CodeMirror バージョン(6.4.1)- データモデル(§9 of 仕様書)
- UI 文言(§15 of 仕様書)