microsoft
diff --git a/‎CHANGELOG.md‎
Lines changed: 54 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 54 additions & 0 deletions
diff --git a/‎Reactor.sln‎
Lines changed: 19 additions & 0 deletions b/‎Reactor.sln‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎docs/_pipeline/templates/advanced.md.dt‎
Lines changed: 107 additions & 0 deletions b/‎docs/_pipeline/templates/advanced.md.dt‎
Lines changed: 107 additions & 0 deletions
diff --git a/‎docs/guide/advanced.md‎
Lines changed: 107 additions & 0 deletions b/‎docs/guide/advanced.md‎
Lines changed: 107 additions & 0 deletions
@@ -29,6 +29,33 @@ to land under these conventions; subsequent specs follow this shape.
 
 ### Added
 
+- `Microsoft.UI.Reactor.Hooks.UseMemoCells` /
+  `UseMemoCellsByKey` / `UseMemoCellsByIndex` — cell-level memoization
+  hooks (extension methods on `RenderContext`, plus matching `Component`
+  shims) for high-frequency list/grid bodies. Cells whose item value
+  (and declared deps) haven't changed since the previous render are
+  reused by reference; the reconciler short-circuits on
+  `ReferenceEquals` and skips diffing entirely. (spec 034 §C)
+- `REACTOR_HOOKS_007` analyzer + codefix — warns when a `UseMemoCells`
+  builder lambda closes over a value that isn't declared in the
+  `params deps` list, which would silently render stale. The codefix
+  appends the missing capture to the deps slot. Indirect captures
+  through helper methods are a documented blind spot. (spec 034 §C)
+- "Memoizing list cells" section in `docs/guide/advanced.md` covering
+  the three overloads, when each is the right hammer, the gen2
+  trade-off, and the analyzer-as-safety-net story. (spec 034 §C)
+- `tests/stress_perf/StressPerf.ReactorOptimized` — sibling bench
+  variant that demonstrates the spec-034 §B direct-record-initializer
+  idiom for inner-loop cell construction. The naive `StressPerf.Reactor`
+  variant stays unchanged and remains the framework-level baseline; the
+  new optimized sibling is the reference implementation of the perf-tips
+  skill. Wired into `run_stocks_grid_baseline.ps1`,
+  `run_bench_aot_publish.sh`, `run_benchmark.sh`, and
+  `run_sweep_arm64.ps1`. (spec 034 §B)
+- "Hot loops" section in `docs/guide/advanced.md` documenting when to
+  reach for direct record initializers, the trade-offs vs the fluent
+  chain, and a side-by-side worked example. Source template at
+  `docs/_pipeline/templates/advanced.md.dt`. (spec 034 §B)
 - `Expr(Func<Element?>)` factory in `Microsoft.UI.Reactor.Factories` for inline
   block-expression bodies inside a DSL tree, removing the
   `((Func<Element?>)(() => …))()` cast ceremony. Pure composition — no hooks,
@@ -70,6 +97,33 @@ to land under these conventions; subsequent specs follow this shape.
 
 ### Changed
 
+- **Spec 034 — Element allocation reduction.** Three independent
+  allocation cuts in one PR: bucketed `ElementModifiers` (transparent
+  storage shim, ~−11% bytes/tick on the 4,900-cell stress grid),
+  direct-record-initializer idiom for inner cell loops (~−60% bytes
+  per cell), and `UseMemoCells` cell-level memoization. Verified at
+  PR-close on ARM64 Release with full ETW Present-tracking across
+  10/20/50/100% mutation, all eight stress_perf variants:
+  **ReactorOptimized at 10% mutation reaches 17.1 Effective Refresh/s
+  — within noise of DirectX (17.2) and Wpf (17.9), and +66% over
+  naive Reactor (10.3).** Reconcile-time win on the same A/B: −76% at
+  10% (32.5 ms → 7.9 ms), −61% at 20%, −31% at 50%, −12% at 100% —
+  memo's win tracks the partial-reuse opportunity exactly as
+  predicted. DirectX runs away at saturation (50%+) — no allocating
+  framework can keep up there. Component A in isolation (naive
+  Reactor pre-shim vs post-shim, same source, no app-code changes)
+  shows renders/sec within run-to-run noise at 20/50/100% — its win
+  is allocation-side, not renders-side, on this hardware. See
+  `docs/specs/034-element-allocation-reduction.md` § "Verified
+  close-out — 2026-05-03" for the full eight-variant matrix and
+  reads. (spec 034)
+- `ElementModifiers` now stores layout and visual fields in
+  `LayoutModifiers` / `VisualModifiers` sub-records. Existing call sites are
+  unaffected — public properties (`Padding`, `Margin`, `Foreground`,
+  `Background`, …) shim through to the appropriate bucket on read and write.
+  Perf-critical inner loops may construct buckets directly via the new
+  `Layout = …` / `Visual = …` initializer slots to avoid a fat
+  `ElementModifiers` clone per fluent step. (spec 034 §A)
 - `PersistedStateCache` rewritten over an LRU cache with eviction-on-full
   semantics. The previous "refuse new keys when 4096 entries are present"
   policy is replaced — later, hotter keys are no longer starved by the
 
