@johnmorrisdotca/uchusen-rockets 0.2.2 → 0.4.0

package/dist/build/index.d.ts

@@ -3,12 +3,38 @@ import { type Angle, type Vec3, type ViewName } from "../framing.ts";
 import { type LookName } from "../looks.ts";
 import { type PartMesh, type Bounds, type Piece } from "../model/pieces.ts";
 import type { PartRecord } from "../parts.ts";
+import { type LitBell } from "../engines.ts";
 import { type Glb, toGlb } from "./glb.ts";
-/** Raised when a description does not fit: its report says why. */
+/**
+ * Raised by `build` when a description does not fit. Its `report` says why, in the same words `check` gives.
+ *
+ * @param report The report of the fit check that failed.
+ * @example
+ * ```ts
+ * import { build, FitError } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * try {
+ *   build({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * } catch (error) {
+ *   if (error instanceof FitError) console.log(error.report.issues[0]?.message);
+ * }
+ * ```
+ */
 export declare class FitError extends Error {
     readonly report: FitReport;
     constructor(report: FitReport);
 }
+/**
+ * One part of a built rocket: its slot, its record, the pieces it is made of, its mesh and its bounds in metres.
+ *
+ * @example
+ * ```ts
+ * import { build, type BuiltPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const first: BuiltPart | undefined = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(first?.slot, first?.record.name);
+ * ```
+ */
 export interface BuiltPart {
     slot: string;
     record: PartRecord;
@@ -16,37 +42,101 @@ export interface BuiltPart {
     mesh: PartMesh;
     bounds: Bounds;
 }
+/**
+ * What a drawing is asked for: the look, the view, what to show and whether the engines are lit. Anything left out takes its default.
+ *
+ * @example
+ * ```ts
+ * import { build, type SvgOptions } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const options: SvgOptions = { look: "thick", view: "below", show: "booster" };
+ * console.log(build({ rocket: "starship", variant: "v3" }).svg(options).startsWith("<svg"));
+ * ```
+ */
 export interface SvgOptions {
     look?: LookName;
     view?: ViewName | Angle;
     show?: string;
+    /** A flame at each engine that is showing, or as many as a count names for each part. The length is a picture, not a measured flame. Left out, the drawing is unchanged. */
+    engines?: boolean | Readonly<Record<string, number>>;
 }
+/**
+ * A rocket built from a description: the fit report, its parts, and the ways to ask for its size, where each part stands, its lit engines, a `.glb` file and a drawing.
+ *
+ * @example
+ * ```ts
+ * import { build, type Built } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket: Built = build({ rocket: "starship", variant: "v3" });
+ * console.log(rocket.shows.join(", "));
+ * console.log(rocket.boundsOf("together").max);
+ * ```
+ */
 export interface Built {
     report: FitReport;
     parts: readonly BuiltPart[];
     /** What can be shown: together, apart and each part. */
     shows: readonly string[];
-    /** The bounds of a choice of what to show, in metres. */
-    boundsOf(show?: string): Bounds;
+    /** The bounds of a choice of what to show, in metres, and with `lit` the flames of its engines at full thrust. */
+    boundsOf(show?: string, lit?: boolean): Bounds;
     /** Where each part stands for a choice of what to show. */
     placesOf(show?: string): {
         slot: string;
         at: Vec3;
         shown: boolean;
     }[];
+    /** The engines alight at full thrust for a choice of what to show: those the drawing has, of the parts whose engines a source tells of. */
+    flamesOf(show?: string): LitBell[];
     /** The .glb file's bytes: every part stacked, each its own node to move. */
     glb(): Glb;
     /** The drawing, in a look, from an angle. */
     svg(options?: SvgOptions): string;
 }
-/** What a drawing draws of a part: in a stack, what nests inside the part below is out of sight. */
+/**
+ * What a drawing draws of a part: in a stack, what nests inside the part below is out of sight.
+ *
+ * @param part A built part: its record and its pieces.
+ * @param together True when the part stands in a stack, false when it is shown alone.
+ * @returns The pieces to draw. In a stack, what nests inside the part below is left out.
+ * @example
+ * ```ts
+ * import { build, drawnPieces } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const [first] = build({ rocket: "falcon-9", variant: "block-5" }).parts;
+ * if (first) console.log(drawnPieces(first, true).length, drawnPieces(first, false).length);
+ * ```
+ */
 export declare function drawnPieces(part: {
     record: PartRecord;
     pieces: readonly Piece[];
 }, together: boolean): readonly Piece[];
-/** A rocket from a description. Throws FitError when it does not go together. */
+/**
+ * A rocket from a description. Throws FitError when it does not go together.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns The built rocket. It throws a `FitError` when the description does not go together.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-heavy" });
+ * console.log(rocket.report.label, rocket.glb().bytes.length > 1000);
+ * ```
+ */
 export declare function build(description: Description): Built;
-/** One part on its own, by its id. */
+/**
+ * One part on its own, by its id.
+ *
+ * @param id A part's id, as `PART_ENTRIES` lists it.
+ * @returns The part's record and bounds, a function for its `.glb` and one for its drawing. It throws for an id that is not a part.
+ * @example
+ * ```ts
+ * import { buildPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const raptor = buildPart("raptor-vacuum");
+ * console.log(raptor.record.name, raptor.bounds.max);
+ * ```
+ */
 export declare function buildPart(id: string): {
     record: PartRecord;
     bounds: Bounds;

package/dist/build/index.js

@@ -5,9 +5,25 @@ import { cleanShow, placesFor, showsOf } from "../layout.js";
 import { DEFAULT_LOOK } from "../looks.js";
 import { boundsOf, meshOf } from "../model/pieces.js";
 import { partEntry } from "../model/registry.js";
+import { plumeMarkup } from "../draw/plume.js";
 import { defsOf, drawPart, perspective } from "../draw/svg.js";
+import { bellsOf, litBells, pickBells, plumeLength } from "../engines.js";
 import { toGlb } from "./glb.js";
-/** Raised when a description does not fit: its report says why. */
+/**
+ * Raised by `build` when a description does not fit. Its `report` says why, in the same words `check` gives.
+ *
+ * @param report The report of the fit check that failed.
+ * @example
+ * ```ts
+ * import { build, FitError } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * try {
+ *   build({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * } catch (error) {
+ *   if (error instanceof FitError) console.log(error.report.issues[0]?.message);
+ * }
+ * ```
+ */
 export class FitError extends Error {
     report;
     constructor(report) {
@@ -47,7 +63,15 @@ function assembled(report) {
     });
     const slots = parts.map((part) => part.slot);
     const placesOf = (show) => placesFor(report.parts, cleanShow(show, slots), (part) => widthOf(part.id));
-    const boundsOfShow = (show) => {
+    const flamesOf = (show) => {
+        const places = placesOf(show);
+        return litBells(places.map((place) => {
+            const part = parts.find((p) => p.slot === place.slot);
+            const told = report.variant?.facts.engines[part.slot]?.value;
+            return { slot: part.slot, atY: place.at[1], shown: place.shown, pieces: part.pieces, beside: place.at[0] !== 0 || place.at[2] !== 0, dark: told === null || told === undefined };
+        }), !show || show === "together");
+    };
+    const boundsOfShow = (show, lit = false) => {
         const min = [Infinity, Infinity, Infinity];
         const max = [-Infinity, -Infinity, -Infinity];
         for (const place of placesOf(show)) {
@@ -59,6 +83,11 @@ function assembled(report) {
                 max[c] = Math.max(max[c], bounds.max[c] + place.at[c]);
             }
         }
+        if (lit)
+            for (const bell of flamesOf(show)) {
+                const place = placesOf(show).find((one) => one.slot === bell.slot);
+                min[1] = Math.min(min[1], (place?.at[1] ?? 0) + bell.y - plumeLength(bell.exit));
+            }
         return { min, max };
     };
     return {
@@ -67,11 +96,13 @@ function assembled(report) {
         shows: showsOf(slots),
         boundsOf: boundsOfShow,
         placesOf,
+        flamesOf,
         glb: () => toGlb(parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: placesOf("together").find((place) => place.slot === part.slot)?.at ?? [0, 0, 0] }))),
-        svg: ({ look = DEFAULT_LOOK, view = DEFAULT_VIEW, show } = {}) => {
+        svg: ({ look = DEFAULT_LOOK, view = DEFAULT_VIEW, show, engines = false } = {}) => {
             const angle = typeof view === "string" ? VIEWS[cleanView(view)] : view;
             const places = placesOf(show).filter((place) => place.shown);
-            const cam = perspective(boundsOfShow(show), angle);
+            // a flame drawn at full thrust is held in the picture; a count of engines is the timeline's, which has its own room
+            const cam = perspective(boundsOfShow(show, engines === true), angle);
             const ordered = places
                 .map((place) => {
                 const part = parts.find((p) => p.slot === place.slot);
@@ -80,25 +111,69 @@ function assembled(report) {
             })
                 .sort((a, b) => b.depth - a.depth);
             const together = !show || show === "together";
-            return wrap(ordered.map(({ place, part }) => drawPart(drawnPieces(part, together), place.at, cam, look)).join(""), look, PICTURE_W, PICTURE_H, report.label);
+            const flames = typeof engines === "object"
+                ? parts.flatMap((part) => pickBells(bellsOf(part.pieces), engines[part.slot] ?? 0).map((bell) => ({ ...bell, slot: part.slot })))
+                : engines
+                    ? flamesOf(show).filter((bell) => places.some((place) => place.slot === bell.slot))
+                    : [];
+            return wrap(ordered
+                .map(({ place, part }) => drawPart(drawnPieces(part, together), place.at, cam, look) + plumeMarkup(flames.filter((bell) => bell.slot === place.slot), place.at, cam, look, part.slot))
+                .join(""), look, PICTURE_W, PICTURE_H, report.label);
         },
     };
 }
-/** What a drawing draws of a part: in a stack, what nests inside the part below is out of sight. */
+/**
+ * What a drawing draws of a part: in a stack, what nests inside the part below is out of sight.
+ *
+ * @param part A built part: its record and its pieces.
+ * @param together True when the part stands in a stack, false when it is shown alone.
+ * @returns The pieces to draw. In a stack, what nests inside the part below is left out.
+ * @example
+ * ```ts
+ * import { build, drawnPieces } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const [first] = build({ rocket: "falcon-9", variant: "block-5" }).parts;
+ * if (first) console.log(drawnPieces(first, true).length, drawnPieces(first, false).length);
+ * ```
+ */
 export function drawnPieces(part, together) {
     const joint = part.record.joints.bottom?.y ?? 0;
     if (!together || joint <= 0)
         return part.pieces;
     return part.pieces.filter((piece) => !(piece.kind === "lathe" && piece.under && Math.max(...piece.profile.map(([, y]) => y)) <= joint + 0.01));
 }
-/** A rocket from a description. Throws FitError when it does not go together. */
+/**
+ * A rocket from a description. Throws FitError when it does not go together.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns The built rocket. It throws a `FitError` when the description does not go together.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-heavy" });
+ * console.log(rocket.report.label, rocket.glb().bytes.length > 1000);
+ * ```
+ */
 export function build(description) {
     const report = check(description);
     if (!report.ok)
         throw new FitError(report);
     return assembled(report);
 }
-/** One part on its own, by its id. */
+/**
+ * One part on its own, by its id.
+ *
+ * @param id A part's id, as `PART_ENTRIES` lists it.
+ * @returns The part's record and bounds, a function for its `.glb` and one for its drawing. It throws for an id that is not a part.
+ * @example
+ * ```ts
+ * import { buildPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const raptor = buildPart("raptor-vacuum");
+ * console.log(raptor.record.name, raptor.bounds.max);
+ * ```
+ */
 export function buildPart(id) {
     const entry = partEntry(id);
     if (!entry)

package/dist/build/lineup.d.ts

@@ -1,6 +1,15 @@
 import { type ViewName } from "../framing.ts";
 import { type LookName } from "../looks.ts";
-/** Comparison shapes: plain round sizes, for scale, not facts about anything. */
+/**
+ * Comparison shapes: plain round sizes, for scale, not facts about anything.
+ *
+ * @example
+ * ```ts
+ * import { COMPARES } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * console.log(COMPARES.person.height, COMPARES.building.height);
+ * ```
+ */
 export declare const COMPARES: {
     readonly person: {
         readonly name: "A person, 1.8 m";
@@ -13,13 +22,46 @@ export declare const COMPARES: {
         readonly width: 18;
     };
 };
+/**
+ * The name of a comparison shape that can stand in a lineup: `person` or `building`.
+ *
+ * @example
+ * ```ts
+ * import type { CompareId } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const id: CompareId = "person";
+ * console.log(id);
+ * ```
+ */
 export type CompareId = keyof typeof COMPARES;
+/**
+ * One thing standing in a lineup: its key (`starship:v3` or a comparison's name), its label and its height in metres.
+ *
+ * @example
+ * ```ts
+ * import { lineupSvg, type LineupItem } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const items: LineupItem[] = lineupSvg({ items: ["starship:v3", "person"], unit: 3 }).items;
+ * console.log(items.map((item) => item.label));
+ * ```
+ */
 export interface LineupItem {
     /** "starship:v3" or a comparison's name. */
     key: string;
     label: string;
     height: number;
 }
+/**
+ * What a lineup is asked for: the items by key, how many pixels make a metre, and optionally the look, the view, what to show, a ruler and labels.
+ *
+ * @example
+ * ```ts
+ * import { lineupSvg, type LineupOptions } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const options: LineupOptions = { items: ["starship:v2", "starship:v3", "building"], unit: 3, ruler: true, labels: true };
+ * console.log(lineupSvg(options).width);
+ * ```
+ */
 export interface LineupOptions {
     /** "starship:v1,starship:v3,person,building". */
     items: readonly string[];
@@ -31,7 +73,19 @@ export interface LineupOptions {
     ruler?: boolean;
     labels?: boolean;
 }
-/** The whole picture as SVG text. Unknown items are left out. */
+/**
+ * The whole picture as SVG text. Unknown items are left out.
+ *
+ * @param options The items and how they are drawn.
+ * @returns The picture as SVG text, the items it holds, and its width and height.
+ * @example
+ * ```ts
+ * import { lineupSvg } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const picture = lineupSvg({ items: ["falcon-9:block-5", "falcon-heavy:falcon-heavy", "person"], unit: 4, ruler: true });
+ * console.log(picture.items.length, picture.svg.startsWith("<svg"));
+ * ```
+ */
 export declare function lineupSvg(options: LineupOptions): {
     svg: string;
     items: LineupItem[];

package/dist/build/lineup.js

@@ -4,14 +4,31 @@ import { check } from "../fit.js";
 import { axesOf, cleanView, directionOf, VIEWS } from "../framing.js";
 import { DEFAULT_LOOK, LOOKS } from "../looks.js";
 import { defsOf, drawPart, orthographic } from "../draw/svg.js";
+import { MATERIALS } from "../model/materials.js";
 import { variantOf } from "../rockets.js";
-/** Comparison shapes: plain round sizes, for scale, not facts about anything. */
+/**
+ * Comparison shapes: plain round sizes, for scale, not facts about anything.
+ *
+ * @example
+ * ```ts
+ * import { COMPARES } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * console.log(COMPARES.person.height, COMPARES.building.height);
+ * ```
+ */
 export const COMPARES = {
     person: { name: "A person, 1.8 m", height: 1.8, width: 0.5 },
     building: { name: "A ten-storey building, 30 m", height: 30, width: 18 },
 };
 const xmlText = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const n = (v) => (Math.round(v * 10) / 10).toString();
+/** A rocket painted black all over vanishes on the dark ground of a lineup, so it takes the line look's colour for its outline. Only the lines change: its shape and its figures stay. */
+const edgeOf = (built, look) => {
+    if (look !== "painted")
+        return undefined;
+    const hulls = built.parts.flatMap((part) => part.pieces).filter((piece) => piece.kind === "lathe" && piece.body);
+    return hulls.length && hulls.every((piece) => piece.kind === "lathe" && MATERIALS[piece.material].fill === "dark") ? LOOKS.line.line : undefined;
+};
 function comparison(id, x, base, unit, line, fill) {
     const { height, width } = COMPARES[id];
     const h = height * unit;
@@ -25,7 +42,19 @@ function comparison(id, x, base, unit, line, fill) {
         floors += `M${n(x)} ${n(base - (h * i) / 10)}h${n(w)}`;
     return `<rect x="${n(x)}" y="${n(base - h)}" width="${n(w)}" height="${n(h)}" fill="${fill}" stroke="${line}" stroke-width=".9"/><path d="${floors}" stroke="${line}" stroke-width=".35" opacity=".6"/>`;
 }
-/** The whole picture as SVG text. Unknown items are left out. */
+/**
+ * The whole picture as SVG text. Unknown items are left out.
+ *
+ * @param options The items and how they are drawn.
+ * @returns The picture as SVG text, the items it holds, and its width and height.
+ * @example
+ * ```ts
+ * import { lineupSvg } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const picture = lineupSvg({ items: ["falcon-9:block-5", "falcon-heavy:falcon-heavy", "person"], unit: 4, ruler: true });
+ * console.log(picture.items.length, picture.svg.startsWith("<svg"));
+ * ```
+ */
 export function lineupSvg(options) {
     const { items, unit, look = DEFAULT_LOOK, view = "front", ruler = true, labels = true } = options;
     const angle = VIEWS[cleanView(view)];
@@ -67,14 +96,16 @@ export function lineupSvg(options) {
             body.push(comparison(item.compare, cx - (COMPARES[item.compare].width * unit) / 2, base, unit, line, "url(#metal)"));
         else if (item.built) {
             const show = options.show && item.built.shows.includes(options.show) ? options.show : item.built.shows[0];
-            const cam = orthographic(angle, unit, cx, base);
+            const faced = cleanView(view) === "front" ? variantOf(item.key.split(":")[0], item.key.split(":")[1])?.lineupView : undefined;
+            const facing = faced ? VIEWS[faced] : angle;
+            const cam = orthographic(facing, unit, cx, base);
             const places = item.built.placesOf(show).filter((place) => place.shown);
-            const { right, forward } = axesOf(directionOf(angle));
-            void right;
+            const { forward } = axesOf(directionOf(facing));
+            const edge = edgeOf(item.built, look);
             for (const place of places.sort((a, b) => b.at[0] * forward[0] + b.at[2] * forward[2] - a.at[0] * forward[0] - a.at[2] * forward[2])) {
                 const part = item.built.parts.find((p) => p.slot === place.slot);
                 if (part)
-                    body.push(drawPart(drawnPieces(part, show === "together"), place.at, cam, look, 0.7));
+                    body.push(drawPart(drawnPieces(part, show === "together"), place.at, cam, look, 0.7, edge));
             }
         }
         if (labels) {

package/dist/builder.d.ts

@@ -0,0 +1,68 @@
+import { type Description, type FitReport } from "./fit.ts";
+/**
+ * One part a row of the builder offers: its id, its name and the rocket it comes from.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderOption } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const first: BuilderOption | undefined = builderState().rows[0]?.options[0];
+ * console.log(first);
+ * ```
+ */
+export interface BuilderOption {
+    id: string;
+    name: string;
+    /** Which rocket it comes from, to group a long list. */
+    rocket: string;
+}
+/**
+ * One row of the builder, from the bottom: what it chooses, the parts it offers, the one chosen, and whether the builder made the choice because only one part fits.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderRow } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const row: BuilderRow | undefined = builderState().rows[0];
+ * console.log(row?.label, row?.chosen, row?.auto);
+ * ```
+ */
+export interface BuilderRow {
+    /** What this row chooses. */
+    label: string;
+    options: readonly BuilderOption[];
+    chosen: string;
+    /** One answer only: the builder made the choice. */
+    auto: boolean;
+}
+/**
+ * What the builder shows for a set of picks: its rows, the description they make and the fit report for it.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const state: BuilderState = builderState();
+ * console.log(state.rows.length, state.report.ok);
+ * ```
+ */
+export interface BuilderState {
+    rows: readonly BuilderRow[];
+    description: Description;
+    report: FitReport;
+}
+/**
+ * The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits.
+ *
+ * @param picks The part ids chosen so far, row by row from the bottom. Leave it out to start.
+ * @returns The rows to show, the description they make and its fit report.
+ * @example
+ * ```ts
+ * import { builderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const start = builderState();
+ * const next = builderState([start.rows[0]?.chosen ?? ""]);
+ * console.log(next.description, next.report.label);
+ * ```
+ */
+export declare function builderState(picks?: readonly string[]): BuilderState;

package/dist/builder.js

@@ -0,0 +1,116 @@
+// What the part builder offers. A rocket from parts of every rocket, row by row from the bottom: each row offers only what fits on the row below, a row with one answer is answered for the reader, and a change lower down carries what still fits and makes a fresh choice for the rest. So the builder can never reach a rocket that does not go together, and `check` still has the last word. Everything comes from `ROCKETS` and `PART_ENTRIES`, so a new rocket is offered with no change here. Pure.
+import { check, JOINT_TOLERANCE } from "./fit.js";
+import { partEntry, PART_ENTRIES } from "./model/registry.js";
+import { partIdOf, ROCKETS, SLOT_NAMES } from "./rockets.js";
+function framesOf() {
+    const frames = [];
+    for (const rocket of Object.values(ROCKETS))
+        for (const variant of rocket.variants) {
+            const homes = variant.slots.map((slot) => partEntry(partIdOf(variant.rocket, variant.id, slot))?.record);
+            if (homes.every(Boolean))
+                frames.push({ rocket: rocket.id, variant: variant.id, slots: variant.slots, homes: homes });
+        }
+    return frames;
+}
+/** A part can stand in a slot when it is the same kind of part and joins the same ways as the slot's own. */
+const sameShape = (part, home) => part.kind === home.kind && Boolean(part.joints.top) === Boolean(home.joints.top) && Boolean(part.joints.bottom) === Boolean(home.joints.bottom) && part.strapOn?.x === home.strapOn?.x && part.strapOn?.z === home.strapOn?.z;
+/** It sits on what is below it. */
+const fitsOn = (part, below) => {
+    if (!below)
+        return true;
+    const { top } = below.joints;
+    const { bottom } = part.joints;
+    return Boolean(top && bottom && top.kind === bottom.kind && Math.abs(top.diameter - bottom.diameter) <= JOINT_TOLERANCE);
+};
+const REAL_PARTS = () => PART_ENTRIES.map(({ record }) => record).filter((record) => record.trueTo.length > 0);
+const optionOf = (part) => ({ id: part.id, name: part.name, rocket: ROCKETS[part.rocket]?.name ?? part.rocket });
+/**
+ * The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits.
+ *
+ * @param picks The part ids chosen so far, row by row from the bottom. Leave it out to start.
+ * @returns The rows to show, the description they make and its fit report.
+ * @example
+ * ```ts
+ * import { builderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const start = builderState();
+ * const next = builderState([start.rows[0]?.chosen ?? ""]);
+ * console.log(next.description, next.report.label);
+ * ```
+ */
+export function builderState(picks = []) {
+    const every = framesOf();
+    const parts = REAL_PARTS();
+    const rows = [];
+    const chosen = [];
+    // Only what can still be finished is offered: nothing on any row leads to a rocket with a part missing.
+    const known = new Map();
+    const finishes = (frame, row, below, foot) => {
+        if (row >= frame.slots.length)
+            return true;
+        const key = `${frame.rocket}/${frame.variant}/${row}/${below?.id}/${foot.id}`;
+        let answer = known.get(key);
+        if (answer === undefined) {
+            answer = fitting(frame, row, below, foot).length > 0;
+            known.set(key, answer);
+        }
+        return answer;
+    };
+    const fitting = (frame, row, below, foot) => {
+        const home = frame.homes[row];
+        // a part placed rather than stacked has no joint to mix at: it stands where its own variant puts it, by its own foot
+        if (home.strapOn)
+            return frame.homes[0].id === foot.id && finishes(frame, row + 1, below, foot) ? [home] : [];
+        return parts.filter((part) => sameShape(part, home) && fitsOn(part, below) && finishes(frame, row + 1, part, foot));
+    };
+    let alive = every;
+    for (let row = 0; alive.some((frame) => frame.slots.length > row); row++) {
+        // what a part sits on is the last one stacked: one placed beside the stack, a side booster or an orbiter, holds nothing up
+        const below = chosen.findLast((part) => !part.strapOn);
+        const candidates = (frame) => {
+            if (row >= frame.slots.length)
+                return [];
+            // the bottom row offers each rocket's own foot: what stands on it is what mixes
+            if (row === 0)
+                return [frame.homes[0]];
+            return fitting(frame, row, below, chosen[0]);
+        };
+        const offered = new Map();
+        for (const frame of alive)
+            for (const part of candidates(frame))
+                offered.set(part.id, part);
+        if (offered.size === 0)
+            break;
+        const options = [...offered.values()];
+        const asked = picks[row];
+        const pick = (asked !== undefined && offered.get(asked)) ||
+            // the next part of the real vehicle that everything so far belongs to, when there is one
+            alive.flatMap((frame) => (frame.slots.length > row && chosen.every((part, i) => frame.homes[i].id === part.id) ? [frame.homes[row]] : [])).find((part) => offered.has(part.id)) ||
+            // the part that flew with what is below it, when there is one
+            (below && options.find((part) => part.rocket === below.rocket && part.trueTo.some((id) => below.trueTo.includes(id)))) ||
+            options[0];
+        chosen.push(pick);
+        // the bottom row's own frames share one foot by shape; above it a frame stays while it can take the pick
+        alive = row === 0 ? every.filter((frame) => sameShape(pick, frame.homes[0])) : alive.filter((frame) => candidates(frame).some((part) => part.id === pick.id));
+        const slots = [...new Set(alive.filter((frame) => row < frame.slots.length).map((frame) => frame.slots[row]))];
+        rows.push({ label: slots.map((slot) => SLOT_NAMES[slot] ?? slot).join(" or "), options: options.map(optionOf), chosen: pick.id, auto: options.length === 1 });
+        // a real vehicle whole: nothing goes on top of it, even where a longer one shares its shape so far
+        if (alive.some((frame) => frame.slots.length === chosen.length && frame.homes.every((home, i) => home.id === chosen[i].id)))
+            break;
+    }
+    const whole = alive.filter((frame) => frame.slots.length === chosen.length);
+    const chosenSlot = (description) => whole.find((frame) => frame.rocket === description.rocket && frame.variant === description.variant)?.slots[0] ?? "";
+    const described = whole.map((frame) => {
+        const named = Object.fromEntries(frame.slots.flatMap((slot, i) => (frame.homes[i].id === chosen[i].id ? [] : [[slot, chosen[i].id]])));
+        return { rocket: frame.rocket, variant: frame.variant, ...(Object.keys(named).length > 0 ? { parts: named } : {}) };
+    });
+    // the name of a real vehicle where these parts are one; a custom build otherwise, and it says so
+    // and, of those, the version it has most parts of, so a custom build is said the plainest way
+    const swapped = (description) => Object.keys(description.parts ?? {});
+    const reports = described
+        // a tie goes to the version of the bottom part: it is the one the reader chose first
+        .sort((a, b) => swapped(a).length - swapped(b).length || Number(swapped(a).includes(chosenSlot(a))) - Number(swapped(b).includes(chosenSlot(b))))
+        .map((description) => ({ description, report: check(description) }));
+    const best = reports.find(({ report }) => report.ok && !report.custom) ?? reports.find(({ report }) => report.ok) ?? reports[0];
+    return { rows, description: best.description, report: best.report };
+}