@toghen/figma 0.0.0-stage → 0.1.1

package/main/handlers/cancelOperation.ts

@@ -0,0 +1,18 @@
+import { getState, setState } from '../runtimeState.js';
+
+/**
+ * Stops the run in progress, and leaves the plan alone.
+ *
+ * Clearing `lastPlan` here raced the handler still executing it: by the time the
+ * run reported what it had managed to apply, the plan describing the rest was
+ * already gone. Plan lifecycle belongs to the execute handler, which clears it
+ * when the run finishes.
+ *
+ * Nothing needs to be rewound. A mode is recorded only once its value has
+ * actually landed, so re-planning *is* the resume — the next plan contains
+ * exactly what this run did not finish.
+ */
+export async function CANCEL_OPERATION(): Promise<void> {
+  getState().activeOperation?.abort();
+  setState({ activeOperation: null });
+}

package/main/handlers/executeApplyBindings.ts

@@ -0,0 +1,69 @@
+import type { PlanType, Response } from '../../shared/protocol.js';
+import { runOperations } from '../engines/batchRunner.js';
+import { getState, setState } from '../runtimeState.js';
+import { SimpleAbortController } from '../utils/abortController.js';
+
+function postToUi(message: Response): void {
+  figma.ui.postMessage(message);
+}
+
+/** Runs the last plan, when it is one of `planType`: the conventions' bindings, or Apply's tokens. */
+async function executePlan(planType: PlanType, commandType: string, missing: string): Promise<void> {
+  const state = getState();
+  if (!state.lastPlan || state.lastPlanType !== planType) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: missing,
+        code: 'NO_PLAN',
+        commandType,
+      },
+    });
+    return;
+  }
+
+  const controller = new SimpleAbortController();
+  setState({ activeOperation: controller });
+
+  try {
+    const summary = await runOperations(state.lastPlan, {
+      signal: controller.signal,
+      onProgress: (completed, total, currentLabel) => {
+        postToUi({
+          type: 'OPERATION_PROGRESS',
+          payload: { completed, total, currentLabel },
+        });
+      },
+    });
+
+    setState({
+      activeOperation: null,
+      lastPlan: null,
+      lastPlanType: null,
+    });
+
+    postToUi({
+      type: 'OPERATION_COMPLETE',
+      payload: summary,
+    });
+  } catch (error) {
+    setState({ activeOperation: null });
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: error instanceof Error ? error.message : String(error),
+        code: 'FIGMA_API_ERROR',
+        commandType,
+      },
+    });
+  }
+}
+
+export function EXECUTE_APPLY_BINDINGS(): Promise<void> {
+  return executePlan('apply_bindings', 'EXECUTE_APPLY_BINDINGS', 'Create an apply-bindings plan before executing.');
+}
+
+/** Apply's execution: every `APPLY_TOKEN` written through the field writer. No stamp is written. */
+export function EXECUTE_APPLY(): Promise<void> {
+  return executePlan('apply', 'EXECUTE_APPLY', 'Create an apply plan before executing.');
+}

package/main/handlers/executeScaffold.ts

@@ -0,0 +1,59 @@
+import type { Response } from '../../shared/protocol.js';
+import { runOperations } from '../engines/batchRunner.js';
+import { getState, setState } from '../runtimeState.js';
+import { SimpleAbortController } from '../utils/abortController.js';
+
+function postToUi(message: Response): void {
+  figma.ui.postMessage(message);
+}
+
+export async function EXECUTE_SCAFFOLD(): Promise<void> {
+  const state = getState();
+  if (!state.lastPlan || state.lastPlanType !== 'scaffold') {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Create a scaffold plan before executing.',
+        code: 'NO_PLAN',
+        commandType: 'EXECUTE_SCAFFOLD',
+      },
+    });
+    return;
+  }
+
+  const controller = new SimpleAbortController();
+  setState({ activeOperation: controller });
+
+  try {
+    const summary = await runOperations(state.lastPlan, {
+      signal: controller.signal,
+      onProgress: (completed, total, currentLabel) => {
+        postToUi({
+          type: 'OPERATION_PROGRESS',
+          payload: { completed, total, currentLabel },
+        });
+      },
+    });
+
+    setState({
+      activeOperation: null,
+      lastPlan: null,
+      lastPlanType: null,
+    });
+
+    postToUi({
+      type: 'OPERATION_COMPLETE',
+      payload: summary,
+    });
+  } catch (error) {
+    setState({ activeOperation: null });
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: error instanceof Error ? error.message : String(error),
+        code: 'FIGMA_API_ERROR',
+        commandType: 'EXECUTE_SCAFFOLD',
+      },
+    });
+  }
+}

