feat: Chrome Performance panel tracks for Solid (@solidjs/web/performance-tracks)

[ryansolid]

Summary

@solidjs/web/performance-tracks: Solid's attribution records rendered as custom tracks on Chrome's Performance panel, through the panel's extensibility API (console.timeStamp / performance.measure with detail.devtools) — the same mechanism React 19.2's Performance Tracks use from react-dom. Same records, two renderings: the diagnostics artifact for an agent, the track for the human, consistent because they are one stream and every label comes from the shared formatters (formatOrigin, formatRerun, ownerPath).

import { enablePerformanceTracks } from "@solidjs/web/performance-tracks";
const disable = enablePerformanceTracks(); // dev and observe tiers; a no-op in prod

Plan and decisions: documentation/plans/chrome-performance-tracks-plan.md. User docs: documentation/solid-2.0/08-dev-diagnostics.md, "Chrome Performance panel".

Track	Reads as
Interactions	input delay → handler → settle; silent hold = warning
Propagation	one wave per scheduler drain (count 0 → 1 — click on button#next · 5 runs, 1 unchanged), the runs beneath it labelled node ← cause
Effects / Memos	re-runs, creation runs and effect callbacks by owner path; colour by self time; warning when the run changed nothing
Async	flights kickoff → landing (abandoned = warning); fallbacks displayed → hidden
Holds	the wait, by blockers; warning silent, error long — the engine's own verdicts
Navigations	request → settle, by route
Server	server-function calls; frame streams with a shell sub-span
Timings	one marker per diagnostic finding, performanceIssue at warn+

Where this differs from React

• Propagation, not Components. Nothing re-renders in Solid, so a component flame answers the wrong question. The Propagation track paints the graph a write travelled: a wide flat wave is a coarse signal everyone depends on, a deep one a chain of memos, a warning node with nothing after it the equality cutoff at work.
• Runs in production observe builds, not only dev/profiling: the tracks are one consumer of the shared attribution engine, beside the responsiveness findings and an APM adapter. enable()/disable() are ref-counted so consumers coexist.
• Findings on the timeline. Every DiagnosticEvent (silent hold, waterfall, unstable memo…) is a marker with a performanceIssue annotation linking its repair guide; React's tracks carry no verdicts.
• INP join. InteractionEvent.at is the browser event's timeStamp, so PerformanceEventTiming.startTime === interaction.at joins Solid's interaction span to Chrome's INP entry directly.
• JSX-site stacks in dev via console.createTask on the component record.

Commits

One per stage; each with its changeset (all patch, prerelease).

• b512cb30d Stage 0–2 — ref-counted engine enable/disable, checks option, isSilentHold/isLongHold, at/inputDelayMs; the adapter; five listener-gated timeline records (flush, create, effect, flight, fallback) and the flushStart hook. effectRunStart/End move from __DEV__ to __OBSERVE__; a 27% enabled-path regression found and removed (effect frames registered lazily).
• fc03377b1 Stage 3 — Propagation track; ChangeRecord.nodeId; flow-control internals named in observe (children, boundary, value, reveal order, conditions).
• 8cbe1e613 3c285b2a2 ed273ecf3 Stage 3.5 — compilers: componentNames → sourceNames: boolean | { components?, bindings? }. Binding effects named by target (span.textContent, div.class:active, div.spread/div.children); a separate transformSourceNames(code, opts) pass (Oxc, plain JS in/out, runs on .ts too — not a transform() option, since primitives live outside components) names primitives after their declared identifier; stores honour name. The @solidjs/vite-plugin side is staged separately and waits on the compiler release.
• 1e26978ed Stage 4 — findings as Timings markers + performanceIssue; console.createTask stacks; Owner path / Node id / Origin properties; diagnosticGuideUrl export.
• a23eb4d04 Size audit — all source-name plumbing folded out of prod (spread labels via a module-level spreadName, boundary names gate the call, createStore's name branch under __OBSERVE__). Minified prod bundles are structurally identical to next (same byte count, identifier-normalised diff empty); the ±50 B brotli movement is esbuild's name assignment, documented in the caps.
• 34fc47036 Fallback record fix (found rebasing over fix(signals): Loading on follows the frame; DEV LOADING_ON_OUTSIDE_HOLD (#3540) #3575) — a <Loading> swap is a staged write that lands with its frame; the engine timed the fallback from the swap and so recorded spinners that were never on screen (the LOADING_ON_OUTSIDE_HOLD shape: committed and cleared by the same sweep before any effect ran). boundaryFallback now carries the transaction the swap is staged in; the engine stamps at at the flushEnd of the drain that rendered it and drops an open hidden before that. Two tests pin both product-page shapes.

Review fixes (the six commits after the stage commits)

• One adapter instance per page: enablePerformanceTracks() while enabled joins the running instance (its options are not re-read) and returns its own release; the instance is torn down at the last release. An HMR re-evaluation no longer paints twice or strands a hold.
• ./performance-tracks carries node/worker/deno conditions resolving to the inert artifact under every posture — verified under node --conditions=development: no closure, no measures, no hold. Pinned by a test on the manifest.
• The Emitter guards every performance/console call: a throw drops the entry (dev warns once) and never reaches the engine's record loop.
• rich: false falls back to performance.measure where console.timeStamp is missing (mirror of the existing fallback); rich mode clears a User Timing name only while the timeline holds no more entries of it than the adapter made, so an app measure sharing a label is left alone.
• stagedFallbacks is a WeakMap keyed by the transaction (DRAIN is an object key): a transaction dropped without settling or merging releases its staged opens.
• Stale "Scheduler track" wording in the timeline-records changeset → Propagation; docs now say transformSourceNames is the compiler pass and sourceNames.primitives the Vite plugin's option.
• Item 5 — attribution.enable(opts) returns the release of its hold (idempotent, like subscribe); disable() is the full teardown whatever holds are outstanding, so enable(); enable(); disable() cannot strand a hold (the provenance test idiom). Options combine across holds by the most demanding request per key (booleans OR, historyLimit max, a threshold config over false, between configs the bound that fires sooner) — a hold adds to what the engine does and never takes away what another asked for, so the result is independent of enable order: a track's log: false beside a console session leaves the log alone; a capture with tight thresholds beside a records-only adapter runs the checks for its own duration. Prior art: wake-lock sentinels / Rx refCount for the hold, Node trace_events (union of enabled categories) and CDP per-session enablement for the merge. The adapter and @solidjs/diagnostics captures release through the token.
• Item 6 — dev builds create the component's console.createTask task only while an attribution engine is installed (OBSERVE.attribution.installed !== null). A dev session with nothing enabled pays nothing; the tracks enabled at bootstrap see every component's site. Observe and prod artifacts never contained the call (verified: createTask appears in solid.dev.js only).

Public API changes

Breaking

• @solidjs/babel-plugin / @solidjs/compiler: option componentNames: boolean removed (no alias) → sourceNames: boolean | { components?: boolean; bindings?: boolean }. true turns every kind on. bindings is DOM output only.
• @solidjs/signals attribution.enable(opts): () => void — each call is a hold and returns its release (was void); options combine across live holds by the most demanding request per key (a released hold withdraws its requests; an explicit undefined is unsaid and takes the default); the engine is uninstalled at the last release. disable() is the full teardown whatever holds are outstanding (unchanged in effect from next, where one disable() uninstalled). Prod twin: enable returns a no-op.
• @solidjs/signals InteractionEvent.at is now the browser event's timeStamp (the INP join) rather than the engine's performance.now() at dispatch; the dispatch-side delay is the new inputDelayMs.

Added

• @solidjs/web: new export path ./performance-tracks — enablePerformanceTracks(options?: PerformanceTracksOptions): () => void, PerformanceTracksOptions { attribution?, minMs?, rich?, group?, scrub? }. Browser dev/observe artifacts; inert under node/worker/deno and in prod.
• @solidjs/signals: five record types on AttributionRecords / attribution.subscribe(type, …) — create (CreateEvent), effect (EffectRunEvent), flush (FlushEvent), flight (FlightEvent), fallback (FallbackEvent). Built only while a listener exists.
• @solidjs/signals: isSilentHold(hold), isLongHold(hold) (the engine's hold verdicts, exported; () => false in the prod twin); AttributionOptions.checks?: boolean (records only when false); InteractionEvent.inputDelayMs?; ChangeRecord.nodeId; StoreOptions.name honoured for property-node labels (todos.title).
• @solidjs/compiler: transformSourceNames(code, { filename?, sourceMap? }) / transformSourceNamesAsync and TransformSourceNamesOptions — the primitives-naming pass.
• solid-js (client and server): ownerPath(owner) re-exported from @solidjs/signals; diagnosticGuideUrl(code) — the repair guide's section URL for a diagnostic code.
• @solidjs/web compile targets: effect(fn, effectFn, options?: { scope?, name? }) gains name; insert(parent, accessor, marker?, init?, options?) gains options.name; spread(node, props, skipChildren?, skip?, name?) gains a fifth name argument. Emitted by the compilers under sourceNames.bindings; ignored by production runtimes (prod output is structurally identical to next).
• Dev-only, on the component record: _component.task (a console.createTask task, present only for components rendered while an attribution engine is installed) — internal shape, listed for completeness.

Internal hooks changed (@solidjs/signals AttributionHooks, not a public export): flushStart added; boundaryFallback(boundary, tree, shown, transition?) gains the transaction argument; effectRunStart/End now fire under __OBSERVE__ (were __DEV__).

Cost

• Prod: signals-only and frames scenarios byte-identical to next; app scenarios structurally identical — re-verified after the third rebase (over fix(signals): rewriting an orphan override opens no transaction (#3576) #3586, fix(signals): a reawakened lazy memo rejoins its owner's chain #3555): CSR minified bundles 44,649 B on both sides, +51 B brotli name-assignment noise, CSR cap 15.80 → 15.85 KB with the note.
• Observe tier: +155 B (hook sites, node names); engine: +1,250 B (holds + release, most-demanding merge, records, fallback staging). Caps ratcheted with audit notes.
• Enabled hot path: micro-benchmarked against next at the fix(signals): Loading on follows the frame; DEV LOADING_ON_OUTSIDE_HOLD (#3540) #3575 merge — 2,000 effects on one signal, and 200 <Loading> boundaries over memos — disabled / enabled checks:false / checks:true, min-of-5 medians: every cell within ±6%, signs both ways (parity within noise).

Verification

CI green on the head (test, coverage, types, size, benchmarks). Locally after the second rebase (over #3559, #3562, #3584): compiler 5844 / babel-plugin 265 / signals 3537 / solid 655 / web 894 / diagnostics 34 green; types clean; size-limit green. Verified visually in Chrome on a scratch Vite page: tracks, waves, markers with the Insights annotation, and the JSX-site stack on a span.

Follow-ups (not in this PR)

• @solidjs/vite-plugin sourceNames integration (worktree staged; needs the compiler release).
• Stage 5 (deferred in the plan): tracks for the server render, and reading the attribution artifact back into the panel offline.
• D2 in the responsiveness plan (what checks defaults to under a records-only consumer) is still open there.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5e7ebb5

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

This PR includes changesets to release 11 packages

Name	Type
@solidjs/signals	Patch
solid-js	Patch
@solidjs/web	Patch
@solidjs/babel-plugin	Patch
@solidjs/compiler	Patch
@solidjs/diagnostics	Patch
test-integration	Patch
@solidjs/element	Patch
@solidjs/h	Patch
@solidjs/html	Patch
@solidjs/universal	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

[coveralls]

Coverage Report for CI Build 35791922360

Coverage increased (+0.08%) to 72.852%

Details

• Coverage increased (+0.08%) from the base build.
• Patch coverage: 5 of 5 lines across 2 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1073
Covered Lines:	827
Line Coverage:	77.07%
Relevant Branches:	824
Covered Branches:	555
Branch Coverage:	67.35%
Branches in Coverage %:	Yes
Coverage Strength:	17.56 hits per line

---

💛 - Coveralls

[codspeed]

Merging this PR will not alter performance

✅ 176 untouched benchmarks
⏩ 3 skipped benchmarks¹

---

_{Comparing feat/performance-tracks (5e7ebb5) with next (43fae6e)}

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