# SDK: A project

> An AllyHub project is a folder, laid out as its people like, and a TypeScript (Node) project. AllyHub finds what it holds by two things only: its list of work, allyhub.yaml, and imports. This file covers the folders, the items, how a piece imports the SDK and other files, the words it reads, allyhub.config.ts and fonts.

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

```
package.json          depends on allyhub and @allyhub/sdk
tsconfig.json         the compiler's settings: the SDK's types
allyhub.yaml          the work a person sees: each piece's kind, file and title
allyhub.config.ts     the project's settings, the look, fonts (optional)
AGENTS.md, CLAUDE.md  the project's standing instructions (CLAUDE.md is @AGENTS.md)
.gitignore            node_modules/ and .allyhub/
assets/               files used as they are: media/, data/, text/, fonts/
components/           code several items share
.allyhub/             this computer's own, never shared
```

Only the dot folders and Node's own files are fixed places. `assets/` and `components/` are where AllyHub's tools put what they fetch or add (`allyhub add`); the build follows imports, not folders.

## `package.json`

- A folder is a project when its `package.json` depends on `allyhub` or `@allyhub/sdk`, or it has an `allyhub.config.*`. A command works on the nearest one at or above where it runs. The smallest project is a folder with an `allyhub.config.ts` and no `package.json`: the CLI brings `@allyhub/sdk` (and its subpaths) to a project that does not install it.
- The SDK and the CLI are one version. A project whose SDK is another version than the CLI that builds it is AK-B008; a `package.json` that declares AllyHub's packages before `npm install` has installed them is AK-B009, and nothing is built.
- A piece may import any package `package.json` declares and `npm install` installed. An import of an undeclared package, a file outside the project or a URL is AK-B005. `three` (with `three/addons/…`), `@allyhub/model` and `@allyhub/scenery-host/layer` are lent by the CLI unless the project declares its own.
- `npm create allyhub@latest <folder>` starts a project with these files.

