@tldraw/tlschema 5.2.0-next.ee0fa4d6244f → 5.2.0

package/src/migrations.test.ts

@@ -18,7 +18,7 @@ import { TLShape, rootShapeVersions } from './records/TLShape'
 import { userVersions } from './records/TLUser'
 import { arrowShapeVersions } from './shapes/TLArrowShape'
 import { bookmarkShapeVersions } from './shapes/TLBookmarkShape'
-import { drawShapeVersions } from './shapes/TLDrawShape'
+import { DrawShapeSegment, drawShapeVersions } from './shapes/TLDrawShape'
 import { embedShapeVersions } from './shapes/TLEmbedShape'
 import { frameShapeVersions } from './shapes/TLFrameShape'
 import { geoShapeVersions } from './shapes/TLGeoShape'
@@ -2638,6 +2638,28 @@ describe('Adding textFirstEditedBy to note shape', () => {
 	})
 })
 
+describe('Renaming textFirstEditedBy to textLastEditedBy on note shape', () => {
+	const { up, down } = getTestMigration(noteShapeVersions.RenameFirstEditedByToLast)
+
+	test('up renames the prop, preserving its value', () => {
+		expect(up({ props: { textFirstEditedBy: 'user:1' } })).toEqual({
+			props: { textLastEditedBy: 'user:1' },
+		})
+		expect(up({ props: { textFirstEditedBy: null } })).toEqual({
+			props: { textLastEditedBy: null },
+		})
+	})
+
+	test('down renames the prop back, preserving its value', () => {
+		expect(down({ props: { textLastEditedBy: 'user:1' } })).toEqual({
+			props: { textFirstEditedBy: 'user:1' },
+		})
+		expect(down({ props: { textLastEditedBy: null } })).toEqual({
+			props: { textFirstEditedBy: null },
+		})
+	})
+})
+
 describe('TLUser initial migration', () => {
 	const { up } = getTestMigration(userVersions.Initial)
 
@@ -2647,6 +2669,119 @@ describe('TLUser initial migration', () => {
 	})
 })
 
