@johnmorrisdotca/uchusen-rockets 0.2.2 → 0.4.0

package/dist/model/starbase.js

@@ -0,0 +1,108 @@
+// The coordinates, outlines and map heights in this file are © OpenStreetMap contributors, under the Open Database License (ODbL 1.0, https://www.openstreetmap.org/copyright), not MIT: see NOTICE.md.
+// Starbase from the map: places and outlines from OpenStreetMap (a handful of named places, in metres from tower 1, x to the east and z to the south), the road and the coast too. What stands on them is plain geometry with no lettering or logo. Nothing here is announced or from a concept picture. Few pieces, merged by material in one mesh per part, so a whole town is a few dozen draws.
+import { blank } from "../data/types.js";
+import { moved, nose, road, slab, tube } from "./kit.js";
+import { mount, tower, TOWER_X } from "./tower.js";
+// tower 1 is the origin. Each row: x, z, wide, deep, turn in degrees, as measured
+const TOWER_2 = [-333, -101];
+const TOWER_TURN = 35;
+const FARM = { x: -24, z: -116, wide: 314, deep: 78, turn: 13 };
+const BUNKER = { x: -197, z: -195, wide: 51, deep: 20, turn: 12, tall: 4.1 };
+const BAYS = [
+    { x: -3362, z: 1081, wide: 54, deep: 38, turn: 44 },
+    { x: -3390, z: 984, wide: 38, deep: 54, turn: 44 },
+];
+const BAY_TALL = 100;
+const FACTORY = { x: -3170, z: 931, wide: 293, deep: 327, turn: 44, tall: 16.3 };
+const SANCHEZ = { x: -3586, z: 1368, wide: 523, deep: 345, turn: -46 };
+const SIGN = [-3455, 1445];
+const VILLAGE = [-2825, 516];
+const HALL = [-2688, 364];
+const HIGHWAY = [[-3799, 1822], [-3008, 1030], [-2855, 826], [-2546, 516], [-1863, 351], [-1233, 124], [-640, -104], [-333, -236], [-70, -186], [182, -127]];
+const COAST_X = 430;
+const BOOSTER_H = 72.3;
+const SHIP_H = 52.1;
+const R = 4.5;
+/** The land from a coast to the west, the beach, and a little sea. Only what the span reaches. */
+function ground(span) {
+    const land = Math.min(span.x1, COAST_X - 70);
+    const midZ = (span.z0 + span.z1) / 2;
+    const deep = span.z1 - span.z0;
+    const out = [slab("ground", (span.x0 + land) / 2, midZ, land - span.x0, deep, 0, -0.6, 0.02)];
+    if (span.x1 > land) {
+        const beach = Math.min(span.x1, COAST_X);
+        out.push(slab("sand", (land + beach) / 2, midZ, beach - land, deep, 0, -0.6, 0.02));
+        if (span.x1 > beach)
+            out.push(slab("water", (beach + span.x1) / 2, midZ, span.x1 - beach, deep, 0, -0.6, -0.1));
+    }
+    const inside = HIGHWAY.filter(([x, z]) => x >= span.x0 && x <= span.x1 && z >= span.z0 && z <= span.z1);
+    if (inside.length > 1)
+        out.push(...road("concrete", inside, 12, 0));
+    return out;
+}
+/** The tower and its mount as they stand at one place. */
+const pad = (x, z) => moved([...tower(), ...mount()], x - TOWER_X * Math.cos((TOWER_TURN * Math.PI) / 180), z + TOWER_X * Math.sin((TOWER_TURN * Math.PI) / 180), TOWER_TURN);
+function tankFarm() {
+    const out = [slab("concrete", FARM.x, FARM.z, FARM.wide, FARM.deep, FARM.turn, 0, 0.3)];
+    const tanks = 22;
+    for (let i = 0; i < tanks; i++) {
+        const along = -FARM.wide / 2 + 10 + ((FARM.wide - 20) * i) / (tanks - 1);
+        const a = (FARM.turn * Math.PI) / 180;
+        out.push(slab("white", FARM.x + along * Math.cos(a), FARM.z + along * Math.sin(a), 6, 48, FARM.turn, 0.3, 7.1));
+    }
+    out.push(slab("dark", BUNKER.x, BUNKER.z, BUNKER.wide, BUNKER.deep, BUNKER.turn, 0, BUNKER.tall));
+    return out;
+}
+/** A plain rocket at Block 3's sizes, standing at a place: booster, ship or both. */
+function plainRocket(x, z, y, booster, ship) {
+    const at = [x, z];
+    const seg = { segs: 16, at };
+    const out = [];
+    if (booster)
+        out.push(tube("steel", R, y, y + BOOSTER_H, { ...seg, rings: [y + BOOSTER_H - 0.02] }));
+    const base = booster ? y + BOOSTER_H : y;
+    if (ship) {
+        out.push(tube("steel", R, base, base + SHIP_H - 17, seg));
+        out.push(nose("steel", R, base + SHIP_H - 17, base + SHIP_H, 1.05, seg));
+        for (const side of [1, -1])
+            out.push(slab("fin-dark", x + side * (R + 1.6), z, 3.2, 1, 0, base + 2, base + 12));
+    }
+    return out;
+}
+const onPad = () => plainRocket(TOWER_X * -Math.cos((TOWER_TURN * Math.PI) / 180), TOWER_X * Math.sin((TOWER_TURN * Math.PI) / 180), 21, true, true);
+const megaBays = () => BAYS.map((bay) => slab("fin-dark", bay.x, bay.z, bay.wide, bay.deep, bay.turn, 0, BAY_TALL, false));
+const starfactory = () => [slab("white", FACTORY.x, FACTORY.z, FACTORY.wide, FACTORY.deep, FACTORY.turn, 0, FACTORY.tall, false)];
+function garden() {
+    const a = (SANCHEZ.turn * Math.PI) / 180;
+    const row = (along, across) => [SANCHEZ.x + along * Math.cos(a) - across * Math.sin(a), SANCHEZ.z + along * Math.sin(a) + across * Math.cos(a)];
+    const out = [slab("concrete", SANCHEZ.x, SANCHEZ.z, SANCHEZ.wide, SANCHEZ.deep, SANCHEZ.turn, 0, 0.3)];
+    [-90, -50, -10].forEach((along) => out.push(...plainRocket(...row(along, 40), 0.3, true, false)));
+    [30, 70, 110].forEach((along) => out.push(...plainRocket(...row(along, 40), 0.3, false, true)));
+    return out;
+}
+const sign = () => [slab("dark", SIGN[0], SIGN[1], 40, 2, -46, 0, 5, false)];
+function village() {
+    const out = [];
+    for (let i = 0; i < 14; i++)
+        out.push(slab(i % 3 ? "white" : "concrete", VILLAGE[0] + 32 * (i % 7) - 90, VILLAGE[1] + 34 * Math.floor(i / 7) - 20, 14, 10, -40, 0, 6));
+    out.push(slab("concrete", HALL[0], HALL[1], 30, 20, -40, 0, 9));
+    return out;
+}
+const NONE = blank("No source read here gives it.");
+const FROM = "This package's code: places, outlines and the heights the map tags from OpenStreetMap, under its licence, read 2026-11-02. A building is one plain box. Nothing announced, and no logo or lettering.";
+const part = (slot, name, height, wide, pieces) => ({ slot, kind: "site", name, height, diameter: wide, place: { x: 0, z: 0 }, sourcedDiameter: NONE, pieces });
+const LAUNCH = { x0: -620, x1: 640, z0: -420, z1: 200 };
+const BUILD = { x0: -3900, x1: -2950, z0: 700, z1: 1700 };
+const CITY = { x0: -3950, x1: 640, z0: -420, z1: 1800 };
+const pads = () => part("pads", "Two towers and their mounts", 149.4, 360, () => [...pad(0, 0), ...pad(TOWER_2[0], TOWER_2[1])]);
+const farm = () => part("tank-farm", "The tank farm", 7.1, FARM.wide, tankFarm);
+const rocketThere = () => part("on-pad", "A plain rocket at Block 3's size, on the first pad", 145.4, R * 2, onPad);
+const bays = () => part("mega-bays", "The Mega Bays", BAY_TALL, 200, megaBays);
+const factoryPart = () => part("starfactory", "Starfactory, its outer outline", FACTORY.tall, FACTORY.deep, starfactory);
+const gardenPart = () => part("garden", "The rocket garden on the Sanchez site", BOOSTER_H, SANCHEZ.wide, garden);
+const signPart = () => part("sign", "A plain board at the sign's place", 5, 40, sign);
+export const STARBASE_BUILDS = [
+    { rocket: "starbase", variant: "launch-site", drawnFrom: FROM, parts: [part("ground", "The ground, the beach and the road", 0.2, 1260, () => ground(LAUNCH)), pads(), farm(), rocketThere()] },
+    { rocket: "starbase", variant: "build-site", drawnFrom: FROM, parts: [part("ground", "The ground and the road", 0.2, 950, () => ground(BUILD)), bays(), factoryPart(), gardenPart(), signPart()] },
+    { rocket: "starbase", variant: "city", drawnFrom: FROM, parts: [part("ground", "The ground, the beach and the road", 0.2, 4590, () => ground(CITY)), pads(), farm(), rocketThere(), bays(), factoryPart(), gardenPart(), signPart(), part("village", "A few plain houses at the village", 9, 300, village)] },
+];

