eleventy-plugin-uncharted 1.0.0-beta.1 → 1.0.0-beta.3

package/eleventy.config.js

@@ -4,6 +4,7 @@ import { renderers } from './src/renderers/index.js';
 import { loadCSV } from './src/csv.js';
 import { normalizeConfig } from './src/config.js';
 import { resolveColumns } from './src/columns.js';
+import { validateChartType, checkDeprecatedOptions } from './src/deprecation.js';
 import {
   normalizeImageOptions,
   queueChartForImage,
@@ -29,7 +30,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * @param {boolean|string} [options.downloadData] - Enable download links globally (individual charts can override)
  * @param {Object} [options.image] - Image generation options
  * @param {boolean} [options.image.enabled=false] - Enable PNG image generation
- * @param {string} [options.image.outputDir='/images/charts/'] - Output directory for images
+ * @param {string} [options.image.outputDir='/images/charts/'] - Output directory for images (URL path)
+ * @param {string} [options.image.cacheDir] - Source directory for cached images (enables caching when set)
  * @param {number} [options.image.width=800] - Default image width in pixels
  * @param {number} [options.image.height=400] - Default image height in pixels
  * @param {number} [options.image.scale=2] - Device scale factor (2 for retina)
@@ -68,7 +70,8 @@ export default function(eleventyConfig, options = {}) {
 
   // Image generation options
   const imageOptions = normalizeImageOptions(options.image);
-  const skipImageGeneration = shouldSkipInDevMode(imageOptions);
+  const skipImageGeneration = shouldSkipInDevMode(imageOptions) ||
+    process.argv.includes('--skip-images');
 
   // Clear image URLs at start of each build
   clearImageUrls();
@@ -122,6 +125,15 @@ export default function(eleventyConfig, options = {}) {
     });
   }
 
