From 2f2412c857903b3033404f4d2ccc4bb83ca32507 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Mon, 11 May 2026 11:31:05 -0500
Subject: [PATCH 01/12] Mesh hit testing

---
 Axiom/Session/MeshPicking.h       | 97 +++++++++++++++++++++++++++++++
 Editor/GlfwEditorLayer.cpp        | 32 ++++++++++
 Editor/GlfwEditorLayer.h          |  1 +
 Headless/RemoteViewportServer.cpp | 91 ++++++++++++++++-------------
 4 files changed, 182 insertions(+), 39 deletions(-)
 create mode 100644 Axiom/Session/MeshPicking.h

diff --git a/Axiom/Session/MeshPicking.h b/Axiom/Session/MeshPicking.h
new file mode 100644
index 00000000..aed422bb
--- /dev/null
+++ b/Axiom/Session/MeshPicking.h
@@ -0,0 +1,97 @@
+#pragma once
+
+#include <Renderer/Camera.h>
+#include <Session/EditorSession.h>
+
+#include <glm/glm.hpp>
+#include <glm/gtc/matrix_inverse.hpp>
+
+#include <algorithm>
+#include <limits>
+#include <string>
+#include <vector>
+
+namespace Axiom {
+
+// Returns the ObjectId of the closest mesh instance hit by a ray cast from the
+// camera through MousePixel, or an empty string if no mesh is hit. Uses AABB
+// slab intersection in object space to handle arbitrary transforms correctly.
+inline std::string HitTestMeshes(const Camera &Cam, uint32_t VpWidth,
+                                  uint32_t VpHeight, glm::vec2 MousePixel,
+                                  const std::vector<EditorSceneMeshInstance> &Instances) {
+  if (VpWidth == 0 || VpHeight == 0 || Instances.empty()) {
+    return {};
+  }
+
+  const glm::vec3 RayOrigin = Cam.GetPosition();
+  const float NdcX = (MousePixel.x / static_cast<float>(VpWidth)) * 2.0f - 1.0f;
+  const float NdcY = (MousePixel.y / static_cast<float>(VpHeight)) * 2.0f - 1.0f;
+  const glm::vec4 WorldH =
+      glm::inverse(Cam.GetViewProjectionMatrix()) * glm::vec4(NdcX, NdcY, 0.0f, 1.0f);
+  const glm::vec3 WorldPt = glm::vec3(WorldH) / WorldH.w;
+  const glm::vec3 RayDir = glm::normalize(WorldPt - RayOrigin);
+
+  float BestT = std::numeric_limits<float>::infinity();
+  std::string BestId;
+
+  for (const EditorSceneMeshInstance &Instance : Instances) {
+    if (Instance.Mesh.BoundsMin == Instance.Mesh.BoundsMax) {
+      continue;
+    }
+
+    const glm::mat4 InvT = glm::inverse(Instance.Transform);
+    const glm::vec3 LocalOrigin = glm::vec3(InvT * glm::vec4(RayOrigin, 1.0f));
+    const glm::vec3 LocalDirRaw = glm::vec3(InvT * glm::vec4(RayDir, 0.0f));
+    const float LocalDirLen = glm::length(LocalDirRaw);
+    if (LocalDirLen < 1e-6f) {
+      continue;
+    }
+    const glm::vec3 LocalDir = LocalDirRaw / LocalDirLen;
+
+    const glm::vec3 &BMin = Instance.Mesh.BoundsMin;
+    const glm::vec3 &BMax = Instance.Mesh.BoundsMax;
+    float TMin = 0.0f;
+    float TMax = std::numeric_limits<float>::infinity();
+    bool Miss = false;
+
+    for (int Axis = 0; Axis < 3; ++Axis) {
+      const float D = LocalDir[Axis];
+      const float O = LocalOrigin[Axis];
+      if (glm::abs(D) < 1e-8f) {
+        if (O < BMin[Axis] || O > BMax[Axis]) {
+          Miss = true;
+          break;
+        }
+      } else {
+        const float InvD = 1.0f / D;
+        float T1 = (BMin[Axis] - O) * InvD;
+        float T2 = (BMax[Axis] - O) * InvD;
+        if (T1 > T2) {
+          std::swap(T1, T2);
+        }
+        TMin = std::max(TMin, T1);
+        TMax = std::min(TMax, T2);
+        if (TMin > TMax) {
+          Miss = true;
+          break;
+        }
+      }
+    }
+    if (Miss || TMax < 0.0f) {
+      continue;
+    }
+
+    const float LocalT = (TMin >= 0.0f) ? TMin : TMax;
+    const glm::vec3 WorldHit = glm::vec3(
+        Instance.Transform * glm::vec4(LocalOrigin + LocalT * LocalDir, 1.0f));
+    const float WorldT = glm::dot(WorldHit - RayOrigin, RayDir);
+    if (WorldT > 0.0f && WorldT < BestT) {
+      BestT = WorldT;
+      BestId = Instance.ObjectId;
+    }
+  }
+
+  return BestId;
+}
+
+} // namespace Axiom
diff --git a/Editor/GlfwEditorLayer.cpp b/Editor/GlfwEditorLayer.cpp
index 0b25b9ba..9fcf7199 100644
--- a/Editor/GlfwEditorLayer.cpp
+++ b/Editor/GlfwEditorLayer.cpp
@@ -5,7 +5,11 @@
 #include <Core/Window.h>
 #include <Core/WindowInputPlatform.h>
 
+#define GLFW_INCLUDE_NONE
+#include <GLFW/glfw3.h>
+
 #include <Renderer/RenderCommand.h>
+#include <Session/MeshPicking.h>
 #include <Session/StartupScene.h>
 
 namespace Axiom {
@@ -43,6 +47,34 @@ void GlfwEditorLayer::OnUpdate() {
     });
   }
   m_Session.Tick();
+
+  // Left-click mesh picking — detect rising edge to select on click, not hold.
+  {
+    const bool IsLeftDown = m_WindowInputPlatform != nullptr &&
+        m_WindowInputPlatform->IsMouseButtonPressed(GLFW_MOUSE_BUTTON_LEFT);
+    const bool ClickedNow = IsLeftDown && !m_LastLeftMouseDown;
+    m_LastLeftMouseDown = IsLeftDown;
+
+    if (ClickedNow && Viewport != nullptr && !Viewport->IsLooking) {
+      const Window *Win = Application::Get().GetWindow();
+      if (Win != nullptr) {
+        const glm::dvec2 CursorPos = m_WindowInputPlatform->GetCursorPosition();
+        const std::string HitId = HitTestMeshes(
+            Viewport->Camera, Win->GetWidth(), Win->GetHeight(),
+            glm::vec2(CursorPos), m_Session.GetState().Scene.MeshInstances);
+        if (!HitId.empty()) {
+          const CommandContext Ctx{
+              .Session = m_SessionId,
+              .User = m_LocalUserId,
+              .FrameIndex = Application::Get().GetFrameIndex(),
+              .DeltaTimeSeconds = Application::Get().GetDeltaTime(),
+          };
+          m_Session.Submit(Ctx, EditorCommand{SelectObjectCommand{.ObjectId = HitId}});
+        }
+      }
+    }
+  }
+
   if (m_InputSource != nullptr) {
     m_InputSource->SyncViewport(m_Session.FindViewport(m_LocalUserId));
   }
diff --git a/Editor/GlfwEditorLayer.h b/Editor/GlfwEditorLayer.h
index 730d1209..09e5984d 100644
--- a/Editor/GlfwEditorLayer.h
+++ b/Editor/GlfwEditorLayer.h
@@ -27,5 +27,6 @@ class GlfwEditorLayer final : public Layer {
   std::unique_ptr<IInputPlatform> m_WindowInputPlatform;
   std::unique_ptr<IEditorInputSource> m_InputSource;
   float m_MoveSpeed{3.5f};
+  bool m_LastLeftMouseDown{false};
 };
 } // namespace Axiom
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index 98d32be4..de592779 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -8,6 +8,7 @@
 
 #include "GizmoHitTest.h"
 #include "HeadlessCommandProtocol.h"
+#include <Session/MeshPicking.h>
 #include <Renderer/VideoEncoderFactory.h>
 #include <stb_image.h>
 #define STB_IMAGE_WRITE_IMPLEMENTATION
@@ -2001,52 +2002,64 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
         m_Host.GetHeadlessLayer().GetSession();
     const EditorViewportState *Viewport =
         Session.FindViewport(Client->User);
+    if (Viewport == nullptr) {
+      return true;
+    }
     const EditorObjectDetails *Selected =
         Session.FindSelectedObjectDetails(Client->User);
     const auto *DragTD = (Selected != nullptr && Selected->SupportsTransform)
         ? (Selected->WorldTransform.has_value() ? &*Selected->WorldTransform
                : (Selected->Transform.has_value() ? &*Selected->Transform : nullptr))
         : nullptr;
-    if (Viewport == nullptr || DragTD == nullptr) {
-      return true;
-    }
-    const glm::vec3 &ObjPos = DragTD->Location;
-    const float GizmoScale = ComputeGizmoScale(
-        Viewport->Camera, ObjPos, m_Options.Width, m_Options.Height);
-    if (Client->CurrentGizmoMode == GizmoMode::Rotate) {
-      auto DragState = BeginGizmoRotateDrag(
-          Viewport->Camera, m_Options.Width, m_Options.Height,
-          Command->MousePosition, ObjPos, GizmoScale, ObjPos);
-      if (!DragState.has_value()) {
-        return true;
-      }
-      Client->GizmoDrag = ActiveGizmoDrag{
-          .Math = *DragState,
-          .ObjectId = Selected->ObjectId,
-          .StartRotDeg = DragTD->RotationDegrees,
-          .StartScale = DragTD->Scale,
-          .Mode = GizmoMode::Rotate,
-          .GizmoScaleAtDragStart = GizmoScale,
-      };
-      Session.AcquireLock(Selected->ObjectId, Client->User);
-      m_Host.GetHeadlessLayer().SetGizmoHoveredAxis(Client->User, DragState->Axis);
-    } else {
-      auto DragState = BeginGizmoDrag(
-          Viewport->Camera, m_Options.Width, m_Options.Height,
-          Command->MousePosition, ObjPos, GizmoScale, ObjPos);
-      if (!DragState.has_value()) {
-        return true;
+
+    if (DragTD != nullptr) {
+      const glm::vec3 &ObjPos = DragTD->Location;
+      const float GizmoScale = ComputeGizmoScale(
+          Viewport->Camera, ObjPos, m_Options.Width, m_Options.Height);
+      if (Client->CurrentGizmoMode == GizmoMode::Rotate) {
+        auto DragState = BeginGizmoRotateDrag(
+            Viewport->Camera, m_Options.Width, m_Options.Height,
+            Command->MousePosition, ObjPos, GizmoScale, ObjPos);
+        if (DragState.has_value()) {
+          Client->GizmoDrag = ActiveGizmoDrag{
+              .Math = *DragState,
+              .ObjectId = Selected->ObjectId,
+              .StartRotDeg = DragTD->RotationDegrees,
+              .StartScale = DragTD->Scale,
+              .Mode = GizmoMode::Rotate,
+              .GizmoScaleAtDragStart = GizmoScale,
+          };
+          Session.AcquireLock(Selected->ObjectId, Client->User);
+          m_Host.GetHeadlessLayer().SetGizmoHoveredAxis(Client->User, DragState->Axis);
+          return true;
+        }
+      } else {
+        auto DragState = BeginGizmoDrag(
+            Viewport->Camera, m_Options.Width, m_Options.Height,
+            Command->MousePosition, ObjPos, GizmoScale, ObjPos);
+        if (DragState.has_value()) {
+          Client->GizmoDrag = ActiveGizmoDrag{
+              .Math = *DragState,
+              .ObjectId = Selected->ObjectId,
+              .StartRotDeg = DragTD->RotationDegrees,
+              .StartScale = DragTD->Scale,
+              .Mode = Client->CurrentGizmoMode,
+              .GizmoScaleAtDragStart = GizmoScale,
+          };
+          Session.AcquireLock(Selected->ObjectId, Client->User);
+          m_Host.GetHeadlessLayer().SetGizmoHoveredAxis(Client->User, DragState->Axis);
+          return true;
+        }
       }
-      Client->GizmoDrag = ActiveGizmoDrag{
-          .Math = *DragState,
-          .ObjectId = Selected->ObjectId,
-          .StartRotDeg = DragTD->RotationDegrees,
-          .StartScale = DragTD->Scale,
-          .Mode = Client->CurrentGizmoMode,
-          .GizmoScaleAtDragStart = GizmoScale,
-      };
-      Session.AcquireLock(Selected->ObjectId, Client->User);
-      m_Host.GetHeadlessLayer().SetGizmoHoveredAxis(Client->User, DragState->Axis);
+    }
+
+    // No gizmo hit — fall back to mesh picking.
+    const std::string HitId = HitTestMeshes(
+        Viewport->Camera, m_Options.Width, m_Options.Height,
+        Command->MousePosition, Session.GetState().Scene.MeshInstances);
+    if (!HitId.empty()) {
+      m_Host.SubmitRemoteCommand(Client->User,
+          EditorCommand{SelectObjectCommand{.ObjectId = HitId}});
     }
     return true;
   }

From 416ea1affc38fc526aed68c689047eb8fbcdcabb Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 00:38:20 -0500
Subject: [PATCH 02/12] Drag and drop textures onto meshes

---
 .../components/engine/content-browser.tsx     | 12 ++++++
 EditorFrontend/components/engine/viewport.tsx | 43 ++++++++++++++++++-
 Headless/HeadlessCommandProtocol.cpp          | 20 +++++++++
 Headless/HeadlessCommandProtocol.h            |  1 +
 Headless/RemoteViewportServer.cpp             | 36 ++++++++++++++++
 5 files changed, 110 insertions(+), 2 deletions(-)

diff --git a/EditorFrontend/components/engine/content-browser.tsx b/EditorFrontend/components/engine/content-browser.tsx
index 1d768ede..dd96edd4 100644
--- a/EditorFrontend/components/engine/content-browser.tsx
+++ b/EditorFrontend/components/engine/content-browser.tsx
@@ -444,6 +444,12 @@ export function ContentBrowser() {
                       e.dataTransfer.setData("axiom/asset-path", asset.path)
                       e.dataTransfer.setData("axiom/asset-kind", asset.kind)
                       e.dataTransfer.effectAllowed = "copy"
+                      ;(window as any).__axiomDragAsset = { kind: asset.kind, path: asset.path }
+                    }}
+                    onDragEnd={(e) => {
+                      ;(window as any).__axiomDragAsset = null
+                      const h = (window as any).__axiomViewportDropHandler
+                      if (h) h(e.clientX, e.clientY, asset.kind, asset.path)
                     }}
                     title={
                       canAssignToSelection && asset.kind === "mesh"
@@ -496,6 +502,12 @@ export function ContentBrowser() {
                       e.dataTransfer.setData("axiom/asset-path", asset.path)
                       e.dataTransfer.setData("axiom/asset-kind", asset.kind)
                       e.dataTransfer.effectAllowed = "copy"
+                      ;(window as any).__axiomDragAsset = { kind: asset.kind, path: asset.path }
+                    }}
+                    onDragEnd={(e) => {
+                      ;(window as any).__axiomDragAsset = null
+                      const h = (window as any).__axiomViewportDropHandler
+                      if (h) h(e.clientX, e.clientY, asset.kind, asset.path)
                     }}
                     title={
                       canAssignToSelection && asset.kind === "mesh"
diff --git a/EditorFrontend/components/engine/viewport.tsx b/EditorFrontend/components/engine/viewport.tsx
index d737d285..7612495e 100644
--- a/EditorFrontend/components/engine/viewport.tsx
+++ b/EditorFrontend/components/engine/viewport.tsx
@@ -201,6 +201,12 @@ type RemoteViewportCommand =
       objectId: string
       textureAssetPath: string
     }
