@iwsdk/vite-plugin-dev 1.1.0 → 1.2.0-rc.1

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.
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { createHash, randomUUID, randomBytes, timingSafeEqual } from 'crypto';
1
+ import { createHash, randomUUID, randomBytes, timingSafeEqual, X509Certificate } from 'crypto';
2
2
  import * as fs from 'fs';
3
3
  import { existsSync, realpathSync, readFileSync, mkdirSync, writeFileSync, renameSync, unlinkSync, linkSync, rmdirSync, rmSync, readdirSync, statSync, lstatSync as lstatSync$1 } from 'fs';
4
4
  import * as os from 'os';
@@ -1150,6 +1150,7 @@ const TIMED_RUNTIME_METHODS = new Set([
1150
1150
  'set_select_value',
1151
1151
  ]);
1152
1152
  const BROWSER_RUNTIME_METHODS = new Set([
1153
+ 'browser_filmstrip',
1153
1154
  'browser_interact',
1154
1155
  'browser_profile',
1155
1156
  'browser_set_muted',
@@ -2238,6 +2239,34 @@ const ALL_RUNTIME_MCP_TOOLS = [
2238
2239
  additionalProperties: false,
2239
2240
  },
2240
2241
  },
2242
+ {
2243
+ name: 'browser_filmstrip',
2244
+ description: 'Capture a frame-accurate sequence of the application: pause the ECS, capture the current frame, then step `every` simulation frames and capture again until `count` frames are taken, and return one contact-sheet image (screenshotPath) with each panel labeled by its frame offset. Restores the previous pause state. Use it to see motion (physics, animation, locomotion) independently of how fast the browser renders.',
2245
+ inputSchema: {
2246
+ type: 'object',
2247
+ properties: {
2248
+ count: {
2249
+ type: 'integer',
2250
+ minimum: 2,
2251
+ maximum: 12,
2252
+ description: 'Frames to capture, including the current one. Defaults to 6.',
2253
+ },
2254
+ every: {
2255
+ type: 'integer',
2256
+ minimum: 1,
2257
+ maximum: 120,
2258
+ description: 'Simulation frames to step between captures (fixed 1/72 s timestep). Defaults to 5.',
2259
+ },
2260
+ format: {
2261
+ type: 'string',
2262
+ enum: ['png', 'jpeg'],
2263
+ description: 'Image format of the contact sheet. Defaults to png.',
2264
+ },
2265
+ },
2266
+ required: [],
2267
+ additionalProperties: false,
2268
+ },
2269
+ },
2241
2270
  {
2242
2271
  name: 'browser_snapshot',
2243
2272
  description: 'Inspect the current application as a compact accessibility-first list of interactive elements and canvas regions. Use returned refs with browser_interact.',
@@ -4262,6 +4291,7 @@ const RUNTIME_TOOL_TO_METHOD = {
4262
4291
  xr_cancel_sequence: 'cancel_sequence',
4263
4292
  xr_list_targets: 'list_targets',
4264
4293
  browser_screenshot: 'screenshot',
4294
+ browser_filmstrip: 'browser_filmstrip',
4265
4295
  browser_snapshot: 'browser_snapshot',
4266
4296
  browser_interact: 'browser_interact',
4267
4297
  browser_profile: 'browser_profile',
@@ -4287,6 +4317,7 @@ const ALL_RUNTIME_CLI_PATHS = {
4287
4317
  xr_get_gamepad_state: ['xr', 'get-gamepad-state'],
4288
4318
  xr_set_gamepad_state: ['xr', 'set-gamepad-state'],
4289
4319
  browser_screenshot: ['browser', 'screenshot'],
4320
+ browser_filmstrip: ['browser', 'filmstrip'],
4290
4321
  browser_snapshot: ['browser', 'snapshot'],
4291
4322
  browser_interact: ['browser', 'interact'],
4292
4323
  browser_profile: ['browser', 'profile'],
@@ -4400,6 +4431,7 @@ const EDITOR_TARGET_MCP_TOOL_NAME_SET = new Set([
4400
4431
  ]);
4401
4432
  const HOST_BROWSER_MCP_TOOL_NAME_SET = new Set([
4402
4433
  'browser_screenshot',
4434
+ 'browser_filmstrip',
4403
4435
  'browser_snapshot',
4404
4436
  'browser_interact',
4405
4437
  'browser_profile',
@@ -22720,6 +22752,388 @@ class ManagedBrowserConsole {
22720
22752
  }
22721
22753
  }
22722
22754
 
22755
+ /**
22756
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
22757
+ *
22758
+ * This source code is licensed under the MIT license found in the
22759
+ * LICENSE file in the root directory of this source tree.
22760
+ */
22761
+ const FILMSTRIP_DEFAULT_COUNT = 6;
22762
+ const FILMSTRIP_DEFAULT_EVERY = 5;
22763
+ const FILMSTRIP_MAX_COUNT = 12;
22764
+ const FILMSTRIP_MAX_EVERY = 120;
22765
+ const FILMSTRIP_MAX_COLUMNS = 4;
22766
+ function normalizeFilmstripOptions(options = {}) {
22767
+ const integer = (name, value, fallback, min, max) => {
22768
+ if (value == null) {
22769
+ return fallback;
22770
+ }
22771
+ if (typeof value !== 'number' ||
22772
+ !Number.isInteger(value) ||
22773
+ value < min ||
22774
+ value > max) {
22775
+ throw Object.assign(new Error(`browser_filmstrip ${name} must be an integer from ${min} to ${max}`), { retryable: false });
22776
+ }
22777
+ return value;
22778
+ };
22779
+ const format = options.format ?? 'png';
22780
+ if (format !== 'png' && format !== 'jpeg') {
22781
+ throw Object.assign(new Error('browser_filmstrip format must be png or jpeg'), { retryable: false });
22782
+ }
22783
+ return {
22784
+ count: integer('count', options.count, FILMSTRIP_DEFAULT_COUNT, 2, FILMSTRIP_MAX_COUNT),
22785
+ every: integer('every', options.every, FILMSTRIP_DEFAULT_EVERY, 1, FILMSTRIP_MAX_EVERY),
22786
+ format,
22787
+ };
22788
+ }
22789
+ /**
22790
+ * `ecs_step` advances one simulation step per animation frame, and the managed
22791
+ * browser animates at most 60 frames per second, so a filmstrip needs at least
22792
+ * this long however fast the app renders.
22793
+ */
22794
+ function filmstripMinimumDurationMs(options) {
22795
+ return Math.ceil((((options.count - 1) * options.every) / 60) * 1000);
22796
+ }
22797
+ function filmstripOutOfTime(detail) {
22798
+ return Object.assign(new Error(`browser_filmstrip ran out of active command time before it could continue (${detail})`), { retryable: false });
22799
+ }
22800
+ /** Settle with `work`, or reject once `budgetMs` passes. */
22801
+ async function withinBudget(work, budgetMs, detail) {
22802
+ let timer;
22803
+ try {
22804
+ return await Promise.race([
22805
+ work,
22806
+ new Promise((_, reject) => {
22807
+ timer = setTimeout(() => reject(filmstripOutOfTime(detail)), Math.max(0, budgetMs));
22808
+ }),
22809
+ ]);
22810
+ }
22811
+ finally {
22812
+ clearTimeout(timer);
22813
+ }
22814
+ }
22815
+ /**
22816
+ * Pause, capture the current frame, then step and capture until `count`
22817
+ * frames are taken. The caller's pause state is restored however this ends:
22818
+ * ECS resumes only if this call paused it.
22819
+ *
22820
+ * Every step and capture runs against the remaining command budget, so a
22821
+ * sequence that cannot finish fails with a clear error before the managed
22822
+ * browser's command coordinator would time the whole browser out.
22823
+ */
22824
+ async function runFilmstrip(ecs, options, capture, budget) {
22825
+ const minimumMs = filmstripMinimumDurationMs(options);
22826
+ if (minimumMs > budget()) {
22827
+ throw Object.assign(new Error(`browser_filmstrip needs at least ${(minimumMs / 1000).toFixed(1)} s ` +
22828
+ `to step ${(options.count - 1) * options.every} frames at 60 fps, more than one ` +
22829
+ 'command allows. Lower count or every.'), { retryable: false });
22830
+ }
22831
+ const wasPaused = await ecs.isPaused();
22832
+ if (wasPaused === null) {
22833
+ // Guessing would risk resuming an ECS the user paused on purpose.
22834
+ throw Object.assign(new Error('browser_filmstrip needs an @iwsdk/core that reports ECS pause state ' +
22835
+ '(MCPRuntime.ecsPaused). Update @iwsdk/core to match @iwsdk/vite-plugin-dev.'), { retryable: false });
22836
+ }
22837
+ // Set before pausing, so a pause that takes effect and then rejects is
22838
+ // still undone.
22839
+ const pausedHere = !wasPaused;
22840
+ let failure;
22841
+ try {
22842
+ if (pausedHere) {
22843
+ // Read the budget first: it throws once spent, and must do so before
22844
+ // the next ECS command starts.
22845
+ const pauseBudgetMs = budget();
22846
+ await withinBudget(ecs.pause(), pauseBudgetMs, 'pausing ECS');
22847
+ }
22848
+ const frames = [];
22849
+ for (let index = 0; index < options.count; index++) {
22850
+ const offset = index * options.every;
22851
+ if (index > 0) {
22852
+ const stepBudgetMs = budget();
22853
+ await withinBudget(ecs.step(options.every), stepBudgetMs, `stepping to frame +${offset}`);
22854
+ }
22855
+ frames.push({ offset, capture: await capture(offset) });
22856
+ }
22857
+ return frames;
22858
+ }
22859
+ catch (error) {
22860
+ failure = error;
22861
+ throw error;
22862
+ }
22863
+ finally {
22864
+ if (pausedHere) {
22865
+ try {
22866
+ await ecs.resume();
22867
+ }
22868
+ catch (resumeError) {
22869
+ if (failure === undefined) {
22870
+ throw Object.assign(new Error(`browser_filmstrip captured every frame but could not resume ECS: ${errorText(resumeError)}`), { cause: resumeError, retryable: false });
22871
+ }
22872
+ // Keep the original failure; record that ECS may still be paused.
22873
+ if (failure instanceof Error) {
22874
+ failure.message += ` (ECS may still be paused: resume failed with ${errorText(resumeError)})`;
22875
+ failure.resumeError =
22876
+ resumeError;
22877
+ }
22878
+ }
22879
+ }
22880
+ }
22881
+ }
22882
+ function errorText(error) {
22883
+ return error instanceof Error ? error.message : String(error);
22884
+ }
22885
+ /** ECS controls through the page runtime's MCP dispatch. */
22886
+ function pageFilmstripEcsControl(frame) {
22887
+ const dispatch = (method, params = {}) => frame.evaluate(async ({ method, params }) => {
22888
+ const runtime = window.FRAMEWORK_MCP_RUNTIME;
22889
+ if (typeof runtime?.dispatch !== 'function') {
22890
+ throw new Error('browser_filmstrip needs an IWSDK app runtime (FRAMEWORK_MCP_RUNTIME)');
22891
+ }
22892
+ return runtime.dispatch(method, params);
22893
+ }, { method, params });
22894
+ return {
22895
+ isPaused: () => frame.evaluate(() => {
22896
+ const paused = window.FRAMEWORK_MCP_RUNTIME?.ecsPaused;
22897
+ return typeof paused === 'boolean' ? paused : null;
22898
+ }),
22899
+ pause: async () => {
22900
+ await dispatch('ecs_pause');
22901
+ },
22902
+ step: async (frames) => {
22903
+ await dispatch('ecs_step', { count: frames });
22904
+ },
22905
+ resume: async () => {
22906
+ await dispatch('ecs_resume');
22907
+ },
22908
+ };
22909
+ }
22910
+ /**
22911
+ * Lay `count` panels of `source` aspect out in at most four columns, balanced
22912
+ * across rows (6 panels make 3×2, not 4+2), scaled down so the whole sheet
22913
+ * fits `bounds`.
22914
+ */
22915
+ function contactSheetLayout(count, source, bounds) {
22916
+ const rows = Math.ceil(count / FILMSTRIP_MAX_COLUMNS);
22917
+ const columns = Math.ceil(count / rows);
22918
+ const scale = Math.min(1, bounds.width / (columns * source.width), bounds.height / (rows * source.height));
22919
+ const panelWidth = Math.max(1, Math.floor(source.width * scale));
22920
+ const panelHeight = Math.max(1, Math.floor(source.height * scale));
22921
+ return {
22922
+ columns,
22923
+ rows,
22924
+ panelWidth,
22925
+ panelHeight,
22926
+ width: columns * panelWidth,
22927
+ height: rows * panelHeight,
22928
+ };
22929
+ }
22930
+ function offsetLabel(offset, panelHeight) {
22931
+ const fontSize = Math.max(12, Math.round(panelHeight * 0.06));
22932
+ const padding = Math.round(fontSize * 0.45);
22933
+ const text = `+${offset}`;
22934
+ const width = Math.round(text.length * fontSize * 0.62 + padding * 2);
22935
+ const height = Math.round(fontSize + padding * 1.6);
22936
+ return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">` +
22937
+ `<rect width="${width}" height="${height}" rx="${Math.round(padding * 0.8)}" fill="#000000" fill-opacity="0.72"/>` +
22938
+ `<text x="${padding}" y="${Math.round(padding * 0.8 + fontSize * 0.85)}" font-family="DejaVu Sans Mono, monospace" font-size="${fontSize}" font-weight="700" fill="#ffffff">${text}</text>` +
22939
+ `</svg>`);
22940
+ }
22941
+ /**
22942
+ * Stitch captures into one contact sheet, each panel labeled with its
22943
+ * simulation frame offset (`+0`, `+5`, ...).
22944
+ */
22945
+ async function composeContactSheet(panels, bounds, format) {
22946
+ const first = await sharp(panels[0].bytes).metadata();
22947
+ const layout = contactSheetLayout(panels.length, { width: first.width ?? 1, height: first.height ?? 1 }, bounds);
22948
+ const layers = await Promise.all(panels.map(async ({ offset, bytes }, index) => {
22949
+ const left = (index % layout.columns) * layout.panelWidth;
22950
+ const top = Math.floor(index / layout.columns) * layout.panelHeight;
22951
+ const resized = await sharp(bytes)
22952
+ .resize(layout.panelWidth, layout.panelHeight, { fit: 'fill' })
22953
+ .png()
22954
+ .toBuffer();
22955
+ const margin = Math.max(4, Math.round(layout.panelHeight * 0.02));
22956
+ return [
22957
+ { input: resized, left, top },
22958
+ {
22959
+ input: offsetLabel(offset, layout.panelHeight),
22960
+ left: left + margin,
22961
+ top: top + margin,
22962
+ },
22963
+ ];
22964
+ }));
22965
+ const sheet = sharp({
22966
+ create: {
22967
+ background: { alpha: 1, b: 0, g: 0, r: 0 },
22968
+ channels: 4,
22969
+ height: layout.height,
22970
+ width: layout.width,
22971
+ },
22972
+ }).composite(layers.flat());
22973
+ const bytes = await (format === 'jpeg'
22974
+ ? sheet.jpeg({ quality: 90 }).toBuffer()
22975
+ : sheet.png().toBuffer());
22976
+ return { bytes, layout };
22977
+ }
22978
+
22979
+ /**
22980
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
22981
+ *
22982
+ * This source code is licensed under the MIT license found in the
22983
+ * LICENSE file in the root directory of this source tree.
22984
+ */
22985
+ const warnedRenderModeOverrides = new Set();
22986
+ /**
22987
+ * Resolve the render mode for a managed browser session. Headed sessions are
22988
+ * always continuous because a person is watching them. `IWSDK_DEV_RENDER_MODE`
22989
+ * (`continuous` or `on-demand`, case-insensitive) overrides the headless
22990
+ * default; any other value is reported once and ignored.
22991
+ */
22992
+ function resolveManagedRenderMode(headless, override = process.env.IWSDK_DEV_RENDER_MODE, warn = console.warn) {
22993
+ if (!headless) {
22994
+ return 'continuous';
22995
+ }
22996
+ const normalized = override?.trim().toLowerCase();
22997
+ if (!normalized) {
22998
+ return 'on-demand';
22999
+ }
23000
+ if (normalized === 'continuous' || normalized === 'on-demand') {
23001
+ return normalized;
23002
+ }
23003
+ if (!warnedRenderModeOverrides.has(normalized)) {
23004
+ warnedRenderModeOverrides.add(normalized);
23005
+ warn(`[IWSDK Dev] Ignoring IWSDK_DEV_RENDER_MODE=${JSON.stringify(override)}: expected "continuous" or "on-demand". Headless sessions render on demand.`);
23006
+ }
23007
+ return 'on-demand';
23008
+ }
23009
+ /**
23010
+ * Draw `frames` fresh frames in the application frame and wait, at most
23011
+ * `timeoutMs`, until they have been handed to the compositor. Resolves
23012
+ * `'timeout'` when they were not drawn in time, for example because an
23013
+ * uncaught error stopped the app's render loop. Apps that do not expose
23014
+ * `requestRender` (non-IWSDK runtimes, older @iwsdk/core) are left alone and
23015
+ * resolve `'unsupported'`. Rejects when the app's `requestRender` does.
23016
+ */
23017
+ async function requestApplicationRender(frame, frames = 1, timeoutMs = 10000) {
23018
+ return frame.evaluate(({ frames, timeoutMs, }) => {
23019
+ const runtime = window.FRAMEWORK_MCP_RUNTIME;
23020
+ if (typeof runtime?.requestRender !== 'function') {
23021
+ return 'unsupported';
23022
+ }
23023
+ let timer;
23024
+ return Promise.race([
23025
+ Promise.resolve(runtime.requestRender(frames)).then(() => 'drawn'),
23026
+ new Promise((resolve) => {
23027
+ timer = setTimeout(() => resolve('timeout'), timeoutMs);
23028
+ }),
23029
+ ]).finally(() => clearTimeout(timer));
23030
+ }, { frames, timeoutMs });
23031
+ }
23032
+ /**
23033
+ * Whether a frame the application draws stays on its canvas until the next
23034
+ * draw. False under the emulator's default per-frame clear in immersive
23035
+ * sessions; the injected runtime turns that clear off for on-demand sessions
23036
+ * and sets `__IWSDK_KEEPS_DRAWN_FRAMES`.
23037
+ */
23038
+ async function applicationKeepsDrawnFrames(frame) {
23039
+ return frame
23040
+ .evaluate(() => window.__IWSDK_KEEPS_DRAWN_FRAMES === true)
23041
+ .catch(() => false);
23042
+ }
23043
+ /**
23044
+ * Start drawing every frame in the application until the returned function is
23045
+ * called. Holds are counted by the runtime, so overlapping holds (a capture
23046
+ * during a profile) cannot end each other early. Returns `null` when the app
23047
+ * does not support render holds (non-IWSDK runtimes, older @iwsdk/core); such
23048
+ * apps draw continuously anyway.
23049
+ */
23050
+ async function acquireApplicationRenderHold(frame) {
23051
+ return frame.evaluate(() => {
23052
+ const runtime = window.FRAMEWORK_MCP_RUNTIME;
23053
+ return typeof runtime?.acquireRenderHold === 'function'
23054
+ ? runtime.acquireRenderHold()
23055
+ : null;
23056
+ });
23057
+ }
23058
+ /**
23059
+ * Release a hold from {@link acquireApplicationRenderHold}. A reload drops
23060
+ * every hold with the page, so a missing runtime is not an error.
23061
+ */
23062
+ async function releaseApplicationRenderHold(frame, id) {
23063
+ if (id == null) {
23064
+ return;
23065
+ }
23066
+ await frame
23067
+ .evaluate((id) => {
23068
+ window.FRAMEWORK_MCP_RUNTIME?.releaseRenderHold?.(id);
23069
+ }, id)
23070
+ .catch(() => { });
23071
+ }
23072
+ /**
23073
+ * Run `fn` with the application drawing every frame. Profiling, runtime
23074
+ * evidence and pixel captures under the emulator's per-frame clear need real
23075
+ * frames, which on-demand rendering would otherwise skip.
23076
+ */
23077
+ async function withApplicationRenderHold(frame, fn) {
23078
+ const id = await acquireApplicationRenderHold(frame);
23079
+ try {
23080
+ return await fn();
23081
+ }
23082
+ finally {
23083
+ await releaseApplicationRenderHold(frame, id);
23084
+ }
23085
+ }
23086
+ /** Longest a capture waits for its fresh frame before capturing anyway. */
23087
+ const MAX_RENDER_REQUEST_MS = 10000;
23088
+ /**
23089
+ * Capture pixels from an application that may render on demand. When drawn
23090
+ * frames persist, one fresh frame is requested and captured. Otherwise (the
23091
+ * emulator clears the canvas every immersive frame) rendering is held for the
23092
+ * whole capture so the frame on screen is always current. The render request
23093
+ * gets a bounded share of `timeoutMs`; `capture` receives what is left.
23094
+ */
23095
+ async function captureFreshApplicationFrame(frame, timeoutMs, capture) {
23096
+ const startedAt = Date.now();
23097
+ const renderBudgetMs = Math.max(1, Math.min(timeoutMs, MAX_RENDER_REQUEST_MS));
23098
+ const remaining = () => Math.max(1, timeoutMs - (Date.now() - startedAt));
23099
+ if (await applicationKeepsDrawnFrames(frame)) {
23100
+ await requestApplicationRender(frame, 1, renderBudgetMs);
23101
+ return capture(remaining());
23102
+ }
23103
+ return withApplicationRenderHold(frame, async () => {
23104
+ await requestApplicationRender(frame, 1, renderBudgetMs);
23105
+ return capture(remaining());
23106
+ });
23107
+ }
23108
+ /**
23109
+ * Create a {@link RenderHoldTracker}. Evidence collection waits for a
23110
+ * reloaded runtime to appear; a hold requested before it exists comes back
23111
+ * `null` and must be requested again once it does.
23112
+ */
23113
+ function createRenderHoldTracker() {
23114
+ let current = null;
23115
+ return {
23116
+ async ensure(frame) {
23117
+ if (current?.frame === frame && current.id != null) {
23118
+ return;
23119
+ }
23120
+ if (current != null && current.frame !== frame) {
23121
+ await releaseApplicationRenderHold(current.frame, current.id);
23122
+ }
23123
+ const id = await acquireApplicationRenderHold(frame).catch(() => null);
23124
+ current = { frame, id };
23125
+ },
23126
+ async release() {
23127
+ if (current == null) {
23128
+ return;
23129
+ }
23130
+ const { frame, id } = current;
23131
+ current = null;
23132
+ await releaseApplicationRenderHold(frame, id);
23133
+ },
23134
+ };
23135
+ }
23136
+
22723
23137
  /**
22724
23138
  * Copyright (c) Meta Platforms, Inc. and affiliates.
22725
23139
  *
@@ -22999,6 +23413,10 @@ class ManagedInteractionSurface {
22999
23413
  captureRuntimeScreenshot(options = {}) {
23000
23414
  return withRuntimeView(this.options.page, () => this.captureApplicationImage(options, this.options.getRemainingOperationTimeMs('browser_screenshot')), (error) => this.options.onRestoreError('browser_screenshot', error));
23001
23415
  }
23416
+ captureRuntimeFilmstrip(options = {}) {
23417
+ const normalized = normalizeFilmstripOptions(options);
23418
+ return withRuntimeView(this.options.page, () => this.captureApplicationFilmstrip(normalized), (error) => this.options.onRestoreError('browser_filmstrip', error));
23419
+ }
23002
23420
  snapshotApplication(request = {}) {
23003
23421
  return collectApplicationSnapshot(this.options.page, this.snapshotRecipes, request, this.options.getRemainingOperationTimeMs('browser_snapshot'));
23004
23422
  }
@@ -23014,9 +23432,40 @@ class ManagedInteractionSurface {
23014
23432
  }
23015
23433
  return withRuntimeView(this.options.page, () => this.runInteractionBatch(request), (error) => this.options.onRestoreError('browser_interact', error));
23016
23434
  }
23435
+ async captureApplicationFilmstrip(options) {
23436
+ const { getRemainingOperationTimeMs, page, screenshotSize } = this.options;
23437
+ const frame = await resolveApplicationFrame(page);
23438
+ // Panels are captured losslessly; only the sheet uses the requested format.
23439
+ // Every step and capture re-reads the active budget, so a sequence that
23440
+ // cannot fit fails with the budget error instead of overrunning the command.
23441
+ const budget = () => getRemainingOperationTimeMs('browser_filmstrip');
23442
+ const frames = await runFilmstrip(pageFilmstripEcsControl(frame), options, async () => (await this.captureApplicationImage({ format: 'png' }, budget())).bytes, budget);
23443
+ const { bytes, layout } = await composeContactSheet(frames.map(({ offset, capture }) => ({ offset, bytes: capture })), { width: screenshotSize.width * 2, height: screenshotSize.height * 2 }, options.format);
23444
+ return {
23445
+ bytes,
23446
+ metadata: {
23447
+ ...(await getApplicationMetadata(page)),
23448
+ columns: layout.columns,
23449
+ count: options.count,
23450
+ every: options.every,
23451
+ frameOffsets: frames.map(({ offset }) => offset),
23452
+ height: layout.height,
23453
+ mimeType: options.format === 'jpeg' ? 'image/jpeg' : 'image/png',
23454
+ panelHeight: layout.panelHeight,
23455
+ panelWidth: layout.panelWidth,
23456
+ rows: layout.rows,
23457
+ width: layout.width,
23458
+ },
23459
+ };
23460
+ }
23017
23461
  async captureApplicationImage(options, timeoutMs) {
23462
+ const frame = await resolveApplicationFrame(this.options.page);
23463
+ // An on-demand app has nothing current on its canvas: draw a fresh frame
23464
+ // (holding rendering where the emulator would clear it) before capturing.
23465
+ return captureFreshApplicationFrame(frame, timeoutMs, (remainingMs) => this.captureRenderedApplicationImage(frame, options, remainingMs));
23466
+ }
23467
+ async captureRenderedApplicationImage(frame, options, timeoutMs) {
23018
23468
  const { page, screenshotSize } = this.options;
23019
- const frame = await resolveApplicationFrame(page);
23020
23469
  const format = options.format ?? 'png';
23021
23470
  const quality = Math.min(100, Math.max(20, options.quality ?? 90));
23022
23471
  const screenshotOptions = format === 'jpeg'
@@ -24454,7 +24903,7 @@ async function openManagedChromium({ browserAutomation, headless, launchUrl, man
24454
24903
  throw error;
24455
24904
  }
24456
24905
  }
24457
- async function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context, managedWorkspaceToken, page, readiness, waitForRuntime = true, signal, traceMcp, url, }) {
24906
+ async function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context, managedWorkspaceToken, page, readiness, renderMode = 'continuous', waitForRuntime = true, signal, traceMcp, url, }) {
24458
24907
  throwIfLaunchAborted(signal);
24459
24908
  if (managedWorkspaceToken != null) {
24460
24909
  await page.addInitScript((queryName) => {
@@ -24479,11 +24928,12 @@ async function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context
24479
24928
  console.error(`[unhandledrejection] ${text}`);
24480
24929
  });
24481
24930
  });
24482
- await page.addInitScript((traceEnabled) => {
24931
+ await page.addInitScript(({ renderMode, traceEnabled }) => {
24483
24932
  window.__IWER_MCP_MANAGED = true;
24484
24933
  window.__IWSDK_MCP_TRACE = traceEnabled;
24485
24934
  window.__IWSDK_MANAGED_BROWSER_TARGET = true;
24486
- }, traceMcp);
24935
+ window.__IWSDK_RENDER_MODE = renderMode;
24936
+ }, { renderMode, traceEnabled: traceMcp });
24487
24937
  try {
24488
24938
  await page.goto(url, { waitUntil: 'commit' });
24489
24939
  }
@@ -24533,6 +24983,51 @@ async function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context
24533
24983
  * This source code is licensed under the MIT license found in the
24534
24984
  * LICENSE file in the root directory of this source tree.
24535
24985
  */
24986
+ /**
24987
+ * Frames an app that renders on demand draws under the profile's render hold
24988
+ * before sampling starts. Such an app may not have drawn for a long time, or
24989
+ * ever in its current view (just after entering XR, say), and its first
24990
+ * frames pay one-time costs (shader programs, texture uploads) that are not
24991
+ * the frame cost being measured. The browser keeps frames in flight, so that
24992
+ * cost can surface a frame or two later. In cold headless sessions of the VR
24993
+ * starter, one warm-up frame left a 1.6 s interval in the first profile and
24994
+ * two left a 1.5 s stall before its first sample; three kept both out.
24995
+ * Runtime publish evidence skips two frames (`warmupFrames: 2`) after its
24996
+ * readiness loop has already drawn one, so it also lets three go by.
24997
+ */
24998
+ const PROFILE_WARMUP_FRAMES = 3;
24999
+ /**
25000
+ * Longest a profile start waits for its warm-up frames: as long as runtime
25001
+ * evidence waits for a frame. An app whose render loop has stopped never
25002
+ * draws them.
25003
+ */
25004
+ const MAX_PROFILE_WARMUP_MS = 5000;
25005
+ /**
25006
+ * Shortest warm-up a profile start attempts. Drawing three frames and seeing
25007
+ * the last one presented takes four frames: 67 ms at 60 Hz for an app with
25008
+ * cheap frames, but about 0.5 s for the VR starter on SwiftShader (headless,
25009
+ * no GPU), whose frames take 117-133 ms. With less time a healthy app could
25010
+ * miss them and the timeout would blame its render loop, so the profile
25011
+ * skips the warm-up instead and says so.
25012
+ */
25013
+ const MIN_PROFILE_WARMUP_MS = 1000;
25014
+ /**
25015
+ * Active command time a profile start keeps after its warm-up, to install the
25016
+ * sampler, attach CDP and start a trace, or to undo them and restore the
25017
+ * workspace view when the start fails.
25018
+ */
25019
+ const PROFILE_START_RESERVE_MS = WORKSPACE_RESTORE_RESERVE_MS + 2500;
25020
+ /**
25021
+ * Animation frames in a row in which the app drew nothing while the profile
25022
+ * held rendering, from which the profile reports `render-loop-stopped`. Under
25023
+ * the hold the app draws every frame; entering or leaving XR skips a frame or
25024
+ * two. A longer run means its render loop stopped (one uncaught error in a
25025
+ * frame stops it), before the profile or during it, or stalled, and the
25026
+ * samples of that run are the requestAnimationFrame intervals of a page that
25027
+ * did not draw. The longest run counts, so a stall that ends before the
25028
+ * profile stops is reported too.
25029
+ */
25030
+ const RENDER_STOPPED_FRAMES = 30;
24536
25031
  const MAX_TRACE_ARTIFACT_BYTES = 100 * 1024 * 1024;
24537
25032
  const MAX_PROFILE_SAMPLES = 10000;
24538
25033
  const MAX_PROFILE_INTERRUPTIONS = 100;
@@ -24582,7 +25077,8 @@ class BrowserProfiler {
24582
25077
  const mode = request.mode ?? 'interaction';
24583
25078
  const profileId = randomUUID();
24584
25079
  const maxDurationMs = Math.min(60000, Math.max(1000, request.maxDurationMs ?? 30000));
24585
- await startProfileInFrame(frame, mode);
25080
+ const startInterruptions = await startProfileInFrame(frame, mode, Math.min(MAX_PROFILE_WARMUP_MS, this.coordinator.getRemainingActiveTimeMs() -
25081
+ PROFILE_START_RESERVE_MS));
24586
25082
  cdp = await this.context.newCDPSession(this.page);
24587
25083
  await cdp.send('Performance.enable').catch(() => { });
24588
25084
  let tracePath = null;
@@ -24625,6 +25121,9 @@ class BrowserProfiler {
24625
25121
  tracePath,
24626
25122
  visibility,
24627
25123
  };
25124
+ for (const interruption of startInterruptions) {
25125
+ this.record(profile, interruption);
25126
+ }
24628
25127
  this.activeProfile = profile;
24629
25128
  this.lastResult = null;
24630
25129
  return this.describe(profile, 'started');
@@ -24665,6 +25164,7 @@ class BrowserProfiler {
24665
25164
  environment: undefined,
24666
25165
  eventDurations: [],
24667
25166
  frameTimes: [],
25167
+ longestUndrawnRun: null,
24668
25168
  longTasks: [],
24669
25169
  marks: [],
24670
25170
  visibilityEvents: [],
@@ -24681,6 +25181,14 @@ class BrowserProfiler {
24681
25181
  this.recordError(profile, 'page-profile-unavailable', error);
24682
25182
  return emptySamples();
24683
25183
  });
25184
+ if (samples.longestUndrawnRun != null &&
25185
+ samples.longestUndrawnRun >= RENDER_STOPPED_FRAMES) {
25186
+ this.record(profile, {
25187
+ at: Date.now(),
25188
+ kind: 'render-loop-stopped',
25189
+ value: `the app drew nothing for ${samples.longestUndrawnRun} animation frames in a row while the profile held rendering`,
25190
+ });
25191
+ }
24684
25192
  const browserMetricsResponse = await profile.cdp
24685
25193
  .send('Performance.getMetrics')
24686
25194
  .catch(() => ({ metrics: [] }));
@@ -24851,16 +25359,95 @@ class BrowserProfiler {
24851
25359
  });
24852
25360
  }
24853
25361
  }
24854
- async function startProfileInFrame(frame, mode) {
25362
+ /**
25363
+ * Hold rendering, warm up an on-demand app, and install the page sampler.
25364
+ * Returns interruptions for the profile to record: warm-up frames that were
25365
+ * not drawn within `warmupBudgetMs`, or a warm-up that was skipped because
25366
+ * that budget was too short or the app's render mode could not be read.
25367
+ */
25368
+ async function startProfileInFrame(frame, mode, warmupBudgetMs) {
25369
+ const interruptions = [];
25370
+ // A profile measures real frame cost, so draw every frame while it runs.
25371
+ // The hold id lives on the page next to the profile state it belongs to.
25372
+ // The same call reads the app's render mode, so the warm-up is decided on
25373
+ // the page that holds rendering. If the page goes away, the call fails and
25374
+ // so does the start.
25375
+ const renderHold = await acquireApplicationRenderHold(frame);
25376
+ const renderMode = await frame.evaluate((id) => {
25377
+ const runtimeWindow = window;
25378
+ const runtime = runtimeWindow.FRAMEWORK_MCP_RUNTIME;
25379
+ runtime?.releaseRenderHold?.(runtimeWindow.__IWSDK_PROFILE_RENDER_HOLD);
25380
+ runtimeWindow.__IWSDK_PROFILE_RENDER_HOLD = id;
25381
+ try {
25382
+ const mode = runtime?.renderMode;
25383
+ return mode === 'continuous' || mode === 'on-demand' ? mode : null;
25384
+ }
25385
+ catch (error) {
25386
+ return {
25387
+ error: error instanceof Error ? error.message : String(error),
25388
+ };
25389
+ }
25390
+ }, renderHold);
25391
+ if (renderMode != null && typeof renderMode === 'object') {
25392
+ // Reading the mode threw. The app may render on demand, so the samples
25393
+ // may include first-draw costs.
25394
+ interruptions.push({
25395
+ at: Date.now(),
25396
+ kind: 'render-mode-unavailable',
25397
+ value: `${PROFILE_WARMUP_FRAMES} warm-up frames skipped: could not read the app's render mode: ${renderMode.error}`,
25398
+ });
25399
+ }
25400
+ else if (renderMode === 'on-demand') {
25401
+ // Only an app that renders on demand needs warming up. One that draws
25402
+ // continuously (headed sessions, IWSDK_DEV_RENDER_MODE=continuous, apps
25403
+ // without render modes) paid its first-draw costs long ago.
25404
+ if (warmupBudgetMs < MIN_PROFILE_WARMUP_MS) {
25405
+ // Too little of the command's time is left to draw the frames. The
25406
+ // samples may include first-draw costs.
25407
+ interruptions.push({
25408
+ at: Date.now(),
25409
+ kind: 'render-warmup-skipped-budget',
25410
+ value: `${PROFILE_WARMUP_FRAMES} warm-up frames skipped: ${Math.max(0, warmupBudgetMs)}ms of the command's time was left for them`,
25411
+ });
25412
+ }
25413
+ else {
25414
+ const warmup = await requestApplicationRender(frame, PROFILE_WARMUP_FRAMES, warmupBudgetMs);
25415
+ if (warmup === 'timeout') {
25416
+ // The samples may include first-draw costs, or frames the app never
25417
+ // drew because its render loop has stopped.
25418
+ interruptions.push({
25419
+ at: Date.now(),
25420
+ kind: 'render-warmup-timeout',
25421
+ value: `${PROFILE_WARMUP_FRAMES} warm-up frames not drawn within ${warmupBudgetMs}ms`,
25422
+ });
25423
+ }
25424
+ }
25425
+ }
24855
25426
  await frame.evaluate(({ maxSamples, mode }) => {
24856
25427
  const runtimeWindow = window;
24857
25428
  runtimeWindow.__IWSDK_BROWSER_PROFILE?.observers?.forEach((observer) => observer.disconnect());
24858
25429
  if (runtimeWindow.__IWSDK_BROWSER_PROFILE?.rafId != null) {
24859
25430
  cancelAnimationFrame(runtimeWindow.__IWSDK_BROWSER_PROFILE.rafId);
24860
25431
  }
25432
+ // Count only work that starts during the profile, not the first draw
25433
+ // or the warm-up frames just before it. Observing without `buffered`
25434
+ // skips earlier entries; the check drops late reports of earlier work.
25435
+ const since = performance.now();
25436
+ const readDrawnFrames = () => {
25437
+ try {
25438
+ const count = runtimeWindow.FRAMEWORK_MCP_RUNTIME?.drawnFrames;
25439
+ return typeof count === 'number' ? count : null;
25440
+ }
25441
+ catch {
25442
+ return null;
25443
+ }
25444
+ };
24861
25445
  const state = {
25446
+ drawnFrames: readDrawnFrames(),
24862
25447
  eventDurations: [],
25448
+ framesSinceDraw: 0,
24863
25449
  frameTimes: [],
25450
+ longestUndrawnRun: 0,
24864
25451
  longTasks: [],
24865
25452
  observers: [],
24866
25453
  previousFrame: null,
@@ -24874,11 +25461,13 @@ async function startProfileInFrame(frame, mode) {
24874
25461
  }
24875
25462
  const observer = new PerformanceObserver((list) => {
24876
25463
  for (const entry of list.getEntries()) {
24877
- callback(entry);
25464
+ if (entry.startTime >= since) {
25465
+ callback(entry);
25466
+ }
24878
25467
  }
24879
25468
  });
24880
25469
  try {
24881
- observer.observe({ type, buffered: true });
25470
+ observer.observe({ type });
24882
25471
  state.observers.push(observer);
24883
25472
  }
24884
25473
  catch {
@@ -24903,6 +25492,22 @@ async function startProfileInFrame(frame, mode) {
24903
25492
  state.frameTimes.push(timestamp - state.previousFrame);
24904
25493
  }
24905
25494
  state.previousFrame = timestamp;
25495
+ // While the profile holds rendering the app draws every frame, so
25496
+ // count the frames since its drawn-frame count last moved, and keep
25497
+ // the longest such run. Counting ends when stopping releases the
25498
+ // hold.
25499
+ const drawnFrames = readDrawnFrames();
25500
+ if (drawnFrames != null &&
25501
+ runtimeWindow.__IWSDK_PROFILE_RENDER_HOLD != null) {
25502
+ if (drawnFrames === state.drawnFrames) {
25503
+ state.framesSinceDraw += 1;
25504
+ state.longestUndrawnRun = Math.max(state.longestUndrawnRun, state.framesSinceDraw);
25505
+ }
25506
+ else {
25507
+ state.drawnFrames = drawnFrames;
25508
+ state.framesSinceDraw = 0;
25509
+ }
25510
+ }
24906
25511
  state.rafId = requestAnimationFrame(sample);
24907
25512
  };
24908
25513
  state.rafId = requestAnimationFrame(sample);
@@ -24923,8 +25528,25 @@ async function startProfileInFrame(frame, mode) {
24923
25528
  performance.mark(`iwsdk-browser-profile-${mode}-start`);
24924
25529
  runtimeWindow.__IWSDK_BROWSER_PROFILE = state;
24925
25530
  }, { maxSamples: MAX_PROFILE_SAMPLES, mode });
25531
+ return interruptions;
24926
25532
  }
25533
+ /**
25534
+ * Release the profile's render hold and collect its page samples.
25535
+ * `longestUndrawnRun` is the longest run of animation frames in which the
25536
+ * app drew nothing while the profile held rendering; it is `null` when the
25537
+ * app does not report drawn frames.
25538
+ */
24927
25539
  async function stopProfileInFrame(frame) {
25540
+ await frame
25541
+ .evaluate(() => {
25542
+ const runtimeWindow = window;
25543
+ const id = runtimeWindow.__IWSDK_PROFILE_RENDER_HOLD;
25544
+ delete runtimeWindow.__IWSDK_PROFILE_RENDER_HOLD;
25545
+ if (id != null) {
25546
+ runtimeWindow.FRAMEWORK_MCP_RUNTIME?.releaseRenderHold?.(id);
25547
+ }
25548
+ })
25549
+ .catch(() => { });
24928
25550
  const result = await frame.evaluate((maxSamples) => {
24929
25551
  const runtimeWindow = window;
24930
25552
  const state = runtimeWindow.__IWSDK_BROWSER_PROFILE;
@@ -24942,6 +25564,7 @@ async function stopProfileInFrame(frame) {
24942
25564
  return {
24943
25565
  eventDurations: state.eventDurations,
24944
25566
  frameTimes: state.frameTimes,
25567
+ longestUndrawnRun: state.drawnFrames == null ? null : state.longestUndrawnRun,
24945
25568
  longTasks: state.longTasks,
24946
25569
  visibilityEvents: state.visibilityEvents,
24947
25570
  marks: performance
@@ -25006,58 +25629,69 @@ async function collectRuntimePreflightEvidence(page, request) {
25006
25629
  };
25007
25630
  });
25008
25631
  const frame = await resolveApplicationFrame(page);
25009
- const runtimeDeadline = Date.now() + 20000;
25010
- let hierarchy = null;
25011
- let hierarchyEntries = [];
25012
- let runtimeHashes = [];
25013
- let renderStats = { available: false };
25014
- let lastRuntimeError = null;
25015
- while (Date.now() < runtimeDeadline) {
25016
- try {
25017
- hierarchy = await frame.evaluate(readRuntimeHierarchy);
25018
- ({ entries: hierarchyEntries, runtimeHashes } =
25019
- flattenRuntimeHierarchy(hierarchy));
25020
- renderStats = await frame.evaluate(readRuntimeRenderStats);
25021
- if (runtimeHashes.length > 0) {
25022
- break;
25632
+ // Evidence reads real draw calls and frame cost, so the app draws every
25633
+ // frame while it is collected. The runtime may not exist yet, so the hold
25634
+ // is retried inside the readiness loop below.
25635
+ const renderHold = createRenderHoldTracker();
25636
+ try {
25637
+ const runtimeDeadline = Date.now() + 20000;
25638
+ let hierarchy = null;
25639
+ let hierarchyEntries = [];
25640
+ let runtimeHashes = [];
25641
+ let renderStats = { available: false };
25642
+ let lastRuntimeError = null;
25643
+ while (Date.now() < runtimeDeadline) {
25644
+ try {
25645
+ await renderHold.ensure(frame);
25646
+ await requestApplicationRender(frame, 1, 5000);
25647
+ hierarchy = await frame.evaluate(readRuntimeHierarchy);
25648
+ ({ entries: hierarchyEntries, runtimeHashes } =
25649
+ flattenRuntimeHierarchy(hierarchy));
25650
+ renderStats = await frame.evaluate(readRuntimeRenderStats);
25651
+ if (runtimeHashes.length > 0) {
25652
+ break;
25653
+ }
25023
25654
  }
25655
+ catch (error) {
25656
+ lastRuntimeError = error;
25657
+ }
25658
+ await page.waitForTimeout(50);
25024
25659
  }
25025
- catch (error) {
25026
- lastRuntimeError = error;
25660
+ if (hierarchy == null) {
25661
+ throw new Error(`IWSDK app runtime bridge is unavailable: ${errorMessage$1(lastRuntimeError ?? 'timed out')}`);
25027
25662
  }
25028
- await page.waitForTimeout(50);
25663
+ const frameTimes = await frame.evaluate(sampleRuntimeFrameTimes, {
25664
+ sampleFrames: request.sampleFrames,
25665
+ warmupFrames: request.warmupFrames,
25666
+ });
25667
+ const environmentRead = await frame.evaluate(readEnvironmentDescriptor, 'renderer');
25668
+ assertBrowserEnvironmentDescriptor(environmentRead.environment);
25669
+ const presentation = await collectPresentationSnapshot(frame, {
25670
+ frameTimes,
25671
+ hierarchyObjectCount: hierarchyEntries.length,
25672
+ renderStats,
25673
+ warmupFrames: request.warmupFrames,
25674
+ });
25675
+ return {
25676
+ ...presentation,
25677
+ collectedAt: Date.now(),
25678
+ editor,
25679
+ environment: {
25680
+ ...environmentRead.environment,
25681
+ canvas: environmentRead.canvas == null
25682
+ ? null
25683
+ : {
25684
+ height: environmentRead.canvas.backingHeight,
25685
+ width: environmentRead.canvas.backingWidth,
25686
+ },
25687
+ },
25688
+ renderStats,
25689
+ runtimeHashes,
25690
+ };
25029
25691
  }
25030
- if (hierarchy == null) {
25031
- throw new Error(`IWSDK app runtime bridge is unavailable: ${errorMessage$1(lastRuntimeError ?? 'timed out')}`);
25692
+ finally {
25693
+ await renderHold.release();
25032
25694
  }
25033
- const frameTimes = await frame.evaluate(sampleRuntimeFrameTimes, {
25034
- sampleFrames: request.sampleFrames,
25035
- warmupFrames: request.warmupFrames,
25036
- });
25037
- const environmentRead = await frame.evaluate(readEnvironmentDescriptor, 'renderer');
25038
- assertBrowserEnvironmentDescriptor(environmentRead.environment);
25039
- const presentation = await collectPresentationSnapshot(frame, {
25040
- frameTimes,
25041
- hierarchyObjectCount: hierarchyEntries.length,
25042
- renderStats,
25043
- warmupFrames: request.warmupFrames,
25044
- });
25045
- return {
25046
- ...presentation,
25047
- collectedAt: Date.now(),
25048
- editor,
25049
- environment: {
25050
- ...environmentRead.environment,
25051
- canvas: environmentRead.canvas == null
25052
- ? null
25053
- : {
25054
- height: environmentRead.canvas.backingHeight,
25055
- width: environmentRead.canvas.backingWidth,
25056
- },
25057
- },
25058
- renderStats,
25059
- runtimeHashes,
25060
- };
25061
25695
  });
25062
25696
  }
25063
25697
  async function collectRuntimePublishEvidence(page, request, managedWorkspaceToken = null) {
@@ -25241,91 +25875,103 @@ async function collectRuntimePublishEvidence(page, request, managedWorkspaceToke
25241
25875
  frame.src = url.pathname + url.search + url.hash;
25242
25876
  }, { source: runtimeSource, token: reloadToken });
25243
25877
  await page.waitForTimeout(250);
25244
- let live = null;
25245
- let runtimeFrame = null;
25246
- let lastLiveError = null;
25247
- let runtimeObservedAt = null;
25248
- const liveDeadline = Date.now() + 20000;
25249
- while (Date.now() < liveDeadline) {
25250
- try {
25251
- const candidateFrame = await resolveApplicationFrame(page);
25252
- if (new URL(candidateFrame.url()).searchParams.get('__iwsdk_publish_reload') !== reloadToken) {
25253
- throw new Error('App runtime reload is still in progress');
25254
- }
25255
- const hierarchy = await candidateFrame.evaluate(readRuntimeHierarchy);
25256
- const { entries, runtimeHashes } = flattenRuntimeHierarchy(hierarchy);
25257
- const nodes = await candidateFrame.evaluate(readRuntimeNodes, request.nodeIds.map((nodeId) => ({
25258
- entry: entries.find((candidate) => candidate.sceneNodeId === nodeId) ??
25259
- null,
25260
- nodeId,
25261
- })));
25262
- const renderStats = await candidateFrame.evaluate(readRuntimeRenderStats);
25263
- if (runtimeHashes.length > 0) {
25264
- runtimeObservedAt ?? (runtimeObservedAt = Date.now());
25265
- const allNodesPresent = nodes.every((entry) => entry.hierarchy != null);
25266
- if (allNodesPresent || Date.now() - runtimeObservedAt >= 3000) {
25267
- const frameTimeSamplesMs = await candidateFrame.evaluate(sampleRuntimeFrameTimes, { sampleFrames: 8, warmupFrames: 2 });
25268
- live = {
25269
- hierarchy,
25270
- hierarchyObjectCount: entries.length,
25271
- nodes,
25272
- renderStats: { ...renderStats, frameTimeSamplesMs },
25273
- runtimeHashes,
25274
- };
25275
- runtimeFrame = candidateFrame;
25276
- break;
25878
+ // Evidence reads real draw calls and frame cost, so the app draws every
25879
+ // frame while it is collected. The reload drops a hold with its page, and
25880
+ // the reloaded runtime may not exist on the first attempts, so the hold
25881
+ // is re-taken on each candidate frame until it sticks.
25882
+ const renderHold = createRenderHoldTracker();
25883
+ try {
25884
+ let live = null;
25885
+ let runtimeFrame = null;
25886
+ let lastLiveError = null;
25887
+ let runtimeObservedAt = null;
25888
+ const liveDeadline = Date.now() + 20000;
25889
+ while (Date.now() < liveDeadline) {
25890
+ try {
25891
+ const candidateFrame = await resolveApplicationFrame(page);
25892
+ if (new URL(candidateFrame.url()).searchParams.get('__iwsdk_publish_reload') !== reloadToken) {
25893
+ throw new Error('App runtime reload is still in progress');
25894
+ }
25895
+ await renderHold.ensure(candidateFrame);
25896
+ await requestApplicationRender(candidateFrame, 1, 5000);
25897
+ const hierarchy = await candidateFrame.evaluate(readRuntimeHierarchy);
25898
+ const { entries, runtimeHashes } = flattenRuntimeHierarchy(hierarchy);
25899
+ const nodes = await candidateFrame.evaluate(readRuntimeNodes, request.nodeIds.map((nodeId) => ({
25900
+ entry: entries.find((candidate) => candidate.sceneNodeId === nodeId) ??
25901
+ null,
25902
+ nodeId,
25903
+ })));
25904
+ const renderStats = await candidateFrame.evaluate(readRuntimeRenderStats);
25905
+ if (runtimeHashes.length > 0) {
25906
+ runtimeObservedAt ?? (runtimeObservedAt = Date.now());
25907
+ const allNodesPresent = nodes.every((entry) => entry.hierarchy != null);
25908
+ if (allNodesPresent || Date.now() - runtimeObservedAt >= 3000) {
25909
+ const frameTimeSamplesMs = await candidateFrame.evaluate(sampleRuntimeFrameTimes, { sampleFrames: 8, warmupFrames: 2 });
25910
+ live = {
25911
+ hierarchy,
25912
+ hierarchyObjectCount: entries.length,
25913
+ nodes,
25914
+ renderStats: { ...renderStats, frameTimeSamplesMs },
25915
+ runtimeHashes,
25916
+ };
25917
+ runtimeFrame = candidateFrame;
25918
+ break;
25919
+ }
25277
25920
  }
25278
25921
  }
25922
+ catch (error) {
25923
+ lastLiveError = error;
25924
+ }
25925
+ await page.waitForTimeout(100);
25279
25926
  }
25280
- catch (error) {
25281
- lastLiveError = error;
25282
- }
25283
- await page.waitForTimeout(100);
25284
- }
25285
- if (live == null || runtimeFrame == null) {
25286
- throw new Error(`App runtime did not become publish-ready: ${errorMessage$1(lastLiveError ?? 'timed out')}`);
25287
- }
25288
- const environmentRead = await runtimeFrame.evaluate(readEnvironmentDescriptor, 'largest');
25289
- assertBrowserEnvironmentDescriptor(environmentRead.environment);
25290
- if (environmentRead.canvas == null ||
25291
- environmentRead.canvasIndex == null ||
25292
- environmentRead.canvasIndex < 0) {
25293
- throw new Error('App runtime did not render a canvas');
25294
- }
25295
- const canvases = runtimeFrame.locator('canvas');
25296
- const canvasCount = await canvases.count();
25297
- if (environmentRead.canvasIndex >= canvasCount) {
25298
- throw new Error('App runtime frame has no canvas to capture');
25299
- }
25300
- const captureBytes = Buffer.from(await canvases
25301
- .nth(environmentRead.canvasIndex)
25302
- .screenshot({ type: 'png' }));
25303
- const capture = await inspectPngCapture(captureBytes);
25304
- const presentation = await collectPresentationSnapshot(runtimeFrame, {
25305
- frameTimes: live.renderStats.frameTimeSamplesMs,
25306
- hierarchyObjectCount: live.hierarchyObjectCount,
25307
- renderStats: live.renderStats,
25308
- warmupFrames: 2,
25309
- });
25310
- return {
25311
- camera: presentation.camera,
25312
- capture,
25313
- collectedAt: Date.now(),
25314
- editor,
25315
- environment: {
25316
- ...environmentRead.environment,
25317
- canvas: environmentRead.canvas,
25318
- },
25319
- framing: presentation.framing,
25320
- hierarchy: live.hierarchy,
25321
- hierarchyObjectCount: presentation.hierarchyObjectCount,
25322
- nodes: live.nodes,
25323
- performance: presentation.performance,
25324
- renderStats: live.renderStats,
25325
- reloadStartedAt,
25326
- runtimeReloadStartedAt,
25327
- runtimeHashes: live.runtimeHashes,
25328
- };
25927
+ if (live == null || runtimeFrame == null) {
25928
+ throw new Error(`App runtime did not become publish-ready: ${errorMessage$1(lastLiveError ?? 'timed out')}`);
25929
+ }
25930
+ const environmentRead = await runtimeFrame.evaluate(readEnvironmentDescriptor, 'largest');
25931
+ assertBrowserEnvironmentDescriptor(environmentRead.environment);
25932
+ if (environmentRead.canvas == null ||
25933
+ environmentRead.canvasIndex == null ||
25934
+ environmentRead.canvasIndex < 0) {
25935
+ throw new Error('App runtime did not render a canvas');
25936
+ }
25937
+ const canvases = runtimeFrame.locator('canvas');
25938
+ const canvasCount = await canvases.count();
25939
+ if (environmentRead.canvasIndex >= canvasCount) {
25940
+ throw new Error('App runtime frame has no canvas to capture');
25941
+ }
25942
+ const captureBytes = Buffer.from(await canvases
25943
+ .nth(environmentRead.canvasIndex)
25944
+ .screenshot({ type: 'png' }));
25945
+ const capture = await inspectPngCapture(captureBytes);
25946
+ const presentation = await collectPresentationSnapshot(runtimeFrame, {
25947
+ frameTimes: live.renderStats.frameTimeSamplesMs,
25948
+ hierarchyObjectCount: live.hierarchyObjectCount,
25949
+ renderStats: live.renderStats,
25950
+ warmupFrames: 2,
25951
+ });
25952
+ return {
25953
+ camera: presentation.camera,
25954
+ capture,
25955
+ collectedAt: Date.now(),
25956
+ editor,
25957
+ environment: {
25958
+ ...environmentRead.environment,
25959
+ canvas: environmentRead.canvas,
25960
+ },
25961
+ framing: presentation.framing,
25962
+ hierarchy: live.hierarchy,
25963
+ hierarchyObjectCount: presentation.hierarchyObjectCount,
25964
+ nodes: live.nodes,
25965
+ performance: presentation.performance,
25966
+ renderStats: live.renderStats,
25967
+ reloadStartedAt,
25968
+ runtimeReloadStartedAt,
25969
+ runtimeHashes: live.runtimeHashes,
25970
+ };
25971
+ }
25972
+ finally {
25973
+ await renderHold.release();
25974
+ }
25329
25975
  });
25330
25976
  }
25331
25977
  async function inspectPngCapture(bytes) {
@@ -25407,6 +26053,7 @@ async function launchManagedBrowser(url, headless, verbose, viewport = null, scr
25407
26053
  managedWorkspaceToken: bootstrap.token,
25408
26054
  page,
25409
26055
  readiness,
26056
+ renderMode: resolveManagedRenderMode(headless),
25410
26057
  waitForRuntime: managedAccess?.runtimeIdentity == null,
25411
26058
  signal,
25412
26059
  traceMcp,
@@ -25456,6 +26103,7 @@ async function launchManagedBrowser(url, headless, verbose, viewport = null, scr
25456
26103
  });
25457
26104
  return {
25458
26105
  captureRuntimeScreenshot: (options = {}) => commandCoordinator.runExclusive(() => interactionSurface.captureRuntimeScreenshot(options)),
26106
+ captureRuntimeFilmstrip: (options = {}) => commandCoordinator.runExclusive(() => interactionSurface.captureRuntimeFilmstrip(options)),
25459
26107
  snapshotApplication: (request = {}) => commandCoordinator.runExclusive(() => interactionSurface.snapshotApplication(request)),
25460
26108
  interactApplication: (request) => commandCoordinator.runExclusive(() => interactionSurface.interactApplication(request)),
25461
26109
  profileApplication: (request) => commandCoordinator.runExclusive(async () => {
@@ -26429,6 +27077,7 @@ function matches(metadata, target) {
26429
27077
  * Reports MCP tool calls, session lifecycle, and errors through MetaVR's
26430
27078
  * DeveloperTelemetry pipeline via the `metavr xxiwsdk` subcommand.
26431
27079
  * All calls are fire-and-forget — telemetry never blocks or breaks the tool.
27080
+ * At most a few MetaVR processes run at once; further events wait their turn.
26432
27081
  *
26433
27082
  * Executes MetaVR's JavaScript entrypoint with the current Node executable.
26434
27083
  * This avoids platform shell shims and works the same way on Windows and Unix.
@@ -26443,7 +27092,60 @@ function resolveMetaVrEntrypoint() {
26443
27092
  return null;
26444
27093
  }
26445
27094
  }
26446
- function metaVrTelemetry(args, clientVersion) {
27095
+ // At most this many MetaVR processes run at once. Each event is its own
27096
+ // Node process that lives under a second; the dev server reports every MCP
27097
+ // tool call, and an agent can issue them faster than that, so without a limit
27098
+ // thousands of these processes piled up on a devserver.
27099
+ const MAX_RUNNING = 4;
27100
+ // Events waiting beyond this are dropped, so telemetry never grows without
27101
+ // bound when a caller outpaces MetaVR for a long time.
27102
+ const MAX_QUEUED = 1000;
27103
+ const queued = [];
27104
+ let running = 0;
27105
+ let exitHookInstalled = false;
27106
+ function launch(argv) {
27107
+ running++;
27108
+ let finished = false;
27109
+ const finish = () => {
27110
+ if (finished) {
27111
+ return;
27112
+ }
27113
+ finished = true;
27114
+ running--;
27115
+ drain();
27116
+ };
27117
+ try {
27118
+ const child = spawn(process.execPath, argv, {
27119
+ stdio: 'ignore',
27120
+ windowsHide: true,
27121
+ });
27122
+ child.on('error', finish);
27123
+ child.on('exit', finish);
27124
+ child.unref();
27125
+ }
27126
+ catch {
27127
+ finish();
27128
+ }
27129
+ }
27130
+ function drain() {
27131
+ while (running < MAX_RUNNING && queued.length > 0) {
27132
+ launch(queued.shift());
27133
+ }
27134
+ }
27135
+ /**
27136
+ * Starts up to MAX_RUNNING of the events still waiting and drops the rest.
27137
+ * Runs when the process exits, so a burst at the end neither floods the
27138
+ * machine nor keeps the process alive. Session and error events wait at the
27139
+ * front, so they are the ones started.
27140
+ */
27141
+ function flushQueuedTelemetry() {
27142
+ const remaining = queued.splice(0, MAX_RUNNING);
27143
+ queued.length = 0;
27144
+ for (const argv of remaining) {
27145
+ launch(argv);
27146
+ }
27147
+ }
27148
+ function metaVrTelemetry(args, clientVersion, urgent = false) {
26447
27149
  const entrypoint = resolveMetaVrEntrypoint();
26448
27150
  if (entrypoint == null) {
26449
27151
  return;
@@ -26452,12 +27154,20 @@ function metaVrTelemetry(args, clientVersion) {
26452
27154
  if (clientVersion) {
26453
27155
  globalArgs.push('--client-version', clientVersion);
26454
27156
  }
26455
- const child = spawn(process.execPath, [entrypoint, ...globalArgs, ...args], {
26456
- stdio: 'ignore',
26457
- windowsHide: true,
26458
- });
26459
- child.on('error', () => { });
26460
- child.unref();
27157
+ if (!exitHookInstalled) {
27158
+ exitHookInstalled = true;
27159
+ process.once('exit', flushQueuedTelemetry);
27160
+ }
27161
+ const argv = [entrypoint, ...globalArgs, ...args];
27162
+ if (urgent) {
27163
+ // Session boundaries and errors are rare and matter more than any one
27164
+ // tool call, so they go ahead of a backlog and are never dropped for it.
27165
+ queued.unshift(argv);
27166
+ }
27167
+ else if (queued.length < MAX_QUEUED) {
27168
+ queued.push(argv);
27169
+ }
27170
+ drain();
26461
27171
  }
26462
27172
  function reportSessionStart(sessionId, opts) {
26463
27173
  const args = ['session-start', '--session-id', sessionId];
@@ -26470,7 +27180,7 @@ function reportSessionStart(sessionId, opts) {
26470
27180
  if (opts?.port) {
26471
27181
  args.push('--port', String(opts.port));
26472
27182
  }
26473
- metaVrTelemetry(args, opts?.clientVersion);
27183
+ metaVrTelemetry(args, opts?.clientVersion, true);
26474
27184
  }
26475
27185
  function reportSessionEnd(sessionId, opts) {
26476
27186
  const args = ['session-end', '--session-id', sessionId];
@@ -26480,7 +27190,7 @@ function reportSessionEnd(sessionId, opts) {
26480
27190
  if (opts?.reason) {
26481
27191
  args.push('--reason', opts.reason);
26482
27192
  }
26483
- metaVrTelemetry(args, opts?.clientVersion);
27193
+ metaVrTelemetry(args, opts?.clientVersion, true);
26484
27194
  }
26485
27195
 
26486
27196
  /**
@@ -59622,14 +60332,7 @@ function iwsdkDev(options = {}) {
59622
60332
  const certDir = path.isAbsolute(configuredCacheDir)
59623
60333
  ? configuredCacheDir
59624
60334
  : path.resolve(projectRoot, configuredCacheDir);
59625
- const certificate = await getCertificate(certDir, httpsOptions.name ?? 'IWSDK Development', httpsOptions.domains, httpsOptions.ttlDays ?? 365);
59626
- // @vitejs/plugin-basic-ssl writes its cache asynchronously after
59627
- // returning. Complete the write before Vite starts so a rapid restart
59628
- // cannot generate a second certificate for the same project.
59629
- mkdirSync(certDir, { recursive: true });
59630
- writeFileSync(path.join(certDir, '_cert.pem'), certificate, {
59631
- mode: 0o600,
59632
- });
60335
+ const certificate = await loadDevelopmentCertificate(certDir, httpsOptions.name ?? 'IWSDK Development', httpsOptions.domains, httpsOptions.ttlDays ?? 365);
59633
60336
  userConfig.server ?? (userConfig.server = {});
59634
60337
  userConfig.server.https = {
59635
60338
  cert: certificate,
@@ -60029,6 +60732,7 @@ function iwsdkDev(options = {}) {
60029
60732
  connectedClientCount: managed.length,
60030
60733
  lastTransitionAt: lifecycle.stateEnteredAt,
60031
60734
  audioMuted: managedBrowserAudioMuted,
60735
+ renderMode: resolveManagedRenderMode(pluginOptions.workspace?.headless ?? false),
60032
60736
  ...(lifecycle.issue
60033
60737
  ? {
60034
60738
  lastError: createBrowserIssue(lifecycle.issueCause ??
@@ -60104,7 +60808,7 @@ function iwsdkDev(options = {}) {
60104
60808
  currentBrowserState = createBrowserState();
60105
60809
  const launchBrowser = () => controller.ensure();
60106
60810
  const ensureBrowser = () => controller.ensure();
60107
- const waitForBridgeConnection = async (timeoutMs, target) => {
60811
+ const waitForBridgeConnection = async (timeoutMs, target, minTabGeneration) => {
60108
60812
  const deadline = Date.now() + Math.min(timeoutMs, 5000);
60109
60813
  while (!serverShuttingDown && Date.now() < deadline) {
60110
60814
  if (listBrowserClients().some((client) => client.deviceClass === 'managed' &&
@@ -60113,11 +60817,14 @@ function iwsdkDev(options = {}) {
60113
60817
  client.sessionId === target.sessionId) &&
60114
60818
  (target.browserEpoch == null ||
60115
60819
  client.browserEpoch === target.browserEpoch) &&
60820
+ (minTabGeneration == null ||
60821
+ client.tabGeneration >= minTabGeneration) &&
60116
60822
  client.commandReady)) {
60117
- return;
60823
+ return true;
60118
60824
  }
60119
60825
  await controller.wait(controller.snapshot().revision, Math.min(250, deadline - Date.now()));
60120
60826
  }
60827
+ return false;
60121
60828
  };
60122
60829
  // Initialize WebSocket server and client tracking
60123
60830
  mcpClients = new Set();
@@ -60322,12 +61029,28 @@ function iwsdkDev(options = {}) {
60322
61029
  }, `${options.resultContext}_relaunched`);
60323
61030
  return;
60324
61031
  }
61032
+ const appBridgeTarget = {
61033
+ role: 'app',
61034
+ sessionId,
61035
+ };
61036
+ const hadAppBridge = options.awaitAppBridge === true &&
61037
+ listBrowserClients().some((client) => client.deviceClass === 'managed' &&
61038
+ client.role === appBridgeTarget.role &&
61039
+ client.commandReady);
60325
61040
  const execution = await runManagedBrowserCommand(options.command, readiness.browser, parsed.target, () => options.execute(readiness.browser));
61041
+ // Waited for outside the command lock, whose budget the command
61042
+ // itself may already have used.
61043
+ const appCommandReady = hadAppBridge
61044
+ ? await waitForBridgeConnection(BRIDGE_READY_TIMEOUT_MS, {
61045
+ ...appBridgeTarget,
61046
+ browserEpoch: controller.snapshot().browserEpoch,
61047
+ }, execution.tab.generation ?? undefined)
61048
+ : undefined;
60326
61049
  sendWsJson(ws, {
60327
61050
  id: parsed.id,
60328
61051
  result: options.serialize == null
60329
61052
  ? execution.result
60330
- : options.serialize(execution.result),
61053
+ : options.serialize(execution.result, appCommandReady),
60331
61054
  ...(execution.tab.id == null
60332
61055
  ? {}
60333
61056
  : {
@@ -61010,11 +61733,15 @@ function iwsdkDev(options = {}) {
61010
61733
  errorContext: 'reload_error',
61011
61734
  execute: (browser) => browser.reloadApplication(),
61012
61735
  resultContext: 'reload_result',
61013
- serialize: (result) => ({
61736
+ serialize: (result, appCommandReady) => ({
61014
61737
  reloaded: true,
61015
61738
  url: result.url,
61739
+ ...(appCommandReady == null
61740
+ ? {}
61741
+ : { commandReady: appCommandReady }),
61016
61742
  }),
61017
61743
  unavailableContext: 'reload_unavailable',
61744
+ awaitAppBridge: true,
61018
61745
  });
61019
61746
  return;
61020
61747
  }
@@ -61101,6 +61828,22 @@ function iwsdkDev(options = {}) {
61101
61828
  });
61102
61829
  return;
61103
61830
  }
61831
+ if (parsed.method === 'browser_filmstrip' &&
61832
+ typeof parsed.id === 'string') {
61833
+ intercepted = true;
61834
+ await handleManagedBrowserRequest(ws, parsed, {
61835
+ command: 'browser_filmstrip',
61836
+ errorContext: 'browser_filmstrip_error',
61837
+ execute: (browser) => browser.captureRuntimeFilmstrip(parsed.params ?? {}),
61838
+ resultContext: 'browser_filmstrip_result',
61839
+ serialize: (capture) => ({
61840
+ ...capture.metadata,
61841
+ imageData: capture.bytes.toString('base64'),
61842
+ }),
61843
+ unavailableContext: 'browser_filmstrip_unavailable',
61844
+ });
61845
+ return;
61846
+ }
61104
61847
  if (intercepted &&
61105
61848
  typeof parsed.id === 'string' &&
61106
61849
  typeof parsed.method === 'string') {
@@ -64850,6 +65593,32 @@ async function readRequestBody(request, maxBytes = Number.POSITIVE_INFINITY) {
64850
65593
  }
64851
65594
  /** @deprecated Use `iwsdkDev` instead */
64852
65595
  const injectIWER = iwsdkDev;
65596
+ /**
65597
+ * Returns the project's development certificate from `<certDir>/_cert.pem`,
65598
+ * generating and caching one when it is missing, unreadable or expired.
65599
+ *
65600
+ * `@vitejs/plugin-basic-ssl` writes its own cache without awaiting the write,
65601
+ * after `getCertificate` has returned. Pointing it at `certDir` itself let that
65602
+ * late write truncate `_cert.pem` while the next start was reading it. It now
65603
+ * generates into a subdirectory that is never read, and this function owns
65604
+ * `_cert.pem` with a synchronous write.
65605
+ */
65606
+ async function loadDevelopmentCertificate(certDir, name, domains, ttlDays) {
65607
+ const certPath = path.join(certDir, '_cert.pem');
65608
+ try {
65609
+ const cached = readFileSync(certPath, 'utf8');
65610
+ if (new Date(new X509Certificate(cached).validTo).getTime() > Date.now()) {
65611
+ return cached;
65612
+ }
65613
+ }
65614
+ catch {
65615
+ // Missing, unreadable or not a certificate: generate a new one.
65616
+ }
65617
+ const certificate = await getCertificate(path.join(certDir, '.basic-ssl'), name, domains, ttlDays);
65618
+ mkdirSync(certDir, { recursive: true });
65619
+ writeFileSync(certPath, certificate, { mode: 0o600 });
65620
+ return certificate;
65621
+ }
64853
65622
 
64854
65623
  export { injectIWER, iwsdkDev };
64855
65624
  //# sourceMappingURL=index.js.map