08 - JSX 컴포넌트

JSX 컴포넌트는 채팅 중 에이전트의 답변 안에 함께 표시할 수 있는 시각적 블록입니다. 글로만 상황을 설명하는 대신, 아래와 같은 정보를 깔끔한 UI로 전달할 수 있습니다.

• 현재 장소, 시간, 캐릭터 의상

• 호감도, 속마음, 능력치

• 추천 선택지, 인물 관계도

주의: 컴포넌트를 등록했다고 해서 채팅창에 자동으로 나타나지는 않습니다. 컴포넌트를 만든 뒤에는 상세 프롬프트나 시작 설정에 "언제, 어떤 형태로 이 컴포넌트를 출력할지" 에이전트에게 지침을 주어야 합니다.

토큰 팁: JSX 코드가 아무리 길어도 걱정하지 마세요! 컴포넌트 코드는 서버에 저장되어 브라우저가 직접 출력하므로 입력 토큰(사용량)에 영향을 주지 않습니다. AI에게는 컴포넌트를 '언제 출력할지'에 대한 호출 조건만 프롬프트 토큰에 영향을 줍니다.

예시:

이런 식의 태그를 캐릭터가 답변에 포함하면, 실제 채팅 화면에서는 코드가 아니라 실제 UI로 렌더링됩니다.

• 상태창, 추천답변, 관계도, 메시지형/이미지 피드형 UI, RPG 상태창 추가

• 직접 만든 커스텀 UI 컴포넌트 관리 및 미리보기 확인

• 컴포넌트 개수: 최대 20개

• 컴포넌트 이름: 최대 30자 (영어, 숫자, 한글, -, _ 사용 가능)

• 컴포넌트 코드: 최대 1,000,000자

• 저장 전 체크 항목: 이름/코드 누락, 잘못된 이름, JSX 문법 오류

참고: 외부 라이브러리, fetch 같은 네트워크 요청, localStorage 같은 브라우저 저장소 기능은 보안 및 안정성을 위해 사용할 수 없습니다.

캡션: JSX 컴포넌트 탭에서는 작품에 사용할 커스텀 UI를 만들고 미리보기로 확인할 수 있습니다.

우마이의 JSX는 React 문법을 그대로 사용합니다. 아래 기능이 지원됩니다.

• JSX 문법 전반: Fragment(<>…</>), 조건부 렌더(&&, 삼항 연산자), 배열 map 반복

• React Hooks를 네임스페이스 없이 바로 호출: useState, useEffect, useRef, useMemo 등 (import React 불필요)

• Tailwind 유틸리티 클래스와 dark: 변형, 인라인 style, 클릭 등 이벤트 핸들러

• lucide-react 아이콘과 TypeScript 타입 어노테이션

• 외부 글꼴: <style> 안의 @import url('...') 방식만 가능 (<link> 태그는 차단)

컴포넌트 안에서 아래 함수와 표기를 쓰면 채팅과 상호작용할 수 있습니다.

sendMessage와 showNotification은 미리보기에서는 토스트(상단 알림 메시지)로만 표시되고, 실제 동작은 채팅에서 확인할 수 있습니다.

컴포넌트는 격리된 샌드박스에서 실행되므로 아래는 사용할 수 없습니다.

• 외부 라이브러리 import 불가 — react와 lucide-react만 허용 (axios, lodash 등 )

• fetch, XMLHttpRequest, WebSocket 등 외부 통신 불가

• localStorage, 쿠키, 부모 페이지 접근 불가

• eval, new Function, <script>, <iframe>은 실행되지 않음

• 태그 중첩 깊이는 10단계까지만 렌더링됩니다

빈 컴포넌트를 직접 만들기보다 제공되는 템플릿을 먼저 사용해 보세요. 고르면 이름과 코드가 자동으로 채워집니다.

• 스테이터스 창: 장소, 시간, 의상, 호감도 등을 보여주는 상태창

