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

package/bin/tools/renderToHtml.js

@@ -1,177 +1,852 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderToHtml = void 0;
+exports.renderToHtml = exports.buildJsField = exports.mergeCdnDefaults = exports.stripFunctionProps = void 0;
+/**
+ * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
+ *
+ * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
+ * 이 파일에는 fs, path, require, let이 없다.
+ */
+// biome-ignore-all lint/complexity/noExcessiveCognitiveComplexity: 기존 spec-walk 함수 복잡도 (Story 5.8 scope 외, 별도 refactor 스토리)
+// biome-ignore-all lint/style/useExportsLast: RenderToHtmlParams export interface 상단 위치 (파일 관행)
+// biome-ignore-all lint/style/noNonNullAssertion: 기존 fallback 패턴 (Story 5.8 scope 외)
+// biome-ignore-all lint/style/noNestedTernary: 기존 reactElementToJsx의 type 판정 로직 (Story 5.8 scope 외)
+// biome-ignore-all lint/style/useTemplate: 기존 attrsPrefix 문자열 결합 (Story 5.8 scope 외)
+const lodash_1 = require("lodash");
 const response_js_1 = require("../utils/response.js");
+const editor_js_1 = require("./external/editor.js");
+const step_guide_js_1 = require("./external/step-guide.js");
 // ── 상수 ──────────────────────────────────────────────────────────
 /** React 특수 props 차단 — injection 방지 */
 const BLOCKED_PROPS = new Set(['dangerouslySetInnerHTML', 'ref', '__self', '__source']);
