Skip to content

AI-native design editor. Open-source Figma alternative.

28.5 KB
Raw Blame
/* eslint-disable max-lines -- SceneGraph is the facade over the domain modules */
import { omitBy, pick } from 'es-toolkit/object'
import { isUndefined } from 'es-toolkit/predicate'

import { removeStaleBindings } from './bindings'
import { BufferedSceneEmitter } from './buffered-events'
import {
  getAbsolutePosition,
  getNodeLocalMatrix,
  getParentWorldMatrix,
  isTranslationOnly,
  localTransformFromWorld
} from './coordinate'
import { cloneNodeProps, type NodeCloneMode } from './copy'
import { bindNodeEvents } from './events'
import { TRANSFORM_FIELDS } from './fields/geometry'
import { LAYOUT_AFFECTING_KEYS } from './fields/layout'
import { withGeneratedFrameSize } from './generated'
import * as HitTest from './hit-test'
import { generateId } from './ids'
import * as Instances from './instances'
import { LayoutWrites } from './layout/writes'
import Matrix from './matrix'
import { CONTAINER_TYPES, createDefaultNode } from './node-defaults'
import { updateNodePreview, type NodePreviewObserver } from './preview'
import type { Color, Rect, Vector } from './primitives'
import { markSourceFieldsEdited } from './source-metadata'
import { textCacheInvalidationChanges } from './text/picture'
import { remapCopiedReferences } from './transfer/copied'
import type {
  DocumentColorSpace,
  DocumentKind,
  EnabledLibraryBinding,
  NodeChangeObserver,
  NodeType,
  SceneGraphEventHandlers,
  SceneNode,
  Variable,
  VariableCollection,
  VariableType,
  VariableValue,
  VariableLiteral
} from './types'
import * as Variables from './variables'
import type { VariableModeFallback } from './variables'
import { normalizeVectorNetwork } from './vector-network'

/** Scopes that graph methods check while a caller's callback runs; scopes nest. */
type GraphScope = 'preview' | 'sourceMetadata' | 'importedState' | 'layout' | 'derivedLayout'

export class SceneGraph {
  nodes = new Map<string, SceneNode>()
  images = new Map<string, Uint8Array>()
  variables = new Map<string, Variable>()
  variableCollections = new Map<string, VariableCollection>()
  activeMode = new Map<string, string>()
  rootId: string
  figKiwiVersion: number | null = null
  /** Deflated kiwi schema bytes from the original .fig file, preserved for roundtrip fidelity. */
  figSchemaDeflated: Uint8Array | null = null
  documentColorSpace: DocumentColorSpace = 'srgb'
  documentKind: DocumentKind = 'design'
  enabledLibraries = new Map<string, EnabledLibraryBinding>()
  readonly emitter = new BufferedSceneEmitter()
  private absPosCache = new Map<string, Vector>()
  private readonly scopeDepths: Record<GraphScope, number> = {
    preview: 0,
    sourceMetadata: 0,
    importedState: 0,
    layout: 0,
    derivedLayout: 0
  }
  private previewObservers: NodePreviewObserver[] = []
  private readonly changeObservers = new Set<NodeChangeObserver>()
  private importedIdGenerator: (() => string) | undefined
  private layoutWrites: LayoutWrites | null = null
  positionPreviewVersion = 0
  instanceIndex = new Map<string, Set<string>>()
  /** Every connector in the graph, so routing need not scan every layer. */
  connectorIds = new Set<string>()

  constructor(private readonly idGenerator: () => string = generateId) {
    const root = createDefaultNode(this.idGenerator, 'FRAME', {
      name: 'Document',
      width: 0,
      height: 0
    })
    this.rootId = root.id
    this.nodes.set(root.id, root)

    this.addPage('Page 1')
  }
  addPage(name: string): SceneNode {
    return this.createNode('CANVAS', this.rootId, { name, width: 0, height: 0 })
  }

  getPages(includeInternal = false): SceneNode[] {
    return this.getChildren(this.rootId).filter(
      (n) => n.type === 'CANVAS' && (includeInternal || !n.internalOnly)
    )
  }
  getAllNodes(): Iterable<SceneNode> {
    return this.nodes.values()
  }
  getNode(id: string): SceneNode | undefined {
    return this.nodes.get(id)
  }
  onNodeEvents(handlers: SceneGraphEventHandlers): () => void {
    return bindNodeEvents(this.emitter, handlers)
  }

