@node-projects/speedscope 2.1.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,118 @@
1
+ # Compare profiles
2
+
3
+ Open a recording, then choose **Profile actions → Compare profiles…**. Select a
4
+ baseline and candidate from the loaded profiles, or use **Open comparison
5
+ recording…** to load a second local recording in any supported format. Choose
6
+ its profile and click **Compare**. The application recording is not replaced.
7
+ Both recordings remain in memory until the dialog closes. Replacing the main
8
+ recording closes the comparison and cancels pending work.
9
+
10
+ Profile choices have name filters and pages of 100 options. The current selection
11
+ is retained even when outside the filtered page. After comparison the settings
12
+ collapse; reopen **Profiles and scaling** to change the inputs or mode.
13
+
14
+ ## Signed values and matching
15
+
16
+ Differences are always **candidate minus baseline**. Positive/red means an
17
+ increase, negative/blue a decrease, and neutral means unchanged. Total includes
18
+ callees; self excludes them. The root's self weight represents idle/unattributed
19
+ recording weight. These measurements compare the selected inputs; they do not
20
+ identify the cause of a change or establish statistical significance.
21
+
22
+ Functions match by exact name, file, line and column under the same caller path,
23
+ independently of importer-assigned frame IDs. Recursion and different callers
24
+ remain distinct. Equal source identities under one caller merge. Renamed/moved
25
+ code or different symbolication can appear as removed/added paths; there is no
26
+ fuzzy alignment or cross-build symbol matching.
27
+
28
+ **Absolute weights** requires identical units and does not rescale recording
29
+ duration or event rate. **Share of each profile total** divides each side by its
30
+ own full total, including idle weight; differences are percentage points. A
31
+ zero-total profile contributes zero. Different-unit normalized comparisons show
32
+ composition only, not absolute performance. Raw side totals and units remain
33
+ visible so that this distinction can be checked.
34
+
35
+ ## Graph, table and navigation
36
+
37
+ The differential flamegraph uses an additive union envelope for widths:
38
+ `max(baseline self, candidate self) + sum(child envelopes)`. It preserves room
39
+ for added and removed paths and may exceed either recording's total. Widths are
40
+ comparison layout weights, not an execution-time axis. Color uses signed total
41
+ differences; tooltip/selection details show both total and self changes.
42
+
43
+ Click or keyboard-focus a tile to select it. Double-click, or use **Zoom to
44
+ selected**, to inspect that subtree. **Parent call path**, ancestor buttons and
45
+ **All stacks** navigate back. Ancestor controls retain at most 16 entries;
46
+ **All stacks** remains available for deep paths.
47
+
48
+ The accessible table displays 100 call paths per page. Search matches full names
49
+ and source files case-insensitively, returning the first 100 matches with an
50
+ explicit limit notice. Selecting a table result focuses its parent so the path
51
+ can be inspected in the graph. Search does not require rendering the full graph.
52
+
53
+ ## Resource policy and limits
54
+
55
+ Comparison is a cancellable walk of the grouped trees. It does not retain a
56
+ per-sample stack array or construct full path strings for every node. The result
57
+ still consumes memory proportional to the union; this is not an out-of-core
58
+ comparison engine. Temporary merge indexes are discarded after preparation.
59
+
60
+ | Resource | Maximum |
61
+ | --- | ---: |
62
+ | Union nodes | 500,000 |
63
+ | Input node visits | 2,000,000 |
64
+ | Unique serialized source identity characters | 8 Mi |
65
+ | Name plus file characters per source identity | 65,536 |
66
+ | Graph layout tiles | 5,000 |
67
+ | Graph traversal visits | 20,000 |
68
+ | Graph levels relative to the focused node | 128 |
69
+
70
+ Exceeding a model budget fails explicitly; compare cropped/filtered recordings
71
+ instead. Nonfinite source weights or overflowing union weights also fail.
72
+ Graph detail/depth limits and hidden subpixel paths are indicated. The graph
73
+ mounts only visible rows. Search/table selection and subtree zoom provide access
74
+ to paths beyond the initial graph limits. No weights are silently truncated.
75
+
76
+ PLC self-comparison prepared 160,613 union nodes with zero differences and about
77
+ 47.45 MiB retained model heap in one Node 24 ARM64 check. Preparation plus the
78
+ post-comparison GC took 683 ms. This excludes browser import/rendering and is not
79
+ a memory guarantee for another capture. The original PLC export hash was unchanged.
80
+
81
+ Comparison is transient. Closing the dialog releases the external candidate and
82
+ comparison state; reopening starts a new comparison. Existing Export still saves
83
+ the main recording. Comparison-file export, synchronized timelines and
84
+ statistical comparison remain separate features.
85
+
86
+ ## Differential folded files
87
+
88
+ Use **Open differential folded…** inside the comparison dialog to open
89
+ `difffolded.pl` output: `stack;leaf baselineWeight candidateWeight`. The two
90
+ columns are nonnegative weights, not a weight and its signed delta. The first
91
+ becomes Baseline and the second Candidate; click **Compare** to see their signed
92
+ differences. Both sides are also available in the profile selectors. **Use loaded
93
+ recording** restores the original choices. The main recording is unchanged.
94
+
95
+ Alternatively, import a file named `capture.diff.folded` or
96
+ `capture.differential.folded` (also `.collapsed`, `.stacks`, and gzip variants)
97
+ through the main Import button. It creates two ordinary aggregate profiles;
98
+ choose Compare profiles to visualize them. Export preserves both sides as
99
+ ordinary speedscope profiles. No signed native schema extension is required.
100
+
101
+ Selection is explicit because `function 12 3` could be an ordinary folded symbol
102
+ named `function 12` with weight 3. Ordinary folded import retains that meaning.
103
+ The differential picker supports any filename, using an internal format hint.
104
+ It rejects malformed noncomment lines, negative/nonfinite weights, overflowing
105
+ totals and mixed one/two-column files. Decimal/scientific notation is accepted;
106
+ all-zero rows have no measured width. UTF-8 plain/native-gzip inputs stream with
107
+ the existing text byte, line, sample and depth guards. Output models still scale
108
+ with both sides; generic fallback decoding can materialize expanded input.
109
+
110
+ The format follows the [producer's column definition](https://github.com/brendangregg/FlameGraph/blob/master/difffolded.pl).
111
+ Our graph uses the documented union envelope and total-delta colors. It does not
112
+ reproduce the producer SVG's candidate-only widths or self-only color scale.
113
+ Weights already normalized by the producer are imported as supplied; choose
114
+ absolute mode to avoid normalizing them again. See the
115
+ [authored example](../sample/profiles/differential-folded/example.diff.folded).
116
+
117
+ Signed pprof delta recordings use a related contribution-pair projection,
118
+ explained in [pprof import](PPROF_IMPORT.md).
@@ -0,0 +1,36 @@
1
+ # Property-test migration
2
+
3
+ The utility and LRU suites use fast-check 4.10.3. Byte domains remain signed
4
+ 8-bit for bisect inputs and unsigned 8-bit for base64 data. Generated arrays
5
+ now cover up to 50 values; cache histories cover up to 100 commands, retaining
6
+ the 1,000-run cache comparison against the slow reference implementation.
7
+ Fast-check reports a seed and shrink path on failure for deterministic replay.
8
+
9
+ The math suite still uses jsverify. This is intentional partial progress on
10
+ [#354](https://github.com/jlfwong/speedscope/issues/354), not a completed migration.
11
+ The previous default number generator used a size in 0–50 and 32-bit fractions;
12
+ it did not sample arbitrary IEEE doubles. Filtered generators also grew their
13
+ size after repeated rejection. Replacing them with generic finite doubles or
14
+ fixed bounded filters changes their domain and behavior.
15
+
16
+ A trial migration exposed fixed-absolute-tolerance inverse round-trip failures
17
+ for near-singular transforms. Two recorded coefficient/input examples are:
18
+
19
+ | Operation | Affine coefficients `(m00,m01,m02,m10,m11,m12)` | Input |
20
+ | --- | --- | --- |
21
+ | Vector round-trip | `(-34,-34,-34,-34,-33.999999984167516,-34)` | `(0,-0.9999999986030161)` |
22
+ | Position round-trip | `(-27,-27,-27,-27,-26.999999987427145,-27)` | `(0,0)` |
23
+
24
+ The observed round-trip outputs were `(0,-1)` and
25
+ `(2.384185792125848e-7,0)`, respectively. These are evidence for numerical
26
+ conditioning/oracle investigation, not a demonstrated new runtime regression.
27
+ A simple componentwise residual bound also proved unsuitable for every
28
+ explicit-inverse position solve. The trial math migration and tentative oracle
29
+ changes were discarded; the checked-in math suite and runtime math remain
30
+ unchanged. The existing #138 deterministic composition counterexample and
31
+ extreme-scale checks remain covered.
32
+
33
+ Before migrating the math suite, choose and justify inverse/solve error checks
34
+ that distinguish conditioning from implementation errors, preserve the generated
35
+ domains and shrinking, and retain the recorded cases. Do not narrow generators
36
+ or discard difficult inputs merely to make the migration green.
@@ -0,0 +1,25 @@
1
+ # Native Python cProfile statistics
2
+
3
+ Open an uncompressed `cProfile.Profile.dump_stats()` file named `.prof`, `.pstats`, or `.cprofile`. The importer reads a restricted, data-only subset of CPython's marshal format. It does not invoke Python, execute code, or accept pickle/code objects. A marshal dictionary signature and the complete cProfile record schema are required; the extension alone does not establish validity.
4
+
5
+ The primary profile, **flat self time**, preserves each function's measured self time in seconds, with filename and first source line. Its total is the sum of those self times. No call order is available. Functions with zero self time have no measured width in this projection.
6
+
7
+ The secondary profile, **immediate-caller self time; not full stacks**, assigns each function's self time to its recorded direct callers. A two-frame stack represents one direct edge only. Self time not attributed to a caller appears as a one-frame stack. Recursive edges remain two-frame edges; they are not expanded into hypothetical deep stacks. Both profiles are marked nonchronological, including after export.
8
+
9
+ cProfile stores an aggregate directed call graph. Shared callees and recursion mean the original full stack paths cannot be recovered from these records. This importer does not invent those paths or turn cumulative times into additive self time. Primitive/total call counts and cumulative times are validated, but are not separate displayed metrics. If caller self times exceed a function's self time beyond rounding tolerance, the importer keeps only the exact flat projection and marks its profile name **caller attribution unavailable**. Tiny floating-point excesses within relative tolerance `1e-12` are clipped to the remaining self time.
10
+
11
+ ## Limits and cancellation
12
+
13
+ The native decoder accepts at most 32 MiB of input, one million decoded objects, 500,000 references, 8 MiB of decoded string bytes in total, 64 KiB per source string, depth 16, 100,000 functions, and 200,000 direct caller edges. All limits apply together; a smaller object/string limit can be reached before the function/edge ceiling. The reader checks lengths before allocation, rejects incomplete/cyclic references, duplicate source identities, trailing data, unsafe integer counts, invalid UTF-8, unsupported object types, and nonfinite/negative measurements. Decoding/building yields periodically and supports cancellation. The parsed marshal graph and both output projections coexist during import; this is a bounded in-memory importer, not a streaming or out-of-core format.
14
+
15
+ Oversized **raw** native files are checked using a six-byte signature slice before reading their body. Generic gzip/zlib decompression happens before binary format detection and is not currently bounded by this native decoder's input limit. Compressed `.prof` files can also be pprof recordings, so those generic wrappers are retained. For predictable memory use with native cProfile, supply the uncompressed marshal file within the size limit. Do not treat the 32 MiB decoder limit as a generic compressed-input expansion limit.
16
+
17
+ ## Compatibility and evidence
18
+
19
+ The fixtures were produced by CPython 3.14.3's actual cProfile profiler, with a deterministic timer, a shared callee, builtins, and recursion. The same statistics are additionally serialized with marshal wire versions 0–5. These fixtures verify the supported data encodings; they do not establish compatibility with every historical or future Python release. Python explicitly reserves the right to change marshal and profiler file formats. Python 2 byte-string labels, pure-Python `profile`'s different caller schema, arbitrary marshal values, and future unsupported encodings are rejected rather than guessed.
20
+
21
+ - [CPython 3.14.3 cProfile implementation](https://github.com/python/cpython/blob/v3.14.3/Lib/cProfile.py): `snapshot_stats()` defines function and caller tuples.
22
+ - [CPython 3.14.3 marshal implementation](https://github.com/python/cpython/blob/v3.14.3/Python/marshal.c): numeric/string/container/reference encodings.
23
+ - [Python marshal documentation](https://docs.python.org/3.14/library/marshal.html): version limitations and the hazards of unrestricted native unmarshalling.
24
+ - [Python pstats documentation](https://docs.python.org/3/library/pstats.html): self/cumulative time and call-count meanings.
25
+ - [Synthetic fixture source and regeneration](../sample/profiles/python-cprofile/README.md).
package/docs/RELEASING.md CHANGED
@@ -51,8 +51,10 @@ For a new version, it attaches the newly built npm tarball as well.
51
51
 
52
52
  ## npm trusted publishing after the first publication
53
53
 
54
- The npm trusted publisher was created successfully on 2026-11-18 for
55
- `@node-projects/speedscope`. It authorizes the following GitHub Actions identity:
54
+ The original npm trusted publisher, created on 2026-11-18, expired before its
55
+ first automated publication. It was recreated on 2026-11-21 and successfully
56
+ published **2.1.0** through the [release workflow retry](https://github.com/node-projects/speedscope/actions/runs/44884626601/attempts/2).
57
+ This validates end-to-end OIDC publication for the following GitHub Actions identity:
56
58
 
57
59
  - Organization/user: `node-projects`
58
60
  - Repository: `speedscope`
@@ -79,16 +81,27 @@ npm trust github @node-projects/speedscope --repository node-projects/speedscope
79
81
  ```
80
82
 
81
83
  npm requires fresh two-factor authentication for these account operations. The
82
- setup was completed through the CLI's browser authentication flow; no credentials
83
- were added to the repository. Recreating an existing publisher is not a routine
84
+ original setup used the CLI's browser authentication flow; the replacement used
85
+ npm's package settings in the browser. No credentials were added to the repository.
86
+ Recreating an existing publisher is not a routine
84
87
  release step.
85
88
 
86
89
  New publisher configurations must complete their first successful automated
87
90
  publish within **two days**, otherwise npm expires them. Creating a GitHub release
88
91
  for an already-published version does not validate OIDC because this workflow
89
92
  skips the npm publish step for that version. Use the next new version (for example
90
- `v2.0.1`) when ready. Until that first workflow publish, setup is verified but an
91
- end-to-end OIDC publication has not been exercised.
93
+ `v2.0.1`) when ready. The recreated connection completed this validation with
94
+ 2.1.0; the two-day deadline applies to new, unvalidated connections.
95
+
96
+ If publication fails with `E404` while the package exists, inspect **Trusted
97
+ Publisher** in npm package settings. On 2026-11-21 this displayed **Expired**;
98
+ the runner's Node/npm versions and OIDC permission were already correct. Delete
99
+ the expired connection, recreate the same identity with direct publication
100
+ allowed, then retry the failed job or dispatch the existing release tag.
101
+ npm may require separate fresh authentication checks to view settings, delete
102
+ the expired connection and save its replacement. Verify the retry's publish
103
+ step and the registry's version/dist-tag afterward. No code or tag change was
104
+ needed for this recovery.
92
105
 
93
106
  See [npm's trusted publisher setup](https://docs.npmjs.com/trusted-publishers/).
94
107
  The repository URL in package.json points to this fork, as required for provenance.
@@ -1,5 +1,83 @@
1
1
  # Search across profiles and arrange Sandwich panes
2
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
+
3
81
  ## Search all profiles
4
82
 
5
83
  Choose **Profile actions → Search all profiles…**, enter a function name or source
@@ -122,7 +200,7 @@ occurrences in depth-first order. If there are more, the count shows `10000+`
122
200
  and a visible status asks you to refine your search. This is a lower bound,
123
201
  not the full count. Previous/Next and Enter/Shift+Enter wrap within the retained
124
202
  window. A selected frame outside that window shows `?` for its navigation index.
125
- Use a more specific name/path or Whole word/Exact mode to narrow the query.
203
+ Use a more specific name/path or Whole word/Exact/Regex mode to narrow the query.
126
204
 
127
205
  Matching and graph highlights still inspect full names and source paths, even
128
206
  outside the navigation window. Sparse queries can find late occurrences: the
@@ -137,7 +215,7 @@ and 512 highlight lists, evicting old entries and recomputing them when needed.
137
215
  Only labels/rows being drawn request name-highlight ranges, capped at the first
138
216
  64 ranges per name. A long, repetitive name can therefore match beyond its
139
217
  drawn underlines. File-only matches have no name underlines. Search input is
140
- limited to 4,096 characters. These are literal modes, not arbitrary regexes.
218
+ limited to 4,096 characters in literal modes; Regex has the separate 256-character and compilation limits described above.
141
219
 
142
220
  Search no longer builds a full per-symbol highlight map or a rectangle for
143
221
  every matching call. Traversal uses O(depth) auxiliary storage and creates a
@@ -234,7 +312,54 @@ errors. A PLC streaming smoke retained four profiles, 17,510 frames and
234
312
  2.4 seconds in that Node run. These UI changes add no per-frame context index or
235
313
  profile copy. Source-name metadata is one bounded string per group.
236
314
 
237
- ## Upstream review
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
238
363
 
239
364
  The 2026-11-21 shared-selection, Java text-dump, hosted-offline and numerical
240
365
  test follow-up passed all 393 Jest tests across 68 suites (307 snapshots), five
@@ -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.
@@ -1,4 +1,82 @@
1
- # Source-code links and compact graph labels
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.
2
80
 
3
81
  ## Open a source location
4
82
 
@@ -47,6 +125,43 @@ search and exports. Function signatures containing path-like punctuation are
47
125
  preserved. Search still matches the full name: a match entirely inside a hidden
48
126
  prefix can highlight a frame without underlining text in its displayed suffix.
49
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
+
50
165
  ## Large traces
51
166
 
52
167
  Neither setting reimports or transforms a recording. Labels are shortened only
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@node-projects/speedscope",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "description": "A fast, interactive performance profile viewer with large-trace improvements, an accessible call tree and offline CLI.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -25,6 +25,7 @@
25
25
  "backlog:generate": "node scripts/generate-issue-backlog.mjs",
26
26
  "backlog:check": "node scripts/generate-issue-backlog.mjs --check",
27
27
  "build:pages": "node scripts/prepare-release.mjs --protocol http",
28
+ "build:single-file": "tsx scripts/build-single-file.ts",
28
29
  "deploy": "gh workflow run pages.yml --ref main",
29
30
  "release:version": "node scripts/set-release-version.mjs",
30
31
  "prepack": "node scripts/prepare-release.mjs",
@@ -43,10 +44,19 @@
43
44
  "docs/RELEASING.md",
44
45
  "docs/LARGE_TRACE_PERFORMANCE.md",
45
46
  "docs/PROFILE_FILTERS.md",
47
+ "docs/PROFILE_COMPARISON.md",
48
+ "docs/PPROF_IMPORT.md",
49
+ "docs/PYTHON_CPROFILE.md",
46
50
  "docs/SEARCH_AND_LAYOUT.md",
47
51
  "docs/SOURCE_AND_LABELS.md",
48
52
  "docs/JAVA_THREAD_DUMPS.md",
53
+ "docs/JAVA_THREAD_DUMP_ZIP.md",
54
+ "docs/IMPORT_FORMATS.md",
55
+ "docs/PERF_IMPORT.md",
56
+ "docs/OTEL_PROFILES.md",
49
57
  "docs/OFFLINE.md",
58
+ "docs/SINGLE_FILE.md",
59
+ "docs/PROPERTY_TESTS.md",
50
60
  "bin/cli.mjs",
51
61
  "bin/server.mjs",
52
62
  "dist/release/**",
@@ -76,6 +86,7 @@
76
86
  "eslint": "8.0.0",
77
87
  "eslint-plugin-prettier": "5.1.2",
78
88
  "eslint-plugin-react-hooks": "4.6.0",
89
+ "fast-check": "4.10.3",
79
90
  "jest": "30.2.0",
80
91
  "jest-environment-jsdom": "29.7.0",
81
92
  "jfrview": "0.2.0",
@@ -120,6 +131,7 @@
120
131
  ]
121
132
  },
122
133
  "dependencies": {
123
- "open": "10.1.0"
134
+ "open": "10.1.0",
135
+ "re2js": "2.10.0"
124
136
  }
125
137
  }
@@ -41,6 +41,10 @@ export namespace FileFormat {
41
41
  file?: string
42
42
  line?: number
43
43
  col?: number
44
+ /** Producer-selected RGB color. Presentation may adapt it for text contrast.
45
+ * @pattern ^#[0-9a-fA-F]{6}$
46
+ */
47
+ color?: string
44
48
  }
45
49
 
46
50
  export enum ProfileType {