@@ -39,6 +39,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StressPerf.Bound", "tests\s
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StressPerf.Reactor", "tests\stress_perf\StressPerf.Reactor\StressPerf.Reactor.csproj", "{1CBE61F7-04BC-44FE-B2C9-85A6EF22A653}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StressPerf.ReactorOptimized", "tests\stress_perf\StressPerf.ReactorOptimized\StressPerf.ReactorOptimized.csproj", "{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StressPerf.Wpf", "tests\stress_perf\StressPerf.Wpf\StressPerf.Wpf.csproj", "{92A235CE-7700-4A4C-83A2-D1A1FD9BB593}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StressPerf.DirectX", "tests\stress_perf\StressPerf.DirectX\StressPerf.DirectX.csproj", "{CC8B6B85-4256-403C-B6B6-68DE09C80B54}"
@@ -383,6 +385,22 @@ Global
 		{1CBE61F7-04BC-44FE-B2C9-85A6EF22A653}.Release|Any CPU.Build.0 = Release|x64
 		{1CBE61F7-04BC-44FE-B2C9-85A6EF22A653}.Release|x86.ActiveCfg = Release|x64
 		{1CBE61F7-04BC-44FE-B2C9-85A6EF22A653}.Release|x86.Build.0 = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|ARM64.ActiveCfg = Debug|ARM64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|ARM64.Build.0 = Debug|ARM64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|x64.ActiveCfg = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|x64.Build.0 = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|Any CPU.ActiveCfg = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|Any CPU.Build.0 = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|x86.ActiveCfg = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Debug|x86.Build.0 = Debug|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|ARM64.ActiveCfg = Release|ARM64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|ARM64.Build.0 = Release|ARM64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|x64.ActiveCfg = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|x64.Build.0 = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|Any CPU.ActiveCfg = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|Any CPU.Build.0 = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|x86.ActiveCfg = Release|x64
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB}.Release|x86.Build.0 = Release|x64
 		{92A235CE-7700-4A4C-83A2-D1A1FD9BB593}.Debug|ARM64.ActiveCfg = Debug|ARM64
 		{92A235CE-7700-4A4C-83A2-D1A1FD9BB593}.Debug|ARM64.Build.0 = Debug|ARM64
 		{92A235CE-7700-4A4C-83A2-D1A1FD9BB593}.Debug|x64.ActiveCfg = Debug|x64
@@ -1347,6 +1365,7 @@ Global
 		{E21C1E62-3135-4577-8130-9023A2D8E0AE} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
 		{FE122C30-D3DF-4AA9-9EAD-B63C804D42C7} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
 		{1CBE61F7-04BC-44FE-B2C9-85A6EF22A653} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
+		{5A1B2C3D-4E5F-6789-ABCD-1234567890AB} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
 		{92A235CE-7700-4A4C-83A2-D1A1FD9BB593} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
 		{CC8B6B85-4256-403C-B6B6-68DE09C80B54} = {B899CF64-C19C-0C08-9E9A-B3F6D048BA53}
 		{E2F3A4B5-C6D7-8901-2345-6789ABCDEF12} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 
@@ -110,6 +110,113 @@ mutate the original `ObservableCollection` in event handlers. Reactor
 subscribes to `CollectionChanged` and triggers a re-render on any
 modification.
 
