문제 해결

차트 통합 실패 시 자주 쓰이는 복사 가능한 점검 항목 및 수정법.

이 실패 유형들은 diagnose_chart에서 사용된 동일한 버전 지식으로 생성되었습니다. 애플리케이션과 가장 유사한 증상부터 시작해 진단 검사를 적용하고, 문서화된 수명 주기와 타입 배열 소유권 계약을 보존하는 수정만 적용하십시오.

일치하는 항목이 없으면 관련 기호를 중첩된 API 참조에서 검사하거나 로컬 Model Context Protocol(MCP) 서버에 집중 진단을 요청하십시오. 재현 범위를 진단 단계로서만 renderMode: "main" 및 animated: false으로 축소하십시오. 이는 자동 프로덕션 구성으로 사용해서는 안 됩니다.

증상 색인

캔버스가 비어 있거나 크기가 0입니다

적용 대상: line, stock.

증상. 차트는 오류 없이 초기화되지만 플롯이 표시되지 않거나 캔버스의 높이 측정값이 0픽셀입니다.

가능한 원인. 렌더러가 초기화될 때 캔버스 호스트에 구체적인 높이가 설정되어 있지 않았습니다.

확인하십시오

  • 호스트와 캔버스를 getBoundingClientRect(); 로 검사하십시오. 너비와 높이 모두 0보다 커야 합니다.
  • 차트 행이 flex 또는 grid 조상 요소에 의해 축소되었는지 확인하십시오.

해결 방법

  • initialize()가 실행되기 전에 호스트에 명시적인 height 또는 min-height를 부여하십시오.
  • 캔버스 고유 치수에 의존하지 말고 해당 호스트를 캔버스가 채우게 하십시오.

차트에 측정 가능한 호스트를 제공하십시오

.chart-host {
  position: relative;
  width: 100%;
  height: clamp(20rem, 55vh, 34rem);
}

.chart-host > canvas {
  display: block;
  width: 100%;
  height: 100%;
}

차트가 준비되기 전에 데이터가 설정됩니다

적용 대상: line, stock.

증상. 첫 번째 데이터셋이 나타나지 않지만 이후 업데이트나 리마운트는 정상 동작합니다.

가능한 원인. 순수 통합(바닐라)이 initialize()가 완료되기 전에 데이터 메서드를 호출했거나 동일한 캔버스를 한 번 이상 초기화했습니다.

확인

  • 각 차트 인스턴스에 대해 initialize()가 정확히 한 번만 await되는지 확인하세요.
  • 프레임워크가 뷰를 소유하는 경우 공식 어댑터를 사용하여 마운트 및 언마운트 순서가 자동으로 처리되도록 하세요.
  • 어댑터 준비 완료 이벤트는 초기화 및 데이터, 외형, 뷰포트 속성의 첫 성공 배치 이후 한 번 발생하며, 이는 페인팅된 프레임 알림이 아닙니다.

수정

  • setData() 또는 setMultiSeriesData()를 호출하기 전에 initialize()가 완료될 때까지 대기하십시오.
  • 다른 인스턴스에서 캔버스를 재사용하기 전에 기존 차트를 파기하십시오.
  • 어댑터 prop 설치가 거부된 경우 다시 마운트하지 않고 수정된 props를 제공하여 재시도하십시오. 성공적으로 설치된 데이터는 다시 전송되지 않습니다. 렌더러가 치명적으로 실패한 경우에는 재마운트가 필요합니다.

바닐라 라이프사이클을 사용하십시오.

const chart = new LineChart(canvas, { renderMode: "auto" });
await chart.initialize();
chart.setData(data);

// Call this when the view is permanently removed.
export function disposeChart() {
  chart.destroy();
}

Worker 렌더링은 메인 스레드로 대체됩니다.

해당 항목: line, stock.

증상. 차트는 작동하지만 메인 스레드 렌더링으로 해결되거나, 프로덕션에서만 Worker 구성에 실패합니다.

