fix(reader): B2 末行補償 off-by-one——近滿末行不再把末字擠成孤行

letterSpacing 加在範圍內每個字元之後（字數份），安全上限分母卻用
間隙數（字數-1），總增量最多超出 headroom 一個 spacing，近滿末行
的末字會被擠到下一行。分母改為末行字元數並加回歸測試。

chore(release): bump version to 0.2.137+151

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bennytsai1234

docs/changes/completed/2026-07-13/b2-lastline-offbyone.md

@@ -0,0 +1,20 @@
+# B2 末行補償 off-by-one — 近滿末行末字回捲修正
+
+層級：T0/T1（單點數學修正，探針已實證，回歸測試已加）
+
+## Before
+
+`layout_pump.dart` 末行補償的安全上限以 `headroom ÷ 間隙數（字數−1）`
+計算，但 letterSpacing 加在範圍內每個字元之後（字數份），總增量
+= spacing × 字數，最多超出 headroom 一個 spacing。末行接近滿行時，
+末字被擠到下一行成孤行（探針：9/9/9 三行段落變四行）。
+觸發條件：「末行字距補償」開啟（預設關）＋末行近滿。
+
+## After
+
+分母改為末行字元數（`lastLineBoxes.length`），總增量必 ≤ headroom，
+斷行不再改變。新增回歸測試（hybrid_pump_test：27 字 9/9/9、headroom
+1px，斷言行數維持 3 且末行寬 ≤ 內容寬）。
+
+驗證：`flutter analyze` 無問題；`flutter test` 734 全過。
+隨 v0.2.137 發布。

docs/changes/completed/2026-07-13/summary.md

@@ -1,3 +1,4 @@
 # 2026-07-13 工作摘要
 
 - [justify-indent-placeholder](justify-indent-placeholder.md) — 修正 justify 折疊行首 U+3000 縮排造成 soft-wrap 行字距異常放大、單行/多行段落間距不一致；縮排改用 placeholder 呈現，並升級 metrics 快取版本。
+- [b2-lastline-offbyone](b2-lastline-offbyone.md) — 修正末行補償安全上限的 off-by-one（分母間隙數→字數），近滿末行不再把末字擠成孤行；隨 v0.2.137 發布。

lib/features/reader_v2/hybrid/pump/layout_pump.dart

@@ -244,9 +244,12 @@ final class LayoutPump implements HybridLayoutPump {
         textAlignOverride: task.textStyle.textAlign,
       );
     }
+    // letterSpacing 加在範圍內每個字元之後（含末字），總增量是
+    // spacing × 字數而非 × 間隙數；分母若用 gaps，近滿末行會超寬
+    // 一個 spacing 而把末字擠到下一行。
     final lastLineHeadroom =
         (task.contentWidth - lines[lastLineIndex].width) /
-        lastLineGaps.toDouble();
+        lastLineBoxes.length.toDouble();
     final safeExtraLetterSpacing =
         extraLetterSpacing
             .clamp(0.0, lastLineHeadroom > 0 ? lastLineHeadroom : 0.0)

pubspec.yaml

@@ -1,7 +1,7 @@
 name: night_reader
 description: "夜讀 - Night Reader, a Flutter novel reader app"
 publish_to: 'none'
-version: 0.2.136+150
+version: 0.2.137+151
 homepage: https://github.com/bennytsai1234/night-reader
 repository: https://github.com/bennytsai1234/night-reader
 issue_tracker: https://github.com/bennytsai1234/night-reader/issues

test/features/reader_v2/hybrid/hybrid_pump_test.dart

@@ -220,6 +220,57 @@ void main() {
       baselineCache.dispose();
     });
 
+    test('B2 末行補償：近滿末行不得把末字擠到下一行', () async {
+      final store = MeasurementStore();
+      final cache = ParagraphCache();
+      final fingerprint = _fingerprint(lastLineSpacingCompensation: true);
+      final pump = LayoutPump(
+        paragraphCache: cache,
+        measurementStore: store,
+        namespace: MeasurementNamespace(
+          epoch: LayoutEpoch.initial,
+          fingerprint: fingerprint,
+        ),
+      );
+      const key = BlockKey(chapterIndex: 0, blockIndex: 0);
+      const fontSize = 20.0;
+      // 27 個無標點字元 + 寬 9 字 + 1px 殘餘 → 9/9/9 三行；末行 headroom
+      // 僅 1px。補償上限若誤用間隙數（8）作分母，總增量 9×0.125 會超寬
+      // 而把末字擠成第四行孤行。
+      final text = '夜' * 27;
+      pump.submit(
+        LayoutTask(
+          block: ChapterBlock(
+            key: key,
+            text: text,
+            charRange: const HybridTextRange(0, 27),
+            sourceParagraphIndex: 0,
+          ),
+          epoch: LayoutEpoch.initial,
+          fingerprint: fingerprint,
+          textStyle: const HybridBlockTextStyle(
+            fontSize: fontSize,
+            lineHeight: 1.5,
+            letterSpacing: 0,
+            textAlign: ui.TextAlign.justify,
+          ),
+          contentWidth: fontSize * 9 + 1,
+        ),
+      );
+
+      expect(await pump.pumpPending(), 1);
+      final paragraph = cache.acquire(key, LayoutEpoch.initial)!;
+      final lines = paragraph.computeLineMetrics();
+      expect(lines.length, 3, reason: '補償不得改變斷行（末字回捲即為 off-by-one）');
+      expect(
+        lines.last.width,
+        lessThanOrEqualTo(fontSize * 9 + 1 + 0.01),
+        reason: '末行寬不得超出內容寬',
+      );
+      pump.dispose();
+      cache.dispose();
+    });
+
     test('justify 下段首縮排以 placeholder 保留原寬，字距不吸收縮排寬度', () async {
       final store = MeasurementStore();
       final cache = ParagraphCache();