Visual Summary → 텍스트 대치2026.09.18 · 현재 코드 기준

같은 Title이어도,
들어가는 내용은 다르다.

Title · Subtitle · Description의 대치는 매칭 경계와 Frame에서 맡은 필드로 결정된다. 문서 제목, 각 항목의 내용, 원문 보존을 실제 함수로 계산한 여덟 가지 예시로 따라간다.

화면 /comp-frame코드 20bd9b357예시 8개 함수 실행 검증

역할 이름과 입력 필드를 먼저 구분한다

Title / Subtitle / Description은 컴포넌트의 RLSC 역할이다. Visual Summary 입력은 title, entities[].label, value + unit, items[]에 내용을 담는다. 이름이 비슷해도 서로 같은 분류가 아니다.

Title

문서 제목 또는 항목 제목

문서 제목 자리 → VisualSummary.title
항목의 label 자리 → entity.label

여러 항목의 Title은 각각 대치될 수 있다. 문서 제목을 넣는 별도 자리는 한 곳이다.

Subtitle

값 슬롯이면 수치 대치

value로 매핑된 항목 슬롯 → entity.value + entity.unit
예: 80%

공통 부제(satellites.subtitle)는 원문 유지. 경계 밖에서 제목으로 선택되면 문서 제목이 들어간다.

Description

목록 슬롯이면 설명 대치

items로 매핑된 항목 슬롯 → entity.items[]
예: 이번 주 8명 완료

공통 설명(satellites.desc)은 원문 유지. 슬롯 밖에 남은 텍스트는 안/밖에 따라 처리가 다르다.

일대일 고정 규칙은 아니다. IIS 경로는 저장된 entities[].fields의 노드 매핑을 사용한다. 규칙 기반 Frame·보강 경로에서는 첫 Title → label, 첫 Subtitle → value, Description → items가 기본이다. 같은 항목의 두 번째 이후 Title·Subtitle은 items에 포함될 수 있다.

아래 예시는 value를 읽는 KPIKeyMetric.BigNumber 카테고리다. 모든 카테고리가 같은 필드를 읽지는 않는다. 예컨대 List의 IIS 필드에 value를 임의로 추가한다고 그대로 값 슬롯이 되는 것은 아니다.

경계는 사각형이 아니라, 선택한 하위 트리

검색 결과의 node_id가 기준이다. 그 노드와 후손이면 경계 안, 나머지는 경계 밖이다. 화면에서 글이 배경 도형 위에 올라가 있는지는 이 분류의 입력이 아니다.

RLSC · node_id = body

root
- header · 경계 밖
  - head1 Title
  - head2 Subtitle
  - head3 Description
- body ← 매칭 경계
  - card1 → Title / Subtitle / Description
  - card2 → Title / Subtitle / Description

root를 매칭하면 header와 body가 모두 안에 들어가며, 경계 밖 목록은 빈다.

경계 밖문서 제목 후보 / 나머지는 원문

같은 노드라도 다른 검색 결과의 node_id를 기준으로 보면 안/밖이 달라질 수 있다.

경계 안Frame 매핑으로 처리

항목 슬롯 → 내용 대치
공통 머리말 → title 대치, subtitle·desc 보존
미매핑 잔여 → 임시 문구 / 보존 예외

정확한 목록 계산과 예외

outside_text = 전체 Text − 경계 하위 트리의 Text − 이미 Frame 슬롯이 참조하는 Text. 규칙 기반 fallback이 경계 밖 노드를 이미 슬롯으로 사용하면 중복 대치 후보에서 제외한다. 경계 안 미매핑 목록은 경계의 Text 중 Frame 슬롯이 참조하지 않는 노드다. 원래 id가 없거나 경계 노드를 찾지 못한 경우는 목록에서 제외한다. 화면은 저장된 inside_unbound_text를 우선 사용하고 필요하면 RLSC를 순회한다.

