@pitchkit/react 0.2.0 → 0.3.0

package/README.md

@@ -139,6 +139,28 @@ the `<Pitch>` tree must originate inside a `"use client"` component — React Se
 can't pass functions across the client boundary. SSR still happens; only the prop-serialisation
 boundary moves. `<Heatmap>` is Canvas-backed and therefore client-only.
 
+## Agent Skill
+
+No model has PitchKit in its training data, so coding agents asked for a shot map tend to
+invent an mplsoccer-flavoured API. This package ships an Agent Skill — `skills/pitchkit/`
+inside the tarball — that documents the real one.
+
+```bash
+npx @pitchkit/react skills install          # -> .claude/skills/pitchkit/
+npx @pitchkit/react skills install --dir .cursor/skills
+npx @pitchkit/react skills path             # where it lives in node_modules
+```
+
+Install *symlinks* the target at the copy inside `node_modules`, so `npm update
+@pitchkit/react` moves the skill with it and an agent can't end up reading last version's
+API. On a filesystem that won't take a symlink it copies instead and says so — that copy is
+a snapshot, so re-run with `--force` after upgrading.
+
+The default directory suits Claude Code; for any other agent, point `--dir` at wherever it
+reads skills from, or hand it the `skills path` output to read directly. The layout follows
+the `skills/<name>/SKILL.md` convention, so generic installers like `skills-npm` find it in
+`node_modules` without needing this CLI at all.
+
 ## Links
 
 - [Documentation & gallery](https://pitchkitjs.com)

package/bin/install-skill.mjs

@@ -0,0 +1,223 @@
+// The `npx @pitchkit/react skills install` implementation, kept separate from
+// bin/pitchkit.mjs so it can be unit-tested without spawning a process or
+// doing the "am I the main module?" dance (which npx's bin symlinks make
+// unreliable). Zero dependencies on purpose: this runs in a consumer's
+// project, via npx, before anything of ours is necessarily installed.
+import { cp, lstat, mkdir, readdir, rm, symlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_NAME = "pitchkit";
+
+/**
+ * Claude Code's project-scoped skills directory. Chosen as the default
+ * because it's the one convention with a settled on-disk layout; every
+ * other agent gets pointed at `--dir` in the help text rather than us
+ * guessing at a location it may not read.
+ */
+export const DEFAULT_SKILLS_DIR = join(".claude", "skills");
+
+/** `bin/` -> the package root, so this resolves inside a consumer's node_modules too. */
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export const skillSourceDir = join(packageRoot, "skills", SKILL_NAME);
+
+export class CliError extends Error {}
+
+export function formatHelp() {
+  return `pitchkit — ships the PitchKit Agent Skill with the package you installed
+
+Usage
+  npx @pitchkit/react skills install [options]   Link the skill into your project
+  npx @pitchkit/react skills path                Print the skill's location in node_modules
+  npx @pitchkit/react --help
+
+Options
+  --dir <path>   Skills directory to install into (default: ${DEFAULT_SKILLS_DIR})
+  --force        Replace an existing installation
+  -h, --help     Show this message
+
+<dir>/${SKILL_NAME}/ is symlinked to the copy inside node_modules, so the skill stays in
+step with the installed version; it falls back to a plain copy on filesystems that
+won't take a link. The default directory suits Claude Code; for another agent, point
+--dir at wherever it reads skills from, or use \`skills path\` and read SKILL.md
+directly.`;
+}
+
+export function parseArgs(argv) {
+  const options = { command: null, dir: DEFAULT_SKILLS_DIR, force: false, help: false };
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "--force" || arg === "-f") {
+      options.force = true;
+    } else if (arg === "--dir") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("-")) {
+        throw new CliError("--dir needs a path, e.g. --dir .claude/skills");
+      }
+      options.dir = value;
+      i += 1;
+    } else if (arg.startsWith("--dir=")) {
+      const value = arg.slice("--dir=".length);
+      if (value === "") throw new CliError("--dir needs a path, e.g. --dir .claude/skills");
+      options.dir = value;
+    } else if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  // `skills install` and a bare `install` both work — the former is what the
+  // docs show, the latter is what people type.
+  const words = positional[0] === "skills" ? positional.slice(1) : positional;
+  options.command = words[0] ?? null;
+
+  if (words.length > 1) {
+    throw new CliError(`Unexpected argument: ${words[1]}`);
+  }
+
+  return options;
+}
+
+/**
+ * `lstat`, not `access`, so a dangling symlink left by an uninstalled
+ * dependency still counts as present and gets cleaned up by `--force`
+ * rather than colliding with EEXIST.
+ */
+async function entryExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Links the destination at the skill inside node_modules, so `npm update
+ * @pitchkit/react` carries the skill with it — the property that makes a
+ * bundled skill worth more than scraped docs, and the one a plain copy
+ * silently loses. Falls back to copying where the filesystem won't take a
+ * link (Windows without Developer Mode, some network and container mounts).
+ *
+ * Returns "link" or "copy" so the caller can tell the user which they got;
+ * the update semantics differ, so this isn't an implementation detail.
+ */
+async function linkOrCopy(destination) {
+  try {
+    if (process.platform === "win32") {
+      // Junctions need an absolute target, but unlike real symlinks they
+      // don't need elevation or Developer Mode.
+      await symlink(skillSourceDir, destination, "junction");
+    } else {
+      // Relative, so the link survives the project being moved or checked
+      // out at a different path with node_modules already in place.
+      await symlink(relative(dirname(destination), skillSourceDir), destination, "dir");
+    }
+    return "link";
+  } catch {
+    await cp(skillSourceDir, destination, { recursive: true, force: true });
+    return "copy";
+  }
+}
+
+/**
+ * Installs `skills/pitchkit/` from the installed package into the consumer's
+ * project. Returns the destination, how it was installed, and what's now
+ * readable there.
+ */
+export async function installSkill({
+  cwd = process.cwd(),
+  dir = DEFAULT_SKILLS_DIR,
+  force = false,
+} = {}) {
+  if (!(await entryExists(skillSourceDir))) {
+    throw new CliError(
+      `Could not find the bundled skill at ${skillSourceDir}. ` +
+        "Is @pitchkit/react installed, and new enough to ship one?",
+    );
+  }
+
+  const skillsDir = isAbsolute(dir) ? dir : resolve(cwd, dir);
+  const destination = join(skillsDir, SKILL_NAME);
+
+  if (await entryExists(destination)) {
+    if (!force) {
+      throw new CliError(
+        `${relative(cwd, destination) || destination} already exists. Re-run with --force to replace it.`,
+      );
+    }
+    // `rm` unlinks a symlink rather than following it, so this can't reach
+    // through an existing link and delete the copy inside node_modules.
+    await rm(destination, { recursive: true, force: true });
+  }
+
+  await mkdir(skillsDir, { recursive: true });
+  const method = await linkOrCopy(destination);
+
+  // Plain codepoint sort, so SKILL.md leads and the references/ paths follow.
+  return { destination, method, files: (await listFiles(destination)).sort() };
+}
+
+async function listFiles(dir, prefix = "") {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(join(dir, entry.name), name)));
+    } else {
+      files.push(name);
+    }
+  }
+  return files;
+}
+
+export async function run(argv, { cwd = process.cwd(), log = console.log } = {}) {
+  const options = parseArgs(argv);
+
+  if (options.help || options.command === null || options.command === "help") {
+    log(formatHelp());
+    return 0;
+  }
+
+  if (options.command === "path") {
+    log(skillSourceDir);
+    return 0;
+  }
+
+  if (options.command !== "install") {
+    throw new CliError(`Unknown command: ${options.command}\n\n${formatHelp()}`);
+  }
+
+  const { destination, method, files } = await installSkill({
+    cwd,
+    dir: options.dir,
+    force: options.force,
+  });
+  const shown = relative(cwd, destination) || destination;
+
+  if (method === "link") {
+    log(`Linked the PitchKit skill at ${shown}`);
+  } else {
+    log(`Copied the PitchKit skill to ${shown}`);
+  }
+  for (const file of files) log(`  ${shown}/${file}`);
+  log("");
+
+  if (method === "link") {
+    log("It points into node_modules, so `npm update @pitchkit/react` updates the");
+    log("skill too. Add it to .gitignore unless you want the link committed.");
+  } else {
+    log("This filesystem wouldn't take a symlink, so the skill was copied instead —");
+    log("it's a snapshot. Re-run with --force after upgrading @pitchkit/react.");
+  }
+  log("Start a new agent session so it picks the skill up.");
+
+  return 0;
+}

