Text Chunker 仕様書 v4.3-draft
v4.2-final に対する差分仕様。単一配列モデル・pinChunk 統合・trim 変更・emoji swap・commit→snapshot rename + schemaVersion 3 migration を反映した最終仕様。
Text Chunker 仕様書 v4.3-final
本書の読み方
- 本書は v4.2-final(2026-09-29-text-chunker-spec-v4.2-final)に対する差分仕様 である。
- v4.2-final に Batch 7-L2 / 7-M / 7-N / 7-P / 7-P-fix / 7-Q / 7-Q2 を適用した状態を記述する。
- 本書に記載のない項目は v4.2-final を継承する。
- 受入テストは v4.2-final §12 に 追加 する形で §12 に列挙する。
1. 変更サマリ
| # | 変更 | v4.2-final | v4.3-final | バッチ |
|---|---|---|---|---|
| D1 | チャンク配列 | app.chunks + app.autos 二重 | app.chunks 単一配列 | 7-P |
| D2 | pinChunk | pinChunk / pinChunkLocal 二重 | pinChunk(c, opts) 統合 | 7-N |
| D3 | 末尾改行 trim | \n+$ | \n$(1 つのみ) | 7-M |
| D4 | ツリー長さ badge | endOffset - startOffset | contentTextOf(...).length | 7-M |
| D5 | 同一行 chunk 番号クリック | count > 1 のみ | 常時有効 | 7-M |
| D6 | ゼロ長 chunk 行マーカー | min-height なし | min-height: 1.4em | 7-M |
| D7 | Row 2 レイアウト | ◀▶ / chunkStatus / 📋 / ✓ / ⋮ | chunkStatus / pin / ✓ / ⋮ | 7-L2 |
| D8 | Row 3 レイアウト | [Text|Diff] / ⇤ / ⇣ / 🔍 | ◀▶⇣ / spacer / 📋 / [Text|Diff] / 🔍 | 7-L2 |
| D9 | pin emoji | 📌=pinned / 📍=unpinned | 📍=pinned / 📌=unpinned | 7-P-fix |
| D10 | Merge menu | Merge down のみ | Merge with next chunk + Merge with next master text… | 7-L2 |
| D11 | 設定 Merge 文言 | “document” | “master text” | 7-L2 |
| D12 | 内部識別子 | commit* | snapshot* | 7-Q |
| D13 | schemaVersion | 2 | 3 | 7-Q2 |
2. §1 用語と不変条件(追加)
2.1 用語(追加)
| 用語 | 定義 |
|---|---|
| persisted chunk | id != null の chunk。IndexedDB に保存される |
| ephemeral chunk | id == null の chunk。recomputeAutoChunks で毎回再生成される |
| snapshot | 内部名 snapshotVersion / snapshotText / snapshotAt。v4.2 の commit* の rename 後 |
用語対応:
| v4.2 | v4.3 | 意味 |
|---|---|---|
commitVersion | snapshotVersion | snapshot 通し番号 |
commitText | snapshotText | snapshot 時点の source slice |
commitAt | snapshotAt | snapshot 時刻 |
commitAutoPin | snapshotAutoPin | snapshot 時に pin するか |
commitChunk | snapshotChunk | snapshot 実行関数 |
commitOnly | snapshotOnly | snapshot のみ(copy なし) |
copyAndCommit | copyAndSnapshot | copy + snapshot |
copyAndCommitChunk | copyAndSnapshotChunk | 同上(chunk 引数版) |
undoLastCommit | undoLastSnapshot | snapshot の undo |
commitBtn(DOM id) | snapshotBtn | Row 2 の snapshot ボタン |
commit-only(data-act) | snapshot-only | ACTION_MAP キー |
2.2 不変条件(追加)
- I8(単一配列):
app.chunksは persisted + ephemeral の全 chunk を含む。app.autosは存在しない - I9(保存境界):
Store.put('chunks', ...)に渡せるのはid != nullの chunk のみ - I10(ephemeral 不変): ephemeral chunk の
stateは常に'unpinned' - I11(migration 冪等):
migrateChunkはcommitVersionの存在で v2 を検出、変換後delete。2 回目以降は no-op
3. §4 状態と範囲追従(改訂)
3.1 §4.1 状態(追加)
ChunkRec の state に加え、保存種別 を id の有無で区別:
| 条件 | 種別 | Store 保存 | recomputeAutoChunks の対象 |
|---|---|---|---|
id != null | persisted | ✓ | 保護対象(保持) |
id == null | ephemeral | ✗ | 再生成対象 |
3.2 §4.2 操作(改訂)
| 操作 | 対象 | 結果 |
|---|---|---|
| Pin | ephemeral unpinned | makePersistedChunk で persisted clone を作成、app.chunks 内で置換 |
| Pin | persisted unpinned | state: 'pinned' に変更、Store 更新 |
| Unpin | persisted pinned、履歴なし | app.chunks から除去、次回 recompute で ephemeral 再生成 |
| Unpin | persisted pinned、履歴あり | state: 'unpinned' に変更、Store 更新(履歴保持) |
| Snapshot | ephemeral | makePersistedChunk で昇格、snapshotVersion = 1 |
| Snapshot | persisted | snapshotVersion++ |
| Fill by limit (this chunk) | persisted pinned 非 snapshot | endOffset を再計算 |
| Cut at headings (this chunk) | persisted pinned 非 snapshot | 次の heading で分割 |
3.3 §4.5 ゼロ長チャンクの保護則(変更なし)
v4.2-final §4.5 と同じ。persisted chunk のみ対象。
3.4 §4.6 自動 pin 設定(改訂)
autoPinOnInteraction → snapshotAutoPin とは別物。autoPinOnInteraction は編集時 pin、snapshotAutoPin は snapshot 時 pin。
4. §5 画面(追加・改訂)
4.1 §5.2 Row 2(改訂)
┌─────────────────────────────────────────────────┐│ [chunkStatus] ● [📍pin] [✓ snapshot] [⋮] │└─────────────────────────────────────────────────┘◀ ▶は Row 3 へ移動chunkStatusの badge は version のみ(v1,v2, …)。Pinned/Unpinned は表示しない- pin ボタン(
#pinToggleBtn):disabledwhen no chunk selectedpinnedclass(青系) +📍+ title “Unpin this chunk”unpinnedclass(灰色) +📌+ title “Pin this chunk”aria-pressed反映
- snapshot ボタン(
#snapshotBtn):class="btn compact snapshot"(緑)
4.2 §5.3 Row 3(改訂)
┌─────────────────────────────────────────────────┐│ ◀ ▶ ⇣ {spacer} 📋 [Text|Diff] 🔍 │└─────────────────────────────────────────────────┘◀ ▶:navPrev/navNext⇣(#jumpChunkEndBtn):jumpTail(現在 chunk の end へ)- 左寄せ ◀▶⇣ / spacer / 右寄せ 📋 [Text|Diff] 🔍
📋は アイコンのみ
4.3 §5.7 エディタ左ガター(追加)
同一行に複数 chunk があっても 単一でも chunk 番号をクリック可能。ChunkLabelMarker は常に arr を保持し、クリックで openChunkStackPopover を開く。
ゼロ長 chunk の行マーカー(.cm-zero-len-marker)は min-height: 1.4em を持つ。
4.4 §5.8 チャンクメニュー(改訂)
Merge グループ:
Merge with next chunk— 現在 chunk と次の persisted chunk を結合(pinned かつ非 snapshot のみ有効)Merge with next master text…— 次のドキュメント(order昇順)を現在 master に連結
4.5 §5.9 設定 Merge タブ(文言変更)
File ▾ → Merge with next master text…に統一
4.6 §5.10 統合履歴メニュー(変更なし)
内部で snapshotVersion / snapshotText を使用。
5. §7 保存・出力(改訂)
5.1 §7.1 末尾改行の扱い
composeOutput / contentTextOf は trimTrailingNewline: true のとき、末尾の \n を 最大 1 つだけ 除去する。
例:
"abc\n"→"abc""abc\n\n"→"abc\n""abc"→"abc"
5.2 §7.x Snapshot
内部関数 snapshotChunk(c) を使用。UI 語は v4.2-final と同じ “Snapshot”。
6. §8 永続化(改訂)
6.1 §8.1 単一配列モデル(新規)
app.chunks は persisted + ephemeral の混在配列。app.autos は存在しない。
Store 境界ルール:
Store.put('chunks', c)はc.id != nullの場合のみ呼ぶapp.docsData[docId].chunksは persisted subset のみ を保持- 読み込み時:
app.chunks = app.docsData[docId].chunks.slice()、直後にrecomputeAutoChunks()で ephemeral を追加
helper:
isPersisted(c)→c.id != nullisEphemeral(c)→c.id == nullpersistedChunks()→app.chunks.filter(isPersisted)ephemeralChunks()→app.chunks.filter(isEphemeral)
6.2 §8.1 モジュール依存グラフ(変更なし)
DAG は v4.2-final と同じ。svc レジストリに pinChunk を追加(7-N)。
6.3 recomputeAutoChunks(mode) のアルゴリズム(改訂)
1. persisted subset を startOffset 昇順で取得2. persisted 間の gap を計算3. 各 gap を splitGap(mode) で分割 → ephemeral 生成4. app.chunks = [...persisted, ...ephemeral] を再構築5. app.docsData[currentDocId].chunks = persisted subset6. __i / __n を再採番7. _nameCache.clear()6.4 schemaVersion 3 への移行(新規)
6.4.1 SettingsRec
defaultSettings().schemaVersion: 3。loadSettings で v2 → v3 migration:
if ((app.settings.schemaVersion || 1) < 3) { if (app.settings.commitAutoPin !== undefined && app.settings.snapshotAutoPin === undefined) { app.settings.snapshotAutoPin = app.settings.commitAutoPin; } delete app.settings.commitAutoPin; app.settings.schemaVersion = 3; await Store.put('settings', { key: 'global', ...app.settings });}6.4.2 ChunkRec
migrateChunk に v2 → v3 フィールド移行:
if (c.commitVersion !== undefined) { if (c.snapshotVersion === undefined) c.snapshotVersion = c.commitVersion; delete c.commitVersion;}if (c.commitText !== undefined) { if (c.snapshotText === undefined) c.snapshotText = c.commitText; delete c.commitText;}if (c.commitAt !== undefined) { if (c.snapshotAt === undefined) c.snapshotAt = c.commitAt; delete c.commitAt;}6.4.3 冪等性
migrateChunk は commitVersion の存在で v2 を検出。変換後 delete されるため、2 回目以降は no-op。
loadSettings は schemaVersion < 3 判定。変換後 schemaVersion = 3 に更新。
6.4.4 migration コードの保護
migration コードは // rename:skip-begin ~ // rename:skip-end で囲む。rename-identifiers.mjs を再実行しても保護される。
6.5 JSON Export / Import
exportJSONのschemaVersion: 3importJSONWithModeの許容バージョン[1, 2, 3]- 既存 v1 / v2 JSON は
mapImportedChunk→migrateChunk経由で v3 に変換
7. §9 データモデル(改訂)
7.1 ChunkRec
interface ChunkRec { id: string | null; // null = ephemeral documentId: string; state: 'unpinned' | 'pinned'; startOffset: number; endOffset: number; name: string | null; beforeNote: string | null; afterNote: string | null; snapshotVersion: number; // v4.2 の commitVersion snapshotText: string | null; // v4.2 の commitText snapshotAt: number | null; // v4.2 の commitAt rev: number; createdAt: number; updatedAt: number;}7.2 SettingsRec
interface SettingsRec { schemaVersion: 3; // v4.2 の 2 theme: 'system' | 'light' | 'dark'; defaultParams: SplitParams; defaultOutput: OutputSettings; defaultLineEnding: 'LF' | 'CRLF'; beforeSnippets: string[]; afterSnippets: string[]; snapshotAutoPin: boolean; // v4.2 の commitAutoPin autoPinOnInteraction: boolean; autoSplit: boolean; showWhitespace: boolean; wordWrap: boolean; mergeSeparator: string; lastOpened: { docId: string; chunkKey: string } | null;}7.3 HistoryRec(変更なし)
v4.2-final と同じ。内部の commitText 参照は history レコードには存在しない。
8. §10 非機能(変更なし)
v4.2-final §10 と同じ。
9. §12 受入テスト(追加)
v4.2-final の T1〜T69 に以下を追加:
| # | 条件 | 期待結果 |
|---|---|---|
| T70 | 新規 doc | app.chunks.length === 1、id === null(ephemeral) |
| T71 | Pin (ephemeral) | app.chunks 内で persisted clone に置換、Store に保存 |
| T72 | Pin (persisted unpinned) | state のみ変更、Store 更新 |
| T73 | Unpin(履歴なし) | app.chunks から除去、recompute で ephemeral 再生成 |
| T74 | Unpin(履歴あり) | state のみ変更、app.chunks に残る |
| T75 | Snapshot (ephemeral) | persisted 昇格、snapshotVersion = 1 |
| T76 | Live split ON + 編集 | ephemeral が再生成、persisted は保持 |
| T77 | promoteAllAuto | 全 ephemeral が persisted 化 |
| T78 | clearAllChunksPrompt | Store 空、app.chunks に ephemeral 1 つ |
| T79 | pin emoji(pinned) | 📍 |
| T80 | pin emoji(unpinned) | 📌 |
| T81 | 末尾 \n\n の chunk | trim 後 \n 1 つ残る |
| T82 | ツリー badge 長 | contentTextOf の長さと一致 |
| T83 | 同一行 chunk 番号クリック(単一) | popover が開く |
| T84 | ゼロ長 chunk 行マーカー | min-height: 1.4em で表示 |
| T85 | 旧 v2 データ(commitVersion)で起動 | 正常動作、snapshotVersion に変換 |
| T86 | 旧 v2 データを保存 | snapshotVersion で永続化 |
| T87 | v2 JSON import | mapImportedChunk 経由で成功 |
| T88 | v3 JSON export | schemaVersion: 3 |
| T89 | v3 JSON 再 import | そのまま読める |
| T90 | migration 冪等性 | 2 回目起動で commitVersion が再出現しない |
10. §13 語彙(改訂)
| 用途 | 文言 |
|---|---|
| pin 状態 | Pinned / Unpinned |
| pin ボタン(pinned) | 📍(location marker) |
| pin ボタン(unpinned) | 📌(pushpin) |
| Snapshot | ✓(緑、.btn.snapshot) |
| Merge 操作 | Merge with next chunk / Merge with next master text… |
| 内部識別子 | snapshot*(snapshotVersion, snapshotText, …) |
| 内部 DOM id | snapshotBtn |
| 内部 data-act | snapshot-only |
11. §14 v4.2-final からの差分
| # | v4.2-final | v4.3-final | 理由 |
|---|---|---|---|
| D1 | app.chunks + app.autos 二重配列 | 単一配列 | 同期漏れバグ解消 |
| D2 | pinChunk / pinChunkLocal 二重実装 | pinChunk(c, opts) 統合 | 重複排除 |
| D3 | trim は \n+$ | \n$(1 つのみ) | 段落末尾空行の保持 |
| D4 | ツリー badge = endOffset - startOffset | contentTextOf(...).length | 表示一貫性 |
| D5 | 同一行 chunk 番号クリック = count > 1 のみ | 常時有効 | 単一でも詳細を見たい |
| D6 | ゼロ長 chunk 行マーカー | min-height: 1.4em | 可視性 |
| D7 | Row 2 = ◀▶ / chunkStatus / 📋 / ✓ / ⋮ | chunkStatus / pin / ✓ / ⋮ | レイアウト整理 |
| D8 | Row 3 = [Text|Diff] / ⇤ / ⇣ / 🔍 | ◀▶⇣ / spacer / 📋 / [Text|Diff] / 🔍 | レイアウト整理 |
| D9 | pin emoji = 📌 / 📍 | 📍 / 📌 | 直感整合 |
| D10 | Merge menu = Merge down のみ | Merge with next chunk + Merge with next master text… | 語彙拡張 |
| D11 | 設定 Merge 文言 “document” | “master text” | 語彙統一 |
| D12 | 内部識別子 commit* | snapshot* | UI 語彙と内部名の統一 |
| D13 | schemaVersion: 2 | 3 | migration 形式の明示 |
| D14 | migrateChunk に v2 → v3 分岐なし | 追加 | 既存データ互換 |
| D15 | loadSettings に v2 → v3 分岐なし | 追加 | 既存設定互換 |
| D16 | exportJSON の schemaVersion: 2 | 3 | export/import 互換 |
| D17 | importJSONWithMode の許容 [1, 2] | [1, 2, 3] | 後方互換 |
12. §15 既知の制約(改訂)
v4.2-final §15 から以下を更新:
| # | 内容 | 状態 |
|---|---|---|
| 4 | app.chunks / app.autos の二重配列 | 解消済み(7-P) |
| 5 | 内部名 commit* と UI 語 snapshot の乖離 | 解消済み(7-Q) |
| 6 | pinChunk / pinChunkLocal の重複 | 解消済み(7-N) |
| 7 | chunkKey の unpinned@<offset> 位置依存 | 継続 |
| 8 | mergeWithNextDocument の seq 再採番がセッション依存 | 継続 |
| 9 | #diffView 高さ 40% 固定 | 継続 |
| 11 | app.ui.historyExpanded デッドステート | v4.4 で削除予定 |
| 12 | #detailPanel 関連 CSS 残存 | v4.4 で削除予定 |
| 新 | migration コードの重複チェックコスト | 微小(on-read、冪等) |
13. §16 v4.4 への持ち越し
| # | 内容 | 予定バッチ |
|---|---|---|
| 1 | app.ui.historyExpanded 削除 | 8-A |
| 2 | #detailPanel 関連 CSS 削除 | 8-A |
| 3 | chunkKey の ephemeral キー再設計 | 8-B |
| 4 | #diffView 高さ可変化 | 8-C |
| 5 | 自動テストフレームワーク導入(node --test) | 8-D |
| 6 | svc レジストリの必要性見直し | 8-E |
14. 関連ドキュメント
- 引き継ぎ v4.3-final: 2026-09-30-text-chunker-handover-v4.3-final
- v4.2-final 仕様書: 2026-09-29-text-chunker-spec-v4.2-final
- v4.2-final 引き継ぎ: 2026-09-29-text-chunker-handover-v4.2-final
- directive: 260929_directive