• 이모지 추천답변: 유저가 고를 수 있는 선택지를 이모지와 함께 표시

• 관계도: 캐릭터 간 호감도나 관계를 게이지로 시각화

• 메시지 / 이미지 피드: 메신저 대화방이나 SNS 피드 스타일의 UI

• RPG 상태창: HP, 레벨, 능력치 같은 정보를 게임 UI처럼 표시

1. 템플릿 선택: 목적에 가장 가까운 템플릿을 고릅니다.

2. 미리보기 확인: 기본 상태로 어떻게 화면에 보이는지 먼저 확인합니다.

3. 컴포넌트 이름 확인: Status처럼 대문자로 시작하는 이름을 확인합니다.

4. 미리보기 코드 수정: 값을 조금씩 바꿔보며 UI가 어떻게 변하는지 익힙니다.

5. 상세 프롬프트에 규칙 작성: 캐릭터가 언제 이 컴포넌트를 출력해야 하는지 적어줍니다.

6. 테스트 채팅: 실제 대화에서 의도대로 UI가 출력되는지 확인합니다.

문의가 가장 많은 부분입니다. JSX 컴포넌트는 "화면에 보여줄 수 있는 도구"이고, 상세 프롬프트는 "언제 그 도구를 쓸지 알려주는 지시문"입니다. 컴포넌트만 만들어 두면 AI는 언제 불러야 할지 모르기 때문에 아무것도 출력하지 않습니다.

출력 위치(대화 맨 위 / 맨 아래)나 타이밍도 지침으로 지정할 수 있습니다.

에이전트 입력창에서 @를 눌러 만든 JSX 컴포넌트를 첨부한 뒤 이렇게 물어보세요.

• "이 컴포넌트를 호감도가 크게 변할 때 출력되게 하려면 프롬프트에 뭐라고 적어야 해?"

• "이 상태창을 쓰기 위한 상세 프롬프트 문구도 같이 써줘"

• "모바일에서 너무 길어 보이지 않게 UI를 단순화해줘"

미리보기 코드는 컴포넌트를 실제로 호출해 보는 연습 공간입니다.

• 숫자는 {23}처럼 중괄호로, 문장은 "카페"처럼 따옴표로 감쌉니다. 미리보기에서 원하는 모양이 나오면, 같은 형태를 상세 프롬프트의 예시로 적어 두세요.

캡션: 왼쪽 미리보기 코드에 컴포넌트 호출을 적으면 오른쪽에 실제 렌더링 결과가 표시됩니다.

코드를 직접 수정하기 어렵다면 우측 패널의 에이전트에게 도움을 요청해 보세요.

• "호감도와 장소를 보여주는 상태창 JSX를 만들어줘"

• "이 컴포넌트를 모바일 화면에 보기 좋게 단순화해줘"

• "이 상태창을 쓰기 위한 상세 프롬프트 문구도 같이 짜줘"

Tip: 이미 만든 컴포넌트가 있다면 입력창에 @ 멘션으로 해당 JSX 컴포넌트를 첨부하고 질문하면 훨씬 정확한 코드를 얻을 수 있습니다.

오류가 있으면 임시저장이 실패할 수 있으니 저장 전 아래 항목을 체크해 주세요.

• 컴포넌트 이름과 코드가 비어 있지 않은지

• 이름이 대문자로 시작하고, 사용할 수 없는 문자가 없는지

• 태그 쌍(<div></div>)과 괄호·따옴표가 맞는지

• 같은 이름의 컴포넌트를 여러 개 만들지 않았는지

• 미리보기에 오류 표시가 뜨지 않는지

Q. 컴포넌트를 만들었는데 채팅에 안 나와요.

• 등록만으로는 자동 출력되지 않습니다. 상세 프롬프트에 구체적인 출력 타이밍과 규칙을 적어주세요.

