FrameMetrics Type
Feature 108/109/110/111 (US1, FR-001/002): the per-frame structured work/timing signal the host loop and the deterministic `Perf.runScript` driver both produce. The count/bool fields are the byte-stable determinism surface (FR-007/SC-005); `FrameDuration` is reported for real perf observation but EXCLUDED from golden assertions (it varies run to run, FR-012). Feature 109 replaced the conflating `ViewRebuilt` with the two precise booleans `ProductModelChanged` + `ViewCalled` and added the integer `FullRenderCount`. Feature 110 added `FullRenderFallbackCount` and narrowed `FullRenderCount`/`ViewCalled` so retained routing increments NEITHER. Feature 111 added `FrameCause` + the per-phase booleans `DiffRan`/`LayoutRan`/`PaintRan` (the VIEW phase is `ViewCalled`) and narrowed `ViewCalled`/`FullRenderCount` to `false`/`0` on a model-unchanged frame (the scheduler reuses the already-produced view tree, FR-003/FR-011).
Record fields
| Record Field |
Description
|
|
Feature 120 (US1, FR-001/FR-002): flush + buffer-swap present/compose time. Live diagnostic only; non-golden; `TimeSpan.Zero` on the deterministic path.
|
Full Usage:
DiffRan
Field type: bool
|
Feature 111 (FR-002): the DIFF/reconcile phase ran — a newly-produced view tree was reconciled against the retained tree this frame (the retained step ran on a fresh `host.View`). An animation-only tick re-samples the overlay WITHOUT producing a new tree, so it reports `false`.
|
Full Usage:
DirtyArea
Field type: int
|
Feature 116 (Phase 7, FR-001/FR-004, US1); Feature 120 (FR-015) corrected the computation: the integer area of the **union** of distinct damage rectangles this frame (no longer the sum of their areas), so overlapping damage is counted once and the value never exceeds the frame area. A localized change covers only the changed box(es) (`< FrameArea`); a theme switch covers the frame; an idle frame reports `0`. Deterministic integer, golden-asserted via `Perf.runScript`.
|
Full Usage:
DirtyRectCount
Field type: int
|
Feature 116 (Phase 7, FR-001/FR-004, US1): the number of DISTINCT axis-aligned damage rectangles this frame — one per repainted node's evaluated box, identical boxes deduplicated (`None` boxes contribute none), so `<= RepaintedNodeCount`. `0` on an idle frame. Deterministic integer, golden-asserted via `Perf.runScript`.
|
|
Feature 111 (FR-001): the trigger that caused this frame (idle / pointer-move / pointer-discrete / key / tick / resize / theme). Deterministic, golden-asserted. Names the trigger, not the effect — a key that changes the model is `FrameCause.Key` with `ProductModelChanged = true`.
|
|
Wall-clock duration of the frame's work — reported, EXCLUDED from the golden/determinism surface (FR-012).
|
Full Usage:
FullRenderCount
Field type: int
|
Number of full `host.View` + `Control.renderTree` materializations this frame performed — the retained-step render where it occurs, plus any oracle fallback render. Feature 110 narrowed this: routing a pointer event via the retained path increments NEITHER this nor `ViewCalled` (the per-sample routing full render is removed from the hot path, FR-008); a model-driven re-render after a dispatched message still counts.
|
Full Usage:
FullRenderFallbackCount
Field type: int
|
Feature 110 (FR-009): how many times retained pointer routing fell back to a full render to route an event this frame. `0` for every normal scripted pointer scenario (SC-005); non-zero only when the retained frame could not resolve a bindable hit and the preserved full-render oracle had to run (a counted correctness escape hatch, never the normal path). Deterministic, golden-asserted.
|
Full Usage:
LayoutInvalidatedNodeCount
Field type: int
|
Feature 117 (Phase 8, FR-006, US2): the size of the layout dirty set fed into incremental layout this frame (the patch-derived self-dirty nodes BEFORE fixed-size-ancestor propagation). Distinct from `RemeasuredNodeCount` (the POST-pinning set actually re-measured); because propagation expands each dirty node to its first fixed-size ancestor's whole subtree, `LayoutInvalidatedNodeCount <= RemeasuredNodeCount`. `0` on an idle / style-only / visual-state-only frame; bounded and explainable on a geometry frame. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
LayoutRan
Field type: bool
|
Feature 111 (FR-002): the LAYOUT phase ran — at least one node was re-measured this frame (equivalent to `RemeasuredNodeCount > 0`, but set explicitly as part of the phase record).
|
Full Usage:
MemoHitCount
Field type: int
|
Feature 113 (Phase 5, FR-009/FR-010): memoized-projection HITS while building this frame — a memoizable control (the DataGrid row/column projection) whose declared dependency was unchanged and whose previously-lowered subtree was reused without recomputing. `0` on an idle frame or any frame that evaluates no memoizable control. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
MemoMissCount
Field type: int
|
Feature 113 (Phase 5, FR-009/FR-010): memoized-projection MISSES while building this frame — a memoizable control whose dependency changed, or a cold first evaluation, so the projection was recomputed and stored. `0` on an idle frame or any frame that evaluates no memoizable control. Deterministic, golden-asserted via `Perf.runScript`.
|
|
Feature 120 (US1, FR-001/FR-002): scene→canvas paint-walk time. Live diagnostic only — EXCLUDED from count goldens (mirrors `FrameDuration`); `TimeSpan.Zero` on the deterministic `Perf.runScript` path so adding it leaves every golden byte-identical (SC-001).
|
Full Usage:
PaintRan
Field type: bool
|
Feature 111 (FR-002): the PAINT phase ran — the painted scene (a model render) or the animation overlay was (re)assembled this frame. `true` on model frames AND animation-only ticks; `false` on idle and pure routing frames. (Hit-test is intentionally NOT a phase field — clarified 2026-06-12: the deterministic path does not hit-test coalesced moves; routing work stays in `PointerSamplesReceived`/`PointerMovesProcessed`/`FullRenderFallbackCount`.)
|
Full Usage:
PictureCacheEntryCount
Field type: int
|
Feature 116 (Phase 7, FR-009, US3): the live bounded-LRU picture-cache entry count after this frame — `<= PictureCacheCap` at all times, even under eviction pressure (more distinct cacheable pictures than the cap). A steady cache may retain entries across an idle frame, so this reflects live size, not necessarily `0`. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
PictureCacheHitCount
Field type: int
|
Feature 116 (Phase 7, FR-005/FR-007, US2): picture-cache HITS this frame — cacheable boundaries (a `data-grid-row` identity) whose full correctness key was unchanged and whose cached picture was still resident, reused without recomputing. `0` on a frame with no cacheable picture or under the always-miss oracle. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
PictureCacheMissCount
Field type: int
|
Feature 116 (Phase 7, FR-006/FR-010, US2/US3): picture-cache MISSES this frame — a cacheable boundary recomputed because its correctness key changed, the identity was cold, or its entry had been evicted. `0` on a frame with no cacheable picture. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
PointerMovesProcessed
Field type: int
|
Pointer MOVES actually applied after coalescing — at most one per frame (FR-009/SC-002).
|
Full Usage:
PointerSamplesReceived
Field type: int
|
Raw pointer samples that arrived this frame, including deferred/queued moves carried from a prior boundary (K before coalescing) (FR-008).
|
Full Usage:
ProductModelChanged
Field type: bool
|
A product message actually changed the model this frame (the reference identity of the folded model changed across `host.Update`). `false` for a no-message frame, a pure hover/focus frame, and an animation-only tick (FR-001/003/005).
|
Full Usage:
RemeasuredNodeCount
Field type: int
|
Nodes re-measured this frame (from `WorkReductionRecord.RemeasuredNodeCount`); 0 on an idle frame, bounded (overlay-assembly, not whole-tree) on an animation-only frame.
|
Full Usage:
RepaintedNodeCount
Field type: int
|
Feature 116 (Phase 7, FR-001/FR-002, US1): the number of nodes whose paint was REPAINTED this frame — the damage set: the changed node(s) plus any genuinely-shifted nodes. A localized visual-state change reports a small count (the changed control + its immediate shifted neighbours, `<= 4` for a leaf hover, `< TotalNodeCount`); a theme switch that invalidates all paint reports every node; an idle frame reports `0`. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
ReplayCacheNativeBytes
Field type: int
|
Feature 120 (US3, FR-013): native bytes held by the replay cache after this frame — a deterministic model estimate (resident recorded-picture subtree node counts), bounded by the cap so a memory regression is observable. Deterministic, golden-asserted. The live backend additionally reports its real `SKPicture` native byte total in the non-golden timing baseline.
|
Full Usage:
ReplayHitCount
Field type: int
|
Feature 120 (US3, FR-014): replay HITS this frame — `CachedSubtree` boundaries whose recorded picture was resident and whose fingerprint matched, so the recorded draw commands were replayed instead of re-walked. `0` on a frame with no cacheable boundary or under the replay-disable oracle. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
ReplayMissCount
Field type: int
|
Feature 120 (US3, FR-014): replay MISSES this frame — boundaries (re)recorded because the identity was cold, its fingerprint changed, or its entry had been evicted. `0` on a frame with no cacheable boundary. Deterministic, golden-asserted.
|
Full Usage:
ReplayRecordCount
Field type: int
|
Feature 120 (US3, FR-014): pictures recorded this frame (one per miss). Deterministic, golden-asserted.
|
Full Usage:
ReplaySkippedNodeCount
Field type: int
|
Feature 120 (US3, FR-014/SC-004): subtree paint-nodes skipped by replay this frame — the summed node count of every replayed (hit) boundary's recorded subtree, i.e. the draw-call walk avoided. The work-reduction signal. `0` on a frame with no replay hit. Deterministic, golden-asserted.
|
Full Usage:
TextMeasureCacheHitCount
Field type: int
|
Feature 117 (Phase 8, FR-001/FR-005, US1): text-measure cache HITS this frame — measurements `(text, font)` whose key was resident, reused without re-invoking `Scene.measureText`. `0` on a frame that measures no text or under the always-miss oracle. A warm text-heavy frame whose text inputs did not change reports `> 0`. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
TextMeasureCacheMissCount
Field type: int
|
Feature 117 (Phase 8, FR-001/FR-005, US1): text-measure cache MISSES this frame — measurements whose key was cold, changed (any of text/family/size/weight), or evicted, so the text was measured fresh and stored. `0` on a frame that measures no text; `> 0` on a cold frame and on a style-only frame only if new text appeared (unchanged text serves hits). Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
ViewCalled
Field type: bool
|
THE VIEW PHASE: `host.View size model` actually ran this frame to (re)produce a tree. Feature 111 narrows this — it is `false` on a model-unchanged frame (including an animation-only tick, which formerly reported `true`) because the scheduler reuses the already-produced view tree and skips `host.View` (FR-003/FR-011); the overlay/paint fact moves to `PaintRan`. Still equals `FullRenderCount > 0`. Feature 110: retained pointer routing does not set it true either.
|
Full Usage:
VirtualItemsMaterialized
Field type: int
|
Feature 114 (Phase 6, FR-013): the number of repeated-control row items actually MATERIALIZED this frame — the count of `data-grid-row` nodes the virtualized control(s) realized. Bounded by `visibleCount + 2 * overscan` and does NOT scale with the total logical row count: a 100-, 1000-, and 10000-row grid with the same viewport + overscan all report the same materialized count. `0` on a frame that evaluates no virtualized control; aggregates across virtualized controls. Deterministic, golden-asserted via `Perf.runScript`.
|
Full Usage:
VirtualItemsTotal
Field type: int
|
Feature 114 (Phase 6, FR-013): the total LOGICAL item count the virtualized control(s) represent this frame (the sum of each `data-grid`'s logical `Total`). Equals `VirtualItemsMaterialized` only when the whole collection fits the realized window; otherwise it scales with the data while `VirtualItemsMaterialized` stays bounded. `0` on a frame with no virtualized control. Deterministic, golden-asserted via `Perf.runScript`.
|