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.
package.json depends on allyhub and @allyhub/sdktsconfig.json the compiler's settings: the SDK's typesallyhub.yaml the work a person sees: each piece's kind, file and titleallyhub.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 sharedOnly 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
Section titled “package.json”- A folder is a project when its
package.jsondepends onallyhubor@allyhub/sdk, or it has anallyhub.config.*. A command works on the nearest one at or above where it runs. The smallest project is a folder with anallyhub.config.tsand nopackage.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.jsonthat declares AllyHub’s packages beforenpm installhas installed them is AK-B009, and nothing is built. - A piece may import any package
package.jsondeclares andnpm installinstalled. An import of an undeclared package, a file outside the project or a URL is AK-B005.three(withthree/addons/…),@allyhub/modeland@allyhub/scenery-host/layerare lent by the CLI unless the project declares its own. npm create allyhub@latest <folder>starts a project with these files.
tsconfig.json
Section titled “tsconfig.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/clienttypes the imports the build understands (Media and data);allyhub/client, the packages the build lends by name (@allyhub/scenery-host/layer,@allyhub/model), from the project’sallyhub.- 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 failstsc.**/*.tsdoes not enter folders that start with a dot, so the folder is listed ininclude. Without it, any string is a key. - A
vite.config.tsof the project’s own is read: itsplugins,resolve,css,define,json,assetsIncludeandoxcapply after AllyHub’s. Everything else is AllyHub’s.
.allyhub/
Section titled “.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 |
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:
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) |
slides |
A deck | export default presentation({ slides, script, size }, (prs) => { … }) from @allyhub/sdk/slides, naming its slides file and its script (slides.md) |
image |
An image | export default image({ script, boards }) from @allyhub/sdk/image, naming its script (image.md) |
scenery |
A 3D scenery | export default defineScenery({ … }) (scenery.md) |
model |
A 3D model | export default defineModel(build) (modeling.md) |
doc |
A doc | The doc itself, MDX (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) |
website |
A website | JSON: how the web project in its folder is served, built and where the built site is (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, itsfilefrom the project’s root and, if you want, atitle: its name where people see it; without one, the title its file says, else the file’s name. Agroupis a heading over itsitems, and groups nest. A new project’s list iswork: []; an item a person makes in Studio orallyhub devis 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’sidis its item’s unless it setsid(lowercase letters, digits,.,_and-, with/between levels). Two pieces with one id are AK-B001. The id names its message keys (launch/filmreads keys underlaunch.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 checkreports 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.tsanda.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
Section titled “The item’s file”- The default export is
video({ … })orpresentation(…)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
windowordocumentgoes inparts(orpages) or in a layer’smountandrender. 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
Section titled “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:
import { part, say, video } from "@allyhub/sdk";
export default video({ format: "16x9", music: "./music/bed.mp3", parts: ({ s }) => [ part({ key: "hook", speech: say(s("launch.film.hook.say")) }), ],});import { video } from "@allyhub/sdk";
import film from "../film.ts";
// Its music is still launch/music/bed.mp3; its id is launch/vertical/film.export default video({ ...film, format: "9x16" });video()returns its fields as written, so a piece can spread another. A copy of a piece that setsidneeds anidof its own.- A video item can be shown inside another:
take(piece),footage(piece)andctx.video(piece, el)(footage.md, speech.md). A chain of videos that reaches itself is AK-M010.
Words: scripts and shared text
Section titled “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
Section titled “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). A video without script has no words of its own.
title: Tidyform launchtext: url: tidyform.appparts: - 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) |
boards[].text.<name> |
<prefix>.<board>.<name>, an image’s layer’s words (image.md) |
- A row’s
idis a part’skey; a row hasid,sayandscreen, nothing else. A row for a part the video does not have yet is allowed. A video’s words are underparts, a deck’s underslides, an image’s underboards(idandtext), each by its kind’s own name for what it is made of. - A
sayis one line, or a plural: it may hold anchors (@{name}) and text shown one way and said another (<12|twelve>) (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
Section titled “assets/text/<lang>.json”Flat keys, in inlang’s message format (allyhub.config.ts’s text names another folder):
{ "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
Section titled “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 |
hintis{ 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 withallyhub.config.ts’slocalesfirst, elseen; a piece’smatrix.dims.langnarrows them (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,markRunsandwithoutMarksread it, andmarked()from@allyhub/sdk/domdraws it (layers.md). - Text written in code is drawn as written, in every language.
Media and data
Section titled “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.
import { custom, part, video } from "@allyhub/sdk";
import logo from "../../assets/media/logo.svg";import plans from "../../assets/data/plans.csv";
export default video({ 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; soundmp3 wav m4a ogg aac flac; videomp4 webm mov m4v qt; fontswoff2 woff ttf otf; 3Dglb gltf bin ktx2, environmentshdr exr) imports as aMediaInfo:pathfrom the project’s root,sha256,kind,widthandheight,duration,audio, and what the build measured (words,loudness,tempo,faces,matte…).urlis where the stage loads it, valid only at run time; a media value turned into a string is itsurl(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),<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
Section titled “allyhub.config.ts”Optional. Its default export is defineConfig(…):
import { defineConfig } from "@allyhub/sdk";
export default defineConfig({ 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) |
text |
The folder of the shared words; default assets/text |
look |
{ color?, font?, motion?, sfx? }, laid over the built-in clean look (video.md) |
defaults |
{ format?, part?: { dur?, lead?, tail? } }: what every video starts from; a video’s own defaults.part is over it |
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’sfont.emoji). Thecleanlook’smonois 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-facerules beside the font files by a relative path. The package must be declared (AK-B005). - Listed in
allyhub.config.ts:fontsloads 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.