editor-perf

---
name: editor-perf
description: Guides performance investigation, benchmarking, and optimization of the Grida Canvas web editor (TypeScript reducer, Immer, React hooks). Use when profiling reducer dispatch cost, diagnosing slow interactions (drag, resize, color change), writing or running editor benchmarks, instrumenting with PerfObserver, or optimizing the JS-side state management pipeline.
---

# Grida Canvas Editor — Performance Development

Workflow and reasoning framework for performance work on the
**TypeScript editor pipeline** — the reducer, Immer state management,
React subscription layer, and headless benchmarks.

> **Scope boundary:** This skill covers the **JS/TS editor** pipeline
> (`editor/grida-canvas/`). For the **Rust rendering engine** (the
> `grida` crate), use the engine repo's render-perf skill:
> https://github.com/gridaco/nothing/blob/main/.agents/skills/render-perf/SKILL.md.
> The two pipelines are connected — a dispatch in JS may trigger a WASM
> re-render — but they are profiled with different tools, in different repos.

> **Maintaining this document:** If you notice a section that has gone
> stale (e.g. a workflow step no longer matches the code, a discovery
> query returns nothing, or a pitfall has been resolved), update this
> `SKILL.md` as part of your current task. Keep it high-level —
> reference patterns and categories rather than specific function names
> or measured numbers, which change frequently.

## When to Use This Skill

- Benchmarking or profiling editor reducer operations
- Diagnosing slow interactions (drag, resize, color picker, opacity slider)
- Investigating Immer overhead or state cloning costs
- Instrumenting code with `PerfObserver` spans
- Writing or running the editor bench
- Optimizing queries, snap targets, hover resolution
- Reducing React re-render cost from editor state subscriptions

---

## Pick your measurement tool

Performance work starts with the right signal. The three tools below are
complementary — do not skip the browser trace if the user offers one,
do not open a browser for a reducer-only regression.

| Tool                                            | Use when                                                                                                               | What it catches                                                                                        | What it misses                              |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| **Browser trace (Chrome DevTools Performance)** | User provided a `.json.gz` trace, or the symptom is interaction-level (drag/nudge feels laggy). **This is the truth.** | Everything on the main thread: React, selector cost, paint, compositor, GC, WASM, reducer, Immer, RAF. | Not reproducible without the user's session |
| **editor-bench** (automated)                    | Default for proactive investigation and A/B of a reducer / encode / WASM change. No user input needed.                 | `PerfObserver` span table, per-scene (1K / 10K). Deterministic and comparable across runs.             | React render cost, DOM overlays, real RAF   |
| **Node CPU profile**                            | A bench span points at a hotspot but you need function-level detail inside it, or microtask timing.                    | Function self-time and call chains within a single Node process.                                       | Browser-only code paths                     |

### Decision rules

1. **If the user provides a browser trace, start there.** It already has
   React, DevTools, and WASM on the same timeline — quote actual
   numbers from the trace rather than guessing. Parse it as JSON
   (see "Reading a browser trace" below).
2. **Otherwise run the bench first.** No user input needed — it covers
   every scenario at 1K and 10K and emits a `PerfObserver` span table
   that's directly comparable across runs.
3. **Once bench points at a span, drill with a Node CPU profile.**
   Use the `withCpuProfile()` helper in `_utils.ts`, or run node with
   `--cpu-prof`. Open the resulting `.cpuprofile` in Chrome DevTools
   (Performance → Load profile) for a function-level flame graph
   inside the span.

## How to Orient Yourself

Before touching any code, build context by reading these sources in order:

1. **Read `editor/grida-canvas/__tests__/bench/README.md`** — benchmark
   catalog, run instructions, and the authoritative list of
   `PerfObserver` spans with a "when to trust the numbers" guide.
2. **Read `editor/grida-canvas/perf.ts`** — the `PerfObserver` API.
   Understand `start()`, `measure()`, `report()`, `dump()`.
3. **Skim `editor/grida-canvas/editor.ts`** — the `EditorDocumentStore`
   class, specifically the `dispatch()` method. This is the single
   entry point for all state mutations.
4. **Skim `editor/grida-canvas/reducers/index.ts`** — the root reducer
   that wraps everything in Immer `produceWithPatches`.
5. **Browse the bench files** (`perf-editor.test.ts`,
   `perf-per-node-sync.test.ts`) to see what operations are already
   measured and at what scale.

### Key discovery queries

