Gallery 보기 전체 가이드

Gallery는 이미지가 많은 Markdown 문서를 앨범처럼 훑고, 비교하고, 정리하는 projection이다. 사진 데이터베이스를 따로 만들지 않는다. H1, H2와 Markdown 이미지 줄이 계속 정본이며 Gallery에서 지원하는 편집도 같은 Markdown을 source-safe하게 다시 쓴다.

이 페이지가 검증하는 기능 ID는 VW-40, VW-41, VW-42, VW-43, VW-44, VW-45, VW-46, VW-47, VW-48, VW-49다.

이 장을 끝내면 다음을 할 수 있다.

• H1·H2·독립 이미지 줄로 Gallery 문서를 만든다.
• Source에서 Gallery로 전환하고 앨범 보기와 전체 보기를 오간다.
• 썸네일, 대표 이미지와 lightbox를 사용한다.
• 앨범과 이미지를 추가·이동·편집·삭제하면서 Markdown 변화 범위를 판단한다.
• 누락된 대체 텍스트, 제목, 중복 이미지, 빈 앨범과 로드 오류를 찾는다.
• Gallery 스타일과 session-only 상태를 구분한다.
• 저장된 Gallery를 Slide와 Hugo 출력에서 재사용한다.

1. 실습 Binder 준비

• Gallery 실습 안내
• Gallery 원문
• 실습 자산 폴더

gallery-lab 폴더를 내려받아 Scope 또는 Binder로 연다. 01_gallery-tour.md와 Resources/의 상대 위치를 유지해야 이미지 경로가 그대로 해석된다.

실습 문서에는 정상 앨범 세 개와 빈 앨범 하나가 있다. 일부 이미지에는 title 또는 alt가 없고 같은 이미지가 다른 앨범에서도 사용된다. 이는 진단 기능을 실제로 확인하기 위한 의도적인 입력이다.

2. Gallery가 읽는 Markdown 문법

최소 구조는 다음과 같다.

# 문서는 자산이다 — Gallery 실습

## 입력 게이트

![여러 입력이 모이는 장면](Resources/input-gate.svg "다양한 입력")

![Markdown 원문 자산](Resources/markdown-asset.svg "Markdown 자산")

## 표현과 투영

![같은 원문의 여러 보기](Resources/projection-fan.svg "다양한 Projection")

이미지를 문단 안에 섞거나 H2 밖에 두면 Gallery 앨범 이미지로 인식되지 않을 수 있다. 한 줄에 이미지 하나를 독립적으로 작성하는 것이 가장 예측 가능하다.

3. Source에서 Gallery로 전환

1. 01_gallery-tour.md를 연다.
2. 원문에서 H1 하나, H2 네 개와 이미지 여덟 줄을 확인한다.
3. 문서 헤더의 보기 선택기를 연다.
4. Gallery를 선택한다.
5. 화면 상단에서 앨범 수와 이미지 수를 확인한다.

영상은 실제 Glif 앱에서 Source를 확인하고 Gallery로 전환한 뒤, Gallery 정보 pane에서 앨범 → 전체로 바꾸는 과정을 보여 준다. 파란 pointer와 하단 설명은 조작 위치와 검증 의도를 표시한다.

4. 앨범 보기 읽기

앨범 보기는 한 H2 section에 집중한다.

• 큰 stage에는 현재 선택 이미지가 표시된다.
• 좌우 이동 버튼과 썸네일로 같은 앨범의 이미지를 넘긴다.
• 첫 번째 Markdown 이미지 줄이 대표 이미지다.
• 앨범 제목과 이미지 수는 현재 source에서 파생된다.
• 빈 H2는 빈 앨범으로 유지되며 조용히 삭제되지 않는다.

대표 이미지는 별도 cover flag가 아니다. 다른 이미지를 대표 이미지로 설정하면 그 이미지 줄을 해당 H2의 첫 이미지 위치로 옮긴다. 화면 의미와 Markdown 순서가 갈라지지 않게 하기 위한 규칙이다.

5. 전체 보기에서 문서 전체 훑기

1. Gallery와 연결된 정보 pane을 연다.
2. 탐색 → 보기에서 전체를 선택한다.
3. 앨범이 H2 순서로, 각 tile이 이미지 줄 순서로 나타나는지 확인한다.
4. 검토 대기가 빈 앨범 tile로 남는지 확인한다.
5. tile의 원문 이동 action으로 해당 이미지 줄을 열 수 있는지 확인한다.

전체 보기는 문서 전체를 빠르게 scan하는 contact sheet다. 독립된 content store나 임의 grid 좌표를 만들지 않으며, album과 image의 순서는 여전히 Markdown이 소유한다.

큰 Gallery에서의 동작

Gallery는 화면 밖 album section에 content-visibility containment를 적용하고, resolve된 URL·자연 크기·load error를 session-derived 상태로만 유지한다. 2026-08-02 로컬 브라우저 측정에서는 26개 채워진 앨범 + 빈 앨범 2개, 이미지 tile 1,040개를 다음 조건으로 확인했다.

