@neta-art/cohub-cli 10.19.0 → 10.21.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.
@@ -2,6 +2,7 @@ import { type BoardMediaSpan, type BoardMediaState } from "@neta-art/cohub/board
2
2
  export declare function createBoardMediaFiles(spaceId: string, dir: string, signal?: AbortSignal): {
3
3
  path(src: string, kind: "video" | "audio"): Promise<string>;
4
4
  audible(src: string, kind: "video" | "audio"): Promise<boolean>;
5
+ duration(src: string): Promise<number>;
5
6
  };
6
7
  export type BoardMediaFiles = ReturnType<typeof createBoardMediaFiles>;
7
8
  export declare function createBoardVideoFrames(files: BoardMediaFiles, dir: string, options: {
@@ -22,6 +22,7 @@ async function ffmpeg(args, signal) {
22
22
  export function createBoardMediaFiles(spaceId, dir, signal) {
23
23
  const files = new Map();
24
24
  const audible = new Map();
25
+ const durations = new Map();
25
26
  const client = createClient();
26
27
  return {
27
28
  path(src, kind) {
@@ -53,6 +54,17 @@ export function createBoardMediaFiles(spaceId, dir, signal) {
53
54
  }
54
55
  return pending;
55
56
  },
57
+ async duration(src) {
58
+ let pending = durations.get(src);
59
+ if (!pending) {
60
+ pending = this.path(src, "video").then(async (path) => {
61
+ const { stdout } = await execFile("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", path], { signal });
62
+ return Math.max(0, Number(stdout.trim()) * 1000 || 0);
63
+ }).catch(() => 0);
64
+ durations.set(src, pending);
65
+ }
66
+ return pending;
67
+ },
56
68
  };
57
69
  }
58
70
  export function createBoardVideoFrames(files, dir, options) {
@@ -85,6 +97,11 @@ export function createBoardVideoFrames(files, dir, options) {
85
97
  }
86
98
  return {
87
99
  async frame(state, rate, edge) {
100
+ if (state.loop) {
101
+ const duration = await files.duration(state.src);
102
+ if (duration > 0)
103
+ state = { ...state, time: state.time % duration };
104
+ }
88
105
  const current = chunks.get(state.id);
89
106
  let file = current?.src === state.src ? lookup(current, state.time, edge) : null;
90
107
  if (!file)
@@ -0,0 +1,21 @@
1
+ import { type BoardDocument, type BoardExportRegion } from "@neta-art/cohub/board";
2
+ import { type BoardGpuProfile } from "./board-gpu/index.js";
3
+ export type BoardProfile = BoardGpuProfile & {
4
+ hints: string[];
5
+ };
6
+ export declare function profileBoard(options: {
7
+ spaceId: string;
8
+ target: string;
9
+ time: number;
10
+ animation?: string;
11
+ region: BoardExportRegion;
12
+ size: {
13
+ width: number;
14
+ height: number;
15
+ };
16
+ frames: number;
17
+ rounds: number;
18
+ budgetMs: number;
19
+ withImages: boolean;
20
+ }): Promise<BoardProfile>;
21
+ export declare function boardProfileHints(document: BoardDocument, profile: BoardGpuProfile): string[];
@@ -0,0 +1,67 @@
1
+ import { boardModelFormat } from "@neta-art/cohub/board";
2
+ import { gpuResources, loadBoardDocument } from "./board-export.js";
3
+ import { openBoardGpu } from "./board-gpu/daemon.js";
4
+ import { findBoardGpuBrowser } from "./board-gpu/index.js";
5
+ import { BOARD_EXPORT_IMAGE_MEMORY_MIB } from "./board-export-resources.js";
6
+ import { buildBoardScene, planBoardExport } from "./board-kernel.js";
7
+ import { settleBoardDocument } from "./board-media.js";
8
+ const LARGE_OWNER = 4000;
9
+ const LARGE_STATE = 512 * 512;
10
+ const MANY_EFFECTS = 16;
11
+ const LARGE_MODEL = 8 * 1024 ** 2;
12
+ export async function profileBoard(options) {
13
+ const browser = findBoardGpuBrowser();
14
+ if (!browser)
15
+ throw new Error("Profiling needs Chrome, Chromium or Edge. Install one, or set COHUB_CHROME to its path.");
16
+ const document = await settleBoardDocument(options.spaceId, (await loadBoardDocument(options.spaceId, options.target)).document);
17
+ if (options.animation && !document.animations[options.animation])
18
+ throw new Error(`Animation ${options.animation} does not exist.`);
19
+ const plan = planBoardExport({ scene: buildBoardScene(document), region: options.region, scale: 1, padding: 0 });
20
+ if (!plan)
21
+ throw new Error("Nothing to profile: the region contains no items.");
22
+ const scale = Math.min(options.size.width / plan.world.width, options.size.height / plan.world.height);
23
+ const gpu = await openBoardGpu(gpuResources(options.spaceId, document), { browser });
24
+ try {
25
+ await gpu.init({ document, animation: options.animation ?? null, theme: "dark" });
26
+ const profile = await gpu.profile({
27
+ time: options.time,
28
+ region: options.region,
29
+ scale,
30
+ frames: options.frames,
31
+ rounds: options.rounds,
32
+ budgetMs: options.budgetMs,
33
+ withImages: options.withImages,
34
+ imageMemory: BOARD_EXPORT_IMAGE_MEMORY_MIB * 1024 ** 2,
35
+ });
36
+ return { ...profile, hints: boardProfileHints(document, profile) };
37
+ }
38
+ finally {
39
+ await gpu.close();
40
+ }
41
+ }
42
+ export function boardProfileHints(document, profile) {
43
+ const hints = [];
44
+ const share = (ms) => (profile.frame.p50 > 0 ? ms / profile.frame.p50 : 0);
45
+ for (const owner of profile.owners) {
46
+ if (owner.filter === "always" && share(owner.ms) > 0.1)
47
+ hints.push(`${owner.id} redraws everything under it through a filter every frame; name its filter passes and turn them on with ctx.passes() only while they show.`);
48
+ const item = document.items[owner.id];
49
+ if (item && "size" in item && Math.max(item.size.width, item.size.height) > LARGE_OWNER)
50
+ hints.push(`${owner.id} is larger than any view, so its shaders never leave the screen; a Board script, or shaders on the smaller items, draw only what shows.`);
51
+ if (owner.boxes && share(owner.ms) > 0.1)
52
+ hints.push(`${owner.id} shades every pixel of its box; if its picture changes only every few units, as pixel art or a map does, give the pass texel so it shades once per texel.`);
53
+ if (owner.state && owner.state.width * owner.state.height > LARGE_STATE)
54
+ hints.push(`${owner.id} steps a ${owner.state.width}×${owner.state.height} state 60 times a second and replays it from the start in exports; keep it as small as reads well.`);
55
+ }
56
+ const noisy = profile.owners.filter((owner) => owner.ms > 1 && owner.range[1] - owner.range[0] > owner.ms);
57
+ if (noisy.length)
58
+ hints.push(`${noisy.map((owner) => owner.id).join(", ")} varied more between rounds than ${noisy.length === 1 ? "its" : "their"} median; compare the frame time, or raise --rounds.`);
59
+ for (const [id, item] of Object.entries(document.items)) {
60
+ const size = item.type === "file" && boardModelFormat(item.props.src, item.props.snapshot?.mimeType) ? (item.props.snapshot?.size ?? 0) : 0;
61
+ if (size > LARGE_MODEL)
62
+ hints.push(`${id} is a ${(size / 1024 ** 2).toFixed(0)} MB model every viewer downloads for its card, and phones skip past 16 MB; compress it (meshopt or Draco geometry, KTX2 textures).`);
63
+ }
64
+ if (profile.effects > MANY_EFFECTS)
65
+ hints.push(`${profile.effects} items draw with shadows, blurs or color filters, each in its own offscreen pass; present them only while they change, and drop neutral values.`);
66
+ return hints;
67
+ }
@@ -1,6 +1,6 @@
1
1
  import type { BoardExportRegion, BoardThemeId } from "@neta-art/cohub/board";
2
2
  import type { BoardNodeExportFormat } from "@neta-art/cohub/board/export/node";
3
- import type { BoardScriptHarnessPointer } from "@neta-art/cohub/board/testing";
3
+ import type { BoardScriptHarnessPointer, BoardScriptHarnessPress } from "@neta-art/cohub/board/testing";
4
4
  declare const TOOLS: readonly ["select", "hand", "text", "shape", "draw", "arrow", "frame"];
5
5
  type Point = {
6
6
  x: number;
@@ -16,6 +16,9 @@ export type BoardSimulationStep = {
16
16
  } | {
17
17
  drag: Point[];
18
18
  input: BoardScriptHarnessPointer;
19
+ } | {
20
+ move: Point[];
21
+ input: BoardScriptHarnessPointer;
19
22
  } | {
20
23
  pointer: "down" | "move" | "up";
21
24
  at: Point;
@@ -26,11 +29,16 @@ export type BoardSimulationStep = {
26
29
  select: string[];
27
30
  };
28
31
  export declare function parseBoardSimulationSteps(value: unknown): BoardSimulationStep[];
32
+ export type BoardSimulationPress = BoardScriptHarnessPress & {
33
+ step: number;
34
+ };
29
35
  export type BoardSimulationResult = {
30
36
  time: number;
31
37
  commits: number;
32
38
  changes: Record<string, unknown>;
33
39
  errors: Record<string, string>;
40
+ presses: BoardSimulationPress[];
41
+ warnings: string[];
34
42
  shaders?: {
35
43
  count: number;
36
44
  compiled: boolean;
@@ -41,11 +49,13 @@ export type BoardSimulationResult = {
41
49
  height: number;
42
50
  };
43
51
  };
52
+ export declare const BOARD_SIMULATION_TIMEOUT_MS = 120000;
44
53
  export declare function runBoardSimulation(options: {
45
54
  spaceId: string;
46
55
  target: string;
47
56
  steps: readonly BoardSimulationStep[];
48
57
  leader: boolean;
58
+ timeoutMs?: number;
49
59
  image?: {
50
60
  region: BoardExportRegion;
51
61
  scale: number;
@@ -1,7 +1,8 @@
1
1
  import { diffMergePatch } from "@neta-art/cohub/board";
2
2
  import { gpuResources, loadBoardDocument, readSpaceFileBytes, resolveBundledFonts, runBoardExport } from "./board-export.js";
3
- import { findBoardGpuBrowser, launchBoardGpuExporter } from "./board-gpu/index.js";
4
- import { boardScriptAttachments, boardShaderParameters, checkBoardShader, createBoardScriptHarness, createNodeBoardRenderer } from "./board-kernel.js";
3
+ import { openBoardGpu } from "./board-gpu/daemon.js";
4
+ import { findBoardGpuBrowser } from "./board-gpu/index.js";
5
+ import { boardScriptAttachments, boardShaderParameters, buildBoardScene, checkBoardShader, createBoardScriptHarness, createNodeBoardRenderer, describeBoardScriptLanes, itemBounds, planBoardExport, rectsIntersect, } from "./board-kernel.js";
5
6
  import { settleBoardDocument } from "./board-media.js";
6
7
  import { parseBoardTime } from "./board-time.js";
7
8
  import { createClient } from "./client.js";
@@ -35,7 +36,7 @@ export function parseBoardSimulationSteps(value) {
35
36
  if (value.length > MAX_STEPS)
36
37
  throw new Error(`steps exceed the limit of ${MAX_STEPS}`);
37
38
  const steps = value.map(parseStep);
38
- const elapsed = steps.reduce((total, step) => total + ("wait" in step ? step.wait : "tap" in step ? 2 * FRAME_MS : "drag" in step ? (step.drag.length + 1) * FRAME_MS : "pointer" in step ? FRAME_MS : 0), 0);
39
+ const elapsed = steps.reduce((total, step) => total + ("wait" in step ? step.wait : "tap" in step ? 2 * FRAME_MS : "drag" in step ? (step.drag.length + 1) * FRAME_MS : "move" in step ? step.move.length * FRAME_MS : "pointer" in step ? FRAME_MS : 0), 0);
39
40
  if (elapsed > MAX_TIME_MS)
40
41
  throw new Error(`steps exceed ${MAX_TIME_MS / 60_000} minutes of simulated time`);
41
42
  return steps;
@@ -63,6 +64,11 @@ function parseStep(entry, index) {
63
64
  throw new Error(`${name}.drag must list at least two points`);
64
65
  return { drag: step.drag.map((entry, at) => point(entry, `${name}.drag[${at}]`)), input: pointerInput(step, name) };
65
66
  }
67
+ if ("move" in step) {
68
+ if (!Array.isArray(step.move) || !step.move.length)
69
+ throw new Error(`${name}.move must list points`);
70
+ return { move: step.move.map((entry, at) => point(entry, `${name}.move[${at}]`)), input: pointerInput(step, name) };
71
+ }
66
72
  if ("pointer" in step) {
67
73
  if (step.pointer !== "down" && step.pointer !== "move" && step.pointer !== "up")
68
74
  throw new Error(`${name}.pointer must be down, move or up`);
@@ -78,31 +84,51 @@ function parseStep(entry, index) {
78
84
  throw new Error(`${name}.select must list item ids`);
79
85
  return { select: step.select };
80
86
  }
81
- throw new Error(`${name} must be one of wait, tool, tap, drag, pointer, key or select`);
87
+ throw new Error(`${name} must be one of wait, tool, tap, drag, move, pointer, key or select`);
82
88
  }
83
- async function run(harness, steps) {
84
- for (const step of steps) {
89
+ async function run(harness, steps, progress, presses) {
90
+ for (const [index, step] of steps.entries()) {
91
+ progress.step = index;
92
+ let press = null;
85
93
  if ("wait" in step)
86
94
  await harness.advance(step.wait);
87
95
  else if ("tool" in step)
88
96
  harness.tool = step.tool;
89
97
  else if ("tap" in step)
90
- await harness.tap(step.tap, step.input);
98
+ press = await harness.tap(step.tap, step.input);
91
99
  else if ("drag" in step)
92
- await harness.drag(step.drag, step.input);
100
+ press = await harness.drag(step.drag, step.input);
101
+ else if ("move" in step)
102
+ await harness.move(step.move, step.input);
93
103
  else if ("pointer" in step)
94
- await harness.pointer(step.pointer, step.at, step.input);
104
+ press = await harness.pointer(step.pointer, step.at, step.input);
95
105
  else if ("key" in step) {
96
106
  await harness.key("keydown", step.key);
97
107
  await harness.key("keyup", step.key);
98
108
  }
99
109
  else
100
110
  await harness.select(step.select);
111
+ if (press)
112
+ presses.push({ step: index, ...press });
101
113
  }
102
114
  }
115
+ export const BOARD_SIMULATION_TIMEOUT_MS = 120_000;
116
+ function shadersOf(harness) {
117
+ const errors = {};
118
+ const shaders = [];
119
+ for (const { id } of boardScriptAttachments(harness.document)) {
120
+ const message = harness.error(id);
121
+ const output = harness.output(id);
122
+ if (message)
123
+ errors[id] = message;
124
+ else if (output?.shader)
125
+ shaders.push({ id, shader: output.shader, ...(output.parameters ? { parameters: output.parameters } : {}) });
126
+ }
127
+ return { shaders, errors };
128
+ }
103
129
  async function checkShaders(shaders, spaceId, document) {
104
130
  const browser = findBoardGpuBrowser();
105
- const exporter = browser ? await launchBoardGpuExporter(gpuResources(spaceId, document), { browser }).catch(() => null) : null;
131
+ const exporter = browser ? await openBoardGpu(gpuResources(spaceId, document), { browser }).catch(() => null) : null;
106
132
  if (exporter) {
107
133
  try {
108
134
  return { errors: await exporter.compile(shaders), compiled: true };
@@ -126,41 +152,78 @@ export async function runBoardSimulation(options) {
126
152
  const client = createClient();
127
153
  const document = await settleBoardDocument(options.spaceId, (await loadBoardDocument(options.spaceId, options.target)).document);
128
154
  const renderer = await createNodeBoardRenderer({ fonts: resolveBundledFonts() });
129
- const harness = await createBoardScriptHarness({
130
- document,
131
- renderer,
132
- leader: options.leader,
133
- readModule: async (path) => new TextDecoder().decode((await readSpaceFileBytes(client, options.spaceId, path)).bytes),
155
+ const progress = { step: -1, phase: "starting the scripts" };
156
+ let harness = null;
157
+ let timer;
158
+ const timeoutMs = options.timeoutMs ?? BOARD_SIMULATION_TIMEOUT_MS;
159
+ let stopped = false;
160
+ const expired = new Promise((_resolve, reject) => {
161
+ timer = setTimeout(() => {
162
+ stopped = true;
163
+ const busy = harness ? describeBoardScriptLanes(harness.status()) : [];
164
+ const at = harness ? ` at ${Math.round(harness.time)} ms of simulated time` : "";
165
+ const step = progress.step >= 0 ? `, step ${progress.step + 1} of ${options.steps.length}` : "";
166
+ reject(new Error([
167
+ `The simulation did not finish in ${timeoutMs / 1000} s${at}${step}, while ${progress.phase}.`,
168
+ ...busy.map((line) => ` ${line}`),
169
+ ...(!busy.length && progress.phase === "running the steps" ? [" No script was busy: the scripts keep handing each other work, or a step waits on something else."] : []),
170
+ ].join("\n")));
171
+ }, timeoutMs);
134
172
  });
135
- try {
136
- await run(harness, options.steps);
137
- await harness.flush();
138
- const shown = options.image ? await harness.shown(options.image.scale) : null;
139
- const errors = {};
140
- const shaders = [];
141
- for (const { id } of boardScriptAttachments(harness.document)) {
142
- const message = harness.error(id);
143
- const output = harness.output(id);
144
- if (message)
145
- errors[id] = message;
146
- else if (output?.shader)
147
- shaders.push({ id, shader: output.shader, ...(output.parameters ? { parameters: output.parameters } : {}) });
173
+ const work = async () => {
174
+ harness = await createBoardScriptHarness({
175
+ document,
176
+ renderer,
177
+ leader: options.leader,
178
+ readModule: async (path) => new TextDecoder().decode((await readSpaceFileBytes(client, options.spaceId, path)).bytes),
179
+ });
180
+ const current = harness;
181
+ if (stopped) {
182
+ current.destroy();
183
+ throw new Error("The simulation timed out.");
148
184
  }
149
- const checked = shaders.length ? await checkShaders(shaders, options.spaceId, harness.document) : null;
150
- Object.assign(errors, checked?.errors);
185
+ progress.phase = "compiling shaders";
186
+ const initial = shadersOf(current);
187
+ const early = initial.shaders.length ? await checkShaders(initial.shaders, options.spaceId, current.document) : null;
188
+ const presses = [];
189
+ if (early && Object.keys(early.errors).length) {
190
+ return {
191
+ time: Math.round(current.time), commits: 0, changes: {}, errors: { ...initial.errors, ...early.errors }, presses,
192
+ warnings: ["Stopped before the steps: fix the shader errors first."],
193
+ shaders: { count: initial.shaders.length, compiled: early.compiled },
194
+ };
195
+ }
196
+ progress.phase = "running the steps";
197
+ await run(current, options.steps, progress, presses);
198
+ progress.phase = "settling the scripts";
199
+ await current.flush();
200
+ const { shaders, errors } = shadersOf(current);
201
+ const checked = new Set(initial.shaders.map(({ id }) => id));
202
+ const added = shaders.filter(({ id }) => !checked.has(id));
203
+ progress.phase = "compiling shaders";
204
+ const late = added.length ? await checkShaders(added, options.spaceId, current.document) : null;
205
+ Object.assign(errors, late?.errors);
206
+ const compiled = (early?.compiled ?? true) && (late?.compiled ?? true);
207
+ const warnings = [...current.emitFailures].map(([id, message]) => `${id}: ${message}`);
151
208
  const result = {
152
- time: Math.round(harness.time),
153
- commits: harness.commits.length,
154
- changes: diffMergePatch(document, harness.document) ?? {},
209
+ time: Math.round(current.time),
210
+ commits: current.commits.length,
211
+ changes: diffMergePatch(document, current.document) ?? {},
155
212
  errors,
156
- ...(checked ? { shaders: { count: shaders.length, compiled: checked.compiled } } : {}),
213
+ presses,
214
+ warnings,
215
+ ...(shaders.length ? { shaders: { count: shaders.length, compiled } } : {}),
157
216
  };
158
- if (options.image && shown) {
217
+ if (options.image) {
218
+ progress.phase = "rendering the image";
219
+ const shown = await current.shown(options.image.scale);
220
+ const gpu = compiled && shaders.length > 0 && !Object.keys(errors).length && shaderShown(current.document, shaders, options.image.region);
159
221
  const exported = await runBoardExport({
160
222
  spaceId: options.spaceId,
161
223
  target: options.target,
162
- document: shown.document,
163
- ...(shown.scripts ? { scripts: shown.scripts } : {}),
224
+ ...(gpu
225
+ ? { document: current.document, snapshots: await current.snapshot(), renderer: "gpu" }
226
+ : { document: shown.document, ...(shown.scripts ? { scripts: shown.scripts } : {}) }),
164
227
  region: options.image.region,
165
228
  scale: options.image.scale,
166
229
  theme: options.image.theme,
@@ -171,11 +234,26 @@ export async function runBoardSimulation(options) {
171
234
  const frame = exported?.frames[0];
172
235
  if (frame)
173
236
  result.image = { bytes: frame.bytes, width: frame.width, height: frame.height };
237
+ warnings.push(...(exported?.warnings ?? []));
174
238
  }
175
239
  return result;
240
+ };
241
+ try {
242
+ return await Promise.race([work(), expired]);
176
243
  }
177
244
  finally {
178
- harness.destroy();
245
+ clearTimeout(timer);
246
+ harness?.destroy();
179
247
  renderer.destroy();
180
248
  }
181
249
  }
250
+ function shaderShown(document, shaders, region) {
251
+ const scene = buildBoardScene(document);
252
+ const plan = planBoardExport({ scene, region, scale: 1 });
253
+ if (!plan)
254
+ return false;
255
+ return shaders.some(({ id }) => {
256
+ const item = scene.get(id);
257
+ return !item || rectsIntersect(itemBounds(item.frame), plan.world);
258
+ });
259
+ }
@@ -0,0 +1 @@
1
+ {"commit":"b2e3ef6"}