docs: wire up nav + rename "V1 Protocol" page to "Control Reconciler Protocol"

The two pages added in #444 (the protocol reference + the extension
cookbook) were never added to the mkdocs `nav:` tree, so they published
but were unreachable from the site navigation. Wire both into the
"Under the Hood" section.

Rename the reference page from the internal "V1 Protocol" label to the
clearer "Control Reconciler Protocol" (reader-visible only):
- template v1-protocol.md.dt -> control-reconciler-protocol.md.dt, which
  drives the generated output filename
- page title/H1, nav label, and the 8 cross-links + link text from the
  cookbook page
- internal slugs left as-is (doc-app folder, image paths, the
  src/Reactor/Core/V1Protocol namespace) since they are not reader-visible

Recompiled the docset (no screenshots), which refreshes generated output
that had drifted from source:
- threading-and-dispatch.md: echo-suppression snippet picks up the
  EchoSuppressScopeDepth path
- skills/reactor.api.txt (both copies) regenerated: adds the
  ItemsRepeater<T> factory overloads and the V1UnmountDisposition enum

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: codemonkeychris

…cs/_pipeline/templates/v1-protocol.md.dt …plates/control-reconciler-protocol.md.dtdocs/_pipeline/templates/v1-protocol.md.dt renamed to docs/_pipeline/templates/control-reconciler-protocol.md.dt docs/_pipeline/templates/v1-protocol.md.dt renamed to docs/_pipeline/templates/control-reconciler-protocol.md.dt

@@ -1,5 +1,5 @@
 ---
-title: "The V1 Handler Protocol"
+title: "The Control Reconciler Protocol"
 app: v1-protocol
 order: 33.5
 audience: advanced
@@ -27,7 +27,7 @@ every control you add yourself dispatches through the same tight loop.
 Read this page before adding a new native control or before reaching for
 a debugger when an existing one mis-updates.
 
