# EmberLite — Full AI & LLM Technical Specification

> Version: 1.0.0
> Canonical URL: https://emberlite.net/llms-full.txt
> Schema: EmberLite Language (.el) & Markdown Shape Engine
> Architecture: Client-Side Only (Zero Backend), Local-First (IndexedDB), Seeded Deterministic PRNG

---

## 1. System Philosophy & Architecture

EmberLite is designed around strict architectural guarantees:
1. **Local-First & Zero Backend**: All state resides in the browser (IndexedDB and memory). There are no multi-tenant databases or telemetry trackers. Persistence uses Bring Your Own Storage (BYOS).
2. **Deterministic Seeded PRNG**: Procedural content and table rolls are governed by deterministic seeded random algorithms. Given the same seed and table weights, every player sees the exact same result.
3. **Plain Text Interchange**: Every spark, table, character sheet, and procedural map is defined in human-readable Markdown (.md) or EmberLite Language (.el) files.

---

## 2. EmberLite Language (.el) Grammar

The `.el` format is an extended Markdown format for expressing weighted random tables, rollable prompts, and reactive cue chains.

### 2.1 File Header
```markdown
# EmberLite Sparks Dataset
- **Exported:** 2026-09-03T20:00:00.000Z
- **Count:** 3 items across 1 tables
```

### 2.2 Table Declaration
Each table begins with a level-2 heading `## Table: [TableName]` followed by bulleted metadata:
- `- **Category:** [CategoryName]`
- `- **Source:** [SourceURL]` (optional)
- `- **Default Chain:** [TargetTableName]` (optional; defines the next table to roll when this result is rolled)

### 2.3 Options Table Columns
Tables must use standard Markdown pipes with 5 columns:
```markdown
| Result | Weight | Dice | Chain | Notes |
| --- | --- | --- | --- | --- |
| Result String | 1 | 1-2 | TargetTable | Descriptive tags or notes |
```

- **Result**: The primary text string rolled.
- **Weight**: Positive integer representing relative weight for weighted sampling (default: 1).
- **Dice**: Optional range for dice sampling (e.g., `1-2`, `3-4`, `5-6`).
- **Chain**: Optional specific table name to trigger downstream. Overrides `Default Chain`.
- **Notes**: Comma-separated tags or rules (e.g. `slot:11`, `hazard`, `rare`).

### 2.4 Complete `.el` Example
```markdown
# EmberLite Sparks Dataset

## Table: Action
- **Category:** Voidlight
- **Source:** https://farirpgs.com/voidlight
- **Default Chain:** Outcome

| Result | Weight | Dice | Chain | Notes |
| --- | --- | --- | --- | --- |
| SACRIFICE | 1 | 1 | Disaster | slot:11 |
| CHART | 1 | 2 | Navigation | slot:11 |
| BUILD | 1 | 3 | Construction | slot:12 |
| OVERCLOCK | 1 | 4 | Complication | slot:12 |
| IMPROVISE | 1 | 5 | | slot:13 |
| CALIBRATE | 1 | 6 | | slot:13 |

## Table: Outcome
- **Category:** Voidlight

| Result | Weight | Dice | Chain | Notes |
| --- | --- | --- | --- | --- |
| Triumphant Success | 1 | 1 | | +2 Resolve |
| Costly Victory | 2 | 2-3 | | Take 1 Stress |
| Desperate Gambol | 2 | 4-5 | | Lose Gear |
| Catastrophic Failure | 1 | 6 | | Alarm Sounded |
```

---

## 3. Shape & Sheet Markdown Format

EmberLite interactive cards (character sheets, hex maps, trackers) are written in Markdown with `## Section` and `- **Field:**` declarations.

### 3.1 Shape Metadata
```markdown
# Shape: [Shape Name]
- **ID:** [unique_snake_case_id]
- **System:** [Game System Name]
- **Category:** [character | map | combat | roller | party | vehicle]
- **Kind:** [shape | block]
- **Color:** [hex color code, e.g. #0284c7]
- **Icon:** [Lucide icon name, e.g. Shield, MapPinned, Skull, Truck]
- **Description:** [Summary of what this sheet does]
```

### 3.2 Field Types
Fields are declared within sections using pipe delimiters:
`- **Field:** [key] | [Label] | [type] | [defaultValue] | options: [opt1, opt2]`

Supported types:
- `text`: Single-line text input.
- `number`: Numeric counter with +/- stepper buttons.
- `select`: Dropdown menu with defined `options: val1, val2, val3`.
- `checkbox`: Boolean toggle (`true` / `false`).
- `textarea`: Multi-line text block.
- `spark`: Rollable cue slot linked to a table.
- `tags`: Tag list input.

### 3.3 Theme Customization
Shapes can optionally define custom styling in a `## Theme` block:
```markdown
## Theme
- **Font:** Outfit
- **Background:** #0f172a
- **Accent:** #38bdf8
- **Icon:** Compass
- **Icon Fill:** #ffffff
- **Icon Stroke:** #38bdf8
- **Icon Stroke Width:** 1.5
```

---

## 4. Model Context Protocol (MCP) Integration

EmberLite exposes its schemas and templates at `https://emberlite.net/.well-known/mcp.json`.
MCP clients (Claude Desktop, Cursor, local agent runtimes) can use EmberLite as a deterministic TTRPG tool engine.

### Core Tool Functions:
1. `emberlite_roll_table`: Rolls on a specified `.el` table using a seed integer and returns the selected result and downstream chain target.
2. `emberlite_parse_el`: Validates `.el` plain text and returns structured JSON tables.
3. `emberlite_list_templates`: Queries the static manifest (`/templates/manifest.json`) to inspect available modules.

---

## 5. Web Deep-Linking & Import URL Parameters

To load AI-generated content directly into a user's EmberLite browser session, generate URLs with query parameters:

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `importUrl` | URL | Fetches raw `.el` or `.md` from an external URL (e.g. GitHub Gist or Pastebin) and renders on canvas. |
| `el` | Text / Base64 | Decodes inline `.el` or markdown text directly into rollable sparks. |
| `template` | ID | Automatically instantiates a built-in template (e.g. `torchlite_hex_flower_map`). |

### Examples:
- Load remote Gist:
  `https://emberlite.net/spark?importUrl=https://gist.githubusercontent.com/user/123/raw/dungeon.el`
- Instantiate Hex Flower Map:
  `https://emberlite.net/spark?template=torchlite_hex_flower_map`