ggaction 0.0.15 → 0.0.16

package/src/persistence.js

@@ -0,0 +1,74 @@
+import { ChartProgram } from "./ChartProgram.js";
+import { BasicChartProgram } from "./BasicChartProgram.js";
+import { cloneAndFreeze } from "./core/immutable.js";
+import { hasRegisteredExtension, isBuiltinProgramClass } from "./core/extensionRegistry.js";
+import { packageVersion } from "./version.js";
+import { decodeValue, encodeValue, invalidSnapshot } from "./persistence/codec.js";
+import { exactKeys, requireObject, STATE_KEYS, validateGraphic, validateProgramState, validateTrace } from "./persistence/validation.js";
+
+function canonicalState(program, extensions, path = "payload") {
+  if (!(program instanceof ChartProgram || program instanceof BasicChartProgram) || !isBuiltinProgramClass(program.constructor)) {
+    throw invalidSnapshot(`Cannot persist an unregistered program class at ${path}.`, path);
+  }
+  if (program.actionStack.length !== 0) throw invalidSnapshot("Cannot persist an open actionStack.", `${path}.actionStack`);
+  const state = Object.fromEntries(STATE_KEYS.map(key => [key, program[key]]));
+  state.children = Object.fromEntries(Object.entries(program.children).map(([id, child]) => [id, canonicalState(child, extensions, `${path}.children.${id}`)]));
+  validateTrace(program.trace, program.constructor, extensions, `${path}.trace`);
+  validateProgramState(program, path);
+  return state;
+}
+
+function envelope(kind, payload, extensions = []) {
+  return JSON.stringify({ schemaVersion: 1, kind, packageVersion, extensions, payload: encodeValue(payload) });
+}
+
+function readEnvelope(text, kind) {
+  if (typeof text !== "string") throw invalidSnapshot("Snapshot must be a JSON string.", "snapshot");
+  let value;
+  try { value = JSON.parse(text); } catch { throw invalidSnapshot("Snapshot must be valid JSON.", "snapshot"); }
+  exactKeys(value, ["schemaVersion", "kind", "packageVersion", "extensions", "payload"], "snapshot");
+  if (value.schemaVersion !== 1 || value.kind !== kind) throw invalidSnapshot(`Unsupported snapshot schema or kind; expected schema 1 ${kind}.`, "snapshot");
+  if (typeof value.packageVersion !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value.packageVersion)) throw invalidSnapshot("Invalid snapshot packageVersion.", "snapshot.packageVersion");
+  if (!Array.isArray(value.extensions) || new Set(value.extensions).size !== value.extensions.length ||
+      value.extensions.some(name => typeof name !== "string" || !hasRegisteredExtension(name)) || (kind === "graphic" && value.extensions.length)) {
+    throw invalidSnapshot("Snapshot requires unknown, duplicate, or inapplicable extensions.", "snapshot.extensions");
+  }
+  return { ...value, payload: decodeValue(value.payload) };
+}
+
+function restoreState(state, extensions, path = "payload") {
+  exactKeys(state, STATE_KEYS, path);
+  if (!Array.isArray(state.actionStack) || state.actionStack.length) throw invalidSnapshot("Snapshot actionStack must be empty.", `${path}.actionStack`);
+  requireObject(state.children, `${path}.children`);
+  validateTrace(state.trace, ChartProgram, extensions, `${path}.trace`);
+  const children = Object.fromEntries(Object.entries(state.children).map(([id, child]) => [id, restoreState(child, extensions, `${path}.children.${id}`)]));
+  const program = new ChartProgram({ ...state, children });
+  validateProgramState(program, path);
+  return program;
+}
+
+export function serializeProgram(program) {
+  const extensions = new Set();
+  return envelope("editable", canonicalState(program, extensions), [...extensions].sort());
+}
+
+export function deserializeProgram(text) {
+  const stored = readEnvelope(text, "editable");
+  const extensions = new Set();
+  const program = restoreState(stored.payload, extensions);
+  if (extensions.size !== stored.extensions.length || stored.extensions.some(name => !extensions.has(name))) {
+    throw invalidSnapshot("Snapshot extensions must exactly match its action traces.", "snapshot.extensions");
+  }
+  return program;
+}
+
+export function serializeGraphic(program) {
+  validateGraphic(program?.graphicSpec);
+  return envelope("graphic", program.graphicSpec);
+}
+
+export function deserializeGraphic(text) {
+  const { payload } = readEnvelope(text, "graphic");
+  validateGraphic(payload);
+  return cloneAndFreeze({ graphicSpec: payload });
+}

