bbdata-cli 0.1.1 → 0.3.0

package/dist/bin/bbdata.js

@@ -213,6 +213,8 @@ var SavantAdapter = class {
       plate_z: Number(row.plate_z) || 0,
       launch_speed: row.launch_speed != null ? Number(row.launch_speed) || null : null,
       launch_angle: row.launch_angle != null ? Number(row.launch_angle) || null : null,
+      hc_x: row.hc_x != null && row.hc_x !== "" ? Number(row.hc_x) || null : null,
+      hc_y: row.hc_y != null && row.hc_y !== "" ? Number(row.hc_y) || null : null,
       description: String(row.description ?? ""),
       events: row.events ? String(row.events) : null,
       bb_type: row.bb_type ? String(row.bb_type) : null,
@@ -401,13 +403,88 @@ var BaseballReferenceAdapter = class {
   }
 };
 
+// src/adapters/stdin.ts
+var StdinAdapter = class {
+  source = "stdin";
+  description = "Local data from stdin (for sandboxed environments)";
+  data = [];
+  player = null;
+  loaded = false;
+  /**
+   * Load data from a pre-read stdin string.
+   * Called by the CLI before the adapter is used.
+   */
+  load(raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        this.data = parsed;
+      } else if (parsed.data && Array.isArray(parsed.data)) {
+        this.data = parsed.data;
+        if (parsed.player) {
+          this.player = parsed.player;
+        }
+      } else {
+        throw new Error('Expected JSON array or { "data": [...] } object');
+      }
+      this.loaded = true;
+      log.info(`Stdin adapter loaded ${this.data.length} records`);
+    } catch (error) {
+      throw new Error(
+        `Failed to parse stdin data: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  supports(_query) {
+    return this.loaded && this.data.length > 0;
+  }
+  async fetch(query2) {
+    if (!this.loaded) {
+      throw new Error("Stdin adapter has no data \u2014 pipe JSON via stdin with --stdin flag");
+    }
+    return {
+      data: this.data,
+      source: "stdin",
+      cached: false,
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      meta: {
+        rowCount: this.data.length,
+        season: query2.season,
+        query: query2
+      }
+    };
+  }
+  async resolvePlayer(name) {
+    if (this.player && this.player.name.toLowerCase() === name.toLowerCase()) {
+      return this.player;
+    }
+    const firstRecord = this.data[0];
+    if (firstRecord) {
+      const id = firstRecord.pitcher_id ?? firstRecord.player_id ?? "";
+      const recordName = firstRecord.pitcher_name ?? firstRecord.player_name ?? name;
+      if (id) {
+        return {
+          mlbam_id: id,
+          name: recordName
+        };
+      }
+    }
+    return null;
+  }
+};
+
 // src/adapters/index.ts
+var stdinAdapter = new StdinAdapter();
 var adapters = {
   "mlb-stats-api": new MlbStatsApiAdapter(),
   "savant": new SavantAdapter(),
   "fangraphs": new FanGraphsAdapter(),
-  "baseball-reference": new BaseballReferenceAdapter()
+  "baseball-reference": new BaseballReferenceAdapter(),
+  "stdin": stdinAdapter
 };
+function getStdinAdapter() {
+  return stdinAdapter;
+}
 function resolveAdapters(preferred) {
   return preferred.map((source) => adapters[source]).filter(Boolean);
 }
@@ -578,10 +655,24 @@ function getTemplatesDir() {
   return dir;
 }
 
+// src/utils/stdin.ts
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      reject(new Error(`--stdin flag requires piped input. Usage: echo '{"data":[...]}' | bbdata query ... --stdin`));
+      return;
+    }
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("error", reject);
+  });
+}
+
 // src/templates/queries/registry.ts
 var templates = /* @__PURE__ */ new Map();
-function registerTemplate(template13) {
-  templates.set(template13.id, template13);
+function registerTemplate(template16) {
+  templates.set(template16.id, template16);
 }
 function getTemplate(id) {
   return templates.get(id);
@@ -624,6 +715,10 @@ var PitchDataSchema = z2.object({
   // exit velocity (mph)
   launch_angle: z2.number().nullable(),
   // degrees
+  hc_x: z2.number().nullable(),
+  // Statcast hit coordinate x (horizontal)
+  hc_y: z2.number().nullable(),
+  // Statcast hit coordinate y (distance from home)
   description: z2.string(),
   // called_strike, swinging_strike, ball, foul, hit_into_play, etc.
   events: z2.string().nullable(),
@@ -1321,7 +1416,7 @@ var template11 = {
     };
   },
   columns() {
-    return ["Window", "Games", "AVG", "SLG", "K %", "Avg EV", "Hard Hit %"];
+    return ["Window", "Window End", "Games", "AVG", "SLG", "K %", "Avg EV", "Hard Hit %"];
   },
   transform(data) {
     const pitches = data;
@@ -1335,7 +1430,16 @@ var template11 = {
     const dates = Array.from(byDate.keys()).sort();
     const windowSize = 15;
     if (dates.length < windowSize) {
-      return [{ Window: "Insufficient data", Games: dates.length, AVG: "\u2014", SLG: "\u2014", "K %": "\u2014", "Avg EV": "\u2014", "Hard Hit %": "\u2014" }];
+      return [{
+        Window: "Insufficient data",
+        "Window End": "",
+        Games: dates.length,
+        AVG: "\u2014",
+        SLG: "\u2014",
+        "K %": "\u2014",
+        "Avg EV": "\u2014",
+        "Hard Hit %": "\u2014"
+      }];
     }
     const results = [];
     for (let i = 0; i <= dates.length - windowSize; i += Math.max(1, Math.floor(windowSize / 3))) {
@@ -1354,8 +1458,10 @@ var template11 = {
       const batted = windowPitches.filter((p) => p.launch_speed !== null && p.launch_speed > 0);
       const avgEv = batted.length > 0 ? batted.reduce((s, p) => s + p.launch_speed, 0) / batted.length : null;
       const hardHit = batted.filter((p) => p.launch_speed >= 95).length;
+      const windowEnd = windowDates[windowDates.length - 1];
       results.push({
-        Window: `${windowDates[0]} \u2192 ${windowDates[windowDates.length - 1]}`,
+        Window: `${windowDates[0]} \u2192 ${windowEnd}`,
+        "Window End": windowEnd,
         Games: windowDates.length,
         AVG: pas.length > 0 ? (hits.length / pas.length).toFixed(3) : "\u2014",
         SLG: pas.length > 0 ? (totalBases / pas.length).toFixed(3) : "\u2014",
@@ -1427,12 +1533,182 @@ function formatVal(n) {
 }
 registerTemplate(template12);
 
+// src/templates/queries/pitcher-raw-pitches.ts
+var template13 = {
+  id: "pitcher-raw-pitches",
+  name: "Pitcher Raw Pitches",
+  category: "pitcher",
+  description: "One row per pitch with coordinate columns for visualization (movement, location)",
+  preferredSources: ["savant"],
+  requiredParams: ["player"],
+  optionalParams: ["season", "pitchType"],
+  examples: [
+    'bbdata query pitcher-raw-pitches --player "Corbin Burnes" --season 2025 --format json'
+  ],
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? (/* @__PURE__ */ new Date()).getFullYear(),
+      stat_type: "pitching",
+      pitch_type: params.pitchType ? [params.pitchType] : void 0
+    };
+  },
+  columns() {
+    return [
+      "pitch_type",
+      "release_speed",
+      "release_spin_rate",
+      "pfx_x",
+      "pfx_z",
+      "plate_x",
+      "plate_z",
+      "game_date"
+    ];
+  },
+  transform(data) {
+    const pitches = data;
+    if (pitches.length === 0) return [];
+    return pitches.filter((p) => p.pitch_type).map((p) => ({
+      pitch_type: p.pitch_type,
+      release_speed: p.release_speed,
+      release_spin_rate: p.release_spin_rate,
+      pfx_x: p.pfx_x,
+      pfx_z: p.pfx_z,
+      plate_x: p.plate_x,
+      plate_z: p.plate_z,
+      game_date: p.game_date
+    }));
+  }
+};
+registerTemplate(template13);
+
+// src/templates/queries/hitter-raw-bip.ts
+var template14 = {
+  id: "hitter-raw-bip",
+  name: "Hitter Raw Batted Balls",
+  category: "hitter",
+  description: "One row per batted ball with hit coordinates, exit velo, and launch angle",
+  preferredSources: ["savant"],
+  requiredParams: ["player"],
+  optionalParams: ["season"],
+  examples: [
+    'bbdata query hitter-raw-bip --player "Aaron Judge" --season 2025 --format json'
+  ],
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? (/* @__PURE__ */ new Date()).getFullYear(),
+      stat_type: "batting"
+    };
+  },
+  columns() {
+    return [
+      "hc_x",
+      "hc_y",
+      "launch_speed",
+      "launch_angle",
+      "events",
+      "bb_type",
+      "game_date"
+    ];
+  },
+  transform(data) {
+    const pitches = data;
+    if (pitches.length === 0) return [];
+    return pitches.filter(
+      (p) => p.launch_speed != null && p.launch_speed > 0 && p.hc_x != null && p.hc_y != null
+    ).map((p) => ({
+      hc_x: p.hc_x,
+      hc_y: p.hc_y,
+      launch_speed: p.launch_speed,
+      launch_angle: p.launch_angle,
+      events: p.events ?? "unknown",
+      bb_type: p.bb_type ?? "unknown",
+      game_date: p.game_date
+    }));
+  }
+};
+registerTemplate(template14);
+
+// src/templates/queries/hitter-zone-grid.ts
+var ZONES2 = [
+  { name: "High-In", row: 0, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.83, zMax: 3.5 },
+  { name: "High-Mid", row: 0, col: 1, xMin: -0.28, xMax: 0.28, zMin: 2.83, zMax: 3.5 },
+  { name: "High-Out", row: 0, col: 2, xMin: 0.28, xMax: 0.83, zMin: 2.83, zMax: 3.5 },
+  { name: "Mid-In", row: 1, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.17, zMax: 2.83 },
+  { name: "Mid-Mid", row: 1, col: 1, xMin: -0.28, xMax: 0.28, zMin: 2.17, zMax: 2.83 },
+  { name: "Mid-Out", row: 1, col: 2, xMin: 0.28, xMax: 0.83, zMin: 2.17, zMax: 2.83 },
+  { name: "Low-In", row: 2, col: 0, xMin: -0.83, xMax: -0.28, zMin: 1.5, zMax: 2.17 },
+  { name: "Low-Mid", row: 2, col: 1, xMin: -0.28, xMax: 0.28, zMin: 1.5, zMax: 2.17 },
+  { name: "Low-Out", row: 2, col: 2, xMin: 0.28, xMax: 0.83, zMin: 1.5, zMax: 2.17 }
+];
+var template15 = {
+  id: "hitter-zone-grid",
+  name: "Hitter Zone Grid (numeric)",
+  category: "hitter",
+  description: "3x3 strike zone grid with numeric row/col/xwoba for heatmap visualization",
+  preferredSources: ["savant"],
+  requiredParams: ["player"],
+  optionalParams: ["season"],
+  examples: [
+    'bbdata query hitter-zone-grid --player "Shohei Ohtani" --format json'
+  ],
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? (/* @__PURE__ */ new Date()).getFullYear(),
+      stat_type: "batting"
+    };
+  },
+  columns() {
+    return ["zone", "row", "col", "pitches", "xwoba"];
+  },
+  transform(data) {
+    const pitches = data;
+    if (pitches.length === 0) return [];
+    return ZONES2.map((z3) => {
+      const inZone = pitches.filter(
+        (p) => p.plate_x >= z3.xMin && p.plate_x < z3.xMax && p.plate_z >= z3.zMin && p.plate_z < z3.zMax
+      );
+      const paEnding = inZone.filter((p) => p.events != null);
+      let xwobaSum = 0;
+      for (const p of paEnding) {
+        if (p.events === "walk") {
+          xwobaSum += 0.69;
+        } else if (p.events === "hit_by_pitch") {
+          xwobaSum += 0.72;
+        } else if (p.events === "strikeout") {
+          xwobaSum += 0;
+        } else {
+          xwobaSum += p.estimated_woba ?? 0;
+        }
+      }
+      const xwoba = paEnding.length > 0 ? xwobaSum / paEnding.length : 0;
+      return {
+        zone: z3.name,
+        row: z3.row,
+        col: z3.col,
+        pitches: inZone.length,
+        pa: paEnding.length,
+        xwoba: Number(xwoba.toFixed(3))
+      };
+    });
+  }
+};
+registerTemplate(template15);
+
 // src/commands/query.ts
 async function query(options) {
+  if (options.stdin) {
+    const raw = await readStdin();
+    const adapter = getStdinAdapter();
+    adapter.load(raw);
+    options.source = "stdin";
+  }
   const config = getConfig();
   const outputFormat = options.format ?? config.defaultFormat;
-  const template13 = getTemplate(options.template);
-  if (!template13) {
+  const template16 = getTemplate(options.template);
+  if (!template16) {
     const available = listTemplates().map((t) => `  ${t.id} \u2014 ${t.description}`).join("\n");
     throw new Error(`Unknown template "${options.template}". Available templates:
 ${available}`);
@@ -1449,13 +1725,13 @@ ${available}`);
     top: options.top,
     seasons: options.seasons
   };
