@penkit/adapter-svg

PenKit의 reference SVG renderer adapter다. committed pen item과 live preview를 SVGSVGElement 안에 렌더링한다.

npm install @penkit/adapter-svg @penkit/core

가장 빠른 브라우저 데모 경로는 @penkit/sdk와 함께 쓰는 것이다.

npm install @penkit/sdk @penkit/adapter-svg

LLM Agent Quick Start

1. committed item과 live preview를 담을 <svg>를 만든다.
2. new SvgPenAdapter(svg)를 생성한다.
3. @penkit/sdk로 mount하거나 PenEngine을 직접 만든다.
4. SVG에 안정적인 크기와 touch-action: none을 준다.

import { SvgPenAdapter } from "@penkit/adapter-svg";
import { mountPenKit } from "@penkit/sdk";

const svg = document.querySelector<SVGSVGElement>("#ink")!;
const adapter = new SvgPenAdapter(svg);

const pen = mountPenKit(svg, {
  adapter,
  penPriority: true,
});

pen.engine.setTool("pen");

주요 모듈

SvgPenAdapter

SvgPenAdapter는 PenHostAdapter<PenItemProps>를 구현한다.

주요 method:

• createPenItem(payload): 중립 commit payload를 PenItemProps로 바꾸고 렌더링한 뒤 반환한다.
• render(item): committed item을 렌더링하거나 다시 렌더링한다.
• remove(itemId): item의 SVG group을 제거한다.
• renderPreview(strokes, style, options): live ink, lasso guide, pointer preview를 top-most preview group에 렌더링한다.
• clearPreview(): preview group을 비운다.

기본 id는 pen-1, pen-2 방식으로 생성된다. host가 deterministic id를 원하면 generator를 넘긴다.

const adapter = new SvgPenAdapter(svg, () => crypto.randomUUID());

Brush Rendering

SvgPenAdapter는 PenStroke.brush 또는 InkStyle.brush의 built-in BrushRenderHints를 읽어 fountain wet-ink shade, ballpoint broken grain, pencil graphite pattern, marker segment accumulation, highlighter multiply blend를 렌더링한다.

adapter.brushCapabilities는 SVG renderer가 직접 처리하는 hint 범위를 선언한다. core의 supportsBrushRenderHints helper로 custom brush fallback 여부를 판단할 수 있다.

buildPathD

buildPathD(points)는 SVG host가 centerline path가 필요할 때 쓰기 편하도록 @penkit/core에서 re-export한 함수다.

import { buildPathD } from "@penkit/adapter-svg";

const d = buildPathD(rawPoints);

Rendering Behavior

• solid stroke는 outlinePathD를 우선 사용하고 filled pressure ribbon으로 렌더링한다.
• dash, dot, dash-dot stroke는 stroked centerline으로 렌더링한다.
• preview option의 pathMode: "centerline"으로 centerline 렌더링을 강제할 수 있다.
• item transform은 item bounds center 기준 SVG group transform으로 표현한다.
• preview group은 항상 마지막 child로 다시 append되어 live ink가 committed item 위에 보인다.

Integration Recipes

ViewBox, Zoom, Pan

pointer sample을 현재 viewBox coordinate로 매핑한다.

const pen = mountPenKit(svg, {
  adapter: new SvgPenAdapter(svg),
  transformPoint(point) {
    const rect = svg.getBoundingClientRect();
    const nx = (point.x - rect.left) / rect.width;
    const ny = (point.y - rect.top) / rect.height;
    return {
      ...point,
      x: viewBox.x + nx * viewBox.width,
      y: viewBox.y + ny * viewBox.height,
    };
  },
});

저장된 item 다시 렌더링

for (const item of snapshot.items) {
  adapter.render(item);
}

하지 말 것

• 이 adapter를 production Miricanvas renderer나 canvas renderer처럼 말하지 않는다. SVG 전용이다.
• host가 모든 engine update마다 re-render할 책임을 지지 않는 한 adapter가 소유한 SVG group을 직접 mutate하지 않는다.
• zoom, pan, scroll, CSS transform, viewBox transform이 있을 때 SVG client coordinate가 document coordinate와 같다고 가정하지 않는다.