@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/dist/embed.d.ts

@@ -1,26 +1,131 @@
 import { type RocketOptions } from "./attrs.ts";
+/**
+ * The six ways `embedCode` writes a rocket for another page: `element`, `iframe`, `module`, `svg`, `data` and `link`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
 export declare const EMBED_KINDS: readonly ["element", "iframe", "module", "svg", "data", "link"];
+/**
+ * One of the ways in `EMBED_KINDS`.
+ *
+ * @example
+ * ```ts
+ * import type { EmbedKind } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const kind: EmbedKind = "iframe";
+ * console.log(kind);
+ * ```
+ */
 export type EmbedKind = (typeof EMBED_KINDS)[number];
+/**
+ * Where the embed code points: the address of the demo that holds `embed.html`, and the CDN folder the element loads from. Both default to this package's own.
+ *
+ * @example
+ * ```ts
+ * import { embedCode, type EmbedSettings } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const settings: EmbedSettings = { site: "https://example.test/rockets/" };
+ * console.log(embedCode({ rocket: "starship" }, "iframe", settings));
+ * ```
+ */
 export interface EmbedSettings {
     /** The address of the published demo, where `embed.html` is. */
     site?: string;
     /** The CDN or package path the element is loaded from. */
     cdn?: string;
 }
+/**
+ * The address of the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { SITE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SITE);
+ * ```
+ */
 export declare const SITE = "https://johnmorrisdotca.github.io/uchusen-rockets/";
+/**
+ * The folder on a CDN the element loads from when the embed is a plain script with no bundler.
+ *
+ * @example
+ * ```ts
+ * import { CDN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CDN);
+ * ```
+ */
 export declare const CDN = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/uchusen-rockets@0";
-/** The three.js a page with no bundler takes from the CDN: the version this package is built and tested with. */
+/**
+ * The three.js a page with no bundler takes from the CDN: the version this package is built and tested with.
+ *
+ * @example
+ * ```ts
+ * import { THREE_VERSION } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(THREE_VERSION);
+ * ```
+ */
 export declare const THREE_VERSION = "0.186.1";
-/** What an embed asks of the page around it, in words: a line for the demo to show. */
+/**
+ * What an embed asks of the page around it, in words: a line for the demo to show.
+ *
+ * @param kind Which way of embedding.
+ * @param options The rocket being embedded.
+ * @returns A line of text for the demo to show beside the code.
+ * @example
+ * ```ts
+ * import { embedNote } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedNote("iframe", { rocket: "starship" }));
+ * ```
+ */
 export declare function embedNote(kind: EmbedKind, options: RocketOptions): string;
 /**
- * The CC BY line for a painted rocket, generated from the parts that are showing.
- * Empty when the look is not painted, or when those parts are this package's own paint.
+ * The CC BY line for a painted rocket, generated from the parts that are showing. Empty when the look is not painted, or when those parts are this package's own paint.
+ *
+ * @param options The rocket as it will be drawn.
+ * @returns The credit line, or an empty text when nothing needs crediting.
+ * @example
+ * ```ts
+ * import { paintedCredit } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "painted" }));
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "line" }) === "");
+ * ```
  */
 export declare function paintedCredit(options: RocketOptions): string;
 /**
  * The shipped picture of these options, under the package's `dist/assets/`: `starship-v3.svg`, `falcon-9-block-5-apart.thick.svg`. These are drawn from the default view, with no flames. Null for a custom build, which has no file, or a variant, part or look that does not exist.
+ *
+ * @param options The rocket, variant, look, view and what to show.
+ * @returns The path of the shipped picture under `dist/assets/`, or null when none is shipped for those options.
+ * @example
+ * ```ts
+ * import { assetPathOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(assetPathOf({ rocket: "starship", variant: "v3" }));
+ * ```
  */
 export declare function assetPathOf(options: RocketOptions): string | null;
-/** The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`. */
+/**
+ * The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`.
+ *
+ * @param options The rocket and how it looks.
+ * @param kind Which way to write it. Defaults to the element.
+ * @param settings Where the demo and the CDN are, if not the package's own.
+ * @returns The text to paste into a page. A painted rocket's credit is part of it.
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5", look: "thick" }));
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5" }, "iframe"));
+ * ```
+ */
 export declare function embedCode(options: RocketOptions, kind?: EmbedKind, settings?: EmbedSettings): string;

package/dist/embed.js

@@ -7,10 +7,49 @@ import { cleanView } from "./framing.js";
 import { cleanShow, showsOf } from "./layout.js";
 import { cleanLook, DEFAULT_LOOK } from "./looks.js";
 import { attributesFromOptions, rocketToParams } from "./attrs.js";
+/**
+ * The six ways `embedCode` writes a rocket for another page: `element`, `iframe`, `module`, `svg`, `data` and `link`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
 export const EMBED_KINDS = ["element", "iframe", "module", "svg", "data", "link"];
+/**
+ * The address of the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { SITE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SITE);
+ * ```
+ */
 export const SITE = "https://johnmorrisdotca.github.io/uchusen-rockets/";
+/**
+ * The folder on a CDN the element loads from when the embed is a plain script with no bundler.
+ *
+ * @example
+ * ```ts
+ * import { CDN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CDN);
+ * ```
+ */
 export const CDN = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/uchusen-rockets@0";
-/** The three.js a page with no bundler takes from the CDN: the version this package is built and tested with. */
+/**
+ * The three.js a page with no bundler takes from the CDN: the version this package is built and tested with.
+ *
+ * @example
+ * ```ts
+ * import { THREE_VERSION } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(THREE_VERSION);
+ * ```
+ */
 export const THREE_VERSION = "0.186.1";
 const THREE_CDN = `https://cdn.jsdelivr.net/npm/three@${THREE_VERSION}`;
 const IMPORT_MAP = `<script type="importmap">\n  { "imports": { "three": "${THREE_CDN}/build/three.module.js", "three/addons/": "${THREE_CDN}/examples/jsm/" } }\n</script>`;
@@ -34,7 +73,19 @@ function descriptionOf(options) {
     }
     return { rocket: options.rocket ?? "starship", ...(options.variant ? { variant: options.variant } : {}) };
 }
