@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/paperfold/PaperFoldFrame.tsx

@@ -0,0 +1,576 @@
+/* eslint-disable comppack/no-raw-colour -- a video frame, not site UI: every colour is config content; the few literals are fixed tints (white light, black shade) of the lighting model and the debug overlay's own colours (DECISIONS §27). */
+import type { ComponentType, CSSProperties, ReactNode } from 'react';
+import { getPath, type PaperFoldConfig } from './config';
+import { PANELS, type PanelId } from './controls';
+import { frameState, mixHex, rgba, type EdgeFx, type FrameState, type HandState, type StripState, type TextFit } from './engine';
+import { bottomHand, sleevePath, topHand, type HandArt, type HandFill, type HandPart, type HandShape } from './art';
+
+/**
+ * **The procedural renderer.** Draws one frame of paper-fold-promo from the engine's state with plain
+ * DOM and inline SVG. Each panel is its own box placed by the engine's `matrix3d` (true perspective
+ * about its crease), painted in the engine's explicit depth order; its copy is live text inside it.
+ * Hands are inline vector paths in two pieces (body behind the paper, gripping finger in front).
+ * No Remotion, no clock: the Remotion composition passes `useCurrentFrame()`, the web player a rAF
+ * clock, and both get the same pixels. Everything is laid out at the render size, so 4K is vector.
+ *
+ * `debug` (development only — never part of the config) overlays the creases, panel outlines and ids,
+ * fold pivots and angles, the hands' grip anchors, a normalized grid and the scene/frame.
+ */
+export type ImageProps = { src: string; style?: CSSProperties; alt: string };
+export type PaperFoldFrameProps = {
+  /** A validated, complete config (resolveConfig). */
+  config: PaperFoldConfig;
+  /** Authored motion frame (60 fps). */
+  frame: number;
+  width: number;
+  height: number;
+  /** Development overlay. Not part of the config, so it can never reach a production render through it. */
+  debug?: boolean;
+  resolveAsset?: (ref: string) => string;
+  ImageComponent?: ComponentType<ImageProps>;
+};
+
+const DefaultImage = ({ src, style, alt }: ImageProps) => <img src={src} style={style} alt={alt} />;
+const defaultResolve = (ref: string) => (ref.startsWith('static:') ? `/${ref.slice(7)}` : ref);
+export const FONT_STACK = (family: string) => `'${family}', 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif`;
+
+type Ctx = { st: FrameState; n: (p: string) => number; s: (p: string) => string; b: (p: string) => boolean };
+const full: CSSProperties = { position: 'absolute', inset: 0 };
+
+export function PaperFoldFrame({ config, frame, width, height, debug = false, resolveAsset = defaultResolve, ImageComponent = DefaultImage }: PaperFoldFrameProps) {
+  const st = frameState(config, frame, width, height);
+  const n = (p: string) => getPath(config, p) as number;
+  const s = (p: string) => getPath(config, p) as string;
+  const b = (p: string) => getPath(config, p) as boolean;
+  const ctx: Ctx = { st, n, s, b };
+  return (
+    <div
+      data-paper-fold-frame={Math.round(st.frame * 100) / 100}
+      data-phase={st.phase.label}
+      style={{ position: 'relative', width, height, overflow: 'hidden', background: s('background.baseColor'), fontFamily: FONT_STACK('Inter') }}
+    >
+      <div style={{ ...full, transformOrigin: '0 0', transform: st.camera.backgroundTransform }}>
+        <Background ctx={ctx} />
+      </div>
+      {b('background.noise.enabled') && <Noise ctx={ctx} />}
+      <div data-layer="scene" style={{ ...full, transformOrigin: '0 0', transform: st.camera.transform }}>
+        {b('paper.shadow.enabled') && <SheetShadow ctx={ctx} />}
+        {st.strips.map((p) => <StripView key={p.index} ctx={ctx} strip={p} last={st.strips.length - 1} />)}
+        {st.hands.filter((h) => h.enabled).map((h) => <Hand key={h.id} ctx={ctx} h={h} />)}
+      </div>
+      {b('logo.enabled') && <Logo ctx={ctx} img={(src, style, alt) => <ImageComponent src={resolveAsset(src)} style={style} alt={alt} />} />}
+      {b('cta.enabled') && s('content.cta.text') !== '' && <Cta ctx={ctx} />}
+      {debug && <Debug ctx={ctx} />}
+    </div>
+  );
+}
+
+/* ─── background ──────────────────────────────────────────────────────────────────────────────── */
+function Background({ ctx }: { ctx: Ctx }) {
+  const { st, n, s, b } = ctx;
+  const { width: W, height: H, unit: u } = st.size;
+  const stops = getPath(st.cfg, 'background.gradient.stops') as { offset: number; color: string }[];
+  const list = stops.map((x) => `${x.color} ${Math.round(x.offset * 1000) / 10}%`).join(', ');
+  const gradient = s('background.gradient.type') === 'radial' ? `radial-gradient(circle at 50% 45%, ${list})` : `linear-gradient(${n('background.gradient.angle')}deg, ${list})`;
+  const bt = 'background.backgroundTypography';
+  const size = n(`${bt}.fontSize`) * u * st.size.backgroundType.scale;
+  const word = Array.from({ length: st.background.typeRepeat }, () => s(`${bt}.text`)).join(' ');
+  const glowR = n('background.glow.radius') * Math.min(W, H);
+  return (
+    <>
+      {b('background.gradient.enabled') && <div style={{ ...full, background: gradient }} />}
+      {b(`${bt}.enabled`) && s(`${bt}.text`) !== '' && (
+        <div data-layer="background-type" style={{ ...full, transformOrigin: '50% 50%', transform: `rotate(${n(`${bt}.rotation`)}deg)`, opacity: n(`${bt}.opacity`) }}>
+          {st.background.typeRows.map((r, i) => (
+            <div
+              key={i}
+              style={{
+                position: 'absolute', left: r.x, top: r.y, whiteSpace: 'pre', lineHeight: 1, fontSize: size,
+                fontFamily: FONT_STACK(s(`${bt}.fontFamily`)), fontWeight: n(`${bt}.weight`), letterSpacing: `${n(`${bt}.tracking`)}em`, color: s(`${bt}.color`),
+              }}
+            >
+              {word}
+            </div>
+          ))}
+        </div>
+      )}
+      {b('background.glow.enabled') && (
+        <div
+          style={{
+            position: 'absolute', left: n('background.glow.x') * W - glowR, top: n('background.glow.y') * H - glowR, width: glowR * 2, height: glowR * 2, borderRadius: '50%',
+            background: `radial-gradient(circle, ${rgba(s('background.glow.color'), n('background.glow.opacity'))} 0%, ${rgba(s('background.glow.color'), 0)} 70%)`,
+            filter: n('background.glow.blur') > 0 ? `blur(${n('background.glow.blur') * u}px)` : undefined,
+          }}
+        />
+      )}
+    </>
+  );
+}
+
+function Noise({ ctx }: { ctx: Ctx }) {
+  const { st, n } = ctx;
+  const { width: W, height: H, unit: u } = st.size;
+  const id = `pf-noise-${n('background.noise.seed')}`;
+  return (
+    <svg width={W} height={H} style={{ ...full, opacity: n('background.noise.opacity'), mixBlendMode: 'overlay' }} aria-hidden="true">
+      <filter id={id} x="0" y="0" width="100%" height="100%">
+        <feTurbulence type="fractalNoise" baseFrequency={0.75 / (u * n('background.noise.scale'))} numOctaves={2} seed={n('background.noise.seed')} stitchTiles="stitch" />
+        <feColorMatrix type="saturate" values="0" />
+      </filter>
+      <rect width={W} height={H} filter={`url(#${id})`} />
+    </svg>
+  );
+}
+
+/* ─── the sheet ───────────────────────────────────────────────────────────────────────────────── */
+function SheetShadow({ ctx }: { ctx: Ctx }) {
+  const { st, n, s } = ctx;
+  const u = st.size.unit;
+  const pts = (q: [number, number][]) => q.map(([x, y]) => `${Math.round(x * 10) / 10},${Math.round(y * 10) / 10}`).join(' ');
+  return (
+    <div data-layer="sheet-shadow" style={{ ...full, zIndex: 10, opacity: n('paper.shadow.opacity'), filter: `blur(${n('paper.shadow.blur') * u}px)`, transform: `translate(${n('paper.shadow.offsetX') * u}px, ${n('paper.shadow.offsetY') * u}px)` }}>
+      <svg width={st.size.width} height={st.size.height} style={{ position: 'absolute', left: 0, top: 0, overflow: 'visible' }} aria-hidden="true">
+        {st.shadowQuads.map((q, i) => <polygon key={i} points={pts(q)} fill={s('paper.shadow.color')} stroke={s('paper.shadow.color')} strokeWidth={2} />)}
+      </svg>
+    </div>
+  );
+}
+
+function PrintedText({ ctx, fit, text }: { ctx: Ctx; fit: TextFit; text: string }) {
+  const { st, n, s } = ctx;
+  const T = `typography.${fit.slot}`;
+  const pu = st.size.pu;
+  const align = s(`${T}.alignment`) as 'left' | 'center' | 'right';
+  const shadow = n(`${T}.shadowOpacity`) > 0 ? `0 ${Math.max(1, n(`${T}.shadowBlur`) * pu * 0.3)}px ${n(`${T}.shadowBlur`) * pu}px ${rgba(s(`${T}.shadow`), n(`${T}.shadowOpacity`))}` : undefined;
+  const pill = fit.slot === 'bottomCta';
+  const box: CSSProperties = {
+    fontFamily: FONT_STACK(s(`${T}.fontFamily`)), fontWeight: n(`${T}.fontWeight`), fontStyle: s(`${T}.fontStyle`) as 'normal' | 'italic',
+    fontSize: fit.fontSize, lineHeight: n(`${T}.lineHeight`), letterSpacing: `${n(`${T}.letterSpacing`)}em`,
+    color: s(`${T}.color`), opacity: n(`${T}.opacity`), textAlign: align, whiteSpace: 'pre-line', overflowWrap: 'break-word', textShadow: shadow,
+  };
+  return (
+    <div
+      data-slot={fit.slot}
+      data-fit={fit.scale}
+      style={{
+        position: 'absolute', left: fit.x - fit.area.x, top: fit.y - fit.area.y, width: fit.width,
+        transformOrigin: `${align === 'left' ? 0 : align === 'center' ? 50 : 100}% 0%`,
+        transform: `rotate(${n(`${T}.rotation`)}deg) skewX(${n(`${T}.skew`)}deg) scale(${n(`${T}.scale`)})`,
+        ...(pill ? {} : box),
+      }}
+    >
+      {pill
+        ? <span style={{ ...box, display: 'inline-block', padding: '0.42em 0.95em', borderRadius: 999, background: s('cta.backgroundColor'), boxShadow: `0 ${0.12 * fit.fontSize}px ${0.4 * fit.fontSize}px ${rgba('#000000', 0.18)}` }}>{text}</span>
+        : text}
+    </div>
+  );
+}
+
+const PANEL_TEXT: Record<PanelId, string[]> = {
+  top: ['topLogo', 'topHeadline', 'topSubtitle'], middle: ['middleHeadline', 'middleBody'], bottom: ['bottomHeadline', 'bottomBody', 'bottomCta'],
+};
+const SLOT_PATH: Record<string, string> = {
+  topLogo: 'content.top.logo', topHeadline: 'content.top.headline', topSubtitle: 'content.top.subtitle', middleHeadline: 'content.middle.headline',
+  middleBody: 'content.middle.body', bottomHeadline: 'content.bottom.headline', bottomBody: 'content.bottom.body', bottomCta: 'content.bottom.cta',
+};
+
+/**
+ * The print of the whole sheet, in sheet coordinates (0‥width × 0‥height): the paper of each region,
+ * its grain, the crease effects and every word. Every strip draws this same print, offset to its own
+ * height and clipped to itself, so the sheet stays ONE surface — gradient, grain, creases and text run
+ * on across the strips, and each word turns with exactly the part of the sheet it is printed on.
+ * Only the regions that reach the strip are drawn. `face` picks the front or the back of the paper.
+ */
+function SheetPrint({ ctx, face, y0, y1, brightness }: { ctx: Ctx; face: 'front' | 'back'; y0: number; y1: number; brightness: number }) {
+  const { st, n, s, b } = ctx;
+  const { width: PW, height: PH } = st.size.paper;
+  const pu = st.size.pu;
+  const reach = (a: number, c: number) => c >= y0 - 2 && a <= y1 + 2;
+  const mat = 'paperMaterial';
+  // Light: the paper takes the full shade, the print on it part of it (so white type stays crisp).
+  const textShade = brightness < 1 ? (1 - brightness) * 0.3 : 0;
+  const paperShade = brightness < 1 ? Math.min(0.92, 1 - brightness / (1 - textShade)) : 0;
+  const light = brightness > 1 ? Math.min(0.6, (brightness - 1) * 0.9) : 0;
+  const regions = PANELS.map((id) => ({ id, ...st.size.panels[id] })).filter((r) => reach(r.y0, r.y1));
+  const fill = (id: PanelId): CSSProperties => {
+    const P = `panels.${id}`;
+    if (face === 'back') return { backgroundColor: s(`${mat}.backColor`) };
+    const colour = s(`${P}.colorMode`) === 'own' ? s(`${P}.backgroundColor`) : s(`${mat}.baseColor`);
+    return b(`${mat}.gradientEnabled`) && b(`${P}.gradient`) && s(`${P}.colorMode`) !== 'own'
+      ? { backgroundColor: colour, backgroundImage: `linear-gradient(${n(`${mat}.gradientAngle`)}deg, ${colour}, ${s(`${mat}.secondaryColor`)})`, backgroundSize: `${PW}px ${PH}px`, backgroundPosition: `0px ${-st.size.panels[id].y0}px` }
+      : { backgroundColor: colour };
+  };
+  return (
+    <div data-print={face} style={{ position: 'absolute', left: 0, top: 0, width: PW, height: PH }}>
+      {regions.map((r) => (
+        <div key={r.id} data-region={r.id} style={{ position: 'absolute', left: 0, top: r.y0, width: PW, height: r.height, ...fill(r.id) }}>
+          <PaperGrain ctx={ctx} w={PW} h={r.height} y0={r.y0} k={n(`panels.${r.id}.textureOpacity`)} />
+        </div>
+      ))}
+      {paperShade > 0 && <div style={{ ...full, background: '#000000', opacity: paperShade }} />}
+      {light > 0 && <div style={{ ...full, background: '#ffffff', opacity: light }} />}
+      {st.panels.map((p) => p.edges.map((e) => {
+        const yc = st.size.creases[e.crease];
+        const span = Math.max(e.shadow.length + e.shadow.blur, e.valley.length, e.line.width) + 2;
+        return (face === 'front' || e.edge === 'bottom') && reach(yc - span, yc + span)
+          ? <CreaseEffects key={`${p.id}${e.edge}`} e={face === 'front' ? e : { ...e, valley: { ...e.valley, opacity: 0 }, shadow: { ...e.shadow, opacity: 0 } }} yc={yc} w={PW} pu={pu} tint={mixHex(e.line.color, '#000000', 0.55)} />
+          : null;
+      }))}
+      <OuterEdges ctx={ctx} w={PW} h={PH} />
+      {face === 'front' && regions.map((r) => <PanelContent key={r.id} ctx={ctx} id={r.id} />)}
+      {face === 'back' && s('content.back.text') !== '' && regions.some((r) => r.id === s('content.back.panel')) && <BackContent ctx={ctx} id={s('content.back.panel') as PanelId} />}
+      {textShade > 0 && <div style={{ ...full, background: '#000000', opacity: textShade }} />}
+    </div>
+  );
+}
+
+function PanelContent({ ctx, id }: { ctx: Ctx; id: PanelId }) {
+  const { st, n, s, b } = ctx;
+  const { y0, height: h } = st.size.panels[id];
+  const PW = st.size.paper.width, pu = st.size.pu;
+  const P = `panels.${id}`;
+  const fits = st.text.filter((t) => t.panel === id && PANEL_TEXT[id].includes(t.slot));
+  if (!fits.length) return null;
+  const area = fits[0]!.area;
+  const overflow = b(`${P}.overflow`);
+  return (
+    <div data-content={id} style={{ position: 'absolute', left: 0, top: y0, width: PW, height: h, overflow: overflow ? 'visible' : 'hidden' }}>
+      <div style={{ ...full, transformOrigin: '50% 50%', transform: `translate(${n(`${P}.contentOffsetX`) * pu}px, ${n(`${P}.contentOffsetY`) * pu}px) rotate(${n(`${P}.contentRotation`)}deg) scale(${n(`${P}.contentScale`)})` }}>
+        <div data-content-area={id} style={{ position: 'absolute', left: area.x, top: area.y, width: area.width, height: area.height, overflow: overflow ? 'visible' : 'hidden' }}>
+          {fits.map((f) => <PrintedText key={f.slot} ctx={ctx} fit={f} text={s(SLOT_PATH[f.slot]!)} />)}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** Print on the back of a panel: laid out upside down, so it reads upright once the panel turns over. */
+function BackContent({ ctx, id }: { ctx: Ctx; id: PanelId }) {
+  const { st, n, s } = ctx;
+  const { y0, height: h } = st.size.panels[id];
+  const PW = st.size.paper.width, pu = st.size.pu;
+  const T = 'typography.back';
+  const fit: TextFit = { slot: 'back', panel: id, x: n(`${T}.x`) * PW, y: n(`${T}.y`) * h, width: n(`${T}.maxWidth`) * PW, fontSize: n(`${T}.fontSize`) * pu, scale: 1, lines: 1, area: { x: 0, y: 0, width: PW, height: h } };
+  return (
+    <div data-content="back" style={{ position: 'absolute', left: 0, top: y0, width: PW, height: h, overflow: 'hidden', transform: 'scaleY(-1)' }}>
+      <PrintedText ctx={ctx} fit={fit} text={s('content.back.text')} />
+    </div>
+  );
+}
+
+/**
+ * One strip of the sheet — a panel's flat part or one step of a crease's bend — placed by its own
+ * matrix3d and painted at its explicit depth. It shows the front or the back of the one sheet print.
+ * Each strip reaches a hair under the next (at most 1.5 px) so no seam opens between them.
+ */
+function StripView({ ctx, strip, last }: { ctx: Ctx; strip: StripState; last: number }) {
+  const { st, n, s } = ctx;
+  const PW = st.size.paper.width, pu = st.size.pu;
+  const h = strip.y1 - strip.y0;
+  const ov = strip.index < last ? Math.min(1.5, h * 0.5) : 0;
+  const radius = n('paper.cornerRadius') * pu;
+  const corners = strip.index === 0 ? `${radius}px ${radius}px 0 0` : strip.index === last ? `0 0 ${radius}px ${radius}px` : '0';
+  const edge = n('paper.thickness') * pu * strip.edgeOn;
+  return (
+    <div
+      data-strip={strip.index}
+      data-region={strip.region}
+      data-facing={strip.facing}
+      data-rank={strip.rank}
+      style={{ position: 'absolute', left: 0, top: 0, width: PW, height: h + ov, transformOrigin: '0 0', transform: strip.matrix, zIndex: strip.z, overflow: 'hidden', borderRadius: corners }}
+    >
+      <div style={{ position: 'absolute', left: 0, top: -strip.y0, width: PW, height: st.size.paper.height }}>
+        <SheetPrint ctx={ctx} face={strip.facing} y0={strip.y0} y1={strip.y1} brightness={strip.brightness} />
+      </div>
+      {strip.sheen > 0.002 && <div style={{ ...full, background: 'linear-gradient(160deg, rgba(255,255,255,0.9), rgba(255,255,255,0) 70%)', opacity: strip.sheen }} />}
+      {edge > 0.4 && (
+        // The paper's cut edge (its thickness) shows as the strip turns edge-on.
+        <>
+          <div style={{ position: 'absolute', left: 0, top: 0, width: edge, height: h + ov, background: s('paper.edgeColor') }} />
+          <div style={{ position: 'absolute', right: 0, top: 0, width: edge, height: h + ov, background: s('paper.edgeColor') }} />
+        </>
+      )}
+    </div>
+  );
+}
+
+function PaperGrain({ ctx, w, h, y0, k }: { ctx: Ctx; w: number; h: number; y0: number; k: number }) {
+  const { st, n, b } = ctx;
+  const tex = n('paperMaterial.textureOpacity') * k, grain = b('paperMaterial.grainEnabled') ? n('paperMaterial.grainOpacity') * k : 0;
+  if (tex <= 0 && grain <= 0) return null;
+  const seed = n('paperMaterial.grainSeed');
+  const pu = st.size.pu, gs = n('paperMaterial.grainScale');
+  // Sampled in sheet coordinates (the viewBox starts at the region's y), so fibres run on across the creases.
+  return (
+    <svg width={w} height={h} viewBox={`0 ${y0} ${w} ${h}`} style={{ ...full, mixBlendMode: 'soft-light' }} aria-hidden="true">
+      <filter id={`pf-fibre-${seed}`} x="0" y="0" width="100%" height="100%" filterUnits="userSpaceOnUse">
+        <feTurbulence type="fractalNoise" baseFrequency={`${0.9 / (pu * 60)} ${0.9 / (pu * 3)}`} numOctaves={3} seed={seed} />
+        <feColorMatrix type="saturate" values="0" />
+      </filter>
+      <filter id={`pf-grain-${seed}`} x="0" y="0" width="100%" height="100%" filterUnits="userSpaceOnUse">
+        <feTurbulence type="fractalNoise" baseFrequency={0.8 / Math.max(0.6, pu * gs)} numOctaves={1} seed={seed + 1} />
+        <feColorMatrix type="saturate" values="0" />
+      </filter>
+      {tex > 0 && <rect x={0} y={y0} width={w} height={h} filter={`url(#pf-fibre-${seed})`} opacity={Math.min(1, tex * 3)} />}
+      {grain > 0 && <rect x={0} y={y0} width={w} height={h} filter={`url(#pf-grain-${seed})`} opacity={Math.min(1, grain * 3)} />}
+    </svg>
+  );
+}
+
+/** A crease's line, ridge highlight, valley shading and the shadow of the panel closing over — at sheet height `yc`. */
+function CreaseEffects({ e, yc, w, pu, tint }: { e: EdgeFx; yc: number; w: number; pu: number; tint: string }) {
+  // `edge` is the panel's side of the crease: 'bottom' = the panel above it (effects run upward), 'top' = below (downward).
+  const down = e.edge === 'top';
+  const band = (length: number): CSSProperties => ({ position: 'absolute', left: 0, width: w, height: length, top: down ? yc : yc - length });
+  const dir = down ? 'to bottom' : 'to top';
+  const half = e.line.width / 2;
+  return (
+    <div data-crease={e.crease} data-edge={e.edge}>
+      {e.shadow.opacity > 0.002 && e.shadow.length > 0 && (
+        <div style={{ ...band(e.shadow.length + e.shadow.blur), background: `linear-gradient(${dir}, ${rgba(tint, e.shadow.opacity)} 0px, ${rgba(tint, e.shadow.opacity * 0.85)} ${e.shadow.length * 0.8}px, ${rgba(tint, 0)} ${e.shadow.length + e.shadow.blur}px)` }} />
+      )}
+      {e.valley.opacity > 0.002 && <div style={{ ...band(e.valley.length), background: `linear-gradient(${dir}, ${rgba(tint, e.valley.opacity)}, ${rgba(tint, 0)})` }} />}
+      {e.highlight.opacity > 0.002 && (
+        <div style={{ position: 'absolute', left: 0, width: w, height: e.highlight.width, top: down ? yc + half : yc - half - e.highlight.width, background: rgba(e.highlight.color, e.highlight.opacity), filter: `blur(${Math.max(0.3, pu * 0.8)}px)` }} />
+      )}
+      {e.line.opacity > 0.002 && (
+        <div style={{ position: 'absolute', left: 0, width: w, height: Math.max(0.5, half), top: down ? yc : yc - half, background: rgba(e.line.color, e.line.opacity), filter: e.line.blur > 0.2 ? `blur(${e.line.blur}px)` : undefined }} />
+      )}
+    </div>
+  );
+}
+
+function OuterEdges({ ctx, w, h }: { ctx: Ctx; w: number; h: number }) {
+  const { st, n } = ctx;
+  const hi = n('paperMaterial.edgeHighlight'), sh = n('paperMaterial.edgeShadow');
+  if (hi <= 0 && sh <= 0) return null;
+  const t = Math.max(1, 2.2 * st.size.pu);
+  const light = rgba('#ffffff', hi), dark = rgba('#000000', sh);
+  return (
+    <>
+      <div style={{ position: 'absolute', left: 0, top: 0, width: t, height: h, background: light }} />
+      <div style={{ position: 'absolute', right: 0, top: 0, width: t, height: h, background: dark }} />
+      <div style={{ position: 'absolute', left: 0, top: 0, width: w, height: t, background: light }} />
+      <div style={{ position: 'absolute', left: 0, bottom: 0, width: w, height: t, background: dark }} />
+    </>
+  );
+}
+
+/* ─── hands ───────────────────────────────────────────────────────────────────────────────────── */
+/** The hand's drawing, built from its skeleton with the current pose (the grip opening is animated). */
+export function handArt(cfg: PaperFoldConfig, h: HandState): HandArt {
+  const n = (p: string) => getPath(cfg, p) as number;
+  const pose = { ...h.pose, armLength: n(`hands.${h.id}.armLength`) * 0.6, open: h.fingerAngle, nails: getPath(cfg, 'hands.nails.enabled') as boolean, nailScale: n('hands.nails.scale') };
+  return h.id === 'top' ? topHand(pose) : bottomHand(pose);
+}
+/** The SVG transform that places hand units on the canvas at the hand's grip anchor. */
+export const handTransform = (h: HandState) =>
+  `translate(${h.x} ${h.y}) rotate(${h.rotation}) skewX(${h.skewX}) skewY(${h.skewY}) scale(${h.unitScale * h.scale}) translate(${h.offsetX} ${h.offsetY})`;
+
+function Hand({ ctx, h }: { ctx: Ctx; h: HandState }) {
+  const { st, n, s, b } = ctx;
+  const art = handArt(st.cfg, h);
+  const S = 'hands.style';
+  const colours: Record<HandFill, string> = {
+    base: s(`${S}.baseColor`), midtone: s(`${S}.midtoneColor`), shadow: s(`${S}.shadowColor`),
+    highlight: s(`${S}.highlightColor`), nail: s(`${S}.nailColor`), sleeve: s(`${S}.sleeve.color`),
+  };
+  const ow = n(`${S}.outlineWidth`);
+  const shape = (part: HandPart, sh: HandShape, i: number) => {
+    const o = part.name === 'highlights' ? n(`${S}.highlightOpacity`) : part.name === 'fingerShadows' || part.name === 'palmShadow' ? n(`${S}.shadowOpacity`) : part.name === 'nails' ? n('hands.nails.opacity') : 1;
+    return <path key={i} d={sh.d} fill={colours[sh.fill]} fillOpacity={(sh.opacity ?? 1) * o} {...(sh.outline && ow > 0 ? { stroke: s(`${S}.outlineColor`), strokeWidth: ow * 0.6, strokeLinejoin: 'round' as const } : {})} />;
+  };
+  // Once the held panel has turned over, the digits holding it from behind are on its visible side:
+  // they show only where they lie on that panel (clipped to its outline), never past its edge.
+  const held = st.panels.find((p) => p.id === h.panel)!;
+  const clipId = `pf-held-${h.id}`;
+  const clipped = held.facing === 'back';
+  const group = (layer: 'behind' | 'front') => art.parts.filter((p) => p.layer === layer).map((p, i) => {
+    const g = (
+      <g key={`${p.name}${i}`} data-part={p.name} {...(p.grips ? { 'data-grips': 'true' } : {})}>
+        {p.shapes.map((sh, j) => shape(p, sh, j))}
+        {p.name === 'forearm' && b(`${S}.sleeve.enabled`) && <path data-part="sleeve" d={sleevePath(art, n(`${S}.sleeve.position`), n(`hands.${h.id}.armLength`) * 0.6)} fill={colours.sleeve} />}
+      </g>
+    );
+    return p.grips && clipped ? <g key={`c${p.name}${i}`} clipPath={`url(#${clipId})`}><g transform={handTransform(h)}>{g}</g></g> : <g key={`t${p.name}${i}`} transform={handTransform(h)}>{g}</g>;
+  });
+  const svg: CSSProperties = { position: 'absolute', left: 0, top: 0, overflow: 'visible', opacity: h.opacity, pointerEvents: 'none' };
+  const { width: W, height: H } = st.size;
+  const pu = st.size.pu;
+  // The gripping digits cast a small contact shadow on the paper.
+  const drop = n(`${S}.dropShadowOpacity`) > 0 ? `drop-shadow(${n(`${S}.dropShadowOffset`) * pu * 0.5}px ${n(`${S}.dropShadowOffset`) * pu}px ${n(`${S}.dropShadowBlur`) * pu}px ${rgba('#1a0526', n(`${S}.dropShadowOpacity`))})` : undefined;
+  return (
+    <>
+      <svg data-hand={h.id} data-piece="body" width={W} height={H} style={{ ...svg, zIndex: h.bodyZ }} aria-hidden="true">
+        {clipped && <defs><clipPath id={clipId} clipPathUnits="userSpaceOnUse"><polygon points={held.corners.map(([x, y]) => `${x},${y}`).join(' ')} /></clipPath></defs>}
+        {group('behind')}
+      </svg>
+      <svg data-hand={h.id} data-piece="finger" width={W} height={H} style={{ ...svg, zIndex: h.fingerZ, filter: drop }} aria-hidden="true">
+        {group('front')}
+      </svg>
+    </>
+  );
+}
+
+/* ─── logo and CTA ────────────────────────────────────────────────────────────────────────────── */
+function Logo({ ctx, img }: { ctx: Ctx; img: (src: string, style: CSSProperties, alt: string) => ReactNode }) {
+  const { st, n, s, b } = ctx;
+  const u = st.size.unit;
+  const T = 'typography.logo';
+  const size = n(`${T}.fontSize`) * u;
+  const mark = n('logo.markSize') * size;
+  const shadow = n(`${T}.shadowOpacity`) > 0 ? `0 ${n(`${T}.shadowBlur`) * u * 0.3}px ${n(`${T}.shadowBlur`) * u}px ${rgba(s(`${T}.shadow`), n(`${T}.shadowOpacity`))}` : undefined;
+  const image = s('logo.image');
+  return (
+    <div
+      data-layer="logo"
+      style={{
+        position: 'absolute', left: st.logo.x, top: st.logo.y, zIndex: 900, opacity: st.logo.opacity, display: 'flex', alignItems: 'center', gap: n('logo.gap') * size, whiteSpace: 'nowrap',
+        transform: `translate(-50%, -50%) rotate(${n('logo.rotation')}deg) scale(${st.logo.scale})`,
+      }}
+    >
+      {image !== '' ? img(image, { height: n('logo.imageHeight') * u, width: 'auto', display: 'block' }, s('content.logo') || 'logo') : (
+        <>
+          {b('logo.showMark') && (
+            <div
+              data-part="logo-mark"
+              style={{
+                width: mark, height: mark, borderRadius: n('logo.markRadius') * mark, display: 'flex', alignItems: 'center', justifyContent: 'center',
+                background: `linear-gradient(135deg, ${s('logo.markColor')}, ${s('logo.markColorEnd')})`, color: s('logo.markTextColor'),
+                fontFamily: FONT_STACK(s(`${T}.fontFamily`)), fontWeight: 800, fontSize: mark * 0.72, lineHeight: 1,
+              }}
+            >
+              {s('logo.markText')}
+            </div>
+          )}
+          {s('content.logo') !== '' && (
+            <span
+              data-part="logo-word"
+              style={{
+                fontFamily: FONT_STACK(s(`${T}.fontFamily`)), fontWeight: n(`${T}.fontWeight`), fontStyle: s(`${T}.fontStyle`) as 'normal' | 'italic', fontSize: size, lineHeight: 1,
+                letterSpacing: `${n(`${T}.letterSpacing`)}em`, color: s(`${T}.color`), opacity: n(`${T}.opacity`), textShadow: shadow,
+              }}
+            >
+              {s('content.logo')}
+            </span>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function Cta({ ctx }: { ctx: Ctx }) {
+  const { st, n, s } = ctx;
+  const u = st.size.unit;
+  const T = 'typography.cta';
+  const shadow = n('cta.shadowOpacity') > 0 ? `0 ${n('cta.shadowBlur') * u * 0.35}px ${n('cta.shadowBlur') * u}px ${rgba(s('cta.shadowColor'), n('cta.shadowOpacity'))}` : undefined;
+  return (
+    <div
+      data-layer="cta"
+      style={{
+        position: 'absolute', left: st.cta.x, top: st.cta.y, zIndex: 900, opacity: st.cta.opacity, whiteSpace: 'nowrap',
+        transform: `translate(-50%, -50%) rotate(${n('cta.rotation')}deg) scale(${st.cta.scale})`,
+        background: s('cta.backgroundColor'), border: n('cta.borderWidth') > 0 ? `${n('cta.borderWidth') * u}px solid ${s('cta.borderColor')}` : undefined,
+        borderRadius: n('cta.radius') * u, padding: `${n('cta.paddingY') * u}px ${n('cta.paddingX') * u}px`, boxShadow: shadow,
+        fontFamily: FONT_STACK(s(`${T}.fontFamily`)), fontWeight: n(`${T}.fontWeight`), fontStyle: s(`${T}.fontStyle`) as 'normal' | 'italic', fontSize: n(`${T}.fontSize`) * u, lineHeight: 1.2,
+        letterSpacing: `${n(`${T}.letterSpacing`)}em`, color: s(`${T}.color`),
+        textShadow: n(`${T}.shadowOpacity`) > 0 ? `0 0 ${n(`${T}.shadowBlur`) * u}px ${rgba(s(`${T}.shadow`), n(`${T}.shadowOpacity`))}` : undefined,
+      }}
+    >
+      <span style={{ opacity: n(`${T}.opacity`) }}>{s('content.cta.text')}</span>
+    </div>
+  );
+}
+
+/* ─── debug overlay (development only) ────────────────────────────────────────────────────────── */
+function Debug({ ctx }: { ctx: Ctx }) {
+  const { st } = ctx;
+  const { width: W, height: H, unit: u } = st.size;
+  const fs = 14 * u;
+  const label = (x: number, y: number, lines: string[], colour = '#00ffd0') => (
+    <text x={x} y={y} fill={colour} fontSize={fs} fontFamily="ui-monospace, Menlo, monospace" stroke="#000000" strokeWidth={fs * 0.18} paintOrder="stroke">
+      {lines.map((l, i) => <tspan key={i} x={x} dy={i === 0 ? 0 : fs * 1.2}>{l}</tspan>)}
+    </text>
+  );
+  const pts = (q: [number, number][]) => q.map(([x, y]) => `${x},${y}`).join(' ');
+  const centre = (q: [number, number][]) => [q.reduce((a, p) => a + p[0], 0) / 4, q.reduce((a, p) => a + p[1], 0) / 4] as const;
+  // The grid and the read-out are fixed to the canvas; the geometry follows the camera so it sits on the drawing.
+  return (
+    <div data-layer="debug" style={{ ...full, zIndex: 2000, pointerEvents: 'none' }}>
+      <svg width={W} height={H} style={{ position: 'absolute', left: 0, top: 0 }} aria-hidden="true">
+        {Array.from({ length: 9 }, (_, i) => (i + 1) / 10).map((v) => (
+          <g key={v} opacity={0.35}>
+            <line x1={v * W} y1={0} x2={v * W} y2={H} stroke="#ffffff" strokeWidth={u} strokeDasharray={`${4 * u} ${6 * u}`} />
+            <line x1={0} y1={v * H} x2={W} y2={v * H} stroke="#ffffff" strokeWidth={u} strokeDasharray={`${4 * u} ${6 * u}`} />
+            {label(v * W + 3 * u, 16 * u, [v.toFixed(1)], '#ffffff')}
+            {label(3 * u, v * H - 4 * u, [v.toFixed(1)], '#ffffff')}
+          </g>
+        ))}
+      </svg>
+      <svg width={W} height={H} style={{ position: 'absolute', left: 0, top: 0, overflow: 'visible', transformOrigin: '0 0', transform: st.camera.transform }} aria-hidden="true">
+        <g>
+          {st.panels.map((p) => {
+            const [cx, cy] = centre(p.corners);
+            return (
+              <g key={p.id}>
+                <polygon points={pts(p.corners)} fill="none" stroke={p.facing === 'front' ? '#00ffd0' : '#ff9d00'} strokeWidth={2 * u} strokeDasharray={p.facing === 'front' ? undefined : `${8 * u} ${5 * u}`} />
+                {label(cx - 60 * u, cy, [`${p.id.toUpperCase()} PANEL`, `${p.facing} · rank ${p.rank} · z ${p.z}`, `light ${p.brightness.toFixed(2)}`])}
+              </g>
+            );
+          })}
+          {st.debug.creases.map((c, i) => {
+            const mx = (c.from[0] + c.to[0]) / 2, my = (c.from[1] + c.to[1]) / 2;
+            return (
+              <g key={c.id}>
+                <line x1={c.from[0]} y1={c.from[1]} x2={c.to[0]} y2={c.to[1]} stroke="#ff2d78" strokeWidth={3 * u} />
+                <circle cx={mx} cy={my} r={7 * u} fill="#ff2d78" stroke="#ffffff" strokeWidth={1.5 * u} />
+                {label(c.to[0] + 10 * u, c.to[1] + (i ? 18 : -8) * u, [`CREASE ${c.id.toUpperCase()} ${c.position.toFixed(3)}`, `ANGLE: ${c.angle.toFixed(1)}°`, `pivot (${(mx / W).toFixed(3)}, ${(my / H).toFixed(3)})`], '#ff2d78')}
+              </g>
+            );
+          })}
+          {/* Paper bounds: the outline of the one sheet, down its left edge and back up its right. */}
+          <polygon
+            points={[...st.strips.flatMap((p) => [p.corners[0]!, p.corners[3]!]), ...[...st.strips].reverse().flatMap((p) => [p.corners[2]!, p.corners[1]!])].map(([x, y]) => `${x},${y}`).join(' ')}
+            fill="none" stroke="#ffffff" strokeWidth={3 * u} strokeDasharray={`${2 * u} ${4 * u}`}
+          />
+          {st.strips.filter((p) => p.region.startsWith('crease')).map((p) => <polygon key={p.index} points={pts(p.corners)} fill="none" stroke="#ff2d78" strokeWidth={0.8 * u} opacity={0.6} />)}
+          {st.hands.map((h) => {
+            const art = handArt(st.cfg, h);
+            const k = h.unitScale * h.scale;
+            return (
+              <g key={`joints-${h.id}`} transform={handTransform(h)}>
+                {Object.entries(art.joints).map(([name, js]) => (
+                  <g key={name}>
+                    <polyline points={js.map(([x, y]) => `${x},${y}`).join(' ')} fill="none" stroke="#7df9ff" strokeWidth={1.5 * u / k} />
+                    {js.map(([x, y], i) => <circle key={i} cx={x} cy={y} r={3.2 * u / k} fill={i === 0 ? '#ffffff' : '#7df9ff'} />)}
+                  </g>
+                ))}
+              </g>
+            );
+          })}
+          {st.hands.map((h) => (
+            <g key={h.id}>
+              <circle cx={st.anchors[h.id].hand[0]} cy={st.anchors[h.id].hand[1]} r={10 * u} fill="none" stroke="#7df9ff" strokeWidth={2 * u} />
+              <line x1={h.gripX - 14 * u} y1={h.gripY} x2={h.gripX + 14 * u} y2={h.gripY} stroke="#ffe600" strokeWidth={2.5 * u} />
+              <line x1={h.gripX} y1={h.gripY - 14 * u} x2={h.gripX} y2={h.gripY + 14 * u} stroke="#ffe600" strokeWidth={2.5 * u} />
+              <circle cx={h.x} cy={h.y} r={6 * u} fill="none" stroke="#ffe600" strokeWidth={2 * u} />
+              {label(h.gripX + 16 * u, h.gripY - 10 * u, [`HAND ${h.id.toUpperCase()} → ${h.panel}`, `paper.${h.id}GripAnchor (${(h.gripX / W).toFixed(3)}, ${(h.gripY / H).toFixed(3)})`, `${h.id}Hand.gripAnchor Δ ${Math.hypot(st.anchors[h.id].hand[0] - h.gripX, st.anchors[h.id].hand[1] - h.gripY).toFixed(1)} px`, `z body ${h.bodyZ} · finger ${h.fingerZ}`], '#ffe600')}
+            </g>
+          ))}
+        </g>
+      </svg>
+      <svg width={W} height={H} style={{ position: 'absolute', left: 0, top: 0 }} aria-hidden="true">
+        <rect x={10 * u} y={24 * u} width={330 * u} height={7 * fs * 1.2 + 16 * u} fill="#000000" opacity={0.6} rx={6 * u} />
+        {label(20 * u, 24 * u + fs * 1.3, [
+          'DEBUG',
+          `FRAME: ${st.frame.toFixed(1)} / ${st.timeline.end}`,
+          `SCENE: ${st.phase.label} ${(st.phase.progress * 100).toFixed(0)}%`,
+          ...st.folds.map((f) => `${f.id.toUpperCase()} FOLD ANGLE: ${f.angle.toFixed(1)}° (${f.phase})`),
+          `ANCHOR: ${st.anchor.toUpperCase()} PANEL · ZOOM ${st.camera.zoom.toFixed(3)}`,
+          `ORDER: ${[...st.panels].sort((a, c) => a.rank - c.rank).map((p) => p.id).join(' < ')} · ${st.strips.length} strips`,
+        ])}
+      </svg>
+    </div>
+  );
+}