@hanmariyang/drafting 1.6.2

package/api/dist/lib/lint.js

@@ -0,0 +1,141 @@
+// Consistency compiler (§4) — deterministic, AI-free. Pure function over plan
+// items so it is exhaustively unit-testable. Only ACCEPTED items are checked.
+function meta(item) {
+    try {
+        return JSON.parse(item.meta || '{}');
+    }
+    catch {
+        return {};
+    }
+}
+function links(item) {
+    return meta(item).links ?? {};
+}
+function allLinkRefs(l) {
+    return [...(l.reqs ?? []), ...(l.pages ?? []), ...(l.flows ?? []), ...(l.features ?? [])];
+}
+/**
+ * Run rule v1 (6 rules) over a project's plan items. `reqIds` = the valid
+ * REQ-nn ids derived from the PRD's accepted sections (§1.2).
+ */
+export function lintProject(items, reqIds) {
+    const out = [];
+    const reqSet = new Set(reqIds);
+    const byRef = new Map();
+    for (const it of items)
+        byRef.set(it.ref_id, it);
+    const accepted = items.filter((i) => i.status === 'accepted');
+    // ── E-DUP-REF: duplicate ref_id within the same document ──────────────────
+    const seen = new Map(); // `${doc}:${ref}` -> ref
+    const dupped = new Set();
+    for (const it of accepted) {
+        const key = `${it.document_id}:${it.ref_id}`;
+        if (seen.has(key))
+            dupped.add(it.ref_id);
+        else
+            seen.set(key, it.ref_id);
+    }
+    for (const ref of dupped) {
+        out.push({
+            code: 'E-DUP-REF',
+            message: `중복 ref_id "${ref}" — 같은 문서에 같은 번호가 둘 이상 있습니다.`,
+            refs: [ref],
+            severity: 'E',
+        });
+    }
+    // ── E-BROKEN-REF: a link points at a ref that doesn't exist or is rejected ─
+    for (const it of accepted) {
+        for (const ref of allLinkRefs(links(it))) {
+            let broken = false;
+            if (/^REQ-/.test(ref)) {
+                broken = !reqSet.has(ref);
+            }
+            else {
+                const target = byRef.get(ref);
+                broken = !target || target.status === 'rejected';
+            }
+            if (broken) {
+                out.push({
+                    code: 'E-BROKEN-REF',
+                    message: `${it.ref_id} 이(가) 존재하지 않거나 거절된 ${ref} 를 참조합니다.`,
+                    refs: [it.ref_id, ref],
+                    severity: 'E',
+                });
+            }
+        }
+    }
+    // ── W-ORPHAN-SPEC: accepted feature with zero reqs links ──────────────────
+    for (const it of accepted) {
+        if (it.kind !== 'feature')
+            continue;
+        if ((links(it).reqs ?? []).length === 0) {
+            out.push({
+                code: 'W-ORPHAN-SPEC',
+                message: `${it.ref_id} "${it.title}" 이(가) 어느 요구(REQ)에도 연결되지 않았습니다.`,
+                refs: [it.ref_id],
+                severity: 'W',
+            });
+        }
+    }
+    // ── W-UNREACHED-PAGE: accepted page reached by no accepted step ───────────
+    const reachedPages = new Set();
+    for (const it of accepted) {
+        if (it.kind !== 'step')
+            continue;
+        const pg = meta(it).page;
+        if (pg)
+            reachedPages.add(pg);
+    }
+    for (const it of accepted) {
+        if (it.kind !== 'page')
+            continue;
+        if (!reachedPages.has(it.ref_id)) {
+            out.push({
+                code: 'W-UNREACHED-PAGE',
+                message: `${it.ref_id} "${it.title}" 에 도달하는 플로우 스텝이 없습니다.`,
+                refs: [it.ref_id],
+                severity: 'W',
+            });
+        }
+    }
+    // ── W-EMPTY-PAGE: accepted page with zero features links ──────────────────
+    for (const it of accepted) {
+        if (it.kind !== 'page')
+            continue;
+        if ((links(it).features ?? []).length === 0) {
+            out.push({
+                code: 'W-EMPTY-PAGE',
+                message: `${it.ref_id} "${it.title}" 에 연결된 기능(F)이 없습니다.`,
+                refs: [it.ref_id],
+                severity: 'W',
+            });
+        }
+    }
+    // ── W-NO-FLOW: P0 accepted feature in no flow's links.features ────────────
+    const featuresInFlows = new Set();
+    for (const it of accepted) {
+        if (it.kind !== 'flow')
+            continue;
+        for (const f of links(it).features ?? [])
+            featuresInFlows.add(f);
+    }
+    for (const it of accepted) {
+        if (it.kind !== 'feature')
+            continue;
+        if (meta(it).priority !== 'P0')
+            continue;
+        if (!featuresInFlows.has(it.ref_id)) {
+            out.push({
+                code: 'W-NO-FLOW',
+                message: `P0 기능 ${it.ref_id} "${it.title}" 이(가) 어느 플로우에도 등장하지 않습니다.`,
+                refs: [it.ref_id],
+                severity: 'W',
+            });
+        }
+    }
+    return out;
+}
+/** Stable de-dupe key for a violation (code + sorted refs) — used for waive/regression. */
+export function violationKey(v) {
+    return `${v.code}::${[...v.refs].sort().join(',')}`;
+}

