@hello-terrain/three 0.0.0-alpha.6 → 0.0.0-alpha.8

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 import { BufferGeometry } from 'three';
 import * as three_webgpu from 'three/webgpu';
-import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
+import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageArrayTexture, StorageTexture, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
 import * as _hello_terrain_work from '@hello-terrain/work';
-import { TaskRef } from '@hello-terrain/work';
+import { TaskRef, Graph } from '@hello-terrain/work';
 import Node$1 from 'three/src/nodes/core/Node.js';
 import * as three_tsl from 'three/tsl';
 
@@ -114,7 +114,7 @@ declare class TerrainMesh extends InstancedMesh {
 type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
 type ComputePipeline = ComputeStageCallback[];
 
-/** Default compile task — uses normalFieldStageTask as the leaf. */
+/** Default compile task — uses terrainFieldStageTask as the leaf. */
 declare const compileComputeTask: _hello_terrain_work.Task<{
     execute: (renderer: WebGPURenderer, instanceCount: number) => void;
 }, string, unknown>;
@@ -390,6 +390,45 @@ type CubeSphereSurfaceConfig = {
  */
 declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
 
+type TerrainFieldStorageBackendType = "array-texture" | "atlas" | "texture-3d";
+type TerrainFieldStorageFormat = "rgba16float" | "rgba32float";
+type TerrainFieldStorageOptions = {
+    backend?: TerrainFieldStorageBackendType;
+    filter?: "nearest" | "linear";
+    format?: TerrainFieldStorageFormat;
+};
+interface TerrainFieldStorage {
+    readonly backendType: TerrainFieldStorageBackendType;
+    readonly edgeVertexCount: number;
+    readonly tileCount: number;
+    readonly texture: StorageArrayTexture | StorageTexture;
+    uv(ix: Node, iy: Node, tileIndex: Node): Node;
+    texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
+    resize(width: number, height: number, tileCount: number): void;
+}
+declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function AtlasBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+/**
+ * Placeholder backend for future true 3D storage-texture support in Three.js.
+ * We keep it present to preserve the backend API shape.
+ */
+declare function Texture3DBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function createTerrainFieldStorage(edgeVertexCount: number, tileCount: number, renderer?: WebGPURenderer, options?: TerrainFieldStorageOptions): TerrainFieldStorage;
+declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node, value: Node): Node;
+declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
+
 interface TerrainUniformsParams {
     rootSize: number;
     rootOrigin: Vector3Like;
@@ -431,11 +470,6 @@ interface ElevationFieldContext {
     attribute: StorageBufferAttribute;
     node: StorageBufferNode;
 }
-interface NormalFieldContext {
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
     instanceId: TaskRef<string>;
@@ -449,14 +483,17 @@ interface TerrainTasks {
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
-    createNormalFieldContext: TaskRef<NormalFieldContext>;
+    createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
     elevationFieldStage: TaskRef<ComputePipeline>;
-    normalFieldStage: TaskRef<ComputePipeline>;
+    terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }>;
     executeCompute: TaskRef<void | (() => void)>;
 }
+type TerrainGraph = Graph<string, {
+    renderer: WebGPURenderer;
+}>;
 
 declare const createElevationFieldContextTask: _hello_terrain_work.Task<{
     data: Float32Array<ArrayBuffer>;
@@ -479,11 +516,9 @@ declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline,
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
-declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: three_webgpu.StorageBufferNode;
-}, string, unknown>;
+declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
 /**
  * Normal field compute stage — reads height neighbors from the elevation field
  * buffer, computes surface normals via central differences, packs XZ
@@ -492,7 +527,7 @@ declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
  *
  * Accumulates the upstream elevation pipeline via `get(elevationFieldStageTask)`.
  */
-declare const normalFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
 interface ElevationParams {
     worldPosition: Node$1;
@@ -516,7 +551,7 @@ declare const origin: _hello_terrain_work.ParamRef<{
 }>;
 /**
  * Number of segments per inner tile edge.
- * 13 is the max tiles we can support for 256 workgroups (13 + 3 === 16.. 16x16)
+ * Effective edge vertex count is `innerTileSegments + 3`.
  */
 declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
 /** Skirt scale factor. */
@@ -531,6 +566,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -538,11 +575,10 @@ declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
  * Builds the TSL position node for the terrain shader.
  *
  * Depends on leafStorageTask (buffer objects), createUniformsTask
- * (uniform nodes), createElevationFieldContextTask (elevation field storage),
- * and createNormalFieldContextTask (normal field storage).
+ * (uniform nodes), and createTerrainFieldTextureTask (combined terrain field storage).
  *
- * The position node also reads normals from the normal field buffer
- * per-vertex (using vertexIndex) and assigns them to the vNormal
+ * The position node reads packed terrain samples (height + normal.xz)
+ * per-vertex and assigns them to the vNormal
  * varying for use in the fragment shader.
  *
  * These only change when their GPU resources are recreated
@@ -591,9 +627,7 @@ declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContex
  */
 declare const updateUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
 
-declare function terrainGraph(): _hello_terrain_work.Graph<string, {
-    renderer: WebGPURenderer;
-}>;
+declare function terrainGraph(): TerrainGraph;
 /** All terrain task refs for direct access. */
 declare const terrainTasks: {
     readonly instanceId: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
@@ -625,13 +659,11 @@ declare const terrainTasks: {
         rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
         tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
     }, string, unknown>;
-    readonly createNormalFieldContext: _hello_terrain_work.Task<{
-        data: Uint32Array<ArrayBuffer>;
-        attribute: three_webgpu.StorageBufferAttribute;
-        node: three_webgpu.StorageBufferNode;
-    }, string, unknown>;
+    readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
-    readonly normalFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }, string, unknown>;
@@ -640,6 +672,13 @@ declare const terrainTasks: {
     }>;
 };
 
+type ComputeDeviceLimits = {
+    maxWorkgroupSizeX: number;
+    maxWorkgroupSizeY: number;
+    maxWorkgroupInvocations: number;
+};
+declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -712,5 +751,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createNormalFieldContextTask, createSpatialIndex, createState, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, maxLevel, maxNodes, normalFieldStageTask, origin, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, surface, surfaceTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, NormalFieldContext, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { BufferGeometry } from 'three';
 import * as three_webgpu from 'three/webgpu';
-import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
+import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageArrayTexture, StorageTexture, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
 import * as _hello_terrain_work from '@hello-terrain/work';
-import { TaskRef } from '@hello-terrain/work';
+import { TaskRef, Graph } from '@hello-terrain/work';
 import Node$1 from 'three/src/nodes/core/Node.js';
 import * as three_tsl from 'three/tsl';
 
@@ -114,7 +114,7 @@ declare class TerrainMesh extends InstancedMesh {
 type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
 type ComputePipeline = ComputeStageCallback[];
 
-/** Default compile task — uses normalFieldStageTask as the leaf. */
+/** Default compile task — uses terrainFieldStageTask as the leaf. */
 declare const compileComputeTask: _hello_terrain_work.Task<{
     execute: (renderer: WebGPURenderer, instanceCount: number) => void;
 }, string, unknown>;
@@ -390,6 +390,45 @@ type CubeSphereSurfaceConfig = {
  */
 declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
 
+type TerrainFieldStorageBackendType = "array-texture" | "atlas" | "texture-3d";
+type TerrainFieldStorageFormat = "rgba16float" | "rgba32float";
+type TerrainFieldStorageOptions = {
+    backend?: TerrainFieldStorageBackendType;
+    filter?: "nearest" | "linear";
+    format?: TerrainFieldStorageFormat;
+};
+interface TerrainFieldStorage {
+    readonly backendType: TerrainFieldStorageBackendType;
+    readonly edgeVertexCount: number;
+    readonly tileCount: number;
+    readonly texture: StorageArrayTexture | StorageTexture;
+    uv(ix: Node, iy: Node, tileIndex: Node): Node;
+    texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
+    resize(width: number, height: number, tileCount: number): void;
+}
+declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function AtlasBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+/**
+ * Placeholder backend for future true 3D storage-texture support in Three.js.
+ * We keep it present to preserve the backend API shape.
+ */
+declare function Texture3DBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function createTerrainFieldStorage(edgeVertexCount: number, tileCount: number, renderer?: WebGPURenderer, options?: TerrainFieldStorageOptions): TerrainFieldStorage;
+declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node, value: Node): Node;
+declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
+
 interface TerrainUniformsParams {
     rootSize: number;
     rootOrigin: Vector3Like;
@@ -431,11 +470,6 @@ interface ElevationFieldContext {
     attribute: StorageBufferAttribute;
     node: StorageBufferNode;
 }
-interface NormalFieldContext {
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
     instanceId: TaskRef<string>;
@@ -449,14 +483,17 @@ interface TerrainTasks {
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
-    createNormalFieldContext: TaskRef<NormalFieldContext>;
+    createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
     elevationFieldStage: TaskRef<ComputePipeline>;
-    normalFieldStage: TaskRef<ComputePipeline>;
+    terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }>;
     executeCompute: TaskRef<void | (() => void)>;
 }
+type TerrainGraph = Graph<string, {
+    renderer: WebGPURenderer;
+}>;
 
 declare const createElevationFieldContextTask: _hello_terrain_work.Task<{
     data: Float32Array<ArrayBuffer>;
@@ -479,11 +516,9 @@ declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline,
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
-declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: three_webgpu.StorageBufferNode;
-}, string, unknown>;
+declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
 /**
  * Normal field compute stage — reads height neighbors from the elevation field
  * buffer, computes surface normals via central differences, packs XZ
@@ -492,7 +527,7 @@ declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
  *
  * Accumulates the upstream elevation pipeline via `get(elevationFieldStageTask)`.
  */
-declare const normalFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
 interface ElevationParams {
     worldPosition: Node$1;
@@ -516,7 +551,7 @@ declare const origin: _hello_terrain_work.ParamRef<{
 }>;
 /**
  * Number of segments per inner tile edge.
- * 13 is the max tiles we can support for 256 workgroups (13 + 3 === 16.. 16x16)
+ * Effective edge vertex count is `innerTileSegments + 3`.
  */
 declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
 /** Skirt scale factor. */
@@ -531,6 +566,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -538,11 +575,10 @@ declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
  * Builds the TSL position node for the terrain shader.
  *
  * Depends on leafStorageTask (buffer objects), createUniformsTask
- * (uniform nodes), createElevationFieldContextTask (elevation field storage),
- * and createNormalFieldContextTask (normal field storage).
+ * (uniform nodes), and createTerrainFieldTextureTask (combined terrain field storage).
  *
- * The position node also reads normals from the normal field buffer
- * per-vertex (using vertexIndex) and assigns them to the vNormal
+ * The position node reads packed terrain samples (height + normal.xz)
+ * per-vertex and assigns them to the vNormal
  * varying for use in the fragment shader.
  *
  * These only change when their GPU resources are recreated
@@ -591,9 +627,7 @@ declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContex
  */
 declare const updateUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
 
-declare function terrainGraph(): _hello_terrain_work.Graph<string, {
-    renderer: WebGPURenderer;
-}>;
+declare function terrainGraph(): TerrainGraph;
 /** All terrain task refs for direct access. */
 declare const terrainTasks: {
     readonly instanceId: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
@@ -625,13 +659,11 @@ declare const terrainTasks: {
         rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
         tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
     }, string, unknown>;
-    readonly createNormalFieldContext: _hello_terrain_work.Task<{
-        data: Uint32Array<ArrayBuffer>;
-        attribute: three_webgpu.StorageBufferAttribute;
-        node: three_webgpu.StorageBufferNode;
-    }, string, unknown>;
+    readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
-    readonly normalFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }, string, unknown>;
@@ -640,6 +672,13 @@ declare const terrainTasks: {
     }>;
 };
 
+type ComputeDeviceLimits = {
+    maxWorkgroupSizeX: number;
+    maxWorkgroupSizeY: number;
+    maxWorkgroupInvocations: number;
+};
+declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -712,5 +751,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createNormalFieldContextTask, createSpatialIndex, createState, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, maxLevel, maxNodes, normalFieldStageTask, origin, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, surface, surfaceTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, NormalFieldContext, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { BufferGeometry } from 'three';
 import * as three_webgpu from 'three/webgpu';
-import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
+import { InstancedMesh, NodeMaterial, Node, WebGPURenderer, StorageArrayTexture, StorageTexture, StorageBufferAttribute, StorageBufferNode, UniformNode, Vector3, Vector3Like, ConstNode } from 'three/webgpu';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { ShaderCallNodeInternal } from 'three/src/nodes/TSL.js';
 import * as _hello_terrain_work from '@hello-terrain/work';
-import { TaskRef } from '@hello-terrain/work';
+import { TaskRef, Graph } from '@hello-terrain/work';
 import Node$1 from 'three/src/nodes/core/Node.js';
 import * as three_tsl from 'three/tsl';
 
@@ -114,7 +114,7 @@ declare class TerrainMesh extends InstancedMesh {
 type ComputeStageCallback = (nodeIndex: Node, globalVertexIndex: Node, uv: Node, localCoordinates: Node, texelSize: Node) => void;
 type ComputePipeline = ComputeStageCallback[];
 
-/** Default compile task — uses normalFieldStageTask as the leaf. */
+/** Default compile task — uses terrainFieldStageTask as the leaf. */
 declare const compileComputeTask: _hello_terrain_work.Task<{
     execute: (renderer: WebGPURenderer, instanceCount: number) => void;
 }, string, unknown>;
@@ -390,6 +390,45 @@ type CubeSphereSurfaceConfig = {
  */
 declare function createCubeSphereSurface(_cfg: CubeSphereSurfaceConfig): Surface;
 
+type TerrainFieldStorageBackendType = "array-texture" | "atlas" | "texture-3d";
+type TerrainFieldStorageFormat = "rgba16float" | "rgba32float";
+type TerrainFieldStorageOptions = {
+    backend?: TerrainFieldStorageBackendType;
+    filter?: "nearest" | "linear";
+    format?: TerrainFieldStorageFormat;
+};
+interface TerrainFieldStorage {
+    readonly backendType: TerrainFieldStorageBackendType;
+    readonly edgeVertexCount: number;
+    readonly tileCount: number;
+    readonly texture: StorageArrayTexture | StorageTexture;
+    uv(ix: Node, iy: Node, tileIndex: Node): Node;
+    texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
+    resize(width: number, height: number, tileCount: number): void;
+}
+declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function AtlasBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+/**
+ * Placeholder backend for future true 3D storage-texture support in Three.js.
+ * We keep it present to preserve the backend API shape.
+ */
+declare function Texture3DBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
+declare function createTerrainFieldStorage(edgeVertexCount: number, tileCount: number, renderer?: WebGPURenderer, options?: TerrainFieldStorageOptions): TerrainFieldStorage;
+declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node, value: Node): Node;
+declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
+
 interface TerrainUniformsParams {
     rootSize: number;
     rootOrigin: Vector3Like;
@@ -431,11 +470,6 @@ interface ElevationFieldContext {
     attribute: StorageBufferAttribute;
     node: StorageBufferNode;
 }
-interface NormalFieldContext {
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: StorageBufferNode;
-}
 /** Task refs for the standard terrain pipeline. */
 interface TerrainTasks {
     instanceId: TaskRef<string>;
@@ -449,14 +483,17 @@ interface TerrainTasks {
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
-    createNormalFieldContext: TaskRef<NormalFieldContext>;
+    createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
     elevationFieldStage: TaskRef<ComputePipeline>;
-    normalFieldStage: TaskRef<ComputePipeline>;
+    terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }>;
     executeCompute: TaskRef<void | (() => void)>;
 }
+type TerrainGraph = Graph<string, {
+    renderer: WebGPURenderer;
+}>;
 
 declare const createElevationFieldContextTask: _hello_terrain_work.Task<{
     data: Float32Array<ArrayBuffer>;
@@ -479,11 +516,9 @@ declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline,
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
-declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
-    data: Uint32Array<ArrayBuffer>;
-    attribute: StorageBufferAttribute;
-    node: three_webgpu.StorageBufferNode;
-}, string, unknown>;
+declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, string, {
+    renderer: WebGPURenderer;
+}>;
 /**
  * Normal field compute stage — reads height neighbors from the elevation field
  * buffer, computes surface normals via central differences, packs XZ
@@ -492,7 +527,7 @@ declare const createNormalFieldContextTask: _hello_terrain_work.Task<{
  *
  * Accumulates the upstream elevation pipeline via `get(elevationFieldStageTask)`.
  */
-declare const normalFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
 interface ElevationParams {
     worldPosition: Node$1;
@@ -516,7 +551,7 @@ declare const origin: _hello_terrain_work.ParamRef<{
 }>;
 /**
  * Number of segments per inner tile edge.
- * 13 is the max tiles we can support for 256 workgroups (13 + 3 === 16.. 16x16)
+ * Effective edge vertex count is `innerTileSegments + 3`.
  */
 declare const innerTileSegments: _hello_terrain_work.ParamRef<number>;
 /** Skirt scale factor. */
@@ -531,6 +566,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -538,11 +575,10 @@ declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
  * Builds the TSL position node for the terrain shader.
  *
  * Depends on leafStorageTask (buffer objects), createUniformsTask
- * (uniform nodes), createElevationFieldContextTask (elevation field storage),
- * and createNormalFieldContextTask (normal field storage).
+ * (uniform nodes), and createTerrainFieldTextureTask (combined terrain field storage).
  *
- * The position node also reads normals from the normal field buffer
- * per-vertex (using vertexIndex) and assigns them to the vNormal
+ * The position node reads packed terrain samples (height + normal.xz)
+ * per-vertex and assigns them to the vNormal
  * varying for use in the fragment shader.
  *
  * These only change when their GPU resources are recreated
@@ -591,9 +627,7 @@ declare const createUniformsTask: _hello_terrain_work.Task<TerrainUniformsContex
  */
 declare const updateUniformsTask: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
 
-declare function terrainGraph(): _hello_terrain_work.Graph<string, {
-    renderer: WebGPURenderer;
-}>;
+declare function terrainGraph(): TerrainGraph;
 /** All terrain task refs for direct access. */
 declare const terrainTasks: {
     readonly instanceId: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
@@ -625,13 +659,11 @@ declare const terrainTasks: {
         rootUVCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
         tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | three_webgpu.Node, number | three_webgpu.Node, number | three_webgpu.Node]>;
     }, string, unknown>;
-    readonly createNormalFieldContext: _hello_terrain_work.Task<{
-        data: Uint32Array<ArrayBuffer>;
-        attribute: three_webgpu.StorageBufferAttribute;
-        node: three_webgpu.StorageBufferNode;
-    }, string, unknown>;
+    readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
+        renderer: WebGPURenderer;
+    }>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
-    readonly normalFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
+    readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
         execute: (renderer: WebGPURenderer, instanceCount: number) => void;
     }, string, unknown>;
@@ -640,6 +672,13 @@ declare const terrainTasks: {
     }>;
 };
 
+type ComputeDeviceLimits = {
+    maxWorkgroupSizeX: number;
+    maxWorkgroupSizeY: number;
+    maxWorkgroupInvocations: number;
+};
+declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -712,5 +751,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { Dir, TerrainGeometry, TerrainMesh, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createNormalFieldContextTask, createSpatialIndex, createState, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, maxLevel, maxNodes, normalFieldStageTask, origin, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, surface, surfaceTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, NormalFieldContext, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };