ai-html-generate

What this skill does

# AI HTML Generate Skill

## Purpose

This skill leverages **AI's probabilistic generation capabilities** to recreate PDF pages as semantic HTML. The AI receives three complementary inputs that together provide complete context:

1. **Visual reference** (PNG image) - Page layout and visual hierarchy
2. **Text data** (rich_extraction.json) - Accurate text content and formatting metadata
3. **Structural preview** (ASCII text) - Logical layout and element relationships

This **three-input approach** ensures the AI understands not just what text to include, but how it should be structured semantically in HTML.

The output is **probabilistic** (AI-generated), but will be made **deterministic** by validation gates in subsequent skills.

## What to Do

1. **Prepare three input files**
   - Load `02_page_XX.png` (image file)
   - Load `01_rich_extraction.json` (text spans with metadata)
   - Load `03_page_XX_ascii.txt` (structure preview)

2. **Construct AI prompt**
   - Attach PNG image as visual reference
   - Include extracted text data (JSON)
   - Include ASCII preview (text representation)
   - Provide specific generation requirements

3. **Invoke Claude API** with complete context
   - Send multi-modal prompt (text + image)
   - Request semantic HTML5 output
   - Specify CSS classes and structure requirements

4. **Parse and save generated HTML**
   - Extract HTML from AI response
   - Validate basic well-formedness
   - Save to persistent file with metadata

5. **Log generation metadata**
   - Record AI model used
   - Timestamp generation
   - List input files used
   - Store any confidence indicators from AI

## Input Files (From Previous Skills)

### Input 1: Rendered PDF Page (PNG)
**File**: `output/chapter_XX/page_artifacts/page_YY/02_page_XX.png`
- High-resolution rendering of PDF page
- 300+ DPI for visual clarity
- Shows actual page appearance
- Used for visual layout understanding

### Input 2: Rich Extraction Data (JSON)
**File**: `output/chapter_XX/page_artifacts/page_YY/01_rich_extraction.json`
- Text spans with complete metadata
- Font names, sizes, bold/italic flags
- Position information (bounding boxes)
- Sequence and relationships

### Input 3: ASCII Preview (Text)
**File**: `output/chapter_XX/page_artifacts/page_YY/03_page_XX_ascii.txt`
- Text-based structural representation
- Heading hierarchy marked
- Lists and bullets identified
- Paragraph flow documented
- Element types annotated

## AI Prompt Template

The prompt sent to Claude:

```
You are recreating a PDF textbook page as semantic HTML5.

You have three pieces of information about this page:
1. A visual rendering (PNG image) - to understand layout
2. Parsed text data (JSON) - to ensure accuracy
3. An ASCII structure preview (text) - to understand element relationships

VISUAL REFERENCE:
[PNG Image Attached]

PARSED TEXT DATA:
[JSON Attached]

STRUCTURAL PREVIEW:
[ASCII Text Attached]

TASK:
Generate semantic HTML5 that accurately recreates this page.

REQUIREMENTS:

1. HTML5 Structure:
   - Proper DOCTYPE, html, head, body tags
   - Meta charset="UTF-8"
   - Meta viewport for responsive design
   - Title tag with descriptive text

2. Content Wrapper:
   - Single <div class="page-container"> wrapper
   - Single <main class="page-content"> for all content
   - No page breaks or paginated structure

3. Semantic HTML Elements:
   - Use proper heading tags (h1-h6) based on hierarchy
   - Use <p> for paragraphs
   - Use <ul> and <li> for bullet lists
   - Use <table> if data tables present
   - Use <figure> and <figcaption> for images/exhibits

4. Semantic CSS Classes:
   Apply these classes based on detected element types:

   Page Structure:
   - page-container (main wrapper)
   - page-content (content area)
   - chapter-header (chapter opening section)
   - chapter-number (numeric chapter marker)
   - chapter-title (chapter main title)

   Content Elements:
   - section-heading (major section, h2)
   - subsection-heading (minor section, h3-h4)
   - paragraph (body text, p)
   - bullet-list (ul)
   - bullet-item (li)

   Navigation & Structure:
   - section-navigation (list of topics/sections)
   - nav-item (individual nav item)
   - section-divider (hr divider line)

   Special Elements:
   - exhibit (table or figure)
   - exhibit-table (actual table)
   - exhibit-title (figure/table caption)
   - image-placeholder (for embedded images)

5. Content Preservation & Boundary Integrity:
   - Include ALL text content from the parsed data
   - Preserve exact text (no paraphrasing or edits)
   - Maintain original structure and relationships
   - Do not omit or skip sections

   CRITICAL - PAGE BOUNDARY RULES:
   - Start page content EXACTLY where JSON starts it
   - End page content EXACTLY where JSON ends it
   - NEVER add bridging text, connectors, or completing phrases
   - NEVER invent transitional words or sentences
   - NEVER synthesize content to "smooth" page transitions
   - Pages may start or end mid-sentence - this is EXPECTED and CORRECT
   - If a sentence seems incomplete, that is the accurate page boundary
   - Every single word in your HTML MUST exist in the source JSON

6. Heading Hierarchy:
   - Follow logical hierarchy (h1 → h2 → h3 → h4)
   - No skipped levels (don't jump from h1 to h4)
   - Chapter title is h1 (if present)
   - Main sections are h2
   - Subsections are h3 or h4 as appropriate

7. List Formatting:
   - Wrap in <ul class="bullet-list">
   - Each item in <li class="bullet-item">
   - Preserve item order and grouping
   - Include all bullet text exactly

8. CSS Stylesheet Link:
   - Include: <link rel="stylesheet" href="../../styles/main.css">
   - Use relative path (two levels up to root)
   - This stylesheet provides all styling

9. Special Handling:
   - Bold text within paragraphs: Use <strong> tags
   - Italic text: Use <em> tags
   - Embedded images: Use <img> tags with src path and alt text
   - Exhibits/tables: Preserve structure and captions

OUTPUT FORMAT:

Return ONLY valid HTML5. Do not include explanations.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    ...
</head>
<body>
    ...
</body>
</html>
```

VALIDATION:
- HTML must be valid HTML5
- All opening tags must have closing tags
- Class attributes must use correct class names
- All text content from JSON MUST be included
- NO TEXT MAY BE ADDED that doesn't exist in the source JSON extraction
- Coverage must be 99-100% (>100% indicates invented content = FAIL)
- Every single word must come from the extraction data
```

## Process Flow

```
┌─ Load Input Files ─────────────────────┐
│ • 02_page_XX.png (image)               │
│ • 01_rich_extraction.json (text data)  │
│ • 03_page_XX_ascii.txt (structure)     │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Construct Prompt ─────────────────────┐
│ • Attach PNG image                     │
│ • Include JSON data                    │
│ • Include ASCII preview                │
│ • Add generation requirements          │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Invoke Claude API ────────────────────┐
│ • Multi-modal prompt                   │
│ • Vision + Text understanding          │
│ • Deterministic system instructions    │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Extract & Save HTML ──────────────────┐
│ • Parse AI response                    │
│ • Extract HTML block                   │
│ • Basic validation (tag closure)       │
│ • Save to 04_page_XX.html              │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Log Generation Metadata ──────────────┐
│ • Model name and version               │
│ • Input file references                │
│ • Timestamp                            │
│ • Save to 05_generation_metadata.json  │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ GATE 1: Verify Text Content ──────────┐
│ MANDATORY - DO NOT SKIP                │
│                                        │
│ Run per-page text v