@3driseai/3drise-viewer 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,225 @@
+# @3driseai/3drise-viewer
+
+React components for embedding [3dRise](https://3drise.ai) scenes in your app.
+
+You build in the **3dRise studio** — create objects, apply materials, set up animations, effects and
+interactions — then render the result in React with one component. Nothing about the scene is configured
+in code: geometry, materials, lighting, animations and interactions all come from what you published.
+
+There are two components, depending on how much you want to embed:
+
+| Component          | Embeds                                                                  |
+| ------------------ | ----------------------------------------------------------------------- |
+| `<ProjectLoader />` | A whole project — scene, camera, lights, environment, animations, cursors. Renders its own canvas. |
+| `<ObjectNodeApi />` | A single object (and its children) from the studio, dropped into a canvas you control. |
+
+---
+
+## Installation
+
+```bash
+npm install @3driseai/3drise-viewer
+```
+
+The package ships as **ESM only** with bundled TypeScript declarations.
+
+### Peer dependencies
+
+| Peer dependency       | Version         |
+| --------------------- | --------------- |
+| `react`               | `^18` or `^19`  |
+| `three`               | `^0.170`        |
+| `@react-three/fiber`  | `^9`            |
+| `@react-three/drei`   | `^10`           |
+| `@react-three/rapier` | `^2`            |
+| `@gsap/react`         | `^2.1.2`        |
+
+npm 7+ and pnpm 8+ install these for you. On Yarn — classic or Berry — you'll need to add them yourself.
+
+> **`three` must resolve to a single copy.** Two versions of three.js in one app is the classic React
+> Three Fiber failure — objects silently refuse to render, `instanceof` checks fail. If your app pins a
+> different `three` than the `^0.170` declared here, dedupe it (`npm ls three` to check, `overrides` /
+> `resolutions` to force one version) rather than letting both install.
+
+---
+
+## Embed a whole project
+
+`ProjectLoader` fetches a published project by id, renders its own `<Canvas>`, and shows a loading
+indicator until the scene is ready. This is the whole integration:
+
+```tsx
+import { ProjectLoader } from '@3driseai/3drise-viewer';
+
+export default function ProjectPage({ projectId }: { projectId: string }) {
+  return (
+    <div style={{ height: '100svh', position: 'relative' }}>
+      <ProjectLoader projectId={projectId} />
+    </div>
+  );
+}
+```
+
+`ProjectLoader` renders a `<Canvas>` internally, so it needs a sized parent — give the wrapper an
+explicit height (`100svh`, `100%` of a sized container, a fixed pixel value) or nothing will be visible.
+
+### Reacting to the scene
+
+Every callback is optional:
+
+```tsx
+import { ProjectLoader } from '@3driseai/3drise-viewer';
+import type { CreatedObjectSettings } from '@3driseai/3drise-core';
+import type { Object3D } from 'three';
+
+<ProjectLoader
+  projectId={projectId}
+  loadingIndicator={<MySpinner />}
+  onSceneInitialized={() => setReady(true)}
+  onObjectClick={(object: CreatedObjectSettings, ref: Object3D) => {
+    openInspector(object.meshSettings.name, ref);
+  }}
+  onObjectHover={(object, ref) => setHovered(object.id)}
+/>;
+```
+
+### `<ProjectLoader />` props
+
+| Prop                 | Type                                                                        | Description                                                                     |
+| -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `projectId`          | `string` **(required)**                                                     | Id of the published 3dRise project to load.                                     |
+| `loadingIndicator`   | `React.ReactNode`                                                           | Replaces the built-in full-screen loader shown while the project is fetched.    |
+| `onSceneInitialized` | `() => void`                                                                | Fires once the scene has mounted.                                               |
+| `onObjectClick`      | `(object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void` | A scene object was clicked.                                          |
+| `onObjectHover`      | `(object: CreatedObjectSettings, ref: Object3D) => void`                    | Pointer entered a scene object.                                                 |
+| `onElementClick`     | `(element: HtmlElement) => void`                                            | A 2D UI element in the project was clicked.                                     |
+| `onElementHover`     | `(element: HtmlElement \| null) => void`                                    | Pointer entered/left a 2D UI element.                                           |
+| `onObjectReady`      | `(object, ref: Object3D) => void`                                           | Every object in the scene reports its `Object3D` here — see below.              |
+| `onObjectDispose`    | `(object, ref: Object3D) => void`                                           | The matching teardown event for `onObjectReady`.                                |
+
+---
+
+## Embed a single object
+
+Sometimes you don't want a whole scene — you want one thing you built in the studio, placed in a canvas
+your app already owns.
+
+Create the object in the 3dRise studio, give it its material, animations, effects and click
+interactions, publish it, and copy its object id. `ObjectNodeApi` fetches that object's tree and renders
+it — with everything you configured intact:
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import { OrbitControls } from '@react-three/drei';
+import { ObjectNodeApi } from '@3driseai/3drise-viewer';
+import type { CameraState } from '@3driseai/3drise-core';
+
+const cameraSettings: CameraState = {
+  position: [0, 2, 8],
+  orientation: [0, 0, 0, 1],
+  fov: 50,
+  near: 0.1,
+  far: 1000,
+  animations: [],
+  mouseMove: { enabled: false, properties: [] },
+  controls: { enabled: true, target: [0, 0, 0] },
+};
+
+export function Hero({ objectId }: { objectId: string }) {
+  return (
+    <Canvas camera={{ position: [0, 2, 8], fov: 50 }} style={{ height: '60vh' }}>
+      <ambientLight intensity={0.5} />
+      <directionalLight position={[5, 10, 5]} intensity={1.5} />
+
+      <ObjectNodeApi objectId={objectId} cameraSettings={cameraSettings} />
+
+      <OrbitControls />
+    </Canvas>
+  );
+}
+```
+
+Because you own the canvas here, you also own everything around the object — **camera, lighting,
+controls and background are yours to provide**. `ObjectNodeApi` contributes only the object itself, so
+an object with no emissive material in an unlit canvas will render black. It renders `null` until the
+fetch resolves, so it's safe to mount immediately.
+
+Groups come through whole: if the object has children in the studio, they're rendered as a tree with
+their own materials and animations.
+
+### `<ObjectNodeApi />` props
+
+| Prop                | Type                                                                                    | Description                                                              |
+| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `objectId`          | `string` **(required)**                                                                 | Id of the published scene object to load.                                |
+| `cameraSettings`    | `CameraState` **(required)**                                                            | The camera the object should assume. Currently only `fov` is read, and only by particle objects — but the full object is required. |
+| `handleObjectClick` | `(object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void` | The object was clicked. Note the name differs from `ProjectLoader`'s `onObjectClick`. |
+| `onObjectReady`     | `(object, ref: Object3D) => void`                                                       | The object reports its `Object3D` here — see below.                      |
+| `onObjectDispose`   | `(object, ref: Object3D) => void`                                                       | The matching teardown event.                                             |
+
+---
+
+## Getting at the three.js objects
+
+Both components implement the same two props, so you can build a live registry of what's in the scene
+without reaching into refs yourself:
+
+```ts
+type OnObjectReady   = (object: ObjectReadySource, ref: Object3D) => void;
+type OnObjectDispose = (object: ObjectReadySource, ref: Object3D) => void;
+```
+
+- **`object`** is the settings the object was built with in the studio. It's a union: scene objects give
+  you a `CreatedObjectSettings` (with its studio `id` and `meshSettings`), while effects and cursors give
+  you their own config — narrow it before reading fields. Never `null`.
+- **`ref`** is the root `Object3D` that just mounted.
+- Every `onObjectReady` is eventually paired with an `onObjectDispose` for the same ref, on unmount or
+  when the component swaps its root — so a `Map` built from these events stays accurate.
+
+```tsx
+const objects = useRef(new Map<string, Object3D>());
+
+<ProjectLoader
+  projectId={projectId}
+  onObjectReady={(object, ref) => objects.current.set(ref.uuid, ref)}
+  onObjectDispose={(object, ref) => objects.current.delete(ref.uuid)}
+/>;
+```
+
+To key by the studio id instead, narrow first — `if ('meshSettings' in object)` tells you it's a
+`CreatedObjectSettings`.
+
+From there it's plain three.js — animate it, raycast against it, attach it to your own logic.
+
+---
+
+## TypeScript
+
+Types ship with the package:
+
+```ts
+import type {
+  ObjectReadyProps,
+  ObjectReadySource,
+  OnObjectReady,
+  OnObjectDispose,
+} from '@3driseai/3drise-viewer';
+```
+
+Scene and object types come from the core package, which installs alongside this one:
+
+```ts
+import type { CameraState, CreatedObjectSettings } from '@3driseai/3drise-core';
+```
+
+---
+
+## Notes
+
+- **ESM only.** There is no CommonJS build. In Next.js or another SSR framework, render the viewer
+  client-side (`'use client'`, or a dynamic import with `ssr: false`) — it touches `window` and WebGL.
+- **One entry point.** Import everything from `@3driseai/3drise-viewer`; there are no deep subpath imports.
+
+## Links
+
+- [3dRise](https://3drise.ai)

package/dist/components/AdvancedGrid.d.ts

@@ -0,0 +1,16 @@
+import type { ObjectReadyProps } from '../types/objectReady';
+import type { ThreeElements } from '@react-three/fiber';
+import type { MyGridConfig } from '@3driseai/3drise-core';
+export interface AdvancedGridProps extends ObjectReadyProps {
+    config?: MyGridConfig;
+    groupProps?: ThreeElements['group'];
+}
+/**
+ * MyGridConfig — the single source of truth for a grid instance.
+ * Colors are hex strings so they round-trip cleanly through the controller
+ * and any preset/serialization layer.
+ */
+export declare const defaultMyGridConfig: MyGridConfig;
+export declare function AdvancedGrid({ config, groupProps, onObjectReady, onObjectDispose }: AdvancedGridProps): import("react").JSX.Element;
+export default AdvancedGrid;
+//# sourceMappingURL=AdvancedGrid.d.ts.map

package/dist/components/AdvancedGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdvancedGrid.d.ts","sourceRoot":"","sources":["../../src/components/AdvancedGrid.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACvD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACvC;AAKD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAyBjC,CAAC;AAEF,wBAAgB,YAAY,CAAC,EAAE,MAA4B,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,iBAAiB,+BAiE3H;AAED,eAAe,YAAY,CAAC"}

package/dist/components/AdvancedGrid.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useObjectReady } from '../hooks/useObjectReady.js';
+import { useGridSurface } from '../hooks/useGridSurface.js';
+import { useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { MyGridMaterial } from '@3driseai/3drise-core';
+// Side-effect import registers <myGridMaterial> via extend() in MyGridMaterial.ts.
+void MyGridMaterial;
+/**
+ * MyGridConfig — the single source of truth for a grid instance.
+ * Colors are hex strings so they round-trip cleanly through the controller
+ * and any preset/serialization layer.
+ */
+export const defaultMyGridConfig = {
+    cellSize: 1,
+    size: 50,
+    segments: undefined,
+    flat: true,
+    lineMode: 2, // flow
+    cellMode: 2, // twinkle
+    lineWidth: 1,
+    sectionSize: 5,
+    sectionWidth: 1.6,
+    animSpeed: 1,
+    animScale: 0.5,
+    animIntensity: 1,
+    fadeDistance: undefined,
+    fadeStrength: 0.65,
+    displace: 0,
+    lineColor: '#477fb8',
+    sectionColor: '#80c7ff',
+    cellColor: '#1a5999',
+    glowColor: '#339eff',
+    bgColor: '#05080d',
+    bgOpacity: 0,
+    followMouse: false,
+    reveal: 1,
+    revealDuration: 0,
+};
+export function AdvancedGrid({ config = defaultMyGridConfig, groupProps, onObjectReady, onObjectDispose }) {
+    const matRef = useRef(null);
+    const rootRef = useRef(null);
+    const meshRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const { cellSize, size, segments, flat, lineMode, cellMode, lineWidth, sectionSize, sectionWidth, animSpeed, animScale, animIntensity, fadeDistance, fadeStrength, displace, lineColor, sectionColor, cellColor, glowColor, bgColor, bgOpacity, followMouse, reveal, revealDuration, } = config;
+    const segs = segments ?? (displace > 0 ? Math.max(64, Math.ceil(size / cellSize) * 2) : 1);
+    const fade = fadeDistance ?? size * 0.5;
+    // memoize Color objects so we only re-allocate when the hex actually changes
+    const colors = useMemo(() => ({
+        line: new THREE.Color(lineColor),
+        section: new THREE.Color(sectionColor),
+        cell: new THREE.Color(cellColor),
+        glow: new THREE.Color(glowColor),
+        bg: new THREE.Color(bgColor),
+    }), [lineColor, sectionColor, cellColor, glowColor, bgColor]);
+    // Shared with every other shader-plane grid. This also fixes the pointer
+    // projection: it used to assume the XZ plane, so `followMouse` picked
+    // against the wrong plane whenever `flat` was false or a parent transform
+    // had rotated the grid.
+    useGridSurface(matRef, meshRef, { followMouse, reveal, revealDuration });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("myGridMaterial", { ref: matRef, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, u_cellSize: cellSize, u_lineWidth: lineWidth, u_sectionSize: sectionSize, u_sectionWidth: sectionWidth, u_lineMode: lineMode, u_cellMode: cellMode, u_animSpeed: animSpeed, u_animScale: animScale, u_animIntensity: animIntensity, u_fadeDistance: fade, u_fadeStrength: fadeStrength, u_displace: displace, u_lineColor: colors.line, u_sectionColor: colors.section, u_cellColor: colors.cell, u_glowColor: colors.glow, u_bgColor: colors.bg, u_bgOpacity: bgOpacity }, MyGridMaterial.key)] }) }));
+}
+export default AdvancedGrid;

package/dist/components/AnimatedObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimatedObject.d.ts","sourceRoot":"","sources":["../../src/components/AnimatedObject.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACtG,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,aAAa,EAAE,qBAAqB,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IACjH,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACvD,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACvD,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAGD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA+DvD,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"AnimatedObject.d.ts","sourceRoot":"","sources":["../../src/components/AnimatedObject.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACtG,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,aAAa,EAAE,qBAAqB,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IACjH,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACvD,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IACvD,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAGD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAiEvD,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/dist/components/AnimatedObject.js

@@ -32,10 +32,13 @@ visible = true, children, parentRef, handleObjectClick, onPointerEnter, onPointe
         scale: targetScale ? [...targetScale] : [...scale],
         rotation: targetRotation ? [...targetRotation] : [...rotation],
     });
+    // Pass the ref itself, not `groupRef.current`: the animation hooks read
+    // `.current` inside useFrame, so the group resolves the moment React
+    // attaches it — no scene lookup and no extra render needed.
     useObjectAnimation(createdObject, animateMaterial, {
         enabled: createdObject.type !== 'gallery', // 
         hovered,
-    });
+    }, groupRef);
     const { startPathAnimation, updatePathAnimation, isAnimating: isPathAnimating } = usePathAnimation();
     const syncTransform = useCallback(() => {
         const obj = groupRef.current;
@@ -60,14 +63,13 @@ visible = true, children, parentRef, handleObjectClick, onPointerEnter, onPointe
             handleObjectClick(createdObject, groupRef.current, e);
         }
     };
-    // console.log("AnimatedObject render", { name: createdObject.meshSettings.name, id: createdObject.id, hovered, hasHoverFunctionalities })
     if (createdObject.type === 'particles' || createdObject.type === 'gallery' || (!hasHoverFunctionalities && !hasMouseInteraction)) {
         return _jsx(_Fragment, { children: _jsxs("group", { ref: groupRef, position: position, scale: scale, rotation: rotation, visible: visible, onClick: onClick, 
                 // onPointerEnter={onPointerEnter}
                 // onPointerLeave={onPointerLeave}
-                name: createdObject.meshSettings.name, userData: { id: createdObject.id }, children: [children, _jsx(EffectsGroup, { createdObject: createdObject, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) });
+                name: createdObject.meshSettings.name, userData: { id: createdObject.id }, children: [children, _jsx(EffectsGroup, { createdObject: createdObject, objectRef: groupRef, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) });
     }
-    return (_jsx(_Fragment, { children: _jsxs("group", { ref: groupRef, position: position, scale: scale, rotation: rotation, visible: visible, onClick: onClick, onPointerEnter: onPointerEnter, onPointerLeave: onPointerLeave, name: createdObject.meshSettings.name, userData: { id: createdObject.id }, children: [children, _jsx(EffectsGroup, { createdObject: createdObject, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) }));
+    return (_jsx(_Fragment, { children: _jsxs("group", { ref: groupRef, position: position, scale: scale, rotation: rotation, visible: visible, onClick: onClick, onPointerEnter: onPointerEnter, onPointerLeave: onPointerLeave, name: createdObject.meshSettings.name, userData: { id: createdObject.id }, children: [children, _jsx(EffectsGroup, { createdObject: createdObject, objectRef: groupRef, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) }));
 });
 AnimatedObject.displayName = 'AnimatedObject';
 export default AnimatedObject;

package/dist/components/CameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA8J5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAwJ5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}

package/dist/components/CameraController.js

@@ -55,7 +55,6 @@ export const CameraController = ({ enableAutoAnimation = true, animationDuration
             else {
                 cam.rotation.set(orientation[0], orientation[1], orientation[2]);
             }
-            console.log("CameraController: Synced position/orientation", position, orientation);
         }
     }, [position, orientation]);
     // Sync controls config changes imperatively via ref (after initial mount)
@@ -104,26 +103,22 @@ export const CameraController = ({ enableAutoAnimation = true, animationDuration
     // Handle animation events (step-based animations)
     useAnimationEvents({
         onStepStart: (event) => {
-            // console.log('Camera controller - Step started:', event.step);
             if (event.step?.transitions) {
                 const stepDuration = event.step.duration || 1;
                 event.step.transitions.forEach((transition) => {
                     const { state, properties, pathId } = transition;
                     if (state === 'camera') {
-                        console.log('Camera transition detected. Starting animation to new camera state:', properties);
                         isInAnimatedTransition.current = true;
                         if (pathId) {
                             const offset = camera
                                 ? [camera.position.x, camera.position.y, camera.position.z]
                                 : [0, 0, 0];
-                            console.log(`Starting path animation with ID ${pathId} and offset`, offset);
                             startPathAnimation(pathId, stepDuration, {
                                 offset,
                                 applyRotation: false
                             });
                             transformAnimationProgress.current = 0;
                         }
-                        // console.log("Animating camera to:", targetSettings, "over duration:", stepDuration);
                         const startSettings = properties.from ?
                             {
                                 position: properties.from.position,
@@ -133,7 +128,6 @@ export const CameraController = ({ enableAutoAnimation = true, animationDuration
                             // orientation: camera.rotation,
                         };
                         const targetSettings = properties.to;
-                        // console.log("Starting camera animation from:", startSettings);
                         // startSettings.position && camera.position.set(startSettings.position[0], startSettings.position[1], startSettings.position[2]);
                         // camera.rotation.set(startSettings.orientation[0], startSettings.orientation[1], startSettings.orientation[2]);
                         animateCamera(targetSettings, stepDuration, event.step?.ease, properties.to.target)

package/dist/components/CircuitGrid.d.ts

@@ -0,0 +1,22 @@
+import type { ThreeElements } from '@react-three/fiber';
+import type { ObjectReadyProps } from '../types/objectReady';
+import type { CircuitGridConfig } from '../types/gridConfigs';
+export interface CircuitGridProps extends ObjectReadyProps {
+    config?: CircuitGridConfig;
+    groupProps?: ThreeElements['group'];
+}
+/** CircuitGridConfig — the single source of truth for a circuit grid instance. */
+export declare const defaultCircuitGridConfig: CircuitGridConfig;
+/**
+ * A Truchet circuit board on a shader plane.
+ *
+ * Each tile carries two quarter-arcs and half the tiles are mirrored, which is
+ * what chains them into long meandering traces instead of disconnected curves.
+ * `lineMode` 2 sends light pulses travelling along those traces; the other
+ * modes match the rest of the grid family (static, ripple, scan, pulse).
+ * `chipChance` sprinkles IC packages across the board and `sectionSize` lays
+ * straight buses over the weave.
+ */
+export declare function CircuitGrid({ config, groupProps, onObjectReady, onObjectDispose }: CircuitGridProps): import("react").JSX.Element;
+export default CircuitGrid;
+//# sourceMappingURL=CircuitGrid.d.ts.map

package/dist/components/CircuitGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitGrid.d.ts","sourceRoot":"","sources":["../../src/components/CircuitGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACtD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACvC;AAKD,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,EAAE,iBA4BtC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAiC,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,gBAAgB,+BAiE9H;AAED,eAAe,WAAW,CAAC"}

package/dist/components/CircuitGrid.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useObjectReady } from '../hooks/useObjectReady.js';
+import { useGridSurface } from '../hooks/useGridSurface.js';
+import { CircuitGridMaterial } from '@3driseai/3drise-core';
+// Side-effect import registers <circuitGridMaterial> via extend().
+void CircuitGridMaterial;
+/** CircuitGridConfig — the single source of truth for a circuit grid instance. */
+export const defaultCircuitGridConfig = {
+    cellSize: 1.6,
+    size: 50,
+    segments: undefined,
+    flat: true,
+    lineMode: 2, // signal pulses running along the traces
+    cellMode: 0,
+    lineWidth: 1.6,
+    sectionSize: 6,
+    sectionWidth: 1.2,
+    animSpeed: 1,
+    animScale: 1,
+    animIntensity: 1,
+    fadeDistance: undefined,
+    fadeStrength: 0.7,
+    displace: 0,
+    powered: 0.65,
+    chipChance: 0.06,
+    padSize: 1,
+    lineColor: '#186b5c',
+    sectionColor: '#8cf0b4',
+    cellColor: '#082420',
+    glowColor: '#59ffb8',
+    bgColor: '#020806',
+    bgOpacity: 0,
+    followMouse: false,
+    reveal: 1,
+    revealDuration: 0,
+};
+/**
+ * A Truchet circuit board on a shader plane.
+ *
+ * Each tile carries two quarter-arcs and half the tiles are mirrored, which is
+ * what chains them into long meandering traces instead of disconnected curves.
+ * `lineMode` 2 sends light pulses travelling along those traces; the other
+ * modes match the rest of the grid family (static, ripple, scan, pulse).
+ * `chipChance` sprinkles IC packages across the board and `sectionSize` lays
+ * straight buses over the weave.
+ */
+export function CircuitGrid({ config = defaultCircuitGridConfig, groupProps, onObjectReady, onObjectDispose }) {
+    const matRef = useRef(null);
+    const rootRef = useRef(null);
+    const meshRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const { cellSize, size, segments, flat, lineMode, cellMode, lineWidth, sectionSize, sectionWidth, animSpeed, animScale, animIntensity, fadeDistance, fadeStrength, displace, powered, chipChance, padSize, lineColor, sectionColor, cellColor, glowColor, bgColor, bgOpacity, followMouse, reveal, revealDuration, } = config;
+    const segs = segments ?? (displace > 0
+        ? Math.min(256, Math.max(64, Math.ceil(size / Math.max(cellSize, 1e-4)) * 2))
+        : 1);
+    const fade = fadeDistance ?? size * 0.5;
+    const colors = useMemo(() => ({
+        line: new THREE.Color(lineColor),
+        section: new THREE.Color(sectionColor),
+        cell: new THREE.Color(cellColor),
+        glow: new THREE.Color(glowColor),
+        bg: new THREE.Color(bgColor),
+    }), [lineColor, sectionColor, cellColor, glowColor, bgColor]);
+    useGridSurface(matRef, meshRef, { followMouse, reveal, revealDuration });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("circuitGridMaterial", { ref: matRef, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, u_cellSize: cellSize, u_lineWidth: lineWidth, u_sectionSize: sectionSize, u_sectionWidth: sectionWidth, u_lineMode: lineMode, u_cellMode: cellMode, u_animSpeed: animSpeed, u_animScale: animScale, u_animIntensity: animIntensity, u_fadeDistance: fade, u_fadeStrength: fadeStrength, u_displace: displace, u_powered: powered, u_chipChance: chipChance, u_padSize: padSize, u_lineColor: colors.line, u_sectionColor: colors.section, u_cellColor: colors.cell, u_glowColor: colors.glow, u_bgColor: colors.bg, u_bgOpacity: bgOpacity }, CircuitGridMaterial.key)] }) }));
+}
+export default CircuitGrid;

package/dist/components/Clouds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Clouds.d.ts","sourceRoot":"","sources":["../../src/components/Clouds.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACjD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B;AAmFD,QAAA,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CA2LjC,CAAC;AACF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Clouds.d.ts","sourceRoot":"","sources":["../../src/components/Clouds.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACjD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B;AAmFD,QAAA,MAAM,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAsLjC,CAAC;AACF,eAAe,MAAM,CAAC"}

package/dist/components/Clouds.js

@@ -94,9 +94,7 @@ const Clouds = ({ settings, timeSettings = defaultTimeSettings, onObjectReady, o
     const materialSettings = settings.materialSettings;
     const position = meshSettings.position;
     const scale = meshSettings.scale;
-    // console.log(config.speed)
     const baseSpeed = config.speed ?? 1;
-    // console.log(baseSpeed)
     const height = position[1];
     const planeSize = config?.planeSize || [10000, 10000];
     const planeSegments = config?.planeSegments || 64;
@@ -236,10 +234,7 @@ const Clouds = ({ settings, timeSettings = defaultTimeSettings, onObjectReady, o
             ?? numericOverrideRef.current?.speed
             ?? mouseOverrideRef.current.speed
             ?? baseSpeed;
-        // console.log(effectiveSpeed)
-        // console.log(effectiveSpeed)
         cloudAnimTime.current += 0.02 * effectiveSpeed;
-        // console.log(cloudAnimTime.current)
         if (uniforms.u_time)
             uniforms.u_time.value = cloudAnimTime.current;
         if (uniforms.u_cameraPos) {

package/dist/components/ContourGrid.d.ts

@@ -0,0 +1,25 @@
+import type { ThreeElements } from '@react-three/fiber';
+import type { ObjectReadyProps } from '../types/objectReady';
+import type { ContourGridConfig } from '../types/gridConfigs';
+export interface ContourGridProps extends ObjectReadyProps {
+    config?: ContourGridConfig;
+    groupProps?: ThreeElements['group'];
+}
+/** ContourGridConfig — the single source of truth for a contour grid instance. */
+export declare const defaultContourGridConfig: ContourGridConfig;
+/**
+ * Topographic iso-lines over a drifting terrain field — minor contours every
+ * step, index contours every `sectionSize`.
+ *
+ * `displace` is literal here rather than decorative: the vertex stage raises the
+ * surface to exactly the elevation the contours describe, because both stages
+ * evaluate the same terrain function. That is also why the two must stay in
+ * sync — any divergence slides the lines off the landform they describe.
+ *
+ * `cellSize` is the horizontal scale of the terrain, so it is much larger than
+ * on the lattice grids; `roughness` runs from rolling to craggy and `warp`
+ * bends the contours into ridges and valleys.
+ */
+export declare function ContourGrid({ config, groupProps, onObjectReady, onObjectDispose }: ContourGridProps): import("react").JSX.Element;
+export default ContourGrid;
+//# sourceMappingURL=ContourGrid.d.ts.map

package/dist/components/ContourGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContourGrid.d.ts","sourceRoot":"","sources":["../../src/components/ContourGrid.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACtD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACvC;AAKD,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,EAAE,iBA4BtC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAiC,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,gBAAgB,+BAmE9H;AAED,eAAe,WAAW,CAAC"}

package/dist/components/ContourGrid.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useObjectReady } from '../hooks/useObjectReady.js';
+import { useGridSurface } from '../hooks/useGridSurface.js';
+import { ContourGridMaterial } from '@3driseai/3drise-core';
+// Side-effect import registers <contourGridMaterial> via extend().
+void ContourGridMaterial;
+/** ContourGridConfig — the single source of truth for a contour grid instance. */
+export const defaultContourGridConfig = {
+    cellSize: 14,
+    size: 50,
+    segments: undefined,
+    flat: true,
+    lineMode: 0,
+    cellMode: 1, // elevation tint
+    lineWidth: 1,
+    sectionSize: 5,
+    sectionWidth: 2.2,
+    animSpeed: 1,
+    animScale: 0.5,
+    animIntensity: 1,
+    fadeDistance: undefined,
+    fadeStrength: 0.7,
+    displace: 0,
+    levels: 16,
+    roughness: 0.5,
+    warp: 0.35,
+    lineColor: '#59d9b3',
+    sectionColor: '#bff299',
+    cellColor: '#1a5c52',
+    glowColor: '#8cffbf',
+    bgColor: '#020a0a',
+    bgOpacity: 0,
+    followMouse: false,
+    reveal: 1,
+    revealDuration: 0,
+};
+/**
+ * Topographic iso-lines over a drifting terrain field — minor contours every
+ * step, index contours every `sectionSize`.
+ *
+ * `displace` is literal here rather than decorative: the vertex stage raises the
+ * surface to exactly the elevation the contours describe, because both stages
+ * evaluate the same terrain function. That is also why the two must stay in
+ * sync — any divergence slides the lines off the landform they describe.
+ *
+ * `cellSize` is the horizontal scale of the terrain, so it is much larger than
+ * on the lattice grids; `roughness` runs from rolling to craggy and `warp`
+ * bends the contours into ridges and valleys.
+ */
+export function ContourGrid({ config = defaultContourGridConfig, groupProps, onObjectReady, onObjectDispose }) {
+    const matRef = useRef(null);
+    const rootRef = useRef(null);
+    const meshRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const { cellSize, size, segments, flat, lineMode, cellMode, lineWidth, sectionSize, sectionWidth, animSpeed, animScale, animIntensity, fadeDistance, fadeStrength, displace, levels, roughness, warp, lineColor, sectionColor, cellColor, glowColor, bgColor, bgOpacity, followMouse, reveal, revealDuration, } = config;
+    // Terrain needs a far denser mesh than the lattice grids: the silhouette is
+    // the whole point, and it is only as good as the tessellation carrying it.
+    const segs = segments ?? (displace > 0
+        ? Math.min(384, Math.max(128, Math.ceil(size / Math.max(cellSize, 1e-4)) * 48))
+        : 1);
+    const fade = fadeDistance ?? size * 0.5;
+    const colors = useMemo(() => ({
+        line: new THREE.Color(lineColor),
+        section: new THREE.Color(sectionColor),
+        cell: new THREE.Color(cellColor),
+        glow: new THREE.Color(glowColor),
+        bg: new THREE.Color(bgColor),
+    }), [lineColor, sectionColor, cellColor, glowColor, bgColor]);
+    useGridSurface(matRef, meshRef, { followMouse, reveal, revealDuration });
+    return (_jsx("group", { ref: rootRef, ...groupProps, children: _jsxs("mesh", { ref: meshRef, rotation: flat ? [-Math.PI / 2, 0, 0] : [0, 0, 0], children: [_jsx("planeGeometry", { args: [size, size, segs, segs] }), _jsx("contourGridMaterial", { ref: matRef, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, u_cellSize: cellSize, u_lineWidth: lineWidth, u_sectionSize: sectionSize, u_sectionWidth: sectionWidth, u_lineMode: lineMode, u_cellMode: cellMode, u_animSpeed: animSpeed, u_animScale: animScale, u_animIntensity: animIntensity, u_fadeDistance: fade, u_fadeStrength: fadeStrength, u_displace: displace, u_levels: levels, u_roughness: roughness, u_warp: warp, u_lineColor: colors.line, u_sectionColor: colors.section, u_cellColor: colors.cell, u_glowColor: colors.glow, u_bgColor: colors.bg, u_bgOpacity: bgOpacity }, ContourGridMaterial.key)] }) }));
+}
+export default ContourGrid;

package/dist/components/CreatedObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CreatedObject.d.ts","sourceRoot":"","sources":["../../src/components/CreatedObject.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,kBAAmB,SAAQ,gBAAgB;IACjD,aAAa,EAAE,qBAAqB,CAAC;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CACpH;AAGD,QAAA,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAmF9C,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"CreatedObject.d.ts","sourceRoot":"","sources":["../../src/components/CreatedObject.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,kBAAmB,SAAQ,gBAAgB;IACjD,aAAa,EAAE,qBAAqB,CAAC;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CACpH;AAGD,QAAA,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAgF9C,CAAC;AAEH,eAAe,aAAa,CAAC"}