### HTML Canvas Setup for Schematic Viewer

Source: https://github.com/enginehub/schematicwebviewer/blob/master/README.md

Include this HTML in your page to create a canvas element where the schematic will be rendered. Ensure the canvas ID matches the one used in your JavaScript.

```html
<canvas id="schematicRenderer" , width="500," height="500"></canvas>
```

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

### Multiple schematics on the same page

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Demonstrates how to render multiple schematics simultaneously on the same page, each in its own canvas element. It includes examples of setting unique options for each schematic and handling window resizing and page navigation.

```APIDOC
## Multiple schematics on the same page

Each call to `renderSchematic` creates an independent BabylonJS `Engine` and `Scene`. Multiple canvases can render simultaneously; just ensure each canvas element has a unique selector.

```html
<canvas id="viewer-a" width="400" height="400"></canvas>
<canvas id="viewer-b" width="400" height="400"></canvas>
```

```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';

const CORS = 'https://corsanywhere.enginehub.org/';

const [handlesA, handlesB] = await Promise.all([
  renderSchematic(
    document.querySelector<HTMLCanvasElement>('#viewer-a')!,
    schemBase64A,
    { corsBypassUrl: CORS, orbit: true, renderArrow: true }
  ),
  renderSchematic(
    document.querySelector<HTMLCanvasElement>('#viewer-b')!,
    schemBase64B,
    { corsBypassUrl: CORS, renderBars: true, antialias: true }
  ),
]);

// Resize both viewers together when the window resizes
window.addEventListener('resize', () => {
  handlesA.setSize(window.innerWidth / 2, 400);
  handlesB.setSize(window.innerWidth / 2, 400);
});

// Dispose both when navigating away
window.addEventListener('beforeunload', () => {
  handlesA.destroy();
  handlesB.destroy();
});
```
```

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

### SchematicRenderOptions - Full Options Reference

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Demonstrates the full range of options available for customizing schematic rendering, including viewport size, CORS bypass, custom JAR resolvers, resource packs, visual features, quality settings, and control flags.

```APIDOC
## SchematicRenderOptions - Full Options Reference

Complete TypeScript interface controlling every aspect of the rendering pipeline.

```typescript
import type { SchematicRenderOptions, GetClientJarUrlProps } from '@enginehub/schematicwebviewer';

const options: SchematicRenderOptions = {
  // Viewport size — prefer object form; number form is deprecated
  size: { width: 500, height: 500 },

  // CORS proxy URL (required by the default getClientJarUrl implementation)
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',

  // Custom JAR resolver — bypass the default EngineHub Cassette Deck lookup
  getClientJarUrl: async ({ dataVersion, corsBypassUrl }: GetClientJarUrlProps) => {
    // Return URL of a Minecraft client JAR compatible with dataVersion
    const manifest = await fetch(
      `${corsBypassUrl}https://services.enginehub.org/cassette-deck/minecraft-versions/find?dataVersion=${dataVersion}`
    ).then(r => r.json());
    return `${corsBypassUrl}${manifest[0].clientJarUrl}`;
  },

  // Additional resource packs applied on top of the client JAR (in priority order)
  resourcePacks: [
    'https://cdn.example.com/base-pack.zip',
    'https://cdn.example.com/overlay-pack.zip',  // highest priority
  ],

  // Visual features
  renderArrow: true,          // direction indicator arrow
  renderBars: true,           // 3-D bounding grid
  orbit: true,                // auto-rotate camera
  orbitSpeed: 0.02,           // radians per frame

  // Quality
  antialias: true,
  backgroundColor: 'transparent',  // or a hex number like 0xffffff

  // Control
  disableAutoRender: false,   // set true to call handles.render() manually
  debug: false,               // opens the BabylonJS inspector overlay
};
```
```

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

### Configure Schematic Rendering Options

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Set various rendering parameters like viewport size, CORS bypass URL, custom JAR resolvers, resource packs, visual features, quality settings, and control flags.

```typescript
import type { SchematicRenderOptions, GetClientJarUrlProps } from '@enginehub/schematicwebviewer';

const options: SchematicRenderOptions = {
  // Viewport size — prefer object form; number form is deprecated
  size: { width: 500, height: 500 },

  // CORS proxy URL (required by the default getClientJarUrl implementation)
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',

  // Custom JAR resolver — bypass the default EngineHub Cassette Deck lookup
  getClientJarUrl: async ({ dataVersion, corsBypassUrl }: GetClientJarUrlProps) => {
    // Return URL of a Minecraft client JAR compatible with dataVersion
    const manifest = await fetch(
      `${corsBypassUrl}https://services.enginehub.org/cassette-deck/minecraft-versions/find?dataVersion=${dataVersion}`
    ).then(r => r.json());
    return `${corsBypassUrl}${manifest[0].clientJarUrl}`;
  },

  // Additional resource packs applied on top of the client JAR (in priority order)
  resourcePacks: [
    'https://cdn.example.com/base-pack.zip',
    'https://cdn.example.com/overlay-pack.zip',  // highest priority
  ],

  // Visual features
  renderArrow: true,          // direction indicator arrow
  renderBars: true,           // 3-D bounding grid
  orbit: true,                // auto-rotate camera
  orbitSpeed: 0.02,           // radians per frame

  // Quality
  antialias: true,
  backgroundColor: 'transparent',  // or a hex number like 0xffffff

  // Control
  disableAutoRender: false,   // set true to call handles.render() manually
  debug: false,               // opens the BabylonJS inspector overlay
};

```

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

### Provide Custom Minecraft JAR Resolver

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Replace the default JAR resolution logic with a custom async function to serve JARs from self-hosted mirrors or offline environments. Ensure the returned URL is fetchable and prepended with the CORS bypass URL if necessary.

```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';
import type { GetClientJarUrlProps } from '@enginehub/schematicwebviewer';

async function myJarResolver({ dataVersion, corsBypassUrl }: GetClientJarUrlProps): Promise<string> {
  // Map data versions to pre-hosted JAR files
  const VERSION_MAP: Record<number, string> = {
    3700: 'https://assets.example.com/jars/1.20.4-client.jar',
    3465: 'https://assets.example.com/jars/1.19.4-client.jar',
  };
  const url = VERSION_MAP[dataVersion] ?? 'https://assets.example.com/jars/latest-client.jar';
  // Prepend the CORS proxy so the browser can reach the asset server
  return `${corsBypassUrl}${url}`;
}

const handles = await renderSchematic(canvas, base64Schematic, {
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',
  getClientJarUrl: myJarResolver,
  orbit: true,
});

```

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

### Custom getClientJarUrl - Provide your own Minecraft JAR source

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Shows how to replace the default JAR URL resolver with a custom asynchronous function. This is useful for self-hosted mirrors or offline environments, allowing you to map data versions to specific JAR file URLs.

```APIDOC
## Custom `getClientJarUrl` — Provide your own Minecraft JAR source

By default the library uses the EngineHub Cassette Deck service to resolve the correct client JAR URL for the schematic's `dataVersion`. You can replace this with any async function that returns a fetchable JAR URL, which is useful for self-hosted mirrors or offline environments.

```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';
import type { GetClientJarUrlProps } from '@enginehub/schematicwebviewer';

async function myJarResolver({ dataVersion, corsBypassUrl }: GetClientJarUrlProps): Promise<string> {
  // Map data versions to pre-hosted JAR files
  const VERSION_MAP: Record<number, string> = {
    3700: 'https://assets.example.com/jars/1.20.4-client.jar',
    3465: 'https://assets.example.com/jars/1.19.4-client.jar',
  };
  const url = VERSION_MAP[dataVersion] ?? 'https://assets.example.com/jars/latest-client.jar';
  // Prepend the CORS proxy so the browser can reach the asset server
  return `${corsBypassUrl}${url}`;
}

const handles = await renderSchematic(canvas, base64Schematic, {
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',
  getClientJarUrl: myJarResolver,
  orbit: true,
});
```
```

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

### Render Minecraft Schematic with Options

Source: https://github.com/enginehub/schematicwebviewer/blob/master/README.md

Use the `renderSchematic` function to display a Base64 encoded schematic on a canvas. Configure rendering with an options object, including size, CORS bypass URL, and rendering preferences.

```javascript
renderSchematic(document.querySelector('#schematicRenderer'), SCHEMATIC_FILE, {
    size: 500,
    renderArrow: false,
    renderBars: false,
    corsBypassUrl: 'https://url-to-cors-anywhere/',
});
```

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

### Schematic Render Options Interface

Source: https://github.com/enginehub/schematicwebviewer/blob/master/README.md

Defines the available options for configuring schematic rendering, including size, CORS bypass, resource pack URLs, rendering elements, and performance settings.

```typescript
interface SchematicRenderOptions {
    /**
     * Usage as number is deprecated and will be removed
     */
    size?: number | { width: number; height: number };
    /**
     * A url of a cors-anywhere instance to allow access to MC server jars. Required by the default `getClientJarUrl` function
     */
    corsBypassUrl?: string;
    /**
     * A function that returns the url of the client jar to use. Defaults to using the EngineHub Cassette Deck service
     */
    getClientJarUrl?: (props: GetClientJarUrlProps) => Promise<string>;
    /**
     * A list of resource pack URLs in priority order
     */
    resourcePacks?: string[];
    /**
     * Whether a grid should be rendered
     */
    renderBars?: boolean;
    /**
     * Whether an arrow to show direction should be rendered
     */
    renderArrow?: boolean;
    /**
     * Whether the view should automatically rotate when not being dragged by the user
     */
    orbit?: boolean;
    /**
     * The speed at which the view should orbit (default: 0.02)
     */
    orbitSpeed?: number;
    /**
     * Whether antialiasing should be enabled
     */
    antialias?: boolean;
    /**
     * Background color of the canvas (default: 0xffffff), or if it should be transparent
     */
    backgroundColor?: number | 'transparent';
    /**
     * Whether to enable further debug information
     */
    debug?: boolean;
    /**
     * Only update the view when {@link SchematicHandles#render} is called. This is useful if you want to control the rendering yourself
     */
    disableAutoRender?: boolean;
}
```

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

### Control Schematic Rendering with SchematicHandles

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

The SchematicHandles object, returned by `renderSchematic`, allows dynamic resizing, manual render loop control, access to the BabylonJS engine, and resource cleanup. Use `disableAutoRender: true` to manage the render loop manually.

```typescript
import { renderSchematic, type SchematicHandles } from '@enginehub/schematicwebviewer';

const handles: SchematicHandles = await renderSchematic(canvas, base64Schematic, {
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',
  disableAutoRender: true,   // We will drive the loop ourselves
});

// --- Resize the canvas ---
handles.setSize(1280, 720);        // preferred: explicit width × height
// handles.resize(512);            // deprecated square shorthand

// --- Manual render loop (when disableAutoRender: true) ---
let frameId: number;
function loop() {
  handles.render();
  frameId = requestAnimationFrame(loop);
}
frameId = requestAnimationFrame(loop);

// --- Access the raw BabylonJS Engine for advanced use ---
const engine = handles.getEngine();
engine.setHardwareScalingLevel(0.5);  // lower resolution for performance

// --- Clean up all GPU resources when the viewer is unmounted ---
cancelAnimationFrame(frameId);
handles.destroy();
```

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

### Render Schematic onto a Canvas

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Use this function to render a schematic. It requires an HTMLCanvasElement, Base64-encoded schematic data, and an options object. The function returns a Promise that resolves with a SchematicHandles object.

```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';

