Skip to content

feat(render): add self-contained interactive HTML viewer - #58

Open
JAORMX wants to merge 7 commits into
mainfrom
render-html-viewer
Open

JAORMX wants to merge 7 commits into
mainfrom
render-html-viewer

Conversation

@JAORMX

@JAORMX JAORMX commented Sep 28, 2026

Copy link
Copy Markdown

Summary

Add modelith render --format html as an offline, self-contained interactive viewer while keeping Markdown the default.

  • Embed HTML/CSS/vanilla JS in the existing static binary; no new dependencies, server, or external assets.
  • Show directed relationships with declared cardinalities and ownership, subtype edges, self-relationships, and external entities.
  • Add entity details, search, pan/zoom, draggable nodes, deterministic grid/flow arrangements, themes, and relationship highlighting.
  • Present model-wide invariants, enums, glossary, scenarios, and imports in counted accessible tabs.
  • Integrate collapse into the details panel: a persistent header control, a narrow desktop reopen rail, and a compact mobile expand row. Collapsing preserves graph state.
  • Support existing --stdout, --out, and --check workflows and format completion; update CLI docs and ADR-0020.

Model content is encoded with Go's default HTML-safe JSON escaping and rendered through DOM text APIs. Schema and model structs are unchanged. The HTML golden lives in package testdata rather than examples to avoid adding a large generated output to the example workflow; Go tests check it byte-for-byte.

Validation

  • node --test internal/render/html/viewer_test.cjs: 30 passing tests.
  • task check: vet, staticcheck, golangci-lint, race-enabled Go tests, strict example lint, and Markdown render checks pass. The final validate-plugin step is blocked because claude is not installed; no gate was bypassed.
  • HTML golden regeneration/review and git diff --check pass.
  • Installed locally and exercised against the mecatl domain model; rendered output was reviewed interactively by the author through screenshots and feedback.

Review and limitations

Independent agent review/fix rounds covered correctness, standards, geometry, interaction state, and UX. These were approximations, not /code-review. The final UX pass found no remaining blocker after fixing the collapsed rail's clipped keyboard-focus indicator.

The Node harness mocks DOM/geometry; real-browser layout and accessibility smoke testing remains outstanding. The initial independent security-agent review did not complete; lead inspection and escaping/hostile-content regression tests cover the encoding path, but are not represented as an independent security sign-off.

JAORMX and others added 7 commits September 27, 2026 20:00
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
Co-authored-by: Mecatl <noreply@mecatl.dev>
Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>
@JAORMX

JAORMX commented Sep 28, 2026

Copy link
Copy Markdown
Author

Review record (autonomous approximation, not /code-review): initial spec/standards/UX/adversarial rounds fixed HTML check recovery, directed/parallel relationships, self-relationship display, and external incoming details. Subsequent geometry and interaction rounds addressed label placement, draggable layouts, highlight state, and model-wide tabs. For the final panel-integrated collapse change, UX review found the collapsed rail clipped its keyboard-focus outline; an inset outline and width correction fixed it, with structural/contrast tests. Final UX re-review: no remaining blocker. Current validation: 30 Node harness tests pass; task check passes Go lint/vet/race tests, model lint, and render checks, but validate-plugin is blocked by missing claude. Browser-native layout/accessibility smoke and completed independent security review remain gaps, documented in the PR description.

@JAORMX
JAORMX marked this pull request as ready for review September 28, 2026 08:17
@JAORMX
JAORMX requested a review from jbeda as a code owner September 28, 2026 08:17

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant