@tldraw/tlschema 4.2.1 → 4.2.2

package/src/misc/TLOpacity.ts

@@ -53,8 +53,4 @@ export type TLOpacityType = number
  *
  * @public
  */
-export const opacityValidator = T.number.check((n) => {
-	if (n < 0 || n > 1) {
-		throw new T.ValidationError('Opacity must be between 0 and 1')
-	}
-})
+export const opacityValidator = T.unitInterval

package/src/misc/TLRichText.ts

@@ -12,7 +12,12 @@ import { T } from '@tldraw/validate'
  * const isValid = richTextValidator.check(richText) // true
  * ```
  */
-export const richTextValidator = T.object({ type: T.string, content: T.arrayOf(T.unknown) })
+
+export const richTextValidator = T.object({
+	type: T.string,
+	content: T.arrayOf(T.unknown),
+	attrs: T.any.optional(),
+})
 
 /**
  * Type representing rich text content in tldraw. Rich text follows a document-based

package/src/misc/b64Vecs.ts

@@ -0,0 +1,308 @@
+import { VecModel } from './geometry-types'
+
+// Each point = 3 Float16s = 6 bytes = 8 base64 chars
+const POINT_B64_LENGTH = 8
+
+// O(1) lookup table for base64 decoding (maps char code -> 6-bit value)
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+const B64_LOOKUP = new Uint8Array(128)
+for (let i = 0; i < 64; i++) {
+	B64_LOOKUP[BASE64_CHARS.charCodeAt(i)] = i
+}
+
+// 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++) {
+	POW2[i] = Math.pow(2, i - 15)
+}
+const POW2_SUBNORMAL = Math.pow(2, -14) / 1024 // For subnormal numbers
+
+// Precomputed mantissa values: 1 + frac/1024 for all 1024 possible frac values
+// Avoids division in hot path
+const MANTISSA = new Float64Array(1024)
+for (let i = 0; i < 1024; i++) {
+	MANTISSA[i] = 1 + i / 1024
+}
+
+/**
+ * Convert a Uint16Array (containing Float16 bits) to base64.
+ * Processes bytes in groups of 3 to produce 4 base64 characters.
+ *
+ * @internal
+ */
+function uint16ArrayToBase64(uint16Array: Uint16Array): string {
+	const uint8Array = new Uint8Array(
+		uint16Array.buffer,
+		uint16Array.byteOffset,
+		uint16Array.byteLength
+	)
+	let result = ''
+
+	// Process bytes in groups of 3 -> 4 base64 chars
+	for (let i = 0; i < uint8Array.length; i += 3) {
+		const byte1 = uint8Array[i]
+		const byte2 = uint8Array[i + 1] // Always exists for our use case (multiple of 6 bytes)
+		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]
+	}
+
+	return result
+}
+
+/**
+ * Convert a base64 string to Uint16Array containing Float16 bits.
+ * The base64 string must have a length that is a multiple of 4.
+ *
+ * @param base64 - The base64-encoded string to decode
+ * @returns A Uint16Array containing the decoded Float16 bit values
+ * @public
+ */
+function base64ToUint16Array(base64: string): Uint16Array {
+	// Calculate exact number of bytes (4 base64 chars = 3 bytes)
+	const numBytes = Math.floor((base64.length * 3) / 4)
+	const bytes = new Uint8Array(numBytes)
+	let byteIndex = 0
+
+	// Process in groups of 4 base64 characters
+	for (let i = 0; i < base64.length; 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)]
+		const c3 = B64_LOOKUP[base64.charCodeAt(i + 3)]
+
+		const bitmap = (c0 << 18) | (c1 << 12) | (c2 << 6) | c3
+
+		bytes[byteIndex++] = (bitmap >> 16) & 255
+		bytes[byteIndex++] = (bitmap >> 8) & 255
+		bytes[byteIndex++] = bitmap & 255
+	}
+
+	return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 2)
+}
+
+/**
+ * Convert Float16 bits to a number using optimized lookup tables.
+ * Handles normal numbers, subnormal numbers, zero, infinity, and NaN.
+ *
+ * @param bits - The 16-bit Float16 value to decode
+ * @returns The decoded number value
+ */
+function float16BitsToNumber(bits: number): number {
+	const sign = bits >> 15
+	const exp = (bits >> 10) & 0x1f
+	const frac = bits & 0x3ff
+
+	if (exp === 0) {
+		// Subnormal or zero - rare case
+		return sign ? -frac * POW2_SUBNORMAL : frac * POW2_SUBNORMAL
+	}
+	if (exp === 31) {
+		// Infinity or NaN - very rare
+		return frac ? NaN : sign ? -Infinity : Infinity
+	}
+	// Normal case - two table lookups, one multiply, no division
+	const magnitude = POW2[exp] * MANTISSA[frac]
+	return sign ? -magnitude : magnitude
+}
+
+/**
+ * Convert a number to Float16 bits.
+ * Handles normal numbers, subnormal numbers, zero, infinity, and NaN.
+ *
+ * @param value - The number to encode as Float16
+ * @returns The 16-bit Float16 representation of the number
+ * @internal
+ */
+function numberToFloat16Bits(value: number): number {
+	if (value === 0) return Object.is(value, -0) ? 0x8000 : 0
+	if (!Number.isFinite(value)) {
+		if (Number.isNaN(value)) return 0x7e00
+		return value > 0 ? 0x7c00 : 0xfc00
+	}
+
+	const sign = value < 0 ? 1 : 0
+	value = Math.abs(value)
+
+	// Find exponent and mantissa
+	const exp = Math.floor(Math.log2(value))
+	let expBiased = exp + 15
+
+	if (expBiased >= 31) {
+		// Overflow to infinity
+		return (sign << 15) | 0x7c00
+	}
+	if (expBiased <= 0) {
+		// Subnormal or underflow
+		const frac = Math.round(value * Math.pow(2, 14) * 1024)
+		return (sign << 15) | (frac & 0x3ff)
+	}
+
+	// Normal number
+	const mantissa = value / Math.pow(2, exp) - 1
+	let frac = Math.round(mantissa * 1024)
+
+	// Handle rounding overflow: if frac rounds to 1024, increment exponent
+	if (frac >= 1024) {
+		frac = 0
+		expBiased++
+		if (expBiased >= 31) {
+			// Overflow to infinity
+			return (sign << 15) | 0x7c00
+		}
+	}
+
+	return (sign << 15) | (expBiased << 10) | frac
+}
+
+/**
+ * Utilities for encoding and decoding points using base64 and Float16 encoding.
+ * Provides functions for converting between VecModel arrays and compact base64 strings,
+ * as well as individual point encoding/decoding operations.
+ *
+ * @public
+ */
+export class b64Vecs {
+	/**
+	 * Encode a single point (x, y, z) to 8 base64 characters.
+	 * Each coordinate is encoded as a Float16 value, resulting in 6 bytes total.
+	 *
+	 * @param x - The x coordinate
+	 * @param y - The y coordinate
+	 * @param z - The z coordinate
+	 * @returns An 8-character base64 string representing the point
+	 */
+	static encodePoint(x: number, y: number, z: number): string {
+		const xBits = numberToFloat16Bits(x)
+		const yBits = numberToFloat16Bits(y)
+		const zBits = numberToFloat16Bits(z)
+
+		// Convert Float16 bits to 6 bytes (little-endian)
+		const b0 = xBits & 0xff
+		const b1 = (xBits >> 8) & 0xff
+		const b2 = yBits & 0xff
+		const b3 = (yBits >> 8) & 0xff
+		const b4 = zBits & 0xff
+		const b5 = (zBits >> 8) & 0xff
+
+		// Convert 6 bytes to 8 base64 chars
+		const bitmap1 = (b0 << 16) | (b1 << 8) | b2
+		const bitmap2 = (b3 << 16) | (b4 << 8) | b5
+
+		return (
+			BASE64_CHARS[(bitmap1 >> 18) & 0x3f] +
+			BASE64_CHARS[(bitmap1 >> 12) & 0x3f] +
+			BASE64_CHARS[(bitmap1 >> 6) & 0x3f] +
+			BASE64_CHARS[bitmap1 & 0x3f] +
+			BASE64_CHARS[(bitmap2 >> 18) & 0x3f] +
+			BASE64_CHARS[(bitmap2 >> 12) & 0x3f] +
+			BASE64_CHARS[(bitmap2 >> 6) & 0x3f] +
+			BASE64_CHARS[bitmap2 & 0x3f]
+		)
+	}
+
+	/**
+	 * Convert an array of VecModels to a base64 string for compact storage.
+	 * Uses Float16 encoding for each coordinate (x, y, z). If a point's z value is
+	 * undefined, it defaults to 0.5.
+	 *
+	 * @param points - An array of VecModel objects to encode
+	 * @returns A base64-encoded string containing all points
+	 */
+	static encodePoints(points: VecModel[]): string {
+		const uint16s = new Uint16Array(points.length * 3)
+		for (let i = 0; i < points.length; i++) {
+			const p = points[i]
+			uint16s[i * 3] = numberToFloat16Bits(p.x)
+			uint16s[i * 3 + 1] = numberToFloat16Bits(p.y)
+			uint16s[i * 3 + 2] = numberToFloat16Bits(p.z ?? 0.5)
+		}
+		return uint16ArrayToBase64(uint16s)
+	}
+
+	/**
+	 * Convert a base64 string back to an array of VecModels.
+	 * Decodes Float16-encoded coordinates (x, y, z) from the base64 string.
+	 *
+	 * @param base64 - The base64-encoded string containing point data
+	 * @returns An array of VecModel objects decoded from the string
+	 */
+	static decodePoints(base64: string): VecModel[] {
+		const uint16s = base64ToUint16Array(base64)
+		const result: VecModel[] = []
+		for (let i = 0; i < uint16s.length; i += 3) {
+			result.push({
+				x: float16BitsToNumber(uint16s[i]),
+				y: float16BitsToNumber(uint16s[i + 1]),
+				z: float16BitsToNumber(uint16s[i + 2]),
+			})
+		}
+		return result
+	}
+
+	/**
+	 * Decode a single point (8 base64 chars) starting at the given offset.
+	 * Each point is encoded as 3 Float16 values (x, y, z) in 8 base64 characters.
+	 *
+	 * @param b64Points - The base64-encoded string containing point data
+	 * @param charOffset - The character offset where the point starts (must be a multiple of 8)
+	 * @returns A VecModel object with x, y, and z coordinates
+	 * @internal
+	 */
+	static decodePointAt(b64Points: string, charOffset: number): VecModel {
+		// Decode 8 base64 chars -> 6 bytes -> 3 Float16s using O(1) lookup
+		const c0 = B64_LOOKUP[b64Points.charCodeAt(charOffset)]
+		const c1 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 1)]
+		const c2 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 2)]
+		const c3 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 3)]
+		const c4 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 4)]
+		const c5 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 5)]
+		const c6 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 6)]
+		const c7 = B64_LOOKUP[b64Points.charCodeAt(charOffset + 7)]
+
+		// 4 base64 chars -> 24 bits -> 3 bytes
+		const bitmap1 = (c0 << 18) | (c1 << 12) | (c2 << 6) | c3
+		const bitmap2 = (c4 << 18) | (c5 << 12) | (c6 << 6) | c7
+
+		// Extract Float16 bits directly (little-endian byte order)
+		// bitmap1 = [byte0:8][byte1:8][byte2:8], bitmap2 = [byte3:8][byte4:8][byte5:8]
+		// xBits = byte0 | (byte1 << 8), yBits = byte2 | (byte3 << 8), zBits = byte4 | (byte5 << 8)
+		const xBits = ((bitmap1 >> 16) & 0xff) | (bitmap1 & 0xff00)
+		const yBits = (bitmap1 & 0xff) | ((bitmap2 >> 8) & 0xff00)
+		const zBits = ((bitmap2 >> 8) & 0xff) | ((bitmap2 << 8) & 0xff00)
+
+		return {
+			x: float16BitsToNumber(xBits),
+			y: float16BitsToNumber(yBits),
+			z: float16BitsToNumber(zBits),
+		}
+	}
+
+	/**
+	 * Get the first point from a base64-encoded string of points.
+	 *
+	 * @param b64Points - The base64-encoded string containing point data
+	 * @returns The first point as a VecModel, or null if the string is too short
+	 * @public
+	 */
+	static decodeFirstPoint(b64Points: string): VecModel | null {
+		if (b64Points.length < POINT_B64_LENGTH) return null
+		return b64Vecs.decodePointAt(b64Points, 0)
+	}
+
+	/**
+	 * Get the last point from a base64-encoded string of points.
+	 *
+	 * @param b64Points - The base64-encoded string containing point data
+	 * @returns The last point as a VecModel, or null if the string is too short
+	 */
+	static decodeLastPoint(b64Points: string): VecModel | null {
+		if (b64Points.length < POINT_B64_LENGTH) return null
+		return b64Vecs.decodePointAt(b64Points, b64Points.length - POINT_B64_LENGTH)
+	}
+}

package/src/records/TLAsset.ts

@@ -9,7 +9,7 @@ import { TLBaseAsset } from '../assets/TLBaseAsset'
 import { bookmarkAssetValidator, TLBookmarkAsset } from '../assets/TLBookmarkAsset'
 import { imageAssetValidator, TLImageAsset } from '../assets/TLImageAsset'
 import { TLVideoAsset, videoAssetValidator } from '../assets/TLVideoAsset'
-import { TLShape } from './TLShape'
+import { ExtractShapeByProps } from './TLShape'
 
 /**
  * Union type representing all possible asset types in tldraw.
@@ -222,4 +222,4 @@ export type TLAssetId = RecordId<TLBaseAsset<any, any>>
  *
  * @public
  */
-export type TLAssetShape = Extract<TLShape, { props: { assetId: TLAssetId } }>
+export type TLAssetShape = ExtractShapeByProps<{ assetId: TLAssetId }>

package/src/records/TLBinding.ts

@@ -5,7 +5,7 @@ import {
 	createRecordMigrationSequence,
 	createRecordType,
 } from '@tldraw/store'
-import { Expand, mapObjectMapValues, uniqueId } from '@tldraw/utils'
+import { mapObjectMapValues, uniqueId } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 import { TLArrowBinding } from '../bindings/TLArrowBinding'
 import { TLBaseBinding, createBindingValidator } from '../bindings/TLBaseBinding'
@@ -56,10 +56,42 @@ export type TLDefaultBinding = TLArrowBinding
  */
 export type TLUnknownBinding = TLBaseBinding<string, object>
 
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TLGlobalBindingPropsMap {}
+
+/** @public */
+// prettier-ignore
+export type TLIndexedBindings = {
+	// We iterate over a union of augmented keys and default binding types.
+	// This allows us to include (or conditionally exclude or override) the default bindings in one go.
+	//
+	// In the `as` clause we are filtering out disabled bindings.
+	[K in keyof TLGlobalBindingPropsMap | TLDefaultBinding['type'] as K extends TLDefaultBinding['type']
+		? K extends keyof TLGlobalBindingPropsMap
+			? // if it extends a nullish value the user has disabled this binding type so we filter it out with never
+				TLGlobalBindingPropsMap[K] extends null | undefined
+				? never
+				: K
+			: K
+		: K]: K extends TLDefaultBinding['type']
+			? // if it's a default binding type we need to check if it's been overridden
+				K extends keyof TLGlobalBindingPropsMap
+				? // if it has been overriden then use the custom binding definition
+					TLBaseBinding<K, TLGlobalBindingPropsMap[K]>
+				: // if it has not been overriden then reuse existing type aliases for better type display
+					Extract<TLDefaultBinding, { type: K }>
+			: // use the custom binding definition
+				TLBaseBinding<K, TLGlobalBindingPropsMap[K & keyof TLGlobalBindingPropsMap]>
+}
+
 /**
- * The set of all bindings that are available in the editor, including unknown bindings.
+ * The set of all bindings that are available in the editor.
  * Bindings represent relationships between shapes, such as arrows connecting to other shapes.
  *
+ * You can use this type without a type argument to work with any binding, or pass
+ * a specific binding type string (e.g., `'arrow'`) to narrow down to that specific binding type.
+ *
  * @example
  * ```ts
  * // Check binding type and handle accordingly
