log

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 不整合で動作せず

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.mjsround-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/verifyround-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 mergeFile ▾ → 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 popoverfooter #fChunkStatus クリックで内訳
Legend パネル? ボタン → トグルパネル
ガター chunk 番号#N Title を chunk 開始行に表示
Chunk 並び替えMove up / Move down(隣接条件付き)
ガター cachechunkLayoutRevField + _ensureLayoutCache + binary search
Diff 位置合わせfont/line-height/padding を CodeMirror と一致

4.4 バグ修正・監査

Fix内容
A80-split.js の uid import
B1split.mjs の (?![\w$]) boundary
B2enforceI2 の zero-length prev
B3clearAllChunksPrompt で autos = []
B4applyMergeMaster の ChangeSet 使用(注: import 未追加、後述 §6.2)
B5changeFilterFn 拒否 toast
CCode blocks zip プレースホルダー
Dテキスト選択可能化
Edialog backdrop close を pointerdown に
J180-boot.js の showStorageDialog 参照元(110-ui → 160-dialogs)
P3autoSplit デフォルト false
P4autoSplitOnPaste 削除
P5#fChunkStatus の DOM キャッシュ
P6updateEditorTopDebounced(100ms)
P7位置変化時のみ dirty 化
P8_nameCache 部分 eviction
U1migrateParams 通知
U5footer Sel 空時の二重セパレータ解消
R3splitGap の heading 候補 hoist
R5chunkStateLabel 一元化

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 既知のエラー

#ファイル:行内容種別
E1140-workflow.js:23buildLineStarts, buildFenceSet を ./80-split.js から import しようとしている。実際は ./40-candidates.js で定義parse-time
E2160-dialogs.jsChangeSet を使用(applyMergeMaster)するが未 importruntime
E3170-wireui.jsACTION_MAP が参照する約 25 関数(downloadChunk, saveAllChunksZip, splitAuto, navNext, undoDone, …)が未 importruntime
E4180-boot.jsrenderTree, updateEditorTop, updateFooterCounts, pinChunk, markChunkDirty, recomputeAutoChunks, updateNoRoomBanner, updateDoneEditBanner, positionDropdown が未 importruntime
E5100-detail-panel.jstoast, dialog, pushChunkUndo, selectChunk, markNotDone, setViewMode, Store 等が未 importruntime
E6130-tree.jscloseSidebarIfMobile, previewCheckpoint, refreshOverlaps 等が未 importruntime
E7120-crud.jspersistNow, setViewMode, renderTree, scheduleSaveLastState, setUnsaved, updateFooterCounts, refreshEditorRanges, redrawEditorChunks, invalidateCaches, closeDetailPanelForce, updateCursorInTree, markChunkDirty, toast, confirmAsync, dialog, pushChunkUndo, closeSidebarIfMobile 等が未 importruntime

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 経由)— 推奨しない

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 実機確認

Terminal window
cd public/tools/text-chunker
python3 -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 モード回帰確認

Terminal window
node scripts/bundle.mjs
node scripts/verify.mjs # → All files match

dist/text_chunker.html をブラウザで開き、dev ESM と同じ動作を確認。

7.3 落とし穴

#内容対処
1循環 import で const export が TDZ エラー関数宣言に変更 or 循環解消
2Store は export let(live binding)initStorage() 前後で値が変わる。dev ESM で import { Store } した側は初期値 null を保持するため、参照タイミングに注意
3lastSplitError は export let同上。80-split.js で書き換え、110-ui.js で読む場合は live binding で動く
4ACTION_MAP はモジュールトップレベルで関数参照をキャプチャ循環 import で未定義になる可能性 → ACTION_MAP を関数内で構築 or getter 化
5@export directive と実 export の同期修正したら両方更新(verify で検出される)
6bundle 後の 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.js10〜20
130-tree.js5〜10
140-workflow.js2〜5(E1 + 循環回避)
160-dialogs.js1(ChangeSet)
170-wireui.js25〜30
180-boot.js8〜12
100-detail-panel.js5〜10
合計~60〜90 追加 import

8. 未解決タスク(Batch 4 以降)

#内容優先度担当
U-1dev ESM 完全動作(§7)高Batch 4
U-2実機テスト T1〜T44高Batch 4 検証
U-3Move to... ダイアログ(多段移動)中Batch 5
U-4ファイル肥大化(160-dialogs.js 1000 行超)低Batch 5
U-5rangeGutter / cutLinePlugin の cache 統合低Batch 5
U-6renderTree の RAF バッチ化低Batch 6

9. 開発・検証ワークフロー

9.1 通常の作業

Terminal window
# ソース編集
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.html

9.2 LLM ワークフロー

  1. bundle.mjs で dist/text_chunker.html を生成
  2. LLM に単一 HTML を渡して編集させる
  3. 戻ってきた HTML を split.mjs で分割ソースに再展開
  4. verify.mjs で整合性確認

9.3 dev ESM 確認(Batch 4 後)

8000/index.html
python3 -m http.server 8000

10. 安全性

Script読む書く
bundle.mjsjs/*, styles/*, index.htmldist/text_chunker.html
split.mjsdist/text_chunker.htmlsrc-recovered/*(src/ ではない)
verify.mjssrc/*, 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 仕様書)