@iwsdk/vite-plugin-dev 0.3.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.
- package/LICENSE +21 -0
- package/README.md +153 -0
- package/dist/headless-browser.d.ts +43 -0
- package/dist/hzdb-telemetry.d.ts +23 -0
- package/dist/index.d.ts +48 -0
- package/dist/index.js +1145 -0
- package/dist/index.js.map +1 -0
- package/dist/injection-bundle.js +598 -0
- package/dist/injection-bundler.d.ts +11 -0
- package/dist/injection-template.d.ts +7 -0
- package/dist/mcp/index.d.ts +7 -0
- package/dist/mcp/ws-client.d.ts +75 -0
- package/dist/mcp-relay.d.ts +38 -0
- package/dist/mcp-server.d.ts +1379 -0
- package/dist/mcp-server.js +21312 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/types.d.ts +142 -0
- package/package.json +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# @iwsdk/vite-plugin-dev
|
|
2
|
+
|
|
3
|
+
Vite plugin for IWSDK development — XR emulation, AI agent tooling, and Playwright browser.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- 🥽 **Device Emulation** — Emulate Meta Quest 2, Quest 3, Quest Pro, or Quest 1 via [IWER](https://github.com/meta-quest/immersive-web-emulation-runtime)
|
|
8
|
+
- 🏠 **Synthetic Environments** — Optional room-scale environments for AR testing
|
|
9
|
+
- 🤖 **AI Agent Tooling** — MCP-based tools for Claude Code, Cursor, Copilot, and Codex
|
|
10
|
+
- 🖥️ **Managed Browser** — Playwright browser for screenshots and console capture
|
|
11
|
+
- 🔧 **Zero Config** — Works out of the box with sensible defaults
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install -D @iwsdk/vite-plugin-dev
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
```javascript
|
|
22
|
+
import { defineConfig } from 'vite';
|
|
23
|
+
import { iwsdkDev } from '@iwsdk/vite-plugin-dev';
|
|
24
|
+
|
|
25
|
+
export default defineConfig({
|
|
26
|
+
plugins: [
|
|
27
|
+
iwsdkDev({
|
|
28
|
+
emulator: { device: 'metaQuest3' },
|
|
29
|
+
verbose: true,
|
|
30
|
+
}),
|
|
31
|
+
],
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Configuration Options
|
|
36
|
+
|
|
37
|
+
```javascript
|
|
38
|
+
iwsdkDev({
|
|
39
|
+
emulator: {
|
|
40
|
+
// XR device to emulate
|
|
41
|
+
// Options: 'metaQuest2' | 'metaQuest3' | 'metaQuestPro' | 'oculusQuest1'
|
|
42
|
+
device: 'metaQuest3', // default
|
|
43
|
+
|
|
44
|
+
// Synthetic environment for AR room simulation
|
|
45
|
+
// Options: 'living_room' | 'meeting_room' | 'music_room' | 'office_large' | 'office_small'
|
|
46
|
+
environment: 'living_room',
|
|
47
|
+
|
|
48
|
+
// When to activate emulation
|
|
49
|
+
// 'localhost' - only on localhost/127.0.0.1 (default)
|
|
50
|
+
// 'always' - always activate
|
|
51
|
+
// RegExp - custom hostname pattern
|
|
52
|
+
activation: 'localhost',
|
|
53
|
+
|
|
54
|
+
// Inject during production build (not just dev)
|
|
55
|
+
injectOnBuild: false, // default
|
|
56
|
+
|
|
57
|
+
// User-Agent pattern to skip (avoids injection on real XR browsers)
|
|
58
|
+
userAgentException: /OculusBrowser/, // default
|
|
59
|
+
},
|
|
60
|
+
|
|
61
|
+
// AI agent configuration — omit to disable entirely
|
|
62
|
+
ai: {
|
|
63
|
+
// Usage mode:
|
|
64
|
+
// 'agent' - headless Playwright, fixed viewport, no DevUI (default)
|
|
65
|
+
// 'oversight' - visible Playwright, freely resizable, no DevUI
|
|
66
|
+
// 'collaborate' - visible Playwright, freely resizable, DevUI on
|
|
67
|
+
mode: 'agent',
|
|
68
|
+
|
|
69
|
+
// Which AI tools to generate MCP config for
|
|
70
|
+
tools: ['claude'], // default
|
|
71
|
+
|
|
72
|
+
// Screenshot size constraint (viewport in agent mode, downscale bound otherwise)
|
|
73
|
+
screenshotSize: { width: 800, height: 800 }, // default
|
|
74
|
+
},
|
|
75
|
+
|
|
76
|
+
// Enable verbose logging
|
|
77
|
+
verbose: false, // default
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Usage Examples
|
|
82
|
+
|
|
83
|
+
### Basic VR Development
|
|
84
|
+
|
|
85
|
+
```javascript
|
|
86
|
+
iwsdkDev({
|
|
87
|
+
emulator: { device: 'metaQuest3' },
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### AR Development with Synthetic Environment
|
|
92
|
+
|
|
93
|
+
```javascript
|
|
94
|
+
iwsdkDev({
|
|
95
|
+
emulator: {
|
|
96
|
+
device: 'metaQuest3',
|
|
97
|
+
environment: 'living_room',
|
|
98
|
+
},
|
|
99
|
+
});
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### AI Agent Mode (default)
|
|
103
|
+
|
|
104
|
+
```javascript
|
|
105
|
+
iwsdkDev({
|
|
106
|
+
emulator: { device: 'metaQuest3' },
|
|
107
|
+
ai: { mode: 'agent', screenshotSize: { width: 500, height: 500 } },
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Collaborate Mode (human + agent share session)
|
|
112
|
+
|
|
113
|
+
```javascript
|
|
114
|
+
iwsdkDev({
|
|
115
|
+
emulator: { device: 'metaQuest3' },
|
|
116
|
+
ai: { mode: 'collaborate' },
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Oversight Mode (watch the agent)
|
|
121
|
+
|
|
122
|
+
```javascript
|
|
123
|
+
iwsdkDev({
|
|
124
|
+
emulator: { device: 'metaQuest3' },
|
|
125
|
+
ai: { mode: 'oversight' },
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### AI Disabled
|
|
130
|
+
|
|
131
|
+
```javascript
|
|
132
|
+
iwsdkDev({
|
|
133
|
+
emulator: { device: 'metaQuest3' },
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## TypeScript Support
|
|
138
|
+
|
|
139
|
+
Full TypeScript support with exported types:
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
import {
|
|
143
|
+
iwsdkDev,
|
|
144
|
+
type DevPluginOptions,
|
|
145
|
+
type EmulatorOptions,
|
|
146
|
+
type AiOptions,
|
|
147
|
+
type AiMode,
|
|
148
|
+
} from '@iwsdk/vite-plugin-dev';
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
MIT © Meta Platforms, Inc.
|
|
@@ -0,0 +1,43 @@
|
|
|
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
|
+
/**
|
|
8
|
+
* Log types for the server-side console capture.
|
|
9
|
+
*/
|
|
10
|
+
export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug' | 'trace';
|
|
11
|
+
export interface CapturedLog {
|
|
12
|
+
timestamp: number;
|
|
13
|
+
level: LogLevel;
|
|
14
|
+
message: string;
|
|
15
|
+
args: string[];
|
|
16
|
+
repeatCount?: number;
|
|
17
|
+
}
|
|
18
|
+
export interface LogQuery {
|
|
19
|
+
count?: number;
|
|
20
|
+
level?: LogLevel | LogLevel[];
|
|
21
|
+
pattern?: string;
|
|
22
|
+
since?: number;
|
|
23
|
+
until?: number;
|
|
24
|
+
}
|
|
25
|
+
export interface ManagedBrowser {
|
|
26
|
+
close(): Promise<void>;
|
|
27
|
+
page: unknown;
|
|
28
|
+
/** Query captured console logs. */
|
|
29
|
+
queryLogs(options?: LogQuery): CapturedLog[];
|
|
30
|
+
/** Take a screenshot of the browser page via CDP. */
|
|
31
|
+
screenshot(): Promise<Buffer>;
|
|
32
|
+
/** Register a callback invoked when the page/browser closes unexpectedly. */
|
|
33
|
+
onClose(callback: () => void): void;
|
|
34
|
+
/** Whether the underlying Playwright page has been closed. */
|
|
35
|
+
isClosed(): boolean;
|
|
36
|
+
}
|
|
37
|
+
export declare function launchManagedBrowser(url: string, headless: boolean, verbose: boolean, viewport?: {
|
|
38
|
+
width: number;
|
|
39
|
+
height: number;
|
|
40
|
+
} | null, screenshotSize?: {
|
|
41
|
+
width: number;
|
|
42
|
+
height: number;
|
|
43
|
+
}): Promise<ManagedBrowser>;
|
|
@@ -0,0 +1,23 @@
|
|
|
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
|
+
export declare function reportToolCall(toolName: string, success: boolean, durationMs: number, error?: string, sessionId?: string, clientVersion?: string): void;
|
|
8
|
+
export declare function reportSessionStart(sessionId: string, opts?: {
|
|
9
|
+
iwsdkVersion?: string;
|
|
10
|
+
device?: string;
|
|
11
|
+
port?: number;
|
|
12
|
+
clientVersion?: string;
|
|
13
|
+
}): void;
|
|
14
|
+
export declare function reportSessionEnd(sessionId: string, opts?: {
|
|
15
|
+
durationMs?: number;
|
|
16
|
+
reason?: string;
|
|
17
|
+
clientVersion?: string;
|
|
18
|
+
}): void;
|
|
19
|
+
export declare function reportError(type: string, message: string, opts?: {
|
|
20
|
+
context?: string;
|
|
21
|
+
sessionId?: string;
|
|
22
|
+
clientVersion?: string;
|
|
23
|
+
}): void;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
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 { Plugin } from 'vite';
|
|
8
|
+
import type { DevPluginOptions } from './types.js';
|
|
9
|
+
export type { DevPluginOptions, AiOptions, AiMode, EmulatorOptions, ProcessedDevOptions, IWERPluginOptions, SEMOptions, AiTool, } from './types.js';
|
|
10
|
+
/**
|
|
11
|
+
* Merge our server entries into an existing (or new) JSON config file.
|
|
12
|
+
* When `managedKeys` is provided, any key in that list that is NOT in
|
|
13
|
+
* `serverEntries` is removed — this prevents stale entries from surviving
|
|
14
|
+
* across config changes (e.g. uninstalling an optional MCP server).
|
|
15
|
+
* Returns true if the file was newly created.
|
|
16
|
+
*/
|
|
17
|
+
export declare function mergeJsonConfig(filePath: string, serverEntries: Record<string, unknown>, jsonKey: string, managedKeys?: string[]): Promise<boolean>;
|
|
18
|
+
/**
|
|
19
|
+
* Remove our managed server keys from a JSON config file.
|
|
20
|
+
* If we originally created the file and the servers section is now empty
|
|
21
|
+
* with no other top-level keys, delete the file entirely.
|
|
22
|
+
*
|
|
23
|
+
* @internal Not called by the plugin at runtime (MCP configs are left in
|
|
24
|
+
* place on shutdown). Kept as a tested utility for potential external use.
|
|
25
|
+
*/
|
|
26
|
+
export declare function unmergeJsonConfig(filePath: string, serverKeys: string[], jsonKey: string, weCreatedFile: boolean): Promise<void>;
|
|
27
|
+
/**
|
|
28
|
+
* Merge our managed TOML block into an existing (or new) config file.
|
|
29
|
+
* Returns true if the file was newly created.
|
|
30
|
+
*/
|
|
31
|
+
export declare function mergeTomlConfig(filePath: string, serverEntries: Record<string, {
|
|
32
|
+
command: string;
|
|
33
|
+
args: string[];
|
|
34
|
+
}>): Promise<boolean>;
|
|
35
|
+
/**
|
|
36
|
+
* Remove our managed TOML block from a config file.
|
|
37
|
+
* If we originally created the file and it's now effectively empty, delete it.
|
|
38
|
+
*
|
|
39
|
+
* @internal Not called by the plugin at runtime (MCP configs are left in
|
|
40
|
+
* place on shutdown). Kept as a tested utility for potential external use.
|
|
41
|
+
*/
|
|
42
|
+
export declare function unmergeTomlConfig(filePath: string, weCreatedFile: boolean): Promise<void>;
|
|
43
|
+
/**
|
|
44
|
+
* Vite plugin for IWSDK development — XR emulation, AI agent tooling, and Playwright browser
|
|
45
|
+
*/
|
|
46
|
+
export declare function iwsdkDev(options?: DevPluginOptions): Plugin;
|
|
47
|
+
/** @deprecated Use `iwsdkDev` instead */
|
|
48
|
+
export declare const injectIWER: typeof iwsdkDev;
|