@tungstenstudio/outschart-generator 1.0.0-rc.0

package/src/lookup.ts

@@ -0,0 +1,47 @@
+import { DOUBLE_OUT_CHECKOUTS, DOUBLE_OUT_BOGEY_NUMBERS } from './data/double-out-checkouts.js';
+import { SINGLE_OUT_CHECKOUTS, SINGLE_OUT_BOGEY_NUMBERS } from './data/single-out-checkouts.js';
+import type { OutMode, CheckoutEntry, CheckoutChart } from './types.js';
+
+function getChartForMode(outMode: OutMode): CheckoutChart {
+  return outMode === 'double' ? DOUBLE_OUT_CHECKOUTS : SINGLE_OUT_CHECKOUTS;
+}
+
+function getBogeyNumbersForMode(outMode: OutMode): number[] {
+  return outMode === 'double' ? DOUBLE_OUT_BOGEY_NUMBERS : SINGLE_OUT_BOGEY_NUMBERS;
+}
+
+export function getCheckout(score: number, outMode: OutMode = 'double'): CheckoutEntry | null {
+  const chart = getChartForMode(outMode);
+  return chart[score] ?? null;
+}
+
+export function getCheckoutChart(
+  outMode: OutMode = 'double',
+  range?: { min?: number; max?: number },
+): CheckoutChart {
+  const chart = getChartForMode(outMode);
+
+  if (!range) return { ...chart };
+
+  const min = range.min ?? 0;
+  const max = range.max ?? Infinity;
+  const filtered: CheckoutChart = {};
+
+  for (const [scoreStr, entry] of Object.entries(chart)) {
+    const score = Number(scoreStr);
+    if (score >= min && score <= max) {
+      filtered[score] = entry;
+    }
+  }
+
+  return filtered;
+}
+
+export function getBogeyNumbers(outMode: OutMode = 'double'): number[] {
+  return [...getBogeyNumbersForMode(outMode)];
+}
+
+export function isCheckable(score: number, outMode: OutMode = 'double'): boolean {
+  const chart = getChartForMode(outMode);
+  return score in chart;
+}

package/src/miss-analysis.ts

@@ -0,0 +1,90 @@
+import type { OutMode, CheckoutChart, DartAnnotation, MissAnalysisResult } from './types.js';
+import { getCheckoutChart } from './lookup.js';
+
+function missResult(dart: string): { label: string; value: number } | null {
+  if (dart === 'Bull') return { label: '25', value: 25 };
+  if (dart === '25') return { label: '25', value: 25 };
+  const m = dart.match(/^([TD]?)(\d+)$/);
+  if (!m) return null;
+  const num = parseInt(m[2]);
+  const prefix = m[1];
+  if (prefix === 'T' || prefix === 'D') return { label: `${num}`, value: num };
+  return { label: dart, value: parseInt(dart) };
+}
+
+function dartValue(d: string): number {
+  if (d === 'Bull') return 50;
+  if (d === '25') return 25;
+  const m = d.match(/^([TD]?)(\d+)$/);
+  if (!m) return NaN;
+  const num = parseInt(m[2]);
+  const prefix = m[1];
+  if (prefix === 'T') return num * 3;
+  if (prefix === 'D') return num * 2;
+  return num;
+}
+
+function isScoreCheckable(score: number, checkoutsMap: CheckoutChart): boolean {
+  return score >= 1 && score in checkoutsMap;
+}
+
+export function analyzeMisses(
+  score: number,
+  path: string[],
+  outMode: OutMode = 'double',
+): MissAnalysisResult {
+  const checkoutsMap = getCheckoutChart(outMode);
+  const annotations: DartAnnotation[] = [];
+  let remaining = score;
+
+  for (let i = 0; i < path.length; i++) {
+    const dart = path[i];
+    const value = dartValue(dart);
+    const miss = missResult(dart);
+    const isSingle = !dart.startsWith('T') && !dart.startsWith('D') && dart !== 'Bull';
+
+    const annotation: DartAnnotation = {
+      dart: i + 1,
+      target: dart,
+      missRelevant: false,
+    };
+
+    if (!isSingle && miss) {
+      const missRemaining = remaining - miss.value;
+      annotation.missRelevant = true;
+      annotation.missResult = miss.label;
+      annotation.missRemaining = missRemaining;
+
+      if (i === path.length - 1) {
+        annotation.stillCheckable = isScoreCheckable(missRemaining, checkoutsMap);
+        annotation.remainderCheckout = checkoutsMap[missRemaining]?.darts ?? null;
+      } else {
+        annotation.stillCheckable = isScoreCheckable(missRemaining, checkoutsMap);
+      }
+    }
+
+    annotations.push(annotation);
+    remaining -= value;
+  }
+
+  const relevantMisses = annotations.filter((m) => m.missRelevant);
+  const checkableMisses = relevantMisses.filter((m) => m.stillCheckable);
+  const missResiliency =
+    relevantMisses.length > 0
+      ? `${checkableMisses.length}/${relevantMisses.length}`
+      : 'N/A';
+
+  return { score, path, annotations, missResiliency };
+}
+
+export function analyzeCheckoutChart(
+  chart: CheckoutChart,
+  outMode: OutMode = 'double',
+): Record<number, MissAnalysisResult> {
+  const results: Record<number, MissAnalysisResult> = {};
+  for (const [scoreStr, entry] of Object.entries(chart)) {
+    const score = Number(scoreStr);
+    results[score] = analyzeMisses(score, entry.darts, outMode);
+  }
+  return results;
+}

