plotleaf 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,1431 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import path5 from "node:path";
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+
+// src/compiler/compile.ts
+import path3 from "node:path";
+import { realpath as realpath2 } from "node:fs/promises";
+
+// src/compiler/diagnostics.ts
+import path from "node:path";
+
+class Diagnostics {
+  file;
+  items = [];
+  errors = false;
+  constructor(file) {
+    this.file = file;
+  }
+  add(code, message, position, hint, severity = "error") {
+    if (severity === "error")
+      this.errors = true;
+    if (this.items.length >= 100) {
+      this.errors = true;
+      this.items[99] = {
+        code: "E_DIAGNOSTIC_LIMIT",
+        severity: "error",
+        file: this.file,
+        line: position?.start.line ?? 1,
+        column: position?.start.column ?? 1,
+        message: "Report exceeds the limit of 100 diagnostics. Fix the reported issues first."
+      };
+      return;
+    }
+    this.items.push({
+      code,
+      severity,
+      file: this.file,
+      line: position?.start.line ?? 1,
+      column: position?.start.column ?? 1,
+      message: message.length > 2000 ? message.slice(0, 1999) + "…" : message,
+      ...hint ? { hint: hint.length > 1500 ? hint.slice(0, 1499) + "…" : hint } : {}
+    });
+  }
+  get hasErrors() {
+    return this.errors;
+  }
+  sorted() {
+    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 ? `
+${d.hint}` : ""}`).join(`
+
+`);
+}
+
+// src/compiler/data.ts
+import path2 from "node:path";
+import { open, realpath, stat } from "node:fs/promises";
+
+// src/shared/limits.ts
+var limits = {
+  markdownBytes: 1024 ** 2,
+  jsonBytes: 10 * 1024 ** 2,
+  totalBytes: 25 * 1024 ** 2,
+  datasets: 64,
+  rows: 1e5,
+  chartRows: 1e4,
+  tableRows: 1000,
+  tableColumns: 40
+};
+
+// src/compiler/data.ts
+var reserved = new Set(["__proto__", "constructor", "prototype"]);
+function contained(root, filename) {
+  const relative = path2.relative(root, filename);
+  return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
+}
+async function readBounded(filename, maximum) {
+  if (!(await stat(filename)).isFile())
+    throw new Error("Expected a regular file.");
+  const file = await open(filename, "r");
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile())
+      throw new Error("Expected a regular file.");
+    if (stat.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 {
+      text: new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks, bytes)),
+      bytes
+    };
+  } finally {
+    await file.close();
+  }
+}
+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;
+  totalBytes;
+  cache = new Map;
+  constructor(root, diagnostics, dependencies, totalBytes = 0) {
+    this.root = root;
+    this.diagnostics = diagnostics;
+    this.dependencies = dependencies;
+    this.totalBytes = totalBytes;
+  }
+  async load(reference, block) {
+    const fail = (code, message, hint) => {
+      this.diagnostics.add(code, `${reference}: ${message}`, block.position, hint);
+      return;
+    };
+    if (path2.isAbsolute(reference) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(reference) || reference.includes("\\") || /%[\da-f]{2}/i.test(reference) || reference.includes("\x00"))
+      return fail("E_DATA_PATH", "Use a plain relative local .json path.");
+    const candidate = path2.resolve(this.root, reference);
+    if (!contained(this.root, candidate))
+      return fail("E_DATA_PATH", "Reference escapes the report directory.", "Place prepared JSON beside the report or in one of its subdirectories.");
+    if (path2.relative(this.root, candidate).split(path2.sep).some((segment) => segment.startsWith(".")))
+      return fail("E_DATA_PATH", "Hidden files and directories are not allowed.");
+    if (path2.extname(candidate).toLowerCase() !== ".json")
+      return fail("E_DATA_PATH", "Datasets must be .json files.");
+    this.dependencies.add(candidate);
+    let canonical;
+    try {
+      canonical = await realpath(candidate);
+    } catch {
+      return fail("E_DATA_READ", "Cannot read the referenced dataset.", "Create the file at this path or correct the data property.");
+    }
+    if (!contained(this.root, canonical) || path2.relative(this.root, canonical).split(path2.sep).some((segment) => segment.startsWith(".")))
+      return fail("E_DATA_PATH", "The resolved file or symlink escapes the permitted report files.");
+    if (path2.extname(canonical).toLowerCase() !== ".json")
+      return fail("E_DATA_PATH", "The resolved file must also have a .json extension.");
+    this.dependencies.add(canonical);
+    const cached = this.cache.get(canonical);
+    if (cached)
+      return cached;
+    if (this.cache.size >= limits.datasets)
+      return fail("E_DATA_LIMIT", `At most ${limits.datasets} datasets are supported.`);
+    let input;
+    try {
+      input = await readBounded(canonical, Math.min(limits.jsonBytes, limits.totalBytes - this.totalBytes));
+    } catch (error) {
+      return fail("E_DATA_READ", error instanceof Error ? error.message : "Could not read data.");
+    }
+    this.totalBytes += input.bytes;
+    let parsed;
+    try {
+      parsed = JSON.parse(input.text);
+    } catch {
+      return fail("E_DATA_JSON", "Invalid JSON.", "Use a JSON array of flat records, without comments or trailing commas.");
+    }
+    if (!Array.isArray(parsed))
+      return fail("E_DATA_SHAPE", "Expected an array of flat JSON records.");
+    if (parsed.length > limits.rows)
+      return fail("E_DATA_LIMIT", `Dataset exceeds ${limits.rows.toLocaleString("en-GB")} rows.`, "Prepare a smaller aggregate dataset before rendering.");
+    for (const [index, row] of parsed.entries()) {
+      if (!row || typeof row !== "object" || Array.isArray(row))
+        return fail("E_DATA_SHAPE", `Row ${index + 1} is not a record.`);
+      for (const [key, value] of Object.entries(row)) {
+        if (reserved.has(key))
+          return fail("E_DATA_KEY", `Row ${index + 1} contains the reserved key ${JSON.stringify(key)}.`);
+        if (!(value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)))
+          return fail("E_DATA_SHAPE", `Row ${index + 1}, field ${JSON.stringify(key)} must contain a finite number, string, boolean or null.`, "Prepare flat scalar records. Nested cells and sparkline data are planned separately.");
+      }
+    }
+    const rows = parsed;
+    this.cache.set(canonical, rows);
+    return rows;
+  }
+  async resolve(blocks) {
+    for (const block of blocks) {
+      if (block.type !== "component")
+        continue;
+      if (block.name === "line" || block.name === "area" || block.name === "bar" || block.name === "table") {
+        const rows = await this.load(block.props.data, block);
+        if (rows) {
+          if (!rows.length)
+            this.diagnostics.add("W_DATA_EMPTY", `${block.props.data} is empty; a no-data state will be shown.`, block.position, "Field validation requires at least one record.", "warning");
+          if (block.name === "table")
+            this.resolveTable(block, rows);
+          else
+            this.resolveChart(block, rows);
+        }
+      }
+      await this.resolve(block.children);
+    }
+  }
+  field(rows, name, block) {
+    const index = rows.findIndex((row) => !Object.hasOwn(row, name));
+    if (index < 0)
+      return true;
+    const available = Object.keys(rows[index] ?? {});
+    this.diagnostics.add("E_DATA_FIELD", `${block.name} references missing field ${JSON.stringify(name)} in ${block.props && "data" in block.props ? block.props.data : "dataset"}, row ${index + 1}.`, block.position, `Available fields: ${available.slice(0, 12).join(", ") || "none"}${available.length > 12 ? ` … (${available.length - 12} more)` : ""}.`);
+    return false;
+  }
+  resolveChart(block, rows) {
+    const { x, y } = block.props;
+    if (rows.length > limits.chartRows) {
+      this.diagnostics.add("E_DATA_LIMIT", `Chart exceeds ${limits.chartRows} points/categories.`, block.position, "Prepare a smaller chart aggregate.");
+      return;
+    }
+    if (!this.field(rows, x, block) || !this.field(rows, y, block))
+      return;
+    const kind = block.name === "bar" ? "category" : block.props.xType;
+    const seen = new Set;
+    let previous = -Infinity;
+    for (const [index, row] of rows.entries()) {
+      const xv = row[x];
+      const yv = row[y];
+      const validY = typeof yv === "number" && Number.isFinite(yv) || block.name !== "bar" && yv === null;
+      let normalized;
+      if (kind === "category" && (typeof xv === "string" || typeof xv === "number"))
+        normalized = String(xv);
+      if (kind === "number" && typeof xv === "number")
+        normalized = xv;
+      if (kind === "date" && typeof xv === "string")
+        normalized = parseDate(xv);
+      if (normalized === undefined || !validY) {
+        this.diagnostics.add("E_DATA_TYPE", `${block.props.data}, row ${index + 1}: ${JSON.stringify(x)} must be ${kind === "date" ? "an ISO date or zoned timestamp" : `a ${kind === "number" ? "number" : "string or number category"}`} and ${JSON.stringify(y)} must be ${block.name === "bar" ? "a number" : "a number or null"}.`, block.position);
+        return;
+      }
+      if (seen.has(normalized) || typeof normalized === "number" && kind !== "category" && normalized <= previous) {
+        this.diagnostics.add("E_DATA_ORDER", `${block.props.data}, row ${index + 1}: x values must be unique${kind !== "category" ? " and increasing" : ""}.`, block.position, "Sort or aggregate the prepared dataset; plotleaf does not silently change chart data.");
+        return;
+      }
+      seen.add(normalized);
+      if (typeof normalized === "number")
+        previous = normalized;
+    }
+    block.rows = rows.map((row) => Object.fromEntries([...new Set([x, y])].map((key) => [key, row[key]])));
+  }
+  resolveTable(block, rows) {
+    if (rows.length > limits.tableRows) {
+      this.diagnostics.add("E_DATA_LIMIT", `Table exceeds ${limits.tableRows} rows.`, block.position, "Provide a prepared summary table; rows are never silently truncated.");
+      return;
+    }
+    const inferred = Object.keys(rows[0] ?? {});
+    const explicit = block.children.filter((child) => child.type === "component" && child.name === "column");
+    const columns = explicit.length ? explicit.map((column) => column.props) : inferred.map((field) => ({
+      field,
+      sign: "auto",
+      semantics: "neutral"
+    }));
+    if (columns.length > limits.tableColumns) {
+      this.diagnostics.add("E_DATA_LIMIT", `Table exceeds ${limits.tableColumns} columns.`, block.position, "Declare a smaller selection of column fields.");
+      return;
+    }
+    if (new Set(columns.map((column) => column.field)).size !== columns.length)
+      this.diagnostics.add("E_TABLE_COLUMN", "A table cannot declare the same column field twice.", block.position);
+    for (const [index, row] of rows.entries())
+      if (Object.keys(row).length !== inferred.length || inferred.some((field) => !Object.hasOwn(row, field))) {
+        this.diagnostics.add("E_DATA_SHAPE", `${block.props.data}, row ${index + 1}: table records must have consistent keys.`, block.position);
+        return;
+      }
+    for (const column of columns) {
+      if (!this.field(rows, column.field, block))
+        continue;
+      const types = new Set(rows.map((row) => row[column.field]).filter((value) => value !== null).map((value) => typeof value));
+      if (types.size > 1)
+        this.diagnostics.add("E_DATA_TYPE", `Table field ${JSON.stringify(column.field)} has mixed non-null types.`, block.position);
+      if ((column.format || column.sign !== "auto" || column.semantics !== "neutral") && types.size && !types.has("number"))
+        this.diagnostics.add("E_TABLE_FORMAT", `Numeric formatting/sign/semantics cannot be applied to ${JSON.stringify(column.field)}.`, block.position);
+    }
+    block.columns = columns;
+    block.rows = rows.map((row) => Object.fromEntries(columns.map((column) => [column.field, row[column.field]])));
+  }
+}
+
+// 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", "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"}'
+  },
+  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: "An explicit field, label and format inside a table.",
+    schema: z.strictObject({
+      field: text,
+      label: 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"}'
+  },
+  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.
+:::`
+  }
+};
+function componentSpec() {
+  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",
+      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
+      }
+    ])),
+    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.",
+      "Filters, maps, images, nested data and executable components are not supported in this release."
+    ]
+  };
+}
+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 ("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", "Report images are not supported in this initial release.", node.position, "Use a text link; local raster images are planned for the rich-table increment.");
+    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/compile.ts
+async function compileReport(input) {
+  const requested = path3.resolve(input);
+  const diagnostics = new Diagnostics(displayPath(requested));
+  const dependencies = new Set([requested]);
+  const result = () => ({
+    diagnostics: diagnostics.sorted(),
+    dependencies,
+    filename: requested
+  });
+  try {
+    if (path3.extname(requested).toLowerCase() !== ".md") {
+      diagnostics.add("E_REPORT_PATH", "A report must be a .md Markdown file.");
+      return result();
+    }
+    const filename = await realpath2(requested);
+    dependencies.add(filename);
+    const { text, bytes } = await readBounded(filename, limits.markdownBytes);
+    const report = parseReport(text, path3.basename(filename, path3.extname(filename)), diagnostics);
+    const resolver = new DataResolver(path3.dirname(filename), diagnostics, dependencies, bytes);
+    await resolver.resolve(report.blocks);
+    return { ...result(), ...!diagnostics.hasErrors ? { report } : {} };
+  } catch (error) {
+    diagnostics.add("E_REPORT_READ", error instanceof Error ? error.message.replaceAll(requested, displayPath(requested)) : "Could not compile the report.");
+    return result();
+  }
+}
+
+// src/render/html.ts
+import { createHash } 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/shared/format.ts
+var numbers = new Map;
+function formatValue(value, format = "number", sign = "auto", compact = false) {
+  const key = `${format}:${sign}:${compact}`;
+  let formatter = numbers.get(key);
+  if (!formatter) {
+    const options = {
+      maximumFractionDigits: 2,
+      signDisplay: sign
+    };
+    if (format === "percent")
+      Object.assign(options, { style: "percent", maximumFractionDigits: 1 });
+    if (format.startsWith("currency:"))
+      Object.assign(options, {
+        style: "currency",
+        currency: format.slice(9),
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+        trailingZeroDisplay: "stripIfInteger"
+      });
+    if (compact && format === "number")
+      Object.assign(options, { notation: "compact", maximumFractionDigits: 1 });
+    formatter = new Intl.NumberFormat("en-GB", options);
+    numbers.set(key, formatter);
+  }
+  return formatter.format(value) + (format === "percentage-points" ? " pt" : "");
+}
+function valueSentiment(value, semantics = "neutral") {
+  if (value === 0 || semantics === "neutral")
+    return "neutral";
+  return value > 0 === (semantics === "higher-is-better") ? "positive" : "negative";
+}
+
+// src/shared/serialize.ts
+function serializeData(value) {
+  return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll(">", "\\u003e").replaceAll("&", "\\u0026").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+
+// src/render/content.ts
+var t = (value) => ({ type: "text", value: String(value) });
+var h = (tagName, properties = {}, children = []) => ({ type: "element", tagName, properties, children });
+var markdown = unified2().use(remarkRehype);
+var serializer = unified2().use(rehypeSanitize, {
+  ...defaultSchema,
+  clobberPrefix: "",
+  tagNames: [
+    ...defaultSchema.tagNames ?? [],
+    "figure",
+    "figcaption",
+    "button",
+    "caption"
+  ],
+  attributes: {
+    ...defaultSchema.attributes,
+    "*": [
+      ...defaultSchema.attributes?.["*"] ?? [],
+      "className",
+      "id",
+      "role",
+      "ariaLabel",
+      "ariaLabelledBy",
+      "ariaHidden",
+      "ariaSort",
+      "dataPlotleafChart",
+      "dataPlotleafTable",
+      "dataColumn",
+      "dataRaw",
+      "dataColumns",
+      "dataSentiment",
+      "dataTone"
+    ],
+    button: ["type", "disabled", "ariaLabel", "dataColumn"],
+    section: ["className", "ariaLabel"],
+    th: ["scope", "ariaSort", "className"],
+    td: ["className", "dataRaw"]
+  }
+}).use(rehypeStringify);
+function label(field) {
+  const value = field.replaceAll("_", " ");
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function slugOf(text) {
+  return text.toLowerCase().normalize("NFKD").replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/\s+/g, "-") || "section";
+}
+function cellText(value, column) {
+  return value === null ? "—" : typeof value === "number" ? formatValue(value, column.format, column.sign) : String(value);
+}
+function table(rows, columns, title, id, sortable = true) {
+  const numeric = columns.map((column) => 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 content = sortable ? h("button", {
+      type: "button",
+      disabled: true,
+      dataColumn: index,
+      ariaLabel: `Sort by ${name}`
+    }, [
+      t(name),
+      h("span", { className: ["sort-indicator"], ariaHidden: "true" }, [
+        t("↕")
+      ])
+    ]) : t(name);
+    return h("th", {
+      scope: "col",
+      className: numeric[index] ? ["numeric"] : [],
+      ...sortable ? { ariaSort: "none" } : {}
+    }, [content]);
+  });
+  const head = h("thead", {}, [h("tr", {}, headers)]);
+  const tableRows = rows.map((row) => {
+    const cells = columns.map((column, index) => {
+      const value = row[column.field] ?? null;
+      return h("td", {
+        className: numeric[index] ? ["numeric"] : [],
+        dataRaw: serializeData(value),
+        ...typeof value === "number" ? { dataSentiment: valueSentiment(value, column.semantics) } : {}
+      }, [t(cellText(value, column))]);
+    });
+    return h("tr", {}, cells);
+  });
+  const body = h("tbody", {}, tableRows);
+  return h("div", { className: ["table-scroll"] }, [
+    h("table", { id, ...sortable ? { dataPlotleafTable: "" } : {} }, [
+      caption,
+      head,
+      body
+    ])
+  ]);
+}
+function renderContent(report) {
+  let sequence = 0;
+  const payload = { charts: [] };
+  const headings = new Map;
+  let hasH1 = false;
+  const headingId = (text) => {
+    const slug = slugOf(text);
+    const count = headings.get(slug) ?? 0;
+    headings.set(slug, count + 1);
+    return `plotleaf-heading-${slug}${count ? `-${count + 1}` : ""}`;
+  };
+  function decorate(node) {
+    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")
+        hasH1 = true;
+    }
+    if (node.tagName === "a" && typeof node.properties.href === "string") {
+      if (node.properties.href.startsWith("#") && !node.properties.href.startsWith("#plotleaf-heading-")) {
+        let fragment = node.properties.href.slice(1);
+        try {
+          fragment = decodeURIComponent(fragment);
+        } catch {}
+        node.properties.href = `#plotleaf-heading-${slugOf(fragment)}`;
+      }
+      if (/^https?:/.test(node.properties.href))
+        node.properties.rel = ["noopener", "noreferrer"];
+    }
+    node.children.forEach((child) => decorate(child));
+  }
+  function render(blocks) {
+    return blocks.flatMap((block) => {
+      if (block.type === "markdown") {
+        const root = markdown.runSync(block.tree);
+        root.children.forEach((child) => decorate(child));
+        return root.children;
+      }
+      const id = `plotleaf-component-${String(++sequence).padStart(4, "0")}`;
+      switch (block.name) {
+        case "grid":
+          return [
+            h("div", {
+              className: [
+                "component-grid",
+                ...block.children.length > 0 && block.children.every((child) => child.type === "component" && child.name === "metric") ? ["metric-grid"] : []
+              ],
+              dataColumns: block.props.columns
+            }, render(block.children))
+          ];
+        case "metric": {
+          const props = block.props;
+          const comparison = props.comparison ? h("p", {
+            className: ["metric-comparison"],
+            dataSentiment: props.sentiment,
+            ariaLabel: `${props.direction === "up" ? "Increased: " : props.direction === "down" ? "Decreased: " : ""}${props.comparison}`
+          }, [
+            ...props.direction ? [
+              h("span", {
+                ariaHidden: "true",
+                className: ["metric-direction"]
+              }, [
+                t(props.direction === "up" ? "▲" : props.direction === "down" ? "▼" : "—")
+              ])
+            ] : [],
+            t(props.comparison)
+          ]) : null;
+          return [
+            h("section", { className: ["metric"], ariaLabel: props.label }, [
+              h("p", { className: ["metric-label"] }, [t(props.label)]),
+              h("p", { className: ["metric-value"] }, [
+                t(formatValue(props.value, props.format))
+              ]),
+              ...comparison ? [comparison] : []
+            ])
+          ];
+        }
+        case "callout":
+          return [
+            h("aside", { className: ["callout"], dataTone: block.props.tone }, [
+              ...block.props.title ? [
+                h("p", { className: ["callout-title"] }, [
+                  t(block.props.title)
+                ])
+              ] : [],
+              ...render(block.children)
+            ])
+          ];
+        case "table":
+          return [
+            table(block.rows ?? [], block.columns ?? [], block.props.title ?? "Data", id),
+            ...!block.rows?.length ? [
+              h("p", { className: ["empty-state"] }, [
+                t("No data to display.")
+              ])
+            ] : []
+          ];
+        case "column":
+          return [];
+        case "line":
+        case "area":
+        case "bar":
+          return renderChart(block, id);
+      }
+    });
+  }
+  function renderChart(block, id) {
+    const { x, y, title, format } = block.props;
+    const xType = block.name === "bar" ? "category" : block.props.xType;
+    const rows = block.rows ?? [];
+    if (rows.length) {
+      const chart = {
+        id,
+        kind: block.name,
+        title,
+        xType,
+        x,
+        y,
+        format,
+        rows: rows.map((row) => [
+          xType === "date" ? parseDate(row[x]) : xType === "category" ? String(row[x]) : row[x],
+          row[y]
+        ])
+      };
+      if (block.name !== "bar") {
+        chart.target = block.props.target;
+        chart.targetLabel = block.props.targetLabel;
+      }
+      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" }
+    ];
+    return [
+      h("figure", { className: ["chart"] }, [
+        h("figcaption", { id: `${id}-title` }, [t(title)]),
+        ...rows.length ? [
+          h("div", {
+            className: ["chart-plot"],
+            id,
+            dataPlotleafChart: "",
+            role: "img",
+            ariaLabel: `${title}. Data is available in the table below.`
+          })
+        ] : [
+          h("p", { className: ["empty-state"] }, [
+            t("No data to display.")
+          ])
+        ],
+        ...rows.length ? [
+          h("details", { className: ["chart-data"] }, [
+            h("summary", {}, [
+              t("View data"),
+              h("span", { className: ["visually-hidden"] }, [
+                t(` for ${title}`)
+              ])
+            ]),
+            table(rows, columns, title, `${id}-data`, false)
+          ])
+        ] : []
+      ])
+    ];
+  }
+  const children = render(report.blocks);
+  if (!hasH1)
+    children.unshift(h("h1", { id: "plotleaf-heading-title" }, [t(report.metadata.title)]));
+  const tree = { type: "root", children };
+  return {
+    html: serializer.stringify(serializer.runSync(tree)),
+    payload,
+    hasCharts: payload.charts.length > 0
+  };
+}
+
+// src/render/html.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) {
+  const code = [...scripts, ...preview ? [reload(revision)] : []].map(inlineScript);
+  const hashes = code.map((script) => `'sha256-${createHash("sha256").update(script).digest("base64")}'`).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) {
+  const content = renderContent(report);
+  return documentHtml(report.metadata.title, report.metadata.description, content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, content.hasCharts ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
+}
+function renderDiagnostics(diagnostics, assets, 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);
+}
+
+// src/export.ts
+import path4 from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  lstat,
+  stat as stat2,
+  realpath as realpath3,
+  mkdir,
+  writeFile,
+  rename,
+  rm
+} from "node:fs/promises";
+async function writeReport(filename, html, inputs) {
+  const destination = path4.resolve(filename);
+  if (path4.extname(destination).toLowerCase() !== ".html")
+    throw new Error("Output must have an .html extension.");
+  let existing;
+  try {
+    const info = await lstat(destination);
+    if (info.isSymbolicLink())
+      throw new Error("Refusing a symbolic-link output destination. Choose a regular .html path.");
+    if (!info.isFile())
+      throw new Error("Output destination is not a regular file.");
+    existing = info;
+  } catch (error) {
+    if (!(error && typeof error === "object" && ("code" in error) && error.code === "ENOENT"))
+      throw error;
+  }
+  let directory = path4.dirname(destination);
+  const missing = [];
+  while (true) {
+    try {
+      directory = await realpath3(directory);
+      break;
+    } catch (error) {
+      if (!(error && typeof error === "object" && ("code" in error) && error.code === "ENOENT"))
+        throw error;
+      missing.unshift(path4.basename(directory));
+      const parent = path4.dirname(directory);
+      if (parent === directory)
+        throw error;
+      directory = parent;
+    }
+  }
+  const canonical = path4.join(directory, ...missing, path4.basename(destination));
+  for (const input of inputs) {
+    if (path4.resolve(input) === canonical || path4.resolve(input) === destination)
+      throw new Error("Output would overwrite a report input or dependency.");
+    if (existing) {
+      try {
+        const source = await stat2(input);
+        if (source.dev === existing.dev && source.ino === existing.ino)
+          throw new Error("Output is a hard link to a report input or dependency.");
+      } catch (error) {
+        if (!(error && typeof error === "object" && ("code" in error) && error.code === "ENOENT"))
+          throw error;
+      }
+    }
+  }
+  await mkdir(path4.dirname(destination), { recursive: true });
+  const temporary = path4.join(path4.dirname(destination), `.plotleaf-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, html, {
+      encoding: "utf8",
+      mode: 384,
+      flag: "wx"
+    });
+    await rename(temporary, destination);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return destination;
+}
+
+// src/preview.ts
+import { createServer } from "node:http";
+import chokidar from "chokidar";
+import open2 from "open";
+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);
+  let html = render();
+  let closed = false;
+  let running = false;
+  let dirty = false;
+  let timer;
+  let opened = false;
+  const clients = new Set;
+  let url = "";
+  const server = createServer((request, response) => {
+    const port = server.address().port;
+    const authority = request.headers.host?.toLowerCase();
+    const allowed = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Cache-Control", "no-store");
+    if (!authority || !allowed.has(authority) || request.headers.origin && ![...allowed].map((host) => `http://${host}`).includes(request.headers.origin)) {
+      response.writeHead(403).end("Forbidden");
+      return;
+    }
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      response.writeHead(405, { Allow: "GET, HEAD" }).end("Method not allowed");
+      return;
+    }
+    let pathname;
+    try {
+      pathname = new URL(request.url ?? "/", `http://127.0.0.1:${port}`).pathname;
+    } catch {
+      response.writeHead(400).end("Bad request");
+      return;
+    }
+    if (pathname === "/") {
+      response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(request.method === "HEAD" ? undefined : html);
+      return;
+    }
+    if (pathname === "/favicon.ico") {
+      response.writeHead(204).end();
+      return;
+    }
+    if (pathname === "/__plotleaf/events" && request.method === "GET") {
+      response.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no"
+      });
+      response.write(`event: ready
+data: ${revision}
+
+`);
+      clients.add(response);
+      request.on("close", () => clients.delete(response));
+      return;
+    }
+    response.writeHead(404).end("Not found");
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  url = `http://127.0.0.1:${server.address().port}`;
+  const watcher = chokidar.watch([...compilation.dependencies], {
+    ignoreInitial: true,
+    followSymlinks: false,
+    atomic: 100,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 25 }
+  });
+  await new Promise((resolve) => watcher.once("ready", resolve));
+  const openOnce = () => {
+    if (!options.openBrowser || opened || !compilation.report)
+      return;
+    opened = true;
+    open2(url).catch(() => log(`Open ${url} in your browser.`));
+  };
+  async function rebuild() {
+    dirty = true;
+    if (running || closed)
+      return;
+    running = true;
+    try {
+      while (dirty && !closed) {
+        dirty = false;
+        const next = await compileReport(filename);
+        if (closed)
+          break;
+        const previous = compilation.dependencies;
+        compilation = next;
+        watcher.add([...next.dependencies]);
+        const removed = [...previous].filter((file) => !next.dependencies.has(file));
+        if (removed.length)
+          watcher.unwatch(removed);
+        revision++;
+        html = render();
+        for (const client of clients)
+          client.write(`event: reload
+data: ${revision}
+
+`);
+        log(compilation.report ? "Report updated." : humanDiagnostics(compilation.diagnostics));
+        openOnce();
+      }
+    } finally {
+      running = false;
+    }
+  }
+  watcher.on("all", () => {
+    if (timer)
+      clearTimeout(timer);
+    timer = setTimeout(() => {
+      rebuild();
+    }, 35);
+  });
+  watcher.on("error", (error) => log(`File watcher: ${error instanceof Error ? error.message : String(error)}`));
+  const heartbeat = setInterval(() => {
+    for (const client of clients)
+      client.write(`: heartbeat
+
+`);
+  }, 15000);
+  heartbeat.unref();
+  async function close() {
+    if (closed)
+      return;
+    closed = true;
+    if (timer)
+      clearTimeout(timer);
+    clearInterval(heartbeat);
+    for (const client of clients)
+      client.end();
+    clients.clear();
+    await watcher.close();
+    await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+  log(`plotleaf preview: ${url}`);
+  if (!compilation.report)
+    log(humanDiagnostics(compilation.diagnostics));
+  openOnce();
+  return { url, close, server };
+}
+// package.json
+var package_default = {
+  name: "plotleaf",
+  version: "0.1.0",
+  description: "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
+  type: "module",
+  license: "MIT",
+  bin: {
+    plotleaf: "./dist/cli.js"
+  },
+  engines: {
+    node: ">=22"
+  },
+  packageManager: "bun@1.4.4",
+  files: [
+    "dist/cli.js",
+    "dist/assets/base.js",
+    "dist/assets/charts.js",
+    "dist/assets/styles.css",
+    "dist/assets/notices.txt",
+    "schema/components.json",
+    "examples/storefront/*.md",
+    "examples/storefront/*.json",
+    "examples/adoption/*.md",
+    "examples/adoption/*.json",
+    "skills/plotleaf/SKILL.md",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.txt"
+  ],
+  scripts: {
+    format: "bun fmt src scripts tests playwright.config.ts package.json tsconfig.json tsconfig.browser.json tsconfig.dev.json bunfig.toml .github/workflows/ci.yml",
+    build: "bun scripts/build.ts",
+    typecheck: "bun node_modules/typescript/bin/tsc --noEmit -p tsconfig.json && bun node_modules/typescript/bin/tsc --noEmit -p tsconfig.browser.json && bun node_modules/typescript/bin/tsc --noEmit -p tsconfig.dev.json",
+    "typecheck:tsrs": "bun node_modules/tsrs/bin/tsrs --noEmit --fast false -p tsconfig.json && bun node_modules/tsrs/bin/tsrs --noEmit --fast false -p tsconfig.browser.json && bun node_modules/tsrs/bin/tsrs --noEmit --fast false -p tsconfig.dev.json",
+    test: "bun test",
+    "test:browser": "node node_modules/@playwright/test/cli.js test",
+    "test:consumer": "node tests/consumer/smoke.mjs",
+    check: "bun run typecheck && bun run build && bun run test && bun run test:consumer",
+    "audit:package": "node scripts/audit-package.mjs"
+  },
+  dependencies: {
+    chokidar: "6.0.0",
+    open: "11.0.4",
+    "rehype-sanitize": "6.0.0",
+    "rehype-stringify": "10.0.1",
+    "remark-directive": "4.0.0",
+    "remark-frontmatter": "5.0.0",
+    "remark-parse": "11.0.0",
+    "remark-rehype": "11.1.2",
+    unified: "11.0.5",
+    yaml: "2.9.1",
+    zod: "4.6.7"
+  },
+  devDependencies: {
+    "@playwright/test": "1.65.0",
+    "@types/bun": "1.4.4",
+    "@types/hast": "3.0.5",
+    "@types/mdast": "4.0.4",
+    "@types/node": "22.20.5",
+    echarts: "6.1.0",
+    tsrs: "0.23.0-ts7.1.0-beta",
+    typescript: "7.0.2"
+  },
+  keywords: [
+    "markdown",
+    "reports",
+    "data-visualization",
+    "charts",
+    "cli",
+    "agents"
+  ]
+};
+
+// src/cli.ts
+var help = `plotleaf — beautiful reports from Markdown and JSON
+
+Usage:
+  npx plotleaf <report.md>                    Open a live preview
+  npx plotleaf dev <report.md> [--no-open] [--port 3000]
+  npx plotleaf validate <report.md> [--json]   Validate syntax and local data
+  npx plotleaf build <report.md> [--out report.html]
+  npx plotleaf schema                         Print component specifications
+
+Options:
+  -h, --help      Show this help
+  -v, --version   Show the version
+
+Reports run without application setup. Exports work offline in a browser.
+`;
+async function assets() {
+  const base = new URL("./assets/", import.meta.url);
+  const [styles, runtime, charts, notices] = await Promise.all(["styles.css", "base.js", "charts.js", "notices.txt"].map((file) => readFile(new URL(file, base), "utf8")));
+  return {
+    styles,
+    base: runtime,
+    charts,
+    notices
+  };
+}
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    strict: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      "no-open": { type: "boolean" },
+      port: { type: "string" },
+      out: { type: "string", short: "o" }
+    }
+  });
+  if (values.version) {
+    console.log(package_default.version);
+    return;
+  }
+  if (values.help || !positionals.length) {
+    process.stdout.write(help);
+    return;
+  }
+  const first = positionals[0];
+  const known = ["dev", "validate", "build", "schema"];
+  const command = known.includes(first) ? first : "dev";
+  const filename = known.includes(first) ? positionals[1] : first;
+  const extras = positionals.slice(known.includes(first) ? 2 : 1);
+  if (command === "schema") {
+    if (positionals.length !== 1 || Object.keys(values).length)
+      throw new Error("schema does not accept a report or options. Use plotleaf schema.");
+    console.log(JSON.stringify(componentSpec(), null, 2));
+    return;
+  }
+  if (!filename || extras.length)
+    throw new Error("Specify exactly one report.md. Run plotleaf --help for usage.");
+  if (values.json && command !== "validate")
+    throw new Error("--json is only supported by validate.");
+  if (values.out && command !== "build")
+    throw new Error("--out is only supported by build.");
+  if ((values.port !== undefined || values["no-open"]) && command !== "dev")
+    throw new Error("--port and --no-open are only supported by dev/preview.");
+  let port;
+  if (values.port !== undefined) {
+    if (!/^\d+$/.test(values.port) || Number(values.port) > 65535)
+      throw new Error("--port must be an integer from 0 to 65535.");
+    port = Number(values.port);
+  }
+  const result = await compileReport(filename);
+  if (command === "validate") {
+    if (values.json)
+      console.log(JSON.stringify({ valid: Boolean(result.report), diagnostics: result.diagnostics }, null, 2));
+    else {
+      if (result.diagnostics.length)
+        console.error(humanDiagnostics(result.diagnostics));
+      if (result.report)
+        console.log(`Valid: ${displayPath(result.filename)}`);
+    }
+    if (!result.report)
+      process.exitCode = 1;
+    return;
+  }
+  if (command === "build") {
+    if (result.diagnostics.length)
+      console.error(humanDiagnostics(result.diagnostics));
+    if (!result.report) {
+      process.exitCode = 1;
+      return;
+    }
+    const html = renderHtml(result.report, await assets());
+    const defaultOutput = result.filename.slice(0, -path5.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)`);
+    return;
+  }
+  const preview = await startPreview(filename, await assets(), {
+    initial: result,
+    port,
+    openBrowser: !values["no-open"],
+    log: (message) => process.stderr.write(message + `
+`)
+  });
+  let closing = false;
+  const close = () => {
+    if (closing)
+      return;
+    closing = true;
+    preview.close().catch((error) => {
+      console.error(error instanceof Error ? error.message : error);
+      process.exitCode = 2;
+    });
+  };
+  process.once("SIGINT", close);
+  process.once("SIGTERM", close);
+}
+main().catch((error) => {
+  console.error(`plotleaf: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 2;
+});