ggaction 0.0.10 → 0.0.12

package/src/materialization/selection/point.js

@@ -1,4 +1,5 @@
 import { createPointShapeGraphic } from "../../grammar/pointShapes.js";
+import { finiteMidpoint } from "../../grammar/numeric.js";
 
 function pointCenterAndArea(child) {
   const properties = child.properties;
@@ -19,17 +20,23 @@ function pointCenterAndArea(child) {
   const points = properties.commands.filter(command =>
     command.op === "M" || command.op === "L"
   );
-  const xs = points.map(point => point.x);
-  const ys = points.map(point => point.y);
+  let left = Infinity;
+  let right = -Infinity;
+  let top = Infinity;
+  let bottom = -Infinity;
   let twiceArea = 0;
   for (let index = 0; index < points.length; index += 1) {
     const current = points[index];
     const next = points[(index + 1) % points.length];
+    left = Math.min(left, current.x);
+    right = Math.max(right, current.x);
+    top = Math.min(top, current.y);
+    bottom = Math.max(bottom, current.y);
     twiceArea += current.x * next.y - next.x * current.y;
   }
   return {
-    x: (Math.min(...xs) + Math.max(...xs)) / 2,
-    y: (Math.min(...ys) + Math.max(...ys)) / 2,
+    x: finiteMidpoint(left, right),
+    y: finiteMidpoint(top, bottom),
     area: Math.abs(twiceArea) / 2
   };
 }

package/src/materialization/selection/styles.js

@@ -29,6 +29,22 @@ function normalizeOffset(offset) {
   return { x, y };
 }
 
+function normalizeOptionalStroke(args, mark) {
+  const stroke = args.stroke === undefined
+    ? undefined
+    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
+  const strokeWidth = args.strokeWidth === undefined
+    ? undefined
+    : validateNonNegativeFinite(
+        args.strokeWidth,
+        `${mark} highlight strokeWidth`
+      );
+  if (strokeWidth !== undefined && stroke === undefined) {
+    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
+  }
+  return { stroke, strokeWidth };
+}
+
 export function normalizeDimOthers(dimOthers) {
   if (dimOthers === undefined || dimOthers === false) return false;
   if (dimOthers === true) return { opacity: DEFAULT_DIM_OPACITY };
@@ -58,15 +74,7 @@ export function normalizePointHighlightStyle(args) {
   const opacity = args.opacity === undefined
     ? undefined
     : validateUnitInterval(args.opacity, "Point highlight opacity");
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, "Point highlight stroke");
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, "Point highlight strokeWidth");
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error("Point highlight strokeWidth requires stroke.");
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, "Point");
   return {
     fill,
     ...(opacity === undefined ? {} : { opacity }),
@@ -96,15 +104,7 @@ function normalizeRectangularHighlightStyle(args, mark, { offset = false } = {})
   const opacity = args.opacity === undefined
     ? undefined
     : validateUnitInterval(args.opacity, `${mark} highlight opacity`);
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, mark);
   const hasAppearanceOverride = opacity !== undefined || stroke !== undefined ||
     strokeWidth !== undefined || args.offset !== undefined;
   const fill = explicitFill === undefined && hasAppearanceOverride
