@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 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;
@@ -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;