{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"text-build","type":"registry:component","title":"Text Build","description":"Word-by-word text build animation that keeps the line centred. Words enter one at a time while already-placed words physically reflow to stay centered — a growing line on the x axis or a growing stack on the y axis.","dependencies":["remotion"],"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/text-build.tsx","type":"registry:component","target":"components/kuchi/text-build.tsx","content":"/*! Portions Copyright (c) 2026 Sri Nath (snap-cn). MIT License. See THIRD_PARTY_LICENSES. */\n\"use client\";\r\n\r\nimport { useEffect, useMemo, useState } from \"react\";\r\nimport { Easing, interpolate, useCurrentFrame } from \"remotion\";\r\nimport {\r\n  resolveFont,\r\n  type KuchiTheme,\r\n  useKuchiTheme,\r\n} from \"@/lib/kuchi-ui\";\r\n\r\nexport type TextBuildAxis = \"x\" | \"y\";\r\n\r\nexport interface TextBuildProps {\r\n  text: string;\r\n  /** Build direction: \"x\" pushes the line sideways, \"y\" stacks rows. */\r\n  axis?: TextBuildAxis;\r\n  /** Distance a new word travels in from (px). Defaults: 88 on x, 28 on y. */\r\n  entryOffset?: number;\r\n  /** Space between words (px on x) or between rows (px on y, default 12). */\r\n  gap?: number;\r\n  /** Frames the first word takes to settle. */\r\n  firstDuration?: number;\r\n  /** Frames each subsequent enter/push/reflow step takes. */\r\n  pushDuration?: number;\r\n  /** Scale a word enters at before settling to 1. */\r\n  entryScale?: number;\r\n  /** Blur (px) a word enters with. Defaults: 3.5 on x, 2.4 on y. */\r\n  entryBlur?: number;\r\n  /** Peak blur (px) on already-placed words while they reflow. */\r\n  reflowBlur?: number;\r\n  /** Cubic-bezier easing for every move. */\r\n  easing?: [number, number, number, number];\r\n  fontSize?: number;\r\n  /** Overrides the design system's `foreground`. */\r\n  color?: string;\r\n  fontWeight?: number;\r\n  speed?: number;\r\n  className?: string;\r\n  /** Design-system token overrides. */\r\n  theme?: Partial<KuchiTheme>;\r\n  mode?: \"light\" | \"dark\";\r\n  /**\r\n   * The face this scene paints its words in — a label from `fonts.ts`\r\n   * (\"Inter\", \"Space Grotesk\", \"Instrument Serif\") or a CSS family you have\r\n   * loaded yourself. Unset, the scene keeps the face it was designed around.\r\n   *\r\n   * Overrides `theme.fontFamily`, which is how a brand kit re-skins a whole\r\n   * timeline from one value.\r\n   */\r\n  fontFamily?: string;\r\n}\r\n\r\nconst FONT_FAMILY = \"-apple-system, BlinkMacSystemFont, sans-serif\";\r\n\r\nconst MEASURE_FONT =\r\n  '-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif';\r\n\r\n/** Per-axis defaults harvested from the two legacy looks. */\r\nconst AXIS_DEFAULTS: Record<\r\n  TextBuildAxis,\r\n  {\r\n    entryOffset: number;\r\n    gap: number;\r\n    entryBlur: number;\r\n    /** Subtle drift the very first word settles from, on the cross axis (x)\r\n     * or the primary axis (y). */\r\n    firstDrift: number;\r\n  }\r\n> = {\r\n  x: { entryOffset: 88, gap: 10, entryBlur: 3.5, firstDrift: 6 },\r\n  y: { entryOffset: 28, gap: 12, entryBlur: 2.4, firstDrift: -14 },\r\n};\r\n\r\n/**\r\n * Size of each word along the build axis. On \"x\" this is the measured text\r\n * width (canvas measureText, with a `length * fontSize * 0.55` SSR fallback);\r\n * on \"y\" every row is one `fontSize` tall.\r\n */\r\nfunction fallbackWordSizes(\r\n  words: string[],\r\n  axis: TextBuildAxis,\r\n  fontSize: number,\r\n): number[] {\r\n  if (axis === \"y\") return words.map(() => fontSize);\r\n  return words.map((w) => w.length * fontSize * 0.55);\r\n}\r\n\r\nexport function measureWordSizes(\r\n  words: string[],\r\n  axis: TextBuildAxis,\r\n  fontSize: number,\r\n  fontWeight: number,\r\n): number[] {\r\n  if (axis === \"y\") return words.map(() => fontSize);\r\n  if (typeof document === \"undefined\")\r\n    return fallbackWordSizes(words, axis, fontSize);\r\n  const ctx = document.createElement(\"canvas\").getContext(\"2d\");\r\n  if (!ctx) return fallbackWordSizes(words, axis, fontSize);\r\n  ctx.font = `${fontWeight} ${fontSize}px ${MEASURE_FONT}`;\r\n  return words.map((w) => ctx.measureText(w).width);\r\n}\r\n\r\n/**\r\n * Center coordinates for every intermediate layout. `result[k - 1][j]` is the\r\n * centered position of word `j` while the first `k` words are on stage, so\r\n * placed words can be interpolated between consecutive layouts as new words\r\n * land.\r\n */\r\nexport function centeredPositions(sizes: number[], gap: number): number[][] {\r\n  const out: number[][] = [];\r\n  for (let k = 1; k <= sizes.length; k++) {\r\n    let total = gap * (k - 1);\r\n    for (let j = 0; j < k; j++) total += sizes[j];\r\n    let cursor = -total / 2;\r\n    const centers: number[] = [];\r\n    for (let j = 0; j < k; j++) {\r\n      centers.push(cursor + sizes[j] / 2);\r\n      cursor += sizes[j] + gap;\r\n    }\r\n    out.push(centers);\r\n  }\r\n  return out;\r\n}\r\n\r\nexport function TextBuild({\r\n  text,\r\n  axis = \"x\",\r\n  entryOffset,\r\n  gap,\r\n  firstDuration = 10,\r\n  pushDuration = 13,\r\n  entryScale = 0.992,\r\n  entryBlur,\r\n  reflowBlur = 0.8,\r\n  easing = [0.2, 0.8, 0.2, 1],\r\n  fontSize = 72,\r\n  color,\r\n  fontWeight = 600,\r\n  speed = 1,\r\n  className,\r\n  theme,\r\n  mode,\r\n  fontFamily,\r\n}: TextBuildProps) {\r\n  const frame = useCurrentFrame() * speed;\r\n  const t = useKuchiTheme(theme, mode);\r\n  const face = resolveFont(fontFamily ?? t.fontFamily) ?? FONT_FAMILY;\r\n  const fill = color ?? t.foreground;\r\n\r\n  const defaults = AXIS_DEFAULTS[axis];\r\n  const offset = entryOffset ?? defaults.entryOffset;\r\n  const spacing = gap ?? defaults.gap;\r\n  const inBlur = entryBlur ?? defaults.entryBlur;\r\n\r\n  const words = useMemo(() => text.split(\" \"), [text]);\r\n\r\n  // Canvas text measurement isn't available during SSR, so the first client\r\n  // render must also use the fallback estimate (matching the server-rendered\r\n  // markup) before upgrading to the precise canvas measurement post-mount —\r\n  // otherwise the two renders disagree and React logs a hydration mismatch.\r\n  const [measured, setMeasured] = useState(false);\r\n  useEffect(() => setMeasured(true), []);\r\n  const sizes = useMemo(\r\n    () =>\r\n      measured\r\n        ? measureWordSizes(words, axis, fontSize, fontWeight)\r\n        : fallbackWordSizes(words, axis, fontSize),\r\n    [measured, words, axis, fontSize, fontWeight],\r\n  );\r\n  const positionsAt = useMemo(\r\n    () => centeredPositions(sizes, spacing),\r\n    [sizes, spacing],\r\n  );\r\n\r\n  const n = words.length;\r\n  const ease = Easing.bezier(easing[0], easing[1], easing[2], easing[3]);\r\n\r\n  return (\r\n    <div\r\n      style={{\r\n        position: \"absolute\",\r\n        inset: 0,\r\n        display: \"flex\",\r\n        alignItems: \"center\",\r\n        justifyContent: \"center\",\r\n        background: \"transparent\",\r\n      }}\r\n    >\r\n      <div\r\n        className={className}\r\n        style={{\r\n          position: \"relative\",\r\n          fontSize,\r\n          fontWeight,\r\n          color: fill,\r\n          letterSpacing: \"-0.03em\",\r\n          fontFamily: face,\r\n          whiteSpace: \"nowrap\",\r\n        }}\r\n      >\r\n        {words.map((word, j) => {\r\n          const entryStart =\r\n            j === 0 ? 0 : firstDuration + (j - 1) * pushDuration;\r\n          const entryEnd =\r\n            entryStart + (j === 0 ? firstDuration : pushDuration);\r\n          const target = positionsAt[j][j];\r\n\r\n          // Where the word enters from. Later words travel `offset` along the\r\n          // build axis (from the right on x, from above on y). The first word\r\n          // only drifts subtly: cross-axis on x, a short drop on y.\r\n          const primaryFrom =\r\n            j === 0\r\n              ? axis === \"y\"\r\n                ? target + defaults.firstDrift\r\n                : target\r\n              : axis === \"y\"\r\n                ? target - offset\r\n                : target + offset;\r\n          const crossFrom = j === 0 && axis === \"x\" ? defaults.firstDrift : 0;\r\n\r\n          let primary = target;\r\n          let cross = 0;\r\n          let opacity = 1;\r\n          let scale = 1;\r\n          let blur = 0;\r\n\r\n          if (frame < entryStart) {\r\n            opacity = 0;\r\n            primary = primaryFrom;\r\n            cross = crossFrom;\r\n            scale = entryScale;\r\n            blur = inBlur;\r\n          } else if (frame <= entryEnd) {\r\n            const range: [number, number] = [entryStart, entryEnd];\r\n            const opts = {\r\n              extrapolateLeft: \"clamp\" as const,\r\n              extrapolateRight: \"clamp\" as const,\r\n              easing: ease,\r\n            };\r\n            primary = interpolate(frame, range, [primaryFrom, target], opts);\r\n            cross = interpolate(frame, range, [crossFrom, 0], opts);\r\n            opacity = interpolate(frame, range, [0, 1], opts);\r\n            scale = interpolate(frame, range, [entryScale, 1], opts);\r\n            blur = interpolate(frame, range, [inBlur, 0], opts);\r\n          } else {\r\n            // Placed word: reflow between consecutive layouts as each later\r\n            // word lands, with a soft blur pulse mid-move.\r\n            for (let w = j + 1; w < n; w++) {\r\n              const pushStart = firstDuration + (w - 1) * pushDuration;\r\n              const pushEnd = pushStart + pushDuration;\r\n              const from = positionsAt[w - 1][j];\r\n              const to = positionsAt[w][j];\r\n              if (frame >= pushEnd) {\r\n                primary = to;\r\n              } else if (frame >= pushStart) {\r\n                primary = interpolate(frame, [pushStart, pushEnd], [from, to], {\r\n                  extrapolateLeft: \"clamp\",\r\n                  extrapolateRight: \"clamp\",\r\n                  easing: ease,\r\n                });\r\n                blur = interpolate(\r\n                  frame,\r\n                  [pushStart, (pushStart + pushEnd) / 2, pushEnd],\r\n                  [0, reflowBlur, 0],\r\n                  { extrapolateLeft: \"clamp\", extrapolateRight: \"clamp\" },\r\n                );\r\n                break;\r\n              } else {\r\n                primary = from;\r\n                break;\r\n              }\r\n            }\r\n          }\r\n\r\n          const tx = axis === \"x\" ? primary : 0;\r\n          const ty = axis === \"x\" ? cross : primary;\r\n\r\n          return (\r\n            <span\r\n              key={`${j}-${word}`}\r\n              style={{\r\n                position: \"absolute\",\r\n                left: \"50%\",\r\n                top: \"50%\",\r\n                whiteSpace: \"nowrap\",\r\n                // Plain 2D transforms, deliberately. `translate3d(…, 0)` and\r\n                // `backfaceVisibility: hidden` are the same layer-promotion\r\n                // trick wearing two hats: they buy smoothness by handing the\r\n                // scale to the compositor, which resamples a bitmap instead of\r\n                // re-rasterising real type. On a word that is both scaling and\r\n                // blurring, that is the whole deliverable.\r\n                transform: `translate(-50%, -50%) translate(${tx}px, ${ty}px) scale(${scale})`,\r\n                filter: `blur(${blur}px)`,\r\n                opacity,\r\n              }}\r\n            >\r\n              {word}\r\n            </span>\r\n          );\r\n        })}\r\n      </div>\r\n    </div>\r\n  );\r\n}\r\n"}]}