MDX 03 시연 정비 인사이트 — Phase Z pipeline 개선 axis (2026-05-15) #44

New Issue

Kyeongmin · 2026-05-15T12:29:53+09:00

Kyeongmin commented

2026-05-15 12:29:53 +09:00

MDX 03 시연 정비 인사이트 — Phase Z pipeline 개선 axis (2026-05-15)

발표 시연 path (mdx 03 + 03-1/03-2 rank 1/2/3 + 레이아웃 변환 + Connect) 정비 과정에서 얻은 인사이트. 향후 pipeline 개선 axis 로 정리. 모든 항목 = [단계] / [인사이트] / [개선 방향] / [참고] 구조.

1. Multi-layer silent fail chain (진단 도구 필수)

[단계] Step 12 (slot_payload) + Step 13 (render) + frontend handleGenerate
[인사이트] assets_dir 가 partial 까지 도달하지 않은 chain = (a) zones_data 키 누락 + (b) jinja autoescape (') + (c) Windows ` → URL 404` 3 중 silent fail. 한 chain 안 여러 layer 가 동시에 fail 면 "수정했다" 착각 → 사용자에게 "변환이 안 됨" 으로 보임.
[개선] 각 step 에 명시적 assertion + visible signal :
- zones_data[i] 가 partial render 직전 필수 키 (assets_dir, slot_payload) 보유 여부 assertion
- build_layout_css 의 url() output 에 invalid char (&, \) detector
- frontend [DIAG raw overrides] 같은 진단 console.log/terminal log 가 상시 출력 (사용자 진단 cost 0)
[참고] assets_dir buggy chain 수정 = src/phase_z2_pipeline.py:2606,2635 + templates/phase_z2/families/dx_sw_necessity_three_perspectives.html 의 | safe + as_posix()

2. Phase Z 원칙 위배 — zone size 가 frame.min_height 기반 (Axis A: zone lock)

[단계] Step 7-8 (layout / space_allocator)
[인사이트] compute_zone_layout 이 min_height_first + content_weight_distribution 으로 zone height 계산. frame 마다 다른 min_height → frame override 시 zone 비율 변동 → 사용자가 본 "frame 만 바꿨는데 글자가 잘림". CLAUDE.md 의 "디자인이 텍스트에 맞춘다" 와 정확히 반대 방향.
[개선] zone size lock — 1차 generate 의 measured zone heights 를 콘텐츠 자연 height 신호로 채택 + frame override 시 그 값 그대로 유지. 이미 backend build_layout_css 의 override_zone_geometries path 존재 → frontend 가 자동으로 prev heights 를 ratio 로 변환해서 spawn args 에 추가.
[참고] client/src/services/designAgentApi.ts 의 RunMeta zone_heights_px + client/src/pages/Home.tsx handleGenerate 의 pinned zoneGeometries 자동 set. src/phase_z2_pipeline.py:794 의 available = SLIDE_BODY_HEIGHT - gap * (n - 1) 추가 (override path 의 gap subtraction 누락 버그)

3. 수학 비례 fit — CSS container query + jinja line count (Axis B)

[단계] Step 13 (jinja render) + partial CSS
[인사이트] partial 의 padding/margin/gap/line-height 가 고정 px 라 zone 크기 변동 시 fit 안 됨. 사용자 직관 = "frame 100/줄 3/줄간 10 이었으면, 50/6 일 때 줄간 x = ?" 같은 수학적 비례 산식. CSS container query (cqh / cqw 단위) + clamp(min, calc(N*cqh / line_count), max) + jinja 가 카드별 line count --max-body-lines inline 주입.

[개선] 모든 partial 정비 (현재 03-1/03-2 partial 만). 패턴 :

.card { container-type: size; }
.card .text-line {
  line-height: clamp(1.05em, calc(70cqh / var(--max-body-lines, 5)), 1.5em);
}

<div class="card" style="--max-body-lines: {{ body_lines | length }};">

[참고] 사용자 룰 = font-size 미변경. line-height / padding / gap / letter-spacing 만 조정 가능.

4. CSS container query 기반 자동 회전 — layout 변경 대응

[단계] Step 13 (jinja render) + partial CSS

[인사이트] layout preset 변경 (horizontal-2 → vertical-2) 시 zone shape (wide vs tall) 가 바뀜. JS / backend / preset 별 분기 없이 CSS 만으로 grid 회전 가능 :

.root { container-type: size; container-name: my-root; }
@container my-root (aspect-ratio < 1.5) {
  .cards { grid-template-columns: 1fr; grid-template-rows: auto auto auto; align-content: start; }
}

[개선] 모든 콘텐츠 grid partial 에 적용. 단 2 col compare table 같이 회전 부적합한 frame 은 회전 비활성. partial 별 의도 따라.
[참고] 1fr 1fr 1fr (균등 분할) 보다 auto auto auto + align-content: start 가 좌/우 zone visual balance 에 더 자연 — 콘텐츠 height 만 차지 + 위쪽 정렬.

5. 콘텐츠 무손실 보존 — builder 통일 (process_product_pair + column_with_transform)

[단계] Step 11 (builder) + Step 13 (render)
[인사이트] rank 별 frame visual 은 다르더라도 mdx 콘텐츠는 동일. 그러나 bim_dx_comparison_table 의 builder_options column_plain 이 markdown table (AS-IS/TO-BE) 무시 → 사용자가 본 "AS-IS/TO-BE 사라짐". 메모리 [AI 격리 contract] 의 원문 무손실 보존 룰 위배.
[개선] 모든 비교/2-column frame 의 builder = process_product_pair, body_parser = column_with_transform. partial 의 jinja loop 에서 {% if a.transforms %} mini table {% else %} text_lines {% endif %} 분기 처리. 모든 frame 이 동일 mdx 의 모든 element (transforms / text_lines / images / strong) 보존.
[참고] templates/phase_z2/catalog/frame_contracts.yaml 의 bim_dx_comparison_table + app_sw_package_vs_solution (신규 등록) 모두 동일 builder/parser.

6. Frontend stale closure + override comparison bug

[단계] N/A (frontend)
[인사이트] React useCallback deps array 누락 ([state.uploadedFile] 만) → mdx 업로드 후 첫 render 의 state capture → frame override 클릭으로 state 변경 후에도 옛 state 봄. 모든 spawn 의 overrides 가 빈 채로 backend 까지 도달. 진단 도구 (vite plugin DIAG log) 없으면 잡기 매우 어려움.
[개선] frontend 의 모든 useCallback deps 점검 + ESLint react-hooks/exhaustive-deps 활성. 또한 backend 의 current_default_candidate 가 override 적용된 template_id 라 default 와 override 구분 어려움 → backend 가 원본 V4 rank 1 template_id 와 현재 적용된 template_id 를 별도 field 로 반환.
[참고] Home.tsx handleGenerate 의 deps + override 비교 (overrideFrameId !== defaultFrameId) 제거. 사용자 명시 override 는 default 와 같든 다르든 spawn args 에 포함.

7. 자동 fix loop 부분 구현 + 미구현 action (visual_check → retry chain)

[단계] Step 14 (visual_check) → Step 15 (fit_classification) → Step 16 (router_decision) → Step 17 (retry_trace)
[인사이트] _attempt_zone_ratio_retry 는 구현됨 (donor zone 에서 sibling 차감 → rerender → revert on fail, budget=1). 그러나 다른 action :
- details_popup_escalation = 미구현. 콘텐츠가 frame slot 보다 클 때 텍스트 일부를 popup 으로 이동.
- frame_swap = 미구현. V4 rank+1 frame 으로 자동 fallback.
[개선] 우선 순위 :
1. frame_swap (1-2 일 axis, _attempt_zone_ratio_retry 패턴 mirror) — 사용자 명시 override 없을 때만 자동 시도, 사용자 override 시 idempotent.
2. details_popup_escalation (2-3 일 axis) — 텍스트 분할 + slide-base 의 <details> mechanism. AI fallback path (메모리 [AI 격리 contract]).
[참고] src/phase_z2_pipeline.py:1182 의 패턴.

8. Incremental rerun 없음 — V4 + Selenium 매번 재실행

[단계] 전체 pipeline (step00 ~ step21)
[인사이트] frame override 만 바꿔도 매 spawn 마다 step00 ~ step21 전체 재실행. 가장 비싼 step :
- Step 5 (V4 매칭) — TF-IDF + frame index 계산
- Step 14 (visual_check) — Selenium headless chromium
[개선] --reuse-from <prev_run_id> 옵션 — frame override 가 step09 에만 영향, step00~step08 은 동일. prev run 의 output 을 copy + step09 부터 재실행 = 50-70% 시간 절감 (~10-20초 → ~3-8초).
[참고] 1 일 axis. revert mechanism = prev run_id 그대로.

9. Layout override 와 zone position id mismatch

[단계] Step 7-8 (layout)
[인사이트] horizontal-2 (top/bottom) → vertical-2 (left/right) 전환 시 zone_geometries override 의 position key 가 mismatch. backend 가 우연히 default fr 로 fallback 해서 PASS, 그러나 cleanliness 위해 frontend 에서 layout 변경 시 pinned heights skip.
[개선] Home.tsx handleGenerate 의 pinned 조건에 && !overrides.layout 추가. backend build_layout_css 의 override path 가 unknown position key 에 warning emit.
[참고] client/src/pages/Home.tsx:344 (frontend) + src/phase_z2_pipeline.py:790-823 (backend override path).

10. Connect axis — design_agent → cel astro 정적 export

[단계] N/A (integration)
[인사이트] design_agent (3000) 의 final.html 은 상대 path asset 참조. cel astro 사이트의 정적 path (public/slides/<slug>.html + public/slides/assets/) 와 그대로 일치 → 단순 file copy 만으로 사이트에 슬라이드 노출.
[개선] Vite plugin POST /api/connect endpoint (body {run_id, slug}). RUNS_DIR/<run_id>/phase_z2/final.html + assets/ → CEL_SLIDES_DIR/<slug>.html + assets/ (overwrite, fs.cpSync recursive). frontend Connect 버튼 = handleConnect (slug = selectedSample 또는 filename prefix).
[참고] cross-origin 없음, build 없음. cel 사이트의 SlideViewer.astro 가 iframe.src = /slides/<slug>.html 으로 load. 변경 시 cel astro dev server HMR 자동.

발표 후 axis 우선 순위 (추후 implement)

incremental rerun (--reuse-from) — 1 일 axis, 모든 사용자 대상 효과 큼
frame_swap auto retry — _attempt_zone_ratio_retry 패턴 mirror, 1-2 일
details_popup_escalation — AI fallback path, 2-3 일
다른 sample (04 / 05) partial 정비 — 03-1/03-2 의 Axis A/B 패턴 mirror
다른 layout preset (single / hero-detail / three-row) 의 partial 회전 패턴
build-time validation — partial 안 placeholder ID / slot key 가 contract 와 일치하는지 자동 검증

이 정리는 mdx 03 시연 정비 (2026-05-15 lock) 결과. 발표 후 axis 별 implement 검토.

# MDX 03 시연 정비 인사이트 — Phase Z pipeline 개선 axis (2026-05-15) 발표 시연 path (mdx 03 + 03-1/03-2 rank 1/2/3 + 레이아웃 변환 + Connect) 정비 과정에서 얻은 인사이트. 향후 pipeline 개선 axis 로 정리. 모든 항목 = `[단계] / [인사이트] / [개선 방향] / [참고]` 구조. --- ## 1. Multi-layer silent fail chain (진단 도구 필수) - **[단계]** Step 12 (slot_payload) + Step 13 (render) + frontend handleGenerate - **[인사이트]** `assets_dir` 가 partial 까지 도달하지 않은 chain = `(a) zones_data 키 누락 + (b) jinja autoescape (`'`) + (c) Windows `\` → URL 404` 3 중 silent fail. 한 chain 안 여러 layer 가 동시에 fail 면 "수정했다" 착각 → 사용자에게 "변환이 안 됨" 으로 보임. - **[개선]** 각 step 에 *명시적 assertion + visible signal* : - `zones_data[i]` 가 partial render 직전 필수 키 (`assets_dir`, `slot_payload`) 보유 여부 assertion - `build_layout_css` 의 url() output 에 invalid char (`&`, `\`) detector - frontend `[DIAG raw overrides]` 같은 진단 console.log/terminal log 가 *상시 출력* (사용자 진단 cost 0) - **[참고]** assets_dir buggy chain 수정 = `src/phase_z2_pipeline.py:2606,2635` + `templates/phase_z2/families/dx_sw_necessity_three_perspectives.html` 의 `| safe` + as_posix() --- ## 2. Phase Z 원칙 위배 — zone size 가 frame.min_height 기반 (Axis A: zone lock) - **[단계]** Step 7-8 (layout / space_allocator) - **[인사이트]** `compute_zone_layout` 이 `min_height_first + content_weight_distribution` 으로 zone height 계산. **frame 마다 다른 min_height** → frame override 시 zone 비율 변동 → 사용자가 본 "frame 만 바꿨는데 글자가 잘림". CLAUDE.md 의 *"디자인이 텍스트에 맞춘다"* 와 정확히 반대 방향. - **[개선]** zone size lock — 1차 generate 의 measured zone heights 를 *콘텐츠 자연 height* 신호로 채택 + frame override 시 그 값 그대로 유지. 이미 backend `build_layout_css` 의 `override_zone_geometries` path 존재 → frontend 가 자동으로 prev heights 를 ratio 로 변환해서 spawn args 에 추가. - **[참고]** `client/src/services/designAgentApi.ts` 의 RunMeta `zone_heights_px` + `client/src/pages/Home.tsx` handleGenerate 의 pinned zoneGeometries 자동 set. `src/phase_z2_pipeline.py:794` 의 `available = SLIDE_BODY_HEIGHT - gap * (n - 1)` 추가 (override path 의 gap subtraction 누락 버그) --- ## 3. 수학 비례 fit — CSS container query + jinja line count (Axis B) - **[단계]** Step 13 (jinja render) + partial CSS - **[인사이트]** partial 의 padding/margin/gap/line-height 가 *고정 px* 라 zone 크기 변동 시 fit 안 됨. 사용자 직관 = "frame 100/줄 3/줄간 10 이었으면, 50/6 일 때 줄간 x = ?" 같은 *수학적 비례 산식*. CSS container query (`cqh / cqw` 단위) + `clamp(min, calc(N*cqh / line_count), max)` + jinja 가 카드별 line count `--max-body-lines` inline 주입. - **[개선]** 모든 partial 정비 (현재 03-1/03-2 partial 만). 패턴 : ```css .card { container-type: size; } .card .text-line { line-height: clamp(1.05em, calc(70cqh / var(--max-body-lines, 5)), 1.5em); } ``` ```jinja <div class="card" style="--max-body-lines: {{ body_lines | length }};"> ``` - **[참고]** 사용자 룰 = font-size 미변경. line-height / padding / gap / letter-spacing 만 조정 가능. --- ## 4. CSS container query 기반 자동 회전 — layout 변경 대응 - **[단계]** Step 13 (jinja render) + partial CSS - **[인사이트]** layout preset 변경 (horizontal-2 → vertical-2) 시 zone shape (wide vs tall) 가 바뀜. JS / backend / preset 별 분기 없이 CSS 만으로 grid 회전 가능 : ```css .root { container-type: size; container-name: my-root; } @container my-root (aspect-ratio < 1.5) { .cards { grid-template-columns: 1fr; grid-template-rows: auto auto auto; align-content: start; } } ``` - **[개선]** 모든 *콘텐츠 grid* partial 에 적용. 단 *2 col compare table* 같이 회전 부적합한 frame 은 회전 비활성. partial 별 의도 따라. - **[참고]** `1fr 1fr 1fr` (균등 분할) 보다 `auto auto auto + align-content: start` 가 *좌/우 zone visual balance* 에 더 자연 — 콘텐츠 height 만 차지 + 위쪽 정렬. --- ## 5. 콘텐츠 무손실 보존 — builder 통일 (process_product_pair + column_with_transform) - **[단계]** Step 11 (builder) + Step 13 (render) - **[인사이트]** rank 별 frame visual 은 다르더라도 mdx 콘텐츠는 동일. 그러나 `bim_dx_comparison_table` 의 builder_options `column_plain` 이 markdown table (AS-IS/TO-BE) 무시 → 사용자가 본 "AS-IS/TO-BE 사라짐". 메모리 [AI 격리 contract] 의 *원문 무손실 보존* 룰 위배. - **[개선]** 모든 비교/2-column frame 의 builder = `process_product_pair`, body_parser = `column_with_transform`. partial 의 jinja loop 에서 `{% if a.transforms %} mini table {% else %} text_lines {% endif %}` 분기 처리. 모든 frame 이 동일 mdx 의 모든 element (transforms / text_lines / images / strong) 보존. - **[참고]** `templates/phase_z2/catalog/frame_contracts.yaml` 의 `bim_dx_comparison_table` + `app_sw_package_vs_solution` (신규 등록) 모두 동일 builder/parser. --- ## 6. Frontend stale closure + override comparison bug - **[단계]** N/A (frontend) - **[인사이트]** React `useCallback` deps array 누락 (`[state.uploadedFile]` 만) → mdx 업로드 후 첫 render 의 state capture → frame override 클릭으로 state 변경 후에도 옛 state 봄. **모든 spawn 의 overrides 가 빈 채로 backend 까지 도달**. 진단 도구 (vite plugin DIAG log) 없으면 잡기 매우 어려움. - **[개선]** frontend 의 모든 `useCallback` deps 점검 + ESLint `react-hooks/exhaustive-deps` 활성. 또한 backend 의 `current_default_candidate` 가 *override 적용된 template_id* 라 default 와 override 구분 어려움 → backend 가 *원본 V4 rank 1 template_id* 와 *현재 적용된 template_id* 를 별도 field 로 반환. - **[참고]** Home.tsx handleGenerate 의 deps + override 비교 (`overrideFrameId !== defaultFrameId`) 제거. 사용자 명시 override 는 default 와 같든 다르든 spawn args 에 포함. --- ## 7. 자동 fix loop 부분 구현 + 미구현 action (visual_check → retry chain) - **[단계]** Step 14 (visual_check) → Step 15 (fit_classification) → Step 16 (router_decision) → Step 17 (retry_trace) - **[인사이트]** `_attempt_zone_ratio_retry` 는 구현됨 (donor zone 에서 sibling 차감 → rerender → revert on fail, budget=1). 그러나 다른 action : - `details_popup_escalation` = 미구현. 콘텐츠가 frame slot 보다 클 때 텍스트 일부를 popup 으로 이동. - `frame_swap` = 미구현. V4 rank+1 frame 으로 자동 fallback. - **[개선]** 우선 순위 : 1. **frame_swap** (1-2 일 axis, `_attempt_zone_ratio_retry` 패턴 mirror) — 사용자 명시 override 없을 때만 자동 시도, 사용자 override 시 idempotent. 2. **details_popup_escalation** (2-3 일 axis) — 텍스트 분할 + slide-base 의 `<details>` mechanism. AI fallback path (메모리 [AI 격리 contract]). - **[참고]** `src/phase_z2_pipeline.py:1182` 의 패턴. --- ## 8. Incremental rerun 없음 — V4 + Selenium 매번 재실행 - **[단계]** 전체 pipeline (step00 ~ step21) - **[인사이트]** frame override 만 바꿔도 매 spawn 마다 step00 ~ step21 전체 재실행. 가장 비싼 step : - Step 5 (V4 매칭) — TF-IDF + frame index 계산 - Step 14 (visual_check) — Selenium headless chromium - **[개선]** `--reuse-from <prev_run_id>` 옵션 — frame override 가 step09 에만 영향, step00~step08 은 동일. prev run 의 output 을 copy + step09 부터 재실행 = **50-70% 시간 절감** (~10-20초 → ~3-8초). - **[참고]** 1 일 axis. revert mechanism = prev run_id 그대로. --- ## 9. Layout override 와 zone position id mismatch - **[단계]** Step 7-8 (layout) - **[인사이트]** horizontal-2 (top/bottom) → vertical-2 (left/right) 전환 시 zone_geometries override 의 position key 가 mismatch. backend 가 *우연히* default fr 로 fallback 해서 PASS, 그러나 cleanliness 위해 frontend 에서 layout 변경 시 pinned heights skip. - **[개선]** `Home.tsx` handleGenerate 의 pinned 조건에 `&& !overrides.layout` 추가. backend `build_layout_css` 의 override path 가 unknown position key 에 warning emit. - **[참고]** `client/src/pages/Home.tsx:344` (frontend) + `src/phase_z2_pipeline.py:790-823` (backend override path). --- ## 10. Connect axis — design_agent → cel astro 정적 export - **[단계]** N/A (integration) - **[인사이트]** design_agent (3000) 의 final.html 은 *상대 path asset 참조*. cel astro 사이트의 정적 path (`public/slides/<slug>.html` + `public/slides/assets/`) 와 그대로 일치 → 단순 file copy 만으로 사이트에 슬라이드 노출. - **[개선]** Vite plugin `POST /api/connect` endpoint (body `{run_id, slug}`). `RUNS_DIR/<run_id>/phase_z2/final.html` + `assets/` → `CEL_SLIDES_DIR/<slug>.html` + `assets/` (overwrite, `fs.cpSync` recursive). frontend Connect 버튼 = `handleConnect` (slug = `selectedSample` 또는 filename prefix). - **[참고]** cross-origin 없음, build 없음. cel 사이트의 `SlideViewer.astro` 가 `iframe.src = /slides/<slug>.html` 으로 load. 변경 시 cel astro dev server HMR 자동. --- ## 발표 후 axis 우선 순위 (추후 implement) 1. **incremental rerun** (`--reuse-from`) — 1 일 axis, 모든 사용자 대상 효과 큼 2. **frame_swap auto retry** — `_attempt_zone_ratio_retry` 패턴 mirror, 1-2 일 3. **details_popup_escalation** — AI fallback path, 2-3 일 4. **다른 sample (04 / 05) partial 정비** — 03-1/03-2 의 Axis A/B 패턴 mirror 5. **다른 layout preset (single / hero-detail / three-row) 의 partial 회전 패턴** 6. **build-time validation** — partial 안 placeholder ID / slot key 가 contract 와 일치하는지 자동 검증 --- 이 정리는 mdx 03 시연 정비 (2026-05-15 lock) 결과. 발표 후 axis 별 implement 검토.

axis	분해 / 흡수 / 이미 구현됨	신규 IMP / 처리
1 Multi-layer silent fail 진단 도구	분해	#71 IMP-42 silent fail chain 진단 도구
2 Axis A zone size lock	이미 구현됨 (2026-05-15 lock)	—
3 Axis B 수학 비례 fit (cqh / clamp)	흡수	#65 IMP-36 (partial 일반화 안에 포함)
4 CSS container query 자동 회전	분해	#65 IMP-36 fit / rotation 일반화
5 콘텐츠 무손실 보존 builder 통일 (process_product_pair + column_with_transform)	이미 구현됨 (03-1/03-2) + 흡수 일반화	#65 IMP-36 일반화
6 Frontend stale closure + override comparison bug	이미 구현됨	—
7 ⚠ frame_swap auto retry (폐기) + popup escalation	정정 + 분해	#63 IMP-34 zone resize (정정) + #64 IMP-35 popup
8 Incremental rerun `--reuse-from`	분해	#72 IMP-43 incremental rerun
9 Layout override ↔ zone position id mismatch	분해	#73 IMP-44 layout override mismatch warning
10 Connect axis (design_agent → cel)	이미 구현됨 (`/api/connect`)	—

MDX 03 시연 정비 인사이트 — Phase Z pipeline 개선 axis (2026-05-15) #44

MDX 03 시연 정비 인사이트 — Phase Z pipeline 개선 axis (2026-05-15)

1. Multi-layer silent fail chain (진단 도구 필수)

2. Phase Z 원칙 위배 — zone size 가 frame.min_height 기반 (Axis A: zone lock)

3. 수학 비례 fit — CSS container query + jinja line count (Axis B)

4. CSS container query 기반 자동 회전 — layout 변경 대응

5. 콘텐츠 무손실 보존 — builder 통일 (process_product_pair + column_with_transform)

6. Frontend stale closure + override comparison bug

7. 자동 fix loop 부분 구현 + 미구현 action (visual_check → retry chain)

8. Incremental rerun 없음 — V4 + Selenium 매번 재실행

9. Layout override 와 zone position id mismatch

10. Connect axis — design_agent → cel astro 정적 export

발표 후 axis 우선 순위 (추후 implement)

분해 완료 — 14 신규 IMP + 이미 구현됨 + 흡수 매핑 + 정정 사항 (2026-05-21)

#44 axis 10 → 신규 IMP 매핑 표

⚠ axis 7 정정 사항 (중요)

overflow 처리 정정된 순서 (모든 chain IMP 의 가드)

동반 14 신규 IMP 전체 (Wave 1 + Wave 2)

closed.