레이아웃 · 렌더링

문서 모델에서 각 블록의 위치와 크기(bounding box)를 계산하고, 그 결과를 SVG로 렌더링하는 방법을 정의합니다. 모습의 값(색, 선 굵기, 글자 크기, 여백과 치수)은 디자인 토큰으로 04-visual-design에만 있고, 이 문서는 그 토큰을 쓰는 방법을 정합니다.

코드: src/packages/core, 글꼴은 src/packages/fonts (→ ADR-0036)

관련 요구사항

렌더링 파이프라인

flowchart LR
    doc[/"Doc (Content + View)"/]
    lay["layout()"]
    lr[/"LayoutResult<br/>다이어그램 위치<br/>블록 id → bounding box"/]
    theme[/"Theme<br/>디자인 토큰 → 값"/]
    scene["buildScene()"]
    sc[/"Scene<br/>디스플레이 리스트<br/>(요소마다 블록 id)"/]
    svg["toSvg()"]
    out[/"SVG 문자열"/]
    metrics[/"fonts: advance 폭 테이블"/]
    doc --> lay
    metrics -.-> lay
    lay --> lr
    lr --> scene
    theme -.-> scene
    scene --> sc
    sc --> svg
    svg --> out
    lr -.히트 테스트 · 오버레이 위치.-> ed["editor"]
    out -.화면 표시 · 저장.-> ed
    glyphs[/"fonts: 글리프 외곽선"/]
    pages["paginate()"]
    pdf["writePdf()"]
    pdfout[/"PDF 바이트"/]
    glyphs -.텍스트를 외곽선으로.-> svg
    lr --> pages
    pages --> pdf
    sc --> pdf
    glyphs -.-> pdf
    pdf --> pdfout

범례 (UML 액티비티 다이어그램에 가까운 flowchart)

  • 사각형 = 처리 단계(core의 순수 함수), 평행사변형 = 데이터(단계의 입력 · 출력 객체).
  • 실선 화살표: 주 데이터 흐름(앞 단계의 출력이 다음 단계의 입력).
  • 점선 화살표: 보조 입력(메트릭, 테마, 글리프 외곽선), 또는 editor가 결과를 소비하는 곳.
  • 아래 줄(paginate → writePdf)은 PDF 내보내기의 경로입니다(5장). 인쇄는 paginate의 페이지에 SVG 문자열을 넣습니다.
  • 함수 이름(layout, buildScene, toSvg)은 단계를 가리키려고 붙인 가칭입니다. 시그니처는 정하지 않았습니다.
  • 세 단계는 모두 순수 함수입니다. 같은 입력이면 같은 출력이 나옵니다(결정적 출력 → R-FMT-03).
  • 색과 모양의 판단은 모두 씬 빌드(buildScene)에서 합니다. SVG 출력(toSvg)은 씬을 문자열로 옮길 뿐입니다. 그래서 출력 단계만 교체할 수 있습니다(렌더링 백엔드 → ADR-0030).
  • editor는 히트 테스트와 선택 오버레이의 위치를 SVG DOM이 아니라 LayoutResult로 계산합니다 → 4.3 의존 규칙
  • 같은 장면(Scene)이 출력 셋으로 갑니다: 화면과 저장 파일의 SVG(toSvg), 텍스트를 외곽선으로 바꾼 SVG(toSvg(scene, { outlines }), 3장), PDF(writePdf, 5장). 장면을 두 번 만들지 않으므로 셋의 모습이 같습니다 → ADR-0045

1. 레이아웃 알고리즘

관련 요구사항: R-LAY-01, R-LAY-02, R-EDIT-18

이 장의 값은 모두 5. 기하와 해부도의 토큰입니다.

1.1 두 단계

레이아웃은 트리를 두 번 순회합니다 → ADR-0037

단계방향하는 일결과
크기 측정 (measure)안쪽부터 (상향식)블록마다 내용이 들어가는 가장 작은 폭과 높이를 측정한다블록 id → 최소 크기
배치 (place)바깥부터 (하향식)부모가 정한 위치(x, y)와 실제 폭 · 높이를 자식에게 분배한다블록 id → bounding box
  • 크기 측정은 자식의 최소 크기만 보고 부모의 최소 크기를 정합니다. 배치는 부모가 받은 폭을 자식에게 나눕니다. 그래서 어느 분기가 깊어져도 전체가 직사각형으로 남습니다(R-LAY-02).
  • 모든 좌표와 크기는 정수 px입니다. 나누어 떨어지지 않는 폭은 반올림하고, 마지막 자식이 나머지를 받습니다. 그래서 같은 모델이면 같은 좌표가 나옵니다(R-FMT-03).
  • 접힌 것, 펴 보인 호출 블록, 이름 띠를 보이는지는 뷰 상태(2. 뷰 상태)에서 읽습니다. 뷰 상태가 가리키는 id가 없으면 무시합니다.

LayoutResult에 담는 것:

  • 다이어그램마다의 위치와 문서 전체의 폭 · 높이
  • 블록 id → bounding box. 접힌 분기 안의 블록은 그 접힌 줄의 상자를 받습니다(선택하면 분기 전체가 선택되므로)
  • 클릭 영역: 상자와 따로, 그 블록을 누르는 곳. 제어 블록은 조건 칸만, 펴진 접기 영역과 펴 보인 호출 블록은 띠만, 분기 라벨은 그 칸의 이름 줄, 접힌 줄과 접힌 칸은 그 칸 전체, 펼침 삼각형은 띠 · 접힌 칸의 왼쪽 끝 18px. editor가 클릭과 호버를 이것으로 구분합니다
  • 펴 보인 호출 블록 안에 렌더링한 것의 id는 화면 id입니다: 호출 블록의 경로를 /로 이은 뒤에 모델의 id를 붙입니다(b4/b17, 겹쳐 폈으면 b4/b9/b17). 같은 Method가 여러 곳에 펴 보여도 상자가 섞이지 않습니다 → 2. 상태와 선택
  • 렌더링 노드(nodes): 렌더링할 것의 목록입니다. 순서가 곧 칠하는 순서이고(바깥을 안쪽보다 먼저, 테두리는 그 안의 블록 뒤에), buildScene은 이 목록만 읽어 장면을 만듭니다. 텍스트를 측정하거나 모델을 읽지 않습니다.
