plotleaf 0.2.0 → 0.3.1

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path5 from "node:path";
+import path6 from "node:path";
 import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
 // src/compiler/compile.ts
-import path3 from "node:path";
+import path4 from "node:path";
 import { realpath as realpath2 } from "node:fs/promises";
 
 // src/compiler/diagnostics.ts
@@ -62,18 +62,10 @@ ${d.hint}` : ""}`).join(`
 `);
 }
 
-// src/compiler/data.ts
+// src/compiler/files.ts
 import path2 from "node:path";
 import { open, realpath, stat } from "node:fs/promises";
 
-// src/shared/payload.ts
-var funnelStatuses = {
-  "on-target": "On target",
-  "below-target": "Below target",
-  "at-risk": "At risk",
-  neutral: "Neutral"
-};
-
 // src/shared/limits.ts
 var limits = {
   markdownBytes: 1024 ** 2,
@@ -85,24 +77,35 @@ var limits = {
   donutSlices: 8,
   funnelStages: 20,
   tableRows: 1000,
-  tableColumns: 40
+  tableColumns: 40,
+  sparklinePoints: 64,
+  imageFiles: 64,
+  imageBytes: 1024 ** 2,
+  imageDimension: 4096,
+  imagePixels: 4000000
 };
 
-// src/compiler/data.ts
-var reserved = new Set(["__proto__", "constructor", "prototype"]);
+// src/compiler/files.ts
+class LocalFileError extends Error {
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+}
 function contained(root, filename) {
   const relative = path2.relative(root, filename);
   return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
 }
-async function readBounded(filename, maximum) {
+async function readBytesBounded(filename, maximum) {
   if (!(await stat(filename)).isFile())
     throw new Error("Expected a regular file.");
   const file = await open(filename, "r");
   try {
-    const stat = await file.stat();
-    if (!stat.isFile())
+    const info = await file.stat();
+    if (!info.isFile())
       throw new Error("Expected a regular file.");
-    if (stat.size > maximum)
+    if (info.size > maximum)
       throw new Error(`File exceeds the ${Math.floor(maximum / 1024)} KiB size limit.`);
     const chunks = [];
     let bytes = 0;
@@ -116,14 +119,158 @@ async function readBounded(filename, maximum) {
     }
     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
-    };
+    return Buffer.concat(chunks, bytes);
   } finally {
     await file.close();
   }
 }
+async function readBounded(filename, maximum) {
+  const bytes = await readBytesBounded(filename, maximum);
+  return {
+    text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    bytes: bytes.length
+  };
+}
+
+class ReportFiles {
+  root;
+  dependencies;
+  usedBytes;
+  constructor(root, dependencies, usedBytes) {
+    this.root = root;
+    this.dependencies = dependencies;
+    this.usedBytes = usedBytes;
+  }
+  async resolve(reference, extensions) {
+    const fail = (message) => {
+      throw new LocalFileError("path", message);
+    };
+    if (path2.isAbsolute(reference) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(reference) || reference.includes("\\") || /%[\da-f]{2}/i.test(reference) || reference.includes("\x00"))
+      fail(`Use a plain relative local ${extensions.join("/")} path.`);
+    const candidate = path2.resolve(this.root, reference);
+    const hidden = (filename) => path2.relative(this.root, filename).split(path2.sep).some((part) => part.startsWith("."));
+    if (!contained(this.root, candidate))
+      fail("Reference escapes the report directory.");
+    if (hidden(candidate))
+      fail("Hidden files and directories are not allowed.");
+    if (!extensions.includes(path2.extname(candidate).toLowerCase()))
+      fail(`Use a ${extensions.join("/")} file.`);
+    this.dependencies.add(candidate);
+    let canonical;
+    try {
+      canonical = await realpath(candidate);
+    } catch {
+      throw new LocalFileError("read", "Cannot read the referenced file. Create it or correct the reference.");
+    }
+    if (!contained(this.root, canonical) || hidden(canonical))
+      fail("The resolved file or symlink escapes the permitted report files.");
+    if (!extensions.includes(path2.extname(canonical).toLowerCase()))
+      fail(`The resolved file must also have a ${extensions.join("/")} extension.`);
+    this.dependencies.add(canonical);
+    return canonical;
+  }
+  async read(filename, maximum) {
+    const bytes = await readBytesBounded(filename, Math.min(maximum, limits.totalBytes - this.usedBytes));
+    this.usedBytes += bytes.length;
+    return bytes;
+  }
+}
+
+// src/compiler/images.ts
+import { createHash } from "node:crypto";
+import path3 from "node:path";
+import { imageSize } from "image-size";
+function formatOf(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    let offset = 8;
+    let data = false;
+    while (offset + 12 <= bytes.length) {
+      const size = bytes.readUInt32BE(offset);
+      const type = bytes.toString("ascii", offset + 4, offset + 8);
+      if (offset + size + 12 > bytes.length)
+        break;
+      if (offset === 8 && (type !== "IHDR" || size !== 13))
+        break;
+      if (type === "acTL")
+        throw new Error("Animated PNG is not supported; provide a static image.");
+      if (type === "IDAT" && size > 0)
+        data = true;
+      offset += size + 12;
+      if (type === "IEND") {
+        if (data && size === 0 && offset === bytes.length)
+          return "png";
+        break;
+      }
+    }
+    throw new Error("Incomplete or invalid PNG container.");
+  }
+  if (bytes.length >= 4 && bytes.readUInt16BE(0) === 65496 && bytes.readUInt16BE(bytes.length - 2) === 65497)
+    return "jpg";
+  throw new Error("Expected a static PNG or JPEG image with a matching file extension.");
+}
+
+class ImageResolver {
+  files;
+  attempted = new Set;
+  filesRead = new Map;
+  embedded = new Map;
+  constructor(files) {
+    this.files = files;
+  }
+  async load(reference) {
+    const requested = path3.resolve(this.files.root, reference);
+    if (!this.attempted.has(requested) && this.attempted.size >= limits.imageFiles)
+      throw new Error(`At most ${limits.imageFiles} local image references are supported.`);
+    this.attempted.add(requested);
+    const canonical = await this.files.resolve(reference, [
+      ".png",
+      ".jpg",
+      ".jpeg"
+    ]);
+    const cached = this.filesRead.get(canonical);
+    if (cached) {
+      if (path3.extname(reference).toLowerCase() === ".png" !== (cached.mime === "image/png"))
+        throw new Error("Image signature does not match its file extension.");
+      return cached;
+    }
+    if (this.filesRead.size >= limits.imageFiles)
+      throw new Error(`At most ${limits.imageFiles} local image files are supported.`);
+    const bytes = await this.files.read(canonical, limits.imageBytes);
+    const format = formatOf(bytes);
+    const expected = (name) => path3.extname(name).toLowerCase() === ".png" ? "png" : "jpg";
+    if (format !== expected(reference) || format !== expected(canonical))
+      throw new Error("Image signature does not match its file extension.");
+    let size;
+    try {
+      size = imageSize(bytes);
+    } catch {
+      throw new Error("Unsupported or damaged PNG/JPEG header.");
+    }
+    if (size.type !== format || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1)
+      throw new Error("Image must have valid positive raster dimensions.");
+    if (size.width > limits.imageDimension || size.height > limits.imageDimension || size.width * size.height > limits.imagePixels)
+      throw new Error(`Image exceeds ${limits.imageDimension} pixels per side or ${limits.imagePixels.toLocaleString("en-GB")} pixels in total. Resize the prepared asset.`);
+    const id = `plotleaf-image-${createHash("sha256").update(bytes).digest("hex")}`;
+    const image = this.embedded.get(id) ?? {
+      id,
+      mime: format === "png" ? "image/png" : "image/jpeg",
+      base64: bytes.toString("base64")
+    };
+    this.filesRead.set(canonical, image);
+    this.embedded.set(id, image);
+    return image;
+  }
+}
+// src/shared/payload.ts
+var funnelStatuses = {
+  "on-target": "On target",
+  "below-target": "Below target",
+  "at-risk": "At risk",
+  neutral: "Neutral"
+};
+
+// src/compiler/data.ts
+var reserved = new Set(["__proto__", "constructor", "prototype"]);
 function parseDate(value) {
   const date = value.slice(0, 10);
   if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
@@ -143,75 +290,73 @@ class DataResolver {
   root;
   diagnostics;
   dependencies;
-  totalBytes;
   cache = new Map;
+  files;
+  images;
   constructor(root, diagnostics, dependencies, totalBytes = 0) {
     this.root = root;
     this.diagnostics = diagnostics;
     this.dependencies = dependencies;
-    this.totalBytes = totalBytes;
+    this.files = new ReportFiles(root, dependencies, totalBytes);
+    this.images = new ImageResolver(this.files);
   }
   async load(reference, block) {
     const fail = (code, message, hint) => {
       this.diagnostics.add(code, `${reference}: ${message}`, block.position, hint);
       return;
     };
-    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));
+      canonical = await this.files.resolve(reference, [".json"]);
     } catch (error) {
-      return fail("E_DATA_READ", error instanceof Error ? error.message : "Could not read data.");
+      return fail(error instanceof LocalFileError && error.kind === "path" ? "E_DATA_PATH" : "E_DATA_READ", error instanceof Error ? error.message : "Cannot resolve the dataset.", "Place prepared JSON within the report directory and correct the data property.");
     }
