Grida Canvas - IO Figma Fixes & Improvements by softmarshmallow · Pull Request #481 · gridaco/grida

softmarshmallow · 2025-12-24T05:59:49Z

Release Notes

New Features
- Improved component and instance copying from Figma with enhanced payload handling
- Support for component instance flattening
Bug Fixes
- Fixed vector coordinate mapping for proper size normalization scaling
- Enhanced root-level property overrides for copied instances
Documentation
- Expanded clipboard payload structure documentation for components and variants
- Added vector network coordinate mapping guidance
Tests
- Comprehensive clipboard tests for components, instances, and variant scenarios
- Vector scaling and override preservation verification tests

…ing observed patterns and structures

vercel · 2025-12-24T05:59:54Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Dec 24, 2025 7:11am
grida	Ready	Preview, Comment	Dec 24, 2025 7:11am

5 Skipped Deployments

Project	Deployment	Updated (UTC)
code	Ignored	Dec 24, 2025 7:11am
legacy	Ignored	Dec 24, 2025 7:11am
backgrounds	Skipped	Dec 24, 2025 7:11am
blog	Skipped	Dec 24, 2025 7:11am
viewer	Skipped	Dec 24, 2025 7:11am

coderabbitai · 2025-12-24T05:59:56Z

Walkthrough

This PR enhances the Figma clipboard import pipeline by introducing buildClipboardRootNodes to streamline clipboard-to-root node conversion, adds vector network scaling for normalizedSize coordinate space mapping, and implements instance flattening via a new BuildTreeOptions configuration. Includes stroke support for instances and frames, root-level symbol overrides handling, and comprehensive fixture-based tests for clipboard scenarios.

Changes

Cohort / File(s)	Summary
Documentation `docs/wg/feat-fig/glossary/fig.kiwi.md`	Adds observed patterns for component sets in clipboard payloads (frame structure, variant copying behavior), detailed notes on vector node coordinate mapping from `vectorData.normalizedSize` space to node space, and documented VectorNetwork structure.
Documentation `fixtures/test-fig/clipboard/README.md`	Expands clipboard fixtures README with component/instance payload structure documentation, component set representation rules, copy scenarios for container/component/instance variants, and group-to-frame behavior detection logic.
Examples `editor/grida-canvas-hosted/playground/examples.ts`	Adds new canvas example entry for "Happy New Year 2026" poster.
Canvas Data Transfer `editor/grida-canvas-react/use-data-transfer.ts`	Refactors clipboard conversion pipeline to use single `iofigma.kiwi.buildClipboardRootNodes` call instead of manual NodeChanges reconstruction; updates error messaging for unsupported nodes.
Core Library - Figma IO `packages/grida-canvas-io-figma/lib.ts`	Introduces `BuildTreeOptions` type with `flattenInstances` flag; adds `buildClipboardRootNodes` function for streamlined root extraction; implements vector network scaling via `scaleVectorNetworkFromNormalizedSize`; adds stroke trait support for instances/frames; handles root-level symbol overrides; extends `parseFile` signatures to accept options; updates `convertPageToScene` with shared `node_id_generator` for collision avoidance.
Tests - Clipboard Components `packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts`	Tests root resolution for component definitions and instances, verifying correct node types and exclusion of internal SYMBOL masters.
Tests - Clipboard Overrides `packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts`	Tests symbol override extraction and preservation on root instances; validates fill/stroke paint counts match override specifications.
Tests - Clipboard Text Overrides `packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts`	Tests TEXT node overrides within instance symbol overrides; verifies text content replacement when `flattenInstances` is enabled.
Tests - Vector Network `packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts`	Regression test for vector network scaling; validates bounding box alignment when mapping from `normalizedSize` space to node size space.
Tests - Root Merging `packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.fig.test.ts`	Regression test ensuring multiple root frames are preserved during scene conversion without node ID collisions.
Clipboard Fixtures `fixtures/test-fig/components.fig`	Updated git-lfs pointer (oid and size changed).
Clipboard Fixtures `fixtures/test-fig/clipboard/component-\.clipboard.html` (13 files)	HTML clipboard fixture files for testing component definitions, instances, and component set variants in blue/red scenarios with and without overrides.

Sequence Diagram

