kasaframe 0.0.0-stage → 0.1.1

package/packages/plan/src/plan.ts

@@ -0,0 +1,125 @@
+import { detect, type Detection } from "./detect.ts";
+import { layoutScenes, pickDuration } from "./layout.ts";
+import { parseAspect, parseDuration, parseStyle, parseTitle } from "./request.ts";
+import { frameFor, listTemplates, loadTemplate } from "./templates.ts";
+import { pickTheme, suggestThemes, themeFromRequest } from "./themes.ts";
+import { basename } from "node:path";
+import type { Aspect, BeatsLike, GenSpec, Plan, PlannedScene, Purpose, Template } from "./types.ts";
+
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+
+// 이음매 기본은 모션그래픽 전환이다. 영상 모델은 요청에 분명히 적었을 때만 부른다(돈·시간이 크고 결이 들쭉날쭉하다)
+export function wantsVideo(request: string): boolean {
+  return /영상\s*생성|생성\s*영상|AI\s*영상|영상\s*모델|video\s*(gen|model)|generated\s*video/i.test(request);
+}
+
+export interface PlanInput {
+  request: string;
+  purpose?: Purpose; // 사람이 못 박으면 판별을 건너뛴다
+  assets?: string[];
+  music?: string | null;
+  beats?: BeatsLike | null;
+  duration?: number;
+  aspect?: Aspect;
+  style?: string;
+  title?: string;
+  theme?: string; // 테마 id 나 "auto"
+}
+
+export function makePlan(input: PlanInput): Plan {
+  const templates = listTemplates();
+  const det: Detection = input.purpose
+    ? { purpose: input.purpose, confidence: 1, ranked: [], ambiguous: false }
+    : detect({ request: input.request, assets: input.assets, music: input.music }, templates);
+  const tpl = loadTemplate(det.purpose);
+  const aspect = input.aspect ?? parseAspect(input.request);
+  const frame = frameFor(tpl, aspect && (aspect === tpl.aspect || tpl.variants?.[aspect]) ? aspect : undefined);
+  const { duration, notes } = pickDuration(tpl, { requested: input.duration ?? parseDuration(input.request), beats: input.beats });
+  const laid = layoutScenes(tpl, duration, input.beats);
+  // auto: 요청이 테마를 말로 짚었으면 그 테마, 아니면 내용에 맞는 approved 후보 셋 중 첫째
+  const named = input.theme === "auto" ? themeFromRequest(input.request, tpl.id) : null;
+  const themeCandidates = input.theme === "auto" ? [...(named ? [named] : []), ...suggestThemes(input.request, tpl.id, frame.aspect).filter((c) => c.id !== named?.id)].slice(0, 3) : undefined;
+  const theme = input.theme === "auto" ? (themeCandidates?.[0]?.id ?? null) : input.theme ? pickTheme(input.theme).id : null;
+  // 테마를 고르면 그 테마의 style 이 프리셋을 대신한다(kf new 가 themeStyle 로 쓴다)
+  const style = theme ?? input.style ?? parseStyle(input.request) ?? tpl.style;
+  const title = input.title ?? parseTitle(input.request) ?? "";
+  const gen = genSpecs(tpl, laid.scenes, { subject: title || input.request, style, width: frame.width, height: frame.height, video: wantsVideo(input.request), refs: (input.assets ?? []).filter((a) => IMAGE.test(a)).map((a) => `assets/in/${basename(a)}`) });
+
+  const scenes: PlannedScene[] = laid.scenes.map((s) => ({
+    id: s.id,
+    role: s.role,
+    from: s.from,
+    dur: s.dur,
+    idea: s.idea,
+    assets: gen.filter((g) => g.scene === s.id).map((g) => `gen:${g.kind}:${g.id}`),
+  }));
+
+  const top = det.ranked[0];
+  const plan: Plan = {
+    request: input.request,
+    purpose: det.purpose,
+    confidence: det.confidence,
+    alternatives: det.ranked.slice(1, 3).map((r) => ({ purpose: r.purpose, p: r.p })),
+    reasons: [...(top?.reasons ?? (input.purpose ? ["사람이 정함"] : [])), ...notes, ...laid.notes],
+    title,
+    aspect: frame.aspect,
+    width: frame.width,
+    height: frame.height,
+    fps: tpl.fps,
+    duration: laid.duration,
+    style,
+    music: input.music ?? null,
+    captions: tpl.captions,
+    deliverables: tpl.deliverables,
+    scenes,
+    gen,
+    theme,
+    ...(themeCandidates ? { themeCandidates } : {}),
+  };
+  if (det.ambiguous) {
+    plan.questions = [
+      {
+        id: "purpose",
+        ask: "어떤 용도의 영상인가?",
+        choices: det.ranked.slice(0, 4).map((r) => `${r.purpose} — ${templates.find((t) => t.id === r.purpose)?.label}`),
+      },
+    ];
+  }
+  if (tpl.music === "required" && !input.music) {
+    plan.questions = [...(plan.questions ?? []), { id: "music", ask: `${tpl.label} 영상은 곡이 끌고 간다. 쓸 곡 파일은?`, choices: [] }];
+  }
+  return plan;
+}
+
+// "img:hook-bg" → hook 장면 바탕 그림, "vid:seam" → seam 장면 전체를 채우는 이음매 클립(앞 장면 끝 프레임 → 뒤 장면 첫 프레임, 계약 8)
+function genSpecs(
+  tpl: Template,
+  scenes: { id: string; role: string; idea: string }[],
+  o: { subject: string; style: string; width: number; height: number; video: boolean; refs: string[] },
+): GenSpec[] {
+  const gen: GenSpec[] = [];
+  for (const spec of [...tpl.assets.gen, ...(o.video ? (tpl.assets.genVideo ?? []) : [])]) {
+    const [kind, id] = spec.split(":") as ["img" | "vid", string];
+    if (kind === "vid") {
+      const i = scenes.findIndex((s) => s.id === id);
+      if (i <= 0 || i === scenes.length - 1) continue;
+      gen.push({
+        id,
+        kind,
+        scene: id,
+        seam: true,
+        prompt: `${o.subject} — 「${scenes[i - 1].idea}」 화면에서 「${scenes[i + 1].idea}」 화면으로 이음매 없이 빨려 들어가는 카메라 이동. ${o.style} 결, 글자 없음.`,
+      });
+      continue;
+    }
+    // 뮤비 주인공은 받은 그림을 참조해 한 장 만들고, 나머지 그림은 그 주인공을 참조해 같은 얼굴로 간다
+    if (id === "character") {
+      gen.push({ id, kind, scene: scenes[0].id, prompt: `${o.subject} 뮤직비디오 주인공 캐릭터 — 정면 전신 한 명, 단색 바탕, 글자 없음. ${o.style} 결.`, size: `${o.width}x${o.height}`, ...(o.refs.length ? { refs: o.refs } : {}) });
+      continue;
+    }
+    const scene = scenes.find((s) => id === s.id || id.startsWith(`${s.id}-`)) ?? scenes[0];
+    const refs = gen.some((g) => g.id === "character") ? { refs: ["assets/gen/character.png"] } : {};
+    gen.push({ id, kind, scene: scene.id, prompt: `${o.subject} ${tpl.label} 영상 「${scene.idea}」 장면의 바탕 그림. ${o.style} 결, 글자·로고 없음.`, size: `${o.width}x${o.height}`, ...refs });
+  }
+  return gen;
+}

package/packages/plan/src/request.ts

@@ -0,0 +1,55 @@
+import type { Aspect } from "./types.ts";
+
+// 요청 글에서 사람이 못 박은 값만 뽑는다. 못 찾으면 undefined — 틀 기본값이 채운다.
+
+export function parseDuration(text: string): number | undefined {
+  const t = text.toLowerCase();
+  const min = t.match(/(\d+(?:\.\d+)?)\s*(?:분|min(?:ute)?s?\b)/);
+  const sec = t.match(/(\d+(?:\.\d+)?)\s*(?:초|s\b|sec(?:ond)?s?\b)/);
+  if (!min && !sec) {
+    if (/한\s*분|일\s*분/.test(t)) return 60;
+    if (/반\s*분/.test(t)) return 30;
+    return undefined;
+  }
+  return (min ? Number(min[1]) * 60 : 0) + (sec ? Number(sec[1]) : 0);
+}
+
+export function parseAspect(text: string): Aspect | undefined {
+  const t = text.toLowerCase();
+  if (/9\s*[:x×]\s*16|세로|vertical|portrait/.test(t)) return "9:16";
+  if (/1\s*[:x×]\s*1\b|정사각|square/.test(t)) return "1:1";
+  if (/16\s*[:x×]\s*9|가로|landscape|widescreen/.test(t)) return "16:9";
+  return undefined;
+}
+
+const STYLE_HINTS: [RegExp, string][] = [
+  [/카와이|kawaii|파스텔|pastel|귀여운|큐트|cute/i, "kawaii-pastel"],
+  [/카사텀|kasaterm/i, "kasaterm"],
+  [/\bog\b|오픈게이트웨이|opengateway|open gateway/i, "og"],
+  [/다크|어두운|dark|시네마틱|cinematic/i, "neutral-dark"],
+];
+
+export function parseStyle(text: string): string | undefined {
+  return STYLE_HINTS.find(([re]) => re.test(text))?.[1];
+}
+
+const SUBJECTS: [RegExp, string][] = [
+  [/카사텀|kasaterm/i, "kasaterm"],
+  [/\bog\b|오픈게이트웨이|opengateway|open gateway/i, "OpenGateway"],
+];
+
+// 아는 제품만 잡는다. 모르면 비워 두고 kf new(폴더 이름)·kf make(LLM)가 채운다 — 첫 낱말을 이름으로 찍으면 "15초" 같은 게 끝 카드에 뜬다
+export function parseTitle(text: string): string | undefined {
+  return SUBJECTS.find(([re]) => re.test(text))?.[1];
+}
+
+const ASCII_WORD = /^[a-z0-9 .:-]+$/i;
+
+// 영어 짧은 낱말("ad")이 "made" 같은 데 걸리지 않게 영문은 낱말 경계로, 한글은 그대로 찾는다
+export function mentions(text: string, word: string): boolean {
+  const t = text.toLowerCase();
+  const w = word.toLowerCase();
+  if (!ASCII_WORD.test(w)) return t.includes(w);
+  const esc = w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^a-z0-9])${esc}([^a-z0-9]|$)`).test(t);
+}

package/packages/plan/src/studio.ts

@@ -0,0 +1,53 @@
+// 말로 시작한 kf make 도 작업실이 떠 있으면 거기에 등록한다 — 페이지 「지난 작업」·실시간 미리보기로 보이게. 서버가 없으면 조용히 넘어간다
+const base = () => (process.env.KF_APP_URL ?? "http://127.0.0.1:5150").replace(/\/$/, "");
+
+async function post<T>(path: string, body: unknown): Promise<T | null> {
+  try {
+    const r = await fetch(`${base()}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(1500) });
+    return r.ok ? ((await r.json()) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface StudioLink {
+  id: string;
+  url: string;
+  send(p: { lines?: string[]; phase?: string; done?: boolean; ok?: boolean }): Promise<void>;
+  // console.error 로 찍는 진행 줄을 작업실로도 흘린다(모아서 0.5초마다)
+  mirror(): () => Promise<void>;
+}
+
+export async function attachStudio(o: { dir: string; request: string; model?: string; purpose?: string }): Promise<StudioLink | null> {
+  const r = await post<{ id: string; url: string }>("/api/jobs/attach", o);
+  if (!r) return null;
+  const send = async (p: Parameters<StudioLink["send"]>[0]) => {
+    await post(`/api/jobs/${r.id}/progress`, p);
+  };
+  return {
+    ...r,
+    send,
+    mirror() {
+      const orig = console.error;
+      let queue: string[] = [];
+      let chain = Promise.resolve();
+      const flush = () => {
+        if (!queue.length) return chain;
+        const lines = queue;
+        queue = [];
+        chain = chain.then(() => send({ lines }));
+        return chain;
+      };
+      const timer = setInterval(flush, 500);
+      console.error = (...args: unknown[]) => {
+        orig(...args);
+        queue.push(...args.map(String).join(" ").split("\n"));
+      };
+      return async () => {
+        clearInterval(timer);
+        console.error = orig;
+        await flush();
+      };
+    },
+  };
+}

package/packages/plan/src/templates.ts

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Aspect, PURPOSES, type Purpose, type SafeArea, type Template } from "./types.ts";
+
+export const templatesDir = fileURLToPath(new URL("../../../templates/", import.meta.url));
+
+export function listTemplates(): Template[] {
+  return readdirSync(templatesDir)
+    .filter((d) => existsSync(join(templatesDir, d, "template.json")))
+    .map((d) => loadTemplate(d))
+    .sort((a, b) => PURPOSES.indexOf(a.id) - PURPOSES.indexOf(b.id));
+}
+
+export function loadTemplate(id: string): Template {
+  const file = join(templatesDir, id, "template.json");
+  if (!existsSync(file)) {
+    const have = readdirSync(templatesDir).filter((d) => existsSync(join(templatesDir, d, "template.json")));
+    throw new Error(`틀 "${id}" 가 없다. 있는 틀: ${have.join(" ")}`);
+  }
+  return JSON.parse(readFileSync(file, "utf8")) as Template;
+}
+
+export function frameFor(tpl: Template, aspect?: Aspect): { aspect: Aspect; width: number; height: number; safeArea: SafeArea } {
+  if (!aspect || aspect === tpl.aspect) return { aspect: tpl.aspect, width: tpl.width, height: tpl.height, safeArea: tpl.safeArea };
+  const v = tpl.variants?.[aspect];
+  if (!v) throw new Error(`틀 ${tpl.id} 는 ${aspect} 를 받지 않는다(${[tpl.aspect, ...Object.keys(tpl.variants ?? {})].join("·")})`);
+  return { aspect, width: v.width, height: v.height, safeArea: v.safeArea ?? tpl.safeArea };
+}
+
+// 틀 고유(장면 id → 틀 기본) → 역할 공용 → 공용 기본. 뮤비처럼 장면 id 가 곡마다 바뀌는 틀은 틀 기본(scenes/default.ts)이 받는다
+export function sceneSkeleton(tpl: Purpose, sceneId: string, role: string): string {
+  const tries = [
+    join(templatesDir, tpl, "scenes", `${sceneId}.ts`),
+    join(templatesDir, tpl, "scenes", "default.ts"),
+    join(templatesDir, "_shared", "scenes", `${role}.ts`),
+    join(templatesDir, "_shared", "scenes", "default.ts"),
+  ];
+  const hit = tries.find((p) => existsSync(p));
+  if (!hit) throw new Error(`장면 뼈대가 없다: ${tries.join(" · ")}`);
+  return readFileSync(hit, "utf8");
+}

