@node-projects/speedscope 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,385 @@
1
+ # Search across profiles and arrange Sandwich panes
2
+
3
+ ## Choose a profile with the keyboard
4
+
5
+ For a recording with several profiles, click the profile name in the toolbar or
6
+ press **t** to open the chooser. The **Filter profiles** combobox receives focus.
7
+ Type part of a thread/profile name to filter with the existing fuzzy matching.
8
+ Queries are limited to 256 characters. The result list identifies the currently
9
+ selected profile separately from the active keyboard result.
10
+
11
+ Use **Up/Down** to move the active result, **Home/End** to reach either end and
12
+ **Page Up/Page Down** to move by a results page. **Enter** selects the active
13
+ profile. **Escape** or **Close** dismisses the chooser and returns focus to its
14
+ trigger. Typing during an input-method composition does not activate results;
15
+ modified editing shortcuts such as Ctrl/Command+A retain their normal behavior.
16
+ Typing in the chooser does not trigger the viewer's global shortcuts.
17
+
18
+ The result list exposes a listbox with selected state, an active descendant and
19
+ each result's position in the full filtered set. Native buttons sort by index,
20
+ name or total non-idle weight and report the active direction. Tab can reach the
21
+ sort, page and Close controls; moving focus outside dismisses the chooser without
22
+ pulling focus back from the next control. Clicking an option also selects it.
23
+
24
+ At most **100 options** are mounted at a time. Keyboard navigation automatically
25
+ switches result pages, and **Previous/Next** page buttons make other results
26
+ available without rendering every profile row. The result range is displayed
27
+ explicitly. Filtered/sorted results retain numeric profile indices; highlight
28
+ ranges are calculated only for the displayed page. Filtering and sorting still
29
+ scan or arrange the recording's profile list, so the DOM bound is not a total
30
+ memory or processing-time guarantee. This improves the chooser's portion of
31
+ [#376](https://github.com/jlfwong/speedscope/issues/376); it does not make the
32
+ canvas charts or every viewer control fully accessible.
33
+
34
+ ## Regular expression search
35
+
36
+ The viewer and Search all profiles offer **Regex (RE2)** alongside the existing
37
+ literal Contains, Whole word and Exact modes. Enter a pattern directly, such as
38
+ `^render|worker[0-9]+` or `\.tsx?$`, without JavaScript `/.../flags` delimiters.
39
+ Matching starts case-insensitive; RE2 inline flags can adjust it. Both function
40
+ names and source paths are searched in full, with no symbol truncation.
41
+
42
+ The engine is the pinned MIT-licensed
43
+ [`re2js` 2.10.0](https://github.com/le0pard/re2js/tree/2.10.0), a pure JavaScript
44
+ RE2 port. It uses linear-time matching rather than executing user patterns with
45
+ native JavaScript's backtracking engine. Backreferences and lookaround are
46
+ unsupported here and produce an error. RE2 syntax differs from JavaScript
47
+ RegExp syntax; the app does not translate unsupported expressions or silently
48
+ switch engines. Literal modes keep their previous behavior.
49
+
50
+ Patterns are limited to 256 UTF-16 characters. A conservative preflight rejects
51
+ counted-repeat bounds above 1,000 or estimated expansions above 4,096 states
52
+ before compilation; the compiled program also has a 4,096-state ceiling. This
53
+ can reject some otherwise valid RE2 expressions; simplify their repetitions.
54
+ Invalid syntax and limits appear as errors in the search UI, without replacing
55
+ the profile or crashing its rendering. Empty patterns match nothing. Zero-width
56
+ matches select frames but do not paint nonexistent characters. Highlight offsets
57
+ use UTF-16 indices, including after astral characters, as the existing label
58
+ renderer expects.
59
+
60
+ One compiled pattern is cached for validation/reuse; existing bounded frame and
61
+ highlight caches and navigation/result caps still apply. At most 64 match
62
+ attempts per visible label are used for highlights, counting zero-width matches
63
+ toward this budget. Boolean matching still scans the complete symbol. Search
64
+ across profiles yields between bounded batches; synchronous matching of an
65
+ individual exceptionally long symbol can still take time proportional to its
66
+ length. This is not a fixed wall-time guarantee or a cap on profile storage.
67
+
68
+ The dependency has no runtime dependencies or external WASM/network load. An
69
+ isolated esbuild minified browser import measured approximately 151 KB (46 KB
70
+ gzip); final app bundle size depends on bundling and compression.
71
+
72
+ A local PLC regression scanned 513,009 occurrences with a no-match regex in
73
+ 30 ms and retained about 0.60 MiB of search state after collection. A broad
74
+ `^.*` query reached the existing 10,000-result navigation ceiling in 6 ms and
75
+ retained about 1.02 MiB. Both runs preserved four profiles, 17,510 exported
76
+ frames, 1,039,656 events and export hash
77
+ `522de77afbfc4dd94f1f30c3a9551979d12db506305ffef999db9c910ae8eddb`.
78
+ These are individual Windows ARM64 Node observations, not browser latency or
79
+ total-memory guarantees; they exclude import and initial flamechart creation.
80
+
81
+ ## Search all profiles
82
+
83
+ Choose **Profile actions → Search all profiles…**, enter a function name or source
84
+ path, and press Search or Enter. Contains, Whole word and Exact modes use the same
85
+ case-insensitive literal matching as the single-profile search. File paths are
86
+ searched too. There are no arbitrary regular expressions.
87
+
88
+ Each result represents one frame in one profile, with its source location and
89
+ that profile's total/self weights. Different threads and same-named functions in
90
+ different files remain separate. Weights are not added together, and results may
91
+ have different units. Derived profiles are excluded by default; select **Include
92
+ derived profiles** when you want to search filtered/combined views as well.
93
+
94
+ Open a result to switch to its original profile and select that frame in Sandwich.
95
+ Its callers, callees and ordinary search highlights are available there. This also
96
+ works when recursion flattening is enabled. No combined profile or transformed
97
+ recording is created. Replacing the source profiles invalidates pending searches
98
+ and prevents stale results navigating into a different recording.
99
+
100
+ The dialog shows at most 200 results and stops scanning when it finds a further
101
+ match. A truncation message asks you to refine the query; the number shown is not
102
+ claimed to be the complete number of matches. Queries are limited to 4,096
103
+ characters. Editing search options clears the previous results; submit again to
104
+ search with the new settings. Cancel search stops unfinished work, while Close or
105
+ Escape closes the dialog. Clipboard input stays inside the dialog.
106
+
107
+ The search iterates frames lazily and yields based on both frame count and symbol
108
+ text size. It does not enumerate every call occurrence or allocate an unbounded
109
+ result table. Navigation and the existing viewer still have normal profile,
110
+ recursion-flattening, sorting, highlight and rendering costs; the result limit is
111
+ not a hard cap on total browser memory or the cost of opening a large profile.
112
+ A local PLC smoke check searched 17,510 frames across four profiles, found 40
113
+ matches without truncation, and left all profile totals unchanged. It took about
114
+ 148 ms with ten yields in that Node run; this is not a browser latency guarantee.
115
+
116
+ ## Keep a function selected across views
117
+
118
+ Selecting a function in Time Order, Left Heavy or Sandwich now carries that
119
+ function into the other two views of the same profile. Selection uses the frame
120
+ key, so same-named functions from different files remain distinct. Each view
121
+ keeps its own valid call-tree instance and zoom. If it has no instance for the
122
+ newly selected function, it chooses the first matching node in that view's
123
+ depth-first tree order. The view does not automatically change its time range;
124
+ an instance can therefore be outside the current zoom. Search navigation remains
125
+ available to select and zoom into a particular occurrence.
126
+
127
+ Clearing selection carries across views too. Different profiles/threads retain
128
+ their own selection; a newly imported group or newly created derived profile
129
+ starts fresh. Call Tree retains its independent expansion controls.
130
+
131
+ Toggling recursion flattening keeps the function key but discards node/hover and
132
+ caller/callee references from the old tree. Selection is resolved against the
133
+ new visible model. Its aggregate/derived flags are now retained as well, so
134
+ flattening does not accidentally enable Time Order for aggregate data or make a
135
+ derived view count as an original recording.
136
+
137
+ Only one resolved node per graph view and primitive selection keys are stored.
138
+ Model identities use weak keys; there is no per-function occurrence index or
139
+ additional profile copy. A first lookup can scan an entire target tree with
140
+ O(depth) traversal storage. Resolved matches and absent occurrences are reused
141
+ until the model/function changes, so hover and pan updates do not rescan the
142
+ tree. Clearing hovers now emits at most one state update rather than four.
143
+ Cross-profile search resolves directly into Sandwich instead of scanning the
144
+ outgoing graph for an unused occurrence. UI selection is not exported.
145
+
146
+ This implements [#107](https://github.com/jlfwong/speedscope/issues/107).
147
+ Targeted tests cover distinct source files, exact per-view instances, profile
148
+ isolation, empty groups, transformed models, unchanged hover updates and a
149
+ 30,000-level tree. In a PLC Node smoke check, first-occurrence lookup for the
150
+ last source frame took about 7.6 ms in Time Order and 5.5 ms in the grouped tree;
151
+ the full export hash remained unchanged. These are individual measurements,
152
+ not browser responsiveness guarantees.
153
+
154
+ ## Navigate the overview
155
+
156
+ The overview above Time Order and Left Heavy shows an outlined **Visible range**
157
+ for the main graph. The outline uses the theme's foreground and background
158
+ colors together, so it stays distinct from colored frames. Very narrow ranges
159
+ get a minimum visible outline width, without changing the actual viewport or
160
+ profile weights. The outline is clipped below the overview's time axis.
161
+
162
+ Hover inside the visible range for a grab cursor; drag to pan. Outside it, a
163
+ crosshair indicates that dragging selects a new horizontal range. Only the
164
+ primary mouse button starts a drag. Releasing outside the overview, the window
165
+ losing focus, pressing Escape, switching profiles/views or replacing the canvas ends
166
+ the gesture and removes its window listeners. Escape keeps the last viewport.
167
+ Hover cursor changes stay local to the overview, and an active drag restores
168
+ the prior page cursor when it ends.
169
+
170
+ Tab to **Profile overview** to use the keyboard. Left/Right pan by 10% of the
171
+ current width; Up/Down pan by 10% of the viewport height, with a minimum of one
172
+ row. Shift increases these steps to 50%. Plus/Equals halves the width around
173
+ the current center; Minus doubles it. Shift uses quarter/fourfold zoom steps.
174
+ Home restores the full horizontal range and returns to the top. Existing zoom
175
+ and viewport bounds still apply. Modified browser shortcuts such as Ctrl+F
176
+ are left available. A focus outline and accessible description expose the
177
+ current range and controls. This improves overview access without claiming
178
+ that all canvas charts are screen-reader accessible.
179
+
180
+ All overlay and keyboard calculations use only current viewport dimensions;
181
+ they do not scan call occurrences, retain another profile or build an index.
182
+ This implements [#240](https://github.com/jlfwong/speedscope/issues/240) and
183
+ [#241](https://github.com/jlfwong/speedscope/issues/241), and advances
184
+ [#376](https://github.com/jlfwong/speedscope/issues/376).
185
+
186
+ Validation on 2026-11-21 passed 362 Jest tests across 64 suites (307 snapshots),
187
+ five Node tests, type checking, linting, schema/backlog checks and both builds.
188
+ Browser checks verified keyboard zoom/pan/reset, Ctrl+F, pointer pan/range
189
+ selection, restored page cursors and the outline in light/dark themes without
190
+ console errors. A context-replacement regression ensures redraws use the new
191
+ canvas rather than scheduling a stale frame on the old one. PLC streaming
192
+ retained four profiles, 17,510 frames and 1,039,656 call events with its baseline
193
+ export hash; the Node import smoke took about 2.5 seconds. This does not measure
194
+ browser frame rate or establish a total heap cap.
195
+
196
+ ## Bounded graph search
197
+
198
+ Time Order and Left Heavy search navigate at most the first 10,000 matching call
199
+ occurrences in depth-first order. If there are more, the count shows `10000+`
200
+ and a visible status asks you to refine your search. This is a lower bound,
201
+ not the full count. Previous/Next and Enter/Shift+Enter wrap within the retained
202
+ window. A selected frame outside that window shows `?` for its navigation index.
203
+ Use a more specific name/path or Whole word/Exact/Regex mode to narrow the query.
204
+
205
+ Matching and graph highlights still inspect full names and source paths, even
206
+ outside the navigation window. Sparse queries can find late occurrences: the
207
+ limit applies to retained matches, not the number of frames searched. Showing
208
+ the limit requires finding one further match, so exactly 10,000 results are
209
+ reported as complete. No widths, weights or exported symbols are changed.
210
+ Search zoom also keeps root-level result labels below the time axis, including
211
+ short charts whose general viewport clamp would otherwise cover the first row.
212
+
213
+ Symbol matching is lazy. Each query caches at most 4,096 boolean frame results
214
+ and 512 highlight lists, evicting old entries and recomputing them when needed.
215
+ Only labels/rows being drawn request name-highlight ranges, capped at the first
216
+ 64 ranges per name. A long, repetitive name can therefore match beyond its
217
+ drawn underlines. File-only matches have no name underlines. Search input is
218
+ limited to 4,096 characters in literal modes; Regex has the separate 256-character and compilation limits described above.
219
+
220
+ Search no longer builds a full per-symbol highlight map or a rectangle for
221
+ every matching call. Traversal uses O(depth) auxiliary storage and creates a
222
+ navigation rectangle only when a result is opened. Rare/no-match queries can
223
+ still scan an entire graph synchronously; bounded caches can require repeated
224
+ text matching. Existing profile models, graph geometry and Sandwich row lists
225
+ still scale with recording size. Cross-profile search retains its separate
226
+ 200-result limit and cancellation behavior.
227
+
228
+ ## Resize Sandwich panes
229
+
230
+ Select a function in Sandwich to show the table, callers and callees. Drag the
231
+ vertical divider to resize the table against the graphs. Drag the horizontal
232
+ divider to change the callers/callees split. Graph viewports update as you resize.
233
+
234
+ Both dividers are keyboard-focusable separators. Use Left/Right on the table
235
+ divider and Up/Down on the callers/callees divider. Each press moves 2 percentage
236
+ points; hold Shift for 10. Home and End move to the permitted limits. Enter or a
237
+ double-click restores the equal split. Other application shortcuts still work.
238
+
239
+ Pane sizes are clamped to avoid hiding either side, including on small windows.
240
+ Preferences are saved in this browser's local storage on completed drags and
241
+ keyboard actions. They survive reloads and profile changes, but are not part of
242
+ the exported profile. Invalid or unavailable browser storage falls back safely.
243
+
244
+ ## Navigate selected-stack ancestors
245
+
246
+ In Time Order or Left Heavy, select a graph frame to show its stack details.
247
+ Each scope name is now a keyboard-focusable button. Click it or press Enter/Space
248
+ to select that exact ancestor call instance and update its statistics/highlight.
249
+ If the ancestor is above the graph viewport, the graph scrolls up to include it;
250
+ the horizontal range stays unchanged. Source-location links remain separate.
251
+
252
+ Details show at most 100 scopes at a time, starting with the selected frame.
253
+ **Show older ancestors** advances toward the root. **Back to selected frame**
254
+ returns to the start. Selecting a scope starts a fresh page at that scope. This
255
+ keeps the number of DOM rows and source links bounded even for very deep stacks.
256
+ Paging follows only the next 100 parent pointers and retains no complete
257
+ ancestor list or page history. Selecting an ancestor walks its parent chain to
258
+ determine its graph depth, using constant auxiliary space.
259
+
260
+ The helper regression covers a 100,000-level chain and fails if a page walks
261
+ beyond its boundary. UI tests cover paging, exact-instance selection and focus
262
+ restoration. The PLC trace's deepest stack has seven scopes, so it fits on one
263
+ page without changing the imported profile.
264
+
265
+ This implements [ancestor navigation (#350)](https://github.com/jlfwong/speedscope/issues/350).
266
+
267
+ ## Identify recordings and selected functions
268
+
269
+ The browser/window title shows the current file's leaf name, followed by the
270
+ internal recording name when it differs. Thread names remain unchanged in the
271
+ toolbar. A `title` hash parameter still overrides the window title. File names
272
+ are kept as runtime context through worker loading, derived profiles and symbol
273
+ remapping. They are not added to exports: opening an exported recording shows
274
+ the name of that newly opened file. Absolute local directories are discarded
275
+ from this metadata and displayed leaf names are limited to 1,024 characters.
276
+
277
+ Sandwich now shows a **Selected function details** panel above its graphs.
278
+ It displays the full symbol name and source file/line/column, so same-named
279
+ functions from different modules can be distinguished without a hover tooltip.
280
+ Configured source-code links work there too. Missing source metadata is stated
281
+ explicitly. Long names wrap inside a scrollable panel capped at 120 pixels;
282
+ only the selected function gets this panel, without adding a column or index
283
+ across the entire recording.
284
+
285
+ ## Understand the statistics
286
+
287
+ Open **About these statistics** in selected-stack details for contextual help.
288
+ **This Instance** measures the selected call-tree node. In Time Order that node
289
+ represents its call context; in Left Heavy, a node can group multiple calls in
290
+ the same stack context. **All Instances** measures that function across the
291
+ current profile. **Total** includes work in callees; **Self** excludes it.
292
+ Values use the profile's units, including time, bytes or samples.
293
+
294
+ The detail-panel percentages use the entire current profile's weight, including
295
+ idle weight. Sandwich table percentages use its non-idle weight, as explained
296
+ in the column headers. Filtered profiles use their retained weight. For example,
297
+ six units of total work with four self units in a ten-unit recording display
298
+ 60% total and 40% self in details, even when the other four units are idle.
299
+ Zero-weight denominators display 0% with finite bars. Percentage calculations
300
+ also avoid overflow from multiplying very large finite weights by 100 first.
301
+
302
+ These changes implement [#363](https://github.com/jlfwong/speedscope/issues/363),
303
+ [#242](https://github.com/jlfwong/speedscope/issues/242) and
304
+ [#219](https://github.com/jlfwong/speedscope/issues/219).
305
+
306
+ Validation on 2026-11-21 passed all 346 Jest tests across 60 suites (307
307
+ snapshots), five Node tests, type checking, linting, schema/backlog checks and
308
+ both builds. Browser smoke checks covered same-named functions from different
309
+ files, recording/custom titles and expanded statistics help without console
310
+ errors. A PLC streaming smoke retained four profiles, 17,510 frames and
311
+ 1,039,656 call events with the baseline export hash; its import took about
312
+ 2.4 seconds in that Node run. These UI changes add no per-frame context index or
313
+ profile copy. Source-name metadata is one bounded string per group.
314
+
315
+ ## Refocus a search match
316
+
317
+ Graph search offers **Zoom to match** once a retained result is selected. After
318
+ zooming or panning away, use it to center that same match with a little context.
319
+ The action changes only the viewport: measured widths and profile weights stay
320
+ intact. Ordinary next/previous navigation is unchanged, and the existing 10,000
321
+ result cap and numerical zoom limits still apply. Very small matches may reach
322
+ those precision limits. Sandwich's table search does not add this graph action.
323
+
324
+ This partially addresses [#548](https://github.com/jlfwong/speedscope/issues/548);
325
+ artificially inflating tiles in an overview remains separate work.
326
+
327
+ ## Share function links
328
+
329
+ Select a function in Time Order, Left Heavy or Sandwich, then choose **Profile
330
+ actions → Link to selected function…**. Review and copy the generated URL in the
331
+ dialog. When opened with the same recording, it selects the matching profile and
332
+ function in Sandwich. Local files are not uploaded or embedded: the recipient
333
+ must import the same recording after opening the link. For an HTTP recording,
334
+ the link retains its URL and Accept setting only when associated with the actual
335
+ loaded profile. Opening another local file does not reuse an old remote URL.
336
+
337
+ The link stores a versioned profile index/name/unit/total and function
338
+ name/file/line/column identity. Importer-assigned frame keys can change without
339
+ breaking it. Multiple identical source identities are rejected rather than
340
+ silently selecting another frame. Selection JSON is limited to 8,192 characters
341
+ and complete links to 65,536; existing data/file profile URLs and local paths are
342
+ not copied. Function/source names and an HTTP URL's credentials can appear in the
343
+ reviewable link. It cannot grant access to a remote recording.
344
+
345
+ Matching scans the chosen profile's frames once, without a retained frame index.
346
+ Only the first successful restoration for a link is applied; later imports do not
347
+ jump back to that selection. Navigating to another function link in the same tab,
348
+ including browser Back/Forward, restores its selection against the current
349
+ recording without reimporting it. Missing or ambiguous matches show a status
350
+ message and remain pending until the original recording is imported.
351
+ Changing the HTTP profile source or Accept setting starts a cancellable import.
352
+ A new remote link takes precedence over a pending import of another recording;
353
+ selection-only changes during import apply when that import finishes.
354
+ Derived profiles must be exported and reopened first. Symbol-remapped copies
355
+ conservatively generate links requiring local reimport.
356
+
357
+ This partially addresses [#506](https://github.com/jlfwong/speedscope/issues/506).
358
+ Exact call instances, graph view/zoom/time range and profile transformations are
359
+ not restored. Function links select the matching symbol in Sandwich, rather than
360
+ restoring a specific call occurrence or graph viewport.
361
+
362
+ ## Upstream review history
363
+
364
+ The 2026-11-21 shared-selection, Java text-dump, hosted-offline and numerical
365
+ test follow-up passed all 393 Jest tests across 68 suites (307 snapshots), five
366
+ Node tests, type checking, lint, schema/backlog checks, both release builds and
367
+ npm package-content checks. Binary JFR signatures take precedence over embedded
368
+ thread-dump text; the existing unnamed-recording regression covers this case.
369
+ Browser checks covered per-view occurrence retention, same-named source frames,
370
+ recursion/derived profiles, and importing a local Java dump after stopping the
371
+ preview server. An uncached remote recording correctly failed offline.
372
+
373
+ The private PLC streaming check retained four profiles, 17,510 exported frames
374
+ and 1,039,656 call events with SHA-256
375
+ `522de77afbfc4dd94f1f30c3a9551979d12db506305ffef999db9c910ae8eddb`
376
+ (shared data followed by each exported profile, hashed separately). Its final
377
+ Node run took about four seconds to import, with first-occurrence lookup for
378
+ the last source frame taking 5.4 ms in Time Order and 4.2 ms in Left Heavy.
379
+ These are local smoke measurements, not browser performance guarantees.
380
+
381
+ On 2026-11-20, the 30 most recently created open upstream issues were checked.
382
+ Their IDs were already present in the existing 134-issue inventory. This is a
383
+ targeted feature check, not a fresh audit of every issue's open/closed state.
384
+ This follow-up implements [cross-process search (#396)](https://github.com/jlfwong/speedscope/issues/396)
385
+ and [resizable Sandwich panes (#209)](https://github.com/jlfwong/speedscope/issues/209).
@@ -0,0 +1,55 @@
1
+ # Single-HTML build
2
+
3
+ From a repository checkout with dependencies installed, run:
4
+
5
+ ```sh
6
+ npm run build:single-file
7
+ ```
8
+
9
+ The result is `dist/speedscope-standalone.html`. Application code, CSS, fonts,
10
+ icons, the example recording, import-worker code and WebAssembly decoders are
11
+ embedded in that document. It needs no companion assets or source maps. The
12
+ license texts included in the existing standalone release remain in the HTML
13
+ as inert JSON, alongside bundle license comments. CI builds this option on
14
+ Windows/Linux and uploads it with each standalone artifact.
15
+
16
+ Combined validation passed 413 Jest tests in 71 suites, 307 snapshots, five
17
+ Node tests, type checking, lint and schema/backlog checks. Browser QA imported
18
+ the embedded example, local JFR and the private PLC gzip from this one document;
19
+ the preview server logged only the document request and browser errors were
20
+ empty. The browser tool blocks file-protocol navigation, so no `file://` startup
21
+ claim is made here.
22
+
23
+ Serve the document from your own HTTP server or copy it for portable use. It
24
+ registers no service worker and contains no recording supplied by the user.
25
+ Local imports stay in the browser. Explicit remote recording links still need
26
+ their server and CORS permissions. The existing multi-file standalone ZIP,
27
+ CLI and hosted Pages builds remain available independently.
28
+
29
+ ## Content Security Policy
30
+
31
+ One document simplifies deployment but does not remove the app's CSP needs.
32
+ The build prints the SHA-256 source hash for its inline application script;
33
+ use that exact build-specific value in `script-src` if allowing inline code
34
+ by hash. Rebuilding changes the hash. Workers use Blob URLs; decoders use
35
+ WebAssembly; fonts and icons use data URLs. Aphrodite and component styles
36
+ still require dynamically inserted styles and inline style attributes.
37
+
38
+ Browser verification used the following HTTP response policy, serving only
39
+ the HTML document and rejecting all other request paths:
40
+
41
+ ```text
42
+ default-src 'none'; script-src 'unsafe-inline' 'wasm-unsafe-eval' blob:; style-src 'unsafe-inline'; font-src data:; img-src data:; connect-src data:; worker-src blob:;
43
+ ```
44
+
45
+ That policy allowed the embedded example and local JFR/PLC imports without
46
+ companion requests. It blocks remote recordings and source-map network fetches;
47
+ add only the required remote origins to your own deployment's `connect-src`.
48
+ This is an observed deployment example, not a recommendation to relax an
49
+ existing application's policy. Strict policies forbidding inline styles still
50
+ need a style-engine/attribute integration strategy. Browser file-URL startup
51
+ could not be checked by the browser automation tool, which permits HTTP(S) only.
52
+
53
+ This extends [#108](https://github.com/jlfwong/speedscope/issues/108) with a true
54
+ single-document option. Strict-CSP embedding and a supported multi-instance
55
+ library API remain separate work.
@@ -0,0 +1,184 @@
1
+ # Source maps, source-code links and compact graph labels
2
+
3
+ ## Load a linked JavaScript source map
4
+
5
+ Choose **Profile actions → Load linked source map…** after loading a recording.
6
+ Enter the generated JavaScript's HTTP(S) URL as it appears in the recording.
7
+ The dialog suggests the selected function's HTTP(S) source URL when available.
8
+ Opening the dialog or selecting a function performs no network request.
9
+
10
+ 1. Choose **Load preview** to fetch that script and its linked source map.
11
+ 2. Review the generated-script URL, resolved map URL and number of frames that
12
+ would change. The recording remains unchanged during preview.
13
+ 3. Choose **Apply source map** to update matching symbols and source locations
14
+ across the loaded profiles. Weights, profile flags and recording metadata
15
+ remain intact. Editing the URL invalidates the preview.
16
+
17
+ The map applies only to the chosen generated-script URL, including its query
18
+ string. It may have a different or hashed filename. Relative original-source
19
+ URLs are resolved against the fetched map URL; original source files are never
20
+ fetched. A script's exposed `SourceMap` response header takes precedence over
21
+ `X-SourceMap` and its trailing `sourceMappingURL` comment. JavaScript comments
22
+ are located with a tokenizer, so annotation-like text inside strings and
23
+ templates cannot initiate a map request. The script is never executed.
24
+
25
+ Both requests omit cookies and other credentials, use CORS and `no-store`, and
26
+ reject redirects. Use a direct URL whose server allows cross-origin access.
27
+ For a cross-origin `SourceMap` header, the server must also expose that header
28
+ with `Access-Control-Expose-Headers`. HTTP errors, CORS failures, missing links
29
+ and unmatched source positions stay visible in the dialog. **Cancel load**,
30
+ Escape and Close abort pending work. Importing another recording or changing
31
+ the profile models closes the dialog and invalidates its captured preview.
32
+
33
+ The downloaded script body is limited to 8 MiB when it must be inspected; an
34
+ exposed map header allows its body to be cancelled immediately. A map is limited
35
+ to 2 MiB. Before decoding mappings, the loader limits their encoded segment
36
+ count to 100,000 across nested index maps, with at most 1,000 indexed sections,
37
+ 32 nesting levels and 128 encoded characters in one VLQ segment. The preview
38
+ retains at most 100,000 changed frames. Loading has a 30-second timeout and yields
39
+ between token/preview batches so cancellation can be handled. These limits
40
+ bound the additional work; they do not make the underlying recording independent
41
+ of browser memory limits.
42
+
43
+ For local scripts/maps, choose **Import** and open the `.map` file after loading
44
+ your recording. This also provides a fallback when CORS or credentials prevent
45
+ remote loading, a limit is exceeded, or the generated script cannot be fetched.
46
+ Both workflows need usable recorded line and column positions.
47
+ The browser does not read arbitrary local paths from a recording. Inline
48
+ `data:` maps, non-HTTP(S) links and URLs containing embedded credentials are
49
+ unsupported in the linked-map dialog. JavaScript syntax unrecognized by its
50
+ ES2020 tokenizer requires an exposed map header or local-map import.
51
+
52
+ This is explicit linked-map discovery for upstream
53
+ [#446](https://github.com/jlfwong/speedscope/issues/446), not automatic filesystem
54
+ discovery for Node/esbuild logs. Logs without usable source positions still
55
+ cannot be mapped. The linking/header behavior follows
56
+ [ECMA-426](https://tc39.es/ecma426/2024/#sec-retrieving-source-maps).
57
+
58
+ ## Embedded source-line lookup
59
+
60
+ Unnamed source-map entries can infer a symbol from embedded original-source
61
+ text. Lookup now uses sparse newline checkpoints instead of repeatedly scanning
62
+ from the start or splitting the entire source into a line array. A per-remapper
63
+ LRU retains at most 16 source indexes, each with at most 4,096 Uint32 checkpoints:
64
+ **256 KiB maximum retained checkpoint storage**, excluding source strings and
65
+ the mapping consumer. Checkpoints begin every 64 lines and become coarser for
66
+ very long local sources. Arbitrary query order, CRLF, empty/final lines and
67
+ replacement source contents preserve the same inferred names.
68
+
69
+ Preview checks elapsed time as well as frame count, yielding after 8 ms or 128
70
+ frames. SourceMapConsumer decoding remains synchronous under the existing linked
71
+ map size/mapping limits; these changes do not make all map loading interruptible.
72
+
73
+ Run `npx tsx scripts/benchmark-source-maps.ts` for the deterministic comparison.
74
+ One Node 24.19.0 ARM64 run used 100,000 source lines (2,488,889 characters) and
75
+ 5,000 shuffled line queries: the old scan took 2,722 ms and indexed lookup 11 ms,
76
+ with identical checksums and an 8 KiB index. Mapping 100,000 shuffled frames took
77
+ 169 ms with no mismatches. This is a local-source lookup/remapping measurement,
78
+ excluding network and browser rendering. The synthetic embedded source is larger
79
+ than the linked-map download cap; local-map imports do not use that download cap.
80
+
81
+ ## Open a source location
82
+
83
+ Choose **Profile actions → Source-code links…** after loading a recording.
84
+ Select Visual Studio Code, Visual Studio Code Insiders, or a custom HTTP(S) URL.
85
+ Saving turns source locations in Call Tree and the selected stack's details into
86
+ links. A link opens only when clicked. Disable links in the same dialog.
87
+ Frames without a source file keep their ordinary display.
88
+
89
+ For local editors, the mapped path must be absolute. For example, replace recorded
90
+ prefix `/build/project` with `C:/work/project` to open `/build/project/src/app.ts`
91
+ in your local checkout. Windows separators and file URLs are accepted; Windows
92
+ prefix comparisons ignore case. Prefixes match whole leading path segments,
93
+ so `/build/app` does not match `/build/application`. Locations outside a configured
94
+ prefix stay plain text. Leave both prefixes empty to use the recorded path.
95
+
96
+ The editor presets use the official [VS Code file URI format](https://code.visualstudio.com/docs/configure/command-line#_opening-vs-code-with-urls),
97
+ with the recorded line and column, or 1 when unavailable. Your browser may ask to
98
+ open the editor. The viewer does not check that a local file exists.
99
+
100
+ Custom web templates require a fixed HTTP(S) host and a `{file}` placeholder.
101
+ Optional `{line}` and `{column}` placeholders insert source coordinates.
102
+ For example:
103
+
104
+ ```text
105
+ https://github.com/owner/repository/blob/main/{file}#L{line}
106
+ ```
107
+
108
+ Map a build prefix to an empty replacement to produce repository-relative paths.
109
+ File path segments are URL-encoded, preserving their separators. Embedded
110
+ credentials, other protocols, unknown placeholders and variable hosts are rejected.
111
+ The dialog previews the generated URL without opening it. Choose the repository
112
+ and revision matching the recording; links do not fetch or discover source maps.
113
+
114
+ Settings persist in this browser's local storage. They are not included in an
115
+ exported profile. If storage is unavailable, settings work for the current session.
116
+
117
+ ## Shorten graph path labels
118
+
119
+ Choose **Profile actions → Compact graph path labels** to draw only the final
120
+ component of path-like frame names. Choose **Show full graph labels** to restore
121
+ the original labels. This preference also persists in this browser.
122
+
123
+ Full frame names remain available in hover details, Call Tree, Sandwich's table,
124
+ search and exports. Function signatures containing path-like punctuation are
125
+ preserved. Search still matches the full name: a match entirely inside a hidden
126
+ prefix can highlight a frame without underlining text in its displayed suffix.
127
+
128
+ ## Producer-selected frame colors
129
+
130
+ Native `.speedscope.json` producers can set an optional `color` on each shared
131
+ frame. Use exactly six RGB hex digits, such as `"color": "#8A2BE2"`. Short hex,
132
+ alpha channels, named colors and CSS expressions are rejected. Frames without
133
+ this field keep the normal generated theme colors.
134
+
135
+ ```json
136
+ {"name": "compiled method", "file": "example.rb", "line": 12, "color": "#8A2BE2"}
137
+ ```
138
+
139
+ The main flamechart, minimap and function color indicators honor the supplied
140
+ color in both themes. If a color would hide the normal frame label, its displayed
141
+ RGB is mixed toward the active theme background until the label has at least
142
+ 4.5:1 contrast. Unmatched search labels retain the existing dimmed style, and
143
+ search highlights and selection outlines remain visible above the frame color.
144
+ Comparison flamegraphs continue to use their signed-difference colors.
145
+
146
+ The original RGB spelling survives imports, worker transport and both export
147
+ paths unchanged; theme adjustments affect presentation only. Producers can use
148
+ separate shared-frame entries for the same function when it needs different
149
+ colors. Combining profiles preserves different RGB identities while treating
150
+ upper- and lowercase spellings of the same RGB as equivalent.
151
+
152
+ Each graph renderer retains at most 65,025 distinct custom colors in one fixed
153
+ 256 KiB palette, allocated only when a custom color occurs. Additional colors
154
+ fall back to generated colors in that graph, with one console warning. Their raw
155
+ RGB values still survive export, and table indicators can still display them.
156
+ Vertex buffers retain their existing stride, and cached and direct graph draws
157
+ use the same palette. This does not impose a bound on the recording itself.
158
+
159
+ This implements the producer-color request in upstream
160
+ [#351](https://github.com/jlfwong/speedscope/issues/351). It does not add an editor
161
+ for assigning colors to frames in an already loaded recording. See
162
+ [`custom-colors.speedscope.json`](../sample/profiles/speedscope/custom-colors.speedscope.json)
163
+ for a complete example.
164
+
165
+ ## Large traces
166
+
167
+ Neither setting reimports or transforms a recording. Labels are shortened only
168
+ when drawn; source URLs are generated for mounted source locations. Settings
169
+ preview inspects at most 200 frames for a source example and otherwise uses an
170
+ editable example path. No per-frame URL table or second profile is retained.
171
+ Existing graph, call-tree and selected-stack rendering costs still apply.
172
+
173
+ Validation on 2026-11-20 passed all 334 Jest tests (307 snapshots), five Node tests,
174
+ type checking, linting, schema/backlog checks and both application builds.
175
+ Browser checks covered editor and web mappings, persistence, disabling links,
176
+ compact labels and unchanged full names in hover/stack details, with no console
177
+ errors. The private PLC trace streamed in approximately 2.6 seconds; running the
178
+ display helpers across its 17,510 frames took about 3.7 ms in that Node smoke
179
+ check. Its four profiles and 1,039,656 exported call events retained the baseline
180
+ export hash. These measurements do not include browser rendering or hydration,
181
+ and the capture and benchmark artifacts are not committed.
182
+
183
+ These features implement upstream requests [#410](https://github.com/jlfwong/speedscope/issues/410)
184
+ and [#373](https://github.com/jlfwong/speedscope/issues/373).