Skip to content

Commit 588365e

Browse files
lxsmnsycclaude
andauthored
feat: add a Timeline panel of what each action re-ran (#29)
* feat: add a Timeline panel of what each action re-ran - A Timeline tab lists each user action, such as a click or a key press, with the writes it made, the memos and effects that re-ran, and how long the update took. Updates from timers or promises are rows of their own. - A re-run shows the changes that caused it, down to the write that started them. A re-run that produced the same value is marked as no change. - The detail shows the input delay, handler time and settle time from the interaction record, and links each re-run to the reactivity graph. - The copy button puts a report of the action on the clipboard for an agent. - The toolbar turns on the attribution engine of solid-js when it mounts, with its console log off. - Clicks in the toolbar change nothing in the app, so they are left out. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(timeline): list the server-function calls of each action - The timeline reads the `call` record, whose origin is the interaction's own object, or a frame that names it. A call joins the action it ran for. - A click that only calls the server writes nothing, so its interaction record looks idle. Idle interactions are kept aside, and a later call attaches to its own. - The detail lists the calls with method, status and time, and the report has a Server calls section. - A call opens in the server-function panel. The timeline keeps that panel's key for the call, since the runtime's live object for it is not held by anything once it settled. - The test fixture has a "call server" button that sends a call record from its handler. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(timeline): hide updates that only touched unnamed signals - Updates no action caused, whose writes all went to unnamed signals or that wrote nothing, come mostly from Solid's own state, such as a Show condition or a Loading boundary settling. They pushed real actions down the list. - They are hidden by default. A button above the list shows how many there are and brings them back, since an app's own unnamed signal looks the same. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(timeline): hide updates to the memos of Solid's own components solid-js rc.20 names the memos inside <Show>, <Switch> and the Loading boundary, such as value and condition, so their updates no longer carried a default name and showed in the Timeline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 2b8a936 commit 588365e

13 files changed

Lines changed: 1829 additions & 10 deletions

File tree

‎.changeset/timeline-panel.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@solidjs/start-devtools': minor
3+
---
4+
5+
Add a Timeline panel that lists what each user action re-ran, and why.
6+
7+
- Each click, key press or outside update is a row with its writes, re-runs and timing.
8+
- A re-run shows the changes that caused it, down to the write that started them.
9+
- The server-function calls an action made are listed under it, and open in the server-function panel.
10+
- The copy button puts a report of the action on the clipboard for an agent.

‎README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Development error and server-function tooling for Solid Start mode.
66

77
- Runtime error inspection with source-mapped stack frames.
88
- The issues the runtime reports, such as a signal read outside a tracking scope.
9+
- A timeline of what each action re-ran, and why.
910
- Server-function request and response inspection.
1011
- A reactivity graph of the live signals, memos and effects in the app.
1112
- An ownership tree of the components and scopes the app created.
@@ -64,6 +65,31 @@ the same findings, mixed with everything else.
6465
The panel listens from the moment the toolbar mounts, so findings from the first render
6566
are there when you open it. Issues need a development build of `solid-js`.
6667

68+
## Timeline
69+
70+
The timeline lists what each user action made the app do. A click, a key press or an
71+
input is one row, with the signals it wrote and every memo and effect that re-ran because
72+
of it. An update from outside a handler, such as a timer or a promise, is a row of its own.
73+
74+
- A row shows the writes, the number of re-runs and how long the update took.
75+
- Select a row for the input delay, the handler time, the time until the update settled,
76+
and the writes with their old and new values.
77+
- Open a re-run to see why it ran: the changes it saw, and the changes behind each of
78+
those, down to the write that started them.
79+
- A re-run marked **no change** produced the same value as before, so its work was wasted.
80+
- The eye opens the memo or effect in the reactivity graph.
81+
- Server-function calls the action made are listed with their status and time. Click one
82+
to open it in the server-function panel. A click that only calls the server still gets a
83+
row.
84+
- Updates no action caused whose writes all went to unnamed signals are hidden, since most
85+
come from Solid's own state, such as a `<Show>` condition. The button above the list shows
86+
how many there are and brings them back.
87+
88+
The panel turns on the attribution engine of `solid-js` (`solid-js/attribution`) when the
89+
toolbar mounts, so the first action is recorded even with the dock closed. Clicks in the
90+
toolbar itself change nothing in the app, so they are left out. The timeline needs a
91+
development build of `solid-js`.
92+
6793
## Reactivity graph
6894

6995
The graph panel maps the running reactive graph. Signals, memos and effects are nodes,

‎src/dev-toolbar/functions/index.tsx‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { createMemo, createSignal, For, Loading, Show } from 'solid-js';
1+
import { createEffect, createMemo, createSignal, For, Loading, Show } from 'solid-js';
22
import type { JSX } from '@solidjs/web';
33
import {
44
BODY_FORMAT_FILE_KEY,
@@ -375,13 +375,25 @@ function EmptyServerFunctions(): JSX.Element {
375375

376376
export interface ServerFunctionViewerProps {
377377
instances: Record<string, ServerFunctionInstance | undefined>;
378+
/**
379+
* A call another panel asked to show. Pass a new object for every request,
380+
* so asking for the same call twice still selects it.
381+
*/
382+
focus?: { instance: string };
378383
onDeleteInstance: (value: string) => void;
379384
show?: boolean;
380385
}
381386

382387
export function ServerFunctionViewer(props: ServerFunctionViewerProps): JSX.Element {
383388
const [currentInstance, setCurrentInstance] = createSignal<string>();
384389

390+
createEffect(
391+
() => props.focus,
392+
(request) => {
393+
if (request) setCurrentInstance(request.instance);
394+
},
395+
);
396+
385397
const keys = createMemo(() => Object.keys(props.instances));
386398

387399
return (

‎src/dev-toolbar/functions/records.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,18 @@ export interface CallRecordsChannel {
2626
): () => void;
2727
}
2828

29+
/**
30+
* The panel's key for each call the records showed, by the runtime's live
31+
* object for the call. Other panels get the live object from the `"call"`
32+
* record too, so they can point the panel at the same call.
33+
*/
34+
const shownCalls = new WeakMap<object, string>();
35+
36+
/** The panel's key for a call, from the live object of its `"call"` record. */
37+
export function instanceOfCall(live: object): string | undefined {
38+
return shownCalls.get(live);
39+
}
40+
2941
/**
3042
* Feeds the server-function panel from the runtime's records. A call shows
3143
* up when its request is sent and completes when it settles; the two
@@ -56,12 +68,12 @@ export function connectCallRecords(
5668
const offCall = records.subscribe(
5769
'call',
5870
(event, live) => {
59-
const instance = instances.get(live);
60-
const events =
61-
instance === undefined
62-
? callRecordToEvents(event, live, key(event.id))
63-
: settleRecordToEvents(event, live, instance);
64-
if (instance !== undefined) instances.delete(live);
71+
const instance = instances.get(live) ?? key(event.id);
72+
const events = instances.has(live)
73+
? settleRecordToEvents(event, live, instance)
74+
: callRecordToEvents(event, live, instance);
75+
instances.delete(live);
76+
if (events.length) shownCalls.set(live, instance);
6577
for (const call of events) push(call);
6678
},
6779
{ bodies: true },

‎src/dev-toolbar/icons.tsx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -799,3 +799,22 @@ export function IssueIcon(props: JSX.IntrinsicElements['svg'] & { title: string
799799
</svg>
800800
);
801801
}
802+
803+
export function TimelineIcon(props: JSX.IntrinsicElements['svg'] & { title: string }): JSX.Element {
804+
return (
805+
<svg
806+
xmlns="http://www.w3.org/2000/svg"
807+
fill="none"
808+
viewBox="0 0 24 24"
809+
stroke="currentColor"
810+
{...props}
811+
>
812+
<title>{props.title}</title>
813+
<path
814+
stroke-linecap="round"
815+
stroke-linejoin="round"
816+
d="M12 6v6h4.5m4.5 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"
817+
/>
818+
</svg>
819+
);
820+
}

‎src/dev-toolbar/index.tsx‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,27 +26,31 @@ import {
2626
IssueIcon,
2727
MinimizeIcon,
2828
SolidIcon,
29+
TimelineIcon,
2930
TreeIcon,
3031
} from './icons.js';
3132
import { HighlightUpdatesOverlay } from './highlight-updates/overlay.js';
3233
import { installElementTracking, type InspectedComponent } from './inspector/lookup.js';
3334
import { InspectorOverlay } from './inspector/overlay.js';
35+
import { addIssues, captureIssues, type IssueEntry } from './issues/tracker.js';
3436
import { openInEditor } from './open-in-editor.js';
3537
import { excludeOwner, includeOwner } from './ownership/registry.js';
3638
import { excludeReactiveOwner, includeReactiveOwner } from './reactivity/registry.js';
37-
import { addIssues, captureIssues, type IssueEntry } from './issues/tracker.js';
39+
import { startTimeline, TimelineBuilder, type TimelineEntry } from './timeline/tracker.js';
3840
import './index.css';
3941

4042
const ErrorViewer = clientOnly(() => import('./error-viewer/index.js'), { lazy: true });
4143
const ReactivityViewer = clientOnly(() => import('./reactivity/index.js'), { lazy: true });
4244
const OwnershipViewer = clientOnly(() => import('./ownership/index.js'), { lazy: true });
4345
const IssuesViewer = clientOnly(() => import('./issues/index.js'), { lazy: true });
46+
const TimelineViewer = clientOnly(() => import('./timeline/index.js'), { lazy: true });
4447

45-
type Tab = 'err' | 'issues' | 'fn' | 'rx' | 'own';
48+
type Tab = 'err' | 'issues' | 'tl' | 'fn' | 'rx' | 'own';
4649

4750
const TABS: { value: Tab; label: string; icon: typeof ErrorIcon }[] = [
4851
{ value: 'err', label: 'Errors', icon: ErrorIcon },
4952
{ value: 'issues', label: 'Issues', icon: IssueIcon },
53+
{ value: 'tl', label: 'Timeline', icon: TimelineIcon },
5054
{ value: 'fn', label: 'Server functions', icon: FunctionIcon },
5155
{ value: 'rx', label: 'Reactivity', icon: GraphIcon },
5256
{ value: 'own', label: 'Ownership', icon: TreeIcon },
@@ -331,6 +335,8 @@ export function DevToolbar(props: DevToolbarProps) {
331335
const [graphFocus, setGraphFocus] = createSignal<{ node: object }>();
332336
// The graph can ask the ownership tree to show an owner the same way.
333337
const [ownershipFocus, setOwnershipFocus] = createSignal<{ owner: object }>();
338+
// The timeline can ask the server-function panel to show a call.
339+
const [functionsFocus, setFunctionsFocus] = createSignal<{ instance: string }>();
334340

335341
const [errors, setErrors] = createSignal<unknown[]>([]);
336342

@@ -374,6 +380,14 @@ export function DevToolbar(props: DevToolbarProps) {
374380
}
375381
const issueCount = createMemo(() => issues().reduce((total, entry) => total + entry.count, 0));
376382

383+
// The first action can come before the toolbar settles, so the timeline
384+
// starts during setup too.
385+
const timeline = new TimelineBuilder();
386+
const [timelineEntries, setTimelineEntries] = createSignal<TimelineEntry[]>([]);
387+
if (!isServer) {
388+
onCleanup(startTimeline(timeline, () => setTimelineEntries(timeline.snapshot())));
389+
}
390+
377391
const [instances, setInstances] = createSignal<
378392
Record<string, ServerFunctionInstance | undefined>
379393
>({});
@@ -600,6 +614,22 @@ export function DevToolbar(props: DevToolbarProps) {
600614
show('rx');
601615
}}
602616
/>
617+
<TimelineViewer
618+
show={visible('tl')}
619+
entries={timelineEntries()}
620+
onClear={() => {
621+
timeline.clear();
622+
setTimelineEntries([]);
623+
}}
624+
onViewCall={(instance) => {
625+
setFunctionsFocus({ instance });
626+
show('fn');
627+
}}
628+
onViewInGraph={(node) => {
629+
setGraphFocus({ node });
630+
show('rx');
631+
}}
632+
/>
603633
<ReactivityViewer
604634
show={visible('rx')}
605635
focus={graphFocus()}
@@ -620,6 +650,7 @@ export function DevToolbar(props: DevToolbarProps) {
620650
/>
621651
<ServerFunctionViewer
622652
show={visible('fn')}
653+
focus={functionsFocus()}
623654
instances={instances()}
624655
onDeleteInstance={(value) => {
625656
setInstances((current) => {
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
import type { ChangeRecord } from 'solid-js/attribution';
2+
import type { TimelineEntry, TimelineRun } from '../timeline/tracker.js';
3+
import { code } from './markdown.js';
4+
import { isSensitiveName, REDACTED, redactText, redactUrl } from './redact.js';
5+
6+
export interface TimelineReportInput {
7+
entry: TimelineEntry;
8+
/** The path and query of the page. */
9+
route: string;
10+
}
11+
12+
/** Most re-runs the report lists. The rest are counted. */
13+
const MAX_REPORT_RUNS = 50;
14+
15+
/**
16+
* A duration for reading. Browsers round the clock to 0.1ms or coarser, so a
17+
* shorter run reads as under that instead of as zero.
18+
*/
19+
export function ms(value: number | undefined): string {
20+
if (value === undefined) return '?';
21+
if (value < 0.1) return '<0.1ms';
22+
return value < 1 ? `${value.toFixed(2)}ms` : `${value.toFixed(1)}ms`;
23+
}
24+
25+
export function plural(count: number, word: string): string {
26+
return `${count} ${word}${count === 1 ? '' : 's'}`;
27+
}
28+
29+
/** `count` 0 → 1, with the values hidden when the name looks sensitive. */
30+
export function changeText(change: ChangeRecord): string {
31+
const name = code(change.name);
32+
if (change.kind !== 'write') return `${change.kind} ${name}`;
33+
if (change.value === undefined) return `write ${name}`;
34+
if (isSensitiveName(change.name)) return `write ${name} ${REDACTED}`;
35+
const prev = change.prev === undefined ? '' : `${redactText(change.prev)} → `;
36+
return `write ${name} ${prev}${redactText(change.value)}`;
37+
}
38+
39+
/** The changes that made a run happen, nearest first, each with what caused it. */
40+
export function causeLines(causes: ChangeRecord[], depth = 0): string[] {
41+
const out: string[] = [];
42+
for (const cause of causes) {
43+
const text = cause.kind === 'derived' ? `${code(cause.name)} changed` : changeText(cause);
44+
out.push(`${' '.repeat(depth)}- ← ${text}`);
45+
if (cause.causes?.length) out.push(...causeLines(cause.causes, depth + 1));
46+
}
47+
return out;
48+
}
49+
50+
function runLine(run: TimelineRun): string {
51+
const { event } = run;
52+
const notes: string[] = [ms(event.selfMs)];
53+
if (run.effectMs !== undefined) notes.push(`callback ${ms(run.effectMs)}`);
54+
if (!event.changed) notes.push('no change');
55+
if (event.phase !== 'plain') notes.push(event.phase);
56+
if (event.depsAdded.length) notes.push(`now reads ${event.depsAdded.map(code).join(', ')}`);
57+
if (event.depsRemoved.length)
58+
notes.push(`stopped reading ${event.depsRemoved.map(code).join(', ')}`);
59+
return `- ${event.nodeKind} ${code(event.nodeName)} (${notes.join(', ')})`;
60+
}
61+
62+
/** A Markdown report of what one action made the app do, for an agent to read. */
63+
export function timelineReport(input: TimelineReportInput): string {
64+
const { entry } = input;
65+
const { interaction } = entry;
66+
const out: string[] = [`# Solid update: ${code(entry.label)}`, ''];
67+
68+
out.push(`- Page: ${code(redactUrl(input.route))}`);
69+
if (interaction) {
70+
out.push(`- Outcome: ${interaction.outcome ?? 'pending'}`);
71+
if (interaction.inputDelayMs !== undefined) {
72+
out.push(`- Input delay: ${ms(interaction.inputDelayMs)}`);
73+
}
74+
out.push(`- Handler: ${ms(interaction.handlerMs)}`);
75+
if (interaction.continuationMs !== undefined) {
76+
out.push(`- Async handler continued for ${ms(interaction.continuationMs)}`);
77+
}
78+
out.push(`- Re-runs: ${interaction.runs}, ${ms(interaction.runMs)} in total`);
79+
if (interaction.created) out.push(`- Computations created: ${interaction.created}`);
80+
if (interaction.settledMs !== undefined) {
81+
out.push(`- Settled: ${ms(interaction.settledMs)} after the event`);
82+
}
83+
} else {
84+
out.push(`- Re-runs: ${entry.runs.length + entry.droppedRuns}`);
85+
}
86+
if (entry.flushes) out.push(`- Flushes: ${entry.flushes}, ${ms(entry.flushMs)}`);
87+
88+
if (entry.writes.length) {
89+
out.push('', '## Writes', '');
90+
for (const write of entry.writes) out.push(`- ${changeText(write)}`);
91+
}
92+
93+
if (entry.runs.length) {
94+
out.push('', '## Re-runs, in order', '');
95+
for (const run of entry.runs.slice(0, MAX_REPORT_RUNS)) {
96+
out.push(runLine(run));
97+
out.push(...causeLines(run.event.causes, 1));
98+
}
99+
const rest = entry.runs.length - MAX_REPORT_RUNS + entry.droppedRuns;
100+
if (rest > 0) out.push(`- … ${rest} more re-runs`);
101+
}
102+
103+
if (entry.calls.length) {
104+
out.push('', '## Server calls', '');
105+
for (const { event } of entry.calls) {
106+
const status = event.status === undefined ? 'no response' : String(event.status);
107+
const outcome = event.outcome === 'ok' ? '' : ', failed';
108+
out.push(
109+
`- ${event.method} ${code(event.name ?? event.id)} → ${status} in ${ms(event.durationMs)}${outcome}`,
110+
);
111+
}
112+
}
113+
114+
if (entry.holds.length) {
115+
out.push('', '## Holds', '');
116+
for (const hold of entry.holds) {
117+
const blockers = hold.blockers.length
118+
? `, waiting on ${hold.blockers.map(code).join(', ')}`
119+
: '';
120+
const silent = hold.acknowledgements.length ? '' : ', with no pending state shown';
121+
out.push(`- ${ms(hold.holdMs)}${blockers}${silent}`);
122+
}
123+
}
124+
125+
if (entry.navigations.length) {
126+
out.push('', '## Navigations', '');
127+
for (const navigation of entry.navigations) {
128+
const route = navigation.name ? `${code(navigation.name)} ` : '';
129+
out.push(`- ${route}to ${code(navigation.to ?? '?')}, ${navigation.outcome ?? 'pending'}`);
130+
}
131+
}
132+
133+
return out.join('\n');
134+
}

0 commit comments

Comments
 (0)