@flighthq/textsegment 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './textSegment';
+export * from './textSegmentBoundary';
+export * from './textSegmenterBackend';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './textSegment';
+export * from './textSegmentBoundary';
+export * from './textSegmenterBackend';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}

package/dist/textSegment.d.ts

@@ -0,0 +1,5 @@
+import type { TextSegment } from '@flighthq/types';
+export declare function segmentGraphemes(text: string, locale?: string): readonly TextSegment[];
+export declare function segmentSentences(text: string, locale?: string): readonly TextSegment[];
+export declare function segmentWords(text: string, locale?: string): readonly TextSegment[];
+//# sourceMappingURL=textSegment.d.ts.map

package/dist/textSegment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegment.d.ts","sourceRoot":"","sources":["../src/textSegment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAEtF;AAID,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAEtF;AAKD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAElF"}

package/dist/textSegment.js

@@ -0,0 +1,20 @@
+import { getTextSegmenterBackend } from './textSegmenterBackend';
+// Enumerates the grapheme clusters of `text` (UAX #29) via the active backend. Each segment is one
+// user-perceived character: an emoji ZWJ sequence or a base-plus-combining-mark cluster is a single
+// segment, not its constituent code points. `locale` is threaded to the backend for the rare
+// locale-tailored cases. isWordLike is absent on grapheme segments.
+export function segmentGraphemes(text, locale) {
+    return getTextSegmenterBackend().segment(text, 'grapheme', locale);
+}
+// Enumerates the sentences of `text` (UAX #29) via the active backend, in order and covering the
+// whole string. isWordLike is absent on sentence segments.
+export function segmentSentences(text, locale) {
+    return getTextSegmenterBackend().segment(text, 'sentence', locale);
+}
+// Enumerates the words of `text` (UAX #29) via the active backend. Word segments carry isWordLike:
+// true for letters/numbers (a real word), false for the punctuation and whitespace runs between
+// them. Filter on isWordLike to keep only words. `locale` is threaded to the backend.
+export function segmentWords(text, locale) {
+    return getTextSegmenterBackend().segment(text, 'word', locale);
+}
+//# sourceMappingURL=textSegment.js.map

package/dist/textSegment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegment.js","sourceRoot":"","sources":["../src/textSegment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,mGAAmG;AACnG,oGAAoG;AACpG,6FAA6F;AAC7F,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAe;IAC5D,OAAO,uBAAuB,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAED,iGAAiG;AACjG,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAe;IAC5D,OAAO,uBAAuB,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAED,mGAAmG;AACnG,gGAAgG;AAChG,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAe;IACxD,OAAO,uBAAuB,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACjE,CAAC"}

package/dist/textSegmentBoundary.d.ts

@@ -0,0 +1,7 @@
+import type { TextSegmentRange } from '@flighthq/types';
+export declare function getNextGraphemeBoundary(text: string, index: number, locale?: string): number;
+export declare function getNextWordBoundary(text: string, index: number, locale?: string): number;
+export declare function getPreviousGraphemeBoundary(text: string, index: number, locale?: string): number;
+export declare function getPreviousWordBoundary(text: string, index: number, locale?: string): number;
+export declare function getWordRangeAt(text: string, index: number, locale?: string): TextSegmentRange | null;
+//# sourceMappingURL=textSegmentBoundary.d.ts.map

package/dist/textSegmentBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmentBoundary.d.ts","sourceRoot":"","sources":["../src/textSegmentBoundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAOrE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5F;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAExF;AAKD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhG;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5F;AAMD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAapG"}

package/dist/textSegmentBoundary.js