-    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.");
+    let dataset = this.cache.get(canonical);
+    if (!dataset) {
+      if (this.cache.size >= limits.datasets)
+        return fail("E_DATA_LIMIT", `At most ${limits.datasets} datasets are supported.`);
+      let text;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(await this.files.read(canonical, limits.jsonBytes));
+      } catch (error) {
+        return fail("E_DATA_READ", error instanceof Error ? error.message : "Could not read data.");
       }
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return fail("E_DATA_JSON", "Invalid JSON.", "Use a JSON array of records, without comments or trailing commas.");
+      }
+      if (!Array.isArray(parsed))
+        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 dataset before rendering.");
+      const arrays = new Map;
+      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 (Array.isArray(value)) {
+            if (value.length > limits.sparklinePoints)
+              return fail("E_DATA_LIMIT", `Row ${index + 1}, field ${JSON.stringify(key)} exceeds ${limits.sparklinePoints} sparkline points.`, "Prepare a bounded sequence; values are never truncated.");
+            if (value.some((item) => item !== null && !(typeof item === "number" && Number.isFinite(item))))
+              return fail("E_DATA_SHAPE", `Row ${index + 1}, field ${JSON.stringify(key)} must contain only finite numbers or null gaps.`, "Only declared sparkline columns support sequences; nested objects and sequences are invalid.");
+            if (!arrays.has(key))
+              arrays.set(key, index);
+          } else 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; use an explicit sparkline column for bounded numeric/null sequences.");
+        }
+      }
+      dataset = { rows: parsed, arrays };
+      this.cache.set(canonical, dataset);
     }
