plotleaf 0.2.0 → 0.3.1

package/examples/catalog/products.json

@@ -0,0 +1,78 @@
+[
+  {
+    "product": "Linen tote",
+    "image": "./assets/linen-tote.png",
+    "image_alt": "Illustration of a sand-coloured linen tote",
+    "weekly_orders": [
+      42,
+      47,
+      44,
+      56,
+      59,
+      63,
+      68,
+      74
+    ],
+    "orders": 453,
+    "revenue": 18120,
+    "change": 0.182,
+    "last_week": 74
+  },
+  {
+    "product": "Desk lamp",
+    "image": "./assets/desk-lamp.jpg",
+    "image_alt": "Illustration of a blue desk lamp",
+    "weekly_orders": [
+      38,
+      35,
+      39,
+      null,
+      46,
+      44,
+      49,
+      53
+    ],
+    "orders": 304,
+    "revenue": 27360,
+    "change": 0.124,
+    "last_week": 53
+  },
+  {
+    "product": "Field notebook",
+    "image": "./assets/field-notebook.png",
+    "image_alt": "Illustration of a green field notebook",
+    "weekly_orders": [
+      60,
+      63,
+      59,
+      64,
+      62,
+      69,
+      72,
+      78
+    ],
+    "orders": 527,
+    "revenue": 10540,
+    "change": 0.068,
+    "last_week": 78
+  },
+  {
+    "product": "Linen tote \u2014 natural",
+    "image": "./assets/linen-tote.png",
+    "image_alt": "Illustration of the same sand-coloured linen tote in a second product row",
+    "weekly_orders": [
+      18,
+      21,
+      20,
+      24,
+      23,
+      27,
+      29,
+      31
+    ],
+    "orders": 193,
+    "revenue": 7720,
+    "change": 0.094,
+    "last_week": 31
+  }
+]

package/examples/catalog/report.md

@@ -0,0 +1,39 @@
+---
+title: Product Performance
+description: A fictional catalogue with embedded product images and weekly order sparklines.
+---
+
+# Product Performance
+
+A fictional store's product performance over **eight weeks ending 1 November 2026**. All data, comparisons and product illustrations are synthetic and prepared for this example.
+
+:::grid{columns="3"}
+::metric{label="Orders" value="1477" comparison="18.2% vs previous eight weeks" direction="up" sentiment="positive"}
+::metric{label="Revenue" value="63740" format="currency:USD" comparison="20% vs previous eight weeks" direction="up" sentiment="positive"}
+::metric{label="Products" value="4" comparison="1 more than previous period" direction="up" sentiment="positive"}
+:::
+
+The fictional comparison period contains **1,250 orders**, **US$53,120 revenue** and **three products**. Changes above are prepared and rounded by the example author.
+
+## Product detail
+
+Weekly order lines share the same vertical scale, so their heights are comparable. The lamp has one missing week, shown as a gap; its prepared total covers recorded weeks only. Expand **View values** to inspect the original samples.
+
+:::table{data="./products.json" title="Performance by product"}
+::column{field="image" label="Preview" kind="image" alt="image_alt"}
+::column{field="product" label="Product"}
+::column{field="weekly_orders" label="Weekly orders" kind="sparkline" sortBy="last_week"}
+::column{field="orders" label="Orders" format="number"}
+::column{field="revenue" label="Revenue" format="currency:USD"}
+::column{field="change" label="Δ period" format="percent" sign="always" semantics="higher-is-better"}
+:::
+
+### Reading this table
+
+- **Linen tote leads relative growth.** Comparisons are prepared by the author, not calculated from the sparkline.
+- **Notebooks lead order volume.** They also have the highest final-week value in this fictional set.
+- **The natural tote reuses its image.** The portable report embeds each unique illustration once.
+
+:::callout{title="Coverage"}
+Every value and illustration is fictional. Sorting Weekly orders uses the declared final-week key; it does not compare arrays or recompute totals. No live filters or subtotal calculations are implied.
+:::

package/examples/catalog/showcase-products.json