  /**
   * Tells `observer` about each node an edit adds and, before it changes, each node it is about
   * to change, so a recorder can keep the node as it was. Unlike node events these are never
   * buffered. Graph methods report the nodes they change; code that writes into a node directly
   * reports it with `willChangeNode` first.
   */
  observeNodeChanges(observer: NodeChangeObserver): () => void {
    this.changeObservers.add(observer)
    return () => this.changeObservers.delete(observer)
  }

  /** Tells `observeNodeChanges` observers that `node` is about to change. */
  willChangeNode(node: SceneNode | undefined): void {
    if (!node) return
    for (const observer of this.changeObservers) observer.before(node)
  }

  countDescendants(nodeId: string): number {
    const node = this.nodes.get(nodeId)
    if (!node) return 0
    let count = 0
    const stack = [...node.childIds]
    while (stack.length > 0) {
      const id = stack.pop()
      if (id === undefined) break
      count++
      const child = this.nodes.get(id)
      if (child) {
        for (const childId of child.childIds) {
          stack.push(childId)
        }
      }
    }
    return count
  }
  addVariable(variable: Variable): void {
    Variables.addVariable(this, variable)
  }
  removeVariable(id: string): void {
    Variables.removeVariable(this, id)
  }
  addCollection(collection: VariableCollection): void {
    Variables.addCollection(this, collection)
  }
  createVariable(
    name: string,
    type: VariableType,
    collectionId: string,
    value?: VariableValue
  ): Variable {
    return Variables.createVariable(
      this,
      () => this.generateEntityId(),
      name,
      type,
      collectionId,
      value
    )
  }

  createCollection(name: string): VariableCollection {
    // The collection and its default mode are both created before either is registered.
    const issued = new Set<string>()
    return Variables.createCollection(this, () => this.generateEntityId(issued), name)
  }

  createMode(collectionId: string, name: string, sourceModeId?: string): string | undefined {
    return Variables.createMode(
      this,
      () => this.generateEntityId(),
      collectionId,
      name,
      sourceModeId
    )
  }

  removeCollection(id: string): void {
    Variables.removeCollection(this, id)
  }

  getActiveModeId(collectionId: string): string {
    return Variables.getActiveModeId(this, collectionId)
  }

  getNodeVariableModeId(nodeId: string, collectionId: string): string {
    return Variables.getNodeVariableModeId(this, nodeId, collectionId)
  }

  setActiveMode(collectionId: string, modeId: string): void {
    Variables.setActiveMode(this, collectionId, modeId)
  }

  addMode(collectionId: string, modeId: string, name: string, sourceMode?: string): void {
    Variables.addMode(this, collectionId, modeId, name, sourceMode)
  }

  removeMode(collectionId: string, modeId: string): void {
    Variables.removeMode(this, collectionId, modeId)
  }

  renameMode(collectionId: string, modeId: string, name: string): void {
    Variables.renameMode(this, collectionId, modeId, name)
  }

  setDefaultMode(collectionId: string, modeId: string): void {
    Variables.setDefaultMode(this, collectionId, modeId)
  }

  resolveVariable(
    variableId: string,
    modeId?: string,
    visited?: Set<string>
  ): VariableLiteral | undefined {
    return Variables.resolveVariable(this, variableId, modeId, visited)
  }

  resolveColorVariable(variableId: string): Color | undefined {
    return Variables.resolveColorVariable(this, variableId)
  }

  resolveNumberVariable(variableId: string): number | undefined {
    return Variables.resolveNumberVariable(this, variableId)
  }

  resolveColorVariableForNode(
    nodeId: string,
    variableId: string,
    fallback?: VariableModeFallback
  ): Color | undefined {
    return Variables.resolveColorVariableForNode(this, nodeId, variableId, fallback)
  }

  resolveNumberVariableForNode(
    nodeId: string,
    variableId: string,
    fallback?: VariableModeFallback
  ): number | undefined {
    return Variables.resolveNumberVariableForNode(this, nodeId, variableId, fallback)
  }

  resolveVariableForNode(
    nodeId: string,
    variableId: string,
    fallback?: VariableModeFallback
  ): VariableLiteral | undefined {
    return Variables.resolveVariableForNode(this, nodeId, variableId, fallback)
  }

