@stackvibe-studio/three 0.2.0 → 0.3.1

package/README.md

@@ -1,36 +1,81 @@
 # @stackvibe-studio/three
 
-3D visual primitives for hero sections, product cards, and immersive surfaces.
+Product-grade 3D visual primitives, canvas environments, and WebGL components built with Three.js and React Three Fiber.
 
-## Highlights
+Designed for immersive hero sections, interactive landing page surfaces, and futuristic product cards with smooth 60fps animations.
 
-- Glassmorphism-style 3D card wrapper
-- Floating sphere and orb cluster patterns
-- React Three Fiber powered with lightweight presets
-- New in v0.2.0: OrbCluster for layered hero artwork
+[![npm version](https://img.shields.io/npm/v/@stackvibe-studio/three.svg)](https://www.npmjs.com/package/@stackvibe-studio/three)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+## Features
+
+- **WaveCanvas**: WebGL undulating sinusoidal mesh and wave canvas with dynamic light physics.
+- **Glass3DCard**: Glassmorphism-style 3D card wrapper with realistic specular reflection and tilt.
+- **FloatingSphere**: Physics-based floating sphere with ambient lighting and rotation.
+- **OrbCluster**: Multi-layered 3D orb cluster designed for ambient hero backgrounds.
+- **Zero layout shift**: Fully responsive canvas containers with graceful fallback rendering.
+- **Framework agnostic**: Works with Next.js (App Router & Pages Router), Vite, Remix, and Gatsby.
+
+## Installation
 
 ```bash
+pnpm add @stackvibe-studio/three three @react-three/fiber @react-three/drei
+# or
 npm install @stackvibe-studio/three three @react-three/fiber @react-three/drei
 ```
 
-## Example
+## Usage
+
+### WaveCanvas (Hero Backgrounds)
+
+```tsx
+import { WaveCanvas } from '@stackvibe-studio/three';
+
+export function HeroSection() {
+  return (
+    <div className="relative h-[500px] w-full overflow-hidden rounded-2xl bg-zinc-950">
+      <WaveCanvas 
+        wireframe={false} 
+        speed={1.2} 
+        color="#6366f1" 
+        className="absolute inset-0" 
+      />
+      <div className="relative z-10 flex h-full flex-col items-center justify-center text-center p-8">
+        <h1 className="text-4xl font-bold text-white">Next-Gen Interface Canvas</h1>
+        <p className="mt-2 text-zinc-400">Interactive 3D surfaces rendered in real-time WebGL.</p>
+      </div>
+    </div>
+  );
+}
+```
+
+### Glass3DCard & OrbCluster
 
 ```tsx
 import { Glass3DCard, OrbCluster } from '@stackvibe-studio/three';
 
-export function Example() {
+export function FeatureCard() {
   return (
-    <div>
-      <Glass3DCard className="h-80" />
-      <OrbCluster />
+    <div className="relative flex items-center justify-center p-12">
+      <OrbCluster className="absolute inset-0 pointer-events-none opacity-60" />
+      <Glass3DCard className="w-80 h-96 p-6">
+        <h3 className="text-xl font-bold text-white">Pro Access</h3>
+        <p className="text-zinc-400 mt-2">Enterprise-grade WebGL rendering primitives.</p>
+      </Glass3DCard>
     </div>
   );
 }
 ```
 
-## Related packages
+## Components Reference
+
+| Component | Description | Props |
+| :--- | :--- | :--- |
+| `WaveCanvas` | Real-time undulating 3D sine-wave plane | `wireframe?: boolean`, `speed?: number`, `color?: string`, `className?: string` |
+| `Glass3DCard` | 3D glass card with reflective lighting | `children?: ReactNode`, `className?: string` |
+| `FloatingSphere` | Autonomous 3D floating orb with glow | `color?: string`, `wireframe?: boolean`, `className?: string` |
+| `OrbCluster` | Ambient particle cluster with floating orbs | `count?: number`, `className?: string` |
+
+## License
 
-- @stackvibe-studio/ui
-- @stackvibe-studio/motion
+MIT © [StackVibe Studio](https://github.com/StackVibe-Studio/stackvibe-ui)

package/dist/components/wave-canvas.d.ts

@@ -0,0 +1,13 @@
+interface WaveMeshProps {
+    color?: string;
+    wireframe?: boolean;
+    speed?: number;
+    amplitude?: number;
+    roughness?: number;
+    metalness?: number;
+}
+export interface WaveCanvasProps extends WaveMeshProps {
+    className?: string;
+}
+export declare function WaveCanvas({ color, wireframe, speed, amplitude, roughness, metalness, className, }: WaveCanvasProps): import("react").JSX.Element;
+export {};

package/dist/index.cjs

@@ -1,8 +1,10 @@
 "use strict";
 "use client";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -16,6 +18,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -23,7 +33,8 @@ var index_exports = {};
 __export(index_exports, {
   FloatingSphere: () => FloatingSphere,
   Glass3DCard: () => Glass3DCard,
-  OrbCluster: () => OrbCluster
+  OrbCluster: () => OrbCluster,
+  WaveCanvas: () => WaveCanvas
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -131,9 +142,82 @@ function OrbCluster({
     ))
   ] }) });
 }
