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,122 @@
1
+ // What asset_import may write for the two sides a planet goes to: the server
2
+ // that takes it and the player that plays it. KTX2 textures and meshopt
3
+ // geometry are only worth writing where both decode them (publish contract
4
+ // 4); written for a side that does not, the planet is refused at Publish, or
5
+ // worse, drawn as nothing.
6
+ //
7
+ // The pre-flight of every Publish (publish.cjs) asks both sides what they can
8
+ // do. What they said is kept here, in the project's .nowhere/sides.json
9
+ // (.nowhere/ is never committed), and asset_import reads it before it writes:
10
+ // a side that said it lacks 'ktx2' or 'meshopt' gets PNG and JPEG textures
11
+ // and plain geometry, so the planet still goes up to it. A side never asked,
12
+ // or one that did not answer, is taken to decode what this package's player
13
+ // decodes (DECODERS_LIVE): that is what the studio and the CLI draw here, and
14
+ // a Publish to a side that turns out older says so before anything goes up.
15
+ //
16
+ // Electron-free and offline: nothing here asks the network. The CLI vendors
17
+ // it beside the asset tools.
18
+
19
+ import fs from 'node:fs'
20
+ import fsp from 'node:fs/promises'
21
+ import path from 'node:path'
22
+ import { DECODERS_LIVE, capabilityName } from '../../schema/dist/index.js'
23
+
24
+ /** Where a project keeps what the sides last said, from its root. */
25
+ export const SIDES_FILE = path.join('.nowhere', 'sides.json')
26
+ const SCHEMA = 'nowhere/sides@1'
27
+ const SIDES = ['server', 'player']
28
+ const DECODERS = ['meshopt', 'ktx2']
29
+
30
+ /** A reading worth keeping: a side that answered, with its capabilities
31
+ * ('current'), or without them, as one from before contract 3 ('legacy').
32
+ * 'unknown' says nothing about the side and never replaces what it said
33
+ * before. */
34
+ function kept(reading, now) {
35
+ if (!reading || (reading.state !== 'current' && reading.state !== 'legacy') || !Array.isArray(reading.capabilities)) return null
36
+ return {
37
+ state: reading.state,
38
+ ...(reading.state === 'current' && Number.isInteger(reading.info?.contract) ? { contract: reading.info.contract } : {}),
39
+ capabilities: reading.capabilities.filter((c) => typeof c === 'string').slice(0, 64),
40
+ at: new Date(now).toISOString(),
41
+ }
42
+ }
43
+
44
+ /** What the sides last said, as kept: { server?, player? }, or {} when the
45
+ * project has never published (or the file cannot be read). */
46
+ export function readSides(root) {
47
+ try {
48
+ const raw = JSON.parse(fs.readFileSync(path.join(root, SIDES_FILE), 'utf8'))
49
+ if (raw?.schema !== SCHEMA) return {}
50
+ const out = {}
51
+ for (const side of SIDES) if (Array.isArray(raw[side]?.capabilities)) out[side] = raw[side]
52
+ return out
53
+ } catch {
54
+ return {}
55
+ }
56
+ }
57
+
58
+ /**
59
+ * Keeps what a pre-flight's readSides found ({ server, player }, each an
60
+ * InfoReading), side by side: a side that did not answer keeps what it said
61
+ * last. Never throws: the memory is a convenience, and a Publish must not
62
+ * stop because .nowhere/ could not be written.
63
+ */
64
+ export async function rememberSides(root, sides, { now = Date.now() } = {}) {
65
+ try {
66
+ const before = readSides(root)
67
+ const out = { schema: SCHEMA }
68
+ for (const side of SIDES) {
69
+ const reading = kept(sides?.[side], now) ?? before[side]
70
+ if (reading) out[side] = reading
71
+ }
72
+ const file = path.join(root, SIDES_FILE)
73
+ await fsp.mkdir(path.dirname(file), { recursive: true })
74
+ await fsp.writeFile(file, JSON.stringify(out, null, 2) + '\n', 'utf8')
75
+ return { ok: true, sides: out }
76
+ } catch (err) {
77
+ return { ok: false, error: err?.message ?? String(err) }
78
+ }
79
+ }
80
+
81
+ function listed(items) {
82
+ return items.length <= 1 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`
83
+ }
84
+
85
+ /**
86
+ * The decoders asset_import writes for in this project: { meshopt, ktx2 }
87
+ * (what optimiseModel and the material import read), with `lacking`, the
88
+ * sides that took one away ({ side, capability, contract?, at }), and `why`,
89
+ * the sentence that says so, or null when both are written. `live` is what
90
+ * this package's player decodes (DECODERS_LIVE; a check passes its own).
91
+ */
92
+ export function decodersFor(root, { live = DECODERS_LIVE, sides = null } = {}) {
93
+ const memory = sides ?? readSides(root)
94
+ const out = { meshopt: !!live.meshopt, ktx2: !!live.ktx2 }
95
+ const lacking = []
96
+ for (const side of SIDES) {
97
+ const reading = memory?.[side]
98
+ if (!Array.isArray(reading?.capabilities)) continue
99
+ for (const c of DECODERS) {
100
+ if (live[c] && !reading.capabilities.includes(c)) {
101
+ out[c] = false
102
+ lacking.push({ side, capability: c, ...(reading.contract ? { contract: reading.contract } : {}), ...(reading.at ? { at: reading.at } : {}) })
103
+ }
104
+ }
105
+ }
106
+ let why = null
107
+ const off = DECODERS.filter((c) => !out[c])
108
+ if (off.length) {
109
+ const what = listed(off.map(capabilityName))
110
+ if (lacking.length) {
111
+ const sidesSaid = SIDES.filter((side) => lacking.some((l) => l.side === side)).map((side) => {
112
+ const l = lacking.find((x) => x.side === side)
113
+ const day = l.at ? ` on ${l.at.slice(0, 10)}` : ''
114
+ return `the Oda ${side}${l.contract ? ` (publish contract ${l.contract})` : ''} said${day} that it does not take ${listed(lacking.filter((x) => x.side === side).map((x) => capabilityName(x.capability)))}`
115
+ })
116
+ why = `${what[0].toUpperCase()}${what.slice(1)} ${off.length === 1 ? 'is' : 'are'} not written: ${listed(sidesSaid)} (the last Publish asked), so the planet can still be published there. They are written again once a Publish finds both sides take them.`
117
+ } else {
118
+ why = `${what[0].toUpperCase()}${what.slice(1)} ${off.length === 1 ? 'is' : 'are'} not written: the planet player this studio publishes to does not decode ${off.length === 1 ? 'it' : 'them'}.`
119
+ }
120
+ }
121
+ return { ...out, lacking, why }
122
+ }
@@ -0,0 +1,261 @@
1
+ // Pictures as surfaces: whether a texture tiles without a seam, making one
2
+ // tile, the 2 x 2 sheet that shows how it repeats, cutting a card out of a
3
+ // flat background, and a panorama at the 2:1 of an equirectangular sky.
4
+ // Plain RGBA in and out ({ data, width, height }, as reference/decode.mjs
5
+ // gives), so the checks run on pictures they draw themselves.
6
+ //
7
+ // The seam score is measured, not judged by eye: the step across the wrap
8
+ // (the last column into the first, the last row into the first) against the
9
+ // steps between neighbouring columns and rows inside the picture. A tile that
10
+ // repeats cleanly steps across its wrap like anywhere else (a score near 1);
11
+ // a photograph's edges do not meet, and the step there is several times the
12
+ // usual one.
13
+ //
14
+ // Two things a step cannot tell apart are said rather than guessed: on an
15
+ // almost flat picture (a smooth sky, a painted wall) steps under a level and
16
+ // a half of luma are not ones a visitor sees, so the usual step is never
17
+ // taken as less than that; and on a regular pattern (tiles, planks, bricks)
18
+ // a joint that falls on the edge steps as hard as the pattern's own joints,
19
+ // which reads as a seam. When the wrap's step is as big as the picture's
20
+ // biggest ones and those are joints (four times the usual step and more),
21
+ // the verdict is 'joint': the 2 x 2 sheet decides.
22
+
23
+ import { fitEdge, resample } from '../reference/facts.mjs'
24
+
25
+ /** The scores that part a clean wrap from a seam a visitor sees. Set on 24
26
+ * scanned colour maps at 1024 px (Poly Haven and ambientCG: rock, plaster,
27
+ * concrete, marble, metal, bricks, blocks, paving, tiles, planks, a leaf)
28
+ * against crops of each that do not tile, cut at 70% and at 50%. Whole,
29
+ * 21 scored clean or joint and 3 faint (the bricks' mortar rows, the
30
+ * planks' and the marble's veins, 1.7 to 2.1), none a seam; cropped, 43 of
31
+ * 48 scored faint, seam or joint, and the 5 that scored clean were flat or
32
+ * fine-grained walls where the crop's seam is hard to see at all. Between
33
+ * the two bars, a seam that shows where light rakes across it. */
34
+ export const SEAM_CLEAN = 1.6
35
+ export const SEAM_VISIBLE = 2.2
36
+ /** Luma steps (of 255) too small to see, however they compare. */
37
+ export const SEAM_FLOOR = 1.5
38
+
39
+ const MEASURE_EDGE = 1024
40
+
41
+ /** Luma (0 to 255) of a picture, one float per pixel. */
42
+ export function lumaOf(pic) {
43
+ const n = pic.width * pic.height
44
+ const out = new Float32Array(n)
45
+ for (let p = 0, i = 0; p < n; p++, i += 4) out[p] = 0.2126 * pic.data[i] + 0.7152 * pic.data[i + 1] + 0.0722 * pic.data[i + 2]
46
+ return out
47
+ }
48
+
49
+ const median = (values) => {
50
+ const s = Float64Array.from(values).sort()
51
+ return s.length ? s[Math.floor(s.length / 2)] : 0
52
+ }
53
+ const round = (v, d = 2) => Math.round(v * 10 ** d) / 10 ** d
54
+
55
+ /** Along one axis: the wrap's step over the usual (median) step inside,
56
+ * and whether it is the size of the pattern's own joints. */
57
+ function axisScore(L, w, h, axis) {
58
+ const cols = axis === 'x' ? w : h
59
+ const rows = axis === 'x' ? h : w
60
+ const at = axis === 'x' ? (c, r) => L[r * w + c] : (c, r) => L[c * w + r]
61
+ const steps = new Float64Array(cols - 1)
62
+ for (let c = 0; c < cols - 1; c++) {
63
+ let sum = 0
64
+ for (let r = 0; r < rows; r++) sum += Math.abs(at(c + 1, r) - at(c, r))
65
+ steps[c] = sum / rows
66
+ }
67
+ let wrap = 0
68
+ for (let r = 0; r < rows; r++) wrap += Math.abs(at(0, r) - at(cols - 1, r))
69
+ wrap /= rows
70
+ const sorted = Float64Array.from(steps).sort()
71
+ const usual = Math.max(sorted.length ? sorted[Math.floor(sorted.length / 2)] : 0, SEAM_FLOOR)
72
+ const high = sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.99))] : 0
73
+ const biggest = sorted.length ? sorted[sorted.length - 1] : 0
74
+ const score = wrap / usual
75
+ const joint = score > SEAM_CLEAN && biggest >= 4 * usual && wrap >= 0.8 * high && wrap <= 1.1 * biggest
76
+ return { score, joint }
77
+ }
78
+
79
+ /**
80
+ * How well a picture tiles: { x, y, score, verdict, words } where x and y
81
+ * are the seam scores across the left-right and the top-bottom wrap, score
82
+ * the worse of those asked for (axes 'xy', or 'x' for a panorama), and
83
+ * verdict 'clean', 'faint', 'seam' or 'joint' (the step is a joint's: look).
84
+ */
85
+ export function seamScore(pic, { axes = 'xy' } = {}) {
86
+ const p = fitEdge(pic, MEASURE_EDGE)
87
+ const L = lumaOf(p)
88
+ const ax = axisScore(L, p.width, p.height, 'x')
89
+ const ay = axes === 'x' ? { score: 0, joint: false } : axisScore(L, p.width, p.height, 'y')
90
+ const x = round(ax.score)
91
+ const y = round(axes === 'x' ? axisScore(L, p.width, p.height, 'y').score : ay.score)
92
+ const verdictOf = (a) => (a.joint ? 'joint' : a.score <= SEAM_CLEAN ? 'clean' : a.score <= SEAM_VISIBLE ? 'faint' : 'seam')
93
+ const rank = { clean: 0, joint: 1, faint: 2, seam: 3 }
94
+ const [vx, vy] = [verdictOf(ax), verdictOf(ay)]
95
+ const xWorse = rank[vx] > rank[vy] || (rank[vx] === rank[vy] && ax.score >= ay.score)
96
+ const verdict = xWorse ? vx : vy
97
+ const score = axes === 'x' ? x : xWorse ? x : y
98
+ const where = xWorse ? 'its left edge meets its right' : 'its top edge meets its bottom'
99
+ const words =
100
+ verdict === 'clean'
101
+ ? `tiles cleanly (seam score ${score}: the step across the wrap is like any other)`
102
+ : verdict === 'joint'
103
+ ? `where ${where} it steps ${score} times the usual, as hard as its own joints (grout, gaps, mortar): a joint that falls on the edge, or a seam; the 2 x 2 sheet tells which`
104
+ : verdict === 'faint'
105
+ ? `a faint seam where ${where} (score ${score}; ${SEAM_CLEAN} and under is clean): it shows where light rakes across it`
106
+ : `a visible seam where ${where} (score ${score}, the step there ${score} times the usual one): it does not tile`
107
+ return { x, y, score, verdict, words }
108
+ }
109
+
110
+ const smooth = (e0, e1, v) => {
111
+ const t = Math.min(1, Math.max(0, (v - e0) / (e1 - e0)))
112
+ return t * t * (3 - 2 * t)
113
+ }
114
+
115
+ /**
116
+ * The picture made to tile: blended with itself moved by half its size, the
117
+ * moved copy at the edges (which meet across the wrap) and the picture
118
+ * itself in the middle, `feather` the share of the way from an edge to the
119
+ * middle over which one becomes the other. axes 'x' tiles left to right only
120
+ * (a panorama).
121
+ */
122
+ export function makeSeamless(pic, { axes = 'xy', feather = 0.5 } = {}) {
123
+ const { width: w, height: h, data } = pic
124
+ const out = new Uint8Array(data.length)
125
+ const sx = Math.floor(w / 2)
126
+ const sy = axes === 'x' ? 0 : Math.floor(h / 2)
127
+ for (let y = 0; y < h; y++) {
128
+ const dy = axes === 'x' ? 1 : Math.min(y, h - 1 - y) / (h / 2)
129
+ const wy = axes === 'x' ? 1 : smooth(0, feather, dy)
130
+ for (let x = 0; x < w; x++) {
131
+ const dx = Math.min(x, w - 1 - x) / (w / 2)
132
+ const k = smooth(0, feather, dx) * wy
133
+ const i = (y * w + x) * 4
134
+ const j = (((y + sy) % h) * w + ((x + sx) % w)) * 4
135
+ for (let c = 0; c < 4; c++) out[i + c] = Math.round(data[i + c] * k + data[j + c] * (1 - k))
136
+ }
137
+ }
138
+ return { data: out, width: w, height: h }
139
+ }
140
+
141
+ /** The picture repeated 2 x 2, `edge` pixels a side in all: how it tiles. */
142
+ export function tile2x2(pic, edge = 512) {
143
+ const one = resample(pic, Math.max(1, Math.round(edge / 2)), Math.max(1, Math.round(((edge / 2) * pic.height) / pic.width)))
144
+ const W = one.width * 2
145
+ const H = one.height * 2
146
+ const data = new Uint8Array(W * H * 4)
147
+ for (let y = 0; y < H; y++) {
148
+ for (let x = 0; x < W; x++) {
149
+ const s = ((y % one.height) * one.width + (x % one.width)) * 4
150
+ data.set(one.data.subarray(s, s + 4), (y * W + x) * 4)
151
+ }
152
+ }
153
+ return { data, width: W, height: H }
154
+ }
155
+
156
+ /**
157
+ * A card cut out of the flat background it was made on: the background's
158
+ * colour read from the picture's border, every pixel's alpha from its
159
+ * distance to that colour (soft at the edge), and the background's colour
160
+ * taken back out of the half-transparent rim. Answers { pic, key, coverage,
161
+ * problems }: coverage is the share of the picture the card covers.
162
+ */
163
+ export function keyOut(pic, { soft = [36, 96] } = {}) {
164
+ const { width: w, height: h, data } = pic
165
+ const band = Math.max(1, Math.round(Math.min(w, h) * 0.02))
166
+ const border = [[], [], []]
167
+ for (let y = 0; y < h; y++) {
168
+ for (let x = 0; x < w; x++) {
169
+ if (x >= band && x < w - band && y >= band && y < h - band) continue
170
+ const i = (y * w + x) * 4
171
+ for (let c = 0; c < 3; c++) border[c].push(data[i + c])
172
+ }
173
+ }
174
+ const key = border.map((ch) => median(ch))
175
+ let spread = 0
176
+ for (let k = 0; k < border[0].length; k++) spread += Math.hypot(border[0][k] - key[0], border[1][k] - key[1], border[2][k] - key[2])
177
+ spread /= border[0].length
178
+ const out = new Uint8Array(data.length)
179
+ let covered = 0
180
+ for (let p = 0, i = 0; p < w * h; p++, i += 4) {
181
+ const d = Math.hypot(data[i] - key[0], data[i + 1] - key[1], data[i + 2] - key[2])
182
+ const a = smooth(soft[0], soft[1], d)
183
+ covered += a
184
+ for (let c = 0; c < 3; c++) {
185
+ // What is left of the colour once the background's share is taken out.
186
+ const v = a > 0.02 ? (data[i + c] - key[c] * (1 - a)) / a : data[i + c]
187
+ out[i + c] = Math.max(0, Math.min(255, Math.round(v)))
188
+ }
189
+ out[i + 3] = Math.round(a * (data[i + 3] / 255) * 255)
190
+ }
191
+ const coverage = round(covered / (w * h), 3)
192
+ const problems = []
193
+ if (spread > 24) problems.push(`the background is not one flat colour (its border varies by ${Math.round(spread)} on average), so the cut may take part of the subject or leave some background`)
194
+ if (coverage < 0.02) problems.push('almost nothing was left after the background was taken out: the subject may be the background colour')
195
+ if (coverage > 0.95) problems.push('almost nothing was taken out: there may be no flat background to cut away')
196
+ const hex = `#${key.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`
197
+ return { pic: { data: out, width: w, height: h }, key: hex, coverage, problems }
198
+ }
199
+
200
+ /** A panorama at exactly 2:1, its full height kept (an equirectangular sky
201
+ * spans the whole 180 degrees top to bottom), its width fitted to twice
202
+ * that. Stretched wider, its columns are sampled around the wrap, so its
203
+ * left edge still meets its right as it did: clamped, the stretch makes a
204
+ * step there of its own. */
205
+ export function toEquirect(pic, { maxWidth = 4096 } = {}) {
206
+ const h = Math.min(pic.height, Math.floor(maxWidth / 2))
207
+ const W = h * 2
208
+ const tall = h === pic.height ? pic : resample(pic, pic.width, h)
209
+ if (W <= tall.width) return resample(tall, W, h)
210
+ const { data, width } = tall
211
+ const out = new Uint8Array(W * h * 4)
212
+ for (let x = 0; x < W; x++) {
213
+ const fx = ((((x + 0.5) * width) / W - 0.5) % width + width) % width
214
+ const x0 = Math.floor(fx)
215
+ const x1 = (x0 + 1) % width
216
+ const t = fx - x0
217
+ for (let y = 0; y < h; y++) {
218
+ const a = (y * width + x0) * 4
219
+ const b = (y * width + x1) * 4
220
+ const o = (y * W + x) * 4
221
+ for (let c = 0; c < 4; c++) out[o + c] = Math.round(data[a + c] * (1 - t) + data[b + c] * t)
222
+ }
223
+ }
224
+ return { data: out, width: W, height: h }
225
+ }
226
+
227
+ /** Simple numbers about a picture: alpha, mean luma, its 5th and 95th
228
+ * percentiles, and how uneven it is at large scale (the spread of the means
229
+ * of an 8 x 8 grid against the mean: light falling off across a tile shows
230
+ * as a pattern once it repeats). */
231
+ export function pictureStats(pic) {
232
+ const p = fitEdge(pic, 512)
233
+ const L = lumaOf(p)
234
+ let alpha = 0
235
+ for (let i = 3; i < p.data.length; i += 4) if (p.data[i] < 250) alpha++
236
+ const sorted = Float64Array.from(L).sort()
237
+ const mean = L.reduce((a, b) => a + b, 0) / L.length
238
+ const cells = []
239
+ for (let gy = 0; gy < 8; gy++) {
240
+ for (let gx = 0; gx < 8; gx++) {
241
+ let s = 0
242
+ let n = 0
243
+ for (let y = Math.floor((gy * p.height) / 8); y < Math.floor(((gy + 1) * p.height) / 8); y++) {
244
+ for (let x = Math.floor((gx * p.width) / 8); x < Math.floor(((gx + 1) * p.width) / 8); x++) {
245
+ s += L[y * p.width + x]
246
+ n++
247
+ }
248
+ }
249
+ if (n) cells.push(s / n)
250
+ }
251
+ }
252
+ const cm = cells.reduce((a, b) => a + b, 0) / cells.length
253
+ const sd = Math.sqrt(cells.reduce((a, b) => a + (b - cm) ** 2, 0) / cells.length)
254
+ return {
255
+ alpha: round(alpha / (p.width * p.height), 3),
256
+ mean: round(mean / 255, 3),
257
+ p05: round(sorted[Math.floor(sorted.length * 0.05)] / 255, 3),
258
+ p95: round(sorted[Math.floor(sorted.length * 0.95)] / 255, 3),
259
+ unevenness: mean > 0 ? round(sd / mean, 3) : 0,
260
+ }
261
+ }
@@ -0,0 +1,180 @@
1
+ // Safe extraction of a downloaded archive inside quarantine. The whole
2
+ // archive is judged from its central directory before one byte is written,
3
+ // and refused on anything that could write outside the folder or fill the
4
+ // disk: an absolute path, a parent segment, a drive letter, a symlink entry,
5
+ // more than 2000 entries, more than 1 GB uncompressed, an entry that inflates
6
+ // over 200 times its size, an archive inside the archive. Executables and
7
+ // scripts are left in the archive and listed. Each file written is checked
8
+ // again as it inflates (the sizes in a header can lie) and then by
9
+ // downloads.cjs checkFile.
10
+ //
11
+ // fflate inflates; the directory is read here, because fflate does not
12
+ // expose an entry's attributes (which is where a symlink is marked).
13
+
14
+ import fsp from 'node:fs/promises'
15
+ import { createRequire } from 'node:module'
16
+ import path from 'node:path'
17
+ import { Inflate } from 'fflate'
18
+
19
+ const require = createRequire(import.meta.url)
20
+ const { checkFile } = require('../downloads.cjs')
21
+
22
+ export const UNZIP_LIMITS = Object.freeze({ entries: 2000, bytes: 1024 * 1024 * 1024, ratio: 200 })
23
+ const SKIPPED = new Set(['.exe', '.app', '.command', '.sh', '.bat', '.ps1', '.py', '.js', '.mjs', '.cjs', '.dll', '.dylib', '.so', '.jar', '.scr', '.msi', '.pkg'])
24
+ const ARCHIVES = /\.(zip|7z|rar|tar|tgz|gz|bz2|xz|zst|tbz2?|txz)$/i
25
+
26
+ export class ZipRefused extends Error {}
27
+
28
+ /** The central directory: one record per entry. */
29
+ function readDirectory(buf) {
30
+ // The end record sits in the last 64 KB + 22 bytes (a comment may follow it).
31
+ const min = Math.max(0, buf.length - 0xffff - 22)
32
+ let eocd = -1
33
+ for (let i = buf.length - 22; i >= min; i--) {
34
+ if (buf.readUInt32LE(i) === 0x06054b50) {
35
+ eocd = i
36
+ break
37
+ }
38
+ }
39
+ if (eocd < 0) throw new ZipRefused('it is not a zip archive (no end record)')
40
+ const count = buf.readUInt16LE(eocd + 10)
41
+ const size = buf.readUInt32LE(eocd + 12)
42
+ const offset = buf.readUInt32LE(eocd + 16)
43
+ if (count === 0xffff || size === 0xffffffff || offset === 0xffffffff) throw new ZipRefused('it is a ZIP64 archive, which the studio does not unpack')
44
+ if (offset + size > buf.length) throw new ZipRefused('its directory points past its end')
45
+ if (count > UNZIP_LIMITS.entries) throw new ZipRefused(`it has ${count} entries, over the ${UNZIP_LIMITS.entries} the studio unpacks`)
46
+ const entries = []
47
+ let p = offset
48
+ for (let i = 0; i < count; i++) {
49
+ if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50) throw new ZipRefused('its directory is damaged')
50
+ const madeBy = buf.readUInt16LE(p + 4) >> 8
51
+ const flags = buf.readUInt16LE(p + 8)
52
+ const method = buf.readUInt16LE(p + 10)
53
+ const compressed = buf.readUInt32LE(p + 20)
54
+ const uncompressed = buf.readUInt32LE(p + 24)
55
+ const nameLen = buf.readUInt16LE(p + 28)
56
+ const extraLen = buf.readUInt16LE(p + 30)
57
+ const commentLen = buf.readUInt16LE(p + 32)
58
+ const external = buf.readUInt32LE(p + 38)
59
+ const local = buf.readUInt32LE(p + 42)
60
+ const name = buf.subarray(p + 46, p + 46 + nameLen).toString(flags & 0x800 ? 'utf8' : 'latin1')
61
+ entries.push({ name, flags, method, compressed, uncompressed, external, local, madeBy })
62
+ p += 46 + nameLen + extraLen + commentLen
63
+ }
64
+ return entries
65
+ }
66
+
67
+ /** Why an entry's name must not be written, or null. */
68
+ function badName(name) {
69
+ if (!name || name.includes('\0')) return 'an entry without a proper name'
70
+ if (name.startsWith('/') || name.startsWith('\\')) return `an absolute path (${name})`
71
+ if (/^[A-Za-z]:/.test(name)) return `a drive letter (${name})`
72
+ if (name.split(/[\\/]/).some((s) => s === '..')) return `a parent folder segment (${name})`
73
+ return null
74
+ }
75
+
76
+ const isSymlink = (e) => e.madeBy === 3 && ((e.external >>> 16) & 0o170000) === 0o120000
77
+
78
+ /** The bytes of one entry, inflated with a running cap. */
79
+ function inflateEntry(buf, e) {
80
+ if (buf.readUInt32LE(e.local) !== 0x04034b50) throw new ZipRefused(`${e.name} is damaged`)
81
+ const start = e.local + 30 + buf.readUInt16LE(e.local + 26) + buf.readUInt16LE(e.local + 28)
82
+ const data = buf.subarray(start, start + e.compressed)
83
+ if (e.method === 0) return Buffer.from(data)
84
+ const parts = []
85
+ let total = 0
86
+ let failure = null
87
+ const inflater = new Inflate((chunk) => {
88
+ total += chunk.length
89
+ // The header's size is only a claim: past it (or past the ratio) the
90
+ // entry stops inflating at once.
91
+ if (total > e.uncompressed || total > Math.max(1, e.compressed) * UNZIP_LIMITS.ratio) {
92
+ failure ??= new ZipRefused(`${e.name} inflates past what its header says`)
93
+ return
94
+ }
95
+ parts.push(Buffer.from(chunk))
96
+ })
97
+ const STEP = 64 * 1024
98
+ for (let i = 0; i < data.length && !failure; i += STEP) inflater.push(data.subarray(i, i + STEP), i + STEP >= data.length)
99
+ if (failure) throw failure
100
+ return Buffer.concat(parts)
101
+ }
102
+
103
+ /**
104
+ * Unpacks `zipAbs` into `outDir`, all or nothing on a refusal.
105
+ *
106
+ * @returns {Promise<{ ok: true, files: { path: string, bytes: number, kind: string }[], skipped: string[], rejected: { path: string, problem: string }[] }
107
+ * | { ok: false, error: string }>}
108
+ * files: what was written and passed checkFile (paths relative to outDir);
109
+ * skipped: executables and scripts left out; rejected: files that failed
110
+ * checkFile and were removed again.
111
+ */
112
+ export async function safeUnzip(zipAbs, outDir) {
113
+ let buf
114
+ try {
115
+ buf = await fsp.readFile(zipAbs)
116
+ } catch (err) {
117
+ return { ok: false, error: `the archive could not be read (${err.code ?? err.message})` }
118
+ }
119
+ let entries
120
+ try {
121
+ entries = readDirectory(buf)
122
+ let total = 0
123
+ for (const e of entries) {
124
+ const why = badName(e.name)
125
+ if (why) throw new ZipRefused(`it holds ${why}`)
126
+ if (isSymlink(e)) throw new ZipRefused(`it holds a symbolic link (${e.name})`)
127
+ if (e.flags & 0x1) throw new ZipRefused(`it is encrypted (${e.name})`)
128
+ if (e.name.endsWith('/')) continue
129
+ if (ARCHIVES.test(e.name)) throw new ZipRefused(`it holds another archive (${e.name}); nested archives are not unpacked`)
130
+ if (e.method !== 0 && e.method !== 8) throw new ZipRefused(`${e.name} uses a compression the studio does not unpack`)
131
+ if (e.uncompressed > 0 && (e.compressed === 0 || e.uncompressed / e.compressed > UNZIP_LIMITS.ratio)) {
132
+ throw new ZipRefused(`${e.name} would inflate over ${UNZIP_LIMITS.ratio} times its size, which is how an archive bomb looks`)
133
+ }
134
+ total += e.uncompressed
135
+ if (total > UNZIP_LIMITS.bytes) throw new ZipRefused('it unpacks to more than 1 GB')
136
+ }
137
+ } catch (err) {
138
+ if (err instanceof ZipRefused) return { ok: false, error: `The archive was refused: ${err.message}.` }
139
+ return { ok: false, error: `The archive could not be read: ${err.message}.` }
140
+ }
141
+
142
+ const root = path.resolve(outDir)
143
+ const written = []
144
+ const skipped = []
145
+ const rejected = []
146
+ try {
147
+ for (const e of entries) {
148
+ if (e.name.endsWith('/')) continue
149
+ const rel = e.name.replace(/\\/g, '/')
150
+ if (SKIPPED.has(path.extname(rel).toLowerCase())) {
151
+ skipped.push(rel)
152
+ continue
153
+ }
154
+ // macOS's resource forks are noise, never a texture.
155
+ if (rel.startsWith('__MACOSX/') || path.basename(rel).startsWith('._') || path.basename(rel) === '.DS_Store') continue
156
+ const target = path.resolve(root, ...rel.split('/'))
157
+ if (!target.startsWith(root + path.sep)) throw new ZipRefused(`${rel} would land outside the folder`)
158
+ const bytes = inflateEntry(buf, e)
159
+ await fsp.mkdir(path.dirname(target), { recursive: true })
160
+ await fsp.writeFile(target, bytes, { flag: 'wx' })
161
+ written.push({ rel, target, bytes: bytes.length })
162
+ }
163
+ } catch (err) {
164
+ // All or nothing: what this call wrote goes again.
165
+ for (const w of written) await fsp.rm(w.target, { force: true })
166
+ const why = err instanceof ZipRefused ? err.message : err?.code === 'EEXIST' ? 'two entries have the same name' : err.message
167
+ return { ok: false, error: `The archive was refused: ${why}.` }
168
+ }
169
+
170
+ const files = []
171
+ for (const w of written) {
172
+ const check = await checkFile(w.target)
173
+ if (check.ok) files.push({ path: w.rel, bytes: w.bytes, kind: check.kind })
174
+ else {
175
+ rejected.push({ path: w.rel, problem: check.problem })
176
+ await fsp.rm(w.target, { force: true })
177
+ }
178
+ }
179
+ return { ok: true, files, skipped, rejected }
180
+ }