@tldraw/tlschema 4.6.0-next.20de11b7e238 → 4.6.0-next.241e87d4700a

package/dist-cjs/index.d.ts

@@ -247,7 +247,7 @@ export declare const assetIdValidator: T.Validator<TLAssetId>;
  * // Migration is applied automatically when loading old documents
  * const migratedStore = migrator.migrateStoreSnapshot({
  *   schema: oldSchema,
- *   store: oldStoreSnapshot
+ *   store: oldStoreSnapshot,
  * })
  * ```
  *
@@ -256,50 +256,11 @@ export declare const assetIdValidator: T.Validator<TLAssetId>;
 export declare const assetMigrations: MigrationSequence;
 
 /**
- * Record type definition for TLAsset with validation and default properties.
- * Configures assets as document-scoped records that persist across sessions.
- *
- * @example
- * ```ts
- * // Create a new asset record
- * const assetRecord = AssetRecordType.create({
- *   id: 'asset:image123',
- *   type: 'image',
- *   props: {
- *     src: 'https://example.com/image.jpg',
- *     w: 800,
- *     h: 600,
- *     mimeType: 'image/jpeg',
- *     isAnimated: false
- *   }
- * })
- *
- * // Store the asset
- * store.put([assetRecord])
- * ```
+ * Record type definition for default TLAsset records with document scope and default metadata.
  *
  * @public
  */
-export declare const AssetRecordType: RecordType<TLAsset, "props" | "type">;
-
-/**
- * Validator for TLAsset records that ensures runtime type safety.
- * Uses a discriminated union based on the 'type' field to validate different asset types.
- *
- * @example
- * ```ts
- * // Validation happens automatically when assets are stored
- * try {
- *   const validatedAsset = assetValidator.validate(assetData)
- *   store.put([validatedAsset])
- * } catch (error) {
- *   console.error('Asset validation failed:', error.message)
- * }
- * ```
- *
- * @public
- */
-export declare const assetValidator: T.Validator<TLAsset>;
+export declare const AssetRecordType: RecordType<TLAsset<"bookmark" | "image" | "video">, "props" | "type">;
 
 /**
  * Utilities for encoding and decoding points using base64 and Float16 encoding.
@@ -384,6 +345,27 @@ export declare class b64Vecs {
  */
 export declare const bindingIdValidator: T.Validator<TLBindingId>;
 
+/**
+ * Migration sequence for bookmark assets. Handles the evolution of bookmark asset
+ * data structure over time, ensuring backward and forward compatibility.
+ *
+ * The migration sequence includes:
+ * 1. **MakeUrlsValid** (v1): Validates and cleans up src URLs, setting invalid URLs to empty string
+ * 2. **AddFavicon** (v2): Adds the favicon property and validates it, setting invalid favicons to empty string
+ *
+ * @public
+ */
+export declare const bookmarkAssetMigrations: MigrationSequence;
+
+/** @public */
+export declare const bookmarkAssetProps: {
+    description: T.Validator<string>;
+    favicon: T.Validator<string>;
+    image: T.Validator<string>;
+    src: T.Validator<null | string>;
+    title: T.Validator<string>;
+};
+
 /**
  * Migration sequence for bookmark shape properties across different schema versions.
  * Handles backwards compatibility when bookmark shape structure changes.
@@ -497,13 +479,50 @@ export declare function compressLegacySegments(segments: {
     type: 'free' | 'straight';
 }[]): TLDrawShapeSegment[];
 
+/**
+ * Creates properly formatted migration IDs for asset properties.
+ *
+ * @example
+ * ```ts
+ * const assetPropsVersions = createAssetPropsMigrationIds('file', {
+ *   AddFoo: 1,
+ *   RenameBar: 2,
+ * })
+ * // => { AddFoo: 'com.tldraw.asset.file/1', RenameBar: 'com.tldraw.asset.file/2' }
+ * ```
+ *
+ * @public
+ */
+export declare function createAssetPropsMigrationIds<S extends string, T extends Record<string, number>>(assetType: S, ids: T): {
+    [k in keyof T]: `com.tldraw.asset.${S}/${T[k]}`;
+};
+
+/**
+ * Creates a migration sequence for asset properties.
+ *
+ * @example
+ * ```ts
+ * const migrations = createAssetPropsMigrationSequence({
+ *   sequence: [
+ *     { id: 'com.myapp.asset.custom/1', up: (props) => { props.newField = '' } },
+ *   ],
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function createAssetPropsMigrationSequence(migrations: TLPropsMigrations): TLPropsMigrations;
+
+/* Excluded from this release type: createAssetRecordType */
+
 /**
  * Creates a validator for a specific asset record type. This factory function generates
  * a complete validator that validates the entire asset record structure including the
  * base properties (id, typeName, type, meta) and the type-specific props.
  *
  * @param type - The asset type identifier (e.g., 'image', 'video', 'bookmark')
- * @param props - The validator for the asset's type-specific properties
+ * @param props - A validator or per-key validator record for the asset's type-specific properties
+ * @param meta - An optional per-key validator record for the asset's meta properties
  * @returns A complete validator for the asset record type
  *
  * @example
@@ -518,43 +537,28 @@ export declare function compressLegacySegments(segments: {
  *   description?: string
  * }>
  *
- * // Create validator for the custom asset
- * const customAssetValidator = createAssetValidator('custom', T.object({
+ * // Create validator using a per-key record (recommended)
+ * const customAssetValidator = createAssetValidator('custom', {
  *   url: T.string,
  *   title: T.string,
  *   description: T.string.optional()
- * }))
- *
- * // Use the validator
- * const assetData = {
- *   id: 'asset:custom123',
- *   typeName: 'asset' as const,
- *   type: 'custom' as const,
- *   props: {
- *     url: 'https://example.com',
- *     title: 'My Custom Asset'
- *   },
- *   meta: {}
- * }
+ * })
  *
- * const validatedAsset = customAssetValidator.validate(assetData)
+ * // Or using a T.object validator
+ * const customAssetValidator2 = createAssetValidator('custom', T.object({
+ *   url: T.string,
+ *   title: T.string,
+ *   description: T.string.optional()
+ * }))
  * ```
  *
  * @public
  */
-export declare function createAssetValidator<Type extends string, Props extends JsonObject>(type: Type, props: T.Validator<Props>): T.ObjectValidator<Expand<    { [P in "id" | "meta" | "typeName" | (undefined extends Props ? never : "props") | (undefined extends Type ? never : "type")]: {
-id: TLAssetId;
-meta: JsonObject;
-props: Props;
-type: Type;
-typeName: "asset";
-}[P]; } & { [P in (undefined extends Props ? "props" : never) | (undefined extends Type ? "type" : never)]?: {
-id: TLAssetId;
-meta: JsonObject;
-props: Props;
-type: Type;
-typeName: "asset";
-}[P] | undefined; }>>;
+export declare function createAssetValidator<Type extends string, Props extends JsonObject, Meta extends JsonObject = JsonObject>(type: Type, props?: {
+    [K in keyof Props]: T.Validatable<Props[K]>;
+} | T.Validator<Props>, meta?: {
+    [K in keyof Meta]: T.Validatable<Meta[K]>;
+}): T.ObjectValidator<Expand<    { [P in "id" | "meta" | "typeName" | (undefined extends Props ? never : "props") | (undefined extends Type ? never : "type")]: TLBaseAsset<Type, Props>[P]; } & { [P in (undefined extends Props ? "props" : never) | (undefined extends Type ? "type" : never)]?: TLBaseAsset<Type, Props>[P] | undefined; }>>;
 
 /**
  * Creates a new TLBindingId with proper formatting.
@@ -996,12 +1000,13 @@ export declare function createShapeValidator<Type extends string, Props extends
  * validation, and migration sequences for all record types in a tldraw application.
  *
  * The schema includes all core record types (pages, cameras, instances, etc.) plus the
- * shape, binding, and custom record types you specify. Style properties are automatically
- * collected from all shapes to ensure consistency across the application.
+ * shape, binding, asset, and custom record types you specify. Style properties are
+ * automatically collected from all shapes to ensure consistency across the application.
  *
  * @param options - Configuration options for the schema
  *   - shapes - Shape schema configurations. Defaults to defaultShapeSchemas if not provided
  *   - bindings - Binding schema configurations. Defaults to defaultBindingSchemas if not provided
+ *   - assets - Asset schema configurations. Defaults to defaultAssetSchemas if not provided
  *   - user - Custom user record configuration with meta validators and migrations
  *   - records - Custom record type configurations. These are additional record types beyond
  *     the built-in shapes, bindings, assets, etc.
@@ -1011,10 +1016,15 @@ export declare function createShapeValidator<Type extends string, Props extends
  * @public
  * @example
  * ```ts
- * import { createTLSchema, defaultShapeSchemas, defaultBindingSchemas } from '@tldraw/tlschema'
+ * import {
+ *   createTLSchema,
+ *   defaultShapeSchemas,
+ *   defaultBindingSchemas,
+ *   defaultAssetSchemas,
+ * } from '@tldraw/tlschema'
  * import { Store } from '@tldraw/store'
  *
- * // Create schema with all default shapes and bindings
+ * // Create schema with all default shapes, bindings, and assets
  * const schema = createTLSchema()
  *
  * // Create schema with custom shapes added
@@ -1026,6 +1036,8 @@ export declare function createShapeValidator<Type extends string, Props extends
  *       migrations: myCustomShapeMigrations,
  *     },
  *   },
+ *   bindings: defaultBindingSchemas,
+ *   assets: defaultAssetSchemas,
  * })
  *
  * // Create schema with custom user metadata
@@ -1062,7 +1074,8 @@ export declare function createShapeValidator<Type extends string, Props extends
  * })
  * ```
  */
-export declare function createTLSchema({ shapes, bindings, user, records, migrations }?: {
+export declare function createTLSchema({ shapes, bindings, assets, user, records, migrations }?: {
+    assets?: Record<string, SchemaPropsInfo>;
     bindings?: Record<string, SchemaPropsInfo>;
     migrations?: readonly MigrationSequence[];
     records?: Record<string, CustomRecordInfo>;
@@ -1164,6 +1177,57 @@ export declare interface CustomRecordInfo {
     createDefaultProperties?: () => Record<string, unknown>;
 }
 
+/**
+ * Default asset schema configurations for all built-in tldraw asset types.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultAssetSchemas } from '@tldraw/tlschema'
+ *
+ * const schema = createTLSchema({
+ *   assets: defaultAssetSchemas,
+ * })
+ * ```
+ */
+export declare const defaultAssetSchemas: {
+    bookmark: {
+        migrations: MigrationSequence;
+        props: {
+            description: T.Validator<string>;
+            favicon: T.Validator<string>;
+            image: T.Validator<string>;
+            src: T.Validator<null | string>;
+            title: T.Validator<string>;
+        };
+    };
+    image: {
+        migrations: MigrationSequence;
+        props: {
+            fileSize: T.Validator<number | undefined>;
+            h: T.Validator<number>;
+            isAnimated: T.Validator<boolean>;
+            mimeType: T.Validator<null | string>;
+            name: T.Validator<string>;
+            pixelRatio: T.Validator<number | undefined>;
+            src: T.Validator<null | string>;
+            w: T.Validator<number>;
+        };
+    };
+    video: {
+        migrations: MigrationSequence;
+        props: {
+            fileSize: T.Validator<number | undefined>;
+            h: T.Validator<number>;
+            isAnimated: T.Validator<boolean>;
+            mimeType: T.Validator<null | string>;
+            name: T.Validator<string>;
+            src: T.Validator<null | string>;
+            w: T.Validator<number>;
+        };
+    };
+};
+
 /**
  * Default binding schema configurations for all built-in tldraw binding types.
  * Bindings represent relationships between shapes, such as arrows connected to shapes.
@@ -1201,78 +1265,9 @@ export declare const defaultBindingSchemas: {
 };
 
 /**
- * Array of default color names available in tldraw's color palette.
- * These colors form the basis for the default color style system and are available
- * in both light and dark theme variants.
- *
- * @example
- * ```ts
- * import { defaultColorNames } from '@tldraw/tlschema'
- *
- * // Create a color picker with all default colors
- * const colorOptions = defaultColorNames.map(color => ({
- *   name: color,
- *   value: color
- * }))
- * ```
- *
  * @public
  */
-export declare const defaultColorNames: readonly ["black", "grey", "light-violet", "violet", "blue", "light-blue", "yellow", "orange", "green", "light-green", "light-red", "red", "white"];
-
-/**
- * Default color style property used by tldraw shapes for their primary color.
- * This style prop allows shapes to use any of the default color names and
- * automatically saves the last used value for new shapes.
- *
- * @example
- * ```ts
- * import { DefaultColorStyle } from '@tldraw/tlschema'
- *
- * // Use in shape props definition
- * interface MyShapeProps {
- *   color: typeof DefaultColorStyle
- *   // other props...
- * }
- *
- * // Set color on a shape
- * const shape = {
- *   // ... other properties
- *   props: {
- *     color: 'red' as const,
- *     // ... other props
- *   }
- * }
- * ```
- *
- * @public
- */
-export declare const DefaultColorStyle: EnumStyleProp<"black" | "blue" | "green" | "grey" | "light-blue" | "light-green" | "light-red" | "light-violet" | "orange" | "red" | "violet" | "white" | "yellow">;
-
-/**
- * Complete color palette containing both light and dark theme definitions.
- * This object provides the full color system used by tldraw's default themes,
- * including all color variants and theme-specific adjustments.
- *
- * @example
- * ```ts
- * import { DefaultColorThemePalette } from '@tldraw/tlschema'
- *
- * // Get the dark theme colors
- * const darkTheme = DefaultColorThemePalette.darkMode
- * const redColor = darkTheme.red.solid // '#e03131'
- *
- * // Access light theme colors
- * const lightTheme = DefaultColorThemePalette.lightMode
- * const blueColor = lightTheme.blue.fill // '#4465e9'
- * ```
- *
- * @public
- */
-export declare const DefaultColorThemePalette: {
-    darkMode: TLDefaultColorTheme;
-    lightMode: TLDefaultColorTheme;
-};
+export declare const DefaultColorStyle: EnumStyleProp<TLDefaultColorStyle>;
 
 /**
  * Default dash style property used by tldraw shapes for line styling.
@@ -1306,7 +1301,7 @@ export declare const DefaultColorThemePalette: {
  *
  * @public
  */
-export declare const DefaultDashStyle: EnumStyleProp<"dashed" | "dotted" | "draw" | "solid">;
+export declare const DefaultDashStyle: EnumStyleProp<"dashed" | "dotted" | "draw" | "none" | "solid">;
 
 /**
  * Default fill style property used by tldraw shapes for interior styling.
@@ -1438,36 +1433,6 @@ export declare const DefaultFontStyle: EnumStyleProp<"draw" | "mono" | "sans" |
  */
 export declare const DefaultHorizontalAlignStyle: EnumStyleProp<"end-legacy" | "end" | "middle-legacy" | "middle" | "start-legacy" | "start">;
 
-/**
- * Default label color style property used for text labels on shapes.
- * This is separate from the main color style to allow different colors
- * for shape fills/strokes versus their text labels.
- *
- * @example
- * ```ts
- * import { DefaultLabelColorStyle } from '@tldraw/tlschema'
- *
- * // Use in shape props definition
- * interface MyShapeProps {
- *   labelColor: typeof DefaultLabelColorStyle
- *   // other props...
- * }
- *
- * // Create a shape with different fill and label colors
- * const shape = {
- *   // ... other properties
- *   props: {
- *     color: 'blue' as const,
- *     labelColor: 'white' as const,
- *     // ... other props
- *   }
- * }
- * ```
- *
- * @public
- */
-export declare const DefaultLabelColorStyle: EnumStyleProp<"black" | "blue" | "green" | "grey" | "light-blue" | "light-green" | "light-red" | "light-violet" | "orange" | "red" | "violet" | "white" | "yellow">;
-
 /**
  * Default shape schema configurations for all built-in tldraw shape types.
  * Each shape type includes its validation props and migration sequences.
@@ -1758,8 +1723,28 @@ export declare const embedShapeProps: RecordProps<TLEmbedShape>;
  * @public
  */
 export declare class EnumStyleProp<T> extends StyleProp<T> {
-    readonly values: readonly T[];
     /* Excluded from this release type: __constructor */
+    readonly values: T[];
+    /**
+     * Add new values to this enum style prop at runtime. This is useful for extending
+     * the built-in styles with custom values (e.g. adding custom colors). Be sure to
+     * also modify the associated types.
+     *
+     * @param newValues - The new values to add.
+     *
+     * @public
+     */
+    addValues(...newValues: T[]): void;
+    /**
+     * Remove values from this enum style prop at runtime. This is useful for narrowing
+     * the built-in styles with custom values (e.g. adding custom colors). Be sure to
+     * also modify the associated types.
+     *
+     * @param valuesToRemove - The values to remove.
+     *
+     * @public
+     */
+    removeValues(...valuesToRemove: T[]): void;
 }
 
 /**
@@ -1841,62 +1826,6 @@ export declare const geoShapeMigrations: TLPropsMigrations;
  */
 export declare const geoShapeProps: RecordProps<TLGeoShape>;
 
-/**
- * Resolves a color style value to its actual CSS color string for a given theme and variant.
- * If the color is not a default theme color, returns the color value as-is.
- *
- * @param theme - The color theme to use for resolution
- * @param color - The color style value to resolve
- * @param variant - Which variant of the color to return (solid, fill, pattern, etc.)
- * @returns The CSS color string for the specified color and variant
- *
- * @example
- * ```ts
- * import { getColorValue, getDefaultColorTheme } from '@tldraw/tlschema'
- *
- * const theme = getDefaultColorTheme({ isDarkMode: false })
- *
- * // Get the solid variant of red
- * const redSolid = getColorValue(theme, 'red', 'solid') // '#e03131'
- *
- * // Get the fill variant of blue
- * const blueFill = getColorValue(theme, 'blue', 'fill') // '#4465e9'
- *
- * // Custom color passes through unchanged
- * const customColor = getColorValue(theme, '#ff0000', 'solid') // '#ff0000'
- * ```
- *
- * @public
- */
-export declare function getColorValue(theme: TLDefaultColorTheme, color: TLDefaultColorStyle, variant: keyof TLDefaultColorThemeColor): string;
-
-/**
- * Returns the appropriate default color theme based on the dark mode preference.
- *
- * @param opts - Configuration options
- *   - isDarkMode - Whether to return the dark theme (true) or light theme (false)
- * @returns The corresponding TLDefaultColorTheme (light or dark)
- *
- * @example
- * ```ts
- * import { getDefaultColorTheme } from '@tldraw/tlschema'
- *
- * // Get light theme
- * const lightTheme = getDefaultColorTheme({ isDarkMode: false })
- *
- * // Get dark theme
- * const darkTheme = getDefaultColorTheme({ isDarkMode: true })
- *
- * // Use with editor
- * const theme = getDefaultColorTheme({ isDarkMode: window.matchMedia('(prefers-color-scheme: dark)').matches })
- * ```
- *
- * @public
- */
-export declare function getDefaultColorTheme(opts: {
-    isDarkMode: boolean;
-}): TLDefaultColorTheme;
-
 /**
  * Gets the default translation locale based on the user's browser language preferences.
  *
@@ -2062,6 +1991,35 @@ export declare const highlightShapeProps: RecordProps<TLHighlightShape>;
  */
 export declare function idValidator<Id extends RecordId<UnknownRecord>>(prefix: Id['__type__']['typeName']): T.Validator<Id>;
 
+/**
+ * Migration sequence for image assets. Handles the evolution of the image asset schema
+ * over time, providing both forward (up) and backward (down) migration functions to
+ * maintain compatibility across different versions of the tldraw data model.
+ *
+ * The sequence includes migrations for:
+ * - Adding the `isAnimated` property to track animated images
+ * - Renaming `width`/`height` properties to shorter `w`/`h` names
+ * - Ensuring URLs are valid format
+ * - Adding file size tracking
+ * - Making file size optional
+ *
+ *
+ * @public
+ */
+export declare const imageAssetMigrations: MigrationSequence;
+
+/** @public */
+export declare const imageAssetProps: {
+    fileSize: T.Validator<number | undefined>;
+    h: T.Validator<number>;
+    isAnimated: T.Validator<boolean>;
+    mimeType: T.Validator<null | string>;
+    name: T.Validator<string>;
+    pixelRatio: T.Validator<number | undefined>;
+    src: T.Validator<null | string>;
+    w: T.Validator<number>;
+};
+
 /**
  * Validator for image shape crop data. Defines the structure for cropping an image,
  * specifying the visible region within the original image bounds.
@@ -2267,6 +2225,8 @@ export declare function isCustomRecordId(typeName: string, id?: string): boolean
  */
 export declare function isDocument(record?: UnknownRecord): record is TLDocument;
 
+/* Excluded from this release type: isFontEntry */
+
 /**
  * Type guard to check if a string is a valid TLPageId.
  *
@@ -2715,6 +2675,31 @@ export declare type RecordPropsType<Config extends Record<string, T.Validatable<
     [K in keyof Config]: T.TypeOf<Config[K]>;
 }>;
 
+/**
+ * Scan theme definitions and sync color registrations to match.
+ * A color entry is any key in `TLThemeColors` whose value is an object
+ * (i.e. a {@link TLDefaultColor}), as opposed to utility strings like
+ * `background` or `text`.
+ *
+ * Colors present in themes but not yet registered will be added.
+ * Colors currently registered but absent from all themes will be removed.
+ *
+ * @public
+ */
+export declare function registerColorsFromThemes(definitions: TLThemes): void;
+
+/**
+ * Scan theme definitions and sync font registrations to match.
+ * A font entry is any key in `TLThemeFonts` whose value is a {@link TLThemeFont}
+ * object (i.e. has a `fontFamily` property).
+ *
+ * Fonts present in themes but not yet registered will be added.
+ * Fonts currently registered but absent from all themes will be removed.
+ *
+ * @public
+ */
+export declare function registerFontsFromThemes(definitions: TLThemes): void;
+
 /**
  * Validator for TLRichText objects that ensures they have the correct structure
  * for document-based rich text content. Validates a document with a type field
@@ -2762,7 +2747,7 @@ export declare const rootBindingMigrations: MigrationSequence;
 export declare const rootShapeMigrations: MigrationSequence;
 
 /**
- * Configuration information for a schema type (shape or binding), including its properties,
+ * Configuration information for a schema type (shape, binding, or asset), including its properties,
  * metadata, and migration sequences for data evolution over time.
  *
  * @public
@@ -2786,11 +2771,11 @@ export declare interface SchemaPropsInfo {
      */
     migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
     /**
-     * Validation schema for the shape or binding properties. Maps property names to their validators.
+     * Validation schema for the shape, binding, or asset properties.
      */
     props?: Record<string, StoreValidator<any>>;
     /**
-     * Validation schema for metadata fields. Maps metadata field names to their validators.
+     * Validation schema for metadata fields.
      */
     meta?: Record<string, StoreValidator<any>>;
 }
@@ -3321,29 +3306,29 @@ export declare interface TLArrowShapeProps {
 }
 
 /**
- * Union type representing all possible asset types in tldraw.
- * Assets represent external resources like images, videos, or bookmarks that can be referenced by shapes.
+ * The set of all assets that are available in the editor.
+ *
+ * This is the primary asset type used throughout tldraw. It includes both the
+ * built-in default assets and any custom assets registered via
+ * {@link TLGlobalAssetPropsMap} augmentation.
+ *
+ * You can use this type without a type argument to work with any asset, or pass
+ * a specific asset type string (e.g., `'image'`, `'video'`, `'bookmark'`) to
+ * narrow down to that specific asset type.
  *
  * @example
  * ```ts
- * const imageAsset: TLAsset = {
- *   id: 'asset:image123',
- *   typeName: 'asset',
- *   type: 'image',
- *   props: {
- *     src: 'https://example.com/image.jpg',
- *     w: 800,
- *     h: 600,
- *     mimeType: 'image/jpeg',
- *     isAnimated: false
- *   },
- *   meta: {}
+ * // Register a custom asset type
+ * declare module '@tldraw/tlschema' {
+ *   interface TLGlobalAssetPropsMap {
+ *     file: { name: string; size: number; mimeType: string; src: string | null }
+ *   }
  * }
  * ```
  *
  * @public
  */
-export declare type TLAsset = TLBookmarkAsset | TLImageAsset | TLVideoAsset;
+export declare type TLAsset<K extends keyof TLIndexedAssets = keyof TLIndexedAssets> = TLIndexedAssets[K];
 
 /**
  * Context information provided when resolving asset URLs, containing details about
@@ -3397,27 +3382,15 @@ export declare interface TLAssetContext {
 
 /**
  * Branded string type for asset record identifiers.
- * Prevents mixing asset IDs with other types of record IDs at compile time.
+ * Prevents mixing asset IDs with other record IDs at compile time.
  *
  * @example
  * ```ts
- * import { createAssetId } from '@tldraw/tlschema'
- *
- * // Create a new asset ID
- * const assetId: TLAssetId = createAssetId()
- *
- * // Use in asset records
- * const asset: TLAsset = {
- *   id: assetId,
- *   // ... other properties
- * }
- *
- * // Reference in shapes
- * const imageShape: TLImageShape = {
+ * const imageShape = {
+ *   type: 'image',
  *   props: {
- *     assetId: assetId,
- *     // ... other properties
- *   }
+ *     assetId: 'asset:image123' as TLAssetId,
+ *   },
  * }
  * ```
  *
@@ -3436,8 +3409,8 @@ export declare type TLAssetId = RecordId<TLBaseAsset<any, any>>;
  *   id: 'asset:image123',
  *   type: 'image',
  *   props: {
- *     w: 800 // Only updating width
- *   }
+ *     w: 800, // Only updating width
+ *   },
  * }
  *
  * // Use in asset updates
@@ -3459,20 +3432,12 @@ export declare type TLAssetPartial<T extends TLAsset = TLAsset> = T extends T ?
  *
  * @example
  * ```ts
- * // Function that works with any asset-based shape
  * function handleAssetShape(shape: TLAssetShape) {
  *   const assetId = shape.props.assetId
- *   if (assetId) {
- *     const asset = editor.getAsset(assetId)
- *     // Handle the asset...
- *   }
+ *   if (!assetId) return
+ *   const asset = editor.getAsset(assetId)
+ *   // Handle the asset...
  * }
- *
- * // Use with image or video shapes
- * const imageShape: TLImageShape = { props: { assetId: 'asset:img1' } }
- * const videoShape: TLVideoShape = { props: { assetId: 'asset:vid1' } }
- * handleAssetShape(imageShape) // Works
- * handleAssetShape(videoShape) // Works
  * ```
  *
  * @public
@@ -4067,6 +4032,31 @@ export declare type TLCursorType = SetValue<typeof TL_CURSOR_TYPES>;
  */
 export declare type TLCustomRecord = TLIndexedRecords[keyof TLIndexedRecords];
 
+/**
+ * The default set of asset types that are available in the editor.
+ *
+ * @example
+ * ```ts
+ * const imageAsset: TLDefaultAsset = {
+ *   id: 'asset:image123',
+ *   typeName: 'asset',
+ *   type: 'image',
+ *   props: {
+ *     src: 'https://example.com/image.jpg',
+ *     w: 800,
+ *     h: 600,
+ *     mimeType: 'image/jpeg',
+ *     isAnimated: false,
+ *     name: 'image.jpg',
+ *   },
+ *   meta: {},
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type TLDefaultAsset = TLBookmarkAsset | TLImageAsset | TLVideoAsset;
+
 /**
  * The default set of bindings that are available in the editor.
  * Currently includes only arrow bindings, but can be extended with custom bindings.
@@ -4093,56 +4083,6 @@ export declare type TLCustomRecord = TLIndexedRecords[keyof TLIndexedRecords];
  */
 export declare type TLDefaultBinding = TLArrowBinding;
 
-/**
- * Type representing a default color style value.
- * This is a union type of all available default color names.
- *
- * @example
- * ```ts
- * import { TLDefaultColorStyle } from '@tldraw/tlschema'
- *
- * // Valid color values
- * const redColor: TLDefaultColorStyle = 'red'
- * const blueColor: TLDefaultColorStyle = 'blue'
- *
- * // Type guard usage
- * function isValidColor(color: string): color is TLDefaultColorStyle {
- *   return ['black', 'red', 'blue'].includes(color as TLDefaultColorStyle)
- * }
- * ```
- *
- * @public
- */
-export declare type TLDefaultColorStyle = T.TypeOf<typeof DefaultColorStyle>;
-
-/**
- * Complete color theme definition containing all colors and their variants
- * for either light or dark mode. Includes base theme properties and all
- * default colors with their respective color variants.
- *
- * @example
- * ```ts
- * import { TLDefaultColorTheme } from '@tldraw/tlschema'
- *
- * const customTheme: TLDefaultColorTheme = {
- *   id: 'light',
- *   text: '#000000',
- *   background: '#ffffff',
- *   solid: '#fcfffe',
- *   black: { solid: '#000000', semi: '#cccccc', ... },
- *   // ... other colors
- * }
- * ```
- *
- * @public
- */
-export declare type TLDefaultColorTheme = Expand<{
-    background: string;
-    id: 'dark' | 'light';
-    solid: string;
-    text: string;
-} & Record<(typeof defaultColorNames)[number], TLDefaultColorThemeColor>>;
-
 /**
  * Defines the color variants available for each color in the default theme.
  * Each color has multiple variants for different use cases like fills, strokes,
@@ -4150,9 +4090,9 @@ export declare type TLDefaultColorTheme = Expand<{
  *
  * @example
  * ```ts
- * import { TLDefaultColorThemeColor } from '@tldraw/tlschema'
+ * import { TLDefaultColor } from '@tldraw/tlschema'
  *
- * const blueColor: TLDefaultColorThemeColor = {
+ * const blueColor: TLDefaultColor = {
  *   solid: '#4465e9',
  *   semi: '#dce1f8',
  *   pattern: '#6681ee',
@@ -4163,7 +4103,7 @@ export declare type TLDefaultColorTheme = Expand<{
  *
  * @public
  */
-export declare interface TLDefaultColorThemeColor {
+export declare interface TLDefaultColor {
     solid: string;
     semi: string;
     pattern: string;
@@ -4180,6 +4120,16 @@ export declare interface TLDefaultColorThemeColor {
     highlightP3: string;
 }
 
+/**
+ * The names of all available shape colors, derived from {@link TLThemeDefaultColors}.
+ * Extend {@link TLThemeDefaultColors} to add custom color names.
+ *
+ * @public
+ */
+export declare type TLDefaultColorStyle = {
+    [K in keyof TLThemeDefaultColors]: TLThemeDefaultColors[K] extends TLDefaultColor ? K : never;
+}[keyof TLThemeDefaultColors] & string;
+
 /**
  * Type representing a default dash style value.
  * This is a union type of all available dash style options.
@@ -4228,8 +4178,8 @@ export declare type TLDefaultDashStyle = T.TypeOf<typeof DefaultDashStyle>;
 export declare type TLDefaultFillStyle = T.TypeOf<typeof DefaultFillStyle>;
 
 /**
- * Type representing a default font style value.
- * This is a union type of all available font style options.
+ * The names of all available font styles, derived from {@link TLThemeFonts}.
+ * Extend {@link TLThemeFonts} to add custom font names.
  *
  * @example
  * ```ts
@@ -4249,7 +4199,7 @@ export declare type TLDefaultFillStyle = T.TypeOf<typeof DefaultFillStyle>;
  *
  * @public
  */
-export declare type TLDefaultFontStyle = T.TypeOf<typeof DefaultFontStyle>;
+export declare type TLDefaultFontStyle = keyof TLThemeFonts & string;
 
 /**
  * Type representing a default horizontal alignment style value.
@@ -4561,6 +4511,72 @@ export declare interface TLEmbedShapeProps {
     url: string;
 }
 
+/**
+ * A font face that can be used in the editor. The properties of this are largely the same as the
+ * ones in the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face | css `@font-face` rule}.
+ * @public
+ */
+export declare interface TLFontFace {
+    /**
+     * How this font can be referred to in CSS.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family | `font-family`}.
+     */
+    readonly family: string;
+    /**
+     * The source of the font. This
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`}.
+     */
+    readonly src: TLFontFaceSource;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override | `ascent-override`}.
+     */
+    readonly ascentOverride?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override | `descent-override`}.
+     */
+    readonly descentOverride?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch | `font-stretch`}.
+     */
+    readonly stretch?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style | `font-style`}.
+     */
+    readonly style?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight | `font-weight`}.
+     */
+    readonly weight?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings | `font-feature-settings`}.
+     */
+    readonly featureSettings?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override | `line-gap-override`}.
+     */
+    readonly lineGapOverride?: string;
+    /**
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range | `unicode-range`}.
+     */
+    readonly unicodeRange?: string;
+}
+
+/**
+ * Represents the `src` property of a {@link TLFontFace}.
+ * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`} for details of the properties here.
+ * @public
+ */
+export declare interface TLFontFaceSource {
+    /**
+     * A URL from which to load the font. If the value here is a key in
+     * {@link tldraw#TLEditorAssetUrls.fonts}, the value from there will be used instead.
+     */
+    url: string;
+    format?: string;
+    tech?: string;
+}
+
 /**
  * A frame shape provides a container for organizing and grouping other shapes.
  * Frames can be used to create sections, organize content, or define specific areas.
@@ -4693,6 +4709,10 @@ export declare interface TLGeoShapeProps {
     richText: TLRichText;
 }
 
+/** @public */
+export declare interface TLGlobalAssetPropsMap {
+}
+
 /** @public */
 export declare interface TLGlobalBindingPropsMap {
 }
