### Show Notifications (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Provides examples of displaying toast notifications to the user with different severity levels (default, SUCCESS, WARNING, ERROR, INFO) and demonstrates how to programmatically close a notification. Uses the '@owlbear-rodeo/sdk' package.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Show default notification
  const id1 = await OBR.notification.show("Action completed");

  // Show notification with variant
  const id2 = await OBR.notification.show("Success!", "SUCCESS");
  const id3 = await OBR.notification.show("Warning message", "WARNING");
  const id4 = await OBR.notification.show("Error occurred", "ERROR");
  const id5 = await OBR.notification.show("Information", "INFO");

  // Close notification programmatically
  setTimeout(async () => {
    await OBR.notification.close(id1);
  }, 3000);
});
```

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

### Create Custom Tools in Owlbear Rodeo SDK (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Registers custom tools and modes with the Owlbear Rodeo toolbar. This involves defining tool behavior, icons, default modes, and click/event handlers. It also shows how to get the active tool and activate tools programmatically. Dependencies: `@owlbear-rodeo/sdk`.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  const TOOL_ID = "com.example/my-tool";
  const MODE_ID = "com.example/my-mode";

  // Create a tool
  await OBR.tool.create({
    id: TOOL_ID,
    icons: [
      { icon: "/icon.svg", label: "My Tool", filter: { every: [] } }
    ],
    defaultMode: MODE_ID,
    shortcut: "M",
    onClick: async (context, elementId) => {
      console.log("Tool clicked!");
      return true; // Return true to activate the tool
    }
  });

  // Create a tool mode
  await OBR.tool.createMode({
    id: MODE_ID,
    icons: [
      { icon: "/mode-icon.svg", label: "Draw Mode", filter: { every: [] } }
    ],
    onToolClick: async (context, event) => {
      console.log("Canvas clicked at:", event.pointerPosition);
      if (event.target) {
        console.log("Clicked on item:", event.target.id);
        return true; // Return true to select the item
      }
      return false;
    },
    onToolDown: (context, event) => {
      console.log("Mouse down at:", event.pointerPosition);
    },
    onToolDragStart: (context, event) => {
      console.log("Drag started");
    },
    onToolDragMove: (context, event) => {
      console.log("Dragging:", event.pointerPosition);
    },
    onToolDragEnd: (context, event) => {
      console.log("Drag ended");
    },
    onActivate: (context) => {
      console.log("Mode activated");
    },
    onDeactivate: (context) => {
      console.log("Mode deactivated");
    }
  });

  // Get active tool
  const activeTool = await OBR.tool.getActiveTool();

  // Activate tool programmatically
  await OBR.tool.activateTool(TOOL_ID);

  // Remove tool when done
  // await OBR.tool.remove(TOOL_ID);
});
```

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

### Control Viewport (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Illustrates how to get and set the viewport's position, scale, and dimensions, including animating the view and transforming coordinates between screen and world spaces. Requires the '@owlbear-rodeo/sdk' package.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get viewport properties
  const position = await OBR.viewport.getPosition();
  const scale = await OBR.viewport.getScale();
  const width = await OBR.viewport.getWidth();
  const height = await OBR.viewport.getHeight();

  console.log(`Viewport at (${position.x}, ${position.y}), scale: ${scale}`);

  // Set viewport position and scale
  await OBR.viewport.setPosition({ x: 1000, y: 500 });
  await OBR.viewport.setScale(1.5);

  // Animate to specific transform
  await OBR.viewport.animateTo({
    position: { x: 0, y: 0 },
    scale: 1.0
  });

  // Animate to fit specific bounds
  await OBR.viewport.animateToBounds({
    min: { x: 0, y: 0 },
    max: { x: 1000, y: 1000 }
  });

  // Reset viewport to default
  await OBR.viewport.reset();

  // Transform coordinates
  const worldPoint = await OBR.viewport.inverseTransformPoint({ x: 100, y: 100 });
  const screenPoint = await OBR.viewport.transformPoint({ x: 500, y: 300 });
});
```

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

### Query and Update Scene Items (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Shows how to retrieve, modify, and delete items in the scene using various filtering methods and provides an example of subscribing to item change events. Relies on the '@owlbear-rodeo/sdk' package.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get all items
  const allItems = await OBR.scene.items.getItems();

  // Get items by IDs
  const specificItems = await OBR.scene.items.getItems(["id-1", "id-2"]);

  // Get items with filter function
  const shapes = await OBR.scene.items.getItems((item) => {
    return item.type === "SHAPE" && item.layer === "DRAWING";
  });

  // Update items using filter
  await OBR.scene.items.updateItems(
    (item) => item.type === "SHAPE",
    (items) => {
      items.forEach(item => {
        item.visible = true;
        item.position.x += 50;
      });
    }
  );

  // Update specific items by passing them directly
  const myItems = await OBR.scene.items.getItems(["id-1", "id-2"]);
  await OBR.scene.items.updateItems(myItems, (items) => {
    items[0].locked = true;
    items[1].rotation = Math.PI / 4; // 45 degrees
  });

  // Delete items
  await OBR.scene.items.deleteItems(["id-1", "id-2"]);

  // Subscribe to item changes
  const unsubscribe = OBR.scene.items.onChange((items) => {
    console.log(`Scene has ${items.length} items`);
  });
});
```

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

