@softure-ai/core 0.1.10 → 0.2.0

package/src/format.ts

@@ -1,10 +1,12 @@
 // Days, money and percentages as people read them, one way for every module and app. A calendar day
-// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it.
+// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it. Every
+// formatter takes any BCP 47 locale tag (an invalid one throws Intl's RangeError); the only built-in
+// copy is English, and an app passes its own words where a formatter writes any.
 import { isCalendarDay } from "./calendar-day.js";
 import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
-import type { Locale } from "./i18n.js";
+import { formatMessage, selectPlural, type PluralForms } from "./i18n.js";
 
-/** `long`: October 4, 2026 (pl names the month in the genitive); `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (pl: 04.10.2026). */
+/** `long`: October 4, 2026; `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (each locale writes its own order and separators). */
 export type CalendarDayStyle = "long" | "medium" | "numeric";
 
 export interface FormatMoneyOptions {
@@ -16,8 +18,49 @@ export interface FormatMoneyOptions {
   readonly compact?: boolean;
 }
 
+/** `long`: October 2026; `roman`: X 2026. */
+export type CalendarMonthStyle = "long" | "roman";
+
+/** The words `formatDuration` writes: plural forms with `{count}`, and `both` joining `{years}` and `{months}`. */
+export interface DurationMessages {
+  readonly years: PluralForms;
+  readonly months: PluralForms;
+  readonly both: string;
+}
+
+export interface FormatDurationOptions {
+  /** The BCP 47 tag whose plural rules pick a form (default `"en"`). */
+  readonly locale?: string;
+  /** The app's own words (default `DEFAULT_DURATION_MESSAGES`, English). */
+  readonly messages?: DurationMessages;
+}
+
+export interface FormatPercentOptions {
+  /** A `+` before a positive value (a `-` before a negative one is always there). Zero has neither in any mode. */
+  readonly signed?: boolean;
+  /** No space between the number and `%`, whatever the locale's pattern: `12,5%`, not `12,5 %`. */
+  readonly tight?: boolean;
+  /**
+   * Exactly this many fraction digits, an integer from 0 to 20: `{ fractionDigits: 2 }` writes 1900 as `19.00%`.
+   * Without it a value has at most two fraction digits and no trailing zeros.
+   */
+  readonly fractionDigits?: number;
+}
+
+const MONTHS_PER_YEAR = 12;
+const MONTH_PATTERN = /^(\d{4})-(\d{2})$/;
+const ROMAN_MONTHS = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X", "XI", "XII"] as const;
+
+/** The built-in, English words of `formatDuration`; any other category falls back to `other`. */
+export const DEFAULT_DURATION_MESSAGES: DurationMessages = {
+  years: { one: "{count} year", other: "{count} years" },
+  months: { one: "{count} month", other: "{count} months" },
+  both: "{years} and {months}",
+};
+
 const BASIS_POINTS_PER_UNIT = 10_000;
 const MAX_PERCENT_FRACTION_DIGITS = 2;
+const FRACTION_DIGITS_LIMIT = 20;
 
 const dayFormatters = new Map<string, Intl.DateTimeFormat>();
 const numberFormatters = new Map<string, Intl.NumberFormat>();
@@ -29,25 +72,61 @@ const DAY_STYLE_OPTIONS: Readonly<Record<CalendarDayStyle, Intl.DateTimeFormatOp
 };
 
 /** A `YYYY-MM-DD` day as `locale` writes it. Throws a `RangeError` for a malformed day. */
