dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/shotcraft/upstream/template/src/aifl/Caption.tsx

@@ -0,0 +1,65 @@
+import { useVisualTheme, sceneDefaults } from '../themes/visual-theme';
+import { interpolate, useCurrentFrame } from 'remotion';
+
+
+/** Context-level defaults, editable per clip in the workbench (hex = sRGB of the oklch tokens). */
+export const CAPTION_DEFAULTS = {
+  bottom: 72,
+  fontSize: 22,
+  color: '#575552',  // oklch(45% 0.006 82)
+  accent: '#955905', // oklch(52% 0.115 65)
+};
+
+/** Screen-space narration caption: a mono UI info-strip at the bottom of the
+ * frame, led by a small amber square. Fades/rises in over 8 frames and fades
+ * out over the last 8 of its window. */
+export const Caption: React.FC<{
+  text: string;
+  duration: number;
+  bottom?: number;
+  fontSize?: number;
+  color?: string;
+  accent?: string;
+}> = (props) => {
+  const theme = useVisualTheme();
+  const paperStyle = theme.id === 'ink-press';
+  const MONO = (paperStyle ? 'ui-monospace, SFMono-Regular, Menlo, monospace' : theme.font);
+  const {text, duration, ...style} = props;
+  const {fontSize, color, accent, bottom} = {...sceneDefaults(theme, 'caption', CAPTION_DEFAULTS), ...style};
+  const frame = useCurrentFrame();
+  const inT = interpolate(frame, [0, 8], [0, 1], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  const outT = interpolate(frame, [duration - 8, duration], [1, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom,
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'baseline',
+        gap: 14,
+        fontFamily: MONO,
+        fontSize,
+        letterSpacing: paperStyle ? '0.14em' : '0.015em',
+        ...(!paperStyle ? {left: '50%', right: 'auto', width: 'max-content', maxWidth: '90%', padding: '8px 18px', borderRadius: 8, background: theme.surface, border: `1px solid ${theme.border}`, fontWeight: 500, lineHeight: 1.2} : {}),
+        textTransform: 'uppercase',
+        color,
+        opacity: inT * outT,
+        transform: paperStyle ? `translateY(${(1 - inT) * 8}px)` : `translate(-50%, ${(1 - inT) * 8}px)`,
+        pointerEvents: 'none',
+      }}
+    >
+      <span style={{ width: 6, height: 6, background: accent, display: 'inline-block' }} />
+      <span>{text}</span>
+    </div>
+  );
+};

package/lib/motion/shotcraft/upstream/template/src/aifl/DigitRoll.tsx

@@ -0,0 +1,48 @@
+import { useVisualTheme } from '../themes/visual-theme';
+import { interpolate, useCurrentFrame, Easing } from 'remotion';
+
+const DIGITS = '0123456789';
+
+/** Odometer-style digit column roll for monospace numerals. */
+export const DigitRoll: React.FC<{
+  value: string;
+  delay?: number;
+  fontSize?: number;
+  color?: string;
+}> = ({ value, delay = 0, fontSize = 30, color = 'oklch(52% 0.115 65)' }) => {
+  const theme = useVisualTheme();
+  const paperStyle = theme.id === 'ink-press';
+
+  const frame = useCurrentFrame();
+  const lineH = fontSize * 1.15;
+  return (
+    <span style={{ fontFamily: paperStyle ? undefined : theme.font, display: 'inline-flex', overflow: 'hidden', height: lineH, verticalAlign: 'bottom' }}>
+      {value.split('').map((ch, i) => {
+        const target = DIGITS.indexOf(ch);
+        if (target < 0) {
+          return (
+            <span key={i} style={{ fontSize, lineHeight: `${lineH}px`, color }}>{ch}</span>
+          );
+        }
+        const t = interpolate(frame, [delay + i * 4, delay + i * 4 + 22], [0, 1], {
+          extrapolateLeft: 'clamp',
+          extrapolateRight: 'clamp',
+          easing: Easing.bezier(0.25, 0.8, 0.25, 1),
+        });
+        // roll through one full strip then land on the target digit
+        const offset = (10 + target) * t * lineH;
+        return (
+          <span key={i} style={{ display: 'inline-block', height: lineH }}>
+            <span style={{ display: 'block', transform: `translateY(${-offset}px)` }}>
+              {(DIGITS + DIGITS).split('').map((d, j) => (
+                <span key={j} style={{ display: 'block', fontSize, lineHeight: `${lineH}px`, color, fontVariantNumeric: 'tabular-nums' }}>
+                  {d}
+                </span>
+              ))}
+            </span>
+          </span>
+        );
+      })}
+    </span>
+  );
+};

