@ncds/ui-admin-mcp 1.0.0-alpha.2 → 1.0.0-alpha.21

package/bin/tools/listCompositionOverrides.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCompositionOverrides = exports.buildListCompositionOverridesResponse = exports.buildCompositionOverridesSummary = void 0;
+const response_js_1 = require("../utils/response.js");
+/**
+ * coverageScore 가중치 — 각 보강 영역의 점수 기여도.
+ * 시나리오(canonicalExamples)가 가장 큰 가중치를 가지는 이유: AI hallucination 차단력이 가장 큼.
+ */
+const COVERAGE_WEIGHTS = {
+    CANONICAL_EXAMPLES_FULL: 0.5,
+    CANONICAL_EXAMPLES_PARTIAL: 0.25,
+    ALLOWED_CHILDREN_FULL: 0.2,
+    ALLOWED_CHILDREN_PARTIAL: 0.1,
+    BEM_CLASSES_EXTRA: 0.1,
+    DESCRIPTION_EXTRA: 0.1,
+    ALIASES_EXTRA: 0.1,
+};
+/**
+ * 전체 가중치 합 (5 영역 모두 적용 가능한 경우의 최대).
+ * applicableMax = TOTAL_WEIGHT - Σ(notApplicable 영역 가중치) 로 동적 계산.
+ */
+const TOTAL_WEIGHT = 1.0;
+/**
+ * 영역별 가중치 맵 — applicableMax 동적 계산 시 사용.
+ * canonicalExamples 는 항상 적용 가능하므로 포함하지 않음 (분모에서 제외되지 않음).
+ */
+const AREA_WEIGHT_MAP = {
+    allowedChildren: COVERAGE_WEIGHTS.ALLOWED_CHILDREN_FULL,
+    bemClassesExtra: COVERAGE_WEIGHTS.BEM_CLASSES_EXTRA,
+    descriptionExtra: COVERAGE_WEIGHTS.DESCRIPTION_EXTRA,
+    aliasesExtra: COVERAGE_WEIGHTS.ALIASES_EXTRA,
+};
+/** coverageNote tier 임계값. */
+const TIER_THRESHOLD_HIGH = 0.7;
+const TIER_THRESHOLD_MEDIUM = 0.4;
+/** 점수 cap (이론적 최대값). */
+const SCORE_CAP = 1;
+/** 소수점 2자리 반올림용 — `Math.round(x * 100) / 100`. */
+const TWO_DECIMAL_BASE = 100;
+/** AI 가 UI 를 얼마나 정확히 그릴 수 있는지 추정 — 각 composition overrides 보강이 다른 정확도 영역을 커버한다 */
+const METRIC_DESCRIPTIONS = {
+    canonicalExamples: 'AI 가 시나리오별로 분기 가능한 정답 트리 수 (form / data-grid / with-tooltip 등). 가장 강한 정확도 신호 — 0 이면 AI 가 prop 조합을 추측해야 한다.',
+    hasCanonicalExample: 'legacy 단일 시나리오 존재 여부 — 진입용 표준 트리 1건. canonicalExamples 가 비어있는 컴포넌트의 fallback.',
+    bemClassesExtra: 'extract 가 못 잡은 BEM 클래스 화이트리스트 수. validate_html 이 합법/위법을 정확히 판정 — 발명 클래스 사용 차단력.',
+    allowedChildrenKeys: 'compound 부모-자식 제약 노드 수. 잘못된 자식 끼우기 / 컨텍스트 위반 (Table.Pagination in DataGrid 등) 차단력.',
+    allowedParentsKeys: '역방향 제약 노드 수 — 자식이 어느 부모 안에만 허용되는지 명시.',
+    descriptionExtra: 'list_components 응답에 자연어 용도/모드 명시 여부. 같은 컴포넌트가 다른 모드(horizontal/vertical) 로 쓰일 때 AI 가 모드를 인지하는 정확도.',
+    aliasesExtra: 'search_component 한국어/유사 키워드 매칭 별칭 수. AI 가 "폼 레이아웃", "세로 테이블" 같은 비공식 용어로 검색해도 정답 컴포넌트에 도달.',
+    coverageScore: '자기 카테고리 천장 대비 정규화 점수 (0.0 ~ 1.0). 1.0 이면 컴포넌트 구조상 가능한 모든 보강 영역을 완료. applicableMax = 1.0 − Σ(notApplicable 영역 가중치)로 동적 계산되어 모든 컴포넌트가 동일 척도. 절대 가중합이 아니라 정규화 비율이므로 컴포넌트 종류 무관하게 직접 비교 가능.',
+    notApplicable: '컴포넌트 구조상 적용 불가한 보강 영역 목록. non-compound 는 자동으로 ["allowedChildren"] 포함 (자식 없어 부모-자식 제약 의미 없음). composition.json notApplicableAreas 선언(예: extract 가 BEM 을 완전히 잡는 컴포넌트 → ["bemClassesExtra"])과 union 되어 최종 notApplicable 결정. 점수 분모에서 자동 제외되어 천장이 1.0 으로 통일된다.',
+};
+const COVERAGE_FORMULA = 'rawScore (가중 합) = canonicalExamples>=2: +0.50 (>=1 또는 hasCanonicalExample: +0.25) + allowedChildrenKeys>=2: +0.20 (>=1: +0.10, compound 만 적용) + bemClassesExtra>=1: +0.10 + descriptionExtra: +0.10 + aliasesExtra>=1: +0.10. applicableMax = 1.0 − Σ(notApplicable 영역 가중치) — non-compound 는 자동으로 allowedChildren(0.20) 제외, composition.json notApplicableAreas 선언 시 해당 가중치 추가 차감. coverageScore = rawScore / applicableMax (Math.min(1.0, ...)). 임계값: high>=0.70, medium>=0.40, 그 외 low. coverageScore 1.0 = 자기 카테고리에서 더 채울 영역 없음.';
+/** 적용 가능 영역의 절대 가중치 합 (정규화 전 raw 점수). */
+const computeRawScore = (s) => {
+    let score = 0;
+    if (s.canonicalExamples.length >= 2)
+        score += COVERAGE_WEIGHTS.CANONICAL_EXAMPLES_FULL;
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        score += COVERAGE_WEIGHTS.CANONICAL_EXAMPLES_PARTIAL;
+    if (s.allowedChildrenKeys.length >= 2)
+        score += COVERAGE_WEIGHTS.ALLOWED_CHILDREN_FULL;
+    else if (s.allowedChildrenKeys.length >= 1)
+        score += COVERAGE_WEIGHTS.ALLOWED_CHILDREN_PARTIAL;
+    if (s.bemClassesExtra >= 1)
+        score += COVERAGE_WEIGHTS.BEM_CLASSES_EXTRA;
+    if (s.descriptionExtra)
+        score += COVERAGE_WEIGHTS.DESCRIPTION_EXTRA;
+    if (s.aliasesExtra >= 1)
+        score += COVERAGE_WEIGHTS.ALIASES_EXTRA;
+    return score;
+};
+/**
+ * 컴포넌트의 notApplicable 영역 목록.
+ * 구조적 제외(non-compound → allowedChildren) + entry 의 notApplicableAreas 선언을 union.
+ */
+const getNotApplicable = (isCompound, entryNotApplicableAreas) => {
+    const structural = isCompound ? [] : ['allowedChildren'];
+    return [...new Set([...structural, ...entryNotApplicableAreas])];
+};
+/**
+ * applicableMax = TOTAL_WEIGHT - Σ(notApplicable 영역 가중치).
+ * compound 기본: 1.0. non-compound 기본: 0.8 (allowedChildren 0.2 제외).
+ * notApplicableAreas 추가 선언 시 해당 가중치만큼 추가 차감 → coverageScore 1.0 = 실제 달성 가능 최대.
+ */
+const getApplicableMax = (notApplicable) => {
+    const excluded = notApplicable.reduce((sum, area) => sum + (AREA_WEIGHT_MAP[area] ?? 0), 0);
+    return Math.round((TOTAL_WEIGHT - excluded) * TWO_DECIMAL_BASE) / TWO_DECIMAL_BASE;
+};
+/** rawScore → coverageScore (자기 카테고리 천장 기준 0~1.0 정규화). */
+const normalizeScore = (rawScore, applicableMax) => Math.min(SCORE_CAP, Math.round((rawScore / applicableMax) * TWO_DECIMAL_BASE) / TWO_DECIMAL_BASE);
+/** coverageScore 를 high/medium/low tier 로 분류. */
+const getTier = (score) => {
+    if (score >= TIER_THRESHOLD_HIGH)
+        return 'high';
+    if (score >= TIER_THRESHOLD_MEDIUM)
+        return 'medium';
+    return 'low';
+};
+const noteFor = (s, score) => {
+    const strengths = [];
+    if (s.canonicalExamples.length >= 2)
+        strengths.push(`시나리오 ${s.canonicalExamples.length}`);
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        strengths.push('시나리오 1');
+    if (s.allowedChildrenKeys.length >= 1)
+        strengths.push(`compound 제약 ${s.allowedChildrenKeys.length}`);
+    if (s.bemClassesExtra >= 1)
+        strengths.push(`BEM 화이트리스트 ${s.bemClassesExtra}`);
+    if (s.descriptionExtra)
+        strengths.push('모드 인지 보강');
+    if (s.aliasesExtra >= 1)
+        strengths.push(`검색 별칭 ${s.aliasesExtra}`);
+    const tier = getTier(score);
+    return strengths.length > 0
+        ? `${tier} · ${strengths.join(' + ')}`
+        : `${tier} · 보강 거의 없음 — 직접 작성 hallucination 위험`;
+};
+/** 단일 entry 를 row 로 변환 — compound 여부에 따라 applicableMax 가 결정되고 coverageScore 가 정규화된다. */
+const toSummary = (component, entry, componentMap) => {
+    const base = {
+        component,
+        canonicalExamples: Object.keys(entry.canonicalExamples ?? {}).filter((k) => !k.startsWith('_')),
+        hasCanonicalExample: !!entry.canonicalExample,
+        bemClassesExtra: (entry.bemClassesExtra ?? []).length,
+        allowedChildrenKeys: Object.keys(entry.allowedChildren ?? {}),
+        allowedParentsKeys: Object.keys(entry.allowedParents ?? {}),
+        descriptionExtra: !!entry.descriptionExtra,
+        aliasesExtra: (entry.aliasesExtra ?? []).length,
+    };
+    const subComponentCount = Object.keys(componentMap.get(component)?.subComponents ?? {}).length;
+    const isCompound = subComponentCount > 0;
+    const notApplicable = getNotApplicable(isCompound, entry.notApplicableAreas ?? []);
+    const applicableMax = getApplicableMax(notApplicable);
+    const rawScore = computeRawScore(base);
+    const coverageScore = normalizeScore(rawScore, applicableMax);
+    return { ...base, coverageScore, notApplicable, coverageNote: noteFor(base, coverageScore) };
+};
+/** composition overrides map → 요약 결과 (순수 함수). coverageScore 내림차순 + 동률은 이름 알파벳. */
+const buildCompositionOverridesSummary = (compositionOverrides, componentMap) => {
+    const overrides = Object.entries(compositionOverrides)
+        .map(([component, entry]) => toSummary(component, entry, componentMap))
+        .sort((a, b) => b.coverageScore - a.coverageScore || a.component.localeCompare(b.component));
+    return {
+        total: overrides.length,
+        metrics: METRIC_DESCRIPTIONS,
+        coverageScoreFormula: COVERAGE_FORMULA,
+        overrides,
+    };
+};
+exports.buildCompositionOverridesSummary = buildCompositionOverridesSummary;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+const buildListCompositionOverridesResponse = (compositionOverrides, componentMap) => (0, response_js_1.successResponse)((0, exports.buildCompositionOverridesSummary)(compositionOverrides, componentMap));
+exports.buildListCompositionOverridesResponse = buildListCompositionOverridesResponse;
+/** list_composition_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+const listCompositionOverrides = (prebuilt) => prebuilt;
+exports.listCompositionOverrides = listCompositionOverrides;

package/bin/tools/listSidecarOverrides.d.ts

@@ -0,0 +1,54 @@
+/**
+ * list_sidecar_overrides tool — composition.json sidecar 적용 현황 요약
+ *
+ * 신규 프로젝트에서 NCDS MCP 와 연결한 뒤, 어느 컴포넌트에 어떤 sidecar 보강이
+ * 들어가 있는지 표 형태(컴포넌트별 row)로 한 번에 확인하는 용도. 응답이 크지 않도록
+ * 시나리오 키 목록 + 카운트 위주로 구성하고, 상세는 get_component_props 로 유도.
+ *
+ * 순수 함수 — server.ts 부팅 시 1회 buildListSidecarOverridesResponse() 로 사전 직렬화.
+ */
+import type { ComponentData } from '../types.js';
+import type { CompositionEntry } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface SidecarOverrideSummary {
+    /** 컴포넌트 이름 (kebab-case) */
+    component: string;
+    /** canonicalExamples 시나리오 key 목록 — 비어있으면 [] */
+    canonicalExamples: string[];
+    /** legacy 단일 시나리오 canonicalExample 존재 여부 */
+    hasCanonicalExample: boolean;
+    /** bemClassesExtra 항목 수 */
+    bemClassesExtra: number;
+    /** allowedChildren 정의된 부모 키 목록 (예: ["Table", "Table.Header", ...]) */
+    allowedChildrenKeys: string[];
+    /** allowedParents 정의된 자식 키 목록 */
+    allowedParentsKeys: string[];
+    /** descriptionExtra 존재 여부 */
+    descriptionExtra: boolean;
+    /** aliasesExtra 항목 수 */
+    aliasesExtra: number;
+    /** AI 의 UI 작성 정확도 추정 점수 (0.0 ~ 1.0). 시나리오 + compound 제약 + validate 정확도 + 자연어 보강의 가중 합. */
+    coverageScore: number;
+    /** 컴포넌트 구조상 의미 있게 달성 가능한 최대 점수. compound 컴포넌트(subComponents 보유): 1.0, 그 외: 0.8. */
+    maxAchievable: number;
+    /** coverageScore / maxAchievable — 컴포넌트별 천장 대비 충족율 (0.0 ~ 1.0). 절대 점수가 낮아도 비율이 1.0 이면 더 보강할 게 없다. */
+    coverageRatio: number;
+    /** coverageScore 한 줄 해석 — high/medium/low 와 강점 영역 요약 */
+    coverageNote: string;
+}
+export interface ListSidecarOverridesResult {
+    /** sidecar 적용 컴포넌트 수 */
+    total: number;
+    /** 각 척도가 무엇을 의미하고 AI 의 UI 작성 정확도에 어떻게 영향을 주는지 (AI 가 본 응답을 바로 해석하도록 동봉) */
+    metrics: Record<string, string>;
+    /** coverageScore 산식 (가중치 명시) */
+    coverageScoreFormula: string;
+    /** 컴포넌트별 요약 row 배열 — coverageScore 내림차순, 동률은 컴포넌트 이름 알파벳 */
+    overrides: SidecarOverrideSummary[];
+}
+/** sidecar map → 요약 결과 (순수 함수). coverageRatio 내림차순 + 동률은 coverageScore + 이름 알파벳 */
+export declare const buildSidecarOverridesSummary: (sidecar: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => ListSidecarOverridesResult;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+export declare const buildListSidecarOverridesResponse: (sidecar: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => McpToolResponse;
+/** list_sidecar_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+export declare const listSidecarOverrides: (prebuilt: McpToolResponse) => McpToolResponse;

package/bin/tools/listSidecarOverrides.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSidecarOverrides = exports.buildListSidecarOverridesResponse = exports.buildSidecarOverridesSummary = void 0;
+const response_js_1 = require("../utils/response.js");
+/** AI 가 UI 를 얼마나 정확히 그릴 수 있는지 추정 — 각 sidecar 보강이 다른 정확도 영역을 커버한다 */
+const METRIC_DESCRIPTIONS = {
+    canonicalExamples: 'AI 가 시나리오별로 분기 가능한 정답 트리 수 (form / data-grid / with-tooltip 등). 가장 강한 정확도 신호 — 0 이면 AI 가 prop 조합을 추측해야 한다.',
+    hasCanonicalExample: 'legacy 단일 시나리오 존재 여부 — 진입용 표준 트리 1건. canonicalExamples 가 비어있는 컴포넌트의 fallback.',
+    bemClassesExtra: 'extract 가 못 잡은 BEM 클래스 화이트리스트 수. validate_html 이 합법/위법을 정확히 판정 — 발명 클래스 사용 차단력.',
+    allowedChildrenKeys: 'compound 부모-자식 제약 노드 수. 잘못된 자식 끼우기 / 컨텍스트 위반 (Table.Pagination in DataGrid 등) 차단력.',
+    allowedParentsKeys: '역방향 제약 노드 수 — 자식이 어느 부모 안에만 허용되는지 명시.',
+    descriptionExtra: 'list_components 응답에 자연어 용도/모드 명시 여부. 같은 컴포넌트가 다른 모드(horizontal/vertical) 로 쓰일 때 AI 가 모드를 인지하는 정확도.',
+    aliasesExtra: 'search_component 한국어/유사 키워드 매칭 별칭 수. AI 가 "폼 레이아웃", "세로 테이블" 같은 비공식 용어로 검색해도 정답 컴포넌트에 도달.',
+    maxAchievable: '구조상 의미 있게 도달 가능한 최대 점수. compound 컴포넌트(subComponents 보유): 1.0, 그 외(prop 배열로 항목 받는 컴포넌트 — menus/groups/optionItems 등): 0.8. allowedChildren 가중치(+0.20) 가 compound 가 아닌 컴포넌트에는 적용 불가하기 때문.',
+    coverageRatio: 'coverageScore / maxAchievable. 절대 점수보다 더 정확한 "보강 충족율" — 1.0 이면 해당 컴포넌트는 더 채울 영역이 없다. 0.8 미만이면 의미 있는 보강 여지 있음.',
+};
+const COVERAGE_FORMULA = 'canonicalExamples>=2: +0.50 (>=1 또는 hasCanonicalExample: +0.25) · allowedChildrenKeys>=2: +0.20 (>=1: +0.10) · bemClassesExtra>=1: +0.10 · descriptionExtra: +0.10 · aliasesExtra>=1: +0.10 · max 1.0. 임계값: high>=0.70, medium>=0.40, 그 외 low. 시나리오 가중치가 가장 큼 — AI hallucination 의 가장 강한 차단 신호이기 때문.';
+const computeCoverageScore = (s) => {
+    let score = 0;
+    if (s.canonicalExamples.length >= 2)
+        score += 0.5;
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        score += 0.25;
+    if (s.allowedChildrenKeys.length >= 2)
+        score += 0.2;
+    else if (s.allowedChildrenKeys.length >= 1)
+        score += 0.1;
+    if (s.bemClassesExtra >= 1)
+        score += 0.1;
+    if (s.descriptionExtra)
+        score += 0.1;
+    if (s.aliasesExtra >= 1)
+        score += 0.1;
+    return Math.min(1, Math.round(score * 100) / 100);
+};
+/** 컴포넌트 구조상 의미 있게 도달 가능한 최대 점수.
+ *  compound (subComponents 보유): canonicalExamples 0.5 + allowedChildren 0.2 + bem 0.1 + desc 0.1 + alias 0.1 = 1.0.
+ *  non-compound: allowedChildren 항목이 의미 없음 → 0.8 cap. */
+const computeMaxAchievable = (isCompound) => (isCompound ? 1.0 : 0.8);
+const noteFor = (s, score) => {
+    const strengths = [];
+    if (s.canonicalExamples.length >= 2)
+        strengths.push(`시나리오 ${s.canonicalExamples.length}`);
+    else if (s.canonicalExamples.length >= 1 || s.hasCanonicalExample)
+        strengths.push('시나리오 1');
+    if (s.allowedChildrenKeys.length >= 1)
+        strengths.push(`compound 제약 ${s.allowedChildrenKeys.length}`);
+    if (s.bemClassesExtra >= 1)
+        strengths.push(`BEM 화이트리스트 ${s.bemClassesExtra}`);
+    if (s.descriptionExtra)
+        strengths.push('모드 인지 보강');
+    if (s.aliasesExtra >= 1)
+        strengths.push(`검색 별칭 ${s.aliasesExtra}`);
+    const tier = score >= 0.7 ? 'high' : score >= 0.4 ? 'medium' : 'low';
+    return strengths.length > 0 ? `${tier} · ${strengths.join(' + ')}` : `${tier} · 보강 거의 없음 — 직접 작성 hallucination 위험`;
+};
+/** 단일 entry 를 row 로 변환 — componentMap 으로 compound 여부 결정해 maxAchievable 계산 */
+const toSummary = (component, entry, componentMap) => {
+    const base = {
+        component,
+        canonicalExamples: Object.keys(entry.canonicalExamples ?? {}).filter((k) => !k.startsWith('_')),
+        hasCanonicalExample: !!entry.canonicalExample,
+        bemClassesExtra: (entry.bemClassesExtra ?? []).length,
+        allowedChildrenKeys: Object.keys(entry.allowedChildren ?? {}),
+        allowedParentsKeys: Object.keys(entry.allowedParents ?? {}),
+        descriptionExtra: !!entry.descriptionExtra,
+        aliasesExtra: (entry.aliasesExtra ?? []).length,
+    };
+    const coverageScore = computeCoverageScore(base);
+    const subComponentCount = Object.keys(componentMap.get(component)?.subComponents ?? {}).length;
+    const isCompound = subComponentCount > 0;
+    const maxAchievable = computeMaxAchievable(isCompound);
+    const coverageRatio = Math.round((coverageScore / maxAchievable) * 100) / 100;
+    return { ...base, coverageScore, maxAchievable, coverageRatio, coverageNote: noteFor(base, coverageScore) };
+};
+/** sidecar map → 요약 결과 (순수 함수). coverageRatio 내림차순 + 동률은 coverageScore + 이름 알파벳 */
+const buildSidecarOverridesSummary = (sidecar, componentMap) => {
+    const overrides = Object.entries(sidecar)
+        .map(([component, entry]) => toSummary(component, entry, componentMap))
+        .sort((a, b) => b.coverageRatio - a.coverageRatio ||
+        b.coverageScore - a.coverageScore ||
+        a.component.localeCompare(b.component));
+    return {
+        total: overrides.length,
+        metrics: METRIC_DESCRIPTIONS,
+        coverageScoreFormula: COVERAGE_FORMULA,
+        overrides,
+    };
+};
+exports.buildSidecarOverridesSummary = buildSidecarOverridesSummary;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+const buildListSidecarOverridesResponse = (sidecar, componentMap) => (0, response_js_1.successResponse)((0, exports.buildSidecarOverridesSummary)(sidecar, componentMap));
+exports.buildListSidecarOverridesResponse = buildListSidecarOverridesResponse;
+/** list_sidecar_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+const listSidecarOverrides = (prebuilt) => prebuilt;
+exports.listSidecarOverrides = listSidecarOverrides;

package/bin/tools/ping.d.ts

@@ -1,7 +1,7 @@
 /**
  * ping tool — NCUA MCP 서버 health check + capabilities/rules 제공 (순수 함수)
  */
-import type { ComponentData, Capability } from '../types.js';
+import type { Capability, ComponentData } from '../types.js';
 import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** ping tool 파라미터 — server.ts에서 모든 데이터를 소유하고 전달한다 */

package/bin/tools/renderToHtml.d.ts

@@ -1,21 +1,52 @@
-/**
- * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
- *
- * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
- * 이 파일에는 fs, path, require, let이 없다.
- */
-import type { ComponentData, ReactRuntime } from '../types.js';
+import type { ComponentData, JsApiInfo, ReactRuntime } from '../types.js';
 import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** render_to_html tool 파라미터 */
 export interface RenderToHtmlParams {
     componentMap: Map<string, ComponentData>;
     bundle: Record<string, unknown>;
+    iconBundle: Record<string, unknown>;
     cdnMeta: CdnMeta | null;
     iconMeta: IconMeta | null;
     reactRuntime: ReactRuntime;
+    jsApiMap: Map<string, JsApiInfo>;
     name: string;
     props?: Record<string, unknown>;
+    /**
+     * CDN init 패턴(Story 5.8) 생성 시 `<div id>` 접미사로 사용되는 고유 식별자.
+     * server.ts가 매 호출마다 `crypto.randomUUID().slice(0, 6)` 방식으로 생성해 주입한다.
+     * renderToHtml.ts는 순수 함수 원칙(파일 헤더 주석)을 위해 내부에서 랜덤을 생성하지 않는다.
+     */
+    instanceId: string;
 }
+/** Story 5.9: 사용자 props 에서 함수 prop 재귀 제거 (JSON 직렬화·deep merge 안전).
+ *  cdnDefaults 는 JSON 이라 함수 없음 → 사용자 props 만 정리.
+ *  Story 5.10: 외부 분기 모듈(`tools/external/editor.ts`)에서도 재사용 → export. */
+export declare const stripFunctionProps: (obj: unknown) => unknown;
+/** Story 5.9: cdnDefaults 와 사용자 props 를 deep merge.
+ *  - 사용자 값 우선 (lodash merge 의 두 번째 인자가 우선)
+ *  - 함수 prop 은 사용자 props 에서 stripFunctionProps 로 사전 제거
+ *  - DatePicker `datePickerOptions` 배열 한정: 각 항목의 `options` 에 cdnDefaults 의 첫 항목 options 를 per-element 부분 merge
+ *  - 다른 배열(`buttons` 등) 은 사용자 값 그대로
+ *  반환: { merged, defaultsApplied } — defaultsApplied 는 cdnDefaults 에 있고 사용자 props 에 없는 top-level 키 (defaultsUsed 응답용)
+ *  Story 5.10: 외부 분기 모듈(`tools/external/editor.ts`)에서도 재사용 → export. */
+export declare const mergeCdnDefaults: (componentName: string, cdnDefaults: Record<string, unknown> | undefined, userProps: Record<string, unknown>) => {
+    merged: Record<string, unknown>;
+    defaultsApplied: string[];
+};
+/** jsRequired에 따라 js 필드를 생성 */
+export declare const buildJsField: (componentData: ComponentData, jsApiMap: Map<string, JsApiInfo>) => {
+    required: false;
+} | {
+    api?: {
+        className: string;
+        constructor: string;
+        constructorParams: Record<string, string>;
+        methods: string[];
+        example: string;
+    } | undefined;
+    required: true;
+    description: string;
+};
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 export declare const renderToHtml: (params: RenderToHtmlParams) => McpToolResponse;