# IFX Assembly Specification v1.0
## IterFact Exchange Protocol — How Engines Become Documents

---

## 1. Core Concepts

### 1.1 Engine Roles

Every engine in the vault serves one of two roles in any given assembly:

**WRAPPER** — The outer shell that provides navigation, layout structure, and the overall user experience. An assembly has exactly ONE wrapper. The wrapper defines how sections are presented (slides, scroll sections, tabs, single page).

**COMPONENT** — An interactive block injected INTO a wrapper section. An assembly can have 1-20+ components. Components provide the actual functionality (charts, calculators, forms, tables, etc.).

### 1.2 Engine Role Matrix

| Engine | Can Be Wrapper | Can Be Component | Primary Role |
|--------|---------------|-----------------|-------------|
| 01 - Particle Ambient | ✅ | ✅ (background) | Wrapper for immersive experiences |
| 02 - Slide Deck | ✅ | ❌ | Wrapper — most common |
| 03 - Dashboard KPI | ❌ | ✅ | Component — metric cards + charts |
| 04 - 3D Scene | ✅ | ✅ | Wrapper for spatial, component for product showcase |
| 05 - Timeline | ❌ | ✅ | Component — chronological data |
| 06 - Flowchart | ❌ | ✅ | Component — process diagrams |
| 07 - Comparison | ❌ | ✅ | Component — feature matrices |
| 08 - Calculator | ❌ | ✅ | Component — interactive computation |
| 09 - Quiz | ❌ | ✅ | Component — assessment/engagement |
| 10 - Kanban | ❌ | ✅ | Component — task/status tracking |
| 11 - Pricing | ❌ | ✅ | Component — tier comparison |
| 12 - Infographic | ✅ | ✅ | Wrapper for data narratives, component for stats |
| 13 - Flashcard | ❌ | ✅ | Component — learning/reference |
| 14 - Before/After | ❌ | ✅ | Component — visual comparison |
| 15 - Mind Map | ❌ | ✅ | Component — concept relationships |
| 16 - Form/Survey | ❌ | ✅ | Component — data capture |
| 17 - Scenario Modeler | ❌ | ✅ | Component — what-if analysis |
| 18 - Parallax Story | ✅ | ❌ | Wrapper — scroll-driven narrative |
| 19 - Org Chart | ❌ | ✅ | Component — people/hierarchy |
| 20 - Interactive Map | ❌ | ✅ | Component — location data |
| 21 - Guided Tour | ✅ | ❌ | Wrapper — step-by-step walkthrough |
| 22 - Accordion FAQ | ❌ | ✅ | Component — Q&A/reference |
| 23 - Image Gallery | ❌ | ✅ | Component — visual showcase |
| 24 - Event Countdown | ✅ | ✅ | Wrapper for events, component for urgency |
| 25 - E-Sign Contract | ✅ | ✅ | Wrapper for agreements, component for signoff |
| 26 - Data Table | ❌ | ✅ | Component — structured data |
| 27 - Testimonials | ❌ | ✅ | Component — social proof |
| 28 - Checklist | ❌ | ✅ | Component — progress tracking |
| 29 - Waterfall Chart | ❌ | ✅ | Component — financial bridges |
| 30 - Code Playground | ❌ | ✅ | Component — live code editing |

### 1.3 Wrapper Types

Each wrapper defines a different navigation/layout paradigm:

| Wrapper | Navigation Model | Best For |
|---------|-----------------|----------|
| 02 - Slide Deck | Keyboard/swipe between discrete slides | Pitches, proposals, reports, presentations |
| 04 - 3D Scene | Orbit/zoom in 3D space with clickable objects | Architecture, product showcase, spatial data |
| 12 - Infographic | Single continuous scroll with animated reveals | Data stories, one-pagers, marketing assets |
| 18 - Parallax Story | Full-viewport chapters with parallax scroll | Annual reports, case studies, brand stories, longform |
| 21 - Guided Tour | Step-by-step with highlights and tooltips | Product demos, onboarding, training |
| 24 - Event Countdown | Hero + schedule + RSVP sections | Events, launches, invitations |
| 25 - E-Sign Contract | Scrollable terms + acknowledgments + signature | Contracts, agreements, consent |
| 01 - Particle Ambient | Immersive canvas with overlay text | Art, luxury, emotional experiences |

