# Component Studio

Build custom UI components your AVCodex agent renders inside chat. Instead of plain text, the agent can show a room-status card, a signal-flow diagram, an RFP-line-item form, a Crestron module catalog tile, or anything else you can build with HTML, CSS, and JavaScript.

---

Component Studio lets you create components (room cards, equipment lookup tiles, troubleshooting checklists, RFP scope forms, control-system status panels) that your agent renders directly inside the chat. The agent decides when to use them based on context, and passes structured data as props.

## How It Works

Components are self-contained HTML/CSS/JS bundles that run inside a sandboxed iframe within the chat interface. When your agent decides a visual component is the right way to respond, it renders the component with dynamic data passed as props.

```
Field tech: "Show me the rooms with offline DSPs"
    |
Agent selects the "room-status-card" component
Agent passes props: { rooms: [...], status: "offline" }
    |
Component renders inside chat as an interactive grid of room cards
```

The agent knows about every component registered to itself: name, props schema, purpose. It picks when to use them based on conversation context.

## Creating a Component

**1. Open Component Studio**

Open your agent in the Builder and click the **Components** tab.

**2. Describe Your Component**

Open The Alchemist panel and describe what you want:

- "Create a room-status card showing room name, control system online/offline, DSP firmware version, and a 'View signal flow' button."
- "Build a Crestron module catalog tile with module name, manufacturer, version, and a copy-to-clipboard button for the SIMPL# include path."
- "Make an RFP scope form with rows for room type, count, AVoIP requirement, and a submit button."

You can also drop a screenshot of a design you want to replicate (a Q-SYS Designer panel, a Crestron Construct screen, an existing internal tool). The Alchemist generates production-ready HTML, CSS, and JavaScript.

**3. Edit and Preview**

The studio shows a split-pane view: tabbed code editors (HTML, CSS, JS) on the left, live preview on the right. As you edit, the preview updates with a 500ms debounce.

**4. Refine with AI**

Ask The Alchemist to make changes to an existing component:

- "Add a hover effect to the card."
- "Make the form responsive for a field tech's phone."
- "Change the color scheme to match our integrator brand."

AI-refined code saves automatically and the component list refreshes.

**5. Save**

Click **Save** to persist manual edits. The component is immediately available to your agent in conversations.

## The Bridge API

Components run inside a sandboxed iframe, but they communicate back to the chat conversation through the Bridge API on `window.avcodex`. This is how components send data, save memories, and trigger actions.

### `window.avcodex.actions.submitForm(data)`

Send form data back to the conversation as a user message. The agent sees the data and can respond.

```javascript
window.avcodex.actions.submitForm({
  roomType: "Mid-size huddle",
  count: 12,
  avoipRequired: true
});
```

### `window.avcodex.actions.saveMemory(data)`

Save unstructured text to the user's episodic memory. This text is searched via vector similarity in future conversations.

```javascript
window.avcodex.actions.saveMemory(
  "Programmer prefers SIMPL# over SIMPL+ and uses tabs not spaces"
);
```

### `window.avcodex.actions.saveToProfile(updates)`

Save structured data to the user's profile (dossier). Injected into every future conversation's system prompt. Pass `null` for a field to remove it. Requires a logged-in user.

```javascript
window.avcodex.actions.saveToProfile({
  timezone: "America/Los_Angeles",
  manufacturers: ["Crestron", "QSC", "Biamp"],
  preferences: ["concise", "code-first"],
  notes: "Senior programmer, no entry-level explanations needed"
});
```

### `window.avcodex.actions.triggerAction(name, data)`

Trigger a named custom action. Sent to the conversation as `[Action: name]` so the agent can respond accordingly.

```javascript
window.avcodex.actions.triggerAction("schedule_truck_roll", {
  site: "Building 4 - Main Conference Room",
  date: "2026-05-02",
  priority: "P1"
});
```

### `window.avcodex.props`

Read-only object containing data the agent passes when rendering the component. Use this to populate dynamic content.

```javascript
const { userName, rooms } = window.avcodex.props;
document.getElementById("greeting").textContent =
  "Hello, " + (userName || "tech") + ". Showing " + rooms.length + " rooms.";
```

## Props Schema

Each component has a props schema that tells the agent what data it can pass. The schema is defined automatically by The Alchemist when it generates the component. You can view and inspect it in the studio.

| Field | Type | Description |
|-------|------|-------------|
| **name** | string | The prop name (e.g. `rooms`, `userName`) |
| **type** | string, number, boolean, array, object | The expected data type |
| **description** | string | What this prop contains |
| **required** | boolean | Whether the agent must provide this prop |

The props schema appears as chips below the editor when a component is selected.

## Workspace Sharing

Components can be shared across agents in your workspace or organization. Useful when you have a common UI pattern (a room-status card, a signal-flow tile) that multiple agents need.

### Sharing Scopes

| Scope | Visibility |
|-------|------------|
| **Private** | Only the agent that owns the component can use it |
| **Workspace** | All agents in the same workspace can link to this component |
| **Organization** | All agents in any workspace in the organization can link to this component |

Change the sharing scope using the dropdown in the code editor toolbar.

### Linked Components

When you share a component at the workspace or organization level, other agents can **link** to it. Linked components appear in the component list with a "Linked" badge and show which agent owns them. Linked components are read-only. Edits happen on the original.

To unlink a component from your agent, select it and click **Unlink**. Removes it from your agent without deleting the original.

> **Note:** The sharing badge shows how many agents have linked to a shared component (e.g. "Workspace - 3 agents"). Helps you understand the impact before changing or deleting a shared component.

## Component Examples

Common component patterns AV builders create:

| Component | Use Case | Key Props |
|-----------|----------|-----------|
| **Room status card** | Managed-services agents showing rack health | roomName, controlSystemStatus, dspStatus, firmware |
| **Truck-roll booking form** | Field service scheduling assistants | availableTechs, sites, priority |
| **Spec-sheet search results** | Design engineer pulling answers from Crestron / Biamp / Extron PDFs | items, query, totalCount |
| **Pricing comparison** | Reseller agents comparing matrix switchers across manufacturers | products, features, prices |
| **Control system dashboard** | Field-tech agent showing live error codes | metrics, errorLog |
| **RFP scope form** | Sales-engineer agent capturing room counts and standards | fields, submitLabel |

## Tips for Better Components

1. **Keep it focused**: One component, one job. A room-status card, not a room-status-card-with-truck-roll-with-billing.
2. **Use the Bridge API for interactivity**: Forms should call `submitForm()` so the agent processes the data instead of silently posting elsewhere.
3. **Design for chat context**: Components render inside message bubbles. Keep widths flexible. Avoid fixed pixel widths larger than 400px (a tech may be looking at this on a phone in a server room).
4. **Include fallback text**: If `window.avcodex.props` is empty, show placeholder content so the preview stays useful during development.
5. **Share common patterns**: If two agents need the same room-card layout, create it once and share at the workspace level rather than duplicating code across your integrator's library.

*AVCodex · Your AV expertise. Amplified by AI.*