@iwsdk/vite-plugin-dev 1.1.0 → 1.2.0-rc.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.
@@ -1 +1 @@
1
- export{s as startIwsdkDevRuntime}from"./chunks/injection-template-0HSd4CcE.js";
1
+ export{s as startIwsdkDevRuntime}from"./chunks/injection-template-5pO4YM1n.js";
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+ import type { Frame } from 'playwright';
8
+ export interface BrowserFilmstripOptions {
9
+ count?: number;
10
+ every?: number;
11
+ format?: 'jpeg' | 'png';
12
+ }
13
+ export interface NormalizedFilmstripOptions {
14
+ count: number;
15
+ every: number;
16
+ format: 'jpeg' | 'png';
17
+ }
18
+ export declare const FILMSTRIP_DEFAULT_COUNT = 6;
19
+ export declare const FILMSTRIP_DEFAULT_EVERY = 5;
20
+ export declare const FILMSTRIP_MAX_COUNT = 12;
21
+ export declare const FILMSTRIP_MAX_EVERY = 120;
22
+ export declare const FILMSTRIP_MAX_COLUMNS = 4;
23
+ export declare function normalizeFilmstripOptions(options?: BrowserFilmstripOptions): NormalizedFilmstripOptions;
24
+ /** The page-side ECS controls a filmstrip needs. */
25
+ export interface FilmstripEcsControl {
26
+ /** Whether ECS was paused before the filmstrip; `null` if unknown. */
27
+ isPaused(): Promise<boolean | null>;
28
+ pause(): Promise<void>;
29
+ step(frames: number): Promise<void>;
30
+ resume(): Promise<void>;
31
+ }
32
+ /**
33
+ * Remaining active command time in milliseconds. Throws the managed browser's
34
+ * "ran out of active command time" error once the budget is spent.
35
+ */
36
+ export type FilmstripBudget = () => number;
37
+ /**
38
+ * `ecs_step` advances one simulation step per animation frame, and the managed
39
+ * browser animates at most 60 frames per second, so a filmstrip needs at least
40
+ * this long however fast the app renders.
41
+ */
42
+ export declare function filmstripMinimumDurationMs(options: NormalizedFilmstripOptions): number;
43
+ /**
44
+ * Pause, capture the current frame, then step and capture until `count`
45
+ * frames are taken. The caller's pause state is restored however this ends:
46
+ * ECS resumes only if this call paused it.
47
+ *
48
+ * Every step and capture runs against the remaining command budget, so a
49
+ * sequence that cannot finish fails with a clear error before the managed
50
+ * browser's command coordinator would time the whole browser out.
51
+ */
52
+ export declare function runFilmstrip<T>(ecs: FilmstripEcsControl, options: NormalizedFilmstripOptions, capture: (offset: number) => Promise<T>, budget: FilmstripBudget): Promise<Array<{
53
+ offset: number;
54
+ capture: T;
55
+ }>>;
56
+ /** ECS controls through the page runtime's MCP dispatch. */
57
+ export declare function pageFilmstripEcsControl(frame: Frame): FilmstripEcsControl;
58
+ export interface ContactSheetLayout {
59
+ columns: number;
60
+ rows: number;
61
+ panelWidth: number;
62
+ panelHeight: number;
63
+ width: number;
64
+ height: number;
65
+ }
66
+ /**
67
+ * Lay `count` panels of `source` aspect out in at most four columns, balanced
68
+ * across rows (6 panels make 3×2, not 4+2), scaled down so the whole sheet
69
+ * fits `bounds`.
70
+ */
71
+ export declare function contactSheetLayout(count: number, source: {
72
+ width: number;
73
+ height: number;
74
+ }, bounds: {
75
+ width: number;
76
+ height: number;
77
+ }): ContactSheetLayout;
78
+ /**
79
+ * Stitch captures into one contact sheet, each panel labeled with its
80
+ * simulation frame offset (`+0`, `+5`, ...).
81
+ */
82
+ export declare function composeContactSheet(panels: Array<{
83
+ offset: number;
84
+ bytes: Buffer;
85
+ }>, bounds: {
86
+ width: number;
87
+ height: number;
88
+ }, format: 'jpeg' | 'png'): Promise<{
89
+ bytes: Buffer;
90
+ layout: ContactSheetLayout;
91
+ }>;
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import type { Frame, Page } from 'playwright';
8
8
  import { type BrowserApplicationMetadata } from './application-surface.js';
9
+ import { type BrowserFilmstripOptions } from './filmstrip.js';
9
10
  export declare const MAX_BROWSER_INTERACTION_TIMEOUT_MS = 12000;
10
11
  export interface BrowserScreenshotOptions {
11
12
  format?: 'jpeg' | 'png';
@@ -110,6 +111,21 @@ export interface BrowserScreenshotCapture {
110
111
  width: number;
111
112
  };
112
113
  }
114
+ export interface BrowserFilmstripCapture {
115
+ bytes: Buffer;
116
+ metadata: BrowserApplicationMetadata & {
117
+ columns: number;
118
+ count: number;
119
+ every: number;
120
+ frameOffsets: number[];
121
+ height: number;
122
+ mimeType: 'image/jpeg' | 'image/png';
123
+ panelHeight: number;
124
+ panelWidth: number;
125
+ rows: number;
126
+ width: number;
127
+ };
128
+ }
113
129
  interface InteractionProfiler {
114
130
  readonly activeDeadline: number | null;
115
131
  markInteractionStep(frame: Frame, index: number, action: string): Promise<void>;
@@ -130,9 +146,12 @@ export declare class ManagedInteractionSurface {
130
146
  private readonly snapshotRecipes;
131
147
  constructor(options: ManagedInteractionSurfaceOptions);
132
148
  captureRuntimeScreenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotCapture>;
149
+ captureRuntimeFilmstrip(options?: BrowserFilmstripOptions): Promise<BrowserFilmstripCapture>;
133
150
  snapshotApplication(request?: BrowserSnapshotRequest): Promise<BrowserSnapshotResult>;
134
151
  interactApplication(request: BrowserInteractionRequest): Promise<BrowserInteractionResult>;
152
+ private captureApplicationFilmstrip;
135
153
  private captureApplicationImage;
154
+ private captureRenderedApplicationImage;
136
155
  private runInteractionBatch;
137
156
  }
138
157
  export declare function isRetryableInteractionError(error: unknown): boolean;
@@ -5,6 +5,7 @@
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
7
  import { type Browser, type BrowserContext, type Page } from 'playwright';
8
+ import type { ManagedRenderMode } from './render-mode.js';
8
9
  export interface ManagedBrowserAccess {
9
10
  headerName: string;
10
11
  pathnames: readonly string[];
@@ -46,12 +47,13 @@ export declare function openManagedChromium({ browserAutomation, headless, launc
46
47
  dispose: () => Promise<void>;
47
48
  page: Page;
48
49
  }>;
49
- export declare function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context, managedWorkspaceToken, page, readiness, waitForRuntime, signal, traceMcp, url, }: {
50
+ export declare function navigateAndVerifyManagedPage({ browserAutomationEndpoint, context, managedWorkspaceToken, page, readiness, renderMode, waitForRuntime, signal, traceMcp, url, }: {
50
51
  browserAutomationEndpoint: string | null;
51
52
  context: BrowserContext;
52
53
  managedWorkspaceToken: string | null;
53
54
  page: Page;
54
55
  readiness: ManagedBrowserReadiness;
56
+ renderMode?: ManagedRenderMode;
55
57
  waitForRuntime?: boolean;
56
58
  signal?: AbortSignal;
57
59
  traceMcp: boolean;
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+ import type { Frame } from 'playwright';
8
+ /**
9
+ * Render loop policy for the managed application. Headless sessions default to
10
+ * `'on-demand'`: systems run every frame but nothing is drawn until a tool
11
+ * needs pixels, so a GPU-less host does not software-rasterize every frame.
12
+ */
13
+ export type ManagedRenderMode = 'continuous' | 'on-demand';
14
+ /**
15
+ * Resolve the render mode for a managed browser session. Headed sessions are
16
+ * always continuous because a person is watching them. `IWSDK_DEV_RENDER_MODE`
17
+ * (`continuous` or `on-demand`, case-insensitive) overrides the headless
18
+ * default; any other value is reported once and ignored.
19
+ */
20
+ export declare function resolveManagedRenderMode(headless: boolean, override?: string | undefined, warn?: (message: string) => void): ManagedRenderMode;
21
+ /**
22
+ * Draw `frames` fresh frames in the application frame and wait until they have
23
+ * been handed to the compositor. Apps that do not expose `requestRender`
24
+ * (non-IWSDK runtimes, older @iwsdk/core) are left alone.
25
+ */
26
+ export declare function requestApplicationRender(frame: Frame, frames?: number, timeoutMs?: number): Promise<void>;
27
+ /**
28
+ * Whether a frame the application draws stays on its canvas until the next
29
+ * draw. False under the emulator's default per-frame clear in immersive
30
+ * sessions; the injected runtime turns that clear off for on-demand sessions
31
+ * and sets `__IWSDK_KEEPS_DRAWN_FRAMES`.
32
+ */
33
+ export declare function applicationKeepsDrawnFrames(frame: Frame): Promise<boolean>;
34
+ /**
35
+ * Start drawing every frame in the application until the returned function is
36
+ * called. Holds are counted by the runtime, so overlapping holds (a capture
37
+ * during a profile) cannot end each other early. Returns `null` when the app
38
+ * does not support render holds (non-IWSDK runtimes, older @iwsdk/core); such
39
+ * apps draw continuously anyway.
40
+ */
41
+ export declare function acquireApplicationRenderHold(frame: Frame): Promise<string | null>;
42
+ /**
43
+ * Release a hold from {@link acquireApplicationRenderHold}. A reload drops
44
+ * every hold with the page, so a missing runtime is not an error.
45
+ */
46
+ export declare function releaseApplicationRenderHold(frame: Frame, id: string | null): Promise<void>;
47
+ /**
48
+ * Run `fn` with the application drawing every frame. Profiling, runtime
49
+ * evidence and pixel captures under the emulator's per-frame clear need real
50
+ * frames, which on-demand rendering would otherwise skip.
51
+ */
52
+ export declare function withApplicationRenderHold<T>(frame: Frame, fn: () => Promise<T>): Promise<T>;
53
+ /** The application's render mode, or `null` when it does not report one. */
54
+ export declare function readApplicationRenderMode(frame: Frame): Promise<ManagedRenderMode | null>;
55
+ /**
56
+ * Capture pixels from an application that may render on demand. When drawn
57
+ * frames persist, one fresh frame is requested and captured. Otherwise (the
58
+ * emulator clears the canvas every immersive frame) rendering is held for the
59
+ * whole capture so the frame on screen is always current. The render request
60
+ * gets a bounded share of `timeoutMs`; `capture` receives what is left.
61
+ */
62
+ export declare function captureFreshApplicationFrame<T>(frame: Frame, timeoutMs: number, capture: (remainingMs: number) => Promise<T>): Promise<T>;
63
+ /** Tracks one render hold across a page that may reload. */
64
+ export interface RenderHoldTracker {
65
+ /**
66
+ * Make sure `frame` holds rendering. Retries while the runtime is not ready
67
+ * (no hold yet), and takes a new hold when the frame object changes.
68
+ */
69
+ ensure(frame: Frame): Promise<void>;
70
+ /** Release the current hold, if any. Never throws. */
71
+ release(): Promise<void>;
72
+ }
73
+ /**
74
+ * Create a {@link RenderHoldTracker}. Evidence collection waits for a
75
+ * reloaded runtime to appear; a hold requested before it exists comes back
76
+ * `null` and must be requested again once it does.
77
+ */
78
+ export declare function createRenderHoldTracker(): RenderHoldTracker;
@@ -6,7 +6,8 @@
6
6
  */
7
7
  import { type BrowserApplicationMetadata } from './application-surface.js';
8
8
  import { type CapturedLog, type LogQuery } from './console-capture.js';
9
- import { type BrowserInteractionRequest, type BrowserInteractionResult, type BrowserScreenshotOptions, type BrowserSnapshotRequest, type BrowserSnapshotResult } from './interaction.js';
9
+ import type { BrowserFilmstripOptions } from './filmstrip.js';
10
+ import { type BrowserFilmstripCapture, type BrowserInteractionRequest, type BrowserInteractionResult, type BrowserScreenshotOptions, type BrowserSnapshotRequest, type BrowserSnapshotResult } from './interaction.js';
10
11
  import { type ManagedBrowserAccess, type ManagedBrowserReadiness } from './launch.js';
11
12
  import { type BrowserProfileRequest, type BrowserProfileResult } from './profiling.js';
12
13
  import { type ManagedRuntimePreflightEvidence, type ManagedRuntimePreflightRequest, type ManagedRuntimePublishEvidence, type ManagedRuntimePublishRequest } from './runtime-evidence.js';
@@ -40,6 +41,8 @@ export interface ManagedBrowser {
40
41
  width: number;
41
42
  };
42
43
  }>;
44
+ /** Pause, step and capture a labeled contact sheet of simulation frames. */
45
+ captureRuntimeFilmstrip(options?: BrowserFilmstripOptions): Promise<BrowserFilmstripCapture>;
43
46
  /** Return a bounded semantic snapshot of the current application. */
44
47
  snapshotApplication(request?: BrowserSnapshotRequest): Promise<BrowserSnapshotResult>;
45
48
  /** Execute a bounded batch of trusted Playwright interactions. */
@@ -35,6 +35,16 @@ interface FrameworkMCPRuntime {
35
35
  dispatch(method: string, params: Record<string, unknown>): Promise<unknown>;
36
36
  /** Resolves the target names of emulated hand sequences in the scene. */
37
37
  targetResolver?: MCPTargetResolver;
38
+ /** Draw fresh frames before pixels are captured (on-demand render mode). */
39
+ requestRender?(frames?: number): Promise<void>;
40
+ /** Draw every frame until the hold with the returned id is released. */
41
+ acquireRenderHold?(): string;
42
+ /** Release a hold from `acquireRenderHold`. */
43
+ releaseRenderHold?(id: string): boolean;
44
+ /** `'continuous'` or `'on-demand'`. */
45
+ readonly renderMode?: 'continuous' | 'on-demand';
46
+ /** Whether the ECS debug hook has paused system updates. */
47
+ readonly ecsPaused?: boolean;
38
48
  }
39
49
  declare global {
40
50
  interface Window {
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+ /** Element id of the notice, so a second call never adds another. */
8
+ export declare const NATIVE_CONTROL_NOTICE_ID = "iwsdk-native-control-notice";
9
+ export declare const NATIVE_CONTROL_NOTICE_TITLE = "Agent-controlled page";
10
+ export declare const NATIVE_CONTROL_NOTICE_TEXT: string;
11
+ /**
12
+ * Shows a fixed banner on a page whose WebXR input is overridden by a
13
+ * `--native-xr-control` dev session. The flat page is the only place a person
14
+ * can see it before entering XR. Without it, the page looks like a normal app
15
+ * whose headset and controllers have stopped responding.
16
+ */
17
+ export declare function showNativeControlNotice(doc: Document): void;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+ /** The page globals the managed session and the injected runtime share. */
8
+ export interface OnDemandEmulatorWindow {
9
+ __IWSDK_RENDER_MODE?: unknown;
10
+ __IWSDK_KEEPS_DRAWN_FRAMES?: boolean;
11
+ FRAMEWORK_MCP_RUNTIME?: {
12
+ drawnFrames?: unknown;
13
+ };
14
+ }
15
+ /** What {@link configureOnDemandEmulator} changed on the emulator. */
16
+ export interface OnDemandEmulatorSetup {
17
+ /** The per-frame clear was turned off (`frameClearEnabled = false`). */
18
+ keepsDrawnFrames: boolean;
19
+ /** The synthetic AR environment draws only when the app draws. */
20
+ drawsEnvironmentWithApp: boolean;
21
+ }
22
+ /**
23
+ * Configure the XR emulator so the app can render on demand.
24
+ *
25
+ * Managed sessions can render on demand: systems run every frame but the app
26
+ * draws only when a tool needs pixels. Headless sessions start that way, and
27
+ * any managed session can switch at runtime (`RuntimeSettings`), so the
28
+ * emulator is set up the same way in every managed session, whatever mode it
29
+ * starts in; the app's render mode stays the single switch.
30
+ *
31
+ * - IWER's per-frame clear would only wipe the last drawn frame, at the cost
32
+ * of a full-canvas software clear every frame. It is turned off, and the
33
+ * managed browser is told that one requested frame is enough for a
34
+ * capture. three.js clears before each frame it draws, so continuous
35
+ * rendering looks the same.
36
+ * - In emulated AR, IWER draws its synthetic room behind the app every frame.
37
+ * It now draws only on frames the app drew (the runtime's `drawnFrames`
38
+ * changed), so the room and the app always match and an idle on-demand
39
+ * session draws neither. When the app does not report drawn frames, the
40
+ * room draws every frame as before.
41
+ *
42
+ * Pages outside a managed session (a person's own browser) are left alone.
43
+ * `frameClearEnabled` and `shouldDrawEnvironment` were added in iwer 2.8;
44
+ * an older emulator is left alone too, and the managed browser draws
45
+ * continuously during captures instead.
46
+ */
47
+ export declare function configureOnDemandEmulator(device: object, win: OnDemandEmulatorWindow, log?: (message: string) => void): OnDemandEmulatorSetup;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iwsdk/vite-plugin-dev",
3
- "version": "1.1.0",
3
+ "version": "1.2.0-rc.0",
4
4
  "type": "module",
5
5
  "description": "Vite plugin for IWSDK development — XR emulation, AI agent tooling, and Playwright browser",
6
6
  "main": "dist/index.js",
@@ -43,26 +43,26 @@
43
43
  "license": "MIT",
44
44
  "dependencies": {
45
45
  "@drawcall/uikitml": "0.1.8",
46
- "@iwer/devui": "^2.7.0",
46
+ "@iwer/devui": "^2.8.0",
47
47
  "@preact/signals-core": "^1.12.1",
48
48
  "@vitejs/plugin-basic-ssl": "^2.3.0",
49
49
  "lucide": "^0.468.0",
50
50
  "open": "^10.2.0",
51
- "playwright": "^1.58.2",
51
+ "playwright": "1.65.1",
52
52
  "preact": "^10.29.7",
53
53
  "sharp": "^0.35.4",
54
54
  "three": "npm:super-three@0.185.0",
55
55
  "three-viewport-gizmo": "^2.2.0",
56
56
  "ws": "^8.21.1",
57
- "@iwsdk/scene-composition": "1.1.0",
58
- "@iwsdk/core": "1.1.0"
57
+ "@iwsdk/scene-composition": "1.2.0-rc.0",
58
+ "@iwsdk/core": "1.2.0-rc.0"
59
59
  },
60
60
  "devDependencies": {
61
- "@iwer/sem": "^2.7.0",
61
+ "@iwer/sem": "^2.8.0",
62
62
  "@types/ws": "^8.5.13",
63
- "iwer": "^2.7.0",
63
+ "iwer": "^2.8.0",
64
64
  "vitest": "^4.1.10",
65
- "@iwsdk/cli": "1.1.0"
65
+ "@iwsdk/cli": "1.2.0-rc.0"
66
66
  },
67
67
  "peerDependencies": {
68
68
  "vite": "^7.0.0"