@dgpholdings/greatoak-shared 1.2.86 → 1.2.87

package/dist/utils/constellation/evaluateConstellation.js

@@ -0,0 +1,135 @@
+"use strict";
+// utils/constellation/evaluateConstellation.ts — Orchestrator
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Orchestrator
+ * ============================================================================
+ *
+ * The single entry point. Takes raw input (sessions, catalog, user, now) and
+ * returns a render-ready TConstellationState: six resolved stars plus the
+ * figure aggregate that drives the silhouette's aura.
+ *
+ * Purely live — everything is recomputed from raw records on every call.
+ * Nothing is persisted; the same input always yields the same output.
+ *
+ * Scoring happens ONCE here: every (session, exercise) is scored a single time
+ * into scoredSessions, which both quality and recovery read — no double work.
+ *
+ * Runs server-side (Lambda) so the evaluation logic can evolve independently of
+ * app releases.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateConstellation = evaluateConstellation;
+const scoringWorkout_1 = require("../scoringWorkout");
+const starFoundation_1 = require("./starFoundation");
+const levelThresholds_1 = require("./levelThresholds");
+const consistency_1 = require("./stars/consistency");
+const quality_1 = require("./stars/quality");
+const push_1 = require("./stars/push");
+const pull_1 = require("./stars/pull");
+const lowerBody_1 = require("./stars/lowerBody");
+const recovery_1 = require("./stars/recovery");
+/**
+ * The six stars, in figure reading order: heart (consistency) and core
+ * (quality) first, then the limbs (push/pull/lowerBody), then the crown
+ * (recovery). Appending a level/goal star later = adding to this list.
+ */
+const STAR_DEFINITIONS = [
+    consistency_1.consistencyStar,
+    quality_1.qualityStar,
+    push_1.pushStar,
+    pull_1.pullStar,
+    lowerBody_1.lowerBodyStar,
+    recovery_1.recoveryStar,
+];
+/**
+ * Score every (session, exercise) exactly once. Shared by quality (uses
+ * `score`) and recovery (uses `muscleScores`). An exercise missing from the
+ * catalog, or one the engine cannot score, yields score=null + empty muscles
+ * and is skipped downstream.
+ */
+function scoreAllSessions(input) {
+    var _a;
+    const { sessions, exerciseCatalog, user, now } = input;
+    const scored = [];
+    for (const session of sessions) {
+        if (session.date > now)
+            continue; // ignore future-dated sessions
+        const exercises = [];
+        for (const ex of session.exercises) {
+            const exercise = exerciseCatalog[ex.exerciseId];
+            if (!exercise) {
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: null,
+                    muscleScores: {},
+                });
+                continue;
+            }
+            try {
+                const result = (0, scoringWorkout_1.calculateExerciseScoreV2)({
+                    exercise,
+                    record: ex.records,
+                    user: user,
+                });
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: typeof result.score === "number" ? result.score : null,
+                    muscleScores: (_a = result.muscleScores) !== null && _a !== void 0 ? _a : {},
+                });
+            }
+            catch (_b) {
+                exercises.push({
+                    exerciseId: ex.exerciseId,
+                    score: null,
+                    muscleScores: {},
+                });
+            }
+        }
+        scored.push({ date: session.date, exercises });
+    }
+    return scored;
+}
+/** Build the figure aggregate from the resolved stars. */
+function computeFigure(stars) {
+    if (stars.length === 0) {
+        return { auraIntensity: 0, fullStarCount: 0 };
+    }
+    const totalBrightness = stars.reduce((sum, s) => sum + s.brightness, 0);
+    const auraIntensity = totalBrightness / stars.length;
+    const fullStarCount = stars.filter((s) => s.tier === 3).length;
+    return {
+        auraIntensity: Math.round(auraIntensity * 10) / 10,
+        fullStarCount,
+    };
+}
+/**
+ * Evaluate the full constellation from raw input.
+ *
+ * @param input  sessions + exercise catalog (UNFILTERED) + user + now + level
+ * @returns      render-ready state: six stars + figure aggregate
+ * @throws       if `now` is not a finite timestamp
+ */
+function evaluateConstellation(input) {
+    if (!Number.isFinite(input.now)) {
+        throw new Error("evaluateConstellation: `now` must be a finite UNIX ms timestamp");
+    }
+    const level = (0, levelThresholds_1.clampLevel)(input.currentLevel);
+    const scoredSessions = scoreAllSessions(input);
+    const ctx = {
+        sessions: input.sessions,
+        scoredSessions,
+        exerciseCatalog: input.exerciseCatalog,
+        user: input.user,
+        now: input.now,
+        level,
+    };
+    const stars = STAR_DEFINITIONS.map((def) => (0, starFoundation_1.resolveStar)(def, ctx));
+    const figure = computeFigure(stars);
+    return {
+        stars,
+        figure,
+        currentLevel: level,
+        evaluatedAt: new Date(input.now).toISOString(),
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Public API
+ * ============================================================================
+ *
+ * The constellation module's surface. Consumers (the Lambda, tests) import from
+ * here, not from internal files.
+ *
+ *   import { evaluateConstellation } from ".../constellation";
+ *   const state = evaluateConstellation({ sessions, exerciseCatalog, user, now });
+ *
+ * Everything else (individual stars, helpers, the normalised-load math) is an
+ * implementation detail and intentionally not re-exported.
+ */
+export { evaluateConstellation } from "./evaluateConstellation";
+export type { TConstellationInput, TConstellationState, TConstellationFigure, TResolvedStar, TStarId, TStarTier, TFigurePosition, TStarMeasure, TLocalizedText, TSessionRecord, } from "./types";
+export { TIER_THRESHOLDS, deriveTier } from "./starFoundation";

package/dist/utils/constellation/index.js

@@ -0,0 +1,26 @@
+"use strict";
+// utils/constellation/index.ts — Public API
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Public API
+ * ============================================================================
+ *
+ * The constellation module's surface. Consumers (the Lambda, tests) import from
+ * here, not from internal files.
+ *
+ *   import { evaluateConstellation } from ".../constellation";
+ *   const state = evaluateConstellation({ sessions, exerciseCatalog, user, now });
+ *
+ * Everything else (individual stars, helpers, the normalised-load math) is an
+ * implementation detail and intentionally not re-exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveTier = exports.TIER_THRESHOLDS = exports.evaluateConstellation = void 0;
+// The single entry point.
+var evaluateConstellation_1 = require("./evaluateConstellation");
+Object.defineProperty(exports, "evaluateConstellation", { enumerable: true, get: function () { return evaluateConstellation_1.evaluateConstellation; } });
+// Tier thresholds are exported so the app can label tiers consistently with
+// the server (dormant / faint / rising / full) without hard-coding the cutoffs.
+var starFoundation_1 = require("./starFoundation");
+Object.defineProperty(exports, "TIER_THRESHOLDS", { enumerable: true, get: function () { return starFoundation_1.TIER_THRESHOLDS; } });
+Object.defineProperty(exports, "deriveTier", { enumerable: true, get: function () { return starFoundation_1.deriveTier; } });

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

@@ -0,0 +1,99 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Level Threshold Ladder
+ * ============================================================================
+ *
+ * The single source of truth for what "full" means at each level, for every
+ * star. Stars read their row by the user's current level; nothing about a
+ * threshold is hard-coded inside star logic.
+ *
+ * Design intent (coach's calibration):
+ *   Level 1 = committed beginner   (reachable in ~2-3 months of honest work)
+ *   Level 2 = solid intermediate   (~6-12 months)
+ *   Level 3 = advanced             (multi-year, genuinely strong)
+ *
+ * Strength thresholds are estimated-1RM as a ratio of bodyweight, by sex.
+ * `unmentioned` gender is resolved to `male` (the higher bar) elsewhere, so a
+ * star is never too-easily lit for an unspecified profile.
+ *
+ * Calibration note (v1.1): these are first-pass values to be tuned against real
+ * brightness distributions post-launch. L1 pull was lowered from 0.65 -> 0.50
+ * because 0.65x BW pull excluded the large beginner segment that cannot yet do
+ * bodyweight pull-ups; L1 push eased 0.75 -> 0.60 so the first milestone lands
+ * in ~6-8 weeks rather than feeling intermediate. Lower body held at 1.0x — the
+ * bodyweight-load path lets home users reach it via pistol squats/lunges.
+ *
+ * Adding a level later = adding a key to each record. Star code does not change.
+ * The future goal layer can multiply these per-goal without touching this file.
+ */
+export type TLevel = 1 | 2 | 3;
+export declare const MAX_LEVEL: TLevel;
+export interface ISexThreshold {
+    male: number;
+    female: number;
+}
+/**
+ * Bodyweight-ratio thresholds for a full strength star, per level.
+ *
+ * Push  (bench/press family):
+ *   L1 0.60 — a committed beginner pressing meaningful load (~6-8 weeks)
+ *   L2 1.00 — pressing ~bodyweight (classic intermediate bench)
+ *   L3 1.40 — advanced pressing strength
+ * Pull  (row/pulldown/pull-up family):
+ *   L1 0.50 — reachable beginner pulling (rows / pulldowns), pre-pull-up
+ *   L2 0.85 — strong rows / clean bodyweight pull-ups
+ *   L3 1.20 — advanced (heavy weighted pull-ups)
+ * Lower (squat/hinge/lunge family):
+ *   L1 1.00 — beginner squatting ~bodyweight (reachable via bodyweight work too)
+ *   L2 1.50 — intermediate
+ *   L3 2.00 — advanced (a 2x bodyweight squat is a real milestone)
+ */
+export declare const STRENGTH_THRESHOLDS: Record<"push" | "pull" | "lowerBody", Record<TLevel, ISexThreshold>>;
+export interface IConsistencyThreshold {
+    /** Training days required within the window for full brightness. */
+    requiredSessions: number;
+    /** Trailing window length in days. */
+    windowDays: number;
+    /** Maximum idle gap (days) allowed before the no-gap condition breaks. */
+    maxGapDays: number;
+    /** Trailing idle days at which the "cooling" warning begins. */
+    warningAtIdleDays: number;
+}
+/**
+ * L1 ~2x/week habit; L2 ~3x/week; L3 ~4x/week. Window stays 28 days so it always
+ * reads "this month's habit".
+ *
+ * L3 maxGap relaxed 3 -> 4 (v1.1): a 3-day cap punished legitimate splits and
+ * planned deloads. 4 still keeps higher-level gap discipline tighter than L1/L2
+ * without penalising smart programming.
+ */
+export declare const CONSISTENCY_THRESHOLDS: Record<TLevel, IConsistencyThreshold>;
+export interface IQualityThreshold {
+    /** A session "clears" at or above this score (0-100). */
+    bar: number;
+    /** Number of most-recent sessions considered. */
+    windowSessions: number;
+    /** How many of the window must clear for full brightness. */
+    targetClearing: number;
+}
+/**
+ * L1 forgiving bar (70) over a short window; higher levels demand both a higher
+ * bar and a longer clean streak.
+ */
+export declare const QUALITY_THRESHOLDS: Record<TLevel, IQualityThreshold>;
+export interface IRecoveryThreshold {
+    /** Recovery cycles needed for full brightness (summed across trained zones). */
+    targetCycles: number;
+    /** Trailing window length in days. */
+    windowDays: number;
+    /** A muscle is "recovered" below this fatigue value (0-100). */
+    recoveredBelow: number;
+}
+/**
+ * Cycles are counted PER trained zone (upper/lower/core), so targets reflect
+ * summed zone cycles. Recovery is meaningful only alongside training volume — a
+ * no-train user earns nothing (untrained zones give no credit).
+ */
+export declare const RECOVERY_THRESHOLDS: Record<TLevel, IRecoveryThreshold>;
+/** Clamp any incoming level into the valid 1..MAX_LEVEL range. */
+export declare function clampLevel(level: number | undefined): TLevel;

package/dist/utils/constellation/levelThresholds.js

@@ -0,0 +1,123 @@
+"use strict";
+// utils/constellation/levelThresholds.ts — Per-level threshold ladder
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Level Threshold Ladder
+ * ============================================================================
+ *
+ * The single source of truth for what "full" means at each level, for every
+ * star. Stars read their row by the user's current level; nothing about a
+ * threshold is hard-coded inside star logic.
+ *
+ * Design intent (coach's calibration):
+ *   Level 1 = committed beginner   (reachable in ~2-3 months of honest work)
+ *   Level 2 = solid intermediate   (~6-12 months)
+ *   Level 3 = advanced             (multi-year, genuinely strong)
+ *
+ * Strength thresholds are estimated-1RM as a ratio of bodyweight, by sex.
+ * `unmentioned` gender is resolved to `male` (the higher bar) elsewhere, so a
+ * star is never too-easily lit for an unspecified profile.
+ *
+ * Calibration note (v1.1): these are first-pass values to be tuned against real
+ * brightness distributions post-launch. L1 pull was lowered from 0.65 -> 0.50
+ * because 0.65x BW pull excluded the large beginner segment that cannot yet do
+ * bodyweight pull-ups; L1 push eased 0.75 -> 0.60 so the first milestone lands
+ * in ~6-8 weeks rather than feeling intermediate. Lower body held at 1.0x — the
+ * bodyweight-load path lets home users reach it via pistol squats/lunges.
+ *
+ * Adding a level later = adding a key to each record. Star code does not change.
+ * The future goal layer can multiply these per-goal without touching this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOVERY_THRESHOLDS = exports.QUALITY_THRESHOLDS = exports.CONSISTENCY_THRESHOLDS = exports.STRENGTH_THRESHOLDS = exports.MAX_LEVEL = void 0;
+exports.clampLevel = clampLevel;
+exports.MAX_LEVEL = 3;
+/**
+ * Bodyweight-ratio thresholds for a full strength star, per level.
+ *
+ * Push  (bench/press family):
+ *   L1 0.60 — a committed beginner pressing meaningful load (~6-8 weeks)
+ *   L2 1.00 — pressing ~bodyweight (classic intermediate bench)
+ *   L3 1.40 — advanced pressing strength
+ * Pull  (row/pulldown/pull-up family):
+ *   L1 0.50 — reachable beginner pulling (rows / pulldowns), pre-pull-up
+ *   L2 0.85 — strong rows / clean bodyweight pull-ups
+ *   L3 1.20 — advanced (heavy weighted pull-ups)
+ * Lower (squat/hinge/lunge family):
+ *   L1 1.00 — beginner squatting ~bodyweight (reachable via bodyweight work too)
+ *   L2 1.50 — intermediate
+ *   L3 2.00 — advanced (a 2x bodyweight squat is a real milestone)
+ */
+exports.STRENGTH_THRESHOLDS = {
+    push: {
+        1: { male: 0.6, female: 0.45 },
+        2: { male: 1.0, female: 0.7 },
+        3: { male: 1.4, female: 0.95 },
+    },
+    pull: {
+        1: { male: 0.5, female: 0.38 },
+        2: { male: 0.85, female: 0.6 },
+        3: { male: 1.2, female: 0.85 },
+    },
+    lowerBody: {
+        1: { male: 1.0, female: 0.75 },
+        2: { male: 1.5, female: 1.1 },
+        3: { male: 2.0, female: 1.5 },
+    },
+};
+/**
+ * L1 ~2x/week habit; L2 ~3x/week; L3 ~4x/week. Window stays 28 days so it always
+ * reads "this month's habit".
+ *
+ * L3 maxGap relaxed 3 -> 4 (v1.1): a 3-day cap punished legitimate splits and
+ * planned deloads. 4 still keeps higher-level gap discipline tighter than L1/L2
+ * without penalising smart programming.
+ */
+exports.CONSISTENCY_THRESHOLDS = {
+    1: {
+        requiredSessions: 8,
+        windowDays: 28,
+        maxGapDays: 5,
+        warningAtIdleDays: 4,
+    },
+    2: {
+        requiredSessions: 12,
+        windowDays: 28,
+        maxGapDays: 4,
+        warningAtIdleDays: 3,
+    },
+    3: {
+        requiredSessions: 16,
+        windowDays: 28,
+        maxGapDays: 4,
+        warningAtIdleDays: 3,
+    },
+};
+/**
+ * L1 forgiving bar (70) over a short window; higher levels demand both a higher
+ * bar and a longer clean streak.
+ */
+exports.QUALITY_THRESHOLDS = {
+    1: { bar: 70, windowSessions: 5, targetClearing: 5 },
+    2: { bar: 78, windowSessions: 8, targetClearing: 7 },
+    3: { bar: 85, windowSessions: 10, targetClearing: 9 },
+};
+/**
+ * Cycles are counted PER trained zone (upper/lower/core), so targets reflect
+ * summed zone cycles. Recovery is meaningful only alongside training volume — a
+ * no-train user earns nothing (untrained zones give no credit).
+ */
+exports.RECOVERY_THRESHOLDS = {
+    1: { targetCycles: 3, windowDays: 56, recoveredBelow: 25 },
+    2: { targetCycles: 5, windowDays: 56, recoveredBelow: 25 },
+    3: { targetCycles: 7, windowDays: 56, recoveredBelow: 25 },
+};
+// --- Level helper -----------------------------------------------------------
+/** Clamp any incoming level into the valid 1..MAX_LEVEL range. */
+function clampLevel(level) {
+    if (!level || level < 1)
+        return 1;
+    if (level > exports.MAX_LEVEL)
+        return exports.MAX_LEVEL;
+    return Math.floor(level);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Star Foundation
+ * ============================================================================
+ *
+ * Shared pure glue. Types come from ./types. Behaviour only:
+ *   - deriveTier:  continuous brightness -> discrete band (0-3)
+ *   - resolveStar: definition + context -> render-ready TResolvedStar
+ */
+import type { TStarTier, TStarDefinition, TStarContext, TResolvedStar } from "./types";
+/** Brightness lower-bounds per tier. Tunable in one place. */
+export declare const TIER_THRESHOLDS: {
+    readonly faint: 1;
+    readonly rising: 34;
+    readonly full: 100;
+};
+/**
+ * 0 dormant (<1) - 1 faint (1-33) - 2 rising (34-99) - 3 full (>=100).
+ */
+export declare function deriveTier(brightness: number): TStarTier;
+/**
+ * Run a star definition through its evaluator into the render-ready shape.
+ * Brightness clamped 0-100 here so evaluators don't each have to.
+ */
+export declare function resolveStar(def: TStarDefinition, ctx: TStarContext): TResolvedStar;

package/dist/utils/constellation/starFoundation.js

@@ -0,0 +1,54 @@
+"use strict";
+// utils/constellation/starFoundation.ts — Star Foundation
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Star Foundation
+ * ============================================================================
+ *
+ * Shared pure glue. Types come from ./types. Behaviour only:
+ *   - deriveTier:  continuous brightness -> discrete band (0-3)
+ *   - resolveStar: definition + context -> render-ready TResolvedStar
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIER_THRESHOLDS = void 0;
+exports.deriveTier = deriveTier;
+exports.resolveStar = resolveStar;
+/** Brightness lower-bounds per tier. Tunable in one place. */
+exports.TIER_THRESHOLDS = {
+    faint: 1,
+    rising: 34,
+    full: 100,
+};
+/**
+ * 0 dormant (<1) - 1 faint (1-33) - 2 rising (34-99) - 3 full (>=100).
+ */
+function deriveTier(brightness) {
+    if (brightness >= exports.TIER_THRESHOLDS.full)
+        return 3;
+    if (brightness >= exports.TIER_THRESHOLDS.rising)
+        return 2;
+    if (brightness >= exports.TIER_THRESHOLDS.faint)
+        return 1;
+    return 0;
+}
+/**
+ * Run a star definition through its evaluator into the render-ready shape.
+ * Brightness clamped 0-100 here so evaluators don't each have to.
+ */
+function resolveStar(def, ctx) {
+    const { brightness, detail } = def.evaluate(ctx);
+    const clamped = Math.max(0, Math.min(100, brightness));
+    return {
+        id: def.id,
+        displayName: def.displayName,
+        color: def.color,
+        figurePosition: def.figurePosition,
+        brightness: clamped,
+        tier: deriveTier(clamped),
+        objective: def.objective,
+        rationale: def.rationale,
+        currentState: detail.currentState,
+        target: detail.target,
+        gap: detail.gap,
+    };
+}

package/dist/utils/constellation/stars/consistency.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Consistency Star (the heart)
+ * ============================================================================
+ *
+ * The live "showing up" star. Brightness reflects the user's CURRENT training
+ * habit, recomputed every call from recent session dates. The one star meant to
+ * be maintained, not achieved — it brightens with a steady habit and dims when
+ * the user goes quiet.
+ *
+ * Full brightness requires BOTH:
+ *   - requiredSessions training days within the trailing window, AND
+ *   - the trailing idle gap (last session -> now) within maxGapDays.
+ *
+ * Brightness is graded below full so progress is always visible:
+ *   - countComponent — progress toward the required session count
+ *   - gapComponent   — a live penalty as the TRAILING gap exceeds maxGapDays
+ *
+ * Note: brightness uses the TRAILING gap, not interior gaps. An old gap the user
+ * has since recovered from should not permanently dim a live habit signal.
+ * Interior gaps still inform the gap MESSAGE for context.
+ *
+ * Counting rule: a session counts as a training day only if it has >=1 completed
+ * set. Multiple sessions on one calendar day = one training day.
+ *
+ * Thresholds come from CONSISTENCY_THRESHOLDS[level].
+ */
+import type { TStarDefinition } from "../types";
+export declare const consistencyStar: TStarDefinition;

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

@@ -0,0 +1,142 @@
+"use strict";
+// utils/constellation/stars/consistency.ts — Consistency Star (the heart)
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Consistency Star (the heart)
+ * ============================================================================
+ *
+ * The live "showing up" star. Brightness reflects the user's CURRENT training
+ * habit, recomputed every call from recent session dates. The one star meant to
+ * be maintained, not achieved — it brightens with a steady habit and dims when
+ * the user goes quiet.
+ *
+ * Full brightness requires BOTH:
+ *   - requiredSessions training days within the trailing window, AND
+ *   - the trailing idle gap (last session -> now) within maxGapDays.
+ *
+ * Brightness is graded below full so progress is always visible:
+ *   - countComponent — progress toward the required session count
+ *   - gapComponent   — a live penalty as the TRAILING gap exceeds maxGapDays
+ *
+ * Note: brightness uses the TRAILING gap, not interior gaps. An old gap the user
+ * has since recovered from should not permanently dim a live habit signal.
+ * Interior gaps still inform the gap MESSAGE for context.
+ *
+ * Counting rule: a session counts as a training day only if it has >=1 completed
+ * set. Multiple sessions on one calendar day = one training day.
+ *
+ * Thresholds come from CONSISTENCY_THRESHOLDS[level].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consistencyStar = void 0;
+const levelThresholds_1 = require("../levelThresholds");
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// --- Helpers ----------------------------------------------------------------
+/** Does a session have at least one completed set? (isDone is a guaranteed bool on TRecord) */
+function hasCompletedSet(session) {
+    for (const ex of session.exercises) {
+        for (const set of ex.records) {
+            if (set.isDone)
+                return true;
+        }
+    }
+    return false;
+}
+function countMeasure(sessions, required) {
+    return {
+        value: sessions,
+        unit: "sessions",
+        display: {
+            translationKey: "constellation.consistency.measure.sessions",
+            params: [Math.min(sessions, required), required],
+        },
+    };
+}
+function buildGap(sessionsInWindow, longestGapDays, trailingGapDays, required, maxGapDays, warningAtIdleDays) {
+    // Brand-new user (no training days in window): invite, don't scold. Without
+    // this, a zero-session user trips the "broken" branch (trailingGap = window).
+    if (sessionsInWindow === 0) {
+        return { translationKey: "constellation.consistency.gap.getStarted" };
+    }
+    // Cooling warning: trailing gap is creeping toward the max.
+    if (trailingGapDays >= warningAtIdleDays && trailingGapDays <= maxGapDays) {
+        const daysRemaining = maxGapDays - trailingGapDays + 1;
+        return {
+            translationKey: "constellation.consistency.gap.cooling",
+            params: [daysRemaining],
+        };
+    }
+    if (longestGapDays > maxGapDays) {
+        return { translationKey: "constellation.consistency.gap.broken" };
+    }
+    const remaining = Math.max(0, required - sessionsInWindow);
+    if (remaining > 0) {
+        return {
+            translationKey: "constellation.consistency.gap.moreSessions",
+            params: [remaining],
+        };
+    }
+    return { translationKey: "constellation.consistency.gap.full" };
+}
+// --- Evaluator --------------------------------------------------------------
+function evaluateConsistency(ctx) {
+    const { requiredSessions, windowDays, maxGapDays, warningAtIdleDays } = levelThresholds_1.CONSISTENCY_THRESHOLDS[ctx.level];
+    const { now } = ctx;
+    const windowStart = now - windowDays * MS_PER_DAY;
+    const nowDay = Math.floor(now / MS_PER_DAY);
+    // Training days = sessions with >=1 completed set, deduped to calendar day,
+    // within the trailing window, sorted ascending. Upper bound is by CALENDAR
+    // DAY (<= today) so a session logged later today than `now` still counts.
+    const dayIndices = Array.from(new Set(ctx.sessions
+        .filter((s) => {
+        if (!hasCompletedSet(s))
+            return false;
+        const d = Math.floor(s.date / MS_PER_DAY);
+        return s.date > windowStart && d <= nowDay;
+    })
+        .map((s) => Math.floor(s.date / MS_PER_DAY)))).sort((a, b) => a - b);
+    const sessionsInWindow = dayIndices.length;
+    // Longest interior gap (for the message only).
+    let longestGapDays = 0;
+    for (let i = 1; i < dayIndices.length; i++) {
+        const gap = dayIndices[i] - dayIndices[i - 1];
+        if (gap > longestGapDays)
+            longestGapDays = gap;
+    }
+    // Trailing gap: last training day -> today. No sessions -> maximally idle.
+    const trailingGap = dayIndices.length > 0
+        ? nowDay - dayIndices[dayIndices.length - 1]
+        : windowDays;
+    if (trailingGap > longestGapDays)
+        longestGapDays = trailingGap;
+    // Brightness: two multiplicative components, both 0..1.
+    const countComponent = Math.min(1, sessionsInWindow / requiredSessions);
+    let gapComponent;
+    if (trailingGap <= maxGapDays) {
+        gapComponent = 1; // within allowed idle window — no penalty
+    }
+    else {
+        const over = trailingGap - maxGapDays;
+        const decayRange = Math.max(1, windowDays - maxGapDays);
+        gapComponent = Math.max(0, 1 - over / decayRange);
+    }
+    const brightness = Math.min(100, countComponent * gapComponent * 100);
+    return {
+        brightness,
+        detail: {
+            currentState: countMeasure(sessionsInWindow, requiredSessions),
+            target: countMeasure(requiredSessions, requiredSessions),
+            gap: buildGap(sessionsInWindow, longestGapDays, trailingGap, requiredSessions, maxGapDays, warningAtIdleDays),
+        },
+    };
+}
+// --- Definition -------------------------------------------------------------
+exports.consistencyStar = {
+    id: "consistency",
+    displayName: { translationKey: "constellation.consistency.name" },
+    color: "#ff8c00", // amber-gold — the spark of the flame, the heart
+    figurePosition: "heart",
+    objective: { translationKey: "constellation.consistency.objective" },
+    rationale: { translationKey: "constellation.consistency.rationale" },
+    evaluate: evaluateConsistency,
+};

package/dist/utils/constellation/stars/lowerBody.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Lower Body Star
+ * ============================================================================
+ *
+ * Lower-body strength across squat, lunge, and hinge patterns combined, any
+ * equipment. Squats, goblet squats, leg press, lunges, deadlifts, RDLs, hip
+ * thrusts, kettlebell swings — all count. Best load across all three lights it.
+ * (Knee-vs-hip balance nuance deferred to the future goal layer.)
+ *
+ * Threshold per level from STRENGTH_THRESHOLDS.lowerBody, resolved by sex.
+ * Leg press is NOT special-cased — it is simply a squat-pattern exercise.
+ * Bodyweight lower-body work loads via the exercise's weightMultiplier, so home
+ * users can reach the threshold honestly.
+ */
+import type { TStarDefinition } from "../types";
+export declare const lowerBodyStar: TStarDefinition;