docs(getting-started): show launch line in samples + pipeline fixes (#331)

* docs(getting-started): show launch line in samples + pipeline fixes

Getting-started samples now include the ReactorApp.Run<T>(...) call so
readers see the full launch shape. Three companion pipeline fixes shake
out from the same work:

- Snippet extractor edits stayed off the table after a false start —
  the simpler fix was dropping the `#if DEBUG / preview: true / #endif`
  scaffolding from the doc apps and switching to the current
  `devtools: true` parameter (the older `preview:` is deprecated). A
  bullet in the template notes that real apps should guard `devtools`
  under `#if DEBUG`; we skip the conditional in samples for brevity.

- NormalizeLineEndings in CompileCommand (also called by the reference
  generator) converts emitted Markdown to Environment.NewLine. Without
  it, every compile under Windows/`core.autocrlf=true` flapped all 63
  outputs as modified.

- reference-map.yaml gains a `Microsoft.UI.Reactor.Core.RenderContext.Use*`
  default so the actually-used hook surface (UseState, UseEffect, etc.)
  gets reference pages and `<!-- ref:UseState -->` markers in hooks.md
  resolve to working links. Six guide outputs (animation,
  architecture-overview, collections, effects, hooks, reconciliation)
  re-sync with their templates as a side effect.

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

* docs(animation,collections): restore content lost from templates

PR #322 (spec 042) wrote the "Transactional animation — Animations.Animate(...)"
section into docs/guide/animation.md and the "Keyed reconciliation, in one
paragraph" / IReactorKeyed / .WithKey(item) subsections into
docs/guide/collections.md, but never added them to the .md.dt templates.
The previous commit re-synced the generated outputs from their templates
and stripped those sections.

Port both back into the templates and regenerate.

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: codemonkeychris

docs/_pipeline/ai-author-skill.md

@@ -336,15 +336,11 @@ using Microsoft.UI.Reactor.Core;
 using static Microsoft.UI.Reactor.Factories;
 using Microsoft.UI.Xaml;
 
-ReactorApp.Run<MyApp>("Title", width: 600, height: 400
-#if DEBUG
-    , preview: true
-#endif
-);
+ReactorApp.Run<MyApp>("Title", width: 600, height: 400, devtools: true);
 ```
 
-- Always include `preview: true` under `#if DEBUG` — this enables the
-  screenshot capture system.
+- Always include `devtools: true` — this enables the screenshot capture system.
+  (The older `preview:` parameter is deprecated; the compiler will warn.)
 - Each component class in the file can be wrapped in snippet markers.
 - The app should display a reasonable default state on launch (the screenshots
   are captured after `startup-delay` ms with no interaction).

docs/_pipeline/apps/calculator/App.cs

@@ -1,15 +1,11 @@
+// <snippet:calculator-app>
 using Microsoft.UI.Reactor;
 using Microsoft.UI.Reactor.Core;
 using static Microsoft.UI.Reactor.Factories;
 using Microsoft.UI.Xaml;
 
-ReactorApp.Run<CalculatorApp>("Calculator", width: 380, height: 500
-#if DEBUG
-    , preview: true
-#endif
-);
+ReactorApp.Run<CalculatorApp>("Calculator", width: 380, height: 500, devtools: true);
 
-// <snippet:calculator-app>
 class CalculatorApp : Component
 {
     public override Element Render()

docs/_pipeline/apps/getting-started/App.cs

@@ -1,15 +1,11 @@
+// <snippet:hello-world>
 using Microsoft.UI.Reactor;
 using Microsoft.UI.Reactor.Core;
 using static Microsoft.UI.Reactor.Factories;
 using Microsoft.UI.Xaml;
 
-ReactorApp.Run<GettingStartedApp>("Getting Started", width: 600, height: 400
-#if DEBUG
-    , preview: true
-#endif
-);
+ReactorApp.Run<GettingStartedApp>("Getting Started", width: 600, height: 400, devtools: true);
 
-// <snippet:hello-world>
 class GettingStartedApp : Component
 {
     public override Element Render()
@@ -24,7 +20,15 @@ public override Element Render()
 }
 // </snippet:hello-world>
 
+// The classes below are alternate roots for the rest of this page. Only one
+// ReactorApp.Run<T>() call can run as a top-level statement, so the launch
+// lines for these classes are shown as comments — drop one into a fresh
+// App.cs to try it.
+
 // <snippet:usestate-counter>
+// Launch with:
+//   ReactorApp.Run<CounterExample>("Counter", width: 600, height: 400);
+
 class CounterExample : Component
 {
     public override Element Render()
@@ -44,6 +48,9 @@ public override Element Render()
 // </snippet:usestate-counter>
 
 // <snippet:layout-basics>
+// Launch with:
+//   ReactorApp.Run<LayoutBasicsExample>("Layout", width: 600, height: 400);
+
 class LayoutBasicsExample : Component
 {
     public override Element Render()
@@ -77,6 +84,9 @@ public override Element Render()
 // </snippet:layout-basics>
 
 // <snippet:multiple-state>
+// Launch with:
+//   ReactorApp.Run<MultipleStateExample>("Multiple State", width: 600, height: 400);
+
 class MultipleStateExample : Component
 {
     public override Element Render()

docs/_pipeline/apps/todo-app/App.cs

@@ -1,19 +1,11 @@
+// <snippet:todo-app>
 using Microsoft.UI.Reactor;
 using Microsoft.UI.Reactor.Core;
 using static Microsoft.UI.Reactor.Factories;
 using Microsoft.UI.Xaml;
 
-ReactorApp.Run<TodoApp>("Todo App", width: 550, height: 600
-#if DEBUG
-    , preview: true
-#endif
-);
-
-// <snippet:todo-record>
-record TodoItem(string Text, bool Done);
-// </snippet:todo-record>
+ReactorApp.Run<TodoApp>("Todo App", width: 550, height: 600, devtools: true);
 
-// <snippet:todo-app>
 class TodoApp : Component
 {
     public override Element Render()
@@ -81,3 +73,7 @@ public override Element Render()
     }
 }
 // </snippet:todo-app>
+
+// <snippet:todo-record>
+record TodoItem(string Text, bool Done);
+// </snippet:todo-record>

docs/_pipeline/reference-map.yaml

@@ -13,6 +13,9 @@
 # fall through with no category/guide-pages.
 
 defaults:
+  - match: "Microsoft.UI.Reactor.Core.RenderContext.Use*"
+    category: hooks
+    guide-pages: [hooks, effects]
   - match: "Microsoft.UI.Reactor.Hooks.*"
     category: hooks
     guide-pages: [hooks, effects]

docs/_pipeline/templates/animation.md.dt

@@ -162,6 +162,89 @@ animation runs automatically when the reconciler detects the transition.
 Use connected animations for list-to-detail [navigation](navigation.md)
 where an element "flies" from the list into the detail view.
 
+## Transactional animation — `Animations.Animate(...)`
+
+`Animations.Animate(kind, action)` is Reactor's SwiftUI-style transactional
+animation primitive. Wrap a state mutation, and any **structural** change to
+a keyed list (insert, move, remove) that comes out of that mutation picks up
+the kind — without a per-element modifier in sight.
+
+```csharp
+class TodoList : Component
+{
+    public override Element Render()
+    {
+        var (items, setItems) = UseState<IReadOnlyList<Todo>>(_seed);
+
+        return VStack(12,
+            Button("Add", () =>
+                Animations.Animate(AnimationKind.Spring, () =>
+                    setItems([.. items, new Todo(Guid.NewGuid().ToString(), "New")]))),
+            ListView<Todo>(items, (t, _) => TextBlock(t.Title).Padding(8))
+                .Height(400)
+        );
+    }
+}
+```
+
+`AnimationKind` is the declarative knob — `Spring`, `EaseIn`, `EaseOut`,
+`EaseInOut`, `Default`, or `None`. The kind flows through an `AsyncLocal`
+ambient: a setter invoked inside `Animate` snapshots the ambient before
+queuing the render, and the reconciler re-pushes the snapshot around the
+diff pass so `ListView`, `GridView`, `LazyVStack` (and hand-built
+`FlexColumn(items.Select(...).WithKey(...))` children) all animate the
+resulting insert / move / remove. (See spec 042 §6.)
+
+### What `Animate` does *not* do
+
+`Animate` is **scoped to structural changes**. A leaf `TextBlock` whose
+`Foreground` changes inside `Animate(.Spring)` does **not** animate the
+foreground — that remains the job of per-element modifiers like
+`.WithImplicitTransition(...)` or
+[`AnimationScope.WithAnimation(...)`](#withanimation-scope). The two
+channels are deliberately independent so the SwiftUI "`withAnimation` only
+animates layout-shape ops" contract holds; conflating them would surprise
+users coming from that mental model.
+
+Per-element animation modifiers continue to win when set: declaring
+`.Transition(Fade)` on a row makes that row's enter / exit use Fade
+regardless of the ambient. The ambient is a default for the transactional
+case, not a hammer for every change.
+
+### Nesting and explicit suppression
+
+Nested `Animate` calls stack like `using` blocks — the inner kind wins for
+state changes inside its scope, and the outer kind resumes after:
+
+```csharp
+Animations.Animate(AnimationKind.Spring, () =>
+{
+    // Insert: animates with Spring.
+    setItems([.. items, x]);
+
+    Animations.Animate(AnimationKind.None, () =>
+    {
+        // Insert inside None: no animation, even though we're still inside
+        // an outer Spring transaction. Useful when a child component needs
+        // to opt out of the caller's implicit animation intent.
+        setOtherItems([.. others, y]);
+    });
+});
+```
+
+### Reduced motion
+
+`Animate` respects the system's reduced-motion preference *at the call
+site*. Read `UseReducedMotion()` and skip the wrapper when the user has
+opted out:
+
+```csharp
+var reduceMotion = UseReducedMotion();
+Action commit = () => setItems([.. items, x]);
+if (reduceMotion) commit();
+else              Animations.Animate(AnimationKind.Spring, commit);
+```
+
 ## WithAnimation Scope
 
 `AnimationScope.WithAnimation()` wraps a state change so that every

docs/_pipeline/templates/collections.md.dt

@@ -59,6 +59,61 @@ The `keySelector` parameter (`c => c.Id`) tells Reactor how to identify each
 item. When your data changes, Reactor uses keys to match old items to new ones
 and update only what changed — no full-list rebuild.
 
+### Keyed reconciliation, in one paragraph
+
+When you replace the list (immutable state in, immutable state out), Reactor
+walks the old and new key sequences and emits the minimum set of
+`Insert` / `Move` / `RemoveAt` operations to the underlying WinUI
+`ListView` / `GridView` / `ItemsRepeater`. A single insert at the front of
+a 100-item list animates one row instead of re-realizing 100 containers.
+You get this for free as long as `keySelector` returns a value that is:
+
+- **Stable** across re-renders for the lifetime of the item — using a
+  row index defeats reconciliation and produces the same churn as
+  having no key.
+- **Unique** within the list — duplicate keys trigger a bulk-replace
+  bailout and a one-shot diagnostic in the dev log.
+- **Non-null** — null keys bail out the diff for the affected list.
+
+### `IReactorKeyed` — identity on the data
+
+When a model type owns its identity, implement `IReactorKeyed` to drop the
+`keySelector` boilerplate at every call site:
+
+```csharp
+record Contact(string Id, string Name, string Email) : IReactorKeyed
+{
+    string IReactorKeyed.Key => Id;
+}
+
+// keySelector is inferred from IReactorKeyed.Key:
+ListView<Contact>(contacts, (contact, index) => …);
+LazyVStack<Contact>(contacts, (contact, index) => …);
+GridView<Contact>(contacts, (contact, index) => …);
+```
+
+The explicit-`keySelector` overload remains the right choice for types you
+do not own (interop / third-party POCOs without a natural identity
+property) — for those, keep `c => c.Id` at the call site.
+
+### `.WithKey(item)` for hand-built children
+
+For hand-built keyed children — `FlexColumn(items.Select(…))` and
+similar — `.WithKey<TKey>(TKey item) where TKey : IReactorKeyed` is the
+ergonomic peer of `.WithKey(item.Key)`:
+
+```csharp
+FlexColumn(
+    contacts.Select(c =>
+        TextBlock(c.Name).WithKey(c)   // identity-on-data
+    ).ToArray<Element?>()
+)
+```
+
+Both shapes route through the same incremental diff, so a hand-built
+`FlexColumn` of contacts animates inserts and reorders just like the
+templated `ListView<Contact>`.
+
 ## LazyVStack (Virtualized)
 
 `LazyVStack<T>` looks like `ListView<T>` but only creates elements for items

docs/_pipeline/templates/getting-started.md.dt

@@ -152,6 +152,9 @@ Run it with `dotnet run` and you'll see this:
 Here's what's happening:
 
 - **`ReactorApp.Run<T>`** launches a window and mounts your root component.
+- **`devtools: true`** enables the in-app dev menu and screenshot capture. In a
+  real app you'd normally guard this under `#if DEBUG` so release builds don't
+  ship the dev surface; we skip the conditional here for brevity.
 - **[`UseState`](hooks.md)** returns the current value and a setter. When you call the
   setter, Reactor re-renders the component with the new value.
 - **[`VStack`](layout.md)** stacks children vertically. The number `16` is the pixel spacing.

docs/guide/architecture-overview.md

@@ -119,14 +119,80 @@ sees one shape per concept.
 ```csharp
 public UIElement GetElement(ElementFactoryGetArgs args)
 {
-    var index = args.Data is int i ? i : 0;
+    // Resolve the realized data → (key, dataIndex). Three paths:
+    //   1. Spec 042: args.Data is ReactorRow — read both off the row.
+    //   2. Legacy: args.Data is int — index directly, synthetic key.
+    //   3. Fallback: unknown shape, treat as index 0.
+    string key;
+    int index;
+    switch (args.Data)
+    {
+        case ReactorRow row:
+            key = row.Key;
+            index = row.Index;
+            break;
+        case int i:
+            index = i;
+            key = i.ToString(global::System.Globalization.CultureInfo.InvariantCulture);
+            break;
+        default:
+            index = 0;
+            key = "0";
+            break;
+    }
+
     if (index < 0 || index >= _items.Count)
         return new TextBlock { Text = "" };
 
     var item = _items[index];
     var element = _viewBuilder(item, index);
-    _mountedElements[index] = element;
-    var control = _reconciler.Mount(element, _requestRerender);
+
+    UIElement? control;
+    if (_recyclePool.Count > 0)
+    {
+        // Reuse a previously-recycled container. The framework still has
+        // it parented to the ItemsRepeater, so the ViewManager.cpp:866
+        // Append-skip kicks in and the visual tree stays stable.
+        var reused = _recyclePool.Pop();
+        if (_lastElementByControl.TryGetValue(reused, out var oldElement))
+        {
+            var replacement = _reconciler.Reconcile(oldElement, element, reused, _requestRerender);
+            if (replacement is not null && !ReferenceEquals(replacement, reused))
+            {
+                // Heterogeneous-row case: Reconcile decided the root
+                // element type changed and built a fresh control.
+                // `reused` is now unmounted but still parented to the
+                // ItemsRepeater — detach so it doesn't sit there as
+                // an orphan (the original leak shape we're fixing).
+                // (PR #324 review)
+                DetachFromParent(reused);
+                _lastElementByControl.Remove(reused);
+                control = replacement;
+            }
+            else
+            {
+                control = reused;
+            }
+        }
+        else
+        {
+            // Defensive: pool entry without a tracked oldElement should
+            // not happen — fall back to re-mounting on top of it.
+            control = _reconciler.Mount(element, _requestRerender);
+        }
+    }
+    else
+    {
+        control = _reconciler.Mount(element, _requestRerender);
+    }
+
+    _mountedElements[key] = element;
+    if (control is not null)
+    {
+        _keyByControl[control] = key;
+        _lastElementByControl[control] = element;
+    }
+
     return control ?? new TextBlock { Text = "" };
 }
 ```

docs/guide/effects.md

@@ -2,7 +2,7 @@
 Effects are commit-phase side effects with dependency tracking. After Reactor
 finishes [reconciling](reconciliation.md) the element tree and patching the
 WinUI controls for a render, it walks the effect queue for that render and
-runs every <!-- ref:UseEffect --> body whose dependency array has changed
+runs every [UseEffect](reference/hooks/UseEffect.md) body whose dependency array has changed
 since the previous commit. The body runs **after** the new UI has been
 committed — never during render — so an effect is the safe place to start a
 timer, open a subscription, or kick off a `Task.Run` that will eventually