공개 SDK 지원 범위 조사 — 2026-09-20

연결: #294, 사업 토론 #288. 상태: 공개 메타데이터·소스 조사 완료. 지원 정책과 개발자 사용성 검증은 미완료.

조사 기준

• 원격 main: 558714a818ae8f0dcffc8436d8e7e30a66c93442.
• 기존 npm 배포 보고의 원본: b300ea1ac43bd45958a89dea3d2d3548cc48cfda. #260 최종 기록.
• 이번 직접 확인: 공개 패키지 31개의 npm latest 버전·exports·peerDependencies·license. 조회일은 2026-09-20이다. latest는 조회 당시의 상태이며 고정 버전 URL을 표에 연결했다.
• main의 공개 package.json 목록 및 배포 commit의 publishConfig.exports와 대조했다. 31개 모두 버전과 공개 경로가 일치했다. JS/타입 경로 44개, CSS 경로 9개다. 모든 조회 대상의 license는 MIT다.
• [email protected]과 [email protected] 두 공개 압축 파일을 내려받아 registry SHA-512와 대조하고 선언 파일을 읽었다. 다른 29개 압축 파일의 내용은 이번에 다시 검사하지 않았다.
• 설치·컴파일·브라우저 실행·전체 archive manifest 재검증은 이번 회차에서 하지 않았다. 기존 보고의 실행 성공을 이번 실행 결과로 표시하지 않는다.

중요한 발견: main API와 npm API가 다르다

패키지 버전 문자열과 공개 import 경로가 같아도, 아직 릴리스하지 않은 main의 공개 심볼은 다를 수 있다.

확인 대상	main 소스	공개 npm 선언 파일
model	FragmentEditor, defineEditingPolicy, encodeClipboardFragment를 export	[email protected]의 선언 파일 80개에서 세 심볼을 찾지 못함
extensions	standardClipboardPolicy를 export	[email protected]의 선언 파일 60개에서 심볼을 찾지 못함

근거: model 공개 연결, editing export, extensions export, 대기 Changeset. 공개 npm 파일은 아래 고정 버전 registry 기록의 dist.tarball과 대조했다.

판단: 새 API 안내에는 사용 가능한 배포 버전 또는 main 전용·미배포 표시가 필요하다. 현재 npm 설치 안내에 main 전용 예제를 무조건 연결하면 첫 통합을 막을 수 있다. 배포 실패나 패키지 철회의 근거는 아니다. 기존 #294의 버전/지원 범위 작업에 포함하고 새 이슈를 만들지 않는다.

공개 패키지 목록

모든 이름은 @barocss/ 아래다. .은 패키지 루트다. 분류는 지원 책임을 논의하기 위한 제안이며 등급·SLA를 확정하지 않는다. /src/...는 공개 계약이 아니다.

분류 제안	패키지와 고정 버전 registry 근거	배포 버전	공개 경로
엔진·문서 계약	shared	1.0.1	.
엔진·문서 계약	datastore	0.1.3	.
엔진·문서 계약	schema	1.0.1	.
엔진·문서 계약	model	1.0.3	.
엔진·문서 계약	editor-core	1.0.3	.
엔진·문서 계약	extensions	1.0.3	.
엔진·문서 계약	dsl	1.1.1	.
엔진·문서 계약	text-analyzer	0.1.1	.
엔진·문서 계약	converter	1.0.3	.
편집 화면·렌더러	dom-observer	0.1.1	.
편집 화면·렌더러	renderer-dom	1.0.3	.
편집 화면·렌더러	renderer-react	0.2.1	.
편집 화면·렌더러	editor-view-dom	0.1.3	.
편집 화면·렌더러	editor-view-react	0.1.3	.
Office 공통 기반	office-text	0.1.2	., ./text.css
Office 공통 기반	office-canvas	0.1.2	.
Office 공통 기반	office-controls	0.1.2	.
Office 공통 기반	office-editor-ui	0.1.2	.
Office 공통 기반	office-icons	0.1.2	.
Office 공통 기반	office-ui	0.1.2	., ./tokens.css
제품·자료함	office-note	0.1.2	., ./view, ./note.css, ./workspace
제품·자료함	office-word	0.1.2	., ./ui, ./ui.css, ./workspace
제품·자료함	office-slides	0.1.2	., ./ui, ./ui.css, ./workspace, ./slides.css
제품·자료함	office-site	0.1.2	., ./ui, ./ui.css, ./workspace
제품·자료함	office-workspace	0.1.2	., ./ui, ./host, ./style.css
협업 adapter	collaboration	0.1.3	.
협업 adapter	collaboration-yjs	0.1.3	.
협업 adapter	collaboration-liveblocks	0.1.3	.
개발·검색 도구	conformance	0.1.2	.
개발·검색 도구	devtool	0.1.3	.
개발·검색 도구	query-editor	0.1.2	., ./jql, ./core, ./react, ./style.css

@barocss/wonffice-release는 private 제품 릴리스 메타데이터다. 공개 SDK 31개에 포함하지 않는다. @barocss/math-editor는 별도 저장소가 공급하는 의존성이다. 이 저장소의 SDK 유지보수 범위로 합산하지 않는다. npm 릴리스 계약.

호환 선언과 확인된 검사 범위

