DavidHDev/canvas-ui 딥다이브
— 당신의 진짜 DOM을 불·물·유리로 왜곡하는 프레임워크 무관 캔버스 UI 라이브러리

1프로젝트 한 줄 요약

웹에서 "멋진 비주얼 이펙트"를 넣는 흔한 방법은 이렇다. 페이지 맨 위에 투명한 <canvas>를 한 장 덮고, 그 위에 WebGL로 파티클이나 물결을 그린다. 문제는 이 캔버스가 아래에 뭐가 있는지 전혀 모른다는 것이다. 파티클은 당신의 제목 글자를 피해 가지도, 굴절시키지도 못한다. 그냥 무관한 장식이 위에 떠 있을 뿐이다. 게다가 오버레이가 클릭을 가로채지 않도록 pointer-events:none을 걸어야 해서, 이펙트와 콘텐츠는 완전히 남남이다.

Canvas UI가 하는 일은 명확하다. 실험적 브라우저 기능인 html-in-canvas로 당신의 살아있는 DOM을 매 프레임 비트맵으로 굽고 → 그 비트맵을 GPU 텍스처로 업로드하고 → 프래그먼트 셰이더(GLSL)로 그 텍스처를 왜곡·변형해 → 결과를 출력 캔버스에 그린다. 그 결과가 원본 DOM 위에 정렬돼 얹히므로, 사용자 눈에는 "페이지가 불타고, 얼고, 물결치고, 산산조각 나는" 것처럼 보이지만 실제 상호작용은 그대로 살아있다.

이름은 canvas-ui지만, 진짜 핵심어는 "live DOM as texture(살아있는 DOM을 텍스처로)"다. 스크린샷을 찍어 얹는 것도, 페이지를 통째로 <canvas>로 다시 그리는 것도 아니다. 여전히 진짜 DOM이 살아 숨 쉬는 채로 그 위를 GPU가 실시간으로 굴절시킨다는 점이 이 도구의 정체성이자, 이 문서에서 배울 것을 관통하는 열쇠다.

2왜 주목받는가

2026년 웹 프론트엔드에는 세 가지 큰 흐름이 있다. ① 크롬이 밀고 있는 html-in-canvas라는 완전히 새로운 그래픽 API, ② shadcn/ui가 대중화한 "설치하지 말고 소스를 복사해 써라"는 배포 방식, ③ AI 코딩 에이전트가 컴포넌트를 자동 설치하는 MCP 워크플로. Canvas UI가 트렌딩에 오른 이유는 이 세 물결이 정확히 겹치는 지점에 서 있기 때문이다. 하나만 잘해도 화제가 될 텐데, 셋을 한 번에 묶었다.

차별점 ① — html-in-canvas 위에 세운 "첫 진지한 컴포넌트 라이브러리"

대부분의 캔버스 이펙트는 페이지와 단절된 오버레이다. Canvas UI의 급소는 이펙트가 당신의 실제 DOM을 읽어(read) 다시 그린다(redraw)는 것이다. 텍스트는 선택 가능한 채로, 링크는 클릭 가능한 채로 남고, 페이지 전체가 하나의 텍스처가 돼 불·물·유리가 실시간으로 왜곡한다. 이건 이론이 아니라 크롬의 신기능을 실제 프로덕션급 라이브러리로 증명한 첫 사례에 가깝고, 그래서 "이게 진짜 되네?"라는 반응이 트렌딩을 만든다.

차별점 ② — "설치하지 말고 복사하라" (shadcn 레지스트리 + MCP)

Canvas UI는 npm 패키지가 아니다. shadcn 호환 레지스트리로 배포돼, npx shadcn@latest add @canvas-ui/liquid-react 한 줄이면 컴포넌트 소스 파일이 당신 프로젝트의 components/canvasui/에 직접 떨어진다. 블랙박스 의존성이 아니라 당신이 열어보고 고칠 수 있는 코드가 손에 들어온다. 게다가 shadcn MCP 서버를 이 레지스트리에 연결하면 "내 히어로 섹션에 liquid 넣어줘"라고 AI에게 말하는 것만으로 설치된다.

차별점 ③ — 하나의 엔진에서 6개 프레임워크가 나온다

이런 이펙트 라이브러리는 대개 React 전용이다. Canvas UI는 25개 컴포넌트 각각을 React · Solid · Preact · Vue · Svelte · 바닐라 JS 여섯 가지 맛으로 제공한다(25 × 6 = 150 레지스트리 아이템). 비결은 뒤에서 자세히 뜯어볼 "프레임워크 무관 엔진 하나 + 얇은 래퍼 여섯" 구조다. 어떤 스택을 쓰든 같은 이펙트를 붙일 수 있다는 건, 채택 장벽을 극적으로 낮춘다.

차별점 ④ — 어디서나 깨지지 않는다 (우아한 폴백)

html-in-canvas는 아직 Chrome/Edge 140+에서 플래그를 켜야 하는 실험 기능이다. 그럼 사파리·파이어폭스 사용자는? Canvas UI는 지원 여부를 런타임에 감지해, 지원되면 살아있는 DOM 텍스처 모드로, 안 되면 순수 WebGL 오버레이 모드로 자동 전환한다. 에러 없이, 모든 방문자가 작동하는 페이지를 본다. "최신 기능을 쓰되 아무도 배제하지 않는" 프로그레시브 인핸스먼트의 교과서적 사례다.

3기술 스택 전체 지도

Canvas UI 저장소를 처음 열면 헷갈린다. 이펙트 라이브러리인가, Next.js 웹사이트인가? 답은 "둘 다이되 역할이 다르다"이다. 이 저장소는 하나의 리포에 (A) 배포할 컴포넌트 라이브러리, (B) 그것을 소개하는 문서·마케팅 사이트, (C) 둘을 잇는 레지스트리 빌드 스크립트가 함께 산다. 이 셋을 구분하는 순간 전체 그림이 선명해진다.

세계 A — 컴포넌트 라이브러리 (src/lib/)

진짜 상품이다. 25개 컴포넌트가 각각 폴더 하나로 들어 있고, 렌더링 전략이 두 갈래로 나뉜다. 이 구분을 반드시 기억해야 한다 — "전부 three.js"라고 오해하기 쉽지만 아니다.

세계 B — 문서·마케팅 사이트 (src/app/)

라이브러리를 보여주기 위한 canvasui.dev 사이트 그 자체다. 라이브러리 코드와 섞이지 않도록 src/components/(사이트 UI)와 src/lib/(배포 라이브러리)를 철저히 분리해 둔 게 인상적이다.

세계 C — 배포 파이프라인 (scripts/build-registry.mts)

이 저장소의 숨은 주인공. npm run dev는 먼저 registry 스크립트를 돌려 150개 레지스트리 JSON을 public/r/에 생성한 뒤 Next를 띄운다. 이 스크립트가 node --experimental-strip-types로 컴파일 없이 TS를 그대로 실행한다는 점(별도 빌드 툴 없음)도, 그리고 뒤에서 볼 makeStandalone()이라는 "엔진을 래퍼에 인라인해 단일 파일로 합치는" 변환도 전부 여기서 일어난다.

4아키텍처 심화 분석

Canvas UI의 모든 것은 하나의 설계 결정에서 나온다: 렌더링 로직(엔진)은 프레임워크와 완전히 무관한 순수 DOM+WebGL 코드로 짜고, React/Vue/Svelte 같은 프레임워크 래퍼는 최대한 얇게 유지한다. 기여 가이드(CONTRIBUTING.md)가 이걸 못박아 둔다 — "바닐라 엔진이 모든 렌더링 로직을 소유한다. 프레임워크 래퍼는 얇게 유지하라. 모든 컴포넌트는 html-in-canvas(라이브 DOM 텍스처)와 순수 WebGL 오버레이 폴백 양쪽 모두에서 동작해야 한다."

4-1. 파일 6개의 정체 — 폴더 하나를 열어보면

src/lib/ 아래 25개 폴더는 각각 정확히 6개 파일을 담는다. 하나의 엔진과, 그 엔진을 각 프레임워크로 감싼 얇은 래퍼 다섯이다.

4-2. 엔진의 공개 API — 팩토리 하나, 인스턴스 셋

모든 엔진은 똑같은 모양을 갖는다: 지원 여부를 확인하는 supports…() 프로브, 요소들과 옵션을 받아 이펙트를 켜는 create…(elements, options) 팩토리, 그리고 팩토리가 돌려주는 인스턴스가 노출하는 세 개의 손잡이 — setOptions(실시간 옵션 변경)·resize·destroy.

