사이트: 데모와 전체 glue 코드를 탭형 워크벤치에서 함께 보여준다

[developer-1px]

Goal Anchor

• Outcome: 모든 데모에서 실행 결과와 그 데모가 부담하는 실제 전체 코드를 같은 워크벤치에서 검토할 수 있다.
• Done: 가장 왼쪽 Demo 탭과 demo-owned 파일 탭들이 표시되고, 각 파일 탭에서 실제 파일 전문을 볼 수 있다.
• Don’t: 패키지 내부 구현, 문서 사이트 chrome, 파일 탐색기, 손으로 복제한 예제 코드, 부분 발췌를 포함하지 않는다.

Success Evidence

• 각 데모의 Demo 탭에서 기존 기능이 그대로 동작한다.
• 파일 탭의 내용이 대응하는 저장소 파일과 일치한다.
• demo-owned helper로 복잡도를 옮기면 그 helper도 별도 탭에 나타난다.
• react, @tanstack/*, @interactive-os/* 패키지 내부 파일은 탭에 나타나지 않는다.
• 각 소스 파일은 일부 구간이 아니라 전문으로 표시된다.

Target Structure

DemoWorkbench
├── TabList
│   ├── Demo
│   └── SourceFile × N
└── ActivePanel
    ├── DemoPanel
    │   └── existing interactive demo
    └── SourcePanel
        ├── source path
        └── full CodeBlock

Behavior Contract

• Demo 탭 선택 → 기존 인터랙티브 데모 표시
• 파일 탭 선택 → 해당 실제 파일의 전체 코드 표시
• demo-owned behavioral import 발견 → source tab 집합에 포함
• package import 또는 문서 chrome 경계 도달 → import 추적 중단

[developer-1px]

작업 계획

고정 계약

• Outcome: 모든 데모에서 실행 결과와 그 데모가 부담하는 실제 전체 코드를 같은 워크벤치에서 검토할 수 있다.
• Done: 가장 왼쪽 Demo 탭과 demo-owned 파일 탭들이 표시되고, 각 파일 탭에서 실제 파일 전문을 볼 수 있다.
• Don’t: 패키지 내부 구현, 문서 사이트 chrome, 파일 탐색기, 손으로 복제한 예제 코드, 부분 발췌를 포함하지 않는다.

단계

1. 기존 데모 엔트리와 site-owned behavioral import 경계를 목록화한다.
2. 실제 파일 전문을 받는 공용 DemoWorkbench와 탭 접근성 계약을 구현한다.
3. 모든 Demo·Widget·Adapter·Connector 화면을 워크벤치에 연결한다.
4. 단위 테스트, 브라우저 테스트, typecheck, build와 실제 화면으로 검증한다.

제외

• package 내부 소스 탭
• 문서 사이트 chrome 소스 탭
• 파일 탐색기 또는 폴더 트리
• 손으로 복제하거나 일부만 발췌한 코드

검증

• 탭 키보드·ARIA 동작과 파일 전문 일치 단위 테스트
• 대표 데모의 실행/소스 전환 브라우저 테스트
• npm run typecheck, npm run build

위험

• demo-owned 코드와 문서 chrome의 경계가 누락되면 복잡도가 숨겨질 수 있다. 상대 import graph와 실제 데모 책임을 대조해 검토한다.
• 파일 수가 많은 데모는 탭이 길어질 수 있다. 가로 스크롤을 허용하되 파일을 숨기지 않는다.

계약 변경이나 보류 목표는 없다.

[developer-1px]

구현 진행

완료된 관찰 지점

• DemoWorkbench가 가장 왼쪽 Demo와 실제 source 파일 탭을 렌더링한다.
• source entry에서 상대 import/export를 따라 demo-owned closure를 자동 구성하고 shared/ui, 공용 frame, package import에서 멈춘다.
• Demo 패널은 source 탭을 보는 동안에도 mount 상태를 유지해 편집 상태가 초기화되지 않는다.
• Document와 Database 대표 경로에서 실제 파일 전문, package import 표시, 다중 파일 탭을 브라우저로 확인했다.

검증 완료

• site typecheck
• site unit tests: 34개 통과
• site production build
• 전체 browser tests: 66개 통과

현재 최전선

전체 diff와 source boundary를 감사한 뒤 commit·push·PR 생성으로 진행한다. 차단 사항과 계약 변경은 없다.

[developer-1px]

PR 생성 및 최종 검증

• PR: 사이트: 데모와 전체 glue 코드를 탭형 워크벤치에서 함께 보여준다 #461
• commit: 22148e8b
• 완료: 모든 공개 인터랙티브 데모에 Demo + 실제 source 파일 탭 워크벤치를 연결했다.
• 완료: demo-owned 상대 import closure를 포함하고 package·문서 chrome 경계에서 추적을 중단한다.
• 완료: source 전환 뒤에도 Demo mount와 선택 상태가 유지된다.

검증 보고

• npm run typecheck -w @interactive-os/json-document-site 통과
• npm test -w @interactive-os/json-document-site — 34개 통과
• npm run build -w @interactive-os/json-document-site 통과
• npm run browser:test — 66개 통과
• Chrome 실제 경로 /demo에서 DocumentDemoRoute.tsx 전문과 package import를 확인하고 Demo 선택 상태 유지 및 console error 0건을 확인
• push 전 root TypeScript build hook 통과

남은 구현 항목, 차단 사항, 계약 변경은 없다. 병합은 별도 승인 전까지 진행하지 않는다.

[developer-1px]

CI 보정

첫 CI에서 source raw module을 공통 chunk에 eager-load해 문서 route 전환 단위 테스트가 제한 시간 안에 렌더링되지 못하는 회귀를 확인했다. source closure 의미는 유지하면서 현재 데모 경로의 파일만 lazy-load하도록 수정했다.

• Demo 화면과 일반 문서 route는 source 다운로드를 기다리지 않고 즉시 렌더링
• source 탭은 현재 demo-owned closure만 동적으로 로드
• CI와 동일한 site typecheck, 전체 unit test, Pages build/evaluate/HTTP smoke 통과
• 변경 후 workbench 브라우저 acceptance 통과

계약 변경은 없다.

[developer-1px]

최종 상태

• PR #461의 최종 HEAD 5523e560
• GitHub Actions Package, Site 모두 통과
• Site job에서 typecheck, 34개 unit test, Pages build/evaluate/HTTP smoke, 66개 browser test 통과
• source asset은 실행 route와 경쟁하지 않도록 파일 탭 선택 시점에만 로드

완료 조건 전부 충족, 남은 구현·차단·계약 변경 없음. PR은 병합 승인 전 상태로 열어 둔다.

[developer-1px]

후속 레이아웃 보정

사용자 확인에 따라 demo route의 페이지 소유권을 바로잡았다.

• page shell이 breadcrumb를 렌더링하고 그 아래에 DemoWorkbench를 배치
• demo component의 PageHeader에는 breadcrumb를 주입하지 않음
• workbench tab strip을 viewport 상단에 sticky 처리
• 가로 탭 overflow와 sticky를 분리해 긴 파일 목록에서도 고정 유지

검증: site unit 34개, Pages build/evaluate/HTTP smoke, browser 67개 통과. 계약의 source 공개 범위와 Demo 상태 보존은 변경하지 않았다.

[developer-1px]

데모와 문서의 책임 경계를 추가로 분리했습니다.

• breadcrumb, 제목, 설명, 고양이 일러스트, 상태/설치/연결 설명은 페이지 문서 영역에 유지
• 실제 조작 가능한 제품 surface만 DemoSurface/DemoWorkbench 안에 배치
• 데모 컴포넌트가 라우터를 알지 않도록 페이지 셸에서 source manifest를 Context로 전달
• 기존 sticky 탭과 demo/source 전환 시 상태 보존 유지

검증:

• npm run typecheck -w @interactive-os/json-document-site
• npm test -w @interactive-os/json-document-site (34개 통과)
• npm run site:verify:pages
• npm run browser:test에서 최초 66/67 통과 후, Connector의 문서용 Live demo 레이블을 탭 밖에 복원
• 실패했던 Connector 순서 테스트 재실행 2/2 통과
• push 전 전체 TypeScript build 통과

커밋: e9c15576