check: generation

CLAUDE.md

@@ -7,18 +7,19 @@ Printable math worksheet generator (A4 PDF) for children aged 7–9. Claude Code
 ## Commands
 
 ```bash
-npm run build:css          # Build Tailwind CSS (minified)
+pnpm build:css          # Build Tailwind CSS (minified)
-npm run build:css:watch    # Watch mode for CSS
+pnpm build:css:watch    # Watch mode for CSS
-npm run preview            # Serve HTML at localhost:3000 with live-reload
+pnpm preview            # Serve HTML at localhost:3000 with live-reload
-npm run dev                # CSS watch + preview server (concurrent)
+pnpm dev                # CSS watch + preview server (concurrent)
-npm run pdf -- <file>      # Convert HTML file to PDF
+pnpm pdf -- <file>      # Convert HTML file to PDF
-npm run remove-bg -- <file|dir>  # Remove white background from PNG icons
+pnpm remove-bg -- <file|dir>  # Remove white background from PNG icons
 ```
 
 Generate images via Banatie API:
 ```bash
-node src/scripts/banatie.mjs --type background --prompt "forest theme" --output assets/backgrounds/forest.png
+node src/scripts/banatie.mjs --prompt "forest theme" --output assets/backgrounds/forest.png --aspect-ratio 9:16
-node src/scripts/banatie.mjs --type icon --prompt "golden star" --output assets/icons/stars/star1.png
+node src/scripts/banatie.mjs --prompt "golden star" --output assets/icons/star.png
+node src/scripts/banatie.mjs --prompt "similar gem" --output assets/icons/gem.png --ref assets/icons/sample.png
 ```
 
 ## Directory Structure
@@ -150,12 +151,30 @@ When generating HTML worksheets:
 
 ## Banatie API
 
-REST API for generating images.
+REST API at `https://api.banatie.app` for generating images. Auth via `X-API-Key` header (reads `BANATIE_KEY` from `.env`).
 
-- **Backgrounds:** ~1200×1700px, themed illustrations (forest, space, ocean, etc.)
+**POST `/api/v1/generations`** — create generation:
-- **Icons:** 128×128px, transparent PNG, simple collectible items (stars, gems, animals)
+- `prompt` (string, required) — image description
+- `aspectRatio` — `1:1`, `16:9`, `9:16`, `3:2`, `4:3`, `3:4`, `21:9` (default: `1:1`)
+- `referenceImages` (string[]) — `@alias` names of reference images
+- `flowId` (string) — associate with a flow (for flow-scoped alias resolution)
+- `autoEnhance` (boolean) — prompt enhancement (default: true)
 
-Configuration is in `src/scripts/banatie.mjs`. Set the `BANATIE_API_KEY` environment variable for authentication.
+**POST `/api/v1/images/upload`** — upload image (for use as reference):
+- Multipart form data: `file` (up to 5MB, JPEG/PNG/WebP), `alias` (@name), `flowId`
+- Auto-creates a flow, returns `flowId` in response
+
+Response returns JSON with `data.outputImage.storageUrl` (CDN URL to download).
+
+Script `src/scripts/banatie.mjs` CLI:
+```bash
+node src/scripts/banatie.mjs --prompt "description" --output path.png [--aspect-ratio 1:1] [--ref file.png]...
+```
+- `--ref` accepts local file paths or `@alias`. Can be repeated
+- Local files are uploaded with auto-generated `@alias` into a shared flow
+- The flow's `flowId` is passed to generation for alias resolution
+
+Rate limit: 100 requests/hour per API key.
 
 ## Background Removal
 
@@ -186,5 +205,5 @@ Puppeteer settings for A4 worksheets:
 3. Claude reads `src/templates/space-base.html` + `src/examples/space-worksheet.html` as references
 4. Claude generates HTML file in `output/html/` — creates concrete problems from `task` text, assigns unique shuffled icons, builds all pages
 5. Add a link to the new document in `output/index.html` (card with title and path)
