Add Layer Compositing Cache architecture for improved performance

[softmarshmallow]

• Introduced a new section on Layer Compositing Cache, replacing the global tile-based raster caching strategy.
• Detailed the advantages of layer-based compositing over tile-based caching, addressing issues like pixel bleeding and animation inefficiencies.
• Provided a comprehensive architecture overview, including promotion heuristics and effect cacheability classification to optimize rendering performance.
• Enhanced documentation with flowcharts and tables to clarify the caching process and decision-making for node promotion.

These changes significantly improve the optimization techniques for high-performance rendering in design tools.

Summary by CodeRabbit

• New Features

  • Per-node layer compositing with GPU atlas, render-surface architecture, and camera-change detection to improve pan/zoom performance.
  • Interaction render-scale control for smoother interactive frames.

• Chores

  • Runtime API renamed for layer compositing.
  • Added extensive performance benchmarks, examples, and documentation.

• Breaking / Removals

  • Figma import path removed.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
backgrounds	Ready	Preview, Comment	Mar 16, 2026 4:40pm
blog	Ready	Preview, Comment	Mar 16, 2026 4:40pm
docs	Ready	Preview, Comment	Mar 16, 2026 4:40pm
grida	Ready	Preview, Comment	Mar 16, 2026 4:40pm
viewer	Ready	Preview, Comment	Mar 16, 2026 4:40pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
code	Ignored		Mar 16, 2026 4:40pm
legacy	Ignored		Mar 16, 2026 4:40pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR replaces tile-based raster caching with a layer-based GPU compositing pipeline: it renames the runtime API from runtime_renderer_set_cache_tile → runtime_renderer_set_layer_compositing, removes the tile cache and overlays, and adds atlas packing, a per-node compositor cache, effect-tree render-surface logic, renderer changes, benchmarks, and docs.

Changes

