kasaframe 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,683 @@
+import * as THREE from "three";
+import { FIT, FOV, type Pose } from "./rig.ts";
+
+/** 장면 화면을 t 로 그리는 함수 — 같은 t 면 같은 그림이어야 한다 */
+export type Painter = (g: CanvasRenderingContext2D, t: number, w: number, h: number) => void;
+
+/** 시각마다 텍스처로 올리는 살아 있는 DOM. build 는 장면 build 와 같은 꼴(root 에 한 번 짓고 t 로 그리는 함수를 돌려준다) */
+export interface LiveDom {
+  dom(root: HTMLElement): ((t: number) => void) | void;
+  /** 전환 안 시각 → 이 화면의 시각. 기본은 그대로 */
+  time?: (t: number) => number;
+  /** HTML-in-Canvas 가 없는 브라우저(플래그 없는 크롬)에서 대신 쓸 화면 */
+  still?: Source;
+}
+
+/** <video> — data-kf-from 처럼 영상 전체 기준 from 초에 0 초부터 튼다. 엔진 media 어댑터가 시각을 맞춘다 */
+export interface VideoSource {
+  video: string;
+  from?: number;
+  rate?: number;
+  loop?: boolean;
+}
+
+/** 앞·뒤 장면 화면. 주소(kf still PNG 등)·그림·캔버스·그리기 함수·영상·살아 있는 DOM */
+export type Source = string | HTMLImageElement | HTMLCanvasElement | Painter | VideoSource | LiveDom;
+
+export interface Palette {
+  bg: string;
+  deep: string;
+  accent: string;
+  glow: string;
+  ink: string;
+}
+
+export interface Screen {
+  texture: THREE.Texture;
+  /** dom·video 는 seek 의 그리기 단계 뒤(영상 맞춤·페인트 뒤)에 텍스처를 다시 올려야 한다 */
+  live: "dom" | "video" | null;
+  /** 받는 중인 그림이 있으면 다 받을 때까지 */
+  loaded(): Promise<void> | null;
+  /** 흐린 꾸밈용 — 밉맵을 단 같은 그림 */
+  soft(): THREE.Texture;
+  /** 그리기 함수·살아 있는 DOM 을 t 로 */
+  update(t: number): void;
+  /** 영상 프레임·DOM 스냅숏을 텍스처로. DOM 은 페인트 이벤트 안에서 불러야 이번 프레임 그림이다 */
+  refresh(): void;
+  /** 살아 있는 DOM 을 이번 프레임에 스냅숏할지 */
+  show(on: boolean): void;
+  /** 살아 있는 DOM 화면의 상자(공유 캔버스 자식) */
+  box?: HTMLElement;
+  dispose(): void;
+}
+
+let shared: THREE.WebGLRenderer | null = null;
+
+// 크롬은 한 페이지에 WebGL 문맥을 16 개쯤만 살려 둔다. 전환이 여럿인 영상에서도 하나를 돌려 쓰고, 그리는 장면으로 캔버스를 옮긴다.
+// 살아 있는 DOM 화면은 이 캔버스의 자식이어야 텍스처로 올릴 수 있다(layoutSubtree).
+export function sharedRenderer(w: number, h: number): THREE.WebGLRenderer {
+  if (!shared) {
+    shared = new THREE.WebGLRenderer({ antialias: true, stencil: true, preserveDrawingBuffer: true, alpha: false, powerPreference: "high-performance" });
+    shared.setPixelRatio(1);
+    shared.outputColorSpace = THREE.SRGBColorSpace;
+    shared.autoClear = false;
+    shared.domElement.dataset.kfTransition3d = "";
+    shared.domElement.style.cssText = "position:absolute;inset:0;width:100%;height:100%;display:block";
+    if (elementTextures()) (shared.domElement as HTMLCanvasElement & { layoutSubtree: boolean }).layoutSubtree = true;
+  }
+  const size = shared.getSize(new THREE.Vector2());
+  if (size.x !== w || size.y !== h) shared.setSize(w, h, false);
+  return shared;
+}
+
+/** HTML-in-Canvas(크롬 --enable-features=CanvasDrawElement) — DOM 을 그대로 WebGL 텍스처로 */
+export function elementTextures(): boolean {
+  return typeof (globalThis.WebGL2RenderingContext?.prototype as { texElementImage2D?: unknown } | undefined)?.texElementImage2D === "function" && "requestPaint" in HTMLCanvasElement.prototype;
+}
+
+type PaintCanvas = HTMLCanvasElement & { requestPaint(): void };
+
+/** 다음 렌더링 갱신의 paint 이벤트 안에서 fn — 자식 DOM 스냅숏이 이번 DOM 상태로 찍힌 뒤다. 가상 시계와 무관한 진짜 타이머로 끝을 막는다 */
+export function inPaint(canvas: HTMLCanvasElement, fn: () => void): Promise<void> {
+  const realTimeout = (window as { __kfClock?: { real: { setTimeout: typeof setTimeout } } }).__kfClock?.real.setTimeout ?? setTimeout;
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      canvas.removeEventListener("paint", run);
+      fn();
+      resolve();
+    };
+    const run = () => finish();
+    canvas.addEventListener("paint", run);
+    (canvas as PaintCanvas).requestPaint();
+    realTimeout(() => {
+      if (!done) console.warn("[kf] 3D 전환: paint 이벤트가 오지 않아 지난 DOM 스냅숏으로 그린다");
+      finish();
+    }, 3000);
+  });
+}
+
+// 페이지 ready 는 문서 안 <img> 를 기다린다. 없는 파일을 <img> 로 부르면 404 가 콘솔 오류로 찍혀 검사가 실패로 친다 —
+// 개발 서버는 없는 경로에 index.html 을 200 으로 주므로 content-type 으로 가린다.
+function urlExists(url: string, kind: "image/" | "video/"): boolean {
+  if (url.startsWith("data:") || url.startsWith("blob:")) return true;
+  const x = new XMLHttpRequest();
+  x.open("HEAD", url, false);
+  try {
+    x.send();
+  } catch {
+    return false;
+  }
+  return x.status === 200 && (x.getResponseHeader("content-type") ?? "").startsWith(kind);
+}
+
+function setup(tex: THREE.Texture): THREE.Texture {
+  // 텍셀을 그대로 내보낸다 — 색 공간을 오가면 경계 프레임이 앞·뒤 장면과 한두 단계 어긋난다
+  tex.colorSpace = THREE.NoColorSpace;
+  tex.minFilter = THREE.LinearFilter;
+  tex.magFilter = THREE.LinearFilter;
+  tex.generateMipmaps = false;
+  tex.wrapS = tex.wrapT = THREE.ClampToEdgeWrapping;
+  return tex;
+}
+
+function canvasOf(w: number, h: number): { canvas: HTMLCanvasElement; g: CanvasRenderingContext2D } {
+  const canvas = document.createElement("canvas");
+  canvas.width = w;
+  canvas.height = h;
+  return { canvas, g: canvas.getContext("2d")! };
+}
+
+export interface ScreenEnv {
+  /** 그림·영상 요소를 둘 곳(장면 안) */
+  host: HTMLElement;
+  w: number;
+  h: number;
+  renderer: THREE.WebGLRenderer;
+  /** 영상 from 기본값 — 이 장면이 시작하는 영상 전체 기준 초 */
+  sceneFrom: number;
+}
+
+const isVideo = (s: unknown): s is VideoSource => !!s && typeof s === "object" && typeof (s as VideoSource).video === "string";
+const isLive = (s: unknown): s is LiveDom => !!s && typeof s === "object" && typeof (s as LiveDom).dom === "function";
+
+// 같은 주소의 그림은 전환이 몇 개든 텍스처 하나 — 전환 백여 개가 그림 두 장을 함께 쓰면 GPU 메모리가 기가바이트로 불어난다
+const imageScreens = new Map<string, { screen: Screen; refs: number }>();
+
+export function makeScreen(src: Source | undefined, fallback: Painter, env: ScreenEnv): Screen {
+  if (isLive(src)) return elementTextures() ? domScreen(src, env) : makeScreen(src.still, fallback, env);
+  if (isVideo(src)) return urlExists(src.video, "video/") ? videoScreen(src, env) : makeScreen(undefined, fallback, env);
+  if (typeof src === "string" && urlExists(src, "image/")) {
+    const key = `${src}|${env.w}x${env.h}`;
+    let hit = imageScreens.get(key);
+    if (!hit) {
+      const screen = stillScreen(src, fallback, env);
+      const dispose = screen.dispose;
+      hit = { screen: { ...screen, dispose: () => {} }, refs: 0 };
+      const entry = hit;
+      entry.screen.dispose = () => {
+        if (--entry.refs > 0) return;
+        imageScreens.delete(key);
+        dispose();
+      };
+      imageScreens.set(key, hit);
+    }
+    hit.refs++;
+    return hit.screen;
+  }
+  // 없는 그림 주소는 부르지 않는다(대체 화면)
+  return stillScreen(typeof src === "string" ? undefined : src, fallback, env);
+}
+
+function stillScreen(src: Source | undefined, fallback: Painter, env: ScreenEnv): Screen {
+  const { host, w, h } = env;
+  let image: TexImageSource | HTMLCanvasElement;
+  let painter: Painter | null = null;
+  let pending: HTMLImageElement | null = null;
+  let live = false;
+  let g: CanvasRenderingContext2D | null = null;
+  const useFallback = () => {
+    const c = canvasOf(w, h);
+    painter = fallback;
+    g = c.g;
+    return c.canvas;
+  };
+  if (typeof src === "function") {
+    const c = canvasOf(w, h);
+    painter = src;
+    g = c.g;
+    image = c.canvas;
+  } else if (typeof src === "string") {
+    const img = document.createElement("img");
+    img.src = src;
+    img.decoding = "sync";
+    img.style.display = "none";
+    host.append(img);
+    pending = img;
+    image = useFallback();
+  } else if (src instanceof HTMLImageElement) {
+    pending = src;
+    image = useFallback();
+  } else if (src instanceof HTMLCanvasElement) {
+    image = src;
+    live = true;
+  } else image = useFallback();
+
+  const texture = setup(new THREE.Texture(image as HTMLCanvasElement));
+  texture.needsUpdate = true;
+  let softTex: THREE.Texture | null = null;
+  const touch = () => {
+    texture.needsUpdate = true;
+    if (softTex) {
+      softTex.image = texture.image;
+      softTex.needsUpdate = true;
+    }
+  };
+  return {
+    texture,
+    live: null,
+    loaded() {
+      return pending && !(pending.complete && pending.naturalWidth > 0) ? pending.decode().catch(() => {}) : null;
+    },
+    soft() {
+      if (!softTex) {
+        softTex = texture.clone();
+        softTex.generateMipmaps = true;
+        softTex.minFilter = THREE.LinearMipmapLinearFilter;
+        softTex.needsUpdate = true;
+      }
+      return softTex;
+    },
+    update(t) {
+      if (pending && pending.complete && pending.naturalWidth > 0) {
+        texture.image = pending;
+        painter = null;
+        pending = null;
+        touch();
+      }
+      if (painter && g) {
+        g.save();
+        g.clearRect(0, 0, w, h);
+        painter(g, t, w, h);
+        g.restore();
+        touch();
+      } else if (live) touch();
+    },
+    refresh() {},
+    show() {},
+    dispose() {
+      texture.dispose();
+      softTex?.dispose();
+    },
+  };
+}
+
+function videoScreen(src: VideoSource, env: ScreenEnv): Screen {
+  const v = document.createElement("video");
+  v.src = src.video;
+  v.muted = true;
+  v.playsInline = true;
+  v.preload = "auto";
+  v.loop = !!src.loop;
+  v.dataset.kfFrom = String(src.from ?? env.sceneFrom);
+  if (src.rate !== undefined) v.dataset.kfRate = String(src.rate);
+  // display:none 이면 디코더가 프레임을 안 내놓는 경우가 있어 화면 밖 작은 칸에 둔다
+  v.style.cssText = "position:absolute;left:0;top:0;width:2px;height:2px;opacity:0;pointer-events:none";
+  env.host.append(v);
+  const texture = setup(new THREE.Texture(v as unknown as HTMLCanvasElement));
+  return {
+    texture,
+    live: "video",
+    loaded: () => null,
+    soft: () => texture,
+    update() {},
+    refresh() {
+      if (v.readyState < 2) return;
+      // three 는 <video> 크기를 width·height 속성에서 읽는다(기본 0 이면 텍스처를 0 크기로 잡는다). 화면 배치는 CSS 가 쥔다
+      if (v.width !== v.videoWidth) v.width = v.videoWidth;
+      if (v.height !== v.videoHeight) v.height = v.videoHeight;
+      texture.needsUpdate = true;
+    },
+    show() {},
+    dispose() {
+      texture.dispose();
+      v.remove();
+    },
+  };
+}
+
+// 살아 있는 DOM 화면들 — 공유 캔버스 자식으로 두고, 이번 프레임에 쓰는 것만 보이게 해 스냅숏 비용을 줄인다
+function domScreen(src: LiveDom, env: ScreenEnv): Screen {
+  const { w, h, renderer } = env;
+  const canvas = renderer.domElement;
+  const box = document.createElement("div");
+  box.dataset.kfLive = "";
+  box.setAttribute("aria-hidden", "true");
+  box.style.cssText = `position:relative;width:${w}px;height:${h}px;overflow:hidden;background:#000;display:none`;
+  canvas.append(box);
+  const draw = src.dom(box) ?? (() => {});
+  const gl = renderer.getContext() as WebGL2RenderingContext & { texElementImage2D(target: number, internalformat: number, el: Element): void };
+  const glTex = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, glTex);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([0, 0, 0, 255]));
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  renderer.resetState();
+  const texture = new THREE.ExternalTexture(glTex);
+  return {
+    texture,
+    box,
+    live: "dom",
+    loaded: () => null,
+    soft: () => texture,
+    update(t) {
+      if (box.parentNode !== canvas) canvas.append(box);
+      draw(src.time ? src.time(t) : t);
+    },
+    refresh() {
+      if (box.style.display === "none") return;
+      gl.bindTexture(gl.TEXTURE_2D, glTex);
+      // three 의 그림 텍스처와 같은 방향(위가 v=1)
+      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+      try {
+        gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, box);
+      } catch {
+        // 아직 첫 스냅숏 전 — 다음 페인트에서 올린다
+      }
+      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+      renderer.resetState();
+    },
+    show(on) {
+      const d = on ? "block" : "none";
+      if (box.style.display !== d) box.style.display = d;
+    },
+    dispose() {
+      gl.deleteTexture(glTex);
+      box.remove();
+    },
+  };
+}
+
+/** 받은 그림이 아직 없을 때(kf still 전) 서는 화면 — 스타일 색으로 앞·뒤를 갈라 그린다 */
+export function placeholder(pal: Palette, side: 0 | 1): Painter {
+  return (g, _t, w, h) => {
+    const bg = g.createLinearGradient(0, 0, w, h);
+    bg.addColorStop(0, side ? pal.deep : pal.bg);
+    bg.addColorStop(1, side ? pal.bg : pal.deep);
+    g.fillStyle = bg;
+    g.fillRect(0, 0, w, h);
+    const k = h / 1080;
+    g.globalAlpha = 0.9;
+    g.fillStyle = pal.accent;
+    if (side === 0) {
+      g.beginPath();
+      g.arc(w * 0.68, h * 0.46, 210 * k, 0, Math.PI * 2);
+      g.fill();
+      g.globalAlpha = 0.5;
+      g.fillStyle = pal.glow;
+      g.fillRect(w * 0.14, h * 0.62, w * 0.3, 26 * k);
+      g.fillRect(w * 0.14, h * 0.68, w * 0.2, 26 * k);
+    } else {
+      g.save();
+      g.translate(w * 0.32, h * 0.5);
+      g.rotate(-0.2);
+      g.fillRect(-170 * k, -170 * k, 340 * k, 340 * k);
+      g.restore();
+      g.globalAlpha = 0.5;
+      g.fillStyle = pal.glow;
+      g.fillRect(w * 0.56, h * 0.36, w * 0.28, 26 * k);
+      g.fillRect(w * 0.56, h * 0.42, w * 0.18, 26 * k);
+    }
+    g.globalAlpha = 1;
+  };
+}
+
+// 화면 판 — 녹아 사라지는(dissolve) 칸과 지직거림(glitch). 두 값이 0 이면 텍셀 그대로
+export const SCREEN_FRAG = /* glsl */ `
+uniform sampler2D map;
+uniform float dissolve;
+uniform float glitch;
+uniform float sheen;
+uniform float tick;
+uniform float aspect;
+uniform float seed;
+uniform vec3 edge;
+varying vec2 vUv;
+float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7)) + seed * 17.13) * 43758.5453); }
+void main() {
+  vec2 uv = vUv;
+  float band = floor(uv.y * 36.0);
+  float h = hash(vec2(band, tick));
+  if (glitch > 0.0 && h > 1.0 - glitch * 0.3) uv.x += (hash(vec2(tick, band)) - 0.5) * 0.05 * glitch;
+  vec3 c = texture2D(map, uv).rgb;
+  if (glitch > 0.0) {
+    c.r = mix(c.r, texture2D(map, uv + vec2(0.004 * glitch, 0.0)).r, glitch);
+    c *= 1.0 - glitch * 0.1 * step(0.5, fract(vUv.y * 240.0));
+  }
+  vec2 g = vec2(vUv.x * aspect, vUv.y) * 30.0;
+  vec2 cell = floor(g);
+  vec2 cc = (cell + 0.5) / 30.0 - vec2(aspect * 0.5, 0.5);
+  float d = length(cc) / length(vec2(aspect * 0.5, 0.5));
+  float th = hash(cell) * 0.45 + d * 0.55;
+  float r = dissolve * 1.25 - 0.12;
+  if (th < r) discard;
+  if (th < r + 0.07) c = mix(c, edge, 0.85);
+  c += sheen * smoothstep(0.3, 1.0, 1.0 - abs(vUv.x - vUv.y * 0.6 - 0.1) * 2.5);
+  gl_FragColor = vec4(c, 1.0);
+}`;
+
+/** 녹아 사라지는 화면 판. dissolve·glitch·sheen 이 0 이면 텍셀 그대로 */
+export function screenMaterial(map: THREE.Texture, edge: string, aspect: number, seed: number): THREE.ShaderMaterial {
+  return new THREE.ShaderMaterial({
+    vertexShader: /* glsl */ `varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+    fragmentShader: SCREEN_FRAG,
+    uniforms: {
+      map: { value: map },
+      dissolve: { value: 0 },
+      glitch: { value: 0 },
+      sheen: { value: 0 },
+      tick: { value: 0 },
+      aspect: { value: aspect },
+      seed: { value: seed },
+      edge: { value: raw(edge) },
+    },
+  });
+}
+
+/** CSS 색을 셰이더에 날것 그대로 — 우리 셰이더는 출력 색 공간 변환을 거치지 않는다 */
+export const raw = (css: string): THREE.Color => new THREE.Color().setStyle(css, THREE.LinearSRGBColorSpace);
+
+/** 종류와 상관없이 카메라에 얹는 효과 — 진입점이 프레임마다 정한다. 전환 양 끝에서는 모두 0 이라 경계 프레임이 그대로다 */
+export interface CamFx {
+  /** 시선 방향으로 다가가는 거리(착지 넘침) */
+  dolly: number;
+  /** 화면 평면 흔들림(충격) */
+  shake: [number, number];
+  /** 더하는 기울기(라디안) */
+  roll: number;
+  /** 더하는 화각(도) — 음수면 당겨 들어간다(펀치) */
+  fov: number;
+  /** 조리개 위 자리 — 초점(시선 점)은 그대로 두고 카메라만 옮겨, 하위 프레임 평균이 피사계 심도가 된다 */
+  jitter: [number, number];
+}
+
+export const NO_FX: CamFx = { dolly: 0, shake: [0, 0], roll: 0, fov: 0, jitter: [0, 0] };
+
+export function aim(cam: THREE.PerspectiveCamera, pose: Pose) {
+  const fx = (cam.userData.fx as CamFx | undefined) ?? NO_FX;
+  cam.position.set(pose.pos[0], pose.pos[1], pose.pos[2]);
+  cam.up.set(0, 1, 0);
+  cam.lookAt(pose.look[0], pose.look[1], pose.look[2]);
+  if (fx.jitter[0] || fx.jitter[1]) {
+    cam.translateX(fx.jitter[0]);
+    cam.translateY(fx.jitter[1]);
+    cam.lookAt(pose.look[0], pose.look[1], pose.look[2]);
+  }
+  const roll = (pose.roll ?? 0) + fx.roll;
+  if (roll) cam.rotateZ(roll);
+  if (fx.dolly) cam.translateZ(-fx.dolly);
+  if (fx.shake[0] || fx.shake[1]) {
+    cam.translateX(fx.shake[0]);
+    cam.translateY(fx.shake[1]);
+  }
+  const fov = FOV + (pose.fov ?? 0) + fx.fov;
+  if (cam.fov !== fov) {
+    cam.fov = fov;
+    cam.updateProjectionMatrix();
+  }
+  cam.updateMatrixWorld(true);
+}
+
+export function camera(aspect: number): THREE.PerspectiveCamera {
+  const cam = new THREE.PerspectiveCamera(FOV, aspect, 0.01, 200);
+  cam.position.set(0, 0, FIT);
+  cam.updateProjectionMatrix();
+  return cam;
+}
+
+const IMAGE_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+
+// 장면 화면 판. 꾸밈 값이 모두 0 이면 텍셀을 그대로 낸다(경계 프레임 = 앞·뒤 장면).
+const IMAGE_FRAG = /* glsl */ `
+uniform sampler2D map;
+uniform vec4 uvRect;
+uniform float opacity;
+uniform float dim;
+uniform float bias;
+uniform vec3 tint;
+uniform float tintAmt;
+uniform vec3 backColor;
+varying vec2 vUv;
+void main() {
+  vec2 uv = uvRect.xy + vUv * uvRect.zw;
+  vec3 c = texture2D(map, uv, bias).rgb;
+  c = mix(c, tint, tintAmt);
+  c *= 1.0 - dim;
+  if (!gl_FrontFacing) c = mix(c * 0.35, backColor, 0.55);
+  gl_FragColor = vec4(c, opacity);
+}`;
+
+export type ImageMaterial = THREE.ShaderMaterial & {
+  uniforms: {
+    map: { value: THREE.Texture };
+    uvRect: { value: THREE.Vector4 };
+    opacity: { value: number };
+    dim: { value: number };
+    bias: { value: number };
+    tint: { value: THREE.Color };
+    tintAmt: { value: number };
+    backColor: { value: THREE.Color };
+  };
+};
+
+export function imageMaterial(map: THREE.Texture, o: { back?: string; double?: boolean } = {}): ImageMaterial {
+  return new THREE.ShaderMaterial({
+    vertexShader: IMAGE_VERT,
+    fragmentShader: IMAGE_FRAG,
+    uniforms: {
+      map: { value: map },
+      uvRect: { value: new THREE.Vector4(0, 0, 1, 1) },
+      opacity: { value: 1 },
+      dim: { value: 0 },
+      bias: { value: 0 },
+      tint: { value: new THREE.Color(0, 0, 0) },
+      tintAmt: { value: 0 },
+      backColor: { value: raw(o.back ?? "#223") },
+    },
+    transparent: true,
+    side: o.double ? THREE.DoubleSide : THREE.FrontSide,
+  }) as ImageMaterial;
+}
+
+// 둘레 바탕 — 위아래 그러데이션 + 한 점에 모인 빛. 큰 구 안쪽에 칠한다
+const SKY_FRAG = /* glsl */ `
+uniform vec3 top;
+uniform vec3 bottom;
+uniform vec3 glow;
+uniform vec3 glowDir;
+uniform float glowAmt;
+uniform float glowPow;
+varying vec3 vDir;
+void main() {
+  vec3 d = normalize(vDir);
+  vec3 c = mix(bottom, top, smoothstep(-0.6, 0.8, d.y));
+  float g = pow(max(dot(d, normalize(glowDir)), 0.0), glowPow);
+  c += glow * g * glowAmt;
+  gl_FragColor = vec4(c, 1.0);
+}`;
+
+const SKY_VERT = /* glsl */ `
+varying vec3 vDir;
+void main() {
+  vDir = position;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+
+export function sky(o: { top: string; bottom: string; glow: string; dir?: [number, number, number]; amt?: number; pow?: number; radius?: number }): THREE.Mesh<THREE.SphereGeometry, THREE.ShaderMaterial> {
+  const m = new THREE.Mesh(
+    new THREE.SphereGeometry(o.radius ?? 80, 48, 24),
+    new THREE.ShaderMaterial({
+      vertexShader: SKY_VERT,
+      fragmentShader: SKY_FRAG,
+      uniforms: {
+        top: { value: raw(o.top) },
+        bottom: { value: raw(o.bottom) },
+        glow: { value: raw(o.glow) },
+        glowDir: { value: new THREE.Vector3(...(o.dir ?? [0, 0, -1])) },
+        glowAmt: { value: o.amt ?? 0.6 },
+        glowPow: { value: o.pow ?? 6 },
+      },
+      side: THREE.BackSide,
+      depthWrite: false,
+    }),
+  );
+  m.renderOrder = -10;
+  return m;
+}
+
+/** 시드로 흩은 빛 점들 — 지나가는 속도감. 같은 시드면 같은 자리 */
+export function dust(positions: Float32Array, color: string, size: number): THREE.Points {
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+  const mat = new THREE.PointsMaterial({ color: raw(color), size, sizeAttenuation: true, transparent: true, opacity: 0.85, depthWrite: false, blending: THREE.AdditiveBlending });
+  return new THREE.Points(geo, mat);
+}
+
+const GRID_VERT = /* glsl */ `
+varying vec3 vPos;
+void main() {
+  vec4 wp = modelMatrix * vec4(position, 1.0);
+  vPos = wp.xyz;
+  gl_Position = projectionMatrix * viewMatrix * wp;
+}`;
+
+const GRID_FRAG = /* glsl */ `
+uniform vec3 color;
+uniform float focus;
+uniform float spread;
+varying vec3 vPos;
+void main() {
+  vec2 p = vPos.xz * 2.0;
+  vec2 w = fwidth(p);
+  vec2 l = abs(fract(p - 0.5) - 0.5) / max(w, 1e-4);
+  float line = 1.0 - min(min(l.x, l.y), 1.0);
+  float f = exp(-abs(vPos.z - focus) * 0.18) * smoothstep(spread, spread * 0.2, abs(vPos.x));
+  gl_FragColor = vec4(color * line * f * 0.8, 1.0);
+}`;
+
+/** 바닥·천장 빛 격자(더해 그린다) */
+export function gridPlane(o: { color: string; y: number; width: number; depth: number; z: number; focus: number }): THREE.Mesh {
+  const m = new THREE.Mesh(
+    new THREE.PlaneGeometry(o.width, o.depth),
+    new THREE.ShaderMaterial({
+      vertexShader: GRID_VERT,
+      fragmentShader: GRID_FRAG,
+      uniforms: { color: { value: raw(o.color) }, focus: { value: o.focus }, spread: { value: o.width * 0.45 } },
+      transparent: true,
+      blending: THREE.AdditiveBlending,
+      depthWrite: false,
+      side: THREE.DoubleSide,
+    }),
+  );
+  m.rotation.x = -Math.PI / 2;
+  m.position.set(0, o.y, o.z);
+  return m;
+}
+
+/** 판 테두리 고리(가운데가 빈 사각형) */
+export function frameRing(w: number, h: number, t: number): THREE.ShapeGeometry {
+  const s = new THREE.Shape();
+  s.moveTo(-w / 2 - t, -h / 2 - t);
+  s.lineTo(w / 2 + t, -h / 2 - t);
+  s.lineTo(w / 2 + t, h / 2 + t);
+  s.lineTo(-w / 2 - t, h / 2 + t);
+  s.lineTo(-w / 2 - t, -h / 2 - t);
+  const hole = new THREE.Path();
+  hole.moveTo(-w / 2, -h / 2);
+  hole.lineTo(-w / 2, h / 2);
+  hole.lineTo(w / 2, h / 2);
+  hole.lineTo(w / 2, -h / 2);
+  hole.lineTo(-w / 2, -h / 2);
+  s.holes.push(hole);
+  return new THREE.ShapeGeometry(s);
+}
+
+/** 씬 아래 모든 것을 놓아준다 */
+export function disposeTree(o: THREE.Object3D) {
+  o.traverse((x) => {
+    const m = x as THREE.Mesh;
+    m.geometry?.dispose();
+    const mats = Array.isArray(m.material) ? m.material : m.material ? [m.material] : [];
+    for (const mat of mats) mat.dispose();
+  });
+}
+
+/** 종류마다 받는 재료 */
+export interface Kit {
+  renderer: THREE.WebGLRenderer;
+  cam: THREE.PerspectiveCamera;
+  aspect: number;
+  w: number;
+  h: number;
+  seed: string;
+  pal: Palette;
+  from: Screen;
+  to: Screen;
+  /** 화면 모두(diveChain). 두 장면 전환이면 [from, to] */
+  screens: Screen[];
+}
+
+export interface KindRun {
+  /** u = 전환 진행도 0..1, t = 장면 안 초(지직거림 같은 결에만) */
+  frame(u: number, t: number): void;
+  dispose(): void;
+}