Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
/**
* Editing on top of the viewer: the operations the canvas, panels, and
* shortcuts perform, undo and redo, and saving.
*
* Every change is an engine operation (`fig_engine::edit::Op`) applied in
* all engine workers. After each step the changed page area is re-rendered
* (see `TileCompositor.invalidate`) and the viewer reloads what it shows.
* Saving writes the whole `.fig` (the engine patches only what changed)
* after a short pause in editing, when the tab is hidden, and on close.
*/
import type { EditResult, FigEngine } from '@core/fig-engine/client';
import type {
LibraryPackage,
LibrarySpec,
} from '@core/fig-engine/library-types';
import type {
NodeInfo,
PasteSpec,
Rect,
Sizing,
VectorNetwork,
} from '@core/fig-engine/types';
import { fireAndForget } from '@core/util/fireAndForget';
import { Telemetry } from '@macro-inc/observability';
import { createSignal, onCleanup } from 'solid-js';
import type { FigSharing } from '../context/fig-viewer-context';
import { type Alignment, alignOffset, distributeOffsets } from '../core/align';
import type { BooleanOperation } from '../core/boolean';
import type { Point } from '../core/camera';
import {
type ClipboardMeta,
decodeClipboard,
encodeClipboard,
pasteParent,
} from '../core/clipboard';
import type { DesignOp } from '../core/design-system';
import type { HandoffOp } from '../core/handoff-ops';
import type { LibraryOp } from '../core/libraries';
import { copyPaint, type PaintType, type StopSpec } from '../core/paint';
import type { InteractionSpec } from '../core/prototype';
import { resizedOrigin } from '../core/rotation';
import type { Measure } from '../core/type';
import { type PenPoint, pencilPoints, penNetwork } from '../core/vector';
import type { FigViewer, Selected } from './create-fig-viewer';
import { resolveFrameDrop } from './resolve-frame-drop';
export type SaveState = 'saved' | 'unsaved' | 'saving' | 'error';
/** Characters selected in a text layer being edited (UTF-16 units). */
export interface TextSelection {
id: string;
start: number;
end: number;
}
/** Properties to set (`fig_engine::edit::Patch`). */
export interface Patch {
name?: string;
x?: number;
y?: number;
width?: number;
height?: number;
rotation?: number;
opacity?: number;
visible?: boolean;
locked?: boolean;
fills?: PaintSpec[];
strokes?: PaintSpec[];
strokeWeight?: number;
strokeAlign?: 'INSIDE' | 'OUTSIDE' | 'CENTER';
cornerRadius?: number;
clipContent?: boolean;
blendMode?: string;
characters?: string;
fontSize?: number;
fontFamily?: string;
/** Figma's style name: `Regular`, `Semi Bold`, `Bold Italic`… */
fontStyle?: string;
lineHeight?: Measure;
letterSpacing?: Measure;
paragraphSpacing?: number;
textAlignHorizontal?: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED';
textAlignVertical?: 'TOP' | 'CENTER' | 'BOTTOM';
textAutoResize?: 'WIDTH_AND_HEIGHT' | 'HEIGHT' | 'NONE';
textDecoration?: 'NONE' | 'UNDERLINE' | 'STRIKETHROUGH';
textCase?: 'ORIGINAL' | 'UPPER' | 'LOWER' | 'TITLE';
/**
* Characters (UTF-16 units, `[start, end)`) the text fields and fills
* apply to, instead of the whole text layer.
*/
textRange?: [number, number];
/** Auto layout direction; `NONE` removes it. */
layoutMode?: 'HORIZONTAL' | 'VERTICAL' | 'NONE';
itemSpacing?: number;
paddingTop?: number;
paddingRight?: number;
paddingBottom?: number;
paddingLeft?: number;
primaryAlign?: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN';
counterAlign?: 'MIN' | 'CENTER' | 'MAX';
sizingHorizontal?: Sizing;
sizingVertical?: Sizing;
layoutPositioning?: 'AUTO' | 'ABSOLUTE';
constraintHorizontal?: Constraint;
constraintVertical?: Constraint;
/** Replaces the effects, bottom first. */
effects?: EffectSpec[];
strokeCap?: 'NONE' | 'ROUND' | 'SQUARE' | 'ARROW_LINES' | 'ARROW_EQUILATERAL';
/** Dash and gap lengths along strokes; empty for a solid stroke. */
dashPattern?: number[];
}
/** An effect as the editor sends it: an existing one kept, or a new one. */
export interface EffectSpec {
keep?: number;
type?: 'DROP_SHADOW' | 'INNER_SHADOW' | 'LAYER_BLUR' | 'BACKGROUND_BLUR';
/** `RRGGBB` or `RRGGBBAA`. */
color?: string;
x?: number;
y?: number;
radius?: number;
spread?: number;
visible?: boolean;
}
/** How a layer follows its frame's resizing. */
export type Constraint = 'MIN' | 'MAX' | 'CENTER' | 'STRETCH' | 'SCALE';
/** A paint as the editor sends it: an existing one kept, or a solid. */
export interface PaintSpec {
keep?: number;
/** An image fill, by the hash `FigEngine.addImage` returned. */
image?: string;
/** `RRGGBB` or `RRGGBBAA`. */
color?: string;
opacity?: number;
visible?: boolean;
/** Switches the kind: `SOLID` or a gradient (stops carried over). */
type?: PaintType;
/** A gradient's stops, replacing its current ones. */
stops?: StopSpec[];
}
export type Arrangement = 'forward' | 'backward' | 'front' | 'back';
export type ShapeTool =
| 'frame'
| 'rectangle'
| 'ellipse'
| 'line'
| 'arrow'
| 'text';
export type Op =
| { op: 'set'; ids: string[]; props: Patch }
| { op: 'translate'; ids: string[]; dx: number; dy: number }
| {
op: 'create';
parent: string;
index?: number;
node: {
type: string;
name?: string;
x: number;
y: number;
width: number;
height: number;
props?: Patch;
};
}
| { op: 'delete'; ids: string[] }
| { op: 'reorder'; ids: string[]; parent: string; index: number }
| { op: 'arrange'; ids: string[]; how: Arrangement }
| { op: 'duplicate'; ids: string[]; dx?: number; dy?: number }
| { op: 'group'; ids: string[]; frame?: boolean }
| { op: 'ungroup'; ids: string[] }
| { op: 'reflow'; ids: string[] }
| { op: 'autoLayout'; ids: string[] }
| { op: 'createComponent'; ids: string[] }
| {
op: 'instantiate';
component: string;
parent: string;
x: number;
y: number;
}
| { op: 'detach'; ids: string[] }
| { op: 'flip'; ids: string[]; vertical?: boolean }
| { op: 'boolean'; ids: string[]; operation: BooleanOperation }
| { op: 'flatten'; ids: string[] }
| {
op: 'createVector';
parent: string;
index?: number;
/** Page coordinates. */
network: VectorNetwork;
name?: string;
props?: Patch;
}
| { op: 'setVector'; id: string; network: VectorNetwork }
| { op: 'setInteractions'; id: string; interactions: InteractionSpec[] }
| { op: 'setFlowStart'; id: string; name: string | null }
| HandoffOp
| DesignOp
| LibraryOp;
export interface FigEditorOptions {
engine: FigEngine;
viewer: FigViewer;
/** Whether this person may edit (viewers get a read-only canvas). */
canEdit: () => boolean;
/** Stores the edited file; absent when nothing can be saved. */
save?: (bytes: Uint8Array) => Promise<void>;
/** Identifies the file to the clipboard (a document id). */
fileKey?: string;
/** Called with each changed page area, to re-render it. */
onDirty: (rect: Rect) => void;
notifyError: (message: string) => void;
/** Live edits with other people, when the design is shared. */
sharing?: FigSharing;
/**
* Whether this person stores the merged file (one person among those
* editing does). Defaults to always.
*/
stores?: () => boolean;
/**
* Whether the sync service of a shared design is reachable; storing
* waits for it (see `FigSharing.willStore`). Defaults to always.
*/
online?: () => boolean;
}
/** Undo steps whose selections are remembered (the engine keeps 200). */
const MAX_REMEMBERED_STEPS = 256;
/** Quiet time after the last edit before saving. */
const SAVE_DELAY_MS = 1500;
/** How often the steps of one gesture are shared with other people. */
const GESTURE_PUSH_MS = 80;
const TYPE_FOR_TOOL: Record<ShapeTool, string> = {
frame: 'FRAME',
rectangle: 'RECTANGLE',
ellipse: 'ELLIPSE',
line: 'LINE',
arrow: 'LINE',
text: 'TEXT',
};
export function createFigEditor(options: FigEditorOptions) {
const { engine, viewer } = options;
const [canUndo, setCanUndo] = createSignal(false);
const [canRedo, setCanRedo] = createSignal(false);
const [saveState, setSaveState] = createSignal<SaveState>('saved');
/** The text layer being typed into, if any. */
const [editingText, setEditingText] = createSignal<string>();
/** The characters selected in the text editor (UTF-16 units). */
const [textSelection, setTextSelection] = createSignal<TextSelection>();
/** The points of the path the pen is drawing (page coordinates). */
const [penPath, setPenPath] = createSignal<PenPoint[]>();
/**
* The layer whose points are being edited, its points (page
* coordinates), and the selected point.
*/
const [vectorEdit, setVectorEdit] = createSignal<{
id: string;
network: VectorNetwork;
selected?: number;
}>();
let clipboard: string[] = [];
/** Whether the page may read the system clipboard without asking. */
let clipboardReadable = false;
void navigator.permissions
?.query({ name: 'clipboard-read' as PermissionName })
.then((status) => {
clipboardReadable = status.state === 'granted';
status.onchange = () => {
clipboardReadable = status.state === 'granted';
};
})
.catch(() => {});
let saveTimer: ReturnType<typeof setTimeout> | undefined;
let saving: Promise<void> | undefined;
let dirtySinceSave = false;
let dragKey = 0;
const enabled = () => options.canEdit();
const ids = () => viewer.selected().map((s) => s.id);
// Instance sublayers cannot be moved, resized, or removed, as in Figma;
// their appearance and text are overridden (`setProps`).
const editableIds = () => ids().filter((id) => !id.startsWith('I'));
// ---- saving ----------------------------------------------------------
const { sharing } = options;
// In a shared design one person stores the merged file; the others'
// edits are kept by the sync service until then.
const stores = () => options.stores?.() ?? true;
const saveNow = async (): Promise<void> => {
clearTimeout(saveTimer);
saveTimer = undefined;
if (!options.save || !dirtySinceSave || !stores() || !enabled()) return;
if (options.online?.() === false) {
// The changes wait in the sync log, and are stored once it is
// reachable (see `takeOver`).
setSaveState('unsaved');
return;
}
if (saving) {
await saving;
if (!dirtySinceSave) return;
}
dirtySinceSave = false;
setSaveState('saving');
const run = (async () => {
try {
const version = sharing?.appliedVersion();
const bytes = await engine.save();
if (sharing && !(await sharing.willStore(bytes))) {
dirtySinceSave = true;
setSaveState('unsaved');
return;
}
await options.save?.(bytes);
if (version) sharing?.markStored(version);
setSaveState(dirtySinceSave ? 'unsaved' : 'saved');
} catch (e) {
dirtySinceSave = true;
setSaveState('error');
options.notifyError(
e instanceof Error ? e.message : 'The design could not be saved'
);
}
})();
saving = run;
await run;
saving = undefined;
};
const scheduleSave = () => {
dirtySinceSave = true;
clearTimeout(saveTimer);
saveTimer = undefined;
// Shared live, so nothing is lost while someone else stores the file.
if (!stores()) return;
setSaveState('unsaved');
saveTimer = setTimeout(
() => fireAndForget(saveNow(), 'fig-editor'),
SAVE_DELAY_MS
);
};
const onHidden = () => {
if (document.visibilityState === 'hidden')
fireAndForget(saveNow(), 'fig-editor');
};
document.addEventListener('visibilitychange', onHidden);
// Whoever stores the file now (the one who did may have left) stores
// changes nobody stored yet.
const takeOver = sharing
? setInterval(() => {
if (dirtySinceSave && stores() && !saveTimer && !saving) scheduleSave();
}, SAVE_DELAY_MS * 2)
: undefined;
const unsubscribeStored = sharing?.onStoredElsewhere(() => {
if (saving) return;
dirtySinceSave = false;
clearTimeout(saveTimer);
saveTimer = undefined;
setSaveState('saved');
});
onCleanup(() => {
document.removeEventListener('visibilitychange', onHidden);
clearInterval(takeOver);
unsubscribeStored?.();
engine.retain(saveNow());
});
// ---- applying ----------------------------------------------------------
let queue: Promise<unknown> = Promise.resolve();
// What was selected around each undo step, so undo and redo bring the
// selection back as Figma does (undoing a duplicate selects the original).
const stepSelections = new Map<
number,
{ page: number; before: Selected[]; after?: Selected[] }
>();
let undoStep: number | null = null;
let redoStep: number | null = null;
/** Selects what was selected, as far as those layers still exist. */
const restoreSelection = async (page: number, wanted: Selected[]) => {
if (viewer.page() !== page) return;
const rows =
wanted.length > 0
? await engine.rows(
page,
wanted.map((s) => s.id)
)
: [];
const alive = new Set(rows.map((r) => r.id));
viewer.select(wanted.filter((s) => alive.has(s.id)));
};
/** After a step: undo state, saving, and (unless `quiet`) the view. */
const settle = async (result: EditResult, quiet = false) => {
setCanUndo(result.canUndo);
setCanRedo(result.canRedo);
undoStep = result.undoStep;
redoStep = result.redoStep;
scheduleSave();
if (quiet) return;
if (result.dirty) options.onDirty(result.dirty);
await viewer.afterEdit();
};
/** Applies other people's changes that arrived (inside the queue). */
const pullShared = async () => {
const result = await sharing?.pull(viewer.page());
if (!result) return;
await settle(result);
await viewer.pruneSelection();
};
// Steps of one gesture (a drag, typing) are shared at most this often;
// anything else is shared right away.
let pushTimer: ReturnType<typeof setTimeout> | undefined;
const pushNow = async () => {
clearTimeout(pushTimer);
pushTimer = undefined;
await sharing?.push();
};
const pushSoon = () => {
if (pushTimer) return;
pushTimer = setTimeout(() => {
pushTimer = undefined;
queue = queue.then(async () => {
try {
await sharing?.push();
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
}
});
}, GESTURE_PUSH_MS);
};
onCleanup(() => clearTimeout(pushTimer));
let pullQueued = false;
const unsubscribeIncoming = sharing?.onIncoming(() => {
if (pullQueued) return;
pullQueued = true;
queue = queue.then(async () => {
pullQueued = false;
try {
await pullShared();
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
}
});
});
onCleanup(() => unsubscribeIncoming?.());
/**
* Applies operations as one undo step, in order with other edits.
* Resolves to the engine's result (undefined when not allowed or failed).
* `quiet` steps re-render and reload nothing (a lifted move's steps,
* which the canvas draws itself).
*/
const apply = (
ops: Op[] | ((page: number) => Promise<Op[]>),
coalesce?: string,
quiet = false
) => {
if (!enabled() || (Array.isArray(ops) && ops.length === 0))
return Promise.resolve(undefined);
const run = queue.then(async () => {
try {
// Other people's changes that arrived first apply first.
await pullShared();
const page = viewer.page();
const resolved = typeof ops === 'function' ? await ops(page) : ops;
if (resolved.length === 0) return undefined;
const before = viewer.selected();
const result = await engine.apply(page, resolved, coalesce);
// A drag's later steps coalesce into its first: keep that one's.
if (result.undoStep !== null && !stepSelections.has(result.undoStep)) {
stepSelections.set(result.undoStep, { page, before });
// The engine keeps 200 steps; forget the oldest beyond that.
for (const id of stepSelections.keys()) {
if (stepSelections.size <= MAX_REMEMBERED_STEPS) break;
stepSelections.delete(id);
}
}
if (coalesce) pushSoon();
else await pushNow();
await settle(result, quiet);
return result;
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
return undefined;
}
});
queue = run;
return run;
};
const history = (action: 'undo' | 'redo'): Promise<unknown> => {
if (!enabled()) return Promise.resolve();
queue = queue.then(async () => {
try {
await pullShared();
const step = action === 'undo' ? undoStep : redoStep;
const remembered = step === null ? undefined : stepSelections.get(step);
if (remembered && action === 'undo')
remembered.after = viewer.selected();
const result =
action === 'undo'
? await engine.undo(viewer.page())
: await engine.redo(viewer.page());
// Undo is local: what it restores is shared as a new change.
await pushNow();
await settle(result);
const wanted =
action === 'undo' ? remembered?.before : remembered?.after;
if (remembered && wanted)
await restoreSelection(remembered.page, wanted);
else await viewer.pruneSelection();
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
}
});
return queue;
};
/** Selects the layers a step created. */
const selectCreated = async (result: EditResult | undefined) => {
if (result && result.created.length > 0)
await viewer.selectIds(result.created);
};
// ---- selection operations ---------------------------------------------
const setProps = (patch: Patch, coalesce?: string) => {
// Layers in instances take the patch as overrides.
const targets = ids();
if (targets.length === 0) return Promise.resolve(undefined);
return apply([{ op: 'set', ids: targets, props: patch }], coalesce);
};
const toggleLocked = (targets = ids()) => {
const page = viewer.page();
return apply(async (currentPage) => {
if (currentPage !== page || targets.length === 0) return [];
// Read after queued and remote edits, never from the inspector or a
// cached layer row. Several layers unlock only when all are locked.
const rows = await engine.rows(page, targets);
if (rows.length === 0) return [];
return [
{
op: 'set',
ids: rows.map((row) => row.id),
props: { locked: rows.some((row) => !row.locked) },
},
];
});
};
const deleteSelection = async () => {
const targets = editableIds();
if (targets.length === 0) return;
await apply([{ op: 'delete', ids: targets }]);
viewer.select([]);
};
const duplicateSelection = async () => {
const result = await apply([
{ op: 'duplicate', ids: editableIds(), dx: 0, dy: 0 },
]);
await selectCreated(result);
};
const group = async (frame = false) => {
const targets = editableIds();
if (targets.length === 0) return;
const result = await apply([{ op: 'group', ids: targets, frame }]);
await selectCreated(result);
};
/** Figma's ⇧A: a frame gets auto layout; other layers are wrapped. */
const addAutoLayout = async () => {
const targets = editableIds();
if (targets.length === 0) return;
const result = await apply([{ op: 'autoLayout', ids: targets }]);
await selectCreated(result);
};
/** ⌥⌘K: a frame becomes a component; other layers are wrapped. */
const createComponent = async () => {
const targets = editableIds();
if (targets.length === 0) return;
const result = await apply([{ op: 'createComponent', ids: targets }]);
await selectCreated(result);
};
/** ⌥⌘B: instances become ordinary layers. */
const detachInstance = () => apply([{ op: 'detach', ids: editableIds() }]);
/** Places an instance of a component in the middle of the view. */
const insertInstance = async (component: {
id: string;
width: number;
height: number;
}) => {
const c = viewer.camera();
const v = viewer.viewport();
const x = Math.round(c.x + v.w / 2 / c.zoom - component.width / 2);
const y = Math.round(c.y + v.h / 2 / c.zoom - component.height / 2);
const page = viewer.pages[viewer.page()];
if (!page) return;
const result = await apply([
{ op: 'instantiate', component: component.id, parent: page.id, x, y },
]);
await selectCreated(result);
};
/** The page point that centers a `width × height` box in the view. */
const viewCenter = (width: number, height: number) => {
const c = viewer.camera();
const v = viewer.viewport();
return {
x: Math.round(c.x + v.w / 2 / c.zoom - width / 2),
y: Math.round(c.y + v.h / 2 / c.zoom - height / 2),
};
};
/**
* Imports library assets (a package from the library's engine) as one
* step, in order with other edits, selecting what `spec.then` created.
*/
const importLibrary = async (pkg: LibraryPackage, spec: LibrarySpec) => {
if (!enabled()) return undefined;
const run = queue.then(async () => {
try {
await pullShared();
const result = await engine.importLibrary(viewer.page(), pkg, spec);
await pushNow();
await settle(result);
return result;
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
return undefined;
}
});
queue = run;
const result = await run;
await selectCreated(result);
return result;
};
const removeAutoLayout = () =>
apply([{ op: 'set', ids: editableIds(), props: { layoutMode: 'NONE' } }]);
const ungroup = async () => {
const result = await apply([{ op: 'ungroup', ids: editableIds() }]);
await selectCreated(result);
};
const arrange = (how: Arrangement) =>
apply([{ op: 'arrange', ids: editableIds(), how }]);
/** Arrow-key nudges; consecutive ones undo together. */
let nudgeTimer: ReturnType<typeof setTimeout> | undefined;
let nudgeKey = 0;
const nudge = (dx: number, dy: number) => {
clearTimeout(nudgeTimer);
nudgeTimer = setTimeout(() => nudgeKey++, 800);
return apply(
[{ op: 'translate', ids: editableIds(), dx, dy }],
`nudge-${nudgeKey}`
);
};
/** Aligns the selection (or one layer within its parent frame). */
const align = async (how: Alignment) => {
const geometry = viewer
.selectionGeometry()
.filter((g) => !g.id.startsWith('I'));
if (geometry.length === 0) return;
let to: Rect | undefined;
if (geometry.length > 1) {
to = viewer.selectionBounds();
} else {
const parent = viewer.selected()[0]?.parent;
if (!parent) return;
to = (await engine.geometry(viewer.page(), [parent]))[0]?.bounds;
}
if (!to) return;
const target = to;
const ops: Op[] = geometry
.map((g) => ({ id: g.id, ...alignOffset(g.bounds, target, how) }))
.filter((o) => Math.abs(o.dx) > 1e-6 || Math.abs(o.dy) > 1e-6)
.map((o) => ({
op: 'translate' as const,
ids: [o.id],
dx: Math.round(o.dx * 100) / 100,
dy: Math.round(o.dy * 100) / 100,
}));
await apply(ops);
};
/** Spaces three or more layers evenly (Figma's distribute spacing). */
const distribute = async (axis: 'horizontal' | 'vertical') => {
const boxes = viewer
.selectionGeometry()
.filter((g) => !g.id.startsWith('I'))
.map((g) => ({ id: g.id, bounds: g.bounds }));
const ops: Op[] = distributeOffsets(boxes, axis)
.filter((o) => Math.abs(o.dx) > 1e-6 || Math.abs(o.dy) > 1e-6)
.map((o) => ({
op: 'translate' as const,
ids: [o.id],
dx: Math.round(o.dx * 100) / 100,
dy: Math.round(o.dy * 100) / 100,
}));
if (ops.length > 0) await apply(ops);
};
/** Figma's ⇧X: a layer's fills become its strokes and the other way. */
const swapFillStroke = async (info: NodeInfo) => {
const copies = (paints: NodeInfo['fills']) =>
paints.map(copyPaint).filter((p): p is PaintSpec => p !== null);
const fills = copies(info.strokes);
const strokes = copies(info.fills);
if (fills.length === 0 && strokes.length === 0) return;
// A layer without a stroke weight shows none: give it Figma's 1.
const weight = strokes.length > 0 && !info.strokeWeight ? 1 : undefined;
await setProps({
fills,
strokes,
...(weight ? { strokeWeight: weight } : {}),
});
};
/**
* ⌘C: the selected layers go on the system clipboard as Figma puts them
* there (they paste into other files and tabs), and are remembered for
* pasting here when the clipboard cannot be written.
*/
const copy = () => {
clipboard = editableIds();
const ids = clipboard;
if (ids.length === 0) return;
const meta: ClipboardMeta = {
fileKey: options.fileKey ?? '',
pasteID: Math.floor(Math.random() * 2 ** 31),
dataType: 'scene',
ids,
};
const html = engine
.copy(viewer.page(), ids)
.then(
(copied) =>
new Blob([encodeClipboard({ meta, copied })], { type: 'text/html' })
);
// The item is handed over now, inside the key press, and filled in
// when the engine has written the layers.
try {
if (typeof ClipboardItem === 'undefined') return;
void navigator.clipboard
.write([new ClipboardItem({ 'text/html': html })])
.catch(() => {});
} catch {
// No clipboard access: pasting here still works.
}
};
/**
* The system clipboard's HTML, for the context menu's paste actions (⌘V
* gets it from the paste event); undefined without clipboard access. The
* browser is asked for access only when nothing was copied here, so a
* menu paste never waits on a permission prompt it does not need.
*/
const readClipboardHtml = async (): Promise<string | undefined> => {
try {
if (clipboard.length > 0) {
const status = await navigator.permissions.query({
name: 'clipboard-read' as PermissionName,
});
if (status.state !== 'granted') return undefined;
}
for (const item of await navigator.clipboard.read()) {
if (item.types.includes('text/html'))
return await (await item.getType('text/html')).text();
}
} catch {
// No access: the layers copied here are pasted.
}
return undefined;
};
/**
* Pastes layers: those on the clipboard (`html`: copied here, in another
* file, or in Figma), or else the ones copied here, as one step. By
* default they go by Figma's rules: into a selected frame, beside a
* selected layer, or onto the page, where they were when that is in view
* and in the middle of the view otherwise. "Paste here" puts their top
* left at a point; "Paste to replace" puts them in place of layers.
*/
const pasteLayers = async (
html: string | undefined,
place?: { at: Point } | { replace: string[] }
) => {
const payload = html ? decodeClipboard(html) : undefined;
const page = viewer.pages[viewer.page()];
if (!enabled() || !page) return;
const own = clipboard;
if (!payload && own.length === 0) return;
let parent = page.id;
if (place && 'at' in place) {
parent = await viewer.containerAt(place.at);
} else if (!place) {
const selection = viewer.selected();
const rows =
selection.length > 0
? await engine.rows(
viewer.page(),
selection.map((s) => s.id)
)
: [];
const sameFile =
!payload ||
(!!payload.meta && payload.meta.fileKey === (options.fileKey ?? ''));
parent = pasteParent(
selection.map((s) => ({
...s,
type: rows.find((r) => r.id === s.id)?.type ?? 'GROUP',
})),
page.id,
sameFile ? (payload ? (payload.meta?.ids ?? []) : own) : []
);
}
const c = viewer.camera();
const v = viewer.viewport();
const spec: PasteSpec = {
parent,
view: { x: c.x, y: c.y, w: v.w / c.zoom, h: v.h / c.zoom },
...(place && 'at' in place ? { at: place.at } : {}),
...(place && 'replace' in place ? { replace: place.replace } : {}),
};
const run = queue.then(async () => {
try {
const copied =
payload?.copied ?? (await engine.copy(viewer.page(), own));
// As with other steps: others' changes first, then share this one.
await pullShared();
const result = await engine.paste(viewer.page(), copied, spec);
await pushNow();
await settle(result);
return result;
} catch (e) {
options.notifyError(e instanceof Error ? e.message : String(e));
return undefined;
}
});
queue = run;
await selectCreated(await run);
};
/** ⌘V (`html` from the paste event) and the menus' Paste. */
const paste = (html?: string) => pasteLayers(html);
/** Figma's "Paste here": the layers' top left at a page point. */
const pasteHere = async (at: Point) =>
pasteLayers(await readClipboardHtml(), { at });
/** "Paste to replace": in place of the selection, centered on it. */
const pasteToReplace = async () => {
const targets = editableIds();
const html = await readClipboardHtml();
return pasteLayers(
html,
targets.length > 0 ? { replace: targets } : undefined
);
};
/** Cut layers stay pasteable: the engine can copy a deleted layer. */
const cut = async () => {
copy();
if (clipboard.length === 0) return;
await apply([{ op: 'delete', ids: clipboard }]);
viewer.select([]);
};
// ---- shapes --------------------------------------------------------------
/** Union, Subtract, Intersect, Exclude (⌥⇧U, S, I, X). */
const booleanOp = async (operation: BooleanOperation) => {
const targets = editableIds();
if (targets.length === 0) return;
const result = await apply([{ op: 'boolean', ids: targets, operation }]);
await selectCreated(result);
};
/** ⌘E: the selection becomes one vector layer. */
const flatten = async () => {
const targets = editableIds();
if (targets.length === 0) return;
const result = await apply([{ op: 'flatten', ids: targets }]);
await selectCreated(result);
};
/** Adds a point to the pen's path. */
const penAdd = (point: PenPoint) =>
setPenPath((points) => [...(points ?? []), point]);
/** Sets the handle of the point the pen placed last (while dragging). */
const penHandle = (handle: { x: number; y: number }) =>
setPenPath((points) => {
if (!points || points.length === 0) return points;
const next = [...points];
next[next.length - 1] = { ...next[next.length - 1], handle };
return next;
});
/**
* Ends the pen's path (Enter, Escape, or a press on its first point,
* which closes it): a vector layer is made, in the frame under its first
* point, and selected.
*/
const penFinish = async (closed = false) => {
const points = penPath();
setPenPath(undefined);
viewer.setTool('move');
if (!points || points.length < 2) return undefined;
const parent = await viewer.containerAt(points[0]);
const result = await apply([
{
op: 'createVector',
parent,
network: penNetwork(points, closed),
},
]);
await selectCreated(result);
return result?.created[0];
};
/**
* Ends a pencil stroke (page points): a smoothed open path, made in the
* frame under where it started and selected. The pencil stays chosen.
*/
const pencilFinish = async (stroke: Point[], tolerance: number) => {
if (!enabled() || stroke.length < 2) return undefined;
const points = pencilPoints(stroke, tolerance);
if (points.length < 2) return undefined;
const parent = await viewer.containerAt(points[0]);
const result = await apply([
{
op: 'createVector',
parent,
network: penNetwork(points, false),
},
]);
await selectCreated(result);
return result?.created[0];
};
/** Starts editing a layer's points (double-click or Enter, as in Figma). */
const editVector = async (id: string) => {
if (!enabled() || id.startsWith('I')) return false;
const network = await engine.vectorNetwork(viewer.page(), id);
if (!network) return false;
setVectorEdit({ id, network });
return true;
};
const endVectorEdit = () => setVectorEdit(undefined);
const selectVertex = (index: number | undefined) =>
setVectorEdit((v) => v && { ...v, selected: index });
/** A point or handle drag: the layer follows live; steps undo as one. */
const startVectorDrag = () => {
const key = `vector-${++dragKey}`;
let wanted: VectorNetwork | undefined;
let running = false;
const pump = async () => {
if (running) return;
running = true;
while (wanted) {
const network = wanted;
wanted = undefined;
const id = vectorEdit()?.id;
if (!id) break;
await apply([{ op: 'setVector', id, network }], key);
}
running = false;
};
return {
to(network: VectorNetwork) {
setVectorEdit((v) => v && { ...v, network });
wanted = network;
fireAndForget(pump(), 'fig-editor');
},
async end() {
await pump();
await queue;
},
};
};
/**
* Replaces the points of the layer being edited (a point deleted, say);
* a layer left without points is deleted.
*/
const setVectorNetwork = async (network: VectorNetwork) => {
const edit = vectorEdit();
if (!edit) return;
if (network.vertices.length === 0) {
endVectorEdit();
await apply([{ op: 'delete', ids: [edit.id] }]);
viewer.select([]);
return;
}
setVectorEdit({ ...edit, network, selected: undefined });
await apply([{ op: 'setVector', id: edit.id, network }]);
};
/** ⇧H / ⇧V: mirrors the selection about each layer's center. */
const flip = (vertical: boolean) =>
apply([{ op: 'flip', ids: editableIds(), vertical }]);
// ---- drags ---------------------------------------------------------------
/** A move drag: offsets accumulate; one engine step at a time. */
const startMove = (targets: string[]) => {
const key = `drag-${++dragKey}`;
let applied = { x: 0, y: 0 };
let wanted = { x: 0, y: 0 };
let running: Promise<void> | undefined;
const pump = async () => {
if (running) return running;
running = (async () => {
while (wanted.x !== applied.x || wanted.y !== applied.y) {
const dx = wanted.x - applied.x;
const dy = wanted.y - applied.y;
applied = { ...wanted };
await apply([{ op: 'translate', ids: targets, dx, dy }], key);
}
})();
try {
await running;
} finally {
running = undefined;
}
};
return {
/** Total page-space offset from the drag's start. */
to(dx: number, dy: number) {
wanted = { x: dx, y: dy };
fireAndForget(pump(), 'fig-editor');
},
async end(at?: Point) {
await pump();
await queue;
if (applied.x !== 0 || applied.y !== 0) {
const ops = at
? await resolveFrameDrop(engine, viewer.page(), targets, at)
: [];
ops.push({ op: 'reflow', ids: targets });
await apply(ops, key);
if (at) await viewer.selectIds(targets);
}
},
};
};
/**
* A move the canvas draws itself while the layers are dragged (a lifted
* move). In a shared design the document follows at gesture pace,
* quietly, so other people see the layers move; the drop applies the
* rest, all one undo step. `end` resolves to how far the document moved
* them.
*/
const startLiftedMove = (targets: string[]) => {
const key = `drag-${++dragKey}`;
let wanted = { x: 0, y: 0 };
let applied = { x: 0, y: 0 };
let moved = { x: 0, y: 0 };
let timer: ReturnType<typeof setTimeout> | undefined;
const step = async (last: boolean, at?: Point) => {
const dx = wanted.x - applied.x;
const dy = wanted.y - applied.y;
applied = { ...wanted };
const ops: Op[] =
dx !== 0 || dy !== 0 ? [{ op: 'translate', ids: targets, dx, dy }] : [];
if (last && (applied.x !== 0 || applied.y !== 0)) {
if (at)
ops.push(
...(await resolveFrameDrop(engine, viewer.page(), targets, at))
);
ops.push({ op: 'reflow', ids: targets });
}
const result = await apply(ops, key, !last);
if (result) moved = { x: moved.x + dx, y: moved.y + dy };
};
return {
to(dx: number, dy: number) {
wanted = { x: dx, y: dy };
if (!sharing || timer) return;
timer = setTimeout(() => {
timer = undefined;
fireAndForget(step(false), 'fig-editor');
}, GESTURE_PUSH_MS);
},
async end(at?: Point) {
clearTimeout(timer);
timer = undefined;
await queue;
await step(true, at);
if (at) await viewer.selectIds(targets);
return moved;
},
};
};
/** A resize drag on one layer: new page bounds → position and size. */
/**
* A resize drag on the selection: each layer scales with the selection's
* page bounds (`start`) as they become the dragged rectangle.
*/
const startResize = (ids: string[], start: Rect, known?: NodeInfo) => {
const key = `resize-${++dragKey}`;
const page = viewer.page();
const loadInfos = async (): Promise<NodeInfo[]> => {
if (known && ids.length === 1 && ids[0] === known.id) return [known];
try {
return await Promise.all(ids.map((id) => engine.nodeInfo(page, id)));
} catch (e) {
// Every step of the drag awaits this: rejecting would leave
// `running` set and the drag stuck.
Telemetry.error(e, { surface: 'fig-editor' });
options.notifyError(e instanceof Error ? e.message : String(e));
return [];
}
};
const infos = loadInfos();
let wanted: Rect | undefined;
let running = false;
const pump = async () => {
if (running) return;
running = true;
const items = await infos;
while (wanted) {
const r = wanted;
wanted = undefined;
const sx = start.w > 0 ? r.w / start.w : 1;
const sy = start.h > 0 ? r.h / start.h : 1;
const round = (v: number) => Math.round(v * 100) / 100;
await apply(
items.map((info) => {
const b = info.bounds;
const nx = r.x + (b.x - start.x) * sx;
const ny = r.y + (b.y - start.y) * sy;
const origin = resizedOrigin(info, b, {
x: nx,
y: ny,
w: b.w * sx,
h: b.h * sy,
});
return {
op: 'set' as const,
ids: [info.id],
props: {
x: round(origin.x),
y: round(origin.y),
width: Math.max(1, round(info.width * sx)),
height: Math.max(1, round(info.height * sy)),
},
};
}),
key
);
}
running = false;
};
return {
to(rect: Rect) {
wanted = rect;
fireAndForget(pump(), 'fig-editor');
},
async end() {
await pump();
await queue;
},
};
};
/** A rotation drag on one layer: degrees as the panel shows them. */
const startRotate = (id: string) => {
const key = `rotate-${++dragKey}`;
let wanted: number | undefined;
let running = false;
const pump = async () => {
if (running) return;
running = true;
while (wanted !== undefined) {
const rotation = wanted;
wanted = undefined;
await apply([{ op: 'set', ids: [id], props: { rotation } }], key);
}
running = false;
};
return {
to(degrees: number) {
wanted = degrees;
fireAndForget(pump(), 'fig-editor');
},
async end() {
await pump();
await queue;
},
};
};
// ---- images --------------------------------------------------------------
/**
* Places image files as rectangles filled with them (named after the
* files), centered on a page point, inside `parent`; selects them.
*/
const importImages = async (
files: File[],
at: { x: number; y: number },
parent: string
) => {
if (!enabled()) return;
const images = files.filter((f) => f.type.startsWith('image/'));
const ops: Op[] = [];
let offset = 0;
for (const file of images) {
try {
const { hash, width, height } = await engine.addImage(
await file.arrayBuffer()
);
// Large images come in at most 1000 units on their long side.
const k = Math.min(1, 1000 / Math.max(width, height));
const w = Math.max(1, Math.round(width * k));
const h = Math.max(1, Math.round(height * k));
ops.push({
op: 'create',
parent,
node: {
type: 'RECTANGLE',
name: file.name.replace(/\.[^.]+$/, '') || 'Image',
x: Math.round(at.x - w / 2 + offset),
y: Math.round(at.y - h / 2 + offset),
width: w,
height: h,
props: { fills: [{ image: hash }] },
},
});
offset += 20;
} catch (e) {
options.notifyError(
e instanceof Error ? e.message : `${file.name} could not be added`
);
}
}
const result = await apply(ops);
await selectCreated(result);
};
// ---- creation ------------------------------------------------------------
/**
* Creates a layer of `tool`'s kind over a page rectangle, inside the
* frame under its start when there is one (as Figma does), and selects
* it. Returns the new layer's id.
*/
const create = async (
tool: ShapeTool,
rect: Rect,
parent: string
): Promise<string | undefined> => {
const isText = tool === 'text';
const result = await apply([
{
op: 'create',
parent,
node: {
type: TYPE_FOR_TOOL[tool],
x: Math.round(rect.x),
y: Math.round(rect.y),
width: Math.max(1, Math.round(rect.w)),
height: Math.max(1, Math.round(rect.h)),
props: isText ? { characters: '', fontSize: 12 } : undefined,
},
},
]);
await selectCreated(result);
return result?.created[0];
};
/**
* Draws a line (or an arrow) between two page points, inside `parent`:
* a LINE as long as the drag, turned to its angle.
*/
const createLine = async (
from: { x: number; y: number },
to: { x: number; y: number },
arrow: boolean,
parent: string
): Promise<string | undefined> => {
const length = Math.max(1, Math.hypot(to.x - from.x, to.y - from.y));
const mid = { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
// Figma's degrees turn counter-clockwise; screen y points down.
const rotation =
Math.round(
((-Math.atan2(to.y - from.y, to.x - from.x) * 180) / Math.PI) * 100
) / 100;
const result = await apply([
{
op: 'create',
parent,
node: {
type: 'LINE',
name: arrow ? 'Arrow' : undefined,
x: mid.x - length / 2,
y: mid.y,
width: length,
height: 0,
props: {
rotation,
...(arrow ? { strokeCap: 'ARROW_LINES' as const } : {}),
},
},
},
]);
await selectCreated(result);
return result?.created[0];
};
return {
enabled,
createLine,
booleanOp,
flatten,
penPath,
penAdd,
penHandle,
penFinish,
pencilFinish,
vectorEdit,
editVector,
endVectorEdit,
selectVertex,
startVectorDrag,
setVectorNetwork,
canUndo,
canRedo,
saveState,
editingText,
setEditingText,
textSelection,
setTextSelection,
apply,
undo: () => history('undo'),
redo: () => history('redo'),
setProps,
toggleLocked,
deleteSelection,
duplicateSelection,
group,
ungroup,
arrange,
align,
distribute,
swapFillStroke,
nudge,
copy,
paste,
cut,
pasteHere,
pasteToReplace,
/** Whether layers copied in this file can be pasted. */
/** Layers were copied here, or may be on the readable clipboard. */
canPaste: () => clipboard.length > 0 || clipboardReadable,
flip,
addAutoLayout,
removeAutoLayout,
createComponent,
detachInstance,
insertInstance,
importLibrary,
viewCenter,
startMove,
startLiftedMove,
startResize,
startRotate,
create,
importImages,
saveNow,
/** The editable subset of the selection. */
editableIds,
isSelected: (id: string) => viewer.selected().some((s) => s.id === id),
selected: (): Selected[] => viewer.selected(),
};
}
export type FigEditor = ReturnType<typeof createFigEditor>;