### Development Build Instructions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/PROJECT-SUMMARY.md

Installs project dependencies and starts a development server. The application will be accessible at http://localhost:5173.

```bash
npm install
npm run dev
```

--------------------------------

### Example Request to Get Application Profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

An example of how to make an HTTP GET request to retrieve application profiles using a specific app ID and version.

```javascript
const response = await Http.get<ApplicationProfileResponse>(
  'http://app-server/cfg/apps/usd_viewer/versions/2024.1.0/profiles'
);
```

--------------------------------

### Full GFN Streaming Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

A comprehensive example of the GFN configuration, including stream and local settings alongside GFN-specific parameters. This demonstrates a complete setup for GFN streaming.

```json
{
  "source": "gfn",
  "stream": {
    "appServer": "",
    "streamServer": ""
  },
  "gfn": {
    "catalogClientId": "abc-123-xyz",
    "clientId": "client-456-def",
    "cmsId": 789
  },
  "local": {
    "server": "127.0.0.1",
    "signalingPort": 49100,
    "mediaPort": null
  }
}
```

--------------------------------

### Example Application Response Usage

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Demonstrates how to fetch and access data from an application catalog response. Requires an Http client configured for GET requests.

```typescript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
console.log(response.data.items.length); // Number of apps in this page
console.log(response.data.count); // Total apps available
```

--------------------------------

### Unsupported Engine Warning Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Example of an 'Unsupported engine' warning from npm, indicating that the installed Node.js or npm versions do not meet the project's requirements. Consult package.json for correct versions.

```bash
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@nvidia/web-viewer-sample@1.4.0',
npm warn EBADENGINE   required: { node: '^18.0.0', npm: '^10.0.0' },
npm warn EBADENGINE   current: { node: '17.0.0', npm: '10.9.2' }
npm warn EBADENGINE }
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Install all the necessary Node.js dependencies for the project using npm. A new terminal may be required if Node.js was recently installed.

```bash
npm install
```

--------------------------------

### Create Streaming Session Example Request

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

An example JavaScript snippet demonstrating how to construct and send a POST request to create a new streaming session.

```javascript
const payload = {
  id: "usd_viewer",
  version: "2024.1.0",
  profile: "default"
};
const response = await Http.post<typeof payload, StreamItem>(
  'http://stream-server/streaming/stream',
  payload
);
```

--------------------------------

### Example Local Streaming Configuration

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

An example of a complete local streaming configuration, including optional fields and specific IP address. Note that 'stream' and 'gfn' sections are present but not used when 'source' is 'local'.

```json
{
  "source": "local",
  "stream": {
    "appServer": "",
    "streamServer": ""
  },
  "gfn": {
    "catalogClientId": "",
    "clientId": "",
    "cmsId": 0
  },
  "local": {
    "server": "192.168.1.50",
    "signalingPort": 49100,
    "mediaPort": null
  }
}
```

--------------------------------

### Full OKAS Streaming Configuration Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

An example of a complete OKAS streaming configuration, including the 'stream' object with server URLs. The 'gfn' and 'local' sections are included for completeness but are not used when 'source' is 'stream'.

```json
{
  "source": "stream",
  "stream": {
    "appServer": "http://localhost:8080",
    "streamServer": "http://localhost:8081"
  },
  "gfn": {
    "catalogClientId": "",
    "clientId": "",
    "cmsId": 0
  },
  "local": {
    "server": "127.0.0.1",
    "signalingPort": 49100,
    "mediaPort": null
  }
}
```

--------------------------------

### Run Development Server

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Start the development server for the web viewer client. This command is used for local development and testing.

```bash
npm run dev
```

--------------------------------

### Dockerfile for Deployment

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

A Dockerfile example that builds the project, copies the configuration, and sets up the environment to serve the application. It includes multi-stage builds for efficiency.

```dockerfile
FROM node:18
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

FROM node:18
WORKDIR /app
COPY --from=0 /app/dist dist
COPY stream.config.json dist/