-6. Run `npm run pdf -- output/html/<file>.html` to create PDF
+6. Run `pnpm pdf -- output/html/<file>.html` to create PDF
-7. Preview with `npm run preview` at localhost:3000
+7. Preview with `pnpm preview` at localhost:3000

package.json

@@ -5,11 +5,11 @@
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "build:css": "npx @tailwindcss/cli -i src/styles/main.css -o output/css/styles.css --minify",
+    "build:css": "tailwindcss -i src/styles/main.css -o output/css/styles.css --minify",
-    "build:css:watch": "npx @tailwindcss/cli -i src/styles/main.css -o output/css/styles.css --watch",
+    "build:css:watch": "tailwindcss -i src/styles/main.css -o output/css/styles.css --watch",
     "preview": "browser-sync start --config bs-config.cjs",
     "pdf": "node src/scripts/generate-pdf.mjs",
-    "dev": "concurrently \"npm run build:css:watch\" \"npm run preview\"",
+    "dev": "concurrently \"pnpm build:css:watch\" \"pnpm preview\"",
     "split-sprites": "node src/scripts/split-sprites.mjs",
     "remove-bg": "node src/scripts/remove-bg.mjs"
   },

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+ignoredBuiltDependencies:
+  - '@parcel/watcher'
+  - puppeteer
+  - sharp

src/scripts/banatie.mjs

@@ -1,58 +1,152 @@
-import { writeFileSync, mkdirSync } from 'fs';
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'fs';
-import { resolve, dirname } from 'path';
+import { resolve, dirname, basename } from 'path';
 
