@stacksjs/image 0.70.232 → 0.70.234

package/dist/app-icons.d.ts

@@ -0,0 +1,15 @@
+import type { AppIconResult, FaviconResult } from 'ts-images';
+import type { ImagesConfig } from '@stacksjs/types';
+export declare function generateAppIconSet(images: ImagesConfig, root?: string): Promise<AppIconSetResult>;
+/**
+ * Generate the platform icon sets from one square source.
+ *
+ * The failure mode this removes is an icon set that is complete on the day it
+ * is made and incomplete forever after: Apple adds a size, the favicon set
+ * misses the one format a browser wants, and nobody notices because each file
+ * was placed by hand. From one source, all of them regenerate together.
+ */
+export declare interface AppIconSetResult {
+  icons: AppIconResult[]
+  favicons: FaviconResult[]
+}

package/dist/app-icons.js

@@ -0,0 +1,13 @@
+import process from "node:process";
+import { generateAppIcons, generateFavicons } from "ts-images";
+import { projectFile } from "./theme";
+export async function generateAppIconSet(images, root = process.cwd()) {
+  const appIcons = images.appIcons;
+  if (appIcons?.enabled !== !0 || !appIcons.source)
+    return { icons: [], favicons: [] };
+  const source = projectFile(appIcons.source, root), platforms = appIcons.platforms?.length ? appIcons.platforms : ["ios", "macos"], icons = await generateAppIcons(source, {
+    outputDir: projectFile(appIcons.outputDir ?? "resources/app-icons", root),
+    platform: platforms.length === 1 ? platforms[0] : "all"
+  }), favicons = appIcons.favicon ? await generateFavicons(source, projectFile(appIcons.faviconDir ?? "public", root)) : [];
+  return { icons, favicons };
+}

package/dist/app-store.d.ts

@@ -0,0 +1,14 @@
+import type { AppStoreDisplay, ImagesConfig } from '@stacksjs/types';
+/**
+ * Generate the App Store screenshot set a project declares.
+ *
+ * App Store Connect takes ten screenshots per device class and most listings
+ * ship one, because keeping ten in step with the product — across iPhone, iPad
+ * and Mac, every release — is not something anyone does by hand twice. Declared
+ * as slides, they regenerate from fresh captures whenever the app changes.
+ *
+ * Returns the paths keyed by display type, which is the shape
+ * `extension.safariAppStore.screenshots` takes, so the result can be handed
+ * straight to the upload step.
+ */
+export declare function generateAppStoreScreenshotSet(images: ImagesConfig, root?: string): Promise<Partial<Record<AppStoreDisplay, string[]>>>;

package/dist/app-store.js

@@ -0,0 +1,45 @@
+import { mkdir } from "node:fs/promises";
+import process from "node:process";
+import { APP_STORE_MAX_SCREENSHOTS, generateAppStoreScreenshots } from "ts-images";
+import { loadFonts } from "./fonts";
+import { background, color, device, markPainter, projectFile, themed } from "./theme";
+export async function generateAppStoreScreenshotSet(images, root = process.cwd()) {
+  if (images.appStore?.enabled !== !0 || !images.appStore.slides?.length)
+    return {};
+  const appStore = themed(images, images.appStore), declared = images.appStore.slides, displays = appStore.displays?.length ? appStore.displays : ["APP_IPHONE_67"], fonts = await loadFonts(images.fonts, root), outputDir = projectFile(appStore.outputDir ?? "resources/app-store/screenshots", root);
+  await mkdir(outputDir, { recursive: !0 });
+  const shared = {
+    outputDir,
+    titleFont: fonts.title,
+    bodyFont: fonts.body,
+    brand: appStore.brand,
+    drawMark: await markPainter(appStore.mark, root),
+    markPlate: appStore.markPlate === !1 ? void 0 : color(appStore.markPlate),
+    background: background(appStore.background, root),
+    color: color(appStore.color),
+    mutedColor: color(appStore.mutedColor),
+    device: device(appStore.device),
+    layout: appStore.layout,
+    format: appStore.format ?? "png",
+    quality: appStore.quality
+  }, results = {};
+  for (const display of displays) {
+    const slides = declared.filter((slide) => !slide.displays?.length || slide.displays.includes(display)).map((slide) => ({
+      capture: projectFile(slide.capture, root),
+      headline: slide.headline,
+      subheadline: slide.subheadline,
+      background: background(slide.background, root)
+    }));
+    if (!slides.length)
+      continue;
+    if (slides.length > APP_STORE_MAX_SCREENSHOTS)
+      throw Error(`[image] ${display} has ${slides.length} slides; App Store Connect accepts at most ${APP_STORE_MAX_SCREENSHOTS}`);
+    const rendered = await generateAppStoreScreenshots({
+      ...shared,
+      slides,
+      displayTypes: [display]
+    });
+    results[display] = rendered[display] ?? [];
+  }
+  return results;
+}