+describe('OmitNonPressureZ migration for draw shape', () => {
+	const { up, down } = getTestMigration(drawShapeVersions.OmitNonPressureZ)
+
+	test('up is a no-op for 3D segments (absent dim reads as 3D)', () => {
+		const path = b64Vecs.encodePoints([
+			{ x: 0, y: 0, z: 0.5 },
+			{ x: 10, y: 10, z: 0.5 },
+		])
+		const result = up({ props: { segments: [{ type: 'free', path }] } })
+		expect(result.props.segments[0]).toEqual({ type: 'free', path })
+	})
+
+	test('up leaves a 2D segment untouched', () => {
+		const path = b64Vecs.encodePoints2D([
+			{ x: 0, y: 0, z: 0.5 },
+			{ x: 10, y: 10, z: 0.5 },
+		])
+		const result = up({ props: { segments: [{ type: 'free', path, dim: 2 }] } })
+		expect(result.props.segments[0]).toEqual({ type: 'free', path, dim: 2 })
+	})
+
+	test('down re-encodes a 2D segment to 3D and strips dim', () => {
+		const points = [
+			{ x: 5, y: 6, z: 0.5 },
+			{ x: 12, y: 9, z: 0.5 },
+			{ x: 20, y: 4, z: 0.5 },
+		]
+		const result = down({
+			props: { segments: [{ type: 'free', path: b64Vecs.encodePoints2D(points), dim: 2 }] },
+		})
+
+		expect(result.props.segments[0].dim).toBeUndefined()
+		const decoded = b64Vecs.decodePoints(result.props.segments[0].path)
+		expect(decoded.length).toBe(3)
+		expect(decoded[2].x).toBeCloseTo(20, 0)
+		expect(decoded[0].z).toBe(0.5)
+	})
+
+	test('down leaves a 3D segment (no dim) unchanged', () => {
+		const path = b64Vecs.encodePoints([
+			{ x: 0, y: 0, z: 0.5 },
+			{ x: 10, y: 10, z: 0.6 },
+		])
+		const result = down({ props: { segments: [{ type: 'free', path }] } })
+		expect(result.props.segments[0]).toEqual({ type: 'free', path })
+	})
+
+	test('down strips an explicit dim: 3 without re-encoding the (already 3D) path', () => {
+		const path = b64Vecs.encodePoints([
+			{ x: 1, y: 2, z: 0.6 },
+			{ x: 3, y: 4, z: 0.7 },
+		])
+		const result = down({ props: { segments: [{ type: 'free', path, dim: 3 }] } })
+		expect(result.props.segments[0].dim).toBeUndefined()
+		expect(result.props.segments[0].path).toBe(path) // already 3D — field dropped, bytes untouched
+	})
+
+	test('down handles mixed 2D and 3D segments', () => {
+		const path3D = b64Vecs.encodePoints([
+			{ x: 1, y: 2, z: 0.6 },
+			{ x: 3, y: 4, z: 0.7 },
+		])
+		const path2D = b64Vecs.encodePoints2D([
+			{ x: 5, y: 6, z: 0.5 },
+			{ x: 7, y: 8, z: 0.5 },
+		])
+		const result = down({
+			props: {
+				segments: [
+					{ type: 'free', path: path3D },
+					{ type: 'straight', path: path2D, dim: 2 },
+				],
+			},
+		})
+		expect(result.props.segments[0]).toEqual({ type: 'free', path: path3D })
+		expect(result.props.segments[1].dim).toBeUndefined()
+		expect(b64Vecs.decodePoints(result.props.segments[1].path).length).toBe(2)
+	})
+})
+
+describe('OmitNonPressureZ migration for highlight shape', () => {
+	const { up, down } = getTestMigration(highlightShapeVersions.OmitNonPressureZ)
+
+	test('up is a no-op', () => {
+		const path = b64Vecs.encodePoints2D([
+			{ x: 0, y: 0, z: 0.5 },
+			{ x: 10, y: 10, z: 0.5 },
+		])
+		const result = up({ props: { segments: [{ type: 'free', path, dim: 2 }] } })
+		expect(result.props.segments[0]).toEqual({ type: 'free', path, dim: 2 })
+	})
+
+	test('down re-encodes a 2D segment to 3D and strips dim', () => {
+		const path2D = b64Vecs.encodePoints2D([
+			{ x: 5, y: 6, z: 0.5 },
+			{ x: 12, y: 9, z: 0.5 },
+		])
+		const result = down({ props: { segments: [{ type: 'free', path: path2D, dim: 2 }] } })
+		expect(result.props.segments[0].dim).toBeUndefined()
+		expect(b64Vecs.decodePoints(result.props.segments[0].path).length).toBe(2)
+	})
+})
+
+describe('DrawShapeSegment dim validation', () => {
+	test('accepts dim 2, 3, or absent; rejects other values', () => {
+		expect(() => DrawShapeSegment.validate({ type: 'free', path: 'AAAA', dim: 2 })).not.toThrow()
+		expect(() => DrawShapeSegment.validate({ type: 'free', path: 'AAAA', dim: 3 })).not.toThrow()
+		expect(() => DrawShapeSegment.validate({ type: 'free', path: 'AAAA' })).not.toThrow()
+		expect(() => DrawShapeSegment.validate({ type: 'free', path: 'AAAA', dim: 0 })).toThrow()
+		expect(() => DrawShapeSegment.validate({ type: 'free', path: 'AAAA', dim: 4 })).toThrow()
+	})
+})
+
 /* ---  PUT YOUR MIGRATIONS TESTS ABOVE HERE --- */
 
 // check that all migrator fns were called at least once

package/src/misc/b64Vecs.test.ts

@@ -478,3 +478,115 @@ describe('b64Vecs legacy encoding', () => {
 		expect(uniqueXValues.size).toBeLessThanOrEqual(2) // Should collapse to 1-2 values, not 4
 	})
 })