kind무엇담는 것
process처리 블록상자, 배치한 텍스트, 분기의 하나뿐인 빈 블록(∅)인지
call호출 블록상자, 호출 블록의 텍스트(결과 · 이름 · 인자)
loopWhile · Do-While · For상자, 조건 칸(While · For는 위, Do-While은 아래), 텍스트
ifIf상자, 조건 칸, 텍스트, 빗금의 꼭짓점 x, 참 · 거짓의 분기 라벨
caseCase상자, 조건 칸, 텍스트, 분기의 열(default 열이 맨 뒤)
foldedSeq접힌 분기 · 반복문의 본문상자, “n개” 문구
foldCell접힌 접기 영역상자, 이름, 이름을 붙였는지
foldFrame펴진 접기 영역(이름 띠가 켜졌을 때)상자, 이름 띠, 이름, 이름을 붙였는지. 안의 블록보다 뒤에 칠함
peek펴 보인 호출 블록상자, 띠, 호출 블록의 텍스트. 안의 블록보다 뒤에 칠함
diagramHead다이어그램의 헤더상자, 종류(Event · Method), 모양(shape · title), 텍스트
missingDefaultdefault가 없는 Case의 빈 default 칸상자, 그 Case의 id
  • 클릭 영역(regions)의 종류: block(처리 · 호출 블록의 상자 전체), head(제어 블록의 조건 칸), branchLabel(분기의 라벨 줄. default가 없는 Case의 빈 default는 branchId가 null), missingDefault(빈 default 칸), diagramHead(다이어그램의 헤더), foldedSeq(접힌 줄), fold(접기 영역의 이름 띠나 접힌 칸), peekBand(펴 보인 호출 블록의 띠), toggle(펼침 삼각형: 접기 영역인지 호출 블록인지, 대상 id, 지금 펴져 있는지). 목록은 바깥이 먼저이고, 한 점을 담는 영역이 여럿이면 editor의 히트 테스트가 가장 작은 영역을 고릅니다 → 3.1 히트 테스트

1.2 텍스트의 크기

  • 텍스트는 줄 바꿈 문자(\n)에서만 줄을 나눕니다. 폭은 가장 긴 줄의 폭, 높이는 줄 수 × space.line입니다.

  • 줄의 폭은 번들 글꼴의 폭 표로 계산하고 정수 px로 올립니다(2장 → ADR-0026). 굵은 텍스트(호출 블록의 Method 이름)의 폭을 어떻게 계산할지는 정하지 않았습니다(→ 미결정 사항).

  • 빈 텍스트도 한 줄로 계산합니다. 빈 블록이 납작해지지 않습니다.

  • 긴 줄은 자동으로 바꾸지 않습니다. 사용자가 적은 줄 그대로 그리고, 줄이 길면 블록이 그만큼 넓어집니다. 가장 넓은 폭도, 말줄임(…)도 없습니다. 줄은 사용자가 텍스트를 편집하는 중에 Shift+Enter로 바꿉니다 → LT1

1.3 줄 (Seq)

줄의 블록은 위에서 아래로 틈 없이 맞붙습니다(NS 차트의 표기).

  • 크기 측정: 폭은 블록들의 최소 폭 가운데 가장 큰 것, 높이는 블록들의 최소 높이의 합입니다.
  • 배치: 모든 블록이 줄의 폭 전체를 받습니다. 높이는 각자의 최소 높이이고, 줄이 받은 높이가 더 크면 남는 높이를 블록 수로 똑같이 나눠 블록마다 더합니다(If의 짧은 분기가 긴 분기와 바닥을 맞추는 경우) → SB1
    • 나누어 떨어지지 않는 나머지는 마지막 블록이 받습니다(정수 px).
    • 블록의 텍스트는 늘어난 블록의 위쪽에 그대로 있습니다(space.pad-y).
    • 제어 블록이 더 받은 높이는 조건 칸이 아니라 안쪽 줄에 갑니다. If · Case는 분기마다 같은 높이를 더 받아 그 분기의 줄이 다시 나누고, 반복은 본문의 줄이 나눕니다. 펴진 접기 영역과 펴 보인 호출 블록도 안쪽 줄이 나눕니다.
  • 테두리가 있는 것(펴진 접기 영역, 펴 보인 호출 블록)은 1.6에서 들여쓰기와 틈을 더합니다.

1.4 블록

텍스트의 폭 · 높이를 tw · th라고 씁니다.

