large-file-build

Large-File Build (Chunked write_file Strategy)

Build large self-contained files (typically HTML dashboards, > 10KB) by splitting them into sequential write_file + patch operations. Single write calls exceed stream limits and must be avoided.

When to Use

• Building a single-file dashboard (HTML + CSS + JS + embedded data)
• Any output > 8KB where the first write_file would fail
• User explicitly requests a "self-contained HTML file"

Workflow

1. Calculate First, Then Embed

• Run all data/model calculations in execute_code (Python) to get exact numbers
• Print verification to stdout — this is your ground truth
• Only AFTER confirming values are correct, embed them

2. First Write — Skeleton + CSS + First Section

write_file(path=./draft.html)
# Include: <html>, <head>, <style>, <body>, <header>
# First content section (e.g., the bracket/tournament)
# Target: < 8KB payload

3. Subsequent Patches — One Section Each

patch(path=./draft.html)
# Match surrounding context exactly:
# old_string: closing tags from previous section
# new_string: next section's full HTML
# Keep each patch < 4KB

Sections to chunk (example for a World Cup dashboard):

1. Bracket data (1 section)
2. Stats tables (1 section)
3. Model/prediction with embedded data (1 section)
4. Footer (1 section)

4. Copy to Final Location

cp ./draft.html ./file.html   # the deliverable goes in the working directory

5. Verify with Browser

python3 -m http.server 8765 &
browser_navigate(url=http://localhost:8765/file.html)
browser_snapshot(full=true)  # verify all data rendered
browser_console()           # check for JS errors

If browser_snapshot returns empty elements or — values: the JS didn't execute or data wasn't embedded. Check for:

• HTML entity encoding issues in CSS (τ in style blocks)
• Script tag placement (must be after the HTML it references)
• Python execute_code vs HTML literal string encoding

Pitfalls