From 38c00100d0fc0bececb2e02db0ec21c8c299727a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Sun, 28 Jun 2026 18:29:39 +0200
Subject: [PATCH] fix(insights): sleep-debt explainer on the resolved card;
 Skeleton primitive for the narrative loader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sleep-debt computed-engine InfoHint only rendered in the still-learning
state — but the resolved full-debt card is the common case and where the
figure most needs the 'this is our own estimate, not a wearable's native
number' context. Show it there too. Separately, swap the period-narrative
loading shell's hand-rolled muted divs for the shared Skeleton primitive
so its shimmer matches every other loader.
---
 src/components/insights/period-narrative-card.tsx | 7 ++++---
 src/components/insights/sleep/sleep-debt-card.tsx | 7 +++++++
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/components/insights/period-narrative-card.tsx b/src/components/insights/period-narrative-card.tsx
index 47ffa3cde..222401b94 100644
--- a/src/components/insights/period-narrative-card.tsx
+++ b/src/components/insights/period-narrative-card.tsx
@@ -9,6 +9,7 @@ import { formatUpdatedLabel } from "@/lib/i18n/relative-time";
 import { queryKeys } from "@/lib/query-keys";
 import { useAuth } from "@/hooks/use-auth";
 import { cn } from "@/lib/utils";
+import { Skeleton } from "@/components/ui/skeleton";
 import { SectionHeading } from "@/components/insights/section-heading";
 import { AskCoachAction } from "@/components/insights/ask-coach-action";
 import { ProseBlocks } from "@/components/insights/prose-blocks";
@@ -108,9 +109,9 @@ export function PeriodNarrativeCard({
           aria-hidden="true"
           className={SKELETON_SHELL}
         >
-          <div className="bg-muted/40 h-4 w-full rounded" />
-          <div className="bg-muted/40 h-4 w-5/6 rounded" />
-          <div className="bg-muted/40 h-4 w-2/3 rounded" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-5/6" />
+          <Skeleton className="h-4 w-2/3" />
         </div>
       </section>
     );
diff --git a/src/components/insights/sleep/sleep-debt-card.tsx b/src/components/insights/sleep/sleep-debt-card.tsx
index db4d329cb..cb246d5d5 100644
--- a/src/components/insights/sleep/sleep-debt-card.tsx
+++ b/src/components/insights/sleep/sleep-debt-card.tsx
@@ -70,6 +70,13 @@ export function SleepDebtCard({ debt }: { debt: SleepDebtDto }) {
           <CardTitle className="text-base font-semibold">
             {t("insights.sleep.debt.title")}
           </CardTitle>
+          {/* v1.25.0 — the resolved full-debt card is the common case and the
+              place the figure most needs context: explain the COMPUTED engine
+              and that it differs from a wearable's native number here too, not
+              only in the still-learning `partial` state above. */}
+          {debt.source === "COMPUTED" ? (
+            <InfoHint label={t("insights.sleep.debt.computedInfo")} />
+          ) : null}
         </div>
       </CardHeader>
       <CardContent>