-    const rows = parsed;
-    this.cache.set(canonical, rows);
-    return rows;
+    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) {
@@ -223,7 +368,7 @@ class DataResolver {
           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);
+            await this.resolveTable(block, rows);
           else if (block.name === "donut" || block.name === "funnel")
             this.resolveParts(block, rows);
           else
@@ -342,7 +487,7 @@ class DataResolver {
     }
     block.rows = rows.map((row) => Object.fromEntries(fields.map((field) => [field, row[field]])));
   }
-  resolveTable(block, rows) {
+  async 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;
@@ -358,24 +503,101 @@ class DataResolver {
       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)
+    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);
+      return;
+    }
     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;
       }
+    const prepared = rows.map(() => ({}));
     for (const column of columns) {
-      if (!this.field(rows, column.field, block))
+      const origin = explicit.find((child) => child.props.field === column.field) ?? block;
+      const fields = [
+        column.field,
+        ...column.alt ? [column.alt] : [],
+        ...column.sortBy ? [column.sortBy] : []
+      ];
+      if (fields.some((field) => !this.field(rows, field, origin)))
         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);
+      const fail = (code, row, message, hint) => this.diagnostics.add(code, `${block.props.data}, row ${row + 1}, field ${JSON.stringify(column.field)}: ${message}`, origin.position, hint);
+      const kind = column.kind ?? "scalar";
+      if (kind === "scalar") {
+        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.`, origin.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)}.`, origin.position);
+      }
+      let sortType;
+      for (const [index, row] of rows.entries()) {
+        const value = row[column.field];
+        const sort = column.sortBy ? row[column.sortBy] : undefined;
+        if (column.sortBy && (Array.isArray(sort) || sort === undefined)) {
+          fail("E_TABLE_SORT", index, "sortBy must name a scalar field.");
+          continue;
+        }
+        if (sort !== undefined && sort !== null) {
+          if (sortType && sortType !== typeof sort) {
+            fail("E_TABLE_SORT", index, "sortBy values must have consistent non-null types.");
+            continue;
+          }
+          sortType = typeof sort;
+        }
+        if (kind === "scalar") {
+          prepared[index][column.field] = value;
+          continue;
+        }
+        let rich;
+        if (kind === "sparkline") {
+          if (value !== null && !Array.isArray(value)) {
+            fail("E_DATA_TYPE", index, "Sparkline values must be a bounded numeric/null array or null.");
+            continue;
+          }
+          rich = {
+            kind: "sparkline",
+            values: value ?? [],
+            ...column.sortBy ? { sort } : {}
+          };
+        } else {
+          const alt = row[column.alt];
+          if (value !== null && (typeof alt !== "string" || !alt.trim() || alt.length > 1000) || value === null && alt !== null && typeof alt !== "string") {
+            fail("E_TABLE_IMAGE", index, "alt must name a nonblank string of at most 1000 characters for each image.");
+            continue;
+          }
+          if (value === null) {
+            prepared[index][column.field] = {
+              kind: "image",
+              imageId: null,
+              alt: "",
+              ...column.sortBy ? { sort } : {}
+            };
+            continue;
+          }
+          if (typeof value !== "string" || !value.trim()) {
+            fail("E_TABLE_IMAGE", index, "Image values must be a plain local PNG/JPEG path or null.");
+            continue;
+          }
+          try {
+            const image = await this.images.load(value);
+            rich = {
+              kind: "image",
+              imageId: image.id,
+              alt,
+              ...column.sortBy ? { sort } : {}
+            };
+          } catch (error) {
+            fail(error instanceof LocalFileError ? error.kind === "path" ? "E_ASSET_PATH" : "E_ASSET_READ" : "E_ASSET_IMAGE", index, `${value}: ${error instanceof Error ? error.message : "Cannot read image."}`, "Use a bounded static PNG/JPEG inside the report directory, with a matching extension.");
+            continue;
+          }
+        }
+        prepared[index][column.field] = rich;
+      }
     }
     block.columns = columns;