---

## 2. Slot System

### 2.1 How Slots Work

A wrapper defines SLOTS — named positions where components can be injected. Each slot has:
- **slot_id**: Unique name within the wrapper (e.g., "slide-3", "chapter-2", "section-financials")
- **slot_type**: What kind of content fits here ("full-section", "inline-block", "sidebar", "overlay")
- **accepts**: Which engine categories can be injected (e.g., ["data", "tool", "visual"])

### 2.2 Wrapper Slot Definitions

#### Slide Deck Wrapper (Engine 02)
```
slots: [
  { id: "slide-{n}", type: "full-section", accepts: ["any"] }
]
```
Each slide is a slot. Components fill entire slides. Unlimited slides.
A single slide can contain 1-3 components stacked vertically.

#### Parallax Story Wrapper (Engine 18)
```
slots: [
  { id: "chapter-{n}", type: "full-viewport", accepts: ["any"] },
  { id: "chapter-{n}-stats", type: "inline-block", accepts: ["data", "visual"] }
]
```
Each chapter is a full-viewport slot. Stat blocks are inline within chapters.

#### Infographic Wrapper (Engine 12)
```
slots: [
  { id: "section-{n}", type: "scroll-section", accepts: ["any"] }
]
```
Continuous scroll. Each section triggers animation on scroll-into-view.

#### Guided Tour Wrapper (Engine 21)
```
slots: [
  { id: "step-{n}", type: "tooltip-step", accepts: ["text-only"] },
  { id: "backdrop", type: "full-background", accepts: ["visual", "data"] }
]
```
Steps are tooltip overlays. Backdrop is the simulated product/content underneath.

#### E-Sign Wrapper (Engine 25)
```
slots: [
  { id: "terms-section-{n}", type: "document-section", accepts: ["text-only"] },
  { id: "acknowledgments", type: "checkbox-group", accepts: ["form"] },
  { id: "signature", type: "signature-pad", accepts: ["none — built-in"] }
]
```
Document sections are scrollable text. Acknowledgments and signature are fixed.

### 2.3 Component Injection Rules

When a component is injected into a slot:

1. **CSS Isolation**: Component CSS is namespaced to avoid conflicts. Each component gets a unique container class: `.ifx-{engine-id}-{instance}`.

2. **JS Namespacing**: Component JavaScript variables and functions are scoped under a namespace object: `IFX.engine_{id}_{instance}`.

3. **Theme Inheritance**: Components inherit CSS variables from the wrapper (--primary, --accent, --text, --muted, --bg, --surface, --border, --font-display, --font-body, --font-mono).

4. **Data Flow**: Components receive their data via a `data-ifx-config` attribute containing JSON, or via a shared `IFX.data` object.

5. **Size Adaptation**: Components must be responsive to their container. A Dashboard KPI injected into a slide has different dimensions than one injected into a scroll section.

---

## 3. Theme System

### 3.1 Theme Variables

Every assembly defines a theme object that flows to all engines:

```json
{
  "theme": {
    "mode": "dark",
    "colors": {
      "primary": "#0a0a0a",
      "surface": "#141414",
      "border": "#262626",
      "text": "#fafafa",
      "muted": "#a1a1aa",
      "accent": "#3dffa2",
      "accent2": "#00d4ff",
      "green": "#22c55e",
      "red": "#ef4444",
      "yellow": "#f59e0b"
    },
    "fonts": {
      "display": "Fraunces",
      "body": "DM Sans",
      "mono": "JetBrains Mono"
    },
    "radius": "10px",
    "spacing_unit": "8px"
  }
}
```

### 3.2 Pre-Built Themes