블록최소 폭최소 높이
처리max(size.block-min-w, tw + 2·space.pad-x)th + 2·space.pad-y
호출결과 · 이름 · 인자 텍스트의 폭 + 2·space.pad-x + 2·size.call-barspace.line + 2·space.pad-y (한 줄)
While · Do-While · Formax(tw + 2·space.pad-x, size.loop-strip + 본문의 폭)조건 칸(th + 2·space.pad-y) + 본문의 높이
Ifmax(조건 칸의 폭, 참 분기의 폭 + 거짓 분기의 폭)조건 칸의 높이 + max(두 분기의 높이)
Casemax(조건 칸의 폭, 분기들의 폭의 합)조건 칸의 높이 + max(분기들의 높이)
  • 반복: 본문은 size.loop-strip만큼 오른쪽에 놓입니다. While과 For는 조건 칸이 위, Do-While은 조건 칸이 아래입니다. For는 While과 크기 계산도 렌더링도 같습니다(FB1).

  • If · Case의 분기 폭: 배치에서 받은 폭이 분기들의 최소 폭의 합보다 크면, 남는 폭을 최소 폭에 비례해 분배합니다. 마지막 분기가 나머지를 받습니다.

  • If의 조건 칸: 높이는 조건 텍스트 + 2·space.pad-y + size.if-label(분기 라벨 줄)이고, 최소 폭은 tw + 2·space.pad-x + size.if-head-extra입니다. 참 · 거짓 분기마다 최소 폭은 Case처럼 max(그 분기 줄의 폭, 분기 라벨의 폭 + size.label-room)입니다. 라벨이 긴 분기도 라벨이 칸 안에 들어갑니다. 빗금의 꼭짓점은 참 분기와 거짓 분기의 경계 위에 있습니다. 조건 텍스트는 꼭짓점 위 가운데에 두되 블록 밖으로 나가지 않게 밉니다.

  • 조건 텍스트와 빗금: 조건 칸을 텍스트에 맞춰 넓히거나 높이지 않습니다. 조건이 길면 빗금이 텍스트에 닿을 수 있고, 렌더링하는 단계에서 텍스트 뒤에 조건 칸 배경색의 테두리(size.text-halo)를 깔아 가립니다. 레이아웃의 계산에는 영향이 없습니다 → BH1, 배치 규칙

  • Case의 조건 칸: 높이는 조건 텍스트 + 2·space.pad-y + size.case-label이고, 최소 폭은 tw + 2·space.pad-x + size.case-head-extra입니다. 긴 빗금은 왼쪽 위에서 default 분기의 왼쪽 아래로, 짧은 빗금은 오른쪽 위에서 같은 점으로 갑니다. 분기 사이의 세로선은 긴 빗금에서 내려옵니다. 분기마다 최소 폭은 max(그 분기 줄의 폭, 분기 라벨의 폭 + size.label-room)입니다.

  • 분기 라벨: If는 “참”을 왼쪽 아래 구석에, “거짓”을 오른쪽 아래 구석에 둡니다. Case는 분기 라벨을 칸의 왼쪽에, default의 라벨만 오른쪽에 붙입니다(Q25). 구석과의 거리는 size.label-inset(default도 같음)입니다. 사용자가 라벨을 입력하지 않은 분기는 렌더링 결과의 고정 문구로 표시합니다: If는 “참” · “거짓”(영어 true · false), Case의 default는 한국어 · 영어 모두 default입니다.

  • 이름 없는 호출 블록(호출하는 Method의 이름이 비어 있음)은 이름 위치에 고정 문구 “(이름 없음)“(영어 (no name))을 표시합니다.

  • 분기 라벨의 클릭 영역은 그 칸 위의 라벨 줄입니다. 높이는 If가 size.if-label(16px), Case가 size.case-label(28px)입니다(프로토타입은 둘 다 20px).

  • 빈 분기: If · Case의 분기에 빈 블록 하나만 있으면 그 블록 가운데에 ∅를 렌더링합니다. 크기 측정에는 영향이 없습니다(빈 블록의 크기 그대로) → E1

  • 접힌 분기 · 접힌 본문: ”⋯ 블록 n개” 한 줄의 크기(점 셋의 영역 16px + 텍스트 + 2·space.pad-x, 한 줄 + 2·space.pad-y)로 측정합니다. n은 안의 제어 블록에 든 블록까지 센 수입니다. 배치에서는 그 분기(본문)의 영역을 다 채웁니다. 무엇이 접혔는지는 뷰 상태의 folded에 든 분기의 id, 반복 블록의 id(그 본문)입니다.

  • default가 없는 Case(코드에서 가져온 것, otherwise: null)는 빈 default 칸을 렌더링해 둡니다. 모델에는 분기가 없지만, 레이아웃은 default 칸이 빈 블록 하나인 것처럼 측정하고 놓으며 칸 가운데에 ∅를 렌더링합니다. 그래서 보통 Case와 모양이 같습니다. 이 칸은 LayoutResult에 “없는 default”로 표시해 editor가 구분할 수 있게 합니다 → CD1

  • default만 있는 Case(분기 없음)는 default 칸이 블록 전체입니다. 긴 빗금은 길이가 없어 렌더링하지 않고, 짧은 빗금 하나(오른쪽 위에서 왼쪽 아래로)만 남습니다 → CD2

1.5 헤더

헤더 모양높이최소 폭
모양 그대로 (headStyle: 'shape')size.hat + th + 2·space.pad-ytw + 2·space.pad-x + size.hat-room
제목처럼 (headStyle: 'title')size.title-tag + space.line + size.title-gap = 40px라벨과 이름 가운데 넓은 것. 텍스트는 다이어그램의 왼쪽 선에 맞추므로 space.pad-x를 더하지 않음
  • 다이어그램의 폭은 max(본문의 폭, 헤더의 최소 폭, size.diagram-min-w)입니다. 헤더와 본문이 같은 폭을 받습니다.
  • 헤더가 없는 다이어그램은 본문만 있습니다.
  • Event의 모자는 왼쪽에 size.hat-w 폭으로, Method의 아치는 폭 전체에 걸쳐 솟습니다.

1.6 테두리가 있는 것

펴진 접기 영역(이름 띠를 보일 때)과 펴 보인 호출 블록은 둘레에 테두리를 두르고 맨 위에 띠(size.band)를 붙입니다.

