ggaction 0.0.13 → 0.0.16

package/src/persistence.js

@@ -0,0 +1,74 @@
+import { ChartProgram } from "./ChartProgram.js";
+import { BasicChartProgram } from "./BasicChartProgram.js";
+import { cloneAndFreeze } from "./core/immutable.js";
+import { hasRegisteredExtension, isBuiltinProgramClass } from "./core/extensionRegistry.js";
+import { packageVersion } from "./version.js";
+import { decodeValue, encodeValue, invalidSnapshot } from "./persistence/codec.js";
+import { exactKeys, requireObject, STATE_KEYS, validateGraphic, validateProgramState, validateTrace } from "./persistence/validation.js";
+
+function canonicalState(program, extensions, path = "payload") {
+  if (!(program instanceof ChartProgram || program instanceof BasicChartProgram) || !isBuiltinProgramClass(program.constructor)) {
+    throw invalidSnapshot(`Cannot persist an unregistered program class at ${path}.`, path);
+  }
+  if (program.actionStack.length !== 0) throw invalidSnapshot("Cannot persist an open actionStack.", `${path}.actionStack`);
+  const state = Object.fromEntries(STATE_KEYS.map(key => [key, program[key]]));
+  state.children = Object.fromEntries(Object.entries(program.children).map(([id, child]) => [id, canonicalState(child, extensions, `${path}.children.${id}`)]));
+  validateTrace(program.trace, program.constructor, extensions, `${path}.trace`);
+  validateProgramState(program, path);
+  return state;
+}
+
+function envelope(kind, payload, extensions = []) {
+  return JSON.stringify({ schemaVersion: 1, kind, packageVersion, extensions, payload: encodeValue(payload) });
+}
+
+function readEnvelope(text, kind) {
+  if (typeof text !== "string") throw invalidSnapshot("Snapshot must be a JSON string.", "snapshot");
+  let value;
+  try { value = JSON.parse(text); } catch { throw invalidSnapshot("Snapshot must be valid JSON.", "snapshot"); }
+  exactKeys(value, ["schemaVersion", "kind", "packageVersion", "extensions", "payload"], "snapshot");
+  if (value.schemaVersion !== 1 || value.kind !== kind) throw invalidSnapshot(`Unsupported snapshot schema or kind; expected schema 1 ${kind}.`, "snapshot");
+  if (typeof value.packageVersion !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value.packageVersion)) throw invalidSnapshot("Invalid snapshot packageVersion.", "snapshot.packageVersion");
+  if (!Array.isArray(value.extensions) || new Set(value.extensions).size !== value.extensions.length ||
+      value.extensions.some(name => typeof name !== "string" || !hasRegisteredExtension(name)) || (kind === "graphic" && value.extensions.length)) {
+    throw invalidSnapshot("Snapshot requires unknown, duplicate, or inapplicable extensions.", "snapshot.extensions");
+  }
+  return { ...value, payload: decodeValue(value.payload) };
+}
+
+function restoreState(state, extensions, path = "payload") {
+  exactKeys(state, STATE_KEYS, path);
+  if (!Array.isArray(state.actionStack) || state.actionStack.length) throw invalidSnapshot("Snapshot actionStack must be empty.", `${path}.actionStack`);
+  requireObject(state.children, `${path}.children`);
+  validateTrace(state.trace, ChartProgram, extensions, `${path}.trace`);
+  const children = Object.fromEntries(Object.entries(state.children).map(([id, child]) => [id, restoreState(child, extensions, `${path}.children.${id}`)]));
+  const program = new ChartProgram({ ...state, children });
+  validateProgramState(program, path);
+  return program;
+}
+
+export function serializeProgram(program) {
+  const extensions = new Set();
+  return envelope("editable", canonicalState(program, extensions), [...extensions].sort());
+}
+
+export function deserializeProgram(text) {
+  const stored = readEnvelope(text, "editable");
+  const extensions = new Set();
+  const program = restoreState(stored.payload, extensions);
+  if (extensions.size !== stored.extensions.length || stored.extensions.some(name => !extensions.has(name))) {
+    throw invalidSnapshot("Snapshot extensions must exactly match its action traces.", "snapshot.extensions");
+  }
+  return program;
+}
+
+export function serializeGraphic(program) {
+  validateGraphic(program?.graphicSpec);
+  return envelope("graphic", program.graphicSpec);
+}
+
+export function deserializeGraphic(text) {
+  const { payload } = readEnvelope(text, "graphic");
+  validateGraphic(payload);
+  return cloneAndFreeze({ graphicSpec: payload });
+}

