cards demo share: iOS lit the card black; Safari's bars; white flash on dark systems (#1017)

## What changed

Three fixes for the cards share page, found after #1016 went live.

- The card rendered nearly black on iOS. The studio environment maps
were `Float32` `DataTexture`s, and iOS Safari has no
`OES_texture_float_linear`, so the PMREM could not filter them and
sampled black; the card was lit by the one directional lamp alone. The
maps are now uploaded as half floats (`DataUtils.toHalfFloat`), which
every WebGL2 implementation filters. The desktop picture is unchanged.
- Grey bands above and below the page. Mobile Safari colors its status
bar and tab bar from the document background, which was the app body's
surface (`#1a1a1a` in dark) rather than the page's (`#111111`). The
share page's `html` and `body` now take its surface, and the page
exports its own `themeColor` (the root layout's `theme-color` metas
moved to a `viewport` export so the page-level one replaces them).

- White flash on a dark system (desktop). The page's surface and ink
were inline styles from a React state that started light and flipped in
an effect after hydration. They are now CSS custom properties keyed on
`html[data-theme]`, which the root layout's boot script sets before the
first paint, so the server's HTML paints in the right colors. The GL
reads the theme through `useSyncExternalStore` (client snapshot during
hydration, re-rendered before paint), and follows a theme switch.

## Test plan

- iOS 27 Simulator (iPhone 18 Pro), Safari, against the local dev
server: the green Buchi card is lit and legible in dark mode; status and
tab bar areas sample as the page color in both light (`#f8f8f7`) and
dark (`#111111`).
- Desktop Chromium: the playground stage in light and dark looks as
before the half-float change.
- CDP screencast of the page load in headless Chromium with
`colorScheme: dark`: production shows a light frame before hydration;
the branch shows only dark frames. SSR HTML carries no inline surface
style.
- `curl` of `/` and `/c/{slug}` shows the app's and the page's
`theme-color` tags respectively, no duplicates.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: patcapulong

components/grid-cards-demo/src/app/(share)/c/[slug]/ShareCard.module.scss