무엇최소 폭최소 높이안쪽 줄의 들여쓰기
펴진 접기 영역max(안쪽 줄의 폭, 띠 텍스트의 폭 + size.band-text-x + size.band-icon-room + space.pad-x)size.band + 안쪽 줄의 높이size.nest-inset
펴 보인 호출 블록max(안쪽 줄의 폭, 띠 텍스트의 폭 + size.band-text-x + size.band-icon-room + space.pad-x)size.band + 안쪽 줄의 높이size.peek-inset
접힌 접기 영역이름의 폭 + 2·space.pad-x + size.fold-icon-room이름의 높이 + 2·space.pad-y + size.fold-extra-h—
  • 들여쓰기는 테두리가 있는 자식에만 적용합니다. 안쪽 줄의 보통 블록은 테두리에 붙고(양옆과 아래로 들여 쓰지 않음), 테두리가 있는 자식만 양옆과 아래에서 들여쓰기만큼 들어갑니다. 그래서 테두리가 겹쳐도 상자가 따로 보입니다 → 접기 · 펼치기
  • 제어 블록을 거쳐 들어간 테두리: 들여쓰기는 테두리 바로 안의 줄에서 끝나지 않고, 제어 블록을 몇 겹 거쳐도 안쪽 줄로 전달됩니다. 안쪽 테두리의 변이 바깥 테두리의 왼쪽 · 오른쪽 · 아래 변에 닿는 곳에서만 그 변을 들여쓰기만큼(4px) 들입니다. 펴진 접기 영역과 펴 보인 호출 블록의 네 조합이 모두 같습니다 → NF1
    • 왼쪽 · 오른쪽: 반복 블록의 본문은 왼쪽 띠 때문에 왼쪽 변에 닿지 않고 오른쪽 변에만 닿습니다. If · Case는 첫 분기가 왼쪽 변에, 마지막 분기(Case는 default 칸)가 오른쪽 변에 닿습니다.
    • 아래: 줄의 마지막 항목만 아래 변에 닿습니다. Do-While의 본문은 그 아래에 조건 칸이 있어 닿지 않습니다.
    • 측정과 배치가 같은 값을 씁니다(Insets). 들인 만큼 바깥의 폭과 높이가 늘어나므로 안쪽 테두리의 폭은 줄지 않습니다. 테두리 안에 테두리가 없는 문서의 출력은 바뀌지 않습니다.
  • 이어진 테두리: 한 줄에서 테두리가 있는 것 둘이 맞붙으면 그 사이를 띄워 size.nest-gap(1px)의 빈 줄이 보이게 합니다. 맞붙은 블록은 경계선 한 줄을 나눠 쓰므로, 높이에는 경계선 1px + 틈 1px = 2px을 더합니다.
  • 이름 띠를 끄면 펴진 접기 영역은 테두리도 띠도 없이, 접기 영역이 없는 것과 똑같이 측정합니다.
  • 접힌 접기 영역의 이름은 블록 글꼴로, 이름 띠의 이름은 보조 크기로 한 줄에 표시합니다. 이름이 없으면 기본 이름(“첫 블록의 텍스트 외 n개”, 고정 문구는 그림 문구의 언어)입니다. 접힌 칸의 텍스트와 띠의 텍스트는 왼쪽 끝에서 20px에서 시작합니다(그 앞은 펼침 삼각형의 영역 → FD8).
  • 렌더링 순서: 테두리와 띠는 그 안의 블록을 렌더링한 뒤에 렌더링합니다. 굵은 테두리가 안쪽 블록의 바깥 선을 덮어야 하기 때문입니다.
  • 보이는 구조: 줄 하나가 보이는 것은 블록과 그 줄의 접기 영역을 묶은 나무입니다(src/packages/core/src/layout/shown.ts). 접기 영역은 시작이 빠른 것, 같으면 긴 것부터 바깥에 둡니다. 펴진 채 이름 띠를 끈 접기 영역은 나무에 넣지 않고 그 안의 것을 그 위치에 둡니다. 레이아웃과 editor의 키보드 이동(→ 2.2 이동)이 같은 나무를 씁니다.
  • 펴 보인 호출 블록의 안쪽은 호출하는 Method의 본문을 그 위치에서 다시 측정하고 놓은 것입니다(모델에는 사본이 없음 → 1.6 펴 보인 곳의 접기 영역). 펴 보인 안쪽의 접힘은 그 호출 경로의 접힘을 따르고(경로의 접힘이 아직 없으면 Method의 접힘 → 2. 뷰 상태), 이 자리의 접기 영역(SiteFold)은 그 위치에서 더합니다. 묶어 둔 블록이 없어졌으면 남은 블록으로 범위를 줄이고, 하나도 없으면 렌더링하지 않습니다.
    • 이 자리의 접기 영역은 첫 블록이 든 Method의 줄에(첫 블록이 없어졌으면 끝 블록의 줄에) 놓습니다. 두 끝이 그 줄에 다 남았으면 그 사이를, 하나만 남았으면 그 블록 하나를 묶습니다.
    • Method의 접기 영역을 이미 복사한 자리(뷰 상태에 b4/가 있는 자리)에는 Method의 접기 영역(FoldMark)을 렌더링하지 않고 이 자리의 접기 영역만 렌더링합니다. 표시가 없는 자리(아직 정리하지 않은 이전 파일)는 Method의 접기 영역을 렌더링합니다 → ADR-0047
    • 함께 렌더링하는 접기 영역과 걸쳐 겹치거나 범위가 똑같은 이 자리의 접기 영역은 렌더링하지 않습니다(Method가 바뀌어 그렇게 된 것이다. Method의 접기 영역과 먼저 놓인 것이 먼저다).
    • 펴 보이는 것은 뷰 상태의 opened에 경로가 든 호출 블록 가운데 같은 문서의 Method를 호출하는 것입니다. 겹쳐 펴 보인 안쪽 호출 블록은 그 경로가 따로 opened에 있어야 펴집니다.

1.7 여러 다이어그램의 배치