### Query and Update Scene Items

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

This section details how to retrieve and modify existing scene items. It covers getting items by IDs or filters, updating them, deleting them, and subscribing to item changes.

```APIDOC
## Query and Update Scene Items

### Description
Retrieve and modify existing scene items with filters and update functions. This includes getting items, updating them based on criteria, deleting them, and subscribing to changes.

### Method
`OBR.onReady` with internal OBR SDK calls

### Endpoint
N/A (Client-side SDK functionality)

### Parameters
N/A

### Request Example
```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get all items
  const allItems = await OBR.scene.items.getItems();

  // Get items by IDs
  const specificItems = await OBR.scene.items.getItems(["id-1", "id-2"]);

  // Get items with filter function
  const shapes = await OBR.scene.items.getItems((item) => {
    return item.type === "SHAPE" && item.layer === "DRAWING";
  });

  // Update items using filter
  await OBR.scene.items.updateItems(
    (item) => item.type === "SHAPE",
    (items) => {
      items.forEach(item => {
        item.visible = true;
        item.position.x += 50;
      });
    }
  );

  // Update specific items by passing them directly
  const myItems = await OBR.scene.items.getItems(["id-1", "id-2"]);
  await OBR.scene.items.updateItems(myItems, (items) => {
    items[0].locked = true;
    items[1].rotation = Math.PI / 4; // 45 degrees
  });

  // Delete items
  await OBR.scene.items.deleteItems(["id-1", "id-2"]);

  // Subscribe to item changes
  const unsubscribe = OBR.scene.items.onChange((items) => {
    console.log(`Scene has ${items.length} items`);
  });
});
```

### Response
N/A (Modifies scene state or returns item data)
```

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

### Get Party Information

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Retrieves information about all players currently in the Owlbear Rodeo room, including their names, roles, colors, connection IDs, and current selections. It also provides a way to subscribe to changes in the party, such as players joining or leaving. This is essential for understanding the overall game state and player distribution.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get all players
  const players = await OBR.party.getPlayers();

  players.forEach(player => {
    console.log(`${player.name} (${player.role})`);
    console.log(`  Color: ${player.color}`);
    console.log(`  Connection ID: ${player.connectionId}`);
    console.log(`  Selection:`, player.selection);
  });

  // Subscribe to party changes (players joining/leaving)
  const unsubscribe = OBR.party.onChange((players) => {
    console.log(`Party size: ${players.length}`);
    const gms = players.filter(p => p.role === "GM");
    console.log(`GMs: ${gms.length}`);
  });
});
```

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

### Get and Update Player Information

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Manages the current player's properties, including name, color, role, and custom metadata. It allows fetching and modifying these details, checking edit permissions, and subscribing to changes in player data. This functionality is crucial for personalizing player experience and tracking game state.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get player ID
  const playerId = OBR.player.id;

  // Get player details
  const name = await OBR.player.getName();
  const color = await OBR.player.getColor();
  const role = await OBR.player.getRole(); // "GM" or "PLAYER"

  // Update player properties
  await OBR.player.setName("Dungeon Master");
  await OBR.player.setColor("#FF5733");

  // Get and set custom metadata
  const metadata = await OBR.player.getMetadata();
  await OBR.player.setMetadata({
    "com.example.myext/customData": { level: 5, hp: 50 }
  });

  // Check permissions
  const canEdit = await OBR.player.hasPermission("EDIT");

  // Subscribe to player changes
  const unsubscribe = OBR.player.onChange((player) => {
    console.log("Player updated:", player.name, player.color);
  });

  // Later: unsubscribe();
});
```

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

