CustomRenderer (Next)

CustomRenderer renders arbitrary HTML, CSS, and JS from layout JSON (customRendererItem). It does not subscribe to $heat-dataservice channels the way MapDisplayDS or ComposableChartDS do.

On session analysis pages, scripts can read window.$session, including inside the sandboxed iframe (see Does $session work in sandbox?).

When to use something else

If the dashboard-v2 node already publishes data, the sensible path is almost always: add or reuse channels in $heat-dataservice, then pick a manifest widget that declares the right channelShapes. CustomRenderer should not replace that pipeline.

How this relates to the dashboard node

The dashboard-v2 node (Legacy: dashboard node) does two jobs that matter here:

1. Layout , merged layoutConfiguration (rows, component ids, per-widget configuration). This becomes $session.layout / $session.layoutConfiguration on the session page.
2. Session payload , the JSON blob the runner stored for the dimension (channel data, scores, legacy keys, and so on). On the session page this is exposed as $session.payload without HEAT rewriting its shape.

Next (generation: "next"): $session.payload is the last raw session API object captured before channel ingest. It often contains $heat-dataservice (canonical realms/channels) but may still include legacy top-level keys if the runner publishes them. The data service also ingests channels for built-in widgets; CustomRenderer does not automatically use that ingest path.

Legacy (generation: "legacy"): $session.payload is the v1 dashboard facade blob (dashboardData: keys such as Map, combined-custom-charts, ImpactHeatmap, and so on). Built-in Legacy widgets still fetch their own API slices; CustomRenderer only sees what you read from $session.payload in script.

Rule of thumb: if the data you need is already a channel in $heat-dataservice, do not scrape it from $session.payload in CustomRenderer. Add a proper widget binding instead. Use $session.payload when you truly need ad hoc access to the stored runner JSON (debug panels, migration shims, prototypes).

Dashboard generation

Layout component identifier

CustomRenderer , cols[].component in v2 layout rows (Legacy mount id matches).

Layout configuration

customRendererItem

Sandbox example (recommended)

{
  "component": "CustomRenderer",
  "colspan": 6,
  "configuration": {
    "name": "custom-demo",
    "titleContent": "Custom panel",
    "channels": [],
    "customRendererItem": {
      "html": "<div id=\"root\"></div>",
      "css": "#root { font-family: sans-serif; padding: 1rem; }",
      "js": "var r = document.getElementById('root'); r.textContent = $session.title + ' (' + $session.generation + ')';",
      "useCard": true,
      "renderMode": "sandbox"
    }
  }
}

Inline example (discouraged except trusted internal templates)

{
  "component": "CustomRenderer",
  "colspan": 12,
  "configuration": {
    "name": "custom-inline",
    "titleContent": "Trusted only",
    "channels": [],
    "customRendererItem": {
      "html": "<p id=\"x\">Inline</p>",
      "js": "document.getElementById('x').textContent = $session.query('scenarioInstance.scenarioName') || 'n/a';",
      "renderMode": "inline",
      "useCard": true
    }
  }
}

Set useCard: false when the layout grid cell already provides chrome and you want edge-to-edge content.

window.$session

On session analysis routes, SessionPageContextProvider sets window.$session (Next and Legacy share the same top-level fields). CustomRenderer scripts read it without React hooks.

Does $session work in sandbox?

Yes. With the default renderMode: "sandbox", the dashboard builds the iframe srcDoc with a bootstrap script that runs before your css and js. That script assigns a frozen copy of $session on the iframe’s window, including query(path).

• Your layout js runs inside the iframe and can use $session and $session.query(...) the same way as in inline mode.
• The copy is a snapshot at iframe render time. When the user changes realm, or layout/payload updates, the iframe remounts with a new snapshot (not live postMessage yet).
• The sandbox uses sandbox="allow-scripts" without allow-same-origin, so iframe script cannot read the parent dashboard DOM, cookies, or localStorage.

Inline mode uses the parent page’s window.$session directly (live reference, full page access).

API reference

payload by generation (not normalized)

HEAT does not map Legacy keys into Next shapes inside $session.payload. Inspect defensively:

if ($session.generation === "next" && $session.payload && $session.payload["$heat-dataservice"]) {
  var realms = $session.payload["$heat-dataservice"].realms || [];
  // prototype-only: list realm names
} else if ($session.generation === "legacy" && $session.payload) {
  var keys = Object.keys($session.payload);
}

For production analytics UI, prefer layout channels + a built-in widget consuming the ingested data service, not manual payload parsing in CustomRenderer.

Practical authoring workflow

1. Confirm a built-in widget cannot do the job (see When to use something else).
2. Ship the dashboard node so layout and payload exist; open a session analysis page in the target generation (Next vs Legacy).
3. Inspect in the browser console (same generation as your users):
   • $session.generation, $session.title, $session.query('layoutConfiguration')
   • Object.keys($session.payload || {})
   • On Next: $session.query('payload.$heat-dataservice.realms') if present
4. Prototype in sandbox with small html / css / js in customRendererItem; keep renderMode: "sandbox".
5. Harden or replace with a node template + channel + manifest widget before calling the layout production-ready.

Script examples

Header line from session metadata (sandbox or inline):

document.getElementById("hdr").textContent =
  $session.title + " ,  " + ($session.query("scenarioInstance.scenarioName") || "");

List realm names from stored Next payload (sandbox):

var ds = $session.query("payload.$heat-dataservice");
var names = (ds && ds.realms) ? ds.realms.map(function (r) { return r.name; }) : [];
document.getElementById("realms").textContent = names.join(", ") || "(none)";

Read layout playback setting:

var enabled = $session.query("layoutConfiguration.enableGlobalPlaybackControls");

Limitations

Security matrix

Layout JSON is trusted-author input. There is no HTML sanitizer: isolation mode is the control.

Air-gapped deployments: embed CSS and JS in layout JSON. CDN scripts will not load without outbound network.

Inline mode logs a dev-only console warning. Script errors show an in-widget error state instead of crashing the whole session page.

Implementation notes

• Session analysis pages wrap the layout grid with SessionPageContextProvider.
• Sandbox srcDoc order: session bootstrap → css → html body → your js.
• Closing </script> in layout js is escaped in srcDoc so the document stays well-formed.
• Prefer small layout JSON; large scripts are hard to review and slow to load.

Related

• Next dashboard components index
• Dataservice migration status , layout-only widget
• dashboard-v2 upstream contract , canonical channel shapes for built-in widgets
• Legacy dashboard components , mount ids and v1 payload keys
• Reference JSON: tools/arbex/reference/next/CustomRenderer.json
• Arbex RAG: tools/arbex/rag/reference/components/CustomRenderer.md
• Layout schema: ui/dashboard/src/lib/data-service/data-lib/heat-client/docs/heat-layout-schema.json