규칙은 5. 여러 다이어그램의 배치에 있습니다. 레이아웃은 그것을 이렇게 계산합니다.

  1. 다이어그램을 두 그룹으로 나눕니다: 왼쪽 그룹(Event와 헤더 없는 다이어그램), 오른쪽 그룹(Method). 그룹 안의 순서는 문서의 순서입니다.
  2. 그룹마다 다이어그램을 위에서 아래로 쌓고(사이 space.diagram), 다음 다이어그램이 줄 높이를 넘으면 오른쪽 새 줄에 배치합니다. 한 줄의 폭은 그 줄의 가장 넓은 다이어그램이고, 줄 사이도 space.diagram입니다.
  3. 왼쪽 그룹 오른쪽에 오른쪽 그룹을 놓습니다. 두 그룹 사이는 space.kind-gap(space.diagram의 두 배)만큼 띄웁니다. 구분선이나 텍스트는 넣지 않습니다 → DA1. 한 그룹이 비어 있으면 띄우지 않습니다.
  4. 줄 높이 선택: 줄 높이의 후보는 “가장 높은 다이어그램의 높이”와 size.column-min 가운데 큰 것에서 시작해, 4px씩 올려 그룹 하나를 한 줄에 다 쌓는 높이까지입니다. 후보마다 문서 전체의 폭 · 높이를 계산해 가로 : 세로가 16 : 10에 가장 가까운 것을 선택합니다. 같으면 낮은 줄 높이를 선택합니다. 두 그룹은 같은 줄 높이를 씁니다.
  5. 문서 전체의 둘레에 space.paper를 둡니다.

1.8 지금 프로토타입과 다른 곳

프로토타입(66번째 버전)은 버리는 코드이고, 개발은 이 문서를 따릅니다.

  • 텍스트 폭을 브라우저(canvas.measureText)로 측정합니다. 글꼴도 IBM Plex입니다(이 문서는 번들한 D2Coding의 폭 표).
  • default가 없는 Case(CD1)와 default만 있는 Case(CD2)는 편집 명령으로 만들 수 없어(코드에서 가져올 때만 생김) 렌더링하지 않습니다.
  • 접기 영역의 이름을 보이는 실험용 모양 둘(“왼쪽 여백에 이름”, “구석에 이름”)이 남아 있습니다. 정한 것은 이름 띠를 켜고 끄는 것뿐입니다.
  • 펴 보기의 흰 배경과 흰 줄이 토큰이 아니라 코드에 하드코딩된 값입니다.

2. 텍스트 폭 측정

정한 것: 글꼴을 번들하고, 그 글꼴 파일의 글리프 advance 폭 테이블로 core가 계산한다. 셸이 주입하지 않는다(브라우저의 텍스트 측정 API를 쓰지 않음). 커닝을 끄고 정수 px로 올림한다 → ADR-0026

정한 것: 기본 블록 글꼴은 D2Coding 보통 하나이고, 한자를 뺀 문자를 포함한다 → ADR-0034

2.1 advance 폭 테이블

D2Coding 1.4.0(unitsPerEm 1000)의 문자 폭은 두 가지뿐입니다: 반각 500(라틴 등, 13px에서 6.5px)과 전각 1000(한글 등, 13px에서 13px). 포함하는 문자 12,824자 가운데 1,259자가 반각, 11,565자가 전각입니다.

  • 포함하는 문자는 아래 유니코드 블록 17개 안에서 D2Coding에 글리프가 있는 것입니다(한자는 포함하지 않음 → ADR-0034): ASCII(U+0020–007E), Latin-1(U+00A0–00FF), 라틴 확장 A · B(U+0100–024F), 그리스(U+0370–03FF), 키릴(U+0400–04FF), 일반 구두점(U+2000–206F), 화살표(U+2190–21FF), 수학 연산자(U+2200–22FF), 상자 그리기(U+2500–257F), 도형(U+25A0–25FF), CJK 기호와 구두점(U+3000–303F), 히라가나(U+3040–309F), 가타카나(U+30A0–30FF), 한글 호환 자모(U+3130–318F), 한글 음절(U+AC00–D7A3), 반각 · 전각 형태(U+FF00–FFEF).

  • 번들한 글꼴과 폭 테이블은 D2Coding 릴리스 파일(sha256으로 확인)에서 스크립트가 만들어 저장소에 넣어 둡니다(src/packages/fonts/scripts/build-fonts.py). 글꼴 파일 안의 이름은 AriadneNSD Mono입니다(D2Coding은 OFL의 예약 글꼴 이름 → 4.3 글꼴).

  • 테이블은 “같은 폭이 이어지는 코드 포인트 구간”의 목록으로 기록합니다: 기본 폭(전각 1000)과, 기본 폭이 아닌 구간들 [시작, 끝, 폭]. 구간은 50개이고 JSON으로 약 0.8 KB라 core에 그대로 포함합니다.

  • 굵게(D2Coding Bold)의 폭은 보통과 모든 문자에서 같습니다. 굵은 텍스트도 같은 테이블로 계산합니다.

  • 테이블에 없는 문자는 전각(1000)으로 계산합니다(→ ADR-0037). 번들 글꼴에 없는 문자(한자, 이모지, 포함하지 않은 문자)는 렌더링하는 쪽이 다른 글꼴로 렌더링하므로 폭을 알 수 없습니다. 넓게 계산하면 텍스트가 블록 밖으로 나가지 않고, 한자와 이모지는 대개 전각입니다. 반각 문자가 테이블에 없으면 블록이 조금 넓어질 뿐입니다.

  • 줄의 폭은 문자 폭의 합을 픽셀로 바꾼 뒤 정수 px로 올립니다. 예: n > 0은 33px, a[j] <= pivot && j < hi는 150px, i ← i + 1은 59px.

2.2 서브셋 글꼴의 크기

저장 파일에는 문서에 쓰인 문자만 추린 서브셋을 포함합니다(커닝 · 합자 · 힌팅 없음). 이름 레코드(name 테이블)는 모두 남깁니다: 글꼴 이름(AriadneNSD Mono)과 저작권 · OFL 고지가 저장 파일 안의 글꼴에도 따라가야 하기 때문입니다. 문서에 쓰인 서로 다른 문자 수에 따라:

문서압축하지 않은 TTFWOFF (저장 파일)woff2
영어만 (ASCII 95자)9.6 KB6.9 KB5.2 KB
한글 100자 + ASCII23 KB15 KB12 KB
한글 300자 + ASCII51 KB29 KB23 KB
한글 800자 + ASCII118 KB61 KB48 KB
(편집기에 포함하는 글꼴 전체, 12,824자)1,335 KB532 KB327 KB (편집기에 포함하는 형식)

한글은 이 저장소의 docs/에서 자주 쓰는 순서로 선택했습니다. 자주 쓰는 음절은 자모 글리프를 함께 쓰는 복합 글리프라 작게 나옵니다. 같은 300자를 한글 음절 전체에서 고르게 흩어 고르면 TTF 81 KB, WOFF 44 KB로 커집니다(2026-11-01, src/packages/fonts/node/subset.test.ts). 측정한 스크립트: journal/assets/2026-10-25-d2coding-metrics-spike.py(결과 …-spike.json)

저장 파일에는 WOFF로 포함합니다. 압축은 버전을 고정한 JS zlib 라이브러리로 하고, 브라우저에 든 압축기는 쓰지 않습니다(브라우저마다 바이트가 달라질 수 있어 “같은 모델이면 같은 파일”(R-FMT-03)을 지키지 못함) → ADR-0039

3. SVG 렌더링

MVP 코드(2026-11-01)에서 정한 그림 부분의 형식입니다.

  • SVG 요소와 클래스: 그림 요소는 <g class="ans-render"> 하나이고, 전체를 반 픽셀 옮기며(translate(.5 .5) → 9.1 픽셀에 맞추기), font-family(번들 글꼴 다음에 폴백 목록)와 font-kerning:none을 그 요소에 지정합니다. 안에는 <rect>(칸) · <path>(선, 빗금) · <circle>(∅) · <text>(굵은 부분과 구문 강조의 색은 <tspan> → 3.1)만 두고, 색은 클래스가 아니라 fill · stroke 값으로 지정합니다(src/packages/core/src/render/to-svg.ts) → 4. 그림 부분
  • 요소별 출력: 숫자는 좌표 규칙대로 기록합니다. 값이 없는 속성은 쓰지 않습니다.
요소속성
칸 <rect>x y width height fill stroke stroke-width, shape-rendering="crispEdges"(가로세로 선이 픽셀에 맞게)
선 <path>d(M · L), fill="none", stroke, stroke-width. 점선은 stroke-dasharray, 둥근 끝은 stroke-linecap="round"
도형 <path>d(M · L · C, 끝에 Z로 닫음), fill, stroke, stroke-width
원 <circle> (∅)cx cy r, fill="none", stroke, stroke-width
텍스트 <text>x y font-size fill, xml:space="preserve"(빈칸을 그대로). text-anchor는 시작 정렬이면 생략. 테두리(halo)가 있으면 stroke, 테두리 두께의 2배인 stroke-width, stroke-linejoin="round", paint-order="stroke"
텍스트 런 <tspan>기본과 다른 것만: font-weight, fill, font-style="italic". 다른 것이 없으면 <tspan>을 쓰지 않음
  • 디자인 토큰 맵: buildScene()이 테마(토큰 이름 → 색 값, src/packages/core/src/render/theme.ts)를 받아 문서 레이어를 렌더링합니다. 테마는 넷(themes: default · dark · high-contrast · print)이고, 저마다 종이의 종류(kind: light · dark)를 가집니다. themeFor(id)는 지원하지 않는 이름에 기본 테마를 반환합니다. 오버레이 레이어는 editor가 테마의 종류에 맞는 편집 색으로 따로 렌더링합니다(src/packages/editor/src/dom/overlay.ts, ADR-0044) → 2. 레이어와 출력, 9. 렌더링 규칙(픽셀 스냅)

  • 고정 문구의 로캘: layout()이 문서 설정의 그림 문구의 언어(settings.locale)를 읽어, 렌더링 결과에 표시하는 고정 문구(“참” · “거짓” 등)를 core의 메시지 카탈로그(src/packages/core/src/i18n/messages.ts)에서 고릅니다. 화면 언어는 받지 않습니다. 그래서 같은 문서는 화면 언어와 상관없이 같은 렌더링 결과가 됩니다 → R-NFR-04, ADR-0041

  • 텍스트를 외곽선으로(R-FMT-10, 문서 설정 textOutlines): toSvg가 텍스트 요소를 번들 글꼴의 글리프 외곽선으로 직렬화합니다(src/packages/core/src/render/outline-text.ts). 글리프는 advance 폭대로 나란히 놓습니다(커닝 · 셰이핑 없음, 2.1과 같은 폭). 한 요소는 글자색마다 보통 글자 하나, 굵은 글자 하나의 <path>가 되고(Q 곡선, 좌표는 소수 둘째 자리), 테두리(halo, UX BH1)는 그 아래에 같은 모양을 보통 글자와 굵은 글자로 나눠 획으로 먼저 렌더링합니다. 굵은 글자는 같은 모양에 글자색 획을 더합니다(브라우저의 합성 굵게와 같은 두께: 크기의 1/24(9px 이하) ~ 1/32(36px 이상)). 기울임 런의 글리프는 외곽선의 각 점을 기준선에서의 높이의 1/4만큼 오른쪽으로 옮겨 기울입니다(약 14도, 브라우저의 합성 기울임과 같은 값). advance 폭은 그대로라 레이아웃은 바뀌지 않습니다(SL1). 번들 글꼴에 없는 문자가 든 요소는 텍스트로 남고, 서브셋 글꼴에는 그런 요소의 문자만 넣습니다. 글리프 외곽선은 fonts의 readGlyphOutlines가 번들 TTF의 glyf · cmap · hmtx에서 읽습니다 → 4.3 텍스트 외곽선

  • PNG는 웹 셸이 저장 파일의 SVG를 캔버스에 그려 만듭니다 → 1.2 PNG 내보내기. PDF는 같은 장면을 5장의 페이지로 나눠 씁니다.