package/src/renderers/canvas/circle.js

@@ -1,6 +1,7 @@
 import { requireFiniteProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
+import { applyCanvasStroke } from "./stroke.js";
 
 function drawCircle(context, child, collectionId) {
   const properties = child.properties ?? {};
@@ -43,9 +44,7 @@ function drawCircle(context, child, collectionId) {
         `Graphic "${graphicId}" requires a non-negative strokeWidth.`
       );
     }
-    context.strokeStyle = properties.stroke;
-    context.lineWidth = strokeWidth;
-    context.setLineDash([]);
+    applyCanvasStroke(context, properties);
     context.stroke();
   }
 }

package/src/renderers/canvas/index.js

@@ -1,3 +1,4 @@
+import { annotateError } from "../../core/diagnostics.js";
 import { drawCircleGraphic } from "./circle.js";
 import { drawLineGraphic } from "./line.js";
 import { drawPathGraphic } from "./path.js";
@@ -208,14 +209,14 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     physicalWidth > MAX_RASTER_DIMENSION ||
     physicalHeight > MAX_RASTER_DIMENSION
   ) {
-    throw new RangeError(
+    throw annotateError(new RangeError(
       `render physical Canvas dimensions must not exceed ${MAX_RASTER_DIMENSION}.`
-    );
+    ), { code: "resource-limit", operation: "render", optionPath: "physicalDimensions", limit: MAX_RASTER_DIMENSION, actual: Math.max(physicalWidth, physicalHeight) });
   }
   if (physicalWidth * physicalHeight > MAX_RASTER_PIXELS) {
-    throw new RangeError(
+    throw annotateError(new RangeError(
       `render physical Canvas pixel count must not exceed ${MAX_RASTER_PIXELS}.`
-    );
+    ), { code: "resource-limit", operation: "render", optionPath: "physicalPixels", limit: MAX_RASTER_PIXELS, actual: physicalWidth * physicalHeight });
   }
   preflightCanvasGraphicSpec(target, pixelRatio);
 

package/src/renderers/canvas/line.js

