kasaframe 0.1.1 → 0.1.4

package/packages/jizura/src/install.ts

@@ -1,27 +1,20 @@
-// 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";
+// 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 { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+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 { JIZURA_COMMIT, JIZURA_CREDIT, JIZURA_REPO, JIZURA_VERSION } from "./pin.ts";
+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 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;
@@ -31,181 +24,231 @@ export interface EngineInfo {
   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" },
+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")] },
 ];
-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);
+export const FONT_LANGS = ["ko", "ja"];
 
-const WEIGHT: Record<string, number> = { Thin: 100, ExtraLight: 200, Light: 300, Regular: 400, Medium: 500, SemiBold: 600, Bold: 700, ExtraBold: 800, Black: 900 };
+export const localName = (file: string): string => file.replace(/\[.*\]/, "-VF");
 
-const git = (args: string[], cwd?: string) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+export interface BuiltinFont {
+  family: string;
+  weight: string;
+  file: string;
+  /** 서브셋을 뜬 원본(google/fonts 파일 이름) */
+  from: string;
+  /** 서브셋이면 남긴 글자 범위 — 원본을 그대로 실은 것은 없다 */
+  unicodes?: string;
+}
 
-/** 고정 커밋만 얕게 받는다. 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;
+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;
 }
 
-/** 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;
+/** 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];
 }
 
-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();
+export function engineInfo(): EngineInfo | null {
+  const p = join(vendorDir, "engine.json");
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as EngineInfo) : null;
 }
 
-async function download(url: string, to: string): Promise<void> {
-  for (let i = 0; ; i++) {
+// 막힌 망에서는 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);
-      if (!r.ok) throw new Error(`${r.status}`);
-      writeFileSync(`${to}.part`, Buffer.from(await r.arrayBuffer()));
+      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) {
-      if (i >= 3) throw new Error(`${url} 를 못 받았다: ${err instanceof Error ? err.message : err}`);
+      last = why(err);
     }
   }
+  throw new Error(`${url} — ${last}`);
 }
 
-/** 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);
+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);
       }
-      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);
+    })();
+    jobs.set(fam.family, job);
+    job.catch(() => jobs.delete(fam.family));
   }
-  writeFileSync(manifestPath, JSON.stringify(out, null, 1));
-  return out;
+  return job;
 }
 
-export function engineInfo(): EngineInfo | null {
-  const p = join(engineDir(), "engine.json");
-  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as EngineInfo) : null;
+export interface FaceSrc {
+  family: string;
+  weight: string;
+  /** /@kf-jizura/ 아래 경로 */
+  url: string;
 }
 
-export function installedFonts(): FontFile[] {
-  const p = join(fontDir(), "fonts.json");
-  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf8")) as FontFile[]) : [];
+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 langs = [...new Set(installedFonts().map((f) => f.lang))].filter((l) => l !== "common");
-  const ok = !!info && info.commit === JIZURA_COMMIT && langs.length > 0;
+  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)} 이 아니다)`} · 글꼴 ${langs.join("·") || "없음"} — ${jizuraHome()}`
-      : "없음 — 뮤비 가사 키네틱(jizuraLayer)만 못 쓴다. 없으면 틀 장면은 DOM 낱말로 대신한다",
-    fix: ok ? undefined : "kf setup jizura  (일본어 가사도 쓰면 node packages/jizura/src/install.ts --lang ko,ja)",
+      ? `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 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()}`);
+  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]) {
@@ -219,7 +262,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
   install(langs).then(
     () => process.exit(0),
     (err) => {
-      console.error(`jizura 설치 실패: ${err instanceof Error ? err.message : err}`);
+      console.error(`jizura 글꼴 받기 실패: ${why(err)}`);
       process.exit(1);
     },
   );

package/packages/jizura/src/layer.ts

@@ -1,10 +1,11 @@
 // JIZURA 字面(MIT, (c) 2026 hakoniwa) 엔진을 결정적인 가사 층으로 — 장면 위 캔버스 한 장에 시각 t 의 가사를 그린다.
 // 플랜 하나 = JIZURA 프로젝트 하나(곡 전체 가사·박). 같은 설정을 쓰는 장면끼리는 한 플랜을 나눠 쓰고, 장면마다 다른 플랜을 고른다.
-// 엔진·글꼴은 kf setup jizura 가 ~/.cache/kasaframe/jizura 에 두고 서버가 /@kf-jizura/ 로 낸다(vite.ts).
+// 엔진은 패키지에 실려 있고(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/";
@@ -89,46 +90,78 @@ async function getJson<T>(url: string | URL): Promise<T | null> {
   }
 }
 