같은 fixture의 source-derived model 측정에서는 3,840개 이미지까지 parse p95 19.292ms, overview model p95 0.974ms를 관측했다. 이 값은 현재 개발 장치의 회귀 근거이지 모든 장치에 대한 성능 보장은 아니다. 재검증 명령은 pnpm run measure:gallery-large-album과 pnpm run measure:gallery-browser다.

6. Lightbox로 이미지 검사

이미지 stage 또는 전체 보기 tile에서 이미지 미리보기 열기를 선택한다.

• 이전/다음으로 source 순서를 이동한다.
• 확대, 축소, 맞춤으로 재설정을 사용한다.
• 확대 상태에서는 이미지를 pan할 수 있다.
• metadata row에서 현재 위치와 원문 이동 action을 확인한다.
• Esc 또는 닫기 버튼으로 원래 focus 위치로 돌아간다.

앨범 보기의 이전/다음은 현재 앨범 안에 머문다. 전체 보기에서 연 lightbox는 전체 문서의 flattened source 순서로 앨범을 넘어 이동한다.

7. 앨범 편집과 Markdown 변화

Gallery에서 가능한 album 작업은 다음과 같다.

작업 적용 전에 원문이 바뀌면 Glif는 오래된 source span에 억지로 쓰지 않는다. 원문이 변경되었습니다 상태를 표시하고 해당 원문을 다시 연 뒤 사용자가 최신 source에서 다시 시도하게 한다.

8. 이미지 추가·편집·이동·삭제

이미지 삭제는 Resources/의 물리 파일을 삭제하지 않는다. 다른 문서나 이미지 줄이 같은 파일을 참조할 수 있기 때문이다. 파일 자체를 정리하려면 참조 범위를 별도로 검토한다.

업로드 도중 Markdown 저장이 실패하면 생성한 파일을 rollback하려고 시도한다. rollback까지 실패했다는 오류가 나오면 원문과 Resources/를 모두 다시 확인한 뒤 재시도한다.

로컬 이미지를 Binder에 업로드

파일 선택기는 plugin renderer가 아니라 Glif host가 소유한다. Gallery 정보 pane에서 다음 순서로 실행한다.

1. 이미지 추가 section을 연다.
2. 대상 앨범에서 이미지 줄을 받을 H2를 선택한다.
3. 이미지 업로드를 누르고 로컬 이미지 파일을 선택한다.
4. 선택 파일이 Binder의 Resources/에 복사됐는지 확인한다.
5. 대상 H2에 /Resources/<파일명> Markdown 이미지 줄이 추가됐는지 확인한다.

영상은 빈 검토 대기 앨범을 대상으로 선택한 뒤 파일을 업로드한다. 실증 결과 이미지 줄은 8개에서 9개로 늘고, 원문 SHA-256이 의도적으로 달라졌으며, Resources/에는 새 파일 하나가 만들어졌다. 보기 전환·검색·lightbox 검사만 수행한 앞 단계에서는 원문 SHA-256이 바뀌지 않았다.

9. 검색과 진단으로 정리할 곳 찾기

Gallery 정보 pane의 탐색 section은 현재 Markdown과 runtime asset 상태에서 다음을 파생한다.

• 대체 텍스트 없음
• 이미지 제목 없음
• 같은 앨범 안 중복 이미지
• 앨범 간 중복 이미지
• 빈 앨범
• runtime 이미지 로드 오류

검색 상자에는 앨범 제목, alt, title 또는 path 일부를 입력한다. 결과를 선택하면 Gallery의 해당 이미지가 강조되고, 원문 줄 열기 action으로 정확한 source 위치로 돌아갈 수 있다.

영상은 전체 보기의 tile에서 lightbox를 열어 확대하고, 닫은 뒤 재사용을 검색해 일치하는 앨범과 이미지를 찾는 실제 상호작용을 보여 준다.

중복 정리 action은 사용자가 선택한 중복 occurrence의 Markdown 이미지 줄 하나만 삭제한다. 전체 Binder의 파일을 자동 dedupe하거나 물리 resource를 삭제하지 않는다.

10. Gallery 스타일 저장

Gallery 정보 pane에서 다음 presentation 설정을 조정할 수 있다.

• 보기: 앨범 / 전체
• 제목 위치·정렬·강조
• 밀도와 정렬
• 앨범 표면, 모서리 반경과 강조 색상
• 뷰어 맞춤: 맞춤 / 채움
• 썸네일 표시 여부와 크기

이 값은 renderer-neutral Gallery style profile로 저장된다. 다음 항목은 저장하지 않는다.

• parsed album/image model과 source span
• 현재 선택한 이미지
• 검색어와 진단 filter
• lightbox zoom, pan과 focus
• resolve된 runtime URL, 자연 크기와 load error cache

문서를 닫았다 다시 열었을 때 보기와 presentation 설정은 복원될 수 있지만, 이전 검색어와 zoom 위치가 그대로 돌아오는 것을 기대하면 안 된다.

