thesysdev/openui 딥다이브
— "LLM이 UI를 직접 그리는" 스트리밍 전용 언어와 렌더러

1한 줄 정체

OpenUI를 한 줄로 정의하면 이렇다. "내가 미리 정의해둔 React(또는 Vue·Svelte) 컴포넌트 목록을, LLM이 OpenUI Lang이라는 압축 언어로 호출하게 만들고, 그 호출을 실시간으로 파싱해 화면에 그려주는 프레임워크." 단순히 "AI가 만든 컴포넌트 모음집"이 아니라, 언어 설계 + 파서 + 런타임 평가기 + 프레임워크별 렌더러를 자체 구현한 하나의 작은 프로그래밍 언어 생태계에 가깝다.

가장 헷갈리기 쉬운 지점부터 짚자면, OpenUI는 "AI 코드 생성 도구"가 아니다. 임의의 HTML/JSX를 즉석에서 만들어내는 게 아니라, 개발자가 defineComponent()로 미리 등록해둔 제한된 컴포넌트 집합 안에서만 LLM이 조립하도록 강제한다. 이 "울타리 쳐진 창의성(bounded generation)"이 이 프로젝트 설계의 핵심 축이다.

2왜 지금 뜨는가

① "제너러티브 UI(Generative UI)"라는 장르 자체가 막 커지는 시점

챗봇이 텍스트만 출력하던 시절을 지나, 이제는 차트·표·폼처럼 실제로 조작 가능한 UI를 LLM이 직접 그리게 하는 흐름이 Vercel의 AI SDK, Google의 A2UI, CopilotKit 등 여러 진영에서 동시에 나타나고 있다. OpenUI는 이 경쟁에서 "프레임워크(React/Vue/Svelte 전부 지원) + 토큰 효율(자체 언어)"이라는 두 축을 함께 파는 포지션을 잡았다.

② JSON 기반 방식의 "토큰 비용" 문제를 정면으로 겨냥

기존 제너러티브 UI 도구 대부분은 LLM에게 JSON으로 UI 트리를 출력하게 한다. JSON은 사람이 읽기엔 좋지만, 중괄호·따옴표·반복되는 키 이름 때문에 토큰(모델이 텍스트를 처리하는 단위)을 많이 잡아먹는다. README에 실린 벤치마크(tiktoken GPT-5 인코더, 7가지 UI 시나리오 합산)에서 OpenUI Lang은 총 4,800토큰인 반면 Vercel의 JSON 렌더 방식은 10,180토큰, Thesys 자체의 구 JSON 포맷(C1 JSON)은 9,948토큰이 필요했다 — 각각 52.8%, 51.7% 절감이다. 토큰이 줄면 스트리밍 지연(latency)도 그만큼 짧아진다.

③ "한 벌의 코어, 세 개의 프레임워크" 확장 전략

React가 메인이지만, @openuidev/vue-lang(Vue 3)과 @openuidev/svelte-lang(Svelte 5)이 같은 @openuidev/lang-core 위에서 동작한다. 여기에 빌드 도구 없이 <script> 태그 하나로 붙일 수 있는 @openuidev/browser-bundle까지 있어, "React 앱에만 종속되지 않는다"는 점이 채택 장벽을 낮춘다.

3무엇을 해결하나

LLM이 UI를 직접 만들게 하려는 모든 시도는 결국 같은 벽에 부딪힌다. 모델은 텍스트를 "예측"할 뿐이지, 문법적으로 완벽한 구조를 "보장"하지 않는다. 스트리밍 중간에 잘린 문장, 존재하지 않는 컴포넌트 이름, 타입이 안 맞는 값이 실시간으로 쏟아질 수 있다. OpenUI가 실제로 푸는 문제는 세 가지로 요약된다.

4전체 구조

