# @mwillbanks/tuil-pointer

Source: /tuil/docs/reference/packages/pointer
Locale: en

Renderer-neutral terminal pointer parsing, hit testing, capture, and dispatch for tuil.



## Overview [#overview]

Renderer-neutral terminal pointer parsing, hit testing, capture, and dispatch for tuil.

`@mwillbanks/tuil-pointer` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-pointer
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-pointer
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-pointer
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-pointer
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Pointer input parses SGR sequences, hit-tests shared layout bounds, and routes capture and bubble phases for click, hover, drag, wheel, and focus behavior.

<Mermaid
  chart="flowchart LR
  S0[&#x22;enable tracking&#x22;]
  S1[&#x22;decode&#x22;]
  S2[&#x22;hit test&#x22;]
  S3[&#x22;route&#x22;]
  S4[&#x22;disable tracking&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                 | Signature                       | Description                           |
| ----------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
| [`DecodedPointerInput`](/tuil/docs/reference/packages/pointer/api/decoded-pointer-input) | `interface DecodedPointerInput` | Public interface DecodedPointerInput. |
| [`ParsedPointerInput`](/tuil/docs/reference/packages/pointer/api/parsed-pointer-input)   | `interface ParsedPointerInput`  | Public interface ParsedPointerInput.  |
| [`parseSgrPointer`](/tuil/docs/reference/packages/pointer/api/parse-sgr-pointer)         | `function parseSgrPointer`      | Public function parseSgrPointer.      |
| [`PointerButton`](/tuil/docs/reference/packages/pointer/api/pointer-button)              | `type PointerButton`            | Public type PointerButton.            |
| [`PointerEventType`](/tuil/docs/reference/packages/pointer/api/pointer-event-type)       | `type PointerEventType`         | Public type PointerEventType.         |
| [`PointerModifiers`](/tuil/docs/reference/packages/pointer/api/pointer-modifiers)        | `interface PointerModifiers`    | Public interface PointerModifiers.    |

## Events and lifecycle [#events-and-lifecycle]

Normalized pointer events carry coordinates, buttons, modifiers, phase, and propagation state.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { parseSgrPointer } from "@mwillbanks/tuil-pointer";

const event = parseSgrPointer(sequence);
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)