perf: Views engine render optimizations — warm 99.99% faster, cold 10% faster

[johnml1135]

Summary

This PR is now focused on Views rendering performance and the framework needed to verify render output and benchmark render behavior.

The branch speeds up warm render paths by avoiding unnecessary reconstruct/layout work when the root box is already in a reusable state. It adds explicit root-box reconstruct state, tighter SimpleRootSite.RefreshDisplay() behavior, cheaper root-box data-access swaps, and refresh-policy coverage for XML/browse views. DataTree and related controls also get lifecycle/layout guards so render work is skipped when the view is disposed or not in a valid layout state.

For cold and repeated native rendering paths, the Views engine now caches expensive render resources and avoids repeated hot-path work. The native changes include font-handle and color-state caches, layout/cache helpers, render tracing hooks, and targeted updates in text, graphics, root-box, layout-stream, and Uniscribe paths. The intent is to reduce repeated GDI/font/color setup, avoid redundant normalization/render setup, and keep layout/reconstruct work proportional to actual state changes.

The PR also adds a render verification layer so these optimizations can be reviewed safely:

• RenderVerification and RenderTestInfrastructure projects for view capture, snapshot verification, scenario generation, benchmark comparison, report writing, environment validation, diagnostics toggling, and trace parsing.
• Real-data render scenarios for lexical and scripture views, including Verify image baselines.
• DataTree render baselines and timing scenario support for production-like nested cases.
• Render timing/trace parser tests and a VS Code task for RenderBaselineTests.
• OpenSpec artifacts documenting the render-speedup benchmark design, tasks, schemas, and migration notes.

Non-render cleanup and branch-surgery residue have been split out into #865 so this PR can stay about render speed and render/image assessment. Stale rebase residue identified during review was removed rather than preserved in either PR.

Validation

• shell: Build passed on the render-only branch.
• Test: RenderBaselineTests passed after correcting the task invocation: 8 total, 8 passed.
• Full shell: Test passed before the final split when the non-render cleanup was still present.
• After the final split, the render-only branch's full suite has one unrelated ToneParsInvokerTest absolute-path comparison failure; that deterministic test normalization is isolated in chore: separate non-render cleanup #865, where the full suite passes: 4150 total, 4090 passed, 60 skipped.

Related PR

• chore: separate non-render cleanup #865 contains the non-render cleanup extracted from this branch.

---

This change is 

[Copilot]

Pull request overview

Performance-focused updates introduce render verification/benchmark infrastructure and targeted optimizations in the DetailControls/DataTree rendering path to reduce redundant work and support pixel-perfect render validation.

Changes:

• Added RenderVerification infrastructure (environment validation, diagnostics/trace toggling, benchmark result models, reporting & comparison utilities).
• Optimized DataTree/Slice construction, layout, painting, and visibility paths to avoid repeated O(N) work.
• Added/updated test harness assets (layouts/parts, new diagnostics tests, VS Code tasks) and snapshot testing support.

Reviewed changes

