feat(preview): 문서 속 이미지를 프리뷰에 렌더한다 (M10)

[Bori-github]

요약 / 의도

문서에 넣은 이미지를 프리뷰에 렌더한다. 파일 하나만 연 경우에도 문서와 같은 폴더의 이미지를 읽는다. VS Code도 작업 폴더에 속하지 않은 마크다운을 미리 볼 때 같은 폴더를 읽는다(getMarkdownLocalResourceRoots).

범위

이번에 한 것

• 로컬 이미지는 Tauri asset 프로토콜로 읽는다. 파일을 허용하는 경우 그 파일이 있는 폴더를 asset 스코프에 등록한다(부모가 파일시스템 루트인 경우 그 파일만).
• 상대 경로는 문서가 있는 폴더, /는 연 폴더 기준으로 해석한다. 기준 폴더가 없는 경우 그대로 둔다.
• img[srcset]·source[srcset]을 후보마다 해석하고, 후보가 asset:으로 시작하는 경우 버린다.
• 못 찾은 이미지는 그 자리에 alt 텍스트를 세우고, 이미지가 도착하면 스크롤 동기화가 블록을 다시 잰다.
• 눈으로 판정하는 examples/이미지-예시.md를 만들고, 실앱 E2E에 파일만 연 경우를 더했다.
• 브라우저 테스트의 간헐 실패를 없앴다. 원인은 이미지와 무관하다 — Vite가 실행 중간에 의존성을 다시 묶으며 페이지를 리로드했다.

의도적으로 안 한 것 / 후속

• 연 폴더에도 문서 폴더에도 없는 이미지 — 다이얼로그로 이미지 폴더를 추가 허용할지가 결정 대상이다(열린 결정에 기록).
• 원격 이미지를 끄는 설정 — CSP가 정적이라 렌더 단계에서 따로 제거해야 한다(기존 열린 결정).
• 파일 커맨드의 범위는 넓히지 않았다. 넓어진 것은 이미지 읽기뿐이다.

주요 변경점

• 프론트(FSD): 연 폴더를 workspace 상태에서 읽어 프리뷰로 넘긴다.
• 마크다운(packages/markdown): 기준 폴더를 둘로 나누고, sanitize 뒤에 src·srcset을 바꾼다.
• Rust(src-tauri): FileScope의 허용·거부를 asset 스코프에도 등록한다. assetProtocol 설정을 객체 형태로 바꿨다.
• 스크립트/툴링: NORII_E2E_SCOPE_FILE로 파일 하나만 연 상태를 만든다(webdriver 빌드 전용). optimizeDeps.include로 테스트 중 페이지 리로드를 막는다.
• 문서(.claude): 읽는 폴더·경로 해석·해석하는 속성·권한·위험을 갱신했다.

설계 · 결정

• 파일을 허용하는 경우에만 두 스코프가 갈라진다. 파일 커맨드는 그 파일만, asset 스코프는 그 파일이 있는 폴더를 읽는다. 이 차이의 위험은 security.md#이미지가 소유한다.
• /는 연 폴더 기준이다. 디스크 루트 기준으로 해석하는 경우 같은 문서가 GitHub·VS Code와 다른 파일을 가리킨다.
• assetProtocol.scope는 객체로 적고 requireLiteralLeadingDot: false를 넣는다. unix 기본값이 true라 생략하면 점으로 시작하는 폴더의 파일을 파일 커맨드는 통과시키고 이미지만 거부한다.
• 문서와 달라진 점: 없다. 문서를 먼저 갱신하고 코드를 맞췄다.

flowchart LR
  A["FileScope.allow(경로)"] --> B{폴더인가}
  B -- 예 --> C["파일 커맨드: 하위 트리<br/>asset: 하위 트리"]
  B -- 아니오 --> D{부모가 루트인가}
  D -- 아니오 --> E["파일 커맨드: 그 파일만<br/>asset: 부모 폴더의 하위 트리"]
  D -- 예 --> F["둘 다 그 파일만"]

Loading

검증 (체크가 아니라 값으로)

• mise run check: 통과 — desktop 62파일 435개 · markdown 113개 · editor 28개 · rust 88개. 차가운 node_modules/.vite로도 통과.
• TDD(신규 기능·커맨드·상태 전이·파서는 실패 테스트 먼저): 예 — 스코프 3개, 경로 해석 3개, srcset 5개, 앱 배선 2개를 먼저 실패시키고 구현했다.
• 실앱 E2E (mise run dev-webdriver → mise run e2e): 통과 23/23. 이미지 시나리오 둘이 문서 폴더 기준·연 폴더 기준·srcset 후보·점으로 시작하는 폴더·없는 파일·읽을 수 없는 경로·파일만 연 경우를 덮는다.
• 번들 크기: N/A — 릴리스 빌드를 만들지 않았다.
• 자동 검증 불가 항목: 서명된 배포 빌드에서 http: 이미지가 막히는지. 개발 서버는 CSP를 붙이지 않아 개발 빌드에서 확인되지 않는다.

관련 문서 (단일 출처)

• .claude/docs/preview-strategy.md — 어느 폴더의 이미지를 읽는가 · 경로 해석 · 해석하는 속성
• .claude/docs/rust-commands.md — 권한(asset 프로토콜)
• .claude/docs/security.md — 이미지가 읽을 수 있는 경로와 남는 위험
• examples/이미지-예시.md — 눈으로 판정하는 예시

리뷰 포인트 / 위험 지점

• scope.rs의 allow() 파일 분기 — 두 스코프가 갈라지는 유일한 자리다.
• render.ts의 parseSrcset — 후보 경계를 URL 뒤의 쉼표로만 판정한다.
• lib.rs의 NORII_E2E_SCOPE_FILE — webdriver 피처에서만 컴파일된다.

체크리스트 (프로젝트 규칙)

• 동작을 바꾸는 변경은 계약 문서를 먼저/같은 커밋에서 갱신
• docs-drift 통과 (tech-stack 버전 ↔ 핀, Rust 커맨드 등재)
• 비목표 경계(.claude/rules/non-goals.md)를 넘지 않음 — 인덱싱·DB가 생기지 않는다
• 성능 규칙(뷰포트 한정 데코레이션·프리뷰 디바운스·번들 목표) 준수
• 커밋·PR 제목이 Conventional Commits(한국어)

스크린샷 / 데모

norii-.mov

E2E 시나리오 둘을 그대로 녹화했다. 왼쪽 소스, 오른쪽 프리뷰 — 문서 폴더 기준·연 폴더 기준·srcset 2배 후보가 뜨고, 이어서 폴더 없이 파일만 연 문서의 옆 이미지가 뜬다.

마일스톤 / 비고

M10(문서 속 이미지). 브라우저 테스트 간헐 실패 수정은 이 마일스톤과 무관하지만 mise run check를 무작위로 실패시켜 함께 담았다.