@byre/vellum 1.0.0

package/dist/spec.md

@@ -0,0 +1,1292 @@
+# Vellum Specification v2.0.0 RC3
+
+**Version**: 1.0.0
+**Date**: January 30, 2026
+**Status**: Release Candidate 4
+
+## 1. Purpose and Scope
+
+### 1.1 What This Specification Defines
+
+Vellum is a specification for mod loaders in web applications. It defines:
+
+- Host and mod custom element interfaces
+- Mod discovery and loading behavior
+- Dependency resolution
+- Lifecycle events
+
+A conforming implementation provides a mod loader that adheres to this specification.
+
+### 1.2 What This Specification Does Not Define
+
+This specification does not define:
+
+- Action/event systems (ecosystem mods MAY provide these)
+- Rendering or layout management
+- State management
+- Logging or debugging utilities
+- Any application-level functionality
+
+These capabilities MAY be provided by mods and are not part of the kernel.
+
+### 1.3 Conformance
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in RFC 2119.
+
+### 1.4 Design Philosophy
+
+Vellum is a kernel, not a framework. It loads mods and coordinates their
+initialization. Everything else is delegated to mods.
+
+**The DOM is the source of truth.** Wherever possible, Vellum state is
+expressed through DOM structure and element attributes, not internal
+JavaScript state. For example:
+
+- **Add a mod element to the DOM** → mod loads
+- **Remove mod element from DOM** → mod unloads
+- **`disabled` attribute** → mod skipped/unloaded
+- **`src` attribute changes** → mod reloads with new source
+- **`loading` attribute** → mod is loading
+- **`loaded` attribute** → mod loaded successfully
+- **`failed` attribute** → mod failed to load
+
+Inspecting the document reveals application structure without tracing
+JavaScript state. DevTools, CSS selectors, and mutation observers can all
+interact with mod lifecycle.
+
+This declarative approach has practical benefits:
+
+- Server-rendered HTML can include mod elements
+- CSS can target mod states (`my-mod[loading] { opacity: 0.5; }`)
+- Tests can assert on DOM attributes
+- Debugging requires only element inspection
+
+### 1.5 Architecture
+
+Vellum provides two custom elements:
+
+- **`<vellum-app>`** provides a host element for mod discovery and loading.
+- **`<vellum-mod>`** is a mod element, providing a source and dependencies.
+
+The tag names are configurable.
+
+## 2. Definitions
+
+- **Dependency**      A mod that must be loaded before another mod can load.
+- **Host element**    The custom element that manages mod elements (e.g., `<vellum-app>`)
+- **Lifecycle event** A CustomEvent dispatched by the host element to signal state changes.
+- **Mod element**     A custom element representing a module. Describes source and dependencies.
+- **Mod module**      The imported module object returned by `import()`
+- **Mod script**      The ES module file referenced by `src`
+- **Priority**        A number used to determine load order among peer mods. Lower values load first.
+
+## 3. Host Element
+
+### 3.1 Class Export
+
+A conforming implementation MUST export a host element class that extends `HTMLElement`.
+
+The implementation MUST NOT call `customElements.define()`. Tag name registration is the consumer's responsibility.
+
+**Example Invocation**
+
+_In your JavaScript_
+```javascript
+import { VellumApp } from '@byre/vellum';
+customElements.define('vellum-app', VellumApp);
+```
+
+_In your HTML_
+```html
+<vellum-app></vellum-app>
+```
+
+### 3.2 Attributes
+
+| Attribute | Required | Default      | Description                            |
+|-----------|----------|--------------|----------------------------------------|
+| `mod-tag` | No       | `vellum-mod` | Tag name used to discover mod elements |
+| `debug`   | No       | —            | If present, implementation MAY emit debug events |
+
+### 3.3 Behavior
+
+When connected to the DOM, the host element MUST:
+
+1. Wait for descendant elements to be parsed
+2. Discover all descendant mod elements matching `mod-tag`, excluding:
+   - Elements with `disabled` attribute
+   - Elements that have a closer ancestor host element (see Section 3.6)
+3. Resolve dependencies and determine load order (see Section 5)
+4. Load each mod element in resolved order (see Section 3.5)
+   - Mod elements with all dependencies resolved MAY be loaded in parallel
+5. Begin observing for mod element additions, removals, and attribute changes
+
+When a mod element is added to the host's subtree after initial load:
+
+1. The host MUST detect the addition via MutationObserver
+2. If the mod element has `disabled` attribute, the host MUST skip it
+3. If the mod element has a closer ancestor host, the host MUST skip it
+4. The host MUST resolve dependencies against already-loaded mod elements
+5. The host MUST load the new mod element
+6. If the mod element's hard dependencies cannot be satisfied, the host MUST
+   set the `failed` attribute and dispatch `vellum:mod-failed` with a
+   `VellumDependencyError`
+
+When a mod element is removed from the host's subtree:
+
+1. The host MUST detect the removal via MutationObserver
+2. If the mod element has `loaded` attribute, the host MUST unload it (see Section 3.5)
+
+When a mod element's attributes change:
+
+1. The host MUST observe attribute changes via MutationObserver for at least
+   `src` and `disabled` attributes
+2. If `src` changes on a mod element with `loaded` attribute:
+   - The host MUST unload the current module
+   - The host MUST load from the new source
+3. If `src` changes on a mod element with `loading` attribute:
+   - The host MUST abort the current load (via AbortSignal)
+   - The host MUST load from the new source
+4. If `disabled` is added to a mod element with `loaded` attribute:
+   - The host MUST unload the module
+5. If `disabled` is removed from a mod element without `loaded` or `loading`:
+   - The host MUST initiate loading (respecting dependencies)
+
+When disconnected from the DOM, the host element MUST:
+
+1. Stop observing for mod changes
+2. Dispatch `vellum:teardown` event
+
+### 3.4 Events Dispatched
+
+| Event                     | Detail                               | When                     |
+|---------------------------|--------------------------------------|--------------------------|
+| `vellum:loading-started`  | `{ total: number }`                  | Before first mod loads   |
+| `vellum:loading-complete` | `{ loaded: number, failed: number }` | After all mods processed |
+| `vellum:teardown`         | `{}`                                 | On disconnect            |
+| `vellum:debug`            | Implementation-defined               | MAY be emitted if `debug` attribute present |
+
+Events MUST bubble and MUST be composed (cross shadow DOM boundaries).
+
+### 3.5 Loading and Unloading
+
+The host element is solely responsible for loading and unloading mod elements.
+Mod elements MUST NOT load themselves.
+
+**Loading a mod element:**
+
+1. If `loading`, `loaded`, `failed`, or `disabled` attribute is present, return
+2. Validate attributes:
+   - If both `src` and `ref` are present, set `failed` attribute, dispatch
+     `vellum:mod-failed` with `VellumAttributeError`, and stop
+   - If neither `src` nor `ref` is present, set `failed` attribute, dispatch
+     `vellum:mod-failed` with `VellumAttributeError`, and stop
+3. Set `loading` attribute
+4. Obtain the mod definition:
+   - If `src` is present: Import the mod script via dynamic `import()`
+   - If `ref` is present: Resolve the key to a mod definition (resolution
+     mechanism is implementation-defined)
+5. If obtaining the mod definition fails:
+   - Remove `loading` attribute
+   - Set `failed` attribute
+   - Dispatch `vellum:mod-failed` with `VellumLoadError` (for `src`) or
+     `VellumReferenceError` (for `ref`)
+   - Stop
+6. If the mod definition exports a `mount` function:
+   - Create an AbortController
+   - Call `mount({ element, host, signal })` where:
+     - `element` is the mod element
+     - `host` is the host element
+     - `signal` is the AbortController's signal
+   - If `mount` throws or rejects:
+     - Remove `loading` attribute
+     - Set `failed` attribute
+     - Dispatch `vellum:mod-failed` with `VellumMountError`
+     - Stop
+7. Remove `loading` attribute
+8. Set `loaded` attribute
+9. Dispatch `vellum:mod-loaded` with `{ element, module }`
+
+**Unloading a mod element:**
+
+1. If the `loading` attribute is present, abort the current load then continue.
+2. If the `unloading` attribute is present, return
+3. If neither the `loaded` nor `failed` attributes are present, return
+4. If `loaded` attribute is present:
+   - Set `unloading` attribute
+   - If the mod definition exported an `unmount` function during load:
+     - Call `unmount({ element, host })`
+   - Remove `unloading` attribute
+5. Remove `loading`, `loaded`, and `failed` attributes
+6. Dispatch `vellum:mod-unloaded` with `{ element, module, wasLoaded }` where:
+   - `module` is the mod definition (or `null` if load failed before resolution)
+   - `wasLoaded` is `true` if `loaded` attribute was present, `false` otherwise
+7. Release any references to the mod definition.
+
+### 3.6 Nested Hosts
+
+Host elements MAY be nested within other host elements.
+
+A mod element belongs to its **closest ancestor host element**. When
+discovering mod elements, a host MUST NOT process mod elements that have a
+closer ancestor host.
+
+```html
+<outer-app mod-tag="my-mod">
+  <my-mod src="./a.mjs" name="a"></my-mod>      <!-- belongs to outer-app -->
+  <inner-app mod-tag="my-mod">
+    <my-mod src="./b.mjs" name="b"></my-mod>    <!-- belongs to inner-app -->
+  </inner-app>
+  <my-mod src="./c.mjs" name="c"></my-mod>      <!-- belongs to outer-app -->
+</outer-app>
+```
+
+Each host element manages only its direct mod elements. Events from inner
+hosts bubble normally and MAY be observed by outer hosts.
+
+Host elements MAY catch events from within their own subtree and prevent
+them from propagating.
+
+A host MUST NOT wait for nested hosts to complete before dispatching its
+own `vellum:loading-complete` event.
+
+### 3.7 Registration Requirements
+
+Consumers MUST register both the host element class and the mod element class
+as custom elements before connecting the host element to the DOM.
+
+The tag name used for `customElements.define()` on the mod element class MUST
+match the host element's `mod-tag` attribute (or the default `vellum-mod`).
+
+If the host encounters elements matching `mod-tag` that are not registered
+custom elements, the host SHOULD log a warning and skip those elements.
+
+## 4. Mod Element
+
+### 4.1 Purpose
+
+The mod element is a declarative marker representing a loadable module. It
+carries configuration (source URL, dependencies, priority) but does not
+perform loading itself.
+
+**Loading is the sole responsibility of the host element.**
+
+The mod element is inert until processed by a host.
+
+### 4.2 Class Export
+
+A conforming implementation MUST export a mod element class that extends
+`HTMLElement`.
+
+The implementation MUST NOT call `customElements.define()`. Tag name
+registration is the consumer's responsibility.
+
+
+### 4.3 Attributes
+
+| Attribute  | Type   | Required | Default        | Description                                   |
+|------------|--------|----------|----------------|-----------------------------------------------|
+| `src`      | Input  | No*      | —              | URL of the mod script                         |
+| `ref`      | Input  | No*      | —              | Key identifying a pre-registered mod definition |
+| `name`     | Input  | No       | Value of `src` or `ref` | Unique identifier for dependency resolution   |
+| `require`  | Input  | No       | —              | Comma-separated list of hard dependencies     |
+| `after`    | Input  | No       | —              | Comma-separated list of soft dependencies     |
+| `priority` | Input  | No       | —              | Integer; lower values load first among peers  |
+| `disabled` | Input  | No       | —              | If present, mod will not load                 |
+| `loading`  | Output | —        | —              | Set by host while load is in progress         |
+| `loaded`   | Output | —        | —              | Set by host on successful load                |
+| `failed`   | Output | —        | —              | Set by host on failed load                    |
+| `unloading`| Output | —        | —              | Set by host while unload is in progress       |
+
+*Exactly one of `src` or `ref` MUST be present. If both are present or neither
+is present, the host MUST set the `failed` attribute and dispatch
+`vellum:mod-failed` with a `VellumAttributeError`.
+
+The `loading`, `loaded`, `failed`, and `unloading` attributes are reserved
+and output-only. They MUST NOT be set by consumers. They are managed
+exclusively by the host element.
+
+**Hard vs Soft Dependencies:**
+
+- `require`: The mod element MUST NOT load until all required mod elements have
+  loaded successfully. If a required mod element is missing or fails, this mod
+  element MUST fail.
+
+- `after`: The mod element SHOULD load after these mod elements if they exist
+  and are loading/loaded. If an `after` target is missing, this mod element
+  loads anyway. If an `after` target fails, this mod element still attempts
+  to load.
+
+**Priority:**
+
+The `priority` attribute serves as a tiebreaker when dependency order does
+not determine load sequence:
+
+1. For mod elements with equivalent dependency status, lower `priority` values
+   load first
+2. If priorities are equal, DOM order determines sequence
+
+### 4.4 Behavior
+
+The mod element has no autonomous behavior. It MUST NOT initiate loading,
+unloading, or any lifecycle operations.
+
+When connected to the DOM, the mod element remains inert until the host
+element processes it.
+
+When disconnected from the DOM, the host element is responsible for detecting
+the removal and performing cleanup (see Section 3.3).
+
+The mod element MAY provide convenience getters for attribute access:
+
+```javascript
+get src() { return this.getAttribute('src'); }
+get name() { return this.getAttribute('name') || this.src; }
+get dependencies() {
+  const req = this.getAttribute('require');
+  return req ? req.split(',').map(s => s.trim()).filter(Boolean) : [];
+}
+get softDependencies() {
+  const after = this.getAttribute('after');
+  return after ? after.split(',').map(s => s.trim()).filter(Boolean) : [];
+}
+```
+
+### 4.5 Child Content
+
+Mod elements MAY contain child elements. This specification does not define
+semantics for child content.
+
+Mod scripts MAY access children via standard DOM APIs on the `element`
+parameter passed to `mount()`:
+
+```javascript
+export function mount({ element, host, signal }) {
+  const template = element.querySelector('template');
+  const config = element.querySelector('script[type="application/json"]');
+  // ...
+}
+```
+
+### 4.6 Events
+
+All lifecycle events are dispatched by the host element, using the mod
+element as the event target:
+
+| Event                 | Detail                                          | When                            |
+|-----------------------|-------------------------------------------------|---------------------------------|
+| `vellum:mod-loaded`   | `{ element: HTMLElement, module: object }`      | After successful load and mount |
+| `vellum:mod-failed`   | `{ element: HTMLElement, error: Error }`        | After load or mount failure     |
+| `vellum:mod-unloaded` | `{ element: HTMLElement, module: object, wasLoaded: boolean }` | After unload     |
+
+Events MUST bubble and MUST be composed.
+
+### 4.7 State Machine
+
+The mod element's state is represented by output attributes. The following
+state transitions are valid:
+
+```
+                                    ┌─────────────────────────────────┐
+                                    │                                 │
+                                    ▼                                 │
+┌─────────┐  host triggers  ┌───────────┐  import+mount   ┌────────┐  │
+│ Initial │ ───────────────►│  Loading  │ ───────────────►│ Loaded │  │
+└─────────┘                 └───────────┘                 └────────┘  │
+     ▲                            │                            │      │
+     │                            │ import or                  │      │
+     │                            │ mount fails                │      │
+     │                            ▼                            │      │
+     │                       ┌────────┐                        │      │
+     │  DOM removal          │ Failed │                        │      │
+     └───────────────────────┴────────┘                        │      │
+     ▲                                                         │      │
+     │                       ┌───────────┐                     │      │
+     │  unmount completes    │ Unloading │◄────────────────────┘      │
+     └───────────────────────┴───────────┘  DOM removal /             │
+                                            disabled /                │
+                                            src change                │
+                                                                      │
+     ▲                                                                │
+     │                          disabled present (no-op)              │
+     └────────────────────────────────────────────────────────────────┘
+```
+
+**State-to-attribute mapping:**
+
+| State     | Attributes Present |
+|-----------|--------------------|
+| Initial   | (none)             |
+| Loading   | `loading`          |
+| Loaded    | `loaded`           |
+| Failed    | `failed`           |
+| Unloading | `unloading`        |
+
+A mod element MUST have at most one of these output attributes present.
+
+## 5. Dependency Resolution
+
+### 5.1 Resolution Algorithm
+
+The host MUST resolve mod load order using:
+
+1. **Hard dependencies (`require`)**: Mod elements MUST load after all required
+   mod elements have successfully loaded
+2. **Soft dependencies (`after`)**: Mod elements SHOULD load after listed mod
+   elements if those mod elements exist and haven't failed
+3. **Priority**: Among mod elements with satisfied dependencies, lower
+   `priority` values load first
+4. **DOM order**: Among mod elements with equal priority, earlier DOM position
+   loads first
+
+### 5.2 Hard Dependency Failures
+
+If a mod element's required dependency (via `require`) is missing or has failed:
+
+- The mod element MUST NOT attempt to load
+- The host MUST set the `failed` attribute on the mod element
+- The host MUST dispatch `vellum:mod-failed` with a `VellumDependencyError`
+
+### 5.3 Soft Dependency Handling
+
+If a mod element's `after` dependency is missing:
+
+- The mod element MUST proceed as if the dependency was satisfied
+- The mod element loads in its normal priority/DOM order position
+
+If a mod element's `after` dependency has failed:
+
+- The mod element MUST still attempt to load
+- The mod script's `mount` function MAY check for the failed dependency if needed
+
+Mod scripts using `after` dependencies SHOULD check for dependent mod state
+if they require conditional behavior based on whether the soft dependency
+loaded successfully.
+
+### 5.4 Circular Dependencies
+
+Circular dependencies in `require` attributes produce a fatal error.
+
+If circular hard dependencies are detected:
+
+- The host MUST NOT attempt to load any mod element in the cycle
+- The host MUST set the `failed` attribute on all mod elements in the cycle
+- The host MUST dispatch `vellum:mod-failed` for each with a
+  `VellumCircularDependencyError`
+- The error message MUST include the cycle path (e.g., "a → b → c → a")
+
+Circular dependencies in `after` attributes are permitted and do not cause
+errors, since `after` is non-blocking.
+
+### 5.5 Dynamic Mod Elements
+
+When a mod element is added after initial load:
+
+- Its `require` dependencies MUST already be loaded (or the mod element fails
+  with `VellumDependencyError`)
+- Its `after` dependencies refer to currently loaded or loading mod elements;
+  missing targets are treated as satisfied
+- Already-loaded mod elements MUST NOT be reloaded
+- The new mod element MUST wait for any pending mod elements it depends on
+
+## 6. Mod Script Interface
+
+### 6.1 Module Format
+
+Mod scripts MUST be ES modules.
+
+All valid ES module specifiers are permitted for the `src` attribute,
+including:
+
+- Relative URLs (resolved relative to the document)
+- Absolute URLs
+- Data URLs
+- Blob URLs
+
+Cross-origin mod scripts are subject to CORS restrictions per the ES module
+specification.
+
+### 6.2 Exports
+
+#### 6.2.1 `mount` function
+
+Mod scripts MAY export a `mount` function. The `mount` function MAY be async.
+
+```typescript
+mount(context: {
+  element: HTMLElement,
+  host: HTMLElement,
+  signal: AbortSignal
+}): void | Promise<void>
+```
+
+Parameters (passed as a single object):
+
+- `element`: The mod element that initiated the load
+- `host`: The host element coordinating the load
+- `signal`: An AbortSignal that is aborted if the load is cancelled (e.g.,
+  due to `src` attribute change or element removal during load)
+
+If `mount` is not exported, the mod script runs its top-level code only.
+
+The `mount` function SHOULD:
+
+- Store the `host` reference if needed for later access
+- Attach an abort listener to `signal` if cleanup is needed on cancellation
+- Return or resolve when initialization is complete
+
+#### 6.2.2 `unmount` function
+
+Mod scripts MAY export an `unmount` function for cleanup:
+
+```typescript
+unmount(context: {
+  element: HTMLElement,
+  host: HTMLElement
+}): void | Promise<void>
+```
+
+Parameters (passed as a single object):
+
+- `element`: The mod element being unloaded
+- `host`: The host element coordinating the unload
+
+The `unmount` function is called when:
+
+- The mod element is removed from the DOM
+- The `disabled` attribute is added
+- The `src` attribute changes
+- (There is no public `unload()` method; these are the only triggers)
+
+The `unmount` function SHOULD:
+
+- Remove event listeners
+- Cancel pending operations
+- Release resources
+- Clean up any DOM modifications
+
+If `unmount` is not exported, no cleanup is performed.
+
+#### 6.2.3 Other exports
+
+A mod script MAY export any other functions or variables. The host MUST NOT
+store or access exports other than `mount` and `unmount`.
+
+### 6.3 Dispatching Events
+
+Mod scripts communicate via native DOM events:
+
+```javascript
+export async function mount({ element, host, signal }) {
+  element.dispatchEvent(new CustomEvent('my:event', {
+    bubbles: true,
+    composed: true,
+    detail: { /* ... */ }
+  }));
+}
+```
+
+No toolkit or wrapper is required.
+
+## 7. Event Namespacing
+
+All events defined by this specification use the `vellum:` prefix.
+
+| Event                     | Source | Target      | Purpose                 |
+|---------------------------|--------|-------------|-------------------------|
+| `vellum:loading-started`  | Host   | Host        | Loading phase beginning |
+| `vellum:loading-complete` | Host   | Host        | Loading phase complete  |
+| `vellum:teardown`         | Host   | Host        | Host disconnecting      |
+| `vellum:debug`            | Host   | Host        | Debug information       |
+| `vellum:mod-loaded`       | Host   | Mod element | Mod successfully loaded |
+| `vellum:mod-failed`       | Host   | Mod element | Mod failed to load      |
+| `vellum:mod-unloaded`     | Host   | Mod element | Mod unloaded            |
+
+Implementations MUST use these exact event names.
+
+Ecosystem mods MAY define additional events with their own namespaces.
+
+### 7.1 Reserved Namespaces
+
+The following attribute and event prefixes are reserved:
+
+- `vellum-*` attributes: Reserved for future specification use
+- `vellum:*` events: Reserved for specification-defined events
+
+Consumers SHOULD use `data-*` attributes for custom metadata on mod elements.
+Consumers MAY use any valid, HTML-compliant attributes on mod elements.
+
+Ecosystem mods SHOULD use their own event namespace (e.g., `mymod:event`).
+
+## 8. Error Types
+
+Implementations MUST define and throw the following error types:
+
+### 8.1 VellumError
+
+Base class for all Vellum errors.
+
+```typescript
+class VellumError extends Error {
+  name: 'VellumError';
+  cause?: Error;
+}
+```
+
+### 8.2 VellumDependencyError
+
+Thrown when a mod element's hard dependencies cannot be satisfied.
+
+```typescript
+class VellumDependencyError extends VellumError {
+  name: 'VellumDependencyError';
+  modName: string;
+  missingDependencies: string[];
+}
+```
+
+Message format: `Mod "{modName}" has unmet dependencies: {deps.join(', ')}`
+
+### 8.3 VellumCircularDependencyError
+
+Thrown when circular hard dependencies are detected.
+
+```typescript
+class VellumCircularDependencyError extends VellumError {
+  name: 'VellumCircularDependencyError';
+  cycle: string[];
+}
+```
+
+Message format: `Circular dependency detected: {cycle.join(' → ')}`
+
+### 8.4 VellumLoadError
+
+Thrown when a mod script fails to import.
+
+```typescript
+class VellumLoadError extends VellumError {
+  name: 'VellumLoadError';
+  src: string;
+}
+```
+
+Message format: `Failed to load mod from "{src}"`
+
+### 8.5 VellumMountError
+
+Thrown when a mod script's `mount` function fails.
+
+```typescript
+class VellumMountError extends VellumError {
+  name: 'VellumMountError';
+  modName: string;
+}
+```
+
+Message format: `Mount failed for mod "{modName}"`
+
+### 8.6 VellumAttributeError
+
+Thrown when a mod element has invalid attribute configuration.
+```typescript
+class VellumAttributeError extends VellumError {
+  name: 'VellumAttributeError';
+  modName: string;
+}
+```
+
+Message format (both present): `Mod "{modName}" has both src and ref attributes; exactly one is required`
+
+Message format (neither present): `Mod "{modName}" has neither src nor ref attribute; exactly one is required`
+
+### 8.7 VellumReferenceError
+
+Thrown when a mod element's `ref` attribute cannot be resolved.
+```typescript
+class VellumReferenceError extends VellumError {
+  name: 'VellumReferenceError';
+  ref: string;
+}
+```
+
+Message format: `Could not resolve mod reference "{ref}"`
+
+## 9. Security Considerations
+
+### 9.1 Content Security Policy
+
+Mod scripts are loaded via dynamic `import()`. For this to succeed, the mod
+script's origin MUST be permitted by the document's `script-src` CSP directive.
+
+Implementations MUST NOT bypass or weaken CSP restrictions.
+
+Example CSP header allowing mod scripts from same origin and a trusted CDN:
+
+```
+Content-Security-Policy: script-src 'self' https://cdn.example.com
+```
+
+### 9.2 Subresource Integrity
+
+This specification does not require SRI support for mod scripts.
+
+Implementations MAY support an `integrity` attribute on mod elements:
+
+```html
+<my-mod src="./x.mjs" integrity="sha384-..."></my-mod>
+```
+
+If supported, implementations MUST reject modules that fail integrity checks
+and MUST set the `failed` attribute with a `VellumLoadError`.
+
+### 9.3 Cross-Origin Loading
+
+Mod scripts loaded from different origins are subject to CORS restrictions
+per the ES module specification.
+
+Cross-origin scripts MUST be served with appropriate headers:
+
+- `Access-Control-Allow-Origin` matching the document origin or `*`
+
+If CORS checks fail, the host MUST set the `failed` attribute and dispatch
+`vellum:mod-failed` with a `VellumLoadError`.
+
+### 9.4 Module Isolation
+
+Implementations SHOULD NOT store arbitrary properties from loaded mod modules.
+Only the `mount` and `unmount` exports (if present) should be retained and
+invoked.
+
+This mitigates prototype pollution risks from malicious mod scripts.
+
+## 10. Conformance
+
+### 10.1 Implementation Conformance
+
+A conforming Vellum implementation MUST:
+
+1. Export a host element class meeting Section 3 requirements
+2. Export a mod element class meeting Section 4 requirements
+3. Implement dependency resolution per Section 5
+4. Dispatch all required events per Section 7
+5. Define all error types per Section 8
+
+A conforming implementation MUST NOT:
+
+1. Call `customElements.define()` for either element class
+2. Expose a `load()` method on mod elements
+3. Allow mod elements to initiate their own loading
+
+### 10.2 Consumer Conformance
+
+A conforming Vellum consumer MUST:
+
+1. Register both host and mod element classes as custom elements
+2. Use matching tag names (host's `mod-tag` matches mod element registration)
+3. Register both element classes before connecting the host to the DOM
+
+### 10.3 Mod Script Conformance
+
+Mod scripts have no conformance requirements. They MAY export `mount`
+and/or `unmount`. They MAY dispatch events.
+
+Mod scripts MAY provide user interface elements.
+
+## 11. Versioning
+
+### 11.1 Specification Versioning
+
+This specification follows Semantic Versioning 2.0.0:
+
+- **MAJOR**: Breaking changes to element interfaces or required behaviors
+- **MINOR**: New optional features, attributes, or recommendations
+- **PATCH**: Clarifications and corrections
+
+### 11.2 Implementation Versioning
+
+Implementations SHOULD indicate which specification version they conform to.
+
+---
+
+## Appendix A: Glossary
+
+**Host Element**: The coordinating custom element that manages mod loading.
+
+**Mod Element**: A custom element representing a single loadable module. Inert
+until processed by a host.
+
+**Mod Script**: The ES module file loaded by a mod element.
+
+**Mod Module**: The JavaScript module object returned by `import()`.
+
+**Kernel**: The core Vellum implementation (host + mod elements). Provides
+loading only.
+
+**Ecosystem Mod**: A mod script providing reusable functionality (e.g.,
+actions, routing, rendering).
+
+### Mod Element
+```
+Attributes (input):
+  src              Module URL (required if ref not present)
+  ref              Registry key (required if src not present)
+  name             Identifier for dependencies
+  require          Comma-separated hard dependency names
+  after            Comma-separated soft dependency names
+  priority         Load order tiebreaker (lower = earlier)
+  disabled         If present, mod will not load
+
+Attributes (output, managed by host):
+  loading          Present while load is in progress
+  loaded           Present after successful load
+  failed           Present after failed load
+  unloading        Present while unload is in progress
+
+Methods:
+  (none - loading is host's responsibility)
+
+Events (dispatched by host on this element):
+  vellum:mod-loaded      { element, module }
+  vellum:mod-failed      { element, error }
+  vellum:mod-unloaded    { element, module, wasLoaded }
+
+Behavior:
+  - Inert until processed by host
+  - No autonomous lifecycle operations
+  - Exactly one of src or ref must be present
+  - Child content accessible to mod script via element parameter
+```
+
+## Appendix C: Example Usages
+
+### Basic Setup
+
+```javascript
+// app.js
+import { VellumHost, VellumMod } from '@byre/vellum';
+
+customElements.define('my-app', VellumHost);
+customElements.define('my-mod', VellumMod);
+```
+
+```html
+<my-app mod-tag="my-mod">
+  <my-mod src="./layout.mjs" name="layout"></my-mod>
+  <my-mod src="./header.mjs" name="header" require="layout"></my-mod>
+  <my-mod src="./analytics.mjs" name="analytics" after="layout"></my-mod>
+  <my-mod src="./content.mjs" require="layout" after="analytics"></my-mod>
+  <my-mod src="./experimental.mjs" disabled></my-mod>
+</my-app>
+```
+
+In this example:
+- `header` requires `layout` (fails if layout fails)
+- `analytics` loads after `layout` if present (but would work without it)
+- `content` requires `layout`, and loads after `analytics` if present
+- `experimental` is present but won't load until `disabled` is removed
+
+### Mod Script with Mount and Unmount
+
+```javascript
+// layout.mjs
+let container;
+let hostRef;
+
+export function mount({ element, host, signal }) {
+  hostRef = host;
+  
+  // Handle cancellation
+  signal.addEventListener('abort', () => {
+    container?.remove();
+    container = null;
+  });
+  
+  container = document.createElement('div');
+  container.id = 'layout-root';
+  host.appendChild(container);
+  
+  element.dispatchEvent(new CustomEvent('layout:ready', {
+    bubbles: true,
+    composed: true,
+    detail: { container }
+  }));
+}
+
+export function unmount({ element, host }) {
+  container?.remove();
+  container = null;
+  hostRef = null;
+}
+```
+
+### Mod Script Listening to Another Mod
+
+```javascript
+// header.mjs
+let headerElement;
+
+export function mount({ element, host, signal }) {
+  // Wait for layout to be ready
+  host.addEventListener('layout:ready', (e) => {
+    headerElement = document.createElement('header');
+    headerElement.textContent = 'My Application';
+    e.detail.container.prepend(headerElement);
+  }, { once: true });
+}
+
+export function unmount({ element, host }) {
+  headerElement?.remove();
+  headerElement = null;
+}
+```
+
+### Bundle Registration
+```javascript
+// mybundle.mjs - a mod that registers other mods
+export function mount({ element, host, signal }) {
+  // Registration mechanism is implementation-defined
+  // This example assumes host.register() exists
+  host.register('mybundle.mod-a', {
+    mount({ element, host, signal }) {
+      console.log('mod-a mounted');
+    },
+    unmount({ element, host }) {
+      console.log('mod-a unmounted');
+    }
+  });
+
+  host.register('mybundle.mod-b', {
+    mount({ element, host, signal }) {
+      console.log('mod-b mounted');
+    }
+  });
+}
+```
+
+```html
+<!-- Load the bundle first -->
+<my-mod src="mybundle.mjs" name="mybundle"></my-mod>
+
+<!-- These resolve from the bundle's registrations -->
+<my-mod ref="mybundle.mod-a" require="mybundle"></my-mod>
+<my-mod ref="mybundle.mod-b" require="mybundle"></my-mod>
+```
+
+In this example:
+- `mybundle` loads via `src` and registers two mod definitions during mount
+- `mybundle.mod-a` and `mybundle.mod-b` use `ref` to resolve from registrations
+- `require="mybundle"` ensures the bundle mounts before resolution is attempted
+- The registration mechanism (`host.register()`) is implementation-defined
+
+### Using Child Content
+
+```html
+<my-mod src="./configurable.mjs" name="configurable">
+  <script type="application/json">
+    { "theme": "dark", "language": "en" }
+  </script>
+  <template>
+    <div class="custom-content">
+      <slot></slot>
+    </div>
+  </template>
+</my-mod>
+```
+
+```javascript
+// configurable.mjs
+export function mount({ element, host, signal }) {
+  const configScript = element.querySelector('script[type="application/json"]');
+  const config = configScript ? JSON.parse(configScript.textContent) : {};
+  
+  const template = element.querySelector('template');
+  if (template) {
+    const content = template.content.cloneNode(true);
+    // Use content...
+  }
+  
+  console.log('Config:', config);
+}
+```
+
+### Using Default Tag Names
+
+```javascript
+// For users who want vellum-app / vellum-mod
+import '@byre/vellum/register';
+```
+
+```html
+<vellum-app>
+  <vellum-mod src="./my-mod.mjs"></vellum-mod>
+</vellum-app>
+```
+
+### DOM-Driven Lifecycle
+
+```javascript
+const host = document.querySelector('my-app');
+
+// Load a mod: add to DOM
+const mod = document.createElement('my-mod');
+mod.setAttribute('src', './new-feature.mjs');
+host.appendChild(mod);
+
+// Unload a mod: remove from DOM
+mod.remove();
+
+// Reload a mod: remove and re-add
+const parent = mod.parentElement;
+const next = mod.nextSibling;
+mod.remove();
+parent.insertBefore(mod, next);
+
+// Disable a mod (unloads if loaded)
+mod.setAttribute('disabled', '');
+
+// Enable a mod (loads if dependencies satisfied)
+mod.removeAttribute('disabled');
+
+// Change source (unloads old, loads new)
+mod.setAttribute('src', './new-feature-v2.mjs');
+```
+
+### CSS Targeting Mod State
+
+```css
+/* Style based on load state */
+my-mod[loading] {
+  opacity: 0.5;
+}
+
+my-mod[loaded] {
+  /* loaded indicator */
+}
+
+my-mod[failed] {
+  outline: 2px solid red;
+}
+
+my-mod[failed]::after {
+  content: ' (failed)';
+  color: red;
+}
+
+my-mod[disabled] {
+  display: none;
+}
+
+my-mod[unloading] {
+  opacity: 0.3;
+  pointer-events: none;
+}
+```
+
+### Nested Hosts
+
+```html
+<my-app mod-tag="my-mod">
+  <my-mod src="./shell.mjs" name="shell"></my-mod>
+  
+  <!-- Inner application with its own mods -->
+  <my-app mod-tag="my-mod" id="inner-app">
+    <my-mod src="./inner-feature.mjs" name="inner-feature"></my-mod>
+  </my-app>
+  
+  <my-mod src="./outer-feature.mjs" name="outer-feature"></my-mod>
+</my-app>
+```
+
+```javascript
+// Outer host can listen to inner host events
+document.querySelector('my-app').addEventListener('vellum:mod-loaded', (e) => {
+  console.log('A mod loaded somewhere:', e.detail.element.getAttribute('name'));
+});
+```
+
+## Appendix D: Migration from v1.x
+
+### Removed Features
+
+| v1.x Feature             | v2.0 Equivalent                  |
+|--------------------------|----------------------------------|
+| Built-in action registry | Use `@byre/vellum-actions` mod   |
+| Toolkit object           | Use native DOM APIs              |
+| `dispatchAction()`       | Use `element.dispatchEvent()`    |
+| Built-in rendering       | Use rendering mod                |
+| Logging utilities        | Use debug mod or browser console |
+| `mod.load()`             | (removed - host loads mods)      |
+| `mod.reload()`           | Remove and re-add element        |
+| `mod.unload()`           | Remove element from DOM          |
+
+### Changed Behaviors
+
+| Behavior          | v1.x                     | v2.0                                               |
+|-------------------|--------------------------|-----------------------------------------------------|
+| Mod element       | Inert DOM element        | Inert custom element (still inert, but typed)      |
+| Mod state         | Internal                 | Visible via `loading`/`loaded`/`failed`/`unloading` |
+| Event prefix      | `harness:` / none        | `vellum:`                                          |
+| Setup function    | `init(toolkit)`          | `mount({ element, host, signal })`                 |
+| Cleanup function  | Not supported            | `unmount({ element, host })`                       |
+| Load trigger      | Public `load()` on mod   | Host-only (no public method)                       |
+| Unload trigger    | Not supported            | DOM removal or `disabled` attribute                |
+| Soft dependencies | Not supported            | Use `after` attribute                              |
+| Disable mod       | Not supported            | Use `disabled` attribute                           |
+| Circular deps     | Resolved via priority    | Fatal error (`VellumCircularDependencyError`)      |
+
+### Migration Steps
+
+1. Register both `VellumHost` and `VellumMod` as custom elements
+2. Add `@byre/vellum-actions` mod if using action system
+3. Rename `init(toolkit)` to `mount({ element, host, signal })`
+4. Add `unmount({ element, host })` for any cleanup logic
+5. Replace `toolkit.dispatchAction()` with native `dispatchEvent()`
+6. Update event listeners from `harness:action` to mod-specific events
+7. Change optional dependencies from `require` to `after`
+8. Use `disabled` attribute instead of conditional loading logic
+9. Remove any direct calls to `mod.load()` (loading is automatic)
+10. Replace `mod.reload()` with remove-and-re-add pattern
+11. Replace `mod.unload()` with `mod.remove()`
+12. Handle `VellumCircularDependencyError` if you relied on cycle resolution
+
+## Appendix E: Implementation Notes
+
+This appendix provides non-normative guidance for implementers.
+
+### E.1 MutationObserver Configuration
+
+The host element should observe its subtree for:
+
+- Child list changes (mod additions and removals)
+- Attribute changes on mod elements (`src`, `disabled` at minimum)
+
+Recommended configuration:
+
+```javascript
+const observer = new MutationObserver(callback);
+observer.observe(hostElement, {
+  childList: true,
+  subtree: true,
+  attributes: true,
+  attributeFilter: ['src', 'disabled'],
+  attributeOldValue: true
+});
+```
+
+Note: Observing `subtree: true` with `attributes: true` can be expensive for
+large DOM trees. Implementations MAY use separate observers for child list
+and attributes, or MAY track mod elements and observe them individually.
+
+### E.2 Handling Shadow DOM Boundaries
+
+If mod elements are placed inside shadow roots, the host's `querySelectorAll`
+will not find them by default.
+
+Implementations MAY:
+
+- Document that mod elements must be in the light DOM
+- Use `querySelectorAll` with `{ root: document }` (where supported)
+- Provide a mechanism for shadow roots to register with the host
+
+The simplest approach is to require mod elements in light DOM.
+
+### E.3 Performance Considerations for Large Mod Counts
+
+For applications with many mod elements (50+):
+
+- **Batch processing**: Process mod additions/removals in batches using
+  `requestAnimationFrame` or `queueMicrotask`
+- **Parallel loading**: Load mod elements with satisfied dependencies in
+  parallel, respecting any implementation-defined concurrency limit
+- **Lazy attribute observation**: Only observe attributes on mod elements
+  that have been loaded (not disabled/failed)
+
+### E.4 AbortSignal Usage
+
+The `signal` passed to `mount()` enables cancellation. Common patterns:
+
+```javascript
+export async function mount({ element, host, signal }) {
+  // Check if already aborted
+  if (signal.aborted) return;
+  
+  // Cancel fetch requests
+  const response = await fetch(url, { signal });
+  
+  // Cancel timers
+  const timeoutId = setTimeout(doSomething, 1000);
+  signal.addEventListener('abort', () => clearTimeout(timeoutId));
+  
+  // Cancel event listeners
+  const handler = (e) => { /* ... */ };
+  document.addEventListener('click', handler);
+  signal.addEventListener('abort', () => {
+    document.removeEventListener('click', handler);
+  });
+}
+```
+
+### E.5 Testing Recommendations
+
+Implementations should test:
+
+- All state transitions in the state machine
+- Dependency resolution with complex graphs
+- Circular dependency detection
+- Dynamic mod addition/removal
+- Attribute change handling during various states
+- Nested host behavior
+- Error propagation and error types
+- AbortSignal cancellation during load
+
+## Appendix F: Related Work
+
+Vellum draws inspiration from and differs from several existing systems:
+
+### Module Loaders
+
+**SystemJS / RequireJS**: Full module loaders with resolution, bundling
+concerns, and format transformation. Vellum delegates to native ES modules
+and focuses only on lifecycle coordination.
+
+**ES Module Shims**: Polyfills for import maps and other module features.
+Vellum works alongside such tools but doesn't replace them.
+
+### Web Component Libraries
+
+**Lit / Stencil / etc.**: Component authoring libraries. Vellum doesn't
+provide component authoring—it loads arbitrary modules that MAY use any
+component library.
+
+### Micro-Frontend Frameworks
+
+**single-spa / Module Federation**: Orchestrate multiple applications.
+Vellum is lower-level—it loads modules, not applications. A micro-frontend
+framework could be built as a Vellum mod.
+
+### Key Differentiators
+
+1. **DOM-centric**: State visible in DOM, not JavaScript
+2. **Kernel philosophy**: Minimal core, everything else is a mod
+3. **No opinions**: No rendering, routing, state management built-in
+4. **Native ES modules**: Uses `import()`, no custom loader
+
+---
+
+## References
+
+**Normative:**
+- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119): Key words for requirements
+- [Custom Elements](https://html.spec.whatwg.org/multipage/custom-elements.html): WHATWG specification
+- [ES Modules](https://tc39.es/ecma262/#sec-modules): ECMAScript specification
+- [Semantic Versioning 2.0.0](https://semver.org/)
+
+**Informative:**
+- [MutationObserver](https://dom.spec.whatwg.org/#mutationobserver): DOM observation
+- [CustomEvent](https://dom.spec.whatwg.org/#customevent): Event interface
+- [AbortController](https://dom.spec.whatwg.org/#abortcontroller): Cancellation API
+- [Content Security Policy](https://www.w3.org/TR/CSP3/): CSP Level 3
+- [Subresource Integrity](https://www.w3.org/TR/SRI/): SRI specification