Drive diagram runtime from YAML

Author: eddmpython

docs/skills/architecture/learning-yaml-contract.md

@@ -38,6 +38,13 @@ intro:
         detail: 따라 칠 코드
       - label: 실행
         detail: 입력과 검증
+    runtime:
+      - label: 계약
+        detail: YAML SSOT
+      - label: 환경
+        detail: uv 패키지
+      - label: 검증
+        detail: 실행 결과
 sections:
   - id: dataframe-basics
     title: DataFrame 만들기
@@ -70,7 +77,7 @@ sections:
 ## 렌더링 원칙
 
 - 레슨 상단은 `intro.direction`, `intro.benefits`, `intro.diagram`을 읽어 무엇을 공부하는지, 왜 유용한지, 전체 흐름을 보여준다.
-- `intro.diagram`은 제품 화면에서 blueprint 질감, 좌측 overview rail, 번호가 있는 노드, 연결선, 흐름 트랙, 런타임 스트립을 가진 학습 아키텍처 캔버스로 렌더링한다. 단순 목록 박스로 축소하지 않고, 상단 benefit은 작은 박스 반복이 아니라 흐름을 보조하는 체크 리스트로 둔다.
+- `intro.diagram`은 제품 화면에서 blueprint 질감, 좌측 overview rail, 번호가 있는 노드, 연결선, 흐름 트랙, 런타임 스트립을 가진 학습 아키텍처 캔버스로 렌더링한다. `diagram.steps`는 상단 학습 흐름, `diagram.runtime`은 계약/환경/검증 같은 런타임 레이어를 정의한다. 단순 목록 박스로 축소하지 않고, 상단 benefit은 작은 박스 반복이 아니라 흐름을 보조하는 체크 리스트로 둔다.
 - 섹션 하나가 학습카드 하나다. `sections[].blocks[]`의 작은 카드 반복을 기본 구조로 삼지 않는다.
 - 섹션 카드는 `title → subtitle → goal → why → explanation → tips → snippet → exercise → result → check` 순서로 이어진다.
 - 카드 내부 정보는 라벨, 구획선, 여백으로 구분한다. 카드 안에 또 카드가 덕지덕지 쌓이는 구조는 피한다.
@@ -80,7 +87,7 @@ sections:
 - 섹션 헤더 번호는 타이틀/서브타이틀 묶음과 높이를 맞춘다. 셀 도움 요청 액션은 hover-only가 아니라 항상 보이는 control로 둔다.
 - 셀 TOC는 push rail이다. overlay flyout으로 같은 아이콘 목록을 한 번 더 띄우지 않는다.
 - structured 섹션의 `exercise` band는 클릭해야 열리는 preview가 아니라 바로 보이는 실제 입력 editor를 가진다. `learning-card-browser` gate는 이 editor가 desktop/mobile에서 보이고 starter code를 렌더링하는지 확인한다.
-- 레슨 overview는 `data-learning-overview`, `data-learning-overview-blueprint`, `data-learning-overview-rail`, `data-learning-overview-part`, `data-learning-flow-diagram`, `data-learning-flow-blueprint`, `data-learning-flow-track`, `data-learning-flow-step`, `data-learning-flow-runtime-node` marker를 가진다. `learning-card-browser` gate는 방향, 학습 효과, 플로우 track/step/runtime node가 실제 desktop/mobile 화면에 보이는지 확인한다.
+- 레슨 overview는 `data-learning-overview`, `data-learning-overview-blueprint`, `data-learning-overview-rail`, `data-learning-overview-part`, `data-learning-flow-diagram`, `data-learning-flow-blueprint`, `data-learning-flow-track`, `data-learning-flow-step`, `data-learning-flow-runtime-node` marker를 가진다. `learning-card-browser` gate는 방향, 학습 효과, 플로우 track/step/runtime node가 실제 desktop/mobile 화면에 보이는지 확인하고, runtime node 문구가 YAML의 `intro.diagram.runtime`에서 온다는 점을 검증한다.
 - structured section card는 브라우저 검증을 위해 `data-learning-section-card`, `data-learning-section-structured`, `data-learning-section-part` marker를 가진다. 검증 대상 part는 `overview`, `snippet`, `exercise`, `result`, `check`다.
 - marker 계약과 editor build는 `uv run python -X utf8 tests/run.py gate learning-card-contract`로 확인한다. 실제 데스크톱/모바일 브라우저 렌더링은 `uv run python -X utf8 tests/run.py gate learning-card-browser`로 확인한다.
 - `snippet`은 예제 스니펫 셀로, `exercise.starterCode`는 학습자가 직접 입력/수정하는 실습 셀로 materialize한다. 렌더러는 이 영역을 `Python 실습 코드`와 `학습자가 작성` 상태로 명확히 표시하고 `data-learning-exercise-input-role="student-practice"`를 유지한다.