| Theme Name | Mode | Accent | Display Font | Vibe |
|------------|------|--------|-------------|------|
| Midnight Mint | dark | #3dffa2 | Fraunces | Premium tech, IterFact default |
| Obsidian Cyan | dark | #22d3ee | Playfair Display | Financial, corporate |
| Warm Ivory | light | #b45309 | Crimson Pro | Editorial, nonprofit, luxury |
| Clean Slate | light | #6366f1 | Plus Jakarta Sans | SaaS, modern professional |
| Brutalist | light | #000000 | Bebas Neue | Bold, agency, creative |
| Deep Violet | dark | #a78bfa | Cormorant Garamond | Artistic, premium, emotional |
| Forest | dark | #22c55e | Libre Baskerville | Nature, sustainability, health |
| Sunset | light | #f59e0b | Sora | Energy, startups, warm |

---

## 4. Assembly Plan Schema

The AI Planner outputs a JSON assembly plan that the Assembler consumes.

### 4.1 Full Schema

```json
{
  "meta": {
    "title": "Document title",
    "description": "Brief description of what this document does",
    "author": "Company or person name",
    "recipient": "Who this is for (optional)",
    "created": "ISO date"
  },
  
  "theme": "midnight-mint | obsidian-cyan | warm-ivory | clean-slate | custom",
  "custom_theme": { },
  
  "wrapper": {
    "engine": "02",
    "config": {
      "navigation": "side | top | bottom | hidden",
      "transition": "slide | fade | none",
      "progress_bar": true
    }
  },
  
  "sections": [
    {
      "id": "intro",
      "title": "Section display name",
      "slot_id": "slide-1",
      "components": [
        {
          "engine": "03",
          "instance_id": "hero-kpis",
          "role": "KPI summary cards",
          "config": {
            "layout": "grid-4",
            "animate": true
          },
          "data": {
            "metrics": [
              { "label": "Revenue", "value": "$18.7M", "change": "+34%", "direction": "up" }
            ]
          }
        }
      ],
      "content": {
        "headline": "Text here",
        "body": "Paragraph text here"
      }
    }
  ],
  
  "footer": {
    "left": "Confidential",
    "right": "Built on IterFact",
    "show_branding": true
  }
}
```

### 4.2 Component Data Schemas (per engine)

**Engine 03 - Dashboard KPI**
```json
{
  "metrics": [{ "label": "str", "value": "str", "change": "str", "direction": "up|down" }],
  "sparklines": [{ "metric_index": 0, "data": [1,2,3] }],
  "charts": [{ "type": "bar|line|doughnut|radar", "title": "str", "labels": [], "datasets": [] }]
}
```

**Engine 05 - Timeline**
```json
{
  "events": [{ "date": "str", "title": "str", "description": "str", "icon": "emoji", "side": "left|right" }]
}
```

**Engine 06 - Flowchart**
```json
{
  "nodes": [{ "id": "str", "label": "str", "type": "start|process|decision|end", "x": 0, "y": 0 }],
  "connections": [{ "from": "id", "to": "id", "label": "str" }]
}
```

**Engine 07 - Comparison**
```json
{
  "products": [{ "name": "str", "price": "str", "recommended": false }],
  "features": [{ "name": "str", "values": ["str|true|false"] }]
}
```

**Engine 08 - Calculator**
```json
{
  "inputs": [{ "id": "str", "label": "str", "min": 0, "max": 100, "default": 50, "step": 1, "prefix": "$", "unit": "" }],
  "formula": "javascript expression string using input ids as variables",
  "outputs": [{ "label": "str", "format": "currency|percent|number" }]
}
```

**Engine 09 - Quiz**
```json
{
  "questions": [{ "question": "str", "options": ["str"], "correct": 0, "explanation": "str" }],
  "results": { "80": "msg", "60": "msg", "0": "msg" }
}
```

**Engine 17 - Scenario Modeler**
```json
{
  "variables": [{ "id": "str", "label": "str", "min": 0, "max": 100, "default": 50, "step": 1, "prefix": "", "unit": "" }],
  "scenarios": [{ "name": "str", "values": {} }],
  "model_function": "javascript function body string",
  "chart_type": "line|bar"
}
```

