soroban-abacus-flashcards/apps/web/scripts/generateTenFrameExamples.ts

// Script to generate ten-frame example images for blog post
// Shows single problems with different ten-frame scaffolding levels
//
// REUSABLE PATTERN: This script demonstrates how to generate single-problem
// examples for blog posts using the SAME code that powers the display options
// preview in the worksheet generator UI. The generateExampleTypst function
// in src/app/api/create/worksheets/addition/example/route.ts is the single
// source of truth for rendering individual problems with display options.
//
// To generate examples for other blog posts:
// 1. Import generateTypstHelpers and generateProblemStackFunction from typstHelpers.ts
// 2. Use the generateExampleTypst pattern below with your desired options
// 3. Compile to SVG using typst
// 4. Save to public/blog/[your-post-name]/

import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import {
  generateTypstHelpers,
  generateProblemStackFunction,
} from "../src/app/create/worksheets/addition/typstHelpers";

// Output directory
const outputDir = path.join(
  process.cwd(),
  "public",
  "blog",
  "ten-frame-examples",
);

// Ensure output directory exists
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}

interface ExampleOptions {
  showCarryBoxes?: boolean;
  showAnswerBoxes?: boolean;
  showPlaceValueColors?: boolean;
  showTenFrames?: boolean;
  showProblemNumbers?: boolean;
  transparentBackground?: boolean;
  fontSize?: number;
  addend1: number;
  addend2: number;
}

/**
 * Generate a single compact problem example
 * This is the SAME logic used by the API route for display option previews
 * Extracted here so we can generate static examples for blog posts
 */
function generateExampleTypst(config: ExampleOptions): string {
  const a = config.addend1;
  const b = config.addend2;
  const fontSize = config.fontSize || 16;
  const cellSize = 0.45; // Slightly larger for blog examples vs UI previews (0.35)

  // Boolean flags matching worksheet generator
  const showCarries = config.showCarryBoxes ?? false;
  const showAnswers = config.showAnswerBoxes ?? false;
  const showColors = config.showPlaceValueColors ?? false;
  const showNumbers = config.showProblemNumbers ?? false;
  const showTenFrames = config.showTenFrames ?? false;
  const showTenFramesForAll = false; // Not used for blog examples
  const transparentBg = config.transparentBackground ?? false;

  return String.raw`
#set page(width: auto, height: auto, margin: 12pt, fill: ${transparentBg ? "none" : "white"})
#set text(size: ${fontSize}pt, font: "New Computer Modern Math")

#let heavy-stroke = 0.8pt
#let show-ten-frames-for-all = ${showTenFramesForAll ? "true" : "false"}

${generateTypstHelpers(cellSize)}

${generateProblemStackFunction(cellSize)}

#let a = ${a}
#let b = ${b}
#let aT = calc.floor(calc.rem(a, 100) / 10)
#let aO = calc.rem(a, 10)
#let bT = calc.floor(calc.rem(b, 100) / 10)
#let bO = calc.rem(b, 10)

#align(center + horizon)[
  #problem-stack(
    a, b, aT, aO, bT, bO,
    ${showNumbers ? "0" : "none"},
    ${showCarries},
    ${showAnswers},
    ${showColors},
    ${showTenFrames},
    ${showNumbers}
  )
]
`;
}

// Generate examples showing ten-frames in action
// Use problems that WILL have regrouping to show ten-frames
const examples = [
  {
    name: "with-ten-frames",
    filename: "with-ten-frames.svg",
    description: "With Ten-Frames: Visual scaffolding for regrouping",
    options: {
      addend1: 47,
      addend2: 38, // 7+8=15 requires regrouping, will show ten-frames
      showCarryBoxes: false,
      showAnswerBoxes: false,
      showPlaceValueColors: false,
      showTenFrames: true,
      showProblemNumbers: false,
      transparentBackground: true,
    },
  },
  {
    name: "without-ten-frames",
    filename: "without-ten-frames.svg",
    description: "Without Ten-Frames: Abstract representation",
    options: {
      addend1: 47,
      addend2: 38, // Same problem, no ten-frames
      showCarryBoxes: false,
      showAnswerBoxes: false,
      showPlaceValueColors: false,
      showTenFrames: false, // No ten-frames
      showProblemNumbers: false,
      transparentBackground: true,
    },
  },
  {
    name: "beginner-with-ten-frames",
    filename: "beginner-ten-frames.svg",
    description: "Beginner: Learning regrouping with ten-frames",
    options: {
      addend1: 28,
      addend2: 15, // 8+5=13 requires regrouping
      showCarryBoxes: false,
      showAnswerBoxes: false,
      showPlaceValueColors: false,
      showTenFrames: true,
      showProblemNumbers: false,
      transparentBackground: true,
    },
  },
  {
    name: "ten-frames-both-columns",
    filename: "ten-frames-both-columns.svg",
    description: "Ten-frames in both columns: Double regrouping",
    options: {
      addend1: 57,
      addend2: 68, // Both ones (7+8=15) and tens (5+6+1=12) regroup
      showCarryBoxes: false,
      showAnswerBoxes: false,
      showPlaceValueColors: false,
      showTenFrames: true,
      showProblemNumbers: false,
      transparentBackground: true,
    },
  },
] as const;

console.log("Generating ten-frame example images (single problems)...\n");

for (const example of examples) {
  console.log(`Generating ${example.description}...`);

  try {
    const typstSource = generateExampleTypst(example.options);

    // Compile to SVG
    let svg = execSync("typst compile --format svg - -", {
      input: typstSource,
      encoding: "utf8",
      maxBuffer: 2 * 1024 * 1024,
    });

    // Post-process: Make SVG visible on dark background
    // - Digits on white cells should stay BLACK
    // - Operator symbols (+) should be WHITE
    // - Structural elements (borders, bars) should be WHITE
    svg = svg
      .replace(/stroke="#000000"/g, 'stroke="rgba(255, 255, 255, 0.8)"')
      .replace(/stroke="#0000004d"/g, 'stroke="rgba(255, 255, 255, 0.4)"');

    // Replace operator (+) fill specifically to white
    svg = svg.replace(
      /(<use xlink:href="#gCFEF70472F9D2AA9AC128F96529819DA"[^>]*fill=")#000000/g,
      "$1rgba(255, 255, 255, 0.9)",
    );

    // Save to file
    const outputPath = path.join(outputDir, example.filename);
    fs.writeFileSync(outputPath, svg, "utf-8");

    console.log(`  ✓ Saved to ${outputPath}`);
  } catch (error) {
    console.error(`  ✗ Error generating ${example.name}:`, error);
  }
}

console.log("\nDone! Ten-frame example images generated.");
console.log(`\nFiles saved to: ${outputDir}`);