@bymaksym/loadline 0.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.
Files changed (98) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -0
  3. package/bin/loadline.js +50 -0
  4. package/dist/cli/cli/args.js +324 -0
  5. package/dist/cli/cli/args.types.js +3 -0
  6. package/dist/cli/cli/gates.js +173 -0
  7. package/dist/cli/cli/gates.types.js +3 -0
  8. package/dist/cli/cli/main.js +156 -0
  9. package/dist/cli/cli/read-build.js +382 -0
  10. package/dist/cli/cli/read-build.types.js +3 -0
  11. package/dist/cli/cli/render-json.js +116 -0
  12. package/dist/cli/cli/render-json.types.js +10 -0
  13. package/dist/cli/cli/render-markdown.js +30 -0
  14. package/dist/cli/cli/render-pr.js +76 -0
  15. package/dist/cli/cli/render-sarif.js +83 -0
  16. package/dist/cli/cli/render-text.js +388 -0
  17. package/dist/cli/cli/report.js +196 -0
  18. package/dist/cli/cli/report.types.js +3 -0
  19. package/dist/cli/cli/self-check.js +85 -0
  20. package/dist/cli/cli/text.js +180 -0
  21. package/dist/cli/cli/text.types.js +10 -0
  22. package/dist/cli/src/app/core/analysis/analysis.js +661 -0
  23. package/dist/cli/src/app/core/analysis/analysis.types.js +6 -0
  24. package/dist/cli/src/app/core/analysis/barrels.js +128 -0
  25. package/dist/cli/src/app/core/analysis/blast.js +172 -0
  26. package/dist/cli/src/app/core/analysis/cycles.js +110 -0
  27. package/dist/cli/src/app/core/analysis/delivery.js +143 -0
  28. package/dist/cli/src/app/core/analysis/entries.js +217 -0
  29. package/dist/cli/src/app/core/analysis/exclusive.js +91 -0
  30. package/dist/cli/src/app/core/analysis/importers.js +38 -0
  31. package/dist/cli/src/app/core/analysis/insights.js +202 -0
  32. package/dist/cli/src/app/core/analysis/insights.types.js +10 -0
  33. package/dist/cli/src/app/core/analysis/invariant.js +69 -0
  34. package/dist/cli/src/app/core/analysis/metafile.types.js +44 -0
  35. package/dist/cli/src/app/core/analysis/module-graph.js +192 -0
  36. package/dist/cli/src/app/core/analysis/sourcemap.js +231 -0
  37. package/dist/cli/src/app/core/analysis/sourcemap.types.js +3 -0
  38. package/dist/cli/src/app/core/analysis/split-drift.js +47 -0
  39. package/dist/cli/src/app/core/assets/assets.js +296 -0
  40. package/dist/cli/src/app/core/assets/assets.types.js +11 -0
  41. package/dist/cli/src/app/core/baseline/baseline.js +0 -0
  42. package/dist/cli/src/app/core/baseline/baseline.types.js +3 -0
  43. package/dist/cli/src/app/core/caching/caching.js +241 -0
  44. package/dist/cli/src/app/core/caching/caching.types.js +10 -0
  45. package/dist/cli/src/app/core/caching/from-analysis.js +73 -0
  46. package/dist/cli/src/app/core/config/loadline-config.js +110 -0
  47. package/dist/cli/src/app/core/config/loadline-config.types.js +12 -0
  48. package/dist/cli/src/app/core/criteria/criteria.js +228 -0
  49. package/dist/cli/src/app/core/criteria/criteria.types.js +3 -0
  50. package/dist/cli/src/app/core/deps/deps.js +225 -0
  51. package/dist/cli/src/app/core/deps/deps.types.js +15 -0
  52. package/dist/cli/src/app/core/export/markdown-table.utils.js +40 -0
  53. package/dist/cli/src/app/core/export/summary.js +72 -0
  54. package/dist/cli/src/app/core/findings/actions.js +59 -0
  55. package/dist/cli/src/app/core/findings/assets.js +130 -0
  56. package/dist/cli/src/app/core/findings/caching.js +165 -0
  57. package/dist/cli/src/app/core/findings/compose.js +41 -0
  58. package/dist/cli/src/app/core/findings/deps.js +66 -0
  59. package/dist/cli/src/app/core/findings/effort.js +117 -0
  60. package/dist/cli/src/app/core/findings/finding-html.js +13 -0
  61. package/dist/cli/src/app/core/findings/finding-plain.js +26 -0
  62. package/dist/cli/src/app/core/findings/finding-text.js +1231 -0
  63. package/dist/cli/src/app/core/findings/finding.types.js +80 -0
  64. package/dist/cli/src/app/core/findings/findings.js +514 -0
  65. package/dist/cli/src/app/core/findings/graph.js +167 -0
  66. package/dist/cli/src/app/core/findings/own-in-boot.js +88 -0
  67. package/dist/cli/src/app/core/findings/page.js +49 -0
  68. package/dist/cli/src/app/core/findings/requests.js +185 -0
  69. package/dist/cli/src/app/core/findings/scan.js +126 -0
  70. package/dist/cli/src/app/core/findings/shipped.js +244 -0
  71. package/dist/cli/src/app/core/findings/situation.js +116 -0
  72. package/dist/cli/src/app/core/format/format.utils.js +204 -0
  73. package/dist/cli/src/app/core/i18n/en.js +819 -0
  74. package/dist/cli/src/app/core/i18n/es.js +822 -0
  75. package/dist/cli/src/app/core/i18n/ui-strings.js +11 -0
  76. package/dist/cli/src/app/core/i18n/ui.js +7 -0
  77. package/dist/cli/src/app/core/intake/bundle-graph.js +346 -0
  78. package/dist/cli/src/app/core/intake/bundle-graph.types.js +3 -0
  79. package/dist/cli/src/app/core/intake/dist-files.js +160 -0
  80. package/dist/cli/src/app/core/intake/index-html.js +292 -0
  81. package/dist/cli/src/app/core/json/json.utils.js +55 -0
  82. package/dist/cli/src/app/core/measurement/measurement.types.js +14 -0
  83. package/dist/cli/src/app/core/project/budget-advice.js +76 -0
  84. package/dist/cli/src/app/core/project/project-context.js +394 -0
  85. package/dist/cli/src/app/core/project/project-context.types.js +3 -0
  86. package/dist/cli/src/app/core/scan/catalog.js +67 -0
  87. package/dist/cli/src/app/core/scan/scan.js +280 -0
  88. package/dist/cli/src/app/core/scan/scan.types.js +10 -0
  89. package/dist/cli/src/app/core/scan/secrets.js +0 -0
  90. package/dist/cli/src/app/core/situation/situation.js +261 -0
  91. package/dist/cli/src/app/core/situation/situation.types.js +19 -0
  92. package/dist/cli/src/app/core/timing/timing.js +87 -0
  93. package/dist/cli/src/app/core/timing/timing.types.js +3 -0
  94. package/dist/cli/src/app/core/whatif/defer.js +68 -0
  95. package/dist/cli/src/app/state/report-messages.utils.js +73 -0
  96. package/docs/HOW-IT-WORKS.md +1087 -0
  97. package/loadline.html +78 -0
  98. package/package.json +154 -0