package/main/handlers/executeStyleSync.ts

@@ -0,0 +1,121 @@
+import type { Operation } from '../../shared/operations.js';
+import type { Response } from '../../shared/protocol.js';
+import { runOperations } from '../engines/batchRunner.js';
+import { getState, setState } from '../runtimeState.js';
+import { buildSyncStatePayload } from '../utils/syncState.js';
+import { SimpleAbortController } from '../utils/abortController.js';
+
+function postToUi(message: Response): void {
+  figma.ui.postMessage(message);
+}
+
+/**
+ * Loads the fonts the plan's text styles name. A font that was listed and
+ * cannot be loaded costs its styles, not the run: each becomes a skip, as a
+ * style with no family to load is skipped at plan time.
+ */
+async function preloadFontsForPlan(ops: readonly Operation[]): Promise<Operation[]> {
+  const fontOf = (op: Operation): FontName | null => {
+    if (op.kind !== 'CREATE_STYLE' && op.kind !== 'UPDATE_STYLE') return null;
+    const props = op.props as Record<string, unknown>;
+    if (typeof props.fontFamily !== 'string' || !props.fontFamily) return null;
+    return { family: props.fontFamily, style: typeof props.fontStyle === 'string' ? props.fontStyle : 'Regular' };
+  };
+
+  const refs = [
+    ...new Set(
+      ops
+        .map(fontOf)
+        .filter((font) => font !== null)
+        .map((font) => JSON.stringify(font)),
+    ),
+  ];
+  const failed = new Set<string>();
+  await Promise.all(refs.map((ref) => figma.loadFontAsync(JSON.parse(ref) as FontName).catch(() => void failed.add(ref))));
+
+  return ops.map((op) => {
+    const font = fontOf(op);
+    if (!font || !failed.has(JSON.stringify(font)) || (op.kind !== 'CREATE_STYLE' && op.kind !== 'UPDATE_STYLE')) return op;
+    return {
+      kind: 'SKIP',
+      reason: `"${op.tokenPath}" has no family Figma can load: "${font.family}" is listed but could not be loaded.`,
+      path: op.tokenPath,
+      cause: 'font-not-loaded',
+      reported: true,
+    };
+  });
+}
+
+export async function EXECUTE_STYLE_SYNC(): Promise<void> {
+  const state = getState();
+
+  if (!state.resolver) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Load a resolver document before executing style sync.',
+        code: 'NO_RESOLVER',
+        commandType: 'EXECUTE_STYLE_SYNC',
+      },
+    });
+    return;
+  }
+
+  if (!state.lastPlan || state.lastPlanType !== 'style_sync') {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Create a style sync plan before executing.',
+        code: 'NO_PLAN',
+        commandType: 'EXECUTE_STYLE_SYNC',
+      },
+    });
+    return;
+  }
+
+  const controller = new SimpleAbortController();
+  setState({ activeOperation: controller });
+
+  try {
+    const plan = await preloadFontsForPlan(state.lastPlan);
+
+    const summary = await runOperations(plan, {
+      signal: controller.signal,
+      onProgress: (completed, total, currentLabel) => {
+        postToUi({
+          type: 'OPERATION_PROGRESS',
+          payload: { completed, total, currentLabel },
+        });
+      },
+    });
+
+    // What the run applied is already stamped on each style it wrote, from what Figma reported back.
+    setState({
+      activeOperation: null,
+      lastPlan: null,
+      lastPlanType: null,
+    });
+
+    postToUi({
+      type: 'OPERATION_COMPLETE',
+      payload: summary,
+    });
+
+    // The stamps just moved. A run that changes them and leaves the header
+    // reading the old numbers is the defect this reporting exists to close.
+    postToUi({
+      type: 'SYNC_STATE',
+      payload: await buildSyncStatePayload(state.resolver, state.conversionMap),
+    });
+  } catch (error) {
+    setState({ activeOperation: null });
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: error instanceof Error ? error.message : String(error),
+        code: 'FIGMA_API_ERROR',
+        commandType: 'EXECUTE_STYLE_SYNC',
+      },
+    });
+  }
+}

