layershift 0.2.0 → 0.2.1

package/README.md

@@ -20,10 +20,55 @@ A precomputed depth map drives per-pixel UV displacement with Parallax Occlusion
 ></layershift-parallax>
 ```
 
+### `<layershift-portal>` — Logo Depth Portal
+
+Renders video through an SVG-shaped cutout with depth-aware parallax, emissive interior compositing, geometric chamfer lighting, and dimensional boundary effects. The canvas background is fully transparent, so the portal can be overlaid on any HTML content.
+
+```html
+<script src="https://cdn.layershift.io/layershift.js"></script>
+
+<layershift-portal
+  src="video.mp4"
+  depth-src="depth-data.bin"
+  depth-meta="depth-meta.json"
+  logo-src="logo.svg"
+></layershift-portal>
+```
+
 **[Live demo →](https://layershift.io)**
 
 ---
 
+## Install
+
+### Script Tag (IIFE)
+
+```html
+<script src="https://cdn.layershift.io/layershift.js"></script>
+```
+
+### npm
+
+```bash
+npm install layershift
+```
+
+```js
+import 'layershift';
+// Both <layershift-parallax> and <layershift-portal> are now registered
+```
+
+### TypeScript
+
+Add JSX type support for the custom elements:
+
+```json
+// tsconfig.json
+{ "compilerOptions": { "types": ["layershift/global"] } }
+```
+
+---
+
 ## Prerequisites
 
 The `precompute` script needs **FFmpeg** to read video metadata and extract frames.
@@ -44,7 +89,7 @@ npm install
 npm run precompute
 ```
 
-Generates `public/depth-data.bin` and `public/depth-meta.json` from the video in `public/sample.mp4`.
+Generates `depth-data.bin` and `depth-meta.json` from a video using Depth Anything v2.
 
 ## Development
 
@@ -58,11 +103,11 @@ npm run dev
 # Build the landing page
 npm run build
 
-# Build the standalone Web Component
+# Build the standalone Web Component (IIFE)
 npm run build:component
 
-# Package output (video + depth data + component + demo page)
-npm run package
+# Build the npm package (ESM + IIFE + types)
+npm run build:package
 ```
 
 ---
@@ -84,30 +129,8 @@ npm run package
 | `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 |
@@ -123,21 +146,8 @@ 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.
@@ -148,25 +158,82 @@ Each `<layershift-parallax>` instance creates 1 WebGL renderer, 1 Web Worker, 1
 | **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.
+---
+
+## `<layershift-portal>` Reference
+
+### Required Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `src` | string | Video file URL |
+| `depth-src` | string | Depth binary URL |
+| `depth-meta` | string | Depth metadata URL |
+| `logo-src` | string | SVG file URL for the portal shape |
+
+### Key Optional Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `parallax-x` | number | 0.4 | Horizontal parallax intensity |
+| `parallax-y` | number | 0.8 | Vertical parallax intensity |
+| `parallax-max` | number | 30 | Max parallax in pixels |
+| `chamfer-width` | number | 0.025 | Chamfer geometry width (0 = no chamfer) |
+| `chamfer-color` | string | #262630 | Chamfer tint color |
+| `chamfer-specular` | number | 0.3 | Chamfer specular highlight |
+| `rim-intensity` | number | 0.6 | Rim light intensity (0 = off) |
+| `rim-color` | string | #ffffff | Rim light color |
+| `light-direction` | string | -0.5,0.7,-0.3 | 3D light direction as "x,y,z" |
+| `autoplay` | boolean | true | Auto-play on mount |
+| `loop` | boolean | true | Loop playback |
+| `muted` | boolean | true | Muted (required for autoplay) |
+
+The portal supports 40+ optional attributes for fine-grained control over the interior scene, chamfer geometry, boundary effects, bevel, volumetric edge wall, and depth-of-field. See `docs/portal/portal-overview.md` for the full reference.
 
-#### Per-Instance Resource Footprint (512x512 depth)
+### Transparent Background
 
-| Resource | Cost |
-|----------|------|
-| GPU textures | 2 (video texture + 262 KB depth texture) |
-| 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) |
+The portal canvas is fully transparent outside the logo shape. Overlay it on any background:
+
+```html
+<div style="position: relative; background: #1a1a2e;">
+  <layershift-portal
+    src="video.mp4"
+    depth-src="depth-data.bin"
+    depth-meta="depth-meta.json"
+    logo-src="logo.svg"
+    style="position: absolute; inset: 0;"
+    autoplay loop muted
+  ></layershift-portal>
+</div>
+```
+
+### Events
+
+| Event | Detail | When |
+|-------|--------|------|
+| `layershift-portal:ready` | `{ videoWidth, videoHeight, duration }` | Initialization complete |
+| `layershift-portal:play` | `{ currentTime }` | Video starts playing |
+| `layershift-portal:pause` | `{ currentTime }` | Video pauses |
+| `layershift-portal:loop` | `{ loopCount }` | Video loops back to start |
+| `layershift-portal:frame` | `{ currentTime, frameNumber }` | New video frame presented |
+| `layershift-portal:error` | `{ message }` | Initialization error |
+
+### SVG Requirements
+
+The `logo-src` SVG should use a `viewBox` attribute and contain filled shapes (`<path>`, `<polygon>`, `<rect>`, `<circle>`, `<ellipse>`). Complex SVGs with multiple paths, compound paths, nested groups, and holes (letters A, R, O, etc.) are supported.
 
 ---
 
-## Controls
+## Frame-Level Sync
 
-- **Space** — Play / pause video
+Both effects use `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)
+- Frame events fire at true video frame rate
+- Browsers without RVFC fall back to `requestAnimationFrame` automatically
+
+---
 
 ## Testing
 
@@ -181,14 +248,6 @@ npm run build && npm run build:component && npm run test:e2e
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layershift",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Embeddable video effects as Web Components. Drop-in parallax, depth-aware motion, and more.",
   "type": "module",
   "main": "dist/components/layershift.js",