@node-projects/speedscope 0.0.0-stage → 2.1.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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2020 Juanjo Diaz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,32 @@
1
+ # Java thread-dump snapshots
2
+
3
+ Import traditional HotSpot text output from `jstack PID` or
4
+ `jcmd PID Thread.print` by opening a `.jstack` file or a text file containing
5
+ the `Full thread dump …` header. Concatenate captures from the same JVM to
6
+ compare observed stacks across repeated snapshots. Extract ZIP archives first.
7
+
8
+ Each observed Java stack contributes one raw sample. The importer creates an
9
+ aggregate profile per thread name and Java thread ID, falling back to `tid`
10
+ when the Java ID is absent. Renamed threads appear separately. Missing threads
11
+ and threads without Java frames add no samples. The profile selector switches
12
+ between threads; Left Heavy, Sandwich and Call Tree show the observations.
13
+ Time Order is unavailable because snapshots do not measure execution duration.
14
+ CPU, elapsed, timestamps, state and lock text are not converted into weights.
15
+
16
+ Frames retain method/module names and available source files and positive line
17
+ numbers. Native Method and Unknown Source entries keep their identity without
18
+ inventing a source location. Deadlock summaries are ignored because they repeat
19
+ stacks already listed in the snapshot. Malformed thread headers, malformed Java
20
+ frames and duplicate thread identities within a snapshot produce an import error.
21
+
22
+ The parser iterates lines and retains the current stack and current snapshot's
23
+ thread identities, rather than collecting every line or observation. The text
24
+ input and resulting profile model still occupy memory; this format does not use
25
+ the duration-trace streaming importer. Prefer captures from one JVM per file.
26
+ ZIP input, structured virtual-thread JSON, native address stacks and lock/state
27
+ visualization are outside the supported format.
28
+
29
+ The checked-in [synthetic example](../sample/profiles/java-thread-dump/synthetic.jstack)
30
+ contains repeated snapshots and source locations. Format references are
31
+ [OpenJDK's traditional dump examples](https://github.com/openjdk/jdk/blob/master/test/hotspot/jtreg/serviceability/tmtools/jstack/utils/DefaultFormat.java)
32
+ and the [Oracle Java troubleshooting guide](https://docs.oracle.com/en/java/javase/21/troubleshoot/troubleshooting-guide.pdf).
@@ -0,0 +1,346 @@
1
+ # Large trace performance follow-up
2
+
3
+ Baseline: `eb93425`, reviewed 2026-11-18. These changes continue the open-issue
4
+ review, prioritizing large profiles and the export request in issue #89.
5
+
6
+ ## Changes
7
+
8
+ - Both profile builders index grouped children once a node reaches 16 children.
9
+ Narrow nodes keep the small linear scan; construction indexes are released at
10
+ build completion. Wide/inverted trees no longer scan thousands of siblings for
11
+ every sample. Existing frame identities are reused without allocating candidates.
12
+ - Evented builders skip frame/node weight updates when the timestamp delta is zero.
13
+ Deep enter/leave sequences at identical timestamps avoid repeated depth scans.
14
+ - Folded input produces samples one at a time. Text readers also yield lines
15
+ lazily across decoded chunks, avoiding arrays of every line/sample in the file.
16
+ - V8 heap profiles use an iterative, allocation-driven traversal instead of
17
+ recursive indexing/size passes and materialized ancestor paths. Empty branches
18
+ stay empty, and the importer no longer retains call-frame objects in a global
19
+ cache. A 20,000-level heap regression verifies depth handling and byte totals.
20
+ - Interactive export uses a lazy call-event iterator and JSON Blob chunks. It
21
+ yields every 16,384 events and 4,096 source frames using message tasks (with a
22
+ timer fallback), reports progress and supports
23
+ cancellation. It does not construct another full event-object tree or a single
24
+ trace-sized JSON string. Downloads release their object URLs after starting.
25
+ - Known aggregate importers (folded, Callgrind, pprof, Haskell, PMCStat, Instruments
26
+ table copies and V8 heap trees) and derived aggregate profiles disable Time Order. Optional
27
+ `isChronological` and `isDerived` fields in this fork's file format retain those
28
+ properties through export/reimport. Existing files default to chronological,
29
+ original captures when metadata is absent. Cloning/export no longer loses derived provenance and causes
30
+ combined views to be counted again when originals are combined.
31
+
32
+ ## Local measurements
33
+
34
+ Single-process Node smoke measurements on this Windows machine; timings and
35
+ garbage collection vary. The PLC capture contains 1,039,851 input events and four
36
+ profiles. Its export contains 1,039,656 call events and 17,510 source frames.
37
+ Private capture data is not committed.
38
+
39
+ | Operation | Baseline | Updated |
40
+ | --- | ---: | ---: |
41
+ | Combine PLC profiles | 427 ms | 368 ms |
42
+ | Invert combined PLC stacks | 5,315 ms | 562 ms |
43
+ | Group combined PLC stacks by file | 29 ms | 26 ms |
44
+ | Import 500,000 repeated folded stacks | 657 ms | 451 ms |
45
+ | Folded import heap at completion | 276 MiB | 62 MiB |
46
+ | Folded process peak RSS | 449 MiB | 177 MiB |
47
+
48
+ The folded fixture is 500,000 repetitions of `root;main;worker;leaf 1`. It
49
+ isolates temporary parsing allocations; real captures with many distinct stacks
50
+ retain more call-tree data. Both implementations produce total weight 500,000.
51
+ The PLC transformations preserve the combined busy weight exactly.
52
+
53
+ For the 52,619,139-byte PLC JSON export, the legacy blocking serializer on the
54
+ current profile model took 410 ms with sampled peak JS heap of 301 MiB. The new
55
+ cooperative serializer took 857 ms with sampled peak heap of 237 MiB and 73
56
+ progress updates. Starting heap after forced collection was 131 MiB in each case.
57
+ This reduces sampled additional export heap from 170 to 106 MiB, with higher elapsed
58
+ time in exchange for responsive progress and cancellation. Process peak RSS stayed
59
+ around 984–987 MiB because input parsing dominates it. These samples do not prove
60
+ a hard memory bound or a cross-browser speedup.
61
+
62
+ To reproduce against an available capture:
63
+
64
+ ```powershell
65
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" all
66
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" import
67
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" legacy-export
68
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" export
69
+ ```
70
+
71
+ The wrapper bundles the existing importer with embedded WASM and runs a separate
72
+ Node process. `all` measures aggregate transforms; `import` reports completion heap
73
+ and peak RSS. Export modes force collection after import before measuring export.
74
+ Run benchmarks without other CPU/memory-heavy jobs. `legacy-export` remains a
75
+ benchmark comparison; interactive downloads use cooperative serialization.
76
+
77
+ ## Verification and remaining limits
78
+
79
+ Regression tests cover wide-node lookup bounds and frame identity, restarting
80
+ construction after sorting, deep recursive weight accounting, lazy Unicode line
81
+ iteration, exact JSON/export round trips, cancellation before/during event and
82
+ source-frame batches, URL cleanup, aggregate navigation and persisted provenance.
83
+
84
+ Browser testing with the PLC capture verified visible progress, cancellation,
85
+ completed download, disabled Time Order for aggregates and combined-stack
86
+ inversion. The downloaded JSON was compared exactly with the standard exporter,
87
+ then reimported with all profile totals preserved.
88
+
89
+ ## Worker import and search follow-up
90
+
91
+ Large input files (at least 1 MiB of input bytes) named `.json`, `.trace`,
92
+ `.cpuprofile` or `.heapprofile`, optionally gzip-compressed, now use a browser
93
+ worker when available. The existing format detector is reused, preserving its
94
+ dispatch order. HTTP/profileURL, local File and CLI base64 loading use this path.
95
+ Input buffers and numeric profile tables transfer ownership instead of being
96
+ JSON-serialized or cloned as full call-tree objects. File inputs can be read in
97
+ the worker. Symbols are demangled there before returning immutable profile data.
98
+
99
+ The UI shows import progress and cancellation. Cancellation terminates the worker;
100
+ new loads and unmounts cancel old imports, and stale results cannot replace newer
101
+ profiles or clear their loading state. The worker is released before UI object
102
+ reconstruction, which yields between bounded batches so it can also be cancelled.
103
+ Worker creation blocked by a host can fall back to the ordinary importer. An
104
+ unexpected worker crash reports an error rather than trying a detached buffer.
105
+ Small files and other filename extensions retain the ordinary importer; that
106
+ synchronous fallback cannot be interrupted during parsing.
107
+
108
+ The worker code is embedded by the build plugin, so both HTTP and offline builds
109
+ can create it without fetching a worker script or WASM from an external host.
110
+ The transport is an internal implementation detail, not a public interchange API.
111
+
112
+ Tests cover numeric/string frame identity, recursion, source locations, formatting,
113
+ aggregate/derived flags, idle ranges, transferred buffers, deep trees, invalid
114
+ references, cancellation, worker cleanup, host fallback and stale-load races.
115
+ The PLC worker import was cancelled interactively while parsing, then completed;
116
+ its exported JSON matched the ordinary importer exactly (four profiles, 17,510
117
+ frames and 1,039,656 call events). A local snapshot smoke check measured 214 ms to
118
+ encode the PLC profiles and 34,602,732 bytes of numeric tables (excluding frame
119
+ strings and metadata). Browser elapsed-time/peak-RSS speedups are not claimed.
120
+
121
+ Search also supports literal whole-word and exact matching. Patterns are reused
122
+ per query and file-only checks avoid allocating name highlight ranges. Unicode
123
+ word boundaries, punctuation, escaped metacharacters and full-name/path matching
124
+ have regressions. User-provided regex is still not enabled.
125
+
126
+ Profile trees and rendering remain in-memory operations. Unsupported formats
127
+ still use the original full-document importer. UI hydration and rendering have
128
+ costs, and transferring work can increase overall elapsed time even while making
129
+ the interface responsive. This does not fix every OOM report. Derived
130
+ transformations other than frame filtering remain synchronous. Frame filtering
131
+ visits grouped paths and yields during traversal, with cancellation; final tree
132
+ sorting remains synchronous. See [filter behavior and limits](PROFILE_FILTERS.md).
133
+ Export retains the final
134
+ Blob bytes and source profile while bounding temporary serialization chunks
135
+ (apart from an individually huge string). An out-of-core model, heap budgets,
136
+ worker-backed transforms, signed comparisons and synchronized timelines remain
137
+ separate follow-ups in [the maintained backlog](ISSUE_BACKLOG.md).
138
+
139
+ ## Streaming duration traces
140
+
141
+ Large duration-event `.json`/`.trace` files, optionally gzip-compressed, now use
142
+ incremental parsing inside the worker. A local File is streamed without reading
143
+ its whole contents; transferred ArrayBuffers are consumed in 64 KiB slices.
144
+ Native `DecompressionStream` inflates gzip incrementally. The streaming parser
145
+ ([@streamparser/json](https://github.com/juanjoDiaz/streamparser-json), pinned at
146
+ 0.0.26) releases completed event objects from its parent array. We retain the
147
+ duration events, naming metadata and first event needed by the existing Hermes
148
+ discriminator, dropping unused event fields and ignored events. Event arguments
149
+ remain intact because they participate in frame identities.
150
+
151
+ This avoids a full inflated byte buffer, a whole JSON string and a complete
152
+ parsed input object. Out-of-order traces still need stable sorting, so retained
153
+ events and constructed trees continue to scale with the capture. This is not an
154
+ out-of-core profile store or a hard bound on total JavaScript/browser memory.
155
+
156
+ The streaming path rejects excessive input complexity before returning a profile:
157
+
158
+ | Limit | Default |
159
+ | --- | ---: |
160
+ | Decompressed input | 1 GiB |
161
+ | Pending event/metadata bytes between completed events | 16 MiB |
162
+ | Retained event source bytes | 256 MiB |
163
+ | Input events, including ignored events | 2,000,000 |
164
+ | JSON nesting depth | 128 |
165
+
166
+ Checks run before bounded parser writes and while tokens/events are emitted.
167
+ The pending-byte check is conservative at chunk boundaries. These are source
168
+ complexity limits, not heap accounting: object overhead, expanded Unicode,
169
+ sorting, call-tree nodes, numeric snapshots, hydration and GPU resources have
170
+ additional costs. A limit failure stops with an actionable error; it never
171
+ silently truncates the trace or retries the full importer. Cancellation releases
172
+ the reader and terminates the worker; source cancellation failures cannot hide
173
+ the original error.
174
+
175
+ Native CPU/heap/speedscope files and known filename overrides retain their
176
+ detector. CPU markers anywhere in the stream, sample tables, duplicate root
177
+ `traceEvents` properties and unrecognized wrapper properties return to that
178
+ detector, preserving their original semantics. Those fallback formats do not
179
+ gain these streaming budgets. Gzip also falls back when native decompression is
180
+ unavailable. URL/CLI loading still buffers the input response before transfer;
181
+ local File streaming avoids that buffer. Tolerated trailing commas and missing
182
+ final `]` after complete array events remain supported. Incomplete values and
183
+ corrupt gzip fail rather than producing a partial result.
184
+
185
+ Validation includes every duration-trace fixture against the ordinary importer,
186
+ one-byte UTF-8/escape boundaries, late metadata, argument identity, unordered and
187
+ anonymous events, sampled/CPU fallback, ignored payloads, gzip File imports with
188
+ whole-file reads forbidden, resource-limit failures, and cancellation races.
189
+ The PLC capture exported identically: four profiles, 17,510 frames, 1,039,656
190
+ call events and matching totals. Fresh-process Windows/Node 24 import-only runs:
191
+
192
+ | Path | Import time | Peak RSS | Heap after import |
193
+ | --- | ---: | ---: | ---: |
194
+ | Ordinary importer | 2,281 ms | 999 MiB | 572 MiB |
195
+ | Streaming duration importer | 4,311 ms | 623 MiB | 437 MiB |
196
+
197
+ This single capture/run measured about 38% lower peak RSS at a latency cost.
198
+ Browser peak memory, rendering and worker hydration are not represented by this
199
+ Node benchmark. Results vary by machine, input and garbage collection. Reproduce
200
+ each path in its own process with `node scripts/benchmark-profile.mjs <capture>
201
+ import` and `node scripts/benchmark-profile.mjs <capture> stream-import`.
202
+
203
+ Issues #519, #347, #478, #386 and #404 remain **partial** in the backlog: the
204
+ specific original reproductions and a general bounded-memory profile model still
205
+ need work.
206
+
207
+ ## Faster streaming event parsing
208
+
209
+ CPU profiling of the first streaming implementation showed substantial time in
210
+ token parsing, per-property assignment, selector matching and callbacks. The
211
+ worker now scans structural bytes to frame each complete event object, then
212
+ decodes and parses that one object with native `JSON.parse`. The token parser
213
+ still validates the wrapper/array grammar and handles other values. The bounded
214
+ event framing scan tracks string escapes and nesting; it does not interpret
215
+ fields or split on text delimiters. A rare permissive retry retains the existing
216
+ trailing-comma behavior.
217
+
218
+ No whole-document string or inflated buffer is introduced. Events spanning read
219
+ boundaries use a temporary buffer for that one event. The existing decompressed,
220
+ pending, retained, event-count and depth limits remain in force, including while
221
+ framing native records. Truncated later records cannot be silently dropped when
222
+ repairing a producer's omitted final array bracket. Additional regressions cover
223
+ all small chunk sizes, large records, split UTF-8/escapes, malformed inner and
224
+ outer grammar, and the existing fallback/cancellation/limit cases.
225
+
226
+ Three alternating fresh-process runs of the same PLC capture on Windows/Node 24
227
+ compared the previous streaming bundle (`39b264b`) with native event framing:
228
+
229
+ | Metric | Previous streaming | Native event framing |
230
+ | --- | ---: | ---: |
231
+ | Import times | 4,255 / 4,336 / 4,423 ms | 2,493 / 2,563 / 2,445 ms |
232
+ | Median import time | 4,336 ms | 2,493 ms |
233
+ | Peak RSS | 612 / 613 / 615 MiB | 579 / 573 / 581 MiB |
234
+ | Median peak RSS | 613 MiB | 579 MiB |
235
+
236
+ That is about 43% faster while retaining (and slightly improving) the previous
237
+ memory reduction. These are import-only process measurements, not browser
238
+ rendering or hydration measurements. Each revision's `benchmark-profile.ts` was
239
+ bundled separately with esbuild (Node/CommonJS, ES2020, binary WASM) and run with
240
+ the capture path and `stream-import` action, alternating revisions without
241
+ explicit garbage collection. Captures and timing logs are not committed.
242
+ The full exported profiles match the ordinary importer, including all four
243
+ profiles, 17,510 frames, 1,039,656 call events and profile totals.
244
+
245
+ The same follow-up fixes issue #199's deep-zoom axis labels: formatting receives
246
+ the visible tick interval, tick generation clamps below floating-point precision,
247
+ and overlapping labels are skipped. V8 source-path extraction and exact-first
248
+ sourcemap matching (with empty maps ignored) improve #446, which remains partial
249
+ because automatic linked map discovery/loading is still separate work. The
250
+ maintained backlog records these completion boundaries explicitly.
251
+
252
+ ## Smaller duration queues and bounded selected-stack details
253
+
254
+ The 2026-11-20 follow-up reuses complete (`X`) events as begin records rather
255
+ than spreading every event into another full object. Synthesized end records
256
+ retain only their timestamp, name and shared arguments. Source positions and
257
+ argument-based frame identity remain unchanged. Queues already ordered by time
258
+ skip stable-sort workspace; unordered queues still use the existing stable sort,
259
+ including equal-timestamp and epoch-rounding behavior. No additional event index
260
+ is retained. The streaming limits are unchanged.
261
+
262
+ Three alternating fresh-process runs on Windows/Node 24 compared `f6c5d43`
263
+ against this change, using the same ES2020 CommonJS benchmark bundle options:
264
+
265
+ | Capture / metric | Before | After |
266
+ | --- | ---: | ---: |
267
+ | PLC import times (ms) | 2,609 / 2,524 / 2,579 | 2,562 / 2,546 / 2,562 |
268
+ | PLC median peak RSS (MiB) | 576 | 576 |
269
+ | Complete-event fixture import times (ms) | 1,131 / 833 / 822 | 986 / 767 / 779 |
270
+ | Complete-event fixture median peak RSS (MiB) | 362 | 295 |
271
+ | Complete-event fixture median heap at import (MiB) | 224 | 155 |
272
+
273
+ The synthetic fixture contains 250,000 sequential complete events with 5,000
274
+ distinct argument-based frame keys. Its median peak RSS fell about 19%; PLC
275
+ performance remained essentially unchanged. These are process import measurements,
276
+ not browser hydration/rendering or hard heap bounds. Separate full-export checks
277
+ matched the baseline hash for both captures. PLC still exports four profiles,
278
+ 17,510 frames and 1,039,656 call events. Captures and benchmark artifacts are not
279
+ committed. Reproduce import measurements with `node scripts/benchmark-profile.mjs
280
+ <capture> stream-import`; do not include export validation in import-only RSS.
281
+
282
+ Selected-stack details now retain/render at most 100 ancestor rows and follow
283
+ parent pointers only as pages are requested, without building the full ancestor
284
+ list. All scopes remain reachable through older-page and reset controls. Clicking
285
+ one selects the exact ancestor instance; see [stack navigation](SEARCH_AND_LAYOUT.md#navigate-selected-stack-ancestors).
286
+ Tests include a 100,000-level chain with a guarded page boundary. The PLC's
287
+ deepest seven-scope stack was paged without changing the export hash.
288
+
289
+ Issues #519, #478, #386, #347 and #404 remain partial: the final profile model,
290
+ worker snapshots, unordered sorts and graph rendering still grow with capture
291
+ size. This work reduces specific temporary allocations and bounds the details
292
+ panel, without claiming an out-of-core viewer or fixing every reported OOM.
293
+
294
+ Validation passed 339 Jest tests across 58 suites (307 snapshots), five Node
295
+ tests, type checking, linting, schema/backlog checks, both builds and a dry-run
296
+ npm contents check. Browser smoke checks used a 220-level profile to verify
297
+ 100-row pages, access to the root, reset controls, Enter/Space selection and
298
+ visible ancestor highlighting below the time axis, without console errors.
299
+
300
+ ## Bounded graph-search state
301
+
302
+ On 2026-11-21, graph search stopped eagerly caching every source symbol and
303
+ allocating navigation geometry/index entries for every matching call. Per query,
304
+ boolean frame results are capped at 4,096 entries and drawn-label ranges at
305
+ 512 entries with at most 64 ranges each. Time Order/Left Heavy navigation keeps
306
+ the first 10,000 matches and checks for one further match to establish
307
+ truncation. The search UI displays a `+` lower bound and a visible refinement
308
+ notice; it never claims the truncated count is complete. Matching/highlighting
309
+ can continue beyond that navigation window.
310
+
311
+ Three alternating fresh-process Windows/Node 24 runs compared `a72d309` with
312
+ bounded search on the PLC's first profile (513,009 graph frames), using a broad
313
+ single-space query:
314
+
315
+ | Search-only metric | Before | After |
316
+ | --- | ---: | ---: |
317
+ | Initialization times (ms) | 96 / 89 / 94 | 3 / 3 / 4 |
318
+ | Retained search heap after explicit GC (MiB) | 119.60 / 119.60 / 119.60 | 0.907 / 0.907 / 0.906 |
319
+ | Retained navigation matches | 513,009 | 10,000 (explicitly limited) |
320
+
321
+ This is a deliberate navigation-limit tradeoff, not equivalent full-result
322
+ enumeration. Separate single-run checks found the same 40 `GroupCalls` matches
323
+ (14 → 22 ms) and zero matches for a nonexistent symbol (14 → 25 ms). Those sparse
324
+ queries retain about half as much search heap, but can be slower because cached
325
+ entries are recomputed. These are Node search measurements after import and graph
326
+ construction, not whole-app memory caps or browser latency guarantees.
327
+ The measured initialization counts results and opens the first ten; it does not
328
+ draw labels or measure browser rendering.
329
+
330
+ The PLC import/export check still reports four profiles, 17,510 source frames
331
+ and 1,039,656 call events, with the unchanged baseline export hash. Captures and
332
+ benchmark artifacts remain private/uncommitted. The maintained benchmark adds
333
+ `node scripts/benchmark-profile.mjs <capture> stream-search [query]` for streaming
334
+ import followed by bounded search of the first profile; its default query is a
335
+ single space. It reports the navigation limit and retained search heap separately
336
+ from input/model memory. Graph creation, worker snapshots, sorting, Sandwich
337
+ row lists and the final model remain proportional to recording size; the OOM
338
+ backlog stays partial.
339
+
340
+ Validation passed all 354 Jest tests across 62 suites (307 snapshots), five Node
341
+ tests, type checking, linting, schema/backlog checks, both builds and package
342
+ contents. Regressions cover cache eviction, dense-symbol range limits, exact
343
+ limit detection, late sparse matches, depth-first order and 25,000-level graphs.
344
+ Browser checks on 20,050 calls verified the visible limit notice, both keyboard
345
+ wrap directions, narrowing to a late result, and the root-label axis fix,
346
+ without console errors.
@@ -0,0 +1,58 @@
1
+ # Hosted offline use
2
+
3
+ The hosted HTTP build caches its application shell after a successful online
4
+ visit in a service-worker-capable secure browser. Once installation has finished,
5
+ the app's entry page can reopen without a network connection. Import a recording
6
+ from your computer again after reopening; an open recording remains in memory
7
+ when the network disconnects.
8
+
9
+ This caches application code, styles, fonts, icons and WebAssembly decoders only.
10
+ Imported recordings, remote `profileURL` responses, the CLI's local profile
11
+ endpoint, source maps supplied by users, the built-in example recording and
12
+ arbitrary network responses are not saved. A `profileURL` link can open the
13
+ offline app shell, but its remote recording still needs a network connection.
14
+ The built-in example also needs the network. Application caching is not a saved
15
+ recording feature.
16
+
17
+ Use the app's ordinary entry URL, such as `/speedscope/` or
18
+ `/speedscope/index.html`. Hash parameters are supported; query-string entry URLs
19
+ are not intercepted. Neither arbitrary paths within the scope nor cross-origin
20
+ URLs are intercepted. Explicit `no-store` requests and range requests bypass
21
+ the worker as well.
22
+
23
+ ## Updates
24
+
25
+ Shell revisions are derived from the generated HTML, immutable asset contents
26
+ and worker policy. An update is installed in the background and waits for all
27
+ tabs using the previous app version to close. Open recordings are not reloaded
28
+ or replaced automatically. Close all app tabs, then reopen the app to adopt a
29
+ waiting update. Offline reopening can continue to use the last installed shell
30
+ if no newer version has been downloaded.
31
+
32
+ Each application scope owns at most three shell generations: the active shell,
33
+ the previous waiting shell and the newest installation/waiting shell. One small
34
+ metadata cache holds only active/waiting cache names. A failed new install keeps
35
+ the active and previously waiting versions usable. Activation removes obsolete
36
+ owned shell caches; caches belonging to other apps/scopes are left untouched.
37
+ There is no runtime cache insertion. Builds reject more than 64 shell files or
38
+ more than 16 MiB of shell assets.
39
+
40
+ Browser storage restrictions, quota pressure or manually clearing site data can
41
+ remove the offline copy. The app continues to work online if registration or
42
+ installation is unavailable. The worker uses the browser's ordinary
43
+ [installation and waiting lifecycle](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)
44
+ without `skipWaiting`, `clients.claim` or forced reloads.
45
+
46
+ ## Build and local behavior
47
+
48
+ `npm run build:pages` emits the worker and hosted registration script.
49
+ `npm run prepack` retains the existing portable standalone ZIP behavior and
50
+ does not emit/register a service worker. The ordinary development server also
51
+ does not register one. File-protocol pages remain independent of service workers.
52
+
53
+ Localhost root pages are excluded to avoid controlling another local app or CLI
54
+ session. A deliberate hosted-build preview under a subdirectory such as
55
+ `http://127.0.0.1:PORT/app/` can register a worker limited to that directory.
56
+ For browser verification, complete an online visit there, stop the server, then
57
+ reload the same entry URL. Use a dedicated preview origin/port and clear its
58
+ site storage afterward if you no longer need the preview's offline shell.
@@ -0,0 +1,73 @@
1
+ # Filter frames
2
+
3
+ Choose **Profile actions → Filter frames…** to create an aggregate view of your
4
+ code or hide framework frames. The original recording stays in the profile
5
+ selector. Select it to return to the complete profile. Filtering applies to the
6
+ active profile, and you can apply another filter to a derived profile.
7
+
8
+ Choose source file path, function name, or either. Enter one case-insensitive
9
+ literal substring per line. Slashes are interchangeable, so `src/app/` also
10
+ matches Windows paths. Multiple include rules are alternatives (OR); any exclude
11
+ match removes the frame, even if an include rule matches it. Leave include blank
12
+ to retain all frames except exclusions. Empty lines are ignored. File rules do
13
+ not match frames without a source path; use function names for those profiles.
14
+ Names match the displayed frame name, including any arguments that a trace
15
+ importer incorporates into it. There are no regular expressions or glob rules.
16
+
17
+ For example, include `src/` and exclude `node_modules/`. Or leave include empty
18
+ and exclude `vendor/` to remove framework frames while keeping unmapped code.
19
+ Up to 128 non-empty rules and 4,096 combined rule characters are accepted.
20
+
21
+ ## What the weights mean
22
+
23
+ This hides individual frames and joins their remaining ancestors/callees. It
24
+ does not discard an entire stack merely because it contains a hidden frame.
25
+ Each remaining stack retains its original weight. If a removed leaf has a kept
26
+ ancestor, its weight becomes self weight on the nearest kept ancestor. If no
27
+ frame remains in a stack, that stack's weight is omitted. Idle/empty-stack weight
28
+ is also omitted. Total/self values and percentages are recomputed from retained
29
+ stacks; they are not percentages of the unfiltered recording.
30
+
31
+ Suppose an 8 MiB allocation profile contains:
32
+
33
+ | Stack | Weight |
34
+ | --- | ---: |
35
+ | framework → render | 2 MiB |
36
+ | framework → render → vendorWork | 2 MiB |
37
+ | framework → helper | 2 MiB |
38
+ | framework | 2 MiB |
39
+
40
+ Including `src/` keeps render and helper, producing 6 MiB total. Render has
41
+ 4 MiB total and self: the hidden vendorWork leaf contributes to render's self
42
+ weight. Also excluding helper's file produces a 4 MiB profile containing render
43
+ alone. The original 8 MiB profile remains available.
44
+
45
+ ## Derived profile behavior
46
+
47
+ Filtered profiles are explicitly aggregate and derived. Time Order is disabled;
48
+ use Left Heavy, Sandwich or Call Tree. Existing Call Tree mode is preserved when
49
+ applying a filter. Filter rules are appended to the profile name, retaining a
50
+ visible history through further transformations and export/reimport. Exports
51
+ include both the original and filtered profiles, their units and aggregate flags.
52
+ “Combine original profiles” excludes derived profiles to avoid double counting.
53
+
54
+ No remaining frames is reported as an error without appending an empty profile.
55
+ Cancel or Escape discards unfinished work. Pasting rules stays inside the dialog
56
+ and does not invoke clipboard-profile import. Replacing the source recording
57
+ aborts/discards the pending result.
58
+
59
+ The implementation visits grouped call paths instead of every original trace
60
+ event, caches each frame's rule match, and yields between bounded batches of
61
+ traversal/stack work. Traversal and cancellation support a 20,000-frame deep-stack
62
+ regression without recursion. Final tree sorting remains synchronous, and the
63
+ original and derived models both occupy memory; this is not an out-of-core filter.
64
+ A local PLC smoke check filtered the selected profile from 16,231 frames to 40
65
+ in about 0.7 seconds, yielding 45 times. That is a single Node measurement, not a
66
+ general browser latency guarantee.
67
+
68
+ ## Memory-profile axes
69
+
70
+ Byte profiles now use power-of-two tick intervals in the main graph and minimap:
71
+ for example 512 KiB steps or whole MiB steps, rendered with the app's existing
72
+ KB/MB/GB labels. Other units retain decimal 1/2/5 spacing. Both axes adapt label
73
+ precision to zoom and skip overlapping labels.