| What you need                | How to find it                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| All instrumented perf spans  | `grep "__perf_" --include="*.ts"` in `editor/grida-canvas/`                           |
| The dispatch entry point     | Search for `dispatch(` in `editor/grida-canvas/editor.ts`                             |
| Root reducer + Immer produce | Read the top-level `reducer()` function in `editor/grida-canvas/reducers/index.ts`    |
| Gesture transform hot path   | Search for `self_update_gesture_transform` in `editor/grida-canvas/reducers/methods/` |
| Document query helpers       | Read `editor/grida-canvas/query/index.ts`                                             |
| React hook subscribers       | `grep "useEditorState" --include="*.ts"` in `editor/grida-canvas-react/`              |
| Action type definitions      | Read `editor/grida-canvas/action.ts`                                                  |
| Existing benchmark files     | `ls editor/grida-canvas/__tests__/bench/`                                             |

---

## The Architecture (Performance-Relevant)

### Dispatch Pipeline

Every user interaction flows through this pipeline:

```
User action (click, drag, keystroke)
  → dispatch(action, recording)
    → Immer produceWithPatches(state, draft => { ... })
      → sub-reducers (document, event-target, surface)
      → tracked-Graph wrapper emits sync_links / delete_node ops
    → appendPatchOps(patches, buffer) lifts document.nodes patches
      into replace_node / delete_node ops
    → history.record(patches)
    → postDispatchHooks
    → emit(action, patches, opLog)
      → __wasm_on_document_change applies opLog 1:1 to WASM
      → React selectors + equality checks
```

The op-log produced during the recipe is the single WASM-sync channel.
Structural edges come from the tracked-`Graph` wrapper; node-property
changes are lifted from Immer patches via `appendPatchOps`. The
subscriber applies ops directly (`Scene.replaceNode` /
`Scene.deleteNode` / `Scene.syncLinks`) or falls back to a full
re-encode only when the batch contains a `full_resync` op.

### Performance-Sensitive Operation Categories

**Gesture-bound (hot loop)** — fires on every frame while the user
drags a handle, slider, or object. These must complete within
~16ms (60fps budget) per frame:

- Property sliders (color picker, opacity, font size)
- Drag translate (moving nodes)
- Resize / scale (corner handles)
- Rotate

**Discrete (single shot)** — fires once per user click or toggle:

- Select, rename, visibility toggle
- Delete, insert
- Gesture start / end (snapshot cost)
- Pointer hover / raycast

### Cost Scaling

Costs scale **linearly** with total node count due to Immer proxy
finalization walking the entire state tree on every dispatch —
even when only a single property on one node changes. This is the
fundamental scaling wall for the current architecture.

Run the benchmarks to get current numbers. The `perf.report()` output
shows exactly which spans dominate at any given scale.

### Bottleneck Categories

Use `GRIDA_PERF=1` to identify which category applies:

| Category                        | How to recognize                                                                         | Where to look                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Immer overhead**              | `reducer.immer_produce` dominates; cost grows with node count regardless of what changed | Root reducer, consider structural sharing or targeted produce    |
| **O(N) tree queries**           | Tree-traversal spans are hot in the breakdown                                            | `query/index.ts` — check if lookups can use pre-built index maps |
| **Deep clone / snapshot**       | `snapshot` span dominates gesture start                                                  | `editor.i.ts` — consider storing only what the gesture needs     |
| **Compute-heavy reducer logic** | Specific spans (snap, hover, transform) dominate                                         | The relevant `reducers/tools/` or `reducers/methods/` file       |
| **React re-render**             | Not visible headless; visible in Chrome DevTools Profiler                                | Selector breadth, equality comparators, virtualization           |

---

## The Benchmark System

The single source of truth is `perf-editor.test.ts` in
`editor/grida-canvas/__tests__/bench/`. It uses `Editor.mountHeadless()`
with the **real WASM raster backend** — every dispatch runs through the
same `__wasm_on_document_change` subscriber the browser installs. Spans
under `dispatch.wasm.*` are end-to-end identical to the browser; spans
under `reducer.*` are pure JS and track within ~10% of browser V8.

```sh
# Default — runs every scenario at 1K synthetic + bench.grida (10K) scales
GRIDA_PERF=1 pnpm vitest run editor/grida-canvas/__tests__/bench/perf-editor.test.ts

# With CPU profile capture (delete scenarios)
GRIDA_PERF=1 GRIDA_PERF_CPUPROFILE=1 pnpm vitest run \
  editor/grida-canvas/__tests__/bench/perf-editor.test.ts

# Large fixtures need more heap
NODE_OPTIONS="--max-old-space-size=8192" GRIDA_PERF=1 \
  pnpm vitest run editor/grida-canvas/__tests__/bench/perf-editor.test.ts
```

### Which spans to read

After a bench run, `perf.report()` prints a table per scene. The bench
README has the authoritative catalog — read it there. Read the table
in category order rather than by specific name:

1. **Total dispatch** — your ceiling per action.
2. **Reducer + Immer** — pure JS cost. Watch p95 on gesture scenarios
   (drag / resize per-frame) — median can be microseconds while p95
   spikes into hundreds of ms as the tree grows.
3. **Document snapshot** — deep-clone at gesture boundaries; pays
   twice per gesture (start + end).
4. **WASM sync (full reload vs. op-apply)** — compare
   `dispatch.wasm.sync_document` (full reload) against
   `dispatch.wasm.op_apply` (per-op replay). If the full reload fires
   for every dispatch and op_apply rarely fires, too many actions are
   routing through the slow path — usually a missing observation
   channel that forces `full_resync` (e.g. a mutation under
   `document.*` outside `document.nodes[id]` that no tracked channel
   covers).
5. **Gesture / query compute** — snap targets, hover ray, tree
   traversal. Usually small but can dominate at high selection count.

Prefer bench ratios over absolute numbers in commits and memory —
absolutes shift with machine and node version; ratios stay meaningful.

### Adding a new benchmark

Extend `BENCH_SCENARIOS` in `perf-editor.test.ts`. Use the `bench()`
helper from `_utils.ts` for per-frame gestures and `runAndTime()` (or
similar) for single-shot discrete actions:

```ts
const result = await bench(() => {
  h.ed.doc.dispatch({ type: "...", ... } as Action, { recording: "silent" });
}, { iterations: 10 });
logBench("my operation", result);
```

If you need a one-off CPU profile of a specific operation, use
`withCpuProfile()` from `_utils.ts` — it wraps the call in
`node:inspector` and writes a `.cpuprofile` to
`fixtures/local/perf/cpuprofile/` (gated by `GRIDA_PERF_CPUPROFILE=1`).

---

## PerfObserver (`perf.ts`)

Opt-in instrumentation layer. Zero cost when disabled (returns a
shared `NOOP` function).

### Enable

```sh
GRIDA_PERF=1              # Node.js / headless tests
NEXT_PUBLIC_GRIDA_PERF=1  # Browser / Next.js (.env.local)
```

Or programmatically:

```ts
import { perf } from "@/grida-canvas/perf";
perf.enable();
```

### Instrument new code

Use the `__perf_` prefix for all perf variables:

```ts
import { perf } from "@/grida-canvas/perf";

function myHotFunction() {
  const __perf_end = perf.start("myHotFunction");
  // ... work ...
  __perf_end();
}

// For functions with multiple return paths, use try/finally:
function myComplexFunction() {
  const __perf_end = perf.start("myComplexFunction");
  try {
    if (earlyExit) return null;
    return result;
  } finally {
    __perf_end();
  }
}

// For wrapping a synchronous call:
const result = perf.measure("expensiveClone", () => doExpensiveWork());
```

### Read results

```ts
perf.report(); // prints formatted table to console
perf.summarize(); // returns PerfSummaryEntry[] (for programmatic use)
perf.dump(); // returns raw PerfSample[]
perf.reset(); // clears all samples
```

### Finding existing spans

Instrumented spans are discoverable via grep:

```sh
grep "__perf_" --include="*.ts" -r editor/grida-canvas/
```

The span labels use dot-notation hierarchy (`dispatch.reducer`,
`dispatch.emit`, etc.) so the `perf.report()` table reads naturally.

---

## Reading a browser trace

Chrome DevTools exports traces as `.json.gz`. They are plain JSON after
decompression, so analyze them with a short Python script rather than
opening DevTools by hand.

Key signals to extract:

| Signal                                    | How to find it                                                                                                              |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| React component renders (count per name)  | Events with `cat == "blink.user_timing"` and `ph == "b"`. Each render emits one; counting them per `name` shows re-renders. |
| Hot JS functions (self-time)              | `ProfileChunk` events contain `cpuProfile.nodes` + `samples` + `timeDeltas`. Accumulate `timeDeltas` per sample id.         |
| Long interactions                         | `FunctionCall` events with `name == "dispatchContinuousEvent"` (or `dispatchDiscreteEvent`) — filter by `dur > 20000` (µs). |
| What happened inside one long interaction | Filter `ProfileChunk` samples by their cumulative timestamp falling inside the `FunctionCall` window.                       |

The trace includes React DevTools overhead when the extension is
installed. **`measureInstance @ installHook.js` is the React DevTools
profiler** — it can easily account for ~10% of CPU and inflates render
counts. Ask the user to disable the extension for "clean" traces, or
subtract it out when reading.

```py
# Minimal trace reader — extract events and CPU profile nodes
import json, gzip
from collections import defaultdict, Counter
data = json.load(gzip.open("logs/Trace-....json.gz"))
events = data["traceEvents"] if isinstance(data, dict) else data

# Component renders by name
renders = Counter()
for e in events:
    if e.get("cat") == "blink.user_timing" and e.get("ph") == "b":
        renders[e.get("name","")] += 1

# CPU self-time by function
nodes_by_id = {}
self_time = defaultdict(int)
for e in events:
    if e.get("name") == "ProfileChunk":
        cp = e["args"]["data"].get("cpuProfile", {})
        for n in cp.get("nodes", []):
            nodes_by_id[n["id"]] = n
        for sid, dt in zip(cp.get("samples", []),
                           e["args"]["data"].get("timeDeltas", [])):
            self_time[sid] += dt
```