package/src/notation.ts

@@ -0,0 +1,69 @@
+import { parseTarget } from './dartboard.js';
+import type { CheckoutChart, CheckoutEntry } from './types.js';
+import { OutsChartError } from './types.js';
+
+export interface NotationMap {
+  treble: string;
+  double: string;
+  single: string;
+  bull: string;
+  outerBull: string;
+}
+
+export const NOTATIONS: Record<string, NotationMap> = {
+  default: { treble: 'T', double: 'D', single: '', bull: 'Bull', outerBull: '25' },
+  british: { treble: 'T', double: 'D', single: 'S', bull: 'DB', outerBull: 'SB' },
+  american: { treble: 'T', double: 'D', single: '', bull: 'DB', outerBull: 'SB' },
+  explicit: { treble: 'T', double: 'D', single: 'S', bull: 'Bull', outerBull: '25' },
+};
+
+export function formatDart(dart: string, notation: NotationMap): string {
+  const parsed = parseTarget(dart);
+  if (!parsed) {
+    throw new OutsChartError('INVALID_TARGET', `Cannot format invalid dart notation '${dart}'`);
+  }
+
+  if (parsed.bed === 'Bull') return notation.bull;
+  if (parsed.bed === '25') return notation.outerBull;
+  if (parsed.bed === 'treble') return `${notation.treble}${parsed.number}`;
+  if (parsed.bed === 'double') return `${notation.double}${parsed.number}`;
+  return `${notation.single}${parsed.number}`;
+}
+
+export function formatCheckoutChart(
+  chart: CheckoutChart,
+  notation: NotationMap | string,
+): CheckoutChart {
+  const map = resolveNotation(notation);
+  const result: CheckoutChart = {};
+
+  for (const [scoreStr, entry] of Object.entries(chart)) {
+    const score = Number(scoreStr);
+    const formatted: CheckoutEntry = {
+      darts: entry.darts.map((d) => formatDart(d, map)),
+      numDarts: entry.numDarts,
+    };
+    if (entry.alternates) {
+      formatted.alternates = entry.alternates.map((alt) =>
+        alt.map((d) => formatDart(d, map)),
+      );
+    }
+    result[score] = formatted;
+  }
+
+  return result;
+}
+
+function resolveNotation(notation: NotationMap | string): NotationMap {
+  if (typeof notation === 'string') {
+    const preset = NOTATIONS[notation];
+    if (!preset) {
+      throw new OutsChartError(
+        'INVALID_TARGET',
+        `Unknown notation preset '${notation}'. Available: ${Object.keys(NOTATIONS).join(', ')}`,
+      );
+    }
+    return preset;
+  }
+  return notation;
+}

package/src/recommend.ts