-# The V1 Handler Protocol
+# The Control Reconciler Protocol
 
 This page documents the data path between
 [`Reconciler.Reconcile`](reconciliation.md#reconcile--the-entry-point)

docs/_pipeline/templates/extending-reactor-controls.md.dt

@@ -25,7 +25,7 @@ that flow. By the end you will have added a `StarMeter` element to a
 Reactor app, wired it to WinUI's `RatingControl`, and matched the
 built-in performance bar without writing a line of imperative
 interpreter code. Read the reference companion
-[The V1 Handler Protocol](v1-protocol.md) for the model the steps here
+[The Control Reconciler Protocol](control-reconciler-protocol.md) for the model the steps here
 plug into.
 
 # Extending Reactor with Native Controls
@@ -102,9 +102,9 @@ shape; keeping the demo focused, the cookbook below omits it.
 ## Step 2 — Choose a shape (descriptor vs hand-coded)
 
 Reactor's handler protocol has two surfaces — declarative
-([`ControlDescriptor`](v1-protocol.md#descriptors--declarative-handlers))
+([`ControlDescriptor`](control-reconciler-protocol.md#descriptors--declarative-handlers))
 and imperative
-([`IElementHandler`](v1-protocol.md#the-handler-contract)) — that
+([`IElementHandler`](control-reconciler-protocol.md#the-handler-contract)) — that
 land on the same dispatch table. New controls should default to a
 descriptor; reach for a hand-coded handler only when the descriptor
 escape hatches (`.Imperative`, `.HandCoded…`) still cannot express
@@ -129,7 +129,7 @@ the bar for "complicated enough to write by hand."
 ```
 
 Each fluent builder call adds one
-[`PropEntry`](v1-protocol.md#propentry-shapes--the-prop-binding-vocabulary)
+[`PropEntry`](control-reconciler-protocol.md#propentry-shapes--the-prop-binding-vocabulary)
 to the descriptor. The interpreter iterates them in declaration order
 during Mount and Update. The descriptor above uses three of the
 common shapes:
@@ -199,7 +199,7 @@ short-circuit for `IsDisabledFocusable` and the
 
 `StarMeterElement` is a leaf, so the descriptor declares
 `Children = new None<…>()`. The dispatch surface is the same as the
-[ChildrenStrategy survey](v1-protocol.md#children-strategies); the
+[ChildrenStrategy survey](control-reconciler-protocol.md#children-strategies); the
 right strategy is whichever matches your WinUI control's structural
 contract:
 
@@ -265,7 +265,7 @@ opt-ins.
 exposes `(Color, IsOn) → Background` is one entry, not two — the
 `get` returns a tuple and the `set` reads both fields. The diff fires
 exactly when either input changes. This is how the LED indicator in
-[the V1 Protocol reference](v1-protocol.md#descriptors--declarative-handlers)
+[the Control Reconciler Protocol reference](control-reconciler-protocol.md#descriptors--declarative-handlers)
 collapses two element fields into one WinUI write.
 
 **Layer in a Reactor-friendly default for an awkward control.** Many
@@ -358,14 +358,14 @@ floating-point tolerance, deliberately imperative entry — capture
 the reason in a comment on the descriptor field, not on the calling
 component. The descriptor is where future maintainers will look.
 
-**Read the V1 Protocol reference once end-to-end.** Steps 1 through 6
-above are the recipe; [the protocol page](v1-protocol.md) is the
+**Read the Control Reconciler Protocol reference once end-to-end.** Steps 1 through 6
+above are the recipe; [the protocol page](control-reconciler-protocol.md) is the
 specification it implements. The two pages together are the complete
 contract — bookmark both.
 
 ## Next Steps
 
-- [The V1 Handler Protocol](v1-protocol.md) — the model the steps on this page plug into.
+- [The Control Reconciler Protocol](control-reconciler-protocol.md) — the model the steps on this page plug into.
 - [Reconciliation](reconciliation.md) — what happens before the registered handler is invoked, and how Mount vs Update vs Unmount get chosen.
 - [Element Pool](element-pool.md) — what `RentControl` actually does, and how the per-type pool keeps `Mount` allocation-free.
 - [Modifier System](modifier-system.md) — how the `Setters` chain a descriptor applies after its own prop loop works.

docs/guide/v1-protocol.md docs/guide/control-reconciler-protocol.mddocs/guide/v1-protocol.md renamed to docs/guide/control-reconciler-protocol.md

@@ -12,7 +12,7 @@ every control you add yourself dispatches through the same tight loop.
 Read this page before adding a new native control or before reaching for
 a debugger when an existing one mis-updates.
 
-# The V1 Handler Protocol
+# The Control Reconciler Protocol
 
 This page documents the data path between
 [`Reconciler.Reconcile`](reconciliation.md#reconcile--the-entry-point)

docs/guide/extending-reactor-controls.md

@@ -11,7 +11,7 @@ that flow. By the end you will have added a `StarMeter` element to a
 Reactor app, wired it to WinUI's `RatingControl`, and matched the
 built-in performance bar without writing a line of imperative
 interpreter code. Read the reference companion
-[The V1 Handler Protocol](v1-protocol.md) for the model the steps here
+[The Control Reconciler Protocol](control-reconciler-protocol.md) for the model the steps here
 plug into.
 
 # Extending Reactor with Native Controls
@@ -100,9 +100,9 @@ shape; keeping the demo focused, the cookbook below omits it.
 ## Step 2 — Choose a shape (descriptor vs hand-coded)
 
 Reactor's handler protocol has two surfaces — declarative
-([`ControlDescriptor`](v1-protocol.md#descriptors--declarative-handlers))
+([`ControlDescriptor`](control-reconciler-protocol.md#descriptors--declarative-handlers))
 and imperative
-([`IElementHandler`](v1-protocol.md#the-handler-contract)) — that
+([`IElementHandler`](control-reconciler-protocol.md#the-handler-contract)) — that
 land on the same dispatch table. New controls should default to a
 descriptor; reach for a hand-coded handler only when the descriptor
 escape hatches (`.Imperative`, `.HandCoded…`) still cannot express
@@ -164,7 +164,7 @@ public static class StarMeterDescriptor
 ```
 
 Each fluent builder call adds one
-[`PropEntry`](v1-protocol.md#propentry-shapes--the-prop-binding-vocabulary)
+[`PropEntry`](control-reconciler-protocol.md#propentry-shapes--the-prop-binding-vocabulary)
 to the descriptor. The interpreter iterates them in declaration order
 during Mount and Update. The descriptor above uses three of the
 common shapes:
@@ -232,7 +232,7 @@ short-circuit for `IsDisabledFocusable` and the
 
 `StarMeterElement` is a leaf, so the descriptor declares
 `Children = new None<…>()`. The dispatch surface is the same as the
-[ChildrenStrategy survey](v1-protocol.md#children-strategies); the
+[ChildrenStrategy survey](control-reconciler-protocol.md#children-strategies); the
 right strategy is whichever matches your WinUI control's structural
 contract:
 
@@ -335,7 +335,7 @@ opt-ins.
 exposes `(Color, IsOn) → Background` is one entry, not two — the
 `get` returns a tuple and the `set` reads both fields. The diff fires
 exactly when either input changes. This is how the LED indicator in
-[the V1 Protocol reference](v1-protocol.md#descriptors--declarative-handlers)
+[the Control Reconciler Protocol reference](control-reconciler-protocol.md#descriptors--declarative-handlers)
 collapses two element fields into one WinUI write.
 
 **Layer in a Reactor-friendly default for an awkward control.** Many
@@ -428,14 +428,14 @@ floating-point tolerance, deliberately imperative entry — capture
 the reason in a comment on the descriptor field, not on the calling
 component. The descriptor is where future maintainers will look.
 
-**Read the V1 Protocol reference once end-to-end.** Steps 1 through 6
-above are the recipe; [the protocol page](v1-protocol.md) is the
+**Read the Control Reconciler Protocol reference once end-to-end.** Steps 1 through 6
+above are the recipe; [the protocol page](control-reconciler-protocol.md) is the
 specification it implements. The two pages together are the complete
 contract — bookmark both.
 
 ## Next Steps
 
-- [The V1 Handler Protocol](v1-protocol.md) — the model the steps on this page plug into.
+- [The Control Reconciler Protocol](control-reconciler-protocol.md) — the model the steps on this page plug into.
 - [Reconciliation](reconciliation.md) — what happens before the registered handler is invoked, and how Mount vs Update vs Unmount get chosen.
 - [Element Pool](element-pool.md) — what `RentControl` actually does, and how the per-type pool keeps `Mount` allocation-free.
 - [Modifier System](modifier-system.md) — how the `Setters` chain a descriptor applies after its own prop loop works.

docs/guide/threading-and-dispatch.md

@@ -165,8 +165,13 @@ internal static void BeginSuppress(UIElement control)
 internal static bool ShouldSuppress(UIElement control)
 {
     if (control is not FrameworkElement fe) return false;
-    if (fe.GetValue(Reconciler.ReactorAttached.StateProperty) is Reconciler.ReactorState state
-        && state.EchoSuppressCount > 0)
+    if (fe.GetValue(Reconciler.ReactorAttached.StateProperty) is not Reconciler.ReactorState state)
+        return false;
+    // §8.2 — setter-suppression scope: drop the echo without consuming a
+    // counter token. The scope wraps ApplySetters, where the engine can't
+    // predict which value-bearing DPs the user's `.Set(...)` will write.
+    if (state.EchoSuppressScopeDepth > 0) return true;
+    if (state.EchoSuppressCount > 0)
     {
         state.EchoSuppressCount--;
         return true;

mkdocs.yml

@@ -136,6 +136,8 @@ nav:
     - WPF Interop: wpf-interop.md
   - Under the Hood:
     - Architecture Overview: architecture-overview.md
+    - Control Reconciler Protocol: control-reconciler-protocol.md
+    - Extending Reactor Controls: extending-reactor-controls.md
     - Reactivity Model: reactivity-model.md
     - Hooks Internals: hooks-internals.md
     - Reconciliation: reconciliation.md

plugins/reactor/skills/reactor-dsl/references/reactor.api.txt

@@ -90,6 +90,8 @@ InfoBadge(int value) → InfoBadgeElement
 InfoBar(string title = null, string message = null) → InfoBarElement
 InterspersedGrid(Orientation orientation, Element[] items, double[] proportions, double separatorSize, Func<int, Element> separatorFactory) → GridElement
 ItemContainer(Element child) → ItemContainerElement
+ItemsRepeater<T>(IReadOnlyList<T> items, Func<T, int, Element> viewBuilder) → ItemsRepeaterElement<T>
+ItemsRepeater<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → ItemsRepeaterElement<T>
 ItemsView<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → ItemsViewElement<T>
 LazyHStack<T>(IReadOnlyList<T> items, Func<T, int, Element> viewBuilder) → LazyHStackElement<T>
 LazyHStack<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → LazyHStackElement<T>
@@ -918,6 +920,7 @@ KeyedListDiagnosticKind { NullKey, DuplicateKey }
 ItemsViewLayoutKind { StackLayout, LinedFlowLayout, UniformGridLayout }
 PersistedScope { Window, Application }
 TemplatedControlKind { ListView, GridView, FlipView }
+V1UnmountDisposition { CollectSelf, ContinueDefaultTraversal, SkipPool }
 BlockStatus { Loading, Loaded, Failed }
 DataSourceCapabilities { None, ServerSort, ServerFilter, ServerSearch, ServerCount, ServerSelect, Mutate, Refresh }
 FilterOperator { Equals, NotEquals, Contains, StartsWith, EndsWith, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Between, In, IsNull, IsNotNull }

skills/reactor.api.txt

@@ -90,6 +90,8 @@ InfoBadge(int value) → InfoBadgeElement
 InfoBar(string title = null, string message = null) → InfoBarElement
 InterspersedGrid(Orientation orientation, Element[] items, double[] proportions, double separatorSize, Func<int, Element> separatorFactory) → GridElement
 ItemContainer(Element child) → ItemContainerElement
+ItemsRepeater<T>(IReadOnlyList<T> items, Func<T, int, Element> viewBuilder) → ItemsRepeaterElement<T>
+ItemsRepeater<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → ItemsRepeaterElement<T>
 ItemsView<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → ItemsViewElement<T>
 LazyHStack<T>(IReadOnlyList<T> items, Func<T, int, Element> viewBuilder) → LazyHStackElement<T>
 LazyHStack<T>(IReadOnlyList<T> items, Func<T, string> keySelector, Func<T, int, Element> viewBuilder) → LazyHStackElement<T>
@@ -918,6 +920,7 @@ KeyedListDiagnosticKind { NullKey, DuplicateKey }
 ItemsViewLayoutKind { StackLayout, LinedFlowLayout, UniformGridLayout }
 PersistedScope { Window, Application }
 TemplatedControlKind { ListView, GridView, FlipView }
+V1UnmountDisposition { CollectSelf, ContinueDefaultTraversal, SkipPool }
 BlockStatus { Loading, Loaded, Failed }
 DataSourceCapabilities { None, ServerSort, ServerFilter, ServerSearch, ServerCount, ServerSelect, Mutate, Refresh }
 FilterOperator { Equals, NotEquals, Contains, StartsWith, EndsWith, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Between, In, IsNull, IsNotNull }