package/dist/model/tower.d.ts

@@ -0,0 +1,6 @@
+import { type Piece } from "./pieces.ts";
+import type { StackBuild } from "./stacks.ts";
+export declare const TOWER_X = -28;
+export declare function tower(): Piece[];
+export declare function mount(): Piece[];
+export declare const TOWER_BUILDS: readonly StackBuild[];

package/dist/model/tower.js

@@ -0,0 +1,89 @@
+// The tower's 13 m footprint in this file is © OpenStreetMap contributors, under the Open Database License (ODbL 1.0, https://www.openstreetmap.org/copyright), not MIT: see NOTICE.md.
+// The integration tower from a table of numbers: its height, its lightning rod and its footprint are sourced; its nine sections are sourced, and their bracing, its arms and the mount are judged from photographs. Plain boxes, few enough that the scene with a whole Starship stays inside a code-made mesh's limit.
+import { STARSHIP_DRAWS, boosterPieces, shipPieces } from "./starship.js";
+import { blank } from "../data/types.js";
+import { TOWER_HEIGHT } from "../data/tower.js";
+import { deg } from "../framing.js";
+import { strut } from "./pieces.js";
+const ROD = 10 * 0.3048;
+const SECTIONS = 9;
+const HALF = 6.5;
+export const TOWER_X = -28;
+const MOUNT_TOP = 21;
+const ARM_REACH = 32;
+const ARM_FROM = TOWER_X + HALF + 1;
+const SHIP_ARM_Y = 100;
+const CATCH_Y = 125;
+const CATCH_BOOSTER_Y = 58;
+const OPEN_Z = 13;
+const CLOSED_Z = 5;
+const R = 4.5;
+const beam = (material, a, b, width, depth = width) => strut(material, a, b, width, depth, { plain: true });
+export function tower() {
+    const out = [];
+    const corners = [[HALF, HALF], [HALF, -HALF], [-HALF, -HALF], [-HALF, HALF]];
+    const step = TOWER_HEIGHT / SECTIONS;
+    for (const [x, z] of corners)
+        out.push(beam("fin-dark", [x, 0, z], [x, TOWER_HEIGHT, z], 1));
+    for (let s = 0; s <= SECTIONS; s++) {
+        const y = s * step;
+        for (let c = 0; c < 4; c++) {
+            const [x0, z0] = corners[c];
+            const [x1, z1] = corners[(c + 1) % 4];
+            out.push(beam("fin-dark", [x0, y, z0], [x1, y, z1], 0.6));
+            if (s < SECTIONS)
+                out.push(beam("fin", [x0, y, z0], [x1, y + step, z1], 0.34));
+        }
+    }
+    // the lightning rod, and the arm that fuels the Ship
+    out.push({ kind: "lathe", material: "engine-metal", segs: 8, profile: [[0.2, TOWER_HEIGHT], [0.06, TOWER_HEIGHT + ROD]] });
+    out.push(beam("dark", [HALF, SHIP_ARM_Y, HALF], [HALF + 15, SHIP_ARM_Y, 3], 1.1));
+    out.push(beam("dark", [HALF, SHIP_ARM_Y, -HALF], [HALF + 15, SHIP_ARM_Y, 3], 0.8));
+    return out;
+}
+export function mount() {
+    const table = (r, r0, y) => ({ kind: "lathe", material: "fin", segs: 48, body: true, profile: [[r, y], [r0, y]] });
+    const out = [
+        { kind: "lathe", material: "concrete", segs: 48, body: true, outline: true, profile: [[32, 0], [32, 0.5], [0.001, 0.5]] },
+        { kind: "lathe", material: "fin", segs: 48, body: true, outline: true, profile: [[14, MOUNT_TOP - 3], [14, MOUNT_TOP]], rings: [MOUNT_TOP - 3] },
+        { kind: "lathe", material: "fin", segs: 40, under: true, profile: [[6, MOUNT_TOP - 3], [14, MOUNT_TOP - 3]] },
+        { kind: "lathe", material: "soot", segs: 32, only: "mesh", profile: [[6, MOUNT_TOP], [6, MOUNT_TOP - 3]] },
+        table(14, 6, MOUNT_TOP),
+        // the steel plate that takes the blast, under the ring
+        { kind: "lathe", material: "engine-metal", segs: 32, body: true, profile: [[11, 2], [0.001, 2.6]] },
+    ];
+    for (let i = 0; i < 6; i++) {
+        const a = deg(30 + i * 60);
+        const at = (r, y) => [r * Math.sin(a), y, r * Math.cos(a)];
+        out.push(beam("dark", at(16, 0.5), at(11.5, MOUNT_TOP - 3), 2.2));
+    }
+    return out;
+}
+function arms(z) {
+    const end = ARM_FROM + ARM_REACH;
+    const out = [{ kind: "plate", material: "dark", frame: { o: [ARM_FROM - 1, 2, 0], u: [0, 1, 0], v: [0, 0, 1], w: [1, 0, 0] }, outline: [[-2, -(HALF + 1.2)], [2, -(HALF + 1.2)], [2, HALF + 1.2], [-2, HALF + 1.2]], thickness: 1.4, plain: false }];
+    for (const side of [1, -1]) {
+        const inner = [end, 2, side * z];
+        const root = [ARM_FROM, 2, side * HALF];
+        out.push(beam("dark", root, inner, 1.9, 1.7));
+        // the track on top, and its truss underneath
+        out.push(beam("engine-metal", [root[0] + 3, 3, root[2]], [end - 1, 3, side * z], 0.5, 0.3));
+        out.push(beam("fin-dark", [ARM_FROM, 0.2, side * HALF], [(ARM_FROM + end) / 2, 0.6, side * ((HALF + z) / 2)], 0.5));
+    }
+    return out;
+}
+const NONE = blank("No source read here gives it.");
+const FROM = "This package's code. The tower's height and lightning rod are from the FAA's 2022 assessment, its nine sections from Wikipedia, its footprint from OpenStreetMap; its bracing, arms and mount are judged from photographs, which were looked at and not traced. No lettering or mark is drawn.";
+const v3 = STARSHIP_DRAWS.v3;
+const common = (armY, armZ) => [
+    { slot: "mount", kind: "mount", name: "Launch mount and pad", height: MOUNT_TOP, diameter: 64, place: { x: 0, z: 0 }, sourcedDiameter: NONE, pieces: mount },
+    { slot: "tower", kind: "tower", name: "Integration tower", height: TOWER_HEIGHT, diameter: HALF * 2, place: { x: TOWER_X, z: 0 }, sourcedDiameter: { value: 13, source: "openstreetmap", note: "The map's footprint of tower 1, 13 by 12 m." }, pieces: tower },
+    { slot: "arms", kind: "arms", name: armZ === CLOSED_Z ? "The arms, closed" : "The arms, open", height: 4, diameter: ARM_REACH, place: { x: 0, z: 0, y: armY }, sourcedDiameter: NONE, pieces: () => arms(armZ) },
+];
+const booster = (y) => ({ slot: "booster", kind: "booster", name: "Super Heavy, Block 3 (V3)", height: v3.boosterHeight, diameter: v3.radius * 2, place: { x: 0, z: 0, y }, sourcedDiameter: { value: R * 2, source: "wikipedia-starship" }, pieces: () => boosterPieces(v3) });
+const ship = (y) => ({ slot: "ship", kind: "ship", name: "Ship, Block 3 (V3)", height: v3.shipHeight, diameter: v3.radius * 2, place: { x: 0, z: 0, y }, sourcedDiameter: { value: R * 2, source: "wikipedia-starship" }, pieces: () => shipPieces(v3) });
+export const TOWER_BUILDS = [
+    { rocket: "launch-tower", variant: "tower", drawnFrom: FROM, parts: common(CATCH_Y, OPEN_Z) },
+    { rocket: "launch-tower", variant: "stack", drawnFrom: FROM, parts: [...common(CATCH_Y, OPEN_Z), booster(MOUNT_TOP), ship(MOUNT_TOP + v3.boosterHeight)] },
+    { rocket: "launch-tower", variant: "catch", drawnFrom: FROM, parts: [...common(CATCH_Y, CLOSED_Z), booster(CATCH_BOOSTER_Y)] },
+];