package/dist/fonts.d.ts

@@ -0,0 +1,21 @@
+import type { Font } from 'ts-images';
+import type { ImageFontConfig } from '@stacksjs/types';
+export declare function resolveFontPath(value: string, root?: string): string;
+export declare function loadFonts(fonts: ImageFontConfig | undefined, root?: string): Promise<ResolvedFonts>;
+/**
+ * Resolve the faces the generators draw with.
+ *
+ * The renderer reads TrueType outlines directly — no browser, no system font
+ * stack — so the face has to be a file the project actually ships or depends
+ * on. Reaching for whatever the machine happens to have installed would make
+ * a card render differently in CI than on a laptop, which is worse than not
+ * rendering at all.
+ *
+ * A configured value may be a project-relative path or a module specifier, so
+ * a font that arrives as a dependency (`@expo-google-fonts/inter/Inter_700Bold
+ * .ttf`) works without vendoring the binary into the repository.
+ */
+export declare interface ResolvedFonts {
+  title: Font
+  body: Font
+}

package/dist/fonts.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { loadFont } from "ts-images";
+export function resolveFontPath(value, root = process.cwd()) {
+  if (isAbsolute(value))
+    return value;
+  const local = resolve(root, value);
+  if (existsSync(local))
+    return local;
+  try {
+    return Bun.resolveSync(value, root);
+  } catch {
+    throw Error(`[image] Font not found: ${value}
+Looked for ${local} and for a module resolvable from ${root}.
+Set \`images.fonts.title\` in config/images.ts to a TrueType (.ttf) file. OpenType/CFF (.otf) and WOFF2 are not TrueType outlines and cannot be read.`);
+  }
+}
+export async function loadFonts(fonts, root = process.cwd()) {
+  if (!fonts?.title)
+    throw Error("[image] No font configured. Set `images.fonts.title` in config/images.ts to a TrueType (.ttf) file \u2014 " + "generated cards and screenshots draw real glyphs and cannot fall back to a system face.");
+  const title = loadFont(new Uint8Array(await readFile(resolveFontPath(fonts.title, root)))), body = fonts.body ? loadFont(new Uint8Array(await readFile(resolveFontPath(fonts.body, root)))) : title;
+  return { title, body };
+}

package/dist/generate.d.ts

@@ -0,0 +1,25 @@
+import type { AppIconSetResult } from './app-icons';
+import type { AppStoreDisplay, ImagesConfig } from '@stacksjs/types';
+import type { SocialCardResult } from './social';
+export declare function generateImages(images: ImagesConfig, options?: GenerateImagesOptions): Promise<GenerateImagesResult>;
+/** Count what a run produced, for a one-line summary on the CLI. */
+export declare function countGeneratedImages(result: GenerateImagesResult): { social: number, appStore: number, appIcons: number };
+export declare interface GenerateImagesResult {
+  social: SocialCardResult[]
+  appStore: Partial<Record<AppStoreDisplay, string[]>>
+  appIcons: AppIconSetResult
+}
+export declare interface GenerateImagesOptions {
+  only?: ImageTarget[]
+  root?: string
+}
+/**
+ * Run every image generator a project has declared.
+ *
+ * The three are independent — a site with cards has no App Store listing, an
+ * app with a listing may not have a marketing site — so each is skipped
+ * silently when it is not configured. What they share is the reason for
+ * existing at all: generated imagery goes stale without anyone noticing,
+ * because nothing fails when it does.
+ */
+export type ImageTarget = 'social' | 'app-store' | 'app-icons';