+## Hot loops
+
+The fluent modifier chain is ergonomic but allocates an `ElementModifiers`
+clone per `with`-step. For ordinary UI that is invisible — a button has
+five modifiers, the cost is two extra small records on a click handler.
+For inner-loop cell construction in a 4,900-cell grid that re-renders
+30× per second, those clones dominate the allocation profile.
+
+The escape hatch is to construct the `Element` and its `ElementModifiers`
+record directly, skipping the fluent chain entirely. The
+`LayoutModifiers` and `VisualModifiers` sub-records are public types
+specifically so perf-critical code can build them once instead of having
+the fluent chain rebuild them step-by-step.
+
+```csharp
+// Fluent — five clones per cell. Right tool for ordinary UI.
+var cell = TextBlock(label)
+    .FontSize(8)
+    .Foreground(item.IsUp ? GreenBrush : RedBrush)
+    .Padding(2, 1, 2, 1)
+    .Grid(row: r, column: c);
+
+// Direct record initializer — one TextBlockElement, one ElementModifiers,
+// two bucket sub-records, one Attached dictionary. Use only when the
+// allocation cost shows up in profiles.
+var cell = new TextBlockElement(label)
+{
+    FontSize = 8,
+    Modifiers = new ElementModifiers
+    {
+        Layout = new LayoutModifiers { Padding = new Thickness(2, 1, 2, 1) },
+        Visual = new VisualModifiers { Foreground = item.IsUp ? GreenBrush : RedBrush },
+    },
+    Attached = new Dictionary<Type, object>(1)
+    {
+        [typeof(GridAttached)] = new GridAttached(r, c, 1, 1),
+    },
+};
+```
+
+**Workload shape.** Use this idiom in lists or grids with hundreds-plus
+elements per render — tickers, log tables, observability dashboards. Don't
+adopt it for ordinary screens. The fluent chain remains the right tool for
+everything except the inner cell loop.
+
+**Trade-offs.** Roughly halves the allocation cost of cell construction
+on the 4,900-cell stress grid, but loses fluent ergonomics. The direct
+form is more brittle to refactor — changing one field touches an explicit
+initializer block instead of a chain step. Restrict it to the
+identifiable hot loop and keep the rest of the file fluent.
+
+**Reference implementation.** The canonical before/after pair lives in
+`tests/stress_perf/StressPerf.Reactor` (naive — fluent chain, the shape
+unaware users write) and `tests/stress_perf/StressPerf.ReactorOptimized`
+(idiomatic perf-tuned variant). Same workload, side-by-side diffable.
+
+**Forward reference.** Spec 008's builder-pattern element factories
+would let the fluent chain match this allocation profile, eliminating
+the dichotomy. Until then, treat direct-initializer as a targeted
+optimization.
+
+## Memoizing list cells
+
+`UseMemoCells` skips the cell-build for indices whose item value (and
+declared dependencies) haven't changed since the previous render. The
+reconciler's `ReferenceEquals` shortcut means a reused cell allocates
+nothing and skips diffing entirely.
+
+```csharp
+var theme = ctx.UseTheme();
+var children = ctx.UseMemoCells(
+    stocks,
+    (item, i) => Cell(item, theme),
+    theme);   // ← deps; framework invalidates on change
+```
+
+**When it's the right hammer.** Tickers, log tables, file lists, large
+read-only grids — anywhere the cell content is a pure function of `T`
+plus a small set of declared deps.
+
+**When it's the wrong hammer.** Rows whose chrome depends on focus,
+drag, selection, or hover state that you aren't capturing in deps.
+Memo silently renders stale when an external state change isn't
+declared as a dep — the analyzer below catches the obvious cases, but
+indirect captures through helper methods aren't visible to it.
+
+**Three overloads:**
+
+| Overload | Use when |
+|----------|----------|
+| `UseMemoCells<T>` | Per-item value equality. Default choice. |
+| `UseMemoCellsByKey<T, TKey>` | Items have stable identity but mutable interior (`record Person(int Id, string Name)`). Hashes by key, value-compares for content. Reordered keys reuse cells via the reconciler's keyed-children path. |
+| `UseMemoCellsByIndex<T>` | Data source already knows which indices changed. Skips the per-cell equality scan; only the named indices run the builder. |
+
+**gen2 caveat.** Memo trades short-lived gen0 churn for longer-lived
+gen1/gen2 retention. Many memoized lists across an app can compound
+gen2 pressure even when bytes-per-tick drops. Profile before adopting
+across the board.
+
+**Compile-time safety net.** The companion Roslyn analyzer
+`REACTOR_HOOKS_007` warns when a builder closure captures a value that
+isn't declared in the deps list. Codefix is "add the missing capture to
+deps". Indirect captures through intermediate methods are a documented
+blind spot — the analyzer can't see through a method call without
+whole-program analysis (same blind spot as React's
+`react-hooks/exhaustive-deps`).
+
 ## Tips
 
 **Wrap third-party components in `ErrorBoundary`.** If a plugin or external
 
@@ -253,6 +253,113 @@ mutate the original `ObservableCollection` in event handlers. Reactor
 subscribes to `CollectionChanged` and triggers a re-render on any
 modification.
 
