Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

23.5 KB
Raw Blame
/**
 * The `.fig` engine as the app calls it: async methods, workers behind them.
 *
 * Each open file gets a primary worker, which answers queries (layers, hit
 * tests, properties), plus raster
 * helpers that open the same file and rasterize tiles in parallel. Workers
 * are terminated when the file is closed, which returns their memory (wasm
 * memory never shrinks while a worker lives).
 */

import { fireAndForget } from '@core/util/fireAndForget';
import { compiledFigModule } from './compiled-module';
import type { CollectionInfo, DesignInfo, StyleInfo } from './design-types';
import type {
  Exportable,
  ExportedFile,
  ExportRequest,
  LayoutAids,
} from './handoff-types';
import type {
  LibraryPackage,
  LibrarySpec,
  LibraryStatus,
  LibraryUse,
  PublishedLibrary,
} from './library-types';
import type { FigRequest, FigResponse, QueryMethod } from './protocol';
import type { PrototypeInfo } from './prototype-types';
import type {
  ComponentInfo,
  CopiedLayers,
  EntryChange,
  FileSummary,
  FontUse,
  LayerRow,
  LiftPlan,
  NodeGeometry,
  NodeInfo,
  PageLayout,
  PasteSpec,
  Rect,
  RegisteredFace,
  SearchHit,
  TextGeometry,
  VectorNetwork,
} from './types';

type Ok = Extract<FigResponse, { ok: true }>;
type Body = FigRequest extends infer R
  ? R extends { id: number }
    ? Omit<R, 'id'>
    : never
  : never;

export interface TileRequest {
  page: number;
  /** Page coordinates of the tile's top-left corner. */
  x: number;
  y: number;
  /** Device pixels per page unit. */
  scale: number;
  width: number;
  height: number;
  outline: boolean;
  /** Lower renders first. */
  priority: number;
  /** Only some layers (`LayersSpec` JSON); all when absent. */
  layers?: string;
}

/** What an edit changed (`EditResult` in the engine). */
export interface EditResult {
  created: string[];
  /** Page area whose pixels may have changed. */
  dirty: Rect | null;
  canUndo: boolean;
  canRedo: boolean;
  /**
   * The steps undo and redo would act on next; a step keeps its id while
   * it coalesces and across undo and redo.
   */
  undoStep: number | null;
  redoStep: number | null;
  /** Layers were added, removed, or moved between parents. */
  structure: boolean;
}

export interface TileResult {
  bitmap: ImageBitmap;
  millis: number;
}

/** A queued render that can be cancelled before it starts. */
export interface PendingTile {
  id: number;
  promise: Promise<TileResult | null>;
}

let nextId = 1;

class EngineWorker {
  readonly worker: Worker;
  private readonly pending = new Map<
    number,
    { resolve: (r: Ok) => void; reject: (e: Error) => void }
  >();
  renders = 0;
  dead = false;

  constructor(onDeath: (error: Error) => void) {
    // Constructed on first use, never at module load: WKWebView deadlocks on
    // eager module workers (apps/web/AGENTS.md).
    this.worker = new Worker(new URL('./fig.worker.ts', import.meta.url), {
      type: 'module',
    });
    this.worker.addEventListener(
      'message',
      (event: MessageEvent<FigResponse>) => {
        const response = event.data;
        const waiting = this.pending.get(response.id);
        if (!waiting) return;
        this.pending.delete(response.id);
        if (response.ok) waiting.resolve(response);
        else {
          if (response.trapped) this.dead = true;
          waiting.reject(new Error(response.error));
        }
      }
    );
    this.worker.addEventListener('error', (event) => {
      this.dead = true;
      const error = new Error(`fig engine worker failed: ${event.message}`);
      for (const waiting of this.pending.values()) waiting.reject(error);
      this.pending.clear();
      onDeath(error);
    });
  }

  request(body: Body, transfer: Transferable[] = []): Promise<Ok> {
    const id = nextId++;
    return this.requestWithId(id, body, transfer);
  }

