Pascal Editor 딥다이브
— 브라우저 3D 건축 편집기에서 "AI가 집을 짓는" MCP 플랫폼으로

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 짧고 명확하다: "A 3D building editor built with React Three Fiber and WebGPU." 실제로 열어 보면 Site → Building → Level → (Wall/Slab/Ceiling/Roof/Zone) → Item의 계층 구조 위에서, 각 요소가 Zod 스키마로 타입 검증되고 Zustand 스토어에 플랫 딕셔너리로 저장된다.

루트 AGENTS.md(=CLAUDE.md=GEMINI.md 심링크)는 이 레포가 "Consumed both as npm packages and (in pascalorg/private-editor) as a git submodule"라고 밝힌다 — 즉 이 공개 레포가 상용 서비스(private-editor)의 엔진 역할도 겸한다. 오픈소스 코어 위에 비공개 프로덕트를 얹는 전형적인 "오픈 코어" 전략이다.

2왜 주목받는가

WebGPU 실전 적용 · MCP로 "AI가 집 짓기" · IFC 건축 표준 지원 · 서드파티 플러그인 생태계.

3월 분석 대비 무엇이 달라졌나

경쟁 제품 비교

주목도를 끌어올린 구체적 요인은 다음과 같다. ① "AI가 집을 짓는다"는 화제성. MCP 서버 하나로 Claude가 create_room·add_door·furnish_room을 호출해 실제 3D 건물을 만드는 데모는 AI 에이전트 시대의 대표적 활용 사례가 됐다.
② Vision AI 파이프라인. analyze_floorplan_image·analyze_room_photo·photo_to_scene 툴로 스마트폰 사진 한 장을 3D 씬으로 역변환하는 기능은 실측(measurement) 도구로도 활용 가치가 크다.
③ 프로덕션급 아키텍처 문서. wiki/architecture/의 17개 문서와 .agents/skills/review-architecture/는 대규모 오픈소스 프로젝트가 AI 코딩 에이전트와 협업하는 법을 실전으로 보여준다.

3기술 스택 전체 지도

프론트엔드(R3F/WebGPU) · MCP 백엔드(Bun+SQLite) · Turborepo 10패키지 인프라.

① 프론트엔드 (UI & 렌더링)

② 상태관리 & 데이터 검증

③ 3D 지오메트리 & 연산

④ MCP 백엔드 (packages/mcp) — 신규 축

⑤ 빌드 & 개발 도구

4아키텍처 심화 분석

3계층 레이어 경계 + 3체크박스 노드 정의 모델 + MCP↔브라우저 실시간 동기화.

Pascal Editor의 아키텍처는 AGENTS.md가 못박은 세 개의 엄격한 레이어 경계 위에 서 있다. packages/core는 Three.js를 몰라야 하고(순수 도메인 로직), packages/viewer는 에디터 개념(툴·패널·모드)을 몰라야 하며(뷰어 격리), apps/editor만 이 둘을 조합해 실제 편집 경험을 만든다. 이 경계 위에 MCP 서버가 core를 헤드리스로 직접 구동하는 네 번째 진입점이 얹혀 있다.

핵심 설계 패턴 1 — 3체크박스 노드 정의 모델

기존 분석(3월)에서는 렌더러가 하나의 방식(React 컴포넌트)으로 통일된 것처럼 보였지만, 지금은 wiki/architecture/node-definitions.md가 정의하는 독립적인 3개 필드로 세분화됐다. 노드 종류(kind)마다 필요한 조합만 켠다.

// shelf — 순수 geometry만, React·프레임 로직 없음
export const shelfDefinition: NodeDefinition<typeof ShelfNode> = {
  geometry: buildShelfGeometry,         // geometry.ts의 순수 함수
}

// door — 순수 geometry + 애니메이션 system 병행
export const doorDefinition: NodeDefinition<typeof DoorNode> = {
  geometry: buildDoorGeometry,
  system: { module: () => import('./animation') },  // operationState 진행
}

런타임에서는 <NodeRenderer>가 def.renderer 유무로 커스텀 컴포넌트 or <ParametricNodeRenderer>(빈 그룹 + 레지스트리 등록)를 고르고, <GeometrySystem>이 매 프레임 dirty한 노드 중 def.geometry가 있는 것만 재빌드한다. "구조/조직용 킨드(site·building·level·zone)"는 dirtyTracking: false로 이 추적에서 아예 빠진다 — 불필요한 더티 마크가 세션 내내 누적되는 걸 막기 위해서다.

핵심 설계 패턴 2 — GeometryContext로 "순수함" 지키기

geometry() 두 번째 인자 GeometryContext는 resolve()·children·siblings·parent만 제공한다. 벽은 ctx.siblings로 이웃 벽과 모서리를 맞대고(mitering), 문/창문은 ctx.parent로 자신이 박힌 벽의 두께를 읽어 프레임 깊이를 맞춘다. 빌더 함수 자체는 useScene import도, 스토어 mutation도 하지 않는 순수 함수로 남아 유닛 테스트가 쉽다.

핵심 설계 패턴 3 — 상호작용 스코프 (Interaction Scope, "the spine")