-/** 아이콘 관련 props — React 변환 시 import 생성 대상 */
-const ICON_PROP_NAMES = new Set(['leadingIcon', 'trailingIcon', 'icon']);
-// ── 순수 함수 (헬퍼) ──────────────────────────────────────────────
-/** componentData.exportName으로 번들에서 컴포넌트를 찾는다 */
-const findComponent = (bundle, exportName) => {
-    return bundle[exportName] ?? null;
+/** children 중첩 렌더링 제한 */
+const MAX_CHILDREN_DEPTH = 5;
+const MAX_CHILDREN_COUNT = 30;
+/** spec-walk 재귀 깊이 제한 — 순환 spec 방지 */
+const MAX_SPEC_DEPTH = 6;
+// ── 타입 가드: children 중첩 ────────────────────────────────────────
+/** { component: string, props?: object } 형태인지 판별 */
+const isChildDescriptor = (value) => typeof value === 'object' && value !== null && typeof value.component === 'string';
+/** PascalCase 변환: "header" → "Header" */
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** kebab-case → PascalCase 변환: "action-bar" → "ActionBar", "header-cell" → "HeaderCell" */
+const kebabToPascal = (s) => s.split('-').map(capitalize).join('');
+/** PascalCase → kebab-case 변환: "DataGrid" → "data-grid", "PageTitle" → "page-title" */
+const pascalToKebab = (s) => s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+/** 단순 컴포넌트 resolve: "button" → { Component, propsSpec, compoundKey: null } */
+const resolveSimpleComponent = (name, ctx) => {
+    const normalized = (0, response_js_1.normalizeName)(name);
+    const childData = ctx.componentMap.get(normalized);
+    const Component = childData?.exportName ? (ctx.bundle[childData.exportName] ?? null) : null;
+    return { Component, propsSpec: childData?.props, compoundKey: null };
 };
-/** componentMap의 props 스펙에서 defaultsUsed를 자동 계산 */
-const calcDefaultsUsed = (propsSpec, userProps) => {
-    const defaults = {};
-    for (const [key, spec] of Object.entries(propsSpec)) {
-        if (spec.default !== undefined && !(key in userProps)) {
-            defaults[key] = spec.default;
+/** compound component resolve: "data-grid.action-bar" → { Component: bundle.DataGrid.ActionBar, propsSpec: subComponents["DataGrid.ActionBar"].props } */
+const resolveCompoundComponent = (name, dotIndex, ctx) => {
+    const parentName = name.slice(0, dotIndex).toLowerCase();
+    const subName = name.slice(dotIndex + 1);
+    const parentData = ctx.componentMap.get(parentName);
+    const parentExportName = parentData?.exportName;
+    if (!parentExportName)
+        return { Component: null, propsSpec: undefined, compoundKey: null };
+    const Parent = ctx.bundle[parentExportName];
+    // kebab→PascalCase: "action-bar" → "ActionBar". 단일 워드도 정상 동작 ("header" → "Header").
+    const pascalSubName = kebabToPascal(subName);
+    const Component = Parent?.[pascalSubName] ?? null;
+    // subComponents key는 "DataGrid.ActionBar" 형태 (parent export name + PascalCase sub name)
+    const compoundKey = `${parentExportName}.${pascalSubName}`;
+    const propsSpec = parentData?.subComponents?.[compoundKey]?.props;
+    return { Component, propsSpec, compoundKey };
+};
+/**
+ * 부모 컴포넌트의 allowedChildren[parentKey].forbiddenInContext 에 자식 compound key 가 있는지 검사.
+ * 위반 시 disallowedChildren 응답 entry 생성 (silent drop 의도)
+ */
+const checkForbiddenInContext = (parentKey, childCompoundKey, parentComponentData) => {
+    const allowed = parentComponentData?.allowedChildren?.[parentKey];
+    if (!allowed || Array.isArray(allowed))
+        return null; // 단순 배열 형식은 forbiddenInContext 없음
+    const forbidden = allowed.forbiddenInContext;
+    if (!forbidden)
+        return null;
+    const message = forbidden[childCompoundKey];
+    if (!message)
+        return null;
+    return { reason: 'forbidden_in_context', message };
+};
+/** children JSON을 재귀적으로 React element로 변환 — silent drop 차단 + composition 제약 검증 */
+const resolveChildren = (children, ctx, depth) => {
+    if (depth > MAX_CHILDREN_DEPTH)
+        return null;
+    // 문자열/숫자/boolean — 그대로 반환
+    if (typeof children === 'string' || typeof children === 'number' || typeof children === 'boolean')
+        return children;
+    // 배열 — 각 요소를 재귀 처리 (MAX_CHILDREN_COUNT 제한, undefined/null 결과 filter)
+    if (Array.isArray(children)) {
+        const limited = children.slice(0, MAX_CHILDREN_COUNT);
+        const results = [];
+        limited.forEach((child, idx) => {
+            const childCtx = { ...ctx, path: `${ctx.path}[${idx}]` };
+            const resolved = resolveChildren(child, childCtx, depth);
+            if (resolved !== null && resolved !== undefined)
+                results.push(resolved);
+        });
+        return results;
+    }
+    // { component, props?, children? } — React element로 변환
+    if (isChildDescriptor(children)) {
+        const componentName = children.component.trim();
+        const dotIndex = componentName.indexOf('.');
+        // dot notation: "data-grid.action-bar" → bundle.DataGrid.ActionBar (+ subComponents props spec)
+        const resolved = dotIndex > 0
+            ? resolveCompoundComponent(componentName, dotIndex, ctx)
+            : resolveSimpleComponent(componentName, ctx);
+        const { Component, propsSpec, compoundKey } = resolved;
+        // ── 갭 해소 1: forbiddenInContext 검증 (resolve 가 성공해도 컨텍스트 위반은 차단) ──
+        if (Component && compoundKey && ctx.parentKey) {
+            // ctx.parentKey 는 PascalCase ("DataGrid" 또는 "DataGrid.Table") — componentMap 키는 kebab-case 이므로 변환
+            const rootParentExport = ctx.parentKey.split('.')[0]; // "DataGrid"
+            const parentName = pascalToKebab(rootParentExport); // "data-grid"
+            const parentData = ctx.componentMap.get(parentName);
+            const forbidden = checkForbiddenInContext(ctx.parentKey, compoundKey, parentData);
+            if (forbidden) {
+                ctx.disallowedChildren.push({
+                    path: ctx.path,
+                    parent: ctx.parentKey,
+                    child: compoundKey,
+                    reason: forbidden.reason,
+                    message: forbidden.message,
+                });
+                ctx.warnings.push(`${componentName} 은(는) ${ctx.parentKey} 안에서 사용할 수 없음: ${forbidden.message}`);
+                return null; // silent drop
+            }
+        }
+        // ── 갭 해소 2: lookup 실패 → unknownChildren 보고 (silent drop 차단) ──
+        if (!Component) {
+            const reason = dotIndex > 0 ? 'unknown_subcomponent' : 'unknown_component';
+            ctx.unknownChildren.push({ path: ctx.path, component: componentName, reason });
+            ctx.warnings.push(reason === 'unknown_subcomponent'
+                ? `'${componentName}' 은(는) 알 수 없는 sub-component. get_component_props 로 subComponents 확인 후 정정.`
+                : `'${componentName}' 은(는) 알 수 없는 component. list_components 로 정식 이름 확인 후 정정.`);
+            return null;
+        }
+        // BLOCKED_PROPS(dangerouslySetInnerHTML, ref, __self, __source)를 먼저 제거
+        // propsSpec이 있으면 화이트리스트 필터(sanitizeProps)도 적용하여 XSS/alien prop 차단
+        const rawProps = children.props ?? {};
+        const blockedRemoved = removeBlockedProps(rawProps);
+        const childProps = propsSpec ? sanitizeProps(blockedRemoved, propsSpec) : blockedRemoved;
+        // descriptor의 children 필드가 있으면 props.children보다 우선
+        const rawChildren = children.children !== undefined ? children.children : childProps.children;
+        if (rawChildren !== undefined) {
+            // 자식 재귀 시 parentKey 전파 — forbiddenInContext 검증에 사용
+            const nestedCtx = {
+                ...ctx,
+                parentKey: compoundKey ?? ctx.parentKey,
+                path: `${ctx.path}>${componentName}`,
+            };
+            childProps.children = resolveChildren(rawChildren, nestedCtx, depth + 1);
         }
+        const resolvedProps = resolveIconProps(childProps, ctx.iconBundle, propsSpec);
+        return ctx.reactRuntime.createElement(Component, resolvedProps);
     }
-    return defaults;
+    return children;
 };
+// ── Props 변환 ──────────────────────────────────────────────────────
 /** BLOCKED_PROPS를 제거 — props spec 유무와 무관하게 항상 적용 */
-const removeBlockedProps = (props) => {
-    const safe = {};
-    for (const [key, value] of Object.entries(props)) {
-        if (!BLOCKED_PROPS.has(key))
-            safe[key] = value;
-    }
-    return safe;
-};
+const removeBlockedProps = (props) => Object.fromEntries(Object.entries(props).filter(([key]) => !BLOCKED_PROPS.has(key)));
 /** componentData.props에 정의된 키 + children만 허용하는 화이트리스트 필터 */
 const sanitizeProps = (userProps, propsSpec) => {
     const allowedKeys = new Set([...Object.keys(propsSpec), 'children']);
-    const sanitized = {};
-    for (const [key, value] of Object.entries(userProps)) {
-        if (allowedKeys.has(key))
-            sanitized[key] = value;
+    return Object.fromEntries(Object.entries(userProps).filter(([key]) => allowedKeys.has(key)));
+};
+/**
+ * spec-walk 재귀 resolver — spec.semantic === 'icon-component' 위치에서 문자열을 iconBundle 컴포넌트로 치환
+ *
+ * 이름 화이트리스트가 아닌 **타입 정체성(semantic)** 기반 판정.
+ * extract 단계에서 ts-morph가 SlotIconComponent alias를 감지하여 spec.semantic을 부착한다.
+ * 중첩 객체/배열을 spec.properties를 따라 자동 순회하므로 어떤 깊이에도 대응.
+ */
+const resolveValueBySpec = (value, spec, iconBundle, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH)
+        return value;
+    if (!spec)
+        return value;
+    // leaf: icon-component 위치에서 string → 컴포넌트 치환. bundle miss 시 원본 유지.
+    if (spec.semantic === 'icon-component' && typeof value === 'string') {
+        const iconComponent = iconBundle[value];
+        return typeof iconComponent === 'function' ? iconComponent : value;
     }
-    return sanitized;
+    // 배열: spec이 배열 타입이고 value가 배열이면 각 요소에 재귀 (spec.properties는 요소 shape)
+    if (spec.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        return value.map((item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                const resolved = { ...obj };
+                for (const [key, childSpec] of Object.entries(spec.properties)) {
+                    if (key in resolved) {
+                        resolved[key] = resolveValueBySpec(resolved[key], childSpec, iconBundle, depth + 1);
+                    }
+                }
+                return resolved;
+            }
+            return item;
+        });
+    }
+    // 중첩 객체: spec.properties를 따라 각 키에 재귀 적용
+    if (spec.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const resolved = { ...obj };
+        for (const [key, childSpec] of Object.entries(spec.properties)) {
+            if (key in resolved) {
+                resolved[key] = resolveValueBySpec(resolved[key], childSpec, iconBundle, depth + 1);
+            }
+        }
+        return resolved;
+    }
+    return value;
 };
+/** 최상위 props를 propsSpec에 따라 재귀 resolve */
+const resolveIconProps = (props, iconBundle, propsSpec) => {
+    if (!propsSpec)
+        return props;
+    const resolved = { ...props };
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        if (key in resolved) {
+            resolved[key] = resolveValueBySpec(resolved[key], spec, iconBundle);
+        }
+    }
+    return resolved;
+};
+// ── JSX 변환 ──────────────────────────────────────────────────────
 /** JSX attribute 값에서 " 를 이스케이프 */
 const escapeJsxAttrValue = (value) => value.replace(/"/g, '"');
-/** props 값을 JSX attribute 문자열로 변환 */
-const propsToJsxAttrs = (props, propsSpec) => {
-    const attrs = [];
-    for (const [key, value] of Object.entries(props)) {
-        if (key === 'children')
-            continue;
+/**
+ * spec-walk 재귀로 JSX 값 문자열을 생성.
+ * icon-component 위치의 문자열은 컴포넌트 이름 참조(중괄호 없는 identifier)로,
+ * 중첩 객체는 `{ key: ... }` object literal 형태로 직렬화.
+ */
+const toJsxValueBySpec = (value, spec, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH)
+        return JSON.stringify(value);
+    // leaf: icon-component 위치의 문자열은 identifier로 반환
+    if (spec?.semantic === 'icon-component' && typeof value === 'string')
+        return value;
+    // 배열: 각 요소를 재귀 직렬화
+    if (spec?.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        const items = value.map((item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                const entries = Object.entries(obj).map(([k, v]) => {
+                    const childSpec = spec.properties?.[k];
+                    return `${k}: ${toJsxValueBySpec(v, childSpec, depth + 1)}`;
+                });
+                return `{ ${entries.join(', ')} }`;
+            }
+            return JSON.stringify(item);
+        });
+        return `[${items.join(', ')}]`;
+    }
+    // 중첩 객체: spec.properties 따라 각 키를 재귀 직렬화
+    if (spec?.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const entries = Object.entries(obj).map(([k, v]) => {
+            const childSpec = spec.properties?.[k];
+            return `${k}: ${toJsxValueBySpec(v, childSpec, depth + 1)}`;
+        });
+        return `{ ${entries.join(', ')} }`;
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    return JSON.stringify(value);
+};
+/** 단일 prop을 JSX attribute 문자열로 변환 — spec-driven */
+const toJsxAttr = (key, value, spec) => {
+    if (typeof value === 'boolean' && value)
+        return key;
+    // icon-component 최상위 prop — key={SearchLg} 형태
+    if (spec?.semantic === 'icon-component' && typeof value === 'string')
+        return `${key}={${value}}`;
+    // 배열 prop — key={[{ ... }, { ... }]} 형태
+    if (spec?.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        return `${key}={${toJsxValueBySpec(value, spec)}}`;
+    }
+    // 중첩 spec 객체 — key={{ icon: X, color: 'success', ... }} 형태 (JSX 표현식 중괄호로 감싸기)
+    if (spec?.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        return `${key}={${toJsxValueBySpec(value, spec)}}`;
+    }
+    if (typeof value === 'string')
+        return `${key}="${escapeJsxAttrValue(value)}"`;
+    if (typeof value === 'number')
+        return `${key}={${value}}`;
+    if (spec?.type === 'enum' || spec?.type === 'string')
+        return `${key}="${String(value)}"`;
+    return `${key}={${JSON.stringify(value)}}`;
+};
+/** props 객체를 JSX attribute 문자열로 변환 */
+const propsToJsxAttrs = (props, propsSpec) => Object.entries(props)
+    .filter(([key]) => key !== 'children')
+    .map(([key, value]) => toJsxAttr(key, value, propsSpec[key]))
+    .join(' ');
+// ── 아이콘 추출 ──────────────────────────────────────────────────
+/** spec-walk로 value에서 icon-component 위치의 문자열 이름을 수집. 중첩 객체 + 배열까지 내려감. */
+const collectIconNamesBySpec = (value, spec, acc, depth = 0) => {
+    if (depth > MAX_SPEC_DEPTH || !spec)
+        return;
+    if (spec.semantic === 'icon-component' && typeof value === 'string' && value.length > 0) {
+        acc.add(value);
+        return;
+    }
+    // 배열 요소 재귀
+    if (spec.rawType?.includes('[]') && spec.properties && Array.isArray(value)) {
+        for (const item of value) {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const obj = item;
+                for (const [key, childSpec] of Object.entries(spec.properties)) {
+                    if (key in obj)
+                        collectIconNamesBySpec(obj[key], childSpec, acc, depth + 1);
+                }
+            }
+        }
+        return;
+    }
+    if (spec.properties && value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        for (const [key, childSpec] of Object.entries(spec.properties)) {
+            if (key in obj) {
+                collectIconNamesBySpec(obj[key], childSpec, acc, depth + 1);
+            }
+        }
+    }
+};
+/** propsSpec을 따라 appliedProps에서 아이콘 이름을 수집 — 이름 화이트리스트 없음 */
+const extractIconNames = (props, propsSpec) => {
+    if (!propsSpec)
+        return [];
+    const acc = new Set();
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        if (key in props)
+            collectIconNamesBySpec(props[key], spec, acc);
+    }
+    return [...acc];
+};
+// ── 검증 ────────────────────────────────────────────────────────
+/** 잘못된 enum 값을 경고 문자열로 변환 — 교정 결과도 포함 */
+const formatInvalidEnum = (key, value, spec) => {
+    const allowed = spec.values ?? [];
+    const correction = spec.default !== undefined ? ` Corrected to default '${spec.default}'.` : ' Removed (no default).';
+    return `Invalid enum value '${value}' for prop '${key}'.${correction} Allowed: ${allowed.join(', ')}.`;
+};
+/** props 검증 — enum 불일치, 필수 prop 누락을 warnings로 반환 */
+const validateProps = (userProps, propsSpec) => {
+    const missingRequired = Object.entries(propsSpec)
+        .filter(([key, spec]) => spec.required && !(key in userProps))
+        .map(([key]) => `Required prop '${key}' is missing.`);
+    const invalidEnums = Object.entries(userProps)
+        .filter(([key, value]) => {
         const spec = propsSpec[key];
-        if (typeof value === 'boolean' && value) {
-            attrs.push(key);
+        return spec?.type === 'enum' && spec.values && typeof value === 'string' && !spec.values.includes(value);
+    })
+        .map(([key, value]) => formatInvalidEnum(key, value, propsSpec[key]));
+    const missingArrays = Object.entries(propsSpec)
+        .filter(([key, spec]) => spec.rawType?.includes('[]') && !(key in userProps))
+        .map(([key]) => `Array prop '${key}' is missing. Filled with empty array []. Pass data for meaningful rendering.`);
+    return [...missingRequired, ...invalidEnums, ...missingArrays];
+};
+/** invalid enum 값을 default 또는 제거로 교정 — 할루시네이션 HTML 방지 */
+const correctInvalidEnums = (userProps, propsSpec) => {
+    const corrected = { ...userProps };
+    for (const [key, value] of Object.entries(corrected)) {
+        const spec = propsSpec[key];
+        if (spec?.type !== 'enum' || !spec.values || typeof value !== 'string')
+            continue;
+        if (spec.values.includes(value))
+            continue;
+        if (spec.default !== undefined) {
+            corrected[key] = spec.default;
+        }
+        else {
+            delete corrected[key];
+        }
+    }
+    return corrected;
+};
+/** required prop 누락 시 type별 safe default 주입 — React crash 방지 (fillMissingArrayProps 통합) */
+const correctMissingRequired = (userProps, propsSpec) => {
+    const corrected = { ...userProps };
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        // array prop — required 여부와 무관하게 [] 주입 (.map() crash 방지)
+        if (spec.rawType?.includes('[]') && !(key in corrected && Array.isArray(corrected[key]))) {
+            corrected[key] = [];
+            continue;
+        }
+        // required가 아니거나 이미 값이 있으면 스킵
+        if (!spec.required || key in corrected)
+            continue;
+        // default가 있으면 사용
+        if (spec.default !== undefined) {
+            corrected[key] = spec.default;
+            continue;
+        }
+        // icon-component 타입 — 빈 span 반환 스텁 주입하여 crash 방지 (spec.semantic 기반 판정)
+        if (spec.semantic === 'icon-component') {
+            corrected[key] = () => null;
+            continue;
+        }
+        // 일반 function/ReactNode는 HTML에 영향 없으므로 주입하지 않음
+        if (spec.type === 'function' || spec.type === 'ReactNode')
+            continue;
+        // type별 safe default
+        const safeDefaults = {
+            string: '',
+            object: {},
+            boolean: false,
+            number: 0,
+            enum: spec.values?.[0] ?? '',
+        };
+        if (spec.type in safeDefaults) {
+            corrected[key] = safeDefaults[spec.type];
+        }
+    }
+    return corrected;
+};
+// ── CDN init 패턴 (Story 5.8) ─────────────────────────────────────
+/**
+ * CDN 호출 패턴은 `js-api.json`의 `cdnPattern` 필드(A/B/C)로 단일 관리한다.
+ * 컴포넌트 추가 시 js-api.json 한 곳에만 패턴을 명시하면 자동 인식된다.
+ */
+/** options를 안전하게 직렬화 — script 블록 탈출 방지(`</script>` 이스케이프) */
+const serializeCdnOptions = (options) => JSON.stringify(options).replace(/<\/script/gi, '<\\/script');
+/** 패턴 A: `new ncua.X(wrapper, options)` */
+const buildPatternA = (id, className, options) => [
+    `<div id="${id}"></div>`,
+    '<script>',
+    "  document.addEventListener('DOMContentLoaded', function () {",
+    `    const wrapper = document.querySelector('#${id}');`,
+    `    new ncua.${className}(wrapper, ${serializeCdnOptions(options)});`,
+    '  });',
+    '</script>',
+].join('\n');
+/** 패턴 B: `new ncua.X({...options, container: id})` — container 자동 주입 */
+const buildPatternB = (id, className, options) => [
+    `<div id="${id}"></div>`,
+    '<script>',
+    "  document.addEventListener('DOMContentLoaded', function () {",
+    `    new ncua.${className}(${serializeCdnOptions({ ...options, container: id })});`,
+    '  });',
+    '</script>',
+].join('\n');
+/** 패턴 C: `new ncua.X(options)` + `getElement()` + 수동 append */
+const buildPatternC = (id, className, options) => [
+    `<div id="${id}"></div>`,
+    '<script>',
+    "  document.addEventListener('DOMContentLoaded', function () {",
+    `    const wrapper = document.querySelector('#${id}');`,
+    `    const inst = new ncua.${className}(${serializeCdnOptions(options)});`,
+    '    wrapper.appendChild(inst.getElement());',
+    '  });',
+    '</script>',
+].join('\n');
+/**
+ * CDN init 스크립트 생성. 패턴은 `jsApi.cdnPattern` (A/B/C)으로 결정한다.
+ * 호출자는 `cdnPattern` 부재 시 isCdnInput=false로 분기하여 React renderToStaticMarkup 경로를 사용한다.
+ */
+const buildCdnInitScript = (pattern, componentName, instanceId, className, options) => {
+    const id = `ncua-${componentName}-${instanceId}`;
+    if (pattern === 'A')
+        return buildPatternA(id, className, options);
+    if (pattern === 'B')
+        return buildPatternB(id, className, options);
+    return buildPatternC(id, className, options);
+};
+/** options 키 중 `jsApi.constructorParams`에 없는 키를 warning 메시지로 변환.
+ *  constructorParams의 키는 `config.options` 같은 dot 표기 — 마지막 segment만 추출해 비교. */
+const checkUnknownCdnKeys = (options, jsApi) => {
+    if (Object.keys(jsApi.constructorParams).length === 0)
+        return [];
+    const allowedKeys = new Set();
+    for (const param of Object.keys(jsApi.constructorParams)) {
+        const lastDot = param.lastIndexOf('.');
+        allowedKeys.add(lastDot >= 0 ? param.slice(lastDot + 1) : param);
+    }
+    return Object.keys(options)
+        .filter((key) => !allowedKeys.has(key))
+        .map((key) => `Unknown CDN option key '${key}' for component '${jsApi.className}'. Passed through as-is. Verify against constructorParams.`);
+};
+/** SelectBox/ComboBox `options` 배열 요소 키 정규화.
+ *  공식 docs는 `{id, label}` 또는 `{id, text}` 허용. React 매칭은 `label`만 받으므로
+ *  통일된 `{id, label}`로 정규화. `{value, text}`는 비표준 alias(HTML `<option>` 컨벤션
+ *  오용)이며 함께 변환. 정규화 발생 시 warning 기록(에이전트 학습용). */
+const normalizeCdnInputProps = (componentName, cdnConfig) => {
+    if (componentName !== 'select-box' && componentName !== 'combo-box') {
+        return { normalized: cdnConfig, warnings: [] };
+    }
+    const { options } = cdnConfig;
+    if (!Array.isArray(options))
+        return { normalized: cdnConfig, warnings: [] };
+    const aliasesUsed = new Set();
+    const normalizedOptions = options.map((opt) => {
+        if (opt === null || typeof opt !== 'object')
+            return opt;
+        const item = { ...opt };
+        if (item.id === undefined && item.value !== undefined) {
+            item.id = item.value;
+            delete item.value;
+            aliasesUsed.add('value');
         }
-        else if (typeof value === 'string') {
-            attrs.push(`${key}="${escapeJsxAttrValue(value)}"`);
+        if (item.label === undefined && item.text !== undefined) {
+            item.label = item.text;
+            delete item.text;
+            aliasesUsed.add('text');
         }
-        else if (typeof value === 'number') {
-            attrs.push(`${key}={${value}}`);
+        return item;
+    });
+    const warnings = [];
+    if (aliasesUsed.has('value')) {
+        warnings.push(`Option key 'value' normalized to 'id' for component '${componentName}'. Canonical form is {id, label}.`);
+    }
+    if (aliasesUsed.has('text')) {
+        warnings.push(`Option key 'text' normalized to 'label' for component '${componentName}'. Canonical form is {id, label}.`);
+    }
+    return { normalized: { ...cdnConfig, options: normalizedOptions }, warnings };
+};
+/** Story 5.9: 사용자 props 에서 함수 prop 재귀 제거 (JSON 직렬화·deep merge 안전).
+ *  cdnDefaults 는 JSON 이라 함수 없음 → 사용자 props 만 정리.
+ *  Story 5.10: 외부 분기 모듈(`tools/external/editor.ts`)에서도 재사용 → export. */
+const stripFunctionProps = (obj) => {
+    if (typeof obj === 'function')
+        return undefined;
+    if (Array.isArray(obj)) {
+        return obj.map((item) => (0, exports.stripFunctionProps)(item)).filter((item) => item !== undefined);
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        return Object.fromEntries(Object.entries(obj)
+            .filter(([, value]) => typeof value !== 'function')
+            .map(([key, value]) => [key, (0, exports.stripFunctionProps)(value)]));
+    }
+    return obj;
+};
+exports.stripFunctionProps = stripFunctionProps;
+/** 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. */
+const mergeCdnDefaults = (componentName, cdnDefaults, userProps) => {
+    if (!cdnDefaults)
+        return { merged: userProps, defaultsApplied: [] };
+    const userPropsClean = (0, exports.stripFunctionProps)(userProps);
+    const baseMerged = (0, lodash_1.merge)((0, lodash_1.cloneDeep)(cdnDefaults), userPropsClean);
+    const merged = componentName === 'date-picker' && Array.isArray(userPropsClean.datePickerOptions)
+        ? {
+            ...baseMerged,
+            datePickerOptions: userPropsClean.datePickerOptions.map((item) => {
+                const baseOptions = cdnDefaults.datePickerOptions?.[0]?.options ?? {};
+                return {
+                    ...item,
+                    options: (0, lodash_1.merge)((0, lodash_1.cloneDeep)(baseOptions), item.options ?? {}),
+                };
+            }),
         }
-        else if (ICON_PROP_NAMES.has(key) && typeof value === 'object' && value !== null) {
-            const iconObj = value;
-            if (iconObj.type === 'icon' && typeof iconObj.icon === 'string') {
-                attrs.push(`${key}={{ type: 'icon', icon: ${iconObj.icon} }}`);
+        : baseMerged;
+    const defaultsApplied = Object.keys(cdnDefaults).filter((key) => !(key in userPropsClean));
+    return { merged, defaultsApplied };
+};
+exports.mergeCdnDefaults = mergeCdnDefaults;
+/** CDN config(에이전트 입력) → React props (buildReactOutput 입력) 번역.
+ *  단순 컴포넌트는 identity, 차이가 있는 컴포넌트는 별도 룰. */
+const translateCdnToReactProps = (componentName, cdnConfig) => {
+    // SelectBox/ComboBox: options → optionItems, value(원시) → value(객체) (배열에서 매칭해 wrap)
+    if (componentName === 'select-box' || componentName === 'combo-box') {
+        const { options, value, ...rest } = cdnConfig;
+        const result = { ...rest };
+        if (options !== undefined)
+            result.optionItems = options;
+        if (value !== undefined) {
+            if ((typeof value === 'string' || typeof value === 'number') && Array.isArray(options)) {
+                const matched = options.find((opt) => typeof opt === 'object' && opt !== null && opt.id === value);
+                result.value = matched !== undefined ? matched : value;
             }
             else {
-                attrs.push(`${key}={${JSON.stringify(value)}}`);
+                result.value = value;
             }
         }
-        else if (spec?.type === 'enum' || spec?.type === 'string') {
-            attrs.push(`${key}="${String(value)}"`);
-        }
-        else {
-            attrs.push(`${key}={${JSON.stringify(value)}}`);
-        }
+        return result;
     }
-    return attrs.join(' ');
+    // FileInput/ImageFileInput: container 키는 React props에 없음 → 제거
+    if (componentName === 'file-input' || componentName === 'image-file-input') {
+        const result = { ...cdnConfig };
+        delete result.container;
+        return result;
+    }
+    // 그 외: identity (Slider, DatePicker, Tooltip, Notification, ProgressBar, Tag — key 동일 가정)
+    return cdnConfig;
 };
-/** appliedProps에서 아이콘 이름을 추출 (PascalCase) */
-const extractIconNames = (props) => {
-    const icons = [];
-    for (const [key, value] of Object.entries(props)) {
-        if (!ICON_PROP_NAMES.has(key))
-            continue;
-        if (typeof value === 'object' && value !== null) {
-            const iconObj = value;
-            if (iconObj.type === 'icon' && typeof iconObj.icon === 'string') {
-                icons.push(iconObj.icon);
+// ── 응답 조립 ──────────────────────────────────────────────────────
+/** componentMap의 props 스펙에서 defaultsUsed를 자동 계산 */
+const calcDefaultsUsed = (propsSpec, userProps) => Object.fromEntries(Object.entries(propsSpec)
+    .filter(([key, spec]) => spec.default !== undefined && !(key in userProps))
+    .map(([key, spec]) => [key, spec.default]));
+/** descriptor의 component 이름에서 해당 컴포넌트의 propsSpec을 조회 */
+const lookupPropsSpecByComponentName = (componentName, componentMap) => {
+    const dotIndex = componentName.indexOf('.');
+    if (dotIndex > 0) {
+        const parentName = componentName.slice(0, dotIndex).toLowerCase();
+        const subName = componentName.slice(dotIndex + 1);
+        const parentData = componentMap.get(parentName);
+        if (!parentData?.exportName)
+            return undefined;
+        const compoundKey = `${parentData.exportName}.${kebabToPascal(subName)}`;
+        return parentData.subComponents?.[compoundKey]?.props;
+    }
+    return componentMap.get((0, response_js_1.normalizeName)(componentName))?.props;
+};
+/** descriptor/React element 트리를 JSX 문자열로 변환. spec을 따라 icon-component를 식별자로 직렬화하고 사용된 icon 이름을 누적 */
+const reactElementToJsx = (node, ctx) => {
+    if (node == null)
+        return '';
+    if (typeof node === 'string')
+        return node;
+    if (typeof node === 'number' || typeof node === 'boolean')
+        return String(node);
+    if (Array.isArray(node))
+        return node.map((n) => reactElementToJsx(n, ctx)).join('\n');
+    // Component descriptor: { component, props, children } — compound component 포함
+    if (typeof node === 'object' && 'component' in node) {
+        const desc = node;
+        const componentName = desc.component.trim();
+        // "data-grid.action-bar" → "DataGrid.ActionBar" (kebab→PascalCase per dot segment)
+        const pascalName = componentName.split('.').map(kebabToPascal).join('.');
+        const propsSpec = lookupPropsSpecByComponentName(componentName, ctx.componentMap);
+        // 이 descriptor에서 사용된 icon 이름 수집 (imports 생성용)
+        if (propsSpec && desc.props) {
+            for (const [key, spec] of Object.entries(propsSpec)) {
+                if (key in desc.props)
+                    collectIconNamesBySpec(desc.props[key], spec, ctx.iconNames);
             }
         }
-        else if (typeof value === 'string' && value.length > 0) {
-            icons.push(value);
+        const { children: descChildren, ...restProps } = desc.props || {};
+        const attrs = Object.entries(restProps)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => toJsxAttr(k, v, propsSpec?.[k]))
+            .join(' ');
+        const attrsStr = attrs ? ` ${attrs}` : '';
+        const inner = desc.children ?? descChildren;
+        if (inner != null) {
+            return `<${pascalName}${attrsStr}>${reactElementToJsx(inner, ctx)}</${pascalName}>`;
         }
+        return `<${pascalName}${attrsStr} />`;
     }
-    return icons;
+    // React element: { type, props, ... } — spec 조회 불가 → 최소 직렬화
+    if (typeof node === 'object' && 'type' in node) {
+        const el = node;
+        const name = typeof el.type === 'string'
+            ? el.type
+            : typeof el.type === 'function'
+                ? el.type.displayName ||
+                    el.type.name ||
+                    'Component'
+                : 'Component';
+        const { children: childChildren, ...restProps } = el.props || {};
+        const attrs = Object.entries(restProps)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => {
+            if (typeof v === 'boolean' && v)
+                return k;
+            if (typeof v === 'string')
+                return `${k}="${v}"`;
+            return `${k}={${JSON.stringify(v)}}`;
+        })
+            .join(' ');
+        const attrsStr = attrs ? ` ${attrs}` : '';
+        if (childChildren != null) {
+            return `<${name}${attrsStr}>${reactElementToJsx(childChildren, ctx)}</${name}>`;
+        }
+        return `<${name}${attrsStr} />`;
+    }
+    return String(node);
 };
-/** React 변환 매핑 정보를 생성 */
-const buildReactOutput = (componentData, appliedProps, iconMeta) => {
+/** React 변환 매핑 정보를 생성 — top-level + 중첩 descriptor에서 사용된 icon을 모두 수집 */
+const buildReactOutput = (componentData, appliedProps, iconMeta, componentMap) => {
     const { exportName, importPath, props: propsSpec } = componentData;
-    const imports = [`import { ${exportName} } from '${importPath}';`];
     const dependencies = [importPath];
-    const iconNames = extractIconNames(appliedProps);
-    if (iconNames.length > 0 && iconMeta) {
-        const iconImport = `import { ${iconNames.join(', ')} } from '${iconMeta.packageName}';`;
-        imports.push(iconImport);
+    // top-level props에서 icon 이름 수집
+    const iconNames = new Set(extractIconNames(appliedProps, propsSpec));
+    const attrsStr = propsSpec ? propsToJsxAttrs(appliedProps, propsSpec) : '';
+    const attrsPrefix = attrsStr ? ' ' + attrsStr : '';
+    const children = appliedProps.children;
+    // children 트리 직렬화 — 그 과정에서 중첩 descriptor의 icon도 누적
+    const jsxCtx = { componentMap, iconNames };
+    const jsx = children
+        ? `<${exportName}${attrsPrefix}>${reactElementToJsx(children, jsxCtx)}</${exportName}>`
+        : `<${exportName}${attrsPrefix} />`;
+    const imports = [`import { ${exportName} } from '${importPath}';`];
+    if (iconNames.size > 0 && iconMeta) {
+        imports.push(`import { ${[...iconNames].join(', ')} } from '${iconMeta.packageName}';`);
         if (!dependencies.includes(iconMeta.packageName)) {
             dependencies.push(iconMeta.packageName);
         }
     }
-    const attrsStr = propsSpec ? propsToJsxAttrs(appliedProps, propsSpec) : '';
-    const children = appliedProps.children;
-    const jsx = children
-        ? `<${exportName}${attrsStr ? ' ' + attrsStr : ''}>${String(children)}</${exportName}>`
-        : `<${exportName}${attrsStr ? ' ' + attrsStr : ''} />`;
-    return {
-        imports,
-        jsx,
-        cssImport: `import '${importPath}/style.css';`,
-        dependencies,
-    };
+    return { imports, jsx, cssImport: `import '${importPath}/style.css';`, dependencies };
 };
 /** dataVersion 객체를 생성 */
-const buildDataVersion = (cdnMeta, iconMeta) => {
-    const versions = {};
-    if (cdnMeta)
-        versions['@ncds/ui-admin'] = cdnMeta.version;
-    if (iconMeta)
-        versions[iconMeta.packageName] = iconMeta.version;
-    return versions;
+const buildDataVersion = (cdnMeta, iconMeta) => ({
+    ...(cdnMeta && { '@ncds/ui-admin': cdnMeta.version }),
+    ...(iconMeta && { [iconMeta.packageName]: iconMeta.version }),
+});
+/** jsRequired에 따라 js 필드를 생성 */
+const buildJsField = (componentData, jsApiMap) => {
+    if (!componentData.jsRequired)
+        return { required: false };
+    const jsApi = jsApiMap.get(componentData.exportName);
+    return {
+        required: true,
+        description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+        ...(jsApi && {
+            api: {
+                className: jsApi.className,
+                constructor: jsApi.constructor,
+                constructorParams: jsApi.constructorParams,
+                methods: jsApi.methods,
+                example: jsApi.example,
+            },
+        }),
+    };
 };
+exports.buildJsField = buildJsField;
 // ── 진입점 ────────────────────────────────────────────────────────
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 const renderToHtml = (params) => {
-    const { componentMap, bundle, cdnMeta, iconMeta, reactRuntime, name, props } = params;
+    const { componentMap, bundle, iconBundle, cdnMeta, iconMeta, reactRuntime, jsApiMap, name, props, instanceId } = params;
     const normalized = (0, response_js_1.normalizeName)(name);
+    // Story 5.10: editor alias 검출 시 ui-admin 흐름 우회 — 외부 분기에서 응답 직접 조립
+    if ((0, editor_js_1.isEditorAlias)(normalized)) {
+        return (0, editor_js_1.buildEditorResponse)(props ?? {}, instanceId);
+    }
+    // Story 6.1: step-guide alias 검출 시 ui-admin 흐름 우회 — 외부 분기 (함수 호출 형식)
+    if ((0, step_guide_js_1.isStepGuideAlias)(normalized)) {
+        return (0, step_guide_js_1.buildStepGuideResponse)(props ?? {}, instanceId);
+    }
     const componentData = componentMap.get(normalized);
     if (!componentData)
         return (0, response_js_1.componentNotFoundResponse)(normalized);
     const exportName = componentData.exportName;
     if (!exportName) {
-        return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (yarn extract).');
+        return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (pnpm extract).');
     }
-    const Component = findComponent(bundle, exportName);
+    const Component = bundle[exportName] ?? null;
     if (!Component) {
-        return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (yarn build:bundle).');
+        return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (pnpm build:bundle).');
     }
     try {
-        const rawProps = props ?? {};
-        const safeProps = removeBlockedProps(rawProps);
-        const userProps = componentData.props ? sanitizeProps(safeProps, componentData.props) : safeProps;
-        const element = reactRuntime.createElement(Component, userProps);
-        const rawHtml = reactRuntime.renderToStaticMarkup(element);
-        const html = `<!-- ncua:${normalized} -->\n${rawHtml}\n<!-- /ncua:${normalized} -->`;
-        const defaultsUsed = componentData.props ? calcDefaultsUsed(componentData.props, userProps) : {};
-        const react = buildReactOutput(componentData, userProps, iconMeta);
-        const dataVersion = buildDataVersion(cdnMeta, iconMeta);
+        // Story 5.8: jsRequired + js-api 정의 + jsApi.cdnPattern 등록 → CDN-input 모드
+        const jsApi = jsApiMap.get(exportName);
+        const isCdnInput = componentData.jsRequired && jsApi !== undefined && jsApi.cdnPattern !== undefined;
+        // CDN-input은 입력이 CDN config 스키마 → 옵션 배열 키 정규화 → React 파이프라인을 위해 React props로 번역
+        const cdnNormalization = isCdnInput
+            ? normalizeCdnInputProps(normalized, props ?? {})
+            : { normalized: props ?? {}, warnings: [] };
+        const normalizedCdnProps = cdnNormalization.normalized;
+        // Story 5.9: cdnDefaults 와 deep merge (사용자 props 우선, 함수 prop skip, datePickerOptions per-element 부분 merge)
+        const cdnMergeResult = isCdnInput && jsApi
+            ? (0, exports.mergeCdnDefaults)(normalized, jsApi.cdnDefaults, normalizedCdnProps)
+            : { merged: normalizedCdnProps, defaultsApplied: [] };
+        const mergedCdnProps = cdnMergeResult.merged;
+        const reactInput = isCdnInput ? translateCdnToReactProps(normalized, mergedCdnProps) : mergedCdnProps;
+        const safeProps = removeBlockedProps(reactInput);
+        const sanitized = componentData.props ? sanitizeProps(safeProps, componentData.props) : safeProps;
+        const enumWarnings = componentData.props ? validateProps(sanitized, componentData.props) : [];
+        const enumCorrected = componentData.props ? correctInvalidEnums(sanitized, componentData.props) : sanitized;
+        const corrected = componentData.props ? correctMissingRequired(enumCorrected, componentData.props) : enumCorrected;
+        const postWarnings = componentData.props ? validateProps(corrected, componentData.props) : [];
+        const cdnKeyWarnings = isCdnInput && jsApi ? checkUnknownCdnKeys(normalizedCdnProps, jsApi) : [];
+        const warnings = [
+            ...enumWarnings,
+            ...postWarnings.filter((w) => !enumWarnings.includes(w)),
+            ...cdnKeyWarnings,
+            ...cdnNormalization.warnings,
+        ];
+        const resolvedProps = resolveIconProps(corrected, iconBundle, componentData.props);
+        // P12: children + 모든 ReactNode prop 에 대해 component descriptor 자동 resolve.
+        // PageTitle.primaryAction / Modal.actions / BlockHeader.tooltip 같은 ReactNode prop 에
+        // {component, props, children} descriptor 또는 그 배열을 넘기면 React element 로 변환.
+        // children 외 ReactNode prop 도 동일 흐름 — godomall5 결과물에서 PageTitle action 이
+        // 빈 상태로 떨어진 근본 원인(ReactNode prop 자동 resolve 부재) 해결.
+        // Epic 7: resolveChildren 결과(unknown/disallowed/추가 warnings)를 누적할 ctx 초기화.
+        // ctx 는 children 처리 전체에서 공유되어 silent drop 차단 + composition 제약 검증을 수행한다.
+        const renderCtx = {
+            bundle,
+            iconBundle,
+            componentMap,
+            reactRuntime,
+            warnings: [],
+            unknownChildren: [],
+            disallowedChildren: [],
+            parentKey: exportName, // 최상위 부모 키 (compound parent lookup 시작점)
+            path: normalized,
+        };
+        if (resolvedProps.children !== undefined || componentData.props) {
+            if (resolvedProps.children !== undefined) {
+                resolvedProps.children = resolveChildren(resolvedProps.children, renderCtx, 0);
+            }
+            // children 이외의 ReactNode prop 들 — propsSpec.type === 'ReactNode' 인 키 전부 처리
+            if (componentData.props) {
+                for (const [key, spec] of Object.entries(componentData.props)) {
+                    if (key === 'children')
+                        continue; // 위에서 처리됨
+                    if (spec.type !== 'ReactNode')
+                        continue;
+                    const val = resolvedProps[key];
+                    if (val === undefined || val === null)
+                        continue;
+                    // string / number / boolean primitive 는 React 가 직접 렌더 — 건드리지 않음
+                    if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean')
+                        continue;
+                    // component descriptor 또는 그 배열인 경우만 resolve
+                    resolvedProps[key] = resolveChildren(val, renderCtx, 0);
+                }
+            }
+        }
+        // HTML 출력: CDN-input은 init script, 그 외는 React 정적 HTML (renderToStaticMarkup은 필요할 때만 호출)
+        const cdnInitScript = isCdnInput && jsApi?.cdnPattern
+            ? buildCdnInitScript(jsApi.cdnPattern, normalized, instanceId, jsApi.className, removeBlockedProps(mergedCdnProps))
+            : null;
+        const html = cdnInitScript !== null
+            ? cdnInitScript
+            : `<!-- ncua:${normalized} start -->\n${reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps))}\n<!-- ncua:${normalized} end -->`;
+        // Story 5.1-8: jsRequired 컴포넌트는 React data 의 default 무시 (vanilla 정의에 없는 React-only default 누수 차단).
+        // React 컴포넌트는 기존 동작 유지.
+        const isJsRequired = componentData.jsRequired === true;
+        const hasDefaults = !isJsRequired && componentData.props ? calcDefaultsUsed(componentData.props, corrected) : {};
+        // Story 5.9: cdnDefaults 적용된 키도 defaultsUsed 에 노출 (에이전트 학습용)
+        const cdnDefaultsApplied = isCdnInput && jsApi?.cdnDefaults
+            ? Object.fromEntries(cdnMergeResult.defaultsApplied.map((key) => [key, jsApi.cdnDefaults?.[key]]))
+            : {};
+        const finalDefaultsUsed = { ...hasDefaults, ...cdnDefaultsApplied };
+        // Epic 7: prop warnings + children resolve warnings 통합
+        const allWarnings = [...warnings, ...renderCtx.warnings];
         return (0, response_js_1.successResponse)({
             html,
             component: normalized,
             exportName,
             importPath: componentData.importPath,
-            appliedProps: userProps,
-            ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
-            js: componentData.jsRequired
-                ? { required: true, description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다' }
-                : { required: false },
+            appliedProps: corrected,
+            ...(Object.keys(finalDefaultsUsed).length > 0 && { defaultsUsed: finalDefaultsUsed }),
+            ...(allWarnings.length > 0 && { warnings: allWarnings }),
+            ...(renderCtx.unknownChildren.length > 0 && { unknownChildren: renderCtx.unknownChildren }),
+            ...(renderCtx.disallowedChildren.length > 0 && { disallowedChildren: renderCtx.disallowedChildren }),
+            js: (0, exports.buildJsField)(componentData, jsApiMap),
             cdn: cdnMeta ?? undefined,
-            dataVersion,
-            react,
+            dataVersion: buildDataVersion(cdnMeta, iconMeta),
+            react: buildReactOutput(componentData, corrected, iconMeta, componentMap),
         });
     }
     catch (err) {
-        return (0, response_js_1.errorResponse)('RENDER_FAILED', `'${normalized}' 렌더링 실패: ${(0, response_js_1.toErrorMessage)(err)}`, '사용 가능한 속성을 확인하려면 get_component_props를 사용하세요.');
+        const catchWarnings = componentData.props ? validateProps(props ?? {}, componentData.props) : [];
+        const suggestion = componentData.usageExamples
+            ? 'get_component_props로 usageExamples를 확인하고 해당 props로 재시도하세요.'
+            : '사용 가능한 속성을 확인하려면 get_component_props를 사용하세요.';
+        return (0, response_js_1.errorResponse)('RENDER_FAILED', `'${normalized}' 렌더링 실패: ${(0, response_js_1.toErrorMessage)(err)}`, suggestion, catchWarnings.length > 0 ? catchWarnings : undefined);
     }
 };
 exports.renderToHtml = renderToHtml;