kasaframe 0.0.0-stage → 0.1.3

package/packages/motion/src/react/parts.tsx

@@ -0,0 +1,431 @@
+import type { CSSProperties, ReactNode } from "react";
+import { combine, toCss, type Style } from "@kasaframe/core";
+import { enter, inOut, type MoveName, type MoveOpts } from "../enter.ts";
+import { typeText, type TypeOpts } from "../type.ts";
+import { counter, letters, sweep, words, type CounterOpts, type SweepOpts } from "../text.ts";
+import { transition, type TransitionName, type TransitionOpts } from "../transition.ts";
+import { beatPulse, dropBurst } from "../impact.ts";
+import { breathe, camera, type BreatheOpts, type CameraOpts } from "../camera.ts";
+import { burst, sparkles, type BurstOpts, type SparkleOpts } from "../particles.ts";
+import { codeReveal, cursor, grow, safeText, terminal, type CursorKey, type TermStep } from "../ui.ts";
+import { useBeats, useCtx, useSceneId, useT } from "./time.tsx";
+
+const v = (name: string, fallback: string) => `var(--kf-${name}, ${fallback})`;
+const C = {
+  ink: v("ink", "#111"),
+  dim: v("dim", "#666"),
+  accent: v("accent", "#4A90E2"),
+  accentText: v("accent-text", "#2F6FC0"),
+  accentSoft: v("accent-soft", "rgba(74,144,226,0.35)"),
+  surface: v("surface", "#fff"),
+  raised: v("raised", "#f3f5f8"),
+  line: v("line", "#dde3ea"),
+  bg: v("bg", "#fff"),
+  sans: v("font-sans", "sans-serif"),
+  mono: v("font-mono", "monospace"),
+  display: v("font-display", "sans-serif"),
+};
+
+interface Timed {
+  /** 장면 안 시각. 안 주면 감싼 KfScene·Sequence 의 시각 */
+  t?: number;
+}
+
+interface Boxed {
+  style?: CSSProperties;
+  className?: string;
+  children?: ReactNode;
+}
+
+function Moved(props: Boxed & { s: Style; as?: "div" | "span" }) {
+  const Tag = props.as ?? "div";
+  const display = props.as === "span" ? "inline-block" : undefined;
+  return (
+    <Tag className={props.className} style={{ display, ...props.style, ...toCss(props.s) }}>
+      {props.children}
+    </Tag>
+  );
+}
+
+/** 들어온다. out 을 주면 그때 나간다 */
+export function Enter(props: Timed & Boxed & MoveOpts & { move?: MoveName; out?: number; as?: "div" | "span" }) {
+  const t = useT(props.t);
+  const scene = useSceneId();
+  const ctx = useCtx();
+  const { move = (ctx?.style.motion.enter as MoveName | undefined) ?? "rise", style, className, children, as, ...o } = props;
+  const s = o.out === undefined ? enter(move, t, { scene, ...o }) : inOut(move, t, { scene, ...o });
+  return (
+    <Moved s={s} style={style} className={className} as={as}>
+      {children}
+    </Moved>
+  );
+}
+
+/** 한글 자모 단위 타자 */
+export function Typewriter(props: Timed & TypeOpts & { text: string; caret?: boolean; caretColor?: string; style?: CSSProperties; className?: string }) {
+  const t = useT(props.t);
+  const st = typeText(safeText(props.text), t, props);
+  return (
+    <span className={props.className} style={{ whiteSpace: "pre-wrap", ...props.style }}>
+      {st.text}
+      {props.caret !== false && <Caret on={st.caret} color={props.caretColor} />}
+    </span>
+  );
+}
+
+export function Caret(props: { on: boolean; color?: string; mono?: boolean }) {
+  return (
+    <span
+      aria-hidden
+      style={{
+        display: "inline-block",
+        width: props.mono ? "0.6em" : "0.08em",
+        minWidth: 2,
+        height: "1.05em",
+        marginLeft: "0.06em",
+        verticalAlign: "-0.15em",
+        background: props.color ?? C.accent,
+        opacity: props.on ? 1 : 0,
+      }}
+    />
+  );
+}
+
+export function Counter(props: Timed & CounterOpts & { style?: CSSProperties; className?: string }) {
+  const t = useT(props.t);
+  return (
+    <span className={props.className} style={{ fontVariantNumeric: "tabular-nums", ...props.style }}>
+      {counter(t, props)}
+    </span>
+  );
+}
+
+/** 낱말이 차례로 들어온다 */
+export function Words(props: Timed & MoveOpts & { text: string; move?: MoveName; each?: number; gap?: string; style?: CSSProperties; className?: string; by?: "word" | "letter" }) {
+  const t = useT(props.t);
+  const scene = useSceneId();
+  const list = (props.by === "letter" ? letters : words)(safeText(props.text), t, { scene, ...props });
+  return (
+    <span className={props.className} style={{ display: "inline-flex", flexWrap: "wrap", columnGap: props.by === "letter" ? 0 : (props.gap ?? "0.28em"), ...props.style }}>
+      {list.map((w) => (
+        <span key={w.index} style={{ display: "inline-block", whiteSpace: "pre", ...toCss(w.style) }}>
+          {w.text}
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/** 형광펜 쓸기 — 글 뒤에 강조 띠가 지나간다 */
+export function Highlight(props: Timed & SweepOpts & { color?: string; children?: ReactNode; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const s = sweep(t, props);
+  return (
+    <span style={{ position: "relative", display: "inline-block", ...props.style }}>
+      <span aria-hidden style={{ position: "absolute", left: "-0.12em", right: "-0.12em", top: "52%", bottom: "4%", background: props.color ?? C.accentSoft, borderRadius: "0.12em", ...toCss(s) }} />
+      <span style={{ position: "relative" }}>{props.children}</span>
+    </span>
+  );
+}
+
+/** 두 장면 사이 전환. from·to 를 겹쳐 그리고 전환 밖에서는 한쪽만 */
+export function Transition(props: Timed & Omit<TransitionOpts, "scene"> & { name: TransitionName; from: ReactNode; to: ReactNode; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const scene = useSceneId();
+  const s = transition(props.name, t, { scene, ...props });
+  const showOut = t < props.at || s.both;
+  const showIn = t >= props.at;
+  const layer: CSSProperties = { position: "absolute", inset: 0 };
+  return (
+    <div style={{ position: "relative", width: "100%", height: "100%", overflow: "hidden", ...props.style }}>
+      {showOut && <div style={{ ...layer, ...toCss(s.out) }}>{props.from}</div>}
+      {showIn && <div style={{ ...layer, ...toCss(s.in) }}>{props.to}</div>}
+    </div>
+  );
+}
+
+/** 카메라 틀 — 안의 내용을 밀거나 민다 */
+export function Camera(props: Timed & Boxed & Omit<CameraOpts, "scene">) {
+  const t = useT(props.t);
+  const scene = useSceneId();
+  const s = camera(t, { scene, ...props });
+  return (
+    <Moved s={s} style={{ position: "absolute", inset: 0, transformOrigin: "50% 50%", ...props.style }} className={props.className}>
+      {props.children}
+    </Moved>
+  );
+}
+
+/** 숨 쉬는 틀 — 가만히 있는 화면이 멈춤으로 찍히지 않게. 장면 내용 전체를 감싼다 */
+export function Breathe(props: Timed & Boxed & BreatheOpts) {
+  const t = useT(props.t);
+  const scene = useSceneId();
+  const s = breathe(t, { seed: scene, ...props });
+  return (
+    <Moved s={s} style={{ position: "absolute", inset: 0, transformOrigin: "50% 50%", ...props.style }} className={props.className}>
+      {props.children}
+    </Moved>
+  );
+}
+
+/** 박 펄스 — style.json 규칙을 따른다(기본은 드롭 구간만) */
+export function BeatPulse(props: Timed & Boxed & { amount?: number; every?: "beat" | "downbeat" | "bar" | number; source?: string; as?: "div" | "span" }) {
+  const t = useT(props.t);
+  const beats = useBeats();
+  const ctx = useCtx();
+  const scene = useSceneId();
+  const s = beats ? beatPulse(t, { beats, amount: props.amount, every: props.every, rules: ctx?.style.motion, scene, source: props.source }) : {};
+  return (
+    <Moved s={s} style={props.style} className={props.className} as={props.as}>
+      {props.children}
+    </Moved>
+  );
+}
+
+/**
+ * 드롭 터짐 — 섬광·충격파·흔들림. 드롭 번호로만 건다(드롭이 아닌 곳에서 터지지 않게).
+ * children 은 흔들리고, 섬광·고리는 위에 덮인다.
+ */
+export function DropBurst(props: Timed & Boxed & { drop: number; color?: string; ring?: boolean; px?: number; source?: string }) {
+  const t = useT(props.t);
+  const beats = useBeats();
+  const ctx = useCtx();
+  const scene = useSceneId();
+  if (!beats) return <>{props.children}</>;
+  const b = dropBurst(t, { beats, drop: props.drop, rules: ctx?.style.motion, px: props.px, scene, source: props.source });
+  const color = props.color ?? "#fff";
+  return (
+    <div className={props.className} style={{ position: "absolute", inset: 0, overflow: "hidden", ...props.style }}>
+      <Moved s={combine(b.shake, b.punch)} style={{ position: "absolute", inset: 0 }}>
+        {props.children}
+      </Moved>
+      {props.ring !== false && b.ring.opacity > 0.01 && (
+        <div
+          aria-hidden
+          style={{
+            position: "absolute",
+            left: "50%",
+            top: "50%",
+            width: "60vmin",
+            height: "60vmin",
+            marginLeft: "-30vmin",
+            marginTop: "-30vmin",
+            borderRadius: "50%",
+            border: `0.9vmin solid ${C.accent}`,
+            ...toCss({ scale: b.ring.scale, opacity: b.ring.opacity }),
+          }}
+        />
+      )}
+      {b.flash > 0.01 && <div aria-hidden style={{ position: "absolute", inset: 0, background: color, opacity: b.flash * 0.85 }} />}
+    </div>
+  );
+}
+
+const STAR = "M12 0 L14.2 9.8 L24 12 L14.2 14.2 L12 24 L9.8 14.2 L0 12 L9.8 9.8 Z";
+
+/** 반짝이 — 시드 고정 자리에서 깜빡인다 */
+export function Sparkles(props: Timed & Partial<SparkleOpts> & { colors?: string[]; size?: number; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const ctx = useCtx();
+  const w = props.width ?? ctx?.meta.width ?? 1920;
+  const h = props.height ?? ctx?.meta.height ?? 1080;
+  const list = sparkles(t, { ...props, width: w, height: h });
+  const colors = props.colors ?? ["#fff"];
+  const size = props.size ?? 28;
+  return (
+    <svg aria-hidden width={w} height={h} viewBox={`0 0 ${w} ${h}`} style={{ position: "absolute", inset: 0, pointerEvents: "none", ...props.style }}>
+      {list.map((p) =>
+        p.opacity < 0.02 ? null : (
+          <path
+            key={p.i}
+            d={STAR}
+            fill={colors[Math.floor(p.hue * colors.length) % colors.length]}
+            opacity={p.opacity}
+            transform={`translate(${p.x.toFixed(1)} ${p.y.toFixed(1)}) rotate(${p.rotate.toFixed(1)}) scale(${((p.scale * size) / 24).toFixed(3)}) translate(-12 -12)`}
+          />
+        ),
+      )}
+    </svg>
+  );
+}
+
+/** 한 점에서 터지는 조각 */
+export function Burst(props: Timed & BurstOpts & { colors?: string[]; size?: number; shape?: "dot" | "star"; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const ctx = useCtx();
+  const w = ctx?.meta.width ?? 1920;
+  const h = ctx?.meta.height ?? 1080;
+  const list = burst(t, props);
+  const colors = props.colors ?? ["#fff"];
+  const size = props.size ?? 14;
+  return (
+    <svg aria-hidden width={w} height={h} viewBox={`0 0 ${w} ${h}`} style={{ position: "absolute", inset: 0, pointerEvents: "none", ...props.style }}>
+      {list.map((p) => {
+        const fill = colors[Math.floor(p.hue * colors.length) % colors.length];
+        return props.shape === "star" ? (
+          <path key={p.i} d={STAR} fill={fill} opacity={p.opacity} transform={`translate(${p.x.toFixed(1)} ${p.y.toFixed(1)}) rotate(${p.rotate.toFixed(1)}) scale(${((p.scale * size) / 24).toFixed(3)}) translate(-12 -12)`} />
+        ) : (
+          <circle key={p.i} cx={p.x.toFixed(1)} cy={p.y.toFixed(1)} r={((p.scale * size) / 2).toFixed(2)} fill={fill} opacity={p.opacity} />
+        );
+      })}
+    </svg>
+  );
+}
+
+/** 화살표 커서 + 누른 자리 물결 */
+export function Cursor(props: Timed & { keys: CursorKey[]; size?: number; color?: string }) {
+  const t = useT(props.t);
+  const c = cursor(t, props.keys);
+  const size = props.size ?? 44;
+  return (
+    <>
+      {c.ripple && (
+        <div
+          aria-hidden
+          style={{
+            position: "absolute",
+            left: c.ripple.x - size,
+            top: c.ripple.y - size,
+            width: size * 2,
+            height: size * 2,
+            borderRadius: "50%",
+            background: props.color ?? C.accent,
+            ...toCss({ scale: c.ripple.scale, opacity: c.ripple.opacity }),
+          }}
+        />
+      )}
+      <svg aria-hidden width={size} height={size} viewBox="0 0 24 24" style={{ position: "absolute", left: c.x, top: c.y, transform: `scale(${c.pressed ? 0.86 : 1})`, transformOrigin: "0 0", filter: "drop-shadow(0 2px 3px rgba(0,0,0,0.3))" }}>
+        <path d="M2 1 L2 19 L7 14.5 L10.5 22 L13.5 20.6 L10 13.2 L17 13 Z" fill="#fff" stroke="#111" strokeWidth={1.4} strokeLinejoin="round" />
+      </svg>
+    </>
+  );
+}
+
+/** 터미널 창 + 입력. 창은 style.json 의 term* 색이 있으면 그걸로 */
+export function Terminal(props: Timed & { steps: TermStep[]; title?: string; at?: number; prompt?: string; maxLines?: number; cps?: number; fontSize?: number; width?: number | string; height?: number | string; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const st = terminal(t, props.steps, { at: props.at, prompt: props.prompt, maxLines: props.maxLines, cps: props.cps });
+  const bg = v("term-surface", "#1A1D23");
+  const fg = v("term-text", "#ECEEF3");
+  const dim = v("term-dim", "#A0A6B0");
+  const acc = v("term-accent", "#5A8CE6");
+  const fs = props.fontSize ?? 30;
+  return (
+    <div
+      style={{
+        width: props.width ?? 1100,
+        height: props.height,
+        background: bg,
+        color: fg,
+        borderRadius: v("radius-md", "18px"),
+        boxShadow: v("shadow-soft", "0 8px 24px rgba(0,0,0,0.25)"),
+        overflow: "hidden",
+        fontFamily: C.mono,
+        fontSize: fs,
+        lineHeight: 1.45,
+        ...props.style,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: fs * 0.3, padding: `${fs * 0.45}px ${fs * 0.6}px`, borderBottom: `1px solid rgba(255,255,255,0.08)` }}>
+        {["#FF5F57", "#FEBC2E", "#28C840"].map((c) => (
+          <span key={c} style={{ width: fs * 0.42, height: fs * 0.42, borderRadius: "50%", background: c }} />
+        ))}
+        {props.title && <span style={{ marginLeft: fs * 0.4, color: dim, fontFamily: C.sans, fontSize: fs * 0.62 }}>{props.title}</span>}
+      </div>
+      <div style={{ padding: `${fs * 0.5}px ${fs * 0.7}px` }}>
+        {st.lines.map((l, i) => (
+          <div key={i} style={{ whiteSpace: "pre-wrap", color: l.kind === "out" ? dim : fg, minHeight: "1.45em" }}>
+            {l.kind === "cmd" && <span style={{ color: acc, marginRight: "0.6em" }}>{l.prompt}</span>}
+            {l.text}
+            {l.caret && <Caret on={l.text.length > 0 || Math.floor((t + 10) / 0.53) % 2 === 0} color={acc} mono />}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function CodeBlock(props: Timed & { code: string; at?: number; mode?: "line" | "type"; lps?: number; fontSize?: number; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const st = codeReveal(props.code, t, props);
+  const fs = props.fontSize ?? 28;
+  return (
+    <pre style={{ margin: 0, padding: fs * 0.9, background: C.raised, color: C.ink, borderRadius: v("radius-md", "12px"), fontFamily: C.mono, fontSize: fs, lineHeight: 1.5, ...props.style }}>
+      {st.lines.map((l, i) => (
+        <div key={i} style={{ minHeight: "1.5em", background: i === st.active ? C.accentSoft : "transparent", marginInline: -fs * 0.4, paddingInline: fs * 0.4, borderRadius: 4 }}>
+          {l}
+        </div>
+      ))}
+    </pre>
+  );
+}
+
+/** 막대 차트가 자란다 */
+export function BarChart(props: Timed & { values: number[]; labels?: string[]; max?: number; at?: number; dur?: number; stagger?: number; width?: number; height?: number; color?: string; format?: (v: number) => string; style?: CSSProperties }) {
+  const t = useT(props.t);
+  const cur = grow(t, props.values, props);
+  const max = props.max ?? Math.max(1, ...props.values.filter((x) => Number.isFinite(x)));
+  const w = props.width ?? 900;
+  const h = props.height ?? 420;
+  const gap = 0.28;
+  const bw = w / (props.values.length * (1 + gap));
+  return (
+    <div style={{ position: "relative", width: w, height: h + 60, fontFamily: C.sans, ...props.style }}>
+      {cur.map((x, i) => {
+        const bh = (Math.max(0, x) / max) * h;
+        const left = i * bw * (1 + gap) + (bw * gap) / 2;
+        return (
+          <div key={i}>
+            <div style={{ position: "absolute", left, width: bw, bottom: 60, height: bh, background: props.color ?? C.accent, borderRadius: `${Math.min(12, bw / 4)}px ${Math.min(12, bw / 4)}px 0 0` }} />
+            <div style={{ position: "absolute", left, width: bw, bottom: 60 + bh + 8, textAlign: "center", color: C.ink, fontVariantNumeric: "tabular-nums", fontSize: 26, opacity: bh > 1 ? 1 : 0 }}>
+              {props.format ? safeText(props.format(x)) : Math.round(x).toLocaleString("en-US")}
+            </div>
+            {props.labels?.[i] !== undefined && (
+              <div style={{ position: "absolute", left: left - 20, width: bw + 40, bottom: 12, textAlign: "center", color: C.dim, fontSize: 24 }}>{safeText(props.labels[i])}</div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/** 기기 틀 — 안에 화면을 넣는다. 크기는 바깥 너비 기준 */
+export function DeviceFrame(props: { kind?: "phone" | "laptop" | "browser"; width?: number; url?: string; children?: ReactNode; style?: CSSProperties }) {
+  const kind = props.kind ?? "browser";
+  const w = props.width ?? (kind === "phone" ? 420 : 1280);
+  if (kind === "phone") {
+    const h = w * 2.08;
+    return (
+      <div style={{ position: "relative", width: w, height: h, borderRadius: w * 0.14, background: "#111", padding: w * 0.035, boxSizing: "border-box", boxShadow: v("shadow-lift", "0 20px 50px rgba(0,0,0,0.35)"), ...props.style }}>
+        <div style={{ position: "relative", width: "100%", height: "100%", borderRadius: w * 0.11, overflow: "hidden", background: C.bg }}>
+          {props.children}
+          <div style={{ position: "absolute", top: w * 0.03, left: "50%", width: w * 0.3, height: w * 0.075, marginLeft: -w * 0.15, borderRadius: w, background: "#111" }} />
+        </div>
+      </div>
+    );
+  }
+  const bar = Math.max(28, w * 0.034);
+  const screen = (
+    <div style={{ borderRadius: kind === "laptop" ? w * 0.012 : w * 0.01, overflow: "hidden", background: C.surface, border: `1px solid ${C.line}`, boxShadow: v("shadow-lift", "0 20px 50px rgba(0,0,0,0.25)") }}>
+      <div style={{ height: bar, display: "flex", alignItems: "center", gap: bar * 0.25, padding: `0 ${bar * 0.45}px`, background: C.raised, borderBottom: `1px solid ${C.line}` }}>
+        {["#FF5F57", "#FEBC2E", "#28C840"].map((c) => (
+          <span key={c} style={{ width: bar * 0.36, height: bar * 0.36, borderRadius: "50%", background: c }} />
+        ))}
+        {props.url !== undefined && (
+          <span style={{ marginLeft: bar * 0.6, flex: 1, maxWidth: "60%", height: bar * 0.6, borderRadius: bar, background: C.surface, color: C.dim, fontFamily: C.sans, fontSize: bar * 0.42, display: "flex", alignItems: "center", paddingLeft: bar * 0.4 }}>
+            {safeText(props.url)}
+          </span>
+        )}
+      </div>
+      <div style={{ position: "relative", width: "100%", aspectRatio: "16 / 10" }}>{props.children}</div>
+    </div>
+  );
+  if (kind === "browser") return <div style={{ width: w, ...props.style }}>{screen}</div>;
+  return (
+    <div style={{ width: w, ...props.style }}>
+      <div style={{ padding: w * 0.018, background: "#1d1f24", borderRadius: `${w * 0.025}px ${w * 0.025}px 0 0` }}>{screen}</div>
+      <div style={{ height: w * 0.025, margin: `0 ${-w * 0.06}px`, background: "linear-gradient(#d9dbe0, #a9acb3)", borderRadius: `0 0 ${w * 0.04}px ${w * 0.04}px` }} />
+    </div>
+  );
+}

package/packages/motion/src/react/time.tsx

@@ -0,0 +1,97 @@
+import { createContext, useContext, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
+import { frameTime, onFrame, safeTime, type Beats, type SceneCtx } from "@kasaframe/core";
+
+interface TimeValue {
+  /** 지금 상자 안 시각(초) */
+  t: number;
+  ctx: SceneCtx | null;
+  /** 장면 id — 움직임 이벤트에 붙인다 */
+  scene?: string;
+}
+
+const TimeContext = createContext<TimeValue | null>(null);
+
+/**
+ * 장면 맨 위에 둔다. 어댑터가 넘긴 { t, ctx } 를 아래 부품이 useTime()·useCtx() 로 받는다.
+ * 감싸지 않으면 부품은 페이지 전체 시각(frameTime)을 쓴다.
+ */
+export function KfScene(props: { t: number; ctx: SceneCtx; children?: ReactNode }) {
+  return <TimeContext.Provider value={{ t: safeTime(props.t), ctx: props.ctx, scene: props.ctx.id }}>{props.children}</TimeContext.Provider>;
+}
+
+const noop = () => () => {};
+
+export function useTime(): number {
+  const v = useContext(TimeContext);
+  const global = useSyncExternalStore(v ? noop : onFrame, frameTime, frameTime);
+  return v ? v.t : global;
+}
+
+export function useCtx(): SceneCtx | null {
+  return useContext(TimeContext)?.ctx ?? null;
+}
+
+export function useSceneId(): string | undefined {
+  return useContext(TimeContext)?.scene;
+}
+
+/** 장면 기준 박자. KfScene 밖이면 null */
+export function useBeats(): Beats | null {
+  return useCtx()?.beats ?? null;
+}
+
+/** 부품이 t 를 받았으면 그것을, 아니면 감싼 상자의 시각을 */
+export function useT(t?: number): number {
+  const ctxT = useTime();
+  return t === undefined ? ctxT : safeTime(t);
+}
+
+/** from 부터 dur 동안만 그리고, 안에서는 from 을 0 으로 센다 */
+export function Sequence(props: { from: number; dur?: number; children?: ReactNode; keep?: boolean }) {
+  const parent = useContext(TimeContext);
+  const t = useTime();
+  const local = t - props.from;
+  const active = local >= 0 && (props.dur === undefined || local < props.dur);
+  if (!active && !props.keep) return null;
+  return (
+    <TimeContext.Provider value={{ t: local, ctx: parent?.ctx ?? null, scene: parent?.scene }}>{props.children}</TimeContext.Provider>
+  );
+}
+
+/** 자식 SeriesItem 들을 차례로 이어 붙인다 */
+export function Series(props: { children?: ReactNode }) {
+  const items: { dur: number; offset: number; node: ReactNode }[] = [];
+  let at = 0;
+  const kids = Array.isArray(props.children) ? props.children.flat() : [props.children];
+  for (const k of kids) {
+    if (!k || typeof k !== "object" || !("props" in k)) continue;
+    const p = (k as { props: { dur?: number; offset?: number; children?: ReactNode } }).props;
+    const dur = p.dur ?? 0;
+    const from = at + (p.offset ?? 0);
+    items.push({ dur, offset: from, node: p.children });
+    at = from + dur;
+  }
+  return (
+    <>
+      {items.map((it, i) => (
+        <Sequence key={i} from={it.offset} dur={it.dur}>
+          {it.node}
+        </Sequence>
+      ))}
+    </>
+  );
+}
+
+/** Series 의 칸 — 그 자체는 그리지 않고 Series 가 읽는다 */
+export function SeriesItem(_props: { dur: number; offset?: number; children?: ReactNode }): null {
+  return null;
+}
+
+/** 화면 가득 — 겹쳐 쌓는 층 */
+export function Fill(props: { children?: ReactNode; style?: CSSProperties; className?: string }) {
+  return (
+    <div className={props.className} style={{ position: "absolute", inset: 0, overflow: "hidden", ...props.style }}>
+      {props.children}
+    </div>
+  );
+}

package/packages/motion/src/text.ts

@@ -0,0 +1,103 @@
+import { progress, toEase, type Ease, type EaseName, type Style, safeTime } from "@kasaframe/core";
+import { enter, stagger, type MoveName, type MoveOpts, type StaggerOpts } from "./enter.ts";
+
+export interface CounterOpts {
+  from?: number;
+  to: number;
+  at?: number;
+  dur?: number;
+  ease?: EaseName | Ease;
+  decimals?: number;
+  /** 세 자리 쉼표. 기본 켬 */
+  group?: boolean;
+  prefix?: string;
+  suffix?: string;
+  /** ko: 1.2만·3.4억 처럼 한국어 큰 단위로 */
+  unit?: "none" | "ko";
+}
+
+const fmt = (v: number, decimals: number, group: boolean): string => {
+  const fixed = Math.abs(v).toFixed(decimals);
+  const [int, frac] = fixed.split(".");
+  const g = group ? int.replace(/\B(?=(\d{3})+(?!\d))/g, ",") : int;
+  return (v < 0 && Number(fixed) !== 0 ? "-" : "") + g + (frac ? `.${frac}` : "");
+};
+
+function koUnit(v: number, decimals: number): string {
+  const a = Math.abs(v);
+  if (a >= 1e8) return `${fmt(v / 1e8, decimals, true)}억`;
+  if (a >= 1e4) return `${fmt(v / 1e4, decimals, true)}만`;
+  return fmt(v, 0, true);
+}
+
+/** 숫자가 굴러 오른다. 늘 글을 돌려주고, 수가 아닌 값이 와도 NaN 을 찍지 않는다 */
+export function counter(t: number, opts: CounterOpts): string {
+  t = safeTime(t);
+  const to = Number.isFinite(opts.to) ? opts.to : 0;
+  const from = opts.from !== undefined && Number.isFinite(opts.from) ? opts.from : 0;
+  const p = toEase(opts.ease, toEase("outCubic"))(progress(Number.isNaN(t) ? 0 : t, opts.at ?? 0, opts.dur ?? 1.2));
+  const v = from + (to - from) * p;
+  const decimals = Math.max(0, Math.min(6, Math.floor(opts.decimals ?? 0)));
+  const body = opts.unit === "ko" ? koUnit(v, decimals) : fmt(v, decimals, opts.group ?? true);
+  return `${opts.prefix ?? ""}${body}${opts.suffix ?? ""}`;
+}
+
+export interface SweepOpts {
+  at?: number;
+  dur?: number;
+  ease?: EaseName | Ease;
+  from?: "left" | "right";
+}
+
+/** 형광펜 쓸기 — 강조 띠 요소에 Style.clip 으로 준다 */
+export function sweep(t: number, opts: SweepOpts = {}): Style & { p: number } {
+  t = safeTime(t);
+  const p = toEase(opts.ease, toEase("inOutCubic"))(progress(t, opts.at ?? 0, opts.dur ?? 0.45));
+  return opts.from === "right" ? { p, clip: { left: 1 - p } } : { p, clip: { right: 1 - p } };
+}
+
+export interface WordState {
+  text: string;
+  index: number;
+  style: Style;
+}
+
+/** 낱말 키네틱 — 띄어쓰기로 나눠 차례로 들인다. 빈 낱말은 만들지 않는다 */
+export function words(
+  text: string,
+  t: number,
+  opts: MoveOpts & StaggerOpts & { move?: MoveName } = {},
+): WordState[] {
+  t = safeTime(t);
+  const src = typeof text === "string" ? text : "";
+  const list = src.split(/\s+/).filter((w) => w.length > 0);
+  return list.map((w, index) => ({
+    text: w,
+    index,
+    style: enter(opts.move ?? "rise", t, {
+      ...opts,
+      at: (opts.at ?? 0) + stagger(index, { ...opts, count: list.length }),
+      source: opts.source ?? "words",
+      emit: index === 0 && opts.emit !== false,
+    }),
+  }));
+}
+
+/** 글자 단위 — 제목 한 줄을 글자마다 들일 때. 서로게이트 쌍을 쪼개지 않는다 */
+export function letters(text: string, t: number, opts: MoveOpts & StaggerOpts & { move?: MoveName } = {}): WordState[] {
+  t = safeTime(t);
+  const list = Array.from(typeof text === "string" ? text : "");
+  return list.map((ch, index) => ({
+    text: ch,
+    index,
+    style:
+      ch.trim() === ""
+        ? {}
+        : enter(opts.move ?? "rise", t, {
+            ...opts,
+            at: (opts.at ?? 0) + stagger(index, { ...opts, each: opts.each ?? 0.03, count: list.length }),
+            source: opts.source ?? "letters",
+            emit: index === 0 && opts.emit !== false,
+          }),
+  }));
+}