Copilot reviewed 68 out of 153 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Src/Common/RenderVerification/RenderModels.cs	Adds shared models for scenarios and timing results used by render verification/benchmarks.
Src/Common/RenderVerification/RenderEnvironmentValidator.cs	Captures environment details and produces a hash/diff for deterministic snapshot comparisons.
Src/Common/RenderVerification/RenderDiagnosticsToggle.cs	Adds a toggle for diagnostics/trace output with file-backed flags and a trace listener.
Src/Common/RenderVerification/RenderBenchmarkResults.cs	Defines JSON-serializable benchmark run/result structures and flags loading.
Src/Common/RenderVerification/RenderBenchmarkReportWriter.cs	Writes JSON + Markdown summary reports and recommendations for benchmark runs.
Src/Common/RenderVerification/RenderBenchmarkComparer.cs	Compares runs to detect regressions/improvements and generates a summary.
Src/Common/RenderVerification/CompositeViewCapture.cs	Implements two-pass DataTree capture with Views content overlay for pixel-perfect snapshots.
Src/Common/FieldWorks/FieldWorks.Diagnostics.dev.config	Adds a new trace switch for Views render timing.
Src/Common/Controls/XMLViews/XMLViewsTests/XmlBrowseViewBaseTests.cs	Updates test stub interface to include NeedsReconstruct.
Src/Common/Controls/DetailControls/VectorReferenceView.cs	Avoids drawing a trailing separator bar after the last item.
Src/Common/Controls/DetailControls/Slice.cs	Adds cached XML attribute parsing + width fast-path + DataTree method call updates.
Src/Common/Controls/DetailControls/PossibilityVectorReferenceView.cs	Avoids drawing a trailing separator bar after the last item.
Src/Common/Controls/DetailControls/HwndDiagnostics.cs	Adds helper methods to read USER/GDI handle counts for diagnostics/tests.
Src/Common/Controls/DetailControls/DetailControlsTests/TestResult.xml	Adds a test runner output artifact (currently shows a failed/invalid run).
Src/Common/Controls/DetailControls/DetailControlsTests/TestParts.xml	Extends test parts inventory to include senses sequences and collapsible slices.
Src/Common/Controls/DetailControls/DetailControlsTests/Test.fwlayout	Updates test layouts to include CitationForm and senses parts/layouts.
Src/Common/Controls/DetailControls/DetailControlsTests/DetailControlsTests.csproj	Adds snapshot/JSON deps and references RenderVerification project.
Src/Common/Controls/DetailControls/DetailControlsTests/DataTreeTests.cs	Updates expected template XML string for modified layout composition.
Src/Common/Controls/DetailControls/DetailControlsTests/DataTreeHwndCountTest.cs	Adds baseline diagnostics tests for handle growth and slice install count.
Src/Common/Controls/DetailControls/DataTree.cs	Adds multiple layout/paint/visibility optimizations and diagnostics counters.
Directory.Packages.props	Adds central package version for Verify.
AGENTS.md	Adds note about external dependency repository (liblcm).
.vscode/tasks.json	Adds tasks for render baseline tests and building tests via repo script.
.vscode/settings.json	Allows the new “Build Tests” task as an approved VS Code task.
.github/skills/openspec-verify-change/SKILL.md	Updates generatedBy metadata version.
.github/skills/openspec-sync-specs/SKILL.md	Updates generatedBy metadata version.
.github/skills/openspec-onboard/SKILL.md	Updates onboarding workflow text/commands and cross-platform command notes.
.github/skills/openspec-new-change/SKILL.md	Updates generatedBy metadata version.
.github/skills/openspec-ff-change/SKILL.md	Updates generatedBy metadata version.
.github/skills/openspec-explore/SKILL.md	Updates explore-mode wording around “proposal” vs other workflows.
.github/skills/openspec-continue-change/SKILL.md	Updates generatedBy metadata version.
.github/skills/openspec-bulk-archive-change/SKILL.md	Updates text and generatedBy metadata version.
.github/skills/openspec-archive-change/SKILL.md	Updates guidance to invoke the sync skill via Task tool.
.github/skills/openspec-apply-change/SKILL.md	Updates generatedBy metadata version.
.github/prompts/opsx-onboard.prompt.md	Mirrors onboarding prompt updates (CLI install check, command list).
.github/prompts/opsx-ff.prompt.md	Clarifies template usage vs context/rules constraints.
.github/prompts/opsx-explore.prompt.md	Mirrors explore prompt updates (“proposal” wording).
.github/prompts/opsx-bulk-archive.prompt.md	Mirrors bulk-archive prompt copy update.
.github/prompts/opsx-archive.prompt.md	Mirrors archive prompt sync invocation update.
.github/instructions/csharp.instructions.md	Adds C# instructions file (currently specifies “latest C# / C# 14” guidance).
.gitattributes	Marks Verify snapshot PNG extensions as binary.
.GitHub/skills/render-testing/SKILL.md	Adds a render-testing skill doc with build/test/run instructions and baseline workflow.
.GitHub/skills/code-review-skill-main/scripts/pr-analyzer.py	Adds a Python tool to analyze diffs and estimate PR review complexity.
.GitHub/skills/code-review-skill-main/reference/typescript.md	Adds TypeScript review reference documentation.
.GitHub/skills/code-review-skill-main/reference/security-review-guide.md	Adds security review reference documentation.
.GitHub/skills/code-review-skill-main/reference/java.md	Adds Java review reference documentation.
.GitHub/skills/code-review-skill-main/reference/cpp.md	Adds C++ review reference documentation.
.GitHub/skills/code-review-skill-main/reference/code-review-best-practices.md	Adds code review best practices reference documentation.
.GitHub/skills/code-review-skill-main/reference/c.md	Adds C review reference documentation.
.GitHub/skills/code-review-skill-main/assets/review-checklist.md	Adds a condensed review checklist asset.
.GitHub/skills/code-review-skill-main/assets/pr-review-template.md	Adds a PR review template asset.
.GitHub/skills/code-review-skill-main/SKILL.md	Adds a top-level code review skill description/index.
.GitHub/skills/code-review-skill-main/README.md	Adds documentation for the code-review skill bundle.
.GitHub/skills/code-review-skill-main/LICENSE	Adds license file for the bundled code-review skill content.
.GitHub/skills/code-review-skill-main/CONTRIBUTING.md	Adds contribution guidelines for the bundled code-review skill content.
.GitHub/skills/code-review-skill-main/.gitignore	Adds gitignore for the bundled code-review skill content.

