# API Reference

This document provides an overview of Vellum’s public API, including the `Vellum` class, key utility functions, and events emitted by the system. For detailed technical specifications, including method signatures and parameter types, refer to the [JSDoc-generated API documentation](#full-api-docs) (to be generated from the source code). This reference is designed to help you understand Vellum’s core components and how to interact with them effectively.

---

## Vellum Class Overview

The `Vellum` class is a custom web component (`HTMLElement`) that serves as the central manager for modular web applications. It handles mod loading, action dispatching, and content rendering within a shadow DOM.

### Key Methods

- **`constructor({ renderer, modTagName })`**  
  Initializes a Vellum instance with optional configuration.  
  - `renderer`: A function to render content (defaults to `defaultRenderer`).  
  - `modTagName`: The tag name for mod elements (defaults to `'vellum-mod'`).  
  Example:
  ```javascript
  const vellum = new Vellum({ renderer: customRenderer });
  ```

- **`connectedCallback()`**  
  Sets up event listeners, observes DOM changes, and loads mods when the element is added to the DOM.

- **`disconnectedCallback()`**  
  Cleans up event listeners and observers when the element is removed from the DOM.

- **`setRenderer(renderer)`**  
  Sets a new renderer function and updates the display if initialized.  
  Example:
  ```javascript
  vellum.setRenderer((content, container) => container.innerHTML = content);
  ```

- **`update()`**  
  Updates the rendered content by querying the active layout and applying the current renderer.

### Key Properties

- **`actionHandlers`**  
  An object storing action handlers by type and mod name.

- **`renderer`**  
  The function used to render content into the shadow DOM.

- **`shadow`**  
  The shadow DOM root where content is rendered.

- **`isInitialized`**  
  A boolean indicating whether Vellum has completed its initial mod loading.

- **`modTagName`**  
  The tag name used to identify mod elements (configurable via attribute or constructor).

---

## Utility Functions

Vellum relies on utility modules in `src/utils/` to handle specific tasks. Below are the key functions exposed for potential use or extension.

### `utils/actions.mjs`
- **`registerHandler(actionType, modName, handler, registry)`**  
  Registers an action handler for a given type and mod.

- **`unregisterHandler(actionType, modName, registry)`**  
  Removes an action handler.

- **`handleAction(action, handlers)`**  
  Invokes all handlers for an action type.

### `utils/dom.mjs`
- **`createCustomEvent(type, detail)`**  
  Creates a custom event with bubbling and composed path support.

- **`dispatchEventTo(element, type, detail)`**  
  Dispatches a custom event to a target element.

### `utils/logging.mjs`
- **`logWarning(message, data)`**  
  Logs a warning to the console with optional data.

- **`logError(message, error)`**  
  Logs an error to the console with error details.

### `utils/mods.mjs`
- **`extractModData(element, tagName, index)`**  
  Extracts metadata (e.g., `src`, `name`, `require`) from a mod element.

- **`loadModule(src)`**  
  Dynamically imports a module from a URL.

- **`sortMods(modList)`**  
  Sorts mods by dependencies, priority, and DOM order.

- **`fetchMods(modList)`**  
  Loads multiple mods concurrently.

- **`executeMod(mod, toolkit, dispatchError)`**  
  Executes a mod’s `init` function with error handling.

### `utils/rendering.mjs`
- **`defaultRenderer(content, container)`**  
  Renders content into a container (strings or DOM nodes).

- **`renderContent(newContent, currentContent, renderer, container)`**  
  Renders new content if it differs from the current content.

### `utils/toolkit.mjs`
- **`createToolkit(element, toolkitProp)`**  
  Creates a toolkit object for mod interaction.  
  Example:
  ```javascript
  const toolkit = createToolkit(vellumElement);
  toolkit.dispatchAction({ type: 'test:action' });
  ```

---

## Events

Vellum emits several events to communicate its state and mod lifecycle. These events are namespaced with `vellum:` (pending implementation from the roadmap).

- **`vellum:mod-loading-started`**  
  Fired when mod loading begins.  
  - `detail`: `{ totalMods: number }`

- **`vellum:mod-loaded`**  
  Fired when a mod is successfully loaded.  
  - `detail`: `{ src: string, module: object }`

- **`vellum:mod-load-failed`**  
  Fired when a mod fails to load.  
  - `detail`: `{ src: string, error: Error }`

- **`vellum:mod-initialized`**  
  Fired when a mod’s `init` function completes successfully.  
  - `detail`: `{ src: string }`

- **`vellum:mod-init-failed`**  
  Fired when a mod’s `init` function fails.  
  - `detail`: `{ src: string, error: Error }`

- **`vellum:mod-loading-complete`**  
  Fired when all mods have finished loading and initializing.  
  - `detail`: `{ loadedCount: number, failedCount: number }`

- **`vellum:mods-failed`**  
  Fired if any mods fail to load or initialize.  
  - `detail`: `{ failedMods: array }`

- **`mods-loaded`**  
  Fired when Vellum completes its initial mod loading process (not yet namespaced).

- **`harness:action`**  
  Internal event for action dispatching (not typically listened to directly).

---

## Full API Docs

For a complete reference, including parameter types and additional utility functions, see the [JSDoc-generated API documentation](#) (to be generated from `src/` with JSDoc annotations). This will provide exhaustive details on all methods, properties, and internal utilities.

---

## Next Steps
- **Explore Other Topics**: Check out [Understanding Mods](./mods.md) or [Action System](./actions.md) for practical guidance.
- **Contribute**: Add JSDoc annotations to enhance this reference—see the [roadmap](./docs-outline.md).