어디에 속했는지에 따라 갈라지는 대치 흐름

컴포넌트의 Text 노드선택된 경계 + 저장된 Frame 슬롯 확인

INSIDE · 매핑된 필드가 기준

항목의 label / value / items 슬롯?

Visual Summary의 해당 항목 내용을 대치한다. 여러 항목의 Title도 각각 처리한다.

실제 내용 대치

공통 머리말(satellites)?

첫 Title → 문서 제목. 추가 Title → desc.
Subtitle·desc → 원문 유지.

첫 제목 외 공통 문구 보존

빈 슬롯 또는 미매핑 텍스트?

임시 문구로 채운다. 한 글자·VS·숫자+단위 등 shouldPreserveText에 해당하면 원문을 남긴다.

임시 문구 / 보존 예외

OUTSIDE · 문서 제목 한 곳 선택

문서 제목이 비었거나 이미 field: title로 매핑됨?

경계 밖 추가 대치를 하지 않는다.
field: label인 항목 제목은 이 차단 조건이 아니다.

조건에 해당 → 전부 원문 유지

Title이 있으면 Title만 후보로

없으면 Subtitle·Description 등 경계 밖 Text 전체를 후보로 삼는다.

위쪽 · 왼쪽 · 큰 글꼴을 합산

한 곳에 VisualSummary.title을 넣는다. 선택되지 않은 문구는 원문을 유지한다.

문서 제목 1곳 대치

경계 밖 제목 점수위쪽 정도 × 0.45 + 왼쪽 정도 × 0.20 + 글꼴 크기 × 0.35

각 축은 0~1로 정규화한다. 위치는 컴포넌트 박스, 글꼴 크기는 후보들 사이 최솟값·최댓값 기준이다. 동점이면 트리 순회상 앞선 후보가 이긴다. sheetJson이 아직 없으면 측정값이 없어 후보 순서로 선택하고, 도착하면 다시 계산한다. 경계 안의 공통 Title은 이 점수 대신 순회 순서상 첫 번째를 사용한다.

예시를 바꾸며 대치 전후를 비교한다

같은 Visual Summary를 서로 다른 역할·경계 구성에 넣었다. 썸네일은 합성 컴포넌트의 설명용 SVG이며, 표시한 문구·매핑·점수는 실제 buildIisFrame → buildQueryFrames → align → nodeTextMapFromResult 실행 결과다. 제품 렌더 엔진의 화면 캡처나 운영 데이터 실측은 아니다.

항목 / 문서 제목 대치경계 밖 제목 선택원문 유지임시 문구

BEFORE컴포넌트 원문

AFTER이 Visual Summary의 대치 결과

입력 Visual Summary

현재 화면의 입력 파서로 검증한 YAML. 부제·설명이라는 별도 최상위 입력은 없다.

version: '0.5'
title: 우리 팀의 실행 현황
components:
  - type: KPIKeyMetric.BigNumber
    structure:
      entities:
        - label: 고객 인터뷰
          value: 80
          unit: '%'
          items:
            - 이번 주 8명 완료
        - label: 시제품 검증
          value: 60
          unit: '%'
          items:
            - 사용성 테스트 진행

이번 사례에서 선택한 자리

노드별 대치·보존 결과 전부 보기

노드 / 역할	위치 · 필드	처리	최종 문구

Title이 여러 개일 때, 이 세 가지를 구분한다

Title이 있는 곳	무엇을 대치하나	나머지 Title은?
경계 밖	Title 후보들의 점수로 한 곳에 문서 제목	원문 유지
경계 안 · 항목 슬롯	각 항목의 매핑 필드에 해당하는 내용	항목마다 각각 대치 가능. 규칙 Frame의 추가 Title은 items가 될 수 있음
경계 안 · 공통 머리말	순회상 첫 Title에 문서 제목	satellites.desc에 들어가 원문 유지

