@toghen/figma 0.0.0-stage → 0.1.1

package/main/utils/syncState.ts

@@ -0,0 +1,133 @@
+/**
+ * Reads the stamps on the file's variables and styles into something the screen can say.
+ *
+ * ### Why this exists
+ *
+ * Each variable and style a sync writes carries a stamp (`tokenStamps.ts`): the
+ * token it holds and a receipt of what was written. The dirty check reads them,
+ * and without this none of it would reach the UI: a user opening a file they
+ * synced last week would have no way to learn that they had.
+ *
+ * ### What "covered" means here, exactly
+ *
+ * A token is covered when its variable's stamp holds a receipt for **every mode
+ * that token actually has a value in**, not every mode the document declares.
+ * A token contributed only by `dark` is complete with one, and measuring it
+ * against both modes would report it permanently half-done. This mirrors
+ * `VariableSyncEngine`, which builds `staleModes` only from modes where the
+ * token resolves; the two have to agree or the status contradicts the plan.
+ *
+ * Style-backed tokens are the exception: Figma styles have no modes, so a style
+ * stamped for the token is complete.
+ *
+ * ### What it deliberately does not claim
+ *
+ * Coverage is *presence of a stamp*, not currency. A token whose document value
+ * changed since the last sync still counts as covered: the stamp exists, the
+ * document has simply moved, and the plan is what says so. Answering "is it up
+ * to date?" here would mean keeping a second copy of the dirty check in step
+ * with the engine's. One dirty check, in the engine, is the arrangement worth having.
+ */
+
+import type { Resolver } from '@toghen/lib';
+import type { SyncStatePayload } from '../../shared/protocol.js';
+import { defaultTokenTypeMap, type TokenTypeConversionMap } from '../../shared/tokenTypeMap.js';
+import { indexFigmaCollections, type FigmaCollectionIndex } from './figmaCollectionIndex.js';
+import { figmaCollectionNameFor } from './resolverModes.js';
+import { buildSum, type SumToken } from './sum.js';
+import { localStyles } from './tokenStamps.js';
+
+/**
+ * Builds the payload describing what this Figma file's stamps say about being synced.
+ *
+ * @param resolver - The loaded document, or `null`. Without one the file-level
+ *   facts are still answered and the coverage counts are `null`: there is
+ *   nothing to measure the stamps against, and reporting `0` would read as
+ *   "nothing is synced" when the truth is "nothing has been asked".
+ */
+export async function buildSyncStatePayload(
+  resolver: Resolver | null,
+  conversionMap: TokenTypeConversionMap = defaultTokenTypeMap,
+): Promise<SyncStatePayload> {
+  const figmaIndex = await indexFigmaCollections();
+  const styled = new Set<string>();
+  for (const { stamp } of await localStyles()) if (stamp?.is.token !== undefined) styled.add(stamp.is.token);
+  const tokens = [...Object.keys(figmaIndex.variablesByToken), ...styled];
+  const recordedCount = Object.values(figmaIndex.variablesByToken).reduce((count, stamped) => count + stamped.length, 0) + styled.size;
+
+  const base = {
+    hasRecord: recordedCount > 0,
+    recordedCount,
+    recordNames: recordNamesOf(tokens),
+  };
+
+  if (!resolver) {
+    return { ...base, documentTokenCount: null, coveredCount: null, partialCount: null };
+  }
+
+  let sumTokens: SumToken[];
+  try {
+    sumTokens = buildSum(resolver, figmaCollectionNameFor(resolver), conversionMap).tokens;
+  } catch {
+    // A document the sum cannot be built from has no coverage to count; the plan says why.
+    return { ...base, documentTokenCount: null, coveredCount: null, partialCount: null };
+  }
+
+  let covered = 0;
+  let partial = 0;
+  for (const token of sumTokens) {
+    const coverage = token.routing.kind === 'style' ? (styled.has(token.path) ? 'covered' : 'none') : coverageOfToken(token, figmaIndex);
+    if (coverage === 'covered') covered += 1;
+    if (coverage === 'partial') partial += 1;
+  }
+
+  return {
+    ...base,
+    documentTokenCount: sumTokens.length,
+    coveredCount: covered,
+    partialCount: partial,
+  };
+}
+
+type Coverage = 'covered' | 'partial' | 'none';
+
+/**
+ * A token is the variables it is made of: one, or the links of a chain, each
+ * stamped with a key of its own. It is covered when every one of them is.
+ */
+function coverageOfToken(token: SumToken, figmaIndex: FigmaCollectionIndex): Coverage {
+  if (token.variables.length === 0) return 'none';
+
+  const each = token.variables.map((variable): Coverage => {
+    const collection = figmaIndex.byName[variable.collection];
+    const stamped = figmaIndex.variablesByToken[variable.key]?.find((held) => held.variableCollectionId === collection?.id);
+    const modes = [...variable.cells.keys()];
+    if (!stamped || !collection || modes.length === 0) return 'none';
+    const receipt = stamped.stamp?.receipt ?? {};
+    const recorded = modes.filter((mode) => {
+      const modeId = collection.modes.find((held) => held.name === mode)?.modeId;
+      return modeId !== undefined && receipt[modeId] !== undefined;
+    }).length;
+    if (recorded === modes.length) return 'covered';
+    return recorded > 0 ? 'partial' : 'none';
+  });
+  if (each.every((coverage) => coverage === 'covered')) return 'covered';
+  return each.some((coverage) => coverage !== 'none') ? 'partial' : 'none';
+}
+
+/**
+ * Whose stamps they are: the leading segment of every token they name, each
+ * once, in the order first met.
+ *
+ * A lookup path starts with the document's name, which is also the name of the
+ * base collection variable sync writes, so this names the documents synced into
+ * the file without a document loaded to compare against.
+ */
+function recordNamesOf(tokens: readonly string[]): string[] {
+  const names = new Set<string>();
+  for (const path of tokens) {
+    const dot = path.indexOf('.');
+    if (dot > 0) names.add(path.slice(0, dot));
+  }
+  return [...names];
+}

