Skip to content

Fix rendering strategy diagnostics#72

Merged
dacharyc merged 2 commits intomainfrom
fix-rendering-strategy-diagnostics
Apr 30, 2026
Merged

Fix rendering strategy diagnostics#72
dacharyc merged 2 commits intomainfrom
fix-rendering-strategy-diagnostics

Conversation

@dacharyc
Copy link
Copy Markdown
Member

Summary

Two related fixes for rendering-strategy, prompted by Archbee scoring as having a third of its pages "use client-side rendering" when in fact every sampled page was fully server-rendered — they were just brief.

1. Split spa-shell-html-invalid into two distinct diagnostics

The diagnostic previously fired whenever the warn-or-fail proportion exceeded 25%, but its message claimed pages used client-side rendering. That was correct for actual shells but wrong for sparse-but-rendered pages, which is the larger bucket in practice.

  • spa-shell-html-invalid now fires only on actual SPA shells (spaShells / total > 0.25) and keeps its strong "client-side rendering invalidates the HTML path" message.
  • New sparse-content-html fires on sparse pages (sparseContent / total > 0.25), suppressed when the shell diagnostic already fired. Its message and resolution direct readers to spot-check rather than assume a renderer bug.

2. Loosen the heuristic so legitimately short doc pages pass

detect-rendering previously required visibleTextLength >= 1500 (after chrome stripping) as the wall-of-text fallback. Archbee's short integration explainers (Loom, Figma, Branches & Reviews) sat at 589–1485 chars of real prose and got flagged as sparse. Real shells, by contrast, post-strip to ~0 chars — the gap is much wider than 1500 implied.

Added a new clause to the hasContent disjunction:

(contentHeadings >= 1 && visibleTextLength >= 500)

A heading plus 500+ characters of post-chrome-strip body is well above any actual shell and well below what's needed to admit one. Two new tests cover both sides: a div-soup short page (passes) and an <h1>Loading…</h1> shell with empty body (still fails).

Impact

Archbee re-scored: serverRendered 36→68, sparseContent 32→0, page-size 89→100, overall 78→80 (B).

Doc updates

The split and the proportion math touched several docs. Updated:

  • docs/agent-score-calculation.md, docs/checks/page-size.md, docs/improve-your-score.md
  • docs/interaction-diagnostics.md (new sparse-content section, updated shell section)
  • SCORING.md, scoring-reference.md

Score-cap labels changed from "75%+/50%+ SPA shells" to proportion-based language reflecting the actual formula: (serverRendered + sparseContent × 0.5) / total. SPEC.md needed no changes — it already specifies the three result levels accurately.

Test plan

  • All 1,231 tests pass
  • Lint and typecheck clean
  • Re-ran Archbee end-to-end and confirmed expected score change
  • Spot-check at least one other site previously flagged for sparse content to confirm no regression

@dacharyc dacharyc merged commit 1c93420 into main Apr 30, 2026
2 checks passed
@dacharyc dacharyc deleted the fix-rendering-strategy-diagnostics branch April 30, 2026 01:53
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