kasaframe 0.0.0-stage → 0.1.3

package/packages/adapters/src/page.ts

@@ -0,0 +1,229 @@
+import { setFrameSample, setFrameTime, type FrameSample, type KfMeta, type KfMotionEvent } from "@kasaframe/core";
+import type { KfClock } from "@kasaframe/clock/types";
+import { syncCss } from "./css.ts";
+import { syncMedia } from "./media.ts";
+
+export type KfMode = "seek" | "step";
+
+export interface KfMarker {
+  t: number;
+  label: string;
+  kind: "scene" | "beat" | "drop" | "section";
+}
+
+export interface KfPageMeta extends KfMeta {
+  // 프로젝트 기준 곡 경로. 미리보기는 이걸 기준 시계로, 렌더는 이걸 영상에 얹는다.
+  music?: string;
+}
+
+export interface KfPage {
+  meta: KfPageMeta;
+  mode: KfMode;
+  ready(): Promise<void>;
+  // sample — 렌더의 모션 블러 하위 프레임(몇 번째·몇 장 중). 없으면 보통 프레임
+  seek(t: number, sample?: FrameSample): Promise<void>;
+  markers?: KfMarker[];
+  events?: KfMotionEvent[];
+}
+
+export interface PageOptions {
+  meta: KfPageMeta;
+  mode?: KfMode;
+  markers?: KfMarker[];
+  ready?(): Promise<void>;
+  render?(t: number): void | Promise<void>;
+  // React 는 flushSync 를 넘겨 setFrameTime 과 render 를 한 번에 커밋한다.
+  commit?(fn: () => void): void;
+  // <video> 를 시각에 묶을지. 기본 켬.
+  media?: boolean;
+}
+
+declare global {
+  interface Window {
+    __kf?: Partial<KfPage>;
+  }
+}
+
+type Syncer = (t: number) => void | Promise<void>;
+const syncers = new Set<Syncer>();
+
+// lottie·gsap·three 처럼 시각을 직접 맞춰야 하는 것들이 여기 건다. seek 마다 순서대로 불린다.
+export function onSeek(fn: Syncer): () => void {
+  syncers.add(fn);
+  return () => {
+    syncers.delete(fn);
+  };
+}
+
+export function clock(): KfClock | undefined {
+  return window.__kfClock;
+}
+
+function fontsSettled(): Promise<void> {
+  const realTimeout = clock()?.real.setTimeout ?? setTimeout;
+  return Promise.race([document.fonts.ready.then(() => {}), new Promise<void>((r) => realTimeout(r, 10_000))]);
+}
+
+// unicode-range 로 쪼갠 글꼴(구글 폰트)은 레이아웃이 그 글자를 만나야 조각을 받기 시작한다.
+// 레이아웃을 먼저 강제해 요청을 내보낸 뒤 받을 때까지 기다린다 — font-display:block 이면 그동안 글자가 투명하다.
+async function fontsForFrame(): Promise<void> {
+  for (let i = 0; i < 3; i++) {
+    void document.documentElement.getBoundingClientRect();
+    if (document.fonts.status !== "loading") return;
+    await fontsSettled();
+  }
+}
+
+function nextPaint(): Promise<void> {
+  return new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+}
+
+const IMAGE_PROPS = ["backgroundImage", "maskImage", "borderImageSource", "listStyleImage"] as const;
+const URL_RE = /url\(\s*(['"]?)(.*?)\1\s*\)/g;
+
+function grabUrls(value: string | undefined, base: string, into: Set<string>) {
+  if (!value || !value.includes("url(")) return;
+  for (const m of value.matchAll(URL_RE)) {
+    if (m[2] && !m[2].startsWith("data:")) into.add(new URL(m[2], base).href);
+  }
+}
+
+// CSS 로 깐 그림(background-image 등)은 <img> 와 달리 기다릴 손잡이가 없다. url() 을 모아 미리 받아 두면 첫 래스터에 들어간다.
+function cssImageUrls(elements: Iterable<Element>, sheets: boolean): Set<string> {
+  const urls = new Set<string>();
+  for (const el of elements) {
+    if (!el.isConnected) continue;
+    const cs = getComputedStyle(el);
+    for (const p of IMAGE_PROPS) grabUrls(cs[p], document.baseURI, urls);
+  }
+  if (sheets) {
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules: CSSRuleList;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        continue;
+      }
+      for (const r of Array.from(rules)) {
+        if (r instanceof CSSStyleRule) for (const p of IMAGE_PROPS) grabUrls(r.style[p], sheet.href ?? document.baseURI, urls);
+      }
+    }
+  }
+  return urls;
+}
+
+const preloaded = new Set<string>();
+
+function preload(urls: Iterable<string>): Promise<unknown> {
+  const realTimeout = clock()?.real.setTimeout ?? setTimeout;
+  const jobs: Promise<unknown>[] = [];
+  for (const src of urls) {
+    if (preloaded.has(src)) continue;
+    preloaded.add(src);
+    const img = new Image();
+    img.src = src;
+    jobs.push(img.decode().catch(() => console.warn(`[kf] 그림을 못 받았다: ${src}`)));
+  }
+  if (!jobs.length) return Promise.resolve();
+  return Promise.race([Promise.allSettled(jobs), new Promise((r) => realTimeout(r, 15_000))]);
+}
+
+// 장면이 처음 그려질 때(React 장면 등) 생기는 배경 그림도 잡도록, 바뀐 요소만 골라 본다.
+const touched = new Set<Element>();
+function watchTouched() {
+  new MutationObserver((records) => {
+    for (const r of records) {
+      if (r.type === "attributes" && r.target instanceof Element) touched.add(r.target);
+      for (const n of Array.from(r.addedNodes)) if (n instanceof Element) touched.add(n);
+    }
+  }).observe(document, { subtree: true, childList: true, attributes: true, attributeFilter: ["style", "class"] });
+}
+
+function imagesForFrame(): Promise<unknown> {
+  if (!touched.size) return Promise.resolve();
+  const els: Element[] = [];
+  for (const el of touched) els.push(el, ...Array.from(el.querySelectorAll("*")));
+  touched.clear();
+  return preload(cssImageUrls(els, false));
+}
+
+async function assetsReady(): Promise<void> {
+  await document.fonts.ready;
+  const realTimeout = clock()?.real.setTimeout ?? setTimeout;
+  const imgs = Array.from(document.images).filter((i) => i.src && !i.complete);
+  await Promise.race([
+    Promise.allSettled([...imgs.map((i) => i.decode()), preload(cssImageUrls(document.querySelectorAll("*"), true))]),
+    new Promise((r) => realTimeout(r, 15_000)),
+  ]);
+  touched.clear();
+  const media = Array.from(document.querySelectorAll("video"));
+  await Promise.allSettled(
+    media.map(
+      (v) =>
+        new Promise<void>((resolve) => {
+          // 오류가 리스너를 걸기 전에 이미 났을 수 있다(없는 파일). 그땐 기다릴 것이 없다.
+          if (v.readyState >= 2 || v.error || v.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) return resolve();
+          v.addEventListener("loadeddata", () => resolve(), { once: true });
+          v.addEventListener("error", () => resolve(), { once: true });
+          realTimeout(resolve, 15_000);
+        }),
+    ),
+  );
+  for (const v of media) {
+    if (v.readyState < 2) console.warn(`[kf] 영상을 못 받았다(빈 칸으로 찍힌다): ${v.currentSrc || v.src}`);
+  }
+}
+
+export function definePage(o: PageOptions): KfPage {
+  const mode = o.mode ?? "seek";
+  const c0 = clock();
+  if (c0) {
+    c0.mode = mode;
+    c0.fps = o.meta.fps;
+  }
+  const commit = o.commit ?? ((fn: () => void) => fn());
+  watchTouched();
+  const page: KfPage = {
+    meta: o.meta,
+    mode,
+    markers: o.markers ?? [],
+    async ready() {
+      await o.ready?.();
+      await assetsReady();
+      await fontsForFrame();
+    },
+    async seek(t: number, sample?: FrameSample) {
+      setFrameSample(sample?.index ?? 0, sample?.count ?? 1);
+      const c = clock();
+      const draw = async (at: number) => {
+        let pending: void | Promise<void> = undefined;
+        commit(() => {
+          setFrameTime(at);
+          pending = o.render?.(at);
+        });
+        await pending;
+      };
+      if (c && mode === "step") {
+        // 자기 시계로 도는 컴포넌트가 중간 프레임의 props 변화도 겪어야 해서, 건너뛰는 프레임마다 그린다.
+        let drawn = -1;
+        await c.advanceTo(t * 1000, (ms) => draw((drawn = Math.round((ms / 1000) * o.meta.fps) / o.meta.fps)));
+        if (drawn !== t) await draw(t);
+      } else {
+        if (c) await c.jumpTo(t * 1000);
+        await draw(t);
+      }
+      if (o.media !== false) await syncMedia(t);
+      for (const fn of syncers) await fn(t);
+      await imagesForFrame();
+      if (c) await c.settle();
+      else {
+        if (mode === "seek") syncCss(t);
+        await nextPaint();
+      }
+      await fontsForFrame();
+    },
+  };
+  // 움직임 부품이 먼저 쌓아 둔 events 를 잃지 않게 덮어쓰지 않고 채운다.
+  window.__kf = Object.assign(window.__kf ?? {}, page);
+  return window.__kf as KfPage;
+}

package/packages/adapters/src/project.ts

@@ -0,0 +1,214 @@
+import {
+  createBeats,
+  cssVars,
+  fontCss,
+  setBeats,
+  silentBeats,
+  type BeatsJson,
+  type KfStyle,
+  type SafeArea,
+  type SceneCtx,
+} from "@kasaframe/core";
+import { definePage, type KfMarker, type KfMode, type KfPage } from "./page.ts";
+
+export interface KfSceneEntry {
+  id: string;
+  from: number;
+  dur: number;
+  file?: string;
+  role?: string;
+  idea?: string;
+}
+
+// kf.json 중 엔진이 읽는 부분. 나머지 키는 그대로 둔다.
+export interface KfProjectJson {
+  fps: number;
+  width: number;
+  height: number;
+  duration: number;
+  mode?: KfMode;
+  music?: string;
+  safeArea?: SafeArea;
+  scenes: KfSceneEntry[];
+  [k: string]: unknown;
+}
+
+export type SceneDraw = (t: number) => void;
+
+export interface SceneModule {
+  build?(root: HTMLElement, ctx: SceneCtx): SceneDraw | void;
+  react?: unknown;
+}
+
+export interface MountOptions {
+  kf: KfProjectJson;
+  // import.meta.glob("./scenes/*.ts", { eager: true }) 그대로, 또는 { [id]: 모듈 }
+  scenes: Record<string, unknown>;
+  beats?: BeatsJson | string | null;
+  style?: KfStyle | string | null;
+  stage: HTMLElement;
+}
+
+interface LiveScene {
+  entry: KfSceneEntry;
+  root: HTMLElement;
+  draw: SceneDraw;
+}
+
+const ZERO: SafeArea = { top: 0, bottom: 0, left: 0, right: 0 };
+
+async function load<T>(v: T | string | null | undefined): Promise<T | null> {
+  if (v == null) return null;
+  if (typeof v !== "string") return v;
+  const res = await fetch(v);
+  if (!res.ok) return null;
+  return (await res.json()) as T;
+}
+
+function baseName(p: string): string {
+  return p.split("/").pop()!.replace(/\.[^.]+$/, "");
+}
+
+function findModule(scenes: Record<string, unknown>, entry: KfSceneEntry): SceneModule {
+  const file = entry.file?.replace(/^\.\//, "");
+  for (const [key, mod] of Object.entries(scenes)) {
+    const k = key.replace(/^\.\//, "");
+    if (k === entry.id || (file && (k === file || k.endsWith(`/${file}`))) || baseName(k) === entry.id) {
+      const m = mod as { default?: SceneModule } & SceneModule;
+      return m.default ?? m;
+    }
+  }
+  throw new Error(`장면 "${entry.id}" 의 파일을 못 찾았다 (${entry.file ?? `scenes/${entry.id}.ts`})`);
+}
+
+function assetUrl(path: string): string {
+  const clean = path.replace(/^\.?\/+/, "").replace(/^assets\//, "");
+  return new URL(`assets/${clean}`, document.baseURI).href;
+}
+
+function loadSheet(href: string): Promise<void> {
+  return new Promise((resolve) => {
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.onload = link.onerror = () => resolve();
+    document.head.prepend(link);
+  });
+}
+
+// font-display:block 이라 받는 동안 글자가 투명하다. 첫 레이아웃 전의 fonts.ready 는 아직 부르지도 않은 글꼴을 안 기다리므로,
+// @import 대신 <link> 로 CSS 를 받아 끝을 확인하고, 쓰는 글꼴 스택마다 직접 load 를 건다.
+async function injectStyle(style: KfStyle | null, kf: KfProjectJson) {
+  const el = document.createElement("style");
+  el.dataset.kf = "project";
+  el.textContent = [
+    "html, body { margin: 0; padding: 0; background: #000; overflow: hidden; }",
+    // 장면 루트의 display 는 장면 몫이라 켜고 끄기는 hidden 으로 한다.
+    "[data-kf-scene][hidden] { display: none !important; }",
+    style ? fontCss(style).split("\n").filter((l) => !l.startsWith("@import")).join("\n") : "",
+    style ? cssVars(style, kf) : "",
+  ].join("\n");
+  document.head.prepend(el);
+  if (!style) return;
+  await Promise.all((style.fonts.css ?? []).map(loadSheet));
+  const weights = [...new Set([400, style.type.weightBody, style.type.weightDisplay])];
+  const stacks = [style.fonts.sans, style.fonts.display, style.fonts.mono];
+  await Promise.allSettled(
+    stacks.flatMap((stack) => weights.map((w) => document.fonts.load(`${w} 1em ${stack}`, "가A1"))),
+  );
+}
+
+export function projectMarkers(kf: KfProjectJson, beats: BeatsJson | null): KfMarker[] {
+  const out: KfMarker[] = kf.scenes.map((s) => ({ t: s.from, label: s.id, kind: "scene" }));
+  if (beats) {
+    for (const t of beats.beats ?? []) out.push({ t, label: "beat", kind: "beat" });
+    (beats.drops ?? []).forEach((t, i) => out.push({ t, label: `drop ${i}`, kind: "drop" }));
+    for (const s of beats.sections ?? []) out.push({ t: s.t, label: s.kind, kind: "section" });
+  }
+  return out.sort((a, b) => a.t - b.t);
+}
+
+export function mountProject(o: MountOptions): KfPage {
+  const { kf, stage } = o;
+  const live: LiveScene[] = [];
+  let captions: SceneDraw | null = null;
+  let built: Promise<void> | null = null;
+  let markers: KfMarker[] = projectMarkers(kf, typeof o.beats === "object" ? o.beats : null);
+
+  Object.assign(stage.style, {
+    position: "relative",
+    width: `${kf.width}px`,
+    height: `${kf.height}px`,
+    overflow: "hidden",
+  });
+
+  async function build() {
+    const [beats, style] = await Promise.all([load<BeatsJson>(o.beats), load<KfStyle>(o.style)]);
+    if (beats) setBeats(beats);
+    markers = projectMarkers(kf, beats);
+    page.markers = markers;
+    await injectStyle(style, kf);
+    const meta = { fps: kf.fps, width: kf.width, height: kf.height, duration: kf.duration };
+    // 자막을 켜면 장면을 짓기 전에 안전 영역 아래쪽 자막 띠를 뺀다 — 주소 ?captions=on|off|fit 가 kf.json 을 그 판만 덮는다(kf render --captions)
+    const { captionsPlan } = await import("@kasaframe/motion/captions");
+    const caps = await captionsPlan({ kf: kf as Parameters<typeof captionsPlan>[0]["kf"], mode: new URLSearchParams(location.search).get("captions"), style: style as KfStyle | null });
+    for (const entry of kf.scenes) {
+      const mod = findModule(o.scenes, entry);
+      const root = document.createElement("div");
+      root.dataset.kfScene = entry.id;
+      root.style.cssText = "position:absolute;inset:0;overflow:hidden;";
+      root.hidden = true;
+      stage.appendChild(root);
+      const ctx: SceneCtx = {
+        id: entry.id,
+        from: entry.from,
+        dur: entry.dur,
+        meta,
+        beats: beats ? createBeats(beats, entry.from) : silentBeats(entry.dur),
+        style: style as KfStyle,
+        safe: caps?.safe ?? kf.safeArea ?? ZERO,
+        asset: assetUrl,
+      };
+      let draw: SceneDraw;
+      if (mod.react) {
+        const { reactScene } = await import("./react.ts");
+        draw = reactScene(root, mod.react, ctx);
+      } else if (mod.build) {
+        draw = mod.build(root, ctx) ?? (() => {});
+      } else {
+        throw new Error(`장면 "${entry.id}" 가 build 도 react 도 내보내지 않는다`);
+      }
+      live.push({ entry, root, draw });
+    }
+    // 자막 판은 장면들 위 한 겹 — 장면 파일은 그대로다
+    captions = (await caps?.mount(stage, style)) ?? null;
+  }
+
+  const last = kf.scenes[kf.scenes.length - 1];
+  function render(t: number) {
+    for (const s of live) {
+      const { from, dur } = s.entry;
+      // 마지막 장면은 끝 시각까지 붙든다 — duration 정각을 찍어도 빈 화면이 안 나오게.
+      const on = t >= from && (t < from + dur || (s.entry === last && t <= from + dur + 1e-6));
+      if (s.root.hidden === on) s.root.hidden = !on;
+      if (on) s.draw(t - from);
+    }
+    captions?.(t);
+  }
+
+  const page = definePage({
+    meta: {
+      fps: kf.fps,
+      width: kf.width,
+      height: kf.height,
+      duration: kf.duration,
+      ...(kf.music ? { music: kf.music } : {}),
+    },
+    mode: kf.mode ?? "seek",
+    markers,
+    ready: () => (built ??= build()),
+    render,
+  });
+  built = build();
+  return page;
+}

package/packages/adapters/src/react.ts

@@ -0,0 +1,36 @@
+import { createElement, type ComponentType, type ReactNode } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import type { SceneCtx } from "@kasaframe/core";
+import { definePage, type KfPage, type PageOptions } from "./page.ts";
+
+export interface SceneProps {
+  t: number;
+  ctx: SceneCtx;
+}
+
+// mountProject 가 React 장면을 붙일 때 쓴다. seek 마다 동기로 커밋해야 찍을 때 화면이 맞다.
+export function reactScene(root: HTMLElement, Comp: unknown, ctx: SceneCtx): (t: number) => void {
+  const r = createRoot(root);
+  const C = Comp as ComponentType<SceneProps>;
+  return (t) => flushSync(() => r.render(createElement(C, { t, ctx })));
+}
+
+// 장면 시간표 없이 React 트리 하나를 영상으로 쓸 때. 자기 시계를 쓰는 컴포넌트면 mode: "step".
+export function renderReact(
+  node: ReactNode | ComponentType<{ t: number }>,
+  o: Omit<PageOptions, "render" | "commit"> & { container: HTMLElement },
+): KfPage {
+  const r = createRoot(o.container);
+  const isComponent = typeof node === "function";
+  let mounted = false;
+  return definePage({
+    ...o,
+    commit: (fn) => flushSync(fn),
+    render(t) {
+      if (isComponent) r.render(createElement(node as ComponentType<{ t: number }>, { t }));
+      else if (!mounted) r.render(node as ReactNode);
+      mounted = true;
+    },
+  });
+}

package/packages/adapters/src/svelte.ts

@@ -0,0 +1,22 @@
+import { flushSync, mount, type Component } from "svelte";
+import { readable } from "svelte/store";
+import { frameTime, onFrame } from "@kasaframe/core";
+import { definePage, type KfPage, type PageOptions } from "./page.ts";
+
+// 컴포넌트에서 $time 으로 영상 시각(초)을 읽는다. 프로젝트 vite.config 에 @sveltejs/vite-plugin-svelte 가 있어야 .svelte 가 묶인다.
+export const time = readable(frameTime(), (set) => onFrame(set));
+
+export function renderSvelte(
+  root: Component<Record<string, unknown>>,
+  o: Omit<PageOptions, "render" | "commit"> & { container: HTMLElement; props?: Record<string, unknown> },
+): KfPage {
+  mount(root, { target: o.container, props: o.props ?? {} });
+  return definePage({
+    ...o,
+    // 스토어 갱신은 다음 마이크로태스크에 반영되므로 setFrameTime 직후 동기로 밀어 넣는다.
+    commit(fn) {
+      fn();
+      flushSync();
+    },
+  });
+}

package/packages/adapters/src/three.ts

@@ -0,0 +1,18 @@
+import { onSeek } from "./page.ts";
+
+interface RendererLike {
+  render(scene: unknown, camera: unknown): void;
+}
+
+// three.js 장면을 seek 마다 t 로 갱신하고 한 번 그린다. setAnimationLoop 대신 이걸 쓴다.
+export function bindThree<S, C>(o: {
+  renderer: RendererLike;
+  scene: S;
+  camera: C;
+  update?(t: number, scene: S, camera: C): void;
+}): () => void {
+  return onSeek((t) => {
+    o.update?.(t, o.scene, o.camera);
+    o.renderer.render(o.scene, o.camera);
+  });
+}

package/packages/adapters/src/vue.ts

@@ -0,0 +1,27 @@
+import { createApp, h, nextTick, onBeforeUnmount, shallowRef, type Component, type ShallowRef } from "vue";
+import { frameTime, onFrame } from "@kasaframe/core";
+import { definePage, type KfPage, type PageOptions } from "./page.ts";
+
+// 컴포넌트 안에서 영상 시각(초)을 읽는다. 다른 부품들과 같은 core 시각 저장소를 본다.
+export function useTime(): ShallowRef<number> {
+  const t = shallowRef(frameTime());
+  const off = onFrame((v) => (t.value = v));
+  onBeforeUnmount(off);
+  return t;
+}
+
+// 루트 컴포넌트는 props 로 t 를 받는다. Vue 는 갱신을 마이크로태스크로 미루므로 nextTick 까지 기다려 찍는다.
+export function renderVue(
+  root: Component,
+  o: Omit<PageOptions, "render" | "commit"> & { container: HTMLElement },
+): KfPage {
+  const t = shallowRef(0);
+  createApp({ render: () => h(root, { t: t.value }) }).mount(o.container);
+  return definePage({
+    ...o,
+    async render(at) {
+      t.value = at;
+      await nextTick();
+    },
+  });
+}

package/packages/check/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@kasaframe/check",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5"
+  },
+  "dependencies": {
+    "@kasaframe/cli": "*",
+    "@kasaframe/clock": "*",
+    "@kasaframe/core": "*",
+    "playwright": "^1.64.0",
+    "pngjs": "^7.0.0"
+  }
+}