# @sgrsoft/vision-sdk — LLM / Coding-Agent Guide

> 이 문서는 코딩 에이전트가 이 패키지를 정확히 사용하도록 돕는 압축 레퍼런스입니다.
> 사람용 소개는 README.md 를, 실행 데모는 /demo.html 을 참고하세요.

## What it is
프레임워크 비의존, 의존성 0 의 ESM 라이브러리. 페이지에 이미 존재하는 `<video>` 를
CSS 셀렉터(또는 element)로 지정하면 그 위에 `<canvas>` 를 정확히 겹쳐 올리고,
WebGPU(미지원 시 WebGL 자동 폴백)로 실시간 화질 개선을 수행한다. 원본 `<video>` 는
`visibility:hidden` 으로 숨겨지고 캔버스가 그 자리를 대신한다.

핵심: **재생은 사용자의 플레이어(hls.js/dash.js/native 등)가 담당하고, 이 라이브러리는
그 `<video>` 의 화면 출력만 개선한다.** 영상을 로드/디코드/재생하지 않는다.

## Install
```
npm install @sgrsoft/vision-sdk
```
- type: module (ESM only). main/module: ./dist/vision-sdk.js, types: ./dist/index.d.ts
- 브라우저 전용 (DOM/WebGL/WebGPU 필요). Node SSR 환경에서 import 시 top-level 부작용은 없으나
  enhance() 는 document/HTMLVideoElement 가 있어야 동작.

## Primary API
```ts
import { enhance } from "@sgrsoft/vision-sdk";

const fx = enhance(target, options?);
```
- `target`: `string`(CSS 셀렉터) | `HTMLVideoElement`. 셀렉터가 video 가 아니면 throw.
- `options`: `VideoEnhancementOptions`(아래). 생략 시 `{ enabled: true, profile: "default" }`.
- 반환 `EnhanceHandle`:
  - `update(options: VideoEnhancementOptions): void` — 옵션 갱신(프로필/강도/렌더러 등)
  - `setEnabled(enabled: boolean): void` — 효과 on/off 단축
  - `getState(): { backend: "webgl"|"webgpu"|null, enabled: boolean, unsupported: boolean }`
  - `destroy(): void` — 캔버스 제거 + 원본 video 원복 (반드시 호출하여 정리)
  - `video: HTMLVideoElement`, `enhancer: VideoEnhancer`(저수준 인스턴스)

## VideoEnhancementOptions (전체)
```ts
{
  enabled: boolean;                 // 필수
  profile?: "off"|"default"|"detail"|"ott"|"education"|"cctv"|"anime"|"oled"|"retro";
  renderer?: "auto"|"webgpu"|"webgl"|"webgl2";  // 기본 "auto" (WebGPU→WebGL 폴백)

  // 개별 강도 — 명시 시 profile 기본값을 덮어씀
  sharpen?: number;        // 0..1  언샤프 선명도
  contrast?: number;       // 0..1  글로벌 S-curve
  cleanup?: number;        // 0..1  압축 노이즈/블록 제거
  anime?: number;          // 0..1  라인 강조 + 색면 평탄화
  gamma?: number;          // 0.5..2.0 (기본 1.0)
  localContrast?: number;  // 0..1  와이드 radius 언샤프(텍스트/디테일 체감)
  darkLift?: number;       // 0..1  암부(luma<0.35)만 lift

  scanline?: { enabled?: boolean; intensity?: number; spacing?: number };

  upscale?: {              // 저해상도 → 캔버스 해상도 SR
    enabled?: boolean;
    algorithm?: "none"|"nearest"|"bilinear"|"lanczos"|"lanczos2"|"fsr"|"easu";
    target?: "source"|"720p"|"1080p"|"1440p"|"2x"|"3x"|"custom";
    width?: number; height?: number;   // target:"custom"
    sharpness?: number;  // RCAS 단축(권장 0..0.2)
  };

  edgeEnhancement?: {      // sharpen+rcas 통합 단일 API (명시 시 legacy 필드 무시)
    enabled?: boolean; algorithm?: "off"|"classic"|"rcas"; strength?: number; // 0..1
  };

  cnn1?: { enabled?: boolean };                 // 1-layer CNN (WebGPU 전용)
  cnn?: { enabled?: boolean; layers?: CnnLayer[] }; // multi-layer CNN (WebGPU 전용)

  autoReduceOnLowEnd?: boolean;  // 저사양 기기 강도 자동 감쇠 (기본 true)

  // 라이선스(선택) — 지정 시 검증 통과 전까지 효과 비활성(원본 재생). 미지정이면 게이팅 없음.
  licenseKey?: string;
  licenseEndpoint?: string;      // 검증 함수 URL(기본: SGR 라이선스 서버)
}
```
- 라이선스: `licenseKey` 지정 시 enhance() 가 비동기 검증 → 통과해야 효과 적용. 실패(없음/만료/폐기/도메인불일치/네트워크)면 원본 재생. `getState().license` = `none|pending|ok|invalid`. localhost 는 도메인 검증 면제.