**Engine 26 - Data Table**
```json
{
  "columns": [{ "key": "str", "label": "str", "type": "text|number|currency|tag", "sortable": true }],
  "data": [{}]
}
```

**Engine 29 - Waterfall Chart**
```json
{
  "items": [{ "label": "str", "value": 0, "type": "start|add|subtract|total" }]
}
```

---

## 5. Recipe Library — Pre-Mapped Assemblies

These are the template recipes the onboarding UI references. Each maps a template name to a specific engine combination.

### 5.1 Professional — Interactive Reports

**Quarterly Earnings Review**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Headline & Summary", "components": [], "content_type": "hero" },
    { "title": "Key Metrics", "components": ["03"], "notes": "4-column KPI grid with sparklines" },
    { "title": "Revenue Trend", "components": ["03"], "notes": "Bar chart, quarterly revenue" },
    { "title": "Segment Breakdown", "components": ["03", "07"], "notes": "Segment cards + optional comparison" },
    { "title": "Forward Outlook", "components": ["17"], "notes": "Bull/bear scenario modeler" }
  ],
  "theme": "midnight-mint"
}
```

**Confidential Information Memo (CIM)**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Executive Summary", "components": [], "content_type": "hero" },
    { "title": "Company Overview", "components": ["05"], "notes": "Company history timeline" },
    { "title": "Financial Performance", "components": ["03", "29"], "notes": "KPI dashboard + revenue waterfall" },
    { "title": "Market Position", "components": ["07", "26"], "notes": "Competitive comparison + market data table" },
    { "title": "Growth Strategy", "components": ["17"], "notes": "Scenario modeler with growth assumptions" },
    { "title": "Management Team", "components": ["19"], "notes": "Org chart with bios" },
    { "title": "Transaction Overview", "components": ["05", "08"], "notes": "Process timeline + valuation calculator" },
    { "title": "Appendix", "components": ["26"], "notes": "Transaction comps data table" }
  ],
  "theme": "obsidian-cyan"
}
```

**Board Update / Investor Report**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Quarter at a Glance", "components": ["03"], "notes": "6-8 KPI cards with sparklines" },
    { "title": "Revenue Bridge", "components": ["29"], "notes": "Waterfall: last Q → this Q" },
    { "title": "Strategic Initiatives", "components": ["28", "10"], "notes": "Checklist progress + kanban status" },
    { "title": "Financial Model", "components": ["17"], "notes": "Scenario modeler with guidance range" },
    { "title": "Key Risks", "components": ["07"], "notes": "Risk matrix — likelihood vs impact" },
    { "title": "The Ask", "components": ["16"], "notes": "Board action items / vote form" }
  ],
  "theme": "obsidian-cyan"
}
```

**Market Analysis Brief**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Market Overview", "components": ["03"], "notes": "Market size, growth rate, key stats" },
    { "title": "Competitive Landscape", "components": ["07", "26"], "notes": "Feature comparison + competitor data table" },
    { "title": "Positioning", "components": ["15"], "notes": "Mind map of market segments" },
    { "title": "Opportunity Analysis", "components": ["08"], "notes": "TAM/SAM/SOM calculator" }
  ],
  "theme": "clean-slate"
}
```

**Investment Memo**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Thesis", "components": [], "content_type": "hero" },
    { "title": "Market Opportunity", "components": ["03", "12"], "notes": "Stats + infographic" },
    { "title": "Financial Summary", "components": ["03", "29"], "notes": "KPIs + revenue bridge" },
    { "title": "Return Scenarios", "components": ["17"], "notes": "Bull/base/bear modeler" },
    { "title": "Risk Factors", "components": ["07"], "notes": "Risk/mitigation matrix" },
    { "title": "Recommendation", "components": ["16"], "notes": "Vote / decision form" }
  ],
  "theme": "obsidian-cyan"
}
```

**Due Diligence Summary**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Executive Summary", "components": ["03"], "notes": "Overall risk score + key findings" },
    { "title": "Findings Matrix", "components": ["26"], "notes": "Sortable table of all findings" },
    { "title": "Risk Heatmap", "components": ["07"], "notes": "Category × severity matrix" },
    { "title": "Key Issues", "components": ["22"], "notes": "Accordion with detailed findings" },
    { "title": "Recommendation", "components": [], "content_type": "narrative" }
  ],
  "theme": "obsidian-cyan"
}
```

