Shockproof AI HTML Deck Builder

Required Environment Variables

See SETUP.md for how to generate these values and for local development notes.

Before You Start

1. Read references/api_reference.md for the complete JSON schema reference.
2. The DeckSpecification is processed by @shockproof/deck-builder (monorepo: packages/deck-builder/).

Text wrapping is fully automatic. CSS handles all word-wrap, line-clamp, and overflow. You never need to manually break strings or calculate positions.

What You Need From the User

Confirm before generating:

• Series title (e.g., "Asset-Based Lending Mastery")
• Total modules in series (e.g., 6)
• Module number within the series
• Module title (e.g., "Interviewing CRE Borrowers")
• Topic/subject matter for the content
• Case study requirements (3 per module; varied outcomes: Approved, Approved with Conditions, Declined)
• Output filename convention: {Series}_Module_{N}_{ShortName}.pdf
• Next module info for the closing slide (or omit if last module)

DeckSpecification JSON Structure

Generate a JSON file matching this structure. The full schema is in references/api_reference.md.

Server-side equivalent: The courseMapDeckFillerChain agent job generates the same DeckSpecification JSON using the deckSpecGenerator agent instructions (agents/courseassistant/deckSpecGenerator/instructions.md) and a shared schema reference fragment (agents/courseassistant/shared/deckspec-schema-reference.md). Both paths feed into the same @shockproof/deck-builder pipeline.

{
  "config": {
    "seriesTitle": "Asset-Based Lending Mastery",
    "totalModules": 6
  },
  "slides": [
    {
      "type": "title",
      "moduleNum": 1,
      "title": "Inventory Financing Fundamentals",
      "subtitle": "Understanding Collateral Valuation",
      "totalPages": 40,
      "narration": "Welcome to Module 1 of the Asset-Based Lending Mastery series."
    },
    {
      "type": "content",
      "chrome": {
        "title": "Learning Objectives",
        "moduleNum": 1,
        "moduleTitle": "Inventory Financing Fundamentals",
        "pageNum": 2,
        "totalPages": 40
      },
      "components": [
        {
          "type": "row",
          "children": [
            { "type": "cardHtml", "accent": "#1A4FE8", "title": "Objective 1", "body": "Identify eligible inventory types" },
            { "type": "cardHtml", "accent": "#2E7D32", "title": "Objective 2", "body": "Calculate advance rates" }
          ]
        },
        {
          "type": "row",
          "children": [
            { "type": "cardHtml", "accent": "#C17D10", "title": "Objective 3", "body": "Evaluate borrowing base" },
            { "type": "cardHtml", "accent": "#B91C1C", "title": "Objective 4", "body": "Spot red flags in aging reports" }
          ]
        }
      ],
      "narration": "In this module you will learn four key objectives."
    },
    {
      "type": "section",
      "title": "Core Concepts",
      "subtitle": "Building a strong foundation",
      "moduleNum": 1,
      "moduleTitle": "Inventory Financing Fundamentals",
      "pageNum": 3,
      "totalPages": 40,
      "narration": "Now lets dive into core concepts."
    },
    {
      "type": "content",
      "chrome": { "title": "Process Overview", "moduleNum": 1, "moduleTitle": "Inventory Financing Fundamentals", "pageNum": 4, "totalPages": 40 },
      "components": [
        { "type": "stepRow", "num": 1, "title": "First Step", "description": "Description of step one." },
        { "type": "stepRow", "num": 2, "title": "Second Step", "description": "Description of step two." },
        { "type": "stepRow", "num": 3, "title": "Third Step", "description": "Description of step three." },
        { "type": "calloutBox", "title": "Key Insight", "body": "Summary of the process." }
      ],
      "narration": "This slide outlines the three-step process."
    },
    {
      "type": "keyTakeaways",
      "moduleNum": 1,
      "moduleTitle": "Inventory Financing Fundamentals",
      "pageNum": 38,
      "totalPages": 40,
      "takeaways": [
        { "title": "Takeaway 1", "desc": "Description..." },
        { "title": "Takeaway 2", "desc": "Description..." },
        { "title": "Takeaway 3", "desc": "Description..." },
        { "title": "Takeaway 4", "desc": "Description..." }
      ],
      "narration": "Lets review the four key takeaways from this module."
    },
    {
      "type": "references",
      "moduleNum": 1,
      "moduleTitle": "Inventory Financing Fundamentals",
      "pageNum": 39,
      "totalPages": 40,
      "references": [
        { "category": "Regulatory Guidance", "items": ["OCC Handbook", "FDIC Manual"] }
      ],
      "narration": "Here are the key references for further reading."
    },
    {
      "type": "closing",
      "moduleNum": 1,
      "moduleTitle": "Inventory Financing Fundamentals",
      "nextModuleNum": 2,
      "nextModuleTitle": "Accounts Receivable Analysis",
      "totalPages": 40,
      "narration": "Thank you for completing Module 1.\n\n(pause: 1)\n\nThank you."
    }
  ]
}

