# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `BatchJob`

```ts
interface BatchJob
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Echoed back on the result, so a caller can correlate without relying on order. |
| `document` | `BatchDocument` |  |  |
| `format?` | `ExportFormat` |  | Default `'svg'` — the only format that needs no rasterizer at all. |
| `options?` | `ExportOptions` |  | Merged over the batch-wide options. |

### `BatchOptions`

```ts
interface BatchOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options?` | `ExportOptions` |  | Applied to every job; a job's own `options` win. |
| `theme?` | `Theme` |  | Theme for every job. |
| `rendererConfig?` | `SVGRendererConfig` |  | Renderer config for every job. |
| `concurrency?` | `number` |  | How many jobs run at once. Default 4. |
| `onProgress?` | `(done: number, total: number, result: BatchResult) => void` |  | Called as each job settles — for a progress bar or a log line. |

### `BatchResult`

```ts
interface BatchResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `format` | `ExportFormat` |  |  |
| `output?` | `string` |  | The artifact: an SVG string, or a `data:` URL for a raster. Absent when `error` is set. |
| `warnings` | `string[]` |  | Fidelity caveats (foreignObject, unresolved theme vars, a clamped size). |
| `error?` | `Error` |  | Set when THIS job failed. The rest of the batch still ran. |

### `BoundsOptions`

```ts
interface BoundsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeIds?` | `Set<string>` |  | Only union elements whose subtree is one of these diagram ids (node ids / link ids). This is what makes a SELECTION export tight around the selection. |

### `CaptureHostOptions`

```ts
interface CaptureHostOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale?` | `number` |  | The camera zoom the html layer is transformed by. Client rects are SCREEN space, so they are divided by this to get the host-local layout coordinates the export needs. Defaults to being inferred from the host itself, which is more reliable than trusting a caller to remember. |
| `maxElements?` | `number` |  | Safety valve for a pathologically deep host. Default 4000 elements. |

### `ClampResult`

```ts
interface ClampResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale` | `number` |  | The scale that actually gets used (≤ the requested one). |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `warning?` | `string` |  | Set when the requested scale had to be reduced. |

### `CustomNodeCapture`

What the DOM boundary hands the pure layer for one custom node.

```ts
interface CustomNodeCapture
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The node id — carried onto the group, and what `includeIds` scoping matches. |
| `rect` | `Rectangle` |  | The node's WORLD rect (position + size), i.e. where to place the content. |
| `fidelity` | `CustomNodeFidelity` |  |  |
| `content?` | `VNode[]` |  | The transcribed display list, in HOST-RELATIVE coordinates (0,0 = the host's top-left). Placed by translating to `rect`. Only for `fidelity: 'vector'`. |
| `html?` | `string` |  | Raw XHTML for the `foreignObject` attempt. Only for `fidelity: 'html'`. |
| `warning?` | `string` |  | A caveat the DOM boundary knows and this layer cannot see. |

### `CustomNodeOptions`

```ts
interface CustomNodeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `htmlFallback?` | `HtmlFallbackMode` |  | How to export a `fidelity: 'html'` capture. Default `'foreignObject'` — the honest best effort: browsers render it, so an SVG opened in a browser or placed in a web page is correct. It is still reported as a fidelity risk, because a PDF and most standalone rasterizers will drop it. |

### `FontSource`

```ts
interface FontSource
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `family` | `string` |  | The family name the diagram's `font-family` refers to, e.g. `Inter`. |
| `data` | `Uint8Array` |  | The font program's bytes. |
| `format?` | `FontFormat` |  |  |
| `weight?` | `string \| number` |  | e.g. `400`, `700`, `'bold'`. Default `'normal'`. |
| `style?` | `string` |  | `'normal'` \| `'italic'`. Default `'normal'`. |
| `unicodeRange?` | `string` |  | Optional `unicode-range` descriptor. |

### `Page`

```ts
interface Page
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | 0-based, reading order (left→right, top→bottom). |
| `row` | `number` |  |  |
| `column` | `number` |  |  |
| `rect` | `Rectangle` |  | The world window mapped onto the paper. Always the full page size — see the header. |
| `clip` | `Rectangle` |  | The sub-rectangle actually painted. Equals `rect` unless a break was snapped in. |

### `PaginationOptions`

```ts
interface PaginationOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pageWidth` | `number` |  | One page's width in WORLD units. |
| `pageHeight` | `number` |  | One page's height in WORLD units. |
| `overlap?` | `number` |  | World units each page repeats from its neighbour — a bleed, so a printed poster can be trimmed and taped without losing a strip. Default 0. |
| `snapToNodes?` | `boolean` |  | Pull a page break back so it does not slice through a node. Default true — a break through the middle of a box is the thing that makes tiled printouts unusable. |
| `snapTolerance?` | `number` |  | How far a break may be pulled back, as a fraction of the page. Default 0.25. |
| `content?` | `Rectangle` |  | The region to paginate. Default: the tree's content bounds. |
| `padding?` | `number` |  | Padding around the content bounds, in world units. Default 20. |

### `PaginationResult`

```ts
interface PaginationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pages` | `Page[]` |  |  |
| `columns` | `number` |  |  |
| `rows` | `number` |  |  |
| `columnBreaks` | `number[]` |  | The x break positions (page origins). |
| `rowBreaks` | `number[]` |  | The y break positions. |
| `warnings` | `string[]` |  | Nodes we could NOT spare — a break had to cut them. |