@@ -73,11 +105,17 @@ export type TLUnknownBinding = TLBaseBinding<string, object>
  *       break
  *   }
  * }
+ *
+ * // Narrow to a specific binding type by passing the type as a generic argument
+ * function getArrowSourceId(binding: TLBinding<'arrow'>) {
+ *   return binding.fromId // TypeScript knows this is a TLArrowBinding
+ * }
  * ```
  *
  * @public
  */
-export type TLBinding = TLDefaultBinding | TLUnknownBinding
+export type TLBinding<K extends keyof TLIndexedBindings = keyof TLIndexedBindings> =
+	TLIndexedBindings[K]
 
 /**
  * Type for updating existing bindings with partial properties.
@@ -99,15 +137,17 @@ export type TLBinding = TLDefaultBinding | TLUnknownBinding
  *
  * @public
  */
-export type TLBindingUpdate<T extends TLBinding = TLBinding> = Expand<{
-	id: TLBindingId
-	type: T['type']
-	typeName?: T['typeName']
-	fromId?: T['fromId']
-	toId?: T['toId']
-	props?: Partial<T['props']>
-	meta?: Partial<T['meta']>
-}>
+export type TLBindingUpdate<T extends TLBinding = TLBinding> = T extends T
+	? {
+			id: TLBindingId
+			type: T['type']
+			typeName?: T['typeName']
+			fromId?: T['fromId']
+			toId?: T['toId']
+			props?: Partial<T['props']>
+			meta?: Partial<T['meta']>
+		}
+	: never
 
 /**
  * Type for creating new bindings with required fromId and toId.
@@ -133,15 +173,17 @@ export type TLBindingUpdate<T extends TLBinding = TLBinding> = Expand<{
  *
  * @public
  */
-export type TLBindingCreate<T extends TLBinding = TLBinding> = Expand<{
-	id?: TLBindingId
-	type: T['type']
-	typeName?: T['typeName']
-	fromId: T['fromId']
-	toId: T['toId']
-	props?: Partial<T['props']>
-	meta?: Partial<T['meta']>
-}>
+export type TLBindingCreate<T extends TLBinding = TLBinding> = T extends T
+	? {
+			id?: TLBindingId
+			type: T['type']
+			typeName?: T['typeName']
+			fromId: T['fromId']
+			toId: T['toId']
+			props?: Partial<T['props']>
+			meta?: Partial<T['meta']>
+		}
+	: never
 
 /**
  * Branded string type for binding record identifiers.
@@ -166,7 +208,7 @@ export type TLBindingCreate<T extends TLBinding = TLBinding> = Expand<{
  *
  * @public
  */
-export type TLBindingId = RecordId<TLUnknownBinding>
+export type TLBindingId = RecordId<TLBinding>
 
 /**
  * Migration version identifiers for the root binding record schema.
@@ -375,7 +417,7 @@ export function createBindingPropsMigrationIds<S extends string, T extends Recor
  * @internal
  */
 export function createBindingRecordType(bindings: Record<string, SchemaPropsInfo>) {
-	return createRecordType<TLBinding>('binding', {
+	return createRecordType('binding', {
 		scope: 'document',
 		validator: T.model(
 			'binding',

package/src/records/TLShape.ts

@@ -79,12 +79,51 @@ export type TLDefaultShape =
  */
 export type TLUnknownShape = TLBaseShape<string, object>
 
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TLGlobalShapePropsMap {}
+
+/** @public */
+// prettier-ignore
+export type TLIndexedShapes = {
+	// We iterate over a union of augmented keys and default shape types.
+	// This allows us to include (or conditionally exclude or override) the default shapes in one go.
+	//
+	// In the `as` clause we are filtering out disabled shapes.
+	[K in keyof TLGlobalShapePropsMap | TLDefaultShape['type'] as K extends TLDefaultShape['type']
+		? // core shapes are always available and cannot be overridden so we just include them
+			K extends 'group'
+			? K
+			: K extends keyof TLGlobalShapePropsMap
+				? // if it extends a nullish value the user has disabled this shape type so we filter it out with never
+					TLGlobalShapePropsMap[K] extends null | undefined
+					? never
+					: K
+				: K
+		: K]: K extends 'group'
+		? // core shapes are always available and cannot be overridden so we just include them
+			Extract<TLDefaultShape, { type: K }>
+		: K extends TLDefaultShape['type']
+			? // if it's a default shape type we need to check if it's been overridden
+				K extends keyof TLGlobalShapePropsMap
+				? // if it has been overriden then use the custom shape definition
+					TLBaseShape<K, TLGlobalShapePropsMap[K]>
+				: // if it has not been overriden then reuse existing type aliases for better type display
+					Extract<TLDefaultShape, { type: K }>
+			: // use the custom shape definition
+				TLBaseShape<K, TLGlobalShapePropsMap[K & keyof TLGlobalShapePropsMap]>
+}
+
 /**
- * The set of all shapes that are available in the editor, including unknown shapes.
+ * The set of all shapes that are available in the editor.
  *
  * This is the primary shape type used throughout tldraw. It includes both the
  * built-in default shapes and any custom shapes that might be added.
  *
+ * You can use this type without a type argument to work with any shape, or pass
+ * a specific shape type string (e.g., `'geo'`, `'arrow'`, `'text'`) to narrow
+ * down to that specific shape type.
+ *
  * @example
  * ```ts
  * // Work with any shape in the editor
