log

Text Chunker 分割化指示書 v2(双方向対応)

Text Chunker 分割化指示書 v2(双方向対応)

0. この文書の位置付け

本稿は、単一 HTML で構成されている Text Chunker を 双方向変換可能な分割ソース + ビルド 方式に移行するための作業指示書である。

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.js

2.2 非目標

  • 機能追加・仕様変更
  • 変数名の意味的リネーム(startOffset → start などはしない)
  • パフォーマンス最適化
  • 汎用ツール化(§11 で方針のみ提示)

純粋な「同一コードの双方向分割」である。ロジックには一切手を加えない。


3. ファイル分割マップ

3.1 CSS(5 ファイル)

ファイル内容元の行範囲
00-base.css* reset / html, body / #app / #storageBannerL1〜40
10-layout.css#topbar / #sidebar / #main / #editorPane / #editorTop / #editorContainer / #detailPanel / #footer / レスポンシブL41〜250
20-components.css.btn / .dropdown / .tree-* / #searchPanel / #toastContainer / .toast / .dialog / #contextMenuL251〜450
30-editor.css.cm-* / #diffView / .notesIndicator / #viewModeSeg / スクロールバーL451〜560
40-theme-light.csshtml[data-theme="light"] 全般L561〜640

3.2 JS(19 ファイル)

以下、各ファイルの責務と、含まれるべき関数・定数の一覧。

ファイル推定行数内容
00-main.js30import 集約 + boot() 呼び出し + window.__app = app
10-utils.js60$, $$, uid, now, debounce, escHtml, sanitizeFilename, toLF, toCRLF, fmtBytes
20-count.js40countString
30-safe-pos.js60isCombiningMark, isSafePosition, safeFloor, nextSafe
40-candidates.js130buildLineStarts, lineIndexAtArr, reFenceStart, isCodeFenceStart, fenceDelim, isCodeFenceEnd, buildFenceSet, findHeadingCandidates, findBlankCandidates, findLineCandidates, findSentenceCandidates, lastLE, firstGT
50-storage.js200STORES, makeMemoryBackend, makeLSBackend, makeIDBBackend, probeIDB, probeLS, openIDB, Store, initStorage
60-model.js150defaultParams, defaultOutput, defaultSettings, app, chunkKey, chunkStateLabel, allChunks, findChunkByKey, currentChunk
70-compose.js180truncate30, computeName, expandTpl, stripNL, contentTextOf, resolveBefore, resolveAfter, isCrlfCount, composeOutput, countOutputStr, effectiveLimit, countBetween, overheadFor
80-split.js300chooseEnd, verifyFit, overlapStart, splitGap, lastSplitError, recomputeAutoChunks, makeAutoChunk, makePersistedChunk
90-editor.js500dirty/schedule, mapPos, effects/compartments, StateField, gutter, plugins, theme, filter/paste, extensions, cache, update dispatcher, cursor, redraw
100-detail-panel.js350詳細パネルの全関数
110-ui.js250toast, dialog, confirmAsync, download, copyToClipboard, showContextMenu, setUnsaved, settings 永続化, loadAllData, makeDocument, banners
120-crud.js350document CRUD, chunk CRUD, navigation, overlap, badges
130-tree.js300renderTree, showChunkContextMenu
140-workflow.js400split/merge/align, undo, copy&mark, fit, updateEditorTop, refreshChunkUI, footer, bulk copy/save
150-checkpoint.js300dmp, edit array, renderDMPLineDiff, renderSimpleDiff, checkpoint system
160-dialogs.js600wrapper presets, notes, split settings, snippets, log, stats, storage, code blocks, count mode, app settings, preview, search, JSON, view mode
170-wireui.js400ACTION_MAP, closeAllDropdowns, positionDropdown, wireUI
180-boot.js150boot(定義のみ), 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.mjsround-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, name2JS のみ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, fmtBytes
const $ = (s, r = document) => r.querySelector(s);
const $$ = (s, r = document) => [...r.querySelectorAll(s)];
// ...
// === @file: js/20-count.js ===
// @import: (none)
// @export: countString
function 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/ に split
2. src/ と tmp/recovered/ をファイル単位で比較
3. 全ファイルが一致すれば exit 0、不一致なら exit 1
4. 差分があればファイル名と行番号を表示

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 モジュール規約

  1. 各ファイルは export function name() {} または export const name = ... で公開
  2. 依存は import { name } from './NN-xxx.js' で明示(同時に @import ディレクティブにも書く)
  3. app オブジェクトは 60-model.js からのみ export
  4. 副作用のある module-level コード(window.addEventListener など)は許容、ただし wireUI / initPart5 内に集約
  5. 循環依存を避ける。避けられない場合は関数宣言(function)を使用