package/dist/generate.js

@@ -0,0 +1,19 @@
+import process from "node:process";
+import { generateAppIconSet } from "./app-icons";
+import { generateAppStoreScreenshotSet } from "./app-store";
+import { generateSocialCardSet } from "./social";
+export async function generateImages(images, options = {}) {
+  const root = options.root ?? process.cwd(), wanted = (target) => !options.only?.length || options.only.includes(target);
+  return {
+    social: wanted("social") ? await generateSocialCardSet(images, root) : [],
+    appStore: wanted("app-store") ? await generateAppStoreScreenshotSet(images, root) : {},
+    appIcons: wanted("app-icons") ? await generateAppIconSet(images, root) : { icons: [], favicons: [] }
+  };
+}
+export function countGeneratedImages(result) {
+  return {
+    social: result.social.reduce((total, card) => total + Object.keys(card.files).length, 0),
+    appStore: Object.values(result.appStore).reduce((total, paths) => total + (paths?.length ?? 0), 0),
+    appIcons: result.appIcons.icons.reduce((total, set) => total + set.sizes.length, 0) + result.appIcons.favicons.length
+  };
+}

package/dist/index.d.ts

@@ -26,3 +26,13 @@ export declare class ImageBuilder {
   storage(adapter: ImageStorageAdapter, prefix?: string): this;
   generate(): Promise<ImageManifest>;
 }
+// Generated imagery: social cards, App Store screenshots, app icons. Declared
+// in `config/images.ts` and produced by `buddy generate:images`. Kept in this
+// package rather than a build script because the same wrappers back the CLI,
+// the build pipeline, and anything a project wants to call directly.
+export * from './app-icons';
+export * from './app-store';
+export * from './fonts';
+export * from './generate';
+export * from './social';
+export * from './theme';

package/dist/index.js

@@ -2,6 +2,13 @@ import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto
 import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { basename, extname, isAbsolute, relative, resolve } from "node:path";
 import { decode, encode, imageToSplatHash, resize } from "ts-images";
