MDX Input
  ↓
Stage 0  Normalize
  ↓
Stage 1A/1B  AI Meaning Analysis
  ↓
Phase Y  Group / Schema / Recipe Parsing
  ↓
Stage 1.5a  Space Allocation
  ↓
Stage 1.7  Block Selection
  ↓
Stage 1.8  Fit / Measure / Adjustment
  ↓
Stage 2  Assemble final slide HTML
  ↓
Stage 4  Validate with Selenium / Vision
  ↓
Stage 5  Save final artifacts

핵심 원칙은 다음과 같습니다.

source of truth는 normalized.sections
문서명 하드코딩보다 shape, schema, recipe, tag를 우선한다
흐름의 우선순위는 구조 -> payload -> layout -> fit
popup / detail은 overflow를 덮는 임시 장치가 아니라 메인 요약 + 상세 보기의 표현 계약이다

타입 구조

현재 메인 타입 선택은 사실상 Type A와 Type B입니다.

Type A

본문 외에 sidebar, reference, 부록성 영역이 함께 필요한 슬라이드
현재는 Type B보다 덜 닫혀 있고, AI 생성 + renderer 경로 비중이 더 큼

Type B

top / bottom 같은 본문 zone 조합으로 해결되는 슬라이드
현재 가장 안정적인 메인 경로
최근 구조화 작업은 대부분 이 Type B 경로를 중심으로 진행됨

Type B' / B''

역사적으로 실험/호환 과정에서 나온 변형 경로
일부 legacy 코드와 과거 산출물에 흔적이 남아 있음
현재 메인 1급 타입이라기보다, 과거 흐름과 검증된 표시 계약을 담고 있는 보조 경로에 가까움

단계별 파이프라인

단계	담당	주요 파일	하는 일	주요 산출물
Stage 0	코드	`src/mdx_normalizer.py`	MDX를 정규화하고 sections, tables, images, popups로 분리	`NormalizedContent`
Stage 1A	AI (Kei/Opus)	`src/kei_client.py`	title, core message, topic, 초기 layout 힌트 추출	`Analysis`, `Topic[]`
Phase Y	코드	`src/pipeline.py`, `src/section_parser.py`	`normalized.sections` 기반으로 group, schema, recipe, zone/page_structure 결정	`PageStructure`, `mdx_sections`
Stage 1B	AI (Kei/Opus)	`src/kei_client.py`	topic별 relation, source_data, 표현 힌트 보강	보강된 `Topic[]`
Stage 1B-ST	AI (Kei/Opus)	`src/kei_client.py`	structured_text 생성	`Topic.structured_text`
Stage 1.5a	코드	`src/space_allocator.py`	zone / container 크기, preset, font hierarchy 계산	`containers`, `font_hierarchy`
Stage 1.7	코드	`src/block_reference.py`, `templates/catalog.yaml`	tag_match, schema_match, fallback 기준으로 block 선택	`references`
Stage 1.8	코드 + Selenium + 일부 AI	`src/pipeline.py`, `src/slide_measurer.py`	fit 측정, overflow 확인, 재배분, 보정	`fit_result`, `measurement`
Stage 2	코드 중심	`src/block_assembler.py`	Type B 기준 slide-base + block template + payload 조립	`generated_html`
Stage 3	코드	`src/renderer.py`	Type A 쪽 Jinja/renderer 조립, Type B는 대체로 생략	`rendered_html`
Stage 4	코드 + Vision AI	`src/slide_measurer.py`, `src/kei_client.py`	Selenium overflow 측정, screenshot, vision quality 평가	`measurement`, `quality_score`
Stage 5	코드	`src/pipeline.py`	`final.html`, `final_context.json`, popup/detail html 저장	run 산출물

현재 메인 실행 경로

Type B 메인 경로

지금 실전에서 가장 중요한 경로는 아래입니다.

Stage 0에서 MDX를 정규화
Stage 1A / 1B에서 AI가 문서 의미와 topic 추출
Phase Y에서 코드가 normalized.sections를 읽고 page_structure를 다시 생성
Stage 1.7에서 block / recipe 후보 선택
Stage 1.8에서 fit / overflow 검증
Stage 2에서 assemble_slide_html_final()로 최종 HTML 조립
Stage 4 / 5에서 측정과 산출물 저장

Type B의 핵심 파일은 아래입니다.

src/pipeline.py
src/section_parser.py
src/block_reference.py
src/block_assembler.py
src/space_allocator.py
templates/catalog.yaml

Type A 경로

Type A는 현재도 살아 있지만, Type B만큼 단단하게 닫힌 상태는 아닙니다.

AI 생성 비중이 더 큼
src/renderer.py 의존도가 더 큼
sidebar / reference 구조를 포함하는 문서에서 의미가 큼

schema -> recipe -> block

최근 구조화에서 가장 중요한 변화 중 하나는 schema -> recipe -> block 레이어입니다.

schema

콘텐츠의 의미 구조입니다.

예:

parallel_cluster
parallel_cluster_plus_visual
compare_asymmetric_paired
sequence_plus_visual
single_block

recipe