  requestWithId(id: number, body: Body, transfer: Transferable[] = []) {
    if (this.dead) return Promise.reject(new Error('the file engine stopped'));
    return new Promise<Ok>((resolve, reject) => {
      this.pending.set(id, { resolve, reject });
      this.worker.postMessage({ ...body, id } as FigRequest, transfer);
    });
  }

  cancel(ids: number[]) {
    if (ids.length === 0 || this.dead) return;
    this.worker.postMessage({ id: 0, kind: 'cancel', ids } as FigRequest);
  }

  terminate() {
    this.dead = true;
    this.worker.terminate();
    for (const waiting of this.pending.values())
      waiting.reject(new Error('the file was closed'));
    this.pending.clear();
  }
}

/** Files larger than this get one raster helper (each helper holds a copy). */
const LARGE_FILE_BYTES = 48 * 1024 * 1024;

function helperCount(byteLength: number): number {
  const cores =
    typeof navigator !== 'undefined' ? navigator.hardwareConcurrency || 4 : 4;
  const wanted = Math.max(1, Math.min(3, cores - 2));
  return byteLength > LARGE_FILE_BYTES ? 1 : wanted;
}

export class FigEngine {
  private readonly primary: EngineWorker;
  private readonly helpers: EngineWorker[] = [];
  private readonly placed = new Map<number, EngineWorker>();
  private readonly starting = new Set<EngineWorker>();
  private closed = false;
  /** Work (a last save) that keeps the primary worker alive after close. */
  private readonly holds = new Set<Promise<unknown>>();
  private onFailure?: (error: Error) => void;

  private constructor(
    primary: EngineWorker,
    readonly summary: FileSummary
  ) {
    this.primary = primary;
  }

  /** The bytes of a new, empty design (one page). */
  static async blank(name: string): Promise<Uint8Array<ArrayBuffer>> {
    const worker = new EngineWorker(() => {});
    try {
      const module = await compiledFigModule();
      const r = await worker.request({ kind: 'blank', name, module });
      if (r.kind !== 'saved') throw new Error('unexpected response');
      return new Uint8Array(r.bytes);
    } finally {
      worker.terminate();
    }
  }

  /** Opens a file. `bytes` is copied to each worker; the caller keeps it. */
  static async open(
    bytes: ArrayBuffer,
    options: { helpers?: number; onFailure?: (error: Error) => void } = {}
  ): Promise<FigEngine> {
    let engine: FigEngine | undefined;
    const primary = new EngineWorker((e) => engine?.onFailure?.(e));
    try {
      const module = await compiledFigModule();
      const copy = bytes.slice(0);
      const response = await primary.request(
        { kind: 'open', bytes: copy, module },
        [copy]
      );
      if (response.kind !== 'open') throw new Error('unexpected response');
      engine = new FigEngine(primary, response.summary);
      engine.onFailure = options.onFailure;
      const helpers = options.helpers ?? helperCount(bytes.byteLength);
      for (let i = 0; i < helpers; i++) engine.startHelper(bytes, module);
      return engine;
    } catch (error) {
      primary.terminate();
      throw error;
    }
  }

  private startHelper(bytes: ArrayBuffer, module: WebAssembly.Module) {
    const helper = new EngineWorker(() => {
      const at = this.helpers.indexOf(helper);
      if (at >= 0) this.helpers.splice(at, 1);
      this.starting.delete(helper);
    });
    // Edits reach a helper that is still opening through its queue, after
    // the open, so it never misses one.
    this.starting.add(helper);
    const copy = bytes.slice(0);
    helper
      .request({ kind: 'open', bytes: copy, module }, [copy])
      .then(() => {
        this.starting.delete(helper);
        if (this.closed) helper.terminate();
        else this.helpers.push(helper);
      })
      .catch(() => {
        this.starting.delete(helper);
        helper.terminate();
      });
  }

  private async query<T>(
    method: QueryMethod,
    ...args: (string | number | null)[]
  ): Promise<T> {
    const r = await this.primary.request({ kind: 'query', method, args });
    if (r.kind !== 'query') throw new Error('unexpected response');
    return JSON.parse(r.json) as T;
  }