EXPOSE 3000
CMD ["npx", "http-server", "dist", "-p", "3000"]
```

--------------------------------

### Example Response for Application Profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Illustrates a successful response body containing the count, limit, offset, and a list of application profiles.

```json
{
  "count": 2,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": "default",
      "name": "Default",
      "description": "Standard configuration"
    },
    {
      "id": "high_performance",
      "name": "High Performance",
      "description": "Optimized for rendering performance"
    }
  ]
}
```

--------------------------------

### Production Build and Preview Instructions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/PROJECT-SUMMARY.md

Builds the project for production and starts a local server to preview the distribution files. Alternatively, the 'dist/' folder can be served with any HTTP server.

```bash
npm run build
npm run preview
```

--------------------------------

### Example Streaming Session Response

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

An example JSON object representing the response from the GET /streaming/stream endpoint, showing active session details.

```json
{
  "count": 1,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": "session-abc123",
      "routes": {
        "192.168.1.100": {
          "routes": [
            {
              "description": "signaling",
              "destination_port": 49100,
              "protocol": "TCP",
              "source_port": 49100
            },
            {
              "description": "media",
              "destination_port": 50000,
              "protocol": "UDP",
              "source_port": 50000
            }
          ]
        }
      }
    }
  ]
}
```

--------------------------------

### Retrieve Application Versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Get a list of available versions for a specific application. This GET request requires an application ID and returns a list of version strings.

```http
GET /cfg/apps/usd_viewer/versions
→ List { 2024.1.0, 2024.2.0, ... }
```

--------------------------------

### Example Successful Session Creation Response

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

An example JSON object representing a successful response (200 OK) after creating a new streaming session, including the session ID and route information.

```json
{
  "id": "session-abc123",
  "routes": {
    "192.168.1.100": {
      "routes": [
        {
          "description": "signaling",
          "destination_port": 49100,
          "protocol": "TCP",
          "source_port": 49100
        }
      ]
    }
  }
}
```

--------------------------------

### GET /cfg/apps/{appId}/versions/{version}/profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Retrieves profile configurations for a specific application version. Use this to get details about available profiles for an app version.

```APIDOC
## GET /cfg/apps/{appId}/versions/{version}/profiles

### Description
Application profile configuration.

### Method
GET

### Endpoint
/cfg/apps/{appId}/versions/{version}/profiles

### Response
#### Success Response (200)
- **count** (number) - Yes - Total number of profiles available
- **limit** (number) - Yes - Maximum items in response
- **offset** (number) - Yes - Starting index in full result set
- **items** (ProfileData[]) - Yes - Array of profile entries
```

--------------------------------

### Send AppStream Message Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Example of constructing and sending a message using the AppStreamMessageType interface. Ensure the message is stringified.

```typescript
const message: AppStreamMessageType = {
  event_type: "openStageRequest",
  payload: { url: "./samples/stage01.usd" }
};
AppStream.sendMessage(JSON.stringify(message));
```

--------------------------------

### StreamItem Example Structure

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Illustrates the expected JSON structure for creating or fetching a streaming session, detailing session ID and network routes.

```json
{
  "id": "session-abc123",
  "routes": {
    "192.168.1.100": {
      "routes": [
        {
          "description": "signaling",
          "destination_port": 49100,
          "protocol": "TCP",
          "source_port": 49100
        },
        {
          "description": "media",
          "destination_port": 50000,
          "protocol": "UDP",
          "source_port": 50000
        }
      ]
    }
  }
}
```

--------------------------------

### Retrieve Applications

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Fetch a list of available applications. This GET request returns a list of application identifiers.

```http
GET /cfg/apps
→ List { usd_viewer, usd_composer, ... }
```

--------------------------------

### GET /cfg/apps

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Retrieves a paginated list of applications from the catalog. Use this endpoint to fetch application entries and their metadata.

```APIDOC
## GET /cfg/apps

### Description
Paginated response from application catalog query.

### Method
GET

### Endpoint
/cfg/apps

### Response
#### Success Response (200)
- **offset** (number) - Yes - Starting index of returned items in full result set
- **limit** (number) - Yes - Maximum number of items requested
- **count** (number) - Yes - Total number of items matching query
- **items** (ApplicationItem[]) - Yes - Array of application entries

### Request Example
```typescript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
console.log(response.data.items.length); // Number of apps in this page
console.log(response.data.count); // Total apps available
```
```

--------------------------------

### Polling Pattern for Kit Ready

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/custom-messaging.md

An example of a polling pattern to check Kit's readiness. It sends a loadingStateQuery and schedules a subsequent check.

```typescript
async _pollForKitReady() {
  if (this.state.isKitReady === true) return
  this._queryLoadingState()
  setTimeout(() => this._pollForKitReady(), 3000);  // Poll every 3 seconds
}
```

--------------------------------

### Check Node.js and npm Versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Verify that your Node.js and npm installations meet the minimum required versions for the application. Refer to package.json for specific version requirements.

```bash
node -v
npm -v
```

--------------------------------

### Error Handling Usage Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Demonstrates how to check an API response for an error detail field and log the error message.

```typescript
const response = await Http.del(endpoint, payload);
if ('detail' in response) {
  console.error(response.detail); // Error message
}
```

--------------------------------

### Example of Terminating a Streaming Session

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Demonstrates how to send a DELETE request to terminate a session and handle potential errors based on the response structure.

```javascript
const payload = { id: "session-abc123" };
const response = await Http.del(
  'http://stream-server/streaming/stream',
  payload
);

if ('detail' in response) {
  console.error('Termination failed:', response.detail);
}
```

--------------------------------

### ApplicationItem Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Represents a single application entry in the catalog. Used for GET /cfg/apps.

```typescript
interface ApplicationItem {
  id: string;
  name: string;
  description: string;
  tags: string[];
}
```

--------------------------------

### GET /cfg/apps

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Retrieves a list of available Kit applications from the application catalog. This endpoint is used to query the available applications that can be launched or viewed.

```APIDOC
## GET /cfg/apps

