@toghen/figma 0.0.0-stage → 0.1.0

package/main/components/run.ts

@@ -0,0 +1,273 @@
+/**
+ * Makes Figma agree with a component file: resolve, snapshot, diff, apply.
+ *
+ * `desired` is a component file already read, validated and expanded
+ * (`file.ts` does that, from the file's text). Everything the members name is
+ * addressed by name and resolved here, and a name that does not resolve stops the
+ * run before its first write: the plugin does not roll back, so the engine
+ * checks everything it can foresee first.
+ *
+ * Run one file at a time against a Figma file: two interleave.
+ */
+
+import { diff, diffArtboard, type Receipts } from '../../shared/components/diff.js';
+import type { Desired, Report, RunOptions, Step } from '../../shared/components/steps.js';
+import { applyCreateArtboard, applyCreateSet, shownDefault, type Applied, type AppliedArtboard } from './apply.js';
+import { noteTouched, pageOf } from './endOfRun.js';
+import { ComponentRunError } from './errors.js';
+import { expectedOf, type Wiring } from './receipt.js';
+import { plannedValueLines } from './fieldWriter.js';
+import { preferredOf, resolve, type Resolved } from './resolve.js';
+import { copiesFinder, keepsNoStamp, outermost } from './stamp.js';
+import { applyArtboardUpdate, applyUpdate, keepsChildren, type Updated, type UpdatedArtboard } from './update.js';
+import { takeArtboardSnapshot, takeSnapshot } from './snapshot.js';
+
+const refusal = (step: Step): step is Extract<Step, { kind: 'REFUSE_FOREIGN' }> => step.kind === 'REFUSE_FOREIGN';
+
+/** What writes a run's steps into another file than Figma's: the command line's FigCraft target (`cli/figcraftApply.ts`). */
+export interface ComponentWriter {
+  createSet(step: Extract<Step, { kind: 'CREATE_SET' }>, resolved: Resolved): Promise<Applied>;
+  update(setId: string, steps: Step[], desired: Desired, resolved: Resolved): Promise<Updated>;
+  createArtboard(step: Extract<Step, { kind: 'CREATE_ARTBOARD' }>, resolved: Resolved): Promise<AppliedArtboard>;
+  updateArtboard(frameId: string, steps: Step[], desired: Desired, resolved: Resolved): Promise<UpdatedArtboard>;
+  /** What the plan needs that this writer does not build, one line each: a run, a dry run included, stops on any. */
+  refuses(desired: Desired, steps: Step[], resolved: Resolved): string[];
+}
+
+let writer: ComponentWriter | undefined;
+
+/** Sends every run's steps to `next` instead of Figma's API; `undefined` puts Figma's back. */
+export function writeComponentsWith(next: ComponentWriter | undefined): void {
+  writer = next;
+}
+
+/** Stops the run, before it writes or reports a plan, when the writer cannot build what the plan needs. */
+function refuseUnbuilt(desired: Desired, steps: Step[], resolved: Resolved): void {
+  const lines = writer?.refuses(desired, steps, resolved) ?? [];
+  if (lines.length > 0) throw new ComponentRunError(`will not build "${desired.component.name}": nothing was written`, lines);
+}
+
+/**
+ * What Figma's own writer does not build: a preferred value by name. Figma takes preferred values by published key, and
+ * whether it takes a resolved component's key, a local one's included, waits for a measurement in the desktop app.
+ */
+function refusedInFigma(desired: Desired): string[] {
+  const lines: string[] = [];
+  for (const property of desired.component.properties) {
+    const named = preferredOf(property).find((value) => 'name' in value) as { loc?: { line: number } } | undefined;
+    if (named)
+      lines.push(
+        `"${desired.component.name}": the preferred values of "${property.name}" by name are not written in Figma until measured in the desktop app; name them by key${named.loc ? ` (line ${named.loc.line})` : ''}`,
+      );
+  }
+  return lines;
+}
+
+/** What a plan says about what it leaves alone, what it overwrites and what it breaks, for the report. */
+function describe(steps: Step[]): Pick<Report, 'notes' | 'breaking' | 'warnings'> {
+  const notes: string[] = [];
+  const breaking: string[] = [];
+  const warnings: string[] = [];
+  for (const step of steps) {
+    if (step.kind === 'LEAVE') notes.push(step.message);
+    if (step.kind === 'OVERWRITE') warnings.push(step.message);
+    if ('breaks' in step && step.breaks) breaking.push(step.breaks);
+  }
+  return { notes, breaking, warnings };
+}
+
+/**
+ * Each step that deletes a node names the person's copies of it, and of what is in it, whose stamps it strips once it
+ * runs; its own row says so (decisions, *A copy whose original Toghen removes*). A copy is named by the first step that
+ * removes what it copies, so a layer deleted inside another is said once.
+ */
+async function withStrips(steps: Step[]): Promise<void> {
+  let copiesOf: ReturnType<typeof copiesFinder> | undefined;
+  const named = new Set<string>();
+  for (const step of steps) {
+    if (step.kind !== 'DELETE_MEMBER' && step.kind !== 'DELETE_LAYER' && step.kind !== 'REPLACE_LAYER') continue;
+    const node = (await figma.getNodeByIdAsync(step.kind === 'DELETE_MEMBER' ? step.memberId : step.nodeId)) as SceneNode | null;
+    if (!node) continue;
+    copiesOf ??= copiesFinder();
+    const copies = copiesOf(node, step.kind !== 'REPLACE_LAYER' || !keepsChildren(step.layer, node)).filter((copy) => !named.has(copy.id));
+    if (copies.length === 0) continue;
+    for (const copy of copies) named.add(copy.id);
+    step.strip = copies.map((copy) => copy.id);
+    const said = keepsNoStamp(outermost(copies));
+    if (step.breaks) step.breaks = `${step.breaks}; ${said}`;
+    else if (step.kind === 'DELETE_LAYER') step.message = `removes "${step.address}"; ${said}`;
+  }
+}
+
+/** What the diff compares each layer's receipt with: the receipt the file's value would leave. */
+const receiptsOf = (resolved: Resolved, wiring: Wiring, options: RunOptions): Receipts => ({
+  expected: (layer) => expectedOf(layer, resolved, wiring),
+  component: (ref) => resolved.componentSource(ref),
+  preferred: (value) => {
+    const node = resolved.preferred(value);
+    return node ? { type: value.type, key: node.key } : value;
+  },
+  defaultComponent: (ref) => {
+    try {
+      return resolved.component(ref).id;
+    } catch (_missing) {
+      // A component the run cannot find is said by the write that needs it; here it only means the default is set again.
+      return undefined;
+    }
+  },
+  ...(options.overwriteDrift ? { overwriteDrift: true } : {}),
+});
+
+/** Tells the end of the run which page a set or an artboard is on, the run's page for one yet to be made. */
+async function noteSet(existingId: string | undefined, page: PageNode): Promise<void> {
+  const node = existingId === undefined ? null : await figma.getNodeByIdAsync(existingId);
+  noteTouched(node ? pageOf(node) : page);
+}
+
+export async function run(desired: Desired, options: RunOptions = {}): Promise<Report> {
+  // A real run builds against what is in the file. A name only a plan said would exist would be a binding to nothing.
+  if (options.pending && !options.dryRun) {
+    throw new ComponentRunError(`will not build "${desired.component.name}": nothing was written`, [
+      'pending names are for a dry run: a real run resolves against what the file holds, and the steps before it have made those names',
+    ]);
+  }
+  if (!writer) {
+    const refused = refusedInFigma(desired);
+    if (refused.length > 0) throw new ComponentRunError(`will not build "${desired.component.name}": nothing was written`, refused);
+  }
+  // Under dynamic-page access a page's contents are not there until it is loaded, and the snapshot reads every page.
+  // Page by page, not loadAllPagesAsync(): a measured choice, and it loads only what the snapshot reads.
+  // The searches then run page by page too (findInEveryPage): the plugin may not search the document itself.
+  for (const page of figma.root.children) await page.loadAsync();
+
+  const resolved = await resolve(desired, options);
+  if (desired.artboard) return runArtboard(desired, resolved, options);
+  const snapshot = await takeSnapshot(desired.component.name);
+  const wiring: Wiring = {
+    keys: new Map((snapshot.set?.definitions ?? []).map((definition) => [definition.name, definition.key])),
+    defaults: new Map(),
+  };
+  for (const property of desired.component.properties) {
+    if (property.type !== 'BOOLEAN' && property.type !== 'TEXT') continue;
+    try {
+      wiring.defaults.set(property.name, shownDefault(resolved, property));
+    } catch (_pending) {
+      // A default's variable a dry run only expects: a field wired to it reads as moved, and is written.
+    }
+  }
+  const steps = diff(desired.members, desired.component, snapshot, receiptsOf(resolved, wiring, options));
+  await withStrips(steps);
+  refuseUnbuilt(desired, steps, resolved);
+  const report: Report = {
+    dryRun: !!options.dryRun,
+    steps,
+    created: [],
+    updated: [],
+    deleted: [],
+    pending: resolved.pending,
+    ...describe(steps),
+  };
+  report.notes.push(...resolved.notes);
+
+  if (options.dryRun) {
+    // What the run would write as a value is said before it runs (R10).
+    report.warnings.push(...plannedValueLines(desired.component.name, resolved, steps));
+    await noteSet(snapshot.set?.id, resolved.page);
+    return report;
+  }
+
+  const refused = steps.filter(refusal);
+  if (refused.length > 0) {
+    throw new ComponentRunError(
+      `will not build "${desired.component.name}": nothing was written`,
+      refused.map((step) => step.message),
+    );
+  }
+
+  // Breaking steps are advisory in a dry run and a gate in a real one: only someone who read them and said so takes them.
+  if (report.breaking.length > 0 && !options.allowBreaking) {
+    throw new ComponentRunError(
+      `will not change "${desired.component.name}": ${report.breaking.length} step${report.breaking.length === 1 ? '' : 's'} would break instances, and nothing was written; pass allowBreaking to take ${report.breaking.length === 1 ? 'it' : 'them'}`,
+      report.breaking,
+    );
+  }
+
+  const create = steps.find((step): step is Extract<Step, { kind: 'CREATE_SET' }> => step.kind === 'CREATE_SET');
+  if (create) {
+    const applied = await (writer ? writer.createSet(create, resolved) : applyCreateSet(create, resolved));
+    report.setId = applied.setId;
+    noteTouched(resolved.page, applied.setId);
+    report.created.push(...applied.created);
+    report.warnings.push(...applied.warnings);
+  } else if (snapshot.set) {
+    const applied = await (writer
+      ? writer.update(snapshot.set.id, steps, desired, resolved)
+      : applyUpdate(snapshot.set.id, steps, desired, resolved));
+    report.setId = snapshot.set.id;
+    await noteSet(snapshot.set.id, resolved.page);
+    report.created.push(...applied.created);
+    report.updated.push(...applied.updated);
+    report.deleted.push(...applied.deleted);
+    report.warnings.push(...applied.warnings);
+  }
+  return report;
+}
+
+/**
+ * An artboard: snapshot its frame by stamp, plan the difference, and apply it.
+ *
+ * The gate is the set's: a layer the file stopped producing is removed, which is a breaking step, so a real run
+ * that has one stops before its first write unless it was told to take it. A layer without our stamp is never touched.
+ */
+async function runArtboard(desired: Desired, resolved: Resolved, options: RunOptions): Promise<Report> {
+  const [member] = desired.members;
+  const snapshot = await takeArtboardSnapshot(member.name);
+  const steps = diffArtboard(member, snapshot, receiptsOf(resolved, { keys: new Map(), defaults: new Map() }, options));
+  await withStrips(steps);
+  refuseUnbuilt(desired, steps, resolved);
+  const report: Report = {
+    artboard: true,
+    dryRun: !!options.dryRun,
+    steps,
+    created: [],
+    updated: [],
+    deleted: [],
+    pending: resolved.pending,
+    ...describe(steps),
+  };
+  report.notes.push(...resolved.notes);
+  if (options.dryRun) {
+    report.warnings.push(...plannedValueLines(member.name, resolved, steps));
+    await noteSet(snapshot.artboard?.id, resolved.page);
+    return report;
+  }
+
+  if (report.breaking.length > 0 && !options.allowBreaking) {
+    throw new ComponentRunError(
+      `will not change "${member.name}": ${report.breaking.length} step${report.breaking.length === 1 ? '' : 's'} would remove layers, and nothing was written; pass allowBreaking to take ${report.breaking.length === 1 ? 'it' : 'them'}`,
+      report.breaking,
+    );
+  }
+
+  const create = steps.find((step): step is Extract<Step, { kind: 'CREATE_ARTBOARD' }> => step.kind === 'CREATE_ARTBOARD');
+  if (create) {
+    const applied = await (writer ? writer.createArtboard(create, resolved) : applyCreateArtboard(create, resolved));
+    report.setId = applied.frameId;
+    noteTouched(resolved.page, applied.frameId);
+    report.created.push(...applied.created);
+    report.warnings.push(...applied.warnings);
+  } else if (snapshot.artboard) {
+    report.setId = snapshot.artboard.id;
+    // A run with nothing to change does not even switch pages.
+    if (!steps.some((step) => step.kind !== 'LEAVE' && step.kind !== 'OVERWRITE')) return report;
+    const applied = await (writer
+      ? writer.updateArtboard(snapshot.artboard.id, steps, desired, resolved)
+      : applyArtboardUpdate(snapshot.artboard.id, steps, desired, resolved));
+    await noteSet(snapshot.artboard.id, resolved.page);
+    report.created.push(...applied.created);
+    report.updated.push(...applied.updated);
+    report.deleted.push(...applied.deleted);
+    report.warnings.push(...applied.warnings);
+  }
+  return report;
+}

