@ghuts/memegen 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Meme Generator Sharp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Font notice: the bundled Anton font in assets/Anton-Regular.ttf is licensed
+separately under the SIL Open Font License 1.1. See assets/OFL-Anton.txt.

package/README.md

@@ -0,0 +1,251 @@
+# Memegen
+
+A JavaScript module for creating memes with [Sharp](https://sharp.pixelplumbing.com/), automatic text wrapping, shrink-to-fit captions, and a bundled meme-style font.
+
+Memegen takes a background image, keeps the original image size, and draws top and bottom captions that stay inside the image bounds. It works as an ESM module and as a command-line tool.
+
+## Features
+
+- Keeps the output size equal to the background image size.
+- Supports top and bottom caption text.
+- Automatically wraps long text.
+- Automatically shrinks text until it fits the caption area.
+- Can choose readable text color from the background (`textColor: 'auto'`).
+- Classic meme outline and subtle shadow.
+- Bundled Anton font from Google Fonts, so servers do not need system fonts installed.
+- Outputs `png`, `jpg/jpeg`, or `webp`.
+- Usable from code or from the CLI.
+
+## Installation
+
+From npm:
+
+```bash
+npm install @ghuts/memegen
+```
+
+From a local clone:
+
+```bash
+git clone <repo-url>
+cd memegen
+npm install
+```
+
+## Quick Start
+
+```js
+import { generateMemeFile } from '@ghuts/memegen';
+
+await generateMemeFile({
+  input: 'background.jpg',
+  output: 'output/meme.png',
+  topText: 'WHEN THE CODE WORKS',
+  bottomText: 'BUT YOU DO NOT KNOW WHY'
+});
+```
+
+The output image will use the original dimensions of `background.jpg`.
+
+## Return a Buffer
+
+```js
+import { readFile } from 'node:fs/promises';
+import { generateMeme } from '@ghuts/memegen';
+
+const background = await readFile('background.jpg');
+
+const memeBuffer = await generateMeme({
+  background,
+  topText: 'TOP TEXT',
+  bottomText: 'BOTTOM TEXT',
+  format: 'png'
+});
+```
+
+You can send the returned `Buffer` directly from an API route, bot, or serverless function.
+
+## CLI
+
+```bash
+npx @ghuts/memegen \
+  --image background.jpg \
+  --top "WHEN THE BUILD PASSES" \
+  --bottom "ON THE FIRST TRY" \
+  --out output/meme.png
+```
+
+From a local checkout:
+
+```bash
+node cli.js \
+  --image background.jpg \
+  --top "WHEN THE BUILD PASSES" \
+  --bottom "ON THE FIRST TRY" \
+  --out output/meme.png
+```
+
+## API
+
+### `generateMemeFile(options)`
+
+Renders a meme and writes it to disk.
+
+```js
+const result = await generateMemeFile({
+  input: 'background.jpg',
+  output: 'output/meme.png',
+  topText: 'TOP TEXT',
+  bottomText: 'BOTTOM TEXT'
+});
+```
+
+Returns:
+
+```js
+{
+  output: 'output/meme.png',
+  buffer: Buffer,
+  width: 600,
+  height: 600,
+  format: 'png',
+  top: { lines: ['TOP TEXT'], fontSize: 82, ... },
+  bottom: { lines: ['BOTTOM TEXT'], fontSize: 76, ... }
+}
+```
+
+### `generateMeme(options)`
+
+Renders a meme and returns a `Buffer`.
+
+```js
+const memeBuffer = await generateMeme({
+  input: 'background.jpg',
+  topText: 'TOP',
+  bottomText: 'BOTTOM'
+});
+```
+
+### `renderMeme(options)`
+
+Renders a meme and returns the image buffer plus layout metadata.
+
+```js
+const result = await renderMeme({
+  input: 'background.jpg',
+  topText: 'TOP',
+  bottomText: 'BOTTOM'
+});
+
+console.log(result.width, result.height, result.top.lines);
+```
+
+### `layoutMemeText(options)`
+
+Calculates the text layout without rendering an image. This is useful for tests and previews.
+
+```js
+const layout = layoutMemeText({
+  width: 600,
+  height: 600,
+  topText: 'THIS IS A LONG TOP CAPTION',
+  bottomText: 'THIS LONG BOTTOM CAPTION WILL WRAP AUTOMATICALLY'
+});
+
+console.log(layout.bottom.lines);
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `input` / `image` / `background` | `string | Buffer | Uint8Array` | required | Background image source. |
+| `output` / `out` | `string` | required for `generateMemeFile` | Output path. |
+| `topText` / `top` | `string` | `''` | Top caption. |
+| `bottomText` / `bottom` | `string` | `''` | Bottom caption. |
+| `uppercase` | `boolean` | `true` | Convert captions to uppercase. |
+| `format` | `png | jpg | jpeg | webp` | `png` | Output format. |
+| `quality` | `number` | `92` | JPEG/WebP quality. |
+| `textColor` | `auto | string` | `auto` | Caption fill color. |
+| `strokeColor` | `auto | string` | `auto` | Caption outline color. |
+| `strokeWidthRatio` | `number` | `0.075` | Outline width relative to font size. |
+| `shadow` | `boolean` | `true` | Enables drop shadow. |
+| `paddingRatio` | `number` | `0.045` | Caption padding relative to image size. |
+| `captionHeightRatio` | `number` | `0.25` | Height of the top and bottom caption areas. |
+| `fontSizeRatio` | `number` | `0.145` | Starting font size ratio. |
+| `minFontSizeRatio` | `number` | `0.018` | Minimum font size ratio. |
+| `lineHeight` | `number` | `0.92` | Caption line height. |
+| `fontPath` | `string | Buffer | Uint8Array | false` | bundled Anton | Custom TTF/OTF font source. |
+
+## Fonts
+
+Default font:
+
+- `assets/Anton-Regular.ttf`
+- Source: Google Fonts, Anton family
+- License: SIL Open Font License 1.1
+- License file: `assets/OFL-Anton.txt`
+
+Memegen converts text into SVG paths with `opentype.js`, so the rendered result stays consistent even when the host machine has no matching system font.
+
+Use a custom font:
+
+```js
+await generateMemeFile({
+  input: 'background.jpg',
+  output: 'output/custom-font.png',
+  topText: 'CUSTOM',
+  bottomText: 'FONT',
+  fontPath: './fonts/MyFont.ttf'
+});
+```
+
+Disable embedded font paths and let SVG use a system font family:
+
+```js
+await generateMemeFile({
+  input: 'background.jpg',
+  output: 'output/system-font.png',
+  topText: 'SYSTEM',
+  bottomText: 'FONT',
+  fontPath: false,
+  fontFamily: 'Impact, Arial Black, sans-serif'
+});
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+npm run demo
+```
+
+Scripts:
+
+- `npm run check`: syntax-checks the main files.
+- `npm test`: runs a render smoke test and checks text bounds.
+- `npm run demo`: creates `output/demo-meme.png`.
+
+`node_modules/` and `output/` are ignored so the repository stays clean.
+
+## Publish Checklist
+
+Before publishing or pushing a release:
+
+```bash
+rm -rf node_modules output
+npm install
+npm run check
+npm test
+npm pack --dry-run
+```
+
+The package should contain only source files, font assets, license files, type definitions, examples, tests, and documentation.
+
+## License
+
+Code: MIT. See `LICENSE`.
+
+Bundled font: Anton, SIL Open Font License 1.1. See `assets/OFL-Anton.txt`.

package/assets/OFL-Anton.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Anton Project Authors (https://github.com/googlefonts/AntonFont.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { generateMemeFile } from './index.js';
+
+function printHelp() {
+  console.log(`
+Meme Generator Sharp Module
+
+Usage:
+  node cli.js --image background.jpg --top "WHEN THE BUILD PASSES" --bottom "ON THE FIRST TRY" --out output/meme.png
+
+Options:
+  --image <file>       Background image. Alias: --input.
+  --top <text>         Top text.
+  --bottom <text>      Bottom text.
+  --out <file>         Output file. Default: output/meme.png.
+  --format <format>    png, jpg, jpeg, or webp. Default: inferred from --out or png.
+  --text-color <hex>   Text color, or auto. Default: auto.
+  --stroke-color <hex> Stroke color, or auto. Default: auto.
+  --font <file>        TTF/OTF font path. Default: bundled Anton.
+  --font-ratio <num>   Text size ratio. Default: 0.145.
+  --caption-ratio <n>  Top/bottom text box height ratio. Default: 0.25.
+  --no-caps            Keep original letter casing.
+  --no-shadow          Disable subtle shadow.
+  --help               Show this help.
+`);
+}
+
+async function main() {
+  const { values: cliOptions } = parseArgs({
+    options: {
+      image: { type: 'string' },
+      input: { type: 'string' },
+      top: { type: 'string', default: '' },
+      bottom: { type: 'string', default: '' },
+      out: { type: 'string', default: 'output/meme.png' },
+      format: { type: 'string' },
+      'text-color': { type: 'string', default: 'auto' },
+      'stroke-color': { type: 'string', default: 'auto' },
+      font: { type: 'string' },
+      'font-ratio': { type: 'string' },
+      'caption-ratio': { type: 'string' },
+      'no-caps': { type: 'boolean', default: false },
+      'no-shadow': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false }
+    }
+  });
+
+  if (cliOptions.help) {
+    printHelp();
+    return;
+  }
+
+  const input = cliOptions.image ?? cliOptions.input;
+  if (!input) {
+    printHelp();
+    throw new Error('Missing --image or --input.');
+  }
+
+  const output = cliOptions.out;
+  const inferredFormat = output.match(/\.(png|jpe?g|webp)$/i)?.[1]?.toLowerCase();
+
+  const result = await generateMemeFile({
+    input,
+    output,
+    topText: cliOptions.top,
+    bottomText: cliOptions.bottom,
+    format: cliOptions.format ?? inferredFormat ?? 'png',
+    textColor: cliOptions['text-color'],
+    strokeColor: cliOptions['stroke-color'],
+    fontPath: cliOptions.font,
+    fontSizeRatio: cliOptions['font-ratio'] === undefined ? undefined : Number(cliOptions['font-ratio']),
+    captionHeightRatio: cliOptions['caption-ratio'] === undefined ? undefined : Number(cliOptions['caption-ratio']),
+    uppercase: !cliOptions['no-caps'],
+    shadow: !cliOptions['no-shadow']
+  });
+
+  console.log(`OK: ${result.output}`);
+  console.log(`Size: ${result.width}x${result.height}`);
+  console.log(`Top lines: ${result.top.lines.length} | Bottom lines: ${result.bottom.lines.length}`);
+}
+
+main().catch((error) => {
+  console.error(`ERROR: ${error.message}`);
+  process.exit(1);
+});

package/examples/demo.js

@@ -0,0 +1,27 @@
+import { mkdir } from 'node:fs/promises';
+import sharp from 'sharp';
+import { generateMemeFile } from '../index.js';
+
+await mkdir('output', { recursive: true });
+
+const backgroundSvg = `
+<svg width="600" height="600" viewBox="0 0 600 600" xmlns="http://www.w3.org/2000/svg">
+  <rect width="600" height="600" fill="#ffffff"/>
+  <rect y="370" width="600" height="230" fill="#f0f2f4"/>
+  <circle cx="135" cy="170" r="78" fill="#31343a"/>
+  <circle cx="455" cy="310" r="104" fill="#d8a334"/>
+  <path d="M0 430 C120 365 210 475 325 408 C440 340 492 410 600 372 L600 600 L0 600 Z" fill="#2f645f"/>
+</svg>`;
+
+const background = await sharp(Buffer.from(backgroundSvg)).png().toBuffer();
+
+await generateMemeFile({
+  background,
+  output: 'output/demo-meme.png',
+  topText: 'when the demo works',
+  bottomText: 'ship it with confidence',
+  textColor: '#ffffff',
+  strokeColor: '#000000'
+});
+
+console.log('OK: output/demo-meme.png');

package/index.d.ts

@@ -0,0 +1,80 @@
+export type MemeImageInput = string | Buffer | Uint8Array;
+
+export type MemeFormat = 'png' | 'jpg' | 'jpeg' | 'webp';
+
+export interface MemeGeneratorOptions {
+  input?: MemeImageInput;
+  image?: MemeImageInput;
+  background?: MemeImageInput;
+  output?: string;
+  out?: string;
+  topText?: string;
+  top?: string;
+  bottomText?: string;
+  bottom?: string;
+  uppercase?: boolean;
+  fontPath?: string | Buffer | Uint8Array | false | null;
+  fontFamily?: string;
+  textColor?: 'auto' | string;
+  strokeColor?: 'auto' | string;
+  strokeWidthRatio?: number;
+  shadow?: boolean;
+  paddingRatio?: number;
+  captionHeightRatio?: number;
+  fontSizeRatio?: number;
+  minFontSizeRatio?: number;
+  lineHeight?: number;
+  format?: MemeFormat;
+  quality?: number;
+  autoColorThreshold?: number;
+}
+
+export interface CaptionZone {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface CaptionLayout {
+  text: string;
+  lines: string[];
+  fontSize: number;
+  lineHeightPx: number;
+  blockHeight: number;
+  maxLineWidth: number;
+  zone: CaptionZone;
+}
+
+export interface RenderResult {
+  buffer: Buffer;
+  width: number;
+  height: number;
+  format: 'png' | 'jpeg' | 'webp';
+  top: CaptionLayout;
+  bottom: CaptionLayout;
+}
+
+export interface FileRenderResult extends RenderResult {
+  output: string;
+}
+
+export interface LayoutOnlyOptions extends Omit<MemeGeneratorOptions, 'input' | 'image' | 'background' | 'output' | 'out'> {
+  width: number;
+  height: number;
+}
+
+export interface LayoutOnlyResult {
+  width: number;
+  height: number;
+  top: CaptionLayout;
+  bottom: CaptionLayout;
+}
+
+export function generateMeme(options: MemeGeneratorOptions): Promise<Buffer>;
+
+export function generateMemeFile(options: MemeGeneratorOptions & { output?: string; out?: string }): Promise<FileRenderResult>;
+
+export function renderMeme(options: MemeGeneratorOptions): Promise<RenderResult>;
+
+export function layoutMemeText(options: LayoutOnlyOptions): LayoutOnlyResult;

package/index.js

@@ -0,0 +1,503 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import opentype from 'opentype.js';
+import sharp from 'sharp';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_FONT_PATH = path.join(MODULE_DIR, 'assets', 'Anton-Regular.ttf');
+const DEFAULT_FONT_NAME = 'Anton';
+
+const DEFAULTS = {
+  topText: '',
+  bottomText: '',
+  uppercase: true,
+  fontPath: DEFAULT_FONT_PATH,
+  fontFamily: DEFAULT_FONT_NAME,
+  textColor: 'auto',
+  strokeColor: 'auto',
+  strokeWidthRatio: 0.075,
+  shadow: true,
+  paddingRatio: 0.045,
+  captionHeightRatio: 0.25,
+  fontSizeRatio: 0.145,
+  minFontSizeRatio: 0.018,
+  lineHeight: 0.92,
+  format: 'png',
+  quality: 92,
+  autoColorThreshold: 150
+};
+
+const SUPPORTED_FORMATS = new Set(['png', 'jpeg', 'jpg', 'webp']);
+
+export async function generateMeme(options) {
+  const result = await renderMeme(options);
+  return result.buffer;
+}
+
+export async function generateMemeFile(options) {
+  const output = options?.output ?? options?.out;
+  if (!output) {
+    throw new Error('generateMemeFile requires output or out path.');
+  }
+
+  const result = await renderMeme(options);
+  await mkdir(path.dirname(path.resolve(output)), { recursive: true });
+  await writeFile(output, result.buffer);
+
+  return {
+    ...result,
+    output
+  };
+}
+
+export async function renderMeme(options = {}) {
+  const settings = normalizeOptions(options);
+  settings.font = await loadFont(settings.fontPath);
+  const background = await loadBackground(settings.background);
+  const normalizedImage = await sharp(background).rotate().toBuffer();
+  const metadata = await sharp(normalizedImage).metadata();
+  const width = metadata.width;
+  const height = metadata.height;
+
+  if (!width || !height) {
+    throw new Error('Background image has no readable width/height.');
+  }
+
+  const raw = await sharp(normalizedImage)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const overlay = createMemeSvg({
+    width,
+    height,
+    raw,
+    settings
+  });
+
+  const pipeline = sharp(normalizedImage).composite([
+    {
+      input: Buffer.from(overlay),
+      top: 0,
+      left: 0
+    }
+  ]);
+
+  const format = settings.format === 'jpg' ? 'jpeg' : settings.format;
+  const buffer = await encodeImage(pipeline, format, settings.quality);
+
+  return {
+    buffer,
+    width,
+    height,
+    format,
+    top: layoutCaption({
+      text: settings.topText,
+      zone: getCaptionZones(width, height, settings).top,
+      settings
+    }),
+    bottom: layoutCaption({
+      text: settings.bottomText,
+      zone: getCaptionZones(width, height, settings).bottom,
+      settings
+    })
+  };
+}
+
+export function layoutMemeText(options = {}) {
+  const settings = normalizeOptions({
+    ...options,
+    background: options.background ?? Buffer.from([0])
+  }, { skipBackground: true });
+  const width = positiveNumber(options.width, 'width');
+  const height = positiveNumber(options.height, 'height');
+  const zones = getCaptionZones(width, height, settings);
+
+  return {
+    width,
+    height,
+    top: layoutCaption({ text: settings.topText, zone: zones.top, settings }),
+    bottom: layoutCaption({ text: settings.bottomText, zone: zones.bottom, settings })
+  };
+}
+
+function normalizeOptions(options, flags = {}) {
+  const settings = {
+    ...DEFAULTS,
+    ...options,
+    topText: options.topText ?? options.top ?? DEFAULTS.topText,
+    bottomText: options.bottomText ?? options.bottom ?? DEFAULTS.bottomText,
+    background: options.background ?? options.image ?? options.input
+  };
+
+  if (!flags.skipBackground && !settings.background) {
+    throw new Error('Background image is required. Use background, image, or input.');
+  }
+
+  settings.format = String(settings.format ?? DEFAULTS.format).toLowerCase();
+  if (!SUPPORTED_FORMATS.has(settings.format)) {
+    throw new Error(`Unsupported format "${settings.format}". Use png, jpeg, jpg, or webp.`);
+  }
+
+  settings.quality = clampNumber(settings.quality, 1, 100, DEFAULTS.quality);
+  settings.fontPath = settings.fontPath ?? DEFAULTS.fontPath;
+  settings.fontFamily = settings.fontFamily || DEFAULTS.fontFamily;
+  settings.paddingRatio = clampNumber(settings.paddingRatio, 0, 0.2, DEFAULTS.paddingRatio);
+  settings.captionHeightRatio = clampNumber(settings.captionHeightRatio, 0.08, 0.48, DEFAULTS.captionHeightRatio);
+  settings.fontSizeRatio = clampNumber(settings.fontSizeRatio, 0.03, 0.3, DEFAULTS.fontSizeRatio);
+  settings.minFontSizeRatio = clampNumber(settings.minFontSizeRatio, 0.004, 0.08, DEFAULTS.minFontSizeRatio);
+  settings.strokeWidthRatio = clampNumber(settings.strokeWidthRatio, 0, 0.2, DEFAULTS.strokeWidthRatio);
+  settings.lineHeight = clampNumber(settings.lineHeight, 0.75, 1.5, DEFAULTS.lineHeight);
+  settings.autoColorThreshold = clampNumber(settings.autoColorThreshold, 1, 254, DEFAULTS.autoColorThreshold);
+
+  return settings;
+}
+
+async function loadBackground(background) {
+  if (Buffer.isBuffer(background)) return background;
+  if (background instanceof Uint8Array) return Buffer.from(background);
+  if (typeof background === 'string') return readFile(background);
+  throw new Error('Background must be a file path, Buffer, or Uint8Array.');
+}
+
+async function loadFont(fontPath) {
+  if (fontPath === false || fontPath === null) return null;
+
+  const fontBuffer = Buffer.isBuffer(fontPath) || fontPath instanceof Uint8Array
+    ? Buffer.from(fontPath)
+    : await readFile(fontPath);
+  const arrayBuffer = fontBuffer.buffer.slice(
+    fontBuffer.byteOffset,
+    fontBuffer.byteOffset + fontBuffer.byteLength
+  );
+
+  return opentype.parse(arrayBuffer);
+}
+
+async function encodeImage(pipeline, format, quality) {
+  if (format === 'jpeg') return pipeline.jpeg({ quality }).toBuffer();
+  if (format === 'webp') return pipeline.webp({ quality }).toBuffer();
+  return pipeline.png().toBuffer();
+}
+
+function createMemeSvg({ width, height, raw, settings }) {
+  const zones = getCaptionZones(width, height, settings);
+  const top = buildCaptionSvg({
+    text: settings.topText,
+    zone: zones.top,
+    position: 'top',
+    raw,
+    settings
+  });
+  const bottom = buildCaptionSvg({
+    text: settings.bottomText,
+    zone: zones.bottom,
+    position: 'bottom',
+    raw,
+    settings
+  });
+
+  return `<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <filter id="memeShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="${formatNumber(Math.max(1, width * 0.003))}" stdDeviation="${formatNumber(Math.max(1, width * 0.004))}" flood-color="#000000" flood-opacity="0.48"/>
+    </filter>
+  </defs>
+  ${top}
+  ${bottom}
+</svg>`;
+}
+
+function buildCaptionSvg({ text, zone, position, raw, settings }) {
+  const layout = layoutCaption({ text, zone, settings });
+  if (!layout.text) return '';
+
+  const colors = resolveCaptionColors({ zone, raw, settings });
+  const shadow = settings.shadow ? ' filter="url(#memeShadow)"' : '';
+  const strokeWidth = Math.max(0, layout.fontSize * settings.strokeWidthRatio);
+  const yStart = zone.y + (zone.height - layout.blockHeight) / 2 + layout.fontSize * 0.82;
+
+  if (!settings.font) {
+    const tspans = layout.lines.map((line, index) => {
+      const y = yStart + index * layout.lineHeightPx;
+      return `<tspan x="${formatNumber(zone.x + zone.width / 2)}" y="${formatNumber(y)}">${escapeXml(line)}</tspan>`;
+    }).join('');
+
+    return `<text data-position="${position}"
+        font-family="${escapeXml(settings.fontFamily)}"
+        font-size="${formatNumber(layout.fontSize)}"
+        text-anchor="middle"
+        fill="${escapeXml(colors.fill)}"
+        stroke="${escapeXml(colors.stroke)}"
+        stroke-width="${formatNumber(strokeWidth)}"
+        stroke-linejoin="round"
+        paint-order="stroke fill"${shadow}>${tspans}</text>`;
+  }
+
+  const paths = layout.lines.map((line, index) => {
+    const y = yStart + index * layout.lineHeightPx;
+    const lineWidth = measureText(line, layout.fontSize, settings);
+    const x = zone.x + (zone.width - lineWidth) / 2;
+    const glyphPath = settings.font.getPath(line, x, y, layout.fontSize);
+    return `<path d="${glyphPath.toPathData(2)}"/>`;
+  }).join('');
+
+  return `<g data-position="${position}"
+        fill="${escapeXml(colors.fill)}"
+        stroke="${escapeXml(colors.stroke)}"
+        stroke-width="${formatNumber(strokeWidth)}"
+        stroke-linejoin="round"
+        paint-order="stroke fill"${shadow}>${paths}</g>`;
+}
+
+function getCaptionZones(width, height, settings) {
+  const padding = Math.round(Math.min(width, height) * settings.paddingRatio);
+  const zoneHeight = Math.round(height * settings.captionHeightRatio);
+  const zoneWidth = Math.max(1, width - padding * 2);
+
+  return {
+    top: {
+      x: padding,
+      y: padding,
+      width: zoneWidth,
+      height: Math.max(1, zoneHeight)
+    },
+    bottom: {
+      x: padding,
+      y: Math.max(padding, height - padding - zoneHeight),
+      width: zoneWidth,
+      height: Math.max(1, zoneHeight)
+    }
+  };
+}
+
+function layoutCaption({ text, zone, settings }) {
+  const normalized = normalizeText(text, settings.uppercase);
+  if (!normalized) {
+    return {
+      text: '',
+      lines: [],
+      fontSize: 0,
+      lineHeightPx: 0,
+      blockHeight: 0,
+      maxLineWidth: 0,
+      zone
+    };
+  }
+
+  const base = Math.min(zone.width, zone.height * 2.2);
+  const maxFontSize = Math.max(4, Math.floor(base * settings.fontSizeRatio * 2.2));
+  const minFontSize = Math.max(4, Math.floor(Math.min(zone.width, zone.height) * settings.minFontSizeRatio));
+  let low = Math.min(minFontSize, maxFontSize);
+  let high = Math.max(minFontSize, maxFontSize);
+  let best = makeCaptionLayout(normalized, zone, low, settings);
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const candidate = makeCaptionLayout(normalized, zone, mid, settings);
+
+    if (candidate.fits) {
+      best = candidate;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return {
+    text: normalized,
+    lines: best.lines,
+    fontSize: best.fontSize,
+    lineHeightPx: best.lineHeightPx,
+    blockHeight: best.blockHeight,
+    maxLineWidth: best.maxLineWidth,
+    zone
+  };
+}
+
+function makeCaptionLayout(text, zone, fontSize, settings) {
+  const lines = wrapText(text, zone.width, fontSize, settings);
+  const lineHeightPx = fontSize * settings.lineHeight;
+  const blockHeight = lines.length * lineHeightPx;
+  const maxLineWidth = lines.reduce((max, line) => {
+    return Math.max(max, measureText(line, fontSize, settings));
+  }, 0);
+
+  return {
+    lines,
+    fontSize,
+    lineHeightPx,
+    blockHeight,
+    maxLineWidth,
+    fits: maxLineWidth <= zone.width && blockHeight <= zone.height
+  };
+}
+
+function wrapText(text, maxWidth, fontSize, settings) {
+  const lines = [];
+  const paragraphs = text.split('\n');
+
+  for (const paragraph of paragraphs) {
+    const words = paragraph.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+      lines.push('');
+      continue;
+    }
+
+    let current = '';
+    for (const word of words) {
+      const next = current ? `${current} ${word}` : word;
+      if (measureText(next, fontSize, settings) <= maxWidth) {
+        current = next;
+        continue;
+      }
+
+      if (current) {
+        lines.push(current);
+        current = '';
+      }
+
+      if (measureText(word, fontSize, settings) <= maxWidth) {
+        current = word;
+        continue;
+      }
+
+      const chunks = splitLongWord(word, maxWidth, fontSize, settings);
+      lines.push(...chunks.slice(0, -1));
+      current = chunks.at(-1) ?? '';
+    }
+
+    if (current) lines.push(current);
+  }
+
+  return lines.filter((line, index) => line || index === 0);
+}
+
+function splitLongWord(word, maxWidth, fontSize, settings) {
+  const chunks = [];
+  let current = '';
+
+  for (const char of word) {
+    const next = current + char;
+    if (!current || measureText(next, fontSize, settings) <= maxWidth) {
+      current = next;
+      continue;
+    }
+
+    chunks.push(current);
+    current = char;
+  }
+
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+function measureText(text, fontSize, settings) {
+  if (settings?.font) {
+    return settings.font.getAdvanceWidth(String(text), fontSize);
+  }
+
+  let units = 0;
+
+  for (const char of String(text)) {
+    units += charWidthUnit(char);
+  }
+
+  return units * fontSize * 1.08;
+}
+
+function charWidthUnit(char) {
+  if (/\s/.test(char)) return 0.34;
+  if (/[ilI.,'!:;|]/.test(char)) return 0.34;
+  if (/[fjrt()\[\]{}]/.test(char)) return 0.46;
+  if (/[mwMW@#%&]/.test(char)) return 0.92;
+  if (/[A-Z0-9]/.test(char)) return 0.66;
+  if (char.codePointAt(0) > 0x2e7f) return 1;
+  return 0.58;
+}
+
+function resolveCaptionColors({ zone, raw, settings }) {
+  if (settings.textColor !== 'auto') {
+    return {
+      fill: settings.textColor,
+      stroke: settings.strokeColor === 'auto' ? oppositeColor(settings.textColor) : settings.strokeColor
+    };
+  }
+
+  const luminance = averageLuminance(raw, zone);
+  const fill = luminance < settings.autoColorThreshold ? '#ffffff' : '#000000';
+  const stroke = settings.strokeColor === 'auto' ? oppositeColor(fill) : settings.strokeColor;
+
+  return { fill, stroke };
+}
+
+function averageLuminance(raw, zone) {
+  const { data, info } = raw;
+  const channels = info.channels;
+  const xStart = Math.max(0, Math.floor(zone.x));
+  const yStart = Math.max(0, Math.floor(zone.y));
+  const xEnd = Math.min(info.width, Math.ceil(zone.x + zone.width));
+  const yEnd = Math.min(info.height, Math.ceil(zone.y + zone.height));
+  const sampleStep = Math.max(1, Math.floor(Math.sqrt(((xEnd - xStart) * (yEnd - yStart)) / 1200)));
+  let total = 0;
+  let count = 0;
+
+  for (let y = yStart; y < yEnd; y += sampleStep) {
+    for (let x = xStart; x < xEnd; x += sampleStep) {
+      const index = (y * info.width + x) * channels;
+      const red = data[index];
+      const green = data[index + 1];
+      const blue = data[index + 2];
+      total += 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+      count += 1;
+    }
+  }
+
+  return count ? total / count : 255;
+}
+
+function oppositeColor(color) {
+  if (String(color).toLowerCase() === '#000000' || String(color).toLowerCase() === 'black') {
+    return '#ffffff';
+  }
+  return '#000000';
+}
+
+function normalizeText(text, uppercase) {
+  const value = String(text ?? '')
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.trim().replace(/\s+/g, ' '))
+    .join('\n')
+    .trim();
+
+  return uppercase ? value.toUpperCase() : value;
+}
+
+function positiveNumber(value, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`${name} must be a positive number.`);
+  }
+  return number;
+}
+
+function clampNumber(value, min, max, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(max, Math.max(min, number));
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function formatNumber(value) {
+  return Number.parseFloat(Number(value).toFixed(3)).toString();
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ghuts/memegen",
+  "version": "1.0.0",
+  "description": "A JavaScript module for creating memes with Sharp, bundled Anton font, automatic text wrapping, and shrink-to-fit captions.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "memegen": "cli.js",
+    "meme-generator": "cli.js"
+  },
+  "files": [
+    "assets/",
+    "cli.js",
+    "examples/",
+    "index.d.ts",
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "scripts/"
+  ],
+  "scripts": {
+    "check": "node --check index.js && node --check cli.js && node --check examples/demo.js",
+    "demo": "node examples/demo.js",
+    "test": "node scripts/smoke-test.js"
+  },
+  "keywords": [
+    "meme",
+    "meme-generator",
+    "sharp",
+    "image",
+    "caption",
+    "canvas",
+    "nodejs"
+  ],
+  "author": "ghuts",
+  "license": "MIT AND OFL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yeweroooo/memegen.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yeweroooo/memegen/issues"
+  },
+  "homepage": "https://github.com/yeweroooo/memegen#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "opentype.js": "^2.0.0",
+    "sharp": "^0.34.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/smoke-test.js

@@ -0,0 +1,44 @@
+import { strict as assert } from 'node:assert';
+import sharp from 'sharp';
+import { layoutMemeText, renderMeme } from '../index.js';
+
+const background = await sharp({
+  create: {
+    width: 640,
+    height: 360,
+    channels: 3,
+    background: '#f8f8f8'
+  }
+}).png().toBuffer();
+
+const rendered = await renderMeme({
+  background,
+  topText: 'when the render works',
+  bottomText: 'long captions should wrap safely',
+  format: 'png'
+});
+
+assert.equal(rendered.width, 640);
+assert.equal(rendered.height, 360);
+assert.equal(rendered.format, 'png');
+assert.ok(rendered.buffer.length > 0);
+assert.ok(rendered.top.lines.length >= 1);
+assert.ok(rendered.bottom.lines.length >= 1);
+assert.ok(rendered.top.maxLineWidth <= rendered.top.zone.width);
+assert.ok(rendered.bottom.maxLineWidth <= rendered.bottom.zone.width);
+
+const metadata = await sharp(rendered.buffer).metadata();
+assert.equal(metadata.width, 640);
+assert.equal(metadata.height, 360);
+
+const layout = layoutMemeText({
+  width: 640,
+  height: 360,
+  topText: 'a very long top sentence that must fit',
+  bottomText: 'a very long bottom sentence that must wrap without crossing image bounds'
+});
+
+assert.ok(layout.top.maxLineWidth <= layout.top.zone.width);
+assert.ok(layout.bottom.maxLineWidth <= layout.bottom.zone.width);
+
+console.log('OK: smoke test passed');