@particle-academy/fancy-3d-babylon 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @particle-academy/fancy-3d-babylon
+
+Babylon.js adapter for [`@particle-academy/fancy-3d`](https://www.npmjs.com/package/@particle-academy/fancy-3d).
+
+`fancy-3d` ships an engine-agnostic core (Scene types + a `CanvasEngine` interface + a DOM/CSS-3D renderer). This package adds a full WebGL renderer on top, plus the React components that mount onto a Babylon `Scene`: `Stage`, `Monitor`, `Card3D`, `Screen`, primitives, and layout helpers (`placeOnGrid`, `placeOnArc`, `placeOnWall`, `placeOnSphere`, `placeOnPath`).
+
+> A Three.js / WebGPU / WebXR engine could ship as a sibling package: `fancy-3d-three`, `fancy-3d-webgpu`, etc. They implement the same `CanvasEngine` interface from the core; they don't depend on this one.
+
+## Install
+
+```bash
+npm install @particle-academy/fancy-3d @particle-academy/fancy-3d-babylon @babylonjs/core
+```
+
+You always install three packages together: the core (types + `<Canvas>`), the Babylon adapter (this package), and Babylon itself. None of them pull in the others to keep the core lightweight for non-Babylon consumers.
+
+## Usage
+
+### Mount the Babylon engine on `<Canvas>`
+
+```tsx
+import { Canvas } from "@particle-academy/fancy-3d";
+import { babylonEngine } from "@particle-academy/fancy-3d-babylon/engine";
+
+<Canvas engine={babylonEngine} style={{ height: 480 }}>
+  {/* 2D children are still allowed — Canvas hosts a DOM overlay
+      alongside the WebGL view */}
+</Canvas>
+```
+
+### Stage / Monitor / Card3D (React)
+
+```tsx
+import { Stage, Monitor, Card3D } from "@particle-academy/fancy-3d-babylon/react";
+import { Card } from "@particle-academy/react-fancy";
+
+<Stage camera={{ position: [0, 2, 5], target: [0, 0, 0] }}>
+  <Monitor width={2} height={1.2} position={[0, 1, 0]}>
+    <Card>
+      <Card.Body>This react-fancy card renders as a live WebGL texture.</Card.Body>
+    </Card>
+  </Monitor>
+  <Card3D position={[2, 0, 0]} rotation={[0, 30, 0]}>
+    <h3>Children are plain React</h3>
+  </Card3D>
+</Stage>
+```
+
+### Layout helpers
+
+```tsx
+import { placeOnGrid, placeOnArc } from "@particle-academy/fancy-3d-babylon";
+
+placeOnGrid(node, mesh, bounds, { cols: 4, gapX: 0.2, gapY: 0.2 });
+placeOnArc(node, mesh, bounds, { radius: 3, startAngle: 0, endAngle: Math.PI });
+```
+
+## Why a separate package?
+
+The core `fancy-3d` is engine-agnostic and lightweight (~80KB). Pulling in Babylon would force every consumer — including ones using only the DOM engine or shipping a custom Three.js adapter — to bundle ~13MB of WebGL runtime they don't use. The split keeps Babylon's cost paid only by Babylon consumers.
+
+## License
+
+MIT

package/dist/chunk-DGUM43GV.js

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };
+//# sourceMappingURL=chunk-DGUM43GV.js.map
+//# sourceMappingURL=chunk-DGUM43GV.js.map

package/dist/chunk-DGUM43GV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-DGUM43GV.js"}

package/dist/engine.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/engine.ts
+var babylonEngine = {
+  name: "babylon",
+  mount(host, viewport) {
+    const BABYLON = __require("@babylonjs/core");
+    const overlay = document.createElement("canvas");
+    overlay.style.position = "absolute";
+    overlay.style.inset = "0";
+    overlay.style.width = "100%";
+    overlay.style.height = "100%";
+    overlay.style.pointerEvents = "none";
+    overlay.dataset.fancy3dCanvasEngine = "babylon";
+    host.appendChild(overlay);
+    const engine = new BABYLON.Engine(overlay, true, { preserveDrawingBuffer: true, stencil: true });
+    const scene = new BABYLON.Scene(engine);
+    scene.clearColor = new BABYLON.Color4(0, 0, 0, 0);
+    const camera = new BABYLON.ArcRotateCamera(
+      "fancy3d-canvas-camera",
+      Math.PI / 2,
+      Math.PI / 2.5,
+      8,
+      BABYLON.Vector3.Zero(),
+      scene
+    );
+    camera.attachControl(overlay, false);
+    new BABYLON.HemisphericLight("fancy3d-canvas-light", new BABYLON.Vector3(0, 1, 0), scene);
+    const observer = engine.runRenderLoop(() => scene.render());
+    function updateViewport(_v) {
+    }
+    function dispose() {
+      try {
+        engine.stopRenderLoop(observer);
+      } catch {
+      }
+      scene.dispose();
+      engine.dispose();
+      if (overlay.parentElement === host) host.removeChild(overlay);
+    }
+    return {
+      name: "babylon",
+      root: scene,
+      updateViewport,
+      dispose
+    };
+  }
+};
+
+exports.babylonEngine = babylonEngine;
+//# sourceMappingURL=engine.cjs.map
+//# sourceMappingURL=engine.cjs.map

