@opendata-ai/openchart-engine 6.0.0 → 6.1.0

package/src/compiler/__tests__/validate.test.ts

@@ -12,7 +12,7 @@ const validLineData = [
 ];
 
 const validLineSpec = {
-  type: 'line',
+  mark: 'line',
   data: validLineData,
   encoding: {
     x: { field: 'date', type: 'temporal' },
@@ -23,7 +23,7 @@ const validLineSpec = {
 };
 
 const validBarSpec = {
-  type: 'bar',
+  mark: 'bar',
   data: [
     { category: 'A', count: 10 },
     { category: 'B', count: 20 },
@@ -34,8 +34,8 @@ const validBarSpec = {
   },
 };
 
-const validPieSpec = {
-  type: 'pie',
+const validArcSpec = {
+  mark: 'arc',
   data: [
     { label: 'Apples', amount: 30 },
     { label: 'Oranges', amount: 50 },
@@ -73,18 +73,17 @@ describe('validateSpec', () => {
       expect(result.errors[0].code).toBe('INVALID_TYPE');
     });
 
-    it('rejects objects without type with MISSING_FIELD code', () => {
+    it('rejects objects without mark or type with MISSING_FIELD code', () => {
       const result = validateSpec({ data: [] });
       expect(result.valid).toBe(false);
-      expect(result.errors[0].message).toContain('"type" field');
       expect(result.errors[0].code).toBe('MISSING_FIELD');
-      expect(result.errors[0].suggestion).toContain('line');
+      expect(result.errors[0].suggestion).toContain('bar');
     });
 
-    it('rejects invalid type values with INVALID_VALUE code', () => {
-      const result = validateSpec({ type: 'waterfall' });
+    it('rejects invalid mark values with INVALID_VALUE code', () => {
+      const result = validateSpec({ mark: 'waterfall' });
       expect(result.valid).toBe(false);
-      expect(result.errors[0].message).toContain('"waterfall" is not a valid type');
+      expect(result.errors[0].message).toContain('"waterfall" is not a valid mark type');
       expect(result.errors[0].code).toBe('INVALID_VALUE');
       expect(result.errors[0].suggestion).toContain('line');
     });
@@ -103,8 +102,8 @@ describe('validateSpec', () => {
       expect(result.valid).toBe(true);
     });
 
-    it('accepts a valid pie spec', () => {
-      const result = validateSpec(validPieSpec);
+    it('accepts a valid arc spec', () => {
+      const result = validateSpec(validArcSpec);
       expect(result.valid).toBe(true);
     });
 
@@ -125,7 +124,7 @@ describe('validateSpec', () => {
 
     it('rejects missing encoding with MISSING_FIELD code and channel suggestion', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: validLineData,
       });
       expect(result.valid).toBe(false);
@@ -137,7 +136,7 @@ describe('validateSpec', () => {
 
     it('rejects missing required channel with MISSING_FIELD code', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: validLineData,
         encoding: {
           x: { field: 'date', type: 'temporal' },
@@ -155,7 +154,7 @@ describe('validateSpec', () => {
 
     it('rejects field referencing non-existent column with DATA_FIELD_MISSING code', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: validLineData,
         encoding: {
           x: { field: 'nonexistent', type: 'temporal' },
@@ -175,7 +174,7 @@ describe('validateSpec', () => {
 
     it('rejects invalid field type with INVALID_VALUE code', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: validLineData,
         encoding: {
           x: { field: 'date', type: 'bogus' },
@@ -192,7 +191,7 @@ describe('validateSpec', () => {
 
     it('rejects disallowed type for channel with ENCODING_MISMATCH code', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: validLineData,
         encoding: {
           x: { field: 'date', type: 'quantitative' },
@@ -208,7 +207,7 @@ describe('validateSpec', () => {
 
     it('catches temporal field with non-date values with ENCODING_MISMATCH', () => {
       const result = validateSpec({
-        type: 'line',
+        mark: 'line',
         data: [
           { x: 'not-a-date', y: 10 },
           { x: 'also-not-a-date', y: 20 },
@@ -227,7 +226,7 @@ describe('validateSpec', () => {
 
     it('catches quantitative field with non-numeric values with ENCODING_MISMATCH', () => {
       const result = validateSpec({
-        type: 'scatter',
+        mark: 'point',
         data: [
           { x: 'hello', y: 10 },
           { x: 'world', y: 20 },
@@ -258,7 +257,7 @@ describe('validateSpec', () => {
 
     it('rejects missing encoding channel field with MISSING_FIELD code', () => {
       const result = validateSpec({
-        type: 'bar',
+        mark: 'bar',
         data: [{ a: 1, b: 2 }],
         encoding: {
           x: { type: 'quantitative' },
@@ -386,10 +385,10 @@ describe('validateSpec', () => {
       const results = [
         validateSpec(null),
         validateSpec({ data: [] }),
-        validateSpec({ type: 'waterfall' }),
-        validateSpec({ type: 'line', data: [] }),
+        validateSpec({ mark: 'waterfall' }),
+        validateSpec({ mark: 'line', data: [] }),
         validateSpec({
-          type: 'line',
+          mark: 'line',
           data: [{ x: 1 }],
           encoding: { x: { field: 'missing', type: 'quantitative' } },
         }),
@@ -407,8 +406,8 @@ describe('validateSpec', () => {
       const results = [
         validateSpec(null),
         validateSpec({ data: [] }),
-        validateSpec({ type: 'waterfall' }),
-        validateSpec({ type: 'line', data: [] }),
+        validateSpec({ mark: 'waterfall' }),
+        validateSpec({ mark: 'line', data: [] }),
       ];
 
       for (const result of results) {
@@ -422,7 +421,7 @@ describe('validateSpec', () => {
 
     it('DATA_FIELD_MISSING suggestion lists available fields', () => {
       const result = validateSpec({
-        type: 'bar',
+        mark: 'bar',
         data: [{ alpha: 1, beta: 2, gamma: 3 }],
         encoding: {
           x: { field: 'nonexistent', type: 'quantitative' },

package/src/compiler/index.ts

@@ -31,7 +31,7 @@ export function compile(spec: unknown): CompileResult {
   return { spec: normalized, warnings };
 }
 
-export { normalizeSpec } from './normalize';
+export { flattenLayers, normalizeSpec } from './normalize';
 export type {
   CompileResult,
   NormalizedChartSpec,

package/src/compiler/normalize.ts

@@ -17,10 +17,18 @@ import type {
   Encoding,
   FieldType,
   GraphSpec,
+  LayerSpec,
   TableSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';
-import { isChartSpec, isGraphSpec, isTableSpec } from '@opendata-ai/openchart-core';
+import {
+  isChartSpec,
+  isGraphSpec,
+  isLayerSpec,
+  isTableSpec,
+  resolveMarkDef,
+  resolveMarkType,
+} from '@opendata-ai/openchart-core';
 
 import type {
   NormalizedChartSpec,
@@ -116,9 +124,12 @@ function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: strin
     const spec = result[channel];
     if (!spec) continue;
 
+    // Skip conditional value definitions - they don't have field/type at the top level
+    if ('condition' in spec) continue;
+
     if (!spec.type) {
       const inferred = inferFieldType(data, spec.field);
-      result[channel] = { ...spec, type: inferred };
+      (result as Record<string, unknown>)[channel] = { ...spec, type: inferred };
       warnings.push(
         `Inferred encoding.${channel}.type as "${inferred}" from data values for field "${spec.field}"`,
       );
@@ -180,9 +191,12 @@ function normalizeAnnotations(annotations: Annotation[] | undefined): Annotation
 
 function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChartSpec {
   const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
+  const markType = resolveMarkType(spec.mark);
+  const markDef = resolveMarkDef(spec.mark);
 
   return {
-    type: spec.type,
+    markType,
+    markDef,
     data: spec.data,
     encoding,
     chrome: normalizeChrome(spec.chrome),
@@ -258,6 +272,16 @@ function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGra
  * @returns A NormalizedSpec with all optionals filled.
  */
 export function normalizeSpec(spec: VizSpec, warnings: string[] = []): NormalizedSpec {
+  if (isLayerSpec(spec)) {
+    // For LayerSpec, we flatten and normalize the first leaf to get a valid NormalizedChartSpec.
+    // The actual layer compilation happens in compileLayer, not here.
+    // This path exists so the generic compile() pipeline doesn't reject layer specs.
+    const leaves = flattenLayers(spec);
+    if (leaves.length === 0) {
+      throw new Error('LayerSpec has no leaf chart specs after flattening');
+    }
+    return normalizeChartSpec(leaves[0], warnings);
+  }
   if (isChartSpec(spec)) {
     return normalizeChartSpec(spec, warnings);
   }
@@ -268,5 +292,54 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
     return normalizeGraphSpec(spec, warnings);
   }
   // Should never happen after validation
-  throw new Error(`Unknown spec type: ${(spec as Record<string, unknown>).type}`);
+  throw new Error(
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', or type: 'graph'.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Layer flattening (used by compileLayer in compile.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively flatten a LayerSpec into leaf ChartSpecs.
+ * Merges parent data, encoding, and transforms down to children.
+ */
+export function flattenLayers(
+  spec: LayerSpec,
+  parentData?: DataRow[],
+  parentEncoding?: Encoding,
+  parentTransforms?: import('@opendata-ai/openchart-core').Transform[],
+): ChartSpec[] {
+  const resolvedData = spec.data ?? parentData;
+  const resolvedEncoding: Encoding | undefined =
+    parentEncoding && spec.encoding
+      ? { ...parentEncoding, ...spec.encoding }
+      : (spec.encoding ?? parentEncoding);
+  const resolvedTransforms = [...(parentTransforms ?? []), ...(spec.transform ?? [])];
+
+  const leaves: ChartSpec[] = [];
+
+  for (const child of spec.layer) {
+    if (isLayerSpec(child)) {
+      // Nested layer: recurse with merged context
+      leaves.push(...flattenLayers(child, resolvedData, resolvedEncoding, resolvedTransforms));
+    } else {
+      // Leaf ChartSpec: merge inherited properties
+      const mergedData = child.data ?? resolvedData ?? [];
+      const mergedEncoding = resolvedEncoding
+        ? { ...resolvedEncoding, ...child.encoding }
+        : child.encoding;
+      const mergedTransforms = [...resolvedTransforms, ...(child.transform ?? [])];
+
+      leaves.push({
+        ...child,
+        data: mergedData,
+        encoding: mergedEncoding,
+        transform: mergedTransforms.length > 0 ? mergedTransforms : undefined,
+      });
+    }
+  }
+
+  return leaves;
 }

package/src/compiler/types.ts

@@ -10,7 +10,6 @@ import type {
   AggregateOp,
   Annotation,
   AxisConfig,
-  ChartType,
   ChromeText,
   ColumnConfig,
   DarkMode,
@@ -22,6 +21,8 @@ import type {
   GraphSpec,
   LabelConfig,
   LegendConfig,
+  MarkDef,
+  MarkType,
   NodeOverride,
   ScaleConfig,
   ThemeConfig,
@@ -59,7 +60,10 @@ export interface NormalizedEncodingChannel {
 
 /** A ChartSpec with all optional fields filled with sensible defaults. */
 export interface NormalizedChartSpec {
-  type: ChartType;
+  /** Resolved mark type string (extracted from spec.mark). */
+  markType: MarkType;
+  /** Resolved mark definition with defaults filled in. */
+  markDef: MarkDef;
   data: DataRow[];
   encoding: Encoding;
   chrome: NormalizedChrome;

package/src/compiler/validate.ts

@@ -10,10 +10,10 @@
  */
 
 import {
-  CHART_ENCODING_RULES,
-  CHART_TYPES,
-  type ChartType,
   type FieldType,
+  MARK_ENCODING_RULES,
+  MARK_TYPES,
+  type MarkType,
   type VizSpec,
 } from '@opendata-ai/openchart-core';
 
@@ -53,7 +53,8 @@ function isNumeric(value: unknown): boolean {
 // ---------------------------------------------------------------------------
 
 function validateChartSpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
-  const chartType = spec.type as ChartType;
+  const markType =
+    typeof spec.mark === 'string' ? spec.mark : (spec.mark as Record<string, unknown>)?.type;
 
   // Check data
   if (!Array.isArray(spec.data)) {
@@ -91,12 +92,12 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
 
   // Check encoding exists
   if (!spec.encoding || typeof spec.encoding !== 'object') {
-    const rules = CHART_ENCODING_RULES[chartType];
+    const rules = MARK_ENCODING_RULES[markType as MarkType];
     const requiredChannels = Object.entries(rules)
       .filter(([, rule]) => rule.required)
       .map(([ch]) => ch);
     errors.push({
-      message: `Spec error: ${chartType} chart requires an "encoding" object`,
+      message: `Spec error: ${markType} chart requires an "encoding" object`,
       path: 'encoding',
       code: 'MISSING_FIELD',
       suggestion: `Add an encoding object with required channels: ${requiredChannels.join(', ')}. Example: encoding: { ${requiredChannels.map((ch) => `${ch}: { field: "...", type: "..." }`).join(', ')} }`,
@@ -104,7 +105,7 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     return;
   }
 
-  const rules = CHART_ENCODING_RULES[chartType];
+  const rules = MARK_ENCODING_RULES[markType as MarkType];
   const encoding = spec.encoding as Record<string, unknown>;
   const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
   const availableColumns = [...dataColumns].join(', ');
@@ -114,7 +115,7 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     if (rule.required && !encoding[channel]) {
       const allowedTypes = rule.allowedTypes.join(' or ');
       errors.push({
-        message: `Spec error: ${chartType} chart requires encoding.${channel} but none was provided`,
+        message: `Spec error: ${markType} chart requires encoding.${channel} but none was provided`,
         path: `encoding.${channel}`,
         code: 'MISSING_FIELD',
         suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}) and type (${allowedTypes}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${rule.allowedTypes[0]}" }`,
@@ -122,6 +123,19 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     }
   }
 
+  // Collect fields that transforms will create, so we don't reject them
+  const transformFields = new Set<string>();
+  if (Array.isArray(spec.transform)) {
+    for (const t of spec.transform as Record<string, unknown>[]) {
+      if (typeof t.as === 'string') transformFields.add(t.as);
+      if (Array.isArray(t.as)) {
+        for (const f of t.as) {
+          if (typeof f === 'string') transformFields.add(f);
+        }
+      }
+    }
+  }
+
   // Validate provided channels
   for (const [channel, channelSpec] of Object.entries(encoding)) {
     if (!channelSpec || typeof channelSpec !== 'object') continue;
@@ -129,6 +143,9 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     const channelObj = channelSpec as Record<string, unknown>;
     const channelRule = rules[channel as keyof typeof rules];
 
+    // Skip ConditionalValueDef channels (they have 'condition' instead of 'field')
+    if ('condition' in channelObj) continue;
+
     // Check field exists
     if (!channelObj.field || typeof channelObj.field !== 'string') {
       errors.push({
@@ -140,8 +157,8 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
       continue;
     }
 
-    // Check field references a column in data
-    if (!dataColumns.has(channelObj.field)) {
+    // Check field references a column in data (or will be created by a transform)
+    if (!dataColumns.has(channelObj.field) && !transformFields.has(channelObj.field)) {
       errors.push({
         message: `Spec error: encoding.${channel}.field "${channelObj.field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
@@ -164,7 +181,7 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     if (channelRule && channelObj.type && channelRule.allowedTypes.length > 0) {
       if (!channelRule.allowedTypes.includes(channelObj.type as FieldType)) {
         errors.push({
-          message: `Spec error: encoding.${channel} for ${chartType} chart does not accept type "${channelObj.type}". Allowed types: ${channelRule.allowedTypes.join(', ')}`,
+          message: `Spec error: encoding.${channel} for ${markType} chart does not accept type "${channelObj.type}". Allowed types: ${channelRule.allowedTypes.join(', ')}`,
           path: `encoding.${channel}.type`,
           code: 'ENCODING_MISMATCH',
           suggestion: `Change encoding.${channel}.type to one of: ${channelRule.allowedTypes.join(', ')}`,
@@ -493,6 +510,99 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
   }
 }
 
+// ---------------------------------------------------------------------------
+// Layer validation
+// ---------------------------------------------------------------------------
+
+function validateLayerSpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  const layer = spec.layer as unknown[];
+
+  if (layer.length === 0) {
+    errors.push({
+      message: 'Spec error: "layer" must be a non-empty array',
+      path: 'layer',
+      code: 'EMPTY_DATA',
+      suggestion: 'Add at least one layer with a mark and encoding',
+    });
+    return;
+  }
+
+  for (let i = 0; i < layer.length; i++) {
+    const child = layer[i];
+    if (!child || typeof child !== 'object' || Array.isArray(child)) {
+      errors.push({
+        message: `Spec error: layer[${i}] must be an object`,
+        path: `layer[${i}]`,
+        code: 'INVALID_TYPE',
+        suggestion:
+          'Each layer must be a chart spec (with mark) or a nested layer spec (with layer)',
+      });
+      continue;
+    }
+
+    const childObj = child as Record<string, unknown>;
+    const isNestedLayer = 'layer' in childObj && Array.isArray(childObj.layer);
+    const isChildChart = 'mark' in childObj;
+
+    if (!isNestedLayer && !isChildChart) {
+      errors.push({
+        message: `Spec error: layer[${i}] must have a "mark" field or a "layer" array`,
+        path: `layer[${i}]`,
+        code: 'MISSING_FIELD',
+        suggestion:
+          'Each layer must be a chart spec (with mark + encoding) or a nested layer spec (with layer array)',
+      });
+      continue;
+    }
+
+    if (isNestedLayer) {
+      validateLayerSpec(childObj, errors);
+    } else if (isChildChart) {
+      // Validate mark type
+      const mark = childObj.mark;
+      let markValue: string | undefined;
+      if (typeof mark === 'string') {
+        markValue = mark;
+      } else if (mark && typeof mark === 'object' && !Array.isArray(mark)) {
+        markValue = (mark as Record<string, unknown>).type as string | undefined;
+      }
+
+      if (!markValue || !MARK_TYPES.has(markValue)) {
+        errors.push({
+          message: `Spec error: layer[${i}].mark "${markValue ?? String(mark)}" is not a valid mark type`,
+          path: `layer[${i}].mark`,
+          code: 'INVALID_VALUE',
+          suggestion: `Change mark to one of: ${[...MARK_TYPES].join(', ')}`,
+        });
+        continue;
+      }
+
+      // Child layers can inherit data and encoding from parent, so only validate
+      // if the child has its own data (or the parent provides shared data).
+      const hasOwnData = Array.isArray(childObj.data) && (childObj.data as unknown[]).length > 0;
+      const parentHasData = Array.isArray(spec.data) && (spec.data as unknown[]).length > 0;
+
+      if (hasOwnData || parentHasData) {
+        // Build a merged spec for validation purposes
+        const mergedForValidation = { ...childObj };
+        if (!hasOwnData && parentHasData) {
+          mergedForValidation.data = spec.data;
+        }
+        // Merge encoding: parent fields are inherited unless child overrides
+        if (spec.encoding && typeof spec.encoding === 'object') {
+          mergedForValidation.encoding = {
+            ...(spec.encoding as Record<string, unknown>),
+            ...((childObj.encoding as Record<string, unknown>) ?? {}),
+          };
+        }
+        if (mergedForValidation.data && mergedForValidation.encoding) {
+          validateChartSpec(mergedForValidation, errors);
+        }
+      }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -516,7 +626,7 @@ export function validateSpec(spec: unknown): ValidationResult {
           message: 'Spec error: spec must be a non-null object',
           code: 'INVALID_TYPE',
           suggestion:
-            'Pass a spec object with at least a "type" field, e.g. { type: "line", data: [...], encoding: {...} }',
+            'Pass a spec object with at least a "mark" field for charts, e.g. { mark: "line", data: [...], encoding: {...} }',
         },
       ],
       normalized: null,
@@ -525,43 +635,65 @@ export function validateSpec(spec: unknown): ValidationResult {
 
   const obj = spec as Record<string, unknown>;
 
-  // Type check
-  if (!obj.type || typeof obj.type !== 'string') {
-    return {
-      valid: false,
-      errors: [
-        {
-          message: 'Spec error: spec must have a "type" field',
-          path: 'type',
-          code: 'MISSING_FIELD',
-          suggestion: `Add a type field. Valid types: ${[...CHART_TYPES].join(', ')}, table, graph`,
-        },
-      ],
-      normalized: null,
-    };
-  }
-
-  const isChart = CHART_TYPES.has(obj.type);
+  // Determine spec type via structural discrimination:
+  // - Layer specs have a 'layer' array
+  // - Chart specs have a 'mark' field (string or object with type property)
+  // - Table specs have type: 'table'
+  // - Graph specs have type: 'graph'
+  const hasLayer = 'layer' in obj && Array.isArray(obj.layer);
+  const hasMark = 'mark' in obj;
   const isTable = obj.type === 'table';
   const isGraph = obj.type === 'graph';
+  const isLayer = hasLayer && !isTable && !isGraph;
+  const isChart = hasMark && !hasLayer && !isTable && !isGraph;
 
-  if (!isChart && !isTable && !isGraph) {
+  if (!isChart && !isTable && !isGraph && !isLayer) {
     return {
       valid: false,
       errors: [
         {
-          message: `Spec error: "${obj.type}" is not a valid type. Valid types: ${[...CHART_TYPES].join(', ')}, table, graph`,
-          path: 'type',
-          code: 'INVALID_VALUE',
-          suggestion: `Change type to one of: ${[...CHART_TYPES].join(', ')}, table, graph`,
+          message:
+            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs',
+          path: 'mark',
+          code: 'MISSING_FIELD',
+          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs (type: "table" or type: "graph"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
         },
       ],
       normalized: null,
     };
   }
 
-  // Type-specific validation
+  // For layer specs, validate each child layer recursively
+  if (isLayer) {
+    validateLayerSpec(obj, errors);
+  }
+
+  // For chart specs, validate the mark field
   if (isChart) {
+    const mark = obj.mark;
+    let markValue: string | undefined;
+
+    if (typeof mark === 'string') {
+      markValue = mark;
+    } else if (mark && typeof mark === 'object' && !Array.isArray(mark)) {
+      markValue = (mark as Record<string, unknown>).type as string | undefined;
+    }
+
+    if (!markValue || !MARK_TYPES.has(markValue)) {
+      return {
+        valid: false,
+        errors: [
+          {
+            message: `Spec error: "${markValue ?? String(mark)}" is not a valid mark type. Valid mark types: ${[...MARK_TYPES].join(', ')}`,
+            path: 'mark',
+            code: 'INVALID_VALUE',
+            suggestion: `Change mark to one of: ${[...MARK_TYPES].join(', ')}`,
+          },
+        ],
+        normalized: null,
+      };
+    }
+
     validateChartSpec(obj, errors);
   } else if (isTable) {
     validateTableSpec(obj, errors);

package/src/graphs/__tests__/compile-graph.test.ts

@@ -295,7 +295,7 @@ describe('compileGraph', () => {
   describe('error handling', () => {
     it('throws for non-graph specs', () => {
       const chartSpec = {
-        type: 'scatter' as const,
+        mark: 'point' as const,
         data: [{ x: 1, y: 2 }],
         encoding: {
           x: { field: 'x', type: 'quantitative' as const },
@@ -304,7 +304,7 @@ describe('compileGraph', () => {
       };
 
       expect(() => compileGraph(chartSpec, compileOptions)).toThrow(
-        /compileGraph received a scatter spec/,
+        /compileGraph received a non-graph spec/,
       );
     });
 

package/src/graphs/compile-graph.ts

@@ -181,9 +181,9 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
   // 1. Validate + normalize
   const { spec: normalized } = compileSpec(spec);
 
-  if (normalized.type !== 'graph') {
+  if (!('type' in normalized) || normalized.type !== 'graph') {
     throw new Error(
-      `compileGraph received a ${normalized.type} spec. Use compileChart or compileTable instead.`,
+      'compileGraph received a non-graph spec. Use compileChart or compileTable instead.',
     );
   }