@zendir/ui 0.4.1 → 0.6.0

package/dist/react/hooks/useSimulationScene.js

@@ -1,401 +1,508 @@
-import { useState, useRef, useCallback, useEffect } from "react";
-const PLACEHOLDER_SCENECRAFT_POSITION = { x: 6771, y: 0, z: 0 };
-const TICK_RETRY = {
-  maxRetries: 2,
-  initialDelayMs: 500,
-  maxDelayMs: 1500
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/react/hooks/useSimulationScene.ts
+/**
+* @zendir/ui - useSimulationScene Hook
+*
+* Bridge between a `zendir-ts` `ZendirClient` and the `ZenSpace3D`
+* Cesium component. On mount the hook calls `getSimulationStructure`
+* to bucket simulation objects (spacecraft / ground stations) and then
+* polls each spacecraft's `Position_BN_N` on a fixed interval, emitting
+* ZenSpace3D-shaped state.
+*
+* Ground stations are resolved once per structure load (lat/lon is
+* static — no ECI polling).
+*
+* Structure JSON may use `ID`/`id` and `Type`/`type` interchangeably;
+* the walker accepts common variants. Call `refresh()` to re-fetch the
+* structure (e.g. on a consumer-owned timer) so newly spawned objects
+* appear without remounting.
+*
+* `referenceDate` is the wall-clock instant of the last successful tick
+* — pass it to `<ZenSpace3D referenceTime={...} />` so ECI/J2000
+* positions rotate to ECEF at the engine's "now".
+*
+* OPTIONAL DEPENDENCY: requires a `zendir-ts` client instance. The
+* client is passed in to avoid coupling this hook to a specific
+* session-management strategy (the consumer app owns sessions).
+*/
+/**
+* Non-zero ECI placeholder (km) used until the first `Position_BN_N`
+* poll lands. The 3D viewer expects ECI / J2000 km positions; the
+* origin (0,0,0) sits at Earth's centre and would crash Cesium's
+* `Cartesian3.normalize` with "normalized result is not a number".
+*
+* Value: ~400 km altitude on the +X axis (vernal-equinox direction).
+* Renders just above the equator and is invisible after one tick.
+*/
+var PLACEHOLDER_SCENECRAFT_POSITION = {
+	x: 6771,
+	y: 0,
+	z: 0
 };
-const DEFAULT_POLL_MS = 2e3;
-const M_TO_KM = 1 / 1e3;
+/**
+* Per-tick retry config for the position-polling loop.
+*
+* The SDK defaults `getProperties` to `engineWarmup` (24 retries /
+* ~3.6 min). That budget is right for a one-shot mount call, but
+* disastrous for a 2-second polling tick — a single warmup blip would
+* stall every subsequent tick (skip-if-busy guard) for minutes, freezing
+* the viewer. We override with a tight 2-attempt budget that rides
+* through quick blips (~1.5 s total) but cedes to the next tick fast.
+*/
+var TICK_RETRY = {
+	maxRetries: 2,
+	initialDelayMs: 500,
+	maxDelayMs: 1500
+};
+var DEFAULT_POLL_MS = 2e3;
+var M_TO_KM = 1 / 1e3;
 function useSimulationScene(options) {
-  const {
-    client,
-    containerId,
-    simulationId,
-    pollIntervalMs = DEFAULT_POLL_MS,
-    enabled = true
-  } = options;
-  const [satellites, setSatellites] = useState([]);
-  const [groundStations, setGroundStations] = useState([]);
-  const [celestialBodies, setCelestialBodies] = useState([]);
-  const [objects, setObjects] = useState([]);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState(null);
-  const [referenceDate, setReferenceDate] = useState(() => /* @__PURE__ */ new Date());
-  const [structureDiag, setStructureDiag] = useState(null);
-  const [positionTickDiag, setPositionTickDiag] = useState(null);
-  const spacecraftIdsRef = useRef([]);
-  const celestialBodyIdsRef = useRef([]);
-  const celestialBodyNamesRef = useRef([]);
-  const intervalRef = useRef(null);
-  const abortRef = useRef(null);
-  const tickInFlightRef = useRef(false);
-  const positionPropsRef = useRef(null);
-  const tickPositions = useCallback(
-    async (signal) => {
-      if (!client) return;
-      const ids = spacecraftIdsRef.current;
-      if (ids.length === 0) return;
-      if (tickInFlightRef.current) return;
-      tickInFlightRef.current = true;
-      try {
-        const propsToFetch = positionPropsRef.current;
-        const useFallbackAll = !propsToFetch || propsToFetch.length === 0;
-        const updates = await Promise.allSettled(
-          ids.map(
-            (id) => useFallbackAll ? (
-              // `retry: TICK_RETRY` overrides the SDK's engineWarmup default
-              // for this one call. See the TICK_RETRY definition above for
-              // the rationale (avoid a stuck tick stalling the viewer).
-              client.getAllProperties(id, containerId, { signal, retry: TICK_RETRY })
-            ) : client.getProperties(id, propsToFetch, containerId, {
-              signal,
-              retry: TICK_RETRY
-            })
-          )
-        );
-        if (signal.aborted) return;
-        let parsedOk = 0;
-        let parseFailed = 0;
-        let requestFailed = 0;
-        let firstResponseKeys = [];
-        let firstResponseSample = "";
-        for (let i = 0; i < ids.length; i++) {
-          const result = updates[i];
-          if (result.status !== "fulfilled") {
-            requestFailed += 1;
-            continue;
-          }
-          if (i === 0) {
-            const v = result.value;
-            if (v && typeof v === "object") firstResponseKeys = Object.keys(v);
-            try {
-              const json = JSON.stringify(v);
-              firstResponseSample = json.length > 200 ? `${json.slice(0, 200)}…` : json;
-            } catch {
-              firstResponseSample = String(v);
-            }
-          }
-          if (parsePositionVelocity(result.value)) parsedOk += 1;
-          else parseFailed += 1;
-        }
-        setPositionTickDiag({
-          attemptedAt: /* @__PURE__ */ new Date(),
-          requested: ids.length,
-          parsedOk,
-          parseFailed,
-          requestFailed,
-          requestedProps: useFallbackAll ? null : propsToFetch,
-          firstResponseKeys,
-          firstResponseSample
-        });
-        setSatellites((prev) => {
-          if (prev.length === 0) return prev;
-          const next = prev.slice();
-          for (let i = 0; i < ids.length; i++) {
-            const result = updates[i];
-            if (result.status !== "fulfilled") continue;
-            const idx = next.findIndex((sc) => sc.id === ids[i]);
-            if (idx < 0) continue;
-            const parsed = parsePositionVelocity(result.value);
-            if (!parsed) continue;
-            next[idx] = { ...next[idx], position: parsed.position, velocity: parsed.velocity };
-          }
-          return next;
-        });
-        const celIds = celestialBodyIdsRef.current;
-        if (celIds.length > 0) {
-          const celResults = await Promise.allSettled(
-            celIds.map(
-              (id) => client.getProperties(id, ["Position", "IsCentralBody"], containerId, {
-                signal,
-                retry: TICK_RETRY
-              })
-            )
-          );
-          if (signal.aborted) return;
-          const next = [];
-          for (let i = 0; i < celIds.length; i++) {
-            const result = celResults[i];
-            if (result.status !== "fulfilled") continue;
-            const raw = result.value;
-            const obj = raw && typeof raw === "object" ? raw : null;
-            if (!obj) continue;
-            if (obj.IsCentralBody === true) continue;
-            const posVec = parseVec3(obj.Position);
-            if (!posVec) continue;
-            const positionKm = scaleVec(posVec, M_TO_KM);
-            const id = celIds[i];
-            const name = celestialBodyNamesRef.current[i] ?? `CelestialBody ${shortId(id)}`;
-            next.push({ id, name, position: positionKm });
-          }
-          setCelestialBodies(next);
-        }
-      } catch {
-      } finally {
-        tickInFlightRef.current = false;
-        if (!signal.aborted) {
-          setReferenceDate(/* @__PURE__ */ new Date());
-        }
-      }
-    },
-    [client, containerId]
-  );
-  const loadStructure = useCallback(
-    async (signal) => {
-      if (!client) return;
-      setIsLoading(true);
-      setError(null);
-      try {
-        const structure = await client.getSimulationStructure(simulationId, containerId, { signal });
-        if (signal.aborted) return;
-        setStructureDiag({
-          topLevelKeys: Object.keys(structure),
-          rawObjectCount: Array.isArray(structure.Objects) ? structure.Objects.length : Array.isArray(structure.objects) ? structure.objects.length : -1,
-          rawSystemCount: Array.isArray(structure.Systems) ? structure.Systems.length : Array.isArray(structure.systems) ? structure.systems.length : -1
-        });
-        const buckets = bucketStructure(structure);
-        spacecraftIdsRef.current = buckets.spacecraft.map((s) => s.id);
-        celestialBodyIdsRef.current = buckets.celestialBodyIds;
-        celestialBodyNamesRef.current = buckets.celestialBodyNames;
-        setSatellites(buckets.spacecraft);
-        setObjects(buckets.objects);
-        if (buckets.spacecraft.length > 0) {
-          try {
-            const probeId = buckets.spacecraft[0].id;
-            const all = await client.getAllProperties(probeId, containerId, { signal });
-            if (signal.aborted) return;
-            positionPropsRef.current = detectPositionPropertyNames(all);
-          } catch {
-            positionPropsRef.current = null;
-          }
-        } else {
-          positionPropsRef.current = null;
-        }
-        const stationResults = await Promise.allSettled(
-          buckets.groundStationIds.map(
-            (id) => client.getAllProperties(id, containerId, { signal })
-          )
-        );
-        if (signal.aborted) return;
-        const stations = [];
-        for (let i = 0; i < buckets.groundStationIds.length; i++) {
-          const result = stationResults[i];
-          const id = buckets.groundStationIds[i];
-          const fallbackName = buckets.groundStationNames[i] ?? shortId(id);
-          if (result.status !== "fulfilled") {
-            stations.push({ id, name: fallbackName, latitude: 0, longitude: 0 });
-            continue;
-          }
-          stations.push(toGroundStation(id, fallbackName, result.value));
-        }
-        setGroundStations(stations);
-        setIsLoading(false);
-        if (spacecraftIdsRef.current.length > 0) {
-          await tickPositions(signal);
-        }
-      } catch (err) {
-        if (signal.aborted) return;
-        setError(err instanceof Error ? err.message : "Failed to load simulation structure");
-        setIsLoading(false);
-      }
-    },
-    [client, containerId, simulationId, tickPositions]
-  );
-  useEffect(() => {
-    if (!client || !containerId || !simulationId) {
-      setIsLoading(false);
-      return;
-    }
-    const controller = new AbortController();
-    abortRef.current = controller;
-    void loadStructure(controller.signal);
-    return () => {
-      controller.abort();
-      if (abortRef.current === controller) abortRef.current = null;
-    };
-  }, [client, containerId, simulationId, loadStructure]);
-  useEffect(() => {
-    if (!enabled || !client || error) {
-      if (intervalRef.current) {
-        clearInterval(intervalRef.current);
-        intervalRef.current = null;
-      }
-      return;
-    }
-    const interval = setInterval(() => {
-      const controller = new AbortController();
-      void tickPositions(controller.signal).catch(() => void 0);
-    }, pollIntervalMs);
-    intervalRef.current = interval;
-    return () => {
-      clearInterval(interval);
-      if (intervalRef.current === interval) intervalRef.current = null;
-    };
-  }, [client, enabled, error, pollIntervalMs, tickPositions]);
-  const refresh = useCallback(async () => {
-    const controller = new AbortController();
-    await loadStructure(controller.signal);
-  }, [loadStructure]);
-  return {
-    satellites,
-    groundStations,
-    celestialBodies,
-    objects,
-    isLoading,
-    error,
-    refresh,
-    referenceDate,
-    structureDiag,
-    positionTickDiag
-  };
+	const { client, containerId, simulationId, pollIntervalMs = DEFAULT_POLL_MS, enabled = true } = options;
+	const [satellites, setSatellites] = useState([]);
+	const [groundStations, setGroundStations] = useState([]);
+	const [celestialBodies, setCelestialBodies] = useState([]);
+	const [objects, setObjects] = useState([]);
+	const [isLoading, setIsLoading] = useState(true);
+	const [error, setError] = useState(null);
+	const [referenceDate, setReferenceDate] = useState(() => /* @__PURE__ */ new Date());
+	const [structureDiag, setStructureDiag] = useState(null);
+	const [positionTickDiag, setPositionTickDiag] = useState(null);
+	const spacecraftIdsRef = useRef([]);
+	const celestialBodyIdsRef = useRef([]);
+	const celestialBodyNamesRef = useRef([]);
+	const intervalRef = useRef(null);
+	const abortRef = useRef(null);
+	const tickInFlightRef = useRef(false);
+	const positionPropsRef = useRef(null);
+	const tickPositions = useCallback(async (signal) => {
+		if (!client) return;
+		const ids = spacecraftIdsRef.current;
+		if (ids.length === 0) return;
+		if (tickInFlightRef.current) return;
+		tickInFlightRef.current = true;
+		try {
+			const propsToFetch = positionPropsRef.current;
+			const useFallbackAll = !propsToFetch || propsToFetch.length === 0;
+			const updates = await Promise.allSettled(ids.map((id) => useFallbackAll ? client.getAllProperties(id, containerId, {
+				signal,
+				retry: TICK_RETRY
+			}) : client.getProperties(id, propsToFetch, containerId, {
+				signal,
+				retry: TICK_RETRY
+			})));
+			if (signal.aborted) return;
+			let parsedOk = 0;
+			let parseFailed = 0;
+			let requestFailed = 0;
+			let firstResponseKeys = [];
+			let firstResponseSample = "";
+			for (let i = 0; i < ids.length; i++) {
+				const result = updates[i];
+				if (result.status !== "fulfilled") {
+					requestFailed += 1;
+					continue;
+				}
+				if (i === 0) {
+					const v = result.value;
+					if (v && typeof v === "object") firstResponseKeys = Object.keys(v);
+					try {
+						const json = JSON.stringify(v);
+						firstResponseSample = json.length > 200 ? `${json.slice(0, 200)}…` : json;
+					} catch {
+						firstResponseSample = String(v);
+					}
+				}
+				if (parsePositionVelocity(result.value)) parsedOk += 1;
+				else parseFailed += 1;
+			}
+			setPositionTickDiag({
+				attemptedAt: /* @__PURE__ */ new Date(),
+				requested: ids.length,
+				parsedOk,
+				parseFailed,
+				requestFailed,
+				requestedProps: useFallbackAll ? null : propsToFetch,
+				firstResponseKeys,
+				firstResponseSample
+			});
+			setSatellites((prev) => {
+				if (prev.length === 0) return prev;
+				const next = prev.slice();
+				for (let i = 0; i < ids.length; i++) {
+					const result = updates[i];
+					if (result.status !== "fulfilled") continue;
+					const idx = next.findIndex((sc) => sc.id === ids[i]);
+					if (idx < 0) continue;
+					const parsed = parsePositionVelocity(result.value);
+					if (!parsed) continue;
+					next[idx] = {
+						...next[idx],
+						position: parsed.position,
+						velocity: parsed.velocity
+					};
+				}
+				return next;
+			});
+			const celIds = celestialBodyIdsRef.current;
+			if (celIds.length > 0) {
+				const celResults = await Promise.allSettled(celIds.map((id) => client.getProperties(id, ["Position", "IsCentralBody"], containerId, {
+					signal,
+					retry: TICK_RETRY
+				})));
+				if (signal.aborted) return;
+				const next = [];
+				for (let i = 0; i < celIds.length; i++) {
+					const result = celResults[i];
+					if (result.status !== "fulfilled") continue;
+					const raw = result.value;
+					const obj = raw && typeof raw === "object" ? raw : null;
+					if (!obj) continue;
+					if (obj.IsCentralBody === true) continue;
+					const posVec = parseVec3(obj.Position);
+					if (!posVec) continue;
+					const positionKm = scaleVec(posVec, M_TO_KM);
+					const id = celIds[i];
+					const name = celestialBodyNamesRef.current[i] ?? `CelestialBody ${shortId(id)}`;
+					next.push({
+						id,
+						name,
+						position: positionKm
+					});
+				}
+				setCelestialBodies(next);
+			}
+		} catch {} finally {
+			tickInFlightRef.current = false;
+			if (!signal.aborted) setReferenceDate(/* @__PURE__ */ new Date());
+		}
+	}, [client, containerId]);
+	const loadStructure = useCallback(async (signal) => {
+		if (!client) return;
+		setIsLoading(true);
+		setError(null);
+		try {
+			const structure = await client.getSimulationStructure(simulationId, containerId, { signal });
+			if (signal.aborted) return;
+			setStructureDiag({
+				topLevelKeys: Object.keys(structure),
+				rawObjectCount: Array.isArray(structure.Objects) ? structure.Objects.length : Array.isArray(structure.objects) ? structure.objects.length : -1,
+				rawSystemCount: Array.isArray(structure.Systems) ? structure.Systems.length : Array.isArray(structure.systems) ? structure.systems.length : -1
+			});
+			const buckets = bucketStructure(structure);
+			spacecraftIdsRef.current = buckets.spacecraft.map((s) => s.id);
+			celestialBodyIdsRef.current = buckets.celestialBodyIds;
+			celestialBodyNamesRef.current = buckets.celestialBodyNames;
+			setSatellites(buckets.spacecraft);
+			setObjects(buckets.objects);
+			if (buckets.spacecraft.length > 0) try {
+				const probeId = buckets.spacecraft[0].id;
+				const all = await client.getAllProperties(probeId, containerId, { signal });
+				if (signal.aborted) return;
+				positionPropsRef.current = detectPositionPropertyNames(all);
+			} catch {
+				positionPropsRef.current = null;
+			}
+			else positionPropsRef.current = null;
+			const stationResults = await Promise.allSettled(buckets.groundStationIds.map((id) => client.getAllProperties(id, containerId, { signal })));
+			if (signal.aborted) return;
+			const stations = [];
+			for (let i = 0; i < buckets.groundStationIds.length; i++) {
+				const result = stationResults[i];
+				const id = buckets.groundStationIds[i];
+				const fallbackName = buckets.groundStationNames[i] ?? shortId(id);
+				if (result.status !== "fulfilled") {
+					stations.push({
+						id,
+						name: fallbackName,
+						latitude: 0,
+						longitude: 0
+					});
+					continue;
+				}
+				stations.push(toGroundStation(id, fallbackName, result.value));
+			}
+			setGroundStations(stations);
+			setIsLoading(false);
+			if (spacecraftIdsRef.current.length > 0) await tickPositions(signal);
+		} catch (err) {
+			if (signal.aborted) return;
+			setError(err instanceof Error ? err.message : "Failed to load simulation structure");
+			setIsLoading(false);
+		}
+	}, [
+		client,
+		containerId,
+		simulationId,
+		tickPositions
+	]);
+	useEffect(() => {
+		if (!client || !containerId || !simulationId) {
+			setIsLoading(false);
+			return;
+		}
+		const controller = new AbortController();
+		abortRef.current = controller;
+		loadStructure(controller.signal);
+		return () => {
+			controller.abort();
+			if (abortRef.current === controller) abortRef.current = null;
+		};
+	}, [
+		client,
+		containerId,
+		simulationId,
+		loadStructure
+	]);
+	useEffect(() => {
+		if (!enabled || !client || error) {
+			if (intervalRef.current) {
+				clearInterval(intervalRef.current);
+				intervalRef.current = null;
+			}
+			return;
+		}
+		const interval = setInterval(() => {
+			const controller = new AbortController();
+			tickPositions(controller.signal).catch(() => void 0);
+		}, pollIntervalMs);
+		intervalRef.current = interval;
+		return () => {
+			clearInterval(interval);
+			if (intervalRef.current === interval) intervalRef.current = null;
+		};
+	}, [
+		client,
+		enabled,
+		error,
+		pollIntervalMs,
+		tickPositions
+	]);
+	return {
+		satellites,
+		groundStations,
+		celestialBodies,
+		objects,
+		isLoading,
+		error,
+		refresh: useCallback(async () => {
+			const controller = new AbortController();
+			await loadStructure(controller.signal);
+		}, [loadStructure]),
+		referenceDate,
+		structureDiag,
+		positionTickDiag
+	};
 }
+/**
+* First non-empty string among PascalCase / camelCase keys for one logical field.
+*/
 function firstStringField(obj, keys) {
-  for (const key of keys) {
-    const v = obj[key];
-    if (typeof v === "string" && v.length > 0) return v;
-  }
-  return void 0;
+	for (const key of keys) {
+		const v = obj[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
 }
+/**
+* Walk a `GetSimulationStructure` response and bucket objects by Type.
+*
+* Tolerant of:
+*   - PascalCase (`Objects`, `Systems`, `Children`) and camelCase
+*     (`objects`, `systems`, `children`) — the engine has shipped both.
+*   - Objects nested at the top level, inside Systems children, or under
+*     any depth of `Children` / `children` arrays.
+*/
 function bucketStructure(structure) {
-  const out = {
-    spacecraft: [],
-    groundStationIds: [],
-    groundStationNames: [],
-    celestialBodyIds: [],
-    celestialBodyNames: [],
-    objects: []
-  };
-  const topObjects = pickArray(structure, ["Objects", "objects"]);
-  for (const obj of topObjects) walkObject(obj, out);
-  const topSystems = pickArray(structure, ["Systems", "systems"]);
-  for (const sys of topSystems) walkObject(sys, out);
-  return out;
+	const out = {
+		spacecraft: [],
+		groundStationIds: [],
+		groundStationNames: [],
+		celestialBodyIds: [],
+		celestialBodyNames: [],
+		objects: []
+	};
+	const topObjects = pickArray(structure, ["Objects", "objects"]);
+	for (const obj of topObjects) walkObject(obj, out);
+	const topSystems = pickArray(structure, ["Systems", "systems"]);
+	for (const sys of topSystems) walkObject(sys, out);
+	return out;
 }
+/**
+* Return the first non-empty array found under any of `keys` on `obj`.
+* Allows the caller to tolerate PascalCase / camelCase top-level array keys
+* without duplicating logic at every call site.
+*/
 function pickArray(obj, keys) {
-  for (const key of keys) {
-    const v = obj[key];
-    if (Array.isArray(v) && v.length > 0) return v;
-  }
-  for (const key of keys) {
-    const v = obj[key];
-    if (Array.isArray(v)) return v;
-  }
-  return [];
+	for (const key of keys) {
+		const v = obj[key];
+		if (Array.isArray(v) && v.length > 0) return v;
+	}
+	for (const key of keys) {
+		const v = obj[key];
+		if (Array.isArray(v)) return v;
+	}
+	return [];
 }
 function walkObject(node, out) {
-  if (!node || typeof node !== "object") return;
-  const obj = node;
-  const id = firstStringField(obj, ["ID", "id", "Id"]);
-  const type = firstStringField(obj, ["Type", "type"]);
-  const name = firstStringField(obj, ["Name", "name"]);
-  if (id && type) {
-    if (type === "Spacecraft" || type.endsWith(".Spacecraft")) {
-      upsertObjectSummary(out, {
-        id,
-        name: name ?? `Spacecraft ${shortId(id)}`,
-        kind: "spacecraft"
-      });
-      out.spacecraft.push({
-        id,
-        name: name ?? `Spacecraft ${shortId(id)}`,
-        category: "satellite",
-        position: { ...PLACEHOLDER_SCENECRAFT_POSITION },
-        visualRadius: 50
-      });
-    } else if (type === "GroundStation" || type.endsWith(".GroundStation")) {
-      upsertObjectSummary(out, {
-        id,
-        name: name ?? `GroundStation ${shortId(id)}`,
-        kind: "groundStation"
-      });
-      out.groundStationIds.push(id);
-      out.groundStationNames.push(name);
-    } else if (type === "CelestialBody" || type.endsWith(".CelestialBody")) {
-      upsertObjectSummary(out, {
-        id,
-        name: name ?? `CelestialBody ${shortId(id)}`,
-        kind: "celestialBody"
-      });
-      out.celestialBodyIds.push(id);
-      out.celestialBodyNames.push(name);
-    }
-  }
-  const children = pickArray(obj, ["Children", "children"]);
-  for (const child of children) walkObject(child, out);
+	if (!node || typeof node !== "object") return;
+	const obj = node;
+	const id = firstStringField(obj, [
+		"ID",
+		"id",
+		"Id"
+	]);
+	const type = firstStringField(obj, ["Type", "type"]);
+	const name = firstStringField(obj, ["Name", "name"]);
+	if (id && type) {
+		if (type === "Spacecraft" || type.endsWith(".Spacecraft")) {
+			upsertObjectSummary(out, {
+				id,
+				name: name ?? `Spacecraft ${shortId(id)}`,
+				kind: "spacecraft"
+			});
+			out.spacecraft.push({
+				id,
+				name: name ?? `Spacecraft ${shortId(id)}`,
+				category: "satellite",
+				position: { ...PLACEHOLDER_SCENECRAFT_POSITION },
+				visualRadius: 50
+			});
+		} else if (type === "GroundStation" || type.endsWith(".GroundStation")) {
+			upsertObjectSummary(out, {
+				id,
+				name: name ?? `GroundStation ${shortId(id)}`,
+				kind: "groundStation"
+			});
+			out.groundStationIds.push(id);
+			out.groundStationNames.push(name);
+		} else if (type === "CelestialBody" || type.endsWith(".CelestialBody")) {
+			upsertObjectSummary(out, {
+				id,
+				name: name ?? `CelestialBody ${shortId(id)}`,
+				kind: "celestialBody"
+			});
+			out.celestialBodyIds.push(id);
+			out.celestialBodyNames.push(name);
+		}
+	}
+	const children = pickArray(obj, ["Children", "children"]);
+	for (const child of children) walkObject(child, out);
 }
 function upsertObjectSummary(out, next) {
-  const idx = out.objects.findIndex((o) => o.id === next.id);
-  if (idx >= 0) {
-    out.objects[idx] = next;
-    return;
-  }
-  out.objects.push(next);
+	const idx = out.objects.findIndex((o) => o.id === next.id);
+	if (idx >= 0) {
+		out.objects[idx] = next;
+		return;
+	}
+	out.objects.push(next);
 }
+/**
+* Inspect a `getAllProperties` response and return the position property name
+* this engine exposes on a spacecraft.
+*
+* Only position is probed — velocity is intentionally excluded. The engine's
+* `/get` endpoint validates names more strictly than `getAllProperties`, and
+* `Velocity_BN_N` exists in the probe response but triggers a 400 when passed
+* to `getProperties`. Since velocity is optional (only position is used for
+* rendering), we never request it in the polling tick.
+*
+* Returns at most one name — the first position candidate whose value parses
+* as a 3-vector in the probe response.
+*/
 function detectPositionPropertyNames(props) {
-  const positionCandidates = ["Position_BN_N", "Position", "r_BN_N", "r_N"];
-  for (const name of positionCandidates) {
-    if (name in props && parseVec3(props[name]) !== null) {
-      return [name];
-    }
-  }
-  return [];
+	for (const name of [
+		"Position_BN_N",
+		"Position",
+		"r_BN_N",
+		"r_N"
+	]) if (name in props && parseVec3(props[name]) !== null) return [name];
+	return [];
 }
+/**
+* Engines have shipped two property-naming conventions for spacecraft state:
+*
+*   - Basilisk-style ECI: `Position_BN_N`, `Velocity_BN_N` (m, m/s)
+*   - Shorter form:       `Position`, `Velocity`           (m, m/s)
+*
+* Both are in metres. ZenSpace3D's `Vector3D` is documented as km / km/s,
+* so we scale by 1e-3. The first key that produces a parseable 3-vector wins.
+*/
 function parsePositionVelocity(raw) {
-  if (!raw || typeof raw !== "object") return null;
-  const obj = raw;
-  const position = parseVec3(obj.Position_BN_N) ?? parseVec3(obj.Position) ?? parseVec3(obj.position);
-  if (!position) return null;
-  if (position.x === 0 && position.y === 0 && position.z === 0) return null;
-  const velocity = parseVec3(obj.Velocity_BN_N) ?? parseVec3(obj.Velocity) ?? parseVec3(obj.velocity);
-  return {
-    position: scaleVec(position, M_TO_KM),
-    velocity: velocity ? scaleVec(velocity, M_TO_KM) : void 0
-  };
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	const position = parseVec3(obj.Position_BN_N) ?? parseVec3(obj.Position) ?? parseVec3(obj.position);
+	if (!position) return null;
+	if (position.x === 0 && position.y === 0 && position.z === 0) return null;
+	const velocity = parseVec3(obj.Velocity_BN_N) ?? parseVec3(obj.Velocity) ?? parseVec3(obj.velocity);
+	return {
+		position: scaleVec(position, M_TO_KM),
+		velocity: velocity ? scaleVec(velocity, M_TO_KM) : void 0
+	};
 }
+/**
+* Accepts the engine's two known shapes for a 3-vector property:
+* either a `[x, y, z]` array or an object with `X/Y/Z` keys (the
+* gateway's JSON normalizer flips between the two depending on how
+* the property is declared in the model).
+*/
 function parseVec3(raw) {
-  if (Array.isArray(raw) && raw.length >= 3) {
-    const [x, y, z] = raw;
-    if (typeof x === "number" && typeof y === "number" && typeof z === "number") {
-      return { x, y, z };
-    }
-  }
-  if (raw && typeof raw === "object") {
-    const obj = raw;
-    const x = obj.X ?? obj.x;
-    const y = obj.Y ?? obj.y;
-    const z = obj.Z ?? obj.z;
-    if (typeof x === "number" && typeof y === "number" && typeof z === "number") {
-      return { x, y, z };
-    }
-  }
-  return null;
+	if (Array.isArray(raw) && raw.length >= 3) {
+		const [x, y, z] = raw;
+		if (typeof x === "number" && typeof y === "number" && typeof z === "number") return {
+			x,
+			y,
+			z
+		};
+	}
+	if (raw && typeof raw === "object") {
+		const obj = raw;
+		const x = obj.X ?? obj.x;
+		const y = obj.Y ?? obj.y;
+		const z = obj.Z ?? obj.z;
+		if (typeof x === "number" && typeof y === "number" && typeof z === "number") return {
+			x,
+			y,
+			z
+		};
+	}
+	return null;
 }
 function scaleVec(v, k) {
-  return { x: v.x * k, y: v.y * k, z: v.z * k };
+	return {
+		x: v.x * k,
+		y: v.y * k,
+		z: v.z * k
+	};
 }
 function toGroundStation(id, fallbackName, props) {
-  const name = firstStringField(props, ["Name"]) ?? fallbackName;
-  const latitude = pickNumber(props, ["Latitude", "latitude"]) ?? 0;
-  const longitude = pickNumber(props, ["Longitude", "longitude"]) ?? 0;
-  const elevation = pickNumber(props, ["Altitude", "altitude", "Elevation"]);
-  const minElevation = pickNumber(props, ["MinElevation", "MinimumElevation"]);
-  const station = { id, name, latitude, longitude };
-  if (elevation !== void 0) station.elevation = elevation;
-  if (minElevation !== void 0) station.minElevation = minElevation;
-  return station;
+	const name = firstStringField(props, ["Name"]) ?? fallbackName;
+	const latitude = pickNumber(props, ["Latitude", "latitude"]) ?? 0;
+	const longitude = pickNumber(props, ["Longitude", "longitude"]) ?? 0;
+	const elevation = pickNumber(props, [
+		"Altitude",
+		"altitude",
+		"Elevation"
+	]);
+	const minElevation = pickNumber(props, ["MinElevation", "MinimumElevation"]);
+	const station = {
+		id,
+		name,
+		latitude,
+		longitude
+	};
+	if (elevation !== void 0) station.elevation = elevation;
+	if (minElevation !== void 0) station.minElevation = minElevation;
+	return station;
 }
 function pickNumber(obj, keys) {
-  for (const key of keys) {
-    const v = obj[key];
-    if (typeof v === "number" && Number.isFinite(v)) return v;
-  }
-  return void 0;
+	for (const key of keys) {
+		const v = obj[key];
+		if (typeof v === "number" && Number.isFinite(v)) return v;
+	}
 }
 function shortId(id) {
-  return id.length > 8 ? id.slice(0, 8) : id;
+	return id.length > 8 ? id.slice(0, 8) : id;
 }
-export {
-  useSimulationScene
-};
-//# sourceMappingURL=useSimulationScene.js.map
+//#endregion
+export { useSimulationScene as default, useSimulationScene };
+
+//# sourceMappingURL=useSimulationScene.js.map