@toghen/figma 0.0.0-stage → 0.1.1

package/main/utils/figmaTokenAdapter.ts

@@ -0,0 +1,255 @@
+import { normalizeColorToSRGB01, normalizeDimensionToPx, fontFamilyNames, type ColorValue, type DimensionValue } from '@toghen/lib';
+
+const EPSILON = 1e-9;
+
+/**
+ * The spec models fontFamily as an ordered fallback stack, and `@toghen/lib`
+ * preserves it as an array — §9.1 forbids collapsing it during resolution.
+ * This is the stack as a list of names, however it was written.
+ */
+export function fontStack(fontFamily: unknown): string[] {
+  if (Array.isArray(fontFamily) || (typeof fontFamily === 'string' && fontFamily.trim())) {
+    return fontFamilyNames(fontFamily).map(String);
+  }
+  return [String(fontFamily ?? '')];
+}
+
+/**
+ * Figma names exactly one family, in a STRING variable: the stack's first.
+ * A text style may take a later one (`utils/fontStack.ts`), but the variable
+ * keeps the token's meaning and does not depend on the machine that ran the sync.
+ */
+export function toFigmaFontFamily(fontFamily: unknown): string {
+  return fontStack(fontFamily)[0] ?? '';
+}
+
+function clamp01(value: number): number {
+  if (Number.isNaN(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function toHexByte(value: number): string {
+  return Math.round(clamp01(value) * 255)
+    .toString(16)
+    .padStart(2, '0');
+}
+
+/**
+ * Converts a token colour to Figma's `RGBA`.
+ *
+ * Figma's `RGB`/`RGBA` channels are **sRGB** 0–1 — the same encoding the colour
+ * picker shows and the same one `normalizeColorToSRGB01()` produces. So this is
+ * a pass-through, and that is the whole point: this function used to apply the
+ * sRGB→linear transfer curve on top, which shipped every mid-tone several stops
+ * too dark (`#808080` became `#373737`).
+ *
+ * It also disagreed with `figmaStyleAdapter`, which has always written shadow
+ * and gradient colours as plain sRGB — so one token value rendered two
+ * different ways in the same file depending on where it landed.
+ *
+ * `clamp01` stays: culori can return slightly out-of-gamut channels when
+ * converting from wider spaces such as `lab` or `oklch`, and Figma rejects
+ * values outside 0–1.
+ *
+ * ### Known limitation: Display P3 documents
+ *
+ * Figma's channels are gamma-encoded **in the document's colour profile**, not
+ * unconditionally sRGB: *"All colors are specified in the same color space
+ * which will be the color profile of the document, `documentColorProfile`."*
+ * In a default (sRGB) document these are ordinary sRGB values and this
+ * pass-through is exact. In a **Display P3** document the same numbers are read
+ * as P3 coordinates, so an sRGB token would land slightly more saturated.
+ *
+ * Handling that means reading `figma.root.documentColorProfile` and converting
+ * sRGB→P3 when it is `DISPLAY_P3`. Not done here: it needs its own decision
+ * about which profile a token document is authored in, and the error is far
+ * smaller than the sRGB→linear conversion this replaced.
+ *
+ * Since Update 141 a paint, a gradient stop and an effect colour may carry a
+ * `sourceColor` (sRGB, Display P3, OKLCH and others) beside `r`/`g`/`b`, which
+ * stay the profile's projection. That could carry a token's `colorSpace` as
+ * authored, for paints and effects; Figma documents nothing of the kind for
+ * variables. Not used here.
+ */
+function toFigmaRgba(value: string | ColorValue): RGBA {
+  const srgb = normalizeColorToSRGB01(value);
+  return {
+    r: clamp01(srgb.r),
+    g: clamp01(srgb.g),
+    b: clamp01(srgb.b),
+    a: clamp01(srgb.a),
+  };
+}
+
+/**
+ * What a number is in Figma: `percent` for an opacity, which a variable bound to a layer's opacity holds as a
+ * percentage (`55` is 55%, drawn at 0.55), and nothing for every other number.
+ */
+export type FigmaUnit = 'percent';
+
+/** An opacity from 0 to 1, as the percentage a Figma variable holds. Rounded to what a float can say, so 0.55 is 55 and not 55.00000000000001. */
+const toPercent = (fraction: number): number => Number((fraction * 100).toPrecision(12));
+
+/**
+ * A token value in Figma's representation. `unit` says the number is an opacity: it is written × 100.
+ * Both sides of a comparison (`figmaValuesEqual`) are in this representation, so they compare in percent.
+ */
+export function toFigmaValue(value: unknown, type: string, unit?: FigmaUnit): VariableValue {
+  switch (type) {
+    case 'color':
+      if (
+        typeof value !== 'string' &&
+        (typeof value !== 'object' || value === null || !('colorSpace' in value) || !('components' in value))
+      ) {
+        throw new Error(`Unsupported color value format: ${JSON.stringify(value)}`);
+      }
+      return toFigmaRgba(value as string | ColorValue);
+
+    case 'dimension':
+      // The library does the unit arithmetic, and throws on a non-dimension.
+      return normalizeDimensionToPx(value as DimensionValue);
+
+    case 'letterSpacing':
+      // Figma binds a number to letter spacing as pixels. `em` has none: sum.ts reports it before it gets here.
+      if (typeof value === 'object' && value !== null && (value as { unit?: unknown }).unit === 'em') {
+        throw new Error('A letter spacing in em has no pixel value without a font size.');
+      }
+      return normalizeDimensionToPx(value as DimensionValue);
+
+    case 'number':
+    case 'fontWeight': {
+      const numeric = Number(value);
+      if (!Number.isFinite(numeric)) {
+        throw new Error(`Cannot convert value "${String(value)}" to number.`);
+      }
+      return unit === 'percent' && type === 'number' ? toPercent(numeric) : numeric;
+    }
+
+    case 'string':
+      return String(value);
+
+    case 'fontFamily':
+      return toFigmaFontFamily(value);
+
+    case 'boolean':
+      return Boolean(value);
+
+    default:
+      throw new Error(`Cannot convert type "${type}" to a Figma Variable value.`);
+  }
+}
+
+/**
+ * Relative tolerance for comparing two numbers Figma has stored.
+ *
+ * **Figma stores float32.** Measured: `0.4` reads back as `0.4000000059604645`
+ * and a PERCENT line height of `160` as `160.0000023841858` — see
+ * `.reference/figma/measured_behaviour.md`. So a value written and read back is
+ * never bit-identical to the one sent, and comparing with `===` would report
+ * every token in the file as changed.
+ *
+ * The tolerance is **relative** because the error is. float32 carries a 24-bit
+ * mantissa, so its relative epsilon is ~1.19e-7; an absolute tolerance tuned for
+ * a colour channel in 0–1 would be far too tight for a `9999px` radius.
+ */
+const FLOAT32_RELATIVE_TOLERANCE = 1e-6;
+/** Floor for values at or near zero, where a relative tolerance vanishes. */
+const NEAR_ZERO_TOLERANCE = 1e-9;
+
+export function numbersEqual(a: number, b: number): boolean {
+  if (a === b) return true;
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return false;
+
+  const scale = Math.max(Math.abs(a), Math.abs(b));
+  return Math.abs(a - b) <= Math.max(NEAR_ZERO_TOLERANCE, FLOAT32_RELATIVE_TOLERANCE * scale);
+}
+
+function isRgbLike(value: unknown): value is RGBA {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as RGB).r === 'number' &&
+    typeof (value as RGB).g === 'number' &&
+    typeof (value as RGB).b === 'number'
+  );
+}
+
+export function isAlias(value: unknown): value is VariableAlias {
+  return typeof value === 'object' && value !== null && (value as VariableAlias).type === 'VARIABLE_ALIAS';
+}
+
+/**
+ * Whether two Figma variable values are the same value.
+ *
+ * Both sides must already be in **Figma's** representation. Do not compare by
+ * round-tripping through `fromFigmaValue()`: that is lossy by design — a
+ * `{colorSpace, components}` token becomes a hex string on the way back — so a
+ * comparison made there would report differences that do not exist.
+ *
+ * An alias never equals a concrete value. A designer pointing a variable at
+ * another variable really has changed it, and saying so is the honest answer.
+ */
+export function figmaValuesEqual(a: VariableValue | undefined, b: VariableValue | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+
+  if (isAlias(a) || isAlias(b)) {
+    return isAlias(a) && isAlias(b) && a.id === b.id;
+  }
+
+  if (typeof a === 'number' && typeof b === 'number') {
+    return numbersEqual(a, b);
+  }
+
+  if (isRgbLike(a) && isRgbLike(b)) {
+    // Alpha is optional on RGB; Figma treats an absent alpha as opaque.
+    return numbersEqual(a.r, b.r) && numbersEqual(a.g, b.g) && numbersEqual(a.b, b.b) && numbersEqual(a.a ?? 1, b.a ?? 1);
+  }
+
+  return a === b;
+}
+
+/**
+ * Turns a value Figma holds back into something readable.
+ *
+ * **The alias case is checked before the type**, and that ordering is the whole
+ * of it: a `VariableAlias` is an object with no `r`/`g`/`b`, so a COLOR variable
+ * pointed at another variable would fall through `clamp01(undefined ?? 0)` and
+ * read back as a confident `#000000`. A silently wrong value is worse than an
+ * unreadable one — this is the only place in the plugin where a Figma value is
+ * shown to a person rather than compared, so it is the only place that mistake
+ * would be believed.
+ *
+ * The alias's target name is not knowable here. `resolveAliasName` is how the
+ * caller — which holds the variable index — supplies it; without one the id is
+ * shown, which is at least true.
+ */
+export function fromFigmaValue(
+  value: VariableValue,
+  type: VariableResolvedDataType,
+  resolveAliasName?: (variableId: string) => string | undefined,
+): unknown {
+  if (isAlias(value)) {
+    return `→ ${resolveAliasName?.(value.id) ?? value.id}`;
+  }
+
+  switch (type) {
+    case 'COLOR': {
+      const color = value as RGBA;
+      // Figma channels are already sRGB — see toFigmaRgba().
+      const r = clamp01(color.r ?? 0);
+      const g = clamp01(color.g ?? 0);
+      const b = clamp01(color.b ?? 0);
+      const a = clamp01(color.a ?? 1);
+
+      const hex = `#${toHexByte(r)}${toHexByte(g)}${toHexByte(b)}`;
+      const alphaHex = toHexByte(a);
+      return Math.abs(a - 1) < EPSILON ? hex : `${hex}${alphaHex}`;
+    }
+    case 'FLOAT':
+    case 'STRING':
+    case 'BOOLEAN':
+      return value;
+    default:
+      return value;
+  }
+}

package/main/utils/flattenDesignSystem.ts

@@ -0,0 +1,38 @@
+import type { DesignSystem, DesignToken } from '@toghen/lib';
+
+export interface FlattenedTokenEntry {
+  path: string;
+  token: DesignToken;
+  collection: string;
+}
+
+/**
+ * Yields every token of a `DesignSystem`, resolved.
+ *
+ * A system may hold a multi-mode collection alongside a single-mode one, and a
+ * mode that only some collections know about skips the others rather than
+ * aborting the walk (`getAllPaths()` throws `InvalidModeError` for a mode its
+ * collection does not declare).
+ *
+ * @param ds - The system to walk
+ * @param mode - Optional mode; collections lacking it are skipped. When omitted,
+ *   each collection's own default mode is used.
+ */
+export function* flattenDesignSystem(ds: DesignSystem, mode?: string): Generator<FlattenedTokenEntry> {
+  for (const collectionName of ds.getCollectionNames()) {
+    const collection = ds.getCollection(collectionName);
+    if (!collection) continue;
+
+    if (mode !== undefined && !collection.getModes().includes(mode)) {
+      continue;
+    }
+
+    for (const tokenPath of collection.getAllPaths(mode)) {
+      const path = `${collectionName}.${tokenPath}`;
+      const token = ds.resolveToken(path, mode);
+      if (!token) continue;
+
+      yield { path, token, collection: collectionName };
+    }
+  }
+}

package/main/utils/folds.ts

@@ -0,0 +1,203 @@
+/**
+ * Parts folded into modes, or left as one variable each.
+ *
+ * A subgroup whose key is in the parts vocabulary is a part (lib's `partsOf`). A component is the group
+ * above the first part of a path, and it varies along the vocabulary's axes. Each axis, for each component, is
+ * either folded or not:
+ *
+ * - **Folded:** a collection named after the axis, `rest` first and a mode per value. The variable of the
+ *   rest token (the path with the part segment removed) takes its cell in a mode from the part token.
+ * - **Not folded:** the segment stays in the path, and the part token is a variable of its own.
+ *
+ * The decision is per axis per component, in the vocabulary's order, and the reason an axis did not fold is kept
+ * to be said. This file only decides and re-homes; where a token lives otherwise is `sum.ts`.
+ */
+
+import { cssLinkName, cssPropertyName, referencePath, type Collection, type Part, type Resolver } from '@toghen/lib';
+import { REST } from '../../shared/components/axes.js';
+import { flatMap } from './lists.js';
+import { MAX_MODES } from './resolverModes.js';
+import { linkVariableName } from './tokenPath.js';
+import type { SumCell, SumCollection, SumToken, SumVariable } from './sum.js';
+
+/**
+ * The component groups a loaded document lays out as one variable per part (`layout=parts` in a component file),
+ * as the command line told the plugin when it checked the files. Every plan and every reader of the sum asks it,
+ * so they agree on where a variable is.
+ */
+const unfolded = new WeakMap<Resolver, readonly string[]>();
+export const unfoldedFor = (resolver: Resolver): readonly string[] => unfolded.get(resolver) ?? [];
+export const setUnfolded = (resolver: Resolver, groups: readonly string[]): void => void unfolded.set(resolver, groups);
+
+export interface AxisFold {
+  axis: string;
+  /** The part keys the component uses on this axis, in the vocabulary's order. */
+  values: string[];
+  folded: boolean;
+  /** Why it did not fold, in words. */
+  why?: string;
+}
+
+export interface ComponentFold {
+  /** The component's group: the path above the first part. */
+  group: string;
+  /** Every axis its parts use, in the vocabulary's order. */
+  axes: AxisFold[];
+}
+
+export interface Folds {
+  components: ComponentFold[];
+  /** Folded axis to the modes of its collection, `rest` first, shared by every component that folds it. */
+  collections: Map<string, string[]>;
+  /** Rest path to folded axis (in vocabulary order) to mode to the path of the part token that gives it. */
+  parts: Map<string, Map<string, Map<string, string>>>;
+}
+
+/**
+ * Decides, for every component the paths hold, which axes fold. `unfold` names the groups laid out as
+ * one variable per part whatever the tokens allow (`layout=parts`). Throws what lib throws for a bad vocabulary
+ * or two parts of one axis on a path.
+ */
+export function foldsOf(collection: Collection, paths: readonly string[], unfold: readonly string[] = []): Folds {
+  // Each part token by its component (lib's `partsOf`), with the parts it passes through and their twins.
+  const byGroup = new Map<string, { path: string; parts: Part[] }[]>();
+  for (const path of paths) {
+    const { parts, component } = collection.partsOf(path);
+    if (component === null) continue;
+    (byGroup.get(component) ?? byGroup.set(component, []).get(component)!).push({ path, parts });
+  }
+
+  const folds: Folds = { components: [], collections: new Map(), parts: new Map() };
+  for (const [group, tokens] of byGroup) {
+    const folded = new Set<string>();
+    const axes: AxisFold[] = [];
+    // The component's axes and their values, in precedence order (lib's `axesOf`).
+    for (const { axis, values } of collection.axesOf(group)) {
+      const partOf = (token: (typeof tokens)[number]) => token.parts.find((part) => part.axis === axis);
+      const carrying = tokens.filter((token) => partOf(token) !== undefined);
+      if (carrying.length === 0) continue;
+      const clash = carrying.find((token) => token.parts.some((part) => folded.has(part.axis)));
+      // The twin along this axis: the token its cell falls back to.
+      const lacking = carrying.find((token) => !partOf(token)!.twinExists);
+      const modes = folds.collections.get(axis) ?? [REST];
+      const merged = [...modes, ...values.filter((value) => !modes.includes(value))];
+      const why = unfold.includes(group)
+        ? 'the component is laid out as one variable per part (layout=parts)'
+        : clash
+          ? `"${clash.path}" carries it together with the folded "${clash.parts.find((part) => folded.has(part.axis))!.axis}"`
+          : lacking
+            ? `no rest value: "${lacking.path}" needs "${partOf(lacking)!.twin}", which is not defined`
+            : merged.length > MAX_MODES
+              ? `its values ${merged.slice(MAX_MODES).join(', ')} do not fit the ${folds.collections.has(axis) ? 'shared ' : ''}collection "${axis}", which already holds ${modes.length} mode${modes.length === 1 ? '' : 's'} (${modes.join(', ')}) and Figma allows ${MAX_MODES}`
+              : undefined;
+      axes.push({ axis, values, folded: why === undefined, ...(why ? { why } : {}) });
+      if (why) continue;
+      folded.add(axis);
+      folds.collections.set(axis, merged);
+      for (const token of carrying) {
+        const { twin: rest, key } = partOf(token)!;
+        const modesOf = folds.parts.get(rest) ?? folds.parts.set(rest, new Map()).get(rest)!;
+        const byMode = modesOf.get(axis) ?? modesOf.set(axis, new Map()).get(axis)!;
+        byMode.set(key, token.path);
+      }
+    }
+    folds.components.push({ group, axes });
+  }
+  return folds;
+}
+
+/** What a component's layout is, in one sentence, when some axis stays in the path; `undefined` when every axis folded. */
+export function layoutSaid({ group, axes }: ComponentFold): string | undefined {
+  const stays = axes.filter((axis) => !axis.folded);
+  if (stays.length === 0) return undefined;
+  const folded = axes.filter((axis) => axis.folded);
+  return (
+    `"${group}": ` +
+    (folded.length > 0 ? `folds ${folded.map((axis) => `"${axis.axis}" (modes ${[REST, ...axis.values].join(', ')})`).join(', ')}; ` : '') +
+    stays.map((axis) => `"${axis.axis}" stays in the path, one variable per part: ${axis.why}`).join('; ') +
+    '.'
+  );
+}
+
+/**
+ * Re-homes the tokens a fold touches. A rest token's variable becomes the head of a chain through the folded
+ * axes' collections, in vocabulary order (the later axis wins, as the later modifier does), above any chain the
+ * worlds already made. Each cell takes the part token's cell, an alias to the part token's own variable when it
+ * varies with a world and so keeps one, and falls back to the rest where there is no part token.
+ *
+ * Part tokens that fed a cell and need no variable of their own are dropped.
+ */
+export function foldTokens(
+  tokens: SumToken[],
+  folds: Folds,
+  dsName: string,
+  baseName: string,
+): { tokens: SumToken[]; collections: SumCollection[] } {
+  const byPath = new Map(tokens.map((token) => [token.path, token]));
+  const dropped = new Set<string>();
+  const folded = new Map<string, SumToken>();
+
+  for (const [rest, axes] of folds.parts) {
+    const token = byPath.get(`${dsName}.${rest}`);
+    if (token?.routing.kind !== 'variable' || token.variables.length === 0) continue;
+    const { variableType } = token.routing;
+    const [head, ...below] = token.variables;
+    const worlds = head.collection !== baseName;
+
+    // The part token's cell: its value, or an alias to its variable when worlds give it one. A part token that
+    // is not a variable of this type is not folded: it stays what it is, and the mode falls back to the rest.
+    // A part that is a whole reference to its rest has no cell of its own (the mode falls back to the rest), and
+    // one that is a whole reference to a sibling part folded into the same rest takes that part's cell. `seen`
+    // stops a loop of siblings, which falls back to the rest as well.
+    const siblings = new Set(flatMap([...axes.values()], (byMode) => [...byMode.values()]));
+    const cellOf = (path: string, seen = new Set<string>([path])): SumCell | undefined => {
+      const part = byPath.get(`${dsName}.${path}`);
+      const first = part?.variables[0];
+      if (part?.routing.kind !== 'variable' || part.routing.variableType !== variableType || !first) return undefined;
+      if (first.collection !== baseName) return { kind: 'link', to: first.key };
+      dropped.add(part.path);
+      const cell = first.cells.get('default');
+      if (cell?.kind !== 'reference') return cell;
+      if (cell.to === token.path) return undefined;
+      const sibling = referencePath(cell.to);
+      if (!siblings.has(sibling)) return cell;
+      return seen.has(sibling) ? undefined : cellOf(sibling, seen.add(sibling));
+    };
+
+    // The rest, kept as a link below when worlds vary it; otherwise its single cell is the axis's `rest`.
+    const demoted: SumVariable | undefined = worlds
+      ? {
+          ...head,
+          key: `${dsName}.${rest}~${head.collection}`,
+          name: linkVariableName(rest, head.collection),
+          codeSyntax: `var(${cssLinkName(cssPropertyName(token.path), head.collection)})`,
+        }
+      : undefined;
+    let under = demoted;
+    const rows: SumVariable[] = [];
+    const names = [...axes.keys()];
+    for (const [axis, byMode] of axes) {
+      const last = axis === names[names.length - 1];
+      const cells = new Map<string, SumCell>();
+      for (const mode of folds.collections.get(axis) as string[]) {
+        const part = byMode.get(mode);
+        const own = part === undefined ? undefined : cellOf(part);
+        cells.set(mode, own ?? (under ? { kind: 'link', to: under.key } : (head.cells.get('default') as SumCell)));
+      }
+      under = {
+        key: last ? token.path : `${dsName}.${rest}~${axis}`,
+        name: last ? head.name : linkVariableName(rest, axis),
+        collection: axis,
+        codeSyntax: last ? head.codeSyntax : `var(${cssLinkName(cssPropertyName(token.path), axis)})`,
+        cells,
+      };
+      rows.unshift(under);
+    }
+    folded.set(token.path, { ...token, variables: [...rows, ...(demoted ? [demoted] : []), ...below] });
+  }
+
+  return {
+    tokens: tokens.filter((token) => !dropped.has(token.path)).map((token) => folded.get(token.path) ?? token),
+    collections: [...folds.collections].map(([name, modes]): SumCollection => ({ name, axis: true, modes })),
+  };
+}

package/main/utils/fontStack.ts

@@ -0,0 +1,57 @@
+/**
+ * A font stack is a fallback in Figma too: a text style takes the first family
+ * of the stack that Figma lists with the style asked for, as CSS takes the first
+ * the platform has. The generic families are CSS keywords, never in Figma's
+ * list, so they are named but not looked up.
+ */
+
+const GENERIC_FAMILIES: ReadonlySet<string> = new Set([
+  'monospace',
+  'serif',
+  'sans-serif',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-monospace',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-rounded',
+]);
+
+const keyOf = (family: string, style: string): string => `${family}\u0000${style}`;
+
+/** The fonts Figma lists, as a lookup by family and style. Read once per plan. */
+export async function listFonts(): Promise<ReadonlySet<string>> {
+  const fonts = await figma.listAvailableFontsAsync();
+  return new Set(fonts.map(({ fontName }) => keyOf(fontName.family, fontName.style)));
+}
+
+export interface FontChoice {
+  family: string;
+  /** The families before it that were passed over, in stack order. */
+  passedOver: string[];
+}
+
+/** The first family that is listed with `style`, or nothing when none is. */
+export function chooseFamily(stack: readonly string[], style: string, listed: ReadonlySet<string>): FontChoice | undefined {
+  const at = stack.findIndex((family) => !GENERIC_FAMILIES.has(family.toLowerCase()) && listed.has(keyOf(family, style)));
+  return at < 0 ? undefined : { family: stack[at], passedOver: stack.slice(0, at) };
+}
+
+/** `"a"`, `"a" and "b"`, `"a", "b" and "c"`. */
+function quoted(names: readonly string[]): string {
+  const all = names.map((name) => `"${name}"`);
+  return all.length < 2 ? all.join('') : `${all.slice(0, -1).join(', ')} and ${all[all.length - 1]}`;
+}
+
+const areNotAvailable = (names: readonly string[]): string => `${quoted(names)} ${names.length === 1 ? 'is' : 'are'} not available`;
+
+/** What a style that fell back to a later family says. */
+export function fallbackNote(path: string, choice: FontChoice): string {
+  return `"${path}" uses "${choice.family}": ${areNotAvailable(choice.passedOver)} in Figma.`;
+}
+
+/** Why a style none of whose families loads is skipped. */
+export function noFamilyReason(path: string, stack: readonly string[]): string {
+  return `"${path}" has no family Figma can load: ${areNotAvailable(stack)}.`;
+}

package/main/utils/lists.ts

@@ -0,0 +1,4 @@
+/** `flatMap`, which the sandbox's ES2017 library lacks. */
+export function flatMap<T, U>(items: readonly T[], map: (item: T) => U[]): U[] {
+  return ([] as U[]).concat(...items.map(map));
+}

package/main/utils/lockStore.ts

@@ -0,0 +1,72 @@
+/**
+ * The lock: what each name a file uses from a library resolved to, kept on the file's root.
+ *
+ * Shared plugin data in the `toghen` namespace, under `lock`, sharded (`shardedData.ts`) as kept templates are: a
+ * library of a few hundred components passes Figma's 100 kB per entry. It records keys, never what Toghen wrote: no
+ * hash, no time, no receipt. Receipts stay one per object. The shape is `reference.md`'s, *The lock*.
+ */
+
+import type { Lock, LockedLibrary } from '../../shared/protocol.js';
+import { isPlainObject, readSharded, toAsciiJson, writeSharded } from './shardedData.js';
+
+const KEY = 'lock';
+
+/** Our own limit, as for templates: room for a few thousand keys, and for other plugins. */
+const MAX_SHARDS = 8;
+
+const BY: readonly LockedLibrary['by'][] = ['discovery', 'build', 'command line', 'person'];
+
+const record = (value: unknown, valid: (entry: unknown) => boolean): boolean => isPlainObject(value) && Object.values(value).every(valid);
+
+export function isLibrary(value: unknown): value is LockedLibrary {
+  return (
+    isPlainObject(value) &&
+    (value.fileKey === undefined || typeof value.fileKey === 'string') &&
+    (value.path === undefined || typeof value.path === 'string') &&
+    (value.id === undefined || typeof value.id === 'string') &&
+    BY.includes(value.by as LockedLibrary['by']) &&
+    record(value.components, (entry) => isPlainObject(entry) && typeof entry.key === 'string' && typeof entry.set === 'boolean') &&
+    record(
+      value.styles,
+      (entry) => isPlainObject(entry) && typeof entry.key === 'string' && ['TEXT', 'EFFECT', 'PAINT'].includes(entry.kind as string),
+    ) &&
+    record(value.variables, (entry) => typeof entry === 'string')
+  );
+}
+
+/** The file's lock. None, or a damaged record, reads as an empty one: nothing resolves through it. */
+export function loadLock(): Lock {
+  try {
+    const payload = readSharded(KEY);
+    const parsed: unknown = payload ? JSON.parse(payload) : undefined;
+    if (
+      isPlainObject(parsed) &&
+      record(parsed.libraries, isLibrary) &&
+      (parsed.overrides === undefined || record(parsed.overrides, (entry) => typeof entry === 'string'))
+    ) {
+      return parsed as unknown as Lock;
+    }
+  } catch {
+    // A damaged record is no record.
+  }
+  return { libraries: {} };
+}
+
+/** Writes the lock. Returns why it could not, rather than throwing. */
+export function saveLock(lock: Lock): { ok: true } | { ok: false; reason: string } {
+  const written = writeSharded(KEY, toAsciiJson(lock), MAX_SHARDS);
+  if (written.ok) return { ok: true };
+  if (written.tooBig)
+    return {
+      ok: false,
+      reason: `The lock comes to ${Math.round(written.bytes / 1024)} kB, more than this plugin keeps in one file. Forget a library first.`,
+    };
+  return { ok: false, reason: written.reason ?? 'Figma refused the write.' };
+}
+
+/** A library's entry, or an empty one written by `by`. */
+export const libraryIn = (lock: Lock, name: string, by: LockedLibrary['by']): LockedLibrary =>
+  lock.libraries[name] ?? { by, components: {}, styles: {}, variables: {} };
+
+/** How a key is written where a name could be: `(key)"…"`, as a component file writes one. */
+export const keyIn = (value: string): string | undefined => /^\(key\)"([^"]+)"$/.exec(value)?.[1];