“Subtitle·Description은 대치에서 제외된다”는 일괄 해석은 맞지 않는다. 항목 슬롯이면 해당 내용으로 대치되고, 경계 밖에 Title이 없으면 문서 제목의 목적지로도 선택된다. 공통 부제·공통 설명으로 분류된 경우에 원문을 유지한다.

제목이 비어 있으면 바깥 제목 채움 함수는 아무것도 하지 않는다. 다만 현재 화면의 전체 Visual Summary 입력 스키마는 빈 title을 거부하므로, 이를 정상 입력 예시로 제시하지 않았다. 이 문서는 경계 노드 전수 집계나 삭제 영향률을 재측정하지 않았다.

현재 구현을 기준으로, 확인 범위를 남긴다

기준은 miricanvas-iui@20bd9b3570d35aa0949cb281de20c17116adc90c의 현재 /comp-frame 화면이다. 해당 라우트는 통합 VisualSummary를 띄우며 공유 FrameResultCard에서 본문의 대치 함수를 호출한다. 인용 파일의 워킹트리와 커밋이 동일한지 확인했다.

195개 기존 테스트 통과

제목 후보, 대치 지도, 안/밖 잔여, align, IIS·규칙 Frame 구성 · 7개 파일

8개 예시 직접 실행

입력 스키마 검증 + 실제 함수 호출 + 기대 노드·대치 문자열 assertion

합성 예시는 대치 단계만 격리해 확인한다. 검색 후보 조회·순위·운영 DB의 현재 적재 상태·실제 렌더러의 줄바꿈과 폰트 축소는 검증 범위에 포함하지 않았다. 공유 화면의 동작이며 별도 SDK의 title_target 소비 경로 전체를 설명하는 문서는 아니다.

확인한 로직	고정 커밋 코드
현재 화면 · 공유 대치 호출	src/comp-frame/FrameResultCard.tsx:630
IIS 경계와 공통 머리말 슬롯	packages/comp-frame-index/src/frame/component-frame.ts:1134
규칙 기반 항목의 Title / Subtitle / Description	packages/comp-frame-index/src/frame/component-frame.ts:1446
Visual Summary → query Frame	src/comp-frame/query-frame.ts:127
항목 정렬과 공통 머리말 보존	src/comp-frame/align.ts:698
경계 밖 Text 수집	packages/comp-frame-shared/src/outsideText.ts:84
경계 안 미매핑 Text 수집	packages/comp-frame-shared/src/insideResidue.ts:66
Title 우선 + 가중 점수로 하나 선택	src/comp-frame/titleCandidate.ts:245
중복 제목 차단 / 실제 대치 지도	src/comp-frame/resultMaps.ts:128

규약과 구현의 차이, 이전 문서

Visual Summary 규약 §7은 label → Title, items → Description 같은 대응을 제시하지만 전체 RLSC 매핑은 아직 완결되지 않았다고 명시한다. 경계 밖 제목의 가중치, 공통 부제 보존, 잔여 텍스트 임시 문구 등은 여기서 인용한 현재 comp-frame 구현을 설명한 것이며 규약 전체의 공통 계약으로 확대하지 않는다.

aippt 구현의 README·_SIGNATURE와 연결된 규약·capability·내용 대치 contract도 함께 확인했다. 기존 comp-sign 검색 설명은 이전 판: 텍스트는 어디서 개입하나에 보관했다.

재현에 사용한 입력·산출물·스크립트

단일 HTML 안에 여덟 예시의 입력, RLSC, Frame 위성 슬롯, binding / preserve / outside_text / inside_unbound_text, 노드별 최종 문구를 포함했다. 스크립트는 위 고정 커밋의 iui 저장소 out/text-matching-doc-20260918/ 아래에서 실행하도록 작성했다.

예시·산출물 JSON 저장 · 재현 TypeScript 저장

node node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/dist/cli.mjs \
  out/text-matching-doc-20260918/build-examples.ts