+  // Image cache passthrough - copies cached images to output
+  if (imageOptions.cacheDir) {
+    const cacheDirClean = imageOptions.cacheDir.replace(/^\/|\/$/g, '');
+    const outputDirClean = imageOptions.outputDir.replace(/^\/|\/$/g, '');
+    eleventyConfig.addPassthroughCopy({
+      [cacheDirClean]: outputDirClean
+    });
+  }
+
   eleventyConfig.addShortcode('chart', function(chartId) {
     // Get resolved data directory (from Eleventy config or plugin options)
     const resolvedDataDir = getDataDir();
@@ -145,11 +157,21 @@ export default function(eleventyConfig, options = {}) {
       return `<!-- Chart "${chartId}" has no type specified -->`;
     }
 
+    // Check for deprecated chart type (ERROR - prevents rendering)
+    const typeError = validateChartType(chartType, chartId);
+    if (typeError) {
+      console.error(`[uncharted] ${typeError}`);
+      return `<!-- ${typeError} -->`;
+    }
+
     const renderer = renderers[chartType];
     if (!renderer) {
       return `<!-- Unknown chart type "${chartType}" for chart "${chartId}" -->`;
     }
 
+    // Check for deprecated config options (WARNING - chart renders but option ignored)
+    checkDeprecatedOptions(chartConfig, chartId);
+
     // Load data from CSV file or use inline data
     let data = chartConfig.data;
     if (chartConfig.file && !data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "An Eleventy plugin that renders CSS-based charts from CSV data using shortcodes",
   "main": "eleventy.config.js",
   "type": "module",

package/src/columns.js

@@ -1,7 +1,6 @@
 /**
  * Column resolution for Uncharted
  * Handles explicit column mapping and implicit detection
- * Supports both new unified schema (x.column, y.columns) and deprecated columns key
  */
 
 import { parseAxisConfig } from './config.js';
@@ -9,13 +8,10 @@ import { parseAxisConfig } from './config.js';
 /**
  * Resolve column mappings for chart data
  *
- * New unified schema (takes precedence):
+ * New unified schema:
  * - x: { column: "month" } or x: "month"
  * - y: { columns: ["a", "b"] } or y: { columns: { a: "Label A" } }
  *
- * Deprecated schema (fallback):
- * - columns: { x: "month", y: ["a", "b"] }
- *
  * @param {Object} config - Chart configuration with optional columns mapping
  * @param {Object[]} data - Chart data array
  * @param {string} chartType - Chart type for context-aware defaults
@@ -42,7 +38,6 @@ export function resolveColumns(config, data, chartType) {
   }
 
   const keys = Object.keys(data[0]);
-  const deprecatedColumns = config.columns || {};
 
   // Helper to find column by name (case-insensitive)
   const findKey = name => keys.find(k => k.toLowerCase() === name.toLowerCase()) || null;
@@ -100,40 +95,28 @@ export function resolveColumns(config, data, chartType) {
   // Chart-type specific resolution
   if (chartType === 'bubble') {
     // Bubble charts use x (categorical), y, series, size columns
-    // Like scatter but with categorical X axis
-    // New schema: x.column, y.column, series.column, size.column
-    // Deprecated: columns.x, columns.y, columns.series, columns.size
+    // Schema: x.column, y.column, series.column, size.column
 
     // X column (categorical)
     if (xConfig?.columns?.length) {
       resolved.x = validateColumn('x.column', xConfig.columns[0]);
-    } else if (deprecatedColumns.x) {
-      resolved.x = validateColumn('columns.x', deprecatedColumns.x);
     }
 
     // Y column
     if (yConfig?.columns?.length) {
       resolved.y = validateColumn('y.column', yConfig.columns[0]);
-    } else if (deprecatedColumns.y) {
-      resolved.y = validateColumn('columns.y', deprecatedColumns.y);
     }
 
     // Series column (for coloring)
     if (seriesConfig?.columns?.length) {
       resolved.series = validateColumn('series.column', seriesConfig.columns[0]);
       resolved.seriesTitle = seriesConfig.title;
-    } else if (deprecatedColumns.series) {
-      resolved.series = validateColumn('columns.series', deprecatedColumns.series);
-      resolved.seriesTitle = config.legendTitle; // deprecated
     }
 
     // Size column
     if (sizeConfig?.columns?.length) {
       resolved.size = validateColumn('size.column', sizeConfig.columns[0]);
       resolved.sizeTitle = sizeConfig.title;
-    } else if (deprecatedColumns.size) {
-      resolved.size = validateColumn('columns.size', deprecatedColumns.size);
-      resolved.sizeTitle = config.sizeTitle; // deprecated
     }
 
     // Implicit detection for bubble if not explicitly specified
@@ -168,28 +151,21 @@ export function resolveColumns(config, data, chartType) {
 
   } else if (chartType === 'scatter') {
     // Scatter charts use x, y, label, series, size columns
-    // New schema: x.column, y.column, label.column, series.column, size.column
-    // Deprecated: columns.x, columns.y, columns.label, columns.series, columns.size
+    // Schema: x.column, y.column, label.column, series.column, size.column
 
     // X column
     if (xConfig?.columns?.length) {
       resolved.x = validateColumn('x.column', xConfig.columns[0]);
-    } else if (deprecatedColumns.x) {
-      resolved.x = validateColumn('columns.x', deprecatedColumns.x);
     }
 
     // Y column
     if (yConfig?.columns?.length) {
       resolved.y = validateColumn('y.column', yConfig.columns[0]);
-    } else if (deprecatedColumns.y) {
-      resolved.y = validateColumn('columns.y', deprecatedColumns.y);
     }
 
     // Label column (point identifier)
     if (labelConfig?.columns?.length) {
       resolved.label = validateColumn('label.column', labelConfig.columns[0]);
-    } else if (deprecatedColumns.label) {
-      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
     } else {
       resolved.label = keys[0];
     }
@@ -198,18 +174,12 @@ export function resolveColumns(config, data, chartType) {
     if (seriesConfig?.columns?.length) {
       resolved.series = validateColumn('series.column', seriesConfig.columns[0]);
       resolved.seriesTitle = seriesConfig.title;
-    } else if (deprecatedColumns.series) {
-      resolved.series = validateColumn('columns.series', deprecatedColumns.series);
-      resolved.seriesTitle = config.legendTitle; // deprecated
     }
 
     // Size column
     if (sizeConfig?.columns?.length) {
       resolved.size = validateColumn('size.column', sizeConfig.columns[0]);
       resolved.sizeTitle = sizeConfig.title;
-    } else if (deprecatedColumns.size) {
-      resolved.size = validateColumn('columns.size', deprecatedColumns.size);
-      resolved.sizeTitle = config.sizeTitle; // deprecated
     }
 
     // Implicit detection for scatter if not explicitly specified
@@ -236,21 +206,16 @@ export function resolveColumns(config, data, chartType) {
 
   } else if (chartType === 'sankey') {
     // Sankey charts use source, target, value columns
-    // New schema: source.column, target.column, value.column
-    // Deprecated: columns.source, columns.target, columns.value
+    // Schema: source.column, target.column, value.column
 
     if (sourceConfig?.columns?.length) {
       resolved.source = validateColumn('source.column', sourceConfig.columns[0]);
-    } else if (deprecatedColumns.source) {
-      resolved.source = validateColumn('columns.source', deprecatedColumns.source);
     } else {
       resolved.source = keys[0];
     }
 
     if (targetConfig?.columns?.length) {
       resolved.target = validateColumn('target.column', targetConfig.columns[0]);
-    } else if (deprecatedColumns.target) {
-      resolved.target = validateColumn('columns.target', deprecatedColumns.target);
     } else {
       resolved.target = keys[1];
     }
@@ -258,22 +223,17 @@ export function resolveColumns(config, data, chartType) {
     if (valueConfig?.columns?.length) {
       resolved.value = validateColumn('value.column', valueConfig.columns[0]);
       resolved.valueFormat = valueConfig.format;
-    } else if (deprecatedColumns.value) {
-      resolved.value = validateColumn('columns.value', deprecatedColumns.value);
     } else {
       resolved.value = keys[2];
     }
 
   } else if (chartType === 'donut') {
     // Donut charts use label, value columns
-    // New schema: label.column, value.column
-    // Deprecated: columns.label, columns.value (or implicit first/second columns)
+    // Schema: label.column, value.column
 
     if (labelConfig?.columns?.length) {
       resolved.label = validateColumn('label.column', labelConfig.columns[0]);
       resolved.yLabels = labelConfig.labels || {};
-    } else if (deprecatedColumns.label) {
-      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
     } else {
       resolved.label = keys[0];
     }
@@ -284,9 +244,6 @@ export function resolveColumns(config, data, chartType) {
         resolved.values = [resolved.values];
       }
       resolved.valueFormat = valueConfig.format;
-    } else if (deprecatedColumns.value) {
-      const val = validateColumn('columns.value', deprecatedColumns.value);
-      resolved.values = val ? [val] : [];
     } else {
       // Default: all columns except label
       resolved.values = keys.filter(k => k !== resolved.label);
@@ -294,14 +251,11 @@ export function resolveColumns(config, data, chartType) {
 
   } else if (chartType === 'stacked-bar') {
     // Stacked bar: y = categories (left side), x = value series (bars extend right)
-    // New schema: y.column (categories), x.columns (values with labels)
-    // Deprecated: columns.y (or label), columns.x (or y as values)
+    // Schema: y.column (categories), x.columns (values with labels)
 
     // Category column (on Y axis for stacked-bar)
     if (yConfig?.columns?.length) {
       resolved.label = validateColumn('y.column', yConfig.columns[0]);
-    } else if (deprecatedColumns.label) {
-      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
     } else {
       resolved.label = keys[0];
     }
@@ -310,25 +264,18 @@ export function resolveColumns(config, data, chartType) {
     if (xConfig?.columns?.length) {
       resolved.values = validateColumn('x.columns', xConfig.columns) || [];
       resolved.xLabels = xConfig.labels || {};
-    } else if (deprecatedColumns.y) {
-      // Deprecated: columns.y was used for value columns in stacked-bar
-      const explicitY = validateColumn('columns.y', deprecatedColumns.y);
-      resolved.values = Array.isArray(explicitY) ? explicitY : (explicitY ? [explicitY] : []);
     } else {
       // Implicit: all columns except label are values
       resolved.values = keys.filter(k => k !== resolved.label);
     }
 
   } else {
-    // Standard charts (dot, line, stacked-column): x = categories, y = multi-series values
-    // New schema: x.column (categories), y.columns (values with labels)
-    // Deprecated: columns.label (or implicit first), columns.y
+    // Standard charts (line, stacked-column): x = categories, y = multi-series values
+    // Schema: x.column (categories), y.columns (values with labels)
 
     // Label/category column (X axis)
     if (xConfig?.columns?.length) {
       resolved.label = validateColumn('x.column', xConfig.columns[0]);
-    } else if (deprecatedColumns.label) {
-      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
     } else {
       resolved.label = keys[0];
     }
@@ -337,9 +284,6 @@ export function resolveColumns(config, data, chartType) {
     if (yConfig?.columns?.length) {
       resolved.values = validateColumn('y.columns', yConfig.columns) || [];
       resolved.yLabels = yConfig.labels || {};
-    } else if (deprecatedColumns.y) {
-      const explicitY = validateColumn('columns.y', deprecatedColumns.y);
-      resolved.values = Array.isArray(explicitY) ? explicitY : (explicitY ? [explicitY] : []);
     } else {
       // Implicit: all columns except label are values
       resolved.values = keys.filter(k => k !== resolved.label);

package/src/config.js

@@ -3,58 +3,22 @@
  * Transforms various config formats into a standardized structure
  */
 
-// Deprecated keys mapping for deprecation warnings
-const DEPRECATED_KEYS = {
-  maxX: 'x.max',
-  minX: 'x.min',
-  maxY: 'y.max',
-  minY: 'y.min',
-  titleX: 'x.title',
-  titleY: 'y.title',
-  legendTitle: 'series.title',
-  sizeTitle: 'size.title',
-  rotateLabels: 'x.rotateLabels'
-};
-
-// Track which deprecation warnings have been shown to avoid spam
-const warnedConfigs = new Set();
-
-/**
- * Log a deprecation warning (once per config/key combination)
- * @param {string} chartId - Chart identifier
- * @param {string} oldKey - Deprecated key name
- * @param {string} newKey - New key path
- */
-function warnDeprecation(chartId, oldKey, newKey) {
-  const key = `${chartId}:${oldKey}`;
-  if (warnedConfigs.has(key)) return;
-  warnedConfigs.add(key);
-  console.warn(`[uncharted] Chart "${chartId}": "${oldKey}" is deprecated, use "${newKey}" instead`);
-}
-
 /**
  * Normalize chart configuration to standardized structure
  *
- * Precedence for axis properties (highest to lowest):
- * 1. x.max / y.max (new nested format)
- * 2. maxX / maxY (deprecated suffixed format)
- * 3. max (global fallback)
- *
- * Format precedence:
- * 1. x.format / y.format (new nested format)
- * 2. format.x / format.y (deprecated nested format)
- * 3. format (global fallback)
+ * Axis properties:
+ * - x.max / y.max, x.min / y.min
+ * - x.title / y.title
+ * - x.format / y.format
  *
- * Column mapping precedence:
- * 1. x.column / x.columns / y.column / y.columns (new unified format)
- * 2. columns.x / columns.y (deprecated format)
+ * Column mapping:
+ * - x.column / x.columns / y.column / y.columns
  *
- * Legend precedence:
- * 1. y.columns: { key: "Label" } or x.columns (for stacked-bar)
- * 2. legend: ["Label1", "Label2"] (deprecated)
+ * Legend:
+ * - y.columns: { key: "Label" } or x.columns (for stacked-bar)
  *
  * @param {Object} config - Raw chart configuration
- * @param {string} [chartId] - Chart ID for deprecation warnings
+ * @param {string} [chartId] - Chart ID (unused, kept for API compatibility)
  * @returns {Object} - Normalized configuration
  */
 export function normalizeConfig(config, chartId = 'unknown') {
@@ -63,26 +27,10 @@ export function normalizeConfig(config, chartId = 'unknown') {
   const normalized = { ...config };
 
   // Build x axis config
-  normalized.x = buildAxisConfig('x', config, chartId);
+  normalized.x = buildAxisConfig('x', config);
 
   // Build y axis config
-  normalized.y = buildAxisConfig('y', config, chartId);
-
-  // Warn for deprecated legend array (when used for labels, not boolean)
-  if (Array.isArray(config.legend)) {
-    warnDeprecation(chartId, 'legend (array)', 'y.columns: { key: "Label" }');
-  }
-
-  // Warn for deprecated scatter-specific keys
-  if (config.legendTitle !== undefined) {
-    warnDeprecation(chartId, 'legendTitle', 'series.title');
-  }
-  if (config.sizeTitle !== undefined) {
-    warnDeprecation(chartId, 'sizeTitle', 'size.title');
-  }
-
-  // Clean up deprecated top-level keys (keep them for backwards compat but don't pass to renderers)
-  // The renderers will use normalized.x and normalized.y instead
+  normalized.y = buildAxisConfig('y', config);
 
   return normalized;
 }
@@ -91,58 +39,22 @@ export function normalizeConfig(config, chartId = 'unknown') {
  * Build normalized axis configuration
  * @param {'x' | 'y'} axis - Axis name
  * @param {Object} config - Raw config
- * @param {string} chartId - Chart ID for warnings
  * @returns {Object} - Normalized axis config
  */
-function buildAxisConfig(axis, config, chartId) {
-  const axisUpper = axis.toUpperCase();
+function buildAxisConfig(axis, config) {
   const existingAxisConfig = config[axis] || {};
 
   // Start with existing axis config if present
   const axisConfig = { ...existingAxisConfig };
 
-  // max: x.max > maxX > max
-  if (axisConfig.max === undefined) {
-    const deprecatedKey = `max${axisUpper}`;
-    if (config[deprecatedKey] !== undefined) {
-      warnDeprecation(chartId, deprecatedKey, `${axis}.max`);
-      axisConfig.max = config[deprecatedKey];
-    } else if (config.max !== undefined) {
-      axisConfig.max = config.max;
-    }
-  }
-
-  // min: x.min > minX > min
-  if (axisConfig.min === undefined) {
-    const deprecatedKey = `min${axisUpper}`;
-    if (config[deprecatedKey] !== undefined) {
-      warnDeprecation(chartId, deprecatedKey, `${axis}.min`);
-      axisConfig.min = config[deprecatedKey];
-    } else if (config.min !== undefined) {
-      axisConfig.min = config.min;
-    }
+  // max: x.max > max (global fallback)
+  if (axisConfig.max === undefined && config.max !== undefined) {
+    axisConfig.max = config.max;
   }
 
-  // title: x.title > titleX
-  if (axisConfig.title === undefined) {
-    const deprecatedKey = `title${axisUpper}`;
-    if (config[deprecatedKey] !== undefined) {
-      warnDeprecation(chartId, deprecatedKey, `${axis}.title`);
-      axisConfig.title = config[deprecatedKey];
-    }
-  }
-
-  // format: x.format > format.x > format
-  if (axisConfig.format === undefined) {
-    const globalFormat = config.format || {};
-    if (globalFormat[axis] !== undefined) {
-      // format.x or format.y (deprecated nested format)
-      warnDeprecation(chartId, `format.${axis}`, `${axis}.format`);
-      axisConfig.format = globalFormat[axis];
-    } else if (typeof globalFormat === 'object' && !globalFormat.x && !globalFormat.y) {
-      // Global format object (no x/y nesting) - use as fallback
-      axisConfig.format = globalFormat;
-    }
+  // min: x.min > min (global fallback)
+  if (axisConfig.min === undefined && config.min !== undefined) {
+    axisConfig.min = config.min;
   }
 
   return axisConfig;
@@ -236,20 +148,10 @@ export function parseAxisConfig(axisConfig) {
 }
 
 /**
- * Get rotateLabels setting from axis config or deprecated top-level
+ * Get rotateLabels setting from axis config
  * @param {Object} config - Normalized config
- * @param {string} chartId - Chart ID for deprecation warnings
  * @returns {boolean} - Whether to rotate labels
  */
-export function getRotateLabels(config, chartId) {
-  // New schema: x.rotateLabels
-  if (config.x?.rotateLabels !== undefined) {
-    return config.x.rotateLabels;
-  }
-  // Deprecated: top-level rotateLabels
-  if (config.rotateLabels !== undefined) {
-    warnDeprecation(chartId, 'rotateLabels', 'x.rotateLabels');
-    return config.rotateLabels;
-  }
-  return false;
+export function getRotateLabels(config) {
+  return config.x?.rotateLabels ?? false;
 }

package/src/deprecation.js

@@ -0,0 +1,111 @@
+/**
+ * Deprecation validation for Uncharted
+ * Validates config for deprecated usage and logs appropriate warnings/errors
+ */
+
+// Track which deprecation warnings have been shown to avoid spam
+const warnedConfigs = new Set();
+
+/**
+ * Log a deprecation warning (once per config/key combination)
+ * @param {string} chartId - Chart identifier
+ * @param {string} oldKey - Deprecated key name
+ * @param {string} newKey - New key path
+ */
+function warnDeprecation(chartId, oldKey, newKey) {
+  const key = `${chartId}:${oldKey}`;
+  if (warnedConfigs.has(key)) return;
+  warnedConfigs.add(key);
+  console.warn(`[uncharted] Chart "${chartId}": "${oldKey}" is deprecated, use "${newKey}" instead`);
+}
+
+/**
+ * Validate chart type and return error message if deprecated
+ * @param {string} type - Chart type
+ * @param {string} chartId - Chart identifier
+ * @returns {string|null} - Error message or null if valid
+ */
+export function validateChartType(type, chartId) {
+  if (type === 'dot') {
+    return `Chart "${chartId}": type "dot" is no longer supported. Use type "line" with lines: false instead.`;
+  }
+  return null;
+}
+
+/**
+ * Check config for deprecated options and log warnings
+ * @param {Object} config - Chart configuration
+ * @param {string} chartId - Chart identifier
+ */
+export function checkDeprecatedOptions(config, chartId) {
+  if (!config) return;
+
+  // Check for deprecated axis shorthand keys
+  if (config.maxX !== undefined) {
+    warnDeprecation(chartId, 'maxX', 'x.max');
+  }
+  if (config.minX !== undefined) {
+    warnDeprecation(chartId, 'minX', 'x.min');
+  }
+  if (config.maxY !== undefined) {
+    warnDeprecation(chartId, 'maxY', 'y.max');
+  }
+  if (config.minY !== undefined) {
+    warnDeprecation(chartId, 'minY', 'y.min');
+  }
+  if (config.titleX !== undefined) {
+    warnDeprecation(chartId, 'titleX', 'x.title');
+  }
+  if (config.titleY !== undefined) {
+    warnDeprecation(chartId, 'titleY', 'y.title');
+  }
+
+  // Check for deprecated top-level rotateLabels
+  if (config.rotateLabels !== undefined) {
+    warnDeprecation(chartId, 'rotateLabels', 'x.rotateLabels');
+  }
+
+  // Check for deprecated legend array (when used for labels, not boolean)
+  if (Array.isArray(config.legend)) {
+    warnDeprecation(chartId, 'legend (array)', 'y.columns: { key: "Label" }');
+  }
+
+  // Check for deprecated scatter-specific keys
+  if (config.legendTitle !== undefined) {
+    warnDeprecation(chartId, 'legendTitle', 'series.title');
+  }
+  if (config.sizeTitle !== undefined) {
+    warnDeprecation(chartId, 'sizeTitle', 'size.title');
+  }
+
+  // Check for deprecated format.x / format.y structure
+  if (config.format && typeof config.format === 'object') {
+    if (config.format.x !== undefined) {
+      warnDeprecation(chartId, 'format.x', 'x.format');
+    }
+    if (config.format.y !== undefined) {
+      warnDeprecation(chartId, 'format.y', 'y.format');
+    }
+  }
+
+  // Check for deprecated columns.* structure
+  if (config.columns && typeof config.columns === 'object') {
+    const deprecatedColumnKeys = ['x', 'y', 'label', 'series', 'size', 'source', 'target', 'value'];
+    for (const key of deprecatedColumnKeys) {
+      if (config.columns[key] !== undefined) {
+        const newPath = key === 'label' ? 'x.column or label.column' :
+                        key === 'x' ? 'x.column' :
+                        key === 'y' ? 'y.columns' :
+                        `${key}.column`;
+        warnDeprecation(chartId, `columns.${key}`, newPath);
+      }
+    }
+  }
+}
+
+/**
+ * Clear warning cache (useful for testing)
+ */
+export function clearWarningCache() {
+  warnedConfigs.clear();
+}

package/src/image/index.js

@@ -15,6 +15,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * @typedef {Object} ImageOptions
  * @property {boolean} [enabled=false] - Enable image generation
  * @property {string} [outputDir='/images/charts/'] - Output directory for images (URL path)
+ * @property {string} [cacheDir=null] - Source directory for cached images (enables caching when set)
  * @property {number} [width=800] - Default image width
  * @property {number} [height=400] - Default image height
  * @property {number} [scale=2] - Device scale factor (2 for retina)
@@ -33,6 +34,7 @@ const imageUrls = new Map();
 const defaultOptions = {
   enabled: false,
   outputDir: '/images/charts/',
+  cacheDir: null,
   width: 800,
   height: 400,
   scale: 2,
@@ -83,6 +85,23 @@ export function getImageUrl(chartId, chartConfig, globalOptions) {
   return `${dir}${filename}.png`;
 }
 
+/**
+ * Get the cache file path for a chart image.
+ * @param {string} chartId - Chart identifier
+ * @param {Object} chartConfig - Chart configuration
+ * @param {ImageOptions} globalOptions - Global image options
+ * @returns {string|null} Absolute cache path, or null if caching disabled
+ */
+export function getCachePath(chartId, chartConfig, globalOptions) {
+  if (!globalOptions.cacheDir) return null;
+
+  const imageConfig = chartConfig.image || {};
+  const filename = imageConfig.filename || chartId;
+  const cacheDir = globalOptions.cacheDir.replace(/\/$/, '');
+
+  return path.resolve(process.cwd(), cacheDir, `${filename}.png`);
+}
+
 /**
  * Store the image URL for a chart (for shortcode lookup).
  * @param {string} chartId
@@ -143,6 +162,7 @@ export function queueChartForImage(chartId, chartHtml, chartConfig, globalOption
 
   const outputPath = getImageOutputPath(chartId, chartConfig, globalOptions, outputDir);
   const url = getImageUrl(chartId, chartConfig, globalOptions);
+  const cachePath = getCachePath(chartId, chartConfig, globalOptions);
 
   // Store URL for shortcode lookup
   storeImageUrl(chartId, url);
@@ -152,7 +172,8 @@ export function queueChartForImage(chartId, chartHtml, chartConfig, globalOption
     id: chartId,
     html: chartHtml,
     config,
-    outputPath
+    outputPath,
+    cachePath
   });
 }
 
@@ -171,7 +192,10 @@ export async function processQueue(options) {
   if (!available) {
     const count = getQueueSize();
     clearQueue();
-    console.warn(`[uncharted] Puppeteer not installed. Skipped ${count} chart image(s).`);
+    // Suppress warning if cacheDir is set (cached images will be used via passthrough)
+    if (!options.cacheDir) {
+      console.warn(`[uncharted] Puppeteer not installed. Skipped ${count} chart image(s).`);
+    }
     return { success: [], failed: [], skipped: true };
   }