### Description
Retrieve list of available Kit applications from the application catalog.

### Method
GET

### Endpoint
/cfg/apps

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
```

### Response
#### Success Response (200)
- **offset** (number) - Starting index of items in full result set
- **limit** (number) - Maximum number of items requested
- **count** (number) - Total count of applications available
- **items** (ApplicationItem[]) - Array of application details
  - **items[].id** (string) - Unique application identifier
  - **items[].name** (string) - Human-readable application name
  - **items[].description** (string) - Application description
  - **items[].tags** (string[]) - Metadata tags for categorization

#### Response Example
```json
{
  "offset": 0,
  "limit": 100,
  "count": 2,
  "items": [
    {
      "id": "usd_viewer",
      "name": "USD Viewer",
      "description": "Universal Scene Description viewer",
      "tags": ["viewer", "usd"]
    },
    {
      "id": "omni_usd_composer",
      "name": "Omniverse USD Composer",
      "description": "USD authoring and editing application",
      "tags": ["editor", "usd", "authoring"]
    }
  ]
}
```
```

--------------------------------

### Example USD Primitive Tree Structure

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Illustrates a sample hierarchical structure for USD primitives. The 'children' field is populated dynamically when a parent node is expanded.

```typescript
const prims: USDPrimType[] = [
  {
    name: "World",
    path: "/World",
    children: [
      { name: "Camera", path: "/World/Camera" },
      { name: "Mesh", path: "/World/Mesh", children: [] }
    ]
  }
];
```

--------------------------------

### Get Available Applications

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Retrieves a list of available Kit applications from the application catalog. Use this endpoint to populate application selection menus or catalogs.

```http
GET http://{appServer}/cfg/apps
```

```json
Content-Type: application/json
```

```typescript
interface ApplicationResponse {
  offset: number;
  limit: number;
  count: number;
  items: ApplicationItem[];
}

interface ApplicationItem {
  id: string;
  name: string;
  description: string;
  tags: string[];
}
```

```javascript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
```

```json
{
  "offset": 0,
  "limit": 100,
  "count": 2,
  "items": [
    {
      "id": "usd_viewer",
      "name": "USD Viewer",
      "description": "Universal Scene Description viewer",
      "tags": ["viewer", "usd"]
    },
    {
      "id": "omni_usd_composer",
      "name": "Omniverse USD Composer",
      "description": "USD authoring and editing application",
      "tags": ["editor", "usd", "authoring"]
    }
  ]
}
```

--------------------------------

### USD Asset Component Usage Example

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Demonstrates how to provide an array of USDAssetType objects to the USDAsset component. Accepted URL patterns include relative paths, Omniverse URLs, and template variables.

```typescript
const usdAssets: USDAssetType[] = [
  { name: "Sample 1", url: "./samples/stage01.usd" },
  { name: "Sample 2", url: "./samples/stage02.usd" }
];
<USDAsset usdAssets={usdAssets} onSelectUSDAsset={handleSelect} width={300} />
```

--------------------------------

### Environment Variable Configuration Pattern

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

Example of how to use environment variables for configuration, falling back to static defaults. Vite prefixes environment variables with VITE_ by convention.

```typescript
const streamConfig = {
  source: process.env.VITE_STREAM_SOURCE || StreamConfig.source,
  local: {
    server: process.env.VITE_LOCAL_SERVER || StreamConfig.local.server,
    ...
  }
};
```

--------------------------------

### Local Streaming Data Flow

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/PROJECT-SUMMARY.md

Illustrates the sequence of events for establishing a local WebRTC connection to Kit and managing USD assets. This flow is initiated when the application is started with source="local".

```text
1. User starts app with source="local"
2. AppStream.componentDidMount() reads stream.config.json
3. AppStreamer.connect() establishes WebRTC connection to Kit
4. User selects USD asset from dropdown
5. Window._openSelectedAsset() sends openStageRequest
6. Kit loads USD file, responds with openedStageResult
7. Client polls loadingStateQuery until idle
8. Client fetches stage prims via getChildrenRequest
9. User interacts with tree or viewport
10. Selections sync via selectPrimsRequest and stageSelectionChanged messages
```

--------------------------------

### Get Applications from App Server

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves all available Kit applications from the application catalog server. Handles paginated responses and converts them to a dictionary keyed by application ID. Use when you need a list of all available applications.

```typescript
export async function getApplications(appServer: string): Promise<{ 
  status: number
  data: { [key: string]: ApplicationItem }
}>
```

```typescript
const response = await getApplications('http://app-server:8080');
if (response.status === 200) {
  Object.entries(response.data).forEach(([id, app]) => {
    console.log(`${app.name} (${id}): ${app.description}`);
  });
}
```

