Skip to content

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

10.6 KB
Raw Blame
import { unzipSync, zipSync, type Unzipped, type Zippable } from 'fflate'
import * as v from 'valibot'

import type { FigPageManifestEntry } from '@open-pencil/kiwi/fig'
import type { NodeChange } from '@open-pencil/kiwi/fig/codec'
import {
  buildFigKiwi,
  figFileKind,
  parseFigKiwiChunks,
  type FigDataCompressor,
  type FigFileKind
} from '@open-pencil/kiwi/fig/container'
import { decodeFigKiwiCanvas, parseFigKiwiContainer } from '@open-pencil/kiwi/fig/parse'
import type { HeaderFields } from '@open-pencil/kiwi/schema-runtime'
import type { Color, Rect, Size } from '@open-pencil/scene-graph/primitives'

import { figArchiveMetaSchema, type FigArchiveMetaJSON } from './schema'
import { isPNG } from './thumbnail'

export interface FigImageEntry {
  name: string
  data: Uint8Array
}

export interface WriteFigArchiveInput {
  schemaDeflated: Uint8Array
  kiwiData: Uint8Array
  thumbnailPNG: Uint8Array
  metaJSON: string
  images?: FigImageEntry[]
  figKiwiVersion?: number
  /** Compresses the document data; Bun's zstd or deflate when omitted. */
  compress?: FigDataCompressor
  /** A design file, or a FigJam board saved as `.jam`; a design when omitted. */
  kind?: FigFileKind
}

export interface FigParseResult {
  nodeChanges: NodeChange[]
  blobs: Uint8Array[]
  images: Array<[string, Uint8Array]>
  figKiwiVersion: number
  /** Deflated Kiwi schema bytes from the original file, retained for round-trip fidelity. */
  figSchemaDeflated: Uint8Array
  /** A design file or a FigJam board, by the canvas's header. */
  kind: FigFileKind
  thumbnailPNG: Uint8Array | null
  metaJSON: string | null
}

function isLikelyAsset(name: string): boolean {
  const lower = name.toLowerCase()
  return lower.endsWith('.png') || lower.endsWith('.jpg') || lower.endsWith('.json')
}

function findCanvasData(entries: Partial<Record<string, Uint8Array>>): Uint8Array | null {
  const canonical = entries['canvas.fig'] ?? entries.canvas
  if (canonical) return canonical

  let largest: Uint8Array | null = null
  for (const [name, data] of Object.entries(entries)) {
    if (!data || isLikelyAsset(name)) continue
    if (!largest || data.byteLength > largest.byteLength) largest = data
  }
  return largest
}

function isCanonicalCanvasEntry(name: string): boolean {
  return name === 'canvas.fig' || name === 'canvas'
}

/**
 * Whether a `.fig` or `.jam` archive, or a bare canvas, holds a design or a FigJam board, by its
 * canvas's header, without decoding the document; `null` when it holds no Figma canvas.
 */
export function figArchiveKind(bytes: Uint8Array): FigFileKind | null {
  const bare = figFileKind(bytes)
  if (bare) return bare
  try {
    const entries: Partial<Record<string, Uint8Array>> = unzipSync(bytes, {
      filter: ({ name }) => isCanonicalCanvasEntry(name)
    })
    const canvas = entries['canvas.fig'] ?? entries.canvas
    return canvas ? figFileKind(canvas) : null
  } catch {
    return null
  }
}

function parseRawFigKiwi(
  bytes: Uint8Array,
  onPages?: (pages: FigPageManifestEntry[]) => void,
  headers?: HeaderFields
): FigParseResult | null {
  const chunks = parseFigKiwiChunks(bytes)
  if (!chunks) return null

  const decoded = decodeFigKiwiCanvas(bytes, onPages, headers)
  const thumbnailPNG = chunks.slice(2).find(isPNG) ?? null
  return { ...decoded, images: [], thumbnailPNG, metaJSON: null }
}

/**
 * Parse a complete zipped or legacy raw `.fig` file into its protocol payload and resources.
 * Records decoded as `headers` keep only the named fields; `decodeWhole` reads one in full.
 */
