sheetJson 해부도

type PageData = {
  id:              string;     // pageId (uuid) — 컨버팅 때 generateUUID()로 새로 발급
  designId:        string;     // 소속 디자인. 컴포넌트 단독 sheetJson에도 실려 있다
  width:           number;     // ← SHEETSIZE.cx   (§3)
  height:          number;     // ← SHEETSIZE.cy   (§3)
  position?:       number;     // 디자인 안에서 이 페이지가 몇 번째인가
  rootNodeIds:     string[];   // ★ 그리는 순서 = z-order  (§5)
  nodes:           NodeData[]; // ★ 평평한 조회 테이블      (§4)
  data:            { props: PageProps }; // 페이지 자체의 속성
  backgroundNodeId?: string;   // 배경 노드는 rootNodeIds 밖에 따로 산다
  template?:       PageTemplateReference;
};

// data.props 안에 실제로 들어 있는 것
data.props.boundingBox   // { left:0, top:0, width:1920, height:1080 } — 캔버스 크기
data.props.shape.fill    // 배경색/배경 이미지
data.props.guidelines    // 안내선 (XML GUIDELINES에서 변환)
data.props.playback      // 페이지 재생 시간·인트로/아웃트로 애니메이션
data.props.templateReference

노드 하나

type NodeData = {
  id:            string;
  pageId:        string;
  rootNodeId?:   string;   // 이 노드가 속한 최상위 노드(그룹 조상)의 id
  parentNodeId:  string;   // ★ 부모 노드 id. 페이지 직속이면 문자열 'NONE' (null 아님!)
  childNodeIds:  string[]; // ★ 자식 순서 = 그룹 내부의 z-order
  position?:     number;
  backgroundNodeId?: string;
  data: {
    nodeType: string;  // 'TextItem' | 'GroupItem' | 'ShapeItem' | 'ComponentItem' | ...
    props:    NodeProps; // nodeType마다 다른 속성 덩어리
  };
};

const rootNodeData = nodes?.find(
  (n) =>
    (n.data.nodeType === NODE_TYPE.COMPONENT_ITEM ||
     n.data.nodeType === NODE_TYPE.COMPONENT_ITEM_V2) &&
    n.parentNodeId === 'NONE'
);

nodeType — 대충 20종

const pageBoundingBox = {
  left: 0, top: 0,
  width:  validatedPageXmlSchema.SHEETSIZE.properties.cx,
  height: validatedPageXmlSchema.SHEETSIZE.properties.cy,
};
// …
const pageJson: PageJson = {
  id: pageId,                // generateUUID() — XML의 PagePersistentKey와 맵으로 연결만 해 둔다
  designId,
  rootNodeIds,             // 이 시점엔 아직 [] — 요소 변환이 끝나야 채워진다 (§5)
  backgroundNodeId: backgroundNode?.id,
  data: { props: {
    boundingBox: pageBoundingBox,
    playback,
    guidelines: convertXmlGuidelinesToJson(pageGuideline, pageBoundingBox),
    shape: nodeShape,
  } },
  width:  pageBoundingBox.width,
  height: pageBoundingBox.height,
  nodes: [],                // 이 시점엔 아직 [] — assignNodesToPages()가 나중에 채운다
};

좌표는 부모 기준 상대값이다

실제로 터진 사고 — 배경이 글자를 덮다

① XML 컨버터 — 원본 포맷의 문지기

② 엔진 직렬화 — Page 객체를 다시 JSON으로

export const makePageCreateCommandChunk = (page, currentPageIds?) => ({
  id: page.getId(),
  data: { props: page.props },
  rootNodeIds: page.getChildren().map((c) => c.getId()),   // ← 화면 순서 그대로
  nodes: nodes.map((c) => makeNodeCreateCommandChunks(c, page.getId())).flat(),
  width:  page.props.boundingBox.width,                      // ← boundingBox가 정본
  height: page.props.boundingBox.height,
  template: page.props.templateReference,
  backgroundNodeId: backgroundNode?.getId(),
});

// 자식은 재귀로 평탄화 — 여기서 트리가 flat 배열이 된다
// makeNodeCreateCommandChunks.ts:34
parentNodeId: parentNode && parentNode !== page ? parentNode.getId() : 'NONE',

③ 손조립 — 최소 껍데기

export const buildPageJson = (nodes: PageNode[]) => ({
  id: nodes[0].pageId || uuidv4(),
  data: PAGE_JSON_DEFAULT_DATA,      // boundingBox 1920×1080 + 흰 배경 + 안내선 2개
  rootNodeIds: [nodes[0].id],       // 첫 노드는 GroupItem 이라는 약속
  nodes,
  width: 1920, height: 1080,
  position: 0,
  designId: uuidv4(),
});

메시지 프로토콜

parent → iframe   COMPONENT_THUMBNAIL_PING       // 살아 있니?
iframe → parent   COMPONENT_THUMBNAIL_READY      // 응
parent → iframe   COMPONENT_THUMBNAIL            // { sheetJson, nodeTextMap, nodeBboxMap,
                                              //   siblingGroups, fontScaleRange, rlsc? }
iframe → parent   COMPONENT_THUMBNAIL_LOADED     // { pageJson } ← 대치·재배치가 끝난 sheetJson
iframe → parent   COMPONENT_THUMBNAIL_ERROR      // { message, stack, componentStack }

대치 전후에 끼어드는 것들

타입 정의 — "sheetJson이 뭐냐"의 정답들

컨버터 — XML ⇄ sheetJson

엔진 — sheetJson ⇄ Page 객체

내용 대치 — web-2

내용 대치 — iui

preview 렌더러 — web-2 feature/UNICORN-73380_

파이프라인 — aippt-prisonbreak (MORDOR)

# 1. 컴포넌트 sheetJson 원본을 파일로 (렌더 없음, 가장 빠름)
pnpm exec tsx scripts/dump-sheet-json.ts --id 6357697 --outdir out

# 2. markdown을 대치해 렌더 → 이미지 + 대치 후 sheetJson
pnpm exec tsx scripts/comp-replace-render.ts \
  --id 6357697 --text-file page.md \
  --dump-rendered out/ --dump-payload out/

# 3. 이미 있는 sheetJson 파일을 그림으로만 굽기 (브라우저 불필요)
pnpm exec tsx scripts/sheetjson-thumb.ts out/6357697_base.json --out thumb.webp

지켜야 하는 불변 규칙