kasaframe 0.1.1 → 0.1.4

package/themes/orbit-system/effects.ts

@@ -0,0 +1,665 @@
+import { clamp, ease, rand, toEase, type EaseName, type SceneCtx } from "@kasaframe/core";
+import { dropBurst } from "@kasaframe/motion";
+import { stage3d, THREE, type Stage3D } from "@kasaframe/themes/stage3d";
+
+type V3 = [number, number, number];
+/** 천체 자리 — 서 있는 점이거나 시각의 함수(행성의 where). 위성·전이 궤도·글자판이 움직이는 행성을 따라간다 */
+export type Where = V3 | THREE.Vector3 | ((t: number) => THREE.Vector3);
+type Font = "display" | "sans" | "mono";
+
+const TAU = Math.PI * 2;
+const X = new THREE.Vector3(1, 0, 0);
+const Y = new THREE.Vector3(0, 1, 0);
+const at3 = (w: Where, t: number): THREE.Vector3 => (typeof w === "function" ? w(t) : w instanceof THREE.Vector3 ? w.clone() : new THREE.Vector3(...w));
+const hex = (ctx: SceneCtx, k: string): string => ctx.style.colors[k] ?? k;
+const color = (ctx: SceneCtx, k: string) => new THREE.Color(hex(ctx, k));
+const pop = (t: number, at: number, dur = 0.36) => (t < at ? 0 : ease.outBack(clamp((t - at) / dur)));
+const settle = (t: number, at: number, dur = 0.4) => (t < at ? 0 : ease.outCubic(clamp((t - at) / dur)));
+// 캔버스에 칠할 색 — 변주 생성기가 어떤 꼴의 색을 넣어도 rgba 로 바꾼다
+const rgba = (c: string, a: number) => {
+  const h = new THREE.Color(c).getHex();
+  return `rgba(${(h >> 16) & 255},${(h >> 8) & 255},${h & 255},${a})`;
+};
+
+const glowCache = new Map<string, THREE.Texture>();
+function glowTexture(c: string): THREE.Texture {
+  const hit = glowCache.get(c);
+  if (hit) return hit;
+  const s = 128;
+  const cv = document.createElement("canvas");
+  cv.width = cv.height = s;
+  const g = cv.getContext("2d")!;
+  const grad = g.createRadialGradient(s / 2, s / 2, 0, s / 2, s / 2, s / 2);
+  grad.addColorStop(0, rgba(c, 1));
+  grad.addColorStop(0.18, rgba(c, 0.55));
+  grad.addColorStop(0.5, rgba(c, 0.12));
+  grad.addColorStop(1, rgba(c, 0));
+  g.fillStyle = grad;
+  g.fillRect(0, 0, s, s);
+  const tex = new THREE.CanvasTexture(cv);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  glowCache.set(c, tex);
+  return tex;
+}
+
+const glowSprite = (ctx: SceneCtx, tone: string) =>
+  new THREE.Sprite(new THREE.SpriteMaterial({ map: glowTexture(hex(ctx, tone)), blending: THREE.AdditiveBlending, transparent: true, depthWrite: false, toneMapped: false }));
+
+export interface CamKey {
+  t: number;
+  pos: V3;
+  look: V3;
+  /** 앞 키에서 이 키로 오는 이징 — 박에 떠나 박에 내려앉는다. 기본 inOutCubic */
+  ease?: EaseName;
+}
+
+export interface Shot {
+  from: number;
+  to: number;
+  /** 키 사이는 움직이고 키에서 선다. 쉬지 않는 몫은 도는 행성·위성이 진다 */
+  keys: CamKey[];
+}
+
+const mix3 = (a: V3, b: V3, u: number): V3 => [a[0] + (b[0] - a[0]) * u, a[1] + (b[1] - a[1]) * u, a[2] + (b[2] - a[2]) * u];
+function camAt(t: number, keys: CamKey[]): { pos: V3; look: V3 } {
+  const ks = [...keys].sort((a, b) => a.t - b.t);
+  if (t <= ks[0].t) return ks[0];
+  for (let i = 1; i < ks.length; i++) {
+    if (t >= ks[i].t) continue;
+    const [a, b] = [ks[i - 1], ks[i]];
+    const u = toEase(b.ease ?? "inOutCubic")((t - a.t) / Math.max(1e-6, b.t - a.t));
+    return { pos: mix3(a.pos, b.pos, u), look: mix3(a.look, b.look, u) };
+  }
+  return ks[ks.length - 1];
+}
+
+/** 궤도 무대 — 짙은 우주, 서 있는 별 점, 밤 반구를 남색으로 살리는 옅은 환경광. 카메라는 궤도면을 비스듬히 내려다보고 박에 맞춘 키로만 움직인다 */
+export function orbitStage(el: HTMLElement, o: { ctx: SceneCtx; shots: Shot[]; fov?: number; key?: number; seed?: string }): ((t: number) => void) & Stage3D {
+  const { ctx } = o;
+  const shots = [...o.shots].sort((a, b) => a.from - b.from);
+  const stage = stage3d(el, {
+    ctx,
+    fov: o.fov ?? 40,
+    exposure: 1.1,
+    shot(t, cam) {
+      const s = shots.find((x) => t >= x.from && t < x.to) ?? shots[shots.length - 1];
+      const p = camAt(t, s.keys);
+      cam.position.set(...p.pos);
+      cam.lookAt(...p.look);
+    },
+  });
+  stage.scene.add(stage.camera);
+  // 밤 반구가 새까만 구멍이 아니라 남색 공으로 읽히게 — 위·아래 다 밤빛
+  stage.scene.add(new THREE.HemisphereLight(color(ctx, "night"), color(ctx, "night"), 4.6));
+  // 먼 별빛 — 게이트웨이 별이 아직 없는 세트(흩어진 행성)만 쓴다. 별이 있으면 0 으로 두어 밤 반구가 별 반대쪽에 진다
+  if (o.key) {
+    const far = new THREE.DirectionalLight(0xfff1dc, o.key);
+    far.position.set(-10, 8, 6);
+    stage.scene.add(far);
+  }
+  const sky = starfield(ctx, o.seed ?? "sky");
+  stage.scene.add(sky);
+  // 별 점은 무한히 멀다 — 카메라 자리를 따라 옮겨 시차 없이 서 있게
+  stage.add(() => sky.position.copy(stage.camera.position));
+  return Object.assign((t: number) => stage.paint(t), stage);
+}
+
+function starfield(ctx: SceneCtx, seed: string): THREE.Group {
+  const group = new THREE.Group();
+  const layer = (n: number, size: number, opacity: number, salt: number) => {
+    const pos = new Float32Array(n * 3);
+    for (let i = 0; i < n; i++) {
+      const u = rand(seed, i * 3 + salt) * 2 - 1;
+      const a = rand(seed, i * 3 + salt + 1) * TAU;
+      const r = 180;
+      const s = Math.sqrt(1 - u * u);
+      pos.set([Math.cos(a) * s * r, u * r, Math.sin(a) * s * r], i * 3);
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute("position", new THREE.BufferAttribute(pos, 3));
+    const pts = new THREE.Points(geo, new THREE.PointsMaterial({ color: color(ctx, "orbit"), size, sizeAttenuation: false, transparent: true, opacity, depthWrite: false, fog: false, toneMapped: false }));
+    pts.renderOrder = -10;
+    group.add(pts);
+  };
+  layer(1300, 1.5, 0.42, 0);
+  layer(160, 2.6, 0.85, 99991);
+  return group;
+}
+
+/**
+ * 한글이 서는 글꼴로 그린 글자판 — 짙은 판에 왼쪽 눈금(기본 호박, 범례면 그 행성 색). 바뀌는 글은 draw 로 다시 칠한다.
+ * 크기는 화면 px 로 둔다(오러리의 이름표처럼) — 카메라가 물러나도 글이 읽히고, 다가가도 화면을 덮지 않는다
+ */
+function labelPlane(stage: Stage3D, ctx: SceneCtx, o: { sample: string; font?: Font; weight?: number; color?: string; plate?: boolean; tick?: string }) {
+  const px = 120;
+  const family = ctx.style.fonts[o.font ?? "display"];
+  const font = `${o.weight ?? 700} ${px}px ${family}`;
+  const probe = document.createElement("canvas").getContext("2d")!;
+  probe.font = font;
+  const plate = o.plate !== false;
+  const padX = plate ? px * 0.42 : px * 0.12;
+  const tick = plate ? px * 0.09 : 0;
+  const cw = Math.ceil(probe.measureText(o.sample).width + padX * 2 + tick);
+  const ch = Math.ceil(px * 1.3 + (plate ? px * 0.5 : px * 0.2));
+  const cv = document.createElement("canvas");
+  cv.width = cw;
+  cv.height = ch;
+  const g = cv.getContext("2d")!;
+  const tex = new THREE.CanvasTexture(cv);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = 4;
+  const mesh = new THREE.Mesh(
+    new THREE.PlaneGeometry(cw / ch, 1),
+    new THREE.MeshBasicMaterial({ map: tex, transparent: true, depthWrite: false, depthTest: false, toneMapped: false, side: THREE.DoubleSide }),
+  );
+  mesh.renderOrder = 20;
+  const ink = hex(ctx, o.color ?? "ink");
+  const draw = (s: string) => {
+    g.clearRect(0, 0, cw, ch);
+    if (plate) {
+      g.fillStyle = rgba(hex(ctx, "surface"), 0.86);
+      g.beginPath();
+      g.roundRect(0, 0, cw, ch, px * 0.14);
+      g.fill();
+      g.strokeStyle = rgba(hex(ctx, "line"), 1);
+      g.lineWidth = px * 0.03;
+      g.stroke();
+      g.fillStyle = hex(ctx, o.tick ?? "accent");
+      g.fillRect(px * 0.14, ch * 0.24, tick, ch * 0.52);
+    }
+    g.font = font;
+    g.fillStyle = ink;
+    g.textAlign = "center";
+    g.textBaseline = "middle";
+    g.fillText(s, (cw + tick) / 2 + (plate ? px * 0.05 : 0), ch / 2 + px * 0.05, cw - padX * 2);
+    tex.needsUpdate = true;
+  };
+  const cam = stage.camera as THREE.PerspectiveCamera;
+  const fwd = new THREE.Vector3();
+  /** 화면 px 높이 h 일 때의 세계 높이 — 카메라 앞 깊이로 잰다 */
+  const worldH = (pos: THREE.Vector3, h: number) => {
+    cam.getWorldDirection(fwd);
+    const d = Math.max(0.5, pos.clone().sub(cam.position).dot(fwd));
+    return (h / ctx.meta.height) * 2 * d * Math.tan(THREE.MathUtils.degToRad(cam.fov / 2));
+  };
+  /** pos 에 h px 높이로 세우고 카메라를 보게 한다. k 는 톡 서는 배율 */
+  const place = (pos: THREE.Vector3, h: number, k = 1) => {
+    mesh.position.copy(pos);
+    mesh.quaternion.copy(cam.quaternion);
+    mesh.scale.setScalar(Math.max(0.001, worldH(pos, h) * k));
+  };
+  return { mesh, draw, place, worldH };
+}
+
+/** 글자판 — 천체 곁에 떠서 늘 카메라를 본다. text 가 함수면 매 프레임 다시 칠한다(같은 t 를 두 번 그려도 같은 화면 글) */
+export function bodyTag(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; text: string | ((t: number) => string); on: Where; lift?: V3; px?: number; at?: number; until?: number; font?: Font; color?: string; plate?: boolean; sample?: string; tick?: string },
+): (t: number) => void {
+  const sample = o.sample ?? (typeof o.text === "function" ? o.text(1e9) : o.text);
+  const { mesh, draw, place } = labelPlane(stage, o.ctx, { sample, font: o.font, color: o.color, plate: o.plate, tick: o.tick });
+  if (typeof o.text === "string") draw(o.text);
+  stage.scene.add(mesh);
+  const lift = new THREE.Vector3(...(o.lift ?? [0, 0, 0]));
+  return (t) => {
+    const at = o.at ?? -1;
+    const on = t >= at && (o.until === undefined || t < o.until);
+    mesh.visible = on;
+    if (!on) return;
+    if (typeof o.text === "function") draw(o.text(t));
+    place(at3(o.on, t).add(lift), o.px ?? 64, pop(t, at, 0.3));
+  };
+}
+
+/** 게이트웨이 별 — 모든 궤도의 중심, 한 주소. 요청이 닿는 박(pulse)마다 빛무리가 크게 부풀었다 잦아든다. 행성의 낮·밤을 가르는 빛도 여기서. shapes 면 로고가 별 자리에서 빛난다 */
+export function gatewayStar(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; pos: V3; radius?: number; at?: number; pulse?: number[]; light?: number; shapes?: THREE.Shape[]; width?: number },
+): (t: number) => void {
+  const { ctx } = o;
+  const r = o.radius ?? 1;
+  const group = new THREE.Group();
+  group.position.set(...o.pos);
+  // shapes 를 주면 별 대신 그 표(로고)가 빛난다 — 끝 카드에서 게이트웨이의 이름이 곧 별이다
+  const coreGeo = o.shapes
+    ? new THREE.ExtrudeGeometry(o.shapes, { depth: 0.03, bevelEnabled: false, curveSegments: 10 }).scale(o.width ?? 4, o.width ?? 4, o.width ?? 4)
+    : new THREE.SphereGeometry(r, 32, 16);
+  const core = new THREE.Mesh(coreGeo, new THREE.MeshBasicMaterial({ color: color(ctx, o.shapes ? "accent" : "accentSoft"), toneMapped: false }));
+  const glow = glowSprite(ctx, "accent");
+  const halo = glowSprite(ctx, "accentSoft");
+  group.add(glow, halo, core);
+  stage.scene.add(group);
+  // 빛은 늘 켜 둔다(세기만 0) — 빛 개수가 바뀌면 셰이더를 다시 굽는다. 거리 끝을 두어 멀리 떨어진 다른 세트는 비추지 않는다
+  const light = new THREE.PointLight(0xfff1dc, 0, 90, 0);
+  light.position.set(...o.pos);
+  stage.scene.add(light);
+  return (t) => {
+    const a = pop(t, o.at ?? -1, 0.42);
+    group.visible = a > 0;
+    light.intensity = (o.light ?? 3.2) * clamp(a);
+    let f = 0;
+    for (const p of o.pulse ?? []) if (t >= p) f = Math.max(f, Math.exp(-(t - p) / 0.2));
+    core.scale.setScalar(Math.max(0.001, a * (1 + 0.14 * f)));
+    glow.scale.setScalar(Math.max(0.001, r * 7.5 * a * (1 + 0.8 * f)));
+    halo.scale.setScalar(Math.max(0.001, r * 3 * a * (1 + 0.3 * f)));
+  };
+}
+
+function bandTexture(ctx: SceneCtx, tone: string, seed: string): THREE.CanvasTexture {
+  const cv = document.createElement("canvas");
+  cv.width = 256;
+  cv.height = 128;
+  const g = cv.getContext("2d")!;
+  g.fillStyle = hex(ctx, tone);
+  g.fillRect(0, 0, 256, 128);
+  for (let i = 0; i < 11; i++) {
+    const y = rand(seed, i) * 128;
+    const h = 3 + rand(seed, i + 50) * 14;
+    g.fillStyle = rand(seed, i + 90) > 0.5 ? `rgba(255,255,255,${0.05 + 0.1 * rand(seed, i + 7)})` : `rgba(0,0,0,${0.08 + 0.14 * rand(seed, i + 9)})`;
+    g.fillRect(0, y, 256, h);
+  }
+  // 소용돌이 하나 — 띠 무늬만이면 자전이 안 보인다
+  g.fillStyle = "rgba(255,255,255,0.22)";
+  g.beginPath();
+  g.ellipse(60 + rand(seed, 200) * 140, 40 + rand(seed, 201) * 48, 22, 8, 0, 0, TAU);
+  g.fill();
+  const tex = new THREE.CanvasTexture(cv);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  return tex;
+}
+
+export interface Planet {
+  (t: number): void;
+  /** 그 시각 행성 가운데(세계 좌표) — 위성·글자판이 따라간다 */
+  where(t: number): THREE.Vector3;
+}
+
+/** 행성 = 모델 — 별 둘레 제 궤도를 쉬지 않고 돈다(주기 = 지연, 짧을수록 빠르다). at 에 궤도선이 한 바퀴 그어지고 공이 톡 떠오른다, 별 쪽 반만 밝다 */
+export function modelPlanet(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; center: V3; orbit: number; size: number; period: number; tone?: string; phase?: number; tilt?: number; at?: number; label?: string; labelFont?: Font; labelPx?: number; line?: number; spin?: number; seed?: string },
+): Planet {
+  const { ctx } = o;
+  const r = o.orbit;
+  const tilt = o.tilt ?? 0;
+  const center = new THREE.Vector3(...o.center);
+  const group = new THREE.Group();
+  group.position.copy(center);
+  group.rotation.x = tilt;
+  stage.scene.add(group);
+  const ang = (t: number) => TAU * ((o.phase ?? 0) + t / o.period);
+  const local = (t: number) => new THREE.Vector3(Math.cos(ang(t)) * r, 0, -Math.sin(ang(t)) * r);
+  const where = (t: number) => local(t).applyAxisAngle(X, tilt).add(center);
+  const seed = o.seed ?? `${o.label ?? "planet"}:${r}`;
+  const ball = new THREE.Mesh(new THREE.SphereGeometry(o.size, 40, 20), new THREE.MeshStandardMaterial({ map: bandTexture(ctx, o.tone ?? "teal", seed), roughness: 0.92, metalness: 0 }));
+  group.add(ball);
+  // 궤도선 — RingGeometry 를 눕히면 각 θ 가 (cos θ, 0, -sin θ) 에 놓여 local() 과 같은 자리다
+  const lw = o.line ?? 0.045;
+  const ringMat = new THREE.MeshBasicMaterial({ color: color(ctx, "orbit"), transparent: true, opacity: 0.4, side: THREE.DoubleSide, depthWrite: false, toneMapped: false });
+  const ring = new THREE.Mesh(new THREE.RingGeometry(r - lw / 2, r + lw / 2, 192, 1), ringMat);
+  ring.rotation.x = -Math.PI / 2;
+  group.add(ring);
+  let lastU = 1;
+  const tag = o.label ? labelPlane(stage, ctx, { sample: o.label, font: o.labelFont ?? "display" }) : null;
+  if (tag) {
+    tag.draw(o.label!);
+    stage.scene.add(tag.mesh);
+  }
+  const at = o.at ?? -1;
+  return Object.assign(
+    (t: number) => {
+      const u = settle(t, at, 0.55);
+      if (u !== lastU) {
+        ring.geometry.dispose();
+        ring.geometry = new THREE.RingGeometry(r - lw / 2, r + lw / 2, 192, 1, ang(at), TAU * Math.max(0.001, u));
+        lastU = u;
+      }
+      ring.visible = u > 0;
+      const a = pop(t, at + 0.05, 0.38);
+      ball.visible = a > 0;
+      ball.scale.setScalar(Math.max(0.001, a));
+      ball.position.copy(local(t));
+      ball.rotation.y = t * (o.spin ?? 0.9);
+      if (tag) {
+        tag.mesh.visible = t >= at + 0.1;
+        const c = where(t);
+        const h = tag.worldH(c, o.labelPx ?? 56);
+        tag.place(c.add(new THREE.Vector3(0, o.size * clamp(a) + 0.15 + h / 2, 0)), o.labelPx ?? 56, pop(t, at + 0.1, 0.28));
+      }
+    },
+    { where },
+  );
+}
+
+/**
+ * 위성 = 요청 — 천체 곁에서 쏘아 올려 궤도에 들고, 짧은 꼬리(지나온 길)를 끌며 돈다. 한 바퀴 = 한 번 왕복.
+ * period 는 안쪽 반지름의 주기, 바깥은 케플러대로 (r/r0)^1.5 배 느리다. 무리가 되면 껍질(incline 으로 기운 궤도들)
+ */
+export function requestSats(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; around: Where; count: number; radius: number | [number, number]; period: number; at?: number; spread?: number; incline?: number; trail?: number; tone?: string; size?: number; rise?: number; until?: number; seed?: string },
+): (t: number) => void {
+  const { ctx } = o;
+  const n = o.count;
+  const [r0, r1] = Array.isArray(o.radius) ? o.radius : [o.radius, o.radius];
+  const seed = o.seed ?? "sats";
+  const at = o.at ?? -1;
+  const spread = o.spread ?? 0;
+  const incline = o.incline ?? 0.6;
+  const sats = Array.from({ length: n }, (_, i) => {
+    const r = r0 + (r1 - r0) * rand(seed, i);
+    return { r, T: o.period * Math.pow(r / r0, 1.5), inc: (rand(seed, i + 101) * 2 - 1) * incline, node: rand(seed, i + 202) * TAU, ph: rand(seed, i + 303), L: at + (n > 1 ? (spread * i) / (n - 1) : 0) };
+  });
+  const rise = o.rise ?? r0 * 0.35;
+  const v = new THREE.Vector3();
+  const posAt = (s: (typeof sats)[number], t: number, out: THREE.Vector3) => {
+    const rr = rise + (s.r - rise) * settle(t, s.L, 0.42);
+    const th = TAU * (s.ph + (t - s.L) / s.T);
+    return out.set(Math.cos(th) * rr, 0, Math.sin(th) * rr).applyAxisAngle(X, s.inc).applyAxisAngle(Y, s.node).add(at3(o.around, t));
+  };
+  const size = o.size ?? 0.08;
+  const tone = color(ctx, o.tone ?? "accent");
+  const dots = new THREE.InstancedMesh(new THREE.SphereGeometry(size, 10, 6), new THREE.MeshBasicMaterial({ color: tone, toneMapped: false }), n);
+  dots.frustumCulled = false;
+  const glowPos = new Float32Array(n * 3);
+  const glowGeo = new THREE.BufferGeometry();
+  glowGeo.setAttribute("position", new THREE.BufferAttribute(glowPos, 3));
+  const glow = new THREE.Points(glowGeo, new THREE.PointsMaterial({ size: size * 9, map: glowTexture(hex(ctx, o.tone ?? "accent")), transparent: true, blending: THREE.AdditiveBlending, depthWrite: false, toneMapped: false }));
+  glow.frustumCulled = false;
+  const K = 14;
+  const trailPos = new Float32Array(n * K * 6);
+  const trailCol = new Float32Array(n * K * 6);
+  const trailGeo = new THREE.BufferGeometry();
+  trailGeo.setAttribute("position", new THREE.BufferAttribute(trailPos, 3));
+  trailGeo.setAttribute("color", new THREE.BufferAttribute(trailCol, 3));
+  const trails = new THREE.LineSegments(trailGeo, new THREE.LineBasicMaterial({ vertexColors: true, transparent: true, blending: THREE.AdditiveBlending, depthWrite: false, toneMapped: false }));
+  trails.frustumCulled = false;
+  stage.scene.add(trails, glow, dots);
+  const m = new THREE.Matrix4();
+  const a = new THREE.Vector3();
+  const b = new THREE.Vector3();
+  const FAR = 1e5;
+  return (t) => {
+    sats.forEach((s, i) => {
+      const on = t >= s.L && (o.until === undefined || t < o.until);
+      if (!on) {
+        dots.setMatrixAt(i, m.makeScale(0, 0, 0));
+        glowPos.set([0, -FAR, 0], i * 3);
+        trailPos.fill(0, i * K * 6, (i + 1) * K * 6);
+        trailCol.fill(0, i * K * 6, (i + 1) * K * 6);
+        return;
+      }
+      posAt(s, t, v);
+      const grow = Math.max(0.001, pop(t, s.L, 0.3));
+      dots.setMatrixAt(i, m.makeScale(grow, grow, grow).setPosition(v));
+      glowPos.set([v.x, v.y, v.z], i * 3);
+      const dt = ((o.trail ?? 0.2) * s.T) / K;
+      for (let j = 0; j < K; j++) {
+        const ta = t - j * dt;
+        const tb = Math.max(s.L, ta - dt);
+        const k = (i * K + j) * 6;
+        if (ta <= s.L) {
+          trailPos.fill(0, k, k + 6);
+          trailCol.fill(0, k, k + 6);
+          continue;
+        }
+        posAt(s, ta, a);
+        posAt(s, tb, b);
+        trailPos.set([a.x, a.y, a.z, b.x, b.y, b.z], k);
+        const f0 = 1 - j / K;
+        const f1 = 1 - (j + 1) / K;
+        trailCol.set([tone.r * f0, tone.g * f0, tone.b * f0, tone.r * f1, tone.g * f1, tone.b * f1], k);
+      }
+    });
+    dots.instanceMatrix.needsUpdate = true;
+    glowGeo.attributes.position.needsUpdate = true;
+    trailGeo.attributes.position.needsUpdate = true;
+    trailGeo.attributes.color.needsUpdate = true;
+  };
+}
+
+/** 궤도 전이 = 라우팅·폴백 — 위성 하나가 휜 전이 궤도를 그리며 from 에서 to 로 옮겨 간다. 지나온 길은 점선으로 남았다가 닿으면 잦아든다 */
+export function transferArc(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; from: Where; to: Where; at: number; dur?: number; bend?: number; lift?: number; tone?: string; size?: number; label?: string; labelFont?: Font; labelPx?: number; linger?: number },
+): (t: number) => void {
+  const { ctx } = o;
+  const dur = o.dur ?? 0.5;
+  const A = at3(o.from, o.at);
+  const B = at3(o.to, o.at + dur);
+  const d = B.clone().sub(A);
+  const side = new THREE.Vector3(-d.z, 0, d.x).normalize();
+  const C = A.clone()
+    .lerp(B, 0.5)
+    .addScaledVector(side, d.length() * (o.bend ?? 0.3))
+    .addScaledVector(Y, d.length() * (o.lift ?? 0.12));
+  const curve = new THREE.QuadraticBezierCurve3(A, C, B);
+  const N = 96;
+  const line = new THREE.Line(
+    new THREE.BufferGeometry().setFromPoints(curve.getPoints(N)),
+    new THREE.LineDashedMaterial({ color: color(ctx, o.tone ?? "accent"), dashSize: 0.22, gapSize: 0.14, transparent: true, depthWrite: false, toneMapped: false }),
+  );
+  line.computeLineDistances();
+  const size = o.size ?? 0.13;
+  const dot = new THREE.Mesh(new THREE.SphereGeometry(size, 12, 8), new THREE.MeshBasicMaterial({ color: color(ctx, o.tone ?? "accent"), toneMapped: false }));
+  const glow = glowSprite(ctx, o.tone ?? "accent");
+  glow.scale.setScalar(size * 10);
+  dot.add(glow);
+  stage.scene.add(line, dot);
+  const tag = o.label ? labelPlane(stage, ctx, { sample: o.label, font: o.labelFont ?? "mono" }) : null;
+  if (tag) {
+    tag.draw(o.label!);
+    stage.scene.add(tag.mesh);
+  }
+  const linger = o.linger ?? 0.35;
+  return (t) => {
+    const k = (t - o.at) / dur;
+    const live = k >= 0 && t < o.at + dur + linger;
+    line.visible = live;
+    dot.visible = k >= 0 && k < 1;
+    if (tag) tag.mesh.visible = live;
+    if (!live) return;
+    const u = ease.inOutCubic(clamp(k));
+    line.geometry.setDrawRange(0, Math.max(2, Math.ceil(u * N) + 1));
+    (line.material as THREE.LineDashedMaterial).opacity = 0.9 * (1 - clamp((t - o.at - dur) / linger));
+    const p = curve.getPoint(u);
+    dot.position.copy(p);
+    if (tag) {
+      const lpx = o.labelPx ?? 50;
+      tag.place(p.clone().addScaledVector(Y, size + 0.15 + tag.worldH(p, lpx) / 2), lpx, pop(t, o.at, 0.25) * (1 - clamp((t - o.at - dur) / linger)));
+    }
+  };
+}
+
+export interface PriceRing {
+  (t: number): void;
+  /** 그 시(0–24)의 고리 바깥 자리 — 시각 글자판을 붙인다 */
+  hour(h: number, out?: number): THREE.Vector3;
+}
+
+/**
+ * 하루 고리 = 시간대 비용 — 자전하는 행성을 24 시 막대가 시계처럼 두르고(막대 길이 = 값), 별 반대쪽 밤 반구에 든 창(window)의 막대가
+ * fall 에 off 만큼 쑥 줄어든다. 행성의 밤 그늘이 곧 싼 시간대다. 00 시가 위, 시계 방향
+ */
+export function nightPrice(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; pos: V3; radius?: number; at?: number; fall: number; window?: [number, number]; off?: number; tone?: string; sun?: V3; light?: number },
+): PriceRing {
+  const { ctx } = o;
+  const r = o.radius ?? 2.4;
+  const [h0, h1] = o.window ?? [0, 10];
+  const off = o.off ?? 0.9;
+  const group = new THREE.Group();
+  group.position.set(...o.pos);
+  stage.scene.add(group);
+  const ball = new THREE.Mesh(new THREE.SphereGeometry(r, 48, 24), new THREE.MeshStandardMaterial({ map: bandTexture(ctx, o.tone ?? "ice", "dayside"), roughness: 0.92 }));
+  group.add(ball);
+  // 이 행성만 비추는 별빛 — 왼쪽에서 와서 오른쪽(00–10 시 쪽)이 밤 그늘이 된다
+  const sunAt = new THREE.Vector3(...(o.sun ?? [-16, 3, 6])).add(group.position);
+  const light = new THREE.PointLight(0xfff1dc, o.light ?? 3.4, 60, 0);
+  light.position.copy(sunAt);
+  stage.scene.add(light);
+  const gap = r * 0.14;
+  const len = r * 0.62;
+  const theta = (h: number) => Math.PI / 2 - (h / 24) * TAU;
+  const w = ((TAU * (r + gap)) / 24) * 0.62;
+  const geo = new THREE.BoxGeometry(w, 1, 0.16);
+  geo.translate(0, 0.5, 0);
+  const night = (h: number) => h >= h0 && h < h1;
+  const bars = Array.from({ length: 24 }, (_, h) => {
+    const pivot = new THREE.Object3D();
+    pivot.rotation.z = theta(h + 0.5) - Math.PI / 2;
+    const bar = new THREE.Mesh(geo, new THREE.MeshBasicMaterial({ color: color(ctx, night(h) ? "accent" : "orbit"), transparent: true, opacity: night(h) ? 1 : 0.5, toneMapped: false }));
+    bar.position.y = r + gap;
+    pivot.add(bar);
+    group.add(pivot);
+    return { bar, h };
+  });
+  const at = o.at ?? -1;
+  return Object.assign(
+    (t: number) => {
+      const a = pop(t, at, 0.4);
+      ball.visible = a > 0;
+      ball.scale.setScalar(Math.max(0.001, a));
+      ball.rotation.y = t * 0.5;
+      const sink = 1 - off * settle(t, o.fall, 0.38);
+      for (const { bar, h } of bars) {
+        const g = pop(t, at + 0.15 + h * 0.012, 0.3);
+        bar.visible = g > 0;
+        bar.scale.y = Math.max(0.001, len * g * (night(h) ? sink : 1));
+      }
+    },
+    {
+      hour: (h: number, out = 1.4) =>
+        new THREE.Vector3(Math.cos(theta(h)), Math.sin(theta(h)), 0).multiplyScalar(r + gap + len * out).add(group.position),
+    },
+  );
+}
+
+/**
+ * 고리 = 캐시 — 행성이 두른 알갱이 고리에 지난 문맥이 쌓인다(안쪽 알갱이가 빨리 돈다). squeeze 면 고리 폭이 by 배로 좁아진다 —
+ * 캐시 압축(57× 면 한 줄 실이 된다). 고리는 at 에 한 바퀴 휘감기며 생긴다
+ */
+export function cacheRing(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; around: Where; inner: number; outer: number; count?: number; tilt?: number; at?: number; squeeze?: { at: number; dur?: number; by: number }; tone?: string; speed?: number; seed?: string },
+): (t: number) => void {
+  const { ctx } = o;
+  const n = o.count ?? 900;
+  const seed = o.seed ?? "ring";
+  const tilt = o.tilt ?? 0.42;
+  const parts = Array.from({ length: n }, (_, i) => {
+    const r = o.inner + (o.outer - o.inner) * Math.pow(rand(seed, i), 0.85);
+    return { r, phi: rand(seed, i + 7001) * TAU, y: (rand(seed, i + 9001) - 0.5) * 0.05, w: (o.speed ?? 0.9) * Math.pow(o.inner / r, 1.5) };
+  });
+  const pos = new Float32Array(n * 3);
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute("position", new THREE.BufferAttribute(pos, 3));
+  const pts = new THREE.Points(geo, new THREE.PointsMaterial({ color: color(ctx, o.tone ?? "sand"), size: 0.07, transparent: true, opacity: 0.95, depthWrite: false, toneMapped: false }));
+  pts.frustumCulled = false;
+  stage.scene.add(pts);
+  const v = new THREE.Vector3();
+  const at = o.at ?? -1;
+  return (t) => {
+    const c = at3(o.around, t);
+    const sq = o.squeeze;
+    const u = sq ? ease.inOutCubic(clamp((t - sq.at) / (sq.dur ?? 0.6))) : 0;
+    parts.forEach((p, i) => {
+      const shown = t >= at + (p.phi / TAU) * 0.45;
+      if (!shown) {
+        pos.set([0, -1e5, 0], i * 3);
+        return;
+      }
+      const tight = o.inner + (p.r - o.inner) / (sq?.by ?? 1);
+      const r = p.r + (tight - p.r) * u;
+      const a = p.phi + t * p.w;
+      v.set(Math.cos(a) * r, p.y * (1 - u), Math.sin(a) * r).applyAxisAngle(X, tilt).add(c);
+      pos.set([v.x, v.y, v.z], i * 3);
+    });
+    geo.attributes.position.needsUpdate = true;
+  };
+}
+
+export interface Belt {
+  (t: number): void;
+  /** 그 시각까지 떠오른 행성 수 — 화면 숫자와 점이 같은 값을 쓴다 */
+  shown(t: number): number;
+}
+
+/** 행성대 = 모델 목록 — 작은 행성 count 개가 한 궤도면에 차례로 떠올라 돈다(at 부터 dur 동안 하나씩, 안쪽이 빠르다). 별빛을 받아 반쪽만 밝다 */
+export function modelBelt(
+  stage: Stage3D,
+  o: { ctx: SceneCtx; center: V3; count: number; radius: [number, number]; period: number; at?: number; dur?: number; size?: number; tilt?: number; tones?: string[]; seed?: string },
+): Belt {
+  const { ctx } = o;
+  const n = o.count;
+  const seed = o.seed ?? "belt";
+  const [r0, r1] = o.radius;
+  const tones = (o.tones ?? ["teal", "rust", "sand", "lilac", "ice"]).map((k) => color(ctx, k));
+  const center = new THREE.Vector3(...o.center);
+  const tilt = o.tilt ?? 0;
+  const at = o.at ?? -1;
+  const dur = o.dur ?? 0;
+  const bodies = Array.from({ length: n }, (_, i) => {
+    const r = r0 + (r1 - r0) * rand(seed, i);
+    return { r, phi: rand(seed, i + 501) * TAU, T: o.period * Math.pow(r / r0, 1.5), y: (rand(seed, i + 907) - 0.5) * 0.3, s: 0.7 + 0.6 * rand(seed, i + 1301), L: at + (n > 1 ? (dur * i) / (n - 1) : 0) };
+  });
+  const mesh = new THREE.InstancedMesh(new THREE.SphereGeometry(o.size ?? 0.16, 16, 10), new THREE.MeshStandardMaterial({ roughness: 0.9, metalness: 0 }), n);
+  bodies.forEach((_, i) => mesh.setColorAt(i, tones[i % tones.length]));
+  mesh.frustumCulled = false;
+  stage.scene.add(mesh);
+  const m = new THREE.Matrix4();
+  const v = new THREE.Vector3();
+  const shown = (t: number) => bodies.filter((b) => t >= b.L).length;
+  return Object.assign(
+    (t: number) => {
+      bodies.forEach((b, i) => {
+        const g = pop(t, b.L, 0.3);
+        if (g <= 0) {
+          mesh.setMatrixAt(i, m.makeScale(0, 0, 0));
+          return;
+        }
+        const a = b.phi + (TAU * t) / b.T;
+        v.set(Math.cos(a) * b.r, b.y, -Math.sin(a) * b.r).applyAxisAngle(X, tilt).add(center);
+        const k = g * b.s;
+        mesh.setMatrixAt(i, m.makeScale(k, k, k).setPosition(v));
+      });
+      mesh.instanceMatrix.needsUpdate = true;
+    },
+    { shown },
+  );
+}
+
+/** 드롭 — 별이 터지듯 빛나고 궤도면을 따라 충격파 고리 둘이 번져 나간다. 섬광·흔들림은 dropBurst 로(검사가 센다) */
+export function starFlare(stage: Stage3D, o: { ctx: SceneCtx; pos: V3; drop?: number; reach?: number; tone?: string }): (t: number) => void {
+  const { ctx } = o;
+  const reach = o.reach ?? 22;
+  const mk = () => {
+    const m = new THREE.Mesh(
+      new THREE.RingGeometry(0.97, 1, 160),
+      new THREE.MeshBasicMaterial({ color: color(ctx, o.tone ?? "accentSoft"), transparent: true, blending: THREE.AdditiveBlending, depthWrite: false, side: THREE.DoubleSide, toneMapped: false }),
+    );
+    m.rotation.x = -Math.PI / 2;
+    m.position.set(...o.pos);
+    stage.scene.add(m);
+    return m;
+  };
+  const rings = [mk(), mk()];
+  const flash = document.createElement("div");
+  flash.style.cssText = `position:absolute;inset:0;background:${hex(ctx, "accentSoft")};opacity:0;pointer-events:none;`;
+  stage.el.append(flash);
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "starFlare" });
+    flash.style.opacity = String(Math.round(s.flash * 70) / 100);
+    const local = t - ctx.beats.drop(o.drop ?? 0);
+    rings.forEach((m, i) => {
+      const k = (local - i * 0.14) / 1.15;
+      m.visible = k >= 0 && k < 1;
+      if (!m.visible) return;
+      m.scale.setScalar(Math.max(0.001, 1.5 + (reach - 1.5) * ease.outCubic(k)));
+      (m.material as THREE.MeshBasicMaterial).opacity = (1 - k) * (i ? 0.6 : 1);
+    });
+    stage.camera.position.x += (s.shake.x ?? 0) * 0.02;
+    stage.camera.position.y += (s.shake.y ?? 0) * 0.02;
+  };
+}

package/themes/orbit-system/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>