-/** What an embed asks of the page around it, in words: a line for the demo to show. */
+/**
+ * What an embed asks of the page around it, in words: a line for the demo to show.
+ *
+ * @param kind Which way of embedding.
+ * @param options The rocket being embedded.
+ * @returns A line of text for the demo to show beside the code.
+ * @example
+ * ```ts
+ * import { embedNote } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedNote("iframe", { rocket: "starship" }));
+ * ```
+ */
 export function embedNote(kind, options) {
     const notes = {
         element: "One script from the CDN and the tag. The import map names three.js, for the 3D view; a page with a bundler needs neither, only the package.",
@@ -47,8 +98,17 @@ export function embedNote(kind, options) {
     return notes[kind];
 }
 /**
- * The CC BY line for a painted rocket, generated from the parts that are showing.
- * Empty when the look is not painted, or when those parts are this package's own paint.
+ * The CC BY line for a painted rocket, generated from the parts that are showing. Empty when the look is not painted, or when those parts are this package's own paint.
+ *
+ * @param options The rocket as it will be drawn.
+ * @returns The credit line, or an empty text when nothing needs crediting.
+ * @example
+ * ```ts
+ * import { paintedCredit } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "painted" }));
+ * console.log(paintedCredit({ rocket: "starship", variant: "v3", look: "line" }) === "");
+ * ```
  */
 export function paintedCredit(options) {
     if (cleanLook(options.look) !== "painted")
@@ -68,6 +128,15 @@ export function paintedCredit(options) {
 }
 /**
  * The shipped picture of these options, under the package's `dist/assets/`: `starship-v3.svg`, `falcon-9-block-5-apart.thick.svg`. These are drawn from the default view, with no flames. Null for a custom build, which has no file, or a variant, part or look that does not exist.
+ *
+ * @param options The rocket, variant, look, view and what to show.
+ * @returns The path of the shipped picture under `dist/assets/`, or null when none is shipped for those options.
+ * @example
+ * ```ts
+ * import { assetPathOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(assetPathOf({ rocket: "starship", variant: "v3" }));
+ * ```
  */
 export function assetPathOf(options) {
     if (options.build)
@@ -103,7 +172,21 @@ function drawingOf(options) {
     }
 }
 const creditHtml = (credit) => (credit === "" ? "" : `\n<p>${esc(credit).replaceAll("\n", "<br>\n")}</p>`);
-/** The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`. */
+/**
+ * The text of one embed. The `module` one imports the package; the `data` one is a `data:image/svg+xml` address for an `<img>`.
+ *
+ * @param options The rocket and how it looks.
+ * @param kind Which way to write it. Defaults to the element.
+ * @param settings Where the demo and the CDN are, if not the package's own.
+ * @returns The text to paste into a page. A painted rocket's credit is part of it.
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5", look: "thick" }));
+ * console.log(embedCode({ rocket: "falcon-9", variant: "block-5" }, "iframe"));
+ * ```
+ */
 export function embedCode(options, kind = "element", settings = {}) {
     const site = settings.site ?? SITE;
     const cdn = settings.cdn ?? CDN;

package/dist/engines.d.ts

@@ -4,13 +4,57 @@ export declare const PLUME_EXITS = 34;
 export declare const PLUME_MOST_M = 26;
 /** How many shock diamonds a flame shows near the ground. A picture. */
 export declare const PLUME_DIAMONDS = 6;
-/** With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one. */
+/**
+ * With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one.
+ *
+ * @example
+ * ```ts
+ * import { FLAME_SETTLE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLAME_SETTLE_MS / 1000, "seconds");
+ * ```
+ */
 export declare const FLAME_SETTLE_MS = 15000;
 /** A flame that only flickers is drawn at most this often. A turn or a move still draws once a frame. */
 export declare const FLAME_GAP_MS = 33;
+/**
+ * How long a flame is drawn, in metres, for an engine whose bell is `exit` metres across at the mouth. The length is a picture, not a measured flame.
+ *
+ * @param exit The exit radius of the bell, in metres.
+ * @returns The flame's length in metres.
+ * @example
+ * ```ts
+ * import { plumeLength } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(plumeLength(0.45).toFixed(2));
+ * ```
+ */
 export declare function plumeLength(exit: number): number;
-/** `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off. */
+/**
+ * `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off.
+ *
+ * @param attribute The value of the `engines` attribute, or null when it is missing.
+ * @param reduced True when the reader asked for reduced motion.
+ * @returns True when the flames should be drawn.
+ * @example
+ * ```ts
+ * import { enginesWanted } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(enginesWanted("on", false), enginesWanted("on", true), enginesWanted(null, false));
+ * ```
+ */
 export declare function enginesWanted(attribute: string | null, reduced: boolean): boolean;
+/**
+ * One engine bell as the drawing has it: where it stands across the part, the height of its mouth and its exit radius, all in metres in the part's own frame.
+ *
+ * @example
+ * ```ts
+ * import { bellsOf, type Bell } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const bells: Bell[] = bellsOf([]);
+ * console.log(bells.length);
+ * ```
+ */
 export interface Bell {
     x: number;
     z: number;
@@ -19,7 +63,20 @@ export interface Bell {
     /** Exit radius, metres. */
     exit: number;
 }
-/** One bell for every engine the pieces already draw. The mouth is the first point of the bell. */
+/**
+ * One bell for every engine the pieces already draw. The mouth is the first point of the bell.
+ *
+ * @param pieces The pieces of a part, as the builder makes them.
+ * @returns The bells, one for each engine the pieces already draw.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? bellsOf(booster.pieces).length : 0);
+ * ```
+ */
 export declare function bellsOf(pieces: readonly Piece[]): Bell[];
 export interface LitBell extends Bell {
     slot: string;
@@ -36,9 +93,34 @@ export declare function litBells(parts: readonly {
     beside?: boolean;
     dark?: boolean;
 }[], together: boolean): LitBell[];
-/** The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis. */
+/**
+ * The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis.
+ *
+ * @param bells The bells of one part.
+ * @returns The rings, innermost first, each a list of bells.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, ringsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? ringsOf(bellsOf(booster.pieces)).map((ring) => ring.length) : []);
+ * ```
+ */
 export declare function ringsOf(bells: readonly Bell[]): Bell[][];
 /**
  * Which `count` engines burn: from the middle out, and a ring that is only partly used has them evenly round it, so three of a Falcon 9's nine are the middle one and two opposite. A source says how many; where they stand is this rule.
+ *
+ * @param bells All the bells of a part.
+ * @param count How many burn.
+ * @returns The bells that burn.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, pickBells } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? pickBells(bellsOf(booster.pieces), 3).length : 0);
+ * ```
  */
 export declare function pickBells(bells: readonly Bell[], count: number): Bell[];

package/dist/engines.js

@@ -3,18 +3,64 @@ export const PLUME_EXITS = 34;
 export const PLUME_MOST_M = 26;
 /** How many shock diamonds a flame shows near the ground. A picture. */
 export const PLUME_DIAMONDS = 6;
-/** With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one. */
+/**
+ * With no one touching anything, a flame stops moving after this long and nothing draws: a lit rocket at rest costs the same as a dark one.
+ *
+ * @example
+ * ```ts
+ * import { FLAME_SETTLE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLAME_SETTLE_MS / 1000, "seconds");
+ * ```
+ */
 export const FLAME_SETTLE_MS = 15_000;
 /** A flame that only flickers is drawn at most this often. A turn or a move still draws once a frame. */
 export const FLAME_GAP_MS = 33;
+/**
+ * How long a flame is drawn, in metres, for an engine whose bell is `exit` metres across at the mouth. The length is a picture, not a measured flame.
+ *
+ * @param exit The exit radius of the bell, in metres.
+ * @returns The flame's length in metres.
+ * @example
+ * ```ts
+ * import { plumeLength } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(plumeLength(0.45).toFixed(2));
+ * ```
+ */
 export function plumeLength(exit) {
     return Math.min(exit * PLUME_EXITS, PLUME_MOST_M);
 }
-/** `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off. */
+/**
+ * `on` asks for them, and a reader who asked for reduced motion has them off whatever the page says. Anything else, or nothing, is off.
+ *
+ * @param attribute The value of the `engines` attribute, or null when it is missing.
+ * @param reduced True when the reader asked for reduced motion.
+ * @returns True when the flames should be drawn.
+ * @example
+ * ```ts
+ * import { enginesWanted } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(enginesWanted("on", false), enginesWanted("on", true), enginesWanted(null, false));
+ * ```
+ */
 export function enginesWanted(attribute, reduced) {
     return attribute === "on" && !reduced;
 }
-/** One bell for every engine the pieces already draw. The mouth is the first point of the bell. */
+/**
+ * One bell for every engine the pieces already draw. The mouth is the first point of the bell.
+ *
+ * @param pieces The pieces of a part, as the builder makes them.
+ * @returns The bells, one for each engine the pieces already draw.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? bellsOf(booster.pieces).length : 0);
+ * ```
+ */
 export function bellsOf(pieces) {
     const bells = [];
     for (const piece of pieces) {
@@ -44,7 +90,20 @@ export function litBells(parts, together) {
     }
     return bells;
 }
-/** The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis. */
+/**
+ * The bells grouped by how far they are from the part's axis, innermost ring first, and each ring in order round the axis.
+ *
+ * @param bells The bells of one part.
+ * @returns The rings, innermost first, each a list of bells.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, ringsOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? ringsOf(bellsOf(booster.pieces)).map((ring) => ring.length) : []);
+ * ```
+ */
 export function ringsOf(bells) {
     const sorted = [...bells].sort((a, b) => Math.hypot(a.x, a.z) - Math.hypot(b.x, b.z));
     const rings = [];
@@ -61,6 +120,18 @@ export function ringsOf(bells) {
 }
 /**
  * Which `count` engines burn: from the middle out, and a ring that is only partly used has them evenly round it, so three of a Falcon 9's nine are the middle one and two opposite. A source says how many; where they stand is this rule.
+ *
+ * @param bells All the bells of a part.
+ * @param count How many burn.
+ * @returns The bells that burn.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ * import { bellsOf, pickBells } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const booster = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(booster ? pickBells(bellsOf(booster.pieces), 3).length : 0);
+ * ```
  */
 export function pickBells(bells, count) {
     const wanted = Math.max(0, Math.min(bells.length, Math.floor(count)));

package/dist/fit.d.ts

@@ -1,6 +1,17 @@
 import { type CreditId, type ModelCredit } from "./data/credits.ts";
 import type { Variant } from "./data/types.ts";
 import type { PartRecord } from "./parts.ts";
+/**
+ * A rocket to check or build: its id, its variant (left out: the rocket's default) and any other part in a slot, by part id.
+ *
+ * @example
+ * ```ts
+ * import { check, type Description } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const description: Description = { rocket: "starship", variant: "v3", parts: { ship: "starship-v2-ship" } };
+ * console.log(check(description).label);
+ * ```
+ */
 export interface Description {
     rocket: string;
     /** Left out: the rocket's default variant. */
@@ -8,17 +19,61 @@ export interface Description {
     /** Another part in a slot, by its id. */
     parts?: Readonly<Record<string, string>>;
 }
+/**
+ * Why a check said what it said: an unknown rocket, variant, slot or part, a part of the wrong kind, a joint that is missing, of another kind or of another width, or a custom build.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const codes: FitCode[] = check({ rocket: "nowhere" }).issues.map((issue) => issue.code);
+ * console.log(codes);
+ * ```
+ */
 export type FitCode = "unknown-rocket" | "unknown-variant" | "unknown-slot" | "unknown-part" | "wrong-kind" | "no-joint" | "joint-kind" | "joint-diameter" | "custom";
+/**
+ * One thing a check found: its code, its level (`error` stops a build, `note` says what was decided) and a sentence saying it.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitIssue } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const issue: FitIssue | undefined = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } }).issues[0];
+ * console.log(issue?.level, issue?.message);
+ * ```
+ */
 export interface FitIssue {
     code: FitCode;
     /** "error" stops the build. "note" says what the check decided. */
     level: "error" | "note";
     message: string;
 }
+/**
+ * A part standing in a slot of a checked rocket.
+ *
+ * @example
+ * ```ts
+ * import { check, type SlotPart } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const bottom: SlotPart | undefined = check({ rocket: "starship", variant: "v3" }).parts[0];
+ * console.log(bottom?.slot, bottom?.part.name);
+ * ```
+ */
 export interface SlotPart {
     slot: string;
     part: PartRecord;
 }
+/**
+ * The answer of `check`: whether the parts go together, the issues, the label to call the rocket, whether it is a custom build, the variant, the parts, the size and the credits of every licensed model.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitReport } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report: FitReport = check({ rocket: "falcon-9", variant: "block-5" });
+ * console.log(report.ok, report.size);
+ * ```
+ */
 export interface FitReport {
     ok: boolean;
     issues: readonly FitIssue[];
@@ -42,4 +97,17 @@ export interface FitReport {
 }
 /** How far apart two joints may be in metres and still meet. */
 export declare const JOINT_TOLERANCE = 0.1;
+/**
+ * Asks whether a rocket goes together, from the parts' records alone, with no three.js and no DOM. A rocket labelled as a real version uses only parts true for it; any mix is a custom build and says so.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns A report that says whether it fits and why, with the size and the credits.
+ * @example
+ * ```ts
+ * import { check } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * console.log(report.ok, report.issues[0]?.message);
+ * ```
+ */
 export declare function check(description: Description): FitReport;

package/dist/fit.js

@@ -20,6 +20,19 @@ function sizeOf(parts) {
     }
     return { height: Math.round(top * 1000) / 1000, diameter: Math.max(...parts.map(({ part }) => part.diameter)) };
 }
+/**
+ * Asks whether a rocket goes together, from the parts' records alone, with no three.js and no DOM. A rocket labelled as a real version uses only parts true for it; any mix is a custom build and says so.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns A report that says whether it fits and why, with the size and the credits.
+ * @example
+ * ```ts
+ * import { check } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * console.log(report.ok, report.issues[0]?.message);
+ * ```
+ */
 export function check(description) {
     const issues = [];
     const fail = (code, message) => issues.push({ code, level: "error", message });