### Initialize Owlbear Rodeo SDK

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Initializes the Owlbear Rodeo SDK and provides a callback for when the SDK is ready to be used. It also demonstrates how to check if the SDK is available and retrieve basic player information. Ensure the SDK is ready before making any API calls.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(() => {
  console.log("SDK is ready!");

  // Get player information
  OBR.player.getName().then(name => {
    console.log(`Player name: ${name}`);
  });

  // Check if SDK is available
  if (OBR.isAvailable) {
    console.log("Extension is running inside Owlbear Rodeo");
  }
});

// Alternative: Check ready state directly
if (OBR.isReady) {
  // SDK already initialized
}
```

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

### Build and Add Scene Items (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Demonstrates how to create and add various types of items (shapes, text, images) to the scene using the SDK's fluent builder pattern. Requires the '@owlbear-rodeo/sdk' package.

```typescript
import OBR, { buildShape, buildImage, buildText } from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Build a shape item
  const rectangle = buildShape()
    .width(200)
    .height(100)
    .position({ x: 500, y: 300 })
    .shapeType("RECTANGLE")
    .fillColor("#3498db")
    .fillOpacity(0.8)
    .strokeColor("#2c3e50")
    .strokeWidth(3)
    .layer("DRAWING")
    .locked(false)
    .visible(true)
    .name("Blue Rectangle")
    .metadata({ "custom/data": "value" })
    .build();

  // Add items to scene
  await OBR.scene.items.addItems([rectangle]);

  // Build and add a text label
  const label = buildText()
    .position({ x: 500, y: 200 })
    .plainText("Hello World!")
    .fontSize(32)
    .fontWeight(700)
    .textAlign("CENTER")
    .fillColor("#ffffff")
    .strokeWidth(2)
    .strokeColor("#000000")
    .build();

  await OBR.scene.items.addItems([label]);

  // Build an image (requires ImageContent and ImageGrid)
  const imageUrl = "https://example.com/token.png";
  const image = buildImage(
    { url: imageUrl, mime: "image/png" },
    { dpi: 300, offset: { x: 0, y: 0 } }
  )
    .position({ x: 100, y: 100 })
    .scale({ x: 1, y: 1 })
    .layer("CHARACTER")
    .name("Player Token")
    .build();

  await OBR.scene.items.addItems([image]);
});
```

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

### Add and Manage Scene Items

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

This section covers creating and manipulating items within the scene using a fluent builder pattern. You can build shapes, text, and images, and then add them to the scene.

```APIDOC
## Add and Manage Scene Items

### Description
Create and manipulate items in the scene using the fluent builder pattern. This includes building shapes, text, and images, and then adding them to the scene.

### Method
`OBR.onReady` with internal OBR SDK calls

### Endpoint
N/A (Client-side SDK functionality)

### Parameters
N/A

### Request Example
```typescript
import OBR, { buildShape, buildImage, buildText } from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Build a shape item
  const rectangle = buildShape()
    .width(200)
    .height(100)
    .position({ x: 500, y: 300 })
    .shapeType("RECTANGLE")
    .fillColor("#3498db")
    .fillOpacity(0.8)
    .strokeColor("#2c3e50")
    .strokeWidth(3)
    .layer("DRAWING")
    .locked(false)
    .visible(true)
    .name("Blue Rectangle")
    .metadata({ "custom/data": "value" })
    .build();

  // Add items to scene
  await OBR.scene.items.addItems([rectangle]);

  // Build and add a text label
  const label = buildText()
    .position({ x: 500, y: 200 })
    .plainText("Hello World!")
    .fontSize(32)
    .fontWeight(700)
    .textAlign("CENTER")
    .fillColor("#ffffff")
    .strokeWidth(2)
    .strokeColor("#000000")
    .build();

  await OBR.scene.items.addItems([label]);

  // Build an image (requires ImageContent and ImageGrid)
  const imageUrl = "https://example.com/token.png";
  const image = buildImage(
    { url: imageUrl, mime: "image/png" },
    { dpi: 300, offset: { x: 0, y: 0 } }
  )
    .position({ x: 100, y: 100 })
    .scale({ x: 1, y: 1 })
    .layer("CHARACTER")
    .name("Player Token")
    .build();

  await OBR.scene.items.addItems([image]);
});
```

### Response
N/A (Modifies scene state)
```

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

### Access Theme Information

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Retrieves information about the current theme (light or dark mode) and subscribes to theme changes.

```APIDOC
## Access Theme Information

### Description
Get the current theme (light or dark mode) to style your extension accordingly.

### Method
`OBR.theme.getTheme()`
`OBR.theme.onChange(callback)`

### Endpoint
N/A (SDK methods)

### Parameters
None for `getTheme()`.

