@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/modules/native-osr/src/native-osr-manager.js

@@ -0,0 +1,210 @@
+// ============================================================================
+// NativeOSRManager — Renderer-side coordinator for Blitz-backed OSR
+//
+// Coordinates panel renderers (createRenderer, addElement, render,
+// handleInput, focusBillboard, …). Textures come from in-process `pullFrame`
+// + writeTexture, and the host object is the native bridge's osr sub-API.
+// ============================================================================
+import { OSRInputRouter } from "./input-router.js";
+import { NativeOsrTextureSource } from "./native-texture-source.js";
+import { WorldSpaceUIPass } from "./world-space-ui-pass.js";
+export class NativeOSRManager {
+    device;
+    host = null;
+    sources = new Map();
+    renderPass;
+    inputRouter = null;
+    elements = new Map();
+    rendererIds = [];
+    rendererStatuses = new Map();
+    atlasLayouts = new Map();
+    errorTextureIndices = new Set();
+    cursorStyle = "default";
+    onCursorStyleCb = null;
+    constructor(device, surfaceFormat = "bgra8unorm", depthFormat = "depth24plus") {
+        this.device = device;
+        this.renderPass = new WorldSpaceUIPass(device, surfaceFormat, depthFormat);
+    }
+    init(host) {
+        this.host = host;
+        this.renderPass.prepare();
+        host.onPanelLayout((rendererId, layout) => {
+            this.atlasLayouts.set(rendererId, layout);
+            this.updateInputRouterConfig();
+        });
+        host.onRendererEvent((event) => {
+            this.rendererStatuses.set(event.rendererId, event.status);
+            const texIdx = this.rendererIds.indexOf(event.rendererId);
+            if (texIdx >= 0) {
+                if (event.status === "failed")
+                    this.errorTextureIndices.add(texIdx);
+                else if (event.status === "running")
+                    this.errorTextureIndices.delete(texIdx);
+            }
+            this.updateInputRouterConfig();
+        });
+        if (typeof host.onCursorStyle === "function") {
+            host.onCursorStyle((_id, cursor) => {
+                if (this.cursorStyle !== cursor) {
+                    this.cursorStyle = cursor;
+                    this.onCursorStyleCb?.(cursor);
+                }
+            });
+        }
+    }
+    createRenderer(config) {
+        if (!this.host)
+            return;
+        this.sources.set(config.id, new NativeOsrTextureSource(this.device, config.id, config.width, config.height, config.pixelFormat ?? "rgba"));
+        this.rendererIds.push(config.id);
+        this.rendererStatuses.set(config.id, "running");
+        this.updateTextureBindings();
+        this.updateInputRouterConfig();
+        void this.host.createRenderer(config);
+    }
+    destroyRenderer(id) {
+        if (!this.host)
+            return;
+        const texIdx = this.rendererIds.indexOf(id);
+        this.sources.get(id)?.destroy();
+        this.sources.delete(id);
+        this.rendererIds = this.rendererIds.filter((r) => r !== id);
+        this.rendererStatuses.delete(id);
+        this.atlasLayouts.delete(id);
+        this.errorTextureIndices.delete(texIdx);
+        for (const [elId, el] of this.elements.entries()) {
+            if (el.textureIndex === texIdx)
+                this.elements.delete(elId);
+        }
+        this.updateTextureBindings();
+        this.updateInputRouterConfig();
+        void this.host.destroyRenderer(id);
+    }
+    addPanel(config) {
+        void this.host?.addPanel(config);
+    }
+    removePanel(rendererId, panelId) {
+        void this.host?.removePanel(rendererId, panelId);
+    }
+    updatePanel(rendererId, panelId, html) {
+        void this.host?.updatePanel(rendererId, panelId, html);
+    }
+    updateData(rendererId, panelId, values) {
+        this.host?.updateData(rendererId, panelId, values);
+    }
+    setContent(rendererId, html) {
+        void this.host?.setContent(rendererId, html);
+    }
+    addElement(element) {
+        this.elements.set(element.id, element);
+    }
+    removeElement(id) {
+        this.elements.delete(id);
+    }
+    updateElements(elements) {
+        this.elements.clear();
+        elements.forEach((el) => { this.elements.set(el.id, el); ; });
+    }
+    /** Pull dirty frames from the host and upload — call once per frame before
+     *  render(). Cheap when clean (the cdylib returns null without rasterizing). */
+    update() {
+        if (!this.host)
+            return;
+        for (const source of this.sources.values()) {
+            source.update(this.host);
+        }
+    }
+    render(camera, passEncoder) {
+        if (this.elements.size === 0)
+            return;
+        this.update();
+        const texList = this.getTextureList();
+        if (texList.length === 0)
+            return;
+        this.renderPass.updateCamera(camera);
+        this.renderPass.setTextures(texList.map((t) => ({ textureView: t.textureView })));
+        this.renderPass.execute(passEncoder, Array.from(this.elements.values()), this.errorTextureIndices);
+    }
+    handleInput(camera, mouseState) {
+        this.inputRouter?.handleMouse(camera, mouseState, Array.from(this.elements.values()));
+    }
+    handleKey(type, keyCode, modifiers) {
+        this.inputRouter?.handleKey(type, keyCode, modifiers);
+    }
+    focusBillboard(canvasWidth, canvasHeight) {
+        const id = this.inputRouter?.focusBillboard() ?? null;
+        if (id && canvasWidth && canvasHeight) {
+            this.inputRouter?.setForcedFocusCanvasSize(canvasWidth, canvasHeight);
+        }
+        return id;
+    }
+    unfocusBillboard() {
+        this.inputRouter?.unfocusBillboard();
+    }
+    isForcedFocus() {
+        return this.inputRouter?.isForcedFocus() ?? false;
+    }
+    isHoveringBillboard() {
+        return this.inputRouter?.isHoveringBillboard() ?? false;
+    }
+    getCursorStyle() {
+        return this.cursorStyle;
+    }
+    onCursorStyleChange(cb) {
+        this.onCursorStyleCb = cb;
+    }
+    setSoftwareCursorEnabled(enabled) {
+        if (!this.host || typeof this.host.setSoftwareCursor !== "function")
+            return;
+        for (let _i7044 = 0, _it7044 = this.rendererIds, _n7044 = _it7044.length; _i7044 < _n7044; _i7044++) {
+            const id = _it7044[_i7044];
+            this.host.setSoftwareCursor(id, enabled);
+            ;
+        }
+        ;
+    }
+    destroy() {
+        this.renderPass.destroy();
+        for (const s of this.sources.values())
+            s.destroy();
+        this.sources.clear();
+        this.elements.clear();
+        this.rendererIds = [];
+        this.rendererStatuses.clear();
+        this.atlasLayouts.clear();
+    }
+    getTextureList() {
+        const list = [];
+        for (const [id, s] of this.sources.entries())
+            list.push({ rendererId: id, textureView: s.getTextureView() });
+        return list;
+    }
+    updateTextureBindings() {
+        this.renderPass.setTextures(this.getTextureList().map((t) => ({ textureView: t.textureView })));
+    }
+    updateInputRouterConfig() {
+        const textureIndexToRendererId = new Map();
+        for (let i = 0; i < this.rendererIds.length; i++)
+            textureIndexToRendererId.set(i, this.rendererIds[i]);
+        const rendererDimensions = new Map();
+        this.rendererIds.forEach((id) => {
+            const s = this.sources.get(id);
+            if (s)
+                rendererDimensions.set(id, { width: s.width, height: s.height });
+        });
+        const config = {
+            textureIndexToRendererId,
+            atlasLayouts: this.atlasLayouts,
+            rendererStatuses: this.rendererStatuses,
+            rendererDimensions,
+        };
+        if (!this.inputRouter && this.host) {
+            this.inputRouter = new OSRInputRouter(config, (rendererId, event) => {
+                this.host?.sendInputEvent(rendererId, event);
+            });
+        }
+        else {
+            this.inputRouter?.updateConfig(config);
+        }
+    }
+}

package/dist/modules/native-osr/src/native-texture-source.js

@@ -0,0 +1,66 @@
+// ============================================================================
+// NativeOsrTextureSource — GPUTexture sink for one Blitz OSR renderer
+//
+// In-process pull pipeline: the bridge's `pullFrame`
+// hands back a dirty RGBA8 buffer which is uploaded via queue.writeTexture.
+// When the source also exposes `frameRect` only the changed region is copied
+// and uploaded.
+// ============================================================================
+export class NativeOsrTextureSource {
+    rendererId;
+    width;
+    height;
+    device;
+    texture;
+    view;
+    /** Reusable staging buffer for unaligned-strided partial uploads. */
+    scratch = new Uint8Array(0);
+    constructor(device, rendererId, width, height, _pixelFormat) {
+        this.device = device;
+        this.rendererId = rendererId;
+        this.width = width;
+        this.height = height;
+        // Blitz rasterizes RGBA8; the pixelFormat flag is ignored — wgpu
+        // textures are always rgba8unorm here (no bgra swapchain semantics).
+        this.texture = device.createTexture({
+            size: { width, height },
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.view = this.texture.createView();
+    }
+    getTextureView() {
+        return this.view;
+    }
+    /** Pull + upload a dirty frame. Returns true when new pixels were written. */
+    update(source) {
+        const pixels = source.pullFrame(this.rendererId);
+        if (!pixels || pixels.length === 0)
+            return false;
+        if (pixels.length !== this.width * this.height * 4)
+            return false;
+        const rect = source.frameRect?.(this.rendererId)
+            ?? { x: 0, y: 0, w: this.width, h: this.height };
+        const rowBytes = this.width * 4;
+        if (rowBytes % 256 === 0) {
+            // Frame rows already satisfy wgpu's 256-byte stride — upload the dirty
+            // region straight out of the source buffer, no copies.
+            this.device.queue.writeTexture({ texture: this.texture, origin: [rect.x, rect.y, 0] }, pixels, { offset: (rect.y * this.width + rect.x) * 4, bytesPerRow: rowBytes, rowsPerImage: rect.h }, { width: rect.w, height: rect.h, depthOrArrayLayers: 1 });
+            return true;
+        }
+        // Unaligned stride — repack the dirty rows into a 256-aligned scratch.
+        const stride = Math.ceil(rect.w * 4 / 256) * 256;
+        const need = stride * rect.h;
+        if (this.scratch.length < need)
+            this.scratch = new Uint8Array(need);
+        for (let r = 0; r < rect.h; r++) {
+            const src = ((rect.y + r) * this.width + rect.x) * 4;
+            this.scratch.set(pixels.subarray(src, src + rect.w * 4), r * stride);
+        }
+        this.device.queue.writeTexture({ texture: this.texture, origin: [rect.x, rect.y, 0] }, this.scratch, { bytesPerRow: stride, rowsPerImage: rect.h }, { width: rect.w, height: rect.h, depthOrArrayLayers: 1 });
+        return true;
+    }
+    destroy() {
+        this.texture.destroy();
+    }
+}

package/dist/modules/native-osr/src/types.js

@@ -0,0 +1,8 @@
+// ============================================================================
+// Native OSR Module — Shared Types
+// ============================================================================
+export const BillboardMode = {
+    ScreenAligned: 0,
+    AxisAligned: 1,
+    Fixed: 2,
+};

package/dist/modules/native-osr/src/world-space-ui-pass.js

@@ -0,0 +1,313 @@
+// ============================================================================
+// World Space UI Pass — Renders OSR textures as billboarded quads in 3D space
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+const SHADER_CODE = /* wgsl */ `
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  cameraRight: vec4<f32>,
+  cameraUp: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var uiSampler: sampler;
+
+@group(1) @binding(0) var uiTexture: texture_2d<f32>;
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+  @location(1) errorFlag: f32,
+};
+
+struct InstanceInput {
+  @location(1) position: vec3<f32>,
+  @location(2) size: vec2<f32>,
+  @location(3) uvOffset: vec2<f32>,
+  @location(4) uvScale: vec2<f32>,
+  @location(5) billboardMode: f32,
+  @location(6) textureIndex: f32,
+  @location(7) errorFlag: f32,
+};
+
+@vertex
+fn vs_main(@location(0) quadUV: vec2<f32>, instance: InstanceInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.errorFlag = instance.errorFlag;
+
+  var worldOffset: vec3<f32>;
+  if (instance.billboardMode == 0.0) {
+    worldOffset = camera.cameraRight.xyz * (quadUV.x - 0.5) * instance.size.x
+                + camera.cameraUp.xyz * (quadUV.y - 0.5) * instance.size.y;
+  } else if (instance.billboardMode == 1.0) {
+    worldOffset = vec3<f32>((quadUV.x - 0.5) * instance.size.x, 0.0, 0.0)
+                + camera.cameraUp.xyz * (quadUV.y - 0.5) * instance.size.y;
+  } else {
+    worldOffset = vec3<f32>((quadUV.x - 0.5) * instance.size.x, 0.0, (quadUV.y - 0.5) * instance.size.y);
+  }
+
+  let worldPos = vec4<f32>(instance.position + worldOffset, 1.0);
+  output.clipPosition = camera.viewProj * worldPos;
+  output.uv = instance.uvOffset + vec2<f32>(quadUV.x, 1.0 - quadUV.y) * instance.uvScale;
+
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let texColor = textureSample(uiTexture, uiSampler, input.uv);
+  let errorColor = vec4<f32>(1.0, 0.0, 0.0, 0.85);
+  let result = mix(texColor, errorColor, select(0.0, 1.0, input.errorFlag > 0.5));
+  return vec4<f32>(result.rgb, 1.0);
+}
+`;
+// Instance data layout: position(3) + pad(1) + size(2) + uvOffset(2) + uvScale(2) +
+//   billboardMode(1) + textureIndex(1) + errorFlag(1) + pad(1) = 14 floats = 56 bytes
+const INSTANCE_FLOATS = 14;
+const INSTANCE_BYTES = INSTANCE_FLOATS * 4;
+// Quad vertices: 6 vertices × 2 floats (uv) = 12 floats
+// Flipped horizontally (U: 1→0) to correct mirrored rendering
+const QUAD_VERTICES = new Float32Array([
+    1, 0,
+    0, 0,
+    1, 1,
+    1, 1,
+    0, 0,
+    0, 1,
+]);
+export class WorldSpaceUIPass {
+    device;
+    surfaceFormat;
+    depthFormat;
+    shaderModule = null;
+    pipeline = null;
+    uniformBuffer = null;
+    sampler = null;
+    vertexBuffer = null;
+    instanceBuffer = null;
+    instanceCount = 0;
+    maxInstances = 256;
+    bindGroupLayout0 = null;
+    bindGroup0 = null;
+    textureBindGroups = new Map();
+    currentTextures = [];
+    constructor(device, surfaceFormat = "bgra8unorm", depthFormat = "depth24plus") {
+        this.device = device;
+        this.surfaceFormat = surfaceFormat;
+        this.depthFormat = depthFormat;
+    }
+    prepare() {
+        // Shader module
+        this.shaderModule = createValidatedShaderModule(this.device, { code: SHADER_CODE, label: "WorldSpaceUIPass" });
+        // Sampler
+        this.sampler = this.device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+        // Uniform buffer: viewProj(64) + cameraRight(16) + cameraUp(16) = 96 bytes
+        this.uniformBuffer = this.device.createBuffer({
+            size: 96,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // Vertex buffer (quad UVs)
+        this.vertexBuffer = this.device.createBuffer({
+            size: QUAD_VERTICES.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.vertexBuffer, 0, QUAD_VERTICES);
+        // Instance buffer
+        this.instanceBuffer = this.device.createBuffer({
+            size: this.maxInstances * INSTANCE_BYTES,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        // Bind group layout 0: camera uniform + sampler
+        this.bindGroupLayout0 = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+            ],
+        });
+        this.bindGroup0 = this.device.createBindGroup({
+            layout: this.bindGroupLayout0,
+            entries: [
+                { binding: 0, resource: { buffer: this.uniformBuffer } },
+                { binding: 1, resource: this.sampler },
+            ],
+        });
+        // Bind group layout 1: texture
+        const bindGroupLayout1 = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+            ],
+        });
+        // Pipeline layout
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout0, bindGroupLayout1],
+        });
+        // Render pipeline
+        this.pipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: {
+                module: this.shaderModule,
+                entryPoint: "vs_main",
+                buffers: [
+                    {
+                        // Vertex buffer — quad UVs
+                        arrayStride: 8,
+                        stepMode: "vertex",
+                        attributes: [{ shaderLocation: 0, offset: 0, format: "float32x2" }],
+                    },
+                    {
+                        // Instance buffer — per-instance data
+                        arrayStride: INSTANCE_BYTES,
+                        stepMode: "instance",
+                        attributes: [
+                            { shaderLocation: 1, offset: 0, format: "float32x3" }, // position
+                            { shaderLocation: 2, offset: 16, format: "float32x2" }, // size
+                            { shaderLocation: 3, offset: 24, format: "float32x2" }, // uvOffset
+                            { shaderLocation: 4, offset: 32, format: "float32x2" }, // uvScale
+                            { shaderLocation: 5, offset: 40, format: "float32" }, // billboardMode
+                            { shaderLocation: 6, offset: 44, format: "float32" }, // textureIndex
+                            { shaderLocation: 7, offset: 48, format: "float32" }, // errorFlag
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: this.shaderModule,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: this.surfaceFormat,
+                        blend: {
+                            color: {
+                                srcFactor: "src-alpha",
+                                dstFactor: "one-minus-src-alpha",
+                                operation: "add",
+                            },
+                            alpha: {
+                                srcFactor: "one",
+                                dstFactor: "one-minus-src-alpha",
+                                operation: "add",
+                            },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-list" },
+            depthStencil: {
+                depthWriteEnabled: false,
+                depthCompare: "less",
+                format: this.depthFormat,
+            },
+        });
+    }
+    updateInstances(elements, errorTextureIndices) {
+        if (!this.instanceBuffer)
+            return;
+        this.instanceCount = elements.length;
+        // Grow buffer if needed
+        if (this.instanceCount > this.maxInstances) {
+            this.maxInstances = Math.ceil(this.instanceCount * 1.5);
+            this.instanceBuffer.destroy();
+            this.instanceBuffer = this.device.createBuffer({
+                size: this.maxInstances * INSTANCE_BYTES,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+        }
+        const data = new Float32Array(this.instanceCount * INSTANCE_FLOATS);
+        for (let i = 0; i < this.instanceCount; i++) {
+            const el = elements[i];
+            const offset = i * INSTANCE_FLOATS;
+            data[offset + 0] = el.position[0];
+            data[offset + 1] = el.position[1];
+            data[offset + 2] = el.position[2];
+            data[offset + 3] = 0; // pad
+            data[offset + 4] = el.size[0];
+            data[offset + 5] = el.size[1];
+            data[offset + 6] = el.uvOffset[0];
+            data[offset + 7] = el.uvOffset[1];
+            data[offset + 8] = el.uvScale[0];
+            data[offset + 9] = el.uvScale[1];
+            data[offset + 10] = el.billboardMode;
+            data[offset + 11] = el.textureIndex;
+            data[offset + 12] = errorTextureIndices.has(el.textureIndex) ? 1 : 0;
+            data[offset + 13] = 0; // pad
+        }
+        this.device.queue.writeBuffer(this.instanceBuffer, 0, data);
+    }
+    updateCamera(camera) {
+        if (!this.uniformBuffer)
+            return;
+        // WGSL uniform struct layout (vec4 = 16 bytes each):
+        //   viewProj: mat4x4 at offset 0  (16 floats = 64 bytes)
+        //   cameraRight: vec4 at offset 64 (floats 16-19)
+        //   cameraUp: vec4 at offset 80   (floats 20-23)
+        const data = new Float32Array(24);
+        data.set(camera.viewProj, 0);
+        data[16] = camera.cameraRight[0];
+        data[17] = camera.cameraRight[1];
+        data[18] = camera.cameraRight[2];
+        data[19] = 0;
+        data[20] = camera.cameraUp[0];
+        data[21] = camera.cameraUp[1];
+        data[22] = camera.cameraUp[2];
+        data[23] = 0;
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, data);
+    }
+    setTextures(textures) {
+        this.currentTextures = textures;
+        this.textureBindGroups.clear();
+        if (!this.pipeline)
+            return;
+        const bindGroupLayout1 = this.pipeline.getBindGroupLayout(1);
+        for (let i = 0; i < textures.length; i++) {
+            this.textureBindGroups.set(i, this.device.createBindGroup({
+                layout: bindGroupLayout1,
+                entries: [{ binding: 0, resource: textures[i].textureView }],
+            }));
+        }
+    }
+    execute(passEncoder, elements, errorTextureIndices) {
+        if (!this.pipeline || !this.bindGroup0 || !this.vertexBuffer || !this.instanceBuffer)
+            return;
+        if (elements.length === 0)
+            return;
+        // Sort elements by textureIndex so instances are contiguous per texture group
+        const sorted = [...elements].sort((a, b) => a.textureIndex - b.textureIndex);
+        this.updateInstances(sorted, errorTextureIndices);
+        passEncoder.setPipeline(this.pipeline);
+        passEncoder.setBindGroup(0, this.bindGroup0);
+        passEncoder.setVertexBuffer(0, this.vertexBuffer);
+        passEncoder.setVertexBuffer(1, this.instanceBuffer);
+        // Group sorted instances by textureIndex — each group is contiguous
+        let firstInstance = 0;
+        let currentTexIdx = sorted[0].textureIndex;
+        let groupCount = 0;
+        for (let i = 0; i <= sorted.length; i++) {
+            const texIdx = i < sorted.length ? sorted[i].textureIndex : -1;
+            if (texIdx !== currentTexIdx) {
+                // Draw the accumulated group
+                const bg = this.textureBindGroups.get(currentTexIdx);
+                if (bg) {
+                    passEncoder.setBindGroup(1, bg);
+                    passEncoder.draw(6, groupCount, 0, firstInstance);
+                }
+                firstInstance += groupCount;
+                groupCount = 0;
+                currentTexIdx = texIdx;
+            }
+            groupCount++;
+        }
+    }
+    destroy() {
+        this.shaderModule?.destroy();
+        this.pipeline = null;
+        this.uniformBuffer?.destroy();
+        this.vertexBuffer?.destroy();
+        this.instanceBuffer?.destroy();
+        this.bindGroupLayout0 = null;
+        this.bindGroup0 = null;
+        this.textureBindGroups.clear();
+    }
+}

package/dist/modules/sailing/src/index.js

@@ -0,0 +1,39 @@
+// ============================================================================
+// @downdraft/engine/modules/sailing — sailing mechanics (wind + buoyancy + steering)
+//
+// Composes water physics (wave sampling, buoyancy) with sailing mechanics
+// (wind force, sail trim, rudder steering, hull drag). Requires the water
+// library's WaterWriterTok to sample wave heights for buoyancy.
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { WaterWriterTok } from "@downdraft/engine/libraries/water";
+export const SailingStateTok = resourceToken("sailing:state");
+export const WindStateTok = resourceToken("sailing:wind");
+export function createSailingModule(config = {}) {
+    const cfg = {
+        baseWindSpeed: config.baseWindSpeed ?? 8.0,
+        baseWindDirection: config.baseWindDirection ?? 0,
+        sailArea: config.sailArea ?? 50,
+        rudderArea: config.rudderArea ?? 10,
+        hullDragCoeff: config.hullDragCoeff ?? 0.3,
+        maxTurnRate: config.maxTurnRate ?? 0.5,
+    };
+    return {
+        name: "sailing",
+        version: "1.0.0",
+        requires: [WaterWriterTok],
+        provides: [SailingStateTok, WindStateTok],
+        register(ctx) {
+            // Inject the water writer (validated by `requires`).
+            // The water writer is used by the game's sailing system to sample
+            // wave heights for buoyancy. The plugin validates the dependency
+            // exists; the game's system reads it from the DI graph.
+            ctx.injectOptional(WaterWriterTok);
+            ctx.provide(SailingStateTok, cfg);
+            ctx.provide(WindStateTok, { speed: cfg.baseWindSpeed, direction: cfg.baseWindDirection });
+            // The actual sailing system (force calculation, rudder integration,
+            // hull drag) is game-specific and registered as an ECS system by
+            // the game. This plugin provides config + wind state via DI.
+        },
+    };
+}

package/dist/modules/terrain/src/index.js

@@ -0,0 +1,44 @@
+// ============================================================================
+// @downdraft/engine/modules/terrain — composable terrain plugin
+//
+// Composes @downdraft/engine/libraries/marching-cubes (mesh extraction + chunked voxel
+// fields) with LOD management, streaming, and deformation broadcasting into a
+// single Module with typed DI. Games register this plugin instead of manually
+// wiring TerrainSystem + TerrainLODManager + mesh worker pools.
+//
+// Provides:
+//   - TerrainStreamingTok — the terrain streaming config (LOD levels, voxel sizes)
+//
+// The actual TerrainSystem and TerrainLODManager are game-specific (they need
+// a game-provided DensityField), so games create them in onReady and inject
+// TerrainStreamingTok for the config.
+//
+// Requires:
+//   - (none — terrain is self-contained; physics integration is optional)
+// ============================================================================
+import { resourceToken, } from "@downdraft/engine";
+import { DEFAULT_STREAMING_CONFIG, } from "@downdraft/engine/libraries/marching-cubes";
+// ── Typed tokens (DI) ──
+/** Token for the terrain streaming config. Inject to read LOD/streaming config. */
+export const TerrainStreamingTok = resourceToken("terrain:streaming");
+// ── Module factory ──
+export function createTerrainModule(config = {}) {
+    const streamingConfig = {
+        ...DEFAULT_STREAMING_CONFIG,
+        ...config.streaming,
+    };
+    return {
+        name: "terrain",
+        version: "1.0.0",
+        provides: [TerrainStreamingTok],
+        register(ctx) {
+            // Provide the streaming config so other systems/plugins can read it.
+            ctx.provide(TerrainStreamingTok, streamingConfig);
+            // The actual terrain system (chunk gen, LOD, deform) and LOD manager
+            // are game-specific — they need a game-provided DensityField. Games
+            // create them in onReady and inject TerrainStreamingTok for the config.
+        },
+    };
+}
+// Re-export library types for convenience
+export { DEFAULT_STREAMING_CONFIG } from "@downdraft/engine/libraries/marching-cubes";