@gridspace/raster-path 1.0.4 → 1.0.6

package/src/core/raster-tool.js

@@ -0,0 +1,104 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Raster Tool - Sparse Tool Representation
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Utilities for creating sparse tool representations from rasterized tool data.
+ * Converts dense grid data into compact offset-based format for GPU toolpath
+ * generation.
+ *
+ * EXPORTS:
+ * ────────
+ * Functions:
+ *   - createSparseToolFromPoints(points) - Convert tool points to sparse format
+ *
+ * DATA FORMATS:
+ * ─────────────
+ * Input (Dense Grid):
+ *   - Float32Array of [gridX, gridY, Z, gridX, gridY, Z, ...]
+ *   - gridX, gridY are integer grid indices (not world coordinates)
+ *   - Z is height in world units (mm)
+ *
+ * Output (Sparse Tool):
+ *   {
+ *     count: number,           // Number of tool points
+ *     xOffsets: Int32Array,    // X offset from tool center (grid cells)
+ *     yOffsets: Int32Array,    // Y offset from tool center (grid cells)
+ *     zValues: Float32Array,   // Z height (mm)
+ *     referenceZ: number       // Tool tip Z (lowest point)
+ *   }
+ *
+ * ALGORITHM:
+ * ──────────
+ * 1. Find bounding box in grid space (integer coordinates)
+ * 2. Calculate tool center (grid coordinates)
+ * 3. Convert each point to offset from center
+ * 4. Store as parallel arrays for GPU consumption
+ *
+ * This sparse representation reduces memory usage and improves GPU cache
+ * coherency during toolpath generation, as the tool can be "stamped" at
+ * each position using simple offset arithmetic.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+// Create sparse tool representation from rasterized points
+// Points come from GPU as [gridX, gridY, Z] - pure integer grid coordinates for X/Y
+export function createSparseToolFromPoints(points) {
+    if (!points || points.length === 0) {
+        throw new Error('No tool points provided');
+    }
+
+    // Points are [gridX, gridY, Z] where gridX/gridY are grid indices (floats but integer values)
+    // Find bounds in grid space and tool tip Z
+    let minGridX = Infinity, minGridY = Infinity, minZ = Infinity;
+    let maxGridX = -Infinity, maxGridY = -Infinity;
+
+    for (let i = 0; i < points.length; i += 3) {
+        const gridX = points[i];      // Already a grid index
+        const gridY = points[i + 1];  // Already a grid index
+        const z = points[i + 2];
+
+        minGridX = Math.min(minGridX, gridX);
+        maxGridX = Math.max(maxGridX, gridX);
+        minGridY = Math.min(minGridY, gridY);
+        maxGridY = Math.max(maxGridY, gridY);
+        minZ = Math.min(minZ, z);
+    }
+
+    // Calculate tool center in grid coordinates (pure integer)
+    const width = Math.floor(maxGridX - minGridX) + 1;
+    const height = Math.floor(maxGridY - minGridY) + 1;
+    const centerX = Math.floor(minGridX) + Math.floor(width / 2);
+    const centerY = Math.floor(minGridY) + Math.floor(height / 2);
+
+    // Convert each point to offset from center (integer arithmetic only)
+    const xOffsets = [];
+    const yOffsets = [];
+    const zValues = [];
+
+    for (let i = 0; i < points.length; i += 3) {
+        const gridX = Math.floor(points[i]);      // Grid index (ensure integer)
+        const gridY = Math.floor(points[i + 1]);  // Grid index (ensure integer)
+        const z = points[i + 2];
+
+        // Calculate offset from tool center (pure integer arithmetic)
+        const xOffset = gridX - centerX;
+        const yOffset = gridY - centerY;
+        // Z relative to tool tip: tip=0, points above tip are positive
+        // minZ is the lowest Z (tip), so z - minZ gives positive offsets upward
+        const zValue = z;// - minZ;
+
+        xOffsets.push(xOffset);
+        yOffsets.push(yOffset);
+        zValues.push(zValue);
+    }
+
+    return {
+        count: xOffsets.length,
+        xOffsets: new Int32Array(xOffsets),
+        yOffsets: new Int32Array(yOffsets),
+        zValues: new Float32Array(zValues),
+        referenceZ: minZ
+    };
+}

package/src/core/raster-worker.js

@@ -0,0 +1,152 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * WebGPU Worker - GPU Compute Operations
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Offloads all WebGPU compute operations to a worker thread to prevent UI blocking.
+ * Handles both planar (XY grid) and radial (cylindrical) rasterization modes.
+ *
+ * MESSAGE PROTOCOL:
+ * ─────────────────
+ * Main Thread → Worker:
+ *   'init'                     - Initialize WebGPU device
+ *   'rasterize-planar'         - Rasterize geometry to XY grid
+ *   'generate-toolpath-planar' - Generate planar toolpath from rasters
+ *   'radial-generate-toolpaths'- Generate radial toolpaths (does rasterization + toolpath)
+ *   'calibrate'                - Run GPU workload calibration
+ *
+ * Worker → Main Thread:
+ *   'webgpu-ready'            - Initialization complete
+ *   'rasterize-complete'      - Planar rasterization complete
+ *   'rasterize-progress'      - Progress update (0-1)
+ *   'toolpath-complete'       - Planar toolpath complete
+ *   'toolpath-progress'       - Progress update (0-1)
+ *   'radial-toolpaths-complete' - Radial toolpaths complete
+ *   'calibrate-complete'      - Calibration results
+ *
+ * ARCHITECTURE:
+ * ─────────────
+ * 1. PLANAR MODE:
+ *    - Rasterize terrain: XY grid, keep max Z per cell
+ *    - Rasterize tool: XY grid, keep min Z per cell
+ *    - Generate toolpath: Scan tool over terrain, compute Z-heights
+ *
+ * 2. RADIAL MODE:
+ *    - Batched processing: 360 angles per batch
+ *    - X-bucketing: Spatial partitioning to reduce triangle tests
+ *    - For each angle:
+ *        * Cast ray from origin
+ *        * Rasterize terrain triangles along ray
+ *        * Calculate tool-terrain collision
+ *        * Output Z-heights along X-axis
+ *
+ * MEMORY MANAGEMENT:
+ * ──────────────────
+ * - All GPU buffers are preallocated to known maximum sizes
+ * - Triangle data transferred once per operation
+ * - Output buffers mapped asynchronously to avoid blocking
+ * - Worker maintains pipeline cache to avoid recompilation
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+import { initWebGPU, setConfig, updateConfig, deviceCapabilities, debug, device } from './raster-config.js';
+import { rasterizeMesh } from './raster-planar.js';
+import { generateToolpath } from './path-planar.js';
+import { generateRadialToolpaths } from './path-radial.js';
+import { calibrateGPU } from './workload-calibrate.js';
+
+// Global error handler for uncaught errors in worker
+self.addEventListener('error', (event) => {
+    debug.error('Uncaught error:', event.error || event.message);
+    debug.error('Stack:', event.error?.stack);
+});
+
+self.addEventListener('unhandledrejection', (event) => {
+    debug.error('Unhandled promise rejection:', event.reason);
+});
+
+// Handle messages from main thread
+self.onmessage = async function(e) {
+    const { type, data } = e.data;
+
+    try {
+        switch (type) {
+            case 'init':
+                // Store config
+                setConfig(data?.config || {
+                    maxGPUMemoryMB: 256,
+                    gpuMemorySafetyMargin: 0.8,
+                    tileOverlapMM: 10,
+                    autoTiling: true,
+                    batchDivisor: 1,  // For testing batching overhead: 1=optimal, 2=2x batches, 4=4x batches, etc.
+                    maxConcurrentThreads: 32768  // GPU watchdog limit: max threads across all workgroups in a dispatch
+                });
+                const success = await initWebGPU();
+                self.postMessage({
+                    type: 'webgpu-ready',
+                    data: {
+                        success,
+                        capabilities: deviceCapabilities
+                    }
+                });
+                break;
+
+            case 'update-config':
+                updateConfig(data.config);
+                debug.log('Config updated');
+                break;
+
+            case 'rasterize':
+                const { triangles, stepSize, filterMode, boundsOverride } = data;
+                const rasterOptions = boundsOverride || {};
+                const rasterResult = await rasterizeMesh(triangles, stepSize, filterMode, rasterOptions);
+                self.postMessage({
+                    type: 'rasterize-complete',
+                    data: rasterResult,
+                }, [rasterResult.positions.buffer]);
+                break;
+
+            case 'generate-toolpath':
+                const { terrainPositions, toolPositions, xStep, yStep, zFloor, gridStep, terrainBounds, singleScanline } = data;
+                const toolpathResult = await generateToolpath(
+                    terrainPositions, toolPositions, xStep, yStep, zFloor, gridStep, terrainBounds, singleScanline
+                );
+                self.postMessage({
+                    type: 'toolpath-complete',
+                    data: toolpathResult
+                }, [toolpathResult.pathData.buffer]);
+                break;
+
+            case 'radial-generate-toolpaths':
+                const radialToolpathResult = await generateRadialToolpaths(data);
+                const toolpathTransferBuffers = radialToolpathResult.strips.map(strip => strip.pathData.buffer);
+                self.postMessage({
+                    type: 'radial-toolpaths-complete',
+                    data: radialToolpathResult
+                }, toolpathTransferBuffers);
+                break;
+
+            case 'calibrate':
+                const calibrationResult = await calibrateGPU(device, data?.options || {});
+                self.postMessage({
+                    type: 'calibrate-complete',
+                    data: calibrationResult
+                });
+                break;
+
+            default:
+                self.postMessage({
+                    type: 'error',
+                    message: 'Unknown message type: ' + type
+                });
+        }
+    } catch (error) {
+        debug.error('Error:', error);
+        self.postMessage({
+            type: 'error',
+            message: error.message,
+            stack: error.stack
+        });
+    }
+};

package/src/core/workload-calibrate.js

@@ -0,0 +1,416 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Workload Calibrate - GPU Watchdog Limit Detection
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Calibrates GPU capabilities by testing workgroup configurations until
+ * watchdog kills are detected. Uses actual ray-triangle intersection code
+ * to simulate real workload characteristics.
+ *
+ * EXPORTS:
+ * ────────
+ * Functions:
+ *   - calibrateGPU(device, options) - Run calibration and return limits
+ *
+ * DETECTION STRATEGY:
+ * ───────────────────
+ * Problem: Watchdog kills are SILENT - threads just stop executing
+ * Solution: Initialize output buffer to zeros, each thread writes 1 on completion
+ * Detection: Any zeros remaining = that thread was killed by watchdog
+ *
+ * TEST PARAMETERS:
+ * ────────────────
+ * 1. Workgroup dimensions (x, y, z)
+ *    - Start: 16x16x1 (256 threads)
+ *    - Increase: 32x32x1, 64x64x1, etc.
+ *
+ * 2. Work intensity (triangle_tests)
+ *    - Start: 1000 intersection tests per thread
+ *    - Increase: 2000, 5000, 10000, etc.
+ *
+ * BINARY SEARCH:
+ * ──────────────
+ * For each workgroup size:
+ *   1. Start with low work intensity (known to pass)
+ *   2. Binary search for max intensity before watchdog kill
+ *   3. Record (workgroup_size, max_intensity) pair
+ *
+ * OUTPUT:
+ * ───────
+ * {
+ *   maxWorkgroupSize: { x: 64, y: 64, z: 1 },    // Largest safe config
+ *   maxWorkPerThread: 50000,                      // Max intersection tests
+ *   safeWorkloadMatrix: [                         // Safe configs tested
+ *     { workgroupSize: [16,16,1], maxWork: 100000, timingMs: 45 },
+ *     { workgroupSize: [32,32,1], maxWork: 50000, timingMs: 123 },
+ *     ...
+ *   ],
+ *   deviceInfo: {
+ *     maxComputeWorkgroupSizeX: 256,
+ *     maxComputeWorkgroupsPerDimension: 65535,
+ *     ...
+ *   }
+ * }
+ *
+ * USAGE:
+ * ──────
+ * const limits = await calibrateGPU(device, {
+ *   minWorkgroupSize: [8, 8, 1],
+ *   maxWorkgroupSize: [64, 64, 1],
+ *   minWork: 1000,
+ *   maxWork: 100000,
+ * });
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+const calibrateShaderCode = 'SHADER:workload-calibrate';
+
+// Test multiple workgroup dispatches (simulates real-world usage)
+async function testWorkloadDispatch(device, pipeline, workgroupSize, triangleTests, dispatchCount) {
+    const [x, y, z] = workgroupSize;
+    const threadsPerWorkgroup = x * y * z;
+    const totalThreads = threadsPerWorkgroup * dispatchCount;
+
+    // Create completion flags buffer for ALL workgroups
+    const completionBuffer = device.createBuffer({
+        size: totalThreads * 4,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+    });
+
+    // Initialize to zeros
+    const zeroData = new Uint32Array(totalThreads);
+    device.queue.writeBuffer(completionBuffer, 0, zeroData);
+
+    // Create uniforms
+    const uniformData = new Uint32Array([x, y, z, triangleTests]);
+    const uniformBuffer = device.createBuffer({
+        size: uniformData.byteLength,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(uniformBuffer, 0, uniformData);
+
+    await device.queue.onSubmittedWorkDone();
+
+    // Create bind group
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: completionBuffer } },
+            { binding: 1, resource: { buffer: uniformBuffer } },
+        ],
+    });
+
+    // Dispatch multiple workgroups
+    const startTime = performance.now();
+    const commandEncoder = device.createCommandEncoder();
+    const passEncoder = commandEncoder.beginComputePass();
+    passEncoder.setPipeline(pipeline);
+    passEncoder.setBindGroup(0, bindGroup);
+
+    // Dispatch NxN workgroups (e.g., 10×10 = 100 workgroups)
+    const dispatchX = Math.ceil(Math.sqrt(dispatchCount));
+    const dispatchY = Math.ceil(dispatchCount / dispatchX);
+    passEncoder.dispatchWorkgroups(dispatchX, dispatchY, 1);
+    passEncoder.end();
+
+    // Readback
+    const stagingBuffer = device.createBuffer({
+        size: totalThreads * 4,
+        usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+    });
+
+    commandEncoder.copyBufferToBuffer(completionBuffer, 0, stagingBuffer, 0, totalThreads * 4);
+    device.queue.submit([commandEncoder.finish()]);
+
+    await device.queue.onSubmittedWorkDone();
+    const elapsed = performance.now() - startTime;
+
+    await stagingBuffer.mapAsync(GPUMapMode.READ);
+    const completionData = new Uint32Array(stagingBuffer.getMappedRange());
+    const completionCopy = new Uint32Array(completionData);
+    stagingBuffer.unmap();
+
+    // Check for failures
+    let failedThreads = 0;
+    for (let i = 0; i < totalThreads; i++) {
+        if (completionCopy[i] === 0) {
+            failedThreads++;
+        }
+    }
+
+    // Cleanup
+    completionBuffer.destroy();
+    uniformBuffer.destroy();
+    stagingBuffer.destroy();
+
+    return {
+        success: failedThreads === 0,
+        failedThreads,
+        totalThreads,
+        dispatchCount,
+        elapsed,
+    };
+}
+
+// Test a specific workload configuration (single workgroup)
+async function testWorkload(device, pipeline, workgroupSize, triangleTests) {
+    const [x, y, z] = workgroupSize;
+    const totalThreads = x * y * z;
+
+    // Create completion flags buffer (initialized to zeros)
+    const completionBuffer = device.createBuffer({
+        size: totalThreads * 4, // u32 per thread
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+    });
+
+    // Initialize to zeros (so we can detect threads that never completed)
+    const zeroData = new Uint32Array(totalThreads);
+    device.queue.writeBuffer(completionBuffer, 0, zeroData);
+
+    // Create uniforms
+    const uniformData = new Uint32Array([x, y, z, triangleTests]);
+    const uniformBuffer = device.createBuffer({
+        size: uniformData.byteLength,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(uniformBuffer, 0, uniformData);
+
+    // Wait for writes to complete
+    await device.queue.onSubmittedWorkDone();
+
+    // Create bind group
+    const bindGroup = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: completionBuffer } },
+            { binding: 1, resource: { buffer: uniformBuffer } },
+        ],
+    });
+
+    // Dispatch compute shader
+    const startTime = performance.now();
+    const commandEncoder = device.createCommandEncoder();
+    const passEncoder = commandEncoder.beginComputePass();
+    passEncoder.setPipeline(pipeline);
+    passEncoder.setBindGroup(0, bindGroup);
+
+    // Dispatch exactly 1 workgroup (16x16x1 = 256 threads by default)
+    // The shader itself is parameterized with the workgroup size to test
+    passEncoder.dispatchWorkgroups(1, 1, 1);
+    passEncoder.end();
+
+    // Create staging buffer for readback
+    const stagingBuffer = device.createBuffer({
+        size: totalThreads * 4,
+        usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+    });
+
+    commandEncoder.copyBufferToBuffer(completionBuffer, 0, stagingBuffer, 0, totalThreads * 4);
+    device.queue.submit([commandEncoder.finish()]);
+
+    // Wait for GPU to complete
+    await device.queue.onSubmittedWorkDone();
+    const elapsed = performance.now() - startTime;
+
+    // Read back completion flags
+    await stagingBuffer.mapAsync(GPUMapMode.READ);
+    const completionData = new Uint32Array(stagingBuffer.getMappedRange());
+    const completionCopy = new Uint32Array(completionData);
+    stagingBuffer.unmap();
+
+    // Check for failures (any zeros = thread didn't complete)
+    let failedThreads = 0;
+    for (let i = 0; i < totalThreads; i++) {
+        if (completionCopy[i] === 0) {
+            failedThreads++;
+        }
+    }
+
+    // Cleanup
+    completionBuffer.destroy();
+    uniformBuffer.destroy();
+    stagingBuffer.destroy();
+
+    return {
+        success: failedThreads === 0,
+        failedThreads,
+        totalThreads,
+        elapsed,
+    };
+}
+
+// Binary search for max work intensity at a given workgroup size
+async function findMaxWork(device, pipeline, workgroupSize, minWork, maxWork) {
+    let low = minWork;
+    let high = maxWork;
+    let lastSuccess = minWork;
+
+    while (low <= high) {
+        const mid = Math.floor((low + high) / 2);
+        const result = await testWorkload(device, pipeline, workgroupSize, mid);
+
+        if (result.success) {
+            lastSuccess = mid;
+            low = mid + 1;
+        } else {
+            high = mid - 1;
+        }
+    }
+
+    return lastSuccess;
+}
+
+// Calibrate dispatch count limits (how many workgroups can be queued)
+export async function calibrateDispatchLimits(device, options = {}) {
+    const {
+        workgroupSize = [16, 16, 1],  // Use known-good size
+        triangleTests = 10000,         // Moderate work per thread
+        minDispatch = 1,
+        maxDispatch = 100000,          // Test up to 100k workgroups
+        verbose = true,
+    } = options;
+
+    const shaderModule = device.createShaderModule({ code: calibrateShaderCode });
+    const pipeline = device.createComputePipeline({
+        layout: 'auto',
+        compute: { module: shaderModule, entryPoint: 'main' },
+    });
+
+    if (verbose) {
+        console.log('[Calibrate] Testing dispatch count limits...');
+        console.log(`[Calibrate] Workgroup size: ${workgroupSize.join('x')}, work: ${triangleTests} tests/thread`);
+    }
+
+    // Binary search for max dispatch count
+    let low = minDispatch;
+    let high = maxDispatch;
+    let lastSuccess = minDispatch;
+    const results = [];
+
+    while (low <= high) {
+        const mid = Math.floor((low + high) / 2);
+
+        if (verbose) {
+            console.log(`[Calibrate] Testing ${mid} workgroups...`);
+        }
+
+        const result = await testWorkloadDispatch(device, pipeline, workgroupSize, triangleTests, mid);
+        results.push({ ...result, dispatchCount: mid });
+
+        if (result.success) {
+            lastSuccess = mid;
+            if (verbose) {
+                const totalThreads = result.totalThreads.toLocaleString();
+                const totalWork = (result.totalThreads * triangleTests).toLocaleString();
+                console.log(`[Calibrate]   ✓ ${mid} workgroups OK (${totalThreads} threads, ${totalWork} total tests) in ${result.elapsed.toFixed(1)}ms`);
+            }
+            low = mid + 1;
+        } else {
+            if (verbose) {
+                console.log(`[Calibrate]   ❌ ${mid} workgroups FAILED (${result.failedThreads}/${result.totalThreads} threads killed)`);
+            }
+            high = mid - 1;
+        }
+    }
+
+    if (verbose) {
+        console.log(`[Calibrate] Max safe dispatch count: ${lastSuccess} workgroups`);
+    }
+
+    return {
+        maxSafeDispatchCount: lastSuccess,
+        workgroupSize,
+        triangleTests,
+        results,
+    };
+}
+
+// Main calibration function
+export async function calibrateGPU(device, options = {}) {
+    const {
+        workgroupSizes = [
+            [8, 8, 1],
+            [16, 16, 1],
+            [32, 32, 1],
+            [64, 64, 1],
+        ],
+        minWork = 1000,
+        maxWork = 100000,
+        verbose = true,
+    } = options;
+
+    // Compile calibration shader
+    const shaderModule = device.createShaderModule({ code: calibrateShaderCode });
+    const pipeline = device.createComputePipeline({
+        layout: 'auto',
+        compute: { module: shaderModule, entryPoint: 'main' },
+    });
+
+    const results = [];
+
+    if (verbose) {
+        console.log('[Calibrate] Starting GPU calibration...');
+        console.log('[Calibrate] Testing workgroup sizes:', workgroupSizes);
+    }
+
+    for (const size of workgroupSizes) {
+        const [x, y, z] = size;
+        const totalThreads = x * y * z;
+
+        if (verbose) {
+            console.log(`[Calibrate] Testing ${x}x${y}x${z} (${totalThreads} threads)...`);
+        }
+
+        // First, verify minimal work succeeds
+        const minTest = await testWorkload(device, pipeline, size, minWork);
+        if (!minTest.success) {
+            if (verbose) {
+                console.log(`[Calibrate]   ❌ Failed even at minimum work (${minWork} tests)`);
+            }
+            break; // This workgroup size is too large
+        }
+
+        // Binary search for maximum work
+        const maxWorkFound = await findMaxWork(device, pipeline, size, minWork, maxWork);
+        const finalTest = await testWorkload(device, pipeline, size, maxWorkFound);
+
+        results.push({
+            workgroupSize: size,
+            totalThreads,
+            maxWork: maxWorkFound,
+            timingMs: finalTest.elapsed,
+            msPerThread: finalTest.elapsed / totalThreads,
+            testsPerSecond: (maxWorkFound * totalThreads) / (finalTest.elapsed / 1000),
+        });
+
+        if (verbose) {
+            console.log(`[Calibrate]   ✓ Max work: ${maxWorkFound} tests (${finalTest.elapsed.toFixed(1)}ms)`);
+            console.log(`[Calibrate]     ${(maxWorkFound * totalThreads).toLocaleString()} total ray-triangle tests`);
+        }
+    }
+
+    // Determine overall limits
+    const maxWorkgroupResult = results[results.length - 1];
+    const minWorkPerThread = Math.min(...results.map(r => r.maxWork));
+
+    const calibration = {
+        maxWorkgroupSize: maxWorkgroupResult.workgroupSize,
+        maxWorkPerThread: minWorkPerThread, // Conservative: min across all sizes
+        safeWorkloadMatrix: results,
+        deviceInfo: {
+            maxComputeWorkgroupSizeX: device.limits.maxComputeWorkgroupSizeX,
+            maxComputeWorkgroupSizeY: device.limits.maxComputeWorkgroupSizeY,
+            maxComputeWorkgroupSizeZ: device.limits.maxComputeWorkgroupSizeZ,
+            maxComputeWorkgroupsPerDimension: device.limits.maxComputeWorkgroupsPerDimension,
+        },
+    };
+
+    if (verbose) {
+        console.log('[Calibrate] Calibration complete:');
+        console.log(`[Calibrate]   Max safe workgroup: ${maxWorkgroupResult.workgroupSize.join('x')}`);
+        console.log(`[Calibrate]   Max work per thread: ${minWorkPerThread.toLocaleString()}`);
+    }
+
+    return calibration;
+}