package/dist/parts.d.ts

@@ -1,7 +1,28 @@
 import type { CreditId } from "./data/credits.ts";
 import type { Figure } from "./data/types.ts";
-export type PartKind = "booster" | "first-stage" | "ship" | "second-stage" | "fairing" | "capsule" | "trunk" | "engine" | "fin" | "flap" | "ring" | "test-vehicle";
-/** Where a part mates. Every part's origin is the middle of its base on its axis, at its lowest point; Y is up and the windward side faces +Z, in metres. */
+/**
+ * What kind of part a record is: a booster, a ship, a stage, a fairing, a capsule, an engine, a fin and so on. A joint only mates a part of a kind that fits it.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type PartKind } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const kind: PartKind | undefined = partEntry("raptor-vacuum")?.record.kind;
+ * console.log(kind);
+ * ```
+ */
+export type PartKind = "booster" | "first-stage" | "ship" | "second-stage" | "fairing" | "capsule" | "trunk" | "engine" | "fin" | "flap" | "ring" | "test-vehicle" | "third-stage" | "adapter" | "service-module" | "tower" | "tank" | "solid-booster" | "liquid-booster" | "orbiter" | "deck" | "mount" | "arms" | "site" | "spacecraft";
+/**
+ * Where a part mates. Every part's origin is the middle of its base on its axis, at its lowest point; Y is up and the windward side faces +Z, in metres.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type Joint } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const top: Joint | undefined = partEntry("starship-v3-booster")?.record.joints.top;
+ * console.log(top);
+ * ```
+ */
 export interface Joint {
     /** What this joint is, so only like meets like: "stage". */
     kind: "stage";
@@ -10,6 +31,17 @@ export interface Joint {
     /** Metres across at the joint. */
     diameter: number;
 }
+/**
+ * The one record every part has: its id, kind and name, the rocket and variants it is true for, its height and diameter in metres, the sourced figures, its joints, any painted model, and where its shape came from.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type PartRecord } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const record: PartRecord | undefined = partEntry("starship-v3-ship")?.record;
+ * console.log(record?.name, record?.height, record?.trueTo);
+ * ```
+ */
 export interface PartRecord {
     id: string;
     kind: PartKind;
@@ -29,10 +61,11 @@ export interface PartRecord {
         readonly top?: Joint;
         readonly bottom?: Joint;
     };
-    /** It stands beside the part below it rather than on top, this far from the rocket's axis: a side booster. */
+    /** It is placed rather than stacked, this far from the rocket's axis and this far up (left out: on the ground): a side booster beside the core, or a booster standing on a deck. */
     strapOn?: {
         x: number;
         z: number;
+        y?: number;
     };
     /** The painted look's mesh, when a licensed model gives one: its file under assets/models/ and whose it is. Otherwise this package's own code paints it. `ownNozzle`: the model has none, so this package's own shows with it unless the part is nested in the stage below. */
     painted: {

package/dist/pixels.d.ts

@@ -1,8 +1,48 @@
-/** The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million). */
+/**
+ * The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million).
+ *
+ * @example
+ * ```ts
+ * import { MAX_PIXELS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_PIXELS);
+ * ```
+ */
 export declare const MAX_PIXELS = 6000000;
-/** The longest side the backing store may have. */
+/**
+ * The longest side the backing store may have.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SIDE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_SIDE);
+ * ```
+ */
 export declare const MAX_SIDE = 4096;
-/** The sharpest ratio ever used, however dense the screen. */
+/**
+ * The sharpest ratio ever used, however dense the screen.
+ *
+ * @example
+ * ```ts
+ * import { MAX_RATIO } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_RATIO);
+ * ```
+ */
 export declare const MAX_RATIO = 2;
-/** The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value. */
+/**
+ * The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value.
+ *
+ * @param width The view's width in CSS pixels.
+ * @param height Its height in CSS pixels.
+ * @param deviceRatio The screen's own pixel ratio.
+ * @returns The ratio to draw at.
+ * @example
+ * ```ts
+ * import { pixelRatioFor } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(pixelRatioFor(620, 827, 3), pixelRatioFor(3000, 3000, 2));
+ * ```
+ */
 export declare function pixelRatioFor(width: number, height: number, deviceRatio: number): number;

package/dist/pixels.js

@@ -1,11 +1,51 @@
 // How sharp the 3D canvas may be. The backing store is width x height x ratio squared, and a view as big as a 5K screen at a ratio of 2 would ask the graphics card for 15 million pixels, every frame. Pure.
-/** The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million). */
+/**
+ * The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million).
+ *
+ * @example
+ * ```ts
+ * import { MAX_PIXELS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_PIXELS);
+ * ```
+ */
 export const MAX_PIXELS = 6_000_000;
-/** The longest side the backing store may have. */
+/**
+ * The longest side the backing store may have.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SIDE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_SIDE);
+ * ```
+ */
 export const MAX_SIDE = 4096;
-/** The sharpest ratio ever used, however dense the screen. */
+/**
+ * The sharpest ratio ever used, however dense the screen.
+ *
+ * @example
+ * ```ts
+ * import { MAX_RATIO } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_RATIO);
+ * ```
+ */
 export const MAX_RATIO = 2;
-/** The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value. */
+/**
+ * The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value.
+ *
+ * @param width The view's width in CSS pixels.
+ * @param height Its height in CSS pixels.
+ * @param deviceRatio The screen's own pixel ratio.
+ * @returns The ratio to draw at.
+ * @example
+ * ```ts
+ * import { pixelRatioFor } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(pixelRatioFor(620, 827, 3), pixelRatioFor(3000, 3000, 2));
+ * ```
+ */
 export function pixelRatioFor(width, height, deviceRatio) {
     const w = Math.max(1, width);
     const h = Math.max(1, height);

package/dist/react.d.ts

@@ -2,6 +2,17 @@ import { type HTMLAttributes, type Ref } from "react";
 import type { Description } from "./fit.ts";
 import type { ViewName } from "./framing.ts";
 import type { LookName } from "./looks.ts";
+/**
+ * The props of the React wrapper: the element's attributes as props (`rocket`, `variant`, `show`, `look`, `view`, `mode`, `assets`, `spin`, `way`, `label`, `engines`, `phase`), `build` as an object, and any other HTML attribute.
+ *
+ * @example
+ * ```ts
+ * import type { UchusenRocketProps } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * const props: UchusenRocketProps = { rocket: "starship", variant: "v3", look: "thick" };
+ * console.log(props);
+ * ```
+ */
 export interface UchusenRocketProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
     rocket?: string;
     variant?: string;
@@ -16,8 +27,25 @@ export interface UchusenRocketProps extends Omit<HTMLAttributes<HTMLElement>, "s
     spin?: string | number;
     way?: "cw" | "ccw";
     label?: string;
+    /** "on" lights the engines, and a reader who asked for reduced motion has them off. */
+    engines?: "on" | "off";
+    /** A phase of the rocket's flight, by its id. */
+    phase?: string;
     ref?: Ref<HTMLElement>;
 }
+/**
+ * A thin React wrapper round `<uchusen-rocket>`. It loads the element on first use, so server rendering draws only the tag.
+ *
+ * @param props The props. `build` is turned into the element's JSON attribute; the rest go through as they are.
+ * @returns The `<uchusen-rocket>` element. It is never null or undefined.
+ * @example
+ * ```tsx no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * export const Hero = () => <UchusenRocket rocket="falcon-9" variant="block-5" look="painted" />;
+ * console.log(typeof UchusenRocket);
+ * ```
+ */
 export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): import("react").DOMElement<{
     build: string | undefined;
     rocket?: string;
@@ -31,16 +59,24 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     spin?: string | number;
     way?: "cw" | "ccw";
     label?: string;
+    /** "on" lights the engines, and a reader who asked for reduced motion has them off. */
+    engines?: "on" | "off";
+    /** A phase of the rocket's flight, by its id. */
+    phase?: string;
     ref?: Ref<HTMLElement>;
     part?: string | undefined | undefined;
     id?: string | undefined | undefined;
     slot?: string | undefined | undefined;
     children?: import("react").ReactNode;
     title?: string | undefined | undefined;
+    "aria-label"?: string | undefined | undefined;
+    "aria-live"?: "off" | "assertive" | "polite" | undefined | undefined;
+    about?: string | undefined | undefined;
+    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
+    "aria-valuetext"?: string | undefined | undefined;
+    color?: string | undefined | undefined;
     role?: import("react").AriaRole | undefined;
     "aria-roledescription"?: string | undefined | undefined;
-    color?: string | undefined | undefined;
-    "aria-label"?: string | undefined | undefined;
     defaultChecked?: boolean | undefined | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined | undefined;
@@ -61,7 +97,6 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     tabIndex?: number | undefined | undefined;
     translate?: "yes" | "no" | undefined | undefined;
     radioGroup?: string | undefined | undefined;
-    about?: string | undefined | undefined;
     content?: string | undefined | undefined;
     datatype?: string | undefined | undefined;
     inlist?: any;
@@ -117,7 +152,6 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     "aria-keyshortcuts"?: string | undefined | undefined;
     "aria-labelledby"?: string | undefined | undefined;
     "aria-level"?: number | undefined | undefined;
-    "aria-live"?: "off" | "assertive" | "polite" | undefined | undefined;
     "aria-modal"?: (boolean | "true" | "false") | undefined;
     "aria-multiline"?: (boolean | "true" | "false") | undefined;
     "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
@@ -125,7 +159,6 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     "aria-owns"?: string | undefined | undefined;
     "aria-placeholder"?: string | undefined | undefined;
     "aria-posinset"?: number | undefined | undefined;
-    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
     "aria-readonly"?: (boolean | "true" | "false") | undefined;
     "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined | undefined;
     "aria-required"?: (boolean | "true" | "false") | undefined;
@@ -139,7 +172,6 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     "aria-valuemax"?: number | undefined | undefined;
     "aria-valuemin"?: number | undefined | undefined;
     "aria-valuenow"?: number | undefined | undefined;
-    "aria-valuetext"?: string | undefined | undefined;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
     } | undefined | undefined;

package/dist/react.js

@@ -1,5 +1,18 @@
 // A thin React wrapper round `<uchusen-rocket>`.
 import { createElement, useEffect } from "react";
+/**
+ * A thin React wrapper round `<uchusen-rocket>`. It loads the element on first use, so server rendering draws only the tag.
+ *
+ * @param props The props. `build` is turned into the element's JSON attribute; the rest go through as they are.
+ * @returns The `<uchusen-rocket>` element. It is never null or undefined.
+ * @example
+ * ```tsx no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * export const Hero = () => <UchusenRocket rocket="falcon-9" variant="block-5" look="painted" />;
+ * console.log(typeof UchusenRocket);
+ * ```
+ */
 export function UchusenRocket({ build, ...rest }) {
     useEffect(() => {
         void import("./element.js");

package/dist/rockets.d.ts

@@ -1,14 +1,51 @@
+import { type MakerId } from "./data/makers.ts";
 import type { Figure, Variant } from "./data/types.ts";
 import type { SourceId } from "./data/sources.ts";
+/**
+ * Whether a rocket is `built` (it has a shape) or `planned` (it has facts and no shape yet).
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS, type RocketStatus } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const status: RocketStatus | undefined = ROCKETS["starship"]?.status;
+ * console.log(status);
+ * ```
+ */
 export type RocketStatus = "built" | "planned";
+/**
+ * One rocket: its id and name, its variants, its default variant, the group it is listed under and who made it.
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS, type RocketEntry } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const starship: RocketEntry | undefined = ROCKETS["starship"];
+ * console.log(starship?.name, starship?.variants.map((variant) => variant.id));
+ * ```
+ */
 export interface RocketEntry {
     id: string;
     name: string;
     status: RocketStatus;
     variants: readonly Variant[];
     defaultVariant: string;
+    /** Which group the demo lists it under. */
+    maker: MakerId;
+    /** Whose it is and who built it, as its source says, or a blank. */
+    madeBy: Figure<string>;
 }
-/** A rocket on the list with no mesh yet: its name and the sourced facts to build it from. */
+/**
+ * A rocket on the list with no mesh yet: its name and the sourced facts to build it from.
+ *
+ * @example
+ * ```ts
+ * import { PLANNED_ROCKETS, type PlannedRocket } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const planned: PlannedRocket | undefined = PLANNED_ROCKETS[0];
+ * console.log(planned?.name);
+ * ```
+ */
 export interface PlannedRocket {
     id: string;
     name: string;
@@ -18,10 +55,66 @@ export interface PlannedRocket {
     firstFlight: Figure<string>;
     source: SourceId;
 }
+/**
+ * Every rocket that has a shape, by id, each with its variants. Add a rocket here and the element, the drawing, the fit check and the demo all read it.
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(ROCKETS).slice(0, 6));
+ * ```
+ */
 export declare const ROCKETS: Readonly<Record<string, RocketEntry>>;
+/**
+ * Rockets with sourced facts and no shape yet.
+ *
+ * @example
+ * ```ts
+ * import { PLANNED_ROCKETS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(PLANNED_ROCKETS.map((rocket) => rocket.name));
+ * ```
+ */
 export declare const PLANNED_ROCKETS: readonly PlannedRocket[];
+/**
+ * Finds a rocket's variant, with its sourced sizes.
+ *
+ * @param rocket A rocket's id.
+ * @param id A variant's id. Left out, null or undefined: the rocket's default variant.
+ * @returns The variant, or undefined when the rocket or the variant is not known.
+ * @example
+ * ```ts
+ * import { variantOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const v3 = variantOf("starship", "v3");
+ * console.log(v3?.facts.height.value, variantOf("starship", "v99"));
+ * ```
+ */
 export declare function variantOf(rocket: string, id?: string | null): Variant | undefined;
-/** A part's name for a rocket's slot in a variant. */
+/**
+ * A part's name for a rocket's slot in a variant.
+ *
+ * @param rocket A rocket's id.
+ * @param variant A variant's id.
+ * @param slot A slot name.
+ * @returns The id of the part that stands in that slot.
+ * @example
+ * ```ts
+ * import { partIdOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(partIdOf("starship", "v3", "booster"));
+ * ```
+ */
 export declare const partIdOf: (rocket: string, variant: string, slot: string) => string;
-/** What to call a slot. */
+/**
+ * What to call a slot.
+ *
+ * @example
+ * ```ts
+ * import { SLOT_NAMES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SLOT_NAMES["booster"]);
+ * ```
+ */
 export declare const SLOT_NAMES: Readonly<Record<string, string>>;