AI-native design editor. Open-source Figma alternative.
import { isEqual } from 'es-toolkit/predicate'
import type { Effect as KiwiEffect, NodeChange, Paint } from '@open-pencil/kiwi/fig/codec'
import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
import { scaleGeometryPaths } from '@open-pencil/scene-graph/copy'
import {
bindingOverrideField,
setInstanceOverride,
variableModeOverrideField
} from '@open-pencil/scene-graph/instances/overrides'
import { createDefaultSourceMetadata } from '@open-pencil/scene-graph/node-defaults'
import { EFFECT_BINDING_PROPERTIES, effectBindingField } from '@open-pencil/scene-graph/variables'
import { nodeChangeToProps } from '../node-change'
import { numericVariableBindingScales } from '../node-change/variable/bindings'
import { EFFECT_VARIABLE_FIELDS } from '../node-change/variable/effects'
import { variableModeLayer } from '../node-change/variable/maps'
import {
recordVariableBindingClaims,
occurrenceAssignmentScales,
occurrenceScale
} from './bindings/variables'
import { isClearedStyle } from './cleared-style'
import { OVERRIDE_FIELDS, type OverrideField, type RawOverrideField } from './fields'
import { resolveOccurrencePath } from './interpret'
import type { InstanceOccurrence } from './occurrence/types'
import { symbolDataOf } from './types'
function occurrenceMetadata(
current: InstanceOccurrence,
converted: ReturnType<typeof nodeChangeToProps>
) {
const metadata = createDefaultSourceMetadata()
// Figma's own sibling key, so re-export keeps the order Figma saved.
metadata.orderKey = current.properties.parentIndex?.position ?? null
metadata.fig.layout = converted.source?.fig.layout ?? null
metadata.fig.uniformScaleFactor = symbolDataOf(current.properties)?.uniformScaleFactor ?? null
return metadata
}
/**
* Fields a layer keeps its own: its children, and state written in place, such as its source
* metadata and its override maps.
*/
const OWN_FIELDS = new Set(['childIds', 'source', 'instanceOverrides'])
/** Maps and sets are written in place, so values holding them are never shared. */
function holdsCollections(value: unknown): boolean {
if (value instanceof Map || value instanceof Set) return true
if (value === null || typeof value !== 'object' || ArrayBuffer.isView(value)) return false
return Object.values(value).some(holdsCollections)
}
/**
* A layer inside an instance holds what its component's layer holds unless an override changed
* it. Each equal value is the component layer's own object rather than a copy, so a design kit's
* many instances do not each repeat their components' paints, glyphs, and defaults. Values are
* replaced, never written into, once loaded; loading writes only into fields a layer keeps.
*/
function shareUnchanged(node: SceneNode, source: SceneNode): void {
for (const field of Object.keys(node)) {
if (OWN_FIELDS.has(field)) continue
const value: unknown = Reflect.get(node, field)
const original: unknown = Reflect.get(source, field)
if (value === original || value === null || typeof value !== 'object') continue
if (holdsCollections(value) || !isEqual(value, original)) continue
Reflect.set(node, field, original)
}
// The layer's source metadata is its own, but the layout Figma saved for it is replaced whole,
// never written into, and nearly always the component layer's.
const layout = node.source.fig.layout
const originalLayout = source.source.fig.layout
if (layout && layout !== originalLayout && isEqual(layout, originalLayout))
node.source.fig.layout = originalLayout
}
export interface MaterializedInstance {
root: SceneNode
/** Occurrence object identity distinguishes repeated uses of a source node. */
nodes: ReadonlyMap<InstanceOccurrence, SceneNode>
}
/**
* Materialize an interpreted tree. Population, sync and layout are the caller's to run.
* Component IDs must refer to existing COMPONENT nodes in the destination graph.
* Occurrence provenance stays in the returned map, not in fabricated FIG metadata.
*/
/** Outlines inherited from a component are drawn at its size; scale them to the instance's. */
function scaleInheritedOutlines(
converted: ReturnType<typeof nodeChangeToProps>,
occurrence: InstanceOccurrence
): void {
const scale = occurrence.inheritedOutlineScale
if (!scale) return
if (converted.fillGeometry) {
converted.fillGeometry = scaleGeometryPaths(converted.fillGeometry, scale.fill.x, scale.fill.y)
}
if (converted.strokeGeometry) {
converted.strokeGeometry = scaleGeometryPaths(
converted.strokeGeometry,
scale.stroke.x,
scale.stroke.y
)
}
}
/** What an occurrence tree needs beyond the graph it is written into. */
export interface MaterializeInstanceOptions {
blobs?: Uint8Array[]
/** Graph ids for occurrences a component definition already materialized. */
sourceChildren?: ReadonlyMap<InstanceOccurrence, string>
/** Nodes to update in place rather than create, keyed by occurrence. */
existingNodes?: ReadonlyMap<InstanceOccurrence, SceneNode>
/**
* The id to create a layer under that is a record of its own, not a copy inside an instance:
* its saved GUID, so it keeps one id across loads. Undefined creates it under a fresh id.
*/
recordId?: (occurrence: InstanceOccurrence) => string | undefined
}
/** A document or a variable is a resource record, never a node in an expansion. */
function assertMaterializableType(
nodeType: 'DOCUMENT' | 'VARIABLE' | SceneNode['type']
): asserts nodeType is SceneNode['type'] {
if (nodeType === 'DOCUMENT' || nodeType === 'VARIABLE') {
throw new Error(`Cannot materialize ${nodeType} as an instance descendant`)
}
}
export function materializeInstance(
graph: SceneGraph,
parentId: string,
occurrence: InstanceOccurrence,
components: ReadonlyMap<string, string>,
options: MaterializeInstanceOptions = {}
): MaterializedInstance {
const { blobs = [], sourceChildren = new Map(), existingNodes = new Map(), recordId } = options
if (!graph.getNode(parentId)) throw new Error('Missing materialization parent')
const prepared = new Map<InstanceOccurrence, ReturnType<typeof nodeChangeToProps>>()
const validate = (current: InstanceOccurrence): void => {
if (prepared.has(current)) throw new Error('Repeated or cyclic instance occurrence')
const converted = nodeChangeToProps(current.properties, blobs, 'occurrence')
scaleInheritedOutlines(converted, current)
if (converted.nodeType === 'TEXT' && current.derivedSize) {
converted.derivedLayout = { width: current.derivedSize.x, height: current.derivedSize.y }
}
assertMaterializableType(converted.nodeType)
const existing = existingNodes.get(current)
if (
existing &&
(graph.getNode(existing.id) !== existing || existing.type !== converted.nodeType)
) {
throw new Error(`Invalid preallocated occurrence ${current.sourceId}`)
}
prepared.set(current, converted)
const sourceChildId = sourceChildren.get(current)
if (sourceChildId && graph.getNode(sourceChildId)?.type !== converted.nodeType) {
throw new Error(`Invalid source child for ${current.sourceId}`)
}
if (current.mainComponentId !== null) {
const id = components.get(current.mainComponentId)
if (!id || graph.getNode(id)?.type !== 'COMPONENT') {
throw new Error(`Missing materialized component ${current.mainComponentId}`)
}
}
for (const child of current.children) validate(child)
}
validate(occurrence)
const nodes = new Map<InstanceOccurrence, SceneNode>(existingNodes)
const applyBindingClaims = (
current: InstanceOccurrence,
node: SceneNode,
owner?: SceneNode
): void => {
if (!owner) return
for (const claim of current.bindingClaims) {
if (claim.origin === 'assignment' && claim.field === 'visible') {
setInstanceOverride(owner.instanceOverrides, owner.id, node.id, 'visible', node.visible)
}
}
}
/** A record of its own takes its saved GUID, and a copy inside an instance a fresh id. */
const createLayer = (
current: InstanceOccurrence,
nodeType: SceneNode['type'],
parent: string,
props: Partial<SceneNode>,
owner: SceneNode | undefined
): SceneNode => {
const id = owner ? undefined : recordId?.(current)
return id
? graph.createNodeWithId(id, nodeType, parent, props)
: graph.createNode(nodeType, parent, props)
}
const create = (current: InstanceOccurrence, parent: string, owner?: SceneNode): SceneNode => {
const converted = prepared.get(current)
if (!converted) throw new Error('Missing prepared occurrence')
const { nodeType, ...props } = converted
assertMaterializableType(nodeType)
const metadata = occurrenceMetadata(current, converted)
const propsWithIdentity = {
...props,
variableAssignmentScales: occurrenceAssignmentScales(current),
componentScale: occurrenceScale(current),
variableBindingScales: numericVariableBindingScales(
props.boundVariables ?? {},
current.layoutScale ?? 1,
current.variableBindingScales
),
componentId:
current.mainComponentId === null
? (sourceChildren.get(current) ?? null)
: components.get(current.mainComponentId),
source: metadata
}
const existing = existingNodes.get(current)
if (existing && existing.parentId !== parent) {
throw new Error(`Preallocated occurrence has wrong parent ${current.sourceId}`)
}
const node = existing ?? createLayer(current, nodeType, parent, propsWithIdentity, owner)
if (existing) graph.updateNode(existing.id, propsWithIdentity)
const sharedSource = graph.getNode(sourceChildren.get(current) ?? '')
if (sharedSource) shareUnchanged(node, sharedSource)
nodes.set(current, node)
if (existing && current !== occurrence && node.type === 'COMPONENT') return node
applyBindingClaims(current, node, owner)
const sourceChildId = sourceChildren.get(current)
if (owner && current.mainComponentId !== null && sourceChildId) {
setInstanceOverride(
owner.instanceOverrides,
owner.id,
node.id,
'sourceComponentId',
sourceChildId
)
const sourceChild = graph.getNode(sourceChildId)
if (sourceChild?.componentId !== node.componentId) {
setInstanceOverride(
owner.instanceOverrides,
owner.id,
node.id,
'componentId',
node.componentId
)
}
}
const children = current.children.map(
(child) => create(child, node.id, node.type === 'INSTANCE' ? node : owner).id
)
node.childIds = children
return node
}
const root = create(occurrence, parentId)
recordPropertyClaims(nodes)
return { root, nodes }
}
/** Whether a raw claim actually carries the scene value its kind maps to. */
function claimApplies(field: OverrideField, value: unknown, target: SceneNode): boolean {
if (field.kind === 'text')
return typeof value === 'object' && value !== null && 'characters' in value
// A text style claim names the style the layer took, or clears the component's; one that
// resolved to neither, such as a library style missing here, is not claimed.
if (field.kind === 'text-style') return Boolean(target.textStyleId) || isClearedStyle(value)
return true
}
/**
* A claimed paint carries its colour alias inside the paint, so the binding it declares is
* part of the claim too; otherwise a later component sync restores the component's binding.
*/
function recordPaintBindingClaims(
owner: SceneNode,
target: SceneNode,
scene: keyof SceneNode,
paints: unknown
): void {
if (!Array.isArray(paints)) return
let declared = false
for (const [index, paint] of paints.entries()) {
const alias = (paint as Paint).colorVar?.value?.alias
if (!alias) continue
const field = bindingOverrideField(`${scene}/${index}/color`)
setInstanceOverride(
owner.instanceOverrides,
owner.id,
target.id,
field,
target.boundVariables[`${scene}/${index}/color`] ?? null
)
declared = true
}
if (declared) setInstanceOverride(owner.instanceOverrides, owner.id, target.id, 'boundVariables')
}
function recordVariableModeClaims(owner: SceneNode, target: SceneNode, claim: NodeChange): void {
if (!claim.variableModeBySetMap) {
return
}
for (const collection of variableModeLayer(claim).keys()) {
const field = variableModeOverrideField(collection)
setInstanceOverride(owner.instanceOverrides, owner.id, target.id, field)
}
}
/** A claimed effect carries its properties' aliases, so its bindings are part of the claim too. */
function recordEffectBindingClaims(owner: SceneNode, target: SceneNode, effects: unknown): void {
if (!Array.isArray(effects)) return
let declared = false
for (const [index, effect] of (effects as KiwiEffect[]).entries()) {
for (const property of EFFECT_BINDING_PROPERTIES) {
if (!effect[EFFECT_VARIABLE_FIELDS[property]]?.value?.alias) continue
const path = effectBindingField(index, property)
setInstanceOverride(
owner.instanceOverrides,
owner.id,
target.id,
bindingOverrideField(path),
target.boundVariables[path] ?? null
)
declared = true
}
}
if (declared) setInstanceOverride(owner.instanceOverrides, owner.id, target.id, 'boundVariables')
}
function recordPropertyClaims(nodes: ReadonlyMap<InstanceOccurrence, SceneNode>): void {
for (const [ownerOccurrence, owner] of nodes) {
if (owner.type !== 'INSTANCE') continue
for (const claim of ownerOccurrence.propertyClaims) {
const targetOccurrence = resolveOccurrencePath(ownerOccurrence, claim.path)
const target = nodes.get(targetOccurrence)
if (!target) throw new Error('Unmaterialized property claim target')
for (const raw of Object.keys(OVERRIDE_FIELDS) as RawOverrideField[]) {
if (!(raw in claim.properties)) continue
const field = OVERRIDE_FIELDS[raw]
if (!claimApplies(field, claim.properties[raw], target)) continue
for (const scene of field.scene) {
const value = target[scene]
setInstanceOverride(
owner.instanceOverrides,
owner.id,
target.id,
scene,
structuredClone(value)
)
}
if (field.kind === 'paint')
recordPaintBindingClaims(owner, target, field.scene[0], claim.properties[raw])
if (raw === 'effects') recordEffectBindingClaims(owner, target, claim.properties[raw])
}
recordVariableBindingClaims(owner, target, claim.properties)
recordVariableModeClaims(owner, target, claim.properties)
}
}
}