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

# [2.9.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.8.3...abacus-react-v2.9.0) (2025-11-05)

### Bug Fixes

* **docker:** upgrade OpenSCAD to 2024.11 to fix CGAL intersection bug ([e1bcd24](e1bcd24169))
* **guide:** increase abacus sizes - they were too small ([1074624](1074624b2f))
* **guide:** make abacus sizes consistent and add nav spacing ([bea4842](bea4842a29))
* **guide:** remove inner containers and tighten margins ([7e54c6f](7e54c6f4fc))
* **layout:** add systematic spacing for fixed nav bar ([4559fb1](4559fb121d))
* **layout:** remove wrapper, use utility class for nav spacing ([247c3d9](247c3d9874))
* **nav:** restrict transparent hero styling to home page only ([fab227d](fab227d686))

### Features

* **3d-abacus:** change default columns from 13 to 4 ([cd15c70](cd15c70a25))
* add client-side OpenSCAD WASM support for 3D preview ([eaaf17c](eaaf17cd4c))

Dockerfile

@@ -85,7 +85,7 @@ RUN ARCH=$(uname -m) && \
     else \
         echo "Unsupported architecture: $ARCH" && exit 1; \
     fi && \
-    TYPST_VERSION="v0.11.1" && \
+    TYPST_VERSION="v0.13.0" && \
     wget -q "https://github.com/typst/typst/releases/download/${TYPST_VERSION}/typst-${TYPST_ARCH}.tar.xz" && \
     tar -xf "typst-${TYPST_ARCH}.tar.xz" && \
     mv "typst-${TYPST_ARCH}/typst" /usr/local/bin/typst && \
@@ -107,23 +107,60 @@ RUN mkdir -p /bosl2 && \
     find . -type f ! -name "*.scad" -delete && \
     find . -type d -empty -delete
 