package/main/handlers/executeVariableSync.ts

@@ -0,0 +1,82 @@
+import { SimpleAbortController } from '../utils/abortController.js';
+import type { Response } from '../../shared/protocol.js';
+import { runOperations } from '../engines/batchRunner.js';
+import { getState, setState } from '../runtimeState.js';
+import { buildSyncStatePayload } from '../utils/syncState.js';
+
+function postToUi(message: Response): void {
+  figma.ui.postMessage(message);
+}
+
+export async function EXECUTE_VARIABLE_SYNC(): Promise<void> {
+  const state = getState();
+
+  if (!state.resolver) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Load a resolver document before executing sync.',
+        code: 'NO_RESOLVER',
+        commandType: 'EXECUTE_VARIABLE_SYNC',
+      },
+    });
+    return;
+  }
+
+  if (!state.lastPlan || state.lastPlanType !== 'variable_sync') {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Create a variable sync plan before executing.',
+        code: 'NO_PLAN',
+        commandType: 'EXECUTE_VARIABLE_SYNC',
+      },
+    });
+    return;
+  }
+
+  const controller = new SimpleAbortController();
+  setState({ activeOperation: controller });
+
+  try {
+    const summary = await runOperations(state.lastPlan, {
+      signal: controller.signal,
+      onProgress: (completed, total, currentLabel) => {
+        postToUi({
+          type: 'OPERATION_PROGRESS',
+          payload: { completed, total, currentLabel },
+        });
+      },
+    });
+
+    // What the run applied is already stamped on each variable it wrote, from what Figma reported back, so a run
+    // that stopped halfway resumes: the next plan holds exactly the modes that did not land.
+    setState({
+      activeOperation: null,
+      lastPlan: null,
+      lastPlanType: null,
+    });
+
+    postToUi({
+      type: 'OPERATION_COMPLETE',
+      payload: summary,
+    });
+
+    // The stamps just moved. A run that changes them and leaves the header
+    // reading the old numbers is the defect this reporting exists to close.
+    postToUi({
+      type: 'SYNC_STATE',
+      payload: await buildSyncStatePayload(state.resolver, state.conversionMap),
+    });
+  } catch (error) {
+    setState({ activeOperation: null });
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: error instanceof Error ? error.message : String(error),
+        code: 'FIGMA_API_ERROR',
+        commandType: 'EXECUTE_VARIABLE_SYNC',
+      },
+    });
+  }
+}

package/main/handlers/exportDocument.ts