export function parseFigBuffer(
  buffer: ArrayBuffer,
  onPages?: (pages: FigPageManifestEntry[]) => void,
  headers?: HeaderFields
): FigParseResult {
  const bytes = new Uint8Array(buffer)
  const raw = parseRawFigKiwi(bytes, onPages, headers)
  if (raw) return raw

  const canvasArchive = unzipSync(bytes, { filter: ({ name }) => isCanonicalCanvasEntry(name) })
  let canvasData = findCanvasData(canvasArchive)
  let archive: Unzipped
  let decoded: ReturnType<typeof decodeFigKiwiCanvas>
  if (canvasData) {
    decoded = decodeFigKiwiCanvas(canvasData, onPages, headers)
    archive = unzipSync(bytes, { filter: ({ name }) => !isCanonicalCanvasEntry(name) })
  } else {
    archive = unzipSync(bytes)
    canvasData = findCanvasData(archive)
    if (!canvasData) {
      throw new Error(
        `No canvas data found in .fig file. Entries: ${Object.keys(archive).join(', ')}`
      )
    }
    decoded = decodeFigKiwiCanvas(canvasData, onPages, headers)
  }

  const metaBytes = archive['meta.json']
  const images = Object.entries(archive)
    .filter(([name]) => name.startsWith('images/') && name !== 'images/')
    .map(([name, data]) => [name.slice('images/'.length), data] as [string, Uint8Array])

  return {
    ...decoded,
    images,
    thumbnailPNG: archive['thumbnail.png'] ?? null,
    metaJSON: Object.hasOwn(archive, 'meta.json') ? new TextDecoder().decode(metaBytes) : null
  }
}

/** A `.fig` file's parts with its Kiwi message still encoded, for copying records as bytes. */
export interface FigArchiveParts {
  schemaDeflated: Uint8Array
  /** The inflated Kiwi message. */
  dataRaw: Uint8Array
  figKiwiVersion: number
  /** A design file or a FigJam board, by the canvas's header. */
  kind: FigFileKind
  images: Array<[string, Uint8Array]>
  thumbnailPNG: Uint8Array | null
  metaJSON: string | null
}

function canvasParts(canvasData: Uint8Array) {
  const payload = parseFigKiwiContainer(canvasData)
  if (!payload) throw new Error('Invalid fig-kiwi container')
  return {
    schemaDeflated: payload.schemaDeflated,
    dataRaw: payload.dataRaw,
    figKiwiVersion: payload.version,
    kind: payload.kind
  }
}

export function readFigArchiveParts(buffer: ArrayBuffer): FigArchiveParts {
  const bytes = new Uint8Array(buffer)
  const chunks = parseFigKiwiChunks(bytes)
  if (chunks) {
    const thumbnailPNG = chunks.slice(2).find(isPNG) ?? null
    return { ...canvasParts(bytes), images: [], thumbnailPNG, metaJSON: null }
  }
  const canvasArchive = unzipSync(bytes, { filter: ({ name }) => isCanonicalCanvasEntry(name) })
  const canonical = findCanvasData(canvasArchive)
  const archive = unzipSync(
    bytes,
    canonical ? { filter: ({ name }) => !isCanonicalCanvasEntry(name) } : undefined
  )
  const canvasData = canonical ?? findCanvasData(archive)
  if (!canvasData)
    throw new Error(
      `No canvas data found in .fig file. Entries: ${Object.keys(archive).join(', ')}`
    )
  const images = Object.entries(archive)
    .filter(([name]) => name.startsWith('images/') && name !== 'images/')
    .map(([name, data]) => [name.slice('images/'.length), data] as [string, Uint8Array])
  return {
    ...canvasParts(canvasData),
    images,
    thumbnailPNG: archive['thumbnail.png'] ?? null,
    metaJSON: Object.hasOwn(archive, 'meta.json')
      ? new TextDecoder().decode(archive['meta.json'])
      : null
  }
}