sequenceDiagram
    participant User
    participant Canvas as Canvas UI
    participant Transfer as use-data-transfer
    participant Kiwi as iofigma.kiwi
    participant Factory as factory.node
    participant Scene as Insertable Scene

    User->>Canvas: Paste component/instance
    Canvas->>Transfer: onDataTransfer (HTML clipboard)
    Transfer->>Transfer: readHTMLMessage()
    Transfer->>Kiwi: buildClipboardRootNodes({<br/>  nodeChanges,<br/>  message,<br/>  options: {flattenInstances}})
    
    rect rgb(200, 220, 240)
        Note over Kiwi,Factory: Root Building Process
        Kiwi->>Kiwi: Build GUID maps
        Kiwi->>Kiwi: Attach children by parentIndex
        alt flattenInstances = true
            Kiwi->>Kiwi: Inline SYMBOL subtrees
            Kiwi->>Factory: Create flattened instances
            Factory->>Factory: Apply symbol overrides
            Factory->>Factory: Scale vector networks<br/>(normalizedSize → node space)
            Factory-->>Kiwi: Return processed nodes
        else flattenInstances = false
            Kiwi-->>Kiwi: Return root structure as-is
        end
    end
    
    Kiwi-->>Transfer: rootNodes[]
    Transfer->>Transfer: Validate roots found
    Transfer->>Scene: Insert root nodes
    Scene-->>Canvas: Nodes added to scene

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The PR introduces substantial new functionality across the Figma IO library with heterogeneous changes: core library refactoring with new types and functions, vector scaling logic, instance flattening implementation, clipboard conversion pipeline changes, and an extensive fixture/test suite. Logic density is moderate-to-high in lib.ts, spanning symbol overrides, vector network transformations, and tree building with multiple configuration options.

Possibly related PRs

Copy-Paste from Figma #457 — Directly related through parallel iofigma/fig-kiwi clipboard and node-conversion code changes, including factory utilities and buildClipboardRootNodes implementation.
Daily RC #461 — Modifies the same clipboard pipeline, iofigma factory methods, and adds overlapping clipboard/instance handling tests and fixtures.
schema_version 0.0.3-beta+20251202 Towards all system wide snake_case schema #456 — Related through vector network and clipboard import machinery changes, including vectorNetwork field handling and iofigma output updates.

Suggested labels

canvas/io

Poem

🐰 A Kiwi clipboard now flows so clean,
Building roots through the Figma scene,
Instances flatten, vectors scale true,
Overrides nested, all symbols pass through! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 61.90% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.
Title check	❓ Inconclusive	The title 'Grida Canvas - IO Figma Fixes & Improvements' is vague and generic, using non-descriptive terms like 'Fixes & Improvements' that don't convey meaningful information about the specific changeset.	Use a more specific title that highlights the primary change, such as 'Add clipboard root node building and vector network scaling' or 'Implement instance flattening and vector network support for clipboard operations'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch canary

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…including support for root-level overrides and flattening instances

…ing capabilities

… and scaling implications for Figma nodes

…zed size to improve rendering accuracy

…as file

chatgpt-codex-connector · 2025-12-24T07:08:24Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (5)

packages/grida-canvas-io-figma/lib.ts (3)

1952-2025: Root-level symbolOverrides patching for instances is minimal but well-scoped

The new instance construction:

Builds a full InstanceNode once and then conditionally applies a “root patch” when the first symbolOverrides entry lacks guid/type/parentIndex, which matches the clipboard payloads you’re targeting.

Avoids touching targeted overrides (with guid), which are instead consumed later by flattenInstancesInPlace via symbolOverrideByGuid.

This strikes a good balance between fixing real clipboard cases and not over-implementing the full override system prematurely. The inline TODO(kiwi-overrides) is accurate and keeps expectations clear.

2057-2117: Vector network scaling hook in vectorNode is correct and matches the new tests

Wiring parseVectorNetworkBlob through scaleVectorNetworkFromNormalizedSize before emitting an X_VECTOR node:

Uses normalizedSize and size to compute per-axis scale factors and applies them uniformly to vertices and tangents.

Falls back to scale 1 when either dimension is missing or zero, which is safe and predictable.

Preserves the old VECTOR fallback path (with empty path strings) when no blob is available, so existing behavior is unchanged there.

The new vector-network test exercises this path and should catch regressions in the coordinate-space mapping.

2298-2637: Instance flattening and clipboard/page tree builders are thoughtfully structured

The new BuildTreeOptions + helpers (buildGuidToKiwiMap, buildFlatFigmaNodes, buildChildrenRelationsInPlace, flattenInstancesInPlace, buildClipboardRootNodes, buildCanvasRootNodes) form a coherent pipeline:

Building flat REST/IR nodes once and reusing guidToNode / guidToKiwi avoids repeated conversion.

Child attachment via parentIndex.guid + lexicographic position sorting mirrors Figma’s ordering model.

flattenInstancesInPlace + cloneTreeWithNewIdsAndFlattenInstances properly:

Inline component trees for INSTANCEs when flattenInstances is enabled.

Guard against component cycles via componentStack.

Apply targeted overrides by guid during cloning, while preserving root-level patches applied in instance().

The clipboard builder also correctly excludes children of internal-only canvases from the roots, treating those canvases as a component repository.