@@ -95,11 +134,16 @@ export type TLUnknownShape = TLBaseShape<string, object>
  *     y: shape.y + deltaY
  *   }
  * }
+ *
+ * // Narrow to a specific shape type by passing the type as a generic argument
+ * function getArrowLabel(shape: TLShape<'arrow'>): string {
+ *   return shape.props.text // TypeScript knows this is a TLArrowShape
+ * }
  * ```
  *
  * @public
  */
-export type TLShape = TLDefaultShape | TLUnknownShape
+export type TLShape<K extends keyof TLIndexedShapes = keyof TLIndexedShapes> = TLIndexedShapes[K]
 
 /**
  * A partial version of a shape, useful for updates and patches.
@@ -139,6 +183,57 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
 		} & Partial<Omit<T, 'type' | 'id' | 'props' | 'meta'>>
 	: never
 
+/**
+ * A partial version of a shape, useful for creating shapes.
+ *
+ * This type represents a shape where all properties except `type` are optional.
+ * It's commonly used when creating shapes.
+ *
+ * @example
+ * ```ts
+ * // Create a shape
+ * const shapeCreate: TLCreateShapePartial = {
+ *   type: 'geo',
+ *   x: 100,
+ *   y: 200
+ * }
+ *
+ * // Create shape properties
+ * const propsCreate: TLCreateShapePartial<TLGeoShape> = {
+ *   type: 'geo',
+ *   props: {
+ *     w: 150,
+ *     h: 100
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export type TLCreateShapePartial<T extends TLShape = TLShape> = T extends T
+	? {
+			type: T['type']
+			props?: Partial<T['props']>
+			meta?: Partial<T['meta']>
+		} & Partial<Omit<T, 'type' | 'props' | 'meta'>>
+	: never
+
+/**
+ * Extract a shape type by its props.
+ *
+ * This utility type takes a props object type and returns the corresponding shape type
+ * from the TLShape union whose props match the given type.
+ *
+ * @example
+ * ```ts
+ * type MyShape = ExtractShapeByProps<{ w: number; h: number }>
+ * // MyShape is now the type of shape(s) that have props with w and h as numbers
+ * ```
+ *
+ * @public
+ */
+export type ExtractShapeByProps<P> = Extract<TLShape, { props: P }>
+
 /**
  * A unique identifier for a shape record.
  *
@@ -153,7 +248,7 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
  *
  * @public
  */
-export type TLShapeId = RecordId<TLUnknownShape>
+export type TLShapeId = RecordId<TLShape>
 
 /**
  * The ID of a shape's parent, which can be either a page or another shape.
@@ -195,7 +290,7 @@ export const rootShapeVersions = createMigrationIds('com.tldraw.shape', {
 	HoistOpacity: 2,
 	AddMeta: 3,
 	AddWhite: 4,
-} as const)
+})
 
 /**
  * Migration sequence for the root shape record type.
@@ -469,7 +564,7 @@ export function createShapePropsMigrationIds<
  * @internal
  */
 export function createShapeRecordType(shapes: Record<string, SchemaPropsInfo>) {
-	return createRecordType<TLShape>('shape', {
+	return createRecordType('shape', {
 		scope: 'document',
 		validator: T.model(
 			'shape',

package/src/shapes/ShapeWithCrop.ts

@@ -1,5 +1,5 @@
 import { VecModel } from '../misc/geometry-types'
-import { TLBaseShape } from './TLBaseShape'
+import { ExtractShapeByProps } from '../records/TLShape'
 
 /**
  * Defines cropping parameters for shapes that support cropping.
@@ -71,4 +71,4 @@ export interface TLShapeCrop {
  *
  * @public
  */
-export type ShapeWithCrop = TLBaseShape<string, { w: number; h: number; crop: TLShapeCrop | null }>
+export type ShapeWithCrop = ExtractShapeByProps<{ w: number; h: number; crop: TLShapeCrop | null }>