kasaframe 0.1.3 → 0.1.5

package/themes/water-works/effects.ts

@@ -0,0 +1,609 @@
+import { clamp, ease, rand, toEase, type EaseName, type SceneCtx } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+import { stage3d, textPlane, THREE, type Stage3D } from "@kasaframe/themes/stage3d";
+
+export type { SceneCtx };
+
+export type V3 = [number, number, number];
+type Rig = (t: number) => void;
+
+const color = (ctx: SceneCtx, k: string): THREE.Color => new THREE.Color(ctx.style.colors[k] ?? k);
+const css = (ctx: SceneCtx, k: string): string => ctx.style.colors[k] ?? k;
+// 기계 부품이 「텅」 하고 서는 한 손 — 살짝 넘쳤다 앉는다
+const pop = (t: number, at: number, dur = 0.3): number => (t < at ? 0 : ease.outBack(clamp((t - at) / dur)));
+const std = (c: THREE.Color, rough = 0.55, metal = 0): THREE.MeshStandardMaterial => new THREE.MeshStandardMaterial({ color: c, roughness: rough, metalness: metal });
+const shade = <T extends THREE.Object3D>(m: T, cast = true): T => {
+  m.castShadow = cast;
+  m.receiveShadow = true;
+  return m;
+};
+
+export interface HallKey {
+  t: number;
+  /** 보는 곳 */
+  look: V3;
+  /** 보는 곳에서 카메라까지 */
+  dist: number;
+  /** 왼쪽(음수)·오른쪽에서 보는 각(라디안). 기본 -0.16 */
+  yaw?: number;
+  /** 위에서 내려다보는 각. 기본 0.2 */
+  pitch?: number;
+  ease?: EaseName;
+}
+
+export interface HallShot {
+  from: number;
+  to: number;
+  /** 키 사이는 움직이고 키에서 선다 — 드러낼 것에 다가갈 때만 키를 둘 이상 둔다 */
+  keys: HallKey[];
+}
+
+function keyAt(t: number, keys: HallKey[]): Required<Omit<HallKey, "t" | "ease">> {
+  const ks = [...keys].sort((a, b) => a.t - b.t);
+  const v = (k: HallKey) => ({ look: k.look, dist: k.dist, yaw: k.yaw ?? -0.16, pitch: k.pitch ?? 0.2 });
+  if (t <= ks[0].t) return v(ks[0]);
+  for (let i = 1; i < ks.length; i++) {
+    if (t >= ks[i].t) continue;
+    const [a, b] = [v(ks[i - 1]), v(ks[i])];
+    const u = toEase(ks[i].ease ?? "inOutCubic")((t - ks[i - 1].t) / Math.max(1e-6, ks[i].t - ks[i - 1].t));
+    return { look: [0, 1, 2].map((j) => a.look[j] + (b.look[j] - a.look[j]) * u) as V3, dist: a.dist + (b.dist - a.dist) * u, yaw: a.yaw + (b.yaw - a.yaw) * u, pitch: a.pitch + (b.pitch - a.pitch) * u };
+  }
+  return v(ks[ks.length - 1]);
+}
+
+let tileTex: THREE.CanvasTexture | null = null;
+function tiles(ctx: SceneCtx): THREE.CanvasTexture {
+  if (tileTex) return tileTex;
+  const c = document.createElement("canvas");
+  c.width = c.height = 256;
+  const g = c.getContext("2d")!;
+  g.fillStyle = css(ctx, "bg");
+  g.fillRect(0, 0, 256, 256);
+  // 유약 타일 줄눈 — 한 장에 타일 넷
+  g.strokeStyle = css(ctx, "tile");
+  g.lineWidth = 6;
+  for (const p of [0, 128, 256]) {
+    g.beginPath();
+    g.moveTo(p, 0);
+    g.lineTo(p, 256);
+    g.moveTo(0, p);
+    g.lineTo(256, p);
+    g.stroke();
+  }
+  tileTex = new THREE.CanvasTexture(c);
+  tileTex.colorSpace = THREE.SRGBColorSpace;
+  tileTex.wrapS = tileTex.wrapT = THREE.RepeatWrapping;
+  return tileTex;
+}
+
+/**
+ * 펌프장 무대 — 청자 타일 벽 앞 관 선반을 정면 약간 위에서 본다(망원에 가까운 렌즈). 따뜻한 빛 한 방향, 그림자 하나.
+ * 컷마다 다른 선반(세트)을 보고, 카메라는 키를 둘 때만(드러낼 것에 다가가기) 움직인다
+ */
+export function pumpHall(el: HTMLElement, o: { ctx: SceneCtx; shots: HallShot[]; fov?: number; dado?: boolean }): ((t: number) => void) & Stage3D {
+  const { ctx } = o;
+  const shots = [...o.shots].sort((a, b) => a.from - b.from);
+  const shotAt = (t: number) => shots.find((x) => t >= x.from && t < x.to) ?? shots[shots.length - 1];
+  const stage = stage3d(el, {
+    ctx,
+    camera: "perspective",
+    fov: o.fov ?? 30,
+    env: true,
+    exposure: 0.92,
+    shot(t, cam) {
+      const k = keyAt(t, shotAt(t).keys);
+      const look = new THREE.Vector3(...k.look);
+      const dir = new THREE.Vector3(Math.sin(k.yaw) * Math.cos(k.pitch), Math.sin(k.pitch), Math.cos(k.yaw) * Math.cos(k.pitch));
+      cam.position.copy(look).addScaledVector(dir, k.dist);
+      cam.lookAt(look);
+    },
+  });
+  const { scene } = stage;
+  const span = 400;
+  const wallTex = tiles(ctx).clone();
+  wallTex.needsUpdate = true;
+  wallTex.repeat.set(span / 1.6, 30 / 1.6);
+  const wall = shade(new THREE.Mesh(new THREE.PlaneGeometry(span, 30), new THREE.MeshStandardMaterial({ map: wallTex, roughness: 0.45 })), false);
+  wall.position.set(span / 2 - 30, 8, -1.8);
+  scene.add(wall);
+  // 허리 띠 — 짙은 초록 줄 하나가 벽을 가로지른다
+  const dado = shade(new THREE.Mesh(new THREE.BoxGeometry(span, 0.16, 0.06), std(color(ctx, "pipeDeep"), 0.6)), false);
+  dado.position.set(span / 2 - 30, -1.35, -1.76);
+  if (o.dado !== false) scene.add(dado);
+  const floor = shade(new THREE.Mesh(new THREE.PlaneGeometry(span, 30), std(color(ctx, "floor"), 0.9)), false);
+  floor.rotation.x = -Math.PI / 2;
+  floor.position.set(span / 2 - 30, -3.2, 10);
+  scene.add(floor);
+  scene.add(new THREE.HemisphereLight(0xfff6e8, color(ctx, "floor"), 1.0));
+  const sun = new THREE.DirectionalLight(0xffe2b8, 2.2);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(1024, 1024);
+  Object.assign(sun.shadow.camera as THREE.OrthographicCamera, { left: -14, right: 14, top: 12, bottom: -12, near: 1, far: 60 });
+  sun.shadow.bias = -0.0006;
+  scene.add(sun, sun.target);
+  const follow = (t: number) => {
+    const [x, y, z] = shotAt(t).keys[0].look;
+    sun.position.set(x - 7, y + 12, z + 12);
+    sun.target.position.set(x, y, z);
+    sun.target.updateMatrixWorld();
+    (sun.shadow.camera as THREE.OrthographicCamera).updateProjectionMatrix();
+  };
+  return Object.assign((t: number) => {
+    follow(t);
+    stage.paint(t);
+  }, stage);
+}
+
+// 직각으로 꺾이는 관 길 — 모서리는 반지름 bend 의 엘보로 굽힌다
+function pipeCurve(points: V3[], bend: number): THREE.CurvePath<THREE.Vector3> {
+  const P = points.map((p) => new THREE.Vector3(...p));
+  const path = new THREE.CurvePath<THREE.Vector3>();
+  let start = P[0].clone();
+  for (let i = 1; i < P.length; i++) {
+    const a = P[i];
+    if (i < P.length - 1) {
+      const din = a.clone().sub(P[i - 1]).normalize();
+      const dout = P[i + 1].clone().sub(a).normalize();
+      const r = Math.min(bend, a.distanceTo(P[i - 1]) / 2, a.distanceTo(P[i + 1]) / 2);
+      const p1 = a.clone().addScaledVector(din, -r);
+      const p2 = a.clone().addScaledVector(dout, r);
+      path.add(new THREE.LineCurve3(start, p1));
+      path.add(new THREE.QuadraticBezierCurve3(p1, a.clone(), p2));
+      start = p2;
+    } else path.add(new THREE.LineCurve3(start, a.clone()));
+  }
+  return path;
+}
+
+let flowTex: THREE.CanvasTexture | null = null;
+// 관 속 물 — 늘 차 있는 옅은 물에 밝은 물덩이가 줄지어 있다(한 바퀴 = 덩이 하나)
+function flowTexture(ctx: SceneCtx): THREE.CanvasTexture {
+  if (flowTex) return flowTex;
+  const c = document.createElement("canvas");
+  c.width = 128;
+  c.height = 8;
+  const g = c.getContext("2d")!;
+  const grad = g.createLinearGradient(0, 0, 128, 0);
+  const w = css(ctx, "water");
+  grad.addColorStop(0, w);
+  grad.addColorStop(0.35, "#ffffff");
+  grad.addColorStop(0.55, w);
+  grad.addColorStop(1, w);
+  g.fillStyle = grad;
+  g.fillRect(0, 0, 128, 8);
+  flowTex = new THREE.CanvasTexture(c);
+  flowTex.colorSpace = THREE.SRGBColorSpace;
+  flowTex.wrapS = THREE.RepeatWrapping;
+  return flowTex;
+}
+
+/** 흐른 거리 — 빠르기가 시각마다 바뀌어도(밸브) 같은 t 면 같은 값. 1/60초 마다 더한다 */
+function travelled(flow: number | ((t: number) => number), t: number): number {
+  if (t <= 0) return 0;
+  if (typeof flow === "number") return flow * t;
+  let s = 0;
+  const dt = 1 / 60;
+  for (let u = 0; u < t; u += dt) s += flow(u) * Math.min(dt, t - u);
+  return s;
+}
+
+export interface PipeOpts {
+  ctx: SceneCtx;
+  /** 관이 지나는 점 — 직각으로 꺾으면 엘보가 붙는다 */
+  points: V3[];
+  /** 관 반지름 = 한도. 기본 0.26 */
+  r?: number;
+  /** 관 색(colors 키). 기본 pipe */
+  color?: string;
+  /** 관을 놓는 시각 — 앞에서부터 이어진다. 없으면 처음부터 있다 */
+  at?: number;
+  dur?: number;
+  /** 물 빠르기(단위/초) = 처리량. 함수면 시각마다(밸브가 바꾼다). 0 이면 고인 물 */
+  flow?: number | ((t: number) => number);
+  /** 물덩이 사이(단위). 기본 1.1 */
+  gap?: number;
+  /** 물머리가 들어오는 시각 — 물이 관을 따라 앞으로 나아간다(지연). 없으면 처음부터 차 있다 */
+  fillAt?: number;
+  fillSpeed?: number;
+  /** 관에 찬 물 몫(0..1, 들머리부터) — 주면 fillAt 대신. 밸브가 열린 갈래만 물이 차오른다 */
+  fill?: (t: number) => number;
+  /** 엘보 반지름. 기본 r × 2.4 */
+  bend?: number;
+}
+
+/**
+ * 관 = 요청이 지나는 길. 초록이 비치는 투명 관 속을 물덩이가 같은 빠르기로 줄지어 간다(유량 = 처리량), 관 굵기 = 한도.
+ * at 에 관이 앞에서부터 이어지고, fillAt 에 물머리가 관을 따라 나아간다(끝에 닿는 시간 = 지연)
+ */
+export function pipeRun(stage: Stage3D, o: PipeOpts): Rig {
+  const { ctx } = o;
+  const r = o.r ?? 0.26;
+  const curve = pipeCurve(o.points, o.bend ?? r * 2.4);
+  const len = curve.getLength();
+  const tub = Math.max(8, Math.ceil(len * 10));
+  const radial = 16;
+  const shellMat = new THREE.MeshStandardMaterial({ color: color(ctx, o.color ?? "pipe"), roughness: 0.18, metalness: 0, transparent: true, opacity: 0.42, depthWrite: false });
+  const shell = new THREE.Mesh(new THREE.TubeGeometry(curve, tub, r, radial, false), shellMat);
+  shell.renderOrder = 2;
+  const tex = flowTexture(ctx).clone();
+  tex.needsUpdate = true;
+  const gap = o.gap ?? 1.1;
+  tex.repeat.set(len / gap, 1);
+  const core = new THREE.Mesh(new THREE.TubeGeometry(curve, tub, r * 0.66, 12, false), new THREE.MeshBasicMaterial({ map: tex, toneMapped: false }));
+  core.renderOrder = 1;
+  stage.scene.add(core, shell);
+  // 이음 테 — 꺾이는 곳과 두 끝에 넓은 플랜지(불투명 페인트)
+  const collarGeo = new THREE.CylinderGeometry(r * 1.38, r * 1.38, r * 0.55, 20);
+  const collarMat = std(color(ctx, o.color ?? "pipe"), 0.5, 0.1);
+  const stops: number[] = [0];
+  let acc = 0;
+  for (const c of curve.curves) {
+    acc += c.getLength();
+    stops.push(acc / len);
+  }
+  const collars = [...new Set(stops.map((s) => Math.round(s * 1000) / 1000))].map((u) => {
+    const m = shade(new THREE.Mesh(collarGeo, collarMat));
+    const p = curve.getPointAt(clamp(u));
+    const tan = curve.getTangentAt(clamp(u));
+    m.position.copy(p);
+    m.quaternion.setFromUnitVectors(new THREE.Vector3(0, 1, 0), tan);
+    stage.scene.add(m);
+    return { m, u };
+  });
+  const shellCount = (shell.geometry.index?.count ?? 0) / tub;
+  const coreCount = (core.geometry.index?.count ?? 0) / tub;
+  return (t) => {
+    const lay = o.at === undefined ? 1 : clamp((t - o.at) / (o.dur ?? Math.max(0.2, len / 14)));
+    const fill = o.fill ? clamp(o.fill(t)) : o.fillAt === undefined ? 1 : clamp(((t - o.fillAt) * (o.fillSpeed ?? 8)) / len);
+    const n = Math.ceil(lay * tub);
+    shell.visible = n > 0;
+    shell.geometry.setDrawRange(0, n * shellCount);
+    const m = Math.min(n, Math.ceil(fill * tub));
+    core.visible = m > 0;
+    core.geometry.setDrawRange(0, m * coreCount);
+    for (const c of collars) c.m.visible = lay >= c.u - 1e-3 && lay > 0;
+    // 물은 관 끝 쪽으로 — 텍스처를 거슬러 민다
+    tex.offset.x = -travelled(o.flow ?? 2.4, t) / gap;
+  };
+}
+
+/**
+ * 밸브 — 관 위에 선 빨간 바퀴. open(t) 이 0..1(닫힘..열림)이고 바퀴가 그만큼 돌며 줄기가 올라온다.
+ * 모델 고르기는 그 갈래 밸브를 열고 나머지를 닫는 것, 값 줄이기는 조이는 것
+ */
+export function valve(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; size?: number; at?: number; open: (t: number) => number; axis?: "x" | "z"; vertical?: boolean }): Rig {
+  const { ctx } = o;
+  const s = o.size ?? 1;
+  const g = new THREE.Group();
+  g.position.set(...o.pos);
+  // 세로관이면 바퀴가 보는 쪽을 향하게 눕힌다 — 관 방향(로컬 z)이 위아래가 된다
+  const axis = o.vertical ? "z" : o.axis;
+  if (o.vertical) g.rotation.x = Math.PI / 2;
+  const pipeMat = std(color(ctx, "pipe"), 0.45, 0.1);
+  const body = shade(new THREE.Mesh(new THREE.SphereGeometry(0.42 * s, 20, 14), pipeMat));
+  g.add(body);
+  for (const side of [-1, 1]) {
+    const fl = shade(new THREE.Mesh(new THREE.CylinderGeometry(0.4 * s, 0.4 * s, 0.14 * s, 20), pipeMat));
+    fl.rotation.z = axis === "z" ? 0 : Math.PI / 2;
+    if (axis === "z") fl.rotation.x = Math.PI / 2;
+    fl.position.set(axis === "z" ? 0 : side * 0.44 * s, 0, axis === "z" ? side * 0.44 * s : 0);
+    g.add(fl);
+  }
+  const steel = std(color(ctx, "steel"), 0.25, 0.85);
+  const bonnet = shade(new THREE.Mesh(new THREE.CylinderGeometry(0.17 * s, 0.22 * s, 0.4 * s, 16), pipeMat));
+  bonnet.position.y = 0.5 * s;
+  g.add(bonnet);
+  const stem = shade(new THREE.Mesh(new THREE.CylinderGeometry(0.05 * s, 0.05 * s, 0.6 * s, 10), steel));
+  stem.position.y = 0.8 * s;
+  g.add(stem);
+  const wheel = new THREE.Group();
+  const red = std(color(ctx, "accent"), 0.4, 0.05);
+  wheel.add(shade(new THREE.Mesh(new THREE.TorusGeometry(0.42 * s, 0.055 * s, 10, 36), red)));
+  for (let k = 0; k < 4; k++) {
+    const spoke = shade(new THREE.Mesh(new THREE.BoxGeometry(0.84 * s, 0.05 * s, 0.05 * s), red));
+    spoke.rotation.z = (k * Math.PI) / 4;
+    wheel.add(spoke);
+  }
+  wheel.add(shade(new THREE.Mesh(new THREE.CylinderGeometry(0.09 * s, 0.09 * s, 0.1 * s, 12).rotateX(Math.PI / 2), red)));
+  wheel.rotation.x = -Math.PI / 2;
+  const wheelHolder = new THREE.Group();
+  wheelHolder.add(wheel);
+  g.add(wheelHolder);
+  stage.scene.add(g);
+  return (t) => {
+    const k = o.at === undefined ? 1 : pop(t, o.at);
+    g.visible = k > 0;
+    g.scale.setScalar(Math.max(1e-3, k));
+    const op = clamp(o.open(t));
+    wheelHolder.position.y = (1.05 + 0.18 * op) * s;
+    wheelHolder.rotation.y = -op * Math.PI * 3;
+  };
+}
+
+function dialTexture(ctx: SceneCtx, o: { ticks: string[]; band?: [number, number]; sweep: number; unit?: string }): THREE.CanvasTexture {
+  const S = 512;
+  const c = document.createElement("canvas");
+  c.width = c.height = S;
+  const g = c.getContext("2d")!;
+  const cx = S / 2;
+  g.fillStyle = css(ctx, "dial");
+  g.beginPath();
+  g.arc(cx, cx, S / 2, 0, Math.PI * 2);
+  g.fill();
+  // 한 바퀴 계기(하루 시계)는 0 이 맨 위, 나머지는 아래가 비게 가운데를 위로
+  const base = o.sweep >= 360 ? 0 : 0.5;
+  const at = (u: number) => ((-90 + (u - base) * o.sweep) * Math.PI) / 180;
+  if (o.band) {
+    g.strokeStyle = css(ctx, "success");
+    g.lineWidth = 34;
+    g.beginPath();
+    g.arc(cx, cx, S * 0.39, at(o.band[0]), at(o.band[1]));
+    g.stroke();
+  }
+  const n = o.ticks.length - 1;
+  g.strokeStyle = css(ctx, "ink");
+  for (let i = 0; i <= n * 5; i++) {
+    const a = at(i / (n * 5));
+    const major = i % 5 === 0;
+    g.lineWidth = major ? 7 : 3;
+    g.beginPath();
+    g.moveTo(cx + Math.cos(a) * S * 0.46, cx + Math.sin(a) * S * 0.46);
+    g.lineTo(cx + Math.cos(a) * S * (major ? 0.36 : 0.41), cx + Math.sin(a) * S * (major ? 0.36 : 0.41));
+    g.stroke();
+  }
+  g.fillStyle = css(ctx, "ink");
+  g.textAlign = "center";
+  g.textBaseline = "middle";
+  const fs = Math.round(S * (o.ticks.some((x) => x.length > 3) ? 0.065 : 0.085));
+  g.font = `700 ${fs}px ${ctx.style.fonts.mono}`;
+  o.ticks.forEach((tx, i) => {
+    const a = at(i / n);
+    g.fillText(tx, cx + Math.cos(a) * S * 0.27, cx + Math.sin(a) * S * 0.27);
+  });
+  if (o.unit) {
+    g.font = `800 ${Math.round(S * 0.075)}px ${ctx.style.fonts.display}`;
+    g.fillText(o.unit, cx, cx + S * (o.sweep >= 360 ? 0.13 : 0.25));
+  }
+  const tex = new THREE.CanvasTexture(c);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  return tex;
+}
+
+/**
+ * 수압계 — 놋쇠 테 안 미색 눈금판, 빨간 바늘이 value(t)(0..1) 로 가서 한 번 넘쳤다 선다. 초록 띠(band)가 좋은 구간.
+ * sweep 360 이면 하루 시계(바늘이 시간을 돈다)
+ */
+export function gauge(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; size?: number; at?: number; value: (t: number) => number; ticks?: string[]; band?: [number, number]; unit?: string; sweep?: number; stem?: number }): Rig {
+  const { ctx } = o;
+  const s = o.size ?? 1;
+  const sweep = o.sweep ?? 270;
+  const g = new THREE.Group();
+  g.position.set(...o.pos);
+  const brass = std(color(ctx, "brass"), 0.3, 0.8);
+  const rim = shade(new THREE.Mesh(new THREE.TorusGeometry(s, 0.09 * s, 12, 48), brass));
+  g.add(rim);
+  const back = shade(new THREE.Mesh(new THREE.CylinderGeometry(s, s, 0.22 * s, 40).rotateX(Math.PI / 2), brass));
+  back.position.z = -0.12 * s;
+  g.add(back);
+  const face = new THREE.Mesh(new THREE.CircleGeometry(s * 0.98, 48), new THREE.MeshStandardMaterial({ map: dialTexture(ctx, { ticks: o.ticks ?? ["0", "1", "2", "3", "4"], band: o.band, sweep, unit: o.unit }), roughness: 0.6 }));
+  face.position.z = 0.005;
+  g.add(face);
+  const needle = new THREE.Group();
+  const red = std(color(ctx, "accent"), 0.4, 0.05);
+  const blade = shade(new THREE.Mesh(new THREE.BoxGeometry(0.06 * s, 0.86 * s, 0.03 * s), red));
+  blade.position.y = 0.3 * s;
+  needle.add(blade, shade(new THREE.Mesh(new THREE.CylinderGeometry(0.1 * s, 0.1 * s, 0.06 * s, 16).rotateX(Math.PI / 2), red)));
+  needle.position.z = 0.06 * s;
+  g.add(needle);
+  if (o.stem) {
+    const st = shade(new THREE.Mesh(new THREE.CylinderGeometry(0.1 * s, 0.1 * s, o.stem, 12), brass));
+    st.position.y = -s - o.stem / 2;
+    g.add(st);
+  }
+  stage.scene.add(g);
+  return (t) => {
+    const k = o.at === undefined ? 1 : pop(t, o.at);
+    g.visible = k > 0;
+    g.scale.setScalar(Math.max(1e-3, k));
+    const v = o.value(t);
+    needle.rotation.z = -((v - (sweep >= 360 ? 0 : 0.5)) * sweep * Math.PI) / 180;
+  };
+}
+
+/** 바늘이 값으로 가서 한 번 넘쳤다 서는 곡선 — gauge 의 value 에 쓴다 */
+export function needle(t: number, o: { at: number; from?: number; to: number; dur?: number }): number {
+  const from = o.from ?? 0;
+  if (t <= o.at) return from;
+  return from + (o.to - from) * ease.outBack(clamp((t - o.at) / (o.dur ?? 0.45)));
+}
+
+/**
+ * 탱크 = 공급자. 강철 테 두른 투명 통 속 수위가 level(t)(0..1) 로 차오른다 — 수위가 그 회사의 값(모델 수)
+ */
+export function tank(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; r?: number; h?: number; at?: number; level: (t: number) => number }): Rig {
+  const { ctx } = o;
+  const r = o.r ?? 0.7;
+  const h = o.h ?? 3;
+  const g = new THREE.Group();
+  g.position.set(...o.pos);
+  const steel = std(color(ctx, "steel"), 0.22, 0.85);
+  const glass = new THREE.Mesh(new THREE.CylinderGeometry(r, r, h, 32, 1, true), new THREE.MeshStandardMaterial({ color: color(ctx, "surface"), roughness: 0.1, transparent: true, opacity: 0.28, depthWrite: false, side: THREE.DoubleSide }));
+  glass.position.y = h / 2;
+  glass.renderOrder = 2;
+  const water = new THREE.Mesh(new THREE.CylinderGeometry(r * 0.94, r * 0.94, 1, 32), new THREE.MeshStandardMaterial({ color: color(ctx, "water"), roughness: 0.15, transparent: true, opacity: 0.88 }));
+  water.renderOrder = 1;
+  g.add(water, glass);
+  for (const y of [0, h]) {
+    const band = shade(new THREE.Mesh(new THREE.CylinderGeometry(r * 1.06, r * 1.06, 0.16, 32), steel));
+    band.position.y = y;
+    g.add(band);
+  }
+  const cap = shade(new THREE.Mesh(new THREE.SphereGeometry(r * 1.02, 28, 12, 0, Math.PI * 2, 0, Math.PI / 2), steel));
+  cap.scale.y = 0.45;
+  cap.position.y = h;
+  g.add(cap);
+  const base = shade(new THREE.Mesh(new THREE.CylinderGeometry(r * 1.15, r * 1.25, 0.3, 32), std(color(ctx, "brass"), 0.35, 0.7)));
+  base.position.y = -0.15;
+  g.add(base);
+  stage.scene.add(g);
+  return (t) => {
+    const k = o.at === undefined ? 1 : pop(t, o.at, 0.34);
+    g.visible = k > 0;
+    g.scale.set(Math.max(1e-3, Math.min(1, k)), Math.max(1e-3, k), Math.max(1e-3, Math.min(1, k)));
+    const lv = Math.max(0.002, clamp(o.level(t)) * (h - 0.1));
+    water.scale.y = lv;
+    water.position.y = lv / 2 + 0.05;
+  };
+}
+
+export interface PlateOpts {
+  ctx: SceneCtx;
+  text: string | ((t: number) => string);
+  pos: V3;
+  /** 글 한 줄 높이(세계 단위) */
+  height: number;
+  at?: number;
+  until?: number;
+  font?: "display" | "sans" | "mono";
+  /** plate 미색 이름판 · brass 놋쇠판 · counter 검은 계수기(흰 숫자) */
+  look?: "plate" | "brass" | "counter";
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * 이름판·계수기 — 판에 굵은 글자, at 에 아래에서 「텅」 하고 선다. 글이 바뀌면 판이 한 번 넘어가며(넘김판) 새 글이 선다
+ */
+export function nameplate(stage: Stage3D, o: PlateOpts): Rig {
+  const { ctx } = o;
+  const look = o.look ?? "plate";
+  const plate = look === "counter" ? css(ctx, "ink") : look === "brass" ? css(ctx, "brass") : css(ctx, "surface");
+  const ink = look === "counter" ? css(ctx, "surface") : css(ctx, "ink");
+  const holder = new THREE.Group();
+  holder.position.set(...o.pos);
+  stage.scene.add(holder);
+  const meshes = new Map<string, THREE.Mesh>();
+  const make = (text: string) => {
+    let m = meshes.get(text);
+    if (!m) {
+      const f = o.font ?? "display";
+      m = textPlane({ text, family: ctx.style.fonts[f], weight: f === "display" ? 850 : 700, color: ink, height: o.height, plate, pad: 40, align: o.align });
+      (m.material as THREE.MeshBasicMaterial).transparent = false;
+      (m.material as THREE.MeshBasicMaterial).depthWrite = true;
+      shade(m, true);
+      m.visible = false;
+      holder.add(m);
+      meshes.set(text, m);
+    }
+    return m;
+  };
+  const textAt = typeof o.text === "function" ? o.text : () => o.text as string;
+  make(textAt(0));
+  return (t) => {
+    const on = (o.at === undefined || t >= o.at) && (o.until === undefined || t < o.until);
+    const now = textAt(t);
+    for (const [k, m] of meshes) m.visible = on && k === now;
+    if (!on) return;
+    const m = make(now);
+    m.visible = true;
+    const k = o.at === undefined ? 1 : pop(t, o.at);
+    // 글이 막 바뀌었으면 넘김판처럼 한 번 넘어온다
+    let flip = 0;
+    for (let d = 1 / 60; d < 0.14; d += 1 / 60)
+      if (textAt(t - d) !== now) {
+        flip = 1 - d / 0.14;
+        break;
+      }
+    holder.scale.set(1, Math.max(1e-3, k), 1);
+    holder.rotation.x = -flip * Math.PI * 0.5;
+  };
+}
+
+/**
+ * 드롭 — 밸브가 한꺼번에 열려 수압이 터진다: 물보라 알갱이가 사방으로 튀고 파문 고리 셋이 벽을 따라 번진다.
+ * 흔들림·한 번 튐을 돌려준다(shake 는 무대 DOM 에, punch 는 주인공에)
+ */
+export function surge(stage: Stage3D, o: { ctx: SceneCtx; drop?: number; pos: V3; count?: number; seed?: string | number }): (t: number) => DropBurstState {
+  const { ctx } = o;
+  const at = ctx.beats.drop(o.drop ?? 0);
+  const n = o.count ?? 60;
+  const seed = o.seed ?? `${ctx.id}:surge`;
+  const drops = new THREE.InstancedMesh(new THREE.SphereGeometry(0.09, 8, 6), new THREE.MeshStandardMaterial({ color: color(ctx, "water"), roughness: 0.1 }), n);
+  drops.castShadow = true;
+  stage.scene.add(drops);
+  const vel = Array.from({ length: n }, (_, i) => {
+    const a = rand(seed, i) * Math.PI * 2;
+    const sp = 4 + rand(seed, i + 100) * 6;
+    return new THREE.Vector3(Math.cos(a) * sp, Math.abs(Math.sin(a)) * sp * 0.9 + 2, 1.5 + rand(seed, i + 200) * 3);
+  });
+  const rings = [0, 1, 2].map(() => {
+    const m = new THREE.Mesh(new THREE.TorusGeometry(1, 0.05, 8, 64), new THREE.MeshBasicMaterial({ color: color(ctx, "water"), transparent: true, depthWrite: false, toneMapped: false }));
+    m.position.set(...o.pos);
+    m.position.z += 0.05;
+    stage.scene.add(m);
+    return m;
+  });
+  const m4 = new THREE.Matrix4();
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "surge" });
+    const k = t - at;
+    const live = k >= 0 && k < 1.1;
+    drops.visible = live;
+    if (live) {
+      vel.forEach((v, i) => {
+        const p = new THREE.Vector3(o.pos[0] + v.x * k, o.pos[1] + v.y * k - 4.9 * k * k, o.pos[2] + v.z * k);
+        const sc = Math.max(0.01, 1 - k / 1.1);
+        m4.makeScale(sc, sc, sc).setPosition(p);
+        drops.setMatrixAt(i, m4);
+      });
+      drops.instanceMatrix.needsUpdate = true;
+    }
+    rings.forEach((m, j) => {
+      const p = clamp((k - j * 0.1) / 0.7);
+      m.visible = k >= j * 0.1 && p < 1;
+      if (!m.visible) return;
+      m.scale.setScalar(0.3 + ease.outCubic(p) * 9);
+      (m.material as THREE.MeshBasicMaterial).opacity = 1 - p;
+    });
+    return s;
+  };
+}
+
+/**
+ * 끝 카드 — 놋쇠 테·모서리 나사의 미색 이름판(DOM, 검사가 읽는다). 아래에서 「텅」 하고 서고, 로고 → 제목 → 주소 차례로 박힌다
+ */
+export function brassCard(el: HTMLElement, o: { ctx: SceneCtx; rect: { x: number; y: number; w: number; h: number }; logo?: string; title: string; sub?: string; at: number; subAt?: number }): (t: number) => void {
+  const { ctx, rect: r } = o;
+  const doc = el.ownerDocument;
+  const card = doc.createElement("div");
+  card.style.cssText = `position:absolute;left:${r.x}px;top:${r.y}px;width:${r.w}px;height:${r.h}px;box-sizing:border-box;border-radius:14px;background:${css(ctx, "surface")};border:10px solid ${css(ctx, "brass")};box-shadow:0 14px 0 rgba(28, 37, 34, 0.25);transform-origin:50% 100%;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:26px`;
+  for (const [x, y] of [[14, 14], [r.w - 46, 14], [14, r.h - 46], [r.w - 46, r.h - 46]]) {
+    const s = doc.createElement("div");
+    s.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:12px;height:12px;border-radius:50%;background:${css(ctx, "brass")}`;
+    card.append(s);
+  }
+  const logo = doc.createElement("div");
+  logo.style.cssText = `width:${Math.round(r.w * 0.36)}px;color:${css(ctx, "pipe")}`;
+  if (o.logo) logo.innerHTML = o.logo.replace(/ width="\d+" height="\d+"/, ' width="100%" style="display:block"');
+  const title = doc.createElement("div");
+  title.style.cssText = `font:850 ${Math.round(r.h * 0.17)}px ${ctx.style.fonts.display};letter-spacing:-0.02em;color:${css(ctx, "ink")};white-space:pre;line-height:1`;
+  const sub = doc.createElement("div");
+  sub.style.cssText = `font:700 ${Math.round(r.h * 0.065)}px ${ctx.style.fonts.mono};color:${css(ctx, "accentText")};white-space:pre;line-height:1`;
+  card.append(logo, title, sub);
+  el.append(card);
+  const type = (node: HTMLElement, text: string, at: number) => {
+    const n = Math.max(0, Math.min(text.length, Math.floor((at < 0 ? 0 : at) / 0.022) + (at >= 0 ? 1 : 0)));
+    node.textContent = text.slice(0, n);
+    node.style.visibility = at >= 0 ? "visible" : "hidden";
+  };
+  return (t) => {
+    const k = t - o.at;
+    card.style.display = k < 0 ? "none" : "flex";
+    if (k < 0) return;
+    card.style.transform = `scaleY(${ease.outBack(clamp(k / 0.3)).toFixed(4)})`;
+    logo.style.visibility = k >= 0.1 ? "visible" : "hidden";
+    logo.style.transform = k >= 0.1 ? `scale(${ease.outBack(clamp((k - 0.1) / 0.3)).toFixed(4)})` : "";
+    type(title, o.title, k - 0.3);
+    type(sub, o.sub ?? "", t - (o.subAt ?? o.at + 0.8));
+  };
+}

package/themes/water-works/sample/assets/og/logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1140 650" width="1140" height="650" fill="none" role="img" aria-label="OpenGateway">
+  <title>OpenGateway</title>
+  <g id="logo" stroke="currentColor" fill="currentColor">
+    <rect id="node-in" x="36" y="36" width="420" height="578" rx="89" fill="none" stroke-width="72"/>
+    <rect id="bar-in" x="72" y="272" width="277" height="106" stroke="none"/>
+    <path id="node-out" d="M684 213 L684 125 A89 89 0 0 1 773 36 L1015 36 A89 89 0 0 1 1104 125 L1104 525 A89 89 0 0 1 1015 614 L773 614 A89 89 0 0 1 684 525 L684 436" fill="none" stroke-width="72" stroke-linecap="butt"/>
+    <g id="arrow">
+      <rect id="arrow-shaft" x="420" y="272" width="394" height="106" stroke="none"/>
+      <path id="arrow-head" d="M833 220 L970 325 L833 430 Z" stroke-width="38" stroke-linejoin="round"/>
+    </g>
+  </g>
+</svg>