{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"card-rail","type":"registry:component","title":"Card Rail","description":"Card carousel animation: cards flicked sideways on a tilted 3D plane. A rail of cards flicked sideways across a tilted plane.","dependencies":["remotion","@remotion/google-fonts"],"docs":"Needs a Remotion project. If a frame renders black, the component is drawing on a transparent layer: put a background behind it, e.g. <AbsoluteFill style={{ background: \"#faf9f6\" }}><Component /></AbsoluteFill>. Pass mode=\"dark\" for dark frames.","registryDependencies":["https://kuchi.kalarislabs.com/r/kuchi-ui.json"],"files":[{"path":"components/kuchi/card-rail.tsx","type":"registry:component","target":"components/kuchi/card-rail.tsx","content":"/*! Portions Copyright (c) 2026 Sri Nath (snap-cn). MIT License. See THIRD_PARTY_LICENSES. */\n\"use client\";\r\n\r\nimport { loadFont as loadSans } from \"@remotion/google-fonts/Figtree\";\r\nimport type { CSSProperties } from \"react\";\r\nimport { forwardRef, useCallback, useState } from \"react\";\r\nimport {\r\n  AbsoluteFill,\r\n  continueRender,\r\n  delayRender,\r\n  getRemotionEnvironment,\r\n  staticFile,\r\n  useCurrentFrame,\r\n  useVideoConfig,\r\n} from \"remotion\";\r\nimport {\r\n  Item,\r\n  mixOklch,\r\n  parseColor,\r\n  resolveFont,\r\n  type KuchiTheme,\r\n  useKuchiTheme,\r\n} from \"@/lib/kuchi-ui\";\r\n\r\n/**\r\n * A rail of cards flicked sideways across a tilted plane.\r\n *\r\n * The cards do not crawl past on a loop. They are *flicked* — the rail leaves at\r\n * speed, decelerates for well over a second, and comes to rest one card further\r\n * along, the way a carousel behaves under a thumb rather than under a timer. A\r\n * title holds the top of the frame and does not move with them.\r\n *\r\n * ## The plane is tilted, and that is the whole look\r\n *\r\n * The rail is not flat to the camera. Measured on the card edges of a recording,\r\n * the horizontal scale grows **0.000825 per pixel of height** about the frame's\r\n * own centre line — the bottom of a card is 22% wider than its top — while\r\n * horizontals stay horizontal and the type stays upright. That is a plane\r\n * rotated about a horizontal axis under perspective, and it is why a row of\r\n * plain rectangles reads as a surface receding into the frame.\r\n *\r\n * The three numbers that describe it are `DEPTH`, `TILT` and `HORIZON`, and they\r\n * are deliberately separate from the card metrics: change the card size and the\r\n * plane does not move.\r\n *\r\n * ## The flick is measured, not eased\r\n *\r\n * `FLICK` is the curve off the recording — it peaks at 29px a frame three frames\r\n * in and is still moving at 2px a frame a second later. No standard ease has that\r\n * tail; a cubic-out arrives four times too early and a spring overshoots\r\n * something that never overshoots.\r\n */\r\n\r\nconst { fontFamily: SANS } = loadSans(\"normal\", {\r\n  weights: [\"400\", \"500\", \"600\", \"700\"],\r\n  subsets: [\"latin\"],\r\n});\r\n\r\n/* ─────────────────────────────────────────────────────────────────────────\r\n   The stage, in the recording's own 714 × 396 pixels\r\n   ───────────────────────────────────────────────────────────────────────── */\r\n\r\nexport const REF_W = 714;\r\nexport const REF_H = 396;\r\n\r\n/** Title: cap height and baseline, measured on its own ink. */\r\nexport const HEAD_CAP = 20.81;\r\nexport const HEAD_BASE = 64.45;\r\n\r\n/** The card, in layout pixels — before the plane tilts it. */\r\nexport const CARD_W = 259.2;\r\nexport const CARD_TOP = 79.8;\r\nexport const GAP = 54.2;\r\nexport const RADIUS = 10;\r\n/**\r\n * The card runs to the foot of the frame — the rail is a surface passing\r\n * through the shot, not a row of objects sitting in it.\r\n *\r\n * Its own number rather than `REF_H - CARD_TOP`, because `CARD_TOP` is a\r\n * *layout* height on a tilted plane and the two are not the same measurement:\r\n * the plane pushes the card 54px down the frame on its way to the camera.\r\n */\r\nexport const CARD_H = 323.3;\r\n/** The picture's share of the card's width, as an aspect. */\r\nexport const SHOT_ASPECT = 16 / 9;\r\n\r\n/**\r\n * The plane.\r\n *\r\n * `HORIZON` is the height at which the plane is exactly life-size — above it the\r\n * rail is smaller and further away, below it nearer and larger. It is measured,\r\n * not chosen: solving the card's width at two heights puts it at 300.6, which is\r\n * most of the way down the visible card rather than at the frame's middle.\r\n */\r\nexport const DEPTH = 740;\r\nexport const TILT = 30;\r\nexport const HORIZON = 300;\r\n\r\n/**\r\n * The backdrop's axis, in degrees.\r\n *\r\n * Fitted, not guessed: a plane's corners have to satisfy TL + BR = TR + BL for a\r\n * linear gradient, and the recording's do to within five parts in 235 — so it is\r\n * linear, and the angle that puts its measured corners on one line is 138°.\r\n */\r\nexport const ANGLE = 138;\r\n\r\n/**\r\n * How far the rail travels, and the curve it travels on.\r\n *\r\n * One card pitch, so the rail comes to rest showing the next card where the last\r\n * one stood. The table is seconds → share of that distance, straight off the\r\n * recording: 29px on frame three, 2px a second later, and no analytic curve in\r\n * between that fits both ends.\r\n */\r\n/**\r\n * Not `CARD_W + GAP`, and the difference is the point.\r\n *\r\n * A rail that advanced by exactly one pitch would be an assumption; measured, the\r\n * recording's travels 333 where its pitch is 325. A flick is a flick — it ends\r\n * where the momentum ran out, not on a snap — and eight pixels of overshoot is\r\n * the whole difference between a carousel and a surface someone pushed.\r\n */\r\nexport const TRAVEL = 323;\r\nexport const FLICK: readonly (readonly [number, number])[] = [\r\n  [0, 0],\r\n  [0.0333, 0.009],\r\n  [0.0667, 0.0338],\r\n  [0.1, 0.07508],\r\n  [0.1333, 0.13213],\r\n  [0.1667, 0.21021],\r\n  [0.2, 0.2973],\r\n  [0.225, 0.38138],\r\n  [0.2583, 0.45345],\r\n  [0.2917, 0.51351],\r\n  [0.325, 0.56757],\r\n  [0.3583, 0.60961],\r\n  [0.3917, 0.65165],\r\n  [0.4333, 0.68468],\r\n  [0.4583, 0.71171],\r\n  [0.4917, 0.73874],\r\n  [0.525, 0.76276],\r\n  [0.5583, 0.78378],\r\n  [0.5917, 0.8018],\r\n  [0.625, 0.81982],\r\n  [0.6583, 0.83483],\r\n  [0.6917, 0.84985],\r\n  [0.73, 0.86186],\r\n  [0.7633, 0.87387],\r\n  [0.7967, 0.88288],\r\n  [0.8383, 0.89189],\r\n  [0.8717, 0.9009],\r\n  [0.905, 0.90991],\r\n  [0.9383, 0.91592],\r\n  [0.9717, 0.92492],\r\n  [0.9967, 0.93093],\r\n  [1.03, 0.93694],\r\n  [2.2, 1],\r\n];\r\n\r\n/** Linear read of a rising table, clamped at both ends. */\r\nexport function read(\r\n  table: readonly (readonly [number, number])[],\r\n  x: number,\r\n): number {\r\n  const first = table[0];\r\n  const last = table[table.length - 1];\r\n  if (!first || !last) return 0;\r\n  if (x <= first[0]) return first[1];\r\n  if (x >= last[0]) return last[1];\r\n  for (let i = 1; i < table.length; i++) {\r\n    const hi = table[i];\r\n    const lo = table[i - 1];\r\n    if (hi && lo && x <= hi[0]) {\r\n      return lo[1] + ((hi[1] - lo[1]) * (x - lo[0])) / (hi[0] - lo[0]);\r\n    }\r\n  }\r\n  return last[1];\r\n}\r\n\r\n/** One card. Leave the words out and the picture is the whole card. */\r\nexport interface RailCard {\r\n  image?: string;\r\n  title?: string;\r\n  /** A line of small print under the title. */\r\n  note?: string;\r\n  tag?: string;\r\n}\r\n\r\nconst POSTERS = \"https://kuchi-media.kalarislabs.com/components/art/\";\r\n\r\nexport const DEFAULT_CARDS: readonly RailCard[] = (\r\n  [\r\n    [\"orbit-gallery\", \"Orbit Gallery\", 300],\r\n    [\"moodboard-reveal\", \"Moodboard Reveal\", 150],\r\n    [\"hero-launch\", \"Hero Launch\", 170],\r\n    [\"phone-frame\", \"Phone Frame\", 240],\r\n    [\"count-grid\", \"Count Grid\", 47],\r\n    [\"terminal-simulator\", \"Terminal Simulator\", 200],\r\n    [\"logo-flicker\", \"Logo Flicker\", 100],\r\n    [\"laptop-frame\", \"Laptop Frame\", 240],\r\n    [\"announce-title\", \"Announce Title\", 170],\r\n  ] as const\r\n).map(([slug, title, frames]) => ({\r\n  image: `${POSTERS}art-${String((slug.length % 12) + 1).padStart(2, '0')}.svg`,\r\n  title,\r\n  note: `Scene · ${frames} frames`,\r\n  tag: `@kuchi/${slug}`,\r\n}));\r\n\r\nexport interface CardRailProps {\r\n  /**\r\n   * The cards, in order. The rail repeats them if it runs out.\r\n   *\r\n   * Also accepts one string, for the customizer and for quick edits: cards\r\n   * split by `|`, and each card's picture, title, small print and tag split by\r\n   * `>` — `\"https://… > Inbox > 4 screens > @acme/inbox | https://…\"`. A card\r\n   * that is only a URL is only a picture. Not commas or `;`: a data: URL has\r\n   * both.\r\n   */\r\n  cards?: readonly RailCard[] | string;\r\n  /** The line that holds the top of the frame. */\r\n  heading?: string;\r\n  /** Frame the first flick starts on. Negative starts the scene already moving. */\r\n  from?: number;\r\n  /** How many flicks. Each one carries the rail about another card along. */\r\n  flicks?: number;\r\n  /** Frames between one flick leaving and the next. */\r\n  every?: number;\r\n  /** Where the rail sits before it moves, in layout pixels. */\r\n  offset?: number;\r\n  /**\r\n   * The backdrop: two colour stops split by `|`, or one picture.\r\n   *\r\n   * A picture because a brand backdrop is often not a gradient at all — the\r\n   * recording this was measured from has corners that satisfy a linear fit and a\r\n   * middle that is 40 levels darker than one, which is a mesh or a painted plate\r\n   * and not something two stops can be talked into.\r\n   */\r\n  backdrop?: string;\r\n  theme?: Partial<KuchiTheme>;\r\n  mode?: \"light\" | \"dark\";\r\n  fontFamily?: string;\r\n}\r\n\r\nexport function CardRail({\r\n  cards = DEFAULT_CARDS,\r\n  heading = \"Browse scenes\",\r\n  from = 0,\r\n  flicks = 3,\r\n  every = 30,\r\n  offset = 0,\r\n  backdrop = \"\",\r\n  theme,\r\n  mode = \"light\",\r\n  fontFamily = \"Default\",\r\n}: CardRailProps) {\r\n  const frame = useCurrentFrame();\r\n  const { fps, width, height } = useVideoConfig();\r\n  const t = useKuchiTheme(theme, mode);\r\n  const face = resolveFont(fontFamily) ?? SANS;\r\n\r\n  const u = height / REF_H;\r\n  const ox = (width - REF_W * u) / 2;\r\n\r\n  const deck = toCards(cards);\r\n  // No cards is a rail of blank ones, not a modulo by zero.\r\n  const count = Math.max(1, deck.length);\r\n  const stops = split(backdrop);\r\n  const only = stops.length === 1 ? (stops[0] ?? \"\") : \"\";\r\n  const plate = only.startsWith(\"data:\") || only.startsWith(\"/\") ? only : \"\";\r\n\r\n  /**\r\n   * Flicks add up.\r\n   *\r\n   * Each one is the same measured curve started `every` frames after the last,\r\n   * and the rail's position is their sum — so a flick begun while the one before\r\n   * it is still creeping carries that creep with it, which is what repeated\r\n   * swipes actually do. `read` clamps at both ends, so a flick that has not\r\n   * started contributes nothing and one that has finished contributes all of it.\r\n   */\r\n  let travelled = 0;\r\n  for (let k = 0; k < Math.max(1, Math.round(flicks)); k++) {\r\n    travelled += TRAVEL * read(FLICK, (frame - from - k * every) / fps);\r\n  }\r\n  const pitch = CARD_W + GAP;\r\n\r\n  // Enough cards to cover the frame at its widest, plus one leaving and one\r\n  // arriving. The rail repeats the list rather than running out.\r\n  const span = Math.ceil(REF_W / pitch) + 3;\r\n  // The rail has a beginning. Cards repeat to the right for as long as the flick\r\n  // needs them, but nothing is drawn before the first one — a loop that wraps\r\n  // round puts a card in the empty half of the frame the scene opens on.\r\n  const first = Math.max(0, Math.floor((travelled - offset) / pitch));\r\n  // The rail can show one card twice. Studio outlines the copy nearest the\r\n  // middle of the frame; the other is only a picture of it.\r\n  const nearest = new Map<number, number>();\r\n  for (let n = 0; n < span; n++) {\r\n    const i = first + n;\r\n    const k = ((i % count) + count) % count;\r\n    const d = Math.abs(i * pitch - travelled + offset - (REF_W - CARD_W) / 2);\r\n    const held = nearest.get(k);\r\n    const dHeld =\r\n      held === undefined\r\n        ? Number.POSITIVE_INFINITY\r\n        : Math.abs(held * pitch - travelled + offset - (REF_W - CARD_W) / 2);\r\n    if (d < dHeld) nearest.set(k, i);\r\n  }\r\n\r\n  // Both stops are mixed toward *blues*, never toward the page. The page is a\r\n  // near-neutral, its hue in oklch is undefined, and interpolating the accent\r\n  // through it comes out somewhere else entirely — measured once already, a blue\r\n  // accent over a warm off-white mixed to a pale green.\r\n  const from0 = stops[0] ?? mixOklch(t.primary, \"#0b1f3d\", 0.55);\r\n  const to0 = stops[1] ?? mixOklch(t.primary, \"#dceaff\", 0.78);\r\n  // A theme with a transparent page asks for no page: no backdrop, so the rail\r\n  // sits on whatever is under it, and a heading in ink rather than mixed off it.\r\n  const bare = parseColor(t.background).alpha === 0;\r\n\r\n  return (\r\n    <AbsoluteFill\r\n      style={\r\n        bare\r\n          ? undefined\r\n          : plate\r\n            ? { backgroundColor: t.background }\r\n            : { background: `linear-gradient(${ANGLE}deg, ${from0}, ${to0})` }\r\n      }\r\n    >\r\n      {plate && !bare && (\r\n        <Plate\r\n          src={plate}\r\n          style={{ position: \"absolute\", inset: 0, objectFit: \"cover\" }}\r\n        />\r\n      )}\r\n      <div\r\n        style={{\r\n          position: \"absolute\",\r\n          left: ox,\r\n          top: 0,\r\n          width: REF_W * u,\r\n          height: REF_H * u,\r\n          fontFamily: face,\r\n          textRendering: \"geometricPrecision\",\r\n          overflow: \"hidden\",\r\n        }}\r\n      >\r\n        {heading && (\r\n          <div\r\n            style={{\r\n              position: \"absolute\",\r\n              left: 0,\r\n              right: 0,\r\n              top: (HEAD_BASE - HEAD_CAP * 1.32) * u,\r\n              textAlign: \"center\",\r\n              fontSize: HEAD_CAP * 1.38 * u,\r\n              lineHeight: 1,\r\n              fontWeight: 500,\r\n              color: bare ? t.foreground : mixOklch(to0, t.background, 0.62),\r\n            }}\r\n          >\r\n            {heading}\r\n          </div>\r\n        )}\r\n        <div\r\n          style={{\r\n            position: \"absolute\",\r\n            inset: 0,\r\n            // The plane. `HORIZON` is where it is life-size, so the tilt pivots\r\n            // about a line inside the visible band rather than about the top of\r\n            // a box nobody can see.\r\n            perspective: DEPTH * u,\r\n            perspectiveOrigin: `50% ${HORIZON * u}px`,\r\n          }}\r\n        >\r\n          <div\r\n            style={{\r\n              position: \"absolute\",\r\n              inset: 0,\r\n              transform: `rotateX(${TILT}deg)`,\r\n              transformOrigin: `50% ${HORIZON * u}px`,\r\n              transformStyle: \"preserve-3d\",\r\n            }}\r\n          >\r\n            {Array.from({ length: span }, (_, n) => {\r\n              const i = first + n;\r\n              const x = i * pitch - travelled + offset;\r\n              const k = ((i % count) + count) % count;\r\n              const card = deck[k] ?? {};\r\n              return (\r\n                <Item key={i} index={k} primary={nearest.get(k) === i}>\r\n                  <Card\r\n                    x={x * u}\r\n                    src={card.image ?? \"\"}\r\n                    title={card.title ?? \"\"}\r\n                    note={card.note ?? \"\"}\r\n                    tag={card.tag ?? \"\"}\r\n                    t={t}\r\n                    u={u}\r\n                  />\r\n                </Item>\r\n              );\r\n            })}\r\n          </div>\r\n        </div>\r\n      </div>\r\n    </AbsoluteFill>\r\n  );\r\n}\r\n\r\nconst split = (s: string) =>\r\n  s\r\n    .split(\"|\")\r\n    .map((v) => v.trim())\r\n    .filter(Boolean);\r\n\r\n/** The string form of `cards`: see `CardRailProps.cards`. */\r\nexport function toCards(\r\n  input: readonly RailCard[] | string,\r\n): readonly RailCard[] {\r\n  if (typeof input !== \"string\") return input;\r\n  return input\r\n    .split(\"|\")\r\n    .filter((c) => c.trim())\r\n    .map((c) => {\r\n      const [image = \"\", title = \"\", note = \"\", tag = \"\"] = c\r\n        .split(\">\")\r\n        .map((v) => v.trim());\r\n      return { image, title, note, tag };\r\n    });\r\n}\r\n\r\n/**\r\n * One card: a picture, and under it a title and a line of small print. Forwards\r\n * its `ref` and takes a `style` on top of its own so Remotion Studio can\r\n * outline it and nudge it (see `Item`) — forwardRef, not a `ref` prop, which\r\n * React 18 would drop.\r\n */\r\nconst Card = forwardRef<\r\n  HTMLDivElement,\r\n  {\r\n    x: number;\r\n    src: string;\r\n    title: string;\r\n    note: string;\r\n    tag: string;\r\n    t: KuchiTheme;\r\n    u: number;\r\n    style?: CSSProperties;\r\n  }\r\n>(function Card({ x, src, title, note, tag, t, u, style }, ref) {\r\n  const bodied = Boolean(title || note || tag);\r\n  const shot = CARD_W / SHOT_ASPECT;\r\n  return (\r\n    <div\r\n      ref={ref}\r\n      style={{\r\n        ...style,\r\n        position: \"absolute\",\r\n        left: x,\r\n        top: CARD_TOP * u,\r\n        width: CARD_W * u,\r\n        height: CARD_H * u,\r\n        borderRadius: RADIUS * u,\r\n        overflow: \"hidden\",\r\n        background: t.card,\r\n      }}\r\n    >\r\n      <Plate\r\n        src={src}\r\n        style={{\r\n          display: \"block\",\r\n          width: CARD_W * u,\r\n          // With no body the picture *is* the card. That is not a special case\r\n          // for its own sake — it is what lets a whole card be handed in as one\r\n          // image when the layout below is somebody else's.\r\n          height: (bodied ? shot : CARD_H) * u,\r\n          objectFit: \"cover\",\r\n        }}\r\n      />\r\n      {bodied && (\r\n        <div style={{ padding: `${13 * u}px ${15 * u}px` }}>\r\n          <div\r\n            style={{\r\n              fontSize: 15 * u,\r\n              lineHeight: 1.25,\r\n              fontWeight: 700,\r\n              color: t.foreground,\r\n            }}\r\n          >\r\n            {title}\r\n          </div>\r\n          <div\r\n            style={{\r\n              marginTop: 5 * u,\r\n              fontSize: 12.5 * u,\r\n              lineHeight: 1.3,\r\n              color: t.mutedForeground,\r\n            }}\r\n          >\r\n            {note}\r\n          </div>\r\n          {tag && (\r\n            <div\r\n              style={{\r\n                marginTop: 14 * u,\r\n                display: \"inline-block\",\r\n                padding: `${5 * u}px ${10 * u}px`,\r\n                borderRadius: 999,\r\n                fontSize: 11.5 * u,\r\n                lineHeight: 1.2,\r\n                fontWeight: 500,\r\n                color: t.mutedForeground,\r\n                border: `1px solid ${t.border}`,\r\n              }}\r\n            >\r\n              {tag}\r\n            </div>\r\n          )}\r\n        </div>\r\n      )}\r\n    </div>\r\n  );\r\n});\r\n\r\n/**\r\n * A root-relative asset is a `public/` file. Only the site's own Player serves\r\n * it at that path; Remotion Studio and a render know its URL through\r\n * `staticFile()` alone — so every environment but the Player rewrites it.\r\n */\r\nfunction resolveSrc(src: string): string {\r\n  const isLocal = src.startsWith(\"/\") && !src.startsWith(\"//\");\r\n  if (!isLocal || getRemotionEnvironment().isPlayer) return src;\r\n  // A value that already came out of staticFile() carries the static base\r\n  // (`/static-<hash>/…`); running it through again would prefix it twice.\r\n  const base = staticFile(\"_\").slice(0, -2);\r\n  if (base && src.startsWith(`${base}/`)) return src;\r\n  try {\r\n    return staticFile(src.replace(/^\\/+/, \"\"));\r\n  } catch {\r\n    return src;\r\n  }\r\n}\r\n\r\n/**\r\n * A picture that holds the render until it has actually loaded.\r\n *\r\n * Without it a frame can be captured before the image arrives and the card comes\r\n * out empty — invisible in the Player, where an image simply appears, and silent\r\n * in an mp4 until somebody watches it. Remotion's own `Img` is avoided for the\r\n * reason `hero-launch` documents: it awaits `decode()`, which the headless\r\n * compositor rejects for some progressive JPEGs and hangs the export.\r\n */\r\nfunction Plate({ src, style }: { src: string; style: CSSProperties }) {\r\n  // No picture is an empty surface, not an <img> that never loads and holds\r\n  // the render open.\r\n  return src ? <Picture src={src} style={style} /> : <div style={style} />;\r\n}\r\n\r\nfunction Picture({ src, style }: { src: string; style: CSSProperties }) {\r\n  const [handle] = useState(() => delayRender(`card-rail: ${src}`));\r\n  const release = useCallback(() => continueRender(handle), [handle]);\r\n  return (\r\n    // biome-ignore lint/performance/noImgElement: Remotion frame, not a Next route.\r\n    <img // eslint-disable-line @remotion/warn-native-media-tag -- onLoad releases the frame; <Img> hangs on some JPEGs\r\n      src={resolveSrc(src)}\r\n      alt=\"\"\r\n      // Tailwind's preflight sets `img { max-width: 100% }`, which collapses an\r\n      // image inside a shrink-to-fit box to zero pixels wide on the site while\r\n      // rendering perfectly in an mp4. Size it here and say so.\r\n      style={{ ...style, maxWidth: \"none\" }}\r\n      onLoad={release}\r\n      onError={release}\r\n    />\r\n  );\r\n}\r\n"}]}