fix(mcp): agent HTML pages stop painting slab backgrounds

[t3dotgg]

Agents' inline HTML pages sometimes paint a solid background (often #000 from personal "true black" style rules) with no padding. The page then reads as a dark slab in the thread, and its content touches the slab's edges.

The html_render layout guide now tells agents:

• By default, leave html, body, and the outermost element with no background color. The injected --background already matches the thread. This rule overrides general style preferences.
• If a box needs its own background (a mock of a specific screen, or a panel that must stand apart), give it at least 16px of padding and var(--radius) corners.

Backgrounds are still allowed. We only add guidance, with no CSS override.

Check: I gave the same mock request to agents with a "true black" rule and the html-communication skill. With the new guide, 3 of 3 runs left the page background unset and padded the boxes that had a background by 16px. With the old guide, 3 of 3 runs used var(--background), so I could not reproduce the original #000 slab locally. The fix is guidance only, and an agent can still ignore it.

Reviewed with sol-loop: 1 round with GPT-6.1 Sol on medium.

Created with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The PR changes the default styling guidance supplied to agents for existing inline HTML renders, which can alter user-visible page backgrounds, padding, and corners. Despite being a small, guidance-only diff, product-default changes require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 1ce0e3f3-7c26-483c-bca4-19b97028c101

📥 Commits

Reviewing files that changed from the base of the PR and between f60367b and cee3426.

📒 Files selected for processing (1)

• packages/shared/src/htmlRender.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The HTML render layout guide now specifies that pages inherit the thread background and that root and outer backgrounds remain unset. It retains the fluid-width and no-outer-card guidance and adds padding and corner requirements for separately colored boxes.

Changes

HTML layout guidance

Layer / File(s)	Summary
Layout and box styling rules packages/shared/src/htmlRender.ts	The guide says to leave root and outer backgrounds unset, retains the fluid-width and no-outer-card rule, and requires at least 16px of padding on every side and var(--radius) corners for boxes with their own background.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to cee34

This change only updates layout guidance, and no concrete user-facing or operational issue is established. It is mergeable with normal checks.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: guidance that prevents agent-generated HTML pages from painting slab backgrounds.
Description check	✅ Passed	The description clearly explains the problem, change, and focused verification results. It does not include a scope-and-approval section or explain why the change qualifies for an exception, but the d…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful main measurement shown below.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	4.9 KiB	4.9 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.8 KiB	20.8 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	1	1	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	−41 B (−0.8%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−41 B (−3.3%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	−41 B (−0.2%)	29.3 KiB	✅
Claude	Live turn messages	2	1	−1 (−50.0%)	8	✅

Baseline: 250e052 · PR result: cee3426 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.