  resolveStringVariableForNode(
    nodeId: string,
    variableId: string,
    fallback?: VariableModeFallback
  ): string | undefined {
    return Variables.resolveStringVariableForNode(this, nodeId, variableId, fallback)
  }

  getVariablesForCollection(collectionId: string): Variable[] {
    return Variables.getVariablesForCollection(this, collectionId)
  }

  getVariablesByType(type: VariableType): Variable[] {
    return Variables.getVariablesByType(this, type)
  }

  bindVariable(nodeId: string, field: string, variableId: string): void {
    Variables.bindVariable(this, nodeId, field, variableId)
  }

  unbindVariable(nodeId: string, field: string): void {
    Variables.unbindVariable(this, nodeId, field)
  }

  getChildren(id: string): SceneNode[] {
    const node = this.nodes.get(id)
    if (!node) return []
    return node.childIds
      .map((cid) => this.nodes.get(cid))
      .filter((n): n is SceneNode => n !== undefined)
  }

  isContainer(id: string): boolean {
    const node = this.nodes.get(id)
    return node ? CONTAINER_TYPES.has(node.type) : false
  }

  isDescendant(childId: string, ancestorId: string): boolean {
    return this.closest(childId, (node) => node.id === ancestorId) !== undefined
  }

  /**
   * The node itself or its nearest ancestor that matches. The walk visits at most as many nodes
   * as the graph holds, so a parent cycle in bad data cannot hang it.
   */
  closest(id: string, match: (node: SceneNode) => boolean): SceneNode | undefined {
    let current = this.nodes.get(id)
    for (let steps = 0; current && steps < this.nodes.size; steps++) {
      if (match(current)) return current
      current = current.parentId ? this.nodes.get(current.parentId) : undefined
    }
    return undefined
  }

  /**
   * The page a node is on: the node itself for a page, its nearest page ancestor otherwise, and
   * null for the document root or a node on no page.
   */
  pageOf(id: string): string | null {
    return this.closest(id, (node) => node.type === 'CANVAS')?.id ?? null
  }

  clearAbsPosCache(): void {
    this.absPosCache.clear()
  }

  getAbsolutePosition(id: string): Vector {
    const cached = this.absPosCache.get(id)
    if (cached) return cached

    const node = this.getNode(id)
    if (!node) return { x: 0, y: 0 }

    const result = getAbsolutePosition(node, this)
    this.absPosCache.set(id, result)
    return result
  }

  getAbsoluteBounds(id: string): Rect {
    const pos = this.getAbsolutePosition(id)
    const node = this.nodes.get(id)
    return {
      x: pos.x,
      y: pos.y,
      width: node?.width ?? 0,
      height: node?.height ?? 0
    }
  }
  /**
   * An ID no entity uses; `issued` also excludes IDs handed out earlier in the same creation.
   * A generator that returns more taken IDs than the graph holds must be repeating itself, so
   * it counts as exhausted then; a fixed cap would reject a sequence walking past a large import.
   */
  private generateEntityId(issued?: Set<string>): string {
    let limit = Infinity
    for (let attempt = 0; attempt < limit; attempt++) {
      const id = (this.importedIdGenerator ?? this.idGenerator)()
      if (this.isEntityIdTaken(id) || issued?.has(id)) {
        if (limit === Infinity) limit = this.entityIdCount() + (issued?.size ?? 0) + 1
        continue
      }
      issued?.add(id)
      return id
    }
    throw new Error('The ID generator only returned IDs that are in use')
  }
  private entityIdCount(): number {
    let count = this.nodes.size + this.variables.size + this.variableCollections.size
    for (const collection of this.variableCollections.values()) count += collection.modes.length
    return count
  }
  /** Whether a node, variable, collection, or mode has this id. */
  isEntityIdTaken(id: string): boolean {
    if (this.nodes.has(id) || this.variables.has(id) || this.variableCollections.has(id))
      return true
    // Callers replace collection maps and edit `modes` in place (history snapshots, transfer,
    // undo), so an index of mode IDs would go stale; walk them without allocating instead.
    for (const collection of this.variableCollections.values()) {
      for (const mode of collection.modes) if (mode.modeId === id) return true
    }
    return false
  }
  private indexInstance(componentId: string, instanceId: string): void {
    let set = this.instanceIndex.get(componentId)
    if (!set) {
      set = new Set()
      this.instanceIndex.set(componentId, set)
    }
    set.add(instanceId)
  }
  private unindexInstance(componentId: string, instanceId: string): void {
    this.instanceIndex.get(componentId)?.delete(instanceId)
  }
  private registerNode(node: SceneNode, parentId: string | null): SceneNode {
    node.parentId = parentId
    this.nodes.set(node.id, node)
    if (node.type === 'CONNECTOR') this.connectorIds.add(node.id)
    for (const observer of this.changeObservers) observer.created(node)
    if (node.type === 'INSTANCE' && node.componentId) this.indexInstance(node.componentId, node.id)
    this.emitter.emit('node:created', node)
    return node
  }
  /** Publish synchronous graph events only after the supplied mutation succeeds. */
  withBufferedEvents<T>(action: () => T): T {
    return this.emitter.batch(action)
  }

