@g1cloud/bpmn-modeler-next

BPMN 프로세스 문서 저작 에디터 Vue 3 라이브러리. 표준 BPMN 2.0 다이어그램을 시각적으로 저작하고, AI 에이전트로 프로세스 문서를 생성·편집하는 것을 목표로 한다.

• 패키지: @g1cloud/bpmn-modeler-next
• 스택: TypeScript · Vue 3 · Vite(library mode) · Vitest 4(browser mode) · 캔버스 = bpmn-js 18 래핑
• 상태: beta (5.0.0-beta.*)

개요

레거시 bluework 의 BPMN 저작 기능을 시블링(entity-modeler-next / ui-modeler-next)과 동일 위상 — 라이브러리 패키지 + bluework4-tool 호스트 임베드 + 에이전트 저작 — 으로 재구현한다.

두 종류의 소비자를 지원한다.

• 에디터 통합자 — Vue 앱(호스트)에 캔버스를 임베드. createBpmnEditorController + BpmnModelerView + op 전송층.
• 에이전트/서버 — 에디터 없이 문서를 읽고(describeProcess) 쓰는(applyBpmnOpBatch) 표면. read 는 순수 함수, write 는 헤드리스 modeler(createHeadlessBpmnModeler)로 서버에서 집행한다.

핵심 설계

• 진실은 표준 BPMN 2.0 XML 단일. 영속 형태는 표준 XML 하나뿐이고, 에이전트 대면 IR 은 거기서 파생 생성되는 뷰다(IR·JSON 병행 저장 없음). 레거시가 이미 표준 XML 을 저장하므로 마이그레이션 비용이 0이다.
• 2단계 컴파일러. 라이브러리에 LLM SDK 는 없다. 외부 LLM 이 심볼릭 op 를 생성하고, 결정론적 resolver 가 이를 bpmn-js modeling API 로 하강(lowering)한다.
• AI 는 좌표를 직접 생성하지 않는다. 신규 초안은 하이브리드 배치(프로세스 내부 자동 레이아웃 + 풀 골격·메시지플로우·주석 op), 부분 편집은 기존 배치를 보존한다.
• 힌트 = 선택적 장식. 배치 힌트(주석 방위·그룹 멤버·풀 순서·밴드)는 표준 내 extensionElements(bwl 네임스페이스)에 싣는다. 소실되어도 휴리스틱으로 재생성 가능한 파생 정보이며, 어휘 진화는 additive-only 다.
• 문서 단위 낙관적 버전. 동시성 단위는 문서 하나(baseVersion 스칼라). BPMN 은 단일 저작자·소규모 문서가 일반적이라 element 단위 CAS 는 두지 않는다 — 시블링의 파트 단위 CAS 와 의도적으로 다른 선택이다.

하강 경로 2종 (같은 의미론)

| 경로 | 주체 | 용도 | |---|---|---| | 캔버스 | controller.applyAgentBatch — 열린 에디터가 적용 | GUI 채팅. 배치 = 단일 undo 에피소드(op 수십 개가 사용자 undo 1회로 되감김) + 턴 중 사용자 편집 잠금 | | 헤드리스 | createHeadlessBpmnModeler + applyBpmnOpBatch — 호스트 서버가 집행 | CLI·배치 저작. Node + jsdom 에서 동작 |

두 경로는 같은 resolver·같은 배치 wire 를 타며, 구조 타입 BpmnModelerLike 가 그 공유를 타입으로 강제한다. 헤드리스 산출 DI 는 캔버스와 도형 바운즈 0 오차·외부 라벨 ±2px 로 등가가 고정되어 있다(회귀 게이트 2종).

설치

pnpm add @g1cloud/bpmn-modeler-next

peer dependency:

{
  "vue": "^3.5.0"
}

bpmn-js·diagram-js·bpmn-moddle 계열은 이 패키지의 dependencies 로 함께 설치된다.

스타일시트를 함께 임포트한다(bpmn-js 캔버스 자산이 흡수되어 있어 없으면 다이어그램이 렌더되지 않는다).

import '@g1cloud/bpmn-modeler-next/style.css'

빠른 시작 — 에디터 임베드

<template>
  <BpmnModelerView ref="view" :xml="initialXml" @ready="onReady" />
</template>

<script setup lang="ts">
import { provide, ref } from 'vue'
import { BpmnModelerView, createBpmnEditorController, EDITOR } from '@g1cloud/bpmn-modeler-next'

const view = ref<InstanceType<typeof BpmnModelerView>>()
const controller = createBpmnEditorController()

// 뷰 컴포넌트·패널이 inject 로 소비
provide(EDITOR, controller)