block 이름이 아니라 표현 규칙입니다.

예:

single_block
two_col_text_visual
two_col_text_detail
stacked_summary_detail

recipe는 보통 이런 계약을 가질 수 있습니다.

left / right kind
top / bottom kind
ratio
vertical align
direct render 우선 여부

block

실제 구현 템플릿 후보입니다.

예:

prerequisites-3col
process-product-2col
compare-detail-gradient
card-icon-desc

즉, “무슨 문서냐”보다 “무슨 구조냐”를 먼저 읽고, 그 구조에 맞는 표현 규칙을 정한 뒤, 마지막에 구현 block을 고르는 방향으로 가고 있습니다.

popup은 현재 다음 철학으로 정리되는 중입니다.

메인 슬라이드에는 zone 크기에 맞는 요약만 남긴다
큰 표, 시각 컴포넌트, 과다 bullet은 상세 popup으로 분리한다
메인에서는 자세히보기 링크를 제공한다

현재 popup 관련 핵심은 아래입니다.

PopupItem 모델로 popup 데이터를 명시적으로 다루기 시작함
popup_id와 popup_file 생애주기를 분리해 관리 중
최종 목표는 popup 판단을 휴리스틱이 아니라 명시적 contract로 만드는 것

다만 아직 일부 구간에는 추측 로직과 이중 관리가 남아 있어, 이 부분은 계속 정리 중입니다.

run 산출물 구조

각 실행은 data/runs/{run_id}/ 아래에 저장됩니다.

주요 파일은 다음과 같습니다.

final.html
final_context.json
steps/*.html
popup / detail HTML

final.html

최종 렌더 결과
실제 눈으로 보는 산출물

final_context.json

각 단계 결과를 최종 context 형태로 저장
block 선택, page_structure, measurement, quality_score 등을 확인할 때 가장 중요

steps/*.html

단계별 디버그 / 설명용 보드
현재도 검토용으로 유용하지만, 일부 인코딩과 설명 품질은 더 다듬을 필요가 있음

자주 봐야 하는 파일

파이프라인 핵심

템플릿 / 카탈로그

templates/catalog.yaml
templates/blocks/new/prerequisites-3col.html
templates/blocks/redesign/process-product-2col.html
templates/blocks/cards/compare-detail-gradient.html
templates/blocks/slide-base.html

검증 / 측정

계획 / 히스토리

현재 상태

비교적 잘 닫혀가는 것

Type B 메인 경로
normalized.sections 기반 구조 해석
schema / recipe 기반 block selection의 골격
redesign block 자산화
popup / detail 2단 표현 계약의 초안 연결

아직 정리 중인 것

Type A 전체 안정화
popup을 완전한 source of truth로 정리
tag_match 와 schema_match의 완전한 동등 점수 비교
step 보드 인코딩 / 설명 품질
fit loop의 공간 재분배 고도화
legacy 경로와 문서 정리

최근 Type B에서 특히 중요해진 방향

recipe direct render가 block 선택에 끌려가지 않도록 구조 계약을 더 강하게 만든다
Type B direct render가 Type B'의 검증된 표시 계약을 최대한 재사용하도록 정리한다
sample은 복제 대상이 아니라 evaluation rule의 기준으로 사용한다
validation은 “같아야 한다”보다 “어긋나면 안 된다”에 초점을 둔다

향후 개선 방향

현재 이후의 개선 방향은 아래 축으로 정리됩니다.

1. 구조 계약 강화

top / bottom zone의 contract를 더 구체화
parallel_cluster_plus_visual, full_text + detail_preview 같은 recipe를 표현 범주 수준으로 강화
recipe가 block를 끌고 가는 것이 아니라 recipe가 block를 통제하도록 정리

2. 표시 계약 통합

Type B direct render가 Type B'에서 이미 검증된 bullet / indent / body-text 구조를 재사용하도록 통합
.rdr-* 계열 신규 CSS를 계속 키우기보다, 기존 검증된 계약을 최대한 재사용

3. detail preview 개선

popup source가 표면 헤더 + 일부 행
popup source가 리스트면 앞부분 몇 개
popup source가 컴포넌트면 구조화된 preview

즉 “링크만 있는 상세”가 아니라 “상세가 있다는 걸 바로 이해할 수 있는 preview”를 만드는 방향

4. fit loop 고도화

지금은 주로 overflow 대응 중심이지만, 앞으로는 아래까지 확장하려고 합니다.

빈 공간 감지
이미지 확대
preview 행 수 조정
zone 비율 재배분

5. 검증판과 final 일치화

stage_4 보드와 실제 final_context.json / final.html의 상태 차이를 줄이기
검수 보드를 더 믿을 수 있는 상태로 정리

읽는 순서 추천

프로세스를 빠르게 파악하려면 아래 순서가 좋습니다.

이 README.md
src/pipeline.py
src/section_parser.py
src/block_assembler.py
최근 run의 final_context.json

히스토리와 설계 변화까지 보려면 아래 문서를 이어서 보면 좋습니다.

README.md

C.E.L. Slide Pipeline

무엇을 하는가

한눈에 보는 프로세스