// Base64-encoded .schem / .schematic file (read from <input type="file"> or fetched from a server)
const base64Schematic = await fetch('/my-structure.schem')
  .then(r => r.arrayBuffer())
  .then(buf => btoa(String.fromCharCode(...new Uint8Array(buf))));

const canvas = document.querySelector<HTMLCanvasElement>('#viewer')!;

const handles = await renderSchematic(canvas, base64Schematic, {
  // Canvas dimensions
  size: { width: 800, height: 600 },

  // CORS proxy required so the browser can fetch Mojang's client JAR
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',

  // Optional: supply extra resource packs (higher-priority packs come last)
  resourcePacks: ['https://example.com/my-texture-pack.zip'],

  // Camera auto-rotation
  orbit: true,
  orbitSpeed: 0.015,

  // Visual overlays
  renderArrow: true,   // shows a north-facing direction arrow
  renderBars: true,    // shows a 3-D bounding-box grid

  // Rendering quality
  antialias: true,
  backgroundColor: 0x87ceeb,   // sky-blue; use 'transparent' for alpha canvas

  // Advanced: take full control of the render loop
  disableAutoRender: false,

  debug: false,
});

console.log('Scene ready!');
// handles is a SchematicHandles object (see below)
```

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

### Render Multiple Schematics Simultaneously

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Render multiple schematics on the same page by using separate canvas elements for each. Each canvas requires a unique selector, and event listeners should be set up to manage resizing and cleanup for all viewers.

```html
<canvas id="viewer-a" width="400" height="400"></canvas>
<canvas id="viewer-b" width="400" height="400"></canvas>

```

```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';

const CORS = 'https://corsanywhere.enginehub.org/';

const [handlesA, handlesB] = await Promise.all([
  renderSchematic(
    document.querySelector<HTMLCanvasElement>('#viewer-a')!,
    schemBase64A,
    { corsBypassUrl: CORS, orbit: true, renderArrow: true }
  ),
  renderSchematic(
    document.querySelector<HTMLCanvasElement>('#viewer-b')!,
    schemBase64B,
    { corsBypassUrl: CORS, renderBars: true, antialias: true }
  ),
]);

// Resize both viewers together when the window resizes
window.addEventListener('resize', () => {
  handlesA.setSize(window.innerWidth / 2, 400);
  handlesB.setSize(window.innerWidth / 2, 400);
});

// Dispose both when navigating away
window.addEventListener('beforeunload', () => {
  handlesA.destroy();
  handlesB.destroy();
});

```

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

### SchematicHandles

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

A post-render control object returned by `renderSchematic`. It provides methods for resizing the viewport, manually controlling the render loop, accessing the underlying BabylonJS engine, and cleaning up resources.

```APIDOC
## SchematicHandles — Post-render control object

### Description
The object returned by `renderSchematic`. Provides methods to dynamically resize the viewport, manually drive the render loop, inspect the BabylonJS engine, and release all WebGL resources.

### Methods
- **`setSize(width: number, height: number): void`**: Resizes the canvas to the specified width and height.
- **`resize(size: number): void`**: Deprecated shorthand for resizing to a square canvas.
- **`render(): void`**: Manually triggers a single render frame. Useful when `disableAutoRender` is true.
- **`getEngine(): BABYLON.Engine`**: Returns the underlying BabylonJS engine instance for advanced manipulation.
- **`destroy(): void`**: Cleans up all WebGL resources associated with the scene.

