fix(CommandPalette): weigh the grapheme-snap ceiling against the value

[IgorShevchik]

Linked issue

Closes #387.

Type of change

• Documentation (updates to the documentation or readme)
• Bug fix (a non-breaking change that fixes an issue)
• Enhancement (improving an existing functionality)
• New feature (a non-breaking change that adds functionality)
• Chore (updates to the build process or auxiliary tools and libraries)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

GRAPHEME_SNAP_MAX_LENGTH is documented, and was tested, as a bound on the field text. It was not measured against it. truncateHTMLFromStart built its snapper from content — the value after escaping and after mark insertion — so the ceiling was reached early, by an amount nothing in the constant hints at. Escaping has no fixed overhead: & expands to five characters, " to six.

const FLAG = '\u{1F1FA}\u{1F1F8}'   // 🇺🇸

'a'.repeat(8140) + FLAG.repeat(10) + 'match'     // value.length 8185 — under the ceiling
'&'.repeat(1600) + FLAG.repeat(50) + 'match'     // value.length 1805 — 22% of the ceiling

Both degraded, and both rendered 🇸🇺 with an orphaned regional indicator where the author wrote 🇺🇸 — a different country, with nothing to signal the loss. That is the defect #364 describes and #371 exists to prevent, reappearing above a threshold no reader could predict from the constant.

Fix

createClusterSnapper takes the length to weigh separately from the string to segment, named fieldTextLength for what it is. The parameter is required, not defaulted to value.length: a default is precisely what would let the next derived-string caller inherit this bug in silence.

Cost

Segmenting a string the ceiling would have excluded is affordable — but not because the call is cheap in isolation. On a long run of regional indicators it is not, since containing() walks the run. It is that Array.from(html) above it already paid the larger price on the same string, unconditionally, on both sides of this fix.

Measured end to end, this branch against the old behaviour on identical input:

input	old	new	delta
plain, value.length 8185	86 µs → 🇸🇺	98 µs → 🇺🇸	+11 µs
escape-heavy, value.length 1505	172 µs → 🇺🇸	167 µs → 🇺🇸	−6 µs

Within noise in both directions. An independent A/B through vitest bench (400+ samples, ~2% RME) reached the same conclusion: 1.1879 ms vs 1.1843 ms on the all-quotes worst case at the ceiling.

test/bench/search.bench.ts gains under the ceiling, escaped six-fold, which reaches the ceiling by escaping rather than by length, so the claim rests on a durable measurement rather than a throwaway script — the convention that file's own header sets.

An earlier revision of this description carried a cost table that was wrong by three orders of magnitude. The benchmark behind it built the Segments view once and reused it across iterations, while the real code builds a fresh view per truncation. Recording that here because the number was quoted in the commit message and the source comment too, and the comment now explains the trap instead of restating a figure.

Tests

The two ceiling tests moved off value.length + MARKUP onto value.length. That makes snaps clusters exactly at the ceiling the plain-text repro in its own right — a value of exactly the advertised length previously degraded, verified against main.

measures the ceiling against the value, not its escaped copy covers the unbounded half. It was missing because no fixture in degraded paths contained an escapable character, so only the fixed 13-character single-mark overhead was ever exercised.

Mutation-checked: reverting the segmenter gate to the derived string, passing content.length at the call site, moving GRAPHEME_SNAP_MAX_LENGTH by ±1, and ignoring the new parameter are each caught by a named test.

732 tests green (test/utils/, test/components/); eslint and vue-tsc --noEmit clean. test/utils/search.spec.ts run 38 consecutive times on a quiet tree, all green — two reviewers reported intermittent failures in these tests, which reproduced only while a concurrent mutation-testing pass had the file modified, and whose failure signature matches that mutation exactly.

Documentation

.sync/PORTING.md's guard entry said the threshold "is crossed 13 characters earlier than a reading of value.length suggests". That described the defect rather than the design, so it is corrected here rather than deferred to the documentation follow-up — a porter reading the old sentence could have restored the bug deliberately.

Provenance

The defect was found by an independent review pass over #371 — five reviewers reading the merged code, rather than the authoring session re-reading itself. #371's own description argued its three self-review rounds were not converging; this is what that looked like in practice. The wrong cost figure, the parameter name, the missing default, and the deferred documentation fix were all caught by a second such pass over this branch.

Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.