package/packages/plan/src/themes.ts

@@ -0,0 +1,48 @@
+import { listThemes, loadTheme, type Theme } from "@kasaframe/themes";
+import { parseTitle } from "./request.ts";
+import type { Aspect, Purpose } from "./types.ts";
+
+export interface ThemePick {
+  id: string;
+  why: string;
+}
+
+const words = (s: string) => s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length >= 2);
+
+// 자동 추천은 approved 테마만(SPEC 9). 요청 낱말이 테마 이름·비유·THEME.md 에 얼마나 나오나로 줄 세우고, 같으면 최근에 승인된 쪽
+export function suggestThemes(request: string, purpose: Purpose, aspect?: Aspect, n = 3): ThemePick[] {
+  const pool = listThemes({ status: "approved", purpose, ...(aspect ? { aspect } : {}) });
+  const ask = new Set(words(request));
+  const scored = pool.map((t) => {
+    const hay = `${t.name} ${t.metaphor} ${t.guide}`.toLowerCase();
+    const hit = [...ask].filter((w) => hay.includes(w));
+    return { t, score: hit.length, hit };
+  });
+  scored.sort((a, b) => b.score - a.score || (b.t.approvedAt ?? "").localeCompare(a.t.approvedAt ?? ""));
+  return scored.slice(0, n).map(({ t, hit }) => ({ id: t.id, why: hit.length ? `요청의 ${hit.slice(0, 3).map((w) => `「${w}」`).join("·")} 이(가) 테마 비유와 맞는다 — ${t.metaphor}` : `${purpose} 에 쓰는 승인 테마 — ${t.metaphor}` }));
+}
+
+// 「리소 느낌으로」처럼 사람이 말로 테마를 짚었는지 — 테마 이름 낱말(두 글자 넘게)·id 조각(세 글자 넘게)이 요청에 나오면 그 테마.
+// 사람이 짚은 것이라 review 까지 받는다(draft 는 빼고)
+export function themeFromRequest(request: string, purpose?: Purpose): ThemePick | null {
+  const t = request.toLowerCase();
+  let best: { th: Theme; score: number; hit: string[] } | null = null;
+  for (const th of listThemes({ status: ["approved", "review"] })) {
+    const keys = [...th.name.split(/\s+/).filter((w) => w.length >= 2), ...th.id.split("-").filter((w) => w.length >= 3)].map((w) => w.toLowerCase());
+    const hit = keys.filter((k) => t.includes(k));
+    if (!hit.length) continue;
+    // 제품 이름(「카사텀」·「OG」)은 무엇을 찍나일 뿐 결이 아니다 — 「카와이」·「리소」 같은 결 낱말보다 약하게, 「~ 느낌·풍·스타일」로 짚으면 가장 세게.
+    // 용도에 안 맞는 테마도 사람이 짚었으면 쓰되, 같은 점수면 용도에 맞는 쪽
+    const weight = (k: string) => (parseTitle(k) ? 4 : 10) + (new RegExp(`${k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*(느낌|풍|스타일|결|톤|테마|처럼)`).test(t) ? 20 : 0);
+    const score = hit.reduce((a, k) => a + weight(k), 0) + (purpose && th.purposes.includes(purpose) ? 1 : 0);
+    if (!best || score > best.score) best = { th, score, hit };
+  }
+  return best ? { id: best.th.id, why: `요청이 「${best.hit.join("·")}」 로 ${best.th.name} 을(를) 짚었다 — ${best.th.metaphor}` } : null;
+}
+
+// 사람이 고른 id 는 review 까지 쓴다. draft 는 테마 폴더 sample/ 안에서만이라 여기선 막는다
+export function pickTheme(id: string): Theme {
+  const t = loadTheme(id);
+  if (t.status === "draft") throw new Error(`테마 ${id} 는 아직 draft — 견본이 review 로 올라온 뒤에 쓴다`);
+  return t;
+}

