@yuzhouu/canvas-kit 0.1.2

package/_vendor/canvas-core/schema/snapshots.ts

@@ -0,0 +1,527 @@
+import type { BindingUtilRegistry } from "../bindings/BindingUtilRegistry";
+import type { ShapeUtilRegistry } from "../shapes/ShapeUtilRegistry";
+import type { StoreSnapshot } from "@land/store";
+import {
+  DEFAULT_CAMERA,
+  DEFAULT_PAGE_ID,
+  isAssetRecord,
+  createDefaultPage,
+  createDefaultSession,
+  isBindingRecord,
+  type AssetId,
+  type AssetRecord,
+  type Camera,
+  type BindingId,
+  type BindingRecord,
+  type DocumentRecord,
+  type PageId,
+  type PageRecord,
+  type SessionRecord,
+  type ShapeId,
+  type ShapeParentId,
+  type ShapeRecord,
+} from "./records";
+
+export type DocumentSnapshot = StoreSnapshot<DocumentRecord, 1>;
+export type SessionSnapshot = StoreSnapshot<SessionRecord, 1>;
+
+export class SnapshotParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SnapshotParseError";
+  }
+}
+
+const CURRENT_DOCUMENT_SNAPSHOT_VERSION = 1 as const;
+const CURRENT_SESSION_SNAPSHOT_VERSION = 1 as const;
+
+/**
+ * A single forward migration step. `up` transforms the raw records array from
+ * `fromVersion` to `fromVersion + 1`. Steps are chained in order, so adding a
+ * new schema version means bumping the CURRENT_* constant and appending one
+ * migration with `fromVersion` equal to the previous current version.
+ */
+export interface SnapshotMigration {
+  fromVersion: number;
+  up: (records: unknown[]) => unknown[];
+}
+
+// No migrations yet: version 1 is the first schema. Append future steps here.
+const DOCUMENT_SNAPSHOT_MIGRATIONS: readonly SnapshotMigration[] = [];
+const SESSION_SNAPSHOT_MIGRATIONS: readonly SnapshotMigration[] = [];
+
+/**
+ * Apply forward migration steps to bring a records array from `fromVersion` up
+ * to `toVersion`. Throws if a step is missing or the snapshot is newer than the
+ * supported version (no down-migration).
+ */
+export function migrateSnapshotRecords(
+  records: unknown[],
+  fromVersion: number,
+  toVersion: number,
+  migrations: readonly SnapshotMigration[],
+  kind: "document" | "session" = "document",
+): unknown[] {
+  if (fromVersion > toVersion) {
+    throw new SnapshotParseError(
+      `Unsupported ${kind} snapshot schema version: ${fromVersion} is newer than ${toVersion}`,
+    );
+  }
+
+  let current = records;
+  for (let version = fromVersion; version < toVersion; version += 1) {
+    const step = migrations.find((migration) => migration.fromVersion === version);
+    if (!step) {
+      throw new SnapshotParseError(
+        `No ${kind} snapshot migration from schema version ${version}`,
+      );
+    }
+    current = step.up(current);
+  }
+  return current;
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function isObject(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asFiniteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function asMeta(value: unknown): Record<string, unknown> {
+  return isObject(value) ? value : {};
+}
+
+function parseCamera(value: unknown): Camera | null {
+  if (!isObject(value)) return null;
+
+  return {
+    x: asFiniteNumber(value.x, DEFAULT_CAMERA.x),
+    y: asFiniteNumber(value.y, DEFAULT_CAMERA.y),
+    z: Math.min(8, Math.max(0.1, asFiniteNumber(value.z, DEFAULT_CAMERA.z))),
+  };
+}
+
+function parseCameraMap(value: unknown): SessionRecord["pageCameraById"] {
+  if (!isObject(value)) return {};
+
+  const entries = Object.entries(value)
+    .filter(([pageId]) => pageId.startsWith("page:"))
+    .map(([pageId, camera]) => [pageId as PageId, parseCamera(camera)])
+    .filter((entry): entry is [PageId, Camera] => entry[1] !== null);
+
+  return Object.fromEntries(entries);
+}
+
+function parseSelectedShapeIds(
+  value: unknown,
+): SessionRecord["pageSelectedShapeIdsById"][PageId] {
+  return Array.from(
+    new Set(
+      asStringArray(value).filter((id): id is ShapeRecord["id"] =>
+        id.startsWith("shape:"),
+      ),
+    ),
+  );
+}
+
+function parseSelectionMap(
+  value: unknown,
+): SessionRecord["pageSelectedShapeIdsById"] {
+  if (!isObject(value)) return {};
+
+  const entries = Object.entries(value)
+    .filter(([pageId]) => pageId.startsWith("page:"))
+    .map(([pageId, selectedShapeIds]) => [
+      pageId as PageId,
+      parseSelectedShapeIds(selectedShapeIds),
+    ]);
+
+  return Object.fromEntries(entries);
+}
+
+function getSnapshotEnvelope(
+  snapshot: unknown,
+  kind: "document" | "session",
+): { schemaVersion: number; records: unknown[] } {
+  if (!isObject(snapshot)) {
+    throw new SnapshotParseError(`Invalid ${kind} snapshot: expected object`);
+  }
+
+  const rawVersion = snapshot.schemaVersion;
+  const schemaVersion = asFiniteNumber(rawVersion, Number.NaN);
+  if (!Number.isFinite(schemaVersion) || schemaVersion < 1) {
+    throw new SnapshotParseError(
+      `Unsupported ${kind} snapshot schema version: ${String(rawVersion)}`,
+    );
+  }
+
+  if (!Array.isArray(snapshot.records)) {
+    throw new SnapshotParseError(
+      `Invalid ${kind} snapshot: records must be an array`,
+    );
+  }
+
+  const currentVersion =
+    kind === "document"
+      ? CURRENT_DOCUMENT_SNAPSHOT_VERSION
+      : CURRENT_SESSION_SNAPSHOT_VERSION;
+  const migrations =
+    kind === "document"
+      ? DOCUMENT_SNAPSHOT_MIGRATIONS
+      : SESSION_SNAPSHOT_MIGRATIONS;
+
+  const records = migrateSnapshotRecords(
+    snapshot.records,
+    schemaVersion,
+    currentVersion,
+    migrations,
+    kind,
+  );
+
+  return { schemaVersion: currentVersion, records };
+}
+
+function parsePageRecord(record: UnknownRecord, order: number): PageRecord {
+  if (typeof record.id !== "string" || !record.id.startsWith("page:")) {
+    throw new SnapshotParseError("Invalid page record id");
+  }
+
+  return {
+    id: record.id as PageId,
+    typeName: "page",
+    scope: "document",
+    name: asString(record.name, `Page ${order + 1}`),
+    index: asString(record.index, String(order + 1).padStart(4, "0")),
+    meta: asMeta(record.meta),
+  };
+}
+
+function parseShapeRecord(
+  record: UnknownRecord,
+  shapeUtils: ShapeUtilRegistry,
+  order: number,
+): ShapeRecord {
+  if (typeof record.id !== "string" || !record.id.startsWith("shape:")) {
+    throw new SnapshotParseError("Invalid shape record id");
+  }
+
+  if (typeof record.type !== "string") {
+    throw new SnapshotParseError("Invalid shape record type");
+  }
+
+  if (
+    typeof record.parentId !== "string" ||
+    (!record.parentId.startsWith("page:") &&
+      !record.parentId.startsWith("shape:"))
+  ) {
+    throw new SnapshotParseError(`Invalid parent id for shape ${record.id}`);
+  }
+
+  const shared = {
+    id: record.id as ShapeRecord["id"],
+    typeName: "shape" as const,
+    scope: "document" as const,
+    parentId: record.parentId as ShapeParentId,
+    index: asString(record.index, String(order + 1).padStart(6, "0")),
+    x: asFiniteNumber(record.x, 0),
+    y: asFiniteNumber(record.y, 0),
+    rotation: asFiniteNumber(record.rotation, 0),
+    scaleX: asFiniteNumber(record.scaleX, 1),
+    scaleY: asFiniteNumber(record.scaleY, 1),
+    opacity: Math.min(1, Math.max(0, asFiniteNumber(record.opacity, 1))),
+    isHidden: asBoolean(record.isHidden, false),
+    isLocked: asBoolean(record.isLocked, false),
+    meta: asMeta(record.meta),
+  };
+  return {
+    ...shared,
+    type: record.type,
+    props: shapeUtils.get(record.type).validateProps(record.props),
+  } as ShapeRecord;
+}
+
+function parseBindingRecord(
+  record: UnknownRecord,
+  bindingUtils: BindingUtilRegistry,
+): BindingRecord {
+  if (typeof record.id !== "string" || !record.id.startsWith("binding:")) {
+    throw new SnapshotParseError("Invalid binding record id");
+  }
+
+  if (typeof record.type !== "string") {
+    throw new SnapshotParseError("Invalid binding record type");
+  }
+
+  if (
+    typeof record.fromId !== "string" ||
+    !record.fromId.startsWith("shape:")
+  ) {
+    throw new SnapshotParseError(`Invalid from id for binding ${record.id}`);
+  }
+
+  if (typeof record.toId !== "string" || !record.toId.startsWith("shape:")) {
+    throw new SnapshotParseError(`Invalid to id for binding ${record.id}`);
+  }
+
+  const bindingType = record.type;
+  const util = bindingUtils.get(bindingType);
+
+  return {
+    id: record.id as BindingId,
+    typeName: "binding",
+    scope: "document",
+    type: bindingType,
+    fromId: record.fromId as ShapeId,
+    toId: record.toId as ShapeId,
+    props: util.validateProps(record.props),
+    meta: asMeta(record.meta),
+  } as BindingRecord;
+}
+
+function parseAssetRecord(record: UnknownRecord): AssetRecord {
+  if (typeof record.id !== "string" || !record.id.startsWith("asset:")) {
+    throw new SnapshotParseError("Invalid asset record id");
+  }
+
+  if (typeof record.type !== "string") {
+    throw new SnapshotParseError("Invalid asset record type");
+  }
+
+  return {
+    id: record.id as AssetId,
+    typeName: "asset",
+    scope: "document",
+    type: record.type,
+    props: isObject(record.props) ? record.props : {},
+    meta: asMeta(record.meta),
+  } as AssetRecord;
+}
+
+function hasValidShapeParent({
+  pageIds,
+  parentId,
+  shapeById,
+  shapeId,
+  shapeUtils,
+}: {
+  pageIds: ReadonlySet<PageId>;
+  parentId: ShapeParentId;
+  shapeById: ReadonlyMap<ShapeId, ShapeRecord>;
+  shapeId: ShapeId;
+  shapeUtils: ShapeUtilRegistry;
+}): boolean {
+  if (parentId.startsWith("page:")) {
+    return pageIds.has(parentId as PageId);
+  }
+
+  if (parentId === shapeId) {
+    return false;
+  }
+
+  const parentShape = shapeById.get(parentId as ShapeId);
+  if (!parentShape) {
+    return false;
+  }
+
+  if (!shapeUtils.get(parentShape.type).canReceiveChildren(parentShape)) {
+    return false;
+  }
+
+  const seen = new Set<ShapeId>([shapeId]);
+  let currentParentId = parentShape.parentId;
+  while (currentParentId.startsWith("shape:")) {
+    const ancestorId = currentParentId as ShapeId;
+    if (seen.has(ancestorId)) {
+      return false;
+    }
+    seen.add(ancestorId);
+
+    const ancestor = shapeById.get(ancestorId);
+    if (!ancestor) {
+      return false;
+    }
+    if (!shapeUtils.get(ancestor.type).canReceiveChildren(ancestor)) {
+      return false;
+    }
+    currentParentId = ancestor.parentId;
+  }
+
+  return pageIds.has(currentParentId as PageId);
+}
+
+function repairDocumentRecords(
+  records: DocumentRecord[],
+  shapeUtils: ShapeUtilRegistry,
+): DocumentRecord[] {
+  const pages = records.filter(
+    (record): record is PageRecord => record.typeName === "page",
+  );
+  const shapes = records.filter(
+    (record): record is ShapeRecord => record.typeName === "shape",
+  );
+  const bindings = records.filter(isBindingRecord);
+  const assets = records.filter(isAssetRecord);
+
+  const orderedPages =
+    pages.length > 0
+      ? [...pages].sort((left, right) => left.index.localeCompare(right.index))
+      : [createDefaultPage()];
+  const repairedPages = orderedPages.map((page, index) => ({
+    ...page,
+    index: String(index + 1).padStart(4, "0"),
+  }));
+  const fallbackPageId = repairedPages[0]?.id ?? DEFAULT_PAGE_ID;
+  const pageIds = new Set(repairedPages.map((page) => page.id));
+  const orderedShapes = [...shapes].sort((left, right) =>
+    left.index.localeCompare(right.index),
+  );
+  const shapeById = new Map(orderedShapes.map((shape) => [shape.id, shape]));
+
+  const repairedShapes = orderedShapes.map((shape, index) => {
+    const parentId = hasValidShapeParent({
+      pageIds,
+      parentId: shape.parentId,
+      shapeById,
+      shapeId: shape.id,
+      shapeUtils,
+    })
+      ? shape.parentId
+      : fallbackPageId;
+    const repairedShape = {
+      ...shape,
+      parentId,
+      index: shape.index || String(index + 1).padStart(6, "0"),
+    };
+
+    return shapeUtils.get(repairedShape.type).repairLoadedShape(repairedShape) ??
+      repairedShape;
+  });
+
+  const shapeIds = new Set(repairedShapes.map((shape) => shape.id));
+  const repairedBindings = bindings.filter(
+    (binding) => shapeIds.has(binding.fromId) && shapeIds.has(binding.toId),
+  );
+
+  return [...repairedPages, ...assets, ...repairedShapes, ...repairedBindings];
+}
+
+export function parseDocumentSnapshot(
+  snapshot: unknown,
+  shapeUtils: ShapeUtilRegistry,
+  bindingUtils: BindingUtilRegistry,
+): DocumentSnapshot {
+  const envelope = getSnapshotEnvelope(snapshot, "document");
+  const seenIds = new Set<string>();
+  const records: DocumentRecord[] = [];
+
+  envelope.records.forEach((value, index) => {
+    if (!isObject(value)) {
+      throw new SnapshotParseError("Invalid document record: expected object");
+    }
+
+    if (typeof value.id !== "string") {
+      throw new SnapshotParseError("Invalid document record id");
+    }
+    if (seenIds.has(value.id)) {
+      throw new SnapshotParseError(`Duplicate document record id: ${value.id}`);
+    }
+    seenIds.add(value.id);
+
+    if (value.typeName === "page") {
+      records.push(parsePageRecord(value, index));
+      return;
+    }
+
+    if (value.typeName === "shape") {
+      records.push(parseShapeRecord(value, shapeUtils, index));
+      return;
+    }
+
+    if (value.typeName === "binding") {
+      records.push(parseBindingRecord(value, bindingUtils));
+      return;
+    }
+
+    if (value.typeName === "asset") {
+      records.push(parseAssetRecord(value));
+      return;
+    }
+
+    throw new SnapshotParseError(
+      `Unsupported document record type: ${String(value.typeName)}`,
+    );
+  });
+
+  return {
+    schemaVersion: CURRENT_DOCUMENT_SNAPSHOT_VERSION,
+    records: repairDocumentRecords(records, shapeUtils),
+  };
+}
+
+export function parseSessionSnapshot(snapshot: unknown): SessionSnapshot {
+  const envelope = getSnapshotEnvelope(snapshot, "session");
+  const record = envelope.records[0];
+  if (!isObject(record)) {
+    return {
+      schemaVersion: CURRENT_SESSION_SNAPSHOT_VERSION,
+      records: [createDefaultSession()],
+    };
+  }
+
+  const fallback = createDefaultSession();
+  const currentPageId =
+    typeof record.currentPageId === "string" &&
+    record.currentPageId.startsWith("page:")
+      ? (record.currentPageId as SessionRecord["currentPageId"])
+      : fallback.currentPageId;
+  const parsedCameraById = parseCameraMap(record.pageCameraById);
+  const parsedSelectionById = parseSelectionMap(
+    record.pageSelectedShapeIdsById,
+  );
+  const session: SessionRecord = {
+    ...fallback,
+    id: fallback.id,
+    typeName: "session",
+    scope: "session",
+    currentPageId,
+    activeToolId: asString(record.activeToolId, fallback.activeToolId),
+    isToolLocked:
+      typeof record.isToolLocked === "boolean"
+        ? record.isToolLocked
+        : fallback.isToolLocked,
+    editingShapeId: null,
+    shapeEditingSession: null,
+    pageCameraById:
+      Object.keys(parsedCameraById).length > 0
+        ? parsedCameraById
+        : fallback.pageCameraById,
+    pageSelectedShapeIdsById:
+      Object.keys(parsedSelectionById).length > 0
+        ? parsedSelectionById
+        : fallback.pageSelectedShapeIdsById,
+    meta: asMeta(record.meta),
+  };
+
+  return {
+    schemaVersion: CURRENT_SESSION_SNAPSHOT_VERSION,
+    records: [session],
+  };
+}