+## Hot loops
+
+The fluent modifier chain is ergonomic but allocates an `ElementModifiers`
+clone per `with`-step. For ordinary UI that is invisible — a button has
+five modifiers, the cost is two extra small records on a click handler.
+For inner-loop cell construction in a 4,900-cell grid that re-renders
+30× per second, those clones dominate the allocation profile.
+
+The escape hatch is to construct the `Element` and its `ElementModifiers`
+record directly, skipping the fluent chain entirely. The
+`LayoutModifiers` and `VisualModifiers` sub-records are public types
+specifically so perf-critical code can build them once instead of having
+the fluent chain rebuild them step-by-step.
+
+```csharp
+// Fluent — five clones per cell. Right tool for ordinary UI.
+var cell = TextBlock(label)
+    .FontSize(8)
+    .Foreground(item.IsUp ? GreenBrush : RedBrush)
+    .Padding(2, 1, 2, 1)
+    .Grid(row: r, column: c);
+
+// Direct record initializer — one TextBlockElement, one ElementModifiers,
+// two bucket sub-records, one Attached dictionary. Use only when the
+// allocation cost shows up in profiles.
+var cell = new TextBlockElement(label)
+{
+    FontSize = 8,
+    Modifiers = new ElementModifiers
+    {
+        Layout = new LayoutModifiers { Padding = new Thickness(2, 1, 2, 1) },
+        Visual = new VisualModifiers { Foreground = item.IsUp ? GreenBrush : RedBrush },
+    },
+    Attached = new Dictionary<Type, object>(1)
+    {
+        [typeof(GridAttached)] = new GridAttached(r, c, 1, 1),
+    },
+};
+```
+
+**Workload shape.** Use this idiom in lists or grids with hundreds-plus
+elements per render — tickers, log tables, observability dashboards. Don't
+adopt it for ordinary screens. The fluent chain remains the right tool for
+everything except the inner cell loop.
+
+**Trade-offs.** Roughly halves the allocation cost of cell construction
+on the 4,900-cell stress grid, but loses fluent ergonomics. The direct
+form is more brittle to refactor — changing one field touches an explicit
+initializer block instead of a chain step. Restrict it to the
+identifiable hot loop and keep the rest of the file fluent.
+
+**Reference implementation.** The canonical before/after pair lives in
+`tests/stress_perf/StressPerf.Reactor` (naive — fluent chain, the shape
+unaware users write) and `tests/stress_perf/StressPerf.ReactorOptimized`
+(idiomatic perf-tuned variant). Same workload, side-by-side diffable.
+
+**Forward reference.** Spec 008's builder-pattern element factories
+would let the fluent chain match this allocation profile, eliminating
+the dichotomy. Until then, treat direct-initializer as a targeted
+optimization.
+
+## Memoizing list cells
+
+`UseMemoCells` skips the cell-build for indices whose item value (and
+declared dependencies) haven't changed since the previous render. The
+reconciler's `ReferenceEquals` shortcut means a reused cell allocates
+nothing and skips diffing entirely.
+
+```csharp
+var theme = ctx.UseTheme();
+var children = ctx.UseMemoCells(
+    stocks,
+    (item, i) => Cell(item, theme),
+    theme);   // ← deps; framework invalidates on change
+```
+
+**When it's the right hammer.** Tickers, log tables, file lists, large
+read-only grids — anywhere the cell content is a pure function of `T`
+plus a small set of declared deps.
+
+**When it's the wrong hammer.** Rows whose chrome depends on focus,
+drag, selection, or hover state that you aren't capturing in deps.
+Memo silently renders stale when an external state change isn't
+declared as a dep — the analyzer below catches the obvious cases, but
+indirect captures through helper methods aren't visible to it.
+
+**Three overloads:**
+
+| Overload | Use when |
+|----------|----------|
+| `UseMemoCells<T>` | Per-item value equality. Default choice. |
+| `UseMemoCellsByKey<T, TKey>` | Items have stable identity but mutable interior (`record Person(int Id, string Name)`). Hashes by key, value-compares for content. Reordered keys reuse cells via the reconciler's keyed-children path. |
+| `UseMemoCellsByIndex<T>` | Data source already knows which indices changed. Skips the per-cell equality scan; only the named indices run the builder. |
+
+**gen2 caveat.** Memo trades short-lived gen0 churn for longer-lived
+gen1/gen2 retention. Many memoized lists across an app can compound
+gen2 pressure even when bytes-per-tick drops. Profile before adopting
+across the board.
+
+**Compile-time safety net.** The companion Roslyn analyzer
+`REACTOR_HOOKS_007` warns when a builder closure captures a value that
+isn't declared in the deps list. Codefix is "add the missing capture to
+deps". Indirect captures through intermediate methods are a documented
+blind spot — the analyzer can't see through a method call without
+whole-program analysis (same blind spot as React's
+`react-hooks/exhaustive-deps`).
+
 ## Tips
 
 **Wrap third-party components in `ErrorBoundary`.** If a plugin or external