@penkit/dom-input

PenKit의 browser PointerEvent input layer다. mouse, pen, touch, pressure, tilt, coalesced events, stylus button metadata를 @penkit/core의 RawPoint sample로 정규화한다.

npm install @penkit/dom-input @penkit/core

대부분의 브라우저 앱은 @penkit/sdk를 사용하면 된다. DOM event를 직접 PenEngine에 feed하거나, host가 input element lifecycle을 이미 소유하고 있다면 이 패키지를 직접 사용한다.

LLM Agent Quick Start

1. pen input을 받을 element로 PointerInputController를 만든다.
2. PenEngine.pointerHandlers 형태의 handler를 넘기거나, 정규화된 RawPoint를 host runtime으로 전달한다.
3. mount 때 attach(), teardown 때 detach()를 호출한다.
4. tablet에서 stylus-first palm rejection이 필요하면 penPriority: true를 사용한다.

import { PointerInputController } from "@penkit/dom-input";
import { PenEngine } from "@penkit/engine";

const engine = new PenEngine({ adapter });
const input = document.querySelector<HTMLElement>("[data-pen-input]")!;

const controller = new PointerInputController(input, engine.pointerHandlers, {
  penPriority: true,
});

controller.attach();
controller.detach();

주요 모듈

extractRawPoint

extractRawPoint(source, timestamp)는 browser pointer sample에서 PenKit이 읽는 필드를 RawPoint로 변환한다.

import { extractRawPoint } from "@penkit/dom-input";

element.addEventListener("pointerdown", (event) => {
  const point = extractRawPoint(event, performance.now());
  engine.pointerDown(point);
});

보존하는 값:

• clientX/clientY를 x/y로 전달
• 실제 pressure가 없는 장치에서는 0을 0.5로 정규화
• pointerType을 mouse, pen, touch로 매핑
• buttons/button, barrel button, eraser-end normalization
• tilt, twist, altitude, azimuth

client coordinate를 document coordinate로 바꾸는 일은 PenEngine 또는 mountPenKit의 transformPoint에서 한다.

mapPointerType

mapPointerType(pointerType)은 PenKit의 normalized pointer family를 반환한다.

import { mapPointerType } from "@penkit/dom-input";

mapPointerType("pen"); // "pen"
mapPointerType("touch"); // "touch"
mapPointerType("mouse"); // "mouse"
mapPointerType("unknown-vendor-type"); // "mouse"

PointerInputController

하나의 element에 대한 browser pointer lifecycle을 소유한다.

• pointerdown, pointermove, pointerup, pointercancel
• pointer capture/release
• move에서 getCoalescedEvents() expansion
• single-active-pointer tracking
• optional pen-priority palm rejection
• side-button/right-click stroke 처리를 위한 context menu suppression

const controller = new PointerInputController(
  svg,
  {
    onPointerStart(point) {
      engine.pointerDown(point);
    },
    onPointerMove(points) {
      engine.pointerMove(points);
    },
    onPointerEnd(point) {
      engine.pointerUp(point);
    },
  },
  {
    now: () => performance.now(),
    penPriority: true,
  },
);

Integration Notes

• input element나 overlay에 touch-action: none을 설정한다.
• controller는 client-space coordinate를 emit한다. engine 또는 SDK transformPoint로 host canvas/document 좌표로 변환한다.
• penPriority는 간단한 정책이다. pen pointer가 한 번 보이면 touch pointer를 무시한다. native 수준 palm rejection을 대체하지 않는다.
• coalesced event는 onPointerMove(points) batch로 도착한다. batch 전체를 engine.pointerMove(points)로 넘겨야 고주파 입력을 보존한다.

하지 말 것

• document model에 PointerEvent 객체를 저장하지 않는다. RawPoint[]를 저장한다.
• non-browser runtime에서 이 패키지를 그대로 쓰지 않는다. 필요하면 구조적으로 같은 sample object를 extractRawPoint에 넘긴다.
• host가 pointer ownership을 의도적으로 multiplex하지 않는 한 같은 element에 controller를 여러 개 붙이지 않는다.