항목	확인 사실	지원 약속으로 확대하지 않을 것
모듈	ESM·타입 선언·CSS, exports 기반 배포	CommonJS 지원. default 조건은 CJS 번들 제공을 뜻하지 않음
React	React view는 react/react-dom >=18.0.0. Office UI와 제품들은 >=18. renderer-react는 react >=18.0.0	모든 React 18 이후 버전과 SSR의 실행 검증
소비자 검사 환경	현재 consumer script는 React 18.3.1, TypeScript 5.9.3, Vite 5.4.21을 고정해 타입 검사와 build를 수행	브라우저 편집·마지막 입력 저장·기기별 동작까지 검사한다는 주장
협업	yjs ^13.6.0, Liveblocks client ^1.0.0을 peer로 선언	최신 공급자 버전이나 운영 수준 동시 편집 보장
내부 peer	registry의 model/datastore는 editor-core 1.0.3을 peer로 지정	저장소의 workspace:* 문자열을 소비자 설치 지침으로 사용
Node	조사한 31개 공개 manifest에는 engines 선언이 없음. 저장소 개발·CI는 .nvmrc 기준	Node 22.22.0을 모든 소비자의 입증된 최소 런타임으로 단정
브라우저/서버	React view와 제품 편집 표면은 브라우저 수명 관리가 필요	모든 루트 import의 SSR 안전성, Safari·Firefox·IME 지원 완료
Office 스타일	공개 CSS와 Tailwind 4의 설치된 dist 스캔 지침이 있음	CSS 한 파일만 추가하면 모든 호스트에서 같은 화면이 된다는 주장

근거: 각 행의 package registry 기록, consumer script, React 가이드, Note README. consumer script는 이번에 읽었으며 재실행하지 않았다.

개발자 진입 경로 제안

1. 자체 편집 UI를 만들 개발자

DOM 또는 React view 경로를 선택한다. schema·store·editor·extension·renderer registry의 책임을 배운다. 초기 예제에는 임의 고급 기능보다 입력→저장→완전한 호스트 종료→저장 데이터로 재생성하는 경로가 필요하다.

현재 DOM quick start와 React 가이드는 mount·cleanup을 보여 주며 저장은 호스트 책임으로 설명한다. 따라서 완전한 저장/재열기 예제가 끝났다고 보지 않는다. DOM 예제의 extension 생성 방식은 현재 문서 PR #304의 수정 범위와 겹치므로 별도 수정 이슈를 만들지 않는다.

2. 완성된 본문 편집기를 넣을 개발자

Note의 openNoteTree·NoteEditor를 우선 후보로 둔다. 이는 개발자 경험 제안이며 비교 실험으로 검증되지 않았다. openNoteTree의 onChange는 본문 blocks를 전달한다. flush/close와 호스트의 비동기 저장 완료는 다른 책임이다. 계정·서버·파일 업로드는 제품 호스트가 제공해야 한다.

Note 문서 #312가 이 수명·저장 예제와 기능 범위를 조사 중이다. 같은 문서를 다시 작성하지 않고, 그 결과를 공개 npm 고정 버전과 연결한다.

Word·Slides·Site는 제품별 factory·UI·codec 경로를 선택한다. workspace는 로컬 자료함과 제품 이동의 경로다. 이를 클라우드 계정·권한 서비스 SDK로 설명하지 않는다.

지원 등급을 정할 때 필요한 증거

아래는 평가 단계 제안이다. 현재 공식 지원 등급이 아니다.

단계	최소 증거	다음 확인
공개됨	exact version, exports, 라이선스, 출처	소비자 타입·build 및 실행
예제 검증됨	고정 배포 버전으로 빈 프로젝트의 예제가 동작	오류·cleanup·저장/재열기·복수 인스턴스
제품 통합 검증됨	지원 환경별 실제 업무와 복구 검증	호환 변경 정책·유지보수 책임·운영 조건

31개 모두 공개 메타데이터를 이번에 확인했다. #260은 기존 외부 소비자 타입/build 검증을 보고한다. 이 근거만으로 31개 모두의 제품 통합을 보증하지 않는다. 버전의 0.x/1.x 여부도 실행 증거를 대체하지 않는다.

#294의 다음 완료 과제

1. 두 진입 예제를 공개 npm 고정 버전에서 실행한다. 저장소 alias나 main에서 새로 pack한 파일을 쓰면 별도 결과로 표시한다.
2. 기본 입력·마지막 입력 저장·호스트 종료·재열기·cleanup을 검증한다. 예제 실행 시간, 막힌 단계, 문서 수정 필요를 기록한다.
3. main 전용 API의 표시 위치와 배포 뒤 바꿀 조건을 정한다. 문서 PR #304/#309 및 #312와 연결한다.
4. #311이 관리하는 릴리스 근거 기록을 재사용한다. 패키지 버전별 출처를 별도 수동 목록으로 이중 관리하지 않는다.
5. 지원 대상 환경과 책임자를 결정한다. 현재 등급표는 제안으로 유지한다.

개발자 활성화 지표 제안은 단순 설치 수가 아니라 “자기 호스트에서 작성한 내용을 저장하고 새 세션에서 재열기”다. 외부 개발자의 관찰이 없으므로 첫 성공 시간이나 전환율은 아직 계산하지 않는다.

범위와 후속

이번 회차는 목록·공개 경로·버전 경계의 확인이다. 코드 수정, npm 게시, 소비자 build 실행, SLA 또는 유료 정책 결정은 하지 않았다. #294는 열린 상태로 유지한다. 후속 독립 연구는 #296의 제공 형태별 비용 변수와 유료 가치 가설을 정리하는 것이다.