/** What an archive's `meta.json` records about the file and its `thumbnail.png`. */
export interface FigArchiveMeta {
  fileName: string
  /** The background of the page the thumbnail shows. */
  backgroundColor: Color
  /** The thumbnail's size in pixels. */
  thumbnailSize: Size
  /** The page-space rectangle the thumbnail shows. */
  renderCoordinates: Rect
  exportedAt: Date
}

/**
 * The `meta.json` Figma's "Save local copy…" writes, in its key order. Colour channels are
 * rounded to the 32-bit floats the canvas records store, so they read as Figma's do.
 */
export function figArchiveMetaJSON(meta: FigArchiveMeta): string {
  const { r, g, b, a } = meta.backgroundColor
  const { x, y, width, height } = meta.renderCoordinates
  const json: FigArchiveMetaJSON = {
    client_meta: {
      background_color: {
        r: Math.fround(r),
        g: Math.fround(g),
        b: Math.fround(b),
        a: Math.fround(a)
      },
      thumbnail_size: { width: meta.thumbnailSize.width, height: meta.thumbnailSize.height },
      render_coordinates: { x, y, width, height }
    },
    file_name: meta.fileName,
    developer_related_links: [],
    exported_at: meta.exportedAt.toISOString()
  }
  return JSON.stringify(json)
}

/** Decode an archive's `meta.json`, failing on malformed JSON and on a shape Figma does not write. */
export function readFigArchiveMeta(text: string) {
  return v.safeParse(v.pipe(v.string(), v.parseJson(), figArchiveMetaSchema), text)
}

/** Any `meta.json` object, its keys in the order they were written. */
const storedMetaSchema = v.pipe(v.string(), v.parseJson(), v.record(v.string(), v.unknown()))

/**
 * The archive with its `meta.json` recording `fileName`, every other entry's bytes and every
 * other key of `meta.json` as they were; the archive itself when it already records that name.
 * Null when its `meta.json` records no `file_name`, which only a full write can give it.
 */
export function renameFigArchive(bytes: Uint8Array, fileName: string): Uint8Array | null {
  if (parseFigKiwiChunks(bytes)) return null
  const stored = unzipSync(bytes, { filter: ({ name }) => name === 'meta.json' })
  if (!Object.hasOwn(stored, 'meta.json')) return null
  const meta = v.safeParse(storedMetaSchema, new TextDecoder().decode(stored['meta.json']))
  if (!meta.success || typeof meta.output.file_name !== 'string') return null
  if (meta.output.file_name === fileName) return bytes
  const renamed: Zippable = {}
  for (const [name, data] of Object.entries(unzipSync(bytes))) {
    renamed[name] =
      name === 'meta.json'
        ? new TextEncoder().encode(JSON.stringify({ ...meta.output, file_name: fileName }))
        : [data, { level: 0 }]
  }
  return zipSync(renamed)
}

/** Assemble a complete zipped `.fig` archive from an encoded Kiwi message and resources. */
export function writeFigArchive(input: WriteFigArchiveInput): Uint8Array {
  const canvasData = buildFigKiwi(
    input.schemaDeflated,
    input.kiwiData,
    input.figKiwiVersion,
    input.compress,
    input.kind
  )
  const entries: Zippable = {
    'canvas.fig': [canvasData, { level: 0 }],
    'thumbnail.png': [input.thumbnailPNG, { level: 0 }],
    'meta.json': new TextEncoder().encode(input.metaJSON)
  }
  for (const image of input.images ?? []) entries[image.name] = [image.data, { level: 0 }]
  return zipSync(entries)
}

/** Compatibility signature used by core while archive assembly migrates to this package. */
export function compressFigDataSync(
  schemaDeflated: Uint8Array,
  kiwiData: Uint8Array,
  thumbnailPNG: Uint8Array,
  metaJSON: string,
  imageEntries: FigImageEntry[],
  figKiwiVersion?: number,
  compress?: FigDataCompressor,
  kind?: FigFileKind
): Uint8Array {
  return writeFigArchive({
    schemaDeflated,
    kiwiData,
    thumbnailPNG,
    metaJSON,
    images: imageEntries,
    figKiwiVersion,
    compress,
    kind
  })
}