chore: restructure gpu/ folder per Spec C

src/@types/EngineGpuHandles.d.ts

@@ -33,10 +33,10 @@
  * GPU bag rather than the whole `EngineState`.
  */
 
-import type { PointRenderer } from '../services/gpu/pointRenderer';
-import type { PostProcess } from '../services/gpu/postProcess';
-import type { createPickRenderer } from '../services/gpu/pickRenderer';
-import type { FilamentRenderer } from '../services/gpu/filamentRenderer';
+import type { PointRenderer } from '../services/gpu/renderers/pointRenderer';
+import type { PostProcess } from '../services/gpu/passes/postProcess';
+import type { createPickRenderer } from '../services/gpu/renderers/pickRenderer';
+import type { FilamentRenderer } from '../services/gpu/renderers/filamentRenderer';
 
 export type EngineGpuHandles = {
   renderer: PointRenderer | null;

src/data/defaults.ts

@@ -107,7 +107,7 @@ export const DEFAULT_DEPTH_FADE_ENABLED = true;
  * Procedural Milky Way impostor defaults ON.  The single screen-aligned
  * quad at the world origin gives the user a visceral "you are here"
  * sense before they fly out into the cosmic-web view.  See
- * `services/gpu/milkyWayRenderer.ts` and `utils/math/milkyWayFade.ts`
+ * `services/gpu/renderers/milkyWayRenderer.ts` and `utils/math/milkyWayFade.ts`
  * for the rendering rationale and the distance-fade band.
  */
 export const DEFAULT_MILKY_WAY_ENABLED = true;
@@ -128,7 +128,7 @@ export const DEFAULT_MILKY_WAY_ENABLED = true;
  * For local-dev clones without the offline DisPerSE pipeline run, the
  * file is missing → `loadFilaments` returns null silently → the
  * renderer skips the overlay regardless of this default.  No regression
- * for that path.  See `services/gpu/filamentRenderer.ts`.
+ * for that path.  See `services/gpu/renderers/filamentRenderer.ts`.
  */
 export const DEFAULT_FILAMENTS_ENABLED = true;
 

src/services/engine/frame/renderFrame.ts

@@ -92,12 +92,12 @@ import type { OrbitCamera, PointCloud } from '../../../@types';
 import type { Source } from '../../../data/sources';
 import type { BiasMode } from '../../../data/biasMode';
 import type { ToneMapCurve } from '../../../data/toneMapCurve';
-import type { PointRenderer } from '../../gpu/pointRenderer';
-import type { PostProcess } from '../../gpu/postProcess';
-import type { QuadRenderer } from '../../gpu/quadRenderer';
-import type { DiskRenderer } from '../../gpu/diskRenderer';
-import type { MilkyWayRenderer } from '../../gpu/milkyWayRenderer';
-import type { FilamentRenderer } from '../../gpu/filamentRenderer';
+import type { PointRenderer } from '../../gpu/renderers/pointRenderer';
+import type { PostProcess } from '../../gpu/passes/postProcess';
+import type { QuadRenderer } from '../../gpu/renderers/quadRenderer';
+import type { DiskRenderer } from '../../gpu/renderers/diskRenderer';
+import type { MilkyWayRenderer } from '../../gpu/renderers/milkyWayRenderer';
+import type { FilamentRenderer } from '../../gpu/renderers/filamentRenderer';
 import type { ThumbnailSubsystem } from '../subsystems/thumbnailSubsystem';
 import type { FamousMetaEntry, FamousXrefMap } from '../../loading/fetchers/famousMetaFetcher';
 import { milkyWayFadeAlpha } from '../../../utils/math/milkyWayFade';

src/services/engine/frame/runFrame.ts

@@ -73,10 +73,10 @@
 
 import type { EngineCallbacks, EngineState } from '../../../@types';
 import type { Source } from '../../../data/sources';
-import type { QuadRenderer } from '../../gpu/quadRenderer';
-import type { DiskRenderer } from '../../gpu/diskRenderer';
-import type { MilkyWayRenderer } from '../../gpu/milkyWayRenderer';
-import type { FilamentRenderer } from '../../gpu/filamentRenderer';
+import type { QuadRenderer } from '../../gpu/renderers/quadRenderer';
+import type { DiskRenderer } from '../../gpu/renderers/diskRenderer';
+import type { MilkyWayRenderer } from '../../gpu/renderers/milkyWayRenderer';
+import type { FilamentRenderer } from '../../gpu/renderers/filamentRenderer';
 import type { FpsCounter } from '../subsystems/fpsCounter';
 
 import { computeViewProj, updatePosition } from '../../camera/orbitCamera';

src/services/engine/interaction/clickHandler.ts

@@ -67,7 +67,7 @@
 
 import type { PointCloud, PointInfo } from '../../../@types';
 import { Source } from '../../../data/sources';
-import type { createPickRenderer } from '../../gpu/pickRenderer';
+import type { createPickRenderer } from '../../gpu/renderers/pickRenderer';
 
 /**
  * Snapshot of the renderer's per-source draw records the picker

src/services/engine/phases/initGpu.ts

@@ -71,13 +71,13 @@
  */
 
 import { initGpu as gpuInitGpu, resizeCanvasToDisplay } from '../../gpu/device';
-import { PointRenderer } from '../../gpu/pointRenderer';
-import { createPostProcess } from '../../gpu/postProcess';
-import { QuadRenderer } from '../../gpu/quadRenderer';
-import { DiskRenderer } from '../../gpu/diskRenderer';
-import { ProceduralDiskRenderer } from '../../gpu/proceduralDiskRenderer';
-import { MilkyWayRenderer } from '../../gpu/milkyWayRenderer';
-import { FilamentRenderer } from '../../gpu/filamentRenderer';
+import { PointRenderer } from '../../gpu/renderers/pointRenderer';
+import { createPostProcess } from '../../gpu/passes/postProcess';
+import { QuadRenderer } from '../../gpu/renderers/quadRenderer';
+import { DiskRenderer } from '../../gpu/renderers/diskRenderer';
+import { ProceduralDiskRenderer } from '../../gpu/renderers/proceduralDiskRenderer';
+import { MilkyWayRenderer } from '../../gpu/renderers/milkyWayRenderer';
+import { FilamentRenderer } from '../../gpu/renderers/filamentRenderer';
 import { POINT_SOURCE_REGISTRY, wirePointSourceSlot } from '../wiring/pointSourceRegistry';
 
 import type { EngineState } from '../../../@types';

src/services/engine/phases/wireInput.ts

@@ -79,7 +79,7 @@
 import { Source } from '../../../data/sources';
 import { createOrbitCamera } from '../../camera/orbitCamera';
 import { attachOrbitControls } from '../../camera/orbitControls';
-import { createPickRenderer } from '../../gpu/pickRenderer';
+import { createPickRenderer } from '../../gpu/renderers/pickRenderer';
 import { createClickResolver } from '../interaction/clickHandler';
 import { attachEngineInputs } from '../interaction/inputBindings';
 import { computeInitialCamera } from '../camera/cameraFraming';

src/services/engine/subsystems/thumbnailSubsystem.ts

@@ -70,11 +70,11 @@ import { Source } from '../../../data/sources';
 import { pickColourIndex } from '../../../data/colourIndex';
 import type { PointCloud, QuadInstance } from '../../../@types';
 import type { OrbitCamera } from '../../../@types';
-import { TextureAtlas } from '../../gpu/textureAtlas';
+import { TextureAtlas } from '../../gpu/resources/textureAtlas';
 import { PriorityQueue } from '../../../utils/concurrency/priorityQueue';
-import type { QuadRenderer } from '../../gpu/quadRenderer';
-import { DiskRenderer, type DiskInstance } from '../../gpu/diskRenderer';
-import { ProceduralDiskRenderer } from '../../gpu/proceduralDiskRenderer';
+import type { QuadRenderer } from '../../gpu/renderers/quadRenderer';
+import { DiskRenderer, type DiskInstance } from '../../gpu/renderers/diskRenderer';
+import { ProceduralDiskRenderer } from '../../gpu/renderers/proceduralDiskRenderer';
 import type { ProceduralDiskInstance } from '../../../@types/ProceduralDiskInstance';
 import { fetchGalaxyBitmap } from '../../../utils/network/galaxyImageFetcher';
 import { cartesianToRaDecZ } from '../../../utils/math';

src/services/gpu/postProcess.ts → src/services/gpu/passes/postProcess.ts

@@ -96,10 +96,10 @@
 // compiles a strictly-smaller GPUShaderModule from disjoint source.
 // Both modules import their shared structs from `shaders/toneMap/io.wesl`
 // so the vertex-to-fragment interface stays byte-identical.
-import vsCode from './shaders/toneMap/vertex.wesl?static';
-import fsCode from './shaders/toneMap/fragment.wesl?static';
-import { ToneMapCurve } from '../../data/toneMapCurve';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import vsCode from '../shaders/toneMap/vertex.wesl?static';
+import fsCode from '../shaders/toneMap/fragment.wesl?static';
+import { ToneMapCurve } from '../../../data/toneMapCurve';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 /**
  * Plain `{ width, height }` pair, kept local to this module.  We

src/services/gpu/diskRenderer.ts → src/services/gpu/renderers/diskRenderer.ts

@@ -27,10 +27,10 @@
  */
 
 import type { mat4 } from 'gl-matrix';
-import type { GpuContext } from '../../@types';
-import vsCode from './shaders/disks/vertex.wesl?static';
-import fsCode from './shaders/disks/fragment.wesl?static';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import type { GpuContext } from '../../../@types';
+import vsCode from '../shaders/disks/vertex.wesl?static';
+import fsCode from '../shaders/disks/fragment.wesl?static';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 export type DiskInstance = {
   x: number;

src/services/gpu/filamentRenderer.ts → src/services/gpu/renderers/filamentRenderer.ts

@@ -22,12 +22,12 @@
  *   - clear()                       → drops the instance buffer
  *   - destroy()                     → releases all GPU resources
  */
-import vsCode from './shaders/filaments/vertex.wesl?static';
-import fsCode from './shaders/filaments/fragment.wesl?static';
-import type { FilamentCloud } from '../../@types/FilamentCloud';
+import vsCode from '../shaders/filaments/vertex.wesl?static';
+import fsCode from '../shaders/filaments/fragment.wesl?static';
+import type { FilamentCloud } from '../../../@types/FilamentCloud';
 import type { mat4 } from 'gl-matrix';
-import { CloudFade } from './cloudFade';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import { CloudFade } from '../resources/cloudFade';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 const FLOATS_PER_SEGMENT = 8; // startxyz + startD + endxyz + endD
 

src/services/gpu/milkyWayRenderer.ts → src/services/gpu/renderers/milkyWayRenderer.ts

@@ -86,9 +86,9 @@
 // for the procedural-galaxy helpers. Sharing modules across pipelines
 // would invite the WebGPU 'auto' bind-group-layout trap — sidestepped
 // here by giving each stage its own module from disjoint sources.
-import vsCode from './shaders/milkyWay/vertex.wesl?static';
-import fsCode from './shaders/milkyWay/fragment.wesl?static';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import vsCode from '../shaders/milkyWay/vertex.wesl?static';
+import fsCode from '../shaders/milkyWay/fragment.wesl?static';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 type Init = {
   device: GPUDevice;

src/services/gpu/pickRenderer.ts → src/services/gpu/renderers/pickRenderer.ts

@@ -58,11 +58,11 @@
 // shared with PointRenderer, but we compile our OWN GPUShaderModule from
 // it; never share modules across pipelines (see the `auto` bind-group-
 // layout trap noted in pointRenderer.ts).
-import vsCode from './shaders/points/vertex.wesl?static';
-import pickFsCode from './shaders/points/pickFragment.wesl?static';
-import type { Source } from '../../data/sources';
+import vsCode from '../shaders/points/vertex.wesl?static';
+import pickFsCode from '../shaders/points/pickFragment.wesl?static';
+import type { Source } from '../../../data/sources';
 import type { PointRenderer } from './pointRenderer';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 

src/services/gpu/pointRenderer.ts → src/services/gpu/renderers/pointRenderer.ts

@@ -40,15 +40,15 @@
  */
 
 import { mat4 } from 'gl-matrix';
-import type { PointCloud } from '../../@types';
-import { ALL_SOURCES, Source } from '../../data/sources';
-import { BiasMode } from '../../data/biasMode';
-import { type SchechterTriple } from '../../data/surveyFluxLimits';
+import type { PointCloud } from '../../../@types';
+import { ALL_SOURCES, Source } from '../../../data/sources';
+import { BiasMode } from '../../../data/biasMode';
+import { type SchechterTriple } from '../../../data/surveyFluxLimits';
 import {
   type BuildPointInterleavedBufferInput,
   type BuildPointInterleavedBufferMode,
   type BuildPointInterleavedBufferResult,
-} from '../engine/bake/buildPointInterleavedBuffer';
+} from '../../engine/bake/buildPointInterleavedBuffer';
 
 // `?worker` is a Vite-specific import suffix.  It instructs the bundler to
 // emit `buildPointInterleavedBuffer.worker.ts` as a separate worker chunk
@@ -61,15 +61,15 @@ import {
 // In Node-only test environments the `?worker` suffix isn't resolvable;
 // tests inject a synchronous fallback via `setBuildBufferFactory` instead
 // of importing this module.  See the `BuildBufferFactory` type below.
-import BuildPointBufferWorker from '../engine/bake/buildPointInterleavedBuffer.worker?worker';
+import BuildPointBufferWorker from '../../engine/bake/buildPointInterleavedBuffer.worker?worker';
 
 // Lazy-Schechter worker import — same `?worker` Vite suffix as the main
 // vertex bake, but for the much smaller (single Float32Array) Schechter
 // integral.  Spawned by `setBiasMode(BiasMode.Schechter)` the first time
 // the user selects that mode; subsequent toggles reuse the cached
 // `Float32Array` per source for instant re-toggle.
-import ComputeSchechterRatiosWorker from '../engine/bake/computeSchechterRatios.worker?worker';
-import { type ComputeSchechterRatiosInput } from '../engine/bake/computeSchechterRatios';
+import ComputeSchechterRatiosWorker from '../../engine/bake/computeSchechterRatios.worker?worker';
+import { type ComputeSchechterRatiosInput } from '../../engine/bake/computeSchechterRatios';
 
 // Lazy-angular-reweight worker import — same `?worker` Vite suffix.  The
 // HEALPix bake is much cheaper than the Schechter integral (~100-300 ms for
@@ -78,8 +78,8 @@ import { type ComputeSchechterRatiosInput } from '../engine/bake/computeSchechte
 // `setBiasMode(BiasMode.AngularReweight)` the first time the user picks
 // that mode; subsequent toggles reuse `cachedAngularWeights` for instant
 // re-toggle.
-import ComputeAngularWeightsWorker from '../engine/bake/computeAngularWeights.worker?worker';
-import { type ComputeAngularWeightsInput } from '../engine/bake/computeAngularWeights';
+import ComputeAngularWeightsWorker from '../../engine/bake/computeAngularWeights.worker?worker';
+import { type ComputeAngularWeightsInput } from '../../engine/bake/computeAngularWeights';
 
 // `?static` is wesl-plugin's Vite import suffix. It runs the WESL linker at
 // build time and hands us a plain WGSL string with all `import` statements
@@ -97,10 +97,10 @@ import { type ComputeAngularWeightsInput } from '../engine/bake/computeAngularWe
 // fragment GPUShaderModule from disjoint sources, eliminating a class of
 // selection-on-wrong-galaxy bugs that came from one shader module servicing
 // two pipelines with diverging fragment paths.
-import vsCode from './shaders/points/vertex.wesl?static';
-import colorFsCode from './shaders/points/colorFragment.wesl?static';
-import { CloudFade } from './cloudFade';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import vsCode from '../shaders/points/vertex.wesl?static';
+import colorFsCode from '../shaders/points/colorFragment.wesl?static';
+import { CloudFade } from '../resources/cloudFade';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 // ─── Layout constants ─────────────────────────────────────────────────────────
 

src/services/gpu/proceduralDiskRenderer.ts → src/services/gpu/renderers/proceduralDiskRenderer.ts

@@ -11,10 +11,10 @@
  * is just the JS-side pipeline wiring.
  */
 
-import vsCode from './shaders/proceduralDisks/vertex.wesl?static';
-import fsCode from './shaders/proceduralDisks/fragment.wesl?static';
-import type { ProceduralDiskInstance } from '../../@types/ProceduralDiskInstance';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import vsCode from '../shaders/proceduralDisks/vertex.wesl?static';
+import fsCode from '../shaders/proceduralDisks/fragment.wesl?static';
+import type { ProceduralDiskInstance } from '../../../@types/ProceduralDiskInstance';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 const STRIDE_FLOATS = 12; // 3 vec4<f32> per instance
 const STRIDE_BYTES = STRIDE_FLOATS * 4;

src/services/gpu/quadRenderer.ts → src/services/gpu/renderers/quadRenderer.ts

@@ -14,10 +14,10 @@
  */
 
 import type { mat4 } from 'gl-matrix';
-import type { GpuContext, QuadInstance } from '../../@types';
-import vsCode from './shaders/quads/vertex.wesl?static';
-import fsCode from './shaders/quads/fragment.wesl?static';
-import { createShaderModuleWithDevLog } from './shaderCompileLogger';
+import type { GpuContext, QuadInstance } from '../../../@types';
+import vsCode from '../shaders/quads/vertex.wesl?static';
+import fsCode from '../shaders/quads/fragment.wesl?static';
+import { createShaderModuleWithDevLog } from '../shaderCompileLogger';
 
 /**
  * Per-instance vertex attributes packed as 12 floats / 48 bytes:

src/services/gpu/shaders/filaments/fragment.wesl

@@ -39,7 +39,7 @@ import package::lib::masks::edgeBandMask;
 
 @group(0) @binding(0) var<uniform> u : Uniforms;
 
-// Per-cloud fade-in (CloudFade — see src/services/gpu/cloudFade.ts).
+// Per-cloud fade-in (CloudFade — see src/services/gpu/resources/cloudFade.ts).
 // 'CloudUniforms' is imported from 'lib/cloudFade.wesl' (shared with
 // points.wesl). The CPU-side 'CloudFade' class produces the same
 // 16-byte layout for every consumer, so the shared shader struct is

src/services/gpu/shaders/lib/cloudFade.wesl

@@ -4,12 +4,12 @@
 // skeleton, future overlays) has a tiny 16-byte uniform buffer at
 // '@group(1) @binding(0)' carrying the smoothstep-shaped fade-in
 // opacity. The CPU side that owns the buffer + bind group + per-frame
-// 'writeBuffer' lives in 'src/services/gpu/cloudFade.ts'; this lib is
+// 'writeBuffer' lives in 'src/services/gpu/resources/cloudFade.ts'; this lib is
 // the GPU half of the same contract.
 //
 // ## Why a SHARED struct
 //
-// The CPU-side 'CloudFade' class (services/gpu/cloudFade.ts) emits a
+// The CPU-side 'CloudFade' class (services/gpu/resources/cloudFade.ts) emits a
 // SINGLE 16-byte layout — 'opacity: f32 + sourceCode: u32 + 8 bytes pad'
 // — for every consumer. Both the points renderer and the filaments
 // renderer bind buffers built by the same class, and the bytes are
@@ -64,7 +64,7 @@ struct CloudUniforms {
   // stage to compose '(sourceCode << 27u) | instance_index' for the
   // selection-halo + pick-output paths. Filaments doesn't read this
   // slot today, but the CPU producer ('CloudFade.writeFrame' in
-  // services/gpu/cloudFade.ts) writes it for every cloud regardless,
+  // services/gpu/resources/cloudFade.ts) writes it for every cloud regardless,
   // so the byte is already there for a future filament feature to
   // opt into.
   sourceCode: u32,

src/utils/network/galaxyImageFetcher.ts

@@ -24,7 +24,7 @@
  */
 
 import { sdssThumbnailUrl, dssThumbnailUrl } from '../math';
-import { SLOT_SIDE } from '../../services/gpu/textureAtlas';
+import { SLOT_SIDE } from '../../services/gpu/resources/textureAtlas';
 
 export type FetchGalaxyBitmapInput = {
   ra: number;

tests/services/engine/interaction/clickHandler.test.ts

@@ -24,7 +24,7 @@ import {
 } from '../../../../src/services/engine/interaction/clickHandler';
 import { Source } from '../../../../src/data/sources';
 import type { PointCloud, PointInfo } from '../../../../src/@types';
-import type { createPickRenderer } from '../../../../src/services/gpu/pickRenderer';
+import type { createPickRenderer } from '../../../../src/services/gpu/renderers/pickRenderer';
 
 type PickRenderer = ReturnType<typeof createPickRenderer>;
 

tests/services/gpu/fontMetrics.test.ts → tests/services/gpu/labels/fontMetrics.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseFontMetrics, lookupGlyph, type FontMetrics } from '../../../src/services/gpu/fontMetrics';
+import { parseFontMetrics, lookupGlyph, type FontMetrics } from '../../../../src/services/gpu/labels/fontMetrics';
 
 const FIXTURE = {
   pages: ['jetbrains-mono.png'],

tests/services/gpu/labelLayout.test.ts → tests/services/gpu/labels/labelLayout.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { layoutLabel, type GlyphQuad } from '../../../src/services/gpu/labelLayout';
-import { parseFontMetrics } from '../../../src/services/gpu/fontMetrics';
+import { layoutLabel, type GlyphQuad } from '../../../../src/services/gpu/labels/labelLayout';
+import { parseFontMetrics } from '../../../../src/services/gpu/labels/fontMetrics';
 
 const FIXTURE = {
   pages: ['atlas.png'],

tests/services/gpu/youAreHereVisibility.test.ts → tests/services/gpu/labels/youAreHereVisibility.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { youAreHereAlpha, YOU_ARE_HERE_NEAR_MPC, YOU_ARE_HERE_FAR_MPC } from '../../../src/services/gpu/youAreHereVisibility';
+import { youAreHereAlpha, YOU_ARE_HERE_NEAR_MPC, YOU_ARE_HERE_FAR_MPC } from '../../../../src/services/gpu/labels/youAreHereVisibility';
 
 describe('youAreHereAlpha', () => {
   it('is 1.0 when camera is closer than NEAR threshold', () => {