ggaction 0.0.13 → 0.0.16

package/src/materialization/text.js

@@ -1,11 +1,21 @@
 import { resolveBarChannels } from "../grammar/bars/policy.js";
+import {
+  assertMarkLabelPlacementSupport,
+  normalizeMarkLabelPlacement,
+  resolveMarkLabelPlacement
+} from "../layout/labels.js";
 import { resolveMarkLabelValues } from "../grammar/markLabels.js";
 import { formatTextValue } from "../grammar/text.js";
 import { normalizePositionDatum } from "../grammar/positionDatum.js";
 import { mapOrdinalPositionValues } from "../grammar/scales/index.js";
 import { findDataset } from "../selectors/datasets.js";
+import { findCoordinate } from "../selectors/coordinates.js";
 import { findLayer } from "../selectors/layers.js";
+import { unionConcreteGraphicBounds } from
+  "../grammar/schemas/graphicBounds.js";
+import { polarDirection } from "../grammar/polar.js";
 import { resolveMarkItems } from "./selection/policies/index.js";
+import { resolveMarkSelection } from "./selection/state.js";
 import { mapScaleConsumerValues } from "./scales/map.js";
 import { resolveRowEncodingValues } from "./rowEncoding.js";
 
@@ -83,6 +93,172 @@ function sourceAnchor(program, source, item) {
   return { x: item.properties.x, y: item.properties.y };
 }
 
