From b696a4a1a614c3eb0d7d47ac69fd1aaab3d17d8c Mon Sep 17 00:00:00 2001
From: JunghwanNA <70629228+shaun0927@users.noreply.github.com>
Date: Thu, 16 Apr 2026 14:26:21 +0900
Subject: [PATCH] docs: document breakableFitAdvances cache invariant

The cache check in getSegmentBreakableFitAdvances returns the stored
result without consulting the mode parameter. This is safe because
the current call sites guarantee mode is determined by
isNumericRunSegment (text-deterministic) and the session-invariant
engine profile, so the same segment text always arrives with the
same mode.

Add a comment explaining this invariant so future callers know
the constraint. No behavior change.
---
 src/measurement.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/measurement.ts b/src/measurement.ts
index 8ef956dd..3147e3b0 100644
--- a/src/measurement.ts
+++ b/src/measurement.ts
@@ -200,6 +200,11 @@ export function getSegmentBreakableFitAdvances(
   emojiCorrection: number,
   mode: BreakableFitMode,
 ): number[] | null {
+  // The cached result is mode-agnostic: the current call sites guarantee that
+  // a given segment text always arrives with the same mode, because mode is
+  // determined by isNumericRunSegment(text) (text-deterministic) and the
+  // session-invariant engine profile.  If a future caller breaks this
+  // invariant, the cache will silently return the wrong advances.
   if (metrics.breakableFitAdvances !== undefined) return metrics.breakableFitAdvances
 
   const graphemeSegmenter = getSharedGraphemeSegmenter()