+# OpenSCAD builder stage - download and prepare newer OpenSCAD binary
+FROM node:18-slim AS openscad-builder
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    wget \
+    ca-certificates \
+    file \
+    && rm -rf /var/lib/apt/lists/*
+
+# Download latest OpenSCAD AppImage and extract it
+# Using 2024.11 which has CGAL fixes for intersection operations
+RUN wget -q https://files.openscad.org/OpenSCAD-2024.11.18-x86_64.AppImage -O /tmp/openscad.AppImage && \
+    chmod +x /tmp/openscad.AppImage && \
+    cd /tmp && \
+    ./openscad.AppImage --appimage-extract && \
+    mv squashfs-root/usr/bin/openscad /usr/local/bin/openscad && \
+    mv squashfs-root/usr/lib /usr/local/openscad-lib && \
+    chmod +x /usr/local/bin/openscad
+
 # Production image - Using Debian base for OpenSCAD availability
 FROM node:18-slim AS runner
 WORKDIR /app
 
 # Install ONLY runtime dependencies (no build tools)
-# Using Debian because OpenSCAD is not available in Alpine repos
 RUN apt-get update && apt-get install -y --no-install-recommends \
     python3 \
     python3-pip \
     qpdf \
-    openscad \
     ca-certificates \
+    libgomp1 \
+    libglu1-mesa \
+    libglew2.2 \
+    libfreetype6 \
+    libfontconfig1 \
+    libharfbuzz0b \
+    libxml2 \
+    libzip4 \
+    libdouble-conversion3 \
+    libqt5core5a \
+    libqt5gui5 \
+    libqt5widgets5 \
+    libqt5concurrent5 \
+    libqt5multimedia5 \
+    libqt5network5 \
+    libqt5dbus5 \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy typst binary from typst-builder stage
 COPY --from=typst-builder /usr/local/bin/typst /usr/local/bin/typst
 
+# Copy newer OpenSCAD from openscad-builder stage
+COPY --from=openscad-builder /usr/local/bin/openscad /usr/local/bin/openscad
+COPY --from=openscad-builder /usr/local/openscad-lib /usr/local/openscad-lib
+ENV LD_LIBRARY_PATH=/usr/local/openscad-lib:$LD_LIBRARY_PATH
+
 # Copy minimized BOSL2 library from bosl2-builder stage
 RUN mkdir -p /usr/share/openscad/libraries
 COPY --from=bosl2-builder /bosl2 /usr/share/openscad/libraries/BOSL2
@@ -156,6 +193,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/.claude/CLAUDE.md

@@ -1,5 +1,75 @@
 # Claude Code Instructions for apps/web
 
+## CRITICAL: Production Dependencies
+
+**NEVER add TypeScript execution tools to production dependencies.**
+
+### Forbidden Production Dependencies
+
+The following packages must ONLY be in `devDependencies`, NEVER in `dependencies`:
+
+- ❌ `tsx` - TypeScript execution (only for scripts during development)
+- ❌ `ts-node` - TypeScript execution
+- ❌ Any TypeScript compiler/executor that runs .ts/.tsx files at runtime
+
+### Why This Matters
+
+1. **Docker Image Size**: These tools add 50-100MB+ to production images
+2. **Security**: Running TypeScript at runtime is a security risk
+3. **Performance**: Production should run compiled JavaScript, not interpret TypeScript
+4. **Architecture**: If you need TypeScript at runtime, the code is in the wrong place
+
+### What To Do Instead
+
+**❌ WRONG - Adding tsx to dependencies to run .ts/.tsx at runtime:**
+```json
+{
+  "dependencies": {
+    "tsx": "^4.20.5"  // NEVER DO THIS
+  }
+}
+```
+
+**✅ CORRECT - Move code to proper location:**
+
+1. **For Next.js API routes**: Move files to `src/` so Next.js bundles them during build
+   - Example: `scripts/generateCalendar.tsx` → `src/utils/calendar/generateCalendar.tsx`
+   - Next.js will compile and bundle these during `npm run build`
+
+2. **For standalone scripts**: Keep in `scripts/` and use `tsx` from devDependencies
+   - Only run during development/build, never at runtime
+   - Scripts can use `tsx` because it's available during build
+
+3. **For server-side TypeScript**: Compile to JavaScript during build
+   - Use `tsc` to compile `src/` to `dist/`
+   - Production runs the compiled JavaScript from `dist/`
+
+### Historical Context
+
+**We've made this mistake TWICE:**
+
+1. **First time (commit ffae9c1b)**: Added tsx to dependencies for calendar generation scripts
+   - **Fix**: Moved scripts to `src/utils/calendar/` so Next.js bundles them
+
+2. **Second time (would have happened again)**: Almost added tsx again for same reason
+   - **Learning**: If you're tempted to add tsx to dependencies, the architecture is wrong
+
+### Red Flags
+
+If you find yourself thinking:
+- "I need to add tsx to dependencies to run this .ts file in production"
+- "This script needs TypeScript at runtime"
+- "Production can't import this .tsx file"
+
+**STOP.** The code is in the wrong place. Move it to `src/` for bundling.
+
+### Enforcement
+
+Before modifying `package.json` dependencies:
+1. Check if any TypeScript execution tools are being added
+2. Ask yourself: "Could this code be in `src/` instead?"
+3. If unsure, ask the user before proceeding
+
 ## MANDATORY: Quality Checks for ALL Work
 
 **BEFORE declaring ANY work complete, fixed, or working**, you MUST run and pass these checks:
@@ -56,13 +126,14 @@ When asked to make ANY changes:
 
 **CRITICAL: The user manages running the dev server, NOT Claude Code.**
 
-- ❌ DO NOT run `npm run dev` or `npm start`
+- ❌ DO NOT run `pnpm dev`, `npm run dev`, or `npm start`
 - ❌ DO NOT attempt to start, stop, or restart the dev server
+- ❌ DO NOT kill processes on port 3000
 - ❌ DO NOT use background Bash processes for the dev server
 - ✅ Make code changes and let the user restart the server when needed
 - ✅ You may run other commands like `npm run type-check`, `npm run lint`, etc.
 
-The user will manually start/restart the dev server after you make changes.
+**The user runs the dev server themselves.** The user will manually start/restart the dev server after you make changes.
 
 ## Details
 

apps/web/.claude/settings.local.json

@@ -168,7 +168,5 @@
     "ask": []
   },
   "enableAllProjectMcpServers": true,
-  "enabledMcpjsonServers": [
-    "sqlite"
-  ]
+  "enabledMcpjsonServers": ["sqlite"]
 }

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",
@@ -71,6 +71,7 @@
     "next": "^14.2.32",
     "next-auth": "5.0.0-beta.29",
     "next-intl": "^4.4.0",
+    "openscad-wasm-prebuilt": "^1.2.0",
     "python-bridge": "^1.1.0",
     "qrcode.react": "^4.2.0",
     "react": "^18.2.0",

apps/web/public/3d-models/abacus-inline.scad

@@ -0,0 +1,47 @@
+// Inline version of abacus.scad that doesn't require BOSL2
+// This version uses a hardcoded bounding box size instead of the bounding_box() function
+
+// ----  USER CUSTOMIZABLE PARAMETERS  ----
+// These can be overridden via command line: -D 'columns=7' etc.
+columns = 13;          // Total number of columns (1-13, mirrored book design)
+scale_factor = 1.5;    // Overall size scale (preserves aspect ratio)
+// -----------------------------------------
+
+stl_path = "/3d-models/simplified.abacus.stl";
+
+// Known bounding box dimensions of the simplified.abacus.stl file
+// These were measured from the original file
+bbox_size = [186, 60, 120];  // [width, depth, height] in STL units
+
+// Calculate parameters based on column count
+// The full STL has 13 columns. We want columns/2 per side (mirrored).
+total_columns_in_stl = 13;
+columns_per_side = columns / 2;
+width_scale = columns_per_side / total_columns_in_stl;
+
+// Column spacing: distance between mirrored halves
+units_per_column = bbox_size[0] / total_columns_in_stl;  // ~14.3 units per column
+column_spacing = columns_per_side * units_per_column;
+
+// --- actual model ---
+module imported() {
+    import(stl_path, convexity = 10);
+}
+
+// Create a bounding box manually instead of using BOSL2's bounding_box()
+module bounding_box_manual() {
+    translate([-bbox_size[0]/2, -bbox_size[1]/2, -bbox_size[2]/2])
+        cube(bbox_size);
+}
+
+module half_abacus() {
+    intersection() {
+        scale([width_scale, 1, 1]) bounding_box_manual();
+        imported();
+    }
+}
+
+scale([scale_factor, scale_factor, scale_factor]) {
+    translate([column_spacing, 0, 0]) mirror([1,0,0]) half_abacus();
+    half_abacus();
+}

apps/web/scripts/generateCalendarAbacus.tsx

@@ -1,35 +0,0 @@
-#!/usr/bin/env tsx
-
-/**
- * Generate a simple abacus SVG (no customization for now - just get it working)
- * Usage: npx tsx scripts/generateCalendarAbacus.tsx <value> <columns>
- * Example: npx tsx scripts/generateCalendarAbacus.tsx 15 2
- *
- * Pattern copied directly from working generateDayIcon.tsx
- */
-
-import React from 'react'
-import { renderToStaticMarkup } from 'react-dom/server'
-import { AbacusReact } from '@soroban/abacus-react'
-
-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)
-}
-
-// Use exact same pattern as generateDayIcon - inline customStyles
-const abacusMarkup = renderToStaticMarkup(
-  <AbacusReact
-    value={value}
-    columns={columns}
-    scaleFactor={1}
-    animated={false}
-    interactive={false}
-    showNumbers={false}
-  />
-)
-
-process.stdout.write(abacusMarkup)

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 '@/utils/calendar/generateCalendarComposite'
+import { generateAbacusElement } from '@/utils/calendar/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,58 +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
-    const pdfPath = join(tempDir, 'calendar.pdf')
+    // Compile with Typst: stdin for .typ content, stdout for PDF output
+    let pdfBuffer: Buffer
     try {
-      execSync(`typst compile "${typstPath}" "${pdfPath}"`, {
-        stdio: 'pipe',
+      pdfBuffer = execSync('typst compile --format pdf - -', {
+        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)
@@ -87,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)
@@ -112,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 '@/utils/calendar/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("${tempDir}/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("${tempDir}/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]
 
@@ -127,14 +98,14 @@ export function generateDailyTypst(config: TypstConfig): string {
   // Header: Year
   #align(center)[
     #v(1em)
-    #image("${tempDir}/year.svg", width: 30%)
+    #image("year.svg", width: 30%)
   ]
 
   #v(2em)
 
   // Main: Day number as large abacus
   #align(center + horizon)[
-    #image("${tempDir}/day-${day}.svg", width: 50%)
+    #image("day-${day}.svg", width: 50%)
   ]
 
   #v(2em)

apps/web/src/app/arcade/rithmomachia/page.tsx

@@ -2,6 +2,9 @@
 
 import { rithmomachiaGame } from '@/arcade-games/rithmomachia'
 
+// Force dynamic rendering to avoid build-time initialization errors
+export const dynamic = 'force-dynamic'
+
 const { Provider, GameComponent } = rithmomachiaGame
 
 export default function RithmomachiaPage() {

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

@@ -7,7 +7,7 @@ import { css } from '../../../../styled-system/css'
 
 export default function ThreeDPrintPage() {
   // New unified parameter system
-  const [columns, setColumns] = useState(13)
+  const [columns, setColumns] = useState(4)
   const [scaleFactor, setScaleFactor] = useState(1.5)
   const [widthMm, setWidthMm] = useState<number | undefined>(undefined)
   const [format, setFormat] = useState<'stl' | '3mf' | 'scad'>('stl')

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

@@ -2,7 +2,7 @@
 
 import { css } from '../../../../../styled-system/css'
 import { AbacusReact, useAbacusConfig } from '@soroban/abacus-react'
-import Link from 'next/link'
+import { AbacusDisplayDropdown } from '@/components/AbacusDisplayDropdown'
 
 interface CalendarConfigPanelProps {
   month: number
@@ -243,7 +243,7 @@ export function CalendarConfigPanel({
         </select>
       </fieldset>
 
-      {/* Abacus Styling Info */}
+      {/* Abacus Styling */}
       <div
         data-section="styling-info"
         className={css({
@@ -259,7 +259,7 @@ export function CalendarConfigPanel({
             color: 'gray.300',
           })}
         >
-          Using your saved abacus style:
+          Calendar abacus style preview:
         </p>
         <div
           className={css({
@@ -273,22 +273,17 @@ export function CalendarConfigPanel({
             columns={2}
             customStyles={abacusConfig.customStyles}
             scaleFactor={0.5}
+            showNumbers={false}
           />
         </div>
-        <Link
-          href="/create"
-          data-action="edit-style"
+        <div
           className={css({
-            display: 'block',
-            textAlign: 'center',
-            fontSize: '0.875rem',
-            color: 'yellow.400',
-            textDecoration: 'underline',
-            _hover: { color: 'yellow.300' },
+            display: 'flex',
+            justifyContent: 'center',
           })}
         >
-          Edit your abacus style →
-        </Link>
+          <AbacusDisplayDropdown />
+        </div>
       </div>
 
       {/* Generate Button */}

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

@@ -1,45 +1,47 @@
 'use client'
 
+import { useQuery } 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 to fetch Typst-generated preview (client-side only)
+  const { data: typstPreviewSvg, isLoading } = useQuery({
+    queryKey: ['calendar-typst-preview', month, year, format],
+    queryFn: () => fetchTypstPreview(month, year, format),
+    enabled: typeof window !== 'undefined' && format === 'monthly', // Only run on client and for monthly 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') {
+  // Show loading state while fetching preview
+  if (isLoading || (!displaySvg && format === 'monthly')) {
     return (
       <div
         data-component="calendar-preview"
@@ -57,108 +59,42 @@ 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}
-            />
-          </div>
-
-          {/* Large day number */}
-          <div
-            className={css({
-              display: 'flex',
-              justifyContent: 'center',
-              marginBottom: '2rem',
-            })}
-          >
-            <AbacusReact
-              value={1}
-              columns={2}
-              customStyles={abacusConfig.customStyles}
-              scaleFactor={0.8}
-            />
-          </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)
+          Loading preview...
         </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)
+  if (!displaySvg) {
+    return (
+      <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',
+          })}
+        >
+          {format === 'daily' ? 'Daily format - preview after generation' : 'No preview available'}
+        </p>
+      </div>
+    )
   }
 
   return (
@@ -168,99 +104,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]} {year}
-        </h2>
-        <div
-          className={css({
-            display: 'flex',
-            justifyContent: 'center',
-          })}
-        >
-          <AbacusReact
-            value={year}
-            columns={4}
-            customStyles={abacusConfig.customStyles}
-            scaleFactor={0.6}
-          />
-        </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={0.35}
-              />
-            )}
-          </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

@@ -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,28 @@ 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)
     }
@@ -58,12 +66,12 @@ export default function CalendarCreatorPage() {
     <PageWithNav navTitle="Create" navEmoji="📅">
       <div
         data-component="calendar-creator"
-        className={css({
+        className={`with-fixed-nav ${css({
           minHeight: '100vh',
           bg: 'gray.900',
           color: 'white',
           padding: '2rem',
-        })}
+        })}`}
       >
         <div
           className={css({
@@ -122,7 +130,7 @@ export default function CalendarCreatorPage() {
             />
 
             {/* Preview */}
-            <CalendarPreview month={month} year={year} format={format} />
+            <CalendarPreview month={month} year={year} format={format} previewSvg={previewSvg} />
           </div>
         </div>
       </div>

apps/web/src/app/globals.css

@@ -3,6 +3,18 @@
 /* Import Panda CSS generated styles */
 @import "../../styled-system/styles.css";
 
+/* Layout variables */
+:root {
+  /* Navigation bar heights - used by both the nav itself and content padding */
+  --app-nav-height-full: 72px;
+  --app-nav-height-minimal: 92px;
+}
+
+/* Utility class for pages with fixed nav */
+.with-fixed-nav {
+  padding-top: var(--app-nav-height, 80px);
+}
+
 /* Custom global styles */
 body {
   font-family:

apps/web/src/app/guide/components/ReadingNumbersGuide.tsx

@@ -245,7 +245,7 @@ export function ReadingNumbersGuide() {
                   border: '1px solid',
                   borderColor: 'gray.200',
                   rounded: 'lg',
-                  p: '4',
+                  p: '2',
                   textAlign: 'center',
                   display: 'flex',
                   flexDirection: 'column',
@@ -257,27 +257,19 @@ export function ReadingNumbersGuide() {
                     fontSize: 'xl',
                     fontWeight: 'bold',
                     color: 'brand.600',
-                    mb: '3',
+                    mb: '2',
                   })}
                 >
                   {example.num}
                 </div>
 
-                {/* Aspect ratio container for soroban - roughly 1:3 ratio */}
                 <div
                   className={css({
-                    width: '100%',
-                    aspectRatio: '1/2.8',
-                    maxW: '120px',
-                    bg: 'white',
-                    border: '1px solid',
-                    borderColor: 'gray.300',
-                    rounded: 'md',
-                    mb: '3',
+                    flex: '1',
                     display: 'flex',
                     alignItems: 'center',
                     justifyContent: 'center',
-                    overflow: 'hidden',
+                    my: '2',
                   })}
                 >
                   <AbacusReact
@@ -286,7 +278,7 @@ export function ReadingNumbersGuide() {
                     beadShape={appConfig.beadShape}
                     colorScheme={appConfig.colorScheme}
                     hideInactiveBeads={appConfig.hideInactiveBeads}
-                    scaleFactor={0.8}
+                    scaleFactor={1.2}
                     interactive={false}
                     showNumbers={false}
                     animated={true}
@@ -299,7 +291,7 @@ export function ReadingNumbersGuide() {
                     color: 'gray.600',
                     lineHeight: 'tight',
                     textAlign: 'center',
-                    mt: 'auto',
+                    mt: '2',
                   })}
                 >
                   {t(`singleDigits.examples.${example.descKey}`)}
@@ -469,7 +461,7 @@ export function ReadingNumbersGuide() {
                     border: '1px solid',
                     borderColor: 'blue.300',
                     rounded: 'lg',
-                    p: '4',
+                    p: '2',
                     textAlign: 'center',
                     display: 'flex',
                     flexDirection: 'column',
@@ -481,27 +473,19 @@ export function ReadingNumbersGuide() {
                       fontSize: '2xl',
                       fontWeight: 'bold',
                       color: 'blue.600',
-                      mb: '3',
+                      mb: '2',
                     })}
                   >
                     {example.num}
                   </div>
 
-                  {/* Larger container for multi-digit numbers */}
                   <div
                     className={css({
-                      width: '100%',
-                      aspectRatio: '3/4',
-                      maxW: '180px',
-                      bg: 'gray.50',
-                      border: '1px solid',
-                      borderColor: 'blue.200',
-                      rounded: 'md',
-                      mb: '3',
+                      flex: '1',
                       display: 'flex',
                       alignItems: 'center',
                       justifyContent: 'center',
-                      overflow: 'hidden',
+                      my: '2',
                     })}
                   >
                     <AbacusReact
@@ -510,7 +494,7 @@ export function ReadingNumbersGuide() {
                       beadShape={appConfig.beadShape}
                       colorScheme={appConfig.colorScheme}
                       hideInactiveBeads={appConfig.hideInactiveBeads}
-                      scaleFactor={0.9}
+                      scaleFactor={1.2}
                       interactive={false}
                       showNumbers={false}
                       animated={true}
@@ -523,6 +507,7 @@ export function ReadingNumbersGuide() {
                       color: 'blue.700',
                       lineHeight: 'relaxed',
                       textAlign: 'center',
+                      mt: '2',
                     })}
                   >
                     {t(`multiDigit.examples.${example.descKey}`)}

apps/web/src/app/guide/page.tsx

@@ -16,7 +16,7 @@ export default function GuidePage() {
 
   return (
     <PageWithNav navTitle={t('navTitle')} navEmoji="📖">
-      <div className={css({ minHeight: '100vh', bg: 'gray.50' })}>
+      <div className={`with-fixed-nav ${css({ minHeight: '100vh', bg: 'gray.50' })}`}>
         {/* Hero Section */}
         <div
           className={css({

apps/web/src/app/test-static-abacus/page.tsx

@@ -1,9 +1,11 @@
 /**
  * Test page for AbacusStatic - Server Component
  * This demonstrates that AbacusStatic works without "use client"
+ *
+ * Note: Uses /static import path to avoid client-side code
  */
 
-import { AbacusStatic } from '@soroban/abacus-react'
+import { AbacusStatic } from '@soroban/abacus-react/static'
 
 export default function TestStaticAbacusPage() {
   const numbers = [1, 2, 3, 4, 5, 10, 25, 50, 100, 123, 456, 789]
@@ -12,8 +14,8 @@ export default function TestStaticAbacusPage() {
     <div style={{ padding: '40px', maxWidth: '1200px', margin: '0 auto' }}>
       <h1 style={{ marginBottom: '10px' }}>AbacusStatic Test (Server Component)</h1>
       <p style={{ color: '#64748b', marginBottom: '30px' }}>
-        This page is a React Server Component - no "use client" directive!
-        All abacus displays below are rendered on the server with zero client-side JavaScript.
+        This page is a React Server Component - no &quot;use client&quot; directive! All abacus
+        displays below are rendered on the server with zero client-side JavaScript.
       </p>
 
       <div
@@ -37,26 +39,20 @@ export default function TestStaticAbacusPage() {
               gap: '10px',
             }}
           >
-            <AbacusStatic
-              value={num}
-              columns="auto"
-              hideInactiveBeads
-              compact
-              scaleFactor={0.9}
-            />
-            <span style={{ fontSize: '20px', fontWeight: 'bold', color: '#475569' }}>
-              {num}
-            </span>
+            <AbacusStatic value={num} columns="auto" hideInactiveBeads compact scaleFactor={0.9} />
+            <span style={{ fontSize: '20px', fontWeight: 'bold', color: '#475569' }}>{num}</span>
           </div>
         ))}
       </div>
 
-      <div style={{ marginTop: '40px', padding: '20px', background: '#f0fdf4', borderRadius: '8px' }}>
+      <div
+        style={{ marginTop: '40px', padding: '20px', background: '#f0fdf4', borderRadius: '8px' }}
+      >
         <h2 style={{ marginTop: 0, color: '#166534' }}>✅ Success!</h2>
         <p style={{ color: '#15803d' }}>
-          If you can see the abacus displays above, then AbacusStatic is working correctly
-          in React Server Components. Check the page source - you'll see pure HTML/SVG with
-          no client-side hydration markers!
+          If you can see the abacus displays above, then AbacusStatic is working correctly in React
+          Server Components. Check the page source - you&apos;ll see pure HTML/SVG with no
+          client-side hydration markers!
         </p>
       </div>
     </div>

apps/web/src/components/3d-print/STLPreview.tsx

@@ -2,7 +2,7 @@
 
 import { OrbitControls, Stage } from '@react-three/drei'
 import { Canvas, useLoader } from '@react-three/fiber'
-import { Suspense, useEffect, useState } from 'react'
+import { Suspense, useEffect, useRef, useState } from 'react'
 // @ts-expect-error - STLLoader doesn't have TypeScript declarations
 import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js'
 import { css } from '../../../styled-system/css'
@@ -30,68 +30,86 @@ export function STLPreview({ columns, scaleFactor }: STLPreviewProps) {
   const [previewUrl, setPreviewUrl] = useState<string>('/3d-models/simplified.abacus.stl')
   const [isGenerating, setIsGenerating] = useState(false)
   const [error, setError] = useState<string | null>(null)
+  const workerRef = useRef<Worker | null>(null)
 
+  // Initialize worker
   useEffect(() => {
-    let mounted = true
+    const worker = new Worker(new URL('../../workers/openscad.worker.ts', import.meta.url), {
+      type: 'module',
+    })
 
-    const generatePreview = async () => {
-      setIsGenerating(true)
-      setError(null)
+    worker.onmessage = (event: MessageEvent) => {
+      const { data } = event
 
-      try {
-        const response = await fetch('/api/abacus/preview', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ columns, scaleFactor }),
-        })
+      switch (data.type) {
+        case 'ready':
+          console.log('[STLPreview] Worker ready')
+          break
 
-        if (!response.ok) {
-          throw new Error('Failed to generate preview')
-        }
+        case 'result': {
+          // Create blob from STL data
+          const blob = new Blob([data.stl], { type: 'application/octet-stream' })
+          const objectUrl = URL.createObjectURL(blob)
 
-        // Convert response to blob and create object URL
-        const blob = await response.blob()
-        const objectUrl = URL.createObjectURL(blob)
-
-        if (mounted) {
           // Revoke old URL if it exists
           if (previewUrl && previewUrl.startsWith('blob:')) {
             URL.revokeObjectURL(previewUrl)
           }
-          setPreviewUrl(objectUrl)
-        } else {
-          // Component unmounted, clean up the URL
-          URL.revokeObjectURL(objectUrl)
-        }
-      } catch (err) {
-        if (mounted) {
-          const errorMessage = err instanceof Error ? err.message : 'Failed to generate preview'
 
-          // Check if this is an OpenSCAD not found error
-          if (
-            errorMessage.includes('openscad: command not found') ||
-            errorMessage.includes('Command failed: openscad')
-          ) {
-            setError('OpenSCAD not installed (preview only available in production/Docker)')
-            // Fallback to showing the base STL
-            setPreviewUrl('/3d-models/simplified.abacus.stl')
-          } else {
-            setError(errorMessage)
-          }
-          console.error('Preview generation error:', err)
-        }
-      } finally {
-        if (mounted) {
+          setPreviewUrl(objectUrl)
           setIsGenerating(false)
+          setError(null)
+          break
         }
+
+        case 'error':
+          console.error('[STLPreview] Worker error:', data.error)
+          setError(data.error)
+          setIsGenerating(false)
+          // Fallback to showing the base STL
+          setPreviewUrl('/3d-models/simplified.abacus.stl')
+          break
+
+        default:
+          console.warn('[STLPreview] Unknown message type:', data)
       }
     }
 
-    // Debounce: Wait 1 second after parameters change before regenerating
-    const timeoutId = setTimeout(generatePreview, 1000)
+    worker.onerror = (error) => {
+      console.error('[STLPreview] Worker error:', error)
+      setError('Worker failed to load')
+      setIsGenerating(false)
+    }
+
+    workerRef.current = worker
+
+    return () => {
+      worker.terminate()
+      workerRef.current = null
+      // Clean up any blob URLs
+      if (previewUrl && previewUrl.startsWith('blob:')) {
+        URL.revokeObjectURL(previewUrl)
+      }
+    }
+  }, [])
+
+  // Trigger rendering when parameters change
+  useEffect(() => {
+    if (!workerRef.current) return
+
+    setIsGenerating(true)
+    setError(null)
+
+    // Debounce: Wait 500ms after parameters change before regenerating
+    const timeoutId = setTimeout(() => {
+      workerRef.current?.postMessage({
+        type: 'render',
+        columns,
+        scaleFactor,
+      })
+    }, 500)
 
     return () => {
-      mounted = false
       clearTimeout(timeoutId)
     }
   }, [columns, scaleFactor])

apps/web/src/components/AppNavBar.tsx

@@ -495,6 +495,10 @@ function MinimalNav({
         justifyContent: 'center',
         alignItems: 'flex-start',
         pointerEvents: 'none',
+        // Set active nav height for content to use
+        ['--app-nav-height' as any]: 'var(--app-nav-height-minimal)',
+        // Use the variable for min-height to ensure consistency
+        minHeight: 'var(--app-nav-height-minimal)',
       }}
     >
       {/* Hamburger Menu - positioned absolutely on left */}
@@ -568,6 +572,7 @@ export function AppNavBar({ variant = 'full', navSlot }: AppNavBarProps) {
   const pathname = usePathname()
   const router = useRouter()
   const isArcadePage = pathname?.startsWith('/arcade')
+  const isHomePage = pathname === '/'
   const { isFullscreen, toggleFullscreen, exitFullscreen } = useFullscreen()
 
   // Try to get home hero context (if on homepage)
@@ -579,7 +584,7 @@ export function AppNavBar({ variant = 'full', navSlot }: AppNavBarProps) {
   const subtitle = homeHero?.subtitle || fallbackSubtitle
 
   // Show branding unless we're on homepage with visible hero
-  const showBranding = !homeHero || !homeHero.isHeroVisible
+  const showBranding = !isHomePage || !homeHero || !homeHero.isHeroVisible
 
   // Auto-detect variant based on context
   // Only arcade pages (not /games) should use minimal nav
@@ -600,12 +605,18 @@ export function AppNavBar({ variant = 'full', navSlot }: AppNavBarProps) {
     )
   }
 
-  // Check if we should use transparent styling (when hero is visible)
-  const isTransparent = homeHero?.isHeroVisible
+  // Check if we should use transparent styling (when hero is visible on home page)
+  const isTransparent = isHomePage && homeHero?.isHeroVisible
 
   return (
     <Tooltip.Provider delayDuration={200}>
       <header
+        style={{
+          // Set active nav height for content to use
+          ['--app-nav-height' as any]: 'var(--app-nav-height-full)',
+          // Use the variable for min-height to ensure consistency
+          minHeight: 'var(--app-nav-height-full)',
+        }}
         className={css({
           bg: isTransparent ? 'transparent' : 'rgba(0, 0, 0, 0.5)',
           backdropFilter: isTransparent ? 'none' : 'blur(12px)',

apps/web/src/components/InteractiveAbacus.tsx

@@ -66,32 +66,6 @@ export function InteractiveAbacus({
       const beadPosition = beadElement.getAttribute('data-bead-position')
       const isActive = beadElement.getAttribute('data-bead-active') === '1'
 
-      console.log('Bead clicked:', {
-        beadType,
-        beadColumn,
-        beadPosition,
-        isActive,
-      })
-      console.log('Current value before click:', currentValue)
-
-      if (beadType === 'earth') {
-        const position = parseInt(beadPosition || '0', 10)
-        const placeValue = beadColumn
-        const columnPower = 10 ** placeValue
-        const currentDigit = Math.floor(currentValue / columnPower) % 10
-        const heavenContribution = Math.floor(currentDigit / 5) * 5
-        const earthContribution = currentDigit % 5
-        console.log('Earth bead analysis:', {
-          position,
-          beadColumn,
-          placeValue,
-          columnPower,
-          currentDigit,
-          heavenContribution,
-          earthContribution,
-        })
-      }
-
       if (beadType === 'heaven') {
         // Toggle heaven bead (worth 5)
         // Now using place-value based column numbering: 0=ones, 1=tens, 2=hundreds
@@ -140,13 +114,6 @@ export function InteractiveAbacus({
           newEarthContribution = position + 1
         }
 
-        console.log('Earth bead calculation:', {
-          position,
-          isActive,
-          currentEarthContribution: earthContribution,
-          newEarthContribution,
-        })
-
         // Calculate the new digit for this column
         const newDigit = heavenContribution + newEarthContribution
 

apps/web/src/components/MyAbacus.tsx

@@ -226,7 +226,6 @@ export function MyAbacus() {
             />
           </div>
         </div>
-
       </div>
 
       {/* Keyframes for animations */}

apps/web/src/components/tutorial/TutorialPlayer.tsx

@@ -970,16 +970,11 @@ function TutorialPlayerContent({
 
   // Two-level dynamic column highlights: group terms + individual term
   const dynamicColumnHighlights = useMemo(() => {
-    console.log('🎨 COMPUTING COLUMN HIGHLIGHTS')
-    console.log('  - activeTermIndices:', Array.from(activeTermIndices))
-    console.log('  - activeIndividualTermIndex:', activeIndividualTermIndex)
-
     const highlights: Record<number, any> = {}
 
     // Level 1: Group highlights (blue glow for all terms in activeTermIndices)
     activeTermIndices.forEach((termIndex) => {
       const columnIndex = getColumnFromTermIndex(termIndex, true) // Use group column (rhsPlace)
-      console.log(`  - Group term ${termIndex} maps to column ${columnIndex} (using rhsPlace)`)
       if (columnIndex !== null) {
         highlights[columnIndex] = {
           // Group background glow effect (blue)
@@ -998,16 +993,12 @@ function TutorialPlayerContent({
             borderColor: '#3b82f6',
           },
         }
-        console.log(`  🔵 Added BLUE highlight for column ${columnIndex}`)
       }
     })
 
     // Level 2: Individual term highlight (orange glow, overrides group styling)
     if (activeIndividualTermIndex !== null) {
       const individualColumnIndex = getColumnFromTermIndex(activeIndividualTermIndex, false) // Use individual column (termPlace)
-      console.log(
-        `  - Individual term ${activeIndividualTermIndex} maps to column ${individualColumnIndex} (using termPlace)`
-      )
       if (individualColumnIndex !== null) {
         highlights[individualColumnIndex] = {
           // Individual background glow effect (orange) - overrides group glow
@@ -1026,54 +1017,46 @@ function TutorialPlayerContent({
             borderColor: '#ea580c',
           },
         }
-        console.log(
-          `  🟠 Added ORANGE highlight for column ${individualColumnIndex} (overriding blue)`
-        )
       }
     }
 
-    console.log(
-      '🎨 Final highlights:',
-      Object.keys(highlights).map((col) => `Column ${col}`)
-    )
     return highlights
   }, [activeTermIndices, activeIndividualTermIndex, getColumnFromTermIndex])
 
   // Memoize custom styles calculation to avoid expensive recalculation on every render
   const customStyles = useMemo(() => {
-    // Calculate valid column range based on abacusColumns
-    const minValidColumn = 5 - abacusColumns
-
-    // Start with static highlights from step configuration
-    const staticHighlights: Record<number, any> = {}
+    // Separate bead-level and column-level styles
+    const beadLevelHighlights: Record<number, any> = {}
+    const columnLevelHighlights: Record<number, any> = {}
 
+    // Process static highlights from step configuration (bead-specific)
     if (currentStep.highlightBeads && Array.isArray(currentStep.highlightBeads)) {
       currentStep.highlightBeads.forEach((highlight) => {
         // Convert placeValue to columnIndex for AbacusReact compatibility
         const columnIndex = abacusColumns - 1 - highlight.placeValue
 
-        // Skip highlights for columns that don't exist
-        if (columnIndex < minValidColumn) {
+        // Skip highlights for columns that don't exist in the rendered abacus
+        if (columnIndex < 0 || columnIndex >= abacusColumns) {
           return
         }
 
         // Initialize column if it doesn't exist
-        if (!staticHighlights[columnIndex]) {
-          staticHighlights[columnIndex] = {}
+        if (!beadLevelHighlights[columnIndex]) {
+          beadLevelHighlights[columnIndex] = {}
         }
 
         // Add the bead style to the appropriate type
         if (highlight.beadType === 'earth' && highlight.position !== undefined) {
-          if (!staticHighlights[columnIndex].earth) {
-            staticHighlights[columnIndex].earth = {}
+          if (!beadLevelHighlights[columnIndex].earth) {
+            beadLevelHighlights[columnIndex].earth = {}
           }
-          staticHighlights[columnIndex].earth[highlight.position] = {
+          beadLevelHighlights[columnIndex].earth[highlight.position] = {
             fill: '#fbbf24',
             stroke: '#f59e0b',
             strokeWidth: 3,
           }
         } else {
-          staticHighlights[columnIndex][highlight.beadType] = {
+          beadLevelHighlights[columnIndex][highlight.beadType] = {
             fill: '#fbbf24',
             stroke: '#f59e0b',
             strokeWidth: 3,
@@ -1082,29 +1065,30 @@ function TutorialPlayerContent({
       })
     }
 
-    // Merge static and dynamic highlights (dynamic takes precedence)
-    const mergedHighlights = { ...staticHighlights }
+    // Process dynamic column highlights (column-level: backgroundGlow, numerals)
     Object.keys(dynamicColumnHighlights).forEach((columnIndexStr) => {
       const columnIndex = parseInt(columnIndexStr, 10)
 
-      // Skip highlights for columns that don't exist
-      if (columnIndex < minValidColumn) {
+      // Skip highlights for columns that don't exist in the rendered abacus
+      if (columnIndex < 0 || columnIndex >= abacusColumns) {
         return
       }
 
-      if (!mergedHighlights[columnIndex]) {
-        mergedHighlights[columnIndex] = {}
-      }
-      // Merge dynamic highlights into the column
-      Object.assign(mergedHighlights[columnIndex], dynamicColumnHighlights[columnIndex])
+      // Dynamic highlights are column-level (backgroundGlow, numerals)
+      columnLevelHighlights[columnIndex] = dynamicColumnHighlights[columnIndex]
     })
 
     // Build the custom styles object
     const styles: any = {}
 
-    // Add column highlights if any
-    if (Object.keys(mergedHighlights).length > 0) {
-      styles.columns = mergedHighlights
+    // Add bead-level highlights to styles.beads
+    if (Object.keys(beadLevelHighlights).length > 0) {
+      styles.beads = beadLevelHighlights
+    }
+
+    // Add column-level highlights to styles.columns
+    if (Object.keys(columnLevelHighlights).length > 0) {
+      styles.columns = columnLevelHighlights
     }
 
     // Add frame styling for dark mode
@@ -1123,6 +1107,17 @@ function TutorialPlayerContent({
       }
     }
 
+    // Debug logging for custom styles
+    if (Object.keys(styles).length > 0) {
+      console.log('📋 TUTORIAL CUSTOM STYLES:', JSON.stringify({
+        beadLevelHighlights,
+        columnLevelHighlights,
+        finalStyles: styles,
+        currentStepHighlightBeads: currentStep.highlightBeads,
+        abacusColumns,
+      }, null, 2))
+    }
+
     return Object.keys(styles).length > 0 ? styles : undefined
   }, [currentStep.highlightBeads, dynamicColumnHighlights, abacusColumns, theme])
 
@@ -1608,7 +1603,7 @@ function TutorialPlayerContent({
                   columns={abacusColumns}
                   interactive={true}
                   animated={true}
-                  scaleFactor={2.5}
+                  scaleFactor={1.5}
                   colorScheme={abacusConfig.colorScheme}
                   beadShape={abacusConfig.beadShape}
                   hideInactiveBeads={abacusConfig.hideInactiveBeads}

apps/web/src/contexts/HomeHeroContext.tsx

@@ -53,49 +53,28 @@ export function HomeHeroProvider({ children }: { children: React.ReactNode }) {
 
   // Load from sessionStorage after mount (client-only, no hydration mismatch)
   useEffect(() => {
-    console.log('[HeroAbacus] Loading from sessionStorage...')
     isLoadingFromStorage.current = true // Block saves during load
 
     const saved = sessionStorage.getItem('heroAbacusValue')
-    console.log('[HeroAbacus] Saved value from storage:', saved)
 
     if (saved) {
       const parsedValue = parseInt(saved, 10)
-      console.log('[HeroAbacus] Parsed value:', parsedValue)
       if (!Number.isNaN(parsedValue)) {
-        console.log('[HeroAbacus] Setting abacus value to:', parsedValue)
         setAbacusValue(parsedValue)
       }
-    } else {
-      console.log('[HeroAbacus] No saved value found, staying at 0')
     }
 
     // Use setTimeout to ensure the value has been set before we allow saves
     setTimeout(() => {
       isLoadingFromStorage.current = false
       setIsAbacusLoaded(true)
-      console.log('[HeroAbacus] Load complete, allowing saves now and fading in')
     }, 0)
   }, [])
 
   // Persist value to sessionStorage when it changes (but skip during load)
   useEffect(() => {
-    console.log(
-      '[HeroAbacus] Save effect triggered. Value:',
-      abacusValue,
-      'isLoadingFromStorage:',
-      isLoadingFromStorage.current
-    )
-
     if (!isLoadingFromStorage.current) {
-      console.log('[HeroAbacus] Saving to sessionStorage:', abacusValue)
       sessionStorage.setItem('heroAbacusValue', abacusValue.toString())
-      console.log(
-        '[HeroAbacus] Saved successfully. Storage now contains:',
-        sessionStorage.getItem('heroAbacusValue')
-      )
-    } else {
-      console.log('[HeroAbacus] Skipping save (currently loading from storage)')
     }
   }, [abacusValue])
 

apps/web/src/utils/calendar/generateCalendarAbacus.tsx

@@ -0,0 +1,19 @@
+/**
+ * Generate a simple abacus SVG element
+ * Uses AbacusStatic for server-side rendering (no client hooks)
+ */
+
+import React from 'react'
+import { AbacusStatic } from '@soroban/abacus-react/static'
+
+export function generateAbacusElement(value: number, columns: number) {
+  return (
+    <AbacusStatic
+      value={value}
+      columns={columns}
+      scaleFactor={1}
+      showNumbers={false}
+      frameVisible={true}
+    />
+  )
+}

apps/web/src/utils/calendar/generateCalendarComposite.tsx

@@ -0,0 +1,205 @@
+/**
+ * Generate a complete monthly calendar as a single SVG
+ * This prevents multi-page overflow - one image scales to fit
+ */
+
+import type 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
+}

apps/web/src/workers/openscad.worker.ts

@@ -0,0 +1,206 @@
+/// <reference lib="webworker" />
+
+import { createOpenSCAD } from 'openscad-wasm-prebuilt'
+
+declare const self: DedicatedWorkerGlobalScope
+
+let openscad: Awaited<ReturnType<typeof createOpenSCAD>> | null = null
+let simplifiedStlData: ArrayBuffer | null = null
+let isInitializing = false
+let initPromise: Promise<void> | null = null
+
+// Message types
+interface RenderRequest {
+  type: 'render'
+  columns: number
+  scaleFactor: number
+}
+
+interface InitRequest {
+  type: 'init'
+}
+
+type WorkerRequest = RenderRequest | InitRequest
+
+// Initialize OpenSCAD instance and load base STL file
+async function initialize() {
+  if (openscad) return // Already initialized
+  if (isInitializing) return initPromise // Already initializing, return existing promise
+
+  isInitializing = true
+  initPromise = (async () => {
+    try {
+      console.log('[OpenSCAD Worker] Initializing...')
+
+      // Create OpenSCAD instance
+      openscad = await createOpenSCAD()
+      console.log('[OpenSCAD Worker] OpenSCAD WASM loaded')
+
+      // Fetch the simplified STL file once
+      const stlResponse = await fetch('/3d-models/simplified.abacus.stl')
+      if (!stlResponse.ok) {
+        throw new Error(`Failed to fetch STL: ${stlResponse.statusText}`)
+      }
+      simplifiedStlData = await stlResponse.arrayBuffer()
+      console.log('[OpenSCAD Worker] Simplified STL loaded', simplifiedStlData.byteLength, 'bytes')
+
+      self.postMessage({ type: 'ready' })
+    } catch (error) {
+      console.error('[OpenSCAD Worker] Initialization failed:', error)
+      self.postMessage({
+        type: 'error',
+        error: error instanceof Error ? error.message : 'Initialization failed',
+      })
+      throw error
+    } finally {
+      isInitializing = false
+    }
+  })()
+
+  return initPromise
+}
+
+async function render(columns: number, scaleFactor: number) {
+  // Wait for initialization if not ready
+  if (!openscad || !simplifiedStlData) {
+    await initialize()
+  }
+
+  if (!openscad || !simplifiedStlData) {
+    throw new Error('Worker not initialized')
+  }
+
+  try {
+    console.log(`[OpenSCAD Worker] Rendering with columns=${columns}, scaleFactor=${scaleFactor}`)
+
+    // Get low-level instance for filesystem access
+    const instance = openscad.getInstance()
+
+    // Create directory if it doesn't exist
+    try {
+      instance.FS.mkdir('/3d-models')
+      console.log('[OpenSCAD Worker] Created /3d-models directory')
+    } catch (e: any) {
+      // Check if it's EEXIST (directory already exists) - errno 20
+      if (e.errno === 20) {
+        console.log('[OpenSCAD Worker] /3d-models directory already exists')
+      } else {
+        console.error('[OpenSCAD Worker] Failed to create directory:', e)
+        throw new Error(`Failed to create /3d-models directory: ${e.message || e}`)
+      }
+    }
+
+    // Write STL file
+    instance.FS.writeFile('/3d-models/simplified.abacus.stl', new Uint8Array(simplifiedStlData))
+    console.log('[OpenSCAD Worker] Wrote simplified STL to filesystem')
+
+    // Generate the SCAD code with parameters
+    const scadCode = `
+// Inline version of abacus.scad that doesn't require BOSL2
+columns = ${columns};
+scale_factor = ${scaleFactor};
+
+stl_path = "/3d-models/simplified.abacus.stl";
+
+// Known bounding box dimensions
+bbox_size = [186, 60, 120];
+
+// Calculate parameters
+total_columns_in_stl = 13;
+columns_per_side = columns / 2;
+width_scale = columns_per_side / total_columns_in_stl;
+
+units_per_column = bbox_size[0] / total_columns_in_stl;
+column_spacing = columns_per_side * units_per_column;
+
+// Model modules
+module imported() {
+    import(stl_path, convexity = 10);
+}
+
+module bounding_box_manual() {
+    translate([-bbox_size[0]/2, -bbox_size[1]/2, -bbox_size[2]/2])
+        cube(bbox_size);
+}
+
+module half_abacus() {
+    intersection() {
+        scale([width_scale, 1, 1]) bounding_box_manual();
+        imported();
+    }
+}
+
+scale([scale_factor, scale_factor, scale_factor]) {
+    translate([column_spacing, 0, 0]) mirror([1,0,0]) half_abacus();
+    half_abacus();
+}
+`
+
+    // Use high-level renderToStl API
+    console.log('[OpenSCAD Worker] Calling renderToStl...')
+    const stlBuffer = await openscad.renderToStl(scadCode)
+    console.log('[OpenSCAD Worker] Rendering complete:', stlBuffer.byteLength, 'bytes')
+
+    // Send the result back
+    self.postMessage({
+      type: 'result',
+      stl: stlBuffer,
+    }, [stlBuffer])  // Transfer ownership of the buffer
+
+    // Clean up STL file
+    try {
+      instance.FS.unlink('/3d-models/simplified.abacus.stl')
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+  } catch (error) {
+    console.error('[OpenSCAD Worker] Rendering failed:', error)
+
+    // Try to get more error details
+    let errorMessage = 'Rendering failed'
+    if (error instanceof Error) {
+      errorMessage = error.message
+      console.error('[OpenSCAD Worker] Error stack:', error.stack)
+    }
+
+    // Check if it's an Emscripten FS error
+    if (error && typeof error === 'object' && 'errno' in error) {
+      console.error('[OpenSCAD Worker] FS errno:', (error as any).errno)
+      console.error('[OpenSCAD Worker] FS error details:', error)
+    }
+
+    self.postMessage({
+      type: 'error',
+      error: errorMessage,
+    })
+  }
+}
+
+// Message handler
+self.onmessage = async (event: MessageEvent<WorkerRequest>) => {
+  const { data } = event
+
+  try {
+    switch (data.type) {
+      case 'init':
+        await initialize()
+        break
+
+      case 'render':
+        await render(data.columns, data.scaleFactor)
+        break
+
+      default:
+        console.error('[OpenSCAD Worker] Unknown message type:', data)
+    }
+  } catch (error) {
+    console.error('[OpenSCAD Worker] Message handler error:', error)
+    self.postMessage({
+      type: 'error',
+      error: error instanceof Error ? error.message : 'Unknown error',
+    })
+  }
+}
+
+// Auto-initialize on worker start
+initialize()

packages/abacus-react/.claude/settings.local.json

@@ -11,7 +11,24 @@
       "Bash(git commit:*)",
       "Bash(npm run build:*)",
       "Bash(git reset:*)",
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(pnpm --filter @soroban/abacus-react build:*)",
+      "Bash(git show:*)",
+      "Bash(pnpm build:*)",
+      "Bash(pnpm --filter @soroban/web build:*)",
+      "Bash(pnpm tsc:*)",
+      "Bash(AbacusReact.tsx)",
+      "Bash(git log:*)",
+      "Bash(pnpm dev)",
+      "Bash(npx biome:*)",
+      "Bash(pnpm --filter @soroban/web tsc:*)",
+      "Bash(git tag:*)",
+      "Bash(gh api:*)",
+      "WebSearch",
+      "WebFetch(domain:schroer.ca)",
+      "WebFetch(domain:github.com)",
+      "Bash(npm search:*)",
+      "Bash(pnpm add:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

packages/abacus-react/CHANGELOG.md

@@ -1,3 +1,91 @@
+# [2.9.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.8.3...abacus-react-v2.9.0) (2025-11-05)
+
+
+### Bug Fixes
+
+* **docker:** upgrade OpenSCAD to 2024.11 to fix CGAL intersection bug ([e1bcd24](https://github.com/antialias/soroban-abacus-flashcards/commit/e1bcd241691050fa05cd49e14c288b4b070a7d17))
+* **guide:** increase abacus sizes - they were too small ([1074624](https://github.com/antialias/soroban-abacus-flashcards/commit/1074624b2fbce1d1d887dbd6326cf22eeb31dcec))
+* **guide:** make abacus sizes consistent and add nav spacing ([bea4842](https://github.com/antialias/soroban-abacus-flashcards/commit/bea4842a29aa86ca4261b4ddd6150bacc8babc46))
+* **guide:** remove inner containers and tighten margins ([7e54c6f](https://github.com/antialias/soroban-abacus-flashcards/commit/7e54c6f4fc5bc4daa6088eb3381d860a495776f2))
+* **layout:** add systematic spacing for fixed nav bar ([4559fb1](https://github.com/antialias/soroban-abacus-flashcards/commit/4559fb121d0df954ebaf33616a5262c7ca633c6e))
+* **layout:** remove wrapper, use utility class for nav spacing ([247c3d9](https://github.com/antialias/soroban-abacus-flashcards/commit/247c3d9874303f83641e599724a485eea8d5604a))
+* **nav:** restrict transparent hero styling to home page only ([fab227d](https://github.com/antialias/soroban-abacus-flashcards/commit/fab227d6862672e8250b1c169b302fbae23ce4d2))
+
+
+### Features
+
+* **3d-abacus:** change default columns from 13 to 4 ([cd15c70](https://github.com/antialias/soroban-abacus-flashcards/commit/cd15c70a25c597c17ee5d2f816b1c85ba8ce4ce9))
+* add client-side OpenSCAD WASM support for 3D preview ([eaaf17c](https://github.com/antialias/soroban-abacus-flashcards/commit/eaaf17cd4c675bfd40e0573b9c99f0c733d926aa))
+
+## [2.8.3](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.8.2...abacus-react-v2.8.3) (2025-11-05)
+
+
+### Bug Fixes
+
+* **tutorial:** correct column validation for bead highlights ([9ba1824](https://github.com/antialias/soroban-abacus-flashcards/commit/9ba18242262cd63cc6c25361aaec3a4c0f66b161))
+* **tutorial:** fix overlay rendering, arrow indicators, and bead visibility ([a804316](https://github.com/antialias/soroban-abacus-flashcards/commit/a80431608dbc4f54d8e4f1095936b95a258b4a72))
+* **web,docker:** add --format flag for Typst and upgrade to v0.13.0 ([19b9d7a](https://github.com/antialias/soroban-abacus-flashcards/commit/19b9d7a74f549c7e93c9564e4a903e1bcd5a4bbc))
+* **web:** move tsx to production dependencies for calendar generation ([ffae9c1](https://github.com/antialias/soroban-abacus-flashcards/commit/ffae9c1bdbccc5edb2e747a09d1fcad3b29e4eac))
+
+## [2.8.2](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.8.1...abacus-react-v2.8.2) (2025-11-04)
+
+
+### Bug Fixes
+
+* **abacus-react:** add data-testid attributes back to beads for testing ([23ae1b0](https://github.com/antialias/soroban-abacus-flashcards/commit/23ae1b0c6f878daf79a993992d43ad80a89fa790))
+
+## [2.8.1](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.8.0...abacus-react-v2.8.1) (2025-11-04)
+
+
+### Bug Fixes
+
+* **abacus-react:** fix animations by preventing component remounting ([be7d4c4](https://github.com/antialias/soroban-abacus-flashcards/commit/be7d4c471327534a95c4c75372680c629b5f12c2))
+* **abacus-react:** restore original AbacusReact measurements and positioning ([88c0baa](https://github.com/antialias/soroban-abacus-flashcards/commit/88c0baaad9b83b60ab8cdcad92070cc049d61cc7))
+
+# [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)
+
+
+### Bug Fixes
+
+* **web:** add dynamic export to rithmomachia page ([329e623](https://github.com/antialias/soroban-abacus-flashcards/commit/329e62321245ef62726c986c917f19a909a5b65e))
+* **web:** fix Typst PDF generation path resolution ([7ce1287](https://github.com/antialias/soroban-abacus-flashcards/commit/7ce12875254a31d8acdb35ef5de7d36d215ccd92))
+
+
+### Features
+
+* **abacus-react:** add separate /static export path for React Server Components ([ed69f6b](https://github.com/antialias/soroban-abacus-flashcards/commit/ed69f6b917c543bbcaa4621a0e63745bee70f5bf))
+* **web:** add test page for AbacusStatic RSC compatibility ([903dea2](https://github.com/antialias/soroban-abacus-flashcards/commit/903dea25844f1d2b3730fbcbd8478e7af1887663))
+* **web:** improve calendar abacus preview styling ([8439727](https://github.com/antialias/soroban-abacus-flashcards/commit/8439727b152accf61f0c28158b92788510ca086e))
+
 # [2.6.0](https://github.com/antialias/soroban-abacus-flashcards/compare/abacus-react-v2.5.0...abacus-react-v2.6.0) (2025-11-04)
 
 

packages/abacus-react/README.md

@@ -127,7 +127,8 @@ import { AbacusReact, ABACUS_THEMES } from '@soroban/abacus-react';
 For static, non-interactive displays that work in React Server Components:
 
 ```tsx
-import { AbacusStatic } from '@soroban/abacus-react';
+// IMPORTANT: Use /static import path for RSC compatibility!
+import { AbacusStatic } from '@soroban/abacus-react/static';
 
 // ✅ Works in React Server Components - no "use client" needed!
 // ✅ No JavaScript sent to client
@@ -141,6 +142,66 @@ import { AbacusStatic } from '@soroban/abacus-react';
 />
 ```
 
+**Import paths:**
+- `@soroban/abacus-react` - Full package (client components with hooks/animations)
+- `@soroban/abacus-react/static` - Server-compatible components only (no client code)
+
+**Guaranteed Visual Consistency:**
+
+Both `AbacusStatic` and `AbacusReact` share the same underlying layout engine. **Same props = same exact SVG output.** This ensures:
+- Static previews match interactive versions pixel-perfect
+- Server-rendered abaci look identical to client-rendered ones
+- PDF generation produces accurate representations
+- No visual discrepancies between environments
+
+**Architecture: How We Guarantee Consistency**
+
+The package uses a shared rendering architecture with dependency injection:
+
+```
+┌─────────────────────────────────────────────┐
+│ Shared Utilities (AbacusUtils.ts)          │
+│ • calculateStandardDimensions() - Single    │
+│   source of truth for all layout dimensions│
+│ • calculateBeadPosition() - Exact bead      │
+│   positioning using shared formulas        │
+└────────────┬────────────────────────────────┘
+             │
+             ├──────────────────────────────────┐
+             ↓                                  ↓
+   ┌─────────────────┐              ┌─────────────────┐
+   │ AbacusStatic    │              │ AbacusReact     │
+   │ (Server/Static) │              │ (Interactive)   │
+   └────────┬────────┘              └────────┬────────┘
+            │                                │
+            └────────────┬───────────────────┘
+                         ↓
+             ┌────────────────────────┐
+             │ AbacusSVGRenderer      │
+             │ • Pure SVG structure   │
+             │ • Dependency injection │
+             │ • Bead component prop  │
+             └────────────────────────┘
+                         ↓
+         ┌───────────────┴───────────────┐
+         ↓                               ↓
+   ┌──────────────┐              ┌──────────────────┐
+   │ AbacusStatic │              │ AbacusAnimated   │
+   │ Bead         │              │ Bead             │
+   │ (Simple SVG) │              │ (react-spring)   │
+   └──────────────┘              └──────────────────┘
+```
+
+**Key Components:**
+
+1. **`calculateStandardDimensions()`** - Returns complete layout dimensions (bar position, bead sizes, gaps, etc.)
+2. **`calculateBeadPosition()`** - Calculates exact x,y coordinates for any bead
+3. **`AbacusSVGRenderer`** - Shared SVG rendering component that accepts a bead component via dependency injection
+4. **`AbacusStaticBead`** - Simple SVG shapes for static display (no hooks, RSC-compatible)
+5. **`AbacusAnimatedBead`** - Client component with react-spring animations and gesture handling
+
+This architecture eliminates code duplication (~560 lines removed in the refactor) while guaranteeing pixel-perfect consistency.
+
 **When to use `AbacusStatic` vs `AbacusReact`:**
 
 | Feature | AbacusStatic | AbacusReact |
@@ -151,13 +212,14 @@ import { AbacusStatic } from '@soroban/abacus-react';
 | Animations | ❌ No | ✅ Smooth transitions |
 | Sound effects | ❌ No | ✅ Optional sounds |
 | 3D effects | ❌ No | ✅ Yes |
+| **Visual output** | **✅ Identical** | **✅ Identical** |
 | Bundle size | 📦 Minimal | 📦 Full-featured |
-| Use cases | Preview cards, thumbnails, static pages | Interactive tutorials, games, tools |
+| Use cases | Preview cards, thumbnails, static pages, PDFs | Interactive tutorials, games, tools |
 
 ```tsx
 // Example: Server Component with static abacus cards
 // app/flashcards/page.tsx
-import { AbacusStatic } from '@soroban/abacus-react'
+import { AbacusStatic } from '@soroban/abacus-react/static'
 
 export default function FlashcardsPage() {
   const numbers = [1, 5, 10, 25, 50, 100]
@@ -643,6 +705,63 @@ const state2 = numberToAbacusState(123);
 const isEqual = areStatesEqual(state1, state2); // true
 ```
 
+### calculateStandardDimensions
+
+**⚡ Core Architecture Function** - Calculate complete layout dimensions for consistent rendering.
+
+This is the **single source of truth** for all layout dimensions, used internally by both `AbacusStatic` and `AbacusReact` to guarantee pixel-perfect consistency.
+
+```tsx
+import { calculateStandardDimensions } from '@soroban/abacus-react';
+
+const dimensions = calculateStandardDimensions({
+  columns: 3,
+  scaleFactor: 1.5,
+  showNumbers: true,
+  columnLabels: ['ones', 'tens', 'hundreds']
+});
+
+// Returns complete layout info:
+// {
+//   width, height,           // SVG canvas size
+//   beadSize,                // 12 * scaleFactor (standard bead size)
+//   rodSpacing,              // 25 * scaleFactor (column spacing)
+//   rodWidth,                // 3 * scaleFactor
+//   barThickness,            // 2 * scaleFactor
+//   barY,                    // Reckoning bar Y position (30 * scaleFactor + labels)
+//   heavenY, earthY,         // Inactive bead rest positions
+//   activeGap,               // 1 * scaleFactor (gap to bar when active)
+//   inactiveGap,             // 8 * scaleFactor (gap between active/inactive)
+//   adjacentSpacing,         // 0.5 * scaleFactor (spacing between adjacent beads)
+//   padding, labelHeight, numbersHeight, totalColumns
+// }
+```
+
+**Why this matters:** Same input parameters = same exact layout dimensions = pixel-perfect visual consistency across static and interactive displays.
+
+### calculateBeadPosition
+
+**⚡ Core Architecture Function** - Calculate exact x,y coordinates for any bead.
+
+Used internally by `AbacusSVGRenderer` to position all beads consistently in both static and interactive modes.
+
+```tsx
+import { calculateBeadPosition, calculateStandardDimensions } from '@soroban/abacus-react';
+
+const dimensions = calculateStandardDimensions({ columns: 3, scaleFactor: 1 });
+const bead = {
+  type: 'heaven',
+  active: true,
+  position: 0,
+  placeValue: 1  // tens column
+};
+
+const position = calculateBeadPosition(bead, dimensions);
+// Returns: { x: 25, y: 29 }  // exact pixel coordinates
+```
+
+Useful for custom rendering or positioning tooltips/overlays relative to specific beads.
+
 ## Educational Use Cases
 
 ### Interactive Math Lessons
@@ -720,6 +839,8 @@ import {
   calculateBeadDiffFromValues,
   validateAbacusValue,
   areStatesEqual,
+  calculateStandardDimensions,  // NEW: Shared layout calculator
+  calculateBeadPosition,         // NEW: Bead position calculator
 
   // Theme Presets
   ABACUS_THEMES,
@@ -735,7 +856,9 @@ import {
   BeadState,
   BeadDiffResult,
   BeadDiffOutput,
-  AbacusThemeName
+  AbacusThemeName,
+  AbacusLayoutDimensions,        // NEW: Complete layout dimensions type
+  BeadPositionConfig             // NEW: Bead config for position calculation
 } from '@soroban/abacus-react';
 
 // All interfaces fully typed for excellent developer experience

packages/abacus-react/package.json

@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs.js"
+    },
+    "./static": {
+      "types": "./dist/static.d.ts",
+      "import": "./dist/static.es.js",
+      "require": "./dist/static.cjs.js"
     }
   },
   "files": [

packages/abacus-react/src/AbacusAnimatedBead.tsx

@@ -0,0 +1,390 @@
+'use client'
+
+/**
+ * AbacusAnimatedBead - Interactive bead component for AbacusReact (Core Architecture)
+ *
+ * This is the **client-side bead component** injected into AbacusSVGRenderer by AbacusReact.
+ * It provides animations and interactivity while the parent renderer handles positioning.
+ *
+ * ## Architecture Role:
+ * - Injected into `AbacusSVGRenderer` via dependency injection (BeadComponent prop)
+ * - Receives x,y position from `calculateBeadPosition()` (already calculated)
+ * - Adds animations and interactions on top of the shared layout
+ * - Used ONLY by AbacusReact (requires "use client")
+ *
+ * ## Features:
+ * - ✅ React Spring animations for smooth position changes
+ * - ✅ Drag gesture handling with @use-gesture/react
+ * - ✅ Direction indicators for tutorials (pulsing arrows)
+ * - ✅ 3D effects and gradients
+ * - ✅ Click and hover interactions
+ *
+ * ## Comparison:
+ * - `AbacusStaticBead` - Simple SVG shapes (no animations, RSC-compatible)
+ * - `AbacusAnimatedBead` - This component (animations, gestures, client-only)
+ *
+ * Both receive the same position from `calculateBeadPosition()`, ensuring visual consistency.
+ */
+
+import React, { useCallback, useRef } from 'react'
+import { useSpring, animated, to } from '@react-spring/web'
+import { useDrag } from '@use-gesture/react'
+import type { BeadComponentProps } from './AbacusSVGRenderer'
+import type { BeadConfig } from './AbacusReact'
+
+interface AnimatedBeadProps extends BeadComponentProps {
+  // Animation controls
+  enableAnimation: boolean
+  physicsConfig: any
+
+  // Gesture handling
+  enableGestures: boolean
+  onGestureToggle?: (bead: BeadConfig, direction: 'activate' | 'deactivate') => void
+
+  // Direction indicators (for tutorials)
+  showDirectionIndicator?: boolean
+  direction?: 'activate' | 'deactivate'
+  isCurrentStep?: boolean
+
+  // 3D effects
+  enhanced3d?: 'none' | 'subtle' | 'realistic' | 'delightful'
+  columnIndex?: number
+
+  // Hover state from parent abacus
+  isAbacusHovered?: boolean
+}
+
+export function AbacusAnimatedBead({
+  bead,
+  x,
+  y,
+  size,
+  shape,
+  color,
+  hideInactiveBeads,
+  customStyle,
+  onClick,
+  onMouseEnter,
+  onMouseLeave,
+  onRef,
+  enableAnimation,
+  physicsConfig,
+  enableGestures,
+  onGestureToggle,
+  showDirectionIndicator,
+  direction,
+  isCurrentStep,
+  enhanced3d = 'none',
+  columnIndex,
+  isAbacusHovered = false,
+}: AnimatedBeadProps) {
+  // x, y are already calculated by AbacusSVGRenderer
+
+  // Track hover state for showing hidden inactive beads
+  const [isHovered, setIsHovered] = React.useState(false)
+
+  // Use abacus hover if provided, otherwise use individual bead hover
+  const effectiveHoverState = isAbacusHovered || isHovered
+
+  // Spring animation for position
+  const [{ springX, springY }, api] = useSpring(() => ({
+    springX: x,
+    springY: y,
+    config: physicsConfig,
+  }))
+
+  // Arrow pulse animation for direction indicators
+  const [{ arrowPulse }, arrowApi] = useSpring(() => ({
+    arrowPulse: 1,
+    config: enableAnimation ? { tension: 200, friction: 10 } : { duration: 0 },
+  }))
+
+  const gestureStateRef = useRef({
+    isDragging: false,
+    lastDirection: null as 'activate' | 'deactivate' | null,
+    startY: 0,
+    threshold: size * 0.3,
+    hasGestureTriggered: false,
+  })
+
+  // Calculate gesture direction based on bead type
+  const getGestureDirection = useCallback(
+    (deltaY: number) => {
+      const movement = Math.abs(deltaY)
+      if (movement < gestureStateRef.current.threshold) return null
+
+      if (bead.type === 'heaven') {
+        return deltaY > 0 ? 'activate' : 'deactivate'
+      } else {
+        return deltaY < 0 ? 'activate' : 'deactivate'
+      }
+    },
+    [bead.type, size]
+  )
+
+  // Gesture handler
+  const bind = enableGestures
+    ? useDrag(
+        ({ event, movement: [, deltaY], first, active }) => {
+          if (first) {
+            event?.preventDefault()
+            gestureStateRef.current.isDragging = true
+            gestureStateRef.current.lastDirection = null
+            gestureStateRef.current.hasGestureTriggered = false
+            return
+          }
+
+          if (!active || !gestureStateRef.current.isDragging) {
+            if (!active) {
+              gestureStateRef.current.isDragging = false
+              gestureStateRef.current.lastDirection = null
+              setTimeout(() => {
+                gestureStateRef.current.hasGestureTriggered = false
+              }, 100)
+            }
+            return
+          }
+
+          const currentDirection = getGestureDirection(deltaY)
+
+          if (
+            currentDirection &&
+            currentDirection !== gestureStateRef.current.lastDirection
+          ) {
+            gestureStateRef.current.lastDirection = currentDirection
+            gestureStateRef.current.hasGestureTriggered = true
+            onGestureToggle?.(bead, currentDirection)
+          }
+        },
+        {
+          enabled: enableGestures,
+          preventDefault: true,
+        }
+      )
+    : () => ({})
+
+  // Update spring animation when position changes
+  React.useEffect(() => {
+    if (enableAnimation) {
+      api.start({ springX: x, springY: y, config: physicsConfig })
+    } else {
+      api.set({ springX: x, springY: y })
+    }
+  }, [x, y, enableAnimation, api, physicsConfig])
+
+  // Pulse animation for direction indicators
+  React.useEffect(() => {
+    if (showDirectionIndicator && direction && isCurrentStep) {
+      const startPulse = () => {
+        arrowApi.start({
+          from: { arrowPulse: 1 },
+          to: async (next) => {
+            await next({ arrowPulse: 1.3 })
+            await next({ arrowPulse: 1 })
+          },
+          loop: true,
+        })
+      }
+
+      const timeoutId = setTimeout(startPulse, 200)
+      return () => {
+        clearTimeout(timeoutId)
+        arrowApi.stop()
+      }
+    } else {
+      arrowApi.set({ arrowPulse: 1 })
+    }
+  }, [showDirectionIndicator, direction, isCurrentStep, arrowApi])
+
+  // Render bead shape
+  const renderShape = () => {
+    const halfSize = size / 2
+
+    // Determine fill - use gradient for realistic mode, otherwise use color
+    let fillValue = customStyle?.fill || color
+    if (enhanced3d === 'realistic' && columnIndex !== undefined) {
+      if (bead.type === 'heaven') {
+        fillValue = `url(#bead-gradient-${columnIndex}-heaven)`
+      } else {
+        fillValue = `url(#bead-gradient-${columnIndex}-earth-${bead.position})`
+      }
+    }
+
+    // Calculate opacity based on state and settings
+    let opacity: number
+    if (customStyle?.opacity !== undefined) {
+      // Custom opacity always takes precedence
+      opacity = customStyle.opacity
+    } else if (bead.active) {
+      // Active beads are always full opacity
+      opacity = 1
+    } else if (hideInactiveBeads && effectiveHoverState) {
+      // Inactive beads that are hidden but being hovered show at low opacity
+      opacity = 0.3
+    } else if (hideInactiveBeads) {
+      // Inactive beads that are hidden and not hovered are invisible (handled below)
+      opacity = 0
+    } else {
+      // Inactive beads when hideInactiveBeads is false are full opacity
+      opacity = 1
+    }
+
+    const stroke = customStyle?.stroke || '#000'
+    const strokeWidth = customStyle?.strokeWidth || 0.5
+
+    switch (shape) {
+      case 'diamond':
+        return (
+          <polygon
+            points={`${size * 0.7},0 ${size * 1.4},${halfSize} ${size * 0.7},${size} 0,${halfSize}`}
+            fill={fillValue}
+            stroke={stroke}
+            strokeWidth={strokeWidth}
+            opacity={opacity}
+          />
+        )
+      case 'square':
+        return (
+          <rect
+            width={size}
+            height={size}
+            fill={fillValue}
+            stroke={stroke}
+            strokeWidth={strokeWidth}
+            rx="1"
+            opacity={opacity}
+          />
+        )
+      case 'circle':
+      default:
+        return (
+          <circle
+            cx={halfSize}
+            cy={halfSize}
+            r={halfSize}
+            fill={fillValue}
+            stroke={stroke}
+            strokeWidth={strokeWidth}
+            opacity={opacity}
+          />
+        )
+    }
+  }
+
+  // Calculate offsets for shape positioning
+  const getXOffset = () => {
+    return shape === 'diamond' ? size * 0.7 : size / 2
+  }
+
+  const getYOffset = () => {
+    return size / 2
+  }
+
+  // Use animated.g if animations enabled, otherwise regular g
+  const GElement = enableAnimation ? animated.g : 'g'
+  const DirectionIndicatorG =
+    enableAnimation && showDirectionIndicator && direction ? animated.g : 'g'
+
+  // Build style object
+  // Show pointer cursor on hidden beads so users know they can interact
+  const shouldShowCursor = bead.active || !hideInactiveBeads || effectiveHoverState
+  const cursor = shouldShowCursor ? (enableGestures ? 'grab' : onClick ? 'pointer' : 'default') : 'default'
+
+  const beadStyle: any = enableAnimation
+    ? {
+        transform: to(
+          [springX, springY],
+          (sx, sy) => `translate(${sx - getXOffset()}px, ${sy - getYOffset()}px)`
+        ),
+        cursor,
+        touchAction: 'none' as const,
+        transition: 'opacity 0.2s ease-in-out',
+        pointerEvents: 'auto' as const, // Ensure hidden beads can still be hovered
+      }
+    : {
+        transform: `translate(${x - getXOffset()}px, ${y - getYOffset()}px)`,
+        cursor,
+        touchAction: 'none' as const,
+        transition: 'opacity 0.2s ease-in-out',
+        pointerEvents: 'auto' as const, // Ensure hidden beads can still be hovered
+      }
+
+  const handleClick = (event: React.MouseEvent) => {
+    // Prevent click if gesture was triggered
+    if (gestureStateRef.current.hasGestureTriggered) {
+      event.preventDefault()
+      return
+    }
+    onClick?.(bead, event)
+  }
+
+  const handleMouseEnter = (e: React.MouseEvent) => {
+    setIsHovered(true)
+    onMouseEnter?.(bead, e as any)
+  }
+
+  const handleMouseLeave = (e: React.MouseEvent) => {
+    setIsHovered(false)
+    onMouseLeave?.(bead, e as any)
+  }
+
+  return (
+    <>
+      <GElement
+        className={`abacus-bead ${bead.active ? 'active' : 'inactive'} ${hideInactiveBeads && !bead.active ? 'hidden-inactive' : ''}`}
+        data-testid={`bead-place-${bead.placeValue}-${bead.type}${bead.type === 'earth' ? `-pos-${bead.position}` : ''}`}
+        style={beadStyle}
+        {...bind()}
+        onClick={handleClick}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        ref={(el) => onRef?.(bead, el as any)}
+      >
+        {renderShape()}
+      </GElement>
+
+      {/* Direction indicator for tutorials */}
+      {showDirectionIndicator && direction && (
+        <DirectionIndicatorG
+          className="direction-indicator"
+          style={
+            (enableAnimation
+              ? {
+                  transform: to(
+                    [springX, springY, arrowPulse],
+                    (sx, sy, pulse) => {
+                      const centerX = shape === 'diamond' ? size * 0.7 : size / 2
+                      const centerY = size / 2
+                      // Scale from center: translate to position, then translate to center, scale, translate back
+                      return `translate(${sx}px, ${sy}px) scale(${pulse}) translate(${-centerX}px, ${-centerY}px)`
+                    }
+                  ),
+                  pointerEvents: 'none' as const,
+                }
+              : {
+                  transform: `translate(${x}px, ${y}px) translate(${-(shape === 'diamond' ? size * 0.7 : size / 2)}px, ${-size / 2}px)`,
+                  pointerEvents: 'none' as const,
+                }) as any
+          }
+        >
+          <text
+            x={shape === 'diamond' ? size * 0.7 : size / 2}
+            y={size / 2}
+            textAnchor="middle"
+            dy=".35em"
+            fontSize={size * 0.7}
+            fill="#fbbf24"
+            fontWeight="bold"
+            stroke="#000"
+            strokeWidth="1.5"
+            paintOrder="stroke"
+          >
+            {bead.type === 'heaven'
+              ? (direction === 'activate' ? '↓' : '↑')
+              : (direction === 'activate' ? '↑' : '↓')}
+          </text>
+        </DirectionIndicatorG>
+      )}
+    </>
+  )
+}

packages/abacus-react/src/AbacusSVGRenderer.tsx

@@ -0,0 +1,383 @@
+/**
+ * AbacusSVGRenderer - Shared SVG rendering component (Core Architecture)
+ *
+ * This is the **single SVG renderer** used by both AbacusStatic and AbacusReact to guarantee
+ * pixel-perfect visual consistency. It implements dependency injection to support different
+ * bead components while maintaining identical layout.
+ *
+ * ## Architecture Role:
+ * ```
+ * AbacusStatic + AbacusReact
+ *         ↓
+ * calculateStandardDimensions() ← Single source for all layout dimensions
+ *         ↓
+ * AbacusSVGRenderer ← This component (shared structure)
+ *         ↓
+ * calculateBeadPosition() ← Exact positioning for every bead
+ *         ↓
+ * BeadComponent (injected) ← AbacusStaticBead OR AbacusAnimatedBead
+ * ```
+ *
+ * ## Key Features:
+ * - ✅ No "use client" directive - works in React Server Components
+ * - ✅ No hooks or state - pure rendering from props
+ * - ✅ Dependency injection for bead components
+ * - ✅ Supports 3D gradients, background glows, overlays (via props)
+ * - ✅ Same props → same dimensions → same positions → same layout
+ *
+ * ## Why This Matters:
+ * Before this architecture, AbacusStatic and AbacusReact had ~700 lines of duplicate
+ * SVG rendering code with separate dimension calculations. This led to layout inconsistencies.
+ * Now they share this single renderer, eliminating duplication and guaranteeing consistency.
+ */
+
+import React from 'react'
+import type { AbacusLayoutDimensions } from './AbacusUtils'
+import type { BeadConfig, AbacusCustomStyles, ValidPlaceValues } from './AbacusReact'
+import { numberToAbacusState, calculateBeadPosition, type AbacusState } from './AbacusUtils'
+
+/**
+ * Props that bead components must accept
+ */
+export interface BeadComponentProps {
+  bead: BeadConfig
+  x: number
+  y: number
+  size: number
+  shape: 'circle' | 'diamond' | 'square'
+  color: string
+  hideInactiveBeads: boolean
+  customStyle?: {
+    fill?: string
+    stroke?: string
+    strokeWidth?: number
+    opacity?: number
+  }
+  onClick?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onMouseEnter?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onMouseLeave?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onRef?: (bead: BeadConfig, element: SVGElement | null) => void
+}
+
+/**
+ * Props for the SVG renderer
+ */
+export interface AbacusSVGRendererProps {
+  // Core data
+  value: number | bigint
+  columns: number
+  state: AbacusState
+  beadConfigs: BeadConfig[][]  // Array of columns, each containing beads
+
+  // Layout
+  dimensions: AbacusLayoutDimensions
+  scaleFactor?: number
+
+  // Appearance
+  beadShape: 'circle' | 'diamond' | 'square'
+  colorScheme: string
+  colorPalette: string
+  hideInactiveBeads: boolean
+  frameVisible: boolean
+  showNumbers: boolean
+  customStyles?: AbacusCustomStyles
+  interactive?: boolean  // Enable interactive CSS styles
+
+  // Tutorial features
+  highlightColumns?: number[]
+  columnLabels?: string[]
+
+  // 3D Enhancement (optional - only used by AbacusReact)
+  defsContent?: React.ReactNode  // Custom defs content (gradients, patterns, etc.)
+
+  // Additional content (overlays, etc.)
+  children?: React.ReactNode  // Rendered at the end of the SVG
+
+  // Dependency injection
+  BeadComponent: React.ComponentType<any>  // Accept any bead component (base props + extra props)
+  getBeadColor: (bead: BeadConfig, totalColumns: number, colorScheme: string, colorPalette: string) => string
+
+  // Event handlers (optional, passed through to beads)
+  onBeadClick?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onBeadMouseEnter?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onBeadMouseLeave?: (bead: BeadConfig, event?: React.MouseEvent) => void
+  onBeadRef?: (bead: BeadConfig, element: SVGElement | null) => void
+
+  // Extra props calculator (for animations, gestures, etc.)
+  // This function is called for each bead to get extra props
+  calculateExtraBeadProps?: (bead: BeadConfig, baseProps: BeadComponentProps) => Record<string, any>
+}
+
+/**
+ * Pure SVG renderer for abacus
+ * Uses dependency injection to support both static and animated beads
+ */
+export function AbacusSVGRenderer({
+  value,
+  columns,
+  state,
+  beadConfigs,
+  dimensions,
+  scaleFactor = 1,
+  beadShape,
+  colorScheme,
+  colorPalette,
+  hideInactiveBeads,
+  frameVisible,
+  showNumbers,
+  customStyles,
+  interactive = false,
+  highlightColumns = [],
+  columnLabels = [],
+  defsContent,
+  children,
+  BeadComponent,
+  getBeadColor,
+  onBeadClick,
+  onBeadMouseEnter,
+  onBeadMouseLeave,
+  onBeadRef,
+  calculateExtraBeadProps,
+}: AbacusSVGRendererProps) {
+  const { width, height, rodSpacing, barY, beadSize, barThickness, labelHeight, numbersHeight } = dimensions
+
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={width * scaleFactor}
+      height={height * scaleFactor}
+      viewBox={`0 0 ${width} ${height}`}
+      className={`abacus-svg ${hideInactiveBeads ? 'hide-inactive-mode' : ''} ${interactive ? 'interactive' : ''}`}
+      style={{ overflow: 'visible', display: 'block' }}
+    >
+      <defs>
+        <style>{`
+          /* CSS-based opacity system for hidden inactive beads */
+          .abacus-bead {
+            transition: opacity 0.2s ease-in-out;
+          }
+
+          /* Hidden inactive beads are invisible by default */
+          .hide-inactive-mode .abacus-bead.hidden-inactive {
+            opacity: 0;
+          }
+
+          /* Interactive abacus: When hovering over the abacus, hidden inactive beads become semi-transparent */
+          .abacus-svg.hide-inactive-mode.interactive:hover .abacus-bead.hidden-inactive {
+            opacity: 0.5;
+          }
+
+          /* Interactive abacus: When hovering over a specific hidden inactive bead, it becomes fully visible */
+          .hide-inactive-mode.interactive .abacus-bead.hidden-inactive:hover {
+            opacity: 1 !important;
+          }
+
+          /* Non-interactive abacus: Hidden inactive beads always stay at opacity 0 */
+          .abacus-svg.hide-inactive-mode:not(.interactive) .abacus-bead.hidden-inactive {
+            opacity: 0 !important;
+          }
+        `}</style>
+
+        {/* Custom defs content (for 3D gradients, patterns, etc.) */}
+        {defsContent}
+      </defs>
+
+      {/* Background glow effects - rendered behind everything */}
+      {Array.from({ length: columns }, (_, colIndex) => {
+        const placeValue = columns - 1 - colIndex
+        const columnStyles = customStyles?.columns?.[colIndex]
+        const backgroundGlow = columnStyles?.backgroundGlow
+
+        if (!backgroundGlow) return null
+
+        const x = colIndex * rodSpacing + rodSpacing / 2
+        const glowWidth = rodSpacing + (backgroundGlow.spread || 0)
+        const glowHeight = height + (backgroundGlow.spread || 0)
+
+        return (
+          <rect
+            key={`background-glow-pv${placeValue}`}
+            x={x - glowWidth / 2}
+            y={-(backgroundGlow.spread || 0) / 2}
+            width={glowWidth}
+            height={glowHeight}
+            fill={backgroundGlow.fill || 'rgba(59, 130, 246, 0.2)'}
+            filter={backgroundGlow.blur ? `blur(${backgroundGlow.blur}px)` : 'none'}
+            opacity={backgroundGlow.opacity ?? 0.6}
+            rx={8}
+            style={{ pointerEvents: 'none' }}
+          />
+        )
+      })}
+
+      {/* Column highlights */}
+      {highlightColumns.map((colIndex) => {
+        if (colIndex < 0 || colIndex >= columns) return null
+
+        const x = colIndex * rodSpacing + rodSpacing / 2
+        const highlightWidth = rodSpacing * 0.9
+        const highlightHeight = height - labelHeight - numbersHeight
+
+        return (
+          <rect
+            key={`column-highlight-${colIndex}`}
+            x={x - highlightWidth / 2}
+            y={labelHeight}
+            width={highlightWidth}
+            height={highlightHeight}
+            fill="rgba(59, 130, 246, 0.15)"
+            stroke="rgba(59, 130, 246, 0.4)"
+            strokeWidth={2}
+            rx={6}
+            style={{ pointerEvents: 'none' }}
+          />
+        )
+      })}
+
+      {/* Column labels */}
+      {columnLabels.map((label, colIndex) => {
+        if (!label || colIndex >= columns) return null
+
+        const x = colIndex * rodSpacing + rodSpacing / 2
+
+        return (
+          <text
+            key={`column-label-${colIndex}`}
+            x={x}
+            y={labelHeight / 2 + 5}
+            textAnchor="middle"
+            fontSize="14"
+            fontWeight="600"
+            fill="rgba(0, 0, 0, 0.7)"
+            style={{ pointerEvents: 'none', userSelect: 'none' }}
+          >
+            {label}
+          </text>
+        )
+      })}
+
+      {/* Rods (column posts) */}
+      {frameVisible && beadConfigs.map((_, colIndex) => {
+        const placeValue = columns - 1 - colIndex
+        const x = colIndex * rodSpacing + rodSpacing / 2
+
+        // Apply custom column post styling (column-specific overrides global)
+        const columnStyles = customStyles?.columns?.[colIndex]
+        const globalColumnPosts = customStyles?.columnPosts
+        const rodStyle = {
+          fill: columnStyles?.columnPost?.fill || globalColumnPosts?.fill || 'rgb(0, 0, 0, 0.1)',
+          stroke: columnStyles?.columnPost?.stroke || globalColumnPosts?.stroke || 'none',
+          strokeWidth: columnStyles?.columnPost?.strokeWidth ?? globalColumnPosts?.strokeWidth ?? 0,
+          opacity: columnStyles?.columnPost?.opacity ?? globalColumnPosts?.opacity ?? 1,
+        }
+
+        return (
+          <rect
+            key={`rod-pv${placeValue}`}
+            x={x - dimensions.rodWidth / 2}
+            y={labelHeight}
+            width={dimensions.rodWidth}
+            height={height - labelHeight - numbersHeight}
+            fill={rodStyle.fill}
+            stroke={rodStyle.stroke}
+            strokeWidth={rodStyle.strokeWidth}
+            opacity={rodStyle.opacity}
+            className="column-post"
+          />
+        )
+      })}
+
+      {/* Reckoning bar */}
+      {frameVisible && (
+        <rect
+          x={0}
+          y={barY}
+          width={columns * rodSpacing}
+          height={barThickness}
+          fill={customStyles?.reckoningBar?.fill || 'rgb(0, 0, 0, 0.15)'}
+          stroke={customStyles?.reckoningBar?.stroke || 'rgba(0, 0, 0, 0.3)'}
+          strokeWidth={customStyles?.reckoningBar?.strokeWidth || 2}
+          opacity={customStyles?.reckoningBar?.opacity ?? 1}
+        />
+      )}
+
+      {/* Beads - delegated to injected component */}
+      {beadConfigs.map((columnBeads, colIndex) => {
+        const placeValue = columns - 1 - colIndex
+        // Get column state for inactive earth bead positioning
+        const columnState = state[placeValue] || { heavenActive: false, earthActive: 0 }
+
+        return (
+          <g key={`column-${colIndex}`}>
+            {columnBeads.map((bead, beadIndex) => {
+              // Calculate position using shared utility with column state for accurate positioning
+              const position = calculateBeadPosition(bead, dimensions, { earthActive: columnState.earthActive })
+              const color = getBeadColor(bead, columns, colorScheme, colorPalette)
+
+              // Get custom style for this specific bead
+              const customStyle =
+                bead.type === 'heaven'
+                  ? customStyles?.heavenBeads
+                  : customStyles?.earthBeads
+
+              // Build base props
+              const baseProps: BeadComponentProps = {
+                bead,
+                x: position.x,
+                y: position.y,
+                size: beadSize,
+                shape: beadShape,
+                color,
+                hideInactiveBeads,
+                customStyle,
+                onClick: onBeadClick,
+                onMouseEnter: onBeadMouseEnter,
+                onMouseLeave: onBeadMouseLeave,
+                onRef: onBeadRef,
+              }
+
+              // Calculate extra props if provided (for animations, etc.)
+              const extraProps = calculateExtraBeadProps?.(bead, baseProps) || {}
+
+              return (
+                <BeadComponent
+                  key={`bead-pv${bead.placeValue}-${bead.type}-${bead.position}`}
+                  {...baseProps}
+                  {...extraProps}
+                />
+              )
+            })}
+          </g>
+        )
+      })}
+
+      {/* Column numbers */}
+      {showNumbers && beadConfigs.map((_, colIndex) => {
+        const placeValue = columns - 1 - colIndex
+        const columnState = state[placeValue] || { heavenActive: false, earthActive: 0 }
+        const digit = (columnState.heavenActive ? 5 : 0) + columnState.earthActive
+        const x = colIndex * rodSpacing + rodSpacing / 2
+
+        return (
+          <text
+            key={`number-${colIndex}`}
+            x={x}
+            y={height - numbersHeight / 2 + 5}
+            textAnchor="middle"
+            fontSize={customStyles?.numerals?.fontSize || '16px'}
+            fontWeight={customStyles?.numerals?.fontWeight || '600'}
+            fill={customStyles?.numerals?.color || 'rgba(0, 0, 0, 0.8)'}
+            style={{ pointerEvents: 'none', userSelect: 'none' }}
+          >
+            {digit}
+          </text>
+        )
+      })}
+
+      {/* Additional content (overlays, numbers, etc.) */}
+      {children}
+    </svg>
+  )
+}
+
+export default AbacusSVGRenderer

packages/abacus-react/src/AbacusStatic.stories.tsx

@@ -7,20 +7,39 @@ import { ABACUS_THEMES } from './AbacusThemes'
  *
  * ## Key Features:
  * - ✅ Works in React Server Components (no "use client")
- * - ✅ Shares core utilities with AbacusReact (numberToAbacusState, color logic)
+ * - ✅ **Identical layout to AbacusReact** - same props = same exact SVG output
  * - ✅ No animations, hooks, or client-side JavaScript
  * - ✅ Lightweight rendering for static displays
  *
- * ## Shared Code (No Duplication!):
- * - Uses `numberToAbacusState()` from AbacusUtils
- * - Uses same color scheme logic as AbacusReact
- * - Uses same bead positioning concepts
- * - Accepts same `customStyles` prop structure
+ * ## Shared Architecture (Zero Duplication!):
+ * Both AbacusStatic and AbacusReact use the **exact same rendering pipeline**:
+ *
+ * ```
+ * calculateStandardDimensions() → AbacusSVGRenderer → calculateBeadPosition()
+ *                                        ↓
+ *                    ┌───────────────────┴───────────────────┐
+ *                    ↓                                       ↓
+ *             AbacusStaticBead                    AbacusAnimatedBead
+ *             (Simple SVG)                        (react-spring)
+ * ```
+ *
+ * - `calculateStandardDimensions()` - Single source of truth for layout (beadSize, gaps, bar position, etc.)
+ * - `AbacusSVGRenderer` - Shared SVG structure with dependency injection for bead components
+ * - `calculateBeadPosition()` - Exact positioning formulas used by both variants
+ * - `AbacusStaticBead` - RSC-compatible simple SVG shapes (this component)
+ * - `AbacusAnimatedBead` - Client component with animations (AbacusReact)
+ *
+ * ## Visual Consistency Guarantee:
+ * Both AbacusStatic and AbacusReact produce **pixel-perfect identical output** for the same props.
+ * This ensures previews match interactive versions, PDFs match web displays, etc.
+ *
+ * **Architecture benefit:** ~560 lines of duplicate code eliminated. Same props = same dimensions = same positions = same layout.
  *
  * ## When to Use:
  * - React Server Components (Next.js App Router)
  * - Static site generation
  * - Non-interactive previews
+ * - PDF generation
  * - Server-side rendering without hydration
  */
 const meta = {

packages/abacus-react/src/AbacusStatic.tsx

@@ -1,12 +1,14 @@
 /**
  * AbacusStatic - Server Component compatible static abacus
  *
- * Shares core logic with AbacusReact but uses static rendering without hooks/animations.
- * Reuses: numberToAbacusState, getBeadColor logic, positioning calculations
- * Different: No hooks, no animations, no interactions, simplified rendering
+ * Shares layout and rendering with AbacusReact through dependency injection.
+ * Uses standard dimensions to ensure same props = same exact visual output.
+ * Reuses: AbacusSVGRenderer for structure, shared dimension/position calculators
+ * Different: No hooks, no animations, no interactions, simplified bead rendering
  */
 
-import { numberToAbacusState } from './AbacusUtils'
+import { numberToAbacusState, calculateStandardDimensions } from './AbacusUtils'
+import { AbacusSVGRenderer } from './AbacusSVGRenderer'
 import { AbacusStaticBead } from './AbacusStaticBead'
 import type {
   AbacusCustomStyles,
@@ -30,7 +32,7 @@ export interface AbacusStaticConfig {
   columnLabels?: string[]
 }
 
-// Shared color logic from AbacusReact (simplified for static use)
+// Shared color logic (matches AbacusReact)
 function getBeadColor(
   bead: BeadConfig,
   totalColumns: number,
@@ -87,37 +89,6 @@ function getBeadColor(
   return '#3b82f6'
 }
 
-// Calculate bead positions (simplified from AbacusReact)
-function calculateBeadPosition(
-  bead: BeadConfig,
-  dimensions: { beadSize: number; rodSpacing: number; heavenY: number; earthY: number; barY: number; totalColumns: number }
-): { x: number; y: number } {
-  const { beadSize, rodSpacing, heavenY, earthY, barY, totalColumns } = dimensions
-
-  // X position based on place value (rightmost = ones place)
-  const columnIndex = totalColumns - 1 - bead.placeValue
-  const x = columnIndex * rodSpacing + rodSpacing / 2
-
-  // Y position based on bead type and active state
-  if (bead.type === 'heaven') {
-    // Heaven bead: if active, near bar; if inactive, at top
-    const y = bead.active ? barY - beadSize - 5 : heavenY
-    return { x, y }
-  } else {
-    // Earth bead: if active, stack up from bar; if inactive, at bottom
-    const earthSpacing = beadSize + 4
-    if (bead.active) {
-      // Active earth beads stack upward from the bar
-      const y = barY + beadSize / 2 + 10 + bead.position * earthSpacing
-      return { x, y }
-    } else {
-      // Inactive earth beads rest at the bottom
-      const y = earthY + (bead.position - 2) * earthSpacing
-      return { x, y }
-    }
-  }
-}
-
 /**
  * AbacusStatic - Pure static abacus component (Server Component compatible)
  */
@@ -175,191 +146,38 @@ export function AbacusStatic({
     beadConfigs.push(beads)
   }
 
-  // Calculate dimensions (matching AbacusReact)
-  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 = effectiveColumns * rodSpacing + padding * 2
-  const height = heavenHeight + earthHeight + barHeight + padding * 2 + numberHeightCalc + labelHeight
-
-  const dimensions = {
-    width,
-    height,
-    beadSize,
-    rodSpacing,
-    heavenY: padding + labelHeight + heavenHeight / 3,
-    earthY: padding + labelHeight + heavenHeight + barHeight + earthHeight * 0.7,
-    barY: padding + labelHeight + heavenHeight,
-    padding,
-    totalColumns: effectiveColumns,
-  }
+  // Calculate standard dimensions (same as AbacusReact!)
+  const dimensions = calculateStandardDimensions({
+    columns: effectiveColumns,
+    scaleFactor,
+    showNumbers: !!showNumbers,
+    columnLabels,
+  })
 
   // Compact mode hides frame
   const effectiveFrameVisible = compact ? false : frameVisible
 
+  // Use shared renderer with static bead component
   return (
-    <svg
-      width={width * scaleFactor}
-      height={height * scaleFactor}
-      viewBox={`0 0 ${width} ${height}`}
-      className={`abacus-svg ${hideInactiveBeads ? 'hide-inactive-mode' : ''}`}
-      style={{ overflow: 'visible', display: 'block' }}
-    >
-      <defs>
-        <style>{`
-          .abacus-bead {
-            transition: opacity 0.2s ease-in-out;
-          }
-          .hide-inactive-mode .abacus-bead.hidden-inactive {
-            opacity: 0 !important;
-          }
-        `}</style>
-      </defs>
-
-      {/* Column highlights */}
-      {highlightColumns.map((colIndex) => {
-        if (colIndex < 0 || colIndex >= effectiveColumns) return null
-
-        const x = colIndex * rodSpacing + rodSpacing / 2 + padding
-        const highlightWidth = rodSpacing * 0.9
-        const highlightHeight = height - padding * 2 - numberHeightCalc - labelHeight
-
-        return (
-          <rect
-            key={`column-highlight-${colIndex}`}
-            x={x - highlightWidth / 2}
-            y={padding + labelHeight}
-            width={highlightWidth}
-            height={highlightHeight}
-            fill="rgba(59, 130, 246, 0.15)"
-            stroke="rgba(59, 130, 246, 0.4)"
-            strokeWidth={2}
-            rx={6}
-            style={{ pointerEvents: 'none' }}
-          />
-        )
-      })}
-
-      {/* Column labels */}
-      {columnLabels.map((label, colIndex) => {
-        if (!label || colIndex >= effectiveColumns) return null
-
-        const x = colIndex * rodSpacing + rodSpacing / 2 + padding
-
-        return (
-          <text
-            key={`column-label-${colIndex}`}
-            x={x}
-            y={padding + 15}
-            textAnchor="middle"
-            fontSize="14"
-            fontWeight="600"
-            fill="rgba(0, 0, 0, 0.7)"
-            style={{ pointerEvents: 'none', userSelect: 'none' }}
-          >
-            {label}
-          </text>
-        )
-      })}
-
-      {/* Rods (column posts) */}
-      {effectiveFrameVisible && beadConfigs.map((_, colIndex) => {
-        const x = colIndex * rodSpacing + rodSpacing / 2 + padding
-
-        return (
-          <rect
-            key={`rod-${colIndex}`}
-            x={x - 3}
-            y={padding + labelHeight}
-            width={6}
-            height={heavenHeight + earthHeight + barHeight}
-            fill={customStyles?.columnPosts?.fill || 'rgb(0, 0, 0, 0.1)'}
-            stroke={customStyles?.columnPosts?.stroke || 'rgba(0, 0, 0, 0.2)'}
-            strokeWidth={customStyles?.columnPosts?.strokeWidth || 1}
-            opacity={customStyles?.columnPosts?.opacity ?? 1}
-          />
-        )
-      })}
-
-      {/* Reckoning bar */}
-      {effectiveFrameVisible && (
-        <rect
-          x={padding}
-          y={dimensions.barY}
-          width={effectiveColumns * rodSpacing}
-          height={barHeight}
-          fill={customStyles?.reckoningBar?.fill || 'rgb(0, 0, 0, 0.15)'}
-          stroke={customStyles?.reckoningBar?.stroke || 'rgba(0, 0, 0, 0.3)'}
-          strokeWidth={customStyles?.reckoningBar?.strokeWidth || 2}
-          opacity={customStyles?.reckoningBar?.opacity ?? 1}
-        />
-      )}
-
-      {/* Beads */}
-      {beadConfigs.map((columnBeads, colIndex) => {
-        const placeValue = effectiveColumns - 1 - colIndex
-
-        return (
-          <g key={`column-${colIndex}`}>
-            {columnBeads.map((bead, beadIndex) => {
-              const position = calculateBeadPosition(bead, dimensions)
-
-              // Adjust X for padding
-              position.x += padding
-
-              const color = getBeadColor(bead, effectiveColumns, colorScheme, colorPalette)
-
-              return (
-                <AbacusStaticBead
-                  key={`bead-${colIndex}-${beadIndex}`}
-                  bead={bead}
-                  x={position.x}
-                  y={position.y}
-                  size={beadSize}
-                  shape={beadShape}
-                  color={color}
-                  hideInactiveBeads={hideInactiveBeads}
-                  customStyle={
-                    bead.type === 'heaven'
-                      ? customStyles?.heavenBeads
-                      : customStyles?.earthBeads
-                  }
-                />
-              )
-            })}
-          </g>
-        )
-      })}
-
-      {/* Column numbers */}
-      {showNumbers && beadConfigs.map((_, colIndex) => {
-        const placeValue = effectiveColumns - 1 - colIndex
-        const columnState = state[placeValue] || { heavenActive: false, earthActive: 0 }
-        const digit = (columnState.heavenActive ? 5 : 0) + columnState.earthActive
-        const x = colIndex * rodSpacing + rodSpacing / 2 + padding
-
-        return (
-          <text
-            key={`number-${colIndex}`}
-            x={x}
-            y={height - padding + 5}
-            textAnchor="middle"
-            fontSize={customStyles?.numerals?.fontSize || 16}
-            fontWeight={customStyles?.numerals?.fontWeight || '600'}
-            fill={customStyles?.numerals?.color || 'rgba(0, 0, 0, 0.8)'}
-            style={{ pointerEvents: 'none', userSelect: 'none' }}
-          >
-            {digit}
-          </text>
-        )
-      })}
-    </svg>
+    <AbacusSVGRenderer
+      value={value}
+      columns={effectiveColumns}
+      state={state}
+      beadConfigs={beadConfigs}
+      dimensions={dimensions}
+      scaleFactor={scaleFactor}
+      beadShape={beadShape}
+      colorScheme={colorScheme}
+      colorPalette={colorPalette}
+      hideInactiveBeads={hideInactiveBeads}
+      frameVisible={effectiveFrameVisible}
+      showNumbers={!!showNumbers}
+      customStyles={customStyles}
+      highlightColumns={highlightColumns}
+      columnLabels={columnLabels}
+      BeadComponent={AbacusStaticBead}
+      getBeadColor={getBeadColor}
+    />
   )
 }
 

packages/abacus-react/src/AbacusStaticBead.tsx

@@ -91,6 +91,7 @@ export function AbacusStaticBead({
   return (
     <g
       className={`abacus-bead ${bead.active ? 'active' : 'inactive'} ${hideInactiveBeads && !bead.active ? 'hidden-inactive' : ''}`}
+      data-testid={`bead-place-${bead.placeValue}-${bead.type}${bead.type === 'earth' ? `-pos-${bead.position}` : ''}`}
       transform={transform}
       style={{ transition: 'opacity 0.2s ease-in-out' }}
     >

packages/abacus-react/src/AbacusUtils.ts

@@ -356,3 +356,207 @@ function getPlaceName(place: number): string {
       return `place ${place} column`
   }
 }
+
+/**
+ * Complete layout dimensions for abacus rendering
+ * Used by both static and dynamic rendering to ensure identical layouts
+ */
+export interface AbacusLayoutDimensions {
+  // SVG canvas size
+  width: number
+  height: number
+
+  // Bead and spacing
+  beadSize: number
+  rodSpacing: number  // Same as columnSpacing
+  rodWidth: number
+  barThickness: number
+
+  // Gaps and positioning
+  heavenEarthGap: number  // Gap between heaven and earth sections (where bar sits)
+  activeGap: number       // Gap between active beads and reckoning bar
+  inactiveGap: number     // Gap between inactive beads and active beads/bar
+  adjacentSpacing: number // Minimal spacing for adjacent beads of same type
+
+  // Key Y positions (absolute coordinates)
+  barY: number           // Y position of reckoning bar
+  heavenY: number        // Y position where inactive heaven beads rest
+  earthY: number         // Y position where inactive earth beads rest
+
+  // Padding and extras
+  padding: number
+  labelHeight: number
+  numbersHeight: number
+
+  // Derived values
+  totalColumns: number
+}
+
+/**
+ * Calculate standard layout dimensions for abacus rendering
+ * This ensures both static and dynamic rendering use identical geometry
+ * Same props = same exact visual output
+ *
+ * @param columns - Number of columns in the abacus
+ * @param scaleFactor - Size multiplier (default: 1)
+ * @param showNumbers - Whether numbers are shown below columns
+ * @param columnLabels - Array of column labels (if any)
+ * @returns Complete layout dimensions object
+ */
+export function calculateStandardDimensions({
+  columns,
+  scaleFactor = 1,
+  showNumbers = false,
+  columnLabels = [],
+}: {
+  columns: number
+  scaleFactor?: number
+  showNumbers?: boolean
+  columnLabels?: string[]
+}): AbacusLayoutDimensions {
+  // Standard dimensions - used by both AbacusStatic and AbacusReact
+  const rodWidth = 3 * scaleFactor
+  const beadSize = 12 * scaleFactor
+  const adjacentSpacing = 0.5 * scaleFactor
+  const columnSpacing = 25 * scaleFactor
+  const heavenEarthGap = 30 * scaleFactor
+  const barThickness = 2 * scaleFactor
+
+  // Positioning gaps
+  const activeGap = 1 * scaleFactor
+  const inactiveGap = 8 * scaleFactor
+
+  // Calculate total dimensions
+  const totalWidth = columns * columnSpacing
+  const baseHeight = heavenEarthGap + 5 * (beadSize + 4 * scaleFactor) + 10 * scaleFactor
+
+  // Extra spacing
+  const numbersSpace = showNumbers ? 40 * scaleFactor : 0
+  const labelSpace = columnLabels.length > 0 ? 30 * scaleFactor : 0
+  const padding = 0 // No padding - keeps layout clean
+
+  const totalHeight = baseHeight + numbersSpace + labelSpace
+
+  // Key Y positions - bar is at heavenEarthGap from top
+  const barY = heavenEarthGap + labelSpace
+  const heavenY = labelSpace + activeGap  // Top area for inactive heaven beads
+  const earthY = barY + barThickness + (4 * beadSize) + activeGap + inactiveGap  // Bottom area for inactive earth
+
+  return {
+    width: totalWidth,
+    height: totalHeight,
+    beadSize,
+    rodSpacing: columnSpacing,
+    rodWidth,
+    barThickness,
+    heavenEarthGap,
+    activeGap,
+    inactiveGap,
+    adjacentSpacing,
+    barY,
+    heavenY,
+    earthY,
+    padding,
+    labelHeight: labelSpace,
+    numbersHeight: numbersSpace,
+    totalColumns: columns,
+  }
+}
+
+/**
+ * @deprecated Use calculateStandardDimensions instead for full layout info
+ * This function only returns width/height for backward compatibility
+ */
+export function calculateAbacusDimensions({
+  columns,
+  showNumbers = true,
+  columnLabels = [],
+}: {
+  columns: number
+  showNumbers?: boolean
+  columnLabels?: string[]
+}): { width: number; height: number } {
+  // Redirect to new function for backward compatibility
+  const dims = calculateStandardDimensions({ columns, scaleFactor: 1, showNumbers, columnLabels })
+  return { width: dims.width, height: dims.height }
+}
+
+/**
+ * Simplified bead config for position calculation
+ * (Compatible with BeadConfig from AbacusReact)
+ */
+export interface BeadPositionConfig {
+  type: 'heaven' | 'earth'
+  active: boolean
+  position: number  // 0 for heaven, 0-3 for earth
+  placeValue: number
+}
+
+/**
+ * Column state needed for earth bead positioning
+ * (Required to calculate inactive earth bead positions correctly)
+ */
+export interface ColumnStateForPositioning {
+  earthActive: number  // Number of active earth beads (0-4)
+}
+
+/**
+ * Calculate the x,y position for a bead based on standard layout dimensions
+ * This ensures both static and dynamic rendering position beads identically
+ * Uses exact Typst formulas from the original implementation
+ *
+ * @param bead - Bead configuration
+ * @param dimensions - Layout dimensions from calculateStandardDimensions
+ * @param columnState - Optional column state (required for inactive earth beads)
+ * @returns Object with x and y coordinates
+ */
+export function calculateBeadPosition(
+  bead: BeadPositionConfig,
+  dimensions: AbacusLayoutDimensions,
+  columnState?: ColumnStateForPositioning
+): { x: number; y: number } {
+  const { beadSize, rodSpacing, heavenEarthGap, barThickness, activeGap, inactiveGap, adjacentSpacing, totalColumns } = dimensions
+
+  // X position based on place value (rightmost = ones place)
+  const columnIndex = totalColumns - 1 - bead.placeValue
+  const x = columnIndex * rodSpacing + rodSpacing / 2
+
+  // Y position based on bead type and active state
+  // These formulas match the original Typst implementation exactly
+  if (bead.type === 'heaven') {
+    if (bead.active) {
+      // Active heaven bead: positioned close to reckoning bar (Typst line 175)
+      const y = heavenEarthGap - beadSize / 2 - activeGap
+      return { x, y }
+    } else {
+      // Inactive heaven bead: positioned away from reckoning bar (Typst line 178)
+      const y = heavenEarthGap - inactiveGap - beadSize / 2
+      return { x, y }
+    }
+  } else {
+    // Earth bead positioning (Typst lines 249-261)
+    const earthActive = columnState?.earthActive ?? 0
+
+    if (bead.active) {
+      // Active beads: positioned near reckoning bar, adjacent beads touch (Typst line 251)
+      const y = heavenEarthGap + barThickness + activeGap + beadSize / 2 +
+                bead.position * (beadSize + adjacentSpacing)
+      return { x, y }
+    } else {
+      // Inactive beads: positioned after active beads + gap (Typst lines 254-261)
+      let y: number
+      if (earthActive > 0) {
+        // Position after the last active bead + gap, then adjacent inactive beads touch (Typst line 256)
+        y = heavenEarthGap + barThickness + activeGap + beadSize / 2 +
+            (earthActive - 1) * (beadSize + adjacentSpacing) +
+            beadSize / 2 + inactiveGap + beadSize / 2 +
+            (bead.position - earthActive) * (beadSize + adjacentSpacing)
+      } else {
+        // No active beads: position after reckoning bar + gap, adjacent inactive beads touch (Typst line 259)
+        y = heavenEarthGap + barThickness + inactiveGap + beadSize / 2 +
+            bead.position * (beadSize + adjacentSpacing)
+      }
+      return { x, y }
+    }
+  }
+}

packages/abacus-react/src/index.ts

@@ -47,6 +47,9 @@ export {
   calculateBeadDiffFromValues,
   validateAbacusValue,
   areStatesEqual,
+  calculateAbacusDimensions,
+  calculateStandardDimensions,  // NEW: Shared layout calculator
+  calculateBeadPosition,         // NEW: Bead position calculator
 } from "./AbacusUtils";
 export type {
   BeadState,
@@ -54,6 +57,8 @@ export type {
   BeadDiffResult,
   BeadDiffOutput,
   PlaceValueBasedBead,
+  AbacusLayoutDimensions,        // NEW: Complete layout dimensions type
+  BeadPositionConfig,            // NEW: Bead config for position calculation
 } from "./AbacusUtils";
 
 export { useAbacusDiff, useAbacusState } from "./AbacusHooks";

packages/abacus-react/src/static.ts

@@ -0,0 +1,18 @@
+/**
+ * Server Component compatible exports
+ * This entry point only exports components that work without "use client"
+ */
+
+export { AbacusStatic } from './AbacusStatic'
+export type { AbacusStaticConfig } from './AbacusStatic'
+export { AbacusStaticBead } from './AbacusStaticBead'
+export type { StaticBeadProps } from './AbacusStaticBead'
+
+// Re-export shared utilities that are safe for server components
+export { numberToAbacusState, calculateAbacusDimensions } from './AbacusUtils'
+export type {
+  AbacusCustomStyles,
+  BeadConfig,
+  PlaceState,
+  ValidPlaceValues,
+} from './AbacusReact'

packages/abacus-react/vite.config.ts

@@ -8,10 +8,12 @@ export default defineConfig(async () => {
     plugins: [react()],
     build: {
       lib: {
-        entry: resolve(__dirname, "src/index.ts"),
-        name: "AbacusReact",
+        entry: {
+          index: resolve(__dirname, "src/index.ts"),
+          static: resolve(__dirname, "src/static.ts"),
+        },
         formats: ["es", "cjs"],
-        fileName: (format) => `index.${format}.js`,
+        fileName: (format, entryName) => `${entryName}.${format === "es" ? "es" : "cjs"}.js`,
       },
       sourcemap: true,
       rollupOptions: {

pnpm-lock.yaml

@@ -188,6 +188,9 @@ importers:
       next-intl:
         specifier: ^4.4.0
         version: 4.4.0(next@14.2.33(@babel/core@7.28.4)(@playwright/test@1.56.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react@18.3.1)(typescript@5.9.3)
+      openscad-wasm-prebuilt:
+        specifier: ^1.2.0
+        version: 1.2.0
       python-bridge:
         specifier: ^1.1.0
         version: 1.1.0
@@ -7484,6 +7487,9 @@ packages:
     resolution: {integrity: sha512-7x81NCL719oNbsq/3mh+hVrAWmFuEYUqrq/Iw3kUzH8ReypT9QQ0BLoJS7/G9k6N81XjW4qHWtjWwe/9eLy1EQ==}
     engines: {node: '>=12'}
 
+  openscad-wasm-prebuilt@1.2.0:
+    resolution: {integrity: sha512-JfXJlopHVHvsYiVYUKYDXkg8yOkABm8zclo8zPrSRBeeICR+fitesO6NRwBdAzSdbtOYh6Scmuz/XLyhllbzYA==}
+
   optionator@0.9.4:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
@@ -17737,6 +17743,8 @@ snapshots:
       is-docker: 2.2.1
       is-wsl: 2.2.0
 
+  openscad-wasm-prebuilt@1.2.0: {}
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4