Records

The "record" is the unit of state in tldraw. Everything observable — shapes, bindings, pages, presence, the document, the camera — is a record in the store.

Shape of a record

Every record extends BaseRecord<TypeName, Id> (packages/store/src/lib/BaseRecord.ts):

interface BaseRecord<TypeName extends string, Id extends RecordId<any>> {
  readonly id: Id;
  readonly typeName: TypeName;
}

Concrete records add their own props:

interface TLNoteShape extends TLBaseShape<'note', { color: TLColor; text: string; ... }> {}

IDs are strings like shape:abc123 or page:page1. The id-construction helpers (createShapeId, createBindingId, createPageId, …) live in tlschema and store.

RecordType

RecordType<R> (packages/store/src/lib/RecordType.ts) is the factory:

const PageRecordType = createRecordType<TLPage>('page', {
  scope: 'document',
}).withDefaultProperties(() => ({ name: 'New page', meta: {} }));

Each record type knows:

• The typeName.
• Default property factory.
• The validator (a Validator from @tldraw/validate).
• Migrations (record-level).
• Scope (document | session | presence).

RecordsDiff

The store's mutation primitive is RecordsDiff:

interface RecordsDiff<R> {
  added: Record<RecordId<R>, R>;
  updated: Record<RecordId<R>, [oldRecord: R, newRecord: R]>;
  removed: Record<RecordId<R>, R>;
}

Every store change emits one of these. Diffs squash (squashRecordDiffs) and reverse (reverseRecordsDiff), which are used by the history and sync layers.

The TL- record family

Defined in packages/tlschema/src/records/:

• TLDocument, TLPage, TLPageState, TLInstance, TLPointer, TLCamera, TLUser.
• TLShape (union of all concrete shape records).
• TLBinding (union of all concrete binding records).
• TLAsset (union of asset records).
• TLInstancePresence.

Custom records

packages/tlschema/src/records/TLCustomRecord.ts defines the helper for adding application-specific record types. Useful for AI agent state, app metadata, etc. Set scope appropriately so your records sync (or don't) the way you want.

Related

• @tldraw/store
• @tldraw/tlschema
• Store and migrations