### 5.2 Professional — Pitch Decks

**Fundraising Pitch Deck**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Cover", "components": [], "content_type": "hero" },
    { "title": "Problem", "components": [], "content_type": "narrative" },
    { "title": "Solution", "components": ["23"], "notes": "Product screenshot gallery" },
    { "title": "Market Size", "components": ["08"], "notes": "TAM/SAM/SOM calculator" },
    { "title": "Traction", "components": ["03", "05"], "notes": "Metric cards + milestone timeline" },
    { "title": "Business Model", "components": ["11"], "notes": "Pricing tiers" },
    { "title": "Competition", "components": ["07"], "notes": "Feature comparison matrix" },
    { "title": "Team", "components": ["19"], "notes": "Org chart with bios" },
    { "title": "Financials", "components": ["17"], "notes": "Revenue projection modeler" },
    { "title": "The Ask", "components": ["03"], "notes": "Use of funds breakdown" }
  ],
  "theme": "midnight-mint"
}
```

**Channel Partnership Pitch**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "The Opportunity", "components": [], "content_type": "hero" },
    { "title": "Market Research", "components": ["03"], "notes": "Partner-specific data" },
    { "title": "Partnership Structure", "components": ["07"], "notes": "Tier comparison" },
    { "title": "Terms", "components": ["07", "28"], "notes": "Detailed terms + acceptance checklist" },
    { "title": "Revenue Model", "components": ["17", "03"], "notes": "Scenario modeler + projections" },
    { "title": "Next Steps", "components": ["16", "25"], "notes": "Interest form + LOI signature" }
  ],
  "theme": "midnight-mint"
}
```

**Sales Proposal**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Cover", "components": [], "content_type": "hero" },
    { "title": "Understanding Your Needs", "components": [], "content_type": "narrative" },
    { "title": "Our Solution", "components": ["07"], "notes": "Solution vs current state comparison" },
    { "title": "ROI Analysis", "components": ["08"], "notes": "ROI calculator with client inputs" },
    { "title": "Pricing", "components": ["11"], "notes": "Package tiers with toggle" },
    { "title": "Social Proof", "components": ["27"], "notes": "Testimonial carousel" },
    { "title": "Timeline", "components": ["05"], "notes": "Implementation timeline" },
    { "title": "Accept Proposal", "components": ["25"], "notes": "E-sign acceptance" }
  ],
  "theme": "clean-slate"
}
```

### 5.3 Professional — Client Proposals & Reports

**Consulting Engagement Proposal**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Situation Analysis", "components": ["06"], "notes": "Current process flowchart" },
    { "title": "Recommended Approach", "components": ["05"], "notes": "Project phase timeline" },
    { "title": "Scope & Deliverables", "components": ["28"], "notes": "Deliverable checklist" },
    { "title": "Team", "components": ["19"], "notes": "Engagement team" },
    { "title": "Investment", "components": ["11", "08"], "notes": "Pricing tiers + ROI calculator" },
    { "title": "Agreement", "components": ["25"], "notes": "SOW signature" }
  ],
  "theme": "clean-slate"
}
```

**Monthly Client Report**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Month in Review", "components": ["03"], "notes": "Hero KPIs" },
    { "title": "Performance Metrics", "components": ["03", "29"], "notes": "Dashboard + variance waterfall" },
    { "title": "Activities Completed", "components": ["28"], "notes": "Completed checklist" },
    { "title": "Next Month Plan", "components": ["10", "05"], "notes": "Kanban + timeline" },
    { "title": "Recommendations", "components": ["22"], "notes": "FAQ-style recommendations" }
  ],
  "theme": "obsidian-cyan"
}
```

### 5.4 Professional — Real Estate

**Listing Presentation (CMA)**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Your Property", "components": ["23"], "notes": "Photo gallery" },
    { "title": "Market Analysis", "components": ["03", "26"], "notes": "Market stats + comp data table" },
    { "title": "Comparable Properties", "components": ["07"], "notes": "Side-by-side comparison" },
    { "title": "Pricing Strategy", "components": ["17"], "notes": "Price scenario modeler" },
    { "title": "Marketing Plan", "components": ["05"], "notes": "Marketing timeline" },
    { "title": "Why Me", "components": ["27", "03"], "notes": "Testimonials + agent stats" },
    { "title": "Let's Get Started", "components": ["16"], "notes": "Listing agreement form" }
  ],
  "theme": "warm-ivory"
}
```