@@ -0,0 +1,76 @@
+import { segmentGraphemes, segmentWords } from './textSegment';
+// Returns the next grapheme-cluster boundary at or after `index` — the offset a caret lands on when
+// stepping right by one user-perceived character, so an emoji or combining sequence is crossed in a
+// single step. `index` is clamped into [0, text.length]; at or past the end it returns text.length.
+export function getNextGraphemeBoundary(text, index, locale) {
+    return nextSegmentBoundary(segmentGraphemes(text, locale), index, text.length);
+}
+// Returns the next word boundary at or after `index` — the offset a caret lands on when jumping right
+// by one word (Ctrl/Alt-Right). `index` is clamped into [0, text.length]; at or past the end it
+// returns text.length.
+export function getNextWordBoundary(text, index, locale) {
+    return nextSegmentBoundary(segmentWords(text, locale), index, text.length);
+}
+// Returns the previous grapheme-cluster boundary at or before `index` — the offset a caret lands on
+// when stepping left by one user-perceived character. `index` is clamped into [0, text.length]; at or
+// before the start it returns 0.
+export function getPreviousGraphemeBoundary(text, index, locale) {
+    return previousSegmentBoundary(segmentGraphemes(text, locale), index);
+}
+// Returns the previous word boundary at or before `index` — the offset a caret lands on when jumping
+// left by one word. `index` is clamped into [0, text.length]; at or before the start it returns 0.
+export function getPreviousWordBoundary(text, index, locale) {
+    return previousSegmentBoundary(segmentWords(text, locale), index);
+}
+// Returns the word-like segment's range covering `index`, for double-click / word-select. `index` is
+// clamped into [0, text.length]; at the very end it resolves against the last character. Returns null
+// when the covered segment is not word-like (whitespace or punctuation) or the text is empty — the
+// caller should then select nothing, mirroring how a double-click on a space selects no word.
+export function getWordRangeAt(text, index, locale) {
+    if (text.length === 0)
+        return null;
+    const clamped = clampIndex(index, text.length);
+    // At the trailing boundary there is no segment starting at text.length; resolve against the last
+    // character so a double-click at the end still selects the final word.
+    const lookup = clamped === text.length ? text.length - 1 : clamped;
+    const segments = segmentWords(text, locale);
+    for (const segment of segments) {
+        if (lookup >= segment.start && lookup < segment.end) {
+            return segment.isWordLike === true ? { start: segment.start, end: segment.end } : null;
+        }
+    }
+    return null;
+}
+// The boundary offsets are every segment start plus text.length (segments cover the string in order
+// with strictly increasing starts). Clamping keeps out-of-range indices from throwing per house rules.
+function clampIndex(index, length) {
+    if (index < 0)
+        return 0;
+    if (index > length)
+        return length;
+    return index;
+}
+function nextSegmentBoundary(segments, index, length) {
+    const from = clampIndex(index, length);
+    if (from >= length)
+        return length;
+    for (const segment of segments) {
+        if (segment.start > from)
+            return segment.start;
+    }
+    return length;
+}
+function previousSegmentBoundary(segments, index) {
+    const length = segments.length === 0 ? 0 : segments[segments.length - 1].end;
+    const from = clampIndex(index, length);
+    if (from <= 0)
+        return 0;
+    let previous = 0;
+    for (const segment of segments) {
+        if (segment.start >= from)
+            break;
+        previous = segment.start;
+    }
+    return previous;
+}
+//# sourceMappingURL=textSegmentBoundary.js.map

package/dist/textSegmentBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmentBoundary.js","sourceRoot":"","sources":["../src/textSegmentBoundary.ts"],"names":[],"mappings":"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"}

package/dist/textSegmenterBackend.d.ts

@@ -0,0 +1,5 @@
+import type { TextSegmenterBackend } from '@flighthq/types';
+export declare function createWebTextSegmenterBackend(): TextSegmenterBackend;
+export declare function getTextSegmenterBackend(): TextSegmenterBackend;
+export declare function setTextSegmenterBackend(backend: TextSegmenterBackend | null): void;
+//# sourceMappingURL=textSegmenterBackend.d.ts.map

package/dist/textSegmenterBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmenterBackend.d.ts","sourceRoot":"","sources":["../src/textSegmenterBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuC,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAQjG,wBAAgB,6BAA6B,IAAI,oBAAoB,CAEpE;AAKD,wBAAgB,uBAAuB,IAAI,oBAAoB,CAG9D;AAKD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAElF"}

package/dist/textSegmenterBackend.js