--------------------------------

### GET /cfg/apps/{appId}/versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Retrieves version information for a specific application. This endpoint is useful for querying available versions of a given app.

```APIDOC
## GET /cfg/apps/{appId}/versions

### Description
Application version information.

### Method
GET

### Endpoint
/cfg/apps/{appId}/versions

### Response
#### Success Response (200)
- **count** (number) - Yes - Total number of versions available
- **limit** (number) - Yes - Maximum number of items requested
- **offset** (number) - Yes - Starting index in full result set
- **items** (VersionData[]) - Yes - Array of version entries
```

--------------------------------

### Get Application Versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Retrieves the available versions for a specific application identified by its appId. Use this when a user needs to select a particular version of an application.

```http
GET http://{appServer}/cfg/apps/{appId}/versions
```

```typescript
interface ApplicationVersionResponse {
  count: number;
  limit: number;
  offset: number;
  items: VersionData[];
}

interface VersionData {
  version: string;
}
```

```javascript
const response = await Http.get<ApplicationVersionResponse>(
  'http://app-server/cfg/apps/usd_viewer/versions'
);
```

```json
{
  "count": 3,
  "limit": 100,
  "offset": 0,
  "items": [
    { "version": "2024.1.0" },
    { "version": "2024.1.1" },
    { "version": "2024.2.0" }
  ]
}
```

--------------------------------

### Retrieve Application Profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Fetch the available profiles for a specific application version. This GET request requires both application ID and version, returning a list of profile names.

```http
GET /cfg/apps/usd_viewer/versions/2024.1.0/profiles
→ List { default, high_performance, ... }
```

--------------------------------

### Client Example: Handling Custom Messages

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/custom-messaging.md

Handle custom extension messages by checking event types and responding using AppStream.sendMessage. Ensure your custom message has a unique event_type.

```typescript
private _handleCustomEvent(event: any): void {
  if (!event) return;

  // Existing messages...
  if (event.event_type === "openedStageResult") { ... }

  // Custom extension message
  else if (event.event_type === "myCustomMessage") {
    const data = event.payload;
    console.log('Received custom data:', data);

    // Send response back to Kit
    const response = {
      event_type: "myCustomResponse",
      payload: { status: "processed" }
    };
    AppStream.sendMessage(JSON.stringify(response));
  }
}
```

--------------------------------

### Get Application Versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves all available versions for a specific application. Use when you need to know which versions of an application are available for deployment or use. Handles 404 errors if the application is not found.

```typescript
export async function getApplicationVersions(
  appServer: string,
  appId: string
): Promise<{
  status: number
  data: {
    appId: string
    versions: string[]
  }
}>
```

```typescript
const response = await getApplicationVersions('http://app-server:8080', 'usd_viewer');
if (response.status === 200) {
  console.log(`Available versions: ${response.data.versions.join(', ')}`);
}
```

--------------------------------

### GET /cfg/apps/{appId}/versions/{version}/profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Retrieves a list of available execution profiles for a specific application version. This endpoint is useful for understanding the different configurations available for an application.

```APIDOC
## GET /cfg/apps/{appId}/versions/{version}/profiles

### Description
Retrieve available execution profiles for a specific application version.

### Method
GET

### Endpoint
/cfg/apps/{appId}/versions/{version}/profiles

### Parameters
#### Path Parameters
- **appId** (string) - Yes - Unique application identifier
- **version** (string) - Yes - Application version string

### Response
#### Success Response (200)
- **count** (number) - Total profiles available
- **limit** (number) - Items per page
- **offset** (number) - Starting index in full set
- **items** (ProfileData[]) - Array of profile data
  - **items[].id** (string) - Unique profile identifier
  - **items[].name** (string) - Human-readable profile name
  - **items[].description** (string) - Profile description and hardware specs

#### Error Response
- **404** - Application, version, or profile not found

### Response Example
```json
{
  "count": 2,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": "default",
      "name": "Default",
      "description": "Standard configuration"
    },
    {
      "id": "high_performance",
      "name": "High Performance",
      "description": "Optimized for rendering performance"
    }
  ]
}
```
```

--------------------------------

### Handle Loading Progress Activity

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/custom-messaging.md

Logs a message and updates the UI state when the 'updateProgressActivity' event is received. Use this to indicate that an asset loading operation has started.

```typescript
if (event.event_type === "updateProgressActivity") {
  console.log('Kit App communicates progress activity.');
  if (this.state.loadingText !== "Loading Asset...")
    this.setState( {loadingText: "Loading Asset...", isLoading: true} )
}
```

--------------------------------

### Get Application Version Profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves all available execution profiles for a specific application version. Use this to determine the different ways an application version can be run. Handles 404 errors if the application or version is not found.