+
+export * from "./app-icons";
+export * from "./app-store";
+export * from "./fonts";
+export * from "./generate";
+export * from "./social";
+export * from "./theme";
 const mime = { avif: "image/avif", webp: "image/webp", jpeg: "image/jpeg", png: "image/png" };
 function integer(name, value, min, max) {
   if (!Number.isInteger(value) || value < min || value > max)

package/dist/social.d.ts

@@ -0,0 +1,38 @@
+import type { ImagesConfig } from '@stacksjs/types';
+/**
+ * Name a card after its route.
+ *
+ * `/` is the site-wide card and keeps the bare `og` name so its URL never
+ * moves; everything else is its path with the separators flattened, which
+ * makes the file recognisable in a directory listing and stable across
+ * regenerations.
+ */
+export declare function socialCardName(path: string): string;
+export declare function generateSocialCardSet(images: ImagesConfig, root?: string): Promise<SocialCardResult[]>;
+/**
+ * The meta tags a page needs so a scraper renders the card at full size.
+ *
+ * Emitting the image alone is not enough: X falls back to a small square
+ * thumbnail unless `twitter:card` says otherwise, and a scraper that cannot
+ * fetch the image has nothing to reserve layout with unless the dimensions are
+ * declared alongside it.
+ */
+export declare function socialMetaTags(card: SocialCardResult, siteUrl: string, format?: 'jpeg' | 'png' | 'webp' | 'avif'): string[];
+/**
+ * Generate the link-preview cards a site declares.
+ *
+ * The failure this addresses is mundane and universal: a page ships with its
+ * favicon as `og:image`, so every share of it renders as a small square icon
+ * next to the URL, and the preview — the only part of the page most people
+ * ever see — says nothing. Declaring cards in `config/images.ts` and building
+ * them with the site keeps them right as the copy changes.
+ */
+export declare interface SocialCardResult {
+  path: string
+  name: string
+  files: Record<string, string>
+  urls: Record<string, string>
+  width: number
+  height: number
+  title: string
+}

package/dist/social.js

@@ -0,0 +1,85 @@
+import { mkdir } from "node:fs/promises";
+import process from "node:process";
+import { generateSocialCards } from "ts-images";
+import { loadFonts } from "./fonts";
+import { background, color, device, markPainter, projectFile, themed } from "./theme";
+const PRESET_SIZES = {
+  og: { width: 1200, height: 630 },
+  twitter: { width: 1200, height: 600 },
+  square: { width: 1200, height: 1200 },
+  portrait: { width: 1200, height: 1500 }
+};
+export function socialCardName(path) {
+  const trimmed = path.replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? "og" : trimmed.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+}
+export async function generateSocialCardSet(images, root = process.cwd()) {
+  if (images.social?.enabled !== !0)
+    return [];
+  const social = themed(images, images.social), fonts = await loadFonts(images.fonts, root), outputDir = projectFile(social.outputDir ?? "public/social", root), publicPath = `/${(social.publicPath ?? "/social").replace(/^\/+|\/+$/g, "")}`, presets = social.presets?.length ? social.presets : ["og", "square", "portrait"], format = social.format ?? "jpeg";
+  await mkdir(outputDir, { recursive: !0 });
+  const drawMark = await markPainter(social.mark, root), shared = {
+    titleFont: fonts.title,
+    bodyFont: fonts.body,
+    brand: social.brand,
+    drawMark,
+    markPlate: social.markPlate === !1 ? void 0 : color(social.markPlate),
+    surface: background(social.background, root),
+    color: color(social.color),
+    mutedColor: color(social.mutedColor),
+    accent: color(social.accent),
+    format,
+    quality: social.quality,
+    presets
+  }, pages = social.pages?.length ? social.pages : [{ path: "/", title: social.brand ?? "Home" }], deviceOptions = device(social.device), results = [];
+  for (const page of pages) {
+    const name = socialCardName(page.path), shot = page.foreground ?? social.foreground, files = await generateSocialCards(outputDir, {
+      ...shared,
+      name,
+      title: page.title,
+      eyebrow: page.eyebrow,
+      subtitle: page.subtitle,
+      foreground: shot ? {
+        image: projectFile(shot, root),
+        radius: deviceOptions?.radius,
+        borderColor: deviceOptions?.borderColor,
+        shadow: deviceOptions?.shadow,
+        scale: deviceOptions?.scale
+      } : void 0
+    }), urls = Object.fromEntries(Object.entries(files).map(([preset, file]) => [
+      preset,
+      `${publicPath}/${file.slice(file.lastIndexOf("/") + 1)}`
+    ]));
+    results.push({
+      path: page.path,
+      name,
+      files,
+      urls,
+      width: PRESET_SIZES[presets[0]].width,
+      height: PRESET_SIZES[presets[0]].height,
+      title: page.title
+    });
+  }
+  return results;
+}
+export function socialMetaTags(card, siteUrl, format = "jpeg") {
+  const base = siteUrl.replace(/\/+$/, ""), primary = `${base}${card.urls.og ?? Object.values(card.urls)[0]}`, mimeType = format === "jpeg" ? "image/jpeg" : `image/${format}`, tags = [
+    `<meta property="og:image" content="${primary}">`,
+    `<meta property="og:image:type" content="${mimeType}">`,
+    `<meta property="og:image:width" content="${card.width}">`,
+    `<meta property="og:image:height" content="${card.height}">`,
+    `<meta property="og:image:alt" content="${escapeAttribute(card.title)}">`,
+    '<meta name="twitter:card" content="summary_large_image">',
+    `<meta name="twitter:image" content="${primary}">`,
+    `<meta name="twitter:image:alt" content="${escapeAttribute(card.title)}">`
+  ];
+  for (const [preset, url] of Object.entries(card.urls)) {
+    if (preset === "og")
+      continue;
+    tags.push(`<meta property="og:image" content="${base}${url}">`);
+  }
+  return tags;
+}
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/theme.d.ts

@@ -0,0 +1,45 @@
+import type { ImageBackgroundConfig, ImageColor, ImageDeviceConfig, ImagesConfig } from '@stacksjs/types';
+import type { ImageData, RGBA, SurfaceBackground } from 'ts-images';
+/**
+ * Turn the declarative half of `config/images.ts` into the shapes ts-images
+ * takes.
+ *
+ * Configuration carries colours as strings and paths as project-relative, both
+ * of which have to become something concrete before a pixel is drawn. Doing it
+ * in one place means the three generators agree on what `background` means,
+ * which is the point of having a shared palette at all.
+ */
+export declare function projectFile(path: string, root?: string): string;
+export declare function color(value: ImageColor | undefined): RGBA | undefined;
+export declare function background(value: ImageBackgroundConfig | undefined, root?: string): SurfaceBackground | undefined;
+/**
+ * `shadow` is tri-state in configuration and in the renderer: absent means
+ * "the default shadow", `false` means "none", and an object means "this one".
+ * `undefined` cannot express the middle case, so the translation is explicit.
+ */
+export declare function device(value: ImageDeviceConfig | undefined): {
+  radius?: number
+  borderColor?: RGBA
+  scale?: number
+  shadow?: { blur?: number, offsetX?: number, offsetY?: number, spread?: number, color?: RGBA }
+} | undefined;
+/**
+ * Build a `drawMark` callback from an image path.
+ *
+ * ts-images hands back a box and lets the caller paint the mark, because a
+ * library cannot know what a brand's mark looks like. For a Stacks project it
+ * is nearly always a file already in the repository — the app icon — so the
+ * callback is just a placement.
+ */
+export declare function markPainter(path: string | undefined, root?: string): Promise<((canvas: ImageData, box: { x: number, y: number, size: number }) => void) | undefined>;
+/** Fold the shared palette into a generator's own, letting the generator win. */
+export declare function themed<T extends ImageTheme>(images: ImagesConfig, section: T | undefined): T & ImageTheme;
+/** The palette keys a generator inherits from the top level of the config. */
+export declare interface ImageTheme {
+  background?: ImageBackgroundConfig
+  color?: ImageColor
+  mutedColor?: ImageColor
+  device?: ImageDeviceConfig
+  brand?: string
+  mark?: string
+}

package/dist/theme.js

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { decode, drawImage, parseColor } from "ts-images";
+export function projectFile(path, root = process.cwd()) {
+  return isAbsolute(path) ? path : resolve(root, path);
+}
+export function color(value) {
+  return value === void 0 ? void 0 : parseColor(value);
+}
+export function background(value, root = process.cwd()) {
+  if (!value)
+    return;
+  return {
+    color: color(value.color),
+    gradient: value.gradient && {
+      angle: value.gradient.angle,
+      stops: value.gradient.stops.map((stop) => ({ offset: stop.offset, color: parseColor(stop.color) }))
+    },
+    glows: value.glows?.map((glow) => ({ ...glow, color: parseColor(glow.color) })),
+    image: value.image ? projectFile(value.image, root) : void 0
+  };
+}
+export function device(value) {
+  if (!value)
+    return;
+  return {
+    radius: value.radius,
+    scale: value.scale,
+    borderColor: color(value.borderColor),
+    shadow: value.shadow === !1 ? void 0 : { ...value.shadow ?? {}, color: color(value.shadow?.color) }
+  };
+}
+export async function markPainter(path, root = process.cwd()) {
+  if (!path)
+    return;
+  const mark = await decode(new Uint8Array(await readFile(projectFile(path, root))));
+  return (canvas, box) => {
+    drawImage(canvas, mark, { x: box.x, y: box.y, width: box.size, height: box.size, fit: "contain" });
+  };
+}
+export function themed(images, section) {
+  return {
+    ...section ?? {},
+    background: section?.background ?? images.background,
+    color: section?.color ?? images.color,
+    mutedColor: section?.mutedColor ?? images.mutedColor,
+    device: section?.device ?? images.device,
+    brand: section?.brand ?? images.brand,
+    mark: section?.mark ?? images.mark
+  };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/image",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.232",
+  "version": "0.70.234",
   "description": "Native responsive image delivery for Stacks.",
   "author": "Chris Breuer",
   "license": "MIT",
@@ -15,7 +15,6 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
       "bun": "./dist/index.js",
       "import": "./dist/index.js"
     }
@@ -32,7 +31,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "ts-images": "^0.2.1"
+    "@stacksjs/types": "0.70.234",
+    "ts-images": "^0.2.6"
   },
   "devDependencies": {
     "better-dx": "^0.2.17"