Text Chunker 分割化指示書 v2(双方向対応)
Text Chunker 分割化指示書 v2(双方向対応)
0. この文書の位置付け
本稿は、単一 HTML で構成されている Text Chunker を 双方向変換可能な分割ソース + ビルド 方式に移行するための作業指示書である。
- 機能一覧: Text Chunker 引き継ぎレポート — 分割ソース化・BASELINE-3 到達と Batch 4 修正計画
- 要件: 2026-09-27-text-chunker-spec
- 本作業は「リファクタリング」であり、機能追加・仕様変更は行わない。
v1 との差分:
- ファイル境界マーカーを必須化(
split逆変換を可能にするため) split.mjs/verify.mjsを追加(round-trip 検証)- 汎用化戦略を §11 に記載(将来検討用)
1. 前提
1.1 現状
text_chunker.htmlが 単一ファイル(約 5,200 行) として存在- 5 バッチに分けて生成されたものを、ユーザーが連結済み
- 機能は Phase 1〜7 完了、仕様書 v3.2 に準拠
- 動作検証は未実施
1.2 問題意識
| 問題 | 影響 |
|---|---|
| 1 ファイル 5,200 行 | 修正箇所の特定に時間がかかる |
| 全文再生成が必要 | 1 箇所の修正で 5 バッチ出力が必要 |
| LLM に渡す単位が大きすぎる | コンテキスト消費、編集の粒度が粗い |
| 単体テスト不可 | 1 関数の検証にも全体起動が必要 |
1.3 解決方針
- 開発時: 分割ソースを native ESM で読み込み(ビルド不要、
python3 -m http.serverで即時反映) - 配布時:
bundle.mjsで単一 HTML に結合 - 逆変換:
split.mjsで単一 HTML から分割ソースを復元 - 保証:
verify.mjsで round-trip の等価性を検証
1.4 なぜ双方向が必要か
LLM とのワークフローを柔軟にするため:
| ワークフロー | 使うツール |
|---|---|
自分で src/ を編集 | bundle.mjs |
| LLM に単一 HTML を渡して編集させる | bundle.mjs → 編集 → split.mjs |
旧バージョンの単一 HTML を src/ に取り込む | split.mjs |
| 回帰防止 | verify.mjs |
「LLM に単一 HTML を渡して編集させ、戻ってきたものを分割ソースに再展開する」 が、今後の主ワークフローになる。
2. 目標
2.1 成果物(全 31 ファイル)
text-chunker/├── index.html (HTML テンプレート)├── manifest.json (ビルド設定)├── scripts/│ ├── bundle.mjs (分割 → 単一 HTML)│ ├── split.mjs (単一 HTML → 分割)│ └── verify.mjs (round-trip 検証)├── 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 ├── 20-count.js ├── 30-safe-pos.js ├── 40-candidates.js ├── 50-storage.js ├── 60-model.js ├── 70-compose.js ├── 80-split.js ├── 90-editor.js ├── 100-detail-panel.js ├── 110-ui.js ├── 120-crud.js ├── 130-tree.js ├── 140-workflow.js ├── 150-checkpoint.js ├── 160-dialogs.js ├── 170-wireui.js └── 180-boot.js2.2 非目標
- 機能追加・仕様変更
- 変数名の意味的リネーム(
startOffset→startなどはしない) - パフォーマンス最適化
- 汎用ツール化(§11 で方針のみ提示)
純粋な「同一コードの双方向分割」である。ロジックには一切手を加えない。
3. ファイル分割マップ
3.1 CSS(5 ファイル)
| ファイル | 内容 | 元の行範囲 |
|---|---|---|
00-base.css | * reset / html, body / #app / #storageBanner | L1〜40 |
10-layout.css | #topbar / #sidebar / #main / #editorPane / #editorTop / #editorContainer / #detailPanel / #footer / レスポンシブ | L41〜250 |
20-components.css | .btn / .dropdown / .tree-* / #searchPanel / #toastContainer / .toast / .dialog / #contextMenu | L251〜450 |
30-editor.css | .cm-* / #diffView / .notesIndicator / #viewModeSeg / スクロールバー | L451〜560 |
40-theme-light.css | html[data-theme="light"] 全般 | L561〜640 |
3.2 JS(19 ファイル)
以下、各ファイルの責務と、含まれるべき関数・定数の一覧。
| ファイル | 推定行数 | 内容 |
|---|---|---|
00-main.js | 30 | import 集約 + boot() 呼び出し + window.__app = app |
10-utils.js | 60 | $, $$, uid, now, debounce, escHtml, sanitizeFilename, toLF, toCRLF, fmtBytes |
20-count.js | 40 | countString |
30-safe-pos.js | 60 | isCombiningMark, isSafePosition, safeFloor, nextSafe |
40-candidates.js | 130 | buildLineStarts, lineIndexAtArr, reFenceStart, isCodeFenceStart, fenceDelim, isCodeFenceEnd, buildFenceSet, findHeadingCandidates, findBlankCandidates, findLineCandidates, findSentenceCandidates, lastLE, firstGT |
50-storage.js | 200 | STORES, makeMemoryBackend, makeLSBackend, makeIDBBackend, probeIDB, probeLS, openIDB, Store, initStorage |
60-model.js | 150 | defaultParams, defaultOutput, defaultSettings, app, chunkKey, chunkStateLabel, allChunks, findChunkByKey, currentChunk |
70-compose.js | 180 | truncate30, computeName, expandTpl, stripNL, contentTextOf, resolveBefore, resolveAfter, isCrlfCount, composeOutput, countOutputStr, effectiveLimit, countBetween, overheadFor |
80-split.js | 300 | chooseEnd, verifyFit, overlapStart, splitGap, lastSplitError, recomputeAutoChunks, makeAutoChunk, makePersistedChunk |
90-editor.js | 500 | dirty/schedule, mapPos, effects/compartments, StateField, gutter, plugins, theme, filter/paste, extensions, cache, update dispatcher, cursor, redraw |
100-detail-panel.js | 350 | 詳細パネルの全関数 |
110-ui.js | 250 | toast, dialog, confirmAsync, download, copyToClipboard, showContextMenu, setUnsaved, settings 永続化, loadAllData, makeDocument, banners |
120-crud.js | 350 | document CRUD, chunk CRUD, navigation, overlap, badges |
130-tree.js | 300 | renderTree, showChunkContextMenu |
140-workflow.js | 400 | split/merge/align, undo, copy&mark, fit, updateEditorTop, refreshChunkUI, footer, bulk copy/save |
150-checkpoint.js | 300 | dmp, edit array, renderDMPLineDiff, renderSimpleDiff, checkpoint system |
160-dialogs.js | 600 | wrapper presets, notes, split settings, snippets, log, stats, storage, code blocks, count mode, app settings, preview, search, JSON, view mode |
170-wireui.js | 400 | ACTION_MAP, closeAllDropdowns, positionDropdown, wireUI |
180-boot.js | 150 | boot(定義のみ), initPart5, setupVisualViewport, startInlineRename, wireInlineRename, insertCheckpointMenuItems |
3.3 ルートファイル
| ファイル | 内容 |
|---|---|
index.html | 既存 HTML 構造を保持。<style> → <link> 5 本、<script type="module"> → <script type="module" src="./js/00-main.js"> |
manifest.json | ビルド設定(§5 参照) |
scripts/bundle.mjs | 分割 → 単一 HTML |
scripts/split.mjs | 単一 HTML → 分割 |
scripts/verify.mjs | round-trip 検証 |
4. ファイル境界マーカー(必須)
4.1 目的
split.mjs が単一 HTML からファイル境界を復元するための唯一の手がかり。
コード内にマーカーコメントを埋め込むことで、逆変換を可能にする。
4.2 各ソースファイルの形式
JS ファイルの先頭:
// === @file: js/70-compose.js ===// @import: { app } from './60-model.js';// @import: { countString } from './20-count.js';// @export: composeOutput, countOutputStr, effectiveLimit
import { app } from './60-model.js';import { countString } from './20-count.js';
export function composeOutput(chunk, i, n, masterText, forCopy) { // ...}export function countOutputStr(str) { // ...}export function effectiveLimit() { // ...}CSS ファイルの先頭:
/* === @file: styles/20-components.css === */
.btn { /* ... */}4.3 ディレクティブの文法
| ディレクティブ | 必須 | 内容 |
|---|---|---|
// === @file: {path} === | ✅ | ファイルパス(js/ または styles/ 相対) |
// @import: { statement }; | JS のみ | 1 行 1 import。複数行可 |
// @export: name1, name2 | JS のみ | export する名前の一覧 |
ルール:
- マーカーはファイルの 1 行目(先頭の改行・空白は不可)
@fileは 1 ファイルに 1 つだけ@import/@exportは@fileの直後にまとめて書く@exportの名前はカンマ区切り
4.4 ディレクティブと実コードの関係
- ディレクティブはメタデータ(bundle / split の手がかり)
- 実コードの
import/exportは残す(dev 時の native ESM 実行のため) - 両者は内容が一致していること(
verify.mjsが検証)
4.5 単一 HTML 出力時の形式
bundle.mjs は各ファイルを以下の形式で連結:
// === @file: js/10-utils.js ===// @import: (none)// @export: $, $$, uid, now, debounce, escHtml, sanitizeFilename, toLF, toCRLF, fmtBytesconst $ = (s, r = document) => r.querySelector(s);const $$ = (s, r = document) => [...r.querySelectorAll(s)];// ...
// === @file: js/20-count.js ===// @import: (none)// @export: countStringfunction countString(s, mode, crlf) { // ...}ポイント:
import文は除去される(単一スコープに統合)exportキーワードは除去される(export function→function)- ディレクティブはコメントとして残す(split の手がかり)
5. ビルド設定(manifest.json)
{ "name": "text-chunker", "template": "index.html", "styles": "styles/*.css", "scripts": "js/*.js", "entry": "js/00-main.js", "output": "dist/text_chunker.html", "marker": { "file": "=== @file: ", "import": "@import:", "export": "@export:" }}6. スクリプトの仕様
6.1 scripts/bundle.mjs
入力: src/ 全体 + index.html + manifest.json
出力: dist/text_chunker.html(単一ファイル)
処理:
1. manifest.json を読む2. styles/*.css をファイル名順に読む3. js/*.js を依存グラフ順に読む - @import を解析してトポロジカルソート - 循環依存があればエラー4. 各 JS ファイルから: - `import` 行(行頭が `import `)を除去 - `export ` キーワードを除去(`export function` → `function` など) - ディレクティブコメントは保持5. CSS を `/* === @file: ... */` 付きで連結6. JS を `// === @file: ... ===` 付きで連結7. index.html のテンプレートを読む: - `<link rel="stylesheet">` を 1 つの `<style>` に置換 - `<script type="module" src="./js/00-main.js">` をインライン `<script type="module">` に置換8. dist/text_chunker.html に書き出し依存なし(Node.js の fs / path のみ)。
6.2 scripts/split.mjs
入力: dist/text_chunker.html(単一ファイル)
出力: src-recovered/ 配下に 24 ファイル
処理:
1. 単一 HTML を読む2. `<style>` 内を抽出 → `/* === @file: ... */` で分割3. `<script type="module">` 内を抽出 → `// === @file: ... ===` で分割4. 各 JS ブロックから: - @import ディレクティブを読む - @export ディレクティブを読む - @export の各名前について `function name(` → `export function name(` に書き換え - `const name =` → `export const name =` に書き換え - 冒頭に import 文を再構築して挿入5. src-recovered/ に書き出し注意: @export に列挙された名前を、コード内で発見して export を付与する。regex で ^\s*(async\s+)?function\s+name\b / ^\s*(const|let|var)\s+name\b / ^\s*class\s+name\b を探す。
6.3 scripts/verify.mjs
入力: src/ と dist/text_chunker.html
出力: 標準出力に差分レポート
処理:
1. dist/text_chunker.html を tmp/recovered/ に split2. src/ と tmp/recovered/ をファイル単位で比較3. 全ファイルが一致すれば exit 0、不一致なら exit 14. 差分があればファイル名と行番号を表示6.4 package.json(任意)
npm を使う場合:
{ "name": "text-chunker", "private": true, "type": "module", "scripts": { "bundle": "node scripts/bundle.mjs", "split": "node scripts/split.mjs", "verify": "node scripts/verify.mjs", "dev": "python3 -m http.server 8000" }}npm を使わない場合、直接 node scripts/bundle.mjs を実行。
7. 実装規約
7.1 モジュール規約
- 各ファイルは
export function name() {}またはexport const name = ...で公開 - 依存は
import { name } from './NN-xxx.js'で明示(同時に@importディレクティブにも書く) appオブジェクトは60-model.jsからのみ export- 副作用のある module-level コード(
window.addEventListenerなど)は許容、ただしwireUI/initPart5内に集約 - 循環依存を避ける。避けられない場合は関数宣言(
function)を使用
7.2 命名規約
- ファイル名:
NN-name.js/NN-name.css - 変数名・関数名: 既存コードから一切変更しない
7.3 round-trip のための制約
| # | 制約 | 理由 |
|---|---|---|
| 1 | import は行頭に 1 行ずつ | regex で除去可能 |
| 2 | 複数行 import 禁止 | import { a,\n b } は除去できない |
| 3 | トップレベル await 禁止 | concat 順序が不定になる |
| 4 | import.meta 禁止 | bundle 後に意味が変わる |
| 5 | 副作用は boot() に集約 | 連結順序への依存を排除 |
| 6 | 変数名は全体で一意 | グローバル衝突回避 |
| 7 | ミニファイしない | byte-exact の round-trip のため |
| 8 | 文字列リテラルは 1 行で書く | 複数行テンプレートは保持する |
7.4 文字列リテラルの扱い
テンプレートリテラル(バッククォート)内に @file や import が含まれる場合、split が誤動作する可能性がある。
対策:
- テンプレートリテラル内で
=== @file:や// @import:を書かない - やむを得ず書く場合は
\u0040などエスケープする
現行コードでは該当箇所は少ないが、buildDetailHeader などのテンプレートを確認すること。
8. 開発フロー
8.1 通常の編集
# 1. 編集vim src/js/140-workflow.js
# 2. サーバー起動cd srcpython3 -m http.server 8000
# 3. ブラウザで http://localhost:8000/ を開く注意: file:// では動かない(Clipboard API が secure context 必須)。
8.2 単一 HTML 生成
node scripts/bundle.mjs# → dist/text_chunker.html 生成8.3 単一 HTML から復元
# dist/text_chunker.html を編集した後node scripts/split.mjs# → src-recovered/ に展開
# 手動で src/ にマージdiff -r src/ src-recovered/8.4 round-trip 検証
node scripts/verify.mjs# → "All files match" が出れば OK9. 検証手順
9.1 起動確認(必須)
python3 -m http.server 8000で起動http://localhost:8000/を開く- Console にエラーが出ないこと
Untitledドキュメントが表示されること- テキストを貼り付けて自動分割が動くこと
- Copy & Mark Done が動くこと
9.2 round-trip 検証(必須)
node scripts/verify.mjs期待: 全 24 ファイルで ”✓” が表示され、“All files match” で終了。
9.3 単一 HTML 検証
node scripts/bundle.mjs生成された dist/text_chunker.html を別のブラウザタブで開き、開発版と同じ動作をすることを確認。
9.4 受入テスト
2026-09-27-text-chunker-spec §14 の T1〜T27 を、結合版 dist/text_chunker.html に対して実行。
開発版では動くが結合版で動かない場合、ビルドの問題。
10. 完了条件
- 全 31 ファイルが生成されている(
index.html,manifest.json, scripts×3, CSS×5, JS×19) - 各ソースファイルの先頭に
// === @file: ... ===マーカーがある - 各 JS ファイルに
@import/@exportディレクティブがある -
python3 -m http.serverで起動し、エラーが出ない -
node scripts/bundle.mjsでdist/text_chunker.htmlが生成される -
node scripts/split.mjsでsrc-recovered/に 24 ファイルが復元される -
node scripts/verify.mjsで全ファイルが一致する - 開発版と結合版で同じ動作をする
- 受入テスト T1〜T27 をすべてパスする
- Console にエラー / 警告が出ない
- 機能追加・仕様変更をしていない
11. 汎用化戦略(将来検討用)
本作業で作成する bundle.mjs / split.mjs / verify.mjs は、Text Chunker 専用として実装する。
将来的には、以下を満たす汎用ツールに昇華できる。
11.1 汎用化の構想
tool/├── bundle.mjs # 任意の src/ → 単一 HTML├── split.mjs # 任意の単一 HTML → src/├── verify.mjs # round-trip 検証└── manifest.schema.json # 設定の JSON Schema各プロジェクトは manifest.json のみを持つ:
{ "name": "text-chunker", "template": "index.html", "styles": "styles/*.css", "scripts": "js/*.js", "entry": "js/00-main.js", "output": "dist/single.html", "marker": { "file": "=== @file: ", "import": "@import:", "export": "@export:" }}11.2 汎用化の利点
| 利点 | 内容 |
|---|---|
| 複数プロジェクトで再利用 | Parlourite Notes の管理ツールなどにも適用可能 |
| LLM との協働 | 「単一 HTML 渡し → 編集 → split」フローを全ツールで統一 |
| ドキュメント共有 | マーカー文法を 1 箇所で定義 |
| テスト資産の共有 | round-trip テストを 1 箇所で保守 |
11.3 汎用化の課題
| 課題 | 対応 |
|---|---|
| プロジェクトごとの複雑な依存関係 | esbuild の採用を検討(--bundle で自動解決) |
CSS の @import サポート | split 時に @import を展開する必要 |
| TypeScript / JSX の対応 | esbuild に委譲 |
| ソースマップ | esbuild の --sourcemap で対応 |
| マーカー文法の衝突 | 文字列リテラル内の @file を無視するパーサが必要 |
11.4 段階的なアプローチ
Step 1(本作業): Text Chunker 専用の bundle.mjs / split.mjs / verify.mjs を実装し、round-trip を検証。
Step 2(次回以降): 別プロジェクトで同じスクリプトを試し、共通部分を抽出。
Step 3(将来): manifest.json のスキーマを定義し、汎用ツール化。
11.5 今回の作業での注意
- 汎用化は急がない。まず Text Chunker で動くことを優先
- マーカー文法は汎用的に設計(プロジェクト固有名を含めない)
- スクリプトは
scripts/に配置(後にtool/へ移動可能な構造)
12. 注意事項
12.1 変更してはいけないもの
- 関数名・変数名・文字列リテラル(UI 文言含む)
- ロジック(判定順序、境界条件)
- CSS の見た目(分割のみ、ルールは変えない)
- データモデル(
ChunkRecのフィールド名など)
12.2 特に注意すべき点
| # | 内容 |
|---|---|
| 1 | app オブジェクトは 60-model.js の 1 箇所でのみ生成、他は import |
| 2 | Store は 50-storage.js で let 宣言、initStorage 後に値が入る |
| 3 | boot() の呼び出しは 00-main.js のみ |
| 4 | window.__app = app の設定は 00-main.js で行う |
| 5 | CodeMirror の import は 90-editor.js のみ |
| 6 | diff_match_patch は HTML の <script src> で読み込み、JS では window.diff_match_patch 参照 |
| 7 | 循環依存を避けるため、120-crud.js → 140-workflow.js の依存は関数宣言で対応 |
| 8 | event.target.closest('[data-act]') 系のハンドラは 170-wireui.js に集約 |
| 9 | テンプレートリテラル内に @file / @import を書かない(split の誤動作防止) |
| 10 | 複数行 import を書かない(行頭 1 行ずつ) |
12.3 落とし穴
- CSS の
@mediaクエリは分割単位に注意:10-layout.cssの末尾に全@mediaを置く let変数の分割:_cachedEditorDocなど module-levelletは参照するファイルに配置constの名前衝突: ESM スコープでは自動的に分離されるが、bundle 後は同一スコープ。全ファイルで一意であることを確認
13. 参考
- 開発引き継ぎレポート: Text Chunker 引き継ぎレポート — 分割ソース化・BASELINE-3 到達と Batch 4 修正計画
- 現行仕様書: 2026-09-27-text-chunker-spec
- frontmatter schema:
meta/SCHEMA.md - Jupytext(双方向変換の参考): https://jupytext.readthedocs.io/
- esbuild 公式: https://esbuild.github.io/
14. 提出物
以下の順で提出:
- ディレクトリ構造の一覧
- 各ファイルの完全なソースコード
- 出力は 6〜7 バッチに分割して良い
- 1 ファイル = 1 コードブロック
- ファイルパスをコードブロックの直前に明記
- 動作確認ログ
python3 -m http.server起動 → スクリーンショットnode scripts/bundle.mjs実行 → 標準出力node scripts/split.mjs実行 → 標準出力node scripts/verify.mjs実行 → 標準出力(“All files match”)- 受入テスト T1〜T27 の結果
- 想定と異なった点の報告
- 汎用化のための改善提案(§11 に対する気づき)
以上。
---
# 補足: 次エージェントへの申し送り
## A. 作業順序の推奨
| ステップ | 出力 ||---|---|| 1 | `index.html` + `manifest.json` + `scripts/*.mjs`(3 本) || 2 | CSS 5 本 || 3 | 基盤 JS(00〜60) || 4 | エンジン JS(70〜90) || 5 | UI / CRUD(100〜130) || 6 | ワークフロー(140〜150) || 7 | ダイアログ・起動(160〜180) |
各バッチ 700〜1,200 行。7 メッセージで完結。
## B. 最小検証経路
時間がない場合、以下 4 点だけでも確認:
1. `python3 -m http.server` → Console エラーなし2. `node scripts/bundle.mjs` → `dist/text_chunker.html` 生成3. `node scripts/split.mjs` → `src-recovered/` 生成4. `node scripts/verify.mjs` → "All files match"
これが通れば、双方向分割化は成功。
## C. 困ったときの判断
| 状況 | 判断 ||---|---|| 循環依存が発生 | 関数宣言(`function`)に変える || bundle が通らない | `@file` / `@import` の記法を確認 || split が誤動作 | テンプレートリテラル内の `@file` を疑う || round-trip が一致しない | 空白・改行の差を疑う(`diff -w`) || verify が遅い | 5,200 行なら 1 秒以内。遅ければ regex を見直す |
## D. 完成後
次エージェントは以下を報告すること:
- 生成したファイル数(31 を期待)- round-trip 検証の結果- 受入テストの結果- 想定外だった点- 汎用化のための気づき(§11 への追記案)