```typescript
export async function getApplicationVersionProfiles(
  appServer: string,
  appId: string,
  appVersion: string
): Promise<{
  status: number
  data: {
    appId: string
    appVersion: string
    profiles: ProfileData[]
  }
}>
```

```typescript
const response = await getApplicationVersionProfiles(
  'http://app-server:8080',
  'usd_viewer',
  '2024.1.0'
);
if (response.status === 200) {
  response.data.profiles.forEach(profile => {
    console.log(`${profile.name} (${profile.id})`);
  });
}
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Change the current directory to the cloned web-viewer-sample project folder.

```bash
cd web-viewer-sample
```

--------------------------------

### Build Project for Production

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

Build the project for production deployment using the 'npm run build' command.

```bash
npm run build
```

--------------------------------

### Perform GET Request

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/api-reference.md

Use this method to perform a GET request to a specified URL. It returns a promise that resolves to an object containing the HTTP status code and the parsed response data.

```typescript
static async get<T>(url: string): Promise<{ status: number; data: T }>
```

```typescript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
console.log(response.status); // 200
console.log(response.data); // { items: [...], count: 5 }
```

--------------------------------

### Project Structure

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/PROJECT-SUMMARY.md

This snippet outlines the directory and file structure of the web-viewer-sample project. It helps in understanding the organization of source code, configuration files, and build-related assets.

```tree
web-viewer-sample/
├── src/
│   ├── App.tsx                    # Main application container; handles form flow
│   ├── AppStream.tsx              # WebRTC stream component (from AppStreamer)
│   ├── Window.tsx                 # USD viewer with full UI
│   ├── StreamOnlyWindow.tsx       # Minimal stream-only UI
│   ├── Forms.tsx                  # Configuration forms (AppOnly, URLs, Apps, Versions, Profiles)
│   ├── Endpoints.tsx              # OKAS API functions
│   ├── http.ts                    # HTTP utility class for GET/POST/DELETE
│   ├── USDAsset.tsx               # USD asset selector component
│   ├── USDStage.tsx               # USD hierarchy tree view component
│   ├── App.css                    # Global styles
│   ├── USDAsset.css               # Asset selector styles
│   ├── USDStage.css               # Stage tree styles
│   ├── main.tsx                   # React DOM entry point
│   └── vite-env.d.ts              # TypeScript declarations
├── stream.config.json             # Configuration for streaming backends
├── package.json                   # Project metadata and dependencies
├── tsconfig.json                  # TypeScript compiler configuration
├── vite.config.ts                 # Vite build configuration
├── index.html                     # HTML entry point
├── .npmrc                         # NPM registry configuration
└── README.md                      # Documentation
```

--------------------------------

### getApplications

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves all available Kit applications from the application catalog server.

```APIDOC
## GET {appServer}/cfg/apps

### Description
Retrieves all available Kit applications from the application catalog server.

### Method
GET

### Endpoint
`GET {appServer}/cfg/apps`

### Parameters
#### Query Parameters
- **appServer** (string) - Required - Base URL of app server (e.g., "http://localhost:8080")

### Response
#### Success Response (200)
- **status** (number) - HTTP status code from the request
- **data** (object) - Dictionary mapping application IDs to ApplicationItem objects
  - **id** (string) - Application ID
  - **name** (string) - Application name
  - **description** (string) - Application description
  - **tags** (string[]) - Array of tags associated with the application

### Request Example
```typescript
const response = await getApplications('http://app-server:8080');
if (response.status === 200) {
  Object.entries(response.data).forEach(([id, app]) => {
    console.log(`${app.name} (${id}): ${app.description}`);
  });
}
```

### Response Example
```json
{
  "status": 200,
  "data": {
    "usd_viewer": {
      "id": "usd_viewer",
      "name": "USD Viewer",
      "description": "A viewer for USD files.",
      "tags": ["viewer", "usd"]
    }
  }
}
```
```

--------------------------------

### Clone Repository for Kit 107.3.1+

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Clone the web-viewer-sample repository using the branch compatible with Kit versions 107.3.1 and higher.

```bash
git clone -b 1.5.2 https://github.com/NVIDIA-Omniverse/web-viewer-sample.git
```

--------------------------------

### Get Streaming Sessions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves a list of all active streaming sessions from the specified stream server.

```APIDOC
## GET /streaming/stream

### Description
Retrieves a list of all active streaming sessions.

### Method
GET

### Endpoint
`GET {streamServer}/streaming/stream`

### Parameters
#### Query Parameters
- **streamServer** (string) - Required - Base URL of the stream server.

### Response
#### Success Response (200)
- **status** (number) - HTTP status code.
- **data** (StreamingResponse) - Full StreamingResponse object containing session details.

### Response Structure
```typescript
interface StreamingResponse {
  count: number;
  items: StreamItem[];
  limit: number;
  offset: number;
}

interface StreamItem {
  id: string;
  routes: { [key: string]: StreamRoutes };
}
```

