kasaframe 0.0.0-stage → 0.1.1

package/packages/cli/src/commands/still.ts

@@ -0,0 +1,40 @@
+import { writeFileSync } from "node:fs";
+import type { Command } from "../command.ts";
+import { num, parseFlags } from "../command.ts";
+import { openSession } from "../browser.ts";
+import { fmtTime, outPath } from "../out.ts";
+import { blurOpts, captureBlurred, rgbaToPng } from "../blur.ts";
+
+const cmd: Command = {
+  summary: "한 시각을 PNG 한 장으로",
+  usage: `kf still <폴더> --t <초> [--out 파일.png]
+  --t       찍을 시각(초). --frame N 으로 프레임 번호를 줘도 된다
+  --out     기본 <폴더>/out/still-<t>.png
+  --motion-blur N --shutter 180  렌더와 같은 모션 블러(하위 프레임 N 장 평균)로 한 장
+step 모드 페이지는 0 초부터 그 시각까지 돌린 뒤 찍는다.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const dir = args[0];
+    if (!dir) {
+      console.error("kf still: 폴더를 줘라 — kf still <폴더> --t 12.3");
+      return 2;
+    }
+    const s = await openSession(dir);
+    try {
+      const { fps } = s.info.meta;
+      const t = opts.frame !== undefined ? num(opts.frame, 0) / fps : num(opts.t, 0);
+      const file = outPath(dir, opts.out, `still-${fmtTime(t)}.png`);
+      const blur = blurOpts(opts);
+      if (blur && s.info.mode === "seek") writeFileSync(file, rgbaToPng(await captureBlurred(s.first, s.info, t, blur)));
+      else {
+        await s.first.seek(t);
+        writeFileSync(file, await s.first.capture());
+      }
+      console.log(file);
+      return 0;
+    } finally {
+      await s.close();
+    }
+  },
+};
+export default cmd;

package/packages/cli/src/commands/theme.ts

@@ -0,0 +1,85 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { listThemes, themesDir } from "@kasaframe/themes";
+import { briefs, review, scaffold, sessionPrompt, setStatus, staticCheck } from "@kasaframe/themes/factory";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const kfBin = new URL("../kf.ts", import.meta.url).pathname;
+
+const cmd: Command = {
+  summary: "테마 공장 — 참고 자료로 테마 팩 뼈대·지시서, 계약 검사, 견본 review, 사람 OK 뒤 approve",
+  usage: `kf theme list
+kf theme new <id> --ref <그림·영상·폴더·URL> [--ref …] [--name 이름] [--like <기존 테마>] [--3d] [--brief ${briefs().join("|")}] [--force]
+kf theme check <id> [--no-page]     계약·빈칸 검사 + kf check sample
+kf theme review <id> [--tabs 2]     굽기 → mp4 검사 → 장면 모음·대표 장면 → 공유 폴더 → status review
+kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
+
+  new 는 themes/<id>/ 에 계약 파일 뼈대·refs/·브리프대로 자른 곡과 박·장면 넷 뼈대·THEME-MAKE.md(지시서)를 짓고,
+  그 지시서를 받을 세션을 여는 명령을 알려 준다. 테마는 그 세션이 만든다.`,
+  async run(argv) {
+    const [sub, ...rest] = argv;
+    const { args, opts } = parseFlags(rest);
+    const id = args[0];
+    if (sub === "list" || !sub) {
+      const all = listThemes();
+      if (!all.length) console.log("(테마 없음)");
+      for (const t of all) console.log(`${t.id.padEnd(18)} ${t.status.padEnd(9)} ${String(t.approvedAt ?? "").padEnd(11)} 효과 ${String(t.effects.length).padStart(2)} · ${t.metaphor}`);
+      return 0;
+    }
+    if (!id) {
+      console.error(`kf theme ${sub}: 테마 id 가 필요하다. kf theme --help`);
+      return 2;
+    }
+    if (sub === "new") {
+      // --ref 는 여러 번 — parseFlags 는 마지막 하나만 남기니 따로 모은다
+      const refs = rest.flatMap((a, i) => (a === "--ref" && rest[i + 1] ? [rest[i + 1]] : a.startsWith("--ref=") ? [a.slice(6)] : []));
+      try {
+        const r = scaffold(id, {
+          refs,
+          name: typeof opts.name === "string" ? opts.name : undefined,
+          like: typeof opts.like === "string" ? opts.like : undefined,
+          brief: typeof opts.brief === "string" ? opts.brief : undefined,
+          kind: opts["3d"] ? "3d" : "flat",
+          force: !!opts.force,
+        });
+        console.log(`${r.dir}/ — 참고 자료 ${r.refs.length}개${r.urls.length ? ` · 주소 ${r.urls.length}개` : ""}`);
+        console.log(`지시서: ${r.make}`);
+        console.log(`\n세션 열기(레포 뿌리에서):\n  claude --model opus "${sessionPrompt(id)}"`);
+        return 0;
+      } catch (e) {
+        console.error(`kf theme new: ${(e as Error).message}`);
+        return 2;
+      }
+    }
+    if (sub === "check") {
+      const bad = await staticCheck(id);
+      for (const b of bad) console.log(`[오류] ${b}`);
+      if (!bad.length) console.log("계약·빈칸: 통과");
+      let page = 0;
+      if (!opts["no-page"]) page = spawnSync(process.execPath, [kfBin, "check", join(themesDir, id, "sample"), "--tabs", String(num(opts.tabs, 2))], { stdio: "inherit" }).status ?? 1;
+      return bad.length || page ? 1 : 0;
+    }
+    if (sub === "review") {
+      const bad = await staticCheck(id);
+      if (bad.length) {
+        for (const b of bad) console.log(`[오류] ${b}`);
+        console.error("kf theme review: 계약·빈칸 오류부터 — kf theme check");
+        return 1;
+      }
+      const r = review(id, { tabs: num(opts.tabs, 2), brief: typeof opts.brief === "string" ? opts.brief : undefined });
+      for (const n of r.notes) console.log(n);
+      if (!r.ok) return 1;
+      console.log(`status review · 공유 폴더 ${r.share}`);
+      return 0;
+    }
+    if (sub === "approve") {
+      const m = setStatus(id, "approved");
+      console.log(`${id} approved ${m.approvedAt} — 사람이 견본을 보고 OK 한 테마만`);
+      return 0;
+    }
+    console.error(`kf theme: 모르는 하위 명령 "${sub}". kf theme --help`);
+    return 2;
+  },
+};
+
+export default cmd;

package/packages/cli/src/commands/transitions.ts

@@ -0,0 +1,40 @@
+import type { Command } from "../command.ts";
+import { parseFlags } from "../command.ts";
+import { CATALOG, type TransitionEntry } from "@kasaframe/motion/transitions2d";
+
+const USE: Record<TransitionEntry["use"], string> = { transition3d: "이름으로", react: "React 부품", vendor: "원본만" };
+
+const cmd: Command = {
+  summary: "전환 목록 — 이름·출처·라이선스·seek/step",
+  usage: `kf transitions [찾을 말] [--source 출처] [--clock seek|step] [--use transition3d|react|vendor] [--json]
+  이름으로(transition3d) 인 것은 장면에서 transition3d(root, ctx, { kind: "<이름>" }) 로 부른다 — 예 gl:crosswarp · smooth:sdf-circle · dive
+  React 부품은 @kasaframe/motion/transitions2d/react, 원본만은 geono-hub vendor/transitions/ 에 있다
+  step 은 자기 시계(rAF·타이머)라 kf.json 의 mode 를 "step" 으로`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const has = (v: string, q: unknown) => typeof q !== "string" || v.toLowerCase().includes(q.toLowerCase());
+    const list = CATALOG.filter(
+      (e) =>
+        has(e.source, opts.source) &&
+        (typeof opts.clock !== "string" || e.clock === opts.clock) &&
+        (typeof opts.use !== "string" || e.use === opts.use) &&
+        args.every((q) => has(`${e.name} ${e.note ?? ""} ${e.author ?? ""}`, q)),
+    );
+    if (opts.json) {
+      console.log(JSON.stringify(list, null, 2));
+      return 0;
+    }
+    const count = (k: (e: TransitionEntry) => string) => [...list.reduce((m, e) => m.set(k(e), (m.get(k(e)) ?? 0) + 1), new Map<string, number>())].map(([k, n]) => `${k} ${n}`).join(" · ");
+    console.log(`${list.length}개 — ${count((e) => e.source)}`);
+    console.log(`시계 ${count((e) => e.clock)} · ${count((e) => USE[e.use])}\n`);
+    const w = Math.max(...list.map((e) => e.name.length), 4) + 2;
+    const sw = Math.max(...list.map((e) => e.source.length), 4) + 2;
+    const lw = Math.max(...list.map((e) => e.license.length), 4) + 2;
+    for (const e of list) {
+      const extra = [e.component && `<${e.component}>`, e.author, e.note].filter(Boolean).join(" — ");
+      console.log(`${e.name.padEnd(w)}${e.source.padEnd(sw)}${e.license.padEnd(lw)}${e.clock.padEnd(6)}${USE[e.use].padEnd(9)}${extra}`);
+    }
+    return 0;
+  },
+};
+export default cmd;

package/packages/cli/src/deps.ts

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hasKey, whereToPut } from "@kasaframe/gen";
+import { jizuraCheck } from "@kasaframe/jizura/install";
+import { launch } from "./browser.ts";
+import { lyricsCheck } from "./commands/lyrics.ts";
+
+// kf doctor·kf setup 이 같이 보는 바깥 도구들 — npm 이 못 까는 것(ffmpeg·파이썬 꾸러미·크롬 본체)만.
+
+export const requirements = fileURLToPath(new URL("../../../tools/beats/requirements.txt", import.meta.url));
+// 요즘 파이썬(Homebrew·데비안)은 시스템에 pip 설치를 막는다(PEP 668) — kf setup 은 쓰임마다 venv 를 따로 둔다
+export const pyVenv = (name: string): string => join(homedir(), ".cache", "kasaframe", "py", name);
+export const venvPython = (dir: string): string => join(dir, platform() === "win32" ? "Scripts/python.exe" : "bin/python");
+export const beatsVenv = pyVenv("beats");
+
+export function python(): string {
+  return process.env.KF_PYTHON ?? (existsSync(venvPython(beatsVenv)) ? venvPython(beatsVenv) : "python3");
+}
+
+// npx playwright 는 다른 판의 playwright 를 집을 수 있다 — 크롬 판이 이 패키지가 쓰는 playwright 와 맞아야 뜬다
+export const playwrightCli = (): string => join(dirname(createRequire(import.meta.url).resolve("playwright/package.json")), "cli.js");
+
+export interface Check {
+  name: string;
+  ok: boolean;
+  /** 없으면 렌더가 안 된다 */
+  required: boolean;
+  detail: string;
+  fix?: string;
+}
+
+const run = (cmd: string, args: string[]) => spawnSync(cmd, args, { encoding: "utf8" });
+
+function installHint(pkg: { brew: string; apt: string; url: string }): string {
+  if (platform() === "darwin") return `brew install ${pkg.brew}`;
+  if (platform() === "linux") return `sudo apt-get install -y ${pkg.apt}  (데비안·우분투 — 다른 배포판은 그 패키지 관리자로)`;
+  return pkg.url;
+}
+
+function node(): Check {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const ok = major > 22 || (major === 22 && minor >= 18);
+  return { name: "Node 22.18 이상", ok, required: true, detail: process.version, fix: ok ? undefined : "https://nodejs.org 에서 22 LTS 이상" };
+}
+
+function ffmpeg(): Check {
+  const r = run("ffmpeg", ["-hide_banner", "-version"]);
+  const p = run("ffprobe", ["-hide_banner", "-version"]);
+  const ok = r.status === 0 && p.status === 0;
+  return {
+    name: "ffmpeg·ffprobe",
+    ok,
+    required: true,
+    detail: ok ? (/version (\S+)/.exec(r.stdout)?.[1] ?? "있음") : "없음 — MP4 로 굽기·검사에 쓴다",
+    fix: ok ? undefined : installHint({ brew: "ffmpeg", apt: "ffmpeg", url: "https://ffmpeg.org/download.html" }),
+  };
+}
+
+async function chrome(): Promise<Check> {
+  try {
+    const b = await launch();
+    const v = b.version();
+    await b.close();
+    return { name: "크롬(Playwright)", ok: true, required: true, detail: v };
+  } catch (err) {
+    const first = String(err instanceof Error ? err.message : err).split("\n")[0];
+    return { name: "크롬(Playwright)", ok: false, required: true, detail: `못 띄웠다 — ${first.slice(0, 120)}`, fix: `kf setup chrome  (같은 일: node ${playwrightCli()} install chromium${platform() === "linux" ? " · 리눅스는 sudo 로 install-deps chromium 도" : ""})` };
+  }
+}
+
+function librosa(): Check {
+  const py = python();
+  const r = run(py, ["-c", "import librosa; print(librosa.__version__)"]);
+  const ok = r.status === 0;
+  return {
+    name: "python3 + librosa",
+    ok,
+    required: false,
+    detail: ok ? `${py} · librosa ${r.stdout.trim()}` : `${py} 에 없다 — 곡에 박자를 맞출 때(kf beats·--music)만 쓴다`,
+    fix: ok ? undefined : `kf setup beats  (같은 일: python3 -m venv ${beatsVenv} && ${venvPython(beatsVenv)} -m pip install -r ${requirements})`,
+  };
+}
+
+function ogKey(): Check {
+  const ok = hasKey("opengateway");
+  return {
+    name: "OG 키",
+    ok,
+    required: false,
+    detail: ok ? "있음 — 그림 생성(kf gen)·kf make OG 모드" : "없음 — 그림 생성(kf gen)과 kf make OG 모드만 못 쓴다. 장면·렌더·검사는 키 없이 돈다",
+    fix: ok ? undefined : whereToPut("opengateway"),
+  };
+}
+
+// 글꼴은 CDN(jsdelivr)에서 받지만, 망이 막힌 리눅스 상자에서는 한글이 두부로 나온다
+function koreanFont(): Check | null {
+  if (platform() !== "linux") return null;
+  const r = run("fc-list", [":lang=ko", "family"]);
+  const ok = r.status === 0 && r.stdout.trim().length > 0;
+  return { name: "한글 글꼴", ok, required: false, detail: ok ? r.stdout.trim().split("\n")[0] : "없음 — 글꼴 CDN 이 막히면 한글이 두부로 나온다", fix: ok ? undefined : "sudo apt-get install -y fonts-noto-cjk" };
+}
+
+// 점검을 더할 땐 여기 한 줄 — kf doctor 와 kf setup 끝 표가 같이 쓴다
+export async function checks(): Promise<Check[]> {
+  return [node(), ffmpeg(), await chrome(), librosa(), jizuraCheck(), lyricsCheck(), ogKey(), koreanFont()].filter((c): c is Check => c !== null);
+}
+
+// 한글은 터미널에서 두 칸을 먹는다 — padEnd 로는 열이 어긋난다
+const cols = (s: string) => [...s].reduce((n, ch) => n + (/[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af]/.test(ch) ? 2 : 1), 0);
+const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - cols(s)));
+
+export function report(list: Check[]): void {
+  const w = Math.max(...list.map((c) => cols(c.name))) + 2;
+  for (const c of list) {
+    console.log(`  ${pad(c.ok ? "ok" : c.required ? "없음" : "선택", 4)}  ${pad(c.name, w)}${c.detail}`);
+    if (c.fix) console.log(`  ${pad("", 4 + 2 + w)}→ ${c.fix}`);
+  }
+}

package/packages/cli/src/ffmpeg.ts

@@ -0,0 +1,81 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+
+export type VideoFormat = "h264" | "prores";
+
+export interface Encoder {
+  /** PNG, raw 로 만들었으면 RGBA 날것 */
+  write(frame: Buffer): Promise<void>;
+  end(): Promise<void>;
+}
+
+function run(args: string[], label: string): { proc: ChildProcess; done: Promise<void> } {
+  const proc = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...args], {
+    stdio: ["pipe", "ignore", "pipe"],
+  });
+  let err = "";
+  proc.stderr!.on("data", (d) => (err += d));
+  const done = new Promise<void>((resolve, reject) => {
+    proc.on("error", (e) => reject(new Error(`${label}: ffmpeg 를 못 띄웠다 (${e.message})`)));
+    proc.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`${label}: ffmpeg 종료 ${code}\n${err.trim()}`))));
+  });
+  return { proc, done };
+}
+
+// RGB→YUV 를 BT.709 로 바꾸고 그렇다고 적는다. 안 적으면 ffmpeg 는 BT.601 로 바꾸는데 브라우저·유튜브는 HD 를 709 로 풀어
+// 색이 어긋난다(#20C040 이 (20,168,61) 로 — 초록이 눌린다)
+const BT709 = ["-vf", "scale=out_color_matrix=bt709:out_range=tv,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"];
+
+const CODEC: Record<VideoFormat, string[]> = {
+  h264: ["-c:v", "libx264", "-preset", "medium", "-crf", "16", "-pix_fmt", "yuv420p", ...BT709, "-movflags", "+faststart"],
+  prores: ["-c:v", "prores_ks", "-profile:v", "3", "-pix_fmt", "yuv422p10le", ...BT709, "-vendor", "apl0"],
+};
+
+// PNG(또는 raw 를 주면 RGBA 날것 — 모션 블러가 평균한 프레임)를 stdin 으로 흘려 구간 파일 하나를 만든다. 쓰기가 밀리면 기다려 메모리가 차지 않게 한다.
+export function encoder(out: string, fps: number, format: VideoFormat, crf?: number, raw?: { width: number; height: number }): Encoder {
+  const codec = [...CODEC[format]];
+  if (crf !== undefined && format === "h264") codec[codec.indexOf("-crf") + 1] = String(crf);
+  const input = raw
+    ? ["-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${raw.width}x${raw.height}`, "-framerate", String(fps), "-i", "-"]
+    : ["-f", "image2pipe", "-framerate", String(fps), "-c:v", "png", "-i", "-"];
+  const { proc, done } = run([...input, ...codec, "-r", String(fps), out], out);
+  const stdin = proc.stdin!;
+  let failed: Error | null = null;
+  done.catch((e) => (failed = e));
+  return {
+    async write(frame) {
+      if (failed) throw failed;
+      if (!stdin.write(frame)) await Promise.race([once(stdin, "drain"), done]);
+    },
+    async end() {
+      stdin.end();
+      await done;
+    },
+  };
+}
+
+// 구간들을 다시 인코딩하지 않고 잇고, 곡이 있으면 그 구간만큼 잘라 얹는다.
+export async function concat(o: {
+  list: string;
+  out: string;
+  format: VideoFormat;
+  music?: string;
+  from: number;
+  dur: number;
+}): Promise<void> {
+  const args = ["-f", "concat", "-safe", "0", "-i", o.list];
+  if (o.music) args.push("-ss", o.from.toFixed(6), "-i", o.music);
+  args.push("-map", "0:v:0");
+  if (o.music) {
+    args.push("-map", "1:a:0", ...(o.format === "prores" ? ["-c:a", "pcm_s16le"] : ["-c:a", "aac", "-b:a", "256k"]));
+    args.push("-af", `apad`, "-t", o.dur.toFixed(6));
+  }
+  args.push("-c:v", "copy");
+  // concat 이 구간 파일의 primaries·trc 태그를 떨군다 — 다시 인코딩 없이 비트스트림에 709 를 다시 적는다
+  args.push("-bsf:v", o.format === "h264" ? "h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1" : "prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709");
+  args.push("-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709");
+  if (o.format === "h264") args.push("-movflags", "+faststart");
+  args.push(o.out);
+  const { done } = run(args, o.out);
+  await done;
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,8 @@
+export type { Command, Flags } from "./command.ts";
+export { parseFlags, num } from "./command.ts";
+export { openProject, repoRoot } from "./serve.ts";
+export type { OpenProject, OpenProjectOptions } from "./serve.ts";
+export { openPage, openSession, launch, Tab } from "./browser.ts";
+export type { OpenPage, PageInfo, PageMeta, Session, SessionOptions } from "./browser.ts";
+export { blurOpts, captureBlurred, rgbaToPng, subTimes } from "./blur.ts";
+export type { BlurOpts } from "./blur.ts";

package/packages/cli/src/kf.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Command } from "./command.ts";
+
+const commandsDir = fileURLToPath(new URL("./commands/", import.meta.url));
+
+function available(): string[] {
+  return readdirSync(commandsDir)
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"))
+    .map((f) => f.slice(0, -3))
+    .sort();
+}
+
+async function load(name: string): Promise<Command> {
+  const mod = await import(new URL(`./commands/${name}.ts`, import.meta.url).href);
+  return mod.default as Command;
+}
+
+async function help(): Promise<void> {
+  console.log("kf <명령> [인자]\n");
+  for (const name of available()) {
+    const cmd = await load(name).catch(() => null);
+    console.log(`  ${name.padEnd(10)} ${cmd?.summary ?? ""}`);
+  }
+  console.log("\nkf <명령> --help 로 인자를 본다.");
+}
+
+async function main(argv: string[]): Promise<number> {
+  const [name, ...rest] = argv;
+  if (!name || name === "help" || name === "--help" || name === "-h") {
+    await help();
+    return 0;
+  }
+  if (!available().includes(name)) {
+    console.error(`kf: 모르는 명령 "${name}". 있는 명령: ${available().join(" ")}`);
+    return 2;
+  }
+  const cmd = await load(name);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(`kf ${name} — ${cmd.summary}\n\n${cmd.usage ?? ""}`.trimEnd());
+    return 0;
+  }
+  return (await cmd.run(rest)) ?? 0;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(1);
+  },
+);

