chore: Documentation OverHaul + Auto-Captured Images/webp

[wallstop]

We need to upgrade our user-facing documentation to really describe what this project is, along with current screenshots and gifs about how to use this project.

This should be done via both our markdown (README) and github pages (doesn't exist yet).

We should take inspiration from sibling repos, such as https://github.com/ambiguous-interactive/unity-helpers. github.com/ambiguous-interactive/DxMessaging for styling, presentation, and automation.

As part of agentic/local tooling, we should ensure that we have automated ways of capturing editor state/screenshots, so that we can reliably update/generate content for the docs.

Copy should describe why the project exists, how to use it, and make it very clear that this is a "free forever, no subscriptions, no paid upgrades" style project.

[wallstop]

This is a multi-phase set of work items.

[wallstop]

Theme workflow documentation landed in PR #116: README now explains creating a DataVisualizerThemeSettings asset, selecting it in window Settings, reset behavior, and current limits (no presets, no full token surface yet). This covers the theme-usage portion of the doc overhaul; GitHub Pages and auto-capture remain open.

[wallstop]

Status update, run of 2026-09-18: the README half of this issue advanced with PR #116 (merged to main as a02226f) — theme creation, selection, reset, and current limits (inline styles still win, no hot reload of changed stylesheet references) are now documented, on top of the existing usage docs corrected in PR #106.

Still open, in dependency order: (1) local capture automation (T10) so screenshots/gifs are regenerable rather than hand-taken, (2) the GitHub Pages site itself, styled after the sibling repos listed in the issue, (3) the "free forever" positioning copy. The capture infrastructure is the gating item for honest current imagery and is a roadmap slice of its own; no docs-site work was started this run.

[wallstop]

Docs-accuracy update in PR #119 (branch t86/theme-hot-reload), run of 2026-09-18: with #86's hot-reload slice, the README's documented limit "After changing the theme asset's stylesheet reference, reselect the theme or reopen the window" is removed and replaced with the new behavior (edits, reference swaps, renames/moves, and deletions of the applied theme or its stylesheet now update the open window immediately, with deletion falling back to the package style).

Still open, in the previously recorded dependency order: (1) local capture automation (T10) for regenerable screenshots/gifs, (2) the GitHub Pages site, (3) the "free forever" positioning copy. No capture or Pages work was started this run.

[wallstop]

Positioning-copy update in PR #120 (branch t86/style-variants), run of 2026-09-19: the README now states the "free forever" positioning from the issue body — no subscriptions, no paid upgrades, no feature-gated tiers, full MIT-licensed source, every documented capability ships in the free package — right after the intro paragraph. The same PR documents the new Compact/Minimal density variants (see #86).

Still open, unchanged dependency order: (1) local capture automation (T10) for regenerable screenshots/gifs — the gating item; this run's capture attempt also hit a concrete environment blocker worth recording for T10 design: the host macOS TCC dialog denies screencapture to the Unity editor process, so window captures need either a granted permission or a Unity-side capture path; (2) the GitHub Pages site; (3) remaining docs overhauls styled after the sibling repos. No capture or Pages work was started this run.

[wallstop]

Capture-automation slice delivered in PR #123 (run of 2026-09-19): the Unity-side capture path this thread identified as the TCC-free option is now implemented. EditorSurfaceCapture (Tests assembly) popup-hosts a window, settles its UI Toolkit panel layout, renders into an offscreen linear RenderTexture through three repaint/render cycles, and writes a 24-bit PNG — it never reads the desktop, so no Screen Recording permission is needed. EditMode tests prove the real Data Visualizer window captures to a valid non-blank PNG, deterministic surfaces capture byte-identically, and guards fail closed; red-green evidence shows the tests catch a broken render pipeline (blank frame). Full EditMode 311/311, PlayMode 15/15 on the 6000.4.6f1 host; the npm/UPM payload is unchanged (Tests are not shipped).

Two rules for future capture work came out of review: capture hosts must be a dedicated window type nothing else looks up by name, and popup-hosted windows must be torn down with DestroyImmediate (EditorWindow.Close does not reliably unregister them).

Still open, unchanged order: (2) the GitHub Pages site, (3) remaining docs overhauls styled after the sibling repos, plus a capture manifest/driver script that regenerates docs/images/ from this helper.

[wallstop]

Advanced the capture-driver slice in PR #125 (Refs #114):

Delivered

• Tests/Editor/DocsImageCapture.cs: manifest driver that arranges the real window (8 PlayModeDataObject fixture assets, selected type + object via NamespaceController.SelectType/SelectObject, fixed 330/620 splitter panes, snapshotted window prefs) and captures the layout shot through EditorSurfaceCapture. RunFromCommandLine supports batch-mode regeneration via -docsImageOutputDir / DATAVISUALIZER_DOCS_IMAGE_DIR, default Temp/DocsImageCaptures (never writes into docs/). EditMode coverage: guards, CLI resolution, full-manifest integration capture — 17/17, full suite 328/328 on the 6000.4.6f1 host.

RCA: why no README image swap yet
Offscreen panel capture renders laid-out, display:flex labels without painting them. Probe evidence on this host (Unity 6000.4.6f1, 1180x780 popup-hosted window):

• Objects list shows 8 named rows, selection highlight, and inspector Title/Description fields — but the inspector's Asset Name: band (y=40) and Base Data foldout header (y=225) do not paint, and one namespace row paints blank.
• All five ScrollViews sit at scrollOffset.y = 0 before and after capture, so this is not scroll state or ListView virtualization; the elements have valid layout geometry and resolvedStyle.display == Flex.
  The stale data-visualizer-layout.jpg stays until that render gap is understood — a known-broken hero is worse than the old JPG. The driver is now the in-repo reproduction for that investigation (next slice), followed by the remaining shot states (create/import/settings popovers likely need in-panel redesign or a granted OS permission, since child popup panels are separate panels the offscreen render cannot composite).

[wallstop]

Render-gap RCA, run of 2026-09-19 (post-#125): fix attempt failed; blocker recorded

Attempted the next recorded slice — root-cause and fix the offscreen capture's unpainted content, then swap the README hero. The fix attempt failed; this comment records what was measured so the next attempt starts from evidence, not guesses.

Reproduction (deterministic, via the #125 driver + instrumented probe tests on the 6000.4.6f1 host):

• Unpainted subtrees: the unselected namespace group and its type row (window's namespace tree), the window's Asset Name: field, the Asset Labels: section, and InspectorElement's m_Script row plus the IMGUI-backed _assetGuid row ([Header] decorator + IMGUIContainer for the [ReadOnly] drawer). Their selected counterparts (Runtime/PlayModeDataObject), all ListView object rows, and the plain Title/Description property fields paint correctly.
• The unpainted elements are fully valid in the tree: display=Flex, visibility=Visible, opacity 1 (except the disabled m_Script field at 0.5), correct worldBounds, all ScrollView scroll offsets 0. Whole subtrees emit zero pixels (backgrounds, borders, and text).

Workarounds tried and falsified (each with pixel-level before/after sampling):

• More render cycles (8+), editor-frame yields between cycles, MarkDirtyRepaint() on every element, window.Repaint(), InternalEditorUtility.RepaintAllViews().
• SetEnabled(true) across the tree; fresh RenderTexture allocation; display:none → flex full-chain rebuild; popup vs ShowUtility hosting (pixel output byte-identical across all variants).
• Minimal-repro bisect: a plain EditorWindow with the same element shapes (bold labels, arrow buttons, readonly/disabled fields), and the same window with the package stylesheet applied, and a ScrollView + sheet variant — all paint fully. The trigger only exists in the full real window's composition.
• Also falsified as triggers: persisted theme (none on the host), the stylesheet alone, arrangement step order (blanks exist right after the initial load), DPI/scale (panel scale 1, pixelsPerPoint 2), DynamicAtlas state, and HostView.InvokeOnGUI (the real paint path) — it throws inside GUILayoutUtility.BeginLayoutArea without a native current-view context, so it is unreachable reflectively.

Conclusion: the omissions happen inside Unity's internal UI Toolkit renderer (UIR/Panel) for the popup-hosted offscreen path; no public or reflective API found on 6000.4 forces a faithful full repaint into an offscreen target. Per the agreed bar, the stale data-visualizer-layout.jpg stays (a hero with missing labels is worse), and the driver remains the standing reproduction. The two CaptureShot runs through the MCP eval bridge also showed an intermittent NRE thrown outside the invocation (tests stay 17/17 through the supported path) — noted as an observation, no repo defect claimed.

Next viable directions, for the record: (1) a granted macOS Screen Recording permission for the Unity process, after which capturing the live popup window needs no offscreen render; (2) a Unity-side answer (or upstream report) on forcing full UIR repaints offscreen; (3) partial-shot capture of individual panes, which paint correctly, if per-pane imagery is acceptable for docs.