FieldWorks Semantic Render Parity

Shared definitions (Path 3 bundle, evidence types, artifact naming) live in ../fieldworks-winforms-to-avalonia-migration/references/parity-evidence.md. This skill covers how to build and review the snapshots themselves.

Role in the migration before/after pipeline

This skill owns the "after" half of the migration-doc before/after pairs (see fieldworks-winapp; for where Docs/migration/ lives, see the hub skill's "Phase-1 Landing Strategy"). The before is the legacy WinForms truth PNG (captured by the fieldworks-winapp launch-per-tool script / dialog harness); the after is the Avalonia view rendered from the same seeded data by its visual test in FwAvaloniaDialogsTests/FwAvaloniaTests, saved as <name>-after.png in the doc's images/. Use the same render/visual evidence type defined here (not a one-off screenshot) so the "after" doubles as the parity baseline, and both PNGs attach to the conversion's JIRA ticket. When the two should match, the semantic snapshot — not the side-by-side image — is the authoritative parity check; the images are the human-facing summary.

Snapshot Discipline

Semantic snapshots preserve behaviorally meaningful identity and omit incidental layout noise. The snapshot is the anchor artifact of a parity bundle: when visual evidence diverges, the snapshot explains whether the cause is the XML import, slice filtering, editor registry, or rendering.

Include

• Stable node ID and source layout/part identity.
• Which route produced the artifact (Avalonia, legacy fallback, or blocked state) when a scenario can run through multiple hosts.
• Object/class binding, field/flid binding, editor kind, writing-system metadata, visibility, ghost state, expansion, focus order, localization key, and accessibility identity.
• Unsupported construct diagnostics with enough path context to fix the source layout.

Exclude Or Normalize

• Pixel bounds, transient generated names, timestamps, machine paths, culture-dependent ordering, and realized-control counts unless the test explicitly owns them.

Canonical Examples

• IR model and snapshot projection: Src/Common/FwAvalonia/ViewDefinition/ViewDefinitionModel.cs
• Snapshot/parity tests: Src/Common/FwAvalonia/FwAvaloniaTests/DetailViewingParityTests.cs, ViewDefinitionTests.cs, CanonicalJsonTests.cs, Path3BundleTests.cs
• Import coverage tracking: LayoutImportCoverageTests.cs and Src/Common/FwAvalonia/ViewDefinition/LayoutImportCoverage.cs
• Visual/density evidence: VisualParityAndDensityTests.cs

Render Evidence

• Pixel/render tests need deterministic fixtures, clear thresholds, and failure artifacts reviewers can inspect (classified failure summary, not a raw diff image).
• A semantic snapshot is not a substitute for visual/render parity when typography, density, wrapping, or native rendering seams are under review — and vice versa. One evidence type per axis; see parity-evidence.md §2.
• Control-level Avalonia visual evidence may come from Avalonia.Headless rendered frames when the scenario is explicitly control-scoped; desktop workflow/accessibility claims still need live-window evidence.

Review Red Flags

• A preview-only or lossy route presented as if it proved product parity.
• Placeholder metadata presented as real binding or writing-system parity.
• Snapshot tests updating large JSON blobs without a small behavioral explanation of what changed and why.
• Cache invalidation tests that depend on sleeps or filesystem timestamp luck.
• A new layout construct silently dropped by the importer instead of producing a diagnostic node and a coverage-tracking entry.

Handoff

State whether evidence is semantic, visual, accessibility/workflow, or performance parity, and identify remaining unproven axes. When a Path 3 bundle is used, name each artifact and which evidence type it proves.

Keep This Skill Current

When snapshot fields, normalization rules, or fixture patterns change, or a new artifact type joins the bundle, update this skill and parity-evidence.md together in the same PR; record durable lessons via ../fieldworks-winforms-to-avalonia-migration/references/lessons-learned.md.