@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/recipes/water_tower/README.md

@@ -0,0 +1,40 @@
+# Railroad water tank — Frisco, Beaumont, Kansas (c. 1886) (`water_tower`)
+
+## Identity
+The St. Louis & San Francisco ("Frisco") 50,000-gallon cypress-stave water tank at Beaumont, KS:
+NRHP-listed (93000843) and HABS-recorded (KS-82), so its dimensions are on paper, and it is the
+textbook American wayside tank. Signature features: a squat stave tub bound by steel hoops (closer
+near the bottom, where the pressure is), a low six-sided shingle roof with a finial, a timber
+trestle of posts on concrete footings with X bracing round a wooden central core, and the
+goose-neck delivery spout over the track (removed at Beaumont in the 1950s; restored here from the
+period type Berg describes).
+
+## Specs
+| Dimension | Value | Source |
+|---|---|---|
+| tank height (staves) | 14 ft (4.267 m) | NRHP nomination 93000843, §7, https://npgallery.nps.gov/GetAsset/f632b7b3-36b4-4a36-be22-47bb617fad0d |
+| tank diameter | 22 ft (6.706 m) | same |
+| superstructure (ground → tank floor) | 14 ft (4.267 m) | same |
+| central core | 10 ft dia × 14 ft high (3.048 × 4.267 m) | same |
+| supports | 8 timber pillars on concrete footings, cross-braced | same |
+| capacity | 50,000 US gal | same (6.706² π/4 × 4.267 m = 150.7 m³ ≈ 39,800 gal of staves at the inside; the quoted figure is nominal) |
+| roof | six-sided, wooden shingles | same |
+| spout | goose-neck delivery spout projecting over the track | Berg, *Buildings and Structures of American Railroads* (1893) p. 116, quoted in the nomination |
+| roof rise, finial, hoop count | ≈ 1.05 m rise, 14 hoops | ESTIMATE, scaled from the photo (tank height as ruler) |
+| spout length / rest angle | 3.4 m, 25° up | ESTIMATE (D&RGW tank practice, railroads procgen recipe station_prop_water_tank_wood) |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| 3/4 side | https://commons.wikimedia.org/wiki/File:Beaumont_Kansas_Water_Tower.jpg | hoops, hexagonal roof, posts on footings, X braces, core, ladder pole |
+| record | https://en.wikipedia.org/wiki/Beaumont_St._Louis_and_San_Francisco_Railroad_Water_Tank | HABS KS-82 (12 measured drawings) |
+| spout type | https://davesriogrande.net/Structures/WaterTanks/watertanks.htm | D&RG tanks with spouts (Chama double spout, Osier) |
+
+## Parts the engine needs
+`spout` (pivot at the tank outlet, `sway` about Y: lowered over a tender) · `socket` `water_fill`
+(interact) at the spout mouth · `tank`, `trestle`, `core`, `roof`.
+
+## Open questions
+- The current Beaumont trestle (heavy timbers, concrete footings) is a 20th-century replacement; the
+  nomination says the original bracing was lighter. The current one is modelled (it is in the photo).
+- Roof rise and hoop count are photo estimates; HABS drawings (loc.gov, 403 to fetchers) would fix them.

package/recipes/water_tower/water_tower.ts

