@dofek/scoring 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Asher Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @dofek/scoring
+
+Platform-agnostic TypeScript models for health scores, sleep and readiness
+presentation, breathwork sessions, and shared design tokens. The package is used
+by both web and mobile clients but has no UI-framework dependency.
+
+## Install
+
+```sh
+npm install @dofek/scoring
+```
+
+Requires Node.js 22.14 or newer.
+
+## Usage
+
+There is no root export; import the subpath for the model you need.
+
+```ts
+import {
+  StrainScore,
+  zScoreToRecoveryScore,
+} from "@dofek/scoring/scoring";
+
+const strain = StrainScore.fromRawLoad(120);
+
+console.log({
+  strain: strain.value,
+  strainLabel: strain.label,
+  recovery: zScoreToRecoveryScore(0.75),
+});
+```
+
+## Public API
+
+| Subpath | Purpose |
+| --- | --- |
+| `@dofek/scoring/scoring` | Strain, recovery, workload-ratio, trend, score-zone, and presentation helpers |
+| `@dofek/scoring/colors` | Semantic, chart, surface, text, sleep-stage, and activity colors |
+| `@dofek/scoring/tokens` | Framework-neutral typography, spacing, radius, animation, and chart tokens |
+| `@dofek/scoring/strain-target` | Daily strain-target calculation and result types |
+| `@dofek/scoring/sleep-performance` | Sleep-performance components, tiers, and recommended-bedtime calculation |
+| `@dofek/scoring/healthspan-years` | Score-to-years mapping and formatting |
+| `@dofek/scoring/menstrual-cycle` | Cycle-phase estimation and display metadata |
+| `@dofek/scoring/breathwork` | Built-in breathing techniques and session-duration helpers |
+| `@dofek/scoring/loading-policy` | Blocking-loading state policy |
+| `@dofek/scoring/query-cache` | Shared query-cache age constant |
+
+## Model behavior
+
+- `StrainScore.fromRawLoad` applies logarithmic scaling, maps non-positive loads
+  to zero, and caps the result at 21.
+- `zScoreToRecoveryScore` uses a Dofek-defined asymmetric sigmoid where a
+  z-score of zero maps to 62.
+- Strain targets use Dofek-defined readiness bands and cap the target when the
+  acute-to-chronic workload ratio exceeds 1.3.
+- Sleep performance defaults to 70% sleep sufficiency and 30% efficiency. When
+  consistency or low-stress inputs are supplied, it averages all available
+  components equally.
+- Healthspan display deltas map scores from 0–100 onto +3 to -2 years.
+- Cycle phases estimate ovulation as `cycleLength - 14`; this is a display
+  estimate, not a clinical assessment.
+- The design-token modules contain values only; they do not install fonts or
+  render UI.
+
+The package performs no network requests and needs no authentication or runtime
+configuration. Validate untrusted input before calling the calculation
+functions. These models are for fitness software and are not medical advice.
+
+## License and contributing
+
+[MIT](./LICENSE). Source is in the
+[Dofek repository](https://github.com/Asherlc/dofek/tree/main/packages/scoring).
+Please [open an issue](https://github.com/Asherlc/dofek/issues) for bugs or API
+proposals, or [submit a pull request](https://github.com/Asherlc/dofek/pulls).

package/dist/breathwork.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Breathwork technique definitions and session helpers.
+ *
+ * Each technique defines the breathing pattern (inhale/hold/exhale/hold durations)
+ * and default number of rounds.
+ */
+export interface BreathworkTechnique {
+    id: string;
+    name: string;
+    description: string;
+    /** Inhale duration in seconds */
+    inhaleSeconds: number;
+    /** Hold after inhale in seconds (optional) */
+    holdInSeconds?: number;
+    /** Exhale duration in seconds */
+    exhaleSeconds: number;
+    /** Hold after exhale in seconds (optional) */
+    holdOutSeconds?: number;
+    /** Default number of rounds */
+    defaultRounds: number;
+}
+export declare const TECHNIQUES: BreathworkTechnique[];
+/** Look up a technique by its ID */
+export declare function getTechniqueById(id: string): BreathworkTechnique | undefined;
+/** Compute total session duration in seconds for a given number of rounds */
+export declare function totalSessionSeconds(technique: BreathworkTechnique, rounds: number): number;
+//# sourceMappingURL=breathwork.d.ts.map

package/dist/breathwork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breathwork.d.ts","sourceRoot":"","sources":["../src/breathwork.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAkD3C,CAAC;AAEF,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAE5E;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAO1F"}

package/dist/breathwork.js

@@ -0,0 +1,65 @@
+/**
+ * Breathwork technique definitions and session helpers.
+ *
+ * Each technique defines the breathing pattern (inhale/hold/exhale/hold durations)
+ * and default number of rounds.
+ */
+export const TECHNIQUES = [
+    {
+        id: "box-breathing",
+        name: "Box Breathing",
+        description: "Equal parts inhale, hold, exhale, hold. Used by Navy SEALs to reduce stress and improve focus.",
+        inhaleSeconds: 4,
+        holdInSeconds: 4,
+        exhaleSeconds: 4,
+        holdOutSeconds: 4,
+        defaultRounds: 4,
+    },
+    {
+        id: "4-7-8",
+        name: "4-7-8 Breathing",
+        description: "Relaxing breath technique. Inhale 4s, hold 7s, exhale 8s. Promotes deep relaxation and sleep.",
+        inhaleSeconds: 4,
+        holdInSeconds: 7,
+        exhaleSeconds: 8,
+        defaultRounds: 4,
+    },
+    {
+        id: "coherent",
+        name: "Coherent Breathing",
+        description: "Slow, rhythmic breathing at 5 breaths per minute. Balances the autonomic nervous system and optimizes HRV.",
+        inhaleSeconds: 6,
+        exhaleSeconds: 6,
+        defaultRounds: 10,
+    },
+    {
+        id: "physiological-sigh",
+        name: "Physiological Sigh",
+        description: "Double inhale through the nose followed by a long exhale. Rapidly reduces stress and anxiety.",
+        inhaleSeconds: 3,
+        holdInSeconds: 1,
+        exhaleSeconds: 6,
+        defaultRounds: 5,
+    },
+    {
+        id: "wim-hof",
+        name: "Wim Hof Method",
+        description: "Power breathing with deep inhales and passive exhales. Increases energy, focus, and cold tolerance.",
+        inhaleSeconds: 2,
+        exhaleSeconds: 2,
+        defaultRounds: 30,
+    },
+];
+/** Look up a technique by its ID */
+export function getTechniqueById(id) {
+    return TECHNIQUES.find((t) => t.id === id);
+}
+/** Compute total session duration in seconds for a given number of rounds */
+export function totalSessionSeconds(technique, rounds) {
+    const roundSeconds = technique.inhaleSeconds +
+        (technique.holdInSeconds ?? 0) +
+        technique.exhaleSeconds +
+        (technique.holdOutSeconds ?? 0);
+    return roundSeconds * rounds;
+}
+//# sourceMappingURL=breathwork.js.map

package/dist/breathwork.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breathwork.js","sourceRoot":"","sources":["../src/breathwork.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,MAAM,CAAC,MAAM,UAAU,GAA0B;IAC/C;QACE,EAAE,EAAE,eAAe;QACnB,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,gGAAgG;QAClG,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,cAAc,EAAE,CAAC;QACjB,aAAa,EAAE,CAAC;KACjB;IACD;QACE,EAAE,EAAE,OAAO;QACX,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,+FAA+F;QACjG,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;KACjB;IACD;QACE,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,4GAA4G;QAC9G,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,EAAE;KAClB;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,+FAA+F;QACjG,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;KACjB;IACD;QACE,EAAE,EAAE,SAAS;QACb,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,qGAAqG;QACvG,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,EAAE;KAClB;CACF,CAAC;AAEF,oCAAoC;AACpC,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,SAA8B,EAAE,MAAc;IAChF,MAAM,YAAY,GAChB,SAAS,CAAC,aAAa;QACvB,CAAC,SAAS,CAAC,aAAa,IAAI,CAAC,CAAC;QAC9B,SAAS,CAAC,aAAa;QACvB,CAAC,SAAS,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC;IAClC,OAAO,YAAY,GAAG,MAAM,CAAC;AAC/B,CAAC"}

package/dist/colors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Semantic color palette shared across web and iOS.
+ *
+ * Web components use these in ECharts config and inline styles.
+ * iOS components use these directly in React Native StyleSheets.
+ * Tailwind utility classes remain platform-specific (web only).
+ */
+/** Status colors for scores, alerts, and thresholds.
+ *  Darkened one shade vs originals for contrast on light sage background. */
+export declare const statusColors: {
+    /** Positive / good / green — scores ≥67, optimal zones */
+    readonly positive: "#16a34a";
+    /** Warning / moderate / yellow — scores 34-66, caution zones */
+    readonly warning: "#ca8a04";
+    /** Danger / poor / red — scores <34, injury risk */
+    readonly danger: "#dc2626";
+    /** Informational / neutral / blue */
+    readonly info: "#2563eb";
+    /** Orange — elevated warnings (e.g. high ramp rate) */
+    readonly elevated: "#ea580c";
+};
+/** Chart series colors for consistent multi-series plots.
+ *  Adjusted for contrast on light (#eef3ed) background. */
+export declare const chartColors: {
+    readonly teal: "#0ea5e9";
+    readonly purple: "#5E35B1";
+    readonly blue: "#2563eb";
+    readonly green: "#16a34a";
+    readonly orange: "#ea580c";
+    readonly emerald: "#059669";
+    readonly pink: "#db2777";
+    readonly amber: "#d97706";
+};
+/** Light sage/mint theme surface colors */
+export declare const surfaceColors: {
+    readonly background: "#eef3ed";
+    readonly surface: "#f5f9f5";
+    readonly surfaceSecondary: "#e8ede7";
+    readonly accent: "#2d7a56";
+};
+/** Text colors for sage/mint light theme */
+export declare const textColors: {
+    readonly primary: "#1a2e1a";
+    readonly secondary: "#4a6a4a";
+    readonly tertiary: "#6b8a6b";
+    /** Neutral gray — used for stable/unchanged trends */
+    readonly neutral: "#8aaa8a";
+};
+/** Sleep stage colors — consistent across web (ECharts) and mobile (SVG).
+ *  Uses the Material-inspired palette for maximum stage distinction. */
+export declare const sleepStageColors: {
+    readonly deep: "#5E35B1";
+    readonly rem: "#42A5F5";
+    readonly light: "#78909C";
+    readonly awake: "#FF8A65";
+};
+/** Activity metric chart series colors — universal associations. */
+export declare const activityMetricColors: {
+    readonly heartRate: "#dc2626";
+    readonly power: "#d97706";
+    readonly speed: "#2563eb";
+    readonly cadence: "#5E35B1";
+};
+/** Chart chrome colors for ECharts tooltips, axes, and grid lines */
+export declare const chartThemeColors: {
+    readonly gridLine: "rgba(74, 158, 122, 0.12)";
+    readonly axisLine: "rgba(74, 158, 122, 0.25)";
+    readonly axisLabel: "#6b8a6b";
+    readonly tooltipBackground: "#ffffff";
+    readonly tooltipBorder: "rgba(74, 158, 122, 0.2)";
+    readonly tooltipText: "#1a2e1a";
+    readonly legendText: "#4a6a4a";
+};
+//# sourceMappingURL=colors.d.ts.map

package/dist/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;6EAC6E;AAC7E,eAAO,MAAM,YAAY;IACvB,0DAA0D;;IAE1D,gEAAgE;;IAEhE,oDAAoD;;IAEpD,qCAAqC;;IAErC,uDAAuD;;CAE/C,CAAC;AAEX;2DAC2D;AAC3D,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,2CAA2C;AAC3C,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,UAAU;;;;IAIrB,sDAAsD;;CAE9C,CAAC;AAEX;wEACwE;AACxE,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,gBAAgB;;;;;;;;CAQnB,CAAC"}

package/dist/colors.js

@@ -0,0 +1,74 @@
+/**
+ * Semantic color palette shared across web and iOS.
+ *
+ * Web components use these in ECharts config and inline styles.
+ * iOS components use these directly in React Native StyleSheets.
+ * Tailwind utility classes remain platform-specific (web only).
+ */
+/** Status colors for scores, alerts, and thresholds.
+ *  Darkened one shade vs originals for contrast on light sage background. */
+export const statusColors = {
+    /** Positive / good / green — scores ≥67, optimal zones */
+    positive: "#16a34a",
+    /** Warning / moderate / yellow — scores 34-66, caution zones */
+    warning: "#ca8a04",
+    /** Danger / poor / red — scores <34, injury risk */
+    danger: "#dc2626",
+    /** Informational / neutral / blue */
+    info: "#2563eb",
+    /** Orange — elevated warnings (e.g. high ramp rate) */
+    elevated: "#ea580c",
+};
+/** Chart series colors for consistent multi-series plots.
+ *  Adjusted for contrast on light (#eef3ed) background. */
+export const chartColors = {
+    teal: "#0ea5e9",
+    purple: "#5E35B1",
+    blue: "#2563eb",
+    green: "#16a34a",
+    orange: "#ea580c",
+    emerald: "#059669",
+    pink: "#db2777",
+    amber: "#d97706",
+};
+/** Light sage/mint theme surface colors */
+export const surfaceColors = {
+    background: "#eef3ed",
+    surface: "#f5f9f5",
+    surfaceSecondary: "#e8ede7",
+    accent: "#2d7a56",
+};
+/** Text colors for sage/mint light theme */
+export const textColors = {
+    primary: "#1a2e1a",
+    secondary: "#4a6a4a",
+    tertiary: "#6b8a6b",
+    /** Neutral gray — used for stable/unchanged trends */
+    neutral: "#8aaa8a",
+};
+/** Sleep stage colors — consistent across web (ECharts) and mobile (SVG).
+ *  Uses the Material-inspired palette for maximum stage distinction. */
+export const sleepStageColors = {
+    deep: "#5E35B1",
+    rem: "#42A5F5",
+    light: "#78909C",
+    awake: "#FF8A65",
+};
+/** Activity metric chart series colors — universal associations. */
+export const activityMetricColors = {
+    heartRate: "#dc2626",
+    power: "#d97706",
+    speed: "#2563eb",
+    cadence: "#5E35B1",
+};
+/** Chart chrome colors for ECharts tooltips, axes, and grid lines */
+export const chartThemeColors = {
+    gridLine: "rgba(74, 158, 122, 0.12)",
+    axisLine: "rgba(74, 158, 122, 0.25)",
+    axisLabel: "#6b8a6b",
+    tooltipBackground: "#ffffff",
+    tooltipBorder: "rgba(74, 158, 122, 0.2)",
+    tooltipText: "#1a2e1a",
+    legendText: "#4a6a4a",
+};
+//# sourceMappingURL=colors.js.map

package/dist/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;6EAC6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,SAAS;IACnB,gEAAgE;IAChE,OAAO,EAAE,SAAS;IAClB,oDAAoD;IACpD,MAAM,EAAE,SAAS;IACjB,qCAAqC;IACrC,IAAI,EAAE,SAAS;IACf,uDAAuD;IACvD,QAAQ,EAAE,SAAS;CACX,CAAC;AAEX;2DAC2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;CACR,CAAC;AAEX,2CAA2C;AAC3C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,UAAU,EAAE,SAAS;IACrB,OAAO,EAAE,SAAS;IAClB,gBAAgB,EAAE,SAAS;IAC3B,MAAM,EAAE,SAAS;CACT,CAAC;AAEX,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,SAAS;IACpB,QAAQ,EAAE,SAAS;IACnB,sDAAsD;IACtD,OAAO,EAAE,SAAS;CACV,CAAC;AAEX;wEACwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,SAAS;CACR,CAAC;AAEX,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,SAAS;IACpB,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,SAAS;CACV,CAAC;AAEX,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,0BAA0B;IACpC,QAAQ,EAAE,0BAA0B;IACpC,SAAS,EAAE,SAAS;IACpB,iBAAiB,EAAE,SAAS;IAC5B,aAAa,EAAE,yBAAyB;IACxC,WAAW,EAAE,SAAS;IACtB,UAAU,EAAE,SAAS;CACb,CAAC"}

package/dist/healthspan-years.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Healthspan Years — maps a healthspan score (0-100) to a biological age delta.
+ *
+ * Score 0 → +3 years (aging faster than chronological age)
+ * Score 50 → 0 years (aging at expected rate)
+ * Score 100 → -2 years (aging slower than chronological age)
+ *
+ * The scale is intentionally asymmetric: poor health has a bigger penalty
+ * than good health has a benefit, reflecting longevity research showing
+ * inactivity/poor sleep shortens life more than peak fitness extends it.
+ */
+/**
+ * Convert a healthspan score (0-100) to a years-of-life delta.
+ * Positive = aging faster (losing years). Negative = aging slower (gaining years).
+ */
+export declare function scoreToYearsDelta(score: number): number;
+/**
+ * Format a years delta for display.
+ * Examples: "+1.5 yr", "-2.0 yr", "+0.0 yr"
+ */
+export declare function formatYearsDelta(years: number): string;
+//# sourceMappingURL=healthspan-years.d.ts.map

package/dist/healthspan-years.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthspan-years.d.ts","sourceRoot":"","sources":["../src/healthspan-years.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/healthspan-years.js

@@ -0,0 +1,33 @@
+/**
+ * Healthspan Years — maps a healthspan score (0-100) to a biological age delta.
+ *
+ * Score 0 → +3 years (aging faster than chronological age)
+ * Score 50 → 0 years (aging at expected rate)
+ * Score 100 → -2 years (aging slower than chronological age)
+ *
+ * The scale is intentionally asymmetric: poor health has a bigger penalty
+ * than good health has a benefit, reflecting longevity research showing
+ * inactivity/poor sleep shortens life more than peak fitness extends it.
+ */
+/**
+ * Convert a healthspan score (0-100) to a years-of-life delta.
+ * Positive = aging faster (losing years). Negative = aging slower (gaining years).
+ */
+export function scoreToYearsDelta(score) {
+    const clamped = Math.max(0, Math.min(100, score));
+    if (clamped <= 50) {
+        // 0→+3, 50→0 (linear interpolation)
+        return Math.round((3 - (clamped / 50) * 3) * 10) / 10;
+    }
+    // 50→0, 100→-2 (linear interpolation)
+    return Math.round((-(clamped - 50) / 50) * 2 * 10) / 10;
+}
+/**
+ * Format a years delta for display.
+ * Examples: "+1.5 yr", "-2.0 yr", "+0.0 yr"
+ */
+export function formatYearsDelta(years) {
+    const sign = years >= 0 ? "+" : "";
+    return `${sign}${years.toFixed(1)} yr`;
+}
+//# sourceMappingURL=healthspan-years.js.map

package/dist/healthspan-years.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthspan-years.js","sourceRoot":"","sources":["../src/healthspan-years.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IAElD,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QAClB,oCAAoC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IACxD,CAAC;IACD,sCAAsC;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnC,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AACzC,CAAC"}

package/dist/loading-policy.d.ts

@@ -0,0 +1,8 @@
+interface LoadingPolicyInput {
+    data: unknown;
+    isLoading: boolean;
+    isFetching?: boolean;
+}
+export declare function shouldShowBlockingLoading({ data, isLoading, isFetching, }: LoadingPolicyInput): boolean;
+export {};
+//# sourceMappingURL=loading-policy.d.ts.map

package/dist/loading-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-policy.d.ts","sourceRoot":"","sources":["../src/loading-policy.ts"],"names":[],"mappings":"AAAA,UAAU,kBAAkB;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAOD,wBAAgB,yBAAyB,CAAC,EACxC,IAAI,EACJ,SAAS,EACT,UAAkB,GACnB,EAAE,kBAAkB,GAAG,OAAO,CAE9B"}

package/dist/loading-policy.js

@@ -0,0 +1,9 @@
+function hasExistingData(data) {
+    if (Array.isArray(data))
+        return data.length > 0;
+    return data != null;
+}
+export function shouldShowBlockingLoading({ data, isLoading, isFetching = false, }) {
+    return (isLoading || isFetching) && !hasExistingData(data);
+}
+//# sourceMappingURL=loading-policy.js.map

package/dist/loading-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-policy.js","sourceRoot":"","sources":["../src/loading-policy.ts"],"names":[],"mappings":"AAMA,SAAS,eAAe,CAAC,IAAa;IACpC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,OAAO,IAAI,IAAI,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,EACxC,IAAI,EACJ,SAAS,EACT,UAAU,GAAG,KAAK,GACC;IACnB,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}

package/dist/menstrual-cycle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Menstrual cycle phase computation.
+ *
+ * Four phases based on day within cycle:
+ * 1. Menstrual (days 1-5): period bleeding
+ * 2. Follicular (days 6 to ovulation-1): estrogen rises
+ * 3. Ovulatory (around ovulation ±1 day): peak fertility
+ * 4. Luteal (post-ovulation to end): progesterone dominant
+ *
+ * Ovulation is estimated at cycleLength - 14 (luteal phase is ~14 days).
+ */
+export type CyclePhase = "menstrual" | "follicular" | "ovulatory" | "luteal";
+/**
+ * Compute the cycle phase for a given day within a cycle.
+ * @param dayOfCycle 1-based day number within the cycle
+ * @param cycleLength Total cycle length in days (typically 21-35)
+ */
+export declare function computePhase(dayOfCycle: number, cycleLength: number): CyclePhase;
+/** Display name and color for each phase */
+export declare const PHASE_DISPLAY: Record<CyclePhase, {
+    label: string;
+    color: string;
+}>;
+//# sourceMappingURL=menstrual-cycle.d.ts.map

package/dist/menstrual-cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menstrual-cycle.d.ts","sourceRoot":"","sources":["../src/menstrual-cycle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAqBhF;AAED,4CAA4C;AAC5C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,UAAU,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAK9E,CAAC"}

package/dist/menstrual-cycle.js

@@ -0,0 +1,32 @@
+import { chartColors, statusColors } from "./colors.js";
+/**
+ * Compute the cycle phase for a given day within a cycle.
+ * @param dayOfCycle 1-based day number within the cycle
+ * @param cycleLength Total cycle length in days (typically 21-35)
+ */
+export function computePhase(dayOfCycle, cycleLength) {
+    // Menstrual phase: first 5 days
+    if (dayOfCycle <= 5) {
+        return "menstrual";
+    }
+    // Estimated ovulation day (luteal phase is roughly constant at 14 days)
+    const ovulationDay = Math.max(6, cycleLength - 14);
+    // Ovulatory window: ovulation day ± 1
+    if (dayOfCycle >= ovulationDay - 1 && dayOfCycle <= ovulationDay + 1) {
+        return "ovulatory";
+    }
+    // Follicular: between menstrual and ovulatory
+    if (dayOfCycle < ovulationDay - 1) {
+        return "follicular";
+    }
+    // Luteal: after ovulatory window
+    return "luteal";
+}
+/** Display name and color for each phase */
+export const PHASE_DISPLAY = {
+    menstrual: { label: "Menstrual", color: statusColors.danger },
+    follicular: { label: "Follicular", color: statusColors.info },
+    ovulatory: { label: "Ovulatory", color: chartColors.purple },
+    luteal: { label: "Luteal", color: chartColors.amber },
+};
+//# sourceMappingURL=menstrual-cycle.js.map

package/dist/menstrual-cycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menstrual-cycle.js","sourceRoot":"","sources":["../src/menstrual-cycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgBxD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,WAAmB;IAClE,gCAAgC;IAChC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,wEAAwE;IACxE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,EAAE,CAAC,CAAC;IAEnD,sCAAsC;IACtC,IAAI,UAAU,IAAI,YAAY,GAAG,CAAC,IAAI,UAAU,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACrE,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,8CAA8C;IAC9C,IAAI,UAAU,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,iCAAiC;IACjC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAyD;IACjF,SAAS,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE;IAC7D,UAAU,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,EAAE;IAC7D,SAAS,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE;IAC5D,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE;CACtD,CAAC"}

package/dist/query-cache.d.ts

@@ -0,0 +1,2 @@
+export declare const QUERY_CACHE_MAX_AGE_MS: number;
+//# sourceMappingURL=query-cache.d.ts.map

package/dist/query-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-cache.d.ts","sourceRoot":"","sources":["../src/query-cache.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,QAAsB,CAAC"}

package/dist/query-cache.js

@@ -0,0 +1,2 @@
+export const QUERY_CACHE_MAX_AGE_MS = 1000 * 60 * 60 * 12;
+//# sourceMappingURL=query-cache.js.map

package/dist/query-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-cache.js","sourceRoot":"","sources":["../src/query-cache.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC"}

package/dist/scoring.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Whoop-like 0–21 strain score with display classification.
+ *
+ * Construct directly with a strain value or use `fromRawLoad()` to convert
+ * raw daily training load (duration_min × avg_hr/max_hr) using logarithmic
+ * scaling that produces diminishing returns at higher loads.
+ */
+export declare class StrainScore {
+    #private;
+    readonly value: number;
+    constructor(value: number);
+    get color(): string;
+    get label(): string;
+    get description(): string;
+    static fromRawLoad(rawLoad: number): StrainScore;
+    static fromPhysiologicalLoad(physiologicalLoad: number): StrainScore;
+    static fromAcuteLoad(acuteLoad: number): StrainScore;
+}
+/** Get the color for a recovery/readiness score (0-100) */
+export declare const SCORE_WARNING_THRESHOLD = 50;
+export declare const SCORE_RECOVERED_THRESHOLD = 70;
+export interface ScoreZone {
+    /** Lower bound (inclusive) */
+    min: number;
+    /** Upper bound (inclusive for charting) */
+    max: number;
+    status: "danger" | "warning" | "positive";
+}
+/** Visual score zones used by charts and cards to keep threshold bands consistent. */
+export declare const SCORE_ZONES: ScoreZone[];
+export declare function scoreColor(score: number): string;
+/** Get a human-readable label for a recovery score (0-100) */
+export declare function scoreLabel(score: number): string;
+/** Get a contextual description for a recovery score explaining what it means */
+export declare function scoreDescription(score: number): string;
+/** Strain zone classification with display properties. */
+export declare class StrainZone {
+    readonly zone: string;
+    constructor(zone: string);
+    get color(): string;
+    get label(): string;
+}
+/** Workload ratio (ACWR) with display classification. */
+export declare class WorkloadRatio {
+    readonly value: number | null;
+    constructor(value: number | null);
+    get color(): string;
+    get hint(): string | null;
+}
+export interface WeekSummary {
+    week: string;
+    hours: number;
+    fraction: number;
+}
+/** Aggregate weekly volume rows into a summary with relative fractions */
+export declare function aggregateWeeklyVolume(rows: Array<{
+    week: string;
+    hours: number;
+}>): WeekSummary[];
+/** Determine trend direction from two values */
+export declare function trendDirection(current: number, previous: number): "up" | "down" | "stable";
+/** Stress score (0-3 Whoop-like scale) with display classification. */
+export declare class StressScore {
+    readonly value: number;
+    constructor(value: number);
+    get color(): string;
+    get label(): string;
+}
+/** Get the color for a trend direction */
+export declare function trendColor(trend: "improving" | "worsening" | "stable" | "declining"): string;
+/** Get the color for a categorical readiness level (high/moderate/low) */
+export declare function readinessLevelColor(level: "high" | "moderate" | "low" | "unknown"): string;
+/** Get the color for a health metric status (excellent/good/fair/poor) */
+export declare function healthStatusColor(status: "excellent" | "good" | "fair" | "poor"): string;
+/** Get the color for a ramp rate value (always uses absolute value) */
+export declare function rampRateColor(rate: number): string;
+/**
+ * Map a z-score to a 0-100 recovery score using an asymmetric sigmoid.
+ * Tuned to match Whoop's recovery scoring:
+ *   z=0 (at baseline mean) → 62 (average day feels "recovered")
+ *   z=+1 → ~80, z=-1 → ~40
+ *   z=+2 → ~93, z=-2 → ~18
+ * Uses separate scales for positive/negative z to handle the asymmetric center.
+ */
+export declare function zScoreToRecoveryScore(zScore: number): number;
+/** Get the color for a sleep performance tier */
+export declare function sleepTierColor(tier: "Excellent" | "Good" | "Fair" | "Poor"): string;
+/** Get a contextual description for a sleep performance tier */
+export declare function sleepTierDescription(tier: "Excellent" | "Good" | "Fair" | "Poor"): string;
+/** Get the color for sleep debt in minutes */
+export declare function sleepDebtColor(minutes: number): string;
+/** Get the color for a sleep performance percentage (actual vs target) */
+export declare function sleepPerformanceColor(percentage: number): string;
+/** Form zone boundaries (intervals.icu defaults) */
+export declare const FORM_ZONE_TRANSITION = 25;
+export declare const FORM_ZONE_FRESH = 5;
+export declare const FORM_ZONE_GREY = -10;
+export declare const FORM_ZONE_OPTIMAL = -30;
+/** Colors for form (training stress balance) zones */
+export declare const FORM_ZONE_COLORS: {
+    readonly transition: "#60a5fa";
+    readonly fresh: "#16a34a";
+    readonly grey: "#a1a1aa";
+    readonly optimal: "#16a34a";
+    readonly highRisk: "#dc2626";
+};
+/** Form zone (training stress balance) classification with display properties. */
+export declare class FormZone {
+    readonly value: number;
+    constructor(value: number);
+    get color(): string;
+    get label(): string;
+}
+//# sourceMappingURL=scoring.d.ts.map