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

package/css/uncharted.css

@@ -313,6 +313,11 @@
   background-color: var(--color);
 }
 
+.chart-stacked-bar .bar-fill[title]:hover {
+  filter: brightness(1.15);
+  cursor: default;
+}
+
 .chart-stacked-bar .bar-value {
   display: flex;
   align-items: center;
@@ -374,6 +379,11 @@
   background-color: var(--color);
 }
 
+.chart-stacked-column .column-segment[title]:hover {
+  filter: brightness(1.15);
+  cursor: default;
+}
+
 .chart-stacked-column .column-labels {
   grid-row: 2;
   display: flex;
@@ -604,7 +614,7 @@
 }
 
 :is(.chart-dot, .chart-line) .dot[title]:hover {
-  transform: translate(-50%, 50%) scale(1.3);
+  transform: translate(-50%, 50%) scale(1.3) !important;
   z-index: 1;
 }
 
@@ -742,7 +752,7 @@
 }
 
 .chart-bubble .dot[title]:hover {
-  transform: translate(-50%, 50%) scale(1.3);
+  transform: translate(-50%, 50%) scale(1.3) !important;
   z-index: 1;
 }
 
@@ -932,7 +942,7 @@
 }
 
 .chart-scatter .dot[title]:hover {
-  transform: translate(-50%, 50%) scale(1.3);
+  transform: translate(-50%, 50%) scale(1.3) !important;
   z-index: 1;
 }
 
@@ -1038,7 +1048,7 @@
 }
 
 .chart-timeseries .dot[title]:hover {
-  transform: translate(-50%, 50%) scale(1.3);
+  transform: translate(-50%, 50%) scale(1.3) !important;
   z-index: 1;
 }
 
@@ -1051,7 +1061,7 @@
 
 :is(.chart-line, .chart-timeseries).no-dots .dot:hover {
   background-color: var(--color);
-  transform: translate(-50%, 50%) scale(1.3);
+  transform: translate(-50%, 50%) scale(1.3) !important;
   z-index: 1;
 }
 

package/eleventy.config.js

@@ -4,6 +4,15 @@ 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 {
+  normalizeImageOptions,
+  queueChartForImage,
+  processQueue,
+  getImageUrl,
+  getStoredImageUrl,
+  shouldSkipInDevMode,
+  clearImageUrls
+} from './src/image/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -18,6 +27,14 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * @param {boolean} [options.dataPassthrough] - Copy CSV files to public dataPath (default: false)
  * @param {string} [options.dataPath] - Public URL path for CSV files (default: '/data/')
  * @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 {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)
