@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/getting-started/editor/scene-inspector.md

@@ -0,0 +1,64 @@
+# Scene Inspector
+
+The **Scene** tab in the inspector panel exposes scene wide singleton components settings that apply globally to the entire project rather than to a specific entity.
+
+## Opening the Scene tab
+
+Click the **Scene** tab at the top of the inspector (right panel). The Object tab shows the selected entity's components; the Scene tab always shows the same global settings regardless of selection.
+
+![Scene Inspector](/images/getting-started/editor/scene-inspector.gif)
+
+## Sections
+
+### Skybox
+
+Controls the background and ambient lighting of the scene.
+
+| Field | Description |
+| --- | --- |
+| **Mode** | `Gradient`, `Color`, or `Image`. |
+| **Top color / Bottom color** | Gradient stops (gradient mode). |
+| **Color** | Flat background color (color mode). |
+| **Intensity** | Ambient light contribution from the skybox. |
+
+<!-- | **Image** | HDR or equirectangular image path (image mode). | -->
+
+### Fog
+
+
+Adds atmospheric depth by fading distant objects toward a fog color.
+
+| Field | Description |
+| --- | --- |
+| **Enabled** | Toggle fog on or off. |
+| **Type** | `Linear` or `Exponential`. |
+| **Color** | Fog blend color. |
+| **Near / Far** | Start and end distances (linear mode). |
+| **Density** | Fog density exponent (exponential mode). |
+
+### Gravity
+
+Sets the global physics gravity vector applied to all dynamic rigidbodies.
+
+| Field | Description |
+| --- | --- |
+| **X / Y / Z** | Gravity direction and magnitude (m/s²). Default is `(0, -9.81, 0)`. |
+
+### Postprocessing
+
+Adds full-screen visual effects on top of the rendered frame.
+
+| Effect | Description |
+| --- | --- |
+| **Bloom** | Glowing halo around bright areas. |
+| **Depth of field** | Lens blur at a configurable focal distance. |
+| **Vignette** | Darkened corners. |
+| **Color grading** | Brightness, contrast, and saturation adjustments. |
+
+See [Scene → Postprocessing](../../scene/postprocessing) for field-level details.
+
+## Related
+
+- [Inspector](./inspector)
+- [Scene → Environment](../../scene/environment)
+- [Scene → Postprocessing](../../scene/postprocessing)

package/dist/docs/guide/getting-started/editor/toolbar.md

@@ -0,0 +1,39 @@
+# Toolbar
+
+The toolbar is the global header at the top of the editor window. It groups project-level actions on the left, viewport controls in the center, and history / publishing actions on the right.
+
+![Toolbar with Settings, Report, transform tools, preview, save and publish.](/images/getting-started/editor/toolbar.png)
+
+## Left group — project
+
+| Control | Action |
+| --- | --- |
+| ![Logo](/images/getting-started/editor/toolbar/logo.png) | Relu Spatial logo. Clicking this returns to the project dashboard. |
+| ![Shortcuts](/images/getting-started/editor/toolbar/shortcuts.png) | Opens the shortcuts modal (shows various keyboard shortcuts). |
+| ![Report](/images/getting-started/editor/toolbar/report.png) | Opens the in-app issue reporter. |
+
+## Center group — scene & preview
+
+| Control | Action |
+| --- | --- |
+| ![Transform tools](/images/getting-started/editor/toolbar/transform-tools.png) | Active manipulation mode (move / rotate / scale). Mirrors the gizmo shown on the selected entity. |
+| ![Add object](/images/getting-started/editor/toolbar/add-object.png) | Adds a new entity to the scene (cube, sphere, plane, light, camera, etc.). |
+| ![Preview](/images/getting-started/editor/toolbar/preview.png) | Launches the **preview runtime** in a separate window using the current saved snapshot. |
+
+## Right group — history & publishing
+
+| Control | Action |
+| --- | --- |
+| ![Undo](/images/getting-started/editor/toolbar/undo.png) | Reverts the last scene-affecting action. Bound to `Cmd/Ctrl + Z`. |
+| ![Redo](/images/getting-started/editor/toolbar/redo.png) | Re-applies the last undone action. Bound to `Cmd/Ctrl + Shift + Z`. |
+| ![Save](/images/getting-started/editor/toolbar/save.png) | Writes the current scene to disk. Bound to `Cmd/Ctrl + S`. |
+| ![Publish](/images/getting-started/editor/toolbar/publish.png) | Uploads the project to Relu and makes it shareable. |
+| ![Help](/images/getting-started/editor/toolbar/help.png) | Opens the in-app tour and links to this documentation. |
+
+> [!TIP]
+> Save and Publish are independent. You always need to **save** before previewing or publishing — preview/publish read the on-disk snapshot, not the in-memory state.
+
+## Related
+
+- [Keyboard shortcuts](../shortcuts)
+- [Viewport](./viewport)

package/dist/docs/guide/getting-started/editor/viewport.md

@@ -0,0 +1,43 @@
+# Viewport
+
+The viewport is the central live 3D view of your scene. You navigate the editor camera with the mouse and keyboard, and you transform entities with on-screen gizmos.
+
+![Viewport](/images/getting-started/editor/viewport.png)
+
+## Camera navigation
+
+| Input | Action |
+| --- | --- |
+| **Left mouse drag** | Orbit (look around). |
+| **Shift + Left mouse drag** | Pan. |
+| **Mouse wheel** | Zoom in / out. |
+| **`F`** | Focus on the selected entity. |
+
+The bottom-left **axis gizmo** shows the current orientation of the editor camera. Click an axis to snap the view to that direction.
+
+## Selecting
+
+- **Left-click** an object to select it.
+- **Click empty space** to deselect.
+- **`Esc`** also deselects.
+
+## Transform gizmos
+
+When an entity is selected, a gizmo appears at its origin. Switch the active mode from the [top bar](./toolbar) or with the keyboard:
+
+| Key | Mode |
+| --- | --- |
+| **`W`** | Move (translate) — _disabled while flying with right mouse held._ |
+| **`E`** | Rotate. |
+| **`R`** | Scale. |
+
+Drag a colored arrow / ring / handle to constrain the operation to that axis. Hold **`Shift`** while dragging to enable snapping.
+
+<!-- ## Editor-only helpers
+
+Some helpers are visible only while editing — wireframe colliders, light cones, camera frustums. They are tagged internally with `userData.ecsHelper` and are stripped from preview and publish builds, so they never affect runtime rendering. -->
+
+## Related
+
+- [Top bar](./toolbar) — transform tool buttons.
+- [Keyboard shortcuts](../shortcuts) — the full list.

package/dist/docs/guide/getting-started/first-launch.md

@@ -0,0 +1,17 @@
+# Launching the Editor for the First Time
+
+When you start Relu Spatial for the first time you will be prompted to sign in or create an account. Authentication uses your default web browser so the flow is the same as the web dashboard.
+
+## Sign in or sign up
+
+Click **Sign in** or **Sign up** on the welcome screen. Your default browser opens, you complete the flow there, and the browser redirects you back into the editor signed in.
+
+![Editor welcome screen — Sign in / Sign up](/images/getting-started/signin.png)
+
+## After signing in
+
+Once authentication succeeds, the editor opens the **Projects dashboard**. Before you can create or open a project, you must pick where projects live on disk see the next page.
+
+## Next
+
+- [Projects: choose a default folder and create or open a project](./projects)

package/dist/docs/guide/getting-started/index.md

