@yuzhouu/canvas-kit 0.1.2

package/_vendor/canvas-core/editor/commands.ts

@@ -0,0 +1,833 @@
+import type { Editor } from "./Editor";
+import type { ChangeSource } from "@land/store";
+import type {
+  AssetId,
+  AssetRecord,
+  AssetRecordBase,
+  BindingId,
+  BindingRecordBase,
+  BindingRecord,
+  Camera,
+  PageId,
+  PageRecord,
+  ShapeId,
+  ShapeParentId,
+  ShapeRecordBase,
+  ShapeRecord,
+  ShapeEditingEntryMode,
+} from "../schema/records";
+import { getEditorStore } from "./internal";
+
+export interface EditorCommandOptions {
+  source?: ChangeSource;
+}
+
+export interface CreateShapeInput {
+  type: ShapeRecordBase["type"];
+  x: number;
+  y: number;
+  props?: Record<string, unknown>;
+  parentId?: ShapeParentId;
+  index?: string;
+  opacity?: number;
+  isHidden?: boolean;
+  rotation?: number;
+  scaleX?: number;
+  scaleY?: number;
+  isLocked?: boolean;
+  meta?: Record<string, unknown>;
+}
+
+export interface CreateAssetInput {
+  id?: AssetId;
+  type: AssetRecordBase["type"];
+  props?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface UpdateAssetInput {
+  id: AssetId;
+  props?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface ShapeUpdate {
+  id: ShapeId;
+  x?: number;
+  y?: number;
+  rotation?: number;
+  scaleX?: number;
+  scaleY?: number;
+  isHidden?: boolean;
+  isLocked?: boolean;
+  parentId?: ShapeParentId;
+  index?: string;
+  props?: Record<string, unknown>;
+}
+
+export interface ReparentShapesInput {
+  ids: ShapeId[];
+  parentId: ShapeParentId;
+}
+
+export interface StartEditingShapeInput {
+  shapeId: ShapeId;
+  entryMode?: ShapeEditingEntryMode;
+  caretPagePoint?: { x: number; y: number };
+  markId?: string;
+  reuseExistingMark?: boolean;
+  preserveInteraction?: boolean;
+}
+
+export interface CreateBindingInput {
+  id?: BindingId;
+  type: BindingRecordBase["type"];
+  fromId: ShapeId;
+  toId: ShapeId;
+  props?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface UpdateBindingInput {
+  id: BindingId;
+  fromId?: ShapeId;
+  toId?: ShapeId;
+  props?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface CreatePageInput {
+  name?: string;
+  index?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface RenamePageInput {
+  id: PageId;
+  name: string;
+}
+
+export interface MovePageInput {
+  id: PageId;
+  toIndex: number;
+}
+
+export interface SetCameraInput {
+  pageId?: PageId;
+  camera: Partial<Camera>;
+}
+
+export interface EditorCommands {
+  createPage(
+    input?: CreatePageInput,
+    options?: EditorCommandOptions,
+  ): PageRecord;
+  deletePage(id: PageId, options?: EditorCommandOptions): boolean;
+  renamePage(input: RenamePageInput, options?: EditorCommandOptions): void;
+  movePage(input: MovePageInput, options?: EditorCommandOptions): void;
+  createShapes(
+    inputs: CreateShapeInput[],
+    options?: EditorCommandOptions,
+  ): ShapeRecord[];
+  /**
+   * Persist already-built shape records (with their existing ids) through the
+   * command pipeline. Used by paste/duplicate where ids must be assigned before
+   * parent/binding remapping. Prefer `createShapes` for fresh shapes.
+   */
+  createShapesFromRecords(
+    records: ShapeRecord[],
+    options?: EditorCommandOptions,
+  ): ShapeRecord[];
+  updateShapes(updates: ShapeUpdate[], options?: EditorCommandOptions): void;
+  reparentShapes(
+    input: ReparentShapesInput,
+    options?: EditorCommandOptions,
+  ): void;
+  deleteShapes(ids: ShapeId[], options?: EditorCommandOptions): void;
+  createAsset(
+    input: CreateAssetInput,
+    options?: EditorCommandOptions,
+  ): AssetRecord;
+  /**
+   * Persist already-built asset records (with their existing ids) through the
+   * command pipeline. Used by paste/duplicate. Prefer `createAsset` otherwise.
+   */
+  createAssetsFromRecords(
+    records: AssetRecord[],
+    options?: EditorCommandOptions,
+  ): AssetRecord[];
+  updateAsset(
+    input: UpdateAssetInput,
+    options?: EditorCommandOptions,
+  ): AssetRecord | null;
+  deleteAsset(id: AssetId, options?: EditorCommandOptions): boolean;
+  createBinding(
+    input: CreateBindingInput,
+    options?: EditorCommandOptions,
+  ): BindingRecord;
+  updateBinding(
+    input: UpdateBindingInput,
+    options?: EditorCommandOptions,
+  ): BindingRecord | null;
+  deleteBinding(id: BindingId, options?: EditorCommandOptions): boolean;
+  setCurrentPageId(id: PageId, options?: EditorCommandOptions): void;
+  setCamera(input: SetCameraInput, options?: EditorCommandOptions): void;
+  setSelectedShapeIds(ids: ShapeId[], options?: EditorCommandOptions): void;
+  setActiveTool(toolId: string, options?: EditorCommandOptions): void;
+  setToolLocked(locked: boolean, options?: EditorCommandOptions): void;
+}
+
+export function createEditorCommands(editor: Editor): EditorCommands {
+  return {
+    createPage(input, options) {
+      return createPage(editor, input, options);
+    },
+    deletePage(id, options) {
+      return deletePage(editor, id, options);
+    },
+    renamePage(input, options) {
+      renamePage(editor, input, options);
+    },
+    movePage(input, options) {
+      movePage(editor, input, options);
+    },
+    createShapes(inputs, options) {
+      return createShapes(editor, inputs, options);
+    },
+    createShapesFromRecords(records, options) {
+      return createShapesFromRecords(editor, records, options);
+    },
+    updateShapes(updates, options) {
+      updateShapes(editor, updates, options);
+    },
+    reparentShapes(input, options) {
+      reparentShapes(editor, input, options);
+    },
+    deleteShapes(ids, options) {
+      deleteShapes(editor, ids, options);
+    },
+    createAsset(input, options) {
+      return createAsset(editor, input, options);
+    },
+    createAssetsFromRecords(records, options) {
+      return createAssetsFromRecords(editor, records, options);
+    },
+    updateAsset(input, options) {
+      return updateAsset(editor, input, options);
+    },
+    deleteAsset(id, options) {
+      return deleteAsset(editor, id, options);
+    },
+    createBinding(input, options) {
+      return createBinding(editor, input, options);
+    },
+    updateBinding(input, options) {
+      return updateBinding(editor, input, options);
+    },
+    deleteBinding(id, options) {
+      return deleteBinding(editor, id, options);
+    },
+    setCurrentPageId(id, options) {
+      setCurrentPageId(editor, id, options);
+    },
+    setCamera(input, options) {
+      setCamera(editor, input, options);
+    },
+    setSelectedShapeIds(ids, options) {
+      setSelectedShapeIds(editor, ids, options);
+    },
+    setActiveTool(toolId, options) {
+      setActiveTool(editor, toolId, options);
+    },
+    setToolLocked(locked, options) {
+      setToolLocked(editor, locked, options);
+    },
+  };
+}
+
+function normalizePageOrder(pages: PageRecord[]): PageRecord[] {
+  return pages.map((page, index) => ({
+    ...page,
+    index: String(index + 1).padStart(4, "0"),
+  }));
+}
+
+function createPage(
+  editor: Editor,
+  input?: CreatePageInput,
+  options?: EditorCommandOptions,
+): PageRecord {
+  const source = options?.source ?? "user";
+  const nextPage = editor.createPageRecord(input);
+  let createdPage = nextPage;
+
+  getEditorStore(editor).atomic(() => {
+    const pages = normalizePageOrder([...editor.getPages(), nextPage]);
+    createdPage = pages.find((page) => page.id === nextPage.id) ?? nextPage;
+    getEditorStore(editor).put(pages, source);
+    editor.ensurePageSessionState(createdPage.id, source);
+  }, source);
+
+  return createdPage;
+}
+
+function deletePage(
+  editor: Editor,
+  id: PageId,
+  options?: EditorCommandOptions,
+): boolean {
+  const source = options?.source ?? "user";
+  const pages = editor.getPages();
+  if (pages.length <= 1) {
+    return false;
+  }
+
+  const pageIndex = pages.findIndex((page) => page.id === id);
+  if (pageIndex < 0) {
+    return false;
+  }
+
+  const shapeIds = editor.getShapesForPage(id).map((shape) => shape.id);
+  const nextPages = normalizePageOrder(pages.filter((page) => page.id !== id));
+  const fallbackPageId =
+    pages[pageIndex + 1]?.id ?? pages[pageIndex - 1]?.id ?? pages[0]?.id;
+  const nextCurrentPageId =
+    editor.getCurrentPageId() === id && fallbackPageId
+      ? fallbackPageId
+      : editor.getCurrentPageId();
+
+  getEditorStore(editor).atomic(() => {
+    if (shapeIds.length > 0) {
+      deleteShapes(editor, shapeIds, options);
+    }
+    getEditorStore(editor).remove([id], source);
+    editor.removePageSessionState(id, nextCurrentPageId, source);
+    getEditorStore(editor).put(nextPages, source);
+  }, source);
+
+  return true;
+}
+
+function renamePage(
+  editor: Editor,
+  input: RenamePageInput,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "user";
+  const current = editor.getPage(input.id);
+  if (!current) {
+    return;
+  }
+
+  const name = input.name.trim();
+  if (!name || name === current.name) {
+    return;
+  }
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put([{ ...current, name }], source);
+  }, source);
+}
+
+function movePage(
+  editor: Editor,
+  input: MovePageInput,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "user";
+  const pages = editor.getPages();
+  const fromIndex = pages.findIndex((page) => page.id === input.id);
+  if (fromIndex < 0) {
+    return;
+  }
+
+  const toIndex = Math.max(0, Math.min(input.toIndex, pages.length - 1));
+  if (fromIndex === toIndex) {
+    return;
+  }
+
+  const nextPages = [...pages];
+  const [movedPage] = nextPages.splice(fromIndex, 1);
+  if (!movedPage) {
+    return;
+  }
+  nextPages.splice(toIndex, 0, movedPage);
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put(normalizePageOrder(nextPages), source);
+  }, source);
+}
+
+function createShapes(
+  editor: Editor,
+  inputs: CreateShapeInput[],
+  options?: EditorCommandOptions,
+): ShapeRecord[] {
+  const created: ShapeRecord[] = [];
+  const source = options?.source ?? "user";
+
+  getEditorStore(editor).atomic(() => {
+    const records = inputs.map((input) => {
+      const record = editor.createShapeRecord(input);
+      if (source !== "user" || input.parentId) {
+        return record;
+      }
+
+      const parentId = editor.getContainingParentIdForShapeRecord(record);
+      return parentId && parentId !== record.parentId
+        ? ({ ...record, parentId } as ShapeRecord)
+        : record;
+    });
+    created.push(...records);
+    getEditorStore(editor).put(records, source);
+  }, source);
+
+  return created;
+}
+
+function createShapesFromRecords(
+  editor: Editor,
+  records: ShapeRecord[],
+  options?: EditorCommandOptions,
+): ShapeRecord[] {
+  const source = options?.source ?? "user";
+  if (records.length === 0) {
+    return [];
+  }
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put(records, source);
+  }, source);
+
+  return records;
+}
+
+export function reparentShapeToContainingParent(
+  editor: Editor,
+  shapeId: ShapeId,
+  options?: EditorCommandOptions,
+): void {
+  const shape = editor.getShape(shapeId);
+  if (!shape) {
+    return;
+  }
+
+  const parentId = editor.getContainingParentIdForShapeRecord(shape);
+  if (!parentId || parentId === shape.parentId) {
+    return;
+  }
+
+  editor.commands.reparentShapes({ ids: [shapeId], parentId }, options);
+}
+
+function updateShapes(
+  editor: Editor,
+  updates: ShapeUpdate[],
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "user";
+
+  getEditorStore(editor).atomic(() => {
+    const nextRecords: ShapeRecord[] = [];
+    const changes: Array<{ before: ShapeRecord; after: ShapeRecord }> = [];
+    for (const update of updates) {
+      const current = editor.getShape(update.id);
+      if (!current) continue;
+
+      const nextX = update.x ?? current.x;
+      const nextY = update.y ?? current.y;
+      const nextRotation = update.rotation ?? current.rotation;
+      const nextScaleX = update.scaleX ?? current.scaleX;
+      const nextScaleY = update.scaleY ?? current.scaleY;
+      const nextIsHidden = update.isHidden ?? current.isHidden;
+      const nextIsLocked = update.isLocked ?? current.isLocked;
+      const nextParentId = update.parentId ?? current.parentId;
+      const nextIndex = update.index ?? current.index;
+
+      if (!editor.canUseShapeParent(nextParentId, current.id)) {
+        throw new Error(`Invalid parent id for shape ${current.id}`);
+      }
+
+      if (
+        !update.props &&
+        nextX === current.x &&
+        nextY === current.y &&
+        nextRotation === current.rotation &&
+        nextScaleX === current.scaleX &&
+        nextScaleY === current.scaleY &&
+        nextIsHidden === current.isHidden &&
+        nextIsLocked === current.isLocked &&
+        nextParentId === current.parentId &&
+        nextIndex === current.index
+      ) {
+        continue;
+      }
+
+      const util = editor.shapeUtils.get(current.type);
+      const nextRecord: ShapeRecord = {
+        ...current,
+        x: nextX,
+        y: nextY,
+        rotation: nextRotation,
+        scaleX: nextScaleX,
+        scaleY: nextScaleY,
+        isHidden: nextIsHidden,
+        isLocked: nextIsLocked,
+        parentId: nextParentId,
+        index: nextIndex,
+        props: update.props
+          ? util.validateProps({
+              ...current.props,
+              ...update.props,
+            })
+          : current.props,
+      } as ShapeRecord;
+      nextRecords.push(nextRecord);
+      changes.push({ before: current, after: nextRecord });
+    }
+
+    if (nextRecords.length === 0) {
+      return;
+    }
+
+    getEditorStore(editor).put(nextRecords, source);
+    editor.bindings.handleShapeChanges(changes, source);
+    syncTransformDescendantAncestorBounds(editor, changes, source);
+  }, source);
+}
+
+function syncTransformDescendantAncestorBounds(
+  editor: Editor,
+  changes: Array<{ before: ShapeRecord; after: ShapeRecord }>,
+  source: ChangeSource,
+): void {
+  const changedIds = new Set(changes.map((change) => change.after.id));
+  const ancestorIds = new Set<ShapeId>();
+  for (const change of changes) {
+    collectTransformDescendantAncestorIds(editor, change.before, ancestorIds);
+    collectTransformDescendantAncestorIds(editor, change.after, ancestorIds);
+  }
+
+  const updates: ShapeRecord[] = [];
+  const bindingChanges: Array<{ before: ShapeRecord; after: ShapeRecord }> = [];
+  for (const ancestorId of ancestorIds) {
+    if (changedIds.has(ancestorId)) {
+      continue;
+    }
+
+    const ancestor = editor.getShape(ancestorId);
+    if (!ancestor || ancestor.rotation !== 0 || ancestor.scaleX !== 1 || ancestor.scaleY !== 1) {
+      continue;
+    }
+
+    const bounds = editor.getDescendantPageBounds(ancestor.id);
+    if (!bounds) {
+      continue;
+    }
+
+    const props = ancestor.props as Record<string, unknown>;
+    if (typeof props.w !== "number" || typeof props.h !== "number") {
+      continue;
+    }
+
+    if (
+      ancestor.x === bounds.x &&
+      ancestor.y === bounds.y &&
+      props.w === bounds.w &&
+      props.h === bounds.h
+    ) {
+      continue;
+    }
+
+    const util = editor.shapeUtils.get(ancestor.type);
+    const nextRecord = {
+      ...ancestor,
+      x: bounds.x,
+      y: bounds.y,
+      props: util.validateProps({
+        ...props,
+        w: bounds.w,
+        h: bounds.h,
+      }),
+    } as ShapeRecord;
+    updates.push(nextRecord);
+    bindingChanges.push({ before: ancestor, after: nextRecord });
+  }
+
+  if (updates.length === 0) {
+    return;
+  }
+
+  getEditorStore(editor).put(updates, source);
+  editor.bindings.handleShapeChanges(bindingChanges, source);
+}
+
+function collectTransformDescendantAncestorIds(
+  editor: Editor,
+  shape: ShapeRecord,
+  ids: Set<ShapeId>,
+): void {
+  const seen = new Set<ShapeId>([shape.id]);
+  let parentId = shape.parentId;
+  while (parentId.startsWith("shape:")) {
+    const parent = editor.getShape(parentId as ShapeId);
+    if (!parent || seen.has(parent.id)) {
+      return;
+    }
+    seen.add(parent.id);
+    if (editor.getShapeUtil(parent).shouldTransformDescendants(parent)) {
+      ids.add(parent.id);
+    }
+    parentId = parent.parentId;
+  }
+}
+
+function reparentShapes(
+  editor: Editor,
+  input: ReparentShapesInput,
+  options?: EditorCommandOptions,
+): void {
+  const ids = Array.from(new Set(input.ids));
+  if (ids.length === 0) {
+    return;
+  }
+
+  updateShapes(
+    editor,
+    ids.map((id) => ({ id, parentId: input.parentId })),
+    options,
+  );
+}
+
+function deleteShapes(
+  editor: Editor,
+  ids: ShapeId[],
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "user";
+  const idsWithDescendants = editor.getShapeIdsIncludingDescendants(ids);
+  const assetIdsToCleanup = editor.getUnreferencedAssetIdsAfterShapeDelete(
+    idsWithDescendants,
+  );
+
+  getEditorStore(editor).atomic(() => {
+    editor.sideEffects.runBeforeDelete(
+      "shape",
+      idsWithDescendants,
+      source,
+    );
+    getEditorStore(editor).remove(idsWithDescendants, source);
+    if (assetIdsToCleanup.length > 0) {
+      getEditorStore(editor).remove(assetIdsToCleanup, source);
+    }
+    editor.sideEffects.runAfterDelete("shape", idsWithDescendants, source);
+  }, source);
+}
+
+function createAsset(
+  editor: Editor,
+  input: CreateAssetInput,
+  options?: EditorCommandOptions,
+): AssetRecord {
+  const source = options?.source ?? "user";
+  const asset = editor.createAssetRecord(input);
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put([asset], source);
+  }, source);
+
+  return asset;
+}
+
+function createAssetsFromRecords(
+  editor: Editor,
+  records: AssetRecord[],
+  options?: EditorCommandOptions,
+): AssetRecord[] {
+  const source = options?.source ?? "user";
+  if (records.length === 0) {
+    return [];
+  }
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put(records, source);
+  }, source);
+
+  return records;
+}
+
+function updateAsset(
+  editor: Editor,
+  input: UpdateAssetInput,
+  options?: EditorCommandOptions,
+): AssetRecord | null {
+  const source = options?.source ?? "user";
+  const current = editor.getAsset(input.id);
+  if (!current) {
+    return null;
+  }
+
+  const next: AssetRecord = {
+    ...current,
+    props: input.props ? { ...current.props, ...input.props } : current.props,
+    meta: input.meta ?? current.meta,
+  };
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).put([next], source);
+  }, source);
+
+  return next;
+}
+
+function deleteAsset(
+  editor: Editor,
+  id: AssetId,
+  options?: EditorCommandOptions,
+): boolean {
+  const source = options?.source ?? "user";
+  if (!editor.getAsset(id)) {
+    return false;
+  }
+
+  getEditorStore(editor).atomic(() => {
+    getEditorStore(editor).remove([id], source);
+  }, source);
+
+  return true;
+}
+
+function canWriteBinding(editor: Editor, binding: BindingRecord): boolean {
+  return editor.bindings.canBind(binding);
+}
+
+function createBinding(
+  editor: Editor,
+  input: CreateBindingInput,
+  options?: EditorCommandOptions,
+): BindingRecord {
+  const source = options?.source ?? "user";
+  const binding = editor.createBindingRecord(input);
+  if (!canWriteBinding(editor, binding)) {
+    throw new Error(`Invalid binding endpoints for ${binding.type} binding`);
+  }
+
+  getEditorStore(editor).atomic(() => {
+    const conflictingIds = editor.bindings
+      .getConflictingBindings(binding)
+      .map((candidate) => candidate.id);
+    if (conflictingIds.length > 0) {
+      editor.bindings.cleanupBindings(conflictingIds, source);
+    }
+    getEditorStore(editor).put([binding], source);
+    editor.bindings.syncCreatedBinding(binding, source);
+  }, source);
+
+  return binding;
+}
+
+function updateBinding(
+  editor: Editor,
+  input: UpdateBindingInput,
+  options?: EditorCommandOptions,
+): BindingRecord | null {
+  const source = options?.source ?? "user";
+  const current = editor.getBinding(input.id);
+  if (!current) {
+    return null;
+  }
+
+  const util = editor.getBindingUtil(current);
+  const next: BindingRecord = {
+    ...current,
+    fromId: input.fromId ?? current.fromId,
+    toId: input.toId ?? current.toId,
+    props: input.props
+      ? util.validateProps({ ...current.props, ...input.props })
+      : current.props,
+    meta: input.meta ?? current.meta,
+  };
+  if (!canWriteBinding(editor, next)) {
+    throw new Error(`Invalid binding endpoints for ${next.type} binding`);
+  }
+
+  getEditorStore(editor).atomic(() => {
+    const conflictingIds = editor.bindings
+      .getConflictingBindings(next)
+      .map((candidate) => candidate.id);
+    if (conflictingIds.length > 0) {
+      editor.bindings.cleanupBindings(conflictingIds, source);
+    }
+    getEditorStore(editor).put([next], source);
+    editor.bindings.syncUpdatedBinding(current, next, source);
+  }, source);
+
+  return next;
+}
+
+function deleteBinding(
+  editor: Editor,
+  id: BindingId,
+  options?: EditorCommandOptions,
+): boolean {
+  const source = options?.source ?? "user";
+  const binding = editor.getBinding(id);
+  if (!binding) {
+    return false;
+  }
+
+  getEditorStore(editor).atomic(() => {
+    editor.bindings.cleanupBindings([binding.id], source);
+    getEditorStore(editor).remove([binding.id], source);
+  }, source);
+
+  return true;
+}
+
+function setCurrentPageId(
+  editor: Editor,
+  id: PageId,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "system";
+  editor.setCurrentPage(id, source);
+}
+
+function setCamera(
+  editor: Editor,
+  input: SetCameraInput,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "system";
+  editor.setCamera(input.camera, { pageId: input.pageId, source });
+}
+
+function setSelectedShapeIds(
+  editor: Editor,
+  ids: ShapeId[],
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "user";
+  editor.setSelectedShapeIds(ids, { source });
+}
+
+function setActiveTool(
+  editor: Editor,
+  toolId: string,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "system";
+  editor.completeEditing(source);
+  editor.tools.setActiveTool(toolId);
+  editor.updateSession({ activeToolId: toolId }, source);
+}
+
+function setToolLocked(
+  editor: Editor,
+  locked: boolean,
+  options?: EditorCommandOptions,
+): void {
+  const source = options?.source ?? "system";
+  editor.tools.setToolLocked(locked);
+  editor.updateSession({ isToolLocked: locked }, source);
+}