@tldraw/utils 5.4.0-next.569ee2e27e8b → 5.4.0-next.591510702314

package/dist-cjs/index.d.ts

@@ -795,6 +795,16 @@ export declare function isNonNull<T>(value: T): value is typeof value extends nu
  */
 export declare function isNonNullish<T>(value: T): value is typeof value extends undefined ? never : typeof value extends null ? never : T;
 
+/**
+ * Iterate over the grapheme clusters of a string — user-perceived characters such as emoji
+ * sequences, flags, and accented letters — instead of UTF-16 code units. Uses `Intl.Segmenter`
+ * where available and falls back to iterating by code point on browsers that lack it, where a
+ * multi-code-point cluster is yielded as its component code points rather than as one segment.
+ *
+ * @public
+ */
+export declare function iterateGraphemes(str: string): IterableIterator<string>;
+
 /**
  * A type representing a JSON array containing any valid JSON values.
  * Arrays can contain mixed types of JSON values including nested arrays and objects.

package/dist-cjs/index.js

@@ -89,6 +89,7 @@ __export(index_exports, {
   isNativeStructuredClone: () => import_value.isNativeStructuredClone,
   isNonNull: () => import_value.isNonNull,
   isNonNullish: () => import_value.isNonNullish,
+  iterateGraphemes: () => import_string.iterateGraphemes,
   last: () => import_array.last,
   lerp: () => import_number.lerp,
   lns: () => import_hash.lns,
@@ -173,7 +174,7 @@ var import_version2 = require("./lib/version");
 var import_warn = require("./lib/warn");
 (0, import_version.registerTldrawLibraryVersion)(
   "@tldraw/utils",
-  "5.4.0-next.569ee2e27e8b",
+  "5.4.0-next.591510702314",
   "cjs"
 );
 //# sourceMappingURL=index.js.map

package/dist-cjs/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import { registerTldrawLibraryVersion } from './lib/version'\n\nexport { default as isEqual } from 'lodash.isequal'\nexport { default as isEqualWith } from 'lodash.isequalwith'\nexport { default as throttle } from 'lodash.throttle'\nexport { default as uniq } from 'lodash.uniq'\nexport {\n\tareArraysShallowEqual,\n\tcompact,\n\tdedupe,\n\tlast,\n\tmaxBy,\n\tmergeArraysAndReplaceDefaults,\n\tminBy,\n\tpartition,\n\trotateArray,\n} from './lib/array'\nexport { bind } from './lib/bind'\nexport { WeakCache } from './lib/cache'\nexport {\n\tassert,\n\tassertExists,\n\texhaustiveSwitchError,\n\tpromiseWithResolve,\n\tResult,\n\tsleep,\n\ttype ErrorResult,\n\ttype OkResult,\n} from './lib/control'\nexport { debounce } from './lib/debounce'\nexport { annotateError, getErrorAnnotations, type ErrorAnnotations } from './lib/error'\nexport { ExecutionQueue } from './lib/ExecutionQueue'\nexport { FileHelpers } from './lib/file'\nexport { noop, omitFromStackTrace } from './lib/function'\nexport { getHashForBuffer, getHashForObject, getHashForString, lns } from './lib/hash'\nexport { mockUniqueId, restoreUniqueId, uniqueId } from './lib/id'\nexport { getFirstFromIterable } from './lib/iterable'\nexport { LruCache } from './lib/LruCache'\nexport type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './lib/json-value'\nexport {\n\tDEFAULT_SUPPORT_VIDEO_TYPES,\n\tDEFAULT_SUPPORTED_IMAGE_TYPES,\n\tDEFAULT_SUPPORTED_MEDIA_TYPE_LIST,\n\tDEFAULT_SUPPORTED_MEDIA_TYPES,\n\tMediaHelpers,\n} from './lib/media/media'\nexport { PngHelpers } from './lib/media/png'\nexport { fetch, Image } from './lib/network'\nexport { invLerp, lerp, modulate, rng } from './lib/number'\nexport {\n\tareObjectsShallowEqual,\n\tfilterEntries,\n\tgetChangedKeys,\n\tgetOwnProperty,\n\tgroupBy,\n\thasOwnProperty,\n\tisEqualAllowingForFloatingPointErrors,\n\tmapObjectMapValues,\n\tobjectMapEntries,\n\tobjectMapEntriesIterable,\n\tobjectMapFromEntries,\n\tobjectMapKeys,\n\tobjectMapValues,\n\tomit,\n} from './lib/object'\nexport { measureAverageDuration, measureCbDuration, measureDuration } from './lib/perf'\nexport { PerformanceTracker } from './lib/PerformanceTracker'\nexport {\n\tgetIndexAbove,\n\tgetIndexBelow,\n\tgetIndexBetween,\n\tgetIndices,\n\tgetIndicesAbove,\n\tgetIndicesBelow,\n\tgetIndicesBetween,\n\tsortByIndex,\n\tsortByMaybeIndex,\n\tvalidateIndexKey,\n\tZERO_INDEX_KEY,\n\ttype IndexKey,\n} from './lib/reordering'\nexport { retry } from './lib/retry'\nexport { sortById } from './lib/sort'\nexport {\n\tclearLocalStorage,\n\tclearSessionStorage,\n\tdeleteFromLocalStorage,\n\tdeleteFromSessionStorage,\n\tgetFromLocalStorage,\n\tgetFromSessionStorage,\n\tsetInLocalStorage,\n\tsetInSessionStorage,\n} from './lib/storage'\nexport { getFirstCharacter } from './lib/string'\nexport { stringEnum } from './lib/stringEnum'\nexport { FpsScheduler, fpsThrottle, throttleToNextFrame } from './lib/throttle'\nexport { Timers } from './lib/timers'\nexport {\n\ttype Awaitable,\n\ttype Expand,\n\ttype MakeUndefinedOptional,\n\ttype RecursivePartial,\n\ttype Required,\n} from './lib/types'\nexport { safeParseUrl } from './lib/url'\nexport {\n\tisDefined,\n\tisNativeStructuredClone,\n\tisNonNull,\n\tisNonNullish,\n\tSTRUCTURED_CLONE_OBJECT_PROTOTYPE,\n\tstructuredClone,\n} from './lib/value'\nexport { registerTldrawLibraryVersion } from './lib/version'\nexport { warnDeprecatedGetter, warnOnce } from './lib/warn'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA6C;AAE7C,oBAAmC;AACnC,IAAAA,iBAAuC;AACvC,IAAAA,iBAAoC;AACpC,IAAAA,iBAAgC;AAChC,mBAUO;AACP,kBAAqB;AACrB,mBAA0B;AAC1B,qBASO;AACP,sBAAyB;AACzB,mBAA0E;AAC1E,4BAA+B;AAC/B,kBAA4B;AAC5B,sBAAyC;AACzC,kBAA0E;AAC1E,gBAAwD;AACxD,sBAAqC;AACrC,sBAAyB;AAEzB,mBAMO;AACP,iBAA2B;AAC3B,qBAA6B;AAC7B,oBAA6C;AAC7C,oBAeO;AACP,kBAA2E;AAC3E,gCAAmC;AACnC,wBAaO;AACP,mBAAsB;AACtB,kBAAyB;AACzB,qBASO;AACP,oBAAkC;AAClC,wBAA2B;AAC3B,sBAA+D;AAC/D,oBAAuB;AAQvB,iBAA6B;AAC7B,mBAOO;AACP,IAAAC,kBAA6C;AAC7C,kBAA+C;AAAA,IAE/C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
+  "sourcesContent": ["import { registerTldrawLibraryVersion } from './lib/version'\n\nexport { default as isEqual } from 'lodash.isequal'\nexport { default as isEqualWith } from 'lodash.isequalwith'\nexport { default as throttle } from 'lodash.throttle'\nexport { default as uniq } from 'lodash.uniq'\nexport {\n\tareArraysShallowEqual,\n\tcompact,\n\tdedupe,\n\tlast,\n\tmaxBy,\n\tmergeArraysAndReplaceDefaults,\n\tminBy,\n\tpartition,\n\trotateArray,\n} from './lib/array'\nexport { bind } from './lib/bind'\nexport { WeakCache } from './lib/cache'\nexport {\n\tassert,\n\tassertExists,\n\texhaustiveSwitchError,\n\tpromiseWithResolve,\n\tResult,\n\tsleep,\n\ttype ErrorResult,\n\ttype OkResult,\n} from './lib/control'\nexport { debounce } from './lib/debounce'\nexport { annotateError, getErrorAnnotations, type ErrorAnnotations } from './lib/error'\nexport { ExecutionQueue } from './lib/ExecutionQueue'\nexport { FileHelpers } from './lib/file'\nexport { noop, omitFromStackTrace } from './lib/function'\nexport { getHashForBuffer, getHashForObject, getHashForString, lns } from './lib/hash'\nexport { mockUniqueId, restoreUniqueId, uniqueId } from './lib/id'\nexport { getFirstFromIterable } from './lib/iterable'\nexport { LruCache } from './lib/LruCache'\nexport type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './lib/json-value'\nexport {\n\tDEFAULT_SUPPORT_VIDEO_TYPES,\n\tDEFAULT_SUPPORTED_IMAGE_TYPES,\n\tDEFAULT_SUPPORTED_MEDIA_TYPE_LIST,\n\tDEFAULT_SUPPORTED_MEDIA_TYPES,\n\tMediaHelpers,\n} from './lib/media/media'\nexport { PngHelpers } from './lib/media/png'\nexport { fetch, Image } from './lib/network'\nexport { invLerp, lerp, modulate, rng } from './lib/number'\nexport {\n\tareObjectsShallowEqual,\n\tfilterEntries,\n\tgetChangedKeys,\n\tgetOwnProperty,\n\tgroupBy,\n\thasOwnProperty,\n\tisEqualAllowingForFloatingPointErrors,\n\tmapObjectMapValues,\n\tobjectMapEntries,\n\tobjectMapEntriesIterable,\n\tobjectMapFromEntries,\n\tobjectMapKeys,\n\tobjectMapValues,\n\tomit,\n} from './lib/object'\nexport { measureAverageDuration, measureCbDuration, measureDuration } from './lib/perf'\nexport { PerformanceTracker } from './lib/PerformanceTracker'\nexport {\n\tgetIndexAbove,\n\tgetIndexBelow,\n\tgetIndexBetween,\n\tgetIndices,\n\tgetIndicesAbove,\n\tgetIndicesBelow,\n\tgetIndicesBetween,\n\tsortByIndex,\n\tsortByMaybeIndex,\n\tvalidateIndexKey,\n\tZERO_INDEX_KEY,\n\ttype IndexKey,\n} from './lib/reordering'\nexport { retry } from './lib/retry'\nexport { sortById } from './lib/sort'\nexport {\n\tclearLocalStorage,\n\tclearSessionStorage,\n\tdeleteFromLocalStorage,\n\tdeleteFromSessionStorage,\n\tgetFromLocalStorage,\n\tgetFromSessionStorage,\n\tsetInLocalStorage,\n\tsetInSessionStorage,\n} from './lib/storage'\nexport { getFirstCharacter, iterateGraphemes } from './lib/string'\nexport { stringEnum } from './lib/stringEnum'\nexport { FpsScheduler, fpsThrottle, throttleToNextFrame } from './lib/throttle'\nexport { Timers } from './lib/timers'\nexport {\n\ttype Awaitable,\n\ttype Expand,\n\ttype MakeUndefinedOptional,\n\ttype RecursivePartial,\n\ttype Required,\n} from './lib/types'\nexport { safeParseUrl } from './lib/url'\nexport {\n\tisDefined,\n\tisNativeStructuredClone,\n\tisNonNull,\n\tisNonNullish,\n\tSTRUCTURED_CLONE_OBJECT_PROTOTYPE,\n\tstructuredClone,\n} from './lib/value'\nexport { registerTldrawLibraryVersion } from './lib/version'\nexport { warnDeprecatedGetter, warnOnce } from './lib/warn'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA6C;AAE7C,oBAAmC;AACnC,IAAAA,iBAAuC;AACvC,IAAAA,iBAAoC;AACpC,IAAAA,iBAAgC;AAChC,mBAUO;AACP,kBAAqB;AACrB,mBAA0B;AAC1B,qBASO;AACP,sBAAyB;AACzB,mBAA0E;AAC1E,4BAA+B;AAC/B,kBAA4B;AAC5B,sBAAyC;AACzC,kBAA0E;AAC1E,gBAAwD;AACxD,sBAAqC;AACrC,sBAAyB;AAEzB,mBAMO;AACP,iBAA2B;AAC3B,qBAA6B;AAC7B,oBAA6C;AAC7C,oBAeO;AACP,kBAA2E;AAC3E,gCAAmC;AACnC,wBAaO;AACP,mBAAsB;AACtB,kBAAyB;AACzB,qBASO;AACP,oBAAoD;AACpD,wBAA2B;AAC3B,sBAA+D;AAC/D,oBAAuB;AAQvB,iBAA6B;AAC7B,mBAOO;AACP,IAAAC,kBAA6C;AAC7C,kBAA+C;AAAA,IAE/C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
   "names": ["import_lodash", "import_version"]
 }

package/dist-cjs/lib/string.js

@@ -18,14 +18,32 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var string_exports = {};
 __export(string_exports, {
-  getFirstCharacter: () => getFirstCharacter
+  getFirstCharacter: () => getFirstCharacter,
+  iterateGraphemes: () => iterateGraphemes
 });
 module.exports = __toCommonJS(string_exports);
 let graphemeSegmenter;
+let checkedForSegmenter = false;
+function getGraphemeSegmenter() {
+  if (!checkedForSegmenter) {
+    checkedForSegmenter = true;
+    if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
+      graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+    }
+  }
+  return graphemeSegmenter;
+}
+function* iterateGraphemes(str) {
+  const segmenter = getGraphemeSegmenter();
+  if (segmenter) {
+    for (const { segment } of segmenter.segment(str)) yield segment;
+  } else {
+    yield* str;
+  }
+}
 function getFirstCharacter(str) {
   if (!str) return "";
-  graphemeSegmenter ??= new Intl.Segmenter(void 0, { granularity: "grapheme" });
-  for (const { segment } of graphemeSegmenter.segment(str)) {
+  for (const segment of iterateGraphemes(str)) {
     return segment;
   }
   return "";

package/dist-cjs/lib/string.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/string.ts"],
-  "sourcesContent": ["let graphemeSegmenter: Intl.Segmenter | undefined\n\n/**\n * Get the first character of a string, treating a multi-code-unit character such as an emoji as a\n * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so\n * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an\n * empty string when the input is empty.\n *\n * @example\n * ```ts\n * getFirstCharacter('hello') // 'h'\n * getFirstCharacter('\uD83D\uDE00 hello') // '\uD83D\uDE00'\n * getFirstCharacter('') // ''\n * ```\n *\n * @public\n */\nexport function getFirstCharacter(str: string): string {\n\tif (!str) return ''\n\tgraphemeSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' })\n\tfor (const { segment } of graphemeSegmenter.segment(str)) {\n\t\treturn segment\n\t}\n\treturn ''\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAI;AAiBG,SAAS,kBAAkB,KAAqB;AACtD,MAAI,CAAC,IAAK,QAAO;AACjB,wBAAsB,IAAI,KAAK,UAAU,QAAW,EAAE,aAAa,WAAW,CAAC;AAC/E,aAAW,EAAE,QAAQ,KAAK,kBAAkB,QAAQ,GAAG,GAAG;AACzD,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
+  "sourcesContent": ["let graphemeSegmenter: Intl.Segmenter | undefined\nlet checkedForSegmenter = false\n\n/**\n * Resolve a shared grapheme `Intl.Segmenter`, or `undefined` when the runtime has no\n * `Intl.Segmenter`. `Intl.Segmenter` is unavailable on some older browsers (notably Firefox before\n * 125), so feature-detect it once rather than constructing it eagerly, which would throw at module\n * load and take down the whole app.\n */\nfunction getGraphemeSegmenter(): Intl.Segmenter | undefined {\n\tif (!checkedForSegmenter) {\n\t\tcheckedForSegmenter = true\n\t\tif (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {\n\t\t\tgraphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })\n\t\t}\n\t}\n\treturn graphemeSegmenter\n}\n\n/**\n * Iterate over the grapheme clusters of a string \u2014 user-perceived characters such as emoji\n * sequences, flags, and accented letters \u2014 instead of UTF-16 code units. Uses `Intl.Segmenter`\n * where available and falls back to iterating by code point on browsers that lack it, where a\n * multi-code-point cluster is yielded as its component code points rather than as one segment.\n *\n * @public\n */\nexport function* iterateGraphemes(str: string): IterableIterator<string> {\n\tconst segmenter = getGraphemeSegmenter()\n\tif (segmenter) {\n\t\tfor (const { segment } of segmenter.segment(str)) yield segment\n\t} else {\n\t\tyield* str\n\t}\n}\n\n/**\n * Get the first character of a string, treating a multi-code-unit character such as an emoji as a\n * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so\n * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an\n * empty string when the input is empty.\n *\n * @example\n * ```ts\n * getFirstCharacter('hello') // 'h'\n * getFirstCharacter('\uD83D\uDE00 hello') // '\uD83D\uDE00'\n * getFirstCharacter('') // ''\n * ```\n *\n * @public\n */\nexport function getFirstCharacter(str: string): string {\n\tif (!str) return ''\n\tfor (const segment of iterateGraphemes(str)) {\n\t\treturn segment\n\t}\n\treturn ''\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAI;AACJ,IAAI,sBAAsB;AAQ1B,SAAS,uBAAmD;AAC3D,MAAI,CAAC,qBAAqB;AACzB,0BAAsB;AACtB,QAAI,OAAO,SAAS,eAAe,eAAe,MAAM;AACvD,0BAAoB,IAAI,KAAK,UAAU,QAAW,EAAE,aAAa,WAAW,CAAC;AAAA,IAC9E;AAAA,EACD;AACA,SAAO;AACR;AAUO,UAAU,iBAAiB,KAAuC;AACxE,QAAM,YAAY,qBAAqB;AACvC,MAAI,WAAW;AACd,eAAW,EAAE,QAAQ,KAAK,UAAU,QAAQ,GAAG,EAAG,OAAM;AAAA,EACzD,OAAO;AACN,WAAO;AAAA,EACR;AACD;AAiBO,SAAS,kBAAkB,KAAqB;AACtD,MAAI,CAAC,IAAK,QAAO;AACjB,aAAW,WAAW,iBAAiB,GAAG,GAAG;AAC5C,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
   "names": []
 }

package/dist-esm/index.d.mts

@@ -795,6 +795,16 @@ export declare function isNonNull<T>(value: T): value is typeof value extends nu
  */
 export declare function isNonNullish<T>(value: T): value is typeof value extends undefined ? never : typeof value extends null ? never : T;
 
+/**
+ * Iterate over the grapheme clusters of a string — user-perceived characters such as emoji
+ * sequences, flags, and accented letters — instead of UTF-16 code units. Uses `Intl.Segmenter`
+ * where available and falls back to iterating by code point on browsers that lack it, where a
+ * multi-code-point cluster is yielded as its component code points rather than as one segment.
+ *
+ * @public
+ */
+export declare function iterateGraphemes(str: string): IterableIterator<string>;
+
 /**
  * A type representing a JSON array containing any valid JSON values.
  * Arrays can contain mixed types of JSON values including nested arrays and objects.

package/dist-esm/index.mjs

@@ -86,7 +86,7 @@ import {
   setInLocalStorage,
   setInSessionStorage
 } from "./lib/storage.mjs";
-import { getFirstCharacter } from "./lib/string.mjs";
+import { getFirstCharacter, iterateGraphemes } from "./lib/string.mjs";
 import { stringEnum } from "./lib/stringEnum.mjs";
 import { FpsScheduler, fpsThrottle, throttleToNextFrame } from "./lib/throttle.mjs";
 import { Timers } from "./lib/timers.mjs";
@@ -103,7 +103,7 @@ import { registerTldrawLibraryVersion as registerTldrawLibraryVersion2 } from ".
 import { warnDeprecatedGetter, warnOnce } from "./lib/warn.mjs";
 registerTldrawLibraryVersion(
   "@tldraw/utils",
-  "5.4.0-next.569ee2e27e8b",
+  "5.4.0-next.591510702314",
   "esm"
 );
 export {
@@ -168,6 +168,7 @@ export {
   isNativeStructuredClone,
   isNonNull,
   isNonNullish,
+  iterateGraphemes,
   last,
   lerp,
   lns,

package/dist-esm/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import { registerTldrawLibraryVersion } from './lib/version'\n\nexport { default as isEqual } from 'lodash.isequal'\nexport { default as isEqualWith } from 'lodash.isequalwith'\nexport { default as throttle } from 'lodash.throttle'\nexport { default as uniq } from 'lodash.uniq'\nexport {\n\tareArraysShallowEqual,\n\tcompact,\n\tdedupe,\n\tlast,\n\tmaxBy,\n\tmergeArraysAndReplaceDefaults,\n\tminBy,\n\tpartition,\n\trotateArray,\n} from './lib/array'\nexport { bind } from './lib/bind'\nexport { WeakCache } from './lib/cache'\nexport {\n\tassert,\n\tassertExists,\n\texhaustiveSwitchError,\n\tpromiseWithResolve,\n\tResult,\n\tsleep,\n\ttype ErrorResult,\n\ttype OkResult,\n} from './lib/control'\nexport { debounce } from './lib/debounce'\nexport { annotateError, getErrorAnnotations, type ErrorAnnotations } from './lib/error'\nexport { ExecutionQueue } from './lib/ExecutionQueue'\nexport { FileHelpers } from './lib/file'\nexport { noop, omitFromStackTrace } from './lib/function'\nexport { getHashForBuffer, getHashForObject, getHashForString, lns } from './lib/hash'\nexport { mockUniqueId, restoreUniqueId, uniqueId } from './lib/id'\nexport { getFirstFromIterable } from './lib/iterable'\nexport { LruCache } from './lib/LruCache'\nexport type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './lib/json-value'\nexport {\n\tDEFAULT_SUPPORT_VIDEO_TYPES,\n\tDEFAULT_SUPPORTED_IMAGE_TYPES,\n\tDEFAULT_SUPPORTED_MEDIA_TYPE_LIST,\n\tDEFAULT_SUPPORTED_MEDIA_TYPES,\n\tMediaHelpers,\n} from './lib/media/media'\nexport { PngHelpers } from './lib/media/png'\nexport { fetch, Image } from './lib/network'\nexport { invLerp, lerp, modulate, rng } from './lib/number'\nexport {\n\tareObjectsShallowEqual,\n\tfilterEntries,\n\tgetChangedKeys,\n\tgetOwnProperty,\n\tgroupBy,\n\thasOwnProperty,\n\tisEqualAllowingForFloatingPointErrors,\n\tmapObjectMapValues,\n\tobjectMapEntries,\n\tobjectMapEntriesIterable,\n\tobjectMapFromEntries,\n\tobjectMapKeys,\n\tobjectMapValues,\n\tomit,\n} from './lib/object'\nexport { measureAverageDuration, measureCbDuration, measureDuration } from './lib/perf'\nexport { PerformanceTracker } from './lib/PerformanceTracker'\nexport {\n\tgetIndexAbove,\n\tgetIndexBelow,\n\tgetIndexBetween,\n\tgetIndices,\n\tgetIndicesAbove,\n\tgetIndicesBelow,\n\tgetIndicesBetween,\n\tsortByIndex,\n\tsortByMaybeIndex,\n\tvalidateIndexKey,\n\tZERO_INDEX_KEY,\n\ttype IndexKey,\n} from './lib/reordering'\nexport { retry } from './lib/retry'\nexport { sortById } from './lib/sort'\nexport {\n\tclearLocalStorage,\n\tclearSessionStorage,\n\tdeleteFromLocalStorage,\n\tdeleteFromSessionStorage,\n\tgetFromLocalStorage,\n\tgetFromSessionStorage,\n\tsetInLocalStorage,\n\tsetInSessionStorage,\n} from './lib/storage'\nexport { getFirstCharacter } from './lib/string'\nexport { stringEnum } from './lib/stringEnum'\nexport { FpsScheduler, fpsThrottle, throttleToNextFrame } from './lib/throttle'\nexport { Timers } from './lib/timers'\nexport {\n\ttype Awaitable,\n\ttype Expand,\n\ttype MakeUndefinedOptional,\n\ttype RecursivePartial,\n\ttype Required,\n} from './lib/types'\nexport { safeParseUrl } from './lib/url'\nexport {\n\tisDefined,\n\tisNativeStructuredClone,\n\tisNonNull,\n\tisNonNullish,\n\tSTRUCTURED_CLONE_OBJECT_PROTOTYPE,\n\tstructuredClone,\n} from './lib/value'\nexport { registerTldrawLibraryVersion } from './lib/version'\nexport { warnDeprecatedGetter, warnOnce } from './lib/warn'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
-  "mappings": "AAAA,SAAS,oCAAoC;AAE7C,SAAoB,WAAXA,gBAA0B;AACnC,SAAoB,WAAXA,gBAA8B;AACvC,SAAoB,WAAXA,gBAA2B;AACpC,SAAoB,WAAXA,gBAAuB;AAChC;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,YAAY;AACrB,SAAS,iBAAiB;AAC1B;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGM;AACP,SAAS,gBAAgB;AACzB,SAAS,eAAe,2BAAkD;AAC1E,SAAS,sBAAsB;AAC/B,SAAS,mBAAmB;AAC5B,SAAS,MAAM,0BAA0B;AACzC,SAAS,kBAAkB,kBAAkB,kBAAkB,WAAW;AAC1E,SAAS,cAAc,iBAAiB,gBAAgB;AACxD,SAAS,4BAA4B;AACrC,SAAS,gBAAgB;AAEzB;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,kBAAkB;AAC3B,SAAS,OAAO,aAAa;AAC7B,SAAS,SAAS,MAAM,UAAU,WAAW;AAC7C;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,wBAAwB,mBAAmB,uBAAuB;AAC3E,SAAS,0BAA0B;AACnC;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEM;AACP,SAAS,aAAa;AACtB,SAAS,gBAAgB;AACzB;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,yBAAyB;AAClC,SAAS,kBAAkB;AAC3B,SAAS,cAAc,aAAa,2BAA2B;AAC/D,SAAS,cAAc;AAQvB,SAAS,oBAAoB;AAC7B;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,gCAAAC,qCAAoC;AAC7C,SAAS,sBAAsB,gBAAgB;AAE/C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
+  "sourcesContent": ["import { registerTldrawLibraryVersion } from './lib/version'\n\nexport { default as isEqual } from 'lodash.isequal'\nexport { default as isEqualWith } from 'lodash.isequalwith'\nexport { default as throttle } from 'lodash.throttle'\nexport { default as uniq } from 'lodash.uniq'\nexport {\n\tareArraysShallowEqual,\n\tcompact,\n\tdedupe,\n\tlast,\n\tmaxBy,\n\tmergeArraysAndReplaceDefaults,\n\tminBy,\n\tpartition,\n\trotateArray,\n} from './lib/array'\nexport { bind } from './lib/bind'\nexport { WeakCache } from './lib/cache'\nexport {\n\tassert,\n\tassertExists,\n\texhaustiveSwitchError,\n\tpromiseWithResolve,\n\tResult,\n\tsleep,\n\ttype ErrorResult,\n\ttype OkResult,\n} from './lib/control'\nexport { debounce } from './lib/debounce'\nexport { annotateError, getErrorAnnotations, type ErrorAnnotations } from './lib/error'\nexport { ExecutionQueue } from './lib/ExecutionQueue'\nexport { FileHelpers } from './lib/file'\nexport { noop, omitFromStackTrace } from './lib/function'\nexport { getHashForBuffer, getHashForObject, getHashForString, lns } from './lib/hash'\nexport { mockUniqueId, restoreUniqueId, uniqueId } from './lib/id'\nexport { getFirstFromIterable } from './lib/iterable'\nexport { LruCache } from './lib/LruCache'\nexport type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './lib/json-value'\nexport {\n\tDEFAULT_SUPPORT_VIDEO_TYPES,\n\tDEFAULT_SUPPORTED_IMAGE_TYPES,\n\tDEFAULT_SUPPORTED_MEDIA_TYPE_LIST,\n\tDEFAULT_SUPPORTED_MEDIA_TYPES,\n\tMediaHelpers,\n} from './lib/media/media'\nexport { PngHelpers } from './lib/media/png'\nexport { fetch, Image } from './lib/network'\nexport { invLerp, lerp, modulate, rng } from './lib/number'\nexport {\n\tareObjectsShallowEqual,\n\tfilterEntries,\n\tgetChangedKeys,\n\tgetOwnProperty,\n\tgroupBy,\n\thasOwnProperty,\n\tisEqualAllowingForFloatingPointErrors,\n\tmapObjectMapValues,\n\tobjectMapEntries,\n\tobjectMapEntriesIterable,\n\tobjectMapFromEntries,\n\tobjectMapKeys,\n\tobjectMapValues,\n\tomit,\n} from './lib/object'\nexport { measureAverageDuration, measureCbDuration, measureDuration } from './lib/perf'\nexport { PerformanceTracker } from './lib/PerformanceTracker'\nexport {\n\tgetIndexAbove,\n\tgetIndexBelow,\n\tgetIndexBetween,\n\tgetIndices,\n\tgetIndicesAbove,\n\tgetIndicesBelow,\n\tgetIndicesBetween,\n\tsortByIndex,\n\tsortByMaybeIndex,\n\tvalidateIndexKey,\n\tZERO_INDEX_KEY,\n\ttype IndexKey,\n} from './lib/reordering'\nexport { retry } from './lib/retry'\nexport { sortById } from './lib/sort'\nexport {\n\tclearLocalStorage,\n\tclearSessionStorage,\n\tdeleteFromLocalStorage,\n\tdeleteFromSessionStorage,\n\tgetFromLocalStorage,\n\tgetFromSessionStorage,\n\tsetInLocalStorage,\n\tsetInSessionStorage,\n} from './lib/storage'\nexport { getFirstCharacter, iterateGraphemes } from './lib/string'\nexport { stringEnum } from './lib/stringEnum'\nexport { FpsScheduler, fpsThrottle, throttleToNextFrame } from './lib/throttle'\nexport { Timers } from './lib/timers'\nexport {\n\ttype Awaitable,\n\ttype Expand,\n\ttype MakeUndefinedOptional,\n\ttype RecursivePartial,\n\ttype Required,\n} from './lib/types'\nexport { safeParseUrl } from './lib/url'\nexport {\n\tisDefined,\n\tisNativeStructuredClone,\n\tisNonNull,\n\tisNonNullish,\n\tSTRUCTURED_CLONE_OBJECT_PROTOTYPE,\n\tstructuredClone,\n} from './lib/value'\nexport { registerTldrawLibraryVersion } from './lib/version'\nexport { warnDeprecatedGetter, warnOnce } from './lib/warn'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
+  "mappings": "AAAA,SAAS,oCAAoC;AAE7C,SAAoB,WAAXA,gBAA0B;AACnC,SAAoB,WAAXA,gBAA8B;AACvC,SAAoB,WAAXA,gBAA2B;AACpC,SAAoB,WAAXA,gBAAuB;AAChC;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,YAAY;AACrB,SAAS,iBAAiB;AAC1B;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGM;AACP,SAAS,gBAAgB;AACzB,SAAS,eAAe,2BAAkD;AAC1E,SAAS,sBAAsB;AAC/B,SAAS,mBAAmB;AAC5B,SAAS,MAAM,0BAA0B;AACzC,SAAS,kBAAkB,kBAAkB,kBAAkB,WAAW;AAC1E,SAAS,cAAc,iBAAiB,gBAAgB;AACxD,SAAS,4BAA4B;AACrC,SAAS,gBAAgB;AAEzB;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,kBAAkB;AAC3B,SAAS,OAAO,aAAa;AAC7B,SAAS,SAAS,MAAM,UAAU,WAAW;AAC7C;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,wBAAwB,mBAAmB,uBAAuB;AAC3E,SAAS,0BAA0B;AACnC;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEM;AACP,SAAS,aAAa;AACtB,SAAS,gBAAgB;AACzB;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,mBAAmB,wBAAwB;AACpD,SAAS,kBAAkB;AAC3B,SAAS,cAAc,aAAa,2BAA2B;AAC/D,SAAS,cAAc;AAQvB,SAAS,oBAAoB;AAC7B;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACM;AACP,SAAS,gCAAAC,qCAAoC;AAC7C,SAAS,sBAAsB,gBAAgB;AAE/C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
   "names": ["default", "registerTldrawLibraryVersion"]
 }

package/dist-esm/lib/string.mjs

@@ -1,13 +1,31 @@
 let graphemeSegmenter;
+let checkedForSegmenter = false;
+function getGraphemeSegmenter() {
+  if (!checkedForSegmenter) {
+    checkedForSegmenter = true;
+    if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
+      graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+    }
+  }
+  return graphemeSegmenter;
+}
+function* iterateGraphemes(str) {
+  const segmenter = getGraphemeSegmenter();
+  if (segmenter) {
+    for (const { segment } of segmenter.segment(str)) yield segment;
+  } else {
+    yield* str;
+  }
+}
 function getFirstCharacter(str) {
   if (!str) return "";
-  graphemeSegmenter ??= new Intl.Segmenter(void 0, { granularity: "grapheme" });
-  for (const { segment } of graphemeSegmenter.segment(str)) {
+  for (const segment of iterateGraphemes(str)) {
     return segment;
   }
   return "";
 }
 export {
-  getFirstCharacter
+  getFirstCharacter,
+  iterateGraphemes
 };
 //# sourceMappingURL=string.mjs.map

package/dist-esm/lib/string.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/string.ts"],
-  "sourcesContent": ["let graphemeSegmenter: Intl.Segmenter | undefined\n\n/**\n * Get the first character of a string, treating a multi-code-unit character such as an emoji as a\n * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so\n * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an\n * empty string when the input is empty.\n *\n * @example\n * ```ts\n * getFirstCharacter('hello') // 'h'\n * getFirstCharacter('\uD83D\uDE00 hello') // '\uD83D\uDE00'\n * getFirstCharacter('') // ''\n * ```\n *\n * @public\n */\nexport function getFirstCharacter(str: string): string {\n\tif (!str) return ''\n\tgraphemeSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' })\n\tfor (const { segment } of graphemeSegmenter.segment(str)) {\n\t\treturn segment\n\t}\n\treturn ''\n}\n"],
-  "mappings": "AAAA,IAAI;AAiBG,SAAS,kBAAkB,KAAqB;AACtD,MAAI,CAAC,IAAK,QAAO;AACjB,wBAAsB,IAAI,KAAK,UAAU,QAAW,EAAE,aAAa,WAAW,CAAC;AAC/E,aAAW,EAAE,QAAQ,KAAK,kBAAkB,QAAQ,GAAG,GAAG;AACzD,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
+  "sourcesContent": ["let graphemeSegmenter: Intl.Segmenter | undefined\nlet checkedForSegmenter = false\n\n/**\n * Resolve a shared grapheme `Intl.Segmenter`, or `undefined` when the runtime has no\n * `Intl.Segmenter`. `Intl.Segmenter` is unavailable on some older browsers (notably Firefox before\n * 125), so feature-detect it once rather than constructing it eagerly, which would throw at module\n * load and take down the whole app.\n */\nfunction getGraphemeSegmenter(): Intl.Segmenter | undefined {\n\tif (!checkedForSegmenter) {\n\t\tcheckedForSegmenter = true\n\t\tif (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {\n\t\t\tgraphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })\n\t\t}\n\t}\n\treturn graphemeSegmenter\n}\n\n/**\n * Iterate over the grapheme clusters of a string \u2014 user-perceived characters such as emoji\n * sequences, flags, and accented letters \u2014 instead of UTF-16 code units. Uses `Intl.Segmenter`\n * where available and falls back to iterating by code point on browsers that lack it, where a\n * multi-code-point cluster is yielded as its component code points rather than as one segment.\n *\n * @public\n */\nexport function* iterateGraphemes(str: string): IterableIterator<string> {\n\tconst segmenter = getGraphemeSegmenter()\n\tif (segmenter) {\n\t\tfor (const { segment } of segmenter.segment(str)) yield segment\n\t} else {\n\t\tyield* str\n\t}\n}\n\n/**\n * Get the first character of a string, treating a multi-code-unit character such as an emoji as a\n * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so\n * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an\n * empty string when the input is empty.\n *\n * @example\n * ```ts\n * getFirstCharacter('hello') // 'h'\n * getFirstCharacter('\uD83D\uDE00 hello') // '\uD83D\uDE00'\n * getFirstCharacter('') // ''\n * ```\n *\n * @public\n */\nexport function getFirstCharacter(str: string): string {\n\tif (!str) return ''\n\tfor (const segment of iterateGraphemes(str)) {\n\t\treturn segment\n\t}\n\treturn ''\n}\n"],
+  "mappings": "AAAA,IAAI;AACJ,IAAI,sBAAsB;AAQ1B,SAAS,uBAAmD;AAC3D,MAAI,CAAC,qBAAqB;AACzB,0BAAsB;AACtB,QAAI,OAAO,SAAS,eAAe,eAAe,MAAM;AACvD,0BAAoB,IAAI,KAAK,UAAU,QAAW,EAAE,aAAa,WAAW,CAAC;AAAA,IAC9E;AAAA,EACD;AACA,SAAO;AACR;AAUO,UAAU,iBAAiB,KAAuC;AACxE,QAAM,YAAY,qBAAqB;AACvC,MAAI,WAAW;AACd,eAAW,EAAE,QAAQ,KAAK,UAAU,QAAQ,GAAG,EAAG,OAAM;AAAA,EACzD,OAAO;AACN,WAAO;AAAA,EACR;AACD;AAiBO,SAAS,kBAAkB,KAAqB;AACtD,MAAI,CAAC,IAAK,QAAO;AACjB,aAAW,WAAW,iBAAiB,GAAG,GAAG;AAC5C,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
   "names": []
 }

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@tldraw/utils",
   "description": "tldraw infinite canvas SDK (private utilities).",
-  "version": "5.4.0-next.569ee2e27e8b",
+  "version": "5.4.0-next.591510702314",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
   },
   "homepage": "https://tldraw.dev",
   "license": "SEE LICENSE IN LICENSE.md",
