@shopware-ag/dive 1.19.1-beta.2 → 1.19.1-beta.4

package/README.md

@@ -1,12 +1,3 @@
-<!--
-
-
-This file is automatically generated
-You can find the template in ci/readme/template/TEMPLATE_README.md
-
-
--->
-
 <p align="center">
     <img alt="DIVE logo" src="./assets/svg/dive.svg" style="width: 100%; height: auto; max-height: 500px;">
 </p>
@@ -28,25 +19,45 @@ You can find the template in ci/readme/template/TEMPLATE_README.md
 
 ## Table of Contents
 
-1. [About](#about)
-2. [Installation](#installation)
-3. [Local development](#local-development)
-4. [Setup in Shopware](#setup-in-shopware)
-5. [Usage](#usage)
-6. [Unit Tests](#unit-tests)
-7. [Formatting](#formatting)
+- [Table of Contents](#table-of-contents)
+- [About](#about)
+- [Setup and Maintenance](#setup-and-maintenance)
+  - [Installation](#installation)
+  - [Module System](#module-system)
+    - [Module Exports](#module-exports)
+    - [Build Process](#build-process)
+    - [Development Workflow](#development-workflow)
+  - [Local Development with Yalc](#local-development-with-yalc)
+  - [Shopware Integration](#shopware-integration)
+  - [Testing and Quality Assurance](#testing-and-quality-assurance)
+    - [Unit Tests](#unit-tests)
+    - [Code Formatting](#code-formatting)
+- [Usage Guide](#usage-guide)
+  - [Core Concepts](#core-concepts)
+    - [Quick View](#quick-view)
+    - [Getting Started](#getting-started)
+      - [Import](#import)
+      - [Instantiate](#instantiate)
+  - [Modules](#modules)
+  - [Modules (List)](#modules-list)
+  - [Actions](#actions)
+    - [Basic Usage](#basic-usage)
+    - [Subscribing to Actions](#subscribing-to-actions)
+    - [Actions List](#actions-list)
 
 ## About
 
-DIVE is a spatial framework made by and optimized for Shopware. It can be used
-directly integrated in a Shopware frontend such as Storefront or in any other
-frontend you want to use it in, it is not tied to Shopware.
+DIVE is a spatial framework made by and optimized for Shopware. It can be used directly integrated
+in a Shopware frontend such as Storefront or in any other frontend you want to use it in, it is not
+tied to Shopware.
+
+DIVE supplies your frontend application with all needed tooling to set up a basic 3D application
+with event-based controls called "Actions". For further information, see
+[Getting started](#getting-started).
 
-DIVE supplies your frontend application with all needed tooling to set up a
-basic 3D application with event-based controls called "Actions". For further
-information, see [Getting started](#getting-started).
+## Setup and Maintenance
 
-## Installation
+### Installation
 
 The `@shopware-ag/dive` package can be installed via
 
@@ -58,59 +69,110 @@ or
 yarn add @shopware-ag/dive
 ```
 
-## Local development
+### Module System
+
+DIVE uses a modern module system with support for both ESM and CommonJS formats. The package is
+built using Vite and supports the following module formats:
+
+- ESM (`.mjs` files)
+- CommonJS (`.cjs` files)
+- TypeScript type definitions (`.d.ts` files)
+
+#### Module Exports
+
+The package exports are configured in `package.json` to support both direct imports and
+module-specific imports:
+
+```json
+{
+    "exports": {
+        ".": {
+            "types": "./build/index.d.ts",
+            "import": "./build/index.mjs",
+            "require": "./build/index.cjs"
+        },
+        "./modules/*": {
+            "types": "./build/src/modules/*.d.ts",
+            "import": "./build/src/modules/*.mjs",
+            "require": "./build/src/modules/*.cjs"
+        }
+    }
+}
+```
 
-### with devenv
+#### Build Process
 
-If you are using `devenv`, you have to make sure that you are in the correct shell while linking. `nix` (what `devenv` is
-based on) uses it's own instances of `npm` so we need to make sure that the `npm link` get's executed within the correct `devenv` environment a.k.a `nix/store`.
-To make sure you are using the correct instance of `npm` you have to browse to your `devenv` project:
+The build process is handled by Vite and can be triggered using:
 
 ```bash
-cd path/to/your/devenv.nix
+yarn build        # One-time build
+yarn dev          # Watch mode for development
 ```
 
-#### with direnv
+The build process:
 
-If you use `direnv` you should be launched into the correct shell automatically.
+1. Compiles TypeScript code
+2. Generates type definitions
+3. Creates both ESM and CommonJS versions of the code
+4. Places all output in the `build/` directory
 
-#### without direnv
+#### Development Workflow
 
-If you don't use `direnv` you can start the correct shell manually by running
+For local development, you can use the watch mode to automatically rebuild when files change:
 
 ```bash
-devenv shell
+yarn dev
 ```
 
-Within the `devenv shell` you have to browse to your DIVE folder
+This is particularly useful when working with the module system as it ensures your changes are
+immediately reflected in the build output.
+
+### Local Development with Yalc
+
+[Yalc](https://github.com/wclr/yalc) is the recommended way to test local changes in your project.
+It provides better dependency management and more reliable linking than npm link.
+
+First, install yalc globally if you haven't already:
 
 ```bash
-cd path/to/@shopware-ag/dive
+npm install -g yalc
 ```
 
-### without devenv
+Then, in your DIVE project directory:
 
-You don't have to do anything special if you don't use `devenv`.
+```bash
+# Publish the package to yalc's local store
+yalc publish
 
-### npm link
+# In your project that uses DIVE:
+yalc add @shopware-ag/dive
+```
 
-If you want to link DIVE package locally after checking out, you can to that in the package's project folder:
+When you make changes to DIVE, you'll need to:
 
 ```bash
-cd path/to/@shopware-ag/dive
-npm link
+# In DIVE directory:
+yalc push
+
+# Or if you want to republish:
+yalc publish --force
 ```
 
-After registering the package in npm, you can use the sym-link in your project:
+To remove the local package from your project:
 
 ```bash
-cd path/to/your/package.json
-npm link @shopware-ag/dive
+yalc remove @shopware-ag/dive
 ```
 
-After successfully linking DIVE into your project you will find the according sym-link in your `node_modules`.
+Benefits of using yalc:
+
+- Better dependency management
+- More reliable than npm link
+- Works well with package managers (npm, yarn, pnpm)
+- Maintains proper package.json dependencies
+- Supports multiple projects using the same local package
 
-## Setup in Shopware
+### Shopware Integration
 
 Don't forget to include DIVE in your `webpack.config.js`:
 
@@ -163,47 +225,54 @@ module.exports = () => {
 };
 ```
 
-## Usage
+### Testing and Quality Assurance
 
-### Quick View
+#### Unit Tests
 
-QuickView is used to quickly display your assets with as few lines of code as
-possible. Simply call the static `QuickView()` method, with your data URI as a
-parameter, to create an instance of DIVE with your asset to use in further code.
+All relevant files are covered by Jest tests. If you find any file that has not been covered yet,
+feel free to add unit tests accordingly.
 
-```ts
-import { DIVE } from '@shopware-ag/dive';
+If there are any modules that have to be mocked (like `three`) you can create a given file in the
+`__mocks__` folder in project root. Jest manages to mock modules with a given file with the modules
+name as a file name (for example `three.ts`). Every export will be part of the modules mock. You
+don't need to mock the module in your test anymore, you only extend the module mock.
 
-const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
+If you have any other things from a module to import, you can simply create a folder structure and
+place the mock file at the end of your structure. To understand better please take a look at the
+`__mocks__` folder for yourself.
 
-const myCanvasWrapper = document.createElement('div');
-myCanvasWrapper.appendChild(dive.Canvas);
-```
+#### Code Formatting
 
-### Example with Error Handling:
+DIVE uses Prettier as a preconfigured formatter.
+
+## Usage Guide
+
+### Core Concepts
+
+#### Quick View
+
+QuickView is used to quickly display your assets with as few lines of code as possible. Simply call
+the static `QuickView()` method, with your data URI as a parameter, to create an instance of DIVE
+with your asset to use in further code.
 
 ```ts
 import { DIVE } from '@shopware-ag/dive';
 
-try {
-    const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
+const dive = await DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
 
-    const myCanvasWrapper = document.createElement('div');
-    myCanvasWrapper.appendChild(dive.Canvas);
-} catch (error) {
-    console.error('Failed to load asset:', error);
-}
+const myCanvasWrapper = document.createElement('div');
+myCanvasWrapper.appendChild(dive.Canvas);
 ```
 
-### Getting started
+#### Getting Started
 
-#### Import:
+##### Import
 
 ```ts
 import { DIVE } from '@shopware-ag/dive'; // <-- import DIVE
 ```
 
-#### Instantiate:
+##### Instantiate
 
 ```ts
 import { DIVE } from '@shopware-ag/dive';
@@ -211,9 +280,8 @@ import { DIVE } from '@shopware-ag/dive';
 const dive = new DIVE(); // <-- instantiate DIVE
 ```
 
-DIVE supplies your application with a HTMLCanvasElement that it uses as a render
-target. After instantiating, you can use the supplied canvas within your frontend
-code to attach it to your DOM.
+DIVE supplies your application with a HTMLCanvasElement that it uses as a render target. After
+instantiating, you can use the supplied canvas within your frontend code to attach it to your DOM.
 
 ```ts
 const dive = new DIVE();
@@ -222,328 +290,193 @@ const myCanvasWrapper = document.createElement('div'); // <-- create wrapper ele
 myCanvasWrapper.appendChild(dive.Canvas); // <-- reference DIVE canvas
 ```
 
-To interact with your newly created DIVE instance you have to perform actions
-via DIVECommunication. For further information, see [Actions](#actions).
+### Modules
+
+DIVE comes with several built-in modules that provide specific functionality. You can access modules
+in two ways:
+
+1. Direct import from the modules directory (recommended for most use cases):
+
+```ts
+import { ARSystem } from '@shopware-ag/dive/modules/ar';
+
+// Initialize AR with options
+const arSystem = new ARSystem();
+await arSystem.launch('path/to/model.glb', {
+    arPlacement: 'horizontal', // or 'vertical'
+    arScale: 'auto' // or 'fixed'
+});
+```
+
+2. Through the DIVE instance (when you need to work with a specific DIVE instance):
 
 ```ts
+import { DIVE } from '@shopware-ag/dive';
+
+// Create a DIVE instance
 const dive = new DIVE();
 
-const myCanvasWrapper = document.createElement('div');
-myCanvasWrapper.appendChild(dive.Canvas);
+// Get a module instance from the DIVE instance
+const assetLoader = await dive.modules.get('AssetLoader');
+const model = await assetLoader.load('path/to/model.glb');
+```
 
-const com = dive.Communication; // <-- reference DIVECommunication
+### Modules (List)
 
-com.PerformAction('SET_CAMERA_TRANSFORM', {
-    // <-- perform action on DIVECommunication
-    position: { x: 0, y: 2, z: 2 },
-    target: { x: 0, y: 0.5, z: 0 },
+DIVE provides several specialized modules for different aspects of 3D content handling:
+
+#### ARSystem
+
+The AR module enables Augmented Reality features across different platforms:
+
+```ts
+import { ARSystem } from '@shopware-ag/dive/modules/ar';
+const arSystem = new ARSystem();
+
+// Launch AR with options
+await arSystem.launch('path/to/model.glb', {
+    arPlacement: 'horizontal', // or 'vertical'
+    arScale: 'auto' // or 'fixed'
 });
 ```
 
-### Actions
+Features:
+- Platform-specific AR implementations (ARQuickLook for iOS, SceneViewer for Android)
+- Automatic format conversion for AR compatibility
+- Configurable placement and scaling options
 
-Actions symbolize the communication between frontend and 3D space. All actions
-can be performed anywhere, no matter if you are in frontend or 3D.
+#### AssetConverter
 
-In addition to the impact that specific actions have, every action can be
-subscribed to.
+Converts between different 3D file formats:
 
 ```ts
-const myCanvasWrapper = document.createElement('div');
-const dive = new DIVE();
+import { AssetConverter } from '@shopware-ag/dive/modules/asset/converter';
+const assetConverter = new AssetConverter();
+const usdzBuffer = await assetConverter.convert('input.glb').to('usdz');
+```
 
-myCanvasWrapper.appendChild(dive.Canvas);
+#### AssetExporter
 
-const com = dive.Communication;
+Exports 3D assets to various formats:
 
-com.Subscribe('SET_CAMERA_TRANSFORM', () => {
-    // <-- add subscription
-    // do something
-});
+```ts
+import { AssetExporter } from '@shopware-ag/dive/modules/asset/exporter';
+const assetExporter = new AssetExporter();
+const buffer = await assetExporter.export(model, 'glb');
+```
 
-com.PerformAction('SET_CAMERA_TRANSFORM', {
-    position: { x: 0, y: 2, z: 2 },
-    target: { x: 0, y: 0.5, z: 0 },
-});
+#### AssetLoader
+
+Handles loading of 3D assets in various formats:
+
+```ts
+// Direct import
+import { AssetLoader } from '@shopware-ag/dive/modules/asset/loader';
+const assetLoader = new AssetLoader();
+const model = await assetLoader.load('path/to/model.glb');
+
+// Or through DIVE instance
+const assetLoader = await dive.modules.get('AssetLoader');
+const model = await assetLoader.load('path/to/model.glb');
 ```
 
-Subscribing to an action returns a `unsubscribe()`-callback that should be
-executed when not needed anymore.
+Supported formats:
+- GLB/GLTF
+- USDZ
+
+#### MediaCreator
+
+Provides tools for creating media content from the 3D scene:
 
 ```ts
-const myCanvasWrapper = document.createElement('div');
-const dive = new DIVE();
+import { MediaCreator } from '@shopware-ag/dive/modules/mediacreator';
+const mediaCreator = new MediaCreator();
+
+// Generate a screenshot
+const screenshot = await mediaCreator.GenerateMedia(
+    { x: 0, y: 0, z: 0 }, // camera position
+    { x: 0, y: 0, z: 0 }, // camera target
+    1920, // width
+    1080  // height
+);
+```
 
-myCanvasWrapper.appendChild(dive.Canvas);
+Features:
+- High-quality screenshot generation
+- Customizable camera position and target
+- Configurable output resolution
 
-const com = dive.Communication;
+#### SystemInfo
 
-const unsubscribe = com.Subscribe('SET_CAMERA_TRANSFORM', () => {
-    // <-- save unsubscribe callback
-    // do something
-});
+Provides information about the system's capabilities and performance:
 
+```ts
+import { SystemInfo } from '@shopware-ag/dive/modules/systeminfo';
+const systemInfo = new SystemInfo();
+
+// Get system information
+const system = systemInfo.getSystem(); // Returns ESystem enum (IOS, ANDROID, etc.)
+
+// Check AR capabilities
+const supportsAR = systemInfo.getSupportsAR();
+
+// Check device type
+const isMobile = systemInfo.isMobile;
+const isDesktop = systemInfo.isDesktop;
+```
+
+Features:
+- System detection (iOS, Android, Windows, etc.)
+- WebXR support detection
+- AR capability checking
+- Device type detection
+- SceneViewer support detection
+
+Each module is designed to be used independently, allowing you to use only the functionality you
+need. This helps keep your bundle size small and your application focused.
+
+### Actions
+
+Actions are the primary way to communicate between your frontend application and the 3D space in
+DIVE. They can be used to control various aspects of the 3D scene, such as camera movement, object
+manipulation, and scene state management.
+
+#### Basic Usage
+
+To perform an action, use the `DIVECommunication` instance:
+
+```ts
+const dive = new DIVE();
+const com = dive.Communication;
+
+// Perform an action
 com.PerformAction('SET_CAMERA_TRANSFORM', {
     position: { x: 0, y: 2, z: 2 },
     target: { x: 0, y: 0.5, z: 0 },
 });
+```
 
-unsubscribe(); // <-- execute unsubscribe callback when done
+#### Subscribing to Actions
+
+You can subscribe to actions to react to changes in the 3D space:
+
+```ts
+const unsubscribe = com.Subscribe('SET_CAMERA_TRANSFORM', (data) => {
+    console.log('Camera position changed:', data);
+});
+
+// Don't forget to unsubscribe when done
+unsubscribe();
 ```
 
 #### Actions List
 
-In the following you find a list of all available actions to perform on
-DIVECommunication class via
-[`com.PerformAction()`](https://github.com/shopware/dive/blob/2e193c58843939ce07a1d35bfbd5b3c9d26eeeca/src/com/Communication.ts#L85).
-
-<table>
-    <tr>
-        <th>Actions</th>
-        <th>Description</th>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/addobject.ts"> ADD_OBJECT </a>
-        </td>
-        <td>
-            Adds an object to the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/computeencompassingview.ts"> COMPUTE_ENCOMPASSING_VIEW </a>
-        </td>
-        <td>
-            Calculates the camera position and target to view the whole scene. (experimental)
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/deleteobject.ts"> DELETE_OBJECT </a>
-        </td>
-        <td>
-            Deletes an object from the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/deselectobject.ts"> DESELECT_OBJECT </a>
-        </td>
-        <td>
-            Deselects an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/dropit.ts"> DROP_IT </a>
-        </td>
-        <td>
-            Places an object on top of an underlying object or the floor.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/exportscene.ts"> EXPORT_SCENE </a>
-        </td>
-        <td>
-            Exports the current scene to a blob and returns the URL.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/media/generatemedia.ts"> GENERATE_MEDIA </a>
-        </td>
-        <td>
-            Generates a screenshot, stores it in a Blob and returns a Promise of a valid URI.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/getallobjects.ts"> GET_ALL_OBJECTS </a>
-        </td>
-        <td>
-            Retrieves all objects in the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/getallscenedata.ts"> GET_ALL_SCENE_DATA </a>
-        </td>
-        <td>
-            Retrieves all current scene data.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/getcameratransform.ts"> GET_CAMERA_TRANSFORM </a>
-        </td>
-        <td>
-            Returns the current camera position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/getobjects.ts"> GET_OBJECTS </a>
-        </td>
-        <td>
-            Returns a list of objects of given IDs.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/launchar.ts"> LAUNCH_AR </a>
-        </td>
-        <td>
-            Launches AR mode in native capabilities. (iOS: AR Quick Look, Android: Google Scene Viewer)
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/modelloaded.ts"> MODEL_LOADED </a>
-        </td>
-        <td>
-            Is triggered when a model is loaded.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/movecamera.ts"> MOVE_CAMERA </a>
-        </td>
-        <td>
-            Moves the camera to a new position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/placeonfloor.ts"> PLACE_ON_FLOOR </a>
-        </td>
-        <td>
-            Places an object on the floor.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/resetcamera.ts"> RESET_CAMERA </a>
-        </td>
-        <td>
-            Reset the camera to its initial position and rotation.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/selectobject.ts"> SELECT_OBJECT </a>
-        </td>
-        <td>
-            Selects an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/setbackground.ts"> SET_BACKGROUND </a>
-        </td>
-        <td>
-            Set the background color of the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/setcameralayer.ts"> SET_CAMERA_LAYER </a>
-        </td>
-        <td>
-            Sets the camera layer to a certain layer.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/setcameratransform.ts"> SET_CAMERA_TRANSFORM </a>
-        </td>
-        <td>
-            Sets the camera position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/select/setgizmomode.ts"> SET_GIZMO_MODE </a>
-        </td>
-        <td>
-            Sets the gizmo's mode.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/transform/setgizmoscalelinked.ts"> SET_GIZMO_SCALE_LINKED </a>
-        </td>
-        <td>
-            Sets the gizmo's unified scale mode.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/transform/setgizmovisible.ts"> SET_GIZMO_VISIBILITY </a>
-        </td>
-        <td>
-            Sets the gizmo's visibility.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/setparent.ts"> SET_PARENT </a>
-        </td>
-        <td>
-            Attach an object to another object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/renderer/startrender.ts"> START_RENDER </a>
-        </td>
-        <td>
-            Starts the render process.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/updateobject.ts"> UPDATE_OBJECT </a>
-        </td>
-        <td>
-            Updates an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/updatescene.ts"> UPDATE_SCENE </a>
-        </td>
-        <td>
-            Updates global scene data.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/usetool.ts"> USE_TOOL </a>
-        </td>
-        <td>
-            Activates a specific tool from the toolbox.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/zoomcamera.ts"> ZOOM_CAMERA </a>
-        </td>
-        <td>
-            Zooms the camera in or out by a certain amount.
-        </td>
-    </tr>
-</table>
-
-## Unit Tests
-
-All relevant files are covered by Jest tests. If you find any file that has not been covered yet, feel free to add unit tests accordingly.
-
-If there are any modules that have to be mocked (like `three`) you can create a given file in the `__mocks__` folder in project root. Jest manages to mock modules with a given file with the modules name as a file name (for example `three.ts`). Every export will be part of the modules mock. You don't need to mock the module in your test anymore, you only extend the module mock.
-
-If you have any other things from a module to import, you can simply create a folder structure and place the mock file at the end of your structure. To understand better please take a look at the `__mocks__` folder for yourself.
-
-## Formatting
+The following table lists all available actions in DIVE:
 
-DIVE uses Prettier as a preconfigured formatter.
+| Action | Description | Input | Return |
+|--------|-------------|-------|--------|
+
+
+
+Each action has specific parameters and return values. For detailed information about each action,
+refer to the TypeScript type definitions in the source code.