package/lib/motion/shotcraft/upstream/template/src/aifl/FlashCut.tsx

@@ -0,0 +1,24 @@
+import { useVisualTheme, themePaint } from '../themes/visual-theme';
+import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion';
+
+/** Bright-field cut: a warm-white bloom that flashes over the hard cut. */
+export const FlashCut: React.FC<{ duration?: number }> = ({ duration = 10 }) => {
+  const theme = useVisualTheme();
+  const paperStyle = theme.id === 'ink-press';
+  const paint = (css: string) => themePaint(theme, css);
+
+  const frame = useCurrentFrame();
+  const o = interpolate(frame, [0, duration * 0.4, duration], [0, paperStyle ? 0.85 : 0.24, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  return (
+    <AbsoluteFill
+      style={{
+        pointerEvents: 'none',
+        opacity: o,
+        background: paint('radial-gradient(ellipse at 50% 45%, rgba(255,248,235,0.98), rgba(255,244,224,0.55) 55%, transparent 80%)'),
+      }}
+    />
+  );
+};

package/lib/motion/shotcraft/upstream/template/src/aifl/Main.tsx

@@ -0,0 +1,192 @@
+import { useVisualTheme, themePaint, themeAsset } from '../themes/visual-theme';
+import { AbsoluteFill, Audio, Sequence } from 'remotion';
+import { SceneOpen } from './live/SceneOpen';
+import { SceneFlyIn } from './live/SceneFlyIn';
+import { SceneDetail } from './live/SceneDetail';
+import { ScenePapers } from './live/ScenePapers';
+import { SceneWbr } from './live/SceneWbr';
+import { PaperTitleCard } from './PaperTitleCard';
+import { SceneOutroLive } from './live/SceneOutroLive';
+import { FlashCut } from './FlashCut';
+import { Caption } from './Caption';
+
+// ~36.2s @ 30fps — paper-and-ink morning reading room (10 shots). Both wordmark
+// moments (brand open, outro sign-off) hold a full second once fully on.
+export const AIFL_SHOTS = {
+  morning: { from: 0, duration: 220 },  // 0–7.3s  brand ~46f + 30f hold + 138f macro
+  card1: { from: 220, duration: 55 },   // 7.3–9.2s "All your team's research, one place to go."
+  table: { from: 275, duration: 190 },  // 9.2–15.5s pile close-up → deal → scroll → search → filter → click
+  macro: { from: 465, duration: 100 },  // 15.5–18.8s macro card detail, rows reveal
+  card2: { from: 565, duration: 55 },   // 18.8–20.7s "Paper Radar, tailored for your morning reading."
+  chart: { from: 620, duration: 105 },  // 20.7–24.2s papers stack radar
+  cardWbr: { from: 725, duration: 50 }, // 24.2–25.8s "Every project, linked to your weekly report."
+  wbr: { from: 775, duration: 110 },    // 25.8–29.5s weekly report / collaborative write
+  card3: { from: 885, duration: 55 },   // 29.5–31.3s "The whole team, on the same page."
+  outro: { from: 940, duration: 145 },  // 31.3–36.2s defocus + letterpress sign-off (+1s hold)
+} as const; // sum = 1085
+
+export const AIFL_TOTAL = 1085;
+
+// title-card copy: space-separated words, `*word*` = amber italic accent. Single
+// source for the render below and for the workbench manifest (workbench.ts).
+export const TITLE_CARDS = {
+  card1: { text: 'All your team’s research, *one* place to go.' },
+  card2: { text: 'Paper *Radar,* tailored for your morning reading.', sub: 'of 31 fetched today', subDigits: '5' },
+  cardWbr: { text: 'Every project, *linked* to your weekly report.' },
+  card3: { text: 'The whole team, on the *same* page.' },
+} as const;
+
+export const parseWords = (text: string): { text: string; accent?: boolean }[] =>
+  text
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => {
+      const m = w.match(/^\*(.+)\*$/);
+      return m ? { text: m[1], accent: true } : { text: w };
+    });
+
+// warm flash cuts straddle these hard cuts (from = cut − 5, 10f long)
+export const FLASH_CUTS = [AIFL_SHOTS.table.from, AIFL_SHOTS.macro.from, AIFL_SHOTS.chart.from, AIFL_SHOTS.wbr.from];
+
+// keyboard: 24f for the short search-box typing, 44f under the wbr writing
+// reveals; everything else plays out (≤3s assets)
+export const sfxDuration = (s: { from: number; src: string }) =>
+  s.src === 'keyboard.mp3' ? (s.from > 700 ? 44 : 24) : 90;
+
+// bottom-strip narration over the live shots (absolute frames; outro stays clean)
+export const CAPTIONS = [
+  { from: 90, duration: 40, text: 'TEN LIVE PROJECTS · FOUR RESEARCHERS' },
+  // (the hero-card hover annotation lives inside SceneOpen as a 3D floating note)
+  { from: 318, duration: 44, text: 'NEW WORK LANDS ALL WEEK' },
+  { from: 395, duration: 55, text: 'SEARCH · FILTER · OPEN' },
+  { from: 477, duration: 68, text: 'EVERY QUESTION, TRACKED TO ITS EXPERIMENTS' },
+  { from: 633, duration: 72, text: 'THE DAILY PAPER RADAR' },
+  { from: 789, duration: 78, text: 'FOUR VOICES, ONE WEEKLY BRIEF' },
+] as const;
+
+// sound design pinned to animation beats (absolute frames, Mixkit license).
+// Classic product-promo vocabulary: whooshes on camera moves, cinematic
+// impacts on landings, a riser into the finale, sparkle on the reveal.
+export const SFX: { from: number; src: string; volume: number }[] = [
+  // brand open: soft transition as the lockup lands, whoosh into the console
+  { from: 12, src: 'transition-soft.mp3', volume: 0.4 },
+  { from: 78, src: 'whoosh-fast.mp3', volume: 0.45 }, // brand → dashboard
+  // hero card: whoosh up on the pop, sparkle on the beam scan, impact reseat
+  { from: 127, src: 'whoosh-big.mp3', volume: 0.5 },
+  { from: 141, src: 'sparkle.mp3', volume: 0.35 },
+  { from: 204, src: 'transition-snap.mp3', volume: 0.5 },
+  // title cards ride a quick swoosh
+  { from: 220, src: 'swoosh-quick.mp3', volume: 0.4 },
+  // deck shot: soft transition into the pile close-up, whoosh as the orbit
+  // pulls back and dealing starts, fast whooshes as the deal accelerates,
+  // then the scroll rest → big whoosh back up to the search bar
+  { from: 277, src: 'transition-soft.mp3', volume: 0.4 }, // pile close-up
+  { from: 308, src: 'whoosh-big.mp3', volume: 0.5 }, // pull-back + first deals
+  { from: 340, src: 'whoosh-fast.mp3', volume: 0.4 }, // dealing accelerates
+  { from: 356, src: 'whoosh-fast.mp3', volume: 0.32 }, // full flurry
+  { from: 388, src: 'whoosh-big.mp3', volume: 0.5 }, // swoosh back to header
+  // typing (slower now, 3f/char) + a breath + filter + click
+  { from: 401, src: 'keyboard.mp3', volume: 0.4 }, // trimmed by sequence length
+  { from: 435, src: 'whoosh-fast.mp3', volume: 0.4 }, // grid filters away
+  { from: 451, src: 'click-camera.mp3', volume: 0.6 }, // click on the result card
+  { from: 455, src: 'swoosh-quick.mp3', volume: 0.35 }, // push-in
+  // detail rows embed with one cinematic transition sweep
+  { from: 475, src: 'transition-soft.mp3', volume: 0.45 },
+  { from: 565, src: 'swoosh-quick.mp3', volume: 0.4 }, // title card 2
+  // papers stack: soft transition, camera-click as the counter settles
+  { from: 623, src: 'transition-soft.mp3', volume: 0.45 },
+  { from: 648, src: 'click-camera.mp3', volume: 0.45 },
+  { from: 725, src: 'swoosh-quick.mp3', volume: 0.4 }, // wbr title card
+  // wbr: the page "writes itself" over live keyboard typing, then past weeks
+  // pop into the left rail one by one (a pop per landing)
+  { from: 779, src: 'transition-soft.mp3', volume: 0.4 },
+  { from: 781, src: 'keyboard.mp3', volume: 0.34 }, // trimmed to the writing reveals
+  { from: 840, src: 'pop.mp3', volume: 0.4 },
+  { from: 845, src: 'pop.mp3', volume: 0.37 },
+  { from: 850, src: 'pop.mp3', volume: 0.34 },
+  { from: 855, src: 'pop.mp3', volume: 0.31 },
+  { from: 860, src: 'pop.mp3', volume: 0.28 },
+  { from: 865, src: 'pop.mp3', volume: 0.25 },
+  { from: 885, src: 'swoosh-quick.mp3', volume: 0.4 }, // title card 3
+  // outro: riser under the assembly, big impact when the wordmark stamps
+  { from: 945, src: 'riser-cine.mp3', volume: 0.5 },
+  { from: 980, src: 'impact-cine.mp3', volume: 0.55 },
+  { from: 1005, src: 'sparkle.mp3', volume: 0.3 }, // rule + tagline glint
+];
+
+export const AiflMain: React.FC = () => {
+  const theme = useVisualTheme();
+  const paint = (css: string) => themePaint(theme, css);
+  const asset = (src: string) => themeAsset(theme, src);
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: paint('#f2eee6') }}>
+      {/* beat-pinned promo sound effects (no music bed — SFX only) */}
+      {SFX.map((s, i) => (
+        <Sequence
+          key={`sfx-${i}`}
+          from={s.from}
+          durationInFrames={sfxDuration(s)}
+        >
+          <Audio src={asset(`audio/${s.src}`)} volume={s.volume} />
+        </Sequence>
+      ))}
+      <Sequence from={AIFL_SHOTS.morning.from} durationInFrames={AIFL_SHOTS.morning.duration}>
+        <SceneOpen />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.card1.from} durationInFrames={AIFL_SHOTS.card1.duration}>
+        <PaperTitleCard
+          duration={AIFL_SHOTS.card1.duration}
+          words={parseWords(TITLE_CARDS.card1.text)}
+        />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.table.from} durationInFrames={AIFL_SHOTS.table.duration}>
+        <SceneFlyIn />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.macro.from} durationInFrames={AIFL_SHOTS.macro.duration}>
+        <SceneDetail />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.card2.from} durationInFrames={AIFL_SHOTS.card2.duration}>
+        <PaperTitleCard
+          duration={AIFL_SHOTS.card2.duration}
+          words={parseWords(TITLE_CARDS.card2.text)}
+          sub={TITLE_CARDS.card2.sub}
+          subDigits={TITLE_CARDS.card2.subDigits}
+        />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.chart.from} durationInFrames={AIFL_SHOTS.chart.duration}>
+        <ScenePapers />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.cardWbr.from} durationInFrames={AIFL_SHOTS.cardWbr.duration}>
+        <PaperTitleCard
+          duration={AIFL_SHOTS.cardWbr.duration}
+          words={parseWords(TITLE_CARDS.cardWbr.text)}
+        />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.wbr.from} durationInFrames={AIFL_SHOTS.wbr.duration}>
+        <SceneWbr />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.card3.from} durationInFrames={AIFL_SHOTS.card3.duration}>
+        <PaperTitleCard
+          duration={AIFL_SHOTS.card3.duration}
+          words={parseWords(TITLE_CARDS.card3.text)}
+        />
+      </Sequence>
+      <Sequence from={AIFL_SHOTS.outro.from} durationInFrames={AIFL_SHOTS.outro.duration}>
+        <SceneOutroLive />
+      </Sequence>
+      {/* narration captions over the live shots (under the flash cuts) */}
+      {CAPTIONS.map((c) => (
+        <Sequence key={c.from} from={c.from} durationInFrames={c.duration}>
+          <Caption text={c.text} duration={c.duration} />
+        </Sequence>
+      ))}
+      {/* warm flash cuts straddling scene changes */}
+      {FLASH_CUTS.map((cut) => (
+        <Sequence key={cut} from={cut - 5} durationInFrames={10}>
+          <FlashCut duration={10} />
+        </Sequence>
+      ))}
+    </AbsoluteFill>
+  );
+};

