oda-engine 0.0.0-stage → 0.1.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 (204) hide show
  1. package/README.md +151 -2
  2. package/bin/nowhere.mjs +352 -0
  3. package/lib/account.mjs +57 -0
  4. package/lib/agentModules.mjs +57 -0
  5. package/lib/devServer.mjs +351 -0
  6. package/lib/headless.mjs +231 -0
  7. package/lib/headlessPreview.mjs +212 -0
  8. package/lib/keys.mjs +517 -0
  9. package/lib/make.mjs +855 -0
  10. package/lib/mcp.mjs +537 -0
  11. package/lib/open.mjs +22 -0
  12. package/lib/preview.mjs +87 -0
  13. package/lib/previewRpc.mjs +134 -0
  14. package/lib/project.mjs +359 -0
  15. package/lib/publishFlow.mjs +131 -0
  16. package/lib/resources.mjs +50 -0
  17. package/lib/rules.mjs +60 -0
  18. package/lib/scaffold.mjs +42 -0
  19. package/lib/setup.mjs +59 -0
  20. package/lib/tools.mjs +668 -0
  21. package/package.json +51 -4
  22. package/template/game.config.json +9 -0
  23. package/template/scene.json +4 -0
  24. package/template/src/main.ts +11 -0
  25. package/vendor/DOCS.md +447 -0
  26. package/vendor/agent/appRun.mjs +520 -0
  27. package/vendor/agent/assets/brief.mjs +242 -0
  28. package/vendor/agent/assets/collider.mjs +531 -0
  29. package/vendor/agent/assets/environments/index.mjs +12 -0
  30. package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
  31. package/vendor/agent/assets/fetch.mjs +168 -0
  32. package/vendor/agent/assets/footprint.mjs +13 -0
  33. package/vendor/agent/assets/gltf.mjs +547 -0
  34. package/vendor/agent/assets/hdr.mjs +269 -0
  35. package/vendor/agent/assets/imageOps.mjs +171 -0
  36. package/vendor/agent/assets/images/codex.mjs +307 -0
  37. package/vendor/agent/assets/images/fal.mjs +75 -0
  38. package/vendor/agent/assets/images/gemini.mjs +84 -0
  39. package/vendor/agent/assets/images/index.mjs +25 -0
  40. package/vendor/agent/assets/images/openai.mjs +75 -0
  41. package/vendor/agent/assets/images/stability.mjs +71 -0
  42. package/vendor/agent/assets/images/views.mjs +31 -0
  43. package/vendor/agent/assets/import.mjs +1352 -0
  44. package/vendor/agent/assets/inspect.mjs +465 -0
  45. package/vendor/agent/assets/jobs.mjs +196 -0
  46. package/vendor/agent/assets/ktx2.mjs +290 -0
  47. package/vendor/agent/assets/ledger.mjs +466 -0
  48. package/vendor/agent/assets/net.mjs +254 -0
  49. package/vendor/agent/assets/prices.json +39 -0
  50. package/vendor/agent/assets/providers/fal.mjs +115 -0
  51. package/vendor/agent/assets/providers/index.mjs +22 -0
  52. package/vendor/agent/assets/providers/meshy.mjs +119 -0
  53. package/vendor/agent/assets/providers/tripo.mjs +188 -0
  54. package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
  55. package/vendor/agent/assets/sources/index.mjs +23 -0
  56. package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
  57. package/vendor/agent/assets/sources/polypizza.mjs +121 -0
  58. package/vendor/agent/assets/splat.mjs +631 -0
  59. package/vendor/agent/assets/targets.mjs +122 -0
  60. package/vendor/agent/assets/tile.mjs +261 -0
  61. package/vendor/agent/assets/unzip.mjs +180 -0
  62. package/vendor/agent/blender/cleanup.py +360 -0
  63. package/vendor/agent/blender/convert.py +167 -0
  64. package/vendor/agent/blender/find.mjs +192 -0
  65. package/vendor/agent/blender/nw_export.py +104 -0
  66. package/vendor/agent/blender/nw_rubric.py +426 -0
  67. package/vendor/agent/blender/run.mjs +193 -0
  68. package/vendor/agent/blender/runner.py +252 -0
  69. package/vendor/agent/blender/sheet.py +743 -0
  70. package/vendor/agent/depth.mjs +134 -0
  71. package/vendor/agent/director/board.mjs +451 -0
  72. package/vendor/agent/director/contracts.mjs +663 -0
  73. package/vendor/agent/director/director.mjs +2365 -0
  74. package/vendor/agent/director/estimate.mjs +200 -0
  75. package/vendor/agent/director/gate.mjs +802 -0
  76. package/vendor/agent/director/limits.json +16 -0
  77. package/vendor/agent/director/methods.mjs +457 -0
  78. package/vendor/agent/director/policy.json +33 -0
  79. package/vendor/agent/director/prompts.mjs +244 -0
  80. package/vendor/agent/director/reading.mjs +341 -0
  81. package/vendor/agent/director/router.mjs +184 -0
  82. package/vendor/agent/director/seams.mjs +243 -0
  83. package/vendor/agent/director/session.mjs +643 -0
  84. package/vendor/agent/director/store.mjs +119 -0
  85. package/vendor/agent/director/taskGate.mjs +110 -0
  86. package/vendor/agent/director/teamLedger.mjs +118 -0
  87. package/vendor/agent/director/triage.mjs +63 -0
  88. package/vendor/agent/downloads.cjs +363 -0
  89. package/vendor/agent/flow.mjs +78 -0
  90. package/vendor/agent/guard.mjs +613 -0
  91. package/vendor/agent/host.mjs +1736 -0
  92. package/vendor/agent/language.mjs +58 -0
  93. package/vendor/agent/ledger.mjs +360 -0
  94. package/vendor/agent/locale.cjs +186 -0
  95. package/vendor/agent/loop/capacity.mjs +74 -0
  96. package/vendor/agent/loop/compose.mjs +127 -0
  97. package/vendor/agent/loop/gate.mjs +205 -0
  98. package/vendor/agent/loop/judge.mjs +189 -0
  99. package/vendor/agent/loop/levels.mjs +273 -0
  100. package/vendor/agent/loop/state.mjs +358 -0
  101. package/vendor/agent/notes.cjs +278 -0
  102. package/vendor/agent/pace.mjs +258 -0
  103. package/vendor/agent/panels.mjs +431 -0
  104. package/vendor/agent/prompt.mjs +342 -0
  105. package/vendor/agent/reference/board.mjs +410 -0
  106. package/vendor/agent/reference/compose.mjs +364 -0
  107. package/vendor/agent/reference/decode.mjs +56 -0
  108. package/vendor/agent/reference/facts.mjs +1874 -0
  109. package/vendor/agent/reference/png.mjs +107 -0
  110. package/vendor/agent/reference/records.mjs +63 -0
  111. package/vendor/agent/reference/web.mjs +252 -0
  112. package/vendor/agent/roles/artist.mjs +69 -0
  113. package/vendor/agent/roles/builder.mjs +79 -0
  114. package/vendor/agent/roles/checks.mjs +223 -0
  115. package/vendor/agent/roles/common.mjs +188 -0
  116. package/vendor/agent/roles/critic.mjs +171 -0
  117. package/vendor/agent/roles/index.mjs +39 -0
  118. package/vendor/agent/roles/modeller.mjs +142 -0
  119. package/vendor/agent/roles/qa.mjs +58 -0
  120. package/vendor/agent/roles/rubrics.mjs +79 -0
  121. package/vendor/agent/roles/sound.mjs +69 -0
  122. package/vendor/agent/rounds.cjs +333 -0
  123. package/vendor/agent/shared.mjs +284 -0
  124. package/vendor/agent/stopGate.mjs +574 -0
  125. package/vendor/agent/subagents.mjs +129 -0
  126. package/vendor/agent/tools/assets.mjs +499 -0
  127. package/vendor/agent/tools/blender.mjs +754 -0
  128. package/vendor/agent/tools/cards.mjs +479 -0
  129. package/vendor/agent/tools/choices.mjs +479 -0
  130. package/vendor/agent/tools/compose.mjs +74 -0
  131. package/vendor/agent/tools/environment.mjs +488 -0
  132. package/vendor/agent/tools/eyes.mjs +733 -0
  133. package/vendor/agent/tools/generate.mjs +338 -0
  134. package/vendor/agent/tools/guide.mjs +46 -0
  135. package/vendor/agent/tools/harness.mjs +193 -0
  136. package/vendor/agent/tools/image.mjs +643 -0
  137. package/vendor/agent/tools/index.mjs +162 -0
  138. package/vendor/agent/tools/look.mjs +578 -0
  139. package/vendor/agent/tools/loop.mjs +858 -0
  140. package/vendor/agent/tools/others.mjs +123 -0
  141. package/vendor/agent/tools/pictures.mjs +535 -0
  142. package/vendor/agent/tools/reference.mjs +366 -0
  143. package/vendor/agent/transcripts.mjs +118 -0
  144. package/vendor/agent-loop.mjs +602 -0
  145. package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
  146. package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
  147. package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
  148. package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
  149. package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
  150. package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
  151. package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
  152. package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
  153. package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
  154. package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
  155. package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
  156. package/vendor/auth.cjs +570 -0
  157. package/vendor/build.cjs +953 -0
  158. package/vendor/catalog.json +455 -0
  159. package/vendor/connectors.cjs +688 -0
  160. package/vendor/eyes.mjs +733 -0
  161. package/vendor/gameExports.json +1390 -0
  162. package/vendor/git.cjs +222 -0
  163. package/vendor/models.json +57 -0
  164. package/vendor/publish.cjs +1018 -0
  165. package/vendor/refBoard.cjs +301 -0
  166. package/vendor/schema/dist/assets.d.ts +335 -0
  167. package/vendor/schema/dist/assets.js +439 -0
  168. package/vendor/schema/dist/brief.d.ts +357 -0
  169. package/vendor/schema/dist/brief.js +302 -0
  170. package/vendor/schema/dist/common.d.ts +9 -0
  171. package/vendor/schema/dist/common.js +13 -0
  172. package/vendor/schema/dist/config.d.ts +406 -0
  173. package/vendor/schema/dist/config.js +355 -0
  174. package/vendor/schema/dist/contract.d.ts +599 -0
  175. package/vendor/schema/dist/contract.js +1146 -0
  176. package/vendor/schema/dist/index.d.ts +14 -0
  177. package/vendor/schema/dist/index.js +21 -0
  178. package/vendor/schema/dist/look.d.ts +463 -0
  179. package/vendor/schema/dist/look.js +681 -0
  180. package/vendor/schema/dist/lookStats.d.ts +230 -0
  181. package/vendor/schema/dist/lookStats.js +768 -0
  182. package/vendor/schema/dist/pilot.d.ts +32 -0
  183. package/vendor/schema/dist/pilot.js +44 -0
  184. package/vendor/schema/dist/publish.d.ts +214 -0
  185. package/vendor/schema/dist/publish.js +291 -0
  186. package/vendor/schema/dist/scene.d.ts +75 -0
  187. package/vendor/schema/dist/scene.js +120 -0
  188. package/vendor/schema/dist/skyLight.d.ts +141 -0
  189. package/vendor/schema/dist/skyLight.js +436 -0
  190. package/vendor/schema/dist/style.d.ts +131 -0
  191. package/vendor/schema/dist/style.js +155 -0
  192. package/vendor/schema/package.json +1 -0
  193. package/vendor/selectionPrompt.mjs +51 -0
  194. package/vendor/useTools.mjs +195 -0
  195. package/vendor/userMessage.mjs +26 -0
  196. package/web-dist/assets/GaussianSplatUtils-CptQkDVX.js +1 -0
  197. package/web-dist/assets/KTX2Loader-C53LJqss.js +2 -0
  198. package/web-dist/assets/SPZLoader-BQ3tjaTv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-_9tcWegB.js +1 -0
  200. package/web-dist/assets/index-Baka-ZO7.js +693 -0
  201. package/web-dist/assets/index-CcjyyQco.css +1 -0
  202. package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
  203. package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
  204. package/web-dist/index.html +34 -0