@@ -178,15 +178,7 @@ export function normalizeAreaHighlightStyle(args, mark = "Area") {
   if (args.color !== undefined && args.fill !== undefined) {
     throw new Error(`${mark} highlight accepts color or fill, not both.`);
   }
-  const stroke = args.stroke === undefined
-    ? undefined
-    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
-  const strokeWidth = args.strokeWidth === undefined
-    ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
-  if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
-  }
+  const { stroke, strokeWidth } = normalizeOptionalStroke(args, mark);
   return {
     fill: validateNonEmptyString(
       args.fill ?? args.color ?? DEFAULT_COLORS.highlight,

package/src/materialization/text.js

@@ -104,7 +104,10 @@ function relativeLuminance(color) {
 }
 
 function sourceTextConfig(config, source, item) {
-  if (source.mark.type !== "rect" || config.fillExplicit === true) return config;
+  if (
+    !["arc", "rect"].includes(source.mark.type) ||
+    config.fillExplicit === true
+  ) return config;
   const luminance = relativeLuminance(item.properties.fill);
   if (luminance === undefined) return config;
   return {

package/src/mcp/adapter.js

@@ -28,7 +28,7 @@ export const OVERVIEW_URI = "ggaction://overview";
 export const SEARCH_TOOL = Object.freeze({
   name: SEARCH_TOOL_NAME,
   title: "Search ggaction authoring knowledge",
-  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, executable immutable steps, terminal unsupported constraints, and explicit unresolved decisions.",
+  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, syntax-valid immutable steps, applied options, explicit placeholders and unmatched requirements, terminal unsupported constraints, and unresolved decisions.",
   inputSchema: Object.freeze({
     type: "object",
     additionalProperties: false,
@@ -164,6 +164,7 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
   if (uri === OVERVIEW_URI) {
     return jsonResource(uri, {
       schemaVersion: resourcesArtifact.schemaVersion,
+      packageVersion: resourcesArtifact.packageVersion,
       title: resourcesArtifact.overview.title,
       text: resourcesArtifact.overview.text
     });
@@ -184,6 +185,7 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
     if (!recipe) throw new KnowledgeResourceError(`Unknown ggaction recipe: ${id}`);
     return jsonResource(uri, {
       schemaVersion: resourcesArtifact.schemaVersion,
+      packageVersion: resourcesArtifact.packageVersion,
       ...recipe,
       packet: searchGgaction(recipe.query)
     });
@@ -201,6 +203,9 @@ export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
   throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
 }
 
-if (cardsArtifact.schemaVersion !== 1 || resourcesArtifact.schemaVersion !== 2) {
-  throw new Error("MCP action cards must use schemaVersion 1 and resources schemaVersion 2.");
+if (cardsArtifact.schemaVersion !== 2 || resourcesArtifact.schemaVersion !== 2) {
+  throw new Error("MCP action cards and resources must use schemaVersion 2.");
+}
+if (resourcesArtifact.packageVersion !== cardsArtifact.packageVersion) {
+  throw new Error("MCP action cards and resources must use one packageVersion.");
 }

package/src/renderers/canvas/fill.js

@@ -1,8 +1,8 @@
 import {
   isLinearGradientPaint,
-  resolveLinearGradientCoordinates,
   validateFillPaint
 } from "../../grammar/paint.js";
+import { resolveCanvasGradientCoordinates } from "./native.js";
 
 export function applyCanvasFill(context, fill, bounds, graphicId) {
   validateFillPaint(fill, `${graphicId}.fill`);
@@ -15,7 +15,7 @@ export function applyCanvasFill(context, fill, bounds, graphicId) {
       `Graphic "${graphicId}" requires Canvas context createLinearGradient().`
     );
   }
-  const coordinates = resolveLinearGradientCoordinates(fill, bounds);
+  const coordinates = resolveCanvasGradientCoordinates(fill, bounds, graphicId);
   const gradient = context.createLinearGradient(
     coordinates.from.x,
     coordinates.from.y,

package/src/renderers/canvas/index.js

@@ -4,6 +4,10 @@ import { drawPathGraphic } from "./path.js";
 import { drawRectGraphic } from "./rect.js";
 import { drawTextGraphic } from "./text.js";
 import { requireFiniteProperty } from "./validation.js";
+import {
+  preflightCanvasGraphicSpec,
+  requireCanvasNativeValue
+} from "./native.js";
 import {
   requireSingleOrderedGraphicByType,
   walkGraphicTreeEvents
@@ -34,6 +38,8 @@ const DRAWING_CONTEXT_METHODS = Object.freeze([
   "rotate",
   "fillText"
 ]);
+const MAX_RASTER_DIMENSION = 32_767;
+const MAX_RASTER_PIXELS = 16_777_216;
 
 function requireDrawingContext(context) {
   if (context === null || typeof context !== "object") {
@@ -182,12 +188,39 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
   if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
     throw new RangeError("render pixelRatio must be a positive finite number.");
   }
+  requireCanvasNativeValue(pixelRatio, "render Canvas pixelRatio");
+  if (Math.fround(pixelRatio) === 0) {
+    throw new RangeError(
+      "render Canvas pixelRatio must remain positive at native precision."
+    );
+  }
 
   const target = resolveGraphicRenderTarget(graphicSpec);
   const { width, height } = target;
+  const physicalWidth = Math.max(1, Math.round(width * pixelRatio));
+  const physicalHeight = Math.max(1, Math.round(height * pixelRatio));
+  if (![physicalWidth, physicalHeight].every(Number.isSafeInteger)) {
+    throw new RangeError(
+      "render physical Canvas dimensions must be finite safe integers."
+    );
+  }
+  if (
+    physicalWidth > MAX_RASTER_DIMENSION ||
+    physicalHeight > MAX_RASTER_DIMENSION
+  ) {
+    throw new RangeError(
+      `render physical Canvas dimensions must not exceed ${MAX_RASTER_DIMENSION}.`
+    );
+  }
+  if (physicalWidth * physicalHeight > MAX_RASTER_PIXELS) {
+    throw new RangeError(
+      `render physical Canvas pixel count must not exceed ${MAX_RASTER_PIXELS}.`
+    );
+  }
+  preflightCanvasGraphicSpec(target, pixelRatio);
 
-  context.canvas.width = Math.round(width * pixelRatio);
-  context.canvas.height = Math.round(height * pixelRatio);
+  context.canvas.width = physicalWidth;
+  context.canvas.height = physicalHeight;
   if (
     context.canvas.style !== null &&
     typeof context.canvas.style === "object"

package/src/renderers/canvas/native.js

@@ -0,0 +1,160 @@
+import { resolveLinearGradientCoordinates } from "../../grammar/paint.js";
+import { resolvePathCommandBounds } from
+  "../../grammar/schemas/graphicBounds.js";
+import { walkGraphicTreeEvents } from
+  "../../grammar/schemas/graphicTree.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+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"],
+  text: ["x", "y", "fontSize"]
+};
+const COMMAND_PROPERTIES = ["x", "y", "x1", "y1", "x2", "y2"];
+
+export function requireCanvasNativeValue(value, label, scale = 1, offset = 0) {
+  const magnitude = Math.abs(value) + Math.abs(offset);
+  const scaled = magnitude * scale;
+  if (
+    !Number.isFinite(value) || magnitude > MAX_NATIVE_VALUE ||
+    !Number.isFinite(scaled) || scaled > MAX_NATIVE_VALUE
+  ) {
+    throw new RangeError(
+      `${label} must be finite with magnitude <= ${MAX_NATIVE_VALUE}.`
+    );
+  }
+}
+
+function requireValues(values, label, scale) {
+  for (const value of values) {
+    requireCanvasNativeValue(value, label, scale);
+  }
+}
+
+function requireProperties(properties, keys, label, scale, offset) {
+  for (const key of keys) {
+    const value = properties?.[key];
+    if (value !== undefined) {
+      requireCanvasNativeValue(
+        value,
+        label,
+        scale,
+        offset?.["xy".indexOf(key[0])]
+      );
+    }
+  }
+}
+
+export function resolveCanvasGradientCoordinates(fill, bounds, graphicId, scale = 1) {
+  const coordinates = resolveLinearGradientCoordinates(fill, bounds);
+  requireValues([
+    coordinates.from.x,
+    coordinates.from.y,
+    coordinates.to.x,
+    coordinates.to.y,
+    Math.hypot(
+      coordinates.to.x - coordinates.from.x,
+      coordinates.to.y - coordinates.from.y
+    )
+  ],
+    `Graphic "${graphicId}" Canvas linear gradient geometry`,
+    scale
+  );
+  return coordinates;
+}
+
+function preflightGraphic(id, graphic, scale, type, offset) {
+  const properties = graphic.properties ?? {};
+  const label = `Graphic "${id}" Canvas native geometry`;
+  requireProperties(
+    properties,
+    NATIVE_PROPERTIES[type] ?? [],
+    label,
+    scale,
+    offset
+  );
+  if (properties.rotation !== undefined) {
+    requireCanvasNativeValue(properties.rotation, label);
+  }
+  if (Array.isArray(properties.strokeDash)) {
+    requireValues(properties.strokeDash, label, scale);
+  }
+  const gradient = properties.fill?.type === "linear-gradient";
+
+  let bounds;
+  if (type === "canvas" || type === "rect" || type === "circle") {
+    const circle = type === "circle";
+    const width = circle ? properties.radius : properties.width;
+    const height = circle ? properties.radius : properties.height;
+    if ([properties.x, properties.y, width, height].every(Number.isFinite) &&
+      width >= 0 && height >= 0) {
+      bounds = {
+        left: properties.x - (circle ? width : 0),
+        right: properties.x + width,
+        top: properties.y - (circle ? height : 0),
+        bottom: properties.y + height
+      };
+      requireCanvasNativeValue(bounds.left, label, scale, offset?.[0]);
+      requireCanvasNativeValue(bounds.right, label, scale, offset?.[0]);
+      requireCanvasNativeValue(bounds.top, label, scale, offset?.[1]);
+      requireCanvasNativeValue(bounds.bottom, label, scale, offset?.[1]);
+    }
+  }
+  if (type === "path" && Array.isArray(properties.commands)) {
+    for (const command of properties.commands) {
+      requireProperties(command, COMMAND_PROPERTIES, label, scale, offset);
+    }
+    if (gradient) {
+      bounds = resolvePathCommandBounds(properties.commands);
+    }
+  }
+  if (gradient && bounds) {
+    resolveCanvasGradientCoordinates(properties.fill, bounds, id, scale);
+  }
+  if (NATIVE_PROPERTIES[type] !== undefined) {
+    validateConcreteGraphicProperties(type, properties);
+  }
+}
+
+export function preflightCanvasGraphicSpec(target, scale = 1) {
+  const offsets = [];
+  walkGraphicTreeEvents(target.graphicSpec, {
+    enter({ id, object }) {
+      let offset = offsets.at(-1);
+      if (object.type === "canvas") {
+        const parent = offset ?? [0, 0];
+        const properties = object.properties ?? {};
+        const x = id === target.canvasId ? 0 : properties.x;
+        const y = id === target.canvasId ? 0 : properties.y;
+        const effective = [parent[0] + x, parent[1] + y];
+        if (Number.isFinite(x) && Number.isFinite(y)) {
+          requireValues(
+            effective,
+            `Graphic "${id}" Canvas nested translation`,
+            scale
+          );
+        }
+        offsets.push(effective);
+        offset = id === target.canvasId ? undefined : parent;
+      }
+      preflightGraphic(id, object, scale, object.type, offset);
+    },
+    item({ id, object, owner }) {
+      preflightGraphic(
+        id,
+        object,
+        scale,
+        object.type ?? owner.type,
+        offsets.at(-1)
+      );
+    },
+    exit({ object }) {
+      if (object.type === "canvas") offsets.pop();
+    }
+  });
+}

package/src/renderers/pdf.js

@@ -8,6 +8,7 @@ import {
   requireProgramGraphicSpec,
   resolveGraphicRenderTarget
 } from "./canvas/index.js";
+import { preflightCanvasGraphicSpec } from "./canvas/native.js";
 
 const PDF_OPTIONS = new Set(["output", "metadata"]);
 const PDF_METADATA = new Set([
@@ -16,6 +17,7 @@ const PDF_METADATA = new Set([
   "subject",
   "keywords"
 ]);
+const MAX_PDF_DIMENSION = 16_777_216;
 
 function requirePlainObject(value, label) {
   if (
@@ -93,10 +95,22 @@ function renderPDFBuffer(target, metadata) {
   return document.close();
 }
 
+function requirePDFPageDimensions(target) {
+  if (![target.width, target.height].every(value =>
+    Number.isSafeInteger(value) && value > 0 && value <= MAX_PDF_DIMENSION
+  )) {
+    throw new RangeError(
+      `PDF page dimensions must be positive integers no larger than ${MAX_PDF_DIMENSION}.`
+    );
+  }
+}
+
 export async function renderToPDF(program, options = {}) {
   const { output, metadata } = requirePDFOptions(options);
   const graphicSpec = requireProgramGraphicSpec(program);
   const target = resolveGraphicRenderTarget(graphicSpec);
+  requirePDFPageDimensions(target);
+  preflightCanvasGraphicSpec(target);
   const buffer = renderPDFBuffer(target, metadata);
 
   await mkdir(dirname(output), { recursive: true });

package/src/renderers/svg.js

@@ -19,7 +19,8 @@ import {
 import { normalizeRendererFontWeight } from "./text.js";
 
 const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
-const SVG_OPTIONS = new Set(["title", "description"]);
+const SVG_OPTIONS = new Set(["title", "description", "resourceNamespace"]);
+const RESOURCE_NAMESPACE = /^[A-Za-z][A-Za-z0-9_-]*$/;
 const TEXT_ANCHORS = Object.freeze({
   left: "start",
   start: "start",
@@ -36,7 +37,28 @@ const DOMINANT_BASELINES = Object.freeze({
   bottom: "text-after-edge"
 });
 
+function resourceNamespace(graphicSpec) {
+  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);
+}
+
 function escapeText(value) {
+  for (const character of value) {
+    const point = character.codePointAt(0);
+    if (!(
+      point === 9 || point === 10 || point === 13 ||
+      (point >= 0x20 && point <= 0xd7ff) ||
+      (point >= 0xe000 && point <= 0xfffd) ||
+      (point >= 0x10000 && point <= 0x10ffff)
+    )) {
+      throw new TypeError("SVG output requires XML 1.0-compatible strings.");
+    }
+  }
   return value
     .replaceAll("&", "&amp;")
     .replaceAll("<", "&lt;")
@@ -122,7 +144,8 @@ function requireCanvasBackground(id, canvas) {
 
 function addLinearGradient(state, fill, bounds, graphicId) {
   const coordinates = resolveLinearGradientCoordinates(fill, bounds);
-  const id = `ggaction-gradient-${state.gradientCount}`;
+  const id =
+    `ggaction-gradient-${state.resourceNamespace}-${state.gradientCount}`;
   state.gradientCount += 1;
   const stops = fill.stops.map(stop => element("stop", [
     ["offset", formatNumber(stop.offset)],
@@ -410,7 +433,7 @@ function openNestedCanvas(state, id, canvas) {
     canvas,
     { nested: true }
   );
-  const clipId = `ggaction-clip-${state.clipCount}`;
+  const clipId = `ggaction-clip-${state.resourceNamespace}-${state.clipCount}`;
   state.clipCount += 1;
   state.definitions.push(element("clipPath", [["id", clipId]], element(
     "rect",
@@ -504,6 +527,14 @@ function requireSVGOptions(options) {
       throw new TypeError(`renderToSVG ${key} must be a non-empty string.`);
     }
   }
+  if (
+    options.resourceNamespace !== undefined &&
+    !RESOURCE_NAMESPACE.test(options.resourceNamespace)
+  ) {
+    throw new TypeError(
+      "renderToSVG resourceNamespace must start with a letter and contain only letters, numbers, _ or -."
+    );
+  }
   return options;
 }
 
@@ -529,7 +560,9 @@ export function renderToSVG(program, options = {}) {
   const state = {
     clipCount: 1,
     definitions: [],
-    gradientCount: 1
+    gradientCount: 1,
+    resourceNamespace:
+      resolvedOptions.resourceNamespace ?? resourceNamespace(graphicSpec)
   };
   const body = serializeBody(
     graphicSpec,

package/types/index.d.ts

@@ -157,6 +157,7 @@ export type {
   MarkGraphicProperty,
   Palette,
   PaletteName,
+  NonPointQuantitativePositionScaleOptions,
   PositionEncodingOptions,
   YPositionEncodingOptions,
   RulePositionEncodingOptions,
@@ -181,6 +182,8 @@ export type {
   ScaleRange,
   ScaleOptions,
   ScaleType,
+  ShapeScaleOptions,
+  SizeScaleOptions,
   StackMode,
   YStackMode,
   SemanticCoordinate,