@tldraw/tlschema 4.5.3 → 4.6.0-canary.00a8c03b5687

package/dist-esm/recordsWithProps.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/recordsWithProps.ts"],
-  "sourcesContent": ["import {\n\tMigration,\n\tMigrationId,\n\tMigrationSequence,\n\tRecordType,\n\tStandaloneDependsOn,\n\tUnknownRecord,\n\tcreateMigrationSequence,\n} from '@tldraw/store'\nimport { MakeUndefinedOptional, assert } from '@tldraw/utils'\nimport { T } from '@tldraw/validate'\nimport { SchemaPropsInfo } from './createTLSchema'\n\n/**\n * Maps a record's property types to their corresponding validators.\n *\n * This utility type takes a record type with a `props` object and creates\n * a mapping where each property key maps to a validator for that property's type.\n * This is used to define validation schemas for record properties.\n *\n * @example\n * ```ts\n * interface MyShape extends TLBaseShape<'custom', { width: number; color: string }> {}\n *\n * // Define validators for the shape properties\n * const myShapeProps: RecordProps<MyShape> = {\n *   width: T.number,\n *   color: T.string\n * }\n * ```\n *\n * @public\n */\nexport type RecordProps<R extends UnknownRecord & { props: object }> = {\n\t[K in keyof R['props']]: T.Validatable<R['props'][K]>\n}\n\n/**\n * Extracts the TypeScript types from a record properties configuration.\n *\n * Takes a configuration object where values are validators and returns the\n * corresponding TypeScript types, with undefined values made optional.\n *\n * @example\n * ```ts\n * const shapePropsConfig = {\n *   width: T.number,\n *   height: T.number,\n *   color: T.optional(T.string)\n * }\n *\n * type ShapeProps = RecordPropsType<typeof shapePropsConfig>\n * // Result: { width: number; height: number; color?: string }\n * ```\n *\n * @public\n */\nexport type RecordPropsType<Config extends Record<string, T.Validatable<any>>> =\n\tMakeUndefinedOptional<{\n\t\t[K in keyof Config]: T.TypeOf<Config[K]>\n\t}>\n\n/**\n * A migration definition for shape or record properties.\n *\n * Defines how to transform record properties when migrating between schema versions.\n * Each migration has an `up` function to upgrade data and an optional `down` function\n * to downgrade data if needed.\n *\n * @example\n * ```ts\n * const addColorMigration: TLPropsMigration = {\n *   id: 'com.myapp.shape.custom/1.0.0',\n *   up: (props) => {\n *     // Add a default color property\n *     return { ...props, color: 'black' }\n *   },\n *   down: (props) => {\n *     // Remove the color property\n *     const { color, ...rest } = props\n *     return rest\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface TLPropsMigration {\n\treadonly id: MigrationId\n\treadonly dependsOn?: MigrationId[]\n\t// eslint-disable-next-line @typescript-eslint/method-signature-style\n\treadonly up: (props: any) => any\n\t/**\n\t * If a down migration was deployed more than a couple of months ago it should be safe to retire it.\n\t * We only really need them to smooth over the transition between versions, and some folks do keep\n\t * browser tabs open for months without refreshing, but at a certain point that kind of behavior is\n\t * on them. Plus anyway recently chrome has started to actually kill tabs that are open for too long\n\t * rather than just suspending them, so if other browsers follow suit maybe it's less of a concern.\n\t *\n\t * @public\n\t */\n\treadonly down?: 'none' | 'retired' | ((props: any) => any)\n}\n\n/**\n * A sequence of property migrations for a record type.\n *\n * Contains an ordered array of migrations that should be applied to transform\n * record properties from one version to another. Migrations can include both\n * property-specific migrations and standalone dependency declarations.\n *\n * @example\n * ```ts\n * const myShapeMigrations: TLPropsMigrations = {\n *   sequence: [\n *     {\n *       id: 'com.myapp.shape.custom/1.0.0',\n *       up: (props) => ({ ...props, version: 1 })\n *     },\n *     {\n *       id: 'com.myapp.shape.custom/2.0.0',\n *       up: (props) => ({ ...props, newFeature: true })\n *     }\n *   ]\n * }\n * ```\n *\n * @public\n */\nexport interface TLPropsMigrations {\n\treadonly sequence: Array<StandaloneDependsOn | TLPropsMigration>\n}\n\n/**\n * Processes property migrations for all record types in a schema.\n *\n * Takes a collection of record configurations and converts their migrations\n * into proper migration sequences that can be used by the store system.\n * Handles different migration formats including legacy migrations.\n *\n * @param typeName - The base type name for the records (e.g., 'shape', 'binding')\n * @param records - Record of type names to their schema configuration\n * @returns Array of processed migration sequences\n *\n * @example\n * ```ts\n * const shapeRecords = {\n *   geo: { props: geoProps, migrations: geoMigrations },\n *   arrow: { props: arrowProps, migrations: arrowMigrations }\n * }\n *\n * const sequences = processPropsMigrations('shape', shapeRecords)\n * ```\n *\n * @internal\n */\nexport function processPropsMigrations<R extends UnknownRecord & { type: string; props: object }>(\n\ttypeName: R['typeName'],\n\trecords: Record<string, SchemaPropsInfo>\n) {\n\tconst result: MigrationSequence[] = []\n\n\tfor (const [subType, { migrations }] of Object.entries(records)) {\n\t\tconst sequenceId = `com.tldraw.${typeName}.${subType}`\n\t\tif (!migrations) {\n\t\t\t// provide empty migrations sequence to allow for future migrations\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: [],\n\t\t\t\t})\n\t\t\t)\n\t\t} else if ('sequenceId' in migrations) {\n\t\t\tassert(\n\t\t\t\tsequenceId === migrations.sequenceId,\n\t\t\t\t`sequenceId mismatch for ${subType} ${RecordType} migrations. Expected '${sequenceId}', got '${migrations.sequenceId}'`\n\t\t\t)\n\t\t\tresult.push(migrations)\n\t\t} else if ('sequence' in migrations) {\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: migrations.sequence.map((m) =>\n\t\t\t\t\t\t'id' in m ? createPropsMigration(typeName, subType, m) : m\n\t\t\t\t\t),\n\t\t\t\t})\n\t\t\t)\n\t\t} else {\n\t\t\t// legacy migrations, will be removed in the future\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: Object.keys(migrations.migrators)\n\t\t\t\t\t\t.map((k) => Number(k))\n\t\t\t\t\t\t.sort((a: number, b: number) => a - b)\n\t\t\t\t\t\t.map(\n\t\t\t\t\t\t\t(version): Migration => ({\n\t\t\t\t\t\t\t\tid: `${sequenceId}/${version}`,\n\t\t\t\t\t\t\t\tscope: 'record',\n\t\t\t\t\t\t\t\tfilter: (r) => r.typeName === typeName && (r as R).type === subType,\n\t\t\t\t\t\t\t\tup: (record: any) => {\n\t\t\t\t\t\t\t\t\tconst result = migrations.migrators[version].up(record)\n\t\t\t\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\t\t\t\treturn result\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\tdown: (record: any) => {\n\t\t\t\t\t\t\t\t\tconst result = migrations.migrators[version].down(record)\n\t\t\t\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\t\t\t\treturn result\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t),\n\t\t\t\t})\n\t\t\t)\n\t\t}\n\t}\n\n\treturn result\n}\n\n/**\n * Creates a store migration from a props migration definition.\n *\n * Converts a high-level property migration into a low-level store migration\n * that can be applied to records. The resulting migration will only affect\n * records of the specified type and subtype.\n *\n * @param typeName - The base type name (e.g., 'shape', 'binding')\n * @param subType - The specific subtype (e.g., 'geo', 'arrow')\n * @param m - The property migration definition\n * @returns A store migration that applies the property transformation\n *\n * @example\n * ```ts\n * const propsMigration: TLPropsMigration = {\n *   id: 'com.myapp.shape.custom/1.0.0',\n *   up: (props) => ({ ...props, color: 'blue' })\n * }\n *\n * const storeMigration = createPropsMigration('shape', 'custom', propsMigration)\n * ```\n *\n * @internal\n */\nexport function createPropsMigration<R extends UnknownRecord & { type: string; props: object }>(\n\ttypeName: R['typeName'],\n\tsubType: R['type'],\n\tm: TLPropsMigration\n): Migration {\n\treturn {\n\t\tid: m.id,\n\t\tdependsOn: m.dependsOn,\n\t\tscope: 'record',\n\t\tfilter: (r) => r.typeName === typeName && (r as R).type === subType,\n\t\tup: (record: any) => {\n\t\t\tconst result = m.up(record.props)\n\t\t\tif (result) {\n\t\t\t\trecord.props = result\n\t\t\t}\n\t\t},\n\t\tdown:\n\t\t\ttypeof m.down === 'function'\n\t\t\t\t? (record: any) => {\n\t\t\t\t\t\tconst result = (m.down as (props: any) => any)(record.props)\n\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\trecord.props = result\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t}\n}\n"],
+  "sourcesContent": ["import {\n\tMigration,\n\tMigrationId,\n\tMigrationSequence,\n\tRecordType,\n\tStandaloneDependsOn,\n\tUnknownRecord,\n\tcreateMigrationSequence,\n} from '@tldraw/store'\nimport { MakeUndefinedOptional, assert } from '@tldraw/utils'\nimport { T } from '@tldraw/validate'\nimport { SchemaPropsInfo } from './createTLSchema'\n\n/**\n * Maps a record's property types to their corresponding validators.\n *\n * This utility type takes a record type with a `props` object and creates\n * a mapping where each property key maps to a validator for that property's type.\n * This is used to define validation schemas for record properties.\n *\n * @example\n * ```ts\n * interface MyShape extends TLBaseShape<'custom', { width: number; color: string }> {}\n *\n * // Define validators for the shape properties\n * const myShapeProps: RecordProps<MyShape> = {\n *   width: T.number,\n *   color: T.string\n * }\n * ```\n *\n * @public\n */\nexport type RecordProps<R extends UnknownRecord & { props: object }> = {\n\t[K in keyof R['props']]: T.Validatable<R['props'][K]>\n}\n\n/**\n * Extracts the TypeScript types from a record properties configuration.\n *\n * Takes a configuration object where values are validators and returns the\n * corresponding TypeScript types, with undefined values made optional.\n *\n * @example\n * ```ts\n * const shapePropsConfig = {\n *   width: T.number,\n *   height: T.number,\n *   color: T.optional(T.string)\n * }\n *\n * type ShapeProps = RecordPropsType<typeof shapePropsConfig>\n * // Result: { width: number; height: number; color?: string }\n * ```\n *\n * @public\n */\nexport type RecordPropsType<Config extends Record<string, T.Validatable<any>>> =\n\tMakeUndefinedOptional<{\n\t\t[K in keyof Config]: T.TypeOf<Config[K]>\n\t}>\n\n/**\n * A migration definition for shape or record properties.\n *\n * Defines how to transform record properties when migrating between schema versions.\n * Each migration has an `up` function to upgrade data and an optional `down` function\n * to downgrade data if needed.\n *\n * @example\n * ```ts\n * const addColorMigration: TLPropsMigration = {\n *   id: 'com.myapp.shape.custom/1.0.0',\n *   up: (props) => {\n *     // Add a default color property\n *     return { ...props, color: 'black' }\n *   },\n *   down: (props) => {\n *     // Remove the color property\n *     const { color, ...rest } = props\n *     return rest\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface TLPropsMigration {\n\treadonly id: MigrationId\n\treadonly dependsOn?: MigrationId[]\n\t// eslint-disable-next-line tldraw/method-signature-style\n\treadonly up: (props: any) => any\n\t/**\n\t * If a down migration was deployed more than a couple of months ago it should be safe to retire it.\n\t * We only really need them to smooth over the transition between versions, and some folks do keep\n\t * browser tabs open for months without refreshing, but at a certain point that kind of behavior is\n\t * on them. Plus anyway recently chrome has started to actually kill tabs that are open for too long\n\t * rather than just suspending them, so if other browsers follow suit maybe it's less of a concern.\n\t *\n\t * @public\n\t */\n\treadonly down?: 'none' | 'retired' | ((props: any) => any)\n}\n\n/**\n * A sequence of property migrations for a record type.\n *\n * Contains an ordered array of migrations that should be applied to transform\n * record properties from one version to another. Migrations can include both\n * property-specific migrations and standalone dependency declarations.\n *\n * @example\n * ```ts\n * const myShapeMigrations: TLPropsMigrations = {\n *   sequence: [\n *     {\n *       id: 'com.myapp.shape.custom/1.0.0',\n *       up: (props) => ({ ...props, version: 1 })\n *     },\n *     {\n *       id: 'com.myapp.shape.custom/2.0.0',\n *       up: (props) => ({ ...props, newFeature: true })\n *     }\n *   ]\n * }\n * ```\n *\n * @public\n */\nexport interface TLPropsMigrations {\n\treadonly sequence: Array<StandaloneDependsOn | TLPropsMigration>\n}\n\n/**\n * Processes property migrations for all record types in a schema.\n *\n * Takes a collection of record configurations and converts their migrations\n * into proper migration sequences that can be used by the store system.\n * Handles different migration formats including legacy migrations.\n *\n * @param typeName - The base type name for the records (e.g., 'shape', 'binding')\n * @param records - Record of type names to their schema configuration\n * @returns Array of processed migration sequences\n *\n * @example\n * ```ts\n * const shapeRecords = {\n *   geo: { props: geoProps, migrations: geoMigrations },\n *   arrow: { props: arrowProps, migrations: arrowMigrations }\n * }\n *\n * const sequences = processPropsMigrations('shape', shapeRecords)\n * ```\n *\n * @internal\n */\nexport function processPropsMigrations<R extends UnknownRecord & { type: string; props: object }>(\n\ttypeName: R['typeName'],\n\trecords: Record<string, SchemaPropsInfo>\n) {\n\tconst result: MigrationSequence[] = []\n\n\tfor (const [subType, { migrations }] of Object.entries(records)) {\n\t\tconst sequenceId = `com.tldraw.${typeName}.${subType}`\n\t\tif (!migrations) {\n\t\t\t// provide empty migrations sequence to allow for future migrations\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: [],\n\t\t\t\t})\n\t\t\t)\n\t\t} else if ('sequenceId' in migrations) {\n\t\t\tassert(\n\t\t\t\tsequenceId === migrations.sequenceId,\n\t\t\t\t`sequenceId mismatch for ${subType} ${RecordType} migrations. Expected '${sequenceId}', got '${migrations.sequenceId}'`\n\t\t\t)\n\t\t\tresult.push(migrations)\n\t\t} else if ('sequence' in migrations) {\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: migrations.sequence.map((m) =>\n\t\t\t\t\t\t'id' in m ? createPropsMigration(typeName, subType, m) : m\n\t\t\t\t\t),\n\t\t\t\t})\n\t\t\t)\n\t\t} else {\n\t\t\t// legacy migrations, will be removed in the future\n\t\t\tresult.push(\n\t\t\t\tcreateMigrationSequence({\n\t\t\t\t\tsequenceId,\n\t\t\t\t\tretroactive: true,\n\t\t\t\t\tsequence: Object.keys(migrations.migrators)\n\t\t\t\t\t\t.map((k) => Number(k))\n\t\t\t\t\t\t.sort((a: number, b: number) => a - b)\n\t\t\t\t\t\t.map(\n\t\t\t\t\t\t\t(version): Migration => ({\n\t\t\t\t\t\t\t\tid: `${sequenceId}/${version}`,\n\t\t\t\t\t\t\t\tscope: 'record',\n\t\t\t\t\t\t\t\tfilter: (r) => r.typeName === typeName && (r as R).type === subType,\n\t\t\t\t\t\t\t\tup: (record: any) => {\n\t\t\t\t\t\t\t\t\tconst result = migrations.migrators[version].up(record)\n\t\t\t\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\t\t\t\treturn result\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\tdown: (record: any) => {\n\t\t\t\t\t\t\t\t\tconst result = migrations.migrators[version].down(record)\n\t\t\t\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\t\t\t\treturn result\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t),\n\t\t\t\t})\n\t\t\t)\n\t\t}\n\t}\n\n\treturn result\n}\n\n/**\n * Creates a store migration from a props migration definition.\n *\n * Converts a high-level property migration into a low-level store migration\n * that can be applied to records. The resulting migration will only affect\n * records of the specified type and subtype.\n *\n * @param typeName - The base type name (e.g., 'shape', 'binding')\n * @param subType - The specific subtype (e.g., 'geo', 'arrow')\n * @param m - The property migration definition\n * @returns A store migration that applies the property transformation\n *\n * @example\n * ```ts\n * const propsMigration: TLPropsMigration = {\n *   id: 'com.myapp.shape.custom/1.0.0',\n *   up: (props) => ({ ...props, color: 'blue' })\n * }\n *\n * const storeMigration = createPropsMigration('shape', 'custom', propsMigration)\n * ```\n *\n * @internal\n */\nexport function createPropsMigration<R extends UnknownRecord & { type: string; props: object }>(\n\ttypeName: R['typeName'],\n\tsubType: R['type'],\n\tm: TLPropsMigration\n): Migration {\n\treturn {\n\t\tid: m.id,\n\t\tdependsOn: m.dependsOn,\n\t\tscope: 'record',\n\t\tfilter: (r) => r.typeName === typeName && (r as R).type === subType,\n\t\tup: (record: any) => {\n\t\t\tconst result = m.up(record.props)\n\t\t\tif (result) {\n\t\t\t\trecord.props = result\n\t\t\t}\n\t\t},\n\t\tdown:\n\t\t\ttypeof m.down === 'function'\n\t\t\t\t? (record: any) => {\n\t\t\t\t\t\tconst result = (m.down as (props: any) => any)(record.props)\n\t\t\t\t\t\tif (result) {\n\t\t\t\t\t\t\trecord.props = result\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t}\n}\n"],
   "mappings": "AAAA;AAAA,EAIC;AAAA,EAGA;AAAA,OACM;AACP,SAAgC,cAAc;AAmJvC,SAAS,uBACf,UACA,SACC;AACD,QAAM,SAA8B,CAAC;AAErC,aAAW,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,OAAO,QAAQ,OAAO,GAAG;AAChE,UAAM,aAAa,cAAc,QAAQ,IAAI,OAAO;AACpD,QAAI,CAAC,YAAY;AAEhB,aAAO;AAAA,QACN,wBAAwB;AAAA,UACvB;AAAA,UACA,aAAa;AAAA,UACb,UAAU,CAAC;AAAA,QACZ,CAAC;AAAA,MACF;AAAA,IACD,WAAW,gBAAgB,YAAY;AACtC;AAAA,QACC,eAAe,WAAW;AAAA,QAC1B,2BAA2B,OAAO,IAAI,UAAU,0BAA0B,UAAU,WAAW,WAAW,UAAU;AAAA,MACrH;AACA,aAAO,KAAK,UAAU;AAAA,IACvB,WAAW,cAAc,YAAY;AACpC,aAAO;AAAA,QACN,wBAAwB;AAAA,UACvB;AAAA,UACA,aAAa;AAAA,UACb,UAAU,WAAW,SAAS;AAAA,YAAI,CAAC,MAClC,QAAQ,IAAI,qBAAqB,UAAU,SAAS,CAAC,IAAI;AAAA,UAC1D;AAAA,QACD,CAAC;AAAA,MACF;AAAA,IACD,OAAO;AAEN,aAAO;AAAA,QACN,wBAAwB;AAAA,UACvB;AAAA,UACA,aAAa;AAAA,UACb,UAAU,OAAO,KAAK,WAAW,SAAS,EACxC,IAAI,CAAC,MAAM,OAAO,CAAC,CAAC,EACpB,KAAK,CAAC,GAAW,MAAc,IAAI,CAAC,EACpC;AAAA,YACA,CAAC,aAAwB;AAAA,cACxB,IAAI,GAAG,UAAU,IAAI,OAAO;AAAA,cAC5B,OAAO;AAAA,cACP,QAAQ,CAAC,MAAM,EAAE,aAAa,YAAa,EAAQ,SAAS;AAAA,cAC5D,IAAI,CAAC,WAAgB;AACpB,sBAAMA,UAAS,WAAW,UAAU,OAAO,EAAE,GAAG,MAAM;AACtD,oBAAIA,SAAQ;AACX,yBAAOA;AAAA,gBACR;AAAA,cACD;AAAA,cACA,MAAM,CAAC,WAAgB;AACtB,sBAAMA,UAAS,WAAW,UAAU,OAAO,EAAE,KAAK,MAAM;AACxD,oBAAIA,SAAQ;AACX,yBAAOA;AAAA,gBACR;AAAA,cACD;AAAA,YACD;AAAA,UACD;AAAA,QACF,CAAC;AAAA,MACF;AAAA,IACD;AAAA,EACD;AAEA,SAAO;AACR;AA0BO,SAAS,qBACf,UACA,SACA,GACY;AACZ,SAAO;AAAA,IACN,IAAI,EAAE;AAAA,IACN,WAAW,EAAE;AAAA,IACb,OAAO;AAAA,IACP,QAAQ,CAAC,MAAM,EAAE,aAAa,YAAa,EAAQ,SAAS;AAAA,IAC5D,IAAI,CAAC,WAAgB;AACpB,YAAM,SAAS,EAAE,GAAG,OAAO,KAAK;AAChC,UAAI,QAAQ;AACX,eAAO,QAAQ;AAAA,MAChB;AAAA,IACD;AAAA,IACA,MACC,OAAO,EAAE,SAAS,aACf,CAAC,WAAgB;AACjB,YAAM,SAAU,EAAE,KAA6B,OAAO,KAAK;AAC3D,UAAI,QAAQ;AACX,eAAO,QAAQ;AAAA,MAChB;AAAA,IACD,IACC;AAAA,EACL;AACD;",
   "names": ["result"]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/tlschema",
   "description": "tldraw infinite canvas SDK (schema).",