• 어려우시다면, 에이전트에서 JSX 컴포넌트를 첨부(@ + 컴포넌트 선택)하고 "이 컴포넌트 ~때 출력되게 하려면 어떻게 적으면 돼?"라고 물어보세요!

Q. 모델을 바꿨더니 상태창이 안 나오거나 중간에 깨져요.

• JSX 태그는 형식이 정확해야 렌더링되기 때문에, 구조화된 출력에 약한 모델에서는 태그가 깨지거나 누락될 수 있습니다.

• 상태창·관계도처럼 구조가 복잡한 컴포넌트를 쓰신다면 Gemini 3.1 Pro, Claude(Opus) 계열 등 상위 모델을 권장합니다. 경량 모델일수록 태그를 생략하거나 형식을 어기는 빈도가 높습니다.

Q. 컴포넌트가 잘려 보여요.

• 컴포넌트에는 최대 높이 상한이 있어, 내용이 매우 길면 아래쪽이 잘릴 수 있습니다. 접기(토글) 구조로 나누거나 표시 항목을 줄여 주세요.

Q. 화면이 멈춰요.

• 컴포넌트 안에 무한 루프가 있으면 일정 시간 뒤 실행이 중단됩니다. useEffect 안에서 상태를 계속 바꾸고 있지 않은지 확인해 주세요.

Q. JSX 컴포넌트를 쓰면 대화 사용량(입력 토큰)이 늘어나나요?

• 컴포넌트 안의 디자인·UI 코드는 AI에게 전달되지 않고 브라우저가 직접 그려주기 때문에 사용량이 늘지 않습니다.

• AI에는 상세 프롬프트에 적어둔 '호출 조건'만 일반 텍스트로 전달되므로, 코드 길와 관계없이 호출 조건의 작성 분량에만 영향을 받습니다. 코드 길이 부담 없이 규칙을 명확히 작성해 주세요.

Q. JSX를 에이전트에게 평가받고 싶어요.

• 에이전트 입력창의 @ 멘션으로 컴포넌트를 첨부하면 가장 정확합니다. 코드가 매우 길 경우 응답이 느리거나 인식이 어려울 수 있으니, 이럴 때는 컴포넌트를 기능 단위로 나누거나 아래 JSX 도우미 GEMS를 이용해 주세요.

Q. 이미지와 상태창이 항상 붙어서 나와요.

이미지 태그({{이미지코드}})와 컴포넌트 태그의 출력 위치는 상세 프롬프트의 지침을 따릅니다. 순서를 정하고 싶다면 아래처럼 명시해 주세요.

한 번 잘못된 형식으로 출력되면 다음 턴에도 그 형식을 따라가는 경향이 있습니다. 이 경우 해당 메시지를 직접 수정해 형식을 바로잡아 주시면 이후 응답이 안정됩니다.

Q. 다른 플랫폼에서 만든 JSX를 그대로 가져왔는데 렌더링이 안 돼요.

• 이식 전 아래 3가지를 먼저 제거·수정해 주세요.

  1. 외부 라이브러리 import (react, lucide-react 외 전부)

  2. fetch 등 네트워크 호출, localStorage 접근

  3. <script>, <iframe>, eval

Q. 다른 사람이 만든 작품에 내 JSX를 적용할 수 있나요?

• 현재는 지원하지 않습니다. JSX 컴포넌트는 작품 제작자가 해당 작품에 등록한 것만 동작합니다.

Q. 미리보기 코드의 '복사' 버튼이 동작하지 않아요.

회색 예시(플레이스홀더) 상태에서는 복사되지 않습니다. 미리보기 코드를 직접 입력한 뒤 복사해 주세요.

• JSX 고급 가이드: https://uummai.notion.site/jsx-guide

• 우마이 JSX 컴포넌트 도우미 GEMS: https://gemini.google.com/gem/1Vd4GxUKKGe7uw4SJgKLP9nJ5wcMczG_0

두 링크는 제작 화면의 JSX 가이드 패널 하단에서도 바로 열 수 있습니다.