@@ -0,0 +1,465 @@
1
+ // asset_inspect: what an asset is made of and whether it is good enough for
2
+ // this space, in numbers, held to the space's brief. asset_import runs the
3
+ // same inspection on what it writes and puts the report in its answer.
4
+ //
5
+ // material which maps it has (colour, normal, rough, ao, metal,
6
+ // displacement, opacity) and which it lacks, their sizes, the
7
+ // texel density at its real size (pixels per metre of surface,
8
+ // from how much one tile covers), and the 2 x 2 seam score
9
+ // model its triangles and size, every material's maps, the texel
10
+ // density its UVs give at its real size, and whether its colour
11
+ // map looks to carry baked shadow (when an occlusion map is
12
+ // there to compare with)
13
+ // texture one picture: its size, alpha, values and seam score
14
+ //
15
+ // The density is compared with the brief's target for that surface
16
+ // (materials[].texelDensity, else budget.texelDensity): under half of it
17
+ // asset_import refuses, under four fifths or over two and a half times it
18
+ // says so. Without a brief, or a target in it, the number is given alone.
19
+ // Every texture's GPU memory is given as it is (RGBA8 with mipmaps) and as
20
+ // KTX2 would make it; with ktx2 asked for, each is encoded and measured.
21
+
22
+ import fs from 'node:fs'
23
+ import fsp from 'node:fs/promises'
24
+ import path from 'node:path'
25
+ import { briefDensityFor } from '../../schema/dist/index.js'
26
+ import { decodeImage } from '../reference/decode.mjs'
27
+ import { fitEdge } from '../reference/facts.mjs'
28
+ import { encodePng } from '../reference/png.mjs'
29
+ import { readBrief } from './brief.mjs'
30
+ import { boundsOf, countTriangles, textureRoles } from './gltf.mjs'
31
+ import { imageSize } from './imageOps.mjs'
32
+ import { decodeKtx2, describe, flipRows, gpuBytes, ktx2For, ktx2Header, mayBeEtc1s } from './ktx2.mjs'
33
+ import { pictureStats, seamScore, tile2x2 } from './tile.mjs'
34
+
35
+ /** The maps a material may have, in the names asset_import gives them. */
36
+ export const MAP_ROLES = ['color', 'normal', 'rough', 'ao', 'metal', 'displacement', 'opacity']
37
+ /** Without these a surface reads flat or plastic in the light. */
38
+ export const NEEDED_MAPS = ['color', 'normal', 'rough']
39
+ const MAP_EXTS = ['.ktx2', '.jpg', '.png']
40
+
41
+ const MB = 1024 * 1024
42
+ const round = (v, d = 1) => Math.round(v * 10 ** d) / 10 ** d
43
+ const mb = (b) => (b / MB).toFixed(b < MB ? 2 : 1)
44
+
45
+ /**
46
+ * A texel density against its target: { verdict, ratio, words }. verdict is
47
+ * 'ok', 'low' (under four fifths), 'high' (over two and a half times: memory
48
+ * spent on what nobody comes close enough to see), 'refuse' (under half) or
49
+ * 'none' (nothing to compare with).
50
+ */
51
+ export function densityVerdict(measured, target) {
52
+ if (!target) return { verdict: 'none', ratio: null, words: `${Math.round(measured)} px/m (the brief sets no target for it)` }
53
+ const ratio = measured / target.target
54
+ const at = `${Math.round(measured)} px/m against ${Math.round(target.target)} px/m from ${target.from}`
55
+ if (ratio < 0.5) return { verdict: 'refuse', ratio: round(ratio, 2), words: `${at}: under half of it, so it would read blurred where the brief has the visitor stand` }
56
+ if (ratio < 0.8) return { verdict: 'low', ratio: round(ratio, 2), words: `${at}: ${Math.round(ratio * 100)}% of it, softer than the brief asks` }
57
+ if (ratio > 2.5) return { verdict: 'high', ratio: round(ratio, 2), words: `${at}: ${round(ratio, 1)} times it, memory nobody comes close enough to see (a smaller maxTexture keeps the target)` }
58
+ return { verdict: 'ok', ratio: round(ratio, 2), words: `${at}: on target` }
59
+ }
60
+
61
+ /** The brief, when the project has one that passes its schema. */
62
+ async function briefOf(projectRoot, given) {
63
+ if (given !== undefined) return given
64
+ const r = await readBrief(projectRoot)
65
+ return r.status === 'ok' ? r.brief : null
66
+ }
67
+
68
+ /** A texture's size from its bytes: a PNG, JPEG or WebP header, or a KTX2's
69
+ * ({ width, height, format, mode }), or null. */
70
+ export function textureSize(bytes) {
71
+ const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? [])
72
+ const size = imageSize(buf)
73
+ if (size) return size
74
+ const head = ktx2Header(buf)
75
+ return head ? { width: head.width, height: head.height, format: 'ktx2', mode: head.mode } : null
76
+ }
77
+
78
+ /** A texture's pixels, whatever it is stored as: a KTX2 is transcoded back. */
79
+ export async function texturePixels(bytes, { mime, maxEdge = 1024, rpc = null } = {}) {
80
+ const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? [])
81
+ if (mime === 'image/ktx2' || ktx2Header(buf)) {
82
+ try {
83
+ const back = await decodeKtx2(buf)
84
+ return { ok: true, ...fitEdge(back, maxEdge) }
85
+ } catch (err) {
86
+ return { ok: false, error: `the KTX2 could not be read back: ${err?.message ?? err}` }
87
+ }
88
+ }
89
+ return decodeImage(buf, { mime: mime ?? (imageSize(buf)?.format === 'jpg' ? 'image/jpeg' : 'image/png'), maxEdge, rpc })
90
+ }
91
+
92
+ /** The codec the arithmetic assumes for a role: ETC1S's range where the
93
+ * role may take it, UASTC where it may not. */
94
+ const estimateMode = (role) => (mayBeEtc1s(role) ? 'etc1s' : 'uastc')
95
+
96
+ /** A picture file's measurements. seam: also the seam score and the 2 x 2
97
+ * sheet (not for a picture with transparency: that is a card, not a tile).
98
+ * A KTX2 is read from its header, and transcoded back for the seam. */
99
+ export async function inspectPicture(abs, { role = 'color', seam = false, ktx2 = false, rpc = null } = {}) {
100
+ const buf = await fsp.readFile(abs)
101
+ const size = textureSize(buf)
102
+ const out = { file: abs, bytes: buf.length, width: size?.width ?? null, height: size?.height ?? null, format: size?.format ?? path.extname(abs).slice(1), role }
103
+ const written = size?.format === 'ktx2'
104
+ if (written) Object.assign(out, { gpu: { rgba8: null, ktx2: gpuBytes(size.width, size.height, size.mode) }, ktx2File: size.mode })
105
+ else out.gpu = size ? { rgba8: gpuBytes(size.width, size.height).rgba8, ktx2: gpuBytes(size.width, size.height, estimateMode(role)) } : null
106
+ if (!seam && !(ktx2 && !written)) return out
107
+ const read = await texturePixels(buf, { mime: written ? 'image/ktx2' : undefined, maxEdge: ktx2 && !written ? 4096 : 1024, rpc })
108
+ if (!read.ok) return { ...out, problem: read.error }
109
+ // A .ktx2 on its own is stored bottom row first (ktx2.mjs), so it is
110
+ // turned the right way up to be looked at.
111
+ const pic = written ? { ok: true, ...flipRows(read) } : read
112
+ const stats = pictureStats(pic)
113
+ out.stats = stats
114
+ if (seam && stats.alpha < 0.01) {
115
+ // A panorama wraps only left to right: its top is the sky straight up.
116
+ out.seam = seamScore(pic, { axes: role === 'panorama' ? 'x' : 'xy' })
117
+ out.sheet = encodePng(tile2x2(pic, 512)).toString('base64')
118
+ }
119
+ if (ktx2 && !written) {
120
+ const k = await ktx2For(pic, { role, alpha: stats.alpha >= 0.01 })
121
+ out.ktx2 = k.ok ? { mode: k.mode, bytes: k.bytes.byteLength, gpu: k.gpu, measured: k.measured, why: k.why, ms: k.ms } : { error: k.error }
122
+ }
123
+ return out
124
+ }
125
+
126
+ /** The maps of a material in assets/: { role: abs } for <stem>_<role>.<ext>. */
127
+ export function materialMaps(projectRoot, stem) {
128
+ const maps = {}
129
+ for (const role of MAP_ROLES) {
130
+ for (const ext of MAP_EXTS) {
131
+ const abs = path.join(projectRoot, 'assets', `${stem}_${role}${ext}`)
132
+ if (fs.existsSync(abs)) {
133
+ maps[role] = abs
134
+ break
135
+ }
136
+ }
137
+ }
138
+ return maps
139
+ }
140
+
141
+ /** Every map file a material name holds in assets/, in any format, as
142
+ * project paths: one name is one set of maps, so asset_import counts all of
143
+ * them as taken, and a replace removes what the new set does not write. */
144
+ export function materialFiles(projectRoot, stem) {
145
+ const out = []
146
+ for (const role of MAP_ROLES) for (const ext of MAP_EXTS) if (fs.existsSync(path.join(projectRoot, 'assets', `${stem}_${role}${ext}`))) out.push(`assets/${stem}_${role}${ext}`)
147
+ return out
148
+ }
149
+
150
+ /**
151
+ * A material's report. tileMetres: what one tile covers (asset_import's
152
+ * size, else the ledger's, else the brief's). files: { role: abs } of the
153
+ * maps to read (asset_import's, the ones it has just written), else what
154
+ * assets/ holds under the name. ledger: assets.lock.json's files, for what
155
+ * was measured at import, matched by each map's own path. Answers { kind:
156
+ * 'material', stem, maps, missing, density, seam, sheet, ... } or { error }.
157
+ */
158
+ export async function inspectMaterial(projectRoot, stem, { tileMetres = null, brief, ktx2 = false, rpc = null, files = null, ledger = null } = {}) {
159
+ const maps = files ?? materialMaps(projectRoot, stem)
160
+ if (!Object.keys(maps).length) return { error: `assets/${stem} has no maps (no assets/${stem}_color.jpg, _normal, ...).` }
161
+ const entryOf = (abs) => ledger?.[path.relative(projectRoot, abs).split(path.sep).join('/')] ?? null
162
+ const ledgerMeta = maps.color ? entryOf(maps.color)?.meta : null
163
+ const b = await briefOf(projectRoot, brief)
164
+ const target = briefDensityFor(b, `assets/${stem}`)
165
+ const fromBrief = b?.materials.find((m) => m.name === stem)?.tileMetres ?? null
166
+ const tile = tileMetres ?? ledgerMeta?.tile_m ?? fromBrief
167
+ const pictures = {}
168
+ for (const [role, abs] of Object.entries(maps)) {
169
+ pictures[role] = await inspectPicture(abs, { role: role === 'color' ? 'color' : role, seam: role === 'color', ktx2, rpc })
170
+ // What the import measured for this very file, when it is not measured again now.
171
+ const recorded = !ktx2 ? entryOf(abs)?.meta?.ktx2 : null
172
+ if (recorded?.mode && !recorded.written) pictures[role].ktx2Recorded = recorded
173
+ }
174
+ const color = pictures.color
175
+ const missing = NEEDED_MAPS.filter((r) => !maps[r])
176
+ const density = tile && color?.width ? densityVerdict(color.width / (Array.isArray(tile) ? tile[0] : tile), target) : null
177
+ return {
178
+ kind: 'material',
179
+ stem,
180
+ maps: pictures,
181
+ missing,
182
+ tileMetres: tile,
183
+ density,
184
+ target,
185
+ seam: color?.seam ?? null,
186
+ sheet: color?.sheet ?? null,
187
+ brief: b ? 'ok' : 'none',
188
+ }
189
+ }
190
+
191
+ // ---------------------------------------------------------------- models
192
+
193
+ const SLOTS = [
194
+ ['baseColor', (m) => m.getBaseColorTexture(), (m) => m.getBaseColorTextureInfo()],
195
+ ['normal', (m) => m.getNormalTexture(), (m) => m.getNormalTextureInfo()],
196
+ ['metallicRoughness', (m) => m.getMetallicRoughnessTexture(), (m) => m.getMetallicRoughnessTextureInfo()],
197
+ ['occlusion', (m) => m.getOcclusionTexture(), (m) => m.getOcclusionTextureInfo()],
198
+ ['emissive', (m) => m.getEmissiveTexture(), (m) => m.getEmissiveTextureInfo()],
199
+ ]
200
+ const MODEL_NEEDED = ['baseColor', 'normal', 'metallicRoughness']
201
+
202
+ const transform = (m, p) => [m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12], m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13], m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14]]
203
+ const triArea3 = (a, b, c) => {
204
+ const u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]]
205
+ const v = [c[0] - a[0], c[1] - a[1], c[2] - a[2]]
206
+ return 0.5 * Math.hypot(u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0])
207
+ }
208
+ const triArea2 = (a, b, c) => 0.5 * Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]))
209
+
210
+ /** Per material, the surface its triangles cover in metres and in its colour
211
+ * map's pixels, from the default scene as drawn (every node's transform). */
212
+ function uvCoverage(doc) {
213
+ const root = doc.getRoot()
214
+ const scene = root.getDefaultScene() ?? root.listScenes()[0]
215
+ const byMaterial = new Map()
216
+ if (!scene) return byMaterial
217
+ scene.traverse((node) => {
218
+ const mesh = node.getMesh()
219
+ if (!mesh) return
220
+ const world = node.getWorldMatrix()
221
+ for (const prim of mesh.listPrimitives()) {
222
+ if (prim.getMode() !== 4) continue
223
+ const mat = prim.getMaterial()
224
+ const tex = mat?.getBaseColorTexture()
225
+ const size = tex ? textureSize(tex.getImage()) : null
226
+ const uvSet = mat?.getBaseColorTextureInfo()?.getTexCoord() ?? 0
227
+ const pos = prim.getAttribute('POSITION')
228
+ const uv = prim.getAttribute(`TEXCOORD_${uvSet}`)
229
+ if (!pos || !uv || !size) continue
230
+ const idx = prim.getIndices()
231
+ const count = idx ? idx.getCount() : pos.getCount()
232
+ const at = (k) => (idx ? idx.getScalar(k) : k)
233
+ let metres = 0
234
+ let pixels = 0
235
+ const p = [[], [], []]
236
+ const t = [[], [], []]
237
+ for (let k = 0; k + 2 < count; k += 3) {
238
+ for (let j = 0; j < 3; j++) {
239
+ p[j] = transform(world, pos.getElement(at(k + j), []))
240
+ t[j] = uv.getElement(at(k + j), [])
241
+ }
242
+ metres += triArea3(p[0], p[1], p[2])
243
+ pixels += triArea2(t[0], t[1], t[2]) * size.width * size.height
244
+ }
245
+ const key = mat ?? 'none'
246
+ const had = byMaterial.get(key) ?? { metres: 0, pixels: 0 }
247
+ byMaterial.set(key, { metres: had.metres + metres, pixels: had.pixels + pixels })
248
+ }
249
+ })
250
+ return byMaterial
251
+ }
252
+
253
+ /** Whether the colour map looks to carry the occlusion map's shading: the
254
+ * correlation of the two (occlusion's red channel), sampled the same way.
255
+ * Null without both, or when they do not decode. */
256
+ async function bakedShadow(material, rpc) {
257
+ const color = material.getBaseColorTexture()
258
+ const occ = material.getOcclusionTexture()
259
+ if (!color || !occ) return null
260
+ const [a, b] = await Promise.all([color, occ].map((t) => texturePixels(t.getImage(), { mime: t.getMimeType(), maxEdge: 256, rpc })))
261
+ if (!a.ok || !b.ok || a.width !== b.width || a.height !== b.height) return null
262
+ let sa = 0
263
+ let sb = 0
264
+ let sab = 0
265
+ let saa = 0
266
+ let sbb = 0
267
+ const n = a.width * a.height
268
+ for (let i = 0; i < n * 4; i += 4) {
269
+ const la = 0.2126 * a.data[i] + 0.7152 * a.data[i + 1] + 0.0722 * a.data[i + 2]
270
+ const lb = b.data[i]
271
+ sa += la
272
+ sb += lb
273
+ sab += la * lb
274
+ saa += la * la
275
+ sbb += lb * lb
276
+ }
277
+ const cov = sab / n - (sa / n) * (sb / n)
278
+ const va = saa / n - (sa / n) ** 2
279
+ const vb = sbb / n - (sb / n) ** 2
280
+ if (va <= 0 || vb <= 0) return null
281
+ return round(cov / Math.sqrt(va * vb), 2)
282
+ }
283
+
284
+ /**
285
+ * A model's report from its Document (asset_import's, before it is written;
286
+ * asset_inspect's, read from assets/). file: its path, for the brief's
287
+ * target. recorded: the ledger's meta.ktx2 for it ({ texture name: { mode,
288
+ * bytes } }), what its import measured. Answers { kind: 'model', triangles,
289
+ * size, materials, density, ... }.
290
+ */
291
+ export async function inspectModelDoc(doc, { file, projectRoot, brief, ktx2 = false, rpc = null, recorded = null } = {}) {
292
+ const b = projectRoot ? await briefOf(projectRoot, brief) : (brief ?? null)
293
+ const target = briefDensityFor(b, file)
294
+ const root = doc.getRoot()
295
+ const bounds = boundsOf(doc)
296
+ const coverage = uvCoverage(doc)
297
+ const roleOfTexture = textureRoles(doc)
298
+ const materials = []
299
+ let metres = 0
300
+ let pixels = 0
301
+ for (const m of root.listMaterials()) {
302
+ const maps = {}
303
+ for (const [slot, get] of SLOTS) {
304
+ const t = get(m)
305
+ if (!t) continue
306
+ const s = textureSize(t.getImage())
307
+ maps[slot] = { width: s?.width ?? null, height: s?.height ?? null, mime: t.getMimeType() }
308
+ }
309
+ const cov = coverage.get(m)
310
+ const density = cov && cov.metres > 0 ? Math.sqrt(cov.pixels / cov.metres) : null
311
+ if (cov) {
312
+ metres += cov.metres
313
+ pixels += cov.pixels
314
+ }
315
+ materials.push({
316
+ name: m.getName() || 'unnamed',
317
+ maps,
318
+ missing: MODEL_NEEDED.filter((s) => !maps[s]),
319
+ density: density ? Math.round(density) : null,
320
+ surfaceM2: cov ? round(cov.metres, 2) : null,
321
+ bakedShadow: await bakedShadow(m, rpc).catch(() => null),
322
+ })
323
+ }
324
+ const overall = metres > 0 ? Math.sqrt(pixels / metres) : null
325
+ const textures = []
326
+ let gpuNow = 0
327
+ let gpuLow = 0
328
+ let gpuHigh = 0
329
+ let bytesNow = 0
330
+ let bytesKtx2 = 0
331
+ let ktx2Counted = 0
332
+ for (const t of root.listTextures()) {
333
+ const s = textureSize(t.getImage())
334
+ if (!s) continue
335
+ const role = roleOfTexture(t)
336
+ const entry = { name: t.getName() || t.getURI() || 'texture', width: s.width, height: s.height, role, bytes: t.getImage()?.byteLength ?? 0 }
337
+ // Written as KTX2, it is what its header says; measured at import, what
338
+ // was measured; else the range its role allows.
339
+ const known = s.mode ?? recorded?.[entry.name]?.mode ?? null
340
+ const est = gpuBytes(s.width, s.height, known ?? estimateMode(role))
341
+ gpuNow += s.mode ? est.high : est.rgba8
342
+ bytesNow += entry.bytes
343
+ if (s.mode) {
344
+ entry.ktx2File = s.mode
345
+ gpuLow += est.low
346
+ gpuHigh += est.high
347
+ } else if (ktx2) {
348
+ const pic = await decodeImage(Buffer.from(t.getImage()), { mime: t.getMimeType(), maxEdge: 4096, rpc })
349
+ const k = pic.ok ? await ktx2For(pic, { role, alpha: false }) : { ok: false, error: pic.error }
350
+ entry.ktx2 = k.ok ? { mode: k.mode, bytes: k.bytes.byteLength, measured: k.measured, why: k.why } : { error: k.error }
351
+ if (k.ok) {
352
+ gpuLow += k.gpu.low
353
+ gpuHigh += k.gpu.high
354
+ bytesKtx2 += k.bytes.byteLength
355
+ ktx2Counted++
356
+ }
357
+ } else {
358
+ if (recorded?.[entry.name]?.bytes) {
359
+ bytesKtx2 += recorded[entry.name].bytes
360
+ ktx2Counted++
361
+ }
362
+ gpuLow += est.low
363
+ gpuHigh += est.high
364
+ }
365
+ textures.push(entry)
366
+ }
367
+ const written = textures.length > 0 && textures.every((t) => t.ktx2File)
368
+ return {
369
+ kind: 'model',
370
+ file,
371
+ triangles: countTriangles(doc),
372
+ size: bounds ? bounds.size.map((v) => round(v, 3)) : null,
373
+ materials,
374
+ textures,
375
+ untextured: materials.filter((m) => !m.maps.baseColor).map((m) => m.name),
376
+ density: overall ? densityVerdict(overall, target) : null,
377
+ densityPx: overall ? Math.round(overall) : null,
378
+ target,
379
+ gpu: { rgba8: gpuNow, ktx2Low: gpuLow, ktx2High: gpuHigh, measured: ktx2, recorded: !ktx2 && ktx2Counted > 0, written },
380
+ // Texture bytes in the file, and as KTX2 where every texture was measured.
381
+ bytes: { textures: bytesNow, ktx2: ktx2Counted === textures.length && textures.length && !written ? bytesKtx2 : null },
382
+ brief: b ? 'ok' : 'none',
383
+ }
384
+ }
385
+
386
+ // ---------------------------------------------------------------- words
387
+
388
+ const sizeOf = (p) => (p?.width ? `${p.width}x${p.height}` : '?')
389
+
390
+ /** What KTX2 does to the bytes a planet downloads, in words. */
391
+ function bytesLine(now, ktx2, what) {
392
+ const change = Math.round(((ktx2 - now) / now) * 100)
393
+ return `download: ${mb(now)} MB ${what}, ${mb(ktx2)} MB as KTX2 (${change > 0 ? `${change}% more` : change < 0 ? `${-change}% less` : 'the same'}): KTX2 trades bytes in the planet's 100 MB for GPU memory`
394
+ }
395
+
396
+ /** A picture's KTX2 GPU range: measured now, else as measured at import,
397
+ * else the arithmetic for its role. */
398
+ const ktx2Range = (p) => p.ktx2?.gpu ?? (p.ktx2Recorded?.mode && p.width ? gpuBytes(p.width, p.height, p.ktx2Recorded.mode) : p.gpu?.ktx2) ?? { low: 0, high: 0 }
399
+
400
+ /** A report as the lines of an answer. */
401
+ export function reportLines(r) {
402
+ const out = []
403
+ if (r.kind === 'material') {
404
+ const have = MAP_ROLES.filter((role) => r.maps[role])
405
+ out.push(`maps: ${have.map((role) => `${role} ${sizeOf(r.maps[role])} ${r.maps[role].format}`).join(', ')}${r.missing.length ? `; missing ${r.missing.join(', ')} (without ${r.missing.length === 1 ? 'it' : 'them'} the surface reads ${r.missing.includes('normal') ? 'flat' : 'plastic'} in the light)` : '; complete'}`)
406
+ if (r.density) out.push(`texel density: ${r.density.words} (one tile covers ${Array.isArray(r.tileMetres) ? r.tileMetres.join(' x ') : r.tileMetres} m)`)
407
+ else out.push(`texel density: unknown, as nothing says how much one tile covers (pass tileSize in metres${r.target ? `; the target is ${Math.round(r.target.target)} px/m from ${r.target.from}` : ''})`)
408
+ if (r.seam) out.push(`2 x 2 tiling: ${r.seam.words}`)
409
+ const pics = Object.values(r.maps)
410
+ const gpu = pics.reduce((a, p) => ({ now: a.now + (p.gpu?.rgba8 ?? 0), low: a.low + ktx2Range(p).low, high: a.high + ktx2Range(p).high }), { now: 0, low: 0, high: 0 })
411
+ const written = Object.entries(r.maps).filter(([, p]) => p.ktx2File)
412
+ const known = pics.every((p) => p.ktx2?.mode || p.ktx2Recorded?.mode)
413
+ if (written.length === pics.length) out.push(`GPU memory: ${mb(gpu.low)} to ${mb(gpu.high)} MB, written as KTX2 (${written.map(([role, p]) => `${role} ${p.ktx2File.toUpperCase()}`).join(', ')})`)
414
+ else out.push(`GPU memory: ${mb(gpu.now)} MB as PNG or JPEG (RGBA8 with mipmaps), ${mb(gpu.low)} to ${mb(gpu.high)} MB as KTX2${known ? (pics.some((p) => p.ktx2?.mode) ? ' (each map encoded and measured)' : ' (each map as measured at import)') : ''}`)
415
+ if (!written.length && known) out.push(bytesLine(pics.reduce((n, p) => n + p.bytes, 0), pics.reduce((n, p) => n + (p.ktx2?.bytes ?? p.ktx2Recorded.bytes), 0), `as ${[...new Set(pics.map((p) => p.format.toUpperCase()))].join(' and ')}`))
416
+ for (const [role, p] of Object.entries(r.maps)) {
417
+ if (p.ktx2?.mode) out.push(`- KTX2 ${role}: ${p.ktx2.mode.toUpperCase()}, ${mb(p.ktx2.bytes)} MB on disk (the ${p.format} is ${mb(p.bytes)} MB); ${p.ktx2.why}`)
418
+ else if (p.ktx2?.error) out.push(`- KTX2 ${role}: not encoded (${p.ktx2.error})`)
419
+ else if (p.ktx2Recorded) out.push(`- KTX2 ${role}, as measured at import: ${p.ktx2Recorded.mode.toUpperCase()}, ${mb(p.ktx2Recorded.bytes)} MB on disk (${describe(p.ktx2Recorded)})`)
420
+ }
421
+ } else if (r.kind === 'model') {
422
+ out.push(`${r.triangles.toLocaleString('en-US')} triangles, ${r.size ? `${r.size.join(' x ')} m (width x height x depth)` : 'size unknown'}`)
423
+ for (const m of r.materials) {
424
+ const maps = Object.entries(m.maps).map(([slot, t]) => `${slot} ${sizeOf(t)}`)
425
+ const bits = [`material ${m.name}: ${maps.length ? maps.join(', ') : 'no textures'}`]
426
+ if (m.missing.length) bits.push(`missing ${m.missing.join(', ')}`)
427
+ if (m.density) bits.push(`${m.density} px/m over ${m.surfaceM2} m2`)
428
+ if (m.bakedShadow !== null && m.bakedShadow !== undefined) bits.push(m.bakedShadow > 0.6 ? `its colour map follows its occlusion map (correlation ${m.bakedShadow}): shadow looks baked into the colour, which lights wrong in this space` : `colour and occlusion maps apart (correlation ${m.bakedShadow}): no sign of baked shadow`)
429
+ out.push(bits.join('; '))
430
+ }
431
+ if (r.materials.length && r.materials.every((m) => m.bakedShadow === null || m.bakedShadow === undefined)) out.push('baked shadow: not measured (no occlusion map beside a colour map to compare it with); look at the contact sheet for dark creases painted into the colour')
432
+ if (r.untextured.length) out.push(`untextured: ${r.untextured.join(', ')} (a flat colour reads as a blockout next to scanned surfaces)`)
433
+ out.push(r.density ? `texel density: ${r.density.words}` : 'texel density: not measured (no UVs or no colour map)')
434
+ if (r.gpu.written) out.push(`GPU memory: ${mb(r.gpu.ktx2Low)} to ${mb(r.gpu.ktx2High)} MB, its textures written as KTX2 (${r.textures.map((t) => `${t.name} ${t.ktx2File.toUpperCase()}`).join(', ')})`)
435
+ else out.push(`GPU memory: ${mb(r.gpu.rgba8)} MB for its textures as they are, ${mb(r.gpu.ktx2Low)} to ${mb(r.gpu.ktx2High)} MB as KTX2${r.gpu.measured ? ' (encoded and measured)' : r.gpu.recorded ? ' (as measured at import)' : ''}`)
436
+ if (r.bytes?.ktx2) out.push(bytesLine(r.bytes.textures, r.bytes.ktx2, 'of textures in the GLB'))
437
+ for (const t of r.textures) {
438
+ if (t.ktx2?.mode) out.push(`- KTX2 ${t.name} (${t.role}): ${t.ktx2.mode.toUpperCase()}, ${mb(t.ktx2.bytes)} MB; ${t.ktx2.why}`)
439
+ else if (t.ktx2?.error) out.push(`- KTX2 ${t.name}: not encoded (${t.ktx2.error})`)
440
+ }
441
+ } else if (r.kind === 'texture') {
442
+ const p = r.picture
443
+ out.push(`${sizeOf(p)} ${p.format}, ${mb(p.bytes)} MB${p.stats ? `, alpha in ${Math.round(p.stats.alpha * 100)}% of it, values ${p.stats.p05} to ${p.stats.p95} (mean ${p.stats.mean}), unevenness ${p.stats.unevenness}` : ''}`)
444
+ if (p.seam) out.push(`2 x 2 tiling: ${p.seam.words}`)
445
+ else if (p.stats?.alpha >= 0.01) out.push('a card (it has transparency), not a tile: no seam score')
446
+ if (r.density) out.push(`texel density: ${r.density.words}`)
447
+ if (p.ktx2?.mode) out.push(`KTX2: ${p.ktx2.mode.toUpperCase()}, ${mb(p.ktx2.bytes)} MB on disk; ${p.ktx2.why}`)
448
+ if (p.ktx2File) out.push(`GPU memory: ${mb(p.gpu.ktx2.low)} to ${mb(p.gpu.ktx2.high)} MB, written as KTX2 ${p.ktx2File.toUpperCase()}`)
449
+ else if (p.gpu) out.push(`GPU memory: ${mb(p.gpu.rgba8)} MB as it is, ${mb(ktx2Range(p).low)} to ${mb(ktx2Range(p).high)} MB as KTX2`)
450
+ if (!p.ktx2File && (p.ktx2?.bytes || p.ktx2Recorded?.bytes)) out.push(bytesLine(p.bytes, p.ktx2?.bytes ?? p.ktx2Recorded.bytes, `as ${p.format.toUpperCase()}`))
451
+ }
452
+ if (r.brief === 'none') out.push('No brief.json that passes its schema, so nothing to hold it to.')
453
+ return out
454
+ }
455
+
456
+ /** The KTX2 measurements of a report, for the ledger: { role or name: { mode, bytes, psnr, deltaE, detail } }. */
457
+ export function ktx2Record(r) {
458
+ const out = {}
459
+ const pick = (k) => (k?.mode ? { mode: k.mode, bytes: k.bytes, ...(k.measured?.[k.mode] ? { psnr: k.measured[k.mode].psnr, deltaE: k.measured[k.mode].deltaE, detail: k.measured[k.mode].detail } : {}) } : null)
460
+ if (r.kind === 'material') for (const [role, p] of Object.entries(r.maps)) if (pick(p.ktx2)) out[role] = pick(p.ktx2)
461
+ if (r.kind === 'model') for (const t of r.textures) if (pick(t.ktx2)) out[t.name] = pick(t.ktx2)
462
+ return out
463
+ }
464
+
465
+ export { describe }
@@ -0,0 +1,196 @@
1
+ // Generation jobs on disk, so a job outlives the request (and the studio)
2
+ // that started it: .nowhere/jobs/<jobId>.json holds what was asked, what it
3
+ // was estimated at, the vendor's ids and where each candidate is. asset_job
4
+ // polls it; a finished candidate is downloaded into quarantine as
5
+ // .nowhere/quarantine/gen-<jobId>-<n>/ with model.glb, its thumbnail and a
6
+ // source.json that asset_import reads like any other, its generation with
7
+ // the prompt's hash and the pictures the job was made from.
8
+
9
+ import { randomBytes } from 'node:crypto'
10
+ import fs from 'node:fs'
11
+ import fsp from 'node:fs/promises'
12
+ import { createRequire } from 'node:module'
13
+ import path from 'node:path'
14
+ import { addToManifest } from './fetch.mjs'
15
+ import { download, fetchThumbnail, imageMime } from './net.mjs'
16
+ import { today } from './ledger.mjs'
17
+
18
+ const require = createRequire(import.meta.url)
19
+ const { QUARANTINE, QUARANTINE_LIMITS } = require('../downloads.cjs')
20
+
21
+ export const JOBS_DIR = '.nowhere/jobs'
22
+ // worldlabs: environment_generate's worlds, kept beside the models' jobs.
23
+ const JOB_ID = /^(meshy|fal|tripo|worldlabs)-\d{8}-\d{6}-[0-9a-f]{6}$/
24
+
25
+ function stamp(now) {
26
+ const d = new Date(now)
27
+ const p = (n) => String(n).padStart(2, '0')
28
+ return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
29
+ }
30
+
31
+ export const newJobId = (provider, now = Date.now()) => `${provider}-${stamp(now)}-${randomBytes(3).toString('hex')}`
32
+ export const isJobId = (id) => JOB_ID.test(String(id ?? ''))
33
+
34
+ const fileOf = (root, id) => path.join(root, ...JOBS_DIR.split('/'), `${id}.json`)
35
+
36
+ export async function writeJob(root, job) {
37
+ const file = fileOf(root, job.id)
38
+ await fsp.mkdir(path.dirname(file), { recursive: true })
39
+ const temp = `${file}.${process.pid}.tmp`
40
+ await fsp.writeFile(temp, `${JSON.stringify(job, null, 2)}\n`)
41
+ await fsp.rename(temp, file)
42
+ }
43
+
44
+ export async function readJob(root, id) {
45
+ if (!isJobId(id)) return null
46
+ try {
47
+ return JSON.parse(await fsp.readFile(fileOf(root, id), 'utf8'))
48
+ } catch {
49
+ return null
50
+ }
51
+ }
52
+
53
+ export async function listJobs(root) {
54
+ try {
55
+ return (await fsp.readdir(path.join(root, ...JOBS_DIR.split('/')))).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).filter(isJobId).sort()
56
+ } catch {
57
+ return []
58
+ }
59
+ }
60
+
61
+ /** The job's status from its candidates: done when every one has finished. */
62
+ export function overall(job) {
63
+ const s = job.candidates.map((c) => c.status)
64
+ if (s.every((x) => x === 'succeeded' || x === 'failed')) return s.some((x) => x === 'succeeded') ? 'succeeded' : 'failed'
65
+ return s.some((x) => x === 'running') ? 'running' : 'pending'
66
+ }
67
+
68
+ /** Asks the vendor about every candidate still going. Mutates and returns the job. */
69
+ export async function pollJob(job, provider, { key, fetch, ua }) {
70
+ for (const c of job.candidates) {
71
+ if (c.status === 'succeeded' || c.status === 'failed') continue
72
+ let r
73
+ try {
74
+ r = await provider.poll(c, { task: job.task, model: job.model, key, fetch, ua })
75
+ } catch (err) {
76
+ // A poll that failed (the network, a 5xx) is not the job failing.
77
+ c.note = `the last poll failed: ${String(err?.message ?? err).slice(0, 160)}`
78
+ continue
79
+ }
80
+ c.note = r.note
81
+ if (r.next) {
82
+ c.history = [...(c.history ?? []), { vendorId: c.vendorId, stage: c.stage }]
83
+ c.vendorId = r.next.vendorId
84
+ c.stage = r.next.stage
85
+ job.vendorIds = [...new Set([...(job.vendorIds ?? []), r.next.vendorId])]
86
+ }
87
+ c.status = r.status
88
+ if (Number.isFinite(r.progress)) c.progress = r.progress
89
+ if (r.error) c.error = r.error
90
+ if (r.glbUrl) c.glbUrl = r.glbUrl
91
+ if (r.thumbnailUrl) c.thumbnailUrl = r.thumbnailUrl
92
+ }
93
+ job.status = overall(job)
94
+ job.updatedAt = new Date().toISOString()
95
+ return job
96
+ }
97
+
98
+ /**
99
+ * Downloads each finished candidate that is not down yet into
100
+ * quarantine/gen-<jobId>-<n>/. Returns the thumbnails (PNG or JPEG) for the
101
+ * answer, and the quarantine ids. With `key`, a signed URL the file host
102
+ * refuses (one that expired between the poll and now: Tripo's live minutes)
103
+ * is asked for once more from the vendor, and the download tried again.
104
+ */
105
+ export async function downloadResults(root, job, provider, { key = null, fetch, ua }) {
106
+ const thumbnails = []
107
+ const ids = []
108
+ // The candidate's GLB (checked by its magic) and its thumbnail, into dir.
109
+ const bring = async (c, dir) => {
110
+ const got = await download(c.glbUrl, path.join(dir, 'model.glb'), { fetch, hosts: provider.hosts, ua, maxBytes: QUARANTINE_LIMITS.generated })
111
+ const head = (await fsp.readFile(path.join(dir, 'model.glb'))).subarray(0, 4).toString('latin1')
112
+ if (head !== 'glTF') throw new Error('what came back is not a GLB')
113
+ if (c.thumbnailUrl) {
114
+ const thumb = await fetchThumbnail(c.thumbnailUrl, { fetch, hosts: provider.hosts, ua, maxBytes: 2 * 1024 * 1024 })
115
+ if (thumb) await fsp.writeFile(path.join(dir, thumb.mime === 'image/png' ? 'thumbnail.png' : 'thumbnail.jpg'), Buffer.from(thumb.data, 'base64'))
116
+ }
117
+ return got
118
+ }
119
+ const bringFresh = async (c, dir) => {
120
+ try {
121
+ return await bring(c, dir)
122
+ } catch (err) {
123
+ // Only when the file host refused the URL, and only once: the vendor
124
+ // is asked where the task is, and a URL it gives that differs is tried.
125
+ if (err?.code !== 'status' || !key || typeof provider.poll !== 'function') throw err
126
+ const fresh = await provider.poll(c, { task: job.task, model: job.model, key, fetch, ua }).catch(() => null)
127
+ if (fresh?.status !== 'succeeded' || !fresh.glbUrl || fresh.glbUrl === c.glbUrl) throw err
128
+ c.glbUrl = fresh.glbUrl
129
+ if (fresh.thumbnailUrl) c.thumbnailUrl = fresh.thumbnailUrl
130
+ return bring(c, dir)
131
+ }
132
+ }
133
+ for (const c of job.candidates) {
134
+ if (c.status !== 'succeeded' || !c.glbUrl) continue
135
+ const qid = `gen-${job.id}-${c.n}`
136
+ const dir = path.join(root, QUARANTINE, qid)
137
+ if (!c.downloaded || !fs.existsSync(path.join(dir, 'model.glb'))) {
138
+ await fsp.mkdir(dir, { recursive: true })
139
+ try {
140
+ const got = await bringFresh(c, dir)
141
+ const license = provider.licenseOf(job.model)
142
+ const source = {
143
+ provider: provider.id,
144
+ id: `${job.id}-${c.n}`,
145
+ kind: 'model',
146
+ title: String(job.prompt || `${provider.label} ${job.task}`).slice(0, 200),
147
+ author: `${provider.label} (generated)`,
148
+ host: got.host,
149
+ license,
150
+ fetchedAt: today(),
151
+ job: job.id,
152
+ generation: { vendor: provider.id, model: job.model, prompt: String(job.prompt ?? '').slice(0, 2000), job: job.id, usd: Math.round((job.estimateUsd / job.candidates.length) * 100) / 100 },
153
+ // The whole prompt's hash and the pictures it was made from, as
154
+ // asset_generate found them; asset_import keeps them in the entry's meta.
155
+ provenance: { promptSha256: job.promptSha256 ?? null, inputs: job.inputs ?? [] },
156
+ files: [{ path: 'model.glb', bytes: got.bytes, sha256: got.sha256 }],
157
+ }
158
+ await fsp.writeFile(path.join(dir, 'source.json'), `${JSON.stringify(source, null, 2)}\n`)
159
+ await addToManifest(root, {
160
+ id: qid,
161
+ file: qid,
162
+ name: `${provider.label} ${job.task} ${c.n}`,
163
+ url: '',
164
+ referrer: '',
165
+ host: got.host,
166
+ bytes: got.bytes,
167
+ sha256: got.sha256,
168
+ kind: 'model',
169
+ ok: true,
170
+ problem: null,
171
+ at: new Date().toISOString(),
172
+ source: { provider: provider.id, job: job.id, license },
173
+ })
174
+ c.downloaded = qid
175
+ // A download that failed on an earlier call is no longer the news.
176
+ delete c.downloadError
177
+ } catch (err) {
178
+ await fsp.rm(dir, { recursive: true, force: true })
179
+ c.downloadError = String(err?.message ?? err).slice(0, 200)
180
+ continue
181
+ }
182
+ }
183
+ ids.push(qid)
184
+ for (const name of ['thumbnail.png', 'thumbnail.jpg']) {
185
+ try {
186
+ const buf = await fsp.readFile(path.join(dir, name))
187
+ const mime = imageMime(buf)
188
+ if (mime) thumbnails.push({ data: buf.toString('base64'), mime })
189
+ break
190
+ } catch {
191
+ // no thumbnail of that kind
192
+ }
193
+ }
194
+ }
195
+ return { thumbnails, ids }
196
+ }