+  "tldraw_product": {
+    "stableId": "tldraw:sdk-core",
+    "name": "SDK",
+    "type": "product",
+    "premium": false
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/tldraw/tldraw"

package/src/index.ts

@@ -91,7 +91,7 @@ export {
 	setInLocalStorage,
 	setInSessionStorage,
 } from './lib/storage'
-export { getFirstCharacter } from './lib/string'
+export { getFirstCharacter, iterateGraphemes } from './lib/string'
 export { stringEnum } from './lib/stringEnum'
 export { FpsScheduler, fpsThrottle, throttleToNextFrame } from './lib/throttle'
 export { Timers } from './lib/timers'

package/src/lib/string.test.ts

@@ -1,4 +1,5 @@
-import { getFirstCharacter } from './string'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getFirstCharacter, iterateGraphemes } from './string'
 
 describe('getFirstCharacter', () => {
 	it('returns the first character of a plain string', () => {
@@ -21,3 +22,59 @@ describe('getFirstCharacter', () => {
 		expect(getFirstCharacter(' hi')).toBe(' ')
 	})
 })
+
+describe('iterateGraphemes', () => {
+	it('yields each grapheme cluster in order', () => {
+		expect([...iterateGraphemes('a😀b')]).toEqual(['a', '😀', 'b'])
+	})
+
+	it('keeps a multi-code-point cluster whole', () => {
+		expect([...iterateGraphemes('👨‍👩‍👧!')]).toEqual(['👨‍👩‍👧', '!'])
+	})
+
+	it('yields nothing for an empty string', () => {
+		expect([...iterateGraphemes('')]).toEqual([])
+	})
+})
+
+// On browsers without `Intl.Segmenter` (e.g. Firefox before 125) the module must not throw and must
+// still iterate; it falls back to code-point iteration. The segmenter is probed lazily on first
+// use, so `Intl.Segmenter` has to be absent at call time — reset the module and remove the global
+// for the duration of each call.
+describe('grapheme iteration without Intl.Segmenter', () => {
+	afterEach(() => {
+		vi.resetModules()
+	})
+
+	async function withoutSegmenter<T>(fn: (mod: typeof import('./string')) => T): Promise<T> {
+		vi.resetModules()
+		// `Intl.Segmenter` is typed read-only; take a mutable view so we can remove and restore it.
+		const mutableIntl = Intl as { Segmenter?: typeof Intl.Segmenter }
+		const original = mutableIntl.Segmenter
+		delete mutableIntl.Segmenter
+		expect('Segmenter' in Intl).toBe(false)
+		try {
+			return fn(await import('./string'))
+		} finally {
+			mutableIntl.Segmenter = original
+		}
+	}
+
+	it('iterateGraphemes falls back to code-point iteration', async () => {
+		await withoutSegmenter(({ iterateGraphemes }) => {
+			expect([...iterateGraphemes('ab😀')]).toEqual(['a', 'b', '😀'])
+		})
+	})
+
+	it('getFirstCharacter keeps a surrogate pair whole', async () => {
+		await withoutSegmenter(({ getFirstCharacter }) => {
+			expect(getFirstCharacter('😀 hello')).toBe('😀')
+		})
+	})
+
+	it('getFirstCharacter splits a ZWJ cluster to its first code point rather than throwing', async () => {
+		await withoutSegmenter(({ getFirstCharacter }) => {
+			expect(getFirstCharacter('👨‍👩‍👧 family')).toBe('👨')
+		})
+	})
+})

package/src/lib/string.ts

@@ -1,4 +1,38 @@
 let graphemeSegmenter: Intl.Segmenter | undefined
+let checkedForSegmenter = false
+
+/**
+ * Resolve a shared grapheme `Intl.Segmenter`, or `undefined` when the runtime has no
+ * `Intl.Segmenter`. `Intl.Segmenter` is unavailable on some older browsers (notably Firefox before
+ * 125), so feature-detect it once rather than constructing it eagerly, which would throw at module
+ * load and take down the whole app.
+ */
+function getGraphemeSegmenter(): Intl.Segmenter | undefined {
+	if (!checkedForSegmenter) {
+		checkedForSegmenter = true
+		if (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {
+			graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+		}
+	}
+	return graphemeSegmenter
+}
+
+/**
+ * Iterate over the grapheme clusters of a string — user-perceived characters such as emoji
+ * sequences, flags, and accented letters — instead of UTF-16 code units. Uses `Intl.Segmenter`
+ * where available and falls back to iterating by code point on browsers that lack it, where a
+ * multi-code-point cluster is yielded as its component code points rather than as one segment.
+ *
+ * @public
+ */
+export function* iterateGraphemes(str: string): IterableIterator<string> {
+	const segmenter = getGraphemeSegmenter()
+	if (segmenter) {
+		for (const { segment } of segmenter.segment(str)) yield segment
+	} else {
+		yield* str
+	}
+}
 
 /**
  * Get the first character of a string, treating a multi-code-unit character such as an emoji as a
@@ -17,8 +51,7 @@ let graphemeSegmenter: Intl.Segmenter | undefined
  */
 export function getFirstCharacter(str: string): string {
 	if (!str) return ''
-	graphemeSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' })
-	for (const { segment } of graphemeSegmenter.segment(str)) {
+	for (const segment of iterateGraphemes(str)) {
 		return segment
 	}
 	return ''