@tldraw/utils 5.2.0-next.ee0fa4d6244f → 5.2.0

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/reordering.ts"],
-  "sourcesContent": ["import { generateKeyBetween, generateNKeysBetween } from 'jittered-fractional-indexing'\n\nconst generateNKeysBetweenWithNoJitter = (a: string | null, b: string | null, n: number) => {\n\treturn generateNKeysBetween(a, b, n, { jitterBits: 0 })\n}\n\nconst generateKeysFn =\n\tprocess.env.NODE_ENV === 'test' ? generateNKeysBetweenWithNoJitter : generateNKeysBetween\n\n/**\n * A string made up of an integer part followed by a fraction part. The fraction point consists of\n * zero or more digits with no trailing zeros. Based on\n * {@link https://observablehq.com/@dgreensp/implementing-fractional-indexing}.\n *\n * @public\n */\nexport type IndexKey = string & { __brand: 'indexKey' }\n\n/**\n * The index key for the first index - 'a0'.\n * @public\n */\nexport const ZERO_INDEX_KEY = 'a0' as IndexKey\n\n/**\n * Validates that a string is a valid IndexKey.\n * @param index - The string to validate.\n * @throws Error if the index is invalid.\n * @internal\n */\nexport function validateIndexKey(index: string): asserts index is IndexKey {\n\ttry {\n\t\tgenerateKeyBetween(index, null)\n\t} catch {\n\t\tthrow new Error('invalid index: ' + index)\n\t}\n}\n\n/**\n * Get a number of indices between two indices.\n * @param below - The index below.\n * @param above - The index above.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values between below and above.\n * @example\n * ```ts\n * const indices = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)\n * console.log(indices) // ['a0V', 'a1']\n * ```\n * @public\n */\nexport function getIndicesBetween(\n\tbelow: IndexKey | null | undefined,\n\tabove: IndexKey | null | undefined,\n\tn: number\n) {\n\treturn generateKeysFn(below ?? null, above ?? null, n) as IndexKey[]\n}\n\n/**\n * Get a number of indices above an index.\n * @param below - The index below.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values above the given index.\n * @example\n * ```ts\n * const indices = getIndicesAbove('a0' as IndexKey, 3)\n * console.log(indices) // ['a1', 'a2', 'a3']\n * ```\n * @public\n */\nexport function getIndicesAbove(below: IndexKey | null | undefined, n: number) {\n\treturn generateKeysFn(below ?? null, null, n) as IndexKey[]\n}\n\n/**\n * Get a number of indices below an index.\n * @param above - The index above.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values below the given index.\n * @example\n * ```ts\n * const indices = getIndicesBelow('a2' as IndexKey, 2)\n * console.log(indices) // ['a1', 'a0V']\n * ```\n * @public\n */\nexport function getIndicesBelow(above: IndexKey | null | undefined, n: number) {\n\treturn generateKeysFn(null, above ?? null, n) as IndexKey[]\n}\n\n/**\n * Get the index between two indices.\n * @param below - The index below.\n * @param above - The index above.\n * @returns A single IndexKey value between below and above.\n * @example\n * ```ts\n * const index = getIndexBetween('a0' as IndexKey, 'a2' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexBetween(\n\tbelow: IndexKey | null | undefined,\n\tabove: IndexKey | null | undefined\n) {\n\treturn generateKeysFn(below ?? null, above ?? null, 1)[0] as IndexKey\n}\n\n/**\n * Get the index above a given index.\n * @param below - The index below.\n * @returns An IndexKey value above the given index.\n * @example\n * ```ts\n * const index = getIndexAbove('a0' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexAbove(below: IndexKey | null | undefined = null) {\n\treturn generateKeysFn(below, null, 1)[0] as IndexKey\n}\n\n/**\n * Get the index below a given index.\n * @param above - The index above.\n * @returns An IndexKey value below the given index.\n * @example\n * ```ts\n * const index = getIndexBelow('a2' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexBelow(above: IndexKey | null | undefined = null) {\n\treturn generateKeysFn(null, above, 1)[0] as IndexKey\n}\n\n/**\n * Get n number of indices, starting at an index.\n * @param n - The number of indices to get.\n * @param start - The index to start at.\n * @returns An array containing the start index plus n additional IndexKey values.\n * @example\n * ```ts\n * const indices = getIndices(3, 'a1' as IndexKey)\n * console.log(indices) // ['a1', 'a2', 'a3', 'a4']\n * ```\n * @public\n */\nexport function getIndices(n: number, start = 'a1' as IndexKey) {\n\treturn [start, ...generateKeysFn(start, null, n)] as IndexKey[]\n}\n\n/**\n * Sort by index.\n * @param a - An object with an index property.\n * @param b - An object with an index property.\n * @returns A number indicating sort order (-1, 0, or 1).\n * @example\n * ```ts\n * const shapes = [\n *   { id: 'b', index: 'a2' as IndexKey },\n *   { id: 'a', index: 'a1' as IndexKey }\n * ]\n * const sorted = shapes.sort(sortByIndex)\n * console.log(sorted) // [{ id: 'a', index: 'a1' }, { id: 'b', index: 'a2' }]\n * ```\n * @public\n */\nexport function sortByIndex<T extends { index: IndexKey }>(a: T, b: T) {\n\tif (a.index < b.index) {\n\t\treturn -1\n\t} else if (a.index > b.index) {\n\t\treturn 1\n\t}\n\treturn 0\n}\n\n/**\n * Sort by index, or null.\n * @param a - An object with an index property.\n * @param b - An object with an index property.\n * @public\n */\nexport function sortByMaybeIndex<T extends { index?: IndexKey | null }>(a: T, b: T) {\n\tif (a.index && b.index) {\n\t\treturn a.index < b.index ? -1 : 1\n\t}\n\tif (a.index && b.index == null) {\n\t\treturn -1\n\t}\n\tif (a.index == null && b.index == null) {\n\t\treturn 0\n\t}\n\treturn 1\n}\n"],
-  "mappings": "AAAA,SAAS,oBAAoB,4BAA4B;AAEzD,MAAM,mCAAmC,CAAC,GAAkB,GAAkB,MAAc;AAC3F,SAAO,qBAAqB,GAAG,GAAG,GAAG,EAAE,YAAY,EAAE,CAAC;AACvD;AAEA,MAAM,iBACL,QAAQ,IAAI,aAAa,SAAS,mCAAmC;AAe/D,MAAM,iBAAiB;AAQvB,SAAS,iBAAiB,OAA0C;AAC1E,MAAI;AACH,uBAAmB,OAAO,IAAI;AAAA,EAC/B,QAAQ;AACP,UAAM,IAAI,MAAM,oBAAoB,KAAK;AAAA,EAC1C;AACD;AAeO,SAAS,kBACf,OACA,OACA,GACC;AACD,SAAO,eAAe,SAAS,MAAM,SAAS,MAAM,CAAC;AACtD;AAcO,SAAS,gBAAgB,OAAoC,GAAW;AAC9E,SAAO,eAAe,SAAS,MAAM,MAAM,CAAC;AAC7C;AAcO,SAAS,gBAAgB,OAAoC,GAAW;AAC9E,SAAO,eAAe,MAAM,SAAS,MAAM,CAAC;AAC7C;AAcO,SAAS,gBACf,OACA,OACC;AACD,SAAO,eAAe,SAAS,MAAM,SAAS,MAAM,CAAC,EAAE,CAAC;AACzD;AAaO,SAAS,cAAc,QAAqC,MAAM;AACxE,SAAO,eAAe,OAAO,MAAM,CAAC,EAAE,CAAC;AACxC;AAaO,SAAS,cAAc,QAAqC,MAAM;AACxE,SAAO,eAAe,MAAM,OAAO,CAAC,EAAE,CAAC;AACxC;AAcO,SAAS,WAAW,GAAW,QAAQ,MAAkB;AAC/D,SAAO,CAAC,OAAO,GAAG,eAAe,OAAO,MAAM,CAAC,CAAC;AACjD;AAkBO,SAAS,YAA2C,GAAM,GAAM;AACtE,MAAI,EAAE,QAAQ,EAAE,OAAO;AACtB,WAAO;AAAA,EACR,WAAW,EAAE,QAAQ,EAAE,OAAO;AAC7B,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,iBAAwD,GAAM,GAAM;AACnF,MAAI,EAAE,SAAS,EAAE,OAAO;AACvB,WAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK;AAAA,EACjC;AACA,MAAI,EAAE,SAAS,EAAE,SAAS,MAAM;AAC/B,WAAO;AAAA,EACR;AACA,MAAI,EAAE,SAAS,QAAQ,EAAE,SAAS,MAAM;AACvC,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
+  "sourcesContent": ["import {\n\tgenerateNJitteredKeysBetween,\n\tgenerateNKeysBetween,\n\tvalidateOrderKey,\n} from './fractionalIndexing'\n\nconst generateKeysFn =\n\tprocess.env.NODE_ENV === 'test' ? generateNKeysBetween : generateNJitteredKeysBetween\n\n/**\n * A string made up of an integer part followed by a fraction part. The fraction point consists of\n * zero or more digits with no trailing zeros. Based on\n * {@link https://observablehq.com/@dgreensp/implementing-fractional-indexing}.\n *\n * @public\n */\nexport type IndexKey = string & { __brand: 'indexKey' }\n\n/**\n * The index key for the first index - 'a0'.\n * @public\n */\nexport const ZERO_INDEX_KEY = 'a0' as IndexKey\n\n/**\n * Validates that a string is a valid IndexKey.\n * @param index - The string to validate.\n * @throws Error if the index is invalid.\n * @internal\n */\nexport function validateIndexKey(index: string): asserts index is IndexKey {\n\ttry {\n\t\tvalidateOrderKey(index)\n\t} catch {\n\t\tthrow new Error('invalid index: ' + index)\n\t}\n}\n\n/**\n * Get a number of indices between two indices.\n * @param below - The index below.\n * @param above - The index above.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values between below and above.\n * @example\n * ```ts\n * const indices = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)\n * console.log(indices) // ['a0V', 'a1']\n * ```\n * @public\n */\nexport function getIndicesBetween(\n\tbelow: IndexKey | null | undefined,\n\tabove: IndexKey | null | undefined,\n\tn: number\n) {\n\treturn generateKeysFn(below ?? null, above ?? null, n) as IndexKey[]\n}\n\n/**\n * Get a number of indices above an index.\n * @param below - The index below.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values above the given index.\n * @example\n * ```ts\n * const indices = getIndicesAbove('a0' as IndexKey, 3)\n * console.log(indices) // ['a1', 'a2', 'a3']\n * ```\n * @public\n */\nexport function getIndicesAbove(below: IndexKey | null | undefined, n: number) {\n\treturn generateKeysFn(below ?? null, null, n) as IndexKey[]\n}\n\n/**\n * Get a number of indices below an index.\n * @param above - The index above.\n * @param n - The number of indices to get.\n * @returns An array of n IndexKey values below the given index.\n * @example\n * ```ts\n * const indices = getIndicesBelow('a2' as IndexKey, 2)\n * console.log(indices) // ['a1', 'a0V']\n * ```\n * @public\n */\nexport function getIndicesBelow(above: IndexKey | null | undefined, n: number) {\n\treturn generateKeysFn(null, above ?? null, n) as IndexKey[]\n}\n\n/**\n * Get the index between two indices.\n * @param below - The index below.\n * @param above - The index above.\n * @returns A single IndexKey value between below and above.\n * @example\n * ```ts\n * const index = getIndexBetween('a0' as IndexKey, 'a2' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexBetween(\n\tbelow: IndexKey | null | undefined,\n\tabove: IndexKey | null | undefined\n) {\n\treturn generateKeysFn(below ?? null, above ?? null, 1)[0] as IndexKey\n}\n\n/**\n * Get the index above a given index.\n * @param below - The index below.\n * @returns An IndexKey value above the given index.\n * @example\n * ```ts\n * const index = getIndexAbove('a0' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexAbove(below: IndexKey | null | undefined = null) {\n\treturn generateKeysFn(below, null, 1)[0] as IndexKey\n}\n\n/**\n * Get the index below a given index.\n * @param above - The index above.\n * @returns An IndexKey value below the given index.\n * @example\n * ```ts\n * const index = getIndexBelow('a2' as IndexKey)\n * console.log(index) // 'a1'\n * ```\n * @public\n */\nexport function getIndexBelow(above: IndexKey | null | undefined = null) {\n\treturn generateKeysFn(null, above, 1)[0] as IndexKey\n}\n\n/**\n * Get n number of indices, starting at an index.\n * @param n - The number of indices to get.\n * @param start - The index to start at.\n * @returns An array containing the start index plus n additional IndexKey values.\n * @example\n * ```ts\n * const indices = getIndices(3, 'a1' as IndexKey)\n * console.log(indices) // ['a1', 'a2', 'a3', 'a4']\n * ```\n * @public\n */\nexport function getIndices(n: number, start = 'a1' as IndexKey) {\n\treturn [start, ...generateKeysFn(start, null, n)] as IndexKey[]\n}\n\n/**\n * Sort by index.\n * @param a - An object with an index property.\n * @param b - An object with an index property.\n * @returns A number indicating sort order (-1, 0, or 1).\n * @example\n * ```ts\n * const shapes = [\n *   { id: 'b', index: 'a2' as IndexKey },\n *   { id: 'a', index: 'a1' as IndexKey }\n * ]\n * const sorted = shapes.sort(sortByIndex)\n * console.log(sorted) // [{ id: 'a', index: 'a1' }, { id: 'b', index: 'a2' }]\n * ```\n * @public\n */\nexport function sortByIndex<T extends { index: IndexKey }>(a: T, b: T) {\n\tif (a.index < b.index) {\n\t\treturn -1\n\t} else if (a.index > b.index) {\n\t\treturn 1\n\t}\n\treturn 0\n}\n\n/**\n * Sort by index, or null.\n * @param a - An object with an index property.\n * @param b - An object with an index property.\n * @public\n */\nexport function sortByMaybeIndex<T extends { index?: IndexKey | null }>(a: T, b: T) {\n\tif (a.index && b.index) {\n\t\treturn a.index < b.index ? -1 : 1\n\t}\n\tif (a.index && b.index == null) {\n\t\treturn -1\n\t}\n\tif (a.index == null && b.index == null) {\n\t\treturn 0\n\t}\n\treturn 1\n}\n"],
+  "mappings": "AAAA;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,OACM;AAEP,MAAM,iBACL,QAAQ,IAAI,aAAa,SAAS,uBAAuB;AAenD,MAAM,iBAAiB;AAQvB,SAAS,iBAAiB,OAA0C;AAC1E,MAAI;AACH,qBAAiB,KAAK;AAAA,EACvB,QAAQ;AACP,UAAM,IAAI,MAAM,oBAAoB,KAAK;AAAA,EAC1C;AACD;AAeO,SAAS,kBACf,OACA,OACA,GACC;AACD,SAAO,eAAe,SAAS,MAAM,SAAS,MAAM,CAAC;AACtD;AAcO,SAAS,gBAAgB,OAAoC,GAAW;AAC9E,SAAO,eAAe,SAAS,MAAM,MAAM,CAAC;AAC7C;AAcO,SAAS,gBAAgB,OAAoC,GAAW;AAC9E,SAAO,eAAe,MAAM,SAAS,MAAM,CAAC;AAC7C;AAcO,SAAS,gBACf,OACA,OACC;AACD,SAAO,eAAe,SAAS,MAAM,SAAS,MAAM,CAAC,EAAE,CAAC;AACzD;AAaO,SAAS,cAAc,QAAqC,MAAM;AACxE,SAAO,eAAe,OAAO,MAAM,CAAC,EAAE,CAAC;AACxC;AAaO,SAAS,cAAc,QAAqC,MAAM;AACxE,SAAO,eAAe,MAAM,OAAO,CAAC,EAAE,CAAC;AACxC;AAcO,SAAS,WAAW,GAAW,QAAQ,MAAkB;AAC/D,SAAO,CAAC,OAAO,GAAG,eAAe,OAAO,MAAM,CAAC,CAAC;AACjD;AAkBO,SAAS,YAA2C,GAAM,GAAM;AACtE,MAAI,EAAE,QAAQ,EAAE,OAAO;AACtB,WAAO;AAAA,EACR,WAAW,EAAE,QAAQ,EAAE,OAAO;AAC7B,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,iBAAwD,GAAM,GAAM;AACnF,MAAI,EAAE,SAAS,EAAE,OAAO;AACvB,WAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK;AAAA,EACjC;AACA,MAAI,EAAE,SAAS,EAAE,SAAS,MAAM;AAC/B,WAAO;AAAA,EACR;AACA,MAAI,EAAE,SAAS,QAAQ,EAAE,SAAS,MAAM;AACvC,WAAO;AAAA,EACR;AACA,SAAO;AACR;",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/utils",
   "description": "tldraw infinite canvas SDK (private utilities).",