@@ -5018,6 +5038,13 @@ export declare interface TLImageShapeProps {
     altText: string;
 }
 
+/** @public */
+export declare type TLIndexedAssets = {
+    [K in keyof TLGlobalAssetPropsMap | TLDefaultAsset['type'] as K extends TLDefaultAsset['type'] ? K extends keyof TLGlobalAssetPropsMap ? TLGlobalAssetPropsMap[K] extends null | undefined ? never : K : K : K]: K extends TLDefaultAsset['type'] ? K extends keyof TLGlobalAssetPropsMap ? TLBaseAsset<K, TLGlobalAssetPropsMap[K]> : Extract<TLDefaultAsset, {
+        type: K;
+    }> : TLBaseAsset<K, TLGlobalAssetPropsMap[K & keyof TLGlobalAssetPropsMap]>;
+};
+
 /** @public */
 export declare type TLIndexedBindings = {
     [K in keyof TLGlobalBindingPropsMap | TLDefaultBinding['type'] as K extends TLDefaultBinding['type'] ? K extends keyof TLGlobalBindingPropsMap ? TLGlobalBindingPropsMap[K] extends null | undefined ? never : K : K : K]: K extends TLDefaultBinding['type'] ? K extends keyof TLGlobalBindingPropsMap ? TLBaseBinding<K, TLGlobalBindingPropsMap[K]> : Extract<TLDefaultBinding, {
@@ -5415,7 +5442,7 @@ export declare type TLLineShapeSplineStyle = T.TypeOf<typeof LineShapeSplineStyl
  *     labelColor: 'black',
  *     size: 's',
  *     font: 'sans',
- *     fontSizeAdjustment: 2,
+ *     fontSizeAdjustment: 0.85,
  *     align: 'start',
  *     verticalAlign: 'start',
  *     growY: 50,
@@ -5442,7 +5469,7 @@ export declare type TLNoteShape = TLBaseShape<'note', TLNoteShapeProps>;
  *   labelColor: 'black',
  *   size: 'm',
  *   font: 'draw',
- *   fontSizeAdjustment: 0,
+ *   fontSizeAdjustment: null,
  *   align: 'middle',
  *   verticalAlign: 'middle',
  *   growY: 0,
@@ -5461,8 +5488,8 @@ export declare interface TLNoteShapeProps {
     size: TLDefaultSizeStyle;
     /** Font family style for the note text */
     font: TLDefaultFontStyle;
-    /** Adjustment to the base font size (positive increases, negative decreases) */
-    fontSizeAdjustment: number;
+    /** Ratio to scale the base font size when text needs to shrink to fit. Null means needs recomputation, 1 means no adjustment, and values less than 1 indicate shrinkage. */
+    fontSizeAdjustment: null | number;
     /** Horizontal alignment of text within the note */
     align: TLDefaultHorizontalAlignStyle;
     /** Vertical alignment of text within the note */
@@ -5749,6 +5776,25 @@ export declare interface TLPropsMigrations {
  */
 export declare type TLRecord = TLCustomRecord | TLDefaultRecord;
 
+/**
+ * Augment this interface to remove built-in palette colors from themes.
+ * Each key you add will be omitted from {@link TLThemeColors}.
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLRemovedDefaultThemeColors {
+ *     'light-violet': true
+ *     'light-blue': true
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface TLRemovedDefaultThemeColors {
+}
+
 /**
  * Type representing rich text content in tldraw. Rich text follows a document-based
  * structure with a root document containing an array of content blocks (paragraphs,
@@ -6151,6 +6197,190 @@ export declare interface TLTextShapeProps {
     autoSize: boolean;
 }
 
+/**
+ * A theme definition containing shared properties and color/font palettes for
+ * both light and dark modes.
+ *
+ * To remove palette colors from themes, augment {@link TLRemovedDefaultThemeColors}.
+ * UI colors (`text`, `background`, `negativeSpace`, `solid`, `cursor`, `noteBorder`)
+ * are always required.
+ *
+ * @example
+ * ```ts
+ * const myTheme: TLTheme = {
+ *   id: 'custom',
+ *   fontSize: 16,
+ *   lineHeight: 1.35,
+ *   strokeWidth: 2,
+ *   fonts: DEFAULT_THEME.fonts,
+ *   colors: {
+ *     light: { ... },
+ *     dark: { ... },
+ *   },
+ * }
+ * editor.updateTheme(myTheme)
+ * ```
+ *
+ * @public
+ */
+export declare interface TLTheme {
+    /** Unique identifier for this theme. Used as the key in the theme registry. */
+    id: TLThemeId;
+    /** Base font size in pixels. Shape font sizes are derived by multiplying this value. */
+    fontSize: number;
+    /** Base line height multiplier. */
+    lineHeight: number;
+    /** Base stroke width in pixels. Shape stroke widths are derived by multiplying this value. */
+    strokeWidth: number;
+    /** Font definitions. Individual fonts may be absent if removed by a custom theme. */
+    fonts: TLThemeFonts;
+    colors: {
+        dark: TLThemeColors;
+        light: TLThemeColors;
+    };
+}
+
+/**
+ * A color palette for one color mode. UI colors are always required.
+ * Palette colors removed via {@link TLRemovedDefaultThemeColors} are omitted.
+ *
+ * @public
+ */
+export declare type TLThemeColors = Pick<TLThemeDefaultColors, TLThemeUiColorKeys> & Omit<TLThemeDefaultColors, keyof TLRemovedDefaultThemeColors | TLThemeUiColorKeys>;
+
+/**
+ * The color palette for a theme. Contains base UI colors (as strings) and
+ * named shape colors (as {@link TLDefaultColor} objects).
+ *
+ * Extend this interface via module augmentation to add custom colors:
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemeColors {
+ *     pink: TLDefaultColor
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface TLThemeDefaultColors {
+    text: string;
+    background: string;
+    negativeSpace: string;
+    solid: string;
+    cursor: string;
+    noteBorder: string;
+    black: TLDefaultColor;
+    grey: TLDefaultColor;
+    'light-violet': TLDefaultColor;
+    violet: TLDefaultColor;
+    blue: TLDefaultColor;
+    'light-blue': TLDefaultColor;
+    yellow: TLDefaultColor;
+    orange: TLDefaultColor;
+    green: TLDefaultColor;
+    'light-green': TLDefaultColor;
+    'light-red': TLDefaultColor;
+    red: TLDefaultColor;
+    white: TLDefaultColor;
+}
+
+/**
+ * A font definition within a theme. Maps a font style name to a CSS font-family
+ * declaration and optional font face descriptors for loading.
+ *
+ * @example
+ * ```ts
+ * import { TLThemeFont } from '@tldraw/tlschema'
+ *
+ * const customSans: TLThemeFont = {
+ *   fontFamily: "'Inter', sans-serif",
+ *   faces: [
+ *     { family: 'Inter', src: { url: 'https://example.com/Inter-Regular.woff2', format: 'woff2' }, weight: 'normal' },
+ *     { family: 'Inter', src: { url: 'https://example.com/Inter-Bold.woff2', format: 'woff2' }, weight: 'bold' },
+ *   ]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface TLThemeFont {
+    /** CSS font-family declaration, e.g. `"'Inter', sans-serif"` */
+    fontFamily: string;
+    /** Font face definitions for loading. Omit for system fonts that don't need loading. */
+    faces?: TLFontFace[];
+    /**
+     * Icon for the style panel. Accepts a string icon ID (resolved via `assetUrls.icons`)
+     * or a React element (`TLUiIconJsx`). Defaults to the built-in icon for known fonts,
+     * or `'font-draw'` for custom fonts.
+     */
+    icon?: unknown;
+}
+
+/**
+ * The font palette for a theme. Contains named font definitions mapping font style
+ * names to their CSS font-family strings and font face descriptors.
+ *
+ * Extend this interface via module augmentation to add custom fonts:
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemeFonts {
+ *     cursive: TLThemeFont
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface TLThemeFonts {
+    draw: TLThemeFont;
+    sans: TLThemeFont;
+    serif: TLThemeFont;
+    mono: TLThemeFont;
+}
+
+/** @public */
+export declare type TLThemeId = keyof TLThemes & string;
+
+/**
+ * A registry of available themes. Extend this interface via module
+ * augmentation to register custom themes for type-safe theme IDs.
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemes {
+ *     corporate: TLTheme
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface TLThemes {
+    default: TLTheme;
+}
+
+/**
+ * Keys in {@link TLThemeDefaultColors} that are required UI infrastructure colors
+ * and cannot be removed via {@link TLRemovedDefaultThemeColors}.
+ *
+ * @public
+ */
+export declare type TLThemeUiColorKeys = 'background' | 'cursor' | 'negativeSpace' | 'noteBorder' | 'solid' | 'text';
+
+/**
+ * A type for an asset that is available in the editor but whose type is
+ * unknown—either one of the editor's default assets or else a custom asset.
+ *
+ * @public
+ */
+export declare type TLUnknownAsset = TLBaseAsset<string, object>;
+
 /**
  * A type for a binding that is available in the editor but whose type is
  * unknown—either one of the editor's default bindings or else a custom binding.
@@ -6467,6 +6697,34 @@ export declare interface VecModel {
  */
 export declare const vecModelValidator: T.ObjectValidator<VecModel>;
 
+/**
+ * Migration sequence for video assets that handles schema evolution over time.
+ * This sequence defines how video asset data should be transformed when upgrading
+ * or downgrading between different schema versions. Each migration step handles
+ * specific changes like adding properties, renaming fields, or changing data formats.
+ *
+ * The migrations handle:
+ * - Adding animation detection (isAnimated property)
+ * - Renaming width/height properties to w/h for consistency
+ * - Ensuring URL validity for src properties
+ * - Adding file size tracking
+ * - Making file size optional for backward compatibility
+ *
+ * @public
+ */
+export declare const videoAssetMigrations: MigrationSequence;
+
+/** @public */
+export declare const videoAssetProps: {
+    fileSize: T.Validator<number | undefined>;
+    h: T.Validator<number>;
+    isAnimated: T.Validator<boolean>;
+    mimeType: T.Validator<null | string>;
+    name: T.Validator<string>;
+    src: T.Validator<null | string>;
+    w: T.Validator<number>;
+};
+
 /**
  * Migration sequence for video shape schema evolution. This handles transforming
  * video shape data between different versions as the schema evolves over time.