@@ -0,0 +1,37 @@
+# Introduction
+
+**Relu Spatial** is a desktop first 3D editor and runtime for building interactive AR / VR / spatial experiences. It combines a visual scene editor with a TypeScript scripting API powered by an entity component system (ECS) runtime, so you can author scenes visually and drive them with code that runs the same way in preview and in production.
+
+You compose scenes from entities, meshes, lights, cameras, image targets, and custom prefabs and you bring them to life with `Behaviour` scripts that read input, query the world, and mutate components every frame.
+
+![Full editor window — hierarchy, viewport, inspector, asset browser, and toolbar](/images/getting-started/editor-overview.png)
+
+## What you can build
+
+- **Image-tracking** experiences that anchor 3D content to printed images.
+- **Face-tracking** filters that follow facial features.
+- **3D**, and **VR / AR** scenes.
+- Standalone web deployable spatial scenes.
+
+## How the pieces fit together
+
+| Layer | What it does |
+| --- | --- |
+| **Editor** | Desktop application where you author scenes, import assets, and configure components. |
+| **Runtime** (npm package `@relu-interactives/spatial-ecs`) | The ECS engine that powers both the editor's preview and your published builds. |
+| **Behaviours** | Your TypeScript scripts attached to entities, dispatched every frame by the runtime. |
+
+<!-- ## Where to next -->
+
+<!-- Continue with the rest of this guide in order:
+
+1. [Installation](./installation) — download the editor and check requirements.
+2. [Launching the editor for the first time](./first-launch) — sign up or log in.
+3. [Projects](./projects) — pick a default folder, create or open a project.
+4. [Project types](./project-types/) — choose the right project for your experience.
+5. [Understanding the editor](./editor/) — hierarchy, toolbar, inspector, asset browser, environment view.
+6. [Creating objects](./creating-objects) — add entities to your scene.
+7. [Editing inspector values](./editing-objects) — tune transforms, materials, lights, scripts.
+8. [Preview and test](./preview-and-test) — run your project in the runtime preview. -->
+<!-- 
+After Getting Started, dive into [Concepts](../concepts), [Custom Behaviours](../authoring-a-behaviour), and the [Component Catalog](../component-catalog). -->

package/dist/docs/guide/getting-started/installation.md