Cohort / File(s)	Summary
API Renaming: Cache → Compositing crates/grida-canvas-wasm/lib/__test__/environment-node-api-spec-validation.test.ts, crates/grida-canvas-wasm/lib/modules/canvas-bindings.d.ts, crates/grida-canvas-wasm/lib/modules/canvas.ts, crates/grida-canvas-wasm/src/wasm_application.rs, crates/grida-canvas/src/window/application.rs, crates/grida-canvas/src/window/application_emscripten.rs, editor/grida-canvas/editor.ts	Renamed exported runtime API and tests from runtime_renderer_set_cache_tile to runtime_renderer_set_layer_compositing and updated callers/FFI/TS declarations.
Atlas Infrastructure crates/grida-canvas/src/cache/atlas/packing.rs, crates/grida-canvas/src/cache/atlas/atlas.rs, crates/grida-canvas/src/cache/atlas/atlas_set.rs, crates/grida-canvas/src/cache/atlas/mod.rs	Adds shelf-based atlas packer, AtlasPage with slot allocation/drawing/snapshot, and AtlasSet multi-page management and stats.
Compositor Cache System crates/grida-canvas/src/cache/compositor/cache.rs, crates/grida-canvas/src/cache/compositor/invalidation.rs, crates/grida-canvas/src/cache/compositor/promotion.rs, crates/grida-canvas/src/cache/compositor/mod.rs	Introduces LayerImageCache (individual/atlas-backed sources), invalidation events/handler, promotion heuristics, and public cache stats/APIs.
Render-Surface & Painter Changes crates/grida-canvas/src/painter/layer.rs, crates/grida-canvas/src/painter/painter.rs	Adds PainterRenderSurface and RenderSurface command, implements effect-isolated offscreen surfaces, draw path for surfaces, promoted-skip, and LOD reductions for interactive frames.
Effect Tree & Scene Cache crates/grida-canvas/src/runtime/effect_tree.rs, crates/grida-canvas/src/cache/scene.rs, crates/grida-canvas/src/node/schema.rs	Adds EffectTree to classify render-surface needs; replaces tile cache with compositor cache in SceneCache; adds Node helper methods (opacity, blend_mode, effects, container checks).
Runtime Config & Camera crates/grida-canvas/src/runtime/config.rs, crates/grida-canvas/src/runtime/camera.rs, crates/grida-canvas/src/runtime/render_policy.rs	Replaces cache_tile with layer_compositing, compositor_atlas, interaction_render_scale; adds CameraChangeKind and effect quality controls; renames allows_tile_cache → allows_layer_compositing.
Renderer & Frame Flow crates/grida-canvas/src/runtime/scene.rs	Extends FramePlan with camera_change and promoted nodes; adds compositor_surface, compositor_atlas, downscale surfaces; updates frame/draw planning, compositor update, invalidation, and metrics reporting.
Removed Tile Infrastructure & Devtools Overlay crates/grida-canvas/src/cache/tile.rs, crates/grida-canvas/src/devtools/tile_overlay.rs, crates/grida-canvas/src/devtools/mod.rs	Removes ImageTileCache, tile-related types and logic, and tile overlay devtool module and references.
Cache Module Restructuring crates/grida-canvas/src/cache/mod.rs	Adds atlas and compositor modules; removes tile module from public exports.
Compositor Integration: Scene & Invalidation crates/grida-canvas/src/cache/compositor/*, crates/grida-canvas/src/cache/atlas/*	Wires new atlas and compositor cache into scene/renderer flows and provides invalidation primitives.
Benchmarks & Examples crates/grida-canvas/benches/bench_pan.rs, crates/grida-canvas/examples/headless_gpu.rs, crates/grida-canvas/examples/skia_bench/...	Adds headless GPU/skia microbenchmarks (pan/zoom, primitives, effects, atlas, downscale, opacity) and corresponding docs/README.
Fixture Helpers & Tooling crates/grida-canvas/examples/fixture_helpers/mod.rs, crates/grida-canvas/examples/fixtures/mod.rs, crates/grida-canvas/examples/tool_gen_bench_fixture.rs, crates/grida-canvas/examples/tool_gen_fixtures.rs	Extracts and centralizes fixture builders, scene encoders, ZIP wrapper, paint/node helpers, and bench fixture generator.
Developer CLI & Native App crates/grida-dev/src/main.rs, crates/grida-dev/src/platform/native_application.rs, crates/grida-dev/Cargo.toml, crates/grida-dev/examples/wd_windowed_mode.rs	Adds headless Bench CLI command and bench args, removes Figma bench paths, simplifies camera fitting to renderer API, and updates example to enable layer compositing.
IO & Figma Removal crates/grida-canvas/src/io/io_figma.rs, crates/grida-canvas/src/io/mod.rs, crates/grida-dev/Cargo.toml, crates/grida-canvas/Cargo.toml	Removes Figma IO module and feature gating; removes figma API dependency and related features; adjusts Cargo manifests.
Verification & IO tweaks crates/grida-canvas/src/io/io_grida_fbs.rs	Uses FlatBuffer root_with_opts with increased VerifierOptions (max_tables, max_depth) for decoding.
Docs & Research docs/wg/feat-2d/optimization.md, docs/wg/research/chromium/*, crates/grida-canvas/AGENTS.md, crates/grida-dev/AGENTS.md, crates/grida-canvas/examples/skia_bench/BENCHMARK.md	Large documentation additions: render-surface architecture, optimization guidance, and extensive Chromium compositor research notes plus benchmarking guidance.
Dev Notes & Minor crates/grida-canvas-wasm/package.json, crates/grida-canvas/Cargo.toml, crates/grida-canvas/CHANGELOG.md, various README/AGENTS files`	Bumped wasm package version, added zip dev-dep, added bench/example entries, removed figma references and adjusted READMEs/CHANGELOG.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant Renderer as Renderer
    participant SceneCache as SceneCache
    participant Compositor as Compositor (LayerImageCache)
    participant Atlas as AtlasSet
    participant GPU as GPU Surface

    App->>Renderer: frame(bounds, zoom, stable)
    Renderer->>SceneCache: build/get EffectTree
    SceneCache-->>Renderer: EffectNode list
    Renderer->>Renderer: compute camera_change
    alt zoom changed
        Renderer->>Compositor: invalidate_all()
    end
    alt stable frame
        Renderer->>Compositor: request promoted nodes
        Compositor-->>Renderer: Vec<NodeId>
        Renderer->>Renderer: build FramePlan(promoted)
    else unstable frame
        Renderer->>Renderer: FramePlan(empty promoted)
    end
    Renderer->>Renderer: draw(canvas, plan)
    Renderer->>Compositor: update_compositor(parent_surface)
    loop each promoted node
        Compositor->>Atlas: get_image_and_src_rect(node_id)
        alt atlas-backed
            Atlas-->>Compositor: (image, src_rect)
            Compositor->>GPU: blit image(src_rect)
        else individual
            Compositor-->>Compositor: use individual image
            Compositor->>GPU: blit image
        end
    end
    loop live (non-promoted) nodes
        Renderer->>Renderer: process PainterRenderCommand
        alt RenderSurface needed
            Renderer->>GPU: draw offscreen surface and apply effects
        else direct draw
            Renderer->>GPU: draw commands
        end
    end
    Renderer-->>App: return DrawResult (cache metrics, timings)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Grida Canvas - skia-safe rust backend - standalone performance testing #383: Original tile-cache and tile-overlay subsystems that are removed/replaced by this PR (strong overlap in removed code and tests).
• Grida Canvas - Layout (prep) - Scene Graph #432: Scene-graph and node structure changes that interact with the new EffectTree and scene cache APIs.
• [Grida Canvas] Paragraph - Texts & Fonts #415: WASM/JS canvas bindings touching the same exported runtime function that was renamed in this PR.

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

crates/grida-canvas/Cargo.toml (1)

4-4: ⚠️ Potential issue | 🟡 Minor

Update edition to "2024" per coding guidelines.

The crate uses edition "2021", but the coding guidelines require Rust 2024 edition for crates in crates/**/Cargo.toml.