-  "version": "5.2.0-next.ee0fa4d6244f",
+  "version": "5.2.0",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -29,7 +29,8 @@
   "files": [
     "dist-esm",
     "dist-cjs",
-    "src"
+    "src",
+    "DOCS.md"
   ],
   "scripts": {
     "test-ci": "yarn run -T vitest run --passWithNoTests",
@@ -43,7 +44,6 @@
     "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
   },
   "dependencies": {
-    "jittered-fractional-indexing": "^1.0.0",
     "lodash.isequal": "^4.5.0",
     "lodash.isequalwith": "^4.4.0",
     "lodash.throttle": "^4.1.1",
@@ -55,7 +55,10 @@
     "@types/lodash.throttle": "^4.1.9",
     "@types/lodash.uniq": "^4.5.9",
     "lazyrepo": "0.0.0-alpha.27",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22.12.0"
   },
   "module": "dist-esm/index.mjs",
   "source": "src/index.ts",

package/src/lib/PerformanceTracker.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, type MockInstance, vi } from 'vitest'
 import { PERFORMANCE_COLORS, PERFORMANCE_PREFIX_COLOR } from './perf'
 import { PerformanceTracker } from './PerformanceTracker'
 
@@ -7,7 +7,7 @@ describe('PerformanceTracker', () => {
 	let mockPerformanceNow: ReturnType<typeof vi.fn>
 	let mockRequestAnimationFrame: ReturnType<typeof vi.fn>
 	let mockCancelAnimationFrame: ReturnType<typeof vi.fn>
-	let mockConsoleDebug: ReturnType<typeof vi.fn>
+	let mockConsoleDebug: MockInstance<typeof console.debug>
 	let frameId = 1
 
 	beforeEach(() => {
@@ -24,8 +24,7 @@ describe('PerformanceTracker', () => {
 		vi.stubGlobal('cancelAnimationFrame', mockCancelAnimationFrame)
 
 		// Mock console.debug
-		mockConsoleDebug = vi.fn()
-		vi.spyOn(console, 'debug').mockImplementation(mockConsoleDebug)
+		mockConsoleDebug = vi.spyOn(console, 'debug').mockImplementation(() => {})
 	})
 
 	afterEach(() => {

package/src/lib/fractionalIndexing.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest'
+import {
+	generateNJitteredKeysBetween,
+	generateNKeysBetween,
+	validateOrderKey,
+} from './fractionalIndexing'
+
+// Single-key helper: the non-jittered generator with n=1.
+const keyBetween = (a: string | null, b: string | null) => generateNKeysBetween(a, b, 1)[0]
+
+describe('fractionalIndexing', () => {
+	// Golden vectors from the upstream `fractional-indexing` README. These pin the
+	// exact base-62 output, proving the vendored/specialized core stays
+	// byte-for-byte compatible with the original library.
+	describe('generateKeyBetween (golden vectors)', () => {
+		it.each([
+			[null, null, 'a0'],
+			['a0', null, 'a1'],
+			['a1', null, 'a2'],
+			[null, 'a0', 'Zz'],
+			['a0', 'a1', 'a0V'],
+			['a1', 'a2', 'a1V'],
+		])('between %o and %o is %o', (a, b, expected) => {
+			expect(keyBetween(a, b)).toBe(expected)
+		})
+	})
+
+	describe('generateNKeysBetween (golden vectors)', () => {
+		it.each<[string | null, string | null, number, string[]]>([
+			[null, null, 2, ['a0', 'a1']],
+			['a1', null, 2, ['a2', 'a3']],
+			[null, 'a0', 2, ['Zy', 'Zz']],
+			['a0', 'a1', 2, ['a0G', 'a0V']],
+			[null, null, 5, ['a0', 'a1', 'a2', 'a3', 'a4']],
+		])('%o keys between %o and %o', (a, b, n, expected) => {
+			expect(generateNKeysBetween(a, b, n)).toEqual(expected)
+		})
+
+		it('returns an empty array for n = 0', () => {
+			expect(generateNKeysBetween(null, null, 0)).toEqual([])
+		})
+	})
+
+	describe('errors', () => {
+		it('throws when a >= b', () => {
+			expect(() => keyBetween('a1', 'a0')).toThrow()
+			expect(() => keyBetween('a0', 'a0')).toThrow()
+		})
+
+		it('throws on invalid input keys', () => {
+			expect(() => keyBetween('a00', null)).toThrow() // trailing zero
+			expect(() => keyBetween('', null)).toThrow()
+			expect(() => keyBetween('foo', null)).toThrow()
+		})
+	})
+
+	describe('validateOrderKey', () => {
+		it.each(['a0', 'a1', 'a0V', 'Zz', 'a0G', 'b127'])('accepts %s', (key) => {
+			expect(() => validateOrderKey(key)).not.toThrow()
+		})
+
+		it.each([
+			'', // empty
+			'a', // integer part too short
+			'1', // invalid head
+			'a00', // trailing zero in fraction
+			'foo', // invalid head
+			'A' + '0'.repeat(26), // the reserved smallest-integer key
+		])('rejects %o', (key) => {
+			expect(() => validateOrderKey(key)).toThrow()
+		})
+	})
+
+	// Invariant tests: independent of exact output, these catch ordering or
+	// digit-mapping regressions across the whole alphabet (e.g. a bad charCode
+	// offset in digitIndex, or carry/borrow bugs when integers roll over).
+	describe('invariants', () => {
+		it('generateNKeysBetween yields strictly increasing, valid, in-bounds keys', () => {
+			const keys = generateNKeysBetween('a0', 'a1', 200)
+			expect(keys).toHaveLength(200)
+			let prev = 'a0'
+			for (const key of keys) {
+				expect(() => validateOrderKey(key)).not.toThrow()
+				expect(key > prev).toBe(true)
+				expect(key < 'a1').toBe(true)
+				prev = key
+			}
+		})
+
+		it('stays ordered while repeatedly inserting after the last key (integer carries)', () => {
+			// 200 sequential keys force the integer part to roll over many digits,
+			// exercising incrementInteger across the full base-62 alphabet.
+			let key = keyBetween(null, null)
+			let prev = ''
+			for (let i = 0; i < 200; i++) {
+				expect(() => validateOrderKey(key)).not.toThrow()
+				expect(key > prev).toBe(true)
+				prev = key
+				key = keyBetween(key, null)
+			}
+		})
+
+		it('stays ordered while repeatedly inserting before the first key (integer borrows)', () => {
+			let key = keyBetween(null, null)
+			let next = 'zzzzz'
+			for (let i = 0; i < 200; i++) {
+				expect(() => validateOrderKey(key)).not.toThrow()
+				expect(key < next).toBe(true)
+				next = key
+				key = keyBetween(null, key)
+			}
+		})
+
+		it('generateNJitteredKeysBetween yields ordered, valid, in-bounds, distinct keys', () => {
+			const keys = generateNJitteredKeysBetween('a0', 'a5', 100)
+			expect(keys).toHaveLength(100)
+			expect(new Set(keys).size).toBe(100)
+			let prev = 'a0'
+			for (const key of keys) {
+				expect(() => validateOrderKey(key)).not.toThrow()
+				expect(key > prev).toBe(true)
+				expect(key < 'a5').toBe(true)
+				prev = key
+			}
+		})
+
+		it('jittered keys land strictly between their neighbours', () => {
+			const a = keyBetween(null, null)
+			const b = keyBetween(a, null)
+			for (let i = 0; i < 50; i++) {
+				const mid = generateNJitteredKeysBetween(a, b, 1)[0]
+				expect(mid > a).toBe(true)
+				expect(mid < b).toBe(true)
+				expect(() => validateOrderKey(mid)).not.toThrow()
+			}
+		})
+	})
+})

package/src/lib/fractionalIndexing.ts

@@ -0,0 +1,275 @@
+// Fractional indexing, specialized to tldraw's needs.
+//
+// This is a vendored and trimmed version of the `fractional-indexing` (by
+// arv@rocicorp.dev) and `jittered-fractional-indexing` (by
+// github@nathanhleung.com) packages, both released under CC0-1.0 (public
+// domain). See https://observablehq.com/@dgreensp/implementing-fractional-indexing
+// for the original algorithm.
+//
+// We only ever use the default base-62 alphabet, so the `digits` parameter has
+// been specialized away. This lets us hoist the per-call allocations that the
+// upstream `validateOrderKey` made (notably `digits[0].repeat(26)`) into module
+// constants, and skip redundant re-validation inside the jitter loop, which are
+// both on hot paths (every index generation and every IndexKey validation).
+
+// Digits must be in ascending character-code order.
+const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const ZERO = DIGITS[0] // '0'
+const LARGEST_DIGIT = DIGITS[DIGITS.length - 1] // 'z'
+// The reserved "smallest integer" key, which has no valid predecessor.
+const SMALLEST_INTEGER = 'A' + ZERO.repeat(26)
+// Number of random bisections used to spread concurrently-generated keys apart,
+// reducing the chance of collisions when multiple clients insert into the same
+// gap at once. Each bit costs one extra key generation and ~0.17 characters of
+// key length, so this trades collision resistance against compute and key size.
+// 16 keeps collisions below ~0.1% even for ~10 simultaneous same-position
+// inserts, which is ample headroom for real multiplayer use.
+const JITTER_BITS = 16
+
+function getIntegerLength(head: string): number {
+	if (head >= 'a' && head <= 'z') {
+		return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2
+	} else if (head >= 'A' && head <= 'Z') {
+		return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2
+	}
+	throw new Error('invalid order key head: ' + head)
+}
+
+function getIntegerPart(key: string): string {
+	const integerPartLength = getIntegerLength(key[0])
+	if (integerPartLength > key.length) {
+		throw new Error('invalid order key: ' + key)
+	}
+	return key.slice(0, integerPartLength)
+}
+
+// Map a base-62 digit to its value. Faster than DIGITS.indexOf() (which scans
+// the alphabet) on the hot key-generation path. DIGITS is in char-code order:
+// '0'-'9' -> 0-9, 'A'-'Z' -> 10-35, 'a'-'z' -> 36-61.
+function digitIndex(char: string): number {
+	const code = char.charCodeAt(0)
+	if (code <= 57) return code - 48
+	if (code <= 90) return code - 55
+	return code - 61
+}
+
+/**
+ * Throws if `key` is not a canonical order key. Allocation-free in the common
+ * case: no `repeat`/`slice` per call.
+ */
+export function validateOrderKey(key: string): void {
+	if (key === SMALLEST_INTEGER) {
+		throw new Error('invalid order key: ' + key)
+	}
+	// getIntegerPart throws if the first character is bad or the key is too short.
+	const i = getIntegerPart(key)
+	// The fractional part (everything after the integer part) must not end in the
+	// smallest digit, as a trailing zero is a non-canonical representation.
+	if (key.length > i.length && key[key.length - 1] === ZERO) {
+		throw new Error('invalid order key: ' + key)
+	}
+}
+
+// `a` may be empty string, `b` is null or non-empty string.
+// `a < b` lexicographically if `b` is non-null. No trailing zeros allowed.
+function midpoint(a: string, b: string | null): string {
+	if (b != null && a >= b) {
+		throw new Error(a + ' >= ' + b)
+	}
+	if (a.slice(-1) === ZERO || (b && b.slice(-1) === ZERO)) {
+		throw new Error('trailing zero')
+	}
+	if (b) {
+		// Remove the longest common prefix, padding `a` with zeros as we go. We
+		// don't need to pad `b`, because it can't end before `a` while traversing
+		// the common prefix.
+		let n = 0
+		while ((a[n] || ZERO) === b[n]) {
+			n++
+		}
+		if (n > 0) {
+			return b.slice(0, n) + midpoint(a.slice(n), b.slice(n))
+		}
+	}
+	// First digits (or lack of digit) are different.
+	const digitA = a ? digitIndex(a[0]) : 0
+	const digitB = b != null ? digitIndex(b[0]) : DIGITS.length
+	if (digitB - digitA > 1) {
+		const midDigit = Math.round(0.5 * (digitA + digitB))
+		return DIGITS[midDigit]
+	}
+	// First digits are consecutive.
+	if (b && b.length > 1) {
+		return b.slice(0, 1)
+	}
+	// `b` is null or has length 1 (a single digit). The first digit of `a` is the
+	// previous digit to `b`, or the largest digit if `b` is null.
+	return DIGITS[digitA] + midpoint(a.slice(1), null)
+}
+
+// May return null, as there is a largest integer.
+function incrementInteger(x: string): string | null {
+	const [head, ...digs] = x.split('')
+	let carry = true
+	for (let i = digs.length - 1; carry && i >= 0; i--) {
+		const d = digitIndex(digs[i]) + 1
+		if (d === DIGITS.length) {
+			digs[i] = ZERO
+		} else {
+			digs[i] = DIGITS[d]
+			carry = false
+		}
+	}
+	if (carry) {
+		if (head === 'Z') return 'a' + ZERO
+		if (head === 'z') return null
+		const h = String.fromCharCode(head.charCodeAt(0) + 1)
+		if (h > 'a') {
+			digs.push(ZERO)
+		} else {
+			digs.pop()
+		}
+		return h + digs.join('')
+	}
+	return head + digs.join('')
+}
+
+// May return null, as there is a smallest integer.
+function decrementInteger(x: string): string | null {
+	const [head, ...digs] = x.split('')
+	let borrow = true
+	for (let i = digs.length - 1; borrow && i >= 0; i--) {
+		const d = digitIndex(digs[i]) - 1
+		if (d === -1) {
+			digs[i] = LARGEST_DIGIT
+		} else {
+			digs[i] = DIGITS[d]
+			borrow = false
+		}
+	}
+	if (borrow) {
+		if (head === 'a') return 'Z' + LARGEST_DIGIT
+		if (head === 'A') return null
+		const h = String.fromCharCode(head.charCodeAt(0) - 1)
+		if (h < 'Z') {
+			digs.push(LARGEST_DIGIT)
+		} else {
+			digs.pop()
+		}
+		return h + digs.join('')
+	}
+	return head + digs.join('')
+}
+
+// Generate a key strictly between `a` and `b`, without validating the inputs.
+// `a`/`b` are order keys or null (START/END). `a < b` if both are non-null.
+function keyBetweenUnchecked(a: string | null, b: string | null): string {
+	if (a != null && b != null && a >= b) {
+		throw new Error(a + ' >= ' + b)
+	}
+	if (a == null) {
+		if (b == null) return 'a' + ZERO
+		const ib = getIntegerPart(b)
+		const fb = b.slice(ib.length)
+		if (ib === SMALLEST_INTEGER) {
+			return ib + midpoint('', fb)
+		}
+		if (ib < b) return ib
+		const res = decrementInteger(ib)
+		if (res == null) throw new Error('cannot decrement any more')
+		return res
+	}
+	if (b == null) {
+		const ia = getIntegerPart(a)
+		const fa = a.slice(ia.length)
+		const i = incrementInteger(ia)
+		return i == null ? ia + midpoint(fa, null) : i
+	}
+	const ia = getIntegerPart(a)
+	const fa = a.slice(ia.length)
+	const ib = getIntegerPart(b)
+	const fb = b.slice(ib.length)
+	if (ia === ib) {
+		return ia + midpoint(fa, fb)
+	}
+	const i = incrementInteger(ia)
+	if (i == null) throw new Error('cannot increment any more')
+	if (i < b) return i
+	return ia + midpoint(fa, null)
+}
+
+// Generate `n` keys between `a` and `b`, without validating the inputs.
+// Intermediate keys are valid by construction, so they're never re-validated.
+function nKeysBetweenUnchecked(a: string | null, b: string | null, n: number): string[] {
+	if (n === 0) return []
+	if (n === 1) return [keyBetweenUnchecked(a, b)]
+	if (b == null) {
+		let c = keyBetweenUnchecked(a, b)
+		const result = [c]
+		for (let i = 0; i < n - 1; i++) {
+			c = keyBetweenUnchecked(c, b)
+			result.push(c)
+		}
+		return result
+	}
+	if (a == null) {
+		let c = keyBetweenUnchecked(a, b)
+		const result = [c]
+		for (let i = 0; i < n - 1; i++) {
+			c = keyBetweenUnchecked(a, c)
+			result.push(c)
+		}
+		result.reverse()
+		return result
+	}
+	const mid = Math.floor(n / 2)
+	const c = keyBetweenUnchecked(a, b)
+	return [...nKeysBetweenUnchecked(a, c, mid), c, ...nKeysBetweenUnchecked(c, b, n - mid - 1)]
+}
+
+// Bisect `[low, high]` JITTER_BITS times, following a random walk, so that keys
+// generated concurrently land in different sub-ranges. `low`/`high` must already
+// be valid (or null); the intermediate midpoints are valid by construction.
+function jitterBetween(low: string | null, high: string | null): string {
+	let mid = keyBetweenUnchecked(low, high)
+	for (let i = 0; i < JITTER_BITS; i++) {
+		if (Math.random() < 0.5) {
+			low = mid
+		} else {
+			high = mid
+		}
+		mid = keyBetweenUnchecked(low, high)
+	}
+	return mid
+}
+
+/**
+ * Generate `n` jittered keys evenly spaced between `a` and `b`. Inputs are
+ * validated once; everything downstream is generated, hence trusted.
+ */
+export function generateNJitteredKeysBetween(
+	a: string | null,
+	b: string | null,
+	n: number
+): string[] {
+	if (n === 0) return []
+	if (a != null) validateOrderKey(a)
+	if (b != null) validateOrderKey(b)
+	const keys = nKeysBetweenUnchecked(a, b, n + 1)
+	const result = new Array<string>(n)
+	for (let i = 0; i < n; i++) {
+		result[i] = jitterBetween(keys[i], keys[i + 1])
+	}
+	return result
+}
+
+/**
+ * Generate `n` keys evenly spaced between `a` and `b`, without jitter. Used in
+ * tests for deterministic output.
+ */
+export function generateNKeysBetween(a: string | null, b: string | null, n: number): string[] {
+	if (n === 0) return []
+	if (a != null) validateOrderKey(a)
+	if (b != null) validateOrderKey(b)
+	return nKeysBetweenUnchecked(a, b, n)
+}

package/src/lib/reordering.ts

@@ -1,11 +1,11 @@
-import { generateKeyBetween, generateNKeysBetween } from 'jittered-fractional-indexing'
-
-const generateNKeysBetweenWithNoJitter = (a: string | null, b: string | null, n: number) => {
-	return generateNKeysBetween(a, b, n, { jitterBits: 0 })
-}
+import {
+	generateNJitteredKeysBetween,
+	generateNKeysBetween,
+	validateOrderKey,
+} from './fractionalIndexing'
 
 const generateKeysFn =
-	process.env.NODE_ENV === 'test' ? generateNKeysBetweenWithNoJitter : generateNKeysBetween
+	process.env.NODE_ENV === 'test' ? generateNKeysBetween : generateNJitteredKeysBetween
 
 /**
  * A string made up of an integer part followed by a fraction part. The fraction point consists of
@@ -30,7 +30,7 @@ export const ZERO_INDEX_KEY = 'a0' as IndexKey
  */
 export function validateIndexKey(index: string): asserts index is IndexKey {
 	try {
-		generateKeyBetween(index, null)
+		validateOrderKey(index)
 	} catch {
 		throw new Error('invalid index: ' + index)
 	}

package/src/lib/version.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { clearRegisteredVersionsForTests, registerTldrawLibraryVersion } from './version'
 
 describe('version utilities', () => {
-	let mockConsoleLog: ReturnType<typeof vi.fn>
+	let mockConsoleLog: ReturnType<typeof vi.fn<(...args: any[]) => any>>
 
 	beforeEach(() => {
 		mockConsoleLog = vi.fn()