feat: refactor spacecraft components to enhance structure and introduce tracking markers

Author: sakobu

rpo-app/src/features/configuration/ConfigurationStep1.tsx

@@ -3,8 +3,8 @@ import { SpacecraftPanel } from './SpacecraftPanel';
 export function ConfigurationStep1() {
   return (
     <section className="grid gap-6 md:grid-cols-2">
-      <SpacecraftPanel vehicle="deputy" />
       <SpacecraftPanel vehicle="chief" />
+      <SpacecraftPanel vehicle="deputy" />
     </section>
   );
 }

rpo-app/src/features/configuration/ConfigurationStep2.tsx

@@ -22,8 +22,8 @@ export function ConfigurationStep2() {
   return (
     <section className="flex flex-col gap-4">
       <div className="grid gap-6 md:grid-cols-2">
-        <VehicleStatePanel vehicle="deputy" />
         <VehicleStatePanel vehicle="chief" />
+        <VehicleStatePanel vehicle="deputy" />
       </div>
       {epochMismatch && chiefVector && deputyVector ? (
         <Callout tone="abort">

rpo-app/src/viewport3d/far-field/FarFieldViewport.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from 'react';
 import { OrbitControls } from '@react-three/drei';
 import { Canvas } from '@react-three/fiber';
 import { useShallow } from 'zustand/react/shallow';
@@ -34,15 +35,18 @@ function VehicleMesh({
   config: SpacecraftConfig;
   vector: StateVectorInput;
 }) {
-  const props = configToSpacecraftProps(config, vehicle);
-  const position = eciKmToScenePosition(vector.position_eci_km);
+  const props = useMemo(() => configToSpacecraftProps(config, vehicle), [config, vehicle]);
+  const position = useMemo(
+    () => eciKmToScenePosition(vector.position_eci_km),
+    [vector.position_eci_km],
+  );
   return (
     <Spacecraft
       {...props}
       position={position}
       scale={FARFIELD_SPACECRAFT_SCALE}
       label={VEHICLE_LABELS[vehicle]}
-      labelColor={TINTS[vehicle].emissive}
+      labelColor={TINTS[vehicle].accent}
       labelFontSize={FARFIELD_LABEL_FONT_SIZE}
       labelOffsetY={FARFIELD_LABEL_OFFSET_Y}
     />

rpo-app/src/viewport3d/proximity/ProximityViewport.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from 'react';
 import { OrbitControls } from '@react-three/drei';
 import { Canvas } from '@react-three/fiber';
 
@@ -14,9 +15,9 @@ const DEFAULT_CHIEF = { preset: 'Servicer 500kg' as const, ...PRESETS['Servicer
 const DEFAULT_DEPUTY = { preset: 'Servicer 500kg' as const, ...PRESETS['Servicer 500kg'] };
 
 export default function ProximityViewport() {
-  const chiefProps = configToSpacecraftProps(DEFAULT_CHIEF, 'chief');
-  const deputyProps = configToSpacecraftProps(DEFAULT_DEPUTY, 'deputy');
-  const deputyPosition = ricToPosition(DEMO_DEPUTY_OFFSET_RIC_M);
+  const chiefProps = useMemo(() => configToSpacecraftProps(DEFAULT_CHIEF, 'chief'), []);
+  const deputyProps = useMemo(() => configToSpacecraftProps(DEFAULT_DEPUTY, 'deputy'), []);
+  const deputyPosition = useMemo(() => ricToPosition(DEMO_DEPUTY_OFFSET_RIC_M), []);
 
   return (
     <div className="h-full w-full">
@@ -34,16 +35,12 @@ export default function ProximityViewport() {
         <directionalLight position={[10, 5, 10]} intensity={1.0} />
         <Grid />
         <RICAxes />
-        <Spacecraft
-          {...chiefProps}
-          label={VEHICLE_LABELS.chief}
-          labelColor={TINTS.chief.emissive}
-        />
+        <Spacecraft {...chiefProps} label={VEHICLE_LABELS.chief} labelColor={TINTS.chief.accent} />
         <Spacecraft
           {...deputyProps}
           position={deputyPosition}
           label={VEHICLE_LABELS.deputy}
-          labelColor={TINTS.deputy.emissive}
+          labelColor={TINTS.deputy.accent}
         />
         <OrbitControls
           enablePan

rpo-app/src/viewport3d/spacecraft/components/MainBody.tsx

@@ -1,28 +1,87 @@
+import {
+  ACCENT_STRIPE_HEIGHT,
+  ACCENT_STRIPE_INTENSITY,
+  BUS_COLOR,
+  DOCKING_COLLAR_COLOR,
+  DOCKING_COLLAR_LENGTH,
+  DOCKING_COLLAR_RADIUS_FRAC,
+  THRUSTER_COLOR,
+  THRUSTER_COUNT,
+  THRUSTER_NOZZLE_APEX_RADIUS,
+  THRUSTER_NOZZLE_BASE_RADIUS,
+  THRUSTER_NOZZLE_LENGTH,
+  THRUSTER_PLACEMENT_RADIUS_FRAC,
+} from '../config/constants';
 import type { MainBodyProps } from '../types';
 
-export function MainBody({
-  width,
-  height,
-  depth,
-  color,
-  emissive,
-  emissiveIntensity = 0.3,
-  metalness = 0.6,
-  roughness = 0.4,
-}: MainBodyProps) {
+const RADIAL_SEGMENTS = 48;
+const NOZZLE_SEGMENTS = 20;
+const STRIPE_OVERHANG = 0.05;
+
+// cylinderGeometry's native axis is +Y. The outer group rotates +π/2 around X
+// so inside the group local +Y maps to world +Z; end-cap positions below use
+// local Y for "along the tube axis."
+
+export function MainBody({ width, height, depth, accent }: MainBodyProps) {
+  const halfWidth = width / 2;
+  const halfHeight = height / 2;
+
+  const busScale = [halfWidth, 1, halfHeight] satisfies [number, number, number];
+  const stripeScale = [(width + STRIPE_OVERHANG) / 2, 1, (height + STRIPE_OVERHANG) / 2] satisfies [
+    number,
+    number,
+    number,
+  ];
+
+  const collarRadiusX = halfWidth * DOCKING_COLLAR_RADIUS_FRAC;
+  const collarRadiusZ = halfHeight * DOCKING_COLLAR_RADIUS_FRAC;
+  const collarY = depth / 2 + DOCKING_COLLAR_LENGTH / 2;
+
+  const thrusterRadiusX = halfWidth * THRUSTER_PLACEMENT_RADIUS_FRAC;
+  const thrusterRadiusZ = halfHeight * THRUSTER_PLACEMENT_RADIUS_FRAC;
+  const thrusterY = -depth / 2 - THRUSTER_NOZZLE_LENGTH / 2;
+
   return (
-    <mesh>
-      <boxGeometry args={[width, height, depth]} />
-      <meshStandardMaterial
-        color={color}
-        metalness={metalness}
-        roughness={roughness}
-        emissive={emissive}
-        emissiveIntensity={emissive ? emissiveIntensity : 0}
-        transparent
-        opacity={1}
-        depthWrite={true}
-      />
-    </mesh>
+    <group rotation={[Math.PI / 2, 0, 0]}>
+      <mesh scale={busScale}>
+        <cylinderGeometry args={[1, 1, depth, RADIAL_SEGMENTS]} />
+        <meshStandardMaterial color={BUS_COLOR} metalness={0.05} roughness={0.75} />
+      </mesh>
+
+      <mesh scale={stripeScale}>
+        <cylinderGeometry args={[1, 1, ACCENT_STRIPE_HEIGHT, RADIAL_SEGMENTS]} />
+        <meshStandardMaterial
+          color={accent}
+          emissive={accent}
+          emissiveIntensity={ACCENT_STRIPE_INTENSITY}
+          metalness={0.1}
+          roughness={0.6}
+        />
+      </mesh>
+
+      <mesh position={[0, collarY, 0]} scale={[collarRadiusX, 1, collarRadiusZ]}>
+        <cylinderGeometry args={[1, 1, DOCKING_COLLAR_LENGTH, RADIAL_SEGMENTS]} />
+        <meshStandardMaterial color={DOCKING_COLLAR_COLOR} metalness={0.7} roughness={0.35} />
+      </mesh>
+
+      {Array.from({ length: THRUSTER_COUNT }, (_, i) => {
+        const angle = (i / THRUSTER_COUNT) * Math.PI * 2;
+        const x = thrusterRadiusX * Math.cos(angle);
+        const z = thrusterRadiusZ * Math.sin(angle);
+        return (
+          <mesh key={`nozzle-${i}`} position={[x, thrusterY, z]}>
+            <cylinderGeometry
+              args={[
+                THRUSTER_NOZZLE_APEX_RADIUS,
+                THRUSTER_NOZZLE_BASE_RADIUS,
+                THRUSTER_NOZZLE_LENGTH,
+                NOZZLE_SEGMENTS,
+              ]}
+            />
+            <meshStandardMaterial color={THRUSTER_COLOR} metalness={0.5} roughness={0.4} />
+          </mesh>
+        );
+      })}
+    </group>
   );
 }

rpo-app/src/viewport3d/spacecraft/components/NavigationLight.tsx

@@ -0,0 +1,74 @@
+import { DoubleSide, ShaderMaterial } from 'three';
+
+const VERTEX_SHADER = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+
+// Unlit on purpose: solar panels in space face direct sun, so we fake the
+// dark-silicon + busbar look rather than rely on a scene light that may not
+// hit the correct face. fwidth()-based AA keeps gridlines readable from
+// thumbnail (~60 px) to proximity zoom.
+const FRAGMENT_SHADER = /* glsl */ `
+varying vec2 vUv;
+
+const vec3 CELL_COLOR     = vec3(0.04, 0.10, 0.20);
+const vec3 GRID_COLOR     = vec3(0.01, 0.01, 0.01);
+const vec3 BUSBAR_COLOR   = vec3(0.68, 0.68, 0.72);
+const vec3 SUBSTRATE_COLOR = vec3(0.42, 0.42, 0.44);
+const vec3 OUTER_GRID_COLOR = vec3(0.05);
+const vec2 CELLS          = vec2(6.0, 4.0);
+const float GRID_WIDTH    = 0.04;
+const float BUSBAR_WIDTH  = 0.018;
+const float BUSBAR_MIX    = 0.70;
+const float OUTER_GRID_WIDTH = 0.012;
+
+void main() {
+  if (!gl_FrontFacing) {
+    gl_FragColor = vec4(SUBSTRATE_COLOR, 1.0);
+    return;
+  }
+
+  vec2 uvCells = vUv * CELLS;
+  vec2 f = fract(uvCells);
+  vec2 eps = fwidth(uvCells);
+
+  vec2 d = min(f, 1.0 - f);
+  float gx = 1.0 - smoothstep(GRID_WIDTH - eps.x, GRID_WIDTH + eps.x, d.x);
+  float gy = 1.0 - smoothstep(GRID_WIDTH - eps.y, GRID_WIDTH + eps.y, d.y);
+  float grid = max(gx, gy);
+
+  float busbarDist = abs(f.y - 0.5);
+  float busbar = 1.0 - smoothstep(BUSBAR_WIDTH - eps.y, BUSBAR_WIDTH + eps.y, busbarDist);
+
+  vec3 col = CELL_COLOR;
+  col = mix(col, GRID_COLOR, grid);
+  col = mix(col, BUSBAR_COLOR, busbar * BUSBAR_MIX);
+
+  // Sub-panel grid drawn last so tile boundaries mask cells/busbar at the seam.
+  float distX = abs(vUv.x - 0.5);
+  float distY = abs(vUv.y - 0.5);
+  vec2 outerEps = fwidth(vUv);
+  float outerGx = 1.0 - smoothstep(OUTER_GRID_WIDTH - outerEps.x, OUTER_GRID_WIDTH + outerEps.x, distX);
+  float outerGy = 1.0 - smoothstep(OUTER_GRID_WIDTH - outerEps.y, OUTER_GRID_WIDTH + outerEps.y, distY);
+  float outerGrid = max(outerGx, outerGy);
+  col = mix(col, OUTER_GRID_COLOR, outerGrid);
+
+  gl_FragColor = vec4(col, 1.0);
+}
+`;
+
+// Module-level singleton: no instance state, no props, shared across all
+// panels. Avoids GLSL recompile and material diffing on every re-render.
+const SOLAR_CELL_MATERIAL = new ShaderMaterial({
+  vertexShader: VERTEX_SHADER,
+  fragmentShader: FRAGMENT_SHADER,
+  side: DoubleSide,
+});
+
+export function SolarCellMaterial() {
+  return <primitive object={SOLAR_CELL_MATERIAL} attach="material" />;
+}

rpo-app/src/viewport3d/spacecraft/components/SolarCellMaterial.tsx

@@ -1,28 +1,17 @@
 import type { SolarPanelProps } from '../types';
 
-export function SolarPanel({
-  width,
-  height,
-  depth,
-  position,
-  rotation = [0, 0, 0],
-  color = '#d0d0d0',
-  emissive = '#444444',
-  emissiveIntensity = 0.2,
-}: SolarPanelProps) {
+import { SolarCellMaterial } from './SolarCellMaterial';
+
+// The shader handles both plane faces via gl_FrontFacing: +Y = cell grid,
+// -Y = honeycomb substrate.
+
+export function SolarPanel({ width, depth, position, rotation = [0, 0, 0] }: SolarPanelProps) {
   return (
-    <mesh position={position} rotation={rotation}>
-      <boxGeometry args={[width, height, depth]} />
-      <meshStandardMaterial
-        color={color}
-        metalness={0.8}
-        roughness={0.2}
-        emissive={emissive}
-        emissiveIntensity={emissiveIntensity}
-        transparent
-        opacity={1}
-        depthWrite={true}
-      />
-    </mesh>
+    <group position={position} rotation={rotation}>
+      <mesh rotation={[-Math.PI / 2, 0, 0]}>
+        <planeGeometry args={[width, depth]} />
+        <SolarCellMaterial />
+      </mesh>
+    </group>
   );
 }

rpo-app/src/viewport3d/spacecraft/components/SolarPanel.tsx

@@ -2,9 +2,9 @@ import type { SpacecraftProps } from '../types';
 
 import { Arm } from './Arm';
 import { MainBody } from './MainBody';
-import { NavigationLight } from './NavigationLight';
 import { SolarPanel } from './SolarPanel';
 import { SpacecraftLabel } from './SpacecraftLabel';
+import { TrackingMarker } from './TrackingMarker';
 
 const LABEL_OFFSET_PAD = 8;
 
@@ -15,7 +15,7 @@ export function Spacecraft({
   mainBody,
   solarPanels,
   arms = [],
-  navigationLights = [],
+  trackingMarkers = [],
   label,
   labelColor,
   labelFontSize,
@@ -37,8 +37,8 @@ export function Spacecraft({
           <SolarPanel key={`panel-${index}`} {...panel} />
         ))}
 
-        {navigationLights.map((light, index) => (
-          <NavigationLight key={`light-${index}`} {...light} />
+        {trackingMarkers.map((marker, index) => (
+          <TrackingMarker key={`marker-${index}`} {...marker} />
         ))}
       </group>