@@ -2,6 +2,12 @@
    rules, the card live in the middle, the brand left, the pitch right. */
 
 .root {
+  /* The surface and the ink, off the theme on <html> (set before the first
+     paint), so the server's HTML paints in the right colors. The same two
+     values as ShareCard.tsx's LIGHT_SURFACE / DARK_SURFACE palettes. */
+  --surface: #f8f8f7;
+  --ink: #1a1a1a;
+  --text-primary: var(--ink);
   --pad: 24px;
   --col-pad: 8px;
   /* Secondary type and the rules: the ink, stepped back (56% of #1a1a1a on
@@ -29,6 +35,11 @@
   -webkit-font-smoothing: antialiased;
 }
 
+:global(html[data-theme='dark']) .root {
+  --surface: #111111;
+  --ink: #f0f0ee;
+}
+
 /* ── The dot grid ──────────────────────────────────────────────────────── */
 
 /* The playground's WebGL dot grid, filling the card's column between its

components/grid-cards-demo/src/app/(share)/c/[slug]/ShareCard.tsx

@@ -17,7 +17,7 @@ import {
   useMemo,
   useRef,
   useState,
-  type CSSProperties,
+  useSyncExternalStore,
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
 } from 'react';
@@ -98,11 +98,14 @@ export function ShareCard({ design, brand, pitch, actions, alt }: ShareCardProps
   /** The card has been turned by hand once: the hint has done its job. */
   const [dragged, setDragged] = useState(false);
 
-  // The theme is on <html> (the root layout's boot script), read once mounted.
-  const [themeDark, setThemeDark] = useState(false);
-  useEffect(() => {
-    setThemeDark(document.documentElement.dataset.theme === 'dark');
-  }, []);
+  // The theme is on <html>, set by the root layout's boot script before the
+  // first paint. The page's colors come from the stylesheet off that
+  // attribute, so the server's HTML paints right; this reading is for the
+  // GL (the dot grid's surface, the card's exposure). The server's snapshot
+  // is light; the client's is read during hydration, and React re-renders
+  // before paint where they differ, so a dark system never sees a light
+  // frame. Subscribed, so a theme switch follows too.
+  const themeDark = useSyncExternalStore(subscribeTheme, readThemeDark, () => false);
   const palette = useMemo<Palette>(() => paletteOn(themeDark ? DARK_SURFACE : LIGHT_SURFACE), [themeDark]);
 
   const meshState = useMemo<CardMeshState>(
@@ -201,11 +204,6 @@ export function ShareCard({ design, brand, pitch, actions, alt }: ShareCardProps
   const onIntroDone = useCallback(() => setIntroDone(true), []);
 
   const foot = footprint(design.orientation);
-  const vars = {
-    '--surface': palette.bg,
-    '--ink': palette.ink,
-    '--text-primary': palette.ink,
-  } as CSSProperties;
 
   return (
     // The pointer is handled here, on the page: the stage paints over the
@@ -217,7 +215,6 @@ export function ShareCard({ design, brand, pitch, actions, alt }: ShareCardProps
         introDone && overCardNow && styles.overCard,
         dragging && styles.dragging,
       )}
-      style={vars}
       onPointerMove={onPointerMove}
       onPointerLeave={onPointerLeave}
       onPointerDown={onPointerDown}
@@ -313,6 +310,16 @@ function cardScale(w: number, h: number, foot: { w: number; h: number }): number
   return long / Math.max(foot.w, foot.h);
 }
 
+function readThemeDark(): boolean {
+  return document.documentElement.dataset.theme === 'dark';
+}
+
+function subscribeTheme(onChange: () => void): () => void {
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+  return () => observer.disconnect();
+}
+
 /** A perspective camera whose view at z = 0 is exactly the stage in px. */
 function StageCamera({ exposure }: { exposure: number }) {
   const camera = useThree((s) => s.camera) as THREE.PerspectiveCamera;

components/grid-cards-demo/src/app/(share)/c/[slug]/page.tsx

@@ -1,4 +1,4 @@
-import type { Metadata } from 'next';
+import type { Metadata, Viewport } from 'next';
 import { headers } from 'next/headers';
 import { notFound } from 'next/navigation';
 import { shareStore } from '@/lib/share/store';
@@ -26,6 +26,15 @@ function first(v: string | string[] | undefined): string | undefined {
   return Array.isArray(v) ? v[0] : v;
 }
 
+/** Mobile Safari's bars take the page's own surface (share.scss's), so the
+ *  page runs under them in one color. */
+export const viewport: Viewport = {
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#f8f8f7' },
+    { media: '(prefers-color-scheme: dark)', color: '#111111' },
+  ],
+};
+
 export async function generateMetadata({ params }: Pick<Props, 'params'>): Promise<Metadata> {
   const record = await shareStore().get(params.slug);
   if (!record) return {};

components/grid-cards-demo/src/app/(share)/share.scss

@@ -16,3 +16,11 @@ html[data-theme='dark'] {
   --share-text-secondary: #9a9a9a;
   --share-border: rgba(255, 255, 255, 0.1);
 }
+
+/* The document itself takes the page's surface. Mobile Safari colors the
+   status bar and the tab bar from it, and the app's body surface (a step
+   lighter in dark) showed as grey bands above and below the page. */
+html,
+body {
+  background: var(--share-bg);
+}

components/grid-cards-demo/src/app/layout.tsx

@@ -1,4 +1,4 @@
-import type { Metadata } from 'next';
+import type { Metadata, Viewport } from 'next';
 import { GeistSans } from 'geist/font/sans';
 import { easingVarsStylesheet } from '@/lib/easing';
 import { CONFIGURE_COL_PX, LAYOUT_WIDE_PX, NAV_COLLAPSED_MAX_PX } from '@/lib/layout';
@@ -8,6 +8,15 @@ const TITLE = 'Lightspark Cards — Playground';
 const DESCRIPTION =
   'Issue a branded Visa debit card and watch the API calls fire as you go.';
 
+/** The browser chrome's color (mobile Safari's bars): the app's surfaces.
+ *  A page whose surface differs (the share page) exports its own. */
+export const viewport: Viewport = {
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#F0F0EE' },
+    { media: '(prefers-color-scheme: dark)', color: '#111111' },
+  ],
+};
+
 export const metadata: Metadata = {
   // Absolute base for social-card image URLs (scrapers need full URLs).
   // VERCEL_PROJECT_PRODUCTION_URL covers previews; the default is prod.
@@ -35,8 +44,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en" className={GeistSans.variable} suppressHydrationWarning>
       <head>
-        <meta name="theme-color" content="#F0F0EE" media="(prefers-color-scheme: light)" />
-        <meta name="theme-color" content="#111111" media="(prefers-color-scheme: dark)" />
         {/* Preload the two variable fonts (every weight of Suisse Intl and of
             its Mono) so the first paint shows the real font sooner.
             crossOrigin is required even though the fonts are same-origin:

components/grid-cards-demo/src/components/CardStage/card3d/CardEnv.tsx

@@ -57,6 +57,23 @@ function base(y: number): [number, number, number] {
   return stops[stops.length - 1][1];
 }
 
+/** The radiance as an equirectangular texture, in half floats. Not single
+ *  floats: iOS Safari cannot filter those (no OES_texture_float_linear), so
+ *  the PMREM sampled black and the card was lit by the one lamp alone.
+ *  Half floats filter everywhere three runs, and hold the range here. */
+function equirect(data: Float32Array, w: number, h: number): THREE.DataTexture {
+  const half = new Uint16Array(data.length);
+  for (let i = 0; i < data.length; i++) half[i] = THREE.DataUtils.toHalfFloat(data[i]);
+  const t = new THREE.DataTexture(half, w, h, THREE.RGBAFormat, THREE.HalfFloatType);
+  t.mapping = THREE.EquirectangularReflectionMapping;
+  t.colorSpace = THREE.LinearSRGBColorSpace;
+  t.magFilter = THREE.LinearFilter;
+  t.minFilter = THREE.LinearFilter;
+  t.generateMipmaps = false;
+  t.needsUpdate = true;
+  return t;
+}
+
 // The maps are painted in JavaScript, half a million texels each with a few
 // lights or panels apiece. The loops keep the trigonometry out of the texel:
 // what depends on the row or the column alone is taken once per row or
@@ -121,14 +138,7 @@ function studioTexture(): THREE.DataTexture {
       data[o + 3] = 1;
     }
   }
-  const t = new THREE.DataTexture(data, ENV_W, ENV_H, THREE.RGBAFormat, THREE.FloatType);
-  t.mapping = THREE.EquirectangularReflectionMapping;
-  t.colorSpace = THREE.LinearSRGBColorSpace;
-  t.magFilter = THREE.LinearFilter;
-  t.minFilter = THREE.LinearFilter;
-  t.generateMipmaps = false;
-  t.needsUpdate = true;
-  return t;
+  return equirect(data, ENV_W, ENV_H);
 }
 
 /**
@@ -240,14 +250,7 @@ function panelStudio(panels: Panel[], base: (y: number) => number, w: number, h:
       data[o + 3] = 1;
     }
   }
-  const t = new THREE.DataTexture(data, w, h, THREE.RGBAFormat, THREE.FloatType);
-  t.mapping = THREE.EquirectangularReflectionMapping;
-  t.colorSpace = THREE.LinearSRGBColorSpace;
-  t.magFilter = THREE.LinearFilter;
-  t.minFilter = THREE.LinearFilter;
-  t.generateMipmaps = false;
-  t.needsUpdate = true;
-  return t;
+  return equirect(data, w, h);
 }
 
 export function foilStudioTexture(): THREE.DataTexture {