graphein-mcp 0.16.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphein-mcp",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "type": "module",
   "description": "Model Context Protocol server for Graphein — wraps generate → validate → repair → render → critique into one tool call, and serves Graphein's schema + agent guide as resources so a model that never saw the API can still build correct charts.",
   "license": "MIT",
@@ -61,9 +61,9 @@
     "prepack": "tsup"
   },
   "dependencies": {
-    "@graphein/node": "^0.16.2",
+    "@graphein/node": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.20.0",
-    "graphein": "^0.16.2",
+    "graphein": "^0.17.0",
     "zod": "^3.23.0"
   }
 }

package/resources/agent-guide.md

@@ -621,6 +621,24 @@ optional `seed`. Reach for it for a casual, low‑fidelity, "napkin sketch" feel
 (brainstorms, draft dashboards, playful reports); keep it off for precise/formal
 charts. The output is deterministic, so the same spec always looks identical.
 
+## Debug mode
+
+Add `"debug": true` to **any** spec to replace the chart with an interactive **debug
+view** — a diagnostic layout that visualizes the spec and its data instead of drawing
+the chart. It composes a **live preview** of the real chart with the resolved **spec**
+(collapsible JSON), a **data** sample (with inferred column types + row count), the
+**validation** errors/warnings, the **render report** diagnostics, and the NL
+**summary**. The original `type` is preserved, so clearing the flag restores the chart.
+
+```jsonc
+{ "type": "bar", "data": [/* … */], "encoding": { "x": { "field": "q" }, "y": { "field": "v" } }, "debug": true }
+```
+
+Pass an object to narrow it: `sections` (`preview`|`spec`|`data`|`validation`|`report`|
+`summary`) and `rows` (data-sample cap). Reach for it when a chart doesn't look right and
+you want to see exactly what the spec resolved to. It's a browser/DOM view; headless PNG
+export gets a plain-text fallback, and `chart.report()` still reflects the real chart.
+
 ## Validation & gotchas
 
 - **`encoding` is required** for `line`/`area`/`bar`/`scatter`/`box` (`x`+`y`), `pie`

package/resources/chart-spec.schema.json

@@ -409,6 +409,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -701,6 +712,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -997,6 +1019,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -1220,6 +1253,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -1412,6 +1456,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -1709,6 +1764,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -2000,6 +2066,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -2615,6 +2692,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -2688,6 +2776,36 @@
       "additionalProperties": true,
       "description": "A single data record (row). Agent-supplied data is an array of these."
     },
