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

package/docs/layers.md

@@ -0,0 +1,317 @@
+# Layers
+
+A graphic layer is DOM a piece draws, made by a component (`defineComponent()`) or written in place (`custom()`). Here: both, the layer's `ctx`, the helpers of `@allyhub/sdk/dom` and `@allyhub/sdk`, and the starter components. A layer's timing (`at`, `until`, `dur`) and stacking (`z`) are in [video.md](video.md#layers); footage layers in [footage.md](footage.md).
+
+## `custom()`
+
+A graphic layer written in the piece, for what no component does. `custom({ mount?, render, at?, until?, dur?, z? })`:
+
+```ts
+import { custom, ease, part, tween } from "@allyhub/sdk";
+import { h, layout, one, tag } from "@allyhub/sdk/dom";
+
+export const year = part({
+  key: "year",
+  dur: 3,
+  layers: [
+    custom({
+      at: 0.5,
+      mount(el, ctx) {
+        const L = layout(ctx);
+        const label = tag(
+          h("div", { fontSize: 240 * L.k, fontWeight: 900 }),
+          "year",
+        );
+        label.textContent = "2026";
+        el.append(
+          h(
+            "div",
+            {
+              position: "absolute",
+              inset: 0,
+              display: "grid",
+              placeItems: "center",
+            },
+            [label],
+          ),
+        );
+      },
+      render(el, t, ctx) {
+        const label = one(el, "year");
+        if (!label) return;
+        const x = tween(t, {
+          start: ctx.layer.start,
+          dur: 0.4,
+          ease: ease.outExpo,
+        });
+        label.style.opacity = String(x);
+        label.style.transform = `scale(${String(1.4 - 0.4 * x)})`;
+      },
+    }),
+  ],
+});
+```
+
+## `defineComponent()`
+
+A component is a function that makes a graphic layer from its props and the layer's options, in one object.
+
+```ts file=components/badge.ts
+import { defineComponent, text, time, type Time } from "@allyhub/sdk";
+import { h, layout, one, tag } from "@allyhub/sdk/dom";
+
+export const badge = defineComponent<{
+  value: string;
+  label: string;
+  settle?: Time;
+}>({
+  name: "badge",
+  label: { en: "Badge" },
+  summary: "A number with a label under it.",
+  props: {
+    value: text({ max: 6 }),
+    label: text({ max: { "16x9": 40, "9x16": 24 } }),
+    settle: time({ optional: true }),
+  },
+  defaults: { label: "" },
+  examples: { pilots: { value: "3", label: "pilot teams" } },
+  mount(el, p, ctx) {
+    const L = layout(ctx);
+    const value = tag(
+      h("div", { fontSize: 160 * L.k, color: "var(--ak-color-accent)" }),
+      "value",
+    );
+    value.textContent = p.value;
+    const label = h("div", {
+      fontSize: 48 * L.k,
+      fontFamily: "var(--ak-font-body)",
+    });
+    label.textContent = p.label;
+    el.append(
+      h("div", { position: "absolute", left: L.left, top: L.top }, [
+        value,
+        label,
+      ]),
+    );
+  },
+  render(el, t, p, ctx) {
+    const value = one(el, "value");
+    if (!value) return;
+    value.style.opacity = t < (p.settle ?? ctx.layer.start) ? "0.4" : "1";
+  },
+});
+```
+
+```ts file=launch/film/parts.ts
+import { part } from "@allyhub/sdk";
+import { badge } from "../../components/badge.ts";
+
+// Its props and the layer's options in one object; settle is given as a reference to the part's anchor.
+export const teams = part({
+  key: "teams",
+  dur: 3,
+  anchors: { live: 1.2 },
+  layers: [
+    badge({ value: "3", label: "pilot teams", settle: "@live", at: 0.5 }),
+  ],
+});
+```
+
+| Field | What it is |
+| --- | --- |
+| `name` | The component's name, unique in the project |
+| `label`, `summary` | Its name (default `name`) and one line on what it is for: a string, or by language |
+| `props` | The props' semantic types, plain data (below) |
+| `defaults` | Default prop values |
+| `examples` | Named example props |
+| `hidden` | Hides a deprecated component |
+| `mount(el, props, ctx)` | Lays the layer out once: builds its elements, may measure text |
+| `render(el, t, props, ctx)` | Sets everything that moves from `t` alone |
+
+`at`, `until`, `dur` and `z` are the layer's options (`LAYER_OPTIONS`): a prop cannot have those names (`defineComponent` throws). A layer's length and still belong to its part.
+
+**Prop types** (from `@allyhub/sdk`, plain data; each takes `label`, `examples` and `optional`):
+
+| Function | What it is | Its limits |
+| --- | --- | --- |
+| `text(o?)` | Text on screen | `max` (one number, or per preset format), `min`, `multiline` |
+| `time(o?)` | A moment ([below](#time-props)) | |
+| `asset(o?)` | Media: an import or `ctx.asset(path)` | `kind` |
+| `color(o?)` | A look variable, such as `var(--ak-color-accent)` | |
+| `number(o?)` | A number | `min`, `max`, `step` |
+| `boolean(o?)` | A switch | |
+| `list(of, o?)` | A list | `min`, `max` |
+| `object(fields, o?)` | An object | |
+
+### Time props
+
+A prop declared `time()` (also inside `list()` and `object()`) is typed `Time` in the component. Where the layer is made it takes a word reference or seconds (`"live"`, `"@press+0.2"`, `1.2`: [speech.md](speech.md)); by the time `mount` runs it is seconds from the part's start. Only `time()` props take word references.
+
+### `mount` and `render`
+
+- `mount` runs once for each element a layer is drawn into, before any `render` of it: once per part that lists it, and again for a cover. Keep what `render` needs on the element (find it again with `one`, or a `WeakMap` keyed by `el`), not in a variable the elements share. The fonts the look and the text need have loaded by then, so it may measure.
+- `render(el, t, …)` gets `t`, seconds from the part's start, and runs only between the layer's `at` and `until`: an entrance counts from `ctx.layer.start`. It sets every moving property from `t` alone, never from the frame before: the same moment draws the same frame in any order (AK-D002). What a layer may and may not do to stay deterministic is in [contract.md](contract.md).
+- A style value the browser does not accept (`fontWeight: "900px"`, `width: "760"`) is dropped by the browser; while checking, every inline style set is watched and such a value is AK-R004.
+- Text inside an element marked `data-ak-picture` is part of a picture (a mocked interface the frame crops on purpose): the frame's text checks leave it out.
+
+### What the contract relies on
+
+- **The look by its variables**: colours and fonts as `var(--ak-color-*)` and `var(--ak-font-*)` ([video.md](video.md#the-look)) follow the project's look; a literal colour does not. A `color()` prop holds a look variable.
+- **Text as text**: the helpers set text as text nodes (`textContent`), so a string never becomes markup.
+- **Every format**: lay out from `ctx.dims`, `ctx.content` or `layout(ctx)`, not by the format's name: a custom `WxH` has no preset's name, and a changed `safe` keeps the format's.
+
+## The layer's `ctx`
+
+`mount` and `render` get a `StageContext`:
+
+| Name | What it is |
+| --- | --- |
+| `ctx.look` | The look (also the CSS variables `--ak-color-*`, `--ak-font-*`, `--ak-motion-beat`) |
+| `ctx.format` | The format's name: `"9x16"`, `"1280x720"`; a deck's may be `"a4"` |
+| `ctx.dims` | `{ width, height, orient, safe, profile? }` ([video.md](video.md#formats)) |
+| `ctx.combo` | The combo. A layer may read the dimensions and its own part's slot, never another slot's pick (AK-X005): a part is rendered once for every combo that has it |
+| `ctx.dur` | The part's length, seconds |
+| `ctx.layer` | `{ start, end }`: this layer's window, seconds from the part's start |
+| `ctx.asset(path)` | Media at a path relative to the piece's file |
+| `ctx.optionalAsset?.(path)` | Media that may not be there (a scenery's bake): `undefined` when it is not, with no problem; the part is drawn again once it is made |
+| `ctx.words()` | The part's words on its own clock, `[{ text, start, end }]`; empty without speech |
+| `ctx.at(ref)` | Seconds from the part's start of a word reference or an anchor |
+| `ctx.captions(opts?)` | The caption cues shown in this part, each with its words ([speech.md](speech.md)) |
+| `ctx.face(t, id?)`, `ctx.faces(t)` | Faces on the frame at `t` ([footage.md](footage.md)) |
+| `ctx.texts(t)` | The text of the layers listed before this one at `t`: `[{ layer, text, box }]`. It draws them to measure, so call it in `mount` |
+| `ctx.covered` | The format's covered areas, `[x, y, w, h]` each in the frame's pixels; none for a custom format |
+| `ctx.content` | The content box, `[x, y, w, h]` ([below](#the-content-box)) |
+| `ctx.wait(promise)` | Work that must finish before anything is drawn (a scenery's build). A rejection is reported with the layer, under its `code` if it carries a rule's, else AK-R001; work that does not settle within `seekLimit` is AK-P003 |
+| `ctx.report?.({ code, message, level? })` | Reports what went wrong drawing this layer, at any moment; a code that is not a rule's is AK-R001 |
+| `ctx.film?` | The video on its clock: `start` (the part's start, film seconds), `part` (its key), `at(ref)` (film seconds of an anchor of any part, or a part's key), `outer` (where an outer video shows this one). Reading it makes the part's place in the film part of its identity |
+| `ctx.video?.(piece, el)` | Another video item drawn in an element of this layer's ([below](#a-video-inside-a-layer)) |
+| `ctx.embedded` | True in a video drawn inside another |
+| `ctx.layoutOnly` | True while a moment is drawn only to measure its layout: nothing reads its pixels. A layer that paints a canvas no layout depends on may skip painting then; it still places its elements |
+| `ctx.realTimers?` | The page's own clock and timers (`now`, `setTimeout`, `clearTimeout`), for work that waits on the wall clock (a loader, a worker), never for what a frame shows |
+
+### The content box
+
+`layout(ctx, opts?)` gives `{ W, H, k, orient, pad, top, bottom, left, right }`; `ctx.content` is the same box as `[x, y, w, h]`. In pixels:
+
+```
+k      = min(W, H) / 1080              the type scale: 1 in every preset and profile
+margin = 120 × k (landscape), 84 × k (portrait, square)
+pad    = max(margin, safe.left, safe.right)
+top    = max(pad, safe.top + 30 × k)
+bottom = H − max(pad, safe.bottom + 20 × k)
+left   = pad,  right = W − pad
+```
+
+`right` and `bottom` are coordinates, not widths. `layout(ctx, { margin, topGap, bottomGap })` changes the margin and the gaps.
+
+### A video inside a layer
+
+`await ctx.video(piece, el)` draws another video item of the project (the piece this module imported) inside `el`, in its own format and, where it has it, this video's language. It gives `{ id, duration, width, height, seek(t), at(ref) }`: `seek(t)` draws its moment `t`, `at(ref)` finds its own anchor or part's key in its seconds. It draws its graphic layers over its background; what it reads counts as this video's. A chain of videos that reaches itself is AK-M010. Put it behind `ctx.wait`. More in [footage.md](footage.md).
+
+## `@allyhub/sdk/dom`
+
+| Helper | What it does |
+| --- | --- |
+| `h(tag, style?, children?, cls?)` | An element with styles and children; a string child is a text node |
+| `css(el, style)` | Sets styles: camelCase or `--custom` names; a number gets `px`, except `opacity`, `zIndex`, `fontWeight`, `lineHeight`, `flex`, `flexGrow`, `flexShrink` |
+| `layout(ctx, opts?)`, `contentBox(L, style?)` | The content box ([above](#the-content-box)); an absolutely placed flex column over it |
+| `tag(el, name)`, `one(el, name)`, `all(el, name)` | Names an element (`data-ak`); finds the first, or every one, again. The measurements (`allyhub inspect`) name what they follow by it |
+| `text(v)`, `list(v)` | A prop as a string; as a list of strings |
+| `textBlock(value, { size, weight?, color?, font?, lineHeight?, align? })` | A `div` of balanced, wrapping text, Chinese broken only between words. Defaults 700, `var(--ak-color-fg)`, `var(--ak-font-display)`, 1.15, `"left"` |
+| `wordBreaks(value)` | Chinese text with zero-width spaces between its words, for `word-break: keep-all` |
+| `marked(line, styles?)` | A `span` of a line with its marks drawn (`**strong**`, `*em*`, `~~struck~~`, `` `code` ``): each marked run a span with `data-mark` and the style of its kinds, `styles` over `MARK_STYLES` (`strong` 700, `em` the accent colour, `strike` a line through, `code` the mono font at 0.9 em) |
+| `fitTo(el, { min, max, maxHeight })` | The largest font size at which `el` fits its width and `maxHeight`; sets it |
+| `fitLines(el \| text, { lines, min, max, width?, height?, precision? })` | `{ size, fits, lines }`: the largest size at which the text takes at most `lines` lines of the box (a text also takes `style`, and needs `width`). Also from `@allyhub/sdk` |
+| `textLines(el)` | Each line of `el`'s text as the browser broke it. Also from `@allyhub/sdk` |
+| `freeAreas(ctx, t, opts?)` | The bands of the content box at `t` clear of faces, other layers' text and covered areas, tallest first. Call it in `mount` |
+| `captionTop(ctx, L, cue, w, h, opts?)` | A top for a block `w × h` over one cue: the first spot of `prefer` (default bottom, top, middle) clear of faces and other text. Call it in `mount` |
+| `emphasized(words, list)`, `wordEmoji(words, map)` | Per word of a caption cue: whether `list` names it; the emoji `map` gives it |
+| `emojiEl(value, style?)` | A span for an emoji in `var(--ak-font-emoji)` |
+| `lightDark(el)` | The look's background and text colours as `{ light, dark }`. Call it in `mount` |
+
+Nothing places, stresses or decorates on its own: these are measurements and builders a layer calls.
+
+## Animation, text, paths and noise
+
+From `@allyhub/sdk`; pure functions.
+
+| Function | What it does |
+| --- | --- |
+| `tween(t, { from?, to?, start?, dur?, ease? })` | The value at `t`; defaults 0, 1, 0, 0.5, `ease.out` |
+| `progress(t, start, dur)`, `lerp(a, b, x)`, `clamp(x, lo?, hi?)` | 0 → 1 over a span, clamped; interpolation; clamping (default 0 to 1) |
+| `ease.linear`, `in`, `out`, `inOut`, `outExpo`, `outBack`, `spring(damping?, frequency?)` | Curves 0 → 1 (cubic `in`, `out`, `inOut`; `spring` defaults 7, 3.2). Any `(x) => number` is an `Ease` |
+| `stagger(i, gap)` | `i × gap` |
+| `rand(seed)` | A seeded random number generator: the same seed, the same numbers |
+| `fitText(el, { min, max })` | The largest font size at which `el`'s text fits its own box; sets it |
+| `splitText(text, by?)` | `"words"` (default), `"chars"`, or a separator |
+| `countText(value, x, from?)` | `"$1,200.5M"` counting: its number `x` (0 → 1) of the way from `from`, keeping what is round it, its decimals and separators |
+| `readMarks(line)`, `markRuns(text, marks)`, `withoutMarks(line)` | A line's marks read into its text and `InlineMark`s; as runs; the line without them |
+| `pathLength(d)`, `pointAtLength(d, l)`, `tangentAtLength(d, l)` | An SVG path measured without the browser |
+| `drawOn(d, progress)` | `{ strokeDasharray, strokeDashoffset }` showing the first `progress` of a stroke |
+| `trimPath(d, from, to)`, `interpolatePath(a, b, x)`, `normalizePath(d)` | A stretch of a path (fractions of its length); the path between two with the same commands (it throws otherwise); absolute commands |
+| `noise2D(seed, x, y)`, `noise3D(seed, x, y, z)`, `noise4D(seed, x, y, z, w)` | Seeded simplex noise in [−1, 1], changing over about one unit |
+
+## A person's input
+
+A cursor, a fingertip, a scrolled list or a field typed into, as functions of time: aimed movements that settle, land a little off their target and tremble, each drawn differently by `seed` and `index`. They place nothing: the piece says where and when, and draws what they return. Defaults: `INPUT_DEFAULTS` ([defaults.md](defaults.md)).
+
+| Function | Returns |
+| --- | --- |
+| `pointer({ from, steps: [{ at, to, size?, press?, duration?, dwell?, hold? }], dwell?, hold?, …reach })` | `{ at(t) → { x, y, down }, moves, presses }` |
+| `reach(from, to, { end, duration?, size?, index? }, reach?)` | One movement: `{ start, end, from, to, at(t), progress(u), bow }` |
+| `tap({ at, to, hold?, slide?, grow?, size?, scatter?, seed?, index? })` | `{ down, up, at(t) → { x, y, down, contact } }` |
+| `drag({ from, to, at, duration?, size?, settle?, release?, index?, …reach })` | `{ down, start, end, up, to, at(t) → { x, y, down } }` |
+| `scroll({ at, by, kind?, limit?, wheel?, flick?, seed?, index? })` | `{ start, end, at(t) → px }`: `"flick"` (default) with momentum, or `"wheel"` notches |
+| `typing(text, { at, cps?, spread?, word?, mark?, think?, mistakes?, notice?, backspace?, seed? })` | `{ keys, times, end, text(t) }`; `mistakes: [{ at, typed }]` types one and corrects it (none unless asked) |
+| `fittsTime(distance, size, fitts?)` | `a + b · log2(1 + distance / size)` seconds |
+| `aimed({ overshoot?, peak?, primary?, vary?, seed?, index? })` | An aimed movement's progress as an ease, 0 → 1 |
+
+The reach options are `overshoot`, `peak`, `vary`, `fitts: { a, b }`, `scatter`, `jitter`, `bow`, `tremor: { px, frequency }` and `seed`.
+
+```ts
+import { custom, pointer } from "@allyhub/sdk";
+import { h, one, tag } from "@allyhub/sdk/dom";
+
+const hand = pointer({
+  from: [200, 900],
+  steps: [
+    { at: 1, to: [960, 540], size: 120, press: true },
+    { at: 2.4, to: [1400, 300] },
+  ],
+});
+
+export const cursor = custom({
+  mount(el) {
+    el.append(
+      tag(
+        h("div", {
+          position: "absolute",
+          width: 24,
+          height: 24,
+          borderRadius: 12,
+          background: "var(--ak-color-fg)",
+        }),
+        "cursor",
+      ),
+    );
+  },
+  render(el, t) {
+    const dot = one(el, "cursor");
+    if (!dot) return;
+    const p = hand.at(t);
+    dot.style.transform = `translate(${String(p.x - 12)}px, ${String(p.y - 12)}px) scale(${p.down ? "0.8" : "1"})`;
+  },
+});
+```
+
+## Starter components
+
+The SDK has no components of its own. `allyhub add <name>` (`caption-line` or `captionLine`) copies a starter component's source into the project's `components/`, where it is the project's code; `allyhub add` alone lists them. Each documents its props in its source, every value a prop with a default (its `*_DEFAULTS` constant where it has one): read it after adding. Import it by a relative path. Only mechanisms are provided, never a layout: a title, a list or an end card is the piece's own `custom()` or component.
+
+| Component | What it does |
+| --- | --- |
+| `screenDemo` (and `uiDemo`, same file) | A demo on a screenshot with its elements file (`allyhub frames web`), or on an interface drawn in code: a camera in on what is acted on, a cursor that travels and clicks, typing, presses |
+| `codePanel` | Code, data or a terminal in a panel: coloured, typed or revealed, lines and spans highlighted in time |
+| `callout` | Marks places (a box, or another layer's element, followed), labels them, draws lines between them |
+| `chart` | Bars, horizontal bars, a line or a ring, with its scale, labels fitted and the draw-on |
+| `captionWord`, `captionLine`, `captionSubtitle` | Captions from `ctx.captions()`: a word at a time; a line with the word being said marked; a quiet subtitle |

package/docs/modeling.md

@@ -0,0 +1,143 @@
+# Modeling props
+
+A prop no library has is modelled in code with `@allyhub-next/model`: a subset of Blender 4.5's data API (`bpy.data`, `bmesh`, modifiers, materials, curves, UVs) in TypeScript, evaluated without Blender, the same in `allyhub model` and in a scenery's page. This file covers a model module, how it is built and measured, and how a scenery shows it. What the subset holds, every option and each deliberate difference from Blender, is `allyhub model capabilities` (JSON; also `capabilities` from `@allyhub-next/model`): a call outside it fails and names what is missing.
+
+## A model module
+
+A model module's default export is `defineModel(build)`. It is code, not an item: keep it in the folder of the scenery that uses it, or in `components/` when several do. `@allyhub-next/model` is lent by the CLI, with no `package.json` entry.
+
+```ts file=room/stick.ts
+import { defineModel } from "@allyhub-next/model";
+
+export default defineModel((bpy, parameters) => {
+  const length = Number(parameters["length"] ?? 0.3);
+  const mesh = bpy.data.meshes.new("Stick");
+  mesh.from_pydata(
+    [
+      [0, 0, 0],
+      [0, 0.004, 0],
+      [-length, 0.004, 0],
+      [-length, 0, 0],
+    ],
+    [
+      [0, 1],
+      [1, 2],
+      [2, 3],
+    ],
+    [],
+  );
+  const stick = bpy.data.objects.new("Stick", mesh);
+  bpy.context.collection.objects.link(stick);
+  const lathe = stick.modifiers.new("Lathe", "SCREW");
+  lathe.axis = "X";
+  lathe.use_merge_vertices = true;
+  lathe.merge_threshold = 1e-6;
+  const brass = bpy.data.materials.new("Brass");
+  brass.diffuse_color = [0.8, 0.6, 0.3, 1];
+  brass.metallic = 1;
+  brass.roughness = 0.2;
+  mesh.materials.append(brass);
+});
+```
+
+- `build(bpy, parameters)` may be async. `parameters` is plain JSON (`--args`, or a scenery's call). `bpy.random()` is seeded (`--param seed=`, default 0); `Math.random()` is not.
+- There is no `bpy.ops`: no edit mode, selection or active object. `bmesh.ops.*` take the geometry they act on and return the new geometry, as in Blender's Python. `applyModifier(bpy, object, { modifier })` applies one named modifier to its base mesh (Blender's `modifier_apply`).
+- Relative imports name their extension (`./parts.ts`); only erasable TypeScript.
+- An object's name is what the scenery commands and measurements call it; a taken name gets Blender's suffix (`Part.001`).
+
+**Axes.** Blender's: right-handed, **Z up**, metres, **radians** (Euler XYZ), unlike a scenery (Y up, degrees). The GLB and `modelObject` turn Z up to Y up with one root rotation: Blender's (x, y, z) is the scenery's (x, z, −y). Blender's length defaults are sized for a room (Bevel `width` 0.1 m, Solidify `thickness` 0.01 m, Screw and Array `merge_threshold` 0.01 m, Mirror 0.001 m): a hand-sized prop sets its own.
+
+## A soft shape: a distance field
+
+A shape with no edges (a foam hand, a pebble) can be written as a signed distance field, `Field = (p) => number`, negative inside. `meshField(field, { min, max, cell, project?, maxSamples? })` meshes it by surface nets, each vertex moved onto the surface by `project` Newton steps (default 3), refusing a grid over `maxSamples` (default 40 million; `FIELD_DEFAULTS`). It gives `{ vertices, faces, closed, samples }`: faces counterclockwise seen from outside, `closed` when the field is outside on all of the box's faces.
+
+```ts file=room/hand.ts
+import {
+  capsule,
+  defineModel,
+  ellipsoid,
+  meshField,
+  smoothUnion,
+  type Vec3,
+} from "@allyhub-next/model";
+
+export default defineModel((bpy) => {
+  // Millimetres while it is written, metres when it is made.
+  const fist = (p: Vec3) =>
+    smoothUnion(
+      ellipsoid(p, [-11, 0, 0], [13, 12.6, 10.8]),
+      capsule(p, [0, 0, 2], [26, 0, 6], 5.3, 4.5),
+      3.2,
+    );
+  const m = meshField(fist, {
+    min: [-36, -17, -17],
+    max: [34, 17, 16],
+    cell: 0.5,
+  });
+  const mesh = bpy.data.meshes.new("Hand");
+  mesh.from_pydata(
+    m.vertices.map(([x, y, z]): Vec3 => [x / 1000, y / 1000, z / 1000]),
+    [],
+    m.faces,
+  );
+  mesh.shade_smooth();
+  bpy.context.collection.objects.link(bpy.data.objects.new("Hand", mesh));
+});
+```
+
+| Helper | The shape |
+| --- | --- |
+| `sphere(p, center, radius)` | A ball |
+| `box(p, center, half, round = 0)` | A box of half-sizes `half`, its edges rounded inside it |
+| `capsule(p, a, b, ra, rb = ra)` | From `a` to `b`, its radius running from `ra` to `rb` |
+| `ellipsoid(p, center, radii)` | Radii along the axes (exact on its surface) |
+| `torus(p, center, axis, major, minor)` | Round `"x"`, `"y"` or `"z"` |
+| `cylinder(p, a, b, radius, round = 0)` | From `a` to `b`, its rims rounded |
+| `smoothUnion(d1, d2, k)`, `smoothIntersect`, `smoothSubtract` | Joined, intersected or cut, the seam rounded `k` wide |
+
+The surface's detail is about one `cell`.
+
+## Build and measure
+
+- `allyhub model <file> --inspect` evaluates it without writing anything: each object's parent, matrix, bounds after its modifiers (Blender's Z-up metres), triangles, materials as glTF reads them, UV layers, a curve's splines, and the objects left with no triangles.
+- `allyhub model <file>` writes a GLB (Y up), by default `.allyhub/out/<module>.glb` (the folder's name for a `model.ts`); `--out` names another (`assets/media/models/<name>.glb` to load it as media). A failed build leaves the last GLB in place.
+- A build is kept in `.allyhub/cache/model/` while the module, the files it read, its folder's files, its parameters and seed are unchanged; `--fresh` builds anew.
+- The program is trusted project code, run in a child process; its logs go to stderr. An error names the call and the place in the project's files it failed at.
+- A subdivision surface lies inside its cage: measure the surface (`--inspect`), not the cage.
+
+## In a scenery
+
+`modelObject(w, model, parameters?, options?)` from `@allyhub-next/model/three` builds the model in the scenery's page, drawn as its GLB is, its images read through `w.texture`. It returns a `Group` not yet in the scene, whose own rotation turns Z up to Y up: place and turn it inside a group of the scenery's own. A model built once into a GLB loads as any model instead (`import`, `w.load`), and stays as built until built again.
+
+```ts file=room/scenery.ts
+import { Group, Mesh, MeshPhysicalMaterial } from "three";
+import { defineScenery } from "@allyhub-next/scenery-host/layer";
+import { modelObject } from "@allyhub-next/model/three";
+import stick from "./stick.ts";
+
+export default defineScenery({
+  async build(w) {
+    const held = new Group();
+    held.name = "stick";
+    held.add(await modelObject(w, stick, { length: 0.32 }));
+    w.scene.add(held);
+    held.traverse((o) => {
+      // A lacquer over the brass, which glTF's metallic-roughness cannot say.
+      if (
+        o instanceof Mesh &&
+        (o.material as MeshPhysicalMaterial).name === "Brass"
+      )
+        o.material = new MeshPhysicalMaterial({
+          color: 0xc89a4a,
+          metalness: 1,
+          roughness: 0.25,
+          clearcoat: 1,
+        });
+    });
+  },
+});
+```
+
+- **Materials** are glTF's metallic-roughness: the Principled BSDF's base colour, metallic, roughness, alpha, normal and emission, from values or images; anything else fails with `unsupported_material`, naming the node and socket. Each three.js material keeps its Blender material's name, so a scenery replaces one by name to draw what glTF cannot say (sheen, clearcoat, transmission).
+- **Images**: `bpy.data.images.load(path)` takes a PNG or JPEG. A path that starts with `./` or `../` is from the module that draws the model (the scenery's module in a scenery, the model's own for `allyhub model`); any other is from the project's root.
+- A model used as a scenery prop for one video only is a `SceneryProp` whose `build` calls `modelObject` ([scenery.md](scenery.md#the-scenery-layer)).