chore(abacus-react): release v2.8.0 [skip ci]

# [2.8.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.7.1...abacus-react-v2.8.0) (2025-11-04)

### Bug Fixes

* **docker:** add scripts, abacus-react, and tsx for production calendar generation ([33eb90e](33eb90e316))
* **web:** generate styled-system artifacts during build ([293390a](293390ae35))
* **web:** move react-dom/server import to API route to satisfy Next.js ([00a8bc3](00a8bc3e5e))
* **web:** prevent abacus overlap in composite calendar ([448f93c](448f93c1e2)), closes [#f0f0f0](https://github.com/antialias/soroban-abacus-flashcards/issues/f0f0f0)
* **web:** use dynamic import for react-dom/server in API route ([4f93c7d](4f93c7d996))
* **web:** use nested SVG elements to prevent coordinate space conflicts ([f9cbee8](f9cbee8fcd))

### Features

* **abacus-react:** add shared dimension calculator for consistent sizing ([e5ba772](e5ba772fde))
* **web:** add Typst-based preview endpoint with React Suspense ([599a758](599a758471))
* **web:** add year abacus to calendar header and make grid bolder ([867c7ee](867c7ee172)), closes [#333](https://github.com/antialias/soroban-abacus-flashcards/issues/333)
* **web:** optimize monthly calendar for single-page layout ([b277a89](b277a89415))
* **web:** redesign monthly calendar as single composite SVG ([8ce8038](8ce8038bae))

Dockerfile

@@ -146,6 +146,9 @@ COPY --from=builder --chown=nextjs:nodejs /app/apps/web/dist ./apps/web/dist
 # Copy database migrations
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/drizzle ./apps/web/drizzle
 
+# Copy scripts directory (needed for calendar generation)
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/scripts ./apps/web/scripts
+
 # Copy PRODUCTION node_modules only (no dev dependencies)
 COPY --from=deps --chown=nextjs:nodejs /app/node_modules ./node_modules
 COPY --from=deps --chown=nextjs:nodejs /app/apps/web/node_modules ./apps/web/node_modules
@@ -156,6 +159,9 @@ COPY --from=builder --chown=nextjs:nodejs /app/packages/core ./packages/core
 # Copy templates package (needed for Typst templates)
 COPY --from=builder --chown=nextjs:nodejs /app/packages/templates ./packages/templates
 
+# Copy abacus-react package (needed for calendar generation scripts)
+COPY --from=builder --chown=nextjs:nodejs /app/packages/abacus-react ./packages/abacus-react
+
 # Install Python dependencies for flashcard generation
 RUN pip3 install --no-cache-dir --break-system-packages -r packages/core/requirements.txt
 

apps/web/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "dev": "tsc -p tsconfig.server.json && tsc-alias -p tsconfig.server.json && concurrently \"node server.js\" \"npx @pandacss/dev --watch\"",
-    "build": "node scripts/generate-build-info.js && tsc -p tsconfig.server.json && tsc-alias -p tsconfig.server.json && next build",
+    "build": "node scripts/generate-build-info.js && npx @pandacss/dev && tsc -p tsconfig.server.json && tsc-alias -p tsconfig.server.json && next build",
     "start": "NODE_ENV=production node server.js",
     "lint": "npx @biomejs/biome lint . && npx eslint .",
     "lint:fix": "npx @biomejs/biome lint . --write && npx eslint . --fix",

apps/web/scripts/generateCalendarAbacus.tsx

@@ -5,31 +5,36 @@
  * Usage: npx tsx scripts/generateCalendarAbacus.tsx <value> <columns>
  * Example: npx tsx scripts/generateCalendarAbacus.tsx 15 2
  *
- * Pattern copied directly from working generateDayIcon.tsx
+ * Uses AbacusStatic for server-side rendering (no client hooks)
  */
 
 import React from 'react'
-import { renderToStaticMarkup } from 'react-dom/server'
-import { AbacusReact } from '@soroban/abacus-react'
+import { AbacusStatic } from '@soroban/abacus-react/static'
 
-const value = parseInt(process.argv[2], 10)
-const columns = parseInt(process.argv[3], 10)
-
-if (isNaN(value) || isNaN(columns)) {
-  console.error('Usage: npx tsx scripts/generateCalendarAbacus.tsx <value> <columns>')
-  process.exit(1)
+export function generateAbacusElement(value: number, columns: number) {
+  return (
+    <AbacusStatic
+      value={value}
+      columns={columns}
+      scaleFactor={1}
+      showNumbers={false}
+      frameVisible={true}
+    />
+  )
 }
 
-// Use exact same pattern as generateDayIcon - inline customStyles
-const abacusMarkup = renderToStaticMarkup(
-  <AbacusReact
-    value={value}
-    columns={columns}
-    scaleFactor={1}
-    animated={false}
-    interactive={false}
-    showNumbers={false}
-  />
-)
+// CLI interface (if run directly)
+if (require.main === module) {
+  // Only import react-dom/server for CLI usage
+  const { renderToStaticMarkup } = require('react-dom/server')
 
-process.stdout.write(abacusMarkup)
+  const value = parseInt(process.argv[2], 10)
+  const columns = parseInt(process.argv[3], 10)
+
+  if (isNaN(value) || isNaN(columns)) {
+    console.error('Usage: npx tsx scripts/generateCalendarAbacus.tsx <value> <columns>')
+    process.exit(1)
+  }
+
+  process.stdout.write(renderToStaticMarkup(generateAbacusElement(value, columns)))
+}

apps/web/scripts/generateCalendarComposite.tsx

@@ -0,0 +1,208 @@
+#!/usr/bin/env tsx
+
+/**
+ * Generate a complete monthly calendar as a single SVG
+ * This prevents multi-page overflow - one image scales to fit
+ *
+ * Usage: npx tsx scripts/generateCalendarComposite.tsx <month> <year>
+ * Example: npx tsx scripts/generateCalendarComposite.tsx 12 2025
+ */
+
+import React from 'react'
+import { AbacusStatic, calculateAbacusDimensions } from '@soroban/abacus-react/static'
+
+interface CalendarCompositeOptions {
+  month: number
+  year: number
+  renderToString: (element: React.ReactElement) => string
+}
+
+const MONTH_NAMES = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+]
+
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+
+function getDaysInMonth(year: number, month: number): number {
+  return new Date(year, month, 0).getDate()
+}
+
+function getFirstDayOfWeek(year: number, month: number): number {
+  return new Date(year, month - 1, 1).getDay()
+}
+
+export function generateCalendarComposite(options: CalendarCompositeOptions): string {
+  const { month, year, renderToString } = options
+  const daysInMonth = getDaysInMonth(year, month)
+  const firstDayOfWeek = getFirstDayOfWeek(year, month)
+  const monthName = MONTH_NAMES[month - 1]
+
+// Layout constants for US Letter aspect ratio (8.5 x 11)
+const WIDTH = 850
+const HEIGHT = 1100
+const MARGIN = 50
+const CONTENT_WIDTH = WIDTH - MARGIN * 2
+const CONTENT_HEIGHT = HEIGHT - MARGIN * 2
+
+// Abacus natural size is 120x230 at scale=1
+const ABACUS_NATURAL_WIDTH = 120
+const ABACUS_NATURAL_HEIGHT = 230
+
+// Calculate how many columns needed for year
+const yearColumns = Math.max(1, Math.ceil(Math.log10(year + 1)))
+
+// Year abacus dimensions (calculate first to determine header height)
+// Use the shared dimension calculator so we stay in sync with AbacusStatic
+const { width: yearAbacusActualWidth, height: yearAbacusActualHeight } = calculateAbacusDimensions({
+  columns: yearColumns,
+  showNumbers: false,
+  columnLabels: [],
+})
+
+const yearAbacusDisplayWidth = WIDTH * 0.15 // Display size on page
+const yearAbacusDisplayHeight = (yearAbacusActualHeight / yearAbacusActualWidth) * yearAbacusDisplayWidth
+
+// Header - sized to fit month name + year abacus
+const MONTH_NAME_HEIGHT = 40
+const HEADER_HEIGHT = MONTH_NAME_HEIGHT + yearAbacusDisplayHeight + 20 // 20px spacing
+const TITLE_Y = MARGIN + 35
+const yearAbacusX = (WIDTH - yearAbacusDisplayWidth) / 2
+const yearAbacusY = TITLE_Y + 10
+
+// Calendar grid
+const GRID_START_Y = MARGIN + HEADER_HEIGHT
+const GRID_HEIGHT = CONTENT_HEIGHT - HEADER_HEIGHT
+const WEEKDAY_ROW_HEIGHT = 25
+const DAY_GRID_HEIGHT = GRID_HEIGHT - WEEKDAY_ROW_HEIGHT
+
+// 7 columns, up to 6 rows (35 cells max = 5 empty + 30 days worst case)
+const CELL_WIDTH = CONTENT_WIDTH / 7
+const DAY_CELL_HEIGHT = DAY_GRID_HEIGHT / 6
+
+// Day abacus sizing - fit in cell with padding
+const CELL_PADDING = 5
+
+// Calculate max scale to fit in cell
+const MAX_SCALE_X = (CELL_WIDTH - CELL_PADDING * 2) / ABACUS_NATURAL_WIDTH
+const MAX_SCALE_Y = (DAY_CELL_HEIGHT - CELL_PADDING * 2) / ABACUS_NATURAL_HEIGHT
+const ABACUS_SCALE = Math.min(MAX_SCALE_X, MAX_SCALE_Y) * 0.9 // 90% to leave breathing room
+
+const SCALED_ABACUS_WIDTH = ABACUS_NATURAL_WIDTH * ABACUS_SCALE
+const SCALED_ABACUS_HEIGHT = ABACUS_NATURAL_HEIGHT * ABACUS_SCALE
+
+// Generate calendar grid
+const calendarCells: (number | null)[] = []
+for (let i = 0; i < firstDayOfWeek; i++) {
+  calendarCells.push(null)
+}
+for (let day = 1; day <= daysInMonth; day++) {
+  calendarCells.push(day)
+}
+
+// Render individual abacus SVGs as complete SVG elements
+function renderAbacusSVG(value: number, columns: number, scale: number): string {
+  return renderToString(
+    <AbacusStatic
+      value={value}
+      columns={columns}
+      scaleFactor={scale}
+      showNumbers={false}
+      frameVisible={true}
+      compact={false}
+    />
+  )
+}
+
+// Main composite SVG
+const compositeSVG = `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}">
+  <!-- Background -->
+  <rect width="${WIDTH}" height="${HEIGHT}" fill="white"/>
+
+  <!-- Title: Month Name -->
+  <text x="${WIDTH / 2}" y="${TITLE_Y}" text-anchor="middle" font-family="Arial" font-size="32" font-weight="bold" fill="#1a1a1a">
+    ${monthName}
+  </text>
+
+  <!-- Year Abacus (centered below month name) -->
+  ${(() => {
+    const yearAbacusSVG = renderAbacusSVG(year, yearColumns, 1)
+    const yearAbacusContent = yearAbacusSVG.replace(/<svg[^>]*>/, '').replace(/<\/svg>$/, '')
+    return `<svg x="${yearAbacusX}" y="${yearAbacusY}" width="${yearAbacusDisplayWidth}" height="${yearAbacusDisplayHeight}"
+         viewBox="0 0 ${yearAbacusActualWidth} ${yearAbacusActualHeight}">
+    ${yearAbacusContent}
+  </svg>`
+  })()}
+
+  <!-- Weekday Headers -->
+  ${WEEKDAYS.map((day, i) => `
+  <text x="${MARGIN + i * CELL_WIDTH + CELL_WIDTH / 2}" y="${GRID_START_Y + 18}"
+        text-anchor="middle" font-family="Arial" font-size="14" font-weight="bold" fill="#555">
+    ${day}
+  </text>`).join('')}
+
+  <!-- Separator line under weekdays -->
+  <line x1="${MARGIN}" y1="${GRID_START_Y + WEEKDAY_ROW_HEIGHT}"
+        x2="${WIDTH - MARGIN}" y2="${GRID_START_Y + WEEKDAY_ROW_HEIGHT}"
+        stroke="#333" stroke-width="2"/>
+
+  <!-- Calendar Grid Cells -->
+  ${calendarCells.map((day, index) => {
+    const row = Math.floor(index / 7)
+    const col = index % 7
+    const cellX = MARGIN + col * CELL_WIDTH
+    const cellY = GRID_START_Y + WEEKDAY_ROW_HEIGHT + row * DAY_CELL_HEIGHT
+
+    return `
+  <rect x="${cellX}" y="${cellY}" width="${CELL_WIDTH}" height="${DAY_CELL_HEIGHT}"
+        fill="none" stroke="#333" stroke-width="2"/>`
+  }).join('')}
+
+  <!-- Calendar Day Abaci -->
+  ${calendarCells.map((day, index) => {
+    if (day === null) return ''
+
+    const row = Math.floor(index / 7)
+    const col = index % 7
+    const cellX = MARGIN + col * CELL_WIDTH
+    const cellY = GRID_START_Y + WEEKDAY_ROW_HEIGHT + row * DAY_CELL_HEIGHT
+
+    // Center abacus in cell
+    const abacusCenterX = cellX + CELL_WIDTH / 2
+    const abacusCenterY = cellY + DAY_CELL_HEIGHT / 2
+
+    // Offset to top-left corner of abacus (accounting for scaled size)
+    const abacusX = abacusCenterX - SCALED_ABACUS_WIDTH / 2
+    const abacusY = abacusCenterY - SCALED_ABACUS_HEIGHT / 2
+
+    // Render at scale=1 and let the nested SVG handle scaling via viewBox
+    const abacusSVG = renderAbacusSVG(day, 2, 1)
+    const svgContent = abacusSVG.replace(/<svg[^>]*>/, '').replace(/<\/svg>$/, '')
+
+    return `
+  <!-- Day ${day} (row ${row}, col ${col}) -->
+  <svg x="${abacusX}" y="${abacusY}" width="${SCALED_ABACUS_WIDTH}" height="${SCALED_ABACUS_HEIGHT}"
+       viewBox="0 0 ${ABACUS_NATURAL_WIDTH} ${ABACUS_NATURAL_HEIGHT}">
+    ${svgContent}
+  </svg>`
+  }).join('')}
+</svg>`
+
+  return compositeSVG
+}
+
+// CLI interface (if run directly)
+if (require.main === module) {
+  // Only import react-dom/server for CLI usage
+  const { renderToStaticMarkup } = require('react-dom/server')
+
+  const month = parseInt(process.argv[2], 10)
+  const year = parseInt(process.argv[3], 10)
+
+  if (isNaN(month) || isNaN(year) || month < 1 || month > 12) {
+    console.error('Usage: npx tsx scripts/generateCalendarComposite.tsx <month> <year>')
+    process.exit(1)
+  }
+
+  process.stdout.write(generateCalendarComposite({ month, year, renderToString: renderToStaticMarkup }))
+}

apps/web/src/app/api/create/calendar/generate/route.ts

@@ -1,10 +1,12 @@
 import { type NextRequest, NextResponse } from 'next/server'
-import { writeFileSync, readFileSync, mkdirSync, rmSync } from 'fs'
+import { writeFileSync, mkdirSync, rmSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { execSync } from 'child_process'
 import { generateMonthlyTypst, generateDailyTypst, getDaysInMonth } from '../utils/typstGenerator'
 import type { AbacusConfig } from '@soroban/abacus-react'
+import { generateCalendarComposite } from '@/../../scripts/generateCalendarComposite'
+import { generateAbacusElement } from '@/../../scripts/generateCalendarAbacus'
 
 interface CalendarRequest {
   month: number
@@ -18,6 +20,9 @@ export async function POST(request: NextRequest) {
   let tempDir: string | null = null
 
   try {
+    // Dynamic import to avoid Next.js bundler issues with react-dom/server
+    const { renderToStaticMarkup } = await import('react-dom/server')
+
     const body: CalendarRequest = await request.json()
     const { month, year, format, paperSize, abacusConfig } = body
 
@@ -26,59 +31,67 @@ export async function POST(request: NextRequest) {
       return NextResponse.json({ error: 'Invalid month or year' }, { status: 400 })
     }
 
-    // Create temp directory
+    // Create temp directory for SVG files
     tempDir = join(tmpdir(), `calendar-${Date.now()}-${Math.random()}`)
     mkdirSync(tempDir, { recursive: true })
 
-    // Generate SVGs using script (avoids Next.js react-dom/server restriction)
+    // Generate and write SVG files
     const daysInMonth = getDaysInMonth(year, month)
-    const maxDay = format === 'daily' ? daysInMonth : 31 // For monthly, pre-generate all
-    const scriptPath = join(process.cwd(), 'scripts', 'generateCalendarAbacus.tsx')
+    let typstContent: string
 
-    // Generate day SVGs (1 to maxDay)
-    for (let day = 1; day <= maxDay; day++) {
-      const svg = execSync(`npx tsx "${scriptPath}" ${day} 2`, {
-        encoding: 'utf-8',
-        cwd: process.cwd(),
+    if (format === 'monthly') {
+      // Generate single composite SVG for monthly calendar
+      const calendarSvg = generateCalendarComposite({
+        month,
+        year,
+        renderToString: renderToStaticMarkup
+      })
+      if (!calendarSvg || calendarSvg.trim().length === 0) {
+        throw new Error('Generated empty composite calendar SVG')
+      }
+      writeFileSync(join(tempDir, 'calendar.svg'), calendarSvg)
+
+      // Generate Typst document
+      typstContent = generateMonthlyTypst({
+        month,
+        year,
+        paperSize,
+        daysInMonth,
+      })
+    } else {
+      // Daily format: generate individual SVGs for each day
+      for (let day = 1; day <= daysInMonth; day++) {
+        const svg = renderToStaticMarkup(generateAbacusElement(day, 2))
+        if (!svg || svg.trim().length === 0) {
+          throw new Error(`Generated empty SVG for day ${day}`)
+        }
+        writeFileSync(join(tempDir, `day-${day}.svg`), svg)
+      }
+
+      // Generate year SVG
+      const yearColumns = Math.max(1, Math.ceil(Math.log10(year + 1)))
+      const yearSvg = renderToStaticMarkup(generateAbacusElement(year, yearColumns))
+      if (!yearSvg || yearSvg.trim().length === 0) {
+        throw new Error(`Generated empty SVG for year ${year}`)
+      }
+      writeFileSync(join(tempDir, 'year.svg'), yearSvg)
+
+      // Generate Typst document
+      typstContent = generateDailyTypst({
+        month,
+        year,
+        paperSize,
+        daysInMonth,
       })
-      writeFileSync(join(tempDir, `day-${day}.svg`), svg)
     }
 
-    // Generate year SVG
-    const yearColumns = Math.max(1, Math.ceil(Math.log10(year + 1)))
-    const yearSvg = execSync(`npx tsx "${scriptPath}" ${year} ${yearColumns}`, {
-      encoding: 'utf-8',
-      cwd: process.cwd(),
-    })
-    writeFileSync(join(tempDir, 'year.svg'), yearSvg)
-
-    // Generate Typst document
-    const typstContent =
-      format === 'monthly'
-        ? generateMonthlyTypst({
-            month,
-            year,
-            paperSize,
-            tempDir,
-            daysInMonth,
-          })
-        : generateDailyTypst({
-            month,
-            year,
-            paperSize,
-            tempDir,
-            daysInMonth,
-          })
-
-    const typstPath = join(tempDir, 'calendar.typ')
-    writeFileSync(typstPath, typstContent)
-
-    // Compile with Typst (run from tempDir so relative paths work)
-    const pdfPath = join(tempDir, 'calendar.pdf')
+    // Compile with Typst: stdin for .typ content, stdout for PDF output
+    let pdfBuffer: Buffer
     try {
-      execSync(`typst compile "calendar.typ" "calendar.pdf"`, {
-        cwd: tempDir,
-        stdio: 'pipe',
+      pdfBuffer = execSync('typst compile - -', {
+        input: typstContent,
+        cwd: tempDir, // Run in temp dir so relative paths work
+        maxBuffer: 50 * 1024 * 1024, // 50MB limit for large calendars
       })
     } catch (error) {
       console.error('Typst compilation error:', error)
@@ -88,18 +101,14 @@ export async function POST(request: NextRequest) {
       )
     }
 
-    // Read and return PDF
-    const pdfBuffer = readFileSync(pdfPath)
-
     // Clean up temp directory
     rmSync(tempDir, { recursive: true, force: true })
     tempDir = null
 
-    return new NextResponse(pdfBuffer, {
-      headers: {
-        'Content-Type': 'application/pdf',
-        'Content-Disposition': `attachment; filename="calendar-${year}-${String(month).padStart(2, '0')}.pdf"`,
-      },
+    // Return JSON with PDF
+    return NextResponse.json({
+      pdf: pdfBuffer.toString('base64'),
+      filename: `calendar-${year}-${String(month).padStart(2, '0')}.pdf`,
     })
   } catch (error) {
     console.error('Error generating calendar:', error)
@@ -113,6 +122,17 @@ export async function POST(request: NextRequest) {
       }
     }
 
-    return NextResponse.json({ error: 'Failed to generate calendar' }, { status: 500 })
+    // Surface the actual error for debugging
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    const errorStack = error instanceof Error ? error.stack : undefined
+
+    return NextResponse.json(
+      {
+        error: 'Failed to generate calendar',
+        message: errorMessage,
+        ...(process.env.NODE_ENV === 'development' && { stack: errorStack })
+      },
+      { status: 500 }
+    )
   }
 }

apps/web/src/app/api/create/calendar/preview/route.ts

@@ -0,0 +1,97 @@
+import { type NextRequest, NextResponse } from 'next/server'
+import { writeFileSync, mkdirSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { execSync } from 'child_process'
+import { generateMonthlyTypst, getDaysInMonth } from '../utils/typstGenerator'
+import { generateCalendarComposite } from '@/../../scripts/generateCalendarComposite'
+
+interface PreviewRequest {
+  month: number
+  year: number
+  format: 'monthly' | 'daily'
+}
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(request: NextRequest) {
+  let tempDir: string | null = null
+
+  try {
+    const body: PreviewRequest = await request.json()
+    const { month, year, format } = body
+
+    // Validate inputs
+    if (!month || month < 1 || month > 12 || !year || year < 1 || year > 9999) {
+      return NextResponse.json({ error: 'Invalid month or year' }, { status: 400 })
+    }
+
+    // Only generate preview for monthly format
+    if (format !== 'monthly') {
+      return NextResponse.json({ svg: null })
+    }
+
+    // Dynamic import to avoid Next.js bundler issues
+    const { renderToStaticMarkup } = await import('react-dom/server')
+
+    // Create temp directory for SVG file
+    tempDir = join(tmpdir(), `calendar-preview-${Date.now()}-${Math.random()}`)
+    mkdirSync(tempDir, { recursive: true })
+
+    // Generate and write composite SVG
+    const calendarSvg = generateCalendarComposite({
+      month,
+      year,
+      renderToString: renderToStaticMarkup
+    })
+    writeFileSync(join(tempDir, 'calendar.svg'), calendarSvg)
+
+    // Generate Typst document content
+    const daysInMonth = getDaysInMonth(year, month)
+    const typstContent = generateMonthlyTypst({
+      month,
+      year,
+      paperSize: 'us-letter',
+      daysInMonth,
+    })
+
+    // Compile with Typst: stdin for .typ content, stdout for SVG output
+    let svg: string
+    try {
+      svg = execSync('typst compile --format svg - -', {
+        input: typstContent,
+        encoding: 'utf8',
+        cwd: tempDir, // Run in temp dir so relative paths work
+      })
+    } catch (error) {
+      console.error('Typst compilation error:', error)
+      return NextResponse.json(
+        { error: 'Failed to compile preview. Is Typst installed?' },
+        { status: 500 }
+      )
+    }
+
+    // Clean up temp directory
+    rmSync(tempDir, { recursive: true, force: true })
+    tempDir = null
+
+    return NextResponse.json({ svg })
+  } catch (error) {
+    console.error('Error generating preview:', error)
+
+    // Clean up temp directory if it exists
+    if (tempDir) {
+      try {
+        rmSync(tempDir, { recursive: true, force: true })
+      } catch (cleanupError) {
+        console.error('Failed to clean up temp directory:', cleanupError)
+      }
+    }
+
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    return NextResponse.json(
+      { error: 'Failed to generate preview', message: errorMessage },
+      { status: 500 }
+    )
+  }
+}

apps/web/src/app/api/create/calendar/utils/typstGenerator.ts

@@ -1,8 +1,14 @@
-interface TypstConfig {
+interface TypstMonthlyConfig {
+  month: number
+  year: number
+  paperSize: 'us-letter' | 'a4' | 'a3' | 'tabloid'
+  daysInMonth: number
+}
+
+interface TypstDailyConfig {
   month: number
   year: number
   paperSize: 'us-letter' | 'a4' | 'a3' | 'tabloid'
-  tempDir: string
   daysInMonth: number
 }
 
@@ -44,73 +50,38 @@ interface PaperConfig {
 
 function getPaperConfig(size: string): PaperConfig {
   const configs: Record<PaperSize, PaperConfig> = {
-    'us-letter': { typstName: 'us-letter', marginX: '0.75in', marginY: '1in' },
-    a4: { typstName: 'a4', marginX: '2cm', marginY: '2.5cm' },
-    a3: { typstName: 'a3', marginX: '2cm', marginY: '2.5cm' },
-    tabloid: { typstName: 'us-tabloid', marginX: '1in', marginY: '1in' },
+    // Tight margins to maximize space for calendar grid
+    'us-letter': { typstName: 'us-letter', marginX: '0.5in', marginY: '0.5in' },
+    // A4 is slightly taller/narrower than US Letter - adjust margins proportionally
+    a4: { typstName: 'a4', marginX: '1.3cm', marginY: '1.3cm' },
+    // A3 is 2x area of A4 - can use same margins but will scale content larger
+    a3: { typstName: 'a3', marginX: '1.5cm', marginY: '1.5cm' },
+    // Tabloid (11" × 17") is larger - can use more margin
+    tabloid: { typstName: 'us-tabloid', marginX: '0.75in', marginY: '0.75in' },
   }
   return configs[size as PaperSize] || configs['us-letter']
 }
 
-export function generateMonthlyTypst(config: TypstConfig): string {
-  const { month, year, paperSize, tempDir, daysInMonth } = config
+export function generateMonthlyTypst(config: TypstMonthlyConfig): string {
+  const { paperSize } = config
   const paperConfig = getPaperConfig(paperSize)
-  const firstDayOfWeek = getFirstDayOfWeek(year, month)
-  const monthName = MONTH_NAMES[month - 1]
-
-  // Generate calendar cells with proper empty cells before the first day
-  let cells = ''
-
-  // Empty cells before first day
-  for (let i = 0; i < firstDayOfWeek; i++) {
-    cells += '  [],\n'
-  }
-
-  // Day cells
-  for (let day = 1; day <= daysInMonth; day++) {
-    cells += `  [#image("day-${day}.svg", width: 90%)],\n`
-  }
 
+  // Single-page design: use one composite SVG that scales to fit
+  // This prevents overflow - Typst will scale the image to fit available space
   return `#set page(
   paper: "${paperConfig.typstName}",
   margin: (x: ${paperConfig.marginX}, y: ${paperConfig.marginY}),
 )
 
-#set text(font: "Arial", size: 12pt)
-
-// Title
-#align(center)[
-  #text(size: 24pt, weight: "bold")[${monthName} ${year}]
-
-  #v(0.5em)
-
-  // Year as abacus
-  #image("year.svg", width: 35%)
+// Composite calendar SVG - scales to fit page (prevents multi-page overflow)
+#align(center + horizon)[
+  #image("calendar.svg", width: 100%, fit: "contain")
 ]
-
-#v(1.5em)
-
-// Calendar grid
-#grid(
-  columns: (1fr, 1fr, 1fr, 1fr, 1fr, 1fr, 1fr),
-  gutter: 4pt,
-
-  // Weekday headers
-  [#align(center)[*Sun*]],
-  [#align(center)[*Mon*]],
-  [#align(center)[*Tue*]],
-  [#align(center)[*Wed*]],
-  [#align(center)[*Thu*]],
-  [#align(center)[*Fri*]],
-  [#align(center)[*Sat*]],
-
-  // Calendar days
-${cells})
 `
 }
 
-export function generateDailyTypst(config: TypstConfig): string {
-  const { month, year, paperSize, tempDir, daysInMonth } = config
+export function generateDailyTypst(config: TypstDailyConfig): string {
+  const { month, year, paperSize, daysInMonth } = config
   const paperConfig = getPaperConfig(paperSize)
   const monthName = MONTH_NAMES[month - 1]
 

apps/web/src/app/create/calendar/components/CalendarPreview.tsx

@@ -1,45 +1,41 @@
 'use client'
 
+import { useSuspenseQuery } from '@tanstack/react-query'
 import { css } from '../../../../../styled-system/css'
-import { AbacusReact, useAbacusConfig } from '@soroban/abacus-react'
 
 interface CalendarPreviewProps {
   month: number
   year: number
   format: 'monthly' | 'daily'
+  previewSvg: string | null
 }
 
-const MONTHS = [
-  'January',
-  'February',
-  'March',
-  'April',
-  'May',
-  'June',
-  'July',
-  'August',
-  'September',
-  'October',
-  'November',
-  'December',
-]
+async function fetchTypstPreview(month: number, year: number, format: string): Promise<string | null> {
+  const response = await fetch('/api/create/calendar/preview', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ month, year, format }),
+  })
 
-const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+  if (!response.ok) {
+    throw new Error('Failed to fetch preview')
+  }
 
-function getDaysInMonth(year: number, month: number): number {
-  return new Date(year, month, 0).getDate()
+  const data = await response.json()
+  return data.svg
 }
 
-function getFirstDayOfWeek(year: number, month: number): number {
-  return new Date(year, month - 1, 1).getDay()
-}
+export function CalendarPreview({ month, year, format, previewSvg }: CalendarPreviewProps) {
+  // Use React Query with Suspense to fetch Typst-generated preview
+  const { data: typstPreviewSvg } = useSuspenseQuery({
+    queryKey: ['calendar-typst-preview', month, year, format],
+    queryFn: () => fetchTypstPreview(month, year, format),
+  })
 
-export function CalendarPreview({ month, year, format }: CalendarPreviewProps) {
-  const abacusConfig = useAbacusConfig()
-  const daysInMonth = getDaysInMonth(year, month)
-  const firstDayOfWeek = getFirstDayOfWeek(year, month)
+  // Use generated PDF SVG if available, otherwise use Typst live preview
+  const displaySvg = previewSvg || typstPreviewSvg
 
-  if (format === 'daily') {
+  if (!displaySvg) {
     return (
       <div
         data-component="calendar-preview"
@@ -57,112 +53,16 @@ export function CalendarPreview({ month, year, format }: CalendarPreviewProps) {
         <p
           className={css({
             fontSize: '1.25rem',
-            color: 'gray.300',
-            marginBottom: '1.5rem',
-            textAlign: 'center',
-          })}
-        >
-          Daily format preview
-        </p>
-        <div
-          className={css({
-            bg: 'white',
-            padding: '3rem 2rem',
-            borderRadius: '8px',
-            boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
-            maxWidth: '400px',
-            width: '100%',
-          })}
-        >
-          {/* Year at top */}
-          <div
-            className={css({
-              display: 'flex',
-              justifyContent: 'center',
-              marginBottom: '2rem',
-            })}
-          >
-            <AbacusReact
-              value={year}
-              columns={4}
-              customStyles={abacusConfig.customStyles}
-              scaleFactor={0.4}
-              showNumbers={false}
-            />
-          </div>
-
-          {/* Large day number */}
-          <div
-            className={css({
-              display: 'flex',
-              justifyContent: 'center',
-              marginBottom: '2rem',
-            })}
-          >
-            <AbacusReact
-              value={1}
-              columns={2}
-              customStyles={abacusConfig.customStyles}
-              scaleFactor={0.8}
-              showNumbers={false}
-            />
-          </div>
-
-          {/* Date text */}
-          <div
-            className={css({
-              textAlign: 'center',
-              color: 'gray.800',
-            })}
-          >
-            <div
-              className={css({
-                fontSize: '1.25rem',
-                fontWeight: '600',
-                marginBottom: '0.25rem',
-              })}
-            >
-              {new Date(year, month - 1, 1).toLocaleDateString('en-US', {
-                weekday: 'long',
-              })}
-            </div>
-            <div
-              className={css({
-                fontSize: '1rem',
-                color: 'gray.600',
-              })}
-            >
-              {MONTHS[month - 1]} 1, {year}
-            </div>
-          </div>
-        </div>
-        <p
-          className={css({
-            fontSize: '0.875rem',
             color: 'gray.400',
-            marginTop: '1rem',
             textAlign: 'center',
           })}
         >
-          Example of first day (1 page per day for all {daysInMonth} days)
+          {format === 'daily' ? 'Daily format - preview after generation' : 'No preview available'}
         </p>
       </div>
     )
   }
 
-  // Monthly format
-  const calendarDays: (number | null)[] = []
-
-  // Add empty cells for days before the first day of month
-  for (let i = 0; i < firstDayOfWeek; i++) {
-    calendarDays.push(null)
-  }
-
-  // Add actual days
-  for (let day = 1; day <= daysInMonth; day++) {
-    calendarDays.push(day)
-  }
-
   return (
     <div
       data-component="calendar-preview"
@@ -170,101 +70,32 @@ export function CalendarPreview({ month, year, format }: CalendarPreviewProps) {
         bg: 'gray.800',
         borderRadius: '12px',
         padding: '2rem',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
       })}
     >
-      <div
-        className={css({
-          textAlign: 'center',
-          marginBottom: '2rem',
-        })}
-      >
-        <h2
-          className={css({
-            fontSize: '2rem',
-            fontWeight: 'bold',
-            marginBottom: '1rem',
-            color: 'yellow.400',
-          })}
-        >
-          {MONTHS[month - 1]}
-        </h2>
-        <div
-          className={css({
-            display: 'flex',
-            justifyContent: 'center',
-          })}
-        >
-          <AbacusReact
-            value={year}
-            columns={4}
-            customStyles={abacusConfig.customStyles}
-            scaleFactor={0.6}
-            showNumbers={false}
-          />
-        </div>
-      </div>
-
-      {/* Calendar Grid */}
-      <div
-        className={css({
-          display: 'grid',
-          gridTemplateColumns: 'repeat(7, 1fr)',
-          gap: '0.5rem',
-        })}
-      >
-        {/* Weekday headers */}
-        {WEEKDAYS.map((day) => (
-          <div
-            key={day}
-            className={css({
-              textAlign: 'center',
-              fontWeight: '600',
-              padding: '0.5rem',
-              color: 'yellow.400',
-              fontSize: '0.875rem',
-            })}
-          >
-            {day}
-          </div>
-        ))}
-
-        {/* Calendar days */}
-        {calendarDays.map((day, index) => (
-          <div
-            key={index}
-            className={css({
-              aspectRatio: '1',
-              display: 'flex',
-              alignItems: 'center',
-              justifyContent: 'center',
-              bg: day ? 'gray.700' : 'transparent',
-              borderRadius: '6px',
-              padding: '0.25rem',
-            })}
-          >
-            {day && (
-              <AbacusReact
-                value={day}
-                columns={2}
-                customStyles={abacusConfig.customStyles}
-                scaleFactor={1.0}
-                showNumbers={false}
-              />
-            )}
-          </div>
-        ))}
-      </div>
-
       <p
         className={css({
-          fontSize: '0.875rem',
-          color: 'gray.400',
-          marginTop: '1.5rem',
+          fontSize: '1.125rem',
+          color: 'yellow.400',
+          marginBottom: '1rem',
           textAlign: 'center',
+          fontWeight: 'bold',
         })}
       >
-        Preview of monthly calendar layout (actual PDF will be optimized for printing)
+        {previewSvg ? 'Generated PDF' : 'Live Preview'}
       </p>
+      <div
+        className={css({
+          bg: 'white',
+          borderRadius: '8px',
+          padding: '1rem',
+          maxWidth: '100%',
+          overflow: 'auto',
+        })}
+        dangerouslySetInnerHTML={{ __html: displaySvg }}
+      />
     </div>
   )
 }

apps/web/src/app/create/calendar/page.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState } from 'react'
+import { useState, Suspense } from 'react'
 import { css } from '../../../../styled-system/css'
 import { useAbacusConfig } from '@soroban/abacus-react'
 import { PageWithNav } from '@/components/PageWithNav'
@@ -15,6 +15,7 @@ export default function CalendarCreatorPage() {
   const [format, setFormat] = useState<'monthly' | 'daily'>('monthly')
   const [paperSize, setPaperSize] = useState<'us-letter' | 'a4' | 'a3' | 'tabloid'>('us-letter')
   const [isGenerating, setIsGenerating] = useState(false)
+  const [previewSvg, setPreviewSvg] = useState<string | null>(null)
 
   const handleGenerate = async () => {
     setIsGenerating(true)
@@ -34,21 +35,26 @@ export default function CalendarCreatorPage() {
       })
 
       if (!response.ok) {
-        throw new Error('Failed to generate calendar')
+        const errorData = await response.json().catch(() => ({}))
+        throw new Error(errorData.message || 'Failed to generate calendar')
       }
 
-      const blob = await response.blob()
+      const data = await response.json()
+
+      // Convert base64 PDF to blob and trigger download
+      const pdfBytes = Uint8Array.from(atob(data.pdf), c => c.charCodeAt(0))
+      const blob = new Blob([pdfBytes], { type: 'application/pdf' })
       const url = window.URL.createObjectURL(blob)
       const a = document.createElement('a')
       a.href = url
-      a.download = `calendar-${year}-${String(month).padStart(2, '0')}.pdf`
+      a.download = data.filename
       document.body.appendChild(a)
       a.click()
       window.URL.revokeObjectURL(url)
       document.body.removeChild(a)
     } catch (error) {
       console.error('Error generating calendar:', error)
-      alert('Failed to generate calendar. Please try again.')
+      alert(`Failed to generate calendar: ${error instanceof Error ? error.message : 'Unknown error'}`)
     } finally {
       setIsGenerating(false)
     }
@@ -122,7 +128,35 @@ export default function CalendarCreatorPage() {
             />
 
             {/* Preview */}
-            <CalendarPreview month={month} year={year} format={format} />
+            <Suspense
+              fallback={
+                <div
+                  data-component="calendar-preview"
+                  className={css({
+                    bg: 'gray.800',
+                    borderRadius: '12px',
+                    padding: '2rem',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    minHeight: '600px',
+                  })}
+                >
+                  <p
+                    className={css({
+                      fontSize: '1.25rem',
+                      color: 'gray.400',
+                      textAlign: 'center',
+                    })}
+                  >
+                    Loading preview...
+                  </p>
+                </div>
+              }
+            >
+              <CalendarPreview month={month} year={year} format={format} previewSvg={previewSvg} />
+            </Suspense>
           </div>
         </div>
       </div>

packages/abacus-react/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [2.8.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.7.1...abacus-react-v2.8.0) (2025-11-04)
+
+
+### Bug Fixes
+
+* **docker:** add scripts, abacus-react, and tsx for production calendar generation ([33eb90e](https://github.com/antialias/soroban-abacus-flashcards/commit/33eb90e316f84650ae619f8c6c02c9e77c663d1b))
+* **web:** generate styled-system artifacts during build ([293390a](https://github.com/antialias/soroban-abacus-flashcards/commit/293390ae350a6c6aa467410f68c735512104d9dd))
+* **web:** move react-dom/server import to API route to satisfy Next.js ([00a8bc3](https://github.com/antialias/soroban-abacus-flashcards/commit/00a8bc3e5e8f044df280c4356d3605a852f82e84))
+* **web:** prevent abacus overlap in composite calendar ([448f93c](https://github.com/antialias/soroban-abacus-flashcards/commit/448f93c1e2a7f86bc48e678d4599ca968c6d81d2)), closes [#f0f0f0](https://github.com/antialias/soroban-abacus-flashcards/issues/f0f0f0)
+* **web:** use dynamic import for react-dom/server in API route ([4f93c7d](https://github.com/antialias/soroban-abacus-flashcards/commit/4f93c7d996732de4bc19e7acf2d4ce803cba88b6))
+* **web:** use nested SVG elements to prevent coordinate space conflicts ([f9cbee8](https://github.com/antialias/soroban-abacus-flashcards/commit/f9cbee8fcdf80641f3b82a65fad6b8a3575525fc))
+
+
+### Features
+
+* **abacus-react:** add shared dimension calculator for consistent sizing ([e5ba772](https://github.com/antialias/soroban-abacus-flashcards/commit/e5ba772fde9839c22daec92007f052ca125c7695))
+* **web:** add Typst-based preview endpoint with React Suspense ([599a758](https://github.com/antialias/soroban-abacus-flashcards/commit/599a758471c43ab0fc87301c5e7eeceed608062e))
+* **web:** add year abacus to calendar header and make grid bolder ([867c7ee](https://github.com/antialias/soroban-abacus-flashcards/commit/867c7ee17251b8df13665bee9c0391961975e681)), closes [#333](https://github.com/antialias/soroban-abacus-flashcards/issues/333)
+* **web:** optimize monthly calendar for single-page layout ([b277a89](https://github.com/antialias/soroban-abacus-flashcards/commit/b277a89415d1823455376c3e0f641b52f3394e7c))
+* **web:** redesign monthly calendar as single composite SVG ([8ce8038](https://github.com/antialias/soroban-abacus-flashcards/commit/8ce8038baeea0b8b0fffe3215746958731bd9d6a))
+
+## [2.7.1](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.7.0...abacus-react-v2.7.1) (2025-11-04)
+
+
+### Bug Fixes
+
+* add xmlns to AbacusStatic for Typst SVG parsing ([98cd019](https://github.com/antialias/soroban-abacus-flashcards/commit/98cd019d4af91d7ca4e7a88f700194273476afb7))
+* **web:** use AbacusStatic for calendar SVG generation ([08c6a41](https://github.com/antialias/soroban-abacus-flashcards/commit/08c6a419e25d220560eba13d6db437145e6e61b8))
+
 # [2.7.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.6.0...abacus-react-v2.7.0) (2025-11-04)
 
 

packages/abacus-react/src/AbacusStatic.tsx

@@ -6,7 +6,7 @@
  * Different: No hooks, no animations, no interactions, simplified rendering
  */
 
-import { numberToAbacusState } from './AbacusUtils'
+import { numberToAbacusState, calculateAbacusDimensions } from './AbacusUtils'
 import { AbacusStaticBead } from './AbacusStaticBead'
 import type {
   AbacusCustomStyles,
@@ -175,7 +175,14 @@ export function AbacusStatic({
     beadConfigs.push(beads)
   }
 
-  // Calculate dimensions (matching AbacusReact)
+  // Calculate dimensions using shared utility
+  const { width, height } = calculateAbacusDimensions({
+    columns: effectiveColumns,
+    showNumbers: !!showNumbers,
+    columnLabels,
+  })
+
+  // Layout constants (must match calculateAbacusDimensions)
   const beadSize = 20
   const rodSpacing = 40
   const heavenHeight = 60
@@ -185,9 +192,6 @@ export function AbacusStatic({
   const numberHeightCalc = showNumbers ? 30 : 0
   const labelHeight = columnLabels.length > 0 ? 30 : 0
 
-  const width = effectiveColumns * rodSpacing + padding * 2
-  const height = heavenHeight + earthHeight + barHeight + padding * 2 + numberHeightCalc + labelHeight
-
   const dimensions = {
     width,
     height,
@@ -205,6 +209,7 @@ export function AbacusStatic({
 
   return (
     <svg
+      xmlns="http://www.w3.org/2000/svg"
       width={width * scaleFactor}
       height={height * scaleFactor}
       viewBox={`0 0 ${width} ${height}`}

packages/abacus-react/src/AbacusUtils.ts

@@ -356,3 +356,37 @@ function getPlaceName(place: number): string {
       return `place ${place} column`
   }
 }
+
+/**
+ * Calculate the natural dimensions of an abacus SVG
+ * This uses the same logic as AbacusStatic to ensure consistency
+ *
+ * @param columns - Number of columns in the abacus
+ * @param showNumbers - Whether numbers are shown below columns
+ * @param columnLabels - Array of column labels (if any)
+ * @returns Object with width and height in pixels (at scale=1)
+ */
+export function calculateAbacusDimensions({
+  columns,
+  showNumbers = true,
+  columnLabels = [],
+}: {
+  columns: number
+  showNumbers?: boolean
+  columnLabels?: string[]
+}): { width: number; height: number } {
+  // Constants matching AbacusStatic
+  const beadSize = 20
+  const rodSpacing = 40
+  const heavenHeight = 60
+  const earthHeight = 120
+  const barHeight = 10
+  const padding = 20
+  const numberHeightCalc = showNumbers ? 30 : 0
+  const labelHeight = columnLabels.length > 0 ? 30 : 0
+
+  const width = columns * rodSpacing + padding * 2
+  const height = heavenHeight + earthHeight + barHeight + padding * 2 + numberHeightCalc + labelHeight
+
+  return { width, height }
+}

packages/abacus-react/src/index.ts

@@ -47,6 +47,7 @@ export {
   calculateBeadDiffFromValues,
   validateAbacusValue,
   areStatesEqual,
+  calculateAbacusDimensions,
 } from "./AbacusUtils";
 export type {
   BeadState,

packages/abacus-react/src/static.ts

@@ -9,7 +9,7 @@ export { AbacusStaticBead } from './AbacusStaticBead'
 export type { StaticBeadProps } from './AbacusStaticBead'
 
 // Re-export shared utilities that are safe for server components
-export { numberToAbacusState } from './AbacusUtils'
+export { numberToAbacusState, calculateAbacusDimensions } from './AbacusUtils'
 export type {
   AbacusCustomStyles,
   BeadConfig,