@canvas3/nuxt 0.1.32 → 0.1.33

package/README.md

@@ -1,68 +1,280 @@
-<!--
-Get your module up and running quickly.
+# Canvas3 Nuxt Module
 
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: My Module
-- Package name: my-module
-- Description: My new Nuxt module
--->
+A Nuxt module that integrates ThreeJS into your Nuxt app, providing a smooth-scroll engine, WebGL image effects, scroll-triggered animations, and a shader/animation API — all wired together through Vue directives and a global `Canvas3` composable-like utility.
 
-# Canvas3 Nuxt Module
+[✨ Example use cases](https://canvas3.vercel.app/)
 
-Nuxt module for ThreeJS integration and additional features
+## Features
 
-[//]: # (- [✨ &nbsp;Release Notes]&#40;/CHANGELOG.md&#41;)
+- 🎬 **Smooth scroll engine** – Custom lerp-based scroll with speed tracking, fixed-to-parent elements, and mobile breakpoint handling.
+- 🖼 **WebGL image replacement** – Turn any `<img>` into a shader-driven ThreeJS mesh via the `v-canvas3-image` directive.
+- 👀 **Scroll-triggered activation** – Activate/deactivate elements (and their linked meshes) as they enter/leave the viewport with `v-canvas3-scroll-action`.
+- 🎨 **Custom shader support** – Bring your own vertex/fragment shaders per mesh, plus a global post-processing scroll shader pass.
+- ⏱ **Animation scheduler** – Register callbacks that run conditionally on scroll, resize, mouse move, or custom render triggers, avoiding unnecessary renders.
+- 🖱 **Mouse-reactive uniforms** – Automatic `uMouse` / `uMouseMovement` uniforms updated on mouse movement for interactive shaders.
+- 📱 **Responsive & reduced-motion aware** – Built-in `isMobile` / `prefersReducedMotion` / `disabled` options to gracefully degrade.
+- 🧩 **Global utility API** – `Canvas3` import exposes scene, camera, renderer, mesh, and scroll controls anywhere in your app.
+- 🏗 **Layout-based setup** – Ships a ready-to-use `canvas3` Nuxt layout that wraps your page content with the scroll/canvas containers.
 
-[//]: # ( - [🏀 Online playground]&#40;https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue&#41;)
+## Quick Setup
 
-[//]: # ( - [📖 &nbsp;Documentation]&#40;https://example.com&#41;)
+Install the module to your Nuxt application with one command:
 
-## Features
+```bash
+npx nuxi module add canvas3-nuxt
+```
 
-[✨ &nbsp;Example use cases](https://canvas3.vercel.app/)
+That's it! You can now use the Canvas3 module in your Nuxt app ✨
 
-<!-- Highlight some of the features your module provide here -->
+### 1. Use the `canvas3` layout
 
-[//]: # (- ⛰ &nbsp;Foo)
+```vue
+<!-- pages/index.vue -->
+<script setup>
+definePageMeta({ layout: 'canvas3' })
+</script>
+```
 
-[//]: # (- 🚠 &nbsp;Bar)
+### 2. Enable Canvas3 in the layout
 
-[//]: # (- 🌲 &nbsp;Baz)
+The layout exposes `canvas3enabled` and `canvas3options` props. Enable it once your options (shaders, fonts, etc.) are ready:
 
-## Quick Setup
+```vue
+<!-- app.vue or a wrapping component -->
+<template>
+  <NuxtLayout
+    :canvas3enabled="ready"
+    :canvas3options="canvas3Options"
+    @canvas3-ready="onReady"
+  >
+    <NuxtPage />
+  </NuxtLayout>
+</template>
 
-Install the module to your Nuxt application with one command:
+<script setup>
+import { ref } from 'vue'
 
-```bash
-npx nuxi module add canvas3-nuxt
+const ready = ref(false)
+const canvas3Options = {
+  shaders: {
+    default: { vertexShader: defaultVert, fragmentShader: defaultFrag },
+    scroll: { vertexShader: scrollVert, fragmentShader: scrollFrag },
+  },
+  activateMeshOptions: {
+    image: { uAniInImage: { value: 1, duration: 1, ease: 'power2.out' } },
+  },
+  canvasElement: { zIndex: -1 },
+  prefersReducedMotion: false,
+  isMobile: false,
+  disabled: false,
+}
+
+function onReady() {
+  ready.value = true
+}
+
+ready.value = true
+</script>
 ```
-That's it! You can now use Canvas3 module in your Nuxt app ✨
+
+## Directives
+
+### `v-canvas3-image`
+
+Converts an `<img>` element into a ThreeJS mesh rendered in sync with the DOM element's position, size, and scroll offset. The original image is hidden (opacity set to 0) and replaced visually by the WebGL mesh.
+
+**Requirements:** must be applied to an `<img>` tag.
+
+**Binding value** (`Canvas3ImageBinding`):
+
+| Option | Type | Description |
+|---|---|---|
+| `shaderName` | `string` | Key of a custom shader registered in `canvas3Options.shaders`. Falls back to `shaders.default`. |
+| `uniforms` | `MeshMaterialUniform` | Extra/overriding shader uniforms merged into the material on creation and reactively on update. |
+| `activateMeshUniforms` | `MeshMaterialUniform` | Uniforms animated (0 → 1) when the mesh's linked scroll-action element becomes active/inactive. |
+
+```vue
+<template>
+  <img
+    src="/images/hero.jpg"
+    alt="Hero"
+    v-canvas3-image="{
+      shaderName: 'wave',
+      uniforms: {
+        vectorVNoise: { value: [2, 2], duration: 0 },
+      },
+      activateMeshUniforms: {
+        uAniInImage: { value: 1, duration: 1.2, ease: 'power2.out' },
+      },
+    }"
+  >
+</template>
+```
+
+Behavior notes:
+- Waits for the image to load (`complete`/`load` event) and for the canvas to be initiated before creating the mesh.
+- Automatically re-creates the mesh if `src` changes.
+- Cleans up (disposes geometry/material/texture, removes from scene) on unmount.
+- Respects `canvas3options.disabled`, adding a `.reduced-motion` class instead of creating a mesh.
+
+### `v-canvas3-scroll-action`
+
+Marks an element to be tracked by the scroll engine. When the element enters/exits the configured viewport range, it toggles an `active` class, fires callbacks, and (optionally) activates any WebGL image meshes nested inside it (matched via `data-mesh-id`, set automatically by `v-canvas3-image`).
+
+**Binding value** (`scrollActionBindOptionType`):
+
+| Option | Type | Description |
+|---|---|---|
+| `activateOnce` | `boolean` | Once activated, the element is never deactivated again. |
+| `trackOnly` | `boolean` | Skip class toggling and mesh activation; only fires callbacks/tracking. |
+| `activeRange` | `number` | Fraction of viewport height used as the "active zone" (default `1`, i.e. full viewport). |
+| `activeRangeMargin` | `number` | Extra pixel margin added to the active range for speed-tracking calculations. |
+| `scrollSpeed` | `{ value: number }` | Applies a parallax translate based on scroll position, proportional to `value`. |
+| `scrollSpeedSetTo` | `{ value: number, duration: number }` | Animates `scrollSpeed.value` to a new target over `duration` seconds via GSAP. |
+| `fixToParent` | `{ containerId: string, fixPosition: number, margin: number }` | Pins the element's first child inside a container (by `id`) at a given viewport position while the container is in view. |
+| `activateCallback` | `(item) => void` | Called when the element becomes active. |
+| `deactivateCallback` | `(item) => void` | Called when the element becomes inactive (unless `activateOnce`). |
+| `onScrollCallback` | `(item, scrollSpeed, currentPosition) => void` | Called continuously while the element is in view and the page is scrolling. |
+
+```vue
+<template>
+  <section
+    v-canvas3-scroll-action="{
+      activeRange: 0.8,
+      activateCallback: onSectionActive,
+      deactivateCallback: onSectionInactive,
+    }"
+  >
+    <img src="/images/panel.jpg" alt="Panel" v-canvas3-image="{}">
+  </section>
+</template>
+
+<script setup>
+function onSectionActive(item) {
+  console.log('Section entered view', item.elNode)
+}
+function onSectionInactive(item) {
+  console.log('Section left view', item.elNode)
+}
+</script>
+```
+
+**Parallax example:**
+
+```vue
+<div v-canvas3-scroll-action="{ scrollSpeed: { value: 0.3 } }">
+  <div>Moves at 0.3x scroll speed</div>
+</div>
+```
+
+**Pin-to-parent example:**
+
+```vue
+<div id="stickyContainer" style="height: 200vh;">
+  <div
+    v-canvas3-scroll-action="{
+      fixToParent: { containerId: 'stickyContainer', fixPosition: 0.5, margin: 0 },
+    }"
+  >
+    <div>Pinned child, centered at 50% viewport while parent is in view</div>
+  </div>
+</div>
+```
+
+## Global `Canvas3` Utility
+
+The module auto-imports a `Canvas3` utility (via Nuxt's `addImports`) that exposes scene/camera/renderer access and imperative controls, independent of the directives.
+
+| Method | Description |
+|---|---|
+| `addMeshToScene(mesh)` | Adds a raw ThreeJS `Mesh` directly to the Canvas3 scene. |
+| `getMeshFromSceneByName(name)` | Retrieves a scene object by its `name`. |
+| `addImageAsMesh(imgEl, shaderName, meshId, uniforms, activateMeshUniforms)` | Lower-level API used internally by `v-canvas3-image`; can be called manually. |
+| `removeMesh(id)` | Disposes and removes a mesh (and its material/texture) by id. |
+| `getShaderMaterial(mesh)` | Type-casts and returns a mesh's `ShaderMaterial`. |
+| `addAnimationToRender(name, setup)` | Registers a named animation callback (see below). |
+| `removeAnimationFromRender(name)` | Unregisters a named animation callback. |
+| `setAnimationsToRender(state)` | Globally toggles whether `onAnimationsRender` animations run. |
+| `setAnimationToRender(name, state, id)` | Adds/removes an `animationId` driving a specific animation's `render` state. |
+| `setRenderDisabled(state)` | Pauses/resumes the entire render loop. |
+| `setMeshPositionsUpdate(state)` | Forces continuous recalculation of image mesh positions/sizes (e.g. during layout shifts). |
+| `resizeOnChange()` | Recalculates canvas size, camera, and mesh positions — call on custom resize triggers. |
+| `scrollTo(position, delay?)` | Smoothly animates scroll to a pixel position. |
+| `scrollToTop(delay?)` | Smoothly animates scroll to the top. |
+| `scrollToElBySelector(selector, delay?, margin?)` | Scrolls to an element matched by a CSS selector. |
+| `getScrollPosition()` | Returns the current rendered scroll position. |
+| `getScrollSpeed()` | Returns the current normalized scroll speed (0–1). |
+| `getCamera()` | Returns the active `THREE.PerspectiveCamera`. |
+| `getRenderer()` | Returns the active `THREE.WebGLRenderer`. |
+| `getScene()` | Returns the active `THREE.Scene`. |
+
+**Animation callback example:**
+
+```ts
+import { Canvas3 } from '#imports'
+
+Canvas3.addAnimationToRender('rotateLogo', {
+  onScroll: false,
+  onResize: false,
+  onMouseMove: true,
+  onAnimationsRender: false,
+  render: false,
+  animationCallback: () => {
+    const mesh = Canvas3.getMeshFromSceneByName('logoMesh')
+    if (mesh) mesh.rotation.y += 0.01
+  },
+})
+
+// later, to stop it:
+Canvas3.removeAnimationFromRender('rotateLogo')
+```
+
+**Manual scroll control example:**
+
+```ts
+import { Canvas3 } from '#imports'
+
+function goToSection() {
+  Canvas3.scrollToElBySelector('#contact', 0, -80)
+}
+```
+
+## Options Reference (`Canvas3OptionsType`)
+
+| Option | Type | Description |
+|---|---|---|
+| `shaders` | `{ default: Shader, scroll?: Shader, [name]: Shader }` | Registry of vertex/fragment shader pairs. `default` is required; `scroll` enables the post-processing scroll-speed effect pass. |
+| `activateMeshOptions.image` | `Record<string, MeshAnimation>` | Default in/out uniform animations applied to image meshes on activation (e.g. `uAniInImage`). |
+| `canvasElement.zIndex` | `number` | z-index applied to the fixed WebGL canvas container. |
+| `prefersReducedMotion` | `boolean` | Flag to adapt behavior for reduced-motion users. |
+| `isMobile` | `boolean` | Flag to adapt behavior for mobile devices. |
+| `disabled` | `boolean` | Globally disables mesh creation; `v-canvas3-image` falls back to a `.reduced-motion` class. |
 
 ## Contribution
 
 <details>
   <summary>Local development</summary>
-  
+
   ```bash
   # Install dependencies
   npm install
-  
+
   # Generate type stubs
   npm run dev:prepare
-  
+
   # Develop with the playground
   npm run dev
-  
+
   # Build the playground
   npm run dev:build
-  
+
   # Run ESLint
   npm run lint
-  
+
   # Run Vitest
   npm run test
   npm run test:watch
-  
+
   # Release new version
   npm run release
   ```

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "canvas-nuxt-layout",
   "configKey": "canvas3Layout",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.0"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, addTemplate, addLayout, addComponent, addPlugin, addTypeTemplate, addImports } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addTemplate, addLayout, addPlugin, addTypeTemplate, addImports } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -13,11 +13,6 @@ const module$1 = defineNuxtModule({
       write: true
     });
     addLayout(canvas3Layout, "canvas3");
-    addComponent({
-      name: "Canvas3Image",
-      filePath: resolve("./runtime/components/canvas3-image.vue"),
-      global: true
-    });
     addPlugin(resolve("./runtime/plugins/directives"));
     addTypeTemplate({
       filename: "types/canvas3-directives.d.ts",

package/dist/runtime/types/types.d.ts

@@ -83,9 +83,7 @@ export type scrollActionBindOptionType = {
     deactivateCallback?: (item: ScrollActionType) => void;
     onScrollCallback?: (item: ScrollActionType, scrollSpeed: number, currentPosition: number) => void;
     activeRangeMargin?: number;
-    activeRangeOrigin?: number;
     activeRange?: number;
-    bidirectionalActivation?: boolean;
 };
 export type ScrollActionBinding = {
     elNode: HTMLElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canvas3/nuxt",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "publishConfig": {
     "access": "public"
   },

package/dist/runtime/components/canvas3-image.vue

@@ -1,76 +0,0 @@
-<template>
-  <div class="webgl-img-wrapper">
-    <img
-      ref="image"
-      class="webgl-img"
-      :class="{ 'reduced-motion': reducedMotion ?? null }"
-      :alt="props.options.alt"
-      :src="props.options.src"
-      :loading="props.options.loadStrategy"
-      @load="addImageToCanvas"
-    >
-  </div>
-</template>
-
-<script setup>
-import { ref, computed, watch, onMounted, nextTick, onBeforeUnmount } from "vue";
-import { Canvas3 } from "#canvas3-nuxt/utils/canvas3/canvas3";
-const props = defineProps({
-  options: { type: Object, required: false, default: () => ({
-    alt: "",
-    src: "",
-    loadStrategy: "lazy",
-    shaderName: void 0,
-    uniforms: {},
-    activateMeshUniforms: {}
-  }) }
-});
-const reducedMotion = computed(() => Canvas3.options?.disabled ?? null);
-const image = ref();
-const generatedMeshId = "image_" + crypto.randomUUID();
-const imgAddedToCanvas = ref(false);
-const imgIsAdding = ref(false);
-const addImageToCanvas = async () => {
-  if (imgAddedToCanvas.value || imgIsAdding.value) return;
-  imgIsAdding.value = true;
-  try {
-    await nextTick();
-    if (!image.value || Canvas3.canvasInitiated.value === false || Canvas3.options?.disabled || imgAddedToCanvas.value) return;
-    if (image.value.naturalWidth === 0) return;
-    image.value.dataset.meshId = generatedMeshId;
-    await Canvas3.addImageAsMesh(
-      image.value,
-      props.options.shaderName ?? null,
-      generatedMeshId,
-      props.options.uniforms ?? {},
-      props.options.activateMeshUniforms ?? {}
-    );
-    imgAddedToCanvas.value = true;
-  } finally {
-    imgIsAdding.value = false;
-  }
-};
-watch(() => Canvas3.canvasInitiated.value, (ready) => {
-  if (ready) addImageToCanvas();
-});
-watch(() => props.options.uniforms, (u) => {
-  if (u)
-    Canvas3.meshUniformsUpdate(generatedMeshId, u);
-}, { deep: true });
-watch(() => props.options.src, () => {
-  imgAddedToCanvas.value = false;
-  nextTick(() => {
-    if (image.value?.complete) addImageToCanvas();
-  });
-});
-onMounted(() => {
-  if (image.value?.complete) addImageToCanvas();
-});
-onBeforeUnmount(() => {
-  Canvas3.removeMesh(generatedMeshId);
-});
-</script>
-
-<style scoped>
-.webgl-img{max-height:100%;max-width:100%;opacity:0}.webgl-img.reduced-motion{height:100%;-o-object-fit:cover;object-fit:cover;opacity:1;width:100%}
-</style>

package/dist/runtime/components/canvas3-image.vue.d.ts

@@ -1,8 +0,0 @@
-import type { Canvas3ImageBindType } from '#canvas3-nuxt/types/types';
-type __VLS_Props = {
-    options?: Canvas3ImageBindType;
-};
-declare const _default: import("vue").DefineComponent<__VLS_Props, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    options: Canvas3ImageBindType;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-export default _default;

package/dist/runtime/components/canvas3-text.vue

@@ -1,95 +0,0 @@
-<template>
-  <span
-    ref="htmlEl"
-    class="text-wrapper"
-    :class="{ 'reduced-motion': reducedMotion }"
-  >
-    <slot />
-  </span>
-</template>
-
-<script setup>
-import { ref, watch, onMounted, onBeforeUnmount, defineProps, computed } from "vue";
-import { Canvas3 } from "#canvas3-nuxt/utils/canvas3/canvas3";
-const props = defineProps({
-  options: {
-    type: {
-      shaderName: {
-        type: String,
-        default: null
-      },
-      theme: {
-        type: String,
-        default: "dark"
-      },
-      uniforms: {
-        type: Object,
-        default: () => {
-        }
-      },
-      activateMeshUniforms: {
-        type: Object,
-        default: () => {
-        }
-      }
-    },
-    default: () => ({
-      uniforms: {},
-      activateMeshUniforms: {}
-    })
-  }
-});
-const reducedMotion = computed(() => {
-  return Canvas3.options?.disabled ?? null;
-});
-const htmlEl = ref("htmlEl");
-const meshId = "text" + crypto.randomUUID();
-const getTrimmedText = () => {
-  let innerHTML = htmlEl.value.innerHTML;
-  if (innerHTML.includes("<!--]-->")) {
-    const start = innerHTML.indexOf("<!--[-->") + 8;
-    const end = innerHTML.indexOf("<!--]-->");
-    innerHTML = innerHTML.slice(start, end);
-  }
-  return innerHTML;
-};
-watch(
-  () => props.options.uniforms,
-  (uniforms) => {
-    if (Canvas3.options?.disabled)
-      return;
-    setTimeout(() => {
-      Canvas3.meshUniformsUpdate(meshId, uniforms);
-    }, 0);
-  },
-  { deep: true }
-);
-onMounted(() => {
-  htmlEl.value.dataset.meshId = meshId;
-});
-onBeforeUnmount(() => {
-  Canvas3.removeMesh(meshId);
-});
-watch(
-  () => Canvas3.canvasInitiated.value,
-  (newVal) => {
-    if (Canvas3.options?.disabled || !newVal)
-      return;
-    setTimeout(() => {
-      Canvas3.addTextAsMSDF(
-        props.options.shaderName,
-        meshId,
-        htmlEl.value,
-        getTrimmedText(),
-        props.options.theme,
-        props.options.uniforms,
-        props.options.activateMeshUniforms
-      );
-    }, 0);
-  }
-);
-</script>
-
-<style scoped>
-.text-wrapper{display:inline-block;opacity:0}.text-wrapper.reduced-motion{opacity:1}
-</style>

package/dist/runtime/components/canvas3-text.vue.d.ts

@@ -1,12 +0,0 @@
-declare var __VLS_1: {};
-type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_1) => any;
-};
-declare const __VLS_component: import("vue").DefineSetupFnComponent<Record<string, any>, {}, {}, Record<string, any> & {}, import("vue").PublicProps>;
-declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
-export default _default;
-type __VLS_WithSlots<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};