AI-native design editor. Open-source Figma alternative.
/**
* Message Encoding/Decoding for Figma Multiplayer
*
* Uses:
* - kiwi-schema: Binary serialization (by Evan Wallace, Figma co-founder)
* - fzstd: Browser-compatible Zstd decompression
*/
import { compileSchema, encodeBinarySchema } from '../schema-runtime'
import { decompressFigKiwiData, loadFigDataDecompressor } from './container'
import { isZstdCompressed, getKiwiMessageType } from './protocol'
import figmaSchema from './schema'
import type { Color, GUID, Matrix, Vector } from './types'
interface CompiledSchema {
encodeMessage(message: unknown): Uint8Array
decodeMessage(data: Uint8Array): unknown
encodePaint(paint: unknown): Uint8Array
encodeNodeChange(nodeChange: unknown): Uint8Array
}
let compiledSchema: CompiledSchema | null = null
/**
* Initialize the codec (compiles Kiwi schema)
*/
export async function initCodec(): Promise<void> {
if (compiledSchema) return
await loadFigDataDecompressor()
compiledSchema = compileSchema(figmaSchema) as CompiledSchema
}
export function getCompiledSchema() {
if (!compiledSchema) throw new Error('Codec not initialized')
return compiledSchema
}
export function getSchemaBytes(): Uint8Array {
return encodeBinarySchema(figmaSchema)
}
/**
* Check if codec is initialized
*/
export function isCodecReady(): boolean {
return compiledSchema !== null
}
/**
* Compress data using Zstd (Bun native)
*/
export function compress(data: Uint8Array): Uint8Array {
return data
}
/**
* Decompress Zstd data (Bun native)
*/
export function decompress(data: Uint8Array): Uint8Array {
if (!isZstdCompressed(data)) return data
return decompressFigKiwiData(data)
}
/**
* Encode a message for sending to Figma
* Handles variable bindings in fillPaints which require custom encoding
*/
export function encodeMessage(message: FigmaMessage): Uint8Array {
if (!compiledSchema) {
throw new Error('Codec not initialized. Call initCodec() first.')
}
return compress(compiledSchema.encodeMessage(message))
}
/**
* Decode a message received from Figma
*/
export function decodeMessage(data: Uint8Array): FigmaMessage {
if (!compiledSchema) {
throw new Error('Codec not initialized. Call initCodec() first.')
}
const decompressed = decompress(data)
return compiledSchema.decodeMessage(decompressed) as FigmaMessage
}
/**
* Quick peek at message type without full decoding
*/
export function peekMessageType(data: Uint8Array): number | null {
try {
const decompressed = decompress(data)
return getKiwiMessageType(decompressed)
} catch {
return null
}
}
// Type definitions
export interface ParentIndex {
guid: GUID
position: string
}
export interface ImageSource {
hash: string | Uint8Array
name?: string
dataBlob?: number
}
export interface Paint {
type:
| 'SOLID'
| 'GRADIENT_LINEAR'
| 'GRADIENT_RADIAL'
| 'GRADIENT_ANGULAR'
| 'GRADIENT_DIAMOND'
| 'IMAGE'
| 'VIDEO'
| 'PATTERN'
| 'NOISE'
| 'CUSTOM'
color?: Color
opacity?: number
visible?: boolean
blendMode?: string
stops?: { color: Color; position: number }[]
transform?: Matrix
image?: ImageSource
imageThumbnail?: ImageSource
animatedImage?: ImageSource
imageScaleMode?: string
/** Degrees an image turns in Fill, Fit, and Tile; a crop's transform holds its own turn. */
rotation?: number
sourceNodeId?: GUID
scale?: number
spacing?: number
patternSpacing?: Vector
patternTileType?: string
verticalAlignment?: string
horizontalAlignment?: string
id?: GUID
altText?: string
noiseType?: string
density?: number
noiseSize?: Vector
customEffectId?: { guid?: GUID }
colorVar?: VariableDataEntry
}
export interface Effect {
type: 'DROP_SHADOW' | 'INNER_SHADOW' | 'LAYER_BLUR' | 'BACKGROUND_BLUR' | 'FOREGROUND_BLUR'
color?: Color
offset?: Vector
radius?: number
visible?: boolean
spread?: number
blendMode?: string
showShadowBehindNode?: boolean
colorVar?: VariableDataEntry
radiusVar?: VariableDataEntry
spreadVar?: VariableDataEntry
xVar?: VariableDataEntry
yVar?: VariableDataEntry
}
/** A reference to a variable: by GUID in the file, or by key in a library. */
export interface VariableAliasValue {
guid?: GUID
assetRef?: { key: string; version?: string }
}
export interface VariableAnyValue {
boolValue?: boolean
textValue?: string
floatValue?: number
colorValue?: Color
alias?: VariableAliasValue
symbolIdValue?: { guid?: GUID }
// fig.kiwi PropRefValue: the component property a parameter entry points at.
propRefValue?: { defId?: GUID }
mapValue?: { values?: { key?: string; guidKey?: GUID; value?: VariableDataEntry }[] }
colorArrayValue?: { colors?: VariableDataEntry[] }
fontStyleValue?: {
asString?: VariableDataEntry
asFloat?: VariableDataEntry
asVariations?: VariableDataEntry
}
expressionValue?: {
expressionFunction?: string
expressionArguments?: VariableDataEntry[]
}
}
export interface VariableDataEntry {
value?: VariableAnyValue
dataType?: string
resolvedDataType?: string
}
export interface VariableConsumptionEntry {
nodeField?: number
variableData?: VariableDataEntry
variableField?: string
}
export interface VariableDataValuesEntry {
modeID: GUID
variableData: VariableDataEntry
}
export interface PluginData {
pluginID: string
value: string
key: string
}
export interface PluginRelaunchData {
pluginID: string
message: string
command: string
isDeleted: boolean
}
export interface AssetRef {
key: string
version?: string
}
export type StyleReference = { guid: GUID; assetRef?: never } | { guid?: never; assetRef: AssetRef }
/** One paragraph of a text: whether it is a list item, and how deeply it nests. */
export interface TextLineData {
lineType?: 'PLAIN' | 'ORDERED_LIST' | 'UNORDERED_LIST' | 'BLOCKQUOTE' | 'HEADER'
styleId?: number
indentationLevel?: number
sourceDirectionality?: string
listStartOffset?: number
isFirstLineOfList?: boolean
}
export interface NodeChange {
[key: string]: unknown
guid?: GUID
phase?: 'CREATED' | 'REMOVED'
parentIndex?: ParentIndex
type?: string
name?: string
visible?: boolean
locked?: boolean
opacity?: number
blendMode?: string
size?: Vector
transform?: Matrix
cornerRadius?: number
fillPaints?: Paint[]
strokePaints?: Paint[]
backgroundPaints?: Paint[]
strokeWeight?: number
strokeAlign?: string
strokeCap?: string
strokeJoin?: string
dashPattern?: number[]
effects?: Effect[]
mask?: boolean
maskType?: string
maskIsOutline?: boolean
exportSettings?: unknown[]
layoutGrids?: unknown[]
// Layout
stackMode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL'
stackSpacing?: number
stackPadding?: number
stackPaddingRight?: number
stackPaddingBottom?: number
stackCounterAlign?: string
stackJustify?: string
stackCounterAlignItems?: string
stackPrimaryAlignItems?: string
stackPrimarySizing?: 'FIXED' | 'RESIZE_TO_FIT' | 'RESIZE_TO_FIT_WITH_IMPLICIT_SIZE'
stackCounterSizing?: 'FIXED' | 'RESIZE_TO_FIT' | 'RESIZE_TO_FIT_WITH_IMPLICIT_SIZE'
stackVerticalPadding?: number
stackHorizontalPadding?: number
stackWrap?: string
stackPositioning?: string
stackChildPrimaryGrow?: number
stackChildAlignSelf?: string
stackCounterSpacing?: number
minSize?: { value?: Vector }
maxSize?: { value?: Vector }
targetAspectRatio?: { value?: Vector }
// Frame
clipsContent?: boolean
frameMaskDisabled?: boolean
resizeToFit?: boolean
// Vector
booleanOperation?: 'UNION' | 'SUBTRACT' | 'INTERSECT' | 'XOR'
vectorData?: unknown
fillGeometry?: Array<{ windingRule?: string; commandsBlob?: number; styleID?: number }>
strokeGeometry?: Array<{ windingRule?: string; commandsBlob?: number }>
// Text
fontSize?: number
fontWeight?: number
fontName?: { family: string; style: string; postscript?: string }
textAlignHorizontal?: string
textAlignVertical?: string
textAutoResize?: string
textData?: {
characters: string
lines?: TextLineData[]
characterStyleIDs?: number[]
styleOverrideTable?: NodeChange[]
}
derivedTextData?: {
layoutSize?: Vector
baselines?: Array<{
firstCharacter: number
endCharacter: number
position: Vector
width: number
lineY?: number
lineHeight: number
lineAscent: number
}>
glyphs?: Array<{
commandsBlob?: number
position: Vector
fontSize: number
/** The character the glyph draws; Figma leaves it out for list markers. */
firstCharacter?: number
advance: number
/** Radians along the text path; kiwi omits the field for axis-aligned text. */
rotation?: number
/** An emoji's code points; Figma draws its image in place of the glyph's placeholder. */
emojiCodePoints?: number[]
/** The image set the emoji is drawn from; left out for the default, APPLE. */
emojiImageSet?: 'APPLE' | 'NOTO'
}>
/** Underlines and strikethroughs, which Figma draws saved text's decorations from. */
decorations?: Array<{
rects: Array<{ x: number; y: number; w: number; h: number }>
/** The override table entry of the characters decorated, or 0 for the text's own style. */
styleID: number
}>
fontMetaData?: Array<{
key: { family: string; style: string; postscript?: string }
fontLineHeight: number
fontDigest?: Uint8Array | Record<string, number>
fontStyle?: string
fontWeight?: number
}>
logicalIndexToCharacterOffsetMap?: number[]
derivedLines?: Array<{ directionality: 'LTR' | 'RTL' }>
truncationStartIndex?: number
truncatedHeight?: number
}
styleType?: string
styleIdForText?: StyleReference
styleIdForFill?: StyleReference
styleIdForStrokeFill?: StyleReference
styleIdForEffect?: StyleReference
styleIdForGrid?: StyleReference
textUserLayoutVersion?: number
textExplicitLayoutVersion?: number
textBidiVersion?: number
textDecoration?: string
textDecorationSkipInk?: boolean
textDecorationFillPaints?: Paint[]
textUnderlineOffset?: { value?: number; units?: string }
textDecorationThickness?: { value?: number; units?: string }
textDecorationStyle?: string
toggledOnOTFeatures?: string[]
toggledOffOTFeatures?: string[]
fontVariations?: Array<{ axisTag?: number; axisName?: string; value?: number }>
fontVariantCommonLigatures?: boolean
fontVariantContextualLigatures?: boolean
fontVariantDiscretionaryLigatures?: boolean
fontVariantHistoricalLigatures?: boolean
fontVariantOrdinal?: boolean
fontVariantSlashedZero?: boolean
fontVariantNumericFigure?: string
fontVariantNumericSpacing?: string
fontVariantNumericFraction?: string
fontVariantCaps?: string
fontVersion?: string
emojiImageSet?: string
lineHeight?: { value: number; units: string }
letterSpacing?: { value: number; units: string }
paragraphSpacing?: number
paragraphIndent?: number
listSpacing?: number
hangingList?: boolean
// Symbol/Instance
symbolData?: { symbolID: GUID }
// ComponentSet
isStateGroup?: boolean
stateGroupPropertyValueOrders?: Array<{ property: string; values: string[] }>
// Internal
internalOnly?: boolean
// Corners
rectangleTopLeftCornerRadius?: number
rectangleTopRightCornerRadius?: number
rectangleBottomLeftCornerRadius?: number
rectangleBottomRightCornerRadius?: number
rectangleCornerRadiiIndependent?: boolean
cornerSmoothing?: number
/** A polygon's sides or a star's points. */
count?: number
/** A star's inner radius as a share of its outer one. */
starInnerScale?: number
// Constraints
horizontalConstraint?: string
verticalConstraint?: string
// Prototype
prototypeStartNodeID?: GUID
prototypeInteractions?: unknown[]
transitionInfo?: unknown
// Variables
variableData?: VariableDataEntry
variableConsumptionMap?: { entries?: VariableConsumptionEntry[] }
// fig.kiwi declares this as the same VariableDataMap as variableConsumptionMap.
parameterConsumptionMap?: { entries?: VariableConsumptionEntry[] }
variableSetModes?: Array<{ id: GUID; name: string; sortPosition?: string }>
variableSetID?: { guid?: GUID; assetRef?: { key: string; version?: string } }
variableResolvedType?: string
variableDataValues?: { entries?: VariableDataValuesEntry[] }
variableScopes?: string[]
codeSyntax?: { entries?: Array<{ platform: string; value: string }> }
description?: string
symbolDescription?: string
isPublishable?: boolean
documentColorProfile?: 'SRGB' | 'DISPLAY_P3'
pluginData?: PluginData[]
pluginRelaunchData?: PluginRelaunchData[]
}
export interface FigmaMessage {
type: string
sessionID?: number
ackID?: number
reconnectSequenceNumber?: number
nodeChanges?: NodeChange[]
blobs?: Array<{ bytes: Uint8Array }>
}
/**
* Create a NODE_CHANGES message
*/
export function createNodeChangesMessage(
sessionID: number,
reconnectSequenceNumber: number,
nodeChanges: NodeChange[],
ackID = 1
): FigmaMessage {
return {
type: 'NODE_CHANGES',
sessionID,
ackID,
reconnectSequenceNumber,
nodeChanges
}
}
/**
* Create a node change for a new shape
*/
export function createNodeChange(opts: {
sessionID: number
localID: number
parentSessionID: number
parentLocalID: number
position?: string
type: string
name: string
x: number
y: number
width: number
height: number
fill?: Color
stroke?: Color
strokeWeight?: number
cornerRadius?: number
opacity?: number
}): NodeChange {
const change: NodeChange = {
guid: { sessionID: opts.sessionID, localID: opts.localID },
phase: 'CREATED',
parentIndex: {
guid: { sessionID: opts.parentSessionID, localID: opts.parentLocalID },
position: opts.position || '!'
},
type: opts.type,
name: opts.name,
visible: true,
opacity: opts.opacity ?? 1.0,
size: { x: opts.width, y: opts.height },
transform: {
m00: 1,
m01: 0,
m02: opts.x,
m10: 0,
m11: 1,
m12: opts.y
}
}
if (opts.fill) {
change.fillPaints = [
{
type: 'SOLID',
color: opts.fill,
opacity: 1.0,
visible: true,
blendMode: 'NORMAL'
}
]
}
if (opts.stroke) {
change.strokePaints = [
{
type: 'SOLID',
color: opts.stroke,
opacity: 1.0,
visible: true,
blendMode: 'NORMAL'
}
]
change.strokeWeight = opts.strokeWeight ?? 1
}
if (opts.cornerRadius !== undefined) {
change.cornerRadius = opts.cornerRadius
}
return change
}