skills/visualize-data/references/inline-chart-renderer.md

# Inline Data Chart Renderer

Use this reference for an already-selected inline chart on Codex Desktop or in Work Mode, including ChatGPT web. Both surfaces deliver the same generated fragment through their installed Visualize skill; Work Mode wraps the file-backed fragment as an inline app block. Do not substitute `charts_widget_v2` merely because Work Mode is active, since that separate renderer does not include Data’s shared styling or editor. The [render-inline-chart.mjs](../scripts/render-inline-chart.mjs) CLI uses the shipped prebuilt version of the actual inline React adapter [index.jsx](../../../templates/data-app/inline/index.jsx), which imports the real shared `ChartRenderer` and `ChartEditor` from [data-app-public.jsx](../../../templates/data-app/base/src/data-app-public.jsx). Chart rendering, editing controls, styles, and themes stay owned by the canonical dashboard implementation; never recreate them in D3 or hand-authored HTML.

## Run The Shared Renderer

When available, call `load_workspace_dependencies` and use its absolute bundled Node executable as `<codex-node>`. In a Work workspace without that tool, resolve the already-installed Node executable; do not install a toolchain for rendering. Resolve the script from the installed Data plugin root. Inspect the bundled reviewed input [inline-chart-example.json](../assets/inline-chart-example.json) only when needed:

```sh
"<codex-node>" "<data-plugin-root>/skills/visualize-data/scripts/render-inline-chart.mjs" --example
"<codex-node>" "<data-plugin-root>/skills/visualize-data/scripts/render-inline-chart.mjs" --list-chart-types
"<codex-node>" "<data-plugin-root>/skills/visualize-data/scripts/render-inline-chart.mjs" \
  --input /absolute/path/reviewed-chart.json \
  --output /absolute/approved/visualizations/weekly-active-users.html --include-sql
```

The output must be an approved writable path outside the installed plugin and any legacy shared cache, with a lowercase-hyphenated `.html` filename. In Work Mode, read the system Visualize skill and write to its workspace root (normally `/workspace/weekly-active-users.html`); on Desktop use the task-owned visualization directory. Use the path returned by the renderer, not a local Desktop path in a web conversation. The renderer combines the verified data-free runtime, approved reviewed payload, canonical theme, and bundled [inline-chart-fragment.html](../assets/inline-chart-fragment.html). Deliver the real returned path in the same final answer as its native Visualize content reference:

```text
visualize{"path":"/absolute/approved/visualizations/weekly-active-users.html"}
```

Honor an explicit request for multiple inline charts, even when several are needed. Render each reviewed input with a stable, distinct chart ID and output filename; reuse the same shipped data-free runtime and emit one actual Visualize content reference per chart in the same final response. Never concatenate complete fragments or rebuild the runtime for each chart.

Use the executable directly; do not rebuild the dashboard, install packages, generate substitute D3, recreate React components, or return the fragment as a download or code block. A build command, unrendered file, source preview, or promised handoff is not the delivered chart.

## Edit The Inline Chart

The chart overflow menu's `Edit chart` action opens the shared `ChartEditor` inside the visualization. It supports local title and description changes, compatible conventional chart types, approved numeric measures and series fields, and the shared axis-label, start-at-zero, color, sort, legend, and value controls where supported. Choices come only from already embedded, privacy-reviewed fields and must preserve the reviewed grain; a grouping that would collapse or overwrite rows is unavailable. Stacked and percentage views keep the original reviewed measure and split; permission to stack the original chart does not authorize a different mapping. A raw stacked chart can switch to a compatible unstacked type before choosing other approved fields; percentage normalization remains fixed. Specialized chart types and their reviewed data mappings stay fixed. Native histogram measurement and count axis labels are editable, while raw observations, binning, and the count baseline remain fixed. Reviewed nonnumeric or numeric-string measures also keep their original type and mapping for cosmetic edits; do not coerce their values. Do not change the analytical chart family or preaggregate reviewed rows merely to unlock presentation controls. Use the offered controls and explain genuinely unsupported options instead of generating another editor or adding unreviewed fields to make an option appear.