@@ -0,0 +1,542 @@
+// Railroad water tank: the Frisco's 50,000-gallon cypress-stave tank at Beaumont, Kansas (c. 1886,
+// NRHP 93000843): a 22 ft × 14 ft stave tub on a 14 ft timber trestle of eight posts round a
+// wooden core, six-sided shingle roof, goose-neck spout over the track (+X). Z up, ground z = 0.
+// Dossier: ./README.md.
+
+import {
+  beam,
+  box,
+  clear,
+  cylinder,
+  defineAsset,
+  grime,
+  hex,
+  lathe,
+  type Mesh,
+  merge,
+  place,
+  planar,
+  tiled,
+  type Vec3,
+} from '@developerz.ai/ts23d';
+
+const FT = 0.3048;
+const TANK_R = (22 * FT) / 2; // 3.353
+const TANK_H = 14 * FT; // 4.267
+const FLOOR_Z = 14 * FT; // superstructure height
+const TANK_TOP = FLOOR_Z + TANK_H;
+const CORE_R = (10 * FT) / 2;
+const POST_R = 2.75; // post circle (estimate: posts sit under the tank, inside its rim)
+const POST_W = 0.3;
+const FOOT_H = 0.45;
+const CAP_Z0 = 3.72;
+const CAP_Z1 = 4.02;
+const ROOF_APOTHEM = TANK_R + 0.35;
+const ROOF_RISE = 1.05;
+const SPOUT_L = 3.4;
+const SPOUT_REST = (25 * Math.PI) / 180;
+const PIVOT: Vec3 = [TANK_R + 0.32, 0, FLOOR_Z + 0.55];
+
+const cypress = hex('#7a5a3e');
+const timber = hex('#8c7b66');
+const timberDark = hex('#6b5d4d');
+const steel = hex('#2b2826');
+const concrete = hex('#b9b3a6');
+const shingle = hex('#4e463e');
+
+/** Ring of `n` flat vertical facets (outward), boards running up: staves, the core's planking. */
+function staveRing(
+  r: number,
+  z0: number,
+  h: number,
+  n: number,
+  color: Vec3,
+  strip: 'wood' | 'plain',
+): Mesh {
+  const out: Mesh[] = [];
+  for (let k = 0; k < n; k++) {
+    const a0 = (k / n) * Math.PI * 2;
+    const a1 = ((k + 1) / n) * Math.PI * 2;
+    const p0: Vec3 = [Math.cos(a0) * r, Math.sin(a0) * r, z0];
+    const p1: Vec3 = [Math.cos(a1) * r, Math.sin(a1) * r, z0];
+    out.push(
+      tiled({
+        origin: p1,
+        u: [0, 0, h],
+        v: [p0[0] - p1[0], p0[1] - p1[1], 0],
+        color,
+        strip,
+        ...(strip === 'plain' ? { vMetres: 100 } : {}),
+      }),
+    );
+  }
+  return merge(out);
+}
+
+/** Axis-aligned box from two corners. */
+const bx = (
+  x0: number,
+  x1: number,
+  y0: number,
+  y1: number,
+  z0: number,
+  z1: number,
+  color: Vec3,
+  strip: 'wood' | 'iron' | 'concrete' | 'plain' = 'wood',
+  bevel = 0,
+): Mesh => {
+  const small = Math.min(Math.abs(x1 - x0), Math.abs(y1 - y0), Math.abs(z1 - z0));
+  return box({
+    size: [Math.abs(x1 - x0), Math.abs(y1 - y0), Math.abs(z1 - z0)],
+    at: [(x0 + x1) / 2, (y0 + y1) / 2, Math.min(z0, z1)],
+    color,
+    strip,
+    ...(bevel > 0 && bevel < small / 2 ? { bevel } : {}),
+  });
+};
+
+export const water_tower = defineAsset({
+  name: 'water_tower',
+  kind: 'building',
+  description:
+    'Frisco 50,000-gallon cypress-stave railroad water tank (Beaumont, Kansas, c. 1886): hooped tub on an eight-post timber trestle with a central core, six-sided shingle roof, goose-neck spout.',
+  tags: ['railroad', 'water-tank', 'lineside', '1880s', 'usa'],
+  license: 'CC0-1.0',
+  sources: [
+    'https://npgallery.nps.gov/GetAsset/f632b7b3-36b4-4a36-be22-47bb617fad0d',
+    'https://commons.wikimedia.org/wiki/File:Beaumont_Kansas_Water_Tower.jpg',
+    'https://en.wikipedia.org/wiki/Beaumont_St._Louis_and_San_Francisco_Railroad_Water_Tank',
+    'https://davesriogrande.net/Structures/WaterTanks/watertanks.htm',
+  ],
+  real: {
+    // Overall box: tank + roof eave (−X) to the spout mouth (+X); roof apex + finial on Z.
+    length: 4.27 + PIVOT[0] + SPOUT_L * Math.cos(SPOUT_REST) + 0.1,
+    width: 2 * ROOF_APOTHEM,
+    height: TANK_TOP + 0.15 + ROOF_RISE + 0.9,
+    measures: [
+      {
+        label: 'tank diameter (22 ft)',
+        value: 22 * FT,
+        axis: 'y',
+        parts: ['tank'],
+        source: 'NRHP 93000843 §7',
+      },
+      {
+        label: 'tank height (14 ft)',
+        value: TANK_H,
+        axis: 'z',
+        parts: ['tank'],
+        source: 'NRHP 93000843 §7',
+      },
+      {
+        label: 'superstructure height (14 ft)',
+        value: FLOOR_Z,
+        axis: 'z',
+        parts: ['trestle'],
+        source: 'NRHP 93000843 §7',
+      },
+      {
+        label: 'core diameter (10 ft)',
+        value: 10 * FT,
+        axis: 'y',
+        parts: ['core'],
+        source: 'NRHP 93000843 §7',
+      },
+      {
+        label: 'core height (14 ft)',
+        value: 14 * FT,
+        axis: 'z',
+        parts: ['core'],
+        source: 'NRHP 93000843 §7',
+      },
+    ],
+  },
+  budget: { triangles: [7900, 3350, 590] },
+  checks: [clear('spout', 'tank', 0.02), clear('spout', 'roof', 0.05)],
+  build(ctx) {
+    const lod = ctx.lod;
+    const bevel = ctx.pick([0.02, 0.01, 0]);
+    const facets = ctx.pick([32, 20, 8]);
+    const dirt = (m: Mesh): Mesh => grime(m, { ground: 1.4, groundStrength: 0.4 });
+
+    // ---- trestle: footings, eight posts, cap ring, X bracing, joists under the tank floor.
+    const tr: Mesh[] = [];
+    const postAt = Array.from({ length: 8 }, (_, k) => {
+      const a = (k / 8) * Math.PI * 2 + Math.PI / 8;
+      return [Math.cos(a) * POST_R, Math.sin(a) * POST_R] as const;
+    });
+    for (const [x, y] of postAt) {
+      tr.push(bx(x - 0.33, x + 0.33, y - 0.33, y + 0.33, 0, FOOT_H, concrete, 'concrete', bevel));
+      tr.push(
+        bx(
+          x - POST_W / 2,
+          x + POST_W / 2,
+          y - POST_W / 2,
+          y + POST_W / 2,
+          FOOT_H,
+          CAP_Z0,
+          timber,
+          'wood',
+          bevel / 2,
+        ),
+      );
+    }
+    postAt.forEach(([x, y], k) => {
+      const [nx, ny] = postAt[(k + 1) % 8] ?? [x, y];
+      // Cap beam post → post (ring), sitting on the post tops.
+      tr.push(
+        beam({
+          from: [x, y, CAP_Z0 + 0.15],
+          to: [nx, ny, CAP_Z0 + 0.15],
+          width: 0.3,
+          height: 0.3,
+          color: timberDark,
+          strip: 'wood',
+          up: [0, 0, 1],
+        }),
+      );
+      if (lod < 2) {
+        // X brace on the outer face of the bay, foot of one post to the head of the next.
+        const mx = (x + nx) / 2;
+        const my = (y + ny) / 2;
+        const ml = Math.hypot(mx, my);
+        const off = 0.2 / ml;
+        const o = (px: number, py: number, z: number): Vec3 => [px + mx * off, py + my * off, z];
+        tr.push(
+          beam({
+            from: o(x, y, FOOT_H + 0.25),
+            to: o(nx, ny, CAP_Z0 - 0.1),
+            width: 0.2,
+            height: 0.1,
+            color: timber,
+            strip: 'wood',
+            up: [mx / ml, my / ml, 0],
+          }),
+        );
+        tr.push(
+          beam({
+            from: o(nx, ny, FOOT_H + 0.25),
+            to: o(x, y, CAP_Z0 - 0.1),
+            width: 0.2,
+            height: 0.1,
+            color: timber,
+            strip: 'wood',
+            up: [mx / ml, my / ml, 0],
+          }),
+        );
+        if (lod === 0) {
+          // Through-bolt at the crossing and at each brace end.
+          const bolt = cylinder({
+            radius: 0.035,
+            length: 0.06,
+            segments: 6,
+            axis: 'x',
+            color: steel,
+          });
+          const n = [mx / ml, my / ml];
+          for (const [px, py, z] of [
+            [mx, my, (FOOT_H + 0.25 + CAP_Z0 - 0.1) / 2],
+            [x, y, FOOT_H + 0.3],
+            [nx, ny, FOOT_H + 0.3],
+            [x, y, CAP_Z0 - 0.15],
+            [nx, ny, CAP_Z0 - 0.15],
+          ] as const) {
+            const at = o(px, py, z);
+            tr.push(
+              place(bolt, {
+                at: [at[0] + (n[0] ?? 0) * 0.06, at[1] + (n[1] ?? 0) * 0.06, at[2]],
+                yaw: Math.atan2(n[1] ?? 0, n[0] ?? 1),
+              }),
+            );
+          }
+        }
+      }
+    });
+    // Joists along X across the tank floor, ends showing past the staves.
+    const joistStep = ctx.pick([0.55, 0.9, 1.6]);
+    for (let y = -TANK_R + 0.35; y <= TANK_R - 0.3; y += joistStep) {
+      const half = Math.sqrt(Math.max(0, TANK_R * TANK_R - y * y)) + 0.15;
+      tr.push(bx(-half, half, y - 0.1, y + 0.1, CAP_Z1, FLOOR_Z, timberDark, 'wood'));
+    }
+    ctx.part('trestle', dirt(merge(tr)));
+
+    // ---- central core: vertical planking round a 10 ft cylinder, with its access door.
+    const coreN = ctx.pick([12, 12, 8]);
+    const core: Mesh[] = [
+      staveRing(CORE_R, 0, 14 * FT, coreN, timberDark, lod === 2 ? 'plain' : 'wood'),
+    ];
+    core.push(
+      lathe({
+        profile: [
+          [0, 14 * FT - 0.01],
+          [CORE_R, 14 * FT - 0.01],
+          [CORE_R, 14 * FT],
+        ],
+        segments: coreN,
+        color: timberDark,
+      }),
+    ); // lid
+    if (lod < 2) {
+      const da = Math.PI; // door faces −X, away from the track
+      const dx = Math.cos(da) * CORE_R * Math.cos(Math.PI / coreN);
+      core.push(bx(dx - 0.06, dx + 0.002, -0.4, 0.4, 0.05, 2.0, timber, 'wood'));
+      if (lod === 0) {
+        core.push(bx(dx - 0.09, dx - 0.06, -0.45, 0.45, 1.98, 2.06, timberDark, 'wood'));
+        for (const z of [0.4, 1.6])
+          core.push(bx(dx - 0.08, dx - 0.06, 0.05, 0.38, z, z + 0.05, steel, 'iron')); // strap hinges
+      }
+    }
+    ctx.part('core', dirt(merge(core)));
+
+    // ---- tank: stave tub, hoops (closer near the bottom), lugs, chime overhang.
+    ctx.part(
+      'tank',
+      staveRing(TANK_R, FLOOR_Z, TANK_H, facets, cypress, lod === 2 ? 'plain' : 'wood'),
+    );
+    if (lod < 2) {
+      const hoops: Mesh[] = [];
+      const n = lod === 0 ? 14 : 7;
+      const hoopSegs = ctx.pick([32, 20, 8]);
+      for (let i = 0; i < n; i++) {
+        // Spacing grows with height: pressure falls off toward the top.
+        const t = (i + 0.5) / n;
+        const z = FLOOR_Z + 0.12 + (TANK_H - 0.3) * t ** 1.35;
+        const rr = TANK_R / Math.cos(Math.PI / facets) + 0.004;
+        hoops.push(
+          lathe({
+            profile: [
+              [rr, z],
+              [rr + 0.012, z + 0.004],
+              [rr + 0.012, z + 0.03],
+              [rr, z + 0.034],
+            ],
+            segments: hoopSegs,
+            color: steel,
+            strip: 'iron',
+          }),
+        );
+        if (lod === 0) {
+          // Lug (the hoop's tightening nut), staggered round the tank.
+          const a = (i * 2.399) % (Math.PI * 2);
+          hoops.push(
+            place(
+              box({ size: [0.05, 0.16, 0.07], at: [0, 0, -0.02], color: steel, strip: 'iron' }),
+              { at: [Math.cos(a) * (rr + 0.03), Math.sin(a) * (rr + 0.03), z], yaw: a },
+            ),
+          );
+        }
+      }
+      ctx.part('tank_hoops', merge(hoops));
+    }
+
+    // ---- roof: low six-sided pyramid of shingles, fascia, finial and lightning rod, hatch.
+    const roofM: Mesh[] = [];
+    const circ = ROOF_APOTHEM / Math.cos(Math.PI / 6);
+    const eaveZ = TANK_TOP + 0.15;
+    const apex: Vec3 = [0, 0, eaveZ + ROOF_RISE];
+    const corner = (k: number, z: number, r = circ): Vec3 => [
+      Math.cos((k * Math.PI) / 3) * r,
+      Math.sin((k * Math.PI) / 3) * r,
+      z,
+    ];
+    for (let k = 0; k < 6; k++) {
+      roofM.push(
+        planar({
+          points: [corner(k, eaveZ), corner(k + 1, eaveZ), apex],
+          color: shingle,
+          strip: 'slate',
+        }),
+      );
+      roofM.push(
+        tiled({
+          origin: corner(k + 1, TANK_TOP),
+          u: [corner(k, 0)[0] - corner(k + 1, 0)[0], corner(k, 0)[1] - corner(k + 1, 0)[1], 0],
+          v: [0, 0, 0.15],
+          color: timberDark,
+          strip: 'wood',
+        }),
+      ); // fascia
+      roofM.push(
+        planar({
+          points: [corner(k + 1, TANK_TOP), corner(k, TANK_TOP), [0, 0, TANK_TOP]],
+          color: timberDark,
+          strip: 'wood',
+        }),
+      ); // soffit
+    }
+    if (lod < 2) {
+      roofM.push(
+        lathe({
+          profile: [
+            [0.12, apex[2] - 0.05],
+            [0.12, apex[2] + 0.12],
+            [0.06, apex[2] + 0.25],
+            [0, apex[2] + 0.3],
+          ],
+          segments: 8,
+          color: steel,
+        }),
+      ); // finial cap
+      roofM.push(
+        cylinder({
+          radius: 0.012,
+          length: 0.62,
+          segments: 4,
+          at: [0, 0, apex[2] + 0.58],
+          color: steel,
+        }),
+      ); // lightning rod
+    }
+    if (lod === 0) {
+      // Hip caps (ridge boards) and a hatch on the −X slope.
+      for (let k = 0; k < 6; k++)
+        roofM.push(
+          beam({
+            from: corner(k, eaveZ + 0.02),
+            to: [0, 0, apex[2] + 0.02],
+            width: 0.1,
+            height: 0.04,
+            color: timberDark,
+            strip: 'wood',
+          }),
+        );
+      const slope = Math.atan2(ROOF_RISE, ROOF_APOTHEM);
+      roofM.push(
+        place(
+          box({ size: [0.7, 0.7, 0.12], at: [0, 0, -0.04], color: timberDark, strip: 'wood' }),
+          { at: [-ROOF_APOTHEM * 0.55, 0, eaveZ + ROOF_RISE * 0.45], pitch: -slope },
+        ),
+      );
+    }
+    ctx.part('roof', merge(roofM));
+
+    // ---- outlet + hinge on the track side; the spout swings on it.
+    const outlet: Mesh[] = [
+      cylinder({
+        radius: 0.2,
+        length: PIVOT[0] - TANK_R + 0.08,
+        segments: ctx.pick([14, 10, 6]),
+        axis: 'x',
+        at: [(TANK_R - 0.08 + PIVOT[0]) / 2, 0, PIVOT[2]],
+        color: steel,
+      }),
+    ];
+    if (lod < 2)
+      outlet.push(
+        cylinder({
+          radius: 0.27,
+          length: 0.06,
+          segments: ctx.pick([14, 10, 6]),
+          axis: 'x',
+          at: [TANK_R + 0.03, 0, PIVOT[2]],
+          color: steel,
+        }),
+      ); // flange
+    ctx.part('outlet', merge(outlet));
+
+    ctx.group('spout', {
+      at: PIVOT,
+      motion: { kind: 'sway', axis: [0, 1, 0], degrees: 15, hz: 0.1 },
+      clearOf: ['outlet'], // the hinge knuckle turns inside the outlet flange by design
+    });
+    const dir: Vec3 = [Math.cos(SPOUT_REST), 0, Math.sin(SPOUT_REST)];
+    const along = (d: number, z = 0): Vec3 => [dir[0] * d, 0, dir[2] * d + z];
+    const sp: Mesh[] = [
+      beam({
+        from: along(0),
+        to: along(SPOUT_L * 0.72),
+        width: 0.4,
+        segments: ctx.pick([12, 8, 6]),
+        color: steel,
+      }),
+      beam({
+        from: along(SPOUT_L * 0.7),
+        to: along(SPOUT_L),
+        width: 0.32,
+        segments: ctx.pick([12, 8, 6]),
+        color: steel,
+      }),
+    ];
+    if (lod < 2) {
+      sp.push(cylinder({ radius: 0.25, length: 0.42, segments: 10, axis: 'y', color: steel })); // hinge knuckle
+      sp.push(
+        place(
+          lathe({
+            profile: [
+              [0.16, 0],
+              [0.24, 0.16],
+              [0.24, 0.2],
+            ],
+            segments: 10,
+            color: steel,
+          }),
+          { at: along(SPOUT_L - 0.05), pitch: Math.PI / 2 - SPOUT_REST },
+        ),
+      );
+      for (const d of [0.9, 1.9])
+        sp.push(
+          place(cylinder({ radius: 0.215, length: 0.05, segments: 10, axis: 'x', color: steel }), {
+            at: along(d),
+            pitch: -SPOUT_REST,
+          }),
+        ); // bands
+    }
+    if (lod === 0) {
+      // Pull chain hanging from the mouth (the fireman pulls it down over the tender).
+      const tip = along(SPOUT_L - 0.1, -0.2);
+      for (let i = 0; i < 9; i++)
+        sp.push(
+          place(box({ size: [0.03, 0.06, 0.12], color: steel, strip: 'iron' }), {
+            at: [tip[0], 0, tip[2] - i * 0.13],
+            yaw: (i % 2) * (Math.PI / 2),
+          }),
+        );
+    }
+    ctx.part('spout_body', merge(sp), { parent: 'spout' });
+    ctx.socket('water_fill', {
+      kind: 'interact',
+      parent: 'spout',
+      at: along(SPOUT_L),
+      dir: [0, 0, -1],
+    });
+
+    // ---- ladder up the −X side to the eave, with stays to the tank and the cap ring.
+    if (lod < 2) {
+      const lx = -(TANK_R + 0.42);
+      const top = TANK_TOP - 0.1;
+      const lad: Mesh[] = [];
+      for (const y of [-0.22, 0.22])
+        lad.push(bx(lx - 0.05, lx + 0.05, y - 0.03, y + 0.03, 0, top, timber, 'wood'));
+      const rung = ctx.pick([0.3, 0.6, 1]);
+      for (let z = 0.3; z < top - 0.1; z += rung)
+        lad.push(
+          cylinder({
+            radius: 0.018,
+            length: 0.44,
+            segments: lod === 0 ? 6 : 4,
+            axis: 'y',
+            at: [lx, 0, z],
+            color: timber,
+          }),
+        );
+      for (const z of [CAP_Z0 + 0.15, FLOOR_Z + 1.5, TANK_TOP - 0.4])
+        for (const y of [-0.22, 0.22]) {
+          const r =
+            z > FLOOR_Z
+              ? TANK_R / Math.cos(Math.PI / facets) - 0.01
+              : POST_R * Math.cos(Math.PI / 8) + 0.05;
+          lad.push(
+            beam({
+              from: [lx + 0.05, y, z],
+              to: [-r, y * 0.6, z],
+              width: 0.05,
+              height: 0.03,
+              color: steel,
+              strip: 'iron',
+            }),
+          );
+        }
+      ctx.part('ladder', dirt(merge(lad)));
+    }
+  },
+});