package/dist/engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.ts"],"names":[],"mappings":";;;;;;;;;;AAqBO,IAAM,aAAA,GAA8B;AAAA,EACzC,IAAA,EAAM,SAAA;AAAA,EACN,KAAA,CAAM,MAAmB,QAAA,EAAuC;AAG9D,IAAA,MAAM,OAAA,GAAe,UAAQ,iBAAiB,CAAA;AAE9C,IAAA,MAAM,OAAA,GAAU,QAAA,CAAS,aAAA,CAAc,QAAQ,CAAA;AAC/C,IAAA,OAAA,CAAQ,MAAM,QAAA,GAAW,UAAA;AACzB,IAAA,OAAA,CAAQ,MAAM,KAAA,GAAQ,GAAA;AACtB,IAAA,OAAA,CAAQ,MAAM,KAAA,GAAQ,MAAA;AACtB,IAAA,OAAA,CAAQ,MAAM,MAAA,GAAS,MAAA;AACvB,IAAA,OAAA,CAAQ,MAAM,aAAA,GAAgB,MAAA;AAC9B,IAAA,OAAA,CAAQ,QAAQ,mBAAA,GAAsB,SAAA;AACtC,IAAA,IAAA,CAAK,YAAY,OAAO,CAAA;AAExB,IAAA,MAAM,MAAA,GAAS,IAAI,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,IAAA,EAAM,EAAE,qBAAA,EAAuB,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,CAAA;AAC/F,IAAA,MAAM,KAAA,GAAQ,IAAI,OAAA,CAAQ,KAAA,CAAM,MAAM,CAAA;AACtC,IAAA,KAAA,CAAM,aAAa,IAAI,OAAA,CAAQ,OAAO,CAAA,EAAG,CAAA,EAAG,GAAG,CAAC,CAAA;AAEhD,IAAA,MAAM,MAAA,GAAS,IAAI,OAAA,CAAQ,eAAA;AAAA,MACzB,uBAAA;AAAA,MACA,KAAK,EAAA,GAAK,CAAA;AAAA,MACV,KAAK,EAAA,GAAK,GAAA;AAAA,MACV,CAAA;AAAA,MACA,OAAA,CAAQ,QAAQ,IAAA,EAAK;AAAA,MACrB;AAAA,KACF;AACA,IAAA,MAAA,CAAO,aAAA,CAAc,SAAS,KAAK,CAAA;AACnC,IAAA,IAAI,OAAA,CAAQ,gBAAA,CAAiB,sBAAA,EAAwB,IAAI,OAAA,CAAQ,QAAQ,CAAA,EAAG,CAAA,EAAG,CAAC,CAAA,EAAG,KAAK,CAAA;AAExF,IAAA,MAAM,WAAW,MAAA,CAAO,aAAA,CAAc,MAAM,KAAA,CAAM,QAAQ,CAAA;AAE1D,IAAA,SAAS,eAAe,EAAA,EAAmB;AAAA,IAI3C;AAEA,IAAA,SAAS,OAAA,GAAU;AACjB,MAAA,IAAI;AAAE,QAAA,MAAA,CAAO,eAAe,QAAe,CAAA;AAAA,MAAG,CAAA,CAAA,MAAQ;AAAA,MAAC;AACvD,MAAA,KAAA,CAAM,OAAA,EAAQ;AACd,MAAA,MAAA,CAAO,OAAA,EAAQ;AACf,MAAA,IAAI,OAAA,CAAQ,aAAA,KAAkB,IAAA,EAAM,IAAA,CAAK,YAAY,OAAO,CAAA;AAAA,IAC9D;AAEA,IAAA,OAAO;AAAA,MACL,IAAA,EAAM,SAAA;AAAA,MACN,IAAA,EAAM,KAAA;AAAA,MACN,cAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF","file":"engine.cjs","sourcesContent":["/**\n * Babylon engine adapter for `@particle-academy/fancy-3d`'s <Canvas>.\n *\n * Mounts a Babylon `Engine` + `Scene` + camera into a `<canvas>` element\n * overlaid on the Canvas DOM container, then exposes the live `Scene` via\n * `EngineHandle.root` so child components can register meshes alongside the\n * 2D node graph.\n *\n *   import { Canvas } from \"@particle-academy/fancy-3d\";\n *   import { babylonEngine } from \"@particle-academy/fancy-3d-babylon/engine\";\n *\n *   <Canvas engine={babylonEngine} style={{ height: 480 }} />\n */\nimport type { CanvasEngine, EngineHandle, ViewportState } from \"@particle-academy/fancy-3d\";\n\n// Declare a CJS-style `require` so the dts compiler doesn't reject the lazy\n// load below. Browsers don't have `require`, but this whole engine adapter\n// only runs when a host bundler (vite/webpack) replaces the call with its own\n// lazy-module shim, or under node-side SSR where the global exists.\ndeclare const require: (specifier: string) => unknown;\n\nexport const babylonEngine: CanvasEngine = {\n  name: \"babylon\",\n  mount(host: HTMLElement, viewport: ViewportState): EngineHandle {\n    // Lazy require so non-babylon Canvas users don't pay the parse cost.\n    // eslint-disable-next-line @typescript-eslint/no-require-imports\n    const BABYLON: any = require(\"@babylonjs/core\");\n\n    const overlay = document.createElement(\"canvas\");\n    overlay.style.position = \"absolute\";\n    overlay.style.inset = \"0\";\n    overlay.style.width = \"100%\";\n    overlay.style.height = \"100%\";\n    overlay.style.pointerEvents = \"none\";\n    overlay.dataset.fancy3dCanvasEngine = \"babylon\";\n    host.appendChild(overlay);\n\n    const engine = new BABYLON.Engine(overlay, true, { preserveDrawingBuffer: true, stencil: true });\n    const scene = new BABYLON.Scene(engine);\n    scene.clearColor = new BABYLON.Color4(0, 0, 0, 0);\n\n    const camera = new BABYLON.ArcRotateCamera(\n      \"fancy3d-canvas-camera\",\n      Math.PI / 2,\n      Math.PI / 2.5,\n      8,\n      BABYLON.Vector3.Zero(),\n      scene,\n    );\n    camera.attachControl(overlay, false);\n    new BABYLON.HemisphericLight(\"fancy3d-canvas-light\", new BABYLON.Vector3(0, 1, 0), scene);\n\n    const observer = engine.runRenderLoop(() => scene.render());\n\n    function updateViewport(_v: ViewportState) {\n      // Default: 6DoF camera owns view; 2D viewport changes are observed\n      // but don't move the Babylon camera. Consumers can override by\n      // attaching their own observers to the scene.\n    }\n\n    function dispose() {\n      try { engine.stopRenderLoop(observer as any); } catch {}\n      scene.dispose();\n      engine.dispose();\n      if (overlay.parentElement === host) host.removeChild(overlay);\n    }\n\n    return {\n      name: \"babylon\",\n      root: scene,\n      updateViewport,\n      dispose,\n    };\n  },\n};\n"]}

