@graphein/node 0.18.0 → 0.20.0

package/README.md

@@ -49,7 +49,7 @@ native bits live only in this package.
 
 ## API
 
-### `renderChart(spec, options?) → { png, report, width, height }`
+### `renderChart(spec, options?) → { png, report, spec, quality?, warnings?, fontRegistrations, width, height }`
 
 Renders `spec` and returns the PNG bytes **and** the [`RenderReport`](https://github.com/spatney/graphein/blob/main/docs/spec-reference.md#render-report)
 — `ok`, mark/series/color counts, and any clipping / overlap / contrast diagnostics. The
@@ -57,6 +57,31 @@ report is computed from the resolved model (no pixel read-back), so it's identic
 `instance.report()` in the browser. This is what lets an agent verify a chart **without a
 vision model**.
 
+Accepts `ChartSpec` **or** `DashboardSpec` (`AnySpec`), with no dashboard casts.
+The default remains one direct render, with no authoring/data repairs.
+Overloads preserve chart-only `RenderReport` typing and return
+`DashboardRenderReport` for a dashboard. Use `NodeRenderResult<AnyRenderReport>`
+when storing results from either kind; plain `NodeRenderResult` retains its
+chart-only default type.
+
+Opt in with `{ quality:true }` to reuse core `draft()`'s presentation controller:
+at most **three total whole-visual render attempts**, including the initial draw
+and any restoration. Only eligible unspecified presentation defaults can change;
+explicit palettes/domains/themes and input data stay unchanged. `spec`, `report`,
+and `png` correspond to the selected final frame, and PNG encoding happens once,
+after selection. `quality` contains `renderPasses`, `selectedPass`, `iterations`,
+retained `applied` actions, `rejected` actions with reasons, and `stopReason`.
+Unresolved warnings remain in `report`; a quality loop is not a guarantee of perfect
+output. `NodeRenderError.result` exposes core validation/failure history if no final
+frame is available; no partial or mismatched PNG is returned.
+Candidate and rollback paints replay from the original canvas pixels, so transparent
+or translucent backgrounds never accumulate discarded attempts. This restoration
+does not add chart-render passes.
+Opted-in results also retain validation `warnings`, including exact data evidence
+and `requiresDecision`. These advisories are separate from the render report:
+presentation improvements do not resolve data/meaning choices or explicit theme
+fallback decisions. The direct default path does not validate and omits `warnings`.
+
 ### `renderToPNG(spec, options?) → Buffer`
 
 Convenience wrapper that returns only the PNG bytes.
@@ -69,6 +94,16 @@ Convenience wrapper that returns only the PNG bytes.
 | `height` | `500`   | Logical height in CSS pixels.                                         |
 | `dpr`    | `2`     | Device pixel ratio — the PNG is rasterized at `width*dpr × height*dpr`. |
 | `fonts`  | —       | `{ path, family }[]` font files to register before rendering.         |
+| `quality` | `false` | `true` or `{maxPasses?:1\|2\|3}`. Initial/candidate/restoration share one budget. Budgets below 3 only evaluate the initial render because rollback capacity is reserved. |
+
+`width` and `height` must be finite numbers from 1 to 8192 CSS pixels. `dpr`
+must be finite from 0.25 to 4, and the final rasterized canvas
+(`round(width*dpr) × round(height*dpr)`) is capped at 67,108,864 pixels.
+Invalid or unsafe sizes throw a `RangeError` before any canvas is allocated.
+Core still records backing-store evidence on reports; if a composing target has
+to lower the effective DPR for safety, `report.evidence.backingStore` contains the
+requested/effective DPR and raster size and the report includes a
+`backing-store-clamped` info diagnostic.
 
 ### Fonts
 
@@ -77,11 +112,16 @@ Convenience wrapper that returns only the PNG bytes.
 
 ```ts
 renderChart(spec, {
-  fonts: [{ path: '/fonts/Inter-Variable.ttf', family: 'Inter' }],
+  fonts: [{ path: 'C:\\fonts\\Inter-Variable.ttf', family: 'Inter' }],
 });
 ```
 
 `GlobalFonts` is re-exported if you prefer to register fonts once at startup.
+Unreadable/unregisterable files do not crash an otherwise valid render:
+`fontRegistrations` contains `{path,family,registered,message?}` for each request,
+and failures add a `font-fallback` warning to the report and quality history.
+Successful registration establishes that the file loaded, not that every glyph or
+requested font style is available.
 
 ## Supported charts
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { GlobalFonts } from '@napi-rs/canvas';
-import { RenderReport, ChartSpec } from 'graphein';
-export { ChartSpec, RenderReport } from 'graphein';
+import { DraftResult, AnyRenderReport, RenderReport, AnySpec, QualityResult, ValidationError, QualityOptions, DashboardSpec, DashboardRenderReport, ChartSpec } from 'graphein';
+export { AnyRenderReport, AnySpec, ChartSpec, DashboardRenderReport, DashboardSpec, QualityOptions, QualityResult, RenderReport, ValidationError } from 'graphein';
 
 /**
  * `@graphein/node` — headless Graphein rendering for Node.
@@ -45,9 +45,18 @@ interface RenderImageOptions {
     dpr?: number;
     /** Extra fonts to register before rendering. */
     fonts?: FontFace[];
+    /** Opt in to core's presentation-default loop (at most three whole-visual render attempts). */
+    quality?: boolean | QualityOptions;
+}
+/** Registration evidence for a caller-supplied font; failure is non-fatal. */
+interface FontRegistration {
+    path: string;
+    family: string;
+    registered: boolean;
+    message?: string;
 }
 /** The result of a headless render: the PNG bytes plus the render report. */