### Response Example
```json
{
  "status": 200,
  "data": {
    "count": 1,
    "items": [
      {
        "id": "session-123",
        "routes": {}
      }
    ],
    "limit": 10,
    "offset": 0
  }
}
```
```

--------------------------------

### Clone Repository for Kit 1.6.1+

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/README.md

Clone the web-viewer-sample repository using the branch compatible with Kit versions 1.6.1 up to 107.3.1.

```bash
git clone -b 1.4.1 https://github.com/NVIDIA-Omniverse/web-viewer-sample.git
```

--------------------------------

### VersionData Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Represents version information for a specific application. Used for GET /cfg/apps/{appId}/versions.

```typescript
interface VersionData {
  version: string;
}
```

--------------------------------

### Minimal Local Streaming Configuration

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

Provides the minimum required JSON configuration to enable direct connection to a local Kit application. Ensure the 'source' is set to 'local' and provide the server IP and ports.

```json
{
  "source": "local",
  "local": {
    "server": "127.0.0.1",
    "signalingPort": 49100,
    "mediaPort": null
  }
}
```

--------------------------------

### ApplicationResponse Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Defines the structure for paginated responses when querying the application catalog. Used for GET /cfg/apps.

```typescript
interface ApplicationResponse {
  offset: number;
  limit: number;
  count: number;
  items: ApplicationItem[];
}
```

--------------------------------

### Serve Production Build with http-server

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

Serve the production build located in the dist directory using Node.js http-server.

```bash
# Using Node.js http-server
npx http-server dist
```

--------------------------------

### Validate Endpoints

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Verify the availability of essential configuration and streaming endpoints. These GET requests should return a 200 OK status.

```http
GET /cfg/apps 
→ 200 OK
GET /streaming/stream 
→ 200 OK
```

--------------------------------

### Get Streaming Sessions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves a list of all active streaming sessions from a stream server. Use this to monitor current sessions.

```typescript
export async function getStreamingSessions(
  streamServer: string
): Promise<{
  status: number
  data: StreamingResponse
}>
```

```typescript
interface StreamingResponse {
  count: number;
  items: StreamItem[];
  limit: number;
  offset: number;
}

interface StreamItem {
  id: string;
  routes: { [key: string]: StreamRoutes };
}
```

```typescript
const response = await getStreamingSessions('http://stream-server:8081');
console.log(`Active sessions: ${response.data.count}`);
response.data.items.forEach(session => {
  console.log(`Session: ${session.id}`);
});
```

--------------------------------

### Copy Configuration to Dist Directory

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

After building the project, copy the stream.config.json file to the dist directory using the 'cp' command.

```bash
cp stream.config.json dist/
```

--------------------------------

### ProfileData Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Represents a profile configuration for an application version. Used for GET /cfg/apps/{appId}/versions/{version}/profiles.

```typescript
interface ProfileData {
  id: string;
  name: string;
  description: string;
}
```

--------------------------------

### AppProps Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/api-reference.md

Props required for initializing the Window component.

```APIDOC
## AppProps Interface

### Description
Props required for initializing the Window component.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| sessionId | string | Yes | — | Unique identifier for the streaming session |
| backendUrl | string | Yes | — | Base URL of the backend streaming service |
| signalingserver | string | Yes | — | IP address or hostname of signaling server |
| signalingport | number | Yes | — | Port number for signaling protocol |
| mediaserver | string | Yes | — | IP address or hostname of media server |
| mediaport | number | Yes | — | Port number for media streaming |
| accessToken | string | Yes | — | Authentication token (if required) |
| onStreamFailed | () => void | Yes | — | Callback fired if stream connection fails |
```

--------------------------------

### Create Streaming Session (POST /streaming/stream)

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Use this endpoint to initiate a new streaming session for a specified Kit application, version, and profile. The request body requires these parameters.

```http
POST http://{streamServer}/streaming/stream
Content-Type: application/json

{
  "id": "usd_viewer",
  "version": "2024.1.0",
  "profile": "default"
}
```

--------------------------------

### ApplicationVersionResponse Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Defines the structure for paginated responses when querying application versions. Used for GET /cfg/apps/{appId}/versions.

```typescript
interface ApplicationVersionResponse {
  count: number;
  limit: number;
  offset: number;
  items: VersionData[];
}
```

--------------------------------

### Retrieve Applications

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Fetches a list of available applications that can be launched or connected to.

```APIDOC
## GET /cfg/apps 
### Description
Retrieves a list of available applications.
### Method
GET
### Endpoint
/cfg/apps
### Response
#### Success Response (200)
- List (array) - A list of application identifiers (e.g., { usd_viewer, usd_composer, ... }).
```

--------------------------------

### GET /streaming/stream/{sessionId}

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Retrieves the configuration of a specific streaming session. This endpoint is used to poll the session status during its creation phase.

```APIDOC
## GET /streaming/stream/{sessionId}

