Make AI-Generated HTML Reports Fast to Load

Table of contents

1. Why fast artifacts get reviewed (slow ones don’t)
2. Start with a DOM budget (and enforce it)
3. Collapse bulk by default with details + summary
4. Skip rendering work until it’s needed (content-visibility)
5. Avoid long tasks: less JS, fewer reflows
6. Keep artifacts small and stable for sharing + compare
7. A copy-paste agent prompt to bake this in

Why fast artifacts get reviewed (slow ones don’t)

BinHTML links are usually opened in the middle of a workflow: a PR review, a CI failure, a planning thread, or a handoff from an agent to a human. In that moment, *latency is trust*. If the artifact takes multiple seconds to become usable (scroll jank, delayed input, constant layout shifts), reviewers assume the underlying work is also messy.

Fast artifacts have two practical benefits:

• **They get read.** A reviewer who can skim and jump to the right section will actually leave feedback.
• **They compare well.** If a page is stable and predictable, diffs show meaningful changes instead of noise (pair this with Make AI-Generated HTML Reports Diff-Friendly).

Start with a DOM budget (and enforce it)

Large DOMs slow down style calculation, layout, and rendering. They also make everything else harder: search, expand/collapse, and client-side filtering. Lighthouse explicitly calls out excessive DOM size, and web.dev has a concrete guide on how DOM size affects interactivity.

A practical approach for AI-generated reports is to define a budget up front. For example:

• **Prefer “summary first”**: one page header + key conclusions + a short table of contents.
• **Hard-cap repeated rows**: show the first N rows and link to a second artifact for the full dataset.
• **Avoid “one div per cell” grids** for huge tables.

If the report truly needs to be enormous, publish it as a *bundle* instead of one mega-page:

• Summary artifact (fast)
• Detail artifact(s) (deep)
• Optional appendix artifact (raw)

If your team is already using project share links, this is the ideal case for a project index page that points to each artifact in the right order.

Collapse bulk by default with `details` + `summary`

A common agent failure mode is “dump everything, fully expanded”:

• 3,000-line logs in the middle of the page
• giant JSON payloads
• stack traces repeated for every failing test

Instead, collapse bulky sections by default and let the reviewer choose what to open. The native HTML disclosure pattern (details + summary) is fast, simple, and accessible when used correctly.

Practical patterns that work well in artifact review:

• “Top 10 failures” expanded; “All failures” collapsed.
• Per-test details blocks with a one-line summary: status + duration + key failure hint.
• An “Evidence” section where each item (log excerpt, HTTP transcript, SQL query plan) is its own collapsed block.

This also makes compare views more useful: a collapsed section is still present in the DOM, but you avoid forcing the browser to paint a huge scrolled region on load.

Skip rendering work until it’s needed (`content-visibility`)

If your artifact contains large sections that are below the fold (tables, log blocks, big lists), content-visibility: auto can reduce initial rendering work by allowing the browser to skip rendering content until it scrolls into view.

For artifact-style pages, this works best when you pair it with a predictable layout:

• Put each major section in a wrapper element (so you can apply the property per section).
• Use a stable heading structure (so reviewers can navigate even if some content hasn’t been rendered yet).

This is not a silver bullet, but it’s a pragmatic “make the first screen usable immediately” lever for long reports.

Avoid long tasks: less JS, fewer reflows

Most HTML artifacts should behave like *documents*, not apps. The goal is reviewability, not interactivity. Every time an agent adds a client-side framework, a massive syntax highlighter, or a big charting library, you risk long JavaScript tasks that freeze the page.

A few rules of thumb:

• **Prefer static HTML + CSS.** If you need interactivity, keep it tiny (expand/collapse, simple filtering).
• **Avoid doing work on page load.** Don’t parse huge JSON, don’t render thousands of rows, don’t compute aggregates in the browser.
• **Watch for “Evaluate Script” hotspots.** web.dev’s long-task guides explain why script evaluation can dominate the main thread and how to break work up.

If you must include heavier JS (for example: an interactive chart), consider splitting the content into two artifacts:

• A fast, static summary artifact for most reviewers
• A separate “interactive exploration” artifact for the few people who need it

Keep artifacts small and stable for sharing + compare

Performance and shareability overlap more than you think. A few practices improve both:

• **Avoid external dependencies.** Self-contained artifacts load reliably and don’t surprise reviewers (see Keep Generated HTML Self-Contained Before You Share It).
• **Prefer links over embedding huge assets.** If you need a 20MB screenshot, publish it as a separate artifact and link it.
• **Don’t bake “generated at” timestamps into the main content.** If you need provenance, put it in a small metadata block (or rely on the published timestamp) so diffs stay clean.

When you’re ready to share outside your immediate team, add the normal safety gates (visibility, expiry, revocation, source-access policy). Performance is not a replacement for those controls — it just makes the review loop actually work.

A copy-paste agent prompt to bake this in

If you’re using an agent to generate HTML reports, add a “performance contract” to the prompt. For example:

1. Output a summary-first HTML report intended for human review.
2. Keep the initial DOM small: avoid rendering full datasets or full logs inline.
3. Any repeated section (rows/tests/files) must be capped and collapsed by default using details + summary.
4. Avoid heavy JavaScript and avoid doing expensive work on page load.
5. If the artifact would be large, split into multiple artifacts (summary + appendix) and publish both (use a project share link if available).
6. Keep the output self-contained (no remote scripts/fonts).

Then publish via your preferred path: API docs or MCP docs. If you’re iterating on the same report over time, publish versions and use /compare before you send the link to a reviewer.