[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72SC5P3QB7FP1QYJBH2T03Y":3,"skill-same:01M72SC5P3QB7FP1QYJBH2T03Y":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":33,"install":34,"resources":47},"01M72SC5P3QB7FP1QYJBH2T03Y","fs-skia-reconciliation",null,"Understand and work with the internal keyed VDOM diff over the lowered Control\u003C'msg> IR (feature 067) — its key-first-then-positional matching, the NodePatch\u002FChildOp operation set, the totality\u002Fdeterminism\u002Fidentity-at-rest\u002Fround-trip invariants, and the module's disposition (internal, property-tested, wired onto the live render path via RetainedRender in feature 091 and current through feature 103 — layout\u002Fbounds cache, injected-delta animation clock, visual-state cross-fade). Use when reading the diff invariants, extending the property tests, or working on the wired retained render path.","EHotwagner\u002FFS-Skia-UI","EHotwagner","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1645484?v=4","01M72S7CTBDPQDQHQJKKHY87K9","01M72S7CVFD0JN82RVX21NFEVC",2,"MIT","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ffs-skia-reconciliation\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: fs-skia-reconciliation\ndescription: Understand and work with the internal keyed VDOM diff over the lowered Control\u003C'msg> IR (feature 067) — its key-first-then-positional matching, the NodePatch\u002FChildOp operation set, the totality\u002Fdeterminism\u002Fidentity-at-rest\u002Fround-trip invariants, and the module's disposition (internal, property-tested, wired onto the live render path via RetainedRender in feature 091 and current through feature 103 — layout\u002Fbounds cache, injected-delta animation clock, visual-state cross-fade). Use when reading the diff invariants, extending the property tests, or working on the wired retained render path.\ncompatibility: F# net10.0; FS.Skia.UI.Controls package, `module internal Reconcile` — assembly-internal, no public-surface entry (zero baseline delta). Wired onto the live render path via `module internal RetainedRender` (feature 091).\nmetadata:\n  author: fs-skia-ui\n  source: specs\u002F067-keyed-reconciliation\u002Fplan.md\n---\n\n# fs-skia-reconciliation\n\nThe keyed **VDOM diff** over the lowered `Control\u003C'msg>` IR (feature 067). It computes a\nminimal patch from a previous control tree to a next one, so a future renderer can mutate in\nplace instead of rebuilding. This skill teaches the diff's invariants, key handling, and the\n`NodePatch`\u002F`ChildOp` operation set, **and** records the module's disposition — because the\nsingle most important fact about `Reconcile` is its disposition: as of feature **091** it is\n**wired onto the live render path** through `module internal RetainedRender` — the host loops no\nlonger rebuild the whole tree every frame — and that wired path has since carried the whole R1–R6\nlive-path roadmap (096–103). It remains `module internal` (no public-surface entry). This skill is\n**current through feature 103**, not frozen at 091.\n\n## Scope \u002F when to use\n\nUse this skill when:\n\n- You are reading `src\u002FControls\u002FReconcile.fsi`\u002F`.fs` and need the diff invariants without\n  reverse-engineering them from the implementation or source comments.\n- You are extending or auditing the Expecto\u002FFsCheck property tests in `tests\u002FControls.Tests`\n  that reach the module via `[\u003Cassembly: InternalsVisibleTo(\"Controls.Tests\")>]`.\n- You are reading or extending the **wired** render path (`module internal RetainedRender`,\n  feature 091) that consumes `Reconcile.diff` to drive partial, identity-preserving frames.\n\nDo **not** promote the module to public to \"document it via the surface baseline\" — both\n`Reconcile` and `RetainedRender` stay `module internal` by design (zero public-surface delta,\nSC-005 of 067; the adapter reaches them via `InternalsVisibleTo`). The keyed-reconciliation\nfollow-ups once framed as future work have **shipped**: the E3 visual-state style layer (093) and\nE4 focus\u002Ftraversal (094) landed, and the R1–R6 live-path roadmap (096–103) built the runtime\nvisual-state bridge, incremental re-layout, the live animation clock, and the visual-state\ncross-fade **on top of** this wired path. The \"## Live retained render path (096–103)\" section\nbelow is the current account; nothing in 096–103 re-wired the diff — they consume it.\n\n## Disposition (the single source for the module's status)\n\n`Reconcile` is:\n\n- **`module internal`** — assembly-internal accessibility, genuinely unreachable from package\n  consumers (mirrors the `module internal SceneRenderer` precedent). It is deliberately **not**\n  in the Controls capability `contracts:` list, so `ApiSurfaceGen`\u002F`PackageSurfaceCheck` emit\n  **no** public-surface entry — zero baseline delta.\n- **Property-tested** — the Expecto\u002FFsCheck suite reaches `diff`\u002F`apply` via\n  `[\u003Cassembly: InternalsVisibleTo(\"Controls.Tests\")>]`, **now on the wired path** as well\n  (`tests\u002FControls.Tests\u002FFeature091RetainedRenderTests.fs`: round-trip\u002Fdeterminism\u002Ftotality\u002F\n  identity-at-rest over `RetainedRender.step`, ≥1,000 cases).\n- **Wired on the render path (features 091–103)** — `diff` (and the `NodePatch`\u002F`ChildOp` set) is\n  consumed by `module internal RetainedRender`, which the interactive controls adapter\n  (`Controls.Elmish.runInteractiveApp`) drives every frame: it holds the previous lowered tree,\n  computes `Reconcile.diff prev next`, reuses the unchanged subtrees' cached render fragments\n  (O(changed-subtree)), carries each matched node's stable identity so per-control state survives\n  an unrelated re-render, and surfaces `Diagnostics` (e.g. `KeyCollision`) through the host\n  channel. Output is byte-for-byte identical to a full rebuild (golden parity). The R1–R6 roadmap\n  (096–103) layered the bounds cache, the injected-delta animation clock, and the visual-state\n  cross-fade onto this same `step` — see \"Live retained render path (096–103)\" above.\n- **The durable foundation** — the 067 invariants and tests still hold; 091 preserved every one\n  of them **on the live path** rather than only in isolation, and 096–103 kept them invariant while\n  building atop `RetainedRender.step` (the promoted 067 suite still asserts totality \u002F determinism \u002F\n  identity-at-rest \u002F round-trip on the wired path).\n\n**Where the wiring lives:** `module internal RetainedRender` (`src\u002FControls\u002FRetainedRender.fs(i)`)\nis the retained structure; `Controls.Elmish.runInteractiveApp` (`src\u002FControls.Elmish\u002F\nControlsElmish.fs`) holds it in its interpreter-edge ref state and produces each frame from it.\nThe generic `SkiaViewer` does not diff (its `View` yields an opaque `SceneNode`); the retained\ndiff lives at the controls adapter edge whose `View` the viewer repaint already calls. Both\n`Reconcile` and `RetainedRender` reach the adapter via `InternalsVisibleTo` and stay\n`module internal`. This Disposition is the **single source of truth** for the module's status.\n\n## Live retained render path (096–103)\n\n091 wired the diff onto the render path; the R1–R6 live-path roadmap (features 096–103) then grew\nthe retained structure that rides it. The disposition above is **current through 103**, not frozen\nat 091. What `module internal RetainedRender` (`src\u002FControls\u002FRetainedRender.fsi`) carries today:\n\n- **Per-frame layout\u002Fbounds cache (097, R2).** `RetainedRender\u003C'msg>` carries a `Layout:\n  LayoutResult` — the previous frame's full measure\u002Fbounds result. `RetainedRender.step` threads it\n  into `Layout.evaluateIncremental`, so an **unchanged subtree's bounds survive across frames and\n  are reused without re-measuring** (`init` seeds it with a full `evaluate`; each `step` advances it\n  to the incremental result). The `RenderFragment.Box` is the reuse key.\n- **Measured re-measure work (097\u002F101).** `WorkReductionRecord.RemeasuredNodeCount` reports the\n  **post-propagation re-measure dirty set** (`Invalidated` from `Layout.evaluateIncremental`):\n  strictly below `BaselineNodeCount` for a localized update, equal to it for a genuine whole-tree\n  relayout, `0` for an empty patch. It measures partial MEASURE work, distinct from the partial\n  PAINT counters (`RecomputedNodeCount = ChangedSubtreeBound + ShiftedNodeCount`).\n- **Per-identity animation clock (099, R4).** `RetainedUiState.Animation` is an `AnimationClock\n  {Anim; Elapsed; Target; From}` keyed by the stable `RetainedId`. It is advanced by an **injected**\n  host delta — `RetainedRender.advance delta clock` accumulates `Elapsed` (the sole time coordinate,\n  clamped to the duration; **no wall-clock**) — and **sampled on paint**. The live channel is the\n  opacity tween only; the single pinned default transition is 150 ms `EaseOut`\n  (`defaultTransitionDuration`). A settled (`clockActive = false`) or absent (`None`) clock is **not\n  sampled** ⇒ the identity paints **byte-identically to the static render at rest** (FR-004\u002FFR-005).\n- **Paint cross-fade is a two-snapshot composite (103, R6).** The visual-state cross-fade is **not**\n  a standalone `Color` tween (`Animation.applyAt` never recolors). `RetainedRender.sampleOnPaint\n  clock ownScene` composites the prior state's `From` snapshot fading OUT (`1→0`) **under** this\n  frame's own-scene fading IN (the clock's opacity tween) — two opacity-driven layers via the public\n  feature-073 `Animation.applyAt`. A region painted in both states shows a colour strictly between\n  the endpoints; `From = []` degenerates to a plain fade-in.\n- **Visual state stamped pre-reconcile (096, R1).** `ControlRuntime.applyRuntimeVisualState model\n  control` stamps each control's derived `VisualState` onto the lowered `Control\u003C'msg>` tree\n  **before** the diff runs (preserving a consumer-set non-`Normal` attribute, emitting nothing at\n  `Normal`). The per-frame transition trigger `RetainedRender.updateClockForState desired priorOwn\n  carried` then decides the clock: **START** a fade-in on a fresh change, **RETARGET** from the\n  current sampled value mid-flight (no snap), **advance-only** when unchanged, and **DROP** a settled\n  return-to-`Normal` clock so a resting identity stays byte-identical.\n\nNone of these re-wired the diff: every one consumes `Reconcile.diff` through `RetainedRender.step`\nand preserves the 067 invariants on the live path (see below). The live host that drives this —\nholding the `RetainedRender` in interpreter-edge ref state, advancing clocks on `Tick`, and stamping\nvisual state each frame — is documented by [[fs-skia-controls-host]].\n\n## Driven-library API and the diff contract\n\nThe whole module is `src\u002FControls\u002FReconcile.fsi` (read it for the authoritative signatures).\nTwo entry points, both pure:\n\n- `diff : prev:Control\u003C'msg> -> next:Control\u003C'msg> -> ReconcileResult\u003C'msg>` — pure, total,\n  deterministic. Never throws.\n- `apply : prev:Control\u003C'msg> -> patch:NodePatch\u003C'msg> -> Control\u003C'msg>` — applies a patch\n  produced by `diff prev _` back onto `prev`, reconstructing a tree structurally equal to\n  `next`. Exists to prove the round-trip invariant.\n\n**Key-first, then positional matching.** Children are matched by their `Key` first; the\nunkeyed residuals are then matched positionally. A `Kind` mismatch on a matched pair is **not**\na field update — it yields a whole-subtree `Replace`.\n\n**The operation set.**\n\n- `NodePatch\u003C'msg>` — one node's diff: `Keep` | `Replace of Control\u003C'msg>` | `Update of\n  UpdatePatch\u003C'msg>`. `Update` recurses into children.\n- `UpdatePatch\u003C'msg>` — a targeted in-place change for a matched same-`Kind` node:\n  `AttrChanges`, `ContentChange`, `AccessibilityChange`, `Children`.\n- `AttrChange\u003C'msg>` — `AttrSet of Attr\u003C'msg>` | `AttrRemoved of name`, matched by `Attr.Name`;\n  the emitted list is sorted by `Name` for deterministic output.\n- `FieldChange\u003C'a>` — `Unchanged` | `ChangedTo of 'a`; avoids `'a option option` when a\n  `Content`\u002F`Accessibility` field is set to `None`.\n- `ChildOp\u003C'msg>` — ordered child operation: `ChildKeep of index * patch` |\n  `ChildMove of fromIndex * toIndex * patch` | `ChildInsert of index * node` |\n  `ChildRemove of key * index`. **Index conventions:** `ChildKeep`\u002F`ChildMove` carry the\n  matched child's **prev**-list index as their source; the child's next-list position is its\n  ordinal among the non-`ChildRemove` ops (emitted in next order). `ChildInsert.index` and\n  `ChildMove.toIndex` are **next**-list positions; `ChildRemove.index` is the **prev**-list\n  position.\n\n**Diagnostics, never exceptions.** `ReconcileResult\u003C'msg>` carries `Patch` plus\n`Diagnostics : ControlDiagnostic list`. Duplicate keys among a node's children produce a\n`KeyCollision` diagnostic rather than a throw — the function stays total.\n\n**The invariants (what the property tests assert).**\n\n- **Totality** — `diff` is defined for every pair of trees; it never throws (collisions become\n  diagnostics).\n- **Determinism** — same `(prev, next)` ⇒ same result, including attribute ordering\n  (canonicalized by `Name`).\n- **Identity-at-rest** — `diff x x` produces a no-op patch (`Keep`, no child ops).\n- **Round-trip** — `apply prev (diff prev next).Patch` is structurally equal to `next`, up to\n  the attribute ordering the diff canonicalizes.\n\n## Runnable example — read the invariants, exercise the round-trip\n\n```fsharp\nopen FS.Skia.UI.Controls   \u002F\u002F Reconcile is internal; visible to Controls.Tests via InternalsVisibleTo\n\n\u002F\u002F Identity-at-rest: diffing a tree against itself is a no-op Keep.\nlet result = Reconcile.diff tree tree\nmatch result.Patch with\n| Reconcile.NodePatch.Keep -> ()        \u002F\u002F expected\n| _ -> failwith \"identity-at-rest violated\"\nresult.Diagnostics |> List.isEmpty      \u002F\u002F true for well-keyed input\n```\n\n```fsharp\n\u002F\u002F Round-trip: applying the patch reconstructs `next` structurally (up to attr ordering).\nlet r = Reconcile.diff prev next\nlet rebuilt = Reconcile.apply prev r.Patch\n\u002F\u002F rebuilt ≡ next  (structural equality, attributes canonicalized by Name)\n\n\u002F\u002F A Kind mismatch on a matched pair is a whole-subtree Replace, not an Update.\nmatch (Reconcile.diff (stackOf [..]) (buttonOf [..])).Patch with\n| Reconcile.NodePatch.Replace _ -> ()   \u002F\u002F expected — different Kind\n| _ -> failwith \"Kind-mismatch should Replace\"\n```\n\nThe property tests live in `tests\u002FControls.Tests`; run them with\n`dotnet test tests\u002FControls.Tests\u002FControls.Tests.fsproj` (they reach the internals via\n`InternalsVisibleTo`). The module routes to the inner-loop tier — `.\u002Ffake.sh build -t Dev`\ncovers a source-internal edit; it has no public `.fsi` surface to escalate.\n\n## Persistent problems\n\nWhen the diff or its round-trip will not reconcile after reasonable in-repo attempts,\n**official online docs first** (the F#\u002F.NET docs; React's reconciliation\u002Fkeys notes are the\ncanonical prior art for keyed-VDOM diffing), then community sources (forums, issue trackers,\nchangelogs). Record findings and resolving links in `specs\u002F\u003Cfeature>\u002Ffeedback\u002F` and, for\ndurable lessons, in this skill's **Sources** line. Offline, record \"research blocked — \u003Cwhy>\"\nrather than hard-failing the phase.\n\n## Related\n\n- [[fs-skia-controls-host]] — the maintainer-facing `Controls.Elmish` interactive host that drives\n  this retained structure each frame (holds it in interpreter-edge ref state, advances the animation\n  clocks on `Tick`, stamps visual state pre-reconcile).\n- [[fsharp-graph-algorithms]] — the keyed matching and ordered child-op emission lean on the\n  same DAG\u002Ftopological reasoning that skill teaches.\n- [[fs-skia-typed-controls]] authors the typed front door that lowers to the `Control\u003C'msg>`\n  IR this diff operates over.\n- [[fsharp-build-orchestration]] — the property-test harness (Expecto + FsCheck) that proves\n  the totality\u002Fdeterminism\u002Fround-trip invariants.\n\n## Sources \u002F links\n\n- Feature 067 plan: `specs\u002F067-keyed-reconciliation\u002Fplan.md`; signatures in\n  `src\u002FControls\u002FReconcile.fsi`.\n- React reconciliation & keys (keyed-VDOM-diff prior art):\n  https:\u002F\u002Freact.dev\u002Flearn\u002Fpreserving-and-resetting-state\n- F#\u002F.NET docs: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fdotnet\u002Ffsharp\u002F\n","# fs-skia-reconciliation\n\nThe keyed **VDOM diff** over the lowered `Control\u003C'msg>` IR (feature 067). It computes a\nminimal patch from a previous control tree to a next one, so a future renderer can mutate in\nplace instead of rebuilding. This skill teaches the diff's invariants, key handling, and the\n`NodePatch`\u002F`ChildOp` operation set, **and** records the module's disposition — because the\nsingle most important fact about `Reconcile` is its disposition: as of feature **091** it is\n**wired onto the live render path** through `module internal RetainedRender` — the host loops no\nlonger rebuild the whole tree every frame — and that wired path has since carried the whole R1–R6\nlive-path roadmap (096–103). It remains `module internal` (no public-surface entry). This skill is\n**current through feature 103**, not frozen at 091.\n\n## Scope \u002F when to use\n\nUse this skill when:\n\n- You are reading `src\u002FControls\u002FReconcile.fsi`\u002F`.fs` and need the diff invariants without\n  reverse-engineering them from the implementation or source comments.\n- You are extending or auditing the Expecto\u002FFsCheck property tests in `tests\u002FControls.Tests`\n  that reach the module via `[\u003Cassembly: InternalsVisibleTo(\"Controls.Tests\")>]`.\n- You are reading or extending the **wired** render path (`module internal RetainedRender`,\n  feature 091) that consumes `Reconcile.diff` to drive partial, identity-preserving frames.\n\nDo **not** promote the module to public to \"document it via the surface baseline\" — both\n`Reconcile` and `RetainedRender` stay `module internal` by design (zero public-surface delta,\nSC-005 of 067; the adapter reaches them via `InternalsVisibleTo`). The keyed-reconciliation\nfollow-ups once framed as future work have **shipped**: the E3 visual-state style layer (093) and\nE4 focus\u002Ftraversal (094) landed, and the R1–R6 live-path roadmap (096–103) built the runtime\nvisual-state bridge, incremental re-layout, the live animation clock, and the visual-state\ncross-fade **on top of** this wired path. The \"## Live retained render path (096–103)\" section\nbelow is the current account; nothing in 096–103 re-wired the diff — they consume it.\n\n## Disposition (the single source for the module's status)\n\n`Reconcile` is:\n\n- **`module internal`** — assembly-internal accessibility, genuinely unreachable from package\n  consumers (mirrors the `module internal SceneRenderer` precedent). It is deliberately **not**\n  in the Controls capability `contracts:` list, so `ApiSurfaceGen`\u002F`PackageSurfaceCheck` emit\n  **no** public-surface entry — zero baseline delta.\n- **Property-tested** — the Expecto\u002FFsCheck suite reaches `diff`\u002F`apply` via\n  `[\u003Cassembly: InternalsVisibleTo(\"Controls.Tests\")>]`, **now on the wired path** as well\n  (`tests\u002FControls.Tests\u002FFeature091RetainedRenderTests.fs`: round-trip\u002Fdeterminism\u002Ftotality\u002F\n  identity-at-rest over `RetainedRender.step`, ≥1,000 cases).\n- **Wired on the render path (features 091–103)** — `diff` (and the `NodePatch`\u002F`ChildOp` set) is\n  consumed by `module internal RetainedRender`, which the interactive controls adapter\n  (`Controls.Elmish.runInteractiveApp`) drives every frame: it holds the previous lowered tree,\n  computes `Reconcile.diff prev next`, reuses the unchanged subtrees' cached render fragments\n  (O(changed-subtree)), carries each matched node's stable identity so per-control state survives\n  an unrelated re-render, and surfaces `Diagnostics` (e.g. `KeyCollision`) through the host\n  channel. Output is byte-for-byte identical to a full rebuild (golden parity). The R1–R6 roadmap\n  (096–103) layered the bounds cache, the injected-delta animation clock, and the visual-state\n  cross-fade onto this same `step` — see \"Live retained render path (096–103)\" above.\n- **The durable foundation** — the 067 invariants and tests still hold; 091 preserved every one\n  of them **on the live path** rather than only in isolation, and 096–103 kept them invariant while\n  building atop `RetainedRender.step` (the promoted 067 suite still asserts totality \u002F determinism \u002F\n  identity-at-rest \u002F round-trip on the wired path).\n\n**Where the wiring lives:** `module internal RetainedRender` (`src\u002FControls\u002FRetainedRender.fs(i)`)\nis the retained structure; `Controls.Elmish.runInteractiveApp` (`src\u002FControls.Elmish\u002F\nControlsElmish.fs`) holds it in its interpreter-edge ref state and produces each frame from it.\nThe generic `SkiaViewer` does not diff (its `View` yields an opaque `SceneNode`); the retained\ndiff lives at the controls adapter edge whose `View` the viewer repaint already calls. Both\n`Reconcile` and `RetainedRender` reach the adapter via `InternalsVisibleTo` and stay\n`module internal`. This Disposition is the **single source of truth** for the module's status.\n\n## Live retained render path (096–103)\n\n091 wired the diff onto the render path; the R1–R6 live-path roadmap (features 096–103) then grew\nthe retained structure that rides it. The disposition above is **current through 103**, not frozen\nat 091. What `module internal RetainedRender` (`src\u002FControls\u002FRetainedRender.fsi`) carries today:\n\n- **Per-frame layout\u002Fbounds cache (097, R2).** `RetainedRender\u003C'msg>` carries a `Layout:\n  LayoutResult` — the previous frame's full measure\u002Fbounds result. `RetainedRender.step` threads it\n  into `Layout.evaluateIncremental`, so an **unchanged subtree's bounds survive across frames and\n  are reused without re-measuring** (`init` seeds it with a full `evaluate`; each `step` advances it\n  to the incremental result). The `RenderFragment.Box` is the reuse key.\n- **Measured re-measure work (097\u002F101).** `WorkReductionRecord.RemeasuredNodeCount` reports the\n  **post-propagation re-measure dirty set** (`Invalidated` from `Layout.evaluateIncremental`):\n  strictly below `BaselineNodeCount` for a localized update, equal to it for a genuine whole-tree\n  relayout, `0` for an empty patch. It measures partial MEASURE work, distinct from the partial\n  PAINT counters (`RecomputedNodeCount = ChangedSubtreeBound + ShiftedNodeCount`).\n- **Per-identity animation clock (099, R4).** `RetainedUiState.Animation` is an `AnimationClock\n  {Anim; Elapsed; Target; From}` keyed by the stable `RetainedId`. It is advanced by an **injected**\n  host delta — `RetainedRender.advance delta clock` accumulates `Elapsed` (the sole time coordinate,\n  clamped to the duration; **no wall-clock**) — and **sampled on paint**. The live channel is the\n  opacity tween only; the single pinned default transition is 150 ms `EaseOut`\n  (`defaultTransitionDuration`). A settled (`clockActive = false`) or absent (`None`) clock is **not\n  sampled** ⇒ the identity paints **byte-identically to the static render at rest** (FR-004\u002FFR-005).\n- **Paint cross-fade is a two-snapshot composite (103, R6).** The visual-state cross-fade is **not**\n  a standalone `Color` tween (`Animation.applyAt` never recolors). `RetainedRender.sampleOnPaint\n  clock ownScene` composites the prior state's `From` snapshot fading OUT (`1→0`) **under** this\n  frame's own-scene fading IN (the clock's opacity tween) — two opacity-driven layers via the public\n  feature-073 `Animation.applyAt`. A region painted in both states shows a colour strictly between\n  the endpoints; `From = []` degenerates to a plain fade-in.\n- **Visual state stamped pre-reconcile (096, R1).** `ControlRuntime.applyRuntimeVisualState model\n  control` stamps each control's derived `VisualState` onto the lowered `Control\u003C'msg>` tree\n  **before** the diff runs (preserving a consumer-set non-`Normal` attribute, emitting nothing at\n  `Normal`). The per-frame transition trigger `RetainedRender.updateClockForState desired priorOwn\n  carried` then decides the clock: **START** a fade-in on a fresh change, **RETARGET** from the\n  current sampled value mid-flight (no snap), **advance-only** when unchanged, and **DROP** a settled\n  return-to-`Normal` clock so a resting identity stays byte-identical.\n\nNone of these re-wired the diff: every one consumes `Reconcile.diff` through `RetainedRender.step`\nand preserves the 067 invariants on the live path (see below). The live host that drives this —\nholding the `RetainedRender` in interpreter-edge ref state, advancing clocks on `Tick`, and stamping\nvisual state each frame — is documented by [[fs-skia-controls-host]].\n\n## Driven-library API and the diff contract\n\nThe whole module is `src\u002FControls\u002FReconcile.fsi` (read it for the authoritative signatures).\nTwo entry points, both pure:\n\n- `diff : prev:Control\u003C'msg> -> next:Control\u003C'msg> -> ReconcileResult\u003C'msg>` — pure, total,\n  deterministic. Never throws.\n- `apply : prev:Control\u003C'msg> -> patch:NodePatch\u003C'msg> -> Control\u003C'msg>` — applies a patch\n  produced by `diff prev _` back onto `prev`, reconstructing a tree structurally equal to\n  `next`. Exists to prove the round-trip invariant.\n\n**Key-first, then positional matching.** Children are matched by their `Key` first; the\nunkeyed residuals are then matched positionally. A `Kind` mismatch on a matched pair is **not**\na field update — it yields a whole-subtree `Replace`.\n\n**The operation set.**\n\n- `NodePatch\u003C'msg>` — one node's diff: `Keep` | `Replace of Control\u003C'msg>` | `Update of\n  UpdatePatch\u003C'msg>`. `Update` recurses into children.\n- `UpdatePatch\u003C'msg>` — a targeted in-place change for a matched same-`Kind` node:\n  `AttrChanges`, `ContentChange`, `AccessibilityChange`, `Children`.\n- `AttrChange\u003C'msg>` — `AttrSet of Attr\u003C'msg>` | `AttrRemoved of name`, matched by `Attr.Name`;\n  the emitted list is sorted by `Name` for deterministic output.\n- `FieldChange\u003C'a>` — `Unchanged` | `ChangedTo of 'a`; avoids `'a option option` when a\n  `Content`\u002F`Accessibility` field is set to `None`.\n- `ChildOp\u003C'msg>` — ordered child operation: `ChildKeep of index * patch` |\n  `ChildMove of fromIndex * toIndex * patch` | `ChildInsert of index * node` |\n  `ChildRemove of key * index`. **Index conventions:** `ChildKeep`\u002F`ChildMove` carry the\n  matched child's **prev**-list index as their source; the child's next-list position is its\n  ordinal among the non-`ChildRemove` ops (emitted in next order). `ChildInsert.index` and\n  `ChildMove.toIndex` are **next**-list positions; `ChildRemove.index` is the **prev**-list\n  position.\n\n**Diagnostics, never exceptions.** `ReconcileResult\u003C'msg>` carries `Patch` plus\n`Diagnostics : ControlDiagnostic list`. Duplicate keys among a node's children produce a\n`KeyCollision` diagnostic rather than a throw — the function stays total.\n\n**The invariants (what the property tests assert).**\n\n- **Totality** — `diff` is defined for every pair of trees; it never throws (collisions become\n  diagnostics).\n- **Determinism** — same `(prev, next)` ⇒ same result, including attribute ordering\n  (canonicalized by `Name`).\n- **Identity-at-rest** — `diff x x` produces a no-op patch (`Keep`, no child ops).\n- **Round-trip** — `apply prev (diff prev next).Patch` is structurally equal to `next`, up to\n  the attribute ordering the diff canonicalizes.\n\n## Runnable example — read the invariants, exercise the round-trip\n\n```fsharp\nopen FS.Skia.UI.Controls   \u002F\u002F Reconcile is internal; visible to Controls.Tests via InternalsVisibleTo\n\n\u002F\u002F Identity-at-rest: diffing a tree against itself is a no-op Keep.\nlet result = Reconcile.diff tree tree\nmatch result.Patch with\n| Reconcile.NodePatch.Keep -> ()        \u002F\u002F expected\n| _ -> failwith \"identity-at-rest violated\"\nresult.Diagnostics |> List.isEmpty      \u002F\u002F true for well-keyed input\n```\n\n```fsharp\n\u002F\u002F Round-trip: applying the patch reconstructs `next` structurally (up to attr ordering).\nlet r = Reconcile.diff prev next\nlet rebuilt = Reconcile.apply prev r.Patch\n\u002F\u002F rebuilt ≡ next  (structural equality, attributes canonicalized by Name)\n\n\u002F\u002F A Kind mismatch on a matched pair is a whole-subtree Replace, not an Update.\nmatch (Reconcile.diff (stackOf [..]) (buttonOf [..])).Patch with\n| Reconcile.NodePatch.Replace _ -> ()   \u002F\u002F expected — different Kind\n| _ -> failwith \"Kind-mismatch should Replace\"\n```\n\nThe property tests live in `tests\u002FControls.Tests`; run them with\n`dotnet test tests\u002FControls.Tests\u002FControls.Tests.fsproj` (they reach the internals via\n`InternalsVisibleTo`). The module routes to the inner-loop tier — `.\u002Ffake.sh build -t Dev`\ncovers a source-internal edit; it has no public `.fsi` surface to escalate.\n\n## Persistent problems\n\nWhen the diff or its round-trip will not reconcile after reasonable in-repo attempts,\n**official online docs first** (the F#\u002F.NET docs; React's reconciliation\u002Fkeys notes are the\ncanonical prior art for keyed-VDOM diffing), then community sources (forums, issue trackers,\nchangelogs). Record findings and resolving links in `specs\u002F\u003Cfeature>\u002Ffeedback\u002F` and, for\ndurable lessons, in this skill's **Sources** line. Offline, record \"research blocked — \u003Cwhy>\"\nrather than hard-failing the phase.\n\n## Related\n\n- [[fs-skia-controls-host]] — the maintainer-facing `Controls.Elmish` interactive host that drives\n  this retained structure each frame (holds it in interpreter-edge ref state, advances the animation\n  clocks on `Tick`, stamps visual state pre-reconcile).\n- [[fsharp-graph-algorithms]] — the keyed matching and ordered child-op emission lean on the\n  same DAG\u002Ftopological reasoning that skill teaches.\n- [[fs-skia-typed-controls]] authors the typed front door that lowers to the `Control\u003C'msg>`\n  IR this diff operates over.\n- [[fsharp-build-orchestration]] — the property-test harness (Expecto + FsCheck) that proves\n  the totality\u002Fdeterminism\u002Fround-trip invariants.\n\n## Sources \u002F links\n\n- Feature 067 plan: `specs\u002F067-keyed-reconciliation\u002Fplan.md`; signatures in\n  `src\u002FControls\u002FReconcile.fsi`.\n- React reconciliation & keys (keyed-VDOM-diff prior art):\n  https:\u002F\u002Freact.dev\u002Flearn\u002Fpreserving-and-resetting-state\n- F#\u002F.NET docs: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fdotnet\u002Ffsharp\u002F\n",{"name":5,"metadata":23,"description":7,"compatibility":26},{"author":24,"source":25},"fs-skia-ui","specs\u002F067-keyed-reconciliation\u002Fplan.md","F# net10.0; FS.Skia.UI.Controls package, `module internal Reconcile` — assembly-internal, no public-surface entry (zero baseline delta). Wired onto the live render path via `module internal RetainedRender` (feature 091).","main","f943406829a9218b2882e09eb88d4ddb539c5e72",".claude\u002Fskills\u002Ffs-skia-reconciliation",0,"https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI","https:\u002F\u002Fgithub.com\u002FEHotwagner","2026-06-16 16:16:52",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add EHotwagner\u002FFS-Skia-UI --skill fs-skia-reconciliation",{"tool":40,"command":41},"bunx","bunx skills add EHotwagner\u002FFS-Skia-UI --skill fs-skia-reconciliation",{"tool":43,"command":44},"pnpm","pnpm dlx skills add EHotwagner\u002FFS-Skia-UI --skill fs-skia-reconciliation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ffs-skia-reconciliation\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":18},"01M72SGYR4T02T1HTS175E0V86","fs-skia-ui-widgets","Generated product guidance for Skia-rendered FS.Skia.UI Controls, rich text, chart controls, graph controls, DataGrid, and custom wrappers.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-ui-widgets\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":18},"01M72SGVZJR1B117QK7TCC6E0J","fs-skia-testing","Assert generated-product expectations and evidence in a governed FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-testing\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":18},"01M72SGTC5HZYEVVVZT4X51AZ3","fs-skia-skiaviewer","Wire a generated FS.Skia.UI product to the desktop viewer host.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-skiaviewer\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":18},"01M72SGS47RPYPC9JTC39CC6EF","fs-skia-scene","Build pure scene descriptions in a generated FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-scene\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":18},"01M72SGQF4G76C4NGSF69KZRRF","fs-skia-keyboard-input","Map keyboard input to product commands in a generated FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-keyboard-input\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":18},"01M72SGNJP3PMSS2VRP98G7Z42","fs-skia-elmish","Drive a generated FS.Skia.UI product through the pure Elmish adapter.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-elmish\u002FSKILL.md",[],[]]