공식 문서(docs/content/docs/openui-lang/overview.mdx)는 OpenUI를 "네 가지 핵심 블록"이라 설명하지만, 실제 코드를 따라가면 런타임 평가 단계가 파서와 렌더러 사이에 별도로 존재해 사실상 5단이다. 이 저장소가 무엇을 "직접 구현"하는지 감을 잡으려면 이 파이프라인을 먼저 그려보는 게 가장 빠르다.

이 구조가 주는 교훈은 "프레임워크(React/Vue/Svelte)에 종속된 로직은 최대한 얇게, 언어·파서·평가는 프레임워크 무관 코어에"라는 분리다. @openuidev/lang-core에는 React import가 단 한 줄도 없다. 이 덕분에 같은 파서·평가 로직을 세 프레임워크가 그대로 재사용할 수 있다.

5핵심 설계 · 동작 원리

이 섹션이 이 문서에서 가장 중요하다. OpenUI의 진짜 값어치는 README의 "67% 절감" 숫자가 아니라, 그 숫자를 가능하게 만드는 네 가지 구체적인 설계 결정에 있다. 실제 소스 경로와 함수명을 인용하며 하나씩 뜯어본다.

설계 ① — Zod 스키마 한 번 쓰면, 컴포넌트 문서·타입·검증이 전부 자동 생성

개발자는 packages/lang-core/src/library.ts의 defineComponent()에 이름·설명·Zod 4 스키마·렌더러만 넘긴다. 여기서 흥미로운 함정 방지 코드가 있다 — assertV4Schema()가 Zod 3 스키마를 감지하면 "OpenUI requires Zod 4 schemas"라는 에러를 즉시 던진다. Zod 3과 4는 내부 구조(_def vs _zod)가 달라, 잘못된 버전을 쓰면 조용히 깨지는 대신 여기서 바로 걸러낸다.

그 다음 buildSignature()가 Zod 스키마의 필드 타입을 재귀적으로 순회해 "Card(children: Component[], title?: string)" 같은 사람이 읽는 함수 시그니처 문자열로 바꾼다. 이 문자열이 그대로 시스템 프롬프트에 박혀 LLM에게 "이 컴포넌트는 이런 인자를 받는다"고 알려준다 — 별도의 문서를 손으로 쓸 필요가 없다는 뜻이다. 실제로 예제 앱이 생성한 examples/openui-chat/src/generated/system-prompt.txt를 열어보면 BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", ...)처럼 이 자동 생성 시그니처들이 그대로 나열돼 있다.

설계 ② — OpenUI Lang: "따옴표·중괄호를 줄인" 위치 기반 대입문 언어

실제 문법은 이렇다. 한 줄에 하나씩 식별자 = 표현식 형태로 값을 선언하고, root라는 특별한 식별자가 최종 렌더링 대상이 된다. 컴포넌트 호출은 TypeName(인자1, 인자2, ...)처럼 키워드 인자가 아닌 위치 인자로만 쓴다 — 실제로 시스템 프롬프트에는 "Write Stack([children], "row", "l") NOT Stack([children], direction: "row", gap: "l") — colon syntax is NOT supported and silently breaks"라는 경고가 명시돼 있다. 콜론 문법을 쓰면 "에러가 나는 게 아니라 조용히 깨진다"는 게 실전에서 중요한 함정이다.

# 실제 examples/openui-chat 생성 프롬프트에서 발췌한 예시 문법
header = CardHeader("월간 매출 요약")
chart = BarChart(["1월","2월","3월"], [Series("매출", [120, 150, 90])])
root = Card([header, chart])

또한 모든 변수는 부모에서 참조돼야만 렌더링된다(시스템 프롬프트 원문: "EVERY variable... MUST be referenced by at least one other variable. Unreferenced variables are silently dropped"). 이는 스트리밍 도중 어떤 문장이 아직 "고아 상태"(어디에도 안 붙은 상태)인지를 파서가 orphaned 필드로 추적하는 이유이기도 하다.

설계 ③ — 스트리밍 파서: "닫히지 않은 문장"을 스스로 임시로 닫아 계속 그린다

parser/statements.ts의 autoClose()와 split()은 아직 도착하지 않은 나머지 텍스트를 기다리지 않고, 지금까지 온 텍스트만으로 최선의 파싱 결과를 만들어낸다. parser/parser.ts의 classifyStatement()는 각 문장을 state($변수 선언) · query(Query(...) 호출) · mutation(Mutation(...) 호출) · value(일반 값)로 분류하는데, 특히 $foo = Query(...)처럼 겉보기엔 상태 선언인데 실제로는 쿼리인 경우를 Query 호출 여부부터 먼저 검사해 올바르게 분류한다 — 코드 주석에도 "check BEFORE $var to handle `$foo = Query(...)` correctly"라고 명시돼 있다.

파싱 결과에는 언제나 meta.incomplete(아직 스트림이 끝나지 않았다는 표시), meta.unresolved(아직 값이 안 채워진 참조), meta.orphaned(부모에 연결되지 않은 문장)이 함께 따라온다. 렌더러는 이 메타데이터를 보고 "지금 완성된 부분까지만" 그린다.

설계 ④ — Query()/Mutation(): LLM이 실제 데이터·도구를 부르는 통로 (MCP와도 연결)

단순히 정적인 UI만 그리는 게 아니라, LLM이 Query(도구이름, 인자, 기본값, 새로고침조건) 형태로 실제 백엔드 함수나 MCP(Model Context Protocol) 도구를 호출하게 할 수 있다. runtime/queryManager.ts의 createQueryManager()가 이 호출을 관리하고, runtime/mcp.ts는 MCP 클라이언트의 응답 포맷(callTool 결과)을 OpenUI가 이해하는 값으로 변환하는 extractToolResult()를 제공한다. React 쪽에서는 Renderer의 toolProvider prop이 "함수 맵" 또는 "MCP 클라이언트" 둘 중 하나를 그대로 받아들이도록 설계돼, OpenUI 자체가 MCP 표준을 흉내내지 않고 그 위에 얹힌다.

설계 ⑤ — 렌더러: "직전까지 성공한 화면"을 절대 지우지 않는 에러 바운더리

react-lang/src/Renderer.tsx의 ElementErrorBoundary는 일반적인 React 에러 바운더리와 다르게 동작한다. 에러가 나면 그냥 대체 UI를 보여주는 게 아니라, componentDidUpdate()에서 매번 this.lastValidChildren = this.props.children으로 마지막 정상 렌더링을 계속 저장해뒀다가, 에러 상태(hasError)일 땐 그 저장본을 그대로 반환한다. 코드 주석 그대로 옮기면: "이 '마지막으로 성공한 상태 보여주기' 동작은 스트리밍 중이나 일시적 평가 오류 중에 UI가 하얗게 비는 것을 막아준다." 스트리밍 특유의 "아직 다 안 왔는데 지금 이 순간엔 문법이 깨져 보이는" 상태를 사용자에게 노출하지 않는 실전적인 해법이다.

6기술 스택 · 의존성

루트 package.json의 이름은 "OpenUI", 버전은 "1.0.1"로 적혀 있지만 이 값은 배포되는 실제 패키지와 무관한 장식용 필드다. 실제로 npm에 올라가는 것은 packages/* 아래 11개 패키지이며, 각자 독립적으로 버전이 매겨진다. 즉 이 프로젝트의 "버전 진실원"은 루트가 아니라 각 패키지 폴더의 package.json이다.

버전 관리에는 흔한 changesets 도구(.changeset/ 폴더)가 보이지 않는다 — 즉 각 패키지 버전은 자동화된 릴리스 도구 없이 수동으로 관리되는 것으로 보인다. 공통 의존성은 pnpm-workspace.yaml의 catalog: 블록에 모아 버전 드리프트를 막는다. 핵심 값만 추리면:

7설치 · 요구사항

8실제 사용 흐름

9함정 · 오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

OpenUI는 "챗봇에 카드·차트·폼처럼 진짜 조작 가능한 UI를 붙이고 싶은데, JSON 방식의 토큰 비용과 스트리밍 어색함이 싫다"는 구체적인 니즈를 겨냥한 프레임워크다. 실제 코드를 뜯어보면 마케팅 문구("67% 토큰 절감")보다 더 인상적인 건, Zod 스키마 하나로 문서·타입·검증을 자동 생성하는 라이브러리 계층과 스트리밍 중 미완성 상태를 명시적으로 다루는 파서, 그리고 에러가 나도 화면을 지우지 않는 렌더러다.

12직접 해볼 수 있는 실습 과제

완성된 채팅 앱부터 실행하면 모델 응답과 화면 처리 중 어디서 문제가 생겼는지 구분하기 어렵다. 먼저 고정된 OpenUI Lang 문자열과 가짜 도구로 각 단계를 따로 확인해 보자. 아래 경로와 명령은 확인한 로컬 소스 기준이며, 의존성과 워크스페이스 패키지 빌드가 준비된 학습용 사본의 레포 루트에서 실행한다. Node와 pnpm 설정은 해당 사본의 package.json과 pnpm-workspace.yaml을 먼저 확인한다.

테스트 추가와 변경은 학습용 사본에서 진행한다. 다음 환경 변수는 코어 패키지의 원격 측정을 끄는 설정이며, 아래 과제는 API 키나 실제 모델 호출을 사용하지 않는다.

export OPENUI_TELEMETRY_DISABLED=1

it("나중에 도착한 제목을 연결한다", () => {
  const stream = createStreamParser(schema);
  const first = stream.push("root = Stack([heading])\n");
  expect(first.meta.unresolved).toContain("heading");

  const last = stream.push('heading = Title("학습 기록")\n', true);
  expect(last.meta.unresolved).toEqual([]);
  expect(last.root?.props.children).toMatchObject([
    { typeName: "Title", props: { text: "학습 기록" } },
  ]);
});

pnpm --filter @openuidev/lang-core run test src/parser/__tests__/parser.test.ts

it("지표의 설명과 파싱 결과를 함께 확인한다", () => {
  const Metric = defineComponent({
    name: "Metric",
    description: "이름과 숫자를 보여주는 지표",
    props: z.object({ label: z.string(), value: z.number() }),
    component: () => null,
  });
  const library = createLibrary({ components: [Metric], root: "Metric" });

  expect(library.prompt()).toContain("Metric(label: string, value: number)");
  const parser = createParser(library.toJSONSchema(), library.root);
  const result = parser.parse('root = Metric("매출", 120)');
  expect(result.meta.errors).toEqual([]);
  expect(result.root?.props.value).toBe(120);
});

pnpm --filter @openuidev/lang-core run test src/__tests__/library.test.ts

component: ({ props }) => (
  <p>{props.label}: {props.value}</p>
)

pnpm --filter @openuidev/react-lang run test src/Renderer.test.tsx

pnpm --filter @openuidev/lang-core run test src/runtime/__tests__/queryManager.test.ts

13관련 기술 심화 학습 로드맵

매주 코드를 읽고 작은 결과물을 하나 남긴다. 다음 단계로 넘어갈 때는 함수 이름을 외우기보다 어떤 입력이 들어와 어떤 결과로 바뀌는지를 설명해 보자. 아래 파일 경로는 모두 레포 루트 기준이다.

마지막 주의 예제는 소스 추적 자료로 사용한다. 먼저 가짜 도구 테스트로 실행 흐름을 이해하고, 예제의 서버 경로에서는 외부 모델 호출이 어느 지점에 놓이는지만 확인하면 된다.

14핵심 키워드 사전