@databrainhq/mcp-server 0.3.0-rc.4 → 0.3.0-rc.5

package/dist/custom-chart/runtime-shim.js

@@ -0,0 +1,146 @@
+/*
+ * Databrain custom chart runtime shim (DAT-925).
+ *
+ * The CLI (`databrain custom-chart build`) prepends this file, byte for byte,
+ * to the author's bundled IIFE. It is plain ES2020 with no imports so it runs
+ * inside the sandbox frame exactly as written. The plugin keeps a copy at
+ * `packages/@databrainhq/plugin/src/customChart/runtimeShim.js` and tests it;
+ * `contract/runtime-shim.js` in the fleet folder is the same bytes.
+ *
+ * Contract with the author bundle (see the authoring guide):
+ *   - The bundle assigns `globalThis.__dbnCustomChart = { render, resize? }`.
+ *   - The CLI may prepend `globalThis.__dbnCustomChartSlots = [...slot ids]`
+ *     so every manifest slot is present on `ctx.slots`, unbound ones as `[]`.
+ *   - `render(ctx)` runs on the first data message and on every data change.
+ *   - `resize(ctx)` runs on window resize when the author defines it;
+ *     otherwise `render(ctx)` runs again (one call per animation frame).
+ *   - Inside the frame, `dbnChart.click(rowIndex, columnId)`,
+ *     `dbnChart.filter(columnId, values)` and `dbnChart.resize(height)` map
+ *     onto the sandbox protocol. There is no other host access.
+ *   - A throw (or a rejected promise) inside render/resize is reported to the
+ *     host once as `error/runtime`; the chart stops receiving data after it.
+ */
+(() => {
+  const sandbox = globalThis.dbnSandbox;
+  if (!sandbox || typeof sandbox.onData !== 'function') return;
+
+  const DEFAULT_THEME = Object.freeze({
+    fontFamily: 'system-ui, sans-serif',
+    fontSize: 12,
+    textColor: 'CanvasText',
+    textSecondaryColor: 'GrayText',
+    background: 'Canvas',
+    surfaceColor: 'Canvas',
+    borderColor: 'GrayText',
+    borderRadius: 8,
+    primaryColor: 'Highlight',
+    palette: [],
+  });
+
+  Object.defineProperty(globalThis, 'dbnChart', {
+    value: Object.freeze({
+      click(rowIndex, columnId) {
+        sandbox.click(rowIndex, columnId);
+      },
+      filter(columnId, values) {
+        sandbox.filter(columnId, Array.isArray(values) ? values : []);
+      },
+      resize(height) {
+        sandbox.resize(height);
+      },
+    }),
+    writable: false,
+    configurable: false,
+  });
+
+  let failed = false;
+  let latest = null;
+  let frame = 0;
+
+  const report = (error) => {
+    if (failed) return;
+    failed = true;
+    latest = null;
+    try {
+      console.error('[dbn custom chart] render failed:', error);
+    } catch {}
+    const message =
+      error && typeof error.message === 'string'
+        ? error.message
+        : String(error);
+    // The sandbox bootstrap listens for window "error" and reports it to the
+    // host as error/runtime. One event, then the chart is inert.
+    globalThis.dispatchEvent(new ErrorEvent('error', { error, message }));
+  };
+
+  const chart = () => {
+    const value = globalThis.__dbnCustomChart;
+    if (!value || typeof value.render !== 'function') {
+      throw new TypeError(
+        'The chart bundle did not assign globalThis.__dbnCustomChart = { render }.'
+      );
+    }
+    return value;
+  };
+
+  const slotsOf = (columns) => {
+    const slots = {};
+    const declared = globalThis.__dbnCustomChartSlots;
+    if (Array.isArray(declared)) {
+      for (const id of declared) if (typeof id === 'string') slots[id] = [];
+    }
+    columns.forEach((column, index) => {
+      const id = column?.slotId;
+      if (typeof id !== 'string') return;
+      if (!Array.isArray(slots[id])) slots[id] = [];
+      slots[id].push(index);
+    });
+    return slots;
+  };
+
+  const context = (data) => ({
+    container: document.getElementById('chart'),
+    data: { columns: data.columns, rows: data.rows },
+    slots: slotsOf(data.columns),
+    options: data.options,
+    theme: data.theme || DEFAULT_THEME,
+    language: typeof data.language === 'string' ? data.language : 'en',
+    dimensions: {
+      width: globalThis.innerWidth,
+      height: globalThis.innerHeight,
+    },
+  });
+
+  const run = (method, data) => {
+    if (failed) return;
+    let result;
+    try {
+      const value = chart();
+      const fn =
+        method === 'resize' && typeof value.resize === 'function'
+          ? value.resize
+          : value.render;
+      result = fn.call(value, context(data));
+    } catch (error) {
+      report(error);
+      return;
+    }
+    if (result && typeof result.then === 'function') {
+      result.then(undefined, report);
+    }
+  };
+
+  sandbox.onData((data) => {
+    latest = data;
+    run('render', data);
+  });
+
+  globalThis.addEventListener('resize', () => {
+    if (!latest || failed) return;
+    if (frame) return;
+    frame = globalThis.requestAnimationFrame(() => {
+      frame = 0;
+      if (latest) run('resize', latest);
+    });
+  });
+})();