**Property Showcase**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Hero", "components": ["23"], "notes": "Full-bleed photo gallery" },
    { "title": "Property Details", "components": ["03"], "notes": "Bed/bath/sqft/price KPI cards" },
    { "title": "Features", "components": ["22"], "notes": "Feature accordion by category" },
    { "title": "Location", "components": ["20"], "notes": "Map with nearby amenities" },
    { "title": "Mortgage Calculator", "components": ["08"], "notes": "Monthly payment calculator" },
    { "title": "Schedule Showing", "components": ["16"], "notes": "Contact form" }
  ],
  "theme": "warm-ivory"
}
```

### 5.5 Professional — Legal

**Contract Package**
```json
{
  "wrapper": "25",
  "sections": [
    { "title": "Agreement Overview", "components": [], "content_type": "narrative" },
    { "title": "Terms & Conditions", "components": ["22"], "notes": "Expandable clause sections" },
    { "title": "Compensation", "components": ["07", "08"], "notes": "Tier comparison + calculator" },
    { "title": "Timeline", "components": ["05"], "notes": "Key dates and milestones" },
    { "title": "Acknowledgments & Signature", "components": [], "notes": "Built into e-sign wrapper" }
  ],
  "theme": "clean-slate"
}
```

### 5.6 Creative

**Portfolio / Case Study**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Hero", "components": ["01"], "notes": "Particle ambient background" },
    { "title": "The Work", "components": ["23"], "notes": "Project gallery with lightbox" },
    { "title": "Process", "components": ["05"], "notes": "Project timeline" },
    { "title": "Results", "components": ["03", "14"], "notes": "Metric cards + before/after" },
    { "title": "Testimonials", "components": ["27"], "notes": "Client quotes" },
    { "title": "Contact", "components": ["16"], "notes": "Inquiry form" }
  ],
  "theme": "deep-violet"
}
```