11. Slide와 Hugo에서 재사용

Gallery는 문서의 저장 가능한 기본 보기다. publish materialization은 같은 Markdown에서 album과 image model을 다시 만든다.

• 문서 수준: 저장된 Gallery view를 Hugo projection으로 materialize
• Slide embed: glif-view gallery 또는 glif-gallery fence로 같은 source-derived Gallery를 포함
• style transport: 지원되는 features.gallery.projection.style 표현 값만 전달
• resource: 기존 publish resource materialization pipeline을 사용

publish용 Gallery JSON이나 screenshot을 두 번째 content 정본으로 만들지 않는다. 깨진 이미지와 누락 resource도 조용히 제거하지 않고 fallback 또는 diagnostic으로 드러내야 한다.

실제 Hugo Gallery 출력

Hugo Gallery 출력 예제 열기는 이 장의 예제 resource를 문서 수준 Gallery projection으로 materialize한다. 저장된 overview layout, tint card surface와 이미지 7개가 실제 Hugo renderer에 전달된 결과다.

실제 Slide 내 Gallery 출력

Slide Gallery embed 출력 예제 열기는 glif-view gallery fence를 Slide 안에서 다시 사용한다. Slide가 이미지 사본을 갖는 것이 아니라 fence 안 Markdown을 Gallery renderer에 넘기며, 실제 DOM에서도 Slide view block 안에 Gallery projection이 중첩된다.

실증 결과와 경계

VW-48은 같은 Gallery lab resource를 Hugo 문서 수준 projection과 Slide embedded Gallery로 각각 materialize해 확인했다. 두 출력 모두 모든 이미지가 로드됐고, 원본 resource path를 유지했으며, 가로 넘침과 console warning/error가 없었다. 캡처는 1200×800 browser viewport에서 projection subtree만 분리해 만들었고 검증 결과는 gallery-publish-evidence.json에 기록한다. VW-49의 대규모 corpus 경계는 위의 1,040 tile browser 측정과 3,840 image source-derived model 측정으로 별도 확인했다.

12. 키보드와 접근성

• Gallery 전환은 보기 선택기에서 키보드로 선택할 수 있다.
• 썸네일, 전체 보기 tile과 원문 이동 action은 focus 가능한 control이다.
• lightbox는 dialog로 노출되며 focus를 내부에 유지하고 닫을 때 이전 control로 돌려보낸다.
• Esc로 lightbox를 닫는다.
• 이전/다음과 zoom action은 accessible name을 가진다.
• alt는 단순 꾸밈이 아니라 이미지의 접근 가능한 설명이므로 진단에서 누락을 먼저 정리한다.

13. 문제 해결

Gallery를 선택할 수 없다

• H2 아래에 독립된 Markdown 이미지 줄이 있는지 확인한다.
• 예제처럼 한 앨범에 이미지 두 개 이상을 두면 shape 판단이 명확하다.
• 이미지가 HTML tag나 일반 링크로만 적혀 있지 않은지 확인한다.

이미지를 불러오지 못한다

• Markdown 파일 기준 상대 경로인지 확인한다.
• Binder 밖 경로나 이동된 resource를 참조하는지 확인한다.
• 정보 pane의 로드 오류와 원문 줄을 함께 확인한다.
• 오류 이미지를 자동 삭제하지 말고 올바른 path로 수정한다.

변경이 적용되지 않는다

• read-only 문서나 Binder 밖 preview인지 확인한다.
• 다른 편집으로 source revision이 바뀌었다면 원문을 다시 연다.
• 빈 album title과 빈 image path는 저장할 수 없다.
• 첫/마지막 위치에서 더 이동하려는 boundary 작업은 거절된다.

스타일이 복원되지 않는다

• 문서가 Binder에 속하고 .glif/profiles/v1/ 아래 문서별 profile을 쓸 수 있는지 확인한다.
• .glif/projections.json은 문서별 기본 보기 선택을 기록하며, Gallery 세부 style profile과 역할이 다르다.
• invalid profile 값은 기본값으로 복구되며 Markdown에는 기록되지 않는다.
• 검색어·선택·zoom은 의도적으로 session-only다.

14. 완료 기준

• H1·H2·독립 이미지 줄의 역할을 설명할 수 있다.
• Source와 Gallery 사이를 전환했다.
• 앨범 보기와 전체 보기에서 Markdown 순서가 유지됨을 확인했다.
• lightbox에서 이전/다음, 확대/축소/reset과 닫기를 사용했다.
• album 또는 image metadata를 바꾸고 Markdown 변화 범위를 확인했다.
• 대표 이미지 설정이 첫 이미지 줄 이동임을 확인했다.
• 누락 alt/title, 중복, 빈 앨범과 load error의 차이를 확인했다.
• style profile과 session-only state를 구분했다.
• 삭제가 물리 resource 삭제 권한을 갖지 않음을 확인했다.
• Slide/Hugo 결과가 같은 Markdown에서 파생됨을 확인했다.