// 캔버스가 마운트되면 modeler 를 컨트롤러에 붙인다(컨트롤러는 bpmn-js 생성을 소유하지 않는다)
function onReady() {
  controller.attach(view.value!.getModeler()!)
}
</script>

컨트롤러는 importXml/saveXml/dirty 와 에이전트 턴 통합(applyAgentBatch·setEditable·agentBusy)을 제공한다. 뷰는 imported(경고 목록)·import-error 도 emit 한다.

에이전트 / 서버 표면

import {
  describeProcess,            // moddle definitions → IrDefinition + hints + omitted (파생 뷰)
  describeProcessXml,         // XML 입력 래퍼 — 순수, 서버 실행 가능
  buildBpmnOpBatch,           // SymbolicOp[] → BpmnOpBatch (baseVersion·origin·멱등 키)
  applyBpmnOps,               // op 배치 하강 (사전 전수 검증 + 실패 시 단일 undo 되감기)
  applyBpmnOpBatch,           // CAS 포함 배치 적용 → ApplyBatchOutcome
  createHeadlessBpmnModeler,  // 에디터 없는 하강용 modeler (Node + jsdom)
  APPLY_BPMN_OPS_SCHEMA,      // applyOps 도구 input_schema (op 어휘의 JSON Schema 단일 출처)
  SYMBOLIC_OP_KINDS,          // op 종류 17
  IR_FLOW_NODE_TYPES,         // describe 가 내는 노드 타입 12 (read)
  ADDABLE_FLOW_NODE_TYPES,    // op 로 만들 수 있는 노드 타입 10 (write · read 의 부분집합)
  IR_EVENT_DEFINITIONS,       // 이벤트 정의 — 'timer' (intermediateCatchEvent 전용)
  BWL_SIDES,                  // 주석 방위 8
} from '@g1cloud/bpmn-modeler-next'

• 실패는 throw 하지 않는다. ApplyBatchOutcome 은 applied / conflict / rejected 세 상태이고, 거부는 issues 로 교정 지점을 지시한다(LLM 교정 루프 전제).
• 원자성: 한 배치 = 한 원자 단위. rejected 면 문서는 무변경이다.
• 카탈로그는 별도 함수가 아니라 정적 스키마 + 어휘 상수다 — BPMN 어휘가 닫힌 집합이라 시블링의 런타임 catalog 필터가 불필요하다. 공개 표면은 src/index.test.ts 가 계약으로 고정한다.

헤드리스 하강은 jsdom 전역을 세운 뒤 호출한다. 라벨 정밀도가 더 필요하면 canvas 패키지를 설치하고 dom: { textMeasurement: 'native' } 로 전환한다.

const modeler = createHeadlessBpmnModeler()
await modeler.importXML(xml)
const outcome = await applyBpmnOpBatch(modeler, batch, { currentVersion })

공개 API 표면

| 영역 | 주요 export | |---|---| | core | IrDefinition·IrNode·IrSequenceFlow 등 IR 어휘 · BWL_NS/BWL_PREFIX/BWL_MODDLE_SCHEMA 힌트 네임스페이스 · BpmnModelerLike | | command | commandSeam(do/undo 계약) · executeAsUndoEpisode(배치를 undo 1회 단위로 묶는 합성 커맨드) | | agent | SymbolicOp 어휘 · applyBpmnOps·validateOps·lowerOps · describeProcess · APPLY_BPMN_OPS_SCHEMA · buildBpmnOpBatch/applyBpmnOpBatch | | editor | createBpmnEditorController · EDITOR inject key | | view | BpmnModelerView | | headless | createHeadlessBpmnModeler · installHeadlessBpmnDom · HEADLESS_BPMN_MODULES · HEADLESS_TEXT_METRICS | | adapter | loadBpmnXml/saveBpmnXml · createBpmnModdle · BPMN_MODDLE_EXTENSIONS(i18n·bwl 스키마 등록) |

개발

pnpm dev          # 데모 하네스 (src/dev)
pnpm test         # Vitest — unit(jsdom) + browser(chromium) 2계층
pnpm typecheck    # vue-tsc --noEmit
pnpm build        # 라이브러리 빌드 → dist/

• Node >= 24.10.0
• 테스트는 2계층이다. 순수 로직은 jsdom, bpmn-js 하강 검증(*.browser.test.ts)은 실브라우저(chromium) 에서 돈다 — 하강이 실 DOM 의미에 의존하므로 시블링의 Vitest 2.x 단일 환경과 의도적으로 diverge 했다.

라이선스

LicenseRef-LICENSE — 사내 라이선스(패키지 license 필드 기준).