oda-engine 0.0.0-stage → 0.1.0

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 +90 -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-CB77cP9U.js +1 -0
  197. package/web-dist/assets/KTX2Loader-6OIWUF7s.js +2 -0
  198. package/web-dist/assets/SPZLoader-zYj0Alfv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-CJTI1sEh.js +1 -0
  200. package/web-dist/assets/index-CcjyyQco.css +1 -0
  201. package/web-dist/assets/index-DMyJcoZJ.js +693 -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,301 @@
1
+ // The reference board's files: every picture in the project's .nowhere/refs/
2
+ // (where the pictures attached in the chat land too, agent/host.mjs
3
+ // writeReferences), and its record beside them, index.json:
4
+ //
5
+ // { version: 1, pictures: { "<file>": { name?, url?, addedAt?, use?, sha256?, measured? } } }
6
+ //
7
+ // name what the picture was called when it was dropped on the board
8
+ // url the page it came from, for one the agent found on the web and
9
+ // offered in the chat (nw_ask_pictures): the brief cites it with it
10
+ // from the project path it was copied from when a picture card offered
11
+ // it (refs/<file>, where the agent gathers pictures): the agent's
12
+ // board then lists this copy, its switch with it, and not the
13
+ // original again (agent/reference/board.mjs), unless the brief
14
+ // cites the original
15
+ // use false when the creator took it out of the brief's references
16
+ // (or a picture card offered it and nobody picked it): the agent
17
+ // is not handed it unless the brief cites it or it is attached
18
+ // again; absent or true, it is: every request's context lists it
19
+ // on the agent's board with what it measured (agent/reference/
20
+ // board.mjs), and a team production's director reads the pictures
21
+ // attached to a request and the HANDED_EARLIER newest of the
22
+ // others (agent/host.mjs writeReferences)
23
+ // sha256 the bytes `measured` was read from
24
+ // seen the file's size and modified time when it was measured: a file
25
+ // that has changed since lists as not measured, and is measured again
26
+ // measured nw_reference's facts as the board shows them (agent/panels.mjs
27
+ // boardMeasure), measured in the agent host and written here by main
28
+ //
29
+ // Which pictures the brief cites is read from brief.json, never written: the
30
+ // brief is the agent's (SPACE_FIRST.md W2). A picture it cites is not removed
31
+ // from the board, so brief.json never names a file that is gone, and it is
32
+ // handed to the agent whatever its use says, so the brief never cites a
33
+ // picture the agent cannot open again (the agent may cite one that was set
34
+ // aside: citing it puts it back).
35
+ //
36
+ // Electron-free: main hands it the picture thumbnailer and the bin, and the
37
+ // checks run it in plain Node.
38
+
39
+ const crypto = require('node:crypto')
40
+ const fs = require('node:fs')
41
+ const path = require('node:path')
42
+
43
+ const REFS = path.join('.nowhere', 'refs')
44
+ const INDEX = 'index.json'
45
+ const VERSION = 1
46
+ /** What the board lists: the pictures the chat keeps there too. */
47
+ const LISTED = /\.(png|jpe?g|webp|gif)$/i
48
+ /** What may be dropped on it: the pictures nw_reference measures. */
49
+ const ADD_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' }
50
+ /** A reference bigger than this is not a picture anyone attached (look.mjs). */
51
+ const MAX_BYTES = 20 * 1024 * 1024
52
+ const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/
53
+ /** How many earlier pictures a team production's director reads beside the
54
+ * ones attached to a request, newest first (agent/host.mjs writeReferences);
55
+ * the agent's own context lists them all (agent/reference/board.mjs). */
56
+ const HANDED_EARLIER = 6
57
+
58
+ const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
59
+
60
+ function dirOf(root) {
61
+ return path.join(root, REFS)
62
+ }
63
+
64
+ /** A board file name, or null for anything that is not one directly inside the folder. */
65
+ function fileOf(file) {
66
+ const f = String(file ?? '')
67
+ return FILE.test(f) && LISTED.test(f) && f !== INDEX ? f : null
68
+ }
69
+
70
+ /** What the bytes are, by their first ones: the board takes no file on its name alone. */
71
+ function mimeOf(bytes) {
72
+ if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return 'image/png'
73
+ if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
74
+ if (bytes.length >= 12 && bytes.toString('latin1', 0, 4) === 'RIFF' && bytes.toString('latin1', 8, 12) === 'WEBP') return 'image/webp'
75
+ return null
76
+ }
77
+
78
+ function readIndex(root) {
79
+ try {
80
+ const raw = JSON.parse(fs.readFileSync(path.join(dirOf(root), INDEX), 'utf8'))
81
+ if (!isRecord(raw) || raw.version !== VERSION || !isRecord(raw.pictures)) throw new Error('unknown')
82
+ const pictures = {}
83
+ for (const [file, e] of Object.entries(raw.pictures)) if (fileOf(file) && isRecord(e)) pictures[file] = e
84
+ return { version: VERSION, pictures }
85
+ } catch {
86
+ return { version: VERSION, pictures: {} }
87
+ }
88
+ }
89
+
90
+ // Written to a temp name and renamed over, as the agent's settings are.
91
+ function writeIndex(root, doc) {
92
+ const file = path.join(dirOf(root), INDEX)
93
+ fs.mkdirSync(path.dirname(file), { recursive: true })
94
+ const tmp = `${file}.${process.pid}.tmp`
95
+ fs.writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`)
96
+ fs.renameSync(tmp, file)
97
+ }
98
+
99
+ function update(root, file, change) {
100
+ const doc = readIndex(root)
101
+ const next = change({ ...(doc.pictures[file] ?? {}) })
102
+ if (next === null) delete doc.pictures[file]
103
+ else doc.pictures[file] = next
104
+ writeIndex(root, doc)
105
+ }
106
+
107
+ /** The brief's references by board file: { status, cites: Map(file -> { id, what }) }.
108
+ * Read as plain JSON: a brief that fails its schema still says what it cites. */
109
+ function briefCites(root) {
110
+ const cites = new Map()
111
+ let raw
112
+ try {
113
+ raw = JSON.parse(fs.readFileSync(path.join(root, 'brief.json'), 'utf8'))
114
+ } catch (err) {
115
+ return { status: err?.code === 'ENOENT' ? 'absent' : 'unreadable', cites }
116
+ }
117
+ for (const r of Array.isArray(raw?.references) ? raw.references : []) {
118
+ if (!isRecord(r) || typeof r.path !== 'string') continue
119
+ const rel = r.path.replace(/\\/g, '/').replace(/^\.\//, '')
120
+ if (!rel.startsWith('.nowhere/refs/')) continue
121
+ const file = rel.slice('.nowhere/refs/'.length)
122
+ if (fileOf(file)) cites.set(file, { id: typeof r.id === 'string' ? r.id : '', what: typeof r.what === 'string' ? r.what : '' })
123
+ }
124
+ return { status: 'present', cites }
125
+ }
126
+
127
+ /** Every picture on the board, newest first, with its record and whether the brief cites it. */
128
+ function list(root) {
129
+ if (!root) return { ok: false, error: 'Open a project first.' }
130
+ const dir = dirOf(root)
131
+ const doc = readIndex(root)
132
+ const brief = briefCites(root)
133
+ let names = []
134
+ try {
135
+ names = fs.readdirSync(dir).filter((n) => fileOf(n))
136
+ } catch {
137
+ names = []
138
+ }
139
+ const pictures = []
140
+ for (const file of names) {
141
+ let stat
142
+ try {
143
+ stat = fs.statSync(path.join(dir, file))
144
+ } catch {
145
+ continue
146
+ }
147
+ if (!stat.isFile()) continue
148
+ const e = doc.pictures[file] ?? {}
149
+ const same = isRecord(e.seen) && e.seen.size === stat.size && e.seen.mtimeMs === stat.mtimeMs
150
+ const cited = brief.cites.get(file) ?? null
151
+ pictures.push({
152
+ file,
153
+ mtimeMs: stat.mtimeMs,
154
+ path: `.nowhere/refs/${file}`,
155
+ bytes: stat.size,
156
+ name: typeof e.name === 'string' ? e.name : null,
157
+ url: typeof e.url === 'string' ? e.url : null,
158
+ addedAt: typeof e.addedAt === 'string' ? e.addedAt : new Date(stat.mtimeMs).toISOString(),
159
+ // One the brief cites is in use whatever was set before it was cited.
160
+ use: e.use !== false || !!cited,
161
+ measured: same && isRecord(e.measured) ? e.measured : null,
162
+ sha256: same && typeof e.sha256 === 'string' ? e.sha256 : null,
163
+ brief: cited,
164
+ // A GIF is listed (the chat keeps them) but nothing measures one.
165
+ measurable: !/\.gif$/i.test(file),
166
+ })
167
+ }
168
+ // Which ones the next request hands over unasked: every one for the
169
+ // brief, as the context's board lists them (agent/reference/board.mjs).
170
+ for (const p of pictures) {
171
+ p.handed = p.use
172
+ delete p.mtimeMs
173
+ }
174
+ pictures.sort((a, b) => b.addedAt.localeCompare(a.addedAt) || a.file.localeCompare(b.file))
175
+ return { ok: true, dir: '.nowhere/refs', pictures, brief: brief.status, handedEarlier: HANDED_EARLIER }
176
+ }
177
+
178
+ /** Pictures dropped or picked, as { name, mime, data: bytes }: each kept under
179
+ * its content's hash, as the chat keeps an attached picture, so the same
180
+ * picture twice is one file. */
181
+ function add(root, items, now = () => new Date()) {
182
+ if (!root) return { ok: false, error: 'Open a project first.' }
183
+ const added = []
184
+ const refused = []
185
+ for (const item of Array.isArray(items) ? items.slice(0, 24) : []) {
186
+ const name = String(item?.name ?? 'picture').slice(0, 120)
187
+ const url = typeof item?.url === 'string' && /^https?:\/\/\S{1,600}$/.test(item.url) ? item.url : null
188
+ const from = projectPath(item?.from)
189
+ let bytes
190
+ try {
191
+ bytes = Buffer.from(item?.data instanceof ArrayBuffer ? new Uint8Array(item.data) : item?.data ?? [])
192
+ } catch {
193
+ bytes = Buffer.alloc(0)
194
+ }
195
+ if (bytes.length === 0) {
196
+ refused.push({ name, why: 'It is empty.' })
197
+ continue
198
+ }
199
+ if (bytes.length > MAX_BYTES) {
200
+ refused.push({ name, why: `It is ${Math.round(bytes.length / 1048576)} MB; a reference is at most 20 MB.` })
201
+ continue
202
+ }
203
+ const mime = mimeOf(bytes)
204
+ if (!mime || !ADD_TYPES[mime]) {
205
+ refused.push({ name, why: 'It is not a PNG, JPEG or WebP picture.' })
206
+ continue
207
+ }
208
+ const file = `${crypto.createHash('sha1').update(bytes).digest('hex').slice(0, 12)}.${ADD_TYPES[mime]}`
209
+ const abs = path.join(dirOf(root), file)
210
+ fs.mkdirSync(dirOf(root), { recursive: true })
211
+ if (!fs.existsSync(abs)) fs.writeFileSync(abs, bytes)
212
+ update(root, file, (e) => ({ ...e, name: e.name ?? name, ...(url && !e.url ? { url } : {}), ...(from && !e.from ? { from } : {}), addedAt: e.addedAt ?? now().toISOString() }))
213
+ added.push(file)
214
+ }
215
+ return { ok: true, added, refused }
216
+ }
217
+
218
+ /** Takes a picture off the board: into the bin main gives (the system's), or
219
+ * deleted where there is none. Never one the brief cites. */
220
+ async function remove(root, file, { trash } = {}) {
221
+ if (!root) return { ok: false, error: 'Open a project first.' }
222
+ const f = fileOf(file)
223
+ if (!f) return { ok: false, error: 'Not a picture on the board.' }
224
+ const cited = briefCites(root).cites.get(f)
225
+ if (cited) return { ok: false, error: `The brief cites it as ${cited.id || 'a reference'}. Ask the agent to take it out of the brief first.`, cited: true }
226
+ const abs = path.join(dirOf(root), f)
227
+ try {
228
+ if (typeof trash === 'function') await trash(abs)
229
+ else await fs.promises.rm(abs, { force: true })
230
+ } catch (err) {
231
+ return { ok: false, error: `It could not be removed: ${err?.message ?? err}` }
232
+ }
233
+ update(root, f, () => null)
234
+ return { ok: true }
235
+ }
236
+
237
+ /** Whether the brief may use it: false takes it out of what the agent is
238
+ * handed. Never for one the brief cites: the agent would no longer be
239
+ * handed a picture its brief names. */
240
+ function setUse(root, file, on) {
241
+ if (!root) return { ok: false, error: 'Open a project first.' }
242
+ const f = fileOf(file)
243
+ if (!f || !fs.existsSync(path.join(dirOf(root), f))) return { ok: false, error: 'Not a picture on the board.' }
244
+ const cited = on === false ? briefCites(root).cites.get(f) : null
245
+ if (cited) return { ok: false, error: `The brief cites it as ${cited.id || 'a reference'}, so the agent keeps it. Ask the agent to take it out of the brief first.`, cited: true }
246
+ update(root, f, (e) => {
247
+ const next = { ...e }
248
+ if (on === false) next.use = false
249
+ else delete next.use
250
+ return next
251
+ })
252
+ return { ok: true, use: on !== false }
253
+ }
254
+
255
+ /** Keeps what the agent host measured, against the bytes it read. */
256
+ function setMeasured(root, file, sha256, measured) {
257
+ const f = fileOf(file)
258
+ if (!root || !f || !isRecord(measured) || !/^[0-9a-f]{64}$/.test(String(sha256))) return false
259
+ let stat
260
+ try {
261
+ stat = fs.statSync(path.join(dirOf(root), f))
262
+ } catch {
263
+ return false
264
+ }
265
+ update(root, f, (e) => ({ ...e, sha256, seen: { size: stat.size, mtimeMs: stat.mtimeMs }, measured }))
266
+ return true
267
+ }
268
+
269
+ /** The picture's path, when it is one on the board. */
270
+ function pictureFile(root, file) {
271
+ const f = fileOf(file)
272
+ if (!root || !f) return null
273
+ const abs = path.join(dirOf(root), f)
274
+ return fs.existsSync(abs) ? abs : null
275
+ }
276
+
277
+ /** A path inside the project as the board keeps it (forward slashes, no
278
+ * leading ./), or null for anything else. */
279
+ function projectPath(v) {
280
+ const p = typeof v === 'string' ? v.replace(/\\/g, '/').replace(/^\.\//, '') : ''
281
+ return p && p.length <= 300 && !p.startsWith('/') && !/^[A-Za-z]:/.test(p) && !p.split('/').includes('..') ? p : null
282
+ }
283
+
284
+ /** The project paths the board's pictures were copied from (a card's
285
+ * candidates from refs/), each standing for its copy still on the board. */
286
+ function copiedFrom(root) {
287
+ const out = new Set()
288
+ for (const [file, e] of Object.entries(readIndex(root).pictures)) {
289
+ if (typeof e.from === 'string' && projectPath(e.from) && fs.existsSync(path.join(dirOf(root), file))) out.add(projectPath(e.from))
290
+ }
291
+ return out
292
+ }
293
+
294
+ /** The board files the agent is not handed, for the agent host: the ones
295
+ * set aside (use false) that the brief does not cite. */
296
+ function excluded(root) {
297
+ const cites = briefCites(root).cites
298
+ return new Set(Object.entries(readIndex(root).pictures).filter(([file, e]) => e.use === false && !cites.has(file)).map(([file]) => file))
299
+ }
300
+
301
+ module.exports = { REFS, INDEX, HANDED_EARLIER, list, add, remove, setUse, setMeasured, pictureFile, excluded, copiedFrom, readIndex, mimeOf }
@@ -0,0 +1,335 @@
1
+ import { z } from 'zod';
2
+ /** Every kind of file a planet may carry, its extensions and the most one
3
+ * file of it may weigh. Models keep the 50 MB storage ceiling
4
+ * (LIMITS.assetFileMb); the others are sized for what a browser decodes
5
+ * without stalling the first frame. A splat environment (a Gaussian splat,
6
+ * three's GaussianSplat) travels as .spz only: asset_import turns a .ply or
7
+ * a .splat into one, so the player reads a single compact format. It keeps
8
+ * the storage ceiling too, which is about 2.3 million splats with their
9
+ * full colour detail. It is not the planet's own splat.bin (publish.ts),
10
+ * the point cloud the universe shows inside a planet's glass. */
11
+ export declare const ASSET_KINDS: {
12
+ readonly model: {
13
+ readonly extensions: readonly [".glb", ".gltf", ".obj", ".fbx", ".stl", ".ply", ".dae", ".3mf"];
14
+ readonly fileMb: 50;
15
+ };
16
+ readonly texture: {
17
+ readonly extensions: readonly [".ktx2", ".webp", ".png", ".jpg"];
18
+ readonly fileMb: 8;
19
+ };
20
+ readonly hdri: {
21
+ readonly extensions: readonly [".hdr", ".exr"];
22
+ readonly fileMb: 24;
23
+ };
24
+ readonly audio: {
25
+ readonly extensions: readonly [".ogg", ".mp3", ".wav"];
26
+ readonly fileMb: 10;
27
+ };
28
+ readonly lut: {
29
+ readonly extensions: readonly [".cube"];
30
+ readonly fileMb: 2;
31
+ };
32
+ readonly splat: {
33
+ readonly extensions: readonly [".spz"];
34
+ readonly fileMb: 50;
35
+ };
36
+ };
37
+ export type AssetKind = keyof typeof ASSET_KINDS;
38
+ /** Everything one planet carries, every kind together (LIMITS.assetsMb). */
39
+ export declare const ASSETS_TOTAL_MB = 100;
40
+ /** The sounds a planet carries, in total, inside ASSETS_TOTAL_MB. */
41
+ export declare const AUDIO_TOTAL_MB = 20;
42
+ /** How many splats one splat file may hold, and the whole planet, the count
43
+ * past which asset_import says a splat is for desktops, and the size a
44
+ * planet with splats aims to stay under (SPACE_FIRST W7: 60 MB, so it
45
+ * loads in a few seconds).
46
+ *
47
+ * Phase 1 timed the GPU alone (1.78 million splats in 15 ms a frame) and
48
+ * allowed 3 million. The real preview is far slower: the CLI's page with
49
+ * the look's defaults, headless Chrome on an Apple M5 Pro at 1280 x 720,
50
+ * walking inside the splat (2026-10-24), steady fps on WebGPU and WebGL 2:
51
+ *
52
+ * 195k about 55 and 40 (three's lion)
53
+ * 500k 33 and 19 (World Labs' example kitchen)
54
+ * 1M 19 and 10 (the kitchen twice over)
55
+ * 2M 9.5 and 5 (four times)
56
+ *
57
+ * so a frame costs about 30 ms per 500,000 splats on WebGPU. A planet may
58
+ * ask for 1 million at most, the most a fast desktop still walks; World
59
+ * Labs' full_res (about 2 million) is past it. Phones were not measured:
60
+ * 500,000 is the size World Labs exports for lighter devices, a vendor's
61
+ * choice, not a measurement. */
62
+ export declare const SPLAT_LIMITS: {
63
+ readonly count: 1000000;
64
+ readonly planetCount: 1000000;
65
+ readonly phoneCount: 500000;
66
+ readonly planetMb: 60;
67
+ };
68
+ /** The splats a ledger records (its splat entries' meta.count), leaving out
69
+ * the paths in `except` (files about to be replaced). */
70
+ export declare function planetSplats(files: Record<string, {
71
+ kind?: string;
72
+ meta?: Record<string, unknown>;
73
+ }> | undefined, except?: readonly string[]): number;
74
+ /** What a check says about a planet's splat environments: more splats in all
75
+ * than a planet may draw, and a planet with splats past the size it aims
76
+ * for. Empty for a planet with none. */
77
+ export declare function splatAdvice(files: Record<string, {
78
+ kind?: string;
79
+ meta?: Record<string, unknown>;
80
+ }> | undefined, planetBytes: number): string[];
81
+ /** The kind a file is by its extension, or null for one a planet cannot carry. */
82
+ export declare function assetKindOf(path: string): AssetKind | null;
83
+ /** A file a planet may carry: directly inside assets/, one of the kinds above,
84
+ * nothing that climbs out. The same structural rules as isAssetPath, so every
85
+ * model a scene could place before is still a path a planet may carry; the
86
+ * Storage key is built from this string. */
87
+ export declare function isPublishablePath(path: string): boolean;
88
+ /** How big a thing is, which sets how many triangles and texture pixels it may
89
+ * spend. The agent names one when it imports or builds a model. */
90
+ export declare const ASSET_CLASSES: readonly ["small", "prop", "large", "hero", "character", "building", "terrain"];
91
+ export type AssetClass = (typeof ASSET_CLASSES)[number];
92
+ export declare const TRIANGLE_BUDGETS: Record<AssetClass, number>;
93
+ /** The longest side of any one texture, in pixels. */
94
+ export declare const TEXTURE_BUDGETS: Record<AssetClass, number>;
95
+ /** What a planet player built from this package decodes: meshopt-compressed
96
+ * geometry and KTX2 textures, both by WebAssembly, which the player page's
97
+ * CSP allows from publish contract 4 on (decision D1). The server and the
98
+ * player that are live may still be older, so whether one planet may carry
99
+ * them is the handshake's business ('meshopt' and 'ktx2' in what each side
100
+ * offers), and asset_import writes them only where the last pre-flight did
101
+ * not find a side without them. */
102
+ export declare const DECODERS_LIVE: {
103
+ readonly meshopt: true;
104
+ readonly ktx2: true;
105
+ };
106
+ /** Whether a planet built from this package shows its credits to visitors:
107
+ * the planet page lists the manifest's credit lines from publish contract 4
108
+ * on (decision D2). CC BY needs a visible credit, so a planet that carries a
109
+ * CC BY file needs 'credits' of the player that shows it, and a server or a
110
+ * player from before contract 4 does not offer it. */
111
+ export declare const CREDITS_SHOWN: boolean;
112
+ export declare const LEDGER_FILE = "assets.lock.json";
113
+ export declare const AssetEntry: z.ZodObject<{
114
+ kind: z.ZodEnum<{
115
+ splat: "splat";
116
+ model: "model";
117
+ texture: "texture";
118
+ hdri: "hdri";
119
+ audio: "audio";
120
+ lut: "lut";
121
+ blend: "blend";
122
+ image: "image";
123
+ }>;
124
+ bytes: z.ZodNumber;
125
+ sha256: z.ZodString;
126
+ origin: z.ZodEnum<{
127
+ download: "download";
128
+ generated: "generated";
129
+ made: "made";
130
+ creator: "creator";
131
+ legacy: "legacy";
132
+ }>;
133
+ license: z.ZodObject<{
134
+ spdx: z.ZodString;
135
+ url: z.ZodOptional<z.ZodString>;
136
+ credit: z.ZodOptional<z.ZodString>;
137
+ textSha256: z.ZodOptional<z.ZodString>;
138
+ checkedAt: z.ZodString;
139
+ confirmedByCreator: z.ZodOptional<z.ZodBoolean>;
140
+ }, z.core.$strip>;
141
+ source: z.ZodOptional<z.ZodObject<{
142
+ provider: z.ZodString;
143
+ id: z.ZodOptional<z.ZodString>;
144
+ url: z.ZodOptional<z.ZodString>;
145
+ author: z.ZodOptional<z.ZodString>;
146
+ title: z.ZodOptional<z.ZodString>;
147
+ host: z.ZodOptional<z.ZodString>;
148
+ fetchedAt: z.ZodOptional<z.ZodString>;
149
+ }, z.core.$strip>>;
150
+ generation: z.ZodOptional<z.ZodObject<{
151
+ vendor: z.ZodString;
152
+ model: z.ZodString;
153
+ prompt: z.ZodString;
154
+ job: z.ZodString;
155
+ usd: z.ZodNumber;
156
+ }, z.core.$strip>>;
157
+ derivedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
158
+ steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
159
+ op: z.ZodString;
160
+ at: z.ZodString;
161
+ detail: z.ZodString;
162
+ }, z.core.$strip>>>;
163
+ publish: z.ZodDefault<z.ZodBoolean>;
164
+ meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
165
+ }, z.core.$strip>;
166
+ export type AssetEntryT = z.infer<typeof AssetEntry>;
167
+ export declare const AssetLock: z.ZodObject<{
168
+ schema: z.ZodLiteral<"nowhere/assets@1">;
169
+ files: z.ZodRecord<z.ZodString, z.ZodObject<{
170
+ kind: z.ZodEnum<{
171
+ splat: "splat";
172
+ model: "model";
173
+ texture: "texture";
174
+ hdri: "hdri";
175
+ audio: "audio";
176
+ lut: "lut";
177
+ blend: "blend";
178
+ image: "image";
179
+ }>;
180
+ bytes: z.ZodNumber;
181
+ sha256: z.ZodString;
182
+ origin: z.ZodEnum<{
183
+ download: "download";
184
+ generated: "generated";
185
+ made: "made";
186
+ creator: "creator";
187
+ legacy: "legacy";
188
+ }>;
189
+ license: z.ZodObject<{
190
+ spdx: z.ZodString;
191
+ url: z.ZodOptional<z.ZodString>;
192
+ credit: z.ZodOptional<z.ZodString>;
193
+ textSha256: z.ZodOptional<z.ZodString>;
194
+ checkedAt: z.ZodString;
195
+ confirmedByCreator: z.ZodOptional<z.ZodBoolean>;
196
+ }, z.core.$strip>;
197
+ source: z.ZodOptional<z.ZodObject<{
198
+ provider: z.ZodString;
199
+ id: z.ZodOptional<z.ZodString>;
200
+ url: z.ZodOptional<z.ZodString>;
201
+ author: z.ZodOptional<z.ZodString>;
202
+ title: z.ZodOptional<z.ZodString>;
203
+ host: z.ZodOptional<z.ZodString>;
204
+ fetchedAt: z.ZodOptional<z.ZodString>;
205
+ }, z.core.$strip>>;
206
+ generation: z.ZodOptional<z.ZodObject<{
207
+ vendor: z.ZodString;
208
+ model: z.ZodString;
209
+ prompt: z.ZodString;
210
+ job: z.ZodString;
211
+ usd: z.ZodNumber;
212
+ }, z.core.$strip>>;
213
+ derivedFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
214
+ steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
215
+ op: z.ZodString;
216
+ at: z.ZodString;
217
+ detail: z.ZodString;
218
+ }, z.core.$strip>>>;
219
+ publish: z.ZodDefault<z.ZodBoolean>;
220
+ meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
221
+ }, z.core.$strip>>;
222
+ }, z.core.$strip>;
223
+ export type AssetLockT = z.infer<typeof AssetLock>;
224
+ export declare const LICENSE_POLICY: {
225
+ readonly allowed: readonly ["CC0-1.0", "LicenseRef-PD", "LicenseRef-Own", "LicenseRef-Creator-Declared", "LicenseRef-Generated-Owned", "LicenseRef-QAL-1.0"];
226
+ /** Need license.credit; publishing them needs CREDITS_SHOWN. */
227
+ readonly credit: readonly ["CC-BY-4.0", "CC-BY-3.0"];
228
+ /** Need confirmedByCreator and a credit. */
229
+ readonly ask: readonly ["CC-BY-SA-4.0", "CC-BY-SA-3.0"];
230
+ readonly refused: RegExp;
231
+ };
232
+ export type LicenseVerdict = {
233
+ ok: true;
234
+ credit: boolean;
235
+ } | {
236
+ ok: false;
237
+ code: string;
238
+ reason: string;
239
+ };
240
+ type LicenseLike = {
241
+ spdx: string;
242
+ credit?: string;
243
+ confirmedByCreator?: boolean;
244
+ };
245
+ /** Whether a file under this licence may be used in a planet, and whether it
246
+ * needs a visible credit. The codes are the LedgerFinding codes publishing
247
+ * reports. */
248
+ export declare function licenseVerdict(license: LicenseLike): LicenseVerdict;
249
+ /** The files the config needs beside the bundle: an HDRI sky's asset and a
250
+ * LUT. Read by plain property access (config.sky.asset when sky.kind is
251
+ * 'hdri'; config.look?.grade?.lut?.asset), so it works on any version of the
252
+ * config schema, and on an unvalidated document. */
253
+ export declare function collectConfigAssets(config: unknown): string[];
254
+ export interface LedgerFinding {
255
+ code: 'ledger:missing' | 'ledger:bytes' | 'ledger:sha' | 'ledger:kind' | 'ledger:license' | 'ledger:credit' | 'ledger:credits-hidden' | 'ledger:sa-unconfirmed' | 'ledger:not-published';
256
+ path: string;
257
+ message: string;
258
+ }
259
+ /** What checkLedger reads of an entry: the full ledger's and the publish
260
+ * view's (publishLock) both have it, so the studio and the Edge Function run
261
+ * the same gate on their own copy. */
262
+ export interface LedgerLike {
263
+ files: Record<string, {
264
+ kind: string;
265
+ bytes: number;
266
+ sha256: string;
267
+ license: LicenseLike;
268
+ publish?: boolean;
269
+ }>;
270
+ }
271
+ /** One sentence per file that may not travel. uploads: every file under
272
+ * assets/ about to go up. sha256 is checked when given (the studio gives it;
273
+ * the Edge Function checks bytes only). */
274
+ export declare function checkLedger(lock: LedgerLike, uploads: {
275
+ path: string;
276
+ bytes: number;
277
+ sha256?: string;
278
+ }[], opts?: {
279
+ creditsShown?: boolean;
280
+ }): LedgerFinding[];
281
+ /** The view of the ledger that goes to the server. */
282
+ export declare const PublishLock: z.ZodObject<{
283
+ schema: z.ZodLiteral<"nowhere/assets-publish@1">;
284
+ files: z.ZodRecord<z.ZodString, z.ZodObject<{
285
+ kind: z.ZodString;
286
+ bytes: z.ZodNumber;
287
+ sha256: z.ZodString;
288
+ origin: z.ZodString;
289
+ license: z.ZodObject<{
290
+ spdx: z.ZodString;
291
+ credit: z.ZodOptional<z.ZodString>;
292
+ confirmedByCreator: z.ZodOptional<z.ZodBoolean>;
293
+ }, z.core.$strip>;
294
+ }, z.core.$strip>>;
295
+ }, z.core.$strip>;
296
+ export type PublishLockT = z.infer<typeof PublishLock>;
297
+ /** What goes to the server: per published file its kind, size, hash, origin
298
+ * and licence. Prompts, costs, steps and sources stay on the creator's
299
+ * machine. */
300
+ export declare function publishLock(lock: AssetLockT): PublishLockT;
301
+ /** The publish view as the server receives it, or why it is refused. */
302
+ export declare function parsePublishLock(raw: unknown): {
303
+ ok: true;
304
+ lock: PublishLockT;
305
+ } | {
306
+ ok: false;
307
+ error: string;
308
+ };
309
+ /** The credits of a ledger: the section CREDITS.md carries, and the lines a
310
+ * planet's manifest lists for visitors (every published file under assets/,
311
+ * with a courtesy line where its licence asks for none). */
312
+ export declare function creditsFor(lock: AssetLockT): {
313
+ markdown: string;
314
+ entries: {
315
+ path: string;
316
+ title?: string;
317
+ author?: string;
318
+ license: string;
319
+ url?: string;
320
+ credit: string;
321
+ }[];
322
+ };
323
+ export interface SizeFinding {
324
+ code: 'budget:file' | 'budget:audio' | 'budget:total' | 'budget:kind';
325
+ path?: string;
326
+ message: string;
327
+ }
328
+ /** Every size rule on the files a version carries beside its code: each file
329
+ * against its kind's ceiling, the sounds together against AUDIO_TOTAL_MB and
330
+ * everything against ASSETS_TOTAL_MB. Empty when they all fit. */
331
+ export declare function assetSizeProblems(files: {
332
+ path: string;
333
+ bytes: number;
334
+ }[]): SizeFinding[];
335
+ export {};