kasaframe 0.0.0-stage → 0.1.3

package/packages/jizura/src/install.ts

@@ -0,0 +1,269 @@
+// JIZURA 가사 층의 엔진·글꼴 자리(노드 쪽). 엔진은 패키지에 실려 있다(vendor/ — 다시 만들기는 vendor.ts).
+// 한국어 가사에 자주 쓰는 얼굴은 vendor/fonts 에 실려 있고(한글·영숫자·문장부호 서브셋), 나머지 얼굴과 서브셋 밖 글자(한자·가나)는
+// 처음 쓸 때 google/fonts 고정 커밋에서 원본을 받아 ~/.cache/kasaframe/jizura/fonts 에 둔다 — 설치본(node_modules 안)에는 못 쓸 수 있다.
+// 못 받으면 다른 글꼴로 대신 그리지 않고 fontsMissing() 에 남긴다. 어떻게 할지는 사람이 고른다(kf 가 끝에 묻는다).
+// 렌더는 오프라인이어도 돌아야 해서 CDN 이 아니라 여기서 낸다(vite.ts 가 /@kf-jizura/ 로 낸다).
+//   node packages/jizura/src/install.ts [--lang ko,ja]      kf setup jizura — 그 언어의 나머지 얼굴을 미리 받는다
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GOOGLE_FONTS_COMMIT, JIZURA_COMMIT } from "./pin.ts";
+
+export const vendorDir = fileURLToPath(new URL("../vendor", import.meta.url));
+export const builtinFontDir = join(vendorDir, "fonts");
+export const jizuraHome = (): string => process.env.KF_JIZURA_HOME ?? join(homedir(), ".cache", "kasaframe", "jizura");
+export const fontDir = (): string => join(jizuraHome(), "fonts");
+
+export interface EngineInfo {
+  commit: string;
+  version: string;
+  sha256: string;
+  bytes: number;
+  files: string[];
+}
+
+export interface Upstream {
+  /** google/fonts ofl/<dir>/ 의 파일 이름 */
+  file: string;
+  /** 가변 글꼴은 "100 900" */
+  weight: string;
+  bytes: number;
+  sha256: string;
+}
+
+export interface Family {
+  family: string;
+  dir: string;
+  lang: "common" | "ko" | "ja";
+  files: Upstream[];
+  /** 사람이 「내장 글꼴로」를 고르면 이 얼굴 대신 그릴 내장 얼굴 */
+  stand?: string;
+}
+
+const up = (file: string, weight: string, bytes: number, sha256: string): Upstream => ({ file, weight, bytes, sha256 });
+
+// JIZURA 의 J.FONTS·J.LANG_FACES 가 그 언어에서 그리는 얼굴. 한국어 매핑에 없는 키(dot·mono)는 일본어 얼굴을 그대로 쓰고 한글은 그 뒤 Noto Sans KR 로 떨어진다
+export const FAMILIES: Family[] = [
+  { family: "IBM Plex Mono", dir: "ibmplexmono", lang: "common", files: [up("IBMPlexMono-Medium.ttf", "500", 136704, "a9b4c49bb299e05b5f6c481e7fb5e78943d2793249a0c8874ab574a2d1ea6755"), up("IBMPlexMono-SemiBold.ttf", "600", 140216, "d3c38e55c78f5b0f28009fddba4834ec503278936a5986032424c9bd2d23aa46")] },
+  { family: "DotGothic16", dir: "dotgothic16", lang: "common", files: [up("DotGothic16-Regular.ttf", "400", 2069236, "3ad9af88726d42b40f7f365f0dcac785af73cf20ea6f1d5b44e57cc21150b8f1")] },
+  { family: "Noto Sans KR", dir: "notosanskr", lang: "ko", files: [up("NotoSansKR[wght].ttf", "100 900", 10414588, "194018e6b2b293a7964f037b25c0249ce1418bc9ab3c971060a03aa57861e252")] },
+  { family: "Noto Serif KR", dir: "notoserifkr", lang: "ko", files: [up("NotoSerifKR[wght].ttf", "200 900", 23795420, "11f8d5de6f1b79195efba3828aaa2ec95c1178f5ae976fb23c8d53250a9938f3")] },
+  { family: "Black Han Sans", dir: "blackhansans", lang: "ko", files: [up("BlackHanSans-Regular.ttf", "400", 998424, "31960809284026681774a8e52dc19ebcad26cf69b0ad9d560f288296fbb52739")] },
+  { family: "Gowun Batang", dir: "gowunbatang", lang: "ko", files: [up("GowunBatang-Bold.ttf", "700", 8178712, "dbfcaa646e5831e7478524924f02906f550285a5050699b4e38c9950b3ec4b94")] },
+  { family: "Jua", dir: "jua", lang: "ko", stand: "Black Han Sans", files: [up("Jua-Regular.ttf", "400", 2119352, "769677aef240bfc3b9965f2b50748075bff885e6c6992fc591a3fb268279f898")] },
+  { family: "Do Hyeon", dir: "dohyeon", lang: "ko", stand: "Black Han Sans", files: [up("DoHyeon-Regular.ttf", "400", 879764, "35644be7f28e0a68a447b1f7af351dcde5674b870f24f7b5f43e26d00b4ab653")] },
+  { family: "Gowun Dodum", dir: "gowundodum", lang: "ko", stand: "Noto Sans KR", files: [up("GowunDodum-Regular.ttf", "400", 7229088, "a6e457933227483a11758fd0947bc74422a106d46f0bf057fdaa5af94a30067d")] },
+  { family: "Nanum Brush Script", dir: "nanumbrushscript", lang: "ko", stand: "Gowun Batang", files: [up("NanumBrushScript-Regular.ttf", "400", 3564804, "27ceaf578c96f594cdf07fe0181b251790acbb746a164e45c1f6473f89911a31")] },
+  { family: "IBM Plex Sans KR", dir: "ibmplexsanskr", lang: "ko", stand: "Noto Sans KR", files: [up("IBMPlexSansKR-Medium.ttf", "500", 2866736, "4a7130f56ce50bf10f9d383f624e50bad2c80bebc63e51f4269ece2c7d919166")] },
+  { family: "Noto Sans JP", dir: "notosansjp", lang: "ja", files: [up("NotoSansJP[wght].ttf", "100 900", 9589900, "c2f3b4d463500a2ddcd3849cded1fceeb9fd6d1c32e6cbecd568453ba50fc68f")] },
+  { family: "Noto Serif JP", dir: "notoserifjp", lang: "ja", files: [up("NotoSerifJP[wght].ttf", "200 900", 13574352, "2fd527ba12b6a44ec30d796d633360da0aeba6c5d4af1304ce12bb4dc15a7dfc")] },
+  { family: "Dela Gothic One", dir: "delagothicone", lang: "ja", files: [up("DelaGothicOne-Regular.ttf", "400", 2508848, "4ff87a0965f1b0505e5a2c58424bc6ad3cff27e56a82f21c2fc9d6b0e3857ee2")] },
+  { family: "Zen Kaku Gothic New", dir: "zenkakugothicnew", lang: "ja", files: [up("ZenKakuGothicNew-Black.ttf", "900", 2300600, "795819a979184981842994d8f4eb9e14ce443d687bd5e731d6ca67ded8f92261")] },
+  { family: "Zen Old Mincho", dir: "zenoldmincho", lang: "ja", files: [up("ZenOldMincho-Black.ttf", "900", 5416348, "84a80d8bca79d7d9478935045b216ed003ad40fdea5fd9116d524eb26e872cdc")] },
+  { family: "Kaisei Tokumin", dir: "kaiseitokumin", lang: "ja", files: [up("KaiseiTokumin-ExtraBold.ttf", "800", 4564000, "bf44bb3e23cc703bfb19111833f78e651998d0a2b1863eff9e88cecb38a8bc53")] },
+  { family: "M PLUS Rounded 1c", dir: "mplusrounded1c", lang: "ja", files: [up("MPLUSRounded1c-ExtraBold.ttf", "800", 3628512, "8e7c15901dca87f1451b356dda594f7d092ba252a5dcc47da74523a242493c36")] },
+  { family: "Mochiy Pop One", dir: "mochiypopone", lang: "ja", files: [up("MochiyPopOne-Regular.ttf", "400", 5163948, "9e009430e1316c271a5f34759c6b65fc343c4e806f193042528887e7235a92c6")] },
+  { family: "Yuji Syuku", dir: "yujisyuku", lang: "ja", files: [up("YujiSyuku-Regular.ttf", "400", 8430348, "82728ebafc8c97391e2dab633414a806f344b8e4e2227d307179f07b548fca61")] },
+  { family: "Reggae One", dir: "reggaeone", lang: "ja", files: [up("ReggaeOne-Regular.ttf", "400", 2153256, "aebe62598732d76036f30ec11bb0ec5f68938e373a06d1b4ceb6b9cf1abf3db2")] },
+  { family: "Rampart One", dir: "rampartone", lang: "ja", files: [up("RampartOne-Regular.ttf", "400", 3722352, "a4c60ee835175fa147eb483fac0dd8ff9007c37884ef77af86b0a868fa554d49")] },
+  { family: "Potta One", dir: "pottaone", lang: "ja", files: [up("PottaOne-Regular.ttf", "400", 4918516, "bde843868b56e429e1c863da2efa76df533162b226d990efcb96d533b0ca2a93")] },
+  { family: "Kiwi Maru", dir: "kiwimaru", lang: "ja", files: [up("KiwiMaru-Medium.ttf", "500", 5123612, "b2659f300a7d48c3f29eb273ffc5e1b26cc416ac8c37ff6bb2f3e43c2f4d235a")] },
+  { family: "Klee One", dir: "kleeone", lang: "ja", files: [up("KleeOne-SemiBold.ttf", "600", 8905128, "b031ec426c23ca1143ef1f7d58bee7a79efe119ed654152f121c922202b303fd")] },
+  { family: "Shippori Mincho B1", dir: "shipporiminchob1", lang: "ja", files: [up("ShipporiMinchoB1-ExtraBold.ttf", "800", 15088060, "bee99a242f32128e8d6a4acff2b3f1742cd42ea90748758e6e10456871887e76")] },
+  { family: "IBM Plex Sans JP", dir: "ibmplexsansjp", lang: "ja", files: [up("IBMPlexSansJP-Medium.ttf", "500", 2389060, "1d09f5e25b19e54b2c55da70de58f9962512c3e07ed7c3e1c9bad77ace5c22e6")] },
+];
+export const FONT_LANGS = ["ko", "ja"];
+
+export const localName = (file: string): string => file.replace(/\[.*\]/, "-VF");
+
+export interface BuiltinFont {
+  family: string;
+  weight: string;
+  file: string;
+  /** 서브셋을 뜬 원본(google/fonts 파일 이름) */
+  from: string;
+  /** 서브셋이면 남긴 글자 범위 — 원본을 그대로 실은 것은 없다 */
+  unicodes?: string;
+}
+
+let builtinCache: BuiltinFont[] | null = null;
+export function builtinFonts(): BuiltinFont[] {
+  if (builtinCache) return builtinCache;
+  const p = join(builtinFontDir, "fonts.json");
+  builtinCache = existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")).fonts as BuiltinFont[]) : [];
+  return builtinCache;
+}
+
+/** text 에서 그 범위(U+AC00-D7A3,…) 밖 글자 — 서브셋에 없으니 원본이 있어야 그 얼굴로 그린다 */
+export function outside(text: string, unicodes: string): string[] {
+  const ranges = unicodes.split(",").map((r) => r.trim().replace(/^U\+/i, "").split("-").map((h) => parseInt(h, 16)));
+  const out = new Set<string>();
+  for (const ch of text) {
+    const c = ch.codePointAt(0)!;
+    if (c < 0x20) continue;
+    if (!ranges.some(([a, b = a]) => c >= a && c <= b)) out.add(ch);
+  }
+  return [...out];
+}
+
+export function engineInfo(): EngineInfo | null {
+  const p = join(vendorDir, "engine.json");
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as EngineInfo) : null;
+}
+
+// 막힌 망에서는 google/fonts 거울을 줄 수 있다 — ofl/<dir>/<파일> 꼴만 맞으면 된다. 받은 파일은 크기·sha256 으로 고정본인지 본다
+const fontBase = (): string => process.env.KF_JIZURA_FONTS_URL ?? `https://raw.githubusercontent.com/google/fonts/${GOOGLE_FONTS_COMMIT}`;
+const fontUrl = (dir: string, file: string): string => `${fontBase()}/ofl/${dir}/${encodeURIComponent(file)}`;
+
+const why = (err: unknown): string => (err instanceof Error ? (err.cause instanceof Error ? `${err.message}(${err.cause.message})` : err.message) : String(err));
+
+async function download(url: string, to: string, want?: Upstream): Promise<void> {
+  let last = "";
+  for (let i = 0; i < 3; i++) {
+    try {
+      const r = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      const buf = Buffer.from(await r.arrayBuffer());
+      if (want && (buf.length !== want.bytes || createHash("sha256").update(buf).digest("hex") !== want.sha256)) {
+        throw new Error(`고정본(${GOOGLE_FONTS_COMMIT.slice(0, 7)})과 다른 파일이 왔다`);
+      }
+      writeFileSync(`${to}.part`, buf);
+      renameSync(`${to}.part`, to);
+      return;
+    } catch (err) {
+      last = why(err);
+    }
+  }
+  throw new Error(`${url} — ${last}`);
+}
+
+export const cached = (f: Upstream): boolean => {
+  const p = join(fontDir(), localName(f.file));
+  return existsSync(p) && statSync(p).size === f.bytes;
+};
+
+const jobs = new Map<string, Promise<void>>();
+
+/** 그 얼굴의 원본을 받아 둔다(같은 얼굴은 한 번만, OFL 원문도 옆에) */
+export function fetchFamily(fam: Family, log: (s: string) => void = console.log): Promise<void> {
+  let job = jobs.get(fam.family);
+  if (!job) {
+    job = (async () => {
+      mkdirSync(fontDir(), { recursive: true });
+      const ofl = join(fontDir(), `OFL-${fam.dir}.txt`);
+      if (!existsSync(ofl)) await download(fontUrl(fam.dir, "OFL.txt"), ofl);
+      for (const f of fam.files) {
+        if (cached(f)) continue;
+        log(`  ${fam.family} ${f.weight} — ${(f.bytes / 1048576).toFixed(1)}MB 받는 중`);
+        await download(fontUrl(fam.dir, f.file), join(fontDir(), localName(f.file)), f);
+      }
+    })();
+    jobs.set(fam.family, job);
+    job.catch(() => jobs.delete(fam.family));
+  }
+  return job;
+}
+
+export interface FaceSrc {
+  family: string;
+  weight: string;
+  /** /@kf-jizura/ 아래 경로 */
+  url: string;
+}
+
+export interface Missing {
+  family: string;
+  reason: string;
+  /** 「내장 글꼴로」를 고르면 대신 그릴 내장 얼굴 — 없으면 그 길로도 못 그린다(서브셋 밖 글자) */
+  stand?: string;
+  /** 그 얼굴을 쓰려던 프로젝트 폴더 — 답을 넣을 곳 */
+  project?: string;
+}
+
+const missing = new Map<string, Missing>();
+/** 이 프로세스에서 못 받아 그리지 못한 얼굴 — kf 가 끝에 이걸 보고 묻는다 */
+export const fontsMissing = (): Missing[] => [...missing.values()];
+
+/** 페이지가 그릴 얼굴의 파일을 고른다 — 받아 둔 원본 → 내장 글꼴(서브셋이면 글자가 다 들 때만) → 처음 쓰는 얼굴이면 받기.
+ *  못 받으면 사람이 「내장 글꼴로」를 골랐을 때(builtin)만 stand 로 그리고, 아니면 missing 으로 돌려준다 */
+export async function provideFonts(families: string[], text: string, o: { builtin?: boolean; project?: string; log?: (s: string) => void } = {}): Promise<{ faces: FaceSrc[]; missing: Missing[] }> {
+  const packed = builtinFonts();
+  const fits = (b: BuiltinFont) => !b.unicodes || !outside(text, b.unicodes).length;
+  const inBox = (name: string) => {
+    const list = packed.filter((b) => b.family === name);
+    return list.length && list.every(fits) ? list : null;
+  };
+  const faces: FaceSrc[] = [];
+  const miss: Missing[] = [];
+  await Promise.all(
+    [...new Set(families)].map(async (name) => {
+      const fam = FAMILIES.find((f) => f.family === name);
+      if (!fam) return;
+      const own = () => faces.push(...fam.files.map((f) => ({ family: name, weight: f.weight, url: `fonts/${localName(f.file)}` })));
+      if (fam.files.every(cached)) return void own();
+      const box = inBox(name);
+      if (box) return void faces.push(...box.map((b) => ({ family: name, weight: b.weight, url: `fonts/${b.file}` })));
+      try {
+        await fetchFamily(fam, o.log);
+        own();
+      } catch (err) {
+        const standName = fam.stand ?? name;
+        const stand = inBox(standName);
+        if (o.builtin && stand) {
+          // 그 얼굴 이름으로 내장 파일을 건다 — 플랜·컷은 그대로 두고 글자 모양만 바뀐다
+          for (const f of fam.files) faces.push({ family: name, weight: f.weight, url: `fonts/${stand[0].file}` });
+          return;
+        }
+        const m: Missing = { family: name, reason: why(err), ...(stand ? { stand: standName } : {}), ...(o.project ? { project: o.project } : {}) };
+        missing.set(name, m);
+        miss.push(m);
+      }
+    }),
+  );
+  return { faces, missing: miss };
+}
+
+/** kf doctor 한 줄 — cli/deps.ts 의 Check 꼴 */
+export function jizuraCheck() {
+  const info = engineInfo();
+  const ok = !!info && info.commit === JIZURA_COMMIT && builtinFonts().length > 0;
+  const packed = [...new Set(builtinFonts().map((f) => f.family))];
+  const rest = FAMILIES.filter((f) => !packed.includes(f.family) && f.lang !== "ja");
+  const have = rest.filter((f) => f.files.every(cached));
+  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)} 이 아니다)`} 내장 · 글꼴 내장 ${packed.length}·받아 둔 한국어 ${have.length}/${rest.length} — 나머지는 처음 쓸 때 받는다`
+      : "엔진이 패키지에 없다 — 깨진 설치",
+    fix: ok ? undefined : "레포면 node packages/jizura/src/vendor.ts, 설치본이면 kasaframe 를 다시 깐다",
+  };
+}
+
+/** kf setup jizura — 그 언어에서 내장에 없는 얼굴을 미리 받는다(오프라인으로 굽기 전에) */
+export async function install(langs: string[], log = console.log): Promise<void> {
+  const packed = new Set(builtinFonts().map((f) => f.family));
+  const want = FAMILIES.filter((f) => (f.lang === "common" || langs.includes(f.lang)) && !packed.has(f.family));
+  for (const fam of want) await fetchFamily(fam, log);
+  log(`  글꼴 ${want.length}개(${langs.join("·")}) → ${fontDir()} · 내장 ${packed.size}개는 패키지에(${[...packed].join("·")})`);
+}
+
+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 글꼴 받기 실패: ${why(err)}`);
+      process.exit(1);
+    },
+  );
+}

package/packages/jizura/src/layer.ts

@@ -0,0 +1,325 @@
+// JIZURA 字面(MIT, (c) 2026 hakoniwa) 엔진을 결정적인 가사 층으로 — 장면 위 캔버스 한 장에 시각 t 의 가사를 그린다.
+// 플랜 하나 = JIZURA 프로젝트 하나(곡 전체 가사·박). 같은 설정을 쓰는 장면끼리는 한 플랜을 나눠 쓰고, 장면마다 다른 플랜을 고른다.
+// 엔진은 패키지에 실려 있고(vendor/) 서버가 /@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 type { FaceSrc, Missing } from "./install.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;
+  }
+}
+
+/** jizura — 가사 층 · builtin — 가사 층인데 못 받은 얼굴은 내장 글꼴로 · words — 가사 층 없이 낱말(틀 장면이 DOM 으로). 사람이 고른다 */
+export type LyricsMode = "jizura" | "builtin" | "words";
+
+let modeJob: Promise<LyricsMode> | null = null;
+/** kf.json "lyrics"(kf lyrics use 가 적는다)를 페이지 주소 ?lyrics= 가 덮는다 */
+export function lyricsMode(): Promise<LyricsMode> {
+  modeJob ??= (async () => {
+    const q = new URLSearchParams(location.search).get("lyrics");
+    const v = q ?? (await getJson<{ lyrics?: unknown }>(new URL("kf.json", document.baseURI)))?.lyrics;
+    return v === "builtin" || v === "words" ? v : "jizura";
+  })();
+  return modeJob;
+}
+
+const registered = new Set<string>();
+
+// 그릴 얼굴의 파일을 서버가 골라 준다(vite.ts) — 받아 둔 원본 · 내장 서브셋 · 처음 쓰는 얼굴이면 받기.
+// 못 받은 얼굴이 있으면 던진다: CSS 대체 목록의 다른 글꼴로 조용히 그리지 않는다
+async function provide(families: string[], text: string): Promise<FaceSrc[]> {
+  const builtin = (await lyricsMode()) === "builtin";
+  const r = await fetch(`${URL_BASE}fonts`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ families, text, builtin }) });
+  if (!r.ok) throw new Error(`글꼴 서버 ${r.status}: ${await r.text()}`);
+  const { faces, missing } = (await r.json()) as { faces: FaceSrc[]; missing: Missing[] };
+  if (missing.length) throw new Error(`JIZURA 글꼴 ${missing.map((m) => m.family).join("·")} 을 못 받았다 — 대신 그리지 않는다(kf 가 끝에 고를 길을 찍는다)`);
+  return faces;
+}
+
+function addFace(family: string, f: FaceSrc): void {
+  const key = `${family}|${f.weight}|${f.url}`;
+  if (registered.has(key)) return;
+  registered.add(key);
+  document.fonts.add(new FontFace(family, `url(${URL_BASE}${f.url.split("/").map(encodeURIComponent).join("/")})`, { weight: f.weight, display: "block" }));
+}
+
+// 한국어·일본어는 CDN 에 묻지 않는다 — 렌더가 오프라인이어도, 늦게 온 조각 글꼴로 첫 프레임이 대체 글꼴이 되는 일도 없다
+const LOCAL = new Set(["ko", "ja"]);
+
+function localFonts(J: J): void {
+  const upstream = J.ensureFonts;
+  J.ensureFonts = async (text: string, keys: string[] | null) => {
+    if (!LOCAL.has(J.lang)) 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 });
+    // 太さ(@var)는 이름이 Noto Sans·Serif JP 인 가변 글꼴로 그린다 — 한국어면 그 이름에 가변 Noto Sans·Serif KR 을 건다(안 걸면 한글이 시스템 글꼴로 떨어진다)
+    const vary = !!keys?.includes("@var");
+    const varFaces = [["Noto Sans JP", "Noto Sans KR", 100, 900], ["Noto Serif JP", "Noto Serif KR", 200, 900]] as const;
+    const want = new Set(faces.map((f) => f.family.replace(/"/g, "")));
+    if (vary) for (const [jp, kr] of varFaces) want.add(J.lang === "ko" ? kr : jp);
+    const got = await provide([...want], text);
+    for (const f of got) addFace(f.family, f);
+    if (vary && J.lang === "ko") for (const [jp, kr] of varFaces) for (const f of got.filter((x) => x.family === kr)) addFace(jp, f);
+    const specs = new Set(faces.map((f) => `${f.weight} 64px ${f.family}`));
+    if (vary) for (const [jp, , lo, hi] of varFaces) specs.add(`${lo} 64px "${jp}"`).add(`${hi} 64px "${jp}"`);
+    await Promise.all([...specs].map((s) => document.fonts.load(s, uniq)));
+    J.glyphs.clear();
+    J.metrics.clear();
+  };
+}
+
+let engine: Promise<J> | null = null;
+
+/** 실린 엔진을 한 번만 싣는다. 못 실으면 던진다 — 깨진 설치를 낱말 화면으로 덮지 않는다 */
+export function loadJizura(): Promise<J> {
+  engine ??= (async () => {
+    if (window.J?.plan) return window.J;
+    await loadScript(`${URL_BASE}engine/jizura_engine.js`);
+    const J = window.J;
+    if (!J?.plan) throw new Error("JIZURA 엔진을 실었는데 window.J 가 없다");
+    localFonts(J);
+    return J;
+  })();
+  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 () => {
+      if ((await lyricsMode()) === "words") return null;
+      const [J, lyrics] = await Promise.all([loadJizura(), o.lyrics ? Promise.resolve(o.lyrics) : projectLyrics()]);
+      if (!lyrics?.lines.length) return null;
+      return buildPlan(J, settings, lyrics, o.ctx);
+    })();
+    plans.set(key, job);
+  }
+  return job;
+}
+
+/** 이 층이 그릴지 — 틀 장면이 낱말 화면을 고를 때. 가사가 없거나 사람이 「낱말로」를 골랐으면 false, 엔진을 못 실으면 던진다 */
+export async function jizuraReady(): Promise<boolean> {
+  if ((await lyricsMode()) === "words") return false;
+  const [, lyrics] = await Promise.all([loadJizura(), projectLyrics()]);
+  return !!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 };
+
+const told = new Set<string>();
+
+/** 장면 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;
+  let failed: unknown = null;
+  const ready = planFor(o).then(
+    (e) => (entry = e),
+    (err) => {
+      failed = err;
+      const msg = err instanceof Error ? err.message : String(err);
+      // 플랜은 장면끼리 나눠 쓴다 — 같은 실패를 장면마다 찍지 않는다
+      if (!told.has(msg)) console.error(`[kf] 가사 층(${ctx.id}): ${msg}`);
+      told.add(msg);
+      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;
+    if (failed) throw failed;
+    paint(want);
+  });
+  const draw = (t: number) => {
+    want = ctx.from + t;
+    paint(want);
+  };
+  return Object.assign(draw, { canvas });
+}