package/lib/motion/shotcraft/upstream/template/src/aifl/PaperTitleCard.tsx

@@ -0,0 +1,111 @@
+import { useVisualTheme, themePaint, sceneDefaults } from '../themes/visual-theme';
+import { AbsoluteFill, interpolate, useCurrentFrame, Easing } from 'remotion';
+import { DigitRoll } from './DigitRoll';
+
+
+/** Context-level defaults (copy size / palette). Exposed as props so the
+ * workbench can edit them per clip; the motion timing stays fixed. Hex values
+ * are the sRGB renderings of the original oklch tokens. */
+export const TITLE_CARD_DEFAULTS = {
+  fontSize: 116,
+  ink: '#13110f',    // oklch(18% 0.006 82)
+  accent: '#955905', // oklch(52% 0.115 65)
+  muted: '#65635f',  // oklch(50% 0.006 82)
+  paper: '#f9f6f1',  // oklch(97.5% 0.008 82)
+};
+
+/**
+ * Paper title card: warm paper field, serif statement letterpressed word by
+ * word, amber italic accent word, amber underline growing beneath.
+ */
+export const PaperTitleCard: React.FC<{
+  duration: number;
+  words: { text: string; accent?: boolean }[];
+  sub?: string;
+  subDigits?: string;
+  fontSize?: number;
+  ink?: string;
+  accent?: string;
+  muted?: string;
+  paper?: string;
+}> = (props) => {
+  const theme = useVisualTheme();
+  const paperStyle = theme.id === 'ink-press';
+  const paint = (css: string) => themePaint(theme, css);
+  const SERIF = paperStyle ? 'ui-serif, Georgia, "Times New Roman", serif' : theme.font;
+  const MONO = (paperStyle ? 'ui-monospace, SFMono-Regular, Menlo, monospace' : theme.font);
+  const {duration, words, sub, subDigits, ...style} = props;
+  const {fontSize, ink, accent, muted, paper} = {...sceneDefaults(theme, 'title-card', TITLE_CARD_DEFAULTS), ...style};
+  const frame = useCurrentFrame();
+  const fadeOut = interpolate(frame, [duration - 8, duration], [1, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  const underline = interpolate(frame, [16, 34], [0, 1], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+    easing: Easing.bezier(0.3, 0, 0.2, 1),
+  });
+  const subT = interpolate(frame, [10, 22], [0, 1], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+
+  return (
+    <AbsoluteFill
+      style={{
+        backgroundColor: paper,
+        justifyContent: 'center',
+        alignItems: 'center',
+        opacity: fadeOut,
+        backgroundImage: paint('radial-gradient(1100px 750px at 50% 42%, oklch(99.3% 0.014 88 / 0.85), transparent 65%)'),
+      }}
+    >
+      <div style={{ textAlign: 'center', maxWidth: 1500 }}>
+        <div
+          style={{
+            fontFamily: SERIF, fontSize, fontWeight: 600, lineHeight: 1.14,
+            color: ink, letterSpacing: '-0.012em',
+            display: 'flex', flexWrap: 'wrap', justifyContent: 'center', columnGap: '0.26em',
+          }}
+        >
+          {words.map((w, i) => {
+            const delay = 4 + i * 4;
+            const t = interpolate(frame, [delay, delay + 9], [0, 1], {
+              extrapolateLeft: 'clamp',
+              extrapolateRight: 'clamp',
+              easing: Easing.bezier(0.2, 0.75, 0.3, 1),
+            });
+            return (
+              <span
+                key={i}
+                style={{
+                  opacity: t,
+                  transform: `scale(${1.28 - 0.28 * t})`,
+                  filter: `blur(${(1 - t) * 7}px)`,
+                  display: 'inline-block',
+                  fontStyle: paperStyle && w.accent ? 'italic' : 'normal',
+                  color: w.accent ? accent : undefined,
+                }}
+              >
+                {w.text}
+              </span>
+            );
+          })}
+        </div>
+        <div
+          style={{
+            height: 6, width: 220, margin: '38px auto 0', borderRadius: 3,
+            background: accent, transform: `scaleX(${underline})`,
+          }}
+        />
+        {sub ? (
+          <div style={{ fontFamily: MONO, fontSize: paperStyle ? 26 : 44, letterSpacing: '0.12em', color: muted, marginTop: 34, opacity: subT, textTransform: 'uppercase', display: 'flex', justifyContent: 'center', alignItems: 'baseline', gap: '0.5em' }}>
+            {subDigits ? <DigitRoll value={subDigits} delay={12} fontSize={paperStyle ? 26 : 44} color={accent} /> : null}
+            <span>{sub}</span>
+          </div>
+        ) : null}
+      </div>
+    </AbsoluteFill>
+  );
+};

package/lib/motion/shotcraft/upstream/template/src/aifl/live/PageCam.tsx

@@ -0,0 +1,150 @@
+import { useVisualTheme, themePaint, themeAsset } from '../../themes/visual-theme';
+import { AbsoluteFill, Img, interpolate, staticFile, useCurrentFrame, Easing } from 'remotion';
+
+export type CamKey = {
+  frame: number;
+  cx: number;
+  cy: number;
+  zoom: number;
+  rotX?: number; // deg, tilt about the horizontal axis (positive = top leans away, like looking at a table)
+  rotY?: number; // deg, tilt about the vertical axis (positive = right edge recedes, i.e. seen from the LEFT)
+  rotZ?: number; // deg, in-plane roll
+  persp?: number; // px, perspective strength (default 1400; smaller = stronger)
+};
+
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+
+/**
+ * 2.5D camera over a full-page screenshot. (cx, cy) is the page-space CSS
+ * point centered in the 1920x1080 viewport; zoom is scale (1 = 1 CSS px
+ * -> 1 output px). Page textures are 2x, rendered at CSS size via width.
+ *
+ * Optional 3D: keys may carry rotX/rotZ/persp to tilt the page like a plane
+ * seen from an oblique camera. When NO key declares any 3D field, the markup
+ * degrades to the original flat pan/zoom and renders pixel-identical.
+ *
+ * Optional DOF: a screen-space gradient-blur band approximating a focal plane
+ * near `focusY` (blurring the far/top part of a tilted page).
+ */
+export const PageCam: React.FC<{
+  src: string; // staticFile path under textures/live/
+  pageH: number; // CSS page height
+  keys: CamKey[];
+  children?: React.ReactNode; // page-space overlays (positioned in CSS px)
+  blur?: number;
+  saturate?: number;
+  ease?: (t: number) => number;
+  dof?: { focusY: number; strength: number };
+}> = ({ src, pageH, keys, children, blur = 0, saturate = 1, ease = Easing.bezier(0.33, 0, 0.15, 1), dof }) => {
+  const theme = useVisualTheme();
+  const paint = (css: string) => themePaint(theme, css);
+  const asset = (src: string) => themeAsset(theme, src);
+
+  const frame = useCurrentFrame();
+  // find segment
+  let a = keys[0], b = keys[keys.length - 1];
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (frame >= keys[i].frame && frame <= keys[i + 1].frame) { a = keys[i]; b = keys[i + 1]; break; }
+  }
+  const t = a.frame === b.frame ? 1 : interpolate(frame, [a.frame, b.frame], [0, 1], {
+    extrapolateLeft: 'clamp', extrapolateRight: 'clamp', easing: ease,
+  });
+  const cx = lerp(a.cx, b.cx, t);
+  const cy = lerp(a.cy, b.cy, t);
+  const zoom = lerp(a.zoom, b.zoom, t);
+
+  const filters: string[] = [];
+  if (blur > 0) filters.push(`blur(${blur}px)`);
+  if (saturate !== 1) filters.push(`saturate(${saturate})`);
+
+  // Does any key request 3D? If not, keep the original flat markup exactly.
+  const has3D = keys.some((k) => k.rotX !== undefined || k.rotY !== undefined || k.rotZ !== undefined || k.persp !== undefined);
+
+  if (!has3D) {
+    return (
+      <AbsoluteFill style={{ overflow: 'hidden', backgroundColor: paint('#faf7f2') }}>
+        <div
+          style={{
+            position: 'absolute', width: 1920, height: pageH,
+            transform: `translate(${960 - cx * zoom}px, ${540 - cy * zoom}px) scale(${zoom})`,
+            transformOrigin: '0 0',
+            filter: filters.length ? filters.join(' ') : undefined,
+          }}
+        >
+          <Img src={asset(src)} style={{ position: 'absolute', width: 1920, height: pageH }} />
+          {children}
+        </div>
+      </AbsoluteFill>
+    );
+  }
+
+  // 3D mode: pivot rotation/scale about the focal page-point (cx, cy) so it
+  // stays centered in the viewport. With rotX=rotZ=0 this reduces to the flat
+  // transform (proven identical: (960,540) + zoom*(p - (cx,cy))).
+  const rotX = lerp(a.rotX ?? 0, b.rotX ?? 0, t);
+  const rotY = lerp(a.rotY ?? 0, b.rotY ?? 0, t);
+  const rotZ = lerp(a.rotZ ?? 0, b.rotZ ?? 0, t);
+  const persp = lerp(a.persp ?? 1400, b.persp ?? 1400, t);
+
+  return (
+    <AbsoluteFill style={{ overflow: 'hidden', backgroundColor: paint('#faf7f2') }}>
+      <div
+        style={{
+          position: 'absolute', inset: 0,
+          perspective: `${persp * zoom}px`,
+          perspectiveOrigin: '960px 540px',
+        }}
+      >
+        {/* LAYOUT-SCALE zoom: instead of scale(zoom) in the transform chain (which
+            makes Chromium rasterize the 3D-composited layer at 1920-wide LAYOUT
+            size and then GPU-upscale by zoom — everything inside gets downsampled
+            before magnification, hence blurry text), we apply the magnification as
+            the CSS `zoom` property. `zoom` enlarges the layout box itself, so the
+            page + card textures rasterize at the ENLARGED device size and sample
+            down from their hi-res sources → sharp glyph edges under perspective.
+
+            Coordinate math: `zoom` scales this element's local coordinate space by
+            `zoom`, so a page point (cx,cy) renders at (cx*zoom, cy*zoom) device px
+            from the box origin, and a `translate(Tx px)` renders as Tx*zoom device
+            px. To land the focal point (cx,cy) at viewport centre (960,540):
+              cx*zoom + Tx*zoom = 960  ⟹  Tx = 960/zoom - cx  (likewise Ty).
+            Rotations pivot about transform-origin (cx,cy) = the focal point, so
+            they leave its screen position unchanged. With rot=0 this reduces to
+            translate(960/zoom - cx, 540/zoom - cy) under zoom — identical framing
+            to the old scale-based transform, just rasterized at layout scale. */}
+        <div
+          style={{
+            position: 'absolute', width: 1920, height: pageH,
+            zoom,
+            transform: `translate(${960 / zoom - cx}px, ${540 / zoom - cy}px) rotateY(${rotY}deg) rotateX(${rotX}deg) rotateZ(${rotZ}deg)`,
+            transformOrigin: `${cx}px ${cy}px`,
+            transformStyle: 'preserve-3d',
+            filter: filters.length ? filters.join(' ') : undefined,
+          }}
+        >
+          <Img src={asset(src)} style={{ position: 'absolute', width: 1920, height: pageH }} />
+          {children}
+        </div>
+      </div>
+
+      {/* Depth-of-field approximation: a top-band gradient blur (far part of a
+          tilted page reads soft). Screen-space, over the page. */}
+      {dof ? (
+        <div
+          style={{
+            position: 'absolute',
+            left: 0,
+            right: 0,
+            top: 0,
+            height: Math.max(0, dof.focusY),
+            backdropFilter: `blur(${dof.strength}px)`,
+            WebkitBackdropFilter: `blur(${dof.strength}px)`,
+            maskImage: paint('linear-gradient(to bottom, rgba(0,0,0,1) 0%, rgba(0,0,0,1) 45%, rgba(0,0,0,0) 100%)'),
+            WebkitMaskImage: paint('linear-gradient(to bottom, rgba(0,0,0,1) 0%, rgba(0,0,0,1) 45%, rgba(0,0,0,0) 100%)'),
+            pointerEvents: 'none',
+          }}
+        />
+      ) : null}
+    </AbsoluteFill>
+  );
+};