-export function formatCalendarDay(day: string, locale: Locale, style: CalendarDayStyle = "long"): string {
+export function formatCalendarDay(day: string, locale: string, style: CalendarDayStyle = "long"): string {
   if (!isCalendarDay(day)) throw new RangeError(`formatCalendarDay: "${String(day)}" is not a YYYY-MM-DD calendar day`);
-  const key = `${locale}:${style}`;
-  let format = dayFormatters.get(key);
-  if (format === undefined) {
-    format = new Intl.DateTimeFormat(locale, { ...DAY_STYLE_OPTIONS[style], timeZone: "UTC" });
-    dayFormatters.set(key, format);
+  return getDayFormatter(`${locale}:${style}`, locale, DAY_STYLE_OPTIONS[style]).format(new Date(`${day}T00:00:00Z`));
+}
+
+/** Whether `value` is a real calendar month written `YYYY-MM` (`2026-13` and `2026-1` are not). */
+export function isCalendarMonth(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = MONTH_PATTERN.exec(value);
+  if (match === null) return false;
+  const month = Number(match[2]);
+  return month >= 1 && month <= MONTHS_PER_YEAR;
+}
+
+/**
+ * The month of a `YYYY-MM` month or a `YYYY-MM-DD` day, with its year, as `locale` writes it alone. Throws a
+ * `RangeError` for anything else.
+ */
+export function formatCalendarMonth(month: string, locale: string, style: CalendarMonthStyle = "long"): string {
+  const firstDay = isCalendarMonth(month) ? `${month}-01` : month;
+  if (!isCalendarDay(firstDay)) throw new RangeError(`formatCalendarMonth: "${String(month)}" is not a YYYY-MM month or a YYYY-MM-DD day`);
+  const date = new Date(`${firstDay}T00:00:00Z`);
+  const year = firstDay.slice(0, 4);
+  if (style === "roman") return `${ROMAN_MONTHS[date.getUTCMonth()] ?? ""} ${year}`;
+  return getDayFormatter(`${locale}:month`, locale, { month: "long", year: "numeric" }).format(date);
+}
+
+/**
+ * Whole months as years and months: 38 is "3 years and 2 months"; a part that is zero is left out, and zero itself is
+ * "0 months". English by default; an app passes its own `messages` and the `locale` whose plural rules pick among
+ * them. Throws a `RangeError` for a negative or fractional count, or an invalid locale tag.
+ */
+export function formatDuration(months: number, options: FormatDurationOptions = {}): string {
+  if (!Number.isSafeInteger(months) || months < 0) {
+    throw new RangeError(`formatDuration: ${String(months)} is not a whole, non-negative number of months`);
   }
-  return format.format(new Date(`${day}T00:00:00Z`));
+  const locale = options.locale ?? "en";
+  const copy = options.messages ?? DEFAULT_DURATION_MESSAGES;
+  const years = Math.floor(months / MONTHS_PER_YEAR);
+  const rest = months % MONTHS_PER_YEAR;
+  const yearsText = formatMessage(selectPlural(locale, years, copy.years), { count: years });
+  const monthsText = formatMessage(selectPlural(locale, rest, copy.months), { count: rest });
+  if (years === 0) return monthsText;
+  if (rest === 0) return yearsText;
+  return formatMessage(copy.both, { years: yearsText, months: monthsText });
 }
 
 /**
  * An amount in the currency's minor unit (2900 PLN = PLN 29.00) in `locale`'s notation, thousands always
- * grouped (pl writes 1 234,56 where its default would leave four digits together), and zero is never signed (`-0`
+ * grouped (even where a locale's default would leave four digits together), and zero is never signed (`-0`
  * and an amount that rounds to zero show as zero). The minor unit is the pinned ISO
  * 4217 one (`CURRENCY_MINOR_UNIT_DIGITS`); a code outside the table gets `Intl`'s digits. Throws a
  * `RangeError` for an amount that is not a whole number of minor units, or a code `Intl` refuses.
  */
-export function formatMoney(minor: number, currency: string, locale: Locale, options: FormatMoneyOptions = {}): string {
+export function formatMoney(minor: number, currency: string, locale: string, options: FormatMoneyOptions = {}): string {
   if (!Number.isSafeInteger(minor)) throw new RangeError(`formatMoney: ${String(minor)} is not a whole number of minor units`);
   const pinned = Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
   const digits = pinned ?? getNumberFormatter(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
@@ -62,14 +141,49 @@ export function formatMoney(minor: number, currency: string, locale: Locale, opt
   return format.format(minor / 10 ** digits);
 }
 
-/** Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits. Throws a `RangeError` for a non-finite value. */
-export function formatPercent(basisPoints: number, locale: Locale): string {
+/**
+ * Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits unless `fractionDigits` fixes
+ * them, and zero is never signed (`-0` and a value that rounds to zero show as `0%`, or `0.0%` at one digit). Throws a
+ * `RangeError` for a non-finite value or an invalid `fractionDigits`.
+ */
+export function formatPercent(basisPoints: number, locale: string, options: FormatPercentOptions = {}): string {
   if (!Number.isFinite(basisPoints)) throw new RangeError(`formatPercent: ${String(basisPoints)} is not a finite number of basis points`);
-  const format = getNumberFormatter(locale, { style: "percent", maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS });
-  return format.format(basisPoints / BASIS_POINTS_PER_UNIT);
+  const format = getNumberFormatter(locale, {
+    style: "percent",
+    ...getPercentFractionDigits(options.fractionDigits),
+    signDisplay: options.signed === true ? "exceptZero" : "negative",
+  });
+  const value = basisPoints / BASIS_POINTS_PER_UNIT;
+  if (options.tight !== true) return format.format(value);
+  const parts = format.formatToParts(value);
+  return parts
+    .filter((part, index) => !(part.type === "literal" && part.value.trim() === "" && isNextToPercentSign(parts, index)))
+    .map((part) => part.value)
+    .join("");
+}
+
+function getPercentFractionDigits(fractionDigits: number | undefined): Intl.NumberFormatOptions {
+  if (fractionDigits === undefined) return { maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS };
+  if (!Number.isInteger(fractionDigits) || fractionDigits < 0 || fractionDigits > FRACTION_DIGITS_LIMIT) {
+    throw new RangeError(`formatPercent: fractionDigits ${String(fractionDigits)} is not an integer from 0 to ${String(FRACTION_DIGITS_LIMIT)}`);
+  }
+  return { minimumFractionDigits: fractionDigits, maximumFractionDigits: fractionDigits };
+}
+
+function isNextToPercentSign(parts: readonly Intl.NumberFormatPart[], index: number): boolean {
+  return parts[index - 1]?.type === "percentSign" || parts[index + 1]?.type === "percentSign";
+}
+
+function getDayFormatter(key: string, locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  let format = dayFormatters.get(key);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" });
+    dayFormatters.set(key, format);
+  }
+  return format;
 }
 
-function getNumberFormatter(locale: Locale, options: Intl.NumberFormatOptions): Intl.NumberFormat {
+function getNumberFormatter(locale: string, options: Intl.NumberFormatOptions): Intl.NumberFormat {
   const key = `${locale}:${JSON.stringify(options)}`;
   let format = numberFormatters.get(key);
   if (format === undefined) {

package/src/i18n.ts

@@ -1,9 +1,12 @@
-// Copy and localization (docs/02-module-standard.md §6): every module ships complete `en` and
-// `pl` dictionaries, and the app passes partial overrides per locale.
+// Copy and localization (docs/02-module-standard.md §6): every module ships a complete `en`
+// dictionary, the only built-in language. An app that shows another language passes its own
+// translation as overrides for its locale; a key it leaves out reads English.
 
-export const LOCALES = ["en", "pl"] as const;
+/** A BCP 47 language tag (`en`, `de-AT`). */
+export type Locale = string;
 
-export type Locale = (typeof LOCALES)[number];
+/** The language of every built-in dictionary and the fallback for any other locale. */
+export const DEFAULT_LOCALE = "en";
 
 /** A dictionary: nested groups of message strings. */
 export interface MessageTree {
@@ -13,11 +16,14 @@ export interface MessageTree {
 /** The same shape with every key optional, at every depth. */
 export type DeepPartial<T> = { [K in keyof T]?: T[K] extends string ? string : DeepPartial<T[K]> };
 
-/** One complete dictionary per locale. */
-export type Dictionaries<T extends MessageTree> = Readonly<Record<Locale, T>>;
+/** A complete `en` dictionary, plus complete dictionaries for any other locales. */
+export type Dictionaries<T extends MessageTree> = { readonly en: T } & { readonly [locale: string]: T | undefined };
 
-/** Partial overrides an app passes for some locales. */
-export type MessageOverrides<T extends MessageTree> = Partial<Record<Locale, DeepPartial<T>>>;
+/** Partial overrides an app passes per locale: a translation for its own locale, or changed English copy. */
+export type MessageOverrides<T extends MessageTree> = { readonly [locale: string]: DeepPartial<T> | undefined };
+
+/** A text an app writes per locale in its options (a plan name, a label); `en` is the fallback. */
+export type LocalizedText = { readonly [locale: string]: string | undefined };
 
 /** Plural forms named after the `Intl.PluralRules` categories; `other` is the fallback. */
 export interface PluralForms {
@@ -29,24 +35,49 @@ export interface PluralForms {
   readonly other: string;
 }
 
+/** Whether `value` is a well-formed BCP 47 language tag. */
 export function isLocale(value: unknown): value is Locale {
-  return LOCALES.some((locale) => locale === value);
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    return Intl.getCanonicalLocales(value).length === 1;
+  } catch {
+    // RangeError: not a well-formed tag.
+    return false;
+  }
 }
 
 /**
- * The defaults with the overrides applied, per locale. Only keys the defaults have are taken,
- * and a group is never replaced by a string, so an override cannot break the dictionary shape.
- * Inputs are not mutated.
+ * The defaults with the overrides applied, per locale: `en` and every locale the defaults or the
+ * overrides name. A locale without its own defaults is built on `en`, so a key its override leaves
+ * out reads English. Only keys the defaults have are taken, and a group is never replaced by a
+ * string, so an override cannot break the dictionary shape. Inputs are not mutated.
  */
 export function mergeMessages<T extends MessageTree>(
   defaults: Dictionaries<T>,
   overrides: MessageOverrides<T> = {},
 ): Dictionaries<T> {
-  const merged = {} as Record<Locale, T>;
-  for (const locale of LOCALES) {
-    merged[locale] = mergeTree(defaults[locale], overrides[locale]) as T;
+  const merged: Record<string, T> = {};
+  for (const locale of new Set([DEFAULT_LOCALE, ...Object.keys(defaults), ...Object.keys(overrides)])) {
+    merged[locale] = mergeTree(defaults[locale] ?? defaults.en, overrides[locale]) as T;
   }
-  return merged;
+  return merged as Dictionaries<T>;
+}
+
+/**
+ * The dictionary for `locale`: its own, else its language's (`pt-BR` reads `pt`), else `en`.
+ */
+export function selectMessages<T extends MessageTree>(dictionaries: Dictionaries<T>, locale: Locale): T {
+  return dictionaries[locale] ?? dictionaries[getLanguage(locale)] ?? dictionaries.en;
+}
+
+/** The text for `locale` with `selectMessages`' fallback order, or `fallback` when no locale has one. */
+export function pickLocalizedText(text: LocalizedText | undefined, locale: Locale, fallback = ""): string {
+  if (text === undefined) return fallback;
+  return text[locale] ?? text[getLanguage(locale)] ?? text.en ?? fallback;
+}
+
+function getLanguage(locale: Locale): string {
+  return locale.split("-")[0] ?? locale;
 }
 
 /** Fills `{name}` placeholders. A placeholder without a value stays as written. */
@@ -57,10 +88,13 @@ export function formatMessage(template: string, params: Readonly<Record<string,
   });
 }
 
-const pluralRulesByLocale = new Map<Locale, Intl.PluralRules>();
+const pluralRulesByLocale = new Map<string, Intl.PluralRules>();
 
-/** The form for `count` under the plural rules of `locale` ("1 file", "2 files"). */
-export function selectPlural(locale: Locale, count: number, forms: PluralForms): string {
+/**
+ * The form for `count` under the plural rules of `locale`, any BCP 47 tag ("1 file", "2 files"). A category the
+ * forms leave out falls back to `other`.
+ */
+export function selectPlural(locale: string, count: number, forms: PluralForms): string {
   let rules = pluralRulesByLocale.get(locale);
   if (rules === undefined) {
     rules = new Intl.PluralRules(locale);

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   addCalendarDays,
   addCalendarMonths,
   calendarDaysBetween,
+  calendarDaySchema,
   getCalendarDay,
   isCalendarDay,
   toCalendarDay,
@@ -11,18 +12,36 @@ export {
   type EndOfMonth,
 } from "./calendar-day.js";
 export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
-export { formatCalendarDay, formatMoney, formatPercent, type CalendarDayStyle, type FormatMoneyOptions } from "./format.js";
+export {
+  DEFAULT_DURATION_MESSAGES,
+  formatCalendarDay,
+  formatCalendarMonth,
+  formatDuration,
+  formatMoney,
+  formatPercent,
+  isCalendarMonth,
+  type CalendarDayStyle,
+  type CalendarMonthStyle,
+  type DurationMessages,
+  type FormatDurationOptions,
+  type FormatMoneyOptions,
+  type FormatPercentOptions,
+} from "./format.js";
+export { memoizeByContent, type MemoizeByContentOptions, type MemoizedFunction } from "./memoize.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export {
   formatMessage,
   getMessage,
+  DEFAULT_LOCALE,
   isLocale,
-  LOCALES,
   mergeMessages,
+  pickLocalizedText,
+  selectMessages,
   selectPlural,
   type DeepPartial,
   type Dictionaries,
   type Locale,
+  type LocalizedText,
   type MessageOverrides,
   type MessageTree,
   type PluralForms,

package/src/memoize.ts

@@ -0,0 +1,89 @@
+// A cache for pure functions of plain data: the arguments' content is the key, so two equal objects built apart hit
+// the same entry. Least recently used entries go beyond `max`; nothing expires by time.
+
+export interface MemoizeByContentOptions {
+  /** The most entries kept; the least recently used one goes first. */
+  readonly max: number;
+}
+
+/** `fn` with a cache, plus `clear()` to empty it. */
+export type MemoizedFunction<Args extends readonly unknown[], Value> = ((...args: Args) => Value) & { readonly clear: () => void };
+
+/**
+ * `fn` cached by the content of its arguments: primitives, arrays, `Date`s and plain objects (key order does not
+ * matter). An argument holding anything else (a function, a `Map`, a class instance, a cycle) throws a `TypeError`.
+ * A promise that rejects is dropped, so the next call tries again. Throws a `RangeError` for a `max` that is not a
+ * positive whole number.
+ */
+export function memoizeByContent<Args extends readonly unknown[], Value>(
+  fn: (...args: Args) => Value,
+  options: MemoizeByContentOptions,
+): MemoizedFunction<Args, Value> {
+  const { max } = options;
+  if (!Number.isSafeInteger(max) || max < 1) throw new RangeError(`memoizeByContent: max must be a positive whole number, got ${String(max)}`);
+  const cache = new Map<string, Value>();
+
+  const memoized = (...args: Args): Value => {
+    const key = toContentKey(args, new Set());
+    if (cache.has(key)) {
+      // Not `?? fn(...)`: a cached `undefined` is a hit too.
+      const hit = cache.get(key) as Value;
+      cache.delete(key);
+      cache.set(key, hit);
+      return hit;
+    }
+    const value = fn(...args);
+    cache.set(key, value);
+    if (cache.size > max) {
+      const oldest = cache.keys().next();
+      if (oldest.done !== true) cache.delete(oldest.value);
+    }
+    if (value instanceof Promise) {
+      value.catch(() => {
+        if (cache.get(key) === value) cache.delete(key);
+      });
+    }
+    return value;
+  };
+  return Object.assign(memoized, { clear: () => cache.clear() });
+}
+
+function toContentKey(value: unknown, path: Set<object>): string {
+  switch (typeof value) {
+    case "undefined":
+      return "u";
+    case "boolean":
+      return value ? "t" : "f";
+    case "number":
+      return `n${Object.is(value, -0) ? "-0" : String(value)}`;
+    case "bigint":
+      return `b${String(value)}`;
+    case "string":
+      return JSON.stringify(value);
+    case "object":
+      return value === null ? "null" : toObjectKey(value, path);
+    default:
+      throw new TypeError(`memoizeByContent: an argument holds a ${typeof value}, which has no content key`);
+  }
+}
+
+function toObjectKey(value: object, path: Set<object>): string {
+  if (value instanceof Date) return `d${String(value.getTime())}`;
+  if (path.has(value)) throw new TypeError("memoizeByContent: an argument holds a cycle");
+  path.add(value);
+  let key: string;
+  if (Array.isArray(value)) {
+    key = `[${value.map((item: unknown) => toContentKey(item, path)).join(",")}]`;
+  } else {
+    const prototype: unknown = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError(`memoizeByContent: an argument holds a ${value.constructor.name}, which has no content key`);
+    }
+    const entries = Object.keys(value)
+      .sort()
+      .map((name) => `${JSON.stringify(name)}:${toContentKey((value as Record<string, unknown>)[name], path)}`);
+    key = `{${entries.join(",")}}`;
+  }
+  path.delete(value);
+  return key;
+}

package/src/messages/index.ts

@@ -1,8 +1,7 @@
 import type { Dictionaries } from "../i18n.js";
 import { en } from "./en.js";
-import { pl } from "./pl.js";
 
 export type CoreMessages = typeof en;
 
 /** Copy for core's own error codes (`core.<key>` → `errors.<key>`). */
-export const coreMessages: Dictionaries<CoreMessages> = { en, pl };
+export const coreMessages: Dictionaries<CoreMessages> = { en };

package/src/og/index.ts

@@ -0,0 +1,12 @@
+// The OG card font loader: server only (it reads files), no `next/*` imports. `@softure-ai/seo/server` re-exports it
+// for an app's own `opengraph-image` routes, the blog for its article card.
+export {
+  createOgFontLoader,
+  loadOgFonts,
+  OG_FONT_WEIGHTS,
+  type OgFont,
+  type OgFontLoaderOptions,
+  type OgFontSource,
+  type OgFontsResult,
+  type OgFontWeight,
+} from "./og-fonts.js";

package/src/og/og-fonts.ts

@@ -0,0 +1,127 @@
+// The loader of an OG card's fonts: each source is read once, checked to be a font Satori draws (.ttf,
+// .otf, .woff; not .woff2), and kept for the life of the loader. A failed read is not kept, so a fixed
+// file is picked up by the next call. It imports no Next code, so a command-line check can run it too.
+// `@softure-ai/seo/server` and the blog re-export it.
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+/** The weights Satori (`next/og`) draws: static fonts only, in steps of 100. */
+export const OG_FONT_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900] as const;
+
+export type OgFontWeight = (typeof OG_FONT_WEIGHTS)[number];
+
+/** A font to read: a path (from the loader's root, or absolute) or an https URL, and how the card names it. */
+export interface OgFontSource {
+  readonly name: string;
+  readonly src: string;
+  readonly weight?: OgFontWeight;
+  readonly style?: "normal" | "italic";
+}
+
+/** A font for the card, as `ImageResponse` takes it. */
+export interface OgFont {
+  readonly name: string;
+  readonly data: ArrayBuffer;
+  readonly weight?: OgFontWeight;
+  readonly style?: "normal" | "italic";
+}
+
+export type OgFontsResult = { readonly ok: true; readonly fonts: readonly OgFont[] } | { readonly ok: false; readonly error: string };
+
+type BytesResult = { readonly ok: true; readonly data: ArrayBuffer } | { readonly ok: false; readonly reason: string };
+
+export interface OgFontLoaderOptions {
+  /** Where a relative path starts: the app's root. */
+  readonly root: string;
+  readonly readFile?: (path: string) => Promise<Uint8Array>;
+  readonly fetchImpl?: typeof fetch;
+  /** What a message names the list by, before `[index]`. Default: `OG card: fonts`. */
+  readonly label?: string;
+}
+
+const DEFAULT_LABEL = "OG card: fonts";
+
+/** The first four bytes of each font format Satori parses. */
+const FONT_SIGNATURES = ["wOFF", "OTTO", "\u0000\u0001\u0000\u0000", "true"];
+const WOFF2_SIGNATURE = "wOF2";
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+
+function checkFontBytes(bytes: Uint8Array): BytesResult {
+  const signature = String.fromCharCode(...bytes.subarray(0, 4));
+  if (signature === WOFF2_SIGNATURE) return { ok: false, reason: "a .woff2 font, which the card cannot read; use the .woff or .ttf file" };
+  if (!FONT_SIGNATURES.includes(signature)) return { ok: false, reason: "not a .ttf, .otf or .woff font" };
+  return { ok: true, data: toArrayBuffer(bytes) };
+}
+
+function getErrorCode(error: unknown): string {
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") return error.code;
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** A loader with its own cache, keyed by the resolved path or URL. */
+export function createOgFontLoader(options: OgFontLoaderOptions): (fonts: readonly OgFontSource[]) => Promise<OgFontsResult> {
+  const read = options.readFile ?? readFile;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const label = options.label ?? DEFAULT_LABEL;
+  const cache = new Map<string, Promise<BytesResult>>();
+
+  async function readSource(location: string, isUrl: boolean): Promise<BytesResult> {
+    if (!isUrl) {
+      try {
+        return checkFontBytes(await read(location));
+      } catch (error) {
+        return { ok: false, reason: `the file cannot be read (${getErrorCode(error)})` };
+      }
+    }
+    let response: Response;
+    try {
+      response = await fetchImpl(location);
+    } catch (error) {
+      return { ok: false, reason: `the request failed (${getErrorCode(error)})` };
+    }
+    if (!response.ok) return { ok: false, reason: `the server answered ${response.status}` };
+    try {
+      return checkFontBytes(new Uint8Array(await response.arrayBuffer()));
+    } catch (error) {
+      return { ok: false, reason: `the answer could not be read (${getErrorCode(error)})` };
+    }
+  }
+
+  function getBytes(location: string, isUrl: boolean): Promise<BytesResult> {
+    const cached = cache.get(location);
+    if (cached !== undefined) return cached;
+    const pending = readSource(location, isUrl).then((result) => {
+      if (!result.ok) cache.delete(location);
+      return result;
+    });
+    cache.set(location, pending);
+    return pending;
+  }
+
+  return async (fonts) => {
+    const located = fonts.map((font) => {
+      const isUrl = font.src.startsWith("https://");
+      return { font, isUrl, location: isUrl || isAbsolute(font.src) ? font.src : resolve(options.root, font.src) };
+    });
+    const results = await Promise.all(located.map(async (entry) => ({ ...entry, result: await getBytes(entry.location, entry.isUrl) })));
+    const loaded: OgFont[] = [];
+    for (const [index, { font, location, result }] of results.entries()) {
+      if (!result.ok) return { ok: false, error: `${label}[${index}] "${font.src}": ${result.reason} (${location}).` };
+      loaded.push({ name: font.name, data: result.data, weight: font.weight, style: font.style });
+    }
+    return { ok: true, fonts: loaded };
+  };
+}
+
+let loadFromWorkingDirectory: ((fonts: readonly OgFontSource[]) => Promise<OgFontsResult>) | undefined;
+
+/** The fonts for an app's own OG card, read from the working directory (the app's root, where Next runs) and cached for the process. */
+export function loadOgFonts(fonts: readonly OgFontSource[]): Promise<OgFontsResult> {
+  loadFromWorkingDirectory ??= createOgFontLoader({ root: process.cwd() });
+  return loadFromWorkingDirectory(fonts);
+}

package/dist/messages/pl.d.ts

@@ -1,3 +0,0 @@
-import type { en } from "./en.js";
-export declare const pl: typeof en;
-//# sourceMappingURL=pl.d.ts.map

package/dist/messages/pl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pl.d.ts","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,eAAO,MAAM,EAAE,EAAE,OAAO,EAKvB,CAAC"}

package/dist/messages/pl.js

@@ -1,7 +0,0 @@
-export const pl = {
-    errors: {
-        database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
-        unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
-    },
-};
-//# sourceMappingURL=pl.js.map

package/dist/messages/pl.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pl.js","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,EAAE,GAAc;IAC3B,MAAM,EAAE;QACN,eAAe,EAAE,wEAAwE;QACzF,UAAU,EAAE,uCAAuC;KACpD;CACF,CAAC"}

package/src/messages/pl.ts

@@ -1,8 +0,0 @@
-import type { en } from "./en.js";
-
-export const pl: typeof en = {
-  errors: {
-    database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
-    unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
-  },
-};