3.1 구문 강조

블록 텍스트를 문서 설정의 블록 텍스트의 언어(settings.textKind → R-LAY-06)로 칠합니다(R-LAY-07). 화면과 저장 파일 · PNG가 같은 색입니다(ADR-0018).

  • 어디서: buildScene()이 settings.textKind를 받아 칠합니다(src/packages/core/src/render/build-scene.ts). 레이아웃은 언어를 읽지 않습니다. 언어와 상관없이 글꼴과 굵기가 같아 폭이 같으므로, 언어를 바꾸면 색만 바뀝니다 → ADR-0042
  • 무엇을: 처리 블록의 텍스트와 반복 · If · Case의 조건 칸입니다. 헤더의 이름, 분기 라벨, 호출 블록은 칠하지 않습니다 → SY1
  • 렉서: 언어마다 하나이고(src/packages/core/src/text/syntax.ts → ADR-0032), 텍스트를 키워드 · 문자열 · 숫자 · 주석 · 그 밖으로 구분합니다. 블록 하나의 텍스트 전체를 한 번에 가른 뒤 줄로 나누므로, 블록 주석은 여러 줄에 걸쳐 칠해집니다. 블록 사이로는 이어지지 않습니다.
  • SVG: 색이 있는 토큰은 <text> 안의 <tspan fill="…">입니다. 그 밖의 토큰은 <text>의 fill(text.primary)을 따릅니다. 색은 테마의 syntax.keyword(키워드) · syntax.comment(주석) · syntax.literal(문자열과 숫자) 토큰입니다 → 3.3 밝은 기본 테마

언어마다의 규칙입니다. 블록의 텍스트는 문법상 완전하지 않은 조각이라 렉서는 실패하지 않습니다.

언어 (textKind)주석문자열그 밖
일반 텍스트 (plain)칠하지 않음칠하지 않음칠하지 않음
C (c)// · /* */"…" · '…'줄 처음의 #include 같은 지시문은 키워드. C23의 키워드까지
C++ (cpp)// · /* */"…" · '…'지시문은 키워드. 숫자 안의 '(1'000)는 숫자의 일부
Java (java)// · /* */"…" · '…' · """…"""(여러 줄)$는 이름의 일부
JavaScript · TypeScript (javascript)// · /* */"…" · '…' · `…`(여러 줄)TypeScript의 키워드(interface · type 등)도 키워드. 타입 이름(number · string)은 변수 이름으로도 흔해 칠하지 않음
Python (python)#"…" · '…' · """…""" · '''…'''(여러 줄). 접두사(f"…" · rb'…')까지 한 문자열//는 나눗셈이라 주석이 아님
Bash (bash)토큰 처음의 #만(${#a} · a#b는 주석이 아님)"…" · '…'(둘 다 여러 줄. '…' 안의 백슬래시는 이스케이프가 아님)예약어와 그처럼 쓰는 내장 명령(local · export · return 등). $는 이름의 일부

언어마다의 키워드입니다(src/packages/core/src/text/syntax.ts).

언어키워드
Cauto break case char const continue default do double else enum extern float for goto if inline int long register restrict return short signed sizeof static struct switch typedef union unsigned void volatile while _Bool _Complex _Imaginary _Alignas _Alignof _Atomic _Generic _Noreturn _Static_assert _Thread_local alignas alignof bool constexpr false nullptr static_assert thread_local true typeof typeof_unqual
C++alignas alignof and and_eq asm auto bitand bitor bool break case catch char char8_t char16_t char32_t class co_await co_return co_yield compl concept const const_cast consteval constexpr constinit continue decltype default delete do double dynamic_cast else enum explicit export extern false final float for friend goto if inline int long mutable namespace new noexcept not not_eq nullptr operator or or_eq override private protected public register reinterpret_cast requires return short signed sizeof static static_assert static_cast struct switch template this thread_local throw true try typedef typeid typename union unsigned using virtual void volatile wchar_t while xor xor_eq
Javaabstract assert boolean break byte case catch char class const continue default do double else enum extends final finally float for goto if implements import instanceof int interface long native new package private protected public return short static strictfp super switch synchronized this throw throws transient try void volatile while true false null var record yield sealed permits
JavaScript · TypeScriptasync await break case catch class const continue debugger default delete do else export extends false finally for function if import in instanceof let new null of return static super switch this throw true try typeof undefined var void while with yield abstract as declare enum implements interface keyof namespace private protected public readonly satisfies type
PythonFalse None True and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield match case
Bashif then else elif fi case esac for select while until do done in function time break continue return exit local export readonly declare
  • 닫지 않은 문자열은 그 줄의 끝까지(여러 줄 문자열은 텍스트의 끝까지), 닫지 않은 블록 주석은 텍스트의 끝까지입니다.
  • 숫자는 토큰의 처음에서만 셉니다(x1의 1은 이름). 0x1F · 1.5e-3f · .5처럼 접두사 · 지수 · 접미사까지 한 숫자이고, 범위 1..10의 점은 숫자가 아닙니다.
  • 이름은 모든 문자(한글 포함)로 이루어질 수 있고, 키워드와 문자가 같을 때만 키워드입니다(합계if는 이름).

4. 성능

목표: 블록 500개 문서에서 편집 한 번이 100ms 안에 화면에 반영된다(QA-07).

