@tldraw/tlschema 5.3.0-next.fc37bd96825b → 5.4.0-canary.074b19f2c11f

package/dist-cjs/index.d.ts

@@ -529,6 +529,43 @@ export declare const CameraRecordType: RecordType<TLCamera, never>;
  */
 export declare const canvasUiColorTypeValidator: T.Validator<"accent" | "black" | "laser" | "muted-1" | "selection-fill" | "selection-stroke" | "white">;
 
+/**
+ * Config for registering the `comment-reaction` record type in a tldraw schema. Pass via
+ * `commentSchemaRecords`; see `TLCommentReaction`.
+ *
+ * @public
+ */
+export declare const commentReactionRecordConfig: CustomRecordInfo;
+
+/**
+ * Config for registering the `comment` record type in a tldraw schema. Pass via
+ * `commentSchemaRecords`; see `TLComment`.
+ *
+ * @public
+ */
+export declare const commentRecordConfig: CustomRecordInfo;
+
+/**
+ * The `records` map to pass to `createTLSchema` / the client `records` option so comment
+ * threads, comments, and reactions sync. Register the types together — one without the others
+ * will fail schema validation on one side of the connection.
+ *
+ * @public
+ */
+export declare const commentSchemaRecords: {
+    'comment-reaction': CustomRecordInfo;
+    'comment-thread': CustomRecordInfo;
+    comment: CustomRecordInfo;
+};
+
+/**
+ * Config for registering the `comment-thread` record type in a tldraw schema. Pass via
+ * `commentSchemaRecords`; see `TLCommentThread`.
+ *
+ * @public
+ */
+export declare const commentThreadRecordConfig: CustomRecordInfo;
+
 /**
  * Compress legacy draw shape segments by converting VecModel[] points to delta-encoded base64 format.
  * This function is useful for converting old draw shape data to the new compressed format.
@@ -810,6 +847,66 @@ export declare function createBindingValidator<Type extends string, Props extend
  */
 export declare function createCachedUserResolve(resolveFn: (userId: string) => null | TLUser): (userId: string) => Signal<null | TLUser>;
 
+/**
+ * Create a new comment record within a thread.
+ *
+ * @public
+ */
+export declare function createComment(props: {
+    authorId: string;
+    body: TLRichText;
+    meta?: JsonObject;
+    now?: number;
+    pageId: TLPageId;
+    threadId: TLCommentThreadId;
+}): TLComment;
+
+/** @public */
+export declare function createCommentId(id?: string): TLCommentId;
+
+/**
+ * Create a reaction record for one user's reaction to one comment. The id is derived from the
+ * comment and user (see `createCommentReactionId`), so re-reacting overwrites rather than adding.
+ *
+ * @public
+ */
+export declare function createCommentReaction(props: {
+    commentId: TLCommentId;
+    emoji: string;
+    meta?: JsonObject;
+    now?: number;
+    pageId: TLPageId;
+    threadId: TLCommentThreadId;
+    userId: string;
+}): TLCommentReaction;
+
+/**
+ * The id of one user's reaction to one comment, derived from the (comment, user, emoji) triple
+ * rather than random, so the same triple always addresses the same record and two tabs converge
+ * instead of racing to create duplicates. The sync authorizer leans on this, so it must be
+ * injective: all three parts are URI-encoded before joining, so a `:` in any of them can't shift
+ * the boundary and collapse two triples onto one id.
+ *
+ * @public
+ */
+export declare function createCommentReactionId(commentId: TLCommentId, userId: string, emoji: string): TLCommentReactionId;
+
+/**
+ * Create a new comment thread record. Pair with `createComment` for the thread's first message.
+ *
+ * @public
+ */
+export declare function createCommentThread(props: {
+    anchor: TLCommentAnchor;
+    createdBy: string;
+    meta?: JsonObject;
+    now?: number;
+    pageId: TLPageId;
+}): TLCommentThread;
+
+/** @public */
+export declare function createCommentThreadId(id?: string): TLCommentThreadId;
+
 /**
  * Creates a unique ID for a custom record type.
  *
@@ -913,7 +1010,7 @@ export declare function createCustomRecordMigrationSequence(migrations: TLPropsM
  *
  * @public
  */