  createNode(type: NodeType, parentId: string, overrides: Partial<SceneNode> = {}): SceneNode {
    const node = createDefaultNode(() => this.generateEntityId(), type, overrides)
    const parent = this.nodes.get(parentId)
    this.willChangeNode(parent)
    parent?.childIds.push(node.id)
    return this.registerNode(node, parentId)
  }
  createNodeWithId(
    id: string,
    type: NodeType,
    parentId: string | null,
    overrides: Partial<SceneNode> = {}
  ): SceneNode {
    const node = createDefaultNode(() => id, type, overrides)
    // `overrides` may be another node's snapshot, ID included.
    node.id = id
    const parent = parentId ? this.nodes.get(parentId) : undefined
    if (parent && !parent.childIds.includes(id)) {
      this.willChangeNode(parent)
      parent.childIds.push(id)
    }
    return this.registerNode(node, parentId)
  }

  private withScope<T>(scope: GraphScope, fn: () => T): T {
    this.scopeDepths[scope]++
    try {
      return fn()
    } finally {
      this.scopeDepths[scope]--
    }
  }

  runPreviewUpdates(fn: () => void, beforeUpdate?: NodePreviewObserver): void {
    if (beforeUpdate) this.previewObservers.push(beforeUpdate)
    try {
      this.withScope('preview', fn)
    } finally {
      if (beforeUpdate) this.previewObservers.pop()
    }
  }
  preserveSourceMetadataDuring<T>(fn: () => T): T {
    return this.withScope('sourceMetadata', fn)
  }
  get isPreservingSourceMetadata(): boolean {
    return this.scopeDepths.sourceMetadata > 0
  }

  applyImportedStateDuring<T>(fn: () => T, idGenerator?: () => string): T {
    const previousGenerator = this.importedIdGenerator
    this.importedIdGenerator = idGenerator ?? previousGenerator
    try {
      return this.withScope('importedState', () => this.preserveSourceMetadataDuring(fn))
    } finally {
      this.importedIdGenerator = previousGenerator
    }
  }

  get isApplyingImportedState(): boolean {
    return this.scopeDepths.importedState > 0
  }

  /**
   * Lays out what the document already holds: a page as it loads, or again once its fonts
   * arrive. What this writes derives from the document; an edit's own layout is not this.
   */
  applyDerivedLayoutDuring(fn: () => void): void {
    this.withScope('derivedLayout', fn)
  }

  get isApplyingDerivedLayout(): boolean {
    return this.scopeDepths.derivedLayout > 0
  }

  /**
   * Runs `fn` as layout. Its updates are published once the outermost layout ends, still as
   * layout, and without values a pass changed and a later pass put back (`LayoutWrites`). Outside
   * derived layout, the positions and sizes it publishes count as edited, so formats save them.
   */
  withLayoutMutations(fn: () => void): void {
    const outermost = this.scopeDepths.layout === 0
    this.scopeDepths.layout++
    if (outermost) this.layoutWrites = new LayoutWrites()
    try {
      fn()
    } finally {
      try {
        if (outermost) this.publishLayoutUpdates()
      } finally {
        this.scopeDepths.layout--
      }
    }
  }

