ggaction 0.0.15 → 0.0.17

package/src/persistence/validation.js

@@ -0,0 +1,185 @@
+import { normalizeTextMetricProfile } from "../core/textMetricProfile.js";
+import { isPlainObject } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+import { collectAllResourceReferences } from "../core/resourceReferences.js";
+import { requiredTraceExtension } from "../core/extensionRegistry.js";
+import { resolveDatasetReference } from "../selectors/datasets.js";
+import { normalizeMarkSelector } from "../grammar/markSelection.js";
+import { parseSemanticPath } from "../grammar/schemas/semanticPath.js";
+import { validateStoredSemanticValue } from "../actions/primitives/semantic.js";
+import { validateGraphicType, isGraphicContainerType } from "../grammar/schemas/graphic.js";
+import { validateConcreteGraphicProperties } from "../grammar/schemas/concreteGraphic.js";
+import { walkGraphicTreeEvents } from "../grammar/schemas/graphicTree.js";
+import { invalidSnapshot } from "./codec.js";
+
+export const STATE_KEYS = Object.freeze([
+  "semanticSpec", "graphicSpec", "resolvedScales", "materializationConfigs",
+  "children", "compositionSpec", "context", "trace", "actionStack"
+]);
+
+export function requireObject(value, path) {
+  if (!isPlainObject(value)) throw invalidSnapshot(`${path} must be a plain object.`, path);
+}
+
+export function exactKeys(value, keys, path) {
+  requireObject(value, path);
+  if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) {
+    throw invalidSnapshot(`${path} must contain exactly: ${keys.join(", ")}.`, path);
+  }
+}
+
+function requireArray(value, path) {
+  if (!Array.isArray(value) || Array.from({ length: value.length }, (_, i) => i).some(i => !Object.hasOwn(value, i))) {
+    throw invalidSnapshot(`${path} must be a dense array.`, path);
+  }
+}
+
+export function validateGraphic(graphic, path = "payload.graphicSpec") {
+  exactKeys(graphic, ["objects", "order"], path);
+  requireObject(graphic.objects, `${path}.objects`);
+  requireArray(graphic.order, `${path}.order`);
+  const ids = new Set(Object.keys(graphic.objects));
+  function attachment(id) {
+    if (typeof id !== "string" || !Object.hasOwn(graphic.objects, id)) {
+      throw invalidSnapshot(`Unknown graphic attachment "${String(id)}".`, path);
+    }
+  }
+  for (const [id, object] of Object.entries(graphic.objects)) {
+    if (!id.length) throw invalidSnapshot("Graphic IDs must be non-empty.", path);
+    requireObject(object, `${path}.objects.${id}`);
+    validateGraphicType(object.type);
+    if (Object.keys(object).some(key => !["type", "properties", "items", "children"].includes(key))) {
+      throw invalidSnapshot(`Unknown graphic member at ${id}.`, path);
+    }
+    if (object.properties !== undefined) validateConcreteGraphicProperties(object.type, object.properties);
+    if (object.items !== undefined) {
+      if (object.type === "canvas" || object.properties !== undefined) throw invalidSnapshot(`Invalid item owner "${id}".`, path);
+      requireArray(object.items, `${path}.objects.${id}.items`);
+      for (const item of object.items) {
+        exactKeys(item, object.type === "collection" ? ["id", "type", "properties"] : ["id", "properties"], path);
+        if (typeof item.id !== "string" || !item.id.length || ids.has(item.id)) throw invalidSnapshot(`Duplicate or invalid graphic item ID "${item.id}".`, path);
+        ids.add(item.id);
+        const type = item.type ?? object.type;
+        validateGraphicType(type);
+        if (isGraphicContainerType(type)) throw invalidSnapshot("Graphic items must be primitive drawables.", path);
+        validateConcreteGraphicProperties(type, item.properties);
+      }
+    } else if (object.properties === undefined) {
+      throw invalidSnapshot(`Graphic "${id}" requires properties or items.`, path);
+    }
+    if (object.children !== undefined) {
+      if (!isGraphicContainerType(object.type)) throw invalidSnapshot(`Graphic "${id}" cannot own children.`, path);
+      requireArray(object.children, `${path}.objects.${id}.children`);
+      object.children.forEach(attachment);
+    }
+  }
+  graphic.order.forEach(attachment);
+  walkGraphicTreeEvents(graphic, {});
+}
+
+export function validateTrace(trace, ProgramClass, extensions, path = "payload.trace") {
+  const seen = new Set();
+  function visit(node, root) {
+    exactKeys(node, ["id", "op", "description", "args", "children"], path);
+    if (typeof node.description !== "string" || typeof node.op !== "string" ||
+        (root ? node.id !== "program" || node.op !== "program" : !/^a[1-9]\d*$/.test(node.id) || node.op === "program") || seen.has(node.id)) {
+      throw invalidSnapshot(`Invalid or duplicate trace node "${node.id}".`, path);
+    }
+    seen.add(node.id);
+    requireObject(node.args, `${path}.args`);
+    requireArray(node.children, `${path}.children`);
+    const extension = requiredTraceExtension(ProgramClass, node.op);
+    if (extension !== undefined) extensions.add(extension);
+    node.children.forEach(child => visit(child, false));
+  }
+  visit(trace, true);
+  // The constructor derives the next action number from the node count.
+  for (let index = 1; index < seen.size; index++) {
+    if (!seen.has(`a${index}`)) throw invalidSnapshot("Trace action IDs must be consecutive.", path);
+  }
+}
+
+function validateSemanticProperties(program, value, property) {
+  let parsed;
+  try { parsed = parseSemanticPath(property); } catch (error) {
+    if (!isPlainObject(value) || !Object.keys(value).length) throw error;
+    for (const [key, child] of Object.entries(value)) validateSemanticProperties(program, child, `${property}.${key}`);
+    return;
+  }
+  const leaf = parsed.path.at(-1);
+  if (["data", "coordinate", "scale"].includes(leaf)) validateUserId(value, property);
+  if (leaf === "field" && (typeof value !== "string" || value.length === 0)) throw invalidSnapshot(`Invalid field at ${property}.`, property);
+  validateStoredSemanticValue(program, parsed, value);
+}
+
+export function validateProgramState(program, path) {
+  const semantic = program.semanticSpec;
+  exactKeys(semantic, ["datasets", "layers", "scales", "coordinates", "guides", "title"], `${path}.semanticSpec`);
+  const resources = new Map();
+  for (const [collection, kind, referenceKind] of [
+    ["datasets", "dataset", "data"], ["layers", "layer", "mark"],
+    ["scales", "scale", "scale"], ["coordinates", "coordinate", "coordinate"]
+  ]) {
+    requireArray(semantic[collection], `${path}.semanticSpec.${collection}`);
+    const entries = new Map();
+    for (const resource of semantic[collection]) {
+      requireObject(resource, `${path}.semanticSpec.${collection}`);
+      validateUserId(resource.id, `${kind} id`);
+      if (entries.has(resource.id)) throw invalidSnapshot(`Duplicate ${kind} "${resource.id}".`, path);
+      entries.set(resource.id, resource);
+    }
+    resources.set(referenceKind, entries);
+    for (const resource of entries.values()) {
+      for (const [key, value] of Object.entries(resource)) {
+        if (key !== "id") validateSemanticProperties(program, value, `${kind}[${resource.id}].${key}`);
+      }
+    }
+  }
+  for (const [key, prefix] of [["guides", "guide"], ["title", "title"]]) {
+    requireObject(semantic[key], `${path}.semanticSpec.${key}`);
+    for (const [name, value] of Object.entries(semantic[key])) validateSemanticProperties(program, value, `${prefix}.${name}`);
+  }
+  for (const key of ["resolvedScales", "materializationConfigs", "context"]) requireObject(program[key], `${path}.${key}`);
+  for (const key of ["marks", "guides"]) requireObject(program.materializationConfigs[key], `${path}.materializationConfigs.${key}`);
+  if (program.materializationConfigs.textMetrics !== undefined) normalizeTextMetricProfile(program.materializationConfigs.textMetrics);
+  const selections = program.materializationConfigs.selections ?? {};
+  requireObject(selections, `${path}.materializationConfigs.selections`);
+  for (const [id, selection] of Object.entries(selections)) {
+    validateUserId(id, "Selection id");
+    exactKeys(selection, ["target", "selector"], `${path}.materializationConfigs.selections.${id}`);
+    validateUserId(selection.target, "Selection target");
+    normalizeMarkSelector(selection.selector);
+  }
+  resources.set("selection", new Map(Object.entries(selections)));
+  for (const reference of collectAllResourceReferences(program)) {
+    if (reference.kind === "data") resolveDatasetReference(program, reference.id);
+    else if (!resources.get(reference.kind)?.has(reference.id)) {
+      throw invalidSnapshot(`Unknown ${reference.kind} "${reference.id}" referenced by ${reference.ownerKind} "${reference.ownerId}".`, path);
+    }
+  }
+  for (const [id, scale] of Object.entries(program.resolvedScales)) {
+    requireObject(scale, `${path}.resolvedScales.${id}`);
+    requireArray(scale.domain, `${path}.resolvedScales.${id}.domain`);
+    requireArray(scale.range, `${path}.resolvedScales.${id}.range`);
+    if (!resources.get("scale").has(id) || scale.type !== resources.get("scale").get(id).type) {
+      throw invalidSnapshot(`Resolved scale "${id}" has no matching semantic owner/type.`, path);
+    }
+  }
+  for (const id of Object.keys(program.markConfigs)) {
+    if (!resources.get("mark").has(id)) throw invalidSnapshot(`Mark config "${id}" has no layer owner.`, path);
+  }
+  for (const kind of ["data", "mark"]) {
+    const visited = new Set();
+    const active = new Set();
+    function visit(resource) {
+      if (active.has(resource.id)) throw invalidSnapshot(`Cyclic ${kind} source "${resource.id}".`, path);
+      if (visited.has(resource.id)) return;
+      active.add(resource.id);
+      if (resource.source !== undefined) visit(kind === "data" ? resolveDatasetReference(program, resource.source) : resources.get(kind).get(resource.source));
+      active.delete(resource.id);
+      visited.add(resource.id);
+    }
+    for (const resource of resources.get(kind).values()) visit(resource);
+  }
+  validateGraphic(program.graphicSpec, `${path}.graphicSpec`);
+}

package/src/persistence.js

@@ -0,0 +1,147 @@
+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";
+import {
+  deriveTransformSchema,
+  inferDatasetSchema,
+  validateDatasetSchema
+} from "./grammar/datasetSchema.js";
+import { restoreResolvedScaleBindings } from "./actions/scales/preview.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: kind === "editable" ? 2 : 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");
+  const versions = kind === "editable" ? [1, 2] : [1];
+  if (!versions.includes(value.schemaVersion) || value.kind !== kind) {
+    throw invalidSnapshot(
+      `Unsupported snapshot schema or kind; expected schema ${versions.join(" or ")} ${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", { requireSchemas = false } = {}) {
+  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}`,
+    { requireSchemas }
+  )]));
+  const program = new ChartProgram({ ...state, children });
+  validateProgramState(program, path);
+  if (requireSchemas) {
+    for (const dataset of program.semanticSpec.datasets) {
+      if (dataset.schema === undefined) {
+        throw invalidSnapshot(`Dataset "${dataset.id}" requires schema in editable snapshot version 2.`, `${path}.semanticSpec.datasets`);
+      }
+      validateDatasetSchema(dataset.schema);
+    }
+  }
+  return restoreResolvedScaleBindings(program);
+}
+
+function migrateStateSchemas(state) {
+  const datasets = state.semanticSpec.datasets;
+  const byId = new Map(datasets.map(dataset => [dataset.id, dataset]));
+  const schemas = new Map();
+  const active = new Set();
+  function schemaFor(id) {
+    if (schemas.has(id)) return schemas.get(id);
+    if (active.has(id)) throw invalidSnapshot(`Cyclic data source "${id}".`, "payload.semanticSpec.datasets");
+    active.add(id);
+    const dataset = byId.get(id);
+    let schema;
+    if (dataset.schema !== undefined) {
+      schema = validateDatasetSchema(dataset.schema);
+    } else if (dataset.source === undefined) {
+      schema = inferDatasetSchema(dataset.values ?? []);
+    } else {
+      const sourceSchema = schemaFor(dataset.source);
+      schema = deriveTransformSchema(
+        sourceSchema,
+        dataset.transform?.[0] ?? {},
+        dataset.values,
+        { sourceId: dataset.source, ownerId: dataset.id }
+      );
+    }
+    active.delete(id);
+    schemas.set(id, schema);
+    return schema;
+  }
+  const semanticSpec = {
+    ...state.semanticSpec,
+    datasets: datasets.map(dataset => ({ ...dataset, schema: schemaFor(dataset.id) }))
+  };
+  return {
+    ...state,
+    semanticSpec,
+    children: Object.fromEntries(Object.entries(state.children).map(
+      ([id, child]) => [id, migrateStateSchemas(child)]
+    ))
+  };
+}
+
+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();
+  let payload = stored.payload;
+  if (stored.schemaVersion === 1) {
+    // Validate the historical state before adding any inferred metadata. Migration
+    // must never repair an invalid reference graph or malformed payload.
+    restoreState(payload, new Set());
+    payload = migrateStateSchemas(payload);
+  }
+  const program = restoreState(payload, extensions, "payload", { requireSchemas: true });
+  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;
 }