@iwsdk/create 0.5.3 → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/dist/cli.js +7224 -216
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -0,0 +1,599 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+
8
+ /**
9
+ * Hard-surface construction library.
10
+ *
11
+ * Pure geometry and math only: no materials, no `World`, no DOM, no timers and
12
+ * no randomness that is not explicitly seeded. The asset manifest is evaluated
13
+ * once by the application runtime and once by the editor in a separate JS
14
+ * realm, so everything here must be deterministic.
15
+ *
16
+ * Conventions used by every model built on top of this file:
17
+ * - meters
18
+ * - model forward is -Z, up is +Y, starboard is +X
19
+ * - closed lofts are watertight and get their winding corrected by signed
20
+ * volume, so callers never have to reason about ring order
21
+ * - surface detail is placed from an explicit surface frame, never from a
22
+ * guessed Euler triple
23
+ */
24
+
25
+ import {
26
+ BufferAttribute,
27
+ BufferGeometry,
28
+ ExtrudeGeometry,
29
+ Float32BufferAttribute,
30
+ InterleavedBufferAttribute,
31
+ Matrix4,
32
+ Object3D,
33
+ Shape,
34
+ Vector3,
35
+ } from '@iwsdk/core';
36
+
37
+ /* ------------------------------------------------------------------ *
38
+ * Deterministic pseudo-randomness
39
+ * ------------------------------------------------------------------ */
40
+
41
+ /** Seeded LCG. Never use `Math.random()` in a manifest-evaluated module. */
42
+ export function makeRandom(seed: number): () => number {
43
+ let state = (seed >>> 0) || 0x9e3779b9;
44
+ return () => {
45
+ state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
46
+ return state / 4294967296;
47
+ };
48
+ }
49
+
50
+ /* ------------------------------------------------------------------ *
51
+ * Surface frames
52
+ * ------------------------------------------------------------------ */
53
+
54
+ export interface SurfaceFrame {
55
+ origin: Vector3;
56
+ normal: Vector3;
57
+ tangent: Vector3;
58
+ bitangent: Vector3;
59
+ }
60
+
61
+ /**
62
+ * Build an orthonormal frame on a surface. `tangentHint` is projected into the
63
+ * surface plane, so callers can ask for "along the hull" or "spanwise" without
64
+ * knowing the local curvature.
65
+ */
66
+ export function surfaceFrame(
67
+ origin: Vector3,
68
+ normal: Vector3,
69
+ tangentHint: Vector3,
70
+ ): SurfaceFrame {
71
+ const n = normal.clone().normalize();
72
+ const t = tangentHint.clone().addScaledVector(n, -tangentHint.dot(n));
73
+ if (t.lengthSq() < 1e-10) {
74
+ t.copy(Math.abs(n.y) < 0.9 ? new Vector3(0, 1, 0) : new Vector3(1, 0, 0));
75
+ t.addScaledVector(n, -t.dot(n));
76
+ }
77
+ t.normalize();
78
+ const b = n.clone().cross(t).normalize();
79
+ t.copy(b).cross(n).normalize();
80
+ return { origin: origin.clone(), normal: n, tangent: t, bitangent: b };
81
+ }
82
+
83
+ /**
84
+ * Seat an object on a surface frame. Detail authored with local X/Y in the
85
+ * plane and local +Z as thickness lands flush against the surface.
86
+ */
87
+ export function placeOnSurface(
88
+ object: Object3D,
89
+ frame: SurfaceFrame,
90
+ normalOffset = 0,
91
+ ): void {
92
+ object.position.copy(frame.origin).addScaledVector(frame.normal, normalOffset);
93
+ object.quaternion.setFromRotationMatrix(
94
+ new Matrix4().makeBasis(frame.tangent, frame.bitangent, frame.normal),
95
+ );
96
+ }
97
+
98
+ /** Mirror a surface frame across the YZ plane while keeping a right-handed basis. */
99
+ export function mirrorSurfaceFrameX(frame: SurfaceFrame): SurfaceFrame {
100
+ const reflect = (value: Vector3): Vector3 =>
101
+ new Vector3(-value.x, value.y, value.z);
102
+ return {
103
+ origin: reflect(frame.origin),
104
+ normal: reflect(frame.normal),
105
+ tangent: reflect(frame.tangent).negate(),
106
+ bitangent: reflect(frame.bitangent),
107
+ };
108
+ }
109
+
110
+ /** Orient an object from an explicit basis instead of Euler angles. */
111
+ export function orientBasis(
112
+ object: Object3D,
113
+ xDir: Vector3,
114
+ yDir: Vector3,
115
+ ): void {
116
+ const x = xDir.clone().normalize();
117
+ const y = yDir.clone().addScaledVector(x, -yDir.dot(x)).normalize();
118
+ const z = x.clone().cross(y).normalize();
119
+ object.quaternion.setFromRotationMatrix(new Matrix4().makeBasis(x, y, z));
120
+ }
121
+
122
+ /**
123
+ * Position and orient a Y-up primitive (cylinder, capsule) so it spans `a` to
124
+ * `b`. Returns the span length so the caller can size the geometry.
125
+ */
126
+ export function alignSpan(
127
+ object: Object3D,
128
+ a: Vector3,
129
+ b: Vector3,
130
+ upHint = new Vector3(0, 0, 1),
131
+ ): number {
132
+ const dir = b.clone().sub(a);
133
+ const length = dir.length();
134
+ if (length < 1e-6) {return 0;}
135
+ const y = dir.clone().normalize();
136
+ const hint =
137
+ Math.abs(upHint.dot(y)) > 0.98 ? new Vector3(1, 0, 0) : upHint.clone();
138
+ const x = hint.clone().cross(y).normalize();
139
+ const z = x.clone().cross(y).normalize();
140
+ object.quaternion.setFromRotationMatrix(new Matrix4().makeBasis(x, y, z));
141
+ object.position.copy(a).addScaledVector(dir, 0.5);
142
+ return length;
143
+ }
144
+
145
+ /* ------------------------------------------------------------------ *
146
+ * Winding / mirroring
147
+ * ------------------------------------------------------------------ */
148
+
149
+ function flipWinding(geometry: BufferGeometry): void {
150
+ const index = geometry.getIndex();
151
+ if (index) {
152
+ const array = index.array as Uint16Array | Uint32Array;
153
+ for (let i = 0; i < array.length; i += 3) {
154
+ const swap = array[i + 1];
155
+ array[i + 1] = array[i + 2];
156
+ array[i + 2] = swap;
157
+ }
158
+ index.needsUpdate = true;
159
+ return;
160
+ }
161
+
162
+ const attributes: Array<BufferAttribute | InterleavedBufferAttribute> = [
163
+ ...Object.values(geometry.attributes),
164
+ ...Object.values(geometry.morphAttributes).flat(),
165
+ ];
166
+ for (const attribute of attributes) {
167
+ for (let triangle = 0; triangle + 2 < attribute.count; triangle += 3) {
168
+ for (let component = 0; component < attribute.itemSize; component += 1) {
169
+ const swap = attribute.getComponent(triangle + 1, component);
170
+ attribute.setComponent(
171
+ triangle + 1,
172
+ component,
173
+ attribute.getComponent(triangle + 2, component),
174
+ );
175
+ attribute.setComponent(triangle + 2, component, swap);
176
+ }
177
+ }
178
+ attribute.needsUpdate = true;
179
+ }
180
+ }
181
+
182
+ /**
183
+ * Correct the winding of a closed loft using its signed volume, which is
184
+ * origin-independent for a watertight mesh. This removes the whole class of
185
+ * "the hull renders inside out" defects without resorting to DoubleSide.
186
+ */
187
+ export function ensureOutwardWinding(geometry: BufferGeometry): BufferGeometry {
188
+ const index = geometry.getIndex();
189
+ const position = geometry.getAttribute('position');
190
+ if (!index || !position) {return geometry;}
191
+ const a = new Vector3();
192
+ const b = new Vector3();
193
+ const c = new Vector3();
194
+ const cross = new Vector3();
195
+ let volume = 0;
196
+ for (let i = 0; i < index.count; i += 3) {
197
+ a.fromBufferAttribute(position, index.getX(i));
198
+ b.fromBufferAttribute(position, index.getX(i + 1));
199
+ c.fromBufferAttribute(position, index.getX(i + 2));
200
+ volume += a.dot(cross.copy(b).cross(c));
201
+ }
202
+ if (volume < 0) {
203
+ flipWinding(geometry);
204
+ geometry.computeVertexNormals();
205
+ }
206
+ return geometry;
207
+ }
208
+
209
+ /** Mirror a chiral geometry across X, preserving outward-facing winding. */
210
+ export function mirrorGeometryX(geometry: BufferGeometry): BufferGeometry {
211
+ const mirrored = geometry.clone();
212
+ mirrored.scale(-1, 1, 1);
213
+ flipWinding(mirrored);
214
+ mirrored.computeVertexNormals();
215
+ return mirrored;
216
+ }
217
+
218
+ /* ------------------------------------------------------------------ *
219
+ * Bevelled box — the hard-surface workhorse
220
+ * ------------------------------------------------------------------ */
221
+
222
+ function roundedRectShape(width: number, height: number, radius: number): Shape {
223
+ const hw = width / 2;
224
+ const hh = height / 2;
225
+ const r = Math.max(0, Math.min(radius, hw - 1e-5, hh - 1e-5));
226
+ const shape = new Shape();
227
+ shape.moveTo(-hw + r, -hh);
228
+ shape.lineTo(hw - r, -hh);
229
+ if (r > 0) {shape.absarc(hw - r, -hh + r, r, -Math.PI / 2, 0, false);}
230
+ shape.lineTo(hw, hh - r);
231
+ if (r > 0) {shape.absarc(hw - r, hh - r, r, 0, Math.PI / 2, false);}
232
+ shape.lineTo(-hw + r, hh);
233
+ if (r > 0) {shape.absarc(-hw + r, hh - r, r, Math.PI / 2, Math.PI, false);}
234
+ shape.lineTo(-hw, -hh + r);
235
+ if (r > 0) {shape.absarc(-hw + r, -hh + r, r, Math.PI, 1.5 * Math.PI, false);}
236
+ return shape;
237
+ }
238
+
239
+ /**
240
+ * A bevelled, optionally round-cornered box centred on the origin, extruded
241
+ * along local +Z. Sized so the finished solid measures exactly w x h x d.
242
+ */
243
+ export function bevelBox(
244
+ width: number,
245
+ height: number,
246
+ depth: number,
247
+ bevel = 0.01,
248
+ cornerRadius?: number,
249
+ curveSegments = 2,
250
+ ): BufferGeometry {
251
+ const b = Math.max(
252
+ 1e-4,
253
+ Math.min(bevel, width * 0.24, height * 0.24, depth * 0.45),
254
+ );
255
+ const shapeW = Math.max(2e-4, width - 2 * b);
256
+ const shapeH = Math.max(2e-4, height - 2 * b);
257
+ const radius = Math.max(
258
+ 0,
259
+ Math.min(cornerRadius ?? b * 1.5, shapeW / 2 - 1e-5, shapeH / 2 - 1e-5),
260
+ );
261
+ const extrudeDepth = Math.max(1e-4, depth - 2 * b);
262
+ const geometry = new ExtrudeGeometry(
263
+ roundedRectShape(shapeW, shapeH, radius),
264
+ {
265
+ depth: extrudeDepth,
266
+ bevelEnabled: true,
267
+ bevelThickness: b,
268
+ bevelSize: b,
269
+ bevelOffset: 0,
270
+ bevelSegments: 1,
271
+ curveSegments,
272
+ steps: 1,
273
+ },
274
+ );
275
+ geometry.translate(0, 0, -extrudeDepth / 2);
276
+ geometry.computeVertexNormals();
277
+ return geometry;
278
+ }
279
+
280
+ /**
281
+ * A trapezoidal plate lying in local XY with thickness along +Z: the standard
282
+ * armour-panel form. Widths are given per edge so plates can follow a taper.
283
+ */
284
+ export function taperPlate(
285
+ lengthX: number,
286
+ widthYFront: number,
287
+ widthYBack: number,
288
+ thickness: number,
289
+ bevel = 0.006,
290
+ ): BufferGeometry {
291
+ const hx = lengthX / 2;
292
+ const shape = new Shape();
293
+ shape.moveTo(-hx, -widthYBack / 2);
294
+ shape.lineTo(hx, -widthYFront / 2);
295
+ shape.lineTo(hx, widthYFront / 2);
296
+ shape.lineTo(-hx, widthYBack / 2);
297
+ shape.closePath();
298
+ const b = Math.max(1e-4, Math.min(bevel, thickness * 0.45));
299
+ const geometry = new ExtrudeGeometry(shape, {
300
+ depth: Math.max(1e-4, thickness - 2 * b),
301
+ bevelEnabled: true,
302
+ bevelThickness: b,
303
+ bevelSize: b,
304
+ bevelOffset: 0,
305
+ bevelSegments: 1,
306
+ steps: 1,
307
+ });
308
+ geometry.translate(0, 0, -(thickness - 2 * b) / 2);
309
+ geometry.computeVertexNormals();
310
+ return geometry;
311
+ }
312
+
313
+ /* ------------------------------------------------------------------ *
314
+ * Lofted surfaces
315
+ * ------------------------------------------------------------------ */
316
+
317
+ function superellipse(value: number, exponent: number): number {
318
+ const magnitude = Math.abs(value);
319
+ const scaled = magnitude === 0 ? 0 : Math.pow(magnitude, exponent);
320
+ return value < 0 ? -scaled : scaled;
321
+ }
322
+
323
+ function lerp(a: number, b: number, t: number): number {
324
+ return a + (b - a) * t;
325
+ }
326
+
327
+ /** One cross-section of a tube swept along +Z. */
328
+ export interface TubeSection {
329
+ z: number;
330
+ /** lateral centre offset */
331
+ cx?: number;
332
+ /** vertical centre offset */
333
+ cy?: number;
334
+ halfW: number;
335
+ hUp: number;
336
+ /** defaults to `hUp` */
337
+ hDown?: number;
338
+ /** 2 = ellipse, 4 = nearly square. Higher reads as machined. */
339
+ power?: number;
340
+ }
341
+
342
+ /** One spanwise station of a blade swept along +X. */
343
+ export interface BladeStation {
344
+ x: number;
345
+ /** vertical centre of the section */
346
+ y?: number;
347
+ leadZ: number;
348
+ trailZ: number;
349
+ thickUp: number;
350
+ thickDown?: number;
351
+ power?: number;
352
+ }
353
+
354
+ interface ResolvedSection {
355
+ cx: number;
356
+ cy: number;
357
+ a: number;
358
+ up: number;
359
+ down: number;
360
+ power: number;
361
+ }
362
+
363
+ function interpolate(
364
+ along: number,
365
+ keys: number[],
366
+ resolve: (i: number) => ResolvedSection,
367
+ ): ResolvedSection {
368
+ const last = keys.length - 1;
369
+ if (along <= keys[0]) {return resolve(0);}
370
+ if (along >= keys[last]) {return resolve(last);}
371
+ let i = 0;
372
+ while (i < last && keys[i + 1] < along) {i += 1;}
373
+ const t = (along - keys[i]) / (keys[i + 1] - keys[i]);
374
+ const lo = resolve(i);
375
+ const hi = resolve(i + 1);
376
+ return {
377
+ cx: lerp(lo.cx, hi.cx, t),
378
+ cy: lerp(lo.cy, hi.cy, t),
379
+ a: lerp(lo.a, hi.a, t),
380
+ up: lerp(lo.up, hi.up, t),
381
+ down: lerp(lo.down, hi.down, t),
382
+ power: lerp(lo.power, hi.power, t),
383
+ };
384
+ }
385
+
386
+ /**
387
+ * A swept superelliptical surface that can be both tessellated into a closed
388
+ * loft and queried for surface frames. Detail placement uses the same
389
+ * evaluator as the geometry, so attached parts cannot drift off the hull.
390
+ */
391
+ export class LoftSurface {
392
+ readonly range: [number, number];
393
+
394
+ private constructor(
395
+ private readonly evaluate: (along: number, theta: number) => Vector3,
396
+ private readonly centre: (along: number) => Vector3,
397
+ range: [number, number],
398
+ ) {
399
+ this.range = range;
400
+ }
401
+
402
+ /** Sweep along +Z: fuselages, nacelles, canopies. */
403
+ static tube(sections: TubeSection[]): LoftSurface {
404
+ const sorted = [...sections].sort((l, r) => l.z - r.z);
405
+ const keys = sorted.map((s) => s.z);
406
+ const resolve = (i: number): ResolvedSection => {
407
+ const s = sorted[i];
408
+ return {
409
+ cx: s.cx ?? 0,
410
+ cy: s.cy ?? 0,
411
+ a: s.halfW,
412
+ up: s.hUp,
413
+ down: s.hDown ?? s.hUp,
414
+ power: s.power ?? 2.6,
415
+ };
416
+ };
417
+ const evaluate = (z: number, theta: number): Vector3 => {
418
+ const s = interpolate(z, keys, resolve);
419
+ const exponent = 2 / s.power;
420
+ const sin = Math.sin(theta);
421
+ return new Vector3(
422
+ s.cx + s.a * superellipse(Math.cos(theta), exponent),
423
+ s.cy + (sin >= 0 ? s.up : s.down) * superellipse(sin, exponent),
424
+ z,
425
+ );
426
+ };
427
+ const centre = (z: number): Vector3 => {
428
+ const s = interpolate(z, keys, resolve);
429
+ return new Vector3(s.cx, s.cy, z);
430
+ };
431
+ return new LoftSurface(evaluate, centre, [keys[0], keys[keys.length - 1]]);
432
+ }
433
+
434
+ /**
435
+ * Sweep along +X: wings and, once reoriented by an explicit basis, fins.
436
+ * theta = 0 is the trailing edge, theta = pi/2 the upper surface.
437
+ */
438
+ static blade(stations: BladeStation[]): LoftSurface {
439
+ const sorted = [...stations].sort((l, r) => l.x - r.x);
440
+ const keys = sorted.map((s) => s.x);
441
+ const resolve = (i: number): ResolvedSection => {
442
+ const s = sorted[i];
443
+ return {
444
+ cx: (s.leadZ + s.trailZ) / 2,
445
+ cy: s.y ?? 0,
446
+ a: (s.trailZ - s.leadZ) / 2,
447
+ up: s.thickUp,
448
+ down: s.thickDown ?? s.thickUp,
449
+ power: s.power ?? 1.9,
450
+ };
451
+ };
452
+ const evaluate = (x: number, theta: number): Vector3 => {
453
+ const s = interpolate(x, keys, resolve);
454
+ const exponent = 2 / s.power;
455
+ const sin = Math.sin(theta);
456
+ return new Vector3(
457
+ x,
458
+ s.cy + (sin >= 0 ? s.up : s.down) * superellipse(sin, exponent),
459
+ s.cx + s.a * superellipse(Math.cos(theta), exponent),
460
+ );
461
+ };
462
+ const centre = (x: number): Vector3 => {
463
+ const s = interpolate(x, keys, resolve);
464
+ return new Vector3(x, s.cy, s.cx);
465
+ };
466
+ return new LoftSurface(evaluate, centre, [keys[0], keys[keys.length - 1]]);
467
+ }
468
+
469
+ point(along: number, theta: number): Vector3 {
470
+ return this.evaluate(along, theta);
471
+ }
472
+
473
+ /** Outward-facing frame; local X follows the sweep, local +Z is the normal. */
474
+ frame(along: number, theta: number): SurfaceFrame {
475
+ const [lo, hi] = this.range;
476
+ const step = Math.max(1e-4, (hi - lo) * 1e-3);
477
+ const forward = Math.min(hi, along + step);
478
+ const back = Math.max(lo, along - step);
479
+ const point = this.evaluate(along, theta);
480
+ const sweep = this.evaluate(forward, theta)
481
+ .sub(this.evaluate(back, theta))
482
+ .normalize();
483
+ const around = this.evaluate(along, theta + 1e-3).sub(point);
484
+ let normal = around.clone().cross(sweep);
485
+ if (normal.lengthSq() < 1e-14) {
486
+ normal = point.clone().sub(this.centre(along));
487
+ }
488
+ normal.normalize();
489
+ if (normal.dot(point.clone().sub(this.centre(along))) < 0) {normal.negate();}
490
+ return surfaceFrame(point, normal, sweep);
491
+ }
492
+
493
+ /**
494
+ * Find the surface frame whose normal most closely faces `outwardDirection`.
495
+ * This lets callers ask for an outboard, upward, or downward attachment point
496
+ * without rediscovering the loft's angular convention.
497
+ */
498
+ frameToward(
499
+ along: number,
500
+ outwardDirection: Vector3,
501
+ samples = 72,
502
+ ): SurfaceFrame {
503
+ const wanted = outwardDirection.clone();
504
+ if (wanted.lengthSq() < 1e-12) {
505
+ return this.frame(along, 0);
506
+ }
507
+ wanted.normalize();
508
+ const count = Math.max(8, Math.floor(samples));
509
+ let best = this.frame(along, 0);
510
+ let bestScore = best.normal.dot(wanted);
511
+ for (let i = 1; i < count; i += 1) {
512
+ const candidate = this.frame(along, (i / count) * Math.PI * 2);
513
+ const score = candidate.normal.dot(wanted);
514
+ if (score > bestScore) {
515
+ best = candidate;
516
+ bestScore = score;
517
+ }
518
+ }
519
+ return best;
520
+ }
521
+
522
+ ring(along: number, segments: number): Vector3[] {
523
+ const points: Vector3[] = [];
524
+ for (let i = 0; i < segments; i += 1) {
525
+ points.push(this.evaluate(along, (i / segments) * Math.PI * 2));
526
+ }
527
+ return points;
528
+ }
529
+
530
+ /**
531
+ * Tessellate into a closed, watertight loft. End caps get their own vertices
532
+ * so the cap-to-body transition stays crisp instead of smearing.
533
+ */
534
+ build(
535
+ alongs: number[],
536
+ segments = 32,
537
+ caps: boolean | { start?: boolean; end?: boolean } = {
538
+ start: true,
539
+ end: true,
540
+ },
541
+ ): BufferGeometry {
542
+ const resolvedCaps = typeof caps === 'boolean' ? { start: caps, end: caps } : caps;
543
+ const rings = alongs.map((a) => this.ring(a, segments));
544
+ const positions: number[] = [];
545
+ const indices: number[] = [];
546
+
547
+ for (const ring of rings) {
548
+ for (const p of ring) {positions.push(p.x, p.y, p.z);}
549
+ }
550
+ for (let r = 0; r < rings.length - 1; r += 1) {
551
+ const base = r * segments;
552
+ const next = (r + 1) * segments;
553
+ for (let j = 0; j < segments; j += 1) {
554
+ const j2 = (j + 1) % segments;
555
+ indices.push(base + j, base + j2, next + j);
556
+ indices.push(base + j2, next + j2, next + j);
557
+ }
558
+ }
559
+
560
+ const addCap = (ringIndex: number, along: number, reverse: boolean) => {
561
+ const ring = rings[ringIndex];
562
+ const centre = this.centre(along);
563
+ const centreIndex = positions.length / 3;
564
+ positions.push(centre.x, centre.y, centre.z);
565
+ const first = positions.length / 3;
566
+ for (const p of ring) {positions.push(p.x, p.y, p.z);}
567
+ for (let j = 0; j < segments; j += 1) {
568
+ const a = first + j;
569
+ const b = first + ((j + 1) % segments);
570
+ if (reverse) {indices.push(centreIndex, b, a);}
571
+ else {indices.push(centreIndex, a, b);}
572
+ }
573
+ };
574
+ if (resolvedCaps.start !== false) {addCap(0, alongs[0], true);}
575
+ if (resolvedCaps.end !== false) {
576
+ addCap(rings.length - 1, alongs[alongs.length - 1], false);
577
+ }
578
+
579
+ const geometry = new BufferGeometry();
580
+ geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
581
+ geometry.setIndex(indices);
582
+ geometry.computeVertexNormals();
583
+ return ensureOutwardWinding(geometry);
584
+ }
585
+ }
586
+
587
+ /** Even sample positions across a loft's sweep range, inclusive of both ends. */
588
+ export function sampleRange(
589
+ from: number,
590
+ to: number,
591
+ count: number,
592
+ ): number[] {
593
+ if (count <= 1) {return [from];}
594
+ const out: number[] = [];
595
+ for (let i = 0; i < count; i += 1) {
596
+ out.push(from + ((to - from) * i) / (count - 1));
597
+ }
598
+ return out;
599
+ }