**Interactive Resume**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Introduction", "components": [], "content_type": "hero" },
    { "title": "Career Timeline", "components": ["05"], "notes": "Job history" },
    { "title": "Skills", "components": ["03"], "notes": "Skill ratings as progress bars" },
    { "title": "Projects", "components": ["23"], "notes": "Project gallery" },
    { "title": "Education", "components": ["05"], "notes": "Education timeline" },
    { "title": "Contact", "components": ["16"], "notes": "Contact form" }
  ],
  "theme": "midnight-mint"
}
```

### 5.7 Events

**Conference / Gala**
```json
{
  "wrapper": "24",
  "sections": [
    { "title": "Event Hero + Countdown", "components": [], "notes": "Built into event wrapper" },
    { "title": "Speakers", "components": ["19"], "notes": "Speaker cards with bios" },
    { "title": "Schedule", "components": [], "notes": "Built into event wrapper" },
    { "title": "Venue", "components": ["20", "23"], "notes": "Map + venue photos" },
    { "title": "Sponsors", "components": ["23"], "notes": "Sponsor logo gallery" },
    { "title": "RSVP", "components": [], "notes": "Built into event wrapper" }
  ],
  "theme": "deep-violet"
}
```

**Wedding Invitation**
```json
{
  "wrapper": "01",
  "sections": [
    { "title": "Announcement", "components": [], "content_type": "hero-text-reveal" },
    { "title": "Our Story", "components": ["05"], "notes": "Relationship timeline" },
    { "title": "Details", "components": ["24"], "notes": "Date/time/venue with countdown" },
    { "title": "Venue", "components": ["20"], "notes": "Map with directions" },
    { "title": "RSVP", "components": ["16"], "notes": "Attendance + meal selection form" }
  ],
  "theme": "deep-violet"
}
```

### 5.8 Education

**Interactive Course Module**
```json
{
  "wrapper": "02",
  "sections": [
    { "title": "Lesson Introduction", "components": [], "content_type": "narrative" },
    { "title": "Core Concepts", "components": ["22"], "notes": "Expandable concept sections" },
    { "title": "Interactive Exercise", "components": ["09"], "notes": "Knowledge check quiz" },
    { "title": "Reference Material", "components": ["13"], "notes": "Key terms flashcards" },
    { "title": "Practice", "components": ["30"], "notes": "Code playground (if technical)" },
    { "title": "Assessment", "components": ["09", "16"], "notes": "Final quiz + feedback form" }
  ],
  "theme": "clean-slate"
}
```

### 5.9 Nonprofit

**Annual Impact Report**
```json
{
  "wrapper": "18",
  "sections": [
    { "title": "Year in Review", "components": [], "content_type": "hero" },
    { "title": "Impact by the Numbers", "components": ["03", "12"], "notes": "Animated KPI cards + infographic stats" },
    { "title": "Our Programs", "components": ["22"], "notes": "Program descriptions accordion" },
    { "title": "Stories of Impact", "components": ["23", "27"], "notes": "Photo gallery + beneficiary testimonials" },
    { "title": "Timeline", "components": ["05"], "notes": "Year milestones" },
    { "title": "Financials", "components": ["29", "03"], "notes": "Revenue waterfall + expense dashboard" },
    { "title": "Thank You", "components": ["19"], "notes": "Board + staff directory" },
    { "title": "Support Our Mission", "components": ["11", "16"], "notes": "Giving tiers + donation form" }
  ],
  "theme": "warm-ivory"
}
```

### 5.10 Product

**SaaS Product Demo**
```json
{
  "wrapper": "21",
  "sections": [
    { "title": "Welcome", "components": [], "notes": "Tour intro step" },
    { "title": "Dashboard Overview", "components": ["03"], "notes": "Simulated product dashboard" },
    { "title": "Key Feature 1", "components": [], "notes": "Tour step with highlight" },
    { "title": "Key Feature 2", "components": [], "notes": "Tour step with highlight" },
    { "title": "Key Feature 3", "components": [], "notes": "Tour step with highlight" },
    { "title": "Pricing", "components": ["11"], "notes": "Plan comparison" },
    { "title": "Get Started", "components": ["16"], "notes": "Signup form" }
  ],
  "theme": "clean-slate"
}
```

**Product Landing Page**
```json
{
  "wrapper": "12",
  "sections": [
    { "title": "Hero", "components": ["03"], "notes": "Key metric stats" },
    { "title": "Problem/Solution", "components": ["14"], "notes": "Before/after slider" },
    { "title": "Features", "components": ["07"], "notes": "Feature comparison vs competitors" },
    { "title": "Social Proof", "components": ["27"], "notes": "Testimonial carousel" },
    { "title": "Pricing", "components": ["11"], "notes": "Tier comparison with toggle" },
    { "title": "FAQ", "components": ["22"], "notes": "Common questions" },
    { "title": "CTA", "components": ["16"], "notes": "Signup/demo request form" }
  ],
  "theme": "clean-slate"
}
```

---

## 6. Assembly Process

### 6.1 Step-by-Step

```
1. INPUT: User description + optional files + optional template selection
                  ↓
2. AI PLANNER: Reads manifest + user input → outputs Assembly Plan JSON
                  ↓
3. ASSEMBLER (deterministic code):
   a. Pull wrapper template from vault
   b. For each section in plan:
      - Create section/slide/chapter in wrapper
      - For each component in section:
        - Pull component template from vault
        - Namespace CSS classes: .ifx-{engine}-{instance}
        - Namespace JS variables: IFX.e{engine}_{instance}
        - Inject component data from plan
        - Insert into section slot
   c. Apply theme: replace CSS variables throughout
   d. Inject fonts: update Google Fonts import
   e. Merge all CSS into single <style> block
   f. Merge all JS into single <script> block
   g. Inject content text from plan
   h. Add footer/branding
                  ↓
