@austencloud/backgrounds 0.1.0

package/dist/backgrounds/deep-ocean/services/implementations/FishSpineController.js

@@ -0,0 +1,165 @@
+import { SPINE_CONFIGS, SWIM_PARAMS } from "../../domain/models/DeepOceanModels.js";
+import { SpineChain } from "../../physics/SpineChain.js";
+import { FishPropulsionCalculator, smoothSpeed } from "./FishPropulsionCalculator.js";
+import { fishDebugConfig } from "../../domain/debug-config.js";
+/**
+ * FishSpineController - Manages spine chain physics for organic swimming
+ *
+ * Handles spine chain lifecycle (create, update, remove) and synchronizes
+ * physics state back to fish entities for rendering. Now includes propulsion
+ * calculation to connect tail motion with forward movement.
+ */
+export class FishSpineController {
+    spineChains = new Map();
+    propulsionCalculator;
+    constructor(propulsionCalculator) {
+        this.propulsionCalculator = propulsionCalculator ?? new FishPropulsionCalculator();
+    }
+    initializeSpineChain(fish) {
+        if (!fish.useSpineChain)
+            return;
+        const spineConfig = SPINE_CONFIGS[fish.species];
+        const swimParams = SWIM_PARAMS[fish.species];
+        // Calculate segment length based on body length
+        const segmentLength = fish.bodyLength / (spineConfig.jointCount - 1);
+        // Create spine chain
+        const spine = new SpineChain({ ...spineConfig, segmentLength }, fish.x, fish.y, fish.direction);
+        // Set width profile scaled to body height
+        const maxWidth = fish.bodyHeight / 2;
+        spine.setWidthProfile(spineConfig.widthProfile, maxWidth);
+        // Store spine chain reference
+        this.spineChains.set(fish, spine);
+        // Set spine properties on fish for rendering
+        fish.spineConfig = spineConfig;
+        fish.spineJoints = spine.joints.map((j) => ({ ...j }));
+        fish.swimPhase = Math.random() * Math.PI * 2;
+        fish.tailAmplitude = swimParams.tailAmplitude * (fish.bodyHeight / 20);
+        fish.swimSpeed = swimParams.swimSpeed;
+        // Create spine-attached fins
+        fish.spineFins = this.createSpineFins(fish.species, spineConfig.jointCount);
+    }
+    updatePropulsion(fish, deltaSeconds) {
+        // DEBUG: Skip propulsion if disabled via toggle
+        if (!fishDebugConfig.enablePropulsion) {
+            return;
+        }
+        // Only apply propulsion to spine-chain fish
+        if (!fish.useSpineChain || fish.swimPhase === undefined) {
+            return;
+        }
+        // Calculate target speed from tail thrust
+        const targetSpeed = this.propulsionCalculator.calculateTargetSpeed(fish);
+        // Smoothly interpolate toward target speed (prevents jerky changes)
+        fish.speed = smoothSpeed(fish.speed, targetSpeed, deltaSeconds);
+    }
+    updateSpineChain(fish, deltaSeconds, frameMultiplier) {
+        const spine = this.spineChains.get(fish);
+        if (!spine || !fish.swimPhase || !fish.tailAmplitude || !fish.swimSpeed) {
+            return;
+        }
+        // Update swim phase (drives tail oscillation)
+        const speedRatio = fish.speed / fish.baseSpeed;
+        fish.swimPhase += fish.swimSpeed * speedRatio * frameMultiplier;
+        // Head target is where the movement controller already placed the fish
+        // DO NOT add velocity again - applyCruising/applyBehavior already moved fish.x
+        const headTargetX = fish.x;
+        const bob = Math.sin(fish.animationPhase) * fish.bobAmplitude;
+        const headTargetY = fish.baseY + bob;
+        // Apply tail oscillation (DEBUG: can be disabled via toggle)
+        if (fishDebugConfig.enableTailOscillation) {
+            spine.applyTailOscillation(fish.tailAmplitude * speedRatio, fish.swimPhase);
+        }
+        // Update spine chain (head follows target, body follows head)
+        spine.update(headTargetX, headTargetY);
+        // Sync fish position with spine head (should be very close, small adjustment from tail physics)
+        fish.x = spine.head.x;
+        fish.y = spine.head.y;
+        // Update rotation from spine head angle
+        fish.rotation = spine.headAngle;
+        if (fish.direction === -1) {
+            fish.rotation += Math.PI;
+        }
+        // Copy spine joint data back to fish for rendering
+        fish.spineJoints = spine.joints.map((j) => ({ ...j }));
+    }
+    getSpineChain(fish) {
+        return this.spineChains.get(fish);
+    }
+    removeSpineChain(fish) {
+        this.spineChains.delete(fish);
+    }
+    /**
+     * Reposition a fish's spine chain to match updated fish.x/y
+     * Call this after manually moving a fish's position
+     */
+    repositionSpineChain(fish, dx, dy) {
+        const spine = this.spineChains.get(fish);
+        if (!spine)
+            return;
+        // Move all joints in the physics spine chain
+        for (const joint of spine.joints) {
+            joint.x += dx;
+            joint.y += dy;
+        }
+        // Update fish.spineJoints to match
+        fish.spineJoints = spine.joints.map((j) => ({ ...j }));
+    }
+    /**
+     * Create fins attached to spine segments
+     */
+    createSpineFins(species, jointCount) {
+        const fins = [];
+        // Dorsal fin (top, around segment 2-3)
+        fins.push({
+            attachmentSegment: Math.floor(jointCount * 0.25),
+            attachmentSide: "top",
+            baseAngle: -Math.PI / 2,
+            length: species === "tropical" ? 0.35 : 0.25,
+            width: 0.15,
+            segments: 5,
+            curvatureResponse: 0.5,
+        });
+        // Pectoral fins (sides, around segment 1-2)
+        const pectoralSegment = Math.floor(jointCount * 0.15);
+        fins.push({
+            attachmentSegment: pectoralSegment,
+            attachmentSide: "left",
+            baseAngle: -Math.PI / 4,
+            length: species === "tropical" ? 0.25 : 0.15,
+            width: 0.12,
+            segments: 4,
+            curvatureResponse: 0.8,
+        });
+        fins.push({
+            attachmentSegment: pectoralSegment,
+            attachmentSide: "right",
+            baseAngle: Math.PI / 4,
+            length: species === "tropical" ? 0.25 : 0.15,
+            width: 0.12,
+            segments: 4,
+            curvatureResponse: 0.8,
+        });
+        // Pelvic fins (bottom, around segment 3-4)
+        fins.push({
+            attachmentSegment: Math.floor(jointCount * 0.4),
+            attachmentSide: "bottom",
+            baseAngle: Math.PI / 2.5,
+            length: 0.12,
+            width: 0.08,
+            segments: 3,
+            curvatureResponse: 0.3,
+        });
+        // Anal fin (bottom, around segment 5-6)
+        fins.push({
+            attachmentSegment: Math.floor(jointCount * 0.65),
+            attachmentSide: "bottom",
+            baseAngle: Math.PI / 2.2,
+            length: 0.15,
+            width: 0.08,
+            segments: 4,
+            curvatureResponse: 0.4,
+        });
+        return fins;
+    }
+}
+//# sourceMappingURL=FishSpineController.js.map