+
+describe('2D encoding (skip-pressure)', () => {
+	it('round-trips x and y, supplies z = 0.5', () => {
+		const points: VecModel[] = [
+			{ x: 1000, y: 2000, z: 0.5 },
+			{ x: 1013, y: 2008, z: 0.5 },
+			{ x: 1027, y: 2011, z: 0.5 },
+		]
+		const decoded = b64Vecs.decodePoints2D(b64Vecs.encodePoints2D(points))
+		expect(decoded.length).toBe(3)
+		for (let i = 0; i < points.length; i++) {
+			expect(decoded[i].x).toBeCloseTo(points[i].x, 1)
+			expect(decoded[i].y).toBeCloseTo(points[i].y, 1)
+			expect(decoded[i].z).toBe(0.5)
+		}
+	})
+
+	it('encodePoints/decodePoints route through 2D when dim = 2', () => {
+		const points: VecModel[] = [
+			{ x: 10, y: 20, z: 0.5 },
+			{ x: 15, y: 28, z: 0.5 },
+		]
+		expect(b64Vecs.encodePoints(points, 2)).toBe(b64Vecs.encodePoints2D(points))
+		const decoded = b64Vecs.decodePoints(b64Vecs.encodePoints(points, 2), 2)
+		expect(decoded[1].z).toBe(0.5)
+		expect(decoded[1].x).toBeCloseTo(15, 1)
+	})
+
+	it('is ~33% smaller than 3D for the same points', () => {
+		const points: VecModel[] = Array.from({ length: 100 }, (_, i) => ({
+			x: i * 2.5,
+			y: 50 + i,
+			z: 0.5,
+		}))
+		const bytes3D = fallbackBase64ToUint8Array(b64Vecs.encodePoints(points)).length
+		const bytes2D = fallbackBase64ToUint8Array(b64Vecs.encodePoints2D(points)).length
+		const saving = 1 - bytes2D / bytes3D
+		expect(saving).toBeGreaterThan(0.3)
+		expect(saving).toBeLessThan(0.36)
+	})
+
+	it('decodeFirstPoint2D / decodeLastPoint2D match decodePoints2D (incl. via dim routing)', () => {
+		const points: VecModel[] = [
+			{ x: 5, y: 6, z: 0.5 },
+			{ x: 12, y: 9, z: 0.5 },
+			{ x: 20, y: 4, z: 0.5 },
+		]
+		const path = b64Vecs.encodePoints(points, 2)
+		const all = b64Vecs.decodePoints2D(path)
+		expect(b64Vecs.decodeFirstPoint(path, 2)).toEqual(all[0])
+		expect(b64Vecs.decodeLastPoint(path, 2)).toEqual(all[all.length - 1])
+	})
+
+	it('empty input returns empty', () => {
+		expect(b64Vecs.encodePoints2D([])).toBe('')
+		expect(b64Vecs.decodePoints2D('')).toEqual([])
+	})
+})
+
+describe('padding-aware fallback base64', () => {
+	it('matches Node Buffer for every trailing-byte remainder', () => {
+		for (let len = 0; len < 32; len++) {
+			const bytes = new Uint8Array(len)
+			for (let i = 0; i < len; i++) bytes[i] = (i * 37 + 11) & 0xff
+			expect(fallbackUint8ArrayToBase64(bytes)).toBe(Buffer.from(bytes).toString('base64'))
+			expect(fallbackBase64ToUint8Array(fallbackUint8ArrayToBase64(bytes))).toEqual(bytes)
+		}
+	})
+
+	it('round-trips 2D buffer lengths (8 + 4(n-1) bytes)', () => {
+		for (const n of [1, 2, 3, 4, 5]) {
+			const len = 8 + (n - 1) * 4
+			const bytes = new Uint8Array(len)
+			for (let i = 0; i < len; i++) bytes[i] = (i * 53 + 7) & 0xff
+			expect(fallbackBase64ToUint8Array(fallbackUint8ArrayToBase64(bytes))).toEqual(bytes)
+		}
+	})
+})
+
+describe('isSinglePoint', () => {
+	const mk = (n: number, dim?: 2 | 3) =>
+		b64Vecs.encodePoints(
+			Array.from({ length: n }, (_, i) => ({ x: i, y: i, z: 0.5 })),
+			dim
+		)
+
+	it('is true only for a single point, across 2D and 3D', () => {
+		expect(b64Vecs.isSinglePoint(mk(1, 3), 3)).toBe(true)
+		expect(b64Vecs.isSinglePoint(mk(2, 3), 3)).toBe(false)
+		expect(b64Vecs.isSinglePoint(mk(1, 2), 2)).toBe(true)
+		expect(b64Vecs.isSinglePoint(mk(2, 2), 2)).toBe(false)
+		expect(b64Vecs.isSinglePoint(mk(3, 2), 2)).toBe(false)
+	})
+
+	it('regression: a 2-point 2D stroke is not a dot (the old `< 24` check failed here)', () => {
+		const twoPoint2D = b64Vecs.encodePoints(
+			[
+				{ x: 0, y: 0, z: 0.5 },
+				{ x: 4, y: 1, z: 0.5 },
+			],
+			2
+		)
+		expect(twoPoint2D.length).toBe(16) // same length as a 3D dot
+		expect(twoPoint2D.length < 24).toBe(true) // the old buggy heuristic would call this a dot
+		expect(b64Vecs.isSinglePoint(twoPoint2D, 2)).toBe(false) // the fix
+	})
+
+	it('defaults to 3D when dim is omitted', () => {
+		expect(b64Vecs.isSinglePoint(mk(1), undefined)).toBe(true)
+		expect(b64Vecs.isSinglePoint(mk(2), undefined)).toBe(false)
+	})
+})

