@where-stars-drift/core 1.0.0

package/src/entities/formations.ts

@@ -0,0 +1,423 @@
+/**
+ * @fileoverview Defines all fleet formations and a registry to manage them.
+ */
+import type { Starship, ShipClass } from './starship';
+
+// --- Base Formation Interfaces ---
+
+type FormationCategory = 'Military' | 'Mixed';
+
+/**
+ * Common properties for all formations.
+ */
+interface IFormation {
+    name: string;
+    category: FormationCategory;
+    description: string;
+    // The function that calculates and returns target positions for each ship.
+    getPosition: (ships: Starship[]) => { x: number, y: number }[];
+}
+
+/**
+ * Strict formations are role-dependent and class-specific.
+ * They require a specific composition of ship classes to be effective.
+ */
+export interface StrictFormation extends IFormation {
+    type: 'Strict';
+    // Defines the exact ship classes and counts required for this formation.
+    composition: { shipClassName: string; count: number }[];
+}
+
+/**
+ * Free formations are geometry-based and adaptable to any ship composition.
+ * They prioritize spatial arrangement over specific ship roles.
+ */
+export interface FreeFormation extends IFormation {
+    type: 'Free';
+}
+
+export type Formation = StrictFormation | FreeFormation;
+
+// --- Formation Geometry Functions ---
+
+const getStaggeredColumnPosition = (ships: Starship[]): { x: number, y: number }[] => {
+    const offsets = [];
+    const numShips = ships.length;
+    const spacingY = 7.5; // Vertical spacing between ships
+    const spacingX = 5; // Horizontal zigzag spacing
+
+    // Calculate total height of the formation
+    const totalHeight = (numShips - 1) * spacingY;
+    const startY = -totalHeight / 2;
+
+    for (let i = 0; i < numShips; i++) {
+        const x = (i % 2 === 0 ? -1 : 1) * spacingX;
+        const y = startY + i * spacingY;
+        offsets.push({ x, y });
+    }
+    return offsets;
+};
+
+const getBoxPosition = (ships: Starship[]): { x: number, y: number }[] => {
+    const numShips = ships.length;
+    const sideLength = Math.ceil(Math.sqrt(numShips));
+    const spacing = 10;
+    const offsets = [];
+
+    for (let i = 0; i < numShips; i++) {
+        const row = Math.floor(i / sideLength);
+        const col = i % sideLength;
+        const x = (col - (sideLength - 1) / 2) * spacing;
+        const y = (row - (sideLength - 1) / 2) * spacing;
+        offsets.push({ x, y });
+    }
+    return offsets;
+}
+
+const getVPointPosition = (ships: Starship[]): { x: number, y: number }[] => {
+    // This is a complex strict formation. We'll sort ships by their role from the composition.
+    const dreadnought = ships.filter(s => s.shipClass.name === 'Dreadnought');
+    const battleships = ships.filter(s => s.shipClass.name === 'Battleship');
+    const heavyCruisers = ships.filter(s => s.shipClass.name === 'Heavy Cruiser');
+    const destroyers = ships.filter(s => s.shipClass.name === 'Destroyer');
+
+    const sortedShips = [...dreadnought, ...battleships, ...heavyCruisers, ...destroyers];
+    const offsets: { x: number; y: number }[] = [];
+    
+    // 1 Dreadnought at the point
+    if (dreadnought.length > 0) offsets.push({ x: 0, y: -20 });
+
+    // 4 Battleships in a smaller V
+    for(let i=0; i<battleships.length; i++) {
+        const side = i % 2 === 0 ? -1 : 1;
+        const rank = Math.floor(i/2) + 1;
+        offsets.push({ x: side * rank * 7.5, y: -20 + rank * 7.5 });
+    }
+
+    // 8 Heavy Cruisers flanking
+     for(let i=0; i<heavyCruisers.length; i++) {
+        const side = i % 2 === 0 ? -1 : 1;
+        const rank = Math.floor(i/2) + 1;
+        offsets.push({ x: side * (15 + rank * 6), y: -12.5 + rank * 6 });
+    }
+
+    // 12 Destroyers screening
+    for(let i=0; i<destroyers.length; i++) {
+        const side = i % 2 === 0 ? -1 : 1;
+        const rank = Math.floor(i/2) + 1;
+        offsets.push({ x: side * (30 + rank * 4), y: -7.5 + rank * 4 });
+    }
+    
+    // This logic needs to map offsets back to original ships, so we return offsets for the sorted list.
+    return offsets;
+};
+
+const getSpherePosition = (ships: Starship[]): { x: number, y: number }[] => {
+    const militaryShips = ships.filter(s => ['Capital', 'Cruiser', 'Escort', 'Small Craft'].includes(s.shipClass.category));
+    const civilianShips = ships.filter(s => !militaryShips.includes(s));
+
+    const offsets: { x: number, y: number }[] = [];
+    const radius = 8 + militaryShips.length * 1.25;
+
+    // Place military ships in a circle
+    militaryShips.forEach((ship, i) => {
+        const angle = (i / militaryShips.length) * 2 * Math.PI;
+        offsets.push({ x: Math.cos(angle) * radius, y: Math.sin(angle) * radius });
+    });
+
+    // Place civilian ships in the center
+    civilianShips.forEach((ship, i) => {
+        const angle = (i / civilianShips.length) * 2 * Math.PI;
+        offsets.push({ x: Math.cos(angle) * (radius * 0.25), y: Math.sin(angle) * (radius * 0.25) });
+    });
+
+    return offsets;
+};
+
+// --- Formation Definitions ---
+
+const FORMATIONS: Formation[] = [
+    // --- Military Formations (Strict) ---
+    {
+        name: 'Dreadnought V-Point',
+        category: 'Military',
+        type: 'Strict',
+        description: 'A massive Dreadnought leads a wedge of 4 Battleships. 8 Heavy Cruisers flank the sides to provide broadside support, while a screen of 12 Destroyers prevents flanking.',
+        composition: [
+            { shipClassName: 'Dreadnought', count: 1 },
+            { shipClassName: 'Battleship', count: 4 },
+            { shipClassName: 'Heavy Cruiser', count: 8 },
+            { shipClassName: 'Destroyer', count: 12 },
+        ],
+        getPosition: getVPointPosition,
+    },
+    {
+        name: 'Carrier Strike Nest',
+        category: 'Military',
+        type: 'Strict',
+        description: 'Two Carriers are positioned at the center of a sphere formed by 6 Light Cruisers. 20 Corvettes orbit the carriers in a high-speed "swarm" to intercept incoming torpedoes.',
+        composition: [
+            { shipClassName: 'Carrier', count: 2 },
+            { shipClassName: 'Light Cruiser', count: 6 },
+            { shipClassName: 'Corvette', count: 20 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Battlecruiser Intercept Row',
+        category: 'Military',
+        type: 'Strict',
+        description: 'A fast-moving line of 6 Battlecruisers designed for "hit and run." They are supported by 4 Scout ships that stay ahead to provide targeting data for long-range spinal mounts.',
+        composition: [
+            { shipClassName: 'Battlecruiser', count: 6 },
+            { shipClassName: 'Pathfinder', count: 4 }, // Assuming Scout = Pathfinder
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Assault Picket Line',
+        category: 'Military',
+        type: 'Strict',
+        description: '15 Frigates and 10 Destroyers are spaced in a wide, flat plane. This formation is used to block an entire orbital corridor, relying on overlapping sensor ranges.',
+        composition: [
+            { shipClassName: 'Frigate', count: 15 },
+            { shipClassName: 'Destroyer', count: 10 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Dreadnought Brawler Pair',
+        category: 'Military',
+        type: 'Strict',
+        description: 'Two Dreadnoughts fly hull-to-hull, linking their heavy shields. They are screened by a tight group of 4 Heavy Cruisers to protect their rear engines.',
+        composition: [
+            { shipClassName: 'Dreadnought', count: 2 },
+            { shipClassName: 'Heavy Cruiser', count: 4 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+
+    // --- Military Formations (Free) ---
+    {
+        name: 'The Box',
+        category: 'Military',
+        type: 'Free',
+        description: 'Ships are arranged in a 3D cube. Any mix of heavy and light ships can fill the corners, creating a multi-directional fire zone.',
+        getPosition: getBoxPosition,
+    },
+    {
+        name: 'The Double Echelon',
+        category: 'Military',
+        type: 'Free',
+        description: 'Ships are arranged in two parallel diagonal lines. This allows any set of ships to retreat in sequence while the next line covers them.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Orbital Ring',
+        category: 'Military',
+        type: 'Free',
+        description: 'Ships maintain a circular orbit around a fixed point (like a station). Can be held by as few as 3 ships or as many as 100.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Staggered Column',
+        category: 'Military',
+        type: 'Free',
+        description: 'Ships follow each other in a zigzag vertical line. This hides the true number of ships from forward sensors.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Dispersed Cloud',
+        category: 'Military',
+        type: 'Free',
+        description: 'Ships maintain maximum sensor range from one another. This "free" formation prevents a single nuclear or area-of-effect weapon from hitting more than one vessel.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    
+    // --- Mixed Formations (Strict) ---
+    {
+        name: 'Colony Vanguard',
+        category: 'Mixed',
+        type: 'Strict',
+        description: 'A Colony Ship at the center, guarded by 2 Battleships and 4 Frigates. 2 Surveyors lead the formation to scan for habitable zones.',
+        composition: [
+            { shipClassName: 'Colony Ship', count: 1 },
+            { shipClassName: 'Battleship', count: 2 },
+            { shipClassName: 'Frigate', count: 4 },
+            { shipClassName: 'Explorer', count: 2 }, // Assuming Surveyor = Explorer
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Refueling Phalanx',
+        category: 'Mixed',
+        type: 'Strict',
+        description: 'A Tanker is positioned directly behind a Dreadnought for protection. 4 Destroyers circle the pair to prevent "engine-sniping" by enemy fighters.',
+        composition: [
+            { shipClassName: 'Hauler', count: 1 }, // Assuming Tanker = Hauler
+            { shipClassName: 'Dreadnought', count: 1 },
+            { shipClassName: 'Destroyer', count: 4 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Extraction Screen',
+        category: 'Mixed',
+        type: 'Strict',
+        description: '5 Asteroid Miners work a field while 2 Monitors provide stationary defense. 4 Corvettes "patrol" the gaps between the miners.',
+        composition: [
+            { shipClassName: 'Mining Vessel', count: 5 },
+            { shipClassName: 'Monitor', count: 2 },
+            { shipClassName: 'Corvette', count: 4 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Diplomatic Escort',
+        category: 'Mixed',
+        type: 'Strict',
+        description: 'A Diplomatic Courier is surrounded by 4 Light Cruisers in a diamond formation. A Hospital Ship follows at the rear in case of an ambush.',
+        composition: [
+            { shipClassName: 'Diplomatic Courier', count: 1 },
+            { shipClassName: 'Light Cruiser', count: 4 },
+            { shipClassName: 'Hospital Ship', count: 1 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'Salvage Sweep',
+        category: 'Mixed',
+        type: 'Strict',
+        description: 'Two Salvage Ships lead, followed by a Tender to store parts. A Heavy Cruiser provides long-range overwatch from a higher orbital plane.',
+        composition: [
+            { shipClassName: 'Salvage Ship', count: 2 },
+            { shipClassName: 'Hauler', count: 1 }, // Assuming Tender = Hauler
+            { shipClassName: 'Heavy Cruiser', count: 1 },
+        ],
+        getPosition: getStaggeredColumnPosition,
+    },
+
+    // --- Mixed Formations (Free) ---
+    {
+        name: 'The Sphere (Bubble)',
+        category: 'Mixed',
+        type: 'Free',
+        description: 'Civilian ships (like Haulers) stay at the dead center while any available military ships form a protective globe around them.',
+        getPosition: getSpherePosition,
+    },
+    {
+        name: 'The Conical Tail',
+        category: 'Mixed',
+        type: 'Free',
+        description: 'A large military ship (like a Battleship) leads, with peaceful ships (like Freighters) following in its "sensor shadow" to remain undetected.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Hub and Spoke',
+        category: 'Mixed',
+        type: 'Free',
+        description: 'A large ship or station acts as the "hub," with smaller ships (Shuttles, Pathfinders) flying back and forth along set "spokes."',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Anchor Point',
+        category: 'Mixed',
+        type: 'Free',
+        description: 'One heavy ship remains stationary while all other ships (peaceful or military) orbit it in an erratic, unpredictable pattern to confuse attackers.',
+        getPosition: getStaggeredColumnPosition,
+    },
+    {
+        name: 'The Lateral Wall',
+        category: 'Mixed',
+        type: 'Free',
+        description: 'All ships, regardless of class, align on a single flat horizontal plane. This maximizes the fleet\'s ability to scan a large area of space simultaneously.',
+        getPosition: getStaggeredColumnPosition,
+    },
+];
+
+// --- Formation Registry ---
+
+class FormationRegistry {
+    private formations: Formation[];
+    private strictFormations: StrictFormation[];
+    private freeFormations: FreeFormation[];
+
+    constructor() {
+        this.formations = FORMATIONS;
+        this.strictFormations = FORMATIONS.filter(f => f.type === 'Strict') as StrictFormation[];
+        this.freeFormations = FORMATIONS.filter(f => f.type === 'Free') as FreeFormation[];
+    }
+
+    /**
+     * Finds a suitable formation for a given fleet based on its composition.
+     * @param fleetShips The list of starships in the fleet.
+     * @returns A formation, or null if no suitable formation is found.
+     */
+    public getFormationForFleet(fleetShips: Starship[]): Formation | null {
+        // 1. Get the composition of the current fleet.
+        const fleetComposition = new Map<string, number>();
+        fleetShips.forEach(ship => {
+            const name = ship.shipClass.name;
+            fleetComposition.set(name, (fleetComposition.get(name) || 0) + 1);
+        });
+
+        // 2. Try to find a matching strict formation.
+        const matchingStrictFormation = this.strictFormations.find(formation => {
+            // Check if the fleet has the exact number of ships required.
+            const totalShipsInFormation = formation.composition.reduce((sum, role) => sum + role.count, 0);
+            if (fleetShips.length !== totalShipsInFormation) {
+                return false;
+            }
+
+            // Check if the fleet has the correct types and counts of ships.
+            const formationComposition = new Map<string, number>();
+            formation.composition.forEach(role => {
+                formationComposition.set(role.shipClassName, role.count);
+            });
+
+            if (formationComposition.size !== fleetComposition.size) {
+                return false;
+            }
+
+            for (const [shipName, count] of formationComposition) {
+                if (fleetComposition.get(shipName) !== count) {
+                    return false;
+                }
+            }
+
+            return true;
+        });
+
+        if (matchingStrictFormation) {
+            return matchingStrictFormation;
+        }
+
+        // 3. If no strict formation matches, find a suitable free formation.
+        const hasCivilianShips = fleetShips.some(s => 
+            s.shipClass.category === 'Commerce & Logistics' ||
+            s.shipClass.category === 'Resource Extraction' ||
+            s.shipClass.category === 'Diplomatic & Civil'
+        );
+
+        const suitableFreeFormations = this.freeFormations.filter(f => {
+            return hasCivilianShips ? f.category === 'Mixed' : f.category === 'Military';
+        });
+
+        if (suitableFreeFormations.length > 0) {
+            return suitableFreeFormations[Math.floor(Math.random() * suitableFreeFormations.length)];
+        }
+        
+        // 4. As a last resort, return any free formation.
+        if (this.freeFormations.length > 0) {
+            return this.freeFormations[Math.floor(Math.random() * this.freeFormations.length)];
+        }
+        
+        return null;
+    }
+
+    public getAllFormations(): Formation[] {
+        return this.formations;
+    }
+}
+
+export const formationRegistry = new FormationRegistry();

package/src/entities/meteor.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Defines the Meteor class for the night sky simulation.
+ */
+
+import { BoundedBody } from '../base/bounded-body';
+
+// --- Meteor Shower Configuration ---
+export const METEOR_CONFIG = {
+  SHOWER_COOLDOWN_MIN: 900, // 15 seconds in frames
+  SHOWER_COOLDOWN_VARIANCE: 900, // 15-30 seconds in frames
+  COUNT_MIN: 10,
+  COUNT_VARIANCE: 15,
+  SPEED_MIN: 3.2,
+  SPEED_VARIANCE: 6.4,
+  LIFESPAN_MIN: 20,
+  LIFESPAN_VARIANCE: 40,
+  MIN_RADIUS: 0.5,
+  RADIUS_VARIANCE: 1.2,
+};
+
+export class Meteor extends BoundedBody {
+    radius: number;
+    color: string;
+    life: number;
+    maxLife: number;
+
+    constructor(x: number, y: number, vx: number, vy: number, color: string) {
+        const radius = Math.random() * METEOR_CONFIG.RADIUS_VARIANCE + METEOR_CONFIG.MIN_RADIUS;
+        super(x, y, radius);
+        this.radius = radius;
+        this.vx = vx;
+        this.vy = vy;
+        this.color = color;
+        this.maxLife = Math.random() * METEOR_CONFIG.LIFESPAN_VARIANCE + METEOR_CONFIG.LIFESPAN_MIN;
+        this.life = this.maxLife;
+    }
+
+    update() {
+        this.x += this.vx;
+        this.y += this.vy;
+        this.life--;
+    }
+
+    isAlive(width: number, height: number): boolean {
+        return this.life > 0 && this.x > 0 && this.x < width && this.y > 0 && this.y < height;
+    }
+
+    draw(ctx: CanvasRenderingContext2D) {
+        const alpha = this.life / this.maxLife;
+        ctx.beginPath();
+        ctx.globalAlpha = alpha;
+        ctx.strokeStyle = this.color;
+        ctx.lineWidth = this.radius;
+        ctx.moveTo(this.x, this.y);
+        ctx.lineTo(this.x - this.vx * 2, this.y - this.vy * 2);
+        ctx.stroke();
+        ctx.globalAlpha = 1;
+    }
+}

package/src/entities/nebula.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Defines the Nebula class for the night sky simulation.
+ */
+
+import { BoundedBody } from '../base/bounded-body';
+
+// --- Nebula Configuration ---
+export const NEBULA_CONFIG = {
+  COUNT: 5,
+  COLORS: ['rgba(139, 0, 255, 0.15)', 'rgba(0, 191, 255, 0.15)', 'rgba(255, 105, 180, 0.15)'],
+  VELOCITY_RANGE: 0.1,
+  RADIUS_BASE_FACTOR: 1 / 6,
+  RADIUS_VARIANCE_FACTOR: 1 / 4,
+};
+
+
+export class Nebula extends BoundedBody {
+    radius: number;
+    color: string;
+
+    constructor(x: number, y: number, width: number) {
+        const radius = Math.random() * (width * NEBULA_CONFIG.RADIUS_VARIANCE_FACTOR) + (width * NEBULA_CONFIG.RADIUS_BASE_FACTOR);
+        super(x, y, radius);
+        this.radius = radius;
+        this.vx = Math.random() * NEBULA_CONFIG.VELOCITY_RANGE * 2 - NEBULA_CONFIG.VELOCITY_RANGE;
+        this.vy = Math.random() * NEBULA_CONFIG.VELOCITY_RANGE * 2 - NEBULA_CONFIG.VELOCITY_RANGE;
+        this.color = NEBULA_CONFIG.COLORS[Math.floor(Math.random() * NEBULA_CONFIG.COLORS.length)];
+    }
+
+    update(ctx: CanvasRenderingContext2D, width: number, height: number) {
+        this.x += this.vx;
+        this.y += this.vy;
+
+        if (this.x - this.radius > width) this.x = -this.radius;
+        if (this.x + this.radius < 0) this.x = width + this.radius;
+        if (this.y - this.radius > height) this.y = -this.radius;
+        if (this.y + this.radius < 0) this.y = height + this.radius;
+    }
+
+    draw(ctx: CanvasRenderingContext2D) {
+        const gradient = ctx.createRadialGradient(this.x, this.y, this.radius * 0.2, this.x, this.y, this.radius);
+        gradient.addColorStop(0, this.color);
+        gradient.addColorStop(1, 'rgba(0, 0, 0, 0)');
+
+        ctx.fillStyle = gradient;
+        ctx.beginPath();
+        ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
+        ctx.fill();
+    }
+}

package/src/entities/orbit.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Defines the Orbit class for the night sky simulation.
+ */
+
+import { Star } from './star';
+import { DockingPoint } from './docking-point';
+
+// --- Orbit Configuration ---
+export const ORBIT_CONFIG = {
+    COUNT_MIN: 1,
+    COUNT_MAX: 3,
+    RADIUS_MULTIPLIER_MIN: 3,
+    RADIUS_MULTIPLIER_MAX: 7,
+    THICKNESS: 0.1,
+    ALPHA: 0.0,
+    DOCKING_POINTS_PER_ORBIT: 8,
+};
+
+export class Orbit {
+    parent: Star;
+    radius: number;
+    thickness: number;
+    color: string;
+    dockingPoints: DockingPoint[] = [];
+
+    constructor(parent: Star, radius: number, thickness: number, color: string) {
+        this.parent = parent;
+        this.radius = radius;
+        this.thickness = thickness;
+        this.color = color;
+
+        // Add docking points along the orbit
+        const pointsOnOrbit = ORBIT_CONFIG.DOCKING_POINTS_PER_ORBIT;
+        for (let j = 0; j < pointsOnOrbit; j++) {
+            const angle = (j / pointsOnOrbit) * Math.PI * 2;
+            const dx = Math.cos(angle) * this.radius;
+            const dy = Math.sin(angle) * this.radius;
+            this.dockingPoints.push(new DockingPoint(this.parent, dx, dy));
+        }
+    }
+    
+    draw(ctx: CanvasRenderingContext2D) {
+      if (!this.parent || ORBIT_CONFIG.ALPHA === 0) return;
+      ctx.save();
+      ctx.globalAlpha = ORBIT_CONFIG.ALPHA;
+      ctx.beginPath();
+      ctx.strokeStyle = this.color;
+      ctx.lineWidth = this.thickness;
+      ctx.arc(this.parent.x, this.parent.y, this.radius, 0, 2 * Math.PI);
+      ctx.stroke();
+      ctx.restore();
+    }
+}

package/src/entities/pulsar.ts

@@ -0,0 +1,64 @@
+
+/**
+ * @fileoverview Defines the Pulsar class, a specialized type of Star.
+ */
+
+import { Star, STAR_CONFIG } from './star';
+
+// --- Pulsar Configuration ---
+export const PULSAR_CONFIG = {
+  PULSAR_SPEED_MIN: 12.0,
+  PULSAR_SPEED_VARIANCE: 12.0,
+};
+
+let pulsarCounter = 0;
+
+export class Pulsar extends Star {
+  pulsarPhase: number;
+  pulsationSpeed: number;
+
+  constructor(x: number, y: number) {
+    super(x, y);
+    this.name = `P-${++pulsarCounter}`;
+    this.pulsarPhase = Math.random() * Math.PI * 2;
+    this.pulsationSpeed = Math.random() * PULSAR_CONFIG.PULSAR_SPEED_VARIANCE + PULSAR_CONFIG.PULSAR_SPEED_MIN;
+    this.hasAura = Math.random() < STAR_CONFIG.AURA_CHANCE;
+  }
+
+  update(
+    ctx: CanvasRenderingContext2D,
+    width: number,
+    height: number,
+    mouse: { dx: number; dy: number },
+    interactive: boolean,
+    isMouseInside: boolean,
+    pulseTime?: number
+  ) {
+    // Call the parent update method to handle movement only in the main simulation
+    if (width > 0 && height > 0) {
+      super.update(ctx, width, height, mouse, interactive, isMouseInside);
+    }
+
+    // Update radius for the live simulation instance
+    const effectivePulseTime = (pulseTime || 0) * this.pulsationSpeed;
+    const pulseFactor = (Math.sin(effectivePulseTime + this.pulsarPhase) + 1.5) / 2.5;
+    this.radius = this.baseRadius * pulseFactor;
+    this.boundingRadius = this.radius;
+  }
+
+  draw(ctx: CanvasRenderingContext2D, pulseTime: number) {
+    const effectivePulseTime = pulseTime * this.pulsationSpeed;
+    
+    ctx.save();
+    
+    // Calculate alpha for the "blinking" effect
+    const alphaPulseFactor = (Math.sin(effectivePulseTime + this.pulsarPhase) + 1) / 2; // varies between 0 and 1
+    ctx.globalAlpha = 0.5 + alphaPulseFactor * 0.5;
+
+    // Call the base star drawing method which handles auras and hover effects correctly.
+    // We wrap it in save/restore to contain the globalAlpha change.
+    super.drawBase(ctx, pulseTime);
+    
+    ctx.restore();
+  }
+}

package/src/entities/ring.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Defines the Ring class, a visual ring around a celestial body.
+ */
+import type { CelestialBody } from '../base/celestial-body';
+
+export class Ring {
+    parent: CelestialBody;
+    radius: number;
+    thickness: number;
+    color: string;
+    isDotted: boolean;
+
+    constructor(parent: CelestialBody, radius: number, thickness: number, color: string, isDotted: boolean) {
+        this.parent = parent;
+        this.radius = radius;
+        this.thickness = thickness;
+        this.color = color;
+        this.isDotted = isDotted;
+    }
+
+    draw(ctx: CanvasRenderingContext2D) {
+        // When drawing rings individually in the catalog, the parent might not be at (0,0) relative to the canvas.
+        // We will draw relative to the current transform.
+        const drawX = this.parent ? this.parent.x : 0;
+        const drawY = this.parent ? this.parent.y : 0;
+
+        ctx.beginPath();
+        ctx.strokeStyle = this.color;
+        ctx.lineWidth = this.thickness;
+
+        if (this.isDotted) {
+            ctx.setLineDash([2, 3]);
+        }
+
+        ctx.arc(drawX, drawY, this.radius, 0, 2 * Math.PI);
+        ctx.stroke();
+
+        if (this.isDotted) {
+            ctx.setLineDash([]);
+        }
+    }
+}