endurance-coach 0.1.1 → 1.0.0

package/dist/schema/compact-plan.schema.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Compact Training Plan Zod Schema
+ *
+ * Runtime validation for compact training plans generated by AI models.
+ */
+import { z } from "zod";
+export declare const SportSchema: z.ZodEnum<{
+    swim: "swim";
+    bike: "bike";
+    run: "run";
+    strength: "strength";
+    brick: "brick";
+    race: "race";
+    rest: "rest";
+}>;
+export declare const FirstDayOfWeekSchema: z.ZodEnum<{
+    monday: "monday";
+    sunday: "sunday";
+}>;
+export declare const DistanceUnitSchema: z.ZodEnum<{
+    km: "km";
+    mi: "mi";
+}>;
+export declare const DayOfWeekSchema: z.ZodEnum<{
+    Mon: "Mon";
+    Tue: "Tue";
+    Wed: "Wed";
+    Thu: "Thu";
+    Fri: "Fri";
+    Sat: "Sat";
+    Sun: "Sun";
+}>;
+/**
+ * Pace string validation - formats like "5:30/km", "8:00/mi", "1:45/100m"
+ */
+export declare const PaceStringSchema: z.ZodString;
+/**
+ * Duration string validation - formats like "30", "30min", "1:30", "90s"
+ */
+export declare const DurationStringSchema: z.ZodString;
+export declare const AthletePacesSchema: z.ZodObject<{
+    easy: z.ZodOptional<z.ZodString>;
+    long: z.ZodOptional<z.ZodString>;
+    tempo: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodOptional<z.ZodString>;
+    marathon: z.ZodOptional<z.ZodString>;
+    halfMarathon: z.ZodOptional<z.ZodString>;
+    interval: z.ZodOptional<z.ZodString>;
+    r200: z.ZodOptional<z.ZodString>;
+    r400: z.ZodOptional<z.ZodString>;
+    r800: z.ZodOptional<z.ZodString>;
+    r1k: z.ZodOptional<z.ZodString>;
+    rMile: z.ZodOptional<z.ZodString>;
+    bikeFtp: z.ZodOptional<z.ZodNumber>;
+    bikeEasy: z.ZodOptional<z.ZodString>;
+    bikeTempo: z.ZodOptional<z.ZodString>;
+    bikeThreshold: z.ZodOptional<z.ZodString>;
+    swimCss: z.ZodOptional<z.ZodString>;
+    swimEasy: z.ZodOptional<z.ZodString>;
+    swimTempo: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const HRZoneConfigSchema: z.ZodObject<{
+    lthr: z.ZodNumber;
+    maxHR: z.ZodOptional<z.ZodNumber>;
+    restingHR: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const AthleteZonesSchema: z.ZodObject<{
+    hr: z.ZodOptional<z.ZodObject<{
+        lthr: z.ZodNumber;
+        maxHR: z.ZodOptional<z.ZodNumber>;
+        restingHR: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const AthleteConstraintsSchema: z.ZodObject<{
+    daysPerWeek: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    preferredDays: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxLongRunHours: z.ZodOptional<z.ZodNumber>;
+    maxLongBikeHours: z.ZodOptional<z.ZodNumber>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const CompactAthleteSchema: z.ZodObject<{
+    name: z.ZodString;
+    event: z.ZodString;
+    eventDate: z.ZodString;
+    paces: z.ZodObject<{
+        easy: z.ZodOptional<z.ZodString>;
+        long: z.ZodOptional<z.ZodString>;
+        tempo: z.ZodOptional<z.ZodString>;
+        threshold: z.ZodOptional<z.ZodString>;
+        marathon: z.ZodOptional<z.ZodString>;
+        halfMarathon: z.ZodOptional<z.ZodString>;
+        interval: z.ZodOptional<z.ZodString>;
+        r200: z.ZodOptional<z.ZodString>;
+        r400: z.ZodOptional<z.ZodString>;
+        r800: z.ZodOptional<z.ZodString>;
+        r1k: z.ZodOptional<z.ZodString>;
+        rMile: z.ZodOptional<z.ZodString>;
+        bikeFtp: z.ZodOptional<z.ZodNumber>;
+        bikeEasy: z.ZodOptional<z.ZodString>;
+        bikeTempo: z.ZodOptional<z.ZodString>;
+        bikeThreshold: z.ZodOptional<z.ZodString>;
+        swimCss: z.ZodOptional<z.ZodString>;
+        swimEasy: z.ZodOptional<z.ZodString>;
+        swimTempo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    zones: z.ZodOptional<z.ZodObject<{
+        hr: z.ZodOptional<z.ZodObject<{
+            lthr: z.ZodNumber;
+            maxHR: z.ZodOptional<z.ZodNumber>;
+            restingHR: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    constraints: z.ZodOptional<z.ZodObject<{
+        daysPerWeek: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        preferredDays: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxLongRunHours: z.ZodOptional<z.ZodNumber>;
+        maxLongBikeHours: z.ZodOptional<z.ZodNumber>;
+        notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    unit: z.ZodDefault<z.ZodEnum<{
+        km: "km";
+        mi: "mi";
+    }>>;
+    firstDayOfWeek: z.ZodDefault<z.ZodEnum<{
+        monday: "monday";
+        sunday: "sunday";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Week range can be "1-3" or [1, 2, 3]
+ */
+export declare const WeekRangeSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodNumber>]>;
+export declare const CompactPhaseSchema: z.ZodObject<{
+    name: z.ZodString;
+    weeks: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodNumber>]>;
+    focus: z.ZodString;
+    keyWorkouts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Workout reference validation.
+ * Format: "template.id" or "template.id(param)" or "template.id(param1, param2)"
+ */
+export declare const WorkoutRefSchema: z.ZodString;
+/**
+ * A day can have a single workout or multiple (for brick days).
+ */
+export declare const DayWorkoutSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+/**
+ * Week schedule maps days to workouts.
+ */
+export declare const CompactWeekScheduleSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+export declare const CompactWeekSchema: z.ZodObject<{
+    week: z.ZodNumber;
+    phase: z.ZodString;
+    focus: z.ZodOptional<z.ZodString>;
+    isRecoveryWeek: z.ZodOptional<z.ZodBoolean>;
+    targetHours: z.ZodOptional<z.ZodNumber>;
+    workouts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
+export declare const CompactRaceStrategySchema: z.ZodObject<{
+    goalTime: z.ZodOptional<z.ZodString>;
+    pacing: z.ZodOptional<z.ZodObject<{
+        swim: z.ZodOptional<z.ZodString>;
+        bike: z.ZodOptional<z.ZodString>;
+        run: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nutrition: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const CompactPlanSchema: z.ZodObject<{
+    version: z.ZodLiteral<"2.0">;
+    athlete: z.ZodObject<{
+        name: z.ZodString;
+        event: z.ZodString;
+        eventDate: z.ZodString;
+        paces: z.ZodObject<{
+            easy: z.ZodOptional<z.ZodString>;
+            long: z.ZodOptional<z.ZodString>;
+            tempo: z.ZodOptional<z.ZodString>;
+            threshold: z.ZodOptional<z.ZodString>;
+            marathon: z.ZodOptional<z.ZodString>;
+            halfMarathon: z.ZodOptional<z.ZodString>;
+            interval: z.ZodOptional<z.ZodString>;
+            r200: z.ZodOptional<z.ZodString>;
+            r400: z.ZodOptional<z.ZodString>;
+            r800: z.ZodOptional<z.ZodString>;
+            r1k: z.ZodOptional<z.ZodString>;
+            rMile: z.ZodOptional<z.ZodString>;
+            bikeFtp: z.ZodOptional<z.ZodNumber>;
+            bikeEasy: z.ZodOptional<z.ZodString>;
+            bikeTempo: z.ZodOptional<z.ZodString>;
+            bikeThreshold: z.ZodOptional<z.ZodString>;
+            swimCss: z.ZodOptional<z.ZodString>;
+            swimEasy: z.ZodOptional<z.ZodString>;
+            swimTempo: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        zones: z.ZodOptional<z.ZodObject<{
+            hr: z.ZodOptional<z.ZodObject<{
+                lthr: z.ZodNumber;
+                maxHR: z.ZodOptional<z.ZodNumber>;
+                restingHR: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        constraints: z.ZodOptional<z.ZodObject<{
+            daysPerWeek: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            preferredDays: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxLongRunHours: z.ZodOptional<z.ZodNumber>;
+            maxLongBikeHours: z.ZodOptional<z.ZodNumber>;
+            notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        unit: z.ZodDefault<z.ZodEnum<{
+            km: "km";
+            mi: "mi";
+        }>>;
+        firstDayOfWeek: z.ZodDefault<z.ZodEnum<{
+            monday: "monday";
+            sunday: "sunday";
+        }>>;
+    }, z.core.$strip>;
+    phases: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        weeks: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodNumber>]>;
+        focus: z.ZodString;
+        keyWorkouts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    weeks: z.ZodArray<z.ZodObject<{
+        week: z.ZodNumber;
+        phase: z.ZodString;
+        focus: z.ZodOptional<z.ZodString>;
+        isRecoveryWeek: z.ZodOptional<z.ZodBoolean>;
+        targetHours: z.ZodOptional<z.ZodNumber>;
+        workouts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+    raceStrategy: z.ZodOptional<z.ZodObject<{
+        goalTime: z.ZodOptional<z.ZodString>;
+        pacing: z.ZodOptional<z.ZodObject<{
+            swim: z.ZodOptional<z.ZodString>;
+            bike: z.ZodOptional<z.ZodString>;
+            run: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        nutrition: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CompactValidationResult = {
+    success: true;
+    data: z.infer<typeof CompactPlanSchema>;
+} | {
+    success: false;
+    errors: CompactValidationError[];
+};
+export interface CompactValidationError {
+    path: string;
+    message: string;
+    code: string;
+}
+/**
+ * Validate a compact training plan against the schema.
+ */
+export declare function validateCompactPlan(data: unknown): CompactValidationResult;
+/**
+ * Validate a compact plan and throw an error if invalid.
+ */
+export declare function validateCompactPlanOrThrow(data: unknown): z.infer<typeof CompactPlanSchema>;
+/**
+ * Format validation errors into a human-readable string.
+ */
+export declare function formatCompactValidationErrors(errors: CompactValidationError[]): string;
+export type CompactPlan = z.infer<typeof CompactPlanSchema>;
+export type CompactAthlete = z.infer<typeof CompactAthleteSchema>;
+export type CompactPhase = z.infer<typeof CompactPhaseSchema>;
+export type CompactWeek = z.infer<typeof CompactWeekSchema>;
+export type CompactWeekSchedule = z.infer<typeof CompactWeekScheduleSchema>;
+export type CompactRaceStrategy = z.infer<typeof CompactRaceStrategySchema>;
+export type AthletePaces = z.infer<typeof AthletePacesSchema>;
+export type AthleteZones = z.infer<typeof AthleteZonesSchema>;
+export type HRZoneConfig = z.infer<typeof HRZoneConfigSchema>;

package/dist/schema/compact-plan.schema.js

@@ -0,0 +1,205 @@
+/**
+ * Compact Training Plan Zod Schema
+ *
+ * Runtime validation for compact training plans generated by AI models.
+ */
+import { z } from "zod";
+// ============================================================================
+// Core Types
+// ============================================================================
+export const SportSchema = z.enum(["swim", "bike", "run", "strength", "brick", "race", "rest"]);
+export const FirstDayOfWeekSchema = z.enum(["monday", "sunday"]);
+export const DistanceUnitSchema = z.enum(["km", "mi"]);
+export const DayOfWeekSchema = z.enum(["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]);
+// ============================================================================
+// Athlete Configuration
+// ============================================================================
+/**
+ * Pace string validation - formats like "5:30/km", "8:00/mi", "1:45/100m"
+ */
+export const PaceStringSchema = z
+    .string()
+    .regex(/^\d{1,2}:\d{2}(\/(?:km|mi|100[my]))?$/, "Pace must be in format MM:SS or MM:SS/unit (e.g., '5:30/km', '8:00/mi', '1:45/100m')");
+/**
+ * Duration string validation - formats like "30", "30min", "1:30", "90s"
+ */
+export const DurationStringSchema = z
+    .string()
+    .regex(/^(\d+(?::\d{2})?(?:min|s|h)?|\d+)$/, "Duration must be a number or format like '30min', '1:30', '90s'");
+export const AthletePacesSchema = z
+    .object({
+    // Running paces
+    easy: PaceStringSchema.optional(),
+    long: PaceStringSchema.optional(),
+    tempo: PaceStringSchema.optional(),
+    threshold: PaceStringSchema.optional(),
+    marathon: PaceStringSchema.optional(),
+    halfMarathon: PaceStringSchema.optional(),
+    interval: PaceStringSchema.optional(),
+    // Interval-specific paces
+    r200: PaceStringSchema.optional(),
+    r400: PaceStringSchema.optional(),
+    r800: PaceStringSchema.optional(),
+    r1k: PaceStringSchema.optional(),
+    rMile: PaceStringSchema.optional(),
+    // Cycling
+    bikeFtp: z.number().positive().optional(),
+    bikeEasy: z.string().optional(),
+    bikeTempo: z.string().optional(),
+    bikeThreshold: z.string().optional(),
+    // Swimming
+    swimCss: PaceStringSchema.optional(),
+    swimEasy: PaceStringSchema.optional(),
+    swimTempo: PaceStringSchema.optional(),
+})
+    .refine((paces) => Object.values(paces).some((v) => v !== undefined), "At least one pace value must be provided");
+export const HRZoneConfigSchema = z.object({
+    lthr: z.number().int().min(100).max(220),
+    maxHR: z.number().int().min(120).max(230).optional(),
+    restingHR: z.number().int().min(30).max(100).optional(),
+});
+export const AthleteZonesSchema = z.object({
+    hr: HRZoneConfigSchema.optional(),
+});
+export const AthleteConstraintsSchema = z.object({
+    daysPerWeek: z.union([z.number().int().min(1).max(7), z.string()]).optional(),
+    preferredDays: z.array(z.string()).optional(),
+    maxLongRunHours: z.number().positive().optional(),
+    maxLongBikeHours: z.number().positive().optional(),
+    notes: z.array(z.string()).optional(),
+});
+export const CompactAthleteSchema = z.object({
+    name: z.string().min(1),
+    event: z.string().min(1),
+    eventDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in ISO format: YYYY-MM-DD"),
+    paces: AthletePacesSchema,
+    zones: AthleteZonesSchema.optional(),
+    constraints: AthleteConstraintsSchema.optional(),
+    unit: DistanceUnitSchema.default("km"),
+    firstDayOfWeek: FirstDayOfWeekSchema.default("monday"),
+});
+// ============================================================================
+// Training Phases
+// ============================================================================
+/**
+ * Week range can be "1-3" or [1, 2, 3]
+ */
+export const WeekRangeSchema = z.union([
+    z.string().regex(/^\d+-\d+$/, "Week range must be in format 'start-end' (e.g., '1-3')"),
+    z.array(z.number().int().positive()),
+]);
+export const CompactPhaseSchema = z.object({
+    name: z.string().min(1),
+    weeks: WeekRangeSchema,
+    focus: z.string().min(1),
+    keyWorkouts: z.array(z.string()).optional(),
+});
+// ============================================================================
+// Weekly Schedule
+// ============================================================================
+/**
+ * Workout reference validation.
+ * Format: "template.id" or "template.id(param)" or "template.id(param1, param2)"
+ */
+export const WorkoutRefSchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9_.]+(?:\([^)]*\))?$/, "Workout reference must be in format 'template' or 'template(params)' (e.g., 'easy(30)', 'intervals.400(6)')");
+/**
+ * A day can have a single workout or multiple (for brick days).
+ */
+export const DayWorkoutSchema = z.union([WorkoutRefSchema, z.array(WorkoutRefSchema)]);
+/**
+ * Week schedule maps days to workouts.
+ */
+export const CompactWeekScheduleSchema = z.record(z.string(), // Day key: Mon, Tue, etc.
+DayWorkoutSchema);
+export const CompactWeekSchema = z.object({
+    week: z.number().int().positive(),
+    phase: z.string().min(1),
+    focus: z.string().optional(),
+    isRecoveryWeek: z.boolean().optional(),
+    targetHours: z.number().positive().optional(),
+    workouts: CompactWeekScheduleSchema,
+});
+// ============================================================================
+// Race Strategy
+// ============================================================================
+export const CompactRaceStrategySchema = z.object({
+    goalTime: z.string().optional(),
+    pacing: z
+        .object({
+        swim: z.string().optional(),
+        bike: z.string().optional(),
+        run: z.string().optional(),
+    })
+        .optional(),
+    nutrition: z.string().optional(),
+    notes: z.array(z.string()).optional(),
+});
+// ============================================================================
+// Complete Compact Plan
+// ============================================================================
+export const CompactPlanSchema = z
+    .object({
+    version: z.literal("2.0"),
+    athlete: CompactAthleteSchema,
+    phases: z.array(CompactPhaseSchema).min(1),
+    weeks: z.array(CompactWeekSchema).min(1),
+    raceStrategy: CompactRaceStrategySchema.optional(),
+})
+    .refine((plan) => {
+    // Validate that all weeks reference valid phases
+    const phaseNames = new Set(plan.phases.map((p) => p.name));
+    return plan.weeks.every((w) => phaseNames.has(w.phase));
+}, {
+    message: "All weeks must reference a valid phase name",
+    path: ["weeks"],
+})
+    .refine((plan) => {
+    // Validate week numbers are sequential and start from 1
+    const weekNumbers = plan.weeks
+        .map((w) => w.week)
+        .sort((a, b) => a - b);
+    for (let i = 0; i < weekNumbers.length; i++) {
+        if (weekNumbers[i] !== i + 1) {
+            return false;
+        }
+    }
+    return true;
+}, {
+    message: "Week numbers must be sequential starting from 1",
+    path: ["weeks"],
+});
+/**
+ * Validate a compact training plan against the schema.
+ */
+export function validateCompactPlan(data) {
+    const result = CompactPlanSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const errors = result.error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        message: issue.message,
+        code: issue.code,
+    }));
+    return { success: false, errors };
+}
+/**
+ * Validate a compact plan and throw an error if invalid.
+ */
+export function validateCompactPlanOrThrow(data) {
+    return CompactPlanSchema.parse(data);
+}
+/**
+ * Format validation errors into a human-readable string.
+ */
+export function formatCompactValidationErrors(errors) {
+    if (errors.length === 0)
+        return "No errors";
+    const lines = errors.map((e, i) => {
+        const path = e.path || "(root)";
+        return `  ${i + 1}. ${path}: ${e.message}`;
+    });
+    return `Validation failed with ${errors.length} error(s):\n${lines.join("\n")}`;
+}

package/dist/templates/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Templates Module
+ *
+ * Re-exports all template-related types and functions.
+ */
+export type { WorkoutTemplate, TemplateParam, TemplateParams, TemplateStep, TemplateIntervalSet, TemplateStructure, TemplateRegistry, InterpolationContext, ExpandedWorkout, ParamType, StepType, WorkoutCategory, MainSetElement, } from "./template.types.js";
+export { WorkoutTemplateSchema, TemplateParamSchema, TemplateParamsSchema, TemplateStepSchema, TemplateStructureSchema, validateTemplate, validateTemplateOrThrow, } from "./template.schema.js";
+export { loadTemplates, loadTemplatesFromArray, getTemplatesPath } from "./loader.js";
+export { parse as parseYaml, stringify as stringifyYaml } from "./yaml-parser.js";
+export { interpolate, interpolateObject, evaluateExpression, createContext, hasInterpolation, extractVariables, } from "./interpolate.js";

package/dist/templates/index.js

@@ -0,0 +1,13 @@
+/**
+ * Templates Module
+ *
+ * Re-exports all template-related types and functions.
+ */
+// Schema validation
+export { WorkoutTemplateSchema, TemplateParamSchema, TemplateParamsSchema, TemplateStepSchema, TemplateStructureSchema, validateTemplate, validateTemplateOrThrow, } from "./template.schema.js";
+// Loader
+export { loadTemplates, loadTemplatesFromArray, getTemplatesPath } from "./loader.js";
+// YAML utilities
+export { parse as parseYaml, stringify as stringifyYaml } from "./yaml-parser.js";
+// Interpolation
+export { interpolate, interpolateObject, evaluateExpression, createContext, hasInterpolation, extractVariables, } from "./interpolate.js";

package/dist/templates/interpolate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Variable Interpolation Engine
+ *
+ * Replaces ${variable} patterns in template strings with actual values.
+ * Supports:
+ * - Simple variables: ${paces.easy} → "5:30/km"
+ * - Math expressions: ${10 + (reps * 3)} → "22"
+ * - Nested access: ${zones.hr.lthr} → "170"
+ */
+import type { InterpolationContext } from "./template.types.js";
+/**
+ * Evaluate a simple math expression with variable substitution.
+ *
+ * This uses a safe evaluation approach that only allows basic math operations.
+ * Variables in the expression are first replaced with their values from context.
+ *
+ * @example
+ * evaluateExpression("10 + (reps * 3)", { reps: 4 }) // 22
+ */
+export declare function evaluateExpression(expr: string, context: InterpolationContext): string | number;
+/**
+ * Interpolate all ${variable} patterns in a string.
+ *
+ * @example
+ * interpolate("Run ${duration} min @ ${paces.easy}", {
+ *   duration: 30,
+ *   paces: { easy: "5:30/km" }
+ * })
+ * // "Run 30 min @ 5:30/km"
+ */
+export declare function interpolate(template: string, context: InterpolationContext): string;
+/**
+ * Interpolate all string values in an object recursively.
+ */
+export declare function interpolateObject<T>(obj: T, context: InterpolationContext): T;
+/**
+ * Create an interpolation context from a compact plan's athlete data.
+ */
+export declare function createContext(paces: Record<string, string | undefined>, zones?: InterpolationContext["zones"], params?: Record<string, unknown>): InterpolationContext;
+/**
+ * Check if a string contains any interpolation markers.
+ */
+export declare function hasInterpolation(str: string): boolean;
+/**
+ * Extract all variable names from a template string.
+ *
+ * @example
+ * extractVariables("Run ${duration} min @ ${paces.easy}")
+ * // ["duration", "paces.easy"]
+ */
+export declare function extractVariables(template: string): string[];