kasaframe 0.0.0-stage → 0.1.1

package/app/server/engine.ts

@@ -0,0 +1,415 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listTemplates, makePlan, type Plan, type Purpose, suggestThemes } from "@kasaframe/plan";
+import { loadTheme, themeCards, type ThemeStatus } from "@kasaframe/themes";
+import { captionMode } from "@kasaframe/motion/captions";
+
+// 화면과 상관없는 엔진 — HTTP 서버든 Electron 이든 컨테이너든 이걸 감싸기만 한다. 일은 전부 kf 명령을 자식 프로세스로 돌린다.
+
+const repo = fileURLToPath(new URL("../../", import.meta.url));
+const kfBin = join(repo, "packages/cli/src/kf.ts");
+export const dataDir = resolve(process.env.KF_APP_DIR ?? join(repo, "out", "app"));
+export const templatePreview = (id: string) => join(repo, "templates", id, "preview.png");
+// 5159 는 작업실 화면의 HMR 자리
+const PREVIEW_PORTS = [5151, 5152, 5153, 5154, 5155, 5156, 5157, 5158];
+
+export type Phase = "plan" | "scaffold" | "gen" | "scenes" | "render" | "check" | "done" | "waiting" | "failed";
+
+export interface JobInput {
+  request: string;
+  purpose?: Purpose | "auto";
+  music?: string;
+  assets?: string[]; // /api/upload 로 올린 파일 경로들 — 일 폴더 in/ 에 모아 kf make --assets 로 넘긴다
+  theme?: string; // 테마 id 나 "auto"
+  model?: string;
+  approve?: boolean;
+  title?: string;
+  captions?: "on" | "off"; // 화면 자막 — 안 주면 틀 기본
+}
+
+export interface Job {
+  id: string;
+  external?: boolean; // 말로 시작한 kf make 가 스스로 등록한 일 — 서버가 돌리지 않고 진행만 받는다
+  input: JobInput;
+  dir: string;
+  phase: Phase;
+  progress: number; // 렌더 진행 0..1
+  running: boolean;
+  createdAt: number;
+  previewUrl?: string;
+  log: string[];
+  error?: string;
+  checkPassed?: boolean;
+}
+
+export interface JobView extends Omit<Job, "log"> {
+  plan?: Plan;
+  kf?: unknown;
+  // alt — 자막을 반대로 다시 구운 판(video-자막.mp4 · video-자막없음.mp4). captions — 들릴 말(captions.json)이 있다
+  files: { video?: string; cover?: string; check?: string; alt?: string; captions?: string };
+}
+
+const PHASES: [RegExp, Phase][] = [
+  [/^용도 /, "scaffold"],
+  [/^생성 자산/, "gen"],
+  [/^계획 다듬/, "scaffold"],
+  [/^장면 \S+ 쓰는 중/, "scenes"],
+  [/^\s+\S+ \d+번째/, "scenes"],
+  [/^\s+\d+\/\d+ \(\d+%\)/, "render"],
+  [/^고치기 /, "scenes"],
+  [/^그림 검사/, "check"],
+];
+
+export class Engine extends EventEmitter {
+  jobs = new Map<string, Job>();
+  private procs = new Map<string, ChildProcess>();
+  private previews = new Map<string, { proc: ChildProcess; port: number }>();
+
+  constructor() {
+    super();
+    mkdirSync(join(dataDir, "jobs"), { recursive: true });
+    for (const id of readdirSync(join(dataDir, "jobs"))) {
+      const f = join(dataDir, "jobs", id, "job.json");
+      if (!existsSync(f)) continue;
+      const job: Job = { ...JSON.parse(readFileSync(f, "utf8")), running: false, previewUrl: undefined };
+      if (!["done", "failed", "waiting"].includes(job.phase)) job.phase = "failed";
+      this.jobs.set(id, job);
+    }
+  }
+
+  // 틀 고르는 화면용. still 은 templates/_shared/previews.ts 가 뽑아 둔 대표 한 장
+  templates() {
+    return listTemplates().map((t) => ({
+      id: t.id,
+      label: t.label,
+      summary: t.summary,
+      aspect: t.aspect,
+      aspects: [t.aspect, ...Object.keys(t.variants ?? {})],
+      width: t.width,
+      height: t.height,
+      duration: t.duration,
+      music: t.music,
+      captions: t.captions,
+      deliverables: t.deliverables,
+      scenes: t.scenes.map((s) => s.id),
+      still: existsSync(templatePreview(t.id)) ? `/api/templates/${t.id}/still.png` : null,
+    }));
+  }
+
+  // 만들기 전에 보여 줄 계획 — 곡 분석 없이 길이·장면 비율만. 사람이 용도를 고르면 판별을 건너뛰고, "auto" 거나 비우면 판별한다
+  plan(request: string, purpose?: Purpose | "auto", theme?: string): Plan {
+    return makePlan({ request, purpose: purpose && purpose !== "auto" ? purpose : undefined, theme });
+  }
+
+  // 목록은 approved 만(SPEC 9). all 이면 review·draft 도 — 테마 만드는 사람이 견본을 보는 자리
+  themes(o: { all?: boolean; purpose?: string; aspect?: string } = {}) {
+    const status: ThemeStatus[] = o.all ? ["approved", "review", "draft"] : ["approved"];
+    return themeCards({ status, ...(o.purpose ? { purpose: o.purpose } : {}), ...(o.aspect ? { aspect: o.aspect } : {}) }).map((c) => ({
+      ...c,
+      still: c.still ? `/api/themes/${c.id}/still` : null,
+      sample: c.sample ? `/api/themes/${c.id}/sample` : null,
+    }));
+  }
+
+  themeFile(id: string, which: "still" | "sample"): string | null {
+    return loadTheme(id).files[which];
+  }
+
+  suggest(request: string, purpose: Purpose) {
+    return { candidates: suggestThemes(request, purpose) };
+  }
+
+  // 테마 공장(kf theme) — new 는 뼈대·지시서까지 만들고 그 지시서를 받을 세션 명령을 돌려준다(테마는 그 세션이 만든다).
+  // review 는 굽기라 무겁다 — 하나씩, 진행은 themeTask 로. approve 는 사람이 화면에서 견본을 보고 누를 때만
+  private themeTasks = new Map<string, { running: boolean; log: string[]; code: number | null }>();
+
+  async themeNew(o: { id: string; refs: string[]; name?: string; like?: string; threeD?: boolean }): Promise<{ ok: boolean; command: string | null; log: string[] }> {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(o.id)) throw Object.assign(new Error("테마 id 는 영문 소문자·숫자·- 만"), { status: 400 });
+    if (!o.refs?.length) throw Object.assign(new Error("참고 자료(refs)가 하나는 있어야 한다"), { status: 400 });
+    const args = ["theme", "new", o.id, ...o.refs.flatMap((r) => ["--ref", r])];
+    if (o.name) args.push("--name", o.name);
+    if (o.like) args.push("--like", o.like);
+    if (o.threeD) args.push("--3d");
+    const { code, log } = await this.kf(args);
+    const at = log.findIndex((l) => l.includes("세션 열기"));
+    return { ok: code === 0, command: at >= 0 ? (log[at + 1]?.trim() ?? null) : null, log };
+  }
+
+  themeReview(id: string): { started: boolean } {
+    const cur = this.themeTasks.get(id);
+    if (cur?.running) throw Object.assign(new Error("이미 굽는 중"), { status: 409 });
+    const task = { running: true, log: [] as string[], code: null as number | null };
+    this.themeTasks.set(id, task);
+    void this.kf(["theme", "review", id, "--tabs", "2"], (l) => task.log.push(l)).then(({ code }) => {
+      task.running = false;
+      task.code = code;
+    });
+    return { started: true };
+  }
+
+  themeTask(id: string) {
+    const t = this.themeTasks.get(id);
+    return t ? { running: t.running, code: t.code, log: t.log.slice(-60) } : { running: false, code: null, log: [] };
+  }
+
+  async themeApprove(id: string) {
+    return this.kf(["theme", "approve", id]);
+  }
+
+  private kf(args: string[], onLine?: (l: string) => void): Promise<{ code: number; log: string[] }> {
+    return new Promise((done) => {
+      const log: string[] = [];
+      const proc = spawn(process.execPath, [kfBin, ...args], { cwd: repo, env: { ...process.env, CLAUDECODE: "" } });
+      for (const stream of [proc.stdout, proc.stderr]) {
+        let buf = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk: string) => {
+          buf += chunk;
+          const parts = buf.split(/\r?\n/);
+          buf = parts.pop() ?? "";
+          for (const l of parts) {
+            log.push(l);
+            onLine?.(l);
+          }
+        });
+      }
+      proc.on("close", (code) => done({ code: code ?? 1, log }));
+    });
+  }
+
+  create(input: JobInput): Job {
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const job: Job = { id, input, dir: join(dataDir, "jobs", id, "project"), phase: "plan", progress: 0, running: false, createdAt: Date.now(), log: [] };
+    this.jobs.set(id, job);
+    mkdirSync(join(dataDir, "jobs", id), { recursive: true });
+    const args = ["make", input.request, "--out", job.dir, "--model", input.model ?? "deepseek/deepseek-v4-pro"];
+    if (input.purpose && input.purpose !== "auto") args.push("--purpose", input.purpose);
+    if (input.music) args.push("--music", input.music);
+    const given = (input.assets ?? []).filter((a) => existsSync(a));
+    if (given.length) {
+      const inDir = join(dataDir, "jobs", id, "in");
+      mkdirSync(inDir, { recursive: true });
+      for (const a of given) copyFileSync(a, join(inDir, basename(a).replace(/^[a-z0-9]+-/, "")));
+      args.push("--assets", inDir);
+    }
+    if (input.title) args.push("--title", input.title);
+    if (input.theme) args.push("--theme", input.theme);
+    if (input.approve) args.push("--yes");
+    if (input.captions) args.push("--captions", input.captions);
+    this.run(job, args);
+    return job;
+  }
+
+  // 장면 카드에서 고친 뒤: 고른 장면만 다시 쓰고 렌더·검사
+  rewrite(id: string, scenes: string[]): Job {
+    const job = this.must(id);
+    this.run(job, ["make", "--rewrite", job.dir, "--scenes", scenes.join(","), "--model", job.input.model ?? "deepseek/deepseek-v4-pro"]);
+    return job;
+  }
+
+  // captions 를 주면 장면을 다시 쓰지 않고 자막만 켜고(끄고) 따로 굽는다 — 원본 video.mp4 는 그대로 두고 -자막 판을 옆에
+  rerender(id: string, o: { captions?: "on" | "off" } = {}): Job {
+    const job = this.must(id);
+    const caps = o.captions === "on" || o.captions === "off" ? ["--captions", o.captions, "--suffix"] : [];
+    this.run(job, ["make", "--finish", job.dir, "--model", job.input.model ?? "deepseek/deepseek-v4-pro", "--fix", "0", ...caps]);
+    return job;
+  }
+
+  // 말로 시작한 kf make(Claude Code 등)가 스스로 등록한다 — 같은 폴더면 같은 일(--finish 가 다시 붙는다)
+  attach(o: { dir: string; request: string; model?: string; purpose?: Purpose }): Job {
+    const dir = resolve(o.dir);
+    const had = [...this.jobs.values()].find((j) => j.dir === dir);
+    if (had) return had;
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const job: Job = { id, external: true, input: { request: o.request, model: o.model, purpose: o.purpose }, dir, phase: "scaffold", progress: 0, running: true, createdAt: Date.now(), log: [] };
+    this.jobs.set(id, job);
+    mkdirSync(join(dataDir, "jobs", id), { recursive: true });
+    if (existsSync(join(dir, "kf.json"))) this.startPreview(job);
+    this.save(job);
+    this.emit("state", this.view(id));
+    return job;
+  }
+
+  progress(id: string, p: { lines?: string[]; phase?: Phase; done?: boolean; ok?: boolean }): void {
+    const job = this.must(id);
+    for (const line of p.lines ?? []) {
+      job.log.push(line);
+      for (const [re, phase] of PHASES) if (re.test(line)) job.phase = phase;
+      const pct = line.match(/\((\d+)%\)/);
+      if (pct && job.phase === "render") job.progress = Number(pct[1]) / 100;
+      this.emit("log", id, line);
+    }
+    if (job.log.length > 800) job.log.splice(0, job.log.length - 800);
+    if (p.phase) job.phase = p.phase;
+    job.running = !p.done;
+    if (p.done) {
+      job.checkPassed = !!p.ok;
+      job.phase = p.phase ?? (existsSync(join(job.dir, "out", "video.mp4")) ? "done" : "failed");
+      this.stopPreview(job);
+    } else if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+    this.save(job);
+    this.emit("state", this.view(id));
+  }
+
+  editScene(id: string, sceneId: string, patch: { idea?: string; dur?: number }): unknown {
+    const job = this.must(id);
+    const kfPath = join(job.dir, "kf.json");
+    const kf = JSON.parse(readFileSync(kfPath, "utf8"));
+    const i = kf.scenes.findIndex((s: { id: string }) => s.id === sceneId);
+    if (i < 0) throw new Error(`장면 ${sceneId} 가 없다`);
+    if (patch.idea !== undefined) kf.scenes[i].idea = patch.idea;
+    // 시간표는 빈틈 없이 이어져야 한다(계약 6) — 길이를 바꾸면 다음 장면 시작이 따라 움직인다
+    if (patch.dur !== undefined && i < kf.scenes.length - 1) {
+      const next = kf.scenes[i + 1];
+      const end = next.from + next.dur;
+      const dur = Math.round(Math.max(0.5, Math.min(patch.dur, end - kf.scenes[i].from - 0.5)) * kf.fps) / kf.fps;
+      kf.scenes[i].dur = +dur.toFixed(4);
+      next.from = +(kf.scenes[i].from + dur).toFixed(4);
+      next.dur = +(end - next.from).toFixed(4);
+    }
+    writeFileSync(kfPath, `${JSON.stringify(kf, null, 2)}\n`);
+    const planPath = join(job.dir, "plan.json");
+    if (existsSync(planPath) && patch.idea !== undefined) {
+      const plan = JSON.parse(readFileSync(planPath, "utf8"));
+      const s = plan.scenes?.find((x: { id: string }) => x.id === sceneId);
+      if (s) s.idea = patch.idea;
+      writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+    }
+    this.emit("state", this.view(id));
+    return kf;
+  }
+
+  view(id: string): JobView {
+    const job = this.must(id);
+    const read = (f: string) => (existsSync(join(job.dir, f)) ? JSON.parse(readFileSync(join(job.dir, f), "utf8")) : undefined);
+    const has = (f: string) => (existsSync(join(job.dir, f)) ? f : undefined);
+    const { log: _log, ...rest } = job;
+    const kf = read("kf.json");
+    const alt = has(captionMode(kf?.captions) === "on" ? "out/video-자막없음.mp4" : "out/video-자막.mp4");
+    return { ...rest, plan: read("plan.json"), kf, files: { video: has("out/video.mp4"), cover: has("out/cover.png"), check: has("out/check.json"), alt, captions: has("captions.json") } };
+  }
+
+  list(): JobView[] {
+    return [...this.jobs.keys()].map((id) => this.view(id)).sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  logOf(id: string): string[] {
+    return this.must(id).log;
+  }
+
+  stop(id: string): void {
+    this.procs.get(id)?.kill("SIGTERM");
+  }
+
+  async close(): Promise<void> {
+    for (const p of this.procs.values()) p.kill("SIGTERM");
+    for (const p of this.previews.values()) p.proc.kill("SIGTERM");
+  }
+
+  private must(id: string): Job {
+    const job = this.jobs.get(id);
+    if (!job) throw Object.assign(new Error(`일 ${id} 가 없다`), { status: 404 });
+    return job;
+  }
+
+  private run(job: Job, args: string[]): void {
+    if (job.running) throw Object.assign(new Error("이미 돌고 있다"), { status: 409 });
+    job.running = true;
+    job.error = undefined;
+    job.progress = 0;
+    const proc = spawn(process.execPath, [kfBin, ...args], { cwd: repo, env: { ...process.env, CLAUDECODE: "" } });
+    this.procs.set(job.id, proc);
+    const onLine = (line: string) => {
+      if (!line.trim()) return;
+      job.log.push(line);
+      if (job.log.length > 800) job.log.splice(0, job.log.length - 800);
+      for (const [re, phase] of PHASES) if (re.test(line)) job.phase = phase;
+      const pct = line.match(/\((\d+)%\)/);
+      if (pct && job.phase === "render") job.progress = Number(pct[1]) / 100;
+      if (/^검사:/.test(line)) job.phase = "check";
+      this.emit("log", job.id, line);
+      if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+      this.emit("state", this.view(job.id));
+    };
+    for (const stream of [proc.stdout, proc.stderr]) {
+      let buf = "";
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk: string) => {
+        buf += chunk;
+        const parts = buf.split(/\r?\n|\r/);
+        buf = parts.pop() ?? "";
+        parts.forEach(onLine);
+      });
+    }
+    proc.on("close", (code) => {
+      this.procs.delete(job.id);
+      job.running = false;
+      // 다 만들었으면 화면은 MP4 를 튼다 — 미리보기 서버는 꺼서 기계 부하를 줄인다(다시 보려면 /preview 가 다시 띄운다)
+      this.stopPreview(job);
+      job.checkPassed = code === 0;
+      if (code === 0) job.phase = "done";
+      else if (code === 3) job.phase = "waiting";
+      else {
+        job.phase = existsSync(join(job.dir, "out", "video.mp4")) ? "done" : "failed";
+        job.error = job.log.slice(-6).join("\n");
+      }
+      job.progress = job.phase === "done" ? 1 : job.progress;
+      this.save(job);
+      this.emit("state", this.view(job.id));
+    });
+    this.save(job);
+  }
+
+  // 만드는 동안 장면 파일이 쓰일 때마다 미리보기가 저절로 새로 고쳐진다(kf preview 의 감시)
+  private startPreview(job: Job): void {
+    if (this.previews.has(job.id)) return;
+    const used = new Set([...this.previews.values()].map((p) => p.port));
+    let port = PREVIEW_PORTS.find((p) => !used.has(p));
+    if (port === undefined) {
+      const [oldest] = this.previews.keys();
+      const old = this.previews.get(oldest)!;
+      old.proc.kill("SIGTERM");
+      this.previews.delete(oldest);
+      const j = this.jobs.get(oldest);
+      if (j) j.previewUrl = undefined;
+      port = old.port;
+    }
+    const proc = spawn(process.execPath, [kfBin, "preview", job.dir, "--port", String(port)], { cwd: repo, stdio: ["ignore", "pipe", "pipe"] });
+    this.previews.set(job.id, { proc, port });
+    job.previewUrl = `http://127.0.0.1:${port}/`;
+    const grab = (chunk: Buffer) => {
+      const m = chunk.toString().match(/https?:\/\/[^\s]+/);
+      if (m) {
+        job.previewUrl = m[0];
+        this.emit("state", this.view(job.id));
+      }
+    };
+    proc.stdout?.on("data", grab);
+    proc.stderr?.on("data", grab);
+    proc.on("close", () => {
+      if (this.previews.get(job.id)?.proc === proc) this.previews.delete(job.id);
+    });
+  }
+
+  private stopPreview(job: Job): void {
+    const p = this.previews.get(job.id);
+    if (!p) return;
+    p.proc.kill("SIGTERM");
+    this.previews.delete(job.id);
+    job.previewUrl = undefined;
+  }
+
+  previewFor(id: string): string | undefined {
+    const job = this.must(id);
+    if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+    return job.previewUrl;
+  }
+
+  private save(job: Job): void {
+    const { previewUrl: _p, running: _r, ...rest } = job;
+    writeFileSync(join(dataDir, "jobs", job.id, "job.json"), `${JSON.stringify(rest, null, 2)}\n`);
+  }
+}

