ggaction 0.0.15 → 0.0.16

package/src/actions/textMetrics/index.js

@@ -0,0 +1,56 @@
+import { action, closedAction } from "../../core/action.js";
+import { noOptions } from "../../core/validation.js";
+import { normalizeTextMetricProfile } from "../../core/textMetricProfile.js";
+import { rematerializeTypography } from "../../materialization/typography.js";
+
+function metricsProgram(parent, child) {
+  return typeof child.applyTextMetrics === "function" ? child : new parent.constructor({
+    ...child, actionSequence: child._actionSequence
+  });
+}
+
+export function inheritTextMetrics(parent, child) {
+  const profile = parent.materializationConfigs.textMetrics;
+  return profile === undefined ? child : metricsProgram(parent, child).applyTextMetrics({ profile });
+}
+
+function applyProfile(program, profile) {
+  let next = profile === undefined
+    ? program._withoutMaterializationConfig(["textMetrics"])
+    : program._withMaterializationConfig(["textMetrics"], profile);
+  if (next.compositionSpec !== undefined) {
+    const children = Object.fromEntries(next.compositionSpec.children.map(id => {
+      const child = next.children[id];
+      return [id, profile === undefined
+        ? child.materializationConfigs.textMetrics === undefined ? child : metricsProgram(next, child).removeTextMetrics()
+        : inheritTextMetrics(next, child)];
+    }));
+    next = next._withCompositionState({ children, compositionSpec: next.compositionSpec });
+    for (const id of next.compositionSpec.children) next = next.useProgram({ id });
+    return next.materializeComposition();
+  }
+  return rematerializeTypography(next);
+}
+
+export const applyTextMetrics = /* @__PURE__ */ closedAction(
+  { op: "applyTextMetrics", description: "Apply measured text widths to chart layout.", scope: "any" }, ["profile"],
+  function (args = {}) {
+    const profile = normalizeTextMetricProfile(args.profile);
+    applyProfile(this, profile);
+    return applyProfile(this, profile);
+  }
+);
+
+export const removeTextMetrics = /* @__PURE__ */ action(
+  { op: "removeTextMetrics", description: "Restore estimated text layout.", scope: "any" },
+  function (args = {}) {
+    noOptions(args, "removeTextMetrics");
+    if (this.materializationConfigs.textMetrics === undefined) throw new Error("removeTextMetrics requires an active profile.");
+    applyProfile(this, undefined);
+    return applyProfile(this, undefined);
+  }
+);
+
+export function registerTextMetricActions(ProgramClass) {
+  Object.assign(ProgramClass.prototype, { applyTextMetrics, removeTextMetrics });
+}

package/src/actions/theme/actions.js

@@ -28,7 +28,7 @@ function requireCompositionThemeHandlers() {
   return compositionThemeHandlers;
 }
 