@@ -0,0 +1,62 @@
+// Builds the default web backend: a wrapper over the browser-native Intl.Segmenter. It ships no
+// Unicode tables — the engine already carries them — so the common path costs nothing in bundle
+// weight. Intl.Segmenter instances are cached by (locale, granularity) because constructing one is
+// expensive relative to a single segment() call. Where Intl.Segmenter is absent (an old or headless
+// engine), segment() returns [] rather than throwing; install a from-scratch UAX #29 backend via
+// setTextSegmenterBackend for those hosts.
+export function createWebTextSegmenterBackend() {
+    return { segment: segmentWithIntlSegmenter };
+}
+// Returns the active segmenter backend, lazily creating the web default the first time so there is
+// always an answer. A native host or a from-scratch UAX #29 backend replaces it via
+// setTextSegmenterBackend; passing null there restores this lazy web default.
+export function getTextSegmenterBackend() {
+    if (_backend === null)
+        _backend = createWebTextSegmenterBackend();
+    return _backend;
+}
+// Installs a segmenter backend; pass null to fall back to the lazily-created web default. Last write
+// wins — registering over an existing backend replaces it. Opt-in and side-effect-free at import:
+// nothing installs until a host calls this (or a segment*/boundary query lazily builds the web one).
+export function setTextSegmenterBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+// Cached Intl.Segmenter instances keyed by `locale|granularity`. A Map preserves insertion order, so
+// the first key is the oldest and drives simple FIFO eviction once the cache is full. Instances are
+// immutable, so sharing them across calls is safe.
+const _segmenterCache = new Map();
+const _segmenterCacheCapacity = 64;
+function getCachedSegmenter(locale, granularity) {
+    if (typeof Intl === 'undefined' || typeof Intl.Segmenter === 'undefined')
+        return null;
+    const key = `${locale ?? ''}|${granularity}`;
+    const existing = _segmenterCache.get(key);
+    if (existing !== undefined)
+        return existing;
+    const built = new Intl.Segmenter(locale, { granularity });
+    if (_segmenterCache.size >= _segmenterCacheCapacity) {
+        const oldest = _segmenterCache.keys().next().value;
+        if (oldest !== undefined)
+            _segmenterCache.delete(oldest);
+    }
+    _segmenterCache.set(key, built);
+    return built;
+}
+function segmentWithIntlSegmenter(text, granularity, locale) {
+    const segmenter = getCachedSegmenter(locale, granularity);
+    if (segmenter === null)
+        return [];
+    const out = [];
+    const isWordGranularity = granularity === 'word';
+    for (const data of segmenter.segment(text)) {
+        const start = data.index;
+        const record = { start, end: start + data.segment.length, text: data.segment };
+        // isWordLike is only meaningful — and only reported — for word granularity.
+        if (isWordGranularity)
+            record.isWordLike = data.isWordLike ?? false;
+        out.push(record);
+    }
+    return out;
+}
+//# sourceMappingURL=textSegmenterBackend.js.map

package/dist/textSegmenterBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmenterBackend.js","sourceRoot":"","sources":["../src/textSegmenterBackend.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,gGAAgG;AAChG,mGAAmG;AACnG,oGAAoG;AACpG,iGAAiG;AACjG,2CAA2C;AAC3C,MAAM,UAAU,6BAA6B;IAC3C,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAC/C,CAAC;AAED,mGAAmG;AACnG,oFAAoF;AACpF,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB;IACrC,IAAI,QAAQ,KAAK,IAAI;QAAE,QAAQ,GAAG,6BAA6B,EAAE,CAAC;IAClE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qGAAqG;AACrG,kGAAkG;AAClG,qGAAqG;AACrG,MAAM,UAAU,uBAAuB,CAAC,OAAoC;IAC1E,QAAQ,GAAG,OAAO,CAAC;AACrB,CAAC;AAED,IAAI,QAAQ,GAAgC,IAAI,CAAC;AAEjD,qGAAqG;AACrG,oGAAoG;AACpG,mDAAmD;AACnD,MAAM,eAAe,GAAG,IAAI,GAAG,EAA0B,CAAC;AAC1D,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,SAAS,kBAAkB,CAAC,MAA0B,EAAE,WAAmC;IACzF,IAAI,OAAO,IAAI,KAAK,WAAW,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACtF,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAE5C,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,eAAe,CAAC,IAAI,IAAI,uBAAuB,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QACnD,IAAI,MAAM,KAAK,SAAS;YAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC;IACD,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAC/B,IAAY,EACZ,WAAmC,EACnC,MAAe;IAEf,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1D,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,MAAM,iBAAiB,GAAG,WAAW,KAAK,MAAM,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,MAAM,GAAgB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5F,4EAA4E;QAC5E,IAAI,iBAAiB;YAAE,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC;QACpE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/textsegment",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Unicode text-segmentation seam (UAX #29 grapheme/word/sentence) over a swappable backend defaulting to the browser-native Intl.Segmenter",
+  "sideEffects": false
+}

package/src/textSegment.test.ts

