kasaframe 0.0.0-stage → 0.1.3

package/packages/motion/src/transition3d/gl.ts

@@ -0,0 +1,219 @@
+import * as THREE from "three";
+import { clamp, rand, toEase } from "@kasaframe/core";
+import { GL_TRANSITIONS, type GlShader } from "../transitions2d/gl-transitions/shaders.ts";
+import { REVEAL_FRAGMENT, REVEAL_VARIANTS, SDF_FRAGMENT, SDF_VARIANTS } from "../transitions2d/smoothui/shaders.ts";
+import type { Kit, KindRun } from "./world.ts";
+
+export type GlValue = number | boolean | readonly number[];
+
+const byName = new Map(GL_TRANSITIONS.map((s) => [s.name, s]));
+
+/** gl-transitions 이름들 — `gl:<이름>` 으로 부른다 */
+export const GL_NAMES: readonly string[] = GL_TRANSITIONS.map((s) => s.name);
+
+/** SmoothUI 덮개 — `smooth:reveal-<갈래>` · `smooth:sdf-<갈래>` */
+export const SMOOTH_NAMES: readonly string[] = [...REVEAL_VARIANTS.map((v) => `reveal-${v}`), ...SDF_VARIANTS.map((v) => `sdf-${v}`)];
+
+export const glShader = (name: string): GlShader | undefined => byName.get(name);
+
+// 그림 두 장(앞·뒤 화면) 사이를 그리는 GLSL ES 1.00 — 원본이 WebGL1 용이라 three 의 GLSL3 머리를 안 붙이는 Raw 로 그대로 컴파일한다
+const VERT = /* glsl */ `
+attribute vec3 position;
+attribute vec2 uv;
+varying vec2 _uv;
+void main() {
+  _uv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}`;
+
+// gl-transition 래퍼(MIT, gre)와 같은 꼴 — 그림 비율이 화면과 다르면 cover 로 맞춘다(같으면 그대로)
+const HEAD = /* glsl */ `
+precision highp float;
+varying vec2 _uv;
+uniform sampler2D from, to;
+uniform float progress, ratio, _fromR, _toR;
+vec4 getFromColor(vec2 uv) { return texture2D(from, .5 + (uv - .5) * vec2(min(ratio / _fromR, 1.), min(_fromR / ratio, 1.))); }
+vec4 getToColor(vec2 uv) { return texture2D(to, .5 + (uv - .5) * vec2(min(ratio / _toR, 1.), min(_toR / ratio, 1.))); }
+`;
+
+const FOOT = /* glsl */ `
+void main() { gl_FragColor = transition(_uv); }`;
+
+const COPY = /* glsl */ `
+precision highp float;
+varying vec2 _uv;
+uniform sampler2D map;
+void main() { gl_FragColor = texture2D(map, _uv); }`;
+
+const literal = (type: string, v: GlValue): string => {
+  if (typeof v === "boolean") return v ? "true" : "false";
+  const num = (n: number) => (type.startsWith("i") || type === "int" ? String(Math.round(n)) : Number.isInteger(n) ? `${n}.0` : String(n));
+  return Array.isArray(v) ? `${type}(${v.map(num).join(", ")})` : num(v as number);
+};
+
+// 원본 기본값이 형과 어긋나게 적힌 것이 있다(angular 의 float 90, luminance_melt 의 bool 1) — GLSL ES 1.00 은 상수에 형 변환을 안 해 준다
+function fixDefault(type: string, v: string): string {
+  if (type === "float" && /^-?\d+$/.test(v)) return `${v}.0`;
+  if (type === "bool" && /^[01]$/.test(v)) return v === "1" ? "true" : "false";
+  if (type === "int" && /^-?\d+\.\d*$/.test(v)) return String(Math.round(Number(v)));
+  return v;
+}
+
+// 기본값이 붙은 uniform 은 상수로 — 고칠 값만 params 로 덮는다. 기본값 없는 sampler2D(displacement·luma 무늬)만 uniform 으로 남긴다
+function glSource(shader: GlShader, params: Record<string, GlValue> = {}): string {
+  const body = shader.glsl
+    .split("\n")
+    .map((line) => {
+      const p = shader.params.find((q) => line.trim().startsWith("uniform") && new RegExp(`\\b${q.name}\\b`).test(line));
+      if (!p || p.type === "sampler2D") return line;
+      const value = p.name in params ? literal(p.type, params[p.name]) : fixDefault(p.type, p.value ?? "");
+      return `const ${p.type} ${p.name} = ${value};`;
+    })
+    .join("\n");
+  return HEAD + body + FOOT;
+}
+
+// 무늬 그림 자리에 꽂는 시드 고정 노이즈 — 같은 시드면 같은 그림
+function noiseTexture(seed: string): THREE.DataTexture {
+  const n = 256;
+  const data = new Uint8Array(n * n * 4);
+  for (let i = 0; i < n * n; i++) {
+    const v = Math.floor(rand(seed, i) * 256);
+    data.set([v, v, v, 255], i * 4);
+  }
+  const tex = new THREE.DataTexture(data, n, n);
+  tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
+  tex.magFilter = tex.minFilter = THREE.LinearFilter;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+const ratioOf = (tex: THREE.Texture, fallback: number): number => {
+  const img = tex.image as { width?: number; height?: number; videoWidth?: number; videoHeight?: number } | null;
+  const w = img?.videoWidth || img?.width;
+  const h = img?.videoHeight || img?.height;
+  return w && h ? w / h : fallback;
+};
+
+function quad(mat: THREE.Material): THREE.Mesh {
+  const m = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), mat);
+  m.frustumCulled = false;
+  return m;
+}
+
+export interface GlOpts {
+  /** gl-transitions 매개변수 덮기 — 이름은 셰이더의 uniform 이름 */
+  params?: Record<string, GlValue>;
+}
+
+/** `gl:<이름>` — gl-transitions 한 조각. 진행도의 순수 함수라 같은 t 면 같은 그림 */
+export function glKind(name: string) {
+  const shader = byName.get(name);
+  if (!shader) throw new Error(`모르는 gl 전환: ${name} — kf transitions --source gl 로 이름을 본다`);
+  return (k: Kit, o: GlOpts): KindRun => {
+    const samplers = shader.params.filter((p) => p.type === "sampler2D");
+    const noise = samplers.length ? noiseTexture(`${k.seed}:${name}`) : null;
+    const uniforms: Record<string, THREE.IUniform> = {
+      from: { value: k.from.texture },
+      to: { value: k.to.texture },
+      progress: { value: 0 },
+      ratio: { value: k.aspect },
+      _fromR: { value: k.aspect },
+      _toR: { value: k.aspect },
+    };
+    for (const p of samplers) uniforms[p.name] = { value: noise };
+    const mat = new THREE.RawShaderMaterial({ vertexShader: VERT, fragmentShader: glSource(shader, o.params), uniforms, depthTest: false, depthWrite: false });
+    return passes(k, mat, (u) => {
+      uniforms.progress.value = u;
+      uniforms._fromR.value = ratioOf(k.from.texture, k.aspect);
+      uniforms._toR.value = ratioOf(k.to.texture, k.aspect);
+    }, () => noise?.dispose());
+  };
+}
+
+const easeInOutCubic = toEase("inOutCubic");
+
+/**
+ * `smooth:reveal-<갈래>`·`smooth:sdf-<갈래>` — SmoothUI 덮개가 덮었다 걷히며 가운데에서 앞 화면이 뒤 화면으로 바뀐다.
+ * 0.8 까지 덮개 진행, 절반을 넘으면 바탕을 갈고, 끝 0.2 동안 덮개가 사라진다. 원본은 덮개를 outQuart 로 몰아 첫 15% 에 다 지나가는데,
+ * 영상에서는 전환 가운데에 덮개가 가장 짙어야 읽혀서 inOutCubic 으로 고르게 편다
+ */
+export function smoothKind(name: string) {
+  const [family, variant] = name.split(/-(.*)/s) as [string, string];
+  const list: readonly string[] = family === "reveal" ? REVEAL_VARIANTS : family === "sdf" ? SDF_VARIANTS : [];
+  const index = list.indexOf(variant);
+  if (index < 0) throw new Error(`모르는 SmoothUI 덮개: ${name} (있는 것: ${SMOOTH_NAMES.join(" · ")})`);
+  return (k: Kit): KindRun => {
+    const uniforms: Record<string, THREE.IUniform> = {
+      uRes: { value: new THREE.Vector2(k.w, k.h) },
+      uTime: { value: 0 },
+      uProgress: { value: 0 },
+      uAlpha: { value: 0 },
+      uVariant: { value: index },
+    };
+    const overlay = new THREE.RawShaderMaterial({
+      vertexShader: VERT,
+      fragmentShader: family === "reveal" ? REVEAL_FRAGMENT : SDF_FRAGMENT,
+      uniforms,
+      depthTest: false,
+      depthWrite: false,
+      transparent: true,
+      blending: THREE.CustomBlending,
+      blendSrc: THREE.OneFactor,
+      blendDst: THREE.OneMinusSrcAlphaFactor,
+    });
+    const top = quad(overlay);
+    let base: THREE.Texture = k.from.texture;
+    const run = passes(k, null, (u, t) => {
+      const p = u < 0.8 ? easeInOutCubic(u / 0.8) : 1;
+      uniforms.uProgress.value = p;
+      uniforms.uAlpha.value = u < 0.8 ? 1 : 1 - easeInOutCubic(clamp((u - 0.8) / 0.2));
+      uniforms.uTime.value = t;
+      base = p < 0.5 ? k.from.texture : k.to.texture;
+      return base;
+    }, () => {
+      top.geometry.dispose();
+      overlay.dispose();
+    }, top);
+    return run;
+  };
+}
+
+/**
+ * 판 하나(필요하면 덮개 하나 더)를 화면 꽉 차게 그린다. 양 끝(u ≤ 0, u ≥ 1)은 셰이더를 거치지 않고 앞·뒤 화면 텍셀 그대로 —
+ * 원본 셰이더가 진행도 0·1 에서 어떻든 경계 프레임이 이어진다
+ */
+function passes(
+  k: Kit,
+  mat: THREE.RawShaderMaterial | null,
+  set: (u: number, t: number) => THREE.Texture | void,
+  free: () => void,
+  overlay?: THREE.Mesh,
+): KindRun {
+  const copyMat = new THREE.RawShaderMaterial({ vertexShader: VERT, fragmentShader: COPY, uniforms: { map: { value: k.from.texture } }, depthTest: false, depthWrite: false });
+  const plane = quad(copyMat);
+  const scene = new THREE.Scene();
+  scene.add(plane);
+  if (overlay) scene.add(overlay);
+  const cam = new THREE.Camera();
+  return {
+    frame(u, t) {
+      const base = set(u, t);
+      const edge = u <= 0 || u >= 1;
+      if (mat && !edge) plane.material = mat;
+      else {
+        plane.material = copyMat;
+        copyMat.uniforms.map.value = edge ? (u >= 1 ? k.to.texture : k.from.texture) : (base ?? k.from.texture);
+      }
+      if (overlay) overlay.visible = !edge;
+      k.renderer.clear(true, true, true);
+      k.renderer.render(scene, cam);
+    },
+    dispose() {
+      plane.geometry.dispose();
+      copyMat.dispose();
+      mat?.dispose();
+      free();
+    },
+  };
+}