-  for (const req of template13.requiredParams) {
+  for (const req of template16.requiredParams) {
     if (!params[req] && !(req === "players" && params.player)) {
-      throw new Error(`Template "${template13.id}" requires --${req}`);
+      throw new Error(`Template "${template16.id}" requires --${req}`);
     }
   }
-  const adapterQuery = template13.buildQuery(params);
-  const preferredSources = options.source ? [options.source] : template13.preferredSources;
+  const adapterQuery = template16.buildQuery(params);
+  const preferredSources = options.source ? [options.source] : template16.preferredSources;
   const adapters2 = resolveAdapters(preferredSources);
   let lastError;
   let result;
@@ -1467,8 +1743,8 @@ ${available}`);
       const adapterResult = await adapter.fetch(adapterQuery, {
         bypassCache: options.cache === false
       });
-      const rows = template13.transform(adapterResult.data, params);
-      const columns = template13.columns(params);
+      const rows = template16.transform(adapterResult.data, params);
+      const columns = template16.columns(params);
       if (rows.length === 0) {
         log.debug(`${adapter.source} returned 0 rows. Trying next source...`);
         continue;
@@ -1476,8 +1752,8 @@ ${available}`);
       result = {
         rows,
         columns,
-        title: template13.name,
-        description: template13.description,
+        title: template16.name,
+        description: template16.description,
         source: adapter.source,
         cached: adapterResult.cached
       };