package/main/components/snapshot.ts

@@ -0,0 +1,341 @@
+/**
+ * What is in the file that is ours, as plain data.
+ *
+ * Finds a component's set, its members and their layers by stamp, wherever a
+ * designer moved them, and reports what it found that is *not* ours: a set of the
+ * same name that Toghen did not make, nodes inside a set that carry no stamp, and
+ * the copies a person made of Toghen's nodes, which carry their stamps.
+ * The diff is taken from this, and it never sees a Figma node.
+ *
+ * Must run after every page is loaded (`page.loadAsync()`): under dynamic-page
+ * access a page's contents are not there until it is loaded.
+ */
+
+import { findInEveryPage } from '../utils/pageRoots.js';
+import { parseCombination, slotKey } from '../../shared/components/diff.js';
+import type {
+  ArtboardSnapshot,
+  LayerSnapshot,
+  MemberSnapshot,
+  PropertySnapshot,
+  Snapshot,
+  SetSnapshot,
+} from '../../shared/components/diff.js';
+import type { LayerKind, SlotSettings as SlotModelSettings } from '../../shared/components/model.js';
+import { slotNodesOf } from './apply.js';
+import { ComponentRunError } from './errors.js';
+import { receiptOf, sortNodes, stampedAs, stampOn, type Sorted, type Stamp } from './stamp.js';
+import { reportedOf } from './receipt.js';
+import { loadLock } from '../utils/lockStore.js';
+
+const LAYER_TYPES: Record<string, LayerKind> = { FRAME: 'FRAME', SLOT: 'SLOT', TEXT: 'TEXT', INSTANCE: 'INSTANCE', LINE: 'LINE' };
+
+/**
+ * A stamped layer's receipt, and the hash of what Figma reports now for each field with a hash in it. An instance's
+ * component is always read, and said as `main`: the diff tells a swap from a receipt to take again by it (`SWAP_COMPONENT`).
+ */
+async function receiptAndReported(
+  node: SceneNode,
+  receipt: Record<string, string>,
+  libraryOf: () => Map<string, string>,
+): Promise<Pick<LayerSnapshot, 'receipt' | 'reported' | 'main'>> {
+  const fields = Object.keys(receipt).filter((field) => receipt[field] !== '');
+  if (node.type !== 'INSTANCE') return { receipt, reported: receiptOf(await reportedOf(node, fields)) };
+  const reported = receiptOf(await reportedOf(node, fields.includes('component') ? fields : [...fields, 'component']));
+  const component = await node.getMainComponentAsync();
+  const shown = component?.parent?.type === 'COMPONENT_SET' ? component.parent : component;
+  if (!shown) return { receipt, reported };
+  return {
+    receipt,
+    reported,
+    main: { name: shown.name, key: shown.key, ...(shown.remote ? { library: libraryOf().get(shown.key) ?? '' } : {}) },
+  };
+}
+
+/** The library the lock holds each component key under, read once a snapshot meets a library's component. */
+function librariesByKey(): () => Map<string, string> {
+  let byKey: Map<string, string> | undefined;
+  return () => {
+    if (byKey) return byKey;
+    byKey = new Map();
+    for (const [library, entry] of Object.entries(loadLock().libraries))
+      for (const { key } of Object.values(entry.components)) byKey.set(key, library);
+    return byKey;
+  };
+}
+
+/** A node of a member or an artboard's frame, as the walk found it. */
+export interface TreeNode {
+  node: SceneNode;
+  index: number;
+  /** The key of the layer it sits in: an address, or for a layer in an instance's slot, `slotKey` of the instance and the slot. */
+  parent?: string;
+  /** Set on a layer Toghen stamped, of a kind it makes. */
+  stamp?: Stamp;
+  address?: string;
+  kind?: LayerKind;
+  /** Toghen's layer, moved: its stamp names another id (`sortOut`). */
+  moved?: true;
+  /** A person's copy of a layer Toghen made: the original. */
+  copyOf?: SceneNode;
+}
+
+/**
+ * The nodes of a member, or an artboard's frame, the root first: each stamped layer by the address in its stamp, sorted
+ * into Toghen's and a person's copies (`sortNodes`), and the nodes that carry no stamp. The walk goes into a stamped
+ * layer only: an unstamped node's contents are its own business, and an instance's children belong to its component;
+ * in an artboard the layers in an instance's slots are walked, under the slot's key. What is inside a copy is left out
+ * with it. The snapshot and the update both read a tree through this, so they agree on which node is which layer.
+ */
+export async function stampedTree(root: SceneNode & ChildrenMixin, slots: boolean): Promise<TreeNode[]> {
+  const found: Array<TreeNode & { up?: TreeNode }> = [];
+  const add = (
+    node: SceneNode,
+    index: number,
+    parent: string | undefined,
+    up: TreeNode | undefined,
+    kind: LayerKind | undefined,
+  ): TreeNode => {
+    const stamp = stampOn(node);
+    const address = stamp?.is.address;
+    const entry = {
+      node,
+      index,
+      ...(parent !== undefined ? { parent } : {}),
+      up,
+      ...(stamp && address !== undefined && kind ? { stamp, address, kind } : {}),
+    };
+    found.push(entry);
+    return entry;
+  };
+  const walk = (node: BaseNode & ChildrenMixin, parent: string | undefined, up: TreeNode): void => {
+    for (const [index, child] of (node.children as readonly SceneNode[]).entries()) {
+      const entry = add(child, index, parent, up, LAYER_TYPES[child.type]);
+      if (entry.address === undefined) continue;
+      if (child.type === 'INSTANCE') {
+        if (slots) for (const slot of slotNodesOf(child)) walk(slot, slotKey(entry.address, slot.name), entry);
+      } else if ('children' in child) {
+        walk(child, entry.address, entry);
+      }
+    }
+  };
+  const top = add(root, 0, undefined, undefined, 'FRAME');
+  walk(root, top.address, top);
+
+  const sorted = await sortNodes(found.filter((entry) => entry.address !== undefined).map((entry) => entry.node));
+  const copyOf = new Map(sorted.copies.map(({ copy, of }) => [copy, of]));
+  const underCopy = (entry: TreeNode & { up?: TreeNode }): boolean => {
+    for (let up = entry.up as (TreeNode & { up?: TreeNode }) | undefined; up; up = up.up) if (copyOf.has(up.node)) return true;
+    return false;
+  };
+  return found
+    .filter((entry) => !underCopy(entry))
+    .map(({ up: _up, ...entry }) => ({
+      ...entry,
+      ...(sorted.moved.has(entry.node) ? { moved: true as const } : {}),
+      ...(copyOf.has(entry.node) ? { copyOf: copyOf.get(entry.node) } : {}),
+    }));
+}
+
+/**
+ * A member, or an artboard's frame, as plain data: its layers by the address in their stamps, with their receipts, the
+ * copies a person made of them, and the nodes in it that carry no stamp. The root is the node itself: one node is the
+ * member (or the artboard) and a layer.
+ */
+async function snapshotTree(root: ComponentNode | FrameNode, name: string, slots: boolean): Promise<MemberSnapshot> {
+  const layers: LayerSnapshot[] = [];
+  const unstamped: MemberSnapshot['unstamped'] = [];
+  const copies: NonNullable<MemberSnapshot['copies']> = [];
+  const libraryOf = librariesByKey();
+  for (const entry of await stampedTree(root, slots)) {
+    const { node } = entry;
+    const parent = entry.parent !== undefined ? { parent: entry.parent } : {};
+    if (!entry.stamp || entry.address === undefined || !entry.kind) {
+      // Not ours: reported, and left alone. What is inside it is its own business.
+      if (node !== root) unstamped.push({ id: node.id, name: node.name, ...parent });
+    } else if (entry.copyOf) {
+      copies.push({ id: node.id, name: node.name, address: entry.address });
+    } else {
+      layers.push({
+        id: node.id,
+        name: node.name,
+        address: entry.address,
+        kind: entry.kind,
+        index: entry.index,
+        ...(await receiptAndReported(node, entry.stamp.receipt, libraryOf)),
+        ...parent,
+        ...(entry.moved ? { moved: true } : {}),
+      });
+    }
+  }
+  return { id: root.id, name, layers, unstamped, ...(copies.length > 0 ? { copies } : {}) };
+}
+
+/** Figma reports an unset limit as null; the file leaves it out. */
+function withoutNulls(settings: SlotSettings): SlotModelSettings {
+  const out: SlotModelSettings = {};
+  for (const [key, value] of Object.entries(settings))
+    if (value !== null && value !== undefined) (out as Record<string, unknown>)[key] = value;
+  return out;
+}
+
+/**
+ * What is wrong with a set Figma reports as broken, from its children's names and stamps, which stay readable when the
+ * set's own properties do not: members with other axes than most, a combination two members share, a name that does not
+ * read as `Axis=value, …`. Each is said to be ours or made by hand.
+ */
+function describeBroken(set: ComponentSetNode, componentName: string): string[] {
+  const children = set.children.filter((child): child is ComponentNode => child.type === 'COMPONENT');
+  const who = (child: ComponentNode): string => (stampOn(child)?.is.member !== undefined ? 'ours' : 'made by hand');
+  const lines = [`cannot build "${componentName}": Figma reports its set (${set.id}) as broken, and nothing was written`];
+
+  const axesOf = new Map<ComponentNode, string>();
+  const byName = new Map<string, ComponentNode[]>();
+  for (const child of children) {
+    const pairs = parseCombination(child.name);
+    if (!pairs) {
+      lines.push(`member "${child.name}" (${child.id}, ${who(child)}) does not read as Axis=value, …`);
+      continue;
+    }
+    axesOf.set(child, pairs.map(([axis]) => axis).join(', '));
+    byName.set(child.name, [...(byName.get(child.name) ?? []), child]);
+  }
+  // The axes most members have; on a tie, the first met.
+  const counts = new Map<string, number>();
+  for (const axes of axesOf.values()) counts.set(axes, (counts.get(axes) ?? 0) + 1);
+  const usual = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+  for (const [child, axes] of axesOf) {
+    if (usual && axes !== usual[0])
+      lines.push(`member "${child.name}" (${child.id}, ${who(child)}) has the axes ${axes}; the other ${usual[1]} have ${usual[0]}`);
+  }
+  for (const [name, same] of byName) {
+    if (same.length > 1)
+      lines.push(
+        `"${name}" is the name of ${same.length === 2 ? 'two' : same.length} members (${same.map((child) => `${child.id}, ${who(child)}`).join('; ')})`,
+      );
+  }
+  lines.push('delete or rename the members named, then run again');
+  return lines;
+}
+
+/** Figma's own message for a set it calls broken, the one every read of its properties then throws. */
+const isBroken = (error: unknown): boolean => error instanceof Error && /Component set .*has existing errors/.test(error.message);
+
+/** The lines that name what is wrong with the component's stamped set, when Figma reports it broken. Reads it, and nothing else. */
+export function brokenSetLines(set: ComponentSetNode, componentName: string): string[] | undefined {
+  try {
+    void set.componentPropertyDefinitions;
+    return undefined;
+  } catch (error) {
+    if (!isBroken(error)) throw error;
+    return describeBroken(set, componentName);
+  }
+}
+
+/** The members of a set, Toghen's and a person's copies (`sortNodes`): its components stamped as members. */
+export const membersOf = (set: ComponentSetNode): Promise<Sorted<ComponentNode>> =>
+  sortNodes(set.children.filter((child): child is ComponentNode => child.type === 'COMPONENT' && stampOn(child)?.is.member !== undefined));
+
+async function snapshotSet(set: ComponentSetNode, componentName: string): Promise<SetSnapshot> {
+  const broken = brokenSetLines(set, componentName);
+  if (broken) throw new ComponentRunError(broken[0], broken.slice(1));
+  const members: MemberSnapshot[] = [];
+  const unstamped: SetSnapshot['unstamped'] = [];
+  const copies: NonNullable<SetSnapshot['copies']> = [];
+  const sorted = await membersOf(set);
+  const copyOf = new Map<SceneNode, ComponentNode>(sorted.copies.map(({ copy, of }) => [copy, of]));
+  for (const child of set.children) {
+    const of = copyOf.get(child);
+    if (of) copies.push({ id: child.id, name: child.name, of: stampOn(of)?.is.member ?? of.name });
+    else if (sorted.ours.includes(child as ComponentNode))
+      members.push(await snapshotTree(child as ComponentNode, stampOn(child)?.is.member as string, false));
+    else unstamped.push({ id: child.id, name: child.name });
+  }
+  // The set's properties, ours and not. A `VARIANT` axis is derived from the members' names and is not one to edit.
+  const definitions: PropertySnapshot[] = Object.entries(set.componentPropertyDefinitions)
+    .filter(([, definition]) => definition.type !== 'VARIANT')
+    .map(([key, definition]) => ({
+      key,
+      name: key.split('#')[0],
+      type: definition.type as PropertySnapshot['type'],
+      defaultValue: definition.defaultValue,
+      ...(definition.description !== undefined ? { description: definition.description } : {}),
+      ...(definition.preferredValues ? { preferredValues: definition.preferredValues } : {}),
+      ...(definition.slotSettings ? { slotSettings: withoutNulls(definition.slotSettings) } : {}),
+    }));
+  return {
+    id: set.id,
+    definitions,
+    properties: Object.keys(stampOn(set)?.receipt ?? {}),
+    members,
+    unstamped,
+    ...(copies.length > 0 ? { copies } : {}),
+  };
+}
+
+/** The sets stamped as this component, Toghen's and a person's copies (`sortNodes`). */
+const stampedSets = (componentName: string): Promise<Sorted<ComponentSetNode>> =>
+  sortNodes(
+    findInEveryPage({ types: ['COMPONENT_SET'], sharedPluginData: stampedAs('component') }).filter(
+      (set): set is ComponentSetNode => stampOn(set)?.is.component === componentName,
+    ),
+  );
+
+/** The lines naming what is wrong with each of these components' stamped sets that Figma reports as broken, for the check that runs before a sync writes anything. A copy is not Toghen's to check. */
+export async function brokenSetProblems(componentNames: string[]): Promise<string[]> {
+  // The same page-by-page loading a run does before it reads the file.
+  if (componentNames.length > 0) for (const page of figma.root.children) await page.loadAsync();
+  const lines: string[] = [];
+  for (const name of componentNames) for (const set of (await stampedSets(name)).ours) lines.push(...(brokenSetLines(set, name) ?? []));
+  return lines;
+}
+
+/**
+ * Finds the set Toghen built for `componentName`, the copies a person made of it, and any set that merely has its name.
+ *
+ * A copy carries the set's stamp, and its id says it is a copy (`sortNodes`). Two sets whose stamps are both their own
+ * (stamped before the stamp recorded an id) cannot be told apart by anything but a guess, so that stops the run rather
+ * than being resolved by picking one.
+ */
+export async function takeSnapshot(componentName: string): Promise<Snapshot> {
+  const { ours, copies } = await stampedSets(componentName);
+
+  if (ours.length > 1) {
+    throw new ComponentRunError(`cannot build "${componentName}": more than one set is stamped as it`, [
+      `${ours.map((set) => set.id).join(', ')} all claim to be "${componentName}"; delete or unstamp all but one`,
+    ]);
+  }
+
+  const foreign = findInEveryPage({ types: ['COMPONENT_SET'] })
+    .filter((set) => set.name === componentName && stampOn(set)?.is.component === undefined)
+    .map((set) => ({ id: set.id, name: set.name }));
+
+  return {
+    ...(ours.length === 1 ? { set: await snapshotSet(ours[0], componentName) } : {}),
+    foreign,
+    ...(copies.length > 0 ? { copies: copies.map(({ copy }) => ({ id: copy.id, name: copy.name })) } : {}),
+  };
+}
+
+/**
+ * Finds the frame Toghen built for the artboard `name`, wherever a person moved it, and the copies a person made of it.
+ *
+ * A frame that merely has the artboard's name is not looked at: nothing is adopted by name. Two frames whose stamps
+ * are both their own cannot be told apart, so that stops the run.
+ */
+export async function takeArtboardSnapshot(name: string): Promise<ArtboardSnapshot> {
+  const { ours, copies } = await sortNodes(
+    findInEveryPage({ types: ['FRAME'], sharedPluginData: stampedAs('artboard') }).filter(
+      (frame): frame is FrameNode => stampOn(frame)?.is.artboard === name,
+    ),
+  );
+  if (ours.length > 1) {
+    throw new ComponentRunError(`cannot build "${name}": more than one frame is stamped as it`, [
+      `${ours.map((frame) => frame.id).join(', ')} all claim to be the artboard "${name}"; delete or unstamp all but one`,
+    ]);
+  }
+  return {
+    ...(ours.length === 1 ? { artboard: await snapshotTree(ours[0], name, true) } : {}),
+    ...(copies.length > 0 ? { copies: copies.map(({ copy }) => ({ id: copy.id, name: copy.name })) } : {}),
+  };
+}