plotleaf 0.4.1 → 0.5.0

package/dist/cli.js

@@ -65,9 +65,138 @@ function displayPath(filename) {
   return path.relative(process.cwd(), filename) || path.basename(filename);
 }
 
-// src/compiler/exploration-schema.ts
+// src/compiler/subtotal-schema.ts
 import * as z from "zod";
 
+// src/shared/limits.ts
+var limits = {
+  markdownBytes: 1024 ** 2,
+  jsonBytes: 10 * 1024 ** 2,
+  totalBytes: 25 * 1024 ** 2,
+  datasets: 64,
+  rows: 1e5,
+  chartRows: 1e4,
+  donutSlices: 8,
+  funnelStages: 20,
+  tableRows: 1000,
+  tableColumns: 40,
+  sparklinePoints: 64,
+  imageFiles: 64,
+  imageBytes: 1024 ** 2,
+  imageDimension: 4096,
+  imagePixels: 4000000
+};
+
+// src/compiler/subtotal-schema.ts
+var row = z.record(z.string(), z.unknown());
+var subtotalSchema = z.strictObject({
+  version: z.literal(1),
+  scope: z.string().trim().min(1).max(1000),
+  groups: z.array(z.strictObject({
+    id: z.string().trim().min(1).max(1000),
+    label: z.string().trim().min(1).max(1000),
+    rows: z.array(row).min(1).max(limits.tableRows),
+    subtotal: row
+  })).max(limits.tableRows)
+}).superRefine((bundle, context) => {
+  const ids = new Set;
+  let count = 0;
+  for (const [index, group] of bundle.groups.entries()) {
+    if (ids.has(group.id))
+      context.addIssue({
+        code: "custom",
+        path: ["groups", index, "id"],
+        message: "Group IDs must be unique."
+      });
+    ids.add(group.id);
+    count += group.rows.length + 1;
+  }
+  if (count > limits.tableRows)
+    context.addIssue({
+      code: "custom",
+      path: ["groups"],
+      message: `At most ${limits.tableRows} detail and subtotal rows are supported.`
+    });
+});
+
+// src/compiler/composition-schema.ts
+import * as z2 from "zod";
+var compositionLimits = {
+  depth: 16,
+  definitions: 64,
+  nodes: 512,
+  rows: 20000,
+  dataBytes: 8 * 1024 * 1024,
+  parameters: 32,
+  jsonDepth: 32,
+  jsonContainers: 1e4
+};
+var identifier = z2.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/);
+var literal3 = z2.union([
+  z2.string().max(1000),
+  z2.number().finite(),
+  z2.boolean()
+]);
+var parameter = z2.discriminatedUnion("type", [
+  z2.strictObject({
+    type: z2.literal("string"),
+    default: z2.string().max(1000).optional()
+  }),
+  z2.strictObject({
+    type: z2.literal("number"),
+    default: z2.number().finite().optional()
+  }),
+  z2.strictObject({
+    type: z2.literal("boolean"),
+    default: z2.boolean().optional()
+  })
+]);
+var value = z2.union([literal3, z2.strictObject({ prop: identifier })]);
+var node = z2.lazy(() => z2.strictObject({
+  name: identifier,
+  props: z2.record(identifier, value),
+  children: z2.array(node).max(compositionLimits.nodes).optional()
+}));
+var compositionSchema = z2.strictObject({
+  version: z2.literal(1),
+  props: z2.record(identifier, parameter),
+  components: z2.array(node).min(1).max(compositionLimits.nodes)
+}).superRefine((definition, context) => {
+  if (Object.hasOwn(definition.props, "src"))
+    context.addIssue({
+      code: "custom",
+      path: ["props", "src"],
+      message: "src is reserved for the composition definition path."
+    });
+  if (Object.keys(definition.props).length > compositionLimits.parameters)
+    context.addIssue({
+      code: "custom",
+      path: ["props"],
+      message: `At most ${compositionLimits.parameters} parameters are supported.`
+    });
+});
+function checkCompositionStructure(value) {
+  const pending = [{ value, depth: 0 }];
+  let containers = 0;
+  while (pending.length) {
+    const current = pending.pop();
+    if (current.value === null || typeof current.value !== "object")
+      continue;
+    if (current.depth > compositionLimits.jsonDepth || ++containers > compositionLimits.jsonContainers)
+      return "Composition JSON exceeds the nesting or container limit.";
+    for (const [key, child] of Object.entries(current.value)) {
+      if (["__proto__", "constructor", "prototype"].includes(key))
+        return `Reserved object key ${JSON.stringify(key)}.`;
+      if (child !== null && typeof child === "object")
+        pending.push({ value: child, depth: current.depth + 1 });
+    }
+  }
+  return;
+}
+
+// src/compiler/registry.ts
+import * as z4 from "zod";
+
 // src/shared/exploration.ts
 var valueKey = (value) => typeof value === "object" ? `${value.start}/${value.end}` : `${typeof value}:${String(value)}`;
 var explorationLimits = {
@@ -84,85 +213,56 @@ var explorationLimits = {
 };
 
 // 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) => {
+import * as z3 from "zod";
+var id = z3.string().regex(/^[a-z][a-z0-9_-]{0,47}$/).refine((value) => !["constructor", "prototype"].includes(value), "Reserved identifier.");
+var label = z3.string().min(1).max(160);
+var date = z3.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 range = z3.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({
+var explorationInputSchema = z3.discriminatedUnion("type", [
+  z3.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)
+    type: z3.enum(["select", "segmented", "text"]),
+    default: z3.string().max(120),
+    options: z3.array(z3.strictObject({ value: z3.string().max(120), label })).min(1).max(explorationLimits.options)
   }),
-  z.strictObject({
+  z3.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)
+    type: z3.literal("number"),
+    default: z3.number().finite(),
+    options: z3.array(z3.strictObject({ value: z3.number().finite(), label })).min(1).max(explorationLimits.options)
   }),
-  z.strictObject({
+  z3.strictObject({
     ...common,
-    type: z.literal("toggle"),
-    default: z.boolean()
+    type: z3.literal("toggle"),
+    default: z3.boolean()
   }),
-  z.strictObject({
+  z3.strictObject({
     ...common,
-    type: z.literal("date-range"),
+    type: z3.literal("date-range"),
     default: range,
-    options: z.array(z.strictObject({ value: range, label })).min(1).max(explorationLimits.options)
+    options: z3.array(z3.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({
+var explorationSchema = z3.strictObject({
+  inputs: z3.array(explorationInputSchema).min(1).max(explorationLimits.inputs),
+  views: z3.array(z3.strictObject({
     id,
     label,
-    when: z.record(id, z.union([
-      z.string().max(120),
-      z.number().finite(),
-      z.boolean(),
+    when: z3.record(id, z3.union([
+      z3.string().max(120),
+      z3.number().finite(),
+      z3.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({})
+    markdown: z3.string().min(1).max(1024 ** 2),
+    datasets: z3.record(z3.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*\.json$/), z3.array(z3.record(z3.string(), z3.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 = {
-  markdownBytes: 1024 ** 2,
-  jsonBytes: 10 * 1024 ** 2,
-  totalBytes: 25 * 1024 ** 2,
-  datasets: 64,
-  rows: 1e5,
-  chartRows: 1e4,
-  donutSlices: 8,
-  funnelStages: 20,
-  tableRows: 1000,
-  tableColumns: 40,
-  sparklinePoints: 64,
-  imageFiles: 64,
-  imageBytes: 1024 ** 2,
-  imageDimension: 4096,
-  imagePixels: 4000000
-};
-
 // src/shared/payload.ts
 var funnelStatuses = {
   "on-target": "On target",
@@ -172,8 +272,8 @@ var funnelStatuses = {
 };
 
 // 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 text = z4.string().min(1).max(1000);
+var format = z4.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,
@@ -181,20 +281,31 @@ var chart = {
   title: text,
   format: format.default("number")
 };
-var line = z2.strictObject({
+var line = z4.strictObject({
   ...chart,
-  xType: z2.enum(["category", "date", "number"]).default("category"),
-  target: z2.number().finite().optional(),
+  xType: z4.enum(["category", "date", "number"]).default("category"),
+  target: z4.number().finite().optional(),
   targetLabel: text.optional()
 });
 var registry = {
+  component: {
+    forms: ["leaf"],
+    children: [],
+    description: "A declarative composition from a local JSON definition.",
+    dataRules: {
+      schema: z4.toJSONSchema(compositionSchema),
+      limits: compositionLimits
+    },
+    schema: z4.object({ src: text }).catchall(z4.string().max(1000)),
+    example: '::component{src="./components/summary.json" label="Orders" value="1284"}'
+  },
   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 }),
+    schema: z4.strictObject({ data: text, title: text }),
     dataRules: {
-      schema: z2.toJSONSchema(explorationSchema),
+      schema: z4.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."
@@ -205,6 +316,7 @@ var registry = {
     forms: ["container"],
     children: [
       "metric",
+      "component",
       "line",
       "area",
       "bar",
@@ -214,8 +326,8 @@ var registry = {
       "callout"
     ],
     description: "A responsive row of one to four components.",
-    schema: z2.strictObject({
-      columns: z2.number().int().min(1).max(4).default(2)
+    schema: z4.strictObject({
+      columns: z4.number().int().min(1).max(4).default(2)
     }),
     example: `:::grid{columns="4"}
 ::metric{label="Teams" value="1492"}
@@ -225,13 +337,13 @@ var registry = {
     forms: ["leaf"],
     children: [],
     description: "A prepared numeric value with optional comparison, direction and sentiment.",
-    schema: z2.strictObject({
+    schema: z4.strictObject({
       label: text,
-      value: z2.number().finite(),
+      value: z4.number().finite(),
       format: format.default("number"),
       comparison: text.optional(),
-      direction: z2.enum(["up", "down", "flat"]).optional(),
-      sentiment: z2.enum(["positive", "negative", "neutral"]).default("neutral")
+      direction: z4.enum(["up", "down", "flat"]).optional(),
+      sentiment: z4.enum(["positive", "negative", "neutral"]).default("neutral")
     }),
     example: '::metric{label="Conversion" value="0.103" format="percent"}'
   },
@@ -253,14 +365,14 @@ var registry = {
     forms: ["leaf"],
     children: [],
     description: "An interactive category bar chart with a zero baseline.",
-    schema: z2.strictObject(chart),
+    schema: z4.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({
+    schema: z4.strictObject({
       data: text,
       category: text,
       value: text,
@@ -278,7 +390,7 @@ var registry = {
     forms: ["leaf"],
     children: [],
     description: "Ordered stage/progress rows with prepared values, denominators, shares and optional explicit status. Works without JavaScript.",
-    schema: z2.strictObject({
+    schema: z4.strictObject({
       data: text,
       stage: text,
       value: text,
@@ -302,7 +414,15 @@ var registry = {
     forms: ["leaf", "container"],
     children: ["column"],
     description: "A semantic sortable table, with inferred or explicitly formatted columns.",
-    schema: z2.strictObject({ data: text, title: text.optional() }),
+    dataRules: {
+      grouped: z4.toJSONSchema(subtotalSchema),
+      sorting: "Details sort within groups; prepared subtotals stay at the end of their group. Scope is supplied explicitly."
+    },
+    schema: z4.strictObject({
+      data: text,
+      title: text.optional(),
+      prepared: z4.enum(["grouped"]).optional()
+    }),
     example: `:::table{data="./plans.json" title="By plan"}
 ::column{field="plan" label="Plan"}
 ::column{field="change" label="Δ QoQ" format="percent" sign="always"}
@@ -312,15 +432,15 @@ var registry = {
     forms: ["leaf"],
     children: [],
     description: "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
-    schema: z2.strictObject({
+    schema: z4.strictObject({
       field: text,
       label: text.optional(),
-      kind: z2.enum(["scalar", "image", "sparkline"]).optional(),
+      kind: z4.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")
+      sign: z4.enum(["auto", "always"]).default("auto"),
+      semantics: z4.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: {
@@ -333,8 +453,8 @@ var registry = {
     forms: ["container"],
     children: ["markdown"],
     description: "A contextual note or warning containing ordinary Markdown.",
-    schema: z2.strictObject({
-      tone: z2.enum(["note", "warning"]).default("note"),
+    schema: z4.strictObject({
+      tone: z4.enum(["note", "warning"]).default("note"),
       title: text.optional()
     }),
     example: `:::callout{title="Coverage"}
@@ -363,7 +483,7 @@ function componentSpec() {
         description: entry.description,
         forms: entry.forms,
         children: entry.children,
-        props: z2.toJSONSchema(entry.schema),
+        props: z4.toJSONSchema(entry.schema),
         example: entry.example,
         ..."dataRules" in entry ? { dataRules: entry.dataRules } : {}
       }
@@ -433,11 +553,187 @@ function decodeProps(name, attributes) {
   return { props, errors };
 }
 
+// src/compiler/sources.ts
+class LocalFileError extends Error {
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
+
+// src/compiler/composition.ts
+var componentProperties = componentSpec().components;
+var compositionState = () => ({
+  definitions: new Map,
+  nodes: 0,
+  rows: 0,
+  dataBytes: 0
+});
+function relativeTo(reference, base) {
+  if (!base)
+    return reference;
+  if (/^(?:\/|[A-Za-z][A-Za-z\d+.-]*:)/.test(reference) || reference.includes("\\"))
+    return reference;
+  return `${base}/${reference}`;
+}
+function parentOf(reference) {
+  const index = reference.lastIndexOf("/");
+  return index < 0 ? "" : reference.slice(0, index);
+}
+async function expandComposition(block, files, diagnostics, state, parent, stack = [], origins = {}) {
+  const fail = (code, message) => {
+    diagnostics.add(code, `${block.props.src}: ${message}`, block.position, "Correct the composition definition and its declared literal parameters.");
+    return [];
+  };
+  let filename;
+  try {
+    filename = await files.resolve(block.props.src, [".json"]);
+  } catch (error) {
+    return fail(error instanceof LocalFileError && error.kind === "path" ? "E_COMPONENT_PATH" : "E_COMPONENT_READ", error instanceof Error ? error.message : "Cannot resolve definition.");
+  }
+  if (stack.includes(filename))
+    return fail("E_COMPONENT_CYCLE", "Composition definitions cannot contain cycles.");
+  if (stack.length >= compositionLimits.depth)
+    return fail("E_COMPONENT_LIMIT", `Composition nesting exceeds ${compositionLimits.depth}.`);
+  let definition = state.definitions.get(filename);
+  if (!definition) {
+    if (state.definitions.size >= compositionLimits.definitions)
+      return fail("E_COMPONENT_LIMIT", `At most ${compositionLimits.definitions} definitions are supported.`);
+    let raw;
+    try {
+      raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await files.read(filename, limits.jsonBytes)));
+    } catch (error) {
+      return fail("E_COMPONENT_READ", error instanceof Error ? error.message : "Cannot read definition JSON.");
+    }
+    const structural = checkCompositionStructure(raw);
+    if (structural)
+      return fail("E_COMPONENT_SCHEMA", structural);
+    const parsed = compositionSchema.safeParse(raw);
+    if (!parsed.success)
+      return fail("E_COMPONENT_SCHEMA", parsed.error.issues.slice(0, 8).map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+    definition = parsed.data;
+    state.definitions.set(filename, definition);
+  }
+  const supplied = Object.entries(block.props).filter(([name]) => name !== "src");
+  for (const [name] of supplied)
+    if (!Object.hasOwn(definition.props, name))
+      return fail("E_COMPONENT_PROP", `Unknown parameter ${JSON.stringify(name)}.`);
+  const base = parentOf(block.props.src);
+  const values = Object.create(null);
+  const valueOrigins = Object.create(null);
+  for (const [name, spec] of Object.entries(definition.props)) {
+    const input = block.props[name];
+    valueOrigins[name] = input === undefined ? base : origins[name] ?? "";
+    if (input === undefined) {
+      if (spec.default === undefined)
+        return fail("E_COMPONENT_PROP", `Missing required parameter ${JSON.stringify(name)}.`);
+      values[name] = spec.default;
+    } else if (spec.type === "number") {
+      if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(input) || !Number.isFinite(Number(input)))
+        return fail("E_COMPONENT_PROP", `${name} must be a finite number.`);
+      values[name] = Number(input);
+    } else if (spec.type === "boolean") {
+      if (input !== "true" && input !== "false")
+        return fail("E_COMPONENT_PROP", `${name} must be true or false.`);
+      values[name] = input === "true";
+    } else
+      values[name] = input;
+  }
+  const build = async (nodes, context, depth) => {
+    const out = [];
+    if (depth > compositionLimits.depth)
+      return fail("E_COMPONENT_LIMIT", "Component nesting exceeds the composition limit.");
+    for (const node of nodes) {
+      if (++state.nodes > compositionLimits.nodes)
+        return fail("E_COMPONENT_LIMIT", `Expanded components exceed ${compositionLimits.nodes}.`);
+      if (!Object.hasOwn(registry, node.name)) {
+        fail("E_COMPONENT_UNKNOWN", `Unknown built-in ${JSON.stringify(node.name)}.`);
+        continue;
+      }
+      const name = node.name;
+      const entry = registry[name];
+      const allowed = context === "root" ? name !== "column" : registry[context]?.children?.includes(name);
+      if (!allowed) {
+        fail("E_COMPONENT_CONTEXT", `${name} is not allowed inside ${context}.`);
+        continue;
+      }
+      const attrs = Object.create(null);
+      const childOrigins = Object.create(null);
+      const properties = componentProperties[name].props.properties ?? {};
+      let bad = false;
+      for (const [key, value] of Object.entries(node.props)) {
+        const dynamic = typeof value === "object";
+        if (dynamic && !Object.hasOwn(values, value.prop)) {
+          fail("E_COMPONENT_PROP", `Unknown parameter reference ${JSON.stringify(value.prop)}.`);
+          bad = true;
+          continue;
+        }
+        let resolved = dynamic ? values[value.prop] : value;
+        const property = properties[key];
+        const expected = property?.type === "integer" ? "number" : property?.type;
+        if (name !== "component" && expected && expected !== typeof resolved) {
+          fail("E_COMPONENT_PROP", `${name}.${key} requires ${expected}; received ${typeof resolved}.`);
+          bad = true;
+          continue;
+        }
+        if (typeof resolved === "string" && (key === "data" && [
+          "line",
+          "area",
+          "bar",
+          "donut",
+          "funnel",
+          "table",
+          "explore"
+        ].includes(name) || key === "src" && name === "component"))
+          resolved = relativeTo(resolved, dynamic ? valueOrigins[value.prop] : base);
+        attrs[key] = String(resolved);
+        if (name === "component" && key !== "src")
+          childOrigins[key] = dynamic ? valueOrigins[value.prop] : base;
+      }
+      if (bad)
+        continue;
+      const decoded = decodeProps(name, attrs);
+      if (decoded.errors.length) {
+        fail("E_COMPONENT_PROP", `${name}: ${decoded.errors.join("; ")}`);
+        continue;
+      }
+      const children = node.children ?? [];
+      if (children.length && !entry.forms.includes("container")) {
+        fail("E_COMPONENT_CONTEXT", `${name} cannot contain children.`);
+        continue;
+      }
+      const built = {
+        type: "component",
+        name,
+        props: decoded.props,
+        children: [],
+        position: block.position,
+        compositionOrigin: true
+      };
+      if (name === "component") {
+        out.push(...await expandComposition(built, files, diagnostics, state, context, [...stack, filename], childOrigins));
+      } else {
+        built.children = await build(children, name, depth + 1);
+        out.push(built);
+      }
+    }
+    return out;
+  };
+  return build(definition.components, parent, 0);
+}
+
 // 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 z5 from "zod";
 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()
+var metadataSchema = z5.strictObject({
+  title: z5.string().min(1).max(500).optional(),
+  description: z5.string().max(2000).optional()
 });
 function textOf(node) {
   return node.value ?? node.children?.map(textOf).join("") ?? "";
@@ -602,15 +898,6 @@ function parseReport(source, fallbackTitle, diagnostics) {
   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,
@@ -814,12 +1101,16 @@ class DataResolver {
   files;
   images;
   expansion;
+  compositions;
+  inExploration;
   cache;
-  constructor(diagnostics, files, images, expansion = expansionBudget(), cache = new Map) {
+  constructor(diagnostics, files, images, expansion = expansionBudget(), compositions = compositionState(), inExploration = false, cache = new Map) {
     this.diagnostics = diagnostics;
     this.files = files;
     this.images = images;
     this.expansion = expansion;
+    this.compositions = compositions;
+    this.inExploration = inExploration;
     this.cache = cache;
   }
   async load(reference, block) {
@@ -849,8 +1140,29 @@ class DataResolver {
       } catch {
         return fail("E_DATA_JSON", "Invalid JSON.", "Use a JSON array of records, without comments or trailing commas.");
       }
+      let grouped;
+      if (block.name === "table" && block.props.prepared === "grouped") {
+        const structural = checkCompositionStructure(parsed);
+        if (structural)
+          return fail("E_TABLE_GROUPS", structural);
+        const result = subtotalSchema.safeParse(parsed);
+        if (!result.success)
+          return fail("E_TABLE_GROUPS", result.error.issues.slice(0, 8).map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+        grouped = {
+          scope: result.data.scope,
+          groups: result.data.groups.map((group) => ({
+            id: group.id,
+            label: group.label,
+            size: group.rows.length
+          }))
+        };
+        parsed = result.data.groups.flatMap((group) => [
+          ...group.rows,
+          group.subtotal
+        ]);
+      }
       if (!Array.isArray(parsed))
-        return fail("E_DATA_SHAPE", "Expected an array of flat JSON records.");
+        return fail("E_DATA_SHAPE", "Expected an array of flat JSON records, or declare prepared=grouped for a subtotal bundle.");
       if (parsed.length > limits.rows)
         return fail("E_DATA_LIMIT", `Dataset exceeds ${limits.rows.toLocaleString("en-GB")} rows.`, "Prepare a smaller dataset before rendering.");
       const arrays = new Map;
@@ -871,21 +1183,44 @@ class DataResolver {
             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; use an explicit sparkline column for bounded numeric/null sequences.");
         }
       }
-      dataset = { rows: parsed, arrays };
+      dataset = {
+        rows: parsed,
+        arrays,
+        ...grouped ? { grouped } : {}
+      };
       this.cache.set(canonical, dataset);
     }
+    if (Boolean(dataset.grouped) !== (block.name === "table" && block.props.prepared === "grouped"))
+      return fail("E_DATA_SHAPE", "Grouped subtotal bundles require prepared=grouped and cannot be used as ordinary datasets.");
+    if (block.name === "table" && dataset.grouped)
+      block.tableGroups = dataset.grouped;
     const declared = new Set(block.name === "table" ? block.children.flatMap((child) => child.type === "component" && child.name === "column" && child.props.kind === "sparkline" ? [child.props.field] : []) : []);
     for (const [field, index] of dataset.arrays)
       if (!declared.has(field))
         return fail("E_DATA_SHAPE", `Row ${index + 1}, field ${JSON.stringify(field)} is a sequence without an explicit sparkline column.`, 'Use a table column with kind="sparkline" for that field. Charts and scalar tables require flat scalar datasets.');
     return dataset.rows;
   }
-  async resolve(blocks) {
-    for (const block of blocks) {
+  async resolve(blocks, parent = "root") {
+    for (let index = 0;index < blocks.length; index++) {
+      let block = blocks[index];
+      if (block.type === "component" && block.name === "component") {
+        const expanded = await expandComposition(block, this.files, this.diagnostics, this.compositions, parent);
+        blocks.splice(index, 1, ...expanded);
+        if (!expanded.length) {
+          index--;
+          continue;
+        }
+        index--;
+        continue;
+      }
       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);
+        if (this.inExploration) {
+          this.diagnostics.add("E_EXPLORE_SCHEMA", "Nested explorations are unsupported, including inside compositions.", block.position);
+          continue;
+        }
+        await resolveExploration(block, this.files, this.diagnostics, (children, files, diagnostics) => new DataResolver(diagnostics, files, this.images, this.expansion, this.compositions, true, 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") {
@@ -901,7 +1236,15 @@ class DataResolver {
             this.resolveChart(block, rows);
         }
       }
-      await this.resolve(block.children);
+      if (block.compositionOrigin && block.rows) {
+        this.compositions.rows += block.rows.length;
+        this.compositions.dataBytes += new TextEncoder().encode(JSON.stringify(block.rows)).length;
+        if (this.compositions.rows > compositionLimits.rows || this.compositions.dataBytes > compositionLimits.dataBytes) {
+          this.diagnostics.add("E_COMPONENT_LIMIT", "Expanded composition data exceeds its row or byte budget.", block.position, "Prepare a smaller dataset or reuse fewer components.");
+          return;
+        }
+      }
+      await this.resolve(block.children, block.name);
     }
   }
   field(rows, name, block) {
@@ -1686,7 +2029,8 @@ var serializer = unified2().use(rehypeSanitize, {
     ul: ["className", "role"],
     ol: ["start", "className", "role"],
     li: ["className", "dataStatus"],
-    th: ["scope", "ariaSort", "className"],
+    th: ["scope", "ariaSort", "className", "colSpan"],
+    tr: ["className", "dataPlotleafGroupHeader", "dataPlotleafSubtotal"],
     td: ["className", "dataRaw"]
   }
 }).use(rehypeStringify);
@@ -1700,11 +2044,14 @@ function slugOf(text) {
 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) {
+function table(rows, columns, title, id, sortable = true, groups) {
   const scales = columns.map((column) => column.kind === "sparkline" ? columnScale(rows, column.field) : undefined);
   const canSort = columns.map((column) => sortable && (!column.kind || column.kind === "scalar" || Boolean(column.sortBy)));
   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 caption = h("caption", {}, [
+    t(title),
+    ...groups ? [h("span", { className: ["table-scope"] }, [t(groups.scope)])] : []
+  ]);
   const headers = columns.map((column, index) => {
     const name = column.label ?? label2(column.field);
     const content = canSort[index] ? h("button", {
@@ -1738,12 +2085,27 @@ function table(rows, columns, title, id, sortable = true) {
     });
     return h("tr", {}, cells);
   });
-  const body = h("tbody", {}, tableRows);
+  let offset = 0;
+  const bodies = groups ? groups.groups.map((group) => {
+    const entries = tableRows.slice(offset, offset + group.size + 1);
+    offset += group.size + 1;
+    const subtotal = entries.at(-1);
+    subtotal.properties.dataPlotleafSubtotal = "";
+    subtotal.properties.className = ["table-subtotal"];
+    return h("tbody", {}, [
+      h("tr", { dataPlotleafGroupHeader: "", className: ["table-group"] }, [
+        h("th", { scope: "rowgroup", colSpan: columns.length }, [
+          t(group.label)
+        ])
+      ]),
+      ...entries
+    ]);
+  }) : [h("tbody", {}, tableRows)];
   return h("div", { className: ["table-scroll"] }, [
     h("table", { id, ...sortable ? { dataPlotleafTable: "" } : {} }, [
       caption,
       head,
-      body
+      ...bodies
     ])
   ]);
 }
@@ -1798,6 +2160,8 @@ function renderContent(report) {
       }
       const id = `plotleaf-component-${String(++sequence).padStart(4, "0")}`;
       switch (block.name) {
+        case "component":
+          return [];
         case "explore":
           return exploration(block, id, render, payload.explorations ??= []);
         case "grid":
@@ -1850,7 +2214,7 @@ function renderContent(report) {
           ];
         case "table":
           return [
-            table(block.rows ?? [], block.columns ?? [], block.props.title ?? "Data", id),
+            table(block.rows ?? [], block.columns ?? [], block.props.title ?? "Data", id, true, block.tableGroups),
             ...!block.rows?.length ? [
               h("p", { className: ["empty-state"] }, [
                 t("No data to display.")
@@ -2335,7 +2699,7 @@ data: ${revision}
 // package.json
 var package_default = {
   name: "plotleaf",
-  version: "0.4.1",
+  version: "0.5.0",
   description: "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   type: "module",
   license: "MIT",
@@ -2362,6 +2726,8 @@ var package_default = {
     "dist/assets/notices.txt",
     "schema/components.json",
     "examples/report.md",
+    "examples/m6/*.md",
+    "examples/m6/*.json",
     "examples/interactions/*.md",
     "examples/interactions/*.json",
     "examples/storefront/*.md",