package/main/utils/templateStore.ts

@@ -0,0 +1,73 @@
+/**
+ * Component files and blueprints kept in the Figma file, so a set can be planned and built
+ * again from the plugin's screen without the command line.
+ *
+ * Kept in the file rather than per user: a template is
+ * part of what the file is built from, and everyone who opens the file should
+ * be able to build from it. Sharded (`shardedData.ts`), as older builds kept the sync record,
+ * since one file of a few dozen members can pass Figma's 100 kB per entry.
+ */
+
+import { isPlainObject, readSharded, toAsciiJson, writeSharded } from './shardedData.js';
+
+const KEY = 'templates';
+
+/** Our own limit: room for a few hundred files, and for other plugins. */
+const MAX_SHARDS = 8;
+
+export interface KeptTemplate {
+  /** The component's name, or a blueprint's page (`.blueprint.kdl`), which is the key: one template per name. */
+  name: string;
+  fileName: string;
+  text: string;
+  /** When it was kept, ISO. */
+  kept: string;
+}
+
+/** The kept templates, in the order they were first kept. A damaged record reads as none. */
+export function loadTemplates(): KeptTemplate[] {
+  let payload: string;
+  try {
+    payload = readSharded(KEY);
+  } catch {
+    return [];
+  }
+  if (!payload) return [];
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (entry): entry is KeptTemplate =>
+        isPlainObject(entry) &&
+        typeof entry.name === 'string' &&
+        typeof entry.fileName === 'string' &&
+        typeof entry.text === 'string' &&
+        typeof entry.kept === 'string',
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Writes the list. Returns why it could not, rather than throwing. */
+export function saveTemplates(templates: readonly KeptTemplate[]): { ok: true } | { ok: false; reason: string } {
+  const written = writeSharded(KEY, toAsciiJson(templates), MAX_SHARDS);
+  if (written.ok) return { ok: true };
+  if (written.tooBig) {
+    return {
+      ok: false,
+      reason: `The kept templates come to ${Math.round(written.bytes / 1024)} kB, more than this plugin keeps in one file. Forget one first.`,
+    };
+  }
+  return { ok: false, reason: written.reason ?? 'Figma refused the write.' };
+}
+
+/** Keeps one, replacing the template of the same name and, when named, the one it takes the place of. */
+export function keepTemplate(templates: readonly KeptTemplate[], template: KeptTemplate, replaces?: string): KeptTemplate[] {
+  const without = templates.filter((kept) => kept.name !== template.name && kept.name !== replaces);
+  const at = templates.findIndex((kept) => kept.name === template.name || kept.name === replaces);
+  if (at < 0) return [...without, template];
+  // Where it was, so replacing a file does not move its row.
+  const before = templates.slice(0, at).filter((kept) => kept.name !== template.name && kept.name !== replaces);
+  return [...before, template, ...without.slice(before.length)];
+}

package/main/utils/tokenPath.ts

@@ -0,0 +1,28 @@
+/**
+ * The functions that spell the Figma name a token path becomes.
+ *
+ * Variable sync writes a variable, and the component engine looks one up, by this
+ * name, so both call it and nothing else. It lives in a module of its own, and
+ * `correspondence.ts` re-exports it, so that the component script, which bundles
+ * only the engine, does not carry the sync comparison and its dependencies with it.
+ *
+ * A name has no collection in it: the variable lives in a collection, and a
+ * component file writes `{space.md}`, not `{ds.space.md}`. So the path these take
+ * is a *reference path*, the token's path without the collection segment, and
+ * lib's `referencePath()` turns a lookup path into one. Keys keep their spelling:
+ * `button.backgroundColor` is `button/backgroundColor`.
+ */
+export function tokenPathToVariableName(path: string, separator = '/'): string {
+  return path.replace(/\./g, separator);
+}
+
+/**
+ * A chain link's variable name: the token's name, `--`, the modifier.
+ *
+ * The head of a chain lives in another collection under the bare name, and a
+ * name found in two collections stops a component build, so a link needs the
+ * suffix. It is the CSS adapter's link rule, so one rule names a link in both targets.
+ */
+export function linkVariableName(path: string, modifier: string): string {
+  return `${tokenPathToVariableName(path)}--${modifier}`;
+}

package/main/utils/tokenStamps.ts

@@ -0,0 +1,91 @@
+/**
+ * The stamps the variable and style syncs keep on what they write.
+ *
+ * A stamp (`components/stamp.ts`) lives on the object it describes: the token the object holds, and a receipt, for
+ * each field Toghen owns, of what Figma reported right after Toghen wrote it. A variable's fields are its value in each
+ * mode, keyed by the mode's id, and `scopes`; a style's are the properties a style plan writes (`reportOf`). What
+ * Figma reports now against the receipt says whether anyone changed the object since (drift); where nobody did, the
+ * document against what Figma holds says whether the document moved.
+ *
+ * Kept on the object, a receipt cannot be carried onto another one, which a record keyed by token path on the
+ * document root could (decisions, *Ruled: the stamp, one receipt per object, for every target*). Older builds kept
+ * that record; `rootRecord.ts` turns it into stamps, once.
+ */
+
+import { getStamp, receiptOf, setStamp, sortOut, type Stamp, type Stamped } from '../components/stamp.js';
+
+/** Adds to an object's receipt what Figma reports for the fields just written. A stamp for another token starts again. */
+export function stampWritten(object: Stamped, token: string, reported: Record<string, unknown>): void {
+  const held = getStamp(object);
+  const receipt = held?.is.token === token ? held.receipt : {};
+  setStamp(object, { is: { token }, receipt: { ...receipt, ...receiptOf(reported) } });
+}
+
+/** Scopes as a receipt hashes them: Figma keeps them in an order of its own, and they compare as a set. */
+export const reportedScopes = (scopes: readonly VariableScope[]): VariableScope[] => [...scopes].sort();
+
+/** What Figma reports for the properties a style plan writes: what a style's receipt hashes, field by field. */
+export function reportOf(style: BaseStyle): Record<string, unknown> {
+  switch (style.type) {
+    case 'TEXT': {
+      const text = style as TextStyle;
+      return {
+        // Figma reads a font back with variation settings nobody set (measured 20 October 2026): a style holds its family and style.
+        fontName: { family: text.fontName.family, style: text.fontName.style },
+        fontSize: text.fontSize,
+        lineHeight: text.lineHeight,
+        letterSpacing: text.letterSpacing,
+        textCase: text.textCase,
+        textDecoration: text.textDecoration,
+        boundVariables: text.boundVariables,
+      };
+    }
+    case 'EFFECT':
+      return { effects: (style as EffectStyle).effects };
+    case 'PAINT':
+      return { paints: (style as PaintStyle).paints };
+    default:
+      return {};
+  }
+}
+
+export type StyleKind = 'TEXT' | 'EFFECT' | 'PAINT';
+
+/** A local style, with its stamp when it is Toghen's. */
+export interface LocalStyle {
+  style: BaseStyle;
+  styleType: StyleKind;
+  /** Absent on a style Toghen did not write, and on a person's copy of one. */
+  stamp?: Stamp;
+  /** The style moved: its stamp names another id, which the next write replaces with its own. */
+  moved?: true;
+  /** A person's copy of a style Toghen wrote: the original. It carries the original's stamp, which is not read as its own. */
+  copyOf?: BaseStyle;
+}
+
+/** The file's local styles, each with its stamp when it is Toghen's, and each copy of one with its original (`sortOut`). */
+export async function localStyles(): Promise<LocalStyle[]> {
+  const [text, effect, paint] = await Promise.all([
+    figma.getLocalTextStylesAsync(),
+    figma.getLocalEffectStylesAsync(),
+    figma.getLocalPaintStylesAsync(),
+  ]);
+  const all = [
+    ...text.map((style) => ({ style, styleType: 'TEXT' as const })),
+    ...effect.map((style) => ({ style, styleType: 'EFFECT' as const })),
+    ...paint.map((style) => ({ style, styleType: 'PAINT' as const })),
+  ];
+  const byId = new Map<string, BaseStyle>(all.map(({ style }) => [style.id, style]));
+  const sorted = await sortOut(
+    all.map(({ style }) => style),
+    getStamp,
+    (id) => byId.get(id),
+  );
+  const copyOf = new Map(sorted.copies.map(({ copy, of }) => [copy, of]));
+  return all.map(({ style, styleType }) => {
+    const of = copyOf.get(style);
+    if (of) return { style, styleType, copyOf: of };
+    const stamp = getStamp(style);
+    return { style, styleType, ...(stamp ? { stamp } : {}), ...(sorted.moved.has(style) ? { moved: true as const } : {}) };
+  });
+}

package/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "Toghen",
+  "id": "com.toghen.figma",
+  "api": "1.0.0",
+  "main": "dist/code.js",
+  "ui": "dist/ui.html",
+  "editorType": ["figma"],
+  "documentAccess": "dynamic-page",
+  "permissions": ["teamlibrary"],
+  "enablePrivatePluginApi": true,
+  "networkAccess": {
+    "allowedDomains": ["none"],
+    "devAllowedDomains": ["ws://localhost:3055"]
+  }
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@toghen/figma",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "toghen-figma": "cli/bin.mjs"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:dist": "node build.mjs",
+    "build:dist:prod": "NODE_ENV=production node build.mjs",
+    "build:watch": "node build.mjs --watch",
+    "preview": "node scripts/preview.mjs",
+    "typecheck": "tsc -p tsconfig.plugin.json && tsc -p tsconfig.test.json",
+    "expectations": "tsx scripts/expectation-sheet.ts",
+    "components": "node cli/bin.mjs components",
+    "toghen-figma": "node cli/bin.mjs",
+    "pretest": "pnpm typecheck",
+    "test": "node --import tsx/esm --test 'test/**/*.test.ts'",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "check": "biome check . && pnpm typecheck && pnpm test && pnpm build && node scripts/check-purity.mjs && node scripts/check-leaks.mjs",
+    "prepack": "node build.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@figma/plugin-typings": "^1.142.0",
+    "@toghen/ui": "^0.1.0",
+    "@types/node": "^24.1.0",
+    "@types/ws": "^8.18.2",
+    "esbuild": "^0.21.0",
+    "postcss": "^8.5.8",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@bgotink/kdl": "^0.4.0",
+    "@toghen/lib": "^0.1.0",
+    "kdlet": "^0.1.0",
+    "kdlet-guards": "^0.1.0",
+    "tsx": "^4.20.3",
+    "ws": "^8.22.0"
+  },
+  "license": "MIT",
+  "author": "Egildo Tagliareni <egildo@tagliareni.it>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/Toghen/figma.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "description": "Toghen's Figma adapter: tokens to Variables and Styles, component files, and the toghen-figma command line",
+  "files": [
+    "cli/",
+    "main/",
+    "shared/",
+    "dist/",
+    "manifest.json",
+    "README.md",
+    "guide.md",
+    "reference.md",
+    "component-files.md",
+    "LICENSE"
+  ]
+}