@@ -1497,13 +1773,13 @@ ${available}`);
     queryTimeMs,
     season: params.season ?? (/* @__PURE__ */ new Date()).getFullYear(),
     sampleSize: result.rows.length,
-    template: template13.id
+    template: template16.id
   }, outputFormat, { columns: result.columns });
   return {
     data: result.rows,
     formatted: output.formatted,
     meta: {
-      template: template13.id,
+      template: template16.id,
       source: result.source,
       cached: result.cached,
       rowCount: result.rows.length,
@@ -1512,7 +1788,7 @@ ${available}`);
   };
 }
 function registerQueryCommand(program2) {
-  const cmd = program2.command("query [template]").description("Query baseball data using pre-built templates").option("-p, --player <name>", "Player name").option("--players <names>", "Comma-separated player names (for matchups/comparisons)").option("-s, --season <year>", "Season year", String((/* @__PURE__ */ new Date()).getFullYear())).option("-f, --format <fmt>", "Output: json, table, csv, markdown", "json").option("--source <src>", "Force a data source: savant, fangraphs, mlb-stats-api").option("--stat <stat>", "Stat to query (for leaderboards)").option("--pitch-type <type>", "Filter by pitch type (e.g., FF, SL)").option("--min-pa <n>", "Minimum plate appearances", parseInt).option("--min-ip <n>", "Minimum innings pitched", parseInt).option("--top <n>", "Number of results for leaderboards", parseInt).option("--seasons <range>", "Season range (e.g., 2023-2025)").option("--no-cache", "Bypass cache").addHelpText("after", `
+  const cmd = program2.command("query [template]").description("Query baseball data using pre-built templates").option("-p, --player <name>", "Player name").option("--players <names>", "Comma-separated player names (for matchups/comparisons)").option("-s, --season <year>", "Season year", String((/* @__PURE__ */ new Date()).getFullYear())).option("-f, --format <fmt>", "Output: json, table, csv, markdown", "json").option("--source <src>", "Force a data source: savant, fangraphs, mlb-stats-api").option("--stat <stat>", "Stat to query (for leaderboards)").option("--pitch-type <type>", "Filter by pitch type (e.g., FF, SL)").option("--min-pa <n>", "Minimum plate appearances", parseInt).option("--min-ip <n>", "Minimum innings pitched", parseInt).option("--top <n>", "Number of results for leaderboards", parseInt).option("--seasons <range>", "Season range (e.g., 2023-2025)").option("--no-cache", "Bypass cache").option("--stdin", "Read pre-fetched JSON data from stdin instead of fetching from APIs").addHelpText("after", `
 Examples:
   bbdata query pitcher-arsenal --player "Corbin Burnes" --season 2025
   bbdata query hitter-batted-ball --player "Aaron Judge" --format table
@@ -1551,7 +1827,8 @@ Available templates:
         seasons: opts.seasons,
         format: opts.format,
         source: opts.source,
-        cache: opts.cache
+        cache: opts.cache,
+        stdin: opts.stdin
       });
       log.data(result.formatted);
     } catch (error) {
@@ -1592,10 +1869,721 @@ function formatGrade(grade) {
   return `${gradeColor(grade)} (${gradeLabel(grade)})`;
 }
 
+// src/commands/viz.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+import { resolve as resolvePath } from "path";
+
+// src/viz/audience.ts
+var AUDIENCE_DEFAULTS = {
+  coach: {
+    width: 800,
+    height: 600,
+    titleFontSize: 22,
+    axisLabelFontSize: 18,
+    axisTitleFontSize: 18,
+    legendLabelFontSize: 16,
+    legendTitleFontSize: 16,
+    scheme: "tableau10",
+    labelDensity: "low",
+    padding: 24
+  },
+  analyst: {
+    width: 640,
+    height: 480,
+    titleFontSize: 16,
+    axisLabelFontSize: 12,
+    axisTitleFontSize: 13,
+    legendLabelFontSize: 11,
+    legendTitleFontSize: 12,
+    scheme: "tableau10",
+    labelDensity: "high",
+    padding: 12
+  },
+  frontoffice: {
+    width: 720,
+    height: 540,
+    titleFontSize: 18,
+    axisLabelFontSize: 13,
+    axisTitleFontSize: 14,
+    legendLabelFontSize: 12,
+    legendTitleFontSize: 13,
+    scheme: "tableau10",
+    labelDensity: "medium",
+    padding: 16
+  },
+  presentation: {
+    width: 960,
+    height: 720,
+    titleFontSize: 24,
+    axisLabelFontSize: 16,
+    axisTitleFontSize: 18,
+    legendLabelFontSize: 14,
+    legendTitleFontSize: 16,
+    scheme: "tableau10",
+    labelDensity: "low",
+    padding: 24
+  }
+};
+function audienceConfig(audience, colorblind) {
+  const d = AUDIENCE_DEFAULTS[audience];
+  return {
+    font: "Arial, Helvetica, sans-serif",
+    padding: d.padding,
+    title: {
+      fontSize: d.titleFontSize,
+      anchor: "start",
+      font: "Arial, Helvetica, sans-serif"
+    },
+    axis: {
+      labelFontSize: d.axisLabelFontSize,
+      titleFontSize: d.axisTitleFontSize,
+      labelFont: "Arial, Helvetica, sans-serif",
+      titleFont: "Arial, Helvetica, sans-serif",
+      grid: true
+    },
+    legend: {
+      labelFontSize: d.legendLabelFontSize,
+      titleFontSize: d.legendTitleFontSize,
+      labelFont: "Arial, Helvetica, sans-serif",
+      titleFont: "Arial, Helvetica, sans-serif"
+    },
+    range: colorblind ? { category: { scheme: "viridis" }, ramp: { scheme: "viridis" } } : { category: { scheme: d.scheme } },
+    view: { stroke: "transparent" },
+    background: "white"
+  };
+}
+
+// src/viz/charts/movement.ts
+var movementBuilder = {
+  id: "movement",
+  dataRequirements: [
+    { queryTemplate: "pitcher-raw-pitches", required: true }
+  ],
+  defaultTitle({ player, season }) {
+    return `${player} \u2014 Pitch Movement (${season})`;
+  },
+  buildSpec(rows, options) {
+    const pitches = rows["pitcher-raw-pitches"] ?? [];
+    const values = pitches.map((p) => ({
+      pitch_type: p.pitch_type,
+      hBreak: -p.pfx_x * 12,
+      // feet → inches, flipped
+      vBreak: p.pfx_z * 12,
+      velo: p.release_speed
+    }));
+    return {
+      $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+      title: options.title,
+      width: options.width,
+      height: options.height,
+      data: { values },
+      layer: [
+        {
+          mark: { type: "rule", stroke: "#888", strokeDash: [4, 4] },
+          encoding: { x: { datum: 0 } }
+        },
+        {
+          mark: { type: "rule", stroke: "#888", strokeDash: [4, 4] },
+          encoding: { y: { datum: 0 } }
+        },
+        {
+          mark: { type: "point", filled: true, opacity: 0.65, size: 60 },
+          encoding: {
+            x: {
+              field: "hBreak",
+              type: "quantitative",
+              scale: { domain: [-25, 25] },
+              axis: { title: "Horizontal Break (in, catcher POV)" }
+            },
+            y: {
+              field: "vBreak",
+              type: "quantitative",
+              scale: { domain: [-25, 25] },
+              axis: { title: "Induced Vertical Break (in)" }
+            },
+            color: {
+              field: "pitch_type",
+              type: "nominal",
+              legend: { title: "Pitch" }
+            },
+            tooltip: [
+              { field: "pitch_type", title: "Type" },
+              { field: "velo", title: "Velo (mph)", format: ".1f" },
+              { field: "hBreak", title: "H Break (in)", format: ".1f" },
+              { field: "vBreak", title: "V Break (in)", format: ".1f" }
+            ]
+          }
+        },
+        {
+          mark: {
+            type: "point",
+            shape: "cross",
+            size: 500,
+            strokeWidth: 3,
+            filled: false
+          },
+          encoding: {
+            x: { aggregate: "mean", field: "hBreak", type: "quantitative" },
+            y: { aggregate: "mean", field: "vBreak", type: "quantitative" },
+            color: { field: "pitch_type", type: "nominal" },
+            detail: { field: "pitch_type" }
+          }
+        }
+      ],
+      config: audienceConfig(options.audience, options.colorblind)
+    };
+  }
+};
+
+// src/viz/charts/spray.ts
+var sprayBuilder = {
+  id: "spray",
+  dataRequirements: [
+    { queryTemplate: "hitter-raw-bip", required: true }
+  ],
+  defaultTitle({ player, season }) {
+    return `${player} \u2014 Spray Chart (${season})`;
+  },
+  buildSpec(rows, options) {
+    const bip = rows["hitter-raw-bip"] ?? [];
+    const SCALE = 2.5;
+    const points = bip.map((b) => ({
+      x: (b.hc_x - 125.42) * SCALE,
+      y: (204 - b.hc_y) * SCALE,
+      launch_speed: b.launch_speed ?? 0,
+      launch_angle: b.launch_angle ?? 0,
+      events: b.events
+    }));
+    const arc = Array.from({ length: 37 }, (_, i) => {
+      const t = Math.PI / 4 + Math.PI / 2 * (i / 36);
+      return { x: Math.cos(t) * 420 * -1, y: Math.sin(t) * 420 };
+    });
+    return {
+      $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+      title: options.title,
+      width: options.width,
+      height: options.height,
+      layer: [
+        // Batted-ball points (first layer controls scales/axes for the chart)
+        {
+          data: { values: points },
+          mark: { type: "circle", opacity: 0.75, stroke: "#333", strokeWidth: 0.5 },
+          encoding: {
+            x: {
+              field: "x",
+              type: "quantitative",
+              scale: { domain: [-450, 450] },
+              axis: null
+            },
+            y: {
+              field: "y",
+              type: "quantitative",
+              scale: { domain: [-50, 500] },
+              axis: null
+            },
+            size: {
+              field: "launch_speed",
+              type: "quantitative",
+              scale: { domain: [60, 115], range: [40, 400] },
+              legend: { title: "Exit Velo" }
+            },
+            color: {
+              field: "events",
+              type: "nominal",
+              scale: {
+                domain: [
+                  "single",
+                  "double",
+                  "triple",
+                  "home_run",
+                  "field_out",
+                  "force_out",
+                  "grounded_into_double_play"
+                ],
+                range: [
+                  "#4e79a7",
+                  "#59a14f",
+                  "#edc948",
+                  "#e15759",
+                  "#bab0ac",
+                  "#bab0ac",
+                  "#bab0ac"
+                ]
+              },
+              legend: { title: "Result" }
+            },
+            tooltip: [
+              { field: "events", title: "Result" },
+              { field: "launch_speed", title: "EV", format: ".1f" },
+              { field: "launch_angle", title: "LA", format: ".0f" }
+            ]
+          }
+        },
+        // Foul lines — left field
+        {
+          data: { values: [{ x: 0, y: 0 }, { x: -297, y: 297 }] },
+          mark: { type: "line", stroke: "#888", strokeWidth: 1.5 },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" }
+          }
+        },
+        // Foul lines — right field
+        {
+          data: { values: [{ x: 0, y: 0 }, { x: 297, y: 297 }] },
+          mark: { type: "line", stroke: "#888", strokeWidth: 1.5 },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" }
+          }
+        },
+        // Outfield arc
+        {
+          data: { values: arc },
+          mark: { type: "line", stroke: "#999", strokeDash: [6, 4], strokeWidth: 1.5 },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" }
+          }
+        }
+      ],
+      config: {
+        ...audienceConfig(options.audience, options.colorblind),
+        axis: { grid: false, domain: false, ticks: false, labels: false }
+      }
+    };
+  }
+};
+
+// src/viz/charts/zone.ts
+var zoneBuilder = {
+  id: "zone",
+  dataRequirements: [
+    { queryTemplate: "hitter-zone-grid", required: true }
+  ],
+  defaultTitle({ player, season }) {
+    return `${player} \u2014 Zone Profile, xwOBA (${season})`;
+  },
+  buildSpec(rows, options) {
+    const grid = rows["hitter-zone-grid"] ?? [];
+    return {
+      $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+      title: options.title,
+      width: options.width,
+      height: options.height,
+      data: { values: grid },
+      layer: [
+        {
+          mark: { type: "rect", stroke: "#222", strokeWidth: 1.5 },
+          encoding: {
+            x: {
+              field: "col",
+              type: "ordinal",
+              axis: { title: "Inside  \u2192  Outside", labels: false, ticks: false }
+            },
+            y: {
+              field: "row",
+              type: "ordinal",
+              axis: { title: "High  \u2192  Low", labels: false, ticks: false }
+            },
+            color: {
+              field: "xwoba",
+              type: "quantitative",
+              // Domain covers the league-wide realistic range for xwOBA
+              // (~.200 is Mendoza-esque; ~.500 is MVP-tier).
+              // `clamp: true` caps values outside the range to the endpoint
+              // colors so elite hitters still render cleanly.
+              scale: options.colorblind ? { scheme: "viridis", domain: [0.2, 0.5], clamp: true } : {
+                scheme: "redyellowblue",
+                reverse: true,
+                domain: [0.2, 0.5],
+                clamp: true
+              },
+              legend: { title: "xwOBA" }
+            },
+            tooltip: [
+              { field: "zone", title: "Zone" },
+              { field: "pitches", title: "Pitches" },
+              { field: "pa", title: "PAs" },
+              { field: "xwoba", title: "xwOBA", format: ".3f" }
+            ]
+          }
+        },
+        {
+          mark: {
+            type: "text",
+            fontSize: 18,
+            fontWeight: "bold",
+            // Halo stroke keeps text legible against every cell color —
+            // light (yellow) and dark (saturated red or blue) alike.
+            stroke: "white",
+            strokeWidth: 3,
+            strokeOpacity: 0.9,
+            paintOrder: "stroke"
+          },
+          encoding: {
+            x: { field: "col", type: "ordinal" },
+            y: { field: "row", type: "ordinal" },
+            text: { field: "xwoba", type: "quantitative", format: ".3f" },
+            color: { value: "black" }
+          }
+        }
+      ],
+      config: audienceConfig(options.audience, options.colorblind)
+    };
+  }
+};
+
+// src/viz/charts/rolling.ts
+function parseNumeric(v) {
+  if (v == null) return null;
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  const s = String(v).replace(/[^\d.\-]/g, "");
+  if (!s) return null;
+  const n = parseFloat(s);
+  return Number.isFinite(n) ? n : null;
+}
+var rollingBuilder = {
+  id: "rolling",
+  dataRequirements: [
+    { queryTemplate: "trend-rolling-average", required: true }
+  ],
+  defaultTitle({ player, season }) {
+    return `${player} \u2014 Rolling Performance (${season})`;
+  },
+  buildSpec(rows, options) {
+    const wideRows = rows["trend-rolling-average"] ?? [];
+    const preferredKeys = ["Window End", "window_end", "Date", "date", "End Date"];
+    let dateKey = null;
+    if (wideRows.length > 0) {
+      const first = wideRows[0];
+      for (const k of preferredKeys) {
+        if (k in first && isParseableDate(first[k])) {
+          dateKey = k;
+          break;
+        }
+      }
+    }
+    const metricKeys = /* @__PURE__ */ new Set();
+    const excluded = new Set([dateKey, "Window", "Games"].filter(Boolean));
+    for (const r of wideRows) {
+      for (const k of Object.keys(r)) {
+        if (excluded.has(k)) continue;
+        if (parseNumeric(r[k]) != null) metricKeys.add(k);
+      }
+    }
+    const tidy = [];
+    for (const r of wideRows) {
+      const date = dateKey ? String(r[dateKey] ?? "") : "";
+      if (!date || !isParseableDate(date)) continue;
+      for (const k of metricKeys) {
+        const n = parseNumeric(r[k]);
+        if (n != null) tidy.push({ window_end: date, metric: k, value: n });
+      }
+    }
+    if (tidy.length === 0) {
+      return {
+        $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+        title: options.title,
+        width: options.width,
+        height: options.height,
+        data: { values: [{ msg: "Insufficient data for rolling trend (need 15+ games)" }] },
+        mark: { type: "text", fontSize: 14, color: "#888" },
+        encoding: { text: { field: "msg", type: "nominal" } },
+        config: audienceConfig(options.audience, options.colorblind)
+      };
+    }
+    const metricOrder = Array.from(metricKeys);
+    const panelHeight = Math.max(80, Math.floor(options.height / metricOrder.length) - 30);
+    return {
+      $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+      title: options.title,
+      data: { values: tidy },
+      facet: {
+        row: {
+          field: "metric",
+          type: "nominal",
+          title: null,
+          header: { labelAngle: 0, labelAlign: "left", labelFontWeight: "bold" },
+          sort: metricOrder
+        }
+      },
+      spec: {
+        width: options.width - 120,
+        height: panelHeight,
+        layer: [
+          {
+            mark: { type: "line", point: true, strokeWidth: 2 },
+            encoding: {
+              x: {
+                field: "window_end",
+                type: "temporal",
+                axis: { title: "Window End", format: "%b %d" }
+              },
+              y: {
+                field: "value",
+                type: "quantitative",
+                axis: { title: null },
+                scale: { zero: false }
+              },
+              color: {
+                field: "metric",
+                type: "nominal",
+                legend: null
+              },
+              tooltip: [
+                { field: "window_end", type: "temporal", format: "%Y-%m-%d" },
+                { field: "metric", title: "Metric" },
+                { field: "value", title: "Value", format: ".3f" }
+              ]
+            }
+          },
+          {
+            mark: { type: "rule", strokeDash: [4, 4], opacity: 0.4 },
+            encoding: {
+              y: { aggregate: "mean", field: "value", type: "quantitative" },
+              color: { field: "metric", type: "nominal", legend: null }
+            }
+          }
+        ]
+      },
+      resolve: { scale: { y: "independent" } },
+      config: audienceConfig(options.audience, options.colorblind)
+    };
+  }
+};
+function isParseableDate(v) {
+  if (v == null || v === "") return false;
+  const s = String(v);
+  if (!/[-/]/.test(s)) return false;
+  const t = Date.parse(s);
+  return Number.isFinite(t);
+}
+
+// src/viz/charts/index.ts
+var builders = {
+  movement: movementBuilder,
+  spray: sprayBuilder,
+  zone: zoneBuilder,
+  rolling: rollingBuilder
+};
+function getChartBuilder(type) {
+  const b = builders[type];
+  if (!b) {
+    throw new Error(
+      `Unknown chart type: "${type}". Available: ${Object.keys(builders).join(", ")}`
+    );
+  }
+  return b;
+}
+function listChartTypes() {
+  return Object.keys(builders);
+}
+
+// src/viz/render.ts
+import { parse as vegaParse, View, Warn } from "vega";
+import { compile } from "vega-lite";
+async function specToSvg(vlSpec) {
+  const { spec: vgSpec } = compile(vlSpec);
+  const runtime = vegaParse(vgSpec);
+  const view = new View(runtime, { renderer: "none" });
+  view.logLevel(Warn);
+  const svg = await view.toSVG();
+  view.finalize();
+  return ensureTextPaintOrder(svg);
+}
+function ensureTextPaintOrder(svg) {
+  return svg.replace(/<text\b([^>]*)>/g, (match, attrs) => {
+    if (/\bpaint-order\s*=/.test(attrs)) return match;
+    if (!/\bfill\s*=/.test(attrs)) return match;
+    if (!/\bstroke\s*=/.test(attrs)) return match;
+    return `<text${attrs} paint-order="stroke">`;
+  });
+}
+
+// src/viz/types.ts
+function resolveVizAudience(a) {
+  if (!a) return "analyst";
+  switch (a) {
+    case "gm":
+      return "frontoffice";
+    case "scout":
+      return "analyst";
+    case "coach":
+    case "analyst":
+    case "frontoffice":
+    case "presentation":
+      return a;
+    default:
+      return "analyst";
+  }
+}
+
+// src/commands/viz.ts
+async function viz(options) {
+  if (options.stdin) {
+    const raw = await readStdin();
+    getStdinAdapter().load(raw);
+  }
+  const config = getConfig();
+  const audience = resolveVizAudience(
+    options.audience ?? config.defaultAudience
+  );
+  const defaults = AUDIENCE_DEFAULTS[audience];
+  const builder = getChartBuilder(options.type);
+  const season = options.season ?? (/* @__PURE__ */ new Date()).getFullYear();
+  const player = options.player ?? "Unknown";
+  const width = options.width ?? defaults.width;
+  const height = options.height ?? defaults.height;
+  const rows = {};
+  let source = "unknown";
+  for (const req of builder.dataRequirements) {
+    try {
+      const result = await query({
+        template: req.queryTemplate,
+        player: options.player,
+        season,
+        format: "json",
+        ...options.stdin ? { source: "stdin" } : {},
+        ...options.source && !options.stdin ? { source: options.source } : {}
+      });
+      rows[req.queryTemplate] = result.data;
+      if (result.meta.source) source = result.meta.source;
+    } catch (err) {
+      if (req.required) throw err;
+      rows[req.queryTemplate] = [];
+    }
+  }
+  const resolved = {
+    type: options.type,
+    player,
+    season,
+    audience,
+    format: options.format ?? "svg",
+    width,
+    height,
+    colorblind: options.colorblind ?? false,
+    title: options.title ?? builder.defaultTitle({ player, season }),
+    players: options.players
+  };
+  const spec = builder.buildSpec(rows, resolved);
+  const svg = await specToSvg(spec);
+  if (options.output) {
+    writeFileSync2(resolvePath(options.output), svg, "utf-8");
+    log.success(`Wrote ${options.output}`);
+  }
+  return {
+    svg,
+    spec,
+    meta: {
+      chartType: options.type,
+      player,
+      season,
+      audience,
+      rowCount: Object.values(rows).reduce((a, r) => a + r.length, 0),
+      source,
+      width,
+      height
+    }
+  };
+}
+function registerVizCommand(program2) {
+  program2.command("viz [type]").description("Generate data visualizations (SVG)").option("--type <type>", "Chart type: movement, spray, zone, rolling").option("-p, --player <name>", "Player name").option("--players <names>", "Comma-separated player names (for comparisons)").option("-s, --season <year>", "Season year", String((/* @__PURE__ */ new Date()).getFullYear())).option(
+    "-a, --audience <role>",
+    "Audience: coach, analyst, frontoffice, presentation, gm, scout"
+  ).option("-f, --format <fmt>", "Output format (svg only in v1)", "svg").option("--size <WxH>", "Chart dimensions, e.g. 800x600").option("--colorblind", "Use a colorblind-safe palette (viridis)").option("-o, --output <path>", "Write SVG to a file (otherwise prints to stdout)").option("--source <src>", "Force a data source (savant, fangraphs, ...)").option("--stdin", "Read pre-fetched JSON data from stdin").addHelpText("after", `
+Examples:
+  bbdata viz movement --player "Corbin Burnes" --season 2025 -o burnes_movement.svg
+  bbdata viz spray    --player "Aaron Judge" --audience coach
+  bbdata viz zone     --player "Shohei Ohtani" --colorblind
+  bbdata viz rolling  --player "Freddie Freeman"
+
+Chart types:
+  movement  \u2014 pitch movement plot (H break vs V break, per pitch type)
+  spray     \u2014 spray chart (batted ball landing positions on a field)
+  zone      \u2014 3x3 zone profile heatmap (xwOBA per plate region)
+  rolling   \u2014 rolling performance trend (time-series)
+`).action(async (typeArg, opts) => {
+    const type = typeArg ?? opts.type;
+    if (!type) {
+      log.data("\nAvailable chart types:\n\n");
+      for (const t of listChartTypes()) {
+        log.data(`  ${t}
+`);
+      }
+      log.data('\nUsage: bbdata viz <type> --player "Name" [options]\n\n');
+      return;
+    }
+    let width;
+    let height;
+    if (opts.size) {
+      const [w, h] = String(opts.size).split("x").map((n) => parseInt(n, 10));
+      if (w && h) {
+        width = w;
+        height = h;
+      }
+    }
+    try {
+      const result = await viz({
+        type,
+        player: opts.player,
+        players: opts.players ? String(opts.players).split(",").map((s) => s.trim()) : void 0,
+        season: opts.season ? parseInt(opts.season) : void 0,
+        audience: opts.audience,
+        format: opts.format,
+        width,
+        height,
+        colorblind: opts.colorblind,
+        output: opts.output,
+        source: opts.source,
+        stdin: opts.stdin
+      });
+      if (!opts.output) log.data(result.svg + "\n");
+    } catch (error) {
+      log.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/viz/embed.ts
+var REPORT_GRAPH_MAP = {
+  "advance-sp": [
+    { slot: "movementChart", type: "movement" }
+  ],
+  "pro-pitcher-eval": [
+    { slot: "movementChart", type: "movement" },
+    { slot: "rollingChart", type: "rolling" }
+  ],
+  "pro-hitter-eval": [
+    { slot: "sprayChart", type: "spray" },
+    { slot: "zoneChart", type: "zone" }
+  ]
+};
+async function generateReportGraphs(reportId, player, season, audience, opts = {}) {
+  const slots = REPORT_GRAPH_MAP[reportId] ?? [];
+  const out = {};
+  for (const { slot, type } of slots) {
+    try {
+      const r = await viz({
+        type,
+        player,
+        season,
+        audience,
+        ...opts.stdin ? { source: "stdin" } : {}
+      });
+      out[slot] = r.svg;
+    } catch {
+      out[slot] = "";
+    }
+  }
+  return out;
+}
+
 // src/templates/reports/registry.ts
 var templates2 = /* @__PURE__ */ new Map();
-function registerReportTemplate(template13) {
-  templates2.set(template13.id, template13);
+function registerReportTemplate(template16) {
+  templates2.set(template16.id, template16);
 }
 function getReportTemplate(id) {
   return templates2.get(id);
@@ -1777,6 +2765,10 @@ Handlebars.registerHelper("compare", (value, leagueAvg) => {
 Handlebars.registerHelper("ifGt", function(a, b, options) {
   return a > b ? options.fn(this) : options.inverse(this);
 });
+Handlebars.registerHelper(
+  "svgOrEmpty",
+  (svg) => new Handlebars.SafeString(svg ?? "")
+);
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
 var BUNDLED_TEMPLATES_DIR = join2(__dirname2, "..", "templates", "reports");
 function loadTemplate(templateFile) {
@@ -1793,14 +2785,14 @@ function loadTemplate(templateFile) {
 }
 function generateFallbackTemplate(templateFile) {
   const templateId = templateFile.replace(".hbs", "");
-  const template13 = getReportTemplate(templateId);
-  if (!template13) return "# Report\n\n{{data}}";
-  const sections = template13.requiredSections.map((s) => `## ${s}
+  const template16 = getReportTemplate(templateId);
+  if (!template16) return "# Report\n\n{{data}}";
+  const sections = template16.requiredSections.map((s) => `## ${s}
 
 {{!-- ${s} data goes here --}}
 *Data pending*
 `).join("\n");
-  return `# ${template13.name}
+  return `# ${template16.name}
 
 **Player:** {{player}}
 **Season:** {{season}}
@@ -1816,10 +2808,15 @@ ${sections}
 `;
 }
 async function report(options) {
+  if (options.stdin) {
+    const raw = await readStdin();
+    const adapter = getStdinAdapter();
+    adapter.load(raw);
+  }
   const config = getConfig();
   const audience = options.audience ?? config.defaultAudience;
-  const template13 = getReportTemplate(options.template);
-  if (!template13) {
+  const template16 = getReportTemplate(options.template);
+  if (!template16) {
     const available = listReportTemplates().map((t) => `  ${t.id} \u2014 ${t.description}`).join("\n");
     throw new Error(`Unknown report template "${options.template}". Available:
 ${available}`);
@@ -1828,14 +2825,15 @@ ${available}`);
   const player = options.player ?? "Unknown";
   const dataResults = {};
   const dataSources = [];
-  for (const req of template13.dataRequirements) {
+  for (const req of template16.dataRequirements) {
     try {
       const result = await query({
         template: req.queryTemplate,
         player: options.player,
         team: options.team,
         season,
-        format: "json"
+        format: "json",
+        ...options.stdin ? { source: "stdin" } : {}
       });
       dataResults[req.queryTemplate] = result.data;
       if (!dataSources.includes(result.meta.source)) {
@@ -1848,7 +2846,14 @@ ${available}`);
       dataResults[req.queryTemplate] = null;
     }
   }
-  const hbsSource = loadTemplate(template13.templateFile);
+  const graphs = await generateReportGraphs(
+    template16.id,
+    player,
+    season,
+    audience,
+    { stdin: options.stdin }
+  );
+  const hbsSource = loadTemplate(template16.templateFile);
   const compiled = Handlebars.compile(hbsSource);
   const content = compiled({
     player,
@@ -1857,19 +2862,20 @@ ${available}`);
     date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
     sources: dataSources.join(", ") || "none",
     data: dataResults,
+    graphs,
     ...dataResults
   });
   let validation;
   if (options.validate) {
-    validation = validateReport(content, template13.requiredSections);
+    validation = validateReport(content, template16.requiredSections);
   }
-  const formatted = options.format === "json" ? JSON.stringify({ content, validation, meta: { template: template13.id, player, audience, season, dataSources } }, null, 2) + "\n" : content + "\n";
+  const formatted = options.format === "json" ? JSON.stringify({ content, validation, meta: { template: template16.id, player, audience, season, dataSources } }, null, 2) + "\n" : content + "\n";
   return {
     content,
     formatted,
     validation,
     meta: {
-      template: template13.id,
+      template: template16.id,
       player,
       audience,
       season,
@@ -1902,7 +2908,7 @@ function validateReport(content, requiredSections) {
   };
 }
 function registerReportCommand(program2) {
-  program2.command("report [template]").description("Generate scouting reports using pre-built templates").option("-p, --player <name>", "Player name").option("-t, --team <code>", "Team abbreviation").option("-s, --season <year>", "Season year", String((/* @__PURE__ */ new Date()).getFullYear())).option("-a, --audience <role>", "Target audience: coach, gm, scout, analyst").option("-f, --format <fmt>", "Output: markdown, json", "markdown").option("--validate", "Run validation checklist on the report").addHelpText("after", `
+  program2.command("report [template]").description("Generate scouting reports using pre-built templates").option("-p, --player <name>", "Player name").option("-t, --team <code>", "Team abbreviation").option("-s, --season <year>", "Season year", String((/* @__PURE__ */ new Date()).getFullYear())).option("-a, --audience <role>", "Target audience: coach, gm, scout, analyst").option("-f, --format <fmt>", "Output: markdown, json", "markdown").option("--validate", "Run validation checklist on the report").option("--stdin", "Read pre-fetched JSON data from stdin instead of fetching from APIs").addHelpText("after", `
 Examples:
   bbdata report pro-pitcher-eval --player "Corbin Burnes"
   bbdata report advance-sp --player "Gerrit Cole" --audience coach --validate
@@ -1933,7 +2939,8 @@ Available templates:
         season: opts.season ? parseInt(opts.season) : void 0,
         audience: opts.audience,
         format: opts.format,
-        validate: opts.validate
+        validate: opts.validate,
+        stdin: opts.stdin
       });
       log.data(result.formatted);
       if (result.validation && !result.validation.passed) {
@@ -1955,6 +2962,7 @@ var program = new Command();
 program.name("bbdata").description("Baseball data CLI \u2014 query stats, generate scouting reports, and build analytics pipelines").version("0.1.0");
 registerQueryCommand(program);
 registerReportCommand(program);
+registerVizCommand(program);
 
 // bin/bbdata.ts
 program.parse(process.argv);