referencestable

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-finalv4.3-finalバッチ
D1チャンク配列app.chunks + app.autos 二重app.chunks 単一配列7-P
D2pinChunkpinChunk / pinChunkLocal 二重pinChunk(c, opts) 統合7-N
D3末尾改行 trim\n+$\n$(1 つのみ)7-M
D4ツリー長さ badgeendOffset - startOffsetcontentTextOf(...).length7-M
D5同一行 chunk 番号クリックcount > 1 のみ常時有効7-M
D6ゼロ長 chunk 行マーカーmin-height なしmin-height: 1.4em7-M
D7Row 2 レイアウト◀▶ / chunkStatus / 📋 / ✓ / ⋮chunkStatus / pin / ✓ / ⋮7-L2
D8Row 3 レイアウト[Text|Diff] / ⇤ / ⇣ / 🔍◀▶⇣ / spacer / 📋 / [Text|Diff] / 🔍7-L2
D9pin emoji📌=pinned / 📍=unpinned📍=pinned / 📌=unpinned7-P-fix
D10Merge menuMerge down のみMerge with next chunk + Merge with next master text…7-L2
D11設定 Merge 文言“document”“master text”7-L2
D12内部識別子commit*snapshot*7-Q
D13schemaVersion237-Q2

2. §1 用語と不変条件(追加)

2.1 用語(追加)

用語定義
persisted chunkid != null の chunk。IndexedDB に保存される
ephemeral chunkid == null の chunk。recomputeAutoChunks で毎回再生成される
snapshot内部名 snapshotVersion / snapshotText / snapshotAt。v4.2 の commit* の rename 後

用語対応:

v4.2v4.3意味
commitVersionsnapshotVersionsnapshot 通し番号
commitTextsnapshotTextsnapshot 時点の source slice
commitAtsnapshotAtsnapshot 時刻
commitAutoPinsnapshotAutoPinsnapshot 時に pin するか
commitChunksnapshotChunksnapshot 実行関数
commitOnlysnapshotOnlysnapshot のみ(copy なし)
copyAndCommitcopyAndSnapshotcopy + snapshot
copyAndCommitChunkcopyAndSnapshotChunk同上(chunk 引数版)
undoLastCommitundoLastSnapshotsnapshot の undo
commitBtn(DOM id)snapshotBtnRow 2 の snapshot ボタン
commit-only(data-act)snapshot-onlyACTION_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 != nullpersisted✓保護対象(保持)
id == nullephemeral✗再生成対象

3.2 §4.2 操作(改訂)

操作対象結果
Pinephemeral unpinnedmakePersistedChunk で persisted clone を作成、app.chunks 内で置換
Pinpersisted unpinnedstate: 'pinned' に変更、Store 更新
Unpinpersisted pinned、履歴なしapp.chunks から除去、次回 recompute で ephemeral 再生成
Unpinpersisted pinned、履歴ありstate: 'unpinned' に変更、Store 更新(履歴保持)
SnapshotephemeralmakePersistedChunk で昇格、snapshotVersion = 1
SnapshotpersistedsnapshotVersion++
Fill by limit (this chunk)persisted pinned 非 snapshotendOffset を再計算
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):
    • disabled when no chunk selected
    • pinned class(青系) + 📍 + title “Unpin this chunk”
    • unpinned class(灰色) + 📌 + 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 != null
  • isEphemeral(c) → c.id == null
  • persistedChunks() → 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 subset
6. __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: 3
  • importJSONWithMode の許容バージョン [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新規 docapp.chunks.length === 1、id === null(ephemeral)
T71Pin (ephemeral)app.chunks 内で persisted clone に置換、Store に保存
T72Pin (persisted unpinned)state のみ変更、Store 更新
T73Unpin(履歴なし)app.chunks から除去、recompute で ephemeral 再生成
T74Unpin(履歴あり)state のみ変更、app.chunks に残る
T75Snapshot (ephemeral)persisted 昇格、snapshotVersion = 1
T76Live split ON + 編集ephemeral が再生成、persisted は保持
T77promoteAllAuto全 ephemeral が persisted 化
T78clearAllChunksPromptStore 空、app.chunks に ephemeral 1 つ
T79pin emoji(pinned)📍
T80pin emoji(unpinned)📌
T81末尾 \n\n の chunktrim 後 \n 1 つ残る
T82ツリー badge 長contentTextOf の長さと一致
T83同一行 chunk 番号クリック(単一)popover が開く
T84ゼロ長 chunk 行マーカーmin-height: 1.4em で表示
T85旧 v2 データ(commitVersion)で起動正常動作、snapshotVersion に変換
T86旧 v2 データを保存snapshotVersion で永続化
T87v2 JSON importmapImportedChunk 経由で成功
T88v3 JSON exportschemaVersion: 3
T89v3 JSON 再 importそのまま読める
T90migration 冪等性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 idsnapshotBtn
内部 data-actsnapshot-only

11. §14 v4.2-final からの差分

#v4.2-finalv4.3-final理由
D1app.chunks + app.autos 二重配列単一配列同期漏れバグ解消
D2pinChunk / pinChunkLocal 二重実装pinChunk(c, opts) 統合重複排除
D3trim は \n+$\n$(1 つのみ)段落末尾空行の保持
D4ツリー badge = endOffset - startOffsetcontentTextOf(...).length表示一貫性
D5同一行 chunk 番号クリック = count > 1 のみ常時有効単一でも詳細を見たい
D6ゼロ長 chunk 行マーカーmin-height: 1.4em可視性
D7Row 2 = ◀▶ / chunkStatus / 📋 / ✓ / ⋮chunkStatus / pin / ✓ / ⋮レイアウト整理
D8Row 3 = [Text|Diff] / ⇤ / ⇣ / 🔍◀▶⇣ / spacer / 📋 / [Text|Diff] / 🔍レイアウト整理
D9pin emoji = 📌 / 📍📍 / 📌直感整合
D10Merge menu = Merge down のみMerge with next chunk + Merge with next master text…語彙拡張
D11設定 Merge 文言 “document”“master text”語彙統一
D12内部識別子 commit*snapshot*UI 語彙と内部名の統一
D13schemaVersion: 23migration 形式の明示
D14migrateChunk に v2 → v3 分岐なし追加既存データ互換
D15loadSettings に v2 → v3 分岐なし追加既存設定互換
D16exportJSON の schemaVersion: 23export/import 互換
D17importJSONWithMode の許容 [1, 2][1, 2, 3]後方互換

12. §15 既知の制約(改訂)

v4.2-final §15 から以下を更新:

#内容状態
4app.chunks / app.autos の二重配列解消済み(7-P)
5内部名 commit* と UI 語 snapshot の乖離解消済み(7-Q)
6pinChunk / pinChunkLocal の重複解消済み(7-N)
7chunkKey の unpinned@<offset> 位置依存継続
8mergeWithNextDocument の seq 再採番がセッション依存継続
9#diffView 高さ 40% 固定継続
11app.ui.historyExpanded デッドステートv4.4 で削除予定
12#detailPanel 関連 CSS 残存v4.4 で削除予定
新migration コードの重複チェックコスト微小(on-read、冪等)

13. §16 v4.4 への持ち越し

#内容予定バッチ
1app.ui.historyExpanded 削除8-A
2#detailPanel 関連 CSS 削除8-A
3chunkKey の ephemeral キー再設計8-B
4#diffView 高さ可変化8-C
5自動テストフレームワーク導入(node --test)8-D
6svc レジストリの必要性見直し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