@@ -1,6 +1,7 @@
 import { requireFiniteProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
+import { applyCanvasStroke } from "./stroke.js";
 
 function drawLine(context, child, collectionId) {
   const properties = child.properties ?? {};
@@ -32,10 +33,8 @@ function drawLine(context, child, collectionId) {
     throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
   }
 
-  context.strokeStyle = properties.stroke;
-  context.lineWidth = strokeWidth;
   context.globalAlpha = opacity;
-  context.setLineDash(properties.strokeDash ?? []);
+  applyCanvasStroke(context, properties, properties.strokeDash ?? []);
   context.beginPath();
   context.moveTo(x1, y1);
   context.lineTo(x2, y2);

package/src/renderers/canvas/native.js

@@ -9,10 +9,10 @@ import { validateConcreteGraphicProperties } from
 const MAX_NATIVE_VALUE = 16_777_216;
 const NATIVE_PROPERTIES = {
   canvas: ["x", "y", "width", "height"],
-  circle: ["x", "y", "radius", "strokeWidth"],
-  rect: ["x", "y", "width", "height", "strokeWidth"],
-  line: ["x1", "y1", "x2", "y2", "strokeWidth"],
-  path: ["strokeWidth"],
+  circle: ["x", "y", "radius", "strokeWidth", "miterLimit"],
+  rect: ["x", "y", "width", "height", "strokeWidth", "miterLimit"],
+  line: ["x1", "y1", "x2", "y2", "strokeWidth", "miterLimit"],
+  path: ["strokeWidth", "miterLimit"],
   text: ["x", "y", "fontSize"]
 };
 const COMMAND_PROPERTIES = ["x", "y", "x1", "y1", "x2", "y2"];

package/src/renderers/canvas/path.js

@@ -3,6 +3,7 @@ import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
 import { resolvePathCommandBounds } from "../../grammar/schemas/graphicBounds.js";
 import { applyCanvasFill } from "./fill.js";
+import { applyCanvasStroke } from "./stroke.js";
 
 function drawPath(context, child, collectionId) {
   const properties = child.properties ?? {};
@@ -82,9 +83,7 @@ function drawPath(context, child, collectionId) {
     context.fill();
   }
   if (hasStroke) {
-    context.strokeStyle = properties.stroke;
-    context.lineWidth = strokeWidth;
-    context.setLineDash(strokeDash);
+    applyCanvasStroke(context, properties, strokeDash);
     context.stroke();
   }
 }

package/src/renderers/canvas/rect.js

@@ -2,6 +2,7 @@ import { requireFiniteProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
 import { applyCanvasFill } from "./fill.js";
+import { applyCanvasStroke } from "./stroke.js";
 
 function drawRect(context, child, collectionId) {
   const properties = child.properties ?? {};
@@ -42,9 +43,7 @@ function drawRect(context, child, collectionId) {
     bottom: y + height
   }, graphicId);
   context.fillRect(x, y, width, height);
-  context.strokeStyle = properties.stroke;
-  context.lineWidth = strokeWidth;
-  context.setLineDash([]);
+  applyCanvasStroke(context, properties);
   context.beginPath();
   context.moveTo(x, y);
   context.lineTo(x + width, y);

package/src/renderers/canvas/stroke.js

@@ -0,0 +1,11 @@
+import { resolveStrokeDetails } from "../../grammar/strokeStyle.js";
+
+export function applyCanvasStroke(context, properties, strokeDash = []) {
+  const details = resolveStrokeDetails(properties);
+  context.strokeStyle = properties.stroke;
+  context.lineWidth = properties.strokeWidth;
+  context.lineCap = details.lineCap;
+  context.lineJoin = details.lineJoin;
+  context.miterLimit = details.miterLimit;
+  context.setLineDash(strokeDash);
+}

package/src/renderers/nativeBackend.js

@@ -0,0 +1,10 @@
+export async function loadNativeBackend() {
+  try {
+    return await import("@napi-rs/canvas");
+  } catch (error) {
+    if (error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes("@napi-rs/canvas")) {
+      throw new Error("PNG/PDF output requires @napi-rs/canvas. Install it with: npm install ggaction @napi-rs/canvas", { cause: error });
+    }
+    throw error;
+  }
+}

package/src/renderers/options.js

@@ -0,0 +1,13 @@
+import { annotateError } from "../core/diagnostics.js";
+import { isPlainObject } from "../core/immutable.js";
+
+export function validateRendererOptions(options, allowed, label) {
+  if (!isPlainObject(options)) {
+    throw annotateError(new TypeError(`${label} must be a plain object.`), { code: "invalid-option" });
+  }
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) {
+      throw annotateError(new TypeError(`${label} does not support option "${key}".`), { code: "invalid-option", optionPath: key });
+    }
+  }
+}

package/src/renderers/pdf.js

@@ -1,7 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
-import { PDFDocument } from "@napi-rs/canvas";
+import { loadNativeBackend } from "./nativeBackend.js";
 
 import {
   drawResolvedGraphicSpec,
@@ -9,8 +9,10 @@ import {
   resolveGraphicRenderTarget
 } from "./canvas/index.js";
 import { preflightCanvasGraphicSpec } from "./canvas/native.js";
+import { validateRendererOptions } from "./options.js";
 
 const PDF_OPTIONS = new Set(["output", "metadata"]);
+const BUFFER_OPTIONS = new Set(["metadata"]);
 const PDF_METADATA = new Set([
   "title",
   "author",
@@ -19,30 +21,9 @@ const PDF_METADATA = new Set([
 ]);
 const MAX_PDF_DIMENSION = 16_777_216;
 
-function requirePlainObject(value, label) {
-  if (
-    value === null ||
-    typeof value !== "object" ||
-    Array.isArray(value) ||
-    Object.getPrototypeOf(value) !== Object.prototype
-  ) {
-    throw new TypeError(`${label} must be a plain object.`);
-  }
-  return value;
-}
-
-function requireClosedKeys(value, allowed, label) {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) {
-      throw new TypeError(`${label} does not support option "${key}".`);
-    }
-  }
-}
-
 function requireMetadata(metadata) {
   if (metadata === undefined) return undefined;
-  requirePlainObject(metadata, "renderToPDF metadata");
-  requireClosedKeys(metadata, PDF_METADATA, "renderToPDF metadata");
+  validateRendererOptions(metadata, PDF_METADATA, "renderToPDF metadata");
 
   const resolved = {};
   for (const key of ["title", "author", "subject"]) {
@@ -75,26 +56,6 @@ function requireMetadata(metadata) {
   return resolved;
 }
 
-function requirePDFOptions(options) {
-  requirePlainObject(options, "renderToPDF options");
-  requireClosedKeys(options, PDF_OPTIONS, "renderToPDF");
-  if (typeof options.output !== "string" || options.output.length === 0) {
-    throw new TypeError("renderToPDF requires a non-empty output path.");
-  }
-  return {
-    output: resolve(options.output),
-    metadata: requireMetadata(options.metadata)
-  };
-}
-
-function renderPDFBuffer(target, metadata) {
-  const document = new PDFDocument(metadata);
-  const context = document.beginPage(target.width, target.height);
-  drawResolvedGraphicSpec(target, context);
-  document.endPage();
-  return document.close();
-}
-
 function requirePDFPageDimensions(target) {
   if (![target.width, target.height].every(value =>
     Number.isSafeInteger(value) && value > 0 && value <= MAX_PDF_DIMENSION
@@ -105,22 +66,32 @@ function requirePDFPageDimensions(target) {
   }
 }
 
-export async function renderToPDF(program, options = {}) {
-  const { output, metadata } = requirePDFOptions(options);
+export async function renderToPDFBuffer(program, options = {}) {
+  validateRendererOptions(options, BUFFER_OPTIONS, "renderToPDFBuffer options");
+  const metadata = requireMetadata(options.metadata);
   const graphicSpec = requireProgramGraphicSpec(program);
   const target = resolveGraphicRenderTarget(graphicSpec);
   requirePDFPageDimensions(target);
   preflightCanvasGraphicSpec(target);
-  const buffer = renderPDFBuffer(target, metadata);
+  const { PDFDocument } = await loadNativeBackend();
+  const document = new PDFDocument(metadata);
+  const context = document.beginPage(target.width, target.height);
+  drawResolvedGraphicSpec(target, context);
+  document.endPage();
+  const buffer = document.close();
+  return Object.freeze({
+    buffer, width: target.width, height: target.height, pages: 1, bytes: buffer.length
+  });
+}
 
+export async function renderToPDF(program, options = {}) {
+  validateRendererOptions(options, PDF_OPTIONS, "renderToPDF options");
+  if (typeof options.output !== "string" || options.output.length === 0) {
+    throw new TypeError("renderToPDF requires a non-empty output path.");
+  }
+  const { buffer, ...result } = await renderToPDFBuffer(program, { metadata: options.metadata });
+  const output = resolve(options.output);
   await mkdir(dirname(output), { recursive: true });
   await writeFile(output, buffer);
-
-  return Object.freeze({
-    output,
-    width: target.width,
-    height: target.height,
-    pages: 1,
-    bytes: buffer.length
-  });
+  return Object.freeze({ output, ...result });
 }

package/src/renderers/png.js

@@ -1,29 +1,34 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { render } from "./canvas/index.js";
+import { validateRendererOptions } from "./options.js";
+import { loadNativeBackend } from "./nativeBackend.js";
 
-import { createCanvas } from "@napi-rs/canvas";
+const PNG_OPTIONS = new Set(["output", "pixelRatio"]);
+const BUFFER_OPTIONS = new Set(["pixelRatio"]);
 
-import { render } from "./canvas/index.js";
+export async function renderToPNGBuffer(program, options = {}) {
+  validateRendererOptions(options, BUFFER_OPTIONS, "renderToPNGBuffer options");
+  const { pixelRatio = 1 } = options;
+  const { createCanvas } = await loadNativeBackend();
+  const canvas = createCanvas(1, 1);
+  render(program, canvas.getContext("2d"), { pixelRatio });
+  // Canvas drawing is synchronous; encoding uses the native async worker.
+  const buffer = await canvas.encode("png");
+  return Object.freeze({
+    buffer, width: canvas.width, height: canvas.height, pixelRatio, bytes: buffer.length
+  });
+}
 
-export async function renderToPNG(program, { output, pixelRatio = 1 } = {}) {
+export async function renderToPNG(program, options = {}) {
+  validateRendererOptions(options, PNG_OPTIONS, "renderToPNG options");
+  const { output, pixelRatio } = options;
   if (typeof output !== "string" || output.length === 0) {
     throw new TypeError("renderToPNG requires a non-empty output path.");
   }
-
-  const canvas = createCanvas(1, 1);
-  const context = canvas.getContext("2d");
-  render(program, context, { pixelRatio });
-
+  const { buffer, ...result } = await renderToPNGBuffer(program, { pixelRatio });
   const path = resolve(output);
-  const buffer = canvas.toBuffer("image/png");
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, buffer);
-
-  return Object.freeze({
-    output: path,
-    width: canvas.width,
-    height: canvas.height,
-    pixelRatio,
-    bytes: buffer.length
-  });
+  return Object.freeze({ output: path, ...result });
 }

package/src/renderers/svg.js

@@ -1,3 +1,4 @@
+import { isOwned } from "../core/immutable.js";
 import {
   requireSingleOrderedGraphicByType,
   walkGraphicTreeEvents
@@ -17,6 +18,7 @@ import {
   requireStringProperty
 } from "./canvas/validation.js";
 import { normalizeRendererFontWeight } from "./text.js";
+import { validateRendererOptions } from "./options.js";
 
 const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 const SVG_OPTIONS = new Set(["title", "description", "resourceNamespace"]);
@@ -37,14 +39,20 @@ const DOMINANT_BASELINES = Object.freeze({
   bottom: "text-after-edge"
 });
 
+const namespaceByGraphic = new WeakMap();
+
 function resourceNamespace(graphicSpec) {
+  const cached = namespaceByGraphic.get(graphicSpec);
+  if (cached !== undefined) return cached;
   const serialized = JSON.stringify(graphicSpec);
   let hash = 0xcbf29ce484222325n;
   for (let index = 0; index < serialized.length; index += 1) {
     hash ^= BigInt(serialized.charCodeAt(index));
     hash = BigInt.asUintN(64, hash * 0x100000001b3n);
   }
-  return hash.toString(36);
+  const namespace = hash.toString(36);
+  if (isOwned(graphicSpec)) namespaceByGraphic.set(graphicSpec, namespace);
+  return namespace;
 }
 
 function escapeText(value) {
@@ -113,6 +121,21 @@ function requireStrokeDash(properties, graphicId) {
   return strokeDash;
 }
 
+function strokeDetailAttributes(properties, strokeWidth) {
+  if (typeof properties.stroke !== "string" || !(strokeWidth > 0)) return [];
+  return [
+    ["stroke-linecap", Object.hasOwn(properties, "lineCap")
+      ? properties.lineCap
+      : undefined],
+    ["stroke-linejoin", Object.hasOwn(properties, "lineJoin")
+      ? properties.lineJoin
+      : undefined],
+    ["stroke-miterlimit", Object.hasOwn(properties, "miterLimit")
+      ? formatNumber(properties.miterLimit)
+      : undefined]
+  ];
+}
+
 function requireCanvasGeometry(id, canvas, { nested }) {
   const properties = canvas.properties ?? {};
   const width = requireFiniteProperty(properties, "width", id);
@@ -200,6 +223,7 @@ function serializeCircle(state, graphicId, properties) {
     ["stroke-width", strokeWidth === undefined
       ? undefined
       : formatNumber(strokeWidth)],
+    ...strokeDetailAttributes(properties, strokeWidth),
     ["opacity", formatNumber(requireOpacity(properties, graphicId))]
   ]);
 }
@@ -240,6 +264,7 @@ function serializeRect(state, graphicId, properties) {
     ["fill", fill],
     ["stroke", properties.stroke],
     ["stroke-width", formatNumber(strokeWidth)],
+    ...strokeDetailAttributes(properties, strokeWidth),
     ["opacity", formatNumber(requireOpacity(properties, graphicId))]
   ]);
 }
@@ -268,6 +293,7 @@ function serializeLine(state, graphicId, properties) {
     ["fill", "none"],
     ["stroke", properties.stroke],
     ["stroke-width", formatNumber(strokeWidth)],
+    ...strokeDetailAttributes(properties, strokeWidth),
     ["stroke-dasharray", strokeDash.length === 0
       ? undefined
       : strokeDash.map(formatNumber).join(" ")],
@@ -332,6 +358,7 @@ function serializePath(state, graphicId, properties) {
     ["stroke-width", strokeWidth === undefined
       ? undefined
       : formatNumber(strokeWidth)],
+    ...strokeDetailAttributes(properties, strokeWidth),
     ["stroke-dasharray", strokeDash.length === 0
       ? undefined
       : strokeDash.map(formatNumber).join(" ")],
@@ -506,19 +533,7 @@ function serializeBody(graphicSpec, rootId, rootCanvas, width, height, state) {
 }
 
 function requireSVGOptions(options) {
-  if (
-    options === null ||
-    typeof options !== "object" ||
-    Array.isArray(options) ||
-    Object.getPrototypeOf(options) !== Object.prototype
-  ) {
-    throw new TypeError("renderToSVG options must be a plain object.");
-  }
-  for (const key of Object.keys(options)) {
-    if (!SVG_OPTIONS.has(key)) {
-      throw new TypeError(`renderToSVG does not support option "${key}".`);
-    }
-  }
+  validateRendererOptions(options, SVG_OPTIONS, "renderToSVG options");
   for (const key of SVG_OPTIONS) {
     if (
       options[key] !== undefined &&

package/src/renderers/text.js

@@ -1,11 +1 @@
-const MIN_RENDERER_NUMERIC_FONT_WEIGHT = 100;
-const MAX_RENDERER_NUMERIC_FONT_WEIGHT = 900;
-
-export function normalizeRendererFontWeight(fontWeight) {
-  if (typeof fontWeight !== "number") return fontWeight;
-  const rounded = Math.round(fontWeight / 100) * 100;
-  return Math.min(
-    MAX_RENDERER_NUMERIC_FONT_WEIGHT,
-    Math.max(MIN_RENDERER_NUMERIC_FONT_WEIGHT, rounded)
-  );
-}
+export { normalizeRendererFontWeight } from "../core/font.js";

package/src/selectors/coordinates.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findCoordinate(program, id) {
   return program.semanticSpec.coordinates.find(coordinate => coordinate.id === id);
 }
@@ -8,6 +10,6 @@ export function hasCoordinate(program, id) {
 
 export function requireCoordinate(program, id) {
   const coordinate = findCoordinate(program, id);
-  if (coordinate === undefined) throw new Error(`Unknown coordinate "${id}".`);
+  if (coordinate === undefined) throw annotateError(new Error(`Unknown coordinate "${id}".`), { code: "missing-resource", resourceId: id });
   return coordinate;
 }

package/src/selectors/datasets.js

@@ -1,7 +1,40 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findDataset(program, id) {
   return program.semanticSpec.datasets.find(dataset => dataset.id === id);
 }
 
+function currentOwnerMatches(program, id) {
+  const families = program.materializationConfigs.data ?? {};
+  return Object.entries(families).flatMap(([family, owners]) =>
+    Object.entries(owners ?? {}).flatMap(([owner, config]) =>
+      owner === id && typeof config?.current === "string"
+        ? [{ family, owner, current: config.current }]
+        : []
+    )
+  );
+}
+
+export function hasDatasetOwner(program, id) {
+  return currentOwnerMatches(program, id).length > 0;
+}
+
+export function resolveDatasetReference(program, id, label = "Dataset") {
+  const matches = currentOwnerMatches(program, id);
+  if (matches.length > 1) {
+    throw annotateError(new Error(`${label} logical owner "${id}" is ambiguous.`), { code: "ambiguous-resource", resourceId: id, candidates: matches.map(match => match.current) });
+  }
+  const resolved = matches.length === 1 ? matches[0].current : id;
+  const dataset = findDataset(program, resolved);
+  if (dataset === undefined) {
+    const kind = label.toLowerCase().includes("source")
+      ? "source dataset"
+      : "dataset";
+    throw annotateError(new Error(`Unknown ${kind} "${id}" does not exist.`), { code: "missing-resource", resourceId: id });
+  }
+  return dataset;
+}
+
 export function hasDataset(program, id) {
   return findDataset(program, id) !== undefined;
 }
@@ -12,19 +45,19 @@ export function findDatasetConsumer(program, source) {
 
 export function requireDataset(program, id, label = `Dataset "${id}"`) {
   const dataset = findDataset(program, id);
-  if (dataset === undefined) throw new Error(`${label} does not exist.`);
+  if (dataset === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return dataset;
 }
 
 export function requireMaterializedDataset(program, id) {
-  const dataset = findDataset(program, id);
-  if (dataset === undefined) throw new Error(`Unknown dataset "${id}".`);
+  const dataset = resolveDatasetReference(program, id, "Dataset");
+  if (dataset === undefined) throw annotateError(new Error(`Unknown dataset "${id}".`), { code: "missing-resource", resourceId: id });
   if (!Array.isArray(dataset.values)) {
-    throw new Error(
+    throw annotateError(new Error(
       `Dataset "${id}" requires materialized values. ` +
       "createDerivedData stores a definition only; use the corresponding " +
       "value-producing data action before creating a chart or mark."
-    );
+    ), { code: "incompatible-resource", resourceId: id });
   }
   return dataset;
 }

package/src/selectors/layers.js

@@ -1,14 +1,20 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findLayer(program, id) {
   return program.semanticSpec.layers.find(layer => layer.id === id);
 }
 
+export function findLayerMatching(program, predicate) {
+  return program.semanticSpec.layers.find(predicate);
+}
+
 export function hasLayer(program, id) {
   return findLayer(program, id) !== undefined;
 }
 
 export function requireLayer(program, id, label = `Layer "${id}"`) {
   const layer = findLayer(program, id);
-  if (layer === undefined) throw new Error(`${label} does not exist.`);
+  if (layer === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return layer;
 }
 
@@ -22,12 +28,12 @@ export function resolveEligibleLayer(program, {
   const candidates = program.semanticSpec.layers.filter(predicate);
   if (target !== undefined) {
     const selected = candidates.find(layer => layer.id === target);
-    if (selected === undefined) throw new Error(`Unknown ${label} ${targetOption} "${target}".`);
+    if (selected === undefined) throw annotateError(new Error(`Unknown ${label} ${targetOption} "${target}".`), { code: findLayer(program, target) ? "incompatible-resource" : "missing-resource", resourceId: target, optionPath: targetOption });
     return selected;
   }
   const selected = candidates.find(layer => layer.id === current);
   if (selected !== undefined) return selected;
   if (candidates.length === 1) return candidates[0];
-  if (candidates.length === 0) throw new Error(`${label} requires an eligible layer.`);
-  throw new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`);
+  if (candidates.length === 0) throw annotateError(new Error(`${label} requires an eligible layer.`), { code: "missing-resource", optionPath: targetOption });
+  throw annotateError(new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`), { code: "ambiguous-resource", optionPath: targetOption, candidates: candidates.map(layer => layer.id) });
 }