@@ -0,0 +1,53 @@
+import type { TextSegment, TextSegmentGranularity, TextSegmenterBackend } from '@flighthq/types';
+
+import { segmentGraphemes, segmentSentences, segmentWords } from './textSegment';
+import { setTextSegmenterBackend } from './textSegmenterBackend';
+
+afterEach(() => setTextSegmenterBackend(null));
+
+describe('segmentGraphemes', () => {
+  it('treats a ZWJ family emoji as one grapheme', () => {
+    const segments = segmentGraphemes('a👨‍👩‍👧b');
+    expect(segments.map((s) => s.text)).toEqual(['a', '👨‍👩‍👧', 'b']);
+    expect(segments[1].start).toBe(1);
+    expect(segments[1].end).toBe('a👨‍👩‍👧'.length);
+  });
+
+  it('treats a base plus combining mark as one grapheme', () => {
+    // 'e' + combining acute accent (U+0301) is one user-perceived character.
+    const segments = segmentGraphemes('éx');
+    expect(segments.map((s) => s.text)).toEqual(['é', 'x']);
+  });
+
+  it('threads the locale argument to the active backend', () => {
+    let seenLocale: string | undefined = 'unset';
+    const fake: TextSegmenterBackend = {
+      segment(text: string, _granularity: TextSegmentGranularity, locale?: string): readonly TextSegment[] {
+        seenLocale = locale;
+        return [{ start: 0, end: text.length, text }];
+      },
+    };
+    setTextSegmenterBackend(fake);
+    segmentGraphemes('hi', 'de-DE');
+    expect(seenLocale).toBe('de-DE');
+  });
+});
+
+describe('segmentSentences', () => {
+  it('splits into sentences', () => {
+    const segments = segmentSentences('Hi. Bye.');
+    expect(segments.map((s) => s.text.trim())).toEqual(['Hi.', 'Bye.']);
+  });
+});
+
+describe('segmentWords', () => {
+  it('marks words as word-like and punctuation/whitespace as not', () => {
+    const segments = segmentWords('Hello, world.');
+    const words = segments.filter((s) => s.isWordLike === true).map((s) => s.text);
+    expect(words).toEqual(['Hello', 'world']);
+    const comma = segments.find((s) => s.text === ',');
+    expect(comma?.isWordLike).toBe(false);
+    const space = segments.find((s) => s.text === ' ');
+    expect(space?.isWordLike).toBe(false);
+  });
+});

package/src/textSegmentBoundary.test.ts

@@ -0,0 +1,98 @@
+import {
+  getNextGraphemeBoundary,
+  getNextWordBoundary,
+  getPreviousGraphemeBoundary,
+  getPreviousWordBoundary,
+  getWordRangeAt,
+} from './textSegmentBoundary';
+import { setTextSegmenterBackend } from './textSegmenterBackend';
+
+afterEach(() => setTextSegmenterBackend(null));
+
+// A ZWJ family emoji is a single grapheme cluster spanning several UTF-16 code units.
+const FAMILY = '👨‍👩‍👧';
+const EMOJI_TEXT = `a${FAMILY}b`;
+const FAMILY_START = 1;
+const B_START = FAMILY_START + FAMILY.length;
+const EMOJI_LEN = EMOJI_TEXT.length;
+
+describe('getNextGraphemeBoundary', () => {
+  it('steps over an emoji cluster in a single move', () => {
+    expect(getNextGraphemeBoundary(EMOJI_TEXT, FAMILY_START)).toBe(B_START);
+  });
+
+  it('advances one plain grapheme from the start', () => {
+    expect(getNextGraphemeBoundary(EMOJI_TEXT, 0)).toBe(FAMILY_START);
+  });
+
+  it('clamps at text.length', () => {
+    expect(getNextGraphemeBoundary(EMOJI_TEXT, EMOJI_LEN)).toBe(EMOJI_LEN);
+    expect(getNextGraphemeBoundary(EMOJI_TEXT, 999)).toBe(EMOJI_LEN);
+  });
+});
+
+describe('getNextWordBoundary', () => {
+  it('jumps to the end of the current word', () => {
+    expect(getNextWordBoundary('foo bar', 0)).toBe(3);
+  });
+
+  it('clamps at text.length', () => {
+    expect(getNextWordBoundary('foo bar', 7)).toBe(7);
+    expect(getNextWordBoundary('foo bar', 42)).toBe(7);
+  });
+});
+
+describe('getPreviousGraphemeBoundary', () => {
+  it('inverts a step over an emoji cluster', () => {
+    expect(getPreviousGraphemeBoundary(EMOJI_TEXT, B_START)).toBe(FAMILY_START);
+  });
+
+  it('clamps at 0', () => {
+    expect(getPreviousGraphemeBoundary(EMOJI_TEXT, 0)).toBe(0);
+    expect(getPreviousGraphemeBoundary(EMOJI_TEXT, -5)).toBe(0);
+  });
+
+  it('steps back from the end onto the last cluster start', () => {
+    expect(getPreviousGraphemeBoundary(EMOJI_TEXT, EMOJI_LEN)).toBe(B_START);
+  });
+});
+
+describe('getPreviousWordBoundary', () => {
+  it('jumps to the start of the current word', () => {
+    expect(getPreviousWordBoundary('foo bar', 7)).toBe(4);
+  });
+
+  it('clamps at 0', () => {
+    expect(getPreviousWordBoundary('foo bar', 0)).toBe(0);
+  });
+});
+
+describe('getWordRangeAt', () => {
+  it('returns the word range under an index', () => {
+    expect(getWordRangeAt('foo bar', 1)).toEqual({ start: 0, end: 3 });
+  });
+
+  it('returns null in whitespace (double-click on a space selects no word)', () => {
+    expect(getWordRangeAt('foo bar', 3)).toBeNull();
+  });
+
+  it('resolves the final word from the trailing boundary', () => {
+    expect(getWordRangeAt('foo bar', 7)).toEqual({ start: 4, end: 7 });
+  });
+
+  it('returns null for empty text', () => {
+    expect(getWordRangeAt('', 0)).toBeNull();
+  });
+
+  it('threads the locale to the active backend', () => {
+    let seenLocale: string | undefined = 'unset';
+    setTextSegmenterBackend({
+      segment(text, _granularity, locale) {
+        seenLocale = locale;
+        return [{ start: 0, end: text.length, text, isWordLike: true }];
+      },
+    });
+    getWordRangeAt('word', 1, 'ja-JP');
+    expect(seenLocale).toBe('ja-JP');
+  });
+});

