@dgpholdings/greatoak-shared 1.2.86 → 1.2.88

package/dist/utils/constellation/stars/recovery.js

@@ -0,0 +1,169 @@
+"use strict";
+// utils/constellation/stars/recovery.ts — Recovery Star (the crown)
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Recovery Star (the crown)
+ * ============================================================================
+ *
+ * Recovery intelligence: does the user let trained muscles fully recover, not
+ * just grind through fatigue? Brightness reflects how many RECOVERY CYCLES the
+ * user achieved in the trailing window.
+ *
+ * ZONE-BASED (not all-or-nothing). The body is split into three independent
+ * recovery zones — upper, lower, core. A split-routine lifter (e.g. Push/Pull/
+ * Legs) almost never has the WHOLE body fresh at once, yet is recovering
+ * intelligently zone by zone; an all-muscles-at-once rule would wrongly score
+ * them near zero. So we count cycles PER ZONE.
+ *
+ * A zone "cycle" = a transition where that zone goes fatigued -> recovered
+ * (a multi-day rest counts once). Crucially, a zone only earns cycles if the
+ * user actually TRAINS it in the window — an untrained zone is "always fresh"
+ * and must not hand out free recovery credit. Total cycles = sum across the
+ * zones the user trains, capped at the level target.
+ *
+ * Reads PRE-SCORED sessions from context (orchestrator scores once); builds the
+ * enriched history the fatigue model consumes, then replays the model across
+ * each day of the window. This star never calls the scoring engine itself.
+ *
+ * Thresholds come from RECOVERY_THRESHOLDS[level].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryStar = void 0;
+const computeMuscleFatigueMap_1 = require("../../scoringWorkout/computeMuscleFatigueMap");
+const levelThresholds_1 = require("../levelThresholds");
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Recovery zones — independent regions that recover on their own clocks. Each
+ * lists the major muscle keys that define it. A zone is "recovered" on a given
+ * day when ALL of its listed muscles are below the fatigue threshold (or carry
+ * no tracked fatigue).
+ */
+const RECOVERY_ZONES = {
+    upper: [
+        "pectoralis-major",
+        "latissimus-dorsi",
+        "deltoids-anterior",
+        "tricep-brachii-long",
+    ],
+    lower: ["quadriceps", "hamstrings", "glutes-maximus"],
+    core: ["abs-upper", "abs-lower", "obliques"],
+};
+const ZONE_NAMES = Object.keys(RECOVERY_ZONES);
+// --- Enriched history (feed for the fatigue map) ----------------------------
+/**
+ * Turn the orchestrator's pre-scored sessions into the fatigue model's inputs.
+ * Also records which zones the user actually trained (any tracked fatigue in a
+ * zone's muscles at any point), so untrained zones earn no recovery credit.
+ */
+function buildEnrichedHistory(ctx) {
+    var _a;
+    var _b;
+    const exercises = {};
+    const byExercise = {};
+    const trainedMuscles = new Set();
+    for (const session of ctx.scoredSessions) {
+        for (const ex of session.exercises) {
+            if (ex.score === null)
+                continue;
+            const exercise = ctx.exerciseCatalog[ex.exerciseId];
+            if (!exercise)
+                continue;
+            if (!exercises[ex.exerciseId]) {
+                exercises[ex.exerciseId] = {
+                    primaryMuscles: exercise.primaryMuscles,
+                    secondaryMuscles: exercise.secondaryMuscles,
+                };
+            }
+            for (const m of exercise.primaryMuscles)
+                trainedMuscles.add(m);
+            for (const m of exercise.secondaryMuscles)
+                trainedMuscles.add(m);
+            ((_a = byExercise[_b = ex.exerciseId]) !== null && _a !== void 0 ? _a : (byExercise[_b] = [])).push({
+                score: ex.score,
+                recordDate: session.date,
+                muscleScores: ex.muscleScores,
+            });
+        }
+    }
+    const scoreHistory = Object.entries(byExercise).map(([exerciseId, recordScore]) => ({ exerciseId, recordScore }));
+    // A zone is "trained" if the user touched any of its muscles in the window.
+    const trainedZones = new Set();
+    for (const zone of ZONE_NAMES) {
+        if (RECOVERY_ZONES[zone].some((m) => trainedMuscles.has(m))) {
+            trainedZones.add(zone);
+        }
+    }
+    return { exercises, scoreHistory, trainedZones };
+}
+/** Is a single zone recovered (all its muscles below threshold) on a day's map? */
+function isZoneRecovered(zone, fatigueMap, recoveredBelow) {
+    for (const muscle of RECOVERY_ZONES[zone]) {
+        const entry = fatigueMap[muscle];
+        if (entry && entry.fatigue >= recoveredBelow)
+            return false;
+    }
+    return true;
+}
+// --- Detail builders --------------------------------------------------------
+function cyclesMeasure(cycles, target) {
+    return {
+        value: cycles,
+        unit: "cycles",
+        display: {
+            translationKey: "constellation.recovery.measure.cycles",
+            params: [Math.min(cycles, target), target],
+        },
+    };
+}
+function buildGap(cycles, target, hasHistory) {
+    if (!hasHistory)
+        return { translationKey: "constellation.recovery.gap.noData" };
+    if (cycles >= target)
+        return { translationKey: "constellation.recovery.gap.full" };
+    return {
+        translationKey: "constellation.recovery.gap.moreCycles",
+        params: [target - cycles],
+    };
+}
+// --- Evaluator --------------------------------------------------------------
+function evaluateRecovery(ctx) {
+    const { targetCycles, windowDays, recoveredBelow } = levelThresholds_1.RECOVERY_THRESHOLDS[ctx.level];
+    const { exercises, scoreHistory, trainedZones } = buildEnrichedHistory(ctx);
+    const hasHistory = scoreHistory.length > 0;
+    const startDay = Math.floor((ctx.now - windowDays * MS_PER_DAY) / MS_PER_DAY);
+    const endDay = Math.floor(ctx.now / MS_PER_DAY);
+    // Per-zone cycle counting. Only zones the user trains can earn cycles.
+    // Seed each trained zone as "recovered" (pre-window baseline = fresh), so the
+    // first cycle is only credited after the zone has actually been fatigued.
+    let totalCycles = 0;
+    for (const zone of trainedZones) {
+        let wasRecovered = true;
+        for (let d = startDay; d <= endDay; d++) {
+            const dayDate = new Date(d * MS_PER_DAY + MS_PER_DAY / 2); // midday
+            const map = (0, computeMuscleFatigueMap_1.computeMuscleFatigueMap)(exercises, scoreHistory, ctx.user, dayDate);
+            const recovered = isZoneRecovered(zone, map, recoveredBelow);
+            if (recovered && !wasRecovered)
+                totalCycles++;
+            wasRecovered = recovered;
+        }
+    }
+    const brightness = Math.min(100, (totalCycles / targetCycles) * 100);
+    return {
+        brightness,
+        detail: {
+            currentState: cyclesMeasure(totalCycles, targetCycles),
+            target: cyclesMeasure(targetCycles, targetCycles),
+            gap: buildGap(totalCycles, targetCycles, hasHistory),
+        },
+    };
+}
+// --- Definition -------------------------------------------------------------
+exports.recoveryStar = {
+    id: "recovery",
+    displayName: { translationKey: "constellation.recovery.name" },
+    color: "#c8d8ff", // silver-white — moonlight, the quiet phase
+    figurePosition: "crown",
+    objective: { translationKey: "constellation.recovery.objective" },
+    rationale: { translationKey: "constellation.recovery.rationale" },
+    evaluate: evaluateRecovery,
+};

