feat(arrow) WebGL transform handles Vectors and writeback (#2618)

Author: ibgreen-openai

AGENTS.md

@@ -23,6 +23,10 @@
 ## Before committing
 - Format code: `yarn lint fix`
 - Always `yarn lint fix` after making changes to ensure that Biome formatting is maintained.
+
+## Merge preparation
+- When asked to "get ready for merge", create a copyable Markdown description of the changes versus `master`.
+- Start that Markdown description with `Goals` and `Changes` sections, then include verification, risks, follow-up notes, or other merge-relevant sections when useful.
 
 ## Code style
 - TypeScript strict mode

docs/api-guide/gpu/arrow-table-columns.md

@@ -537,7 +537,8 @@ const model = new ArrowModel(device, {
 
 `TableTransform` is the WebGL transform-feedback counterpart. It converts an
 Arrow table to a `GPUTable` when needed, merges the table attribute layouts into
-the underlying `BufferTransform`, and can run one preserved GPU batch at a time:
+the underlying `BufferTransform`, accepts already-created `GPUVector` inputs,
+and can run one preserved GPU batch at a time:
 
 ```ts
 const transform = new TableTransform(device, {
@@ -553,14 +554,37 @@ transform.runBatches({
 });
 ```
 
+For a compute-like update path, pass `inputVectors` plus
+`copyOutputToInputVectors`. `outputs` is inferred from the copy map when it is
+omitted:
+
+```ts
+const transform = new TableTransform(device, {
+  vs,
+  shaderLayout,
+  inputVectors: {
+    particlePositions,
+    particleVelocities
+  },
+  copyOutputToInputVectors: {
+    nextParticlePositions: 'particlePositions',
+    nextParticleVelocities: 'particleVelocities'
+  }
+});
+```
+
+Transform feedback writes a dense output stream, so automatic copy-back targets
+tightly packed, directly bindable GPUVectors. It can not scatter-copy into
+padded or interleaved rows.
+
 Use `TableTransform` only for attribute-backed WebGL transform feedback. It is
 not a storage-buffer compute abstraction.
 
 Relevant public types:
 
 | Type | Meaning |
 | --- | --- |
-| `TableTransformProps` | Construction props, including `table`, `arrowTable`, `arrowPaths`, `arrowBufferProps`, and `tableCount`. |
+| `TableTransformProps` | Construction props, including `table`, `arrowTable`, `inputVectors`, `copyOutputToInputVectors`, `arrowPaths`, `arrowBufferProps`, and `tableCount`. |
 | `TableTransformBatchOptions` | `runBatches()` options, including fixed or per-batch `outputBuffers`. |
 
 ### `TableComputation`
@@ -572,7 +596,7 @@ storage bindings. Supply `GPUVector` objects by binding name:
 const computation = new TableComputation(device, {
   source: computeShader,
   shaderLayout: computeShaderLayout,
-  vectorBindings: {
+  inputVectors: {
     particlePositions,
     particleVelocities
   }
@@ -587,7 +611,7 @@ Relevant public types:
 
 | Type | Meaning |
 | --- | --- |
-| `TableComputationProps` | Construction props, including ordinary `bindings` plus `vectorBindings`. |
+| `TableComputationProps` | Construction props, including ordinary `bindings` plus `inputVectors`. |
 | `TableComputationBatch` | Batch metadata passed to a dynamic workgroup-count callback. |
 
 ## Mesh Arrow Geometry

docs/api-guide/gpu/gpu-storage-buffers.md

@@ -104,7 +104,7 @@ For table vectors, use `TableComputation` when storage bindings should come from
 const computation = new TableComputation(device, {
   source: computeShader,
   shaderLayout,
-  vectorBindings: {
+  inputVectors: {
     particlePositions,
     particleVelocities
   }

docs/api-reference/engine/picking-manager.md

@@ -12,7 +12,8 @@ import {Model, PickingManager, ShaderInputs, picking} from '@luma.gl/engine';
 const shaderInputs = new ShaderInputs({picking});
 const pickingManager = new PickingManager(device, {
   shaderInputs,
-  mode: 'auto'
+  mode: 'auto',
+  getTooltip: ({objectIndex}) => (objectIndex === null ? null : `row ${objectIndex}`)
 });
 
 const pickingPass = pickingManager.beginRenderPass();
@@ -33,6 +34,12 @@ export type PickInfo = {
 };
 ```
 
+### `PickingTooltip`
+
+```ts
+export type PickingTooltip = string | null;
+```
+
 ### `PickingMode`
 
 ```ts
@@ -50,10 +57,14 @@ export type PickingMode = 'auto' | 'index' | 'color';
 export type PickingManagerProps = {
   shaderInputs?: ShaderInputs<{picking: typeof pickingUniforms.props}>;
   onObjectPicked?: (info: PickInfo) => void;
+  getTooltip?: (info: PickInfo) => PickingTooltip;
   mode?: PickingMode;
 };
 ```
 
+- `getTooltip` returns plain tooltip text for the latest picked row/object. Returning `null` hides the tooltip.
+- The tooltip is positioned beside the latest mouse position within the active canvas container.
+
 ### `supportsIndexPicking(device: Device): boolean`
 
 Returns `true` when the device can use the index-picking backend.
@@ -100,7 +111,7 @@ When the backend is:
 
 ### `updatePickInfo(mousePosition: [number, number]): Promise<PickInfo | null>`
 
-Reads back one picked pixel, updates shader inputs, and calls `onObjectPicked` when the pick result changes.
+Reads back one picked pixel, updates shader inputs, calls `onObjectPicked` when the pick result changes, and refreshes the tooltip when `getTooltip` is provided.
 
 ### `getPickPosition(mousePosition: [number, number]): [number, number]`
 
@@ -109,6 +120,7 @@ Converts CSS pixel mouse coordinates into device-pixel picking coordinates.
 ## Remarks
 
 - `PickingManager` only manages the framebuffer and readback flow. Your model shaders still need to use a compatible picking module.
+- `getTooltip` is intentionally a formatting callback. Table-aware row lookup belongs with the caller so engine picking does not depend on Arrow or another columnar-data container.
 - Use `picking` when you want the engine to select the appropriate shader path for GLSL/WebGL vs WGSL/WebGPU.
 - Use `colorPicking` when you explicitly want the color-encoded path.
 - Use `indexPicking` when you explicitly want the integer render-target path.