@@ -0,0 +1,78 @@
+[
+  {
+    "product": "Linen tote",
+    "image": "./catalog/assets/linen-tote.png",
+    "image_alt": "Illustration of a sand-coloured linen tote",
+    "weekly_orders": [
+      42,
+      47,
+      44,
+      56,
+      59,
+      63,
+      68,
+      74
+    ],
+    "orders": 453,
+    "revenue": 18120,
+    "change": 0.182,
+    "last_week": 74
+  },
+  {
+    "product": "Desk lamp",
+    "image": "./catalog/assets/desk-lamp.jpg",
+    "image_alt": "Illustration of a blue desk lamp",
+    "weekly_orders": [
+      38,
+      35,
+      39,
+      null,
+      46,
+      44,
+      49,
+      53
+    ],
+    "orders": 304,
+    "revenue": 27360,
+    "change": 0.124,
+    "last_week": 53
+  },
+  {
+    "product": "Field notebook",
+    "image": "./catalog/assets/field-notebook.png",
+    "image_alt": "Illustration of a green field notebook",
+    "weekly_orders": [
+      60,
+      63,
+      59,
+      64,
+      62,
+      69,
+      72,
+      78
+    ],
+    "orders": 527,
+    "revenue": 10540,
+    "change": 0.068,
+    "last_week": 78
+  },
+  {
+    "product": "Linen tote — natural",
+    "image": "./catalog/assets/linen-tote.png",
+    "image_alt": "Illustration of the same sand-coloured linen tote in a second product row",
+    "weekly_orders": [
+      18,
+      21,
+      20,
+      24,
+      23,
+      27,
+      29,
+      31
+    ],
+    "orders": 193,
+    "revenue": 7720,
+    "change": 0.094,
+    "last_week": 31
+  }
+]

package/examples/report.md

@@ -0,0 +1,96 @@
+---
+title: Storefront Overview
+description: A cumulative plotleaf showcase with fictional metrics, charts, tables, images and sparklines.
+---
+
+# Storefront Overview
+
+A fictional store's weekly performance, using synthetic data for demonstration. Orders grew **18.2%**, while returns fell **12%** from the previous period.
+
+:::grid{columns="4"}
+::metric{label="Orders" value="12480" comparison="18.2% vs previous week" direction="up" sentiment="positive"}
+::metric{label="Revenue" value="824160" format="currency:USD" comparison="24.1% vs previous week" direction="up" sentiment="positive"}
+::metric{label="Returns" value="384" comparison="12% vs previous week" direction="down" sentiment="positive"}
+::metric{label="Return rate" value="0.03076923076923077" format="percent" comparison="0.4 pt vs previous week" direction="down" sentiment="positive"}
+:::
+
+## Sales and returns
+
+The store received **12,480 orders** over seven days. Size-related returns made up most of the **384 returns**, suggesting a useful area for clearer product guidance.
+
+:::grid{columns="2"}
+::area{data="./storefront/orders.json" x="date" y="orders" xType="date" title="Orders by day" target="2000" targetLabel="Daily target"}
+::bar{data="./storefront/returns.json" x="reason" y="count" title="Returns by reason"}
+:::
+
+## Sales by category
+
+Apparel accounts for the largest share of this fictional week's **12,480 orders**. Each order belongs to one category.
+
+::::grid{columns="2"}
+::donut{data="./storefront/categories.json" category="category" value="orders" title="Order mix"}
+:::table{data="./storefront/categories.json" title="Category performance"}
+::column{field="category" label="Category"}
+::column{field="orders" label="Orders" format="number"}
+::column{field="revenue" label="Revenue" format="currency:USD"}
+::column{field="change" label="Δ week" format="percent" sign="always" semantics="higher-is-better"}
+:::
+::::
+
+### Key findings
+
+- **Growth spans every category.** All four categories increased orders over the previous week.
+- **Returns declined.** The return count and rate both improved.
+- **Size guidance is the next opportunity.** Review fit descriptions before changing the return policy.
+
+---
+
+## Product onboarding
+
+A separate fictional product example covers **6 April–28 June 2026**. Its prepared funnel uses **41,200 visitors** as the denominator for every stage; its statuses reflect the example author's operating targets. These team counts are independent of the store's orders above.
+
+:::grid{columns="2"}
+::line{data="./onboarding/signups.json" x="week" y="signups" xType="date" title="Signups by week" target="1600" targetLabel="Weekly target"}
+::funnel{data="./onboarding/funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}
+:::
+
+### Onboarding findings
+
+Activation needs attention against the prepared target, and conversion is marked at risk. Expand the chart and funnel data disclosures to inspect the original values and denominators.
+
+---
+
+## Product catalogue
+
+A fictional store's product performance over **eight weeks ending 1 November 2026**. All data, comparisons and product illustrations are synthetic and prepared for this example.
+
+:::grid{columns="3"}
+::metric{label="Orders" value="1477" comparison="18.2% vs previous eight weeks" direction="up" sentiment="positive"}
+::metric{label="Revenue" value="63740" format="currency:USD" comparison="20% vs previous eight weeks" direction="up" sentiment="positive"}
+::metric{label="Products" value="4" comparison="1 more than previous period" direction="up" sentiment="positive"}
+:::
+
+The fictional comparison period contains **1,250 orders**, **US$53,120 revenue** and **three products**. Changes above are prepared and rounded by the example author.
+
+### Product detail
+
+Weekly order lines share the same vertical scale, so their heights are comparable. The lamp has one missing week, shown as a gap; its prepared total covers recorded weeks only. Expand **View values** to inspect the original samples.
+
+:::table{data="./catalog/showcase-products.json" title="Performance by product"}
+::column{field="image" label="Preview" kind="image" alt="image_alt"}
+::column{field="product" label="Product"}
+::column{field="weekly_orders" label="Weekly orders" kind="sparkline" sortBy="last_week"}
+::column{field="orders" label="Orders" format="number"}
+::column{field="revenue" label="Revenue" format="currency:USD"}
+::column{field="change" label="Δ period" format="percent" sign="always" semantics="higher-is-better"}
+:::
+
+### Reading this table
+
+- **Linen tote leads relative growth.** Comparisons are prepared by the author, not calculated from the sparkline.
+- **Notebooks lead order volume.** They also have the highest final-week value in this fictional set.
+- **The natural tote reuses its image.** The portable report embeds each unique illustration once.
+
+:::callout{title="About these examples"}
+All datasets, comparisons, statuses, findings and product illustrations are fictional. Store totals cover 1–7 November 2026; the onboarding and catalogue sections identify their separate periods and populations. Comparisons are prepared by the author, not inferred by the renderer. No live filters, data connections or subtotal calculations are implied.
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "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",
@@ -26,12 +26,17 @@
     "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",
@@ -46,10 +51,12 @@
     "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",

package/schema/components.json

@@ -12,10 +12,15 @@
     "donutSlices": 8,
     "funnelStages": 20,
     "tableRows": 1000,
-    "tableColumns": 40
+    "tableColumns": 40,
+    "sparklinePoints": 64,
+    "imageFiles": 64,
+    "imageBytes": 1048576,
+    "imageDimension": 4096,
+    "imagePixels": 4000000
   },
   "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",
@@ -451,7 +456,7 @@
       "example": ":::table{data=\"./plans.json\" title=\"By plan\"}\n::column{field=\"plan\" label=\"Plan\"}\n::column{field=\"change\" label=\"Δ QoQ\" format=\"percent\" sign=\"always\"}\n:::"
     },
     "column": {
-      "description": "An explicit field, label and format inside a table.",
+      "description": "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
       "forms": [
         "leaf"
       ],
@@ -470,6 +475,24 @@
             "minLength": 1,
             "maxLength": 1000
           },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "scalar",
+              "image",
+              "sparkline"
+            ]
+          },
+          "alt": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "sortBy": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
           "format": {
             "type": "string",
             "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
@@ -499,7 +522,12 @@
         ],
         "additionalProperties": false
       },
