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

package/docs/project.md

@@ -0,0 +1,265 @@
+# 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: an item's entry file name, 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/sdk
+tsconfig.json         the compiler's settings: the SDK's types
+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 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-next/model` and `@allyhub-next/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"],
+    "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)).
+- 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 place |
+| `.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 folder with its entry file. The entry file's name says what the item is:
+
+| Entry file | Item | Its entry file holds |
+| --- | --- | --- |
+| `video.ts` | A video | `export default video({ … })` ([video.md](video.md)) |
+| `slides.ts` | A deck | `export default slides({ … })` ([slides.md](slides.md)) |
+| `scenery.ts` | A 3D scenery | `export default defineScenery({ … })` ([scenery.md](scenery.md)) |
+| `doc.mdx` | A doc | The doc itself, MDX |
+| `sheet.csv` | A sheet | Its rows; `sheet.yaml` beside it says what its columns are |
+| `astro.config.*` | A website | An Astro project |
+
+`video`, `slides` and `scenery` may end in `.ts`, `.tsx`, `.mts`, `.js`, `.jsx` or `.mjs`.
+
+- Everything in an item's folder is the item's own: its script, its media, its edits files. Folders above it only group items.
+- An item may be anywhere but the project's root, a dot folder and `node_modules`. An item cannot hold another, and a folder cannot have two entry files (AK-M003). A `video(…)` exported from anything but an item's entry file is AK-M002.
+- An item's **place** is its folder's path from the project's root (`launch/film`). A piece's `id` is its place 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.
+
+### The entry file
+
+- The default export is `video({ … })` or `slides({ … })` 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`, `slides`, `part`, `take` and `footage` made for that file (`sdkFor({ file })`). 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/video.ts
+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")) }),
+  ],
+});
+```
+
+```ts file=launch/film-vertical/video.ts
+import { video } from "@allyhub/sdk";
+
+import film from "../film/video.ts";
+
+// Its music is still launch/film/music/bed.mp3.
+export default video({ ...film, id: "launch/film-vertical", format: "9x16" });
+```
+
+- `video()` and `slides()` return their 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](footage.md), [speech.md](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`.
+
+### `script.<lang>.yaml`
+
+One file per language in the item's folder (`script.en.yaml`, `script.zh-cn.yaml`):
+
+```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`) |
+
+- 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 `say` is one line, or a plural: it may hold anchors (`@{name}`) and text shown one way and said another (`<12|twelve>`) ([speech.md](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 whose folder has no entry file yet is read and waits for its item.
+
+### `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).
+- The languages are the scripts' and `assets/text/`'s, ordered with `allyhub.config.ts`'s `locales` first, else `en`; a piece's `matrix.dims.lang` narrows them ([batches.md](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](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).
+
+```ts file=launch/plans/video.ts
+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`; 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](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
+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](#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](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.

package/docs/scenery.md

@@ -0,0 +1,308 @@
+# 3D sceneries
+
+A scenery is three.js the agent writes, in a module whose default export is `defineScenery(…)`: AllyHub builds it once, poses it from time alone, draws it from cameras and measures it. This file covers that contract, cameras and their moves, and the `scenery()` layer with its screens. The commands are in `allyhub help 3d`.
+
+## A scenery is an item
+
+An item is a folder with a `scenery.ts` (or tsx, mts, js, jsx, mjs). A person looks round it in Studio and `allyhub dev`'s page at scenery time 0, selecting a placed object (the outermost named one) and its named `cameras`, never editing it; a note on it names the object, its size, the point clicked and the view as an `allyhub scenery view` command. A scenery module by another name is code, not an item.
+
+- A video imports a scenery item by its path, as any module: `import room from "../room/scenery.ts"`.
+- A path a scenery reads that starts with `./` or `../` (`w.texture("./wood.jpg")`, `w.load("./desk.glb")`, a model's image) is from the scenery's own module; any other is from the project's root. An import (`import desk from "./desk.glb"`) is the same. Kept in its folder and named from there, a scenery works wherever the folder goes.
+- `three` (r186, 0.186.1), `three/addons/…`, `three/webgpu` and `three/tsl` are imported by name with no `package.json`: the CLI lends them, unless the project declares its own `three`. So are `@allyhub-next/scenery-host/layer` (everything in this file) and `@allyhub-next/model` ([modeling.md](modeling.md)).
+- glTF and GLB load (`.glb`, `.gltf`, `.bin`, `.ktx2`), environments are `.hdr` or `.exr`; all are media imports. CC0 models, HDRIs and textures: `allyhub add search`, `allyhub add`.
+
+**Units and axes.** Right-handed, **Y up**, **metres**, angles in **degrees** everywhere in AllyHub's API (three.js itself takes radians). A camera looks down its own −Z. A glTF model's front is its +Z. Positions and sizes AllyHub prints are world space. three.js's lights are physical: point and spot lights in candela, directional lights in lux, an emissive surface in nits.
+
+## `defineScenery`
+
+```ts file=room/scenery.ts
+import * as THREE from "three";
+import { defineScenery, path } from "@allyhub-next/scenery-host/layer";
+import sofaModel from "./sofa.glb";
+
+export default defineScenery({
+  async build(w) {
+    w.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    const sofa = await w.load(sofaModel);
+    sofa.name = "sofa";
+    w.scene.add(sofa);
+    const mixer = new THREE.AnimationMixer(sofa);
+    const clips = sofa.userData["animations"] as THREE.AnimationClip[];
+    for (const clip of clips) mixer.clipAction(clip).play();
+    return { mixer };
+  },
+  update(made, t, w) {
+    w.seek(made.mixer, t);
+  },
+  cameras: { door: { position: [0, 1.5, 2.8], target: "sofa", lens: 26 } },
+  moves: {
+    walk: path(
+      [
+        [0, 1.5, 3],
+        [0.4, 1.2, -0.2],
+      ],
+      { dur: 6, target: "sofa" },
+    ),
+  },
+});
+```
+
+`build(w)` runs once, awaited with every load it starts (60 s at most; in a video it counts in the piece's `loadLimit`, AK-P002); what it returns is `made`. `update(made, t, w)` poses it at `t`, seconds of scenery time. `cameras` (checked when defined, AK-W004) and `moves` are by name, for the commands and for layers. `bake` is in [Baked light](#baked-light).
+
+**From `t` alone.** The same moment must draw the same pixels in any order (AK-D002). `Date`, `performance.now`, `Math.random`, `crypto.getRandomValues` and `requestAnimationFrame` follow the moment drawn; timers run only while it builds. Pose an `AnimationMixer` with `w.seek(mixer, t)` (every action reset, then `setTime(t)`), not a bare `setTime`. Name what is referred to (`Object3D.name`): cameras, moves, measurements and `projectScenery` take names, and a name no object has, or two have, is AK-W005.
+
+`renderer` (all optional; `SCENERY_RENDERER_DEFAULTS`, the fastest drawing):
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `kind` | `"webgl"` | `"webgpu"`: `WebGPURenderer` (node materials, TSL) through its WebGL 2 back end; not baked yet |
+| `antialias` | `false` | Multisampled edges |
+| `transmissionScale` | 0.25 | The extra pass transmissive materials (glass) need, a share of the frame's size, (0, 2] |
+| `outputBufferType` | three's | The buffer effects draw into (`HalfFloatType` for HDR effects) |
+| `logarithmicDepthBuffer`, `reversedDepthBuffer` | `false` | |
+| `focus` | `{ samples: 64, maxRadius: 64 }` | A camera's depth of field: samples per pixel, the widest blur's radius in px as drawn, and `supersample` (1–4; default 2 with `antialias`, else 1) |
+
+Alpha, size and pixel ratio are AllyHub's; set the rest on `w.renderer` in `build` (tone mapping, shadows, `setEffects`). A material whose shader does not compile, or needs more texture units than the renderer has (maps, environment, shadow-casting lights, screens lighting it), draws nothing: AK-W006, a warning over 16 units where the renderer has more.
+
+`w`, the scenery's host (`SceneryHost`):
+
+| Field | What it is |
+| --- | --- |
+| `scene`, `renderer` | The `THREE.Scene`, and the renderer AllyHub made |
+| `load(asset)` | A glTF or GLB as a `Group`, with the lent decoders (Draco, meshopt, KTX2); its animations on `userData.animations`. One that does not load is AK-W003 |
+| `texture(asset, { colorSpace? })` | A picture as a texture: sRGB, or `"linear"` for a data map (normal, roughness, AO, displacement) |
+| `environment(asset, { background? })` | An `.hdr` or `.exr` as the scene's environment, and its background when asked |
+| `seek(mixer, t)` | Poses an animation mixer at `t` |
+| `object(name)` | The object of that name, undefined for none |
+| `positionOf(name)`, `boundsOf(name)` | Its box's centre now; its box, from its vertices |
+| `asset(path)` | A project file's URL |
+| `time(ref)` | In `update`: the scenery time of a word or anchor reference (`"@tap"`, `"@tap+0.2"`) of the part that draws it. Throws in `build` |
+| `screen(name)` | A screen's face now (its first mesh's +Z side): `point(x, y)` from shares of its content, `center`, `normal`, `up`, `width`, `height` |
+| `screenPicture(name)` | In `update`: a screen's picture as a mipmapped texture, for a material of the scenery's own; undefined for a screen drawn over the scenery |
+
+An asset is an import or a path. Where there is no part to time a reference by (the `allyhub scenery` commands), its moments come from the video that draws the scenery (the one video of the project that does, or `--piece`'s), its scenery layers finding them as they do when drawing; `--times @tap=2.4` gives them by hand, over the video's.
+
+## Cameras
+
+A `CameraState` points one of three ways, or looks down −Z, level:
+
+```ts fragment
+{ position: [0, 1.5, 2.8], target: "sofa", lens: 26 }        // at an object's box centre, followed as it moves
+{ position: [0, 1.5, 2.8], target: [0, 0.6, -1.4], fov: 40 } // at a point; a vertical fov in degrees
+{ position: [0, 1.5, 2.8], yaw: 30, pitch: -10 }             // 30° left of −Z, 10° down
+{ position: [0, 1.5, 2.8], direction: [0, -0.2, -1], roll: 5 }
+```
+
+| Field | Default | What it is |
+| --- | --- | --- |
+| `position` | required | Metres |
+| `target`, `direction`, or `yaw`/`pitch` | down −Z | `yaw` about +Y (90 looks down −X); `pitch` above the horizon |
+| `up` | `[0, 1, 0]` | A view straight along `up` cannot be drawn (AK-W004) |
+| `roll` | 0 | Degrees about the view, counterclockwise |
+| `lens` | 26 | 35 mm-equivalent focal length, mm |
+| `lensFrame` | `"diagonal"` | What the lens is measured on: the frame's diagonal (CIPA), `"long"`, `"short"`, `"phone"` (`{ aspect: 4/3, keep: "long" }`, a phone's "26 mm"), or `{ aspect, keep }` |
+| `fov` | | Vertical degrees, instead of a lens |
+| `near`, `far` | 0.05, 500 | Metres |
+| `aperture` | none (a pinhole) | An f-number in the same 35 mm-equivalent terms as `lens` (a phone's f/1.8 is about f/8). Needs `focus` |
+| `focus` | | A distance along the view (m), a point, or an object's name |
+| `ev` | none | Exposure, EV at ISO 100: the light is scaled by `exposureOf(ev)`, 1 / (1.2 · 2^ev), before the tone curve, in place of `toneMappingExposure` |
+
+`CAMERA_DEFAULTS` holds them. The aspect is always the frame's. `fieldOfView`, `diagonalLens` and `lensForVertical` convert (three.js's `setFocalLength` measures on another frame). `allyhub scenery solve` finds the camera that put points of the scenery at pixels of a picture.
+
+## Moves
+
+A move (`Move`) is `(t, view?) => CameraState`, a function of scenery time alone; `view` (`SceneryView`) gives `pointOf(name)`, `time(ref)`, the frame's `aspect` and `screen(name)`. Every moment a move takes (`MoveTime`) is seconds or a word or anchor reference of the part that draws the scenery.
+
+| Function | What it makes |
+| --- | --- |
+| `keys([{ t, position?, target?, yaw?, pitch?, lens?, fov?, roll?, aperture?, focus?, ev?, ease? }], { lensSpace? })` | Each key at its time: position along a curve, speed continuous, a repeated position holds; `ease` runs the stretch into its key; lens in log focal length (or `lensSpace: "fov"`); `aperture` and `ev` in every key or none |
+| `path(points, { dur \| speed, start?, ease?, target?, ahead?, frame?, alpha? })` | Through the points at constant speed; `target` a point, a name or `"ahead"` (default); `frame: "rmf"` carries `up` untwisted (`PATH_DEFAULTS`) |
+| `orbit({ around, radius, height?, from, to, dur, start?, ease?, target? })` | Round a point or a name; 0° on its +Z side, 90° on +X, not wrapped |
+| `shots([{ from, camera }, …])` | Shots joined by cuts, each a camera or a move; measurements of motion stop at its cuts (`cutsOf`) |
+| `blend(a, b, { from, to, ease? })` | `a` before `from`, `b` after `to`, mixed between (lens at a steady zoom ratio, `ev` in stops); `ease` default `"smooth"` |
+| `focusScreen(name, [x, y, w, h], { fill?, lens?, fov?, yaw?, pitch?, ev?, lensFrame? })` | A move framing a rectangle of a screen's content (shares from its top left), square on or `yaw`/`pitch` off it |
+| `fitCamera({ points \| boxes \| sphere, aspect, direction \| yaw/pitch, lens \| fov, fill?, margins?, adjust?, … })` | A `CameraState` framing them exactly; `adjust: "lens"` keeps `position` and solves the lens (`FIT_DEFAULTS`) |
+| `mixCameras(a, b, x, view, what)` | The camera `x` of the way from `a` to `b`, as `blend` mixes them |
+| `withCuts(camera, move)` | `move` with `camera`'s cuts, so a move of the agent's own wrapped round `shots()` keeps them |
+
+`Ease` is `"linear"`, `"in"`, `"out"`, `"in-out"`, `"smooth"` or a function on 0–1 (`easeValue`). `aimed({ overshoot?, peak?, primary?, vary?, seed?, index? })`, an aimed movement's progress (past 1 and back), is an `ease` too; `aimAt(shape, x)` and `rise(s, peak)` are its parts (`AIM_DEFAULTS`).
+
+```ts fragment
+camera: shots([
+  { from: 0, camera: "door" },
+  { from: "@demo", camera: blend(wide, focusScreen("monitor-screen", [0.62, 0.05, 0.1, 0.06]), { from: "@demo", to: "@click" }) },
+]),
+```
+
+### `handheld`
+
+`handheld(camera, opts)` is a camera or a move held in a hand: a `Move` of t alone, the same for a `seed`, another hand in each shot of `shots()` (whose cuts it keeps), its lens and focus kept. Amounts are standard deviations. Defaults: `HANDHELD_DEFAULTS`, `STABILIZER_DEFAULTS`, `AUTOFOCUS_DEFAULTS`, `AUTO_EXPOSURE_DEFAULTS` ([defaults.md](defaults.md)).
+
+| Option | What it is |
+| --- | --- |
+| `angle`, `roll`, `shift`, `sway` | The sway: yaw and pitch degrees, roll as a share of them, metres on each axis; its spectrum round `sway` Hz, falling as 1/f² |
+| `tremor` | `{ angle, frequency, spread, vary, swell, period }`: a band round `frequency` Hz that swells |
+| `drift` | `{ angle, shift, period }`: the framing's slow drift |
+| `stabilizer` | `{ strength, cutoff }`: takes `strength` of the turning out above `cutoff` Hz. Absent: none |
+| `reframes` | `[{ at, to?, turn?, shift?, duration?, overshoot? }]`: an aimed move to a camera, or by a `Turn` `[yaw, pitch, roll?]` and `Shift` `[right, up, forward?]`; `reframe` sets defaults |
+| `jolts` | `[{ at, turn? }]`: the hand knocked, ringing out; `jolt` sets their defaults |
+| `autofocus` | With an `aperture` and `focus`: rests `miss` off and hunts after cuts, reframes and jolts. Absent: none; `{}` the defaults |
+| `exposure` | With an `ev`: follows a reframe's `ev` late, is off at a cut and settles, breathes. Absent: none |
+| `seed` | Another seed is another hand |
+
+### A phone
+
+`PHONE_CAMERA` (`@allyhub/sdk/scenery`) names a phone's main camera as the options of each mechanism; `phoneCamera(over)` changes any value and keeps the rest. `lens` goes into a camera state, `sensor` into `scenery({ sensor })`, `hand` into `handheld()`, and the marks it leaves on its picture (grain, softness, sharpening, motion blur) into `video()`'s `capture` and `motionBlur` ([video.md](video.md)). Each is a starting point, not a look.
+
+```ts file=phone/video.ts
+import { part, video } from "@allyhub/sdk";
+import { phoneCamera } from "@allyhub/sdk/scenery";
+import { handheld, scenery, shots } from "@allyhub-next/scenery-host/layer";
+import room from "../room/scenery.ts";
+
+const phone = phoneCamera({ hand: { tremor: { angle: 0.15 } } });
+const camera = handheld(
+  shots([
+    {
+      from: 0,
+      camera: {
+        ...phone.lens,
+        position: [0, 1.4, 1.2],
+        target: "sofa",
+        focus: "sofa",
+        ev: 7.4,
+      },
+    },
+  ]),
+  { ...phone.hand, reframes: [{ at: 2, turn: [-2.5, 1] }] },
+);
+
+export default video({
+  format: "9x16",
+  capture: phone.capture,
+  motionBlur: phone.motionBlur,
+  parts: () => [
+    part({
+      key: "look",
+      dur: 5,
+      layers: [scenery(room, { camera, sensor: phone.sensor })],
+    }),
+  ],
+});
+```
+
+## The `scenery()` layer
+
+`scenery(scenery, opts)` is a graphic layer. The scenery is built once when the output loads and posed at each frame's scenery time.
+
+```ts file=tour/video.ts
+import { custom, part, video } from "@allyhub/sdk";
+import {
+  projectScenery,
+  scenery,
+  screen,
+} from "@allyhub-next/scenery-host/layer";
+import room from "../room/scenery.ts";
+import demo from "../demo/video.ts";
+
+export default video({
+  format: "16x9",
+  parts: () => [
+    part({
+      key: "walk",
+      dur: 6,
+      layers: [
+        scenery(room, {
+          camera: "walk",
+          name: "room",
+          screens: { "tv-screen": screen(demo, { start: 1 }) },
+        }),
+        custom({
+          render(el, t) {
+            const sofa = projectScenery("room", "sofa", t, el);
+            if (sofa)
+              el.style.transform = `translate(${String(sofa.x)}px, ${String(sofa.y)}px)`;
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `camera` | required | A `CameraState`, the name of one of the scenery's cameras or moves, or a move |
+| `box` | the frame | `[x, y, w, h]` as fractions of the frame; the camera's aspect is the box's |
+| `background` | the scenery's own | A colour, or `"transparent"`; without it what `build` set as the scene's background, else transparent |
+| `time` | `{ from: 0 }` | The scenery's time from the film's: `{ from }` at the film's start, or `(filmT) => number`. It runs on across parts and cuts |
+| `quality` | `{ scale: 0.5, focusLevels: 8 }` | `scale`: the share of the layer's size each way it is drawn at (above 1 supersamples). `focusLevels`: Gaussian levels a screen's depth of field is mixed from. `SCENERY_LAYER_DEFAULTS` |
+| `sensor` | none | A phone's sensor filming it: the moiré its Bayer grid makes of the screens' pixels. `{ photosites, lens, moire, chroma, distortion }`, `SENSOR_DEFAULTS` |
+| `screens` | none | `{ <object name>: screen(…) }` (below) |
+| `props` | none | `SceneryProp`s this layer brings in (below) |
+| `name` | `"scenery"` | What `projectScenery` and the facts call it |
+| `at`, `until`, `dur`, `z` | | As every layer ([video.md](video.md)) |
+
+`projectScenery(layer, target, t, el)`, called in a layer's `render` with its own element, gives where a point or a named object of the scenery layer called `layer` in the same part is at part time `t`: `{ x, y }` in frame px, `inView`, `depth` (m); undefined when no such layer shows then.
+
+**Props** (`SceneryProp`: `{ name, build(w), update?(object, t, w) }`) are things a layer brings in (a stand-in, a pointer): built after the scenery and its bake (never in it), posed from t after the scenery's update, shown only in the layers that add them.
+
+**A scenery inside another video.** A video item whose picture is a scenery can be shown in a film: `take(scene).range(from, to)` plays a stretch of it and `footage({ camera })` draws its scenery layers from a camera of the film's (`cameras` by layer name for several, `quality: { scale }` for this film only), on the item's clock. See [footage.md](footage.md) and [speech.md](speech.md).
+
+## Screens
+
+`screen(content, opts)` puts content on a named object of the scenery (its first mesh's +Z face, the content's top left at the geometry's −x, +y). The content is a video item of the project (its piece, imported: its parts, timing, anchors and components its own; pictures only, not its sound, and not footage yet) or graphic layers drawn on `size` px, whose windows and time props are seconds of the screen's time or references of the part.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `start` | 0 | When the screen's time is 0: scenery seconds, or a reference of the part (`"@demo"`) |
+| `cue` | 0 | The screen's own moment that plays at `start`: seconds, or (a video) its own reference (`"@click"`, a part's key) |
+| `cues` | | Instead: `{ <its moment>: <film reference or scenery seconds> }`; between two cues it plays at the speed that joins them |
+| `time` | the scenery's | Instead: `{ from }` or `(t) => number` from scenery time |
+| `size` | `[1920, 1080]` | Layers only: the content's pixels (a video uses its format's) |
+| `dur` | to the layer's end | Layers only |
+| `background` | `"#000000"` | Behind the content, or `"transparent"` |
+| `pixels` | `{ density: 2, rows: 0.15 }` | Its physical pixels, for a sensor's moiré (`PANEL_DEFAULTS`) |
+| `glass` | none | `{ reflectance?, roughness?, scale? }`: what its glass reflects of the scenery over its picture, by Fresnel; `{}` the defaults (`GLASS_DEFAULTS`) |
+| `inScenery` | `true` | Drawn in the scenery: `{ brightness?, light? }` (below); `false`: laid over the scenery |
+
+```ts file=demo/video.ts
+import { custom, part, video } from "@allyhub/sdk";
+
+// Made only to be shown on a screen.
+export default video({
+  format: "16x9",
+  deliverable: false,
+  parts: () => [
+    part({
+      key: "open",
+      dur: 4,
+      layers: [
+        custom({
+          render: (el, t) => (el.textContent = `${String(Math.round(t))} new`),
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Before `start` a video holds its first frame, after its end its last. A video that shows itself through any chain is AK-M010; one made only for a screen is `video({ deliverable: false })`.
+
+**In the scenery** (where the browser has Chrome's HTML-in-Canvas, as AllyHub's has) the content is the mesh's texture, drawn with the exposure, depth of field, glass and moiré, and it lights the scenery's standard and physical materials (at most 2 screens). `brightness` (default 1) is its white, scene-linear: nits in a scenery lit in physical units with an `ev`. `light: false` lights nothing; `light: { cells, specular, base }` sets the cells of its diffuse light (`[8, 5]`), leaves out its reflection (`specular: false`), and with `base: { brightness?, color? }` adds only what differs from steady light the scenery already has from it (`SCREEN_LIGHT_DEFAULTS`). `material.userData.screenLight = false` (or `{ specular: false }`) keeps a material out. Without HTML-in-Canvas (or with `ALLYHUB_HTML_IN_CANVAS=0`) the mesh is a hole with the content laid over it at its own colours: AK-W007, unless asked with `inScenery: false`. An element it cannot show (in the browser's top layer, `preserve-3d` planes it cannot order, over the largest texture) is AK-W008.
+
+Text on a screen is left out of the frame's text facts; `scenery-screen` reports its smallest text instead.
+
+## Baked light
+
+`allyhub scenery bake <item>` bakes the scenery's light (direct, shadows, bounces, emissive surfaces, the environment) into a lightmap once, kept in `.allyhub/cache/bake/` by the scene's digest and the renderer that made it, and laid on the scenery each time it is built. A bake made on a GPU is laid only by that GPU; one made on the CPU by every renderer. A scene that changed is drawn unbaked until baked again. How it bakes is `defineScenery({ bake })` (`BakeOptions`: `density`, `samples`, `bounces`, `weight`, `skip`, `ignore`, `posedAt`, `probe`, …; `BAKE_DEFAULTS`).
+
+## Measuring
+
+`allyhub scenery <item>` (objects, sizes, costs, lights, cameras, moves, bake), `scenery view`, `map`, `see`, `measure`, `motion`, `solve` and `bake` draw or measure the scenery module alone, without its screens (`allyhub frames` on a video shows them); `inspect fidelity` compares each screen drawn in the scenery with its own element.
+
+The check reports each scenery layer's facts, printed by `allyhub inspect`: `scenery-contact`, `scenery-support`, `mesh-health`, `camera-clearance`, `camera-motion`, `scenery-screen` (each screen's share, scale, angle, hidden share, smallest text, moiré, cue speeds), `scenery-screen-fidelity` and `scenery-bake`. `frames cuts` sheets a scenery camera's cuts.
+
+Rules a problem is reported under: AK-W001 (it does not build, or `update` throws), AK-W002 (WebGL cannot be made, or is not SwiftShader where the CPU was asked for), AK-W003 (a file does not load), AK-W004 (a camera cannot be drawn), AK-W005 (a name names no object, or two), AK-W006 (a shader does not compile, or needs too many texture units), AK-W007 (a screen drawn over the scenery, a warning), AK-W008 (a screen in the scenery cannot show its element).
+
+Frames are drawn on the GPU on a Mac and on the CPU (SwiftShader, the same pixels on every computer) elsewhere; `ALLYHUB_GPU=0` or `1` chooses.