package/dist/utils/constellation/stars/recovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/constellation/stars/recovery.test.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/stars/recovery.test.ts
+const starFoundation_1 = require("../starFoundation");
+const recovery_1 = require("../stars/recovery");
+const vitest_1 = require("vitest");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+// Exercises with muscles in specific zones (upper: pec/lat; lower: quad/ham/glute; core: abs).
+const catalog = {
+    bench: {
+        exerciseId: "bench",
+        name: "Bench",
+        primaryMuscles: ["pectoralis-major"],
+        secondaryMuscles: ["deltoids-anterior"],
+        difficultyLevel: 3,
+        movementPattern: "push_horizontal",
+        status: "active",
+    },
+    squat: {
+        exerciseId: "squat",
+        name: "Squat",
+        primaryMuscles: ["quadriceps"],
+        secondaryMuscles: ["glutes-maximus"],
+        difficultyLevel: 3,
+        movementPattern: "squat",
+        status: "active",
+    },
+    row: {
+        exerciseId: "row",
+        name: "Row",
+        primaryMuscles: ["latissimus-dorsi"],
+        secondaryMuscles: [],
+        difficultyLevel: 3,
+        movementPattern: "pull_horizontal",
+        status: "active",
+    },
+};
+const scoredEx = (id, muscles) => ({
+    exerciseId: id,
+    score: 75,
+    muscleScores: Object.fromEntries(muscles.map((m) => [m, 70])),
+});
+const ctx = (scoredSessions, level = 1) => ({
+    sessions: [],
+    scoredSessions,
+    exerciseCatalog: catalog,
+    user: { weightKg: 80, gender: "male" },
+    now: NOW,
+    level,
+});
+(0, vitest_1.describe)("recovery — no data", () => {
+    (0, vitest_1.it)("empty history → noData gap, 0 brightness", () => {
+        const r = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx([]));
+        (0, vitest_1.expect)(r.brightness).toBe(0);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.recovery.gap.noData");
+    });
+});
+(0, vitest_1.describe)("recovery — earns cycles from trained zones", () => {
+    (0, vitest_1.it)("a split lifter (alternating zones, spaced) earns recovery cycles", () => {
+        // train each zone, leave gaps so it recovers, train again → transitions
+        const s = [];
+        const sched = [
+            [40, "bench", ["pectoralis-major"]],
+            [37, "row", ["latissimus-dorsi"]],
+            [34, "squat", ["quadriceps"]],
+            [27, "bench", ["pectoralis-major"]],
+            [24, "row", ["latissimus-dorsi"]],
+            [21, "squat", ["quadriceps"]],
+            [14, "bench", ["pectoralis-major"]],
+            [11, "row", ["latissimus-dorsi"]],
+            [8, "squat", ["quadriceps"]],
+        ];
+        for (const [d, id, m] of sched)
+            s.push({ date: day(d), exercises: [scoredEx(id, m)] });
+        const r = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx(s));
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+        (0, vitest_1.expect)(r.currentState.value).toBeGreaterThanOrEqual(1);
+    });
+});
+(0, vitest_1.describe)("recovery — penalises the daily grinder", () => {
+    (0, vitest_1.it)("training all zones every day → low/zero recovery", () => {
+        const s = [];
+        for (let d = 40; d >= 0; d--) {
+            s.push({
+                date: day(d),
+                exercises: [
+                    scoredEx("bench", ["pectoralis-major"]),
+                    scoredEx("squat", ["quadriceps"]),
+                    scoredEx("row", ["latissimus-dorsi"]),
+                ],
+            });
+        }
+        const r = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx(s));
+        (0, vitest_1.expect)(r.brightness).toBeLessThan(50);
+    });
+});
+(0, vitest_1.describe)("recovery — untrained zones earn no free credit", () => {
+    (0, vitest_1.it)("training only upper does not manufacture lower/core cycles", () => {
+        // only upper trained, spaced so it cycles a few times
+        const s = [];
+        for (const d of [40, 33, 26, 19, 12, 5])
+            s.push({
+                date: day(d),
+                exercises: [scoredEx("bench", ["pectoralis-major"])],
+            });
+        const r = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx(s));
+        // cycles come ONLY from the upper zone; if lower/core counted freely,
+        // brightness would be far higher. Bounded sanity check:
+        (0, vitest_1.expect)(r.currentState.value).toBeGreaterThanOrEqual(1);
+        (0, vitest_1.expect)(r.brightness).toBeLessThanOrEqual(100);
+    });
+});
+(0, vitest_1.describe)("recovery — level scaling", () => {
+    (0, vitest_1.it)("same history is dimmer at L2 (needs more cycles)", () => {
+        const s = [];
+        const sched = [
+            [40, "bench", ["pectoralis-major"]],
+            [34, "squat", ["quadriceps"]],
+            [27, "bench", ["pectoralis-major"]],
+            [21, "squat", ["quadriceps"]],
+            [14, "bench", ["pectoralis-major"]],
+            [8, "squat", ["quadriceps"]],
+        ];
+        for (const [d, id, m] of sched)
+            s.push({ date: day(d), exercises: [scoredEx(id, m)] });
+        const l1 = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx(s, 1));
+        const l2 = (0, starFoundation_1.resolveStar)(recovery_1.recoveryStar, ctx(s, 2));
+        (0, vitest_1.expect)(l2.brightness).toBeLessThanOrEqual(l1.brightness);
+    });
+});