// LiquidVanilla.ts 류의 엔진이 공통으로 노출하는 인터페이스
export interface AsciifyInstance {
  setOptions: (options: AsciifyOptions) => void;  // 옵션을 실시간 갱신
  resize: () => void;                            // 캔버스 크기 다시 읽기
  destroy: () => void;                           // 루프 정지 + GPU 자원 해제
}

// 이 브라우저가 html-in-canvas를 지원하나? (SSR 안전)
export function supportsHtmlInCanvas(): boolean {
  if (typeof document === "undefined") return false;
  const probe = document.createElement("canvas") as PaintableCanvas;
  const ctx = probe.getContext("2d") as ElementImageContext | null;
  return Boolean(
    ctx &&
    typeof ctx.drawElementImage === "function" &&
    typeof probe.requestPaint === "function",
  );
}

4-3. 핵심 메커니즘 — 세 요소(source / content / output)

이펙트의 심장은 세 개의 DOM 요소가 맞물려 도는 방식이다. 이걸 이해하면 Canvas UI의 절반을 이해한 것이다.

코드로 보면 이렇다. html-in-canvas가 지원될 때, DOM이 다시 칠해질 때마다 onpaint가 살아있는 content를 source 캔버스에 비트맵으로 굽고, 그 비트맵을 WebGL 텍스처로 업로드한다.

if (htmlInCanvas) {
  paintable.onpaint = () => {
    try {
      sourceCtx!.reset();
      sourceCtx!.drawElementImage!(content, 0, 0);  // 살아있는 DOM → 캔버스 비트맵
      contentDirty = true;
      wake();  // 렌더 루프 깨우기
    } catch {}
  };
}

// 프레임 루프에서: 더러워졌을 때만 GPU로 업로드(낭비 방지)
function uploadContent() {
  if (!htmlInCanvas || !contentDirty) return;
  contentDirty = false;
  gl!.bindTexture(gl!.TEXTURE_2D, contentTexture);
  gl!.texImage2D(gl!.TEXTURE_2D, 0, gl!.RGBA, gl!.RGBA, gl!.UNSIGNED_BYTE, source);
  gl!.generateMipmap(gl!.TEXTURE_2D);
}

4-4. 얇은 래퍼가 하는 일 — 폴백 분기까지

React 래퍼(약 124줄)의 임무는 넷뿐이다: (1) SSR 안전하게 지원 감지, (2) 세 요소 렌더, (3) useEffect로 엔진 연결, (4) prop이 바뀌면 setOptions로 전달. 지원 감지는 useSyncExternalStore로 하는데, 서버에서는 무조건 false(폴백)로 시작해 하이드레이션 불일치를 피한다.

// 지원 감지 — SSR 안전(서버 → false)
const supported = useSyncExternalStore(emptySubscribe, supportsHtmlInCanvas, () => false);
const native = supported && !failed;

useEffect(() => {
  instanceRef.current = createAsciify({ source, content, output }, initialOptions);
  if (native && !instanceRef.current) setFailed(true);  // 엔진이 null → 폴백으로
  return () => { instanceRef.current?.destroy(); };  // 언마운트 시 정리
}, [initialOptions, native]);

useEffect(() => { instanceRef.current?.setOptions(options); });  // prop 변경 실시간 반영

렌더되는 마크업이 폴백의 정체를 드러낸다. 지원되면 당신의 콘텐츠가 <canvas layoutsubtree> 안으로 들어가 라이브 텍스처가 되고, 안 되면 평범한 형제 <div>에 그대로 렌더되며 오직 오버레이 output 캔버스만 돈다. 어느 쪽이든 사용자는 콘텐츠를 본다.

4-5. 두 렌더링 패밀리 — 이걸 뭉뚱그리면 안 된다

three.js 쪽은 훨씬 단순한 래퍼(약 58줄)를 갖는다 — source/content 분리 없이 캔버스 하나다. 유리(Glass) 물체는 표준 three.js 투과 재질을 prop으로 구동한다.

import * as THREE from "three";
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

const glass = new THREE.MeshPhysicalMaterial({
  color: 0xffffff, metalness: 0, transmission: 1,  // 완전 투과 유리
  clearcoatRoughness: 0.06, specularIntensity: 1,
});
// prop → 물리 계수(범위 클램프)
glass.ior        = Math.min(Math.max(config.ior, 1), 2.333);   // 굴절률
glass.dispersion = Math.max(config.dispersion, 0);            // 색분산(무지개)
glass.clearcoat  = Math.min(Math.max(config.clearcoat, 0), 1);

4-6. 배포 시점의 마법 — makeStandalone()

여기서 반전이 있다. 저장소 안에서는 엔진(*Vanilla.ts)과 래퍼(*.tsx)가 분리돼 있지만, 사용자에게 배포되는 파일은 엔진이 래퍼 안으로 인라인된 단일 자기완결 파일이다. 빌드 시점에 registry.ts의 makeStandalone()이 import {…} from "./XxxVanilla" 줄을 지우고 그 자리에 엔진 본문을 통째로 이어붙인다. React/Solid/Preact는 import 치환으로, Vue/Svelte는 <script> 블록 주입으로 처리한다.

function makeStandalone(base, wrapper, engine, kind) {
  const body = engine.trimEnd();
  if (kind === "react" || kind === "solid" || kind === "preact") {
    return wrapper.replace(vanillaImport(base), body + "\n\n")     // import 줄 → 엔진 본문
                  .replace(/\nexport type \{[^}]*\};\n?/, "\n");
  }
  const stripped = wrapper.replace(vanillaImport(base), "");
  if (kind === "vue") return `<script lang="ts">\n${body}\n</script>\n\n${stripped}`;
  // svelte: <script module> 안으로 주입
}

5디렉토리 구조 해부

구조를 보면 저자의 규율이 보인다. 사용자에게 복사돼 나갈 코드(src/lib/)와, 그것을 소개하는 사이트 코드(src/app/·src/components/)를 철저히 분리했다. 배포되는 것은 오직 src/lib/뿐이고 나머지는 전부 마케팅·문서다.

구조가 말하는 이야기는 분명하다. 진짜 무게중심은 src/lib/의 25개 *Vanilla.ts 엔진에 있다. 엔진 크기는 Glitch 424줄부터 HexFloat 1616줄, Frost 1186줄까지 — 이 손으로 짠 셰이더들이 라이브러리의 실질적 자산이다. 래퍼는 58~148줄로 얇다. "생성은 얇게, 이펙트 엔진은 두껍게"라는 분포가 이 프로젝트의 정체성을 그대로 반영한다.

6학습 포인트

배울 것 ① — html-in-canvas, 가장 새로운 웹 그래픽 API

drawElementImage · requestPaint · layoutsubtree 삼총사를 실제 프로덕션 코드에서 볼 수 있는 드문 기회다. "살아있는 DOM을 GPU 텍스처로 만든다"는 개념과, 지원 감지·오리진 트라이얼·폴백까지 신기능을 안전하게 채택하는 전 과정을 배운다. 아직 문서가 거의 없는 API라 이 레포 자체가 레퍼런스다.

배울 것 ② — 프레임워크 무관 컴포넌트 아키텍처

이 레포에서 가장 재사용 가치가 큰 교훈. "순수 로직 엔진(팩토리 → {setOptions, resize, destroy}) + 얇은 프레임워크 래퍼"라는 패턴은 이펙트 라이브러리뿐 아니라 어떤 크로스 프레임워크 라이브러리에도 적용된다. React useSyncExternalStore로 외부 상태를 SSR 안전하게 구독하는 법까지 실물로 익힌다.

배울 것 ③ — three.js 없이 raw WebGL2 + GLSL

22개 이펙트가 맨손 WebGL2다. 컨텍스트 생성, #version 300 es 셰이더 컴파일, 유니폼 위치 자동 탐색(ACTIVE_UNIFORMS 순회), 화면을 덮는 사각형(TRIANGLE_STRIP 4정점)으로 프래그먼트 셰이더 구동 — WebGL 저수준을 정독할 최고의 교재다. three.js가 감춰주던 것들을 직접 보게 된다.

배울 것 ④ — GPU 유체 시뮬레이션(Navier-Stokes)

LiquidVanilla.ts는 고전적 안정 유체(stable fluids) 솔버다. ADVECT · DIVERGENCE · CURL · VORTICITY · PRESSURE · GRADIENT 등 9개 셰이더 프로그램을 더블 버퍼링된 부동소수 FBO 위에서 돌린다(simResolution 128, pressureIterations 4). 대학원 그래픽스 과제로 나오는 유체 시뮬을 실전 코드로 뜯어볼 수 있다.