  async openPage(page: number): Promise<PageLayout> {
    const r = await this.primary.request({ kind: 'openPage', page });
    if (r.kind !== 'openPage') throw new Error('unexpected response');
    return r.layout;
  }

  /** Queues a tile render on the least busy worker. */
  render(tile: TileRequest): PendingTile {
    const live = this.helpers.filter((h) => !h.dead);
    // Helpers accept work behind their open request. Do not fill the primary
    // with slow raster jobs while they start: it must answer pointer queries.
    const opening = [...this.starting].filter((h) => !h.dead);
    const pool =
      live.length > 0 ? live : opening.length > 0 ? opening : [this.primary];
    const worker = pool.reduce((a, b) => (b.renders < a.renders ? b : a));
    const id = nextId++;
    worker.renders++;
    this.placed.set(id, worker);
    const promise = worker
      .requestWithId(id, { kind: 'render', ...tile })
      .then((r) => {
        if (r.kind === 'render')
          return { bitmap: r.bitmap, millis: r.millis } satisfies TileResult;
        return null;
      })
      .finally(() => {
        worker.renders--;
        this.placed.delete(id);
      });
    return { id, promise };
  }

  /** Drops queued renders that have not started. */
  cancel(ids: number[]) {
    const byWorker = new Map<EngineWorker, number[]>();
    for (const id of ids) {
      const w = this.placed.get(id);
      if (!w) continue;
      const list = byWorker.get(w) ?? [];
      list.push(id);
      byWorker.set(w, list);
    }
    for (const [w, list] of byWorker) w.cancel(list);
  }

  /** The file's pages and details as they are now (after edits). */
  currentSummary(): Promise<FileSummary> {
    return this.query('summary');
  }

  /** Every component in the file (after edits), for the assets list. */
  components(): Promise<ComponentInfo[]> {
    return this.query('components');
  }

  /** The file's shared styles (after edits). */
  styles(): Promise<StyleInfo[]> {
    return this.query('styles');
  }

  /** The file's variable collections (after edits). */
  variables(): Promise<CollectionInfo[]> {
    return this.query('variables');
  }

  /** A layer's component, variant, property, and style details. */
  designInfo(page: number, id: string): Promise<DesignInfo> {
    return this.query('designInfo', page, id);
  }

  layers(page: number, parent?: string): Promise<LayerRow[]> {
    return this.query('layers', page, parent ?? null);
  }

  rows(page: number, ids: string[]): Promise<LayerRow[]> {
    return this.query('rows', page, JSON.stringify(ids));
  }

  nodeInfo(page: number, id: string): Promise<NodeInfo> {
    return this.query('nodeInfo', page, id);
  }

  /** Layers under a page point, from the page's child to the deepest. */
  hitTest(
    page: number,
    x: number,
    y: number,
    tolerance: number
  ): Promise<LayerRow[]> {
    return this.query('hitTest', page, x, y, tolerance);
  }

  /** Layers from the page's child down to `id`. */
  ancestry(page: number, id: string): Promise<LayerRow[]> {
    return this.query('ancestry', page, id);
  }

  geometry(page: number, ids: string[]): Promise<NodeGeometry[]> {
    return this.query('geometry', page, JSON.stringify(ids));
  }

  outline(page: number, id: string): Promise<string> {
    return this.query('outline', page, id);
  }

  search(page: number, query: string, limit = 200): Promise<SearchHit[]> {
    return this.query('search', page, query, limit);
  }

  /**
   * How to draw layers apart from the rest of the page while they move
   * (or why that would not be exact).
   */
  liftPlan(page: number, ids: string[]): Promise<LiftPlan> {
    return this.query('liftPlan', page, JSON.stringify(ids));
  }

  /** The page's guides and its frames' layout grids and guides. */
  layoutAids(page: number): Promise<LayoutAids> {
    return this.query('layoutAids', page);
  }

  /** A layer and the layers inside it with export presets. */
  exportables(page: number, id: string): Promise<Exportable[]> {
    return this.query('exportables', page, id);
  }

