/figma-typings-audit

name: figma-typings-audit
description: 'Upgrade @figma/plugin-typings and absorb what the new version exposes. Diffs the .d.ts between the installed and the target version (that package ships no changelog), sorts the changes into breakage / new API / silently-added fields, maps each onto the sandbox handlers, the hand-written Zod mirrors in shared, and the tool registry — then bumps the package and builds whatever the user picks. Use whenever the user wants @figma/plugin-typings updated or audited, or asks what a new plugin-typings version would break or newly enable — including a Renovate bump PR for that package.'

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:

| Tree | Coupling to typings