+    "DebugConfig": {
+      "type": "object",
+      "properties": {
+        "sections": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DebugSection"
+          },
+          "description": "Which panels to show, in order. Omit for all of them."
+        },
+        "rows": {
+          "type": "number",
+          "description": "Max number of data rows to list in the data table (default 50)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Debug-view options. Set `debug: true` on any spec to replace the chart with a diagnostic view, or pass this object to tune it. All fields are plain JSON so specs still round-trip through `JSON.stringify`. See BaseSpec.debug."
+    },
+    "DebugSection": {
+      "type": "string",
+      "enum": [
+        "preview",
+        "spec",
+        "data",
+        "validation",
+        "report",
+        "summary"
+      ],
+      "description": "Individual panels the debug view can render."
+    },
     "Dimensions": {
       "type": "object",
       "properties": {
@@ -2810,6 +2928,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -2982,6 +3111,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -3574,6 +3714,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -3784,6 +3935,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -4118,6 +4280,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -4368,6 +4541,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -4696,6 +4880,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -4940,6 +5135,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -5187,6 +5393,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -5444,6 +5661,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -5740,6 +5968,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -6021,6 +6260,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -6201,6 +6451,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -6480,6 +6741,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -6705,6 +6977,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -7022,6 +7305,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -7312,6 +7606,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -7845,6 +8150,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {
@@ -8169,6 +8485,17 @@
           ],
           "description": "Render the chart in a hand-drawn (\"sketch\") style — wobbly outlines, hachure fills, and a handwriting font. `true` uses the defaults; pass a `SketchConfig` to tune it. Omit (or `false`) for the default clean rendering."
         },
+        "debug": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/DebugConfig"
+            }
+          ],
+          "description": "Replace the chart with an interactive **debug view** — a live preview of the real chart alongside the resolved spec (JSON), a sample of the data (with inferred column types and row count), validation errors/warnings, render-report diagnostics, and the plain-English summary. `true` shows every panel; pass a DebugConfig to select panels or cap the data sample. Omit (or `false`) to render normally. The original `type` is preserved, so clearing the flag restores the chart. Rich HTML view in the browser; headless PNG export (`@graphein/node`) gets a simple text fallback."
+        },
         "params": {
           "type": "array",
           "items": {

package/resources/spec-reference.md

@@ -50,6 +50,7 @@ Runnable JSON for every chart type lives in [`docs/examples/`](./examples).
 - [Conditional formatting](#conditional-formatting)
 - [Themes](#themes)
 - [Sketch (hand-drawn) mode](#sketchconfig)
+- [Debug mode](#debugconfig)
 - [Format mini‑language](#format-mini-language)
 - [Enumerations](#enumerations)
 - [Runtime API](#runtime-api)
@@ -78,6 +79,7 @@ Shared by **all** chart types.
 | `padding` | `Partial<Insets>` | auto | Extra `{ top, right, bottom, left }` px around the plot. |
 | `background` | `string` | theme bg | CSS color override for the chart surface. |
 | `sketch` | `boolean \| SketchConfig` | `false` | Render with the hand‑drawn ("sketch") look — wobbly outlines, hachure fills, and a handwriting font (see [`SketchConfig`](#sketchconfig)). |
+| `debug` | `boolean \| DebugConfig` | `false` | Replace the chart with a **debug view** — live preview + resolved spec + data sample + validation + report + summary (see [`DebugConfig`](#debugconfig)). |
 | `params` | `SelectionParam[]` | — | Named selections this visual **publishes** (click/brush/slicer). See [Interactivity](#interactivity-selection--highlight--filter). |
 | `highlight` | `HighlightConfig \| HighlightConfig[]` | — | Emphasize rows matching a param; dim the rest. An array unions sources. |
 | `filter` | `FilterClause[]` | — | Subset rows to those matching **every** clause (a `{ param }` or a literal predicate). |
@@ -135,6 +137,45 @@ sketch charts are safe to snapshot/screenshot‑test. Turning sketch off restore
 default crisp rendering path exactly (zero cost when unused — the font and engine are
 code‑split and only loaded on the sketch path).
 
+### `DebugConfig`
+
+Set **`debug: true`** on *any* spec to swap the chart for an interactive **debug
+view** — a diagnostic panel layout that visualizes the spec and its data instead of
+drawing the chart. The original `type` is preserved, so removing the flag restores
+the chart exactly. Useful for inspecting *why* a chart renders the way it does.
+
+The view shows, side by side:
+
+- **Live preview** — the real chart, rendered from the same spec with debug off.
+- **Summary** — the deterministic natural‑language one‑liner ([`summarize`](#render-report)).
+- **Validation** — every `error`/`warning` from [`validateSpec`](#validation--linting).
+- **Render report** — [`RenderReport`](#render-report) diagnostics (mark count, clipped
+  labels, low‑contrast colors, …) for the previewed chart.
+- **Spec** — the resolved spec as syntax‑highlighted, collapsible JSON (the `data`
+  array is summarized to a row count; see the Data panel for the rows).
+- **Data** — a scrollable table of the rows with inferred per‑column types and the
+  total row/column count.
+
+Pass an object to narrow it:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `sections` | `('preview' \| 'spec' \| 'data' \| 'validation' \| 'report' \| 'summary')[]` | all | Which panels to show, in order. |
+| `rows` | `number` | `50` | Max data rows listed in the Data panel (the true total is always shown). |
+
+```jsonc
+// Everything
+{ "type": "bar", "data": [/* … */], "encoding": { /* … */ }, "debug": true }
+
+// Just the resolved spec + a 10-row data sample
+{ "type": "line", "data": [/* … */], "encoding": { /* … */ }, "debug": { "sections": ["spec", "data"], "rows": 10 } }
+```
+
+The debug view is a **browser/DOM** experience (rich HTML panels). Headless PNG export
+(`@graphein/node`) instead paints a plain‑text fallback (type + validation summary +
+spec JSON). `chart.report()` on a debug chart returns the *underlying* chart's report,
+so programmatic diagnostics keep working.
+
 ---
 
 ## Encoding & `FieldDef`