package/dist/engine.d.cts

@@ -0,0 +1,19 @@
+import { CanvasEngine } from '@particle-academy/fancy-3d';
+
+/**
+ * Babylon engine adapter for `@particle-academy/fancy-3d`'s <Canvas>.
+ *
+ * Mounts a Babylon `Engine` + `Scene` + camera into a `<canvas>` element
+ * overlaid on the Canvas DOM container, then exposes the live `Scene` via
+ * `EngineHandle.root` so child components can register meshes alongside the
+ * 2D node graph.
+ *
+ *   import { Canvas } from "@particle-academy/fancy-3d";
+ *   import { babylonEngine } from "@particle-academy/fancy-3d-babylon/engine";
+ *
+ *   <Canvas engine={babylonEngine} style={{ height: 480 }} />
+ */
+
+declare const babylonEngine: CanvasEngine;
+
+export { babylonEngine };

package/dist/engine.d.ts

@@ -0,0 +1,19 @@
+import { CanvasEngine } from '@particle-academy/fancy-3d';
+
+/**
+ * Babylon engine adapter for `@particle-academy/fancy-3d`'s <Canvas>.
+ *
+ * Mounts a Babylon `Engine` + `Scene` + camera into a `<canvas>` element
+ * overlaid on the Canvas DOM container, then exposes the live `Scene` via
+ * `EngineHandle.root` so child components can register meshes alongside the
+ * 2D node graph.
+ *
+ *   import { Canvas } from "@particle-academy/fancy-3d";
+ *   import { babylonEngine } from "@particle-academy/fancy-3d-babylon/engine";
+ *
+ *   <Canvas engine={babylonEngine} style={{ height: 480 }} />
+ */
+
+declare const babylonEngine: CanvasEngine;
+
+export { babylonEngine };