### Request Example
```typescript
const theme = await OBR.theme.getTheme();

if (theme.mode === "DARK") {
  document.body.classList.add("dark-theme");
} else {
  document.body.classList.add("light-theme");
}
```

### Response
#### Success Response (Theme Object)
- **mode** (string) - "LIGHT" or "DARK".
- **primary** (string) - The primary color of the theme (hex code).
- **text** (object) - An object containing text color definitions.
  - **primary** (string) - Primary text color (hex code).
  - **secondary** (string) - Secondary text color (hex code).

#### Response Example
```json
{
  "mode": "DARK",
  "primary": "#abcdef",
  "text": {
    "primary": "#ffffff",
    "secondary": "#cccccc"
  }
}
```

### Event Handlers
- **onChange**: Subscribes to changes in the theme. The callback receives the new theme object.
```

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

### Open Modals and Popovers in Owlbear Rodeo SDK (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Demonstrates how to open and close custom modal dialogs and popovers for user interaction within Owlbear Rodeo. It specifies modal/popover IDs, HTML URLs, dimensions, and positioning/behavioral options. Dependencies: `@owlbear-rodeo/sdk`.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Open a modal dialog
  await OBR.modal.open({
    id: "com.example/settings-modal",
    url: "/settings.html",
    height: 400,
    width: 600,
    fullscreen: false,
    disableClickAway: false,
    hidePaper: false,
    hideBackdrop: false
  });

  // Close modal
  await OBR.modal.close("com.example/settings-modal");

  // Open a popover (positioned UI element)
  await OBR.popover.open({
    id: "com.example/info-popover",
    url: "/info.html",
    height: 200,
    width: 300,
    anchorPosition: { top: 100, left: 200 },
    anchorOrigin: { horizontal: "CENTER", vertical: "CENTER" },
    anchorReference: "POSITION",
    disableClickAway: false,
    hidePaper: false,
    marginThreshold: 16,
    transformOrigin: { horizontal: "CENTER", vertical: "TOP" }
  });

  // Close popover
  await OBR.popover.close("com.example/info-popover");
});
```

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

### Open Modals and Popovers

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Display custom user interfaces as modal dialogs or anchored popovers. Modals are full-screen overlays, while popovers are positioned relative to other elements or screen coordinates.

```APIDOC
## Open Modals and Popovers

Create custom UI overlays for user interaction.

### Method

This documentation describes the `OBR.modal.open`, `OBR.modal.close`, `OBR.popover.open`, and `OBR.popover.close` functions.

### Endpoint

N/A (These are SDK functions, not HTTP endpoints)

### Parameters

#### `OBR.modal.open` Parameters

- **id** (string) - Required - A unique identifier for the modal.
- **url** (string) - Required - The URL of the HTML page to load in the modal.
- **height** (number) - Required - The height of the modal in pixels.
- **width** (number) - Required - The width of the modal in pixels.
- **fullscreen** (boolean) - Optional - Whether the modal should be fullscreen (defaults to `false`).
- **disableClickAway** (boolean) - Optional - Whether clicking outside the modal should close it (defaults to `false`).
- **hidePaper** (boolean) - Optional - Whether to hide the paper background (defaults to `false`).
- **hideBackdrop** (boolean) - Optional - Whether to hide the backdrop behind the modal (defaults to `false`).

#### `OBR.modal.close` Parameters

- **id** (string) - Required - The ID of the modal to close.

#### `OBR.popover.open` Parameters

- **id** (string) - Required - A unique identifier for the popover.
- **url** (string) - Required - The URL of the HTML page to load in the popover.
- **height** (number) - Required - The height of the popover in pixels.
- **width** (number) - Required - The width of the popover in pixels.
- **anchorPosition** (object) - Required - The position on the screen to anchor the popover.
  - **top** (number) - The distance from the top edge in pixels.
  - **left** (number) - The distance from the left edge in pixels.
- **anchorOrigin** (object) - Optional - The origin point on the popover to align with the anchor.
  - **horizontal** (string) - "LEFT", "CENTER", or "RIGHT".
  - **vertical** (string) - "TOP", "CENTER", or "BOTTOM".
- **anchorReference** (string) - Optional - "ANCHOR_ORIGIN" or "POSITION" (defaults to "POSITION").
- **disableClickAway** (boolean) - Optional - Whether clicking outside the popover should close it (defaults to `false`).
- **hidePaper** (boolean) - Optional - Whether to hide the paper background (defaults to `false`).
- **marginThreshold** (number) - Optional - Minimum distance from screen edges (defaults to `16`).
- **transformOrigin** (object) - Optional - The origin point on the popover for transformations.
  - **horizontal** (string) - "LEFT", "CENTER", or "RIGHT".
  - **vertical** (string) - "TOP", "CENTER", or "BOTTOM".

#### `OBR.popover.close` Parameters

- **id** (string) - Required - The ID of the popover to close.

### Request Example

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Open a modal dialog
  await OBR.modal.open({
    id: "com.example/settings-modal",
    url: "/settings.html",
    height: 400,
    width: 600,
    fullscreen: false,
    disableClickAway: false,
    hidePaper: false,
    hideBackdrop: false
  });

  // Close modal
  await OBR.modal.close("com.example/settings-modal");

  // Open a popover (positioned UI element)
  await OBR.popover.open({
    id: "com.example/info-popover",
    url: "/info.html",
    height: 200,
    width: 300,
    anchorPosition: { top: 100, left: 200 },
    anchorOrigin: { horizontal: "CENTER", vertical: "CENTER" },
    anchorReference: "POSITION",
    disableClickAway: false,
    hidePaper: false,
    marginThreshold: 16,
    transformOrigin: { horizontal: "CENTER", vertical: "TOP" }
  });

  // Close popover
  await OBR.popover.close("com.example/info-popover");
});
```

### Response

N/A (These functions modify the SDK's state directly.)

### Error Handling

Errors during modal or popover opening/closing will typically throw exceptions that can be caught using standard JavaScript `try...catch` blocks.
```

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

### Create Custom Tools

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Register custom tools and their modes with the Owlbear Rodeo toolbar. Tools can have icons, shortcuts, and define click behavior. Modes add functionality to a tool, responding to canvas interactions and activation/deactivation events.

```APIDOC
## Create Custom Tools

Register custom tools with the Owlbear Rodeo toolbar, including modes and actions.

### Method

This documentation describes the `OBR.tool.create` and `OBR.tool.createMode` functions.

### Endpoint

N/A (These are SDK functions, not HTTP endpoints)

### Parameters

#### `OBR.tool.create` Parameters

- **id** (string) - Required - A unique identifier for the tool (e.g., `com.example/my-tool`).
- **icons** (Array<object>) - Required - An array of icon definitions.
  - **icon** (string) - Required - The path to the icon asset.
  - **label** (string) - Required - The label for the icon.
  - **filter** (object) - Optional - Defines conditions for when the icon is visible.
- **defaultMode** (string) - Required - The ID of the mode to activate by default when the tool is selected.
- **shortcut** (string) - Optional - A keyboard shortcut for activating the tool.
- **onClick** (function) - Required - A callback function executed when the tool is clicked.
  - **context** (object) - The tool context.
  - **elementId** (string) - The ID of the element that was clicked (if applicable).
  - Returns: `boolean` - `true` to activate the tool, `false` otherwise.

#### `OBR.tool.createMode` Parameters

- **id** (string) - Required - A unique identifier for the tool mode.
- **icons** (Array<object>) - Required - An array of icon definitions for the mode.
- **onToolClick** (function) - Optional - Callback for when the canvas is clicked while the tool is active.
  - Returns: `boolean` - `true` to select the item clicked, `false` otherwise.
- **onToolDown** (function) - Optional - Callback for when the mouse button is pressed down on the canvas.
- **onToolDragStart** (function) - Optional - Callback for when a drag operation starts.
- **onToolDragMove** (function) - Optional - Callback for when the mouse moves during a drag operation.
- **onToolDragEnd** (function) - Optional - Callback for when a drag operation ends.
- **onActivate** (function) - Optional - Callback when the mode is activated.
- **onDeactivate** (function) - Optional - Callback when the mode is deactivated.

### Request Example

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  const TOOL_ID = "com.example/my-tool";
  const MODE_ID = "com.example/my-mode";

  // Create a tool
  await OBR.tool.create({
    id: TOOL_ID,
    icons: [
      { icon: "/icon.svg", label: "My Tool", filter: { every: [] } }
    ],
    defaultMode: MODE_ID,
    shortcut: "M",
    onClick: async (context, elementId) => {
      console.log("Tool clicked!");
      return true;
    }
  });

  // Create a tool mode
  await OBR.tool.createMode({
    id: MODE_ID,
    icons: [
      { icon: "/mode-icon.svg", label: "Draw Mode", filter: { every: [] } }
    ],
    onToolClick: async (context, event) => {
      console.log("Canvas clicked at:", event.pointerPosition);
      if (event.target) {
        console.log("Clicked on item:", event.target.id);
        return true;
      }
      return false;
    },
    onToolDown: (context, event) => {
      console.log("Mouse down at:", event.pointerPosition);
    },
    onActivate: (context) => {
      console.log("Mode activated");
    },
    onDeactivate: (context) => {
      console.log("Mode deactivated");
    }
  });
});
```

### Response

N/A (These functions modify the SDK's state directly.)

### Error Handling

Errors during tool or mode creation will typically throw exceptions that can be caught using standard JavaScript `try...catch` blocks.
```

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

