kasaframe 0.0.0-stage → 0.1.1

package/packages/clock/src/index.ts

@@ -0,0 +1,25 @@
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+import type { ClockOptions } from "./types.ts";
+
+export type { ClockOptions, KfClock } from "./types.ts";
+
+let bundled: Promise<string> | null = null;
+
+function bundle(): Promise<string> {
+  bundled ??= build({
+    entryPoints: [fileURLToPath(new URL("./install.ts", import.meta.url))],
+    bundle: true,
+    write: false,
+    format: "iife",
+    globalName: "__kfClockModule",
+    target: "es2022",
+    minify: true,
+  }).then((r) => r.outputFiles[0].text);
+  return bundled;
+}
+
+// page.addInitScript({ content }) 로 넣는 문자열. 페이지 스크립트보다 먼저 돌아 window.__kfClock 을 건다.
+export async function clockScript(opts: ClockOptions = {}): Promise<string> {
+  return `${await bundle()}\n__kfClockModule.installClock(${JSON.stringify(opts)});`;
+}

package/packages/clock/src/install.ts

@@ -0,0 +1,351 @@
+// 브라우저 안에서 돈다. 렌더러가 addInitScript 로 페이지 스크립트보다 먼저 넣는다.
+import type { ClockOptions, KfClock } from "./types.ts";
+export type { ClockOptions, KfClock };
+
+type TimerFn = (...args: unknown[]) => void;
+interface Timer {
+  id: number;
+  due: number;
+  seq: number;
+  fn: TimerFn;
+  args: unknown[];
+  interval: number | null;
+}
+
+const DEFAULT_EPOCH = Date.UTC(2026, 0, 1);
+
+export function installClock(opts: ClockOptions = {}): KfClock {
+  const w = window as unknown as Window & { __kfClock?: KfClock };
+  if (w.__kfClock) return w.__kfClock;
+
+  const real = {
+    setTimeout: window.setTimeout.bind(window),
+    clearTimeout: window.clearTimeout.bind(window),
+    setInterval: window.setInterval.bind(window),
+    clearInterval: window.clearInterval.bind(window),
+    requestAnimationFrame: window.requestAnimationFrame.bind(window),
+    cancelAnimationFrame: window.cancelAnimationFrame.bind(window),
+    performanceNow: performance.now.bind(performance),
+    Date,
+    random: Math.random,
+  };
+
+  const epoch = opts.epoch ?? DEFAULT_EPOCH;
+  let fps = opts.fps ?? 60;
+  let mode: "seek" | "step" = opts.mode ?? "step";
+  let now = 0;
+  let lastFrame = -1;
+  let seq = 0;
+  // 진짜 타이머 번호와 겹치지 않게 큰 수에서 시작한다 — clearTimeout 이 둘을 가려야 한다.
+  let nextTimerId = 1_000_000_000;
+  let nextRafId = 1;
+  const timers = new Map<number, Timer>();
+  let rafQueue: { id: number; cb: FrameRequestCallback }[] = [];
+  const born = new WeakMap<Animation, number>();
+  const seenAt = new WeakMap<Animation, number>();
+
+  // 같은 페이지를 두 탭에서 찍어도 같은 난수가 나와야 구간 이음매가 맞는다. 한 줄기를 이어 쓰면 탭마다 찍는 차례(앞 프레임에서 몇 번
+  // 뽑았나)에 따라 값이 달라진다 — 프레임마다 그 번호로 다시 씨를 뿌려, 같은 프레임은 어느 탭·어느 차례로 찍어도 같은 수열을 받는다
+  const base = (opts.seed ?? 0x6b66) >>> 0;
+  let s = base;
+  const reseed = (f: number) => {
+    s = (Math.imul(base ^ 0x9e3779b9, 0x85ebca6b) + Math.imul(f + 1, 0xc2b2ae35)) >>> 0;
+  };
+  if (opts.seedRandom !== false) {
+    Math.random = () => {
+      s = (s + 0x6d2b79f5) >>> 0;
+      let t = s;
+      t = Math.imul(t ^ (t >>> 15), t | 1);
+      t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  // 크롬은 그림(이미지·ImageBitmap)을 처음 drawImage 할 때 다음부터와 다르게 래스터한다(스프라이트 가장자리에서 최대 78/255).
+  // 탭마다 처음 그리는 프레임이 달라 이음매·「같은 프레임 두 번」이 갈린다 — 그리기 소스마다 처음 한 번은 작은 판에 네 배율로 먼저 그려 둔다
+  if (opts.warmImages !== false) {
+    const warmed = new WeakSet<object>();
+    let pad: CanvasRenderingContext2D | null = null;
+    for (const proto of [window.CanvasRenderingContext2D?.prototype, (window as any).OffscreenCanvasRenderingContext2D?.prototype]) {
+      if (!proto) continue;
+      const draw = proto.drawImage as (...a: unknown[]) => void;
+      proto.drawImage = function (this: unknown, src: CanvasImageSource, ...rest: unknown[]) {
+        if (src && typeof src === "object" && !warmed.has(src) && !(src instanceof HTMLVideoElement) && !(src instanceof HTMLCanvasElement)) {
+          warmed.add(src);
+          pad ??= Object.assign(document.createElement("canvas"), { width: 512, height: 512 }).getContext("2d");
+          const w = (src as HTMLImageElement).naturalWidth || (src as { width?: number }).width || 0;
+          const h = (src as HTMLImageElement).naturalHeight || (src as { height?: number }).height || 0;
+          if (pad && w > 0 && h > 0) {
+            for (const k of [1, 0.5, 0.25, 2]) {
+              try {
+                draw.call(pad, src, 0, 0, Math.min(512, w * k), Math.min(512, h * k));
+              } catch {}
+            }
+            pad.clearRect(0, 0, 512, 512);
+          }
+        }
+        return draw.call(this, src, ...rest);
+      } as typeof proto.drawImage;
+    }
+  }
+
+  function addTimer(fn: unknown, delay: unknown, args: unknown[], repeat: boolean): number {
+    const f: TimerFn =
+      typeof fn === "function" ? (fn as TimerFn) : () => (0, eval)(String(fn));
+    const d = Math.max(0, Number(delay) || 0);
+    const id = nextTimerId++;
+    timers.set(id, {
+      id,
+      due: now + d,
+      seq: seq++,
+      fn: f,
+      args,
+      // setInterval(fn, 0) 이 한 시각에서 끝없이 돌지 않게 최소 1ms.
+      interval: repeat ? Math.max(1, d) : null,
+    });
+    return id;
+  }
+
+  function clearTimer(id: unknown, realClear: (id: number) => void) {
+    const n = Number(id);
+    if (timers.has(n)) timers.delete(n);
+    else if (Number.isFinite(n)) realClear(n);
+  }
+
+  window.setTimeout = ((fn: unknown, delay?: unknown, ...args: unknown[]) =>
+    addTimer(fn, delay, args, false)) as typeof window.setTimeout;
+  window.setInterval = ((fn: unknown, delay?: unknown, ...args: unknown[]) =>
+    addTimer(fn, delay, args, true)) as typeof window.setInterval;
+  window.clearTimeout = ((id?: number) => clearTimer(id, real.clearTimeout)) as typeof window.clearTimeout;
+  window.clearInterval = ((id?: number) => clearTimer(id, real.clearInterval)) as typeof window.clearInterval;
+
+  window.requestAnimationFrame = (cb: FrameRequestCallback) => {
+    const id = nextRafId++;
+    rafQueue.push({ id, cb });
+    return id;
+  };
+  window.cancelAnimationFrame = (id: number) => {
+    rafQueue = rafQueue.filter((r) => r.id !== id);
+  };
+
+  if ("requestIdleCallback" in window) {
+    window.requestIdleCallback = ((cb: IdleRequestCallback) =>
+      addTimer(() => cb({ didTimeout: false, timeRemaining: () => 50 }), 1, [], false)) as typeof window.requestIdleCallback;
+    window.cancelIdleCallback = ((id: number) => clearTimer(id, () => {})) as typeof window.cancelIdleCallback;
+  }
+
+  Object.defineProperty(performance, "now", { configurable: true, value: () => now });
+
+  const RealDate = real.Date;
+  function VirtualDate(this: unknown, ...args: unknown[]) {
+    if (!new.target) return new RealDate(epoch + now).toString();
+    return Reflect.construct(RealDate, args.length ? args : [epoch + now], new.target);
+  }
+  VirtualDate.prototype = RealDate.prototype;
+  Object.setPrototypeOf(VirtualDate, RealDate);
+  VirtualDate.now = () => epoch + now;
+  VirtualDate.parse = RealDate.parse;
+  VirtualDate.UTC = RealDate.UTC;
+  Object.defineProperty(window, "Date", { configurable: true, writable: true, value: VirtualDate });
+
+  function nextDueTimer(limit: number): Timer | null {
+    let best: Timer | null = null;
+    for (const t of timers.values()) {
+      if (t.due > limit) continue;
+      if (!best || t.due < best.due || (t.due === best.due && t.seq < best.seq)) best = t;
+    }
+    return best;
+  }
+
+  // MessageChannel 은 가상화하지 않았다 — React 스케줄러가 여기로 일을 넘기므로 진짜 태스크를 한 번 내줘야 커밋된다.
+  const channel = new MessageChannel();
+  const waiting: (() => void)[] = [];
+  channel.port1.onmessage = () => waiting.shift()?.();
+  function macrotask(): Promise<void> {
+    return new Promise((resolve) => {
+      waiting.push(resolve);
+      channel.port2.postMessage(0);
+    });
+  }
+
+  async function runTimersUntil(limit: number) {
+    let guard = 0;
+    for (;;) {
+      const t = nextDueTimer(limit);
+      if (!t) return;
+      if (++guard > 100_000) {
+        console.warn("[kf clock] 한 구간에서 타이머가 10만 번 넘게 돌아 멈춘다");
+        return;
+      }
+      now = Math.max(now, t.due);
+      if (t.interval === null) timers.delete(t.id);
+      else {
+        t.due += t.interval;
+        t.seq = seq++;
+      }
+      try {
+        t.fn(...t.args);
+      } catch (err) {
+        console.error(err);
+      }
+      adoptAnimations();
+      await macrotask();
+    }
+  }
+
+  function runFrame() {
+    const queue = rafQueue;
+    rafQueue = [];
+    for (const r of queue) {
+      try {
+        r.cb(now);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+
+  function trackable(a: Animation): boolean {
+    return a.timeline === document.timeline || a.timeline === null;
+  }
+
+  // seek 모드는 화면이 t 의 순수 함수여야 해서, 언제 처음 봤든 0 초에 시작한 것으로 본다(탭마다 seek 순서가 달라도 같은 그림).
+  // step 모드는 0 부터 차례로 돌므로 처음 본 가상 시각이 곧 시작 시각이다.
+  const bornAt = () => (mode === "seek" ? 0 : now);
+
+  function adoptAnimations() {
+    for (const a of document.getAnimations()) {
+      if (born.has(a) || !trackable(a)) continue;
+      born.set(a, bornAt());
+      a.pause();
+    }
+  }
+
+  // CSS 가 animation-play-state: paused 로 세운 것은 우리가 pause() 한 것과 구별이 안 되니 계산값을 직접 본다.
+  function cssPaused(a: Animation): boolean {
+    if (typeof CSSAnimation === "undefined" || !(a instanceof CSSAnimation)) return false;
+    const effect = a.effect as KeyframeEffect | null;
+    if (!effect?.target) return false;
+    const cs = getComputedStyle(effect.target, effect.pseudoElement ?? null);
+    const names = cs.animationName.split(",").map((x) => x.trim());
+    const states = cs.animationPlayState.split(",").map((x) => x.trim());
+    const i = Math.max(0, names.indexOf(a.animationName));
+    return (states[i % states.length] ?? states[0]) === "paused";
+  }
+
+  function syncAnimations() {
+    for (const a of document.getAnimations()) {
+      if (!trackable(a)) continue;
+      if (!born.has(a)) born.set(a, bornAt());
+      const last = seenAt.get(a) ?? now;
+      seenAt.set(a, now);
+      if (cssPaused(a)) {
+        // 멈춘 동안 흐른 시간만큼 시작 시각을 미뤄, 다시 돌 때 멈춘 자리에서 잇는다.
+        if (mode === "step") born.set(a, born.get(a)! + (now - last));
+        if (a.playState !== "paused") a.pause();
+        continue;
+      }
+      const local = (now - born.get(a)!) * (a.playbackRate || 1);
+      const end = Number(a.effect?.getComputedTiming().endTime ?? Infinity);
+      if (Number.isFinite(end) && local >= end) {
+        if (a.playState !== "finished") a.finish();
+      } else {
+        if (a.playState !== "paused") a.pause();
+        a.currentTime = Math.max(0, local);
+      }
+    }
+  }
+
+  const mutated = { n: 0 };
+  new MutationObserver((records) => {
+    mutated.n += records.length;
+  }).observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+
+  async function settle() {
+    await macrotask();
+    for (let round = 0; round < 20; round++) {
+      mutated.n = 0;
+      await macrotask();
+      adoptAnimations();
+      if (mutated.n === 0) break;
+    }
+    syncAnimations();
+    // 막 생긴 애니메이션은 합성기와 시작을 맞추는 동안 pending 이다. 그 사이에 찍으면 첫 프레임이 들쭉날쭉하다.
+    const starting = document.getAnimations().filter((a) => a.pending);
+    if (starting.length) {
+      await Promise.race([
+        Promise.allSettled(starting.map((a) => a.ready)),
+        new Promise((r) => real.setTimeout(r, 500)),
+      ]);
+    }
+    const pending = Array.from(document.images).filter((img) => !img.complete && img.src);
+    if (pending.length) {
+      await Promise.race([
+        Promise.allSettled(pending.map((img) => img.decode())),
+        new Promise((r) => real.setTimeout(r, 3000)),
+      ]);
+    }
+  }
+
+  function frameOf(ms: number): number {
+    const f = (ms * fps) / 1000;
+    const r = Math.round(f);
+    return Math.abs(f - r) < 1e-6 ? r : Math.floor(f);
+  }
+
+  const clock: KfClock = {
+    virtual: true,
+    get fps() {
+      return fps;
+    },
+    set fps(v: number) {
+      fps = v;
+    },
+    get mode() {
+      return mode;
+    },
+    set mode(v: "seek" | "step") {
+      mode = v;
+    },
+    now: () => now,
+    frame: () => lastFrame,
+    async advanceTo(ms: number, onFrame?: (ms: number) => void | Promise<void>) {
+      if (ms < now - 1e-6) {
+        throw new Error(`[kf clock] step 모드는 뒤로 못 간다 (${now}ms → ${ms}ms) — 페이지를 다시 열어라`);
+      }
+      const target = frameOf(ms);
+      // 찍지 않는 프레임(pre-roll)도 찍는 프레임과 똑같이 끝까지 가라앉힌다 — 그래야 탭마다 구간을 나눠도 이음매가 같다.
+      for (let f = lastFrame + 1; f <= target; f++) {
+        // 프레임 시각은 어디서나 (f / fps) 한 가지로 센다. f * (1000 / fps) 와 끝자리가 달라 장면 경계 비교가 한 프레임 갈린다.
+        const at = (f / fps) * 1000;
+        reseed(f);
+        await runTimersUntil(at);
+        now = at;
+        lastFrame = f;
+        runFrame();
+        syncAnimations();
+        await onFrame?.(at);
+        await settle();
+      }
+      if (ms > now) {
+        await runTimersUntil(ms);
+        now = ms;
+        await settle();
+      }
+    },
+    async jumpTo(ms: number) {
+      reseed(frameOf(ms));
+      if (ms >= now) await runTimersUntil(ms);
+      now = ms;
+      lastFrame = frameOf(ms);
+      runFrame();
+      await settle();
+    },
+    settle,
+    syncAnimations,
+    pending: () => ({ timers: timers.size, raf: rafQueue.length }),
+    real,
+  };
+  w.__kfClock = clock;
+  return clock;
+}

package/packages/clock/src/types.ts

@@ -0,0 +1,45 @@
+export interface ClockOptions {
+  fps?: number;
+  mode?: "seek" | "step";
+  // Date.now() 가 가상 0ms 에 돌려줄 값. 탭마다 같아야 해서 고정한다.
+  epoch?: number;
+  // Math.random 을 프레임마다 그 번호로 다시 씨 뿌린다(기본 켬)
+  seedRandom?: boolean;
+  seed?: number;
+  // 그림을 처음 drawImage 하기 전에 작은 판에 네 배율로 먼저 그려 첫 래스터 차를 없앤다(기본 켬)
+  warmImages?: boolean;
+}
+
+export interface KfClock {
+  readonly virtual: true;
+  fps: number;
+  // 페이지 계약의 mode. definePage 가 맞춘다. CSS 애니메이션 시작 시각을 정하는 데 쓴다.
+  mode: "seek" | "step";
+  now(): number;
+  frame(): number;
+  // step: 지금부터 ms 까지 프레임마다 타이머·rAF·애니메이션을 시각 순서대로 돌리고 화면이 다 그려진 뒤 resolve.
+  // onFrame 은 프레임마다 rAF 뒤에 불린다 — 페이지가 그 프레임 시각으로 그리는 자리.
+  advanceTo(ms: number, onFrame?: (ms: number) => void | Promise<void>): Promise<void>;
+  // seek: 중간 프레임 없이 그 시각으로 옮긴다. 뒤로도 간다.
+  jumpTo(ms: number): Promise<void>;
+  settle(): Promise<void>;
+  syncAnimations(): void;
+  pending(): { timers: number; raf: number };
+  real: {
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    setInterval: typeof setInterval;
+    clearInterval: typeof clearInterval;
+    requestAnimationFrame: typeof requestAnimationFrame;
+    cancelAnimationFrame: typeof cancelAnimationFrame;
+    performanceNow: () => number;
+    Date: DateConstructor;
+    random: () => number;
+  };
+}
+
+declare global {
+  interface Window {
+    __kfClock?: KfClock;
+  }
+}

package/packages/core/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@kasaframe/core",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}