정한 것: 편집할 때마다 문서 전체를 처음부터 다시 계산합니다(→ ADR-0037). 바뀐 하위 트리만 다시 계산하는 증분 레이아웃(메모이제이션)은 하지 않습니다. 측정해 보니 레이아웃과 SVG 만들기는 1ms 안팎이고, 시간의 대부분은 만든 SVG를 화면에 넣는 단계였습니다. 빨라져야 하면 줄일 곳은 레이아웃이 아니라 화면 갱신(바뀐 요소만 바꾸기)입니다.

블록 수레이아웃장면 + SVG 문자열화면에 반영합계합계 (느린 5%)
5000.2 ~ 0.3 ms0.2 ~ 0.4 ms8 ~ 10 ms9 ~ 11 ms16 ~ 29 ms
1,0000.4 ms0.6 ms19 ~ 20 ms21 ms33 ~ 58 ms
2,0000.7 ms1.2 ~ 1.3 ms37 ~ 45 ms39 ~ 47 ms63 ~ 137 ms
  • 측정한 곳: 메인테이너의 컴퓨터, Microsoft Edge 156(Chromium) / Windows, 세 번 측정한 값의 범위. 스파이크 M39(https://claude.ai/artifact/SRbqzTEA12ZVKc61YcKCXd, 사본 journal/assets/2026-10-25-layout-perf-spike.html, 결과 …-results.txt)
  • 스파이크는 이 문서의 두 단계(1.1)와 분기 폭 · 짧은 분기의 규칙을 그대로 실행했습니다. 접기 영역의 테두리, 펴 보기, 구문 강조, 클릭 영역은 넣지 않았습니다.
  • 기준 기기(4년 된 보급형 노트북)에서는 아직 측정하지 않았습니다. 그래도 500개에서 느린 5%가 목표의 3분의 1 아래라 여유가 있습니다.
  • 펴 보인 호출 블록 때문에 렌더링되는 블록이 2,000개가 되어도 중앙값은 50ms 아래였습니다 → 8. 위험과 검증이 필요한 사항
  • 제품 코드의 벤치마크는 src/packages/core/src/render/render.bench.ts이고 pnpm --filter @ariadne-nsd/core exec vitest bench --run으로 실행합니다 → 5. 도구와 CI

5. 인쇄와 PDF의 페이지

PDF와 인쇄(R-EXP-03)는 같은 페이지 나누기를 씁니다(src/packages/core/src/export/paginate.ts). 정한 과정 → PD2, PD3

  • 크기: 렌더링 결과를 줄이지 않습니다. 1px = 0.75pt(CSS 기준 픽셀, 96dpi)라서 가장 가는 선 0.75pt, 가장 작은 텍스트 9pt가 지켜집니다 → 9.2 배율과 출력
  • 종이와 여백: A4(595.28 × 841.89pt) 또는 Letter(612 × 792pt). 여백은 네 쪽 모두 36pt(12.7mm)이고, 그 안이 그림의 자리입니다(A4 세로: 698 × 1026px).
  • 방향: 세로와 가로로 각각 나눠 보고 페이지가 적은 쪽을 씁니다. 같으면 세로입니다. 한 문서의 페이지는 모두 같은 방향입니다.
  • 자르는 곳: 자르면 안 되는 상자는 텍스트가 든 칸입니다: 처리 · 호출 블록, 제어 블록의 헤더(If · Case의 갈래 이름 줄 포함), 다이어그램의 헤더, Case의 빈 default 칸. 제어 블록의 옆 벽은 잘려도 됩니다. 한 페이지가 들일 수 있는 데까지에서 어느 칸도 가로지르지 않는 가장 먼 칸의 경계에서 자릅니다. 그런 경계가 페이지의 4분의 1보다 앞에만 있으면(칸 하나가 페이지보다 큼) 페이지 끝에서 그대로 자릅니다.
  • 넓은 다이어그램: 다이어그램의 폭이 한 페이지를 넘으면 같은 규칙으로 세로 줄(열)로 먼저 나누고, 열마다 위의 규칙으로 페이지를 나눕니다. 페이지의 차례는 첫 열을 위에서 아래로, 그다음 열입니다(스프레드시트의 “아래로, 그다음 옆으로”). 종이만 있는 페이지(그 열의 그 높이에 칸이 없음)는 뺍니다.
  • 자른 곳의 선: 페이지는 오른쪽 · 아래로 1px을 더 보여, 자른 곳의 선이 두 페이지 모두에 보입니다.
  • 쪽 번호: 페이지가 둘 이상이면 아래 여백 가운데에 “n / N”을 9pt, text.muted 색으로 표시합니다. 하나면 표시하지 않습니다.
  • PDF의 렌더링(src/packages/core/src/export/pdf.ts): PDF 1.4, 페이지마다 그 부분만 잘라(clip) 장면의 요소 가운데 그 페이지에 걸치는 것만 씁니다. 텍스트는 글리프 외곽선이고, 글리프마다 한 번 폼 XObject로 두고 쓰는 곳에서 참조합니다(채움 · 테두리용 획 · 합성 굵게, 그리고 그 각각의 기울임을 따로). 기울임은 폼의 외곽선에 적용하므로 획의 두께는 기울지 않습니다. 번들 글꼴에 없는 문자는 빈 상자(전각 폭)입니다. 스트림은 저장 파일의 WOFF와 같은 zlib 설정으로 압축합니다. 날짜를 넣지 않아 같은 그림이면 같은 바이트입니다. 제목(/Title)은 문서 이름입니다.

미결정 사항

  • 굵은 텍스트: 기본 블록 글꼴은 D2Coding 보통 하나입니다. 굵게 쓰는 곳(호출 블록의 Method 이름, 접기 영역의 이름 띠, “제목처럼” 헤더의 이름)은 MVP 뒤로 미뤘으므로(ADR-0034), 그것들을 넣을 때 굵은 글꼴을 더 포함할지, 렌더링하는 쪽이 굵게 만든 텍스트(합성 굵게)로 그릴지 정합니다. D2Coding Bold의 폭은 보통과 같습니다(2.1) → 1.2