Skip to content

html-visual.md

Latest commit

 

History

History
104 lines (82 loc) · 5.17 KB

html-visual.md

File metadata and controls

104 lines (82 loc) · 5.17 KB
Raw

Portable HTML Output

Use when the selected output mode is HTML: generate a self-contained report.html as the primary portable visual beside the paired report.md and findings.json.

This file owns HTML metadata, runtime boundaries, and validation. The selected templates/style/*.md file owns visual grammar; visible labels follow the paired Markdown report template.

Authoring Flow

Use only the selected style file's Visualization Style section for visual grammar. Keep the selected style id and localized label out of visible Markdown, HTML titles, notes, and labels.

For Agent Work Loop, mirror the canonical reader order without importing or emulating another host runtime: project introduction, five-dimension fluency, project activity and bounded model/Skill usage, compact finding cards with local AI-fix copy actions and scoped details, Agent Customize, then evidence and methodology. This is semantic parity, not a byte-for-byte host visual clone.

Use the selected style's primary visual family as the first meaningful visual surface. Then mirror the compact Markdown report sections and semantic source parts from report-output.md: style-selected dimensions or fluency framing, shared finding/action rows with local AI fix handoff and fallback text, recommendations, and notes. Do not copy one dashboard across all styles.

Treat fixed source parts as reading order, not prose layout. When numeric or grouped data exists, prefer an inline SVG/CSS chart or matrix for the style-selected framing part. Keep issue evidence in shared finding/action rows, risk heatmaps, or style-owned visuals instead of a standalone aggregate section. Tables and cards remain acceptable fallback surfaces when the source has no chartable score, count, severity, timing, or domain data.

Runtime Boundaries

  • Create exactly one HTML visual file: report.html.
  • The file must be self-contained and open directly from disk.
  • Embed all CSS, SVG, data, and optional small JavaScript inline.
  • Do not use remote assets, CDN links, web fonts, fetch(), network calls, runtime file reads, local absolute asset paths, package imports, build steps, or generated helper files.
  • Optional local preview may use npm run preview:html -- report.html, but the generated file must not depend on that server.
  • Follow output-mode exclusions from templates/reporting/routing.md.
  • Prefer semantic HTML plus CSS and inline SVG. Use inline JavaScript only for small local interactions such as filtering, tabs, or disclosure state.
  • Keep the first viewport useful: project, verdict, confidence, score caveat, and the primary visual should be visible without the Markdown report.

Required Report Parity

Mirror the Markdown report and the parity rules in skills/better-harness/SKILL.md#report-output. Do not introduce new conclusions.

Keep first-screen labels short. Put long paths, command output, screenshots, and raw evidence anchors in an evidence table or appendix. Render retained UTC activity dates left-to-right; use shared cell/tick grid columns and gaps, and keep long-range scrolling inside the chart.

HTML cannot assume a host chat API, native prompt injection, or host-specific deep links. For each shared finding/action row, render compact Copy AI Fix and View details controls only when a non-empty reviewed AI fix exists; keep View details when it does not. Keep aiFixPrompt unchanged in findings.json. Embed only the actionable id/prompt projection plus a separate machine binding containing the final report.html workspace-relative POSIX route, finding id, and current output revision. Do not embed renderer-added absolute workspace or artifact paths.

When opened from its original matching file: location, derive the workspace and sibling final findings.json paths at copy time and append one renderer-owned <better-harness-fix-output> callback. For HTTP previews, moved files, or intentionally context-free renders, copy the unchanged reviewed prompt without a callback. Keep malformed declared bindings fail-closed. Report copy success truthfully and use the same computed text for clipboard, legacy, and selected manual-copy fallbacks. Keep the full cause, expected output, and acceptance checks in the scoped details dialog and readable no-JavaScript and print content.

For reviewed long-session tool traces, render compact cards with the privacy-safe request and session locator. Use a native disclosure and inline SVG/CSS; keep complete traces scrollable, distinguish failures, scale bubble area from observed latency, expose accessible timing labels, and omit host deep links.

Markdown Report Addendum

Add after Generated artifacts in the paired report.md:

- HTML visual: `<selected HTML visual reference, e.g. diagnostic path + evidence table>`

Append near the end of the paired report, after the shared issue/action rows or existing notes:

## HTML Companion

- HTML file: `report.html`
- HTML visual: `<reader-facing visual reference, e.g. diagnostic path + evidence table>`
- HTML must mirror the source reader parts, including row-level AI fix text for
  each finding/action row when present.

Use literal Markdown list lines. Other modes omit HTML visual and HTML Companion.