---

## Node CPU profiles

When an `editor-bench` run flags a span but you need function-level
detail, capture a `.cpuprofile`:

```sh
# Via the bench harness (preferred — uses withCpuProfile wrapper)
GRIDA_PERF=1 GRIDA_PERF_CPUPROFILE=1 pnpm vitest run \
  editor/grida-canvas/__tests__/bench/perf-editor.test.ts
# → writes fixtures/local/perf/cpuprofile/*.cpuprofile

# Or wrap a specific call in code:
import { withCpuProfile } from "./_utils";
await withCpuProfile("my-scenario", async () => { ... });
```

Open the resulting `.cpuprofile` in Chrome DevTools (Performance → Load
profile) or VS Code for an interactive flame graph.

For microtask-level detail, start Node with
`--cpu-prof --cpu-prof-interval=100` (µs between samples). For trace
events / async task timing, `--trace-events-enabled` captures a
chrome://tracing-compatible JSON. Both are Node built-ins — no extra
tooling required.

---

## The Verification Workflow

**Every performance change follows this sequence.**

### Step 1: Baseline

Run the bench BEFORE any changes. Save the output.

```sh
GRIDA_PERF=1 pnpm vitest run editor/grida-canvas/__tests__/bench/perf-editor.test.ts
```

If the user provided a browser trace, also record its pre-change numbers
(render counts and hot-function self-times) — these are the only way to
verify React-side wins.

### Step 2: Implement

Make the change. After each logical step, verify:

```sh
pnpm vitest run grida-canvas/__tests__/headless/
pnpm turbo typecheck --filter=editor
```

### Step 3: Measure

Run the same benchmarks AFTER the change. Compare.

### Step 4: Regression check

An optimization for one operation must not regress others. Run the
full bench suite at both 1K and 10K scales, not just the target
operation — many improvements that help 10K scenes add constant
overhead that hurts 1K.

### Step 5: Accept or iterate

| Criterion                                    | Required? |
| -------------------------------------------- | --------- |
| Target operation measurably faster           | Yes       |
| Non-target operations within 10% of baseline | Yes       |
| All headless tests pass                      | Yes       |
| No new TypeScript errors                     | Yes       |

---

## How to Design an Optimization

### 1. Measure first

Run benchmarks to quantify the problem. Use `GRIDA_PERF=1` to get the
internal span breakdown. Identify which span dominates.

### 2. Classify the bottleneck

See the "Bottleneck Categories" table above. The `perf.report()` output
directly tells you which category you're dealing with.

### 3. Implement incrementally

Each step should compile, pass existing tests, produce a measurable
improvement in the target benchmark, and not regress other benchmarks.

### 4. Add a benchmark if one doesn't exist

If optimizing an operation that has no bench coverage, extend
`BENCH_SCENARIOS` in `perf-editor.test.ts` first. Measure before and
after.

---

## Pitfalls

### Immer makes everything O(N)

Immer's `produceWithPatches` walks the entire proxy tree during
finalization regardless of how many properties changed. This is
the fundamental scaling wall — even a no-op dispatch has a cost
proportional to total node count.

### Gesture start can freeze the UI

Gesture start may deep-clone the entire document state for undo
snapshots. At scale this causes multi-second freezes and high
memory pressure. Check how snapshot data is captured when
investigating gesture-start lag.

### Bench omits React cost — that is intentional

The bench measures the reducer + emit + WASM pipeline, not the React
subscription layer. If the complaint is about interaction feel (a
pointer move stalls, a panel re-renders too often), bench will not
see it. Use a browser trace for that; see "Pick your measurement
tool" above.

### WASM geometry adds memory pressure

The WASM raster backend allocates a real scene in memory. At 10K+
nodes, running full gesture benchmarks may OOM at default heap size.
Use `NODE_OPTIONS="--max-old-space-size=8192"`.

### Gesture-bound operations vary wildly

Drag translate can be orders of magnitude slower than resize at the
same node count because translate triggers snap-target computation
(tree queries per selection item) while single-node resize skips
that path. Always bench the specific gesture type, not just
"gesture" generically.

### `recording: "silent"` skips history

Benchmarks use `{ recording: "silent" }` to avoid history stack
growth during repeated dispatches. This correctly isolates reducer
cost but skips the history recording path. Use `{ recording: "on" }`
when specifically benchmarking history overhead.

More agent context in gridaco/grida

37 other files this repository gives its agents.