  /** Layers exported with presets: one file, or a ZIP of several. */
  async exportFiles(
    page: number,
    request: ExportRequest
  ): Promise<ExportedFile> {
    const r = await this.primary.request({
      kind: 'exportFiles',
      page,
      request: JSON.stringify(request),
    });
    if (r.kind !== 'file') throw new Error('nothing to export');
    return {
      name: r.name,
      mime: r.mime,
      blob: new Blob([r.bytes], { type: r.mime }),
    };
  }

  /** "Export frames to PDF": the page's top-level frames, a page each. */
  async exportFramesPdf(page: number): Promise<Blob> {
    const r = await this.primary.request({ kind: 'exportFramesPdf', page });
    if (r.kind !== 'file') throw new Error('nothing to export');
    return new Blob([r.bytes], { type: 'application/pdf' });
  }

  /** The page's flows, screens, and layers with interactions. */
  prototype(page: number): Promise<PrototypeInfo> {
    return this.query('prototype', page);
  }

  /** The page's distinct solid colors, most used first (`RRGGBB[AA]`). */
  pageColors(page: number, limit = 24): Promise<string[]> {
    return this.query('pageColors', page, limit);
  }

  inRect(page: number, parent: string | undefined, rect: Rect) {
    return this.query<string[]>(
      'inRect',
      page,
      parent ?? null,
      rect.x,
      rect.y,
      rect.w,
      rect.h
    );
  }

  /** A PNG of one layer at `scale` (transparent background). */
  async exportPng(page: number, id: string, scale: number): Promise<Blob> {
    const r = await this.primary.request({
      kind: 'export',
      page,
      node: id,
      scale,
    });
    if (r.kind !== 'png' || !r.bytes) throw new Error('nothing to export');
    return new Blob([r.bytes], { type: 'image/png' });
  }

  /** One layer (and what it holds) as an SVG document. */
  /** The fonts the document's text uses and whether each is available. */
  fonts(): Promise<FontUse[]> {
    return this.query('fonts');
  }

  /** A text layer's lines and caret stops, for the text editor. */
  textGeometry(page: number, id: string): Promise<TextGeometry | null> {
    return this.query('textGeometry', page, id);
  }

  /**
   * Makes a font available to text layout in every worker (TTF, OTF,
   * WOFF, or WOFF2), as `family` when given. Resolves to the faces the
   * primary worker registered (none when the file is not a font).
   */
  async registerFont(
    bytes: ArrayBuffer,
    family?: string
  ): Promise<RegisteredFace[]> {
    for (const h of [...this.helpers, ...this.starting]) {
      const copy = bytes.slice(0);
      h.request({ kind: 'registerFont', bytes: copy, family: family ?? null }, [
        copy,
      ]).catch(() => {});
    }
    const copy = bytes.slice(0);
    const r = await this.primary.request(
      { kind: 'registerFont', bytes: copy, family: family ?? null },
      [copy]
    );
    if (r.kind !== 'query') throw new Error('unexpected response');
    return JSON.parse(r.json) as RegisteredFace[];
  }

  exportSvg(page: number, id: string): Promise<string> {
    return this.query('exportSvg', page, id);
  }

  /** A layer's points in page coordinates; `null` for layers without. */
  vectorNetwork(page: number, id: string): Promise<VectorNetwork | null> {
    return this.query('vectorNetwork', page, id);
  }

  /** Copies layers as the clipboard carries them. */
  async copy(page: number, ids: string[]): Promise<CopiedLayers> {
    const r = await this.primary.request({
      kind: 'copy',
      page,
      ids: JSON.stringify(ids),
    });
    if (r.kind !== 'copied') throw new Error('unexpected response');
    return {
      document: new Uint8Array(r.document),
      images: new Uint8Array(r.images),
    };
  }