package/app/server/main.ts

@@ -0,0 +1,205 @@
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { basename, extname, join, normalize, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import { createServer as createVite } from "vite";
+import { dataDir, Engine, templatePreview } from "./engine.ts";
+
+// 작업실 = 이 엔진 서버(API + SSE) + 그 API 만 쓰는 웹 화면. Electron·컨테이너로 갈 때도 이 파일만 감싼다.
+
+const port = Number(process.env.KF_APP_PORT ?? 5150);
+const host = process.env.KF_APP_HOST ?? "127.0.0.1";
+const webRoot = fileURLToPath(new URL("../web/", import.meta.url));
+const uploads = join(dataDir, "uploads");
+// 곡 모음 — kf make 와 같은 자리(레포 music/, KF_MUSIC_DIR 이 있으면 그쪽)
+const musicDir = process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../music/", import.meta.url));
+mkdirSync(uploads, { recursive: true });
+
+const engine = new Engine();
+// 이 기계에서는 fs 이벤트 감시가 바뀐 파일을 못 알려 옛 모듈을 내줬다 — 작은 폴더라 훑기로 본다
+const vite = await createVite({ root: webRoot, configFile: false, logLevel: "warn", clearScreen: false, server: { middlewareMode: true, hmr: { port: port + 9 }, watch: { usePolling: true, interval: 1000 } }, appType: "spa" });
+
+const TYPES: Record<string, string> = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml", ".webm": "video/webm", ".m4v": "video/mp4", ".mp4": "video/mp4", ".png": "image/png", ".json": "application/json", ".srt": "text/plain; charset=utf-8", ".vtt": "text/vtt", ".mov": "video/quicktime", ".mp3": "audio/mpeg", ".wav": "audio/wav" };
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+const IMAGE = /\.(png|jpe?g|webp|gif|svg)$/i;
+const VIDEO = /\.(mp4|mov|webm|m4v)$/i;
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(body));
+}
+
+async function body<T>(req: IncomingMessage): Promise<T> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  return (chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : {}) as T;
+}
+
+// 폰 사파리는 Range 를 못 받으면 영상을 안 튼다
+function serveFile(req: IncomingMessage, res: ServerResponse, file: string): void {
+  const size = statSync(file).size;
+  const type = TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+  const range = req.headers.range?.match(/bytes=(\d*)-(\d*)/);
+  const disposition = new URL(req.url ?? "", "http://x").searchParams.has("download") ? { "content-disposition": `attachment; filename="${basename(file)}"` } : {};
+  if (range) {
+    const start = range[1] ? Number(range[1]) : 0;
+    const end = range[2] ? Math.min(Number(range[2]), size - 1) : size - 1;
+    res.writeHead(206, { "content-type": type, "content-range": `bytes ${start}-${end}/${size}`, "accept-ranges": "bytes", "content-length": end - start + 1, ...disposition });
+    createReadStream(file, { start, end }).pipe(res);
+    return;
+  }
+  res.writeHead(200, { "content-type": type, "content-length": size, "accept-ranges": "bytes", "cache-control": "no-store", ...disposition });
+  createReadStream(file).pipe(res);
+}
+
+function sse(req: IncomingMessage, res: ServerResponse, jobId?: string): void {
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+  const write = (event: string, data: unknown) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  if (jobId) {
+    write("state", engine.view(jobId));
+    for (const line of engine.logOf(jobId).slice(-200)) write("log", line);
+  }
+  const onState = (v: { id: string }) => (!jobId || v.id === jobId) && write("state", v);
+  const onLog = (id: string, line: string) => jobId === id && write("log", line);
+  engine.on("state", onState);
+  engine.on("log", onLog);
+  const ping = setInterval(() => res.write(": ping\n\n"), 15000);
+  req.on("close", () => {
+    clearInterval(ping);
+    engine.off("state", onState);
+    engine.off("log", onLog);
+  });
+}
+
+async function api(req: IncomingMessage, res: ServerResponse, path: string): Promise<void> {
+  const method = req.method ?? "GET";
+  const m = path.match(/^\/api\/jobs\/([\w-]+)(?:\/(.*))?$/);
+  if (path === "/api/templates") return send(res, 200, engine.templates());
+  const still = path.match(/^\/api\/templates\/([a-z]+)\/still\.png$/);
+  if (still) {
+    const f = templatePreview(still[1]);
+    return existsSync(f) ? serveFile(req, res, f) : send(res, 404, { error: "대표 그림이 없다 — node templates/_shared/previews.ts" });
+  }
+  if (path === "/api/plan" && method === "POST") {
+    const b = await body<{ request: string; purpose?: never; theme?: string }>(req);
+    // purpose: 틀 id 면 그 틀로, "auto" 거나 없으면 요청 글로 판별. theme: id 나 "auto"
+    return send(res, 200, engine.plan(b.request ?? "", b.purpose, b.theme));
+  }
+  if (path === "/api/themes" && method === "GET") {
+    const q = new URL(req.url ?? "", "http://x").searchParams;
+    return send(res, 200, engine.themes({ all: q.get("all") === "1", purpose: q.get("purpose") ?? undefined, aspect: q.get("aspect") ?? undefined }));
+  }
+  if (path === "/api/themes/suggest" && method === "POST") {
+    const b = await body<{ request: string; purpose: never }>(req);
+    return send(res, 200, engine.suggest(b.request ?? "", b.purpose));
+  }
+  if (path === "/api/themes/new" && method === "POST") return send(res, 200, await engine.themeNew(await body(req)));
+  const themeAct = path.match(/^\/api\/themes\/([\w-]+)\/(review|approve)$/);
+  if (themeAct) {
+    const [, id, act] = themeAct;
+    if (act === "review") return send(res, method === "POST" ? 202 : 200, method === "POST" ? engine.themeReview(id) : engine.themeTask(id));
+    if (method === "POST") return send(res, 200, await engine.themeApprove(id));
+  }
+  const themeFile = path.match(/^\/api\/themes\/([\w-]+)\/(still|sample)$/);
+  if (themeFile) {
+    const f = engine.themeFile(themeFile[1], themeFile[2] as "still" | "sample");
+    return f && existsSync(f) ? serveFile(req, res, f) : send(res, 404, { error: "테마 견본이 없다" });
+  }
+  if (path === "/api/events") return sse(req, res);
+  if (path === "/api/jobs" && method === "GET") return send(res, 200, engine.list());
+  if (path === "/api/jobs" && method === "POST") {
+    const b = await body<Parameters<Engine["create"]>[0]>(req);
+    if (!b.request?.trim()) return send(res, 400, { error: "요청 글이 비었다" });
+    return send(res, 201, engine.view(engine.create(b).id));
+  }
+  if (path === "/api/jobs/attach" && method === "POST") {
+    const job = engine.attach(await body(req));
+    return send(res, 200, { id: job.id, url: `http://${req.headers.host}/?job=${job.id}` });
+  }
+  if (path === "/api/music") {
+    const lib = musicDir;
+    // url 은 미리 듣기(Range) — 올린 곡은 /api/uploads, 곡 모음은 /api/music/<파일>
+    const list = (dir: string | undefined, base: string) =>
+      dir && existsSync(dir) ? readdirSync(dir).filter((f) => AUDIO.test(f)).map((f) => ({ name: f.replace(/^[a-z0-9]+-(?=.)/, base === "uploads" ? "" : "$&"), path: join(dir, f), url: `/api/${base}/${encodeURIComponent(f)}` })) : [];
+    return send(res, 200, [...list(uploads, "uploads"), ...list(lib, "music")]);
+  }
+  const song = path.match(/^\/api\/music\/(.+)$/);
+  if (song && method === "GET") {
+    const f = join(musicDir, basename(decodeURIComponent(song[1])));
+    return f && existsSync(f) ? serveFile(req, res, f) : send(res, 404, { error: "곡이 없다" });
+  }
+  // 올린 그림·영상 — POST /api/jobs 의 assets 로 다시 보낸다
+  if (path === "/api/assets") {
+    const list = readdirSync(uploads).filter((f) => IMAGE.test(f) || VIDEO.test(f)).map((f) => ({
+      name: f.replace(/^[a-z0-9]+-/, ""),
+      path: join(uploads, f),
+      kind: IMAGE.test(f) ? "image" : "video",
+      size: statSync(join(uploads, f)).size,
+      url: `/api/uploads/${encodeURIComponent(f)}`,
+    }));
+    return send(res, 200, list);
+  }
+  const up = path.match(/^\/api\/uploads\/(.+)$/);
+  if (up && method === "GET") {
+    const f = join(uploads, basename(decodeURIComponent(up[1])));
+    return existsSync(f) ? serveFile(req, res, f) : send(res, 404, { error: "파일이 없다" });
+  }
+  if (path === "/api/upload" && method === "POST") {
+    const name = basename(new URL(req.url ?? "", "http://x").searchParams.get("name") ?? "upload.bin").replace(/[^\w.\-가-힣]/g, "_");
+    const file = join(uploads, `${Date.now().toString(36)}-${name}`);
+    await pipeline(req, createWriteStream(file));
+    return send(res, 201, { name, path: file });
+  }
+  if (!m) return send(res, 404, { error: "없는 길" });
+  const [, id, rest = ""] = m;
+  if (!rest && method === "GET") return send(res, 200, engine.view(id));
+  if (rest === "events") return sse(req, res, id);
+  if (rest === "log") return send(res, 200, engine.logOf(id));
+  if (rest === "progress" && method === "POST") {
+    engine.progress(id, await body(req));
+    return send(res, 200, { ok: true });
+  }
+  if (rest === "preview") return send(res, 200, { url: engine.previewFor(id) ?? null });
+  if (rest === "stop" && method === "POST") {
+    engine.stop(id);
+    return send(res, 200, { ok: true });
+  }
+  if (rest === "render" && method === "POST") return send(res, 200, engine.view(engine.rerender(id, await body<{ captions?: "on" | "off" }>(req)).id));
+  if (rest === "rewrite" && method === "POST") {
+    const b = await body<{ scenes: string[] }>(req);
+    return send(res, 200, engine.view(engine.rewrite(id, b.scenes ?? []).id));
+  }
+  const scene = rest.match(/^scenes\/([\w-]+)$/);
+  if (scene && method === "PATCH") return send(res, 200, engine.editScene(id, scene[1], await body(req)));
+  const file = rest.match(/^files\/(.+)$/);
+  if (file && method === "GET") {
+    const dir = engine.view(id).dir;
+    const p = resolve(dir, normalize(decodeURIComponent(file[1])));
+    if (!p.startsWith(dir) || !existsSync(p) || statSync(p).isDirectory()) return send(res, 404, { error: "파일이 없다" });
+    return serveFile(req, res, p);
+  }
+  return send(res, 404, { error: "없는 길" });
+}
+
+const server = createServer(async (req, res) => {
+  const path = new URL(req.url ?? "/", "http://x").pathname;
+  if (!path.startsWith("/api/")) return vite.middlewares(req, res);
+  try {
+    await api(req, res, path);
+  } catch (e) {
+    const err = e as Error & { status?: number };
+    if (!res.headersSent) send(res, err.status ?? 500, { error: err.message });
+  }
+});
+
+server.listen(port, host, () => console.log(`작업실 http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/  (일 폴더 ${dataDir})`));
+
+const shutdown = async () => {
+  await engine.close();
+  await vite.close();
+  server.close();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/app/web/env.d.ts

@@ -0,0 +1,2 @@
+// Vite 가 CSS 를 모듈로 가져온다
+declare module "*.css";

package/app/web/icons.ts

@@ -0,0 +1,31 @@
+// 선 굵기 하나(1.75)·둥근 끝으로 맞춘 24px 아이콘. 이모지 대신 쓴다.
+const PATHS = {
+  back: '<path d="M15 6l-6 6 6 6"/>',
+  next: '<path d="M9 6l6 6-6 6"/>',
+  arrow: '<path d="M5 12h14M13 6l6 6-6 6"/>',
+  upload: '<path d="M12 15V4M7 9l5-5 5 5"/><path d="M4 15v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3"/>',
+  music: '<path d="M9 18V6l11-2v12"/><circle cx="6.5" cy="18" r="2.5"/><circle cx="17.5" cy="16" r="2.5"/>',
+  image: '<rect x="3.5" y="4.5" width="17" height="15" rx="2"/><circle cx="9" cy="10" r="1.75"/><path d="M20.5 15.5l-5-5-9 9"/>',
+  video: '<rect x="3" y="6" width="13" height="12" rx="2"/><path d="M16 10.5l5-3v9l-5-3z"/>',
+  play: '<path d="M8 5.5v13l10.5-6.5z" fill="currentColor" stroke="none"/>',
+  pause: '<path d="M7.5 5.5h3v13h-3zM13.5 5.5h3v13h-3z" fill="currentColor" stroke="none"/>',
+  close: '<path d="M6 6l12 12M18 6L6 18"/>',
+  check: '<path d="M5 12.5l4.5 4.5L19 7.5"/>',
+  download: '<path d="M12 4v11M7 10l5 5 5-5"/><path d="M4 18v1a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-1"/>',
+  redo: '<path d="M20 11a8 8 0 1 0-2.3 5.6"/><path d="M20 4v7h-7"/>',
+  stop: '<rect x="6.5" y="6.5" width="11" height="11" rx="1.5" fill="currentColor" stroke="none"/>',
+  history: '<path d="M3.5 12a8.5 8.5 0 1 0 2.5-6"/><path d="M3.5 4.5V9H8"/><path d="M12 8v4.5l3 2"/>',
+  caption: '<rect x="3" y="5.5" width="18" height="13" rx="2"/><path d="M10 10.5a2 2 0 1 0 0 3M17 10.5a2 2 0 1 0 0 3"/>',
+  warn: '<path d="M12 4l9 16H3z"/><path d="M12 10v4M12 17v.5"/>',
+  edit: '<path d="M4 20h4L19 9l-4-4L4 16z"/><path d="M13.5 6.5l4 4"/>',
+  plus: '<path d="M12 5v14M5 12h14"/>',
+  copy: '<rect x="8.5" y="8.5" width="11" height="11" rx="2"/><path d="M15.5 8.5V6a1.5 1.5 0 0 0-1.5-1.5H6A1.5 1.5 0 0 0 4.5 6v8A1.5 1.5 0 0 0 6 15.5h2.5"/>',
+} as const;
+
+export type IconName = keyof typeof PATHS;
+
+export function icon(name: IconName, size = 18): SVGSVGElement {
+  const t = document.createElement("template");
+  t.innerHTML = `<svg viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${PATHS[name]}</svg>`;
+  return t.content.firstChild as SVGSVGElement;
+}