+function explicitIntervalAxis(source) {
+  const axes = ["x", "y"].filter(axis =>
+    source.encoding?.[axis] !== undefined &&
+    source.encoding?.[`${axis}2`] !== undefined
+  );
+  return axes.length === 1 ? axes[0] : undefined;
+}
+
+function sourcePlacementContext(program, source) {
+  const coordinateType = findCoordinate(program, source.coordinate)?.type;
+  return {
+    markType: source.mark.type,
+    coordinateType,
+    intervalAxis: source.mark.type === "bar"
+      ? resolveBarChannels(source).measure
+      : source.mark.type === "rect"
+        ? explicitIntervalAxis(source)
+        : undefined
+  };
+}
+
+export function validateSourceMarkLabelPlacement(program, sourceId, value) {
+  const source = findLayer(program, sourceId);
+  if (source === undefined) {
+    throw new Error(`Unknown mark label placement source "${sourceId}".`);
+  }
+  const placement = normalizeMarkLabelPlacement(value);
+  assertMarkLabelPlacementSupport(sourcePlacementContext(program, source), placement);
+  return placement;
+}
+
+function rectangleBounds(item) {
+  const { x, y, width, height } = item.properties;
+  if (![x, y, width, height].every(Number.isFinite)) {
+    throw new TypeError("Interval mark label placement requires finite rectangle geometry.");
+  }
+  return {
+    left: Math.min(x, x + width),
+    right: Math.max(x, x + width),
+    top: Math.min(y, y + height),
+    bottom: Math.max(y, y + height)
+  };
+}
+
+function mappedChannel(program, source, item, channel) {
+  const value = item.channels[channel];
+  const primary = channel === "x2" ? "x" : channel === "y2" ? "y" : channel;
+  const scale = program.resolvedScales[
+    source.encoding?.[channel]?.scale ?? source.encoding?.[primary]?.scale
+  ];
+  return value === undefined || scale === undefined
+    ? undefined
+    : mapScaleConsumerValues([value], scale, channel)[0];
+}
+
+function scaleIncreaseDirection(program, source, axis) {
+  const scale = program.resolvedScales[source.encoding?.[axis]?.scale];
+  const domain = scale?.domain;
+  if (!Array.isArray(domain) || domain.length < 2) {
+    return axis === "x" ? { x: 1, y: 0 } : { x: 0, y: -1 };
+  }
+  const mapped = mapScaleConsumerValues(
+    [domain[0], domain.at(-1)],
+    scale,
+    axis
+  );
+  const delta = mapped[1] - mapped[0];
+  if (!Number.isFinite(delta) || delta === 0) {
+    return axis === "x" ? { x: 1, y: 0 } : { x: 0, y: -1 };
+  }
+  return axis === "x"
+    ? { x: Math.sign(delta), y: 0 }
+    : { x: 0, y: Math.sign(delta) };
+}
+
+function intervalPlacementGeometry(program, source, item, axis) {
+  const bounds = rectangleBounds(item);
+  const primary = mappedChannel(program, source, item, axis);
+  const secondary = mappedChannel(program, source, item, `${axis}2`);
+  if (![primary, secondary].every(Number.isFinite)) {
+    throw new TypeError(
+      `${source.mark.type === "bar" ? "Bar" : "Rect"} semantic label placement requires resolved ${axis}/${axis}2 endpoints.`
+    );
+  }
+  const cross = axis === "x"
+    ? (bounds.top + bounds.bottom) / 2
+    : (bounds.left + bounds.right) / 2;
+  const start = axis === "x" ? { x: primary, y: cross } : { x: cross, y: primary };
+  const end = axis === "x" ? { x: secondary, y: cross } : { x: cross, y: secondary };
+  const delta = { x: end.x - start.x, y: end.y - start.y };
+  const length = Math.hypot(delta.x, delta.y);
+  const endOutward = length > 0
+    ? { x: delta.x / length, y: delta.y / length }
+    : scaleIncreaseDirection(program, source, axis);
+  return {
+    kind: "interval",
+    center: {
+      x: (bounds.left + bounds.right) / 2,
+      y: (bounds.top + bounds.bottom) / 2
+    },
+    start: {
+      point: start,
+      outward: { x: -endOutward.x, y: -endOutward.y }
+    },
+    end: { point: end, outward: endOutward },
+    bounds
+  };
+}
+
+function pointPlacementGeometry(program, source, item) {
+  const center = { x: item.properties.x, y: item.properties.y };
+  const coordinateType = findCoordinate(program, source.coordinate)?.type;
+  if (coordinateType !== "polar") return { kind: "point", center };
+  const thetaScale = program.resolvedScales[source.encoding?.theta?.scale];
+  const theta = item.channels.theta === undefined || thetaScale === undefined
+    ? undefined
+    : mapScaleConsumerValues([item.channels.theta], thetaScale, "theta")[0];
+  const outward = Number.isFinite(theta) ? polarDirection(theta) : { x: 0, y: -1 };
+  const objectBounds = unionConcreteGraphicBounds(
+    program.graphicSpec,
+    item.graphicIds
+  , program.materializationConfigs.textMetrics);
+  const corners = objectBounds === undefined ? [] : [
+    { x: objectBounds.left, y: objectBounds.top },
+    { x: objectBounds.right, y: objectBounds.top },
+    { x: objectBounds.right, y: objectBounds.bottom },
+    { x: objectBounds.left, y: objectBounds.bottom }
+  ];
+  const support = Math.max(0, ...corners.map(point =>
+    (point.x - center.x) * outward.x + (point.y - center.y) * outward.y
+  ));
+  return {
+    kind: "point",
+    center,
+    end: {
+      point: {
+        x: center.x + outward.x * support,
+        y: center.y + outward.y * support
+      },
+      outward
+    }
+  };
+}
+
+function sourcePlacementGeometry(program, source, item) {
+  if (source.mark.type === "bar") {
+    return intervalPlacementGeometry(
+      program,
+      source,
+      item,
+      resolveBarChannels(source).measure
+    );
+  }
+  if (source.mark.type === "rect") {
+    const axis = explicitIntervalAxis(source);
+    return axis === undefined
+      ? { kind: "point", center: sourceAnchor(program, source, item) }
+      : intervalPlacementGeometry(program, source, item, axis);
+  }
+  if (source.mark.type === "arc") return item.geometry;
+  if (source.mark.type === "point") {
+    return pointPlacementGeometry(program, source, item);
+  }
+  return { kind: "point", center: sourceAnchor(program, source, item) };
+}
+
 function contentValue(encoding, rowOrItem, source) {
   return Object.hasOwn(encoding, "field")
     ? source === undefined
@@ -91,8 +267,7 @@ function contentValue(encoding, rowOrItem, source) {
     : encoding.datum;
 }
 
-function concreteItem(config, position, value, format) {
-  const text = formatTextValue(value, format);
+function concreteTextItem(config, position, text, { offsets = true } = {}) {
   const x = position.x;
   const y = position.y;
   if (text === undefined || !Number.isFinite(x) || !Number.isFinite(y)) {
@@ -101,8 +276,8 @@ function concreteItem(config, position, value, format) {
   return {
     type: "text",
     properties: {
-      x: x + config.dx,
-      y: y + config.dy,
+      x: x + (offsets ? config.dx : 0),
+      y: y + (offsets ? config.dy : 0),
       text,
       fill: config.fill,
       opacity: config.opacity,
@@ -116,6 +291,10 @@ function concreteItem(config, position, value, format) {
   };
 }
 
+function concreteItem(config, position, value, format) {
+  return concreteTextItem(config, position, formatTextValue(value, format));
+}
+
 function relativeLuminance(color) {
   if (typeof color !== "string" || !/^#[0-9a-f]{6}$/i.test(color)) {
     return undefined;
@@ -147,18 +326,90 @@ function resolveSourceTextItems(program, layer, config) {
   if (source === undefined) {
     throw new Error(`Text mark "${layer.id}" requires source layer "${layer.source}".`);
   }
-  const items = resolveMarkItems(program, source.id);
-  const values = layer.encoding.text.content === undefined ? undefined
-    : resolveMarkLabelValues(source, items, layer.encoding.text);
-  return items.flatMap((item, index) => {
-    const anchor = sourceAnchor(program, source, item);
-    const concrete = concreteItem(
-      sourceTextConfig(config, source, item),
-      anchor,
-      values === undefined ? contentValue(layer.encoding.text, item, source) : values[index],
+  const requested = program.markConfigs[layer.id]?.labelAuthoring?.selection ?? {
+    kind: "all"
+  };
+  let allItems;
+  let items;
+  if (requested.kind === "all") {
+    allItems = resolveMarkItems(program, source.id);
+    items = allItems;
+  } else if (requested.kind === "inline") {
+    const resolved = resolveMarkSelection(program, source.id, requested.selector);
+    allItems = resolved.items;
+    const selected = new Set(resolved.keys);
+    items = allItems.filter(item => selected.has(item.key));
+  } else if (requested.kind === "named") {
+    const definition = program.materializationConfigs.selections?.[requested.id];
+    if (definition === undefined) {
+      throw new Error(`Unknown label selection "${requested.id}".`);
+    }
+    if (definition.target !== source.id) {
+      throw new Error(
+        `Label selection "${requested.id}" must target source mark "${source.id}".`
+      );
+    }
+    const resolved = resolveMarkSelection(program, source.id, definition.selector);
+    allItems = resolved.items;
+    const selected = new Set(resolved.keys);
+    items = allItems.filter(item => selected.has(item.key));
+  } else {
+    throw new Error(`Unknown label selection kind "${requested.kind}".`);
+  }
+  const resolvedValues = layer.encoding.text.content === undefined ? undefined
+    : resolveMarkLabelValues(source, allItems, layer.encoding.text);
+  const values = resolvedValues === undefined ? undefined : new Map(
+    allItems.map((item, index) => [item.key, resolvedValues[index]])
+  );
+  return items.flatMap(item => {
+    let resolvedConfig = sourceTextConfig(config, source, item);
+    const text = formatTextValue(
+      values === undefined
+        ? contentValue(layer.encoding.text, item, source)
+        : values.get(item.key),
       layer.encoding.text.format
     );
-    return concrete === undefined ? [] : [{ graphic: concrete, anchor }];
+    if (text === undefined) return [];
+    const placement = program.markConfigs[layer.id]?.labelAuthoring?.placement;
+    if (placement === undefined) {
+      const anchor = sourceAnchor(program, source, item);
+      const concrete = concreteTextItem(resolvedConfig, anchor, text);
+      return concrete === undefined ? [] : [{ graphic: concrete, anchor }];
+    }
+    assertMarkLabelPlacementSupport(sourcePlacementContext(program, source), placement);
+    const resolved = resolveMarkLabelPlacement({
+      placement,
+      geometry: sourcePlacementGeometry(program, source, item),
+      text: {
+        text,
+        fontSize: resolvedConfig.fontSize,
+        fontFamily: resolvedConfig.fontFamily,
+        fontWeight: resolvedConfig.fontWeight,
+        textAlign: resolvedConfig.align,
+        textBaseline: resolvedConfig.baseline,
+        rotation: resolvedConfig.rotation,
+        dx: resolvedConfig.dx,
+        dy: resolvedConfig.dy
+      }
+    }, program.materializationConfigs.textMetrics);
+    if (!resolved.visible) return [];
+    if (
+      resolved.anchor.startsWith("outside") &&
+      config.fillExplicit !== true
+    ) {
+      resolvedConfig = config;
+    }
+    const anchor = { x: resolved.sourceX, y: resolved.sourceY };
+    return [{
+      graphic: concreteTextItem(
+        resolvedConfig,
+        { x: resolved.x, y: resolved.y },
+        text,
+        { offsets: false }
+      ),
+      anchor,
+      placement: resolved
+    }];
   });
 }
 

package/src/materialization/typography.js

@@ -0,0 +1,31 @@
+import { applyMaterializationPlan, buildMaterializationPlan } from "./planner.js";
+import { withGuideLayoutTransaction } from "./guides/layout.js";
+
+// Font tokens and measured-width profiles invalidate the same existing owners.
+// Incomplete text remains incomplete until its own prerequisites are authored.
+export function rematerializeTypography(program) {
+  if (program.compositionSpec !== undefined) {
+    return program.compositionSpec.type === "facet" ? program.materializeComposition() : program;
+  }
+  const exists = (id, op) => program.graphicSpec.objects[id] !== undefined && typeof program[op] === "function";
+  const marks = program.semanticSpec.layers
+    .filter(layer => layer.mark?.type === "text" && exists(layer.id, "rematerializeTextMark"))
+    .map(layer => ({ op: "rematerializeTextMark", args: { id: layer.id } }));
+  const guides = [];
+  for (const [id, op] of [
+    ["xAxisLabels", "editXAxisLabels"], ["yAxisLabels", "editYAxisLabels"],
+    ["xAxisTitle", "editXAxisTitle"], ["yAxisTitle", "editYAxisTitle"],
+    ["thetaAxisLabels", "editThetaAxisLabels"], ["radialAxisLabels", "editRadialAxisLabels"],
+    ["thetaAxisTitle", "editThetaAxisTitle"], ["radialAxisTitle", "editRadialAxisTitle"]
+  ]) if (exists(id, op)) guides.push({ op });
+  const parallel = program.guideConfigs.axis?.parallel?.axes;
+  if (parallel !== undefined && typeof program.rematerializeParallelAxes === "function") {
+    guides.push({ op: "rematerializeParallelAxes", args: { target: parallel.target } });
+  }
+  if (Object.keys(program.guideConfigs.legend ?? {}).length > 0 && typeof program.rematerializeLegend === "function") {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  const layout = exists("chartTitle", "rematerializeTitle") ? [{ op: "rematerializeTitle" }] : [];
+  return withGuideLayoutTransaction(program, next =>
+    applyMaterializationPlan(next, buildMaterializationPlan({ marks, guides, layout })));
+}

package/src/mcp/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 
-import { runGgactionMcpServer } from "./server.js";
-
 try {
+  const { runGgactionMcpServer } = await import("./server.js");
   await runGgactionMcpServer();
 } catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = error.code === "ERR_MODULE_NOT_FOUND" &&
+    error.message.includes("@modelcontextprotocol/sdk")
+    ? "MCP requires @modelcontextprotocol/sdk. Install it with: npm install ggaction @modelcontextprotocol/sdk"
+    : error instanceof Error ? error.message : String(error);
   process.stderr.write(`ggaction MCP failed: ${message}\n`);
   process.exitCode = 1;
 }

package/src/persistence/codec.js

@@ -0,0 +1,65 @@
+import { isPlainObject } from "../core/immutable.js";
+import { annotateError } from "../core/diagnostics.js";
+
+export function invalidSnapshot(message, optionPath) {
+  return annotateError(new TypeError(message), { code: "unsupported-format", optionPath });
+}
+
+export function encodeValue(value, path = "payload", ancestors = new WeakSet()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (value === undefined) return ["undefined"];
+  if (typeof value === "bigint") return ["bigint", value.toString()];
+  if (typeof value === "number") {
+    return Number.isFinite(value) && !Object.is(value, -0) ? value
+      : ["number", Object.is(value, -0) ? "-0" : String(value)];
+  }
+  if (typeof value !== "object") throw invalidSnapshot(`Cannot serialize ${typeof value} at ${path}.`, path);
+  if (ancestors.has(value)) throw invalidSnapshot(`Cannot serialize a cycle at ${path}.`, path);
+  if (!Array.isArray(value) && !isPlainObject(value)) throw invalidSnapshot(`Cannot serialize a class instance at ${path}.`, path);
+  if (Object.getOwnPropertySymbols(value).length) throw invalidSnapshot(`Cannot serialize symbol keys at ${path}.`, path);
+  const keys = Object.getOwnPropertyNames(value);
+  if (Array.isArray(value) ? keys.some(key => key !== "length" && !(/^(0|[1-9]\d*)$/.test(key) && Number(key) < value.length)) :
+      keys.some(key => !Object.getOwnPropertyDescriptor(value, key).enumerable)) {
+    throw invalidSnapshot(`Cannot serialize hidden or named array properties at ${path}.`, path);
+  }
+  ancestors.add(value);
+  const result = Array.isArray(value)
+    ? ["array", Array.from({ length: value.length }, (_, index) => Object.hasOwn(value, index)
+        ? encodeValue(value[index], `${path}[${index}]`, ancestors) : ["hole"])]
+    : ["object", Object.entries(value).map(([key, child]) => [key, encodeValue(child, `${path}.${key}`, ancestors)])];
+  ancestors.delete(value);
+  return result;
+}
+
+export function decodeValue(value, path = "payload") {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)) return value;
+  const invalid = () => { throw invalidSnapshot(`Invalid encoded value at ${path}.`, path); };
+  if (!Array.isArray(value)) return invalid();
+  const [tag, payload] = value;
+  if (tag === "undefined" && value.length === 1) return undefined;
+  if (value.length !== 2) return invalid();
+  if (tag === "bigint" && typeof payload === "string" && /^(?:0|-?[1-9]\d*)$/.test(payload)) return BigInt(payload);
+  if (tag === "number" && typeof payload === "string" && ["NaN", "Infinity", "-Infinity", "-0"].includes(payload)) {
+    return payload === "-0" ? -0 : Number(payload);
+  }
+  if (tag === "array" && Array.isArray(payload)) {
+    const result = new Array(payload.length);
+    payload.forEach((child, index) => {
+      if (Array.isArray(child) && child.length === 1 && child[0] === "hole") return;
+      result[index] = decodeValue(child, `${path}[${index}]`);
+    });
+    return result;
+  }
+  if (tag === "object" && Array.isArray(payload)) {
+    const result = {};
+    for (const entry of payload) {
+      if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || Object.hasOwn(result, entry[0])) return invalid();
+      Object.defineProperty(result, entry[0], {
+        value: decodeValue(entry[1], `${path}.${entry[0]}`), enumerable: true, writable: true, configurable: true
+      });
+    }
+    return result;
+  }
+  return invalid();
+}

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`);
+}