Content Design Principle — Always Steer Toward Titled Items

Before writing any component, ask: can each item be given a 2–5 word title/headline and a description sentence? If yes, use cardGrid (4–8 items) or a row of cardHtml (2–3 items). This is the default visual treatment for enumerable content.

• Concepts, risks, examples, warnings, case studies, best practices, red flags → cardGrid if each can be named
• Only fall back to bullets when items genuinely share no individual title (e.g. a list of sub-points elaborating a single idea)
• Only use redFlagPairs for pure short warning phrases that cannot be given distinct names

Critical Rules

1. Read references/api_reference.md for the full JSON schema. All slide types, component types, and options are documented there.

2. Content is vertically centered. Components stack at their natural height between header and footer. The flex layout vertically centers them, producing balanced whitespace above and below. Components must NOT use flex:1 in the column direction — that would stretch them to fill the area and defeat centering.

3. Page numbers must be sequential. Track pageNum for every slide. The title slide is page 1.

4. section and closing slides do not use chrome. They have their own special layouts. Only content slides have a chrome object.

5. keyTakeaways creates chrome internally. Do not wrap it in a content slide. It is its own slide type.

6. references creates its own slide. Do not wrap it in a content slide.

7. redFlagPairs goes inside a content slide. It does NOT create chrome — the parent content slide provides chrome.

8. Bold-prefix format. Use "Key Term: rest of description" — the colon triggers auto bold formatting.

9. rowH in styledTable opts is in INCHES, not pixels. It is multiplied by SCALE=128 internally. rowH is the primary lever for controlling whitespace within table rows — increase it for spacious rows, decrease for compact rows. cellPadding is secondary and only effective when rowH is large enough to accommodate it.

   • Default (no option): 0.35 in ≈ 45px — baseline for most tables
   • Spacious (≤4 data rows): 0.45–0.55 in — use when few rows leave visible empty space below
   • Compact (6–7 rows): 0.28 in ≈ 36px
   • Extra-compact (8+ rows): 0.22 in ≈ 28px
   • Never pass pixel values like "rowH": 36 — that would be 36 × 128 = 4,608px per row.
   • Rule of thumb: if a table has ≤5 data rows and no other large components on the slide, increase rowH above the default to fill available space.

10. stepRow height budget. Each step row is ~55px. Budget for the content area (~560px after chrome):

    • 5 step rows alone: ~275px OK
    • 5 step rows + calloutBox (~80px): ~373px OK
    • 6 step rows + callout: ~450px — tight, may overflow. Use styledTable instead.

11. cardHtml body accepts arrays for bullet lists. Pass an array of strings to render as bulleted list:

    { "type": "cardHtml", "accent": "#1A4FE8", "title": "Topic", "body": ["Item one", "Item two", "Item three"] }
    

12. Use hex color strings. Always use full hex like "#1A4FE8", not color names or shorthand.

Narration

Every slide should have a narration string field. Narrations are read directly from the DeckSpecification JSON by the build pipeline — no separate narration file is needed.

Key TTS Rules (mandatory)

• Dollar amounts: Remove commas ($17719 not $17,719)
• Negative amounts: negative 204000 dollars
• Acronyms: Phonetic spellings (Gap for GAAP, Fazz-bee for FASB, Cecil for CECL)
• cashflow (one word, always)
• No quotes in narration
• Pause directives on their own line: Write (pause: N) with \n\n before and after — never inline within a sentence. Example: "Final thought.\n\n(pause: 1)\n\nThank you."
• Last slide: Must include \n\n(pause: 1)\n\n before the thank-you

Pre-Finalisation Checklist

Before writing the JSON, scan every narration string for:

• Dollar amounts with commas → remove all commas
• Company/partnership names with commas or & → reformat
• Acronyms from the phonetic table → replace with phonetic spellings
• cash flow (two words) → replace with cashflow
• Single or double quotes → remove or rephrase
• (pause: N) directives inline → move to \n\n(pause: N)\n\n format
• Last slide ends with \n\n(pause: 1)\n\nThank you.

Narakeet Video

When narration is present, the build pipeline auto-generates:

• narakeet-script.md — Narakeet video script pairing PNGs with narration
• narakeet.zip — self-contained archive for Narakeet API upload

Video generation uses the Narakeet API and requires NARAKEET_API_KEY.

Submitting to Narakeet

After the deck build completes (PNGs + narakeet.zip exist in the output directory), use the shared renderer's submitToNarakeet() method to upload the zip, poll for completion, and download the MP4:

const path = require('path');
const RENDERER_ROOT = path.join(__dirname, '../../shared/html-slide-renderer');
const tpl = require(path.join(RENDERER_ROOT, 'scripts/sai_html_template.js'))({
  seriesTitle: 'Your Series Title', totalModules: 1,
});
const pres = tpl.createPresentation();
const videoPath = await pres.submitToNarakeet(outputDir, {
  videoFilename: 'My_Module.mp4',
});
console.log(`Video saved: ${videoPath}`);

