# Viewport

Import these from `@grafloria/renderer`.

## Classes

### `ViewportController`

```ts
class ViewportController
```

**Methods**

- `constructor(options: ViewportControllerOptions = {})`
- `getViewport(): Rectangle`
- `getZoom(): number`
- `getState(): ViewportState`
- `setViewport(viewport: Rectangle): void` — Replace the camera rectangle wholesale.
- `setCanvasSize(width: number, height: number, options: CanvasSizeOptions = {}): void` — Track the canvas element's pixel size. Call on mount and on resize: the width/height of the camera rect must stay equal to the canvas's CSS-pixel size for {@link clientToWorld} to be the true inverse of the rendered `viewBox` (see the coordinate contract).
- `syncCanvasSize(rect: CanvasRect, options: CanvasSizeOptions = {}): void` — Convenience form of {@link setCanvasSize} taking a `getBoundingClientRect()`.
- `clampZoom(zoom: number): number` — Clamp to `[minZoom, maxZoom]`. Non-finite input falls back to the current zoom.
- `setZoom(zoom: number): number` — Set zoom (centre-preserving), clamped. Returns the zoom actually applied.
- `zoomBy(delta: number): number` — Additive zoom step, clamped — the convention the Angular canvas's wheel handler uses (`zoom + delta`, not `zoom * factor`). Returns the applied zoom.
- `zoomByWheel(deltaY: number): number` — Apply one wheel notch. Mirrors `DiagramCanvasComponent.onWheel`: scrolling DOWN (`deltaY > 0`) zooms OUT by `zoomSensitivity`, scrolling up zooms in.
- `zoomAtPoint(zoom: number, clientX: number, clientY: number, rect: CanvasRect): number` — Cursor-anchored zoom: change zoom while keeping the world point currently under `(clientX, clientY)` pinned to that same screen pixel. This is the standard "zoom towards the pointer" behaviour; the plain {@link setZoom} / {@link zoomByWheel} pair is centre-anchored instead.
- `pan(dx: number, dy: number): void` — Translate the camera by a WORLD-space delta.
- `panByScreenDelta(dxPx: number, dyPx: number): void` — Translate the camera by a SCREEN-space (pixel) drag delta, converting to world units by dividing by zoom.
- `getViewBox(): Rectangle` — The world-space rectangle actually visible — centre-preserving zoom applied to the camera rect. Identical to the `viewBox` `SVGRenderer` emits, and the basis of {@link clientToWorld}.
- `getViewBoxString(): string` — The `viewBox` attribute string: `"x y width height"`.
- `getRenderViewport(): Rectangle` — The rectangle to hand to `IRenderer.render(viewport, zoom)` alongside {@link getZoom}. The renderer applies the zoom itself, so this is the raw camera rect — do NOT pre-divide it by zoom (see the class docs).
- `getHtmlLayerTransform(): string` — CSS transform that keeps an HTML overlay layer registered with the SVG layer in the hybrid renderer: `translate(...) scale(zoom)`.
- `clientToWorld(clientX: number, clientY: number, rect: CanvasRect): ViewportPoint` — Convert a client/screen point (e.g. `event.clientX/Y`) into world space. Exact inverse of {@link worldToClient} at any zoom.
- `worldToClient(worldX: number, worldY: number, rect: CanvasRect): ViewportPoint` — Convert a world point into client/screen coordinates — for positioning overlays, toolbars and tooltips over the canvas. Exact inverse of {@link clientToWorld}.
- `fitToBounds(bounds: Rectangle, padding = 40, options?: { maxZoom?: number }): number` — Frame `bounds` (a world-space content rectangle): pick the largest clamped zoom at which it fits inside the canvas with `padding` CSS pixels of margin on every side, and centre it. A zero-area canvas or bounds is a no-op.
- `onChange(listener: ViewportChangeListener): Unsubscribe` — Subscribe to camera changes. Returns an unsubscribe function.
- `dispose(): void` — Drop all subscribers.

## Interfaces

### `CanvasRect`

The subset of `DOMRect` the camera actually needs. Any `getBoundingClientRect()`
result satisfies it; tests can pass a plain object. Keeping it structural is
what lets this class run in Node with no DOM.

```ts
interface CanvasRect
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `left` | `number` |  |  |
| `top` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `CanvasSizeOptions`

How {@link ViewportController.setCanvasSize} places the camera on a size change.

```ts
interface CanvasSizeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `anchor?` | `'origin' \| 'center'` |  | `'origin'` (default) keeps the camera's x/y. `'center'` keeps the world point at the canvas centre — what a picture drawn with `preserveAspectRatio="xMidYMid meet"` (an adopted server svg before the first resize) showed. |

### `ViewportControllerOptions`

```ts
interface ViewportControllerOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport?` | `Rectangle` |  | Camera rectangle. `x`/`y` are WORLD coordinates; `width`/`height` are the canvas's CSS-PIXEL dimensions (see the coordinate contract below). |
| `zoom?` | `number` |  |  |
| `minZoom?` | `number` |  | Default 0.1 — matches `DiagramCanvasComponent.minZoom`. |
| `maxZoom?` | `number` |  | Default 3.0 — matches `DiagramCanvasComponent.maxZoom`. |
| `zoomSensitivity?` | `number` |  | Additive step applied per wheel notch. Default 0.1. |

### `ViewportPoint`

A point in world space. Declared structurally (rather than imported from
`@grafloria/engine`) so the viewport module stays dependency-free: camera math
needs no diagram model. Structurally identical to `Point` from `@grafloria/engine`,
so the two interoperate without conversion.

```ts
interface ViewportPoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |

### `ViewportState`

Immutable snapshot of the camera.

```ts
interface ViewportState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `Rectangle` |  |  |
| `zoom` | `number` |  |  |

## Types

### `Unsubscribe`

Remove a previously registered listener.

```ts
type Unsubscribe = () => void;
```

### `ViewportChangeListener`

```ts
type ViewportChangeListener = (state: ViewportState) => void;
```