-interface NodeRenderResult {
+interface NodeRenderResult<R extends AnyRenderReport = RenderReport> {
     /** PNG-encoded image bytes. */
     png: Buffer;
     /**
@@ -55,12 +64,49 @@ interface NodeRenderResult {
      * browser — `ok`, mark/series/color counts, and any clipping / overlap /
      * contrast warnings. Lets an agent critique the chart with no vision model.
      */
-    report: RenderReport;
+    report: R;
     /** Pixel width of the PNG (`width * dpr`, rounded). */
     width: number;
     /** Pixel height of the PNG (`height * dpr`, rounded). */
     height: number;
+    /** Effective spec corresponding to the final PNG and report. Input data is never transformed by quality mode. */
+    spec: AnySpec;
+    /** Core quality-loop evidence, present only when opted in. */
+    quality?: QualityResult;
+    /** Validation advisories retained when quality mode validates the spec; absent on the direct default path. */
+    warnings?: ValidationError[];
+    /** Outcome of each explicitly requested font registration. */
+    fontRegistrations: FontRegistration[];
+}
+/** Opt-in validation/rendering failed, so no potentially mismatched PNG was encoded. */
+declare class NodeRenderError extends Error {
+    readonly result: DraftResult;
+    constructor(result: DraftResult);
+}
+/** Hard bounds that keep headless renders from creating invalid or enormous canvases. */
+declare const RENDER_LIMITS: Readonly<{
+    minWidth: 1;
+    maxWidth: 8192;
+    minHeight: 1;
+    maxHeight: 8192;
+    minDpr: 0.25;
+    maxDpr: 4;
+    maxPixels: 67108864;
+}>;
+interface ResolvedRenderImageOptions {
+    /** Logical width in CSS pixels. */
+    width: number;
+    /** Logical height in CSS pixels. */
+    height: number;
+    /** Device pixel ratio. */
+    dpr: number;
+    /** Rounded raster width in physical pixels. */
+    pixelWidth: number;
+    /** Rounded raster height in physical pixels. */
+    pixelHeight: number;
 }
+/** Validate and resolve render sizing options before allocating a canvas. */
+declare function validateRenderImageOptions(options?: RenderImageOptions): ResolvedRenderImageOptions;
 /**
  * Render `spec` to a PNG buffer and its {@link RenderReport}, entirely in Node.
  *
@@ -68,12 +114,14 @@ interface NodeRenderResult {
  * sankey, choropleth, combo, histogram, funnel, and the formerly DOM-only kpi,
  * table, matrix, slicers and dashboard (painted as a static canvas snapshot).
  */
+declare function renderChart(spec: DashboardSpec, options?: RenderImageOptions): NodeRenderResult<DashboardRenderReport>;
 declare function renderChart(spec: ChartSpec, options?: RenderImageOptions): NodeRenderResult;
+declare function renderChart(spec: AnySpec, options?: RenderImageOptions): NodeRenderResult<AnyRenderReport>;
 /**
  * Convenience wrapper around {@link renderChart} that returns only the PNG bytes.
  */
-declare function renderToPNG(spec: ChartSpec, options?: RenderImageOptions): Buffer;
+declare function renderToPNG(spec: AnySpec, options?: RenderImageOptions): Buffer;
 
-declare const VERSION = "0.7.0";
+declare const VERSION = "0.20.0";
 
-export { type FontFace, type NodeRenderResult, type RenderImageOptions, VERSION, renderChart, renderToPNG };
+export { type FontFace, type FontRegistration, NodeRenderError, type NodeRenderResult, RENDER_LIMITS, type RenderImageOptions, type ResolvedRenderImageOptions, VERSION, renderChart, renderToPNG, validateRenderImageOptions };

package/dist/index.js

@@ -1,56 +1,163 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
 // src/index.ts
 import { createCanvas, GlobalFonts } from "@napi-rs/canvas";
-import { renderToContext, setMeasureContext } from "graphein";
+import {
+  draft
+} from "graphein";
+import {
+  computeBackingSize,
+  renderDashboardToContext,
+  renderToContext,
+  setMeasureContext
+} from "graphein/internal";
+var NodeRenderError = class extends Error {
+  constructor(result) {
+    super((result.renderError ?? result.errors.map((e) => `${e.path}: ${e.message}`).join("; ")) || "Graphein: no final render report is available.");
+    __publicField(this, "result", result);
+    this.name = "NodeRenderError";
+  }
+};
 var DEFAULT_WIDTH = 800;
 var DEFAULT_HEIGHT = 500;
 var DEFAULT_DPR = 2;
-function registerFonts(fonts) {
-  if (!fonts) return;
-  for (const f of fonts) {
-    try {
-      GlobalFonts.registerFromPath(f.path, f.family);
-    } catch {
-    }
+var RENDER_LIMITS = Object.freeze({
+  minWidth: 1,
+  maxWidth: 8192,
+  minHeight: 1,
+  maxHeight: 8192,
+  minDpr: 0.25,
+  maxDpr: 4,
+  maxPixels: 67108864
+});
+function assertFiniteInRange(name, value, min, max, unit) {
+  if (!Number.isFinite(value) || value < min || value > max) {
+    throw new RangeError(`Graphein render option "${name}" must be a finite number between ${min} and ${max}${unit ? ` ${unit}` : ""}.`);
   }
 }
-function renderChart(spec, options = {}) {
+function validateRenderImageOptions(options = {}) {
   const width = options.width ?? DEFAULT_WIDTH;
   const height = options.height ?? DEFAULT_HEIGHT;
   const dpr = options.dpr ?? DEFAULT_DPR;
-  registerFonts(options.fonts);
-  const pxW = Math.max(1, Math.round(width * dpr));
-  const pxH = Math.max(1, Math.round(height * dpr));
+  assertFiniteInRange("width", width, RENDER_LIMITS.minWidth, RENDER_LIMITS.maxWidth, "CSS pixels");
+  assertFiniteInRange("height", height, RENDER_LIMITS.minHeight, RENDER_LIMITS.maxHeight, "CSS pixels");
+  assertFiniteInRange("dpr", dpr, RENDER_LIMITS.minDpr, RENDER_LIMITS.maxDpr, "");
+  const pixelWidth = Math.round(width * dpr);
+  const pixelHeight = Math.round(height * dpr);
+  const pixels = pixelWidth * pixelHeight;
+  if (!Number.isSafeInteger(pixels) || pixels > RENDER_LIMITS.maxPixels) {
+    throw new RangeError(
+      `Graphein render size ${pixelWidth}\xD7${pixelHeight} (${pixels.toLocaleString("en-US")} pixels) exceeds the ${RENDER_LIMITS.maxPixels.toLocaleString("en-US")}-pixel cap. Reduce width, height, or dpr.`
+    );
+  }
+  return { width, height, dpr, pixelWidth, pixelHeight };
+}
+function registerFonts(fonts) {
+  return (fonts ?? []).map((f) => {
+    try {
+      const registered = !!GlobalFonts.registerFromPath(f.path, f.family);
+      return { ...f, registered, ...registered ? {} : { message: "Font registration returned no font." } };
+    } catch (error) {
+      return { ...f, registered: false, message: error instanceof Error ? error.message : String(error) };
+    }
+  });
+}
+function withFontFindings(report, fonts) {
+  const failed = fonts.filter((f) => !f.registered);
+  if (!failed.length) return report;
+  return {
+    ...report,
+    ok: false,
+    diagnostics: [
+      ...report.diagnostics.filter((d) => d.severity === "error"),
+      ...failed.map((f) => ({
+        code: "font-fallback",
+        severity: "warning",
+        message: `Could not register "${f.family}"; text may use an available fallback font.`,
+        details: { family: f.family, path: f.path, reason: f.message },
+        hint: "Supply a readable font file and register it under the family used by the theme."
+      })),
+      ...report.diagnostics.filter((d) => d.severity !== "error")
+    ]
+  };
+}
+function renderChart(spec, options = {}) {
+  const { width, height, dpr } = validateRenderImageOptions(options);
+  const fontRegistrations = registerFonts(options.fonts);
+  const backing = computeBackingSize(width, height, dpr);
+  const pxW = backing.pixelWidth;
+  const pxH = backing.pixelHeight;
   const canvas = createCanvas(pxW, pxH);
   const ctx = canvas.getContext("2d");
-  ctx.scale(dpr, dpr);
+  ctx.scale(backing.dpr, backing.dpr);
   const measureCtx = createCanvas(1, 1).getContext("2d");
   const interactionCtx = createCanvas(pxW, pxH).getContext("2d");
-  interactionCtx.scale(dpr, dpr);
-  setMeasureContext(measureCtx);
+  interactionCtx.scale(backing.dpr, backing.dpr);
+  const restoreMeasureContext = setMeasureContext(measureCtx);
   let report;
+  let effectiveSpec = spec;
+  let quality;
+  let warnings;
   try {
-    report = renderToContext(
-      {
-        marks: ctx,
-        interaction: interactionCtx,
-        width,
-        height
-      },
-      spec
-    );
+    const target = {
+      marks: ctx,
+      interaction: interactionCtx,
+      width,
+      height,
+      backingStore: {
+        requestedDpr: backing.requestedDpr,
+        effectiveDpr: backing.dpr,
+        pixelWidth: backing.pixelWidth,
+        pixelHeight: backing.pixelHeight,
+        clamped: backing.clamped
+      }
+    };
+    if (options.quality) {
+      const selected = draft(spec, { target, repair: false, quality: options.quality });
+      if (!selected.report) throw new NodeRenderError(selected);
+      report = selected.report;
+      effectiveSpec = selected.spec;
+      quality = selected.quality;
+      warnings = selected.warnings;
+    } else {
+      report = spec.type === "dashboard" ? renderDashboardToContext(target, spec) : renderToContext(target, spec);
+    }
   } finally {
-    setMeasureContext(null);
+    restoreMeasureContext();
+  }
+  if (quality) {
+    for (const iteration of quality.iterations) {
+      if (iteration.report) iteration.report = withFontFindings(iteration.report, fontRegistrations);
+    }
+    report = quality.iterations.find((i) => i.pass === quality.selectedPass)?.report ?? report;
+    if (!report.ok && quality.stopReason === "satisfied") quality.stopReason = "no-actions";
+  } else {
+    report = withFontFindings(report, fontRegistrations);
   }
-  return { png: canvas.toBuffer("image/png"), report, width: pxW, height: pxH };
+  return {
+    png: canvas.toBuffer("image/png"),
+    report,
+    spec: effectiveSpec,
+    quality,
+    ...warnings ? { warnings } : {},
+    fontRegistrations,
+    width: pxW,
+    height: pxH
+  };
 }
 function renderToPNG(spec, options) {
   return renderChart(spec, options).png;
 }
-var VERSION = "0.7.0";
+var VERSION = "0.20.0";
 export {
   GlobalFonts,
+  NodeRenderError,
+  RENDER_LIMITS,
   VERSION,
   renderChart,
-  renderToPNG
+  renderToPNG,
+  validateRenderImageOptions
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphein/node` — headless Graphein rendering for Node.\n *\n * Render any canvas-backed {@link ChartSpec} to a PNG buffer **and** its\n * {@link RenderReport} with no browser and no JSDOM, so the whole\n * generate → validate → render → critique loop can run server-side (CI, agents,\n * email/PDF report assets). It wires `graphein`'s dependency-free\n * `renderToContext` to `@napi-rs/canvas`; the core engine stays zero-dependency.\n *\n * ```ts\n * import { renderChart } from '@graphein/node';\n * const { png, report } = renderChart(spec, { width: 900, height: 480, dpr: 2 });\n * if (!report.ok) console.warn(report.diagnostics);\n * await fs.writeFile('chart.png', png);\n * ```\n *\n * Every chart type rasterizes — kpi/table/matrix/slicers/dashboard render a\n * static canvas snapshot, so the whole catalog can be validated server-side.\n */\n\nimport { createCanvas, GlobalFonts } from '@napi-rs/canvas';\nimport { renderToContext, setMeasureContext, type ChartSpec, type RenderReport } from 'graphein';\n\n/** A font file to register before rendering, improving text fidelity. */\nexport interface FontFace {\n  /** Absolute path to a `.ttf` / `.otf` / `.woff` file. */\n  path: string;\n  /**\n   * The family name to register the font under. Match this to the family your\n   * theme uses (Graphein's default is `Inter`) so text renders in that face.\n   */\n  family: string;\n}\n\n/** Options for {@link renderChart} / {@link renderToPNG}. */\nexport interface RenderImageOptions {\n  /** Logical width in CSS pixels. Default `800`. */\n  width?: number;\n  /** Logical height in CSS pixels. Default `500`. */\n  height?: number;\n  /**\n   * Device pixel ratio. The PNG is rasterized at `width * dpr × height * dpr`\n   * for crisp output. Default `2`.\n   */\n  dpr?: number;\n  /** Extra fonts to register before rendering. */\n  fonts?: FontFace[];\n}\n\n/** The result of a headless render: the PNG bytes plus the render report. */\nexport interface NodeRenderResult {\n  /** PNG-encoded image bytes. */\n  png: Buffer;\n  /**\n   * The same machine-readable diagnostics as `instance.report()` in the\n   * browser — `ok`, mark/series/color counts, and any clipping / overlap /\n   * contrast warnings. Lets an agent critique the chart with no vision model.\n   */\n  report: RenderReport;\n  /** Pixel width of the PNG (`width * dpr`, rounded). */\n  width: number;\n  /** Pixel height of the PNG (`height * dpr`, rounded). */\n  height: number;\n}\n\nconst DEFAULT_WIDTH = 800;\nconst DEFAULT_HEIGHT = 500;\nconst DEFAULT_DPR = 2;\n\nfunction registerFonts(fonts: FontFace[] | undefined): void {\n  if (!fonts) return;\n  for (const f of fonts) {\n    try {\n      GlobalFonts.registerFromPath(f.path, f.family);\n    } catch {\n      // An unreadable font path is non-fatal — napi falls back to a system sans.\n    }\n  }\n}\n\n/**\n * Render `spec` to a PNG buffer and its {@link RenderReport}, entirely in Node.\n *\n * Supports the entire catalog: line, area, bar, scatter, box, pie, heatmap,\n * sankey, choropleth, combo, histogram, funnel, and the formerly DOM-only kpi,\n * table, matrix, slicers and dashboard (painted as a static canvas snapshot).\n */\nexport function renderChart(spec: ChartSpec, options: RenderImageOptions = {}): NodeRenderResult {\n  const width = options.width ?? DEFAULT_WIDTH;\n  const height = options.height ?? DEFAULT_HEIGHT;\n  const dpr = options.dpr ?? DEFAULT_DPR;\n\n  registerFonts(options.fonts);\n\n  const pxW = Math.max(1, Math.round(width * dpr));\n  const pxH = Math.max(1, Math.round(height * dpr));\n\n  const canvas = createCanvas(pxW, pxH);\n  const ctx = canvas.getContext('2d');\n  ctx.scale(dpr, dpr);\n\n  // A dedicated 1×1 context for text measurement so layout uses real font\n  // metrics (not the SSR heuristic) without mutating the drawing context.\n  const measureCtx = createCanvas(1, 1).getContext('2d');\n\n  // The interaction layer is unused on the static path; give it its own canvas\n  // so a stray hover-layer paint can never land on the marks canvas.\n  const interactionCtx = createCanvas(pxW, pxH).getContext('2d');\n  interactionCtx.scale(dpr, dpr);\n\n  setMeasureContext(measureCtx as unknown as CanvasRenderingContext2D);\n  let report: RenderReport;\n  try {\n    report = renderToContext(\n      {\n        marks: ctx as unknown as CanvasRenderingContext2D,\n        interaction: interactionCtx as unknown as CanvasRenderingContext2D,\n        width,\n        height,\n      },\n      spec,\n    );\n  } finally {\n    setMeasureContext(null);\n  }\n\n  return { png: canvas.toBuffer('image/png'), report, width: pxW, height: pxH };\n}\n\n/**\n * Convenience wrapper around {@link renderChart} that returns only the PNG bytes.\n */\nexport function renderToPNG(spec: ChartSpec, options?: RenderImageOptions): Buffer {\n  return renderChart(spec, options).png;\n}\n\n/** Re-exported so callers can register fonts globally without a second dep. */\nexport { GlobalFonts };\nexport type { ChartSpec, RenderReport } from 'graphein';\n\nexport const VERSION = '0.7.0';\n"],"mappings":";AAoBA,SAAS,cAAc,mBAAmB;AAC1C,SAAS,iBAAiB,yBAA4D;AA4CtF,IAAM,gBAAgB;AACtB,IAAM,iBAAiB;AACvB,IAAM,cAAc;AAEpB,SAAS,cAAc,OAAqC;AAC1D,MAAI,CAAC,MAAO;AACZ,aAAW,KAAK,OAAO;AACrB,QAAI;AACF,kBAAY,iBAAiB,EAAE,MAAM,EAAE,MAAM;AAAA,IAC/C,QAAQ;AAAA,IAER;AAAA,EACF;AACF;AASO,SAAS,YAAY,MAAiB,UAA8B,CAAC,GAAqB;AAC/F,QAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,MAAM,QAAQ,OAAO;AAE3B,gBAAc,QAAQ,KAAK;AAE3B,QAAM,MAAM,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,GAAG,CAAC;AAC/C,QAAM,MAAM,KAAK,IAAI,GAAG,KAAK,MAAM,SAAS,GAAG,CAAC;AAEhD,QAAM,SAAS,aAAa,KAAK,GAAG;AACpC,QAAM,MAAM,OAAO,WAAW,IAAI;AAClC,MAAI,MAAM,KAAK,GAAG;AAIlB,QAAM,aAAa,aAAa,GAAG,CAAC,EAAE,WAAW,IAAI;AAIrD,QAAM,iBAAiB,aAAa,KAAK,GAAG,EAAE,WAAW,IAAI;AAC7D,iBAAe,MAAM,KAAK,GAAG;AAE7B,oBAAkB,UAAiD;AACnE,MAAI;AACJ,MAAI;AACF,aAAS;AAAA,MACP;AAAA,QACE,OAAO;AAAA,QACP,aAAa;AAAA,QACb;AAAA,QACA;AAAA,MACF;AAAA,MACA;AAAA,IACF;AAAA,EACF,UAAE;AACA,sBAAkB,IAAI;AAAA,EACxB;AAEA,SAAO,EAAE,KAAK,OAAO,SAAS,WAAW,GAAG,QAAQ,OAAO,KAAK,QAAQ,IAAI;AAC9E;AAKO,SAAS,YAAY,MAAiB,SAAsC;AACjF,SAAO,YAAY,MAAM,OAAO,EAAE;AACpC;AAMO,IAAM,UAAU;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphein/node` — headless Graphein rendering for Node.\n *\n * Render any canvas-backed {@link ChartSpec} to a PNG buffer **and** its\n * {@link RenderReport} with no browser and no JSDOM, so the whole\n * generate → validate → render → critique loop can run server-side (CI, agents,\n * email/PDF report assets). It wires `graphein`'s dependency-free\n * `renderToContext` to `@napi-rs/canvas`; the core engine stays zero-dependency.\n *\n * ```ts\n * import { renderChart } from '@graphein/node';\n * const { png, report } = renderChart(spec, { width: 900, height: 480, dpr: 2 });\n * if (!report.ok) console.warn(report.diagnostics);\n * await fs.writeFile('chart.png', png);\n * ```\n *\n * Every chart type rasterizes — kpi/table/matrix/slicers/dashboard render a\n * static canvas snapshot, so the whole catalog can be validated server-side.\n */\n\nimport { createCanvas, GlobalFonts } from '@napi-rs/canvas';\nimport {\n  draft,\n  type AnySpec, type ChartSpec, type DashboardSpec, type DraftResult,\n  type AnyRenderReport, type DashboardRenderReport, type QualityOptions, type QualityResult, type RenderReport,\n  type ValidationError,\n} from 'graphein';\nimport {\n  computeBackingSize,\n  renderDashboardToContext,\n  renderToContext,\n  setMeasureContext,\n} from 'graphein/internal';\n\n/** A font file to register before rendering, improving text fidelity. */\nexport interface FontFace {\n  /** Absolute path to a `.ttf` / `.otf` / `.woff` file. */\n  path: string;\n  /**\n   * The family name to register the font under. Match this to the family your\n   * theme uses (Graphein's default is `Inter`) so text renders in that face.\n   */\n  family: string;\n}\n\n/** Options for {@link renderChart} / {@link renderToPNG}. */\nexport interface RenderImageOptions {\n  /** Logical width in CSS pixels. Default `800`. */\n  width?: number;\n  /** Logical height in CSS pixels. Default `500`. */\n  height?: number;\n  /**\n   * Device pixel ratio. The PNG is rasterized at `width * dpr × height * dpr`\n   * for crisp output. Default `2`.\n   */\n  dpr?: number;\n  /** Extra fonts to register before rendering. */\n  fonts?: FontFace[];\n  /** Opt in to core's presentation-default loop (at most three whole-visual render attempts). */\n  quality?: boolean | QualityOptions;\n}\n\n/** Registration evidence for a caller-supplied font; failure is non-fatal. */\nexport interface FontRegistration {\n  path: string;\n  family: string;\n  registered: boolean;\n  message?: string;\n}\n\n/** The result of a headless render: the PNG bytes plus the render report. */\nexport interface NodeRenderResult<R extends AnyRenderReport = RenderReport> {\n  /** PNG-encoded image bytes. */\n  png: Buffer;\n  /**\n   * The same machine-readable diagnostics as `instance.report()` in the\n   * browser — `ok`, mark/series/color counts, and any clipping / overlap /\n   * contrast warnings. Lets an agent critique the chart with no vision model.\n   */\n  report: R;\n  /** Pixel width of the PNG (`width * dpr`, rounded). */\n  width: number;\n  /** Pixel height of the PNG (`height * dpr`, rounded). */\n  height: number;\n  /** Effective spec corresponding to the final PNG and report. Input data is never transformed by quality mode. */\n  spec: AnySpec;\n  /** Core quality-loop evidence, present only when opted in. */\n  quality?: QualityResult;\n  /** Validation advisories retained when quality mode validates the spec; absent on the direct default path. */\n  warnings?: ValidationError[];\n  /** Outcome of each explicitly requested font registration. */\n  fontRegistrations: FontRegistration[];\n}\n\n/** Opt-in validation/rendering failed, so no potentially mismatched PNG was encoded. */\nexport class NodeRenderError extends Error {\n  constructor(readonly result: DraftResult) {\n    super((result.renderError ?? result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')) ||\n      'Graphein: no final render report is available.');\n    this.name = 'NodeRenderError';\n  }\n}\n\nconst DEFAULT_WIDTH = 800;\nconst DEFAULT_HEIGHT = 500;\nconst DEFAULT_DPR = 2;\n\n/** Hard bounds that keep headless renders from creating invalid or enormous canvases. */\nexport const RENDER_LIMITS = Object.freeze({\n  minWidth: 1,\n  maxWidth: 8192,\n  minHeight: 1,\n  maxHeight: 8192,\n  minDpr: 0.25,\n  maxDpr: 4,\n  maxPixels: 67_108_864,\n});\n\nexport interface ResolvedRenderImageOptions {\n  /** Logical width in CSS pixels. */\n  width: number;\n  /** Logical height in CSS pixels. */\n  height: number;\n  /** Device pixel ratio. */\n  dpr: number;\n  /** Rounded raster width in physical pixels. */\n  pixelWidth: number;\n  /** Rounded raster height in physical pixels. */\n  pixelHeight: number;\n}\n\nfunction assertFiniteInRange(name: string, value: number, min: number, max: number, unit: string): void {\n  if (!Number.isFinite(value) || value < min || value > max) {\n    throw new RangeError(`Graphein render option \"${name}\" must be a finite number between ${min} and ${max}${unit ? ` ${unit}` : ''}.`);\n  }\n}\n\n/** Validate and resolve render sizing options before allocating a canvas. */\nexport function validateRenderImageOptions(options: RenderImageOptions = {}): ResolvedRenderImageOptions {\n  const width = options.width ?? DEFAULT_WIDTH;\n  const height = options.height ?? DEFAULT_HEIGHT;\n  const dpr = options.dpr ?? DEFAULT_DPR;\n  assertFiniteInRange('width', width, RENDER_LIMITS.minWidth, RENDER_LIMITS.maxWidth, 'CSS pixels');\n  assertFiniteInRange('height', height, RENDER_LIMITS.minHeight, RENDER_LIMITS.maxHeight, 'CSS pixels');\n  assertFiniteInRange('dpr', dpr, RENDER_LIMITS.minDpr, RENDER_LIMITS.maxDpr, '');\n  const pixelWidth = Math.round(width * dpr);\n  const pixelHeight = Math.round(height * dpr);\n  const pixels = pixelWidth * pixelHeight;\n  if (!Number.isSafeInteger(pixels) || pixels > RENDER_LIMITS.maxPixels) {\n    throw new RangeError(\n      `Graphein render size ${pixelWidth}×${pixelHeight} (${pixels.toLocaleString('en-US')} pixels) exceeds the ${RENDER_LIMITS.maxPixels.toLocaleString('en-US')}-pixel cap. Reduce width, height, or dpr.`,\n    );\n  }\n  return { width, height, dpr, pixelWidth, pixelHeight };\n}\n\nfunction registerFonts(fonts: FontFace[] | undefined): FontRegistration[] {\n  return (fonts ?? []).map((f) => {\n    try {\n      const registered = !!GlobalFonts.registerFromPath(f.path, f.family);\n      return { ...f, registered, ...(registered ? {} : { message: 'Font registration returned no font.' }) };\n    } catch (error) {\n      return { ...f, registered: false, message: error instanceof Error ? error.message : String(error) };\n    }\n  });\n}\n\nfunction withFontFindings<R extends AnyRenderReport>(report: R, fonts: FontRegistration[]): R {\n  const failed = fonts.filter((f) => !f.registered);\n  if (!failed.length) return report;\n  return {\n    ...report,\n    ok: false,\n    diagnostics: [\n      ...report.diagnostics.filter((d) => d.severity === 'error'),\n      ...failed.map((f) => ({\n        code: 'font-fallback', severity: 'warning' as const,\n        message: `Could not register \"${f.family}\"; text may use an available fallback font.`,\n        details: { family: f.family, path: f.path, reason: f.message },\n        hint: 'Supply a readable font file and register it under the family used by the theme.',\n      })),\n      ...report.diagnostics.filter((d) => d.severity !== 'error'),\n    ],\n  };\n}\n\n/**\n * Render `spec` to a PNG buffer and its {@link RenderReport}, entirely in Node.\n *\n * Supports the entire catalog: line, area, bar, scatter, box, pie, heatmap,\n * sankey, choropleth, combo, histogram, funnel, and the formerly DOM-only kpi,\n * table, matrix, slicers and dashboard (painted as a static canvas snapshot).\n */\nexport function renderChart(spec: DashboardSpec, options?: RenderImageOptions): NodeRenderResult<DashboardRenderReport>;\nexport function renderChart(spec: ChartSpec, options?: RenderImageOptions): NodeRenderResult;\nexport function renderChart(spec: AnySpec, options?: RenderImageOptions): NodeRenderResult<AnyRenderReport>;\nexport function renderChart(spec: AnySpec, options: RenderImageOptions = {}): NodeRenderResult<AnyRenderReport> {\n  const { width, height, dpr } = validateRenderImageOptions(options);\n\n  const fontRegistrations = registerFonts(options.fonts);\n\n  const backing = computeBackingSize(width, height, dpr);\n  const pxW = backing.pixelWidth;\n  const pxH = backing.pixelHeight;\n\n  const canvas = createCanvas(pxW, pxH);\n  const ctx = canvas.getContext('2d');\n  ctx.scale(backing.dpr, backing.dpr);\n\n  // A dedicated 1×1 context for text measurement so layout uses real font\n  // metrics (not the SSR heuristic) without mutating the drawing context.\n  const measureCtx = createCanvas(1, 1).getContext('2d');\n\n  // The interaction layer is unused on the static path; give it its own canvas\n  // so a stray hover-layer paint can never land on the marks canvas.\n  const interactionCtx = createCanvas(pxW, pxH).getContext('2d');\n  interactionCtx.scale(backing.dpr, backing.dpr);\n\n  const restoreMeasureContext = setMeasureContext(measureCtx as unknown as CanvasRenderingContext2D);\n  let report: AnyRenderReport;\n  let effectiveSpec = spec;\n  let quality: QualityResult | undefined;\n  let warnings: ValidationError[] | undefined;\n  try {\n    const target = {\n      marks: ctx as unknown as CanvasRenderingContext2D,\n      interaction: interactionCtx as unknown as CanvasRenderingContext2D,\n      width,\n      height,\n      backingStore: {\n        requestedDpr: backing.requestedDpr,\n        effectiveDpr: backing.dpr,\n        pixelWidth: backing.pixelWidth,\n        pixelHeight: backing.pixelHeight,\n        clamped: backing.clamped,\n      },\n    };\n    if (options.quality) {\n      const selected = draft(spec, { target, repair: false, quality: options.quality });\n      if (!selected.report) throw new NodeRenderError(selected);\n      report = selected.report;\n      effectiveSpec = selected.spec as AnySpec;\n      quality = selected.quality;\n      warnings = selected.warnings;\n    } else {\n      report = spec.type === 'dashboard'\n        ? renderDashboardToContext(target, spec)\n        : renderToContext(target, spec);\n    }\n  } finally {\n    restoreMeasureContext();\n  }\n\n  if (quality) {\n    for (const iteration of quality.iterations) {\n      if (iteration.report) iteration.report = withFontFindings(iteration.report, fontRegistrations);\n    }\n    report = quality.iterations.find((i) => i.pass === quality.selectedPass)?.report ?? report;\n    if (!report.ok && quality.stopReason === 'satisfied') quality.stopReason = 'no-actions';\n  } else {\n    report = withFontFindings(report, fontRegistrations);\n  }\n  return {\n    png: canvas.toBuffer('image/png'), report, spec: effectiveSpec, quality,\n    ...(warnings ? { warnings } : {}),\n    fontRegistrations, width: pxW, height: pxH,\n  };\n}\n\n/**\n * Convenience wrapper around {@link renderChart} that returns only the PNG bytes.\n */\nexport function renderToPNG(spec: AnySpec, options?: RenderImageOptions): Buffer {\n  return renderChart(spec, options).png;\n}\n\n/** Re-exported so callers can register fonts globally without a second dep. */\nexport { GlobalFonts };\nexport type {\n  AnySpec, ChartSpec, DashboardSpec, QualityOptions, QualityResult,\n  AnyRenderReport, DashboardRenderReport, RenderReport,\n  ValidationError,\n} from 'graphein';\n\nexport const VERSION = '0.20.0';\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphein/node",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "Headless Graphein rendering for Node — render any ChartSpec to a PNG buffer with a RenderReport, no browser required.",
   "license": "MIT",
@@ -48,14 +48,15 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "sync:version": "node ../core/scripts/sync-version.mjs .",
+    "build": "npm run sync:version && tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "prepack": "tsup"
+    "prepack": "npm run sync:version && tsup"
   },
   "dependencies": {
     "@napi-rs/canvas": "^1.0.1",
-    "graphein": "^0.18.0"
+    "graphein": "^0.20.0"
   }
 }