@@ -0,0 +1,114 @@
+import type { ResolverInput } from '@toghen/lib';
+import type { Command, Response } from '../../shared/protocol.js';
+import { exportToJSON } from '../engines/ioAdapter.js';
+import type { Stamp } from '../components/stamp.js';
+import { getState } from '../runtimeState.js';
+import { indexFigmaCollections } from '../utils/figmaCollectionIndex.js';
+import { flatMap } from '../utils/lists.js';
+import { localStyles } from '../utils/tokenStamps.js';
+
+type ExportDocumentCommand = Extract<Command, { type: 'EXPORT_DOCUMENT' }>;
+
+/**
+ * Writes the resolved tokens out as DTCG JSON, for one combination of contexts.
+ *
+ * Figma styles and this format are both single-mode, so a document with several
+ * contexts cannot round-trip through here. The combination is chosen
+ * deliberately: one context per modifier, each defaulting to the modifier's
+ * default and shown on the screen before the command runs. It is resolved on its
+ * own (`resolver.resolveToDesignSystem(input)`), never as part of the product of
+ * every combination, which a large document cannot finish. The combination
+ * appears in the filename, and the contexts left out are named to the user.
+ */
+export async function EXPORT_DOCUMENT(payload: ExportDocumentCommand['payload']): Promise<void> {
+  const { resolver } = getState();
+
+  if (!resolver) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: 'Load a resolver document before exporting.',
+        code: 'NO_RESOLVER',
+        commandType: 'EXPORT_DOCUMENT',
+      },
+    });
+    return;
+  }
+
+  try {
+    const declared = resolver.getModifiers();
+    const modifiers = declared.map((modifier) => modifier.name);
+    const asked = payload.contexts ?? {};
+    for (const name of Object.keys(asked)) {
+      if (!modifiers.includes(name)) {
+        throw new Error(`"${name}" is not one of this document's modifiers (${modifiers.join(', ') || 'none'}).`);
+      }
+    }
+
+    const input: ResolverInput = {};
+    for (const { name, contexts, default: fallback } of declared) {
+      const context = asked[name] ?? fallback;
+      if (context === undefined || !contexts.includes(context)) {
+        throw new Error(`"${context}" is not one of the contexts of "${name}" (${contexts.join(', ')}).`);
+      }
+      input[name] = context;
+    }
+
+    const ds = resolver.resolveToDesignSystem(input);
+    const mode = resolver.getModeName(input);
+
+    const json = exportToJSON(ds, payload.includeExtensions ? await stampsByToken() : new Map(), {
+      includeExtensions: payload.includeExtensions,
+      // Where the tokens came from. The resolver document can say which
+      // revision of the system it describes; without carrying it here, the
+      // export said only which combination it held.
+      documentVersion: resolver.getDeclaredVersion(),
+    });
+
+    const omitted = flatMap(declared, ({ name, contexts }) => contexts.filter((context) => context !== input[name]));
+    if (omitted.length > 0) {
+      figma.notify(
+        `Exported ${mode}. ${omitted.join(', ')} ${omitted.length === 1 ? 'is' : 'are'} ` +
+          `not in this file — DTCG token files hold one context of each modifier.`,
+      );
+    }
+
+    const baseName = resolver.name?.trim() || 'resolver';
+    // A mode name joins the contexts with "/", which a filename cannot hold.
+    const filename = omitted.length > 0 ? `${baseName}.${mode.replace(/\//g, '.')}.json` : `${baseName}.json`;
+
+    postToUi({
+      type: 'DOCUMENT_EXPORTED',
+      payload: { json, filename },
+    });
+  } catch (error) {
+    postToUi({
+      type: 'ERROR',
+      payload: {
+        message: error instanceof Error ? error.message : String(error),
+        code: 'INVALID_DOCUMENT',
+        commandType: 'EXPORT_DOCUMENT',
+      },
+    });
+  }
+}
+
+/**
+ * The stamp each variable and style Toghen wrote in the file carries, by the token it names, without its id: a target's
+ * ids stay in the file they belong to, out of the token file. A person's copy is not Toghen's and is not among them.
+ */
+async function stampsByToken(): Promise<Map<string, Stamp>> {
+  const stamps = new Map<string, Stamp>();
+  const add = (stamp: Stamp | undefined): void => {
+    if (stamp?.is.token === undefined) return;
+    const { id: _id, ...rest } = stamp;
+    stamps.set(stamp.is.token, rest);
+  };
+  for (const stamped of Object.values((await indexFigmaCollections()).variablesByToken)) for (const { stamp } of stamped) add(stamp);
+  for (const { stamp } of await localStyles()) add(stamp);
+  return stamps;
+}
+
+function postToUi(message: Response): void {
+  figma.ui.postMessage(message);
+}

package/main/handlers/getSelection.ts