package/dist/engine.js

@@ -0,0 +1,52 @@
+import { __require } from './chunk-DGUM43GV.js';
+
+// src/engine.ts
+var babylonEngine = {
+  name: "babylon",
+  mount(host, viewport) {
+    const BABYLON = __require("@babylonjs/core");
+    const overlay = document.createElement("canvas");
+    overlay.style.position = "absolute";
+    overlay.style.inset = "0";
+    overlay.style.width = "100%";
+    overlay.style.height = "100%";
+    overlay.style.pointerEvents = "none";
+    overlay.dataset.fancy3dCanvasEngine = "babylon";
+    host.appendChild(overlay);
+    const engine = new BABYLON.Engine(overlay, true, { preserveDrawingBuffer: true, stencil: true });
+    const scene = new BABYLON.Scene(engine);
+    scene.clearColor = new BABYLON.Color4(0, 0, 0, 0);
+    const camera = new BABYLON.ArcRotateCamera(
+      "fancy3d-canvas-camera",
+      Math.PI / 2,
+      Math.PI / 2.5,
+      8,
+      BABYLON.Vector3.Zero(),
+      scene
+    );
+    camera.attachControl(overlay, false);
+    new BABYLON.HemisphericLight("fancy3d-canvas-light", new BABYLON.Vector3(0, 1, 0), scene);
+    const observer = engine.runRenderLoop(() => scene.render());
+    function updateViewport(_v) {
+    }
+    function dispose() {
+      try {
+        engine.stopRenderLoop(observer);
+      } catch {
+      }
+      scene.dispose();
+      engine.dispose();
+      if (overlay.parentElement === host) host.removeChild(overlay);
+    }
+    return {
+      name: "babylon",
+      root: scene,
+      updateViewport,
+      dispose
+    };
+  }
+};
+
+export { babylonEngine };
+//# sourceMappingURL=engine.js.map
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.ts"],"names":[],"mappings":";;;AAqBO,IAAM,aAAA,GAA8B;AAAA,EACzC,IAAA,EAAM,SAAA;AAAA,EACN,KAAA,CAAM,MAAmB,QAAA,EAAuC;AAG9D,IAAA,MAAM,OAAA,GAAe,UAAQ,iBAAiB,CAAA;AAE9C,IAAA,MAAM,OAAA,GAAU,QAAA,CAAS,aAAA,CAAc,QAAQ,CAAA;AAC/C,IAAA,OAAA,CAAQ,MAAM,QAAA,GAAW,UAAA;AACzB,IAAA,OAAA,CAAQ,MAAM,KAAA,GAAQ,GAAA;AACtB,IAAA,OAAA,CAAQ,MAAM,KAAA,GAAQ,MAAA;AACtB,IAAA,OAAA,CAAQ,MAAM,MAAA,GAAS,MAAA;AACvB,IAAA,OAAA,CAAQ,MAAM,aAAA,GAAgB,MAAA;AAC9B,IAAA,OAAA,CAAQ,QAAQ,mBAAA,GAAsB,SAAA;AACtC,IAAA,IAAA,CAAK,YAAY,OAAO,CAAA;AAExB,IAAA,MAAM,MAAA,GAAS,IAAI,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,IAAA,EAAM,EAAE,qBAAA,EAAuB,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,CAAA;AAC/F,IAAA,MAAM,KAAA,GAAQ,IAAI,OAAA,CAAQ,KAAA,CAAM,MAAM,CAAA;AACtC,IAAA,KAAA,CAAM,aAAa,IAAI,OAAA,CAAQ,OAAO,CAAA,EAAG,CAAA,EAAG,GAAG,CAAC,CAAA;AAEhD,IAAA,MAAM,MAAA,GAAS,IAAI,OAAA,CAAQ,eAAA;AAAA,MACzB,uBAAA;AAAA,MACA,KAAK,EAAA,GAAK,CAAA;AAAA,MACV,KAAK,EAAA,GAAK,GAAA;AAAA,MACV,CAAA;AAAA,MACA,OAAA,CAAQ,QAAQ,IAAA,EAAK;AAAA,MACrB;AAAA,KACF;AACA,IAAA,MAAA,CAAO,aAAA,CAAc,SAAS,KAAK,CAAA;AACnC,IAAA,IAAI,OAAA,CAAQ,gBAAA,CAAiB,sBAAA,EAAwB,IAAI,OAAA,CAAQ,QAAQ,CAAA,EAAG,CAAA,EAAG,CAAC,CAAA,EAAG,KAAK,CAAA;AAExF,IAAA,MAAM,WAAW,MAAA,CAAO,aAAA,CAAc,MAAM,KAAA,CAAM,QAAQ,CAAA;AAE1D,IAAA,SAAS,eAAe,EAAA,EAAmB;AAAA,IAI3C;AAEA,IAAA,SAAS,OAAA,GAAU;AACjB,MAAA,IAAI;AAAE,QAAA,MAAA,CAAO,eAAe,QAAe,CAAA;AAAA,MAAG,CAAA,CAAA,MAAQ;AAAA,MAAC;AACvD,MAAA,KAAA,CAAM,OAAA,EAAQ;AACd,MAAA,MAAA,CAAO,OAAA,EAAQ;AACf,MAAA,IAAI,OAAA,CAAQ,aAAA,KAAkB,IAAA,EAAM,IAAA,CAAK,YAAY,OAAO,CAAA;AAAA,IAC9D;AAEA,IAAA,OAAO;AAAA,MACL,IAAA,EAAM,SAAA;AAAA,MACN,IAAA,EAAM,KAAA;AAAA,MACN,cAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF","file":"engine.js","sourcesContent":["/**\n * Babylon engine adapter for `@particle-academy/fancy-3d`'s <Canvas>.\n *\n * Mounts a Babylon `Engine` + `Scene` + camera into a `<canvas>` element\n * overlaid on the Canvas DOM container, then exposes the live `Scene` via\n * `EngineHandle.root` so child components can register meshes alongside the\n * 2D node graph.\n *\n *   import { Canvas } from \"@particle-academy/fancy-3d\";\n *   import { babylonEngine } from \"@particle-academy/fancy-3d-babylon/engine\";\n *\n *   <Canvas engine={babylonEngine} style={{ height: 480 }} />\n */\nimport type { CanvasEngine, EngineHandle, ViewportState } from \"@particle-academy/fancy-3d\";\n\n// Declare a CJS-style `require` so the dts compiler doesn't reject the lazy\n// load below. Browsers don't have `require`, but this whole engine adapter\n// only runs when a host bundler (vite/webpack) replaces the call with its own\n// lazy-module shim, or under node-side SSR where the global exists.\ndeclare const require: (specifier: string) => unknown;\n\nexport const babylonEngine: CanvasEngine = {\n  name: \"babylon\",\n  mount(host: HTMLElement, viewport: ViewportState): EngineHandle {\n    // Lazy require so non-babylon Canvas users don't pay the parse cost.\n    // eslint-disable-next-line @typescript-eslint/no-require-imports\n    const BABYLON: any = require(\"@babylonjs/core\");\n\n    const overlay = document.createElement(\"canvas\");\n    overlay.style.position = \"absolute\";\n    overlay.style.inset = \"0\";\n    overlay.style.width = \"100%\";\n    overlay.style.height = \"100%\";\n    overlay.style.pointerEvents = \"none\";\n    overlay.dataset.fancy3dCanvasEngine = \"babylon\";\n    host.appendChild(overlay);\n\n    const engine = new BABYLON.Engine(overlay, true, { preserveDrawingBuffer: true, stencil: true });\n    const scene = new BABYLON.Scene(engine);\n    scene.clearColor = new BABYLON.Color4(0, 0, 0, 0);\n\n    const camera = new BABYLON.ArcRotateCamera(\n      \"fancy3d-canvas-camera\",\n      Math.PI / 2,\n      Math.PI / 2.5,\n      8,\n      BABYLON.Vector3.Zero(),\n      scene,\n    );\n    camera.attachControl(overlay, false);\n    new BABYLON.HemisphericLight(\"fancy3d-canvas-light\", new BABYLON.Vector3(0, 1, 0), scene);\n\n    const observer = engine.runRenderLoop(() => scene.render());\n\n    function updateViewport(_v: ViewportState) {\n      // Default: 6DoF camera owns view; 2D viewport changes are observed\n      // but don't move the Babylon camera. Consumers can override by\n      // attaching their own observers to the scene.\n    }\n\n    function dispose() {\n      try { engine.stopRenderLoop(observer as any); } catch {}\n      scene.dispose();\n      engine.dispose();\n      if (overlay.parentElement === host) host.removeChild(overlay);\n    }\n\n    return {\n      name: \"babylon\",\n      root: scene,\n      updateViewport,\n      dispose,\n    };\n  },\n};\n"]}