// FRAG_ADVECT — 준-라그랑주 이류(과거로 거슬러 샘플링)
vec2 coord = vUv - uDt * texture(uVelocity, vUv).xy * texelSize;
outColor = uDissipation * texture(uSource, coord);

// FRAG_PRESSURE — 야코비 반복(pressureIterations 번 반복)
float pressure = (L + R + B + T - divergence) * 0.25;

배울 것 ⑤ — 물리 기반 유리·굴절 셰이더

GlassVanilla.ts는 raw WebGL로 둥근 사각형 SDF 렌즈 + 프레넬(Fresnel) + 6개 파장 색수차(chromatic aberration)를 구현해 진짜 분광(dispersion)을 낸다. 페이지 텍스처를 파장별로 굴절해 무지개 테두리를 만드는 이 기법은, 유리 재질 렌더링의 정수를 순수 GLSL로 보여준다.

// 파장별 굴절률 → 6개 파장(611.4~374nm)으로 페이지를 각각 샘플링해 합성
float iorForWavelength (float w) {
  float ab = uAberration * 0.1;
  return mix(uIor + ab, uIor - ab, 1.0 - pow(1.0 - linearStep(450.0, 650.0, w), 4.0));
}
refracted  = sampleRefraction(basePx, rim, normal, iorForWavelength(611.4)) * vec3(1,0,0);
refracted += sampleRefraction(basePx, rim, normal, iorForWavelength(570.5)) * vec3(1,1,0);
// ...4개 파장 더... 그리고 재결합

배울 것 ⑥ — shadcn 레지스트리로 라이브러리 배포하기

npm 없이 컴포넌트를 배포하는 법. registry-item.json 규격, getRegistryItem이 설치 경로(components/canvasui/)를 정하는 법, Solid엔 solid-js를 deps에 추가하는 식의 프레임워크별 처리, 그리고 MCP 서버 연결까지. "복사해서 쓰는" 배포를 직접 만들어보고 싶은 사람에게 완결된 예제다.

7시스템/브라우저 요구사항

주목할 점은 "성능 부담의 위치"다. 라이브러리 소비자는 무거운 런타임을 설치하지 않는다(대부분 의존성 0). 진짜 비용은 GPU가 매 프레임 DOM 텍스처를 업로드하고 셰이더를 돌리는 렌더 루프에서 나온다. 그래서 "더러울 때만 업로드(contentDirty)", "포인터 멈추면 루프 정지", "화면 밖이면 IntersectionObserver로 일시정지", "DPR 상한 2" 같은 최적화가 전부 성능·배터리 절감 장치로 맞물려 있다. 아키텍처와 성능 구조가 한 몸인 셈이다.

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

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

이 순서를 밟으면 Canvas UI는 단순한 "예쁜 이펙트 모음"이 아니라 최신 브라우저 API·GPU 그래픽스·크로스 프레임워크 라이브러리 설계를 잇는 살아있는 교과서가 된다. 각 주차 개념이 정확히 어느 소스 파일에 구현돼 있어, "이론 → 실제 코드" 왕복 학습이 가능하다.

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/DavidHDev/canvas-ui (MIT + Commons Clause · v0.1.0 · 저자 David Haz)
• 공식 사이트: canvasui.dev — 문서(/docs) · 컴포넌트 갤러리(/components) · 플레이그라운드
• TrendShift: trendshift.io/repositories/90816 (2026-07-25 Daily #12)
• html-in-canvas 스펙: Chrome Platform Status feature 5162535032373248(canvas drawElement/drawElementImage)
• 빠른 시작: npx shadcn@latest add @canvas-ui/liquid-react (맛 접미사를 solid/preact/vue/svelte/vanilla로 교체)
• 핵심 소스: src/lib/registry.ts(makeStandalone·컴포넌트 정의) · scripts/build-registry.mts(레지스트리 생성) · src/lib/<Name>/<Name>Vanilla.ts(각 엔진)
• 대표 엔진: LiquidVanilla.ts(유체 시뮬 9셰이더) · GlassVanilla.ts(SDF·색수차) · GlassObjectVanilla.ts(three.js 투과 재질)
• 배경 개념: WebGL2·GLSL 셰이더 · Navier-Stokes 안정 유체 · 프레넬/색수차/SDF · three.js MeshPhysicalMaterial·PMREM · shadcn 레지스트리·MCP · React useSyncExternalStore · 프로그레시브 인핸스먼트