@flighthq/textsegment 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.1047.858b9b6

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/textsegment`. The `@
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/textsegment@0.5.0-next.1944.cd6b6e7](https://github.com/flighthq/flight/tree/cd6b6e71eb472b3a4249830a7743333f019fa7b7/packages/textsegment)
-- [License](https://github.com/flighthq/flight/blob/cd6b6e71eb472b3a4249830a7743333f019fa7b7/LICENSE.md)
+- [Source for @flighthq/textsegment@0.5.1-edge.1047.858b9b6](https://github.com/flighthq/flight/tree/858b9b601de814f6b6940cbb1ffff0916b903268/packages/textsegment)
+- [License](https://github.com/flighthq/flight/blob/858b9b601de814f6b6940cbb1ffff0916b903268/LICENSE.md)

package/dist/contract.d.ts

@@ -1,4 +1,6 @@
+export * from './enableTextSegmentGuards';
 export * from './textSegment';
 export * from './textSegmentBoundary';
+export * from './textSegmentGuards';
 export * from './textSegmenterBackend';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -1,4 +1,6 @@
+export * from './enableTextSegmentGuards';
 export * from './textSegment';
 export * from './textSegmentBoundary';
+export * from './textSegmentGuards';
 export * from './textSegmenterBackend';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

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

package/dist/enableTextSegmentGuards.d.ts

@@ -0,0 +1,5 @@
+/** Uninstalls the guard installed by enableTextSegmentGuards. */
+export declare function disableTextSegmentGuards(): void;
+/** Installs an opt-in warning for use of the bundled provider where Intl.Segmenter is absent. */
+export declare function enableTextSegmentGuards(): void;
+//# sourceMappingURL=enableTextSegmentGuards.d.ts.map

package/dist/enableTextSegmentGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTextSegmentGuards.d.ts","sourceRoot":"","sources":["../src/enableTextSegmentGuards.ts"],"names":[],"mappings":"AAKA,iEAAiE;AACjE,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,iGAAiG;AACjG,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/enableTextSegmentGuards.js

@@ -0,0 +1,17 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setTextSegmentGuard } from './textSegmentGuards';
+/** Uninstalls the guard installed by enableTextSegmentGuards. */
+export function disableTextSegmentGuards() {
+    setTextSegmentGuard(null);
+}
+/** Installs an opt-in warning for use of the bundled provider where Intl.Segmenter is absent. */
+export function enableTextSegmentGuards() {
+    setTextSegmentGuard(warnOnMissingIntlSegmenter);
+}
+function warnOnMissingIntlSegmenter() {
+    logOnce('textsegment:intl-segmenter-unavailable', LogLevel.Warn, {
+        message: 'segmentGraphemes: Intl.Segmenter is unavailable and no replacement provider was supplied, so segmentation returned no results. Install a backend with setTextSegmenterBackend(backend), or pass a HasTextSegmenter host directly to the operation.',
+    }, 'textsegment');
+}
+//# sourceMappingURL=enableTextSegmentGuards.js.map

package/dist/enableTextSegmentGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTextSegmentGuards.js","sourceRoot":"","sources":["../src/enableTextSegmentGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,iEAAiE;AACjE,MAAM,UAAU,wBAAwB;IACtC,mBAAmB,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,uBAAuB;IACrC,mBAAmB,CAAC,0BAA0B,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,0BAA0B;IACjC,OAAO,CACL,wCAAwC,EACxC,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EACL,oPAAoP;KACvP,EACD,aAAa,CACd,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { getNextGraphemeBoundary, getNextWordBoundary, getPreviousGraphemeBoundary, getPreviousWordBoundary, getWordRangeAt, segmentGraphemes, segmentSentences, segmentWords, } from './contract';
+export { disableTextSegmentGuards, enableTextSegmentGuards, explainTextSegmenterBackend, getNextGraphemeBoundary, getNextSentenceBoundary, getNextWordBoundary, getPreviousGraphemeBoundary, getPreviousSentenceBoundary, getPreviousWordBoundary, getWordRangeAt, segmentGraphemes, segmentSentences, segmentWords, webTextSegmenterBackend, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { getNextGraphemeBoundary, getNextWordBoundary, getPreviousGraphemeBoundary, getPreviousWordBoundary, getWordRangeAt, segmentGraphemes, segmentSentences, segmentWords, } from './contract';
+export { disableTextSegmentGuards, enableTextSegmentGuards, explainTextSegmenterBackend, getNextGraphemeBoundary, getNextSentenceBoundary, getNextWordBoundary, getPreviousGraphemeBoundary, getPreviousSentenceBoundary, getPreviousWordBoundary, getWordRangeAt, segmentGraphemes, segmentSentences, segmentWords, webTextSegmenterBackend, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/textSegment.d.ts

@@ -1,5 +1,5 @@
-import type { TextSegment } from '@flighthq/types/contract';
-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[];
+import type { HasTextSegmenter, TextSegment } from '@flighthq/types/contract';
+export declare function segmentGraphemes(text: string, locale?: string, host?: HasTextSegmenter): readonly TextSegment[];
+export declare function segmentSentences(text: string, locale?: string, host?: HasTextSegmenter): readonly TextSegment[];
+export declare function segmentWords(text: string, locale?: string, host?: HasTextSegmenter): readonly TextSegment[];
 //# sourceMappingURL=textSegment.d.ts.map

package/dist/textSegment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textSegment.d.ts","sourceRoot":"","sources":["../src/textSegment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQ5D,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"}
+{"version":3,"file":"textSegment.d.ts","sourceRoot":"","sources":["../src/textSegment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQ9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,WAAW,EAAE,CAE/G;AAID,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,WAAW,EAAE,CAE/G;AAKD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,WAAW,EAAE,CAE3G"}

package/dist/textSegment.js

@@ -3,18 +3,18 @@ import { getTextSegmenterBackend } from './textSegmenterBackend';
 // 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);
+export function segmentGraphemes(text, locale, host) {
+    return getTextSegmenterBackend(host).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);
+export function segmentSentences(text, locale, host) {
+    return getTextSegmenterBackend(host).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);
+export function segmentWords(text, locale, host) {
+    return getTextSegmenterBackend(host).segment(text, 'word', locale);
 }
 //# sourceMappingURL=textSegment.js.map

package/dist/textSegment.js.map

@@ -1 +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"}
+{"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,EAAE,IAAuB;IACrF,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AACzE,CAAC;AAED,iGAAiG;AACjG,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAe,EAAE,IAAuB;IACrF,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AACzE,CAAC;AAED,mGAAmG;AACnG,gGAAgG;AAChG,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAe,EAAE,IAAuB;IACjF,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC"}

package/dist/textSegmentBoundary.d.ts

@@ -1,7 +1,9 @@
-import type { TextSegmentRange } from '@flighthq/types/contract';
-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;
+import type { HasTextSegmenter, TextSegmentRange } from '@flighthq/types/contract';
+export declare function getNextGraphemeBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getNextSentenceBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getNextWordBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getPreviousGraphemeBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getPreviousSentenceBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getPreviousWordBoundary(text: string, index: number, locale?: string, host?: HasTextSegmenter): number;
+export declare function getWordRangeAt(text: string, index: number, locale?: string, host?: HasTextSegmenter): TextSegmentRange | null;
 //# sourceMappingURL=textSegmentBoundary.d.ts.map

package/dist/textSegmentBoundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textSegmentBoundary.d.ts","sourceRoot":"","sources":["../src/textSegmentBoundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9E,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"}
+{"version":3,"file":"textSegmentBoundary.d.ts","sourceRoot":"","sources":["../src/textSegmentBoundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAuC,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQxH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAErH;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAErH;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAEjH;AAKD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,CAER;AAID,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,CAER;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAErH;AAMD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,gBAAgB,GACtB,gBAAgB,GAAG,IAAI,CAyBzB"}

package/dist/textSegmentBoundary.js

@@ -1,39 +1,63 @@
-import { segmentGraphemes, segmentWords } from './textSegment';
+import { getTextSegmenterBackend, webTextSegmenterBackend } from './textSegmenterBackend';
+import { reportTextSegmenterUnavailable } from './textSegmentGuards';
 // 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);
+export function getNextGraphemeBoundary(text, index, locale, host) {
+    return getNextTextSegmentBoundary(text, index, 'grapheme', locale, host);
+}
+// Returns the next sentence boundary at or after `index`. The bundled Intl path stops its iterator as
+// soon as the answer is known and does not materialize the sentence strings or a segment array.
+export function getNextSentenceBoundary(text, index, locale, host) {
+    return getNextTextSegmentBoundary(text, index, 'sentence', locale, host);
 }
 // 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);
+export function getNextWordBoundary(text, index, locale, host) {
+    return getNextTextSegmentBoundary(text, index, 'word', locale, host);
 }
 // 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);
+export function getPreviousGraphemeBoundary(text, index, locale, host) {
+    return getPreviousTextSegmentBoundary(text, index, 'grapheme', locale, host);
+}
+// Returns the previous sentence boundary at or before `index`. The bundled Intl path walks offsets
+// directly and avoids building TextSegment records; custom backends retain their existing array seam.
+export function getPreviousSentenceBoundary(text, index, locale, host) {
+    return getPreviousTextSegmentBoundary(text, index, 'sentence', locale, host);
 }
 // 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);
+export function getPreviousWordBoundary(text, index, locale, host) {
+    return getPreviousTextSegmentBoundary(text, index, 'word', locale, host);
 }
 // 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) {
+export function getWordRangeAt(text, index, locale, host) {
     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);
+    const backend = getTextSegmenterBackend(host);
+    if (backend === webTextSegmenterBackend) {
+        const segmenter = getBoundarySegmenter(locale, 'word');
+        if (segmenter === null)
+            return null;
+        for (const segment of segmenter.segment(text)) {
+            const end = segment.index + segment.segment.length;
+            if (lookup >= segment.index && lookup < end) {
+                return segment.isWordLike === true ? { start: segment.index, end } : null;
+            }
+        }
+        return null;
+    }
+    const segments = backend.segment(text, 'word', locale);
     for (const segment of segments) {
         if (lookup >= segment.start && lookup < segment.end) {
             return segment.isWordLike === true ? { start: segment.start, end: segment.end } : null;
@@ -41,6 +65,59 @@ export function getWordRangeAt(text, index, locale) {
     }
     return null;
 }
+function getBoundarySegmenter(locale, granularity) {
+    if (typeof Intl === 'undefined' || typeof Intl.Segmenter === 'undefined') {
+        reportTextSegmenterUnavailable();
+        return null;
+    }
+    const key = `${locale ?? ''}|${granularity}`;
+    const existing = boundarySegmenterCache.get(key);
+    if (existing !== undefined)
+        return existing;
+    const segmenter = new Intl.Segmenter(locale, { granularity });
+    if (boundarySegmenterCache.size >= BOUNDARY_SEGMENTER_CACHE_CAPACITY) {
+        const oldest = boundarySegmenterCache.keys().next().value;
+        if (oldest !== undefined)
+            boundarySegmenterCache.delete(oldest);
+    }
+    boundarySegmenterCache.set(key, segmenter);
+    return segmenter;
+}
+function getNextTextSegmentBoundary(text, index, granularity, locale, host) {
+    const from = clampIndex(index, text.length);
+    if (from >= text.length)
+        return text.length;
+    const backend = getTextSegmenterBackend(host);
+    if (backend !== webTextSegmenterBackend) {
+        return nextSegmentBoundary(backend.segment(text, granularity, locale), from, text.length);
+    }
+    const segmenter = getBoundarySegmenter(locale, granularity);
+    if (segmenter === null)
+        return text.length;
+    for (const segment of segmenter.segment(text)) {
+        if (segment.index > from)
+            return segment.index;
+    }
+    return text.length;
+}
+function getPreviousTextSegmentBoundary(text, index, granularity, locale, host) {
+    const from = clampIndex(index, text.length);
+    if (from <= 0)
+        return 0;
+    const backend = getTextSegmenterBackend(host);
+    if (backend !== webTextSegmenterBackend)
+        return previousSegmentBoundary(backend.segment(text, granularity, locale), from);
+    const segmenter = getBoundarySegmenter(locale, granularity);
+    if (segmenter === null)
+        return 0;
+    let previous = 0;
+    for (const segment of segmenter.segment(text)) {
+        if (segment.index >= from)
+            break;
+        previous = segment.index;
+    }
+    return previous;
+}
 // 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) {
@@ -73,4 +150,6 @@ function previousSegmentBoundary(segments, index) {
     }
     return previous;
 }
+const boundarySegmenterCache = new Map();
+const BOUNDARY_SEGMENTER_CACHE_CAPACITY = 64;
 //# sourceMappingURL=textSegmentBoundary.js.map

package/dist/textSegmentBoundary.js.map

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

package/dist/textSegmentGuards.d.ts

@@ -0,0 +1,4 @@
+import type { TextSegmentGuard } from '@flighthq/types/contract';
+export declare function reportTextSegmenterUnavailable(): void;
+export declare function setTextSegmentGuard(guard: TextSegmentGuard | null): void;
+//# sourceMappingURL=textSegmentGuards.d.ts.map

package/dist/textSegmentGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmentGuards.d.ts","sourceRoot":"","sources":["../src/textSegmentGuards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAExE"}

package/dist/textSegmentGuards.js

@@ -0,0 +1,8 @@
+export function reportTextSegmenterUnavailable() {
+    _guard?.();
+}
+export function setTextSegmentGuard(guard) {
+    _guard = guard;
+}
+let _guard = null;
+//# sourceMappingURL=textSegmentGuards.js.map

package/dist/textSegmentGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textSegmentGuards.js","sourceRoot":"","sources":["../src/textSegmentGuards.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,8BAA8B;IAC5C,MAAM,EAAE,EAAE,CAAC;AACb,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAA8B;IAChE,MAAM,GAAG,KAAK,CAAC;AACjB,CAAC;AAED,IAAI,MAAM,GAA4B,IAAI,CAAC"}

package/dist/textSegmenterBackend.d.ts

@@ -1,5 +1,16 @@
-import type { TextSegmenterBackend } from '@flighthq/types/contract';
+import type { EntityConstruction, HasTextSegmenter, TextSegmenterBackend, TextSegmenterBackendExplanation } from '@flighthq/types/contract';
 export declare function createWebTextSegmenterBackend(): TextSegmenterBackend;
-export declare function getTextSegmenterBackend(): TextSegmenterBackend;
+export declare const webTextSegmenterBackend: TextSegmenterBackend;
+/** Describes which provider an operation would use and whether Intl.Segmenter is present. */
+export declare function explainTextSegmenterBackend(host?: HasTextSegmenter): TextSegmenterBackendExplanation;
+export declare function getTextSegmenterBackend(host?: HasTextSegmenter): TextSegmenterBackend;
+export declare function initializeWebTextSegmenterBackend(out: EntityConstruction<TextSegmenterBackend>): void;
+/**
+ * Installs the backend used by calls that omit an explicit host; pass null to restore the stable
+ * bundled web default.
+ *
+ * @deprecated Pass a HasTextSegmenter to the segmentation or boundary operation. Retained for
+ * source compatibility until the legacy global path is removed.
+ */
 export declare function setTextSegmenterBackend(backend: TextSegmenterBackend | null): void;
 //# sourceMappingURL=textSegmenterBackend.d.ts.map

package/dist/textSegmenterBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textSegmenterBackend.d.ts","sourceRoot":"","sources":["../src/textSegmenterBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuC,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAQ1G,wBAAgB,6BAA6B,IAAI,oBAAoB,CAEpE;AAKD,wBAAgB,uBAAuB,IAAI,oBAAoB,CAG9D;AAKD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAElF"}
+{"version":3,"file":"textSegmenterBackend.d.ts","sourceRoot":"","sources":["../src/textSegmenterBackend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAGhB,oBAAoB,EACpB,+BAA+B,EAChC,MAAM,0BAA0B,CAAC;AAUlC,wBAAgB,6BAA6B,IAAI,oBAAoB,CAIpE;AAID,eAAO,MAAM,uBAAuB,EAAE,oBAAsD,CAAC;AAE7F,6FAA6F;AAC7F,wBAAgB,2BAA2B,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,+BAA+B,CASpG;AAKD,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,oBAAoB,CAErF;AAED,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAErG;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAElF"}

package/dist/textSegmenterBackend.js

@@ -1,23 +1,46 @@
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
+import { reportTextSegmenterUnavailable } from './textSegmentGuards';
 // 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.
+// engine), segment() returns [] rather than throwing; compose a from-scratch UAX #29 backend into
+// the host for those environments.
 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).
+    const out = allocateEntity();
+    initializeWebTextSegmenterBackend(out);
+    return finishEntity(out);
+}
+// Stable bundled web provider. Hosts can import this directly when composing their explicit
+// capability object; callers that omit a host receive it as the final fallback.
+export const webTextSegmenterBackend = createWebTextSegmenterBackend();
+/** Describes which provider an operation would use and whether Intl.Segmenter is present. */
+export function explainTextSegmenterBackend(host) {
+    const backend = getTextSegmenterBackend(host);
+    const web = backend === webTextSegmenterBackend;
+    const intlSegmenterAvailable = hasIntlSegmenter();
+    return {
+        available: !web || intlSegmenterAvailable,
+        backend: web ? 'web-intl' : 'custom',
+        intlSegmenterAvailable,
+    };
+}
+// Returns the explicit host's provider when supplied, then the legacy installed backend, and
+// finally the bundled web provider. The explicit dependency always wins, so independent callers
+// can interleave different hosts without mutating shared capability state.
+export function getTextSegmenterBackend(host) {
+    return host?.text.segmenter ?? _backend ?? webTextSegmenterBackend;
+}
+export function initializeWebTextSegmenterBackend(out) {
+    out.segment = segmentWithIntlSegmenter;
+}
+/**
+ * Installs the backend used by calls that omit an explicit host; pass null to restore the stable
+ * bundled web default.
+ *
+ * @deprecated Pass a HasTextSegmenter to the segmentation or boundary operation. Retained for
+ * source compatibility until the legacy global path is removed.
+ */
 export function setTextSegmenterBackend(backend) {
     _backend = backend;
 }
@@ -28,8 +51,10 @@ let _backend = null;
 const _segmenterCache = new Map();
 const _segmenterCacheCapacity = 64;
 function getCachedSegmenter(locale, granularity) {
-    if (typeof Intl === 'undefined' || typeof Intl.Segmenter === 'undefined')
+    if (!hasIntlSegmenter()) {
+        reportTextSegmenterUnavailable();
         return null;
+    }
     const key = `${locale ?? ''}|${granularity}`;
     const existing = _segmenterCache.get(key);
     if (existing !== undefined)
@@ -43,6 +68,9 @@ function getCachedSegmenter(locale, granularity) {
     _segmenterCache.set(key, built);
     return built;
 }
+function hasIntlSegmenter() {
+    return typeof Intl !== 'undefined' && typeof Intl.Segmenter !== 'undefined';
+}
 function segmentWithIntlSegmenter(text, granularity, locale) {
     const segmenter = getCachedSegmenter(locale, granularity);
     if (segmenter === null)

package/dist/textSegmenterBackend.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/textsegment",
-  "version": "0.5.0-next.1944.cd6b6e7",
+  "version": "0.5.1-edge.1047.858b9b6",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.5.0-next.1944.cd6b6e7"
+    "@flighthq/entity": "0.5.1-edge.1047.858b9b6",
+    "@flighthq/log": "0.5.1-edge.1047.858b9b6",
+    "@flighthq/types": "0.5.1-edge.1047.858b9b6"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableTextSegmentGuards.test.ts

@@ -0,0 +1,47 @@
+import { clearLogOnceKeys, setLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { vi } from 'vitest';
+
+import { disableTextSegmentGuards, enableTextSegmentGuards } from './enableTextSegmentGuards';
+import { segmentGraphemes } from './textSegment';
+
+let entries: LogEntry[];
+
+beforeEach(() => {
+  clearLogOnceKeys();
+  entries = [];
+  setLogSink((entry) => entries.push(entry));
+});
+
+afterEach(() => {
+  disableTextSegmentGuards();
+  setLogSink(null);
+  vi.unstubAllGlobals();
+});
+
+describe('disableTextSegmentGuards', () => {
+  it('restores silent missing-engine recovery', () => {
+    enableTextSegmentGuards();
+    disableTextSegmentGuards();
+    vi.stubGlobal('Intl', { Segmenter: undefined });
+    segmentGraphemes('text');
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('enableTextSegmentGuards', () => {
+  it('warns once and names the backend fixing call when Intl.Segmenter is absent', () => {
+    enableTextSegmentGuards();
+    vi.stubGlobal('Intl', { Segmenter: undefined });
+    segmentGraphemes('first');
+    segmentGraphemes('second');
+    expect(entries).toHaveLength(1);
+    expect(String((entries[0].data as { message?: unknown }).message)).toContain('setTextSegmenterBackend');
+  });
+
+  it('stays silent when the bundled Intl provider is available', () => {
+    enableTextSegmentGuards();
+    segmentGraphemes('text');
+    expect(entries).toEqual([]);
+  });
+});

package/src/textSegment.test.ts

@@ -1,4 +1,11 @@
-import type { TextSegment, TextSegmentGranularity, TextSegmenterBackend } from '@flighthq/types/contract';
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
+import type { EntityRuntimeKey } from '@flighthq/types/contract';
+import type {
+  HasTextSegmenter,
+  TextSegment,
+  TextSegmentGranularity,
+  TextSegmenterBackend,
+} from '@flighthq/types/contract';
 
 import { segmentGraphemes, segmentSentences, segmentWords } from './textSegment';
 import { setTextSegmenterBackend } from './textSegmenterBackend';
@@ -6,6 +13,25 @@ import { setTextSegmenterBackend } from './textSegmenterBackend';
 afterEach(() => setTextSegmenterBackend(null));
 
 describe('segmentGraphemes', () => {
+  it('accepts an optional explicit segmenter host without breaking the existing signature', () => {
+    expectTypeOf(segmentGraphemes).toEqualTypeOf<
+      (text: string, locale?: string, host?: HasTextSegmenter) => readonly TextSegment[]
+    >();
+  });
+
+  it('gives an explicit host precedence over the legacy installed backend', () => {
+    setTextSegmenterBackend(taggingBackend('legacy'));
+    expect(segmentGraphemes('hi', undefined, segmenterHost(taggingBackend('explicit')))[0].text).toBe('explicit');
+  });
+
+  it('isolates callers that interleave different explicit hosts', () => {
+    const first = segmenterHost(taggingBackend('first'));
+    const second = segmenterHost(taggingBackend('second'));
+    expect(segmentGraphemes('hi', undefined, first)[0].text).toBe('first');
+    expect(segmentGraphemes('hi', undefined, second)[0].text).toBe('second');
+    expect(segmentGraphemes('hi', undefined, first)[0].text).toBe('first');
+  });
+
   it('treats a ZWJ family emoji as one grapheme', () => {
     const segments = segmentGraphemes('a👨‍👩‍👧b');
     expect(segments.map((s) => s.text)).toEqual(['a', '👨‍👩‍👧', 'b']);
@@ -21,18 +47,27 @@ describe('segmentGraphemes', () => {
 
   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 }];
-      },
+    const fake = allocateEntity<TextSegmenterBackend>();
+    fake.segment = (text: string, _granularity: TextSegmentGranularity, locale?: string): readonly TextSegment[] => {
+      seenLocale = locale;
+      return [{ start: 0, end: text.length, text }];
     };
-    setTextSegmenterBackend(fake);
+    setTextSegmenterBackend(finishEntity(fake));
     segmentGraphemes('hi', 'de-DE');
     expect(seenLocale).toBe('de-DE');
   });
 });
 
+function segmenterHost(segmenter: TextSegmenterBackend): HasTextSegmenter {
+  return { text: { segmenter } };
+}
+
+function taggingBackend(tag: string): TextSegmenterBackend {
+  const out = allocateEntity<TextSegmenterBackend>();
+  out.segment = () => [{ start: 0, end: tag.length, text: tag }];
+  return finishEntity(out);
+}
+
 describe('segmentSentences', () => {
   it('splits into sentences', () => {
     const segments = segmentSentences('Hi. Bye.');

package/src/textSegmentBoundary.test.ts

@@ -1,11 +1,18 @@
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
+import type { EntityRuntimeKey } from '@flighthq/types/contract';
+import type { HasTextSegmenter, TextSegmenterBackend } from '@flighthq/types/contract';
+import { vi } from 'vitest';
+
 import {
   getNextGraphemeBoundary,
+  getNextSentenceBoundary,
   getNextWordBoundary,
   getPreviousGraphemeBoundary,
+  getPreviousSentenceBoundary,
   getPreviousWordBoundary,
   getWordRangeAt,
 } from './textSegmentBoundary';
-import { setTextSegmenterBackend } from './textSegmenterBackend';
+import { setTextSegmenterBackend, webTextSegmenterBackend } from './textSegmenterBackend';
 
 afterEach(() => setTextSegmenterBackend(null));
 
@@ -31,6 +38,23 @@ describe('getNextGraphemeBoundary', () => {
   });
 });
 
+describe('getNextSentenceBoundary', () => {
+  it('advances to the next sentence start', () => {
+    expect(getNextSentenceBoundary('First. Second!', 0)).toBe(7);
+  });
+
+  it('clamps at text.length', () => {
+    expect(getNextSentenceBoundary('First.', 99)).toBe(6);
+  });
+
+  it('stops the bundled iterator without materializing backend TextSegment records', () => {
+    const segment = vi.spyOn(webTextSegmenterBackend, 'segment');
+    expect(getNextSentenceBoundary('First. Second!', 0)).toBe(7);
+    expect(segment).not.toHaveBeenCalled();
+    segment.mockRestore();
+  });
+});
+
 describe('getNextWordBoundary', () => {
   it('jumps to the end of the current word', () => {
     expect(getNextWordBoundary('foo bar', 0)).toBe(3);
@@ -57,6 +81,16 @@ describe('getPreviousGraphemeBoundary', () => {
   });
 });
 
+describe('getPreviousSentenceBoundary', () => {
+  it('steps back to the current sentence start', () => {
+    expect(getPreviousSentenceBoundary('First. Second!', 14)).toBe(7);
+  });
+
+  it('clamps at zero', () => {
+    expect(getPreviousSentenceBoundary('First.', -1)).toBe(0);
+  });
+});
+
 describe('getPreviousWordBoundary', () => {
   it('jumps to the start of the current word', () => {
     expect(getPreviousWordBoundary('foo bar', 7)).toBe(4);
@@ -68,6 +102,20 @@ describe('getPreviousWordBoundary', () => {
 });
 
 describe('getWordRangeAt', () => {
+  it('threads an explicit host through the boundary helper', () => {
+    const explicit = allocateEntity<TextSegmenterBackend>();
+    explicit.segment = (text: string) => [{ start: 0, end: text.length, text, isWordLike: true }];
+    const host: HasTextSegmenter = { text: { segmenter: finishEntity(explicit) } };
+    setTextSegmenterBackend(
+      (() => {
+        const out = allocateEntity<TextSegmenterBackend>();
+        out.segment = () => [];
+        return finishEntity(out);
+      })(),
+    );
+    expect(getWordRangeAt('word', 1, undefined, host)).toEqual({ start: 0, end: 4 });
+  });
+
   it('returns the word range under an index', () => {
     expect(getWordRangeAt('foo bar', 1)).toEqual({ start: 0, end: 3 });
   });
@@ -86,12 +134,16 @@ describe('getWordRangeAt', () => {
 
   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 }];
-      },
-    });
+    setTextSegmenterBackend(
+      (() => {
+        const out = allocateEntity<TextSegmenterBackend>();
+        out.segment = (text: string, _granularity: string, locale: string) => {
+          seenLocale = locale;
+          return [{ start: 0, end: text.length, text, isWordLike: true }];
+        };
+        return finishEntity(out);
+      })(),
+    );
     getWordRangeAt('word', 1, 'ja-JP');
     expect(seenLocale).toBe('ja-JP');
   });

package/src/textSegmentConformance.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { segmentGraphemes } from './textSegment';
+
+const graphemeFixtures: ReadonlyArray<{ clusters: string[]; text: string }> = [
+  { text: '🇺🇸🇨🇦', clusters: ['🇺🇸', '🇨🇦'] },
+  { text: '👨‍👩‍👧', clusters: ['👨‍👩‍👧'] },
+  { text: '\r\n', clusters: ['\r\n'] },
+  { text: '각', clusters: ['각'] },
+];
+
+describe('text segment conformance fixtures', () => {
+  it('covers regional indicators, ZWJ emoji, CRLF, and Hangul jamo', () => {
+    for (const fixture of graphemeFixtures) {
+      expect(segmentGraphemes(fixture.text).map((segment) => segment.text)).toEqual(fixture.clusters);
+    }
+  });
+});

package/src/textSegmentGuards.test.ts

@@ -0,0 +1,21 @@
+import { reportTextSegmenterUnavailable, setTextSegmentGuard } from './textSegmentGuards';
+
+afterEach(() => setTextSegmentGuard(null));
+
+describe('reportTextSegmenterUnavailable', () => {
+  it('is silent when no guard is installed', () => {
+    expect(() => reportTextSegmenterUnavailable()).not.toThrow();
+  });
+});
+
+describe('setTextSegmentGuard', () => {
+  it('replaces the active callback', () => {
+    let first = 0;
+    let second = 0;
+    setTextSegmentGuard(() => first++);
+    setTextSegmentGuard(() => second++);
+    reportTextSegmenterUnavailable();
+    expect(first).toBe(0);
+    expect(second).toBe(1);
+  });
+});

package/src/textSegmenterBackend.test.ts

@@ -1,9 +1,20 @@
-import type { TextSegment, TextSegmentGranularity, TextSegmenterBackend } from '@flighthq/types/contract';
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
+import type { EntityRuntimeKey } from '@flighthq/types/contract';
+import type {
+  HasTextSegmenter,
+  TextSegment,
+  TextSegmentGranularity,
+  TextSegmenterBackend,
+} from '@flighthq/types/contract';
+import { vi } from 'vitest';
 
 import {
   createWebTextSegmenterBackend,
+  explainTextSegmenterBackend,
   getTextSegmenterBackend,
+  initializeWebTextSegmenterBackend,
   setTextSegmenterBackend,
+  webTextSegmenterBackend,
 } from './textSegmenterBackend';
 
 interface RecordingBackend extends TextSegmenterBackend {
@@ -12,16 +23,19 @@ interface RecordingBackend extends TextSegmenterBackend {
 
 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 }];
-    },
+  const out = allocateEntity<any>();
+  out.calls = calls;
+  out.segment = (text: string, granularity: TextSegmentGranularity, locale?: string): readonly TextSegment[] => {
+    calls.push({ text, granularity, locale });
+    return [{ start: 0, end: text.length, text }];
   };
+  return finishEntity(out);
 }
 
-afterEach(() => setTextSegmenterBackend(null));
+afterEach(() => {
+  setTextSegmenterBackend(null);
+  vi.unstubAllGlobals();
+});
 
 describe('createWebTextSegmenterBackend', () => {
   it('segments a ZWJ family emoji as a single grapheme', () => {
@@ -47,10 +61,45 @@ describe('createWebTextSegmenterBackend', () => {
   });
 });
 
+describe('explainTextSegmenterBackend', () => {
+  it('reports the bundled Intl provider as available', () => {
+    expect(explainTextSegmenterBackend()).toEqual({
+      available: true,
+      backend: 'web-intl',
+      intlSegmenterAvailable: true,
+    });
+  });
+
+  it('identifies a custom provider independently of Intl availability', () => {
+    expect(explainTextSegmenterBackend(segmenterHost(recordingBackend()))).toEqual({
+      available: true,
+      backend: 'custom',
+      intlSegmenterAvailable: true,
+    });
+  });
+
+  it('reports the bundled provider unavailable when the runtime primitive is absent', () => {
+    vi.stubGlobal('Intl', { Segmenter: undefined });
+    expect(explainTextSegmenterBackend()).toEqual({
+      available: false,
+      backend: 'web-intl',
+      intlSegmenterAvailable: false,
+    });
+  });
+});
+
 describe('getTextSegmenterBackend', () => {
-  it('lazily falls back to a web backend when none is registered', () => {
+  it('returns an explicit host provider ahead of the legacy backend', () => {
+    const legacy = recordingBackend();
+    const explicit = recordingBackend();
+    const host: HasTextSegmenter = { text: { segmenter: explicit } };
+    setTextSegmenterBackend(legacy);
+    expect(getTextSegmenterBackend(host)).toBe(explicit);
+  });
+
+  it('falls back to the stable bundled web backend when none is registered', () => {
     const backend = getTextSegmenterBackend();
-    expect(backend).not.toBeNull();
+    expect(backend).toBe(webTextSegmenterBackend);
     expect(backend.segment('ab', 'grapheme').length).toBe(2);
   });
 
@@ -61,6 +110,12 @@ describe('getTextSegmenterBackend', () => {
   });
 });
 
+describe('initializeWebTextSegmenterBackend', () => {
+  it('is the construction initializer of createWebTextSegmenterBackend', () => {
+    expect(typeof initializeWebTextSegmenterBackend).toBe('function');
+  });
+});
+
 describe('setTextSegmenterBackend', () => {
   it('routes segmentation through the installed backend', () => {
     const backend = recordingBackend();
@@ -69,10 +124,23 @@ describe('setTextSegmenterBackend', () => {
     expect(backend.calls).toEqual([{ text: 'hello', granularity: 'sentence', locale: 'fr' }]);
   });
 
-  it('clears back to the lazy web default when passed null', () => {
+  it('clears back to the stable bundled 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);
   });
 });
+describe('webTextSegmenterBackend', () => {
+  it('provides the stable bundled Intl fallback', () => {
+    expect(webTextSegmenterBackend.segment('a👨‍👩‍👧b', 'grapheme').map((segment) => segment.text)).toEqual([
+      'a',
+      '👨‍👩‍👧',
+      'b',
+    ]);
+  });
+});
+
+function segmenterHost(segmenter: TextSegmenterBackend): HasTextSegmenter {
+  return { text: { segmenter } };
+}