`Apply` commits presentation changes only to that mounted chart. `Cancel` or Escape discards the current draft. `Reset` changes the draft back to the original reviewed presentation; it takes effect only after `Apply`. The shared editor owns undo and redo. Each inline chart has independent state. Edits do not survive a reload or reopening the task, and they do not modify the generated HTML, original reviewed rows, query, source metadata, or provenance.

The inline editor cannot run queries, change source data, publish an artifact, or write to a backend. For a different aggregation, unavailable field, new data, or a persistent/shareable result, return through Data's existing source and output workflows. Mention `Edit chart` in the answer only when it helps the user explore or restyle the result; do not add a fixed editor walkthrough or claim that changes were saved permanently.

## Reviewed Input And Source Safety

Use descriptive titles unless a supported takeaway is requested; preserve user-authored titles. Prefer aligned positions and consistent scales for magnitude comparisons. Use `groupOther` only for exclusive, nonnegative additive categories, never overlapping audiences or rates. Show material uncertainty with estimates and identify interval meaning/level; use a visible bounds table if intervals cannot render. Bounds must match the selected population: never invent them, reuse aggregate intervals for subgroups, or label scenarios as confidence intervals. Disclose unavailable uncertainty. Evaluate differences directly, not by interval overlap.

The JSON input requires `schemaVersion: 1`, a reader-facing `title`, the canonical `chart` specification, bounded reviewed `rows`, and a real `source` with `source.label`. Optional `id`, `queryId`, `description`, approved preview `columns`, reviewed `filters`, `generatedAt`, `height`, and `theme` preserve existing dashboard semantics. The shared `projectChartSpec` and `chartDataShape` retain real histogram, Sankey, precomputed box-plot, and waterfall metadata while removing private extension fields; do not invent extra fields or axes. Preserve missing observations as `null` in the real measure; do not invent helper series or zero-fill missing values to force chart marks. Use `--list-chart-types` for the live supported chart families rather than maintaining a duplicate list. Keep the input below 2 MB, project unnecessary columns, and provide no more than 2,000 reviewed rows; the generated fragment must remain below 1 MB. Explicitly label synthetic or illustrative data as sample data.

Inline charts contain no source button or sidebar. On Desktop outside Work Mode, source inspection belongs to the [Sources receipt](inline-sources-receipt.md) immediately below each chart; follow that reference for evidence scoping and text-only or mixed answers. Work Mode retains its existing source delivery contract. The chart payload retains reviewed provenance for compatibility and semantic styling. Include only reviewed, chart-scoped definitions, freshness, caveats, filters, bounded preview rows, and recorded evidence. Set `source.executedAt` only from recorded query-execution metadata and `generatedAt` only from actual reviewed snapshot creation or capture; preserve materialization or source-refresh timestamps with their timezone in an original approved preview field or explicitly labeled `source.caveats`/`source.evidenceFlow`, omit unknown timestamps, and never relabel freshness as query execution. For SQL-backed results, populate `source.sql` with the exact executed statement from the query call or recorded execution. Review the entire statement, including literals and comments, for credentials, connection strings, and direct contact or payment identifiers; then normally pass `--include-sql` without asking the user again. The renderer rejects common sensitive literals, but that check does not replace this review. Preserve that statement verbatim and describe later filtering, aggregation, or calculations separately in the recorded evidence. If the handoff lacks SQL, retrieve the exact statement from the available execution record before rendering. Never invent SQL for file/API results or reconstruct a missing statement; omit it when unavailable. Use `--omit-sql` for an explicit omission request or a statement that cannot be safely included; this also removes SQL-derived evidence. Explain a material omission in the source caveats without reproducing sensitive values. Do not rewrite or redact the statement and present it as the exact executed SQL. Supplied SQL requires one of these mutually exclusive flags, so forgetting the review decision cannot silently produce a chart without its query. With no recorded SQL, neither flag is needed. The JavaScript API defaults to exclusion and requires `includeSql: true` after the same review. Source URLs are omitted by default; use `--include-source-urls` only when the user explicitly requests reviewed source links. Keep raw code out of surrounding answer prose unless requested. Never include credentials, tokens, hidden reasoning, direct personal contact or payment identifiers, invented provenance, or unreviewed fields. The shared overflow includes Edit chart, Copy as image, and Copy data. Copy data uses the reviewed chart rows; image actions capture the applied presentation. Clipboard support depends on the embedding host and failures must be surfaced. Export chart is not exposed inline.