package/bin/pitchkit.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// The package's only bin, so `npx @pitchkit/react skills install` resolves to
+// it despite the bin name not matching the (scoped) package name.
+import { CliError, run } from "./install-skill.mjs";
+
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof CliError) {
+    console.error(error.message);
+    process.exitCode = 1;
+  } else {
+    throw error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitchkit/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Thin React bindings for @pitchkit/core: declarative <Pitch> + layer components, responsive by default.",
   "license": "MIT",
   "author": "Yohahn Ribeiro",
@@ -35,8 +35,13 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "pitchkit": "./bin/pitchkit.mjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "skills"
   ],
   "scripts": {
     "build": "tsup && node scripts/add-use-client.mjs",

package/skills/pitchkit/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: pitchkit
+description: Builds football (soccer) pitch visualisations for the web with PitchKit, the @pitchkit/react and @pitchkit/core packages. Use when the request involves a shot map, pass map, pass network, pass flow, touch map, heatmap, hexbin, KDE surface, Voronoi, convex hull, or any other chart drawn on a football pitch in React or Next.js; when the user names PitchKit, @pitchkit/react, @pitchkit/core or the Pitch component; when they mention StatsBomb, Opta or UEFA pitch coordinates; or when they ask for mplsoccer's behaviour on the web.
+license: MIT
+---
+
+# PitchKit
+
+PitchKit draws football pitches and the marks on them. It is mplsoccer's feature set
+rebuilt for React, not a port of matplotlib.
+
+This skill ships inside the installed `@pitchkit/react` tarball, so it describes the
+exact version in the consuming project's `node_modules`. Check
+`node_modules/@pitchkit/react/package.json` for that version before assuming any API
+described here is present. Full docs: <https://pitchkitjs.com>.
+
+## Never guess the API
+
+There is no PitchKit in any model's training data. Anything recalled about it is
+invented — usually mplsoccer's Python API in JSX clothing. Every component, prop and
+export a PitchKit answer uses must come from this file, from
+[references/api.md](references/api.md), or from the package's own `.d.ts`. If something
+needed is not in those, say so rather than inventing it.
+
+Things that do **not** exist, however plausible: a `<PassMap>` / `<ShotMap>` /
+`<PassNetwork>` component, a `theme` prop or JS theme object, a `type="wyscout"` (or
+`"tracab"`, `"skillcorner"`, `"custom"`) pitch, a `responsive` prop, a `<Pitch>`
+`onClick` handler that hands back pitch coordinates.
+
+## Package split
+
+| Package           | What it is                                                             | When it's imported from                                                                 |
+| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `@pitchkit/react` | The rendering surface: `<Pitch>` + layer components + `usePitch()`     | Almost always                                                                           |
+| `@pitchkit/core`  | Zero-dependency maths: pitch dimensions, transforms, geometry, binning | Only for helpers like `cropForHalf`, `getPitchDimensions`, `createStandardizeTransform` |
+
+`@pitchkit/react` is the **only supported rendering surface**. `@pitchkit/core` exports
+`svgRenderer` / `renderSceneToSVGElement`; those are internal building blocks for the
+repo's own dev harness and must never appear in consumer code.
+
+```bash
+npm install @pitchkit/react
+# add @pitchkit/core explicitly only when importing its helpers directly:
+npm install @pitchkit/react @pitchkit/core
+```
+
+`@pitchkit/core` arrives transitively as a dependency of `@pitchkit/react`, but importing
+from it without declaring it is a phantom dependency — declare it when it's imported.
+
+## The five rules
+
+1. **Data goes in in its provider's own units.** Never pre-scale coordinates. Set `type`
+   on `<Pitch>` and pass raw StatsBomb / Opta / UEFA numbers straight through.
+2. **Every visual prop is an accessor:** a constant (`r={5}`) or a function of the datum
+   (`r={(s) => 3 + s.xg * 9}`). Same prop name for both forms.
+3. **Layer components must be descendants of `<Pitch>`.** They read the pixel transform
+   from context and throw if rendered outside one.
+4. **Responsive is the default.** A `<Pitch>` fills its container and keeps the pitch
+   aspect ratio, so sizing a pitch means sizing its parent. Passing `width` _and_
+   `height` is the opt-out — pass both or neither.
+5. **Theming is CSS variables only.** There is no theme object and no colour props on
+   `<Pitch>`.
+
+## Pitch types
+
+| `type`        | Extent    | Origin      | y direction | Notes                      |
+| ------------- | --------- | ----------- | ----------- | -------------------------- |
+| `"statsbomb"` | 120 × 80  | top-left    | down        | Abstract units             |
+| `"opta"`      | 100 × 100 | bottom-left | up          | Normalised percentage grid |
+| `"uefa"`      | 105 × 68  | bottom-left | up          | Real metres                |
+
+Those three are the whole list. For a provider that isn't one of them, standardise the
+data first and render in the target grid:
+
+```tsx
+import { createStandardizeTransform, getPitchDimensions } from "@pitchkit/core";
+
+const optaToStatsBomb = createStandardizeTransform(
+  getPitchDimensions("opta"),
+  getPitchDimensions("statsbomb"),
+);
+const [x, y] = optaToStatsBomb([50, 50]); // -> [60, 40]
+```
+
+## Components
+
+SVG layers — server-renderable, one element per datum, all accept `className` and a
+`tooltip` accessor:
+
+`<Scatter>` `<Annotate>` `<Arrows>` `<Comet>` `<Polygon>` `<ConvexHull>` `<Voronoi>`
+`<GoalAngle>` `<Flow>`
+
+Canvas density layers — client-only, accept `className` and `style` but **no** `tooltip`:
+
+`<Heatmap>` `<PositionalHeatmap>` `<Hexbin>` `<KDE>`
+
+Roots: `<Pitch>`, and `<VerticalPitch>` (exactly `<Pitch orientation="vertical">`).
+Escape hatch: `usePitch()` returns `{ dimensions, viewport, transform }` for custom marks.
+
+Full prop tables for every component are in [references/api.md](references/api.md) — read
+it before writing props not shown in the recipes below.
+
+## Composite charts are compositions, not components
+
+A shot map is `<VerticalPitch>` + a crop + `<Scatter>`. A pass network is `<Arrows>` +
+`<Scatter>` + `<Annotate>` over data the caller aggregated. PitchKit ships primitives; the
+aggregation is ordinary JavaScript. Build these from the recipes below.
+
+(The project intends to distribute such compositions as shadcn registry items later. That
+registry does not exist yet — do not tell a user to run `npx shadcn add pass-map`.)
+
+## Gotchas that break builds
+
+**Next.js App Router: originate the tree in a `"use client"` component.** Accessors are
+functions, and React Server Components cannot pass functions to client components. A
+`<Pitch>` tree written directly in a server page fails `next build` with _"Functions
+cannot be passed directly to Client Components"_. Compose it in a `"use client"` component
+and render that from the page — it is still fully server-rendered into the initial HTML.
+
+**Density layers need a fixed-pixel pitch.** `<Heatmap>` / `<PositionalHeatmap>` /
+`<Hexbin>` / `<KDE>` paint to a `<canvas>`, which needs real pixel dimensions and cannot
+use the SVG's responsive viewBox. Give `<Pitch>` explicit `width` and `height` — measure
+the container with a `ResizeObserver` to stay responsive (recipe 3 below).
+
+**Density layers hide the pitch markings.** They fill opaquely from `colorMin` to
+`colorMax`, including empty bins. Pass `appearance={{ linesOnTop: true }}` so the markings
+paint above them (mplsoccer's `line_zorder`), and/or drop the layer's opacity via `style`.
+
+**`className` turns the themed colour default off.** Colour defaults are applied as inline
+styles, which would otherwise beat a utility class at the same property. So passing
+`className` to an SVG layer means it owns `fill` / `stroke` — either style them there, or
+pass `fill` / `stroke` explicitly.
+
+**Canvas layers render nothing on the server.** That is by design; they paint after
+hydration. The pitch and the SVG layers around them still SSR.
+
+## Theming
+
+Set CSS custom properties anywhere in the cascade — globally, on `.dark`, or on a wrapper
+around a single chart. Every variable has a built-in fallback, so none is required.
+
+| Variable                 | Controls                        | Default                     |
+| ------------------------ | ------------------------------- | --------------------------- |
+| `--pitch-surface`        | Grass fill                      | `#1a472a`                   |
+| `--pitch-stripe`         | Mow-stripe overlay              | `rgba(255, 255, 255, 0.04)` |
+| `--pitch-lines`          | Markings, and `<Annotate>` text | `rgba(255, 255, 255, 0.8)`  |
+| `--pitch-line-width`     | Marking stroke width            | `1.5`                       |
+| `--pitch-marker-primary` | Default mark colour             | `#3b82f6`                   |
+| `--pitch-tooltip-bg`     | Tooltip background              | `rgba(17, 17, 17, 0.92)`    |
+| `--pitch-tooltip-color`  | Tooltip text                    | `#fff`                      |
+
+`@pitchkit/core` exports `pitchTokens` as a typo-safe map of those names; the values
+always live in CSS.
+
+`appearance` is structure, never colour: `{ stripes, goalType, linesOnTop }`.
+
+```tsx
+<div style={{ "--pitch-surface": "#101418" } as React.CSSProperties}>
+  <Pitch type="statsbomb" appearance={{ stripes: true, goalType: "box" }} />
+</div>
+```
+
+## Recipe 1 — shot map
+
+Attacking half, vertical framing, markers sized by xG and coloured by outcome.
+
+```tsx
+"use client";
+
+import { cropForHalf, getPitchDimensions } from "@pitchkit/core";
+import { Scatter, VerticalPitch } from "@pitchkit/react";
+
+// StatsBomb coordinates: 120 x 80, origin top-left, y increasing downward.
+const shots = [
+  { x: 112, y: 39, xg: 0.76, outcome: "goal" },
+  { x: 105, y: 44, xg: 0.31, outcome: "saved" },
+  { x: 99, y: 47, xg: 0.13, outcome: "off target" },
+  { x: 91, y: 29, xg: 0.06, outcome: "off target" },
+];
+
+const dimensions = getPitchDimensions("statsbomb");
+
+export function ShotMap() {
+  return (
+    <VerticalPitch type="statsbomb" crop={cropForHalf(dimensions)}>
+      <Scatter
+        data={shots}
+        x={(s) => s.x}
+        y={(s) => s.y}
+        r={(s) => 3 + s.xg * 9}
+        fill={(s) => (s.outcome === "goal" ? "#fb923c" : "#38bdf8")}
+        fillOpacity={(s) => (s.outcome === "goal" ? 0.95 : 0.65)}
+        stroke="white"
+        strokeWidth={(s) => (s.outcome === "goal" ? 2 : 1)}
+        tooltip={(s) => `${s.outcome} · xG ${s.xg.toFixed(2)}`}
+      />
+    </VerticalPitch>
+  );
+}
+```
+
+`crop` takes any `{ x0, y0, x1, y1 }` window in provider units; `cropForHalf` is the
+convenience for the attacking half. The container's aspect ratio follows the crop, so a
+half-pitch crop reserves space for half a pitch.
+
+## Recipe 2 — pass map
+
+Individual passes, tapered from origin to destination and coloured by completion.
+
+```tsx
+"use client";
+
+import { Comet, Pitch } from "@pitchkit/react";
+
+const passes = [
+  { x: 22, y: 30, x2: 48, y2: 18, completed: true },
+  { x: 48, y: 18, x2: 71, y2: 26, completed: true },
+  { x: 71, y: 26, x2: 96, y2: 40, completed: false },
+  { x: 35, y: 55, x2: 62, y2: 62, completed: true },
+];
+
+export function PassMap() {
+  return (
+    <Pitch type="statsbomb">
+      <Comet
+        data={passes}
+        x={(p) => p.x}
+        y={(p) => p.y}
+        x2={(p) => p.x2}
+        y2={(p) => p.y2}
+        color={(p) => (p.completed ? "#38bdf8" : "#f87171")}
+        startWidth={0.5}
+        endWidth={4}
+        gradient
+        tooltip={(p) => (p.completed ? "Completed" : "Incomplete")}
+      />
+    </Pitch>
+  );
+}
+```
+
+Swap `<Comet>` for `<Arrows>` when a flat line with an arrowhead reads better; `<Arrows>`
+takes `strokeWidth` / `strokeOpacity` / `headSize` instead of the taper widths. For passes
+aggregated by starting zone into one arrow per zone (mplsoccer's `flow`), use `<Flow>` with
+`binsX` / `binsY` — its `tooltip` receives a `FlowBin` (`{ x, y, x2, y2, count }`), not a
+raw datum.
+
+## Recipe 3 — heatmap (the responsive-canvas pattern)
+
+This is the pattern for **all four** density layers. Copy it whenever one is used.
+
+```tsx
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { Heatmap, Pitch } from "@pitchkit/react";
+
+const events = [
+  { x: 52, y: 22 },
+  { x: 55, y: 18 },
+  { x: 61, y: 20 },
+  { x: 66, y: 23 },
+  { x: 74, y: 22 },
+  { x: 59, y: 43 },
+  { x: 47, y: 52 },
+  { x: 82, y: 24 },
+];
+
+const PITCH_ASPECT = 120 / 80; // statsbomb length / width
+
+export function PressureHeatmap() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [width, setWidth] = useState(480);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) setWidth(entry.contentRect.width);
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div ref={containerRef}>
+      <Pitch
+        type="statsbomb"
+        width={width}
+        height={Math.round(width / PITCH_ASPECT)}
+        appearance={{ linesOnTop: true }}
+      >
+        <Heatmap
+          data={events}
+          x={(e) => e.x}
+          y={(e) => e.y}
+          binsX={12}
+          binsY={8}
+          colorMin="#0f3d24"
+          colorMax="#38bdf8"
+          style={{ opacity: 0.85 }}
+        />
+      </Pitch>
+    </div>
+  );
+}
+```
+
+Same shape for the variants: `<PositionalHeatmap layout="full" />` for Juego de Posición
+zones, `<Hexbin binsX={14} />` for a hex lattice, `<KDE resolution={64} maxOpacity={0.8} />`
+for a smooth surface. Every one of them takes an optional `weight` accessor — omit it to
+count points per bin, provide it to sum a value (total xG per zone, say).
+
+## Recipe 4 — pass network
+
+Node size = touches, edge width = passes between the pair. The aggregation is plain data
+prep; the pitch just draws the result.
+
+```tsx
+"use client";
+
+import { Annotate, Arrows, Pitch, Scatter } from "@pitchkit/react";
+
+const players = [
+  { id: "GK", x: 10, y: 40, touches: 42 },
+  { id: "LCB", x: 26, y: 30, touches: 71 },
+  { id: "RCB", x: 26, y: 50, touches: 66 },
+  { id: "DM", x: 44, y: 40, touches: 88 },
+  { id: "ST", x: 92, y: 40, touches: 38 },
+];
+
+const byId = Object.fromEntries(players.map((p) => [p.id, p]));
+const node = (id: string) => {
+  const player = byId[id];
+  if (!player) throw new Error(`Unknown player id: ${id}`);
+  return player;
+};
+
+const passes = [
+  { from: "GK", to: "LCB", count: 18 },
+  { from: "GK", to: "RCB", count: 15 },
+  { from: "LCB", to: "DM", count: 24 },
+  { from: "DM", to: "ST", count: 9 },
+];
+
+export function PassNetwork() {
+  return (
+    <Pitch type="statsbomb">
+      <Arrows
+        data={passes}
+        x={(p) => node(p.from).x}
+        y={(p) => node(p.from).y}
+        x2={(p) => node(p.to).x}
+        y2={(p) => node(p.to).y}
+        strokeWidth={(p) => 0.5 + p.count / 6}
+        strokeOpacity={(p) => 0.3 + Math.min(p.count / 30, 0.6)}
+        headSize={0}
+        tooltip={(p) => `${p.from} → ${p.to}: ${p.count} passes`}
+      />
+      <Scatter
+        data={players}
+        x={(p) => p.x}
+        y={(p) => p.y}
+        r={(p) => 4 + p.touches / 12}
+        stroke="white"
+        strokeWidth={1.5}
+        tooltip={(p) => `${p.id} · ${p.touches} touches`}
+      />
+      <Annotate data={players} x={(p) => p.x} y={(p) => p.y} label={(p) => p.id} offsetY={-14} />
+    </Pitch>
+  );
+}
+```
+
+Layer order is paint order: arrows first, then nodes, then labels on top.
+
+## Where to look next
+
+- [references/api.md](references/api.md) — every component's full prop list, plus the
+  `@pitchkit/core` exports worth calling directly.
+- <https://pitchkitjs.com/docs> — narrative guides.
+- <https://pitchkitjs.com/gallery> — worked examples with source.
+- The installed package's `dist/index.d.ts` — the authoritative types.

package/skills/pitchkit/references/api.md

@@ -0,0 +1,235 @@
+# PitchKit API reference
+
+Everything `@pitchkit/react` and `@pitchkit/core` export, at the version of
+`@pitchkit/react` this file shipped inside. `dist/index.d.ts` in the installed package is
+the authoritative source if the two ever disagree.
+
+Throughout: **`Accessor<T, V>`** means `V | ((datum: T, index: number) => V)` — pass a
+constant or a function of the datum. Props marked _(accessor)_ take either form; props
+without the marker are plain static values.
+
+---
+
+## Roots
+
+### `<Pitch>`
+
+| Prop          | Type                              | Default        | Notes                                                          |
+| ------------- | --------------------------------- | -------------- | -------------------------------------------------------------- |
+| `type`        | `"statsbomb" \| "opta" \| "uefa"` | —              | Required. The provider coordinate system.                      |
+| `orientation` | `"horizontal" \| "vertical"`      | `"horizontal"` | Display concern only; never changes the data's units.          |
+| `width`       | `number`                          | —              | Fixed pixel width. Pass with `height` or not at all.           |
+| `height`      | `number`                          | —              | Fixed pixel height.                                            |
+| `crop`        | `{ x0, y0, x1, y1 }`              | —              | Window in provider units. Drives the container's aspect ratio. |
+| `padding`     | `{ top, right, bottom, left }`    | zero           | Pixel padding inside the viewport.                             |
+| `appearance`  | `PitchAppearance`                 | —              | `{ stripes?, goalType?, linesOnTop? }` — see below.            |
+| `className`   | `string`                          | —              | On the wrapper `<div>`, not the `<svg>`.                       |
+| `style`       | `CSSProperties`                   | —              | Merged into the wrapper's own positioning styles.              |
+| `children`    | `ReactNode`                       | —              | Layer components.                                              |
+
+`PitchAppearance`:
+
+| Field        | Type                | Default  | Meaning                                                                                  |
+| ------------ | ------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `stripes`    | `boolean \| number` | `false`  | Mow stripes; a number sets the count, `true` picks a default.                            |
+| `goalType`   | `"line" \| "box"`   | `"line"` | How goals are drawn.                                                                     |
+| `linesOnTop` | `boolean`           | `false`  | Paint markings above the layers (mplsoccer's `line_zorder`). Turn on for density layers. |
+
+Omitting `width`/`height` makes the pitch fill its container via `ResizeObserver`. Before
+the first measurement (server render included) it renders at a nominal size with the
+correct aspect ratio, so SSR output is never distorted.
+
+### `<VerticalPitch>`
+
+`Omit<PitchProps, "orientation">`. Identical to `<Pitch orientation="vertical">`; named to
+match mplsoccer.
+
+### `usePitch()`
+
+Returns `{ dimensions, viewport, transform }` from the enclosing `<Pitch>`. Throws if
+called outside one.
+
+- `dimensions: PitchDimensions` — `{ pitchType, length, width, origin, yDirection, normalized, realLengthMeters, realWidthMeters, markings }`
+- `viewport: Viewport` — `{ width, height, orientation, crop?, padding? }` in pixels
+- `transform: PixelTransform` — `toPixel([x, y])`, `toProvider([px, py])`, `scale`
+
+`toProvider` is the inverse needed to turn a pointer position back into pitch
+coordinates.
+
+---
+
+## SVG layers
+
+Every one of these accepts `className?: string` and `tooltip`, and must be a descendant of
+`<Pitch>`. `tooltip` is `(d: T, i: number) => ReactNode` unless noted. Layer order in JSX
+is paint order.
+
+### `<Scatter>` — one `<circle>` per datum
+
+| Prop          | Type                  | Default                                |
+| ------------- | --------------------- | -------------------------------------- |
+| `data`        | `readonly T[]`        | —                                      |
+| `x`, `y`      | _(accessor)_ `number` | —                                      |
+| `r`           | _(accessor)_ `number` | `4`                                    |
+| `fill`        | _(accessor)_ `string` | `var(--pitch-marker-primary, #3b82f6)` |
+| `fillOpacity` | _(accessor)_ `number` | —                                      |
+| `stroke`      | _(accessor)_ `string` | `"none"`                               |
+| `strokeWidth` | _(accessor)_ `number` | —                                      |
+
+### `<Annotate>` — one `<text>` per datum
+
+| Prop                 | Type                  | Default |
+| -------------------- | --------------------- | ------- |
+| `data`               | `readonly T[]`        | —       |
+| `x`, `y`             | _(accessor)_ `number` | —       |
+| `label`              | _(accessor)_ `string` | —       |
+| `offsetX`, `offsetY` | _(accessor)_ `number` | `0`     |
+
+Offsets are in pixels, applied after the coordinate transform. Text is 10px,
+middle-anchored, filled with `var(--pitch-lines, …)`.
+
+### `<Arrows>` — one `<line>` + arrowhead `<polygon>` per datum
+
+| Prop            | Type                  | Default                                |
+| --------------- | --------------------- | -------------------------------------- |
+| `data`          | `readonly T[]`        | —                                      |
+| `x`, `y`        | _(accessor)_ `number` | — start point                          |
+| `x2`, `y2`      | _(accessor)_ `number` | — end point                            |
+| `stroke`        | _(accessor)_ `string` | `var(--pitch-marker-primary, #3b82f6)` |
+| `strokeWidth`   | _(accessor)_ `number` | `1.5`                                  |
+| `strokeOpacity` | _(accessor)_ `number` | —                                      |
+| `headSize`      | _(accessor)_ `number` | `6`                                    |
+
+`headSize={0}` gives a plain line — the usual choice for pass-network edges.
+
+### `<Comet>` — one tapered `<polygon>` per datum
+
+| Prop                 | Type                  | Default                                        |
+| -------------------- | --------------------- | ---------------------------------------------- |
+| `data`               | `readonly T[]`        | —                                              |
+| `x`, `y`, `x2`, `y2` | _(accessor)_ `number` | —                                              |
+| `color`              | _(accessor)_ `string` | `var(--pitch-marker-primary, #3b82f6)`         |
+| `startWidth`         | _(accessor)_ `number` | `0.5`                                          |
+| `endWidth`           | _(accessor)_ `number` | `4`                                            |
+| `gradient`           | `boolean`             | `false` — fades opacity 0 → 1 along the length |
+
+SVG cannot vary a line's stroke width along its length, so this is a filled quad.
+
+### `<Polygon>` — one `<polygon>` per datum, from explicit vertices
+
+| Prop                         | Type                                                    | Default |
+| ---------------------------- | ------------------------------------------------------- | ------- |
+| `data`                       | `readonly T[]`                                          | —       |
+| `points`                     | _(accessor)_ `ReadonlyArray<readonly [number, number]>` | —       |
+| `fill`, `stroke`             | _(accessor)_ `string`                                   | —       |
+| `fillOpacity`, `strokeWidth` | _(accessor)_ `number`                                   | —       |
+
+### `<ConvexHull>` — one polygon for the whole dataset
+
+| Prop                         | Type                  | Notes                                          |
+| ---------------------------- | --------------------- | ---------------------------------------------- |
+| `data`                       | `readonly T[]`        | —                                              |
+| `x`, `y`                     | _(accessor)_ `number` | —                                              |
+| `fill`, `stroke`             | `string`              | **Static, not accessors** — there is one shape |
+| `fillOpacity`, `strokeWidth` | `number`              | Static                                         |
+| `tooltip`                    | `ReactNode`           | **Static**, not a function                     |
+
+### `<Voronoi>` — one cell per datum, clipped to the pitch
+
+| Prop                         | Type                  |
+| ---------------------------- | --------------------- |
+| `data`                       | `readonly T[]`        |
+| `x`, `y`                     | _(accessor)_ `number` |
+| `fill`, `stroke`             | _(accessor)_ `string` |
+| `fillOpacity`, `strokeWidth` | _(accessor)_ `number` |
+
+### `<GoalAngle>` — a wedge from each point to both goalposts
+
+| Prop                         | Type                                          | Default     |
+| ---------------------------- | --------------------------------------------- | ----------- |
+| `data`                       | `readonly T[]`                                | —           |
+| `x`, `y`                     | _(accessor)_ `number`                         | —           |
+| `goal`                       | _(accessor)_ `"left" \| "right" \| "nearest"` | `"nearest"` |
+| `fill`, `stroke`             | _(accessor)_ `string`                         | —           |
+| `fillOpacity`, `strokeWidth` | _(accessor)_ `number`                         | —           |
+
+### `<Flow>` — one aggregate arrow per occupied grid bin
+
+| Prop                               | Type                                     | Default                                    |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------------ |
+| `data`                             | `readonly T[]`                           | —                                          |
+| `x`, `y`                           | _(accessor)_ `number`                    | — start point, which decides the bin       |
+| `x2`, `y2`                         | _(accessor)_ `number`                    | — end point                                |
+| `binsX`, `binsY`                   | `number`                                 | — grid resolution                          |
+| `colorMin`, `colorMax`             | `string`                                 | — colour at the lowest / highest bin count |
+| `strokeWidthMin`, `strokeWidthMax` | `number`                                 | — width at the lowest / highest bin count  |
+| `tooltip`                          | `(bin: FlowBin, i: number) => ReactNode` | — **per bin, not per datum**               |
+
+`FlowBin` is `{ x, y, x2, y2, count }` in provider coordinates.
+
+---
+
+## Canvas density layers
+
+Client-only: they paint to a `<canvas>` inside a `<foreignObject>` after hydration, and
+render empty on the server. They take `className` and `style` but **no `tooltip`**, and
+they need a `<Pitch>` with explicit `width` and `height` — see the responsive-canvas recipe
+in SKILL.md. Pair them with `appearance={{ linesOnTop: true }}` so the markings stay
+visible.
+
+All four take `data`, `x`, `y`, an optional `weight` _(accessor)_ `number` (omitted =
+count points per bin; provided = sum this per bin), and `colorMin` / `colorMax`.
+
+| Component             | Extra props                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `<Heatmap>`           | `binsX`, `binsY`                                                                                     |
+| `<PositionalHeatmap>` | `layout?: "full" \| "horizontal" \| "vertical"` (default `"full"`), `stroke?`, `strokeWidth?`        |
+| `<Hexbin>`            | `binsX` (hex columns; cell size follows), `stroke?`, `strokeWidth?`                                  |
+| `<KDE>`               | `resolution?` (grid cells per axis), `bandwidth?` (provider units; default Silverman), `maxOpacity?` |
+
+`<PositionalHeatmap>` bins into Juego de Posición zones derived from the pitch markings
+rather than a uniform grid — mplsoccer's `bin_statistic_positional`. Unlike the binned
+layers, `<KDE>` fades to transparent at low density instead of filling with `colorMin`.
+
+---
+
+## `@pitchkit/core` exports worth calling directly
+
+**Dimensions**
+
+- `getPitchDimensions(type)` → `PitchDimensions`; `PITCH_DIMENSIONS` is the record of all three.
+- `PitchDimensions.markings` → `{ penaltyAreaLength, penaltyAreaWidth, sixYardLength, sixYardWidth, centerCircleRadius, penaltySpotDistance, cornerArcRadius, goalWidth }`, in provider units.
+
+**Transforms**
+
+- `cropForHalf(dimensions)` → the attacking-half `CropWindow`.
+- `createStandardizeTransform(from, to)` → `(point) => point`, mplsoccer's `Standardizer`.
+- `createPixelTransform(dimensions, viewport)` → `PixelTransform`. `<Pitch>` builds this
+  itself; call it directly only outside React.
+
+**Aggregation** (the maths behind the density and geometry layers, usable standalone —
+e.g. to compute a legend's domain, or to render a table alongside the chart)
+
+- `computeHeatmapBins`, `computePositionalZones` / `computePositionalBins`,
+  `computeHexBins` / `hexCorners`, `computeKdeGrid` / `silvermanBandwidth`
+- `computeFlowBins`, `computeConvexHull`, `computeVoronoiCells`, `computePolygonCentroid`,
+  `computeGoalAngle` / `selectGoal`
+- `createColorScale` — the interpolator the density painters use
+
+**Theming**
+
+- `pitchTokens` — `{ surface, stripe, lines, lineWidth, markerPrimary, markerGoal, markerMiss }`,
+  mapping to the CSS variable names. Values live in CSS, never here.
+
+**Types** — `PitchTypeId`, `PitchDimensions`, `PitchMarkings`, `Point`, `Orientation`,
+`CropWindow`, `ViewportPadding`, `Viewport`, `PixelTransform`, `Scene`, `Layer`,
+`Accessor`, `PitchAppearance`, and one `*Layer<T>` interface per mark. The React
+components' props are `Omit<XLayer<T>, "type">` plus `tooltip`, so the layer interfaces are
+the canonical prop definitions.
+
+### Not for consumer code
+
+`svgRenderer`, `renderSceneToSVGElement`, `renderDensityLayersToCanvas`,
+`renderHeatmapLayersToCanvas`, `canvasRenderer` and the `paint*` helpers are internal
+rendering machinery, exported only for the repo's own dev harness. Render through
+`@pitchkit/react`.