### Example Usage
```typescript
import { renderSchematic, type SchematicHandles } from '@enginehub/schematicwebviewer';

const handles: SchematicHandles = await renderSchematic(canvas, base64Schematic, {
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',
  disableAutoRender: true,   // We will drive the loop ourselves
});

// --- Resize the canvas ---
handles.setSize(1280, 720);        // preferred: explicit width × height
// handles.resize(512);            // deprecated square shorthand

// --- Manual render loop (when disableAutoRender: true) ---
let frameId: number;
function loop() {
  handles.render();
  frameId = requestAnimationFrame(loop);
}
frameId = requestAnimationFrame(loop);

// --- Access the raw BabylonJS Engine for advanced use ---
const engine = handles.getEngine();
engine.setHardwareScalingLevel(0.5);  // lower resolution for performance

// --- Clean up all GPU resources when the viewer is unmounted ---
cancelAnimationFrame(frameId);
handles.destroy();
```
```

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

### renderSchematic(canvas, schematic, options)

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

The primary function to render a schematic onto an HTML canvas. It asynchronously decodes schematic data, fetches necessary assets, and sets up an interactive 3D scene. It returns a `SchematicHandles` object for further control.

```APIDOC
## renderSchematic(canvas, schematic, options) — Render a schematic onto a canvas

### Description
The primary (and only public) entry point of the library. Accepts an `HTMLCanvasElement`, a Base64-encoded gzip-compressed NBT schematic string, and a `SchematicRenderOptions` configuration object. Returns a `Promise<SchematicHandles>` that resolves once the scene is fully built and the render loop is running.

### Method
```typescript
import { renderSchematic } from '@enginehub/schematicwebviewer';

// Base64-encoded .schem / .schematic file (read from <input type="file"> or fetched from a server)
const base64Schematic = await fetch('/my-structure.schem')
  .then(r => r.arrayBuffer())
  .then(buf => btoa(String.fromCharCode(...new Uint8Array(buf))));

const canvas = document.querySelector<HTMLCanvasElement>('#viewer')!;

const handles = await renderSchematic(canvas, base64Schematic, {
  // Canvas dimensions
  size: { width: 800, height: 600 },

  // CORS proxy required so the browser can fetch Mojang's client JAR
  corsBypassUrl: 'https://corsanywhere.enginehub.org/',

  // Optional: supply extra resource packs (higher-priority packs come last)
  resourcePacks: ['https://example.com/my-texture-pack.zip'],

  // Camera auto-rotation
  orbit: true,
  orbitSpeed: 0.015,

  // Visual overlays
  renderArrow: true,   // shows a north-facing direction arrow
  renderBars: true,    // shows a 3-D bounding-box grid

  // Rendering quality
  antialias: true,
  backgroundColor: 0x87ceeb,   // sky-blue; use 'transparent' for alpha canvas

  // Advanced: take full control of the render loop
  disableAutoRender: false,

  debug: false,
});

console.log('Scene ready!');
// handles is a SchematicHandles object (see below)
```
```

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

### Render Schematic in React Component

Source: https://context7.com/enginehub/schematicwebviewer/llms.txt

Wraps the `renderSchematic` function in a React component using `useEffect` to manage the renderer's lifecycle with the component's mount and unmount events. Ensure `corsBypassUrl` is provided for cross-origin resource fetching.

```tsx
import { useEffect, useRef } from 'react';
import { renderSchematic, type SchematicHandles } from '@enginehub/schematicwebviewer';

interface Props {
  schematicBase64: string;
  corsBypassUrl: string;
}

export function SchematicViewer({ schematicBase64, corsBypassUrl }: Props) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const handlesRef = useRef<SchematicHandles | null>(null);

  useEffect(() => {
    let cancelled = false;

    renderSchematic(canvasRef.current!, schematicBase64, {
      corsBypassUrl,
      size: { width: 500, height: 500 },
      orbit: true,
      antialias: true,
    }).then(handles => {
      if (cancelled) {
        handles.destroy();
      } else {
        handlesRef.current = handles;
      }
    });

    return () => {
      cancelled = true;
      handlesRef.current?.destroy();
      handlesRef.current = null;
    };
  }, [schematicBase64, corsBypassUrl]);

  return <canvas ref={canvasRef} width={500} height={500} />;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.