@allyhub/sdk 0.1.0-alpha.8 → 0.2.0-next.0

package/dist/phone.d.ts

@@ -0,0 +1,26 @@
+import { type Deeper, type PhoneCamera as SceneryPhone } from "@allyhub-next/scenery";
+import type { CaptureOptions, MotionBlur } from "@allyhub-next/video-core";
+export type { Deeper } from "@allyhub-next/scenery";
+/** What a phone's camera is, as the options of each mechanism. */
+export interface PhoneCamera extends SceneryPhone {
+    /** video({ capture }): the marks on the picture it records. */
+    capture: CaptureOptions;
+    /** video({ motionBlur }): the shutter's blur of what moves (a scenery's camera too). */
+    motionBlur: MotionBlur;
+}
+/**
+ * A phone's main camera filming a screen or a room indoors, held in a
+ * hand: a 26 mm lens on its 4:3 frame at f/8 equivalent (f/1.8 on its
+ * small sensor), a 12 MP sensor, a hand whose tremor its stabiliser mostly
+ * takes out, focus that hunts after a cut, a reframe or a jolt, exposure
+ * that follows a new framing late; grain stronger in the shadows and a
+ * little coloured, a soft lens and the phone's sharpening; a half-frame
+ * shutter.
+ */
+export declare const PHONE_CAMERA: PhoneCamera;
+/**
+ * PHONE_CAMERA with any of its values changed (`{ hand: { tremor: { angle:
+ * 0.2 } } }` changes that one and keeps the rest).
+ */
+export declare function phoneCamera(over?: Deeper<PhoneCamera>): PhoneCamera;
+//# sourceMappingURL=phone.d.ts.map

package/dist/phone.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{PHONE_CAMERA as u}from"@allyhub-next/scenery";export const PHONE_CAMERA={...u,capture:{soften:.8,grain:{amount:.02,size:1.5,shadows:2,highlights:.6,chroma:.4,chromaSize:3},sharpen:.25,vignette:.15,bloom:{threshold:.8,radius:14,strength:.25}},motionBlur:{samples:8,shutter:.5}};const i=t=>typeof t=="object"&&t!==null&&!Array.isArray(t);function s(t,r){if(!i(t)||!i(r))return r===void 0?t:r;const o={...t};for(const[n,e]of Object.entries(r))o[n]=e===void 0?t[n]:s(t[n],e);return o}export function phoneCamera(t={}){return s(PHONE_CAMERA,t)}

package/dist/piece.d.ts

@@ -1,64 +1,135 @@
-import { type OutputDefinition, type PagedOptions, type PagedOutput, type PartSpec, type PieceDefinition, type ProjectConfig, type PieceContext as StagePieceContext, type VideoOptions as StageVideoOptions, type VideoOutput } from "@allyhub/engine/stage";
-import type { FormatEntry, Matrix } from "@allyhub/engine/stage";
+import { PIECE_BRAND, type PieceDefinition, type PagedOptions, type PartSpec, type PieceContext as StagePieceContext, type PieceWritten, type VideoOptions as StageVideoOptions } from "@allyhub-next/video-core";
+import type { FormatEntry, Matrix } from "@allyhub-next/video-core";
+import type { ConfigSchema } from "@allyhub-next/formats";
+import type { VideoConfigSchema } from "@allyhub-next/video-core";
+import type { z } from "zod";
 import type { MessageReader } from "./messages.js";
-export type { Combo, Dims, Format, FormatEntry, FormatSpec, Matrix, MediaRef, MessageHint, MotionBlur, MusicOptions, PagedOptions, PostProcess, PieceDefinition, ProjectConfig, } from "@allyhub/engine/stage";
+import type { Written } from "./written.js";
+export type { Combo, Dims, Format, FormatEntry, FormatSpec, Matrix, MediaRef, MessageHint, MotionBlur, MusicOptions, PagedOptions, PagedPiece, PostProcess, CaptureOptions, PieceDefinition, PieceWritten, VideoPiece, } from "@allyhub-next/video-core";
 /**
- * What every output's build function receives, with message keys typed by the generated .local/cache/types.
+ * allyhub.config.ts as a project writes it: the project's settings
+ * (@allyhub-next/formats) with the look and the defaults every video
+ * starts from (@allyhub-next/video-core).
+ */
+export type ProjectConfig = Omit<z.input<typeof ConfigSchema>, "look" | "defaults"> & z.input<typeof VideoConfigSchema>;
+/**
+ * What a piece's parts (or pages) function receives, with message keys
+ * typed by the generated .allyhub/cache/types.
  */
 export interface PieceContext extends Omit<StagePieceContext, "s"> {
     s: MessageReader;
 }