### `PdfExportOptions`

```ts
interface PdfExportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme?` | `Theme` |  | The theme the tree was rendered with. REQUIRED for fidelity in CSS mode: a node's fill and a link's stroke live in the stylesheet, not on the element, so without the theme to resolve them the PDF comes out nearly blank. Defaults to LIGHT_THEME. |
| `pageSize?` | `PageSize \| { width: number; height: number }` |  |  |
| `orientation?` | `Orientation` |  |  |
| `margin?` | `number \| { top: number; right: number; bottom: number; left: number }` |  | Points (1/72"). Default 36 (half an inch) on every side. |
| `viewBox?` | `Rectangle` |  | The world rectangle to draw. Default: the tree's content bounds. |
| `padding?` | `number` |  | Padding around the content bounds, in world units. Default 20. |
| `metadata?` | `PdfMetadata` |  |  |
| `backgroundColor?` | `string` |  | Paint a page background. Default: none (white paper shows through). |
| `pages?` | `Array<Rectangle \| { rect: Rectangle; clip?: Rectangle }>` |  | Pages to lay the diagram across. Supplied by the paginator. |
| `pageNumbers?` | `boolean` |  | Draw "n / total" at the foot of each page. Default false; the paginator turns it on. |

### `PdfExportResult`

```ts
interface PdfExportResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pdf` | `Uint8Array` |  |  |
| `pageCount` | `number` |  |  |
| `warnings` | `string[]` |  |  |

### `PdfMetadata`

```ts
interface PdfMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `string` |  |  |
| `author?` | `string` |  |  |
| `subject?` | `string` |  |  |
| `keywords?` | `string` |  |  |
| `creationDate?` | `string` |  | ISO-8601. Omit for a deterministic file — a wall-clock stamp makes bytes differ. |

### `PdfRgb`

PDF paints in 0–1 channels, not 0–255. Named `PdfRgb` so it cannot be confused with the theme's `Rgb` (which is 0–255).

```ts
interface PdfRgb
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `r` | `number` |  |  |
| `g` | `number` |  |  |
| `b` | `number` |  |  |

### `PrintOptions`

```ts
interface PrintOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `string` |  | Shown in the browser's print dialog and as the default filename. |
| `pageSize?` | `string` |  | CSS page size, e.g. `'A4 landscape'`. Default `'auto'`. |
| `margin?` | `string` |  | CSS margin for |

### `RasterBackend`

Pluggable rasterizer. Returns a `data:` URL.

```ts
interface RasterBackend
```

**Members**

- `rasterize(request: RasterizeRequest): Promise<string>`

### `RasterizeRequest`

What a rasterizer is asked to produce.

```ts
interface RasterizeRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `svg` | `string` |  | A standalone SVG document (styles inlined, no external references). |
| `width` | `number` |  | Target pixel width (already scaled). |
| `height` | `number` |  | Target pixel height (already scaled). |
| `mimeType` | `string` |  | `image/png` \| `image/jpeg` \| `image/webp`. |
| `quality?` | `number` |  | 0–1, for the lossy formats. |

### `ResolveAssetsOptions`

```ts
interface ResolveAssetsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fetcher?` | `AssetFetcher` |  | How to get the bytes. Defaults to `fetch` when the environment has one. |
| `maxBytes?` | `number` |  | Cap on one asset's size, in bytes. Default 5MB — a data: URI is ~33% bigger than the file. |

### `ResolveAssetsResult`

```ts
interface ResolveAssetsResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tree` | `VNode` |  |  |
| `inlined` | `number` |  | How many external references were replaced. |
| `warnings` | `string[]` |  |  |

### `ResvgModule`

The slice of `@resvg/resvg-js` we use.

```ts
interface ResvgModule
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `Resvg` | `new ( svg: string \| Uint8Array, options?: { fitTo?: { mode: 'width' \| 'height'; value: number } } ) => { render(): { asPng(): Uint8Array } }` |  |  |

### `SvgExportResult`

```ts
interface SvgExportResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `svg` | `string` |  | The standalone SVG document. |
| `width` | `number` |  | Intrinsic width in px (viewBox width × the CLAMPED scale). |
| `height` | `number` |  | Intrinsic height in px. |
| `viewBox` | `ViewBox` |  | The world rectangle the document actually covers — what pagination and PDF page off. |
| `warnings` | `string[]` |  | Fidelity caveats hit during this export (foreignObject, unresolved vars, size clamp, …). |

### `TieredFetchOptions`

```ts
interface TieredFetchOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fetcher?` | `AssetFetcher` |  | Tier 2: consulted only when the environment's own fetch fails. |
| `maxBytes?` | `number` |  | Cap on one asset's size, in bytes. Default 5MB. TERMINAL — no tier retries it. |
| `timeoutMs?` | `number` |  | Bound on fetching ONE URL, per tier, in milliseconds. Default 5000. |

### `TieredFetchResult`

```ts
interface TieredFetchResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `byUrl` | `Map<string, string>` |  | URL → `data:` URI, for every asset some tier could produce. |
| `failures` | `Map<string, string>` |  | URL → why EVERY tier failed — ready to surface as a warning. |