# SDK: The contract

> What the build, the check and the render rely on. Everything else is the piece's own choice.

Source: https://allyhub.com/docs/reference/sdk/contract · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

## A frame depends only on its time

- A piece is drawn in a page, a moment at a time, in any order: the check draws moments out of order and compares them with the same moments drawn in order (AK-D002), and the render draws parts on several pages at once and keeps what it drew in the part cache.
- A layer's `mount` lays it out once; its `render(el, t, …)` sets every property that moves from `t` alone ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md)). Nothing may carry state from one `render` call to the next. A deck mounts a slide's components when the slide is shown and may let the slide go and mount them again later, on a new element: what `mount` made that the page does not free with the element (a WebGL context, a worker, a timer) is let go in `unmount(el, …)`, and nothing is carried from one mount to the next.
- Piece code sees the moment's clock, not the wall's: `Date`, `Date.now()` and `performance.now()` read the moment being drawn (time 0 is 2026-01-01T00:00:00Z); `Math.random()` and `crypto.getRandomValues()` are seeded by the piece's id, the combo, the part and the frame; `requestAnimationFrame` callbacks run at the moment; `setTimeout` and `setInterval` never fire. Use `rand(seed)` and the noise functions for randomness of your own.
- CSS animations and transitions run on the browser's clock: never let them drive the picture.
- Work a layer must finish before anything is drawn (a 3D scenery's build, a picture decoding) goes through `ctx.wait(promise)`. Loading may take `loadLimit` seconds (AK-P002), one moment `seekLimit` seconds (AK-P003) ([defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md)).
- A part is rendered once and reused in every combo that has it: a layer reads the combo's dimensions and its own part's slot, never another slot's pick (AK-X005, [batches.md](https://allyhub.com/docs/reference/sdk/batches.md)).

## It is drawn offline

- Fonts, pictures, footage, music and data are files in the project, imported or named by paths relative to the module that names them ([project.md](https://allyhub.com/docs/reference/sdk/project.md)). A request the stage does not serve is AK-N003; a network request while building is AK-B003.
- An import of a URL, of a file outside the project or of a package `package.json` does not declare is AK-B005.
- The module's top level runs in Node when the build reads a piece: only `parts`, `pages`, `covers` and a layer's `mount` and `render` touch `window` and `document`.
- A layer changes only its own element: a change to the page outside the stage is AK-R003, and a style value the browser does not accept is AK-R004.

## What goes wrong is a problem, not a wrong picture

- Every command reads the problems of each page it drew with and prints them, each under its rule: a layer that throws at 0.8 s (AK-R001), work it waits for that fails or does not settle, a picture that does not load (AK-A005), a 3D scenery that does not build (AK-W001). `ctx.report({ code, message })` reports one of a layer's own.
- A render does not make a file whose drawing raised a problem; it lists it as not made, with why, and keeps nothing of it in the part cache.
- What piece code prints with `console.log`, `info`, `warn`, `error` and `debug` is collected with where it ran (the module, a part, a layer, its moment) and printed by the commands after their own output. It changes no frame.

## Checks are for objective errors

`allyhub check` reports problems: what is wrong whatever the taste. Each has a rule, its code's letter its area:

| Codes | Area |
| --- | --- |
| `AK-M…` | An item, a file's format: a piece's fields, the list of work, scripts, messages, docs, sheets |
| `AK-B…` | The build: ids, network, time, imports, the installed SDK |
| `AK-K…` | Parts: keys, a piece without parts |
| `AK-D…` | Determinism |
| `AK-T…` | Speech: word times, generated voices, ranges, word references, anchors, edits files |
| `AK-S…` | Text: a missing key (S001), a missing translation (S002, a warning) |
| `AK-A…` | Media and data files |
| `AK-G…` | An unknown format |
| `AK-P…` | Loading and drawing time |
| `AK-R…`, `AK-N…` | Run time: an exception, the page changed, a style refused; a request blocked |
| `AK-L…` | Layout and fonts: text cut at the frame's edge, missing glyphs, fallback fonts (warnings) |
| `AK-X…` | The matrix and its combos |
| `AK-W…` | 3D sceneries |

An error must be fixed: a render will not make a file with one. A warning is reported and the render goes on. What is a matter of judgment (text near a face, a loudness step between parts, a still stretch, a cut seam) is never a problem: it is a fact, with its numbers, which `allyhub inspect` prints for the agent to weigh.

## Defaults can be changed

Every default of the piece API has an option that changes it: [defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md) lists them with the option. A command's defaults are in `allyhub help <command>`.