+ * @param {string} [options.image.background='#ffffff'] - Default background color
+ * @param {boolean} [options.image.skipDev=true] - Skip image generation during --serve/--watch
  */
 export default function(eleventyConfig, options = {}) {
   // Directory config from Eleventy (populated by eleventy.directories event)
@@ -49,6 +66,13 @@ export default function(eleventyConfig, options = {}) {
   const dataPath = options.dataPath || '/data/';
   const globalDownloadData = options.downloadData ?? false;
 
+  // Image generation options
+  const imageOptions = normalizeImageOptions(options.image);
+  const skipImageGeneration = shouldSkipInDevMode(imageOptions);
+
+  // Clear image URLs at start of each build
+  clearImageUrls();
+
   // Automatic CSS handling
   if (injectCss) {
     const cssSource = path.join(__dirname, 'css/uncharted.css');
@@ -153,7 +177,8 @@ export default function(eleventyConfig, options = {}) {
     // Resolve column mappings
     const columns = resolveColumns(normalizedConfig, data, chartType);
 
-    return renderer({
+    // Render the chart HTML
+    let chartHtml = renderer({
       ...normalizedConfig,
       id: chartId,
       data,
@@ -162,5 +187,71 @@ export default function(eleventyConfig, options = {}) {
       downloadDataUrl,
       _columns: columns
     });
+
+    // Add aria-label for accessibility
+    const altText = chartConfig.alt || chartConfig.title || chartId;
+    chartHtml = chartHtml.replace(
+      /^<figure([^>]*class="chart[^"]*")/,
+      `<figure aria-label="${altText}"$1`
+    );
+
+    // Handle image generation
+    const chartImageEnabled = chartConfig.image?.enabled ?? imageOptions.enabled;
+    if (chartImageEnabled && !skipImageGeneration && eleventyDirs?.output) {
+      // Queue chart for image generation
+      queueChartForImage(chartId, chartHtml, chartConfig, imageOptions, eleventyDirs.output);
+
+      // Add data-chart-image and data-chart-alt attributes to the figure element
+      const imageUrl = getImageUrl(chartId, chartConfig, imageOptions);
+      chartHtml = chartHtml.replace(
+        /^<figure([^>]*aria-label="[^"]*"[^>]*class="chart[^"]*")/,
+        `<figure$1 data-chart-image="${imageUrl}" data-chart-alt="${altText}"`
+      );
+    }
+
+    return chartHtml;
+  });
+
+  // Shortcode to get chart image URL
+  eleventyConfig.addShortcode('chartImageUrl', function(chartId) {
+    // First check if we have a stored URL from queueing
+    const storedUrl = getStoredImageUrl(chartId);
+    if (storedUrl) return storedUrl;
+
+    // Otherwise, look up chart config and compute URL
+    const pageCharts = this.page?.charts;
+    const globalCharts = this.charts || this.ctx?.charts;
+    const chartConfig = pageCharts?.[chartId] || globalCharts?.[chartId];
+
+    if (!chartConfig) return '';
+
+    return getImageUrl(chartId, chartConfig, imageOptions);
+  });
+
+  // Filter to replace chart HTML with image tags (for RSS feeds)
+  eleventyConfig.addFilter('chartToImage', function(content, baseUrl = '') {
+    if (!content) return content;
+
+    // Find chart figures with data-chart-image and data-chart-alt attributes and replace with img tags
+    return content.replace(
+      /<figure[^>]*class="chart[^"]*"[^>]*data-chart-image="([^"]+)"[^>]*data-chart-alt="([^"]+)"[^>]*>[\s\S]*?<\/figure>/g,
+      (match, src, alt) => `<img src="${baseUrl}${src}" alt="${alt}">`
+    );
+  });
+
+  // Process image queue after build completes
+  eleventyConfig.on('eleventy.after', async () => {
+    if (!imageOptions.enabled || skipImageGeneration) return;
+
+    const results = await processQueue(imageOptions);
+
+    if (results.skipped) return;
+
+    if (results.success.length > 0) {
+      console.log(`[uncharted] Generated ${results.success.length} chart image(s)`);
+    }
+    if (results.failed.length > 0) {
+      console.warn(`[uncharted] Failed to generate ${results.failed.length} chart image(s)`);
+    }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "0.9.0",
+  "version": "1.0.0-beta.1",
   "description": "An Eleventy plugin that renders CSS-based charts from CSV data using shortcodes",
   "main": "eleventy.config.js",
   "type": "module",
@@ -32,7 +32,13 @@
     "url": "https://github.com/slunsford/uncharted/issues"
   },
   "peerDependencies": {
-    "@11ty/eleventy": ">=2.0.0 || >=4.0.0-0"
+    "@11ty/eleventy": ">=2.0.0 || >=4.0.0-0",
+    "puppeteer": ">=21.0.0"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@11ty/eleventy": "^3.0.0 || ^4.0.0-0"

package/src/image/index.js

@@ -0,0 +1,205 @@
+/**
+ * Chart Image Generation Module
+ * Orchestrates PNG image generation for charts.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { queueChart, getAndClearQueue, hasQueuedCharts, getQueueSize, clearQueue } from './queue.js';
+import { renderCharts, isPuppeteerAvailable } from './renderer.js';
+
+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 {number} [width=800] - Default image width
+ * @property {number} [height=400] - Default image height
+ * @property {number} [scale=2] - Device scale factor (2 for retina)
+ * @property {string} [background='#ffffff'] - Default background color
+ * @property {string[]} [stylesheets=[]] - External stylesheet URLs to include (e.g., Font Awesome)
+ * @property {boolean} [skipDev=true] - Skip generation during --serve/--watch
+ */
+
+/** @type {Map<string, string>} Chart ID -> Image URL */
+const imageUrls = new Map();
+
+/**
+ * Default image options.
+ * @type {ImageOptions}
+ */
+const defaultOptions = {
+  enabled: false,
+  outputDir: '/images/charts/',
+  width: 800,
+  height: 400,
+  scale: 2,
+  background: '#ffffff',
+  stylesheets: [],
+  skipDev: true
+};
+
+/**
+ * Normalize image options by merging defaults.
+ * @param {Partial<ImageOptions>} options
+ * @returns {ImageOptions}
+ */
+export function normalizeImageOptions(options = {}) {
+  return { ...defaultOptions, ...options };
+}
+
+/**
+ * Get the output path for a chart image.
+ * @param {string} chartId - Chart identifier
+ * @param {Object} chartConfig - Chart configuration
+ * @param {ImageOptions} globalOptions - Global image options
+ * @param {string} outputDir - Eleventy output directory
+ * @returns {string} Absolute file path for the image
+ */
+export function getImageOutputPath(chartId, chartConfig, globalOptions, outputDir) {
+  const imageConfig = chartConfig.image || {};
+  const filename = imageConfig.filename || chartId;
+  const dir = globalOptions.outputDir.replace(/^\//, '').replace(/\/$/, '');
+
+  return path.join(outputDir, dir, `${filename}.png`);
+}
+
+/**
+ * Get the URL for a chart image.
+ * @param {string} chartId - Chart identifier
+ * @param {Object} chartConfig - Chart configuration
+ * @param {ImageOptions} globalOptions - Global image options
+ * @returns {string} URL path to the image
+ */
+export function getImageUrl(chartId, chartConfig, globalOptions) {
+  const imageConfig = chartConfig.image || {};
+  const filename = imageConfig.filename || chartId;
+  const dir = globalOptions.outputDir.endsWith('/')
+    ? globalOptions.outputDir
+    : globalOptions.outputDir + '/';
+
+  return `${dir}${filename}.png`;
+}
+
+/**
+ * Store the image URL for a chart (for shortcode lookup).
+ * @param {string} chartId
+ * @param {string} url
+ */
+export function storeImageUrl(chartId, url) {
+  imageUrls.set(chartId, url);
+}
+
+/**
+ * Get the stored image URL for a chart.
+ * @param {string} chartId
+ * @returns {string|null}
+ */
+export function getStoredImageUrl(chartId) {
+  return imageUrls.get(chartId) || null;
+}
+
+/**
+ * Clear all stored image URLs.
+ */
+export function clearImageUrls() {
+  imageUrls.clear();
+}
+
+/**
+ * Check if image generation should be skipped (dev mode).
+ * @param {ImageOptions} options
+ * @returns {boolean}
+ */
+export function shouldSkipInDevMode(options) {
+  if (!options.skipDev) return false;
+
+  // Check for common dev mode indicators
+  const args = process.argv.join(' ').toLowerCase();
+  return args.includes('--serve') || args.includes('--watch');
+}
+
+/**
+ * Queue a chart for image generation.
+ * @param {string} chartId - Chart identifier
+ * @param {string} chartHtml - Rendered chart HTML
+ * @param {Object} chartConfig - Chart configuration
+ * @param {ImageOptions} globalOptions - Global image options
+ * @param {string} outputDir - Eleventy output directory
+ */
+export function queueChartForImage(chartId, chartHtml, chartConfig, globalOptions, outputDir) {
+  const imageConfig = chartConfig.image || {};
+
+  // Merge global and per-chart config
+  const config = {
+    width: imageConfig.width || globalOptions.width,
+    height: imageConfig.height || globalOptions.height,
+    scale: imageConfig.scale || globalOptions.scale,
+    background: imageConfig.background || globalOptions.background,
+    filename: imageConfig.filename || chartId
+  };
+
+  const outputPath = getImageOutputPath(chartId, chartConfig, globalOptions, outputDir);
+  const url = getImageUrl(chartId, chartConfig, globalOptions);
+
+  // Store URL for shortcode lookup
+  storeImageUrl(chartId, url);
+
+  // Add to queue
+  queueChart(chartId, {
+    id: chartId,
+    html: chartHtml,
+    config,
+    outputPath
+  });
+}
+
+/**
+ * Process the chart image queue and generate all images.
+ * @param {ImageOptions} options - Image options
+ * @returns {Promise<{success: string[], failed: string[], skipped: boolean}>}
+ */
+export async function processQueue(options) {
+  if (!hasQueuedCharts()) {
+    return { success: [], failed: [], skipped: false };
+  }
+
+  // Check if Puppeteer is available
+  const available = await isPuppeteerAvailable();
+  if (!available) {
+    const count = getQueueSize();
+    clearQueue();
+    console.warn(`[uncharted] Puppeteer not installed. Skipped ${count} chart image(s).`);
+    return { success: [], failed: [], skipped: true };
+  }
+
+  // Load CSS
+  const cssPath = path.join(__dirname, '../../css/uncharted.css');
+  let css = '';
+  try {
+    css = fs.readFileSync(cssPath, 'utf-8');
+  } catch (err) {
+    console.error('[uncharted] Failed to load CSS for image rendering:', err.message);
+    clearQueue();
+    return { success: [], failed: [], skipped: true };
+  }
+
+  // Get charts and clear queue
+  const charts = getAndClearQueue();
+
+  // Render all charts
+  const results = await renderCharts(charts, css, {
+    width: options.width,
+    height: options.height,
+    scale: options.scale,
+    background: options.background,
+    stylesheets: options.stylesheets
+  });
+
+  return { ...results, skipped: false };
+}
+
+// Re-export queue utilities for direct access if needed
+export { hasQueuedCharts, getQueueSize, clearQueue };

package/src/image/queue.js

@@ -0,0 +1,62 @@
+/**
+ * Chart Image Queue
+ * Tracks charts that need PNG image generation during the build.
+ */
+
+/** @type {Map<string, ChartImageData>} */
+const queue = new Map();
+
+/**
+ * @typedef {Object} ChartImageData
+ * @property {string} id - Chart identifier
+ * @property {string} html - Rendered chart HTML
+ * @property {Object} config - Image configuration
+ * @property {number} [config.width] - Image width in pixels
+ * @property {number} [config.height] - Image height in pixels
+ * @property {number} [config.scale] - Device scale factor (e.g., 2 for retina)
+ * @property {string} [config.background] - Background color
+ * @property {string} [config.filename] - Custom filename (without extension)
+ * @property {string} outputPath - Output file path for the image
+ */
+
+/**
+ * Add a chart to the image generation queue.
+ * @param {string} id - Chart identifier
+ * @param {ChartImageData} data - Chart data for image generation
+ */
+export function queueChart(id, data) {
+  queue.set(id, data);
+}
+
+/**
+ * Get all queued charts and clear the queue.
+ * @returns {ChartImageData[]} Array of queued chart data
+ */
+export function getAndClearQueue() {
+  const charts = Array.from(queue.values());
+  queue.clear();
+  return charts;
+}
+
+/**
+ * Check if there are any charts queued for image generation.
+ * @returns {boolean}
+ */
+export function hasQueuedCharts() {
+  return queue.size > 0;
+}
+
+/**
+ * Get the number of queued charts.
+ * @returns {number}
+ */
+export function getQueueSize() {
+  return queue.size;
+}
+
+/**
+ * Clear the queue without returning charts.
+ */
+export function clearQueue() {
+  queue.clear();
+}

package/src/image/renderer.js

@@ -0,0 +1,277 @@
+/**
+ * Chart Image Renderer
+ * Uses Puppeteer to render charts as PNG images.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+let puppeteer = null;
+
+/**
+ * Attempt to load Puppeteer dynamically.
+ * Tries multiple resolution strategies to find Puppeteer in the consuming project.
+ * @returns {Promise<Object|null>} Puppeteer module or null if not available
+ */
+async function loadPuppeteer() {
+  if (puppeteer !== null) {
+    return puppeteer;
+  }
+
+  // Try to resolve from the current working directory (consuming project)
+  const require = createRequire(path.join(process.cwd(), 'package.json'));
+
+  try {
+    // Use require.resolve to find puppeteer in the project's node_modules
+    const puppeteerPath = require.resolve('puppeteer');
+    puppeteer = await import(puppeteerPath);
+    return puppeteer;
+  } catch (e) {
+    // Fallback: try direct import (works if puppeteer is in plugin's deps)
+    try {
+      puppeteer = await import('puppeteer');
+      return puppeteer;
+    } catch (e2) {
+      puppeteer = false; // Mark as unavailable
+      return null;
+    }
+  }
+}
+
+/**
+ * Check if Puppeteer is available.
+ * @returns {Promise<boolean>}
+ */
+export async function isPuppeteerAvailable() {
+  const pptr = await loadPuppeteer();
+  return pptr !== null && pptr !== false;
+}
+
+/**
+ * Check if a string is a URL (vs a local file path).
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isUrl(str) {
+  return str.startsWith('http://') || str.startsWith('https://') || str.startsWith('//');
+}
+
+/**
+ * Load stylesheets - URLs become link tags, local files stay as relative paths.
+ * Since we render from a temp file in the project root, relative paths work.
+ * @param {string[]} stylesheets - Array of URLs or file paths
+ * @returns {{links: string, inlined: string}}
+ */
+function loadStylesheets(stylesheets) {
+  const links = [];
+  const inlined = [];
+
+  for (const stylesheet of stylesheets) {
+    if (isUrl(stylesheet)) {
+      links.push(`  <link rel="stylesheet" href="${stylesheet}">`);
+    } else {
+      // Local file - keep relative path (works because temp HTML is in project root)
+      const filePath = path.resolve(process.cwd(), stylesheet);
+      if (fs.existsSync(filePath)) {
+        links.push(`  <link rel="stylesheet" href="${stylesheet}">`);
+      } else {
+        console.warn(`[uncharted] Could not find stylesheet "${stylesheet}"`);
+      }
+    }
+  }
+
+  return {
+    links: links.join('\n'),
+    inlined: inlined.join('\n\n')
+  };
+}
+
+/**
+ * Build a standalone HTML document for chart rendering.
+ * @param {string} chartHtml - The rendered chart HTML
+ * @param {string} css - The chart CSS
+ * @param {Object} options - Rendering options
+ * @param {string} [options.background] - Background color
+ * @param {string[]} [options.stylesheets] - URLs or local file paths for additional stylesheets
+ * @param {number} [options.height] - Image height in pixels
+ * @returns {string} Complete HTML document
+ */
+function buildHtmlDocument(chartHtml, css, options = {}) {
+  const background = options.background || '#ffffff';
+  const stylesheets = options.stylesheets || [];
+  const height = options.height || 400;
+
+  // Remove chart-animate class - animations don't make sense in static images
+  chartHtml = chartHtml.replace(/\bchart-animate\b/g, '');
+
+  // Load stylesheets (URLs as links, local files inlined)
+  const { links: stylesheetLinks, inlined: inlinedStyles } = loadStylesheets(stylesheets);
+
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+${stylesheetLinks}
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body {
+      background: ${background};
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    }
+    body {
+      height: 100vh;
+      padding: 1rem;
+    }
+    .chart-container {
+      width: 100%;
+      height: 100%;
+      display: flex;
+      flex-direction: column;
+    }
+    .chart-container > .chart:not(.chart-donut):not(.chart-stacked-bar):not(.chart-sankey) {
+      flex: 1;
+      min-height: 0;
+      --chart-height: 100%;
+    }
+    .chart-container > .chart:not(.chart-donut):not(.chart-stacked-bar):not(.chart-sankey) .chart-body {
+      flex: 1;
+      min-height: 0;
+    }
+    /* Stacked bar: use natural height based on row count */
+    .chart-stacked-bar .chart-bars {
+      grid-auto-rows: auto;
+    }
+    /* Donut: just center it, don't stretch */
+    .chart-container:has(.chart-donut) {
+      justify-content: center;
+    }
+    /* Sankey: use natural height from --height-scale */
+    ${css}
+
+    /* Additional stylesheets (inlined) */
+    ${inlinedStyles}
+
+    /* Hide download link in images */
+    .chart-download { display: none; }
+  </style>
+</head>
+<body>
+  <div class="chart-container">
+    ${chartHtml}
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Render a single chart to PNG using an existing Puppeteer page.
+ * @param {Object} page - Puppeteer page instance
+ * @param {Object} chart - Chart data
+ * @param {string} chart.html - Chart HTML
+ * @param {Object} chart.config - Image configuration
+ * @param {string} chart.outputPath - Output file path
+ * @param {string} css - Chart CSS content
+ * @param {Object} defaults - Default image options
+ * @returns {Promise<void>}
+ */
+async function renderChart(page, chart, css, defaults) {
+  const config = { ...defaults, ...chart.config };
+  const width = config.width || 800;
+  const height = config.height || 400;
+  const scale = config.scale || 2;
+  const background = config.background || '#ffffff';
+  const stylesheets = config.stylesheets || defaults.stylesheets || [];
+
+  // Set viewport
+  await page.setViewport({
+    width,
+    height,
+    deviceScaleFactor: scale
+  });
+
+  // Build HTML content
+  const html = buildHtmlDocument(chart.html, css, { background, stylesheets, height });
+
+  // Write to temp file so relative paths in CSS resolve correctly
+  const tempHtmlPath = path.join(process.cwd(), `.uncharted-temp-${chart.id}.html`);
+  fs.writeFileSync(tempHtmlPath, html);
+
+  try {
+    // Navigate to the temp file
+    await page.goto(`file://${tempHtmlPath}`, { waitUntil: 'load' });
+    if (stylesheets.length > 0) {
+      // Wait for fonts to load
+      await page.evaluateHandle('document.fonts.ready');
+    }
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(chart.outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Take screenshot
+    await page.screenshot({
+      path: chart.outputPath,
+      type: 'png',
+      omitBackground: background === 'transparent'
+    });
+  } finally {
+    // Clean up temp file
+    fs.unlinkSync(tempHtmlPath);
+  }
+}
+
+/**
+ * Render multiple charts to PNG images.
+ * @param {Object[]} charts - Array of chart data objects
+ * @param {string} css - Chart CSS content
+ * @param {Object} options - Rendering options
+ * @param {number} [options.width] - Default image width
+ * @param {number} [options.height] - Default image height
+ * @param {number} [options.scale] - Default device scale factor
+ * @param {string} [options.background] - Default background color
+ * @param {string[]} [options.stylesheets] - External stylesheet URLs to include
+ * @returns {Promise<{success: string[], failed: string[]}>} Results
+ */
+export async function renderCharts(charts, css, options = {}) {
+  const pptr = await loadPuppeteer();
+
+  if (!pptr) {
+    console.warn('[uncharted] Puppeteer not installed. Skipping image generation.');
+    console.warn('[uncharted] Install puppeteer to enable: npm install puppeteer');
+    return { success: [], failed: charts.map(c => c.id) };
+  }
+
+  const results = { success: [], failed: [] };
+
+  let browser;
+  try {
+    browser = await pptr.default.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--allow-file-access-from-files']
+    });
+
+    const page = await browser.newPage();
+
+    for (const chart of charts) {
+      try {
+        await renderChart(page, chart, css, options);
+        results.success.push(chart.id);
+      } catch (err) {
+        console.error(`[uncharted] Failed to render image for chart "${chart.id}":`, err.message);
+        results.failed.push(chart.id);
+      }
+    }
+  } catch (err) {
+    console.error('[uncharted] Failed to launch browser:', err.message);
+    return { success: [], failed: charts.map(c => c.id) };
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+
+  return results;
+}

package/src/renderers/bubble.js

@@ -177,14 +177,13 @@ export function renderBubble(config) {
       const icon = getSeriesIcon(dot.series);
       const iconClass = icon ? ' has-icon' : '';
 
-      // Build tooltip
-      let tooltipText = `${category}: ${formatNumber(dot.y, fmtY) || dot.y}`;
-      if (seriesKey && dot.series !== 'default') {
-        tooltipText = `${dot.series} - ${tooltipText}`;
-      }
+      // Build tooltip: series: value, plus size if available
+      const fmtYVal = formatNumber(dot.y, fmtY) || dot.y;
+      let tooltipText = seriesList.length > 1 ? `${dot.series}: ${fmtYVal}` : `${fmtYVal}`;
       if (sizeKey && dot.rawSize !== null) {
         const fmtSizeVal = formatNumber(dot.rawSize, fmtSize) || dot.rawSize;
-        tooltipText += ` [${fmtSizeVal}]`;
+        const sizeLabel = sizeTitle || sizeKey;
+        tooltipText += ` — ${sizeLabel}: ${fmtSizeVal}`;
       }
 
       // Build style string with size scale

package/src/renderers/dot.js

@@ -22,7 +22,7 @@ export function renderDot(config) {
   if (chartType === 'dot') {
     console.warn(
       '[uncharted] Chart type "dot" is deprecated. ' +
-      'Migrate to "line" with showLines: false, or use "bubble" for sized dots.'
+      'Migrate to "line" with lines: false, or use "bubble" for sized dots.'
     );
   }
 

package/src/renderers/line.js

@@ -1,6 +1,6 @@
 import { renderDot } from './dot.js';
 
 export function renderLine(config) {
-  const connectDots = config.showLines !== false; // default true
+  const connectDots = config.lines !== false; // default true
   return renderDot({ ...config, connectDots, chartType: 'line' });
 }

package/src/renderers/scatter.js

@@ -169,12 +169,22 @@ export function renderScatter(config) {
     const icon = getSeriesIcon(dot.series);
     const iconClass = icon ? ' has-icon' : '';
 
-    // Build tooltip with optional size value
-    let tooltipText = dot.label ? `${dot.label}: (${fmtXVal}, ${fmtYVal})` : `(${fmtXVal}, ${fmtYVal})`;
+    // Build tooltip with series, axis titles, and optional size
+    let tooltipParts = [];
+    if (dot.label && seriesList.length > 1) {
+      tooltipParts.push(`${dot.label} (${dot.series})`);
+    } else if (dot.label) {
+      tooltipParts.push(dot.label);
+    } else if (seriesList.length > 1) {
+      tooltipParts.push(dot.series);
+    }
+    tooltipParts.push(`${xAxisTitle}: ${fmtXVal}, ${yAxisTitle}: ${fmtYVal}`);
     if (sizeKey && dot.rawSize !== null) {
       const fmtSizeVal = formatNumber(dot.rawSize, fmtSize) || dot.rawSize;
-      tooltipText += ` [${fmtSizeVal}]`;
+      const sizeLabel = sizeTitle || sizeKey;
+      tooltipParts.push(`${sizeLabel}: ${fmtSizeVal}`);
     }
+    const tooltipText = tooltipParts.join(' — ');
 
     // Build style string with optional size scale
     let styleStr = `--dot-index: ${i}; --x: ${xPct.toFixed(2)}%; --value: ${yPct.toFixed(2)}%`;

package/src/renderers/timeseries.js

@@ -176,8 +176,10 @@ function formatXLabel(value, isDate, range) {
     return `${month}<br>${year}`;
   }
 
-  // Days/weeks range: show MMM D
-  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+  // Days/weeks range: show D MMM
+  const day = date.getDate();
+  const month = date.toLocaleDateString('en-US', { month: 'short' });
+  return `${day} ${month}`;
 }
 
 /**