-      "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": {
       "description": "A contextual note or warning containing ordinary Markdown.",
@@ -546,6 +574,7 @@
     "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."
   ]
 }

package/skills/plotleaf/SKILL.md

@@ -11,9 +11,9 @@ Use an installed `plotleaf` CLI or `npx plotleaf`. In an unpublished source chec
 
 ## Discover the contract
 
-Run `plotleaf schema` (or `npx plotleaf schema`) for the current machine-readable component/prop specifications, rules and input limits. Prefer that output over remembered syntax. Supported components in 0.2.0 include `grid`, `metric`, `line`, `area`, `bar`, `donut`, `funnel`, `table`, `column` and `callout`. Donut and funnel require plotleaf 0.2.0 or newer; check the installed CLI's schema when using an older version.
+Run `plotleaf schema` (or `npx plotleaf schema`) for the current machine-readable component/prop specifications, rules and input limits. Prefer that output over remembered syntax. Supported components include `grid`, `metric`, `line`, `area`, `bar`, `donut`, `funnel`, `table`, `column` and `callout`. Donut and funnel require plotleaf 0.2.0 or newer; check the installed CLI's schema when using an older version.
 
-Use ordinary Markdown for headings, prose, findings, emphasis, lists, links and dividers. Headings provide sections. Design is built in; do not add custom CSS, raw HTML or framework components. Filters, maps, image/sparkline cells and executable/custom components are future capabilities, not supported syntax.
+Use ordinary Markdown for headings, prose, findings, emphasis, lists, links and dividers. Headings provide sections. Design is built in; do not add custom CSS, raw HTML or framework components. Image/sparkline column kinds require 0.3.0 or newer; check the installed CLI version and schema. Filters, maps, subtotals and executable/custom components remain future capabilities.
 
 ## Author prepared content
 
@@ -43,10 +43,10 @@ An overview of the prepared dataset, its period and relevant findings.
 
 Literal attributes are quoted strings, decoded by the component schema. `::` is a leaf; `:::` encloses a container. Close every container explicitly. Use a longer outer fence (`::::grid`) when placing another container, such as a table, inside it. Put components at the document root or in allowed component containers, not inline or inside lists/blockquotes. `column` belongs only inside a table. A plain `::table{data="./file.json"}` infers all fields; explicit columns select/order/format fields and exclude unused columns from export.
 
-- Datasets are JSON arrays of flat scalar records. Paths resolve from the Markdown file's directory. Keep them there or in subdirectories; remote, hidden, absolute and outside-root/symlink paths are rejected.
+- Datasets are JSON arrays of flat scalar records, except explicitly declared table sparkline fields. Paths resolve from the Markdown file's directory. Keep them there or in subdirectories; remote, hidden, absolute and outside-root/symlink paths are rejected.
 - Chart fields are literal keys. Charts do not aggregate, join or sort. Prepare a distinct category per bar; date/number x values must be unique and increasing. `xType="date"` accepts real `YYYY-MM-DD` dates or timestamps with an explicit zone. Dates are displayed in UTC.
 - y values are finite JSON numbers. Line/area nulls create gaps; bar nulls are invalid. Missing fields are errors. Empty arrays produce an explicit no-data state and a warning.
-- Table records have consistent keys and non-null types per column. Scalar values stay text; no HTML cell templates. Sorting uses raw values. Use a smaller prepared summary if validation reports table/point limits; the engine never truncates silently.
+- Table records have consistent keys and non-null types per column. Scalar values stay text; rich cells use explicit column kinds, never HTML templates. Sorting uses raw values. Use a smaller prepared summary if validation reports table/point limits; the engine never truncates silently.
 - Numeric formats are `number`, `percent`, `percentage-points` and `currency:GBP` (validated ISO code). Percent uses ratios (`0.12` → 12%); percentage-points uses point values (`0.8` → 0.8 pt); currency uses major units. Whole currency amounts omit `.00`; nonzero cents retain two decimal places. Formatting uses `en-GB`.
 - Metrics, comparisons and business sentiment are supplied by the agent. An increase is not automatically positive. Comparison direction and sentiment are independent; both require comparison text when explicitly supplied. Numeric table changes can declare `higher-is-better` or `lower-is-better` semantics.
 - Include data period, provenance and limitations in the prose where they help readers assess the report. Do not invent findings or imply filters/refresh that the file does not provide.