Use the canonical `codex-classic` theme by default and prefer explicitly requested bundled themes through `theme`. A reviewed local `--theme-css` stylesheet is parsed by the bundled CSS parser and may contain only `:root` custom-property declarations; imports, URL/image resources, other selectors, and arbitrary component CSS are rejected. Preserve host light/dark appearance and the dashboard's actual typography, semantic colors, curves, markers, legends, and tooltips without copying their values into instructions.

Annotations cannot expand the reviewed row projection. For event or benchmark evidence outside the plotted fields, explicitly include the reviewed evidence field in `columns`.
Annotations that name unapproved fields are omitted, even if their anchor would not render.
Point annotations on long-form series use the plotted series name, not another row column.
Sparse factual callouts may use reviewed rows; external events need a source actually read, and timing alone is not causal evidence. Recheck claims after filtering. Keep series distinguishable without color alone and check common color-vision deficiencies; palette limits are style defaults.

## Runtime, Compatibility, And Verification

Preparation uses Codex's bundled Node runtime (Node 20.19+ or Node 22.12+). The plugin ships one pinned, data-free React/Recharts runtime built from the protected dashboard sources. `--prepare` verifies that shipped runtime; it does not compile it or install dependencies. Normal rendering works without npm or network access, including on a fresh machine with no dependency cache. `--offline` and `--cache-dir` remain accepted for compatibility, but do not create or populate dependency caches. Never put reviewed rows, SQL, source URLs, or generated fragments in the plugin or a shared cache. Do not import the full `DataAppShell`, global theme runtime, dashboard fixture data, external scripts, or network-backed runtime dependencies.

The executable escapes reviewed JSON, script terminators, and replacement-sensitive JavaScript so the fragment works in both older `String.replace` string-replacement hosts and fixed callback-replacement hosts. Do not rewrite, re-minify, or interpolate the completed fragment. When changing the renderer, perform real sandbox/browser QA for actual React/Recharts marks, light and dark appearance, desktop and narrow widths, both the Desktop and Work Mode embedding paths, absence of duplicate chart source UI, shared editor Apply/Cancel/reset behavior and keyboard dismissal, independent multi-chart state, unchanged reviewed rows and provenance, exact SQL preservation and explicit omission, default source-URL exclusion, and copy success or explicit permission failure. If preparation, input validation, rendering, or delivery fails, surface the actual error and do not claim an undelivered chart rendered. Never claim a chart rendered unless its native Visualize content reference was emitted successfully.

## Troubleshooting

- Missing or invalid prebuilt runtime: finish the plugin update or restore the verified plugin, then retry; do not fetch replacement packages. `--prepare --offline` verifies the shipped runtime without requiring a cache.
- Protected-runtime mismatch: finish the plugin update or restore the verified plugin, then retry; never bypass its verifier or rewrite the integrity manifest.
- Oversized fragment: aggregate reviewed rows and remove unnecessary preview columns or source details before retrying.
- Rendering failure: inspect actual host-sandbox insertion and browser errors. A `file:///` page or Python preview alone does not prove live insertion. Maintainers run `npm test` and `npm run test:inline-chart-browser` from the Data plugin root.