package/api/dist/lib/mockup-gen.js

@@ -0,0 +1,136 @@
+// AI 고해상도 시안 생성 — 페이지(IA) 1개 + StyleGuide → 자기완결 HTML 화면.
+// AI_STUB 이면 테마 반영 결정적 HTML(테스트·오프라인). 아니면 provider 로 생성.
+import { config } from "./config.js";
+import { resolveProvider } from "../providers/index.js";
+import { getModelConfig } from "./ai.js";
+import { getStyleGuide, guidePromptText } from "./style-guide.js";
+import * as repo from "../db/repos.js";
+function meta(i) {
+    try {
+        return JSON.parse(i.meta || '{}');
+    }
+    catch {
+        return {};
+    }
+}
+function bodyLines(i) {
+    return i.body.split('\n').map((l) => l.replace(/^[·\-*]\s*/, '').trim()).filter(Boolean);
+}
+/** ```html 펜스·잡텍스트 제거 후 <html…>/<!doctype…>~</html> 만 뽑는다. */
+export function extractHtml(text) {
+    let t = text.trim().replace(/^```[a-zA-Z]*\s*/, '').replace(/\s*```$/, '').trim();
+    let lower = t.toLowerCase();
+    // 서두 텍스트 제거 — doctype/html 중 '가장 이른' 마커부터. (max 아님: doctype 를 버리면 안 됨)
+    const starts = [lower.indexOf('<!doctype'), lower.indexOf('<html')].filter((i) => i >= 0);
+    const start = starts.length ? Math.min(...starts) : -1;
+    if (start > 0) {
+        t = t.slice(start);
+        lower = t.toLowerCase(); // slice 후 인덱스 재계산 (스테일 방지)
+    }
+    const end = lower.lastIndexOf('</html>');
+    if (end >= 0)
+        t = t.slice(0, end + 7);
+    return t;
+}
+function buildMessages(page, features, g) {
+    const type = (meta(page).page_type ?? 'GENERIC');
+    const featureBlock = features.length
+        ? features.map((f) => `- ${f.title}${f.body ? `: ${bodyLines(f).slice(0, 4).join(' / ')}` : ''}`).join('\n')
+        : '- (연결된 기능 없음 — 화면 목적에 맞는 합리적 기본 요소)';
+    const system = `너는 시니어 프로덕트 디자이너다. 아래 화면 1개에 대한 **고해상도 시안**을 만든다.\n` +
+        `출력은 오직 자기완결 HTML 문서 하나 — 인라인 <style> 만 사용, 외부 리소스·이미지 URL·JS 금지. ` +
+        `코드펜스·설명 문장 없이 <!doctype html> 로 시작한다.\n` +
+        `모바일 앱 화면(폭 390px 기준, body 는 화면 배경, 중앙에 390px 프레임). 한국어 실제 콘텐츠로 채운다(로렘 금지).\n` +
+        `디자인 토큰(반드시 준수): ${guidePromptText(g)}\n` +
+        `화면 성격 = ${type}. 상단 앱바 + 성격에 맞는 본문(목록/상세/폼/대시보드/설정 등) + 주요 액션 버튼(accent).`;
+    const user = `화면: "${page.title}" (${type})\n담아야 할 기능/요소:\n${featureBlock}\n\n위 토큰과 성격대로 시안 HTML 을 출력하라.`;
+    return [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+    ];
+}
+export async function generateMockupHtml(projectId, page) {
+    const g = getStyleGuide(projectId);
+    const featureRefs = meta(page).links?.features ?? [];
+    const items = repo.listProjectItems(projectId);
+    const byRef = new Map(items.map((i) => [i.ref_id, i]));
+    const features = featureRefs.map((r) => byRef.get(r)).filter((x) => !!x);
+    if (config.aiStub || config.managedTier)
+        return stubMockupHtml(page, features, g);
+    const cfg = getModelConfig('ia');
+    const provider = resolveProvider(cfg.provider);
+    const messages = buildMessages(page, features, g);
+    // 무거운 화면(기능 많음)은 시안 HTML 이 길다 → 넉넉한 토큰(잘림 방지).
+    const maxTokens = Math.max(cfg.maxTokens, 16000);
+    const run = async () => {
+        let text = '';
+        for await (const delta of provider.streamChat({ model: cfg.model, maxTokens, messages }))
+            text += delta;
+        return extractHtml(text);
+    };
+    let html = await run();
+    // 미완성(닫는 </html> 없음·너무 짧음) = 토큰 소진/스톨로 잘린 것 → 1회 재시도.
+    if (!isCompleteHtml(html))
+        html = await run();
+    if (!html.toLowerCase().includes('<html') && !html.toLowerCase().includes('<!doctype')) {
+        // 모델이 조각만 줬으면 최소 래핑
+        return `<!doctype html><html><head><meta charset="utf-8"></head><body>${html}</body></html>`;
+    }
+    return html;
+}
+/** 시안 HTML 이 온전한가 — 닫는 </html> 가 있고 최소 길이 이상. */
+export function isCompleteHtml(html) {
+    const lc = html.toLowerCase();
+    return lc.includes('</html>') && html.trim().length > 400;
+}
+/** 결정적 테마 시안 — stub/offline. 실제 시안의 느낌을 토큰으로 재현. */
+export function stubMockupHtml(page, features, g) {
+    const type = (meta(page).page_type ?? 'GENERIC');
+    const labels = features.map((f) => f.title);
+    const lines = features.flatMap((f) => bodyLines(f));
+    const esc = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+    const gapPx = g.density === 'compact' ? 10 : g.density === 'spacious' ? 20 : 14;
+    const font = g.font === 'serif' ? 'Georgia, serif' : g.font === 'mono' ? 'ui-monospace, Menlo, monospace' : "-apple-system, system-ui, sans-serif";
+    const body = (() => {
+        switch (type) {
+            case 'LIST':
+                return `<div class="input">🔍 ${esc(page.title)} 검색</div>` +
+                    (labels.length ? labels : [page.title]).slice(0, 4).map((t, i) => `<div class="card row"><div class="av">${i + 1}</div><div class="rt"><b>${esc(t)}</b><span>${esc(lines[i] ?? '항목 설명')}</span></div><span class="chev">›</span></div>`).join('');
+            case 'DETAIL':
+                return `<div class="hero"></div><h2>${esc(labels[0] ?? page.title)}</h2>` +
+                    `<div class="chips">${['개요', '상세', '리뷰'].map((c, i) => `<span class="chip${i === 0 ? ' on' : ''}">${c}</span>`).join('')}</div>` +
+                    lines.slice(0, 3).map((b) => `<p>${esc(b)}</p>`).join('') +
+                    `<button class="cta">다음 단계로</button>`;
+            case 'FORM':
+                return (lines.length ? lines : labels).slice(0, 4).map((f) => `<label class="field"><span>${esc(f)}</span><div class="input"> </div></label>`).join('') +
+                    `<button class="cta">제출</button>`;
+            case 'DASH':
+                return `<div class="stats">${(labels.length ? labels : ['활성 사용자', '전환율', '매출']).slice(0, 3).map((l, i) => `<div class="stat"><b>${(i + 4) * 13}%</b><span>${esc(l)}</span></div>`).join('')}</div>` +
+                    `<div class="card"><div class="chart">${[42, 66, 80, 54, 92, 70].map((h) => `<i style="height:${h}%"></i>`).join('')}</div></div>`;
+            case 'SETTINGS':
+                return (lines.length ? lines : labels).slice(0, 4).map((t, i) => `<div class="card tgl"><span>${esc(t)}</span><span class="sw${i < 2 ? ' on' : ''}"></span></div>`).join('');
+            default:
+                return (lines.length ? lines : labels.length ? labels : [page.title]).map((b) => `<div class="card"><p>${esc(b)}</p></div>`).join('') +
+                    `<button class="cta">열기</button>`;
+        }
+    })();
+    return `<!doctype html><html lang="ko"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><style>
+  :root{--ac:${g.accent};--bg:${g.bg};--sf:${g.surface};--ink:${g.ink};--sub:${g.sub};--ln:${g.line};--r:${g.radius}px;--gap:${gapPx}px}
+  *{box-sizing:border-box;margin:0}body{background:var(--bg);font-family:${font};color:var(--ink);display:flex;justify-content:center;padding:16px}
+  .frame{width:390px;background:var(--bg);display:flex;flex-direction:column;gap:var(--gap)}
+  .bar{display:flex;align-items:center;gap:10px;padding:14px 4px 4px;font-weight:700;font-size:17px}
+  .bar .sp{flex:1}.bar .dot{width:26px;height:26px;border-radius:50%;background:var(--ln)}
+  .card{background:var(--sf);border:1px solid var(--ln);border-radius:var(--r);padding:14px}
+  .row{display:flex;align-items:center;gap:12px}.av{width:38px;height:38px;border-radius:calc(var(--r) - 2px);background:color-mix(in srgb,var(--ac) 16%,var(--sf));color:var(--ac);display:flex;align-items:center;justify-content:center;font-weight:800;flex-shrink:0}
+  .rt{display:flex;flex-direction:column;min-width:0}.rt b{font-size:14px}.rt span{font-size:12px;color:var(--sub)}.chev{margin-left:auto;color:var(--sub);font-size:20px}
+  .input{background:var(--sf);border:1px solid var(--ln);border-radius:var(--r);padding:11px 13px;color:var(--sub);font-size:13px;min-height:20px}
+  .hero{height:150px;background:linear-gradient(135deg,color-mix(in srgb,var(--ac) 22%,var(--sf)),var(--sf));border-radius:var(--r);border:1px solid var(--ln)}
+  h2{font-size:20px;margin:2px 0}.chips{display:flex;gap:8px}.chip{font-size:12px;color:var(--sub);border:1px solid var(--ln);border-radius:99px;padding:4px 12px}.chip.on{background:var(--ac);color:#fff;border-color:var(--ac)}
+  p{font-size:13px;line-height:1.6;color:var(--sub)}
+  .field{display:flex;flex-direction:column;gap:6px}.field span{font-size:12px;color:var(--sub);font-weight:600}.field .input{min-height:42px}
+  .cta{background:var(--ac);color:#fff;border:0;border-radius:var(--r);padding:14px;font-size:15px;font-weight:700;margin-top:4px}
+  .stats{display:flex;gap:var(--gap)}.stat{flex:1;background:var(--sf);border:1px solid var(--ln);border-radius:var(--r);padding:14px}.stat b{font-size:22px;color:var(--ac)}.stat span{display:block;font-size:11px;color:var(--sub);margin-top:3px}
+  .chart{display:flex;align-items:flex-end;gap:8px;height:120px}.chart i{flex:1;background:var(--ac);opacity:.85;border-radius:4px 4px 0 0}
+  .tgl{display:flex;align-items:center}.tgl span:first-child{font-size:14px}.sw{margin-left:auto;width:42px;height:24px;border-radius:99px;background:var(--ln);position:relative}.sw.on{background:var(--ac)}.sw::after{content:'';position:absolute;top:3px;left:3px;width:18px;height:18px;border-radius:50%;background:#fff;transition:.2s}.sw.on::after{left:21px}
+  </style></head><body><div class="frame"><div class="bar">${type === 'DETAIL' || type === 'FORM' || type === 'SETTINGS' ? '<span>‹</span>' : ''}<span>${esc(page.title)}</span><span class="sp"></span><span class="dot"></span></div>${body}</div></body></html>`;
+}

