graphein 0.18.0 → 0.20.0

package/dist/spec/lint.js

@@ -0,0 +1,175 @@
+import { accessor, inferType, toNumber, uniqueValues } from "../util/data.js";
+import { applyTransforms } from "./transform/index.js";
+const MAX_PIE_SLICES = 7;
+const MAX_SERIES = 12;
+const MAX_DISCRETE_AXIS = 50;
+const POSITIONAL_AXES = ["x", "y"];
+const TYPE_CHANNELS = ["x", "y", "color", "series"];
+const SERIES_CHANNELS = ["series", "color"];
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function fieldDef(encoding, channel) {
+  const def = encoding?.[channel];
+  if (isObject(def) && typeof def.field === "string" && def.field !== "") return def;
+  return void 0;
+}
+function effectiveData(spec) {
+  const data = Array.isArray(spec.data) ? spec.data : [];
+  if (!("transform" in spec) || !Array.isArray(spec.transform) || spec.transform.length === 0) return data;
+  try {
+    return applyTransforms(spec.transform, data);
+  } catch {
+    return data;
+  }
+}
+function makeAdder(findings) {
+  return (rule, path, message, severity = "warning") => findings.push({ rule, path, message, severity });
+}
+function lintTemporalCategorical(findings, encoding, data) {
+  if (!encoding) return;
+  for (const channel of TYPE_CHANNELS) {
+    const def = fieldDef(encoding, channel);
+    if (!def) continue;
+    const declared = def.type;
+    if ((declared === "nominal" || declared === "ordinal") && inferType(data, def.field) === "temporal") {
+      findings.push({
+        rule: "temporal-typed-as-categorical",
+        path: `encoding.${channel}.type`,
+        message: `Field "${def.field}" looks temporal but is typed "${declared}". Set type:"temporal" so it scales as time.`,
+        severity: "warning",
+        fix: [{ op: "replace", path: `/encoding/${channel}/type`, value: "temporal" }]
+      });
+    }
+  }
+}
+function lintPieSlices(spec, encoding, data, add) {
+  if (spec.type !== "pie") return;
+  const def = fieldDef(encoding, "color") ?? fieldDef(encoding, "theta");
+  const slices = def ? uniqueValues(data, def.field).length : data.length;
+  if (slices > MAX_PIE_SLICES) {
+    add(
+      "pie-too-many-slices",
+      "encoding.color",
+      `Pie has ${slices} slices (> ${MAX_PIE_SLICES}); proportions get hard to compare. Use a bar chart, or group small slices into "Other".`
+    );
+  }
+}
+function lintSeriesCardinality(encoding, data, add) {
+  for (const channel of SERIES_CHANNELS) {
+    const def = fieldDef(encoding, channel);
+    if (!def) continue;
+    if (inferType(data, def.field) === "quantitative" && channel === "color") continue;
+    const count = uniqueValues(data, def.field).length;
+    if (count > MAX_SERIES) {
+      add(
+        "too-many-series",
+        `encoding.${channel}`,
+        `"${def.field}" has ${count} distinct values (> ${MAX_SERIES}); the legend/colors become hard to tell apart. Filter, group, or facet instead.`
+      );
+      break;
+    }
+  }
+}
+function lintBarBaseline(spec, encoding, add) {
+  if (spec.type !== "bar") return;
+  const y = fieldDef(encoding, "y");
+  const scale = y?.scale;
+  if (scale?.zero === false) {
+    add(
+      "bar-nonzero-baseline",
+      "encoding.y.scale.zero",
+      "Bar lengths encode magnitude, so a non-zero baseline exaggerates differences. Remove scale.zero:false (bars should start at 0)."
+    );
+  } else if (Array.isArray(scale?.domain) && typeof scale.domain[0] === "number" && scale.domain[0] > 0) {
+    add(
+      "bar-nonzero-baseline",
+      "encoding.y.scale.domain",
+      `Bar y-domain starts at ${scale.domain[0]} (> 0); a truncated baseline exaggerates differences. Start the domain at 0.`
+    );
+  }
+}
+function lintLogScales(encoding, data, add) {
+  if (!encoding) return;
+  for (const channel of POSITIONAL_AXES) {
+    const def = fieldDef(encoding, channel);
+    if (def?.scale?.type !== "log") continue;
+    const read = accessor(def.field);
+    const hasNonPositive = data.some((d) => {
+      const n = toNumber(read(d));
+      return Number.isFinite(n) && n <= 0;
+    });
+    if (hasNonPositive) {
+      add(
+        "log-nonpositive-data",
+        `encoding.${channel}.scale`,
+        `"${def.field}" has values \u2264 0, which a log scale cannot plot. Use a linear scale or filter non-positive values.`
+      );
+    }
+  }
+}
+function lintHighCardinalityAxis(spec, encoding, data, add) {
+  if (spec.type !== "bar" && spec.type !== "line" && spec.type !== "area") return;
+  for (const channel of POSITIONAL_AXES) {
+    const def = fieldDef(encoding, channel);
+    if (!def) continue;
+    const t = def.type ?? inferType(data, def.field);
+    const discrete = t === "nominal" || t === "ordinal" || def.scale?.type === "band" || def.scale?.type === "point";
+    if (!discrete) continue;
+    const count = uniqueValues(data, def.field).length;
+    if (count > MAX_DISCRETE_AXIS) {
+      add(
+        "high-cardinality-axis",
+        `encoding.${channel}`,
+        `"${def.field}" has ${count} categories on the ${channel}-axis (> ${MAX_DISCRETE_AXIS}); labels will be unreadable. Aggregate, filter to a top-N, or use a different chart.`
+      );
+    }
+  }
+}
+function lintHistogram(spec, encoding, data, add) {
+  if (spec.type !== "histogram") return;
+  const def = fieldDef(encoding, "x");
+  if (!def) return;
+  const t = def.type ?? inferType(data, def.field);
+  if (t !== "quantitative") {
+    add(
+      "histogram-nonnumeric-field",
+      "encoding.x",
+      `Histogram field "${def.field}" is ${t}, not quantitative \u2014 binning needs numbers. Use a numeric field, or a bar chart for categories.`
+    );
+  }
+}
+function lintComboAxis(spec, add) {
+  if (spec.type !== "combo" || !Array.isArray(spec.layers)) return;
+  const layers = spec.layers;
+  const hasRight = layers.some((l) => isObject(l) && l.axis === "right");
+  const hasLeft = layers.some((l) => isObject(l) && l.axis !== "right");
+  if (hasRight && hasLeft) {
+    add(
+      "combo-dual-axis",
+      "layers",
+      "Dual-axis combo: a secondary y-axis can suggest correlations that are not real. Use it only for genuinely different units/scales, and label both axes clearly.",
+      "info"
+    );
+  }
+}
+function lintSpec(spec) {
+  const findings = [];
+  const add = makeAdder(findings);
+  const encoding = isObject(spec) ? spec.encoding : void 0;
+  const data = effectiveData(spec);
+  if (data.length === 0) return findings;
+  lintTemporalCategorical(findings, encoding, data);
+  lintPieSlices(spec, encoding, data, add);
+  lintSeriesCardinality(encoding, data, add);
+  lintBarBaseline(spec, encoding, add);
+  lintLogScales(encoding, data, add);
+  lintHighCardinalityAxis(spec, encoding, data, add);
+  lintHistogram(spec, encoding, data, add);
+  lintComboAxis(spec, add);
+  return findings;
+}
+export {
+  lintSpec
+};
+//# sourceMappingURL=lint.js.map

