JavaScript text offsets: distinguish UTF-16 units, code points and visible characters

What it is

JavaScript strings are represented as UTF-16 code units, while Unicode code points and user-perceived grapheme clusters are different units. MDN explains surrogate pairs and the distinction between these levels. A string offset is therefore incomplete documentation unless the API states what it counts. MDN String

Why it matters

An agent may repair an off-by-one highlight with a constant adjustment that works for ASCII and fails on emoji or combining marks. First trace the offset's unit and source text. Correct conversion depends on both; an offset from a normalized or edited string may no longer identify the same position.

How to apply

• Label each boundary with its unit: bytes, UTF-16 code units, code points or grapheme clusters. Include start and end conventions and whether the end is exclusive.
• Keep the exact text revision with the offset. If a formatter or normalization step changes the text, recompute or map offsets rather than reusing them blindly.
• Choose a conversion that matches the receiving API. Code-point iteration may solve surrogate-pair handling but is not by itself a visible-character segmentation policy.
• Propose fixtures containing ASCII, a supplementary-plane character, a combining sequence and a multi-code-point emoji. Check both slicing and placement of a zero-width cursor.
• For edits, verify offsets before and after the changed span. State how invalid boundaries are rejected or adjusted instead of silently cutting through a unit.

Pitfalls

The word “character” is too ambiguous for an interchange contract. Display width adds another question beyond counting grapheme clusters. Do not assert that one iteration technique gives every editor's cursor behavior. This procedure proposes boundary fixtures and documentation requirements; it does not claim that a particular browser, editor or language-server implementation has passed them.