# gizapp/surface

One app surface bridge for Canvas2D, WebGPU and WebGL. Applications extend the ordinary asset graph.

```gizlang
import * as Surface from "gizapp/surface";
```

## Types

### `File`

```gizlang
type File = { name: string; body: bytes; }
```

A named file of a surface program: a sound its cues name (WAV), or an asset its `file` export takes before
initialize (gizlang/catalog).

- `name`: `string`
- `body`: `bytes`

### `Served`

```gizlang
type Served = { title: string; app: string; port: i64; color: string; label: string; help: string; sounds: Vec<File>; files: Vec<File> }
```

A game's page as serve makes it: its TITLE, its APP name (the folder of its files), its PORT and theme COLOR, the
LABEL of its surface, the HELP the page shows, its SOUNDS and its asset FILES.

- `title`: `string`
- `app`: `string`
- `port`: `i64`
- `color`: `string`
- `label`: `string`
- `help`: `string`
- `sounds`: `Vec<M128.File>`
- `files`: `Vec<M128.File>`

## Functions

### `profileWire`

```gizlang
function profileWire(): string
```

Browser recording uses the existing profiler's event numbers and reader. It never supplies CPU samples.

Effects: fail, alloc.

### `sources`

```gizlang
function sources(host: string, withInspector: bool = false): Vec<Source>
```

Sources for the existing GizApp asset graph. HOST is the runtime's one Wasm loader (wasm.mjs), which the app supplies as it
does to App.client: it belongs to the runtime, not to this library.

Effects: fail, alloc.

### `resources`

```gizlang
function resources(prefix: string, files: Vec<File>, recipe: string, suffix: string = ""): Vec<Resource>
```

FILES as resources of the asset graph under PREFIX, their names in lower case and ended by SUFFIX (an extension for
a name without one: the graph serves a file by it), made by RECIPE.

Effects: fail, alloc.

### `urls`

```gizlang
function urls(graph: Graph, prefix: string, files: Vec<File>, suffix: string = ""): string
```

The JSON object of the names of FILES and their URLs in GRAPH under PREFIX: what <Surface sounds> and <Surface files>
take.

Effects: fail, alloc.

### `serve`

```gizlang
function serve(game: Served): i64
```

Serves the one game page (components/Game.ghtml: Save, Load, Full screen and Mute over the surface) with the game as
WebAssembly (build/APP.wasm, from `giz build --wasm`): the module, its sounds, its files and the page script in one
asset graph, offline after the first visit.

Effects: fail, read, write, console, io, alloc.

## Constants

### `ENTRY`

```gizlang
const ENTRY = "giz/surface.js"
```

The entry module of the reusable giz-surface element.

