# Coralite v1.0.0-rc.3 — Machine-Readable LLM Developer Reference

> **Metadata**: Coralite Framework v1.0.0-rc.3 | Node.js Floor: `>=22.22.2` (ESM native)

---

## Table of Contents
- [§0. Critical Directives](#0-critical-directives)
- [§1. The Golden Optimal App](#1-the-golden-optimal-app)
- [§2. The Serialization Boundary & Isomorphic Model](#2-the-serialization-boundary-isomorphic-model)
- [§3. File Structure: Pages vs. Components](#3-file-structure-pages-vs-components)
- [§4. System Architecture, Fault Isolation & Asset Integrity](#4-system-architecture-fault-isolation-asset-integrity)
- [§5. Static Components (Declarative SSR-Only)](#5-static-components-declarative-ssr-only)
- [§6. Dynamic Components (`defineComponent` API Reference)](#6-dynamic-components-definecomponent-api-reference)
  - [§6.1 Complete Schema & Block Signatures](#61-complete-schema-block-signatures)
  - [§6.2 `attributes` (Coercion Pipeline, Validation & ARIA Rules)](#62-attributes-coercion-pipeline-validation-aria-rules)
  - [§6.3 `server` (SSR Data Fetching & Context Keys)](#63-server-ssr-data-fetching-context-keys)
  - [§6.4 `getters` (Unified Context Mechanics)](#64-getters-unified-context-mechanics)
  - [§6.5 `style` (Synchronous Reactive Host Styles & CSS Vars)](#65-style-synchronous-reactive-host-styles-css-vars)
  - [§6.6 `client` (Lifecycle, `errors`, `updateComplete`, FACE Hooks)](#66-client-lifecycle-errors-updatecomplete-face-hooks)
  - [§6.7 `slots` (Reactive Element Builders)](#67-slots-reactive-element-builders)
  - [§6.8 `onError` (SSR Component Error Boundaries)](#68-onerror-ssr-component-error-boundaries)
  - [§6.9 W3C Context Protocol (`provide`, `consume`, `createContext`)](#69-w3c-context-protocol-provide-consume-createcontext)
  - [§6.10 Form-Associated Custom Elements (`formAssociated: true`)](#610-form-associated-custom-elements-formassociated-true)
  - [§6.11 CSS Scoping, Specificity Taming (`@layer`, `:where()`), Slot Transparency & `::slotted()`](#611-css-scoping-specificity-taming-layer-where-slot-transparency-slotted)
- [§7. Framework Extensibility (`definePlugin`)](#7-framework-extensibility-defineplugin)
  - [§7.1 Plugin Schema & Physical Source Error Mapping (`rootDir`, `filePath`)](#71-plugin-schema-physical-source-error-mapping-rootdir-filepath)
  - [§7.2 Context Resolver System (Static vs. Two-Phase Instance Context)](#72-context-resolver-system-static-vs-two-phase-instance-context)
  - [§7.3 Server & Client Lifecycle Hooks](#73-server-client-lifecycle-hooks)
- [§8. Configuration (`coralite.config.js` / `defineConfig`)](#8-configuration-coraliteconfigjs-defineconfig)
  - [§8.1 Core `defineConfig` vs. `coralite-scripts` Requirements](#81-core-defineconfig-vs-coralite-scripts-requirements)
  - [§8.2 Complete Options Reference](#82-complete-options-reference)
- [§9. Asset Management & Automated SRI Injection](#9-asset-management-automated-sri-injection)
- [§10. Built-In Plugins](#10-built-in-plugins)
- [§11. Automated Testing & E2E](#11-automated-testing-e2e)
- [§12. Native Form & Input Interaction Patterns](#12-native-form-input-interaction-patterns)
- [§13. Collections Architecture (`CoraliteCollection`)](#13-collections-architecture-coralitecollection)
- [§14. Error Handling (`CoraliteError` & `CoraliteBuildError`)](#14-error-handling-coraliteerror-coralitebuilderror)
- [§15. Component Validation & AST Auto-Fixer](#15-component-validation-ast-auto-fixer)
- [§16. Plugin Validation & Auto-Fixer](#16-plugin-validation-auto-fixer)
- [§17. Content Security Policy (CSP Level 2/3)](#17-content-security-policy-csp-level-23)
- [§18. Page Auditing & Encapsulation](#18-page-auditing-encapsulation)
- [§19. CLI & Tooling Ecosystem](#19-cli-tooling-ecosystem)
- [§20. Application Performance Architecture & Optimization](#20-application-performance-architecture-optimization)

---

## 0. Critical Directives

When generating code or providing instructions for Coralite applications, you MUST, SHOULD, and MUST NEVER adhere to the following normative rules:

1. **MUST use `defineComponent`**: Never generate vanilla Web Component classes (`class extends HTMLElement`) or call `customElements.define()` manually for components. Always export `defineComponent({ ... })` from `'coralite'`.
2. **MUST author components in `.html`**: Component definitions are strictly HTML files (`.html`) containing `<template id="tag-name">`, optional `<style>`, and optional `<script type="module">`. Never create `.js` or `.jsx` component files.
3. **MUST respect the Serialization Boundary**: The `server()` block runs strictly in Node.js during build/SSR and is stripped from browser client bundles. The `client()` block runs in the browser and cannot capture outer module-scope variables or imports from the server context. Bridge data through `server()` return values.
4. **MUST obey the "Smart State, Dumb Template" rule**: Coralite templates strictly permit flat identifier interpolations (`{{ propertyName }}`). Never write expressions (`{{ a + b }}`), function calls (`{{ format(val) }}`), or negations (`{{ !isActive }}`) inside template curlies. All logic must be lifted to getters.
5. **NEVER use inline event handlers in templates (`CORALITE-E203`)**: Attributes like `onclick="..."` or `onsubmit="..."` in `<template>` violate CSP and trigger `CORALITE-E203`. All wiring must be done via `refs()` in `client()`.
6. **MUST pass `{ signal }` to all event listeners**: The lifecycle `signal` in `client({ signal })` is aborted on element disconnection. Passing `{ signal }` to `addEventListener` (on `root`, `refs()`, `window`, `document`, or parent forms) guarantees automatic cleanup with zero memory leaks.
7. **MUST use `emit()` instead of `root.dispatchEvent`**: `emit(name, detail, options)` automatically defaults to `{ bubbles: true, composed: true }`, essential for custom element boundary crossing.
8. **NEVER write manual `Object.defineProperty(root, ...)`**: Coralite automatically synthesizes live camelCase getters/setters on the host element for all declared attributes. Setting `host.value = 'abc'` automatically updates reactive `state.value`.
9. **NEVER mutate state inside `observe()` (`CORALITE-E302`)**: Mutating observed state inside its own observer causes infinite reactive loops and triggers diagnostic `CORALITE-E302`. `observe()` is strictly for external DOM synchronization or side-effects.
10. **NEVER put test-specific attributes in `attributes` schema**: Schema pollution (`testId: String`, `bodyTestid: String`) leaks into public APIs and production bundles. Query via semantic roles, static `data-testid` in templates, or scoped host queries.
11. **MUST write static plain-text `data-testid` attributes**: Author static test IDs (e.g., `<button data-testid="submit-btn">`). Never attempt dynamic bindings with template curlies (`data-testid="{{ ref_id }}"`). Authored test IDs are preserved verbatim as authored across development, testing, and E2E production test builds (`CORALITE_PRESERVE_TESTID=true`), and scoped via Playwright locator chaining (`comp.getByTestId('submit-btn')`).
12. **MUST destructure getter unified context**: Getters receive a single unified context object `({ state, root, refs, slots, signal })`. You MUST destructure the parameters. Without destructuring, writing `(state) => state.prop` binds `state` to the context object itself, causing `state.prop` to evaluate to `undefined`.
13. **MUST keep `style` getters synchronous**: Style property getters `(state) => ...` receive `state` directly (NOT a context object) and must be strictly synchronous.
14. **MUST handle accessible names without empty labels**: Never render empty `<label for="...">`. Use dynamic templates or accessible name fallback chains (`computedAriaLabel`). Elements with `role="button"` or `role="tab"` must never contain nested interactive elements (`<button>`, `<a>`, `<input>`).
15. **SHOULD use Two-Phase resolvers for instance-dependent plugin context**: Use `(pluginContext) => (instanceContext) => ({ ... })` when plugin context depends on component instance state.
16. **SHOULD configure explicit `rootDir` and `filePath` in plugins**: Providing `rootDir` and `filePath: fileURLToPath(import.meta.url)` in `definePlugin({ ... })` guarantees esbuild maps compiler diagnostics directly to physical source files on disk.

---

## 1. The Golden Optimal App

Copy-pasteable reference setup featuring an interactive component, a Form-Associated Custom Element (FACE), a page consumer, and a production configuration file.

### `src/components/counter-card.html`
```html
<template id="counter-card">
  <div class="card-container">
    <div class="header">
      <slot name="label">Default Counter</slot>
    </div>
    <div class="display">
      <span class="count-value">{{ formattedCount }}</span>
    </div>
    <div class="actions">
      <button ref="decrementBtn" data-testid="decrement-btn" disabled="{{ isMinReached }}">-</button>
      <button ref="incrementBtn" data-testid="increment-btn">+</button>
    </div>
  </div>
</template>

<style>
  :host {
    display: block;
    box-sizing: border-box;
    border: 1px solid #cbd5e1;
    border-radius: 0.5rem;
    padding: 1rem;
  }

  :host(.theme-dark) {
    background-color: #0f172a;
    color: #f8fafc;
  }

  .card-container {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
  }

  .count-value {
    font-size: 1.5rem;
    font-weight: 700;
    color: var(--counter-color, #3b82f6);
  }

  .actions {
    display: flex;
    gap: 0.5rem;
  }

  button {
    cursor: pointer;
    padding: 0.5rem 1rem;
    border-radius: 0.25rem;
    border: 1px solid #94a3b8;
    background: #f1f5f9;
  }

  button:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
</style>

<script type="module">
  import { defineComponent } from 'coralite'

  export default defineComponent({
    attributes: {
      step: { type: Number, default: 1 },
      min: { type: Number, default: 0 }
    },

    server({ state }) {
      return {
        count: 0
      }
    },

    getters: {
      formattedCount: ({ state }) => `Count: ${state.count}`,
      isMinReached: ({ state }) => state.count <= state.min
    },

    style: {
      '--counter-color': (state) => (state.count > 5 ? '#22c55e' : '#3b82f6')
    },

    onError({ error, state }) {
      return {
        template: '<div class="error-fallback"><p>{{ message }}</p></div>',
        state: { message: 'Counter service unavailable.' }
      }
    },

    client: async ({ state, signal, refs, emit, observe, updateComplete }) => {
      refs('decrementBtn').addEventListener('click', () => {
        if (state.count > state.min) {
          state.count -= state.step
          emit('change', { count: state.count })
        }
      }, { signal })

      refs('incrementBtn').addEventListener('click', () => {
        state.count += state.step
        emit('change', { count: state.count })
      }, { signal })

      observe('count', (newVal) => {
        if (newVal > 10) {
          emit('threshold-reached', { count: newVal })
        }
      })

      await updateComplete
    }
  })
</script>
```

### `src/components/custom-input.html`
```html
<template id="custom-input">
  <div class="input-wrapper">
    <label for="{{ ref_input }}"><slot></slot></label>
    <input
      id="{{ ref_input }}"
      ref="input"
      type="text"
      name="{{ name }}"
      value="{{ value }}"
      disabled="{{ disabled }}"
      placeholder="{{ placeholder }}"
      aria-invalid="{{ hasError }}"
    >
  </div>
</template>

<style>
  :host {
    display: block;
    margin-bottom: 1rem;
  }

  .input-wrapper {
    display: flex;
    flex-direction: column;
    gap: 0.25rem;
  }

  label {
    font-size: 0.875rem;
    font-weight: 500;
    color: #334155;
  }

  input {
    padding: 0.5rem 0.75rem;
    border: 1px solid #cbd5e1;
    border-radius: 0.375rem;
    font-size: 1rem;
  }

  input:focus {
    outline: 2px solid #3b82f6;
    outline-offset: 1px;
  }

  input:disabled {
    background-color: #f1f5f9;
    cursor: not-allowed;
  }
</style>

<script type="module">
  import { defineComponent } from 'coralite'

  export default defineComponent({
    formAssociated: true,

    attributes: {
      name: { type: String, default: '' },
      value: { type: String, default: '' },
      placeholder: { type: String, default: '' },
      required: { type: Boolean, default: false },
      disabled: { type: Boolean, default: false }
    },

    server({ state }) {
      return {}
    },

    getters: {
      hasError: ({ state }) => Boolean(state.required && !state.value)
    },

    client({ state, signal, refs, emit, observe, setFormValue, setValidity, onFormReset, onFormDisabled, onFormRestore }) {
      const inputEl = refs('input')

      // 1. Initial form synchronization
      if (setFormValue) {
        setFormValue(state.value)
      }
      if (setValidity) {
        setValidity(
          state.required && !state.value ? { valueMissing: true } : {},
          state.required && !state.value ? 'This field is required.' : '',
          inputEl
        )
      }

      // 2. Reactive form synchronization on state change
      observe('value', (val) => {
        if (setFormValue) setFormValue(val)
        if (setValidity) {
          setValidity(
            state.required && !val ? { valueMissing: true } : {},
            state.required && !val ? 'This field is required.' : '',
            inputEl
          )
        }
      })

      // 3. User input binding with lifecycle signal
      inputEl.addEventListener('input', (e) => {
        state.value = e.target.value
        emit('change', { value: state.value })
      }, { signal })

      // 4. Comprehensive FACE lifecycle callbacks
      if (onFormReset) {
        onFormReset(() => {
          state.value = ''
          inputEl.value = ''
        })
      }

      if (onFormDisabled) {
        onFormDisabled((disabled) => {
          state.disabled = disabled
          inputEl.disabled = disabled
        })
      }

      if (onFormRestore) {
        onFormRestore((restoredValue) => {
          state.value = restoredValue || ''
          inputEl.value = state.value
        })
      }
    }
  })
</script>
```

### `src/pages/index.html`
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Coralite Optimal App</title>
</head>
<body>
  <main>
    <h1>Coralite Demo</h1>

    <!-- Dynamic Counter Custom Element -->
    <counter-card step="2" min="0" data-testid="active-counter">
      <span slot="label">Active Counter (Step 2)</span>
    </counter-card>

    <!-- Static SSR-rendered Counter (kebab-case no-hydration strips client scripts) -->
    <counter-card no-hydration step="1">
      <span slot="label">Static Rendered Counter</span>
    </counter-card>

    <!-- Native Form with Form-Associated Custom Element -->
    <form id="profile-form">
      <custom-input name="username" required>Username</custom-input>
      <button type="submit">Submit Profile</button>
    </form>
  </main>
</body>
</html>
```

### `coralite.config.js`
```javascript
import { defineConfig } from 'coralite-scripts'

export default defineConfig({
  output: 'dist',
  components: 'src/components',
  pages: 'src/pages',
  public: 'public',
  mode: 'production',
  styles: {
    input: ['src/css/main.css']
  },
  csp: {
    enabled: true,
    hashAlgorithm: 'sha256',
    injectMeta: true,
    externalScripts: false,
    externalStyles: false
  }
})
```

---

## 2. The Serialization Boundary & Isomorphic Model

Coralite components operate across a strict boundary between Node.js server evaluation and browser client hydration.

```
+-----------------------------------------------------------------------+
| SERVER BUILD PASS (Node.js >=22.22.2)                                  |
|                                                                       |
| [attributes] -> [server()] -> [getters] -> SSR Template Compiler      |
|                                                  |                    |
|                                                  v                    |
|                                       Merged State Snapshot           |
+--------------------------------------------------|--------------------+
                                                   |
                                            HTML + JSON Bridge
                                                   |
                                                   v
+-----------------------------------------------------------------------+
| BROWSER CLIENT HYDRATION (Browser)                                    |
|                                                                       |
| Unpack Hydration Snapshot -> Hydrate State Proxy                      |
|                                   |                                   |
|                                   v                                   |
|                          [client({ state })]                          |
+-----------------------------------------------------------------------+
```

1. **`server` Execution**: The `server()` block executes during SSR in Node.js. Top-level imports from Node.js standard modules (`node:fs`, `node:path`) or server-only packages are permitted here.
2. **Stripping Phase**: At compile time, esbuild removes the `server` block and outer static imports from the client JavaScript module payload.
3. **Hydration Bridge**: Values returned by `server()` are serialized to JSON and embedded into the HTML payload. In the browser, Coralite hydrates this data directly into the component's reactive state proxy.
4. **Client Isolation**: The `client()` block cannot reference variables from outer module scope unless they are returned by `server()` or imported dynamically (`await import(...)`) inside `client()`.

---

## 3. File Structure: Pages vs. Components

* **Pages (`src/pages/*.html`)**: Pages are standard `.html` files that represent route entry points. Pages contain HTML document structure (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) and declare custom element component tags as consumers (e.g. `<counter-card></counter-card>`). Pages must never contain component internal logic or manipulate custom element internals.
* **Components (`src/components/*.html`)**: Components are single-file HTML definitions consisting of up to three root tags:
  1. `<template id="component-name">` (**Required**): Defines the element markup structure. The template ID MUST match the component's custom element tag name.
  2. `<style>` (**Optional**): Defines component CSS. Automatically scoped under `@layer components`.
  3. `<script type="module">` (**Optional**): Defines component reactive logic exporting `defineComponent({ ... })`.

---

## 4. System Architecture, Fault Isolation & Asset Integrity

* **Deterministic SSR**: Components render on the server with deterministic instance tracking (`data-cid="counter-card-0"`). Custom element host tags are preserved in the HTML output, and template markup is injected as Light DOM children.
* **Incremental Static Generation**: Rebuilds skip unchanged pages and components via `.coralite/manifest.json` tracking. Failed page renders are recorded in `manifest.failed` and retried automatically on subsequent builds.
* **Page-Level Fault Isolation**: Failures during multi-page rendering (`coralite.build()`) are isolated to individual failed pages (`status: 'failed'`). Sibling pages complete rendering without interruption. At build conclusion, `coralite.build()` throws `CoraliteBuildError` (unless `failOnError: false` is configured).
* **Asset Integrity**: `coralite.save()` wraps build execution in a `try / catch / finally` block. Saved HTML files and asset manifest writes are flushed inside `finally` before re-throwing build errors, ensuring saved pages never reference missing or unwritten asset bundles.

---

## 5. Static Components (Declarative SSR-Only)

Static components perform pure template interpolation without JS scripting overhead.

```html
<template id="user-badge">
  <div class="badge">
    <span class="name">{{ name }}</span>
    <span class="role">{{ role }}</span>
  </div>
</template>

<style>
  :host {
    display: inline-block;
  }
  .badge {
    padding: 0.25rem 0.5rem;
    border-radius: 0.25rem;
    background: #e2e8f0;
  }
</style>
```

- **Data Binding**: Attribute values passed on host tags (e.g., `<user-badge name="Alice" role="Admin"></user-badge>`) render directly into flat `{{ name }}` and `{{ role }}` interpolations.
- **Zero Client Footprint**: Static components output zero client JavaScript chunks.

---

## 6. Dynamic Components (`defineComponent` API Reference)

Dynamic components combine declarative HTML templates with reactive JavaScript state machines.

### 6.1 Complete Schema & Block Signatures

```typescript
export default defineComponent({
  attributes?: Record<string, AttributeSchema>,
  server?: (context: CoraliteServerContext) => Promise<Record<string, any>> | Record<string, any>,
  getters?: Record<string, (context: CoraliteGetterContext) => any>,
  style?: Record<string, ((state: any) => string | number | null | undefined | false) | string | number>,
  client?: (context: CoraliteClientContext) => void | Promise<void>,
  slots?: Record<string, CoraliteComputedSlotFunction | CoraliteModuleSlotFunction>,
  provide?: Record<string | symbol, any> | Map<any, any>,
  consume?: string[] | Record<string, any>,
  formAssociated?: boolean,
  onError?: (context: { error: Error, state: any, element?: any, page?: any, root?: any }) => string | { template?: string, state?: object } | void
})
```

- Note: `slots` supports both single-argument computed slot functions `(context: CoraliteSlotContext) => any` and two-argument node transform functions `(nodes: Node[], context: CoraliteSlotContext) => any`.

### 6.2 `attributes` (Coercion Pipeline, Validation & ARIA Rules)

Attributes declare, coerce, and validate host HTML attributes into reactive component state.

#### Automatic Host Property Accessors
Every attribute declared in `attributes` automatically synthesizes live camelCase getters/setters on the host element (`host.value = 'abc'` automatically updates reactive `state.value`). Never define manual accessors with `Object.defineProperty(root, ...)`.

#### Allowed Types & Reflection Semantics
- **Allowed Constructors**: `String`, `Number`, `Boolean`.
- **Blocked Constructors**: `Array` and `Object` constructors throw a `CoraliteError`. Use `server()` or contexts for complex objects.
- **Reflection**:
  - `Boolean` reflects presence automatically (`attr=""` when truthy, removed when falsy).
  - `String` and `Number` do NOT reflect by default; specify `reflect: true` to reflect attribute changes back to the host element.
- **Nullish Attribute Omission (`default: null`)**:
  - When an attribute schema specifies `default: null` (e.g. `pattern: { type: String, default: null }` or `{ type: 'string', default: null }`) and no attribute value is supplied on the host element, state evaluates to `null` and Coralite automatically omits the attribute from rendered DOM nodes (preventing invalid empty attributes like `<input pattern="">`).
  - When explicit string values (including explicit empty strings like `alt=""` or `placeholder=""`) are supplied, Coralite preserves the empty attribute value on DOM elements.
- **Native & Custom Boolean Attributes**: Single-token bindings on 43 native HTML boolean attributes (`disabled="{{ isDisabled }}"`, `open="{{ isOpen }}"`) or custom attributes declared as boolean in their target component schema (`loading: Boolean` / `{ type: Boolean }`, e.g. `loading="{{ isCreating }}"`) automatically evaluate truthiness as boolean presence attributes (rendered as `attr=""` if truthy, removed completely if falsy).
- **Shorthands**:
  - `isChecked: Boolean`
  - `status: ['active', 'inactive', 'pending']` (short for string enum values)
- **Full Schema**:

```javascript
attributes: {
  count: {
    type: Number,
    default: 0,
    required: false,
    reflect: true,
    transform: (val) => Math.max(0, val),
    validate: (val) => (val >= 0 ? true : 'Count must be non-negative')
  }
}
```

#### The 6-Step Attribute Execution Lifecycle Pipeline
1. **`required` Check**: Missing required attributes throw `CoraliteError`. `required: true` cannot be combined with `default`.
2. **Type `coerce`**: Converts raw attribute string input using declared constructor.
3. **`transform`**: Runs synchronous `transform(value)` function. Must be synchronous.
4. **`values` Check**: Validates transformed value against allowed enumeration array.
5. **`validate`**: Runs synchronous `validate(value)` predicate. Returning `false` triggers standard validation error; returning a non-empty string uses that string as custom message; throwing an error propagates exception.
6. **State Application**: Applies sanitized final value to `state`.

#### ARIA Attribute Removal Rules
- **Core ARIA States (`aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`)**: Falsy values (`false`, `'false'`, `0`, `'0'`) format as `'false'`. Standard truthy values format as `'true'`. Removed ONLY when bound value evaluates to `null`, `undefined`, `''`, `'null'`, or `'undefined'`.
- **Generic ARIA Attributes**: Removed completely when bound value evaluates to falsy (`false`, `'false'`, `null`, `'null'`, `undefined`, `'undefined'`, `''`), preserving numeric `0` / `'0'`.

### 6.3 `server` (SSR Data Fetching & Context Keys)

Executed exclusively on the server during SSR. Returns an object merged into component state.

#### Verbatim TypeScript Type Signature (`CoraliteServerContext`)
```typescript
type CoraliteServerContext<TState = Record<string, any>> = {
  state: TState,
  root?: HTMLElement | null,
  session?: CoraliteSession,
  page?: CoralitePage,
  signal?: AbortSignal,
  slots?: Record<string, any>,
  refs?: (id: string) => any
}
```

#### Runtime Context Extensions
At runtime during SSR, the context object passed to `server()` is intersected with `& TState & Record<string, any>` and augmented with engine runtime properties:
- `id`: Unique instance identifier string.
- `module`: Module definition object.
- `app`: Application instance.
- `noHydration`: Boolean indicating if hydration is stripped.
- Injected server plugin context properties.

### 6.4 `getters` (Unified Context Mechanics)

Isomorphic derived state computed synchronously from state and element context. Getters must be pure functions without side-effects, state mutations, or event dispatching.

#### Verbatim TypeScript Type Signature (`CoraliteGetterContext`)
```typescript
type CoraliteGetterContext<TState = Record<string, any>> = {
  state: Readonly<TState>,
  root: HTMLElement | null,
  refs: (id: string) => HTMLElement | null,
  slots: CoraliteSlotsHelper,
  signal: AbortSignal
}
```

#### Runtime Context Mechanics & Destructuring Rule
Getters strictly receive the single **Unified Context Object** `{ state, root, refs, slots, signal }` as their single argument.
- **Destructuring Required**: You MUST write `({ state }) => ...` or `({ refs, slots }) => ...`.
- **Parameter Binding Behavior**: If authored as `(state) => state.count` without object destructuring, JavaScript binds the context object itself to the parameter named `state`. Evaluating `state.count` accesses `context.count` which returns `undefined` without throwing an error.

```javascript
getters: {
  // CORRECT: Destructured context
  fullName: ({ state }) => `${state.firstName} ${state.lastName}`,
  hasIcon: ({ slots }) => slots.has('icon'),
  iconCount: ({ slots }) => slots.count('icon'),
  inputLength: ({ refs }) => refs('field')?.value.length ?? 0
}
```

### 6.5 `style` (Synchronous Reactive Host Styles & CSS Vars)

Maps CSS properties and CSS custom properties (`--*`) to static values or synchronous getter functions `(state: TState) => string | number | null | undefined | false`.

**Important**: Style functions receive `(state)` directly as their first argument, NOT a context object.

```javascript
style: {
  display: (state) => (state.hidden ? 'none' : 'block'),
  '--theme-accent': (state) => state.color,
  '--counter-color': (state) => (state.count > 5 ? '#22c55e' : '#3b82f6'),
  opacity: (state) => state.opacity // numeric 0 is preserved as valid CSS
}
```
- Returning `null`, `undefined`, `false`, or `''` removes the style property.
- Numeric `0` is strictly preserved as `'0'`.
- Functions MUST be synchronous. Returning a `Promise` throws `CoraliteError`.

### 6.6 `client` (Lifecycle, `errors`, `updateComplete`, FACE Hooks)

Executes in the browser runtime when custom elements connect to the DOM.

#### Verbatim TypeScript Type Signature (`CoraliteClientContext`)
```typescript
type CoraliteClientContext<TState = Record<string, any>> = {
  id: string,
  instanceId: string,
  root: HTMLElement,
  state: TState,
  errors: Record<string, string>,
  refs: (refName: string) => HTMLElement | null,
  signal: AbortSignal,
  observe: (propertyName: string, callback: (newValue: any, oldValue: any) => void) => (() => void),
  emit: (eventName: string, detail?: any, options?: CustomEventInit) => boolean,
  internals?: ElementInternals | null,
  setFormValue?: (value: any, state?: any) => void,
  setValidity?: (flags?: ValidityStateFlags, message?: string, anchor?: HTMLElement) => void,
  checkValidity?: () => boolean,
  reportValidity?: () => boolean,
  updateComplete: Promise<boolean>,
  validity?: ValidityState,
  validationMessage?: string,
  form?: HTMLFormElement | null,
  onFormReset?: (callback: () => void) => () => void,
  onFormDisabled?: (callback: (disabled: boolean) => void) => () => void,
  onFormRestore?: (callback: (state: any, mode: 'restore' | 'autocomplete') => void) => () => void
}
```

- **`updateComplete`**: Resolves when current reactive update cycles settle. Returns `Promise.resolve(true)` immediately when idle.
- **`observe(key, cb)`**: Registers explicit state change listener returning a disposer function. Automatically cleaned up when disconnected. Never mutate observed state inside `observe()`.
- **`emit(name, detail?, options?)`**: Dispatches a bubbling, composed `CustomEvent` from `root`.
- **`signal`**: AbortSignal aborted on element disconnection. Always pass `{ signal }` to `addEventListener`.

### 6.7 `slots` (Reactive Element Builders)

Slot builders intercept and transform Light DOM content projected into component `<slot>` elements.

#### Verbatim TypeScript Type Signature (`CoraliteSlotBuilderContext`)
```typescript
type CoraliteSlotBuilderContext<TState = Record<string, any>> = {
  name: string,
  state: TState,
  root: HTMLElement | null,
  refs: (id: string) => HTMLElement | null,
  signal: AbortSignal,
  observe: (key: string, callback: (val: any) => void) => () => void,
  instanceId: string,
  isServer: boolean,
  isClient: boolean,
  slots: Record<string, any>
}
```

```javascript
slots: {
  default: (nodes, { state, observe }) => {
    // Void / undefined return bypasses client transformation to preserve SSR DOM
    if (typeof window !== 'undefined' && state.isStatic) return undefined
    return nodes.map((node) => transformNode(node))
  }
}
```

### 6.8 `onError` (SSR Component Error Boundaries)

Handles component rendering failures during SSR in production mode.

```javascript
onError({ error, state, element, page, root }) {
  return {
    template: '<div class="fallback"><p>{{ message }}</p></div>',
    state: { message: 'Component failed to render.' }
  }
}
```
- Returns string HTML or object `{ template, state }`.
- Automatically strips hydration markers (`noHydration: true`).
- In `development` and `testing` modes, errors re-throw to preserve diagnostic visibility.

### 6.9 W3C Context Protocol (`provide`, `consume`, `createContext`)

Aligns with the standard W3C Web ComponentsCG Context Protocol for tree-based dependency injection.

```javascript
// Ancestor Provider Component (provider-card.html)
import { defineComponent, createContext } from 'coralite'

export const themeContext = createContext('theme')

export default defineComponent({
  provide: {
    [themeContext]: ({ state }) => state.theme
  }
})
```

```javascript
// Descendant Consumer Component (consumer-badge.html)
import { defineComponent } from 'coralite'
import { themeContext } from './theme.js'

export default defineComponent({
  consume: {
    currentTheme: themeContext
  },
  client: ({ state }) => {
    console.log('Consumed theme:', state.currentTheme)
  }
})
```

### 6.10 Form-Associated Custom Elements (`formAssociated: true`)

Opt-in integration with native HTML `<form>` submissions and constraint validations.

```javascript
export default defineComponent({
  formAssociated: true,
  attributes: {
    value: {
      type: String,
      default: '',
      validate: (val) => (val.length >= 3 ? true : 'Minimum 3 characters required')
    }
  },
  client: ({ state, signal, refs, setFormValue, setValidity, onFormReset, observe }) => {
    const input = refs('input')
    setFormValue(state.value)

    observe('value', (val) => {
      setFormValue(val)
      setValidity(val ? {} : { valueMissing: true }, val ? '' : 'Required', input)
    })

    onFormReset(() => {
      state.value = ''
    })
  }
})
```

### 6.11 CSS Scoping, Specificity Taming (`@layer`, `:where()`), Slot Transparency & `::slotted()`

- **Light DOM Architecture**: Coralite components render in Light DOM, not Shadow DOM. Encapsulation is achieved via CSS Scoping, PostCSS processing, and `@layer components`.
- **Cascade Layer**: Component CSS is wrapped inside `@layer components`. Unlayered utility classes override component styles naturally.
- **Host Styling**: Use `:host` or `:host-context(.dark)` to style the host element. Host selectors are wrapped in `:where(tag-name)` to add zero specificity. Writing `:host .child` is redundant; write `.child` directly.
- **Slot Layout Transparency (`display: contents`)**: Coralite injects `slot, c-token { display: contents; }` outside `@layer components`, allowing projected slotted children to participate directly in parent Flexbox/Grid layouts without extra box wrapping.
- **`::slotted(selector)` Transformation**: Coralite's compiler transforms `::slotted(selector)` into Light DOM scoped selectors (`& > slot > selector` and `& > selector[slot]`).

---

## 7. Framework Extensibility (`definePlugin`)

Plugins extend Coralite across server build pipelines and browser client runtimes.

### 7.1 Plugin Schema & Physical Source Error Mapping (`rootDir`, `filePath`)

```javascript
import { definePlugin } from 'coralite'
import { fileURLToPath } from 'node:url'

export default definePlugin({
  name: 'analytics-plugin',
  rootDir: process.cwd(),
  filePath: fileURLToPath(import.meta.url),

  server: {
    context: (pluginContext) => (instanceContext) => ({
      trackServerEvent: (evt) => { /* ... */ }
    }),
    onBeforeBuild: async ({ app }) => { /* ... */ }
  },

  client: {
    context: (pluginContext) => (instanceContext) => ({
      trackClientEvent: (evt) => { /* ... */ }
    })
  }
})
```

#### Physical Path Resolution Precedence
esbuild error mapping resolves plugin paths using precedence:
1. Explicit `rootDir` and `filePath` options (must be filesystem path, e.g. via `fileURLToPath`).
2. `client.rootDir` and `client.filePath` properties.
3. Caller stack-derived file paths (skipping Node internals and `node_modules`).

### 7.2 Context Resolver System (Static vs. Two-Phase Instance Context)

- **Static Context Object**: Use an object literal `context: { myUtil: () => {} }` for static global helpers.
- **Two-Phase Curried Context**: Use `(pluginContext) => (instanceContext) => ({ ... })` when plugin context depends on component instance state or needs lazy cross-plugin resolution.

### 7.3 Server & Client Lifecycle Hooks

- **Server Hooks**: `onBeforeBuild`, `onPageSet`, `onPageUpdate`, `onPageDelete`, `onComponentSet`, `onComponentUpdate`, `onComponentDelete`, `onBeforePageRender`, `onBeforeComponentRender`, `onAfterComponentRender`, `onAfterPageRender`, `onAfterBuild`.
- **Client Hooks**: `onBeforeComponentRender`, `onAfterComponentRender`, `onDisconnected`.

---

## 8. Configuration (`coralite.config.js` / `defineConfig`)

### 8.1 Core `defineConfig` vs. `coralite-scripts` Requirements

- **Core `'coralite'` (`defineConfig`)**:
  - Required properties: `output`, `components`, `pages`.
- **App `'coralite-scripts'` (`defineConfig`)**:
  - Required properties: `output`, `components`, `pages`, `public`.

### 8.2 Complete Options Reference

```javascript
import { defineConfig } from 'coralite-scripts'

export default defineConfig({
  output: 'dist',
  components: 'src/components',
  pages: 'src/pages',
  public: 'public',
  baseURL: '/',
  mode: 'production',
  incremental: true,
  styles: {
    input: ['src/css/main.css'],
    processors: {
      postcss: { plugins: [] }
    }
  },
  assets: [
    { src: 'src/assets/images', dest: 'assets/images' }
  ],
  csp: {
    enabled: true,
    hashAlgorithm: 'sha256'
  },
  server: {
    port: 3000
  }
})
```

---

## 9. Asset Management & Automated SRI Injection

Configure static assets in `coralite.config.js` to copy files and automatically inject tags with Subresource Integrity (SRI) hashes.

```javascript
export default defineConfig({
  assets: [
    {
      pkg: 'altcha',
      path: 'dist/altcha.js',
      dest: 'assets/js/altcha.js',
      inject: {
        type: 'script',
        placement: 'body-end',
        sri: true, // Computes sha384 integrity and adds crossorigin="anonymous"
        pages: ['*']
      }
    }
  ]
})
```

---

## 10. Built-In Plugins

- **Metadata Plugin**: Extracts page title and SEO meta tags during SSR.
- **Static Asset Plugin**: Copies static public assets to build output.
- **Testing Plugin**: Activated in `mode: 'testing'`, injecting `data-testid` attributes and DevTools telemetry hooks.

---

## 11. Automated Testing & E2E

### Testing Mode Target (`mode: 'testing'`)
- **Velocity Engine**: Coralite's testing plugin automatically suppresses animations, transitions, and smooth scrolling (`*, *::before, *::after { transition: none !important; animation: none !important; scroll-behavior: auto !important; }`) to guarantee instantaneous test execution and deterministic visual snapshots.
- **Three-Tier Prototype Patching**: In `development` and `testing` modes, Coralite patches `Element.prototype.innerHTML`, `outerHTML`, and `document.createElement` to automatically import chunks and upgrade custom elements injected via test fixtures (`mountComponent`) or DevTools console. In production builds, zero prototype patching code is emitted.
- **Settlement**: Wait on `await el.updateComplete` before assertions to ensure all reactive renders and observers have completely settled.

### Selector Strategy & `data-testid` Rules
- **Canonical Playwright Testing Pattern**: Locate the host component element first using Playwright's locator (`const comp = page.locator('counter-card').first()`), then query internal elements using Playwright's native locator chaining (`await comp.getByTestId('increment-btn').click()`) or accessible role locators (`comp.getByRole('button', { name: 'Submit' })`).
- **Authored `data-testid` Preserved Verbatim**: `<button data-testid="submit-btn">` renders verbatim as `<button data-testid="submit-btn">` without dynamic instance prefixing (`comp-0__`).
- **No `ref` Duplication or Positional Auto-IDs**: `ref` attributes are used exclusively for component internal script access (`refs(...)`) and are never copied to `data-testid`. Untagged elements should be queried via accessible role locators.
- **Production Retention (`CORALITE_PRESERVE_TESTID=true`)**: `testingPlugin` preserves `data-testid` in production builds when `CORALITE_PRESERVE_TESTID=true` or `preserveTestId: true` is configured. In public customer builds (without `CORALITE_PRESERVE_TESTID`), `data-testid` attributes are stripped for zero HTML overhead.
- **Forbidden**: Never write dynamic expression test IDs (`data-testid="{{ ref_id }}"`), brittle chained CSS tag names, or regex prefix matchers (`/comp-\d+__btn/`).

### DevTools Introspection
```javascript
// Access component test context in E2E tests
const testContext = element[Symbol.for('coralite.testing')]
// { instanceId, componentId, state, getters, refs }
```

---

## 12. Native Form & Input Interaction Patterns

### Checkbox & Radio Filter Pattern
Wrap inputs in `<label>` elements and generate unique `id` and `for` attributes using `refs` or `instanceId`.

```html
<template id="filter-option">
  <label for="{{ ref_input }}"><slot></slot></label>
  <input id="{{ ref_input }}" ref="input" type="checkbox" name="{{ name }}">
</template>
```

### Accessibility & Keyboard Navigation Best Practices
- **Accessible Names**: Never render an empty `<label for="...">`. If label text is optional, compute label markup dynamically or provide an accessible name fallback:

```javascript
getters: {
  computedAriaLabel: ({ state }) => {
    if (state.label) return null
    return state.ariaLabel || state.placeholder || 'Default Label'
  }
}
```
- **No Nested Interactive Elements**: Custom elements with `role="button"` or `role="tab"` must never contain interactive children (`<button>`, `<a href>`, `<input>`).
- **Keyboard Handling**: Custom buttons must support `tabindex="0"` (or `-1` when disabled) and listen for `keydown` events handling `Enter` and `Space` with `event.preventDefault()`.

---

## 13. Collections Architecture (`CoraliteCollection`)

Coralite maintains structured collections `app.pages` and `app.components`.

- **`list`**: Flat array of collection items.
- **`listByPath`**: Folder-grouped items dictionary.
- **`collection`**: Map of unique ID / pathname to collection item.
- **Methods**: `getItem(id)`, `setItem(val)`, `deleteItem(id)`, `getListByPath(dir)`.

---

## 14. Error Handling (`CoraliteError` & `CoraliteBuildError`)

- **`CoraliteError`**: Standard error class containing `componentId`, `filePath`, `instanceId`, `pagePath`, `line`, `column`, and `cause`.
- **`CoraliteBuildError`**: Thrown at conclusion of `coralite.build()` when `failedPages.length > 0` and `failOnError: true`. Exposes `failedPages` array containing error objects.

---

## 15. Component Validation & AST Auto-Fixer

Audit component files using `coralite validate-components`:

```bash
npx coralite validate-components -c src/components --coverage --strict
```

### Diagnostic Severity Model
Diagnostics emitted by the AST validator follow a three-level severity model:
- `error`: Fatal syntax, schema, or reactivity rule violation. Fails validation.
- `warning`: Unused symbols, dead CSS, or redundant checks.
- `info`: Informational suggestion.

### Rule Categories & Verified Diagnostic Codes
- **Attribute Schema**:
  - `CORALITE-E101`: Non-primitive `Array` or `Object` constructor in attribute schema.
  - `CORALITE-E102`: Mutex violation (`required: true` combined with `default`).
  - `CORALITE-E103`: Asynchronous `transform` or `validate` function.
  - `CORALITE-E104`: Attribute name collides with reserved context or slot key.
  - `CORALITE-E105`: Getter context parameter misuse (non-destructured `(state) => ...`).
  - `CORALITE-E106`: Invalid `provide` or `consume` configuration schema.
- **Template Syntax**:
  - `CORALITE-E201`: Complex, arithmetic, or non-identifier template expression (e.g. `{{ a + b }}`). (Auto-fixer lifts expression to derived getter).
  - `CORALITE-E202`: Missing `ref` declaration referenced by `refs('name')`. (Auto-fixer injects `ref` on matching element).
  - `CORALITE-E203`: Inline event listener attribute (`onclick`, `onsubmit`) in `<template>`.
  - `CORALITE-W204`: Redundant existence check on template ref (e.g. `if (btn)`).
- **Client & Reactivity Boundaries**:
  - `CORALITE-E301`: Outer static module import referenced in `client()`. (Auto-fixer rewrites to dynamic `await import(...)`).
  - `CORALITE-E302`: Reactive state mutation detected inside `observe()` callback.
  - `CORALITE-E303`: Asynchronous getter function in `style` block.
- **Dead Code & Coverage**:
  - `CORALITE-W401`: Unused getter, server property, or declared attribute.
  - `CORALITE-W402`: Dead CSS selectors or unused element `ref="..."` declaration.

### CLI Flags & Pragmas
- **CLI Options**:
  - `--strict`: Treats warnings as errors (exits with code 1 on warnings).
  - `--coverage`: Calculates component symbol usage coverage percentage.
  - `--fix`: Automatically applies AST remediations (e.g., lifting template expressions to getters).
  - `--dry-run`: Previews auto-fixes without writing changes to disk.
- **Ignore Pragmas**:
  - `<!-- coralite-ignore symbol1, symbol2 -->` / `/* coralite-ignore symbol1 */`: Ignores unused warnings for specific symbols.
  - `coralite-ignore-unused` / `@coralite-ignore-unused`: Suppresses all unused symbol warnings for the entire component.

---

## 16. Plugin Validation & Auto-Fixer

Audit plugins using `coralite validate-plugins`:

- `CORALITE-P101`: Missing plugin `name`.
- `CORALITE-P201`: Single-phase context function. (Auto-fixer wraps in Two-Phase function).
- `CORALITE-P401`: Missing `definePlugin` wrapper call. (Auto-fixer injects `import { definePlugin } from 'coralite'` and wraps export).

---

## 17. Content Security Policy (CSP Level 2/3)

Supports Nonce mode (SSR), Hash mode (SSG), and External Scripts/Styles mode.

```javascript
export default defineConfig({
  csp: {
    enabled: true,
    hashAlgorithm: 'sha256',
    injectMeta: true,
    externalScripts: false,
    externalStyles: false,
    directives: {
      'default-src': ["'self'"],
      'script-src': ["'self'"],
      'style-src': ["'self'"]
    }
  }
})
```

---

## 18. Page Auditing & Encapsulation

Audit page files using `coralite validate-pages` (or `coralite check --pages`):

- `CORALITE-PAGE-101`: Unknown custom element tag name found on page.
- `CORALITE-PAGE-102`: Page missing required component attribute (`required: true`).
- `CORALITE-PAGE-201`: Encapsulation violation (page script querying internal component elements).

---

## 19. CLI & Tooling Ecosystem

### `coralite-scripts`
- `coralite-scripts dev`: Starts local development server on port 3000 with SSE live-reloading.
- `coralite-scripts test`: Starts automated test server on port 3862 in `testing` mode.
- `coralite-scripts build`: Compiles production static site to `dist`.

### Core `coralite` CLI
- `coralite check`: Multi-domain workspace auditor across components, plugins, and pages.
- `coralite fix [--dry-run]`: Whole-workspace AST auto-linter.
- `coralite init-agent [--cursor] [--claude]`: Scaffolds zero-token `AGENTS.md` guidelines for AI coding assistants.

---

## 20. Application Performance Architecture & Optimization

When building applications with Coralite, follow these architectural principles to achieve optimal runtime speed, minimal bundle sizes, and rapid time-to-interactive (TTI):

### 20.1 Zero-JS Static Components
Components without a `<script type="module">` block or `client` lifecycle function emit **0 bytes of client JavaScript**. The template is evaluated entirely during SSR, and only the resulting HTML markup and scoped CSS are delivered to the browser. Whenever an element only requires data interpolation or layout presentation (such as cards, headers, badges, footers, and article wrappers), author it as a static component.

### 20.2 Selective Hydration via `no-hydration`
If an interactive component is placed on a page where its client-side interactivity is unnecessary (e.g. read-only previews, landing page showcases, or print views), add the kebab-case `no-hydration` attribute to the host element:

```html
<counter-card no-hydration step="1">
  <span slot="label">Static Counter</span>
</counter-card>
```

The Coralite compiler strips client hydration scripts and state hydration markers for that element instance, eliminating browser parsing and execution overhead.

### 20.3 Lean `client()` Lifecycle
Keep the browser `client()` function minimal and focused strictly on DOM event listeners, external API wiring, and DOM side-effects.
- Push state transformations into isomorphic `getters` rather than calculating inside `client()`.
- Use synchronous CSS variables and style getters in the `style` block to drive visual state changes via CSS rather than mutating element classes or styles imperatively in JavaScript.

### 20.4 Synchronous `getters` vs. Imperative `observe()`
- **Use `getters` for derived state**: Getters are pure, cached, and automatically re-evaluated during render cycles without manual bookkeeping.
- **Reserve `observe()` for external side-effects**: Only use `observe(propertyName, callback)` when synchronizing with external non-reactive subsystems (e.g. canvas rendering, WebGL, third-party chart libraries, imperative scrolling, or native form integration).
- **Never mutate state inside `observe()`**: Doing so triggers reactive cascades and diagnostic `CORALITE-E302`.

### 20.5 Coalesced Updates & Settlement via `updateComplete`
Coralite automatically batches reactive state mutations within a microtask cycle. Avoid dispatching rapid DOM queries or measuring layouts immediately after mutating state. Instead, await the `updateComplete` promise:

```javascript
state.count += 1
await updateComplete
// DOM is guaranteed to be updated and settled
```

Never rely on arbitrary `setTimeout` or `requestAnimationFrame` for DOM synchronization.