package/dist/utils/constellation/strengthStar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/constellation/strengthStar.test.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// shared/src/utils/constellation/__tests__/strengthStars.test.ts
+const starFoundation_1 = require("./starFoundation");
+const push_1 = require("./stars/push");
+const pull_1 = require("./stars/pull");
+const lowerBody_1 = require("./stars/lowerBody");
+const vitest_1 = require("vitest");
+const NOW = Date.UTC(2026, 5, 1);
+const day = (d) => NOW - d * 86400000;
+const wr = (kg, reps) => ({ type: "weight-reps", kg, reps, isDone: true, isStrictMode: false });
+const ro = (reps, aux = "0") => ({
+    type: "reps-only",
+    reps,
+    auxWeightKg: aux,
+    isDone: true,
+    isStrictMode: false,
+});
+const ex = (id, mp, over = {}) => ({
+    exerciseId: id,
+    name: id,
+    primaryMuscles: [],
+    secondaryMuscles: [],
+    difficultyLevel: 3,
+    movementPattern: mp,
+    status: "active",
+    ...over,
+});
+const catalog = {
+    bench: ex("bench", "push_horizontal"),
+    ohp: ex("ohp", "push_vertical"),
+    row: ex("row", "pull_horizontal"),
+    pullup: ex("pullup", "pull_vertical", {
+        weightMultiplier: { male: 1.0, female: 0.95, default: 0.97 },
+    }),
+    squat: ex("squat", "squat"),
+    rdl: ex("rdl", "hinge"),
+    lunge: ex("lunge", "lunge"),
+    pistol: ex("pistol", "squat", {
+        weightMultiplier: { male: 0.95, female: 0.9, default: 0.9 },
+    }),
+};
+const ctx = (sessions, user = {}, level = 1) => ({
+    sessions,
+    scoredSessions: [],
+    exerciseCatalog: catalog,
+    user: { weightKg: 80, gender: "male", ...user },
+    now: NOW,
+    level,
+});
+(0, vitest_1.describe)("push star — pattern filtering & thresholds", () => {
+    (0, vitest_1.it)("lights from a strong bench (L1 0.60 male)", () => {
+        const r = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("60", "5")] }],
+            },
+        ]));
+        // 60x5 → 70/80 = 0.875 vs 0.60 → capped 100
+        (0, vitest_1.expect)(r.brightness).toBe(100);
+        (0, vitest_1.expect)(r.tier).toBe(3);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.push.gap.full");
+    });
+    (0, vitest_1.it)("counts vertical push (OHP) too", () => {
+        const r = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "ohp", records: [wr("40", "5")] }],
+            },
+        ]));
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+    });
+    (0, vitest_1.it)("ignores pull movements", () => {
+        const r = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "row", records: [wr("100", "5")] }],
+            },
+        ]));
+        (0, vitest_1.expect)(r.brightness).toBe(0);
+    });
+    (0, vitest_1.it)("partial brightness below threshold gives a toGo gap", () => {
+        const r = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("25", "5")] }],
+            },
+        ]));
+        // 25x5 → 29.2/80 = 0.365 vs 0.60 → ~61%
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+        (0, vitest_1.expect)(r.brightness).toBeLessThan(100);
+        (0, vitest_1.expect)(r.gap.translationKey).toBe("constellation.push.gap.toGo");
+    });
+});
+(0, vitest_1.describe)("strength — gendered thresholds", () => {
+    (0, vitest_1.it)("female has a lower bar (same lift lights more)", () => {
+        const sessions = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("30", "5")] }],
+            },
+        ];
+        const male = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, { gender: "male" }));
+        const female = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, { gender: "female" }));
+        (0, vitest_1.expect)(female.brightness).toBeGreaterThanOrEqual(male.brightness);
+    });
+    (0, vitest_1.it)("unmentioned gender resolves to the male (higher) bar", () => {
+        const sessions = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("30", "5")] }],
+            },
+        ];
+        const male = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, { gender: "male" }));
+        const unmentioned = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, { gender: undefined }));
+        (0, vitest_1.expect)(unmentioned.brightness).toBe(male.brightness);
+    });
+});
+(0, vitest_1.describe)("strength — level scaling", () => {
+    (0, vitest_1.it)("a fixed lift is dimmer at L2 than L1 (higher bar)", () => {
+        const sessions = [
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "bench", records: [wr("40", "5")] }],
+            },
+        ];
+        // 40x5 → 46.7/80 = 0.583. L1 push 0.60 → ~97%; L2 push 1.0 → ~58%
+        const l1 = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, {}, 1));
+        const l2 = (0, starFoundation_1.resolveStar)(push_1.pushStar, ctx(sessions, {}, 2));
+        (0, vitest_1.expect)(l2.brightness).toBeLessThan(l1.brightness);
+    });
+});
+(0, vitest_1.describe)("pull star", () => {
+    (0, vitest_1.it)("lights from rows", () => {
+        const r = (0, starFoundation_1.resolveStar)(pull_1.pullStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "row", records: [wr("50", "5")] }],
+            },
+        ]));
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+    });
+    (0, vitest_1.it)("bodyweight pull-ups light via weightMultiplier", () => {
+        const r = (0, starFoundation_1.resolveStar)(pull_1.pullStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "pullup", records: [ro("8")] }],
+            },
+        ]));
+        (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+    });
+});
+(0, vitest_1.describe)("lowerBody star — combined patterns & home reachability", () => {
+    (0, vitest_1.it)("squat, hinge, and lunge all count", () => {
+        for (const id of ["squat", "rdl", "lunge"]) {
+            const r = (0, starFoundation_1.resolveStar)(lowerBody_1.lowerBodyStar, ctx([
+                {
+                    date: day(2),
+                    exercises: [{ exerciseId: id, records: [wr("80", "5")] }],
+                },
+            ]));
+            (0, vitest_1.expect)(r.brightness).toBeGreaterThan(0);
+        }
+    });
+    (0, vitest_1.it)("HOME user reaches full lower body via bodyweight pistol squats", () => {
+        const r = (0, starFoundation_1.resolveStar)(lowerBody_1.lowerBodyStar, ctx([
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "pistol", records: [ro("8")] }],
+            },
+        ], { weightKg: 75 }));
+        // pistol 0.95*75=71.25; 1RM=71.25*(1+8/30)=90.25; /75=1.20 vs L1 1.0 → 100
+        (0, vitest_1.expect)(r.brightness).toBe(100);
+    });
+    (0, vitest_1.it)("takes the best across the three patterns", () => {
+        const sessions = [
+            {
+                date: day(5),
+                exercises: [{ exerciseId: "squat", records: [wr("50", "5")] }],
+            },
+            {
+                date: day(2),
+                exercises: [{ exerciseId: "rdl", records: [wr("100", "5")] }],
+            },
+        ];
+        const r = (0, starFoundation_1.resolveStar)(lowerBody_1.lowerBodyStar, ctx(sessions));
+        // rdl 100x5 → 116.7/80 = 1.46 → capped 100
+        (0, vitest_1.expect)(r.brightness).toBe(100);
+    });
+});

package/dist/utils/constellation/strengthStarHelpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Strength Star Helpers
+ * ============================================================================
+ *
+ * Shared by the three strength stars (push, pull, lowerBody). Each star is a
+ * thin definition that names its movement patterns and its threshold key; this
+ * helper does the rest: filter the catalog to those patterns, compute the
+ * normalised load, and turn the ratio into brightness + i18n detail.
+ *
+ * Thresholds come from STRENGTH_THRESHOLDS[key][level], resolved by sex.
+ */
+import type { TUserMetric } from "../../types";
+import { type ISexThreshold } from "./levelThresholds";
+import type { TStarContext, TStarEvaluation, TLocalizedText } from "./types";
+/** Rolling window for strength PRs: 8 weeks. */
+export declare const STRENGTH_WINDOW_DAYS = 56;
+/** Resolve the threshold ratio for this user. unmentioned -> male (higher bar). */
+export declare function resolveThreshold(threshold: ISexThreshold, gender: string | undefined): number;
+/** User bodyweight with fallback. */
+export declare function userBodyweight(user: Partial<TUserMetric>): number;
+/**
+ * Brightness from current ratio vs threshold, graded & continuous.
+ *   brightness = (currentRatio / thresholdRatio) * 100, capped at 100.
+ * Faint from the first rep; full at threshold. No wall.
+ */
+export declare function ratioToBrightness(currentRatio: number, thresholdRatio: number): number;
+/**
+ * Build the "what's missing" gap text. At/above threshold -> a "full" message;
+ * otherwise the remaining kg on the user's best lift to reach the threshold.
+ */
+export declare function buildGap(gapKeyPrefix: string, currentRatio: number, thresholdRatio: number, bodyweightKg: number): TLocalizedText;
+/**
+ * The full strength-star evaluation, shared by push/pull/lowerBody.
+ *
+ * @param ctx               star context (sessions, catalog, user, now, level)
+ * @param strengthKey       which STRENGTH_THRESHOLDS row to use ("push" | "pull" | "lowerBody")
+ * @param matchingPatterns  movement patterns this star counts
+ * @param gapKeyPrefix      translation-key prefix (e.g. "constellation.push")
+ */
+export declare function evaluateStrengthStar(ctx: TStarContext, strengthKey: "push" | "pull" | "lowerBody", matchingPatterns: string[], gapKeyPrefix: string): TStarEvaluation;

package/dist/utils/constellation/strengthStarHelpers.js

@@ -0,0 +1,104 @@
+"use strict";
+// utils/constellation/strengthStarHelpers.ts — Strength Star Helpers
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Strength Star Helpers
+ * ============================================================================
+ *
+ * Shared by the three strength stars (push, pull, lowerBody). Each star is a
+ * thin definition that names its movement patterns and its threshold key; this
+ * helper does the rest: filter the catalog to those patterns, compute the
+ * normalised load, and turn the ratio into brightness + i18n detail.
+ *
+ * Thresholds come from STRENGTH_THRESHOLDS[key][level], resolved by sex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRENGTH_WINDOW_DAYS = void 0;
+exports.resolveThreshold = resolveThreshold;
+exports.userBodyweight = userBodyweight;
+exports.ratioToBrightness = ratioToBrightness;
+exports.buildGap = buildGap;
+exports.evaluateStrengthStar = evaluateStrengthStar;
+const computeNormalisedLoad_1 = require("./computeNormalisedLoad");
+const levelThresholds_1 = require("./levelThresholds");
+/** Rolling window for strength PRs: 8 weeks. */
+exports.STRENGTH_WINDOW_DAYS = 56;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_BODYWEIGHT_KG = 70;
+/** Resolve the threshold ratio for this user. unmentioned -> male (higher bar). */
+function resolveThreshold(threshold, gender) {
+    return gender === "female" ? threshold.female : threshold.male;
+}
+/** User bodyweight with fallback. */
+function userBodyweight(user) {
+    const bw = user.weightKg;
+    return bw && bw > 0 ? bw : DEFAULT_BODYWEIGHT_KG;
+}
+/**
+ * Brightness from current ratio vs threshold, graded & continuous.
+ *   brightness = (currentRatio / thresholdRatio) * 100, capped at 100.
+ * Faint from the first rep; full at threshold. No wall.
+ */
+function ratioToBrightness(currentRatio, thresholdRatio) {
+    if (thresholdRatio <= 0)
+        return 0;
+    return Math.min(100, (currentRatio / thresholdRatio) * 100);
+}
+/** Build a bodyweight-ratio measure for the detail panel. */
+function bwRatioMeasure(ratio) {
+    const rounded = Math.round(ratio * 100) / 100;
+    return {
+        value: rounded,
+        unit: "bw_ratio",
+        display: {
+            translationKey: "constellation.measure.bwRatio",
+            params: [rounded],
+        },
+    };
+}
+/**
+ * Build the "what's missing" gap text. At/above threshold -> a "full" message;
+ * otherwise the remaining kg on the user's best lift to reach the threshold.
+ */
+function buildGap(gapKeyPrefix, currentRatio, thresholdRatio, bodyweightKg) {
+    if (currentRatio >= thresholdRatio) {
+        return { translationKey: `${gapKeyPrefix}.gap.full` };
+    }
+    const remainingKg = Math.max(0, Math.round((thresholdRatio - currentRatio) * bodyweightKg));
+    return {
+        translationKey: `${gapKeyPrefix}.gap.toGo`,
+        params: [remainingKg],
+    };
+}
+/**
+ * The full strength-star evaluation, shared by push/pull/lowerBody.
+ *
+ * @param ctx               star context (sessions, catalog, user, now, level)
+ * @param strengthKey       which STRENGTH_THRESHOLDS row to use ("push" | "pull" | "lowerBody")
+ * @param matchingPatterns  movement patterns this star counts
+ * @param gapKeyPrefix      translation-key prefix (e.g. "constellation.push")
+ */
+function evaluateStrengthStar(ctx, strengthKey, matchingPatterns, gapKeyPrefix) {
+    const bw = userBodyweight(ctx.user);
+    const gender = ctx.user.gender;
+    const thresholdRatio = resolveThreshold(levelThresholds_1.STRENGTH_THRESHOLDS[strengthKey][ctx.level], gender);
+    // Build the matching-exercise id set from the catalog by movement pattern.
+    const patternSet = new Set(matchingPatterns);
+    const matchingIds = new Set();
+    for (const id of Object.keys(ctx.exerciseCatalog)) {
+        const ex = ctx.exerciseCatalog[id];
+        if (patternSet.has(ex.movementPattern))
+            matchingIds.add(id);
+    }
+    const windowStart = ctx.now - exports.STRENGTH_WINDOW_DAYS * MS_PER_DAY;
+    const load = (0, computeNormalisedLoad_1.computeNormalisedLoad)(matchingIds, ctx.sessions, ctx.exerciseCatalog, bw, gender, windowStart, ctx.now);
+    const brightness = ratioToBrightness(load.ratio, thresholdRatio);
+    return {
+        brightness,
+        detail: {
+            currentState: bwRatioMeasure(load.ratio),
+            target: bwRatioMeasure(thresholdRatio),
+            gap: buildGap(gapKeyPrefix, load.ratio, thresholdRatio, bw),
+        },
+    };
+}