@@ -0,0 +1,434 @@
+import { parseTarget, evaluateThrow } from './dartboard.js';
+import dimensions from './data/dartboard-dimensions.json' with { type: 'json' };
+import type { OutMode, CheckoutChart, CheckoutResult } from './types.js';
+import { OutsChartError } from './types.js';
+
+interface Target {
+  label: string;
+  value: number;
+}
+
+function buildTargets(): Target[] {
+  const targets: Target[] = [];
+  for (let i = 1; i <= 20; i++) {
+    targets.push({ label: `${i}`, value: i });
+    targets.push({ label: `D${i}`, value: i * 2 });
+    targets.push({ label: `T${i}`, value: i * 3 });
+  }
+  targets.push({ label: '25', value: 25 });
+  targets.push({ label: 'Bull', value: 50 });
+  return targets;
+}
+
+function buildFinishingDoubles(): Target[] {
+  const doubles: Target[] = [];
+  for (let i = 1; i <= 20; i++) {
+    doubles.push({ label: `D${i}`, value: i * 2 });
+  }
+  doubles.push({ label: 'Bull', value: 50 });
+  return doubles;
+}
+
+const allTargets = buildTargets();
+const finishingDoubles = buildFinishingDoubles();
+
+const AREA = {
+  treble: dimensions.segmentAreas.trebleBed,
+  double: dimensions.segmentAreas.doubleBed,
+  largeSingle: dimensions.segmentAreas.largeSingle,
+  smallSingle: dimensions.segmentAreas.smallSingle,
+  bull: dimensions.segmentAreas.doubleBull,
+  outerBull: dimensions.segmentAreas.singleBull,
+};
+
+// All 1-dart checkable scores for single-out
+const oneDartScores = new Set(allTargets.map((t) => t.value));
+
+function missWeight(target: string, missType: string): number {
+  const parsed = parseTarget(target);
+  if (!parsed) return 0.5;
+
+  if (missType === 'radialIn') {
+    if (!parsed.bed || parsed.bed === null) return AREA.treble / AREA.largeSingle;
+    if (parsed.bed === 'double') return 1.0;
+    if (parsed.bed === 'treble') return 1.0;
+    return 0.5;
+  }
+
+  if (missType === 'radialOut') {
+    if (!parsed.bed || parsed.bed === null) return AREA.double / AREA.largeSingle;
+    if (parsed.bed === 'double') return 0.5;
+    if (parsed.bed === 'treble') return 1.0;
+    return 0.5;
+  }
+
+  return 0.7;
+}
+
+function evaluatePath(
+  score: number,
+  darts: string[],
+  outMode: OutMode,
+  checkableScores?: Set<number>,
+): number {
+  let penalty = 0;
+  let remaining = score;
+  const isDoubleOut = outMode === 'double';
+
+  for (let i = 0; i < darts.length; i++) {
+    const dart = darts[i];
+    const parsed = parseTarget(dart);
+    if (!parsed) return Infinity;
+
+    const evaluation = evaluateThrow(dart, remaining);
+    if (!evaluation) return Infinity;
+
+    for (const miss of evaluation.misses) {
+      const weight = missWeight(dart, miss.missType);
+      if (miss.busts) {
+        penalty += 6 * weight;
+      } else if (isDoubleOut) {
+        // In double-out, bust also if remaining = 1 (can't finish on a double)
+        const missRemaining = remaining - miss.value;
+        if (missRemaining === 1) {
+          penalty += 6 * weight;
+        } else if (missRemaining === 0) {
+          // Only counts as accidental checkout if last dart would be a valid finisher
+          // In double-out, miss to a single doesn't count as checkout
+        } else if (checkableScores && checkableScores.has(missRemaining)) {
+          penalty -= 0.5 * weight;
+        }
+      } else {
+        const missRemaining = remaining - miss.value;
+        if (missRemaining === 0) {
+          penalty -= 1 * weight;
+        } else if (missRemaining > 0 && oneDartScores.has(missRemaining)) {
+          penalty -= 0.5 * weight;
+        }
+      }
+    }
+
+    // Prefer larger targets
+    let targetArea: number;
+    if (parsed.bed === 'treble') targetArea = AREA.treble;
+    else if (parsed.bed === 'double') targetArea = AREA.double;
+    else if (dart === 'Bull') targetArea = AREA.bull;
+    else if (dart === '25') targetArea = AREA.outerBull;
+    else targetArea = AREA.largeSingle;
+    penalty += (1 - targetArea / AREA.largeSingle) * 5.5;
+
+    // Hard penalty: never use treble/double when a fat single scores the same
+    if ((parsed.bed === 'treble' || parsed.bed === 'double') && parsed.value <= 20) {
+      penalty += 5;
+    }
+
+    // Penalize harder darts following easier ones (throw hard darts first)
+    if (i > 0) {
+      const difficulty = (d: string) => {
+        if (/^T\d+$/.test(d)) return 3;
+        if (d === 'Bull') return 2;
+        if (/^D\d+$/.test(d)) return 1.5;
+        if (d === '25') return 1;
+        return 0;
+      };
+      const prev = difficulty(darts[i - 1]);
+      const curr = difficulty(dart);
+      if (curr > prev && (parsed.bed === 'treble' || dart === 'Bull')) {
+        penalty += 4.0;
+      }
+    }
+
+    remaining -= parsed.value;
+  }
+
+  // Prefer finishing doubles with good halving chains
+  const lastDart = darts[darts.length - 1];
+  const lastMatch = lastDart.match(/^D(\d+)$/);
+  if (lastMatch) {
+    let val = parseInt(lastMatch[1]);
+    let chainLen = 0;
+    while (val % 2 === 0) { val /= 2; chainLen++; }
+    chainLen++;
+    penalty -= chainLen * 0.2;
+  }
+
+  return penalty;
+}
+
+function sortTrebles(darts: string[]): string[] {
+  const sorted = [...darts];
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const m1 = sorted[i].match(/^T(\d+)$/);
+    const m2 = sorted[i + 1].match(/^T(\d+)$/);
+    if (m1 && m2 && parseInt(m1[1]) < parseInt(m2[1])) {
+      [sorted[i], sorted[i + 1]] = [sorted[i + 1], sorted[i]];
+    }
+  }
+  return sorted;
+}
+
+function pathKey(darts: string[]): string {
+  return [...darts].sort().join(',');
+}
+
+// Single-out overrides
+const SINGLE_OUT_OVERRIDES: Record<number, { darts: string[] }> = {
+  1: { darts: ['1'] }, 2: { darts: ['2'] }, 3: { darts: ['3'] }, 4: { darts: ['4'] },
+  5: { darts: ['5'] }, 6: { darts: ['6'] }, 7: { darts: ['7'] }, 8: { darts: ['8'] },
+  9: { darts: ['9'] }, 10: { darts: ['10'] }, 11: { darts: ['11'] }, 12: { darts: ['12'] },
+  13: { darts: ['13'] }, 14: { darts: ['14'] }, 15: { darts: ['15'] }, 16: { darts: ['16'] },
+  17: { darts: ['17'] }, 18: { darts: ['18'] }, 19: { darts: ['19'] }, 20: { darts: ['20'] },
+  21: { darts: ['7', '14'] }, 23: { darts: ['3', '20'] },
+  25: { darts: ['9', '16'] }, 27: { darts: ['9', '18'] },
+  29: { darts: ['9', '20'] }, 31: { darts: ['12', '19'] },
+  33: { darts: ['14', '19'] }, 35: { darts: ['15', '20'] },
+  37: { darts: ['18', '19'] }, 39: { darts: ['19', '20'] },
+  50: { darts: ['10', 'D20'] },
+  80: { darts: ['T20', '20'] },
+  82: { darts: ['T14', 'D20'] },
+  92: { darts: ['T20', 'D16'] },
+  100: { darts: ['T20', 'D20'] },
+  103: { darts: ['T19', '6', 'D20'] },
+  147: { darts: ['T20', 'T17', 'D18'] },
+};
+
+function findBestCheckout(
+  score: number,
+  outMode: OutMode,
+  altThreshold: number,
+  includeAlternates: boolean,
+  overrides: Record<number, { darts: string[] }>,
+): { darts: string[]; numDarts: number; penalty: number; alternates: string[][] } | null {
+  const isDoubleOut = outMode === 'double';
+  const finishing = isDoubleOut ? finishingDoubles : allTargets;
+
+  let best: string[] | null = null;
+  let bestPenalty = Infinity;
+  let bestNumDarts = Infinity;
+
+  // 1-dart finishes
+  for (const t of finishing) {
+    if (t.value !== score) continue;
+    const parsed = parseTarget(t.label);
+    // In single-out, trebles for scores <=40 compete as priority 2
+    const priority = (!isDoubleOut && parsed?.bed === 'treble' && score <= 40) ? 2 : 1;
+    const penalty = evaluatePath(score, [t.label], outMode);
+    if (priority < bestNumDarts || (priority === bestNumDarts && penalty < bestPenalty)) {
+      best = [t.label];
+      bestPenalty = penalty;
+      bestNumDarts = priority;
+    }
+  }
+
+  // 2-dart finishes
+  for (const d1 of allTargets) {
+    if (d1.value >= score) continue;
+    const remainder = score - d1.value;
+    for (const d2 of finishing) {
+      if (d2.value !== remainder) continue;
+      const path = [d1.label, d2.label];
+      const penalty = evaluatePath(score, path, outMode);
+      if (2 < bestNumDarts || (2 === bestNumDarts && penalty < bestPenalty)) {
+        best = path;
+        bestPenalty = penalty;
+        bestNumDarts = 2;
+      }
+    }
+  }
+
+  // 3-dart finishes
+  if (bestNumDarts > 2 || score > 110) {
+    for (const d1 of allTargets) {
+      if (d1.value >= score) continue;
+      for (const d2 of allTargets) {
+        if (d1.value + d2.value >= score) continue;
+        const remainder = score - d1.value - d2.value;
+        for (const d3 of finishing) {
+          if (d3.value !== remainder) continue;
+          const path = [d1.label, d2.label, d3.label];
+          const penalty = evaluatePath(score, path, outMode);
+          if (3 < bestNumDarts || (3 === bestNumDarts && penalty < bestPenalty)) {
+            best = path;
+            bestPenalty = penalty;
+            bestNumDarts = 3;
+          }
+        }
+      }
+    }
+  }
+
+  if (!best) return null;
+
+  best = sortTrebles(best);
+
+  if (!includeAlternates) {
+    return { darts: best, numDarts: best.length, penalty: bestPenalty, alternates: [] };
+  }
+
+  // Collect alternates within threshold
+  const alternates: { darts: string[]; penalty: number }[] = [];
+  const seen = new Set<string>();
+  seen.add(pathKey(best));
+
+  const collectAlt = (path: string[], penalty: number) => {
+    if (penalty > bestPenalty + altThreshold) return;
+    const key = pathKey(path);
+    if (seen.has(key)) return;
+    seen.add(key);
+    alternates.push({ darts: sortTrebles(path), penalty });
+  };
+
+  if (bestNumDarts === 1) {
+    for (const t of finishing) {
+      if (t.value !== score) continue;
+      collectAlt([t.label], evaluatePath(score, [t.label], outMode));
+    }
+  }
+
+  if (bestNumDarts <= 2) {
+    for (const d1 of allTargets) {
+      if (d1.value >= score) continue;
+      const remainder = score - d1.value;
+      for (const d2 of finishing) {
+        if (d2.value !== remainder) continue;
+        collectAlt([d1.label, d2.label], evaluatePath(score, [d1.label, d2.label], outMode));
+      }
+    }
+  }
+
+  if (bestNumDarts === 3) {
+    for (const d1 of allTargets) {
+      if (d1.value >= score) continue;
+      for (const d2 of allTargets) {
+        if (d1.value + d2.value >= score) continue;
+        const remainder = score - d1.value - d2.value;
+        for (const d3 of finishing) {
+          if (d3.value !== remainder) continue;
+          collectAlt(
+            [d1.label, d2.label, d3.label],
+            evaluatePath(score, [d1.label, d2.label, d3.label], outMode),
+          );
+        }
+      }
+    }
+  }
+
+  alternates.sort((a, b) => a.penalty - b.penalty);
+
+  return {
+    darts: best,
+    numDarts: best.length,
+    penalty: bestPenalty,
+    alternates: alternates.slice(0, 5).map((a) => a.darts),
+  };
+}
+
+function validateOverrides(
+  overrides: Record<number, { darts: string[] }>,
+  outMode: OutMode,
+): void {
+  const isDoubleOut = outMode === 'double';
+
+  for (const [scoreStr, entry] of Object.entries(overrides)) {
+    const score = Number(scoreStr);
+
+    if (!Array.isArray(entry.darts) || entry.darts.length === 0 || entry.darts.length > 3) {
+      throw new OutsChartError(
+        'INVALID_OVERRIDE',
+        `Override for score ${score}: must have 1-3 darts`,
+      );
+    }
+
+    let sum = 0;
+    for (const dart of entry.darts) {
+      const parsed = parseTarget(dart);
+      if (!parsed) {
+        throw new OutsChartError(
+          'INVALID_OVERRIDE',
+          `Override for score ${score}: invalid dart notation '${dart}'`,
+        );
+      }
+      sum += parsed.value;
+    }
+
+    if (sum !== score) {
+      throw new OutsChartError(
+        'INVALID_OVERRIDE',
+        `Override for score ${score}: darts sum to ${sum}, expected ${score}`,
+      );
+    }
+
+    const lastDart = entry.darts[entry.darts.length - 1];
+    const lastParsed = parseTarget(lastDart)!;
+    if (isDoubleOut && lastParsed.bed !== 'double' && lastParsed.bed !== 'Bull') {
+      throw new OutsChartError(
+        'INVALID_OVERRIDE',
+        `Override for score ${score}: last dart '${lastDart}' is not a valid double-out finish`,
+      );
+    }
+  }
+}
+
+export function generateRecommended(options: {
+  outMode: OutMode;
+  min?: number;
+  max?: number;
+  includeAlternates?: boolean;
+  altThreshold?: number;
+  overrides?: Record<number, { darts: string[] }>;
+}): CheckoutResult {
+  const { outMode } = options;
+  const isDoubleOut = outMode === 'double';
+  const min = options.min ?? (isDoubleOut ? 2 : 1);
+  const max = options.max ?? (isDoubleOut ? 170 : 180);
+  const includeAlternates = options.includeAlternates ?? (outMode === 'single');
+  const altThreshold = options.altThreshold ?? 1.0;
+
+  // Build overrides: start with defaults for single-out, merge user overrides
+  const overrides: Record<number, { darts: string[] }> = {};
+  if (!isDoubleOut) {
+    Object.assign(overrides, SINGLE_OUT_OVERRIDES);
+  }
+  if (options.overrides) {
+    validateOverrides(options.overrides, outMode);
+    Object.assign(overrides, options.overrides);
+  }
+
+  const checkouts: CheckoutChart = {};
+  const bogeyNumbers: number[] = [];
+
+  for (let score = min; score <= max; score++) {
+    const result = findBestCheckout(score, outMode, altThreshold, includeAlternates, overrides);
+
+    if (overrides[score]) {
+      const ov = overrides[score];
+      checkouts[score] = {
+        darts: ov.darts,
+        numDarts: ov.darts.length,
+      };
+      if (includeAlternates && result && result.alternates.length > 0 && ov.darts.length > 1) {
+        const overrideKey = pathKey(ov.darts);
+        const alts = result.alternates.filter((a) => pathKey(a) !== overrideKey);
+        if (pathKey(result.darts) !== overrideKey) {
+          alts.unshift(result.darts);
+        }
+        if (alts.length > 0) checkouts[score].alternates = alts;
+      }
+      continue;
+    }
+
+    if (result) {
+      checkouts[score] = {
+        darts: result.darts,
+        numDarts: result.numDarts,
+      };
+      if (includeAlternates && result.alternates.length > 0) {
+        checkouts[score].alternates = result.alternates;
+      }
+    } else {
+      bogeyNumbers.push(score);
+    }
+  }
+
+  return { checkouts, bogeyNumbers };
+}