Comments suppressed due to low confidence (1)

.GitHub/skills/render-testing/SKILL.md:1

• This doc hardcodes a user-specific NUnit console path and recommends dotnet build for a .NET Framework workflow. For portability and alignment with repo build guidance, prefer .\build.ps1 / .\test.ps1 (and avoid assuming C:\\Users\\johnm\\... exists). Also consider avoiding or clearly calling out commands with pipes/redirection in docs, since the repo guidance prefers wrapper scripts for piped commands.

---

[github-actions]

NUnit Tests

    1 files  ± 0      1 suites  ±0   11m 23s ⏱️ + 4m 25s
4 188 tests +86  4 117 ✅ +86  71 💤 ±0  0 ❌ ±0 
4 197 runs  +86  4 126 ✅ +86  71 💤 ±0  0 ❌ ±0 

Results for commit fbdc4d2. ± Comparison against base commit d4fd1ec.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Copilot reviewed 93 out of 178 changed files in this pull request and generated 8 comments.

[johnml1135]

Update after the force-push:

• Pushed commit: c2cfe529e
• Restored the missing thin gray DataTree separator lines without regressing the tall-image capture fix.
• CompositeViewCapture now composites slice-local chrome for tall trees, then repaints the parent-drawn DataTree separators, then overlays root-box content.
• Refreshed the affected DataTree and RootSite verified render baselines to match the corrected deterministic output.

Verification:

• Focused DataTree render snapshots: 8 passed, 0 failed
• Full suite via ./test.ps1 -NoBuild: 4560 total, 4484 passed, 76 skipped, 0 failed
• CI: Whitespace check: no problems found

This should leave the PR in a current, reviewable state after the rebase/force-push.

[jasonleenaylor]

@jasonleenaylor partially reviewed 15 files and all commit messages, and made 3 comments.
Reviewable status: 6 of 441 files reviewed, all discussions resolved.

---

Src/Common/Controls/DetailControls/PossibilityVectorReferenceView.cs line 325 at r1 (raw file):

				vwenv.AddObj(da.get_VecItem(hvo, tag, i), this, VectorReferenceView.kfragTargetObj);
				// Only add separator between items, not after the last one.
				if (i < count - 1)

(Devin saw this too, this does not seem to be related to performance and is just an arbitrary change in behavior unless I see something else adding a separator bar elsewhere 'more efficiently')

---

Src/Common/Controls/DetailControls/VectorReferenceView.cs line 864 at r1 (raw file):

				// A trailing separator draws an unwanted grey bar after the
				// final item (e.g. after "Main Dictionary").
				if (i < count - 1)

Same comment here as in PossibilityReference

---

Src/views/VwRootBox.cpp line 2516 at r1 (raw file):

	ChkComArgPtr(pfNeeds);

	*pfNeeds = m_fNeedsReconstruct ? true : false;

*pfNeeds = m_fNeedsReconstruct;

Code quote:

*pfNeeds = m_fNeedsReconstruct ? true : false;