  private publishLayoutUpdates(): void {
    const writes = this.layoutWrites
    this.layoutWrites = null
    if (!writes) return
    for (const [node, changes, edited] of writes.updates((nodeId) => this.nodes.get(nodeId))) {
      markSourceFieldsEdited(node, edited)
      this.emitter.emit('node:updated', node.id, changes)
    }
  }
  get isApplyingLayout(): boolean {
    return this.scopeDepths.layout > 0
  }
  updateNodePositionPreview(id: string, x: number, y: number): void {
    this.updateNodePreview(id, { x, y })
  }
  updateNodePreview(id: string, changes: Partial<SceneNode>): void {
    const node = this.nodes.get(id)
    if (node) changes = this.sizedChanges(node, changes)
    const appliedChanges = updateNodePreview(this, id, changes, (node, applied) => {
      for (const observe of this.previewObservers) observe(node, applied)
    })
    if (appliedChanges) this.emitter.emit('node:previewUpdated', id, appliedChanges)
  }

  /**
   * Writes fields as given. Edits detach the shared styles whose fields they change before
   * they get here (`styleDetachmentChanges`); resolving bindings or loading a file does not.
   */
  updateNode(id: string, changes: Partial<SceneNode>): void {
    if (this.scopeDepths.preview > 0) {
      this.updateNodePreview(id, changes)
      return
    }

    const node = this.nodes.get(id)
    if (!node) return
    this.applyNodeChanges(node, this.sizedChanges(node, omitBy(changes, isUndefined)))
  }

  /** A size set from outside layout, with what it also sets on a generated frame. */
  private sizedChanges(node: SceneNode, changes: Partial<SceneNode>): Partial<SceneNode> {
    return this.isApplyingLayout ? changes : withGeneratedFrameSize(node, changes)
  }

  /** Replay captured properties without dropping explicit undefined values or absent keys. */
  restoreNodeProperties(
    id: string,
    changes: Partial<SceneNode>,
    absent: readonly (keyof SceneNode)[]
  ): void {
    const node = this.nodes.get(id)
    if (node) this.applyNodeChanges(node, changes, absent)
  }

  private applyNodeChanges(
    node: SceneNode,
    changes: Partial<SceneNode>,
    absent: readonly (keyof SceneNode)[] = []
  ): void {
    const { id } = node
    this.willChangeNode(node)
    // Include removed keys in cache invalidation and update notifications.
    if (absent.length) {
      changes = { ...changes }
      for (const key of absent) Reflect.set(changes, key, undefined)
    }

    // Only clear absPosCache when layout-affecting properties change.
    // Fills, strokes, effects, plugin data changes do NOT affect absolute position.
    const affectsLayout = Object.keys(changes).some((k) => LAYOUT_AFFECTING_KEYS.has(k))
    if (affectsLayout) this.absPosCache.clear()
    if (
      node.type === 'INSTANCE' &&
      'componentId' in changes &&
      changes.componentId !== node.componentId
    ) {
      if (node.componentId) this.unindexInstance(node.componentId, id)
      if (changes.componentId) this.indexInstance(changes.componentId, id)
    }
    this.markEdited(node, Object.keys(changes))
    // Cache resets that change the node travel with the change, under the caller's own values,
    // so a layout put-back cannot drop their event.
    if (node.type === 'TEXT') {
      const resets = omitBy(textCacheInvalidationChanges(node, changes), (value, key) =>
        Object.is(node[key], value)
      )
      changes = { ...resets, ...changes }
    }
    if (changes.vectorNetwork) {
      changes = { ...changes, vectorNetwork: normalizeVectorNetwork(changes.vectorNetwork) }
    }
    this.layoutWrites?.record(
      node,
      changes,
      this.scopeDepths.sourceMetadata === 0 && !this.isApplyingDerivedLayout
    )
    Object.assign(node, changes)
    if (changes.fills) removeStaleBindings(node, 'fills', changes)
    if (changes.strokes) removeStaleBindings(node, 'strokes', changes)
    if (changes.effects) removeStaleBindings(node, 'effects', changes)
    for (const key of absent) Reflect.deleteProperty(node, key)
    this.publishNodeUpdate(id, changes)
  }

  /** Marks fields an edit changed, unless metadata is being restored or layout is writing them. */
  private markEdited(node: SceneNode, keys: string[]): void {
    if (this.scopeDepths.sourceMetadata === 0 && !this.isApplyingLayout) {
      markSourceFieldsEdited(node, keys)
    }
  }