package/dist/spec/lint.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/spec/lint.ts"],
+  "sourcesContent": ["/**\n * Dataviz linter \u2014 best-practice rules that encode the visualization expertise an\n * agent may lack. Each rule is pure and returns findings with a stable `rule` id\n * and a `severity` ('warning' | 'info'), so an agent can recognize, suppress, or\n * learn from a specific issue. Findings are surfaced through `validateSpec`'s\n * `warnings`, and directly via {@link lintSpec}.\n *\n * Rules lint the *effective* data (after `transform`), so cardinality reflects\n * what actually renders (e.g. pie slices after an `aggregate`). The linter never\n * throws and never blocks rendering \u2014 it is advisory only.\n */\n\nimport type { Datum, FieldType } from '../types';\nimport type { ChartSpec, ComboSpec, Encoding, FieldDef, ScaleType } from './types';\nimport { accessor, inferType, toNumber, uniqueValues } from '../util/data';\nimport { applyTransforms } from './transform';\nimport type { ValidationError } from './validate';\n\n/** A lint finding always carries a `rule` id and a non-error `severity`. */\nexport interface LintFinding extends ValidationError {\n  rule: string;\n  severity: 'warning' | 'info';\n}\n\n/** Thresholds, named so they are easy to tune and reference in messages. */\nconst MAX_PIE_SLICES = 7;\nconst MAX_SERIES = 12;\nconst MAX_DISCRETE_AXIS = 50;\n\n/** Channels that map to a positional/categorical axis on cartesian charts. */\nconst POSITIONAL_AXES: (keyof Encoding)[] = ['x', 'y'];\nconst TYPE_CHANNELS: (keyof Encoding)[] = ['x', 'y', 'color', 'series'];\nconst SERIES_CHANNELS: (keyof Encoding)[] = ['series', 'color'];\n\nfunction isObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\n/** Read a channel as a {@link FieldDef} when it has a string `field`. */\nfunction fieldDef(encoding: Encoding | undefined, channel: keyof Encoding): FieldDef | undefined {\n  const def = encoding?.[channel];\n  if (isObject(def) && typeof def.field === 'string' && def.field !== '') return def as FieldDef;\n  return undefined;\n}\n\n/** Apply transforms defensively so a malformed pipeline never breaks linting. */\nfunction effectiveData(spec: ChartSpec): Datum[] {\n  const data = Array.isArray(spec.data) ? (spec.data as Datum[]) : [];\n  if (!('transform' in spec) || !Array.isArray(spec.transform) || spec.transform.length === 0) return data;\n  try {\n    return applyTransforms(spec.transform, data);\n  } catch {\n    return data;\n  }\n}\n\nfunction makeAdder(findings: LintFinding[]) {\n  return (rule: string, path: string, message: string, severity: 'warning' | 'info' = 'warning') =>\n    findings.push({ rule, path, message, severity });\n}\n\nfunction lintTemporalCategorical(findings: LintFinding[], encoding: Encoding | undefined, data: Datum[]): void {\n    if (!encoding) return;\n    for (const channel of TYPE_CHANNELS) {\n      const def = fieldDef(encoding, channel);\n      if (!def) continue;\n      const declared = def.type as FieldType | undefined;\n      if ((declared === 'nominal' || declared === 'ordinal') && inferType(data, def.field) === 'temporal') {\n        findings.push({\n          rule: 'temporal-typed-as-categorical',\n          path: `encoding.${channel}.type`,\n          message: `Field \"${def.field}\" looks temporal but is typed \"${declared}\". Set type:\"temporal\" so it scales as time.`,\n          severity: 'warning',\n          fix: [{ op: 'replace', path: `/encoding/${channel}/type`, value: 'temporal' }],\n        });\n      }\n    }\n  }\n\n  function lintPieSlices(\n    spec: ChartSpec,\n    encoding: Encoding | undefined,\n    data: Datum[],\n    add: ReturnType<typeof makeAdder>,\n  ): void {\n    if (spec.type !== 'pie') return;\n    const def = fieldDef(encoding, 'color') ?? fieldDef(encoding, 'theta');\n    const slices = def ? uniqueValues(data, def.field).length : data.length;\n    if (slices > MAX_PIE_SLICES) {\n      add(\n        'pie-too-many-slices',\n        'encoding.color',\n        `Pie has ${slices} slices (> ${MAX_PIE_SLICES}); proportions get hard to compare. Use a bar chart, or group small slices into \"Other\".`,\n      );\n    }\n  }\n\n  function lintSeriesCardinality(encoding: Encoding | undefined, data: Datum[], add: ReturnType<typeof makeAdder>): void {\n    for (const channel of SERIES_CHANNELS) {\n      const def = fieldDef(encoding, channel);\n      if (!def) continue;\n      if (inferType(data, def.field) === 'quantitative' && channel === 'color') continue; // continuous color is fine\n      const count = uniqueValues(data, def.field).length;\n      if (count > MAX_SERIES) {\n        add(\n          'too-many-series',\n          `encoding.${channel}`,\n          `\"${def.field}\" has ${count} distinct values (> ${MAX_SERIES}); the legend/colors become hard to tell apart. Filter, group, or facet instead.`,\n        );\n        break; // one finding is enough\n      }\n    }\n  }\n\n  function lintBarBaseline(spec: ChartSpec, encoding: Encoding | undefined, add: ReturnType<typeof makeAdder>): void {\n    if (spec.type !== 'bar') return;\n    const y = fieldDef(encoding, 'y');\n    const scale = y?.scale;\n    if (scale?.zero === false) {\n      add(\n        'bar-nonzero-baseline',\n        'encoding.y.scale.zero',\n        'Bar lengths encode magnitude, so a non-zero baseline exaggerates differences. Remove scale.zero:false (bars should start at 0).',\n      );\n    } else if (Array.isArray(scale?.domain) && typeof scale.domain[0] === 'number' && scale.domain[0] > 0) {\n      add(\n        'bar-nonzero-baseline',\n        'encoding.y.scale.domain',\n        `Bar y-domain starts at ${scale.domain[0]} (> 0); a truncated baseline exaggerates differences. Start the domain at 0.`,\n      );\n    }\n  }\n\n  function lintLogScales(encoding: Encoding | undefined, data: Datum[], add: ReturnType<typeof makeAdder>): void {\n    if (!encoding) return;\n    for (const channel of POSITIONAL_AXES) {\n      const def = fieldDef(encoding, channel);\n      if ((def?.scale?.type as ScaleType | undefined) !== 'log') continue;\n      const read = accessor(def!.field);\n      const hasNonPositive = data.some((d) => {\n        const n = toNumber(read(d));\n        return Number.isFinite(n) && n <= 0;\n      });\n      if (hasNonPositive) {\n        add(\n          'log-nonpositive-data',\n          `encoding.${channel}.scale`,\n          `\"${def!.field}\" has values \u2264 0, which a log scale cannot plot. Use a linear scale or filter non-positive values.`,\n        );\n      }\n    }\n  }\n\n  function lintHighCardinalityAxis(\n    spec: ChartSpec,\n    encoding: Encoding | undefined,\n    data: Datum[],\n    add: ReturnType<typeof makeAdder>,\n  ): void {\n    if (spec.type !== 'bar' && spec.type !== 'line' && spec.type !== 'area') return;\n    for (const channel of POSITIONAL_AXES) {\n      const def = fieldDef(encoding, channel);\n      if (!def) continue;\n      const t = (def.type as FieldType | undefined) ?? inferType(data, def.field);\n      const discrete = t === 'nominal' || t === 'ordinal' || def.scale?.type === 'band' || def.scale?.type === 'point';\n      if (!discrete) continue;\n      const count = uniqueValues(data, def.field).length;\n      if (count > MAX_DISCRETE_AXIS) {\n        add(\n          'high-cardinality-axis',\n          `encoding.${channel}`,\n          `\"${def.field}\" has ${count} categories on the ${channel}-axis (> ${MAX_DISCRETE_AXIS}); labels will be unreadable. Aggregate, filter to a top-N, or use a different chart.`,\n        );\n      }\n    }\n  }\n\n  function lintHistogram(spec: ChartSpec, encoding: Encoding | undefined, data: Datum[], add: ReturnType<typeof makeAdder>): void {\n    if (spec.type !== 'histogram') return;\n    const def = fieldDef(encoding, 'x');\n    if (!def) return;\n    const t = (def.type as FieldType | undefined) ?? inferType(data, def.field);\n    if (t !== 'quantitative') {\n      add(\n        'histogram-nonnumeric-field',\n        'encoding.x',\n        `Histogram field \"${def.field}\" is ${t}, not quantitative \u2014 binning needs numbers. Use a numeric field, or a bar chart for categories.`,\n      );\n    }\n  }\n\nfunction lintComboAxis(spec: ChartSpec, add: ReturnType<typeof makeAdder>): void {\n    if (spec.type !== 'combo' || !Array.isArray((spec as ComboSpec).layers)) return;\n    const layers = (spec as ComboSpec).layers;\n    const hasRight = layers.some((l) => isObject(l) && l.axis === 'right');\n    const hasLeft = layers.some((l) => isObject(l) && l.axis !== 'right');\n    if (hasRight && hasLeft) {\n      add(\n        'combo-dual-axis',\n        'layers',\n        'Dual-axis combo: a secondary y-axis can suggest correlations that are not real. Use it only for genuinely different units/scales, and label both axes clearly.',\n        'info',\n      );\n  }\n}\n\n/**\n * Lint a (structurally valid) chart spec for best-practice issues. Returns an\n * empty array for slicers/dashboards or when no rule fires. Pure and total.\n */\nexport function lintSpec(spec: ChartSpec): LintFinding[] {\n  const findings: LintFinding[] = [];\n  const add = makeAdder(findings);\n\n  const encoding = (isObject(spec) ? (spec as { encoding?: unknown }).encoding : undefined) as\n    | Encoding\n    | undefined;\n  const data = effectiveData(spec);\n  if (data.length === 0) return findings; // nothing to measure against\n\n  // --- Rule: temporal field typed as a category ---------------------------\n  // A field that looks like dates but is declared nominal/ordinal will render on\n  // a categorical axis (no time spacing), a very common agent mistake.\n  lintTemporalCategorical(findings, encoding, data);\n\n  // --- Rule: pie / donut with too many slices -----------------------------\n  lintPieSlices(spec, encoding, data, add);\n\n  // --- Rule: too many series / legend colors ------------------------------\n  lintSeriesCardinality(encoding, data, add);\n\n  // --- Rule: bar baseline not at zero -------------------------------------\n  lintBarBaseline(spec, encoding, add);\n\n  // --- Rule: log scale with non-positive data -----------------------------\n  lintLogScales(encoding, data, add);\n\n  // --- Rule: high-cardinality categorical axis ----------------------------\n  lintHighCardinalityAxis(spec, encoding, data, add);\n\n  // --- Rule: histogram on a non-numeric field ----------------------------\n  // A histogram bins a quantitative measure; a nominal/temporal field can't be\n  // binned meaningfully. Warn so the agent picks a numeric field (or a bar chart).\n  lintHistogram(spec, encoding, data, add);\n\n  // --- Rule: dual-axis combo advisory -------------------------------------\n  // A secondary y-axis can imply a correlation that isn't there; only use it for\n  // genuinely different units. Advisory (info), fires only when both axes are used.\n  lintComboAxis(spec, add);\n\n  return findings;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/spec/repair.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Self-repairing validation. {@link repairSpec} applies the safe, unambiguous
+ * JSON Patch fixes that {@link validateSpec} attaches to its findings, then
+ * re-validates — turning common agent mistakes (a misspelled chart type or enum,
+ * a temporal field typed as a category) into a one-step correction instead of a
+ * full regenerate. Only fixes the validator deems unambiguous are applied; when
+ * the right correction is unclear, the error is left for the agent to resolve.
+ */
+import type { ValidationError } from './validate.js';
+import { type JsonPatchOp } from './jsonpatch.js';
+/** How aggressively {@link repairSpec} may infer missing or misspelled parts. */
+export interface RepairOptions {
+    /**
+     * Repair level. `'safe'` preserves the historical behavior and only applies
+     * validator-provided fixes; `'data'` may additionally infer unambiguous fixes
+     * from the spec's own data array.
+     */
+    level?: 'safe' | 'data';
+}
+/** A patch operation plus the human-readable reason it was considered safe. */
+export interface AppliedRepair {
+    /** The JSON Patch operation that was applied. */
+    op: JsonPatchOp;
+    /** Short explanation of why this repair was applied. */
+    rationale: string;
+}
+/** Result returned by {@link repairSpec}. */
+export interface RepairResult {
+    /** The (possibly) corrected spec — a new object; the input is never mutated. */
+    spec: unknown;
+    /** Patch operations that were applied, in order. Empty when nothing changed. */
+    applied: JsonPatchOp[];
+    /** Applied patch operations paired with their repair rationales. */
+    appliedDetails: AppliedRepair[];
+    /**
+     * Structural errors that remain after repair. `remaining.length === 0` means
+     * the repaired spec is valid. Advisory lint warnings are not counted here.
+     */
+    remaining: ValidationError[];
+}
+/**
+ * Apply every safe auto-fix `validateSpec` proposes, iterating until the spec is
+ * valid or no further progress can be made (a fix may unlock another — e.g.
+ * correcting the chart `type` changes which channels are required). Pure: the
+ * input spec is deep-cloned before any patch is applied.
+ */
+export declare function repairSpec(spec: unknown, options?: RepairOptions): RepairResult;
+//# sourceMappingURL=repair.d.ts.map

package/dist/spec/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/spec/repair.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtE,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,EAAE,EAAE,WAAW,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,IAAI,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC;;;OAGG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B;AA4GD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAgCnF"}

package/dist/spec/repair.js

@@ -0,0 +1,131 @@
+import { validateSpec } from "./validate.js";
+import { recommendChart } from "../analyze/recommend.js";
+import { applyPatch, toPointer } from "./jsonpatch.js";
+import { closest } from "./suggest.js";
+const MAX_PASSES = 8;
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function pathValue(doc, path) {
+  if (path === "") return doc;
+  let current = doc;
+  for (const part of path.replace(/\[(\d+)\]/g, ".$1").split(".")) {
+    if (part === "") continue;
+    if (Array.isArray(current)) {
+      current = current[Number(part)];
+    } else if (isObject(current)) {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function dataRows(spec) {
+  if (!isObject(spec) || !Array.isArray(spec.data) || spec.data.length === 0) return void 0;
+  if (spec.data.some((row) => !isObject(row) || row instanceof Date)) return void 0;
+  return spec.data;
+}
+function rationaleForValidationFix(op) {
+  return `validator-provided safe fix at "${op.path}"`;
+}
+function uniqueRecommendedSpec(spec) {
+  const rows = dataRows(spec);
+  if (!rows) return void 0;
+  const recommendations = recommendChart(rows, { maxResults: 20 });
+  if (recommendations.length === 0) return void 0;
+  const [top, runnerUp] = recommendations;
+  if (top.status === "needs-decision") return void 0;
+  if (runnerUp && top.score - runnerUp.score < 0.1) return void 0;
+  return top.spec;
+}
+function uniqueRecommendationForType(spec, type) {
+  const rows = dataRows(spec);
+  if (!rows) return void 0;
+  const matches = recommendChart(rows, { maxResults: 20 }).filter((rec) => {
+    return isObject(rec.spec) && rec.spec.type === type && rec.status !== "needs-decision";
+  });
+  return matches.length === 1 ? matches[0].spec : void 0;
+}
+function collectDataFixes(spec, findings) {
+  if (!isObject(spec)) return [];
+  const repairs = [];
+  for (const finding of findings) {
+    if (finding.suggestion?.kind !== "field") continue;
+    const value = pathValue(spec, finding.path);
+    if (typeof value !== "string") continue;
+    const best = closest(value, finding.suggestion.candidates);
+    if (!best || best === value) continue;
+    repairs.push({
+      op: { op: "replace", path: toPointer(finding.path), value: best },
+      rationale: `field "${value}" \u2192 "${best}" (nearest column)`
+    });
+  }
+  if (pathValue(spec, "type") === void 0) {
+    const recommended = uniqueRecommendedSpec(spec);
+    if (isObject(recommended) && typeof recommended.type === "string") {
+      repairs.push({
+        op: { op: "add", path: "/type", value: recommended.type },
+        rationale: `type "${recommended.type}" inferred from data shape`
+      });
+    }
+  }
+  const type = pathValue(spec, "type");
+  const encoding = pathValue(spec, "encoding");
+  if (typeof type === "string") {
+    const recommended = uniqueRecommendationForType(spec, type);
+    const recommendedEncoding = isObject(recommended) ? recommended.encoding : void 0;
+    if (isObject(recommendedEncoding)) {
+      if (!isObject(encoding) && findings.some((finding) => finding.path === "encoding")) {
+        repairs.push({
+          op: { op: "add", path: "/encoding", value: recommendedEncoding },
+          rationale: `encoding inferred from data shape for "${type}"`
+        });
+      } else if (isObject(encoding)) {
+        for (const finding of findings) {
+          const match = /^encoding\.([^.]+)$/.exec(finding.path);
+          if (!match) continue;
+          const channel = match[1];
+          if (encoding[channel] !== void 0 || recommendedEncoding[channel] === void 0) continue;
+          repairs.push({
+            op: { op: "add", path: toPointer(finding.path), value: recommendedEncoding[channel] },
+            rationale: `channel "${channel}" inferred from data shape for "${type}"`
+          });
+        }
+      }
+    }
+  }
+  return repairs;
+}
+function repairSpec(spec, options = {}) {
+  let current = spec;
+  const applied = [];
+  const appliedDetails = [];
+  let prevSignature = "";
+  const level = options.level ?? "safe";
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    const { errors, warnings } = validateSpec(current);
+    const fixes = [];
+    for (const finding of [...errors, ...warnings]) {
+      if (finding.fix && finding.fix.length > 0) {
+        fixes.push(...finding.fix.map((op) => ({ op, rationale: rationaleForValidationFix(op) })));
+      }
+    }
+    if (level === "data" && fixes.length === 0) {
+      fixes.push(...collectDataFixes(current, [...errors, ...warnings]));
+    }
+    if (fixes.length === 0) break;
+    const ops = fixes.map((fix) => fix.op);
+    const signature = JSON.stringify(ops);
+    if (signature === prevSignature) break;
+    prevSignature = signature;
+    current = applyPatch(current, ops);
+    applied.push(...ops);
+    appliedDetails.push(...fixes);
+  }
+  return { spec: current, applied, appliedDetails, remaining: validateSpec(current).errors };
+}
+export {
+  repairSpec
+};
+//# sourceMappingURL=repair.js.map

package/dist/spec/repair.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/spec/repair.ts"],
+  "sourcesContent": ["/**\n * Self-repairing validation. {@link repairSpec} applies the safe, unambiguous\n * JSON Patch fixes that {@link validateSpec} attaches to its findings, then\n * re-validates \u2014 turning common agent mistakes (a misspelled chart type or enum,\n * a temporal field typed as a category) into a one-step correction instead of a\n * full regenerate. Only fixes the validator deems unambiguous are applied; when\n * the right correction is unclear, the error is left for the agent to resolve.\n */\n\nimport type { ValidationError } from './validate';\nimport { validateSpec } from './validate';\nimport { recommendChart } from '../analyze/recommend';\nimport { applyPatch, toPointer, type JsonPatchOp } from './jsonpatch';\nimport { closest } from './suggest';\n\n/** How aggressively {@link repairSpec} may infer missing or misspelled parts. */\nexport interface RepairOptions {\n  /**\n   * Repair level. `'safe'` preserves the historical behavior and only applies\n   * validator-provided fixes; `'data'` may additionally infer unambiguous fixes\n   * from the spec's own data array.\n   */\n  level?: 'safe' | 'data';\n}\n\n/** A patch operation plus the human-readable reason it was considered safe. */\nexport interface AppliedRepair {\n  /** The JSON Patch operation that was applied. */\n  op: JsonPatchOp;\n  /** Short explanation of why this repair was applied. */\n  rationale: string;\n}\n\n/** Result returned by {@link repairSpec}. */\nexport interface RepairResult {\n  /** The (possibly) corrected spec \u2014 a new object; the input is never mutated. */\n  spec: unknown;\n  /** Patch operations that were applied, in order. Empty when nothing changed. */\n  applied: JsonPatchOp[];\n  /** Applied patch operations paired with their repair rationales. */\n  appliedDetails: AppliedRepair[];\n  /**\n   * Structural errors that remain after repair. `remaining.length === 0` means\n   * the repaired spec is valid. Advisory lint warnings are not counted here.\n   */\n  remaining: ValidationError[];\n}\n\nconst MAX_PASSES = 8;\n\nfunction isObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\nfunction pathValue(doc: unknown, path: string): unknown {\n  if (path === '') return doc;\n  let current = doc;\n  for (const part of path.replace(/\\[(\\d+)\\]/g, '.$1').split('.')) {\n    if (part === '') continue;\n    if (Array.isArray(current)) {\n      current = current[Number(part)];\n    } else if (isObject(current)) {\n      current = current[part];\n    } else {\n      return undefined;\n    }\n  }\n  return current;\n}\n\nfunction dataRows(spec: unknown): Record<string, unknown>[] | undefined {\n  if (!isObject(spec) || !Array.isArray(spec.data) || spec.data.length === 0) return undefined;\n  if (spec.data.some((row) => !isObject(row) || row instanceof Date)) return undefined;\n  return spec.data as Record<string, unknown>[];\n}\n\nfunction rationaleForValidationFix(op: JsonPatchOp): string {\n  return `validator-provided safe fix at \"${op.path}\"`;\n}\n\nfunction uniqueRecommendedSpec(spec: unknown): unknown | undefined {\n  const rows = dataRows(spec);\n  if (!rows) return undefined;\n  const recommendations = recommendChart(rows, { maxResults: 20 });\n  if (recommendations.length === 0) return undefined;\n  const [top, runnerUp] = recommendations;\n  if (top.status === 'needs-decision') return undefined;\n  if (runnerUp && top.score - runnerUp.score < 0.1) return undefined;\n  return top.spec;\n}\n\nfunction uniqueRecommendationForType(spec: unknown, type: string): unknown | undefined {\n  const rows = dataRows(spec);\n  if (!rows) return undefined;\n  const matches = recommendChart(rows, { maxResults: 20 }).filter((rec) => {\n    return isObject(rec.spec) && rec.spec.type === type && rec.status !== 'needs-decision';\n  });\n  return matches.length === 1 ? matches[0].spec : undefined;\n}\n\nfunction collectDataFixes(spec: unknown, findings: ValidationError[]): AppliedRepair[] {\n  if (!isObject(spec)) return [];\n  const repairs: AppliedRepair[] = [];\n  for (const finding of findings) {\n    if (finding.suggestion?.kind !== 'field') continue;\n    const value = pathValue(spec, finding.path);\n    if (typeof value !== 'string') continue;\n    const best = closest(value, finding.suggestion.candidates);\n    if (!best || best === value) continue;\n    repairs.push({\n      op: { op: 'replace', path: toPointer(finding.path), value: best },\n      rationale: `field \"${value}\" \u2192 \"${best}\" (nearest column)`,\n    });\n  }\n\n  if (pathValue(spec, 'type') === undefined) {\n    const recommended = uniqueRecommendedSpec(spec);\n    if (isObject(recommended) && typeof recommended.type === 'string') {\n      repairs.push({\n        op: { op: 'add', path: '/type', value: recommended.type },\n        rationale: `type \"${recommended.type}\" inferred from data shape`,\n      });\n    }\n  }\n\n  const type = pathValue(spec, 'type');\n  const encoding = pathValue(spec, 'encoding');\n  if (typeof type === 'string') {\n    const recommended = uniqueRecommendationForType(spec, type);\n    const recommendedEncoding = isObject(recommended) ? recommended.encoding : undefined;\n    if (isObject(recommendedEncoding)) {\n      if (!isObject(encoding) && findings.some((finding) => finding.path === 'encoding')) {\n        repairs.push({\n          op: { op: 'add', path: '/encoding', value: recommendedEncoding },\n          rationale: `encoding inferred from data shape for \"${type}\"`,\n        });\n      } else if (isObject(encoding)) {\n        for (const finding of findings) {\n          const match = /^encoding\\.([^.]+)$/.exec(finding.path);\n          if (!match) continue;\n          const channel = match[1];\n          if (encoding[channel] !== undefined || recommendedEncoding[channel] === undefined) continue;\n          repairs.push({\n            op: { op: 'add', path: toPointer(finding.path), value: recommendedEncoding[channel] },\n            rationale: `channel \"${channel}\" inferred from data shape for \"${type}\"`,\n          });\n        }\n      }\n    }\n  }\n\n  return repairs;\n}\n\n/**\n * Apply every safe auto-fix `validateSpec` proposes, iterating until the spec is\n * valid or no further progress can be made (a fix may unlock another \u2014 e.g.\n * correcting the chart `type` changes which channels are required). Pure: the\n * input spec is deep-cloned before any patch is applied.\n */\nexport function repairSpec(spec: unknown, options: RepairOptions = {}): RepairResult {\n  let current: unknown = spec;\n  const applied: JsonPatchOp[] = [];\n  const appliedDetails: AppliedRepair[] = [];\n  let prevSignature = '';\n  const level = options.level ?? 'safe';\n\n  for (let pass = 0; pass < MAX_PASSES; pass++) {\n    const { errors, warnings } = validateSpec(current);\n    const fixes: AppliedRepair[] = [];\n    for (const finding of [...errors, ...warnings]) {\n      if (finding.fix && finding.fix.length > 0) {\n        fixes.push(...finding.fix.map((op) => ({ op, rationale: rationaleForValidationFix(op) })));\n      }\n    }\n    if (level === 'data' && fixes.length === 0) {\n      fixes.push(...collectDataFixes(current, [...errors, ...warnings]));\n    }\n    if (fixes.length === 0) break;\n\n    // Guard against a non-converging fix set repeating forever.\n    const ops = fixes.map((fix) => fix.op);\n    const signature = JSON.stringify(ops);\n    if (signature === prevSignature) break;\n    prevSignature = signature;\n\n    current = applyPatch(current, ops);\n    applied.push(...ops);\n    appliedDetails.push(...fixes);\n  }\n\n  return { spec: current, applied, appliedDetails, remaining: validateSpec(current).errors };\n}\n"],
+  "mappings": "AAUA,SAAS,oBAAoB;AAC7B,SAAS,sBAAsB;AAC/B,SAAS,YAAY,iBAAmC;AACxD,SAAS,eAAe;AAmCxB,MAAM,aAAa;AAEnB,SAAS,SAAS,GAA0C;AAC1D,SAAO,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,CAAC;AAChE;AAEA,SAAS,UAAU,KAAc,MAAuB;AACtD,MAAI,SAAS,GAAI,QAAO;AACxB,MAAI,UAAU;AACd,aAAW,QAAQ,KAAK,QAAQ,cAAc,KAAK,EAAE,MAAM,GAAG,GAAG;AAC/D,QAAI,SAAS,GAAI;AACjB,QAAI,MAAM,QAAQ,OAAO,GAAG;AAC1B,gBAAU,QAAQ,OAAO,IAAI,CAAC;AAAA,IAChC,WAAW,SAAS,OAAO,GAAG;AAC5B,gBAAU,QAAQ,IAAI;AAAA,IACxB,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,SAAS,MAAsD;AACtE,MAAI,CAAC,SAAS,IAAI,KAAK,CAAC,MAAM,QAAQ,KAAK,IAAI,KAAK,KAAK,KAAK,WAAW,EAAG,QAAO;AACnF,MAAI,KAAK,KAAK,KAAK,CAAC,QAAQ,CAAC,SAAS,GAAG,KAAK,eAAe,IAAI,EAAG,QAAO;AAC3E,SAAO,KAAK;AACd;AAEA,SAAS,0BAA0B,IAAyB;AAC1D,SAAO,mCAAmC,GAAG,IAAI;AACnD;AAEA,SAAS,sBAAsB,MAAoC;AACjE,QAAM,OAAO,SAAS,IAAI;AAC1B,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,kBAAkB,eAAe,MAAM,EAAE,YAAY,GAAG,CAAC;AAC/D,MAAI,gBAAgB,WAAW,EAAG,QAAO;AACzC,QAAM,CAAC,KAAK,QAAQ,IAAI;AACxB,MAAI,IAAI,WAAW,iBAAkB,QAAO;AAC5C,MAAI,YAAY,IAAI,QAAQ,SAAS,QAAQ,IAAK,QAAO;AACzD,SAAO,IAAI;AACb;AAEA,SAAS,4BAA4B,MAAe,MAAmC;AACrF,QAAM,OAAO,SAAS,IAAI;AAC1B,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,UAAU,eAAe,MAAM,EAAE,YAAY,GAAG,CAAC,EAAE,OAAO,CAAC,QAAQ;AACvE,WAAO,SAAS,IAAI,IAAI,KAAK,IAAI,KAAK,SAAS,QAAQ,IAAI,WAAW;AAAA,EACxE,CAAC;AACD,SAAO,QAAQ,WAAW,IAAI,QAAQ,CAAC,EAAE,OAAO;AAClD;AAEA,SAAS,iBAAiB,MAAe,UAA8C;AACrF,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,CAAC;AAC7B,QAAM,UAA2B,CAAC;AAClC,aAAW,WAAW,UAAU;AAC9B,QAAI,QAAQ,YAAY,SAAS,QAAS;AAC1C,UAAM,QAAQ,UAAU,MAAM,QAAQ,IAAI;AAC1C,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,OAAO,QAAQ,OAAO,QAAQ,WAAW,UAAU;AACzD,QAAI,CAAC,QAAQ,SAAS,MAAO;AAC7B,YAAQ,KAAK;AAAA,MACX,IAAI,EAAE,IAAI,WAAW,MAAM,UAAU,QAAQ,IAAI,GAAG,OAAO,KAAK;AAAA,MAChE,WAAW,UAAU,KAAK,aAAQ,IAAI;AAAA,IACxC,CAAC;AAAA,EACH;AAEA,MAAI,UAAU,MAAM,MAAM,MAAM,QAAW;AACzC,UAAM,cAAc,sBAAsB,IAAI;AAC9C,QAAI,SAAS,WAAW,KAAK,OAAO,YAAY,SAAS,UAAU;AACjE,cAAQ,KAAK;AAAA,QACX,IAAI,EAAE,IAAI,OAAO,MAAM,SAAS,OAAO,YAAY,KAAK;AAAA,QACxD,WAAW,SAAS,YAAY,IAAI;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,OAAO,UAAU,MAAM,MAAM;AACnC,QAAM,WAAW,UAAU,MAAM,UAAU;AAC3C,MAAI,OAAO,SAAS,UAAU;AAC5B,UAAM,cAAc,4BAA4B,MAAM,IAAI;AAC1D,UAAM,sBAAsB,SAAS,WAAW,IAAI,YAAY,WAAW;AAC3E,QAAI,SAAS,mBAAmB,GAAG;AACjC,UAAI,CAAC,SAAS,QAAQ,KAAK,SAAS,KAAK,CAAC,YAAY,QAAQ,SAAS,UAAU,GAAG;AAClF,gBAAQ,KAAK;AAAA,UACX,IAAI,EAAE,IAAI,OAAO,MAAM,aAAa,OAAO,oBAAoB;AAAA,UAC/D,WAAW,0CAA0C,IAAI;AAAA,QAC3D,CAAC;AAAA,MACH,WAAW,SAAS,QAAQ,GAAG;AAC7B,mBAAW,WAAW,UAAU;AAC9B,gBAAM,QAAQ,sBAAsB,KAAK,QAAQ,IAAI;AACrD,cAAI,CAAC,MAAO;AACZ,gBAAM,UAAU,MAAM,CAAC;AACvB,cAAI,SAAS,OAAO,MAAM,UAAa,oBAAoB,OAAO,MAAM,OAAW;AACnF,kBAAQ,KAAK;AAAA,YACX,IAAI,EAAE,IAAI,OAAO,MAAM,UAAU,QAAQ,IAAI,GAAG,OAAO,oBAAoB,OAAO,EAAE;AAAA,YACpF,WAAW,YAAY,OAAO,mCAAmC,IAAI;AAAA,UACvE,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,WAAW,MAAe,UAAyB,CAAC,GAAiB;AACnF,MAAI,UAAmB;AACvB,QAAM,UAAyB,CAAC;AAChC,QAAM,iBAAkC,CAAC;AACzC,MAAI,gBAAgB;AACpB,QAAM,QAAQ,QAAQ,SAAS;AAE/B,WAAS,OAAO,GAAG,OAAO,YAAY,QAAQ;AAC5C,UAAM,EAAE,QAAQ,SAAS,IAAI,aAAa,OAAO;AACjD,UAAM,QAAyB,CAAC;AAChC,eAAW,WAAW,CAAC,GAAG,QAAQ,GAAG,QAAQ,GAAG;AAC9C,UAAI,QAAQ,OAAO,QAAQ,IAAI,SAAS,GAAG;AACzC,cAAM,KAAK,GAAG,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,WAAW,0BAA0B,EAAE,EAAE,EAAE,CAAC;AAAA,MAC3F;AAAA,IACF;AACA,QAAI,UAAU,UAAU,MAAM,WAAW,GAAG;AAC1C,YAAM,KAAK,GAAG,iBAAiB,SAAS,CAAC,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAAA,IACnE;AACA,QAAI,MAAM,WAAW,EAAG;AAGxB,UAAM,MAAM,MAAM,IAAI,CAAC,QAAQ,IAAI,EAAE;AACrC,UAAM,YAAY,KAAK,UAAU,GAAG;AACpC,QAAI,cAAc,cAAe;AACjC,oBAAgB;AAEhB,cAAU,WAAW,SAAS,GAAG;AACjC,YAAQ,KAAK,GAAG,GAAG;AACnB,mBAAe,KAAK,GAAG,KAAK;AAAA,EAC9B;AAEA,SAAO,EAAE,MAAM,SAAS,SAAS,gBAAgB,WAAW,aAAa,OAAO,EAAE,OAAO;AAC3F;",
+  "names": []
+}

package/dist/spec/selection.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Selection model — the declarative vocabulary for interactivity.
+ *
+ * A *selection* is the unit of interactivity: a named, JSON-serializable value
+ * that a visual publishes (by clicking marks, brushing, or changing a slicer)
+ * and that other visuals consume as either a **highlight** (emphasize matches,
+ * dim the rest) or a **filter** (subset the rows). Selections are plain data —
+ * no functions — so specs still round-trip through `JSON.stringify`.
+ *
+ * Inspired by Vega-Lite params/selections, but pared down to what coding agents
+ * need to wire dashboards: a `point`/`interval` definition, and four concrete
+ * resolved value shapes (point, set, range, text).
+ */
+/** How a selection is captured from user interaction. */
+export interface SelectionDef {
+    /**
+     * - `point`: discrete picks (click marks, choose categories). Toggling builds
+     *   a set of selected tuples.
+     * - `interval`: a continuous range (brush on an axis, a min/max slider, a date
+     *   range).
+     */
+    type: 'point' | 'interval';
+    /** Pointer event that updates the selection. Default `'click'`. */
+    on?: 'click' | 'hover';
+    /**
+     * Data fields that identify the selection. Defaults to the chart's key channel
+     * (e.g. the `x`/`series` field for cartesian charts, the `field` of a slicer).
+     */
+    fields?: string[];
+    /**
+     * Click an already-selected mark to deselect, and accumulate multiple picks.
+     * Default `true` for `on:'click'`.
+     */
+    toggle?: boolean;
+    /**
+     * What an *empty* selection means for consumers: `'all'` (the default) treats
+     * "nothing selected" as "match everything" (no dimming / no filtering);
+     * `'none'` treats it as "match nothing".
+     */
+    empty?: 'all' | 'none';
+}
+/** A named selection a visual defines. */
+export interface SelectionParam {
+    /** Unique name within a chart or dashboard. */
+    name: string;
+    select: SelectionDef;
+    /** Optional initial value. */
+    value?: SelectionValue;
+}
+/** Discrete picks: rows whose `fields` equal one of the selected `tuples`. */
+export interface PointSelection {
+    kind: 'point';
+    fields: string[];
+    /** Each tuple is one selected combination, aligned to `fields`. */
+    tuples: unknown[][];
+}
+/** Membership: rows whose `field` value is one of `values` (dropdown / list). */
+export interface SetSelection {
+    kind: 'set';
+    field: string;
+    values: unknown[];
+}
+/** A continuous span over `field` (numeric or temporal). Bounds are inclusive. */
+export interface RangeSelection {
+    kind: 'range';
+    field: string;
+    min?: number | string;
+    max?: number | string;
+}
+/** A case-insensitive substring match over `field` (search box). */
+export interface TextSelection {
+    kind: 'text';
+    field: string;
+    query: string;
+}
+/** The resolved value of a selection — what lives in the store. */
+export type SelectionValue = PointSelection | SetSelection | RangeSelection | TextSelection;
+/** Reference a named selection for highlighting. */
+export interface HighlightConfig {
+    /** The param whose current value drives the emphasis. */
+    param: string;
+}
+/**
+ * A literal, param-free predicate usable directly in `filter`. Each form maps to
+ * a {@link SelectionValue}, so the same matcher handles params and literals.
+ */
+export type LiteralPredicate = {
+    field: string;
+    equals: unknown;
+} | {
+    field: string;
+    oneOf: unknown[];
+} | {
+    field: string;
+    range: [number | string, number | string];
+} | {
+    field: string;
+    contains: string;
+};
+/** One clause of a `filter`: a named param or a literal predicate. */
+export type FilterClause = {
+    param: string;
+} | LiteralPredicate;
+//# sourceMappingURL=selection.d.ts.map

package/dist/spec/selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../src/spec/selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,mEAAmE;IACnE,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,YAAY,GAAG,cAAc,GAAG,aAAa,CAAC;AAE5F,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAClC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;CAAE,GAC5D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAAC"}

package/dist/spec/selection.js

@@ -0,0 +1 @@
+//# sourceMappingURL=selection.js.map

package/dist/spec/selection.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/spec/sketch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve a spec's `sketch` option into concrete, fully-defaulted knobs for the
+ * rough engine. Returns `null` when sketching is off, which lets every chart
+ * keep its pixel-identical clean path with a single early check.
+ *
+ * The seed is derived deterministically from the spec's identity when the author
+ * doesn't pass one, so the same chart always wobbles the same way (required for
+ * the screenshot harness).
+ */
+import { type RoughStyle } from '../rough/index.js';
+import type { ChartSpec } from './types.js';
+/** Fully-resolved sketch settings handed to charts / the rough pen. */
+export interface ResolvedSketch extends RoughStyle {
+    /** Whether text should use the hand-drawn font. */
+    font: boolean;
+}
+/**
+ * Map `spec.sketch` to a `ResolvedSketch`, or `null` when disabled.
+ * `sketch: true` uses all defaults; an object overrides individual knobs.
+ */
+export declare function resolveSketch(spec: ChartSpec): ResolvedSketch | null;
+//# sourceMappingURL=sketch.d.ts.map

package/dist/spec/sketch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch.d.ts","sourceRoot":"","sources":["../../src/spec/sketch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,KAAK,EAAY,SAAS,EAAgB,MAAM,SAAS,CAAC;AAEjE,uEAAuE;AACvE,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,mDAAmD;IACnD,IAAI,EAAE,OAAO,CAAC;CACf;AAUD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,GAAG,IAAI,CAepE"}

package/dist/spec/sketch.js

@@ -0,0 +1,26 @@
+import { DEFAULT_ROUGH_STYLE, hashString } from "../rough/index.js";
+function deriveSeed(spec) {
+  const title = typeof spec.title === "string" ? spec.title : spec.title?.text ?? spec.title?.subtitle ?? "";
+  const dataLen = Array.isArray(spec.data) ? spec.data.length : 0;
+  const firstRow = Array.isArray(spec.data) && spec.data[0] ? Object.keys(spec.data[0]).join(",") : "";
+  return hashString(`${spec.type}|${title}|${dataLen}|${firstRow}`) || 1;
+}
+function resolveSketch(spec) {
+  const sketch = spec.sketch;
+  if (!sketch) return null;
+  const cfg = sketch === true ? {} : sketch;
+  return {
+    roughness: cfg.roughness ?? DEFAULT_ROUGH_STYLE.roughness,
+    bowing: cfg.bowing ?? DEFAULT_ROUGH_STYLE.bowing,
+    fillStyle: cfg.fillStyle ?? DEFAULT_ROUGH_STYLE.fillStyle,
+    hachureGap: cfg.hachureGap ?? DEFAULT_ROUGH_STYLE.hachureGap,
+    hachureAngle: cfg.hachureAngle ?? DEFAULT_ROUGH_STYLE.hachureAngle,
+    strokeWidth: cfg.strokeWidth ?? DEFAULT_ROUGH_STYLE.strokeWidth,
+    seed: (cfg.seed ?? deriveSeed(spec)) >>> 0,
+    font: cfg.font ?? true
+  };
+}
+export {
+  resolveSketch
+};
+//# sourceMappingURL=sketch.js.map

package/dist/spec/sketch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/spec/sketch.ts"],
+  "sourcesContent": ["/**\n * Resolve a spec's `sketch` option into concrete, fully-defaulted knobs for the\n * rough engine. Returns `null` when sketching is off, which lets every chart\n * keep its pixel-identical clean path with a single early check.\n *\n * The seed is derived deterministically from the spec's identity when the author\n * doesn't pass one, so the same chart always wobbles the same way (required for\n * the screenshot harness).\n */\n\nimport { DEFAULT_ROUGH_STYLE, hashString, type RoughStyle } from '../rough';\nimport type { BaseSpec, ChartSpec, SketchConfig } from './types';\n\n/** Fully-resolved sketch settings handed to charts / the rough pen. */\nexport interface ResolvedSketch extends RoughStyle {\n  /** Whether text should use the hand-drawn font. */\n  font: boolean;\n}\n\nfunction deriveSeed(spec: ChartSpec): number {\n  const title =\n    typeof spec.title === 'string' ? spec.title : (spec.title?.text ?? spec.title?.subtitle ?? '');\n  const dataLen = Array.isArray(spec.data) ? spec.data.length : 0;\n  const firstRow = Array.isArray(spec.data) && spec.data[0] ? Object.keys(spec.data[0]).join(',') : '';\n  return hashString(`${spec.type}|${title}|${dataLen}|${firstRow}`) || 1;\n}\n\n/**\n * Map `spec.sketch` to a `ResolvedSketch`, or `null` when disabled.\n * `sketch: true` uses all defaults; an object overrides individual knobs.\n */\nexport function resolveSketch(spec: ChartSpec): ResolvedSketch | null {\n  const sketch = (spec as BaseSpec).sketch;\n  if (!sketch) return null;\n  const cfg: SketchConfig = sketch === true ? {} : sketch;\n\n  return {\n    roughness: cfg.roughness ?? DEFAULT_ROUGH_STYLE.roughness,\n    bowing: cfg.bowing ?? DEFAULT_ROUGH_STYLE.bowing,\n    fillStyle: cfg.fillStyle ?? DEFAULT_ROUGH_STYLE.fillStyle,\n    hachureGap: cfg.hachureGap ?? DEFAULT_ROUGH_STYLE.hachureGap,\n    hachureAngle: cfg.hachureAngle ?? DEFAULT_ROUGH_STYLE.hachureAngle,\n    strokeWidth: cfg.strokeWidth ?? DEFAULT_ROUGH_STYLE.strokeWidth,\n    seed: (cfg.seed ?? deriveSeed(spec)) >>> 0,\n    font: cfg.font ?? true,\n  };\n}\n"],
+  "mappings": "AAUA,SAAS,qBAAqB,kBAAmC;AASjE,SAAS,WAAW,MAAyB;AAC3C,QAAM,QACJ,OAAO,KAAK,UAAU,WAAW,KAAK,QAAS,KAAK,OAAO,QAAQ,KAAK,OAAO,YAAY;AAC7F,QAAM,UAAU,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;AAC9D,QAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;AAClG,SAAO,WAAW,GAAG,KAAK,IAAI,IAAI,KAAK,IAAI,OAAO,IAAI,QAAQ,EAAE,KAAK;AACvE;AAMO,SAAS,cAAc,MAAwC;AACpE,QAAM,SAAU,KAAkB;AAClC,MAAI,CAAC,OAAQ,QAAO;AACpB,QAAM,MAAoB,WAAW,OAAO,CAAC,IAAI;AAEjD,SAAO;AAAA,IACL,WAAW,IAAI,aAAa,oBAAoB;AAAA,IAChD,QAAQ,IAAI,UAAU,oBAAoB;AAAA,IAC1C,WAAW,IAAI,aAAa,oBAAoB;AAAA,IAChD,YAAY,IAAI,cAAc,oBAAoB;AAAA,IAClD,cAAc,IAAI,gBAAgB,oBAAoB;AAAA,IACtD,aAAa,IAAI,eAAe,oBAAoB;AAAA,IACpD,OAAO,IAAI,QAAQ,WAAW,IAAI,OAAO;AAAA,IACzC,MAAM,IAAI,QAAQ;AAAA,EACpB;AACF;",
+  "names": []
+}

package/dist/spec/suggest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tiny dependency-free closest-match helper powering "did you mean" suggestions
+ * and safe auto-repairs. Used by `validateSpec` (to annotate unknown
+ * types/enums/fields) and `repairSpec` (to pick an unambiguous correction).
+ */
+/** Classic Levenshtein edit distance (insert/delete/substitute = 1). */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Up to `limit` plausible corrections for `input`, nearest first, filtered to a
+ * length-relative edit-distance tolerance. Generous — good for "did you mean".
+ */
+export declare function suggestions(input: string, candidates: readonly string[], limit?: number, maxDistance?: number): string[];
+/**
+ * The single best correction for `input`, but only when it is **unambiguous and
+ * close** — a strict distance bound and a clear margin over the runner-up — so it
+ * is safe to apply automatically. Returns `undefined` when no safe pick exists.
+ */
+export declare function closest(input: string, candidates: readonly string[]): string | undefined;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/spec/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/spec/suggest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAwBD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,KAAK,SAAI,EACT,WAAW,SAAmB,GAC7B,MAAM,EAAE,CAMV;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAYxF"}