### Description
Retrieve configuration of a specific streaming session. Used to poll session status during creation.

### Method
GET

### Endpoint
`/streaming/stream/{sessionId}`

### Parameters
#### Path Parameters
- **sessionId** (string) - Yes - Unique session identifier from POST response

### Request Example
```http
GET http://{streamServer}/streaming/stream/{sessionId}
```

### Response
#### Success Response (200)
- **id** (string) - Session identifier
- **routes** (object) - Server addresses mapped to route configurations

#### Response Example
```json
{
  "id": "string",
  "routes": { "key": { "StreamRoutes" } }
}
```

### Usage Pattern
When POST /streaming/stream returns status 202, client must poll this endpoint repeatedly until status becomes 200:

```javascript
async function pollForSessionReady(sessionId: string) {
  try {
    const response = await Http.get<StreamItem>(
      `http://stream-server/streaming/stream/${sessionId}`
    );
    if (response.status === 200) {
      // Session ready; extract routes and connect
      setupStream(response.data);
    } else if (response.status === 202) {
      // Still initializing; retry after delay
      setTimeout(() => pollForSessionReady(sessionId), 10000);
    }
  } catch (error) {
    console.error('Poll error:', error);
  }
}
```
```

--------------------------------

### openStageRequest

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/custom-messaging.md

Requests to load a USD file into the Kit viewport. The response is an `openedStageResult` message.

```APIDOC
## openStageRequest

### Description
Request to load a USD file into the Kit viewport.

### Payload
```typescript
{
  event_type: "openStageRequest",
  payload: {
    url: string  // Path to USD file
  }
}
```

### Payload Fields
- **url** (string) - USD file path or URI (e.g., "./samples/stage01.usd" or "${omni.usd_viewer.samples}/samples_data/stage01.usd")

### Request Example
```typescript
const message = {
  event_type: "openStageRequest",
  payload: { url: "./samples/stage01.usd" }
};
AppStream.sendMessage(JSON.stringify(message));
```

### Expected Response
`openedStageResult` message with result field indicating success or error.
```

--------------------------------

### Connect Stream

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Establish a WebRTC connection using the extracted stream configuration and source details. This step confirms the stream is ready for use.

```javascript
AppStreamer.connect({ streamConfig, streamSource })
→ WebRTC connection established
```

--------------------------------

### Get Streaming Session Info

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves configuration and route information for a specific streaming session. This is useful for polling session status during creation.

```APIDOC
## GET /streaming/stream/{sessionId}

### Description
Retrieves configuration and route information for a specific streaming session. Used to poll session status during creation.

### Method
GET

### Endpoint
`GET {streamServer}/streaming/stream/{sessionId}`

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - Session ID obtained from `createStreamingSession`.
#### Query Parameters
- **streamServer** (string) - Required - Base URL of the stream server.

### Response
#### Success Response (200)
- **status** (number) - HTTP status code (200 for ready, 202 for pending, 404 for not found).
- **data** (StreamItem) - StreamItem with routes if status is 200.

### Response Example
```json
{
  "status": 200,
  "data": {
    "id": "session-123",
    "routes": {
      "192.168.1.100": {
        "routes": [
          {
            "description": "signaling",
            "source_port": 8080
          },
          {
            "description": "media",
            "source_port": 8081
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Get Streaming Session Info

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves configuration and route information for a specific streaming session. Useful for polling session status during creation.

```typescript
export async function getStreamingSessionInfo(
  streamServer: string,
  sessionId: string
): Promise<{
  status: number
  data: StreamItem
}>
```

```typescript
async function pollForSessionReady(sessionId: string) {
  const response = await getStreamingSessionInfo(streamServer, sessionId);
  
  if (response.status === 200) {
    // Ready; extract routes
    const serverIP = Object.keys(response.data.routes)[0];
    const routeData = response.data.routes[serverIP].routes;
    setupStream(response.data);
  } else if (response.status === 202) {
    // Still initializing; retry
    setTimeout(() => pollForSessionReady(sessionId), 10000);
  } else {
    // Error or not found
    console.error('Session failed');
  }
}
```

```typescript
const sessionItem = response.data;
const serverIP = Object.keys(sessionItem.routes)[0];  // First (usually only) server
const routeData = sessionItem.routes[serverIP].routes;

const signalingData = routeData.find((item: any) => item.description === 'signaling');
const mediaData = routeData.find((item: any) => item.description === 'media');

const signalingPort = signalingData.source_port;
const mediaPort = mediaData.source_port;
```

--------------------------------

### Create Session

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Initiates a new streaming session for a specified application, version, and profile.

```APIDOC
## POST /streaming/stream 
### Description
Creates a new streaming session.
### Method
POST
### Endpoint
/streaming/stream
### Request Body
- **id** (string) - Required - The identifier of the application (e.g., "usd_viewer").
- **version** (string) - Required - The version of the application (e.g., "2024.1.0").
- **profile** (string) - Required - The profile to use for the session (e.g., "default").
### Response
#### Success Response (202 Accepted)
Returns a 202 Accepted status with a sessionId.
- **sessionId** (string) - The unique identifier for the created session.
```

--------------------------------

### ApplicationProfileResponse Interface

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/types.md

Defines the structure for paginated responses when querying application profiles. Used for GET /cfg/apps/{appId}/versions/{version}/profiles.

```typescript
interface ApplicationProfileResponse {
  count: number;
  limit: number;
  offset: number;
  items: ProfileData[];
}
```

--------------------------------

### Http.get

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/api-reference.md

Performs a GET request to the specified URL. Returns a promise that resolves to an object containing the HTTP status code and the parsed response data.

```APIDOC
## Http.get<T>(url: string): Promise<{ status: number; data: T }>

### Description
Performs a GET request to the specified URL.

### Method
GET

### Endpoint
`url` (string) - Full URL endpoint to fetch

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const response = await Http.get<ApplicationResponse>('http://app-server/cfg/apps');
console.log(response.status); // 200
console.log(response.data); // { items: [...], count: 5 }
```

### Response
#### Success Response (200)
- **status** (number) - HTTP status code
- **data** (T) - Parsed response data

#### Response Example
```json
{
  "status": 200,
  "data": {
    "items": [],
    "count": 5
  }
}
```
```

--------------------------------

### getApplicationVersions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints-internal.md

Retrieves all available versions of a specific application.

```APIDOC
## GET {appServer}/cfg/apps/{appId}/versions

### Description
Retrieves all available versions of a specific application.

### Method
GET

### Endpoint
`GET {appServer}/cfg/apps/{appId}/versions`

### Parameters
#### Path Parameters
- **appServer** (string) - Required - Base URL of app server
- **appId** (string) - Required - Application ID (from getApplications)

### Response
#### Success Response (200)
- **status** (number) - HTTP status code
- **data** (object)
  - **appId** (string) - The requested application ID
  - **versions** (string[]) - Array of version strings

### Request Example
```typescript
const response = await getApplicationVersions('http://app-server:8080', 'usd_viewer');
if (response.status === 200) {
  console.log(`Available versions: ${response.data.versions.join(', ')}`);
}
```

### Response Example
```json
{
  "status": 200,
  "data": {
    "appId": "usd_viewer",
    "versions": ["2024.1.0", "2023.3.0"]
  }
}
```
```

--------------------------------

### OKAS Streaming Data Flow

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/PROJECT-SUMMARY.md

Details the steps involved in setting up a streaming session using OKAS (Omniverse Kit App Streaming). This flow includes user input for server URLs, application selection, and session establishment via API calls.

```text
1. User starts app with source="stream"
2. User enters App Server and Stream Server URLs via ServerURLsForm
3. Client validates URLs and fetches application catalog
4. User selects app, version, profile through form sequence
5. Client calls POST /streaming/stream to create session
6. Server returns session ID (202) or ready config (200)
7. Client polls GET /streaming/stream/{sessionId} until ready (200)
8. Client extracts signaling/media routes from response
9. AppStreamer.connect() establishes connection with routes
10. (Rest identical to local flow)
```

--------------------------------

### Default Local Stream Configuration

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

The default stream.config.json file is provided for local streaming. It assumes Kit is running on localhost with signaling port 49100 and auto-detected media port.

```json
{
    "source": "local",
    "stream": {
        "appServer": "",
        "streamServer": ""
    },
    "gfn": {
        "catalogClientId": "",
        "clientId": "",
        "cmsId": 0
    },
    "local": {
        "server": "127.0.0.1",
        "signalingPort": 49100,
        "mediaPort": null
    }
}
```

--------------------------------

### Retrieve Versions

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Fetches a list of available versions for a specific application.

```APIDOC
## GET /cfg/apps/{appName}/versions 
### Description
Retrieves a list of available versions for a specified application.
### Method
GET
### Endpoint
/cfg/apps/{appName}/versions
### Parameters
#### Path Parameters
- **appName** (string) - Required - The name of the application.
### Response
#### Success Response (200)
- List (array) - A list of version strings (e.g., { 2024.1.0, 2024.2.0, ... }).
```

--------------------------------

### Retrieve Application Profiles

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/endpoints.md

Use this endpoint to get a list of available execution profiles for a specific application version. Ensure the application ID and version are correctly specified.

```http
GET http://{appServer}/cfg/apps/{appId}/versions/{version}/profiles
```

--------------------------------

### Update Local Configuration and Restart Server

Source: https://github.com/nvidia-omniverse/web-viewer-sample/blob/main/_autodocs/configuration.md

Edit the stream.config.json file locally using nano and restart the development server with 'npm run dev' to apply changes. Configuration changes are not hot-reloaded.

```bash
# Edit locally
nano stream.config.json

# Restart development server
npm run dev
```