kasaframe 0.0.0-stage → 0.1.1

package/packages/jizura/src/install.ts

@@ -0,0 +1,226 @@
+// JIZURA 엔진을 고정 커밋으로 받아 UI 를 뺀 한 파일로 묶고, 가사 언어에 쓸 글꼴을 받아 둔다(노드 쪽).
+//   node packages/jizura/src/install.ts [--lang ko,ja]      kf setup jizura 가 부른다
+// 결과는 패키지 밖 ~/.cache/kasaframe/jizura 에 둔다 — 설치본은 패키지 폴더(node_modules 안)에 못 쓸 수 있다.
+// 렌더는 오프라인이어도 돌아야 해서 글꼴을 CDN 이 아니라 여기서 낸다(vite.ts 가 /@kf-jizura/ 로 낸다).
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { JIZURA_COMMIT, JIZURA_CREDIT, JIZURA_REPO, JIZURA_VERSION } from "./pin.ts";
+
+export const jizuraHome = (): string => process.env.KF_JIZURA_HOME ?? join(homedir(), ".cache", "kasaframe", "jizura");
+export const engineDir = (): string => join(jizuraHome(), "engine");
+export const fontDir = (): string => join(jizuraHome(), "fonts");
+const repoDir = (): string => join(jizuraHome(), "repo");
+
+export interface FontFile {
+  family: string;
+  /** 가변 글꼴은 "100 900" */
+  weight: string;
+  file: string;
+  lang: string;
+}
+
+export interface EngineInfo {
+  commit: string;
+  version: string;
+  sha256: string;
+  bytes: number;
+  files: string[];
+}
+
+// JIZURA 의 J.LANG_FACES·J.FONTS 가 그 언어에서 그리는 얼굴(google/fonts ofl 폴더). 한국어 매핑에 없는 키(dot·mono)는 일본어 얼굴을 그대로 쓴다
+interface Family { family: string; dir: string; weights?: number[] }
+const COMMON: Family[] = [
+  { family: "IBM Plex Mono", dir: "ibmplexmono", weights: [500, 600] },
+  { family: "DotGothic16", dir: "dotgothic16" },
+];
+const FAMILIES: Record<string, Family[]> = {
+  ko: [
+    { family: "Noto Sans KR", dir: "notosanskr" },
+    { family: "Noto Serif KR", dir: "notoserifkr" },
+    { family: "Black Han Sans", dir: "blackhansans" },
+    { family: "Jua", dir: "jua" },
+    { family: "Do Hyeon", dir: "dohyeon" },
+    { family: "Gowun Dodum", dir: "gowundodum" },
+    { family: "Gowun Batang", dir: "gowunbatang", weights: [700] },
+    { family: "Nanum Brush Script", dir: "nanumbrushscript" },
+    { family: "IBM Plex Sans KR", dir: "ibmplexsanskr", weights: [500] },
+  ],
+  ja: [
+    { family: "Noto Sans JP", dir: "notosansjp" },
+    { family: "Noto Serif JP", dir: "notoserifjp" },
+    { family: "Dela Gothic One", dir: "delagothicone" },
+    { family: "Zen Kaku Gothic New", dir: "zenkakugothicnew", weights: [900] },
+    { family: "Zen Old Mincho", dir: "zenoldmincho", weights: [900] },
+    { family: "Kaisei Tokumin", dir: "kaiseitokumin", weights: [800] },
+    { family: "M PLUS Rounded 1c", dir: "mplusrounded1c", weights: [800] },
+    { family: "Mochiy Pop One", dir: "mochiypopone" },
+    { family: "Yuji Syuku", dir: "yujisyuku" },
+    { family: "Reggae One", dir: "reggaeone" },
+    { family: "Rampart One", dir: "rampartone" },
+    { family: "Potta One", dir: "pottaone" },
+    { family: "Kiwi Maru", dir: "kiwimaru", weights: [500] },
+    { family: "Klee One", dir: "kleeone", weights: [600] },
+    { family: "Shippori Mincho B1", dir: "shipporiminchob1", weights: [800] },
+    { family: "IBM Plex Sans JP", dir: "ibmplexsansjp", weights: [500] },
+  ],
+};
+export const FONT_LANGS = Object.keys(FAMILIES);
+
+const WEIGHT: Record<string, number> = { Thin: 100, ExtraLight: 200, Light: 300, Regular: 400, Medium: 500, SemiBold: 600, Bold: 700, ExtraBold: 800, Black: 900 };
+
+const git = (args: string[], cwd?: string) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+
+/** 고정 커밋만 얕게 받는다. KF_JIZURA_SRC 에 클론을 주면 그걸 읽기만 한다 */
+export function fetchSource(log = console.log): string {
+  const given = process.env.KF_JIZURA_SRC;
+  if (given) {
+    const head = git(["rev-parse", "HEAD"], given);
+    if (head !== JIZURA_COMMIT) log(`  주의: KF_JIZURA_SRC 가 ${head.slice(0, 7)} — 고정 커밋 ${JIZURA_COMMIT.slice(0, 7)} 이 아니다(거부 목록·색 구성 번호가 어긋날 수 있다)`);
+    return given;
+  }
+  const dir = repoDir();
+  if (existsSync(join(dir, ".git")) && git(["rev-parse", "HEAD"], dir) === JIZURA_COMMIT) return dir;
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, ".git"))) {
+    git(["init", "-q"], dir);
+    git(["remote", "add", "origin", JIZURA_REPO], dir);
+  }
+  log(`  ${JIZURA_REPO} @ ${JIZURA_COMMIT.slice(0, 7)} 받는 중`);
+  git(["fetch", "-q", "--depth", "1", "origin", JIZURA_COMMIT], dir);
+  git(["checkout", "-q", "--detach", "FETCH_HEAD"], dir);
+  return dir;
+}
+
+/** src/*.js 를 업스트림 build.py 와 같은 순서로 잇되 편집기 UI(12_ui.js)는 뺀다. 업스트림 파일은 고치지 않는다 */
+export function buildEngine(src: string): EngineInfo {
+  const version = readFileSync(join(src, "VERSION"), "utf8").trim();
+  const files = readdirSync(join(src, "src")).filter((f) => f.endsWith(".js") && f !== "12_ui.js").sort();
+  const body = files.map((f) => readFileSync(join(src, "src", f), "utf8")).join("\n").split("@VERSION@").join(version);
+  const js = `/*! JIZURA 字面 v${version} engine — ${JIZURA_CREDIT}. 라이선스는 옆 JIZURA_LICENSE.txt\n *  ${files.join(" ")} */\n${body}`;
+  const out = engineDir();
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "jizura_engine.js"), js);
+  copyFileSync(join(src, "LICENSE"), join(out, "JIZURA_LICENSE.txt"));
+  const info: EngineInfo = {
+    commit: git(["rev-parse", "HEAD"], src),
+    version,
+    sha256: createHash("sha256").update(js).digest("hex"),
+    bytes: Buffer.byteLength(js),
+    files,
+  };
+  writeFileSync(join(out, "engine.json"), JSON.stringify(info, null, 1));
+  return info;
+}
+
+async function getJson(url: string): Promise<unknown> {
+  const headers: Record<string, string> = { "user-agent": "kasaframe-jizura-fonts" };
+  if (process.env.GITHUB_TOKEN) headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const r = await fetch(url, { headers });
+  if (!r.ok) throw new Error(`${url} → ${r.status}${r.status === 403 ? " (GitHub API 한도 — GITHUB_TOKEN 을 주면 늘어난다)" : ""}`);
+  return r.json();
+}
+
+async function download(url: string, to: string): Promise<void> {
+  for (let i = 0; ; i++) {
+    try {
+      const r = await fetch(url);
+      if (!r.ok) throw new Error(`${r.status}`);
+      writeFileSync(`${to}.part`, Buffer.from(await r.arrayBuffer()));
+      renameSync(`${to}.part`, to);
+      return;
+    } catch (err) {
+      if (i >= 3) throw new Error(`${url} 를 못 받았다: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
+
+/** google/fonts 의 원본(서브셋 아닌 전체) 글꼴. 받은 파일은 크기가 맞으면 건너뛴다 */
+export async function fetchFonts(langs: string[], log = console.log): Promise<FontFile[]> {
+  const dir = fontDir();
+  mkdirSync(dir, { recursive: true });
+  const manifestPath = join(dir, "fonts.json");
+  const have: FontFile[] = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : [];
+  const want = [...COMMON.map((f) => ({ ...f, lang: "common" })), ...langs.flatMap((l) => (FAMILIES[l] ?? []).map((f) => ({ ...f, lang: l })))];
+  const out = have.filter((f) => existsSync(join(dir, f.file)) && !want.some((w) => w.family === f.family));
+  for (const fam of want) {
+    const list = (await getJson(`https://api.github.com/repos/google/fonts/contents/ofl/${fam.dir}`)) as { name: string; size: number; download_url: string }[];
+    const ttf = list.filter((x) => x.name.endsWith(".ttf") && !/Italic/.test(x.name));
+    const variable = ttf.find((x) => x.name.includes("["));
+    const picks = variable
+      ? [{ src: variable, weight: "100 900" }]
+      : ttf
+          .map((x) => ({ src: x, w: WEIGHT[/-(\w+)\.ttf$/.exec(x.name)?.[1] ?? "Regular"] ?? 400 }))
+          .filter((x) => !fam.weights || fam.weights.includes(x.w))
+          .map((x) => ({ src: x.src, weight: String(x.w) }));
+    if (!picks.length) throw new Error(`${fam.family}: google/fonts ofl/${fam.dir} 에 맞는 ttf 가 없다`);
+    for (const p of picks) {
+      const file = p.src.name.replace(/\[.*\]/, "-VF");
+      const to = join(dir, file);
+      if (!existsSync(to) || statSync(to).size !== p.src.size) {
+        log(`  ${fam.family} ${p.weight} — ${(p.src.size / 1048576).toFixed(1)}MB`);
+        await download(p.src.download_url, to);
+      }
+      out.push({ family: fam.family, weight: p.weight, file, lang: fam.lang });
+    }
+    const ofl = list.find((x) => x.name === "OFL.txt");
+    const oflTo = join(dir, `OFL-${fam.dir}.txt`);
+    if (ofl && !existsSync(oflTo)) await download(ofl.download_url, oflTo);
+  }
+  writeFileSync(manifestPath, JSON.stringify(out, null, 1));
+  return out;
+}
+
+export function engineInfo(): EngineInfo | null {
+  const p = join(engineDir(), "engine.json");
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as EngineInfo) : null;
+}
+
+export function installedFonts(): FontFile[] {
+  const p = join(fontDir(), "fonts.json");
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as FontFile[]) : [];
+}
+
+/** kf doctor 한 줄 — cli/deps.ts 의 Check 꼴 */
+export function jizuraCheck() {
+  const info = engineInfo();
+  const langs = [...new Set(installedFonts().map((f) => f.lang))].filter((l) => l !== "common");
+  const ok = !!info && info.commit === JIZURA_COMMIT && langs.length > 0;
+  return {
+    name: "JIZURA 가사 층",
+    ok,
+    required: false,
+    detail: info
+      ? `v${info.version} @${info.commit.slice(0, 7)}${info.commit === JIZURA_COMMIT ? "" : ` (고정 ${JIZURA_COMMIT.slice(0, 7)} 이 아니다)`} · 글꼴 ${langs.join("·") || "없음"} — ${jizuraHome()}`
+      : "없음 — 뮤비 가사 키네틱(jizuraLayer)만 못 쓴다. 없으면 틀 장면은 DOM 낱말로 대신한다",
+    fix: ok ? undefined : "kf setup jizura  (일본어 가사도 쓰면 node packages/jizura/src/install.ts --lang ko,ja)",
+  };
+}
+
+export async function install(langs: string[], log = console.log): Promise<void> {
+  const src = fetchSource(log);
+  const info = buildEngine(src);
+  log(`  엔진 v${info.version} @${info.commit.slice(0, 7)} — ${(info.bytes / 1048576).toFixed(1)}MB, 파일 ${info.files.length}개 → ${engineDir()}`);
+  const fonts = await fetchFonts(langs, log);
+  log(`  글꼴 ${fonts.length}개(${langs.join("·")}) → ${fontDir()}`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const i = process.argv.indexOf("--lang");
+  const langs = (i > 0 ? process.argv[i + 1] : "ko").split(",").filter(Boolean);
+  const bad = langs.filter((l) => !FONT_LANGS.includes(l));
+  if (bad.length) {
+    console.error(`모르는 언어 ${bad.join(" ")} — ${FONT_LANGS.join(" ")}`);
+    process.exit(2);
+  }
+  install(langs).then(
+    () => process.exit(0),
+    (err) => {
+      console.error(`jizura 설치 실패: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    },
+  );
+}

package/packages/jizura/src/layer.ts

@@ -0,0 +1,282 @@
+// JIZURA 字面(MIT, (c) 2026 hakoniwa) 엔진을 결정적인 가사 층으로 — 장면 위 캔버스 한 장에 시각 t 의 가사를 그린다.
+// 플랜 하나 = JIZURA 프로젝트 하나(곡 전체 가사·박). 같은 설정을 쓰는 장면끼리는 한 플랜을 나눠 쓰고, 장면마다 다른 플랜을 고른다.
+// 엔진·글꼴은 kf setup jizura 가 ~/.cache/kasaframe/jizura 에 두고 서버가 /@kf-jizura/ 로 낸다(vite.ts).
+// 빌려 온 것: 플랜 만들기·색 구성 고르기(schemes)는 vocaloid-style-mv-pipeline(MIT, NikusonP) 의 jizura_adapter.js 를 옮겼다.
+import { onSeek } from "@kasaframe/adapters";
+import type { KfMeta, SceneCtx } from "@kasaframe/core";
+import { partPool, type JizuraRegistry, type PoolOptions } from "./deny.ts";
+import { parseLyrics, toLrc, type LyricsJson } from "./lyrics.ts";
+
+const URL_BASE = "/@kf-jizura/";
+
+export type DrawMode = "transparent" | "front" | "back" | "normal";
+
+export interface PlanSettings extends PoolOptions {
+  /** JIZURA 스타일 — ocean·gold·noir·sakura·sunset·mono·paper·sumi … */
+  style?: string;
+  /** 'light' = 밝은 바탕 위 어두운 글(낮 장면) · 'dark' = 어두운 바탕 위 밝은 글(밤 장면) · [번호…] = 그 스타일의 색 구성 */
+  schemes?: "light" | "dark" | number[];
+  /** 가운데를 비우고 양옆(세로 화면은 위아래) 띠에만 — 주인공 얼굴·몸짓이 요점인 장면 */
+  centerFree?: boolean;
+  centerDir?: "tb" | "lr";
+  seed?: number;
+  fx?: Record<string, unknown>;
+  colors?: Record<string, unknown>;
+  /** 그 밖의 JIZURA 프로젝트 칸은 그대로 넘긴다 */
+  [key: string]: unknown;
+}
+
+export interface LayerOptions {
+  ctx: SceneCtx;
+  /** jizuraPlans 로 등록한 이름, 또는 설정 그대로(같은 설정이면 한 플랜을 나눠 쓴다) */
+  plan?: string | PlanSettings;
+  /** 기본 transparent — JIZURA 바탕 없이 글·장식만 */
+  mode?: DrawMode;
+  /** 기본은 프로젝트 뿌리의 lyrics.json */
+  lyrics?: LyricsJson;
+}
+
+type J = JizuraRegistry & Record<string, any>;
+
+interface PlanEntry {
+  plan: any;
+  R: any;
+}
+
+declare global {
+  interface Window {
+    J?: J;
+  }
+}
+
+// mulberry32 — 렌더러가 만들 때 쓰는 Math.random(종이·입자 질감)을 플랜 seed 에 묶는다. 가상 시계가 seek 마다 난수를 다시 심어도 질감이 같다
+function withSeed<T>(seed: number, fn: () => T): T {
+  let a = seed >>> 0;
+  const rnd = () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const real = Math.random;
+  Math.random = rnd;
+  try {
+    return fn();
+  } finally {
+    Math.random = real;
+  }
+}
+
+function loadScript(src: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = document.createElement("script");
+    s.src = src;
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error(`${src} 를 못 받았다`));
+    document.head.append(s);
+  });
+}
+
+// 없는 파일을 Vite 가 SPA 대체로 index.html(200)로 돌려준다 — JSON 이 아니면 없는 것으로 본다. 가사 없는 뮤비 프로젝트가 렌더 중에 던지지 않게
+async function getJson<T>(url: string | URL): Promise<T | null> {
+  try {
+    const r = await fetch(url);
+    if (!r.ok || !(r.headers.get("content-type") ?? "").includes("json")) return null;
+    return (await r.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface FontFile { family: string; weight: string; file: string; lang: string }
+
+// 받아 둔 글꼴이 있는 언어는 CDN 에 묻지 않는다 — 렌더가 오프라인이어도, 늦게 온 조각 글꼴로 첫 프레임이 대체 글꼴이 되는 일도 없다
+async function localFonts(J: J): Promise<void> {
+  const list = (await getJson<FontFile[]>(`${URL_BASE}fonts/fonts.json`)) ?? [];
+  for (const f of list) document.fonts.add(new FontFace(f.family, `url(${URL_BASE}fonts/${encodeURIComponent(f.file)})`, { weight: f.weight, display: "block" }));
+  const langs = new Set(list.map((f) => f.lang));
+  const upstream = J.ensureFonts;
+  J.ensureFonts = async (text: string, keys: string[] | null) => {
+    if (!langs.has(J.lang) || keys?.includes("@var")) return upstream(text, keys);
+    const uniq = [...new Set([...text])].join("") || "가";
+    const list = (keys ?? Object.keys(J.FONTS)).filter((k: string) => J.FONTS[k]);
+    const faces: { family: string; weight: number }[] = list.map((k: string) => J.faceOf(k));
+    for (const b of J.langBaseFaces(list)) faces.push({ family: `"${b.family}"`, weight: b.weight });
+    const specs = [...new Set(faces.map((f) => `${f.weight} 64px ${f.family}`))];
+    await Promise.all(specs.map((s) => document.fonts.load(s, uniq).catch(() => null)));
+    J.glyphs.clear();
+    J.metrics.clear();
+  };
+}
+
+let engine: Promise<J | null> | null = null;
+
+/** 엔진을 한 번만 싣는다. 깔지 않았으면 null — 부르는 쪽은 대체 화면으로 */
+export function loadJizura(): Promise<J | null> {
+  engine ??= (async () => {
+    if (window.J?.plan) return window.J;
+    if (!(await getJson(`${URL_BASE}engine/engine.json`))) {
+      console.warn("[kf] JIZURA 엔진이 없다 — kf setup jizura (가사 층 없이 그린다)");
+      return null;
+    }
+    try {
+      await loadScript(`${URL_BASE}engine/jizura_engine.js`);
+      const J = window.J as J;
+      await localFonts(J);
+      return J;
+    } catch (err) {
+      console.warn(`[kf] JIZURA 엔진을 못 실었다 — 가사 층 없이 그린다: ${err instanceof Error ? err.message : err}`);
+      return null;
+    }
+  })();
+  return engine;
+}
+
+const named = new Map<string, PlanSettings>();
+
+/** 장면들이 이름으로 고를 플랜을 등록한다 — 낮·밤·후렴처럼 */
+export function jizuraPlans(plans: Record<string, PlanSettings>): void {
+  for (const [k, v] of Object.entries(plans)) named.set(k, v);
+}
+
+let lyricsJob: Promise<LyricsJson | null> | null = null;
+function projectLyrics(): Promise<LyricsJson | null> {
+  lyricsJob ??= getJson(new URL("lyrics.json", document.baseURI)).then((raw) => {
+    if (raw === null) return null;
+    try {
+      return parseLyrics(raw);
+    } catch (err) {
+      console.warn(`[kf] lyrics.json 을 못 읽었다 — 가사 층 없이 그린다: ${err instanceof Error ? err.message : err}`);
+      return null;
+    }
+  });
+  return lyricsJob;
+}
+
+const ASPECTS: [string, number][] = [["16:9", 16 / 9], ["9:16", 9 / 16], ["1:1", 1], ["4:5", 0.8], ["4:3", 4 / 3], ["3:4", 0.75], ["21:9", 21 / 9]];
+const aspectOf = (m: KfMeta) => ASPECTS.reduce((b, a) => (Math.abs(a[1] - m.width / m.height) < Math.abs(b[1] - m.width / m.height) ? a : b))[0];
+
+// 플랜을 짓는 동안 J.lang·J.typeset 같은 전역이 바뀐다 — 한 번에 하나씩
+let queue: Promise<unknown> = Promise.resolve();
+const plans = new Map<string, Promise<PlanEntry | null>>();
+
+function buildPlan(J: J, s: PlanSettings, lyrics: LyricsJson, ctx: SceneCtx): Promise<PlanEntry> {
+  const base = J.defaultProject();
+  const { deny, denyOnly, moods, schemes, fx, ...rest } = s;
+  const seed = s.seed ?? 2609;
+  const project = {
+    ...base,
+    lyrics: toLrc(lyrics),
+    lang: lyrics.lang ?? "auto",
+    fps: ctx.meta.fps,
+    res: Math.min(ctx.meta.width, ctx.meta.height),
+    aspect: aspectOf(ctx.meta),
+    style: "ocean",
+    seed,
+    // 統一感·文字整列 켬, 공포·和風 세트 끔. 화면 전체 섬광은 kasaframe(dropBurst·섬광 검사)이 한 곳에서 쥔다
+    unify: true,
+    typeset: true,
+    extra: true,
+    wa: false,
+    horror: false,
+    ...rest,
+    fx: { ...base.fx, flash: false, hud: "off", glitch: 0.3, chroma: 0.45, ...fx },
+    timing: { ...base.timing, ...((rest.timing as object) ?? {}) },
+    enabled: partPool(J, { deny, denyOnly, moods }),
+  };
+  const data = ctx.beats.data;
+  const audio = { duration: data.duration, beats: data.beats.slice(), energy: null, energyRate: 0, bpm: data.bpm };
+  const job = queue.then(async () => {
+    const plan = J.plan(project, audio);
+    if (schemes) {
+      const pick = (test: (l: number) => boolean) => plan.style.schemes.map((x: { bg: string }, i: number) => (test(J.lum(x.bg)) ? i : -1)).filter((i: number) => i >= 0);
+      const ok: number[] = Array.isArray(schemes) ? schemes : schemes === "dark" ? pick((l) => l < 0.25) : pick((l) => l > 0.6);
+      if (ok.length) for (const c of plan.cuts) c.scheme = ok[(c.scheme | 0) % ok.length];
+    }
+    const R = withSeed(seed, () => new J.Renderer());
+    withSeed(seed + 1, () => R.paper(plan.W, plan.H));
+    await J.ensureFonts(project.lyrics + "0123456789:./-", J.fontsOfPlan(plan));
+    J.glyphs.maxRes = plan.H >= 1000 ? 768 : 512;
+    return { plan, R };
+  });
+  queue = job.catch(() => null);
+  return job;
+}
+
+function planFor(o: LayerOptions): Promise<PlanEntry | null> {
+  const settings = typeof o.plan === "string" ? named.get(o.plan) : (o.plan ?? {});
+  if (!settings) return Promise.reject(new Error(`jizuraPlans 에 없는 플랜 "${o.plan}"`));
+  const key = JSON.stringify([settings, o.lyrics ? "own" : "project", o.ctx.meta.width, o.ctx.meta.height]);
+  let job = plans.get(key);
+  if (!job) {
+    job = (async () => {
+      const [J, lyrics] = await Promise.all([loadJizura(), o.lyrics ? Promise.resolve(o.lyrics) : projectLyrics()]);
+      if (!J || !lyrics?.lines.length) return null;
+      return buildPlan(J, settings, lyrics, o.ctx);
+    })();
+    plans.set(key, job);
+  }
+  return job;
+}
+
+/** 엔진·가사가 다 있어 이 층이 그릴 수 있는지 — 틀 장면이 대체 화면을 고를 때 */
+export async function jizuraReady(): Promise<boolean> {
+  const [J, lyrics] = await Promise.all([loadJizura(), projectLyrics()]);
+  return !!J && !!lyrics?.lines.length;
+}
+
+/** 컷 목록 — 어느 컷이 화면을 덮는지 찾을 때(layout·enter·hold·exit·decor·cam·trans) */
+export async function jizuraCuts(o: LayerOptions): Promise<object[]> {
+  const e = await planFor(o);
+  return (e?.plan.cuts ?? []).map((c: any) => ({
+    i: c.index, start: +c.start.toFixed(3), end: +c.end.toFixed(3), text: c.text,
+    layout: c.layout, enter: c.enter, hold: c.hold, exit: c.exit, cam: c.cam, trans: c.trans ?? null,
+    decor: (c.decor ?? []).map((d: any) => d.id ?? d.type ?? d), scheme: c.scheme,
+  }));
+}
+
+const drawOpts = (mode: DrawMode, scale: number) =>
+  mode === "front" || mode === "back" ? { scale, transparent: true, layer: mode } : mode === "transparent" ? { scale, transparent: true } : { scale };
+
+export type JizuraPaint = ((t: number) => void) & { canvas: HTMLCanvasElement };
+
+/** 장면 build 에서 부른다 — 장면을 덮는 캔버스를 짓고 (t) => 칠하기를 돌려준다. t 는 장면 안 시각.
+ *  한 장면에서 플랜을 바꿔 끼우려면(드롭부터 큰 플랜) 층을 둘 짓고 안 쓰는 쪽 .canvas 를 숨긴다 */
+export function jizuraLayer(el: HTMLElement, o: LayerOptions): JizuraPaint {
+  const { ctx } = o;
+  const mode = o.mode ?? "transparent";
+  const canvas = document.createElement("canvas");
+  canvas.width = ctx.meta.width;
+  canvas.height = ctx.meta.height;
+  canvas.dataset.kfLyrics = "jizura";
+  canvas.style.cssText = "position:absolute;inset:0;width:100%;height:100%;pointer-events:none";
+  el.append(canvas);
+  const g = canvas.getContext("2d")!;
+  let entry: PlanEntry | null = null;
+  const ready = planFor(o).then(
+    (e) => (entry = e),
+    (err) => {
+      console.warn(`[kf] 가사 층(${ctx.id}): ${err instanceof Error ? err.message : err}`);
+      return null;
+    },
+  );
+  let want: number | null = null;
+  let drawn: number | null = null;
+  const paint = (T: number) => {
+    if (!entry) return;
+    entry.R.frame(g, entry.plan, T, drawOpts(mode, canvas.width / entry.plan.W));
+    drawn = T;
+  };
+  // 플랜이 아직이면 그 seek 을 플랜이 설 때까지 붙든다 — 첫 프레임부터 가사가 찍힌다
+  onSeek(async () => {
+    if (want === null || drawn === want) return;
+    await ready;
+    paint(want);
+  });
+  const draw = (t: number) => {
+    want = ctx.from + t;
+    paint(want);
+  };
+  return Object.assign(draw, { canvas });
+}

package/packages/jizura/src/lyrics.ts

@@ -0,0 +1,81 @@
+// lyrics.json — 프로젝트 뿌리에 둔다. 시각은 beats.json 과 같은 0(곡 시각 - from).
+// 글자는 공식 가사가 정본이고, 정렬(kf lyrics align)은 시각만 붙인다.
+
+export interface LyricWord {
+  w: string;
+  start: number;
+  end: number;
+}
+
+export interface LyricLine {
+  text: string;
+  start: number;
+  end: number;
+  words?: LyricWord[];
+}
+
+export interface LyricsJson {
+  source?: string;
+  /** 곡에서 잘라 쓴 시작(초) — beats.json 의 from 과 같은 뜻 */
+  from?: number;
+  lang?: string;
+  lines: LyricLine[];
+}
+
+export interface LrcOptions {
+  /** 이 시각보다 길게 빈 자리 뒤에는 [間奏] 줄을 넣는다 — 앞 줄이 다음 줄까지 남지 않게 */
+  gap?: number;
+  /** 줄이 목소리 끝 뒤에 남는 시간 — 정렬은 끝을 이르게 잡는 편이다 */
+  tail?: number;
+  title?: string;
+}
+
+const stamp = (t: number): string => {
+  const s = Math.max(0, t);
+  const m = Math.floor(s / 60);
+  const rest = s - m * 60;
+  return `[${String(m).padStart(2, "0")}:${rest.toFixed(2).padStart(5, "0")}]`;
+};
+
+// LRC 문법 글자(/ * 끝의 !)가 가사에 있으면 JIZURA 가 컷 나누기·강조로 읽는다 — 정본 글자를 그대로 두려면 비슷한 꼴로 바꾼다
+const plain = (text: string): string => text.replace(/\//g, "／").replace(/\*/g, "＊").replace(/!$/, "！").replace(/\|/g, "｜");
+
+export function toLrc(lyrics: LyricsJson, o: LrcOptions = {}): string {
+  const gap = o.gap ?? 2.5;
+  const tail = o.tail ?? 0.5;
+  const lines = lyrics.lines.filter((l) => l.text.trim() && Number.isFinite(l.start)).slice().sort((a, b) => a.start - b.start);
+  const out: string[] = [];
+  if (o.title) out.push(`[ti:${o.title}]`);
+  lines.forEach((l, i) => {
+    out.push(`${stamp(l.start)}${plain(l.text.trim())}`);
+    const next = lines[i + 1];
+    const end = Number.isFinite(l.end) ? l.end : l.start;
+    if (next && next.start - end > gap) out.push(`${stamp(end + tail)}[間奏]`);
+  });
+  return out.join("\n") + "\n";
+}
+
+export function parseLyrics(input: unknown): LyricsJson {
+  const o = (input ?? {}) as Partial<LyricsJson>;
+  if (!Array.isArray(o.lines)) throw new Error("lyrics.json 에 lines 배열이 없다");
+  for (const [i, l] of o.lines.entries()) {
+    if (typeof l?.text !== "string" || !Number.isFinite(l.start) || !Number.isFinite(l.end)) {
+      throw new Error(`lyrics.json lines[${i}] 에 text·start·end 가 다 있어야 한다`);
+    }
+  }
+  return o as LyricsJson;
+}
+
+/** 낱말 시각이 없는 줄은 글자 수 비율로 나눈다 */
+export function wordsOf(l: LyricLine): LyricWord[] {
+  if (l.words?.length) return l.words;
+  const parts = l.text.split(/\s+/).filter(Boolean);
+  const total = parts.reduce((a, p) => a + p.length, 0) || 1;
+  let t = l.start;
+  return parts.map((w) => {
+    const d = ((l.end - l.start) * w.length) / total;
+    const out = { w, start: t, end: t + d };
+    t += d;
+    return out;
+  });
+}

package/packages/jizura/src/pin.ts

@@ -0,0 +1,5 @@
+// 부품 이름·스타일의 색 구성 번호·거부 목록이 이 판에 맞춰져 있다. 판을 올리면 deny.ts 를 다시 보고 견본 스틸을 다시 찍는다 — 같은 seed 라도 컷이 다시 굴려진다
+export const JIZURA_REPO = "https://github.com/852wa/JIZURA.git";
+export const JIZURA_COMMIT = "fc16bfe43ea4a6c25a21f1caf04d17326de14f00";
+export const JIZURA_VERSION = "0.10.1";
+export const JIZURA_CREDIT = "JIZURA 字面 (c) 2026 hakoniwa (github.com/852wa/JIZURA), MIT";

package/packages/jizura/src/vite.ts

@@ -0,0 +1,36 @@
+// 미리보기·렌더·검사 서버(cli/serve.ts)가 붙이는 플러그인 — ~/.cache/kasaframe/jizura 의 엔진·글꼴을 /@kf-jizura/ 로 낸다.
+// Vite 의 fs.allow 를 넓히지 않고, 엔진은 모듈 변환 없이 원본 그대로(전역 스크립트) 나가게 한다.
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { extname, join, normalize, sep } from "node:path";
+import type { Plugin } from "vite";
+import { engineDir, fontDir } from "./install.ts";
+
+export const JIZURA_URL = "/@kf-jizura/";
+
+const TYPES: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+export function jizuraServe(): Plugin {
+  return {
+    name: "kf-jizura",
+    configureServer(server) {
+      server.middlewares.use(JIZURA_URL, (req, res, next) => {
+        const [kind, ...rest] = decodeURIComponent((req.url ?? "").split("?")[0]).replace(/^\/+/, "").split("/");
+        const base = kind === "engine" ? engineDir() : kind === "fonts" ? fontDir() : null;
+        if (!base) return next();
+        const file = normalize(join(base, ...rest));
+        if (!file.startsWith(base + sep) || !existsSync(file) || !statSync(file).isFile()) {
+          res.statusCode = 404;
+          return res.end();
+        }
+        res.setHeader("content-type", TYPES[extname(file)] ?? "application/octet-stream");
+        res.setHeader("cache-control", "no-cache");
+        createReadStream(file).pipe(res);
+      });
+    },
+  };
+}