refactor: 모체 프로젝트와 2D 샘플을 npm workspace 구조로 통합 #5
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: cyhan/dwg-dxf-viewer-sample#5
Reference in New Issue
Block a user
Problem Statement
현재 2D 샘플은 표면상 독립 Vite 앱이지만, 재사용 구현·WASM·폰트·샘플 UI를 한 저장소에 복사해 둔 구조입니다. README는 모체의 2D 구현을 다시 복사해 동기화하라고 안내하지만, 현재 모체 저장소에는 해당 구현이나 이력이 없습니다. 두 저장소는 각각 단일 커밋이며 공통 조상도 확인되지 않아 어느 쪽이 원본인지 현재 기록만으로 증명할 수 없습니다.
그 결과 다음 문제가 있습니다.
Solution
정본 저장소를 먼저 확정한 뒤, 그 저장소를 단일 lockfile의 npm workspaces monorepo로 전환합니다. 목표 구조는 다음 세 개의 독립 workspace unit입니다.
@hmwebviewer/viewer2dpackage샘플 앱은 package의 public API만 소비하고 내부 모듈을 상대 import하지 않습니다. package는 parser, 공통 parse result, renderer lifecycle을 감추고
create/load/dispose중심의 깊은 interface를 제공합니다. WASM과 font URL은 명시적으로 주입하거나 package asset contract로 해결하며, root가 정확히 하나의 Three.js 버전과 인스턴스를 소유합니다.기존 샘플 저장소는 수동 복사로 합치지 않고 이력을 보존해 import합니다. 새 구조가 동일 동작과 배포를 통과한 뒤에도 삭제하지 않고 마지막 standalone tag와 새 위치를 안내하는 read-only archive로 유지합니다.
구현 전 Blocker
cyhanfork와 upstream 중 authoritative repository 및 변경 전파 정책을 결정합니다.dispose()가 RAF, window/DOM listener, controls, renderer, geometry, material, texture를 해제하는 lifecycle contract를 정의합니다.Commits
아래 각 단계는 작업 트리에서 RED를 먼저 확인하고 이슈 코멘트에 명령과 실패 로그를 남긴 뒤 최소 변경으로 GREEN을 만들며, 커밋 시점에는 전체 저장소가 동작해야 합니다.
Decision Document
Testing Decisions
좋은 테스트는 내부 함수 배치가 아니라 사용자가 관찰하는 파싱 결과, 렌더 상태, 오류, lifecycle, 배포 가능성을 검증해야 합니다.
Acceptance Criteria
Out of Scope
다음 항목은 이 이슈의 완료를 막지 않으며 별도 이슈로 관리합니다.
Further Notes
RED팀 3개 관점(이력/이관, package architecture, 테스트/운영)이 본 계획을 검토했습니다. 공통 판정은 계획 이슈 생성은 통과, 구현과 기존 저장소 종료는 Blocker 해결 전 보류입니다.
현재 환경에는 sample 의존성이 설치되어 있지 않아 typecheck가
tsc: not found로 종료했습니다. 이는 기능 RED 증거가 아니며, 실제 구현 시작 시 clean install 이후 의미 있는 행동 실패를 별도로 기록해야 합니다.구현 시작 — 2026-07-29
main브랜치를master기준으로 생성하고 체크아웃했습니다.BasicSample.dwg,simple.dxf로 characterization test를 먼저 구축합니다.코드 변경 전 기능 RED 결과와 구체 구현 방법을 다음 코멘트로 남기겠습니다.
RED 1 — 재사용 package consumer contract
명령:
관찰된 실패:
이는 의존성 설치/compile 실패가 아니라, 샘플이 사용할 재사용 package interface가 실제로 존재하지 않는 기능 RED입니다.
GREEN 구현 방법
@hmwebviewer/viewer2dworkspace package로 이동합니다.isCad2DFile,parseCad,createViewer2D(...).load()/dispose()를 제공합니다.simple.dxf를 public interface로 파싱하여 고정된 6개 entity와 layer를 반환하게 합니다.GREEN 1 —
@hmwebviewer/viewer2dpublic package contract구현:
isCad2DFile,parseCad,createViewer2D를 추가했습니다.@types/three는 최신 stable0.185.1단일 버전으로 exact pin했습니다.검증:
다음 RED는
Viewer2D.dispose()가 없어 mount/unmount 후 RAF와 listener를 해제할 수 없는 lifecycle contract입니다.RED 2 — monorepo + Three.js r185.1 통합
모체
a717900을 history-preserving subtree로 import하고 2D/3D/package workspace를 구성한 뒤 전체 검사를 실행했습니다.실패:
추가 RED팀 확인 결과 r185에서 PLYLoader가
doubleproperty를 Float64Array로 보존하므로 기존 loader가 이를 그대로 WebGL에 전달하는 의미 회귀도 확인했습니다.GREEN 구현 방법
GREEN 2 — 표준 npm workspaces + Three.js 0.185.1
a717900전체 tree를 history-preserving subtree로 import하고 byte-for-byte 동일성을 확인했습니다.0.185.1exact/deduped 한 벌로 통일했습니다.DoublePrecision.plyfixture를 추가했습니다.manualChunksinterface에 맞게 3D build를 수정했습니다.검증:
다음 단계는 실제 브라우저에서 2D/3D fixture matrix와 lifecycle RED→GREEN을 검증하는 것입니다.
RED 3 — Viewer2D lifecycle
실제 Chrome에서 sample DXF를 렌더한 뒤 package instance의 lifecycle을 검사했습니다.
실패:
현재 viewer는 RAF ID를 보관하지 않고 익명 window/canvas/control listener를 등록하며, canvas/WebGL context를 해제하는
dispose()interface가 없습니다.GREEN 구현 방법
dispose()를 멱등으로 구현해 RAF, listener, OrbitControls, scene geometry/material/texture, renderer/context, canvas, CAD result 참조를 해제합니다.onViewChange()는 unsubscribe 함수를 반환합니다.RED 4 — 무신뢰 CAD 입력 정책
실패:
요구 행동은 same-origin URL만 허용하고, URL/file/response 모두 50 MiB를 초과하면 parsing 전에 거부하는 것입니다.
GREEN에서는 URL resolution, byte limit, AbortController timeout을 작은 input-policy module에 숨기고 sample의 URL/file path가 같은 interface를 사용하도록 연결합니다.
GREEN 3 — 실제 Chrome E2E 포맷 매트릭스
npm run test:e2edispose()검증0.185.1: GLB, Draco GLB, OBJ, FBX, DAE, IFC, Float64 PLY 모두 실제 rendering 성공pageerror/console error 없음 확인남은 검증은 production subpath asset 경로, decoder staging 재현성, 전체 clean install 및 evidence attachment입니다.
RED 5 — production subpath asset 경로
tests/public-asset-url.test.ts를 먼저 추가하고 실행했습니다./viewer-3d/아래 배포 시 Draco, Basis/KTX2, web-ifc, preview asset도 동일 subpath 아래에서 resolveruntimeBasepublic contract가 없어 test suite가Cannot find module '../apps/viewer-3d/src/runtimeBase'로 실패/draco/,/basis/,/web-ifc/,/previews/root-absolute 경로를 확인구현 방법:
import.meta.env.BASE_URL을 한 곳에서 해석하는publicAssetUrl()을 추가하고 모든 runtime loader/preview 경로를 해당 함수로 전환한 뒤 unit 및 실제 subpath browser test로 GREEN을 확인합니다.RED 6 — 3D application pagehide lifecycle
실제 Chrome에서
pagehide를 dispatch한 뒤 public exposure와 canvas 정리를 검증했습니다.{ canvases: 0, exposed: false }{ canvases: 0, exposed: true }dispose()호출로 제거되었지만 application 자체가pagehide에서 viewer를 해제하거나window.__viewerreference를 제거하지 않았습니다.구현 방법: application entrypoint에 일회성
pagehidecleanup을 등록하고dispose()후 tooling reference를 삭제합니다. 동일 test에서 cleanup 뒤 추가dispose()가 필요 없는 상태를 GREEN으로 확인합니다.RED 7 — decoder staging permission 재현성
tests/decoder-staging.test.ts를 추가해 installed Three.js/web-ifc 원본과 staged WASM의 SHA-256 일치 및 실행 권한 부재를 검증했습니다.073(0o111)npm package 원본 mode를
cpSync/copyFileSync가 그대로 보존하여 public decoder가 executable file로 생성됩니다. staging 후 directory는0755, 모든 제공 file은0644로 정규화하도록 수정하고 clean staging 결과를 재검증합니다.GREEN 4 — subpath, lifecycle, decoder staging
publicAssetUrl()unit: 1 passed/viewer-3d/build/preview E2E: Draco 및 IFC decoder가 base 아래에서 응답, failed request 없음pagehidelifecycle E2E: canvas 제거와window.__viewerreference 삭제 통과pageerror0건첫 전환 test는 2D가 자동 sample을 여는 것으로 잘못 가정해
ready상태에서 실패했습니다. 실제 public UI 흐름인Sample DWGclick으로 test setup을 바로잡은 뒤 10회 왕복이 통과했습니다.RED 8 — root verify test boundary/type environment
전체 검증에서 두 가지 repository-level failure를 확인했습니다.
npm run typecheck:ImportMeta.envtype 부재 (src/runtimeBase.ts)npm run test:unit: Vitest가tests/e2e/*.spec.ts까지 수집하여 Playwright의test()를 잘못 실행, 4 suite 실패개별 E2E와 unit behavior는 GREEN이지만 root 단일 진입점의 test boundary가 불명확한 구성 문제입니다. 3D tsconfig에 Vite client type을 명시하고, Vitest include를
tests/**/*.test.ts로 제한한 뒤 전체 명령을 다시 실행합니다.실제 구동 이미지 증거
고정 viewport
1440×900, DPR 1, 실제 Chrome에서 evidence E2E 3/3 통과 후 Gitea attachment API로 업로드했습니다.Viewer2D — DWG / 7,309 entities
Viewer2D — DXF / 6 entities
Viewer3D — Three.js
0.185.1GLBViewer3D — Three.js
0.185.1double-precision PLY normalizationSHA-256:
aff6acc4458c3d1ca2ce595e9fce1422ed3f8fa450e9321ea46e218a39d9983815517fb580844ee0498698b8b22b595eed84b0e90b43d9cd26bed7b02ebf5b8e346cd31b8accf4df71b35e5a330cb7c78ad0f2754cf1bec995851e107728de1f13fe36425888c91aa59d534b1d5f1e8ed636ec1d8f6c24fa08f7cbb408fa7e3a최종 clean verify
커밋:
cadbd5f fix: resolve workspace integration blockers (#5)npm ci— 88 packages 재설치, decoder 재staging, 0 vulnerabilitiesnpm ls three @types/three— 2D app / 3D app / viewer2d package 모두three@0.185.1단일 deduped instance,@types/three@0.185.1npm run verify— 성공npm audit --audit-level=low— 0 vulnerabilitiesgit diff --check— 통과남은 fixture coverage gap은 사용자 제공 대기 중인 redistributable KTX2 GLB와 명시적 Z-up FBX입니다. 기존 FBX 및 Draco GLB는 통과했지만 이 두 edge fixture를 받기 전에는 해당 세부 조합을 검증했다고 주장하지 않습니다.
RED 9 — parser/result seam을 package 내부로 이동
최종 Spec RED 리뷰에서 sample이
parseCad와CadParseResult를 직접 조합해 rawviewer.load(result)를 호출하는 얕은 facade가 Blocker로 지적됐습니다.먼저 public contract test를
loadCad(viewer, input) -> { entityCount }로 변경했습니다.TypeError: loadCad is not a function구현 방법:
parseCad를 package 내부 함수로 내리고loadCad가 parse→viewer.load→resize를 수행한 뒤 UI에 필요한 최소 summary만 반환하도록 합니다. sample에서CadParseResult및 rawviewer.load의존을 제거합니다.RED 10 — WebGL context lifecycle 계측
RED 리뷰의 지적에 따라 단순 canvas count 대신
requestAnimationFrame, window/canvas listener, 실제 WebGL context 상태를 browser init script로 계측했습니다.contextsLost: false**로 실패ThreeDViewer.dispose()는renderer.dispose()와 canvas 제거만 수행하고 context를 명시적으로 반환하지 않습니다. idempotent guard와renderer.forceContextLoss()를 추가해 동일 E2E를 GREEN으로 전환합니다.GREEN 5 — 최종 RED Blocker 보완
loadCad(viewer, input) -> { entityCount }unit GREEN. sample에서parseCad,CadParseResult, rawviewer.load(result)의존 제거/viewer-2d/E2E GREEN:BasicSample.dwg, bundled acadrust WASM,NanumGothic-Regular.ttf가 모두 subpath 아래에서 200 응답하고 7,309 entities renderingisContextLost() === truecontextsLost: false를 확인한 뒤 idempotent guard와renderer.forceContextLoss()를 추가해 GREEN 전환Heap 절대량은 GC/browser noise 때문에 pass/fail threshold로 두지 않았고, 직접 소유 자원(RAF/listener/context/reference)을 deterministic contract로 검증했습니다.
보완 커밋 및 verify
커밋:
8ae7c45 fix: close final viewer integration gaps (#5)npm run verify최종 결과:RED팀 최종 리뷰에서 현재 코드 범위 blocker로 분류한 parser seam, 2D subpath, WebGL context lifecycle은 이 커밋에서 해소했습니다.