@@ -0,0 +1,1087 @@
1
+ # How Loadline works
2
+
3
+ [← Back to the README](../README.md)
4
+
5
+ ---
6
+
7
+ ## 1. The idea
8
+
9
+ The browser does not download your project. It downloads a handful of JavaScript files your bundler
10
+ built by fusing hundreds of source files together, and how it grouped them decides whether opening
11
+ the app costs 400 kB or 900 kB. Loadline reconstructs that grouping and reports it **per screen**
12
+ rather than per file.
13
+
14
+ There are two ways one file can reach another, and they mean opposite things:
15
+
16
+ ```ts
17
+ import { thing } from './b'; // static: A and B always travel TOGETHER
18
+ const { thing } = await import('./b'); // dynamic: B travels separately
19
+ ```
20
+
21
+ | Group | What it is | When it downloads |
22
+ | ---------------------------------- | ------------------------------------------------- | ------------------------- |
23
+ | **Bootstrap** (`initial`, `eager`) | Reachable from the entry point via static imports | Always |
24
+ | **Lazy** | Whatever hangs off a dynamic import | When that code is reached |
25
+
26
+ In Angular, `loadComponent`, `loadChildren` and `@defer` are dynamic imports; everything else is
27
+ static.
28
+
29
+ **The blind spot.** When two lazy screens use the same thing, the bundler does not duplicate it — it
30
+ builds a third, shared chunk, which appears in the lazy list. If every screen imports that chunk, it
31
+ downloads every time anyway. Counting how many screens reach each chunk is what the rest of this
32
+ document is built on.
33
+
34
+ ---
35
+
36
+ ## 2. The algorithm
37
+
38
+ Everything comes from one graph: which source file ended up in which chunk, how many bytes each
39
+ contributes, and who imports whom. The esbuild metafile records it directly; a build folder is read
40
+ for it instead when there is no metafile (§5). From here on the two are the same thing — the
41
+ algorithm never learns which one it got.
42
+
43
+ ### 2.1 Reachability over static imports
44
+
45
+ ```js
46
+ const reach = start => {
47
+ const seen = new Set();
48
+ const stack = [start];
49
+ while (stack.length) {
50
+ const file = stack.pop();
51
+ if (!file || seen.has(file) || !outputs[file]) continue;
52
+ seen.add(file);
53
+ for (const imp of outputs[file].imports || []) {
54
+ if (imp.kind === 'import-statement') stack.push(imp.path); // <- static only
55
+ }
56
+ }
57
+ return seen;
58
+ };
59
+ ```
60
+
61
+ Filtering on `import-statement` is the whole trick. A `dynamic-import` is the lazy boundary:
62
+ following it would merge everything and report the entire bundle every time.
63
+
64
+ ### 2.2 Finding the main entry
65
+
66
+ An output is a **lazy entry** when some other output has a `dynamic-import` pointing at it. The main
67
+ entry is one that is not. Several candidates can exist — some libraries emit a stray entry, such as a
68
+ worker — so the one reaching the most code wins:
69
+
70
+ ```js
71
+ const mainChunk = rootCandidates.map(([k]) => [k, reach(k).size]).sort((a, b) => b[1] - a[1])[0][0];
72
+ const alsoStarted = rootCandidates.filter(([k]) => k !== mainChunk && announced.has(baseName(k)));
73
+ const initial = new Set([mainChunk, ...alsoStarted.map(([k]) => k)].flatMap(k => [...reach(k)]));
74
+ ```
75
+
76
+ ⚠️ **An application does not have to have one entry chunk.** Angular's polyfills are a second one and
77
+ SvelteKit starts two, its router and the application, from a script inside the page. Taking the main
78
+ one alone left real bootstrap chunks out of the figure everybody pays. What decides is the page: an
79
+ entry nobody announces is not downloaded on the first load and stays out, which is what keeps the
80
+ worker out.
81
+
82
+ ### 2.3 Detecting screens
83
+
84
+ Lazy entries whose `entryPoint` is your own code:
85
+
86
+ ```js
87
+ const routes = entries
88
+ .filter(([k]) => lazyTargets.has(k))
89
+ .filter(r => !/node_modules/.test(r.source)) // xlsx, pdf.js: not screens
90
+ .filter(r => !/\.routes?\.(t|j)s$/.test(r.source)); // grouping files own nothing
91
+ ```
92
+
93
+ ⚠️ **Both filters came out of testing.** Without the first, `FileSaver.min` and `xlsx` showed up as
94
+ screens — an `await import('xlsx')` produces a lazy entry too. Without the second, routing files
95
+ clutter the list with rows that are nobody's screen.
96
+
97
+ Three more rules joined them:
98
+
99
+ - **A lazy entry that only views import lazily is a piece of a screen, not a screen.** This is the
100
+ rule that keeps the table honest as `@defer` spreads; see §5.
101
+ - **A screen has to be reachable from where the application starts**, following both kinds of import.
102
+ A folder nobody cleans still holds the previous build, and those old chunks were taking rows in the
103
+ table while none of their bytes appeared in any figure.
104
+ - **Data is not a screen.** `import('./locales/ru-RU.json')` produces a lazy entry exactly like a
105
+ route does. Excalidraw lazy-loads fifty languages, and its table came out with sixty-one rows for
106
+ an application with one screen. Data entries are listed separately.
107
+
108
+ ### 2.4 Splitting the cost
109
+
110
+ For each screen: what it reaches, minus the bootstrap, split into what only it loads and what it
111
+ shares.
112
+
113
+ ```js
114
+ const lazy = [...r.set].filter(c => !initial.has(c));
115
+ const own = lazy.filter(c => routeCount.get(c) === 1);
116
+ const shared = lazy.filter(c => routeCount.get(c) > 1);
117
+ const total = bootBytes + sumOf(lazy);
118
+ ```
119
+
120
+ `routeCount` — how many screens reach each chunk — is the figure the whole tool is built around.
121
+
122
+ ### 2.5 Compressing
123
+
124
+ Each file in the build folder is gzipped in the browser with the native API:
125
+
126
+ ```js
127
+ const stream = file.stream().pipeThrough(new CompressionStream('gzip'));
128
+ ```
129
+
130
+ **At which level.** zlib's default, 6. `CompressionStream('gzip')` in the browser and `createGzip()`
131
+ in the command are the same library at the same setting, which is why the page and the terminal print
132
+ the same figure for the same file, and it is what nginx, Apache and most CDNs serve at by default. A
133
+ server tuned to 9 sends slightly less and one tuned to 1 slightly more — a few per cent, in the same
134
+ direction for every file, so it moves the headline and not the ordering.
135
+
136
+ **What is compressed is the file, never its parts.** Gzip works on the whole chunk, using repetitions
137
+ that cross from one module into the next, so "the compressed weight of `date-fns` inside this chunk"
138
+ is not a quantity that exists. The breakdown inside a chunk is therefore always raw, even while the
139
+ report is in compressed figures. To keep the two units from being confused, the chunk's row carries
140
+ its raw size under the compressed one, and the head of its file tree says `raw` and how much of the
141
+ chunk is unattributed. Those bytes are the bundler's own code — module wrapper, banners — which
142
+ belongs to no input file. The sum of the files plus that remainder is the raw size on the row, when
143
+ the two measurements agree, which is checked rather than assumed (§3.23). Other tools
144
+ (`esbuild-visualizer`, Sonda) show the raw figure as the chunk's headline, which is why their numbers
145
+ look nothing like Loadline's until both are read in the same unit.
146
+
147
+ **Brotli.** The browser cannot compress in brotli: `CompressionStream` offers gzip and deflate only.
148
+ `brotli-wasm` ships 1,057 kB of `.wasm`, almost three times the whole of Loadline, and in a
149
+ self-contained HTML file that is paid in base64 — measured and dropped. What works instead: when the
150
+ folder brings pre-compressed `main-ABC.js.br` files, their size on disk **is** the brotli figure, with
151
+ nothing to decompress. Both figures are then available and Criteria picks which drives the report;
152
+ the brotli thresholds are the gzip ones minus 15 %, which is how much more it compresses (measured on
153
+ this build: 0.865 and 0.856). Without `.br` in the folder, the Criteria tab warns that a red just
154
+ above the threshold may not be red in production.
155
+
156
+ ### 2.6 Searching by name
157
+
158
+ The rest of the report answers _what is heavy_. The question that actually turns up is the other way
159
+ round — "are we still shipping `moment`?" — and it used to mean opening chunk after chunk.
160
+
161
+ The index is built once per analysis from what is already in memory: every file that ships bytes,
162
+ with the chunks it lands in. Files under `node_modules` are grouped by package, because that is the
163
+ unit a decision is taken about; project files stay one per file, because that is the unit that gets
164
+ edited. A package also matches on the names of its files, so `md5` finds `crypto-js`.
165
+
166
+ Each result says which chunks carry it, how much in each, which screens load it, and the import chain
167
+ that brings it in. Two details that came out of real use:
168
+
169
+ - **The zone is that of the heaviest chunk, not the worst one.** PrimeNG landed in five chunks of one
170
+ app: 612 kB in a shared one and 145 kB in the bootstrap. Calling it "bootstrap" would say every load
171
+ pays 772 kB for it, and it pays 145. It says "shared", and underneath, how much falls in the
172
+ bootstrap.
173
+ - **Finding nothing is an answer.** "Nothing called _moment_ is in the bundle" could not previously be
174
+ established without walking everything and still being unsure.
175
+
176
+ ### 2.7 What a shared chunk costs, and where the cost comes from
177
+
178
+ A tab saying "58 kB across 44 of 47 screens" leaves the reader with the next question: is that as bad
179
+ as it looks, and which part of it is the weight? Three things can be computed for it
180
+ (`core/worth/worth.ts`).
181
+
182
+ **What it really costs: size × coverage.** 58 kB loaded by 44 of 47 screens costs 54 kB on a typical
183
+ visit; the same 58 kB loaded by 5 of them costs 6 kB. Same row in the size column, ten times the cost.
184
+ That weighted figure is what the report ranks and prices with, and next to it goes what a typical
185
+ visit would weigh with the chunk gone — the ceiling of any fix.
186
+
187
+ **Splitting a shared chunk saves nothing.** esbuild builds one chunk per distinct set of entry points
188
+ that reach a module, so every file inside a chunk is reached by exactly the same screens; cutting it
189
+ in two produces two chunks the same screens load. This follows from how the split is made, and it
190
+ retires the first idea most people have on seeing the tab. What lowers the figure is fewer screens
191
+ importing the thing, or the thing weighing less.
192
+
193
+ **Where the weight comes from** depends on what the chunk carries, and the analysis already groups it
194
+ by package and by project folder:
195
+
196
+ | What dominates it (≥ 50 %) | Tag | Because |
197
+ | ------------------------------------- | ---------------------- | ----------------------------------------------------------------------- |
198
+ | Nothing — the cost is under the floor | Below the threshold | The gain is lost between any two builds |
199
+ | A folder of your own code | Your own code | Nothing to negotiate: usually a barrel file re-exporting a whole folder |
200
+ | A package few of your files import | 1 package · N of yours | Few importers is an address: one place to check whether it is needed |
201
+ | A package imported from all over | No dominant source | No single file to point at; using less of it is the way out |
202
+
203
+ The thresholds are the criteria already in the tool — the minimum size for a shared chunk to be a
204
+ signal, and the number of importers above which a package counts as infrastructure — so the tag moves
205
+ when the reader moves them.
206
+
207
+ **The tags describe the measurement, they do not rate the work.** An earlier version said "not worth
208
+ it" and "no easy fix": both are claims about somebody else's project, and a reader who knows better
209
+ can simply be right. "No dominant source" is a statement about the import graph, which the reader can
210
+ open and check. The cost figure ranks, the tag says where to look, the conclusion stays with whoever
211
+ draws it.
212
+
213
+ The tab totals them at the top: of the chunks almost everybody downloads, how many have a named
214
+ source and how much of a typical visit they account for.
215
+
216
+ ### 2.8 The shape of the split
217
+
218
+ Every other figure judges one thing — this chunk, that screen, this package. After a list of a hundred
219
+ chunks, the question none of them answers is whether the build is **well divided**.
220
+
221
+ That is not a property of any row. More chunks is not better and fewer is not better: what matters is
222
+ that what a screen needs at once arrives in few pieces and what it may never need stays apart. So it
223
+ is measured on the distribution (`core/analysis/shape.ts`), with two numbers per zone:
224
+
225
+ - **Concentration**: how much of a zone sits in its largest chunk. Fifteen shared chunks where one
226
+ holds 93 % is a different situation from fifteen even ones, and a list of fifteen rows hides it.
227
+ - **Crumbs**: how many pieces are under 5 kB, and what they add up to. One crumb is fine; many
228
+ arriving together is a split that went further than it helps.
229
+
230
+ The same reading applies to a single download (`granularityOf`), which is what a screen's detail says:
231
+ "29 files, and 4 of them are 80 % of the weight. 19 are under 5 kB."
232
+
233
+ ⚠️ **It never says a number of chunks is wrong.** A small chunk that is genuinely lazy is doing its
234
+ job (§3.14), so the block is descriptive on purpose: a few lines of fact above the list.
235
+
236
+ **How the block is ordered.** Two questions, nested: **when** each part comes down — eager or lazy,
237
+ the split every bundler reports — and, inside the lazy half, **who pays** for it. The three zones were
238
+ there first and are strictly finer, but reading "how much of this app is deferred at all" meant adding
239
+ two of the three rows in your head. So lazy is a line of its own with shared and own hanging from it,
240
+ and a bar above them carries the same three colours with a gap where eager ends. The filter buttons
241
+ follow the same order. In the tree, a chunk holding at least a quarter of its zone carries that figure
242
+ on its row — zone and size were already there, and the division of one by the other is what says
243
+ whether a row is where the weight is.
244
+
245
+ ### 2.9 When a chunk arrives, and in how many round trips
246
+
247
+ **Eager or lazy** falls straight out of §2.1 and is a second name for what the report calls the
248
+ bootstrap. It is shown anyway because "lazy" is the word people arrive with, and putting it next to
249
+ "19 screens load it" is what makes the contradiction land.
250
+
251
+ **Round trips** is the part no bundler reports. A browser does not know a chunk exists until it has
252
+ downloaded and parsed the one importing it, so entering a screen costs at least two sequential
253
+ requests — the screen's chunk, then the shared chunks it imports — and three if one of those imports
254
+ another. Breadth-first from the screen's entry chunk over static imports, stopping at the bootstrap
255
+ because that is already there:
256
+
257
+ ```js
258
+ const trips = wavesFrom(outputs, [screen.chunk], boot);
259
+ ```
260
+
261
+ The distance is the shortest one, because the browser asks for a chunk as soon as the first parent
262
+ mentioning it is parsed. The count is per screen: the same shared chunk can be the second trip for one
263
+ screen and the third for another. It matters because two screens of 240 kB are not the same screen —
264
+ one trip at 200 ms of latency is 200 ms, three is 600 ms, and a table of bytes shows them as
265
+ identical.
266
+
267
+ **The first load is a separate calculation.** For the bootstrap the graph is not enough: Angular writes
268
+ the entry script and a `modulepreload` link per initial chunk into `index.html`, and everything that
269
+ page names is requested at once regardless of its depth in the graph. A bootstrap chunk it does not
270
+ name is discovered by parsing, which is another trip. So the figure only exists when the build folder
271
+ was loaded with that page; without it, Loadline says "not known" rather than printing a number derived
272
+ from the wrong thing. The page is read with regular expressions rather than `DOMParser`, so the
273
+ command and the browser read it the same way.
274
+
275
+ ---
276
+
277
+ ## 3. The signals
278
+
279
+ A number on its own is not a problem. What turns data into something worth touching is context: how
280
+ many people pay for it, who really uses it, and what fixing it costs.
281
+
282
+ ### 3.1 Common code dressed as lazy
283
+
284
+ **Fires when** a chunk is imported by ≥ 60 % of screens and weighs more than 50 kB.
285
+
286
+ It is not lazy in any useful sense; it always downloads.
287
+
288
+ **What not to do**: split it on reflex. If most of the weight really is used by nearly every screen —
289
+ a table, form fields, the sidebar — splitting redistributes it rather than removing it. What pays off
290
+ is pulling out the components a **single** screen uses.
291
+
292
+ ### 3.2 Bootstrap for a lazy screen
293
+
294
+ **Fires when** a package over 25 kB sits in the bootstrap, is imported by ≤ 4 files, **and at least
295
+ one of those files is a lazily loaded screen**.
296
+
297
+ ⚠️ **That last condition is what makes the signal useful.** The obvious criterion — "few files import
298
+ it" — also flags your theme, which one file imports and which genuinely is needed before first paint.
299
+ What separates a real candidate is that its consumer lives in a lazy screen. The case that produced
300
+ it: a Microsoft sign-in library registered in the bootstrap config whose real consumer was the login
301
+ screen, downloaded by everyone including people who already had a session.
302
+
303
+ ⚠️ **The label says "≤ 4 importers, at least one lazy", not "only lazy screens import it".** The
304
+ second is a stronger claim than the rule makes: a package with three bootstrap importers and one lazy
305
+ one matches too. The row carries the count (`2 of 3 in lazy screens: login, microsoft-callback`),
306
+ which is checkable and says which of the two cases the reader has.
307
+
308
+ **Where to touch**: the signal gives the import chain the package enters through and the routes file
309
+ that loads the screen. Both come from the metafile's `inputs` graph — the chain is the shortest path
310
+ over static imports from `main.ts` to the package (`main.ts › app.config.ts ›
311
+ core/config/msal.config.ts › @azure/msal-browser`), and the routes file is the one doing the
312
+ `import()` of the screen. The last file of yours in the chain holds the import to move; the routes
313
+ file is where the providers go.
314
+
315
+ ### 3.3 Large source file
316
+
317
+ **Fires when** one of your own files exceeds 20 kB inside the bootstrap.
318
+
319
+ Usually a constants table — translation keys, catalogues, routes — pulled in whole because it is
320
+ referenced from everywhere. Check the compressed size before touching it: repetitive text compresses
321
+ enormously, and what looks like the second-biggest problem raw can be irrelevant.
322
+
323
+ ### 3.4 Duplicate versions
324
+
325
+ **Fires when** the same package appears at two versions in the metafile paths.
326
+
327
+ You pay the weight twice because two dependencies ask for incompatible ranges. Knowing there are two
328
+ says nothing about what to do, so each copy is followed separately and reported with its import chain,
329
+ its size, whether it lands in the bootstrap and who imports it. With that, the fix is decided without
330
+ opening the lockfile: if both copies come in through dependencies you asked for, align the versions in
331
+ `package.json`; if one is dragged in by a dependency of a dependency, the resolution has to be forced.
332
+ In the application this was checked against, `@primeuix/utils` 0.7.2 came in through `primeng` and
333
+ 0.6.4 through `@primeuix/styled`, neither asked for directly, so aligning `package.json` would have
334
+ moved nothing.
335
+
336
+ Only a copy that actually weighs something in some chunk counts: a version resolved but tree-shaken
337
+ away is not paid twice.
338
+
339
+ ### 3.5 Expensive screen
340
+
341
+ **Fires when** a screen carries more than 6× the median of its own code, and over 100 kB.
342
+
343
+ It drags in a heavy library for itself alone. If that library is only needed once you open something
344
+ _inside_ the screen — a viewer, an editor, a chart — it belongs in a deferred block.
345
+
346
+ ### 3.6 Against the previous measurement
347
+
348
+ These fire only with a baseline loaded: the previous build's `stats.json`, a Loadline export, or the
349
+ whole previous build folder. Both measurements are always compared in the same mode — a bare previous
350
+ `stats.json` is compared raw even if the report is compressed, and the table says so. For compressed
351
+ against compressed, give the previous folder with its `stats.json` inside.
352
+
353
+ - **The bootstrap has grown** — by 10 % and 10 kB or more, editable under Criteria.
354
+ - **A package has entered the bootstrap** — an npm package that was not in the baseline's. Project
355
+ folders do not count: they change with every commit.
356
+ - **A screen has grown** — shared + own is compared, **without the bootstrap**. Comparing totals, a
357
+ bigger bootstrap would flag all twenty screens at once.
358
+
359
+ ⚠️ **One trap remains**: when a near-global shared chunk grows, every screen loading it goes up by the
360
+ same amount — in one real app, 19 screens at "+247 kB". So when most screens grow by about the same
361
+ amount, the signal changes: it says a shared chunk grew and sends you to that tab, not to 19 places.
362
+
363
+ ### 3.7 The size budget that does not apply
364
+
365
+ These fire only with `angular.json` loaded; the pipeline ones also need `.gitlab-ci.yml` or the GitHub
366
+ workflow. With `package.json`, scripts are followed: `pnpm run build:pre` → `ng build
367
+ --configuration=preproduction`.
368
+
369
+ - **The strictest budget lives in a configuration the pipeline does not build.** Angular only checks
370
+ the `budgets` of the configuration it builds. This is the failure that motivated the tool: in one
371
+ app the 1.5 MB budget lived in `production` while the pipeline built `development` (no budget) and
372
+ `preproduction` (3 MB).
373
+ - **The budget cannot fire** — `maximumError` is more than twice the current raw bootstrap.
374
+ - **The budget only warns** — a `maximumWarning` with no `maximumError`. A warning in the build output
375
+ is read the first time and ignored the second.
376
+ - **No configuration declares a budget.**
377
+
378
+ Angular's budgets measure initial JS + CSS uncompressed; Loadline compares against the raw bootstrap
379
+ JS, and the difference is the few kB of `styles.css`.
380
+
381
+ ### 3.8 No zone.js
382
+
383
+ Informational, not counted towards the verdict. Detected from the polyfills in `angular.json` or from
384
+ the absence of `zone.js` among the dependencies. It rules out the material about change detection
385
+ cycles, `NgZone` and `runOutsideAngular` up front: in a zoneless project there is nothing to optimise
386
+ there.
387
+
388
+ ### 3.9 CommonJS package
389
+
390
+ **Fires when** a file under `node_modules` has `format: "cjs"` in the metafile. To review when the
391
+ package sits in the bootstrap, informational when only some screens load it.
392
+
393
+ A CommonJS package cannot be analysed at build time, so every file of it you import comes in whole
394
+ even for a single function. It is the same warning Angular prints ("CommonJS or AMD dependencies can
395
+ cause optimization bailouts"), with the size, the zone it lands in and who imports it — or which
396
+ package drags it in, when no file of yours imports it directly.
397
+
398
+ It comes from the metafile rather than the build output because esbuild records the format of every
399
+ file it processes: nothing to paste, no `package.json` under `node_modules` to read, and no false
400
+ positive from grepping `"type"` and hitting `"type": "git"`.
401
+
402
+ The size is raw and is what the file takes inside the chunk. Adding the package to
403
+ `allowedCommonJsDependencies` only silences the warning.
404
+
405
+ ### 3.10 Against the browser's measurement
406
+
407
+ **Fires when** somebody pastes what their browser downloaded into the Measured tab. Three signals:
408
+ measured above computed, the router loading an area the guard then rejects, and measured below
409
+ computed (informational).
410
+
411
+ **What is compared** is the set of chunks, not the byte figure. A chunk that came down without being
412
+ predicted is a fact, whatever unit the report is in. Only afterwards is the difference priced with
413
+ Loadline's own figures.
414
+
415
+ **How it is attributed to a screen**: the one that best explains what came down — every chunk of its
416
+ own present counts, every one missing counts against — overridable by hand. If only the bootstrap came
417
+ down there is no screen, and that is the right answer.
418
+
419
+ **Where the guard signal comes from**: extra chunks exclusive to other screens. It is not "the
420
+ computation falls short", it is "this screen paid for that one". The fix is `canMatch` rather than
421
+ `canActivate`: the first discards the route without requesting its chunk, the second runs once it is
422
+ already down.
423
+
424
+ CSS, fonts and images are not counted — Loadline's figures are JavaScript. A downloaded `.js` that is
425
+ not from this build is shown separately: it almost always means a different deployment is being
426
+ measured.
427
+
428
+ ### 3.11 Every language of a library
429
+
430
+ **Fires when** a package ships three or more distinct languages adding up to 10 kB or more. To review
431
+ in the bootstrap, informational otherwise.
432
+
433
+ A library that keeps its languages in a `locale/` folder ships all of them when imported from its
434
+ root, and then one gets used. It is the single largest cut reported in the field — one team went from
435
+ 443 MB to 46 MB of build output by excluding locale files — and it hides well, because no individual
436
+ file is big.
437
+
438
+ **Why languages and not files**: `date-fns` splits one language across ten files under
439
+ `locale/en-US/_lib/`, so counting files would report ten languages where there is one. Distinct codes
440
+ are counted instead, looked for in the two places libraries put them: the file name
441
+ (`moment/locale/es.js`, `primelocale/es.json`) and the folder right after `locale/`
442
+ (`date-fns/locale/es/index.js`). There is no list of package names, because a list would be right for
443
+ the libraries in fashion today and wrong for next year's; the folder convention is older than any of
444
+ them.
445
+
446
+ ### 3.12 Data travelling as code
447
+
448
+ **Fires when** `.json` files inside the bundle add up to 10 kB or more, once the ones already reported
449
+ as languages are taken out. To review in the bootstrap, informational otherwise.
450
+
451
+ An `import` of a data file is not a reference: the content ends up embedded in a chunk of JavaScript,
452
+ downloaded and parsed with it. A list of countries for a dropdown is the usual case. Fetched with a
453
+ request instead, it caches on its own, does not block startup, and changing it does not invalidate the
454
+ JavaScript.
455
+
456
+ ### 3.13 Source maps in the folder you deploy
457
+
458
+ **Fires when** the build folder brings `.js.map` files. Informational always: Loadline cannot know
459
+ whether that folder is the one deployed, and says so instead of accusing.
460
+
461
+ A source map reconstructs your source from the compiled output. It does not weigh on the download —
462
+ the browser only asks for it if somebody opens the tools — but if those files reach the server,
463
+ whoever knows the URL has your code. `"sourceMap": { "scripts": true, "hidden": true }` generates them
464
+ without linking them from the bundle, which is what you want in order to upload them to an error
465
+ tracker; the part that gets forgotten is that not linking them is not the same as not serving them.
466
+
467
+ It is the one finding in the report that is not about size, and it costs nothing, since the folder is
468
+ already read for the compressed figures.
469
+
470
+ ### 3.14 Many requests for one screen
471
+
472
+ **Fires when** the typical screen downloads more files than `screenFilesMax` (30 by default, editable)
473
+ **and** at least five of them are under 1 kB. To review.
474
+
475
+ The one figure in the report that is not about bytes. Each file is a request, a cache entry and a
476
+ module wrapper; below a kilobyte, asking for it costs about what it holds.
477
+
478
+ **Why two conditions**: a file count on its own says "your application is large", which is not a
479
+ finding. The two together say "this is split further than it helps", which is.
480
+
481
+ **Why what a screen loads and not the build's chunk list**: a small chunk is not a problem when it is
482
+ genuinely lazy. A 5 kB chunk for an admin screen hardly anybody opens is doing its job — those 5 kB
483
+ never download. Only code that arrives **together** counts, so the signal looks at the bootstrap plus
484
+ what that one screen pulls in.
485
+
486
+ **What it does not claim**: that chunks under 30 kB are bad, which is the shape this rule usually
487
+ takes and is wrong; or that more requests are worse, which over HTTP/2 and HTTP/3 they are not.
488
+
489
+ **What to do**: the split is nobody's decision. The bundler makes one chunk per distinct set of
490
+ screens reaching a module, so many chunks means many combinations. They come down by removing
491
+ combinations — a barrel file imported by a handful of screens produces one chunk per mix — and merging
492
+ by hand (`manualChunks`, `ngx-build`) can make caching worse.
493
+
494
+ ### 3.15 Your own code in the bootstrap for a deferred screen
495
+
496
+ **Fires when** folders of your own code in the bootstrap, whose files are imported by at least one
497
+ deferred screen and held there by no more than four files that are not screens, add up to half of what
498
+ a package has to weigh to be named. To review.
499
+
500
+ The same question §3.2 asks of an npm package, asked of your code: a service imported by
501
+ `app.config.ts` and by one page downloads on every visit, while the page it was written for is
502
+ deferred.
503
+
504
+ **Why by folder and not by file.** Written per file first, it found nothing on a real build: the
505
+ business layer was in the bootstrap across thirty files of one to three kilobytes each, every one far
506
+ below any size worth naming and together a layer that should not be there. The folder is the unit the
507
+ problem has. The size floor applies to the **total** for the same reason one level up — one folder of
508
+ two kilobytes is noise, the same layer across six of them is a pattern — while the structural
509
+ condition is checked per folder.
510
+
511
+ **What it insists on**: the list of files keeping it in the bootstrap, all of them. Moving the first
512
+ and leaving the other two changes nothing, which is the mistake the signal exists to prevent. If the
513
+ bootstrap file that imports it genuinely needs it, there is nothing to move and the signal is a fact
514
+ rather than a task, which the text says.
515
+
516
+ ### 3.16 The first load in several round trips
517
+
518
+ **Fires when** `index.html` was read and does not name every chunk of the bootstrap, so the browser
519
+ only discovers one of them after parsing another. To review.
520
+
521
+ What §3.5 says about a screen, said about the one load nobody skips. A chunk the page names — the
522
+ entry script or a `modulepreload` link — is requested straight away; one it does not name waits for
523
+ the chunk importing it to arrive and be parsed. Same bytes, one round trip later, in front of the
524
+ first paint.
525
+
526
+ **Why it has no threshold**, while everything else weighs something against a criterion: "how many
527
+ files is too many" is a judgement and this is not one. Either the page names the whole bootstrap or it
528
+ does not.
529
+
530
+ **What to do**: a `modulepreload` link for the missing chunks. Angular emits them for the initial
531
+ chunks and Vite has `build.modulePreload`; when that is switched off, this is the bill. If those
532
+ chunks turn out not to be needed before the first paint, deferring them is the better fix, because
533
+ then the first load also weighs less.
534
+
535
+ ### 3.17 A folder without source maps
536
+
537
+ **Fires when** the graph was read from the folder and the folder carries no `.js.map`. Informational
538
+ always: not a problem with the build, a shorter report.
539
+
540
+ The weight of each chunk is known and what is inside it is not. Screens end up named after their chunk
541
+ file — `0fPdmq0U.js` rather than `orders` — and there is no breakdown by package and no chain from the
542
+ entry point. Everything else comes out in full. It exists because two real builds, elk and immich,
543
+ neither of which publishes maps, came out as a page of hashes with nothing to explain them.
544
+
545
+ ### 3.18 What the report cannot reach
546
+
547
+ **Fires when** some JavaScript of the build is imported by nothing reachable from the entry point, by
548
+ either kind of import. A problem when those chunks are most of the bytes, informational otherwise.
549
+
550
+ The only signal about the report rather than about the build. Three things land here, with a different
551
+ answer each: a **service worker**, which is not part of any load a browser makes from the page; an
552
+ `import()` whose **path is built at run time**, which VitePress writes one of per page; and the
553
+ **leftovers of a previous build** in a folder nobody empties.
554
+
555
+ **Why the share decides the severity**: the Vue documentation site has 244 chunks and 233 of them —
556
+ 9.2 MB — are page chunks reached that way. Describing the other eleven and saying nothing about those
557
+ is the report describing a corner of the build in the voice it uses for the whole of it. Two service
558
+ workers in a 45 MB folder are a footnote, and printing both the same way would bury the first.
559
+
560
+ ### 3.19 The hash cascade
561
+
562
+ **Fires when** a chunk carries the hashed names of two or more others inside it, which is nearly
563
+ always. Informational by default — see §3.22 for what gives it a colour.
564
+
565
+ A bundler writes the hashed file name of every chunk it imports **into** the chunk importing it. So
566
+ changing a leaf changes the leaf's hash, which changes the text of whatever names it, which changes
567
+ that file's hash, and so on. The mental model to correct is that this travels upwards: the usual shape
568
+ in Vite and Rollup is **hub-and-spoke**, one shared chunk every route imports and that transitively
569
+ reaches them all. Change a leaf → the hub changes → everything importing the hub changes, which in a
570
+ single-page application is nearly everything. It does not grow with depth; it jumps.
571
+
572
+ **Measured rather than argued about.** The topology says how far a change travels, so it is read off
573
+ this build — which chunk names the most others, and how many name it — and reported as LOW, MID or
574
+ HIGH with the reason. LOW is the runtime-chunk shape, which is what webpack emits and what largely
575
+ avoids the problem, with the caveat that usually gets dropped: that chunk changes on every deploy and
576
+ has to be tiny and inlined, or the cost comes straight back.
577
+
578
+ **With a baseline it stops being a model.** Two builds diffed by file name _are_ the delta a browser
579
+ would pay. The changed files split into the ones where the edit landed and the ones that only moved
580
+ because a name inside them moved; the second group is the cascade, with its counterfactual next to it.
581
+
582
+ **Where there is no edit left to point at.** `roots` is the changed files that name no other changed
583
+ file. On the default Vite and Rollup layout there are none — the lazy chunks import back from the
584
+ entry chunk, so the naming graph among the changed files closes on itself — and eight of the nineteen
585
+ framework probes came out that way. The sentence read _"only 0 name no other file that also changed
586
+ (0 B): ."_, followed by "that is where the edit landed" and a counterfactual saying the deploy would
587
+ have cost nothing. All three false. It now says the split is unavailable and why, which is itself the
588
+ finding: a naming graph that closes on itself **is** the hub shape, and the case where the cascade
589
+ argument is strongest.
590
+
591
+ **Except where the name _is_ the hash.** SvelteKit, Nuxt and Rollup write chunks called `ChDGvcpR.js`,
592
+ and taking the hash off one of those leaves `.js`. Matching by name had nothing to work with, so every
593
+ chunk read as one file gone and another arrived: on the Nuxt probe, a one-line edit to a shared module
594
+ came out as **8 files removed and 8 added, 100 % of the build re-downloaded, and an empty
595
+ edit-versus-cascade split**. Those chunks are matched instead by the largest source file inside them,
596
+ which the analysis already works out — not a heuristic over the bytes, but what the chunk is made of,
597
+ read from the same metafile or source map the weights come from. A content key naming two chunks on
598
+ one side is not used, and where the build said nothing about its contents, matching falls back to the
599
+ name. The same edit now reads: **4 files changed, 94 %, and 339 B of it is the edit.**
600
+
601
+ **What not to do**: reach for coarser chunks. The two arguments point in opposite directions —
602
+ compression dictionaries make the re-download cheap rather than rarer, and a bigger chunk invalidates
603
+ more — so every way out is named with its price and none is recommended. Import maps move the
604
+ specifiers into the HTML, at the cost of an uncacheable HTML, which it usually already is. Breaking
605
+ the hub with `manualChunks` is paid for with a bigger first load, which Rollup's own documentation
606
+ says.
607
+
608
+ ⚠️ **A citation worth reading in full**: tooling.report's tests say Rollup should not have this
609
+ problem, and they cover a two-level case. A real application with one shared chunk every route imports
610
+ fails all the same. The citation is correct and does not mean what it looks like.
611
+
612
+ ### 3.20 What is served, rather than what was built
613
+
614
+ **Fires when** somebody pastes the browser measurement, which is the only source for anything in this
615
+ section.
616
+
617
+ Half the report reasons about round trips, compression and caching from the folder alone, which is
618
+ reasoning about what was _built_. A `.br` next to a `.js` says the pipeline made one; only
619
+ `encodedBodySize` against `decodedBodySize` says the server sent it. A hashed name says the file _can_
620
+ be cached forever; only a `transferSize` of zero says a returning visitor did not ask again.
621
+
622
+ | What it reads | What it tells you that the folder cannot |
623
+ | ------------------------------------- | ------------------------------------------------------------------------- |
624
+ | `encoded` vs `decoded` body size | JavaScript being served uncompressed. Worth more than any chunk split |
625
+ | `transferSize` of 0, or a few hundred | Served from cache, or a 304 — the premise §3.19 assumed |
626
+ | `connectStart` on the n-th file | The HTTP/1.1 pool running out, observed rather than inferred |
627
+ | `responseStart − requestStart` | A real round trip, better than asking somebody about their latency |
628
+ | `responseStart` of the navigation | The document's own TTFB: round trip zero, which the count starts after |
629
+ | Every request, third parties too | The denominator a count of JavaScript files never had |
630
+ | `serviceWorker.controller` | A worker **controlling** this page, not just present in the folder |
631
+ | `startTime`, sorted | The batches the browser really took, against the ones the graph predicted |
632
+
633
+ That last row needs both halves: the vendors with the waterfall have no module graph, the analysers
634
+ with the graph have no waterfall. Loadline can say "the graph predicted 3 round trips, you measured
635
+ 4" — with the correction made while building it, that a measured batch is **not** a round trip of the
636
+ graph, because a batch also splits when the connection pool runs out. The copy says so and names the
637
+ queueing when there is any.
638
+
639
+ **None of it moves a threshold.** One paste describes one machine, on one connection, on one day. An
640
+ `h3` measured from a laptop on office fibre is a fact about that laptop: a new visitor's first
641
+ connection is usually `h2`, because `Alt-Svc` has to be cached first, and a corporate proxy that drops
642
+ UDP degrades it for a whole company. So the channel is reported with its date and its limits attached,
643
+ it goes stale after thirty days, and it is never written into the committed file.
644
+
645
+ ### 3.21 Where the first load comes from
646
+
647
+ **Fires when** `index.html` names an absolute URL on another host, or the measurement reports one.
648
+
649
+ Before the first byte of the first chunk there is a DNS lookup, a TCP connection and a TLS handshake
650
+ against that host — time no weight figure in this report sees, because the round-trip count starts
651
+ once the connection exists. It has an opposite side, said in the same sentence: under HTTP/1.1 a
652
+ second origin is a second pool of six, so the decision that adds a handshake also removes queueing.
653
+
654
+ Both sources are read because a page written entirely with relative URLs and served from a CDN names
655
+ no other host in its markup; only the addresses the browser reported say where the bytes came from,
656
+ which makes the measured version the stronger of the two.
657
+
658
+ ### 3.22 The five questions
659
+
660
+ **Fires when** somebody answers them, or — for the card listing what is still open — when a signal on
661
+ this report depends on an answer nobody has given.
662
+
663
+ Four claims in this report are grey on purpose: the update cost shows its percentage and withholds its
664
+ colour, the cascade names its topology and refuses to say whether it matters, and the granularity
665
+ signal puts two magnitudes on the table and declines to recommend a direction. The facts that would
666
+ settle them are facts about a team and its users, and no folder on disk contains them.
667
+
668
+ **The arithmetic**: `releases per week × the share arriving with a warm cache` = how many times a week
669
+ one person pays an invalidation. The report shows the multiplication rather than the result, so anyone
670
+ who disagrees can see which of the two numbers they disagree with. It is what turns "87 % of the build
671
+ is re-downloaded" into a cost: 87 % four times a week is the most expensive line in the report; 87 %
672
+ once a quarter to first-time visitors is nothing at all. Same build, same percentage.
673
+
674
+ **The rule, which is half the work**: an answer may **raise** a severity and may never lower one, and
675
+ `unknown` does nothing at all. A test walks all 768 combinations of the five answers against a build
676
+ with an expensive update and asserts that none takes a signal below where nobody having answered
677
+ leaves it, and that none makes a signal disappear. Without that guard, the cheapest way to a clean
678
+ report would be to answer optimistically, and the questionnaire would stop being evidence and become a
679
+ volume knob.
680
+
681
+ **Why the questions are words and the figures optional**: people know "we ship most days"; almost
682
+ nobody knows their releases per week without looking it up. Asking for the figure first produces
683
+ either an empty form or a guess typed with two decimal places, and the guess is worse, because it
684
+ arrives looking like a measurement. So the bands are the question, with three raw controls beside them
685
+ for whoever has the query open in another window; when a figure is there, it wins. Under every question
686
+ is the metric it stands for and where to find it, which is what keeps this from being a personality
687
+ quiz.
688
+
689
+ **Two questions are not like the others.** The fourth — where the audience connects from — is the one
690
+ people answer as they would like it to be, and it says so; ticking "we have RUM" removes it entirely,
691
+ because a p75 measured from real sessions beats a band picked from memory. It is also the only one
692
+ with no raw control of its own: its unit is round-trip time, the report already has exactly one of
693
+ those (`latencyMs`), and a second copy would be two numbers for one fact drifting apart. The fifth
694
+ offers no "I don't know" at all: it is not a fact to look up but which wait the team would rather pay.
695
+ It is also the only place the report names a **direction**, because it is the only place anything
696
+ ranks the two magnitudes.
697
+
698
+ **Only the questions that matter are asked.** The card listing what is still open names only the
699
+ questions some signal on this report depends on. Otherwise it would be five identical lines on every
700
+ report, which is the shape of text people learn to scroll past.
701
+
702
+ **"I don't know" is never drawn as a chosen answer.** `unknown` is the starting value of all five, so
703
+ a form nobody had touched came up with "I don't know" selected on every question, beside a counter
704
+ saying "unanswered". Both could not be true. No line of code downstream tells "nobody looked" from
705
+ "somebody said they do not know" — neither counts as answered, neither moves a colour — so the page
706
+ must not show them differently either. The button stays, as the way to take an answer back.
707
+
708
+ ### 3.23 The breakdown that does not add up to the file
709
+
710
+ **Fires when** the per-file weights inside the chunks and the chunks' own weights disagree by more
711
+ than 5 % **and** by more than a kibibyte per chunk. `mid` from 15 % up, informational below it.
712
+
713
+ Both conditions, because they measure different things. The wrapper a bundler puts round each chunk —
714
+ module boilerplate, banners, the `sourceMappingURL` line — belongs to no input file and is a fixed cost
715
+ per chunk rather than a proportion of one. A plain esbuild build of five chunks weighing 90 to 330
716
+ bytes each comes out at **59 %**, which is 395 bytes of wrapper and nothing else; without the second
717
+ condition that was a `mid` on a build where nothing was wrong. The ratio says whether it matters, the
718
+ bytes say whether it is real.
719
+
720
+ There are two measurements of the same chunk and they are supposed to agree: `bytes` is what the file
721
+ weighs, and the sum of `bytesInOutput` over its inputs is what it is made of. Every figure taken from
722
+ **inside** a chunk — the bootstrap broken down by package, the exclusive column, what a `--what-if`
723
+ would save — is a sum of the second kind, while the headline weight printed next to it is the first.
724
+ When the two disagree, the whole of the first family is wrong by exactly that ratio and nothing else
725
+ in the report shows it.
726
+
727
+ Measured on four builds:
728
+
729
+ | Build | chunk bytes | sum of `bytesInOutput` | ratio |
730
+ | --------------------------------- | ----------- | ---------------------- | ---------- |
731
+ | Angular 17 (probe) | 230 774 | 228 020 | **0.988** |
732
+ | Angular 22 (probe) | 225 684 | 283 571 | **1.256** |
733
+ | Angular 22 (a real application) | 393 504 | 483 159 | **1.228** |
734
+ | Angular 22 (Loadline's own build) | 791 012 | 790 569 | **0.9994** |
735
+
736
+ **The cause is not established, and the signal does not claim one.** The obvious reading — "Angular 22
737
+ writes the metafile before a later pass shrinks the output" — is contradicted by the fourth row, which
738
+ is Angular 22 on the same `@angular/build` 22.1.7 as the second and lands on the file exactly. What
739
+ separates them is not the version: the two that drift are chunks that are almost entirely `@angular/*`
740
+ framework code, and the one that does not is mostly this project's own. Extracted licences were
741
+ checked and are not it — the probe's excess is 57 887 bytes against a 16 954-byte
742
+ `3rdpartylicenses.txt`.
743
+
744
+ What **is** ruled out is esbuild itself. A plain esbuild build — no Angular, 40 modules, one 46 kB
745
+ shared chunk, `metafile: true`, `minify: true` — comes out at **0.9892**, and its biggest chunk at
746
+ **0.9975**: the deficit is the per-chunk wrapper, in the direction the overhead predicts. Whatever
747
+ moves the figure sits between esbuild's metafile and the folder Angular writes, on some of its builds.
748
+
749
+ **Why it is a signal and not a correction.** Scaling the breakdown down by the ratio would make the
750
+ totals reconcile and would be a model: it assumes every file moved by the same proportion, and nothing
751
+ here measures whether it did. There is an exact answer available instead, and the signal's fix is to
752
+ go and get it — build with source maps and drop the folder, and the split is measured on the generated
753
+ file itself. On the same Angular 22 probe, the graph walk over the metafile alone totals 280 153 bytes
754
+ against a 222 555-byte bootstrap (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It
755
+ does not fire on chunks a map covered, because for those there is nothing left to drift.
756
+
757
+ ---
758
+
759
+ ## 4. Traps found while building it
760
+
761
+ ### 4.1 Computed is not measured
762
+
763
+ Loadline walks the graph; the browser measures. They do not match, and in a real case the gap was:
764
+
765
+ ```
766
+ computed from the graph : 2389 kB across 21 files
767
+ measured in the browser : 2534 kB across 66 files
768
+ ```
769
+
770
+ That is not a computation bug. Entering at the root, Angular's router loads the protected zone's chunk
771
+ in order to match the route, and only then does the guard find there is no session and redirect to
772
+ login — the chunk has already downloaded. So **opening the app at `/` costs more than going straight
773
+ to `/login`**. Both numbers are true and they answer different questions. The Measured tab (§3.10)
774
+ contrasts the two chunk by chunk, and what is left over is exactly the chunk the router loaded before
775
+ the guard did its job.
776
+
777
+ ### 4.2 A static server does not know your routes
778
+
779
+ When verifying in the browser, `/login` returns 404 — the server is looking for a file. Enter at the
780
+ root and let the app redirect, or serve with a rewrite:
781
+
782
+ ```bash
783
+ npx http-server dist/<app>/browser -p 8099 --proxy "http://localhost:8099?"
784
+ ```
785
+
786
+ ### 4.3 Analysis tools cache
787
+
788
+ At least one well-known analyser keeps the last report in browser storage and serves stale data
789
+ without saying so. Compare the `main-*.js` name it shows against the one on disk.
790
+
791
+ ### 4.4 Nesting a route changes what guards see
792
+
793
+ Not Loadline's problem, but it is the trap in the fix Loadline recommends. Move a route under a parent
794
+ so you can declare lazily-loaded providers, and a guard that decides like this:
795
+
796
+ ```ts
797
+ const url = (route.routeConfig?.path ?? '').toLowerCase();
798
+ ```
799
+
800
+ …now sees a child with `path: ''`, stops recognising the route as public, and **redirects in a loop,
801
+ with the screen hung and no console error**. The fix: `title` and `canActivate` stay on the parent,
802
+ which keeps its `path`; only `providers` and `loadComponent` move down to the child.
803
+
804
+ ---
805
+
806
+ ## 5. Data format
807
+
808
+ Loadline reads the [esbuild metafile](https://esbuild.github.io/api/#metafile), written by Angular
809
+ with `--stats-json` and by plain esbuild with its metafile option. The keys it uses:
810
+
811
+ | Key | What for |
812
+ | ---------------------------------- | --------------------------------------------------------------------------------- |
813
+ | `outputs[].entryPoint` | Detecting entries and naming screens |
814
+ | `outputs[].imports[].kind` | `import-statement` vs `dynamic-import`: the entire split |
815
+ | `outputs[].bytes` | Raw chunk size |
816
+ | `outputs[].inputs[].bytesInOutput` | Breakdown by package and by folder, and the search |
817
+ | `inputs[].imports[]` | Who imports what: the import chain, §3.2, and which routes file loads each screen |
818
+ | `inputs[].format` | `cjs` marks CommonJS files, for §3.9 |
819
+
820
+ ### The build folder, when there is no metafile
821
+
822
+ Vite, Rollup and Rolldown do not write a metafile, and Vite never compiled for production with esbuild
823
+ — it used Rollup, and since Vite 8 it uses Rolldown. So for everything built on them the graph is read
824
+ from the compiled folder itself (`core/intake/bundle-graph.ts`), which is possible because an ES
825
+ module bundle carries its graph in the code that ships:
826
+
827
+ | What is in the folder | What it gives |
828
+ | ------------------------------ | ------------------------------------------------------ |
829
+ | `import{a}from"./chunk-X.js"` | A static edge: the two files travel together |
830
+ | `import("./chunk-Y.js")` | A lazy edge: the boundary the whole report is built on |
831
+ | The `<script>` of `index.html` | Which chunk the application starts at |
832
+ | `__vitePreload(…, [deps])` | What Vite fetches in parallel with a lazy chunk |
833
+ | `.js.map` | Which source files are inside each chunk, and how much |
834
+
835
+ - **No JavaScript parser.** Specifiers are found with regular expressions and a match is kept only if
836
+ the file it points at exists in the folder, so a false positive points at nothing and drops out.
837
+ - **The page is required.** A bundler writes the shared code of an application into its entry chunk,
838
+ so the entry ends up imported by its own children: there is no "chunk nobody imports" to find. Only
839
+ `index.html` can name it. It does so in one of two ways — a `<script src>`, or an `import()` inside
840
+ an inline script, which is how SvelteKit starts its application.
841
+ - **A folder of webpack or Turbopack chunks is refused.** Those builds have entry chunks and no graph:
842
+ their imports are numbers the loader resolves at run time. Read as ES modules, a Next.js export came
843
+ out as one bootstrap of seven files, zero screens and "nothing stands out" — confident, detailed and
844
+ false. A folder whose entry carries that runtime **and** where nothing imports anything lazily is
845
+ named for what it is. Both halves are needed: the marker alone would refuse an ES bundle carrying
846
+ one webpack-built dependency, and no lazy edges alone is an ordinary application with every route
847
+ eager.
848
+ - **Without `.js.map` the report loses the inside of each chunk**, and nothing else.
849
+
850
+ The preload lists are the one place a bundler's own behaviour changes a figure. Vite does not wait for
851
+ a lazy chunk to arrive and be parsed before fetching what it imports — it bakes the list into the call
852
+ and asks for the whole set at once. Angular does not. Without reading those lists, every screen of a
853
+ Vite application would be counted one round trip deeper than it is.
854
+
855
+ ### What is not a metafile
856
+
857
+ Three files are commonly believed to be "the stats of my build". "Could not read it" would be a lie
858
+ about all three: the file is fine, it is another format, and Loadline says which.
859
+
860
+ | What | Where it comes from | Why it is not read |
861
+ | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
862
+ | webpack `stats.json` | Angular's `browser` builder (up to v16), Next.js, Rspack | Different shape: `chunks`/`modules`/`assets` arrays |
863
+ | Vite `manifest.json` | `build.manifest: true` | Not needed: the folder itself says the same thing, and better |
864
+ | `rollup-plugin-visualizer` | its `--json` output | A drawn tree, not the build's own record |
865
+
866
+ The Vite manifest was the obvious thing to read and it aged badly in a few months: with Rolldown as
867
+ the default it is a compatibility layer somebody has to switch on, while the folder is always there
868
+ and needs nobody to maintain a format.
869
+
870
+ ### Two build shapes that are not a plain SPA
871
+
872
+ Both were analysed wrongly at first, and both are becoming more common (`core/analysis/entries.ts`).
873
+
874
+ **Server-side rendering writes one metafile with both sides in it.** Nobody downloads the server
875
+ bundle and it is usually the bigger of the two, so "the entry that reaches the most" would pick it and
876
+ the whole report would be about code no browser asks for. Everything under `server/` is left out —
877
+ unless there is nothing else, which is somebody analysing their server bundle on purpose — and the
878
+ report says how many outputs that was.
879
+
880
+ **A deferred block looks exactly like a route from the outside.** An Angular `@defer` or a `lazy()`
881
+ inside a component produces a lazy entry with an `entryPoint` of your own code, same as a route's. It
882
+ is not a screen: nobody enters it, it loads when its trigger fires inside the screen holding it, and
883
+ counting it as one inflates the screen count and drags the median down. The evidence has to be
884
+ positive: it is a block only when **every** file that lazily imports it is a view (`*.component.*`,
885
+ `*.page.*`, `*.view.*`, `*.container.*`) or is itself one of these lazy entries. A route file, a
886
+ service, an unknown importer: it stays a screen.
887
+
888
+ **A file that only groups routes is not a screen either.** What it holds is a list of
889
+ somewhere-elses. This is measured rather than read off the file name: it is a grouping file when it
890
+ adds under a kibibyte of its own to its chunk, holds **more than one** dynamic import and nothing
891
+ else, and produces a chunk nothing travels with. `*.routes.ts` still passes on the name alone, for the
892
+ routes file that imports a guard, but nothing depends on that name any more.
893
+
894
+ ⚠️ **"More than one" is the condition a real build had to teach.** A Nuxt page that defers a single
895
+ widget matched every other criterion — small, no static imports, a chunk of its own — so the home
896
+ screen left the table and the widget took its row. With a single dynamic import there is nothing left
897
+ that tells a grouping file from a small screen deferring a piece of itself, and losing a screen is the
898
+ expensive direction to be wrong in.
899
+
900
+ Both lists sit under the screens table, so leaving an entry out is visible rather than silent. Every
901
+ line carries a **count as a screen** button, as every row of the table carries a **not a screen** one:
902
+ telling a screen from a piece of one is partly done by reading file names, and no set of names fits
903
+ every project. A reclassified entry is remembered with the session.
904
+
905
+ ### The other files, all optional
906
+
907
+ | File | What is read |
908
+ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
909
+ | `browser/` folder | Every `.js` and `.css` is gzipped with `CompressionStream` for real figures |
910
+ | `.js.br` / `.css.br` in that folder | Their size on disk **is** the brotli figure: read, never decompressed |
911
+ | `.js.map` in that folder | A second measurement of what each file weighs inside each chunk |
912
+ | `index.html` in that folder | Which chunks the page announces, for the round trips of the first load (§2.9) |
913
+ | Previous `stats.json` or a Loadline export | Baseline: bootstrap, its packages, the cost per screen, the signals raised and every file name with what it weighs and what it is mostly made of |
914
+ | Previous build folder | Compressed baseline: its `stats.json` analysed with its `.js` files compressed here |
915
+ | `loadline.json` | Thresholds, gates, accepted signals and the five answers |
916
+ | `angular.json` | `budgets` in `options` and in each configuration, `defaultConfiguration`, `polyfills` |
917
+ | `package.json` | `scripts` (to follow the pipeline's commands), `zone.js` and `@angular/core` |
918
+ | `.gitlab-ci.yml` / GitHub workflow | Commands containing `ng build` or a build script, with the job they live in |
919
+
920
+ The page's "Export analysis" button and the command's `--export` write the same file. That matters
921
+ more than it sounds: a `stats.json` is the only baseline a build can produce on its own, and Vite,
922
+ Rollup, SvelteKit, Nuxt, Astro and Solid do not write one — so before `--export` the only way to get a
923
+ baseline for any of them was to open a browser and press a button, which a pipeline cannot do.
924
+
925
+ The pipeline file is read without a YAML parser, line by line, which is why every command found is
926
+ shown in the Project tab with what it resolves to: if the heuristic gets it wrong, it shows.
927
+
928
+ ### How `loadline.json` is allowed to grow
929
+
930
+ The file is `version: 1`, and the rule is that **every addition is an optional block and the version
931
+ stays at 1**. Bumping it buys nothing when everything entering is optional — a file written last month
932
+ is still valid word for word, and a bump would make the command carry two readers to express that
933
+ nothing broke. The line is where an old file would stop being valid: that is a new version.
934
+
935
+ One thing deliberately never goes in it: **anything measured from a browser**. Those facts have a date
936
+ and a machine attached and they go stale, and a stale figure committed to a repository is a false fact
937
+ with the shape of a measurement. The five answers are the opposite case and do go in — properties of a
938
+ team, the same for everybody who runs the command, and the kind of thing that should be argued about
939
+ in a review rather than retyped by each person who opens the report. They expire after a year, and the
940
+ report says so when they have.
941
+
942
+ An answer nobody recognises becomes "unanswered" plus a line to print, the same as an acceptance with
943
+ no reason: an answer is the only thing in this file that can move a colour, so it is the one mistake
944
+ that would otherwise change a verdict silently.
945
+
946
+ ---
947
+
948
+ ## 6. Design decisions
949
+
950
+ **One HTML file, no dependencies.** Opened by double-clicking. Nothing to install, update or maintain,
951
+ and it will still work in ten years.
952
+
953
+ **Everything in the browser.** A private app's `stats.json` reveals its routes, its dependencies and
954
+ its internal structure. It has no business leaving your machine.
955
+
956
+ **The last measurement is remembered, locally.** Loading anything stores it in the browser's IndexedDB
957
+ — the raw `stats.json`, the compressed sizes, the baseline and the context — and the next visit offers
958
+ to restore or forget it. Same privacy rule, now with memory.
959
+
960
+ **The bar's three segments are the message.** Colour is not decoration: slate is the unavoidable
961
+ baseline, burnt orange is what everyone pays, teal is this screen's own. On a shared scale, the
962
+ alignment of the orange block tells the story without a single number.
963
+
964
+ **Signals come with their fix**, including warnings about what **not** to do. Data with no "so what"
965
+ is useless.
966
+
967
+ **Three kinds of fact, never mixed in one sentence.** Something is **derived** from the build (exact
968
+ about what was built, silent about what is served), **measured** by a browser (one machine, one
969
+ connection, one day), or **declared** by somebody (worth more than a guess and less than a
970
+ measurement). The fourth state is **unknown**, and it is the one that matters: a report that quietly
971
+ turns "nobody looked" into "we assumed the median" cannot be checked, so `unknown` has a word of its
972
+ own and never a value.
973
+
974
+ **Evidence may raise a severity and only evidence may lower one.** The failure mode of the symmetric
975
+ version is that an optimistic answer produces silence exactly where the honest answer is noise, and
976
+ silence is the one output nobody checks. A test over every combination of the five answers keeps it
977
+ that way (§3.22).
978
+
979
+ **The report never filters.** Context reorders, re-thresholds and rewords; no finding is ever hidden.
980
+ A signal the page hides is a signal nobody can look at, and the page is where somebody goes **to**
981
+ look. Accepting a signal is a decision for the pipeline, and it is printed under the report either
982
+ way.
983
+
984
+ **The size budget is on one file.** Because the tool is one self-contained HTML, a lazy chunk would
985
+ either break the double-click property or be inlined back into the same file, moving the number
986
+ without moving a byte. So the budget in `angular.json` is an alarm on the whole thing. Loadline
987
+ pointed at its own build says where the weight is: the signal copy in two languages, and two woff2
988
+ fonts as data URIs so the page never reaches the network. Both are properties this project chose, and
989
+ the lever that would shrink it — shipping one language per build — costs the language toggle.
990
+
991
+ ### How the source is laid out
992
+
993
+ ```
994
+ src/app/core/ the analysis itself: no Angular anywhere in it, and where the tests are
995
+ src/app/state/ the Angular services holding what is loaded and what derives from it
996
+ src/app/shared/ pieces used by more than one screen: the bytes pipe, the trees, the tag
997
+ src/app/features/ what you look at: the drop zone, the report and its nine panels
998
+ ```
999
+
1000
+ **`core/` never imports Angular.** That is what lets the whole analysis be tested by calling a function
1001
+ with an object, without a browser or an injector. Everything that computes something carries its own
1002
+ `.spec.ts`; what is left is data, type declarations and the browser storage the last session is kept
1003
+ in.
1004
+
1005
+ **A panel holds its own state, never another panel's.** What two panels have to agree on — which tab
1006
+ is open, which row to reveal — goes through `ReportNav`, and everything derived from the loaded files
1007
+ hangs from `ReportStore` as a computed. That is why switching language does not walk the dependency
1008
+ graph again: the analysis does not depend on the language, and the signals do.
1009
+
1010
+ **Text lives apart from the code that decides.** `core/i18n/` holds the interface both languages fill
1011
+ (`ui-strings.ts`) and one file per language; `core/findings/` separates when a signal fires
1012
+ (`findings.ts`) from what it says (`finding-text.ts`). Rewording a signal touches no rule.
1013
+
1014
+ **Shapes live apart from the code that fills them.** A type another file imports goes in a `.types.ts`
1015
+ next to its module: `analysis.ts` computes, `analysis.types.ts` says what comes out. The point is the
1016
+ reading order — a module opens on its first function instead of two hundred lines of declarations.
1017
+ Types that never leave their file stay in it, and so does the input contract of a component.
1018
+
1019
+ **Three path aliases, one per layer**, declared in `tsconfig.json`: `@core/*`, `@shared/*` and
1020
+ `@state/*`, for imports that would otherwise climb. Siblings and one level up stay relative.
1021
+ `features/` has no alias on purpose: inside a screen everything is a sibling, and an alias there would
1022
+ invite one panel to import another.
1023
+
1024
+ ---
1025
+
1026
+ ## 7. What the other tools do
1027
+
1028
+ Checked on 2026-09-01 against each tool's documentation. Loadline does not replace these: it answers a
1029
+ question none of them answers, and leaves out things several of them do well.
1030
+
1031
+ | Tool | Input | What it adds | What it lacks compared to Loadline |
1032
+ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
1033
+ | [esbuild Bundle Size Analyzer](https://esbuild.github.io/analyze/) (official) | metafile | Treemap of what each chunk weighs and which files it contains. Nothing to install. | Nothing per screen. Doesn't know how many screens load a chunk. No real gzip, no comparison, no budgets. |
1034
+ | [Hawkeye](https://angularexperts.io/blog/hawkeye-esbuild-analyzer/) (Angular Experts) | `stats.json` | Separates eager from lazy, searches a library and says whether it lands in the eager or lazy part. | Still "what is in each chunk". No per-screen figure, no screens-per-chunk count, no gzip, comparison or budgets. |
1035
+ | [Sonda](https://sonda.dev/frameworks/angular-cli) | `stats.json` + source maps | Treemap and dependency tree, gzip **and brotli**, JSON report for CI. Measures on the final minified file. | Requires source maps and a command. No per-screen weight, no "lazy that is really common". No build comparison. |
1036
+ | [source-map-explorer](https://www.npmjs.com/package/source-map-explorer) | source maps | Exact bytes of each source file inside the final file. | Only that: a treemap per output file. |
1037
+ | [@rnx-kit/esbuild-bundle-analyzer](https://www.npmjs.com/package/@rnx-kit/esbuild-bundle-analyzer) | metafile | Duplicates **with the import chain** each copy enters through. **Compares two metafiles.** | Terminal only, uncompressed figures, nothing per screen. |
1038
+ | [exoego/esbuild-bundle-analyzer](https://github.com/exoego/esbuild-bundle-analyzer), [build-size-diff](https://github.com/q1sh101/build-size-diff) | metafile / output folder, in CI | GitHub Action: comments on the PR how much each output file changed against the base branch. | They compare files, not screens. They don't say "this screen grew because a shared chunk grew". |
1039
+ | [Statoscope](https://github.com/statoscope/statoscope) | webpack stats | The only one with "download size per entry point" and validation rules between two builds. | Webpack only. Angular 17+ uses esbuild; [the support request](https://github.com/statoscope/statoscope/issues/148) is still open. |
1040
+ | [Bundle Buddy](https://github.com/Timer/bundle-buddy) | source maps | Source code repeated across chunks, at line level. | Only that. |
1041
+ | [bundle-stats](https://github.com/relative-ci/bundle-stats) | webpack, rspack, vite, rollup | Per-build report with history and comparison. | Doesn't read esbuild metafiles or Angular CLI. |
1042
+ | Angular CLI (`ng build`) | — | Table of initial and lazy chunks; enforces the `budgets` in `angular.json`. | No per-screen total. The budget only applies in the configuration being built; nobody checks whether the pipeline builds that one. |
1043
+
1044
+ ### 7.1 What Loadline does that none of them does
1045
+
1046
+ - The per-screen figure (bootstrap + shared + own), by walking the import graph from each lazy route.
1047
+ - Counting how many screens load each "lazy" chunk. The problem is documented — esbuild produces many
1048
+ shared chunks, and the Angular team has an
1049
+ [experimental chunk optimizer](https://push-based.io/article/faster-builds-slower-applications-optimizing-angulars-bundle-output)
1050
+ — but no tool diagnoses it per screen.
1051
+ - Cross-checking the `angular.json` budgets against which configuration the pipeline builds.
1052
+ - Real gzip measured in the browser, without source maps and without installing anything.
1053
+ - Searching a name and seeing, besides where it lands, **which screens pay for it**.
1054
+
1055
+ ### 7.2 What they do that Loadline does not
1056
+
1057
+ - **Post the comment on the PR.** The command writes it (`--format pr-comment`) and exits non-zero
1058
+ when a limit breaks, but some job of yours has to post it. The GitHub Actions and Statoscope do that
1059
+ last step themselves.
1060
+ - **Line-level duplication across chunks** (Bundle Buddy). Loadline works at file and package level.
1061
+ Not started on purpose: comparing everything with everything is expensive inside the browser, and
1062
+ the typical finding — a copied utility — usually weighs little.
1063
+ - **Webpack** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads an esbuild metafile
1064
+ or a folder of ES modules, and webpack is neither: it resolves imports at run time through
1065
+ `__webpack_require__`, so there is nothing in the shipped file to read. That leaves out Angular 16
1066
+ and earlier, Next.js and Create React App.
1067
+
1068
+ ### 7.3 One finding worth keeping
1069
+
1070
+ Reading source maps was added to close the gap against Sonda and source-map-explorer, and the result
1071
+ changed the reason for doing it. The premise was that the metafile measures **before** minification,
1072
+ which is true of webpack stats — what those tools were written for — and **not** of the esbuild
1073
+ metafile: measured on a real build of Loadline, the sum of `bytesInOutput` was 99.9 % of the generated
1074
+ file, while the source bytes of those same files added up to 6.2 times that size. The split was
1075
+ already sound, and the "approximate" label was unwarranted.
1076
+
1077
+ That measurement has since expired on some builds, and the maps being an independent second
1078
+ measurement is what caught it (§3.23). One detail came out of it as well: the maps attribute a
1079
+ component's template to its `.html`, while the metafile counts it inside the `.ts`. Without folding one
1080
+ into the other, a component with a big template came out at 58 % of its real weight.
1081
+
1082
+ ### 7.4 Caveats
1083
+
1084
+ - What is said about Hawkeye comes from its authors' article; its GitHub README could not be read
1085
+ during the check. A recent version adding per-route weight would not show here.
1086
+ - Comparing two builds and detecting duplicates exist elsewhere (rnx-kit, GitHub Actions). What
1087
+ Loadline adds there is doing it per screen and without leaving the browser.