@neta-art/cohub-cli 10.19.0 → 10.20.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.
@@ -0,0 +1,19 @@
1
+ import type { BoardDocument, 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
+ withImages: boolean;
18
+ }): Promise<BoardProfile>;
19
+ export declare function boardProfileHints(document: BoardDocument, profile: BoardGpuProfile): string[];
@@ -0,0 +1,53 @@
1
+ import { gpuResources, loadBoardDocument } from "./board-export.js";
2
+ import { openBoardGpu } from "./board-gpu/daemon.js";
3
+ import { findBoardGpuBrowser } from "./board-gpu/index.js";
4
+ import { BOARD_EXPORT_IMAGE_MEMORY_MIB } from "./board-export-resources.js";
5
+ import { buildBoardScene, planBoardExport } from "./board-kernel.js";
6
+ import { settleBoardDocument } from "./board-media.js";
7
+ const LARGE_OWNER = 4000;
8
+ const LARGE_STATE = 512 * 512;
9
+ const MANY_EFFECTS = 16;
10
+ export async function profileBoard(options) {
11
+ const browser = findBoardGpuBrowser();
12
+ if (!browser)
13
+ throw new Error("Profiling needs Chrome, Chromium or Edge. Install one, or set COHUB_CHROME to its path.");
14
+ const document = await settleBoardDocument(options.spaceId, (await loadBoardDocument(options.spaceId, options.target)).document);
15
+ if (options.animation && !document.animations[options.animation])
16
+ throw new Error(`Animation ${options.animation} does not exist.`);
17
+ const plan = planBoardExport({ scene: buildBoardScene(document), region: options.region, scale: 1, padding: 0 });
18
+ if (!plan)
19
+ throw new Error("Nothing to profile: the region contains no items.");
20
+ const scale = Math.min(options.size.width / plan.world.width, options.size.height / plan.world.height);
21
+ const gpu = await openBoardGpu(gpuResources(options.spaceId, document), { browser });
22
+ try {
23
+ await gpu.init({ document, animation: options.animation ?? null, theme: "dark" });
24
+ const profile = await gpu.profile({
25
+ time: options.time,
26
+ region: options.region,
27
+ scale,
28
+ frames: options.frames,
29
+ withImages: options.withImages,
30
+ imageMemory: BOARD_EXPORT_IMAGE_MEMORY_MIB * 1024 ** 2,
31
+ });
32
+ return { ...profile, hints: boardProfileHints(document, profile) };
33
+ }
34
+ finally {
35
+ await gpu.close();
36
+ }
37
+ }
38
+ export function boardProfileHints(document, profile) {
39
+ const hints = [];
40
+ const share = (ms) => (profile.frame.p50 > 0 ? ms / profile.frame.p50 : 0);
41
+ for (const owner of profile.owners) {
42
+ if (owner.filter === "always" && share(owner.ms) > 0.1)
43
+ 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.`);
44
+ const item = document.items[owner.id];
45
+ if (item && "size" in item && Math.max(item.size.width, item.size.height) > LARGE_OWNER)
46
+ 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.`);
47
+ if (owner.state && owner.state.width * owner.state.height > LARGE_STATE)
48
+ 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.`);
49
+ }
50
+ if (profile.effects > MANY_EFFECTS)
51
+ 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.`);
52
+ return hints;
53
+ }
@@ -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;
@@ -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, 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,7 +84,7 @@ 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
89
  async function run(harness, steps) {
84
90
  for (const step of steps) {
@@ -90,6 +96,8 @@ async function run(harness, steps) {
90
96
  await harness.tap(step.tap, step.input);
91
97
  else if ("drag" in step)
92
98
  await harness.drag(step.drag, step.input);
99
+ else if ("move" in step)
100
+ await harness.move(step.move, step.input);
93
101
  else if ("pointer" in step)
94
102
  await harness.pointer(step.pointer, step.at, step.input);
95
103
  else if ("key" in step) {
@@ -102,7 +110,7 @@ async function run(harness, steps) {
102
110
  }
103
111
  async function checkShaders(shaders, spaceId, document) {
104
112
  const browser = findBoardGpuBrowser();
105
- const exporter = browser ? await launchBoardGpuExporter(gpuResources(spaceId, document), { browser }).catch(() => null) : null;
113
+ const exporter = browser ? await openBoardGpu(gpuResources(spaceId, document), { browser }).catch(() => null) : null;
106
114
  if (exporter) {
107
115
  try {
108
116
  return { errors: await exporter.compile(shaders), compiled: true };
@@ -156,11 +164,13 @@ export async function runBoardSimulation(options) {
156
164
  ...(checked ? { shaders: { count: shaders.length, compiled: checked.compiled } } : {}),
157
165
  };
158
166
  if (options.image && shown) {
167
+ const gpu = checked?.compiled && !Object.keys(checked.errors).length && shaderShown(harness.document, shaders, options.image.region);
159
168
  const exported = await runBoardExport({
160
169
  spaceId: options.spaceId,
161
170
  target: options.target,
162
- document: shown.document,
163
- ...(shown.scripts ? { scripts: shown.scripts } : {}),
171
+ ...(gpu
172
+ ? { document: harness.document, snapshots: await harness.snapshot(), renderer: "gpu" }
173
+ : { document: shown.document, ...(shown.scripts ? { scripts: shown.scripts } : {}) }),
164
174
  region: options.image.region,
165
175
  scale: options.image.scale,
166
176
  theme: options.image.theme,
@@ -179,3 +189,13 @@ export async function runBoardSimulation(options) {
179
189
  renderer.destroy();
180
190
  }
181
191
  }
192
+ function shaderShown(document, shaders, region) {
193
+ const scene = buildBoardScene(document);
194
+ const plan = planBoardExport({ scene, region, scale: 1 });
195
+ if (!plan)
196
+ return false;
197
+ return shaders.some(({ id }) => {
198
+ const item = scene.get(id);
199
+ return !item || rectsIntersect(itemBounds(item.frame), plan.world);
200
+ });
201
+ }
@@ -97,6 +97,26 @@ function showPlayback(playback) {
97
97
  { key: "timeScale", label: "Speed" },
98
98
  ]);
99
99
  }
100
+ const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
101
+ async function runExportTask(boards, options) {
102
+ try {
103
+ const command = ["cohub", ...process.argv.slice(2).filter((arg) => arg !== "--async")].map(shellQuote).join(" ");
104
+ const { taskRunId } = await createClient().space(await resolveSpace(boards)).runCommand({ command });
105
+ if (jsonRequested(options))
106
+ return outJson({ taskRunId, command });
107
+ ok(`Exporting as Task ${taskRunId}`);
108
+ console.log(` Follow it with: cohub tasks get ${taskRunId}`);
109
+ }
110
+ catch (cause) {
111
+ handleHttp(cause);
112
+ }
113
+ }
114
+ function parseSize(value) {
115
+ const size = /^(\d+)x(\d+)$/.exec(value);
116
+ if (!size?.[1] || !size[2])
117
+ throw new Error("--size must be widthxheight, e.g. 1600x900.");
118
+ return { width: parseNumber(size[1], "width", { min: 1, max: 8192 }), height: parseNumber(size[2], "height", { min: 1, max: 8192 }) };
119
+ }
100
120
  /** One region flag at most: being told to pick beats guessing which one wins. */
101
121
  function parseExportRegion(options) {
102
122
  const chosen = [options.camera && "--camera", options.frame && "--frame", options.items && "--items", options.rect && "--rect"].filter(Boolean);
@@ -167,14 +187,21 @@ function registerExportCommand(boards) {
167
187
  .option("--image-memory <mib>", "Decoded image memory budget in MiB", String(BOARD_EXPORT_IMAGE_MEMORY_MIB))
168
188
  .option("--no-images", "Draw placeholders instead of downloading images")
169
189
  .option("--renderer <renderer>", "auto draws in Node and uses local Chrome for shaders; canvas or gpu forces one", "auto")
170
- .option("--force", "Replace existing output files"))
190
+ .option("--force", "Replace existing output files")
191
+ .option("--async", "Run as a Task in the Space's sandbox and return at once; paths are Space paths"))
171
192
  .addHelpText("after", `
193
+ Shaders draw in a shared headless Chrome that stays up a few minutes between calls;
194
+ Boards without shaders never start it. Set COHUB_BOARD_GPU_DAEMON=0 to start one per call.
195
+
172
196
  Examples:
173
197
  cohub boards export plan.board -o plan.png
198
+ cohub boards export plan.board --animation intro --at 0:20s:40ms -o intro.mp4 --async
174
199
  cohub boards export plan.board --frame s2 -o slide-2.png
175
200
  cohub boards export plan.board --animation lecture --at 4.5s -o moment.png
176
201
  cohub boards export plan.board --animation lecture --at 0:6s:40ms -o frames/%04d.png`)
177
202
  .action(async (target, options) => {
203
+ if (options.async)
204
+ return runExportTask(boards, options);
178
205
  const controller = new AbortController();
179
206
  const cancel = () => controller.abort(new Error("Export cancelled."));
180
207
  process.once("SIGINT", cancel);
@@ -185,10 +212,7 @@ Examples:
185
212
  if (options.camera) {
186
213
  if (!options.animation || !times)
187
214
  throw new Error("--camera needs --animation and --at.");
188
- const size = /^(\d+)x(\d+)$/.exec(options.size ?? "1600x900");
189
- if (!size?.[1] || !size[2])
190
- throw new Error("--size must be widthxheight, e.g. 1600x900.");
191
- camera = { width: parseNumber(size[1], "width", { min: 1, max: 8192 }), height: parseNumber(size[2], "height", { min: 1, max: 8192 }) };
215
+ camera = parseSize(options.size ?? "1600x900");
192
216
  }
193
217
  const progress = (completed, total) => {
194
218
  if (!jsonRequested(options) && (completed === total || completed % 30 === 0))
@@ -373,6 +397,59 @@ Examples:
373
397
  }
374
398
  });
375
399
  }
400
+ function registerProfileCommand(boards) {
401
+ withJson(boards.command("profile <board>")
402
+ .description("Measure what a Board costs to draw, shader by shader, and say what to change")
403
+ .option("--at <time>", "A moment of --animation, or a script time without one", "2s")
404
+ .option("--animation <id>", "Animation --at refers to")
405
+ .option("--frame <item-id>", "Profile one frame")
406
+ .option("--items <ids>", "Profile comma-separated item ids")
407
+ .option("--rect <rect>", "Profile a world rect as x,y,width,height")
408
+ .option("--size <widthxheight>", "Fit the region into this many pixels, like a screen", "1600x900")
409
+ .option("--frames <count>", "Frames to time per measurement", "5")
410
+ .option("--no-images", "Draw placeholders instead of downloading images"))
411
+ .addHelpText("after", `
412
+ Draws in a headless Chrome; without a GPU it uses software WebGL, so compare the
413
+ numbers with each other rather than with a real display.
414
+
415
+ Examples:
416
+ cohub boards profile demo.board
417
+ cohub boards profile demo.board --rect 0,0,1600,900 --at 8s --json`)
418
+ .action(async (target, options) => {
419
+ try {
420
+ const { profileBoard } = await import("../board-profile.js");
421
+ const profile = await profileBoard({
422
+ spaceId: await resolveSpace(boards),
423
+ target,
424
+ time: parseBoardTime(options.at ?? "2s", "--at"),
425
+ ...(options.animation ? { animation: options.animation } : {}),
426
+ region: parseExportRegion(options),
427
+ size: parseSize(options.size ?? "1600x900"),
428
+ frames: parseNumber(options.frames ?? "5", "--frames", { min: 3, max: 240, integer: true }),
429
+ withImages: options.images !== false,
430
+ });
431
+ if (jsonRequested(options))
432
+ return outJson(profile);
433
+ const ms = (value) => `${value.toFixed(1)} ms`;
434
+ ok(`${profile.width}×${profile.height} in ${profile.renderer}: ${ms(profile.frame.p50)} a frame (p95 ${ms(profile.frame.p95)}), ${profile.items} items`);
435
+ for (const owner of profile.owners) {
436
+ const traits = [owner.filter !== "none" && `filter ${owner.filter}`, owner.sprites && `${owner.sprites} sprites`, owner.state && `state ${owner.state.width}×${owner.state.height}`].filter(Boolean);
437
+ console.log(` ${owner.id.padEnd(24)} ${ms(owner.ms).padStart(9)}${traits.length ? ` ${traits.join(", ")}` : ""}`);
438
+ }
439
+ for (const hint of profile.hints)
440
+ console.log(` ! ${hint}`);
441
+ }
442
+ catch (cause) {
443
+ handleHttp(cause);
444
+ }
445
+ });
446
+ boards.command("gpu-daemon", { hidden: true })
447
+ .requiredOption("--browser <path>")
448
+ .action(async (options) => {
449
+ const { serveBoardGpu } = await import("../board-gpu/daemon.js");
450
+ await serveBoardGpu(options.browser);
451
+ });
452
+ }
376
453
  // ─── Commands ────────────────────────────────────────────────────────────────
377
454
  export function registerBoards(program) {
378
455
  const boards = program
@@ -611,6 +688,7 @@ Presets: ${BOARD_PRESET_NAMES.join(", ")}
611
688
  registerBoardExampleCommands(boards);
612
689
  registerExportCommand(boards);
613
690
  registerSimulateCommand(boards);
691
+ registerProfileCommand(boards);
614
692
  registerBoardAuthoringCommands(boards);
615
693
  registerPlaybackCommands(boards);
616
694
  withJson(boards.command("watch <board>")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neta-art/cohub-cli",
3
- "version": "10.19.0",
3
+ "version": "10.20.0",
4
4
  "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -18,7 +18,7 @@
18
18
  "NOTICE"
19
19
  ],
20
20
  "dependencies": {
21
- "@neta-art/cohub": "13.10.0",
21
+ "@neta-art/cohub": "13.11.0",
22
22
  "@neta-art/generation": "0.2.15",
23
23
  "commander": "^15.0.0",
24
24
  "sharp": "^0.35.4",