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 ve