package/src/renderers/canvas/index.js

@@ -1,3 +1,4 @@
+import { annotateError } from "../../core/diagnostics.js";
 import { drawCircleGraphic } from "./circle.js";
 import { drawLineGraphic } from "./line.js";
 import { drawPathGraphic } from "./path.js";
@@ -208,14 +209,14 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     physicalWidth > MAX_RASTER_DIMENSION ||
     physicalHeight > MAX_RASTER_DIMENSION
   ) {
-    throw new RangeError(
+    throw annotateError(new RangeError(
       `render physical Canvas dimensions must not exceed ${MAX_RASTER_DIMENSION}.`
-    );
+    ), { code: "resource-limit", operation: "render", optionPath: "physicalDimensions", limit: MAX_RASTER_DIMENSION, actual: Math.max(physicalWidth, physicalHeight) });
   }
   if (physicalWidth * physicalHeight > MAX_RASTER_PIXELS) {
-    throw new RangeError(
+    throw annotateError(new RangeError(
       `render physical Canvas pixel count must not exceed ${MAX_RASTER_PIXELS}.`
-    );
+    ), { code: "resource-limit", operation: "render", optionPath: "physicalPixels", limit: MAX_RASTER_PIXELS, actual: physicalWidth * physicalHeight });
   }
   preflightCanvasGraphicSpec(target, pixelRatio);
 

package/src/renderers/nativeBackend.js

@@ -0,0 +1,10 @@
+export async function loadNativeBackend() {
+  try {
+    return await import("@napi-rs/canvas");
+  } catch (error) {
+    if (error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes("@napi-rs/canvas")) {
+      throw new Error("PNG/PDF output requires @napi-rs/canvas. Install it with: npm install ggaction @napi-rs/canvas", { cause: error });
+    }
+    throw error;
+  }
+}

package/src/renderers/options.js

@@ -0,0 +1,13 @@
+import { annotateError } from "../core/diagnostics.js";
+import { isPlainObject } from "../core/immutable.js";
+
+export function validateRendererOptions(options, allowed, label) {
+  if (!isPlainObject(options)) {
+    throw annotateError(new TypeError(`${label} must be a plain object.`), { code: "invalid-option" });
+  }
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) {
+      throw annotateError(new TypeError(`${label} does not support option "${key}".`), { code: "invalid-option", optionPath: key });
+    }
+  }
+}

package/src/renderers/pdf.js

