ggaction 0.0.15 → 0.0.16

package/src/layout/text.js

@@ -5,12 +5,12 @@ export {
   resolveTextBounds
 } from "../core/textMetrics.js";
 
-function wrapCodePoints(text, maxWidth, style) {
+function wrapCodePoints(text, maxWidth, style, profile) {
   const lines = [];
   let line = "";
   for (const codePoint of [...text]) {
     const candidate = line + codePoint;
-    if (line !== "" && measureTextWidth(candidate, style) > maxWidth) {
+    if (line !== "" && measureTextWidth(candidate, style, profile) > maxWidth) {
       lines.push(line);
       line = codePoint;
     } else {
@@ -21,22 +21,22 @@ function wrapCodePoints(text, maxWidth, style) {
   return lines;
 }
 
-function wrapWords(text, maxWidth, style) {
+function wrapWords(text, maxWidth, style, profile) {
   const lines = [];
   let line = "";
   for (const word of text.trim().split(/\s+/u)) {
-    if (measureTextWidth(word, style) > maxWidth) {
+    if (measureTextWidth(word, style, profile) > maxWidth) {
       if (line !== "") {
         lines.push(line);
         line = "";
       }
-      const fragments = wrapCodePoints(word, maxWidth, style);
+      const fragments = wrapCodePoints(word, maxWidth, style, profile);
       lines.push(...fragments.slice(0, -1));
       line = fragments.at(-1);
       continue;
     }
     const candidate = line === "" ? word : `${line} ${word}`;
-    if (line !== "" && measureTextWidth(candidate, style) > maxWidth) {
+    if (line !== "" && measureTextWidth(candidate, style, profile) > maxWidth) {
       lines.push(line);
       line = word;
     } else {
@@ -50,7 +50,8 @@ function wrapWords(text, maxWidth, style) {
 export function wrapText(text, {
   maxWidth,
   mode = "word",
-  style
+  style,
+  profile
 } = {}) {
   if (maxWidth === undefined) return [text];
   if (!Number.isFinite(maxWidth) || maxWidth <= 0) {
@@ -60,6 +61,6 @@ export function wrapText(text, {
     throw new Error(`Unsupported text wrap mode "${mode}".`);
   }
   return mode === "word"
-    ? wrapWords(text, maxWidth, style)
-    : wrapCodePoints(text, maxWidth, style);
+    ? wrapWords(text, maxWidth, style, profile)
+    : wrapCodePoints(text, maxWidth, style, profile);
 }

package/src/layout/title.js

@@ -4,16 +4,16 @@ function lineCenters(lines, style, lineHeight, start) {
   return lines.map((_, index) => start + style.fontSize / 2 + index * lineHeight);
 }
 
-export function buildTitleReadingBlock({ text, subtitle }, config) {
+export function buildTitleReadingBlock({ text, subtitle }, config, profile) {
   const titleLines = wrapText(text, {
     maxWidth: config.maxWidth,
     mode: config.wrap,
-    style: config.titleStyle
+    style: config.titleStyle, profile
   });
   const subtitleLines = subtitle === undefined ? [] : wrapText(subtitle, {
     maxWidth: config.maxWidth,
     mode: config.wrap,
-    style: config.subtitleStyle
+    style: config.subtitleStyle, profile
   });
   const titleLineHeight = config.lineHeight ?? config.titleStyle.fontSize * 1.2;
   const subtitleLineHeight = config.lineHeight ??
@@ -36,8 +36,8 @@ export function buildTitleReadingBlock({ text, subtitle }, config) {
     ? titleBottom
     : subtitleCenters.at(-1) + config.subtitleStyle.fontSize / 2;
   const widths = [
-    ...titleLines.map(line => measureTextWidth(line, config.titleStyle)),
-    ...subtitleLines.map(line => measureTextWidth(line, config.subtitleStyle))
+    ...titleLines.map(line => measureTextWidth(line, config.titleStyle, profile)),
+    ...subtitleLines.map(line => measureTextWidth(line, config.subtitleStyle, profile))
   ];
   return {
     titleLines,
@@ -61,7 +61,7 @@ export function alignedTextAnchor(start, length, align) {
   return start + length;
 }
 
-function axisAlignedTextBounds({ x, y, text, style, align, rotation }) {
+function axisAlignedTextBounds({ x, y, text, style, align, rotation }, profile) {
   return resolveTextBounds({
     x,
     y,
@@ -70,7 +70,7 @@ function axisAlignedTextBounds({ x, y, text, style, align, rotation }) {
     textAlign: align,
     textBaseline: "middle",
     rotation
-  });
+  }, profile);
 }
 
 function unionBounds(bounds) {
@@ -82,7 +82,7 @@ function unionBounds(bounds) {
   }), { left: Infinity, right: -Infinity, top: Infinity, bottom: -Infinity });
 }
 
-export function resolveTitleComponentBounds(component, style) {
+export function resolveTitleComponentBounds(component, style, profile) {
   return unionBounds(component.lines.map((text, index) => axisAlignedTextBounds({
     x: Array.isArray(component.x) ? component.x[index] : component.x,
     y: Array.isArray(component.y) ? component.y[index] : component.y,
@@ -90,7 +90,7 @@ export function resolveTitleComponentBounds(component, style) {
     style,
     align: component.textAlign,
     rotation: component.rotation
-  })));
+  }, profile)));
 }
 
 export function unionTitleBounds(bounds) {

package/src/materialization/facetGuides/placement.js

@@ -92,7 +92,7 @@ function attachParentLegend(program, prepared, plot, layout) {
 }
 
 function assertSharedLegendFits(program, id, layout, plot) {
-  const bounds = resolveConcreteGraphicBounds(program.graphicSpec, id);
+  const bounds = resolveConcreteGraphicBounds(program.graphicSpec, id, program.materializationConfigs.textMetrics);
   if (bounds === undefined) {
     throw new Error("Facet shared legend requires measurable concrete bounds.");
   }

package/src/materialization/facetGuides/preparation.js

@@ -197,7 +197,7 @@ export function prepareSharedFacetLegend(program) {
   if (roots.length === 0) {
     throw new Error("Shared facet legend has no concrete guide graphics.");
   }
-  const bounds = unionConcreteGraphicBounds(source.graphicSpec, roots);
+  const bounds = unionConcreteGraphicBounds(source.graphicSpec, roots, source.materializationConfigs.textMetrics);
   if (bounds === undefined) {
     throw new Error("Shared facet legend has no measurable concrete bounds.");
   }

package/src/materialization/facetHeaders.js

@@ -139,13 +139,13 @@ function roleDescriptors(program, headers) {
   return [...columns, ...rows];
 }
 
-function laneThickness(descriptors, role) {
+function laneThickness(descriptors, role, profile) {
   const visible = descriptors.filter(item => item.role === role && item.text !== "");
   if (visible.length === 0) return 0;
   if (role === "column") {
     return Math.max(...visible.map(item => item.config.fontSize + item.config.offset));
   }
-  return Math.max(...visible.map(item => measureTextWidth(item.text, item.config) +
+  return Math.max(...visible.map(item => measureTextWidth(item.text, item.config, profile) +
     item.config.offset));
 }
 
@@ -163,7 +163,7 @@ export function prepareFacetHeaders(program, headersConfig) {
   };
   if (headers.mode === "roles") {
     const column = resolveFacetHeaderConfig(headers, "column");
-    const columnThickness = laneThickness(descriptors, "column");
+    const columnThickness = laneThickness(descriptors, "column", program.materializationConfigs.textMetrics);
     if (program.compositionSpec.facet.grid === undefined) {
       for (const descriptor of descriptors) {
         if (descriptor.text !== "") {
@@ -176,7 +176,7 @@ export function prepareFacetHeaders(program, headersConfig) {
     } else {
       headerLayout.outer[column.side] = columnThickness;
       const row = resolveFacetHeaderConfig(headers, "row");
-      headerLayout.outer[row.side] = laneThickness(descriptors, "row");
+      headerLayout.outer[row.side] = laneThickness(descriptors, "row", program.materializationConfigs.textMetrics);
     }
   }
   return { headers, descriptors, headerLayout };
@@ -287,10 +287,10 @@ function styledItem(item) {
   };
 }
 
-function assertRoleHeadersFit(records, items, layout) {
+function assertRoleHeadersFit(records, items, layout, profile) {
   const bounds = items.map((item, index) => records[index].descriptor.text === ""
     ? undefined
-    : resolveTextBounds(item.properties));
+    : resolveTextBounds(item.properties, profile));
   for (const [index, current] of bounds.entries()) {
     if (current === undefined) continue;
     if (current.left < -1e-9 || current.right > layout.width + 1e-9 ||
@@ -305,11 +305,11 @@ function assertRoleHeadersFit(records, items, layout) {
   }
 }
 
-function assertLegacyHeadersFit(items, layout, plotById) {
+function assertLegacyHeadersFit(items, layout, plotById, profile) {
   const previous = [];
   for (let index = 0; index < items.length; index += 1) {
     if (items[index].properties.text === "") continue;
-    const bounds = resolveTextBounds(items[index].properties);
+    const bounds = resolveTextBounds(items[index].properties, profile);
     const cell = layout.children[index];
     const plot = plotById.get(cell.id);
     if (bounds.left < 0 || bounds.right > layout.width ||
@@ -325,6 +325,7 @@ function assertLegacyHeadersFit(items, layout, plotById) {
 }
 
 export function materializeFacetHeaders(program, layout, plots, prepared) {
+  const profile = program.materializationConfigs.textMetrics;
   const cells = new Map(layout.children.map(cell => [cell.id, cell]));
   const plotById = new Map(plots.map(plot => [plot.id, plot]));
   const records = prepared.descriptors.map(descriptor => {
@@ -335,9 +336,9 @@ export function materializeFacetHeaders(program, layout, plots, prepared) {
   });
   const items = records.map(styledItem);
   if (prepared.headers.mode === "legacy") {
-    assertLegacyHeadersFit(items, layout, plotById);
+    assertLegacyHeadersFit(items, layout, plotById, profile);
   } else {
-    assertRoleHeadersFit(records, items, layout);
+    assertRoleHeadersFit(records, items, layout, profile);
   }
   const id = `${program.compositionSpec.id}-headers`;
   return program

package/src/materialization/guides/layout.js

@@ -4,12 +4,12 @@ import { axisGraphicIds, legendResourcePolicies } from "./resources.js";
 
 // Only domain-owned guides participate. Extension primitives may deliberately
 // overlap, and a combined categorical/size legend is one occupied group.
-export function resolveGuideCollisionBlocks(graphicSpec, guideConfigs, titleConfig) {
+export function resolveGuideCollisionBlocks(graphicSpec, guideConfigs, titleConfig, profile) {
   const blocks = [];
   const append = (id, kind, position, ids) => {
     if (position === undefined) return;
     const existing = ids.filter(id => graphicSpec.objects[id] !== undefined);
-    const bounds = unionConcreteGraphicBounds(graphicSpec, existing);
+    const bounds = unionConcreteGraphicBounds(graphicSpec, existing, profile);
     if (bounds !== undefined) blocks.push({ id, kind, position, bounds });
   };
   append("chart title", "title", titleConfig?.position, ["chartTitle", "chartSubtitle"]);
@@ -46,7 +46,7 @@ export function withGuideLayoutTransaction(program, apply) {
     context.deferGuideLayoutValidation = program.context.deferGuideLayoutValidation;
   }
   const next = result._clone({ context });
-  assertGuideCollisionBlocks(resolveGuideCollisionBlocks(next.graphicSpec, next.guideConfigs, next.titleConfig));
+  assertGuideCollisionBlocks(resolveGuideCollisionBlocks(next.graphicSpec, next.guideConfigs, next.titleConfig, next.materializationConfigs.textMetrics));
   return next;
 }
 

package/src/materialization/scaleGuideDependencies.js

@@ -18,6 +18,16 @@ const GRIDS = Object.freeze([
   Object.freeze({ role: "radial", op: "rematerializeRadialGrid" })
 ]);
 
+export function planAxisTickGridRematerialization(program, channel) {
+  const ticks = program.guideConfigs.axis?.[channel]?.ticks;
+  const role = channel === "x" ? "vertical" : "horizontal";
+  const config = program.guideConfigs.grid?.[role];
+  return buildMaterializationPlan({ guides:
+    config?.inferredValues === true && config.scale === ticks?.scale
+      ? GRIDS.filter(grid => grid.role === role).map(grid => ({ op: grid.op })) : []
+  });
+}
+
 function usesPositionalScale(program, id) {
   return program.semanticSpec.layers.some(layer =>
     !isSourceOwnedText(layer) && (

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

@@ -102,7 +102,7 @@ function collectionBounds(program, items) {
   const bounds = unionConcreteGraphicBounds(
     program.graphicSpec,
     items.map(item => item.id)
-  );
+  , program.materializationConfigs.textMetrics);
   if (bounds === undefined) return {};
   const { left, top, right, bottom } = bounds;
   return { x: left, y: top, width: right - left, height: bottom - top };

package/src/materialization/text.js

@@ -214,7 +214,7 @@ function pointPlacementGeometry(program, source, item) {
   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 },
@@ -391,7 +391,7 @@ function resolveSourceTextItems(program, layer, config) {
         dx: resolvedConfig.dx,
         dy: resolvedConfig.dy
       }
-    });
+    }, program.materializationConfigs.textMetrics);
     if (!resolved.visible) return [];
     if (
       resolved.anchor.startsWith("outside") &&

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