@@ -63,6 +63,23 @@ Literal attributes are quoted strings, decoded by the component schema. `::` is
 - Funnel stage names are unique nonblank strings, with at most 20 stages in source order. Each stage can have its own denominator; explain that choice in prose. Status values are `on-target`, `below-target`, `at-risk` or `neutral`. Omit the status mapping for neutral styling; the engine never infers business status. All mapped fields must differ.
 - Use the full-value data disclosures to check counts behind compact funnel labels. Both components retain readable HTML data without JavaScript. Keep the denominator of any nearby conversion KPI explicit when it differs from the funnel baseline.
 
+## Rich tables (0.3.0 or newer)
+
+```markdown
+:::table{data="./products.json" title="Products"}
+::column{field="image" kind="image" alt="description" label="Preview"}
+::column{field="product" label="Product"}
+::column{field="weekly_orders" kind="sparkline" sortBy="last_week" label="Weekly orders"}
+:::
+```
+
+- Omitted `kind` means scalar. Images require an `alt` field containing a nonblank string for each non-null image; null image cells may have null alternatives. Image fields contain a local static PNG/JPEG path or null, resolved from the Markdown directory. Do not supply SVG, GIF/WebP, remote/data URLs or absolute/hidden/outside-root paths. The display box is 64 × 48; prepare images within the schema's byte/dimension/reference limits.
+- Each unique image is embedded once. Its complete original bytes and metadata are readable by recipients; prepare assets for that disclosure. Alternatives are text, not markup. No image styling or numeric-format properties are supported.
+- Sparkline fields contain at most 64 finite numbers/nulls or null. Only explicitly declared sparkline fields may contain sequences. Use a separate flat dataset for a chart or an inferred/scalar table. Nested objects/arrays and numeric strings are invalid; rows retain consistent keys.
+- Sparkline x positions follow sample order. All rows in the same column share its observed min/max y scale. Nulls are gaps; last-sample labels remain missing when the final sample is null. Empty/all-null series show no invented values. Use `format` for numeric labels; sign/sentiment settings apply only to scalar columns.
+- Rich columns are unsortable unless `sortBy` names a separate scalar field with consistent non-null types. Prepare any sort key explicitly, such as `last_week`; it is readable in the export. The engine does not compare arrays or derive a total/trend. Scalar columns keep their existing raw-value sort.
+- Check image alternatives, line gaps/shared scale, keyboard value disclosures, row sorting, both themes and narrow table scrolling. Images/sparklines remain visible without JavaScript. The fictional catalogue example demonstrates this syntax.
+
 ## Validate, preview and export
 
 ```bash
@@ -71,7 +88,7 @@ npx plotleaf dev report.md --no-open
 npx plotleaf build report.md --out ./report.html
 ```
 
-Repair diagnostics using their code, one-based source location, message and hint, then validate again. Preview watches Markdown and referenced JSON; an invalid edit displays diagnostics and recovers after repair. Omit `--no-open` to open a browser. No backend/account is required.
+Repair diagnostics using their code, one-based source location, message and hint, then validate again. Preview watches Markdown, referenced JSON and local table images; an invalid edit displays diagnostics and recovers after repair. Omit `--no-open` to open a browser. No backend/account is required.
 
 Export is one self-contained interactive HTML file. Check it after copying it away from sources and disabling networking. Charts require JavaScript; prose, metrics, tables and native chart-data disclosures remain readable without it. All displayed/embedded values are readable by recipients: collapsing a table or hiding a field visually is not redaction. Prepare sensitive data before rendering; explicit-column tables and chart field projection help avoid exporting unused fields.