-  "version": "4.5.3",
+  "version": "4.6.0-canary.00a8c03b5687",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -35,13 +35,13 @@
     "test-ci": "yarn run -T vitest run --passWithNoTests",
     "test": "yarn run -T vitest --passWithNoTests",
     "test-coverage": "yarn run -T vitest run --coverage --passWithNoTests",
-    "format": "yarn run -T prettier --write --cache \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
+    "format": "yarn run -T oxfmt \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
     "build": "yarn run -T tsx ../../internal/scripts/build-package.ts",
     "build-api": "yarn run -T tsx ../../internal/scripts/build-api.ts",
     "prepack": "yarn run -T tsx ../../internal/scripts/prepack.ts",
     "postpack": "../../internal/scripts/postpack.sh",
     "pack-tarball": "yarn pack",
-    "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
+    "lint": "cd ../.. && yarn run -T oxlint packages/tlschema"
   },
   "devDependencies": {
     "kleur": "^4.1.5",
@@ -50,10 +50,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@tldraw/state": "4.5.3",
-    "@tldraw/store": "4.5.3",
-    "@tldraw/utils": "4.5.3",
-    "@tldraw/validate": "4.5.3"
+    "@tldraw/state": "4.6.0-canary.00a8c03b5687",
+    "@tldraw/store": "4.6.0-canary.00a8c03b5687",
+    "@tldraw/utils": "4.6.0-canary.00a8c03b5687",
+    "@tldraw/validate": "4.6.0-canary.00a8c03b5687"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.2.1",

package/src/createTLSchema.ts

@@ -8,6 +8,11 @@ import { arrowBindingMigrations, arrowBindingProps } from './bindings/TLArrowBin
 import { AssetRecordType, assetMigrations } from './records/TLAsset'
 import { TLBinding, TLDefaultBinding, createBindingRecordType } from './records/TLBinding'
 import { CameraRecordType, cameraMigrations } from './records/TLCamera'
+import {
+	CustomRecordInfo,
+	createCustomRecordType,
+	processCustomRecordMigrations,
+} from './records/TLCustomRecord'
 import { DocumentRecordType, documentMigrations } from './records/TLDocument'
 import { createInstanceRecordType, instanceMigrations } from './records/TLInstance'
 import { PageRecordType, pageMigrations } from './records/TLPage'
@@ -193,12 +198,14 @@ export const defaultBindingSchemas = {
  * 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 and binding types you specify. Style properties are automatically collected from
- * all shapes to ensure consistency across the application.
+ * shape, binding, 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
+ *   - records - Custom record type configurations. These are additional record types beyond
+ *     the built-in shapes, bindings, assets, etc.
  *   - migrations - Additional migration sequences to include in the schema
  * @returns A complete TLSchema ready for use with Store creation
  *
@@ -222,13 +229,19 @@ export const defaultBindingSchemas = {
  *   },
  * })
  *