### Manage Room and Scene Metadata

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Allows storing and retrieving custom data at the room and scene level, which persists across sessions.

```APIDOC
## Manage Room and Scene Metadata

### Description
Store and retrieve custom data at the room and scene level, persisted across sessions.

### Method
`OBR.room.getMetadata()`
`OBR.room.setMetadata(metadata)`
`OBR.room.onMetadataChange(callback)`
`OBR.scene.getMetadata()`
`OBR.scene.setMetadata(metadata)`
`OBR.scene.onMetadataChange(callback)`

### Endpoint
N/A (SDK methods)

### Parameters
#### Room Metadata
- **metadata** (object) - Required - Custom key-value pairs to store for the room.

#### Scene Metadata
- **metadata** (object) - Required - Custom key-value pairs to store for the scene.

### Request Example
```typescript
// Room metadata
await OBR.room.setMetadata({
  "com.example/campaign": {
    name: "Lost Mines of Phandelver",
    session: 5
  }
});

// Scene metadata
await OBR.scene.setMetadata({
  "com.example/weather": "rainy",
  "com.example/time": "night"
});
```

### Response
#### Success Response (Room/Scene Metadata)
- **metadata** (object) - The stored custom metadata.

#### Response Example (Room)
{
  "com.example/campaign": {
    "name": "Lost Mines of Phandelver",
    "session": 5
  }
}

#### Response Example (Scene)
{
  "com.example/weather": "rainy",
  "com.example/time": "night"
}

### Event Handlers
- **onMetadataChange**: Subscribes to changes in room or scene metadata.
```

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

### Control Viewport

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

This section explains how to control the camera view and perform coordinate transformations between screen and world space.

```APIDOC
## Control Viewport

### Description
Manipulate the camera view and transform coordinates between screen and world space. This includes getting and setting viewport properties, animating the view, and converting points.

### Method
`OBR.onReady` with internal OBR SDK calls

### Endpoint
N/A (Client-side SDK functionality)

### Parameters
N/A

### Request Example
```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get viewport properties
  const position = await OBR.viewport.getPosition();
  const scale = await OBR.viewport.getScale();
  const width = await OBR.viewport.getWidth();
  const height = await OBR.viewport.getHeight();

  console.log(`Viewport at (${position.x}, ${position.y}), scale: ${scale}`);

  // Set viewport position and scale
  await OBR.viewport.setPosition({ x: 1000, y: 500 });
  await OBR.viewport.setScale(1.5);

  // Animate to specific transform
  await OBR.viewport.animateTo({
    position: { x: 0, y: 0 },
    scale: 1.0
  });

  // Animate to fit specific bounds
  await OBR.viewport.animateToBounds({
    min: { x: 0, y: 0 },
    max: { x: 1000, y: 1000 }
  });

  // Reset viewport to default
  await OBR.viewport.reset();

  // Transform coordinates
  const worldPoint = await OBR.viewport.inverseTransformPoint({ x: 100, y: 100 });
  const screenPoint = await OBR.viewport.transformPoint({ x: 500, y: 300 });
});
```

### Response
N/A (Modifies viewport or returns coordinate data)
```

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

### Show Notifications

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

This section describes how to display toast notifications to the user with different severity levels and how to close them programmatically.

```APIDOC
## Show Notifications

### Description
Display toast notifications to the user with different severity levels. This includes showing default and variant notifications, and closing them programmatically.

### Method
`OBR.onReady` with internal OBR SDK calls

### Endpoint
N/A (Client-side SDK functionality)

### Parameters
N/A

### Request Example
```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Show default notification
  const id1 = await OBR.notification.show("Action completed");

  // Show notification with variant
  const id2 = await OBR.notification.show("Success!", "SUCCESS");
  const id3 = await OBR.notification.show("Warning message", "WARNING");
  const id4 = await OBR.notification.show("Error occurred", "ERROR");
  const id5 = await OBR.notification.show("Information", "INFO");

  // Close notification programmatically
  setTimeout(async () => {
    await OBR.notification.close(id1);
  }, 3000);
});
```

### Response
N/A (Displays UI notifications)
```

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

### Configure Action Button

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Allows customization of the extension's action button in the Owlbear Rodeo UI, including its icon, title, dimensions, and badge.

