feat: add per-page worksheet generation API

Created generateSinglePage() function that:
- Generates all problems (using seed + random algorithm)
- Generates all Typst sources (lightweight)
- Only compiles the requested page to SVG (expensive operation)

This avoids compiling 100 pages of Typst when you only need page 1.

New API endpoint: POST /api/create/worksheets/preview/[pageNumber]
Returns: { page: string, totalPages: number }

Next: Update frontend to lazy-load pages as they become visible.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

apps/web/src/app/api/create/worksheets/preview/[pageNumber]/route.ts

@@ -0,0 +1,52 @@
+// API route for generating a single worksheet page (SVG)
+
+import { type NextRequest, NextResponse } from 'next/server'
+import { generateSinglePage } from '@/app/create/worksheets/generatePreview'
+import type { WorksheetFormState } from '@/app/create/worksheets/types'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { pageNumber: string } }
+) {
+  try {
+    const body: WorksheetFormState = await request.json()
+    const pageNumber = parseInt(params.pageNumber, 10)
+
+    if (isNaN(pageNumber) || pageNumber < 0) {
+      return NextResponse.json({ error: 'Invalid page number' }, { status: 400 })
+    }
+
+    // Generate only the requested page
+    const result = generateSinglePage(body, pageNumber)
+
+    if (!result.success) {
+      return NextResponse.json(
+        {
+          error: result.error,
+          details: result.details,
+        },
+        { status: result.error?.includes('Invalid page number') ? 404 : 400 }
+      )
+    }
+
+    // Return the page and total count
+    return NextResponse.json({
+      page: result.page,
+      totalPages: result.totalPages,
+    })
+  } catch (error) {
+    console.error('Error generating page preview:', error)
+
+    const errorMessage = error instanceof Error ? error.message : String(error)
+
+    return NextResponse.json(
+      {
+        error: 'Failed to generate page preview',
+        message: errorMessage,
+      },
+      { status: 500 }
+    )
+  }
+}

apps/web/src/app/create/worksheets/generatePreview.ts

@@ -19,6 +19,14 @@ export interface PreviewResult {
   details?: string
 }
 
+export interface SinglePageResult {
+  success: boolean
+  page?: string
+  totalPages?: number
+  error?: string
+  details?: string
+}
+
 /**
  * Generate worksheet preview SVG pages
  * Can be called from API routes or Server Components
@@ -163,3 +171,144 @@ export function generateWorksheetPreview(config: WorksheetFormState): PreviewRes
     }
   }
 }
+
+/**
+ * Generate a single worksheet page SVG
+ * Much faster than generating all pages when you only need one
+ */
+export function generateSinglePage(config: WorksheetFormState, pageNumber: number): SinglePageResult {
+  try {
+    // First, validate and get total page count
+    const validation = validateWorksheetConfig(config)
+    if (!validation.isValid || !validation.config) {
+      return {
+        success: false,
+        error: 'Invalid configuration',
+        details: validation.errors?.join(', '),
+      }
+    }
+
+    const validatedConfig = validation.config
+    const totalPages = validatedConfig.pages
+
+    // Check if requested page is valid
+    if (pageNumber < 0 || pageNumber >= totalPages) {
+      return {
+        success: false,
+        error: `Invalid page number ${pageNumber}. Total pages: ${totalPages}`,
+      }
+    }
+
+    // Generate all problems (need full set to know which problems go on which page)
+    // This is unavoidable because problems are distributed across pages
+    const operator = validatedConfig.operator ?? 'addition'
+    const mode = config.mode ?? 'smart'
+
+    let problems
+
+    // Same problem generation logic as generateWorksheetPreview
+    if (mode === 'mastery' && operator === 'mixed') {
+      const addSkillId = config.currentAdditionSkillId
+      const subSkillId = config.currentSubtractionSkillId
+
+      if (!addSkillId || !subSkillId) {
+        return {
+          success: false,
+          error: 'Mixed mastery mode requires both addition and subtraction skill IDs',
+        }
+      }
+
+      const addSkill = getSkillById(addSkillId as any)
+      const subSkill = getSkillById(subSkillId as any)
+
+      if (!addSkill || !subSkill) {
+        return {
+          success: false,
+          error: 'Invalid skill IDs',
+        }
+      }
+
+      problems = generateMasteryMixedProblems(
+        validatedConfig.total,
+        {
+          digitRange: addSkill.digitRange,
+          pAnyStart: addSkill.regroupingConfig.pAnyStart,
+          pAllStart: addSkill.regroupingConfig.pAllStart,
+        },
+        {
+          digitRange: subSkill.digitRange,
+          pAnyStart: subSkill.regroupingConfig.pAnyStart,
+          pAllStart: subSkill.regroupingConfig.pAllStart,
+        },
+        validatedConfig.seed
+      )
+    } else if (operator === 'mixed') {
+      problems = generateMixedProblems(
+        validatedConfig.total,
+        validatedConfig.digitRange,
+        validatedConfig.pAnyStart,
+        validatedConfig.pAllStart,
+        validatedConfig.seed
+      )
+    } else if (operator === 'subtraction') {
+      problems = generateSubtractionProblems(
+        validatedConfig.total,
+        validatedConfig.digitRange,
+        validatedConfig.pAnyStart,
+        validatedConfig.pAllStart,
+        validatedConfig.seed
+      )
+    } else {
+      problems = generateProblems(
+        validatedConfig.total,
+        validatedConfig.digitRange,
+        validatedConfig.pAnyStart,
+        validatedConfig.pAllStart,
+        validatedConfig.seed
+      )
+    }
+
+    // Generate Typst source for ALL pages (lightweight operation)
+    const typstSources = generateTypstSource(problems, validatedConfig)
+
+    // Only compile the requested page
+    const typstSource = typstSources[pageNumber]
+
+    try {
+      const svgOutput = execSync('typst compile --format svg - -', {
+        input: typstSource,
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+      })
+
+      return {
+        success: true,
+        page: svgOutput,
+        totalPages,
+      }
+    } catch (error) {
+      console.error(`Typst compilation error (page ${pageNumber}):`, error)
+
+      const stderr =
+        error instanceof Error && 'stderr' in error
+          ? String((error as any).stderr)
+          : 'Unknown compilation error'
+
+      return {
+        success: false,
+        error: `Failed to compile page ${pageNumber}`,
+        details: stderr,
+      }
+    }
+  } catch (error) {
+    console.error('Error generating single page:', error)
+
+    const errorMessage = error instanceof Error ? error.message : String(error)
+
+    return {
+      success: false,
+      error: 'Failed to generate page',
+      details: errorMessage,
+    }
+  }
+}