## `tsconfig.json`

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "types": ["@allyhub/sdk/client", "allyhub/client"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true
  },
  "include": ["**/*.ts", ".allyhub/cache/types"],
  "exclude": ["node_modules"]
}
```

- `@allyhub/sdk/client` types the imports the build understands ([Media and data](#media-and-data)); `allyhub/client`, the packages the build lends by name (`@allyhub/scenery-host/layer`, `@allyhub/model`), from the project's `allyhub`.
- Every build (`allyhub check`, `render`, `dev`…) writes `.allyhub/cache/types/messages.d.ts`, the default language's message keys as types: `s()` then autocompletes keys and a wrong key fails `tsc`. `**/*.ts` does not enter folders that start with a dot, so the folder is listed in `include`. Without it, any string is a key.
- A `vite.config.ts` of the project's own is read: its `plugins`, `resolve`, `css`, `define`, `json`, `assetsInclude` and `oxc` apply after AllyHub's. Everything else is AllyHub's.

## `.allyhub/`

This computer's own: never shared, rebuilt as needed. Nothing a piece imports may live there.

| Folder | What is in it |
| --- | --- |
| `.allyhub/work/` | The agent's working files, free to throw away: frame sheets, cut sheets, references (`reference/`) |
| `.allyhub/out/` | Renders and exports, by the item's id |
| `.allyhub/cache/` | What the tools rebuild: builds, the media index (face tracks, mattes, levels), the part cache, types |
| `.allyhub/trash/` | What a person deleted in an editor, kept until they empty it |

## Items

An item is a piece of work a person sees: a file of a kind, named by the project's list, `allyhub.yaml` at its root. Files are yours to name and place; the list says what a person sees in Studio and `allyhub dev`, in its order, under its headings:

```yaml
work:
  - group: Launch
    items:
      - kind: video
        file: launch/film.ts
        title: Launch film, 30 s
      - kind: video
        file: launch/vertical/film.ts
      - kind: slides
        file: decks/seed.ts
  - kind: doc
    file: notes/brief.mdx
```

| Kind | Item | Its file holds |
| --- | --- | --- |
| `video` | A video | `export default video({ … })` ([video.md](https://allyhub.com/docs/reference/sdk/video.md)) |
| `slides` | A deck | `export default presentation({ slides, script, size }, (prs) => { … })` from `@allyhub/sdk/slides`, naming its slides file and its script ([slides.md](https://allyhub.com/docs/reference/sdk/slides.md)) |
| `image` | An image | `export default image({ script, boards })` from `@allyhub/sdk/image`, naming its script ([image.md](https://allyhub.com/docs/reference/sdk/image.md)) |
| `scenery` | A 3D scenery | `export default defineScenery({ … })` ([scenery.md](https://allyhub.com/docs/reference/sdk/scenery.md)) |
| `model` | A 3D model | `export default defineModel(build)` ([modeling.md](https://allyhub.com/docs/reference/sdk/modeling.md)) |
| `doc` | A doc | The doc itself, MDX ([docs.md](https://allyhub.com/docs/reference/sdk/docs.md)) |
| `sheet` | A sheet | The workbook, YAML: its sheets, cells, formulas, formats, names and checks; the CSV files it names hold its tables' rows, and the module its `code` names makes sheets ([sheets.md](https://allyhub.com/docs/reference/sdk/sheets.md)) |
| `website` | A website | JSON: how the web project in its folder is served, built and where the built site is ([websites.md](https://allyhub.com/docs/reference/sdk/websites.md)) |
| (none) | A canvas | A `.canvas` file, JSON Canvas: its editor opens it by its name, so its entry names no `kind` (`- file: boards/launch.canvas`) |

- Each piece has its `kind`, its `file` from the project's root and, if you want, a `title`: its name where people see it; without one, the title its file says, else the file's name. A `group` is a heading over its `items`, and groups nest. A new project's list is `work: []`; an item a person makes in Studio or `allyhub dev` is added at its end.
- A file the list does not name is yours alone: a scenery a video imports, a part, a helper, a draft. Nothing shows it to a person; the build still follows imports to it.
- An item's **id** is its file without its extension (`launch/film`), one in the project: it names the item in commands (`allyhub check launch/film`, `--piece launch/film`), in `.allyhub/out/` and in a share. A piece's `id` is its item's unless it sets `id` (lowercase letters, digits, `.`, `_` and `-`, with `/` between levels). Two pieces with one id are AK-B001. The id names its message keys (`launch/film` reads keys under `launch.film.`) and seeds its randomness.
- An item names the other files it uses, each from its own file's folder: a piece's script (`script: "./film.{locale}.yaml"`), a deck's slides file (`slides: "./deck.yaml"`), a sheet's code (`code: ./forecast.ts`) and its tables' CSV files. Nothing is found by a fixed name, so items share a folder freely, and two share a file only when both name it.
- `allyhub check` reports what is wrong with the list: a list it cannot read, a kind not loaded, a file listed with no kind that no editor opens by its name, or a file not there (AK-M002), one id twice (`a.ts` and `a.mdx`, or one file listed twice, AK-M003). Moving or renaming a listed file in Studio writes the list again, with the imports.

### The item's file

- The default export is `video({ … })` or `presentation(…)` written in the file, or a constant holding one (`const film = video({ … }); export default film`). A re-export, a factory function or a conditional is not followed (AK-M001).
- The module's top level runs in Node when the build reads the piece: what needs `window` or `document` goes in `parts` (or `pages`) or in a layer's `mount` and `render`. The top level may not use the network (AK-B003) and must finish (AK-B004).
- Every field of the piece but its functions (`parts`, `pages`, `covers`) is plain data (AK-M001).

## The SDK, bound to its module

A project file imports `@allyhub/sdk`; the build gives it the SDK with `video`, `part`, `take` and `footage` made for that file (`sdkFor({ file })`), and `@allyhub/sdk/slides` with `presentation` made for it. So a path a module writes as a string is relative to that module's own folder: `take("./vo/en.mp3")`, `footage("./broll.mp4")`, a part's `sounds`, `music`, `post.lut`, `.edits("./edits/host.json")`. A field keeps the folder it was written in when another piece spreads it. Nothing is a global.

An item uses another by an ordinary relative import. A piece in another format is an item of its own:

```ts file=launch/film.ts

  format: "16x9",
  music: "./music/bed.mp3",
  parts: ({ s }) => [
    part({ key: "hook", speech: say(s("launch.film.hook.say")) }),
  ],
});
```

```ts file=launch/vertical/film.ts


// Its music is still launch/music/bed.mp3; its id is launch/vertical/film.
```

- `video()` returns its fields as written, so a piece can spread another. A copy of a piece that sets `id` needs an `id` of its own.
- A video item can be shown inside another: `take(piece)`, `footage(piece)` and `ctx.video(piece, el)` ([footage.md](https://allyhub.com/docs/reference/sdk/footage.md), [speech.md](https://allyhub.com/docs/reference/sdk/speech.md)). A chain of videos that reaches itself is AK-M010.

## Words: scripts and shared text

All the text people see or hear is read with `s(key)` (the parts function's `ctx.s`). An item's own words are its **script**; words several items share are in `assets/text/<lang>.json`.

### Scripts

An item's script is one file per language, which the item names from its module's folder, with `{locale}` once in the file's name standing for each: `video({ script: "./film.{locale}.yaml", … })` reads `film.en.yaml`, `film.zh-cn.yaml`; a deck names its own in `presentation({ script })` ([slides.md](https://allyhub.com/docs/reference/sdk/slides.md#the-script)). A video without `script` has no words of its own.

```yaml
title: Tidyform launch
text:
  url: tidyform.app
parts:
  - id: hook
    say: Tidyform makes forms that fill themselves in, so you @{rest}only ask what you don't know.
    screen:
      line: Forms that fill themselves in.
  - id: how
    screen:
      steps:
        - Paste your form link
        - We match the answers you have
  - id: quote
    say: Northwind cut their form from <12|twelve> fields to <3|three>.
```

The script becomes messages under the piece's prefix (its id with `/` as `.`):

| In the script | Its key |
| --- | --- |
| `title` | `<prefix>.title`, the piece's title |
| `text.<name>` | `<prefix>.<name>` |
| `parts[].say` | `<prefix>.<part>.say` |
| `parts[].screen.<name>` | `<prefix>.<part>.<name>`; names nest, a list is numbered (`<prefix>.how.steps.0`) |
| `slides[].text.<name>` | `<prefix>.<slide>.<name>`, a deck's shape's words ([slides.md](https://allyhub.com/docs/reference/sdk/slides.md)) |
| `boards[].text.<name>` | `<prefix>.<board>.<name>`, an image's layer's words ([image.md](https://allyhub.com/docs/reference/sdk/image.md)) |

- A row's `id` is a part's `key`; a row has `id`, `say` and `screen`, nothing else. A row for a part the video does not have yet is allowed. A video's words are under `parts`, a deck's under `slides`, an image's under `boards` (`id` and `text`), each by its kind's own name for what it is made of.
- A `say` is one line, or a plural: it may hold anchors (`@{name}`) and text shown one way and said another (`<12|twelve>`) ([speech.md](https://allyhub.com/docs/reference/sdk/speech.md)). A text on screen is a string, `{ display, speak }`, a plural, a list, or texts by name.
- A file that is not YAML or not a script, and a key made twice, are AK-M007. A script no item names is not read.

### `assets/text/<lang>.json`

Flat keys, in inlang's message format (`allyhub.config.ts`'s `text` names another folder):

```json
{
  "brand.tagline": "Forms that fill themselves in.",
  "brand.legal": { "display": "© 2026 Tidyform", "speak": "Tidyform" },
  "pricing.greeting": "Hello, {name}",
  "pricing.count": [
    {
      "declarations": ["input count", "local n = count: plural"],
      "selectors": ["n"],
      "match": {
        "n=0": "No plans yet",
        "n=one": "{count} plan",
        "n=other": "{count} plans"
      }
    }
  ]
}
```

A key is segments of letters, digits, `_` and `-` joined by dots. A value is a string, `{ display, speak }`, or a message with variants (one `{ declarations, selectors, match }` in a list); `{name}` is a variable. A file that does not match is AK-M006.

### Reading text

| Call | Returns |
| --- | --- |
| `s(key, hint?)` | The text in the combo's language; `display` of a `{ display, speak }` pair |
| `s.list(prefix, hint?)` | `prefix.0`, `prefix.1`, … in order; deeper keys make objects (`plans.0.name`). `s.list<Plan>(prefix)` names the item type |
| `s.with(key, inputs, hint?)` | The text with its `{name}` variables filled, and a plural's or a selection's variant picked |

- `hint` is `{ max?, note? }`: a length budget and a note for whoever writes the text. It changes nothing.
- A key missing in the combo's language falls back to the default language (AK-S002, a warning); missing there too, it is `""` (AK-S001).
- A piece's languages are its script's and `assets/text/`'s, ordered with `allyhub.config.ts`'s `locales` first, else `en`; a piece's `matrix.dims.lang` narrows them ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)). Each language is a combo of the piece.
- A line may mark stretches: `**strong**`, `*em*`, `~~struck~~`, `` `code` ``. `s()` returns the line as written; `readMarks`, `markRuns` and `withoutMarks` read it, and `marked()` from `@allyhub/sdk/dom` draws it ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md)).
- Text written in code is drawn as written, in every language.

## Media and data

A file is used by importing it, by a string path relative to the module that names it, or by `ctx.asset(path)` and `ctx.data(path)` for a path made at run time (relative to the piece's file).

A share of one item serves only what the item reaches: the files its kind's build lists for it (its file, its script, a deck's slides file, a sheet's code and tables, a doc's pictures and sources), what its code imports, what its slides show, and what a path named at run time read when the check last loaded it, never its folder's other files. A file named only at run time is in its share once the check has run since.

```ts file=launch/plans/plans.ts


  parts: () =>
    plans.map((plan, i) =>
      part({
        key: `plan-${String(i)}`,
        layers: [
          custom({
            mount(el) {
              const img = document.createElement("img");
              img.src = String(logo); // a media value as a string is its url
              el.append(img, String(plan.name));
            },
            render() {},
          }),
        ],
      }),
    ),
});
```

- **Media** (pictures `png jpg jpeg webp gif svg avif`; sound `mp3 wav m4a ogg aac flac`; video `mp4 webm mov m4v qt`; fonts `woff2 woff ttf otf`; 3D `glb gltf bin ktx2`, environments `hdr exr`) imports as a `MediaInfo`: `path` from the project's root, `sha256`, `kind`, `width` and `height`, `duration`, `audio`, and what the build measured (`words`, `loudness`, `tempo`, `faces`, `matte`…). `url` is where the stage loads it, valid only at run time; a media value turned into a string is its `url` (`img.src = logo`).
- **Beside a media file**, files of the same name add to it: `<name>.words.json` (its word times: the file is a take, [speech.md](https://allyhub.com/docs/reference/sdk/speech.md)), `<name>.elements.json` (a screenshot's named element boxes, `elements`), `<file>.gen.json` (how the file was made: `gen`; move it with its file).
- **Data**: CSV imports as an array of objects keyed by the header row, a column whose every value is a number as numbers; YAML as its value; JSON as usual.
- A file that is not there is AK-A001; one of the wrong kind AK-A003; a picture on the stage that does not load AK-A005.

## `allyhub.config.ts`

Optional. Its default export is `defineConfig(…)`:

```ts file=allyhub.config.ts

  locales: ["en", "zh-cn"],
  fonts: ["@fontsource/space-grotesk/400.css", "./assets/fonts/brand.css"],
  look: {
    color: { accent: "#0f766e", bg: "#fbf8f3" },
    font: {
      display: '"Space Grotesk", "Inter Variable", "Noto Sans SC", sans-serif',
    },
    sfx: { ding: "assets/media/sfx/ding.wav" },
  },
  defaults: { format: "16x9", part: { lead: 0.15, tail: 0.4 } },
});
```

| Field | What it is |
| --- | --- |
| `locales` | The project's languages (BCP 47), the first its base; default the languages its words are in, `en` first |
| `fonts` | Font stylesheets every stage loads, each named as an import from the project's root ([Fonts](#fonts)) |
| `text` | The folder of the shared words; default `assets/text` |
| `look` | `{ color?, font?, motion?, sfx? }`, laid over the built-in `clean` look ([video.md](https://allyhub.com/docs/reference/sdk/video.md#the-look)) |
| `defaults` | `{ format?, part?: { dur?, lead?, tail? } }`: what every video starts from; a video's own `defaults.part` is over it |

## Fonts

The stage draws offline, so it draws only fonts that are files: its own, and the stylesheets a project brings.

- **Built in**: `"Inter Variable"` (Latin, Greek, Cyrillic, Vietnamese), `"Noto Sans SC"` (Chinese, 400 and 700) and `"Noto Color Emoji"` (the look's `font.emoji`). The `clean` look's `mono` is the computer's own monospace font, which differs between computers: bring one for code.
- **Imported by code**: install a font package and import its stylesheet in a piece or a module its pieces share (`import "@fontsource/space-grotesk/400.css"`), or import a stylesheet of `@font-face` rules beside the font files by a relative path. The package must be declared (AK-B005).
- **Listed in `allyhub.config.ts`**: `fonts` loads stylesheets on every stage, so the look can name a family no piece imports. An entry that names no file is AK-A001.
- A declared face costs nothing until text needs it: before the layers mount, the stage loads the faces of the families the look, the stylesheets and the layers' props name that cover a character of the piece's text; after mount, what the text on the stage asks for. A family that is not loaded falls to the next one, and a weight or style its faces lack is faked by the browser: both are AK-L006. A character no loaded font has is AK-L003.
