ggaction 0.0.9 → 0.0.11

package/src/materialization/selection/items/arc.js

@@ -1,7 +1,12 @@
 import { deriveArcSectors } from "../../../grammar/arcs.js";
+import { resolvePolarPoint } from "../../../grammar/polarPaths.js";
 import { resolvePolarFrame } from "../../../grammar/polar.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
-import { finalizeItems, uniqueFields } from "./common.js";
+import {
+  concreteProperties,
+  finalizeItems,
+  uniqueFields
+} from "./common.js";
 
 export function resolveArcItems(program, layer, dataset) {
   const thetaScale = program.resolvedScales[layer.encoding?.theta?.scale];
@@ -13,7 +18,8 @@ export function resolveArcItems(program, layer, dataset) {
     frame,
     innerRadiusRatio: program.markConfigs[layer.id]?.innerRadius ?? 0
   });
-  const definitions = derived.sectors.map(sector => {
+  const graphic = program.graphicSpec.objects[layer.id];
+  const definitions = derived.sectors.map((sector, index) => {
     const members = sector.sourceIndices.map(index => dataset.values[index]);
     return {
       fields: uniqueFields(members),
@@ -22,6 +28,14 @@ export function resolveArcItems(program, layer, dataset) {
         ...(sector.radius === undefined ? {} : { radius: sector.radius }),
         ...(sector.color === undefined ? {} : { color: sector.color })
       },
+      properties: {
+        ...concreteProperties(graphic.items[index]?.properties),
+        ...resolvePolarPoint(
+          frame,
+          (sector.startTheta + sector.endTheta) / 2,
+          (sector.innerRadius + sector.outerRadius) / 2
+        )
+      },
       members
     };
   });

package/src/materialization/selection/items/bar.js

@@ -6,6 +6,7 @@ import {
   resolveBarOffsetChannel,
   resolveBarGrain
 } from "../../../grammar/bars/policy.js";
+import { numericExtent } from "../../../grammar/numeric.js";
 import { layoutSeriesPartition } from "../../../grammar/seriesLayout.js";
 import {
   readNominalField,
@@ -215,14 +216,15 @@ function barStackDefinitions(layer, barGrain, definitions) {
         `Bar mark "${layer.id}" stack ${index} has no resolved semantic endpoints.`
       );
     }
+    const [minimum, maximum] = numericExtent(endpoints);
     const members = grouped.flatMap(definition => definition.members);
     return {
       key: itemKey(layer, "stack", index),
       fields: uniqueFields(members),
       channels: {
         ...sharedChannels(grouped),
-        [measure]: Math.min(...endpoints),
-        [secondary]: Math.max(...endpoints)
+        [measure]: minimum,
+        [secondary]: maximum
       },
       members,
       graphicIndices: entries.map(entry => entry.index)

package/src/materialization/selection/items/common.js

@@ -1,5 +1,8 @@
 import { cloneAndFreeze, isPlainObject } from "../../../core/immutable.js";
-import { MARK_GRAPHIC_PROPERTIES } from "../../../grammar/markSelection.js";
+import {
+  MARK_GRAPHIC_PROPERTIES,
+  selectMarkItemKeys
+} from "../../../grammar/markSelection.js";
 import { unionConcreteGraphicBounds } from
   "../../../grammar/schemas/graphicBounds.js";
 
@@ -129,3 +132,20 @@ export function finalizeItems(program, layer, grain, definitions, graphicType) {
     });
   }));
 }
+
+export function reorderHighlightedItems(program, layer, definitions) {
+  let ordered = definitions;
+  for (const config of Object.values(
+    program.materializationConfigs.highlights ?? {}
+  )) {
+    if (config.target !== layer.id || config.bringToFront !== true) continue;
+    const selection = program.materializationConfigs.selections?.[config.selection];
+    if (selection?.target !== layer.id) continue;
+    const selected = new Set(selectMarkItemKeys(ordered, selection.selector));
+    ordered = [
+      ...ordered.filter(definition => !selected.has(definition.key)),
+      ...ordered.filter(definition => selected.has(definition.key))
+    ];
+  }
+  return ordered;
+}

package/src/materialization/selection/items/path.js

@@ -3,8 +3,12 @@ import {
   deriveAreaSeries,
   deriveDensityAreaSeries
 } from "../../../grammar/areaSeries.js";