package/dist/backgrounds/deep-ocean/services/implementations/FishSpineController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishSpineController.js","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishSpineController.ts"],"names":[],"mappings":"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"}

package/dist/backgrounds/deep-ocean/services/implementations/FishSpriteManager.d.ts

@@ -0,0 +1,23 @@
+import type { IFishSpriteManager, PreRenderedSprite } from "../contracts/IFishSpriteManager.js";
+export declare class FishSpriteManager implements IFishSpriteManager {
+    private readonly baseSprites;
+    private readonly colorVariants;
+    /** Pre-rendered sprites (base + variants), ready for immediate drawing */
+    private preRenderedSprites;
+    /** Raw image cache for base sprites */
+    private baseImageCache;
+    private ready;
+    preloadSprites(): Promise<void>;
+    private loadBaseImages;
+    private preRenderAllVariants;
+    /**
+     * Create a pre-rendered canvas with hue rotation applied once.
+     * Uses OffscreenCanvas when available for better performance.
+     */
+    private createPreRenderedCanvas;
+    getRandomSpriteEntry(): PreRenderedSprite | undefined;
+    getAnyLoadedSpriteEntry(): PreRenderedSprite | undefined;
+    getMarineLifeColor(type: "fish" | "jellyfish"): string;
+    isReady(): boolean;
+}
+//# sourceMappingURL=FishSpriteManager.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishSpriteManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishSpriteManager.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishSpriteManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,oCAAoC,CAAC;AAe5C,qBAAa,iBAAkB,YAAW,kBAAkB;IAE1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAQ1B;IAGF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAQ5B;IAEF,0EAA0E;IAC1E,OAAO,CAAC,kBAAkB,CAA2B;IAErD,uCAAuC;IACvC,OAAO,CAAC,cAAc,CAAuC;IAE7D,OAAO,CAAC,KAAK,CAAS;IAEhB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;YAcvB,cAAc;IAsB5B,OAAO,CAAC,oBAAoB;IAkC5B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA8C/B,oBAAoB,IAAI,iBAAiB,GAAG,SAAS;IASrD,uBAAuB,IAAI,iBAAiB,GAAG,SAAS;IAIxD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM;IAyBtD,OAAO,IAAI,OAAO;CAGnB"}

package/dist/backgrounds/deep-ocean/services/implementations/FishSpriteManager.js

@@ -0,0 +1,161 @@
+export class FishSpriteManager {
+    // Base sprites from Kenney pack
+    baseSprites = [
+        { name: "Blue", path: "/assets/background/fish/kenney/fish_blue.png" },
+        { name: "Orange", path: "/assets/background/fish/kenney/fish_orange.png" },
+        { name: "Green", path: "/assets/background/fish/kenney/fish_green.png" },
+        {
+            name: "Grey Long",
+            path: "/assets/background/fish/kenney/fish_grey_long_a.png",
+        },
+    ];
+    // Color variants (pre-rendered at load time, not runtime)
+    colorVariants = [
+        { baseName: "Blue", hueRotate: 30, variantName: "Teal" },
+        { baseName: "Blue", hueRotate: 270, variantName: "Purple" },
+        { baseName: "Orange", hueRotate: -30, variantName: "Gold" },
+        { baseName: "Orange", hueRotate: 330, variantName: "Coral" },
+        { baseName: "Green", hueRotate: -60, variantName: "Cyan" },
+        { baseName: "Green", hueRotate: 60, variantName: "Lime" },
+        { baseName: "Grey Long", hueRotate: 200, variantName: "Deep Blue Long" },
+    ];
+    /** Pre-rendered sprites (base + variants), ready for immediate drawing */
+    preRenderedSprites = [];
+    /** Raw image cache for base sprites */
+    baseImageCache = new Map();
+    ready = false;
+    async preloadSprites() {
+        if (typeof window === "undefined") {
+            return;
+        }
+        // Step 1: Load all base images
+        await this.loadBaseImages();
+        // Step 2: Pre-render all variants to offscreen canvases
+        this.preRenderAllVariants();
+        this.ready = true;
+    }
+    async loadBaseImages() {
+        const loadPromises = this.baseSprites.map((sprite) => {
+            return new Promise((resolve, reject) => {
+                const image = new Image();
+                image.onload = () => {
+                    this.baseImageCache.set(sprite.name, image);
+                    resolve();
+                };
+                image.onerror = (error) => {
+                    console.warn(`Failed to load fish sprite: ${sprite.path}`);
+                    reject(error);
+                };
+                image.src = sprite.path;
+            });
+        });
+        await Promise.all(loadPromises);
+    }
+    preRenderAllVariants() {
+        this.preRenderedSprites = [];
+        // Add base sprites (no hue rotation)
+        for (const sprite of this.baseSprites) {
+            const image = this.baseImageCache.get(sprite.name);
+            if (!image)
+                continue;
+            const canvas = this.createPreRenderedCanvas(image, 0);
+            this.preRenderedSprites.push({
+                sprite,
+                canvas,
+                width: image.naturalWidth,
+                height: image.naturalHeight,
+                hueRotate: 0,
+            });
+        }
+        // Add color variants (pre-rendered with hue rotation)
+        for (const variant of this.colorVariants) {
+            const image = this.baseImageCache.get(variant.baseName);
+            if (!image)
+                continue;
+            const canvas = this.createPreRenderedCanvas(image, variant.hueRotate);
+            this.preRenderedSprites.push({
+                sprite: { name: variant.variantName, path: "" },
+                canvas,
+                width: image.naturalWidth,
+                height: image.naturalHeight,
+                hueRotate: variant.hueRotate,
+            });
+        }
+    }
+    /**
+     * Create a pre-rendered canvas with hue rotation applied once.
+     * Uses OffscreenCanvas when available for better performance.
+     */
+    createPreRenderedCanvas(image, hueRotate) {
+        const width = image.naturalWidth;
+        const height = image.naturalHeight;
+        // Prefer OffscreenCanvas for better memory management
+        let canvas;
+        let ctx;
+        if (typeof OffscreenCanvas !== "undefined") {
+            canvas = new OffscreenCanvas(width, height);
+            ctx = canvas.getContext("2d");
+        }
+        else {
+            canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            ctx = canvas.getContext("2d");
+        }
+        if (!ctx) {
+            // Fallback to regular canvas if context fails
+            const fallback = document.createElement("canvas");
+            fallback.width = width;
+            fallback.height = height;
+            const fbCtx = fallback.getContext("2d");
+            if (fbCtx) {
+                fbCtx.drawImage(image, 0, 0);
+            }
+            return fallback;
+        }
+        // Apply hue rotation filter and draw
+        if (hueRotate !== 0) {
+            ctx.filter = `hue-rotate(${hueRotate}deg)`;
+        }
+        ctx.drawImage(image, 0, 0);
+        ctx.filter = "none";
+        return canvas;
+    }
+    getRandomSpriteEntry() {
+        if (this.preRenderedSprites.length === 0) {
+            return undefined;
+        }
+        const index = Math.floor(Math.random() * this.preRenderedSprites.length);
+        return this.preRenderedSprites[index];
+    }
+    getAnyLoadedSpriteEntry() {
+        return this.preRenderedSprites[0];
+    }
+    getMarineLifeColor(type) {
+        if (type === "fish") {
+            const colors = [
+                "#3d7a8c",
+                "#4a8fa3",
+                "#548da0",
+                "#4b8599",
+                "#5a9cb5",
+                "#6ba8c2",
+            ];
+            return colors[Math.floor(Math.random() * colors.length)] || "#3d7a8c";
+        }
+        // Jellyfish in soft purples, pinks, and blues
+        const colors = [
+            "#7d5a7a",
+            "#8b6d88",
+            "#946f91",
+            "#866783",
+            "#6b7a9d",
+            "#8a7db5",
+        ];
+        return colors[Math.floor(Math.random() * colors.length)] || "#7d5a7a";
+    }
+    isReady() {
+        return this.ready && this.preRenderedSprites.length > 0;
+    }
+}
+//# sourceMappingURL=FishSpriteManager.js.map

package/dist/backgrounds/deep-ocean/services/implementations/FishSpriteManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishSpriteManager.js","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishSpriteManager.ts"],"names":[],"mappings":"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"}

package/dist/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.d.ts

@@ -0,0 +1,20 @@
+import type { FishMarineLife } from "../../domain/models/DeepOceanModels.js";
+import type { IFishVisualUpdater } from "../contracts/IFishVisualUpdater.js";
+/**
+ * FishVisualUpdater - Handles visual animations for fish
+ *
+ * Manages fin physics, body flex, wake trails, bioluminescence,
+ * and other visual effects that don't affect movement logic.
+ */
+export declare class FishVisualUpdater implements IFishVisualUpdater {
+    updateVisuals(fish: FishMarineLife, frameMultiplier: number, animationTime: number): void;
+    updateBodyFlex(fish: FishMarineLife, frameMultiplier: number): void;
+    updateFinPhysics(fish: FishMarineLife, frameMultiplier: number): void;
+    private updateVisualPhases;
+    private updateSingleFin;
+    private updateTailFin;
+    private updateWakeTrail;
+    private updateBioluminescence;
+    private randomInRange;
+}
+//# sourceMappingURL=FishVisualUpdater.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishVisualUpdater.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AA4C7E;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,aAAa,CACX,IAAI,EAAE,cAAc,EACpB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACpB,IAAI;IAaP,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAgBnE,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IA8DrE,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,eAAe;IA2CvB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,aAAa;CAGtB"}

package/dist/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.js

@@ -0,0 +1,185 @@
+/**
+ * Fin physics configuration
+ */
+const FIN_PHYSICS = {
+    stiffness: 0.15,
+    damping: 0.85,
+    accelerationResponse: 0.3,
+    turnResponse: 0.5,
+    idleWave: {
+        amplitude: 0.08,
+        speed: 0.02,
+    },
+    tail: {
+        waveSpeed: 0.12,
+        waveAmplitude: 0.25,
+        forkSpread: 0.15,
+    },
+};
+/**
+ * Wake trail configuration
+ */
+const WAKE_CONFIG = {
+    spawnInterval: 0.08,
+    particleCount: 8,
+    sizeRange: [2, 6],
+    lifetime: 1.2,
+    fadeStart: 0.5,
+};
+/**
+ * Body flex configuration
+ */
+const BODY_FLEX = {
+    swimSpeed: 0.08,
+    amplitude: {
+        cruising: 0.15,
+        darting: 0.25,
+        turning: 0.3,
+    },
+};
+/**
+ * FishVisualUpdater - Handles visual animations for fish
+ *
+ * Manages fin physics, body flex, wake trails, bioluminescence,
+ * and other visual effects that don't affect movement logic.
+ */
+export class FishVisualUpdater {
+    updateVisuals(fish, frameMultiplier, animationTime) {
+        // Core visual animations
+        this.updateVisualPhases(fish, frameMultiplier);
+        // Wake trail
+        this.updateWakeTrail(fish, 0.016 * frameMultiplier, animationTime);
+        // Bioluminescence
+        if (fish.hasBioluminescence) {
+            this.updateBioluminescence(fish, frameMultiplier);
+        }
+    }
+    updateBodyFlex(fish, frameMultiplier) {
+        const speedRatio = fish.speed / fish.baseSpeed;
+        fish.bodyFlexPhase += BODY_FLEX.swimSpeed * speedRatio * frameMultiplier;
+        switch (fish.behavior) {
+            case "darting":
+                fish.bodyFlexAmount = BODY_FLEX.amplitude.darting;
+                break;
+            case "turning":
+                fish.bodyFlexAmount = BODY_FLEX.amplitude.turning;
+                break;
+            default:
+                fish.bodyFlexAmount = BODY_FLEX.amplitude.cruising;
+        }
+    }
+    updateFinPhysics(fish, frameMultiplier) {
+        let speedRatio = fish.speed / fish.baseSpeed;
+        // Tropical fish get nervous (faster fin movement) when too deep
+        // They're out of their comfort zone in the darker waters
+        if (fish.species === "tropical" && fish.preferredVerticalPosition !== undefined) {
+            const bandHeight = fish.depthBand.max - fish.depthBand.min;
+            const currentFraction = (fish.baseY - fish.depthBand.min) / bandHeight;
+            const depthDiscomfort = Math.max(0, currentFraction - 0.6);
+            speedRatio *= 1 + depthDiscomfort * 0.5; // Up to 20% faster fins when deep
+        }
+        const isTurning = fish.behavior === "turning";
+        const isDarting = fish.behavior === "darting";
+        const baseResponse = isTurning
+            ? FIN_PHYSICS.turnResponse
+            : isDarting
+                ? FIN_PHYSICS.accelerationResponse * 1.5
+                : FIN_PHYSICS.accelerationResponse;
+        // Idle wave animation
+        const idleWave = Math.sin(fish.animationPhase * FIN_PHYSICS.idleWave.speed * 60) *
+            FIN_PHYSICS.idleWave.amplitude;
+        // Update each fin with spring physics
+        this.updateSingleFin(fish.dorsalFin, idleWave * 0.5, baseResponse, frameMultiplier);
+        this.updateSingleFin(fish.pectoralFinTop, -idleWave * 0.8 + (speedRatio - 1) * 0.2, baseResponse, frameMultiplier);
+        this.updateSingleFin(fish.pectoralFinBottom, idleWave * 0.8 + (speedRatio - 1) * 0.2, baseResponse, frameMultiplier);
+        this.updateSingleFin(fish.pelvicFin, idleWave * 0.4, baseResponse * 0.5, frameMultiplier);
+        this.updateSingleFin(fish.analFin, idleWave * 0.3, baseResponse * 0.5, frameMultiplier);
+        // Tail has more complex motion
+        this.updateTailFin(fish, speedRatio, frameMultiplier);
+    }
+    updateVisualPhases(fish, frameMultiplier) {
+        // Animation phase (for bobbing, etc)
+        fish.animationPhase += fish.bobSpeed * frameMultiplier;
+        // Scale shimmer
+        fish.scalePhase += fish.scaleSpeed * frameMultiplier;
+        // Gill breathing
+        fish.gillPhase += fish.gillSpeed * frameMultiplier;
+        // Tail phase (legacy + additional animation)
+        fish.tailPhase = fish.tailFin.wavePhase;
+        // Rotation based on vertical drift
+        if (fish.behavior === "cruising" || fish.behavior === "schooling") {
+            const targetRotation = fish.verticalDrift * 0.02 * fish.direction;
+            fish.rotation += (targetRotation - fish.rotation) * 0.1;
+        }
+    }
+    updateSingleFin(fin, targetOffset, _response, frameMultiplier) {
+        fin.targetAngle = targetOffset;
+        const displacement = fin.targetAngle - fin.angle;
+        const springForce = displacement * FIN_PHYSICS.stiffness;
+        fin.velocity += springForce * frameMultiplier;
+        fin.velocity *= FIN_PHYSICS.damping;
+        fin.angle += fin.velocity * frameMultiplier;
+    }
+    updateTailFin(fish, speedRatio, frameMultiplier) {
+        const tail = fish.tailFin;
+        tail.wavePhase += FIN_PHYSICS.tail.waveSpeed * speedRatio * frameMultiplier;
+        const swimAngle = Math.sin(tail.wavePhase) * tail.waveAmplitude * speedRatio;
+        tail.targetAngle = swimAngle;
+        const displacement = tail.targetAngle - tail.angle;
+        const springForce = displacement * FIN_PHYSICS.stiffness * 1.5;
+        tail.velocity += springForce * frameMultiplier;
+        tail.velocity *= FIN_PHYSICS.damping;
+        tail.angle += tail.velocity * frameMultiplier;
+        tail.forkAngle =
+            0.3 + speedRatio * FIN_PHYSICS.tail.forkSpread + Math.abs(swimAngle) * 0.1;
+    }
+    updateWakeTrail(fish, deltaSeconds, animationTime) {
+        // Age existing particles
+        for (let i = fish.wakeTrail.length - 1; i >= 0; i--) {
+            const particle = fish.wakeTrail[i];
+            particle.age += deltaSeconds / WAKE_CONFIG.lifetime;
+            if (particle.age > WAKE_CONFIG.fadeStart) {
+                particle.opacity =
+                    1 -
+                        (particle.age - WAKE_CONFIG.fadeStart) / (1 - WAKE_CONFIG.fadeStart);
+            }
+            if (particle.age >= 1) {
+                fish.wakeTrail.splice(i, 1);
+            }
+        }
+        // Spawn new particles
+        if (animationTime - fish.lastWakeSpawn > WAKE_CONFIG.spawnInterval &&
+            fish.wakeTrail.length < WAKE_CONFIG.particleCount) {
+            const speedRatio = fish.speed / fish.baseSpeed;
+            if (speedRatio > 0.5) {
+                const tailX = fish.x - fish.direction * fish.bodyLength * 0.4;
+                const particle = {
+                    x: tailX + (Math.random() - 0.5) * fish.bodyHeight * 0.3,
+                    y: fish.y + (Math.random() - 0.5) * fish.bodyHeight * 0.3,
+                    age: 0,
+                    size: this.randomInRange(WAKE_CONFIG.sizeRange) * speedRatio,
+                    opacity: 0.3 + speedRatio * 0.3,
+                };
+                fish.wakeTrail.push(particle);
+                fish.lastWakeSpawn = animationTime;
+            }
+        }
+    }
+    updateBioluminescence(fish, frameMultiplier) {
+        fish.glowPhase += 0.02 * frameMultiplier;
+        let pulse = 0.5 + Math.sin(fish.glowPhase) * 0.3;
+        const burst = Math.random() < 0.002 ? 0.5 : 0;
+        // Deep fish glow brighter when ascending into lighter water
+        // They're "seeking warmth" - bioluminescence responds to light gradient
+        if (fish.species === "deep" && fish.behavior === "ascending") {
+            const bandHeight = fish.depthBand.max - fish.depthBand.min;
+            const verticalProgress = 1 - (fish.baseY - fish.depthBand.min) / bandHeight;
+            pulse += verticalProgress * 0.3; // Up to 30% brighter at top
+        }
+        fish.glowIntensity = Math.min(1, pulse + burst);
+    }
+    randomInRange(range) {
+        return range[0] + Math.random() * (range[1] - range[0]);
+    }
+}
+//# sourceMappingURL=FishVisualUpdater.js.map

package/dist/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishVisualUpdater.js","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishVisualUpdater.ts"],"names":[],"mappings":"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"}

package/dist/backgrounds/deep-ocean/services/implementations/FishWobbleAnimator.d.ts

@@ -0,0 +1,16 @@
+import type { FishMarineLife } from "../../domain/models/DeepOceanModels.js";
+import type { WobbleOffset } from "../../domain/types/fish-personality-types.js";
+import type { IFishWobbleAnimator } from "../contracts/IFishWobbleAnimator.js";
+/**
+ * FishWobbleAnimator - Produces expressive wobble animations
+ *
+ * Each wobble type creates a unique visual expression through
+ * rotation, scale, and position offsets that decay over time.
+ */
+export declare class FishWobbleAnimator implements IFishWobbleAnimator {
+    updateWobble(fish: FishMarineLife, deltaSeconds: number): void;
+    getWobbleOffset(fish: FishMarineLife): WobbleOffset;
+    triggerWobble(fish: FishMarineLife, wobbleType: FishMarineLife["wobbleType"], intensity?: number): void;
+    isWobbling(fish: FishMarineLife): boolean;
+}
+//# sourceMappingURL=FishWobbleAnimator.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishWobbleAnimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishWobbleAnimator.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishWobbleAnimator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,8CAA8C,CAAC;AACjG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAuM/E;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IA+B9D,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,YAAY;IAiFnD,aAAa,CACX,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,EACxC,SAAS,GAAE,MAAU,GACpB,IAAI;IAWP,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO;CAO1C"}