4. OUTPUT: Single self-contained HTML file
                  ↓
5. AI CONTENT PASS (optional):
   - Fill [PLACEHOLDER] content sections with AI-generated copy
   - Polish/adapt tone to match user's brand voice
                  ↓
6. DELIVERY: Preview → Edit → Download → Share
```

### 6.2 Conflict Resolution

When multiple components use the same library (e.g., Chart.js):
- Include the CDN script ONCE in the document head
- Each component initializes its own chart instances under namespaced variables

When multiple components use similar CSS (e.g., card styles):
- Each component's CSS is prefixed with its namespace class
- No global styles from components — all scoped

When JavaScript event listeners could conflict:
- Each component attaches listeners to its own container element, not document
- Shared utilities (resize handler, scroll observer) are in a global IFX namespace

---

## 7. File Size Budget

Target: assembled documents should be 50-150KB for typical assemblies.

| Component | Typical Size |
|-----------|-------------|
| Wrapper HTML/CSS structure | 3-5 KB |
| Per component (CSS + JS + HTML) | 2-4 KB |
| Theme CSS variables | 0.5 KB |
| Content text (5-8 sections) | 3-8 KB |
| Chart.js CDN (if charts used) | External — 0 KB in file |
| Three.js CDN (if 3D used) | External — 0 KB in file |
| Google Fonts | External — 0 KB in file |
| **Typical 6-section assembly** | **20-40 KB** |
| **Complex 10-section assembly** | **40-80 KB** |

---

## Appendix: Engine Quick Reference

| ID | Name | Primary Data Input | Key Output |
|----|------|--------------------|-----------|
| 01 | Particle Ambient | sequences[] of text | Mouse-reactive particles + text reveal |
| 02 | Slide Deck | slides[] | Keyboard-navigable presentation |
| 03 | Dashboard KPI | metrics[], charts[] | Animated metric cards + Chart.js |
| 04 | 3D Scene | objects[] | Three.js orbit scene |
| 05 | Timeline | events[] | Scroll-animated vertical timeline |
| 06 | Flowchart | nodes[], connections[] | SVG diagram with pan/zoom |
| 07 | Comparison | products[], features[] | Feature comparison table |
| 08 | Calculator | inputs[], formula | Live-updating computation |
| 09 | Quiz | questions[] | Scored assessment |
| 10 | Kanban | columns[], cards[] | Drag-drop task board |
| 11 | Pricing | plans[] | Toggle pricing page |
| 12 | Infographic | sections[] with stats | Scroll-animated data story |
| 13 | Flashcard | cards[] | Flip-card study system |
| 14 | Before/After | two states | Drag slider comparison |
| 15 | Mind Map | nodes[] with parent refs | Draggable radial diagram |
| 16 | Form/Survey | steps[] with fields[] | Multi-step form |
| 17 | Scenario Modeler | variables[], model_fn | Slider-driven projections |
| 18 | Parallax Story | chapters[] | Full-viewport scroll narrative |
| 19 | Org Chart | people[] | Filterable team directory |
| 20 | Interactive Map | locations[] | Pin map with detail sidebar |
| 21 | Guided Tour | steps[] with highlights | Step-by-step walkthrough |
| 22 | Accordion FAQ | categories[] with items[] | Searchable Q&A |
| 23 | Image Gallery | images[] | Filterable grid + lightbox |
| 24 | Event Countdown | event config + schedule[] | Timer + RSVP |
| 25 | E-Sign Contract | sections[] + checkboxes[] | Terms + signature capture |
| 26 | Data Table | columns[] + data[] | Sortable/searchable table |
| 27 | Testimonials | testimonials[] + metrics[] | Auto-rotating carousel |
| 28 | Checklist | sections[] with items[] | Progress tracker |
| 29 | Waterfall Chart | items[] (start/add/sub/total) | Animated bridge chart |
| 30 | Code Playground | examples[] | Live editor + preview |
