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,366 @@
1
+ // The reference, as tools: what a reference picture is in numbers
2
+ // (nw_reference) and how far a view of the game is from it (nw_compare).
3
+ //
4
+ // nw_reference is what the director's interpretation reads before it writes
5
+ // the brief: the lettering it found and masked out, the palette in OKLab
6
+ // clusters with shares and where each sits, the value key, the contrast,
7
+ // the saturation, the warmth, the haze, the big masses and the focal
8
+ // points with their boxes, the horizon and a guess at the camera with how
9
+ // sure each is, the picture's true shape, and whether it carries a frame
10
+ // (with the crop that leaves the art). Every look value of the brief cites
11
+ // one of these numbers, and every subject of it is boxed against them,
12
+ // which is what keeps a game from drifting to a stock mood or a guessed
13
+ // form. nw_compare puts a view beside the reference (a side by
14
+ // side picture for the critic) with the colour and structure metrics and the
15
+ // gross flags; it is the pixel half of a gate, the critic's eye the other.
16
+ //
17
+ // Electron-free and host-agnostic like look.mjs: the studio, the runner and
18
+ // the CLI answer the same 'view' rpc, and pictures are decoded with sharp or
19
+ // the viewport's 'pixels' rpc (reference/decode.mjs).
20
+
21
+ import fsp from 'node:fs/promises'
22
+ import path from 'node:path'
23
+ import { z } from 'zod'
24
+ import { deltaE2000, hexToLab } from '../../schema/dist/index.js'
25
+ import { compareMetrics, cropPicture, fitAspect, fitEdge, factsSummary, referenceFacts } from '../reference/facts.mjs'
26
+ import { decodeImage } from '../reference/decode.mjs'
27
+ import { blit, canvas, encodePng, fillRect, line, rgbOf } from '../reference/png.mjs'
28
+ import { LOOK_SETTLE_MS, notJudged, readReference } from './look.mjs'
29
+ import { boardIds, boardPalette, briefMeasured, measureBoard, rangeOf } from '../reference/board.mjs'
30
+
31
+ export const RPC_METHODS = ['view', 'pixels', 'build']
32
+
33
+ /** Where a reference may be: what the creator attached, or the project's own refs/. */
34
+ const REF_DIRS = ['.nowhere/refs/', 'refs/']
35
+ const SIDE_WIDTH = 1024
36
+
37
+ const HEX = /^#[0-9a-fA-F]{6}$/
38
+ const vec3 = z.array(z.number()).length(3)
39
+ const Crop = z.array(z.number().min(0).max(1)).length(4).describe('Fractions of the picture: [x0, y0, x1, y1], e.g. the art without its letterbox (its lettering is masked on its own).')
40
+
41
+ /** One camera, as nw_view takes it (eyes.mjs). */
42
+ const shotSpec = z.object({
43
+ view: z.enum(['player', 'orbit', 'closeup', 'overview', 'free']),
44
+ target: z.union([z.string(), vec3]).optional(),
45
+ yaw: z.number().optional(),
46
+ pitch: z.number().optional(),
47
+ distance: z.number().optional(),
48
+ fov: z.number().optional(),
49
+ position: vec3.optional(),
50
+ lookAt: vec3.optional(),
51
+ fog: z.boolean().optional(),
52
+ aspect: z.enum(['wide', 'square', 'tall']).optional(),
53
+ })
54
+
55
+ const REFERENCE_SHAPE = {
56
+ image: z.string().optional().describe('The reference in the project: .nowhere/refs/<file> (what the creator attached) or refs/<file>. Leave it out with board.'),
57
+ board: z.boolean().optional().describe('Measure every picture on the reference board (.nowhere/refs/ and refs/) at once, instead of one: each one\'s palette, values, warmth, haze, horizon and camera, and the board\'s palette pooled over them all.'),
58
+ crop: Crop.optional(),
59
+ sheet: z.boolean().optional().describe('Also return one picture: the reference with its horizon, thirds, masses and masked lettering drawn, its palette and its value histogram.'),
60
+ }
61
+
62
+ const COMPARE_SHAPE = {
63
+ reference: z.string().describe('The reference in the project: .nowhere/refs/<file> or refs/<file>.'),
64
+ camera: z
65
+ .union([z.string(), shotSpec])
66
+ .optional()
67
+ .describe("A camera id from the production's cameras (in a team task), or a shot as nw_view takes it. Default in a team task: the reference camera."),
68
+ crop: Crop.optional(),
69
+ palette: z.array(z.string().regex(HEX, 'must be a #rrggbb hex colour')).min(1).max(8).optional().describe("The brief's palette: how close each colour comes in the view."),
70
+ longEdge: z.number().int().min(256).max(1568).optional().describe('The shot\'s long side in pixels. Default 1024.'),
71
+ }
72
+
73
+ const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
74
+ const fmt = (n, digits = 2) => (typeof n === 'number' && Number.isFinite(n) ? String(Number(n.toFixed(digits))) : '?')
75
+ const signed = (n, digits = 1) => (typeof n === 'number' && Number.isFinite(n) ? `${n > 0 ? '+' : ''}${n.toFixed(digits)}` : '?')
76
+ const rpcOf = (ctx) => (typeof ctx?.rpc === 'function' ? ctx.rpc : async () => ({ ok: false, error: 'The studio is not connected.' }))
77
+
78
+ /** The reference's bytes, or why it cannot be read: readReference's rules
79
+ * (inside the project, a picture, never from a blocked site) and one more,
80
+ * that it lies where references live. */
81
+ async function loadReference(ctx, given, tool) {
82
+ const root = ctx?.projectRoot
83
+ if (!root) return { error: 'There is no project open.' }
84
+ const ref = await readReference(root, given, tool)
85
+ if (ref.error) return ref
86
+ if (!REF_DIRS.some((dir) => ref.rel.startsWith(dir))) {
87
+ return { error: `${given} is not a reference: ${tool} reads pictures under .nowhere/refs/ (what the creator attached) or refs/.` }
88
+ }
89
+ return ref
90
+ }
91
+
92
+ /** A box of fractions outlined on a sheet's picture of w x h pixels. */
93
+ function outline(sheet, box, w, h, rgb, width = 1) {
94
+ const [x0, y0, x1, y1] = box.map((v, i) => Math.round(v * (i % 2 ? h - 1 : w - 1)))
95
+ line(sheet, x0, y0, x1, y0, rgb, width)
96
+ line(sheet, x0, y1, x1, y1, rgb, width)
97
+ line(sheet, x0, y0, x0, y1, rgb, width)
98
+ line(sheet, x1, y0, x1, y1, rgb, width)
99
+ }
100
+
101
+ /** The reference with its horizon, thirds, masses and masked lettering
102
+ * drawn on it, its palette as swatches by share, its accents, and its
103
+ * value histogram. */
104
+ function referenceSheet(pic, facts) {
105
+ const W = 768
106
+ const art = fitEdge(pic, W)
107
+ const scale = W / art.width
108
+ const imgH = Math.round(art.height * scale)
109
+ const sheet = canvas(W, imgH + 8 + 48 + 8 + 24 + 8 + 96 + 8, [28, 28, 32])
110
+ blit(sheet, art, 0, 0, W, imgH)
111
+ for (const f of [1 / 3, 2 / 3]) {
112
+ line(sheet, Math.round(W * f), 0, Math.round(W * f), imgH - 1, [255, 255, 255])
113
+ line(sheet, 0, Math.round(imgH * f), W - 1, Math.round(imgH * f), [255, 255, 255])
114
+ }
115
+ // Masses by their value (dark, mid, light), the lettering in black.
116
+ const VALUE = { dark: [40, 90, 255], mid: [60, 220, 120], light: [255, 200, 40] }
117
+ for (const m of facts.masses ?? []) outline(sheet, m.box, W, imgH, VALUE[m.value] ?? [200, 200, 200], 2)
118
+ for (const t of facts.text?.boxes ?? []) outline(sheet, t.box, W, imgH, [0, 0, 0], 3)
119
+ if (facts.horizon.y !== null) {
120
+ const y = Math.round(facts.horizon.y * imgH)
121
+ const dy = Math.tan((facts.horizon.tiltDeg * Math.PI) / 180) * (W / 2)
122
+ line(sheet, 0, Math.round(y - dy), W - 1, Math.round(y + dy), [255, 47, 208], 3)
123
+ }
124
+ let x = 0
125
+ const top = imgH + 8
126
+ facts.palette.forEach((p, i) => {
127
+ const w = i === facts.palette.length - 1 ? W - x : Math.round(p.share * W)
128
+ fillRect(sheet, x, top, w, 48, rgbOf(p.hex))
129
+ x += w
130
+ })
131
+ facts.accents.forEach((a, i) => fillRect(sheet, i * 32, top + 56, 24, 24, rgbOf(a.hex)))
132
+ const hist = facts.value.histogram
133
+ const peak = Math.max(...hist, 1e-6)
134
+ const barW = W / hist.length
135
+ const base = top + 56 + 24 + 8 + 96
136
+ hist.forEach((v, i) => {
137
+ const h = Math.round((v / peak) * 96)
138
+ const grey = Math.round(((i + 0.5) / hist.length) * 255)
139
+ fillRect(sheet, Math.round(i * barW) + 1, base - h, Math.round(barW) - 2, h, [grey, grey, grey])
140
+ })
141
+ return sheet
142
+ }
143
+
144
+ /** The reference left, the shot right (cut to the reference's shape), each
145
+ * half of SIDE_WIDTH. */
146
+ function sideBySide(refPic, shotPic) {
147
+ const half = SIDE_WIDTH / 2
148
+ const aspect = refPic.width / refPic.height
149
+ const h = Math.min(1024, Math.max(64, Math.round(half / aspect)))
150
+ const out = canvas(SIDE_WIDTH, h, [0, 0, 0])
151
+ blit(out, refPic, 0, 0, half, h)
152
+ blit(out, fitAspect(shotPic, aspect), half, 0, half, h)
153
+ return out
154
+ }
155
+
156
+ /** The camera for nw_compare: a shot as given, or one of the production's
157
+ * cameras by id (cameras.json, made from the builder's report). */
158
+ function cameraFor(given, production) {
159
+ const cameras = !production
160
+ ? []
161
+ : Array.isArray(production.cameras)
162
+ ? production.cameras
163
+ : isObj(production.cameras)
164
+ ? Object.entries(production.cameras).map(([id, v]) => (isObj(v) && v.shot ? { id, ...v } : { id, shot: v }))
165
+ : []
166
+ const briefCamera = (id) => (Array.isArray(production?.brief?.cameras) ? production.brief.cameras.find((c) => c?.id === id) : null)
167
+ const purposeOf = (entry) => entry?.purpose ?? briefCamera(entry?.id)?.purpose ?? (entry?.id === 'reference' ? 'reference' : 'other')
168
+ if (isObj(given)) return { name: given.view, shot: given, purpose: 'reference' }
169
+ if (!production) {
170
+ return typeof given === 'string'
171
+ ? { error: `"${given}" is a camera id, and there are named cameras only in a team task. Give the camera as a shot instead, e.g. { "view": "free", "position": [0, 1.6, 12], "lookAt": [0, 1.6, 0] }.` }
172
+ : { error: 'Give the camera as a shot (as nw_view takes it), e.g. { "view": "player" } or { "view": "free", "position": [0, 1.6, 12], "lookAt": [0, 1.6, 0] }.' }
173
+ }
174
+ const id = typeof given === 'string' ? given : (cameras.find((c) => purposeOf(c) === 'reference') ?? cameras.find((c) => purposeOf(c) === 'player'))?.id
175
+ const entry = cameras.find((c) => c?.id === id)
176
+ if (!entry || !isObj(entry.shot)) {
177
+ const known = cameras.map((c) => c?.id).filter(Boolean)
178
+ return { error: `There is no camera "${id ?? '(none given)'}" in this production${known.length ? `; its cameras: ${known.join(', ')}` : ' yet (the blockout makes them)'}.` }
179
+ }
180
+ return { name: entry.id, shot: entry.shot, purpose: purposeOf(entry) }
181
+ }
182
+
183
+ const safe = (s) => String(s).replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, 60) || 'view'
184
+
185
+ /** Saves the pictures into the production's shots/ folder, when there is one. */
186
+ async function saveShots(ctx, camera, png, shot) {
187
+ const p = ctx?.production
188
+ if (!p?.dir || !ctx.projectRoot) return null
189
+ const dir = path.join(path.isAbsolute(p.dir) ? p.dir : path.join(ctx.projectRoot, p.dir), 'shots')
190
+ const task = isObj(p.task) ? p.task : { id: typeof p.task === 'string' ? p.task : null }
191
+ const stem = `${safe(task.id ?? 'look')}-r${Number.isInteger(task.round) ? task.round : 0}-${safe(camera)}`
192
+ try {
193
+ await fsp.mkdir(dir, { recursive: true })
194
+ const compare = path.join(dir, `${stem}-compare.png`)
195
+ const view = path.join(dir, `${stem}.${shot.mime === 'image/png' ? 'png' : 'jpg'}`)
196
+ await fsp.writeFile(compare, png)
197
+ await fsp.writeFile(view, Buffer.from(shot.data, 'base64'))
198
+ const rel = (f) => path.relative(ctx.projectRoot, f).split(path.sep).join('/')
199
+ return { compare: rel(compare), shot: rel(view) }
200
+ } catch {
201
+ return null
202
+ }
203
+ }
204
+
205
+ /** nw_reference over the whole board: every picture measured (or read from
206
+ * what was measured before), one line each, and what the board says
207
+ * together; then each picture's measured block as brief.json takes it, by
208
+ * its R id (one the brief already has keeps it). Writes nothing: what it
209
+ * measures new it remembers in memory, and the host keeps the digests at
210
+ * the start of the next request. The digests travel with the answer, for a
211
+ * caller that keeps them. */
212
+ async function readBoard(ctx) {
213
+ const root = ctx?.projectRoot
214
+ if (!root) return { text: 'There is no project open.', isError: true }
215
+ const fresh = Array.isArray(ctx?.attached) ? ctx.attached.filter((f) => typeof f === 'string') : []
216
+ const board = await measureBoard(root, { fresh, rpc: ctx?.rpc ?? null, timeMs: null, keep: false })
217
+ const aside = board.aside ? ` ${board.aside} set aside on the board (not for the brief) ${board.aside === 1 ? 'is' : 'are'} left out; brief.json citing one takes it back.` : ''
218
+ if (board.pictures.length === 0) {
219
+ return { text: `The reference board is empty: nothing under .nowhere/refs/ (what the creator attaches) or refs/ (what you gather).${aside} Look references up with nw_find_pictures and keep those you build from with nw_keep_pictures (after the web consent card), or write brief.json from the creator's words with its references empty.`, board: [] }
220
+ }
221
+ let brief = null
222
+ try {
223
+ brief = JSON.parse(await fsp.readFile(path.join(root, 'brief.json'), 'utf8'))
224
+ } catch {
225
+ // no brief yet, or one that does not parse: every picture is new
226
+ }
227
+ const ids = boardIds(board.pictures, brief)
228
+ const digests = board.pictures.map((p) => p.digest)
229
+ const lines = [
230
+ `The reference board: ${board.pictures.length} picture${board.pictures.length === 1 ? '' : 's'}${board.more ? ` (and ${board.more} more past the first ${board.pictures.length}, not read)` : ''}, ${board.measured} measured now and ${board.kept} as measured before.${aside}`,
231
+ ]
232
+ const measured = digests.filter(Boolean)
233
+ if (measured.length) {
234
+ const pooled = boardPalette(measured)
235
+ lines.push(`Pooled palette (each picture weighs the same; colours within deltaE 8 merged): ${pooled.map((p) => `${p.hex} ${Math.round(p.share * 100)}%`).join(', ')}.`)
236
+ lines.push(
237
+ `Across the board: median L* ${rangeOf(measured, (d) => d.value.p50)}, contrast ${rangeOf(measured, (d) => d.contrast)}, warmth b* ${rangeOf(measured, (d) => d.warmth)}, chroma ${rangeOf(measured, (d) => d.chroma)}, haze ${rangeOf(measured, (d) => d.haze.score, 2)}${rangeOf(measured, (d) => d.horizon.y, 2) ? `, horizon ${rangeOf(measured, (d) => d.horizon.y, 2)} of the height` : ''}.`,
238
+ )
239
+ }
240
+ const known = ids.filter((id, i) => Array.isArray(brief?.references) && brief.references.some((r) => r?.path === board.pictures[i].rel)).length
241
+ lines.push('', `Each picture by its id in brief.json's references${known ? ` (${known} already in the brief keep theirs; a new one takes the next free number)` : ''}:`)
242
+ board.pictures.forEach((p, i) => lines.push(`${ids[i]} ${p.rel}${p.fresh ? ' (attached with this message)' : ''}: ${p.line}`))
243
+ // The same numbers in the brief's own units and paths, ready to copy.
244
+ const entries = board.pictures.flatMap((p, i) => (p.digest ? [{ id: ids[i], path: p.rel, measured: briefMeasured(p.digest) }] : []))
245
+ if (entries.length) {
246
+ lines.push('', "brief.json's references, measured (valueKey and horizonY from 0 to 1; add what each shows as what):", ...entries.map((e) => JSON.stringify(e)))
247
+ }
248
+ lines.push('', 'Read one in full (masses, composition, lettering, the camera guess) with image; a picture a brief\'s hero view is compared with deserves that.')
249
+ return { text: lines.join('\n'), board: board.pictures.map((p, i) => ({ id: ids[i], path: p.rel, digest: p.digest, measured: briefMeasured(p.digest), why: p.why ?? null })) }
250
+ }
251
+
252
+ const nwReference = {
253
+ name: 'nw_reference',
254
+ description:
255
+ 'Reads a reference picture in the project and returns what it is in numbers, as JSON with a short summary: its size and true shape (tall, square, wide); its lettering (a title, credits) found as rows of glyphs and masked out before anything else is measured, each as a box; the palette (OKLab clusters, each with its share and where it sits: its centre and box), small saturated accents, the value key (low, mid, high) and the L* percentiles, global and local contrast, saturation and colourfulness, warmth and tint, haze (five bands from top to bottom: lightness, contrast and chroma, a score and its direction), the masses (the big dark, mid and light shapes of a value study, each with its box, share, how tall against how wide and what lies above and below it), composition (a 3 x 3 grid of L*, where the eye goes, the focal points f1 to f3 with their boxes and masses, symmetry, empty space, a 4 x 4 edge grid), the horizon with its tilt and confidence, a guess at the camera with its confidence (a reading under 0.5 is advisory), and whether the picture has a uniform border, with the crop that leaves the art (read that crop with crop). Every box is [x0, y0, x1, y1] in fractions. Every look value of a brief cites one of these numbers. Takes a reference attached by the creator (.nowhere/refs/) or under refs/; never a URL or a picture from ArtStation, Pinterest or Behance. sheet adds a picture with the horizon, thirds, masses, lettering, palette and histogram drawn. board: true measures every picture on the reference board instead (what the creator attached and what you gathered under refs/, not one set aside there), each in one line by its R id (one brief.json already has keeps it), with the palette pooled over the board, the ranges of its values, warmth and haze, and each picture\'s measured block in brief.json\'s units and paths: what brief.json\'s references, palette and light are written from. It writes nothing (the studio keeps the measurements under .nowhere/board/ at the start of a request).',
256
+ shape: REFERENCE_SHAPE,
257
+ readOnly: true,
258
+ async handler(args, ctx) {
259
+ if (args.board) return await readBoard(ctx)
260
+ if (!args.image) return { text: 'Name the picture (image), or measure the whole board with board: true.', isError: true }
261
+ const ref = await loadReference(ctx, args.image, 'nw_reference')
262
+ if (ref.error) return { text: ref.error, isError: true }
263
+ const pic = await decodeImage(Buffer.from(ref.data, 'base64'), { mime: ref.mime, maxEdge: 1568, rpc: ctx?.rpc })
264
+ if (!pic.ok) return { text: pic.error, isError: true }
265
+ const facts = referenceFacts(pic, { source: ref.rel, crop: args.crop ?? null })
266
+ const images = []
267
+ if (args.sheet) images.push({ data: encodePng(referenceSheet(cropPicture(pic, args.crop ?? null), facts)).toString('base64'), mime: 'image/png' })
268
+ // facts travels with the answer for the director, which saves it as is.
269
+ return { text: `${factsSummary(facts)}\n\nThe facts as JSON:\n${JSON.stringify(facts)}`, images, facts }
270
+ },
271
+ }
272
+
273
+ const nwCompare = {
274
+ name: 'nw_compare',
275
+ description:
276
+ 'Takes a view of the running space and puts it beside the reference: returns a side by side picture (the reference left, the view right, cut to the reference\'s shape), the view itself, and the numbers: the colour comparison (palette deltaE2000, mean L*, contrast and chroma ratios, warmth, tint, a verdict), the structure (how the L* layout correlates, the horizon\'s offset, where the eye goes, the edge and detail ratios), one distance from 0 (the same picture) to 1, and the gross flags (palette-far, value-far, and at the reference camera structure-far and detail-far). The numbers never pass a look on their own: they show what is grossly off, and the side by side is what to judge by eye. camera is a camera id in a team task (default: the reference camera) or a shot as nw_view takes it. Takes a reference in .nowhere/refs/ or refs/; never a URL or a picture from ArtStation, Pinterest or Behance.',
277
+ shape: COMPARE_SHAPE,
278
+ readOnly: true,
279
+ async handler(args, ctx) {
280
+ const ref = await loadReference(ctx, args.reference, 'nw_compare')
281
+ if (ref.error) return { text: ref.error, isError: true }
282
+ const cam = cameraFor(args.camera, ctx?.production ?? null)
283
+ if (cam.error) return { text: cam.error, isError: true }
284
+ const rpc = rpcOf(ctx)
285
+ const notes = []
286
+ // A view after an edit shows the edit, as nw_view's do.
287
+ let needed = false
288
+ try {
289
+ needed = Boolean(await ctx?.run?.needsBuild?.())
290
+ } catch {
291
+ needed = false
292
+ }
293
+ if (needed) {
294
+ const built = await rpc('build')
295
+ if (!built?.ok) notes.push(`The build failed, so the view may show the game before your edit: ${String(built?.error ?? 'no reason given').split('\n')[0]}`)
296
+ else if (built.held) notes.push('The creator is playing, so the view shows the game before your latest edit.')
297
+ }
298
+ const shot = { ...Object.fromEntries(Object.entries(cam.shot).filter(([, v]) => v !== undefined)), longEdge: args.longEdge ?? 1024 }
299
+ // After the game's files have arrived, as look_compare's view is: a
300
+ // picture taken before is of a game without them. And record: false, as
301
+ // look_compare's: nw_view's sameAsLast stays the agent's own.
302
+ const r = await rpc('view', { shots: [shot], settle: { waitMs: LOOK_SETTLE_MS }, record: false }, 18_000 + LOOK_SETTLE_MS)
303
+ const s = r?.ok && Array.isArray(r.shots) ? r.shots[0] : null
304
+ if (!s?.ok || !s.image?.data) return { text: `No picture: ${s?.error ?? r?.error ?? 'the viewport did not answer.'}`, isError: true }
305
+ const early = s.loading && s.loading.mounted && !s.loading.settled ? notJudged(s) : null
306
+ if (early) notes.push(`These numbers are of an unfinished picture: ${early}. Compare again once it has loaded (nw_status, loading).`)
307
+ if (r.frozen) return { text: 'The preview is frozen (no frame drawn lately), so this view is not the game as it is now. Check nw_status.', isError: true }
308
+ const [refPic, shotPic] = await Promise.all([
309
+ decodeImage(Buffer.from(ref.data, 'base64'), { mime: ref.mime, maxEdge: 1024, rpc: ctx?.rpc }),
310
+ decodeImage(Buffer.from(s.image.data, 'base64'), { mime: s.image.mime ?? 'image/jpeg', maxEdge: 1024, rpc: ctx?.rpc }),
311
+ ])
312
+ if (!refPic.ok) return { text: refPic.error, isError: true }
313
+ if (!shotPic.ok) return { text: shotPic.error, isError: true }
314
+ const art = cropPicture(refPic, args.crop ?? null)
315
+ const metrics = compareMetrics(shotPic, art, { camera: cam.name, purpose: cam.purpose })
316
+ const png = encodePng(sideBySide(art, shotPic))
317
+ const saved = await saveShots(ctx, cam.name, png, { data: s.image.data, mime: s.image.mime ?? 'image/jpeg' })
318
+
319
+ const c = metrics.colour
320
+ const st = metrics.structure
321
+ const lines = [`Reference: ${ref.rel}${args.crop ? ` (crop [${args.crop.join(', ')}])` : ''}. Camera: ${cam.name} (${cam.purpose}). The first picture is the reference (left) beside the view (right); the second is the view.`, ...notes]
322
+ lines.push(
323
+ '| measure | value |',
324
+ '|---|---|',
325
+ `| colour verdict | ${c.verdict} |`,
326
+ `| palette deltaE | ${fmt(c.paletteDeltaE, 1)} |`,
327
+ `| mean L* | ${signed(c.deltaMeanL)} against the reference |`,
328
+ `| contrast, chroma | x${fmt(c.contrastRatio)}, x${fmt(c.chromaRatio)} |`,
329
+ `| warmth b*, tint a* | ${signed(c.warmthDelta)}, ${signed(c.tintDelta)} |`,
330
+ `| L* layout correlation | ${fmt(st.correlation, 3)} |`,
331
+ `| horizon offset | ${st.horizonDelta === null ? 'no horizon in one of them' : signed(st.horizonDelta, 3)} |`,
332
+ `| where the eye goes, offset | ${fmt(st.centroidDelta, 3)} |`,
333
+ `| edges, detail | x${fmt(st.edgeRatio)}, x${fmt(st.detailRatio)} |`,
334
+ `| distance (0 is the same picture) | ${fmt(metrics.distance, 3)} |`,
335
+ )
336
+ lines.push(metrics.flags.length ? `Flags: ${metrics.flags.join(', ')}. Fix what a flag names before anything finer.` : 'No gross flag: judge the rest by eye in the side by side.')
337
+ if (args.palette?.length) {
338
+ // The accents too: a lamp the brief names is too small to be a palette entry.
339
+ const seen = referenceFacts(fitAspect(shotPic, art.width / art.height), { lettering: false })
340
+ const own = [...seen.palette, ...seen.accents].map((p) => ({ hex: p.hex, lab: hexToLab(p.hex) }))
341
+ lines.push("The brief's palette, nearest colour in the view (deltaE2000; 10 or less reads as that colour):")
342
+ for (const hex of args.palette) {
343
+ let best = null
344
+ for (const p of own) {
345
+ const d = deltaE2000(hexToLab(hex), p.lab)
346
+ if (!best || d < best.d) best = { d, hex: p.hex }
347
+ }
348
+ lines.push(`- ${hex}: ${best ? `${fmt(best.d, 1)} (${best.hex})` : 'none'}`)
349
+ }
350
+ }
351
+ if (saved) lines.push(`Saved: ${saved.compare} and ${saved.shot}.`)
352
+ return {
353
+ text: lines.join('\n'),
354
+ images: [
355
+ { data: png.toString('base64'), mime: 'image/png' },
356
+ { data: s.image.data, mime: s.image.mime ?? 'image/jpeg' },
357
+ ],
358
+ verifies: 'view',
359
+ // For the gate, which reads the numbers rather than the text.
360
+ metrics,
361
+ saved,
362
+ }
363
+ },
364
+ }
365
+
366
+ export const TOOLS = [nwReference, nwCompare]
@@ -0,0 +1,118 @@
1
+ // The session's own transcripts, read as they grow, for what a request
2
+ // really used. The SDK keeps one JSON line per message under the project's
3
+ // session folder (shared.mjs sessionDir): <session>.jsonl for the main agent
4
+ // and <session>/subagents/agent-*.jsonl for each helper, each assistant line
5
+ // with the call's usage. The stream the host reads shows a helper's calls
6
+ // late or not at all, and its assistant messages carry a usage that is not
7
+ // final; these lines carry the final one (2026-10-20: the running total
8
+ // missed the helpers and most of the thinking). Only what this request adds
9
+ // is read: a resumed session's files are marked where they end before it
10
+ // starts.
11
+
12
+ import fs from 'node:fs'
13
+ import fsp from 'node:fs/promises'
14
+ import path from 'node:path'
15
+
16
+ const NEWLINE = 0x0a
17
+
18
+ /**
19
+ * @param {{ dir: string, onLine: (line: object, file: string, helper: boolean) => void }} options
20
+ * dir: the project's session folder; onLine gets every JSON line, helper
21
+ * true for a helper's transcript.
22
+ */
23
+ export function createTranscriptTap({ dir, onLine }) {
24
+ let sessionId = null
25
+ const offsets = new Map() // file -> bytes already read
26
+ const rest = new Map() // file -> the bytes of a line not finished yet
27
+ let reading = null
28
+
29
+ const files = () => {
30
+ if (!sessionId) return []
31
+ const helpers = path.join(dir, sessionId, 'subagents')
32
+ let names = []
33
+ try {
34
+ names = fs.readdirSync(helpers).filter((n) => n.endsWith('.jsonl'))
35
+ } catch {
36
+ // no helper has run in this session
37
+ }
38
+ return [path.join(dir, `${sessionId}.jsonl`), ...names.map((n) => path.join(helpers, n))]
39
+ }
40
+
41
+ async function readFile(file) {
42
+ let size
43
+ try {
44
+ size = (await fsp.stat(file)).size
45
+ } catch {
46
+ return
47
+ }
48
+ const from = offsets.get(file) ?? 0
49
+ if (size < from) {
50
+ // Rewritten under us: what is there now was read already, or is not this request's.
51
+ offsets.set(file, size)
52
+ rest.delete(file)
53
+ return
54
+ }
55
+ if (size === from) return
56
+ const handle = await fsp.open(file, 'r')
57
+ let chunk
58
+ try {
59
+ chunk = Buffer.alloc(size - from)
60
+ const { bytesRead } = await handle.read(chunk, 0, chunk.length, from)
61
+ chunk = chunk.subarray(0, bytesRead)
62
+ } finally {
63
+ await handle.close()
64
+ }
65
+ offsets.set(file, from + chunk.length)
66
+ // Split on newline bytes, so a character cut at the chunk's end waits whole.
67
+ const bytes = rest.has(file) ? Buffer.concat([rest.get(file), chunk]) : chunk
68
+ const end = bytes.lastIndexOf(NEWLINE)
69
+ if (end < 0) {
70
+ rest.set(file, bytes)
71
+ return
72
+ }
73
+ rest.set(file, bytes.subarray(end + 1))
74
+ const helper = file.includes(`${path.sep}subagents${path.sep}`)
75
+ for (const line of bytes.subarray(0, end).toString('utf8').split('\n')) {
76
+ if (!line.trim()) continue
77
+ let parsed
78
+ try {
79
+ parsed = JSON.parse(line)
80
+ } catch {
81
+ continue
82
+ }
83
+ try {
84
+ onLine(parsed, file, helper)
85
+ } catch {
86
+ // one odd line never stops the count
87
+ }
88
+ }
89
+ }
90
+
91
+ return {
92
+ /** Before a resumed session goes on: its files are marked where they end. */
93
+ mark(id) {
94
+ if (typeof id !== 'string' || !id) return
95
+ sessionId = id
96
+ for (const file of files()) {
97
+ try {
98
+ offsets.set(file, fs.statSync(file).size)
99
+ } catch {
100
+ // not there yet: all of it will be this request's
101
+ }
102
+ }
103
+ },
104
+ /** The session's id, once the CLI says it. */
105
+ follow(id) {
106
+ if (typeof id === 'string' && id && !sessionId) sessionId = id
107
+ },
108
+ /** Reads what the files gained since the last time; one read at a time. */
109
+ poll() {
110
+ reading ??= (async () => {
111
+ for (const file of files()) await readFile(file).catch(() => {})
112
+ })().finally(() => {
113
+ reading = null
114
+ })
115
+ return reading
116
+ },
117
+ }
118
+ }