Implement roadmap phases 1 through 8

apps/viewer/src/api.ts

@@ -1,5 +1,11 @@
 import type { WorldDelta, WorldSnapshot } from "./contracts";
 
+export interface WorldStreamScope {
+  scopeKind?: string;
+  systemId?: string | null;
+  bubbleId?: string | null;
+}
+
 export async function fetchWorldSnapshot(signal?: AbortSignal) {
   const response = await fetch("/api/world", { signal });
   if (!response.ok) {
@@ -15,8 +21,22 @@ export function openWorldStream(
     onOpen?: () => void;
     onError?: () => void;
   },
+  scope?: WorldStreamScope,
 ) {
-  const stream = new EventSource(`/api/world/stream?afterSequence=${afterSequence}`);
+  const query = new URLSearchParams({
+    afterSequence: String(afterSequence),
+  });
+  if (scope?.scopeKind) {
+    query.set("scopeKind", scope.scopeKind);
+  }
+  if (scope?.systemId) {
+    query.set("systemId", scope.systemId);
+  }
+  if (scope?.bubbleId) {
+    query.set("bubbleId", scope.bubbleId);
+  }
+
+  const stream = new EventSource(`/api/world/stream?${query.toString()}`);
   stream.addEventListener("open", () => handlers.onOpen?.());
   stream.addEventListener("error", () => handlers.onError?.());
   stream.addEventListener("world-delta", (event) => {

apps/viewer/src/contracts.ts

@@ -5,8 +5,14 @@ export interface WorldSnapshot {
   tickIntervalMs: number;
   generatedAtUtc: string;
   systems: SystemSnapshot[];
+  spatialNodes: SpatialNodeSnapshot[];
+  localBubbles: LocalBubbleSnapshot[];
   nodes: ResourceNodeSnapshot[];
   stations: StationSnapshot[];
+  claims: ClaimSnapshot[];
+  constructionSites: ConstructionSiteSnapshot[];
+  marketOrders: MarketOrderSnapshot[];
+  policies: PolicySetSnapshot[];
   ships: ShipSnapshot[];
   factions: FactionSnapshot[];
 }
@@ -17,10 +23,17 @@ export interface WorldDelta {
   generatedAtUtc: string;
   requiresSnapshotRefresh: boolean;
   events: SimulationEventRecord[];
+  spatialNodes: SpatialNodeDelta[];
+  localBubbles: LocalBubbleDelta[];
   nodes: ResourceNodeDelta[];
   stations: StationDelta[];
+  claims: ClaimDelta[];
+  constructionSites: ConstructionSiteDelta[];
+  marketOrders: MarketOrderDelta[];
+  policies: PolicySetDelta[];
   ships: ShipDelta[];
   factions: FactionDelta[];
+  scope?: ObserverScope | null;
 }
 
 export interface SimulationEventRecord {
@@ -29,6 +42,16 @@ export interface SimulationEventRecord {
   kind: string;
   message: string;
   occurredAtUtc: string;
+  family?: string;
+  scopeKind?: string;
+  scopeEntityId?: string | null;
+  visibility?: string;
+}
+
+export interface ObserverScope {
+  scopeKind: string;
+  systemId?: string | null;
+  bubbleId?: string | null;
 }
 
 export interface Vector3Dto {
@@ -77,6 +100,32 @@ export interface ResourceNodeSnapshot {
 
 export interface ResourceNodeDelta extends ResourceNodeSnapshot {}
 
+export interface SpatialNodeSnapshot {
+  id: string;
+  systemId: string;
+  kind: string;
+  localPosition: Vector3Dto;
+  bubbleId: string;
+  parentNodeId?: string | null;
+  occupyingStructureId?: string | null;
+  orbitReferenceId?: string | null;
+}
+
+export interface SpatialNodeDelta extends SpatialNodeSnapshot {}
+
+export interface LocalBubbleSnapshot {
+  id: string;
+  nodeId: string;
+  systemId: string;
+  radius: number;
+  occupantShipIds: string[];
+  occupantStationIds: string[];
+  occupantClaimIds: string[];
+  occupantConstructionSiteIds: string[];
+}
+
+export interface LocalBubbleDelta extends LocalBubbleSnapshot {}
+
 export interface InventoryEntry {
   itemId: string;
   amount: number;
@@ -88,16 +137,92 @@ export interface StationSnapshot {
   category: string;
   systemId: string;
   localPosition: Vector3Dto;
+  nodeId?: string | null;
+  bubbleId?: string | null;
+  anchorNodeId?: string | null;
   color: string;
   dockedShips: number;
   dockingPads: number;
   energyStored: number;
   inventory: InventoryEntry[];
   factionId: string;
+  commanderId?: string | null;
+  policySetId?: string | null;
+  population: number;
+  populationCapacity: number;
+  workforceRequired: number;
+  workforceEffectiveRatio: number;
+  installedModules: string[];
+  marketOrderIds: string[];
 }
 
 export interface StationDelta extends StationSnapshot {}
 
+export interface ClaimSnapshot {
+  id: string;
+  factionId: string;
+  systemId: string;
+  nodeId: string;
+  bubbleId: string;
+  state: string;
+  health: number;
+  placedAtUtc: string;
+  activatesAtUtc: string;
+}
+
+export interface ClaimDelta extends ClaimSnapshot {}
+
+export interface ConstructionSiteSnapshot {
+  id: string;
+  factionId: string;
+  systemId: string;
+  nodeId: string;
+  bubbleId: string;
+  targetKind: string;
+  targetDefinitionId: string;
+  blueprintId?: string | null;
+  claimId?: string | null;
+  stationId?: string | null;
+  state: string;
+  progress: number;
+  inventory: InventoryEntry[];
+  requiredItems: InventoryEntry[];
+  deliveredItems: InventoryEntry[];
+  assignedConstructorShipIds: string[];
+  marketOrderIds: string[];
+}
+
+export interface ConstructionSiteDelta extends ConstructionSiteSnapshot {}
+
+export interface MarketOrderSnapshot {
+  id: string;
+  factionId: string;
+  stationId?: string | null;
+  constructionSiteId?: string | null;
+  kind: string;
+  itemId: string;
+  amount: number;
+  remainingAmount: number;
+  valuation: number;
+  reserveThreshold?: number | null;
+  policySetId?: string | null;
+  state: string;
+}
+
+export interface MarketOrderDelta extends MarketOrderSnapshot {}
+
+export interface PolicySetSnapshot {
+  id: string;
+  ownerKind: string;
+  ownerId: string;
+  tradeAccessPolicy: string;
+  dockingAccessPolicy: string;
+  constructionAccessPolicy: string;
+  operationalRangePolicy: string;
+}
+
+export interface PolicySetDelta extends PolicySetSnapshot {}
+
 export interface ShipSnapshot {
   id: string;
   label: string;
@@ -111,25 +236,55 @@ export interface ShipSnapshot {
   orderKind: string | null;
   defaultBehaviorKind: string;
   controllerTaskKind: string;
+  nodeId?: string | null;
+  bubbleId?: string | null;
+  dockedStationId?: string | null;
+  commanderId?: string | null;
+  policySetId?: string | null;
   cargoCapacity: number;
+  workerPopulation: number;
   energyStored: number;
   inventory: InventoryEntry[];
   factionId: string;
   health: number;
   history: string[];
+  spatialState: ShipSpatialStateSnapshot;
 }
 
 export interface ShipDelta extends ShipSnapshot {}
 
+export interface ShipSpatialStateSnapshot {
+  spaceLayer: string;
+  currentSystemId: string;
+  currentNodeId?: string | null;
+  currentBubbleId?: string | null;
+  localPosition?: Vector3Dto | null;
+  systemPosition?: Vector3Dto | null;
+  movementRegime: string;
+  destinationNodeId?: string | null;
+  transit?: ShipTransitSnapshot | null;
+}
+
+export interface ShipTransitSnapshot {
+  regime: string;
+  originNodeId?: string | null;
+  destinationNodeId?: string | null;
+  startedAtUtc?: string | null;
+  arrivalDueAtUtc?: string | null;
+  progress: number;
+}
+
 export interface FactionSnapshot {
   id: string;
   label: string;
   color: string;
   credits: number;
+  populationTotal: number;
   oreMined: number;
   goodsProduced: number;
   shipsBuilt: number;
   shipsLost: number;
+  defaultPolicySetId?: string | null;
 }
 
 export interface FactionDelta extends FactionSnapshot {}