If you later need full override semantics (swaps, nested instance overrides, non-paint fields), you already have clear extension points and TODOs.

editor/grida-canvas-react/use-data-transfer.ts (1)

177-183: Centralized clipboard root-building looks correct and simplifies this path

Using iofigma.kiwi.buildClipboardRootNodes with { nodeChanges, message: parsed.message, options: { flattenInstances: true } } cleanly replaces the bespoke root-detection logic, and the updated error message gives much better feedback (total nodes vs insertable roots). No functional issues spotted; this should also keep behavior aligned with the shared iofigma build pipeline going forward.

Also applies to: 185-189

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts (1)

5-8: Consider tracking the fixture replacement as technical debt.

The comment correctly identifies that this test uses handcrafted/mocked data instead of a real Figma clipboard fixture. While the test validates the override logic in isolation, it would be more robust with a real-world fixture.

Do you want me to open an issue to track adding a real clipboard fixture with text overrides? This would ensure the test validates against actual Figma clipboard format.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 30f479c and 27d12d2.

📒 Files selected for processing (26)

docs/wg/feat-fig/glossary/fig.kiwi.md
editor/grida-canvas-hosted/playground/examples.ts
editor/grida-canvas-react/use-data-transfer.ts
editor/public/examples/canvas/poster-happy-new-year-2026.grida
fixtures/test-fig/L0/components.fig
fixtures/test-fig/clipboard/README.md
fixtures/test-fig/clipboard/component-component-blue.clipboard.html
fixtures/test-fig/clipboard/component-component-instance-blue-with-overrides.clipboard.html
fixtures/test-fig/clipboard/component-component-instance-blue.clipboard.html
fixtures/test-fig/clipboard/component-component-instance-red-with-overrides.clipboard.html
fixtures/test-fig/clipboard/component-component-instance-red.clipboard.html
fixtures/test-fig/clipboard/component-component-red.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-blue.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-instance-blue-with-overrides.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-instance-blue.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-instance-red-with-overrides.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-instance-red.clipboard.html
fixtures/test-fig/clipboard/component-component-set-component-red.clipboard.html
fixtures/test-fig/clipboard/component-component-set.clipboard.html
fixtures/test-fig/clipboard/frame-with-stroke.clipboard.html
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.fig.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts
packages/grida-canvas-io-figma/lib.ts

🧰 Additional context used

📓 Path-based instructions (6)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx}: Use TypeScript 5 as the main language for most apps
Use Lucide or Radix Icons for icons

Files:

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts
editor/grida-canvas-hosted/playground/examples.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts
editor/grida-canvas-react/use-data-transfer.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.fig.test.ts
packages/grida-canvas-io-figma/lib.ts

{editor/**/*.{ts,tsx},packages/grida-canvas-*/**/*.{ts,tsx}}

📄 CodeRabbit inference engine (AGENTS.md)

Use DOM (plain DOM as canvas) for website builder canvas, bound with React

Files:

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts
editor/grida-canvas-hosted/playground/examples.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts
editor/grida-canvas-react/use-data-transfer.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.fig.test.ts
packages/grida-canvas-io-figma/lib.ts

packages/grida-canvas-*/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Packages under /packages/grida-canvas-* power the canvas; some are published to npm, refer to individual package README

Files:

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts
packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.fig.test.ts
packages/grida-canvas-io-figma/lib.ts

docs/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Documentation source of truth is in the ./docs directory; deployment is handled by apps/docs

Files:

docs/wg/feat-fig/glossary/fig.kiwi.md

docs/{wg,reference}/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Only actively maintain docs/wg/** and docs/reference/** directories; see docs/AGENTS.md for contribution scope

Files:

docs/wg/feat-fig/glossary/fig.kiwi.md

editor/grida-*/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use /editor/grida-* directories to isolate domain-specific modules; promote well-defined modules to /packages

Files:

editor/grida-canvas-hosted/playground/examples.ts
editor/grida-canvas-react/use-data-transfer.ts

🧠 Learnings (7)

📓 Common learnings

Learnt from: CR
Repo: gridaco/grida PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-14T23:30:42.112Z
Learning: Applies to packages/grida-canvas-*/**/*.{ts,tsx,js,jsx} : Packages under /packages/grida-canvas-* power the canvas; some are published to npm, refer to individual package README

Learnt from: CR
Repo: gridaco/grida PR: 0
File: crates/grida-canvas/AGENTS.md:0-0
Timestamp: 2025-12-20T08:11:16.201Z
Learning: Applies to crates/grida-canvas/**/*.grida : Validate .grida files using the `tool_io_grida` CLI tool to check file structure, parse all nodes, and detect parsing errors

Learnt from: CR
Repo: gridaco/grida PR: 0
File: crates/grida-canvas/AGENTS.md:0-0
Timestamp: 2025-12-20T08:11:16.201Z
Learning: Applies to crates/grida-canvas/**/*.rs : Run `cargo fmt` to maintain code formatting standards

📚 Learning: 2025-12-01T00:22:19.083Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: crates/grida-canvas-wasm/AGENTS.md:0-0
Timestamp: 2025-12-01T00:22:19.083Z
Learning: Applies to crates/grida-canvas-wasm/**/main.rs : Update `grida-canvas-wasm.d.ts` TypeScript definitions file when new APIs are introduced via `main.rs`

Applied to files:

editor/grida-canvas-hosted/playground/examples.ts
packages/grida-canvas-io-figma/lib.ts

📚 Learning: 2025-12-14T23:30:42.112Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-14T23:30:42.112Z
Learning: Applies to packages/grida-canvas-*/**/*.{ts,tsx,js,jsx} : Packages under /packages/grida-canvas-* power the canvas; some are published to npm, refer to individual package README

Applied to files:

editor/grida-canvas-hosted/playground/examples.ts
packages/grida-canvas-io-figma/lib.ts

📚 Learning: 2025-12-14T23:30:42.112Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-14T23:30:42.112Z
Learning: Applies to {editor/**/*.{ts,tsx},packages/grida-canvas-*/**/*.{ts,tsx}} : Use DOM (plain DOM as canvas) for website builder canvas, bound with React

Applied to files:

editor/grida-canvas-react/use-data-transfer.ts

📚 Learning: 2025-12-01T00:22:56.899Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: editor/app/(tools)/tools/halftone/AGENTS.md:0-0
Timestamp: 2025-12-01T00:22:56.899Z
Learning: Applies to editor/app/(tools)/tools/halftone/app/(tools)/tools/halftone/_page.tsx : When adding new shape types, update the Shape type union, add cases in drawShape() function, add cases in shapeToSVG() function, and add SelectItem in UI

Applied to files:

packages/grida-canvas-io-figma/lib.ts

📚 Learning: 2025-12-01T00:22:56.899Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: editor/app/(tools)/tools/halftone/AGENTS.md:0-0
Timestamp: 2025-12-01T00:22:56.899Z
Learning: Applies to editor/app/(tools)/tools/halftone/app/(tools)/tools/halftone/_page.tsx : Use Canvas 2D API with path commands for rendering geometric shapes (circle, square, triangle, etc.)

Applied to files:

packages/grida-canvas-io-figma/lib.ts

📚 Learning: 2025-12-01T00:22:56.899Z

Learnt from: CR
Repo: gridaco/grida PR: 0
File: editor/app/(tools)/tools/halftone/AGENTS.md:0-0
Timestamp: 2025-12-01T00:22:56.899Z
Learning: Applies to editor/app/(tools)/tools/halftone/app/(tools)/tools/halftone/_page.tsx : For SVG export, convert circles to <circle> elements, rectangles to <rect> elements, and polygons to <polygon> elements with calculated points

Applied to files:

packages/grida-canvas-io-figma/lib.ts

🧬 Code graph analysis (5)

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.vector-network.test.ts (2)

packages/grida-canvas-io-figma/fig-kiwi/index.ts (2)

readFigFile (250-283)

getBlobBytes (344-351)

packages/grida-canvas-io-figma/index.ts (1)

iofigma (7-7)

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-overrides.test.ts (3)

editor/eslint.config.mjs (1)

__dirname (6-6)

packages/grida-canvas-io-figma/index.ts (1)

iofigma (7-7)

crates/grida-canvas/src/node/scene_graph.rs (1)

roots (206-208)

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-text-overrides.test.ts (2)

crates/grida-canvas/src/node/scene_graph.rs (1)

roots (206-208)

packages/grida-canvas-io-figma/index.ts (1)

iofigma (7-7)

packages/grida-canvas-io-figma/__tests__/iofigma.kiwi.clipboard-components.test.ts (3)

editor/eslint.config.mjs (1)

__dirname (6-6)

crates/grida-canvas/src/node/scene_graph.rs (1)

roots (206-208)

packages/grida-canvas-io-figma/index.ts (1)

iofigma (7-7)

packages/grida-canvas-io-figma/lib.ts (3)

packages/grida-canvas-schema/grida.ts (1)

NodeChange (1319-1319)

crates/grida-canvas/src/painter/layer.rs (1)

paints (220-224)

packages/grida-canvas-io-figma/fig-kiwi/index.ts (2)

readFigFile (250-283)

ParsedFigmaArchive (82-85)

🪛 Gitleaks (8.30.0)

fixtures/test-fig/clipboard/component-component-set-component-blue.clipboard.html