layershift 0.1.0

package/LICENSE

@@ -0,0 +1,65 @@
+Business Source License 1.1
+
+Copyright (c) 2025 Jeremy Sykes
+All rights reserved.
+
+Licensor: Jeremy Sykes
+
+Change Date: 2029-01-01
+
+Change License: Apache License, Version 2.0
+
+On the Change Date specified above, the Business Source License covering this file will change to the Apache License, Version 2.0.
+
+Additional Use Grant
+
+You may use, reproduce, and distribute this software and its documentation for:
+
+1. Non-commercial purposes, including personal projects and educational use
+2. Internal enterprise evaluation and testing purposes
+3. Academic research and educational institutions
+4. Open source projects that are not commercial SaaS offerings
+
+You may NOT use this software for:
+
+1. Providing this software as a service (SaaS) to third parties
+2. Reselling, redistributing, or sublicensing this software commercially
+3. Including this software in commercial products or services without a separate commercial license
+4. Using this software to compete with the licensor's commercial offerings
+
+For commercial use beyond the scope of this license, please contact the licensor to obtain a commercial license.
+
+---
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and use non-production and production use in any form, with the right to sublicense such rights through multiple tiers of sublicensees, solely to the extent of the following:
+
+1. You may use, reproduce, and distribute this software and its documentation for non-commercial, personal, educational, and internal enterprise evaluation purposes.
+
+2. You may NOT use this software for:
+   a. Providing this software as a service (SaaS) to third parties
+   b. Reselling, redistributing, or sublicensing this software commercially
+   c. Including this software in commercial products or services without a separate commercial license
+   d. Using this software to compete with the licensor's commercial offerings
+
+3. If you wish to use this software for commercial purposes beyond the scope of this license, you must obtain a separate commercial license from the Licensor.
+
+4. This license does not grant you any rights to use the Licensor's trademarks, service marks, or other intellectual property except as necessary to use this software as licensed.
+
+5. 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.
+
+6. In no event shall the Licensor 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.
+
+Change Date: 2029-01-01
+
+Change License: Apache License, Version 2.0
+
+On the Change Date specified above, the Business Source License covering this file will change to the Apache License, Version 2.0, as published by the Apache Software Foundation.
+
+---
+
+For questions about commercial licensing, please contact:
+Jeremy Sykes

package/README.md

