ggaction 0.0.21 → 0.0.22

package/src/materialization/text.js

@@ -5,11 +5,10 @@ import {
   resolveMarkLabelPlacement
 } from "../layout/labels.js";
 import { resolveMarkLabelValues } from "../grammar/markLabels.js";
-import { formatTextValue, resolveTextLines } from "../grammar/text.js";
+import { formatTextValue, resolveTextLines, resolveTextOffsetDataset, textOffsetValue } from "../grammar/text.js";
 import { normalizePositionDatum } from "../grammar/positionDatum.js";
 import { mapOrdinalPositionValues } from "../grammar/scales/index.js";
 import { findDataset } from "../selectors/datasets.js";
-import { applyItemMissingPolicy } from "../grammar/itemMissing.js";
 import { findCoordinate } from "../selectors/coordinates.js";
 import { findLayer } from "../selectors/layers.js";
 import { unionConcreteGraphicBounds } from
@@ -427,8 +426,9 @@ function resolveRowTextItems(program, layer, config) {
   if (sourceDataset === undefined) {
     throw new Error(`Text mark "${layer.id}" requires an existing dataset.`);
   }
-  const dataset = applyItemMissingPolicy(layer, sourceDataset);
-  const encodings = [layer.encoding?.x, layer.encoding?.y, layer.encoding?.text, layer.encoding?.color];
+  const dataset = resolveTextOffsetDataset(layer, sourceDataset);
+  const encodings = [layer.encoding?.x, layer.encoding?.y, layer.encoding?.text, layer.encoding?.color,
+    layer.encoding?.dx, layer.encoding?.dy];
   const length = encodings.some(encoding => encoding !== undefined && Object.hasOwn(encoding, "field"))
     ? dataset.values.length
     : 1;
@@ -465,7 +465,12 @@ function resolveRowTextItems(program, layer, config) {
   const fills = resolveRowEncodingValues(program, layer, dataset, "color");
   return rows.flatMap((row, index) => {
     const concrete = concreteItem(
-      fills === undefined ? config : { ...config, fill: fills[index] },
+      {
+        ...config,
+        ...(fills === undefined ? {} : { fill: fills[index] }),
+        dx: textOffsetValue(layer.encoding?.dx, row, config.dx),
+        dy: textOffsetValue(layer.encoding?.dy, row, config.dy)
+      },
       { x: x[index], y: y[index] },
       contentValue(layer.encoding.text, row),
       layer.encoding.text.format

package/src/persistence/validation.js

@@ -1,4 +1,12 @@
+import { validateGraphicClip } from "../grammar/schemas/graphicClip.js";
+import { validatePointShape } from "../grammar/pointShapes.js";
+import {deriveLookupRows,sameLookupValue} from "../grammar/lookup.js";
+import {deriveTransformSchema,datasetSchemaContext} from "../grammar/datasetSchema.js";
+import {orderedDatasetAncestors} from "../grammar/datasetDependencies.js";
+import {validateLegendSpacing} from "../grammar/legendSpacing.js";
+import { requestedMarkClip, validateMarkClipCoordinate } from "../selectors/markClip.js";
 import { validateAuthoredFacetLegend } from "../grammar/facets/legendIntent.js";
+import { validateFacetHeaderRotations } from "../grammar/facetHeaders.js";
 import { AXIS_RESOURCE_CHANNELS } from "../core/vocabulary.js";
 import { cartesianAxisOwners, assertCartesianAxisSideAvailable } from "../selectors/axes.js";
 import { axisGraphicIds } from "../selectors/axes.js";
@@ -20,16 +28,19 @@ import { validateGraphicItemLimit } from "../core/validation.js";
 import { LEGEND_TITLE_STYLE_KEYS, validateLegendTitleAlignment } from "../grammar/legendTitleStyle.js";
 import { validateGuideDash, normalizeGuideDashMap } from "../grammar/guideDash.js";
 import { validateAxisTextPlacement } from "../grammar/axisTextPlacement.js";
+import { validateTickSelectionRounding, axisTickSelection } from "../grammar/ticks.js";
 import { validateAreaPaintConfig } from "../grammar/areaPaint.js";
 import { validateOptionObject, validateKeys, validatePositiveFinite, validateNonNegativeFinite, validateNonEmptyString, validateGeneratedItemLimit } from "../core/validation.js";
 import { validateRegressionFitStatistics, requireRegressionStatisticsSource, regressionStatisticsRows } from "../grammar/regression/statistics.js";
 import { resolveGraphicItemCapacity } from "../selectors/graphicCapacity.js";
 import { isContinuousColorScaleType } from "../grammar/scales/types.js";
+import { validateTickColorChannels } from "../grammar/scales/colorConsumers.js";
 import { normalizeColorInterpolationOptions } from "../grammar/scales/color.js";
 import { normalizeTransformParameters } from "../grammar/scales/transformed.js";
 import { validateLegendGroupState } from "../grammar/legendGroups.js";
 import { normalizeGradientDirection, validateLegendGradient } from "../grammar/legendGradient.js";
 import { normalizeTextMetricProfile } from "../core/textMetricProfile.js";
+import { resolveTextOffsetDataset } from "../grammar/text.js";
 import { isPlainObject } from "../core/immutable.js";
 import { validateUserId } from "../core/identifiers.js";
 import { collectAllResourceReferences } from "../core/resourceReferences.js";
@@ -48,6 +59,21 @@ export const STATE_KEYS = Object.freeze([
   "children", "compositionSpec", "context", "trace", "actionStack"
 ]);
 
+function validateStoredColorLegendSampling(program, config, path) {
+  requireObject(config.sampling, path);
+  const sample = config.sampling;
+  exactKeys(sample, sample.mode === "values" ? ["mode", "values", "count"] : ["mode", "count"], path);
+  if (!["auto", "values"].includes(sample.mode)) throw invalidSnapshot("Invalid color legend sample mode.", path);
+  if (!Number.isInteger(sample.count) || sample.count < 2) throw invalidSnapshot("Invalid color legend sample count.", path);
+  validateGeneratedItemLimit(sample.count, "Color legend sample count");
+  const scale = program.resolvedScales[config.scale];
+  if (!isContinuousColorScaleType(scale?.type)) throw invalidSnapshot("Sampled color legend requires a continuous color scale.", path);
+  if (sample.mode === "values") {
+    requireArray(sample.values, path);
+    if (!sample.values.length || sample.values.length > 100 || sample.values.some((value, index) => !Number.isFinite(value) || index > 0 && value <= sample.values[index - 1] || value < Math.min(...scale.domain) || value > Math.max(...scale.domain) || scale.type === "log" && value <= 0)) throw invalidSnapshot("Invalid exact color legend samples.", path);
+  }
+}
+
 export function requireObject(value, path) {
   if (!isPlainObject(value)) throw invalidSnapshot(`${path} must be a plain object.`, path);
 }
@@ -79,9 +105,10 @@ export function validateGraphic(graphic, path = "payload.graphicSpec") {
     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))) {
+    if (Object.keys(object).some(key => !["type", "properties", "items", "children", "clip"].includes(key))) {
       throw invalidSnapshot(`Unknown graphic member at ${id}.`, path);
     }
+    if (object.clip !== undefined) validateGraphicClip(object.clip, object.type);
     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);
@@ -143,7 +170,7 @@ function validateSemanticProperties(program, value, property) {
   validateStoredSemanticValue(program, parsed, value);
 }
 
-export function validateProgramState(program, path) {
+export function validateProgramState(program, path, { allowMissingLookupSchemas = false } = {}) {
   const semantic = program.semanticSpec;
   exactKeys(semantic, ["datasets", "layers", "scales", "coordinates", "guides", "title"], `${path}.semanticSpec`);
   const resources = new Map();
@@ -161,6 +188,12 @@ export function validateProgramState(program, path) {
     }
     resources.set(referenceKind, entries);
     for (const resource of entries.values()) {
+      if (kind === "layer") validateTickColorChannels(resource);
+      if (kind === "layer" && ["dx", "dy"].some(channel => resource.encoding?.[channel] !== undefined)) {
+        const dataset = semantic.datasets.find(item => item.id === resource.data);
+        if (dataset === undefined) throw new Error("Numeric text offsets require an existing dataset.");
+        resolveTextOffsetDataset(resource, dataset);
+      }
       if (kind === "scale") {
         normalizeColorInterpolationOptions(resource.interpolate, resource);
         if (resource.type === "pow") normalizeTransformParameters("pow", {
@@ -181,6 +214,13 @@ export function validateProgramState(program, path) {
   if (program.compositionSpec?.type === "facet" && isPlainObject(program.compositionSpec.facet.guides.legend)) {
     validateAuthoredFacetLegend(program, program.compositionSpec.facet.guides.legend);
   }
+  if (program.compositionSpec?.type === "facet") {
+    const headers = program.materializationConfigs.facets?.[program.compositionSpec.id]?.headers;
+    if (headers !== undefined) validateFacetHeaderRotations(headers);
+    if (headers?.row?.title !== undefined && program.compositionSpec.facet.grid === undefined) {
+      throw new TypeError("Facet row field title requires a row-column facet grid.");
+    }
+  }
   if (program.materializationConfigs.textMetrics !== undefined) normalizeTextMetricProfile(program.materializationConfigs.textMetrics);
   for (const config of [
     ...Object.values(program.guideConfigs.axis ?? {}).map(axis => axis.ticks),
@@ -189,17 +229,54 @@ export function validateProgramState(program, path) {
     if (config?.strokeDash !== undefined) validateGuideDash(config.strokeDash);
     if (config?.strokeDashMap !== undefined) normalizeGuideDashMap(config.strokeDashMap, { reset: false });
   }
-  for (const owner of cartesianAxisOwners(program)) {
+  const cartesianOwners = cartesianAxisOwners(program);
+  for (const [id, axis] of Object.entries(program.guideConfigs.axis ?? {})) {
+    for (const config of [axis?.ticks, axis?.labels]) {
+      if (config === undefined || !Object.hasOwn(config, "rounding")) continue;
+      if (!cartesianOwners.some(owner => owner.id === id)) {
+        throw invalidSnapshot("Tick rounding requires a Cartesian axis owner.", path);
+      }
+      validateTickSelectionRounding(config, program.resolvedScales[config.scale]?.type);
+    }
+  }
+  for (const owner of cartesianOwners) {
     const channel = owner.id;
     const axis = owner.config;
+    if (axis?.ticks && axis?.labels &&
+        (Object.hasOwn(axis.ticks, "rounding") || Object.hasOwn(axis.labels, "rounding")) &&
+        JSON.stringify(axisTickSelection(axis.ticks)) !== JSON.stringify(axisTickSelection(axis.labels))) {
+      throw invalidSnapshot("Stored tick rounding conflicts with axis labels.", path);
+    }
     if (axis?.frame !== undefined) {
-      exactKeys(axis.frame, ["offset"], `${path}.guides.axis.${channel}.frame`);
-      validateNonNegativeFinite(axis.frame.offset, "Axis frame offset");
+      validateOptionObject(axis.frame, ["offset", "underlay"], `Stored axis "${channel}" frame`, { allowEmpty: false });
+      if (Object.hasOwn(axis.frame, "offset")) validateNonNegativeFinite(axis.frame.offset, "Axis frame offset");
+      if (Object.hasOwn(axis.frame, "underlay") && axis.frame.underlay !== true) {
+        throw new Error("Stored axis underlay must be canonical true intent.");
+      }
     }
     if (axis?.labels !== undefined) validateAxisTextPlacement(axis.labels);
     if (axis?.title !== undefined) validateAxisTextPlacement(axis.title, { title: true });
   }
+  for (const config of Object.values(program.guideConfigs.grid ?? {})) {
+    if (!Object.hasOwn(config, "rounding")) continue;
+    validateTickSelectionRounding(config, program.resolvedScales[config.scale]?.type);
+    const owners = cartesianOwners.map(owner => owner.config?.ticks)
+      .filter(ticks => ticks?.scale === config.scale);
+    if (config.inferredValues !== true || config.rounding !== "nearest" || owners.length === 0 ||
+        owners.some(ticks => JSON.stringify(axisTickSelection(ticks)) !== JSON.stringify(axisTickSelection(config)))) {
+      throw invalidSnapshot("Stored grid rounding requires its matching inferred tick policy.", path);
+    }
+  }
+  const border = program.materializationConfigs.canvas?.plotBorder;
+  if (isPlainObject(border) && Object.hasOwn(border, "underlay") && border.underlay !== true) {
+    throw new Error("Stored plot border underlay must be canonical true intent.");
+  }
   for (const id of Object.keys(program.guideConfigs.axis ?? {})) {
+    const config = program.guideConfigs.axis[id];
+    if (config?.frame !== undefined && Object.hasOwn(config.frame, "underlay") &&
+        !cartesianOwners.some(owner => owner.id === id)) {
+      throw new Error("Stored axis underlay requires a Cartesian axis owner.");
+    }
     if (!AXIS_RESOURCE_CHANNELS.includes(id) && !Object.hasOwn(program.semanticSpec.guides.axis ?? {}, id)) {
       throw invalidSnapshot("Named axis configs require their semantic owner.", path);
     }
@@ -242,6 +319,7 @@ export function validateProgramState(program, path) {
   if (program.guideConfigs.legendGroups !== undefined) validateLegendGroupState(program.guideConfigs.legendGroups);
   for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
     validateLegendClip(kind,config);
+    validateLegendSpacing(kind,config);
     if (localLegendPosition(config) !== undefined) {
       const descriptor = describeLegendBlock(program, kind, config);
       for (const [key, override] of Object.entries(config.blockOverrides)) {
@@ -301,22 +379,17 @@ export function validateProgramState(program, path) {
     if (["gradient", "strokeGradient"].includes(kind) && config.representation !== "symbols") {
       validateLegendGradient(config.gradient, "Stored legend gradient");
     }
+    if (["gradient", "strokeGradient"].includes(kind) && config.representation !== "symbols" && config.sampling !== undefined) {
+      validateStoredColorLegendSampling(program, config, path);
+      if (config.sampling.mode !== "values" || config.count !== config.sampling.count) {
+        throw invalidSnapshot("Gradient exact sampling must retain its automatic count.", path);
+      }
+    }
     if (config.representation === undefined) continue;
     if (kind !== "gradient" || !["symbols", "gradient"].includes(config.representation)) throw invalidSnapshot("Invalid continuous color legend representation.", path);
     if (config.representation === "symbols") {
       if (config.gradient !== undefined) throw invalidSnapshot("Symbol color legend cannot store gradient dimensions.", path);
-      requireObject(config.sampling, path);
-      const sample = config.sampling;
-      exactKeys(sample, sample.mode === "values" ? ["mode", "values", "count"] : ["mode", "count"], path);
-      if (!["auto", "values"].includes(sample.mode)) throw invalidSnapshot("Invalid color legend sample mode.", path);
-      if (!Number.isInteger(sample.count) || sample.count < 2) throw invalidSnapshot("Invalid color legend sample count.", path);
-      validateGeneratedItemLimit(sample.count, "Color legend sample count");
-      const scale = program.resolvedScales[config.scale];
-      if (!isContinuousColorScaleType(scale?.type)) throw invalidSnapshot("Sampled color legend requires a continuous color scale.", path);
-      if (sample.mode === "values") {
-        requireArray(sample.values, path);
-        if (!sample.values.length || sample.values.length > 100 || sample.values.some((value, index) => !Number.isFinite(value) || index > 0 && value <= sample.values[index - 1] || value < Math.min(...scale.domain) || value > Math.max(...scale.domain) || scale.type === "log" && value <= 0)) throw invalidSnapshot("Invalid exact color legend samples.", path);
-      }
+      validateStoredColorLegendSampling(program, config, path);
       requireObject(config.symbol, path);
       validateKeys(config.symbol, ["type", "radius", "stroke", "strokeWidth"], "Stored sampled color symbol");
       if (config.symbol.type !== "point") throw invalidSnapshot("Invalid sampled color symbol type.", path);
@@ -326,7 +399,7 @@ export function validateProgramState(program, path) {
       if (!["left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"].includes(config.position) || !["horizontal", "vertical"].includes(config.direction) || config.layout !== "edge" || !["left", "center", "right"].includes(config.align) || !["top", "left"].includes(config.titlePosition) || config.columns !== undefined && (!Number.isInteger(config.columns) || config.columns < 1)) throw invalidSnapshot("Invalid sampled color item layout.", path);
       validatePositiveFinite(config.itemGap, "Stored sampled color itemGap");
       validateNonNegativeFinite(config.offset, "Stored sampled color offset");
-    } else if (["sampling", "symbol", "columns", "direction", "layout"].some(key => config[key] !== undefined)) throw invalidSnapshot("Gradient color legend cannot store symbol representation settings.", path);
+    } else if (["symbol", "columns", "direction", "layout"].some(key => config[key] !== undefined)) throw invalidSnapshot("Gradient color legend cannot store symbol representation settings.", path);
   }
 
   const regressionFits = program.materializationConfigs.regressionFits ?? {};
@@ -336,6 +409,18 @@ export function validateProgramState(program, path) {
     validateRegressionFitStatistics(cache, dataset, resources.get("data").get(dataset?.source));
   }
   for (const dataset of semantic.datasets) {
+    if(dataset.transform?.[0]?.type==="lookup"){
+      orderedDatasetAncestors(semantic.datasets,dataset.id);
+      const transform=dataset.transform[0],source=resources.get("data").get(dataset.source),right=resources.get("data").get(transform.lookup.data);
+      if(source===undefined||right===undefined)throw invalidSnapshot("Lookup requires both existing input datasets.",path);
+      const missingSchemas = [source, right, dataset].some(input => input.schema === undefined);
+      if (!allowMissingLookupSchemas || !missingSchemas) {
+        const schema=deriveTransformSchema(source.schema,transform,dataset.values,
+          datasetSchemaContext(source,transform,dataset.id,id=>resources.get("data").get(id)));
+        if(!sameLookupValue(dataset.schema,schema))throw invalidSnapshot("Lookup schema does not match both inputs.",path);
+      }
+      if(dataset.values!==undefined&&!sameLookupValue(dataset.values,deriveLookupRows(source.values,right.values,transform)))throw invalidSnapshot("Lookup values do not match both input datasets.",path);
+    }
     if (dataset.transform?.[0]?.type !== "regressionStatistics") continue;
     const fit = resources.get("data").get(dataset.source);
     requireRegressionStatisticsSource(fit);
@@ -378,7 +463,12 @@ export function validateProgramState(program, path) {
     }
   }
   for (const id of Object.keys(program.markConfigs)) {
+    requestedMarkClip(program.markConfigs[id]);
+    validateMarkClipCoordinate(program, resources.get("mark").get(id), program.markConfigs[id].clip);
     if (!resources.get("mark").has(id)) throw invalidSnapshot(`Mark config "${id}" has no layer owner.`, path);
+    if (resources.get("mark").get(id).mark.type === "point" && program.markConfigs[id].shape !== undefined) {
+      validatePointShape(program.markConfigs[id].shape);
+    }
     if (resources.get("mark").get(id).mark.type === "area") {
       validateAreaPaintConfig(program.markConfigs[id]);
     }

package/src/persistence.js

@@ -7,6 +7,7 @@ import { decodeValue, encodeValue, encodeSharedValue, invalidSnapshot } from "./
 import { exactKeys, requireObject, STATE_KEYS, validateGraphic, validateProgramState, validateTrace } from "./persistence/validation.js";
 import {
   deriveTransformSchema,
+  datasetSchemaContext,
   inferDatasetSchema,
   validateDatasetSchema
 } from "./grammar/datasetSchema.js";
@@ -63,7 +64,7 @@ function restoreState(state, extensions, path = "payload", { requireSchemas = fa
     { requireSchemas }
   )]));
   const program = new ChartProgram({ ...state, children });
-  validateProgramState(program, path);
+  validateProgramState(program, path, { allowMissingLookupSchemas: !requireSchemas });
   if (requireSchemas) {
     for (const dataset of program.semanticSpec.datasets) {
       if (dataset.schema === undefined) {
@@ -96,7 +97,8 @@ function migrateStateSchemas(state) {
         sourceSchema,
         dataset.transform?.[0] ?? {},
         dataset.values,
-        { sourceId: dataset.source, ownerId: dataset.id, sourceTransform: byId.get(dataset.source)?.transform?.[0] }
+        datasetSchemaContext({...byId.get(dataset.source),schema:sourceSchema},dataset.transform?.[0]??{},dataset.id,
+          input=>({...byId.get(input),schema:schemaFor(input)}))
       );
     }
     active.delete(id);

package/src/renderers/canvas/index.js

@@ -1,4 +1,5 @@
 import { MAX_RASTER_DIMENSION, MAX_RASTER_PIXELS } from "./limits.js";
+import { validateGraphicClip } from "../../grammar/schemas/graphicClip.js";
 import { prepareIsolatedGlyphs, drawIsolatedGlyph } from "./isolated.js";
 import { resolveCanvasSolidPaint } from "./fill.js";
 import { annotateError } from "../../core/diagnostics.js";
@@ -158,6 +159,16 @@ export function drawResolvedGraphicSpec(target, context, options = {}) {
         enterNestedCanvas(context, id, object);
         return;
       }
+      if (object.clip !== undefined) {
+        validateGraphicClip(object.clip, object.type);
+        requireContextMethod(context, "rect", `Graphic "${id}" clip`);
+        requireContextMethod(context, "clip", `Graphic "${id}" clip`);
+        context.save();
+        context.beginPath();
+        const {x, y, width, height} = object.clip;
+        context.rect(x, y, width, height);
+        context.clip();
+      }
       if (object.type === "collection") {
         context.save();
         return;
@@ -179,6 +190,7 @@ export function drawResolvedGraphicSpec(target, context, options = {}) {
       ) {
         context.restore();
       }
+      if (object.clip !== undefined) context.restore();
     }
   });
 }
@@ -221,6 +233,10 @@ export function renderCanvasProgram(program, context, { pixelRatio = 1 } = {}, c
     ), { code: "resource-limit", operation: "render", optionPath: "physicalPixels", limit: MAX_RASTER_PIXELS, actual: physicalWidth * physicalHeight });
   }
   preflightCanvasGraphicSpec(target, pixelRatio);
+  if (Object.values(graphicSpec.objects).some(object => object.clip !== undefined)) {
+    requireContextMethod(context, "rect", "Graphic clip");
+    requireContextMethod(context, "clip", "Graphic clip");
+  }
   const isolated = prepareIsolatedGlyphs(target, context, {pixelRatio, createCanvas});
 
   context.canvas.width = physicalWidth;

package/src/renderers/canvas/isolated.js

@@ -1,4 +1,5 @@
 import { resolvePrimitiveGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
+import { graphicClipBounds, intersectClipBounds, validateGraphicClip } from "../../grammar/schemas/graphicClip.js";
 import { walkGraphicTreeEvents } from "../../grammar/schemas/graphicTree.js";
 import { MAX_RASTER_DIMENSION, MAX_RASTER_PIXELS } from "./limits.js";
 
@@ -124,10 +125,19 @@ export function prepareIsolatedGlyphs(target, context, { pixelRatio = 1, createC
         };
         frames.push({offset, clip});
       }
+      if (object.clip !== undefined) {
+        const parent = frames.at(-1);
+        validateGraphicClip(object.clip, object.type);
+        frames.push({offset: parent.offset, clip: intersectClipBounds(parent.clip,
+          graphicClipBounds(object.clip, ...parent.offset))});
+      }
       if (!object.items) plan(id, object, object.type);
     },
     item({id, object, owner}) { plan(id, object, object.type ?? owner.type); },
-    exit({object}) { if (object.type === "canvas") frames.pop(); }
+    exit({object}) {
+      if (object.clip !== undefined) frames.pop();
+      if (object.type === "canvas") frames.pop();
+    }
   });
   return {plans, surface, pixelRatio};
 }

package/src/renderers/canvas/native.js

@@ -1,4 +1,5 @@
 import { resolveLinearGradientCoordinates } from "../../grammar/paint.js";
+import { validateGraphicClip } from "../../grammar/schemas/graphicClip.js";
 import { resolvePathCommandBounds } from
   "../../grammar/schemas/graphicBounds.js";
 import { walkGraphicTreeEvents } from
@@ -143,6 +144,12 @@ export function preflightCanvasGraphicSpec(target, scale = 1) {
         offset = id === target.canvasId ? undefined : parent;
       }
       preflightGraphic(id, object, scale, object.type, offset);
+      if (object.clip !== undefined) {
+        const clip = validateGraphicClip(object.clip, object.type);
+        requireProperties(clip, ["x", "y", "width", "height"], `Graphic "${id}" Canvas clip`, scale, offset);
+        requireCanvasNativeValue(clip.x + clip.width, `Graphic "${id}" Canvas clip`, scale, offset?.[0]);
+        requireCanvasNativeValue(clip.y + clip.height, `Graphic "${id}" Canvas clip`, scale, offset?.[1]);
+      }
     },
     item({ id, object, owner }) {
       preflightGraphic(

package/src/renderers/canvas/scene.js

@@ -0,0 +1,66 @@
+import { isOwned } from '../../core/immutable.js';
+import { render } from './index.js';
+
+const compiled = new WeakMap();
+// Translate only concrete position properties. Path/text child coordinates keep
+// their authored relationship; gradients retain their local bounding-box units.
+function position(properties, dx, dy) {
+  if (!dx && !dy) return properties;
+  const result = { ...properties };
+  for (const key of ['x', 'x1', 'x2']) if (key in result) result[key] += dx;
+  for (const key of ['y', 'y1', 'y2']) if (key in result) result[key] += dy;
+  if (result.commands) result.commands = result.commands.map(command => position(command, dx, dy));
+  return result;
+}
+function compile(scene) {
+  if (scene?.version !== 2 || ![scene.width, scene.height].every(n => Number.isFinite(n) && n > 0) || !Array.isArray(scene.nodes)) {
+    throw new TypeError('renderTransitionScene requires a version 2 Canvas scene.');
+  }
+  const objects = { canvas: { type: 'canvas', properties: { width: scene.width, height: scene.height }, children: [] } };
+  const keys = new Set();
+  let index = 0, activeClips = [];
+  const groups = [objects.canvas], origins = [[0, 0]];
+  const validClip = clip => Array.isArray(clip) && clip.length === 4 &&
+    clip.every(Number.isFinite) && clip[2] >= 0 && clip[3] >= 0;
+  for (const node of scene.nodes) {
+    const clips = node.clips ?? [node.clip];
+    if (typeof node.key !== 'string' || keys.has(node.key) || !['circle','rect','line','path','text'].includes(node.type) ||
+        node.offset?.length !== 2 || !node.offset.every(Number.isFinite) || !validClip(node.clip) ||
+        !Array.isArray(clips) || !clips.every(validClip) || !node.properties || typeof node.properties !== 'object') {
+      throw new TypeError('Canvas scene nodes require unique keys, concrete properties, offsets and clips.');
+    }
+    keys.add(node.key);
+    let common = 0;
+    while (common < Math.min(clips.length, activeClips.length) &&
+        clips[common].every((value, i) => value === activeClips[common][i])) common++;
+    groups.length = common + 1; origins.length = common + 1;
+    // Retain shared concrete clip ancestors across adjacent nodes. Rebuilding
+    // a fractional ancestor between its children can change raster coverage.
+    for (let i = common; i < clips.length; i++) {
+      const clip = clips[i], origin = origins.at(-1), parent = groups.at(-1);
+      const id = `clip-${index++}`;
+      const nested = objects[id] = { type: 'canvas', properties: {
+        x: clip[0] - origin[0], y: clip[1] - origin[1], width: clip[2], height: clip[3]
+      }, children: [] };
+      parent.children.push(id); groups.push(nested); origins.push([clip[0], clip[1]]);
+    }
+    activeClips = clips;
+    const group = groups.at(-1), origin = origins.at(-1);
+    const id = `node-${index++}`;
+    objects[id] = { type: node.type, properties: position(node.properties,
+      node.offset[0] - origin[0], node.offset[1] - origin[1]) };
+    group.children.push(id);
+  }
+  return { graphicSpec: { objects, order: ['canvas'] } };
+}
+/** Paint concrete Canvas scenes with the ordinary renderer; no semantics or DOM. */
+export function renderTransitionScene(scene, context, options) {
+  // Only immutable producer scenes are cacheable. Intermediate animation frames
+  // may be reused/mutated by a caller and must always reflect their current data.
+  let program = isOwned(scene) ? compiled.get(scene) : undefined;
+  if (!program) {
+    program = compile(scene);
+    if (isOwned(scene)) compiled.set(scene, program);
+  }
+  return render(program, context, options);
+}

package/src/renderers/canvas/text.js

@@ -1,6 +1,6 @@
 import { resolveCanvasSolidPaint } from "./fill.js";
 import { requireFiniteProperty, requireStringProperty } from "./validation.js";
-import { validateConcreteGraphicProperties } from
+import { validateConcreteGraphicProperties, validateConcreteGraphicValue } from
   "../../grammar/schemas/concreteGraphic.js";
 import { normalizeRendererFontWeight } from "../text.js";
 
@@ -13,7 +13,8 @@ function drawText(context, child, collectionId) {
   const fontSize = requireFiniteProperty(properties, "fontSize", graphicId);
   const rotation = properties.rotation ?? 0;
   const opacity = properties.opacity ?? 1;
-  const text = requireStringProperty(properties, "text", graphicId);
+  const text = properties.text;
+  validateConcreteGraphicValue("text", "text", text);
   const fill = requireStringProperty(properties, "fill", graphicId);
   const fontFamily = requireStringProperty(
     properties,