package/packages/plan/src/types.ts

@@ -0,0 +1,106 @@
+export type Aspect = "16:9" | "9:16" | "1:1";
+export type Purpose = "promo" | "shorts" | "explainer" | "launch" | "demo" | "ad" | "square" | "mv";
+export const PURPOSES: Purpose[] = ["promo", "shorts", "explainer", "launch", "demo", "ad", "square", "mv"];
+
+export interface SafeArea { top: number; bottom: number; left: number; right: number }
+
+export interface TemplateScene {
+  id: string;
+  role: string;
+  sec?: number;
+  weight?: number;
+  anchor?: string; // start · end · drop:<k> · drop:last · section:<kind>
+  snap?: "bar" | "beat" | "none";
+  idea: string;
+  transition?: string; // 이음매 장면의 3D 전환 종류(dive·portal·cards·shatter·zoomOut·fold)
+}
+
+export interface Template {
+  id: Purpose;
+  label: string;
+  summary: string; // 틀 고르는 화면의 한 줄
+  aspect: Aspect;
+  width: number;
+  height: number;
+  fps: number;
+  variants?: Partial<Record<Aspect, { width: number; height: number; safeArea?: SafeArea }>>;
+  duration: { min: number; max: number; default: number; allowed?: number[] };
+  music: "required" | "optional" | "none";
+  // off: srt·vtt 만 · on: 화면에도 얹는다 · none: 없음 (옛 이름 track·burned 도 읽는다 — @kasaframe/motion/captions 의 captionMode)
+  captions: "off" | "on" | "none";
+  loop: boolean;
+  style: string;
+  safeArea: SafeArea;
+  text: { policy: "none" | "terms-only" | "captions" | "lyrics"; maxOnScreen: number; minPx: number };
+  // 뮤비: kinetic 이면 부른 낱말이 그 시각에 화면에 뜬다(lyrics.json 낱말 시각), track 이면 자막 트랙만
+  lyrics?: { mode: "kinetic" | "track" | "none"; align?: string; lipsync?: string };
+  motion: Record<string, unknown>;
+  scenes: TemplateScene[];
+  // sections: 곡 구간(beats.json sections)마다 장면 하나 — scenes 는 곡이 없을 때 쓰는 기본, sectionIdeas 는 구간 종류별 할 일
+  layout?: "fixed" | "sections";
+  sectionIdeas?: Record<string, string>;
+  // gen 은 늘 만드는 그림, genVideo 는 요청에 「영상 생성」을 분명히 적었을 때만(이음매 기본은 모션그래픽 전환)
+  assets: { need: string[]; want: string[]; gen: string[]; genVideo?: string[] };
+  deliverables: string[];
+  detect: { words: string[]; hints: string[]; aspect: Aspect; assetKinds?: string[] };
+}
+
+// SPEC 4 중 장면 배치에 쓰는 것만
+export interface BeatsLike {
+  duration: number;
+  beats: number[];
+  downbeats?: number[];
+  bars?: number[];
+  drops?: number[];
+  sections?: { t: number; kind: string; strength?: number }[];
+}
+
+export interface PlannedScene {
+  id: string;
+  role: string;
+  from: number;
+  dur: number;
+  idea: string;
+  assets: string[];
+}
+
+// SPEC 계약 8 — @kasaframe/gen 의 GenSpec 과 같은 꼴. 이음매(seam) 영상의 id 는 kf.json 장면 id 와 같다
+export interface GenSpec {
+  id: string;
+  kind: "img" | "vid";
+  scene?: string;
+  prompt: string;
+  size?: string;
+  transparent?: boolean;
+  quality?: string;
+  refs?: string[];
+  seam?: boolean;
+  dur?: number;
+  first?: string;
+  last?: string;
+  provider?: string;
+}
+
+export interface Plan {
+  request: string;
+  purpose: Purpose;
+  confidence: number;
+  alternatives: { purpose: Purpose; p: number }[];
+  reasons: string[];
+  title: string;
+  aspect: Aspect;
+  width: number;
+  height: number;
+  fps: number;
+  duration: number;
+  style: string;
+  music: string | null;
+  captions: Template["captions"];
+  deliverables: string[];
+  scenes: PlannedScene[];
+  gen: GenSpec[];
+  // 고른 테마(themes/<id>). auto 면 approved 후보 셋을 themeCandidates 에 남기고 첫째를 쓴다
+  theme?: string | null;
+  themeCandidates?: { id: string; why: string }[];
+  questions?: { id: string; ask: string; choices: string[] }[];
+}

package/packages/studio/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@kasaframe/studio",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "vite": "^8.3.3"
+  }
+}

package/packages/studio/src/index.ts

@@ -0,0 +1 @@
+export { studioPlugin, studioConfig, type StudioConfig } from "./plugin.ts";