```APIDOC
## Configure Action Button

### Description
Customize the extension's action button in the Owlbear Rodeo UI.

### Method
`OBR.action.setIcon(url)`
`OBR.action.setTitle(title)`
`OBR.action.setWidth(width)`
`OBR.action.setHeight(height)`
`OBR.action.setBadgeText(text | undefined)`
`OBR.action.setBadgeBackgroundColor(color)`
`OBR.action.isOpen()`
`OBR.action.open()`
`OBR.action.close()`
`OBR.action.onOpenChange(callback)`

### Endpoint
N/A (SDK methods)

### Parameters
- **url** (string) - URL path to the icon file.
- **title** (string) - The title text for the action button.
- **width** (number) - The desired width of the action panel in pixels.
- **height** (number) - The desired height of the action panel in pixels.
- **text** (string | undefined) - The text for the notification badge. Use `undefined` to remove the badge.
- **color** (string) - Hex color code for the badge background.

### Request Example
```typescript
await OBR.action.setIcon("/icon.svg");
await OBR.action.setTitle("My Extension");
await OBR.action.setWidth(400);
await OBR.action.setHeight(600);
await OBR.action.setBadgeText("5");
await OBR.action.setBadgeBackgroundColor("#ff0000");
await OBR.action.open();
```

### Response
#### Success Response
- None (methods are void or return boolean for `isOpen`)

#### Response Example (isOpen)
```json
true
```

### Event Handlers
- **onOpenChange**: Subscribes to changes in the action panel's open state.
```

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

### Create Context Menu Items in Owlbear Rodeo SDK (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Adds custom items to the right-click context menu in Owlbear Rodeo. This includes defining item IDs, icons, shortcuts, click handlers, and optional embedded HTML for submenus. It also shows how to remove items. Dependencies: `@owlbear-rodeo/sdk`.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  const MENU_ID = "com.example/custom-action";

  // Create context menu item
  await OBR.contextMenu.create({
    id: MENU_ID,
    icons: [
      { icon: "/action-icon.svg", label: "Custom Action", filter: { every: [] } }
    ],
    shortcut: "Ctrl+Shift+A",
    onClick: (context, elementId) => {
      console.log("Context menu clicked!");
      console.log("Selected items:", context.items);

      // Perform action on selected items
      context.items.forEach(item => {
        console.log(`Processing ${item.name}`);
      });
    },
    embed: {
      url: "/submenu.html",
      height: 300,
      width: 400
    }
  });

  // Remove context menu item
  // await OBR.contextMenu.remove(MENU_ID);
});
```

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

### Broadcast Messages Between Extensions in Owlbear Rodeo SDK (TypeScript)

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Enables sending and receiving custom messages between extension instances across all players in Owlbear Rodeo. It covers subscribing to messages on a channel, sending messages to local, remote, or all destinations, and unsubscribing. Dependencies: `@owlbear-rodeo/sdk`.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  const CHANNEL = "com.example/my-channel";

  // Subscribe to messages
  const unsubscribe = OBR.broadcast.onMessage(CHANNEL, (event) => {
    console.log("Received message:", event.data);
    console.log("From connection:", event.connectionId);
  });

  // Send message to all remote players
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "update",
    payload: { value: 42 }
  }, { destination: "REMOTE" });

  // Send to local extension only
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "local-update"
  }, { destination: "LOCAL" });

  // Send to all (local and remote)
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "broadcast",
    message: "Hello everyone!"
  }, { destination: "ALL" });

  // Later: unsubscribe();
});
```

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

### Broadcast Messages Between Extensions

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Facilitate communication between different extension instances, enabling them to send and receive custom messages across all connected players in real-time.