package/src/misc/b64Vecs.ts

@@ -1,4 +1,3 @@
-import { assert } from '@tldraw/utils'
 import { VecModel } from './geometry-types'
 
 // Each point = 3 Float16s = 6 bytes = 8 base64 chars (legacy format)
@@ -7,6 +6,17 @@ const _POINT_B64_LENGTH = 8
 // First point in delta encoding = 3 Float32s = 12 bytes = 16 base64 chars
 const FIRST_POINT_B64_LENGTH = 16
 
+// First point in 2D delta encoding = 2 Float32s = 8 bytes = 12 base64 chars (incl. padding)
+const FIRST_POINT_2D_B64_LENGTH = 12
+
+// Pressure value supplied when decoding non-pressure (2D) paths
+const DEFAULT_PRESSURE = 0.5
+
+/** Draw segment path encoded with 2 dimensions, XY — the constant pressure Z is dropped. @public */
+export const DIM_2D = 2
+/** Draw segment path encoded with 3 dimensions, XYZ. @public */
+export const DIM_3D = 3
+
 // O(1) lookup table for base64 decoding (maps char code -> 6-bit value)
 const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
 const B64_LOOKUP = new Uint8Array(128)
@@ -14,6 +24,11 @@ for (let i = 0; i < 64; i++) {
 	B64_LOOKUP[BASE64_CHARS.charCodeAt(i)] = i
 }
 
