plotleaf 0.3.1 → 0.4.0

package/dist/cli.js

@@ -12,6 +12,7 @@ import { realpath as realpath2 } from "node:fs/promises";
 // src/compiler/diagnostics.ts
 import path from "node:path";
 
+// src/compiler/diagnostic-core.ts
 class Diagnostics {
   file;
   items = [];
@@ -51,9 +52,6 @@ class Diagnostics {
     return [...this.items].sort((a, b) => a.file.localeCompare(b.file, "en") || a.line - b.line || a.column - b.column || a.code.localeCompare(b.code, "en"));
   }
 }
-function displayPath(filename) {
-  return path.relative(process.cwd(), filename) || path.basename(filename);
-}
 function humanDiagnostics(items) {
   return items.map((d) => `${d.file}:${d.line}:${d.column} ${d.code}${d.severity === "warning" ? " (warning)" : ""}
 ${d.message}${d.hint ? `
@@ -62,9 +60,89 @@ ${d.hint}` : ""}`).join(`
 `);
 }
 
-// src/compiler/files.ts
-import path2 from "node:path";
-import { open, realpath, stat } from "node:fs/promises";
+// src/compiler/diagnostics.ts
+function displayPath(filename) {
+  return path.relative(process.cwd(), filename) || path.basename(filename);
+}
+
+// src/compiler/exploration-schema.ts
+import * as z from "zod";
+
+// src/shared/exploration.ts
+var valueKey = (value) => typeof value === "object" ? `${value.start}/${value.end}` : `${typeof value}:${String(value)}`;
+var explorationLimits = {
+  inputs: 6,
+  options: 20,
+  views: 32,
+  explorations: 4,
+  components: 512,
+  rows: 20000,
+  dataBytes: 8 * 1024 ** 2,
+  markdownBytes: 2 * 1024 ** 2,
+  jsonDepth: 32,
+  jsonContainers: 1e5
+};
+
+// src/compiler/exploration-schema.ts
+var id = z.string().regex(/^[a-z][a-z0-9_-]{0,47}$/).refine((value) => !["constructor", "prototype"].includes(value), "Reserved identifier.");
+var label = z.string().min(1).max(160);
+var date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/).refine((value) => {
+  const timestamp = Date.parse(`${value}T00:00:00Z`);
+  return Number.isFinite(timestamp) && new Date(timestamp).toISOString().slice(0, 10) === value;
+}, "Use a real ISO calendar date.");
+var range = z.strictObject({ start: date, end: date }).refine((value) => value.start <= value.end, "Range start must not follow its end.");
+var common = { id, label };
+var explorationInputSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    ...common,
+    type: z.enum(["select", "segmented", "text"]),
+    default: z.string().max(120),
+    options: z.array(z.strictObject({ value: z.string().max(120), label })).min(1).max(explorationLimits.options)
+  }),
+  z.strictObject({
+    ...common,
+    type: z.literal("number"),
+    default: z.number().finite(),
+    options: z.array(z.strictObject({ value: z.number().finite(), label })).min(1).max(explorationLimits.options)
+  }),
+  z.strictObject({
+    ...common,
+    type: z.literal("toggle"),
+    default: z.boolean()
+  }),
+  z.strictObject({
+    ...common,
+    type: z.literal("date-range"),
+    default: range,
+    options: z.array(z.strictObject({ value: range, label })).min(1).max(explorationLimits.options)
+  })
+]);
+var explorationSchema = z.strictObject({
+  inputs: z.array(explorationInputSchema).min(1).max(explorationLimits.inputs),
+  views: z.array(z.strictObject({
+    id,
+    label,
+    when: z.record(id, z.union([
+      z.string().max(120),
+      z.number().finite(),
+      z.boolean(),
+      range
+    ])),
+    markdown: z.string().min(1).max(1024 ** 2),
+    datasets: z.record(z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*\.json$/), z.array(z.record(z.string(), z.unknown())).max(1e4)).default({})
+  })).min(1).max(explorationLimits.views)
+});
+
+// src/compiler/parse.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkDirective from "remark-directive";
+import remarkFrontmatter from "remark-frontmatter";
+import { parseDocument, visit } from "yaml";
+import * as z3 from "zod";
+
+// src/compiler/registry.ts
+import * as z2 from "zod";
 
 // src/shared/limits.ts
 var limits = {
@@ -85,182 +163,6 @@ var limits = {
   imagePixels: 4000000
 };
 
-// src/compiler/files.ts
-class LocalFileError extends Error {
-  kind;
-  constructor(kind, message) {
-    super(message);
-    this.kind = kind;
-  }
-}
-function contained(root, filename) {
-  const relative = path2.relative(root, filename);
-  return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
-}
-async function readBytesBounded(filename, maximum) {
-  if (!(await stat(filename)).isFile())
-    throw new Error("Expected a regular file.");
-  const file = await open(filename, "r");
-  try {
-    const info = await file.stat();
-    if (!info.isFile())
-      throw new Error("Expected a regular file.");
-    if (info.size > maximum)
-      throw new Error(`File exceeds the ${Math.floor(maximum / 1024)} KiB size limit.`);
-    const chunks = [];
-    let bytes = 0;
-    while (bytes <= maximum) {
-      const buffer = Buffer.alloc(Math.min(64 * 1024, maximum + 1 - bytes));
-      const result = await file.read(buffer, 0, buffer.length, null);
-      if (!result.bytesRead)
-        break;
-      chunks.push(buffer.subarray(0, result.bytesRead));
-      bytes += result.bytesRead;
-    }
-    if (bytes > maximum)
-      throw new Error("File grew beyond the size limit while reading.");
-    return Buffer.concat(chunks, bytes);
-  } finally {
-    await file.close();
-  }
-}
-async function readBounded(filename, maximum) {
-  const bytes = await readBytesBounded(filename, maximum);
-  return {
-    text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
-    bytes: bytes.length
-  };
-}
-
-class ReportFiles {
-  root;
-  dependencies;
-  usedBytes;
-  constructor(root, dependencies, usedBytes) {
-    this.root = root;
-    this.dependencies = dependencies;
-    this.usedBytes = usedBytes;
-  }
-  async resolve(reference, extensions) {
-    const fail = (message) => {
-      throw new LocalFileError("path", message);
-    };
-    if (path2.isAbsolute(reference) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(reference) || reference.includes("\\") || /%[\da-f]{2}/i.test(reference) || reference.includes("\x00"))
-      fail(`Use a plain relative local ${extensions.join("/")} path.`);
-    const candidate = path2.resolve(this.root, reference);
-    const hidden = (filename) => path2.relative(this.root, filename).split(path2.sep).some((part) => part.startsWith("."));
-    if (!contained(this.root, candidate))
-      fail("Reference escapes the report directory.");
-    if (hidden(candidate))
-      fail("Hidden files and directories are not allowed.");
-    if (!extensions.includes(path2.extname(candidate).toLowerCase()))
-      fail(`Use a ${extensions.join("/")} file.`);
-    this.dependencies.add(candidate);
-    let canonical;
-    try {
-      canonical = await realpath(candidate);
-    } catch {
-      throw new LocalFileError("read", "Cannot read the referenced file. Create it or correct the reference.");
-    }
-    if (!contained(this.root, canonical) || hidden(canonical))
-      fail("The resolved file or symlink escapes the permitted report files.");
-    if (!extensions.includes(path2.extname(canonical).toLowerCase()))
-      fail(`The resolved file must also have a ${extensions.join("/")} extension.`);
-    this.dependencies.add(canonical);
-    return canonical;
-  }
-  async read(filename, maximum) {
-    const bytes = await readBytesBounded(filename, Math.min(maximum, limits.totalBytes - this.usedBytes));
-    this.usedBytes += bytes.length;
-    return bytes;
-  }
-}
-
-// src/compiler/images.ts
-import { createHash } from "node:crypto";
-import path3 from "node:path";
-import { imageSize } from "image-size";
-function formatOf(bytes) {
-  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
-    let offset = 8;
-    let data = false;
-    while (offset + 12 <= bytes.length) {
-      const size = bytes.readUInt32BE(offset);
-      const type = bytes.toString("ascii", offset + 4, offset + 8);
-      if (offset + size + 12 > bytes.length)
-        break;
-      if (offset === 8 && (type !== "IHDR" || size !== 13))
-        break;
-      if (type === "acTL")
-        throw new Error("Animated PNG is not supported; provide a static image.");
-      if (type === "IDAT" && size > 0)
-        data = true;
-      offset += size + 12;
-      if (type === "IEND") {
-        if (data && size === 0 && offset === bytes.length)
-          return "png";
-        break;
-      }
-    }
-    throw new Error("Incomplete or invalid PNG container.");
-  }
-  if (bytes.length >= 4 && bytes.readUInt16BE(0) === 65496 && bytes.readUInt16BE(bytes.length - 2) === 65497)
-    return "jpg";
-  throw new Error("Expected a static PNG or JPEG image with a matching file extension.");
-}
-
-class ImageResolver {
-  files;
-  attempted = new Set;
-  filesRead = new Map;
-  embedded = new Map;
-  constructor(files) {
-    this.files = files;
-  }
-  async load(reference) {
-    const requested = path3.resolve(this.files.root, reference);
-    if (!this.attempted.has(requested) && this.attempted.size >= limits.imageFiles)
-      throw new Error(`At most ${limits.imageFiles} local image references are supported.`);
-    this.attempted.add(requested);
-    const canonical = await this.files.resolve(reference, [
-      ".png",
-      ".jpg",
-      ".jpeg"
-    ]);
-    const cached = this.filesRead.get(canonical);
-    if (cached) {
-      if (path3.extname(reference).toLowerCase() === ".png" !== (cached.mime === "image/png"))
-        throw new Error("Image signature does not match its file extension.");
-      return cached;
-    }
-    if (this.filesRead.size >= limits.imageFiles)
-      throw new Error(`At most ${limits.imageFiles} local image files are supported.`);
-    const bytes = await this.files.read(canonical, limits.imageBytes);
-    const format = formatOf(bytes);
-    const expected = (name) => path3.extname(name).toLowerCase() === ".png" ? "png" : "jpg";
-    if (format !== expected(reference) || format !== expected(canonical))
-      throw new Error("Image signature does not match its file extension.");
-    let size;
-    try {
-      size = imageSize(bytes);
-    } catch {
-      throw new Error("Unsupported or damaged PNG/JPEG header.");
-    }
-    if (size.type !== format || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1)
-      throw new Error("Image must have valid positive raster dimensions.");
-    if (size.width > limits.imageDimension || size.height > limits.imageDimension || size.width * size.height > limits.imagePixels)
-      throw new Error(`Image exceeds ${limits.imageDimension} pixels per side or ${limits.imagePixels.toLocaleString("en-GB")} pixels in total. Resize the prepared asset.`);
-    const id = `plotleaf-image-${createHash("sha256").update(bytes).digest("hex")}`;
-    const image = this.embedded.get(id) ?? {
-      id,
-      mime: format === "png" ? "image/png" : "image/jpeg",
-      base64: bytes.toString("base64")
-    };
-    this.filesRead.set(canonical, image);
-    this.embedded.set(id, image);
-    return image;
-  }
-}
 // src/shared/payload.ts
 var funnelStatuses = {
   "on-target": "On target",
@@ -269,62 +171,682 @@ var funnelStatuses = {
   neutral: "Neutral"
 };
 
-// src/compiler/data.ts
-var reserved = new Set(["__proto__", "constructor", "prototype"]);
-function parseDate(value) {
-  const date = value.slice(0, 10);
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
-    return;
-  const day = Date.parse(`${date}T00:00:00.000Z`);
-  if (!Number.isFinite(day) || new Date(day).toISOString().slice(0, 10) !== date)
-    return;
-  if (value.length === 10)
-    return day;
-  if (!/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value))
-    return;
-  const timestamp = Date.parse(value);
-  return Number.isFinite(timestamp) ? timestamp : undefined;
-}
-
-class DataResolver {
-  root;
-  diagnostics;
-  dependencies;
-  cache = new Map;
-  files;
-  images;
-  constructor(root, diagnostics, dependencies, totalBytes = 0) {
-    this.root = root;
-    this.diagnostics = diagnostics;
-    this.dependencies = dependencies;
-    this.files = new ReportFiles(root, dependencies, totalBytes);
-    this.images = new ImageResolver(this.files);
-  }
-  async load(reference, block) {
-    const fail = (code, message, hint) => {
-      this.diagnostics.add(code, `${reference}: ${message}`, block.position, hint);
-      return;
-    };
-    let canonical;
-    try {
-      canonical = await this.files.resolve(reference, [".json"]);
-    } catch (error) {
-      return fail(error instanceof LocalFileError && error.kind === "path" ? "E_DATA_PATH" : "E_DATA_READ", error instanceof Error ? error.message : "Cannot resolve the dataset.", "Place prepared JSON within the report directory and correct the data property.");
-    }
-    let dataset = this.cache.get(canonical);
-    if (!dataset) {
-      if (this.cache.size >= limits.datasets)
-        return fail("E_DATA_LIMIT", `At most ${limits.datasets} datasets are supported.`);
-      let text;
-      try {
-        text = new TextDecoder("utf-8", { fatal: true }).decode(await this.files.read(canonical, limits.jsonBytes));
-      } catch (error) {
-        return fail("E_DATA_READ", error instanceof Error ? error.message : "Could not read data.");
-      }
-      let parsed;
-      try {
-        parsed = JSON.parse(text);
-      } catch {
+// src/compiler/registry.ts
+var text = z2.string().min(1).max(1000);
+var format = z2.string().regex(/^(number|percent|percentage-points|currency:[A-Z]{3})$/, "Use number, percent, percentage-points or currency:GBP (an ISO currency code).");
+var chart = {
+  data: text,
+  x: text,
+  y: text,
+  title: text,
+  format: format.default("number")
+};
+var line = z2.strictObject({
+  ...chart,
+  xType: z2.enum(["category", "date", "number"]).default("category"),
+  target: z2.number().finite().optional(),
+  targetLabel: text.optional()
+});
+var registry = {
+  explore: {
+    forms: ["leaf"],
+    children: [],
+    description: "Scoped native controls select complete agent-prepared views. No analytics or report JavaScript.",
+    schema: z2.strictObject({ data: text, title: text }),
+    dataRules: {
+      schema: z2.toJSONSchema(explorationSchema),
+      resolution: "Relative JSON bundle; inline view datasets override the same plain filename only within that view.",
+      limits: explorationLimits,
+      binding: "Every input affects exactly this exploration. Every view declares all input values. No matching combination hides the previous view."
+    },
+    example: '::explore{data="./regional-views.json" title="Regional performance"}'
+  },
+  grid: {
+    forms: ["container"],
+    children: [
+      "metric",
+      "line",
+      "area",
+      "bar",
+      "donut",
+      "funnel",
+      "table",
+      "callout"
+    ],
+    description: "A responsive row of one to four components.",
+    schema: z2.strictObject({
+      columns: z2.number().int().min(1).max(4).default(2)
+    }),
+    example: `:::grid{columns="4"}
+::metric{label="Teams" value="1492"}
+:::`
+  },
+  metric: {
+    forms: ["leaf"],
+    children: [],
+    description: "A prepared numeric value with optional comparison, direction and sentiment.",
+    schema: z2.strictObject({
+      label: text,
+      value: z2.number().finite(),
+      format: format.default("number"),
+      comparison: text.optional(),
+      direction: z2.enum(["up", "down", "flat"]).optional(),
+      sentiment: z2.enum(["positive", "negative", "neutral"]).default("neutral")
+    }),
+    example: '::metric{label="Conversion" value="0.103" format="percent"}'
+  },
+  line: {
+    forms: ["leaf"],
+    children: [],
+    description: "An interactive single-series line chart from local JSON.",
+    schema: line,
+    example: '::line{data="./usage.json" x="date" y="teams" xType="date" title="Active teams"}'
+  },
+  area: {
+    forms: ["leaf"],
+    children: [],
+    description: "A line chart with a restrained area fill.",
+    schema: line,
+    example: '::area{data="./usage.json" x="date" y="teams" xType="date" title="Active teams" target="1600"}'
+  },
+  bar: {
+    forms: ["leaf"],
+    children: [],
+    description: "An interactive category bar chart with a zero baseline.",
+    schema: z2.strictObject(chart),
+    example: '::bar{data="./errors.json" x="category" y="count" title="Errors by category"}'
+  },
+  donut: {
+    forms: ["leaf"],
+    children: [],
+    description: "A part-to-whole donut with a readable legend and native data table.",
+    schema: z2.strictObject({
+      data: text,
+      category: text,
+      value: text,
+      title: text,
+      format: format.default("number")
+    }),
+    dataRules: {
+      category: "Unique nonblank strings of at most 1000 characters; source order is preserved.",
+      value: "Finite nonnegative numbers with a finite sum. Nulls and numeric strings are invalid. All-zero values show an empty state.",
+      maximumRows: limits.donutSlices
+    },
+    example: '::donut{data="./plans.json" category="plan" value="teams" title="Teams by plan"}'
+  },
+  funnel: {
+    forms: ["leaf"],
+    children: [],
+    description: "Ordered stage/progress rows with prepared values, denominators, shares and optional explicit status. Works without JavaScript.",
+    schema: z2.strictObject({
+      data: text,
+      stage: text,
+      value: text,
+      total: text,
+      share: text,
+      status: text.optional(),
+      title: text,
+      format: format.default("number")
+    }),
+    dataRules: {
+      stage: "Unique nonblank strings of at most 1000 characters; source order is preserved.",
+      value: "Finite nonnegative number no greater than its row's total.",
+      total: "Finite positive denominator supplied per row. No denominator is inferred from adjacent stages.",
+      share: "Prepared ratio from 0 to 1, matching value / total to within 0.0005 (rounding to 0.1 percentage point).",
+      status: Object.keys(funnelStatuses),
+      maximumRows: limits.funnelStages
+    },
+    example: '::funnel{data="./funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}'
+  },
+  table: {
+    forms: ["leaf", "container"],
+    children: ["column"],
+    description: "A semantic sortable table, with inferred or explicitly formatted columns.",
+    schema: z2.strictObject({ data: text, title: text.optional() }),
+    example: `:::table{data="./plans.json" title="By plan"}
+::column{field="plan" label="Plan"}
+::column{field="change" label="Δ QoQ" format="percent" sign="always"}
+:::`
+  },
+  column: {
+    forms: ["leaf"],
+    children: [],
+    description: "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
+    schema: z2.strictObject({
+      field: text,
+      label: text.optional(),
+      kind: z2.enum(["scalar", "image", "sparkline"]).optional(),
+      alt: text.optional(),
+      sortBy: text.optional(),
+      format: format.optional(),
+      sign: z2.enum(["auto", "always"]).default("auto"),
+      semantics: z2.enum(["neutral", "higher-is-better", "lower-is-better"]).default("neutral")
+    }),
+    example: '::column{field="change" label="Δ QoQ" format="percent" sign="always" semantics="higher-is-better"}',
+    dataRules: {
+      image: "Local static PNG/JPEG path or null. alt names a nonblank string field for each image. Fixed 64 × 48 display box; deduplicated and embedded offline. Paths resolve from the report directory.",
+      sparkline: "Only explicitly declared sparkline fields may contain arrays: at most 64 finite numbers/nulls, in sample order. Nulls are gaps. Shared observed y scale per column; no aggregation or resampling.",
+      sortBy: "Optional scalar field for image/sparkline sorting. Without it a rich column has a plain header. Scalar columns sort their own raw values. Sort keys are readable in the export."
+    }
+  },
+  callout: {
+    forms: ["container"],
+    children: ["markdown"],
+    description: "A contextual note or warning containing ordinary Markdown.",
+    schema: z2.strictObject({
+      tone: z2.enum(["note", "warning"]).default("note"),
+      title: text.optional()
+    }),
+    example: `:::callout{title="Coverage"}
+Seven complete days of prepared data.
+:::`
+  }
+};
+function componentSpec() {
+  return {
+    version: 1,
+    syntax: "markdown-directives",
+    attributes: "Literal strings decoded according to each property schema. No JavaScript expressions.",
+    limits,
+    data: {
+      shape: "component datasets are arrays of flat JSON records; explicit table sparkline columns permit bounded numeric/null arrays only in their declared fields; explore bundles use their component-specific inputs/views schema",
+      resolution: "relative to the report directory; local .json files only",
+      percent: "ratios: 0.12 displays as 12%",
+      percentagePoints: "point values: 0.8 displays as 0.8 pt",
+      currency: "major units; omit .00 on whole amounts, preserve nonzero cents",
+      locale: "en-GB",
+      timeZone: "UTC"
+    },
+    components: Object.fromEntries(Object.entries(registry).map(([name, entry]) => [
+      name,
+      {
+        description: entry.description,
+        forms: entry.forms,
+        children: entry.children,
+        props: z2.toJSONSchema(entry.schema),
+        example: entry.example,
+        ..."dataRules" in entry ? { dataRules: entry.dataRules } : {}
+      }
+    ])),
+    rules: [
+      "Use explicit closing fences for containers.",
+      "Components are standalone blocks, not inline/list/blockquote content.",
+      "column is only allowed inside table; grids cannot nest.",
+      "direction and explicitly supplied sentiment require metric comparison text.",
+      "targetLabel requires target.",
+      "Dataset fields are literal own-property keys, not expressions.",
+      "Charts preserve source order; date/number x values must increase.",
+      "Line/area null y values create gaps; bar null y values are invalid.",
+      "Donut category/value fields must differ; category count is bounded, and all-zero values do not create equal slices.",
+      "Funnel fields must differ; shares and denominators are supplied, validated and displayed per row, with no sorting or status inference.",
+      "Only explicit image columns can load local static PNG/JPEG; every resource stays within the report root and shared byte limits.",
+      "explore selects finite agent-prepared views using scoped native controls; nested explorations, arbitrary row queries, maps and executable components are not supported."
+    ]
+  };
+}
+var specs = componentSpec().components;
+var numericLiteral = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+function decodeProps(name, attributes) {
+  const decoded = Object.create(null);
+  const properties = specs[name].props.properties ?? {};
+  for (const [key, value] of Object.entries(attributes)) {
+    const property = properties[key];
+    if (property?.type === "number" || property?.type === "integer")
+      decoded[key] = typeof value === "string" && numericLiteral.test(value) ? Number(value) : value;
+    else
+      decoded[key] = value;
+  }
+  const result = registry[name].schema.safeParse(decoded);
+  if (!result.success)
+    return {
+      errors: result.error.issues.map((issue) => `${issue.path.join(".") || name}: ${issue.message}`)
+    };
+  const props = result.data;
+  const errors = [];
+  if (name === "column") {
+    const column = props;
+    const kind = column.kind ?? "scalar";
+    if (kind === "image" && !column.alt)
+      errors.push("image columns require an alt field.");
+    if (kind !== "image" && column.alt)
+      errors.push("alt is only supported on image columns.");
+    if (kind === "image" && column.format)
+      errors.push("Image columns cannot use numeric formatting.");
+    if (kind !== "scalar" && (column.sign !== "auto" || column.semantics !== "neutral"))
+      errors.push("sign and semantics apply only to scalar columns.");
+    if (kind === "scalar" && column.sortBy)
+      errors.push("Scalar columns sort their own field; sortBy is for image/sparkline columns.");
+    if (column.alt === column.field || column.sortBy === column.field)
+      errors.push("alt and sortBy must reference fields different from the rich cell field.");
+  }
+  if (name === "donut" || name === "funnel") {
+    const fields = Object.entries(props).filter(([key, value]) => ["category", "stage", "value", "total", "share", "status"].includes(key) && value !== undefined).map(([, value]) => value);
+    if (new Set(fields).size !== fields.length)
+      errors.push(`${name} field properties must reference different dataset fields.`);
+  }
+  if ("format" in props && props.format?.startsWith("currency:") && !Intl.supportedValuesOf("currency").includes(props.format.slice(9)))
+    errors.push(`Unknown ISO currency code ${props.format.slice(9)}.`);
+  if (name === "metric" && !props.comparison && (attributes.direction !== undefined || attributes.sentiment !== undefined))
+    errors.push("direction and sentiment require comparison text.");
+  if ((name === "line" || name === "area") && "targetLabel" in props && props.targetLabel !== undefined && (!("target" in props) || props.target === undefined))
+    errors.push("targetLabel requires a numeric target.");
+  return { props, errors };
+}
+
+// src/compiler/parse.ts
+var parser = unified().use(remarkParse).use(remarkFrontmatter).use(remarkDirective);
+var metadataSchema = z3.strictObject({
+  title: z3.string().min(1).max(500).optional(),
+  description: z3.string().max(2000).optional()
+});
+function textOf(node) {
+  return node.value ?? node.children?.map(textOf).join("") ?? "";
+}
+function parseReport(source, fallbackTitle, diagnostics) {
+  const tree = parser.parse(source);
+  const lines = source.split(/\r?\n/);
+  const recognized = new Set;
+  const inert = new Set;
+  const definitions = new Map;
+  let metadata = { title: fallbackTitle };
+  const firstHeading = tree.children.find((node) => node.type === "heading" && node.depth === 1);
+  if (firstHeading)
+    metadata.title = textOf(firstHeading);
+  function inspect(node, depth = 0) {
+    if (depth > 64) {
+      diagnostics.add("E_REPORT_DEPTH", "Markdown nesting exceeds 64 levels.", node.position);
+      return;
+    }
+    if (node.type === "code" || node.type === "yaml") {
+      for (let line = node.position?.start.line ?? 0;line <= (node.position?.end.line ?? 0); line++)
+        inert.add(line);
+      return;
+    }
+    if (node.type === "html")
+      diagnostics.add("E_RAW_HTML", "Raw HTML is not supported in reports.", node.position, "Use Markdown or a registered directive. Put HTML examples inside code fences.");
+    if (node.type === "image" || node.type === "imageReference")
+      diagnostics.add("E_IMAGE_UNSUPPORTED", "Markdown images are not supported; use an explicit image column in a table.", node.position, 'Use ::column{field="image" kind="image" alt="description"} inside a table for local PNG/JPEG images, or use a text link.');
+    if (node.type === "link" || node.type === "definition") {
+      const url = node.url ?? "";
+      let allowed = url.startsWith("#");
+      try {
+        allowed ||= ["https:", "http:", "mailto:"].includes(new URL(url).protocol);
+      } catch {}
+      if (!allowed)
+        diagnostics.add("E_LINK_URL", `Unsupported link destination ${JSON.stringify(url)}.`, node.position, "Use an https:, http:, mailto: link or a same-document #anchor.");
+      if (node.type === "definition")
+        definitions.set(String(node.identifier), url);
+    }
+    node.children?.forEach((child) => inspect(child, depth + 1));
+  }
+  inspect(tree);
+  function blocks(nodes, parent = "root", depth = 0) {
+    if (depth > 32) {
+      diagnostics.add("E_REPORT_DEPTH", "Component nesting exceeds 32 levels.");
+      return [];
+    }
+    const output = [];
+    for (const node of nodes) {
+      if (node.type === "yaml") {
+        try {
+          const document = parseDocument(node.value ?? "", {
+            uniqueKeys: true,
+            strict: true
+          });
+          if (document.errors.length || document.warnings.length)
+            throw new Error([...document.errors, ...document.warnings].map((error) => error.message).join("; "));
+          visit(document, {
+            Alias() {
+              throw new Error("YAML aliases are not supported.");
+            }
+          });
+          const result = metadataSchema.safeParse(document.toJS({ maxAliasCount: 0 }) ?? {});
+          if (!result.success)
+            throw new Error(result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+          metadata = { ...metadata, ...result.data };
+        } catch (error) {
+          diagnostics.add("E_FRONTMATTER", error instanceof Error ? error.message : "Invalid frontmatter.", node.position);
+        }
+        continue;
+      }
+      if (["containerDirective", "leafDirective", "textDirective"].includes(node.type)) {
+        const name = node.name ?? "";
+        recognized.add(node.position?.start.line ?? 0);
+        if (node.type === "containerDirective") {
+          const closingLine = node.position?.end.line ?? 0;
+          const closing = lines[closingLine - 1]?.trim() ?? "";
+          if (!/^:{3,}$/.test(closing))
+            diagnostics.add("E_DIRECTIVE_CLOSE", `:::${name} needs an explicit closing colon fence.`, node.position, "Close the component with ::: on its own line. Use a longer outer fence when nesting containers.");
+          else
+            recognized.add(closingLine);
+        }
+        if (!Object.hasOwn(registry, name)) {
+          diagnostics.add("E_COMPONENT_UNKNOWN", `Unknown component ${JSON.stringify(name)}.`, node.position, `Supported components: ${Object.keys(registry).join(", ")}. Run plotleaf schema for their properties.`);
+          continue;
+        }
+        const componentName = name;
+        const entry = registry[componentName];
+        const form = node.type === "containerDirective" ? "container" : node.type === "leafDirective" ? "leaf" : "text";
+        if (!entry.forms.includes(form))
+          diagnostics.add("E_COMPONENT_FORM", `${name} does not support the ${form} directive form.`, node.position, `Use ${entry.forms.includes("container") ? `:::${name} … :::` : `::${name}{…}`}.`);
+        const allowed = parent === "root" ? name !== "column" : registry[parent]?.children?.includes(name);
+        if (!allowed)
+          diagnostics.add("E_COMPONENT_CONTEXT", `${name} is not allowed inside ${parent}.`, node.position, name === "column" ? "Place column directives inside a table container." : "Place standalone components at the report root or inside a grid.");
+        const opening = lines[(node.position?.start.line ?? 1) - 1] ?? "";
+        const names = new Set;
+        for (const match of opening.matchAll(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|([A-Za-z][\w-]*)\s*=/g)) {
+          if (!match[1])
+            continue;
+          if (names.has(match[1]))
+            diagnostics.add("E_PROP_DUPLICATE", `Duplicate property ${JSON.stringify(match[1])} on ${name}.`, node.position, "Specify each property once.");
+          names.add(match[1]);
+        }
+        if (node.type === "leafDirective" && node.children?.length)
+          diagnostics.add("E_COMPONENT_LABEL", `${name} does not accept a directive [label].`, node.position, "Use the label or title property instead.");
+        const decoded = decodeProps(componentName, node.attributes ?? {});
+        for (const message of decoded.errors)
+          diagnostics.add("E_PROP_VALUE", message, node.position, `Run plotleaf schema for the ${name} contract.`);
+        const children = blocks(node.children ?? [], name, depth + 1);
+        if (decoded.props)
+          output.push({
+            type: "component",
+            name: componentName,
+            props: decoded.props,
+            children,
+            position: node.position
+          });
+        continue;
+      }
+      if (parent !== "root" && !registry[parent]?.children?.includes("markdown"))
+        diagnostics.add("E_COMPONENT_CHILD", `${parent} only accepts its declared component children.`, node.position);
+      const nestedDirectives = (candidate, nesting = 0) => {
+        if (nesting > 64)
+          return;
+        if (candidate.type.endsWith("Directive"))
+          diagnostics.add("E_COMPONENT_CONTEXT", "Components must be standalone blocks, not inline/list/blockquote content.", candidate.position);
+        candidate.children?.forEach((child) => nestedDirectives(child, nesting + 1));
+      };
+      nestedDirectives(node);
+      const last = output.at(-1);
+      if (last?.type === "markdown")
+        last.tree.children.push(node);
+      else
+        output.push({
+          type: "markdown",
+          tree: { type: "root", children: [node] }
+        });
+    }
+    return output;
+  }
+  const reportBlocks = blocks(tree.children);
+  function attachDefinitions(items) {
+    for (const block of items) {
+      if (block.type === "markdown") {
+        for (const [identifier, url] of definitions)
+          if (!block.tree.children.some((node) => node.type === "definition" && node.identifier === identifier))
+            block.tree.children.push({ type: "definition", identifier, url });
+      } else
+        attachDefinitions(block.children);
+    }
+  }
+  attachDefinitions(reportBlocks);
+  for (let index = 0;index < lines.length; index++) {
+    if (/^\s*::/.test(lines[index] ?? "") && !recognized.has(index + 1) && !inert.has(index + 1)) {
+      const position = {
+        start: { line: index + 1, column: 1 },
+        end: { line: index + 1, column: 1 }
+      };
+      diagnostics.add("E_DIRECTIVE_SYNTAX", "Malformed or misplaced component directive.", position, 'Use ::name{key="literal"} on one line, or a balanced :::name container. JavaScript expressions are not supported.');
+    }
+  }
+  return { metadata, blocks: reportBlocks };
+}
+
+// src/compiler/sources.ts
+class LocalFileError extends Error {
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
+
+// src/compiler/exploration.ts
+var expansionBudget = () => ({
+  explorations: 0,
+  components: 0,
+  rows: 0,
+  markdownBytes: 0,
+  dataBytes: 0
+});
+async function resolveExploration(block, files, diagnostics, resolve, budget) {
+  const fail = (message, code = "E_EXPLORE_SCHEMA") => diagnostics.add(code, `${block.props.data}: ${message}`, block.position, "Correct the prepared-view bundle; every view must declare all input values.");
+  try {
+    if (++budget.explorations > explorationLimits.explorations) {
+      fail("At most four explorations are supported.", "E_EXPLORE_LIMIT");
+      return;
+    }
+    const filename = await files.resolve(block.props.data, [".json"]);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(await files.read(filename, limits.jsonBytes));
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      fail("Invalid JSON.", "E_EXPLORE_JSON");
+      return;
+    }
+    const pending = [
+      { value: raw, depth: 0 }
+    ];
+    let containers = 0;
+    while (pending.length) {
+      const { value, depth } = pending.pop();
+      if (value === null || typeof value !== "object")
+        continue;
+      if (depth > explorationLimits.jsonDepth || ++containers > explorationLimits.jsonContainers) {
+        fail("JSON exceeds 32 nesting levels or 100,000 containers.", "E_EXPLORE_LIMIT");
+        return;
+      }
+      for (const [key, child] of Object.entries(value)) {
+        if (["__proto__", "constructor", "prototype"].includes(key)) {
+          fail(`Reserved object key ${JSON.stringify(key)}.`, "E_EXPLORE_KEY");
+          return;
+        }
+        if (child !== null && typeof child === "object")
+          pending.push({ value: child, depth: depth + 1 });
+      }
+    }
+    const parsed = explorationSchema.safeParse(raw);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues.slice(0, 12))
+        fail(`${issue.path.join(".")}: ${issue.message}`);
+      return;
+    }
+    const bundle = parsed.data;
+    const ids = bundle.inputs.map((input) => input.id);
+    if (new Set(ids).size !== ids.length) {
+      fail("Input IDs must be unique.");
+      return;
+    }
+    const domains = new Map;
+    for (const input of bundle.inputs) {
+      const values = input.type === "toggle" ? [false, true] : input.options.map((option) => option.value);
+      const domain = new Set(values.map(valueKey));
+      if (domain.size !== values.length || !domain.has(valueKey(input.default))) {
+        fail(`Input ${input.id} has duplicate choices or an unsupported default.`);
+        return;
+      }
+      domains.set(input.id, domain);
+    }
+    const combinations = new Set, viewIds = new Set;
+    const key = (when) => JSON.stringify(ids.map((id) => valueKey(when[id])));
+    const initial = Object.fromEntries(bundle.inputs.map((input) => [input.id, input.default]));
+    for (const view of bundle.views) {
+      if (viewIds.has(view.id)) {
+        fail(`Duplicate view ID ${view.id}.`);
+        return;
+      }
+      viewIds.add(view.id);
+      if (Object.keys(view.when).length !== ids.length || ids.some((id) => !Object.hasOwn(view.when, id)) || Object.keys(view.when).some((id) => !domains.has(id))) {
+        fail(`View ${view.id} must declare exactly the scoped input IDs.`);
+        return;
+      }
+      if (ids.some((id) => !domains.get(id).has(valueKey(view.when[id])))) {
+        fail(`View ${view.id} contains an unsupported input value or value type.`);
+        return;
+      }
+      const combination = key(view.when);
+      if (combinations.has(combination)) {
+        fail(`View ${view.id} duplicates another input combination.`);
+        return;
+      }
+      combinations.add(combination);
+    }
+    const defaultView = bundle.views.find((view) => key(view.when) === key(initial));
+    if (!defaultView) {
+      fail("Declared defaults must select one prepared view.");
+      return;
+    }
+    const views = [];
+    for (const view of bundle.views) {
+      let inspect = function(blocks) {
+        for (const child of blocks) {
+          if (child.type !== "component")
+            continue;
+          if (child.name === "explore") {
+            fail(`View ${view.id}: nested explorations are unsupported.`);
+            return false;
+          }
+          if (++budget.components > explorationLimits.components) {
+            fail("Expanded components exceed 512.", "E_EXPLORE_LIMIT");
+            return false;
+          }
+          if (!inspect(child.children))
+            return false;
+        }
+        return true;
+      }, countRows = function(blocks) {
+        for (const child of blocks)
+          if (child.type === "component") {
+            budget.rows += child.rows?.length ?? 0;
+            budget.dataBytes += child.rows ? new TextEncoder().encode(JSON.stringify(child.rows)).length : 0;
+            countRows(child.children);
+          }
+      };
+      budget.markdownBytes += new TextEncoder().encode(view.markdown).length;
+      if (budget.markdownBytes > explorationLimits.markdownBytes) {
+        fail("Expanded Markdown exceeds 2 MiB.", "E_EXPLORE_LIMIT");
+        return;
+      }
+      const local = new Diagnostics(`${block.props.data}#${view.id}`);
+      const report = parseReport(view.markdown, view.label, local);
+      if (!inspect(report.blocks))
+        return;
+      const inline = new Map(Object.entries(view.datasets).map(([name, rows]) => [
+        `plotleaf-inline:${budget.explorations}-${view.id}:${name}`,
+        new TextEncoder().encode(JSON.stringify(rows))
+      ]));
+      const virtual = {
+        async resolve(reference, extensions) {
+          const name = reference.startsWith("./") ? reference.slice(2) : reference;
+          const key = `plotleaf-inline:${budget.explorations}-${view.id}:${name}`;
+          return inline.has(key) ? key : files.resolve(reference, extensions);
+        },
+        async read(name, maximum) {
+          const bytes = inline.get(name);
+          if (!bytes)
+            return files.read(name, maximum);
+          if (bytes.length > maximum)
+            throw new Error("Prepared dataset exceeds the file size limit.");
+          return bytes;
+        }
+      };
+      await resolve(report.blocks, virtual, local);
+      countRows(report.blocks);
+      if (budget.rows > explorationLimits.rows) {
+        fail("Expanded component rows exceed 20,000.", "E_EXPLORE_LIMIT");
+        return;
+      }
+      if (budget.dataBytes > explorationLimits.dataBytes) {
+        fail("Expanded prepared data exceeds 8 MiB.", "E_EXPLORE_LIMIT");
+        return;
+      }
+      for (const item of local.sorted())
+        diagnostics.add(item.code, `View ${view.id}, Markdown ${item.line}:${item.column}: ${item.message}`, block.position, item.hint, item.severity);
+      views.push({
+        id: view.id,
+        label: view.label,
+        when: view.when,
+        blocks: report.blocks
+      });
+    }
+    block.exploration = {
+      inputs: bundle.inputs,
+      defaultView: defaultView.id,
+      views
+    };
+  } catch (error) {
+    fail(error instanceof Error ? error.message : "Could not read the exploration.", error instanceof LocalFileError && error.kind === "path" ? "E_EXPLORE_PATH" : "E_EXPLORE_READ");
+  }
+}
+
+// src/shared/date.ts
+function parseDate(value) {
+  const date = value.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+    return;
+  const day = Date.parse(`${date}T00:00:00.000Z`);
+  if (!Number.isFinite(day) || new Date(day).toISOString().slice(0, 10) !== date)
+    return;
+  if (value.length === 10)
+    return day;
+  if (!/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value))
+    return;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+
+// src/compiler/resolve-data.ts
+var reserved = new Set(["__proto__", "constructor", "prototype"]);
+
+class DataResolver {
+  diagnostics;
+  files;
+  images;
+  expansion;
+  cache;
+  constructor(diagnostics, files, images, expansion = expansionBudget(), cache = new Map) {
+    this.diagnostics = diagnostics;
+    this.files = files;
+    this.images = images;
+    this.expansion = expansion;
+    this.cache = cache;
+  }
+  async load(reference, block) {
+    const fail = (code, message, hint) => {
+      this.diagnostics.add(code, `${reference}: ${message}`, block.position, hint);
+      return;
+    };
+    let canonical;
+    try {
+      canonical = await this.files.resolve(reference, [".json"]);
+    } catch (error) {
+      return fail(error instanceof LocalFileError && error.kind === "path" ? "E_DATA_PATH" : "E_DATA_READ", error instanceof Error ? error.message : "Cannot resolve the dataset.", "Place prepared JSON within the report directory and correct the data property.");
+    }
+    let dataset = this.cache.get(canonical);
+    if (!dataset) {
+      if (this.cache.size >= limits.datasets)
+        return fail("E_DATA_LIMIT", `At most ${limits.datasets} datasets are supported.`);
+      let text;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(await this.files.read(canonical, limits.jsonBytes));
+      } catch (error) {
+        return fail("E_DATA_READ", error instanceof Error ? error.message : "Could not read data.");
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
         return fail("E_DATA_JSON", "Invalid JSON.", "Use a JSON array of records, without comments or trailing commas.");
       }
       if (!Array.isArray(parsed))
@@ -362,6 +884,10 @@ class DataResolver {
     for (const block of blocks) {
       if (block.type !== "component")
         continue;
+      if (block.name === "explore") {
+        await resolveExploration(block, this.files, this.diagnostics, (children, files, diagnostics) => new DataResolver(diagnostics, files, this.images, this.expansion, this.cache).resolve(children), this.expansion);
+        continue;
+      }
       if (block.name === "line" || block.name === "area" || block.name === "bar" || block.name === "donut" || block.name === "funnel" || block.name === "table") {
         const rows = await this.load(block.props.data, block);
         if (rows) {
@@ -539,493 +1065,248 @@ class DataResolver {
           fail("E_TABLE_SORT", index, "sortBy must name a scalar field.");
           continue;
         }
-        if (sort !== undefined && sort !== null) {
-          if (sortType && sortType !== typeof sort) {
-            fail("E_TABLE_SORT", index, "sortBy values must have consistent non-null types.");
-            continue;
-          }
-          sortType = typeof sort;
-        }
-        if (kind === "scalar") {
-          prepared[index][column.field] = value;
-          continue;
-        }
-        let rich;
-        if (kind === "sparkline") {
-          if (value !== null && !Array.isArray(value)) {
-            fail("E_DATA_TYPE", index, "Sparkline values must be a bounded numeric/null array or null.");
-            continue;
-          }
-          rich = {
-            kind: "sparkline",
-            values: value ?? [],
-            ...column.sortBy ? { sort } : {}
-          };
-        } else {
-          const alt = row[column.alt];
-          if (value !== null && (typeof alt !== "string" || !alt.trim() || alt.length > 1000) || value === null && alt !== null && typeof alt !== "string") {
-            fail("E_TABLE_IMAGE", index, "alt must name a nonblank string of at most 1000 characters for each image.");
-            continue;
-          }
-          if (value === null) {
-            prepared[index][column.field] = {
-              kind: "image",
-              imageId: null,
-              alt: "",
-              ...column.sortBy ? { sort } : {}
-            };
-            continue;
-          }
-          if (typeof value !== "string" || !value.trim()) {
-            fail("E_TABLE_IMAGE", index, "Image values must be a plain local PNG/JPEG path or null.");
-            continue;
-          }
-          try {
-            const image = await this.images.load(value);
-            rich = {
-              kind: "image",
-              imageId: image.id,
-              alt,
-              ...column.sortBy ? { sort } : {}
-            };
-          } catch (error) {
-            fail(error instanceof LocalFileError ? error.kind === "path" ? "E_ASSET_PATH" : "E_ASSET_READ" : "E_ASSET_IMAGE", index, `${value}: ${error instanceof Error ? error.message : "Cannot read image."}`, "Use a bounded static PNG/JPEG inside the report directory, with a matching extension.");
-            continue;
-          }
-        }
-        prepared[index][column.field] = rich;
-      }
-    }
-    block.columns = columns;
-    block.rows = prepared;
-  }
-}
-
-// src/compiler/parse.ts
-import { unified } from "unified";
-import remarkParse from "remark-parse";
-import remarkDirective from "remark-directive";
-import remarkFrontmatter from "remark-frontmatter";
-import { parseDocument, visit } from "yaml";
-import * as z2 from "zod";
-
-// src/compiler/registry.ts
-import * as z from "zod";
-var text = z.string().min(1).max(1000);
-var format = z.string().regex(/^(number|percent|percentage-points|currency:[A-Z]{3})$/, "Use number, percent, percentage-points or currency:GBP (an ISO currency code).");
-var chart = {
-  data: text,
-  x: text,
-  y: text,
-  title: text,
-  format: format.default("number")
-};
-var line = z.strictObject({
-  ...chart,
-  xType: z.enum(["category", "date", "number"]).default("category"),
-  target: z.number().finite().optional(),
-  targetLabel: text.optional()
-});
-var registry = {
-  grid: {
-    forms: ["container"],
-    children: [
-      "metric",
-      "line",
-      "area",
-      "bar",
-      "donut",
-      "funnel",
-      "table",
-      "callout"
-    ],
-    description: "A responsive row of one to four components.",
-    schema: z.strictObject({
-      columns: z.number().int().min(1).max(4).default(2)
-    }),
-    example: `:::grid{columns="4"}
-::metric{label="Teams" value="1492"}
-:::`
-  },
-  metric: {
-    forms: ["leaf"],
-    children: [],
-    description: "A prepared numeric value with optional comparison, direction and sentiment.",
-    schema: z.strictObject({
-      label: text,
-      value: z.number().finite(),
-      format: format.default("number"),
-      comparison: text.optional(),
-      direction: z.enum(["up", "down", "flat"]).optional(),
-      sentiment: z.enum(["positive", "negative", "neutral"]).default("neutral")
-    }),
-    example: '::metric{label="Conversion" value="0.103" format="percent"}'
-  },
-  line: {
-    forms: ["leaf"],
-    children: [],
-    description: "An interactive single-series line chart from local JSON.",
-    schema: line,
-    example: '::line{data="./usage.json" x="date" y="teams" xType="date" title="Active teams"}'
-  },
-  area: {
-    forms: ["leaf"],
-    children: [],
-    description: "A line chart with a restrained area fill.",
-    schema: line,
-    example: '::area{data="./usage.json" x="date" y="teams" xType="date" title="Active teams" target="1600"}'
-  },
-  bar: {
-    forms: ["leaf"],
-    children: [],
-    description: "An interactive category bar chart with a zero baseline.",
-    schema: z.strictObject(chart),
-    example: '::bar{data="./errors.json" x="category" y="count" title="Errors by category"}'
-  },
-  donut: {
-    forms: ["leaf"],
-    children: [],
-    description: "A part-to-whole donut with a readable legend and native data table.",
-    schema: z.strictObject({
-      data: text,
-      category: text,
-      value: text,
-      title: text,
-      format: format.default("number")
-    }),
-    dataRules: {
-      category: "Unique nonblank strings of at most 1000 characters; source order is preserved.",
-      value: "Finite nonnegative numbers with a finite sum. Nulls and numeric strings are invalid. All-zero values show an empty state.",
-      maximumRows: limits.donutSlices
-    },
-    example: '::donut{data="./plans.json" category="plan" value="teams" title="Teams by plan"}'
-  },
-  funnel: {
-    forms: ["leaf"],
-    children: [],
-    description: "Ordered stage/progress rows with prepared values, denominators, shares and optional explicit status. Works without JavaScript.",
-    schema: z.strictObject({
-      data: text,
-      stage: text,
-      value: text,
-      total: text,
-      share: text,
-      status: text.optional(),
-      title: text,
-      format: format.default("number")
-    }),
-    dataRules: {
-      stage: "Unique nonblank strings of at most 1000 characters; source order is preserved.",
-      value: "Finite nonnegative number no greater than its row's total.",
-      total: "Finite positive denominator supplied per row. No denominator is inferred from adjacent stages.",
-      share: "Prepared ratio from 0 to 1, matching value / total to within 0.0005 (rounding to 0.1 percentage point).",
-      status: Object.keys(funnelStatuses),
-      maximumRows: limits.funnelStages
-    },
-    example: '::funnel{data="./funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}'
-  },
-  table: {
-    forms: ["leaf", "container"],
-    children: ["column"],
-    description: "A semantic sortable table, with inferred or explicitly formatted columns.",
-    schema: z.strictObject({ data: text, title: text.optional() }),
-    example: `:::table{data="./plans.json" title="By plan"}
-::column{field="plan" label="Plan"}
-::column{field="change" label="Δ QoQ" format="percent" sign="always"}
-:::`
-  },
-  column: {
-    forms: ["leaf"],
-    children: [],
-    description: "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
-    schema: z.strictObject({
-      field: text,
-      label: text.optional(),
-      kind: z.enum(["scalar", "image", "sparkline"]).optional(),
-      alt: text.optional(),
-      sortBy: text.optional(),
-      format: format.optional(),
-      sign: z.enum(["auto", "always"]).default("auto"),
-      semantics: z.enum(["neutral", "higher-is-better", "lower-is-better"]).default("neutral")
-    }),
-    example: '::column{field="change" label="Δ QoQ" format="percent" sign="always" semantics="higher-is-better"}',
-    dataRules: {
-      image: "Local static PNG/JPEG path or null. alt names a nonblank string field for each image. Fixed 64 × 48 display box; deduplicated and embedded offline. Paths resolve from the report directory.",
-      sparkline: "Only explicitly declared sparkline fields may contain arrays: at most 64 finite numbers/nulls, in sample order. Nulls are gaps. Shared observed y scale per column; no aggregation or resampling.",
-      sortBy: "Optional scalar field for image/sparkline sorting. Without it a rich column has a plain header. Scalar columns sort their own raw values. Sort keys are readable in the export."
+        if (sort !== undefined && sort !== null) {
+          if (sortType && sortType !== typeof sort) {
+            fail("E_TABLE_SORT", index, "sortBy values must have consistent non-null types.");
+            continue;
+          }
+          sortType = typeof sort;
+        }
+        if (kind === "scalar") {
+          prepared[index][column.field] = value;
+          continue;
+        }
+        let rich;
+        if (kind === "sparkline") {
+          if (value !== null && !Array.isArray(value)) {
+            fail("E_DATA_TYPE", index, "Sparkline values must be a bounded numeric/null array or null.");
+            continue;
+          }
+          rich = {
+            kind: "sparkline",
+            values: value ?? [],
+            ...column.sortBy ? { sort } : {}
+          };
+        } else {
+          const alt = row[column.alt];
+          if (value !== null && (typeof alt !== "string" || !alt.trim() || alt.length > 1000) || value === null && alt !== null && typeof alt !== "string") {
+            fail("E_TABLE_IMAGE", index, "alt must name a nonblank string of at most 1000 characters for each image.");
+            continue;
+          }
+          if (value === null) {
+            prepared[index][column.field] = {
+              kind: "image",
+              imageId: null,
+              alt: "",
+              ...column.sortBy ? { sort } : {}
+            };
+            continue;
+          }
+          if (typeof value !== "string" || !value.trim()) {
+            fail("E_TABLE_IMAGE", index, "Image values must be a plain local PNG/JPEG path or null.");
+            continue;
+          }
+          try {
+            const image = await this.images.load(value);
+            rich = {
+              kind: "image",
+              imageId: image.id,
+              alt,
+              ...column.sortBy ? { sort } : {}
+            };
+          } catch (error) {
+            fail(error instanceof LocalFileError ? error.kind === "path" ? "E_ASSET_PATH" : "E_ASSET_READ" : "E_ASSET_IMAGE", index, `${value}: ${error instanceof Error ? error.message : "Cannot read image."}`, "Use a bounded static PNG/JPEG inside the report directory, with a matching extension.");
+            continue;
+          }
+        }
+        prepared[index][column.field] = rich;
+      }
     }
-  },
-  callout: {
-    forms: ["container"],
-    children: ["markdown"],
-    description: "A contextual note or warning containing ordinary Markdown.",
-    schema: z.strictObject({
-      tone: z.enum(["note", "warning"]).default("note"),
-      title: text.optional()
-    }),
-    example: `:::callout{title="Coverage"}
-Seven complete days of prepared data.
-:::`
+    block.columns = columns;
+    block.rows = prepared;
   }
-};
-function componentSpec() {
+}
+
+// src/compiler/files.ts
+import path2 from "node:path";
+import { open, realpath, stat } from "node:fs/promises";
+function contained(root, filename) {
+  const relative = path2.relative(root, filename);
+  return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
+}
+async function readBytesBounded(filename, maximum) {
+  if (!(await stat(filename)).isFile())
+    throw new Error("Expected a regular file.");
+  const file = await open(filename, "r");
+  try {
+    const info = await file.stat();
+    if (!info.isFile())
+      throw new Error("Expected a regular file.");
+    if (info.size > maximum)
+      throw new Error(`File exceeds the ${Math.floor(maximum / 1024)} KiB size limit.`);
+    const chunks = [];
+    let bytes = 0;
+    while (bytes <= maximum) {
+      const buffer = Buffer.alloc(Math.min(64 * 1024, maximum + 1 - bytes));
+      const result = await file.read(buffer, 0, buffer.length, null);
+      if (!result.bytesRead)
+        break;
+      chunks.push(buffer.subarray(0, result.bytesRead));
+      bytes += result.bytesRead;
+    }
+    if (bytes > maximum)
+      throw new Error("File grew beyond the size limit while reading.");
+    return Buffer.concat(chunks, bytes);
+  } finally {
+    await file.close();
+  }
+}
+async function readBounded(filename, maximum) {
+  const bytes = await readBytesBounded(filename, maximum);
   return {
-    version: 1,
-    syntax: "markdown-directives",
-    attributes: "Literal strings decoded according to each property schema. No JavaScript expressions.",
-    limits,
-    data: {
-      shape: "array of flat JSON records; explicit table sparkline columns permit bounded numeric/null arrays only in their declared fields",
-      resolution: "relative to the report directory; local .json files only",
-      percent: "ratios: 0.12 displays as 12%",
-      percentagePoints: "point values: 0.8 displays as 0.8 pt",
-      currency: "major units; omit .00 on whole amounts, preserve nonzero cents",
-      locale: "en-GB",
-      timeZone: "UTC"
-    },
-    components: Object.fromEntries(Object.entries(registry).map(([name, entry]) => [
-      name,
-      {
-        description: entry.description,
-        forms: entry.forms,
-        children: entry.children,
-        props: z.toJSONSchema(entry.schema),
-        example: entry.example,
-        ..."dataRules" in entry ? { dataRules: entry.dataRules } : {}
-      }
-    ])),
-    rules: [
-      "Use explicit closing fences for containers.",
-      "Components are standalone blocks, not inline/list/blockquote content.",
-      "column is only allowed inside table; grids cannot nest.",
-      "direction and explicitly supplied sentiment require metric comparison text.",
-      "targetLabel requires target.",
-      "Dataset fields are literal own-property keys, not expressions.",
-      "Charts preserve source order; date/number x values must increase.",
-      "Line/area null y values create gaps; bar null y values are invalid.",
-      "Donut category/value fields must differ; category count is bounded, and all-zero values do not create equal slices.",
-      "Funnel fields must differ; shares and denominators are supplied, validated and displayed per row, with no sorting or status inference.",
-      "Only explicit image columns can load local static PNG/JPEG; every resource stays within the report root and shared byte limits.",
-      "Filters, maps, arbitrary nested data and executable components are not supported in this release."
-    ]
+    text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    bytes: bytes.length
   };
 }
-var specs = componentSpec().components;
-var numericLiteral = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
-function decodeProps(name, attributes) {
-  const decoded = Object.create(null);
-  const properties = specs[name].props.properties ?? {};
-  for (const [key, value] of Object.entries(attributes)) {
-    const property = properties[key];
-    if (property?.type === "number" || property?.type === "integer")
-      decoded[key] = typeof value === "string" && numericLiteral.test(value) ? Number(value) : value;
-    else
-      decoded[key] = value;
+
+class ReportFiles {
+  root;
+  dependencies;
+  usedBytes;
+  constructor(root, dependencies, usedBytes) {
+    this.root = root;
+    this.dependencies = dependencies;
+    this.usedBytes = usedBytes;
   }
-  const result = registry[name].schema.safeParse(decoded);
-  if (!result.success)
-    return {
-      errors: result.error.issues.map((issue) => `${issue.path.join(".") || name}: ${issue.message}`)
+  async resolve(reference, extensions) {
+    const fail = (message) => {
+      throw new LocalFileError("path", message);
     };
-  const props = result.data;
-  const errors = [];
-  if (name === "column") {
-    const column = props;
-    const kind = column.kind ?? "scalar";
-    if (kind === "image" && !column.alt)
-      errors.push("image columns require an alt field.");
-    if (kind !== "image" && column.alt)
-      errors.push("alt is only supported on image columns.");
-    if (kind === "image" && column.format)
-      errors.push("Image columns cannot use numeric formatting.");
-    if (kind !== "scalar" && (column.sign !== "auto" || column.semantics !== "neutral"))
-      errors.push("sign and semantics apply only to scalar columns.");
-    if (kind === "scalar" && column.sortBy)
-      errors.push("Scalar columns sort their own field; sortBy is for image/sparkline columns.");
-    if (column.alt === column.field || column.sortBy === column.field)
-      errors.push("alt and sortBy must reference fields different from the rich cell field.");
-  }
-  if (name === "donut" || name === "funnel") {
-    const fields = Object.entries(props).filter(([key, value]) => ["category", "stage", "value", "total", "share", "status"].includes(key) && value !== undefined).map(([, value]) => value);
-    if (new Set(fields).size !== fields.length)
-      errors.push(`${name} field properties must reference different dataset fields.`);
-  }
-  if ("format" in props && props.format?.startsWith("currency:") && !Intl.supportedValuesOf("currency").includes(props.format.slice(9)))
-    errors.push(`Unknown ISO currency code ${props.format.slice(9)}.`);
-  if (name === "metric" && !props.comparison && (attributes.direction !== undefined || attributes.sentiment !== undefined))
-    errors.push("direction and sentiment require comparison text.");
-  if ((name === "line" || name === "area") && "targetLabel" in props && props.targetLabel !== undefined && (!("target" in props) || props.target === undefined))
-    errors.push("targetLabel requires a numeric target.");
-  return { props, errors };
-}
-
-// src/compiler/parse.ts
-var parser = unified().use(remarkParse).use(remarkFrontmatter).use(remarkDirective);
-var metadataSchema = z2.strictObject({
-  title: z2.string().min(1).max(500).optional(),
-  description: z2.string().max(2000).optional()
-});
-function textOf(node) {
-  return node.value ?? node.children?.map(textOf).join("") ?? "";
-}
-function parseReport(source, fallbackTitle, diagnostics) {
-  const tree = parser.parse(source);
-  const lines = source.split(/\r?\n/);
-  const recognized = new Set;
-  const inert = new Set;
-  const definitions = new Map;
-  let metadata = { title: fallbackTitle };
-  const firstHeading = tree.children.find((node) => node.type === "heading" && node.depth === 1);
-  if (firstHeading)
-    metadata.title = textOf(firstHeading);
-  function inspect(node, depth = 0) {
-    if (depth > 64) {
-      diagnostics.add("E_REPORT_DEPTH", "Markdown nesting exceeds 64 levels.", node.position);
-      return;
-    }
-    if (node.type === "code" || node.type === "yaml") {
-      for (let line = node.position?.start.line ?? 0;line <= (node.position?.end.line ?? 0); line++)
-        inert.add(line);
-      return;
-    }
-    if (node.type === "html")
-      diagnostics.add("E_RAW_HTML", "Raw HTML is not supported in reports.", node.position, "Use Markdown or a registered directive. Put HTML examples inside code fences.");
-    if (node.type === "image" || node.type === "imageReference")
-      diagnostics.add("E_IMAGE_UNSUPPORTED", "Markdown images are not supported; use an explicit image column in a table.", node.position, 'Use ::column{field="image" kind="image" alt="description"} inside a table for local PNG/JPEG images, or use a text link.');
-    if (node.type === "link" || node.type === "definition") {
-      const url = node.url ?? "";
-      let allowed = url.startsWith("#");
-      try {
-        allowed ||= ["https:", "http:", "mailto:"].includes(new URL(url).protocol);
-      } catch {}
-      if (!allowed)
-        diagnostics.add("E_LINK_URL", `Unsupported link destination ${JSON.stringify(url)}.`, node.position, "Use an https:, http:, mailto: link or a same-document #anchor.");
-      if (node.type === "definition")
-        definitions.set(String(node.identifier), url);
+    if (path2.isAbsolute(reference) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(reference) || reference.includes("\\") || /%[\da-f]{2}/i.test(reference) || reference.includes("\x00"))
+      fail(`Use a plain relative local ${extensions.join("/")} path.`);
+    const candidate = path2.resolve(this.root, reference);
+    const hidden = (filename) => path2.relative(this.root, filename).split(path2.sep).some((part) => part.startsWith("."));
+    if (!contained(this.root, candidate))
+      fail("Reference escapes the report directory.");
+    if (hidden(candidate))
+      fail("Hidden files and directories are not allowed.");
+    if (!extensions.includes(path2.extname(candidate).toLowerCase()))
+      fail(`Use a ${extensions.join("/")} file.`);
+    this.dependencies.add(candidate);
+    let canonical;
+    try {
+      canonical = await realpath(candidate);
+    } catch {
+      throw new LocalFileError("read", "Cannot read the referenced file. Create it or correct the reference.");
     }
-    node.children?.forEach((child) => inspect(child, depth + 1));
+    if (!contained(this.root, canonical) || hidden(canonical))
+      fail("The resolved file or symlink escapes the permitted report files.");
+    if (!extensions.includes(path2.extname(canonical).toLowerCase()))
+      fail(`The resolved file must also have a ${extensions.join("/")} extension.`);
+    this.dependencies.add(canonical);
+    return canonical;
   }
-  inspect(tree);
-  function blocks(nodes, parent = "root", depth = 0) {
-    if (depth > 32) {
-      diagnostics.add("E_REPORT_DEPTH", "Component nesting exceeds 32 levels.");
-      return [];
-    }
-    const output = [];
-    for (const node of nodes) {
-      if (node.type === "yaml") {
-        try {
-          const document = parseDocument(node.value ?? "", {
-            uniqueKeys: true,
-            strict: true
-          });
-          if (document.errors.length || document.warnings.length)
-            throw new Error([...document.errors, ...document.warnings].map((error) => error.message).join("; "));
-          visit(document, {
-            Alias() {
-              throw new Error("YAML aliases are not supported.");
-            }
-          });
-          const result = metadataSchema.safeParse(document.toJS({ maxAliasCount: 0 }) ?? {});
-          if (!result.success)
-            throw new Error(result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
-          metadata = { ...metadata, ...result.data };
-        } catch (error) {
-          diagnostics.add("E_FRONTMATTER", error instanceof Error ? error.message : "Invalid frontmatter.", node.position);
-        }
-        continue;
-      }
-      if (["containerDirective", "leafDirective", "textDirective"].includes(node.type)) {
-        const name = node.name ?? "";
-        recognized.add(node.position?.start.line ?? 0);
-        if (node.type === "containerDirective") {
-          const closingLine = node.position?.end.line ?? 0;
-          const closing = lines[closingLine - 1]?.trim() ?? "";
-          if (!/^:{3,}$/.test(closing))
-            diagnostics.add("E_DIRECTIVE_CLOSE", `:::${name} needs an explicit closing colon fence.`, node.position, "Close the component with ::: on its own line. Use a longer outer fence when nesting containers.");
-          else
-            recognized.add(closingLine);
-        }
-        if (!Object.hasOwn(registry, name)) {
-          diagnostics.add("E_COMPONENT_UNKNOWN", `Unknown component ${JSON.stringify(name)}.`, node.position, `Supported components: ${Object.keys(registry).join(", ")}. Run plotleaf schema for their properties.`);
-          continue;
-        }
-        const componentName = name;
-        const entry = registry[componentName];
-        const form = node.type === "containerDirective" ? "container" : node.type === "leafDirective" ? "leaf" : "text";
-        if (!entry.forms.includes(form))
-          diagnostics.add("E_COMPONENT_FORM", `${name} does not support the ${form} directive form.`, node.position, `Use ${entry.forms.includes("container") ? `:::${name} … :::` : `::${name}{…}`}.`);
-        const allowed = parent === "root" ? name !== "column" : registry[parent]?.children?.includes(name);
-        if (!allowed)
-          diagnostics.add("E_COMPONENT_CONTEXT", `${name} is not allowed inside ${parent}.`, node.position, name === "column" ? "Place column directives inside a table container." : "Place standalone components at the report root or inside a grid.");
-        const opening = lines[(node.position?.start.line ?? 1) - 1] ?? "";
-        const names = new Set;
-        for (const match of opening.matchAll(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|([A-Za-z][\w-]*)\s*=/g)) {
-          if (!match[1])
-            continue;
-          if (names.has(match[1]))
-            diagnostics.add("E_PROP_DUPLICATE", `Duplicate property ${JSON.stringify(match[1])} on ${name}.`, node.position, "Specify each property once.");
-          names.add(match[1]);
-        }
-        if (node.type === "leafDirective" && node.children?.length)
-          diagnostics.add("E_COMPONENT_LABEL", `${name} does not accept a directive [label].`, node.position, "Use the label or title property instead.");
-        const decoded = decodeProps(componentName, node.attributes ?? {});
-        for (const message of decoded.errors)
-          diagnostics.add("E_PROP_VALUE", message, node.position, `Run plotleaf schema for the ${name} contract.`);
-        const children = blocks(node.children ?? [], name, depth + 1);
-        if (decoded.props)
-          output.push({
-            type: "component",
-            name: componentName,
-            props: decoded.props,
-            children,
-            position: node.position
-          });
-        continue;
+  async read(filename, maximum) {
+    const bytes = await readBytesBounded(filename, Math.min(maximum, limits.totalBytes - this.usedBytes));
+    this.usedBytes += bytes.length;
+    return bytes;
+  }
+}
+
+// src/compiler/images.ts
+import { createHash } from "node:crypto";
+import path3 from "node:path";
+import { imageSize } from "image-size";
+function formatOf(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    let offset = 8;
+    let data = false;
+    while (offset + 12 <= bytes.length) {
+      const size = bytes.readUInt32BE(offset);
+      const type = bytes.toString("ascii", offset + 4, offset + 8);
+      if (offset + size + 12 > bytes.length)
+        break;
+      if (offset === 8 && (type !== "IHDR" || size !== 13))
+        break;
+      if (type === "acTL")
+        throw new Error("Animated PNG is not supported; provide a static image.");
+      if (type === "IDAT" && size > 0)
+        data = true;
+      offset += size + 12;
+      if (type === "IEND") {
+        if (data && size === 0 && offset === bytes.length)
+          return "png";
+        break;
       }
-      if (parent !== "root" && !registry[parent]?.children?.includes("markdown"))
-        diagnostics.add("E_COMPONENT_CHILD", `${parent} only accepts its declared component children.`, node.position);
-      const nestedDirectives = (candidate, nesting = 0) => {
-        if (nesting > 64)
-          return;
-        if (candidate.type.endsWith("Directive"))
-          diagnostics.add("E_COMPONENT_CONTEXT", "Components must be standalone blocks, not inline/list/blockquote content.", candidate.position);
-        candidate.children?.forEach((child) => nestedDirectives(child, nesting + 1));
-      };
-      nestedDirectives(node);
-      const last = output.at(-1);
-      if (last?.type === "markdown")
-        last.tree.children.push(node);
-      else
-        output.push({
-          type: "markdown",
-          tree: { type: "root", children: [node] }
-        });
     }
-    return output;
+    throw new Error("Incomplete or invalid PNG container.");
   }
-  const reportBlocks = blocks(tree.children);
-  function attachDefinitions(items) {
-    for (const block of items) {
-      if (block.type === "markdown") {
-        for (const [identifier, url] of definitions)
-          if (!block.tree.children.some((node) => node.type === "definition" && node.identifier === identifier))
-            block.tree.children.push({ type: "definition", identifier, url });
-      } else
-        attachDefinitions(block.children);
-    }
+  if (bytes.length >= 4 && bytes.readUInt16BE(0) === 65496 && bytes.readUInt16BE(bytes.length - 2) === 65497)
+    return "jpg";
+  throw new Error("Expected a static PNG or JPEG image with a matching file extension.");
+}
+
+class ImageResolver {
+  files;
+  attempted = new Set;
+  filesRead = new Map;
+  embedded = new Map;
+  constructor(files) {
+    this.files = files;
   }
-  attachDefinitions(reportBlocks);
-  for (let index = 0;index < lines.length; index++) {
-    if (/^\s*::/.test(lines[index] ?? "") && !recognized.has(index + 1) && !inert.has(index + 1)) {
-      const position = {
-        start: { line: index + 1, column: 1 },
-        end: { line: index + 1, column: 1 }
-      };
-      diagnostics.add("E_DIRECTIVE_SYNTAX", "Malformed or misplaced component directive.", position, 'Use ::name{key="literal"} on one line, or a balanced :::name container. JavaScript expressions are not supported.');
+  async load(reference) {
+    const requested = path3.resolve(this.files.root, reference);
+    if (!this.attempted.has(requested) && this.attempted.size >= limits.imageFiles)
+      throw new Error(`At most ${limits.imageFiles} local image references are supported.`);
+    this.attempted.add(requested);
+    const canonical = await this.files.resolve(reference, [
+      ".png",
+      ".jpg",
+      ".jpeg"
+    ]);
+    const cached = this.filesRead.get(canonical);
+    if (cached) {
+      if (path3.extname(reference).toLowerCase() === ".png" !== (cached.mime === "image/png"))
+        throw new Error("Image signature does not match its file extension.");
+      return cached;
+    }
+    if (this.filesRead.size >= limits.imageFiles)
+      throw new Error(`At most ${limits.imageFiles} local image files are supported.`);
+    const bytes = await this.files.read(canonical, limits.imageBytes);
+    const format = formatOf(bytes);
+    const expected = (name) => path3.extname(name).toLowerCase() === ".png" ? "png" : "jpg";
+    if (format !== expected(reference) || format !== expected(canonical))
+      throw new Error("Image signature does not match its file extension.");
+    let size;
+    try {
+      size = imageSize(bytes);
+    } catch {
+      throw new Error("Unsupported or damaged PNG/JPEG header.");
     }
+    if (size.type !== format || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1)
+      throw new Error("Image must have valid positive raster dimensions.");
+    if (size.width > limits.imageDimension || size.height > limits.imageDimension || size.width * size.height > limits.imagePixels)
+      throw new Error(`Image exceeds ${limits.imageDimension} pixels per side or ${limits.imagePixels.toLocaleString("en-GB")} pixels in total. Resize the prepared asset.`);
+    const id = `plotleaf-image-${createHash("sha256").update(bytes).digest("hex")}`;
+    const image = this.embedded.get(id) ?? {
+      id,
+      mime: format === "png" ? "image/png" : "image/jpeg",
+      base64: bytes.toString("base64")
+    };
+    this.filesRead.set(canonical, image);
+    this.embedded.set(id, image);
+    return image;
+  }
+}
+
+// src/compiler/data.ts
+class DataResolver2 extends DataResolver {
+  root;
+  constructor(root, diagnostics, dependencies, totalBytes = 0) {
+    const files = new ReportFiles(root, dependencies, totalBytes);
+    super(diagnostics, files, new ImageResolver(files));
+    this.root = root;
   }
-  return { metadata, blocks: reportBlocks };
 }
 
 // src/compiler/compile.ts
@@ -1047,7 +1328,7 @@ async function compileReport(input) {
     dependencies.add(filename);
     const { text, bytes } = await readBounded(filename, limits.markdownBytes);
     const report = parseReport(text, path4.basename(filename, path4.extname(filename)), diagnostics);
-    const resolver = new DataResolver(path4.dirname(filename), diagnostics, dependencies, bytes);
+    const resolver = new DataResolver2(path4.dirname(filename), diagnostics, dependencies, bytes);
     await resolver.resolve(report.blocks);
     if (resolver.images.embedded.size)
       report.images = [...resolver.images.embedded.values()];
@@ -1061,12 +1342,6 @@ async function compileReport(input) {
 // src/render/html.ts
 import { createHash as createHash2 } from "node:crypto";
 
-// src/render/content.ts
-import { unified as unified2 } from "unified";
-import remarkRehype from "remark-rehype";
-import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
-import rehypeStringify from "rehype-stringify";
-
 // src/render/tree.ts
 var t = (value) => ({
   type: "text",
@@ -1074,6 +1349,122 @@ var t = (value) => ({
 });
 var h = (tagName, properties = {}, children = []) => ({ type: "element", tagName, properties, children });
 
+// src/render/exploration.ts
+function exploration(block, id, render, configs) {
+  const data = block.exploration;
+  if (!data)
+    return [];
+  configs.push({
+    id,
+    inputs: data.inputs,
+    views: data.views.map(({ id, label, when }) => ({ id, label, when }))
+  });
+  const controls = data.inputs.map((input, inputIndex) => {
+    const controlId = `${id}-input-${inputIndex}`;
+    const attrs = {
+      disabled: true,
+      dataPlotleafInput: input.id,
+      id: controlId
+    };
+    if (input.type === "segmented")
+      return h("fieldset", { className: ["explore-segmented"] }, [
+        h("legend", {}, [t(input.label)]),
+        h("div", { className: ["explore-segment-options"] }, input.options.map((option, index) => h("label", {}, [
+          h("input", {
+            ...attrs,
+            id: `${controlId}-${index}`,
+            type: "radio",
+            name: controlId,
+            value: String(index),
+            checked: valueKey(option.value) === valueKey(input.default)
+          }),
+          t(option.label)
+        ])))
+      ]);
+    if (input.type === "date-range")
+      return h("fieldset", { className: ["explore-dates"] }, [
+        h("legend", {}, [t(input.label)]),
+        ...["start", "end"].map((part) => h("label", {}, [
+          t(part === "start" ? "From" : "Through"),
+          h("input", {
+            ...attrs,
+            id: `${controlId}-${part}`,
+            type: "date",
+            dataRangePart: part,
+            ariaDescribedBy: [`${controlId}-ranges`],
+            value: input.default[part]
+          })
+        ]))
+      ]);
+    if (input.type === "toggle")
+      return h("label", { className: ["explore-toggle"] }, [
+        h("input", { ...attrs, type: "checkbox", checked: input.default }),
+        t(input.label)
+      ]);
+    if (input.type === "select")
+      return h("div", { className: ["explore-field"] }, [
+        h("label", { htmlFor: [controlId] }, [t(input.label)]),
+        h("select", attrs, input.options.map((option, index) => h("option", {
+          value: String(index),
+          selected: valueKey(option.value) === valueKey(input.default)
+        }, [t(option.label)])))
+      ]);
+    return h("div", { className: ["explore-field"] }, [
+      h("label", { htmlFor: [controlId] }, [t(input.label)]),
+      h("input", {
+        ...attrs,
+        type: input.type === "number" ? "number" : "text",
+        value: String(input.default),
+        ...input.type === "number" ? { step: "any" } : {},
+        list: `${controlId}-choices`
+      }),
+      h("datalist", { id: `${controlId}-choices` }, input.options.map((option) => h("option", { value: String(option.value) }, [t(option.label)])))
+    ]);
+  });
+  const selected = data.views.find((view) => view.id === data.defaultView);
+  return [
+    h("section", {
+      className: ["exploration"],
+      dataPlotleafExplore: id,
+      ariaLabel: block.props.title
+    }, [
+      h("h2", { id: `${id}-title` }, [t(block.props.title)]),
+      h("div", { className: ["explore-controls"] }, [
+        ...controls,
+        h("button", { type: "button", disabled: true, dataPlotleafReset: true }, [t("Reset")])
+      ]),
+      ...data.inputs.flatMap((input, inputIndex) => input.type === "date-range" ? [
+        h("p", {
+          id: `${id}-input-${inputIndex}-ranges`,
+          className: ["explore-supported"]
+        }, [
+          t(`${input.label} — prepared ranges: ${input.options.map((option) => option.label).join(" · ")}`)
+        ])
+      ] : []),
+      h("p", {
+        className: ["explore-status"],
+        dataPlotleafStatus: true,
+        role: "status",
+        ariaLive: "polite"
+      }, [t(`Showing ${selected.label} · Prepared view`)]),
+      h("noscript", {}, [
+        t("JavaScript is disabled. The default prepared view is shown; controls are unavailable.")
+      ]),
+      ...data.views.map((view) => h("section", {
+        dataPlotleafView: view.id,
+        ariaLabel: view.label,
+        hidden: view.id !== data.defaultView
+      }, render(view.blocks, `${id}-${view.id}-`)))
+    ])
+  ];
+}
+
+// src/render/content.ts
+import { unified as unified2 } from "unified";
+import remarkRehype from "remark-rehype";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+
 // src/shared/format.ts
 var numbers = new Map;
 function formatValue(value, format = "number", sign = "auto", compact = false) {
@@ -1213,6 +1604,14 @@ var serializer = unified2().use(rehypeSanitize, {
   clobberPrefix: "",
   tagNames: [
     ...defaultSchema.tagNames ?? [],
+    "select",
+    "option",
+    "input",
+    "label",
+    "fieldset",
+    "legend",
+    "datalist",
+    "noscript",
     "figure",
     "figcaption",
     "button",
@@ -1234,6 +1633,11 @@ var serializer = unified2().use(rehypeSanitize, {
       "ariaLabelledBy",
       "ariaHidden",
       "ariaSort",
+      "hidden",
+      "ariaLive",
+      "dataPlotleafExplore",
+      "dataPlotleafView",
+      "dataPlotleafStatus",
       "dataPlotleafChart",
       "dataPlotleafTable",
       "dataColumn",
@@ -1244,8 +1648,36 @@ var serializer = unified2().use(rehypeSanitize, {
       "dataStatus",
       "dataSlice"
     ],
-    button: ["type", "disabled", "ariaLabel", "dataColumn"],
-    section: ["className", "ariaLabel"],
+    input: [
+      "id",
+      "type",
+      "name",
+      "value",
+      "checked",
+      "disabled",
+      "step",
+      "list",
+      "dataPlotleafInput",
+      "dataRangePart",
+      "ariaDescribedBy"
+    ],
+    select: ["id", "disabled", "dataPlotleafInput"],
+    option: ["value", "selected"],
+    label: ["htmlFor", "className"],
+    button: [
+      "type",
+      "disabled",
+      "ariaLabel",
+      "dataColumn",
+      "dataPlotleafReset"
+    ],
+    section: [
+      "className",
+      "ariaLabel",
+      "dataPlotleafExplore",
+      "dataPlotleafView",
+      "hidden"
+    ],
     meter: ["min", "max", "value", "className", "ariaLabel"],
     svg: ["className", "viewBox", "width", "height", "role", "ariaLabel"],
     use: ["href"],
@@ -1258,7 +1690,7 @@ var serializer = unified2().use(rehypeSanitize, {
     td: ["className", "dataRaw"]
   }
 }).use(rehypeStringify);
-function label(field) {
+function label2(field) {
   const value = field.replaceAll("_", " ");
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
@@ -1274,7 +1706,7 @@ function table(rows, columns, title, id, sortable = true) {
   const numeric = columns.map((column) => column.kind === "sparkline" || rows.some((row) => typeof row[column.field] === "number") || Boolean(column.format));
   const caption = h("caption", {}, [t(title)]);
   const headers = columns.map((column, index) => {
-    const name = column.label ?? label(column.field);
+    const name = column.label ?? label2(column.field);
     const content = canSort[index] ? h("button", {
       type: "button",
       disabled: true,
@@ -1335,13 +1767,13 @@ function renderContent(report) {
     headings.set(slug, count + 1);
     return `plotleaf-heading-${slug}${count ? `-${count + 1}` : ""}`;
   };
-  function decorate(node) {
+  function decorate(node, namespace = "") {
     if (node.type !== "element")
       return;
     if (/^h[1-6]$/.test(node.tagName)) {
       const text = (child) => child.type === "text" ? child.value : child.children.map((n) => text(n)).join("");
-      node.properties.id = headingId(text(node));
-      if (node.tagName === "h1")
+      node.properties.id = headingId(namespace + text(node));
+      if (node.tagName === "h1" && !namespace)
         hasH1 = true;
     }
     if (node.tagName === "a" && typeof node.properties.href === "string") {
@@ -1350,22 +1782,24 @@ function renderContent(report) {
         try {
           fragment = decodeURIComponent(fragment);
         } catch {}
-        node.properties.href = `#plotleaf-heading-${slugOf(fragment)}`;
+        node.properties.href = `#plotleaf-heading-${slugOf(namespace + fragment)}`;
       }
       if (/^https?:/.test(node.properties.href))
         node.properties.rel = ["noopener", "noreferrer"];
     }
-    node.children.forEach((child) => decorate(child));
+    node.children.forEach((child) => decorate(child, namespace));
   }
-  function render(blocks) {
+  function render(blocks, namespace = "") {
     return blocks.flatMap((block) => {
       if (block.type === "markdown") {
         const root = markdown.runSync(block.tree);
-        root.children.forEach((child) => decorate(child));
+        root.children.forEach((child) => decorate(child, namespace));
         return root.children;
       }
       const id = `plotleaf-component-${String(++sequence).padStart(4, "0")}`;
       switch (block.name) {
+        case "explore":
+          return exploration(block, id, render, payload.explorations ??= []);
         case "grid":
           return [
             h("div", {
@@ -1374,7 +1808,7 @@ function renderContent(report) {
                 ...block.children.length > 0 && block.children.every((child) => child.type === "component" && child.name === "metric") ? ["metric-grid"] : []
               ],
               dataColumns: block.props.columns
-            }, render(block.children))
+            }, render(block.children, namespace))
           ];
         case "metric": {
           const props = block.props;
@@ -1411,7 +1845,7 @@ function renderContent(report) {
                   t(block.props.title)
                 ])
               ] : [],
-              ...render(block.children)
+              ...render(block.children, namespace)
             ])
           ];
         case "table":
@@ -1440,17 +1874,17 @@ function renderContent(report) {
     const { stage, value, total, share, status, title, format } = block.props;
     const rows = block.rows ?? [];
     const columns = [
-      { field: stage, label: label(stage), sign: "auto", semantics: "neutral" },
+      { field: stage, label: label2(stage), sign: "auto", semantics: "neutral" },
       {
         field: value,
-        label: label(value),
+        label: label2(value),
         format,
         sign: "auto",
         semantics: "neutral"
       },
       {
         field: total,
-        label: label(total),
+        label: label2(total),
         format,
         sign: "auto",
         semantics: "neutral"
@@ -1570,13 +2004,13 @@ function renderContent(report) {
           dataDisclosure(rows, [
             {
               field: category,
-              label: label(category),
+              label: label2(category),
               sign: "auto",
               semantics: "neutral"
             },
             {
               field: value,
-              label: label(value),
+              label: label2(value),
               format,
               sign: "auto",
               semantics: "neutral"
@@ -1611,8 +2045,8 @@ function renderContent(report) {
       payload.charts.push(chart);
     }
     const columns = [
-      { field: x, label: label(x), sign: "auto", semantics: "neutral" },
-      { field: y, label: label(y), format, sign: "auto", semantics: "neutral" }
+      { field: x, label: label2(x), sign: "auto", semantics: "neutral" },
+      { field: y, label: label2(y), format, sign: "auto", semantics: "neutral" }
     ];
     return [
       h("figure", { className: ["chart"] }, [
@@ -1645,26 +2079,35 @@ function renderContent(report) {
   };
 }
 
-// src/render/html.ts
+// src/render/document.ts
 var escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 var inlineScript = (value) => value.replace(/<\/script/gi, "<\\/script").replaceAll("<!--", "\\x3c!--");
 var reload = (revision) => `(()=>{const source=new EventSource("/__plotleaf/events");source.addEventListener("ready",event=>{if(Number(event.data)!==${revision})location.reload()});source.addEventListener("reload",()=>location.reload());addEventListener("pagehide",()=>source.close(),{once:true});})();`;
-function documentHtml(title, description, body, styles, scripts, preview, payload, notices = "", revision = 0) {
+function documentHtml(title, description, body, styles, scripts, preview, hash, payload, notices = "", revision = 0) {
   const code = [...scripts, ...preview ? [reload(revision)] : []].map(inlineScript);
-  const hashes = code.map((script) => `'sha256-${createHash2("sha256").update(script).digest("base64")}'`).join(" ");
+  const hashes = code.map((script) => `'sha256-${hash(script)}'`).join(" ");
   const policy = `default-src 'none'; script-src ${hashes || "'none'"}; style-src 'unsafe-inline'; img-src data:; font-src data:; connect-src ${preview ? "'self'" : "'none'"}; base-uri 'none'; object-src 'none'; form-action 'none'`;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escapeHtml(policy)}"><meta name="color-scheme" content="light dark"><title>${escapeHtml(title)}</title>${description ? `<meta name="description" content="${escapeHtml(description)}">` : ""}<style>${styles}</style></head><body><a class="skip-link" href="#plotleaf-report">Skip to report</a><main class="report" id="plotleaf-report">${body}</main>${payload ? `<script type="application/json" id="plotleaf-data">${payload}</script>` : ""}${notices ? `<template id="plotleaf-notices"><pre>${escapeHtml(notices)}</pre></template>` : ""}${code.map((script) => `<script>${script}</script>`).join("")}</body></html>
 `;
 }
-function renderHtml(report, assets, preview = false, revision = 0) {
+function renderHtml(report, assets, hash, preview = false, revision = 0) {
   const content = renderContent(report);
   const images = report.images?.length ? `<svg class="image-definitions" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><defs>${report.images.map((image) => `<symbol id="${escapeHtml(image.id)}" viewBox="0 0 64 48"><image href="data:${image.mime};base64,${image.base64}" width="64" height="48" preserveAspectRatio="xMidYMid meet"/></symbol>`).join("")}</defs></svg>` : "";
-  return documentHtml(report.metadata.title, report.metadata.description, images + content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, content.hasCharts ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
+  return documentHtml(report.metadata.title, report.metadata.description, images + content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, hash, content.hasCharts || content.payload.explorations?.length ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
 }
-function renderDiagnostics(diagnostics, assets, preview = true, revision = 0) {
+function renderDiagnostics(diagnostics, assets, hash, preview = true, revision = 0) {
   const body = `<h1>Report needs attention</h1><p class="diagnostic-intro">Update the source files to refresh this preview.</p>${diagnostics.map((item) => `<section class="diagnostic"><p class="diagnostic-location">${escapeHtml(item.file)}:${item.line}:${item.column} · ${escapeHtml(item.code)}</p><p>${escapeHtml(item.message)}</p>${item.hint ? `<p class="diagnostic-hint">${escapeHtml(item.hint)}</p>` : ""}</section>`).join("")}`;
-  return documentHtml("Report needs attention", undefined, body, assets.styles, [], preview, undefined, "", revision);
+  return documentHtml("Report needs attention", undefined, body, assets.styles, [], preview, hash, undefined, "", revision);
+}
+
+// src/render/html.ts
+var hash = (script) => createHash2("sha256").update(script).digest("base64");
+function renderHtml2(report, assets, preview = false, revision = 0) {
+  return renderHtml(report, assets, hash, preview, revision);
+}
+function renderDiagnostics2(diagnostics, assets, preview = true, revision = 0) {
+  return renderDiagnostics(diagnostics, assets, hash, preview, revision);
 }
 
 // src/export.ts
@@ -1749,7 +2192,7 @@ async function startPreview(filename, assets, options = {}) {
   const log = options.log ?? console.log;
   let compilation = options.initial ?? await compileReport(filename);
   let revision = 0;
-  const render = () => compilation.report ? renderHtml(compilation.report, assets, true, revision) : renderDiagnostics(compilation.diagnostics, assets, true, revision);
+  const render = () => compilation.report ? renderHtml2(compilation.report, assets, true, revision) : renderDiagnostics2(compilation.diagnostics, assets, true, revision);
   let html = render();
   let closed = false;
   let running = false;
@@ -1892,7 +2335,7 @@ data: ${revision}
 // package.json
 var package_default = {
   name: "plotleaf",
-  version: "0.3.1",
+  version: "0.4.0",
   description: "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   type: "module",
   license: "MIT",
@@ -1900,7 +2343,7 @@ var package_default = {
     type: "git",
     url: "git+https://github.com/LoueeD/plotleaf.git"
   },
-  homepage: "https://github.com/LoueeD/plotleaf#readme",
+  homepage: "https://plotleaf-site.loueed.workers.dev",
   bugs: {
     url: "https://github.com/LoueeD/plotleaf/issues"
   },
@@ -1919,6 +2362,8 @@ var package_default = {
     "dist/assets/notices.txt",
     "schema/components.json",
     "examples/report.md",
+    "examples/interactions/*.md",
+    "examples/interactions/*.json",
     "examples/storefront/*.md",
     "examples/storefront/*.json",
     "examples/adoption/*.md",
@@ -2077,7 +2522,7 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    const html = renderHtml(result.report, await assets());
+    const html = renderHtml2(result.report, await assets());
     const defaultOutput = result.filename.slice(0, -path6.extname(result.filename).length) + ".html";
     const destination = await writeReport(values.out ?? defaultOutput, html, result.dependencies);
     console.log(`Built ${displayPath(destination)} (${(Buffer.byteLength(html) / 1024).toFixed(1)} KiB)`);