plotleaf 0.3.0 → 0.3.2

package/README.md

@@ -4,12 +4,24 @@ Beautiful, interactive reports from Markdown and prepared JSON. Built for coding
 
 **The agent does the thinking. We do the rendering.**
 
-[Source](https://github.com/LoueeD/plotleaf) · [Issues](https://github.com/LoueeD/plotleaf/issues) · [Verification](https://github.com/LoueeD/plotleaf/actions/workflows/ci.yml) · [Contributing](https://github.com/LoueeD/plotleaf/blob/main/CONTRIBUTING.md)
+[Website](https://plotleaf-site.loueed.workers.dev) · [Docs](https://plotleaf-site.loueed.workers.dev/docs/) · [Examples](https://plotleaf-site.loueed.workers.dev/examples/) · [Playground](https://plotleaf-site.loueed.workers.dev/playground/) · [Source](https://github.com/LoueeD/plotleaf) · [Issues](https://github.com/LoueeD/plotleaf/issues) · [Verification](https://github.com/LoueeD/plotleaf/actions/workflows/ci.yml) · [Contributing](https://github.com/LoueeD/plotleaf/blob/main/CONTRIBUTING.md)
 
 A report is one Markdown file, optionally accompanied by local JSON datasets. No application, configuration file, account, database or hosted service. Export one HTML file that keeps working offline.
 
+## Start with your coding agent
+
+Copy this into your coding agent and describe your report:
+
+```text
+Build a beautiful, interactive report with Plotleaf.
+Here's what I want to explore: [Your brief and data]
+Follow https://plotleaf-site.loueed.workers.dev/agent and give me a preview and a standalone HTML report.
+```
+
 ## Status
 
+**0.3.2** adds the website links and updated agent setup prompt. Read the [docs](https://plotleaf-site.loueed.workers.dev/docs/), explore [example reports](https://plotleaf-site.loueed.workers.dev/examples/), or try the [browser playground](https://plotleaf-site.loueed.workers.dev/playground/) without installing anything. The playground supports Markdown and JSON; local image imports and larger reports use the CLI.
+
 The initial MVP includes validation, live preview/reload, self-contained HTML export and a generated component specification. All bundled examples use fictional data.
 
 **0.3.0** adds local PNG/JPEG image cells, static sparklines and a cumulative example report. Donut charts and prepared funnel/progress views are available since 0.2.0. Check your installed CLI version or schema before using newer components.
@@ -30,6 +42,8 @@ npx plotleaf schema
 
 `plotleaf report.md` is an alias for `dev`. `build` defaults to `report.html` beside the source. Relative dataset paths resolve from the Markdown file's directory; an explicit `--out` resolves from the caller's working directory. Exports contain no preview connection and need no source files at viewing time.
 
+For agent discovery, `npx plotleaf guide` (0.3.1+) prints the bundled report-authoring guide as Markdown, and `npx plotleaf schema` prints the component specification as JSON. The guide is the same `skills/plotleaf/SKILL.md` shipped with the package. These commands print documentation without creating files, changing project configuration or starting a server; once installed, they read local package content.
+
 ## A report
 
 ```markdown

package/dist/cli.js

@@ -12,6 +12,7 @@ import { realpath as realpath2 } from "node:fs/promises";
 // src/compiler/diagnostics.ts
 import path from "node:path";
 
+// src/compiler/diagnostic-core.ts
 class Diagnostics {
   file;
   items = [];
@@ -51,9 +52,6 @@ class Diagnostics {
     return [...this.items].sort((a, b) => a.file.localeCompare(b.file, "en") || a.line - b.line || a.column - b.column || a.code.localeCompare(b.code, "en"));
   }
 }
-function displayPath(filename) {
-  return path.relative(process.cwd(), filename) || path.basename(filename);
-}
 function humanDiagnostics(items) {
   return items.map((d) => `${d.file}:${d.line}:${d.column} ${d.code}${d.severity === "warning" ? " (warning)" : ""}
 ${d.message}${d.hint ? `
@@ -62,30 +60,12 @@ ${d.hint}` : ""}`).join(`
 `);
 }
 
-// src/compiler/files.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,
-  donutSlices: 8,
-  funnelStages: 20,
-  tableRows: 1000,
-  tableColumns: 40,
-  sparklinePoints: 64,
-  imageFiles: 64,
-  imageBytes: 1024 ** 2,
-  imageDimension: 4096,
-  imagePixels: 4000000
-};
+// src/compiler/diagnostics.ts
+function displayPath(filename) {
+  return path.relative(process.cwd(), filename) || path.basename(filename);
+}
 
-// src/compiler/files.ts
+// src/compiler/sources.ts
 class LocalFileError extends Error {
   kind;
   constructor(kind, message) {
@@ -93,184 +73,8 @@ class LocalFileError extends Error {
     this.kind = kind;
   }
 }
-function contained(root, filename) {
-  const relative = path2.relative(root, filename);
-  return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
-}
-async function readBytesBounded(filename, maximum) {
-  if (!(await stat(filename)).isFile())
-    throw new Error("Expected a regular file.");
-  const file = await open(filename, "r");
-  try {
-    const info = await file.stat();
-    if (!info.isFile())
-      throw new Error("Expected a regular file.");
-    if (info.size > maximum)
-      throw new Error(`File exceeds the ${Math.floor(maximum / 1024)} KiB size limit.`);
-    const chunks = [];
-    let bytes = 0;
-    while (bytes <= maximum) {
-      const buffer = Buffer.alloc(Math.min(64 * 1024, maximum + 1 - bytes));
-      const result = await file.read(buffer, 0, buffer.length, null);
-      if (!result.bytesRead)
-        break;
-      chunks.push(buffer.subarray(0, result.bytesRead));
-      bytes += result.bytesRead;
-    }
-    if (bytes > maximum)
-      throw new Error("File grew beyond the size limit while reading.");
-    return Buffer.concat(chunks, bytes);
-  } finally {
-    await file.close();
-  }
-}
-async function readBounded(filename, maximum) {
-  const bytes = await readBytesBounded(filename, maximum);
-  return {
-    text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
-    bytes: bytes.length
-  };
-}
 
-class ReportFiles {
-  root;
-  dependencies;
-  usedBytes;
-  constructor(root, dependencies, usedBytes) {
-    this.root = root;
-    this.dependencies = dependencies;
-    this.usedBytes = usedBytes;
-  }
-  async resolve(reference, extensions) {
-    const fail = (message) => {
-      throw new LocalFileError("path", message);
-    };
-    if (path2.isAbsolute(reference) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(reference) || reference.includes("\\") || /%[\da-f]{2}/i.test(reference) || reference.includes("\x00"))
-      fail(`Use a plain relative local ${extensions.join("/")} path.`);
-    const candidate = path2.resolve(this.root, reference);
-    const hidden = (filename) => path2.relative(this.root, filename).split(path2.sep).some((part) => part.startsWith("."));
-    if (!contained(this.root, candidate))
-      fail("Reference escapes the report directory.");
-    if (hidden(candidate))
-      fail("Hidden files and directories are not allowed.");
-    if (!extensions.includes(path2.extname(candidate).toLowerCase()))
-      fail(`Use a ${extensions.join("/")} file.`);
-    this.dependencies.add(candidate);
-    let canonical;
-    try {
-      canonical = await realpath(candidate);
-    } catch {
-      throw new LocalFileError("read", "Cannot read the referenced file. Create it or correct the reference.");
-    }
-    if (!contained(this.root, canonical) || hidden(canonical))
-      fail("The resolved file or symlink escapes the permitted report files.");
-    if (!extensions.includes(path2.extname(canonical).toLowerCase()))
-      fail(`The resolved file must also have a ${extensions.join("/")} extension.`);
-    this.dependencies.add(canonical);
-    return canonical;
-  }
-  async read(filename, maximum) {
-    const bytes = await readBytesBounded(filename, Math.min(maximum, limits.totalBytes - this.usedBytes));
-    this.usedBytes += bytes.length;
-    return bytes;
-  }
-}
-
-// src/compiler/images.ts
-import { createHash } from "node:crypto";
-import path3 from "node:path";
-import { imageSize } from "image-size";
-function formatOf(bytes) {
-  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
-    let offset = 8;
-    let data = false;
-    while (offset + 12 <= bytes.length) {
-      const size = bytes.readUInt32BE(offset);
-      const type = bytes.toString("ascii", offset + 4, offset + 8);
-      if (offset + size + 12 > bytes.length)
-        break;
-      if (offset === 8 && (type !== "IHDR" || size !== 13))
-        break;
-      if (type === "acTL")
-        throw new Error("Animated PNG is not supported; provide a static image.");
-      if (type === "IDAT" && size > 0)
-        data = true;
-      offset += size + 12;
-      if (type === "IEND") {
-        if (data && size === 0 && offset === bytes.length)
-          return "png";
-        break;
-      }
-    }
-    throw new Error("Incomplete or invalid PNG container.");
-  }
-  if (bytes.length >= 4 && bytes.readUInt16BE(0) === 65496 && bytes.readUInt16BE(bytes.length - 2) === 65497)
-    return "jpg";
-  throw new Error("Expected a static PNG or JPEG image with a matching file extension.");
-}
-
-class ImageResolver {
-  files;
-  attempted = new Set;
-  filesRead = new Map;
-  embedded = new Map;
-  constructor(files) {
-    this.files = files;
-  }
-  async load(reference) {
-    const requested = path3.resolve(this.files.root, reference);
-    if (!this.attempted.has(requested) && this.attempted.size >= limits.imageFiles)
-      throw new Error(`At most ${limits.imageFiles} local image references are supported.`);
-    this.attempted.add(requested);
-    const canonical = await this.files.resolve(reference, [
-      ".png",
-      ".jpg",
-      ".jpeg"
-    ]);
-    const cached = this.filesRead.get(canonical);
-    if (cached) {
-      if (path3.extname(reference).toLowerCase() === ".png" !== (cached.mime === "image/png"))
-        throw new Error("Image signature does not match its file extension.");
-      return cached;
-    }
-    if (this.filesRead.size >= limits.imageFiles)
-      throw new Error(`At most ${limits.imageFiles} local image files are supported.`);
-    const bytes = await this.files.read(canonical, limits.imageBytes);
-    const format = formatOf(bytes);
-    const expected = (name) => path3.extname(name).toLowerCase() === ".png" ? "png" : "jpg";
-    if (format !== expected(reference) || format !== expected(canonical))
-      throw new Error("Image signature does not match its file extension.");
-    let size;
-    try {
-      size = imageSize(bytes);
-    } catch {
-      throw new Error("Unsupported or damaged PNG/JPEG header.");
-    }
-    if (size.type !== format || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1)
-      throw new Error("Image must have valid positive raster dimensions.");
-    if (size.width > limits.imageDimension || size.height > limits.imageDimension || size.width * size.height > limits.imagePixels)
-      throw new Error(`Image exceeds ${limits.imageDimension} pixels per side or ${limits.imagePixels.toLocaleString("en-GB")} pixels in total. Resize the prepared asset.`);
-    const id = `plotleaf-image-${createHash("sha256").update(bytes).digest("hex")}`;
-    const image = this.embedded.get(id) ?? {
-      id,
-      mime: format === "png" ? "image/png" : "image/jpeg",
-      base64: bytes.toString("base64")
-    };
-    this.filesRead.set(canonical, image);
-    this.embedded.set(id, image);
-    return image;
-  }
-}
-// src/shared/payload.ts
-var funnelStatuses = {
-  "on-target": "On target",
-  "below-target": "Below target",
-  "at-risk": "At risk",
-  neutral: "Neutral"
-};
-
-// src/compiler/data.ts
-var reserved = new Set(["__proto__", "constructor", "prototype"]);
+// src/shared/date.ts
 function parseDate(value) {
   const date = value.slice(0, 10);
   if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
@@ -286,19 +90,45 @@ function parseDate(value) {
   return Number.isFinite(timestamp) ? timestamp : undefined;
 }
 
+// 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,
+  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/resolve-data.ts
+var reserved = new Set(["__proto__", "constructor", "prototype"]);
+
 class DataResolver {
-  root;
   diagnostics;
-  dependencies;
-  cache = new Map;
   files;
   images;
-  constructor(root, diagnostics, dependencies, totalBytes = 0) {
-    this.root = root;
+  cache = new Map;
+  constructor(diagnostics, files, images) {
     this.diagnostics = diagnostics;
-    this.dependencies = dependencies;
-    this.files = new ReportFiles(root, dependencies, totalBytes);
-    this.images = new ImageResolver(this.files);
+    this.files = files;
+    this.images = images;
   }
   async load(reference, block) {
     const fail = (code, message, hint) => {
@@ -601,6 +431,188 @@ class DataResolver {
   }
 }
 
+// src/compiler/files.ts
+import path2 from "node:path";
+import { open, realpath, stat } from "node:fs/promises";
+function contained(root, filename) {
+  const relative = path2.relative(root, filename);
+  return relative === "" || !path2.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path2.sep}`);
+}
+async function readBytesBounded(filename, maximum) {
+  if (!(await stat(filename)).isFile())
+    throw new Error("Expected a regular file.");
+  const file = await open(filename, "r");
+  try {
+    const info = await file.stat();
+    if (!info.isFile())
+      throw new Error("Expected a regular file.");
+    if (info.size > maximum)
+      throw new Error(`File exceeds the ${Math.floor(maximum / 1024)} KiB size limit.`);
+    const chunks = [];
+    let bytes = 0;
+    while (bytes <= maximum) {
+      const buffer = Buffer.alloc(Math.min(64 * 1024, maximum + 1 - bytes));
+      const result = await file.read(buffer, 0, buffer.length, null);
+      if (!result.bytesRead)
+        break;
+      chunks.push(buffer.subarray(0, result.bytesRead));
+      bytes += result.bytesRead;
+    }
+    if (bytes > maximum)
+      throw new Error("File grew beyond the size limit while reading.");
+    return Buffer.concat(chunks, bytes);
+  } finally {
+    await file.close();
+  }
+}
+async function readBounded(filename, maximum) {
+  const bytes = await readBytesBounded(filename, maximum);
+  return {
+    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/compiler/data.ts
+class DataResolver2 extends DataResolver {
+  root;
+  constructor(root, diagnostics, dependencies, totalBytes = 0) {
+    const files = new ReportFiles(root, dependencies, totalBytes);
+    super(diagnostics, files, new ImageResolver(files));
+    this.root = root;
+  }
+}
+
 // src/compiler/parse.ts
 import { unified } from "unified";
 import remarkParse from "remark-parse";
@@ -1047,7 +1059,7 @@ async function compileReport(input) {
     dependencies.add(filename);
     const { text, bytes } = await readBounded(filename, limits.markdownBytes);
     const report = parseReport(text, path4.basename(filename, path4.extname(filename)), diagnostics);
-    const resolver = new DataResolver(path4.dirname(filename), diagnostics, dependencies, bytes);
+    const resolver = new DataResolver2(path4.dirname(filename), diagnostics, dependencies, bytes);
     await resolver.resolve(report.blocks);
     if (resolver.images.embedded.size)
       report.images = [...resolver.images.embedded.values()];
@@ -1645,26 +1657,35 @@ function renderContent(report) {
   };
 }
 
-// src/render/html.ts
+// src/render/document.ts
 var escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 var inlineScript = (value) => value.replace(/<\/script/gi, "<\\/script").replaceAll("<!--", "\\x3c!--");
 var reload = (revision) => `(()=>{const source=new EventSource("/__plotleaf/events");source.addEventListener("ready",event=>{if(Number(event.data)!==${revision})location.reload()});source.addEventListener("reload",()=>location.reload());addEventListener("pagehide",()=>source.close(),{once:true});})();`;
-function documentHtml(title, description, body, styles, scripts, preview, payload, notices = "", revision = 0) {
+function documentHtml(title, description, body, styles, scripts, preview, hash, payload, notices = "", revision = 0) {
   const code = [...scripts, ...preview ? [reload(revision)] : []].map(inlineScript);
-  const hashes = code.map((script) => `'sha256-${createHash2("sha256").update(script).digest("base64")}'`).join(" ");
+  const hashes = code.map((script) => `'sha256-${hash(script)}'`).join(" ");
   const policy = `default-src 'none'; script-src ${hashes || "'none'"}; style-src 'unsafe-inline'; img-src data:; font-src data:; connect-src ${preview ? "'self'" : "'none'"}; base-uri 'none'; object-src 'none'; form-action 'none'`;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escapeHtml(policy)}"><meta name="color-scheme" content="light dark"><title>${escapeHtml(title)}</title>${description ? `<meta name="description" content="${escapeHtml(description)}">` : ""}<style>${styles}</style></head><body><a class="skip-link" href="#plotleaf-report">Skip to report</a><main class="report" id="plotleaf-report">${body}</main>${payload ? `<script type="application/json" id="plotleaf-data">${payload}</script>` : ""}${notices ? `<template id="plotleaf-notices"><pre>${escapeHtml(notices)}</pre></template>` : ""}${code.map((script) => `<script>${script}</script>`).join("")}</body></html>
 `;
 }
-function renderHtml(report, assets, preview = false, revision = 0) {
+function renderHtml(report, assets, hash, preview = false, revision = 0) {
   const content = renderContent(report);
   const images = report.images?.length ? `<svg class="image-definitions" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><defs>${report.images.map((image) => `<symbol id="${escapeHtml(image.id)}" viewBox="0 0 64 48"><image href="data:${image.mime};base64,${image.base64}" width="64" height="48" preserveAspectRatio="xMidYMid meet"/></symbol>`).join("")}</defs></svg>` : "";
-  return documentHtml(report.metadata.title, report.metadata.description, images + content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, content.hasCharts ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
+  return documentHtml(report.metadata.title, report.metadata.description, images + content.html, assets.styles, [content.hasCharts ? assets.charts : assets.base], preview, hash, content.hasCharts ? serializeData(content.payload) : undefined, content.hasCharts ? assets.notices : "", revision);
 }
-function renderDiagnostics(diagnostics, assets, preview = true, revision = 0) {
+function renderDiagnostics(diagnostics, assets, hash, preview = true, revision = 0) {
   const body = `<h1>Report needs attention</h1><p class="diagnostic-intro">Update the source files to refresh this preview.</p>${diagnostics.map((item) => `<section class="diagnostic"><p class="diagnostic-location">${escapeHtml(item.file)}:${item.line}:${item.column} · ${escapeHtml(item.code)}</p><p>${escapeHtml(item.message)}</p>${item.hint ? `<p class="diagnostic-hint">${escapeHtml(item.hint)}</p>` : ""}</section>`).join("")}`;
-  return documentHtml("Report needs attention", undefined, body, assets.styles, [], preview, undefined, "", revision);
+  return documentHtml("Report needs attention", undefined, body, assets.styles, [], preview, hash, undefined, "", revision);
+}
+
+// src/render/html.ts
+var hash = (script) => createHash2("sha256").update(script).digest("base64");
+function renderHtml2(report, assets, preview = false, revision = 0) {
+  return renderHtml(report, assets, hash, preview, revision);
+}
+function renderDiagnostics2(diagnostics, assets, preview = true, revision = 0) {
+  return renderDiagnostics(diagnostics, assets, hash, preview, revision);
 }
 
 // src/export.ts
@@ -1749,7 +1770,7 @@ async function startPreview(filename, assets, options = {}) {
   const log = options.log ?? console.log;
   let compilation = options.initial ?? await compileReport(filename);
   let revision = 0;
-  const render = () => compilation.report ? renderHtml(compilation.report, assets, true, revision) : renderDiagnostics(compilation.diagnostics, assets, true, revision);
+  const render = () => compilation.report ? renderHtml2(compilation.report, assets, true, revision) : renderDiagnostics2(compilation.diagnostics, assets, true, revision);
   let html = render();
   let closed = false;
   let running = false;
@@ -1892,7 +1913,7 @@ data: ${revision}
 // package.json
 var package_default = {
   name: "plotleaf",
-  version: "0.3.0",
+  version: "0.3.2",
   description: "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   type: "module",
   license: "MIT",
@@ -1900,7 +1921,7 @@ var package_default = {
     type: "git",
     url: "git+https://github.com/LoueeD/plotleaf.git"
   },
-  homepage: "https://github.com/LoueeD/plotleaf#readme",
+  homepage: "https://plotleaf-site.loueed.workers.dev",
   bugs: {
     url: "https://github.com/LoueeD/plotleaf/issues"
   },
@@ -1988,6 +2009,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:
@@ -2028,14 +2050,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)
@@ -2073,7 +2098,7 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    const html = renderHtml(result.report, await assets());
+    const html = renderHtml2(result.report, await assets());
     const defaultOutput = result.filename.slice(0, -path6.extname(result.filename).length) + ".html";
     const destination = await writeReport(values.out ?? defaultOutput, html, result.dependencies);
     console.log(`Built ${displayPath(destination)} (${(Buffer.byteLength(html) / 1024).toFixed(1)} KiB)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotleaf",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/LoueeD/plotleaf.git"
   },
-  "homepage": "https://github.com/LoueeD/plotleaf#readme",
+  "homepage": "https://plotleaf-site.loueed.workers.dev",
   "bugs": {
     "url": "https://github.com/LoueeD/plotleaf/issues"
   },

package/skills/plotleaf/SKILL.md

@@ -7,7 +7,7 @@ description: Create and revise plotleaf Markdown reports from prepared JSON, the
 
 Create one Markdown file with optional local JSON datasets. The agent retrieves, analyses and prepares data; plotleaf renders it. Do not scaffold an application or put analysis code, SQL, JavaScript expressions or scripts into the report.
 
-Use an installed `plotleaf` CLI or `npx plotleaf`. In an unpublished source checkout, build it with `bun run build` and use `node dist/cli.js` from the package root instead of fetching an npm release.
+Use an installed `plotleaf` CLI or `npx plotleaf`. The CLI requires Node 22 or newer; Bun is not required for report authors. In an unpublished source checkout, build it with `bun run build` and use `node dist/cli.js` from the package root instead of fetching an npm release.
 
 ## Discover the contract