package/packages/cli/src/lock.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { installed, repoRoot } from "./serve.ts";
+
+const LOCK = installed ? join(tmpdir(), "kasaframe-render-lock") : join(repoRoot, ".render-lock");
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function owner(): { pid: number; dir: string; started: string } | null {
+  try {
+    return JSON.parse(readFileSync(join(LOCK, "owner.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// 최종 렌더는 레포 전체에서 하나씩 — mkdir 이 원자적이라 먼저 만든 쪽만 이긴다.
+export async function acquireRenderLock(dir: string, waitSec: number): Promise<() => void> {
+  const until = Date.now() + waitSec * 1000;
+  let told = false;
+  for (;;) {
+    try {
+      mkdirSync(LOCK);
+      writeFileSync(join(LOCK, "owner.json"), JSON.stringify({ pid: process.pid, dir, started: new Date().toISOString() }));
+      let held = true;
+      const release = () => {
+        if (!held) return;
+        held = false;
+        if (owner()?.pid === process.pid) rmSync(LOCK, { recursive: true, force: true });
+      };
+      process.once("exit", release);
+      for (const sig of ["SIGINT", "SIGTERM"] as const) {
+        process.once(sig, () => {
+          release();
+          process.exit(130);
+        });
+      }
+      return release;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+    const o = owner();
+    // 남이 mkdir 하고 owner.json 을 쓰기 전 찰나일 수 있으니, 주인 없는 잠금은 10초 지난 것만 치운다.
+    const age = (() => {
+      try {
+        return Date.now() - statSync(LOCK).mtimeMs;
+      } catch {
+        return 0;
+      }
+    })();
+    if ((o && !alive(o.pid)) || (!o && age > 10_000)) {
+      rmSync(LOCK, { recursive: true, force: true });
+      continue;
+    }
+    if (Date.now() > until) {
+      throw new Error(`렌더 잠금을 못 얻었다 — ${o ? `pid ${o.pid} 가 ${o.dir} 를 ${o.started} 부터 굽는 중` : LOCK}`);
+    }
+    if (!told) {
+      console.error(`렌더 잠금 기다리는 중${o ? ` (pid ${o.pid}: ${o.dir})` : ""} — 최대 ${waitSec}초`);
+      told = true;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+}

package/packages/cli/src/out.ts

@@ -0,0 +1,13 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+// 결과물은 기본으로 프로젝트의 out/ 에 둔다.
+export function outPath(dir: string, given: string | boolean | undefined, fallback: string): string {
+  const p = typeof given === "string" ? resolve(given) : join(resolve(dir), "out", fallback);
+  mkdirSync(dirname(p), { recursive: true });
+  return p;
+}
+
+export function fmtTime(t: number): string {
+  return t.toFixed(3).replace(/\.?0+$/, "") || "0";
+}

package/packages/cli/src/serve.ts

@@ -0,0 +1,124 @@
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { resolve, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer, type Plugin, type ViteDevServer } from "vite";
+import { clockScript, type ClockOptions } from "@kasaframe/clock";
+import { jizuraServe } from "@kasaframe/jizura/vite";
+
+export const repoRoot = fileURLToPath(new URL("../../../", import.meta.url));
+// npm 으로 깐 패키지 안에서 도는가 — 그 자리는 쓸 수 없을 수 있어 잠금·작업실 폴더를 밖에 둔다
+export const installed = repoRoot.includes(`${sep}node_modules${sep}`);
+
+export interface OpenProjectOptions {
+  // true 면 index.html 맨 앞에 가상 시계를 넣는다. Playwright 로 열 땐 addInitScript 가 따로 넣으니 끈다.
+  clock?: boolean | ClockOptions;
+  port?: number;
+  // 미리보기처럼 저장하면 반영돼야 하는 쪽만 켠다. 렌더·검사는 끈다.
+  hmr?: boolean;
+  // 엔진 플러그인 뒤에 붙는다. 미리보기가 studio 화면을 / 에 내는 데 쓴다.
+  plugins?: Plugin[];
+}
+
+export interface OpenProject {
+  url: string;
+  dir: string;
+  server: ViteDevServer;
+  close(): Promise<void>;
+}
+
+// 레포 밖 프로젝트가 import 하는 @kasaframe/*·react 같은 맨 이름을 프로젝트에서 못 찾으면 이 레포에서 찾는다.
+function repoFallback(): Plugin {
+  const anchor = join(repoRoot, "package.json");
+  return {
+    name: "kf-repo-fallback",
+    enforce: "pre",
+    async resolveId(id, importer, opts) {
+      if (/^[./\0]/.test(id) || id.includes(":")) return null;
+      // 설치된 패키지에는 워크스페이스 링크가 없다 — Node 가 푸는 자리(레포는 링크, 패키지는 bin/hooks.mjs)로 보낸다
+      if (id.startsWith("@kasaframe/")) {
+        const file = kasaframeFile(id);
+        return file ? this.resolve(file, importer, { ...opts, skipSelf: true }) : null;
+      }
+      if (!importer || importer.startsWith(repoRoot)) return null;
+      const own = await this.resolve(id, importer, { ...opts, skipSelf: true });
+      if (own) return own;
+      return this.resolve(id, anchor, { ...opts, skipSelf: true });
+    },
+  };
+}
+
+function kasaframeFile(id: string): string | null {
+  try {
+    return fileURLToPath(import.meta.resolve(id));
+  } catch {
+    return null;
+  }
+}
+
+const kasaframePackages = (): string[] =>
+  readdirSync(join(repoRoot, "packages")).filter((p) => existsSync(join(repoRoot, "packages", p, "package.json"))).map((p) => `@kasaframe/${p}`);
+
+function browserEntries(): string[] {
+  return [
+    "packages/adapters/src/react.ts",
+    "packages/motion/src/**/*.{ts,tsx}",
+    "packages/themes/src/fx.ts",
+    "packages/themes/src/stage3d.ts",
+    "themes/*/effects.ts",
+  ].map((p) => join(repoRoot, p));
+}
+
+function injectClock(opts: ClockOptions): Plugin {
+  return {
+    name: "kf-clock",
+    async transformIndexHtml() {
+      return [{ tag: "script", children: await clockScript(opts), injectTo: "head-prepend" }];
+    },
+  };
+}
+
+export async function openProject(dir: string, o: OpenProjectOptions = {}): Promise<OpenProject> {
+  if (!existsSync(join(resolve(dir), "index.html"))) {
+    throw new Error(`${resolve(dir)} 에 index.html 이 없다 — kf new 로 만든 프로젝트 폴더를 줘라`);
+  }
+  // Vite 는 importer 를 실제 경로로 준다(/tmp → /private/tmp). 경로 비교가 어긋나지 않게 처음부터 실제 경로로.
+  const root = realpathSync(resolve(dir));
+  const plugins: Plugin[] = [repoFallback(), jizuraServe()];
+  if (o.clock) plugins.push(injectClock(o.clock === true ? {} : o.clock));
+  plugins.push(...(o.plugins ?? []));
+  const server = await createServer({
+    root,
+    configFile: existsSync(join(root, "vite.config.ts")) ? undefined : false,
+    logLevel: "warn",
+    clearScreen: false,
+    plugins,
+    esbuild: { jsx: "automatic" },
+    define: {
+      __VUE_OPTIONS_API__: "true",
+      __VUE_PROD_DEVTOOLS__: "false",
+      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: "false",
+    },
+    // 레포 밖 컴포넌트가 자기 node_modules 의 React 를 끌고 오면 훅이 깨진다 — 한 벌로 묶는다.
+    resolve: { dedupe: ["react", "react-dom"] },
+    // 렌더는 HMR 이 꺼져 있어, 실행 중에 새 의존성이 나오면 다시 묶은 판으로 갈아탈 수 없다(CJS 가 그대로 가서 named export 가 빠진다).
+    // 그래서 처음 훑을 때 packages/ 의 브라우저 쪽 소스까지 같이 훑게 한다. 이 스캔은 repoFallback 을 거쳐 레포 밖 루트에서도 풀린다.
+    // @kasaframe/* 는 미리 묶지 않고 소스 그대로 낸다 — 설치된 패키지에선 node_modules 안이라 안 빼면 따로 묶여 한 모듈이 두 벌 된다.
+    // 빼면 훑기가 그 안으로 안 들어가므로 위 진입점이 그 몫을 한다.
+    optimizeDeps: {
+      entries: ["**/*.html", ...browserEntries()],
+      exclude: kasaframePackages(),
+    },
+    server: {
+      host: "127.0.0.1",
+      port: o.port ?? 5100,
+      strictPort: false,
+      hmr: o.hmr ?? false,
+      // 이 맥에서 폴더 단위 fs.watch(FSEvents)가 이벤트를 하나도 안 준다(파일 단위 kqueue 만 산다). 프로젝트는 작으니 폴링이 확실하다.
+      watch: o.hmr ? { usePolling: true, interval: 150 } : null,
+      fs: { allow: [root, repoRoot] },
+    },
+  });
+  await server.listen();
+  const url = server.resolvedUrls?.local[0] ?? `http://127.0.0.1:${server.config.server.port}/`;
+  return { url, dir: root, server, close: () => server.close() };
+}

package/packages/clock/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@kasaframe/clock",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./install": "./src/install.ts"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  }
+}