@paulirish/trace_engine 0.0.67-beta.0 → 0.0.67-beta.1
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.
- package/README.md +60 -22
- package/index.d.ts +2 -0
- package/locales/en-US.json +1055 -0
- package/models/trace/trace.js +21 -4
- package/package.json +10 -3
- package/models/trace/lantern/lantern.js +0 -8
- package/models/trace/types/Timing.js +0 -8
- package/models/trace/types/TraceEvents.js +0 -189
- package/models/trace/types/types.js +0 -8
package/README.md
CHANGED
|
@@ -8,46 +8,84 @@ But the breakages should be obvious exceptions or type failures.
|
|
|
8
8
|
## API quickstart
|
|
9
9
|
|
|
10
10
|
```js
|
|
11
|
-
import * as
|
|
11
|
+
import * as Trace from '@paulirish/trace_engine';
|
|
12
12
|
|
|
13
|
-
const
|
|
13
|
+
const model = Trace.TraceModel.Model.createWithAllHandlers();
|
|
14
|
+
await model.parse(traceEvents);
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
console.log(
|
|
16
|
+
const parsedTrace = model.parsedTrace();
|
|
17
|
+
console.log(parsedTrace.data); // Handlers data (Meta, Screenshots, LayoutShifts, etc.)
|
|
18
|
+
console.log(parsedTrace.insights); // Insight models
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
See the included `analyze-trace.mjs` for a runnable
|
|
21
|
+
See the included `analyze-trace.mjs` for a runnable CLI script.
|
|
20
22
|
|
|
21
|
-
###
|
|
23
|
+
### Imports & TypeScript Types
|
|
22
24
|
|
|
23
|
-
All
|
|
25
|
+
All runtime values and types are imported directly from the root package entrypoint (`@paulirish/trace_engine`):
|
|
24
26
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
```js
|
|
28
|
+
import * as TraceEngine from '@paulirish/trace_engine';
|
|
29
|
+
// Or via named imports:
|
|
30
|
+
import {Types, Lantern, Insights, Processor, Handlers, Helpers, Extras} from '@paulirish/trace_engine';
|
|
31
|
+
|
|
32
|
+
// Enums & Event Types
|
|
33
|
+
const {Phase, Name} = Types.Events;
|
|
34
|
+
const {Milli, Micro} = Types.Timing;
|
|
35
|
+
|
|
36
|
+
// Lantern
|
|
37
|
+
const {Graph, Simulation} = Lantern;
|
|
38
|
+
|
|
39
|
+
// Insights
|
|
40
|
+
const {UIStrings} = Insights.Models.ImageDelivery;
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
TypeScript declarations (`.d.ts`) mirror DevTools' own types through the root namespace:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import type {Types, Insights, Lantern} from '@paulirish/trace_engine';
|
|
47
|
+
|
|
48
|
+
type TraceEvent = Types.Events.Event;
|
|
49
|
+
type SyntheticNetworkRequest = Types.Events.SyntheticNetworkRequest;
|
|
50
|
+
type InsightSet = Insights.Types.InsightSet;
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
#### Migrating from Legacy Deep Subpaths
|
|
54
|
+
|
|
55
|
+
Older versions of `@paulirish/trace_engine` exposed individual files inside `models/trace/...`. These deep paths are deprecated in favor of the canonical root exports:
|
|
56
|
+
|
|
57
|
+
| Old Deep Path | Canonical Import (`@paulirish/trace_engine`) |
|
|
58
|
+
| :--- | :--- |
|
|
59
|
+
| `.../models/trace/lantern/lantern.js` | `import { Lantern } from '@paulirish/trace_engine';` |
|
|
60
|
+
| `.../models/trace/types/types.js` | `import { Types } from '@paulirish/trace_engine';` |
|
|
61
|
+
| `.../models/trace/types/TraceEvents.js` | `import { Types } from '@paulirish/trace_engine'; const { Events } = Types;` |
|
|
62
|
+
| `.../models/trace/types/Timing.js` | `import { Types } from '@paulirish/trace_engine'; const { Timing } = Types;` |
|
|
63
|
+
| `.../models/trace/insights/<Insight>.js` | `import { Insights } from '@paulirish/trace_engine'; const { UIStrings } = Insights.Models.<Insight>;` |
|
|
64
|
+
| `.../models/trace/extras/ThirdParties.js` | `import { Extras } from '@paulirish/trace_engine'; const { ThirdParties } = Extras;` |
|
|
27
65
|
|
|
28
66
|
## Maintainer cheatsheet
|
|
29
67
|
|
|
30
|
-
`@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits
|
|
68
|
+
`@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits matching `.d.ts` declarations and locales from `devtools-frontend` (using the commit SHA recorded in `chrome-devtools-mcp/build/src/third_party/bundled-packages.json`).
|
|
31
69
|
|
|
32
|
-
- `
|
|
33
|
-
- Exported `const enum`s under `models/trace` (such as `Types.Events.
|
|
34
|
-
-
|
|
70
|
+
- `models/trace/trace.js` is a static runtime wrapper that initializes `DevToolsLocale` ('en-US') and intercepts `LocalizedStringSet.prototype.getLocalizedString` so calls from `models/trace/` return `{i18nId, values, formattedDefault}` for Lighthouse's multi-locale pipeline.
|
|
71
|
+
- Exported `const enum`s under `models/trace` (such as `Types.Events.Phase`, `Handlers.Threads.ThreadType`, etc.) are materialized at runtime in `models/trace/trace.js` until [CL 8539952](https://chromium-review.git.corp.google.com/c/devtools/devtools-frontend/+/8539952) lands upstream in `devtools-frontend`.
|
|
72
|
+
- `scripts/build.ts` extracts `front_end/` via `git archive` from the local `devtools-frontend` checkout at the exact SHA and runs `tsc --emitDeclarationOnly` in ~2 seconds.
|
|
35
73
|
|
|
36
74
|
```sh
|
|
37
75
|
cd $HOME/code/trace_engine
|
|
38
76
|
|
|
39
|
-
# Update chrome-devtools-mcp to latest
|
|
40
|
-
npm i chrome-devtools-mcp@latest
|
|
77
|
+
# 1. Update chrome-devtools-mcp to latest (exact version)
|
|
78
|
+
npm i chrome-devtools-mcp@latest --save-exact
|
|
79
|
+
|
|
80
|
+
# 2. Re-emit .d.ts declarations and locales (~2s)
|
|
41
81
|
npm run build
|
|
42
|
-
npm test
|
|
43
82
|
|
|
44
|
-
#
|
|
45
|
-
npm
|
|
46
|
-
npm publish --access public --dry-run
|
|
83
|
+
# 3. Run test suite and type check
|
|
84
|
+
npm test
|
|
47
85
|
|
|
48
|
-
#
|
|
49
|
-
npm
|
|
50
|
-
npm publish --
|
|
86
|
+
# 4. Bump version and publish (use --tag beta for testing)
|
|
87
|
+
npm version prerelease --preid=beta # e.g. 0.0.67-beta.0
|
|
88
|
+
npm publish --tag beta
|
|
51
89
|
```
|
|
52
90
|
|
|
53
91
|
## High level architecture
|
package/index.d.ts
ADDED