@@ -0,0 +1,59 @@
+# Installation
+
+The Relu Spatial editor is distributed as a desktop application for macOS, Windows, and Linux.
+
+## Download
+
+Get the latest installer from the official downloads page:
+
+[**reluspatial.com/downloads**](https://reluspatial.com/downloads)
+
+![Download Page Image](/images/getting-started/installation/download-page.png)
+
+## System requirements
+
+| Requirement | Minimum | Recommended |
+| --- | --- | --- |
+| OS | macOS 12, Windows 10, Ubuntu 22.04 | macOS 14+, Windows 11, Ubuntu 24.04 |
+| CPU | 4-core x64 / Apple Silicon | 8-core x64 / Apple Silicon (M2 or newer) |
+| RAM | 8 GB | 16 GB+ |
+| GPU | WebGL2-capable, 1 GB VRAM | Dedicated GPU with 4 GB+ VRAM |
+| Storage | 2 GB free | 10 GB+ free for asset-heavy projects |
+| Display | 1440 × 900 | 1920 × 1080 or higher |
+
+> [!IMPORTANT]
+> The editor uses GPU-accelerated rendering for the viewport and image-target compilation. Integrated graphics work for simple scenes but are noticeably slower on large models or postprocessing-heavy environments.
+
+## Platform-specific notes
+
+### macOS
+
+1. Open the downloaded `.dmg`.
+2. Drag **Relu Spatial** into your `Applications` folder.
+3. The first launch prompts macOS Gatekeeper open **System Settings → Privacy & Security** and click **Open Anyway** if needed.
+
+ ![Macos Installation](/images/getting-started/installation/install-macos.png)
+
+
+### Windows
+
+1. Run the downloaded `.exe` installer.
+2. Follow the wizard to choose an install location.
+3. Allow Relu Spatial through Windows SmartScreen on first launch if prompted.
+
+ ![Windows Installation](/images/getting-started/installation/install-windows.png)
+
+<!-- ### Linux
+
+1. Download the `.AppImage` (or `.deb` / `.rpm` if provided).
+2. Make it executable: `chmod +x ReluSpatial-*.AppImage`.
+3. Double-click or run from a terminal.
+
+::: info Screenshot placeholder
+Linux AppImage launching.
+_Image: `images/getting-started/install-linux.png`_
+::: -->
+
+## Next
+
+Once installed, continue to [Launching the editor for the first time](./first-launch).

package/dist/docs/guide/getting-started/preview-and-test.md

@@ -0,0 +1,55 @@
+# Preview and Test
+
+The editor ships with a runtime preview so you can test your scene without leaving the desktop app. Preview runs the same `@relu-interactives/spatial-ecs` engine that powers your published builds, so what you see is what users will get.
+
+## Starting a preview
+
+Click the **Preview** button in the [toolbar](./editor/toolbar). The editor saves the current scene, spins up a local runtime server, and opens a preview window.
+
+![Previewing scene](/images/getting-started/preview-and-test/preview.gif)
+
+## What runs in preview
+
+- All systems from the runtime including animation, physics, scripts, rendering.
+- Every `Behaviour` script you've authored, compiled in real time.
+- Project type specific runtimes (image tracking, face tracking, WebXR sessions where applicable).
+
+## Stopping a preview
+
+Click **Preview** again (it switches to **Stop preview**). The editor returns to authoring mode and the runtime server shuts down.
+
+## Hot-reload caveats
+
+Preview is **not** a live link to the editor. To see changes:
+
+1. Edit in the editor.
+2. **Save** the project (⌘S / Ctrl+S).
+3. **Restart preview**.
+
+> [!TIP]
+> Most preview iteration is fastest by keeping the preview window visible alongside the editor and restarting it after each significant change.
+
+## Testing on devices
+
+For project types that need real device sensors (image tracking, face tracking, AR, VR) the desktop preview only goes so far. Use these strategies:
+
+- **Image / face tracking:** desktop preview can use your laptop camera. For phone camera quality, publish a draft build and open it on the target device.
+- **WebXR (AR / VR):** publish a draft and open it on a headset or AR capable phone over your local network or via a tunnel like [ngrok](https://ngrok.com).
+
+## Common preview issues
+
+| Symptom | Likely cause |
+| --- | --- |
+| Preview button does nothing | Save failed check for unsaved errors or read-only project folder. |
+| Black viewport | No camera in scene, or camera's clear color matches scene fog. |
+| Scripts don't run | Compile error check the editor footer for compile output. |
+| Image targets don't track | Targets weren't recompiled after upload. Open the compile modal and re-run. |
+
+## Next
+
+You're done with **Getting Started**. Continue with:
+
+- [Concepts](../concepts) — how the ECS runtime is organized.
+- [Custom Behaviours](../authoring-a-behaviour) — write scripts.
+- [Component Catalog](../component-catalog) — full component reference.
+- [World API](../world-api) — query and mutate the runtime from scripts.

package/dist/docs/guide/getting-started/project-types/3d.md

@@ -0,0 +1,30 @@
+# 3D
+
+A **3D** project is a plain interactive 3D scene without any tracking or immersive session. It renders into a regular canvas perfect for games, product viewers, configurators, embedded scenes, dashboards, and any web-deployable 3D experience.
+
+![3D project preview showing an interactive scene rendered in the viewport.](/images/getting-started/project-types/3d/3d.gif)
+
+## What's different in this project type
+
+- The default scene includes a **perspective camera** with orbit controls and basic lighting.
+- The runtime renders into a standard canvas with no WebXR session, no device camera, no tracker bootstrap.
+- Postprocessing is available; tracking-related panels (image targets, face anchors, hit-test) are hidden.
+- Output is suited for embedding on the web or shipping inside another app.
+
+## Workflow
+
+1. **Add scene content:** meshes, models, lights, cameras.
+2. **Tune the environment:** skybox, fog, lighting (see [Scene Inspector](../editor/scene-inspector)).
+3. **Wire up scripts:** pointer interactions, animations, UI logic via `Behaviour` scripts.
+4. **Preview:** runs in the editor's preview window using a standard 3D camera rig.
+
+## Tips
+
+- Pick this type when you want a 3D experience without AR/VR overhead.
+- Combine with orbit / pan / zoom behaviours for product-viewer use cases.
+- Postprocessing has a runtime cost — disable it for low-end targets.
+
+## Related
+
+- [Custom Behaviours](../../authoring-a-behaviour) — interactive scripts.
+- [Component Catalog](../../component-catalog).

package/dist/docs/guide/getting-started/project-types/ar.md

@@ -0,0 +1,6 @@
+# AR
+
+::: warning Coming Soon
+AR (world-space augmented reality) project support is planned for a future release. Documentation will be published when the feature is available.
+:::
+

package/dist/docs/guide/getting-started/project-types/face-tracking.md

@@ -0,0 +1,6 @@
+# Face Tracking
+
+::: warning Coming Soon
+Face Tracking project support is planned for a future release. Documentation will be published when the feature is available.
+:::
+

package/dist/docs/guide/getting-started/project-types/image-tracking.md

@@ -0,0 +1,42 @@
+# Image Tracking
+
+An **Image Tracking** project anchors 3D content to a printed or on-screen image. When the runtime detects a registered image target through the camera, it places the matching anchor entity at that target's position and orientation.
+
+Use this for posters, business cards, product packaging, museum exhibits, and any AR experience tied to a printed surface.
+
+![Image Tracking Example Preview](/images/getting-started/project-types/image-tracking/image-tracking.gif)
+
+
+
+## What's different in this project type
+
+When you open an image-tracking project, the editor changes in three ways:
+
+1. **Image targets are first-class entities** in the hierarchy. Each anchor represents one image and contains the children that should appear when that image is detected.
+2. **A floating Compile Targets button** appears in the viewport overlay. It opens the **image compilation modal** which packages your image targets into a binary the runtime can load.
+3. **The Image Targets panel** lives in the inspector when an image-target entity is selected. From there you upload reference images, set physical sizes, and preview tracking quality.
+
+![Image Target Compile Modal](/images/getting-started/project-types/image-tracking/image-tracking-compile-modal.gif)
+
+## Workflow
+
+1. **Add an Image Target entity** from the toolbar `+` menu (or hierarchy panel). The editor creates an image-target anchor at the scene root.
+2. **Select the anchor** and use the **Image Targets panel** in the inspector to upload one or more reference images. For each, set its real-world physical width.
+3. **Add child entities** under the anchor. Anything you parent to it becomes visible only when that image is detected.
+4. **Compile targets** — click the floating **Compile Targets** button in the viewport. The compilation modal runs through tracker quality analysis and writes the compiled binary into `bin/targets/`.
+5. **Preview** — press the preview button. The runtime loads the compiled targets and starts the device camera.
+
+![Image Target Panel](/images/getting-started/project-types/image-tracking/image-tracking-panel.gif)
+
+
+## Tips
+
+- High-contrast, feature-rich images track best. Photos of faces, gradients, and large flat colors are weak targets.
+- Keep the **physical size** field accurate — this is what the runtime uses to scale your 3D content to the printed image.
+- Children of an image-target anchor inherit its transform. Position objects in **local space** relative to the anchor, not world space.
+- Recompile targets whenever you add or change reference images.
+
+## Related
+
+- [Component Catalog → Image Target](../../component-catalog) — runtime component reference.
+- [Spawning → Image Target](../../spawning/image-target) — spawning anchors from scripts.

package/dist/docs/guide/getting-started/project-types/index.md

@@ -0,0 +1,25 @@
+# Project Types
+
+When you create a new project the editor asks for a **project type**. The type determines:
+
+- the **default scene** seeded into the project,
+- which **components and panels** are available in the inspector,
+- how the **runtime** initializes the camera, tracking, and rendering pipeline,
+- which **publish targets** are valid.
+
+You can't change a project's type after creation, so pick the one that matches the experience you intend to ship.
+
+## Available project types
+
+| Type | Best for |
+| --- | --- |
+| [Image Tracking](./image-tracking) | AR experiences anchored to printed images, posters, or product packaging. |
+| [3D](./3d) | Plain interactive 3D scenes, games, product viewers, configurators, embedded experiences. |
+| [Face Tracking](./face-tracking) | Face filters, avatars, and try-on experiences. *(Coming Soon)* |
+| [VR](./vr) | Fully immersive virtual reality scenes for headsets. *(Coming Soon)* |
+| [AR](./ar) | World-space augmented reality without a specific anchor. *(Coming Soon)* |
+
+![Project Types.](/images/getting-started/projects-new-dialog.png)
+
+> [!TIP]
+> If you're not sure, start with **3D** — it has the simplest scene setup with no tracking or device requirements. You can always create a second project to try a tracking-based or immersive type.

package/dist/docs/guide/getting-started/project-types/vr.md

@@ -0,0 +1,6 @@
+# VR
+
+::: warning Coming Soon
+VR (immersive virtual reality) project support is planned for a future release. Documentation will be published when the feature is available.
+:::
+

package/dist/docs/guide/getting-started/projects.md

@@ -0,0 +1,53 @@
+# Projects
+
+After signing in for the first time, the editor needs to know where to store your projects on disk. From the dashboard you can then create new projects or open existing ones.
+
+## Choose a default projects folder
+
+The first time you open the dashboard you'll see a prompt to pick a **projects folder**. This is the directory where every project you create or open lives.
+
+![Dashboard prompt asking the user to select a projects folder.](/images/getting-started/projects-folder-prompt.png)
+
+![Dashboard prompt asking the user to select a projects folder.](/images/getting-started/projects-folder-selection.png)
+
+1. Click **Select folder**.
+2. Pick a location in your file system: for example `~/Documents/ReluSpatial` on macOS / Linux, or `Documents\ReluSpatial` on Windows.
+3. The editor remembers this path for every future session.
+
+You can change it later from **Settings → Projects path**.
+
+## Project files on disk
+
+Each project is a folder under your projects path.
+
+> [!TIP]
+> The `assets/` folder is yours to organize. Drop models, images, audio, video, and scripts in here directly they appear in the editor's [asset browser](./editor/assets-browser) automatically.
+
+## Create a new project
+
+From the dashboard, click **New project**.
+
+![New project Dialog.](/images/getting-started/projects-new-dialog.png)
+
+
+You'll be asked for:
+
+- **Project name:** used to derive the folder slug.
+- **Project type:** see [Project types](./project-types/) for the differences.
+
+Click **Create**. The editor scaffolds the project, opens it, and seeds the default scene for the chosen project type.
+
+## Open an existing project
+
+The dashboard lists every project found in your projects folder.
+
+![Project List.](/images/getting-started/projects-list.png)
+
+
+- **Click a card** to open the project in the editor.
+- **Click card options:** for actions: rename, duplicate, reveal in finder/explorer, delete.
+
+## Next
+
+- [Project types](./project-types/) — pick the right type for your experience.
+- [Understanding the editor](./editor/) — what each region of the editor window does.

package/dist/docs/guide/getting-started/shortcuts.md

@@ -0,0 +1,43 @@
+# Keyboard Shortcuts
+
+The editor supports keyboard shortcuts for common actions. You can also open the shortcuts panel at any time by clicking the **keyboard icon** in the top-right corner of the navbar (next to the logo).
+
+## Navigation
+
+| Shortcut | Action |
+| --- | --- |
+| `F` | Focus camera on selected object |
+| `Shift+F` | Frame selected object (zoom to fit) |
+
+## Transform Gizmos
+
+| Shortcut | Action |
+| --- | --- |
+| `W` | Switch to **Translate** gizmo |
+| `E` | Switch to **Scale** gizmo |
+| `R` | Switch to **Rotate** gizmo |
+
+## Selection
+
+| Shortcut | Action |
+| --- | --- |
+| `Esc` | Clear active selection |
+| `Del` / `Backspace` | Delete selected object |
+| `⌘+D` / `Ctrl+D` | Duplicate selected object |
+
+## History
+
+| Shortcut | Action |
+| --- | --- |
+| `⌘+Z` / `Ctrl+Z` | Undo last action |
+| `⌘+Shift+Z` / `Ctrl+Y` | Redo last undone action |
+
+## Project
+
+| Shortcut | Action |
+| --- | --- |
+| `⌘+S` / `Ctrl+S` | Save project |
+
+::: tip macOS vs Windows/Linux
+Shortcuts that show `⌘` apply to macOS. Use `Ctrl` in their place on Windows.
+:::