  /** Publishes an update now, or leaves it to the running layout, which publishes once it ends. */
  private publishNodeUpdate(id: string, changes: Partial<SceneNode>): void {
    if (!this.layoutWrites) this.emitter.emit('node:updated', id, changes)
  }

  reparentNode(nodeId: string, newParentId: string): void {
    const node = this.nodes.get(nodeId)
    if (!node || nodeId === this.rootId) return
    if (this.isDescendant(newParentId, nodeId)) return

    const oldParent = node.parentId ? this.nodes.get(node.parentId) : undefined
    const newParent = this.nodes.get(newParentId)
    if (!newParent) return
    if (node.parentId === newParentId) return

    const oldParentId = node.parentId
    this.willChangeNode(node)
    this.willChangeNode(oldParent)
    this.willChangeNode(newParent)
    this.absPosCache.clear()

    const oldParentWorld = getParentWorldMatrix(oldParent, this)
    const newParentWorld = getParentWorldMatrix(newParent, this)

    if (oldParent) {
      oldParent.childIds = oldParent.childIds.filter((cid) => cid !== nodeId)
    }

    node.parentId = newParentId
    newParent.childIds.push(nodeId)

    const before = pick(node, TRANSFORM_FIELDS)
    if (isTranslationOnly(oldParentWorld) && isTranslationOnly(newParentWorld)) {
      node.x += oldParentWorld[2] - newParentWorld[2]
      node.y += oldParentWorld[5] - newParentWorld[5]
    } else {
      const world = Matrix.multiply(oldParentWorld, getNodeLocalMatrix(node))
      const local = localTransformFromWorld(node, world, newParentWorld)
      if (local) Object.assign(node, local)
    }
    // The node keeps its place on the canvas by new coordinates, which a save must write.
    this.markEdited(
      node,
      TRANSFORM_FIELDS.filter((key) => node[key] !== before[key])
    )

    this.emitter.emit('node:reparented', nodeId, oldParentId, newParentId)
  }

  /**
   * Moves a node to `index` among `parentId`'s children, from wherever it was, without changing
   * its own coordinates. An index past the end appends; a move into the node itself or one of
   * its descendants is ignored.
   */
  insertChildAt(childId: string, parentId: string, index: number): void {
    const node = this.nodes.get(childId)
    const newParent = this.nodes.get(parentId)
    if (!node || !newParent || this.isDescendant(parentId, childId)) return
    const previousParentId = node.parentId
    const oldParent = previousParentId ? this.nodes.get(previousParentId) : undefined
    this.willChangeNode(node)
    this.willChangeNode(oldParent)
    this.willChangeNode(newParent)
    if (oldParent) {
      oldParent.childIds = oldParent.childIds.filter((id) => id !== childId)
    }
    newParent.childIds = newParent.childIds.filter((id) => id !== childId)
    const at = Math.min(index, newParent.childIds.length)
    newParent.childIds.splice(at, 0, childId)
    node.parentId = parentId
    this.absPosCache.clear()
    this.emitter.emit('node:reordered', childId, parentId, at, previousParentId)
  }

  deleteNode(id: string): void {
    const node = this.nodes.get(id)
    if (!node || id === this.rootId) return
    this.willChangeNode(node)

    if (node.parentId) {
      const parent = this.nodes.get(node.parentId)
      this.willChangeNode(parent)
      if (parent) {
        parent.childIds = parent.childIds.filter((cid) => cid !== id)
      }
    }

    for (const childId of Array.from(node.childIds)) {
      this.deleteNode(childId)
    }

    if (node.type === 'INSTANCE' && node.componentId) this.unindexInstance(node.componentId, id)
    this.connectorIds.delete(id)
    this.nodes.delete(id)
    this.emitter.emit('node:deleted', id, node.parentId)
  }

  hitTest(px: number, py: number, scopeId?: string): SceneNode | null {
    return HitTest.hitTest(this, px, py, scopeId)
  }

  /** `pad`, in canvas units, grows each shape's box, as Figma takes clicks just outside one. */
  hitTestDeep(px: number, py: number, scopeId?: string, pad = 0): SceneNode | null {
    return HitTest.hitTestDeep(this, px, py, scopeId, pad)
  }