-export const applyTheme = action(
+export const applyTheme = /* @__PURE__ */ action(
   {
     op: "applyTheme",
     description: "Apply persistent visual defaults to the chart program.",
@@ -70,7 +70,7 @@ export const applyTheme = action(
   }
 );
 
-export const removeTheme = action(
+export const removeTheme = /* @__PURE__ */ action(
   {
     op: "removeTheme",
     description: "Remove program theme defaults while preserving local styles.",

package/src/actions/theme/reconcile.js

@@ -1,3 +1,4 @@
+import { rematerializeTypography } from "../../materialization/typography.js";
 import { themeTokens } from "../../theme/defaults.js";
 import {
   normalizeThemeState,
@@ -46,10 +47,7 @@ function tokenFor(value, sourceTokens, targetTokens) {
   if (matches.length === 0) return undefined;
   const targets = new Set(matches.map(token => targetTokens[token]));
   if (targets.size !== 1) return undefined;
-  for (const token of matches) {
-    if (targetTokens[token] === targets.values().next().value) return token;
-  }
-  return undefined;
+  return matches[0];
 }
 
 function roleValues(role, sourceTokens, legacy = []) {
@@ -411,6 +409,11 @@ function recolorConfig(
   return { changed, value: changed ? next : value };
 }
 
+function addMarkPropertyOverrides(overrides, id, property) {
+  overrides.add(`c:marks.${id}.${property}`);
+  overrides.add(`g:${id}.${property}`);
+}
+
 function addMarkOverrides(overrides, program, op, args) {
   const match = /^(?:create|edit)(Point|Line|Area|Arc|Bar|Rect|Rule|Tick|Text)Mark$/u
     .exec(op);
@@ -425,42 +428,43 @@ function addMarkOverrides(overrides, program, op, args) {
   if (typeof id !== "string") return;
   for (const property of ["fill", "stroke", "fontFamily"]) {
     if (!Object.hasOwn(args, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
 function addFacadeMarkOverrides(overrides, op, args) {
   const facades = {
-    createScatterPlot: ["scatterPlot", "point", ["fill", "stroke"]],
-    createLinePlot: ["linePlot", "line", ["stroke"]],
-    createPolarScatterPlot: ["polarScatterPlot", "point", ["fill", "stroke"]],
-    createPolarLinePlot: ["polarLinePlot", "line", ["stroke"]],
-    createRadarPlot: ["radarPlot", "line", ["stroke"]],
-    createRugPlot: ["rugPlot", "tick", ["stroke"]],
-    createStripPlot: ["stripPlot", "point", ["fill", "stroke"]],
-    createBeeswarmPlot: ["beeswarmPlot", "point", ["fill", "stroke"]],
-    createBarPlot: ["barPlot", "bar", ["fill", "stroke"]],
-    createAreaPlot: ["areaPlot", "area", ["fill", "stroke"]],
-    createPiePlot: ["piePlot", "arc", ["fill", "stroke"]],
-    createRosePlot: ["rosePlot", "arc", ["fill", "stroke"]],
-    createRadialBarPlot: ["radialBarPlot", "arc", ["fill", "stroke"]],
-    createDensityPlot: ["densityPlot", "area", ["fill", "stroke"]],
-    createParallelCoordinates: ["parallelCoordinates", "line", ["stroke"]],
-    createHistogram: ["histogram", "bar", ["fill", "stroke"]],
-    createHeatmap: ["heatmap", "rect", ["stroke"]],
-    createHorizonPlot: ["horizonPlot", "area", ["stroke"]],
-    editHorizon: ["horizonPlot", "area", ["stroke"]],
-    createViolinPlot: ["violinPlot", "area", ["fill", "stroke"]]
+    createScatterPlot: ["point", true],
+    createLinePlot: ["line", false],
+    createPolarScatterPlot: ["point", true],
+    createPolarLinePlot: ["line", false],
+    createRadarPlot: ["line", false],
+    createRugPlot: ["tick", false],
+    createStripPlot: ["point", true],
+    createBeeswarmPlot: ["point", true],
+    createBarPlot: ["bar", true],
+    createAreaPlot: ["area", true],
+    createPiePlot: ["arc", true],
+    createRosePlot: ["arc", true],
+    createRadialBarPlot: ["arc", true],
+    createDensityPlot: ["area", true],
+    createParallelCoordinates: ["line", false],
+    createHistogram: ["bar", true],
+    createHeatmap: ["rect", false],
+    createHorizonPlot: ["area", false],
+    editHorizon: ["area", false],
+    createViolinPlot: ["area", true]
   };
   const facade = facades[op];
   if (facade === undefined) return;
-  const [defaultId, option, properties] = facade;
+  const [option, includesFill] = facade;
+  const subject = op === "editHorizon" ? "HorizonPlot" : op.slice(6);
+  const defaultId = subject[0].toLowerCase() + subject.slice(1);
+  const properties = includesFill ? ["fill", "stroke"] : ["stroke"];
   const id = args.id ?? defaultId;
   for (const property of properties) {
     if (!Object.hasOwn(args[option] ?? {}, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
@@ -492,8 +496,7 @@ function addTextFacadeOverrides(overrides, node) {
   if (typeof id !== "string") return;
   for (const property of ["fill", "fontFamily"]) {
     if (!Object.hasOwn(node.args, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
@@ -509,8 +512,7 @@ function addErrorBarOverrides(overrides, program, node) {
   if (id === undefined) return;
   const config = program.markConfigs[id].errorBar;
   for (const target of [id, config.lowerCapId, config.upperCapId]) {
-    overrides.add(`c:marks.${target}.stroke`);
-    overrides.add(`g:${target}.stroke`);
+    addMarkPropertyOverrides(overrides, target, "stroke");
   }
 }
 
@@ -536,8 +538,7 @@ function addErrorBandOverrides(overrides, program, node) {
   const targets = errorBandTargets(program, node);
   if (targets === undefined) return;
   if (Object.hasOwn(node.args, "fill") && node.args.fill !== false) {
-    overrides.add(`c:marks.${targets.id}.fill`);
-    overrides.add(`g:${targets.id}.fill`);
+    addMarkPropertyOverrides(overrides, targets.id, "fill");
   }
   const boundary = node.op === "editErrorBandBoundary"
     ? node.args
@@ -548,8 +549,7 @@ function addErrorBandOverrides(overrides, program, node) {
     ? [targets.lower, targets.upper]
     : [(node.args.boundary === "lower" ? targets.lower : targets.upper)];
   for (const id of ids) {
-    overrides.add(`c:marks.${id}.stroke`);
-    overrides.add(`g:${id}.stroke`);
+    addMarkPropertyOverrides(overrides, id, "stroke");
   }
 }
 
@@ -589,8 +589,7 @@ function addReferenceOverrides(overrides, op, args) {
   const id = args.id ?? defaultId;
   for (const property of properties) {
     if (!Object.hasOwn(args, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
@@ -611,12 +610,10 @@ function addRegressionOverrides(overrides, node) {
       : child?.args.id ?? child?.args.target;
   if (typeof id !== "string") return;
   if (Object.hasOwn(style ?? {}, "color")) {
-    overrides.add(`c:marks.${id}.fill`);
-    overrides.add(`g:${id}.fill`);
+    addMarkPropertyOverrides(overrides, id, "fill");
   }
   if (Object.hasOwn(style ?? {}, "stroke")) {
-    overrides.add(`c:marks.${id}.stroke`);
-    overrides.add(`g:${id}.stroke`);
+    addMarkPropertyOverrides(overrides, id, "stroke");
   }
 }
 
@@ -835,39 +832,18 @@ function addParallelOverrides(overrides, program, op, args) {
 }
 
 function addLegendOverrides(overrides, program, args) {
-  const legend = program.guideConfigs.legend ?? {};
-  const prefixes = {
-    series: "seriesLegend",
-    color: "colorLegend",
-    stroke: "strokeLegend",
-    interval: "colorLegend",
-    gradient: "colorGradient",
-    strokeInterval: "strokeInterval",
-    strokeGradient: "strokeGradient",
-    size: "sizeLegend",
-    strokeWidth: "strokeWidthLegend",
-    opacity: "opacityLegend"
-  };
-  for (const kind of Object.keys(legend)) {
-    if (Object.hasOwn(args.labels ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.labels.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Labels.fill`);
-    }
-    if (Object.hasOwn(args.labels ?? {}, "fontFamily")) {
-      overrides.add(`c:guides.legend.${kind}.labels.fontFamily`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Labels.fontFamily`);
-    }
-    if (Object.hasOwn(args.titleStyle ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.titleStyle.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Title.fill`);
-    }
-    if (Object.hasOwn(args.titleStyle ?? {}, "fontFamily")) {
-      overrides.add(`c:guides.legend.${kind}.titleStyle.fontFamily`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Title.fontFamily`);
-    }
-    if (Object.hasOwn(args.border ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.border.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Background.stroke`);
+  for (const kind of Object.keys(program.guideConfigs.legend ?? {})) {
+    const prefix = legendPrefix(kind);
+    for (const [option, suffix, property, graphicProperty] of [
+      ["labels", "Labels", "color", "fill"],
+      ["labels", "Labels", "fontFamily", "fontFamily"],
+      ["titleStyle", "Title", "color", "fill"],
+      ["titleStyle", "Title", "fontFamily", "fontFamily"],
+      ["border", "Background", "color", "stroke"]
+    ]) {
+      if (!Object.hasOwn(args[option] ?? {}, property)) continue;
+      overrides.add(`c:guides.legend.${kind}.${option}.${property}`);
+      if (prefix) overrides.add(`g:${prefix}${suffix}.${graphicProperty}`);
     }
   }
 }
@@ -1002,51 +978,18 @@ function collectOverrides(program) {
   return overrides;
 }
 
-function callExisting(program, graphicId, operation) {
-  return program.graphicSpec.objects[graphicId] !== undefined &&
-    typeof program[operation] === "function"
-    ? program[operation]()
-    : program;
-}
-
-function rematerializeThemeTypography(program) {
-  if (program.compositionSpec !== undefined) {
-    return program.compositionSpec.type === "facet"
-      ? program.materializeComposition()
-      : program;
-  }
-
-  let next = program;
-  for (const layer of next.semanticSpec.layers) {
-    if (layer.mark?.type === "text" &&
-        next.graphicSpec.objects[layer.id] !== undefined &&
-        typeof next.rematerializeTextMark === "function") {
-      next = next.rematerializeTextMark({ id: layer.id });
-    }
-  }
-  for (const [id, operation] of [
-    ["xAxisLabels", "editXAxisLabels"],
-    ["yAxisLabels", "editYAxisLabels"],
-    ["xAxisTitle", "editXAxisTitle"],
-    ["yAxisTitle", "editYAxisTitle"],
-    ["thetaAxisLabels", "editThetaAxisLabels"],
-    ["radialAxisLabels", "editRadialAxisLabels"],
-    ["thetaAxisTitle", "editThetaAxisTitle"],
-    ["radialAxisTitle", "editRadialAxisTitle"]
-  ]) {
-    next = callExisting(next, id, operation);
-  }
-  if (Object.keys(next.guideConfigs.legend ?? {}).length > 0 &&
-      typeof next.rematerializeLegend === "function") {
-    next = next.rematerializeLegend();
-  }
-  next = callExisting(next, "chartTitle", "rematerializeTitle");
-  return next;
-}
-
 export function reconcileProgramTheme(program, { source, metadata }) {
   const storedState = program.materializationConfigs.theme;
   if (storedState === undefined) return program;
+  // Data/context/trace-only transitions cannot change authored appearance.
+  // Preserve all visual identities instead of rescanning every existing mark.
+  if (program.graphicSpec === source.graphicSpec &&
+      program.materializationConfigs === source.materializationConfigs &&
+      program.children === source.children &&
+      program.compositionSpec === source.compositionSpec &&
+      ["layers", "scales", "coordinates", "guides", "title"].every(
+        key => program.semanticSpec[key] === source.semanticSpec[key]
+      )) return program;
   const composition = program.compositionSpec !== undefined;
   const state = normalizeThemeState(storedState, { composition });
   const sourceState = normalizeThemeState(
@@ -1088,15 +1031,16 @@ export function reconcileProgramTheme(program, { source, metadata }) {
 
   const facetsChanged = configs.value.facets !==
     themed.materializationConfigs.facets;
+  const typographyChanged = sourceTokens.fontFamily !== targetTokens.fontFamily;
   if (facetsChanged && next.compositionSpec?.type === "facet") {
     next = next.materializeComposition();
-  } else if (sourceTokens.fontFamily !== targetTokens.fontFamily) {
-    next = rematerializeThemeTypography(next);
+  } else if (typographyChanged) {
+    next = rematerializeTypography(next);
   }
 
   const parallelChanged = configs.value.guides.axis?.parallel !==
     themed.guideConfigs.axis?.parallel;
-  if (parallelChanged && typeof next.rematerializeParallelAxes === "function") {
+  if (parallelChanged && !typographyChanged && typeof next.rematerializeParallelAxes === "function") {
     next = next.rematerializeParallelAxes();
   }
 

package/src/actions/titles/actions.js

@@ -115,12 +115,12 @@ function titleTextAction(kind, create) {
   }));
 }
 
-export const editTitleText = titleTextAction("title", false);
-export const createTitleText = titleTextAction("title", true);
-export const editSubtitleText = titleTextAction("subtitle", false);
-export const createSubtitleText = titleTextAction("subtitle", true);
+export const editTitleText = /* @__PURE__ */ titleTextAction("title", false);
+export const createTitleText = /* @__PURE__ */ titleTextAction("title", true);
+export const editSubtitleText = /* @__PURE__ */ titleTextAction("subtitle", false);
+export const createSubtitleText = /* @__PURE__ */ titleTextAction("subtitle", true);
 
-export const rematerializeTitle = action(
+export const rematerializeTitle = /* @__PURE__ */ action(
   { op: "rematerializeTitle", description: "Rematerialize chart title graphics." },
   withGuideLayoutValidation(function (args = {}) {
     noOptions(args, "rematerializeTitle");
@@ -142,7 +142,7 @@ export const rematerializeTitle = action(
   })
 );
 
-export const createTitle = action(
+export const createTitle = /* @__PURE__ */ action(
   {
     op: "createTitle",
     description: "Create a chart title and optional subtitle.",
@@ -176,7 +176,7 @@ export const createTitle = action(
   })
 );
 
-export const editTitle = action(
+export const editTitle = /* @__PURE__ */ action(
   {
     op: "editTitle",
     description: "Edit one stable chart title resource.",
@@ -214,7 +214,7 @@ export const editTitle = action(
   })
 );
 
-export const removeTitle = action(
+export const removeTitle = /* @__PURE__ */ action(
   {
     op: "removeTitle",
     description: "Remove the complete chart title resource.",

package/src/actions/titles/resolve.js

@@ -212,7 +212,7 @@ export function resolveTitleLayout(program, config) {
           program.semanticSpec.title.subtitle,
           "Chart subtitle"
         )
-  }, config);
+  }, config, program.materializationConfigs.textMetrics);
   const horizontal = ["top", "bottom"].includes(config.position);
   let component;
   if (horizontal) {
@@ -249,10 +249,10 @@ export function resolveTitleLayout(program, config) {
     ? undefined
     : component(block.subtitleLines, block.subtitleCenters);
   const titleBounds = unionTitleBounds([
-    resolveTitleComponentBounds(title, config.titleStyle),
+    resolveTitleComponentBounds(title, config.titleStyle, program.materializationConfigs.textMetrics),
     ...(subtitle === undefined
       ? []
-      : [resolveTitleComponentBounds(subtitle, config.subtitleStyle)])
+      : [resolveTitleComponentBounds(subtitle, config.subtitleStyle, program.materializationConfigs.textMetrics)])
   ]);
   validateLayout(
     config.position,

package/src/actions/violinPlots/create.js

@@ -132,7 +132,7 @@ function guideOptions(guides, x, y, category, color) {
   };
 }
 
-export const createViolinPlot = action(
+export const createViolinPlot = /* @__PURE__ */ action(
   {
     op: "createViolinPlot",
     description: "Create a categorical kernel-density violin plot."

package/src/actions/violinPlots/edit.js

@@ -74,7 +74,7 @@ function assertSplitSelectionCompatibility(program, owner, changesSplit) {
   }
 }
 
-export const editViolinPlot = action(
+export const editViolinPlot = /* @__PURE__ */ action(
   {
     op: OPERATION,
     description: "Revise one violin plot's data and statistical roles."

package/src/core/action.js

@@ -1,4 +1,6 @@
-import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
+import { validateKeys } from "./validation.js";
+import { annotateError } from "./diagnostics.js";
+import { cloneAndFreeze, freezeOwned, isOwned, isPlainObject } from "./immutable.js";
 
 const metadataByWrappedAction = new WeakMap();
 const implementationByWrappedAction = new WeakMap();
@@ -35,6 +37,8 @@ function summarizeObject(value, ancestors = new WeakSet()) {
       summary[`${key}Count`] = item.length;
     } else if (isPlainObject(item)) {
       summary[key] = summarizeObject(item, ancestors);
+    } else if (typeof item === "function") {
+      summary[`${key}Type`] = "function";
     } else if (item !== null && typeof item === "object") {
       summary[`${key}Type`] = item.constructor?.name ?? "object";
     } else {
@@ -71,13 +75,59 @@ export function createActionNode({ id, op, description, args }) {
   });
 }
 
+// Persistent child tails make appending the active (last) branch independent
+// of sibling count. The public children property remains a stable frozen Array.
+const childLists = new WeakMap();
+
+function childList(node) {
+  let list = childLists.get(node);
+  if (list !== undefined) return list;
+  let tail;
+  for (const child of node.children) tail = { value: child, previous: tail };
+  list = { tail, length: node.children.length };
+  if (isOwned(node)) childLists.set(node, list);
+  return list;
+}
+
+function withChildList(node, list) {
+  let children;
+  const next = {};
+  for (const key of Object.keys(node)) {
+    if (key !== "children") Object.defineProperty(next, key, {
+      value: node[key], enumerable: true
+    });
+  }
+  Object.defineProperty(next, "children", {
+    enumerable: true,
+    get() {
+      if (children === undefined) {
+        const values = new Array(list.length);
+        let item = list.tail;
+        for (let index = list.length - 1; index >= 0; index -= 1) {
+          values[index] = item.value;
+          item = item.previous;
+        }
+        children = freezeOwned(values);
+      }
+      return children;
+    }
+  });
+  childLists.set(next, list);
+  return freezeOwned(next);
+}
+
+function childAt(node, index) {
+  const list = childList(node);
+  return index === list.length - 1 ? list.tail.value : node.children[index];
+}
+
 function nodeAtPath(root, path) {
   let node = root;
   for (const index of path) {
-    if (!Number.isInteger(index) || index < 0 || index >= node.children.length) {
+    if (!Number.isInteger(index) || index < 0 || index >= childList(node).length) {
       throw new Error(`Unknown parent action path "${path.join(".")}".`);
     }
-    node = node.children[index];
+    node = childAt(node, index);
   }
   return node;
 }
@@ -87,19 +137,28 @@ export function appendActionNodeAtPath(root, parentPath, actionNode) {
     throw new TypeError("Parent action path must be an array.");
   }
   const parent = nodeAtPath(root, parentPath);
-  const path = [...parentPath, parent.children.length];
+  const path = [...parentPath, childList(parent).length];
 
   function append(node, depth) {
+    const list = childList(node);
     if (depth === parentPath.length) {
-      return freezeOwned({
-        ...node,
-        children: freezeOwned([...node.children, actionNode])
+      return withChildList(node, {
+        tail: { value: actionNode, previous: list.tail }, length: list.length + 1
       });
     }
     const index = parentPath[depth];
-    const children = [...node.children];
-    children[index] = append(children[index], depth + 1);
-    return freezeOwned({ ...node, children: freezeOwned(children) });
+    const child = append(childAt(node, index), depth + 1);
+    if (index === list.length - 1) {
+      return withChildList(node, {
+        tail: { value: child, previous: list.tail.previous }, length: list.length
+      });
+    }
+    // Restored/extension traces may address an older sibling explicitly.
+    let tail;
+    for (let position = 0; position < list.length; position += 1) {
+      tail = { value: position === index ? child : node.children[position], previous: tail };
+    }
+    return withChildList(node, { tail, length: list.length });
   }
 
   return { root: append(root, 0), path };
@@ -137,39 +196,52 @@ export function action(metadata, implementation) {
   });
 
   const wrappedAction = function wrappedAction(args = {}) {
-    if (!isPlainObject(args)) {
-      throw new TypeError("Action arguments must be a plain object.");
-    }
-
-    if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
-    if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
-
-    const summarizedArgs = summarizeArgs(args);
-    const entered = this._enterAction({
-      ...ownedMetadata,
-      args: summarizedArgs
-    });
-    let result = implementation.call(entered, args);
-
-    if (!(result instanceof this.constructor)) {
-      throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);
-    }
-
-    if (this.actionStack.length === 0 && actionCompletionHook !== undefined) {
-      result = actionCompletionHook(result, {
-        source: this,
-        metadata: ownedMetadata,
+    try {
+      if (!isPlainObject(args)) {
+        throw new TypeError("Action arguments must be a plain object.");
+      }
+  
+      if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
+      if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
+  
+      const summarizedArgs = summarizeArgs(args);
+      const entered = this._enterAction({
+        ...ownedMetadata,
         args: summarizedArgs
       });
+      let result = implementation.call(entered, args);
+  
       if (!(result instanceof this.constructor)) {
-        throw new TypeError("Action completion hook must return a ChartProgram.");
+        throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);
+      }
+  
+      if (this.actionStack.length === 0 && actionCompletionHook !== undefined) {
+        result = actionCompletionHook(result, {
+          source: this,
+          metadata: ownedMetadata,
+          args: summarizedArgs
+        });
+        if (!(result instanceof this.constructor)) {
+          throw new TypeError("Action completion hook must return a ChartProgram.");
+        }
       }
+  
+      return result._exitAction();
+    } catch (error) {
+      throw annotateError(error, { code: "action-failed", operation: ownedMetadata.op });
     }
-
-    return result._exitAction();
   };
 
   metadataByWrappedAction.set(wrappedAction, ownedMetadata);
   implementationByWrappedAction.set(wrappedAction, implementation);
   return wrappedAction;
 }
+
+// Private built-in convenience: action() owns the object boundary and trace,
+// while each definition supplies its closed option vocabulary exactly once.
+export function closedAction(metadata, options, implementation) {
+  return action(metadata, function (args = {}) {
+    if (options !== undefined) validateKeys(args, options, metadata.op);
+    return implementation.call(this, args);
+  });
+}

package/src/core/diagnostics.js

@@ -0,0 +1,16 @@
+const detailsByError = new WeakMap();
+
+export function getErrorDetails(error) {
+  return error !== null && (typeof error === "object" || typeof error === "function")
+    ? detailsByError.get(error) : undefined;
+}
+
+// Attach metadata without modifying the thrown value or its existing class.
+export function annotateError(error, details) {
+  if (!(error instanceof Error)) return error;
+  const previous = getErrorDetails(error);
+  const merged = { ...details, ...previous };
+  if (merged.candidates !== undefined) merged.candidates = Object.freeze([...merged.candidates]);
+  detailsByError.set(error, Object.freeze(merged));
+  return error;
+}