editor/src/components/curriculum/curriculumSurface.tsx

@@ -308,6 +308,7 @@ function LearningRouteConnector() {
 
 function LearningFlowDiagram({ diagram }: { diagram?: Record<string, unknown> }) {
   const customSteps = diagramSteps(diagram);
+  const customRuntimeNodes = diagramRuntimeNodes(diagram);
   const fallbackSteps = [
     { label: "목표", detail: "무슨 공부", Icon: Route, tone: "text-sky-500" },
     { label: "개념", detail: "설명과 팁", Icon: BookOpen, tone: "text-amber-500" },
@@ -324,6 +325,18 @@ function LearningFlowDiagram({ diagram }: { diagram?: Record<string, unknown> })
     }))
     : fallbackSteps;
   const visibleSteps = steps.slice(0, 4);
+  const runtimeIcons = [GitBranch, Package, CheckCircle2];
+  const fallbackRuntimeNodes = [
+    { label: "계약", detail: "YAML SSOT", Icon: GitBranch },
+    { label: "환경", detail: "uv 패키지", Icon: Package },
+    { label: "검증", detail: "실행 결과", Icon: CheckCircle2 },
+  ];
+  const runtimeNodes = customRuntimeNodes.length
+    ? customRuntimeNodes.map((node, index) => ({
+      ...node,
+      Icon: runtimeIcons[index % runtimeIcons.length],
+    }))
+    : fallbackRuntimeNodes;
 
   return (
     <div
@@ -417,11 +430,7 @@ function LearningFlowDiagram({ diagram }: { diagram?: Record<string, unknown> })
         <div className="mt-4 rounded-md border bg-card/80 px-3 py-3" data-learning-flow-runtime="true">
           <div className="mb-2 text-xs font-medium text-muted-foreground">런타임 레이어</div>
           <div className="grid gap-2 sm:grid-cols-3">
-          {[
-            { label: "계약", detail: "YAML SSOT", Icon: GitBranch },
-            { label: "환경", detail: "uv 패키지", Icon: Wrench },
-            { label: "검증", detail: "실행 결과", Icon: CheckCircle2 },
-          ].map(({ Icon, detail, label }) => (
+          {runtimeNodes.slice(0, 3).map(({ Icon, detail, label }) => (
             <div className="flex min-w-0 items-center gap-2 text-xs" data-learning-flow-runtime-node="true" key={label}>
               <Icon className="size-3.5 shrink-0 text-muted-foreground" />
               <span className="min-w-0">
@@ -1125,6 +1134,29 @@ function diagramSteps(diagram?: Record<string, unknown>) {
     .slice(0, 5);
 }
 
+function diagramRuntimeNodes(diagram?: Record<string, unknown>) {
+  if (!diagram) return [];
+  const source = Array.isArray(diagram.runtime)
+    ? diagram.runtime
+    : Array.isArray(diagram.runtimeLayer)
+      ? diagram.runtimeLayer
+      : Array.isArray(diagram.layers)
+        ? diagram.layers
+        : [];
+  return source
+    .map((item) => {
+      if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+        return { label: String(item), detail: "" };
+      }
+      if (!isRecord(item)) return null;
+      const label = readPayloadText(item.label ?? item.title ?? item.name);
+      const detail = readPayloadText(item.detail ?? item.description ?? item.content);
+      return label ? { label, detail } : null;
+    })
+    .filter((item): item is { label: string; detail: string } => Boolean(item))
+    .slice(0, 3);
+}
+
 function readSectionContract(value: unknown): CurriculumSectionContract | undefined {
   return isRecord(value) ? value as CurriculumSectionContract : undefined;
 }