Skip to content

feat: fetch multiple Figma nodes in one get_figma_data call - #404

Open
GLips wants to merge 4 commits into
mainfrom
advisor/003-multi-node-fetch
Open

feat: fetch multiple Figma nodes in one get_figma_data call#404
GLips wants to merge 4 commits into
mainfrom
advisor/003-multi-node-fetch

Conversation

@GLips

@GLips GLips commented Jun 24, 2026

Copy link
Copy Markdown
Owner

What this enables

get_figma_data can now fetch several top-level nodes in a single call by passing comma-separated ids (nodeId: "1:2,3:4"). Previously, assembling a multi-frame design meant one tool call per node — more round-trips, more latency, more tokens spent re-sending the file context each time. The LLM driving the tool can now grab every frame it needs at once.

Two audiences benefit:

  • Tool callers (LLMs / end users): multi-node fetch in one request; and on a partial miss (some ids resolve, some don't) the result now carries a MISSING_NODES marker so the model knows it's working from an incomplete design instead of silently assuming it got everything.
  • Developers in this code: parseAPIResponse is no longer a two-branch mutation bag — both API response shapes (full-file and by-nodes) normalize into a common slice list and aggregate declaratively. This PR also lands the FigmaService characterization tests that lock down the request/error path the feature exercises.

Why now

The Figma REST API's nodes?ids= endpoint has always accepted a comma-separated list, but the parser only ever read the first node and dropped the rest. The same line also crashed with a raw TypeError when the API returned an empty nodes object — bypassing the friendly not-found guidance one line below it. This is a captured, grounded request (docs/ideas/multi-node-fetch.md), and the fix for "only reads the first node" is the same edit that removes the crash.

What reviewers should know

  • Bundles two advisor plans: the FigmaService request/error characterization tests (the safety net for the request layer) plus the multi-node feature itself. Squash-merges to one commit on main.
  • getRawNode is deliberately untouched — it already passes the ids string straight through to the API, so no change was needed at the request layer.
  • Cross-node dedup was the main correctness risk and it's verified. Style hoisting and element templating run over the combined forest (one shared globalVars/traversalState), so a style or subtree shared between two separately-requested nodes is counted across both and elevated once — the same machinery that already deduped across a full file's top-level frames. Tests cover the shared-hoist, single-use-inline, and cross-root-template cases.
  • Partial-miss handling: unresolved ids are skipped (not fatal) as long as at least one node resolves; only an all-miss or empty response raises the tagged not_found error. The skipped ids are logged server-side and surfaced to the caller.
  • Out of scope (intentionally): no change to the output wrapper shape beyond the optional missingNodeIds/MISSING_NODES field, and download_figma_images keeps its own single-node regex (it takes an array, not a comma scalar).

Reviewed for correctness across two independent passes (incl. a cross-model audit); full suite, type-check, and lint green.

GLips added 4 commits June 24, 2026 10:22
Normalize both API response shapes into a common slice list so
parseAPIResponse aggregates roots/components/styles declaratively, and
make the metrics pass (countNamedStyles, detectVariables) skip null node
entries so a partial miss (some ids resolve, some don't) no longer
crashes with a TypeError after simplify. Also surface skipped ids via
Logger, tighten the nodeId regex grammar, and add cross-node dedup +
partial-miss regression tests.
A multi-node fetch where some ids resolve and others don't previously
only logged the gap server-side, so the LLM could act on an incomplete
design as if it were complete. Carry missingNodeIds onto SimplifiedDesign
(present only when non-empty, so the common case costs no tokens) and
render a MISSING_NODES line in the tree format; YAML/JSON pick it up via
metadata.
@GLips
GLips force-pushed the advisor/003-multi-node-fetch branch from c2968c0 to 5637d60 Compare June 24, 2026 17:23
@GLips
GLips changed the base branch from advisor/002-figma-service-tests to main June 24, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant