From a2468329bf097b03bfe3055cef00ea699911d0bc Mon Sep 17 00:00:00 2001
From: SandObserver <260779319+SandObserver@users.noreply.github.com>
Date: Sun, 20 Sep 2026 00:41:18 -0400
Subject: [PATCH] Pin the preview card to the widget's own manifest

A widget with no light design rendered light on a light docs page. The card and
the dark-only flag now come from the widget manifest, and the preview card
colours match the product's.
---
 src/components/WidgetGroup.astro   |  8 +++++--
 src/components/WidgetPreview.astro |  8 +++++--
 src/lib/widget-manifest.ts         | 19 +++++++++++++++
 src/styles/docs.css                | 37 +++++++++++++++++-------------
 4 files changed, 52 insertions(+), 20 deletions(-)
 create mode 100644 src/lib/widget-manifest.ts

diff --git a/src/components/WidgetGroup.astro b/src/components/WidgetGroup.astro
index d1e73b1..fec794b 100644
--- a/src/components/WidgetGroup.astro
+++ b/src/components/WidgetGroup.astro
@@ -1,11 +1,13 @@
 ---
+import { manifestCard } from '../lib/widget-manifest';
+
 /* Geometry must match WidgetPreview. See the note there. */
 interface Item {
   type: string;
   file: string;
   id: string;
   size?: 'small' | 'medium';
-  card?: 'dark' | 'light' | 'translucent' | null;
+  card?: 'dark' | 'graphite' | 'light' | 'translucent' | null;
   title: string;
   label?: string;
 }
@@ -37,6 +39,7 @@ const built = items.map((it) => {
     tx: (w - dw * scale) / 2,
     ty: (CARD_H - dh * scale) / 2,
     src: `/widgets/${it.type}/${it.file}?id=${encodeURIComponent(it.id)}&size=${size}&lang=en`,
+    declared: manifestCard(it.type, it.file),
   };
 });
 ---
@@ -49,7 +52,8 @@ const built = items.map((it) => {
           <div class="wpv__slot">
             <div
               class="wpv__card"
-              data-card={b.card ?? undefined}
+              data-card={b.card ?? b.declared.card ?? undefined}
+              data-appearance={b.declared.appearance}
               style={`width:${b.w}px;height:${CARD_H}px;border-radius:${RADIUS}px;`}
             >
               <iframe
diff --git a/src/components/WidgetPreview.astro b/src/components/WidgetPreview.astro
index 81c39b5..cdfbb59 100644
--- a/src/components/WidgetPreview.astro
+++ b/src/components/WidgetPreview.astro
@@ -1,4 +1,6 @@
 ---
+import { manifestCard } from '../lib/widget-manifest';
+
 /* Geometry mirrors the product and must stay in step with it: the design
    canvas from WIDGET_DESIGN, the card width from the 1041px six-column grid,
    WIDGET_HEIGHTS for height, WIDGET_R for the corner, and mountScaledWidget's
@@ -8,12 +10,13 @@ interface Props {
   file: string;
   id: string;
   size?: 'small' | 'medium';
-  card?: 'dark' | 'light' | 'translucent' | null;
+  card?: 'dark' | 'graphite' | 'light' | 'translucent' | null;
   title: string;
   caption?: string;
 }
 
 const { type, file, id, size = 'small', card = null, title, caption } = Astro.props;
+const declared = manifestCard(type, file);
 
 const DESIGN = { small: [170, 170], medium: [360, 170] } as const;
 const CARD_W = { small: 152.67, medium: 330.34 } as const;
@@ -33,7 +36,8 @@ const src = `/widgets/${type}/${file}?id=${encodeURIComponent(id)}&size=${size}&
   <div class="wpv__mat">
     <div
       class="wpv__card"
-      data-card={card ?? undefined}
+      data-card={card ?? declared.card ?? undefined}
+      data-appearance={declared.appearance}
       style={`width:${w}px;height:${CARD_H}px;border-radius:${RADIUS}px;`}
     >
       <iframe
diff --git a/src/lib/widget-manifest.ts b/src/lib/widget-manifest.ts
new file mode 100644
index 0000000..e606bd1
--- /dev/null
+++ b/src/lib/widget-manifest.ts
@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The card and the dark-only flag a widget declares, so a preview cannot drift
+    from the product. `file` picks the view when the widget has several. */
+export function manifestCard(type: string, viewFile: string) {
+  try {
+    /* From the project root: import.meta.url points into the build output. */
+    const file = path.join(process.cwd(), 'public', 'widgets', type, 'widget.json');
+    const m = JSON.parse(readFileSync(file, 'utf8'));
+    const view = Object.values(m.views ?? {}).find((v: any) => v?.src === viewFile) as any;
+    return {
+      card: (view?.card ?? m.card ?? null) as string | null,
+      appearance: m.appearance === 'dark' ? 'dark' : undefined,
+    };
+  } catch {
+    return { card: null, appearance: undefined };
+  }
+}
diff --git a/src/styles/docs.css b/src/styles/docs.css
index 98240c6..b7bc9c5 100644
--- a/src/styles/docs.css
+++ b/src/styles/docs.css
@@ -797,30 +797,35 @@ starlight-toc nav a {
   .wpv__mat > * {
     position: relative;
   }
+  /* The product's card colours. A widget with no light design, and one that
+     names a card, keeps the same colour in both docs themes. */
   .wpv__card {
     position: relative;
     overflow: hidden;
     flex-shrink: 0;
-      border: 1px solid rgba(255, 255, 255, 0.09);
-    background: rgba(0, 0, 0, 0.32);
-    -webkit-backdrop-filter: blur(16px) saturate(140%);
-    backdrop-filter: blur(16px) saturate(140%);
-  }
-  .wpv__card[data-card='dark'] {
+    border: 1px solid rgba(255, 255, 255, 0.09);
     background: #1c1c1e;
-    -webkit-backdrop-filter: none;
-    backdrop-filter: none;
   }
-  .wpv__card[data-card='light'] {
+  :root[data-theme='light'] .wpv__card {
+    border-color: rgba(0, 0, 0, 0.06);
     background: #ffffff;
-    border-color: rgba(0, 0, 0, 0.12);
-    -webkit-backdrop-filter: none;
-    backdrop-filter: none;
   }
-  .wpv__card[data-card='translucent'] {
-    background: rgba(0, 0, 0, 0.25);
-    -webkit-backdrop-filter: blur(22px) saturate(140%);
-    backdrop-filter: blur(22px) saturate(140%);
+  .wpv__card[data-appearance='dark'],
+  .wpv__card[data-card='dark'],
+  :root[data-theme='light'] .wpv__card[data-appearance='dark'],
+  :root[data-theme='light'] .wpv__card[data-card='dark'] {
+    border-color: rgba(255, 255, 255, 0.09);
+    background: #1c1c1e;
+  }
+  .wpv__card[data-card='graphite'],
+  :root[data-theme='light'] .wpv__card[data-card='graphite'] {
+    border-color: rgba(255, 255, 255, 0.09);
+    background: #2c2c2e;
+  }
+  .wpv__card[data-card='light'],
+  :root[data-theme='light'] .wpv__card[data-card='light'] {
+    border-color: rgba(0, 0, 0, 0.12);
+    background: #ffffff;
   }
   .wpv__card iframe {
     position: absolute;