ProtoPie renderer — renderer-core
개발 문서 원문 텍스트 추출본 / 2026-09-14

# renderer-core

RenderCommand 프로토콜의 핵심 타입 정의. GPU 의존성 없음. WASM 호환 (std only).

## Module layout

```
src/
├── lib.rs           # module declarations + pub use
├── command.rs       # RenderCommand enum, CommandBatch, LayerDescriptor
├── types.rs         # LayerType, LayerId, PathViewBox
├── properties.rs    # Fill, Stroke, text style/range/box semantics,
│                    # StrokeSemantics, StrokeAlign,
│                    # StrokeContourStyle / StrokeLineJoin / StrokeLineCap,
│                    # Shadow, Blur, Color, BlendMode
├── scene.rs         # SceneGraph, RenderNode, Transform, Geometry, FlatEntry
├── stroke/          # StrokePlanCompiler / StrokePlan semantic artifact
├── painter.rs       # Painter trait (begin_frame / submit_scene / end_frame)
├── camera.rs        # CameraState (offset / zoom / dpr / viewport / revision)
├── viewport.rs      # ViewportSize newtype
└── texture_tier.rs  # round_up_texture_tier (texture size quantization)
```

## Stroke seams (canonical, RFC-0201 / RFC-0202 / RFC-0203 / RFC-0208)

이 crate 는 stroke 의 semantic plan 을 한 곳에서 만든다. frame route 는 `StrokePlanSet` 을 한 번 만들고 graph/resource/tess 가 같은 plan 을 소비한다. production consumer 는 planless 호환 API 로 node 를 재해석하지 않는다.

| Artifact / helper | Role |
|-------------------|------|
| `StrokePlanCompiler::compile_node()` / `compile_scene()` | `RenderNode + Stroke` → semantic stroke artifact |
| `StrokePlanSet` | frame/build scope 에서 공유되는 stroke plan collection + `LayerId` lookup |
| `StrokePlan` | target, geometry plan, paint plan, support gates, paint slot, extent outset, signature |
| `StrokePlanTarget` | contour strokes keep a descriptor; text strokes carry only font-free stroke semantics |
| `StrokeContourSource` | Rect / Ellipse 는 descriptor 로 보존, Path 만 borrowed commands 유지 |
| `StrokeGeometryPlan` | width, requested/effective align, style, effective dashed style, dash runtime |
| `StrokePaintPlan` | explicit paint 또는 `Stroke.color` fallback solid |
| `StrokeSupport` | geometry gate 와 paint gate 를 분리해 보존 |
| `StrokeSignature` | renderer-tess stroke curve cache key seed |
| `stroke_paint_slot_index(fill_count)` | reserved stroke paint slot 산출 |
| `contour_stroker_align_for_contour()` | open-path → Center 정규화 |
| `StrokeContourUnsupportedReason` / `contour_stroke_unsupported_reason*()` | 제외된 이유 진단 |
| `summarize_contour_stroke_support()` | scene 전체 stroke 지원/미지원 집계 |

## Geometry seams

| Helper                                       | Role                                            |
|----------------------------------------------|-------------------------------------------------|
| `CornerRadius::resolve_for_size(w, h)`       | analytic rounded-rect 의 CSS-style overlap clamp |

## Text seams (RFC-0204 / RFC-0205 / RFC-0207 / RFC-0208)

renderer-core 는 text scene contract 만 소유한다. Font registry, glyph ID, glyph outline cache, glyph atlas, layout cache 는 renderer-tess 책임이다. `TextLayoutPlan` 은 cross-crate consumer 가 검증될 때까지 renderer-tess-local 로 유지한다. Text stroke 는 core `TextPlan` 이 아니라 `StrokePlanTarget::Text` 로 stroke semantic 만 공유한다.

| Artifact / helper | Role |
|-------------------|------|
| `TextStyle` | single-style fallback + shared base style (`font_style` 기본값 `Regular`) |
| `TextDecoration` | static underline / strikethrough scene contract (`None` 기본값) |
| `TextBoxStyle` | vertical align / auto-resize / truncation / max lines |
| `TextStyleRun` / `TextRunStyle` | UTF-16 range 기반 per-range style override |
| `TextRange::to_byte_range()` | JS/Figma UTF-16 offset 을 Rust byte range 로 검증 변환 |
| `validate_text_style_runs()` | empty / out-of-bounds / surrogate split / overlap 검증 |

`CreateLayer` 의 text descriptor 는 `validate_text_style_runs()` 를 통과해야 scene 에 들어간다. Invalid rich ranges 는 renderer-tess diagnostics 까지 흘려보내지 않는다.

## Feature flags

| Feature | 효과                                                  |
|---------|-------------------------------------------------------|
| `serde` | `Serialize + Deserialize` derive 활성화. WASM 경로는 `renderer-wasm` 이 enable. |

## Hard rules

- 순수 데이터 타입만 (wgpu / GPU 의존 금지).
- WASM 호환 — `std` 만, `std::thread` 금지.
- RFC-0001 (RenderCommand Protocol) 준수.
- LayerType 수정 시 workspace-adr `NodeType` 호환성 확인.
- RenderCommand 수정 시 `docs/protocol/render-command.schema.json` + `fixtures/` 동기화 (현재 protocol/ 디렉토리 부재 — 추후 복구 시).
- 현재 stroke paint 지원 범위: **solid / gradient / image** 만. Video / Lottie / 패턴 paint 는 runtime resolver + WebGL 시각 acceptance 거쳐야 `StrokeSupport.paint` gate 통과 가능.
- Open path 의 contour stroke align 은 `Center` 로 정규화. closed path 는 요청 align 유지.

## Cross-crate impact

- `properties.rs` 변경 → renderer-tess / renderer-wasm batching, renderer-resource paint provider 영향.
- `command.rs` 변경 → 전체 workspace 빌드 + fixtures 동기화.
- `stroke/plan.rs` 의 stroke seam 변경 → graph builder + tess batching + resource sync 모두 영향.