  /** Pastes copied layers as one step, in every worker. */
  paste(
    page: number,
    copied: CopiedLayers,
    spec: PasteSpec
  ): Promise<EditResult> {
    // Each worker gets its own copy of the bytes (they are transferred).
    return this.edit(() => {
      const document = copied.document.slice().buffer;
      const images =
        copied.images.length > 0 ? copied.images.slice().buffer : null;
      return {
        body: {
          kind: 'paste',
          page,
          document,
          images,
          spec: JSON.stringify(spec),
        },
        transfer: images ? [document, images] : [document],
      };
    });
  }

  /**
   * Applies an edit step on every worker (each holds the document); the
   * primary's answer is returned. A helper that disagrees is dropped.
   */
  private async edit(
    make:
      | Extract<Body, { kind: 'edit' }>
      | (() => {
          body: Extract<Body, { kind: 'paste' | 'importLibrary' }>;
          transfer: Transferable[];
        })
  ): Promise<EditResult> {
    const request = (w: EngineWorker) => {
      if (typeof make !== 'function') return w.request(make);
      const { body, transfer } = make();
      return w.request(body, transfer);
    };
    // Every worker holds the same document, so an edit the engine rejects
    // fails in all of them; a helper is dropped only when its result
    // differs from the primary's.
    const fanned = [...this.helpers, ...this.starting].map((h) => ({
      h,
      done: request(h).then(
        () => true,
        () => false
      ),
    }));
    const drop = (h: EngineWorker) => {
      const at = this.helpers.indexOf(h);
      if (at >= 0) this.helpers.splice(at, 1);
      h.terminate();
    };
    let r: Ok;
    try {
      r = await request(this.primary);
    } catch (error) {
      for (const { h, done } of fanned)
        fireAndForget(
          done.then((ok) => ok && drop(h)),
          'fig-engine'
        );
      throw error;
    }
    for (const { h, done } of fanned)
      fireAndForget(
        done.then((ok) => !ok && drop(h)),
        'fig-engine'
      );
    if (r.kind !== 'edit') throw new Error('unexpected response');
    return JSON.parse(r.json) as EditResult;
  }

  /** What publishing the file as a library would change. */
  libraryStatus(): Promise<LibraryStatus> {
    return this.query('libraryStatus');
  }

  /** The file's published library assets. */
  libraryAssets(): Promise<PublishedLibrary> {
    return this.query('libraryAssets');
  }

  /** The libraries the file uses and its copies of their assets. */
  libraryUses(): Promise<LibraryUse> {
    return this.query('libraryUses');
  }

  /** The library assets named by `keys`, with what they use, for another file. */
  async libraryPackage(keys: string[]): Promise<LibraryPackage> {
    const r = await this.primary.request({
      kind: 'libraryPackage',
      keys: JSON.stringify(keys),
    });
    if (r.kind !== 'copied') throw new Error('unexpected response');
    return {
      document: new Uint8Array(r.document),
      images: new Uint8Array(r.images),
    };
  }

  /** Imports a library package as one step, in every worker. */
  importLibrary(
    page: number,
    pkg: LibraryPackage,
    spec: LibrarySpec
  ): Promise<EditResult> {
    return this.edit(() => {
      const document = pkg.document.slice().buffer;
      const images = pkg.images.length > 0 ? pkg.images.slice().buffer : null;
      return {
        body: {
          kind: 'importLibrary',
          page,
          document,
          images,
          spec: JSON.stringify(spec),
        },
        transfer: images ? [document, images] : [document],
      };
    });
  }

  /** A PNG of a layer on any canvas (library copies too); null when empty. */
  async nodeThumbnail(id: string, size: number): Promise<Blob | null> {
    const r = await this.primary.request({
      kind: 'nodeThumbnail',
      node: id,
      size,
    });
    if (r.kind !== 'png' || !r.bytes) return null;
    return new Blob([r.bytes], { type: 'image/png' });
  }

  /** Applies edit operations (see `fig_engine::edit::Op`) as one step. */
  apply(page: number, ops: unknown[], coalesce?: string): Promise<EditResult> {
    return this.edit({
      kind: 'edit',
      page,
      action: 'apply',
      ops: JSON.stringify(ops),
      coalesce,
    });
  }