Proposed fix

-edition = "2021"
+edition = "2024"

As per coding guidelines: "Use Rust 2024 edition for crates".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@crates/grida-canvas/Cargo.toml` at line 4, Update the crate's Cargo.toml
edition setting from edition = "2021" to edition = "2024": locate the edition
field (edition = "2021") in the Cargo.toml for the grida-canvas crate and change
its value to "2024" so the crate uses the Rust 2024 edition per guidelines;
ensure no other Cargo.toml files are inadvertently altered and run a quick build
to verify compatibility.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@crates/grida-canvas/Cargo.toml`:
- Line 4: Update the crate's Cargo.toml edition setting from edition = "2021" to
edition = "2024": locate the edition field (edition = "2021") in the Cargo.toml
for the grida-canvas crate and change its value to "2024" so the crate uses the
Rust 2024 edition per guidelines; ensure no other Cargo.toml files are
inadvertently altered and run a quick build to verify compatibility.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0d5f9722-a3fe-40e8-94ff-3029f0231a06

📥 Commits

Reviewing files that changed from the base of the PR and between 7c8cd0f and cf52692.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (6)

• crates/OPTIMIZATION_SIZE.md
• crates/grida-canvas/CHANGELOG.md
• crates/grida-canvas/Cargo.toml
• crates/grida-canvas/README.md
• crates/grida-canvas/src/io/io_figma.rs
• crates/grida-canvas/src/io/mod.rs

💤 Files with no reviewable changes (5)

• crates/grida-canvas/src/io/mod.rs
• crates/grida-canvas/CHANGELOG.md
• crates/grida-canvas/README.md
• crates/grida-canvas/src/io/io_figma.rs
• crates/OPTIMIZATION_SIZE.md