## Profiles (한 줄 의미)
- default: Cinematic, 실사용 메인 / detail: Ultra Detail, 시연용
- ott: 저비트레이트 스트리밍 cleanup / education: 텍스트·판서 가독성
- cctv: 야간·저조도 대비 / anime: 라인+색면 평탄화
- oled: 깊은 black+영화적 대비 / retro: CRT scanline+warm / off: 비활성

## Upscale presets (그대로 넘기면 됨)
`import { UPSCALE_PRESETS } from "@sgrsoft/vision-sdk"`
키: `off | balanced(1080p+lanczos) | quality(1080p+fsr) | dramatic(강sharpen) | lowPower(720p)`

## Exports
- 함수: `enhance`
- 클래스: `VideoEnhancer`, `WebGLVideoRenderer`, `WebGPUVideoRenderer`, `EnhancementPipeline`
- 유틸: `resolveProfileUniforms`, `getProfileDefaults`, `PROFILE_LIST`, `isHighResDisplay`,
  `UPSCALE_PRESETS`, `resolveOutputSize`, `clampOutputSize`, `normalizeAlgorithm`,
  `loadCnnWeightsFromUrl`, `parseCnnWeights`, `buildIdentityCnnLayers`, `buildSharpenCnnLayers`, `FLOATS_PER_LAYER`
- 타입: `VideoEnhancementOptions`, `EnhancementProfile`, `EnhancementRendererKind`, `UpscaleParams`,
  `EdgeEnhancementParams`, `CnnLayer`, `CnnParams`, `IVideoRenderer`, `EnhanceHandle`, `VideoEnhancerState` 등

## Framework usage
### Plain JS
```ts
const fx = enhance("#player", { enabled: true, profile: "ott" });
```
### React (cleanup 필수)
```tsx
useEffect(() => {
  const fx = enhance(ref.current, { enabled: true, profile: "default" });
  return () => fx.destroy();
}, []);
```
### Vue 3
```ts
onMounted(() => { fx = enhance(videoRef.value, { enabled: true }); });
onBeforeUnmount(() => fx?.destroy());
```
### HLS/DASH (재생은 별도 플레이어)
```ts
const hls = new Hls(); hls.loadSource(url); hls.attachMedia(video);
enhance(video, { enabled: true, profile: "ott", upscale: UPSCALE_PRESETS.quality });
```

## Behavior & constraints (에이전트 주의)
- `<video>` 는 enhance() 호출 시점에 DOM 에 존재해야 한다.
- 부모가 `position:static` 이면 자동으로 `relative` 로 승격하고, 그 안에 absolute overlay+canvas 삽입.
  DOM 을 감싸지 않으므로 레이아웃 영향 최소. destroy() 가 부모/visibility 를 원복.
- 원본 video 는 `visibility:hidden`(레이아웃 박스 유지 → 반응형 크기/비율 letterbox 자동 추종).
- 렌더 루프: `requestVideoFrameCallback`(미지원 시 `rAF`). 영상이 멈추면 GPU 업로드도 멈춤.
- CORS: 교차 출처 영상은 `<video crossorigin="anonymous">` + 서버 CORS 헤더 필요(canvas 오염 방지).
- CNN(cnn/cnn1)은 **WebGPU 백엔드에서만** 적용. renderer 가 webgl 로 폴백되면 무시됨.
- 한 video 에 enhance() 는 1회. 옵션 변경은 새 enhance() 가 아니라 handle.update() 사용.
- enabled:false 또는 profile:"off" 또는 모든 강도 0 이면 passthrough(원본) 출력.
- 백엔드 미지원(WebGL 불가) 시 효과를 끄고 원본 노출, `getState().unsupported === true`.

## Common agent tasks
- "비디오에 화질 개선 적용" → `enhance(selector, { enabled:true, profile:"default" })`
- "끄기/켜기 토글" → `handle.setEnabled(bool)` (재생성 비용 없음)
- "원본 vs 개선 비교" → 효과 ON 상태에서 `video.style.visibility="visible"` + overlay(`[data-vpe-enhancement]`) `clipPath` 로 좌우 분할 (데모 demo.html 의 '동시 비교' 참고)
- "정리" → 컴포넌트 unmount/페이지 이탈 시 `handle.destroy()` 필수
- "트래픽 절감 시나리오" → 저비트레이트 소스 + `profile:"ott"` + 필요 시 `upscale:UPSCALE_PRESETS.quality`

## Links
- npm: https://www.npmjs.com/package/@sgrsoft/vision-sdk
- demo: /demo.html
- README(상세): 패키지 루트 README.md