How it works internally:

1. Reads NARAKEET_API_KEY from env (falls back to gcloud secrets CLI)
2. Requests an upload token from https://api.narakeet.com/video/upload-request/zip
3. Uploads narakeet.zip to the pre-signed URL
4. Requests a video build via POST /video/build
5. Polls the status URL until completion (~2–5 min for 20 slides)
6. Downloads the MP4 to outputDir/{videoFilename}

Key file: .claude/skills/shockproof-skills/shared/html-slide-renderer/scripts/presentation.js — the submitToNarakeet() method (line ~218).

Building the Deck

After generating the DeckSpecification JSON, run it through @shockproof/deck-builder:

import { buildDeck } from '@shockproof/deck-builder';
import fs from 'fs';

const spec = JSON.parse(fs.readFileSync('deck-spec.json', 'utf8'));
const result = await buildDeck(spec, {
  type: 'filesystem',
  outDir: './mnt/outputs/Module_1',
}, {
  pdfName: 'ABL_Mastery_Module_1.pdf',
});

console.log(`Built ${result.slideCount} slides`);
console.log(`PDF: ${result.pdfPath}`);

The same JSON can also be submitted as a cloud agent job (htmlDeckBuilder) for server-side execution.

Slide Component Selection Guide

Prefer cardGrid whenever items have titles

If the content has 4–8 items and each item has a natural headline or lead phrase, always use cardGrid — even if the items are warnings, risks, case studies, or red flags. The rule of thumb: if you could write a 2–5 word title for each item, it should be a card.

bullets is only correct when items have no natural title — they are sentence-length facts or sub-points that don't decompose into a headline + body.

redFlagPairs is only correct when items are pure, short, equal-weight warning phrases that can't be given distinct titles. If you can name them (e.g. "Lehman Brothers", "Washington Mutual"), they are cards, not flag pairs.

When NOT to use cardGrid

• Items are sub-bullets elaborating on a single topic (no individual titles) → bullets
• Items are definition-style "Term: Definition" without distinct conceptual identity → styledTable
• Items have a natural ordering/sequence → stepRow
• Fewer than 4 or more than 8 items

Variety Matters

Avoid repeating the same component layout on consecutive slides. Use at least 8 different component types across a module.

Automated Visual Check (visualCheck)

The build pipeline includes an automated visualCheck phase that detects content overflow and text truncation, then auto-fixes affected slides.

How It Works

1. The renderHtmlToPng cloud function evaluates overflow-detection JS on each slide after DOM layout, before taking the screenshot
2. It returns per-slide overflow metadata alongside the PNGs:
   • contentClipped: boolean — .slide-content children exceed the visible area
   • truncatedElements: string[] — specific elements with scrollHeight > clientHeight (text cut off by overflow: hidden)
   • titleTruncated: boolean — the title element's scrollHeight > clientHeight (title text cut off by -webkit-line-clamp)
3. buildDeck reads the overflow metadata and auto-applies fixes to the DeckSpecification:
   • cardGrid: adds compact: true (14pt titles, 11pt descriptions, tighter padding)
   • cardHtml (in rows): adds compact: true
   • bullets/checklist: reduces fontSize by 2pt (min 9pt)
   • stepRow: enables compact: true
   • styledTable (overflow): shrinks rowH by 0.07in (min 0.22in) first; only compacts cellPadding (8px 10px → 6px 8px → 4px 6px) when rowH is already at minimum
   • styledTable (sparse): increases rowH by 0.05in (max 0.55in) first; only expands cellPadding (8px 10px → 10px 14px → 12px 16px) when rowH is already at maximum
   • Title wrap (orphan word): if the title wraps and only 1 orphan word sits on the second line, titleFontSize is reduced to fit on one line (minimum 18pt). 2+ words on the second line is acceptable and does not trigger downsizing. The fix applies at most once per slide — if a titleFontSize override already exists, no further downsizing occurs. If a previous downsize caused title truncation (detected via titleTruncated in the overflow metadata), the override is reverted to restore the natural title size.
4. Only affected slides are re-interpreted and re-rendered (one retry max)
5. Remaining overflow warnings are reported in result.overflowWarnings

Controlling visualCheck

// Enabled by default
await buildDeck(spec, outputConfig);

// Disable if needed
await buildDeck(spec, outputConfig, { visualCheck: false });

QA After Build

1. Build completes without errors
2. Console output confirms correct slide count and visualCheck results
3. Manual visual spot-check. The automated visualCheck catches most overflow/truncation, but still read every generated PNG to verify:
   • Content must not touch or overlap the footer bar
   • No content should be cut off at the top or bottom
   • No slide should appear mostly empty when it should have content
   • If overflowWarnings are reported in the build result, those slides need manual attention
4. Spot-check PDF: title, section divider, content, case study, closing
5. Every slide in the DeckSpecification has a narration field
6. Scan narration for TTS violations