Repository navigation
chore: Documentation OverHaul + Auto-Captured Images/webp #114
Description
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.
Activity
wallstop commentedon Sep 16, 2026
This is a multi-phase set of work items.
wallstop commentedon Sep 17, 2026
Theme workflow documentation landed in PR #116: README now explains creating a
DataVisualizerThemeSettingsasset, 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.Ship Classic, Nord, and Dracula themes
Add custom theme selection in settings (#116)
wallstop commentedon Sep 18, 2026
Status update, run of 2026-09-18: the README half of this issue advanced with PR #116 (merged to
mainasa02226f) — 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 commentedon Sep 18, 2026
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.
Add theme hot reload for applied theme asset changes (#119)
Add Compact and Minimal style variants and tokenize control sizing
wallstop commentedon Sep 19, 2026
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
screencaptureto 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.Add Compact and Minimal style variants (#86), tokenize control sizing (…
wallstop commentedon Sep 19, 2026
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.Add offscreen editor-window capture automation (#114) (#123)
wallstop commentedon Sep 19, 2026
Advanced the capture-driver slice in PR #125 (Refs #114):
Delivered
Tests/Editor/DocsImageCapture.cs: manifest driver that arranges the real window (8PlayModeDataObjectfixture assets, selected type + object viaNamespaceController.SelectType/SelectObject, fixed 330/620 splitter panes, snapshotted window prefs) and captures thelayoutshot throughEditorSurfaceCapture.RunFromCommandLinesupports batch-mode regeneration via-docsImageOutputDir/DATAVISUALIZER_DOCS_IMAGE_DIR, defaultTemp/DocsImageCaptures(never writes intodocs/). 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:flexlabels without painting them. Probe evidence on this host (Unity 6000.4.6f1, 1180x780 popup-hosted window):Title/Descriptionfields — but the inspector'sAsset Name:band (y=40) andBase Datafoldout header (y=225) do not paint, and one namespace row paints blank.ScrollViews sit atscrollOffset.y = 0before and after capture, so this is not scroll state or ListView virtualization; the elements have valid layout geometry andresolvedStyle.display == Flex.The stale
data-visualizer-layout.jpgstays 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).Add usings-placement lint (#124) and docs-image capture driver (#114) (…
wallstop commentedon Sep 19, 2026
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):
Asset Name:field, theAsset Labels:section, andInspectorElement'sm_Scriptrow plus the IMGUI-backed_assetGuidrow ([Header]decorator +IMGUIContainerfor the[ReadOnly]drawer). Their selected counterparts (Runtime/PlayModeDataObject), all ListView object rows, and the plainTitle/Descriptionproperty fields paint correctly.display=Flex,visibility=Visible, opacity 1 (except the disabledm_Scriptfield at 0.5), correctworldBounds, 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):
MarkDirtyRepaint()on every element,window.Repaint(),InternalEditorUtility.RepaintAllViews().SetEnabled(true)across the tree; fresh RenderTexture allocation;display:none → flexfull-chain rebuild; popup vsShowUtilityhosting (pixel output byte-identical across all variants).EditorWindowwith 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.HostView.InvokeOnGUI(the real paint path) — it throws insideGUILayoutUtility.BeginLayoutAreawithout 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.jpgstays (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.
60 remaining items
Restore Unity connections across managed frontends (#241)
Fix performance baseline contracts (#242)
Docs publish the complete 10,000-asset baseline
wallstop commentedon Oct 14, 2026
DISCLOSURE: LLM-GENERATED TEXT
PR #244 adds a complete post-fix performance report for 100, 1,000, and 10,000 assets, with a downloadable raw JSON report and a table generated from all 15 result cells. The report's SHA-256 matches the host file and the strict site's downloadable artifact.
The page states the measured costs, five-sample limits, roughly 40-minute run, and the refresh timer's exclusion of fixture creation. It preserves the raw background-count defect and links #243. The new data does not close #226's import-stall criterion or the broader documentation epic. This work is on the remote PR branch and is not yet on main.
Publish the 10,000-asset performance baseline (#244)
Keep planning records focused on current work (#245)
Correct benchmark background asset counts (#246)
Validate the complete documentation capture inventory
Validate all six documentation captures (#248)
Keep capture recovery cleanup compatible across Python versions
Retain capture backups when rollback is interrupted
Preserve WebP batches when export fails (#250)
wallstop commentedon Oct 16, 2026
DISCLOSURE: LLM-GENERATED TEXT
Criteria audit against main 5259447, 2026-10-16:
Tests/Editor/DocsImageCapture,docs/images/capture-manifest.json, and the WebP/GIF exporters are on main with EditMode coverage.Remaining items are the macOS 6000.4 render/imagery gap and re-recording the pre-rename video walkthrough; both need that hardware, so the macOS evidence cell belongs with #270's macOS rows. With those two exceptions, this issue's checklist reads complete — happy to close when the owner agrees.
wallstop commentedon Oct 16, 2026
DISCLOSURE: LLM-GENERATED TEXT
Re-verified every in-repo criterion against main 7971cbc, 2026-10-16, beyond the audit above:
Tests/Editor/DocsImageCapture,capture-manifest.json, and the WebP/GIF exporters are on main with EditMode coverage; the committed inventory was verified byte-exact on the 6000.5 host on 2026-10-12.Closing as complete. Two hardware-gated exceptions stay tracked: the macOS 6000.4 imagery gap lives in #270's platform cells, and re-recording the pre-rename video walkthrough is an owner action (also noted on #146).