Figma Typings Audit

Absorbing a @figma/plugin-typings release into Figwright, end to end: audit → upgrade → implement what's worth having.

One hard ordering constraint: diff before upgrading. The audit compares the installed version against the target, so upgrading first destroys the baseline. (Recoverable — the old version is in git history and npm pack can still fetch it — but don't create the problem.)

Target version: whatever the user named, otherwise the latest on npm.

Stage 0 — Resolve versions

grep '@figma/plugin-typings' packages/plugin/package.json          # the declared range
grep '"version"' packages/plugin/node_modules/@figma/plugin-typings/package.json  # what is installed
npm view @figma/plugin-typings version                              # latest
npm view @figma/plugin-typings versions --json                      # how many releases are being skipped

Compare against the installed version, not the declared range — a caret range can already be satisfied by something newer than what the lockfile pinned.

If installed and target are equal, say so and stop. Don't spend tokens on the rest.

Stage 1 — Get the authoritative diff

There is no other source. figma/plugin-typings ships no CHANGELOG and no GitHub Releases (the releases API returns an empty array), and its commit messages are content-free (1.132.0, Release v1.132 updates). The .d.ts diff is the only ground truth.

Work in the session scratchpad directory ($SCRATCH below):

cd "$SCRATCH" && mkdir -p typings-audit && cd typings-audit
npm pack @figma/plugin-typings@<installed> @figma/plugin-typings@<target> --pack-destination .
for v in <installed> <target>; do
  mkdir -p "$v" && tar -xzf "figma-plugin-typings-$v.tgz" -C "$v" --strip-components=1
done
diff -rq <installed> <target>            # which files differ at all — start here
diff -u <installed>/package.json <target>/package.json
diff -u <installed>/index.d.ts <target>/index.d.ts

diff -rq first, so the set of changed files is observed rather than assumed. Every file it names has to be accounted for — including plugin-api-standalone.d.ts, whose trailing export { ... } is one enormous single line where a removed symbol is easy to miss.

index.d.ts declares the figma global, fetch and timers — small, but high blast radius. package.json looks irrelevant and isn't: its devDependencies.prettier explains formatting noise. When that version moves, the .d.ts diff fills with reflowed unions and extends clauses that mean nothing. Check it before reading a single hunk.

Normalize before diffing the .d.ts

Never classify hunks straight out of diff -u. Reformat both versions with the target's own formatter first, so what survives is guaranteed to be semantic:

mkdir -p norm
for v in <installed> <target>; do
  for f in plugin-api.d.ts plugin-api-standalone.d.ts; do cp "$v/$f" "norm/$v.$f"; done
done
cp <target>/.prettierrc norm/.prettierrc          # the package ships its own config
npx --yes prettier@<version from target package.json devDeps> --write "norm/*.d.ts"
diff -u norm/<installed>.plugin-api.d.ts norm/<target>.plugin-api.d.ts
diff -u norm/<installed>.plugin-api-standalone.d.ts norm/<target>.plugin-api-standalone.d.ts

Watch prettier's own per-file output: the target files should report unchanged. That confirms you picked the right formatter version, and turns "the noise is upstream reformatting" from a guess into an observation.

Classify from these normalized diffs. plugin-api.d.ts is the one that matters — packages/plugin/tsconfig.json sets types: ["@figma/plugin-typings"], whose index.d.ts references it — and standalone serves as a cross-check that nothing was missed.

Measured on 1.134.0 → 1.135.0: 328 raw lines collapsed to 32, all of them one change. Never estimate the size of a release from raw diff line count — 1.134.0 was smaller (228 lines) and carried three real buckets.

When the jump spans several releases, diff the two endpoints; the cumulative effect is what matters. Go release-by-release only to attribute a specific change to a version.

Stage 2 — Classify every hunk

Drop hunks that are JSDoc-only (comment/example churn, no signature change) — the file is mostly documentation and these dominate the line count without meaning anything.

Sort the rest into three buckets:

1. Breaking — a removed symbol, a narrowed type (optional → required, union → smaller union), a changed signature, or a newly-added @deprecated. Look at - lines first.
2. New API — a new method, node type, enum member, or namespace. A new capability, so a candidate for a new tool or a new argument on an existing one.
3. New field on an existing type — an added property on something Figwright already reads (Paint, Effect, TextStyle, a node interface…). ⚠️ The dangerous bucket. No compiler will ever flag it and the read path will keep silently omitting the dimension. It is this repo's recurring bug class: a multi-dimensional Figma property collapsed to one field or dropped on the way out.

Stage 3 — Map the diff onto the repo

The three source trees have completely different exposure. Don't treat them alike:

• Bucket 1 — grep the affected symbols under packages/plugin/src/ (handlers, serializer.ts, traverse.ts, reveal.ts). Confirm with Stage 4 rather than reasoning about it.
• Bucket 3 — for each added field, check whether the Zod mirror in packages/shared/src/ carries it, and whether serializer.ts or handlers/get-design-context.ts projects it. A miss here is a real fidelity gap with every gate green.
• Bucket 2 — check coverage against packages/mcp/src/tools/registry.ts (ALL_TOOL_SPECS is the authority on the tool count; prose in READMEs is hand-written and stale).

Stage 4 — Sandbox typecheck (only if Stage 2 found bucket 1)

Type-check the real sandbox sources against the new typings without touching the repo. Never overwrite the copy in node_modules — pnpm hard-links it into the global store, so writing there corrupts the store for every project on the machine.

Write $SCRATCH/typings-audit/tsconfig.probe.json:

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": []
  },
  "files": ["./<target>/index.d.ts"],
  "include": [
    "<REPO_ROOT>/packages/plugin/src/**/*.ts",
    "<REPO_ROOT>/packages/plugin/protocol/**/*.ts"
  ]
}

Expand <REPO_ROOT> to git rev-parse --show-toplevel — the tsconfig lives outside the repo, so those entries have to be absolute. Never hard-code a machine-specific path into a committed file.

types: [] keeps the installed (old) typings out; the files entry pulls the new ones in via its /// <reference path="./plugin-api.d.ts" />. Module resolution still works because it is anchored to each source file's own location, not to the tsconfig's.

./node_modules/.bin/tsc -p "$SCRATCH/typings-audit/tsconfig.probe.json"

Run the same probe against the installed version first. A clean baseline is what makes a failure on the new version mean something.