- * // Create schema with only specific shapes
- * const minimalSchema = createTLSchema({
- *   shapes: {
- *     geo: defaultShapeSchemas.geo,
- *     text: defaultShapeSchemas.text,
+ * // Create schema with custom record types
+ * const schemaWithCustomRecords = createTLSchema({
+ *   records: {
+ *     comment: {
+ *       scope: 'document',
+ *       validator: T.object({
+ *         id: T.string,
+ *         typeName: T.literal('comment'),
+ *         text: T.string,
+ *         shapeId: T.string,
+ *       }),
+ *     },
  *   },
- *   bindings: defaultBindingSchemas,
  * })
  *
  * // Use the schema with a store
@@ -243,10 +256,12 @@ export const defaultBindingSchemas = {
 export function createTLSchema({
 	shapes = defaultShapeSchemas,
 	bindings = defaultBindingSchemas,
+	records = {},
 	migrations,
 }: {
 	shapes?: Record<string, SchemaPropsInfo>
 	bindings?: Record<string, SchemaPropsInfo>
+	records?: Record<string, CustomRecordInfo>
 	migrations?: readonly MigrationSequence[]
 } = {}): TLSchema {
 	const stylesById = new Map<string, StyleProp<unknown>>()
@@ -263,6 +278,30 @@ export function createTLSchema({
 	const BindingRecordType = createBindingRecordType(bindings)
 	const InstanceRecordType = createInstanceRecordType(stylesById)
 
+	// Create RecordTypes for custom records
+	const builtInTypeNames = new Set([
+		'asset',
+		'binding',
+		'camera',
+		'document',
+		'instance',
+		'instance_page_state',
+		'page',
+		'instance_presence',
+		'pointer',
+		'shape',
+		'store',
+	])
+	const customRecordTypes: Record<string, { createId: any }> = {}
+	for (const [typeName, config] of Object.entries(records)) {
+		if (builtInTypeNames.has(typeName)) {
+			throw new Error(
+				`Custom record type name '${typeName}' conflicts with tldraw's built-in record type of that name. Choose a different name instead.`
+			)
+		}
+		customRecordTypes[typeName] = createCustomRecordType(typeName, config)
+	}
+
 	return StoreSchema.create(
 		{
 			asset: AssetRecordType,
@@ -275,6 +314,7 @@ export function createTLSchema({
 			instance_presence: InstancePresenceRecordType,
 			pointer: PointerRecordType,
 			shape: ShapeRecordType,
+			...customRecordTypes,
 		},
 		{
 			migrations: [
@@ -295,6 +335,7 @@ export function createTLSchema({
 
 				...processPropsMigrations<TLShape>('shape', shapes),
 				...processPropsMigrations<TLBinding>('binding', bindings),
+				...processCustomRecordMigrations(records),
 
 				...(migrations ?? []),
 			],

package/src/index.ts

@@ -104,6 +104,14 @@ export {
 	type TLUnknownBinding,
 } from './records/TLBinding'
 export { CameraRecordType, type TLCamera, type TLCameraId } from './records/TLCamera'
+export {
+	createCustomRecordId,
+	createCustomRecordMigrationIds,
+	createCustomRecordMigrationSequence,
+	isCustomRecord,
+	isCustomRecordId,
+	type CustomRecordInfo,
+} from './records/TLCustomRecord'
 export {
 	DocumentRecordType,
 	isDocument,
@@ -139,7 +147,13 @@ export {
 	type TLInstancePresence,
 	type TLInstancePresenceID,
 } from './records/TLPresence'
-export { type TLRecord } from './records/TLRecord'
+export {
+	type TLCustomRecord,
+	type TLDefaultRecord,
+	type TLGlobalRecordPropsMap,
+	type TLIndexedRecords,
+	type TLRecord,
+} from './records/TLRecord'
 export {
 	createShapeId,
 	createShapePropsMigrationIds,

package/src/records/TLCustomRecord.ts

@@ -0,0 +1,297 @@
+import {
+	MigrationSequence,
+	RecordId,
+	RecordScope,
+	UnknownRecord,
+	createMigrationSequence,
+	createRecordType,
+} from '@tldraw/store'
+import { assert, mapObjectMapValues, uniqueId } from '@tldraw/utils'
+import { T } from '@tldraw/validate'
+import { TLPropsMigrations } from '../recordsWithProps'
+
+/**
+ * Configuration for a custom record type in the schema.
+ *
+ * Custom record types allow you to add entirely new data types to the tldraw store
+ * that don't fit into the existing shape, binding, or asset categories. This is useful
+ * for storing domain-specific data like comments, annotations, or application state
+ * that needs to participate in persistence and synchronization.
+ *
+ * @example
+ * ```ts
+ * const commentRecordConfig: CustomRecordInfo = {
+ *   scope: 'document',
+ *   validator: T.object({
+ *     id: T.string,
+ *     typeName: T.literal('comment'),
+ *     text: T.string,
+ *     shapeId: T.string,
+ *     authorId: T.string,
+ *     createdAt: T.number,
+ *   }),
+ *   migrations: createRecordMigrationSequence({
+ *     sequenceId: 'com.myapp.comment',
+ *     recordType: 'comment',
+ *     sequence: [],
+ *   }),
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface CustomRecordInfo {
+	/**
+	 * The scope determines how records of this type are persisted and synchronized:
+	 * - **document**: Persisted and synced across all clients
+	 * - **session**: Local to current session, not synced
+	 * - **presence**: Ephemeral presence data, may be synced but not persisted
+	 */
+	scope: RecordScope
+
+	/**
+	 * Validator for the complete record structure.
+	 *
+	 * Should validate the entire record including `id` and `typeName` fields.
+	 * Use validators like T.object, T.string, etc.
+	 */
+	validator: T.Validatable<any>
+
+	/**
+	 * Optional migration sequence for handling schema evolution over time.
+	 *
+	 * Can be a full MigrationSequence or a simplified TLPropsMigrations format.
+	 * If not provided, an empty migration sequence will be created automatically.
+	 */
+	migrations?: MigrationSequence | TLPropsMigrations
+
+	/**
+	 * Optional factory function that returns default property values for new records.
+	 *
+	 * Called when creating new records to provide initial values for any properties
+	 * not explicitly provided during creation.
+	 */
+	// eslint-disable-next-line tldraw/method-signature-style
+	createDefaultProperties?: () => Record<string, unknown>
+}
+
+/**
+ * Creates a RecordType for a custom record based on its configuration.
+ *
+ * @param typeName - The unique type name for this record type
+ * @param config - Configuration for the custom record type
+ * @returns A RecordType instance that can be used to create and manage records
+ *
+ * @internal
+ */
+export function createCustomRecordType(typeName: string, config: CustomRecordInfo) {
+	return createRecordType<UnknownRecord>(typeName, {
+		scope: config.scope,
+		validator: config.validator,
+	}).withDefaultProperties(config.createDefaultProperties ?? (() => ({})))
+}
+
+/**
+ * Processes migrations for custom record types.
+ *
+ * Converts the migration configuration from CustomRecordInfo into proper
+ * MigrationSequence objects that can be used by the store system.
+ *
+ * @param records - Record of type names to their configuration
+ * @returns Array of migration sequences for the custom record types
+ *
+ * @internal
+ */
+export function processCustomRecordMigrations(
+	records: Record<string, CustomRecordInfo>
+): MigrationSequence[] {
+	const result: MigrationSequence[] = []
+
+	for (const [typeName, config] of Object.entries(records)) {
+		const sequenceId = `com.tldraw.${typeName}`
+		const { migrations } = config
+
+		if (!migrations) {
+			// Provide empty migration sequence to allow for future migrations
+			result.push(
+				createMigrationSequence({
+					sequenceId,
+					retroactive: true,
+					sequence: [],
+				})
+			)
+		} else if ('sequenceId' in migrations) {
+			// Full MigrationSequence provided
+			assert(
+				sequenceId === migrations.sequenceId,
+				`sequenceId mismatch for ${typeName} custom record migrations. Expected '${sequenceId}', got '${migrations.sequenceId}'`
+			)
+			result.push(migrations)
+		} else if ('sequence' in migrations) {
+			// TLPropsMigrations format - convert to full MigrationSequence
+			result.push(
+				createMigrationSequence({
+					sequenceId,
+					retroactive: true,
+					sequence: migrations.sequence.map((m) => {
+						if (!('id' in m)) return m
+						return {
+							id: m.id,
+							dependsOn: m.dependsOn,
+							scope: 'record' as const,
+							filter: (r: UnknownRecord) => r.typeName === typeName,
+							up: (record: any) => {
+								const result = m.up(record)
+								if (result) return result
+							},
+							down:
+								typeof m.down === 'function'
+									? (record: any) => {
+											const result = (m.down as (r: any) => any)(record)
+											if (result) return result
+										}
+									: undefined,
+						}
+					}),
+				})
+			)
+		}
+	}
+
+	return result
+}
+
+/**
+ * Creates properly formatted migration IDs for custom record migrations.
+ *
+ * Generates standardized migration IDs following the convention:
+ * `com.tldraw.{recordType}/{version}`
+ *
+ * @param recordType - The type name of the custom record
+ * @param ids - Record mapping migration names to version numbers
+ * @returns Record with the same keys but formatted migration ID values
+ *
+ * @example
+ * ```ts
+ * const commentVersions = createCustomRecordMigrationIds('comment', {
+ *   AddAuthorId: 1,
+ *   AddCreatedAt: 2,
+ *   RefactorReactions: 3
+ * })
+ * // Result: {
+ * //   AddAuthorId: 'com.tldraw.comment/1',
+ * //   AddCreatedAt: 'com.tldraw.comment/2',
+ * //   RefactorReactions: 'com.tldraw.comment/3'
+ * // }
+ * ```
+ *
+ * @public
+ */
+export function createCustomRecordMigrationIds<
+	const S extends string,
+	const T extends Record<string, number>,
+>(recordType: S, ids: T): { [k in keyof T]: `com.tldraw.${S}/${T[k]}` } {
+	return mapObjectMapValues(ids, (_k, v) => `com.tldraw.${recordType}/${v}`) as any
+}
+
+/**
+ * Creates a migration sequence for custom record types.
+ *
+ * This is a pass-through function that maintains the same structure as the input.
+ * It's used for consistency and to provide a clear API for defining custom record migrations.
+ *
+ * @param migrations - The migration sequence to create
+ * @returns The same migration sequence (pass-through)
+ *
+ * @example
+ * ```ts
+ * const commentMigrations = createCustomRecordMigrationSequence({
+ *   sequence: [
+ *     {
+ *       id: 'com.myapp.comment/1',
+ *       up: (record) => ({ ...record, authorId: record.authorId ?? 'unknown' }),
+ *       down: ({ authorId, ...record }) => record
+ *     }
+ *   ]
+ * })
+ * ```
+ *
+ * @public
+ */
+export function createCustomRecordMigrationSequence(
+	migrations: TLPropsMigrations
+): TLPropsMigrations {
+	return migrations
+}
+
+/**
+ * Creates a unique ID for a custom record type.
+ *
+ * @param typeName - The type name of the custom record
+ * @param id - Optional custom ID suffix. If not provided, a unique ID will be generated
+ * @returns A properly formatted record ID
+ *
+ * @example
+ * ```ts
+ * // Create with auto-generated ID
+ * const commentId = createCustomRecordId('comment') // 'comment:abc123'
+ *
+ * // Create with custom ID
+ * const customId = createCustomRecordId('comment', 'my-comment') // 'comment:my-comment'
+ * ```
+ *
+ * @public
+ */
+export function createCustomRecordId<T extends string>(
+	typeName: T,
+	id?: string
+): RecordId<UnknownRecord> & `${T}:${string}` {
+	return `${typeName}:${id ?? uniqueId()}` as RecordId<UnknownRecord> & `${T}:${string}`
+}
+
+/**
+ * Type guard to check if a string is a valid ID for a specific custom record type.
+ *
+ * @param typeName - The type name to check against
+ * @param id - The string to check
+ * @returns True if the string is a valid ID for the specified record type
+ *
+ * @example
+ * ```ts
+ * const id = 'comment:abc123'
+ * if (isCustomRecordId('comment', id)) {
+ *   // id is now typed as a comment record ID
+ *   const comment = store.get(id)
+ * }
+ * ```
+ *
+ * @public
+ */
+export function isCustomRecordId(typeName: string, id?: string): boolean {
+	if (!id) return false
+	return id.startsWith(`${typeName}:`)
+}
+
+/**
+ * Type guard to check if a record is of a specific custom type.
+ *
+ * @param typeName - The type name to check against
+ * @param record - The record to check
+ * @returns True if the record is of the specified type
+ *
+ * @example
+ * ```ts
+ * function handleRecord(record: TLRecord) {
+ *   if (isCustomRecord('comment', record)) {
+ *     // Handle comment record
+ *     console.log(`Comment: ${record.text}`)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export function isCustomRecord(typeName: string, record?: UnknownRecord): boolean {
+	if (!record) return false
+	return record.typeName === typeName
+}

package/src/records/TLPageState.ts

@@ -35,8 +35,10 @@ import { TLShapeId } from './TLShape'
  *
  * @public
  */
-export interface TLInstancePageState
-	extends BaseRecord<'instance_page_state', TLInstancePageStateId> {
+export interface TLInstancePageState extends BaseRecord<
+	'instance_page_state',
+	TLInstancePageStateId
+> {
 	pageId: RecordId<TLPage>
 	selectedShapeIds: TLShapeId[]
 	hintingShapeIds: TLShapeId[]

package/src/records/TLRecord.ts

@@ -9,10 +9,89 @@ import { TLPointer } from './TLPointer'
 import { TLInstancePresence } from './TLPresence'
 import { TLShape } from './TLShape'
 
+/**
+ * Interface for extending tldraw with custom record types via TypeScript module augmentation.
+ *
+ * Custom record types allow you to add entirely new data types to the tldraw store that
+ * don't fit into the existing shape, binding, or asset categories. Each key in this
+ * interface becomes a new record type name, and the value should be your full record type.
+ *
+ * @example
+ * ```ts
+ * import { BaseRecord, RecordId } from '@tldraw/store'
+ *
+ * // Define your custom record type
+ * interface TLComment extends BaseRecord<'comment', RecordId<TLComment>> {
+ *   text: string
+ *   shapeId: TLShapeId
+ *   authorId: string
+ *   createdAt: number
+ * }
+ *
+ * // Augment the global record props map
+ * declare module '@tldraw/tlschema' {
+ *   interface TLGlobalRecordPropsMap {
+ *     comment: TLComment
+ *   }
+ * }
+ *
+ * // Now TLRecord includes your custom comment type
+ * // and you can use it with createTLSchema()
+ * ```
+ *
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TLGlobalRecordPropsMap {}
+
+/**
+ * Union type of all built-in tldraw record types.
+ *
+ * This includes persistent records (documents, pages, shapes, assets, bindings)
+ * and session/presence records (cameras, instances, pointers, page states).
+ *
+ * @public
+ */
+export type TLDefaultRecord =
+	| TLAsset
+	| TLBinding
+	| TLCamera
+	| TLDocument
+	| TLInstance
+	| TLInstancePageState
+	| TLPage
+	| TLShape
+	| TLInstancePresence
+	| TLPointer
+
+/**
+ * Index type that maps custom record type names to their record types.
+ *
+ * Similar to TLIndexedShapes and TLIndexedBindings, this type creates a mapping
+ * from type name keys to their corresponding record types, filtering out any
+ * disabled types (those set to null or undefined in TLGlobalRecordPropsMap).
+ *
+ * @public
+ */
+// prettier-ignore
+export type TLIndexedRecords = {
+	[K in keyof TLGlobalRecordPropsMap as TLGlobalRecordPropsMap[K] extends null | undefined
+		? never
+		: K]: TLGlobalRecordPropsMap[K]
+}
+
+/**
+ * Union type representing a custom record from the TLGlobalRecordPropsMap.
+ *
+ * @public
+ */
+export type TLCustomRecord = TLIndexedRecords[keyof TLIndexedRecords]
+
 /**
  * Union type representing all possible record types in a tldraw store.
  * This includes both persistent records (documents, pages, shapes, assets, bindings)
- * and session/presence records (cameras, instances, pointers, page states).
+ * and session/presence records (cameras, instances, pointers, page states),
+ * as well as any custom record types added via TLGlobalRecordPropsMap augmentation.
  *
  * Records are organized by scope:
  * - **document**: Persisted across sessions (shapes, pages, assets, bindings, documents)
@@ -52,14 +131,4 @@ import { TLShape } from './TLShape'
  *
  * @public
  */
-export type TLRecord =
-	| TLAsset
-	| TLBinding
-	| TLCamera
-	| TLDocument
-	| TLInstance
-	| TLInstancePageState
-	| TLPage
-	| TLShape
-	| TLInstancePresence
-	| TLPointer
+export type TLRecord = TLDefaultRecord | TLCustomRecord

package/src/recordsWithProps.ts

@@ -88,7 +88,7 @@ export type RecordPropsType<Config extends Record<string, T.Validatable<any>>> =
 export interface TLPropsMigration {
 	readonly id: MigrationId
 	readonly dependsOn?: MigrationId[]
-	// eslint-disable-next-line @typescript-eslint/method-signature-style
+	// eslint-disable-next-line tldraw/method-signature-style
 	readonly up: (props: any) => any
 	/**
 	 * If a down migration was deployed more than a couple of months ago it should be safe to retire it.