-interface FontFile { family: string; weight: string; file: string; lang: string }
+/** jizura — 가사 층 · builtin — 가사 층인데 못 받은 얼굴은 내장 글꼴로 · words — 가사 층 없이 낱말(틀 장면이 DOM 으로). 사람이 고른다 */
+export type LyricsMode = "jizura" | "builtin" | "words";
 
-// 받아 둔 글꼴이 있는 언어는 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));
+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 (!langs.has(J.lang) || keys?.includes("@var")) return upstream(text, keys);
+    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 });
-    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)));
+    // 太さ(@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 = null;
+let engine: Promise<J> | null = null;
 
-/** 엔진을 한 번만 싣는다. 깔지 않았으면 null — 부르는 쪽은 대체 화면으로 */
-export function loadJizura(): Promise<J | null> {
+/** 실린 엔진을 한 번만 싣는다. 못 실으면 던진다 — 깨진 설치를 낱말 화면으로 덮지 않는다 */
+export function loadJizura(): Promise<J> {
   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;
-    }
+    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;
 }
@@ -211,8 +244,9 @@ function planFor(o: LayerOptions): Promise<PlanEntry | null> {
   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 (!J || !lyrics?.lines.length) return null;
+      if (!lyrics?.lines.length) return null;
       return buildPlan(J, settings, lyrics, o.ctx);
     })();
     plans.set(key, job);
@@ -220,10 +254,11 @@ function planFor(o: LayerOptions): Promise<PlanEntry | null> {
   return job;
 }
 
-/** 엔진·가사가 다 있어 이 층이 그릴 수 있는지 — 틀 장면이 대체 화면을 고를 때 */
+/** 이 층이 그릴지 — 틀 장면이 낱말 화면을 고를 때. 가사가 없거나 사람이 「낱말로」를 골랐으면 false, 엔진을 못 실으면 던진다 */
 export async function jizuraReady(): Promise<boolean> {
-  const [J, lyrics] = await Promise.all([loadJizura(), projectLyrics()]);
-  return !!J && !!lyrics?.lines.length;
+  if ((await lyricsMode()) === "words") return false;
+  const [, lyrics] = await Promise.all([loadJizura(), projectLyrics()]);
+  return !!lyrics?.lines.length;
 }
 
 /** 컷 목록 — 어느 컷이 화면을 덮는지 찾을 때(layout·enter·hold·exit·decor·cam·trans) */
@@ -241,6 +276,8 @@ const drawOpts = (mode: DrawMode, scale: number) =>
 
 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 {
@@ -254,10 +291,15 @@ export function jizuraLayer(el: HTMLElement, o: LayerOptions): JizuraPaint {
   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) => {
-      console.warn(`[kf] 가사 층(${ctx.id}): ${err instanceof Error ? err.message : 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;
     },
   );
@@ -268,10 +310,11 @@ export function jizuraLayer(el: HTMLElement, o: LayerOptions): JizuraPaint {
     entry.R.frame(g, entry.plan, T, drawOpts(mode, canvas.width / entry.plan.W));
     drawn = T;
   };
-  // 플랜이 아직이면 그 seek 을 플랜이 설 때까지 붙든다 — 첫 프레임부터 가사가 찍힌다
+  // 플랜이 아직이면 그 seek 을 플랜이 설 때까지 붙든다 — 첫 프레임부터 가사가 찍힌다. 플랜을 못 세웠으면 그 프레임을 가사 없이 찍지 않고 던진다
   onSeek(async () => {
     if (want === null || drawn === want) return;
     await ready;
+    if (failed) throw failed;
     paint(want);
   });
   const draw = (t: number) => {

package/packages/jizura/src/pin.ts

@@ -1,5 +1,8 @@
-// 부품 이름·스타일의 색 구성 번호·거부 목록이 이 판에 맞춰져 있다. 판을 올리면 deny.ts 를 다시 보고 견본 스틸을 다시 찍는다 — 같은 seed 라도 컷이 다시 굴려진다
+// 부품 이름·스타일의 색 구성 번호·거부 목록이 이 판에 맞춰져 있다. 판을 올리면 deny.ts 를 다시 보고 견본 스틸을 다시 찍는다 — 같은 seed 라도 컷이 다시 굴려진다.
+// 올린 뒤에는 node packages/jizura/src/vendor.ts 로 vendor/ 를 다시 만든다
 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";
+// 글꼴은 google/fonts 의 이 커밋에서 받는다 — 같은 파일이라야 어느 기계에서든 같은 프레임이 나온다(install.ts 가 크기·sha256 을 맞춰 본다)
+export const GOOGLE_FONTS_COMMIT = "51303ca9e8ac9dcea7b12d307ba568fd0e6fcfca";