yubisac 0.9.1

package/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Found a bug? Please open an issue and let me know — I'll fix it on my end.
+
+Want a feature? Please open an issue — I know there's still a lot missing, so I'd love to hear what you need.
+
+If you'd rather fix it yourself, open an issue and send a PR — I'll usually merge it in.
+
+## `null` vs `undefined`
+
+Default to `undefined` for "nothing there". Use `null` only when you deliberately put it there, or
+when the DOM/a framework hands it to you (e.g. `elementFromPoint`, React refs, `render(null)` to
+unmount). So a `null` in this code is always on purpose.

package/EXAMPLES.md

@@ -0,0 +1,186 @@
+# yubisac examples 🫰
+
+Copy-paste recipes. Everything is the same idea: **different inputs → one intent → your handler.** The app
+code only ever names the intent (`inspect`, `place`, `context`), never the gesture.
+
+- [Presets — bind without a profile](#presets)
+- [Custom profile — your own intents](#custom-profile)
+- [Keyboard = accessibility, for free](#keyboard)
+- [The conflict cases it resolves](#conflict-cases)
+- [Adapters](#adapters) — core / native · Solid · React · Vue · Svelte · React Native
+- [CDN / plain HTML](#cdn)
+
+---
+
+## Presets
+
+Common mappings ship built in — bind them by name, no profile:
+
+```ts
+import { yubisac } from 'yubisac'
+
+const card = yubisac(el)
+card.clingTo('activate', open)             // mouse click · touch tap · Enter/Space
+card.clingTo('secondary-activate', inspect) // mouse double-click · touch/pen long-press
+card.clingTo('context', showMenu)           // mouse right-click · ContextMenu key
+```
+
+| Intent | touch / pen | mouse | keyboard |
+| --- | --- | --- | --- |
+| `activate` | tap | click | Enter / Space |
+| `secondary-activate` | long-press | double-click | — |
+| `context` | — ¹ | right-click | ContextMenu |
+
+¹ `context` is a desktop notion (right-click / ContextMenu key). Touch has no right-click, so use `secondary-activate` (a long-press) for the touch secondary action.
+
+Keyboard intents need a focusable element — give it `tabindex="0"` (and a `role`) so it can receive the key.
+
+## Custom profile
+
+Define your app's intent vocabulary once; the gesture names never leak past this object:
+
+```ts
+const finger = yubisac(el, {
+  open:    { touch: 'tap',        mouse: 'click',        keyboard: ['Enter', 'Space'] },
+  inspect: { touch: 'long-press', mouse: 'double-click' },
+  context: { touch: 'long-press', mouse: 'right-click',  keyboard: 'ContextMenu' },
+})
+finger.clingTo('open', openItem)
+finger.clingTo('inspect', openInspector)
+finger.clingTo('context', showMenu)
+
+// later
+finger.destroy() // removes every listener
+```
+
+`intent()` returns an `off()` to unbind just that one:
+
+```ts
+const off = finger.clingTo('inspect', openInspector)
+off()
+```
+
+Tune only what a person reasonably tunes:
+
+```ts
+yubisac(el, profile, { hold: 400, tolerance: 12 }) // long-press ms · move px
+```
+
+## Keyboard
+
+Add a `keyboard` key and the same intent works with no pointer at all — "make it work on tablets"
+quietly becomes "make it work for keyboard users too":
+
+```ts
+yubisac(el, {
+  inspect: { touch: 'long-press', mouse: 'double-click', keyboard: 'Enter' },
+}).clingTo('inspect', openInspector)
+```
+
+The handler still gets coordinates for a keyboard fire — the element's centre — so a menu can anchor sensibly.
+
+## Conflict cases
+
+The reason to reach for a library instead of 20 lines. Resolved once here, deterministically:
+
+- a **single** waits out the double-click window only when a **double is actually bound** — otherwise it fires at once
+- a **hold** is abandoned the moment the finger moves past `tolerance` (it was a drag or a scroll)
+- `pointercancel` (the browser taking over for **scroll**) drops the whole recognition — yubisac never sets `touch-action: none`, so the page keeps scrolling
+- the **compatibility mouse events** a browser fires *after* a touch are ignored, so nothing double-counts
+- mouse / touch / pen interleaving on one device stay untangled — the mapping is chosen per **event** `pointerType`, never a device flag
+- the **OS context menu** is suppressed when a right-click intent is bound, so your own menu wins
+
+Opt a subtree out (e.g. a card with its own menu) with `data-yubisac-ignore`:
+
+```html
+<div data-yubisac-ignore> … its own context menu lives here … </div>
+```
+
+Drag lives in [goonteh](https://github.com/mrksye/goonteh); yubisac never drags. A hold cancels on movement,
+goonteh's drag begins on movement — complementary, no coordination needed. Put both on the same element.
+
+## Adapters
+
+### core / native
+
+```ts
+import { yubisac } from 'yubisac'
+const off = yubisac(el, { pick: { touch: 'long-press', mouse: 'double-click' } }).clingTo('pick', onPick)
+```
+
+### Solid
+
+```tsx
+import { cling, Cling } from 'yubisac/solid'
+
+// ref helper — fits an existing element
+<div ref={cling({ inspect: openInspector }, { profile: { inspect: { touch: 'long-press', mouse: 'double-click' } } })} />
+
+// or the wrapper
+<Cling on={{ 'secondary-activate': place }}>{children}</Cling>
+```
+
+No provider — yubisac is element-local (unlike a shared drag context).
+
+### React
+
+```tsx
+import { useCling, Cling } from 'yubisac/react'
+
+function Card() {
+  const ref = useCling({ inspect: openInspector }, { profile: { inspect: { touch: 'long-press', mouse: 'double-click' } } })
+  return <div ref={ref} />
+}
+// or the wrapper
+<Cling on={{ 'secondary-activate': place }}>{children}</Cling>
+```
+
+### Vue
+
+```vue
+<script setup>
+import { vCling } from 'yubisac/vue'
+</script>
+<template>
+  <div v-cling="{ on: { inspect: openInspector }, profile: { inspect: { touch: 'long-press', mouse: 'double-click' } } }" />
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { cling } from 'yubisac/svelte'
+</script>
+<div use:cling={{ on: { inspect: openInspector }, profile: { inspect: { touch: 'long-press', mouse: 'double-click' } } }} />
+```
+
+### React Native (experimental)
+
+No DOM, so its own `PanResponder` recogniser — touch only, and only the `touch` mapping of each intent
+applies. Spread the handlers onto a `View`, or use the `<Cling>` wrapper:
+
+```tsx
+import { useCling, Cling } from 'yubisac/react-native'
+
+function Card() {
+  const handlers = useCling({ inspect: (e) => openInspector() }, { profile: { inspect: { touch: 'long-press' } } })
+  return <View {...handlers} />
+}
+// or
+<Cling on={{ 'secondary-activate': place }}>{children}</Cling>
+```
+
+## CDN
+
+Zero-dep and framework-free, so one `<script>` binds intents anywhere — even a Google Apps Script
+`HtmlService` iframe with no bundler:
+
+```html
+<script src="https://unpkg.com/yubisac@0.9.1"></script>
+<script>
+  yubisac(document.getElementById('card'), {
+    inspect: { touch: 'long-press', mouse: 'double-click' },
+  }).clingTo('inspect', () => openInspector())
+</script>
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrksye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# yubisac 🫰
+
+**Touch-first intent binding.** Design for the tablet — a tap, a long-press — then let the mouse, pen and keyboard **cling to the same intent.** One code path, touch-native, desktop along for the ride.
+
+*Pronounced "yubi-sac" — the name respells 指サック, the little cot worn on a fingertip for precise single-finger work.*
+
+```ts
+import { yubisac } from 'yubisac'
+
+yubisac(card, {
+  inspect: { touch: 'long-press', mouse: 'double-click', pen: 'long-press', keyboard: 'Enter' },
+}).clingTo('inspect', () => openInspector(card))
+```
+
+`openInspector` fires whether you long-pressed on a tablet, double-clicked on a laptop, or pressed Enter. The app names the intent — `inspect` — never the gesture.
+
+## A shift, not another gesture engine
+
+The world is going touch-first — a tablet on every job site — but input libraries are still desktop-first: the click is the canonical action, and touch is bolted on. yubisac flips it. **The intent is the anchor**, and every input **clings** to it — static cling, the everyday electrostatic pull — so a touch long-press, a desktop double-click and an Enter key are the *one* `inspect`.
+
+Hammer.js, interact.js, [@use-gesture](https://use-gesture.netlify.app) and tinygesture **recognise** gestures and hand them back as *separate* events; Pointer Events unify the device but stop at *which* device. The layer above — binding different inputs to the same intent — is the one nobody carved out. That's all yubisac is, on purpose: grow pinch/rotate/swipe and it's on Hammer's turf, out-muscled. Drag lives in its sibling [goonteh](https://github.com/mrksye/goonteh) (軍手, work gloves for gripping); yubisac (指サック, a finger cot for precise taps) never drags.
+
+Recognition is a deliberately small set — `click` · `double-click` · `long-press` · `right-click` · `Enter`/`Space` — and stays small. The value is the deterministic conflict resolution underneath (single-vs-double wait, move cancels a hold, `pointercancel` on scroll, post-touch compatibility-mouse dedup), plus keyboard as a free accessibility layer.
+
+## Runs where a framework can't — CDN, plain HTML
+
+Zero dependencies, framework-free core. One `<script>` and you're clinging intents — no bundler, no `npm install` (even inside a Google Apps Script `HtmlService` page):
+
+```html
+<script src="https://unpkg.com/yubisac@0.9.1"></script>
+<script>
+  yubisac(document.getElementById('card'), {
+    inspect: { touch: 'long-press', mouse: 'double-click' },
+  }).clingTo('inspect', () => openInspector())
+</script>
+```
+
+## Frameworks
+
+```sh
+npm i yubisac
+```
+
+Thin adapters wrap the same core — install only the one you use (each an optional peer dependency); the core needs nothing.
+
+| Import | Framework |
+| --- | --- |
+| `yubisac` / `yubisac/core` | Framework-agnostic engine (vanilla TS + DOM) |
+| `yubisac/native` | Vanilla DOM sugar (`cling`) |
+| `yubisac/solid` | SolidJS — `cling`, `<Cling>` |
+| `yubisac/react` | React ≥ 18 — `useCling`, `<Cling>` |
+| `yubisac/vue` | Vue ≥ 3.2 — `v-cling` directive |
+| `yubisac/svelte` | Svelte ≥ 4 — `use:cling` action |
+| `yubisac/react-native` | React Native (**experimental** — its own PanResponder recogniser, touch only) |
+
+> 📖 **[EXAMPLES.md](./EXAMPLES.md)** — presets, custom profiles, keyboard/accessibility, the conflict-resolution cases, and per-adapter recipes.
+
+## API (core)
+
+`yubisac(el, profile?, config?)` → `{ clingTo(intent, handler) → off(), destroy() }`.
+
+- `profile` — `{ [intent]: { touch?, mouse?, pen?, keyboard? } }`; built-in `PRESETS` (`activate`, `secondary-activate`, `context`) fill in known names.
+- gestures — `click`/`tap`, `double-click`/`double-tap`, `long-press`, `right-click`/`context-menu`.
+- `config` — two knobs only: `{ hold=500, tolerance=8 }`.
+- handler receives `{ intent, pointerType, clientX, clientY, currentTarget, originalEvent }`.
+
+## Status
+
+Born on a construction-site scheduling app that had to work on a foreman's tablet (touch) and an office laptop (mouse) from one code path. Recognition stays small; the investment is the binding and the conflict resolution, not more gestures. The core is pinned by real-browser tests (Playwright / Chromium) — `bun run test` — covering single-vs-double timing, long-press vs move/scroll, `pointercancel`, compatibility-mouse dedup, keyboard, and teardown.
+
+## Contributing · License
+
+Found a bug? Please **open an issue first** — see [CONTRIBUTING.md](./CONTRIBUTING.md). MIT © mrksye.
+
+> *One intent, every finger.*

package/core.ts

@@ -0,0 +1,306 @@
+/**
+ * yubisac core — a framework-agnostic **touch-first intent binding** engine.
+ *
+ * Not a gesture library. Hammer.js, interact.js, @use-gesture and tinygesture all recognise gestures
+ * (tap / double-tap / long-press / pinch …) and hand them to you as *separate* events. Pointer Events
+ * unify the input device but stop at "which device". The layer nobody owns is the one above: **every
+ * input clinging to the same operation intent** — a mouse double-click, a touch long-press and an Enter
+ * key are the one `inspect`. The app speaks in intents (`inspect`, `context`, `activate`); raw event
+ * names never leak into its code. Design for the tablet first, and let the desktop cling on.
+ *
+ * That is all yubisac does, and deliberately all it does: bind different inputs to one intent, and resolve
+ * the conflicts between them deterministically (single-vs-double wait, move cancels a hold, a touch's
+ * trailing compatibility-mouse events, scroll takeover). Recognition stays a tight set on purpose — the
+ * moment it grows into a gesture powerhouse it loses to the incumbents on their turf.
+ *
+ * Basis is the **per-event `pointerType`**, never a device flag: the same machine sends mouse, touch and
+ * pen events interchangeably, so the mapping is chosen per event, not per device.
+ *
+ * The name respells 指サック (yubi-sakku), the little cot worn on a fingertip for precise single-finger
+ * work — where goonteh (軍手, work gloves) is the whole hand gripping and dragging, yubisac is one
+ * fingertip tapping. Two hand-worn tools, one drag, one touch.
+ */
+
+/** Which pointing device an event came from — read per event, not per device. */
+export type PointerKind = 'mouse' | 'touch' | 'pen'
+
+/**
+ * A recognisable gesture token. Synonyms exist so a mapping reads naturally per device
+ * (`mouse: 'double-click'` vs `touch: 'double-tap'`); they collapse to the same recogniser.
+ */
+export type Gesture = 'click' | 'tap' | 'double-click' | 'double-tap' | 'long-press' | 'context-menu' | 'right-click'
+
+/** A keyboard key that fires an intent — `e.key` values (`'Enter'`, `'ContextMenu'`); `'Space'` is accepted for `' '`. */
+export type Key = string
+
+/** How one intent is reached, per input. Omit a device to not bind that device for this intent. */
+export type IntentMapping = Partial<Record<PointerKind, Gesture>> & { keyboard?: Key | Key[] }
+
+/** A named set of intent → per-input mappings. The app's intent vocabulary lives here, once. */
+export type Profile = Record<string, IntentMapping>
+
+/** What a bound handler receives when its intent fires. `clientX/clientY` is the pointer (or the element centre for keyboard). */
+export type IntentEvent = {
+  intent: string
+  pointerType: PointerKind | 'keyboard'
+  clientX: number
+  clientY: number
+  currentTarget: HTMLElement
+  /** The raw event. A right-click intent carries a `MouseEvent` (contextmenu), a keyboard intent a `KeyboardEvent`. */
+  originalEvent: PointerEvent | MouseEvent | KeyboardEvent
+}
+
+export type IntentHandler = (e: IntentEvent) => void
+
+/** A binding handle for one element. Cling handlers to intents; `destroy()` removes every listener. */
+export type Finger = {
+  /** Cling a handler to a named intent (from this element's profile, else a built-in preset). Returns an off(). */
+  clingTo(intent: string, handler: IntentHandler): () => void
+  destroy(): void
+}
+
+/**
+ * The only two knobs, on purpose. Everything else (the double window, the post-touch compatibility-mouse
+ * window) is a browser-timing fact, not an app preference — kept as internal constants so the surface stays
+ * a finger cot, not a powered suit.
+ */
+export type YubisacConfig = {
+  /** Hold this long (ms) without moving to fire a long-press. Default 500. */
+  hold?: number
+  /** Move more than this (px) and a tap/hold is abandoned (it's a drag or scroll). Default 8. */
+  tolerance?: number
+}
+
+/** A second press within this long (ms) resolves the pair as a double. */
+const DOUBLE_MS = 280
+/** After a touch, ignore mouse events for this long — the browser's compatibility mouse events. */
+const COMPAT_MOUSE_MS = 500
+
+/**
+ * Built-in intent presets — a named default mapping you can bind straight away, or override per element
+ * by passing your own profile. Keyboard bindings make these an accessibility layer, not just touch support.
+ */
+export const PRESETS: Profile = {
+  activate: { touch: 'tap', pen: 'tap', mouse: 'click', keyboard: ['Enter', 'Space'] },
+  'secondary-activate': { touch: 'long-press', pen: 'long-press', mouse: 'double-click' },
+  // `context` is a desktop notion (a right-click / the ContextMenu key). Touch has no right-click, so it
+  // carries no touch mapping — reach for `secondary-activate` (a long-press) for the touch secondary action.
+  context: { mouse: 'right-click', keyboard: 'ContextMenu' },
+}
+
+/** The recogniser category a gesture token collapses to — the engine reasons in these, not the tokens. */
+type Recogniser = 'single' | 'double' | 'hold' | 'context'
+
+const RECOGNISER: Record<Gesture, Recogniser> = {
+  click: 'single',
+  tap: 'single',
+  'double-click': 'double',
+  'double-tap': 'double',
+  'long-press': 'hold',
+  'context-menu': 'context',
+  'right-click': 'context',
+}
+
+/** Normalise a keyboard token to a comparable `e.key` (`'Space'` → `' '`), case-insensitively. */
+const normalizeKey = (k: Key): string => (k.toLowerCase() === 'space' ? ' ' : k.toLowerCase())
+
+type Binding = { intent: string; mapping: IntentMapping; handler: IntentHandler }
+
+/**
+ * Attach intent binding to one element. `profile` names the intents this element understands (falling back
+ * to {@link PRESETS} for built-in names); handlers are clung on later by `clingTo(intent, handler)`.
+ *
+ * One recogniser runs per element: pointer/keyboard events are watched once, resolved into a category
+ * (single / double / hold / context), and dispatched to whichever bound intents map that category for the
+ * event's `pointerType`. The app never sees the gesture — only its intent.
+ *
+ * Keyboard intents need a focusable element (a `keydown` only reaches `el` when it holds focus) — give it
+ * `tabindex="0"` and a `role`. Timings compare `event.timeStamp` across event types (all `DOMHighResTimeStamp`).
+ */
+export function yubisac(el: HTMLElement, profile: Profile = {}, config: YubisacConfig = {}): Finger {
+  const holdMs = config.hold ?? 500
+  const moveTolerance = config.tolerance ?? 8
+
+  const bindings = new Set<Binding>()
+  let listening = false
+  // Timestamp of the most recent touch activity. −Infinity until a touch happens, so a mouse event is never
+  // mistaken for a touch's compatibility event before any touch (the guard below would otherwise swallow
+  // early mouse events, whose timeStamp is small). Updated at both the start and the END of a touch.
+  let lastTouchAt = -Infinity
+
+  const mappingOf = (name: string): IntentMapping => {
+    const m = profile[name] ?? PRESETS[name]
+    if (!m) throw new Error(`yubisac: unknown intent "${name}" (not in profile or presets)`)
+    return m
+  }
+
+  /** Does any bound intent want this recogniser category on this device? */
+  const wants = (pointerType: PointerKind, category: Recogniser): boolean => {
+    for (const b of bindings) {
+      const g = b.mapping[pointerType]
+      if (g && RECOGNISER[g] === category) return true
+    }
+    return false
+  }
+
+  const fire = (category: Recogniser, pointerType: PointerKind, x: number, y: number, ev: PointerEvent | MouseEvent): void => {
+    for (const b of [...bindings]) {
+      // snapshot: a handler may destroy() / unbind mid-iteration
+      const g = b.mapping[pointerType]
+      if (g && RECOGNISER[g] === category && bindings.has(b)) b.handler({ intent: b.intent, pointerType, clientX: x, clientY: y, currentTarget: el, originalEvent: ev })
+    }
+  }
+
+  const fireKey = (name: string, handler: IntentHandler, ev: KeyboardEvent): void => {
+    const r = el.getBoundingClientRect()
+    handler({ intent: name, pointerType: 'keyboard', clientX: r.left + r.width / 2, clientY: r.top + r.height / 2, currentTarget: el, originalEvent: ev })
+  }
+
+  // A single tap can only be committed once we know it isn't the first half of a double, so it waits
+  // out DOUBLE_MS — but only when a double is actually bound for that device (otherwise it fires at once).
+  let pendingSingle: { timer: ReturnType<typeof setTimeout>; x: number; y: number; ev: PointerEvent; pointerType: PointerKind } | undefined
+  const clearPending = (): void => {
+    if (pendingSingle) clearTimeout(pendingSingle.timer)
+    pendingSingle = undefined
+  }
+  /** Cleanup for a press still in flight (window listeners + the hold timer). Cleared when it settles. */
+  let activePress: (() => void) | undefined
+
+  const ignored = (e: Event): boolean => (e.target as Element | null)?.closest('[data-yubisac-ignore]') != null
+
+  const onPointerDown = (e: PointerEvent): void => {
+    if (!e.isPrimary) return // ignore secondary touches of a multi-touch gesture
+    if (ignored(e)) return // a descendant opting out (e.g. a card with its own menu) keeps its own handling
+    if (e.pointerType === 'touch') lastTouchAt = e.timeStamp
+    // The browser fires compatibility mouse events after a touch; ignore them so we don't double-count.
+    if (e.pointerType === 'mouse' && e.timeStamp - lastTouchAt < COMPAT_MOUSE_MS) return
+    if (e.pointerType === 'mouse' && e.button !== 0) return // right/middle mouse come through `contextmenu`, not here
+    const pointerType = e.pointerType as PointerKind
+    const id = e.pointerId
+    const sx = e.clientX
+    const sy = e.clientY
+    let moved = false
+    let held = false
+    // Touch/pen: the browser fires its own long-press context menu, which pops a native menu over the app's.
+    // onContextMenu below deliberately skips the touch-synthesised contextmenu (to avoid double-firing an
+    // intent), so it would otherwise slip through — suppress the native menu for the life of this press.
+    // isTrusted only; mouse right-click comes through onContextMenu (button != 0 returned above), untouched.
+    const suppressNativeContextMenu = pointerType !== 'mouse' ? (ev: Event): void => { if (ev.isTrusted) ev.preventDefault() } : undefined
+
+    // A second press while a single is pending, close in time and place, resolves the pair as a double.
+    if (pendingSingle && pendingSingle.pointerType === pointerType && Math.hypot(sx - pendingSingle.x, sy - pendingSingle.y) < moveTolerance * 3) {
+      clearPending()
+      held = true // this down belongs to the double; its up must not start another single
+      fire('double', pointerType, sx, sy, e)
+    }
+
+    const holdTimer = wants(pointerType, 'hold')
+      ? setTimeout(() => {
+          if (moved || held) return // moved = drag/scroll; held = this down already completed a double
+          held = true // consumes this pointer: its up won't also fire a tap
+          fire('hold', pointerType, sx, sy, e)
+        }, holdMs)
+      : undefined
+
+    const teardown = (): void => {
+      if (holdTimer) clearTimeout(holdTimer)
+      // Mark the END of a touch too — the browser's compatibility mouse events arrive after the touch lifts,
+      // so the dedup window must be measured from here, not just from the down.
+      if (pointerType === 'touch') lastTouchAt = performance.now()
+      window.removeEventListener('pointermove', move)
+      window.removeEventListener('pointerup', up)
+      window.removeEventListener('pointercancel', cancel)
+      if (suppressNativeContextMenu) window.removeEventListener('contextmenu', suppressNativeContextMenu)
+      activePress = undefined
+    }
+    const move = (ev: PointerEvent): void => {
+      if (ev.pointerId !== id) return
+      if (Math.hypot(ev.clientX - sx, ev.clientY - sy) < moveTolerance) return
+      moved = true // a drag or a scroll — no tap, no hold
+      teardown()
+    }
+    const up = (ev: PointerEvent): void => {
+      if (ev.pointerId !== id) return
+      teardown()
+      if (moved || held) return // moved = drag/scroll; held = a double or long-press already spoke
+      if (wants(pointerType, 'double')) {
+        clearPending() // a stray earlier single that never doubled — don't leave its timer running
+        const timer = setTimeout(() => {
+          if (pendingSingle?.timer === timer) pendingSingle = undefined // only null my own entry
+          fire('single', pointerType, ev.clientX, ev.clientY, ev)
+        }, DOUBLE_MS)
+        pendingSingle = { timer, x: ev.clientX, y: ev.clientY, ev, pointerType }
+      } else {
+        fire('single', pointerType, ev.clientX, ev.clientY, ev)
+      }
+    }
+    const cancel = (ev: PointerEvent): void => {
+      if (ev.pointerId !== id) return
+      teardown() // scroll takeover / gesture aborted — drop the whole recognition
+    }
+    activePress = teardown
+    if (suppressNativeContextMenu) window.addEventListener('contextmenu', suppressNativeContextMenu)
+    // passive:false on move so a would-be hold that becomes a drag can still let the page scroll — we never
+    // preventDefault here (unlike goonteh), so touch scrolling keeps working; a real scroll fires pointercancel.
+    window.addEventListener('pointermove', move, { passive: false })
+    window.addEventListener('pointerup', up)
+    window.addEventListener('pointercancel', cancel)
+  }
+
+  const onContextMenu = (e: MouseEvent): void => {
+    if (ignored(e)) return
+    if (e.timeStamp - lastTouchAt < COMPAT_MOUSE_MS) return // a touch long-press can synthesise contextmenu; skip it here
+    if (!wants('mouse', 'context')) return
+    e.preventDefault() // a right-click intent is bound → the app opens its own menu, not the OS one
+    fire('context', 'mouse', e.clientX, e.clientY, e)
+  }
+
+  const onKeyDown = (e: KeyboardEvent): void => {
+    if (e.repeat) return // a held key auto-repeats; fire once, not a machine-gun
+    if (ignored(e)) return // a focused descendant opting out keeps its own handling
+    if (e.ctrlKey || e.metaKey || e.altKey) return // a shortcut, not a plain activation
+    const key = e.key.toLowerCase()
+    for (const b of [...bindings]) {
+      const keys = b.mapping.keyboard
+      if (!keys) continue
+      const list = Array.isArray(keys) ? keys : [keys]
+      if (list.some((k) => normalizeKey(k) === key) && bindings.has(b)) {
+        if (key === ' ') e.preventDefault() // Space would scroll the page
+        fireKey(b.intent, b.handler, e)
+      }
+    }
+  }
+
+  const startListening = (): void => {
+    if (listening) return
+    listening = true
+    el.addEventListener('pointerdown', onPointerDown)
+    el.addEventListener('contextmenu', onContextMenu)
+    el.addEventListener('keydown', onKeyDown)
+  }
+  const stopListening = (): void => {
+    if (!listening) return
+    listening = false
+    el.removeEventListener('pointerdown', onPointerDown)
+    el.removeEventListener('contextmenu', onContextMenu)
+    el.removeEventListener('keydown', onKeyDown)
+    activePress?.() // a press still in flight: drop its window listeners and hold timer
+    clearPending()
+  }
+
+  return {
+    clingTo(name, handler) {
+      const binding: Binding = { intent: name, mapping: mappingOf(name), handler }
+      bindings.add(binding)
+      startListening()
+      return () => {
+        bindings.delete(binding)
+        if (bindings.size === 0) stopListening()
+      }
+    },
+    destroy() {
+      bindings.clear()
+      stopListening()
+    },
+  }
+}

package/dist/core.d.ts

@@ -0,0 +1,82 @@
+/**
+ * yubisac core — a framework-agnostic **touch-first intent binding** engine.
+ *
+ * Not a gesture library. Hammer.js, interact.js, @use-gesture and tinygesture all recognise gestures
+ * (tap / double-tap / long-press / pinch …) and hand them to you as *separate* events. Pointer Events
+ * unify the input device but stop at "which device". The layer nobody owns is the one above: **every
+ * input clinging to the same operation intent** — a mouse double-click, a touch long-press and an Enter
+ * key are the one `inspect`. The app speaks in intents (`inspect`, `context`, `activate`); raw event
+ * names never leak into its code. Design for the tablet first, and let the desktop cling on.
+ *
+ * That is all yubisac does, and deliberately all it does: bind different inputs to one intent, and resolve
+ * the conflicts between them deterministically (single-vs-double wait, move cancels a hold, a touch's
+ * trailing compatibility-mouse events, scroll takeover). Recognition stays a tight set on purpose — the
+ * moment it grows into a gesture powerhouse it loses to the incumbents on their turf.
+ *
+ * Basis is the **per-event `pointerType`**, never a device flag: the same machine sends mouse, touch and
+ * pen events interchangeably, so the mapping is chosen per event, not per device.
+ *
+ * The name respells 指サック (yubi-sakku), the little cot worn on a fingertip for precise single-finger
+ * work — where goonteh (軍手, work gloves) is the whole hand gripping and dragging, yubisac is one
+ * fingertip tapping. Two hand-worn tools, one drag, one touch.
+ */
+/** Which pointing device an event came from — read per event, not per device. */
+export type PointerKind = 'mouse' | 'touch' | 'pen';
+/**
+ * A recognisable gesture token. Synonyms exist so a mapping reads naturally per device
+ * (`mouse: 'double-click'` vs `touch: 'double-tap'`); they collapse to the same recogniser.
+ */
+export type Gesture = 'click' | 'tap' | 'double-click' | 'double-tap' | 'long-press' | 'context-menu' | 'right-click';
+/** A keyboard key that fires an intent — `e.key` values (`'Enter'`, `'ContextMenu'`); `'Space'` is accepted for `' '`. */
+export type Key = string;
+/** How one intent is reached, per input. Omit a device to not bind that device for this intent. */
+export type IntentMapping = Partial<Record<PointerKind, Gesture>> & {
+    keyboard?: Key | Key[];
+};
+/** A named set of intent → per-input mappings. The app's intent vocabulary lives here, once. */
+export type Profile = Record<string, IntentMapping>;
+/** What a bound handler receives when its intent fires. `clientX/clientY` is the pointer (or the element centre for keyboard). */
+export type IntentEvent = {
+    intent: string;
+    pointerType: PointerKind | 'keyboard';
+    clientX: number;
+    clientY: number;
+    currentTarget: HTMLElement;
+    /** The raw event. A right-click intent carries a `MouseEvent` (contextmenu), a keyboard intent a `KeyboardEvent`. */
+    originalEvent: PointerEvent | MouseEvent | KeyboardEvent;
+};
+export type IntentHandler = (e: IntentEvent) => void;
+/** A binding handle for one element. Cling handlers to intents; `destroy()` removes every listener. */
+export type Finger = {
+    /** Cling a handler to a named intent (from this element's profile, else a built-in preset). Returns an off(). */
+    clingTo(intent: string, handler: IntentHandler): () => void;
+    destroy(): void;
+};
+/**
+ * The only two knobs, on purpose. Everything else (the double window, the post-touch compatibility-mouse
+ * window) is a browser-timing fact, not an app preference — kept as internal constants so the surface stays
+ * a finger cot, not a powered suit.
+ */
+export type YubisacConfig = {
+    /** Hold this long (ms) without moving to fire a long-press. Default 500. */
+    hold?: number;
+    /** Move more than this (px) and a tap/hold is abandoned (it's a drag or scroll). Default 8. */
+    tolerance?: number;
+};
+/**
+ * Built-in intent presets — a named default mapping you can bind straight away, or override per element
+ * by passing your own profile. Keyboard bindings make these an accessibility layer, not just touch support.
+ */
+export declare const PRESETS: Profile;
+/**
+ * Attach intent binding to one element. `profile` names the intents this element understands (falling back
+ * to {@link PRESETS} for built-in names); handlers are clung on later by `clingTo(intent, handler)`.
+ *
+ * One recogniser runs per element: pointer/keyboard events are watched once, resolved into a category
+ * (single / double / hold / context), and dispatched to whichever bound intents map that category for the
+ * event's `pointerType`. The app never sees the gesture — only its intent.
+ *
+ * Keyboard intents need a focusable element (a `keydown` only reaches `el` when it holds focus) — give it
+ * `tabindex="0"` and a `role`. Timings compare `event.timeStamp` across event types (all `DOMHighResTimeStamp`).
+ */
+export declare function yubisac(el: HTMLElement, profile?: Profile, config?: YubisacConfig): Finger;

package/dist/core.js

@@ -0,0 +1,178 @@
+// core.ts
+var DOUBLE_MS = 280;
+var COMPAT_MOUSE_MS = 500;
+var PRESETS = {
+  activate: { touch: "tap", pen: "tap", mouse: "click", keyboard: ["Enter", "Space"] },
+  "secondary-activate": { touch: "long-press", pen: "long-press", mouse: "double-click" },
+  // `context` is a desktop notion (a right-click / the ContextMenu key). Touch has no right-click, so it
+  // carries no touch mapping — reach for `secondary-activate` (a long-press) for the touch secondary action.
+  context: { mouse: "right-click", keyboard: "ContextMenu" }
+};
+var RECOGNISER = {
+  click: "single",
+  tap: "single",
+  "double-click": "double",
+  "double-tap": "double",
+  "long-press": "hold",
+  "context-menu": "context",
+  "right-click": "context"
+};
+var normalizeKey = (k) => k.toLowerCase() === "space" ? " " : k.toLowerCase();
+function yubisac(el, profile = {}, config = {}) {
+  const holdMs = config.hold ?? 500;
+  const moveTolerance = config.tolerance ?? 8;
+  const bindings = /* @__PURE__ */ new Set();
+  let listening = false;
+  let lastTouchAt = -Infinity;
+  const mappingOf = (name) => {
+    const m = profile[name] ?? PRESETS[name];
+    if (!m) throw new Error(`yubisac: unknown intent "${name}" (not in profile or presets)`);
+    return m;
+  };
+  const wants = (pointerType, category) => {
+    for (const b of bindings) {
+      const g = b.mapping[pointerType];
+      if (g && RECOGNISER[g] === category) return true;
+    }
+    return false;
+  };
+  const fire = (category, pointerType, x, y, ev) => {
+    for (const b of [...bindings]) {
+      const g = b.mapping[pointerType];
+      if (g && RECOGNISER[g] === category && bindings.has(b)) b.handler({ intent: b.intent, pointerType, clientX: x, clientY: y, currentTarget: el, originalEvent: ev });
+    }
+  };
+  const fireKey = (name, handler, ev) => {
+    const r = el.getBoundingClientRect();
+    handler({ intent: name, pointerType: "keyboard", clientX: r.left + r.width / 2, clientY: r.top + r.height / 2, currentTarget: el, originalEvent: ev });
+  };
+  let pendingSingle;
+  const clearPending = () => {
+    if (pendingSingle) clearTimeout(pendingSingle.timer);
+    pendingSingle = void 0;
+  };
+  let activePress;
+  const ignored = (e) => e.target?.closest("[data-yubisac-ignore]") != null;
+  const onPointerDown = (e) => {
+    if (!e.isPrimary) return;
+    if (ignored(e)) return;
+    if (e.pointerType === "touch") lastTouchAt = e.timeStamp;
+    if (e.pointerType === "mouse" && e.timeStamp - lastTouchAt < COMPAT_MOUSE_MS) return;
+    if (e.pointerType === "mouse" && e.button !== 0) return;
+    const pointerType = e.pointerType;
+    const id = e.pointerId;
+    const sx = e.clientX;
+    const sy = e.clientY;
+    let moved = false;
+    let held = false;
+    const suppressNativeContextMenu = pointerType !== "mouse" ? (ev) => {
+      if (ev.isTrusted) ev.preventDefault();
+    } : void 0;
+    if (pendingSingle && pendingSingle.pointerType === pointerType && Math.hypot(sx - pendingSingle.x, sy - pendingSingle.y) < moveTolerance * 3) {
+      clearPending();
+      held = true;
+      fire("double", pointerType, sx, sy, e);
+    }
+    const holdTimer = wants(pointerType, "hold") ? setTimeout(() => {
+      if (moved || held) return;
+      held = true;
+      fire("hold", pointerType, sx, sy, e);
+    }, holdMs) : void 0;
+    const teardown = () => {
+      if (holdTimer) clearTimeout(holdTimer);
+      if (pointerType === "touch") lastTouchAt = performance.now();
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", up);
+      window.removeEventListener("pointercancel", cancel);
+      if (suppressNativeContextMenu) window.removeEventListener("contextmenu", suppressNativeContextMenu);
+      activePress = void 0;
+    };
+    const move = (ev) => {
+      if (ev.pointerId !== id) return;
+      if (Math.hypot(ev.clientX - sx, ev.clientY - sy) < moveTolerance) return;
+      moved = true;
+      teardown();
+    };
+    const up = (ev) => {
+      if (ev.pointerId !== id) return;
+      teardown();
+      if (moved || held) return;
+      if (wants(pointerType, "double")) {
+        clearPending();
+        const timer = setTimeout(() => {
+          if (pendingSingle?.timer === timer) pendingSingle = void 0;
+          fire("single", pointerType, ev.clientX, ev.clientY, ev);
+        }, DOUBLE_MS);
+        pendingSingle = { timer, x: ev.clientX, y: ev.clientY, ev, pointerType };
+      } else {
+        fire("single", pointerType, ev.clientX, ev.clientY, ev);
+      }
+    };
+    const cancel = (ev) => {
+      if (ev.pointerId !== id) return;
+      teardown();
+    };
+    activePress = teardown;
+    if (suppressNativeContextMenu) window.addEventListener("contextmenu", suppressNativeContextMenu);
+    window.addEventListener("pointermove", move, { passive: false });
+    window.addEventListener("pointerup", up);
+    window.addEventListener("pointercancel", cancel);
+  };
+  const onContextMenu = (e) => {
+    if (ignored(e)) return;
+    if (e.timeStamp - lastTouchAt < COMPAT_MOUSE_MS) return;
+    if (!wants("mouse", "context")) return;
+    e.preventDefault();
+    fire("context", "mouse", e.clientX, e.clientY, e);
+  };
+  const onKeyDown = (e) => {
+    if (e.repeat) return;
+    if (ignored(e)) return;
+    if (e.ctrlKey || e.metaKey || e.altKey) return;
+    const key = e.key.toLowerCase();
+    for (const b of [...bindings]) {
+      const keys = b.mapping.keyboard;
+      if (!keys) continue;
+      const list = Array.isArray(keys) ? keys : [keys];
+      if (list.some((k) => normalizeKey(k) === key) && bindings.has(b)) {
+        if (key === " ") e.preventDefault();
+        fireKey(b.intent, b.handler, e);
+      }
+    }
+  };
+  const startListening = () => {
+    if (listening) return;
+    listening = true;
+    el.addEventListener("pointerdown", onPointerDown);
+    el.addEventListener("contextmenu", onContextMenu);
+    el.addEventListener("keydown", onKeyDown);
+  };
+  const stopListening = () => {
+    if (!listening) return;
+    listening = false;
+    el.removeEventListener("pointerdown", onPointerDown);
+    el.removeEventListener("contextmenu", onContextMenu);
+    el.removeEventListener("keydown", onKeyDown);
+    activePress?.();
+    clearPending();
+  };
+  return {
+    clingTo(name, handler) {
+      const binding = { intent: name, mapping: mappingOf(name), handler };
+      bindings.add(binding);
+      startListening();
+      return () => {
+        bindings.delete(binding);
+        if (bindings.size === 0) stopListening();
+      };
+    },
+    destroy() {
+      bindings.clear();
+      stopListening();
+    }
+  };
+}
+export {
+  PRESETS,
+  yubisac
+};

package/dist/yubisac.global.js

@@ -0,0 +1,2 @@
+"use strict";var __yubisac=(()=>{var M=Object.defineProperty;var B=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var G=(t,s)=>{for(var a in s)M(t,a,{get:s[a],enumerable:!0})},z=(t,s,a,m)=>{if(s&&typeof s=="object"||typeof s=="function")for(let u of H(s))!U.call(t,u)&&u!==a&&M(t,u,{get:()=>s[u],enumerable:!(m=B(s,u))||m.enumerable});return t};var F=t=>z(M({},"__esModule",{value:!0}),t);var j={};G(j,{PRESETS:()=>X,yubisac:()=>$});var X={activate:{touch:"tap",pen:"tap",mouse:"click",keyboard:["Enter","Space"]},"secondary-activate":{touch:"long-press",pen:"long-press",mouse:"double-click"},context:{mouse:"right-click",keyboard:"ContextMenu"}},O={click:"single",tap:"single","double-click":"double","double-tap":"double","long-press":"hold","context-menu":"context","right-click":"context"},N=t=>t.toLowerCase()==="space"?" ":t.toLowerCase();function $(t,s={},a={}){let m=a.hold??500,u=a.tolerance??8,l=new Set,y=!1,v=-1/0,_=e=>{let n=s[e]??X[e];if(!n)throw new Error(`yubisac: unknown intent "${e}" (not in profile or presets)`);return n},w=(e,n)=>{for(let r of l){let i=r.mapping[e];if(i&&O[i]===n)return!0}return!1},g=(e,n,r,i,p)=>{for(let d of[...l]){let f=d.mapping[n];f&&O[f]===e&&l.has(d)&&d.handler({intent:d.intent,pointerType:n,clientX:r,clientY:i,currentTarget:t,originalEvent:p})}},D=(e,n,r)=>{let i=t.getBoundingClientRect();n({intent:e,pointerType:"keyboard",clientX:i.left+i.width/2,clientY:i.top+i.height/2,currentTarget:t,originalEvent:r})},c,h=()=>{c&&clearTimeout(c.timer),c=void 0},x,T=e=>e.target?.closest("[data-yubisac-ignore]")!=null,P=e=>{if(!e.isPrimary||T(e)||(e.pointerType==="touch"&&(v=e.timeStamp),e.pointerType==="mouse"&&e.timeStamp-v<500)||e.pointerType==="mouse"&&e.button!==0)return;let n=e.pointerType,r=e.pointerId,i=e.clientX,p=e.clientY,d=!1,f=!1,E=n!=="mouse"?o=>{o.isTrusted&&o.preventDefault()}:void 0;c&&c.pointerType===n&&Math.hypot(i-c.x,p-c.y)<u*3&&(h(),f=!0,g("double",n,i,p,e));let S=w(n,"hold")?setTimeout(()=>{d||f||(f=!0,g("hold",n,i,p,e))},m):void 0,b=()=>{S&&clearTimeout(S),n==="touch"&&(v=performance.now()),window.removeEventListener("pointermove",I),window.removeEventListener("pointerup",C),window.removeEventListener("pointercancel",R),E&&window.removeEventListener("contextmenu",E),x=void 0},I=o=>{o.pointerId===r&&(Math.hypot(o.clientX-i,o.clientY-p)<u||(d=!0,b()))},C=o=>{if(o.pointerId===r&&(b(),!(d||f)))if(w(n,"double")){h();let Y=setTimeout(()=>{c?.timer===Y&&(c=void 0),g("single",n,o.clientX,o.clientY,o)},280);c={timer:Y,x:o.clientX,y:o.clientY,ev:o,pointerType:n}}else g("single",n,o.clientX,o.clientY,o)},R=o=>{o.pointerId===r&&b()};x=b,E&&window.addEventListener("contextmenu",E),window.addEventListener("pointermove",I,{passive:!1}),window.addEventListener("pointerup",C),window.addEventListener("pointercancel",R)},L=e=>{T(e)||e.timeStamp-v<500||w("mouse","context")&&(e.preventDefault(),g("context","mouse",e.clientX,e.clientY,e))},k=e=>{if(e.repeat||T(e)||e.ctrlKey||e.metaKey||e.altKey)return;let n=e.key.toLowerCase();for(let r of[...l]){let i=r.mapping.keyboard;if(!i)continue;(Array.isArray(i)?i:[i]).some(d=>N(d)===n)&&l.has(r)&&(n===" "&&e.preventDefault(),D(r.intent,r.handler,e))}},A=()=>{y||(y=!0,t.addEventListener("pointerdown",P),t.addEventListener("contextmenu",L),t.addEventListener("keydown",k))},K=()=>{y&&(y=!1,t.removeEventListener("pointerdown",P),t.removeEventListener("contextmenu",L),t.removeEventListener("keydown",k),x?.(),h())};return{clingTo(e,n){let r={intent:e,mapping:_(e),handler:n};return l.add(r),A(),()=>{l.delete(r),l.size===0&&K()}},destroy(){l.clear(),K()}}}return F(j);})();
+window.yubisac=__yubisac.yubisac;

package/index.ts

@@ -0,0 +1 @@
+export * from './core'

package/native.ts

@@ -0,0 +1,22 @@
+import { yubisac, type Finger, type IntentHandler, type Profile, type YubisacConfig } from './core'
+
+/**
+ * yubisac — native (vanilla DOM) adapter.
+ *
+ * The core is already framework-free (`yubisac(el, …)`), so this only adds one convenience: bind a whole
+ * map of intent → handler in a single call. Everything from `./core` is re-exported. Needs no dependencies.
+ *
+ * ```ts
+ * import { cling } from 'yubisac/native'
+ * const finger = cling(card, { inspect: openInspector }, { profile: { inspect: { mouse: 'double-click', touch: 'long-press' } } })
+ * finger.destroy()
+ * ```
+ */
+export * from './core'
+
+/** Attach a map of intents to an element in one call; returns the {@link Finger} (call `destroy()` to unbind). */
+export function cling(el: HTMLElement, on: Record<string, IntentHandler>, opts?: { profile?: Profile; config?: YubisacConfig }): Finger {
+  const finger = yubisac(el, opts?.profile, opts?.config)
+  for (const [name, handler] of Object.entries(on)) finger.clingTo(name, handler)
+  return finger
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "yubisac",
+  "version": "0.9.1",
+  "description": "Touch-first intent binding. Design for the tablet, then let mouse, pen and keyboard cling to the same intent — so your app speaks in intents, not events.",
+  "type": "module",
+  "license": "MIT",
+  "author": "mrksye",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrksye/yubisac.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrksye/yubisac/issues"
+  },
+  "homepage": "https://github.com/mrksye/yubisac#readme",
+  "keywords": [
+    "intent",
+    "gesture",
+    "pointer-events",
+    "touch",
+    "pen",
+    "long-press",
+    "double-click",
+    "accessibility",
+    "input",
+    "solid-js",
+    "solidjs",
+    "react",
+    "vue",
+    "svelte"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test/yubisac.test.mjs",
+    "build": "rm -rf dist && node build.mjs && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.40.0",
+    "solid-js": "^1.8.0",
+    "react": "^18.3.0",
+    "@types/react": "^18.3.0",
+    "vue": "^3.4.0",
+    "svelte": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "core.ts",
+    "native.ts",
+    "solid.tsx",
+    "react.tsx",
+    "react-native.tsx",
+    "vue.ts",
+    "svelte.ts",
+    "index.ts",
+    "README.md",
+    "EXAMPLES.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "main": "./dist/core.js",
+  "module": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "unpkg": "./dist/yubisac.global.js",
+  "jsdelivr": "./dist/yubisac.global.js",
+  "exports": {
+    ".": { "types": "./dist/core.d.ts", "import": "./dist/core.js" },
+    "./core": { "types": "./dist/core.d.ts", "import": "./dist/core.js" },
+    "./global": "./dist/yubisac.global.js",
+    "./native": "./native.ts",
+    "./solid": "./solid.tsx",
+    "./react": "./react.tsx",
+    "./react-native": "./react-native.tsx",
+    "./vue": "./vue.ts",
+    "./svelte": "./svelte.ts"
+  },
+  "peerDependencies": {
+    "solid-js": ">=1.6.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "vue": ">=3.2.0",
+    "svelte": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "solid-js": { "optional": true },
+    "react": { "optional": true },
+    "react-native": { "optional": true },
+    "vue": { "optional": true },
+    "svelte": { "optional": true }
+  }
+}

package/react-native.tsx

@@ -0,0 +1,138 @@
+/** @jsxImportSource react */
+import { useEffect, useMemo, useRef, type ReactNode } from 'react'
+import { PanResponder, View, type GestureResponderEvent, type StyleProp, type ViewStyle } from 'react-native'
+import { PRESETS, type Profile, type YubisacConfig } from './core'
+
+/**
+ * yubisac — React Native adapter (experimental).
+ *
+ * React Native has no DOM or Pointer Events, so this does NOT reuse the web core (`./core`) — it ships a
+ * tiny `PanResponder`-based recogniser instead (no extra deps). Only the `touch` mapping of each intent
+ * applies (there is no mouse/pen/keyboard here), and recognition is the same small set: tap / double-tap /
+ * long-press. It claims the touch on start but yields to a parent (a `ScrollView`) on request, so scrolling
+ * still works. Outside the web core's guarantees. `react` and `react-native` are optional peer dependencies.
+ */
+
+/** What a bound handler receives on React Native (screen coordinates; no DOM node). */
+export type RNIntentEvent = { intent: string; x: number; y: number }
+export type RNIntentHandler = (e: RNIntentEvent) => void
+
+/** The `touch` gestures that map to a recogniser on RN (mouse/pen/keyboard tokens are ignored here). */
+const CATEGORY: Record<string, 'single' | 'double' | 'hold' | undefined> = {
+  tap: 'single',
+  click: 'single',
+  'double-tap': 'double',
+  'double-click': 'double',
+  'long-press': 'hold',
+}
+/** A second tap within this long (ms) resolves the pair as a double. */
+const DOUBLE_MS = 280
+
+/** Bind intents to a View. Spread the returned handlers onto a `<View {...panHandlers}>`. */
+export function useCling(on: Record<string, RNIntentHandler>, opts?: { profile?: Profile; config?: YubisacConfig }) {
+  const latest = useRef({ on, opts })
+  latest.current = { on, opts }
+  const s = useRef({ startX: 0, startY: 0, moved: false, held: false, lastTapAt: 0, holdTimer: undefined as ReturnType<typeof setTimeout> | undefined, singleTimer: undefined as ReturnType<typeof setTimeout> | undefined })
+  // Clear any armed timer on unmount so it never fires a handler on a gone component.
+  useEffect(() => () => {
+    if (s.current.holdTimer) clearTimeout(s.current.holdTimer)
+    if (s.current.singleTimer) clearTimeout(s.current.singleTimer)
+  }, [])
+
+  const panHandlers = useMemo(() => {
+    const cfg = () => latest.current.opts?.config
+    const mappingOf = (name: string) => latest.current.opts?.profile?.[name] ?? PRESETS[name]
+    const wants = (cat: 'single' | 'double' | 'hold'): boolean =>
+      Object.keys(latest.current.on).some((n) => {
+        const g = mappingOf(n)?.touch
+        return g !== undefined && CATEGORY[g] === cat
+      })
+    const fire = (cat: 'single' | 'double' | 'hold', x: number, y: number): void => {
+      for (const [name, handler] of Object.entries(latest.current.on)) {
+        const g = mappingOf(name)?.touch
+        if (g !== undefined && CATEGORY[g] === cat) handler({ intent: name, x, y })
+      }
+    }
+    const clearTimers = (): void => {
+      if (s.current.holdTimer) clearTimeout(s.current.holdTimer)
+      if (s.current.singleTimer) clearTimeout(s.current.singleTimer)
+      s.current.holdTimer = undefined
+      s.current.singleTimer = undefined
+    }
+
+    return PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: () => false, // never claim a move → a parent ScrollView keeps scrolling
+      onPanResponderTerminationRequest: () => true, // let scroll/parent win; we abandon recognition
+      onPanResponderGrant: (e: GestureResponderEvent) => {
+        clearTimers()
+        s.current.startX = e.nativeEvent.pageX
+        s.current.startY = e.nativeEvent.pageY
+        s.current.moved = false
+        s.current.held = false
+        if (wants('hold')) {
+          s.current.holdTimer = setTimeout(() => {
+            if (s.current.moved) return
+            s.current.held = true
+            fire('hold', s.current.startX, s.current.startY)
+          }, cfg()?.hold ?? 500)
+        }
+      },
+      onPanResponderMove: (e: GestureResponderEvent) => {
+        const dx = e.nativeEvent.pageX - s.current.startX
+        const dy = e.nativeEvent.pageY - s.current.startY
+        if (Math.hypot(dx, dy) < (cfg()?.tolerance ?? 8)) return
+        s.current.moved = true
+        if (s.current.holdTimer) clearTimeout(s.current.holdTimer)
+      },
+      onPanResponderRelease: (e: GestureResponderEvent) => {
+        if (s.current.holdTimer) clearTimeout(s.current.holdTimer)
+        if (s.current.moved || s.current.held) return
+        const x = e.nativeEvent.pageX
+        const y = e.nativeEvent.pageY
+        const now = Date.now()
+        if (wants('double') && now - s.current.lastTapAt < DOUBLE_MS) {
+          if (s.current.singleTimer) clearTimeout(s.current.singleTimer)
+          s.current.singleTimer = undefined
+          s.current.lastTapAt = 0
+          fire('double', x, y)
+        } else if (wants('double')) {
+          s.current.lastTapAt = now
+          s.current.singleTimer = setTimeout(() => fire('single', x, y), DOUBLE_MS)
+        } else {
+          fire('single', x, y)
+        }
+      },
+      onPanResponderTerminate: () => {
+        clearTimers()
+        s.current.moved = false
+        s.current.held = false
+      },
+    }).panHandlers
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return panHandlers
+}
+
+/** JSX wrapper: a View that binds `on` (intent → handler). */
+export function Cling({
+  on,
+  profile,
+  config,
+  style,
+  children,
+}: {
+  on: Record<string, RNIntentHandler>
+  profile?: Profile
+  config?: YubisacConfig
+  style?: StyleProp<ViewStyle>
+  children: ReactNode
+}) {
+  const panHandlers = useCling(on, { profile, config })
+  return (
+    <View style={style} {...panHandlers}>
+      {children}
+    </View>
+  )
+}

package/react.tsx

@@ -0,0 +1,55 @@
+/** @jsxImportSource react */
+import { useEffect, useRef, type CSSProperties, type ReactNode, type RefObject } from 'react'
+import { yubisac, type IntentHandler, type Profile, type YubisacConfig } from './core'
+
+/**
+ * yubisac — React adapter.
+ *
+ * yubisac is element-local — no shared context, so no provider. `useCling` returns a ref you put on an
+ * element; it binds the intents on mount and removes every listener on unmount. Handlers are read through a
+ * ref so the stable binding always calls the current one. `react` is an optional peer dependency.
+ */
+
+/** Bind intents to an element via the returned ref. Pass a `profile` for custom intents; presets work without one. */
+export function useCling<T extends HTMLElement = HTMLDivElement>(
+  on: Record<string, IntentHandler>,
+  opts?: { profile?: Profile; config?: YubisacConfig },
+): RefObject<T> {
+  const ref = useRef<T>(null)
+  const latest = useRef(on)
+  latest.current = on
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const finger = yubisac(el, opts?.profile, opts?.config)
+    for (const name of Object.keys(latest.current)) finger.clingTo(name, (e) => latest.current[name]?.(e))
+    return () => finger.destroy()
+    // Bind once; profile/config are treated as create-time options (like goonteh's kind).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  return ref
+}
+
+/** JSX wrapper: binds `on` (intent → handler) to its own element. */
+export function Cling({
+  on,
+  profile,
+  config,
+  className,
+  style,
+  children,
+}: {
+  on: Record<string, IntentHandler>
+  profile?: Profile
+  config?: YubisacConfig
+  className?: string
+  style?: CSSProperties
+  children: ReactNode
+}) {
+  const ref = useCling<HTMLDivElement>(on, { profile, config })
+  return (
+    <div ref={ref} className={className} style={style}>
+      {children}
+    </div>
+  )
+}

package/solid.tsx

@@ -0,0 +1,38 @@
+import { onCleanup, type JSX } from 'solid-js'
+import { yubisac, type IntentHandler, type Profile, type YubisacConfig } from './core'
+
+/**
+ * SolidJS binding for yubisac. yubisac is element-local (no shared/global state like goonteh's drag
+ * context), so there is no Provider — you just attach intents to an element.
+ *
+ * `cling` fits an element's `ref` and binds a map of intent → handler; `<Cling>` is the JSX wrapper.
+ * Both register on mount and remove every listener on cleanup.
+ */
+
+/** Bind intents to an element via its `ref`. Pass a `profile` to define custom intents; built-in presets work without one. */
+export function cling(
+  on: Record<string, IntentHandler>,
+  opts?: { profile?: Profile; config?: YubisacConfig },
+): (el: HTMLElement) => void {
+  return (el) => {
+    const finger = yubisac(el, opts?.profile, opts?.config)
+    for (const [name, handler] of Object.entries(on)) finger.clingTo(name, handler)
+    onCleanup(() => finger.destroy())
+  }
+}
+
+/** JSX wrapper: binds `on` (intent → handler) to its own element. `class`/`style` pass through. */
+export function Cling(props: {
+  on: Record<string, IntentHandler>
+  profile?: Profile
+  config?: YubisacConfig
+  class?: string
+  style?: JSX.CSSProperties
+  children: JSX.Element
+}): JSX.Element {
+  return (
+    <div ref={cling(props.on, { profile: props.profile, config: props.config })} class={props.class} style={props.style}>
+      {props.children}
+    </div>
+  )
+}

package/svelte.ts

@@ -0,0 +1,34 @@
+import { yubisac, type Finger, type IntentHandler, type Profile, type YubisacConfig } from './core'
+
+/**
+ * yubisac — Svelte adapter.
+ *
+ * Idiomatic Svelte: a use-directive **action** that attaches intents to an element. Built on the
+ * framework-agnostic core (`./core`); `svelte` is an optional peer dependency.
+ *
+ * ```svelte
+ * <script>
+ *   import { cling } from 'yubisac/svelte'
+ * </script>
+ * <div use:cling={{ on: { inspect: openInspector }, profile: { inspect: { mouse: 'double-click', touch: 'long-press' } } }}>…</div>
+ * ```
+ */
+export type ClingParams = { on: Record<string, IntentHandler>; profile?: Profile; config?: YubisacConfig }
+
+const bind = (el: HTMLElement, p: ClingParams): Finger => {
+  const finger = yubisac(el, p.profile, p.config)
+  for (const [name, handler] of Object.entries(p.on)) finger.clingTo(name, handler)
+  return finger
+}
+
+/** `use:cling={{ on, profile?, config? }}` — binds intents to the element; rebinds on param change. */
+export function cling(el: HTMLElement, params: ClingParams): { update(p: ClingParams): void; destroy(): void } {
+  let finger = bind(el, params)
+  return {
+    update: (next) => {
+      finger.destroy()
+      finger = bind(el, next)
+    },
+    destroy: () => finger.destroy(),
+  }
+}

package/vue.ts

@@ -0,0 +1,39 @@
+import type { Directive } from 'vue'
+import { yubisac, type Finger, type IntentHandler, type Profile, type YubisacConfig } from './core'
+
+/**
+ * yubisac — Vue 3 adapter.
+ *
+ * yubisac attaches behaviour to one element with no shared state, which is exactly what a Vue **directive**
+ * is for — so this is a directive, not components. `vue` is an optional peer dependency.
+ *
+ * ```vue
+ * <script setup>
+ *   import { vCling } from 'yubisac/vue'
+ * </script>
+ * <div v-cling="{ on: { inspect: openInspector }, profile: { inspect: { mouse: 'double-click', touch: 'long-press' } } }">…</div>
+ * ```
+ */
+export type YubisacBinding = { on: Record<string, IntentHandler>; profile?: Profile; config?: YubisacConfig }
+
+type BoundEl = HTMLElement & { __yubisac?: Finger }
+
+const bind = (el: BoundEl, value: YubisacBinding): void => {
+  el.__yubisac?.destroy()
+  const finger = yubisac(el, value.profile, value.config)
+  for (const [name, handler] of Object.entries(value.on)) finger.clingTo(name, handler)
+  el.__yubisac = finger
+}
+
+/** `v-cling="{ on, profile?, config? }"` — binds intents to the element for its lifetime. */
+export const vCling: Directive<BoundEl, YubisacBinding> = {
+  mounted: (el, binding) => bind(el, binding.value),
+  // Only rebind when the binding value actually changed — a re-render alone must not tear down a live press.
+  updated: (el, binding) => {
+    if (binding.value !== binding.oldValue) bind(el, binding.value)
+  },
+  unmounted: (el) => {
+    el.__yubisac?.destroy()
+    el.__yubisac = undefined
+  },
+}