  hitTestSelectable(
    px: number,
    py: number,
    scopeId: string,
    selectedIds: ReadonlySet<string>,
    options?: HitTest.SelectableHitOptions
  ): SceneNode | null {
    return HitTest.hitTestSelectable(this, px, py, scopeId, selectedIds, options)
  }

  hitTestOpenContainer(px: number, py: number, scopeId: string): SceneNode | null {
    return HitTest.hitTestOpenContainer(this, px, py, scopeId)
  }

  isOpenContainer(nodeId: string, framesOpen = true): boolean {
    return HitTest.isOpenContainer(this, nodeId, framesOpen)
  }

  isPointInNode(nodeId: string, px: number, py: number): boolean {
    return HitTest.isPointInNode(this, nodeId, px, py)
  }

  hitTestDropTarget(
    px: number,
    py: number,
    excludeIds: ReadonlySet<string>,
    scopeId?: string,
    options?: HitTest.DropTargetOptions
  ): SceneNode | null {
    return HitTest.hitTestDropTarget(this, px, py, excludeIds, scopeId, options)
  }

  cloneTree(
    sourceId: string,
    parentId: string,
    overrides: Partial<SceneNode> = {}
  ): SceneNode | null {
    const ids = new Map<string, string>()
    const clone = this.cloneSubtree(sourceId, parentId, overrides, ids)
    // Copies point at one another, as a paste's do: an instance at a component cloned with it,
    // as Figma's clone does (desktop 126), and its override records at its copies' new ids.
    remapCopiedReferences(this, ids)
    return clone
  }

  private cloneSubtree(
    sourceId: string,
    parentId: string,
    overrides: Partial<SceneNode>,
    ids: Map<string, string>
  ): SceneNode | null {
    const src = this.nodes.get(sourceId)
    if (!src) return null

    const props = cloneNodeProps(src, null)
    // Null out Figma source identifiers so the clone is treated as local.
    if (props.source) props.source = { ...props.source, id: null, orderKey: null }
    // A copy is a new design nobody has reviewed: Figma's duplicate and clone() drop the status.
    props.status = null
    const clone = this.createNode(src.type, parentId, { ...props, ...overrides })
    if (src.status) markSourceFieldsEdited(clone, ['status'])
    ids.set(src.id, clone.id)

    for (const childId of src.childIds) {
      this.cloneSubtree(childId, clone.id, {}, ids)
    }

    return clone
  }

  createInstance(
    componentId: string,
    parentId: string,
    overrides: Partial<SceneNode> = {}
  ): SceneNode | null {
    return Instances.createInstance(this, componentId, parentId, overrides)
  }

  populateInstanceChildren(
    instanceId: string,
    componentId: string,
    mode: NodeCloneMode = 'deep'
  ): void {
    Instances.populateInstanceChildren(this, instanceId, componentId, mode)
  }

  swapInstanceComponent(
    instanceId: string,
    componentId: string,
    options?: Instances.SwapInstanceOptions
  ): void {
    Instances.swapInstanceComponent(this, instanceId, componentId, options)
  }

  syncInstances(componentId: string): void {
    Instances.syncInstances(this, componentId)
  }

  syncInstancesTogether(componentIds: Iterable<string>): void {
    Instances.syncInstancesTogether(this, componentIds)
  }

  syncInstance(instanceId: string): void {
    Instances.syncInstance(this, instanceId)
  }

  detachInstance(instanceId: string): void {
    Instances.detachInstance(this, instanceId)
  }

  getMainComponent(instanceId: string): SceneNode | undefined {
    return Instances.getMainComponent(this, instanceId)
  }

  getInstances(componentId: string): SceneNode[] {
    return Instances.getInstances(this, componentId)
  }

  flattenTree(parentId?: string, depth = 0): Array<{ node: SceneNode; depth: number }> {
    const id = parentId ?? this.rootId
    const parent = this.nodes.get(id)
    if (!parent) return []
    const result: Array<{ node: SceneNode; depth: number }> = []
    for (const childId of parent.childIds) {
      const child = this.nodes.get(childId)
      if (!child) continue
      result.push({ node: child, depth })
      if (child.childIds.length > 0) result.push(...this.flattenTree(childId, depth + 1))
    }
    return result
  }
}