가능한 원인. Worker, OffscreenCanvas, transferControlToOffscreen 또는 배포된 콘텐츠 보안 정책이 Worker 렌더러의 시작을 차단했을 수 있습니다.

확인하십시오

  • 일시적으로 setStatsCallback()를 사용하여 통계를 검사하십시오.renderMode.
  • 브라우저 콘솔과 worker-src Content Security Policy 지시문을 확인하십시오.

수정

  • 진단을 위해 모드를 강제해야 하는 경우가 아니면 renderMode 값을 auto로 유지하십시오.
  • 애플리케이션이 생성한 Worker URL을 worker-src에 허용하고 메인 스레드 폴백을 계속 작동시키십시오.

해결된 렌더러를 확인하십시오

chart.setStatsCallback((stats) => {
  console.info("Sixtyfold renderer:", stats.renderMode);
  chart.setStatsCallback(null);
});

타입화된 배열은 setData 후 분리(detached)됩니다

적용 대상: line, stock.

증상. 소스 타입화된 배열이 byteLength 0이 되었거나 Worker 지원 차트에 데이터를 설정한 이후 더 이상 읽을 수 없습니다.

가능한 원인. 대량 차트 데이터는 Worker 모드에서 렌더러로 전송됩니다; 전송된 ArrayBuffers는 호출자에서 제거됩니다.

확인하세요

  • 대량 데이터 호출 직전과 직후에 byteLength를 검사하세요.
  • 다른 하위 시스템이 실제로 읽기 가능한 복사본을 유지해야 하는지 확인하세요.

수정

  • 대량 데이터 호출을 소유권 이전으로 처리하십시오.
  • 다른 하위 시스템이 유지해야 하는 열만 복제하십시오. 기본적으로 수백만 값의 데이터셋을 중복하지 마십시오.

의도적인 애플리케이션 복사본을 유지하십시오

const retainedX = sourceX.slice();
const retainedY = sourceY.slice();

chart.setData({
  x: sourceX,
  y: sourceY,
  length: sourceX.length,
});

// retainedX and retainedY remain readable.

시간 축이 압축되었거나 비어 있거나 먼 미래를 가리킵니다

적용 대상: line, stock.

증상. 눈금에 비현실적인 날짜가 표시되거나, 표시 범위가 붕괴되거나, 팬 동작이 예측할 수 없게 됩니다.

가능한 원인. X 열이 유한한 정렬된 epoch 밀리초 대신 초나 문자열을 사용했거나 관측값이 정렬되어 있지 않았습니다.

확인

  • 첫 번째와 마지막 타임스탬프를 확인하고 new Date(value)로 변환하십시오.
  • 모든 타임스탬프가 유한한지 확인하십시오. 주식 스트리밍은 각 배치 내에서 그리고 이전에 큐에 들어가거나 추가된 캔들 이후에 엄격히 증가하는 타임스탬프를 요구합니다.
  • 스트리밍과 정적 StockChart.setData()를 구분하십시오: 정적 데이터는 단조 증가하거나 단조 감소할 수 있으며 동일한 타임스탬프를 포함할 수 있습니다; 차트는 그 순서를 정규화합니다.

수정

  • Float64Array를 생성하기 전에 epoch 초를 밀리초로 변환하십시오.
  • 수집 중에 ISO 날짜를 한 번 파싱하고, 관측치를 열로 분할하기 전에 전체 관측치를 정렬하십시오.
  • 추가하기 전에 주식 스트림 관측치의 중복을 제거하십시오. 스트리밍 추가 메서드는 동일한 타임스탬프를 가진 기존 캔들을 업데이트하지 않습니다.

수집 과정에서 타임스탬프를 정규화하십시오

const timestamp = Float64Array.from(rows, (row) => {
  const value = Date.parse(row.recordedAt);
  if (!Number.isFinite(value)) throw new TypeError("Invalid recordedAt value");
  return value;
});

열들이 길이가 다르거나 숫자 값이 유효하지 않습니다

적용 대상: line, stock.

증상: 차트가 데이터셋을 거부하거나 예기치 않게 잘리거나 값이 잘못된 타임스탬프에 렌더링됩니다.

가능한 원인. 열 형식 데이터가 개별 필터나 매핑에서 생성되어 시간 열과 값 열이 더 이상 동일한 관측치를 설명하지 않습니다.

확인

  • 차트를 호출하기 전에 모든 열의 길이를 비교하십시오.
  • 버퍼를 전송하기 전에 숫자 변환을 검증하십시오.
  • Stock addCandles에는 동일한 크기의 여섯 개 열이 필요합니다; addCandleBatches은(는) 전송 전에 전체 청크 목록을 검증합니다. 잘못된 타임스탬프나 열 길이는 호출자 버퍼를 그대로 연결된 상태로 둡니다.

수정

  • 전체 소스 관측값을 먼저 필터링하고 정렬한 다음, 정렬된 타입별 열로 분할하십시오.
  • 문서화된 선 시계열 간격에는 명시적 NaN만 사용하십시오; OHLCV 값은 유효한 캔들로 유지되어야 합니다.

전송 전에 정렬이 맞지 않는 열을 거부하십시오

const lengths = [timestamp.length, open.length, high.length, low.length, close.length, volume.length];
if (!lengths.every((length) => length === lengths[0])) {
  throw new RangeError(`OHLCV columns are misaligned: ${lengths.join(", ")}`);
}

SSR 또는 하이드레이션이 브라우저 전용 차트 API에 접근함

적용 대상: line, stock.

증상. window, document, Worker 또는 HTMLCanvasElement를 사용할 수 없어 서버 렌더링이 예외를 던지거나 하이드레이션이 다른 트리를 생성합니다.

가능한 원인. 대화형 브라우저 차트가 클라이언트가 마운트된 이후가 아니라 서버 평가 동안 생성되었습니다.

확인하기

  • 모듈 범위나 서버 컴포넌트 내부에서 차트 생성 코드를 찾으십시오.
  • 브라우저 상호작용과 서버 이미지 생성을 @sixtyfold/ssr로 분리하십시오.

수정

  • 클라이언트 소유 컴포넌트 내부에서 공식 프레임워크 어댑터를 사용하십시오.
  • SSR 중에는 안정적인 호스트를 렌더링하고 마운트 후에만 대화형 차트를 초기화하십시오.

클라이언트 경계 뒤에 Next.js 차트를 유지하십시오.

"use client";

import type { MultiSeriesData, TimeSeriesData } from "@sixtyfold/core";
import { SixtyfoldLineChart } from "@sixtyfold/react/line";

type LineData = TimeSeriesData | MultiSeriesData;

export function ChartPanel({ data }: { data: LineData }) {
  return <SixtyfoldLineChart data={data} options={{ renderMode: "auto" }} />;
}

탐색 후에도 워커 또는 메모리가 남아 있음

적용 대상: line, stock.

증상. 뷰를 반복적으로 열면 메모리가 증가하거나 이전 차트가 탐색 후에도 계속 렌더링됩니다.

가능한 원인. 일반 차트 또는 임시 데이터 Worker가 소유 뷰가 제거될 때 파괴되지 않았습니다.

확인

  • 여러 번 마운트/언마운트하는 사이에 브라우저 힙 스냅샷을 전후로 기록하십시오.
  • 유지된 차트 인스턴스, Worker, 옵저버 또는 디코딩된 소스 배열을 찾으십시오.

수정

  • 바닐라 차트 인스턴스마다 정확히 한 번만 destroy()를 호출하십시오.
  • 임시 fetch/decode Worker는 마지막 전송 후 종료하십시오; 공식 프레임워크 어댑터는 차트 Worker를 자동으로 파괴합니다.

차트 및 수집(ingestion) Worker 해제

return () => {
  dataWorker?.terminate();
  chart.destroy();
};

상호작용이 느리거나 프레임이 떨어짐

Applies to: line, stock.

증상. 확대/축소, 팬, 초기 디코드 또는 스트리밍 업데이트가 눈에 띄게 정지하거나 목표 프레임률을 맞추지 못합니다.

가능한 원인. 메인 스레드가 너무 많은 데이터를 디코딩하거나 재구성하고 있거나, 차트가 대체 렌더러로 해결되었거나, 가시적 작업 부하에 대상 장치가 감당할 수 있는 것보다 많은 드로잉 패스가 포함되어 있습니다.

확인하세요

  • 통계 수치(Inspect stats).renderMode, frameTime, 실제 상호작용 순서 동안의 가시적 작업(visible work) 및 LOD 준비 상태를 점검하십시오.
  • 가져오기(fetch), 디코드(decode), 변환(conversion), 전송(transfer), 렌더링을 개별적으로 프로파일링하십시오.

수정(Fix)

  • renderMode auto를 사용하고 전용 데이터 Worker에서 열 기반 타입화 배열을 준비하여 한 번 전송(transfer)한 뒤 해당 수집(ingestion) Worker를 종료하십시오.
  • 대표적인 브라우저, DPR, 시리즈 수 및 제스처에 대해 벤치마크하십시오; 60 FPS는 기기와 무관한 보장이 아니라 설계 목표입니다.

활성 렌더링 경로를 측정하십시오

chart.setStatsCallback((stats) => {
  console.table({
    mode: stats.renderMode,
    fps: stats.fps,
    frameTime: stats.frameTime,
    ready: stats.lodReady,
  });
}, { intervalMs: 250 });

확대/축소가 안정된 후 선의 상세도가 급격히 변경됩니다

적용 대상: line.

증상. 뷰포트가 부드럽게 애니메이션되지만 제스처가 끝날 때 선 텍스처가 다시 변경됩니다.

가능한 원인. 프레젠테이션 밀도 또는 그리드 리베이스가 작업량에 비해 과도하게 공격적이거나, 애플리케이션 코드가 애니메이션 완료 후에 데이터나 외형을 교체합니다.

확인

  • 프레젠테이션 밀도, 그리드 델타 및 쿼리 방문을 관찰하면서 동일한 뷰포트 시퀀스를 재생합니다.
  • 애니메이션이 안정된 후 애플리케이션 측에서 setData(), setAppearance() 또는 뷰포트 복원(restore)을 호출하는지 확인하십시오.

수정 방법

  • 적응형 모드, 밀도 0.75, rebaseRatio 1.25 및 quantizationStep 0.25로 시작하십시오.
  • 하나의 계수만 조정하려면 setLODOptions()을 사용하십시오; 비용이 큰 범위 채우기나 매우 큰 다중 시리즈 작업에는 밀도 0.25를 사용하십시오.

차트를 다시 생성하지 않고 표시를 조정하십시오

chart.setLODOptions({
  mode: "adaptive",
  density: 0.75,
  rebaseRatio: 1.25,
  quantizationStep: 0.25,
});

누락된 관측값 사이를 선으로 연결합니다

적용 대상: line.

증상. 측정값이 존재하지 않는 구간을 시각적으로 선이 가로지릅니다.

가능한 원인: 누락된 관측값이 정렬된 NaN 간격으로 표시되지 않고 제거되었거나 0으로 대체되었습니다.

확인하십시오

  • 눈에 보이는 끊김이 필요할 때 공유된 X 열에 누락된 구간이 포함되어 있는지 확인하십시오.
  • 수집 과정에서 null 값을 0으로 변환했는지 검사하십시오.

수정

  • X 위치를 정렬 상태로 유지하고 누락된 선값은 Number.NaN으로 인코딩하십시오.
  • OHLCV 캔들을 합성하거나 시장 휴장을 연결하지 마십시오; 주식 시계축 동작은 관찰된 캔들에 의해 결정됩니다.

실제 선 계열의 갭을 표시하십시오

const data = {
  x: new Float64Array([0, 1, 2, 3]),
  y: new Float64Array([12, Number.NaN, Number.NaN, 18]),
  length: 4,
};