1# CEF accelerated first-presentation startup trace
2
3Dumber records this cold-start timeline **only for the accelerated CEF → DMABUF
4→ GTK path**. It is not a backend-neutral startup metric: the WebKit backend
5does not add milestones to this trace and never emits this CEF summary.
6
7For a selected CEF GUI process, Dumber captures neutral `process_entry` and
8`config_complete` timestamps, then activates and seeds this CEF-owned trace only
9after configuration selects CEF. CEF helper processes, WebKit GUI startup, the
10standalone omnibox, and CLI commands never initialize this trace, record its
11milestones, or emit its summary. A selected CEF GUI trace accepts these one-shot
12milestones only in order:
13
141. `process_entry`
152. `config_complete`
163. `cef_library_load_begin` (immediately before `InitWithApp`)
174. `cef_initialized`
185. `browser_create_requested`
196. `first_accelerated_paint_received`
207. `first_dmabuf_texture_swap` (after `GtkPicture.SetPaintable` succeeds)
218. `first_gtk_presentation` (the subsequent GTK frame-clock after-paint)
22
23The CEF-to-GTK bridge owns the native accelerated-paint, DMABUF texture-swap,
24and GTK presentation boundaries. Dumber records the bridge's ordered callbacks;
25it does not synthesize them for another engine or rendering path. CEF
26library-load completion is intentionally not recorded: `InitWithApp` is an
27opaque operation. Duplicate, unknown, and out-of-order transitions are
28rejected. At the last milestone Dumber emits exactly one normal-level JSON
29summary (`startup_trace: first presentation`) with the selected CEF render
30backend, an `incomplete_reason`, total milliseconds, and monotonic milestones.
31
32A non-DMABUF CEF backend or a missing accelerated callback does not produce a
33complete summary and is not comparable with this measurement. In particular,
34WebKit startup must be measured with a separately defined WebKit-specific
35contract rather than this CEF trace.
36
37## Reproducible collection
38
39Build the candidate and its build manifest, then run:
40
41```bash
42DUMBER_CEF_DIR=/path/to/selected-cef-runtime \
43DUMBER_FIRST_PRESENTATION_BIN="$PWD/dist/dumber" \
44DUMBER_BUILD_MANIFEST="$PWD/dist/dumber.manifest.json" \
45DUMBER_MACHINE_GPU_PROFILE=integrated-gpu \
46  scripts/collect_first_presentation.sh
47```
48
49The manifest records the measured binary SHA-256, the 40-character source
50revision, and the selected `github.com/bnema/purego-cef2gtk` version plus its
51full 40-character revision. Generate it at build time from the same tree
52that produced the binary; collection verifies the manifest against
53`go version -m` output for the measured binary and fails closed on missing
54or mismatched attribution.
55
56```bash
57make build-manifest
58# or, equivalently:
59python3 scripts/generate_build_manifest.py --binary dist/dumber
60```
61
62Manifest schema (JSON, sorted keys):
63
64```json
65{
66  "binary_sha256": "<hex sha256 of the measured binary>",
67  "source_revision": "<40-hex git revision of the built source>",
68  "modules": {
69    "github.com/bnema/purego-cef2gtk": {
70      "version": "<exact version from go version -m>",
71      "revision": "<40-hex git hash from go mod download origin>"
72    }
73  }
74}
75```
76
77The generator refuses binaries built with a `replace` directive, non-tag
78dependency versions, and missing source revisions. The default manifest
79path is `<binary>.manifest.json`, which is also the collector default
80(`DUMBER_BUILD_MANIFEST` overrides it).
81
82The collector is for the accelerated CEF/DMABUF/GTK contract above. By default
83each collection is a fresh directory below
84`$XDG_STATE_HOME/dumber/roadmap-evidence` (or
85`$HOME/.local/state/dumber/roadmap-evidence` when `XDG_STATE_HOME` is unset),
86not in the repository. `DUMBER_FIRST_PRESENTATION_OUTPUT` may override it only
87with a new absolute directory below an existing non-symlink parent. The
88collector never clears or reuses a caller-supplied path.
89
90The script requires the current display and an explicit `DUMBER_CEF_DIR`
91selecting the measured runtime; there is no default path or version.
92`scripts/cef_runtime_probe.py` runs in a separate bounded subprocess, opens
93only the selected `libcef.so` with standard-library ctypes, calls the
94header-verified `cef_version_info(int)` entries (0-7), and reports numeric
95version fields plus the library hash, never its path. The candidate must still
96pass its normal loader ABI/version validation; the probe never bypasses it.
97Runtimes below Chrome major 150 fail collection. It performs
98exactly five bounded launches with fresh XDG homes and CEF root cache, fixes the
99DMABUF/Vulkan renderer, and writes exactly `metadata.json`, `run-01.json`
100through `run-05.json`, and `baseline.json`. Metadata includes only coarse,
101comparison-safe OS/architecture, display protocol, and machine/GPU profile
102labels. Set `DUMBER_MACHINE_GPU_PROFILE` to one of `generic-gpu`,
103`integrated-gpu`, `discrete-gpu`, `hybrid-gpu`, `virtual-gpu`, or `unknown-gpu`;
104do not use a device model or other identifier. Publish only the seven reviewed
105JSON files to an external Gist. Raw logs and temporary XDG homes are removed and
106must not be published. `metadata.json` binds the measured binary SHA-256 to
107its source revision via `go version -m` plus the build manifest, and records
108the selected `github.com/bnema/purego-cef2gtk` version, tag, and full revision
109from that same binary-bound evidence; it never derives provenance from the
110collection checkout. The child processes receive exactly the selected runtime
111via `CEF_DIR`, never a conflicting inherited override. Branch selectors,
112replacement contamination, version/manifest mismatches, or a missing manifest
113fail collection. A missing or incomplete timeline, non-DMABUF backend, or invalid
114run also fails collection.