+
+// src/components/wave-canvas.tsx
+var import_fiber4 = require("@react-three/fiber");
+var import_react = require("react");
+var THREE = __toESM(require("three"), 1);
+var import_jsx_runtime4 = require("react/jsx-runtime");
+function WaveMesh({
+  color = "#8b5cf6",
+  wireframe = false,
+  speed = 1.5,
+  amplitude = 0.25,
+  roughness = 0.3,
+  metalness = 0.5
+}) {
+  const meshRef = (0, import_react.useRef)(null);
+  const { positions } = (0, import_react.useMemo)(() => {
+    const geo = new THREE.PlaneGeometry(6, 6, 32, 32);
+    return { positions: geo.attributes.position };
+  }, []);
+  (0, import_fiber4.useFrame)(({ clock }) => {
+    if (!meshRef.current) return;
+    const t = clock.getElapsedTime() * speed;
+    const geom = meshRef.current.geometry;
+    const pos = geom.attributes.position;
+    for (let i = 0; i < pos.count; i++) {
+      const u = pos.getX(i);
+      const v = pos.getY(i);
+      const z = Math.sin(u * 1.5 + t) * amplitude + Math.cos(v * 1.5 + t) * amplitude;
+      pos.setZ(i, z);
+    }
+    pos.needsUpdate = true;
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("mesh", { ref: meshRef, rotation: [-Math.PI / 3, 0, 0], children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("planeGeometry", { args: [6, 6, 32, 32] }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      "meshStandardMaterial",
+      {
+        color,
+        wireframe,
+        roughness,
+        metalness,
+        side: THREE.DoubleSide
+      }
+    )
+  ] });
+}
+function WaveCanvas({
+  color = "#8b5cf6",
+  wireframe = false,
+  speed = 1.5,
+  amplitude = 0.25,
+  roughness = 0.3,
+  metalness = 0.5,
+  className = ""
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { className: ["h-64 w-full rounded-3xl overflow-hidden bg-slate-950/50", className].join(" "), children: /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_fiber4.Canvas, { camera: { position: [0, -1, 3], fov: 60 }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("ambientLight", { intensity: 0.8 }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("directionalLight", { position: [3, 5, 4], intensity: 1.5 }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("pointLight", { position: [-3, -3, 2], intensity: 0.5, color: "#22d3ee" }),
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+      WaveMesh,
+      {
+        color,
+        wireframe,
+        speed,
+        amplitude,
+        roughness,
+        metalness
+      }
+    )
+  ] }) });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FloatingSphere,
   Glass3DCard,
-  OrbCluster
+  OrbCluster,
+  WaveCanvas
 });

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './components/floating-sphere';
 export * from './components/glass-3d-card';
 export * from './components/orb-cluster';
+export * from './components/wave-canvas';

package/dist/index.js

@@ -104,8 +104,81 @@ function OrbCluster({
     ))
   ] }) });
 }
+
+// src/components/wave-canvas.tsx
+import { Canvas as Canvas4, useFrame } from "@react-three/fiber";
+import { useRef, useMemo } from "react";
+import * as THREE from "three";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function WaveMesh({
+  color = "#8b5cf6",
+  wireframe = false,
+  speed = 1.5,
+  amplitude = 0.25,
+  roughness = 0.3,
+  metalness = 0.5
+}) {
+  const meshRef = useRef(null);
+  const { positions } = useMemo(() => {
+    const geo = new THREE.PlaneGeometry(6, 6, 32, 32);
+    return { positions: geo.attributes.position };
+  }, []);
+  useFrame(({ clock }) => {
+    if (!meshRef.current) return;
+    const t = clock.getElapsedTime() * speed;
+    const geom = meshRef.current.geometry;
+    const pos = geom.attributes.position;
+    for (let i = 0; i < pos.count; i++) {
+      const u = pos.getX(i);
+      const v = pos.getY(i);
+      const z = Math.sin(u * 1.5 + t) * amplitude + Math.cos(v * 1.5 + t) * amplitude;
+      pos.setZ(i, z);
+    }
+    pos.needsUpdate = true;
+  });
+  return /* @__PURE__ */ jsxs4("mesh", { ref: meshRef, rotation: [-Math.PI / 3, 0, 0], children: [
+    /* @__PURE__ */ jsx4("planeGeometry", { args: [6, 6, 32, 32] }),
+    /* @__PURE__ */ jsx4(
+      "meshStandardMaterial",
+      {
+        color,
+        wireframe,
+        roughness,
+        metalness,
+        side: THREE.DoubleSide
+      }
+    )
+  ] });
+}
+function WaveCanvas({
+  color = "#8b5cf6",
+  wireframe = false,
+  speed = 1.5,
+  amplitude = 0.25,
+  roughness = 0.3,
+  metalness = 0.5,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsx4("div", { className: ["h-64 w-full rounded-3xl overflow-hidden bg-slate-950/50", className].join(" "), children: /* @__PURE__ */ jsxs4(Canvas4, { camera: { position: [0, -1, 3], fov: 60 }, children: [
+    /* @__PURE__ */ jsx4("ambientLight", { intensity: 0.8 }),
+    /* @__PURE__ */ jsx4("directionalLight", { position: [3, 5, 4], intensity: 1.5 }),
+    /* @__PURE__ */ jsx4("pointLight", { position: [-3, -3, 2], intensity: 0.5, color: "#22d3ee" }),
+    /* @__PURE__ */ jsx4(
+      WaveMesh,
+      {
+        color,
+        wireframe,
+        speed,
+        amplitude,
+        roughness,
+        metalness
+      }
+    )
+  ] }) });
+}
 export {
   FloatingSphere,
   Glass3DCard,
-  OrbCluster
+  OrbCluster,
+  WaveCanvas
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackvibe-studio/three",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "3D component layer for StackVibe UI.",
   "repository": {
@@ -12,6 +12,24 @@
     "url": "https://github.com/StackVibe-Studio/stackvibe-ui/issues"
   },
   "license": "MIT",
+  "keywords": [
+    "react",
+    "react-19",
+    "three",
+    "threejs",
+    "webgl",
+    "react-three-fiber",
+    "drei",
+    "3d",
+    "canvas",
+    "wave-canvas",
+    "floating-sphere",
+    "glassmorphism",
+    "glass-card",
+    "orb-cluster",
+    "shaders",
+    "stackvibe"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {