Skip to content

Devtools overlay performance - #280

Open
spaansba wants to merge 6 commits into
mainfrom
devtools-overlay-perf
Open

spaansba wants to merge 6 commits into
mainfrom
devtools-overlay-perf

Conversation

@spaansba

@spaansba spaansba commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Makes the devtools usable with thousands of registered elements.

  • Elements tab is virtualized (@lit-labs/virtualizer). Each row was ~100 DOM nodes, so 10,000 elements meant over a million nodes
  • Elements tab sorts by one DOM pass instead of compareDocumentPosition, which re-sorted 10,000 rows on every visibility change and took seconds per frame
  • Overlay updates are batched per task with one scroll read, and callback hits no longer force a flush each
  • Name labels moved inside their slop area, so scrolling no longer rewrites textContent/transform per element
  • Glow, scroll dash flow and arrow pulse now animate only opacity/transform
  • Toggled-off overlays unmount, dropping their subscriptions
  • Vue mass demo renders its grid in its own component, so a callback hit no longer re-renders every button (React already did this)

- Name labels live inside their slop area and only rewrite on name change
- Glow, dash flow and arrow pulse animate opacity/transform instead of box-shadow, background-position and filter
- Mouse trajectory scales a fixed-width line instead of writing width
- Hidden overlays unmount instead of processing updates behind display: none
@changeset-bot

changeset-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 05a2b9b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
js.foresight-devtools Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@spaansba
spaansba marked this pull request as ready for review November 16, 2026 08:10

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ One minor visual note inline; nothing blocking.

Reviewed changes

  • Overlay lifecycle — debug-overlay now returns nothing for non-mouse strategies and mounts each overlay only while its toggle is on, so a disabled overlay unmounts and drops its manager subscriptions instead of processing updates behind hidden.
  • Name labels — labels are children of their slop area, written only when the name changes, and hidden through :empty / data-hide-names CSS instead of per-element style.display writes; the label's document positioning is preserved exactly by the slop area's padding-box offsets.
  • Compositor-only animation — glow, dash flow and arrow pulse were rewritten to touch only opacity/transform; the mouse line is a fixed-width bar scaled with scaleX plus a sibling arrow, replacing the per-frame width write.
  • Overlay state — overlayMap/callbackAnimations dropped @state(); neither is read by render(), so this only removes redundant re-render scheduling.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using deepseek-v4.1-flash-1017 (free via Pullfrog for OSS) | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

  • Mouse trajectory reverted to the width-based line — 2c3f6b4 drops the scaleX bar and the sibling arrow, so the line is again a translate3d(...) rotate(...) plus style.width write and the arrow is the .trajectory-line::after triangle. This also removes the scaled box-shadow/cap-radius stretch raised in the previous review, so that comment is now moot.
  • Kept from the earlier pass — @query(".trajectory-line", true) caching, hasUpdated guards in _setVisible/handleTrajectoryUpdate, no transform/width zeroing on reset, :host([hidden]) gone (the parent conditionally renders the element), and will-change narrowed to transform.
  • No other files changed — the range-diff confirms debug-overlay.ts, element-overlays.ts, scroll-trajectory.ts and the changeset are untouched since 365bbe9.

Pullfrog  | View workflow run | Using deepseek-v4.1-flash-1017 (free via Pullfrog for OSS) | 𝕏

Reading window.scroll{X,Y} and getBoundingClientRect per overlay after the
previous overlay's style writes forced a layout per element.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

  • Batched overlay updates — every state/bounds subscriber now funnels into a _pendingUpdates set flushed once per queueMicrotask, so _flushUpdates samples window.scrollX/Y a single time and applies all overlays in one pass instead of reading scroll per element.
  • Removed the last per-update layout read — expandedBorderRadius takes the manager's cached bounds.originalRect instead of calling getBoundingClientRect(), and createOrUpdateElementOverlay no longer touches the DOM before the flush's container guard.
  • Immediate flush for queued highlights — highlightElementCallback flushes pending updates when its own element is still queued, so a glow is not lost when an element becomes visible and is predicted in the same task (the manager emits callbackInvoked while isActive is still true).
  • Lifecycle cleanup — disconnectedCallback clears _pendingUpdates, and _syncAlreadyRegisteredElements/elementRegistered now share the queue instead of creating overlays inline.