wiki/architecture/interaction-scope.md가 정의하는, 배치·이동·핸들 조작·박스 선택·페인트 등 모든 포인터 상호작용을 관장하는 단일 상태 머신이다. InteractionScope 유니온 타입 + begin/update/end/endIf 계약으로, "지금 무엇을 클릭하면 무슨 일이 일어나야 하는가"를 한 곳에서 판정한다. PR이 배치/이동/핸들/리셰이프/박스선택/페인트 중 하나라도 건드리면 이 문서를 반드시 읽어야 한다고 AGENTS.md가 명시한다 — 그만큼 사고(엉뚱한 클릭 처리) 위험이 큰 코어라는 뜻이다.

핵심 설계 패턴 4 — MCP ↔ 브라우저 실시간 동기화(Live Sync)

MCP와 에디터가 같은 PASCAL_DATA_DIR을 공유하면, MCP의 씬 변경이 SQLite에 저장되고 로컬 scene_events 스트림에 기록된다. 열려 있는 에디터 브라우저 탭은 /api/scenes/:id/events를 Server-Sent Events로 구독해 씬 그래프 스냅샷을 실시간 반영한다. 각 mutation은 저장 전 버전 체크를 거쳐, 브라우저와 MCP 프로세스가 동시에 저장하면 live_sync_version_conflict를 반환하고 load_scene으로 재로드하게 한다 — 낙관적 동시성 제어(optimistic concurrency)의 실전 사례다.

설계 패턴 5 — 플랫 노드 저장 + 더티 트래킹 (기존 핵심, 여전히 유효)

모든 노드는 Record<id, Node> 평면 딕셔너리에 저장되고, parentId/children으로만 트리를 표현한다. 노드가 바뀌면 dirtyNodes Set에 추가되고, 다음 useFrame에서 그 노드만 재계산된다. Figma·Notion류 복잡한 에디터의 공통 패턴을, Pascal은 44종 건축 노드 + MCP 동시 편집까지 확장해 적용하고 있다.

// 업데이트 시 dirtyNodes에 자동 추가 (사람이든 MCP든 동일 경로)
useScene.getState().updateNode(wallId, { thickness: 0.2 })

// GeometrySystem 렌더 루프: dirty 노드 중 def.geometry 보유자만 처리
useFrame(() => {
  for (const id of dirtyNodes) {
    const group = sceneRegistry.nodes.get(id)          // O(1)
    const ctx = buildGeometryContext(id)              // siblings/parent/children
    const built = def.geometry(node, ctx, shading, textures, colorPreset, theme)
    disposeOldChildren(group); group.add(...built.children)
    clearDirty(id)
  }
})

5디렉토리 구조 해부

2개 앱 + 10개 패키지 Turborepo 모노레포 — 1,302개 TS/TSX 파일.

네 덩어리로 나눠 읽으면 명료하다.

① 도메인 코어 packages/core/. Three.js를 몰라야 하는 순수 로직 레이어. 44종 노드 스키마와 nodeRegistry가 여기 있다. 이 패키지 하나가 UI(apps/editor)와 MCP(packages/mcp) 양쪽에서 동시에 소비된다 — "도메인 로직은 한 곳, 진입점은 여럿"의 실물이다.

② 독립 뷰어 packages/viewer/. 에디터 개념을 모르는 "순수 3D 캔버스"로, 그 자체로 npm 배포된다. 19개의 뷰어 시스템(ceiling·column·door·roof·stair·window·zone 등)이 각 노드 킨드의 프레임별 갱신을 맡는다.

③ MCP 서버 packages/mcp/. 이번 재분석의 핵심 신규 축. tools/ 안에 기능별로 vision(사진 분석)·photo-to-scene(역변환)·scene-lifecycle(저장/불러오기)·templates(정원 딸린 집 등 프리셋)·variants(설계 변형 자동 생성) 5개 하위 그룹이 있다. 거의 모든 툴 파일 옆에 *.test.ts가 붙어 있어 AI가 호출하는 인터페이스일수록 테스트를 촘촘히 깐다는 원칙이 보인다.

④ 위키 + 에이전트 스킬 wiki/architecture/, .agents/skills/. 사람이 아니라 AI 코딩 에이전트가 읽도록 설계된 규범 문서다. AGENTS.md가 "레이어 경계를 건드리는 변경 전에는 반드시 이 문서를 먼저 읽어라"고 명시하고, review-architecture 스킬이 PR 리뷰 시 이를 자동으로 로드해 위반 여부를 층별로 분류·보고한다.

6학습 포인트 (기술별)

이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.

7하드웨어 / 시스템 요구사항

WebGPU 지원 브라우저 필수 · MCP 서버는 Bun만 있으면 헤드리스로 별도 구동.

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

난이도별로 손을 움직여 보는 5가지 — 3D 에디터부터 MCP AI 연동까지.

입문 ★☆☆☆☆

git clone https://github.com/pascalorg/editor.git
cd editor
bun install
bun dev
# http://localhost:3002 에서 에디터 열기

중급 ★★☆☆☆

# 리포 루트에서
bun run --filter=@pascal-app/mcp build
claude mcp add pascal bun /absolute/path/to/editor/packages/mcp/dist/bin/pascal-mcp.js

고급 ★★★☆☆

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

5주 코스 — R3F/WebGPU 기초부터 MCP 서버 직접 만들기까지.

10핵심 키워드 사전

이 프로젝트를 읽을 때 반복 등장하는 용어 정리.

11참고 링크

원본을 직접 확인하고 싶을 때.