-    block.rows = rows.map((row) => Object.fromEntries(columns.map((column) => [column.field, row[column.field]])));
+    block.rows = prepared;
   }
 }
 
@@ -515,15 +737,23 @@ var registry = {
   column: {
     forms: ["leaf"],
     children: [],
-    description: "An explicit field, label and format inside a table.",
+    description: "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
     schema: z.strictObject({
       field: text,
       label: text.optional(),
+      kind: z.enum(["scalar", "image", "sparkline"]).optional(),
+      alt: text.optional(),
+      sortBy: text.optional(),
       format: format.optional(),
       sign: z.enum(["auto", "always"]).default("auto"),
       semantics: z.enum(["neutral", "higher-is-better", "lower-is-better"]).default("neutral")
     }),
-    example: '::column{field="change" label="Δ QoQ" format="percent" sign="always" semantics="higher-is-better"}'
+    example: '::column{field="change" label="Δ QoQ" format="percent" sign="always" semantics="higher-is-better"}',
+    dataRules: {
+      image: "Local static PNG/JPEG path or null. alt names a nonblank string field for each image. Fixed 64 × 48 display box; deduplicated and embedded offline. Paths resolve from the report directory.",
+      sparkline: "Only explicitly declared sparkline fields may contain arrays: at most 64 finite numbers/nulls, in sample order. Nulls are gaps. Shared observed y scale per column; no aggregation or resampling.",
+      sortBy: "Optional scalar field for image/sparkline sorting. Without it a rich column has a plain header. Scalar columns sort their own raw values. Sort keys are readable in the export."
+    }
   },
   callout: {
     forms: ["container"],
@@ -545,7 +775,7 @@ function componentSpec() {
     attributes: "Literal strings decoded according to each property schema. No JavaScript expressions.",
     limits,
     data: {
-      shape: "array of flat JSON records",
+      shape: "array of flat JSON records; explicit table sparkline columns permit bounded numeric/null arrays only in their declared fields",
       resolution: "relative to the report directory; local .json files only",
       percent: "ratios: 0.12 displays as 12%",
       percentagePoints: "point values: 0.8 displays as 0.8 pt",
@@ -575,7 +805,8 @@ function componentSpec() {
       "Line/area null y values create gaps; bar null y values are invalid.",
       "Donut category/value fields must differ; category count is bounded, and all-zero values do not create equal slices.",
       "Funnel fields must differ; shares and denominators are supplied, validated and displayed per row, with no sorting or status inference.",
-      "Filters, maps, images, nested data and executable components are not supported in this release."
+      "Only explicit image columns can load local static PNG/JPEG; every resource stays within the report root and shared byte limits.",
+      "Filters, maps, arbitrary nested data and executable components are not supported in this release."
     ]
   };
 }
@@ -598,6 +829,22 @@ function decodeProps(name, attributes) {
     };
   const props = result.data;
   const errors = [];
+  if (name === "column") {
+    const column = props;
+    const kind = column.kind ?? "scalar";
+    if (kind === "image" && !column.alt)
+      errors.push("image columns require an alt field.");
+    if (kind !== "image" && column.alt)
+      errors.push("alt is only supported on image columns.");
+    if (kind === "image" && column.format)
+      errors.push("Image columns cannot use numeric formatting.");
+    if (kind !== "scalar" && (column.sign !== "auto" || column.semantics !== "neutral"))
+      errors.push("sign and semantics apply only to scalar columns.");
+    if (kind === "scalar" && column.sortBy)
+      errors.push("Scalar columns sort their own field; sortBy is for image/sparkline columns.");
+    if (column.alt === column.field || column.sortBy === column.field)
+      errors.push("alt and sortBy must reference fields different from the rich cell field.");
+  }
   if (name === "donut" || name === "funnel") {
     const fields = Object.entries(props).filter(([key, value]) => ["category", "stage", "value", "total", "share", "status"].includes(key) && value !== undefined).map(([, value]) => value);
     if (new Set(fields).size !== fields.length)
@@ -644,7 +891,7 @@ function parseReport(source, fallbackTitle, diagnostics) {
     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.");
+      diagnostics.add("E_IMAGE_UNSUPPORTED", "Markdown images are not supported; use an explicit image column in a table.", node.position, 'Use ::column{field="image" kind="image" alt="description"} inside a table for local PNG/JPEG images, or use a text link.');
     if (node.type === "link" || node.type === "definition") {
       const url = node.url ?? "";
       let allowed = url.startsWith("#");
@@ -783,7 +1030,7 @@ function parseReport(source, fallbackTitle, diagnostics) {
 
 // src/compiler/compile.ts
 async function compileReport(input) {
-  const requested = path3.resolve(input);
+  const requested = path4.resolve(input);
   const diagnostics = new Diagnostics(displayPath(requested));
   const dependencies = new Set([requested]);
   const result = () => ({
@@ -792,16 +1039,18 @@ async function compileReport(input) {
     filename: requested
   });
   try {
-    if (path3.extname(requested).toLowerCase() !== ".md") {
+    if (path4.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);
+    const report = parseReport(text, path4.basename(filename, path4.extname(filename)), diagnostics);
+    const resolver = new DataResolver(path4.dirname(filename), diagnostics, dependencies, bytes);
     await resolver.resolve(report.blocks);
+    if (resolver.images.embedded.size)
+      report.images = [...resolver.images.embedded.values()];
     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.");
@@ -810,7 +1059,7 @@ async function compileReport(input) {
 }
 
 // src/render/html.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // src/render/content.ts
 import { unified as unified2 } from "unified";
@@ -818,6 +1067,13 @@ import remarkRehype from "remark-rehype";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeStringify from "rehype-stringify";
 
+// src/render/tree.ts
+var t = (value) => ({
+  type: "text",
+  value: String(value)
+});
+var h = (tagName, properties = {}, children = []) => ({ type: "element", tagName, properties, children });
+
 // src/shared/format.ts
 var numbers = new Map;
 function formatValue(value, format = "number", sign = "auto", compact = false) {
@@ -851,14 +1107,106 @@ function valueSentiment(value, semantics = "neutral") {
   return value > 0 === (semantics === "higher-is-better") ? "positive" : "negative";
 }
 
+// src/render/table-cells.ts
+function columnScale(rows, field) {
+  let min = Infinity, max = -Infinity;
+  for (const row of rows) {
+    const cell = row[field];
+    if (!cell || typeof cell !== "object" || cell.kind !== "sparkline")
+      continue;
+    for (const value of cell.values)
+      if (value !== null) {
+        min = Math.min(min, value);
+        max = Math.max(max, value);
+      }
+  }
+  return Number.isFinite(min) ? { min, max } : undefined;
+}
+function richCell(cell, column, scale) {
+  if (cell.kind === "image")
+    return cell.imageId ? [
+      h("svg", {
+        className: ["table-image"],
+        viewBox: "0 0 64 48",
+        width: "64",
+        height: "48",
+        role: "img",
+        ariaLabel: cell.alt
+      }, [h("use", { href: `#${cell.imageId}` })])
+    ] : [t("—")];
+  const values = cell.values;
+  const recorded = values.filter((value) => value !== null);
+  const formatted = (value) => value == null ? "—" : formatValue(value, column.format);
+  const name = column.label ?? column.field;
+  const description = `${name}. ${recorded.length} of ${values.length} recorded samples. First sample ${formatted(values[0])}; last sample ${formatted(values.at(-1))}.${scale ? ` Shared column scale ${formatted(scale.min)} to ${formatted(scale.max)}.` : ""}`;
+  const marks = [];
+  if (scale && recorded.length) {
+    const divisor = Math.max(Math.abs(scale.min), Math.abs(scale.max)) || 1;
+    const low = scale.min / divisor, high = scale.max / divisor;
+    const segments = [];
+    let segment = [];
+    for (const [index, value] of values.entries()) {
+      if (value === null) {
+        if (segment.length)
+          segments.push(segment);
+        segment = [];
+        continue;
+      }
+      const x = values.length === 1 ? 56 : 3 + index / (values.length - 1) * 106;
+      const y = high === low ? 16 : 3 + (1 - (value / divisor - low) / (high - low)) * 26;
+      segment.push([x, y]);
+    }
+    if (segment.length)
+      segments.push(segment);
+    for (const points of segments) {
+      if (points.length === 1)
+        marks.push(h("circle", {
+          cx: points[0][0].toFixed(3),
+          cy: points[0][1].toFixed(3),
+          r: "2"
+        }));
+      else
+        marks.push(h("path", {
+          d: points.map(([x, y], index) => `${index ? "L" : "M"}${x.toFixed(3)} ${y.toFixed(3)}`).join("")
+        }));
+    }
+  }
+  return [
+    h("div", { className: ["sparkline-cell"] }, [
+      ...marks.length ? [
+        h("svg", {
+          className: ["sparkline-chart"],
+          viewBox: "0 0 112 32",
+          width: "112",
+          height: "32",
+          role: "img",
+          ariaLabel: description
+        }, marks)
+      ] : [
+        h("span", { className: ["sparkline-empty"] }, [
+          t("No recorded values")
+        ])
+      ],
+      h("span", {
+        className: ["sparkline-last"],
+        ariaLabel: `Last sample: ${formatted(values.at(-1))}`
+      }, [t(formatted(values.at(-1)))]),
+      ...values.length ? [
+        h("details", { className: ["sparkline-data"] }, [
+          h("summary", {}, [t(`View ${values.length} values`)]),
+          h("ol", { className: ["sparkline-values"] }, values.map((value) => h("li", {}, [t(value === null ? "—" : String(value))])))
+        ])
+      ] : []
+    ])
+  ];
+}
+
 // 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,
@@ -869,7 +1217,11 @@ var serializer = unified2().use(rehypeSanitize, {
     "figcaption",
     "button",
     "caption",
-    "meter"
+    "meter",
+    "svg",
+    "use",
+    "path",
+    "circle"
   ],
   attributes: {
     ...defaultSchema.attributes,
@@ -895,6 +1247,10 @@ var serializer = unified2().use(rehypeSanitize, {
     button: ["type", "disabled", "ariaLabel", "dataColumn"],
     section: ["className", "ariaLabel"],
     meter: ["min", "max", "value", "className", "ariaLabel"],
+    svg: ["className", "viewBox", "width", "height", "role", "ariaLabel"],
+    use: ["href"],
+    path: ["d"],
+    circle: ["cx", "cy", "r"],
     ul: ["className", "role"],
     ol: ["start", "className", "role"],
     li: ["className", "dataStatus"],
@@ -913,11 +1269,13 @@ 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 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 headers = columns.map((column, index) => {
     const name = column.label ?? label(column.field);
-    const content = sortable ? h("button", {
+    const content = canSort[index] ? h("button", {
       type: "button",
       disabled: true,
       dataColumn: index,
@@ -931,18 +1289,20 @@ function table(rows, columns, title, id, sortable = true) {
     return h("th", {
       scope: "col",
       className: numeric[index] ? ["numeric"] : [],
-      ...sortable ? { ariaSort: "none" } : {}
+      ...canSort[index] ? { 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;
+      const rich = value !== null && typeof value === "object";
+      const raw = rich ? value.sort ?? null : value;
       return h("td", {
         className: numeric[index] ? ["numeric"] : [],
-        dataRaw: serializeData(value),
+        ...canSort[index] ? { dataRaw: serializeData(raw) } : {},
         ...typeof value === "number" ? { dataSentiment: valueSentiment(value, column.semantics) } : {}
-      }, [t(cellText(value, column))]);
+      }, rich ? richCell(value, column, scales[index]) : [t(cellText(value, column))]);
     });
     return h("tr", {}, cells);
   });
@@ -1291,7 +1651,7 @@ var inlineScript = (value) => value.replace(/<\/script/gi, "<\\/script").replace
 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 hashes = code.map((script) => `'sha256-${createHash2("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>
@@ -1299,7 +1659,8 @@ function documentHtml(title, description, body, styles, scripts, preview, payloa
 }
 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);
+  const images = report.images?.length ? `<svg class="image-definitions" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><defs>${report.images.map((image) => `<symbol id="${escapeHtml(image.id)}" viewBox="0 0 64 48"><image href="data:${image.mime};base64,${image.base64}" width="64" height="48" preserveAspectRatio="xMidYMid meet"/></symbol>`).join("")}</defs></svg>` : "";
+  return documentHtml(report.metadata.title, report.metadata.description, images + content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, content.hasCharts ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
 }
 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("")}`;
@@ -1307,7 +1668,7 @@ function renderDiagnostics(diagnostics, assets, preview = true, revision = 0) {
 }
 
 // src/export.ts
-import path4 from "node:path";
+import path5 from "node:path";
 import { randomUUID } from "node:crypto";
 import {
   lstat,
@@ -1319,8 +1680,8 @@ import {
   rm
 } from "node:fs/promises";
 async function writeReport(filename, html, inputs) {
-  const destination = path4.resolve(filename);
-  if (path4.extname(destination).toLowerCase() !== ".html")
+  const destination = path5.resolve(filename);
+  if (path5.extname(destination).toLowerCase() !== ".html")
     throw new Error("Output must have an .html extension.");
   let existing;
   try {
@@ -1334,7 +1695,7 @@ async function writeReport(filename, html, inputs) {
     if (!(error && typeof error === "object" && ("code" in error) && error.code === "ENOENT"))
       throw error;
   }
-  let directory = path4.dirname(destination);
+  let directory = path5.dirname(destination);
   const missing = [];
   while (true) {
     try {
@@ -1343,16 +1704,16 @@ async function writeReport(filename, html, inputs) {
     } 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);
+      missing.unshift(path5.basename(directory));
+      const parent = path5.dirname(directory);
       if (parent === directory)
         throw error;
       directory = parent;
     }
   }
-  const canonical = path4.join(directory, ...missing, path4.basename(destination));
+  const canonical = path5.join(directory, ...missing, path5.basename(destination));
   for (const input of inputs) {
-    if (path4.resolve(input) === canonical || path4.resolve(input) === destination)
+    if (path5.resolve(input) === canonical || path5.resolve(input) === destination)
       throw new Error("Output would overwrite a report input or dependency.");
     if (existing) {
       try {
@@ -1365,8 +1726,8 @@ async function writeReport(filename, html, inputs) {
       }
     }
   }
-  await mkdir(path4.dirname(destination), { recursive: true });
-  const temporary = path4.join(path4.dirname(destination), `.plotleaf-${randomUUID()}.tmp`);
+  await mkdir(path5.dirname(destination), { recursive: true });
+  const temporary = path5.join(path5.dirname(destination), `.plotleaf-${randomUUID()}.tmp`);
   try {
     await writeFile(temporary, html, {
       encoding: "utf8",
@@ -1531,7 +1892,7 @@ data: ${revision}
 // package.json
 var package_default = {
   name: "plotleaf",
-  version: "0.2.0",
+  version: "0.3.1",
   description: "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   type: "module",
   license: "MIT",
@@ -1557,12 +1918,17 @@ var package_default = {
     "dist/assets/styles.css",
     "dist/assets/notices.txt",
     "schema/components.json",
+    "examples/report.md",
     "examples/storefront/*.md",
     "examples/storefront/*.json",
     "examples/adoption/*.md",
     "examples/adoption/*.json",
     "examples/onboarding/*.md",
     "examples/onboarding/*.json",
+    "examples/catalog/*.md",
+    "examples/catalog/*.json",
+    "examples/catalog/assets/*.png",
+    "examples/catalog/assets/*.jpg",
     "skills/plotleaf/SKILL.md",
     "README.md",
     "LICENSE",
@@ -1577,10 +1943,12 @@ var package_default = {
     "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"
+    "audit:package": "node scripts/audit-package.mjs",
+    dev: "bun run build && node dist/cli.js dev examples/report.md"
   },
   dependencies: {
     chokidar: "6.0.0",
+    "image-size": "2.1.0",
     open: "11.0.4",
     "rehype-sanitize": "6.0.0",
     "rehype-stringify": "10.0.1",
@@ -1620,6 +1988,7 @@ Usage:
   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 guide                          Read the report-authoring guide
   npx plotleaf schema                         Print component specifications
 
 Options:
@@ -1660,14 +2029,17 @@ async function main() {
     return;
   }
   const first = positionals[0];
-  const known = ["dev", "validate", "build", "schema"];
+  const known = ["dev", "validate", "build", "schema", "guide"];
   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 (command === "schema" || command === "guide") {
     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));
+      throw new Error(`${command} does not accept a report or options. Use plotleaf ${command}.`);
+    if (command === "guide")
+      process.stdout.write(await readFile(new URL("../skills/plotleaf/SKILL.md", import.meta.url), "utf8"));
+    else
+      console.log(JSON.stringify(componentSpec(), null, 2));
     return;
   }
   if (!filename || extras.length)
@@ -1706,7 +2078,7 @@ async function main() {
       return;
     }
     const html = renderHtml(result.report, await assets());
-    const defaultOutput = result.filename.slice(0, -path5.extname(result.filename).length) + ".html";
+    const defaultOutput = result.filename.slice(0, -path6.extname(result.filename).length) + ".html";
     const destination = await writeReport(values.out ?? defaultOutput, html, result.dependencies);
     console.log(`Built ${displayPath(destination)} (${(Buffer.byteLength(html) / 1024).toFixed(1)} KiB)`);
     return;