```APIDOC
## Broadcast Messages Between Extensions

Send and receive custom messages between extension instances across all players.

### Method

This documentation describes the `OBR.broadcast.onMessage` and `OBR.broadcast.sendMessage` functions.

### Endpoint

N/A (These are SDK functions, not HTTP endpoints)

### Parameters

#### `OBR.broadcast.onMessage` Parameters

- **channel** (string) - Required - The name of the channel to subscribe to.
- **callback** (function) - Required - A function to be called when a message is received on the channel.
  - **event** (object) - The message event object.
    - **data** (any) - The data payload of the message.
    - **connectionId** (string) - The ID of the connection that sent the message.
  - Returns: `function` - A function to unsubscribe from the channel.

#### `OBR.broadcast.sendMessage` Parameters

- **channel** (string) - Required - The name of the channel to send the message to.
- **data** (any) - Required - The data payload of the message.
- **options** (object) - Optional - Configuration for message delivery.
  - **destination** (string) - Optional - Specifies the destination for the message. Options include:
    - "REMOTE": Send only to other connected players.
    - "LOCAL": Send only to the local extension instance.
    - "ALL": Send to both local and remote instances (defaults to "ALL" if omitted).

### Request Example

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  const CHANNEL = "com.example/my-channel";

  // Subscribe to messages
  const unsubscribe = OBR.broadcast.onMessage(CHANNEL, (event) => {
    console.log("Received message:", event.data);
    console.log("From connection:", event.connectionId);
  });

  // Send message to all remote players
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "update",
    payload: { value: 42 }
  }, { destination: "REMOTE" });

  // Send to local extension only
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "local-update"
  }, { destination: "LOCAL" });

  // Send to all (local and remote)
  await OBR.broadcast.sendMessage(CHANNEL, {
    action: "broadcast",
    message: "Hello everyone!"
  }, { destination: "ALL" });

  // To unsubscribe later:
  // unsubscribe(); 
});
```

### Response

N/A (These functions initiate or listen for messages.)

### Error Handling

Errors during message sending or subscription will typically throw exceptions that can be caught using standard JavaScript `try...catch` blocks.
```

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

### Access Theme Information in TypeScript

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Retrieve the current theme (light or dark mode) from the Owlbear Rodeo SDK to dynamically style your extension. This includes accessing the theme mode, primary color, and text colors. It also provides a way to subscribe to theme changes and update the UI accordingly.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Get current theme
  const theme = await OBR.theme.getTheme();

  if (theme.mode === "DARK") {
    document.body.classList.add("dark-theme");
  } else {
    document.body.classList.add("light-theme");
  }

  // Subscribe to theme changes
  const unsubscribe = OBR.theme.onChange((theme) => {
    console.log("Theme changed to:", theme.mode);
    console.log("Primary color:", theme.primary);
    console.log("Text colors:", theme.text);

    // Update UI based on theme
    document.documentElement.style.setProperty("--primary", theme.primary);
  });
});
```

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

### Manage Room and Scene Metadata in TypeScript

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Store and retrieve custom data at the room and scene level using the Owlbear Rodeo SDK. This data persists across sessions. It allows setting and subscribing to metadata changes for both the room and individual scenes. Room metadata is shared across all scenes in a room, while scene metadata is specific to the current scene.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Room metadata (persists across all scenes in the room)
  const roomId = OBR.room.id;
  const roomMeta = await OBR.room.getMetadata();

  await OBR.room.setMetadata({
    "com.example/campaign": {
      name: "Lost Mines of Phandelver",
      session: 5
    }
  });

  const unsubscribeRoom = OBR.room.onMetadataChange((metadata) => {
    console.log("Room metadata updated:", metadata);
  });

  // Scene metadata (specific to current scene)
  const sceneMeta = await OBR.scene.getMetadata();

  await OBR.scene.setMetadata({
    "com.example/weather": "rainy",
    "com.example/time": "night"
  });

  const unsubscribeScene = OBR.scene.onMetadataChange((metadata) => {
    console.log("Scene metadata updated:", metadata);
  });

  // Check if scene is ready
  const ready = await OBR.scene.isReady();

  const unsubscribeReady = OBR.scene.onReadyChange((ready) => {
    if (ready) {
      console.log("Scene is loaded and ready");
    }
  });
});
```

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

### Configure Action Button in TypeScript

Source: https://context7.com/owlbear-rodeo/sdk/llms.txt

Customize the extension's action button in the Owlbear Rodeo UI. This includes setting the icon, title, dimensions, and adding/removing notification badges. It also allows checking and controlling the open state of the action panel and subscribing to its open state changes.

```typescript
import OBR from "@owlbear-rodeo/sdk";

OBR.onReady(async () => {
  // Set action button properties
  await OBR.action.setIcon("/icon.svg");
  await OBR.action.setTitle("My Extension");
  await OBR.action.setWidth(400);
  await OBR.action.setHeight(600);

  // Add notification badge
  await OBR.action.setBadgeText("5");
  await OBR.action.setBadgeBackgroundColor("#ff0000");

  // Remove badge
  await OBR.action.setBadgeText(undefined);

  // Check if action panel is open
  const isOpen = await OBR.action.isOpen();

  // Control action panel
  await OBR.action.open();
  await OBR.action.close();

  // Subscribe to open state changes
  const unsubscribe = OBR.action.onOpenChange((isOpen) => {
    console.log("Action panel", isOpen ? "opened" : "closed");
  });
});
```