-const API_ENDPOINT = process.env.BANATIE_API_URL || 'https://api.banatie.com/v1/generate';
+const envPath = resolve(dirname(new URL(import.meta.url).pathname), '../../.env');
-const API_KEY = process.env.BANATIE_API_KEY || '';
+try {
-
+  const envContent = readFileSync(envPath, 'utf-8');
-const PRESETS = {
+  for (const line of envContent.split('\n')) {
-  background: { width: 1200, height: 1700, format: 'png' },
+    const match = line.match(/^([^#=]+)=(.*)$/);
-  icon: { width: 128, height: 128, format: 'png', transparent: true },
+    if (match && !process.env[match[1].trim()]) {
-};
+      process.env[match[1].trim()] = match[2].trim();
-
+    }
-export async function generateImage({ type = 'icon', prompt, output }) {
-  if (!API_KEY) {
-    console.error('BANATIE_API_KEY environment variable is not set');
-    process.exit(1);
   }
+} catch {}
 
-  const preset = PRESETS[type];
-  if (!preset) {
-    console.error(`Unknown type: ${type}. Use "background" or "icon".`);
-    process.exit(1);
-  }
 
-  const response = await fetch(API_ENDPOINT, {
+const API_BASE = 'https://api.banatie.app/api/v1';
+const API_KEY = process.env.BANATIE_KEY || '';
+
+async function uploadImage(filePath, { flowId, alias }) {
+  const absolutePath = resolve(filePath);
+  const fileBuffer = readFileSync(absolutePath);
+  const fileName = basename(absolutePath);
+
+  const ext = fileName.split('.').pop().toLowerCase();
+  const mimeTypes = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' };
+  const mime = mimeTypes[ext] || 'application/octet-stream';
+
+  const form = new FormData();
+  form.append('file', new Blob([fileBuffer], { type: mime }), fileName);
+  form.append('alias', alias);
+  if (flowId) form.append('flowId', flowId);
+
+  console.log(`Uploading: ${filePath} as ${alias}${flowId ? ` (flow: ${flowId})` : ''}...`);
+
+  const response = await fetch(`${API_BASE}/images/upload`, {
     method: 'POST',
-    headers: {
+    headers: { 'X-API-Key': API_KEY },
-      'Content-Type': 'application/json',
+    body: form,
-      'Authorization': `Bearer ${API_KEY}`,
-    },
-    body: JSON.stringify({
-      prompt,
-      ...preset,
-    }),
   });
 
   if (!response.ok) {
-    const body = await response.text();
+    const text = await response.text();
-    console.error(`API error ${response.status}: ${body}`);
+    console.error(`Upload error ${response.status}: ${text}`);
     process.exit(1);
   }
 
-  const buffer = Buffer.from(await response.arrayBuffer());
+  const result = await response.json();
+  if (!result.success) {
+    console.error(`Upload failed:`, result.error);
+    process.exit(1);
+  }
+
+  console.log(`Uploaded: ${alias} (${result.data.id})`);
+  return result.data;
+}
+
+function makeAlias(filePath, index) {
+  const name = basename(filePath).replace(/\.[^.]+$/, '').replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+  return `@ref-${index + 1}-${name}`;
+}
+
+async function resolveRefs(refs) {
+  if (!refs || refs.length === 0) return undefined;
+
+  const aliases = [];
+  let flowId = null;
+
+  for (let i = 0; i < refs.length; i++) {
+    const ref = refs[i];
+    if (ref.startsWith('@')) {
+      aliases.push(ref);
+    } else if (existsSync(ref)) {
+      const alias = makeAlias(ref, i);
+      const data = await uploadImage(ref, { flowId, alias });
+      if (!flowId) flowId = data.flowId;
+      aliases.push(alias);
+    } else {
+      console.error(`Reference not found: ${ref}`);
+      process.exit(1);
+    }
+  }
+
+  return { referenceImages: aliases, flowId };
+}
+
+export async function generateImage({ prompt, output, aspectRatio = '1:1', refs }) {
+  if (!API_KEY) {
+    console.error('BANATIE_KEY environment variable is not set');
+    process.exit(1);
+  }
+
+  const resolved = await resolveRefs(refs);
+  const body = { prompt, aspectRatio };
+  if (resolved) {
+    body.referenceImages = resolved.referenceImages;
+    if (resolved.flowId) body.flowId = resolved.flowId;
+  }
+
+  console.log(`Generating: "${prompt}" (${body.aspectRatio})${resolved ? ` with ${resolved.referenceImages.length} ref(s)` : ''}...`);
+
+  const response = await fetch(`${API_BASE}/generations`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': API_KEY,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    console.error(`API error ${response.status}: ${text}`);
+    process.exit(1);
+  }
+
+  const result = await response.json();
+  if (!result.success) {
+    console.error(`Generation failed:`, result.error);
+    process.exit(1);
+  }
+
+  const imageUrl = result.data.outputImage.storageUrl;
+  console.log(`Downloading from ${imageUrl}...`);
+
+  const imageResponse = await fetch(imageUrl);
+  if (!imageResponse.ok) {
+    console.error(`Failed to download image: ${imageResponse.status}`);
+    process.exit(1);
+  }
+
+  const buffer = Buffer.from(await imageResponse.arrayBuffer());
   const outputPath = resolve(output);
   mkdirSync(dirname(outputPath), { recursive: true });
   writeFileSync(outputPath, buffer);
-  console.log(`Image saved: ${outputPath}`);
+
-  return outputPath;
+  console.log(`Image saved: ${outputPath} (${result.data.outputImage.width}x${result.data.outputImage.height})`);
+  return { path: outputPath, generation: result.data };
 }
 
 function parseArgs(args) {
   const result = {};
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--type') result.type = args[++i];
+    if (args[i] === '--prompt') result.prompt = args[++i];
-    else if (args[i] === '--prompt') result.prompt = args[++i];
     else if (args[i] === '--output') result.output = args[++i];
+    else if (args[i] === '--aspect-ratio') result.aspectRatio = args[++i];
+    else if (args[i] === '--ref') {
+      if (!result.refs) result.refs = [];
+      result.refs.push(args[++i]);
+    }
   }
   return result;
 }
@@ -61,6 +155,6 @@ const args = parseArgs(process.argv.slice(2));
 if (args.prompt && args.output) {
   generateImage(args);
 } else if (process.argv.length > 2) {
-  console.error('Usage: node banatie.mjs --type <background|icon> --prompt "<description>" --output <path>');
+  console.error('Usage: node banatie.mjs --prompt "<description>" --output <path> [--aspect-ratio <ratio>] [--ref <file|id>]...');
   process.exit(1);
 }