+// Mask for one base64 sextet: the low 6 bits select an index into BASE64_CHARS (0–63).
+const SIX_BIT_MASK = 0x3f
+// '=' padding character, appended on encode so the output length is a multiple of 4.
+const PADDING_CHAR_CODE = '='.charCodeAt(0)
+
 // Precomputed powers of 2 for Float16 exponents (exp - 15, so indices 0-30 map to 2^-15 to 2^15)
 const POW2 = new Float64Array(31)
 for (let i = 0; i < 31; i++) {
@@ -67,11 +82,25 @@ function nativeBase64ToUint8Array(base64: string): Uint8Array {
 
 /** @internal */
 export function fallbackBase64ToUint8Array(base64: string): Uint8Array {
-	const numBytes = Math.floor((base64.length * 3) / 4)
+	// Strip up to 2 '=' padding characters to determine the real byte count.
+	// The 2D point layout (8 + 4(n-1) bytes) is not a multiple of 3, so encoded
+	// paths can carry padding the original multiple-of-3-only decoder couldn't read.
+	const paddedLength = base64.length
+	let padding = 0
+	if (paddedLength > 0 && base64.charCodeAt(paddedLength - 1) === PADDING_CHAR_CODE) {
+		padding++
+		if (paddedLength > 1 && base64.charCodeAt(paddedLength - 2) === PADDING_CHAR_CODE) {
+			padding++
+		}
+	}
+	const numBytes = Math.floor((paddedLength * 3) / 4) - padding
 	const bytes = new Uint8Array(numBytes)
 	let byteIndex = 0
 
-	for (let i = 0; i < base64.length; i += 4) {
+	// The reverse of encoding: each 4 chars are 4 six-bit values that pack back into
+	// one 24-bit number, which we then read out as 3 bytes (& 255 keeps one byte).
+	const fullGroups = Math.floor((paddedLength - padding) / 4) * 4
+	for (let i = 0; i < fullGroups; i += 4) {
 		const c0 = B64_LOOKUP[base64.charCodeAt(i)]
 		const c1 = B64_LOOKUP[base64.charCodeAt(i + 1)]
 		const c2 = B64_LOOKUP[base64.charCodeAt(i + 2)]
@@ -79,9 +108,24 @@ export function fallbackBase64ToUint8Array(base64: string): Uint8Array {
 
 		const bitmap = (c0 << 18) | (c1 << 12) | (c2 << 6) | c3
 
+		bytes[byteIndex++] = (bitmap >> 16) & 255 // top byte (bits 23–16)
+		bytes[byteIndex++] = (bitmap >> 8) & 255 // middle byte (bits 15–8)
+		bytes[byteIndex++] = bitmap & 255 // bottom byte (bits 7–0)
+	}
+
+	// Final group when padded: 3 valid chars -> 2 bytes, 2 valid chars -> 1 byte.
+	if (padding === 1) {
+		const c0 = B64_LOOKUP[base64.charCodeAt(fullGroups)]
+		const c1 = B64_LOOKUP[base64.charCodeAt(fullGroups + 1)]
+		const c2 = B64_LOOKUP[base64.charCodeAt(fullGroups + 2)]
+		const bitmap = (c0 << 18) | (c1 << 12) | (c2 << 6)
 		bytes[byteIndex++] = (bitmap >> 16) & 255
 		bytes[byteIndex++] = (bitmap >> 8) & 255
-		bytes[byteIndex++] = bitmap & 255
+	} else if (padding === 2) {
+		const c0 = B64_LOOKUP[base64.charCodeAt(fullGroups)]
+		const c1 = B64_LOOKUP[base64.charCodeAt(fullGroups + 1)]
+		const bitmap = (c0 << 18) | (c1 << 12)
+		bytes[byteIndex++] = (bitmap >> 16) & 255
 	}
 
 	return bytes
@@ -93,21 +137,48 @@ function nativeUint8ArrayToBase64(uint8Array: Uint8Array): string {
 
 /** @internal */
 export function fallbackUint8ArrayToBase64(uint8Array: Uint8Array): string {
-	assert(uint8Array.length % 3 === 0, 'Uint8Array length must be a multiple of 3')
+	const len = uint8Array.length
+	const fullGroups = Math.floor(len / 3) * 3
 	let result = ''
 
-	// Process bytes in groups of 3 -> 4 base64 chars
-	for (let i = 0; i < uint8Array.length; i += 3) {
+	// base64 represents 3 bytes (24 bits) as 4 characters of 6 bits each. For each
+	// group of 3 bytes we pack them into one 24-bit number, then read it back out as
+	// four 6-bit slices and use each slice (a value 0–63) to index into the 64-char
+	// alphabet. `>> n` shifts the wanted slice down to the bottom; SIX_BIT_MASK then
+	// discards everything above those 6 bits.
+	for (let i = 0; i < fullGroups; i += 3) {
 		const byte1 = uint8Array[i]
 		const byte2 = uint8Array[i + 1]
 		const byte3 = uint8Array[i + 2]
 
 		const bitmap = (byte1 << 16) | (byte2 << 8) | byte3
 		result +=
-			BASE64_CHARS[(bitmap >> 18) & 63] +
-			BASE64_CHARS[(bitmap >> 12) & 63] +
-			BASE64_CHARS[(bitmap >> 6) & 63] +
-			BASE64_CHARS[bitmap & 63]
+			BASE64_CHARS[(bitmap >> 18) & SIX_BIT_MASK] + // bits 23–18 (top sextet)
+			BASE64_CHARS[(bitmap >> 12) & SIX_BIT_MASK] + // bits 17–12
+			BASE64_CHARS[(bitmap >> 6) & SIX_BIT_MASK] + // bits 11–6
+			BASE64_CHARS[bitmap & SIX_BIT_MASK] // bits 5–0 (bottom sextet)
+	}
+
+	// A trailing 1 or 2 bytes can't fill a whole 4-char group, so we emit only the
+	// chars their bits cover and pad the rest with '=' to keep the length a multiple
+	// of 4. Standard base64 — matches the native API and Node's Buffer, so a path
+	// encoded by the fallback round-trips on a runtime that decodes with the native one.
+	const remaining = len - fullGroups
+	if (remaining === 1) {
+		// 8 bits → 2 sextets (the 2nd only partly filled), then "=="
+		const bitmap = uint8Array[fullGroups] << 16
+		result +=
+			BASE64_CHARS[(bitmap >> 18) & SIX_BIT_MASK] +
+			BASE64_CHARS[(bitmap >> 12) & SIX_BIT_MASK] +
+			'=='
+	} else if (remaining === 2) {
+		// 16 bits → 3 sextets (the 3rd only partly filled), then "="
+		const bitmap = (uint8Array[fullGroups] << 16) | (uint8Array[fullGroups + 1] << 8)
+		result +=
+			BASE64_CHARS[(bitmap >> 18) & SIX_BIT_MASK] +
+			BASE64_CHARS[(bitmap >> 12) & SIX_BIT_MASK] +
+			BASE64_CHARS[(bitmap >> 6) & SIX_BIT_MASK] +
+			'='
 	}
 
 	return result
@@ -299,10 +370,12 @@ export class b64Vecs {
 	 * - Delta points: 3 Float16 values each = 6 bytes = 8 base64 chars each
 	 *
 	 * @param points - An array of VecModel objects to encode
+	 * @param dim - Encoding dimension; `2` routes through the 2D variant (drops z), `3` (default) keeps x, y, z
 	 * @returns A base64-encoded string containing delta-encoded points
 	 * @public
 	 */
-	static encodePoints(points: VecModel[]): string {
+	static encodePoints(points: VecModel[], dim?: 2 | 3): string {
+		if (dim === DIM_2D) return b64Vecs.encodePoints2D(points)
 		if (points.length === 0) return ''
 
 		// First point: 3 Float32s = 12 bytes
@@ -348,10 +421,12 @@ export class b64Vecs {
 	 * Float16 deltas that are accumulated to reconstruct absolute positions.
 	 *
 	 * @param base64 - The base64-encoded string containing delta-encoded point data
+	 * @param dim - Encoding dimension; `2` expects x/y only (z supplied as 0.5), `3` (default) expects x/y/z
 	 * @returns An array of VecModel objects with absolute coordinates
 	 * @public
 	 */
-	static decodePoints(base64: string): VecModel[] {
+	static decodePoints(base64: string, dim?: 2 | 3): VecModel[] {
+		if (dim === DIM_2D) return b64Vecs.decodePoints2D(base64)
 		if (base64.length === 0) return []
 
 		const bytes = base64ToUint8Array(base64)
@@ -381,10 +456,12 @@ export class b64Vecs {
 	 * The first point is stored as Float32 for full precision.
 	 *
 	 * @param b64Points - The delta-encoded base64 string
+	 * @param dim - Encoding dimension; `2` expects x/y only (z supplied as 0.5), `3` (default) expects x/y/z
 	 * @returns The first point as a VecModel, or null if the string is too short
 	 * @public
 	 */
-	static decodeFirstPoint(b64Points: string): VecModel | null {
+	static decodeFirstPoint(b64Points: string, dim?: 2 | 3): VecModel | null {
+		if (dim === DIM_2D) return b64Vecs.decodeFirstPoint2D(b64Points)
 		// First point needs 16 base64 chars (12 bytes as Float32)
 		if (b64Points.length < FIRST_POINT_B64_LENGTH) return null
 
@@ -403,10 +480,12 @@ export class b64Vecs {
 	 * Requires decoding all points to accumulate deltas.
 	 *
 	 * @param b64Points - The delta-encoded base64 string
+	 * @param dim - Encoding dimension; `2` expects x/y only (z supplied as 0.5), `3` (default) expects x/y/z
 	 * @returns The last point as a VecModel, or null if the string is too short
 	 * @public
 	 */
-	static decodeLastPoint(b64Points: string): VecModel | null {
+	static decodeLastPoint(b64Points: string, dim?: 2 | 3): VecModel | null {
+		if (dim === DIM_2D) return b64Vecs.decodeLastPoint2D(b64Points)
 		if (b64Points.length < FIRST_POINT_B64_LENGTH) return null
 
 		const bytes = base64ToUint8Array(b64Points)
@@ -427,4 +506,140 @@ export class b64Vecs {
 
 		return { x, y, z }
 	}
+
+	/**
+	 * Encode an array of VecModels as 2D delta-encoded points, dropping z entirely.
+	 * Use for draw shapes from devices that don't report pressure, where z is a
+	 * constant 0.5 and storing it wastes ~33% of per-point bytes.
+	 *
+	 * Format:
+	 * - First point: 2 Float32 values (x, y) = 8 bytes
+	 * - Delta points: 2 Float16 values (dx, dy) = 4 bytes each
+	 *
+	 * @param points - An array of VecModel objects to encode (z is discarded)
+	 * @returns A base64-encoded string containing 2D delta-encoded points
+	 * @public
+	 */
+	static encodePoints2D(points: VecModel[]): string {
+		if (points.length === 0) return ''
+
+		const firstPointBytes = 8
+		const deltaBytes = (points.length - 1) * 4
+		const buffer = new Uint8Array(firstPointBytes + deltaBytes)
+		const dataView = new DataView(buffer.buffer)
+
+		const first = points[0]
+		dataView.setFloat32(0, first.x, true)
+		dataView.setFloat32(4, first.y, true)
+
+		let prevX = first.x
+		let prevY = first.y
+
+		for (let i = 1; i < points.length; i++) {
+			const p = points[i]
+			const offset = firstPointBytes + (i - 1) * 4
+			setFloat16(dataView, offset, p.x - prevX)
+			setFloat16(dataView, offset + 2, p.y - prevY)
+			prevX = p.x
+			prevY = p.y
+		}
+
+		return uint8ArrayToBase64(buffer)
+	}
+
+	/**
+	 * Decode a 2D delta-encoded base64 string back to an array of absolute VecModels.
+	 * The z coordinate is always set to 0.5 (the default pressure value) so downstream
+	 * consumers don't need a separate code path.
+	 *
+	 * @param base64 - The base64-encoded string containing 2D delta-encoded point data
+	 * @returns An array of VecModel objects with absolute (x, y) and z = 0.5
+	 * @public
+	 */
+	static decodePoints2D(base64: string): VecModel[] {
+		if (base64.length === 0) return []
+
+		const bytes = base64ToUint8Array(base64)
+		const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+		const result: VecModel[] = []
+
+		let x = dataView.getFloat32(0, true)
+		let y = dataView.getFloat32(4, true)
+		result.push({ x, y, z: DEFAULT_PRESSURE })
+
+		const firstPointBytes = 8
+		for (let offset = firstPointBytes; offset < bytes.length; offset += 4) {
+			x += getFloat16(dataView, offset)
+			y += getFloat16(dataView, offset + 2)
+			result.push({ x, y, z: DEFAULT_PRESSURE })
+		}
+
+		return result
+	}
+
+	/**
+	 * Get the first point from a 2D delta-encoded base64 string.
+	 *
+	 * @param b64Points - The 2D delta-encoded base64 string
+	 * @returns The first point with z = 0.5, or null if the string is too short
+	 * @public
+	 */
+	static decodeFirstPoint2D(b64Points: string): VecModel | null {
+		if (b64Points.length < FIRST_POINT_2D_B64_LENGTH) return null
+
+		const bytes = base64ToUint8Array(b64Points.slice(0, FIRST_POINT_2D_B64_LENGTH))
+		const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+		return {
+			x: dataView.getFloat32(0, true),
+			y: dataView.getFloat32(4, true),
+			z: DEFAULT_PRESSURE,
+		}
+	}
+
+	/**
+	 * Get the last point from a 2D delta-encoded base64 string.
+	 * Requires decoding all points to accumulate deltas.
+	 *
+	 * @param b64Points - The 2D delta-encoded base64 string
+	 * @returns The last point with z = 0.5, or null if the string is too short
+	 * @public
+	 */
+	static decodeLastPoint2D(b64Points: string): VecModel | null {
+		if (b64Points.length < FIRST_POINT_2D_B64_LENGTH) return null
+
+		const bytes = base64ToUint8Array(b64Points)
+		const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+		let x = dataView.getFloat32(0, true)
+		let y = dataView.getFloat32(4, true)
+
+		const firstPointBytes = 8
+		for (let offset = firstPointBytes; offset < bytes.length; offset += 4) {
+			x += getFloat16(dataView, offset)
+			y += getFloat16(dataView, offset + 2)
+		}
+
+		return { x, y, z: DEFAULT_PRESSURE }
+	}
+
+	/**
+	 * Whether an encoded path contains only a single point (a "dot"), inferred from
+	 * the encoded length without decoding — cheap enough for the render path.
+	 *
+	 * The single-point length depends on the encoding dimension, so this takes the
+	 * segment's `dim`: a one-point path is `FIRST_POINT_B64_LENGTH` chars (3D) or
+	 * `FIRST_POINT_2D_B64_LENGTH` chars (2D). Keeping this beside the layout constants
+	 * is deliberate — it is the single source of truth for "how long is one point", so
+	 * callers never hard-code a length threshold (which silently breaks when a new
+	 * encoding is added).
+	 *
+	 * @param b64Points - The encoded path string
+	 * @param dim - Encoding dimension; `2` for (x, y), `3` (default) for (x, y, z)
+	 * @returns true if the path encodes exactly one point
+	 * @public
+	 */
+	static isSinglePoint(b64Points: string, dim?: 2 | 3): boolean {
+		return b64Points.length <= (dim === DIM_2D ? FIRST_POINT_2D_B64_LENGTH : FIRST_POINT_B64_LENGTH)
+	}
 }

package/src/records/TLInstance.ts

@@ -15,6 +15,7 @@ import { scribbleValidator, TLScribble } from '../misc/TLScribble'
 import { StyleProp } from '../styles/StyleProp'
 import { pageIdValidator, TLPageId } from './TLPage'
 import { TLShapeId } from './TLShape'
+import { TLUserId, userIdValidator } from './TLUser'
 
 /**
  * State that is particular to a single browser tab. The TLInstance record stores
@@ -43,8 +44,8 @@ export interface TLInstance extends BaseRecord<'instance', TLInstanceId> {
 	currentPageId: TLPageId
 	opacityForNextShape: TLOpacityType
 	stylesForNextShape: Record<string, unknown>
-	followingUserId: string | null
-	highlightedUserIds: string[]
+	followingUserId: TLUserId | null
+	highlightedUserIds: TLUserId[]
 	brush: BoxModel | null
 	cursor: TLCursor
 	scribbles: TLScribble[]
@@ -211,7 +212,7 @@ export function createInstanceRecordType(stylesById: Map<string, StyleProp<unkno
 			typeName: T.literal('instance'),
 			id: idValidator<TLInstanceId>('instance'),
 			currentPageId: pageIdValidator,
-			followingUserId: T.string.nullable(),
+			followingUserId: userIdValidator.nullable(),
 			brush: boxModelValidator.nullable(),
 			opacityForNextShape: opacityValidator,
 			stylesForNextShape: T.object(stylesForNextShapeValidators),
@@ -228,7 +229,7 @@ export function createInstanceRecordType(stylesById: Map<string, StyleProp<unkno
 			isGridMode: T.boolean,
 			chatMessage: T.string,
 			isChatting: T.boolean,
-			highlightedUserIds: T.arrayOf(T.string),
+			highlightedUserIds: T.arrayOf(userIdValidator),
 			isFocused: T.boolean,
 			devicePixelRatio: T.number,
 			isCoarsePointer: T.boolean,

package/src/records/TLPageState.ts

@@ -212,7 +212,11 @@ export const InstancePageStateRecordType = createRecordType<TLInstancePageState>
 		ephemeralKeys: {
 			pageId: false,
 			selectedShapeIds: false,
-			editingShapeId: false,
+			// editingShapeId is set with `history: 'ignore'`, so entering the editing
+			// state is never undoable. Marking it ephemeral keeps undo/redo from
+			// reapplying a stale editingShapeId (e.g. after a shape it pointed at was
+			// deleted), which could leave the editor pointing at a missing shape.
+			editingShapeId: true,
 			croppingShapeId: false,
 			meta: false,