build-html-dashboard

LIST THE INSIGHTS (terse — one line each, not an essay): Before coding, list the insights you want to present/convey/highlight as 1 - <chart/infographic/etc>: <insight it conveys and why it matters>.. Example: 1 - Line chart of weekly signups: shows growth inflection after the March launch, flags whether momentum is sustained. This is a checklist, not a brief — no narrative prose, no design discussion.

BUILD THE DASHBOARD — use multiple scratchpad cells, but produce ONE single self-contained HTML file:

Before the first write, call create_artifact(type="html-app", name=..., description=..., primary="dashboard.html") and use the returned <artifact_path> for every file you write (the HTML, any sibling data files, images, etc.). All paths below referring to "the output directory" mean <artifact_path>. The final dashboard MUST be a single .html file with all data, CSS, and JS inlined, with exactly two exceptions, both covered below: an oversized JSON payload, and binary assets such as an image the user uploaded. Both live as sibling files in the SAME directory as the HTML. Never reference a local file OUTSIDE <artifact_path> — browsers block local file:// cross-references across directories, and the publisher will not bundle it.

REROUND DISCIPLINE (critical — most "round-cap exhaustion" failures we've seen on real dashboards come from drifting off one or more of these):

1. ONE scratchpad, ONE name. Pick a name on the first cell (e.g. dash) and reuse it for the entire build. Switching names (build_pres → write_html → pres1 …) creates separate isolated environments — variables in one don't exist in another — and burns rounds on recovery.
2. WRITE TO DISK INCREMENTALLY. Open the output .html once in 'w' mode, then open(path, 'a') to append head → body skeleton → each chart section → nav/JS → closing tags. Each cell appends a small chunk you can sanity-check. Do NOT build a single 20KB+ HTML string in memory and write it at the end.
3. CAP STRING SIZE PER CELL at ~5KB. Large-string scratchpad calls are the single biggest cause of silent failures (the tool occasionally drops the code payload on oversized inputs and the cell comes back with an empty-code error, which still counts against the round cap). If a section is too big, split it.
4. NEVER re-emit the full HTML mid-build. Append deltas, don't re-print the world. Assembly is a one-line concat at the end, not a re-render of everything you've written so far.
5. KEEP READS SMALL. To verify what landed, os.path.getsize(path) or open(path).read(2000) — never open(path).read() on a multi-KB HTML.

SECURITY (critical): Dashboards may be published to the web. NEVER embed API keys, tokens, passwords, connection strings, or any credentials in the HTML, JS, or inline data. Fetch data in scratchpad cells using credentials from environment variables, then serialize only the resulting data into the dashboard. If the user explicitly asks to embed a credential (e.g. for a live-updating dashboard), warn them that publishing will expose it and get confirmation before proceeding.

Build the parts in separate cells, then assemble at the end:

CELL 1 — Serialize data to a JS string variable (programmatic, no HTML): Serialize all computed data (dataframes, metrics, KPIs) into a Python string. Build a Python dict with keys like "kpis", "tables", "charts" — each containing the relevant data. Convert DataFrames with df.to_dict(orient='records'). Use json.dumps(data, default=str) to handle dates, Decimal, numpy types. Store as a Python variable: data_js = 'const D = ' + json_string + ';' — do NOT write to a separate file.

CELL 2 — Build CSS + HTML structure as a Python string variable: Write the HTML head (styles, CDN script tags) and body structure (header, KPIs, chart divs, tabs, tables) as a Python string variable html_body. This cell builds the template.

CELL 3+ — Build JS chart rendering logic as Python string variables: Write the JavaScript that initializes charts, populates tables, handles tabs, etc. Split across multiple cells if needed to avoid token limits. Store as js_charts etc.