@@ -1,7 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
-import { PDFDocument } from "@napi-rs/canvas";
+import { loadNativeBackend } from "./nativeBackend.js";
 
 import {
   drawResolvedGraphicSpec,
@@ -9,8 +9,10 @@ import {
   resolveGraphicRenderTarget
 } from "./canvas/index.js";
 import { preflightCanvasGraphicSpec } from "./canvas/native.js";
+import { validateRendererOptions } from "./options.js";
 
 const PDF_OPTIONS = new Set(["output", "metadata"]);
+const BUFFER_OPTIONS = new Set(["metadata"]);
 const PDF_METADATA = new Set([
   "title",
   "author",
@@ -19,30 +21,9 @@ const PDF_METADATA = new Set([
 ]);
 const MAX_PDF_DIMENSION = 16_777_216;
 
-function requirePlainObject(value, label) {
-  if (
-    value === null ||
-    typeof value !== "object" ||
-    Array.isArray(value) ||
-    Object.getPrototypeOf(value) !== Object.prototype
-  ) {
-    throw new TypeError(`${label} must be a plain object.`);
-  }
-  return value;
-}
-
-function requireClosedKeys(value, allowed, label) {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) {
-      throw new TypeError(`${label} does not support option "${key}".`);
-    }
-  }
-}
-
 function requireMetadata(metadata) {
   if (metadata === undefined) return undefined;
-  requirePlainObject(metadata, "renderToPDF metadata");
-  requireClosedKeys(metadata, PDF_METADATA, "renderToPDF metadata");
+  validateRendererOptions(metadata, PDF_METADATA, "renderToPDF metadata");
 
   const resolved = {};
   for (const key of ["title", "author", "subject"]) {
@@ -75,26 +56,6 @@ function requireMetadata(metadata) {
   return resolved;
 }
 
-function requirePDFOptions(options) {
-  requirePlainObject(options, "renderToPDF options");
-  requireClosedKeys(options, PDF_OPTIONS, "renderToPDF");
-  if (typeof options.output !== "string" || options.output.length === 0) {
-    throw new TypeError("renderToPDF requires a non-empty output path.");
-  }
-  return {
-    output: resolve(options.output),
-    metadata: requireMetadata(options.metadata)
-  };
-}
-
-function renderPDFBuffer(target, metadata) {
-  const document = new PDFDocument(metadata);
-  const context = document.beginPage(target.width, target.height);
-  drawResolvedGraphicSpec(target, context);
-  document.endPage();
-  return document.close();
-}
-
 function requirePDFPageDimensions(target) {
   if (![target.width, target.height].every(value =>
     Number.isSafeInteger(value) && value > 0 && value <= MAX_PDF_DIMENSION
@@ -105,22 +66,32 @@ function requirePDFPageDimensions(target) {
   }
 }
 
-export async function renderToPDF(program, options = {}) {
-  const { output, metadata } = requirePDFOptions(options);
+export async function renderToPDFBuffer(program, options = {}) {
+  validateRendererOptions(options, BUFFER_OPTIONS, "renderToPDFBuffer options");
+  const metadata = requireMetadata(options.metadata);
   const graphicSpec = requireProgramGraphicSpec(program);
   const target = resolveGraphicRenderTarget(graphicSpec);
   requirePDFPageDimensions(target);
   preflightCanvasGraphicSpec(target);
-  const buffer = renderPDFBuffer(target, metadata);
+  const { PDFDocument } = await loadNativeBackend();
+  const document = new PDFDocument(metadata);
+  const context = document.beginPage(target.width, target.height);
+  drawResolvedGraphicSpec(target, context);
+  document.endPage();
+  const buffer = document.close();
+  return Object.freeze({
+    buffer, width: target.width, height: target.height, pages: 1, bytes: buffer.length
+  });
+}
 
+export async function renderToPDF(program, options = {}) {
+  validateRendererOptions(options, PDF_OPTIONS, "renderToPDF options");
+  if (typeof options.output !== "string" || options.output.length === 0) {
+    throw new TypeError("renderToPDF requires a non-empty output path.");
+  }
+  const { buffer, ...result } = await renderToPDFBuffer(program, { metadata: options.metadata });
+  const output = resolve(options.output);
   await mkdir(dirname(output), { recursive: true });
   await writeFile(output, buffer);
-
-  return Object.freeze({
-    output,
-    width: target.width,
-    height: target.height,
-    pages: 1,
-    bytes: buffer.length
-  });
+  return Object.freeze({ output, ...result });
 }

package/src/renderers/png.js

@@ -1,29 +1,34 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { render } from "./canvas/index.js";
+import { validateRendererOptions } from "./options.js";
+import { loadNativeBackend } from "./nativeBackend.js";
 
-import { createCanvas } from "@napi-rs/canvas";
+const PNG_OPTIONS = new Set(["output", "pixelRatio"]);
+const BUFFER_OPTIONS = new Set(["pixelRatio"]);
 
-import { render } from "./canvas/index.js";
+export async function renderToPNGBuffer(program, options = {}) {
+  validateRendererOptions(options, BUFFER_OPTIONS, "renderToPNGBuffer options");
+  const { pixelRatio = 1 } = options;
+  const { createCanvas } = await loadNativeBackend();
+  const canvas = createCanvas(1, 1);
+  render(program, canvas.getContext("2d"), { pixelRatio });
+  // Canvas drawing is synchronous; encoding uses the native async worker.
+  const buffer = await canvas.encode("png");
+  return Object.freeze({
+    buffer, width: canvas.width, height: canvas.height, pixelRatio, bytes: buffer.length
+  });
+}
 
-export async function renderToPNG(program, { output, pixelRatio = 1 } = {}) {
+export async function renderToPNG(program, options = {}) {
+  validateRendererOptions(options, PNG_OPTIONS, "renderToPNG options");
+  const { output, pixelRatio } = options;
   if (typeof output !== "string" || output.length === 0) {
     throw new TypeError("renderToPNG requires a non-empty output path.");
   }
-
-  const canvas = createCanvas(1, 1);
-  const context = canvas.getContext("2d");
-  render(program, context, { pixelRatio });
-
+  const { buffer, ...result } = await renderToPNGBuffer(program, { pixelRatio });
   const path = resolve(output);
-  const buffer = canvas.toBuffer("image/png");
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, buffer);
-
-  return Object.freeze({
-    output: path,
-    width: canvas.width,
-    height: canvas.height,
-    pixelRatio,
-    bytes: buffer.length
-  });
+  return Object.freeze({ output: path, ...result });
 }

package/src/renderers/svg.js

@@ -1,3 +1,4 @@
+import { isOwned } from "../core/immutable.js";
 import {
   requireSingleOrderedGraphicByType,
   walkGraphicTreeEvents
@@ -17,6 +18,7 @@ import {
   requireStringProperty
 } from "./canvas/validation.js";
 import { normalizeRendererFontWeight } from "./text.js";
+import { validateRendererOptions } from "./options.js";
 
 const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 const SVG_OPTIONS = new Set(["title", "description", "resourceNamespace"]);
@@ -37,14 +39,20 @@ const DOMINANT_BASELINES = Object.freeze({
   bottom: "text-after-edge"
 });
 
+const namespaceByGraphic = new WeakMap();
+
 function resourceNamespace(graphicSpec) {
+  const cached = namespaceByGraphic.get(graphicSpec);
+  if (cached !== undefined) return cached;
   const serialized = JSON.stringify(graphicSpec);
   let hash = 0xcbf29ce484222325n;
   for (let index = 0; index < serialized.length; index += 1) {
     hash ^= BigInt(serialized.charCodeAt(index));
     hash = BigInt.asUintN(64, hash * 0x100000001b3n);
   }
-  return hash.toString(36);
+  const namespace = hash.toString(36);
+  if (isOwned(graphicSpec)) namespaceByGraphic.set(graphicSpec, namespace);
+  return namespace;
 }
 
 function escapeText(value) {
@@ -525,19 +533,7 @@ function serializeBody(graphicSpec, rootId, rootCanvas, width, height, state) {
 }
 
 function requireSVGOptions(options) {
-  if (
-    options === null ||
-    typeof options !== "object" ||
-    Array.isArray(options) ||
-    Object.getPrototypeOf(options) !== Object.prototype
-  ) {
-    throw new TypeError("renderToSVG options must be a plain object.");
-  }
-  for (const key of Object.keys(options)) {
-    if (!SVG_OPTIONS.has(key)) {
-      throw new TypeError(`renderToSVG does not support option "${key}".`);
-    }
-  }
+  validateRendererOptions(options, SVG_OPTIONS, "renderToSVG options");
   for (const key of SVG_OPTIONS) {
     if (
       options[key] !== undefined &&

package/src/renderers/text.js

@@ -1,11 +1 @@
-const MIN_RENDERER_NUMERIC_FONT_WEIGHT = 100;
-const MAX_RENDERER_NUMERIC_FONT_WEIGHT = 900;
-
-export function normalizeRendererFontWeight(fontWeight) {
-  if (typeof fontWeight !== "number") return fontWeight;
-  const rounded = Math.round(fontWeight / 100) * 100;
-  return Math.min(
-    MAX_RENDERER_NUMERIC_FONT_WEIGHT,
-    Math.max(MIN_RENDERER_NUMERIC_FONT_WEIGHT, rounded)
-  );
-}
+export { normalizeRendererFontWeight } from "../core/font.js";

package/src/selectors/coordinates.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findCoordinate(program, id) {
   return program.semanticSpec.coordinates.find(coordinate => coordinate.id === id);
 }
@@ -8,6 +10,6 @@ export function hasCoordinate(program, id) {
 
 export function requireCoordinate(program, id) {
   const coordinate = findCoordinate(program, id);
-  if (coordinate === undefined) throw new Error(`Unknown coordinate "${id}".`);
+  if (coordinate === undefined) throw annotateError(new Error(`Unknown coordinate "${id}".`), { code: "missing-resource", resourceId: id });
   return coordinate;
 }

package/src/selectors/datasets.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findDataset(program, id) {
   return program.semanticSpec.datasets.find(dataset => dataset.id === id);
 }
@@ -20,7 +22,7 @@ export function hasDatasetOwner(program, id) {
 export function resolveDatasetReference(program, id, label = "Dataset") {
   const matches = currentOwnerMatches(program, id);
   if (matches.length > 1) {
-    throw new Error(`${label} logical owner "${id}" is ambiguous.`);
+    throw annotateError(new Error(`${label} logical owner "${id}" is ambiguous.`), { code: "ambiguous-resource", resourceId: id, candidates: matches.map(match => match.current) });
   }
   const resolved = matches.length === 1 ? matches[0].current : id;
   const dataset = findDataset(program, resolved);
@@ -28,7 +30,7 @@ export function resolveDatasetReference(program, id, label = "Dataset") {
     const kind = label.toLowerCase().includes("source")
       ? "source dataset"
       : "dataset";
-    throw new Error(`Unknown ${kind} "${id}" does not exist.`);
+    throw annotateError(new Error(`Unknown ${kind} "${id}" does not exist.`), { code: "missing-resource", resourceId: id });
   }
   return dataset;
 }
@@ -43,19 +45,19 @@ export function findDatasetConsumer(program, source) {
 
 export function requireDataset(program, id, label = `Dataset "${id}"`) {
   const dataset = findDataset(program, id);
-  if (dataset === undefined) throw new Error(`${label} does not exist.`);
+  if (dataset === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return dataset;
 }
 
 export function requireMaterializedDataset(program, id) {
   const dataset = resolveDatasetReference(program, id, "Dataset");
-  if (dataset === undefined) throw new Error(`Unknown dataset "${id}".`);
+  if (dataset === undefined) throw annotateError(new Error(`Unknown dataset "${id}".`), { code: "missing-resource", resourceId: id });
   if (!Array.isArray(dataset.values)) {
-    throw new Error(
+    throw annotateError(new Error(
       `Dataset "${id}" requires materialized values. ` +
       "createDerivedData stores a definition only; use the corresponding " +
       "value-producing data action before creating a chart or mark."
-    );
+    ), { code: "incompatible-resource", resourceId: id });
   }
   return dataset;
 }

package/src/selectors/layers.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findLayer(program, id) {
   return program.semanticSpec.layers.find(layer => layer.id === id);
 }
@@ -12,7 +14,7 @@ export function hasLayer(program, id) {
 
 export function requireLayer(program, id, label = `Layer "${id}"`) {
   const layer = findLayer(program, id);
-  if (layer === undefined) throw new Error(`${label} does not exist.`);
+  if (layer === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return layer;
 }
 
@@ -26,12 +28,12 @@ export function resolveEligibleLayer(program, {
   const candidates = program.semanticSpec.layers.filter(predicate);
   if (target !== undefined) {
     const selected = candidates.find(layer => layer.id === target);
-    if (selected === undefined) throw new Error(`Unknown ${label} ${targetOption} "${target}".`);
+    if (selected === undefined) throw annotateError(new Error(`Unknown ${label} ${targetOption} "${target}".`), { code: findLayer(program, target) ? "incompatible-resource" : "missing-resource", resourceId: target, optionPath: targetOption });
     return selected;
   }
   const selected = candidates.find(layer => layer.id === current);
   if (selected !== undefined) return selected;
   if (candidates.length === 1) return candidates[0];
-  if (candidates.length === 0) throw new Error(`${label} requires an eligible layer.`);
-  throw new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`);
+  if (candidates.length === 0) throw annotateError(new Error(`${label} requires an eligible layer.`), { code: "missing-resource", optionPath: targetOption });
+  throw annotateError(new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`), { code: "ambiguous-resource", optionPath: targetOption, candidates: candidates.map(layer => layer.id) });
 }

package/src/selectors/markOwners.js

@@ -0,0 +1,46 @@
+import { findLayer } from "./layers.js";
+
+export function ownedChildren(program, id) {
+  const config = program.markConfigs[id] ?? {};
+  return [
+    config.errorBar?.lowerCapId,
+    config.errorBar?.upperCapId,
+    config.errorBand?.lowerBoundaryId,
+    config.errorBand?.upperBoundaryId,
+    config.regression?.bandId,
+    config.regression?.lineId,
+    config.boxPlot?.whiskerId,
+    config.boxPlot?.medianId,
+    config.boxPlot?.outlierId,
+    config.gradientPlot?.centerId,
+    config.intervalPlot?.intervalId,
+    config.endpointPlot?.roles?.stemId,
+    config.endpointPlot?.roles?.startId,
+    config.endpointPlot?.roles?.connectorId,
+    ...(config.raincloudPlot?.ownedChildIds ?? [])
+  ].concat(
+    program.semanticSpec.layers
+      .filter(layer => layer.source === id)
+      .map(layer => layer.id)
+  ).concat(
+    program.semanticSpec.layers
+      .filter(layer =>
+        program.markConfigs[layer.id]?.statisticalReference?.source === id
+      )
+      .map(layer => layer.id)
+  ).filter(child => child !== undefined && child !== id && findLayer(program, child) !== undefined);
+}
+
+export function ownership(program) {
+  const ownerByChild = new Map();
+  for (const layer of program.semanticSpec.layers) {
+    for (const child of ownedChildren(program, layer.id)) {
+      if (program.markConfigs[child]?.statisticalReference !== undefined) {
+        continue;
+      }
+      ownerByChild.set(child, layer.id);
+    }
+  }
+  return ownerByChild;
+}
+

package/src/selectors/scales.js

@@ -1,21 +1,23 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findSemanticScale(program, id) {
   return program.semanticSpec.scales.find(scale => scale.id === id);
 }
 
 export function requireSemanticScale(program, id) {
   const scale = findSemanticScale(program, id);
-  if (scale === undefined) throw new Error(`Unknown scale "${id}".`);
+  if (scale === undefined) throw annotateError(new Error(`Unknown scale "${id}".`), { code: "missing-resource", resourceId: id });
   return scale;
 }
 
 export function requireResolvedScale(program, id, type) {
-  const scale = program.resolvedScales[id];
+  const scale = Object.hasOwn(program.resolvedScales, id) ? program.resolvedScales[id] : undefined;
   if (scale === undefined || (type !== undefined && scale.type !== type)) {
-    throw new Error(
+    throw annotateError(new Error(
       type === undefined
         ? `Unknown resolved scale "${id}".`
         : `Expected resolved ${type} scale "${id}".`
-    );
+    ), { code: scale === undefined ? "missing-resource" : "incompatible-resource", resourceId: id });
   }
   return scale;
 }

package/src/theme/defaults.js

@@ -1,4 +1,5 @@
-export const DEFAULT_FONT_FAMILY = "sans-serif";
+import { DEFAULT_FONT_FAMILY } from "../core/font.js";
+export { DEFAULT_FONT_FAMILY };
 
 export const DEFAULT_POINT_RADIUS = 3;
 

package/src/version.js

@@ -0,0 +1,2 @@
+// Must match package.json; enforced by the snapshot producer-version test.
+export const packageVersion = "0.0.16";

package/types/accessibility.d.ts

@@ -0,0 +1,37 @@
+import type { ChartProgram } from "./program.js";
+import type { BasicChartProgram } from "./basic.js";
+
+export interface AccessibleColumn {
+  readonly key: string;
+  readonly role: string;
+  readonly component: string;
+  readonly field?: string;
+  readonly aggregate?: string;
+  readonly unit?: "utc-milliseconds";
+}
+export interface AccessibleRow {
+  readonly component: string;
+  readonly series: Readonly<Record<string, unknown>>;
+  readonly values: Readonly<Record<string, unknown>>;
+}
+export interface AccessibleOwnerView {
+  readonly ownerId: string;
+  readonly markType: string;
+  readonly columns: readonly AccessibleColumn[];
+  readonly rows: readonly AccessibleRow[];
+  readonly units: Readonly<Record<string, "utc-milliseconds">>;
+}
+export interface AccessibleChildView {
+  readonly ownerId: string;
+  readonly kind: "composition-child";
+  readonly title: string | null;
+  readonly facet?: Readonly<Record<string, unknown>>;
+  readonly views: readonly AccessibleView[];
+}
+export type AccessibleView = AccessibleOwnerView | AccessibleChildView;
+export interface AccessibleData {
+  readonly schemaVersion: 1;
+  readonly title: string | null;
+  readonly views: readonly AccessibleView[];
+}
+export function exportAccessibleData(program: ChartProgram | BasicChartProgram, options?: { readonly target?: string }): AccessibleData;

package/types/basic.d.ts

@@ -1,4 +1,4 @@
-import type { ChartProgram, BasicSeriesLayoutOptions } from "./program.js";
+import type { ChartProgram, BasicSeriesLayoutOptions, CreateDataOptions } from "./program.js";
 
 export type {
   AxisLabelOptions,
@@ -17,6 +17,7 @@ export type {
   CompleteAxisOptions,
   CreateAxesOptions,
   CreateBarPlotOptions,
+  CreateDataOptions,
   CreateGridOptions,
   CreateGuidesOptions,
   CreateHeatmapOptions,
@@ -111,7 +112,8 @@ type RebindMethod<T> = T extends (...args: infer Args) => ChartProgram
 
 export type BasicChartProgram =
   Pick<ChartProgram, BasicStateKey> &
-  { readonly [Key in BasicMethodKey]: RebindMethod<ChartProgram[Key]> } &
+  { readonly [Key in Exclude<BasicMethodKey, "createData">]: RebindMethod<ChartProgram[Key]> } &
+  { createData<Row extends object>(options: CreateDataOptions<Row>): BasicChartProgram } &
   { readonly layoutSeries: (options: BasicSeriesLayoutOptions) => BasicChartProgram };
 
 export function chart(): BasicChartProgram;

package/types/diagnostics.d.ts

@@ -0,0 +1,15 @@
+export type ErrorCode = "invalid-option" | "invalid-value" | "missing-resource" |
+  "ambiguous-resource" | "incompatible-resource" | "resource-in-use" |
+  "resource-limit" | "unsupported-format" | "action-failed";
+
+export interface ErrorDetails {
+  readonly code: ErrorCode;
+  readonly operation?: string;
+  readonly optionPath?: string;
+  readonly resourceId?: string;
+  readonly candidates?: readonly string[];
+  readonly limit?: number;
+  readonly actual?: number;
+}
+
+export function getErrorDetails(error: unknown): ErrorDetails | undefined;

package/types/index.d.ts

@@ -1,6 +1,11 @@
 import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
+  TextMetricFontWeight,
+  TextMeasurement,
+  TextMetricsProfile,
+  ApplyTextMetricsOptions,
+  ReviseDataOptions,
   ActionOptions,
   AxisFormat,
   AxisFormatString,

package/types/pdf.d.ts

@@ -24,3 +24,12 @@ export function renderToPDF(
   program: Pick<ChartProgram, "graphicSpec">,
   options: PDFRenderOptions
 ): Promise<PDFRenderResult>;
+
+export interface PDFBufferResult extends Omit<PDFRenderResult, "output"> {
+  readonly buffer: Uint8Array;
+}
+
+export function renderToPDFBuffer(
+  program: Pick<ChartProgram, "graphicSpec">,
+  options?: { metadata?: PDFMetadata }
+): Promise<PDFBufferResult>;

package/types/persistence.d.ts

@@ -0,0 +1,7 @@
+import type { ChartProgram } from "./program.js";
+import type { BasicChartProgram } from "./basic.js";
+
+export function serializeProgram(program: ChartProgram | BasicChartProgram): string;
+export function deserializeProgram(text: string): ChartProgram;
+export function serializeGraphic(program: Pick<ChartProgram, "graphicSpec">): string;
+export function deserializeGraphic(text: string): Readonly<Pick<ChartProgram, "graphicSpec">>;