+  | {
+      type: "drop_texture"
+      mouseX: number
+      mouseY: number
+      textureAssetPath: string
+    }
 
 function getServerOrigin() {
   const configuredOrigin = process.env.NEXT_PUBLIC_AXIOM_SERVER_ORIGIN?.trim()
@@ -1787,8 +1793,37 @@ export function Viewport() {
       void destroyPeerConnection("page_unload")
     }
 
+    let lastDragX = 0
+    let lastDragY = 0
+
+    const handleDocDragOver = (event: DragEvent) => {
+      lastDragX = event.clientX
+      lastDragY = event.clientY
+    }
+
+    ;(window as any).__axiomViewportDropHandler = (clientX: number, clientY: number, kind: string, path: string) => {
+      if (kind !== "texture" || !path) return
+      const x = lastDragX || clientX
+      const y = lastDragY || clientY
+      const s = viewportShellRef.current
+      const v = videoRef.current
+      if (!s || !v || !v.videoWidth || !v.videoHeight) return
+      const rect = s.getBoundingClientRect()
+      if (x < rect.left || x > rect.right || y < rect.top || y > rect.bottom) return
+      const scale = Math.min(rect.width / v.videoWidth, rect.height / v.videoHeight)
+      const contentW = v.videoWidth * scale
+      const contentH = v.videoHeight * scale
+      const cssX = x - rect.left - (rect.width - contentW) / 2
+      const cssY = y - rect.top - (rect.height - contentH) / 2
+      if (cssX < 0 || cssY < 0 || cssX > contentW || cssY > contentH) return
+      const mouseX = (cssX / contentW) * v.videoWidth
+      const mouseY = (cssY / contentH) * v.videoHeight
+      void sendCommand({ type: "drop_texture", mouseX, mouseY, textureAssetPath: path }, "reliable")
+    }
+
     video?.addEventListener("loadedmetadata", handleLoadedMetadata)
     video?.addEventListener("resize", handleResize)
+    document.addEventListener("dragover", handleDocDragOver)
     document.addEventListener("mousedown", handleMouseDown)
     document.addEventListener("mouseup", handleMouseUp)
     document.addEventListener("contextmenu", handleContextMenu)
@@ -1796,7 +1831,6 @@ export function Viewport() {
     document.addEventListener("keydown", handleKeyDown)
     document.addEventListener("keyup", handleKeyUp)
     window.addEventListener("beforeunload", handleBeforeUnload)
-
     void connect()
 
     return () => {
@@ -1805,6 +1839,8 @@ export function Viewport() {
       stopViewportInputPump()
       video?.removeEventListener("loadedmetadata", handleLoadedMetadata)
       video?.removeEventListener("resize", handleResize)
+      document.removeEventListener("dragover", handleDocDragOver)
+      ;(window as any).__axiomViewportDropHandler = null
       document.removeEventListener("mousedown", handleMouseDown)
       document.removeEventListener("mouseup", handleMouseUp)
       document.removeEventListener("contextmenu", handleContextMenu)
@@ -1892,7 +1928,10 @@ export function Viewport() {
           <ViewportButton icon={Maximize2} onClick={() => void connectRef.current()} />
         </div>
       </div>
-      <div ref={viewportShellRef} className="relative flex-1 overflow-hidden bg-black">
+      <div
+        ref={viewportShellRef}
+        className="relative flex-1 overflow-hidden bg-black"
+      >
         <video
           ref={videoRef}
           className="absolute inset-0 h-full w-full bg-black object-contain"
diff --git a/Headless/HeadlessCommandProtocol.cpp b/Headless/HeadlessCommandProtocol.cpp
index c5108eea..ca55dc54 100644
--- a/Headless/HeadlessCommandProtocol.cpp
+++ b/Headless/HeadlessCommandProtocol.cpp
@@ -747,6 +747,25 @@ std::optional<HeadlessCommand> ParseHeadlessCommand(std::string_view JsonLine,
   if (*Type == "gizmo_drag_start") return ParseMouseXY(HeadlessCommandType::GizmoDragStart);
   if (*Type == "gizmo_drag_update") return ParseMouseXY(HeadlessCommandType::GizmoDragUpdate);
   if (*Type == "gizmo_drag_end") return ParseMouseXY(HeadlessCommandType::GizmoDragEnd);
+  if (*Type == "drop_texture") {
+    static const std::regex TexturePathPattern(R"json("textureAssetPath"\s*:\s*"([^"]*)")json");
+    const auto TexturePath = MatchString(JsonLine, TexturePathPattern);
+    const auto MX = MatchString(JsonLine, MouseXPattern);
+    const auto MY = MatchString(JsonLine, MouseYPattern);
+    float MouseX = 0.0f;
+    float MouseY = 0.0f;
+    if (MX.has_value()) {
+      if (const auto V = ParseDouble(*MX)) MouseX = static_cast<float>(*V);
+    }
+    if (MY.has_value()) {
+      if (const auto V = ParseDouble(*MY)) MouseY = static_cast<float>(*V);
+    }
+    HeadlessCommand Cmd;
+    Cmd.Type = HeadlessCommandType::DropTexture;
+    Cmd.TextureAssetPath = TexturePath.value_or("");
+    Cmd.MousePosition = {MouseX, MouseY};
+    return Cmd;
+  }
   if (*Type == "list_assets") {
     return HeadlessCommand{.Type = HeadlessCommandType::ListAssets};
   }
@@ -966,6 +985,7 @@ ParseRemoteViewportCommand(std::string_view JsonLine, std::string &Error) {
   case HeadlessCommandType::SetLightProperties:
   case HeadlessCommandType::SetMaterialProperties:
   case HeadlessCommandType::SetMaterialTexture:
+  case HeadlessCommandType::DropTexture:
   case HeadlessCommandType::ReloadScripts:
   case HeadlessCommandType::Heartbeat:
   case HeadlessCommandType::Quit:
diff --git a/Headless/HeadlessCommandProtocol.h b/Headless/HeadlessCommandProtocol.h
index 4b25ac3c..bd2ca917 100644
--- a/Headless/HeadlessCommandProtocol.h
+++ b/Headless/HeadlessCommandProtocol.h
@@ -52,6 +52,7 @@ enum class HeadlessCommandType {
   SetLightProperties,
   SetMaterialProperties,
   SetMaterialTexture,
+  DropTexture,
   Heartbeat,
   RenderFrame,
   Quit,
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index de592779..e6aa0330 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -972,6 +972,24 @@ bool RemoteViewportServer::HandlePostRequest(uintptr_t ClientSocketValue,
   case HeadlessCommandType::SetMaterialTexture:
     m_Host.SubmitRemoteCommand(*User, Command->EditorPayload);
     break;
+  case HeadlessCommandType::DropTexture: {
+    if (!Command->TextureAssetPath.empty()) {
+      const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
+      const EditorViewportState *Viewport = Session.FindViewport(*User);
+      if (Viewport != nullptr) {
+        const std::string HitId = HitTestMeshes(
+            Viewport->Camera, m_Options.Width, m_Options.Height,
+            Command->MousePosition, Session.GetState().Scene.MeshInstances);
+        if (!HitId.empty()) {
+          m_Host.SubmitRemoteCommand(*User,
+              EditorCommand{SetMaterialTextureCommand{
+                  .ObjectId = HitId,
+                  .TextureAssetPath = Command->TextureAssetPath}});
+        }
+      }
+    }
+    break;
+  }
   case HeadlessCommandType::GizmoHover:
   case HeadlessCommandType::GizmoDragStart:
   case HeadlessCommandType::GizmoDragUpdate:
@@ -1768,6 +1786,7 @@ bool RemoteViewportServer::HandleWebSocketMessage(uintptr_t ClientSocketValue,
   case HeadlessCommandType::SetLightProperties:
   case HeadlessCommandType::SetMaterialProperties:
   case HeadlessCommandType::SetMaterialTexture:
+  case HeadlessCommandType::DropTexture:
   case HeadlessCommandType::ReloadScripts:
   case HeadlessCommandType::UpdateViewportCamera:
   case HeadlessCommandType::GizmoHover:
@@ -2063,6 +2082,23 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
     }
     return true;
   }
+  case HeadlessCommandType::DropTexture: {
+    const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
+    const EditorViewportState *Viewport = Session.FindViewport(Client->User);
+    if (Viewport == nullptr || Command->TextureAssetPath.empty()) {
+      return true;
+    }
+    const std::string HitId = HitTestMeshes(
+        Viewport->Camera, m_Options.Width, m_Options.Height,
+        Command->MousePosition, Session.GetState().Scene.MeshInstances);
+    if (!HitId.empty()) {
+      m_Host.SubmitRemoteCommand(Client->User,
+          EditorCommand{SetMaterialTextureCommand{
+              .ObjectId = HitId,
+              .TextureAssetPath = Command->TextureAssetPath}});
+    }
+    return true;
+  }
   case HeadlessCommandType::GizmoDragUpdate: {
     if (!Client->GizmoDrag.has_value()) {
       return true;

From aaa5ca7fbe00b71f2cf025aef012470b9c734076 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 15:49:04 -0500
Subject: [PATCH 03/12] Drag and drop meshes into viewport

---
 Axiom/Session/EditorCommand.h                 |  10 +-
 Axiom/Session/EditorSession.cpp               |  79 ++++++++++++
 Axiom/Session/EditorSession.h                 |   2 +
 Axiom/Session/MeshPicking.h                   | 112 ++++++++++++++++--
 .../components/engine/content-browser.tsx     |   4 +-
 EditorFrontend/components/engine/viewport.tsx |  12 +-
 Headless/HeadlessCommandProtocol.cpp          |  20 ++++
 Headless/HeadlessCommandProtocol.h            |   2 +
 Headless/RemoteViewportServer.cpp             |  93 ++++++++++-----
 Headless/RemoteViewportServer.h               |   4 +
 Tests/CMakeLists.txt                          |   1 +
 Tests/HeadlessProtocolTests.cpp               |  13 ++
 Tests/MeshPickingTests.cpp                    |  60 ++++++++++
 Tests/SceneLifecycleTests.cpp                 |  93 ++++++++++++++-
 14 files changed, 459 insertions(+), 46 deletions(-)
 create mode 100644 Tests/MeshPickingTests.cpp

diff --git a/Axiom/Session/EditorCommand.h b/Axiom/Session/EditorCommand.h
index 0b8c26ca..c9db32c3 100644
--- a/Axiom/Session/EditorCommand.h
+++ b/Axiom/Session/EditorCommand.h
@@ -53,6 +53,13 @@ struct CreateObjectCommand {
   std::string TemplateId;
 };
 
+struct CreateMeshObjectCommand {
+  std::string AssetPath;
+  glm::vec3 Location{0.0f};
+  glm::vec3 RotationDegrees{0.0f};
+  glm::vec3 Scale{1.0f};
+};
+
 struct DuplicateObjectCommand {
   std::string ObjectId;
 };
@@ -111,7 +118,8 @@ using EditorCommandPayload =
     std::variant<UpdateViewportCameraCommand, SetViewportCameraPoseCommand,
                  SetLookActiveCommand, SelectObjectCommand,
                  RenameObjectCommand, SetObjectVisibilityCommand,
-                 CreateObjectCommand, DuplicateObjectCommand,
+                 CreateObjectCommand, CreateMeshObjectCommand,
+                 DuplicateObjectCommand,
                  DeleteObjectCommand, ReparentObjectCommand,
                  SetTransformCommand, AttachScriptCommand,
                  DetachScriptCommand, SetMeshAssetCommand,
diff --git a/Axiom/Session/EditorSession.cpp b/Axiom/Session/EditorSession.cpp
index 0399f6bd..162d7764 100644
--- a/Axiom/Session/EditorSession.cpp
+++ b/Axiom/Session/EditorSession.cpp
@@ -65,6 +65,9 @@ std::string CommandTypeName(const EditorCommandPayload &Payload) {
   if (std::holds_alternative<CreateObjectCommand>(Payload)) {
     return "create_object";
   }
+  if (std::holds_alternative<CreateMeshObjectCommand>(Payload)) {
+    return "create_mesh_object";
+  }
   if (std::holds_alternative<DuplicateObjectCommand>(Payload)) {
     return "duplicate_object";
   }
@@ -931,6 +934,34 @@ bool EditorSession::ValidateCommand(const QueuedEditorCommand &QueuedCommand,
     }
   }
 
+  if (const auto *CreateMeshCmd =
+          std::get_if<CreateMeshObjectCommand>(&QueuedCommand.Command.Payload)) {
+    if (CreateMeshCmd->AssetPath.empty()) {
+      FailureReason = "CreateMeshObject requires a non-empty asset path.";
+      return false;
+    }
+    if (FindWorldFolder() == nullptr) {
+      FailureReason = "No world folder found in scene root.";
+      return false;
+    }
+    if (CreateMeshCmd->Scale.x <= 0.0f || CreateMeshCmd->Scale.y <= 0.0f ||
+        CreateMeshCmd->Scale.z <= 0.0f) {
+      FailureReason = "Scale values must be greater than zero.";
+      return false;
+    }
+    if (m_ContentDir.empty()) {
+      FailureReason = "CreateMeshObject requires a configured content directory.";
+      return false;
+    }
+    const std::filesystem::path FullPath = m_ContentDir / CreateMeshCmd->AssetPath;
+    const auto SceneData = Assets::LoadBasicMeshAsset(FullPath);
+    if (!SceneData.has_value() || SceneData->Instances.empty()) {
+      FailureReason = "CreateMeshObject failed to load mesh asset: " +
+                      CreateMeshCmd->AssetPath + ".";
+      return false;
+    }
+  }
+
   if (const auto *DupCmd =
           std::get_if<DuplicateObjectCommand>(&QueuedCommand.Command.Payload)) {
     if (DupCmd->ObjectId.empty()) {
@@ -1262,6 +1293,54 @@ void EditorSession::HandleCommand(const QueuedEditorCommand &QueuedCommand,
                 }});
 }
 
+void EditorSession::HandleCommand(const QueuedEditorCommand &QueuedCommand,
+                                  const CreateMeshObjectCommand &Command) {
+  EnsurePresence(QueuedCommand.Context.User);
+
+  const std::string ObjectId = BuildUniqueObjectId("Mesh");
+  const std::string DisplayName = BuildUniqueDisplayName("Mesh");
+  const EditorTransformDetails Transform{
+      .Location = Command.Location,
+      .RotationDegrees = Command.RotationDegrees,
+      .Scale = Command.Scale,
+  };
+
+  m_State.Scene.ObjectDetailsById.emplace(
+      ObjectId,
+      EditorObjectDetails{
+          .ObjectId = ObjectId,
+          .DisplayName = DisplayName,
+          .Kind = EditorSceneItemKind::Mesh,
+          .Visible = true,
+          .SupportsTransform = true,
+          .TransformReadOnly = false,
+          .Transform = Transform,
+          .WorldTransform = Transform,
+      });
+
+  if (Instance *Node = CreateInstanceForTemplate("Mesh", ObjectId)) {
+    Node->SetParent(FindWorldFolder());
+  }
+
+  SyncItemsFromTree();
+  PublishEvent({.Payload = ObjectCreatedEvent{
+                    .User = QueuedCommand.Context.User,
+                    .ObjectId = ObjectId,
+                    .DisplayName = DisplayName,
+                }});
+
+  HandleCommand(QueuedCommand, SetMeshAssetCommand{
+                                  .ObjectId = ObjectId,
+                                  .AssetPath = Command.AssetPath,
+                              });
+  HandleCommand(QueuedCommand, SetTransformCommand{
+                                  .ObjectId = ObjectId,
+                                  .Location = Command.Location,
+                                  .RotationDegrees = Command.RotationDegrees,
+                                  .Scale = Command.Scale,
+                              });
+}
+
 void EditorSession::HandleCommand(const QueuedEditorCommand &QueuedCommand,
                                   const DuplicateObjectCommand &Command) {
   EnsurePresence(QueuedCommand.Context.User);
diff --git a/Axiom/Session/EditorSession.h b/Axiom/Session/EditorSession.h
index 65f88af9..ebbfb675 100644
--- a/Axiom/Session/EditorSession.h
+++ b/Axiom/Session/EditorSession.h
@@ -245,6 +245,8 @@ class EditorSession final : public IEditorCommandSink {
                      const SetObjectVisibilityCommand &Command);
   void HandleCommand(const QueuedEditorCommand &QueuedCommand,
                      const CreateObjectCommand &Command);
+  void HandleCommand(const QueuedEditorCommand &QueuedCommand,
+                     const CreateMeshObjectCommand &Command);
   void HandleCommand(const QueuedEditorCommand &QueuedCommand,
                      const DuplicateObjectCommand &Command);
   void HandleCommand(const QueuedEditorCommand &QueuedCommand,
diff --git a/Axiom/Session/MeshPicking.h b/Axiom/Session/MeshPicking.h
index aed422bb..c3951429 100644
--- a/Axiom/Session/MeshPicking.h
+++ b/Axiom/Session/MeshPicking.h
@@ -4,23 +4,34 @@
 #include <Session/EditorSession.h>
 
 #include <glm/glm.hpp>
+#include <glm/common.hpp>
 #include <glm/gtc/matrix_inverse.hpp>
 
 #include <algorithm>
+#include <cmath>
 #include <limits>
+#include <optional>
 #include <string>
 #include <vector>
 
 namespace Axiom {
 
-// Returns the ObjectId of the closest mesh instance hit by a ray cast from the
-// camera through MousePixel, or an empty string if no mesh is hit. Uses AABB
-// slab intersection in object space to handle arbitrary transforms correctly.
-inline std::string HitTestMeshes(const Camera &Cam, uint32_t VpWidth,
-                                  uint32_t VpHeight, glm::vec2 MousePixel,
-                                  const std::vector<EditorSceneMeshInstance> &Instances) {
-  if (VpWidth == 0 || VpHeight == 0 || Instances.empty()) {
-    return {};
+struct ViewportRay {
+  glm::vec3 Origin{0.0f};
+  glm::vec3 Direction{0.0f, 0.0f, -1.0f};
+};
+
+struct MeshHitResult {
+  std::string ObjectId;
+  glm::vec3 WorldPosition{0.0f};
+  float Distance{0.0f};
+};
+
+inline std::optional<ViewportRay>
+BuildViewportRay(const Camera &Cam, uint32_t VpWidth, uint32_t VpHeight,
+                 glm::vec2 MousePixel) {
+  if (VpWidth == 0 || VpHeight == 0) {
+    return std::nullopt;
   }
 
   const glm::vec3 RayOrigin = Cam.GetPosition();
@@ -28,11 +39,34 @@ inline std::string HitTestMeshes(const Camera &Cam, uint32_t VpWidth,
   const float NdcY = (MousePixel.y / static_cast<float>(VpHeight)) * 2.0f - 1.0f;
   const glm::vec4 WorldH =
       glm::inverse(Cam.GetViewProjectionMatrix()) * glm::vec4(NdcX, NdcY, 0.0f, 1.0f);
+  if (glm::abs(WorldH.w) < 1e-6f) {
+    return std::nullopt;
+  }
+
   const glm::vec3 WorldPt = glm::vec3(WorldH) / WorldH.w;
   const glm::vec3 RayDir = glm::normalize(WorldPt - RayOrigin);
+  if (!std::isfinite(RayDir.x) || !std::isfinite(RayDir.y) ||
+      !std::isfinite(RayDir.z)) {
+    return std::nullopt;
+  }
+
+  return ViewportRay{.Origin = RayOrigin, .Direction = RayDir};
+}
+
+inline std::optional<MeshHitResult>
+HitTestMeshesDetailed(const Camera &Cam, uint32_t VpWidth, uint32_t VpHeight,
+                      glm::vec2 MousePixel,
+                      const std::vector<EditorSceneMeshInstance> &Instances) {
+  const auto Ray = BuildViewportRay(Cam, VpWidth, VpHeight, MousePixel);
+  if (!Ray.has_value() || Instances.empty()) {
+    return std::nullopt;
+  }
+
+  const glm::vec3 &RayOrigin = Ray->Origin;
+  const glm::vec3 &RayDir = Ray->Direction;
 
   float BestT = std::numeric_limits<float>::infinity();
-  std::string BestId;
+  std::optional<MeshHitResult> BestHit;
 
   for (const EditorSceneMeshInstance &Instance : Instances) {
     if (Instance.Mesh.BoundsMin == Instance.Mesh.BoundsMax) {
@@ -87,11 +121,67 @@ inline std::string HitTestMeshes(const Camera &Cam, uint32_t VpWidth,
     const float WorldT = glm::dot(WorldHit - RayOrigin, RayDir);
     if (WorldT > 0.0f && WorldT < BestT) {
       BestT = WorldT;
-      BestId = Instance.ObjectId;
+      BestHit = MeshHitResult{
+          .ObjectId = Instance.ObjectId,
+          .WorldPosition = WorldHit,
+          .Distance = WorldT,
+      };
     }
   }
 
-  return BestId;
+  return BestHit;
+}
+
+// Returns the ObjectId of the closest mesh instance hit by a ray cast from the
+// camera through MousePixel, or an empty string if no mesh is hit. Uses AABB
+// slab intersection in object space to handle arbitrary transforms correctly.
+inline std::string HitTestMeshes(const Camera &Cam, uint32_t VpWidth,
+                                 uint32_t VpHeight, glm::vec2 MousePixel,
+                                 const std::vector<EditorSceneMeshInstance> &Instances) {
+  const auto Hit = HitTestMeshesDetailed(Cam, VpWidth, VpHeight, MousePixel, Instances);
+  return Hit.has_value() ? Hit->ObjectId : std::string{};
+}
+
+inline std::optional<glm::vec3>
+IntersectViewportRayWithGroundPlane(const Camera &Cam, uint32_t VpWidth,
+                                    uint32_t VpHeight, glm::vec2 MousePixel,
+                                    float GroundY = 0.0f) {
+  const auto Ray = BuildViewportRay(Cam, VpWidth, VpHeight, MousePixel);
+  if (!Ray.has_value()) {
+    return std::nullopt;
+  }
+
+  const float Denominator = Ray->Direction.y;
+  if (glm::abs(Denominator) < 1e-6f) {
+    return std::nullopt;
+  }
+
+  const float T = (GroundY - Ray->Origin.y) / Denominator;
+  if (T < 0.0f) {
+    return std::nullopt;
+  }
+
+  return Ray->Origin + Ray->Direction * T;
+}
+
+inline glm::vec3
+ResolveViewportDropPosition(const Camera &Cam, uint32_t VpWidth,
+                            uint32_t VpHeight, glm::vec2 MousePixel,
+                            const std::vector<EditorSceneMeshInstance> &Instances,
+                            float GroundY = 0.0f, float FallbackDistance = 3.0f) {
+  if (const auto Hit =
+          HitTestMeshesDetailed(Cam, VpWidth, VpHeight, MousePixel, Instances);
+      Hit.has_value()) {
+    return Hit->WorldPosition;
+  }
+
+  if (const auto GroundHit =
+          IntersectViewportRayWithGroundPlane(Cam, VpWidth, VpHeight, MousePixel, GroundY);
+      GroundHit.has_value()) {
+    return *GroundHit;
+  }
+
+  return Cam.GetPosition() + Cam.GetForward() * FallbackDistance;
 }
 
 } // namespace Axiom
diff --git a/EditorFrontend/components/engine/content-browser.tsx b/EditorFrontend/components/engine/content-browser.tsx
index dd96edd4..c5da57df 100644
--- a/EditorFrontend/components/engine/content-browser.tsx
+++ b/EditorFrontend/components/engine/content-browser.tsx
@@ -453,7 +453,7 @@ export function ContentBrowser() {
                     }}
                     title={
                       canAssignToSelection && asset.kind === "mesh"
-                        ? "Double-click or drag to assign to a mesh object"
+                        ? "Double-click to assign, or drag into the viewport to add"
                         : canAssignToSelection && asset.kind === "texture"
                           ? "Double-click or drag to assign texture to a mesh object"
                           : asset.path
@@ -511,7 +511,7 @@ export function ContentBrowser() {
                     }}
                     title={
                       canAssignToSelection && asset.kind === "mesh"
-                        ? "Double-click or drag to assign to a mesh object"
+                        ? "Double-click to assign, or drag into the viewport to add"
                         : canAssignToSelection && asset.kind === "texture"
                           ? "Double-click or drag to assign texture to a mesh object"
                           : asset.path
diff --git a/EditorFrontend/components/engine/viewport.tsx b/EditorFrontend/components/engine/viewport.tsx
index 7612495e..8ab914e7 100644
--- a/EditorFrontend/components/engine/viewport.tsx
+++ b/EditorFrontend/components/engine/viewport.tsx
@@ -201,6 +201,12 @@ type RemoteViewportCommand =
       objectId: string
       textureAssetPath: string
     }
+  | {
+      type: "drop_mesh"
+      mouseX: number
+      mouseY: number
+      assetPath: string
+    }
   | {
       type: "drop_texture"
       mouseX: number
@@ -1802,7 +1808,7 @@ export function Viewport() {
     }
 
     ;(window as any).__axiomViewportDropHandler = (clientX: number, clientY: number, kind: string, path: string) => {
-      if (kind !== "texture" || !path) return
+      if ((kind !== "texture" && kind !== "mesh") || !path) return
       const x = lastDragX || clientX
       const y = lastDragY || clientY
       const s = viewportShellRef.current
@@ -1818,6 +1824,10 @@ export function Viewport() {
       if (cssX < 0 || cssY < 0 || cssX > contentW || cssY > contentH) return
       const mouseX = (cssX / contentW) * v.videoWidth
       const mouseY = (cssY / contentH) * v.videoHeight
+      if (kind === "mesh") {
+        void sendCommand({ type: "drop_mesh", mouseX, mouseY, assetPath: path }, "reliable")
+        return
+      }
       void sendCommand({ type: "drop_texture", mouseX, mouseY, textureAssetPath: path }, "reliable")
     }
 
diff --git a/Headless/HeadlessCommandProtocol.cpp b/Headless/HeadlessCommandProtocol.cpp
index ca55dc54..210423b6 100644
--- a/Headless/HeadlessCommandProtocol.cpp
+++ b/Headless/HeadlessCommandProtocol.cpp
@@ -747,6 +747,25 @@ std::optional<HeadlessCommand> ParseHeadlessCommand(std::string_view JsonLine,
   if (*Type == "gizmo_drag_start") return ParseMouseXY(HeadlessCommandType::GizmoDragStart);
   if (*Type == "gizmo_drag_update") return ParseMouseXY(HeadlessCommandType::GizmoDragUpdate);
   if (*Type == "gizmo_drag_end") return ParseMouseXY(HeadlessCommandType::GizmoDragEnd);
+  if (*Type == "drop_mesh") {
+    static const std::regex AssetPathPattern(R"json("assetPath"\s*:\s*"([^"]+)")json");
+    const auto AssetPath = MatchString(JsonLine, AssetPathPattern);
+    const auto MX = MatchString(JsonLine, MouseXPattern);
+    const auto MY = MatchString(JsonLine, MouseYPattern);
+    float MouseX = 0.0f;
+    float MouseY = 0.0f;
+    if (MX.has_value()) {
+      if (const auto V = ParseDouble(*MX)) MouseX = static_cast<float>(*V);
+    }
+    if (MY.has_value()) {
+      if (const auto V = ParseDouble(*MY)) MouseY = static_cast<float>(*V);
+    }
+    HeadlessCommand Cmd;
+    Cmd.Type = HeadlessCommandType::DropMesh;
+    Cmd.MeshAssetPath = AssetPath.value_or("");
+    Cmd.MousePosition = {MouseX, MouseY};
+    return Cmd;
+  }
   if (*Type == "drop_texture") {
     static const std::regex TexturePathPattern(R"json("textureAssetPath"\s*:\s*"([^"]*)")json");
     const auto TexturePath = MatchString(JsonLine, TexturePathPattern);
@@ -985,6 +1004,7 @@ ParseRemoteViewportCommand(std::string_view JsonLine, std::string &Error) {
   case HeadlessCommandType::SetLightProperties:
   case HeadlessCommandType::SetMaterialProperties:
   case HeadlessCommandType::SetMaterialTexture:
+  case HeadlessCommandType::DropMesh:
   case HeadlessCommandType::DropTexture:
   case HeadlessCommandType::ReloadScripts:
   case HeadlessCommandType::Heartbeat:
diff --git a/Headless/HeadlessCommandProtocol.h b/Headless/HeadlessCommandProtocol.h
index bd2ca917..7c23c69e 100644
--- a/Headless/HeadlessCommandProtocol.h
+++ b/Headless/HeadlessCommandProtocol.h
@@ -52,6 +52,7 @@ enum class HeadlessCommandType {
   SetLightProperties,
   SetMaterialProperties,
   SetMaterialTexture,
+  DropMesh,
   DropTexture,
   Heartbeat,
   RenderFrame,
@@ -75,6 +76,7 @@ struct HeadlessCommand {
   glm::vec4 BaseColorFactor{1.0f}; // used by SetMaterialProperties
   float Metallic{0.0f};         // used by SetMaterialProperties
   float Roughness{0.5f};        // used by SetMaterialProperties
+  std::string MeshAssetPath;    // used by DropMesh
   std::string TextureAssetPath; // used by SetMaterialTexture
 };
 
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index e6aa0330..8c8cb15a 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -972,22 +972,11 @@ bool RemoteViewportServer::HandlePostRequest(uintptr_t ClientSocketValue,
   case HeadlessCommandType::SetMaterialTexture:
     m_Host.SubmitRemoteCommand(*User, Command->EditorPayload);
     break;
+  case HeadlessCommandType::DropMesh:
+    HandleMeshDropCommand(*User, *Command);
+    break;
   case HeadlessCommandType::DropTexture: {
-    if (!Command->TextureAssetPath.empty()) {
-      const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
-      const EditorViewportState *Viewport = Session.FindViewport(*User);
-      if (Viewport != nullptr) {
-        const std::string HitId = HitTestMeshes(
-            Viewport->Camera, m_Options.Width, m_Options.Height,
-            Command->MousePosition, Session.GetState().Scene.MeshInstances);
-        if (!HitId.empty()) {
-          m_Host.SubmitRemoteCommand(*User,
-              EditorCommand{SetMaterialTextureCommand{
-                  .ObjectId = HitId,
-                  .TextureAssetPath = Command->TextureAssetPath}});
-        }
-      }
-    }
+    HandleTextureDropCommand(*User, *Command);
     break;
   }
   case HeadlessCommandType::GizmoHover:
@@ -1629,6 +1618,55 @@ void RemoteViewportServer::HandleClientEncodedVideoPacket(
   }
 }
 
+void RemoteViewportServer::HandleTextureDropCommand(
+    SessionUserId User, const HeadlessCommand &Command) {
+  if (Command.TextureAssetPath.empty()) {
+    return;
+  }
+
+  const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
+  const EditorViewportState *Viewport = Session.FindViewport(User);
+  if (Viewport == nullptr) {
+    return;
+  }
+
+  const std::string HitId = HitTestMeshes(
+      Viewport->Camera, m_Options.Width, m_Options.Height,
+      Command.MousePosition, Session.GetState().Scene.MeshInstances);
+  if (HitId.empty()) {
+    return;
+  }
+
+  m_Host.SubmitRemoteCommand(User, EditorCommand{SetMaterialTextureCommand{
+                                       .ObjectId = HitId,
+                                       .TextureAssetPath = Command.TextureAssetPath,
+                                   }});
+}
+
+void RemoteViewportServer::HandleMeshDropCommand(SessionUserId User,
+                                                 const HeadlessCommand &Command) {
+  if (Command.MeshAssetPath.empty()) {
+    return;
+  }
+
+  const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
+  const EditorViewportState *Viewport = Session.FindViewport(User);
+  if (Viewport == nullptr) {
+    return;
+  }
+
+  const glm::vec3 SpawnLocation = ResolveViewportDropPosition(
+      Viewport->Camera, m_Options.Width, m_Options.Height, Command.MousePosition,
+      Session.GetState().Scene.MeshInstances);
+
+  m_Host.SubmitRemoteCommand(User, EditorCommand{CreateMeshObjectCommand{
+                                       .AssetPath = Command.MeshAssetPath,
+                                       .Location = SpawnLocation,
+                                       .RotationDegrees = glm::vec3(0.0f),
+                                       .Scale = glm::vec3(1.0f),
+                                   }});
+}
+
 bool RemoteViewportServer::HandleWebSocketUpgrade(uintptr_t ClientSocketValue,
                                                   std::string_view HeaderBlock,
                                                   std::string_view Path) {
@@ -1770,6 +1808,12 @@ bool RemoteViewportServer::HandleWebSocketMessage(uintptr_t ClientSocketValue,
   case HeadlessCommandType::SetViewMode:
     m_Host.SetRemoteViewMode(Command->ViewMode);
     return true;
+  case HeadlessCommandType::DropMesh:
+    HandleMeshDropCommand(m_Host.GetHeadlessLayer().GetLocalUserId(), *Command);
+    return true;
+  case HeadlessCommandType::DropTexture:
+    HandleTextureDropCommand(m_Host.GetHeadlessLayer().GetLocalUserId(), *Command);
+    return true;
   case HeadlessCommandType::SetLookActive:
   case HeadlessCommandType::SetViewportCameraPose:
   case HeadlessCommandType::SelectObject:
@@ -1786,7 +1830,6 @@ bool RemoteViewportServer::HandleWebSocketMessage(uintptr_t ClientSocketValue,
   case HeadlessCommandType::SetLightProperties:
   case HeadlessCommandType::SetMaterialProperties:
   case HeadlessCommandType::SetMaterialTexture:
-  case HeadlessCommandType::DropTexture:
   case HeadlessCommandType::ReloadScripts:
   case HeadlessCommandType::UpdateViewportCamera:
   case HeadlessCommandType::GizmoHover:
@@ -1871,6 +1914,9 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
   case HeadlessCommandType::SetMaterialTexture:
     m_Host.SubmitRemoteCommand(Client->User, Command->EditorPayload);
     return true;
+  case HeadlessCommandType::DropMesh:
+    HandleMeshDropCommand(Client->User, *Command);
+    return true;
   case HeadlessCommandType::ReloadScripts: {
     m_Host.ReloadUserScripts();
     if (Client->WebRtcSession != nullptr) {
@@ -2083,20 +2129,7 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
     return true;
   }
   case HeadlessCommandType::DropTexture: {
-    const EditorSession &Session = m_Host.GetHeadlessLayer().GetSession();
-    const EditorViewportState *Viewport = Session.FindViewport(Client->User);
-    if (Viewport == nullptr || Command->TextureAssetPath.empty()) {
-      return true;
-    }
-    const std::string HitId = HitTestMeshes(
-        Viewport->Camera, m_Options.Width, m_Options.Height,
-        Command->MousePosition, Session.GetState().Scene.MeshInstances);
-    if (!HitId.empty()) {
-      m_Host.SubmitRemoteCommand(Client->User,
-          EditorCommand{SetMaterialTextureCommand{
-              .ObjectId = HitId,
-              .TextureAssetPath = Command->TextureAssetPath}});
-    }
+    HandleTextureDropCommand(Client->User, *Command);
     return true;
   }
   case HeadlessCommandType::GizmoDragUpdate: {
diff --git a/Headless/RemoteViewportServer.h b/Headless/RemoteViewportServer.h
index 89e0b82d..2a89080a 100644
--- a/Headless/RemoteViewportServer.h
+++ b/Headless/RemoteViewportServer.h
@@ -120,6 +120,10 @@ class RemoteViewportServer final : public ISessionTransportSubscriber {
                               std::string_view Payload);
   bool HandleClientWebRtcMessage(std::string_view ClientId,
                                  std::string_view Payload);
+  void HandleTextureDropCommand(SessionUserId User,
+                                const HeadlessCommand &Command);
+  void HandleMeshDropCommand(SessionUserId User,
+                             const HeadlessCommand &Command);
   void HandleClientEncodedVideoPacket(std::string_view ClientId,
                                       const EncodedVideoPacket &Packet);
   std::optional<SessionUserId> ResolveClientUser(
diff --git a/Tests/CMakeLists.txt b/Tests/CMakeLists.txt
index ced78aa7..7a8a8e06 100644
--- a/Tests/CMakeLists.txt
+++ b/Tests/CMakeLists.txt
@@ -1,6 +1,7 @@
 add_executable(AxiomTests
   LayerTests.cpp
   HeadlessProtocolTests.cpp
+  MeshPickingTests.cpp
   SceneLifecycleTests.cpp
   ../Headless/HeadlessCommandProtocol.cpp
   ../Headless/WebRtcSession.cpp
diff --git a/Tests/HeadlessProtocolTests.cpp b/Tests/HeadlessProtocolTests.cpp
index 9d60d7f2..8cefa9bf 100644
--- a/Tests/HeadlessProtocolTests.cpp
+++ b/Tests/HeadlessProtocolTests.cpp
@@ -557,6 +557,19 @@ TEST(HeadlessProtocolTests, ParsesSetMeshAssetCommand) {
   EXPECT_EQ(Payload->AssetPath, "Meshes/barrel.glb");
 }
 
+TEST(HeadlessProtocolTests, ParsesDropMeshCommand) {
+  std::string Error;
+  const auto Command = Axiom::ParseRemoteViewportCommand(
+      R"json({"type":"drop_mesh","mouseX":640,"mouseY":360,"assetPath":"Meshes/barrel.glb"})json",
+      Error);
+
+  ASSERT_TRUE(Command.has_value()) << Error;
+  EXPECT_EQ(Command->Type, Axiom::HeadlessCommandType::DropMesh);
+  EXPECT_FLOAT_EQ(Command->MousePosition.x, 640.0f);
+  EXPECT_FLOAT_EQ(Command->MousePosition.y, 360.0f);
+  EXPECT_EQ(Command->MeshAssetPath, "Meshes/barrel.glb");
+}
+
 TEST(HeadlessProtocolTests, ParsesSetLightPropertiesCommand) {
   std::string Error;
   const auto Command = Axiom::ParseRemoteViewportCommand(
diff --git a/Tests/MeshPickingTests.cpp b/Tests/MeshPickingTests.cpp
new file mode 100644
index 00000000..2107a241
--- /dev/null
+++ b/Tests/MeshPickingTests.cpp
@@ -0,0 +1,60 @@
+#include <gtest/gtest.h>
+
+#include <Renderer/Camera.h>
+#include <Session/MeshPicking.h>
+
+#include <glm/ext/matrix_transform.hpp>
+
+namespace {
+
+Axiom::Camera MakeCamera(const glm::vec3 &Position, const glm::vec3 &Target) {
+  Axiom::Camera Camera;
+  Camera.LookAt(Position, Target);
+  Camera.SetPerspective(55.0f, 1280.0f / 720.0f, 0.1f, 100.0f);
+  return Camera;
+}
+
+} // namespace
+
+TEST(MeshPickingTests, HitTestMeshesDetailedReturnsWorldHitPosition) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+  std::vector<Axiom::EditorSceneMeshInstance> Instances{{
+      .ObjectId = "crate",
+      .Mesh = Axiom::MeshData{
+          .BoundsMin = {-0.5f, -0.5f, -0.5f},
+          .BoundsMax = {0.5f, 0.5f, 0.5f},
+      },
+      .Transform = glm::translate(glm::mat4(1.0f), glm::vec3(0.0f, 0.5f, 0.0f)),
+  }};
+
+  const auto Hit =
+      Axiom::HitTestMeshesDetailed(Camera, 1280, 720, {640.0f, 360.0f}, Instances);
+
+  ASSERT_TRUE(Hit.has_value());
+  EXPECT_EQ(Hit->ObjectId, "crate");
+  EXPECT_NEAR(Hit->WorldPosition.x, 0.0f, 1e-3f);
+  EXPECT_NEAR(Hit->WorldPosition.y, 1.0f, 1e-3f);
+  EXPECT_NEAR(Hit->WorldPosition.z, 0.5f, 1e-3f);
+}
+
+TEST(MeshPickingTests, ResolveViewportDropPositionFallsBackToGroundPlane) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 0.0f, 0.0f});
+
+  const glm::vec3 Position = Axiom::ResolveViewportDropPosition(
+      Camera, 1280, 720, {640.0f, 360.0f}, {});
+
+  EXPECT_NEAR(Position.x, 0.0f, 1e-3f);
+  EXPECT_NEAR(Position.y, 0.0f, 1e-3f);
+  EXPECT_NEAR(Position.z, 0.0f, 1e-2f);
+}
+
+TEST(MeshPickingTests, ResolveViewportDropPositionFallsBackInFrontOfCamera) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+
+  const glm::vec3 Position = Axiom::ResolveViewportDropPosition(
+      Camera, 1280, 720, {640.0f, 360.0f}, {});
+
+  EXPECT_NEAR(Position.x, 0.0f, 1e-3f);
+  EXPECT_NEAR(Position.y, 1.0f, 1e-3f);
+  EXPECT_NEAR(Position.z, 2.0f, 1e-3f);
+}
diff --git a/Tests/SceneLifecycleTests.cpp b/Tests/SceneLifecycleTests.cpp
index 0e7d8a30..0a1949dd 100644
--- a/Tests/SceneLifecycleTests.cpp
+++ b/Tests/SceneLifecycleTests.cpp
@@ -5,6 +5,8 @@
 
 #include <glm/vec3.hpp>
 
+#include <mutex>
+
 namespace {
 
 class RecordingSubscriber final : public Axiom::IEditorEventSubscriber {
@@ -24,6 +26,11 @@ Axiom::CommandContext MakeContext(uint64_t FrameIndex = 1) {
   };
 }
 
+void EnsureLogInitialized() {
+  static std::once_flag Flag;
+  std::call_once(Flag, []() { Axiom::Log::Init(); });
+}
+
 // Returns a session with a "world" Folder in Items + ObjectDetailsById so that
 // the Instance tree has a valid world folder for Create commands.
 Axiom::EditorSession MakeWorldSession() {
@@ -133,6 +140,90 @@ TEST(SceneLifecycleTests, CreateFolderHasNoTransform) {
   EXPECT_FALSE(Details->Transform.has_value());
 }
 
+TEST(SceneLifecycleTests, CreateMeshObjectAddsMeshWithAssetAndTransform) {
+  EnsureLogInitialized();
+  Axiom::EditorSession Session = MakeWorldSession();
+  Session.SetContentDir(AXIOM_CONTENT_DIR);
+  RecordingSubscriber Subscriber;
+  Session.Subscribe(&Subscriber);
+
+  Session.Submit(MakeContext(),
+                 {.Payload = Axiom::CreateMeshObjectCommand{
+                      .AssetPath = "basicmesh.glb",
+                      .Location = glm::vec3(1.0f, 2.0f, 3.0f),
+                      .RotationDegrees = glm::vec3(0.0f, 45.0f, 0.0f),
+                      .Scale = glm::vec3(1.5f, 1.5f, 1.5f),
+                  }});
+  Session.Tick();
+
+  ASSERT_EQ(FindEvent<Axiom::CommandRejectedEvent>(Subscriber.Events), nullptr);
+
+  const auto *Created = FindEvent<Axiom::ObjectCreatedEvent>(Subscriber.Events);
+  ASSERT_NE(Created, nullptr);
+
+  const auto *MeshChanged = FindEvent<Axiom::MeshAssetChangedEvent>(Subscriber.Events);
+  ASSERT_NE(MeshChanged, nullptr);
+  EXPECT_EQ(MeshChanged->ObjectId, Created->ObjectId);
+  EXPECT_EQ(MeshChanged->AssetPath, "basicmesh.glb");
+
+  const auto *TransformChanged =
+      FindEvent<Axiom::ObjectTransformUpdatedEvent>(Subscriber.Events);
+  ASSERT_NE(TransformChanged, nullptr);
+  EXPECT_EQ(TransformChanged->ObjectId, Created->ObjectId);
+  EXPECT_FLOAT_EQ(TransformChanged->Location.x, 1.0f);
+  EXPECT_FLOAT_EQ(TransformChanged->Location.y, 2.0f);
+  EXPECT_FLOAT_EQ(TransformChanged->Location.z, 3.0f);
+  EXPECT_FLOAT_EQ(TransformChanged->RotationDegrees.y, 45.0f);
+  EXPECT_FLOAT_EQ(TransformChanged->Scale.x, 1.5f);
+  EXPECT_FLOAT_EQ(TransformChanged->Scale.y, 1.5f);
+  EXPECT_FLOAT_EQ(TransformChanged->Scale.z, 1.5f);
+
+  const Axiom::EditorSceneItem *WorldItem = Session.FindSceneItem("world");
+  ASSERT_NE(WorldItem, nullptr);
+  ASSERT_EQ(WorldItem->Children.size(), 1u);
+  EXPECT_EQ(WorldItem->Children.front().Id, Created->ObjectId);
+
+  const Axiom::EditorObjectDetails *Details =
+      Session.FindObjectDetails(Created->ObjectId);
+  ASSERT_NE(Details, nullptr);
+  ASSERT_TRUE(Details->Transform.has_value());
+  ASSERT_TRUE(Details->WorldTransform.has_value());
+  EXPECT_FLOAT_EQ(Details->Transform->Location.x, 1.0f);
+  EXPECT_FLOAT_EQ(Details->Transform->Location.y, 2.0f);
+  EXPECT_FLOAT_EQ(Details->Transform->Location.z, 3.0f);
+  EXPECT_FLOAT_EQ(Details->WorldTransform->RotationDegrees.y, 45.0f);
+
+  const auto &Instances = Session.GetState().Scene.MeshInstances;
+  const auto It = std::find_if(Instances.begin(), Instances.end(),
+                               [&](const Axiom::EditorSceneMeshInstance &I) {
+                                 return I.ObjectId == Created->ObjectId;
+                               });
+  ASSERT_NE(It, Instances.end());
+  EXPECT_EQ(It->AssetRelativePath, "basicmesh.glb");
+  EXPECT_NE(It->Material, nullptr);
+
+  const auto *Ack = FindEvent<Axiom::CommandAcknowledgedEvent>(Subscriber.Events);
+  ASSERT_NE(Ack, nullptr);
+  EXPECT_EQ(Ack->CommandType, "create_mesh_object");
+}
+
+TEST(SceneLifecycleTests, CreateMeshObjectRejectsInvalidAssetPath) {
+  EnsureLogInitialized();
+  Axiom::EditorSession Session = MakeWorldSession();
+  Session.SetContentDir(AXIOM_CONTENT_DIR);
+  RecordingSubscriber Subscriber;
+  Session.Subscribe(&Subscriber);
+
+  Session.Submit(MakeContext(),
+                 {.Payload = Axiom::CreateMeshObjectCommand{
+                      .AssetPath = "Meshes/missing.glb",
+                  }});
+  Session.Tick();
+
+  ASSERT_NE(FindEvent<Axiom::CommandRejectedEvent>(Subscriber.Events), nullptr);
+  ASSERT_EQ(FindEvent<Axiom::ObjectCreatedEvent>(Subscriber.Events), nullptr);
+}
+
 TEST(SceneLifecycleTests, CreateWithUnknownTemplateIdIsRejected) {
   Axiom::EditorSession Session = MakeWorldSession();
   RecordingSubscriber Subscriber;
@@ -1014,7 +1105,7 @@ TEST(SceneLifecycleTests, SetMeshAsset_RejectsNonMeshTarget) {
 TEST(SceneLifecycleTests, SetMeshAsset_CreatesInstanceForRuntimeCreatedMesh) {
   // A mesh created via CreateObject has no MeshInstance entry yet.
   // SetMeshAsset must create the entry rather than silently dropping the command.
-  Axiom::Log::Init();
+  EnsureLogInitialized();
   Axiom::EditorSession Session(Axiom::SessionId{1});
   Session.SetContentDir(AXIOM_CONTENT_DIR);
   RecordingSubscriber Subscriber;

From e78a802e68f6dbd949df02c038f4dbe7b4842499 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:10:13 -0500
Subject: [PATCH 04/12] Billboard light-bulb

---
 Axiom/Assets/SvgTexture.cpp                   | 332 ++++++++++++++++++
 Axiom/Assets/SvgTexture.h                     |  10 +
 Axiom/CMakeLists.txt                          |   2 +
 Axiom/Renderer/RenderCommand.cpp              |   7 +
 Axiom/Renderer/RenderCommand.h                |   1 +
 Axiom/Renderer/RenderScene.cpp                |   1 +
 Axiom/Renderer/RenderScene.h                  |   7 +
 .../Vulkan/VulkanLightBillboardRenderer.cpp   | 260 ++++++++++++++
 .../Vulkan/VulkanLightBillboardRenderer.h     |  35 ++
 .../Renderer/Vulkan/VulkanRendererBackend.cpp |  29 ++
 Axiom/Renderer/Vulkan/VulkanRendererBackend.h |   4 +
 Content/Shaders/light_billboard.frag          |  12 +
 Content/Shaders/light_billboard.frag.spv      | Bin 0 -> 1064 bytes
 Content/Shaders/light_billboard.vert          |  32 ++
 Content/Shaders/light_billboard.vert.spv      | Bin 0 -> 2748 bytes
 Headless/HeadlessSessionLayer.cpp             |  28 ++
 Headless/HeadlessSessionLayer.h               |   1 +
 Tests/CMakeLists.txt                          |   1 +
 Tests/LayerTests.cpp                          | 133 +++++++
 19 files changed, 895 insertions(+)
 create mode 100644 Axiom/Assets/SvgTexture.cpp
 create mode 100644 Axiom/Assets/SvgTexture.h
 create mode 100644 Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
 create mode 100644 Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.h
 create mode 100644 Content/Shaders/light_billboard.frag
 create mode 100644 Content/Shaders/light_billboard.frag.spv
 create mode 100644 Content/Shaders/light_billboard.vert
 create mode 100644 Content/Shaders/light_billboard.vert.spv

diff --git a/Axiom/Assets/SvgTexture.cpp b/Axiom/Assets/SvgTexture.cpp
new file mode 100644
index 00000000..ec842310
--- /dev/null
+++ b/Axiom/Assets/SvgTexture.cpp
@@ -0,0 +1,332 @@
+#include "Assets/SvgTexture.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cmath>
+#include <cstdlib>
+#include <fstream>
+#include <iterator>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#if defined(__APPLE__)
+#include <CoreGraphics/CoreGraphics.h>
+#endif
+
+namespace Axiom::Assets {
+namespace {
+
+struct SvgViewBox {
+  float MinX{0.0f};
+  float MinY{0.0f};
+  float Width{0.0f};
+  float Height{0.0f};
+};
+
+std::string ReadTextFile(const std::filesystem::path &Path) {
+  std::ifstream Input(Path, std::ios::binary);
+  if (!Input.is_open()) {
+    return {};
+  }
+  return std::string(std::istreambuf_iterator<char>(Input),
+                     std::istreambuf_iterator<char>());
+}
+
+std::optional<std::string_view> FindAttributeValue(std::string_view Text,
+                                                   std::string_view Name) {
+  const std::string Key = std::string(Name) + "=\"";
+  const size_t Start = Text.find(Key);
+  if (Start == std::string_view::npos) {
+    return std::nullopt;
+  }
+  const size_t ValueStart = Start + Key.size();
+  const size_t ValueEnd = Text.find('"', ValueStart);
+  if (ValueEnd == std::string_view::npos) {
+    return std::nullopt;
+  }
+  return Text.substr(ValueStart, ValueEnd - ValueStart);
+}
+
+bool ParseFloatToken(const char *&Cursor, const char *End, float &OutValue) {
+  while (Cursor < End &&
+         (std::isspace(static_cast<unsigned char>(*Cursor)) || *Cursor == ',')) {
+    ++Cursor;
+  }
+  if (Cursor >= End) {
+    return false;
+  }
+
+  char *ParseEnd = nullptr;
+  OutValue = std::strtof(Cursor, &ParseEnd);
+  if (ParseEnd == Cursor) {
+    return false;
+  }
+  Cursor = ParseEnd;
+  return true;
+}
+
+std::optional<SvgViewBox> ParseViewBox(std::string_view Value) {
+  SvgViewBox Result{};
+  const char *Cursor = Value.data();
+  const char *End = Value.data() + Value.size();
+  if (!ParseFloatToken(Cursor, End, Result.MinX) ||
+      !ParseFloatToken(Cursor, End, Result.MinY) ||
+      !ParseFloatToken(Cursor, End, Result.Width) ||
+      !ParseFloatToken(Cursor, End, Result.Height)) {
+    return std::nullopt;
+  }
+  if (Result.Width <= 0.0f || Result.Height <= 0.0f) {
+    return std::nullopt;
+  }
+  return Result;
+}
+
+#if defined(__APPLE__)
+class SvgPathParser {
+public:
+  explicit SvgPathParser(std::string_view PathData)
+      : m_Cursor(PathData.data()), m_End(PathData.data() + PathData.size()) {}
+
+  bool Parse(CGMutablePathRef Path) {
+    char Command = 0;
+    while (SkipSeparators()) {
+      if (std::isalpha(static_cast<unsigned char>(*m_Cursor)) != 0) {
+        Command = *m_Cursor++;
+      } else if (Command == 0) {
+        return false;
+      }
+
+      switch (Command) {
+      case 'M':
+      case 'm':
+        if (!ParseMoveTo(Path, Command == 'm')) {
+          return false;
+        }
+        break;
+      case 'L':
+      case 'l':
+        if (!ParseLineTo(Path, Command == 'l')) {
+          return false;
+        }
+        break;
+      case 'H':
+      case 'h':
+        if (!ParseHorizontalTo(Path, Command == 'h')) {
+          return false;
+        }
+        break;
+      case 'V':
+      case 'v':
+        if (!ParseVerticalTo(Path, Command == 'v')) {
+          return false;
+        }
+        break;
+      case 'C':
+      case 'c':
+        if (!ParseCurveTo(Path, Command == 'c')) {
+          return false;
+        }
+        break;
+      case 'Z':
+      case 'z':
+        CGPathCloseSubpath(Path);
+        m_Current = m_SubpathStart;
+        break;
+      default:
+        return false;
+      }
+    }
+    return true;
+  }
+
+private:
+  bool SkipSeparators() {
+    while (m_Cursor < m_End &&
+           (std::isspace(static_cast<unsigned char>(*m_Cursor)) ||
+            *m_Cursor == ',')) {
+      ++m_Cursor;
+    }
+    return m_Cursor < m_End;
+  }
+
+  bool HasNumberAhead() const {
+    const char *Probe = m_Cursor;
+    while (Probe < m_End &&
+           (std::isspace(static_cast<unsigned char>(*Probe)) || *Probe == ',')) {
+      ++Probe;
+    }
+    return Probe < m_End &&
+           (std::isdigit(static_cast<unsigned char>(*Probe)) != 0 ||
+            *Probe == '-' || *Probe == '+' || *Probe == '.');
+  }
+
+  bool ReadNumber(float &OutValue) {
+    return ParseFloatToken(m_Cursor, m_End, OutValue);
+  }
+
+  bool ReadPoint(CGPoint &OutPoint, bool Relative) {
+    float X = 0.0f;
+    float Y = 0.0f;
+    if (!ReadNumber(X) || !ReadNumber(Y)) {
+      return false;
+    }
+    OutPoint = CGPointMake(Relative ? m_Current.x + X : X,
+                           Relative ? m_Current.y + Y : Y);
+    return true;
+  }
+
+  bool ParseMoveTo(CGMutablePathRef Path, bool Relative) {
+    CGPoint Point{};
+    if (!ReadPoint(Point, Relative)) {
+      return false;
+    }
+    CGPathMoveToPoint(Path, nullptr, Point.x, Point.y);
+    m_Current = Point;
+    m_SubpathStart = Point;
+
+    while (HasNumberAhead()) {
+      if (!ReadPoint(Point, Relative)) {
+        return false;
+      }
+      CGPathAddLineToPoint(Path, nullptr, Point.x, Point.y);
+      m_Current = Point;
+    }
+    return true;
+  }
+
+  bool ParseLineTo(CGMutablePathRef Path, bool Relative) {
+    while (HasNumberAhead()) {
+      CGPoint Point{};
+      if (!ReadPoint(Point, Relative)) {
+        return false;
+      }
+      CGPathAddLineToPoint(Path, nullptr, Point.x, Point.y);
+      m_Current = Point;
+    }
+    return true;
+  }
+
+  bool ParseHorizontalTo(CGMutablePathRef Path, bool Relative) {
+    while (HasNumberAhead()) {
+      float X = 0.0f;
+      if (!ReadNumber(X)) {
+        return false;
+      }
+      m_Current.x = Relative ? (m_Current.x + X) : X;
+      CGPathAddLineToPoint(Path, nullptr, m_Current.x, m_Current.y);
+    }
+    return true;
+  }
+
+  bool ParseVerticalTo(CGMutablePathRef Path, bool Relative) {
+    while (HasNumberAhead()) {
+      float Y = 0.0f;
+      if (!ReadNumber(Y)) {
+        return false;
+      }
+      m_Current.y = Relative ? (m_Current.y + Y) : Y;
+      CGPathAddLineToPoint(Path, nullptr, m_Current.x, m_Current.y);
+    }
+    return true;
+  }
+
+  bool ParseCurveTo(CGMutablePathRef Path, bool Relative) {
+    while (HasNumberAhead()) {
+      CGPoint C1{};
+      CGPoint C2{};
+      CGPoint End{};
+      if (!ReadPoint(C1, Relative) || !ReadPoint(C2, Relative) ||
+          !ReadPoint(End, Relative)) {
+        return false;
+      }
+      CGPathAddCurveToPoint(Path, nullptr, C1.x, C1.y, C2.x, C2.y, End.x, End.y);
+      m_Current = End;
+    }
+    return true;
+  }
+
+  const char *m_Cursor{nullptr};
+  const char *m_End{nullptr};
+  CGPoint m_Current{0.0, 0.0};
+  CGPoint m_SubpathStart{0.0, 0.0};
+};
+
+TextureSourceDataRef RasterizeSvg(std::string_view SvgText,
+                                  uint32_t TargetSize) {
+  const auto ViewBoxText = FindAttributeValue(SvgText, "viewBox");
+  const auto PathText = FindAttributeValue(SvgText, "d");
+  if (!ViewBoxText.has_value() || !PathText.has_value()) {
+    return nullptr;
+  }
+
+  const auto ViewBox = ParseViewBox(*ViewBoxText);
+  if (!ViewBox.has_value()) {
+    return nullptr;
+  }
+
+  CGMutablePathRef Path = CGPathCreateMutable();
+  SvgPathParser Parser(*PathText);
+  const bool Parsed = Parser.Parse(Path);
+  if (!Parsed) {
+    CGPathRelease(Path);
+    return nullptr;
+  }
+
+  const float LongestSide = std::max(ViewBox->Width, ViewBox->Height);
+  const float Scale = static_cast<float>(TargetSize) / LongestSide;
+  const uint32_t Width =
+      std::max<uint32_t>(1u, static_cast<uint32_t>(std::ceil(ViewBox->Width * Scale)));
+  const uint32_t Height =
+      std::max<uint32_t>(1u, static_cast<uint32_t>(std::ceil(ViewBox->Height * Scale)));
+
+  auto Texture = std::make_shared<TextureSourceData>();
+  Texture->Width = Width;
+  Texture->Height = Height;
+  Texture->Pixels.resize(static_cast<size_t>(Width) * static_cast<size_t>(Height) * 4u, 0u);
+
+  CGColorSpaceRef ColorSpace = CGColorSpaceCreateDeviceRGB();
+  CGContextRef Context = CGBitmapContextCreate(
+      Texture->Pixels.data(), Width, Height, 8, Width * 4, ColorSpace,
+      static_cast<uint32_t>(kCGImageAlphaPremultipliedLast |
+                            kCGBitmapByteOrder32Big));
+  CGColorSpaceRelease(ColorSpace);
+
+  if (Context == nullptr) {
+    CGPathRelease(Path);
+    return nullptr;
+  }
+
+  CGContextSetAllowsAntialiasing(Context, true);
+  CGContextSetShouldAntialias(Context, true);
+  CGContextTranslateCTM(Context, 0.0f, static_cast<CGFloat>(Height));
+  CGContextScaleCTM(Context, Scale, -Scale);
+  CGContextTranslateCTM(Context, -ViewBox->MinX, -ViewBox->MinY);
+  CGContextAddPath(Context, Path);
+  CGContextSetRGBFillColor(Context, 1.0, 1.0, 1.0, 1.0);
+  CGContextFillPath(Context);
+
+  CGContextRelease(Context);
+  CGPathRelease(Path);
+  return Texture->IsValid() ? Texture : nullptr;
+}
+#endif
+
+} // namespace
+
+TextureSourceDataRef LoadSvgTextureFromFile(const std::filesystem::path &Path,
+                                            uint32_t TargetSize) {
+  const std::string SvgText = ReadTextFile(Path);
+  if (SvgText.empty()) {
+    return nullptr;
+  }
+
+#if defined(__APPLE__)
+  return RasterizeSvg(SvgText, TargetSize);
+#else
+  (void)TargetSize;
+  return nullptr;
+#endif
+}
+} // namespace Axiom::Assets
diff --git a/Axiom/Assets/SvgTexture.h b/Axiom/Assets/SvgTexture.h
new file mode 100644
index 00000000..4c42eef0
--- /dev/null
+++ b/Axiom/Assets/SvgTexture.h
@@ -0,0 +1,10 @@
+#pragma once
+
+#include "Renderer/Material.h"
+
+#include <filesystem>
+
+namespace Axiom::Assets {
+TextureSourceDataRef LoadSvgTextureFromFile(const std::filesystem::path &Path,
+                                            uint32_t TargetSize = 128);
+} // namespace Axiom::Assets
diff --git a/Axiom/CMakeLists.txt b/Axiom/CMakeLists.txt
index 6d1ae37a..c906ba58 100644
--- a/Axiom/CMakeLists.txt
+++ b/Axiom/CMakeLists.txt
@@ -5,6 +5,7 @@ set(ENGINE_SOURCES
   Assets/IAssetSource.cpp
   Assets/MeshAsset.cpp
   Assets/SceneFile.cpp
+  Assets/SvgTexture.cpp
   Core/Application.cpp
   Core/GlfwEditorInputSource.cpp
   Core/GlfwWindow.cpp
@@ -36,6 +37,7 @@ set(ENGINE_SOURCES
   Renderer/Vulkan/VulkanGizmoRenderer.cpp
   Renderer/Vulkan/VulkanImGuiRenderer.cpp
   Renderer/Vulkan/VulkanInitializers.cpp
+  Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
   Renderer/Vulkan/VulkanMaterialResources.cpp
   Renderer/Vulkan/VulkanMesh.cpp
   Renderer/Vulkan/VulkanOcclusionCulling.cpp
diff --git a/Axiom/Renderer/RenderCommand.cpp b/Axiom/Renderer/RenderCommand.cpp
index 1404cd3d..421da02b 100644
--- a/Axiom/Renderer/RenderCommand.cpp
+++ b/Axiom/Renderer/RenderCommand.cpp
@@ -20,6 +20,13 @@ void RenderCommand::Submit(const RenderMeshSubmission &Submission) {
   }
 }
 
+void RenderCommand::SubmitLightBillboard(
+    const LightBillboardOverlay &Billboard) {
+  if (s_ActiveScene) {
+    s_ActiveScene->LightBillboards.push_back(Billboard);
+  }
+}
+
 void RenderCommand::SetGizmoOverlay(const GizmoOverlayData &Gizmo) {
   if (s_ActiveScene) {
     s_ActiveScene->GizmoOverlay = Gizmo;
diff --git a/Axiom/Renderer/RenderCommand.h b/Axiom/Renderer/RenderCommand.h
index c463a29a..e790c7ce 100644
--- a/Axiom/Renderer/RenderCommand.h
+++ b/Axiom/Renderer/RenderCommand.h
@@ -10,6 +10,7 @@ class RenderCommand {
   static void BeginScene(RenderScene &Scene);
   static void SetCamera(const Camera &Camera);
   static void Submit(const RenderMeshSubmission &Submission);
+  static void SubmitLightBillboard(const LightBillboardOverlay &Billboard);
   static void SetGizmoOverlay(const GizmoOverlayData &Gizmo);
   static void SetSun(const DirectionalLight &Light);
   static void EndScene();
diff --git a/Axiom/Renderer/RenderScene.cpp b/Axiom/Renderer/RenderScene.cpp
index 0f65cf3e..886fa50b 100644
--- a/Axiom/Renderer/RenderScene.cpp
+++ b/Axiom/Renderer/RenderScene.cpp
@@ -7,5 +7,6 @@ void RenderScene::Reset() {
   Submissions.clear();
   GizmoOverlay.reset();
   Sun.reset();
+  LightBillboards.clear();
 }
 } // namespace Axiom
diff --git a/Axiom/Renderer/RenderScene.h b/Axiom/Renderer/RenderScene.h
index 2b5ea03a..302ad417 100644
--- a/Axiom/Renderer/RenderScene.h
+++ b/Axiom/Renderer/RenderScene.h
@@ -27,6 +27,12 @@ struct DirectionalLight {
   glm::vec3 Direction{0.35f, 0.7f, 0.2f}; // world-space, need not be normalized
 };
 
+struct LightBillboardOverlay {
+  glm::vec3 WorldPosition{0.0f};
+  glm::vec4 Color{1.0f};
+  float PixelSize{48.0f};
+};
+
 class RenderScene {
 public:
   void Reset();
@@ -36,5 +42,6 @@ class RenderScene {
   std::vector<RenderMeshSubmission> Submissions;
   std::optional<GizmoOverlayData> GizmoOverlay;
   std::optional<DirectionalLight> Sun;
+  std::vector<LightBillboardOverlay> LightBillboards;
 };
 } // namespace Axiom
diff --git a/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
new file mode 100644
index 00000000..f571d08d
--- /dev/null
+++ b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
@@ -0,0 +1,260 @@
+#include "Renderer/Vulkan/VulkanLightBillboardRenderer.h"
+
+#include "Core/Log.h"
+#include "Renderer/Camera.h"
+#include "Renderer/Vulkan/VulkanInitializers.h"
+#include "Renderer/Vulkan/VulkanPipeline.h"
+
+#include <array>
+#include <cmath>
+
+#ifndef AXIOM_CONTENT_DIR
+#define AXIOM_CONTENT_DIR "Content"
+#endif
+
+namespace Axiom {
+namespace {
+
+struct BillboardPushConstants {
+  glm::mat4 ViewProjection{1.0f};
+  glm::vec4 WorldPositionAndHalfSize{0.0f};
+  glm::vec4 Color{1.0f};
+  glm::vec4 CameraRight{1.0f, 0.0f, 0.0f, 0.0f};
+  glm::vec4 CameraUp{0.0f, 1.0f, 0.0f, 0.0f};
+};
+static_assert(sizeof(BillboardPushConstants) <= 128,
+              "BillboardPushConstants exceeds guaranteed push constant minimum");
+
+float ComputeBillboardHalfSizeWorld(const Camera &Camera,
+                                    const LightBillboardOverlay &Billboard,
+                                    VkExtent2D DrawExtent) {
+  const glm::vec3 ToBillboard = Billboard.WorldPosition - Camera.GetPosition();
+  const float ForwardDistance =
+      glm::dot(ToBillboard, glm::normalize(Camera.GetForward()));
+  const float Distance = std::max(ForwardDistance, 0.1f);
+  const float ProjectionY = std::abs(Camera.GetProjectionMatrix()[1][1]);
+  if (ProjectionY < 0.0001f || DrawExtent.height == 0) {
+    return 0.1f;
+  }
+
+  const float TanHalfFov = 1.0f / ProjectionY;
+  const float WorldUnitsPerPixel =
+      (2.0f * Distance * TanHalfFov) / static_cast<float>(DrawExtent.height);
+  return std::max(0.01f, Billboard.PixelSize * 0.5f * WorldUnitsPerPixel);
+}
+
+} // namespace
+
+void VulkanLightBillboardRenderer::Init(const InitInfo &Info,
+                                        DeletionQueue &DeletionQueue) {
+  m_Device = Info.Device;
+
+  {
+    DescriptorLayoutBuilder Builder;
+    Builder.AddBinding(0, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER);
+    m_DescriptorLayout = Builder.Build(
+        m_Device, VK_SHADER_STAGE_FRAGMENT_BIT);
+  }
+
+  if (Info.DescriptorAllocator != nullptr && Info.TextureView != VK_NULL_HANDLE &&
+      Info.TextureSampler != VK_NULL_HANDLE) {
+    m_DescriptorSet =
+        Info.DescriptorAllocator->Allocate(m_Device, m_DescriptorLayout);
+    VkDescriptorImageInfo TextureInfo{};
+    TextureInfo.sampler = Info.TextureSampler;
+    TextureInfo.imageView = Info.TextureView;
+    TextureInfo.imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
+
+    VkWriteDescriptorSet TextureWrite =
+        VkInit::WriteDescriptorSet(VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
+                                   m_DescriptorSet, &TextureInfo, 0);
+    vkUpdateDescriptorSets(m_Device, 1, &TextureWrite, 0, VK_NULL_HANDLE);
+  }
+
+  VkPushConstantRange PushConstantRange{};
+  PushConstantRange.stageFlags =
+      VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT;
+  PushConstantRange.offset = 0;
+  PushConstantRange.size = sizeof(BillboardPushConstants);
+
+  VkPipelineLayoutCreateInfo LayoutInfo = VkInit::PipelineLayoutCreateInfo();
+  LayoutInfo.setLayoutCount = 1;
+  LayoutInfo.pSetLayouts = &m_DescriptorLayout;
+  LayoutInfo.pushConstantRangeCount = 1;
+  LayoutInfo.pPushConstantRanges = &PushConstantRange;
+
+  if (vkCreatePipelineLayout(m_Device, &LayoutInfo, VK_NULL_HANDLE,
+                             &m_PipelineLayout) != VK_SUCCESS) {
+    A_ERROR("VulkanLightBillboardRenderer: failed to create pipeline layout");
+    return;
+  }
+
+  VkShaderModule VertexShader;
+  const std::string VertexPath =
+      std::string(AXIOM_CONTENT_DIR) + "/Shaders/light_billboard.vert.spv";
+  if (!VkUtil::LoadShaderModule(VertexPath.c_str(), m_Device, &VertexShader)) {
+    A_ERROR("VulkanLightBillboardRenderer: failed to load vertex shader: {0}",
+            VertexPath);
+    return;
+  }
+
+  VkShaderModule FragmentShader;
+  const std::string FragmentPath =
+      std::string(AXIOM_CONTENT_DIR) + "/Shaders/light_billboard.frag.spv";
+  if (!VkUtil::LoadShaderModule(FragmentPath.c_str(), m_Device,
+                                &FragmentShader)) {
+    A_ERROR("VulkanLightBillboardRenderer: failed to load fragment shader: {0}",
+            FragmentPath);
+    vkDestroyShaderModule(m_Device, VertexShader, VK_NULL_HANDLE);
+    return;
+  }
+
+  std::array<VkPipelineShaderStageCreateInfo, 2> ShaderStages = {
+      VkInit::PipelineShaderStageCreateInfo(VK_SHADER_STAGE_VERTEX_BIT,
+                                            VertexShader),
+      VkInit::PipelineShaderStageCreateInfo(VK_SHADER_STAGE_FRAGMENT_BIT,
+                                            FragmentShader)};
+
+  VkPipelineVertexInputStateCreateInfo VertexInputInfo{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO};
+
+  VkPipelineInputAssemblyStateCreateInfo InputAssembly{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO,
+      .topology = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST};
+
+  VkPipelineViewportStateCreateInfo ViewportState{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO,
+      .viewportCount = 1,
+      .scissorCount = 1};
+
+  VkPipelineRasterizationStateCreateInfo Rasterizer{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO,
+      .polygonMode = VK_POLYGON_MODE_FILL,
+      .cullMode = VK_CULL_MODE_NONE,
+      .frontFace = VK_FRONT_FACE_COUNTER_CLOCKWISE,
+      .lineWidth = 1.0f};
+
+  VkPipelineMultisampleStateCreateInfo Multisampling{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO,
+      .rasterizationSamples = VK_SAMPLE_COUNT_1_BIT};
+
+  VkPipelineDepthStencilStateCreateInfo DepthStencil{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO,
+      .depthTestEnable = VK_FALSE,
+      .depthWriteEnable = VK_FALSE,
+      .depthBoundsTestEnable = VK_FALSE,
+      .stencilTestEnable = VK_FALSE};
+
+  VkPipelineColorBlendAttachmentState ColorBlendAttachment{};
+  ColorBlendAttachment.colorWriteMask =
+      VK_COLOR_COMPONENT_R_BIT | VK_COLOR_COMPONENT_G_BIT |
+      VK_COLOR_COMPONENT_B_BIT | VK_COLOR_COMPONENT_A_BIT;
+  ColorBlendAttachment.blendEnable = VK_TRUE;
+  ColorBlendAttachment.srcColorBlendFactor = VK_BLEND_FACTOR_SRC_ALPHA;
+  ColorBlendAttachment.dstColorBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
+  ColorBlendAttachment.colorBlendOp = VK_BLEND_OP_ADD;
+  ColorBlendAttachment.srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE;
+  ColorBlendAttachment.dstAlphaBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
+  ColorBlendAttachment.alphaBlendOp = VK_BLEND_OP_ADD;
+
+  VkPipelineColorBlendStateCreateInfo ColorBlending{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO,
+      .attachmentCount = 1,
+      .pAttachments = &ColorBlendAttachment};
+
+  std::array<VkDynamicState, 2> DynamicStates = {VK_DYNAMIC_STATE_VIEWPORT,
+                                                  VK_DYNAMIC_STATE_SCISSOR};
+  VkPipelineDynamicStateCreateInfo DynamicState{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO,
+      .dynamicStateCount = static_cast<uint32_t>(DynamicStates.size()),
+      .pDynamicStates = DynamicStates.data()};
+
+  VkPipelineRenderingCreateInfo RenderingInfo{
+      .sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO,
+      .colorAttachmentCount = 1,
+      .pColorAttachmentFormats = &Info.DrawImageFormat};
+
+  VkGraphicsPipelineCreateInfo PipelineInfo{
+      .sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO,
+      .pNext = &RenderingInfo,
+      .stageCount = static_cast<uint32_t>(ShaderStages.size()),
+      .pStages = ShaderStages.data(),
+      .pVertexInputState = &VertexInputInfo,
+      .pInputAssemblyState = &InputAssembly,
+      .pViewportState = &ViewportState,
+      .pRasterizationState = &Rasterizer,
+      .pMultisampleState = &Multisampling,
+      .pDepthStencilState = &DepthStencil,
+      .pColorBlendState = &ColorBlending,
+      .pDynamicState = &DynamicState,
+      .layout = m_PipelineLayout,
+      .renderPass = VK_NULL_HANDLE,
+      .subpass = 0};
+
+  if (vkCreateGraphicsPipelines(m_Device, VK_NULL_HANDLE, 1, &PipelineInfo,
+                                VK_NULL_HANDLE, &m_Pipeline) != VK_SUCCESS) {
+    A_ERROR("VulkanLightBillboardRenderer: failed to create pipeline");
+  }
+
+  vkDestroyShaderModule(m_Device, VertexShader, VK_NULL_HANDLE);
+  vkDestroyShaderModule(m_Device, FragmentShader, VK_NULL_HANDLE);
+
+  DeletionQueue.PushFunction([this]() {
+    vkDestroyPipeline(m_Device, m_Pipeline, VK_NULL_HANDLE);
+    vkDestroyPipelineLayout(m_Device, m_PipelineLayout, VK_NULL_HANDLE);
+    vkDestroyDescriptorSetLayout(m_Device, m_DescriptorLayout, VK_NULL_HANDLE);
+  });
+}
+
+void VulkanLightBillboardRenderer::DrawLightBillboards(
+    VkCommandBuffer CommandBuffer, VkExtent2D DrawExtent, VkImageView DrawImageView,
+    const RenderScene &Scene) {
+  if (Scene.ActiveCamera == nullptr || Scene.LightBillboards.empty() ||
+      m_Pipeline == VK_NULL_HANDLE || m_DescriptorSet == VK_NULL_HANDLE) {
+    return;
+  }
+
+  VkRenderingAttachmentInfo ColorAttachment = VkInit::AttachmentInfo(
+      DrawImageView, VK_NULL_HANDLE, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL);
+  VkRenderingInfo RenderingInfo =
+      VkInit::RenderingInfo(DrawExtent, &ColorAttachment, VK_NULL_HANDLE);
+  vkCmdBeginRendering(CommandBuffer, &RenderingInfo);
+
+  vkCmdBindPipeline(CommandBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, m_Pipeline);
+  vkCmdBindDescriptorSets(CommandBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS,
+                          m_PipelineLayout, 0, 1, &m_DescriptorSet, 0, nullptr);
+
+  VkViewport Viewport{.x = 0.0f,
+                      .y = 0.0f,
+                      .width = static_cast<float>(DrawExtent.width),
+                      .height = static_cast<float>(DrawExtent.height),
+                      .minDepth = 0.0f,
+                      .maxDepth = 1.0f};
+  VkRect2D Scissor{.offset = {0, 0}, .extent = DrawExtent};
+  vkCmdSetViewport(CommandBuffer, 0, 1, &Viewport);
+  vkCmdSetScissor(CommandBuffer, 0, 1, &Scissor);
+
+  const glm::mat4 ViewProjection =
+      Scene.ActiveCamera->GetViewProjectionMatrix();
+  const glm::vec3 CameraRight = Scene.ActiveCamera->GetRight();
+  const glm::vec3 CameraUp = Scene.ActiveCamera->GetUp();
+
+  for (const LightBillboardOverlay &Billboard : Scene.LightBillboards) {
+    BillboardPushConstants Push{};
+    Push.ViewProjection = ViewProjection;
+    Push.WorldPositionAndHalfSize = glm::vec4(
+        Billboard.WorldPosition,
+        ComputeBillboardHalfSizeWorld(*Scene.ActiveCamera, Billboard, DrawExtent));
+    Push.Color = Billboard.Color;
+    Push.CameraRight = glm::vec4(CameraRight, 0.0f);
+    Push.CameraUp = glm::vec4(CameraUp, 0.0f);
+    vkCmdPushConstants(CommandBuffer, m_PipelineLayout,
+                       VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
+                       0, sizeof(BillboardPushConstants), &Push);
+    vkCmdDraw(CommandBuffer, 6, 1, 0, 0);
+  }
+
+  vkCmdEndRendering(CommandBuffer);
+}
+
+} // namespace Axiom
diff --git a/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.h b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.h
new file mode 100644
index 00000000..1569e738
--- /dev/null
+++ b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.h
@@ -0,0 +1,35 @@
+#pragma once
+
+#include "Renderer/RenderScene.h"
+#include "Renderer/Vulkan/VulkanDeletionQueue.h"
+#include "Renderer/Vulkan/VulkanDescriptors.h"
+#include "Renderer/Vulkan/VulkanTypes.h"
+
+namespace Axiom {
+
+class VulkanLightBillboardRenderer {
+public:
+  struct InitInfo {
+    VkDevice Device{VK_NULL_HANDLE};
+    VkFormat DrawImageFormat{VK_FORMAT_UNDEFINED};
+    DescriptorAllocator *DescriptorAllocator{nullptr};
+    VkImageView TextureView{VK_NULL_HANDLE};
+    VkSampler TextureSampler{VK_NULL_HANDLE};
+  };
+
+  void Init(const InitInfo &Info, DeletionQueue &DeletionQueue);
+
+  void DrawLightBillboards(VkCommandBuffer CommandBuffer, VkExtent2D DrawExtent,
+                           VkImageView DrawImageView, const RenderScene &Scene);
+
+  bool IsInitialized() const { return m_Pipeline != VK_NULL_HANDLE; }
+
+private:
+  VkDevice m_Device{VK_NULL_HANDLE};
+  VkDescriptorSetLayout m_DescriptorLayout{VK_NULL_HANDLE};
+  VkDescriptorSet m_DescriptorSet{VK_NULL_HANDLE};
+  VkPipeline m_Pipeline{VK_NULL_HANDLE};
+  VkPipelineLayout m_PipelineLayout{VK_NULL_HANDLE};
+};
+
+} // namespace Axiom
diff --git a/Axiom/Renderer/Vulkan/VulkanRendererBackend.cpp b/Axiom/Renderer/Vulkan/VulkanRendererBackend.cpp
index c43e5ef0..2849cfc4 100644
--- a/Axiom/Renderer/Vulkan/VulkanRendererBackend.cpp
+++ b/Axiom/Renderer/Vulkan/VulkanRendererBackend.cpp
@@ -1,5 +1,6 @@
 #include "Renderer/Vulkan/VulkanRendererBackend.h"
 
+#include "Assets/SvgTexture.h"
 #include "Renderer/RenderScene.h"
 #include "Renderer/Vulkan/VulkanBuffer.h"
 #include "Renderer/Vulkan/VulkanDescriptors.h"
@@ -479,12 +480,23 @@ void VulkanRendererBackend::InitDescriptors() {
 
 void VulkanRendererBackend::InitTextureResources() {
   m_MaterialResources.InitFallbackTexture();
+  const std::filesystem::path LightIconPath =
+      std::filesystem::path(AXIOM_CONTENT_DIR) / "Engine" / "lightbulb.svg";
+  if (const auto IconTexture = Assets::LoadSvgTextureFromFile(LightIconPath)) {
+    m_LightBillboardMaterial = std::make_shared<MaterialInstance>();
+    m_LightBillboardMaterial->BaseColorTexture = IconTexture;
+  } else {
+    A_CORE_WARN("Failed to load light billboard icon from {0}; using fallback texture",
+                LightIconPath.string());
+    m_LightBillboardMaterial = std::make_shared<MaterialInstance>();
+  }
 }
 
 void VulkanRendererBackend::InitPipelines() {
   InitBackgroundPipelines();
   InitMeshPipelines();
   InitGizmoPipeline();
+  InitLightBillboardPipeline();
 }
 
 void VulkanRendererBackend::InitGizmoPipeline() {
@@ -493,6 +505,18 @@ void VulkanRendererBackend::InitGizmoPipeline() {
                         m_MainDeletionQueue);
 }
 
+void VulkanRendererBackend::InitLightBillboardPipeline() {
+  const VkImageView TextureView =
+      m_MaterialResources.ResolveMaterialTextureView(m_LightBillboardMaterial);
+  m_LightBillboardRenderer.Init(
+      {.Device = m_Device.Device,
+       .DrawImageFormat = m_DrawImage.ImageFormat,
+       .DescriptorAllocator = &m_GlobalDescriptorAllocator,
+       .TextureView = TextureView,
+       .TextureSampler = m_TextureSampler},
+      m_MainDeletionQueue);
+}
+
 void VulkanRendererBackend::InitBackgroundPipelines() {
   VkPipelineLayoutCreateInfo ComputeLayout =
       VkInit::PipelineLayoutCreateInfo();
@@ -1309,6 +1333,11 @@ void VulkanRendererBackend::Draw() {
                        VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT,
                        MeshFrame.TimestampQueryPool, 3);
 
+  if (m_ActiveScene != nullptr && m_LightBillboardRenderer.IsInitialized()) {
+    m_LightBillboardRenderer.DrawLightBillboards(
+        CommandBuffer, m_DrawExtent, m_DrawImage.ImageView, *m_ActiveScene);
+  }
+
   if (m_ActiveScene != nullptr && m_GizmoRenderer.IsInitialized()) {
     m_GizmoRenderer.DrawGizmoOverlay(CommandBuffer, m_DrawExtent,
                                      m_DrawImage.ImageView, *m_ActiveScene);
diff --git a/Axiom/Renderer/Vulkan/VulkanRendererBackend.h b/Axiom/Renderer/Vulkan/VulkanRendererBackend.h
index 26461abc..44d8de23 100644
--- a/Axiom/Renderer/Vulkan/VulkanRendererBackend.h
+++ b/Axiom/Renderer/Vulkan/VulkanRendererBackend.h
@@ -9,6 +9,7 @@
 #include "Renderer/Vulkan/VulkanDevice.h"
 #include "Renderer/Vulkan/VulkanGizmoRenderer.h"
 #include "Renderer/Vulkan/VulkanImGuiRenderer.h"
+#include "Renderer/Vulkan/VulkanLightBillboardRenderer.h"
 #include "Renderer/Vulkan/VulkanMaterialResources.h"
 #include "Renderer/Vulkan/VulkanOcclusionCulling.h"
 #include "Renderer/Vulkan/VulkanRendererTypes.h"
@@ -57,6 +58,7 @@ class VulkanRendererBackend final : public RendererBackend {
   void InitBackgroundPipelines();
   void InitMeshPipelines();
   void InitGizmoPipeline();
+  void InitLightBillboardPipeline();
   void InitMeshFrameResources();
 
   void InitHzbResources();
@@ -150,9 +152,11 @@ class VulkanRendererBackend final : public RendererBackend {
   std::array<MeshFrameResources, FRAME_OVERLAP> m_MeshFrames{};
   VulkanGizmoRenderer m_GizmoRenderer;
   VulkanImGuiRenderer m_ImGuiRenderer;
+  VulkanLightBillboardRenderer m_LightBillboardRenderer;
   VulkanMaterialResources m_MaterialResources;
   VulkanOcclusionCulling m_OcclusionCulling;
   VulkanSceneRenderer m_SceneRenderer;
+  MaterialInstanceRef m_LightBillboardMaterial;
   RenderScene *m_ActiveScene{nullptr};
   RendererFrameStats m_FrameStats{};
   float m_TimestampPeriod{0.0f};
diff --git a/Content/Shaders/light_billboard.frag b/Content/Shaders/light_billboard.frag
new file mode 100644
index 00000000..20cfb810
--- /dev/null
+++ b/Content/Shaders/light_billboard.frag
@@ -0,0 +1,12 @@
+#version 460
+
+layout(set = 0, binding = 0) uniform sampler2D iconTexture;
+
+layout(location = 0) in vec2 inUv;
+layout(location = 1) in vec4 inColor;
+layout(location = 0) out vec4 outColor;
+
+void main() {
+    vec4 texel = texture(iconTexture, inUv);
+    outColor = vec4(inColor.rgb * texel.rgb, inColor.a * texel.a);
+}
diff --git a/Content/Shaders/light_billboard.frag.spv b/Content/Shaders/light_billboard.frag.spv
new file mode 100644
index 0000000000000000000000000000000000000000..155d029634e09f5d103b0530a54991d8991a3c56
GIT binary patch
literal 1064
zcmYk4$x1^(5Jg*KoQK4D_9e~=;zC6b1##g<P*HI$nngep&_w(J|IQC`BY4isYj_<h
z)phIEt*%N6-K%{ebcLbNA9h3MltVX20P9Wt<<;HQ-bd?Y@8ED>#%L&{L^)&B_29L)
zr+ULg8Jogpuo7HzG~rf2IfNeyi=g=$;{kH5+E?urU*t1_uRk{%_qDH9`@NRds9kS7
zeBx4$eVXmoMf0`!-obj(zV${2x<pr<ib+n4tDP{7)m+ZSYUX3-Fm~PvCUAyII!#FL
z)7*Q(5^RQk&T8y@3E%yAF>Q`12l3|B%byr8pf^N9p7p~SN$ezxoylXrF}!-dOMVHj
zmbiRlXB0C(iT4-uJ?4#_S<L)2UT(}Ay8|)%&EoARe~Q@MB$#J6i&wZuy@b29)~LUV
zSKIiAU(t8FD~~n5AVs`yb9eqP<ew6|gHg=+jh%5EbG}Ea<V|35#LrN)UQE9EIm~&k
zQFoU43={YGR^Jr)3*6O+{6+3!nkVwV>95`rrl!1eumoSh?CD<Ab@nPIF2|j$VfM*$
z)-zmfYc??J#BVcfle;}V5!>P}=G!8+ong*)!zSFt4raZ4^Xj`Z{}1N=P&mf^0g-4f
A`2YX_

literal 0
HcmV?d00001

diff --git a/Content/Shaders/light_billboard.vert b/Content/Shaders/light_billboard.vert
new file mode 100644
index 00000000..c7fc57b2
--- /dev/null
+++ b/Content/Shaders/light_billboard.vert
@@ -0,0 +1,32 @@
+#version 460
+
+layout(push_constant) uniform BillboardPushConstants {
+    mat4 viewProjection;
+    vec4 worldPositionAndHalfSize;
+    vec4 color;
+    vec4 cameraRight;
+    vec4 cameraUp;
+} push;
+
+layout(location = 0) out vec2 outUv;
+layout(location = 1) out vec4 outColor;
+
+void main() {
+    const vec2 corners[6] = vec2[](
+        vec2(-1.0, -1.0),
+        vec2( 1.0, -1.0),
+        vec2( 1.0,  1.0),
+        vec2(-1.0, -1.0),
+        vec2( 1.0,  1.0),
+        vec2(-1.0,  1.0)
+    );
+
+    vec2 corner = corners[gl_VertexIndex];
+    vec3 worldPosition = push.worldPositionAndHalfSize.xyz +
+                         push.cameraRight.xyz * corner.x * push.worldPositionAndHalfSize.w +
+                         push.cameraUp.xyz * corner.y * push.worldPositionAndHalfSize.w;
+
+    gl_Position = push.viewProjection * vec4(worldPosition, 1.0);
+    outUv = vec2(corner.x * 0.5 + 0.5, 1.0 - (corner.y * 0.5 + 0.5));
+    outColor = push.color;
+}
diff --git a/Content/Shaders/light_billboard.vert.spv b/Content/Shaders/light_billboard.vert.spv
new file mode 100644
index 0000000000000000000000000000000000000000..87e4af51900c7cd0d2ee74ce2aea5d6bd3af3e75
GIT binary patch
literal 2748
zcmZvcYjaao6oyYP2{)x8a#69S6fX!?R6rD=lp;;FN}v|+($nM!$2sJ5k`x#}={SCM
z#$V(g@CW(D8K385?>2VanKx^#cdfnlT6?c#VtjT_l8hw>lD$cm4A-G#943LQS8{1(
zb!DzU=**qJaL$N>$wU=s%v7?k(kJ<TnC4xLqhJZFffP*e8AtxbhFUVoXD3$M4DGVl
z&3gLl)&Bd%y}Ma&kUd%McCsh(wd8r?a?Nz3uvTNIk&nw>(P@?ae2|wGP@|U_<n_EL
zHp;ZuX>Ii%ESBB=AngwN3A^@GenOH*dG@%~D}T(|!_D<%f912c|KwfhcA9DN!)pFh
zbxn0n@eKQFmqkhG<gHhnx6@7^X1(-Ie*eK>o44;FzqW}=hRI|Wxk-6LyPkZ6Lhr4t
zH*8<tyz(x6u~Ykyx7Lc!yMvwjhCb`Vw^-zxH*znaosn(mvrc_mMX~Lx@m9W_%ldr7
za%-^msIqI-dtxt!mWiFL-s=GVH^376<GnQTsk>^R$#=9Fy5yN%oOj`harPy5ZG^KQ
zxz-40A9Cv>oOdnfMO%~i<X&^fyR>Fk<UCJK89DdJc}C>a<vhdwy(8z)rJW+R&2yMj
z%`rm;_o*L6t0NoW81dePw!Q}TUZk8jg1x`u`C^?3w&%O&1ol%%W99VAKMj)P=ReQV
zufBsoPQ;igbYkXXjPD_5Oymv)PCjzahL|C@uR8xQoM)KBJ?cth?cq6O19&I)cqHiZ
zmxJy9M)V&?w{Cm$j!q!$%R6-cOGy3l`d>!s_f3xT-9XA|PZK$VYyi1YnCm2*|3SuB
zi}q~byen%w1;&8!uLPfYqW?6ywQ2iaZvvO`b4Y8ozUY4kJ@)c0y5~o~=UoEU9^*em
z_k7>`2GUr$X*B2ATIBQz&%KHC4E^?{y%e}ucN5!X{4&xy8o|DUbicXve;#amF`u@x
zAN%(FF9B;_zxz`V{r0s1ob!v!rP3Z<#{3OaL%P@BfVIT4oCp8^qwV|q8`Hi*yt$77
zXXq-~jCCd#$Y`z?fSfVLyYEFHZ@gz|8}IwR3TDA6V7zzm8j!z5M(6JJz{$JDfIY<=
z{vVp-G>AFQpv%V`XVK+^Ycz**^A@l+=gA!2@i`#>JGENJ+rT{X3q&|i=RvIBS&Mrw
z1Yg{H5!?Opzl416q1&6j*vtFq=5sD%FCU=G$6hX@%L&)+Uar8|i*p<6xmxKvz06~q
zM?Us)4gLRmS%B9Ud%2G8e)-tTBD($P^PQa;Ir~~hehkdr1lH6*egfpRz26n!zT52a
z{yz;IVw?LcaP}PIZUxSnXfbilPz$)<c>Po05Ay1}4LsWz>+|=s3YLKNS--Y%`kjxv
zVE24{5%}Liy<cI=`P=kf?BQ!5FBfxtgTDKHzJ-&IxxPb}8_o4Sw!GZ0A^$yed(+o~
m^Y^w6JXfE+_}{S(Jm2438~7F*AkJ7P@W!X;+W#<Fm%zXHQNV8i

literal 0
HcmV?d00001

diff --git a/Headless/HeadlessSessionLayer.cpp b/Headless/HeadlessSessionLayer.cpp
index 0460e9b0..2c43a225 100644
--- a/Headless/HeadlessSessionLayer.cpp
+++ b/Headless/HeadlessSessionLayer.cpp
@@ -155,6 +155,9 @@ void HeadlessSessionLayer::OnRender() {
   for (const auto &Submission : m_RendererAdapter->BuildRenderSubmissions(m_Session)) {
     RenderCommand::Submit(Submission);
   }
+  for (const auto &Billboard : BuildLightBillboards()) {
+    RenderCommand::SubmitLightBillboard(Billboard);
+  }
   for (const auto &Submission : BuildPresenceOverlaySubmissions(RenderUser)) {
     RenderCommand::Submit(Submission);
   }
@@ -199,6 +202,31 @@ GizmoMode HeadlessSessionLayer::GetGizmoMode(SessionUserId User) const {
   return It != m_GizmoModeByUser.end() ? It->second : GizmoMode::Translate;
 }
 
+std::vector<LightBillboardOverlay> HeadlessSessionLayer::BuildLightBillboards()
+    const {
+  std::vector<LightBillboardOverlay> Result;
+  for (const auto &[Id, Details] : m_Session.GetState().Scene.ObjectDetailsById) {
+    (void)Id;
+    if (Details.Kind != EditorSceneItemKind::Light || !Details.Visible ||
+        !Details.Light.has_value()) {
+      continue;
+    }
+
+    const EditorTransformDetails *EffectiveTransform =
+        Details.WorldTransform.has_value()  ? &*Details.WorldTransform
+        : Details.Transform.has_value()     ? &*Details.Transform
+                                            : nullptr;
+    Result.push_back({
+        .WorldPosition = EffectiveTransform != nullptr
+            ? EffectiveTransform->Location
+            : glm::vec3(0.0f),
+        .Color = glm::vec4(Details.Light->Color, 1.0f),
+        .PixelSize = 48.0f,
+    });
+  }
+  return Result;
+}
+
 bool HeadlessSessionLayer::LoadStartupSceneIntoSession() {
 #ifndef AXIOM_CONTENT_DIR
 #define AXIOM_CONTENT_DIR "Content"
diff --git a/Headless/HeadlessSessionLayer.h b/Headless/HeadlessSessionLayer.h
index 5d8ed59d..2b00dfe7 100644
--- a/Headless/HeadlessSessionLayer.h
+++ b/Headless/HeadlessSessionLayer.h
@@ -50,6 +50,7 @@ class HeadlessSessionLayer final : public Layer {
   int GetGizmoHoveredAxis(SessionUserId User) const;
   void SetGizmoMode(SessionUserId User, GizmoMode Mode);
   GizmoMode GetGizmoMode(SessionUserId User) const;
+  std::vector<LightBillboardOverlay> BuildLightBillboards() const;
   std::vector<RenderMeshSubmission>
   BuildPresenceOverlaySubmissions(SessionUserId RenderUser) const;
 
diff --git a/Tests/CMakeLists.txt b/Tests/CMakeLists.txt
index 7a8a8e06..75d47dde 100644
--- a/Tests/CMakeLists.txt
+++ b/Tests/CMakeLists.txt
@@ -3,6 +3,7 @@ add_executable(AxiomTests
   HeadlessProtocolTests.cpp
   MeshPickingTests.cpp
   SceneLifecycleTests.cpp
+  ../Headless/HeadlessSessionLayer.cpp
   ../Headless/HeadlessCommandProtocol.cpp
   ../Headless/WebRtcSession.cpp
 )
diff --git a/Tests/LayerTests.cpp b/Tests/LayerTests.cpp
index 3991578b..c2491e9d 100644
--- a/Tests/LayerTests.cpp
+++ b/Tests/LayerTests.cpp
@@ -4,7 +4,11 @@
 #include <Core/Platform.h>
 #include <Core/GlfwEditorInputSource.h>
 #include <Core/InputPlatform.h>
+#include <Assets/SvgTexture.h>
+#include <Renderer/RenderCommand.h>
+#include <Renderer/RenderScene.h>
 #include "../Headless/HeadlessRenderView.h"
+#include "../Headless/HeadlessSessionLayer.h"
 #include "../Headless/HeadlessViewportFrameBridge.h"
 #include <Remote/AxiomSessionEndpoint.h>
 #include <Renderer/OffscreenRenderSurface.h>
@@ -22,6 +26,7 @@
 #include <algorithm>
 #include <array>
 #include <chrono>
+#include <filesystem>
 #include <cstddef>
 #include <thread>
 #include <vector>
@@ -1165,3 +1170,131 @@ TEST(RemoteViewportTests, DefaultVideoEncoderProducesH264PacketsOnMacOS) {
   EXPECT_FALSE(Output.Packets.front().Bytes.empty());
 }
 #endif
+
+TEST(RenderSceneTests, ResetClearsLightBillboardsAndOverlayState) {
+  Axiom::RenderScene Scene;
+  Scene.LightBillboards.push_back({
+      .WorldPosition = {1.0f, 2.0f, 3.0f},
+      .Color = {0.2f, 0.4f, 0.6f, 1.0f},
+      .PixelSize = 64.0f,
+  });
+  Scene.GizmoOverlay = Axiom::GizmoOverlayData{};
+  Scene.Sun = Axiom::DirectionalLight{};
+
+  Scene.Reset();
+
+  EXPECT_TRUE(Scene.LightBillboards.empty());
+  EXPECT_FALSE(Scene.GizmoOverlay.has_value());
+  EXPECT_FALSE(Scene.Sun.has_value());
+}
+
+TEST(RenderSceneTests, RenderCommandSubmitsLightBillboardOverlay) {
+  Axiom::RenderScene Scene;
+  Axiom::RenderCommand::BeginScene(Scene);
+  Axiom::RenderCommand::SubmitLightBillboard({
+      .WorldPosition = {4.0f, 5.0f, 6.0f},
+      .Color = {0.8f, 0.3f, 0.1f, 1.0f},
+      .PixelSize = 40.0f,
+  });
+  Axiom::RenderCommand::EndScene();
+
+  ASSERT_EQ(Scene.LightBillboards.size(), 1u);
+  EXPECT_FLOAT_EQ(Scene.LightBillboards.front().WorldPosition.x, 4.0f);
+  EXPECT_FLOAT_EQ(Scene.LightBillboards.front().Color.g, 0.3f);
+  EXPECT_FLOAT_EQ(Scene.LightBillboards.front().PixelSize, 40.0f);
+}
+
+TEST(HeadlessSessionLayerTests, BuildLightBillboardsUsesVisibleLightsOnly) {
+  Axiom::HeadlessSessionLayer Layer;
+  Layer.GetSession().SetObjectDetails({
+      {
+          .ObjectId = "light-a",
+          .DisplayName = "Light A",
+          .Kind = Axiom::EditorSceneItemKind::Light,
+          .Visible = true,
+          .Transform = Axiom::EditorTransformDetails{
+              .Location = {1.0f, 2.0f, 3.0f},
+          },
+          .Light = Axiom::EditorLightProperties{
+              .Color = {0.1f, 0.7f, 0.4f},
+              .Intensity = 2.0f,
+          },
+      },
+      {
+          .ObjectId = "light-b",
+          .DisplayName = "Light B",
+          .Kind = Axiom::EditorSceneItemKind::Light,
+          .Visible = true,
+          .Transform = Axiom::EditorTransformDetails{
+              .Location = {50.0f, 50.0f, 50.0f},
+          },
+          .WorldTransform = Axiom::EditorTransformDetails{
+              .Location = {-3.0f, 5.0f, 8.0f},
+          },
+          .Light = Axiom::EditorLightProperties{
+              .Color = {0.9f, 0.3f, 0.2f},
+              .Intensity = 1.0f,
+          },
+      },
+      {
+          .ObjectId = "light-hidden",
+          .DisplayName = "Hidden Light",
+          .Kind = Axiom::EditorSceneItemKind::Light,
+          .Visible = false,
+          .Transform = Axiom::EditorTransformDetails{
+              .Location = {9.0f, 9.0f, 9.0f},
+          },
+          .Light = Axiom::EditorLightProperties{},
+      },
+      {
+          .ObjectId = "mesh-a",
+          .DisplayName = "Mesh A",
+          .Kind = Axiom::EditorSceneItemKind::Mesh,
+          .Visible = true,
+      },
+  });
+
+  const std::vector<Axiom::LightBillboardOverlay> Billboards =
+      Layer.BuildLightBillboards();
+
+  ASSERT_EQ(Billboards.size(), 2u);
+  const auto WorldTransformBillboard = std::find_if(
+      Billboards.begin(), Billboards.end(),
+      [](const Axiom::LightBillboardOverlay &Billboard) {
+        return Billboard.WorldPosition.x == -3.0f;
+      });
+  ASSERT_NE(WorldTransformBillboard, Billboards.end());
+  EXPECT_FLOAT_EQ(WorldTransformBillboard->PixelSize, 48.0f);
+  EXPECT_FLOAT_EQ(WorldTransformBillboard->Color.r, 0.9f);
+
+  const auto LocalTransformBillboard = std::find_if(
+      Billboards.begin(), Billboards.end(),
+      [](const Axiom::LightBillboardOverlay &Billboard) {
+        return Billboard.WorldPosition.x == 1.0f;
+      });
+  ASSERT_NE(LocalTransformBillboard, Billboards.end());
+  EXPECT_FLOAT_EQ(LocalTransformBillboard->Color.g, 0.7f);
+  EXPECT_FLOAT_EQ(LocalTransformBillboard->WorldPosition.z, 3.0f);
+}
+
+TEST(SvgTextureTests, LightbulbSvgRasterizesToValidTexture) {
+  const std::filesystem::path IconPath =
+      std::filesystem::path(AXIOM_CONTENT_DIR) / "Engine" / "lightbulb.svg";
+  const auto Texture = Axiom::Assets::LoadSvgTextureFromFile(IconPath, 128);
+
+  ASSERT_NE(Texture, nullptr);
+  EXPECT_TRUE(Texture->IsValid());
+  EXPECT_GT(Texture->Width, 0u);
+  EXPECT_GT(Texture->Height, 0u);
+  EXPECT_EQ(Texture->Pixels.size(),
+            static_cast<size_t>(Texture->Width) *
+                static_cast<size_t>(Texture->Height) * 4u);
+  EXPECT_TRUE(std::any_of(Texture->Pixels.begin(), Texture->Pixels.end(),
+                          [](uint8_t Value) { return Value != 0u; }));
+}
+
+TEST(SvgTextureTests, MissingSvgTextureReturnsNull) {
+  const auto Texture = Axiom::Assets::LoadSvgTextureFromFile(
+      std::filesystem::path(AXIOM_CONTENT_DIR) / "Engine" / "missing-icon.svg");
+  EXPECT_EQ(Texture, nullptr);
+}

From 54fe435502ddb2c63fd4b2e5a2fbe4cdc7e71874 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:18:41 -0500
Subject: [PATCH 05/12] Hit-test light bulb

---
 Axiom/Renderer/RenderScene.h                  |  2 +
 .../Vulkan/VulkanLightBillboardRenderer.cpp   | 24 +----
 Axiom/Session/MeshPicking.h                   | 99 ++++++++++++++++++-
 Headless/HeadlessSessionLayer.cpp             |  1 +
 Headless/RemoteViewportServer.cpp             | 11 ++-
 Tests/LayerTests.cpp                          | 12 ++-
 Tests/MeshPickingTests.cpp                    | 72 ++++++++++++++
 7 files changed, 193 insertions(+), 28 deletions(-)

diff --git a/Axiom/Renderer/RenderScene.h b/Axiom/Renderer/RenderScene.h
index 302ad417..dce28791 100644
--- a/Axiom/Renderer/RenderScene.h
+++ b/Axiom/Renderer/RenderScene.h
@@ -7,6 +7,7 @@
 #include <glm/vec4.hpp>
 
 #include <optional>
+#include <string>
 #include <vector>
 
 namespace Axiom {
@@ -28,6 +29,7 @@ struct DirectionalLight {
 };
 
 struct LightBillboardOverlay {
+  std::string ObjectId;
   glm::vec3 WorldPosition{0.0f};
   glm::vec4 Color{1.0f};
   float PixelSize{48.0f};
diff --git a/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
index f571d08d..3d475172 100644
--- a/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
+++ b/Axiom/Renderer/Vulkan/VulkanLightBillboardRenderer.cpp
@@ -4,6 +4,7 @@
 #include "Renderer/Camera.h"
 #include "Renderer/Vulkan/VulkanInitializers.h"
 #include "Renderer/Vulkan/VulkanPipeline.h"
+#include "Session/MeshPicking.h"
 
 #include <array>
 #include <cmath>
@@ -25,24 +26,6 @@ struct BillboardPushConstants {
 static_assert(sizeof(BillboardPushConstants) <= 128,
               "BillboardPushConstants exceeds guaranteed push constant minimum");
 
-float ComputeBillboardHalfSizeWorld(const Camera &Camera,
-                                    const LightBillboardOverlay &Billboard,
-                                    VkExtent2D DrawExtent) {
-  const glm::vec3 ToBillboard = Billboard.WorldPosition - Camera.GetPosition();
-  const float ForwardDistance =
-      glm::dot(ToBillboard, glm::normalize(Camera.GetForward()));
-  const float Distance = std::max(ForwardDistance, 0.1f);
-  const float ProjectionY = std::abs(Camera.GetProjectionMatrix()[1][1]);
-  if (ProjectionY < 0.0001f || DrawExtent.height == 0) {
-    return 0.1f;
-  }
-
-  const float TanHalfFov = 1.0f / ProjectionY;
-  const float WorldUnitsPerPixel =
-      (2.0f * Distance * TanHalfFov) / static_cast<float>(DrawExtent.height);
-  return std::max(0.01f, Billboard.PixelSize * 0.5f * WorldUnitsPerPixel);
-}
-
 } // namespace
 
 void VulkanLightBillboardRenderer::Init(const InitInfo &Info,
@@ -243,8 +226,9 @@ void VulkanLightBillboardRenderer::DrawLightBillboards(
     BillboardPushConstants Push{};
     Push.ViewProjection = ViewProjection;
     Push.WorldPositionAndHalfSize = glm::vec4(
-        Billboard.WorldPosition,
-        ComputeBillboardHalfSizeWorld(*Scene.ActiveCamera, Billboard, DrawExtent));
+        Billboard.WorldPosition, ComputeBillboardHalfSizeWorld(
+                                     *Scene.ActiveCamera, Billboard.WorldPosition,
+                                     Billboard.PixelSize, DrawExtent.height));
     Push.Color = Billboard.Color;
     Push.CameraRight = glm::vec4(CameraRight, 0.0f);
     Push.CameraUp = glm::vec4(CameraUp, 0.0f);
diff --git a/Axiom/Session/MeshPicking.h b/Axiom/Session/MeshPicking.h
index c3951429..81e38f4b 100644
--- a/Axiom/Session/MeshPicking.h
+++ b/Axiom/Session/MeshPicking.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#include <Renderer/RenderScene.h>
 #include <Renderer/Camera.h>
 #include <Session/EditorSession.h>
 
@@ -21,12 +22,14 @@ struct ViewportRay {
   glm::vec3 Direction{0.0f, 0.0f, -1.0f};
 };
 
-struct MeshHitResult {
+struct ViewportObjectHitResult {
   std::string ObjectId;
   glm::vec3 WorldPosition{0.0f};
   float Distance{0.0f};
 };
 
+using MeshHitResult = ViewportObjectHitResult;
+
 inline std::optional<ViewportRay>
 BuildViewportRay(const Camera &Cam, uint32_t VpWidth, uint32_t VpHeight,
                  glm::vec2 MousePixel) {
@@ -132,6 +135,100 @@ HitTestMeshesDetailed(const Camera &Cam, uint32_t VpWidth, uint32_t VpHeight,
   return BestHit;
 }
 
+inline float ComputeBillboardHalfSizeWorld(const Camera &Cam,
+                                           const glm::vec3 &WorldPosition,
+                                           float PixelSize,
+                                           uint32_t VpHeight) {
+  const glm::vec3 ToBillboard = WorldPosition - Cam.GetPosition();
+  const float ForwardDistance =
+      glm::dot(ToBillboard, glm::normalize(Cam.GetForward()));
+  const float Distance = std::max(ForwardDistance, 0.1f);
+  const float ProjectionY = glm::abs(Cam.GetProjectionMatrix()[1][1]);
+  if (ProjectionY < 0.0001f || VpHeight == 0) {
+    return 0.1f;
+  }
+
+  const float TanHalfFov = 1.0f / ProjectionY;
+  const float WorldUnitsPerPixel =
+      (2.0f * Distance * TanHalfFov) / static_cast<float>(VpHeight);
+  return std::max(0.01f, PixelSize * 0.5f * WorldUnitsPerPixel);
+}
+
+inline std::optional<ViewportObjectHitResult>
+HitTestLightBillboardsDetailed(const Camera &Cam, uint32_t VpWidth,
+                               uint32_t VpHeight, glm::vec2 MousePixel,
+                               const std::vector<LightBillboardOverlay> &Billboards) {
+  const auto Ray = BuildViewportRay(Cam, VpWidth, VpHeight, MousePixel);
+  if (!Ray.has_value() || Billboards.empty()) {
+    return std::nullopt;
+  }
+
+  const glm::vec3 PlaneNormal = glm::normalize(Cam.GetForward());
+  const glm::vec3 PlaneRight = Cam.GetRight();
+  const glm::vec3 PlaneUp = Cam.GetUp();
+
+  float BestDistance = std::numeric_limits<float>::infinity();
+  std::optional<ViewportObjectHitResult> BestHit;
+  for (const LightBillboardOverlay &Billboard : Billboards) {
+    const float Denominator = glm::dot(Ray->Direction, PlaneNormal);
+    if (glm::abs(Denominator) < 1e-6f) {
+      continue;
+    }
+
+    const float Distance =
+        glm::dot(Billboard.WorldPosition - Ray->Origin, PlaneNormal) /
+        Denominator;
+    if (Distance < 0.0f) {
+      continue;
+    }
+
+    const glm::vec3 WorldHit = Ray->Origin + Ray->Direction * Distance;
+    const glm::vec3 Delta = WorldHit - Billboard.WorldPosition;
+    const float HalfSize = ComputeBillboardHalfSizeWorld(
+        Cam, Billboard.WorldPosition, Billboard.PixelSize, VpHeight);
+    const float AlongRight = glm::dot(Delta, PlaneRight);
+    const float AlongUp = glm::dot(Delta, PlaneUp);
+    if (glm::abs(AlongRight) > HalfSize || glm::abs(AlongUp) > HalfSize) {
+      continue;
+    }
+
+    if (Distance < BestDistance) {
+      BestDistance = Distance;
+      BestHit = ViewportObjectHitResult{
+          .ObjectId = Billboard.ObjectId,
+          .WorldPosition = WorldHit,
+          .Distance = Distance,
+      };
+    }
+  }
+
+  return BestHit;
+}
+
+inline std::optional<ViewportObjectHitResult>
+ResolveViewportSelectionHit(const Camera &Cam, uint32_t VpWidth,
+                            uint32_t VpHeight, glm::vec2 MousePixel,
+                            const std::vector<EditorSceneMeshInstance> &Instances,
+                            const std::vector<LightBillboardOverlay> &Billboards) {
+  const auto MeshHit =
+      HitTestMeshesDetailed(Cam, VpWidth, VpHeight, MousePixel, Instances);
+  const auto BillboardHit = HitTestLightBillboardsDetailed(
+      Cam, VpWidth, VpHeight, MousePixel, Billboards);
+
+  if (MeshHit.has_value() && BillboardHit.has_value()) {
+    return MeshHit->Distance <= BillboardHit->Distance
+               ? std::optional<ViewportObjectHitResult>(*MeshHit)
+               : BillboardHit;
+  }
+  if (MeshHit.has_value()) {
+    return *MeshHit;
+  }
+  if (BillboardHit.has_value()) {
+    return BillboardHit;
+  }
+  return std::nullopt;
+}
+
 // Returns the ObjectId of the closest mesh instance hit by a ray cast from the
 // camera through MousePixel, or an empty string if no mesh is hit. Uses AABB
 // slab intersection in object space to handle arbitrary transforms correctly.
diff --git a/Headless/HeadlessSessionLayer.cpp b/Headless/HeadlessSessionLayer.cpp
index 2c43a225..7457f768 100644
--- a/Headless/HeadlessSessionLayer.cpp
+++ b/Headless/HeadlessSessionLayer.cpp
@@ -217,6 +217,7 @@ std::vector<LightBillboardOverlay> HeadlessSessionLayer::BuildLightBillboards()
         : Details.Transform.has_value()     ? &*Details.Transform
                                             : nullptr;
     Result.push_back({
+        .ObjectId = Details.ObjectId,
         .WorldPosition = EffectiveTransform != nullptr
             ? EffectiveTransform->Location
             : glm::vec3(0.0f),
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index 8c8cb15a..99999eca 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -2118,13 +2118,14 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
       }
     }
 
-    // No gizmo hit — fall back to mesh picking.
-    const std::string HitId = HitTestMeshes(
+    // No gizmo hit — fall back to viewport object picking.
+    const auto Hit = ResolveViewportSelectionHit(
         Viewport->Camera, m_Options.Width, m_Options.Height,
-        Command->MousePosition, Session.GetState().Scene.MeshInstances);
-    if (!HitId.empty()) {
+        Command->MousePosition, Session.GetState().Scene.MeshInstances,
+        m_Host.GetHeadlessLayer().BuildLightBillboards());
+    if (Hit.has_value() && !Hit->ObjectId.empty()) {
       m_Host.SubmitRemoteCommand(Client->User,
-          EditorCommand{SelectObjectCommand{.ObjectId = HitId}});
+          EditorCommand{SelectObjectCommand{.ObjectId = Hit->ObjectId}});
     }
     return true;
   }
diff --git a/Tests/LayerTests.cpp b/Tests/LayerTests.cpp
index c2491e9d..9adb3c15 100644
--- a/Tests/LayerTests.cpp
+++ b/Tests/LayerTests.cpp
@@ -1192,6 +1192,7 @@ TEST(RenderSceneTests, RenderCommandSubmitsLightBillboardOverlay) {
   Axiom::RenderScene Scene;
   Axiom::RenderCommand::BeginScene(Scene);
   Axiom::RenderCommand::SubmitLightBillboard({
+      .ObjectId = "light-test",
       .WorldPosition = {4.0f, 5.0f, 6.0f},
       .Color = {0.8f, 0.3f, 0.1f, 1.0f},
       .PixelSize = 40.0f,
@@ -1199,6 +1200,7 @@ TEST(RenderSceneTests, RenderCommandSubmitsLightBillboardOverlay) {
   Axiom::RenderCommand::EndScene();
 
   ASSERT_EQ(Scene.LightBillboards.size(), 1u);
+  EXPECT_EQ(Scene.LightBillboards.front().ObjectId, "light-test");
   EXPECT_FLOAT_EQ(Scene.LightBillboards.front().WorldPosition.x, 4.0f);
   EXPECT_FLOAT_EQ(Scene.LightBillboards.front().Color.g, 0.3f);
   EXPECT_FLOAT_EQ(Scene.LightBillboards.front().PixelSize, 40.0f);
@@ -1261,20 +1263,26 @@ TEST(HeadlessSessionLayerTests, BuildLightBillboardsUsesVisibleLightsOnly) {
   const auto WorldTransformBillboard = std::find_if(
       Billboards.begin(), Billboards.end(),
       [](const Axiom::LightBillboardOverlay &Billboard) {
-        return Billboard.WorldPosition.x == -3.0f;
+        return Billboard.ObjectId == "light-b";
       });
   ASSERT_NE(WorldTransformBillboard, Billboards.end());
   EXPECT_FLOAT_EQ(WorldTransformBillboard->PixelSize, 48.0f);
   EXPECT_FLOAT_EQ(WorldTransformBillboard->Color.r, 0.9f);
+  EXPECT_FLOAT_EQ(WorldTransformBillboard->WorldPosition.x, -3.0f);
 
   const auto LocalTransformBillboard = std::find_if(
       Billboards.begin(), Billboards.end(),
       [](const Axiom::LightBillboardOverlay &Billboard) {
-        return Billboard.WorldPosition.x == 1.0f;
+        return Billboard.ObjectId == "light-a";
       });
   ASSERT_NE(LocalTransformBillboard, Billboards.end());
   EXPECT_FLOAT_EQ(LocalTransformBillboard->Color.g, 0.7f);
   EXPECT_FLOAT_EQ(LocalTransformBillboard->WorldPosition.z, 3.0f);
+  EXPECT_EQ(std::find_if(Billboards.begin(), Billboards.end(),
+                         [](const Axiom::LightBillboardOverlay &Billboard) {
+                           return Billboard.ObjectId == "light-hidden";
+                         }),
+            Billboards.end());
 }
 
 TEST(SvgTextureTests, LightbulbSvgRasterizesToValidTexture) {
diff --git a/Tests/MeshPickingTests.cpp b/Tests/MeshPickingTests.cpp
index 2107a241..987b3484 100644
--- a/Tests/MeshPickingTests.cpp
+++ b/Tests/MeshPickingTests.cpp
@@ -37,6 +37,78 @@ TEST(MeshPickingTests, HitTestMeshesDetailedReturnsWorldHitPosition) {
   EXPECT_NEAR(Hit->WorldPosition.z, 0.5f, 1e-3f);
 }
 
+TEST(MeshPickingTests, HitTestLightBillboardsDetailedReturnsLightHit) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+  const std::vector<Axiom::LightBillboardOverlay> Billboards{{
+      .ObjectId = "key-light",
+      .WorldPosition = {0.0f, 1.0f, 0.0f},
+      .PixelSize = 48.0f,
+  }};
+
+  const auto Hit = Axiom::HitTestLightBillboardsDetailed(
+      Camera, 1280, 720, {640.0f, 360.0f}, Billboards);
+
+  ASSERT_TRUE(Hit.has_value());
+  EXPECT_EQ(Hit->ObjectId, "key-light");
+  EXPECT_NEAR(Hit->WorldPosition.x, 0.0f, 1e-3f);
+  EXPECT_NEAR(Hit->WorldPosition.y, 1.0f, 1e-3f);
+  EXPECT_NEAR(Hit->WorldPosition.z, 0.0f, 1e-3f);
+  EXPECT_NEAR(Hit->Distance, 5.0f, 1e-3f);
+}
+
+TEST(MeshPickingTests, HitTestLightBillboardsDetailedMissesOutsideQuad) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+  const std::vector<Axiom::LightBillboardOverlay> Billboards{{
+      .ObjectId = "key-light",
+      .WorldPosition = {0.0f, 1.0f, 0.0f},
+      .PixelSize = 48.0f,
+  }};
+
+  const auto Hit =
+      Axiom::HitTestLightBillboardsDetailed(Camera, 1280, 720, {0.0f, 0.0f}, Billboards);
+
+  EXPECT_FALSE(Hit.has_value());
+}
+
+TEST(MeshPickingTests, ResolveViewportSelectionHitChoosesNearestObjectHit) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+  const std::vector<Axiom::EditorSceneMeshInstance> Instances{{
+      .ObjectId = "crate",
+      .Mesh = Axiom::MeshData{
+          .BoundsMin = {-0.5f, -0.5f, -0.5f},
+          .BoundsMax = {0.5f, 0.5f, 0.5f},
+      },
+      .Transform = glm::translate(glm::mat4(1.0f), glm::vec3(0.0f, 1.0f, 2.0f)),
+  }};
+  const std::vector<Axiom::LightBillboardOverlay> Billboards{{
+      .ObjectId = "key-light",
+      .WorldPosition = {0.0f, 1.0f, 0.0f},
+      .PixelSize = 48.0f,
+  }};
+
+  const auto Hit = Axiom::ResolveViewportSelectionHit(
+      Camera, 1280, 720, {640.0f, 360.0f}, Instances, Billboards);
+
+  ASSERT_TRUE(Hit.has_value());
+  EXPECT_EQ(Hit->ObjectId, "crate");
+  EXPECT_LT(Hit->Distance, 5.0f);
+}
+
+TEST(MeshPickingTests, ResolveViewportSelectionHitUsesBillboardWhenMeshMisses) {
+  const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 1.0f, 0.0f});
+  const std::vector<Axiom::LightBillboardOverlay> Billboards{{
+      .ObjectId = "key-light",
+      .WorldPosition = {0.0f, 1.0f, 0.0f},
+      .PixelSize = 48.0f,
+  }};
+
+  const auto Hit = Axiom::ResolveViewportSelectionHit(
+      Camera, 1280, 720, {640.0f, 360.0f}, {}, Billboards);
+
+  ASSERT_TRUE(Hit.has_value());
+  EXPECT_EQ(Hit->ObjectId, "key-light");
+}
+
 TEST(MeshPickingTests, ResolveViewportDropPositionFallsBackToGroundPlane) {
   const Axiom::Camera Camera = MakeCamera({0.0f, 1.0f, 5.0f}, {0.0f, 0.0f, 0.0f});
 

From d9c02d0e6735c5d6592435fe1518ba141c6e1f84 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:19:54 -0500
Subject: [PATCH 06/12] Update docs

---
 Docs/DistributedWraithEngineDesign.md | 2 ++
 Docs/HeadlessAxiomSessionPrototype.md | 8 ++++++++
 README.md                             | 2 ++
 3 files changed, 12 insertions(+)

diff --git a/Docs/DistributedWraithEngineDesign.md b/Docs/DistributedWraithEngineDesign.md
index 792be051..80e90850 100644
--- a/Docs/DistributedWraithEngineDesign.md
+++ b/Docs/DistributedWraithEngineDesign.md
@@ -47,6 +47,8 @@
 - `VulkanGizmoRenderer` draws mode-appropriate handles: arrows for translate, arrows with perpendicular cross-caps for scale, and 24-segment screen-space rings for rotate; the hovered handle brightens in all modes
 - Gizmo mouse coordinates are forwarded using the correct `object-contain` content rect mapping so hit-testing is accurate regardless of the viewport aspect ratio or window size
 - `gizmoMode` state lives in `RemoteViewportContext` so the toolbar and viewport share a single source of truth without prop drilling
+- Mesh assets can now be dragged from the content browser into the remote viewport to create mesh objects directly at the cursor-resolved spawn point
+- Visible lights now render as color-tinted billboard icons in the remote viewport, and those billboards participate in remote click selection using the same gizmo-first input path
 - Collaboration v1 is now implemented: object locking, selection/lock visibility, presence roster, heartbeat-driven idle detection, and two-threshold disconnect (Away at 10 s, Disconnected at 30 s with lock release)
 - `EditorObjectLockState` (`Unlocked` / `Locked`) and `EditorObjectCollaborationState` live in `EditorSessionState`; `AcquireLock`, `ReleaseLock`, and `ReleaseAllLocksForUser` are public `EditorSession` methods
 - `ValidateCommand` rejects any mutating command (`SetTransform`, `Rename`, `SetObjectVisibility`, `Delete`, `Reparent`) on an object locked by a different user
diff --git a/Docs/HeadlessAxiomSessionPrototype.md b/Docs/HeadlessAxiomSessionPrototype.md
index 0816cafd..7101aee0 100644
--- a/Docs/HeadlessAxiomSessionPrototype.md
+++ b/Docs/HeadlessAxiomSessionPrototype.md
@@ -264,6 +264,14 @@ A server-side transform gizmo is now fully implemented on the `scene-editing` br
 ### Coordinate Mapping Fix
 - mouse pixel coordinates sent to the server account for the `object-contain` CSS letterboxing on the video element: the actual content rectangle is computed from the uniform scale factor and centering offsets before mapping to server pixels, so hit-testing is accurate regardless of window aspect ratio
 
+## Viewport Object Interaction
+
+- dragging a mesh asset from the content browser into the remote viewport now creates a new mesh object directly at the resolved drop point; the server prefers mesh-surface hit, then ground-plane intersection, then a fixed point in front of the camera
+- visible light objects are rendered as camera-facing `lightbulb.svg` billboards tinted from the light color
+- remote viewport click selection now considers those light billboards in addition to mesh hits
+- selection remains gizmo-first; if no gizmo handle is hit, the server compares the nearest mesh hit and nearest light-billboard hit and selects whichever is closer in world space
+- billboard selection targets the underlying light object id; hidden lights do not expose selectable billboards
+
 ## Collaboration v1
 
 Object locking, selection/lock visibility, presence indicators, and heartbeat-driven idle detection are now fully implemented.
diff --git a/README.md b/README.md
index 16bf38f6..e67c61fb 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,8 @@ AxiomRemoteViewportServer  (C++)
 - Scene outliner with drag-drop reparenting, inline rename, right-click context menus
 - Object lifecycle: create, duplicate, delete
 - Per-client gizmo mode (Q / E / R shortcuts)
+- Drag meshes into the remote viewport to add them directly
+- Light icons render as color-tinted billboards and are selectable from the remote viewport
 - User presence and camera visualization
 - Script class attachment and hot-reload button
 

From 8f7c5a35b99eb57b8442d2052e23ecd1c684ff37 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:21:57 -0500
Subject: [PATCH 07/12] Sync gizmo transform with details transform

---
 EditorFrontend/components/engine/details.tsx | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/EditorFrontend/components/engine/details.tsx b/EditorFrontend/components/engine/details.tsx
index b4b8be98..3eb174db 100644
--- a/EditorFrontend/components/engine/details.tsx
+++ b/EditorFrontend/components/engine/details.tsx
@@ -84,9 +84,23 @@ function DetailsContent({
 
   useEffect(() => {
     setDraftName(details.displayName)
-    setDraft(toDraft(details))
   }, [details.objectId])
 
+  useEffect(() => {
+    setDraft(toDraft(details))
+  }, [
+    details.objectId,
+    details.transform?.location[0],
+    details.transform?.location[1],
+    details.transform?.location[2],
+    details.transform?.rotationDegrees[0],
+    details.transform?.rotationDegrees[1],
+    details.transform?.rotationDegrees[2],
+    details.transform?.scale[0],
+    details.transform?.scale[1],
+    details.transform?.scale[2],
+  ])
+
   const schemaTransformReadOnly =
     schema?.properties.find((p) => p.name === "location")?.readOnly ?? null
   const canEdit =

From 48a7f7b9e104d302a5964d2b4e885b55f1fb98f3 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:28:30 -0500
Subject: [PATCH 08/12] Grid snap

---
 .../engine/remote-viewport-context.tsx        |  14 +
 EditorFrontend/components/engine/toolbar.tsx  |   9 +-
 EditorFrontend/components/engine/viewport.tsx | 256 +++++++++---------
 Headless/AxiomHeadless.cpp                    |   5 +
 Headless/DevRemoteViewportClient.cpp          |   5 +
 Headless/HeadlessCommandProtocol.cpp          |   8 +
 Headless/HeadlessCommandProtocol.h            |   2 +
 Headless/RemoteViewportServer.cpp             |  43 +++
 Headless/RemoteViewportServer.h               |   1 +
 Tests/HeadlessProtocolTests.cpp               |  10 +
 10 files changed, 225 insertions(+), 128 deletions(-)

diff --git a/EditorFrontend/components/engine/remote-viewport-context.tsx b/EditorFrontend/components/engine/remote-viewport-context.tsx
index f697ecce..a2cd0641 100644
--- a/EditorFrontend/components/engine/remote-viewport-context.tsx
+++ b/EditorFrontend/components/engine/remote-viewport-context.tsx
@@ -130,6 +130,7 @@ interface RemoteViewportActions {
   toggleLook: () => Promise<void>
   setMode: (mode: RemoteViewportViewMode) => Promise<void>
   setGizmoMode: (mode: RemoteViewportGizmoMode) => Promise<void>
+  setGridSnapEnabled: (enabled: boolean) => Promise<void>
   refreshSessionSnapshot: () => Promise<void>
   selectObject: (objectId: string) => Promise<boolean>
   renameObject: (objectId: string, displayName: string) => Promise<boolean>
@@ -181,6 +182,7 @@ interface RemoteViewportContextValue {
   sessionDetailText: string
   viewMode: RemoteViewportViewMode
   gizmoMode: RemoteViewportGizmoMode
+  gridSnapEnabled: boolean
   isLooking: boolean
   eventLog: string[]
   serverOrigin: string
@@ -254,6 +256,7 @@ interface RemoteViewportContextValue {
   toggleLook: () => Promise<void>
   setMode: (mode: RemoteViewportViewMode) => Promise<void>
   setGizmoMode: (mode: RemoteViewportGizmoMode) => Promise<void>
+  setGridSnapEnabled: (enabled: boolean) => Promise<void>
   refreshSessionSnapshot: () => Promise<void>
   selectObject: (objectId: string) => Promise<boolean>
   renameObject: (objectId: string, displayName: string) => Promise<boolean>
@@ -303,6 +306,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
     toggleLook: async () => {},
     setMode: async () => {},
     setGizmoMode: async () => {},
+    setGridSnapEnabled: async () => {},
     refreshSessionSnapshot: async () => {},
     selectObject: async () => false,
     renameObject: async () => false,
@@ -335,6 +339,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
   )
   const [viewMode, setViewMode] = useState<RemoteViewportViewMode>("lit")
   const [gizmoMode, setGizmoModeState] = useState<RemoteViewportGizmoMode>("translate")
+  const [gridSnapEnabled, setGridSnapEnabledState] = useState(false)
   const [isLooking, setIsLooking] = useState(false)
   const [eventLog, setEventLog] = useState<string[]>([])
   const [serverOrigin, setServerOrigin] = useState("")
@@ -447,6 +452,11 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
     await actionsRef.current.setGizmoMode(mode)
   }, [])
 
+  const setGridSnapEnabled = useCallback(async (enabled: boolean) => {
+    setGridSnapEnabledState(enabled)
+    await actionsRef.current.setGridSnapEnabled(enabled)
+  }, [])
+
   const refreshSessionSnapshot = useCallback(async () => {
     await actionsRef.current.refreshSessionSnapshot()
   }, [])
@@ -568,6 +578,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       sessionDetailText,
       viewMode,
       gizmoMode,
+      gridSnapEnabled,
       isLooking,
       eventLog,
       serverOrigin,
@@ -621,6 +632,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       toggleLook,
       setMode,
       setGizmoMode: setGizmoModeAction,
+      setGridSnapEnabled,
       refreshSessionSnapshot,
       selectObject,
       renameObject,
@@ -646,6 +658,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       frameText,
       isLooking,
       participants,
+      gridSnapEnabled,
       sessionDetailText,
       sessionState,
       sessionStatusText,
@@ -682,6 +695,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       gizmoMode,
       setMode,
       setGizmoModeAction,
+      setGridSnapEnabled,
       setSessionDetailText,
       setSessionState,
       setSessionSnapshot,
diff --git a/EditorFrontend/components/engine/toolbar.tsx b/EditorFrontend/components/engine/toolbar.tsx
index dfe4a754..d60c153d 100644
--- a/EditorFrontend/components/engine/toolbar.tsx
+++ b/EditorFrontend/components/engine/toolbar.tsx
@@ -29,7 +29,9 @@ import { PresenceRoster } from "./presence-roster"
 export function Toolbar() {
   const {
     gizmoMode,
+    gridSnapEnabled,
     setGizmoMode,
+    setGridSnapEnabled,
     saveScene,
     saveStatus,
     setSaveStatus,
@@ -117,7 +119,12 @@ export function Toolbar() {
       <ToolbarDivider />
 
       <ToolbarGroup>
-        <ToolbarButton icon={Grid3X3} tooltip="Grid Snap" />
+        <ToolbarButton
+          icon={Grid3X3}
+          tooltip="Grid Snap (1u / 15deg / 0.1x)"
+          active={gridSnapEnabled}
+          onClick={() => void setGridSnapEnabled(!gridSnapEnabled)}
+        />
         <ToolbarButton icon={Layers} tooltip="Layers" />
       </ToolbarGroup>
 
diff --git a/EditorFrontend/components/engine/viewport.tsx b/EditorFrontend/components/engine/viewport.tsx
index 8ab914e7..cbb3f0f7 100644
--- a/EditorFrontend/components/engine/viewport.tsx
+++ b/EditorFrontend/components/engine/viewport.tsx
@@ -3,8 +3,6 @@
 import { useEffect, useRef, useState, type ElementType } from "react"
 import {
   Maximize2,
-  Grid3X3,
-  Eye,
   Camera,
   ChevronDown,
 } from "lucide-react"
@@ -90,129 +88,133 @@ interface SessionConnectResponse {
 
 type RemoteViewportCommand =
   | {
-      type: "set_view_mode"
-      viewMode: ViewMode
-    }
+    type: "set_view_mode"
+    viewMode: ViewMode
+  }
   | {
-      type: "set_look_active"
-      isLooking: boolean
-      cursorPosition: [number, number]
-    }
+    type: "set_look_active"
+    isLooking: boolean
+    cursorPosition: [number, number]
+  }
   | {
-      type: "update_viewport_camera"
-      worldMovement: [number, number, number]
-      cursorPosition: [number, number]
-    }
+    type: "update_viewport_camera"
+    worldMovement: [number, number, number]
+    cursorPosition: [number, number]
+  }
   | {
-      type: "set_viewport_camera_pose"
-      position: [number, number, number]
-      yawDegrees: number
-      pitchDegrees: number
-    }
+    type: "set_viewport_camera_pose"
+    position: [number, number, number]
+    yawDegrees: number
+    pitchDegrees: number
+  }
   | {
-      type: "select_object"
-      objectId: string
-    }
+    type: "select_object"
+    objectId: string
+  }
   | {
-      type: "rename_object"
-      objectId: string
-      displayName: string
-    }
+    type: "rename_object"
+    objectId: string
+    displayName: string
+  }
   | {
-      type: "set_object_visibility"
-      objectId: string
-      visible: boolean
-    }
+    type: "set_object_visibility"
+    objectId: string
+    visible: boolean
+  }
   | ({
-      type: "set_transform"
-    } & SessionObjectTransformUpdate)
+    type: "set_transform"
+  } & SessionObjectTransformUpdate)
   | {
-      type: "create_object"
-      templateId: string
-    }
+    type: "create_object"
+    templateId: string
+  }
   | {
-      type: "duplicate_object"
-      objectId: string
-    }
+    type: "duplicate_object"
+    objectId: string
+  }
   | {
-      type: "delete_object"
-      objectId: string
-    }
+    type: "delete_object"
+    objectId: string
+  }
   | {
-      type: "reparent_object"
-      objectId: string
-      newParentId: string
-    }
+    type: "reparent_object"
+    objectId: string
+    newParentId: string
+  }
   | {
-      type: "gizmo_hover"
-      mouseX: number
-      mouseY: number
-    }
+    type: "gizmo_hover"
+    mouseX: number
+    mouseY: number
+  }
   | {
-      type: "gizmo_drag_start"
-      mouseX: number
-      mouseY: number
-    }
+    type: "gizmo_drag_start"
+    mouseX: number
+    mouseY: number
+  }
   | {
-      type: "gizmo_drag_update"
-      mouseX: number
-      mouseY: number
-    }
+    type: "gizmo_drag_update"
+    mouseX: number
+    mouseY: number
+  }
   | {
-      type: "gizmo_drag_end"
-      mouseX: number
-      mouseY: number
-    }
+    type: "gizmo_drag_end"
+    mouseX: number
+    mouseY: number
+  }
   | {
-      type: "set_gizmo_mode"
-      mode: GizmoMode
-    }
+    type: "set_gizmo_mode"
+    mode: GizmoMode
+  }
+  | {
+    type: "set_grid_snap"
+    enabled: boolean
+  }
   | { type: "heartbeat" }
   | { type: "list_assets" }
   | { type: "get_schema"; objectId: string }
   | { type: "save_scene" }
   | {
-      type: "set_property"
-      objectId: string
-      property: string
-      value: string | boolean | [number, number, number]
-    }
+    type: "set_property"
+    objectId: string
+    property: string
+    value: string | boolean | [number, number, number]
+  }
   | { type: "reload_scripts" }
   | {
-      type: "set_mesh_asset"
-      objectId: string
-      assetPath: string
-    }
+    type: "set_mesh_asset"
+    objectId: string
+    assetPath: string
+  }
   | {
-      type: "set_light_properties"
-      objectId: string
-      color: [number, number, number]
-      intensity: number
-    }
+    type: "set_light_properties"
+    objectId: string
+    color: [number, number, number]
+    intensity: number
+  }
   | {
-      type: "set_material_properties"
-      objectId: string
-      baseColorFactor: [number, number, number, number]
-      metallic: number
-      roughness: number
-    }
+    type: "set_material_properties"
+    objectId: string
+    baseColorFactor: [number, number, number, number]
+    metallic: number
+    roughness: number
+  }
   | {
-      type: "set_material_texture"
-      objectId: string
-      textureAssetPath: string
-    }
+    type: "set_material_texture"
+    objectId: string
+    textureAssetPath: string
+  }
   | {
-      type: "drop_mesh"
-      mouseX: number
-      mouseY: number
-      assetPath: string
-    }
+    type: "drop_mesh"
+    mouseX: number
+    mouseY: number
+    assetPath: string
+  }
   | {
-      type: "drop_texture"
-      mouseX: number
-      mouseY: number
-      textureAssetPath: string
-    }
+    type: "drop_texture"
+    mouseX: number
+    mouseY: number
+    textureAssetPath: string
+  }
 
 function getServerOrigin() {
   const configuredOrigin = process.env.NEXT_PUBLIC_AXIOM_SERVER_ORIGIN?.trim()
@@ -258,9 +260,9 @@ export function Viewport() {
   const isLookingRef = useRef(false)
   const viewModeRef = useRef<ViewMode>("lit")
   const gizmoModeRef = useRef<GizmoMode>("translate")
-  const setGizmoModeCtxRef = useRef<(mode: GizmoMode) => Promise<void>>(async () => {})
+  const setGizmoModeCtxRef = useRef<(mode: GizmoMode) => Promise<void>>(async () => { })
   const notifyServerOnDestroyRef = useRef(true)
-  const connectRef = useRef<() => Promise<void>>(async () => {})
+  const connectRef = useRef<() => Promise<void>>(async () => { })
   const sendCommandRef = useRef<
     (command: RemoteViewportCommand, preferredChannel?: ChannelPreference) => Promise<boolean>
   >(async () => false)
@@ -513,8 +515,8 @@ export function Viewport() {
         const errorPayload = payload as { detail?: string; message?: string } | null
         throw new Error(
           errorPayload?.detail ??
-            errorPayload?.message ??
-            `${response.status} ${response.statusText}`
+          errorPayload?.message ??
+          `${response.status} ${response.statusText}`
         )
       }
 
@@ -1620,6 +1622,9 @@ export function Viewport() {
         gizmoModeRef.current = nextMode
         await sendCommand({ type: "set_gizmo_mode", mode: nextMode }, "reliable")
       },
+      setGridSnapEnabled: async (enabled) => {
+        await sendCommand({ type: "set_grid_snap", enabled }, "reliable")
+      },
     })
     setServerOrigin(serverOrigin)
     setupClientIdClaimChannel()
@@ -1807,29 +1812,29 @@ export function Viewport() {
       lastDragY = event.clientY
     }
 
-    ;(window as any).__axiomViewportDropHandler = (clientX: number, clientY: number, kind: string, path: string) => {
-      if ((kind !== "texture" && kind !== "mesh") || !path) return
-      const x = lastDragX || clientX
-      const y = lastDragY || clientY
-      const s = viewportShellRef.current
-      const v = videoRef.current
-      if (!s || !v || !v.videoWidth || !v.videoHeight) return
-      const rect = s.getBoundingClientRect()
-      if (x < rect.left || x > rect.right || y < rect.top || y > rect.bottom) return
-      const scale = Math.min(rect.width / v.videoWidth, rect.height / v.videoHeight)
-      const contentW = v.videoWidth * scale
-      const contentH = v.videoHeight * scale
-      const cssX = x - rect.left - (rect.width - contentW) / 2
-      const cssY = y - rect.top - (rect.height - contentH) / 2
-      if (cssX < 0 || cssY < 0 || cssX > contentW || cssY > contentH) return
-      const mouseX = (cssX / contentW) * v.videoWidth
-      const mouseY = (cssY / contentH) * v.videoHeight
-      if (kind === "mesh") {
-        void sendCommand({ type: "drop_mesh", mouseX, mouseY, assetPath: path }, "reliable")
-        return
+      ; (window as any).__axiomViewportDropHandler = (clientX: number, clientY: number, kind: string, path: string) => {
+        if ((kind !== "texture" && kind !== "mesh") || !path) return
+        const x = lastDragX || clientX
+        const y = lastDragY || clientY
+        const s = viewportShellRef.current
+        const v = videoRef.current
+        if (!s || !v || !v.videoWidth || !v.videoHeight) return
+        const rect = s.getBoundingClientRect()
+        if (x < rect.left || x > rect.right || y < rect.top || y > rect.bottom) return
+        const scale = Math.min(rect.width / v.videoWidth, rect.height / v.videoHeight)
+        const contentW = v.videoWidth * scale
+        const contentH = v.videoHeight * scale
+        const cssX = x - rect.left - (rect.width - contentW) / 2
+        const cssY = y - rect.top - (rect.height - contentH) / 2
+        if (cssX < 0 || cssY < 0 || cssX > contentW || cssY > contentH) return
+        const mouseX = (cssX / contentW) * v.videoWidth
+        const mouseY = (cssY / contentH) * v.videoHeight
+        if (kind === "mesh") {
+          void sendCommand({ type: "drop_mesh", mouseX, mouseY, assetPath: path }, "reliable")
+          return
+        }
+        void sendCommand({ type: "drop_texture", mouseX, mouseY, textureAssetPath: path }, "reliable")
       }
-      void sendCommand({ type: "drop_texture", mouseX, mouseY, textureAssetPath: path }, "reliable")
-    }
 
     video?.addEventListener("loadedmetadata", handleLoadedMetadata)
     video?.addEventListener("resize", handleResize)
@@ -1850,7 +1855,7 @@ export function Viewport() {
       video?.removeEventListener("loadedmetadata", handleLoadedMetadata)
       video?.removeEventListener("resize", handleResize)
       document.removeEventListener("dragover", handleDocDragOver)
-      ;(window as any).__axiomViewportDropHandler = null
+        ; (window as any).__axiomViewportDropHandler = null
       document.removeEventListener("mousedown", handleMouseDown)
       document.removeEventListener("mouseup", handleMouseUp)
       document.removeEventListener("contextmenu", handleContextMenu)
@@ -1932,9 +1937,6 @@ export function Viewport() {
           </button>
         </div>
         <div className="flex items-center gap-1">
-          <ViewportButton icon={Grid3X3} />
-          <ViewportButton icon={Eye} />
-          <ViewportButton icon={Camera} onClick={() => void toggleLook()} />
           <ViewportButton icon={Maximize2} onClick={() => void connectRef.current()} />
         </div>
       </div>
diff --git a/Headless/AxiomHeadless.cpp b/Headless/AxiomHeadless.cpp
index c732b53b..3f17207d 100644
--- a/Headless/AxiomHeadless.cpp
+++ b/Headless/AxiomHeadless.cpp
@@ -143,6 +143,11 @@ int main(int argc, char **argv) {
       App.Step();
       Subscriber.DiscardLatestFrame();
       break;
+    case Axiom::HeadlessCommandType::SetGridSnap:
+      std::cout << Axiom::SerializeError(
+                       "`set_grid_snap` is only supported by the remote viewport server.")
+                << std::endl;
+      break;
     case Axiom::HeadlessCommandType::RenderFrame: {
       if (!SceneLoaded) {
         std::cout << Axiom::SerializeError(
diff --git a/Headless/DevRemoteViewportClient.cpp b/Headless/DevRemoteViewportClient.cpp
index e9287430..d7395c92 100644
--- a/Headless/DevRemoteViewportClient.cpp
+++ b/Headless/DevRemoteViewportClient.cpp
@@ -153,6 +153,11 @@ int main(int argc, char **argv) {
       Host.Step();
       Subscriber.DiscardLatestFrame();
       break;
+    case Axiom::HeadlessCommandType::SetGridSnap:
+      std::cout << Axiom::SerializeError(
+                       "`set_grid_snap` is only supported by the remote viewport server.")
+                << std::endl;
+      break;
     case Axiom::HeadlessCommandType::RenderFrame: {
       if (!SceneLoaded) {
         std::cout << Axiom::SerializeError(
diff --git a/Headless/HeadlessCommandProtocol.cpp b/Headless/HeadlessCommandProtocol.cpp
index 210423b6..9dbb02df 100644
--- a/Headless/HeadlessCommandProtocol.cpp
+++ b/Headless/HeadlessCommandProtocol.cpp
@@ -964,6 +964,13 @@ std::optional<HeadlessCommand> ParseHeadlessCommand(std::string_view JsonLine,
     }
     return HeadlessCommand{.Type = HeadlessCommandType::SetGizmoMode, .Mode = Mode};
   }
+  if (*Type == "set_grid_snap") {
+    static const std::regex EnabledPattern(R"json("enabled"\s*:\s*(true|false))json");
+    const auto EnabledStr = MatchString(JsonLine, EnabledPattern);
+    return HeadlessCommand{
+        .Type = HeadlessCommandType::SetGridSnap,
+        .Enabled = EnabledStr.value_or("false") == "true"};
+  }
 
   Error = "Unsupported command type: " + *Type;
   return std::nullopt;
@@ -994,6 +1001,7 @@ ParseRemoteViewportCommand(std::string_view JsonLine, std::string &Error) {
   case HeadlessCommandType::GizmoDragUpdate:
   case HeadlessCommandType::GizmoDragEnd:
   case HeadlessCommandType::SetGizmoMode:
+  case HeadlessCommandType::SetGridSnap:
   case HeadlessCommandType::ListAssets:
   case HeadlessCommandType::GetSchema:
   case HeadlessCommandType::SetProperty:
diff --git a/Headless/HeadlessCommandProtocol.h b/Headless/HeadlessCommandProtocol.h
index 7c23c69e..76328076 100644
--- a/Headless/HeadlessCommandProtocol.h
+++ b/Headless/HeadlessCommandProtocol.h
@@ -41,6 +41,7 @@ enum class HeadlessCommandType {
   GizmoDragUpdate,
   GizmoDragEnd,
   SetGizmoMode,
+  SetGridSnap,
   ListAssets,
   GetSchema,
   SetProperty,
@@ -67,6 +68,7 @@ struct HeadlessCommand {
   RendererViewMode ViewMode{RendererViewMode::Lit};
   glm::vec2 MousePosition{0.0f};
   GizmoMode Mode{GizmoMode::Translate};
+  bool Enabled{false};
   std::string ObjectId;
   std::string PropertyName;
   std::optional<PropertyValue> PropertyVal;
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index 99999eca..6affebc9 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -18,6 +18,7 @@
 #include <charconv>
 #include <chrono>
 #include <cctype>
+#include <cmath>
 #include <cstring>
 #include <filesystem>
 #include <fstream>
@@ -225,6 +226,39 @@ std::optional<std::string> GetQueryParam(std::string_view Path,
   return std::nullopt;
 }
 
+constexpr float kTranslationSnapStep = 1.0f;
+constexpr float kRotationSnapStepDegrees = 15.0f;
+constexpr float kScaleSnapStep = 0.1f;
+constexpr float kMinimumScale = 0.001f;
+
+float SnapToStep(float value, float step) {
+  if (step <= 0.0f) {
+    return value;
+  }
+  return std::round(value / step) * step;
+}
+
+void ApplyGridSnap(bool gridSnapEnabled, GizmoMode mode, int axis,
+                   glm::vec3 &location, glm::vec3 &rotationDegrees,
+                   glm::vec3 &scale) {
+  if (!gridSnapEnabled || axis < 0 || axis > 2) {
+    return;
+  }
+
+  switch (mode) {
+  case GizmoMode::Translate:
+    location[axis] = SnapToStep(location[axis], kTranslationSnapStep);
+    break;
+  case GizmoMode::Rotate:
+    rotationDegrees[axis] =
+        SnapToStep(rotationDegrees[axis], kRotationSnapStepDegrees);
+    break;
+  case GizmoMode::Scale:
+    scale[axis] = std::max(kMinimumScale, SnapToStep(scale[axis], kScaleSnapStep));
+    break;
+  }
+}
+
 std::string Trim(std::string_view Value) {
   while (!Value.empty() &&
          std::isspace(static_cast<unsigned char>(Value.front())) != 0) {
@@ -984,6 +1018,7 @@ bool RemoteViewportServer::HandlePostRequest(uintptr_t ClientSocketValue,
   case HeadlessCommandType::GizmoDragUpdate:
   case HeadlessCommandType::GizmoDragEnd:
   case HeadlessCommandType::SetGizmoMode:
+  case HeadlessCommandType::SetGridSnap:
     break;
   case HeadlessCommandType::Heartbeat:
   case HeadlessCommandType::ListAssets:
@@ -1837,6 +1872,7 @@ bool RemoteViewportServer::HandleWebSocketMessage(uintptr_t ClientSocketValue,
   case HeadlessCommandType::GizmoDragUpdate:
   case HeadlessCommandType::GizmoDragEnd:
   case HeadlessCommandType::SetGizmoMode:
+  case HeadlessCommandType::SetGridSnap:
   case HeadlessCommandType::Heartbeat:
     return false;
   case HeadlessCommandType::ListAssets: {
@@ -2027,6 +2063,9 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
     Client->CurrentGizmoMode = Command->Mode;
     m_Host.GetHeadlessLayer().SetGizmoMode(Client->User, Command->Mode);
     return true;
+  case HeadlessCommandType::SetGridSnap:
+    Client->GridSnapEnabled = Command->Enabled;
+    return true;
   case HeadlessCommandType::GizmoHover: {
     if (Client->GizmoDrag.has_value()) {
       return true;
@@ -2168,6 +2207,8 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
           Command->MousePosition.x, Command->MousePosition.y);
       RotDeg[Drag.Math.Axis] = Drag.StartRotDeg[Drag.Math.Axis] + DeltaDeg;
     }
+    ApplyGridSnap(Client->GridSnapEnabled, Drag.Mode, Drag.Math.Axis, Location,
+                  RotDeg, Scale);
     EditorCommand Cmd;
     Cmd.Payload = SetTransformCommand{
         .ObjectId = Drag.ObjectId,
@@ -2211,6 +2252,8 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
             Command->MousePosition.x, Command->MousePosition.y);
         RotDeg[Drag.Math.Axis] = Drag.StartRotDeg[Drag.Math.Axis] + DeltaDeg;
       }
+      ApplyGridSnap(Client->GridSnapEnabled, Drag.Mode, Drag.Math.Axis, Location,
+                    RotDeg, Scale);
       EditorCommand Cmd;
       Cmd.Payload = SetTransformCommand{
           .ObjectId = Drag.ObjectId,
diff --git a/Headless/RemoteViewportServer.h b/Headless/RemoteViewportServer.h
index 2a89080a..4369b39a 100644
--- a/Headless/RemoteViewportServer.h
+++ b/Headless/RemoteViewportServer.h
@@ -73,6 +73,7 @@ class RemoteViewportServer final : public ISessionTransportSubscriber {
     std::unique_ptr<PacketOutput> VideoPacketOutput;
     std::optional<ActiveGizmoDrag> GizmoDrag;
     GizmoMode CurrentGizmoMode{GizmoMode::Translate};
+    bool GridSnapEnabled{false};
   };
 
   struct ClientSessionResolution {
diff --git a/Tests/HeadlessProtocolTests.cpp b/Tests/HeadlessProtocolTests.cpp
index 8cefa9bf..e03bba5f 100644
--- a/Tests/HeadlessProtocolTests.cpp
+++ b/Tests/HeadlessProtocolTests.cpp
@@ -155,6 +155,16 @@ TEST(HeadlessProtocolTests, RemoteViewportAcceptsSetTransformCommand) {
   EXPECT_EQ(Payload->Scale, glm::vec3(1.0f, 1.5f, 2.0f));
 }
 
+TEST(HeadlessProtocolTests, RemoteViewportAcceptsSetGridSnapCommand) {
+  std::string Error;
+  const auto Command = Axiom::ParseRemoteViewportCommand(
+      R"json({"type":"set_grid_snap","enabled":true})json", Error);
+
+  ASSERT_TRUE(Command.has_value()) << Error;
+  EXPECT_EQ(Command->Type, Axiom::HeadlessCommandType::SetGridSnap);
+  EXPECT_TRUE(Command->Enabled);
+}
+
 TEST(HeadlessProtocolTests, SerializesCommandRejectedEvent) {
   const Axiom::PublishedEditorEvent Event{
       .Id = Axiom::EventId{4},

From e6521cf75786ab77bb2ecdffc6974b8d17e165f4 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:33:37 -0500
Subject: [PATCH 09/12] Grid snap settings

---
 .../engine/remote-viewport-context.tsx        |  39 ++++--
 EditorFrontend/components/engine/toolbar.tsx  | 125 ++++++++++++++++--
 EditorFrontend/components/engine/viewport.tsx |  17 ++-
 Headless/HeadlessCommandProtocol.cpp          |  21 ++-
 Headless/HeadlessCommandProtocol.h            |   3 +
 Headless/RemoteViewportServer.cpp             |  35 ++---
 Headless/RemoteViewportServer.h               |   9 +-
 Tests/HeadlessProtocolTests.cpp               |   6 +-
 8 files changed, 215 insertions(+), 40 deletions(-)

diff --git a/EditorFrontend/components/engine/remote-viewport-context.tsx b/EditorFrontend/components/engine/remote-viewport-context.tsx
index a2cd0641..a34ceb02 100644
--- a/EditorFrontend/components/engine/remote-viewport-context.tsx
+++ b/EditorFrontend/components/engine/remote-viewport-context.tsx
@@ -34,6 +34,13 @@ export type RemoteViewportViewMode = "lit" | "unlit" | "wireframe"
 export type RemoteViewportGizmoMode = "translate" | "scale" | "rotate"
 export type SessionSceneItemKind = "folder" | "mesh" | "light" | "camera" | "actor"
 
+export interface RemoteViewportGridSnapSettings {
+  enabled: boolean
+  translationStep: number
+  rotationStepDegrees: number
+  scaleStep: number
+}
+
 export interface SessionAssetDescriptor {
   id: number
   name: string
@@ -130,7 +137,7 @@ interface RemoteViewportActions {
   toggleLook: () => Promise<void>
   setMode: (mode: RemoteViewportViewMode) => Promise<void>
   setGizmoMode: (mode: RemoteViewportGizmoMode) => Promise<void>
-  setGridSnapEnabled: (enabled: boolean) => Promise<void>
+  setGridSnapSettings: (settings: RemoteViewportGridSnapSettings) => Promise<void>
   refreshSessionSnapshot: () => Promise<void>
   selectObject: (objectId: string) => Promise<boolean>
   renameObject: (objectId: string, displayName: string) => Promise<boolean>
@@ -182,7 +189,7 @@ interface RemoteViewportContextValue {
   sessionDetailText: string
   viewMode: RemoteViewportViewMode
   gizmoMode: RemoteViewportGizmoMode
-  gridSnapEnabled: boolean
+  gridSnapSettings: RemoteViewportGridSnapSettings
   isLooking: boolean
   eventLog: string[]
   serverOrigin: string
@@ -256,7 +263,7 @@ interface RemoteViewportContextValue {
   toggleLook: () => Promise<void>
   setMode: (mode: RemoteViewportViewMode) => Promise<void>
   setGizmoMode: (mode: RemoteViewportGizmoMode) => Promise<void>
-  setGridSnapEnabled: (enabled: boolean) => Promise<void>
+  setGridSnapSettings: (settings: RemoteViewportGridSnapSettings) => Promise<void>
   refreshSessionSnapshot: () => Promise<void>
   selectObject: (objectId: string) => Promise<boolean>
   renameObject: (objectId: string, displayName: string) => Promise<boolean>
@@ -301,12 +308,19 @@ function findSceneItem(items: SessionSceneItem[], objectId: string | null): Sess
 }
 
 export function RemoteViewportProvider({ children }: { children: ReactNode }) {
+  const defaultGridSnapSettings: RemoteViewportGridSnapSettings = {
+    enabled: true,
+    translationStep: 1,
+    rotationStepDegrees: 15,
+    scaleStep: 0.1,
+  }
+
   const actionsRef = useRef<RemoteViewportActions>({
     reconnect: async () => {},
     toggleLook: async () => {},
     setMode: async () => {},
     setGizmoMode: async () => {},
-    setGridSnapEnabled: async () => {},
+    setGridSnapSettings: async () => {},
     refreshSessionSnapshot: async () => {},
     selectObject: async () => false,
     renameObject: async () => false,
@@ -339,7 +353,8 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
   )
   const [viewMode, setViewMode] = useState<RemoteViewportViewMode>("lit")
   const [gizmoMode, setGizmoModeState] = useState<RemoteViewportGizmoMode>("translate")
-  const [gridSnapEnabled, setGridSnapEnabledState] = useState(false)
+  const [gridSnapSettings, setGridSnapSettingsState] =
+    useState<RemoteViewportGridSnapSettings>(defaultGridSnapSettings)
   const [isLooking, setIsLooking] = useState(false)
   const [eventLog, setEventLog] = useState<string[]>([])
   const [serverOrigin, setServerOrigin] = useState("")
@@ -452,9 +467,9 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
     await actionsRef.current.setGizmoMode(mode)
   }, [])
 
-  const setGridSnapEnabled = useCallback(async (enabled: boolean) => {
-    setGridSnapEnabledState(enabled)
-    await actionsRef.current.setGridSnapEnabled(enabled)
+  const setGridSnapSettings = useCallback(async (settings: RemoteViewportGridSnapSettings) => {
+    setGridSnapSettingsState(settings)
+    await actionsRef.current.setGridSnapSettings(settings)
   }, [])
 
   const refreshSessionSnapshot = useCallback(async () => {
@@ -578,7 +593,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       sessionDetailText,
       viewMode,
       gizmoMode,
-      gridSnapEnabled,
+      gridSnapSettings,
       isLooking,
       eventLog,
       serverOrigin,
@@ -632,7 +647,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       toggleLook,
       setMode,
       setGizmoMode: setGizmoModeAction,
-      setGridSnapEnabled,
+      setGridSnapSettings,
       refreshSessionSnapshot,
       selectObject,
       renameObject,
@@ -658,7 +673,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       frameText,
       isLooking,
       participants,
-      gridSnapEnabled,
+      gridSnapSettings,
       sessionDetailText,
       sessionState,
       sessionStatusText,
@@ -695,7 +710,7 @@ export function RemoteViewportProvider({ children }: { children: ReactNode }) {
       gizmoMode,
       setMode,
       setGizmoModeAction,
-      setGridSnapEnabled,
+      setGridSnapSettings,
       setSessionDetailText,
       setSessionState,
       setSessionSnapshot,
diff --git a/EditorFrontend/components/engine/toolbar.tsx b/EditorFrontend/components/engine/toolbar.tsx
index d60c153d..d850f699 100644
--- a/EditorFrontend/components/engine/toolbar.tsx
+++ b/EditorFrontend/components/engine/toolbar.tsx
@@ -22,16 +22,33 @@ import {
   Sun,
   Camera,
   RefreshCw,
+  ChevronDown,
 } from "lucide-react"
-import { useRemoteViewport } from "./remote-viewport-context"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import {
+  useRemoteViewport,
+  type RemoteViewportGridSnapSettings,
+} from "./remote-viewport-context"
 import { PresenceRoster } from "./presence-roster"
 
+const TRANSLATION_SNAP_OPTIONS = [0.25, 0.5, 1, 5] as const
+const ROTATION_SNAP_OPTIONS = [5, 10, 15, 45] as const
+const SCALE_SNAP_OPTIONS = [0.01, 0.05, 0.1, 0.25] as const
+
 export function Toolbar() {
   const {
     gizmoMode,
-    gridSnapEnabled,
+    gridSnapSettings,
     setGizmoMode,
-    setGridSnapEnabled,
+    setGridSnapSettings,
     saveScene,
     saveStatus,
     setSaveStatus,
@@ -119,11 +136,9 @@ export function Toolbar() {
       <ToolbarDivider />
 
       <ToolbarGroup>
-        <ToolbarButton
-          icon={Grid3X3}
-          tooltip="Grid Snap (1u / 15deg / 0.1x)"
-          active={gridSnapEnabled}
-          onClick={() => void setGridSnapEnabled(!gridSnapEnabled)}
+        <GridSnapDropdown
+          settings={gridSnapSettings}
+          onChange={(settings) => void setGridSnapSettings(settings)}
         />
         <ToolbarButton icon={Layers} tooltip="Layers" />
       </ToolbarGroup>
@@ -153,6 +168,100 @@ export function Toolbar() {
   )
 }
 
+function GridSnapDropdown({
+  settings,
+  onChange,
+}: {
+  settings: RemoteViewportGridSnapSettings
+  onChange: (settings: RemoteViewportGridSnapSettings) => void
+}) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          title="Grid Snap"
+          className={`flex items-center gap-1 rounded p-2 hover:bg-neutral-800 transition-colors ${
+            settings.enabled ? "bg-neutral-700 text-white" : "text-neutral-400"
+          }`}
+          type="button"
+        >
+          <Grid3X3 className="h-4 w-4" />
+          <ChevronDown className="h-3 w-3" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align="start"
+        className="w-56 border-neutral-800 bg-neutral-950 text-neutral-200"
+      >
+        <DropdownMenuLabel className="text-xs uppercase tracking-[0.16em] text-neutral-500">
+          Move Snap
+        </DropdownMenuLabel>
+        <DropdownMenuRadioGroup
+          value={String(settings.enabled ? settings.translationStep : 0)}
+          onValueChange={(value) =>
+            onChange({
+              ...settings,
+              enabled: value !== "0",
+              translationStep: value === "0" ? settings.translationStep : Number(value),
+            })
+          }
+        >
+          <DropdownMenuRadioItem value="0">Off</DropdownMenuRadioItem>
+          {TRANSLATION_SNAP_OPTIONS.map((value) => (
+            <DropdownMenuRadioItem key={value} value={String(value)}>
+              {formatSnapValue(value)} units
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+
+        <DropdownMenuSeparator className="bg-neutral-800" />
+        <DropdownMenuLabel className="text-xs uppercase tracking-[0.16em] text-neutral-500">
+          Rotate Snap
+        </DropdownMenuLabel>
+        <DropdownMenuRadioGroup
+          value={String(settings.rotationStepDegrees)}
+          onValueChange={(value) =>
+            onChange({
+              ...settings,
+              rotationStepDegrees: Number(value),
+            })
+          }
+        >
+          {ROTATION_SNAP_OPTIONS.map((value) => (
+            <DropdownMenuRadioItem key={value} value={String(value)}>
+              {value} degrees
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+
+        <DropdownMenuSeparator className="bg-neutral-800" />
+        <DropdownMenuLabel className="text-xs uppercase tracking-[0.16em] text-neutral-500">
+          Scale Snap
+        </DropdownMenuLabel>
+        <DropdownMenuRadioGroup
+          value={String(settings.scaleStep)}
+          onValueChange={(value) =>
+            onChange({
+              ...settings,
+              scaleStep: Number(value),
+            })
+          }
+        >
+          {SCALE_SNAP_OPTIONS.map((value) => (
+            <DropdownMenuRadioItem key={value} value={String(value)}>
+              {formatSnapValue(value)} scale
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+function formatSnapValue(value: number) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0$/, "")
+}
+
 function ToolbarGroup({ children }: { children: React.ReactNode }) {
   return <div className="flex items-center gap-0.5">{children}</div>
 }
diff --git a/EditorFrontend/components/engine/viewport.tsx b/EditorFrontend/components/engine/viewport.tsx
index cbb3f0f7..06344a97 100644
--- a/EditorFrontend/components/engine/viewport.tsx
+++ b/EditorFrontend/components/engine/viewport.tsx
@@ -15,6 +15,7 @@ import {
 } from "@/components/ui/dropdown-menu"
 import {
   useRemoteViewport,
+  type RemoteViewportGridSnapSettings,
   type SessionObjectTransformUpdate,
   type SessionObjectDetails,
   type RemoteViewportConnectionState,
@@ -168,6 +169,9 @@ type RemoteViewportCommand =
   | {
     type: "set_grid_snap"
     enabled: boolean
+    translationStep: number
+    rotationStepDegrees: number
+    scaleStep: number
   }
   | { type: "heartbeat" }
   | { type: "list_assets" }
@@ -1622,8 +1626,17 @@ export function Viewport() {
         gizmoModeRef.current = nextMode
         await sendCommand({ type: "set_gizmo_mode", mode: nextMode }, "reliable")
       },
-      setGridSnapEnabled: async (enabled) => {
-        await sendCommand({ type: "set_grid_snap", enabled }, "reliable")
+      setGridSnapSettings: async (settings: RemoteViewportGridSnapSettings) => {
+        await sendCommand(
+          {
+            type: "set_grid_snap",
+            enabled: settings.enabled,
+            translationStep: settings.translationStep,
+            rotationStepDegrees: settings.rotationStepDegrees,
+            scaleStep: settings.scaleStep,
+          },
+          "reliable"
+        )
       },
     })
     setServerOrigin(serverOrigin)
diff --git a/Headless/HeadlessCommandProtocol.cpp b/Headless/HeadlessCommandProtocol.cpp
index 9dbb02df..2a5759d6 100644
--- a/Headless/HeadlessCommandProtocol.cpp
+++ b/Headless/HeadlessCommandProtocol.cpp
@@ -966,10 +966,29 @@ std::optional<HeadlessCommand> ParseHeadlessCommand(std::string_view JsonLine,
   }
   if (*Type == "set_grid_snap") {
     static const std::regex EnabledPattern(R"json("enabled"\s*:\s*(true|false))json");
+    static const std::regex TranslationStepPattern(
+        R"json("translationStep"\s*:\s*(-?[0-9Ee.+-]+))json");
+    static const std::regex RotationStepPattern(
+        R"json("rotationStepDegrees"\s*:\s*(-?[0-9Ee.+-]+))json");
+    static const std::regex ScaleStepPattern(
+        R"json("scaleStep"\s*:\s*(-?[0-9Ee.+-]+))json");
     const auto EnabledStr = MatchString(JsonLine, EnabledPattern);
+    auto ParseScalar = [&](const std::regex &pattern, double fallback) {
+      std::match_results<std::string_view::const_iterator> match;
+      if (std::regex_search(JsonLine.begin(), JsonLine.end(), match, pattern)) {
+        if (const auto value =
+                ParseDouble(std::string_view(match[1].first, match[1].second))) {
+          return static_cast<float>(*value);
+        }
+      }
+      return static_cast<float>(fallback);
+    };
     return HeadlessCommand{
         .Type = HeadlessCommandType::SetGridSnap,
-        .Enabled = EnabledStr.value_or("false") == "true"};
+        .Enabled = EnabledStr.value_or("false") == "true",
+        .TranslationStep = ParseScalar(TranslationStepPattern, 1.0),
+        .RotationStepDegrees = ParseScalar(RotationStepPattern, 15.0),
+        .ScaleStep = ParseScalar(ScaleStepPattern, 0.1)};
   }
 
   Error = "Unsupported command type: " + *Type;
diff --git a/Headless/HeadlessCommandProtocol.h b/Headless/HeadlessCommandProtocol.h
index 76328076..921cabc5 100644
--- a/Headless/HeadlessCommandProtocol.h
+++ b/Headless/HeadlessCommandProtocol.h
@@ -69,6 +69,9 @@ struct HeadlessCommand {
   glm::vec2 MousePosition{0.0f};
   GizmoMode Mode{GizmoMode::Translate};
   bool Enabled{false};
+  float TranslationStep{1.0f};
+  float RotationStepDegrees{15.0f};
+  float ScaleStep{0.1f};
   std::string ObjectId;
   std::string PropertyName;
   std::optional<PropertyValue> PropertyVal;
diff --git a/Headless/RemoteViewportServer.cpp b/Headless/RemoteViewportServer.cpp
index 6affebc9..62f5242f 100644
--- a/Headless/RemoteViewportServer.cpp
+++ b/Headless/RemoteViewportServer.cpp
@@ -226,9 +226,6 @@ std::optional<std::string> GetQueryParam(std::string_view Path,
   return std::nullopt;
 }
 
-constexpr float kTranslationSnapStep = 1.0f;
-constexpr float kRotationSnapStepDegrees = 15.0f;
-constexpr float kScaleSnapStep = 0.1f;
 constexpr float kMinimumScale = 0.001f;
 
 float SnapToStep(float value, float step) {
@@ -238,23 +235,23 @@ float SnapToStep(float value, float step) {
   return std::round(value / step) * step;
 }
 
-void ApplyGridSnap(bool gridSnapEnabled, GizmoMode mode, int axis,
+void ApplyGridSnap(bool enabled, float translationStep,
+                   float rotationStepDegrees, float scaleStep, GizmoMode mode, int axis,
                    glm::vec3 &location, glm::vec3 &rotationDegrees,
                    glm::vec3 &scale) {
-  if (!gridSnapEnabled || axis < 0 || axis > 2) {
+  if (!enabled || axis < 0 || axis > 2) {
     return;
   }
 
   switch (mode) {
   case GizmoMode::Translate:
-    location[axis] = SnapToStep(location[axis], kTranslationSnapStep);
+    location[axis] = SnapToStep(location[axis], translationStep);
     break;
   case GizmoMode::Rotate:
-    rotationDegrees[axis] =
-        SnapToStep(rotationDegrees[axis], kRotationSnapStepDegrees);
+    rotationDegrees[axis] = SnapToStep(rotationDegrees[axis], rotationStepDegrees);
     break;
   case GizmoMode::Scale:
-    scale[axis] = std::max(kMinimumScale, SnapToStep(scale[axis], kScaleSnapStep));
+    scale[axis] = std::max(kMinimumScale, SnapToStep(scale[axis], scaleStep));
     break;
   }
 }
@@ -2063,9 +2060,15 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
     Client->CurrentGizmoMode = Command->Mode;
     m_Host.GetHeadlessLayer().SetGizmoMode(Client->User, Command->Mode);
     return true;
-  case HeadlessCommandType::SetGridSnap:
-    Client->GridSnapEnabled = Command->Enabled;
+  case HeadlessCommandType::SetGridSnap: {
+    Client->GridSnap.Enabled = Command->Enabled;
+    Client->GridSnap.TranslationStep =
+        std::max(kMinimumScale, Command->TranslationStep);
+    Client->GridSnap.RotationStepDegrees =
+        std::max(0.001f, Command->RotationStepDegrees);
+    Client->GridSnap.ScaleStep = std::max(kMinimumScale, Command->ScaleStep);
     return true;
+  }
   case HeadlessCommandType::GizmoHover: {
     if (Client->GizmoDrag.has_value()) {
       return true;
@@ -2207,8 +2210,9 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
           Command->MousePosition.x, Command->MousePosition.y);
       RotDeg[Drag.Math.Axis] = Drag.StartRotDeg[Drag.Math.Axis] + DeltaDeg;
     }
-    ApplyGridSnap(Client->GridSnapEnabled, Drag.Mode, Drag.Math.Axis, Location,
-                  RotDeg, Scale);
+    ApplyGridSnap(Client->GridSnap.Enabled, Client->GridSnap.TranslationStep,
+                  Client->GridSnap.RotationStepDegrees, Client->GridSnap.ScaleStep,
+                  Drag.Mode, Drag.Math.Axis, Location, RotDeg, Scale);
     EditorCommand Cmd;
     Cmd.Payload = SetTransformCommand{
         .ObjectId = Drag.ObjectId,
@@ -2252,8 +2256,9 @@ bool RemoteViewportServer::HandleClientWebRtcMessage(std::string_view ClientId,
             Command->MousePosition.x, Command->MousePosition.y);
         RotDeg[Drag.Math.Axis] = Drag.StartRotDeg[Drag.Math.Axis] + DeltaDeg;
       }
-      ApplyGridSnap(Client->GridSnapEnabled, Drag.Mode, Drag.Math.Axis, Location,
-                    RotDeg, Scale);
+      ApplyGridSnap(Client->GridSnap.Enabled, Client->GridSnap.TranslationStep,
+                    Client->GridSnap.RotationStepDegrees, Client->GridSnap.ScaleStep,
+                    Drag.Mode, Drag.Math.Axis, Location, RotDeg, Scale);
       EditorCommand Cmd;
       Cmd.Payload = SetTransformCommand{
           .ObjectId = Drag.ObjectId,
diff --git a/Headless/RemoteViewportServer.h b/Headless/RemoteViewportServer.h
index 4369b39a..24a5783b 100644
--- a/Headless/RemoteViewportServer.h
+++ b/Headless/RemoteViewportServer.h
@@ -48,6 +48,13 @@ class RemoteViewportServer final : public ISessionTransportSubscriber {
   void OnSessionTransportViewportFrame(const ViewportFrame &Frame) override;
 
 private:
+  struct GridSnapSettings {
+    bool Enabled{true};
+    float TranslationStep{1.0f};
+    float RotationStepDegrees{15.0f};
+    float ScaleStep{0.1f};
+  };
+
   struct WebSocketClient {
     uintptr_t SocketValue{static_cast<uintptr_t>(~0ull)};
     bool IsOpen{true};
@@ -73,7 +80,7 @@ class RemoteViewportServer final : public ISessionTransportSubscriber {
     std::unique_ptr<PacketOutput> VideoPacketOutput;
     std::optional<ActiveGizmoDrag> GizmoDrag;
     GizmoMode CurrentGizmoMode{GizmoMode::Translate};
-    bool GridSnapEnabled{false};
+    GridSnapSettings GridSnap;
   };
 
   struct ClientSessionResolution {
diff --git a/Tests/HeadlessProtocolTests.cpp b/Tests/HeadlessProtocolTests.cpp
index e03bba5f..b50d362d 100644
--- a/Tests/HeadlessProtocolTests.cpp
+++ b/Tests/HeadlessProtocolTests.cpp
@@ -158,11 +158,15 @@ TEST(HeadlessProtocolTests, RemoteViewportAcceptsSetTransformCommand) {
 TEST(HeadlessProtocolTests, RemoteViewportAcceptsSetGridSnapCommand) {
   std::string Error;
   const auto Command = Axiom::ParseRemoteViewportCommand(
-      R"json({"type":"set_grid_snap","enabled":true})json", Error);
+      R"json({"type":"set_grid_snap","enabled":true,"translationStep":0.5,"rotationStepDegrees":10.0,"scaleStep":0.05})json",
+      Error);
 
   ASSERT_TRUE(Command.has_value()) << Error;
   EXPECT_EQ(Command->Type, Axiom::HeadlessCommandType::SetGridSnap);
   EXPECT_TRUE(Command->Enabled);
+  EXPECT_FLOAT_EQ(Command->TranslationStep, 0.5f);
+  EXPECT_FLOAT_EQ(Command->RotationStepDegrees, 10.0f);
+  EXPECT_FLOAT_EQ(Command->ScaleStep, 0.05f);
 }
 
 TEST(HeadlessProtocolTests, SerializesCommandRejectedEvent) {

From 0fa801bbf327f1bd2f8b819fd5dc8abe94707b36 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:35:21 -0500
Subject: [PATCH 10/12] Fullscreen

---
 EditorFrontend/components/engine/viewport.tsx | 37 ++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/EditorFrontend/components/engine/viewport.tsx b/EditorFrontend/components/engine/viewport.tsx
index 06344a97..b68e71f9 100644
--- a/EditorFrontend/components/engine/viewport.tsx
+++ b/EditorFrontend/components/engine/viewport.tsx
@@ -3,6 +3,7 @@
 import { useEffect, useRef, useState, type ElementType } from "react"
 import {
   Maximize2,
+  Minimize2,
   Camera,
   ChevronDown,
 } from "lucide-react"
@@ -258,6 +259,7 @@ export function Viewport() {
   const rightMouseDownRef = useRef(false)
   const viewportFocusedRef = useRef(false)
   const isDraggingGizmoRef = useRef(false)
+  const [isFullscreen, setIsFullscreen] = useState(false)
   const keysRef = useRef(new Set<string>())
   const cursorRef = useRef({ x: 0, y: 0 })
   const pendingLookDeltaRef = useRef({ x: 0, y: 0 })
@@ -324,6 +326,18 @@ export function Viewport() {
     participantsRef.current = participants
   }, [participants])
 
+  useEffect(() => {
+    function syncFullscreenState() {
+      setIsFullscreen(document.fullscreenElement === viewportShellRef.current)
+    }
+
+    syncFullscreenState()
+    document.addEventListener("fullscreenchange", syncFullscreenState)
+    return () => {
+      document.removeEventListener("fullscreenchange", syncFullscreenState)
+    }
+  }, [])
+
   useEffect(() => {
     let disposed = false
 
@@ -1912,6 +1926,20 @@ export function Viewport() {
     )
   }
 
+  async function toggleFullscreen() {
+    const shell = viewportShellRef.current
+    if (!shell) {
+      return
+    }
+
+    if (document.fullscreenElement === shell) {
+      await document.exitFullscreen()
+      return
+    }
+
+    await shell.requestFullscreen()
+  }
+
   return (
     <div className="h-full flex flex-col bg-neutral-900">
       <div className="flex items-center justify-between h-8 bg-neutral-950 border-b border-neutral-800 px-2">
@@ -1950,7 +1978,11 @@ export function Viewport() {
           </button>
         </div>
         <div className="flex items-center gap-1">
-          <ViewportButton icon={Maximize2} onClick={() => void connectRef.current()} />
+          <ViewportButton
+            icon={isFullscreen ? Minimize2 : Maximize2}
+            tooltip={isFullscreen ? "Exit Fullscreen" : "Enter Fullscreen"}
+            onClick={() => void toggleFullscreen()}
+          />
         </div>
       </div>
       <div
@@ -1990,15 +2022,18 @@ export function Viewport() {
 
 function ViewportButton({
   icon: Icon,
+  tooltip,
   onClick,
 }: {
   icon: ElementType
+  tooltip?: string
   onClick?: () => void
 }) {
   return (
     <button
       className="rounded p-1.5 text-neutral-400 transition-colors hover:bg-neutral-800 hover:text-white"
       onClick={onClick}
+      title={tooltip}
       type="button"
     >
       <Icon className="h-3.5 w-3.5" />

From b2052359e550fbd1732e530a8eb3ef486ae62459 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:36:19 -0500
Subject: [PATCH 11/12] Update docs

---
 Docs/DistributedWraithEngineDesign.md | 2 ++
 Docs/HeadlessAxiomSessionPrototype.md | 6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/Docs/DistributedWraithEngineDesign.md b/Docs/DistributedWraithEngineDesign.md
index 80e90850..9bd37687 100644
--- a/Docs/DistributedWraithEngineDesign.md
+++ b/Docs/DistributedWraithEngineDesign.md
@@ -1287,6 +1287,8 @@ Progress update:
 - the details panel supports rename and transform editing; drafts are scoped to the selected object's ID so periodic server snapshot polls do not clobber edits in progress
 - viewport keyboard input (WASD, Space, Shift) is now gated on pointer lock state; keys are only consumed while the viewport has pointer lock and are cleared immediately when it releases, so other UI elements (inputs, the outliner) receive input normally
 - a server-side transform gizmo is now implemented across all three modes (Translate, Scale, Rotate); the toolbar Move/Rotate/Scale buttons and Q/E/R shortcuts switch modes with active-state feedback; dragging any handle drives `SetTransformCommand` through the same authoritative command path
+- grid snapping is now configured from a toolbar dropdown instead of a fixed toggle preset; the selected move/rotate/scale increments are stored in shared viewport state and pushed to the server with `set_grid_snap`, so gizmo drags snap authoritatively
+- the remote viewport header maximize button now toggles browser fullscreen on the viewport shell and reflects enter/exit state in its iconography
 - reparent is implemented: any object can be dragged onto any other in the outliner; transforms are stored in local space and world transforms are recomputed for the entire moved subtree
 - Collaboration v1 is complete: object locking prevents simultaneous gizmo conflicts, presence roster shows connected users, and the heartbeat/timeout loop handles hard tab closes
 - Phase 5 (Reflection and Asset Evolution) is complete: `AssetId` stable identity, `IAssetSource` / `LocalAssetSource` VFS, `ListAssets` / `GetSchema` / `SetProperty` / `SaveScene` commands, `SceneFile` JSON persistence, content browser wired to live asset catalogue, details panel schema-driven, toolbar Save button with success/failure animation
diff --git a/Docs/HeadlessAxiomSessionPrototype.md b/Docs/HeadlessAxiomSessionPrototype.md
index 7101aee0..2abd8b21 100644
--- a/Docs/HeadlessAxiomSessionPrototype.md
+++ b/Docs/HeadlessAxiomSessionPrototype.md
@@ -252,15 +252,21 @@ A server-side transform gizmo is now fully implemented on the `scene-editing` br
 - `gizmo_drag_start` / `gizmo_drag_end` (reliable): bracket the drag; drag start resolves the hit handle and captures object state; drag end commits the final transform
 - `gizmo_drag_update` (unreliable): sent every `mousemove` during drag; server applies the current drag math and dispatches `SetTransformCommand`
 - `set_gizmo_mode`: switches the per-client gizmo mode (`translate` / `scale` / `rotate`); server updates hit-test and rendering for subsequent frames
+- `set_grid_snap`: updates per-client snap settings for gizmo drags; move snap can be disabled or set from the toolbar dropdown, while rotation and scale use the selected increments when snapping is enabled
 - snapshot refresh is suppressed while a gizmo drag is active to prevent server state polls from fighting the in-progress drag position
 
 ### Mode Switching
 - `GizmoMode` enum (Translate / Scale / Rotate) lives in `RenderScene.h` and is passed through `GizmoOverlayData` to the renderer
 - per-client mode is stored in `RemoteClientSession::CurrentGizmoMode` and in `HeadlessSessionLayer` for the render path
 - the toolbar Move, Rotate, and Scale buttons are now wired to `setGizmoMode` from `RemoteViewportContext`; active-state styling reflects the current mode
+- the toolbar Grid Snap control is now a dropdown instead of a simple toggle; it stores shared snap settings in `RemoteViewportContext` and sends them over `set_grid_snap` so the authoritative drag path uses the chosen move/rotate/scale increments
 - Q = Translate, E = Scale, R = Rotate keyboard shortcuts fire when the viewport is focused and not in camera look mode
 - `gizmoMode` state lives in `RemoteViewportContext` so toolbar and viewport share a single source of truth
 
+### Viewport Chrome
+- the maximize button in the remote viewport header now toggles browser fullscreen on the viewport shell via the Fullscreen API
+- the button swaps between enter/exit fullscreen icons based on `fullscreenchange`, so the viewport chrome stays in sync even if fullscreen exits outside the button
+
 ### Coordinate Mapping Fix
 - mouse pixel coordinates sent to the server account for the `object-contain` CSS letterboxing on the video element: the actual content rectangle is computed from the uniform scale factor and centering offsets before mapping to server pixels, so hit-testing is accurate regardless of window aspect ratio
 

From 281fc2f733c2b71859997576e487718531bbf6c9 Mon Sep 17 00:00:00 2001
From: Tamely <joshua.audia@gmail.com>
Date: Tue, 12 May 2026 16:38:07 -0500
Subject: [PATCH 12/12] Add some more code cleanup to the roadmap

---
 Docs/DistributedWraithEngineDesign.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Docs/DistributedWraithEngineDesign.md b/Docs/DistributedWraithEngineDesign.md
index 9bd37687..48cb619f 100644
--- a/Docs/DistributedWraithEngineDesign.md
+++ b/Docs/DistributedWraithEngineDesign.md
@@ -1179,6 +1179,7 @@ Likely targets based on current trajectory:
 | `Axiom/Session/EditorSession.cpp` | ~2,000 lines | Command dispatch, event publication, lock management, presence logic, schema generation |
 | `Headless/RemoteViewportServer.cpp` | ~1,500 lines | HTTP routing, WebSocket framing, WebRTC signaling, command parsing, client lifecycle |
 | `Headless/HeadlessCommandProtocol.cpp` | ~800 lines | Growing with every new command; serialization/deserialization should be generated or table-driven |
+| viewport interaction / gizmo hit-testing path | multi-file | mode-specific hit testing, drag math, and interaction branching are starting to duplicate patterns and should move toward reusable primitives or strategies |
 
 #### 10.2 Proposed splits
 
@@ -1201,6 +1202,12 @@ Likely targets based on current trajectory:
 - `CommandDeserializer` — inbound command JSON
 - Register new commands by adding a row to a dispatch table rather than growing `if/else` or `switch` chains
 
+**Viewport interaction and hit-testing** → simplify into modular interaction primitives:
+- extract per-tool interaction handlers so translate / rotate / scale / selection no longer expand one shared branch ladder
+- separate hit-test resolution from drag execution so the same selection / gizmo queries can be reused by hover, drag-start, and future tools
+- prefer data-driven handle descriptors or small strategy objects over repeated mode checks spread through the remote viewport path
+- keep the authoritative command path unchanged while reducing the amount of bespoke branching needed to add a new viewport tool
+
 #### 10.3 Acceptance criteria
 - No existing test regressions
 - No single `.cpp` file exceeds 600 lines after the refactor