@@ -0,0 +1,196 @@
+# Layershift
+
+Embeddable video effects as Web Components. One script tag, one custom element — works in plain HTML, React, Vue, Svelte, Angular, WordPress, and anywhere else.
+
+Layershift is a growing collection of visual effects that turn flat video into something interactive. Each effect ships as its own custom element under the `layershift-*` namespace.
+
+## Effects
+
+### `<layershift-parallax>` — Depth-Aware Parallax Video
+
+A precomputed depth map drives per-pixel UV displacement with Parallax Occlusion Mapping (POM), so near objects move more than far objects — creating a convincing 3D effect from a single 2D video.
+
+```html
+<script src="https://cdn.layershift.io/layershift.js"></script>
+
+<layershift-parallax
+  src="video.mp4"
+  depth-src="depth-data.bin"
+  depth-meta="depth-meta.json"
+></layershift-parallax>
+```
+
+**[Live demo →](https://layershift.io)**
+
+---
+
+## Prerequisites
+
+The `precompute` script needs **FFmpeg** to read video metadata and extract frames.
+
+- **macOS:** `brew install ffmpeg`
+- **Windows:** [FFmpeg downloads](https://ffmpeg.org/download.html) or `winget install FFmpeg`
+- **Linux:** `apt install ffmpeg` / `dnf install ffmpeg`
+
+## Setup
+
+```bash
+npm install
+```
+
+## Precompute Depth Data
+
+```bash
+npm run precompute
+```
+
+Generates `public/depth-data.bin` and `public/depth-meta.json` from the video in `public/sample.mp4`.
+
+## Development
+
+```bash
+npm run dev
+```
+
+## Build
+
+```bash
+# Build the landing page
+npm run build
+
+# Build the standalone Web Component
+npm run build:component
+
+# Package output (video + depth data + component + demo page)
+npm run package
+```
+
+---
+
+## `<layershift-parallax>` Reference
+
+### Configuration
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `src` | string | — | Video file URL (required) |
+| `depth-src` | string | — | Depth binary URL (required) |
+| `depth-meta` | string | — | Depth metadata URL (required) |
+| `parallax-x` | number | 0.4 | Horizontal parallax intensity |
+| `parallax-y` | number | 1.0 | Vertical parallax intensity |
+| `parallax-max` | number | 30 | Max pixel offset for nearest layer |
+| `overscan` | number | 0.05 | Extra padding ratio |
+| `autoplay` | boolean | true | Auto-play on mount |
+| `loop` | boolean | true | Loop playback |
+| `muted` | boolean | true | Muted (required for autoplay) |
+
+### Framework Wrappers
+
+```js
+// React
+import { Layershift } from 'layershift/react'
+
+// Vue
+import Layershift from 'layershift/vue'
+
+// Svelte
+import Layershift from 'layershift/svelte'
+
+// Angular
+import { LayershiftComponent } from 'layershift/angular'
+```
+
+**Vue note:** Add `compilerOptions.isCustomElement: (tag) => tag === 'layershift-parallax'` to your Vite or Vue config.
+
+**Angular note:** Add `CUSTOM_ELEMENTS_SCHEMA` to your module or component schemas.
+
+### Events
+
+The `<layershift-parallax>` element dispatches custom events that bubble through the DOM (including Shadow DOM):
+
+| Event | Detail | When |
+|-------|--------|------|
+| `layershift-parallax:ready` | `{ videoWidth, videoHeight, duration }` | Initialization complete |
+| `layershift-parallax:play` | `{ currentTime }` | Video starts playing |
+| `layershift-parallax:pause` | `{ currentTime }` | Video pauses |
+| `layershift-parallax:loop` | `{ loopCount }` | Video loops back to start |
+| `layershift-parallax:frame` | `{ currentTime, frameNumber }` | New video frame presented |
+| `layershift-parallax:error` | `{ message }` | Initialization error |
+
+```js
+const el = document.querySelector('layershift-parallax');
+
+el.addEventListener('layershift-parallax:ready', (e) => {
+  console.log(`Video: ${e.detail.videoWidth}x${e.detail.videoHeight}`);
+});
+
+el.addEventListener('layershift-parallax:frame', (e) => {
+  updateTimeline(e.detail.currentTime);
+});
+```
+
+### Frame-Level Sync
+
+The renderer uses `requestVideoFrameCallback` (RVFC) when available to sync depth updates to actual video frame presentation:
+
+- Depth work only runs when a new frame is decoded (~24–30fps)
+- Parallax input stays smooth at display refresh rate (60–120fps)
+- The `layershift-parallax:frame` event fires at true video frame rate
+- Browsers without RVFC fall back to `requestAnimationFrame` automatically
+
+### Performance
+
+Each `<layershift-parallax>` 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.
+
+| Instances | Suitability |
+|-----------|-------------|
+| **1–3** | Smooth on all modern devices including mobile |
+| **4–6** | Great on desktop; mobile may hit browser video decoder limits |
+| **8–12** | Desktop only; consider pausing off-screen instances |
+
+The bottleneck is concurrent video decoders, not GPU or Workers. Most mobile browsers cap hardware-decoded `<video>` streams at 4–8.
+
+#### Per-Instance Resource Footprint (512x512 depth)
+
+| Resource | Cost |
+|----------|------|
+| GPU textures | 2 (VideoTexture + 262 KB depth DataTexture) |
+| Draw calls / frame | 1 |
+| Web Workers | 1 (with sync fallback) |
+| Worker RAM | ~3 MB (processing buffers) |
+| Depth data download | ~13 MB (50 frames at 512x512) |
+| RAF callbacks | 1 (60–120 fps) |
+| RVFC callbacks | 1 (24–30 fps, when supported) |
+
+---
+
+## Controls
+
+- **Space** — Play / pause video
+
+## Testing
+
+```bash
+# Unit tests (Vitest)
+npm test
+
+# E2E tests (Playwright, requires build first)
+npm run build && npm run build:component && npm run test:e2e
+
+# All tests
+npm run build && npm run build:component && npm run test:all
+```
+
+## Roadmap
+
+Future effects under the Layershift umbrella:
+
+- `<layershift-scroll>` — Scroll-driven video playback
+- `<layershift-reveal>` — Depth-based reveal/mask transitions
+- More to come
+
+## License
+
+Business Source License 1.1 — see [LICENSE](./LICENSE) for details.
+
+Change date: 2029-01-01 → Apache License 2.0