-export declare function createPresenceStateDerivation($user: Signal<null | TLUser>, opts?: CreatePresenceStateDerivationOpts): (store: TLStore) => Signal<null | TLInstancePresence, unknown>;
+export declare function createPresenceStateDerivation($user: Signal<null | TLUser>, opts?: CreatePresenceStateDerivationOpts): (store: TLStore) => Signal<null | TLInstancePresence>;
 
 /** @public */
 export declare interface CreatePresenceStateDerivationOpts {
@@ -1136,7 +1233,7 @@ export declare function createShapeValidator<Type extends string, Props extends
  * })
  * ```
  */
-export declare function createTLSchema({ shapes, bindings, assets, user, records, migrations }?: {
+export declare function createTLSchema({ shapes, bindings, assets, user, records, migrations, }?: {
     assets?: Record<string, SchemaPropsInfo>;
     bindings?: Record<string, SchemaPropsInfo>;
     migrations?: readonly MigrationSequence[];
@@ -2226,6 +2323,28 @@ export declare function isBinding(record?: UnknownRecord): record is TLBinding;
  */
 export declare function isBindingId(id?: string): id is TLBindingId;
 
+/**
+ * Type guard for `TLCommentId`. See `isCommentThreadId`.
+ *
+ * @public
+ */
+export declare function isCommentId(id: string): id is TLCommentId;
+
+/**
+ * Type guard for `TLCommentReactionId`. See `isCommentThreadId`.
+ *
+ * @public
+ */
+export declare function isCommentReactionId(id: string): id is TLCommentReactionId;
+
+/**
+ * Type guard for `TLCommentThreadId`. `isCommentId` rejects these — `comment-thread:` and
+ * `comment:` differ in the character after `comment`, so the prefixes never overlap.
+ *
+ * @public
+ */
+export declare function isCommentThreadId(id: string): id is TLCommentThreadId;
+
 /**
  * Type guard to check if a record is of a specific custom type.
  *
@@ -2295,6 +2414,25 @@ export declare function isDocument(record?: UnknownRecord): record is TLDocument
 
 /* Excluded from this release type: isFontEntry */
 
+/**
+ * Type guard to check if a record is a page.
+ *
+ * @param record - The record to check
+ * @returns True if the record is a page, false otherwise
+ *
+ * @example
+ * ```ts
+ * const record = store.get('page:abc123')
+
+ * if (isPage(record)) {
+ *   console.log(`Page name: ${record.name}`)
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isPage(record?: UnknownRecord): record is TLPage;
+
 /**
  * Type guard to check if a string is a valid TLPageId.
  *
@@ -2364,152 +2502,152 @@ export declare function isUserId(id: string): id is TLUserId;
 
 /** @public */
 export declare const LANGUAGES: readonly [{
-    readonly label: "Bahasa Indonesia";
-    readonly locale: "id";
+    readonly label: 'Bahasa Indonesia';
+    readonly locale: 'id';
 }, {
-    readonly label: "Bahasa Melayu";
-    readonly locale: "ms";
+    readonly label: 'Bahasa Melayu';
+    readonly locale: 'ms';
 }, {
-    readonly label: "Català";
-    readonly locale: "ca";
+    readonly label: 'Català';
+    readonly locale: 'ca';
 }, {
-    readonly label: "Čeština";
-    readonly locale: "cs";
+    readonly label: 'Čeština';
+    readonly locale: 'cs';
 }, {
-    readonly label: "Danish";
-    readonly locale: "da";
+    readonly label: 'Danish';
+    readonly locale: 'da';
 }, {
-    readonly label: "Deutsch";
-    readonly locale: "de";
+    readonly label: 'Deutsch';
+    readonly locale: 'de';
 }, {
-    readonly label: "English";
-    readonly locale: "en";
+    readonly label: 'English';
+    readonly locale: 'en';
 }, {
-    readonly label: "Español";
-    readonly locale: "es";
+    readonly label: 'Español';
+    readonly locale: 'es';
 }, {
-    readonly label: "Filipino";
-    readonly locale: "tl";
+    readonly label: 'Filipino';
+    readonly locale: 'tl';
 }, {
-    readonly label: "Français";
-    readonly locale: "fr";
+    readonly label: 'Français';
+    readonly locale: 'fr';
 }, {
-    readonly label: "Galego";
-    readonly locale: "gl";
+    readonly label: 'Galego';
+    readonly locale: 'gl';
 }, {
-    readonly label: "Hrvatski";
-    readonly locale: "hr";
+    readonly label: 'Hrvatski';
+    readonly locale: 'hr';
 }, {
-    readonly label: "Italiano";
-    readonly locale: "it";
+    readonly label: 'Italiano';
+    readonly locale: 'it';
 }, {
-    readonly label: "Magyar";
-    readonly locale: "hu";
+    readonly label: 'Magyar';
+    readonly locale: 'hu';
 }, {
-    readonly label: "Nederlands";
-    readonly locale: "nl";
+    readonly label: 'Nederlands';
+    readonly locale: 'nl';
 }, {
-    readonly label: "Norwegian";
-    readonly locale: "no";
+    readonly label: 'Norwegian';
+    readonly locale: 'no';
 }, {
-    readonly label: "Polski";
-    readonly locale: "pl";
+    readonly label: 'Polski';
+    readonly locale: 'pl';
 }, {
-    readonly label: "Português - Brasil";
-    readonly locale: "pt-br";
+    readonly label: 'Português - Brasil';
+    readonly locale: 'pt-br';
 }, {
-    readonly label: "Português - Europeu";
-    readonly locale: "pt-pt";
+    readonly label: 'Português - Europeu';
+    readonly locale: 'pt-pt';
 }, {
-    readonly label: "Română";
-    readonly locale: "ro";
+    readonly label: 'Română';
+    readonly locale: 'ro';
 }, {
-    readonly label: "Slovenščina";
-    readonly locale: "sl";
+    readonly label: 'Slovenščina';
+    readonly locale: 'sl';
 }, {
-    readonly label: "Somali";
-    readonly locale: "so";
+    readonly label: 'Somali';
+    readonly locale: 'so';
 }, {
-    readonly label: "Suomi";
-    readonly locale: "fi";
+    readonly label: 'Suomi';
+    readonly locale: 'fi';
 }, {
-    readonly label: "Svenska";
-    readonly locale: "sv";
+    readonly label: 'Svenska';
+    readonly locale: 'sv';
 }, {
-    readonly label: "Tiếng Việt";
-    readonly locale: "vi";
+    readonly label: 'Tiếng Việt';
+    readonly locale: 'vi';
 }, {
-    readonly label: "Türkçe";
-    readonly locale: "tr";
+    readonly label: 'Türkçe';
+    readonly locale: 'tr';
 }, {
-    readonly label: "Ελληνικά";
-    readonly locale: "el";
+    readonly label: 'Ελληνικά';
+    readonly locale: 'el';
 }, {
-    readonly label: "Русский";
-    readonly locale: "ru";
+    readonly label: 'Русский';
+    readonly locale: 'ru';
 }, {
-    readonly label: "Українська";
-    readonly locale: "uk";
+    readonly label: 'Українська';
+    readonly locale: 'uk';
 }, {
-    readonly label: "עברית";
-    readonly locale: "he";
+    readonly label: 'עברית';
+    readonly locale: 'he';
 }, {
-    readonly label: "اردو";
-    readonly locale: "ur";
+    readonly label: 'اردو';
+    readonly locale: 'ur';
 }, {
-    readonly label: "عربي";
-    readonly locale: "ar";
+    readonly label: 'عربي';
+    readonly locale: 'ar';
 }, {
-    readonly label: "فارسی";
-    readonly locale: "fa";
+    readonly label: 'فارسی';
+    readonly locale: 'fa';
 }, {
-    readonly label: "नेपाली";
-    readonly locale: "ne";
+    readonly label: 'नेपाली';
+    readonly locale: 'ne';
 }, {
-    readonly label: "मराठी";
-    readonly locale: "mr";
+    readonly label: 'मराठी';
+    readonly locale: 'mr';
 }, {
-    readonly label: "हिन्दी";
-    readonly locale: "hi-in";
+    readonly label: 'हिन्दी';
+    readonly locale: 'hi-in';
 }, {
-    readonly label: "বাংলা";
-    readonly locale: "bn";
+    readonly label: 'বাংলা';
+    readonly locale: 'bn';
 }, {
-    readonly label: "ਪੰਜਾਬੀ";
-    readonly locale: "pa";
+    readonly label: 'ਪੰਜਾਬੀ';
+    readonly locale: 'pa';
 }, {
-    readonly label: "ગુજરાતી";
-    readonly locale: "gu-in";
+    readonly label: 'ગુજરાતી';
+    readonly locale: 'gu-in';
 }, {
-    readonly label: "தமிழ்";
-    readonly locale: "ta";
+    readonly label: 'தமிழ்';
+    readonly locale: 'ta';
 }, {
-    readonly label: "తెలుగు";
-    readonly locale: "te";
+    readonly label: 'తెలుగు';
+    readonly locale: 'te';
 }, {
-    readonly label: "ಕನ್ನಡ";
-    readonly locale: "kn";
+    readonly label: 'ಕನ್ನಡ';
+    readonly locale: 'kn';
 }, {
-    readonly label: "മലയാളം";
-    readonly locale: "ml";
+    readonly label: 'മലയാളം';
+    readonly locale: 'ml';
 }, {
-    readonly label: "ภาษาไทย";
-    readonly locale: "th";
+    readonly label: 'ภาษาไทย';
+    readonly locale: 'th';
 }, {
-    readonly label: "ភាសាខ្មែរ";
-    readonly locale: "km-kh";
+    readonly label: 'ភាសាខ្មែរ';
+    readonly locale: 'km-kh';
 }, {
-    readonly label: "한국어";
-    readonly locale: "ko-kr";
+    readonly label: '한국어';
+    readonly locale: 'ko-kr';
 }, {
-    readonly label: "日本語";
-    readonly locale: "ja";
+    readonly label: '日本語';
+    readonly locale: 'ja';
 }, {
-    readonly label: "简体中文";
-    readonly locale: "zh-cn";
+    readonly label: '简体中文';
+    readonly locale: 'zh-cn';
 }, {
-    readonly label: "繁體中文 (台灣)";
-    readonly locale: "zh-tw";
+    readonly label: '繁體中文 (台灣)';
+    readonly locale: 'zh-tw';
 }];
 
 /**
@@ -4005,6 +4143,145 @@ export declare type TLCameraId = RecordId<TLCamera>;
  */
 export declare type TLCanvasUiColor = SetValue<typeof TL_CANVAS_UI_COLOR_TYPES>;
 
+/**
+ * A single comment message within a thread. See `TLCommentThread` for the overall model and
+ * sync/registration notes.
+ *
+ * Comment mutations are deliberately not undoable — create/edit them with
+ * `{ history: 'ignore' }` to avoid multiplayer surprises like a comment reappearing after
+ * someone else deleted it.
+ *
+ * @public
+ */
+export declare interface TLComment extends BaseRecord<'comment', TLCommentId> {
+    /** The thread this comment belongs to. */
+    threadId: TLCommentThreadId;
+    /** Denormalized from the thread so per-page queries don't need a join. */
+    pageId: TLPageId;
+    /** See `TLCommentThread.createdBy` — same server-stamping caveat applies. */
+    authorId: string;
+    createdAt: number;
+    /** Null until the comment is first edited. */
+    editedAt: null | number;
+    /** Rich text body. Use `toRichText(...)` for plaintext input. */
+    body: TLRichText;
+    /** Whether the comment is soft-deleted. Same model as `TLCommentThread.isDeleted`. */
+    isDeleted: boolean;
+    meta: JsonObject;
+}
+
+/**
+ * Where a comment thread is anchored on the canvas. Modeled as a discriminated union so new
+ * anchor kinds can be added without breaking existing threads:
+ *
+ * - `shape` — pinned to a shape. `x`/`y` are normalized (0–1) within the shape's bounds, so the pin
+ *   keeps its spot as the shape moves, resizes, and rotates. `isPrecise` mirrors arrow bindings:
+ *   when false (the default) the pin sits at a consumer-defined spot instead, top-right out of the
+ *   box, and `x`/`y` are the remembered precise position
+ * - `point` — pinned to a fixed point on the page, in page coordinates
+ * - `region` — pinned to a rectangular area of the page, in page coordinates
+ * - `page` — a page-level thread with no spatial anchor
+ *
+ * @public
+ */
+export declare type TLCommentAnchor = {
+    /** The normalized (0–1) corner the pin sits on — where the creating drag was released.
+     *  Absent on older records; consumers fall back to a corner of their own choosing. */
+    pinX?: number;
+    h: number;
+    pinY?: number;
+    type: 'region';
+    w: number;
+    x: number;
+    y: number;
+} | {
+    isPrecise: boolean;
+    shapeId: TLShapeId;
+    type: 'shape';
+    x: number;
+    y: number;
+} | {
+    type: 'page';
+} | {
+    type: 'point';
+    x: number;
+    y: number;
+};
+
+/** @public */
+export declare type TLCommentId = RecordId<TLComment>;
+
+/**
+ * One person's emoji reaction to one comment.
+ *
+ * A reaction is its own record rather than a field on the comment: comment records are owner-only
+ * for updates, and a shared field would make concurrent reactions race to overwrite each other.
+ *
+ * A user holds at most one record per (comment, emoji) pair, enforced by the derived id — see
+ * `createCommentReactionId`. Limiting a user to one reaction overall is client-side policy (the
+ * commenting package's `reactionMode`), not a property of this record.
+ *
+ * @public
+ */
+export declare interface TLCommentReaction extends BaseRecord<'comment-reaction', TLCommentReactionId> {
+    /** The comment being reacted to. */
+    commentId: TLCommentId;
+    /** Denormalized from the comment, so a thread's reactions can be found without a join. */
+    threadId: TLCommentThreadId;
+    /** Denormalized from the comment — see `TLComment.pageId`. */
+    pageId: TLPageId;
+    /** Who reacted. See `TLCommentThread.createdBy` — same server-stamping caveat applies. */
+    userId: string;
+    /** The emoji itself, as a string (e.g. `'👍'`), not a shortcode. */
+    emoji: string;
+    createdAt: number;
+    meta: JsonObject;
+}
+
+/** @public */
+export declare type TLCommentReactionId = RecordId<TLCommentReaction>;
+
+/**
+ * A comment thread. The thread owns the anchor (where the conversation lives on the canvas) and
+ * the resolution state; the messages themselves are `TLComment` records pointing at the thread
+ * via `threadId`, ordered by `createdAt`. v1 threads are flat — no nested replies.
+ *
+ * Threads and comments are document records, but they're intended to be served through the sync
+ * server's object-store lane: gated by the session's `objectAccess` rather than `isReadonly`
+ * (so "can comment but not edit" is expressible), excluded from document snapshots and `.tldr`
+ * exports server-side, and persisted in a separate lane from the main document.
+ *
+ * Opt-in: register with `createTLSchema({ records: commentSchemaRecords })` on the server and
+ * the matching `records` option on the client — neither type is part of the default schema, and
+ * both sides must register them identically.
+ *
+ * @public
+ */
+export declare interface TLCommentThread extends BaseRecord<'comment-thread', TLCommentThreadId> {
+    /** The page the thread lives on. */
+    pageId: TLPageId;
+    /** Where the thread is anchored on that page. */
+    anchor: TLCommentAnchor;
+    /** Who started the thread. Client-supplied; sync servers are expected to stamp/verify it. */
+    createdBy: string;
+    createdAt: number;
+    /** Resolution state: when and by whom the thread was resolved, or null while open. */
+    resolved: {
+        at: number;
+        by: string;
+    } | null;
+    /**
+     * Whether the thread is soft-deleted. Clients set the flag and leave the record in place. Sync
+     * servers are expected to enforce it as write-once and creator-only, reject client hard
+     * deletes, and drop flagged threads from future room loads.
+     */
+    isDeleted: boolean;
+    meta: JsonObject;
+}
+
+/** @public */
+export declare type TLCommentThreadId = RecordId<TLCommentThread>;
+
 /**
  * A partial version of a shape, useful for creating shapes.
  *
@@ -4730,7 +5007,9 @@ export declare interface TLFrameShapeProps {
  *     labelColor: 'black',
  *     url: '',
  *     growY: 0,
- *     scale: 1
+ *     scale: 1,
+ *     flipX: false,
+ *     flipY: false
  *   },
  *   meta: {}
  * }
@@ -4765,6 +5044,10 @@ export declare interface TLGeoShapeProps {
     growY: number;
     /** Scale factor applied to the shape */
     scale: number;
+    /** Whether to mirror the shape horizontally */
+    flipX: boolean;
+    /** Whether to mirror the shape vertically */
+    flipY: boolean;
     /** Color style for text label */
     labelColor: TLDefaultColorStyle;
     /** Color style for the shape outline */

package/dist-cjs/index.js

@@ -70,6 +70,10 @@ __export(index_exports, {
   bookmarkShapeProps: () => import_TLBookmarkShape.bookmarkShapeProps,
   boxModelValidator: () => import_geometry_types.boxModelValidator,
   canvasUiColorTypeValidator: () => import_TLColor.canvasUiColorTypeValidator,
+  commentReactionRecordConfig: () => import_TLComment.commentReactionRecordConfig,
+  commentRecordConfig: () => import_TLComment.commentRecordConfig,
+  commentSchemaRecords: () => import_TLComment.commentSchemaRecords,
+  commentThreadRecordConfig: () => import_TLComment.commentThreadRecordConfig,
   compressLegacySegments: () => import_TLDrawShape.compressLegacySegments,
   createAssetPropsMigrationIds: () => import_TLAsset.createAssetPropsMigrationIds,
   createAssetPropsMigrationSequence: () => import_TLAsset.createAssetPropsMigrationSequence,
@@ -80,6 +84,12 @@ __export(index_exports, {
   createBindingPropsMigrationSequence: () => import_TLBinding.createBindingPropsMigrationSequence,
   createBindingValidator: () => import_TLBaseBinding.createBindingValidator,
   createCachedUserResolve: () => import_TLStore.createCachedUserResolve,
+  createComment: () => import_TLComment.createComment,
+  createCommentId: () => import_TLComment.createCommentId,
+  createCommentReaction: () => import_TLComment.createCommentReaction,
+  createCommentReactionId: () => import_TLComment.createCommentReactionId,
+  createCommentThread: () => import_TLComment.createCommentThread,
+  createCommentThreadId: () => import_TLComment.createCommentThreadId,
   createCustomRecordId: () => import_TLCustomRecord.createCustomRecordId,
   createCustomRecordMigrationIds: () => import_TLCustomRecord.createCustomRecordMigrationIds,
   createCustomRecordMigrationSequence: () => import_TLCustomRecord.createCustomRecordMigrationSequence,
@@ -116,10 +126,14 @@ __export(index_exports, {
   imageShapeProps: () => import_TLImageShape.imageShapeProps,
   isBinding: () => import_TLBinding.isBinding,
   isBindingId: () => import_TLBinding.isBindingId,
+  isCommentId: () => import_TLComment.isCommentId,
+  isCommentReactionId: () => import_TLComment.isCommentReactionId,
+  isCommentThreadId: () => import_TLComment.isCommentThreadId,
   isCustomRecord: () => import_TLCustomRecord.isCustomRecord,
   isCustomRecordId: () => import_TLCustomRecord.isCustomRecordId,
   isDocument: () => import_TLDocument.isDocument,
   isFontEntry: () => import_TLFontStyle.isFontEntry,
+  isPage: () => import_TLPage.isPage,
   isPageId: () => import_TLPage.isPageId,
   isShape: () => import_TLShape.isShape,
   isShapeId: () => import_TLShape.isShapeId,
@@ -170,6 +184,7 @@ var import_TLScribble = require("./misc/TLScribble");
 var import_TLAsset = require("./records/TLAsset");
 var import_TLBinding = require("./records/TLBinding");
 var import_TLCamera = require("./records/TLCamera");
+var import_TLComment = require("./records/TLComment");
 var import_TLCustomRecord = require("./records/TLCustomRecord");
 var import_TLDocument = require("./records/TLDocument");
 var import_TLInstance = require("./records/TLInstance");
@@ -207,7 +222,7 @@ var import_translations = require("./translations/translations");
 var import_b64Vecs = require("./misc/b64Vecs");
 (0, import_utils.registerTldrawLibraryVersion)(
   "@tldraw/tlschema",
-  "5.3.0-next.fc37bd96825b",
+  "5.4.0-canary.074b19f2c11f",
   "cjs"
 );
 //# sourceMappingURL=index.js.map