package/api/dist/lib/numbering.js

@@ -0,0 +1,75 @@
+// Server-side ref_id assignment (§1.2). The LLM NEVER produces ref_ids — this
+// module is the single source of truth. Rule: max existing number of that kind
+// (or of that parent's children) + 1. Deleted numbers are NOT reused because we
+// take max, never count. Pure functions — fully unit-tested.
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+/** Highest F-/PG-/FLOW- top-level number among rows of `kind`. 0 if none. */
+function maxTopNumber(rows, kind, prefix) {
+    let max = 0;
+    for (const r of rows) {
+        if (r.kind !== kind)
+            continue;
+        const m = r.ref_id.match(prefix);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max;
+}
+/** Highest child suffix under a given parent ref (feature/step). 0 if none. */
+function maxChildNumber(rows, parentRef, sep) {
+    // Escape regex metacharacters in the parent ref (e.g. the '.' in FLOW-01).
+    const esc = parentRef.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${esc}${sep === '.' ? '\\.' : '-'}(\\d+)$`);
+    let max = 0;
+    for (const r of rows) {
+        const m = r.ref_id.match(re);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max;
+}
+export function nextGroupRef(rows) {
+    return `F-${pad2(maxTopNumber(rows, 'feature-group', /^F-(\d+)$/) + 1)}`;
+}
+export function nextFeatureRef(rows, groupRef) {
+    return `${groupRef}-${maxChildNumber(rows, groupRef, '-') + 1}`;
+}
+export function nextPageRef(rows) {
+    return `PG-${pad2(maxTopNumber(rows, 'page', /^PG-(\d+)$/) + 1)}`;
+}
+export function nextFlowRef(rows) {
+    return `FLOW-${pad2(maxTopNumber(rows, 'flow', /^FLOW-(\d+)$/) + 1)}`;
+}
+export function nextStepRef(rows, flowRef) {
+    return `${flowRef}.${maxChildNumber(rows, flowRef, '.') + 1}`;
+}
+/**
+ * Assign the next ref_id for a new item of `kind`. `parentRef` is required for
+ * feature (its group's ref) and step (its flow's ref).
+ */
+export function nextRefId(rows, kind, parentRef) {
+    switch (kind) {
+        case 'feature-group':
+            return nextGroupRef(rows);
+        case 'feature':
+            if (!parentRef)
+                throw new Error('feature requires a parent group ref');
+            return nextFeatureRef(rows, parentRef);
+        case 'page':
+            return nextPageRef(rows);
+        case 'flow':
+            return nextFlowRef(rows);
+        case 'step':
+            if (!parentRef)
+                throw new Error('step requires a parent flow ref');
+            return nextStepRef(rows, parentRef);
+        default:
+            throw new Error(`unknown plan item kind: ${kind}`);
+    }
+}
+/** Narrow a PlanItem[] to the RefRow shape the numbering functions consume. */
+export function toRefRows(items) {
+    return items.map((i) => ({ kind: i.kind, ref_id: i.ref_id, parent_id: i.parent_id }));
+}

package/api/dist/lib/provider-errors.js

@@ -0,0 +1,31 @@
+/**
+ * provider(직접·게이트웨이) 에러를 사용자 언어 + 해결 힌트로 표준화한다.
+ * 원문은 detail 로 보존한다. UI 배너·카드가 그대로 읽어 도움말을 준다.
+ */
+export function humanizeProviderError(status, rawBody) {
+    const body = (rawBody || '').slice(0, 400);
+    const lc = body.toLowerCase();
+    // 모델 접근 권한 없음 (게이트웨이 모델 그룹 제한 등) — 401 로도 오므로 auth 분기보다 먼저.
+    if (/not allowed to access model|model.*not found|does not exist|no endpoints found/i.test(lc)) {
+        return ('이 키로 접근할 수 없는 모델입니다. 설정의 모델 칸을 게이트웨이가 제공하는 모델로 바꾸세요' +
+            '(드롭다운). · ' + body);
+    }
+    // 인증 헤더 없음 / 잘못된 키 — base URL 이 표준 provider 를 가리키는데 게이트웨이 키를 넣은 전형
+    if (status === 401 || /missing authentication|unauthorized|invalid api key|no auth/i.test(lc)) {
+        return ('인증 실패(401). 키가 이 엔드포인트와 맞는지 확인하세요. ' +
+            '게이트웨이(LiteLLM 등)를 쓴다면 설정의 "OpenAI 호환 게이트웨이" base URL 을 넣고, ' +
+            '키는 그 게이트웨이 키여야 합니다. · ' + body);
+    }
+    // 모델별 게이트(예: 18+ 확인)
+    if (status === 403 || /age.?confirm|attestation|requires you to complete|forbidden/i.test(lc)) {
+        return ('이 모델은 계정에서 추가 확인(예: 연령 확인)이 필요하거나 접근이 막혀 있습니다. ' +
+            '다른 모델을 쓰거나 provider 설정에서 확인을 마치세요. · ' + body);
+    }
+    if (status === 429 || /rate limit|too many requests|quota/i.test(lc)) {
+        return '요청이 많거나 한도를 초과했습니다(429). 잠시 후 다시 시도하세요. · ' + body;
+    }
+    if (status >= 500) {
+        return `provider 서버 오류(${status}). 잠시 후 다시 시도하세요. · ` + body;
+    }
+    return `${status}: ${body}`;
+}

package/api/dist/lib/render.js

@@ -0,0 +1,154 @@
+import { marked } from 'marked';
+import * as repo from "../db/repos.js";
+marked.setOptions({ gfm: true, breaks: false });
+export function documentToMarkdown(documentId) {
+    const doc = repo.getDocument(documentId);
+    if (!doc)
+        throw new Error('document not found');
+    // Only ACCEPTED sections are the document (SYSTEM.md §0.2).
+    const sections = repo.listAcceptedSections(documentId);
+    const parts = [`# ${doc.title}`, ''];
+    for (const s of sections) {
+        parts.push(`## ${s.heading}`, '', s.body.trim(), '');
+    }
+    // 구조 문서(기능명세·IA·유저플로우)는 내용이 sections 가 아니라 plan_items 에 있다.
+    // sections 만 렌더하면 제목만 나오므로, 수락된 항목을 마크다운으로 렌더한다.
+    parts.push(structureItemsToMarkdown(documentId));
+    const excluded = repo.countExcludedSections(documentId);
+    if (excluded > 0) {
+        parts.push('---', '', `> 검토 대기 ${excluded}개 제외`, '');
+    }
+    return parts.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/** 수락된 plan_items 를 트리(그룹/부모 → 자식)로 마크다운 렌더. 항목이 없으면 빈 문자열. */
+export function structureItemsToMarkdown(documentId) {
+    const items = repo.listItems(documentId).filter((i) => i.status === 'accepted');
+    if (items.length === 0)
+        return '';
+    const byParent = new Map();
+    for (const it of items) {
+        const key = it.parent_id ?? null;
+        (byParent.get(key) ?? byParent.set(key, []).get(key)).push(it);
+    }
+    const roots = (byParent.get(null) ?? []).sort((a, b) => a.position - b.position);
+    const lines = [];
+    const linkLine = (it) => {
+        const m = repo.parsePlanItemMeta(it);
+        const refs = [
+            ...(m.links?.reqs ?? []),
+            ...(m.links?.features ?? []),
+            ...(m.links?.pages ?? []),
+            ...(m.links?.flows ?? []),
+        ];
+        return refs.length ? `연결: ${refs.join(' · ')}` : null;
+    };
+    for (const root of roots) {
+        const rm = repo.parsePlanItemMeta(root);
+        const pri = rm.priority ? ` — ${rm.priority}` : '';
+        lines.push('', `## ${root.ref_id} ${root.title}${pri}`, '');
+        if (root.body.trim())
+            lines.push(root.body.trim(), '');
+        const rl = linkLine(root);
+        if (rl)
+            lines.push(rl, '');
+        const kids = (byParent.get(root.id) ?? []).sort((a, b) => a.position - b.position);
+        kids.forEach((kid, idx) => {
+            const km = repo.parsePlanItemMeta(kid);
+            const kpri = km.priority ? ` — ${km.priority}` : '';
+            // 스텝(플로우 자식)은 번호 목록, 그 외(기능 등)는 소제목으로
+            if (kid.kind === 'step') {
+                const page = km.page ? `[${km.page}] ` : '';
+                const branch = km.branch?.label ? ` _(분기: ${km.branch.label})_` : '';
+                lines.push(`${idx + 1}. ${page}${kid.title}${branch}`);
+                if (km.note)
+                    lines.push(`   ${km.note}`);
+            }
+            else {
+                lines.push(`### ${kid.ref_id} ${kid.title}${kpri}`, '');
+                if (kid.body.trim())
+                    lines.push(kid.body.trim(), '');
+                const kl = linkLine(kid);
+                if (kl)
+                    lines.push(kl, '');
+            }
+        });
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Minimal sanitization: strip <script>/<iframe> and inline event handlers. */
+function sanitize(html) {
+    return html
+        .replace(/<\s*(script|iframe)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+        .replace(/\son\w+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+        .replace(/javascript:/gi, '');
+}
+export function documentToHtml(documentId, opts) {
+    const doc = repo.getDocument(documentId);
+    if (!doc)
+        throw new Error('document not found');
+    // Only ACCEPTED sections are the document (SYSTEM.md §0.2).
+    const sections = repo.listAcceptedSections(documentId);
+    let body = sections
+        .map((s) => `<section><h2>${escapeHtml(s.heading)}</h2>${sanitize(marked.parse(s.body))}</section>`)
+        .join('\n');
+    // 구조 문서 항목(plan_items)을 렌더 — sections 만 있으면 제목만 나오는 문제 방지
+    const itemsMd = structureItemsToMarkdown(documentId);
+    if (itemsMd.trim()) {
+        body += `\n<section>${sanitize(marked.parse(itemsMd))}</section>`;
+    }
+    const excluded = repo.countExcludedSections(documentId);
+    const footnote = excluded > 0
+        ? `<footer class="excluded">검토 대기 ${excluded}개 제외</footer>`
+        : '';
+    const badge = opts?.readOnly ? '<div class="ro">읽기 전용 공유</div>' : '';
+    return `<!doctype html>
+<html lang="ko">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(doc.title)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { max-width: 820px; margin: 0 auto; padding: 3rem 1.25rem 6rem;
+         font: 16px/1.7 -apple-system, "Pretendard", "Segoe UI", system-ui, sans-serif;
+         color: #17181c; background: #ffffff; }
+  @media (prefers-color-scheme: dark) { body { color: #e7e7ea; background: #131315; } }
+  h1 { font-size: 2rem; letter-spacing: -0.02em; margin-bottom: 0.25rem; }
+  h2 { font-size: 1.25rem; margin-top: 2.4rem; padding-bottom: 0.3rem;
+       border-bottom: 1px solid rgba(128,128,128,0.25); }
+  section p { margin: 0.6rem 0; }
+  code { background: rgba(128,128,128,0.15); padding: 0.1em 0.35em; border-radius: 4px; }
+  blockquote { border-left: 3px solid #E03A2B; margin: 1rem 0; padding: 0.2rem 1rem; opacity: 0.85; }
+  .ro { position: fixed; top: 0; left: 0; right: 0; text-align: center; font-size: 0.75rem;
+        padding: 0.35rem; background: #E03A2B; color: #fff; letter-spacing: 0.05em; }
+  .meta { color: #8a8a90; font-size: 0.85rem; margin-bottom: 2rem; }
+  .excluded { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid rgba(128,128,128,0.25);
+              color: #8a8a90; font-size: 0.8rem; }
+  /* PDF(인쇄) 최적화 — 흰 배경 고정, 섹션 페이지 넘김 존중, 공유 배지 숨김 */
+  @media print {
+    body { color: #17181c; background: #fff; max-width: none; padding: 0; font-size: 12pt; }
+    .ro { display: none; }
+    section { break-inside: avoid; }
+    h2 { break-after: avoid; }
+    @page { margin: 18mm 16mm; }
+  }
+</style>
+</head>
+<body>
+${badge}
+<h1>${escapeHtml(doc.title)}</h1>
+<div class="meta">${escapeHtml(doc.type)} · v${doc.version}</div>
+${body}
+${footnote}
+${opts?.print ? '<script>window.addEventListener("load", () => setTimeout(() => window.print(), 250));</script>' : ''}
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/api/dist/lib/style-guide.js

@@ -0,0 +1,47 @@
+// 프로젝트 StyleGuide(테마) — C/B/A 세 레이어의 공용 스타일 소스.
+// 저장은 프로젝트별 settings 키(style_guide:<pid>), 스키마 변경 없음.
+import * as repo from "../db/repos.js";
+// 뚜렷이 구분되는 프리셋 — C 의 스타일 선택지.
+export const PRESETS = {
+    clean: { preset: 'clean', accent: '#4f46e5', bg: '#f6f7f9', surface: '#ffffff', ink: '#1b1c1e', sub: '#6f7076', line: '#e6e7ea', radius: 10, density: 'cozy', font: 'sans', mode: 'light' },
+    warm: { preset: 'warm', accent: '#c2603f', bg: '#faf6f0', surface: '#fffdfa', ink: '#2a231c', sub: '#8a7d6d', line: '#ece3d6', radius: 8, density: 'spacious', font: 'serif', mode: 'light' },
+    mono: { preset: 'mono', accent: '#1b1c1e', bg: '#fafafa', surface: '#ffffff', ink: '#111214', sub: '#70727a', line: '#e4e4e6', radius: 4, density: 'compact', font: 'mono', mode: 'light' },
+    vivid: { preset: 'vivid', accent: '#7c3aed', bg: '#f6f4ff', surface: '#ffffff', ink: '#211a34', sub: '#7b7391', line: '#e8e2f7', radius: 16, density: 'cozy', font: 'rounded', mode: 'light' },
+    dark: { preset: 'dark', accent: '#22d3ee', bg: '#0f1115', surface: '#171a21', ink: '#e7e9ee', sub: '#9aa0aa', line: '#272b34', radius: 10, density: 'cozy', font: 'sans', mode: 'dark' },
+};
+export const DEFAULT_GUIDE = PRESETS.clean;
+const FONT_STACK = {
+    sans: "'Pretendard', -apple-system, system-ui, sans-serif",
+    serif: "'Iowan Old Style', 'Apple SD Gothic Neo', Georgia, serif",
+    rounded: "'SF Pro Rounded', 'Pretendard', system-ui, sans-serif",
+    mono: "ui-monospace, 'SF Mono', Menlo, monospace",
+};
+const DENSITY_GAP = { compact: 8, cozy: 12, spacious: 18 };
+const key = (pid) => `style_guide:${pid}`;
+export function getStyleGuide(projectId) {
+    const saved = repo.getSetting(key(projectId));
+    if (!saved)
+        return DEFAULT_GUIDE;
+    const base = PRESETS[saved.preset ?? 'clean'] ?? DEFAULT_GUIDE;
+    return { ...base, ...saved };
+}
+export function saveStyleGuide(projectId, patch) {
+    const current = getStyleGuide(projectId);
+    // 프리셋 전환이면 그 프리셋을 베이스로(값 리셋), 아니면 현재 값 유지 위에 부분 덮어쓰기.
+    const base = patch.preset && patch.preset !== current.preset ? PRESETS[patch.preset] ?? current : current;
+    const next = { ...base, ...patch };
+    repo.setSetting(key(projectId), next);
+    return next;
+}
+/** 프론트 렌더용 파생값(폰트 스택·간격) — CSS 변수로 내려보낸다. */
+export function guideRender(g) {
+    return { fontStack: FONT_STACK[g.font], gap: DENSITY_GAP[g.density] };
+}
+/** AI 시안 프롬프트에 넣을 압축 스타일 설명 — 생성물이 테마와 일관되게. */
+export function guidePromptText(g) {
+    return [
+        `배경 ${g.bg}, 표면(카드) ${g.surface}, 본문 텍스트 ${g.ink}, 보조 텍스트 ${g.sub}, 경계선 ${g.line}, 강조(accent) ${g.accent}.`,
+        `모서리 반경 ${g.radius}px, 밀도 ${g.density}(간격 ${DENSITY_GAP[g.density]}px 기준), 서체 계열 ${g.font}, 모드 ${g.mode}.`,
+        `강조색은 주요 버튼·활성 상태에만 절제해서 쓰고, 나머지는 표면·경계선·텍스트로 차분하게.`,
+    ].join(' ');
+}