package/src/textSegmenterBackend.test.ts

@@ -0,0 +1,78 @@
+import type { TextSegment, TextSegmentGranularity, TextSegmenterBackend } from '@flighthq/types';
+
+import {
+  createWebTextSegmenterBackend,
+  getTextSegmenterBackend,
+  setTextSegmenterBackend,
+} from './textSegmenterBackend';
+
+interface RecordingBackend extends TextSegmenterBackend {
+  calls: Array<{ text: string; granularity: TextSegmentGranularity; locale: string | undefined }>;
+}
+
+function recordingBackend(): RecordingBackend {
+  const calls: RecordingBackend['calls'] = [];
+  return {
+    calls,
+    segment(text: string, granularity: TextSegmentGranularity, locale?: string): readonly TextSegment[] {
+      calls.push({ text, granularity, locale });
+      return [{ start: 0, end: text.length, text }];
+    },
+  };
+}
+
+afterEach(() => setTextSegmenterBackend(null));
+
+describe('createWebTextSegmenterBackend', () => {
+  it('segments a ZWJ family emoji as a single grapheme', () => {
+    const segments = createWebTextSegmenterBackend().segment('a👨‍👩‍👧b', 'grapheme');
+    expect(segments.map((s) => s.text)).toEqual(['a', '👨‍👩‍👧', 'b']);
+  });
+
+  it('reports isWordLike for word granularity and omits it otherwise', () => {
+    const backend = createWebTextSegmenterBackend();
+    const words = backend.segment('Hi there', 'word');
+    expect(words.every((s) => typeof s.isWordLike === 'boolean')).toBe(true);
+    const graphemes = backend.segment('Hi', 'grapheme');
+    expect(graphemes.every((s) => s.isWordLike === undefined)).toBe(true);
+  });
+
+  it('produces gap-free start/end offsets covering the whole string', () => {
+    const segments = createWebTextSegmenterBackend().segment('abc', 'grapheme');
+    expect(segments).toEqual([
+      { start: 0, end: 1, text: 'a' },
+      { start: 1, end: 2, text: 'b' },
+      { start: 2, end: 3, text: 'c' },
+    ]);
+  });
+});
+
+describe('getTextSegmenterBackend', () => {
+  it('lazily falls back to a web backend when none is registered', () => {
+    const backend = getTextSegmenterBackend();
+    expect(backend).not.toBeNull();
+    expect(backend.segment('ab', 'grapheme').length).toBe(2);
+  });
+
+  it('returns the registered backend', () => {
+    const backend = recordingBackend();
+    setTextSegmenterBackend(backend);
+    expect(getTextSegmenterBackend()).toBe(backend);
+  });
+});
+
+describe('setTextSegmenterBackend', () => {
+  it('routes segmentation through the installed backend', () => {
+    const backend = recordingBackend();
+    setTextSegmenterBackend(backend);
+    getTextSegmenterBackend().segment('hello', 'sentence', 'fr');
+    expect(backend.calls).toEqual([{ text: 'hello', granularity: 'sentence', locale: 'fr' }]);
+  });
+
+  it('clears back to the lazy web default when passed null', () => {
+    setTextSegmenterBackend(recordingBackend());
+    setTextSegmenterBackend(null);
+    // The web default segments a ZWJ cluster as one grapheme; a recording backend would not.
+    expect(getTextSegmenterBackend().segment('a👨‍👩‍👧b', 'grapheme').length).toBe(3);
+  });
+});