Adding first working version

backend/test/caEngines.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { listCaEngineRuntimes, registerCaEngineRuntime, stepCaCells } from '../admin/src/caEngines.js'
+import { listCaEngineRuntimes, registerCaEngineRuntime, stepCaCells, stepCaSimulation } from '../admin/src/caEngines.js'
 import type { Cells, SceneParams } from '../admin/src/types.js'
 
 function cells(width: number, height: number, alive: Array<[number, number]> = []): Cells {
@@ -28,6 +28,7 @@ describe('CA engine runtimes', () => {
         'outer-totalistic-2d',
         'elementary-1d',
         'wildfire-2d',
+        'naga-3d',
         'generic-voxel-ca',
         'noop'
       ])
@@ -140,6 +141,75 @@ describe('CA engine runtimes', () => {
     ).toEqual(cells(3, 3))
   })
 
+  it('steps Naga 3D sparse coordinates through the shared grid projection contract', () => {
+    const current = cells(5, 5)
+    const params = settings({
+      caClass: { dimensions: 3, states: 7 },
+      renderer: { id: 'voxel-3d' },
+      simulation: {
+        engineId: 'naga-3d',
+        ruleId: 'naga-3d',
+        grid: { size: [5, 5, 5], boundary: 'wrap' },
+        initialCondition: {
+          type: 'cells',
+          cells: [[2, 2, 2, 1]]
+        }
+      }
+    })
+
+    const stepped = stepCaSimulation(current, params)
+
+    expect(stepped.cells).toEqual(cells(5, 5, [[1, 2]]))
+    expect(params.simulation?.initialCondition?.cells).toEqual([[2, 2, 2, 1]])
+    expect(params.simulation?.nagaTick).toBeUndefined()
+    expect(stepped.settings.simulation?.initialCondition?.cells).toEqual([[1, 2, 2, 1]])
+    expect(stepped.settings.simulation?.nagaTick).toBe(1)
+  })
+
+  it('wraps Naga 3D sparse coordinates before computing voxel addresses', () => {
+    const current = cells(5, 5)
+    const params = settings({
+      caClass: { dimensions: 3, states: 7 },
+      renderer: { id: 'voxel-3d' },
+      simulation: {
+        engineId: 'naga-3d',
+        ruleId: 'naga-3d',
+        grid: { size: [5, 5, 5], boundary: 'wrap' },
+        initialCondition: {
+          type: 'cells',
+          cells: [[4, 2, 2, 4]]
+        }
+      }
+    })
+
+    const stepped = stepCaSimulation(current, params)
+
+    expect(stepped.settings.simulation?.initialCondition?.cells).toEqual([[0, 2, 2, 4]])
+    expect(stepped.cells).toEqual(cells(5, 5, [[0, 2]]))
+  })
+
+  it('keeps Naga 3D sparse coordinates in place when fixed boundaries would leave the grid', () => {
+    const current = cells(5, 5)
+    const params = settings({
+      caClass: { dimensions: 3, states: 7 },
+      renderer: { id: 'voxel-3d' },
+      simulation: {
+        engineId: 'naga-3d',
+        ruleId: 'naga-3d',
+        grid: { size: [5, 5, 5], boundary: 'fixed' },
+        initialCondition: {
+          type: 'cells',
+          cells: [[4, 2, 2, 4]]
+        }
+      }
+    })
+
+    const stepped = stepCaSimulation(current, params)
+
+    expect(stepped.settings.simulation?.initialCondition?.cells).toEqual([[4, 2, 2, 4]])
+    expect(stepped.cells).toEqual(cells(5, 5, [[4, 2]]))
+  })
+
   it('defaults boundaries to wrap when the node does not specify a boundary condition', () => {
     const current = cells(3, 3, [
       [2, 2],