package/dist/custom-chart/template/AGENTS.md

@@ -0,0 +1,374 @@
+# Databrain custom chart: author guide
+
+This folder is one custom chart type for Databrain. When it is uploaded and
+published, every builder in your company can pick it in the metric editor as
+chart type `custom:<key>` and put it on dashboards. The same guide is shipped
+as `AGENTS.md` (for coding agents) and `README.md` (for people); the two files
+are identical, and the `custom-chart` skill in `@databrainhq/agent-skills`
+carries a byte identical copy as `references/authoring-guide.md`.
+
+Read this file to the end before you change `chart.ts`.
+
+## 1. What a custom chart is
+
+A custom chart is a small package: a manifest that declares the data the chart
+needs and the settings it exposes, a TypeScript module that draws into a DOM
+element, an optional stylesheet and an icon. The CLI compiles the module into
+one self contained `dist/index.js`. Databrain stores that file, serves it to
+dashboards, resolves the metric's data onto the slots you declared, and runs
+the bundle inside a sandboxed frame. The chart never sees a token, a query or
+a network. It only sees rows, options, a theme and a container.
+
+The lifecycle:
+
+1. `databrain custom-chart init my-chart` writes this folder.
+2. You edit `manifest.json` and `chart.ts`.
+3. `databrain custom-chart validate` checks the manifest and the icon.
+4. `databrain custom-chart build` writes `dist/`.
+5. `databrain custom-chart upload` creates the chart in your company as a
+   private chart, version 1. A second upload creates version 2 in preview
+   while live dashboards keep the published version.
+6. Publish (with `--publish`, the `publish_custom_chart` tool, or Settings >
+   Developers > Custom charts) makes a version live for every builder.
+
+## 2. Project structure
+
+```
+my-chart/
+  manifest.json        the contract: id, name, slots, options
+  chart.ts             export function render(ctx), optional resize(ctx)
+  chart.css            optional, uploaded next to the bundle; the host injects it into the frame
+  custom-chart.d.ts    the CustomChartContext types (do not edit)
+  icon.svg             required, at most 16 KiB, no script or external references
+  sample-data.json     optional, used by `dev` and by the in app preview
+  package.json         scripts: validate, build, dev, upload
+  tsconfig.json        editor settings so chart.ts type checks
+  AGENTS.md            this guide
+  README.md            this guide
+  dist/                written by build, never edit by hand
+    index.js           the shim plus your compiled module (upload this)
+    manifest.json      the validated manifest
+    icon.svg           the sanitized icon
+    index.css          the raw chart.css, uploaded as bundleCss
+    bundle.zip         the four files above, for drag and drop upload in the app
+```
+
+Only `chart.ts` may import other files. You can add more `.ts` files next to
+it and import them with a relative path. You can also `npm install` a browser
+library and import it; the build bundles it. There is no `external`: whatever
+you import ends up inside `index.js`, and the whole file must stay under 2 MiB.
+
+## 3. The manifest
+
+`manifest.json` is checked with the same rules in the CLI, in the MCP tools, on
+the server and in the dashboard runtime. Unknown keys are refused at every
+level. Every error carries a code shaped `manifest.<path>.<reason>`, a JSON
+path and a sentence that says what to change.
+
+```json
+{
+  "schemaVersion": 2,
+  "id": "revenue-bars",
+  "name": "Revenue bars",
+  "version": "1.2.0",
+  "description": "Bars with a target line.",
+  "slots": [
+    { "id": "category", "label": "Category", "role": "dimension", "types": ["string"], "required": true,
+      "description": "One bar per value." },
+    { "id": "value", "label": "Value", "role": "measure", "types": ["number"], "required": true },
+    { "id": "target", "label": "Target", "role": "measure", "types": ["number"], "required": false }
+  ],
+  "options": [
+    { "id": "show_labels", "label": "Show labels", "type": "boolean", "default": true, "group": "Labels" },
+    { "id": "bar_radius", "label": "Corner radius", "type": "number", "default": 4, "min": 0, "max": 20, "step": 1 },
+    { "id": "subtitle", "label": "Subtitle", "type": "string", "default": "", "maxLength": 120 },
+    { "id": "mode", "label": "Mode", "type": "select", "default": "grouped",
+      "choices": [ { "value": "grouped", "label": "Grouped" }, { "value": "stacked", "label": "Stacked" } ] },
+    { "id": "bar_color", "label": "Bar colour", "type": "color", "default": "#3366cc" }
+  ],
+  "translations": {
+    "fr": {
+      "name": "Barres de revenus",
+      "slots": { "category": { "label": "Categorie" } },
+      "options": { "mode": { "label": "Mode", "choices": { "grouped": "Groupe", "stacked": "Empile" } } }
+    }
+  }
+}
+```
+
+### 3.1 Top level keys
+
+| Key | Required | Rule |
+| --- | --- | --- |
+| `schemaVersion` | yes | `1` or `2`. Use `2`. Version 1 is the older sandbox manifest and does not allow `version`, `description`, `translations`, the `color` type, `step`, `group` or slot descriptions. |
+| `id` | yes | The chart key. `^[a-z][a-z0-9_-]{0,63}$`. The chart type becomes `custom:<id>`. Changing it later creates a different chart. |
+| `name` | yes | 1 to 256 characters. Shown in the chart picker. |
+| `version` | no | Semver such as `1.2.0`. A label for you; Databrain numbers versions itself (1, 2, 3). |
+| `description` | no | Up to 500 characters. |
+| `slots` | yes | 1 to 16 slots with unique ids. See 3.2. |
+| `options` | yes | 0 to 32 options with unique ids. Use `[]` for none. See 3.3. |
+| `translations` | no | Per language overrides. See 3.4. |
+
+The whole file must be at most 32 KiB as JSON.
+
+### 3.2 Slots
+
+A slot is one place where a builder binds a column of the metric. In the
+metric editor each slot becomes a select: dimension slots list the metric's
+dimension columns, measure slots list its measure columns.
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `id` | yes | `^[a-z][a-z0-9_-]{0,63}$`, unique across slots. This is the key you read in `ctx.slots`. |
+| `label` | yes | 1 to 256 characters. |
+| `role` | yes | `"dimension"` (a category, a date, a flag) or `"measure"` (a number to aggregate). |
+| `types` | yes | 1 to 3 unique values from `"string"`, `"number"`, `"boolean"`. A measure slot must be exactly `["number"]`. Dates arrive as ISO strings, so a date slot is `["string"]`. |
+| `required` | yes | `true` when the chart cannot draw without it. The editor marks required slots and refuses to save without them. |
+| `description` | no | Up to 256 characters, shown as help text. |
+
+One slot binds one column. If a chart needs several series, declare several
+slots (`value_1`, `value_2`) or one measure slot and one dimension slot that
+splits the series. There is no "multiple" slot.
+
+### 3.3 Options
+
+Options are the settings a builder changes in the chart settings panel. Their
+values reach the chart as `ctx.options[id]`, already merged with the defaults,
+so you never need to check for a missing option.
+
+Every option has `id` (`^[a-z][a-z0-9_-]{0,63}$`, unique), `label` (1 to 256
+characters), `type`, `default` and an optional `group` (up to 64 characters;
+options with the same group render as one section).
+
+| `type` | Extra fields | Default rule | Rendered as |
+| --- | --- | --- | --- |
+| `boolean` | none | `true` or `false` | a switch |
+| `number` | `min`, `max` (required, finite, `min <= max`), `step` (optional, positive, at most `max - min`) | a finite number inside `[min, max]` | a number input |
+| `string` | `maxLength` (1 to 1024) | a string no longer than `maxLength` | a text input |
+| `select` | `choices`: 1 to 32 of `{ "value", "label" }`, values unique and shaped like ids | one of the choice values | a select |
+| `color` | none | `#rrggbb` (six hex digits) | the colour picker |
+
+The id `theme` and any id that starts with `theme.` are reserved and refused
+with `manifest.option.reserved`. The host theme arrives on `ctx.theme`, not as
+an option.
+
+### 3.4 Translations
+
+`translations` is an object keyed by language code (`^[a-z]{2}(-[A-Z]{2})?$`,
+for example `fr` or `pt-BR`). Each entry may override `name`, `description`,
+`slots.<slotId>.label`, `slots.<slotId>.description`, `options.<optionId>.label`,
+`options.<optionId>.group` and `options.<optionId>.choices.<value>`. Every
+referenced slot, option and choice must exist in the manifest, and every
+string is 1 to 256 characters. The editor uses the builder's language;
+`ctx.language` tells the chart which language the viewer has.
+
+### 3.5 Error codes you will meet
+
+| Code | Meaning |
+| --- | --- |
+| `manifest.schemaVersion.unsupported` | `schemaVersion` is not 1 or 2. |
+| `manifest.unknownKey` | A key that is not in the table above (or a v2 key on a v1 manifest). |
+| `manifest.id.invalid` | The id does not match the pattern. Lowercase, no spaces. |
+| `manifest.slots.empty`, `manifest.slots.tooMany` | Declare 1 to 16 slots. |
+| `manifest.slot.types` | A measure slot must be exactly `["number"]`, or a type is not string, number or boolean. |
+| `manifest.slot.duplicate` | Two slots share an id. |
+| `manifest.option.type` | Unknown option type, or `color` on schemaVersion 1. |
+| `manifest.option.reserved` | The option id is `theme` or starts with `theme.`. |
+| `manifest.option.default` | The default is outside the range, longer than `maxLength` or not a choice. |
+| `manifest.option.step` | `step` is not positive or is larger than `max - min`. |
+| `manifest.option.color` | The colour default is not `#rrggbb`. |
+| `manifest.option.duplicate` | Two options share an id. |
+| `manifest.translations.language` | A key is not a language code. |
+| `manifest.translations.slot`, `.option`, `.choice` | A translation names something the manifest does not declare. |
+| `manifest.size` | The manifest is over 32 KiB as JSON. Reported once every other rule passes. |
+| `bundle.icon.required`, `bundle.icon.size`, `bundle.icon.notSvg`, `bundle.icon.unsafe` | The icon is missing, over 16 KiB, not one `<svg>` element, or breaks a rule from section 7 (the message names the rule). |
+| `bundle.js.size` | `dist/index.js` is over 2 MiB. |
+| `bundle.css.size` | `chart.css` is over 256 KiB. |
+| `bundle.build.failed` | esbuild could not compile `chart.ts`; the message is the compiler's. An import that does not resolve inside the project (a node builtin, a path outside the folder) is this too. |
+| `bundle.build.noRender` | `chart.ts` is not an ES module with a named `render` export. `module.exports` and `export default` are not read. |
+
+## 4. The data your chart receives
+
+Databrain calls `render(ctx)` with one `CustomChartContext` (see
+`custom-chart.d.ts`):
+
+```ts
+import type { CustomChartContext } from '@databrainhq/custom-chart-types';
+
+export function render({ container, data, slots, options, theme, language, dimensions }: CustomChartContext): void {
+  // draw into container
+}
+
+export function resize(ctx: CustomChartContext): void {
+  // optional; without it render runs again on every size change
+}
+```
+
+| Field | What it is |
+| --- | --- |
+| `container` | The `HTMLElement` to draw into. It fills the tile. Clear it before drawing again (`container.replaceChildren()`); render runs again on every data update. |
+| `data.columns` | One entry per bound column, in manifest slot order: `{ id, label, type, filterable, slotId }`. `id` is what you pass to `dbnChart.click` and `dbnChart.filter`. `filterable` is true on dimension columns. |
+| `data.rows` | An array of rows, each an array of cells aligned with `data.columns`. Cells are `string`, `number`, `boolean` or `null`. Row order is the metric's order. Rows are already tenant scoped. At most 5000 rows and 64 columns reach the chart. |
+| `slots` | `slotId -> number[]`, the indexes into `data.columns` bound to that slot. An optional slot that is not bound gives `[]`. Read columns through slots, never by position. |
+| `options` | The option values, defaults merged with what the builder saved. |
+| `theme` | The flat host theme (section 5). |
+| `language` | The viewer's language code, for example `en` or `fr`. |
+| `dimensions` | `{ width, height }` of the container in CSS pixels at the time of the call. |
+
+A typical start of `render`:
+
+```ts
+const categoryIndex = ctx.slots.category[0];
+const valueIndex = ctx.slots.value[0];
+const targetIndex = ctx.slots.target[0];   // undefined when the optional slot is empty
+for (const row of ctx.data.rows) {
+  const label = String(row[categoryIndex] ?? '');
+  const value = typeof row[valueIndex] === 'number' ? row[valueIndex] : 0;
+}
+```
+
+Numbers arrive as numbers, not strings. Dates arrive as ISO strings; parse
+them with `new Date(value)` if you need a time axis. Booleans arrive as
+booleans. Null means no value: draw a gap, not a zero, unless the chart says
+otherwise.
+
+`sample-data.json` uses the same shape (`columns`, `rows`, optional
+`options`) and is what `databrain custom-chart dev` and the in app preview
+feed to the chart. Keep it small and realistic.
+
+## 5. Theme
+
+`ctx.theme` is derived from the dashboard's resolved theme so a custom chart
+looks like the charts around it. Every key is always present; when a host
+sends no theme at all, the shim supplies a neutral default with an empty
+palette, so fall back to `primaryColor` when `palette` is empty.
+
+| Key | Type | Use it for |
+| --- | --- | --- |
+| `fontFamily` | string | Text. |
+| `fontSize` | number (px) | The base text size. Axis labels are usually `fontSize * 0.9`. |
+| `textColor` | string | Titles, values, primary text. |
+| `textSecondaryColor` | string | Axis labels, subtitles, hints. |
+| `background` | string | The tile background. Set it on the container if you paint one. |
+| `surfaceColor` | string | Cards, tooltips, legends. |
+| `borderColor` | string | Axis lines, gridlines, borders. |
+| `borderRadius` | number (px) | Corners. |
+| `primaryColor` | string | The accent colour. |
+| `palette` | string[] | Series colours in order. At least one entry, at most 32. |
+
+Use the theme first and your own colours second. A `color` option is the
+right way to let a builder override one colour; a hard coded `#ff0000` in
+`chart.ts` is not. Do not read `prefers-color-scheme`: the host decides.
+
+`chart.css` is uploaded next to the bundle (`bundleCss`) and the host injects
+it into the frame as a style element, so class names cannot clash with the
+host page. It cannot load fonts, images or any `url(...)`; the sandbox blocks
+network access.
+
+## 6. Interactions
+
+Inside the chart a global `dbnChart` is available (typed in
+`custom-chart.d.ts`). Every call is an event to the host; the host decides
+what happens, and nothing in the chart can navigate, fetch or write.
+
+| Call | Effect on the dashboard |
+| --- | --- |
+| `dbnChart.click(rowIndex, columnId)` | The tile's data point click. `rowIndex` indexes `data.rows`; the host reads the row's slot values and passes them to the embedding app's `onDataPointClick`. |
+| `dbnChart.filter(columnId, values)` | Cross filter the dashboard on that column when it is `filterable` and the values are in the current rows. At most 100 values. An empty list clears the filter. Ignored otherwise. |
+| `dbnChart.resize(height)` | Ask the host for a different tile height, 80 to 1200 pixels. Width always belongs to the host. |
+
+Bind them to real user actions (click, keyboard), never call them in a loop.
+The host caps events at 60 per second and drops the rest.
+
+## 7. Icon
+
+`icon.svg` shows in the chart picker and in Settings. Rules, checked at build
+and again on upload:
+
+- One `<svg>` element, at most 16 KiB.
+- No `<script>`, no `<foreignObject>`, no `<image>`, no `on*=` attributes.
+- No `url(...)` in styles or attributes except `url(#id)`, no `href` that does not start with `#`.
+- No comments, no DOCTYPE, no CDATA, no animation elements, and only the standard SVG
+  drawing attributes (an editor's `inkscape:` or `sodipodi:` attributes are refused).
+  The build strips the XML declaration and comments for you; the upload does not.
+- Use `currentColor` for strokes and fills so the icon follows the UI theme.
+
+The template icon is a 24 by 24 outline on a 2 pixel stroke. Keep that size.
+
+## 8. Build, upload, publish
+
+```
+databrain custom-chart validate            # manifest, icon, css. No compile.
+databrain custom-chart build               # esbuild, writes dist/
+databrain custom-chart dev                 # local page on http://127.0.0.1:4174
+databrain custom-chart upload              # build, server validate, plan, confirm, upload
+databrain custom-chart upload --publish    # same, then publish that version
+databrain custom-chart upload --yes        # no confirmation prompt (CI)
+```
+
+`build` compiles `chart.ts` with esbuild (`format: iife`, `target: es2020`,
+minified, everything bundled), prepends the Databrain runtime shim and the
+list of slot ids, checks the manifest and the icon, enforces 2 MiB and writes
+`dist/`. The shim is the only code between your module and the sandbox: it
+receives the data message, builds the context, calls your `render` and
+`resize` (once per animation frame on resize), and maps `dbnChart` to the
+sandbox protocol. If `render` throws or returns a rejected promise, the shim
+reports it to the host once and the chart stops receiving data. Do not edit
+`dist/index.js`.
+
+`upload` needs `DATABRAIN_SERVICE_TOKEN` (Settings > Service Tokens) and, on
+self hosted instances, `DATABRAIN_API_URL`. It builds, asks the server to
+validate, prints the plan (`will create chart` or `will create version n`),
+waits for `y`, then uploads. The first upload creates the chart with status
+Private and version 1. Every later upload with different content creates the
+next version in preview; the same content is recognised by its hash and
+creates nothing. Live dashboards keep rendering the published version until
+someone publishes the preview.
+
+Publishing is the one step that changes what customers see. Do it with
+`--publish`, with the `publish_custom_chart` MCP tool (dry run first, then
+`confirm: "APPLY_TO_PRODUCTION"`), or in Settings > Developers > Custom charts.
+
+From an agent, the same steps are the MCP tools `custom_chart_scaffold`,
+`custom_chart_validate`, `custom_chart_upload` (dry run, then apply with the
+confirmation string) and `publish_custom_chart`. The tools never write to disk
+and never publish without the confirmation.
+
+## 9. Writing a good chart
+
+- Draw with plain DOM or SVG when you can. A dependency is fine when it earns
+  its bytes; check the size line that `build` prints.
+- Read columns through `ctx.slots`, never by position, and handle an empty
+  optional slot (`[]`).
+- Clear the container at the top of `render`. The host calls it again on
+  every data update and, without `resize`, on every size change.
+- Use `ctx.dimensions` for the drawing size and `ctx.theme` for every colour
+  and font you do not expose as an option.
+- Format numbers with `Intl.NumberFormat(ctx.language)`.
+- Show a short message when the required data is missing instead of throwing.
+  A thrown error is reported to the host once, the tile shows a generic
+  failure and the chart receives no more data.
+- Keep `render` under a few milliseconds for 5000 rows. Avoid layout reads in
+  a loop.
+- Do not touch `window.parent`, `document.cookie`, `fetch`, `localStorage` or
+  timers that outlive a render. The sandbox blocks them and a reviewer will
+  reject the chart.
+
+## 10. Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `manifest.unknownKey` at `/version` | The manifest says `schemaVersion: 1`. Set it to `2`. |
+| `manifest.slot.types` at `/slots/N/types` | A measure slot lists something other than `["number"]`. Change the role to `dimension` or the types to `["number"]`. |
+| `manifest.option.reserved` | Rename the option; `theme` is the host theme. |
+| `bundle.build.failed` with a TypeScript message | esbuild reports the file and line. It does not type check; run `npx tsc -p tsconfig.json` in the project for types. |
+| `bundle.js.size` | A dependency is too big. Import only what you use, or draw it yourself. |
+| `bundle.icon.unsafe` | Export the icon again without links, images, styles with `url(...)` or scripts. Inline the paths. |
+| The chart is blank in `dev` | The events panel shows `error` with code `runtime` and the browser console shows `[dbn custom chart] render failed:` with the error. Fix it and reload. |
+| The chart draws once and never updates | `render` does not clear the container, or it caches the first rows. Clear and redraw from `ctx` each time. |
+| Labels are unreadable on a dark dashboard | Colours are hard coded. Use `ctx.theme.textColor` and `ctx.theme.palette`. |
+| Clicks do nothing on the dashboard | `dbnChart.click` was given a row index that is not in `data.rows`, or the embedding app has no `onDataPointClick`. |
+| `upload` says `DATABRAIN_SERVICE_TOKEN is not set` | Export the token in the shell that runs the command. Never write it into a file in the project. |
+| `upload` says the server refused the bundle | The server runs the same rules; the printed problems name the path to fix. Rebuild and upload again. |
+| Dashboards still show the old chart after upload | Uploads land in preview. Publish the version. |
+| `This tile uses a custom chart (custom:key) that is not published.` | The dashboard references a key that is private or missing in this company. Publish it, or pick another chart type. |