7.2 命名規約

  • ファイル名: NN-name.js / NN-name.css
  • 変数名・関数名: 既存コードから一切変更しない

7.3 round-trip のための制約

#制約理由
1import は行頭に 1 行ずつregex で除去可能
2複数行 import 禁止import { a,\n b } は除去できない
3トップレベル await 禁止concat 順序が不定になる
4import.meta 禁止bundle 後に意味が変わる
5副作用は boot() に集約連結順序への依存を排除
6変数名は全体で一意グローバル衝突回避
7ミニファイしないbyte-exact の round-trip のため
8文字列リテラルは 1 行で書く複数行テンプレートは保持する

7.4 文字列リテラルの扱い

テンプレートリテラル(バッククォート)内に @file や import が含まれる場合、split が誤動作する可能性がある。

対策:

  • テンプレートリテラル内で === @file: や // @import: を書かない
  • やむを得ず書く場合は \u0040 などエスケープする

現行コードでは該当箇所は少ないが、buildDetailHeader などのテンプレートを確認すること。


8. 開発フロー

8.1 通常の編集

Terminal window
# 1. 編集
vim src/js/140-workflow.js
# 2. サーバー起動
cd src
python3 -m http.server 8000
# 3. ブラウザで http://localhost:8000/ を開く

注意: file:// では動かない(Clipboard API が secure context 必須)。

8.2 単一 HTML 生成

Terminal window
node scripts/bundle.mjs
# → dist/text_chunker.html 生成

8.3 単一 HTML から復元

Terminal window
# dist/text_chunker.html を編集した後
node scripts/split.mjs
# → src-recovered/ に展開
# 手動で src/ にマージ
diff -r src/ src-recovered/

8.4 round-trip 検証

Terminal window
node scripts/verify.mjs
# → "All files match" が出れば OK

9. 検証手順

9.1 起動確認(必須)

  1. python3 -m http.server 8000 で起動
  2. http://localhost:8000/ を開く
  3. Console にエラーが出ないこと
  4. Untitled ドキュメントが表示されること
  5. テキストを貼り付けて自動分割が動くこと
  6. Copy & Mark Done が動くこと

9.2 round-trip 検証(必須)

Terminal window
node scripts/verify.mjs

期待: 全 24 ファイルで ”✓” が表示され、“All files match” で終了。

9.3 単一 HTML 検証

Terminal window
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 特に注意すべき点

#内容
1app オブジェクトは 60-model.js の 1 箇所でのみ生成、他は import
2Store は 50-storage.js で let 宣言、initStorage 後に値が入る
3boot() の呼び出しは 00-main.js のみ
4window.__app = app の設定は 00-main.js で行う
5CodeMirror の import は 90-editor.js のみ
6diff_match_patch は HTML の <script src> で読み込み、JS では window.diff_match_patch 参照
7循環依存を避けるため、120-crud.js → 140-workflow.js の依存は関数宣言で対応
8event.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-level let は参照するファイルに配置
  • const の名前衝突: ESM スコープでは自動的に分離されるが、bundle 後は同一スコープ。全ファイルで一意であることを確認

13. 参考


14. 提出物

以下の順で提出:

  1. ディレクトリ構造の一覧
  2. 各ファイルの完全なソースコード
    • 出力は 6〜7 バッチに分割して良い
    • 1 ファイル = 1 コードブロック
    • ファイルパスをコードブロックの直前に明記
  3. 動作確認ログ
    • python3 -m http.server 起動 → スクリーンショット
    • node scripts/bundle.mjs 実行 → 標準出力
    • node scripts/split.mjs 実行 → 標準出力
    • node scripts/verify.mjs 実行 → 標準出力(“All files match”)
    • 受入テスト T1〜T27 の結果
  4. 想定と異なった点の報告
  5. 汎用化のための改善提案(§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 への追記案)