-/** A video output's build function: the parts, in order. */
+/** A video's parts function: the parts, in order. */
 export type VideoBuild = (ctx: PieceContext) => PartSpec[] | Promise<PartSpec[]>;
+/** A deck's pages function: the pages, in order. */
+export type PagedBuild = (ctx: PieceContext) => PartSpec[] | Promise<PartSpec[]>;
 export interface VideoOptions extends Omit<StageVideoOptions, "covers"> {
     /** Cover parts (optional): drawn for the cover image. */
     covers?(ctx: PieceContext): PartSpec[] | Promise<PartSpec[]>;
 }
-export interface PieceOptions<O extends Record<string, OutputDefinition>> {
-    /** A stable identity. Default: the file's path in the project (without the extension). */
+/** What every piece has, whatever it makes. */
+export interface PieceOptions {
+    /** A stable identity. Default: the item's folder, from the project's root. */
     id?: string;
     /** A name for people. Default: messages `<id>.title`, else the file name. */
     title?: string | Record<string, string>;
     /**
-     * What every output is rendered as, each combo in each format: presets
-     * (16x9, 9x16, 1x1, 4x5), platform profiles (tiktok, reels…) or
-     * WIDTHxHEIGHT pixels; a4 and letter for paged outputs only. An entry
-     * may be { format, safe, maxDuration, loudness }: that format with its
-     * covered edges (any format), longest length and loudness (a platform
-     * profile) changed; its name is still the format's. Default:
-     * allyhub.config.ts `defaults.formats`, else ["16x9"].
+     * What it is rendered as, one format: a preset (16x9, 9x16, 1x1, 4x5),
+     * a platform profile (tiktok, reels…) or WIDTHxHEIGHT pixels; a4 and
+     * letter for slides only. It may be { format, safe, maxDuration,
+     * loudness }: that format with its covered edges (any format), longest
+     * length and loudness (a platform profile) changed; its name is still
+     * the format's. Another format is a piece of its own, which imports what
+     * it shares (`video({ ...film, id, format })` reuses another piece's
+     * parts, their paths still relative to where they were written).
+     * Default: allyhub.config.ts `defaults.format`, else "16x9".
      */
-    formats?: FormatEntry[];
+    format?: FormatEntry;
     /**
      * The matrix: `dims` are dimensions and their values, crossed in full;
-     * each combo is one value per dimension (`ctx.combo`). `lang` picks
-     * assets/text/<lang>.json (the first is the default); without it, the
-     * languages are the messages files. `size` and `format` are not
-     * dimensions: the frame is `formats`.
+     * each combo is one value per dimension (`ctx.combo`). `lang` picks the
+     * language of the item's scripts and assets/text/<lang>.json (the first
+     * is the default); without it, the languages are the project's. `size`
+     * and `format` are not dimensions: the frame is `format`.
      */
     matrix?: Matrix;
     /** Any key-values: the platform filters and groups by them. */
     meta?: Record<string, unknown>;
-    outputs: O;
 }
-/** One piece of content: the default export of its module. */
-export declare function definePiece<O extends Record<string, OutputDefinition>>(opts: PieceOptions<O>): PieceDefinition & {
-    outputs: O;
+export interface VideoPieceOptions extends PieceOptions, VideoOptions {
+    /**
+     * The parts, in order. A method, as `covers` is, so a video is the
+     * engine's VideoPiece though its context's messages are typed narrower.
+     */
+    parts(ctx: PieceContext): PartSpec[] | Promise<PartSpec[]>;
+}
+export interface SlidesOptions extends PieceOptions, PagedOptions {
+    /**
+     * The pages, in order. Pages are made like a video's parts (part() with
+     * layers), each with a key unique in the deck; a page is drawn at its
+     * still moment. A method, as a video's parts is.
+     */
+    pages(ctx: PieceContext): PartSpec[] | Promise<PartSpec[]>;
+}
+/**
+ * A video as video() makes it: its fields as written, so another piece can
+ * spread it into its own (`video({ ...film, format: "9x16" })`), and where
+ * it was written.
+ */
+export type Video = VideoPieceOptions & {
+    readonly [PIECE_BRAND]: true;
+    readonly kind: "video";
+    readonly written: PieceWritten;
 };
-/** A video output: the function returns the parts, in order. */
-export declare function video(build: VideoBuild, options?: VideoOptions): VideoOutput;
-/** A paged output's build function: the pages, in order. */
-export type PagedBuild = (ctx: PieceContext) => PartSpec[] | Promise<PartSpec[]>;
+/** A deck as slides() makes it. */
+export type Slides = SlidesOptions & {
+    readonly [PIECE_BRAND]: true;
+    readonly kind: "paged";
+    readonly written: PieceWritten;
+};
+/**
+ * Another item's piece, as what shows or plays it takes it: the SDK's own
+ * video() or slides(), whose ctx reads the project's typed messages, or the
+ * engine's piece. The engine's ctx is wider than the typed one, so a piece
+ * video() made is not the engine's type, though it is the same object.
+ */
+export type ItemPiece = PieceDefinition | Video | Slides;
+/** A video item's piece: the SDK's video(), or the engine's piece. */
+export type VideoItem = PieceDefinition | Video;
+/** Whether a value is a piece video() or slides() made. */
+export declare function isItemPiece(v: unknown): v is ItemPiece;
+/**
+ * The same piece as the engine reads it: the ctx its parts get is the
+ * engine's, which the SDK's typed messages only narrow.
+ */
+export declare function enginePiece(p: ItemPiece): PieceDefinition;
+/** A video: the default export of an item's video.ts. Its function returns its parts, in order. */
+export type VideoFn = (opts: VideoPieceOptions) => Video;
+/** A deck: the default export of an item's slides.ts. */
+export type SlidesFn = (opts: SlidesOptions) => Slides;
+/**
+ * video() for the module `at` names. Its music's and its LUT's paths are
+ * from that module's folder, also once spread into another piece: a field
+ * keeps the folder it was written in while its value is the same.
+ */
+export declare const videoFor: (at: Written) => VideoFn;
+/**
+ * slides() for the module `at` names: pages of one format, each one still
+ * frame: a single image, a carousel, slides, a PDF document; the default
+ * export of an item's slides.ts. `notes: true` reads each page's speaker
+ * notes from `<prefix>.<page>.notes`.
+ */
+export declare const slidesFor: (at: Written) => SlidesFn;
+/**
+ * Gone: an item's entry file exports one video (`video({ … })`) or one
+ * deck (`slides({ … })`). Calling it says so.
+ */
+export declare const definePiece: (opts: unknown) => never;
 /**
- * Pages of one format, each one still frame: a single
- * image, a carousel, slides, a PDF document. Pages are made like a video's
- * parts (part() with layers), each with a key unique in the output;
- * a page is drawn at its still moment. `format` fixes the frame ("a4",
- * "letter", "1200x630", "16x9"…); without it the output renders in each
- * of the piece's formats. `notes: true` reads each page's speaker notes from
- * `<prefix>.<page>.notes`.
+ * Gone: a deck is `slides({ format, pages })`, an item's slides.ts.
+ * Calling it says so.
  */
-export declare function paged(build: PagedBuild, options?: PagedOptions): PagedOutput;
+export declare const paged: (build: unknown, opts?: unknown) => never;
 /** allyhub.config.ts: project defaults and the look (optional). */
 export declare function defineConfig(config: ProjectConfig): ProjectConfig;
 //# sourceMappingURL=piece.d.ts.map

package/dist/piece.js

@@ -1,38 +1,2 @@
-import { OUTPUT_BRAND, PIECE_BRAND, } from "@allyhub/engine/stage";
-/** One piece of content: the default export of its module. */
-export function definePiece(opts) {
-    return { [PIECE_BRAND]: true, ...opts };
-}
-/** A video output: the function returns the parts, in order. */
-export function video(build, options = {}) {
-    // The runtime's reader takes any string; the typed one only narrows keys.
-    return {
-        [OUTPUT_BRAND]: true,
-        kind: "video",
-        build: build,
-        options: options,
-    };
-}
-/**
- * Pages of one format, each one still frame: a single
- * image, a carousel, slides, a PDF document. Pages are made like a video's
- * parts (part() with layers), each with a key unique in the output;
- * a page is drawn at its still moment. `format` fixes the frame ("a4",
- * "letter", "1200x630", "16x9"…); without it the output renders in each
- * of the piece's formats. `notes: true` reads each page's speaker notes from
- * `<prefix>.<page>.notes`.
- */
-export function paged(build, options = {}) {
-    // The runtime's reader takes any string; the typed one only narrows keys.
-    return {
-        [OUTPUT_BRAND]: true,
-        kind: "paged",
-        build: build,
-        options,
-    };
-}
-/** allyhub.config.ts: project defaults and the look (optional). */
-export function defineConfig(config) {
-    return config;
-}
-//# sourceMappingURL=piece.js.map
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{PIECE_BRAND as c,isPieceDefinition as a}from"@allyhub-next/video-core";import{shapeProblem as p,voiceProblem as u}from"@allyhub-next/audio";const s=e=>{throw new Error(e)},m="An item's video.ts exports one video: export default video({ format, parts: (ctx) => [ part(…), … ] }). A second video (a cut-down, another format) is an item of its own, which imports what it shares.";export function isItemPiece(e){return a(e)}export function enginePiece(e){return e}const h=["music","post"];export const videoFor=e=>t=>{if((typeof t=="function"||typeof t.parts!="function")&&s(m),t.mic!==void 0){const i=u(t.mic);if(i!==void 0)throw new Error(`video: ${i}`)}const r=t.music;if(r!==void 0&&typeof r!="string"&&!("path"in r)){const i=Object.fromEntries(["filter","eq","compress"].filter(o=>r[o]!==void 0).map(o=>[o,r[o]])),n=p(i,!0);if(n!==void 0)throw new Error(`video: music: ${n}`)}const d=t.written?.paths,f={};for(const i of h){const n=t[i];if(n===void 0)continue;const o=d?.[i];f[i]=[n,o?.[0]===n?o[1]:e.base]}return{...t,[c]:!0,kind:"video",written:{file:e.file,...Object.keys(f).length>0?{paths:f}:{}}}},slidesFor=e=>t=>((typeof t=="function"||typeof t.pages!="function")&&s("An item's slides.ts exports one deck: export default slides({ format, pages: (ctx) => [ part(…), … ] }). Another deck (a handout in a4) is an item of its own, which imports what it shares."),{...t,[c]:!0,kind:"paged",written:{file:e.file}}),definePiece=()=>s("definePiece is gone: an item's entry file exports one piece, export default video({ format, parts: (ctx) => [ … ] }) in video.ts or slides({ format, pages: (ctx) => [ … ] }) in slides.ts, with what definePiece and its output had (id, format, matrix, music, mix…). Each of its other outputs is an item of its own, which imports what it shares."),paged=()=>s("paged() is gone: an item's slides.ts exports one deck, export default slides({ format, notes, pages: (ctx) => [ … ] }).");export function defineConfig(e){return e}

package/dist/props.d.ts

@@ -1,4 +1,4 @@
-import type { MediaKind, Preset, WordRef } from "@allyhub/engine/stage";
+import type { MediaKind, Preset, WordRef } from "@allyhub-next/video-core";
 declare const TIME: unique symbol;
 /**
  * A prop that is a moment (declared time()): seconds from the part's start

package/dist/props.js

@@ -1,35 +1,2 @@
-/** Text shown on screen: edited sentence by sentence, checked against its budget. */
-export const text = (o = {}) => ({
-    type: "text",
-    ...o,
-});
-/**
- * A moment: given as a word reference ("inbox", "inbox@2", "inbox+0.2") or
- * seconds from the part's start; the component receives seconds. Type the
- * prop as `Time`.
- */
-export const time = (o = {}) => ({
-    type: "time",
-    ...o,
-});
-/** Media: an import or ctx.asset(path). */
-export const asset = (o = {}) => ({
-    type: "asset",
-    ...o,
-});
-/** A look variable such as var(--ak-color-accent); never a literal color. */
-export const color = (o = {}) => ({
-    type: "color",
-    ...o,
-});
-export const number = (o = {}) => ({
-    type: "number",
-    ...o,
-});
-export const boolean = (o = {}) => ({
-    type: "boolean",
-    ...o,
-});
-export const list = (of, o = {}) => ({ type: "list", of, ...o });
-export const object = (fields, o = {}) => ({ type: "object", fields, ...o });
-//# sourceMappingURL=props.js.map
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export const text=(t={})=>({type:"text",...t}),time=(t={})=>({type:"time",...t}),asset=(t={})=>({type:"asset",...t}),color=(t={})=>({type:"color",...t}),number=(t={})=>({type:"number",...t}),boolean=(t={})=>({type:"boolean",...t}),list=(t,e={})=>({type:"list",of:t,...e}),object=(t,e={})=>({type:"object",fields:t,...e});

package/dist/scenery.d.ts

@@ -0,0 +1,2 @@
+export { PHONE_CAMERA, phoneCamera, type Deeper, type PhoneCamera, } from "./phone.js";
+//# sourceMappingURL=scenery.d.ts.map

package/dist/scenery.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export{PHONE_CAMERA,phoneCamera}from"./phone.js";

package/dist/text.js

@@ -1,38 +1,2 @@
-// Text for animation: a line a word or a character at a time, a number on
-// its way to its value.
-/** Splits text into words (whitespace dropped), characters, or by a separator. */
-export function splitText(text, by = "words") {
-    return by === "chars"
-        ? Array.from(text)
-        : by === "words"
-            ? text.split(/\s+/).filter(Boolean)
-            : text.split(by);
-}
-/**
- * A number counting to `value`, as text: `value` as it is written ("38%",
- * "$1,200.5M", "12,400") with its number `x` of the way from `from`, x
- * from 0 to 1. What is around the number stays, and so do its decimal
- * places and its thousands separators, so the text keeps its shape as it
- * counts. At x of 1 or more, and when `value` has no number, it is
- * `value` itself. `x` is yours to ease: countText("38%",
- * ease.outExpo(progress(t, 0.2, 1.4))).
- */
-export function countText(value, x, from = 0) {
-    const m = /^(\D*?)(-?[\d,]*\.?\d+)(.*)$/s.exec(value);
-    if (!m || x >= 1)
-        return value;
-    const digits = m[2] ?? "";
-    const decimals = digits.includes(".")
-        ? (digits.split(".")[1]?.length ?? 0)
-        : 0;
-    const to = Number(digits.replace(/,/g, ""));
-    const n = from + (to - from) * Math.max(0, x);
-    const shown = digits.includes(",")
-        ? n.toLocaleString("en-US", {
-            minimumFractionDigits: decimals,
-            maximumFractionDigits: decimals,
-        })
-        : n.toFixed(decimals);
-    return `${m[1] ?? ""}${shown}${m[3] ?? ""}`;
-}
-//# sourceMappingURL=text.js.map
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export function splitText(t,n="words"){return n==="chars"?Array.from(t):n==="words"?t.split(/\s+/).filter(Boolean):t.split(n)}export function countText(t,n,r=0){const i=/^(\D*?)(-?[\d,]*\.?\d+)(.*)$/s.exec(t);if(!i||n>=1)return t;const o=i[2]??"",s=o.includes(".")?o.split(".")[1]?.length??0:0,e=Number(o.replace(/,/g,"")),c=r+(e-r)*Math.max(0,n),l=o.includes(",")?c.toLocaleString("en-US",{minimumFractionDigits:s,maximumFractionDigits:s}):c.toFixed(s);return`${i[1]??""}${l}${i[3]??""}`}

package/dist/written.d.ts

@@ -0,0 +1,12 @@
+/** The module the SDK is bound to: its file, a project path ("" the project's root). */
+export interface SdkModule {
+    file: string;
+}
+/** A module's file and the folder its relative paths are from, both project paths. */
+export interface Written {
+    file: string;
+    base: string;
+}
+/** Where a module was written: its file in its one spelling, and its folder. */
+export declare function writtenIn(module: SdkModule): Written;
+//# sourceMappingURL=written.d.ts.map

package/dist/written.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{dirOf as i,projectPath as e}from"@allyhub-next/formats";export function writtenIn(r){const t=e(r.file);if(t.startsWith("/")||/^[A-Za-z]:/u.test(t)||t.split("/").includes(".."))throw new Error(`sdkFor: ${JSON.stringify(r.file)} is not a project path: a file's path from the project's root, such as "launch/film/video.ts".`);return{file:t,base:i(t)}}

package/docs/README.md

@@ -0,0 +1,18 @@
+# @allyhub/sdk docs
+
+What a piece is written with, for the version of the SDK installed beside them. Read the file a piece needs before writing it. Commands are not here: `allyhub help` lists them, `allyhub help <command>` says what one does and its options' defaults. Every export also has its documentation in JSDoc.
+
+- [project.md](project.md): a project's folders, items and their entry files, the SDK bound to the file that imports it, imports of media, data and other items, scripts and shared text, `allyhub.config.ts`, fonts.
+- [contract.md](contract.md): what the build, the check and the render rely on: a piece drawn from time alone, what piece code may not do, the rules a problem is reported under.
+- [video.md](video.md): `video()`, formats, `part()`, a part's length, layers and their stacking, transitions, the look, covers, the camera filming the picture, post.
+- [layers.md](layers.md): `defineComponent()` and its prop types, `custom()`, the layer's `ctx`, the DOM and layout helpers, animation, text, path, noise and input helpers, starter components.
+- [speech.md](speech.md): `take()`, `say()`, word references, anchors, shown and said text, captions, edits files.
+- [sound.md](sound.md): music, sound effects, the mix, the master, how the voice was recorded.
+- [footage.md](footage.md): `footage()` layers: placing, cropping, reframing, punch-ins, faces and mattes, the background behind the person, a video item inside another.
+- [slides.md](slides.md): `slides()`, pages, speaker notes, what a deck renders to.
+- [batches.md](batches.md): the matrix: dimensions, slots, pools, structures, rules, combos.
+- [scenery.md](scenery.md): 3D sceneries: `defineScenery()`, cameras and their moves, the hand that holds one, the `scenery()` layer and its screens.
+- [modeling.md](modeling.md): a prop modelled in code with `@allyhub-next/model` and put in a scenery.
+- [docs.md](docs.md): a doc, `doc.mdx`: its title, the Markdown and tags it reads, pictures and links, `comments.json`, check and render.
+- [sheets.md](sheets.md): a sheet, `sheet.csv` and `sheet.yaml`: column types and formats, `comments.json`, check, measure, import and render.
+- [defaults.md](defaults.md): every default of the piece API, generated from the code's constants, with the option that changes it.

package/docs/batches.md

@@ -0,0 +1,148 @@
+# Batches: the matrix
+
+A piece's `matrix` says which versions of it are made. Each version is a **combo**: one value per dimension and, when the piece has slots, a structure and one candidate per slot of it. Every combo renders in the piece's one format.
+
+## Dimensions
+
+`matrix.dims` are dimensions and their values, crossed in full: `{ lang: ["en", "zh-cn"], audience: ["dev", "ops"] }` makes four combos.
+
+- `lang` is the one dimension AllyHub reads: it picks each item's `script.<lang>.yaml` and `assets/text/<lang>.json`, the first value being the default language. Its values are lowercase language tags (`en`, `zh-cn`). Without `lang`, a piece's languages are the project's: the languages its scripts and shared text have, `allyhub.config.ts`'s `locales` first.
+- Other dimensions are the piece's: its parts function reads them from `ctx.combo`.
+- A name starts with a lowercase letter (then letters, digits, `_`, `-`); a value is letters, digits, `.`, `_`, `-`, each listed once. `size`, `format`, `piece`, `output`, `token`, `structure` and `id` name no dimension or slot. A wrong name or value is AK-M001.
+- A combo's **key** is its names sorted, each `name=value`, joined with commas: `audience=dev,lang=en` (`default` when there are none). It names the rendered files (`.allyhub/out/<piece>/video.<key>.mp4`) and filters commands' `--combo` (`--combo lang=zh-cn`).
+
+## Slots
+
+An ad is a structure of **slots** (a hook, a demo, a call to action), each with **candidates**. The matrix chooses which slot combinations to make; each chosen one is crossed with every combo of the dimensions.
+
+```ts file=ads/tidyform/video.ts
+import { footage, part, say, video } from "@allyhub/sdk";
+
+export default video({
+  format: "9x16",
+  maxDuration: 30,
+  matrix: {
+    dims: { lang: ["en"] },
+    slots: {
+      hook: [{ name: "price", tags: ["price"] }, "reaction", "question"],
+      demo: { pool: "./pool/demos" },
+      cta: ["trial", { name: "sale", tags: ["discount"] }],
+    },
+    structures: { classic: ["hook", "demo", "cta"], short: ["hook", "cta"] },
+    pick: 6,
+    seed: 1,
+    differ: { slots: 2, first: ["hook"] },
+    rules: [{ if: { hook: "#price" }, require: { cta: "#discount" } }],
+  },
+  parts: ({ s, combo, pool }) => {
+    const hook = part({
+      key: "hook",
+      speech: say(s(`ads.tidyform.hook.${combo["hook"] ?? ""}`)),
+    });
+    const cta = part({
+      key: "cta",
+      speech: say(s(`ads.tidyform.cta.${combo["cta"] ?? ""}`)),
+    });
+    if (combo["structure"] === "short") return [hook, cta];
+    return [
+      hook,
+      part({ key: "demo", dur: 4, layers: [footage(pool("demo"))] }),
+      cta,
+    ];
+  },
+});
+```
+
+| Field | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `slots` | `{ slot: candidates }` | none | Names, `{ name, tags }`, or a pool `{ pool, tags? }` ([below](#pools)) |
+| `structures` | `{ name: slots[] }` | one structure of every slot, in order | Orders of slots. With it, `combo.structure` names a combo's structure. Every slot is in some structure |
+| `pick` | 1 to 10000 | every combination the rules allow | How many slot combinations sampling chooses |
+| `seed` | number or string | 1 | Decides between equally good choices |
+| `differ` | `{ slots?, first? }` | none | Any two chosen combos differ in at least `slots` slots (another structure counts as one); `first`: their openings differ, the first n slots of each structure, or these slots |
+| `rules` | `[{ if?, require?, exclude? }]` | none | Over slots, dimensions and `structure`; a value is a name, `#tag` or a list of either. When every `if` holds, every `require` must hold and no `exclude` may. Each has a `require` or an `exclude` |
+| `combos` | `Combo[]` | none: sampled | The slot combinations to make, chosen by the agent ([below](#the-agents-own-combos)). Not with `pick` or `seed` |
+
+- A rule's condition on a slot a combo's structure lacks never holds. A condition on a dimension is kept when the slot combinations are crossed with the dimensions: a crossing it rules out is not made.
+- A candidate's tags are what `#tag` matches. A part's own `tags` are labels for people and tools; rules do not read them.
+
+### Pools
+
+`{ pool: "./pool/demos", tags? }` makes one candidate per media file (video, audio or picture) directly in the folder, named by the file's stem. The folder is relative to the item's entry file (`/` first: from the project's root). `tags` go to every file; a file's `<stem>.meta.json` adds its own:
+
+```json
+{ "tags": ["inbox", "short"] }
+```
+
+`ctx.pool(slot)` is the file the slot picked in this combo, as a path from the project's root that `footage()` and `ctx.asset()` take. A pool outside the project, an empty pool, two files with one stem, or a stem that cannot be a name is AK-X001.
+
+## Sampling
+
+Without `combos`, sampling chooses `pick` slot combinations, the same for the same definition. Greedy, best first, it prefers combinations that:
+
+1. keep `differ` against every earlier pick;
+2. use the most candidates (and structures) no pick uses yet, so every candidate appears once when it can;
+3. use the candidates used least so far;
+4. make the most pairs of candidates not yet seen together;
+5. differ most from the nearest earlier pick;
+6. then the seed decides.
+
+Each pick keeps a reason in a few words. Sampling looks at no more than 100,000 slot combinations before the rules; more is AK-X002.
+
+## The agent's own combos
+
+`combos` names the slot combinations to make, in order: each names `structure` when the piece declares structures, and one candidate per slot of it, never a dimension. Nothing is sampled.
+
+```ts file=ads/chosen/video.ts
+import { part, video } from "@allyhub/sdk";
+
+export default video({
+  format: "1x1",
+  matrix: {
+    dims: { lang: ["en", "zh-cn"] },
+    slots: { hook: ["a", "b"], cta: ["trial", "sale"] },
+    combos: [
+      { hook: "a", cta: "trial" },
+      { hook: "b", cta: "sale" },
+    ],
+  },
+  parts: ({ combo }) => [
+    part({ key: "hook", dur: 2, title: `Hook ${combo["hook"] ?? ""}` }),
+    part({ key: "cta", dur: 2 }),
+  ],
+});
+```
+
+This makes `c01-en`, `c01-zh-cn`, `c02-en` and `c02-zh-cn`. Each combo is checked against the slots (AK-X001), the rules (AK-X002) and `differ` (AK-X004; the same combo twice too).
+
+## Combo ids
+
+- The chosen slot combinations are `c01`, `c02`, … in order (with as many digits as the count needs: `c001` when there are 100 or more). With more than one combo of the dimensions, an id adds their values: `c01-en`, `c01-zh-cn`.
+- A piece with slots names its files by id (`.allyhub/out/<piece>/video.c01-en.mp4`), and `--combo c03` names one.
+- A piece with dimensions only has no ids: its combos are named by their keys.
+
+## In the parts function
+
+- `ctx.combo.<slot>` is the candidate's name, `ctx.combo.structure` the structure, `ctx.combo.<dimension>` the dimension's value.
+- `ctx.pool(slot)` is a pool slot's file; a slot that is not a pool throws.
+- A part whose `key` is a slot's name fills that slot; `part({ slot })` names the slot a part with another key fills.
+
+**Each part renders once.** A rendered part is kept and reused in every combo that has the same part; the sound is mixed for each whole combo. So a part's layers read from their `ctx.combo` only the dimensions and their own part's slot: reading another slot's pick, or the structure, is AK-X005. Choose in the parts function and pass the result to the layer. A transition on a slot's part is rendered once per pair of parts it joins.
+
+The check loads only a few combos that between them hold every candidate, and puts the others together from their parts: each combo's length against `maxDuration` (AK-X006), and as facts the speech's loudness at each join (`join-loudness`), the music's length (`music-length`) and the generated media each combo uses. `matrix-coverage` lists each candidate with the combos that use it.
+
+## Rules
+
+| Rule | What is wrong |
+| --- | --- |
+| AK-X001 | A slot, structure, rule, pool or combo names something that does not exist, or a combo lacks a slot of its structure |
+| AK-X002 | The rules leave no combination to make (or the slots make more than sampling looks at), or rule out a combo `combos` names |
+| AK-X004 | Two chosen combos are the same, or more alike than `differ` allows |
+| AK-X005 | A part reads another slot's pick, so one render of it cannot serve every combo |
+| AK-X006 | A combo is longer than its video's `maxDuration` |
+
+## Commands
+
+- `allyhub inspect combos` prints each piece's slots, rules, the chosen combos with why, and what rendering them costs in part renders, without a browser.
+- `allyhub render <piece> --type csv` writes the batch's table of ads, `<piece>/ads.csv`: a row per ad with its combo, picks, length, file, name and the generated media it uses.
+- `allyhub render` renders every combo; `--combo` narrows it.

package/docs/contract.md

@@ -0,0 +1,51 @@
+# The contract
+
+What the build, the check and the render rely on. Everything else is the piece's own choice.
+
+## 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](layers.md)). Nothing may carry state from one `render` call 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](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](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](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, entry files, 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-F…`, `AK-G…` | A platform profile's limits; 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](defaults.md) lists them with the option. A command's defaults are in `allyhub help <command>`.