-import { deriveLineSeries } from "../../../grammar/lineSeries.js";
+import {
+  deriveLineSeries,
+  resolveLineBins
+} from "../../../grammar/lineSeries.js";
 import { findUpstreamTransform } from "../../dataProvenance.js";
+import { requireSemanticScale } from "../../../selectors/scales.js";
 import {
   channelMapFromRow,
   finalizeItems,
@@ -61,7 +65,20 @@ export function resolveLineItems(program, layer, dataset) {
     });
     return finalizeItems(program, layer, "row", definitions, "path");
   }
-  const derived = deriveLineSeries(dataset.values, layer);
+  const x = layer.encoding?.x;
+  const derived = deriveLineSeries(
+    dataset.values,
+    layer,
+    x?.bin === undefined
+      ? undefined
+      : {
+          xBinBoundaries: resolveLineBins(
+            dataset.values,
+            layer,
+            requireSemanticScale(program, x.scale)
+          ).boundaries
+        }
+  );
   return finalizeItems(
     program,
     layer,

package/src/materialization/selection/items/point.js

@@ -1,10 +1,10 @@
-import { selectMarkItemKeys } from "../../../grammar/markSelection.js";
 import {
   channelMapFromRow,
   concreteProperties,
   finalizeItems,
   itemKey,
-  ownFields
+  ownFields,
+  reorderHighlightedItems
 } from "./common.js";
 
 export function resolvePointItems(program, layer, dataset) {
@@ -22,30 +22,18 @@ export function resolvePointItems(program, layer, dataset) {
   ) {
     throw new Error(`Point mark "${layer.id}" is incomplete for selection.`);
   }
-  let definitions = dataset.values.map((row, index) => ({
+  const definitions = dataset.values.map((row, index) => ({
     key: itemKey(layer, "point", index),
     fields: ownFields(row),
     channels: channelMapFromRow(row, layer),
     properties: concreteProperties(graphic.items[index]?.properties),
     members: [row]
   }));
-  for (const config of Object.values(
-    program.materializationConfigs.highlights ?? {}
-  )) {
-    if (config.target !== layer.id || config.bringToFront !== true) continue;
-    const selection = program.materializationConfigs.selections?.[config.selection];
-    if (selection?.target !== layer.id) continue;
-    const selected = new Set(selectMarkItemKeys(definitions, selection.selector));
-    definitions = [
-      ...definitions.filter(definition => !selected.has(definition.key)),
-      ...definitions.filter(definition => selected.has(definition.key))
-    ];
-  }
   return finalizeItems(
     program,
     layer,
     "point",
-    definitions,
+    reorderHighlightedItems(program, layer, definitions),
     program.graphicSpec.objects[layer.id]?.type
   );
 }

package/src/materialization/selection/items/tick.js

@@ -1,10 +1,10 @@
-import { selectMarkItemKeys } from "../../../grammar/markSelection.js";
 import {
   channelMapFromRow,
   concreteProperties,
   finalizeItems,
   itemKey,
-  ownFields
+  ownFields,
+  reorderHighlightedItems
 } from "./common.js";
 
 export function resolveTickItems(program, layer, dataset) {
@@ -15,25 +15,17 @@ export function resolveTickItems(program, layer, dataset) {
   if (!Array.isArray(graphic?.items) || !completePosition) {
     throw new Error(`Tick mark "${layer.id}" is incomplete for selection.`);
   }
-  let definitions = dataset.values.map((row, index) => ({
-    key: itemKey(layer, "tick", index),
-    fields: ownFields(row),
-    channels: channelMapFromRow(row, layer),
-    properties: concreteProperties(graphic.items[index]?.properties),
-    members: [row]
-  }));
-  for (const config of Object.values(
-    program.materializationConfigs.highlights ?? {}
-  )) {
-    if (config.target !== layer.id || config.bringToFront !== true) continue;
-    const selection = program.materializationConfigs.selections?.[config.selection];
-    if (selection?.target !== layer.id) continue;
-    const selected = new Set(selectMarkItemKeys(definitions, selection.selector));
-    definitions = [
-      ...definitions.filter(definition => !selected.has(definition.key)),
-      ...definitions.filter(definition => selected.has(definition.key))
-    ];
-  }
+  let definitions = reorderHighlightedItems(
+    program,
+    layer,
+    dataset.values.map((row, index) => ({
+      key: itemKey(layer, "tick", index),
+      fields: ownFields(row),
+      channels: channelMapFromRow(row, layer),
+      properties: concreteProperties(graphic.items[index]?.properties),
+      members: [row]
+    }))
+  );
   definitions = definitions.map((definition, index) => ({
     ...definition,
     properties: concreteProperties(graphic.items[index]?.properties)

package/src/materialization/selection/point.js

@@ -1,4 +1,5 @@
 import { createPointShapeGraphic } from "../../grammar/pointShapes.js";
+import { finiteMidpoint } from "../../grammar/numeric.js";
 
 function pointCenterAndArea(child) {
   const properties = child.properties;
@@ -19,17 +20,23 @@ function pointCenterAndArea(child) {
   const points = properties.commands.filter(command =>
     command.op === "M" || command.op === "L"
   );
-  const xs = points.map(point => point.x);
-  const ys = points.map(point => point.y);
+  let left = Infinity;
+  let right = -Infinity;
+  let top = Infinity;
+  let bottom = -Infinity;
   let twiceArea = 0;
   for (let index = 0; index < points.length; index += 1) {
     const current = points[index];
     const next = points[(index + 1) % points.length];
+    left = Math.min(left, current.x);
+    right = Math.max(right, current.x);
+    top = Math.min(top, current.y);
+    bottom = Math.max(bottom, current.y);
     twiceArea += current.x * next.y - next.x * current.y;
   }
   return {
-    x: (Math.min(...xs) + Math.max(...xs)) / 2,
-    y: (Math.min(...ys) + Math.max(...ys)) / 2,
+    x: finiteMidpoint(left, right),
+    y: finiteMidpoint(top, bottom),
     area: Math.abs(twiceArea) / 2
   };
 }

package/src/materialization/selection/styles.js

@@ -29,6 +29,22 @@ function normalizeOffset(offset) {
   return { x, y };
 }
 
+function normalizeOptionalStroke(args, mark) {
+  const stroke = args.stroke === undefined
+    ? undefined
+    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
+  const strokeWidth = args.strokeWidth === undefined
+    ? undefined
+    : validateNonNegativeFinite(
+        args.strokeWidth,
+        `${mark} highlight strokeWidth`
+      );
+  if (strokeWidth !== undefined && stroke === undefined) {
+    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
+  }
+  return { stroke, strokeWidth };
+}
+
 export function normalizeDimOthers(dimOthers) {
   if (dimOthers === undefined || dimOthers === false) return false;
   if (dimOthers === true) return { opacity: DEFAULT_DIM_OPACITY };
@@ -58,15 +74,7 @@ export function normalizePointHighlightStyle(args) {
   const opacity = args.opacity === undefined
     ? undefined
     : validateUnitInterval(args.opacity, "Point highlight opacity");
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, "Point highlight stroke");
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, "Point highlight strokeWidth");
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error("Point highlight strokeWidth requires stroke.");
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, "Point");
   return {
     fill,
     ...(opacity === undefined ? {} : { opacity }),
@@ -96,15 +104,7 @@ function normalizeRectangularHighlightStyle(args, mark, { offset = false } = {})
   const opacity = args.opacity === undefined
     ? undefined
     : validateUnitInterval(args.opacity, `${mark} highlight opacity`);
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, mark);
   const hasAppearanceOverride = opacity !== undefined || stroke !== undefined ||
     strokeWidth !== undefined || args.offset !== undefined;
   const fill = explicitFill === undefined && hasAppearanceOverride
@@ -178,15 +178,7 @@ export function normalizeAreaHighlightStyle(args, mark = "Area") {
   if (args.color !== undefined && args.fill !== undefined) {
     throw new Error(`${mark} highlight accepts color or fill, not both.`);
   }
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, mark);
   return {
     fill: validateNonEmptyString(
       args.fill ?? args.color ?? DEFAULT_COLORS.highlight,

package/src/materialization/text.js

@@ -104,7 +104,10 @@ function relativeLuminance(color) {
 }
 
 function sourceTextConfig(config, source, item) {
-  if (source.mark.type !== "rect" || config.fillExplicit === true) return config;
+  if (
+    !["arc", "rect"].includes(source.mark.type) ||
+    config.fillExplicit === true
+  ) return config;
   const luminance = relativeLuminance(item.properties.fill);
   if (luminance === undefined) return config;
   return {

package/src/mcp/adapter.js

@@ -28,7 +28,7 @@ export const OVERVIEW_URI = "ggaction://overview";
 export const SEARCH_TOOL = Object.freeze({
   name: SEARCH_TOOL_NAME,
   title: "Search ggaction authoring knowledge",
-  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, executable immutable steps, terminal unsupported constraints, and explicit unresolved decisions.",
+  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, syntax-valid immutable steps, applied options, explicit placeholders and unmatched requirements, terminal unsupported constraints, and unresolved decisions.",
   inputSchema: Object.freeze({
     type: "object",
     additionalProperties: false,
@@ -164,6 +164,7 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
   if (uri === OVERVIEW_URI) {
     return jsonResource(uri, {
       schemaVersion: resourcesArtifact.schemaVersion,
+      packageVersion: resourcesArtifact.packageVersion,
       title: resourcesArtifact.overview.title,
       text: resourcesArtifact.overview.text
     });
@@ -184,6 +185,7 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
     if (!recipe) throw new KnowledgeResourceError(`Unknown ggaction recipe: ${id}`);
     return jsonResource(uri, {
       schemaVersion: resourcesArtifact.schemaVersion,
+      packageVersion: resourcesArtifact.packageVersion,
       ...recipe,
       packet: searchGgaction(recipe.query)
     });
@@ -201,6 +203,9 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
   throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
 }
 
-if (cardsArtifact.schemaVersion !== 1 || resourcesArtifact.schemaVersion !== 2) {
-  throw new Error("MCP action cards must use schemaVersion 1 and resources schemaVersion 2.");
+if (cardsArtifact.schemaVersion !== 2 || resourcesArtifact.schemaVersion !== 2) {
+  throw new Error("MCP action cards and resources must use schemaVersion 2.");
+}
+if (resourcesArtifact.packageVersion !== cardsArtifact.packageVersion) {
+  throw new Error("MCP action cards and resources must use one packageVersion.");
 }

package/src/renderers/canvas/fill.js

@@ -1,8 +1,8 @@
 import {
   isLinearGradientPaint,
-  resolveLinearGradientCoordinates,
   validateFillPaint
 } from "../../grammar/paint.js";
+import { resolveCanvasGradientCoordinates } from "./native.js";
 
 export function applyCanvasFill(context, fill, bounds, graphicId) {
   validateFillPaint(fill, `${graphicId}.fill`);
@@ -15,7 +15,7 @@ export function applyCanvasFill(context, fill, bounds, graphicId) {
       `Graphic "${graphicId}" requires Canvas context createLinearGradient().`
     );
   }
-  const coordinates = resolveLinearGradientCoordinates(fill, bounds);
+  const coordinates = resolveCanvasGradientCoordinates(fill, bounds, graphicId);
   const gradient = context.createLinearGradient(
     coordinates.from.x,
     coordinates.from.y,

package/src/renderers/canvas/index.js

@@ -4,6 +4,10 @@ import { drawPathGraphic } from "./path.js";
 import { drawRectGraphic } from "./rect.js";
 import { drawTextGraphic } from "./text.js";
 import { requireFiniteProperty } from "./validation.js";
+import {
+  preflightCanvasGraphicSpec,
+  requireCanvasNativeValue
+} from "./native.js";
 import {
   requireSingleOrderedGraphicByType,
   walkGraphicTreeEvents
@@ -34,6 +38,8 @@ const DRAWING_CONTEXT_METHODS = Object.freeze([
   "rotate",
   "fillText"
 ]);
+const MAX_RASTER_DIMENSION = 32_767;
+const MAX_RASTER_PIXELS = 16_777_216;
 
 function requireDrawingContext(context) {
   if (context === null || typeof context !== "object") {
@@ -182,12 +188,39 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
   if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
     throw new RangeError("render pixelRatio must be a positive finite number.");
   }
+  requireCanvasNativeValue(pixelRatio, "render Canvas pixelRatio");
+  if (Math.fround(pixelRatio) === 0) {
+    throw new RangeError(
+      "render Canvas pixelRatio must remain positive at native precision."
+    );
+  }
 
   const target = resolveGraphicRenderTarget(graphicSpec);
   const { width, height } = target;
+  const physicalWidth = Math.max(1, Math.round(width * pixelRatio));
+  const physicalHeight = Math.max(1, Math.round(height * pixelRatio));
+  if (![physicalWidth, physicalHeight].every(Number.isSafeInteger)) {
+    throw new RangeError(
+      "render physical Canvas dimensions must be finite safe integers."
+    );
+  }
+  if (
+    physicalWidth > MAX_RASTER_DIMENSION ||
+    physicalHeight > MAX_RASTER_DIMENSION
+  ) {
+    throw new RangeError(
+      `render physical Canvas dimensions must not exceed ${MAX_RASTER_DIMENSION}.`
+    );
+  }
+  if (physicalWidth * physicalHeight > MAX_RASTER_PIXELS) {
+    throw new RangeError(
+      `render physical Canvas pixel count must not exceed ${MAX_RASTER_PIXELS}.`
+    );
+  }
+  preflightCanvasGraphicSpec(target, pixelRatio);
 
-  context.canvas.width = Math.round(width * pixelRatio);
-  context.canvas.height = Math.round(height * pixelRatio);
+  context.canvas.width = physicalWidth;
+  context.canvas.height = physicalHeight;
   if (
     context.canvas.style !== null &&
     typeof context.canvas.style === "object"

package/src/renderers/canvas/native.js

@@ -0,0 +1,160 @@
+import { resolveLinearGradientCoordinates } from "../../grammar/paint.js";
+import { resolvePathCommandBounds } from
+  "../../grammar/schemas/graphicBounds.js";
+import { walkGraphicTreeEvents } from
+  "../../grammar/schemas/graphicTree.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+const MAX_NATIVE_VALUE = 16_777_216;
+const NATIVE_PROPERTIES = {
+  canvas: ["x", "y", "width", "height"],
+  circle: ["x", "y", "radius", "strokeWidth"],
+  rect: ["x", "y", "width", "height", "strokeWidth"],
+  line: ["x1", "y1", "x2", "y2", "strokeWidth"],
+  path: ["strokeWidth"],
+  text: ["x", "y", "fontSize"]
+};
+const COMMAND_PROPERTIES = ["x", "y", "x1", "y1", "x2", "y2"];
+
+export function requireCanvasNativeValue(value, label, scale = 1, offset = 0) {
+  const magnitude = Math.abs(value) + Math.abs(offset);
+  const scaled = magnitude * scale;
+  if (
+    !Number.isFinite(value) || magnitude > MAX_NATIVE_VALUE ||
+    !Number.isFinite(scaled) || scaled > MAX_NATIVE_VALUE
+  ) {
+    throw new RangeError(
+      `${label} must be finite with magnitude <= ${MAX_NATIVE_VALUE}.`
+    );
+  }
+}
+
+function requireValues(values, label, scale) {
+  for (const value of values) {
+    requireCanvasNativeValue(value, label, scale);
+  }
+}
+
+function requireProperties(properties, keys, label, scale, offset) {
+  for (const key of keys) {
+    const value = properties?.[key];
+    if (value !== undefined) {
+      requireCanvasNativeValue(
+        value,
+        label,
+        scale,
+        offset?.["xy".indexOf(key[0])]
+      );
+    }
+  }
+}
+
+export function resolveCanvasGradientCoordinates(fill, bounds, graphicId, scale = 1) {
+  const coordinates = resolveLinearGradientCoordinates(fill, bounds);
+  requireValues([
+    coordinates.from.x,
+    coordinates.from.y,
+    coordinates.to.x,
+    coordinates.to.y,
+    Math.hypot(
+      coordinates.to.x - coordinates.from.x,
+      coordinates.to.y - coordinates.from.y
+    )
+  ],
+    `Graphic "${graphicId}" Canvas linear gradient geometry`,
+    scale
+  );
+  return coordinates;
+}
+
+function preflightGraphic(id, graphic, scale, type, offset) {
+  const properties = graphic.properties ?? {};
+  const label = `Graphic "${id}" Canvas native geometry`;
+  requireProperties(
+    properties,
+    NATIVE_PROPERTIES[type] ?? [],
+    label,
+    scale,
+    offset
+  );
+  if (properties.rotation !== undefined) {
+    requireCanvasNativeValue(properties.rotation, label);
+  }
+  if (Array.isArray(properties.strokeDash)) {
+    requireValues(properties.strokeDash, label, scale);
+  }
+  const gradient = properties.fill?.type === "linear-gradient";
+
+  let bounds;
+  if (type === "canvas" || type === "rect" || type === "circle") {
+    const circle = type === "circle";
+    const width = circle ? properties.radius : properties.width;
+    const height = circle ? properties.radius : properties.height;
+    if ([properties.x, properties.y, width, height].every(Number.isFinite) &&
+      width >= 0 && height >= 0) {
+      bounds = {
+        left: properties.x - (circle ? width : 0),
+        right: properties.x + width,
+        top: properties.y - (circle ? height : 0),
+        bottom: properties.y + height
+      };
+      requireCanvasNativeValue(bounds.left, label, scale, offset?.[0]);
+      requireCanvasNativeValue(bounds.right, label, scale, offset?.[0]);
+      requireCanvasNativeValue(bounds.top, label, scale, offset?.[1]);
+      requireCanvasNativeValue(bounds.bottom, label, scale, offset?.[1]);
+    }
+  }
+  if (type === "path" && Array.isArray(properties.commands)) {
+    for (const command of properties.commands) {
+      requireProperties(command, COMMAND_PROPERTIES, label, scale, offset);
+    }
+    if (gradient) {
+      bounds = resolvePathCommandBounds(properties.commands);
+    }
+  }
+  if (gradient && bounds) {
+    resolveCanvasGradientCoordinates(properties.fill, bounds, id, scale);
+  }
+  if (NATIVE_PROPERTIES[type] !== undefined) {
+    validateConcreteGraphicProperties(type, properties);
+  }
+}
+
+export function preflightCanvasGraphicSpec(target, scale = 1) {
+  const offsets = [];
+  walkGraphicTreeEvents(target.graphicSpec, {
+    enter({ id, object }) {
+      let offset = offsets.at(-1);
+      if (object.type === "canvas") {
+        const parent = offset ?? [0, 0];
+        const properties = object.properties ?? {};
+        const x = id === target.canvasId ? 0 : properties.x;
+        const y = id === target.canvasId ? 0 : properties.y;
+        const effective = [parent[0] + x, parent[1] + y];
+        if (Number.isFinite(x) && Number.isFinite(y)) {
+          requireValues(
+            effective,
+            `Graphic "${id}" Canvas nested translation`,
+            scale
+          );
+        }
+        offsets.push(effective);
+        offset = id === target.canvasId ? undefined : parent;
+      }
+      preflightGraphic(id, object, scale, object.type, offset);
+    },
+    item({ id, object, owner }) {
+      preflightGraphic(
+        id,
+        object,
+        scale,
+        object.type ?? owner.type,
+        offsets.at(-1)
+      );
+    },
+    exit({ object }) {
+      if (object.type === "canvas") offsets.pop();
+    }
+  });
+}

package/src/renderers/pdf.js

@@ -8,6 +8,7 @@ import {
   requireProgramGraphicSpec,
   resolveGraphicRenderTarget
 } from "./canvas/index.js";
+import { preflightCanvasGraphicSpec } from "./canvas/native.js";
 
 const PDF_OPTIONS = new Set(["output", "metadata"]);
 const PDF_METADATA = new Set([
@@ -16,6 +17,7 @@ const PDF_METADATA = new Set([
   "subject",
   "keywords"
 ]);
+const MAX_PDF_DIMENSION = 16_777_216;
 
 function requirePlainObject(value, label) {
   if (
@@ -93,10 +95,22 @@ function renderPDFBuffer(target, metadata) {
   return document.close();
 }
 
+function requirePDFPageDimensions(target) {
+  if (![target.width, target.height].every(value =>
+    Number.isSafeInteger(value) && value > 0 && value <= MAX_PDF_DIMENSION
+  )) {
+    throw new RangeError(
+      `PDF page dimensions must be positive integers no larger than ${MAX_PDF_DIMENSION}.`
+    );
+  }
+}
+
 export async function renderToPDF(program, options = {}) {
   const { output, metadata } = requirePDFOptions(options);
   const graphicSpec = requireProgramGraphicSpec(program);
   const target = resolveGraphicRenderTarget(graphicSpec);
+  requirePDFPageDimensions(target);
+  preflightCanvasGraphicSpec(target);
   const buffer = renderPDFBuffer(target, metadata);
 
   await mkdir(dirname(output), { recursive: true });