RenderResourceProvider memoized its context value on the resource object reference, but every call site passes an inline object literal (resource={{kind, id}}). A new object every render → the memo recomputed every render → it produced a new array as the context value → every embed in the subtree re-rendered whenever any ancestor re-rendered.

In production the ancestor (the document editor) re-renders ~once per second on the desktop activity-poll's query invalidations → embeds flashed every second. In dev you could trigger the same path just by scrolling.

The fix: memoize the provider value on a primitive identity key instead of the object reference, plus memoize the embed's id so it stops handing a fresh blockRange prop downstream.

We changed our root-cause hypothesis three times before landing it. Each false lead looked plausible and each was killed by a measurement, not an argument. Worth internalizing:

First guess — the 1s desktop activity poll invalidating ENTITY queries. frontend/apps/desktop/src/app-sync.ts polls the activity feed every 1s and invalidates React Query caches. Looked like the obvious "every second" culprit. Killed by: profiling showed that on a quiet document the poll found zero events and fired zero ENTITY invalidations — yet embeds still re-rendered. (We even temporarily bumped the poll interval to 10s; the re-render cadence didn't budge.)

Second guess — the document editor re-applying its content. The editor's XState machine calls applyInitialContent → editor.replaceBlocks on entering the editing state, which rebuilds every tiptap NodeView (embeds are NodeViews). We saw repeated flushSync warnings from that path. Killed by: instrumented logging showed applyInitialContent fires only a handful of times at startup, not continuously. (Those flushSync warnings are a real but separate, pre-existing, dev-only issue.)

Third guess — discovery progress stream churn. useResource({subscribed:true}) → useDiscoveryState → useStream re-renders on every discovery-progress write. Killed by: discovery uses a unary RPC retried ~every 2s, far too slow to explain the ~10ms continuous re-render cascade we were measuring.

Actual cause — found with a "why-did-render" probe. We added a render logger that recorded which tracked input changed reference on each embed render. The answer was unambiguous:

BlockEmbedContent re-rendered with changed=[renderResourceStack]

BlockEmbedContentDocument re-rendered with changed=[blockRange]

That single field ended the guessing.

frontend/packages/shared/src/render-resource-context.tsx provides the "render-resource ancestry stack" (used for embed-cycle detection) via React context:

Every call site passes the resource as an inline literal:

So resource is a new reference on every render → the useMemo dependency changes every render → value is a brand-new array every render. A React context value identity change re-renders every consumer, regardless of whether the consumer's own props/state changed. Every embed reads this context (useRenderResourceStack()), so all embeds re-rendered on every ancestor render.

Why "every second" in production, "on scroll" in dev:

Both are just ancestor re-renders. The unstable context turned any ancestor render into an all-embeds render.

Production: the document editor re-renders ~1×/s from the activity poll's query invalidations (account/feed/etc. broadcasts) → embeds flash every second.

Dev: scrolling sends a scroll event into the document machine (useScrollSync), which re-renders the editor subtree → same cascade.

Secondary amplifier: BlockEmbedContent recomputed id (via unpackHmId(block.link) + spread) on every render, so it handed BlockEmbedContentDocument a fresh blockRange object each time — re-rendering it even after the context was stabilized.

render-resource-context.tsx — memoize on a primitive identity key, not the object:

Now object-identity churn at the call sites is ignored; the array is rebuilt only when the resource actually changes. Because parentStack is itself a now-stable context value, the whole provider chain stabilizes.

embed-views.tsx — memoize id on block.link so id/id.blockRange stay referentially stable across re-renders.

Result (measured)

Continuous ~10ms re-render churn: gone.

Residual renders: only changed=[] at the editor's natural ~2s ticks — i.e. the parent re-rendered with no input change, so React reconciles to the same DOM and there is no visual flash. These are benign; we deliberately did not add React.memo to chase them (it wouldn't bail without first stabilizing unstable callback props, and adds staleness risk for zero user-visible gain).

A useMemo/useContext value keyed on an object that callers construct inline is effectively not memoized at all — and when that value is a context value, the cost is paid by every consumer in the subtree, not just the provider. It's invisible until something upstream starts re-rendering often (here, a 1s poll), at which point it amplifies into a whole-subtree storm.

While investigating we noticed pre-existing, dev-only console warnings, unrelated to the flashing:

flushSync was called from inside a lifecycle method — from applyInitialContent → editor.replaceBlocks (tiptap mounts NodeViews with flushSync). The editor's init is intentionally synchronous, so we left this alone.

validateDOMNesting: <div> cannot appear as a descendant of <p> — the Spinner rendered a <div> inside the document-header author <p>/<a>. Fixed by rendering Spinner as a <span> (it was already styled inline-block, so visually identical and valid everywhere). This also removes a real web-SSR hydration risk.