layershift 0.4.2 → 0.5.0

package/README.md

@@ -52,7 +52,7 @@ npm install layershift
 
 ```js
 import 'layershift';
-// <layershift-effect> and <layershift-portal> are now registered
+// <layershift-effect> is now registered
 ```
 
 ### TypeScript
@@ -135,7 +135,7 @@ Components follow atomic design (Atoms → Molecules → Organisms → Templates
 
 | Event | Detail | When |
 |-------|--------|------|
-| `layershift-effect:ready` | `{ videoWidth, videoHeight, duration }` | Initialization complete |
+| `layershift-effect:ready` | `{ videoWidth, videoHeight, duration, motionConfig }` | Initialization complete |
 | `layershift-effect:play` | `{ currentTime }` | Video starts playing |
 | `layershift-effect:pause` | `{ currentTime }` | Video pauses |
 | `layershift-effect:loop` | `{ loopCount }` | Video loops back to start |
@@ -150,6 +150,84 @@ el.addEventListener('layershift-effect:ready', (e) => {
 });
 ```
 
+### Input
+
+The component reads its position offset from the `input` property every frame. This decoupled design lets you use the built-in helpers or wire your own input source.
+
+#### Quick Setup
+
+Wire input on the ready event using the authored motion settings:
+
+**ESM (npm)**
+```js
+import { connectPointer } from 'layershift';
+
+const el = document.querySelector('layershift-effect');
+el.addEventListener('layershift-effect:ready', (e) => {
+  const { motionConfig } = e.detail;
+  const cleanup = connectPointer(el, motionConfig);
+  // Call cleanup() to stop input tracking
+});
+```
+
+**IIFE (script tag)**
+```js
+const el = document.querySelector('layershift-effect');
+el.addEventListener('layershift-effect:ready', (e) => {
+  const { motionConfig } = e.detail;
+  Layershift.connectPointer(el, motionConfig);
+});
+```
+
+#### Manual Input
+
+Skip the helpers entirely and set `el.input` directly:
+
+```js
+el.input = { x: 0.5, y: -0.3 }; // normalized -1 to 1
+```
+
+This works with any input source — MIDI controllers, WebSocket streams, scroll position, animation timelines, or your own custom logic.
+
+#### Helpers Reference
+
+| Helper | Input Source | Best For |
+|--------|-------------|----------|
+| `connectPointer(el, opts?)` | Mouse + touch + gyro | Default — handles all devices |
+| `connectMouse(el, opts?)` | Mouse only | Desktop-only experiences |
+| `connectTouch(el, opts?)` | Touch drag | Touch-only experiences |
+| `connectGyro(el, opts?)` | Device orientation | Mobile tilt control |
+
+Each helper returns a cleanup function. Do not combine standalone helpers on the same element — use `connectPointer` instead.
+
+#### InputOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sensitivityX` | number | 1 | Horizontal multiplier |
+| `sensitivityY` | number | 1 | Vertical multiplier |
+| `lerpFactor` | number | 0.08 | Smoothing factor (0–1, lower = smoother) |
+
+```js
+connectPointer(el, {
+  sensitivityX: 0.4,  // subtle horizontal movement
+  sensitivityY: 1.0,  // full vertical movement
+  lerpFactor: 0.08,   // smooth interpolation
+});
+```
+
+#### TypeScript
+
+```ts
+import { connectPointer, connectMouse, type InputOptions } from 'layershift';
+import type { EffectInput } from 'layershift';
+
+const el = document.querySelector('layershift-effect')!;
+const cleanup = connectPointer(el as HTMLElement & { input: EffectInput }, {
+  sensitivityX: 0.4,
+});
+```
+
 ### Performance
 
 Each `<layershift-effect>` instance creates 1 WebGL renderer, 1 Web Worker, 1 hidden `<video>` element, and 2 GPU textures (1 draw call per frame). The bilateral filter runs entirely off the main thread.