@@ -0,0 +1,43 @@
+import type { Response } from '../../shared/protocol.js';
+import { buildSelectionPayload } from '../utils/buildPayloads.js';
+import { indexFigmaCollections } from '../utils/figmaCollectionIndex.js';
+
+/**
+ * Answers with the current selection.
+ *
+ * The UI hears about selection *changes* as they happen, so this covers the one
+ * case that event cannot: a panel opening and needing to know what is selected
+ * now, rather than waiting for the user to click something else.
+ */
+export async function GET_SELECTION(): Promise<void> {
+  const response: Response = {
+    type: 'SELECTION_CHANGED',
+    payload: buildSelectionPayload(figma.currentPage.selection),
+  };
+  figma.ui.postMessage(response);
+}
+
+/**
+ * Answers with the file's variable collections and their modes.
+ *
+ * The System pane matches them by name against the collections the document
+ * would build, and shows how many variables each holds beside how many the
+ * document would put there.
+ */
+export async function GET_FIGMA_COLLECTIONS(): Promise<void> {
+  const index = await indexFigmaCollections();
+  const variableCount: Record<string, number> = {};
+  for (const variable of Object.values(index.variableById)) {
+    variableCount[variable.variableCollectionId] = (variableCount[variable.variableCollectionId] ?? 0) + 1;
+  }
+  const response: Response = {
+    type: 'FIGMA_COLLECTIONS',
+    payload: Object.keys(index.byId).map((id) => ({
+      id,
+      name: index.byId[id].name,
+      modes: index.byId[id].modes,
+      variableCount: variableCount[id] ?? 0,
+    })),
+  };
+  figma.ui.postMessage(response);
+}

package/main/handlers/index.ts

@@ -0,0 +1,30 @@
+export {
+  LOAD_DOCUMENT,
+  GET_DOCUMENT_STATE,
+  GET_SYNC_STATE,
+  GET_RECENTS,
+  LOAD_RECENT,
+  FORGET_RECENT,
+} from './loadDocument.js';
+export { INSPECT_CORRESPONDENCE } from './inspectCorrespondence.js';
+export { GET_TOKEN_GRAPH } from './tokenGraph.js';
+export { LOAD_CONVENTIONS, GET_CONVENTIONS } from './loadConventions.js';
+export { PLAN_VARIABLE_SYNC } from './planVariableSync.js';
+export { EXECUTE_VARIABLE_SYNC } from './executeVariableSync.js';
+export { PLAN_STYLE_SYNC } from './planStyleSync.js';
+export { EXECUTE_STYLE_SYNC } from './executeStyleSync.js';
+export { EXPORT_DOCUMENT } from './exportDocument.js';
+export { AUDIT_SELECTION } from './auditSelection.js';
+export { PLAN_SCAFFOLD } from './planScaffold.js';
+export { EXECUTE_SCAFFOLD } from './executeScaffold.js';
+export { PLAN_APPLY_BINDINGS } from './planApplyBindings.js';
+export { EXECUTE_APPLY_BINDINGS, EXECUTE_APPLY } from './executeApplyBindings.js';
+export { PLAN_APPLY } from './planApply.js';
+export { READ_SELECTION_BINDINGS } from './readSelectionBindings.js';
+export { SELECT_NODES, COUNT_BOUND_LAYERS } from './boundLayers.js';
+export { GET_TEMPLATES, KEEP_TEMPLATE, FORGET_TEMPLATE, PLAN_BUILD, EXECUTE_BUILD, LOOK_UP_NEEDS, PLAN_RELINK } from './templates.js';
+export { CANCEL_OPERATION } from './cancelOperation.js';
+export { GET_SELECTION, GET_FIGMA_COLLECTIONS } from './getSelection.js';
+export { RESIZE_UI } from './resizeUi.js';
+export { RUN_COMPONENT, CHECK_COMPONENTS, FINISH_COMPONENTS } from './runComponent.js';
+export { GET_LOCK, DISCOVER_VARIABLES, LOCK_PICK, LOCK_FORGET, SET_BUILD_OVERRIDES, LIBRARY_KEYS, LOCK_WRITE } from './lock.js';