/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 -u <installed>/plugin-api.d.ts <target>/plugin-api.d.ts > api.diff
wc -l api.diff

Diff **`plugin-api.d.ts`**, not `plugin-api-standalone.d.ts` — `packages/plugin/tsconfig.json` sets `types: ["@figma/plugin-typings"]`, whose `index.d.ts` references the former.

Also diff `index.d.ts` (it declares the `figma` global, `fetch`, timers) — small, but high blast radius.

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 | Who catches a break | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `packages/plugin/src/**` | **Real.** The only tree that calls `figma.*` and loads the global types (`tsconfig.json` → `types: ["@figma/plugin-typings"]`) | `tsc` | | `packages/plugin/ui/**` | None — the Vue panel never touches the Figma API | n/a, skip | | `packages/shared/src/**` | ★ **None — and that's the trap.** `serialized-node.ts`, `styles.ts`, `queries.ts` are *hand-written Zod mirrors* of Figma shapes; `shared/tsconfig.json` never loads typings | **Nobody but this audit** |

• **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 t