package/src/cli/args.ts

@@ -0,0 +1,125 @@
+// argv → Args for `t3d`. No dependency, no magic: flags are few and documented in HELP.
+// Bad render flags (--size/--az/--el/--fov) throw T3D_RENDER_OPTIONS with the fix.
+
+import { Ts23dError } from '../core/index.ts';
+import { checkBeautyOptions, parseSize } from '../render/index.ts';
+
+export interface Args {
+  readonly cmd: string;
+  readonly files: string[];
+  readonly out: string;
+  readonly json: boolean;
+  readonly animations: boolean;
+  /** `build` also renders the contact sheet unless --no-shot. */
+  readonly shot: boolean;
+  /** Trim-sheet textures: shared files in <out>/ (default), embedded per GLB, or none. */
+  readonly sheet: 'external' | 'embed' | 'none';
+  readonly sheetSize: 512 | 1024 | 2048;
+  /** Which detail levels to build: all three by default, or e.g. only the hero mesh. */
+  readonly lods: readonly (0 | 1 | 2)[];
+  /**
+   * How LODs land on disk: `split` lodN.glb per level · `single` one <asset>.glb with MSFT_lod
+   * alternates · `both` (default): split files import everywhere, the single file is for
+   * MSFT_lod-aware loaders and one-file pipelines.
+   */
+  readonly lodFiles: 'split' | 'single' | 'both';
+  /** Beauty-render camera and size (hero, review, and build's hero.png); unset = defaults. */
+  readonly render: {
+    readonly width?: number;
+    readonly height?: number;
+    readonly azDeg?: number;
+    readonly elDeg?: number;
+    readonly fovDeg?: number;
+  };
+}
+
+export const HELP = `usage: t3d <command> <recipe.ts…> [flags]
+  build   GLB × 3 LODs + hero + contact sheet + manifest.json per asset; exit 1 on any QA finding
+  shot    contact sheet + manifest.json only (fast look)
+  hero    beauty render only → <out>/<asset>/hero.png (3/4 product shot, textured, shadowed)
+  review  AI review pack → <out>/<asset>/review/: hero, sheet, close-ups, LOD strip, review.md
+          (checklist prompt for a vision agent) and review.json (image metrics + warnings)
+  list    the assets each module exports
+flags:
+  --out <dir>     output root (default: out) → <dir>/<asset>/{lod0,lod1,lod2}.glb hero.png sheet.png manifest.json
+  --no-animations skip the baked 'run' clip (default: baked, so viewers can play it)
+  --no-shot       build without rendering hero.png and the contact sheet
+  --size WxH      beauty render size (default 1600x900) · --az <deg> camera azimuth from the
+                  front, default -35 (front-left 3/4) · --el <deg> elevation, default 18 · --fov <deg> 30
+  --sheet <mode>  external (default): one shared trim_sheet_{albedo,normal,orm}.png in <out>/,
+                  referenced by every GLB · embed: self-contained GLBs · none: vertex colour only
+  --sheet-size n  512 | 1024 | 2048 (default)
+  --lods <list>   which detail levels to build: 0,1,2 (default) · 0 = hero only · 0,2 = near + far
+  --lods <mode>   how they are written: both (default) = lod0/1/2.glb + <asset>.glb · split = lodN.glb
+                  only · single = <asset>.glb only (LOD0 in the scene, LOD1/2 as MSFT_lod alternates
+                  with screen-coverage switch hints; viewers without MSFT_lod show LOD0 only)
+  --json          machine-readable output`;
+
+export function parseArgs(argv: readonly string[]): Args {
+  const files: string[] = [];
+  let out = 'out';
+  let json = false;
+  let animations = true;
+  let shot = true;
+  let sheet: Args['sheet'] = 'external';
+  let sheetSize: Args['sheetSize'] = 2048;
+  let lods: Args['lods'] = [0, 1, 2];
+  let lodFiles: Args['lodFiles'] = 'both';
+  const render: {
+    width?: number;
+    height?: number;
+    azDeg?: number;
+    elDeg?: number;
+    fovDeg?: number;
+  } = {};
+  const num = (flag: string, v: string | undefined): number => {
+    const n = Number(v);
+    if (v === undefined || v.trim() === '' || !Number.isFinite(n))
+      throw new Ts23dError('T3D_RENDER_OPTIONS', {
+        cause: `${flag} needs a number of degrees, got ${v === undefined ? 'nothing' : `"${v}"`}`,
+        fix: `pass e.g. ${flag} ${flag === '--fov' ? 30 : flag === '--el' ? 18 : -35}`,
+      });
+    return n;
+  };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i] ?? '';
+    if (a === '--json') json = true;
+    else if (a === '--no-animations') animations = false;
+    else if (a === '--animations') animations = true;
+    else if (a === '--no-shot') shot = false;
+    else if (a === '--out') out = argv[++i] ?? out;
+    else if (a === '--sheet') {
+      const m = argv[++i];
+      sheet = m === 'embed' || m === 'none' ? m : 'external';
+    } else if (a === '--lods' && /^(split|single|both)$/.test(argv[i + 1] ?? '')) {
+      lodFiles = argv[++i] as Args['lodFiles'];
+    } else if (a === '--lods') {
+      const picked = (argv[++i] ?? '')
+        .split(',')
+        .map(Number)
+        .filter((n): n is 0 | 1 | 2 => n === 0 || n === 1 || n === 2);
+      lods = picked.length ? [...new Set(picked)].sort() : lods;
+    } else if (a === '--sheet-size') {
+      const n = Number(argv[++i]);
+      sheetSize = n === 512 || n === 1024 ? n : 2048;
+    } else if (a === '--size') Object.assign(render, parseSize(argv[++i] ?? ''));
+    else if (a === '--az') render.azDeg = num(a, argv[++i]);
+    else if (a === '--el') render.elDeg = num(a, argv[++i]);
+    else if (a === '--fov') render.fovDeg = num(a, argv[++i]);
+    else files.push(a);
+  }
+  checkBeautyOptions(render);
+  return {
+    cmd: argv[0] ?? 'help',
+    files,
+    out,
+    json,
+    animations,
+    shot,
+    sheet,
+    sheetSize,
+    lods,
+    lodFiles,
+    render,
+  };
+}