Pullfrog  | View workflow run | Using deepseek-v4.1-flash-1017 (free via Pullfrog for OSS) | 𝕏

Every registered element rendered a full row (~100 DOM nodes with three shadow
roots). With 10,000 elements the page held over a million nodes and the browser
froze. Only visible rows are rendered now.
Every callback hit bumped hitCount in the same component as the v-for, so each
hit re-rendered all buttons. React already memoizes its grid for this.
Re-sorting with compareDocumentPosition on every visibility change walked
every sibling per comparison, seconds per frame with 10,000 elements. Callback
hits forced an overlay flush each, a forced layout per scroll-predicted element.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

The new commits virtualize the elements tab and make the overlay hit glow survive deferred overlay creation. The one blocking item is CI: the lint check is red on 05a2b9b because of two auto-fixable Vue rule violations in the mass demo (inline).

Reviewed changes

  • Virtualized the elements tab — element-tab renders a flat ListRow[] through @lit-labs/virtualizer with a self-scrolling .list host, and section headers became rows instead of per-section wrappers.
  • One-pass document order — compareDocumentPosition sorting is replaced by a cached document.querySelectorAll("*") walk, invalidated on register/unregister and park transitions, so the by visibility sort is now a filter over that array.
  • Deferred hit glow — highlightElementCallback no longer flushes; it records the hit kind in _hits so createOverlay can re-apply data-hit when the overlay is created later in the same task.
  • Vue mass demo split — the grid moved into ButtonGrid.vue, keyed from the view, so a hit re-renders only the grid.
  • Virtualizer dependency — @lit-labs/virtualizer added to the devtools dependencies (inlined into the single 91 kB dist/index.mjs chunk), with lockfile and changeset updates.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using deepseek-v4.1-flash-1017 (free via Pullfrog for OSS) | 𝕏

Comment on lines +4 to +5
defineProps<{ buttonCount: number }>()
const emit = defineEmits<{ hit: [] }>()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

vue/define-macros-order is configured with ["defineModel", "defineEmits", "defineSlots"], so defineEmits has to precede defineProps. As written pnpm lint fails here, and that is one of the two errors keeping the lint check red on this PR — swapping the two lines (or running eslint --fix) clears it.

</Foresight>
</div>
<!-- Re-keying the grid on reset re-mounts every button, clearing state. -->
<ButtonGrid :key="resetKey" :button-count="buttonCount" @hit="onHit" />

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

vue/v-bind-style with sameNameShorthand: "always" wants the shorthand form here, and this is the second error in the red lint job. eslint --fix rewrites the line to :button-count (the compiler camelizes the name to form the expression).

Comment on lines +356 to +372
private get documentOrder(): ForesightElement[] {
if (this._documentOrder) {
return this._documentOrder
}

const unplaced = new Set(this.elementListItems.keys())
const ordered: ForesightElement[] = []
for (const node of document.querySelectorAll("*")) {
if (unplaced.delete(node)) {
ordered.push(node)
}
}
ordered.push(...unplaced)
this._documentOrder = ordered

return ordered
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cache is invalidated on register/unregister and on park transitions, but not when an already-registered element moves in the DOM: a framework reordering keyed children leaves the node connected, so it is never parked and the cached order keeps its old position. by document / by visibility then show a stale order until the next register or unregister — low stakes for a debug view, but staler than main, which re-sorted on every dirty recompute.

Technical details
# Stale document order after DOM moves

## Affected sites
- `packages/js.foresight-devtools/src/lit-entry/control-panel/element-tab/element-tab.ts:356-372` — `documentOrder` caches one DOM walk; only registration and `isParked` flips null it.

## Required outcome
- The cached order must not outlive a move/reorder of elements that are already registered and connected.

## Suggested approach (optional)
- Null `_documentOrder` when the manager's document `MutationObserver` reports a childList change (that is the same signal it uses to park/reconnect), or rebuild the order inside `_recomputeElementsCache` if the walk is cheap enough for the target DOM sizes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant