# @latkit/network

WebGPU network renderer for Latkit.

## Install

```sh
npm install @latkit/gpu @latkit/network @latkit/colormaps
```

## Basic use

```ts
import { colormap } from '@latkit/colormaps';
import { requestDevice } from '@latkit/gpu';
import { createNetwork, type Topology } from '@latkit/network';

const topology: Topology = {
  vertexCount: 3,
  vertexCoords: new Float32Array([-96, 30, -95, 31, -94, 30]),
  edges: new Uint32Array([0, 1, 1, 2]),
  polylineStart: new Uint32Array([0, 0, 0]),
};

const device = await requestDevice();
const canvas = document.querySelector<HTMLCanvasElement>('#network')!;
const network = await createNetwork(device, canvas, {
  colormap: colormap('viridis'),
  graticule: true,
});

network.load(topology);
network.setChannel('vertexColor', new Float32Array([0.1, 0.8, 0.4]), [0, 1]);
network.fadeIn();
```

`createNetwork()` accepts a native Core `GPUDevice` and a caller-owned
`HTMLCanvasElement`. `@latkit/gpu` acquires the device and supplies Network's
shared presentation internals. The caller controls the canvas's placement and
CSS size.

Network borrows both. Destroy the renderer before removing the canvas, and
destroy the device only after every renderer using it has been destroyed:

```ts
network.destroy();
canvas.remove();
device.destroy();
```

## Data shape

- `vertexCoords` stores two numbers per vertex.
- `edges` stores endpoint pairs.
- `polylineStart` stores one offset per edge plus a terminal offset.
- Channel arrays must match the current vertex or edge count.

See the repository docs for topology, channel, projection, and lifecycle guidance.

## Interfaces

| Interface | Description |
| :------ | :------ |
| [Borders](interfaces/Borders.md) | GPU-ready world border geometry consumed directly by the renderer. |
| [Network](interfaces/Network.md) | Imperative controller for a WebGPU network canvas. |
| [Options](interfaces/Options.md) | Initial network renderer configuration. |
| [Topology](interfaces/Topology.md) | CPU-side graph and geometry used to build network render buffers. |

## Type Aliases

### Channel

> **Channel** = `"vertexColor"` \| `"vertexHeight"` \| `"vertexSize"` \| `"edgeColor"` \| `"edgeDash"`

Named per-vertex or per-edge data stream that can affect rendering.

***

### Events

> **Events** = `object`

Events emitted by a [Network](interfaces/Network.md) instance.

#### Remarks

`hover` and `select` use `null` values to report cleared interaction state.
Programmatic selection methods do not emit `select`; user pointer selection
does emit it.

#### Properties

| Property | Type | Description |
| :------ | :------ | :------ |
| <a id="property-devicelost"></a> `deviceLost` | (`reason`, `message`) => `void` | WebGPU device-loss notification surfaced before rendering pauses. |
| <a id="property-hover"></a> `hover` | (`kind`, `index`) => `void` | Hovered vertex or edge; null kind and index after hover exit. |
| <a id="property-select"></a> `select` | (`kind`, `index`) => `void` | User-selected vertex or edge; null kind and index after selection clear. |
| <a id="property-zoom"></a> `zoom` | (`atFitView`) => `void` | Camera zoom state after a fit-view transition or gesture. |

## Functions

### createNetwork()

> **createNetwork**(`device`, `canvas`, `options?`): `Promise`\<[`Network`](interfaces/Network.md)\>

Creates a WebGPU network renderer on a caller-owned canvas.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `device` | `GPUDevice` | Borrowed Core WebGPU device. The caller retains ownership. |
| `canvas` | `HTMLCanvasElement` | Borrowed canvas used for presentation and pointer input. |
| `options` | [`Options`](interfaces/Options.md) | Initial rendering and interaction options. |

#### Returns

`Promise`\<[`Network`](interfaces/Network.md)\>

A controller for loading topology, binding channels, and releasing GPU resources.

#### Throws

TypeError when `device` does not provide Core WebGPU features and limits.

#### Throws

Error when canvas presentation or renderer initialization fails.

#### Example

```ts
const network = await createNetwork(device, canvas, { graticule: true });
network.load(topology);
network.fadeIn();
```

The returned controller owns its renderer resources, but not `canvas` or
`device`. Destroy the controller before removing the canvas or destroying the
borrowed device.