package/packages/motion/src/transition3d/index.ts

@@ -0,0 +1,235 @@
+import { onSeek } from "@kasaframe/adapters";
+import { clamp, emit, frameSample, rand, safeTime, type BeatGrid, type KfStyle, type SceneCtx } from "@kasaframe/core";
+import { FIT, TRANSITIONS_3D, arrivalsOn, durOf, hump, rawProgress, resolveTiming, type FoldStyle, type Timing, type TimingOpts, type Transition3dName, type WindowRect } from "./rig.ts";
+import { camera, inPaint, makeScreen, placeholder, sharedRenderer, NO_FX, type CamFx, type Kit, type KindRun, type Palette, type Screen, type Source } from "./world.ts";
+import { liveNeighbors, type LiveProject } from "./live.ts";
+import { cards } from "./cards.ts";
+import { chain } from "./chain.ts";
+import { dive } from "./dive.ts";
+import { fold } from "./fold.ts";
+import { portal } from "./portal.ts";
+import { shatter } from "./shatter.ts";
+import { zoomOut } from "./zoomOut.ts";
+import { whip } from "./whip.ts";
+import { land, rise, type HeroRect } from "./space.ts";
+import { GL_NAMES, SMOOTH_NAMES, glKind, smoothKind, type GlValue } from "./gl.ts";
+
+export { TRANSITIONS_3D, DUR_3D, FIT, FOV, CHAIN_GAP, durOf, resolveTiming, rawProgress, arrivalsOn } from "./rig.ts";
+export { GL_NAMES, SMOOTH_NAMES, glShader } from "./gl.ts";
+export type { GlValue } from "./gl.ts";
+export { diveRig, portalRig, cardsRig, cardSlots, shatterRig, tiles, tileAmount, zoomOutRig, foldRig, chainRig, chainZ, whipRig } from "./rig.ts";
+export type { Transition3dName, Timing, TimingOpts, Pose, FoldStyle, WindowRect, ChainOpts } from "./rig.ts";
+export type { Painter, Source, Palette, LiveDom, VideoSource } from "./world.ts";
+export { elementTextures } from "./world.ts";
+export { sceneSource, liveNeighbors } from "./live.ts";
+export type { LiveProject } from "./live.ts";
+export type { HeroRect } from "./space.ts";
+
+export interface Transition3dOpts extends TimingOpts {
+  /** 기본 dive */
+  kind?: Transition3dName;
+  /** 앞 장면 화면. ctx 가 있으면 기본은 assets/seam/<장면id>-from.png(앞 장면 마지막 프레임) */
+  from?: Source;
+  /** 뒤 장면 화면. 기본 assets/seam/<장면id>-to.png(뒤 장면 첫 프레임) */
+  to?: Source;
+  /** 앞·뒤 장면을 살아 있는 화면으로 — { kf, scenes: import.meta.glob("./*.ts", { eager: true }) }. 앞 장면이 전환 중에도 계속 돈다 */
+  live?: LiveProject;
+  /** diveChain — 뚫고 들어갈 화면들(기본 [from, to]) */
+  screens?: Source[];
+  /** diveChain — 화면마다 꽉 차는 시각(장면 안 초), 또는 박자 격자("beat"·"bar"…)에 한 겹씩 */
+  arrivals?: number[] | BeatGrid;
+  /** diveChain — 0 흘러가기 … 1 화면마다 멈추기. 기본 0.35 */
+  settle?: number;
+  width?: number;
+  height?: number;
+  seed?: string | number;
+  colors?: Partial<Palette>;
+  /** zoomOut — 앞 장면이 뒤 장면의 어느 창이었나 */
+  window?: WindowRect;
+  /** fold — accordion 접기 · roll 말기 */
+  fold?: FoldStyle;
+  /** rise·land — 3D 로 서거나 내려앉을 주인공 상자(화면 비율, 왼쪽 위 0). 안 주면 살아 있는 장면의 [data-kf-hero] 를 프레임마다 잰다 */
+  hero?: HeroRect;
+  /** gl:<이름> — 셰이더 매개변수 덮기(uniform 이름 → 값) */
+  params?: Record<string, GlValue>;
+  /** 빠르기 곡선 — ramp(기본): 천천히 들어가다 확 빨라진다 · linear: 종류가 정한 그대로 */
+  pace?: "ramp" | "linear";
+  /** 3D — 끝에서 살짝 넘쳐 들어갔다 선다(기본 켬) */
+  land?: boolean;
+  /** 3D — 카메라 충격 시각(장면 안 초). 기본은 이 전환 안에 든 드롭. false 면 끈다 */
+  hits?: number[] | false;
+  /** 3D — 피사계 심도 조리개(화면 높이 1 기준). 렌더의 모션 블러 하위 프레임 평균에서만 보인다. 기본 0.03, 0 이면 끈다 */
+  dof?: number;
+  scene?: string;
+  source?: string;
+  emit?: boolean;
+}
+
+export type Transition3dDraw = ((t: number) => void) & { timing: Timing; kind: Transition3dName; dispose(): void };
+
+type Build = (k: Kit, o: Transition3dOpts & { arrivals: number[] }) => KindRun & { visible?(t: number): boolean[] };
+const KINDS: Record<(typeof TRANSITIONS_3D)[number], Build> = { dive, portal, cards, shatter, zoomOut, fold, diveChain: chain, whip, rise, land };
+
+function builderOf(kind: Transition3dName): Build | undefined {
+  if (kind.startsWith("gl:")) return glKind(kind.slice(3));
+  if (kind.startsWith("smooth:")) return smoothKind(kind.slice(7));
+  return (KINDS as Partial<Record<string, Build>>)[kind];
+}
+
+/** 이름 하나로 부를 수 있는 전환 전부 — 3D 일곱 · gl-transitions · SmoothUI 덮개 */
+export const KINDS_ALL: readonly Transition3dName[] = [...TRANSITIONS_3D, ...GL_NAMES.map((n) => `gl:${n}` as const), ...SMOOTH_NAMES.map((n) => `smooth:${n}` as const)];
+
+const DEFAULT_PALETTE: Palette = { bg: "#13203d", deep: "#070b18", accent: "#4A90E2", glow: "#A9CBF0", ink: "#EAF2FF" };
+
+/** 3D 공간은 어두워야 빛이 산다 — 밝은 스타일이면 밤 색을 깊은 바탕으로 */
+export function paletteOf(style: KfStyle | null | undefined, over: Partial<Palette> = {}): Palette {
+  if (!style?.colors) return { ...DEFAULT_PALETTE, ...over };
+  const c = style.colors;
+  const deep = c.nightBg ?? (style.scheme === "dark" ? c.bg : c.ink);
+  return { bg: c.bg, deep, accent: c.accent, glow: c.accentSoft ?? c.accent, ink: c.ink, ...over };
+}
+
+const isCtx = (x: unknown): x is SceneCtx => !!x && typeof x === "object" && "meta" in x && "asset" in x && "id" in x;
+
+/**
+ * 장면 전환을 three.js 3D 로 그린다. 장면 파일의 build 에서 부르고 반환값을 그대로 돌려준다 —
+ * `build(root, ctx) { return transition3d(root, ctx, { kind: "dive" }); }`. 같은 t 면 같은 그림이고,
+ * 구간 앞은 앞 장면 화면, 끝은 뒤 장면 화면 그대로다(경계 프레임이 이어진다).
+ */
+export function transition3d(root: HTMLElement, ctxOrOpts?: SceneCtx | Transition3dOpts | null, more: Transition3dOpts = {}): Transition3dDraw {
+  const ctx = isCtx(ctxOrOpts) ? ctxOrOpts : null;
+  const o: Transition3dOpts = isCtx(ctxOrOpts) ? more : { ...(ctxOrOpts ?? {}), ...more };
+  const kind = o.kind ?? "dive";
+  const build = builderOf(kind);
+  if (!build) throw new Error(`모르는 3D 전환: ${kind} (있는 것: ${TRANSITIONS_3D.join(" · ")} · gl:<이름> · smooth:<이름> — kf transitions)`);
+  const w = o.width ?? ctx?.meta.width ?? 1920;
+  const h = o.height ?? ctx?.meta.height ?? 1080;
+  // ctx 만 주면(이음매 장면) 앞 장면 마지막 프레임(-1 프레임)에서 뒤 장면 첫 프레임(장면 끝)까지 잇는다.
+  // 그 두 프레임은 앞·뒤 장면이 이미 찍으므로 같은 그림이 두 번 나오지 않는다
+  const fps = ctx?.meta.fps ?? 60;
+  let timing =
+    ctx && o.at === undefined && o.dur === undefined && o.endAt === undefined && !o.snap
+      ? { at: -1 / fps, dur: ctx.dur + 1 / fps }
+      : resolveTiming({ ...o, beats: o.beats ?? ctx?.beats }, durOf(kind), ctx?.dur);
+  const pal = paletteOf(ctx?.style, o.colors);
+  const seed = String(o.seed ?? ctx?.id ?? kind);
+  const scene = o.scene ?? ctx?.id;
+  const source = o.source ?? `transition3d:${kind}`;
+
+  const host = document.createElement("div");
+  host.style.cssText = `position:absolute;inset:0;overflow:hidden;background:${pal.deep}`;
+  root.append(host);
+  const renderer = sharedRenderer(w, h);
+  const env = { host, w, h, renderer, sceneFrom: ctx?.from ?? 0 };
+  const near = o.live && ctx ? liveNeighbors(ctx, o.live) : {};
+  const fromSrc = o.from ?? near.from ?? (ctx ? ctx.asset(`seam/${ctx.id}-from.png`) : undefined);
+  const toSrc = o.to ?? near.to ?? (ctx ? ctx.asset(`seam/${ctx.id}-to.png`) : undefined);
+  const screens: Screen[] = (o.screens ?? [fromSrc, toSrc]).map((src, i, all) => makeScreen(src, placeholder(pal, i === all.length - 1 && i > 0 ? 1 : 0), env));
+
+  // 화면이 여럿이면(diveChain) 꽉 차는 시각들. 구간 진행도 u 는 첫 도착 → 마지막 도착
+  let arrivals: number[];
+  if (Array.isArray(o.arrivals)) arrivals = o.arrivals;
+  else if (typeof o.arrivals === "string" && (o.beats ?? ctx?.beats)) arrivals = arrivalsOn((o.beats ?? ctx?.beats)!, o.arrivals, o.at ?? Math.max(0, timing.at), screens.length);
+  else arrivals = screens.map((_, i) => timing.at + (timing.dur * i) / Math.max(1, screens.length - 1));
+  if (o.screens || o.arrivals) timing = { at: arrivals[0], dur: arrivals[arrivals.length - 1] - arrivals[0] };
+
+  const kit: Kit = { renderer, cam: camera(w / h), aspect: w / h, w, h, seed, pal, from: screens[0], to: screens[screens.length - 1], screens };
+  const run = build(kit, { ...o, arrivals });
+  const live = screens.some((s) => s.live);
+
+  // 이 전환이 그리는 동안 다른 전환이 캔버스에 남긴 살아 있는 DOM 은 스냅숏에서 뺀다
+  const hideOthers = () => {
+    const mine = new Set(screens.map((s) => s.box).filter(Boolean));
+    for (const el of Array.from(kit.renderer.domElement.children) as HTMLElement[]) if (!mine.has(el) && el.style.display !== "none") el.style.display = "none";
+  };
+
+  // 카메라 효과 — 3D 종류만. 셰이더 전환(gl·smooth)은 화면 평면이라 빠르기 곡선만 받는다
+  const is3d = !kind.startsWith("gl:") && !kind.startsWith("smooth:");
+  const ramp = (o.pace ?? "ramp") === "ramp";
+  const land = is3d && o.land !== false;
+  const aperture = is3d ? (o.dof ?? 0.03) : 0;
+  const drops = ctx?.beats?.drops ?? [];
+  const hits = !is3d || o.hits === false ? [] : (o.hits ?? drops.filter((d) => d > timing.at && d < timing.at + timing.dur));
+  const fx: CamFx = { ...NO_FX, shake: [0, 0], jitter: [0, 0] };
+  kit.cam.userData.fx = fx;
+  const effects = (u: number, t: number) => {
+    const inside = u > 0 && u < 1;
+    // 끝 18% — 시선 방향으로 넘쳐 들어갔다가 돌아와 선다. 끝에서 값·빠르기 모두 0
+    const s = clamp((u - 0.82) / 0.18);
+    fx.dolly = land && inside ? 0.07 * FIT * Math.sin(Math.PI * s) ** 2 * (1 - s) : 0;
+    let sx = 0;
+    let sy = 0;
+    let amp = 0;
+    let punch = 0;
+    for (const [i, h] of hits.entries()) {
+      const dt = t - h;
+      if (!inside || dt < 0 || dt > 0.5) continue;
+      const env = Math.exp(-dt / 0.11);
+      amp += 0.01 * env;
+      sx += 0.01 * env * Math.sin(2 * Math.PI * 17 * dt + rand(seed, 40 + i) * 6.283);
+      sy += 0.01 * env * Math.sin(2 * Math.PI * 13 * dt + rand(seed, 50 + i) * 6.283);
+      punch -= 7 * Math.exp(-dt / 0.16) * (1 - Math.exp(-dt / 0.02));
+    }
+    fx.shake = [sx, sy];
+    fx.fov = punch;
+    // 화면 높이 1 = 꽉 찬 화면이라 흔들림 0.01 은 높이의 1% — 검사가 px 로 센다. 흔들림이 0 을 지나는 프레임에도 남겨야
+    // 한 번 친 흔들림이 끊긴 여러 번으로 세이지 않는다 — 잦아드는 폭(amp)이 0.5px 넘는 동안 이어서 남긴다
+    const px = Math.hypot(sx, sy) * h;
+    if (amp * h > 0.5 && o.emit !== false) emit({ kind: "shake", source: `${source}:hit`, scene, value: Math.round(px * 10) / 10 });
+    const smp = frameSample();
+    if (aperture > 0 && inside && smp.count > 1) {
+      // 황금각 나선 — 하위 프레임들이 조리개 원판을 고르게 덮는다
+      const r = Math.sqrt((smp.index + 0.5) / smp.count) * aperture * hump(u);
+      const a = smp.index * 2.399963 + rand(seed, 60) * 6.283;
+      fx.jitter = [r * Math.cos(a), r * Math.sin(a)];
+    } else fx.jitter = [0, 0];
+  };
+
+  let pending: number | null = null;
+  const paint = (t: number) => {
+    const u = rawProgress(t, timing);
+    effects(u, t);
+    // 천천히 들어가다 확 빨라진다 — 출발 빠르기는 0.3 배로 남겨 멈춰 보이지 않게
+    run.frame(ramp ? 0.3 * u + 0.7 * u * u * u : u, t);
+  };
+  const draw = ((t: number) => {
+    t = safeTime(t);
+    kit.renderer = sharedRenderer(w, h);
+    if (kit.renderer.domElement.parentNode !== host) host.append(kit.renderer.domElement);
+    const vis = run.visible?.(t);
+    screens.forEach((s, i) => {
+      s.show(vis ? vis[i] : true);
+      s.update(t);
+    });
+    if (live) hideOthers();
+    if (live || screens.some((s) => s.loaded())) pending = t;
+    paint(t);
+    const u = rawProgress(t, timing);
+    if (o.emit !== false && u > 0 && u < 1) emit({ kind: "move", source, scene, name: `transition3d:${kind}`, value: 1 });
+  }) as Transition3dDraw;
+  // seek 의 그리기 단계 뒤 — 영상은 엔진이 시각을 맞춘 뒤, DOM 은 이번 DOM 으로 찍힌 스냅숏(paint 이벤트) 안에서 올리고 같은 t 로 다시 그린다.
+  // React 장면은 첫 seek 에서야 지어져 페이지 ready 가 그림을 못 기다리므로 여기서 받는다
+  const off = onSeek(async () => {
+    if (pending === null) return;
+    const t = pending;
+    pending = null;
+    await Promise.all(screens.map((s) => s.loaded()));
+    // React 커밋 안에서 불렸으면 살아 있는 React 장면의 flushSync 가 미뤄졌을 수 있다 — 바깥에서 한 번 더(같은 t 라 같은 화면)
+    for (const s of screens) s.update(t);
+    const again = () => {
+      for (const s of screens) s.refresh();
+      paint(t);
+    };
+    if (screens.some((s) => s.live === "dom")) await inPaint(kit.renderer.domElement, again);
+    else again();
+  });
+  draw.timing = timing;
+  draw.kind = kind;
+  draw.dispose = () => {
+    off();
+    run.dispose();
+    for (const s of screens) s.dispose();
+    host.remove();
+  };
+  return draw;
+}

package/packages/motion/src/transition3d/live.ts

@@ -0,0 +1,70 @@
+import { createBeats, silentBeats, type SceneCtx } from "@kasaframe/core";
+import type { KfProjectJson, KfSceneEntry, SceneModule } from "@kasaframe/adapters";
+import { reactScene } from "@kasaframe/adapters/react";
+import type { LiveDom, Source } from "./world.ts";
+
+/** 장면 파일 모음 — main.ts 처럼 import.meta.glob("./*.ts", { eager: true }) 그대로 */
+export interface LiveProject {
+  kf: Pick<KfProjectJson, "scenes">;
+  scenes: Record<string, unknown>;
+}
+
+function baseName(p: string): string {
+  return p.split("/").pop()!.replace(/\.[^.]+$/, "");
+}
+
+function moduleOf(scenes: Record<string, unknown>, entry: KfSceneEntry): SceneModule | null {
+  const file = entry.file?.replace(/^\.\//, "").replace(/^scenes\//, "");
+  for (const [key, mod] of Object.entries(scenes)) {
+    const k = key.replace(/^\.\//, "");
+    if (baseName(k) === entry.id || (file && (k === file || k.endsWith(`/${file}`)))) {
+      const m = mod as { default?: SceneModule } & SceneModule;
+      return m.default ?? m;
+    }
+  }
+  return null;
+}
+
+/**
+ * 다른 장면 하나를 살아 있는 화면으로 — 그 장면 모듈을 한 벌 더 지어 time(t) 시각으로 그린다.
+ * 전환 중에도 앞 장면 타자·카운터가 이어서 움직인다.
+ */
+export function sceneSource(mod: SceneModule, ctx: SceneCtx, entry: Pick<KfSceneEntry, "id" | "from" | "dur">, time: (t: number) => number, still?: Source): LiveDom {
+  return {
+    dom(root) {
+      // 장면 뿌리와 같은 꼴. data-kf-scene 은 달지 않는다 — 검사가 진짜 장면 뿌리로 센다
+      const box = document.createElement("div");
+      box.style.cssText = "position:absolute;inset:0;overflow:hidden;";
+      root.append(box);
+      const sub: SceneCtx = {
+        ...ctx,
+        id: entry.id,
+        from: entry.from,
+        dur: entry.dur,
+        beats: ctx.beats?.data ? createBeats(ctx.beats.data, entry.from) : silentBeats(entry.dur),
+      };
+      if (mod.react) return reactScene(box, mod.react, sub);
+      return mod.build?.(box, sub) ?? undefined;
+    },
+    time,
+    still,
+  };
+}
+
+/**
+ * 이음매 장면의 앞·뒤 장면을 살아 있는 화면으로. 앞 장면은 자기 끝을 지나 계속 돌고(앞 장면 시각 = 앞 장면 길이 + t),
+ * 뒤 장면은 첫 프레임에 서 있다가 이음매가 끝나는 순간 제 시각을 시작한다. HTML-in-Canvas 가 없으면 assets/seam 정지 그림.
+ */
+export function liveNeighbors(ctx: SceneCtx, project: LiveProject): { from?: LiveDom; to?: LiveDom } {
+  const list = project.kf.scenes;
+  const i = list.findIndex((s) => s.id === ctx.id);
+  if (i < 0) return {};
+  const prev = list[i - 1];
+  const next = list[i + 1];
+  const pm = prev && moduleOf(project.scenes, prev);
+  const nm = next && moduleOf(project.scenes, next);
+  return {
+    from: pm ? sceneSource(pm, ctx, prev, (t) => prev.dur + t, ctx.asset(`seam/${ctx.id}-from.png`)) : undefined,
+    to: nm ? sceneSource(nm, ctx, next, (t) => Math.max(0, t - ctx.dur), ctx.asset(`seam/${ctx.id}-to.png`)) : undefined,
+  };
+}

package/packages/motion/src/transition3d/portal.ts

@@ -0,0 +1,115 @@
+import * as THREE from "three";
+import { FIT, PORTAL_DEPTH, portalRig, rr } from "./rig.ts";
+import { aim, disposeTree, dust, imageMaterial, raw, sky, type Kit } from "./world.ts";
+
+// 앞 장면 판에 둥근 구멍. 반지름 0 이면 테두리 빛도 0 이라 텍셀 그대로
+const HOLE_FRAG = /* glsl */ `
+uniform sampler2D map;
+uniform vec2 center;
+uniform float radius;
+uniform float aspect;
+uniform vec3 rimColor;
+uniform vec3 hotColor;
+varying vec2 vUv;
+void main() {
+  vec2 p = (vUv - 0.5) * vec2(aspect, 1.0);
+  float d = length(p - center);
+  if (d < radius) discard;
+  vec3 c = texture2D(map, vUv).rgb;
+  float rim = min(0.035, radius * 0.4);
+  if (rim > 0.0) {
+    float k = 1.0 - smoothstep(radius, radius + rim, d);
+    float halo = (1.0 - smoothstep(radius, radius + rim * 6.0, d)) * 0.35;
+    c = mix(c, rimColor, halo);
+    c = mix(c, hotColor, k);
+  }
+  gl_FragColor = vec4(c, 1.0);
+}`;
+
+// 터널 안벽 — 고리와 세로줄, 깊을수록 빛 쪽으로
+const TUNNEL_FRAG = /* glsl */ `
+uniform vec3 base;
+uniform vec3 line;
+uniform vec3 glow;
+uniform float len;
+varying vec2 vUv;
+void main() {
+  float z = vUv.y * len;
+  vec2 g = vec2(vUv.x * 28.0, z * 1.6);
+  vec2 w = fwidth(g);
+  vec2 l = abs(fract(g - 0.5) - 0.5) / max(w, 1e-4);
+  float ring = 1.0 - min(l.y / 1.2, 1.0);
+  float rib = 1.0 - min(l.x / 0.9, 1.0);
+  float depth = 1.0 - vUv.y;
+  vec3 c = base + line * (ring * 0.9 + rib * 0.35) * (0.4 + 0.6 * depth);
+  c = mix(c, glow, smoothstep(0.55, 1.0, depth) * 0.6);
+  gl_FragColor = vec4(c, 1.0);
+}`;
+
+const VERT = /* glsl */ `varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`;
+
+export function portal(k: Kit) {
+  const { aspect, pal, seed } = k;
+  const env = { aspect, seed };
+  const scene = new THREE.Scene();
+  scene.add(sky({ top: pal.deep, bottom: "#020308", glow: pal.accent, dir: [0, 0, -1], amt: 0.5, pow: 10 }));
+
+  const holeMat = new THREE.ShaderMaterial({
+    vertexShader: VERT,
+    fragmentShader: HOLE_FRAG,
+    uniforms: {
+      map: { value: k.from.texture },
+      center: { value: new THREE.Vector2() },
+      radius: { value: 0 },
+      aspect: { value: aspect },
+      rimColor: { value: raw(pal.accent) },
+      hotColor: { value: raw(pal.glow) },
+    },
+  });
+  scene.add(new THREE.Mesh(new THREE.PlaneGeometry(aspect, 1), holeMat));
+
+  const R = 1.45;
+  const len = PORTAL_DEPTH + 0.6;
+  const tube = new THREE.Mesh(
+    new THREE.CylinderGeometry(R, R, len, 96, 1, true),
+    new THREE.ShaderMaterial({
+      vertexShader: VERT,
+      fragmentShader: TUNNEL_FRAG,
+      uniforms: { base: { value: raw(pal.deep) }, line: { value: raw(pal.accent) }, glow: { value: raw(pal.glow) }, len: { value: len } },
+      side: THREE.BackSide,
+    }),
+  );
+  // 원통 축(y)을 화면 깊이(-z)로 눕힌다. uv.y 1 이 입구 쪽
+  tube.rotation.x = -Math.PI / 2;
+  tube.position.z = -len / 2 - 0.02;
+  scene.add(tube);
+
+  const n = 700;
+  const pts = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) {
+    const a = rr(seed, 500 + i, 0, Math.PI * 2);
+    const r = rr(seed, 1500 + i, 0.55, R - 0.08);
+    pts[i * 3] = Math.cos(a) * r;
+    pts[i * 3 + 1] = Math.sin(a) * r;
+    pts[i * 3 + 2] = rr(seed, 2500 + i, -PORTAL_DEPTH + FIT + 0.3, -0.2);
+  }
+  scene.add(dust(pts, pal.glow, 0.012));
+
+  const toPlane = new THREE.Mesh(new THREE.PlaneGeometry(aspect, 1), imageMaterial(k.to.texture));
+  toPlane.position.z = -PORTAL_DEPTH;
+  scene.add(toPlane);
+
+  return {
+    frame(u: number) {
+      const s = portalRig(u, env);
+      aim(k.cam, s.cam);
+      holeMat.uniforms.radius.value = s.radius;
+      holeMat.uniforms.center.value.set(s.center[0], s.center[1]);
+      k.renderer.clear(true, true, true);
+      k.renderer.render(scene, k.cam);
+    },
+    dispose() {
+      disposeTree(scene);
+    },
+  };
+}

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

@@ -0,0 +1,29 @@
+import { useLayoutEffect, useRef, type CSSProperties } from "react";
+import { useCtx, useSceneId, useT } from "../react/time.tsx";
+import { transition3d, type Transition3dDraw, type Transition3dOpts } from "./index.ts";
+
+/**
+ * 3D 전환을 React 장면에. KfScene 안이면 시각·ctx(크기·스타일·박자·seam 그림 기본 경로)를 알아서 받는다.
+ * `<KfScene t={t} ctx={ctx}><Transition3D kind="portal" /></KfScene>`
+ */
+export function Transition3D(props: Transition3dOpts & { t?: number; style?: CSSProperties; className?: string }) {
+  const t = useT(props.t);
+  const ctx = useCtx();
+  const scene = useSceneId();
+  const host = useRef<HTMLDivElement>(null);
+  const draw = useRef<Transition3dDraw | null>(null);
+  const { t: _t, style, className, ...o } = props;
+  // 재료가 바뀔 때만 three 장면을 새로 짓는다 — 시각만 바뀌면 다시 그리기만
+  useLayoutEffect(() => {
+    const d = transition3d(host.current!, ctx, { scene, ...o });
+    draw.current = d;
+    return () => {
+      d.dispose();
+      draw.current = null;
+    };
+  }, [ctx, scene, o.kind, o.from, o.to, o.live, o.screens, o.arrivals, o.settle, o.at, o.dur, o.endAt, o.snap, o.beats, o.seed, o.fold, o.window?.x, o.window?.y, o.window?.h, o.width, o.height, JSON.stringify(o.colors ?? null)]);
+  useLayoutEffect(() => {
+    draw.current?.(t);
+  });
+  return <div ref={host} className={className} style={{ position: "absolute", inset: 0, ...style }} />;
+}