  undo(page: number): Promise<EditResult> {
    return this.edit({ kind: 'edit', page, action: 'undo' });
  }

  redo(page: number): Promise<EditResult> {
    return this.edit({ kind: 'edit', page, action: 'redo' });
  }

  /**
   * Starts editing together with other people, in every worker: new layers
   * get ids in `session` (unique per person and visit). `baseBlobs` is the
   * shared `figMeta.baseBlobs`, when set. Resolves to changes to write.
   */
  async enableCollab(
    session: number,
    baseBlobs: number | null
  ): Promise<EntryChange[]> {
    for (const h of [...this.helpers, ...this.starting])
      h.request({ kind: 'enableCollab', session, baseBlobs }).catch(() => {});
    const r = await this.primary.request({
      kind: 'enableCollab',
      session,
      baseBlobs,
    });
    if (r.kind !== 'query') throw new Error('unexpected response');
    return JSON.parse(r.json) as EntryChange[];
  }

  /** The shared-map changes of this person's edits since the last call. */
  async collabChanges(): Promise<EntryChange[]> {
    const r = await this.primary.request({ kind: 'collabChanges' });
    if (r.kind !== 'query') throw new Error('unexpected response');
    return JSON.parse(r.json) as EntryChange[];
  }

  /** Applies other people's changes in every worker (not undoable here). */
  applyRemote(page: number, changes: EntryChange[]): Promise<EditResult> {
    return this.edit({
      kind: 'edit',
      page,
      action: 'remote',
      changes: JSON.stringify(changes),
    });
  }

  /**
   * Adds an image file (PNG, JPEG, GIF, WebP) for image fills, in every
   * worker; returns its SHA-1 (the paint's reference) and pixel size.
   */
  async addImage(
    bytes: ArrayBuffer
  ): Promise<{ hash: string; width: number; height: number }> {
    const digest = await crypto.subtle.digest('SHA-1', bytes);
    const hash = [...new Uint8Array(digest)]
      .map((b) => b.toString(16).padStart(2, '0'))
      .join('');
    for (const h of [...this.helpers, ...this.starting]) {
      const copy = bytes.slice(0);
      h.request({ kind: 'addImage', hash, bytes: copy }, [copy]).catch(
        () => {}
      );
    }
    const copy = bytes.slice(0);
    const r = await this.primary.request(
      { kind: 'addImage', hash, bytes: copy },
      [copy]
    );
    if (r.kind !== 'query') throw new Error('unexpected response');
    const [width, height] = JSON.parse(r.json) as [number, number];
    return { hash, width, height };
  }

  /** The edited file as `.fig` bytes. */
  async save(): Promise<Uint8Array<ArrayBuffer>> {
    const r = await this.primary.request({ kind: 'save' });
    if (r.kind !== 'saved') throw new Error('unexpected response');
    return new Uint8Array(r.bytes);
  }

  /** Figma's own thumbnail of the file, when it has one. */
  async thumbnail(): Promise<Blob | null> {
    const r = await this.primary.request({ kind: 'thumbnail' });
    if (r.kind !== 'png' || !r.bytes) return null;
    return new Blob([r.bytes], { type: 'image/png' });
  }

  get failed(): boolean {
    return this.primary.dead;
  }

  /**
   * Keeps the file open until `work` settles, even if it is closed first
   * (so the save started when the editor goes away can finish).
   */
  retain(work: Promise<unknown>) {
    this.holds.add(work);
    const release = async () => {
      try {
        await work;
      } catch {
        // Its own caller reports failures.
      } finally {
        this.holds.delete(work);
      }
    };
    fireAndForget(release(), 'fig-engine');
  }

  close() {
    this.closed = true;
    const primary = this.primary;
    if (this.holds.size === 0) primary.terminate();
    else
      fireAndForget(
        Promise.allSettled([...this.holds]).then(() => primary.terminate()),
        'fig-engine'
      );
    for (const h of this.helpers) h.terminate();
    for (const h of this.starting) h.terminate();
    this.helpers.length = 0;
    this.starting.clear();
  }
}