@softure-ai/core 0.1.10 → 0.1.11

package/dist/messages/en.d.ts

@@ -3,5 +3,20 @@ export declare const en: {
         database_failed: string;
         unexpected: string;
     };
+    duration: {
+        years: {
+            one: string;
+            few: string;
+            many: string;
+            other: string;
+        };
+        months: {
+            one: string;
+            few: string;
+            many: string;
+            other: string;
+        };
+        both: string;
+    };
 };
 //# sourceMappingURL=en.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;CAKd,CAAC"}
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;CAUd,CAAC"}

package/dist/messages/en.js

@@ -3,5 +3,10 @@ export const en = {
         database_failed: "Something went wrong while saving or loading data. Please try again.",
         unexpected: "Something went wrong. Please try again.",
     },
+    duration: {
+        years: { one: "{count} year", few: "{count} years", many: "{count} years", other: "{count} years" },
+        months: { one: "{count} month", few: "{count} months", many: "{count} months", other: "{count} months" },
+        both: "{years} and {months}",
+    },
 };
 //# sourceMappingURL=en.js.map

package/dist/messages/en.js.map

@@ -1 +1 @@
-{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,eAAe,EAAE,sEAAsE;QACvF,UAAU,EAAE,yCAAyC;KACtD;CACF,CAAC"}
+{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,eAAe,EAAE,sEAAsE;QACvF,UAAU,EAAE,yCAAyC;KACtD;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE;QACnG,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,EAAE;QACxG,IAAI,EAAE,sBAAsB;KAC7B;CACF,CAAC"}

package/dist/messages/index.d.ts

@@ -1,6 +1,6 @@
 import type { Dictionaries } from "../i18n.js";
 import { en } from "./en.js";
 export type CoreMessages = typeof en;
-/** Copy for core's own error codes (`core.<key>` → `errors.<key>`). */
+/** Copy for core's own error codes (`core.<key>` → `errors.<key>`) and formatters (`duration`). */
 export declare const coreMessages: Dictionaries<CoreMessages>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC;AAErC,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,YAAY,CAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC;AAErC,mGAAmG;AACnG,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,YAAY,CAAc,CAAC"}

package/dist/messages/index.js

@@ -1,5 +1,5 @@
 import { en } from "./en.js";
 import { pl } from "./pl.js";
-/** Copy for core's own error codes (`core.<key>` → `errors.<key>`). */
+/** Copy for core's own error codes (`core.<key>` → `errors.<key>`) and formatters (`duration`). */
 export const coreMessages = { en, pl };
 //# sourceMappingURL=index.js.map

package/dist/messages/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAI7B,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAA+B,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAI7B,mGAAmG;AACnG,MAAM,CAAC,MAAM,YAAY,GAA+B,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC"}

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

@@ -1 +1 @@
-{"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"}
+{"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,EAUvB,CAAC"}

package/dist/messages/pl.js

@@ -3,5 +3,10 @@ export const pl = {
         database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
         unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
     },
+    duration: {
+        years: { one: "{count} rok", few: "{count} lata", many: "{count} lat", other: "{count} roku" },
+        months: { one: "{count} miesiąc", few: "{count} miesiące", many: "{count} miesięcy", other: "{count} miesiąca" },
+        both: "{years} i {months}",
+    },
 };
 //# sourceMappingURL=pl.js.map

package/dist/messages/pl.js.map

@@ -1 +1 @@
-{"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"}
+{"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;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE;QAC9F,MAAM,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,EAAE;QAChH,IAAI,EAAE,oBAAoB;KAC3B;CACF,CAAC"}

package/dist/og/index.d.ts

@@ -0,0 +1,2 @@
+export { createOgFontLoader, loadOgFonts, OG_FONT_WEIGHTS, type OgFont, type OgFontLoaderOptions, type OgFontSource, type OgFontsResult, type OgFontWeight, } from "./og-fonts.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/og/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/og/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,KAAK,MAAM,EACX,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC"}

package/dist/og/index.js

@@ -0,0 +1,4 @@
+// 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, } from "./og-fonts.js";
+//# sourceMappingURL=index.js.map

package/dist/og/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/og/index.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,4EAA4E;AAC5E,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,eAAe,GAMhB,MAAM,eAAe,CAAC"}

package/dist/og/og-fonts.d.ts

@@ -0,0 +1,37 @@
+/** The weights Satori (`next/og`) draws: static fonts only, in steps of 100. */
+export declare const OG_FONT_WEIGHTS: readonly [100, 200, 300, 400, 500, 600, 700, 800, 900];
+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;
+};
+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;
+}
+/** A loader with its own cache, keyed by the resolved path or URL. */
+export declare function createOgFontLoader(options: OgFontLoaderOptions): (fonts: readonly OgFontSource[]) => Promise<OgFontsResult>;
+/** 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 declare function loadOgFonts(fonts: readonly OgFontSource[]): Promise<OgFontsResult>;
+//# sourceMappingURL=og-fonts.d.ts.map

package/dist/og/og-fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-fonts.d.ts","sourceRoot":"","sources":["../../src/og/og-fonts.ts"],"names":[],"mappings":"AAOA,gFAAgF;AAChF,eAAO,MAAM,eAAe,wDAAyD,CAAC;AAEtF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,+GAA+G;AAC/G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACtC;AAED,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACtC;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAItI,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA0BD,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,KAAK,OAAO,CAAC,aAAa,CAAC,CAoD3H;AAID,wIAAwI;AACxI,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAGlF"}

package/dist/og/og-fonts.js

@@ -0,0 +1,95 @@
+// 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];
+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) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+}
+function checkFontBytes(bytes) {
+    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) {
+    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) {
+    const read = options.readFile ?? readFile;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const label = options.label ?? DEFAULT_LABEL;
+    const cache = new Map();
+    async function readSource(location, isUrl) {
+        if (!isUrl) {
+            try {
+                return checkFontBytes(await read(location));
+            }
+            catch (error) {
+                return { ok: false, reason: `the file cannot be read (${getErrorCode(error)})` };
+            }
+        }
+        let 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, isUrl) {
+        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 = [];
+        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;
+/** 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) {
+    loadFromWorkingDirectory ??= createOgFontLoader({ root: process.cwd() });
+    return loadFromWorkingDirectory(fonts);
+}
+//# sourceMappingURL=og-fonts.js.map

package/dist/og/og-fonts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-fonts.js","sourceRoot":"","sources":["../../src/og/og-fonts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/core",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "The SOFTURE AI module contract: app config, module definitions, Result, Clock and messages.",
   "license": "MIT",
   "type": "module",
@@ -39,6 +39,11 @@
       "@softure-ai/source": "./src/cli/index.ts",
       "types": "./dist/cli/index.d.ts",
       "default": "./dist/cli/index.js"
+    },
+    "./og": {
+      "@softure-ai/source": "./src/og/index.ts",
+      "types": "./dist/og/index.d.ts",
+      "default": "./dist/og/index.js"
     }
   },
   "scripts": {

package/src/calendar-day.ts

@@ -1,5 +1,6 @@
 // The calendar day of an instant in a given IANA time zone, as `YYYY-MM-DD`. "Today" computed in the
 // process zone is a classic date bug: on a server in UTC, an evening in New York is already tomorrow.
+import { z } from "zod";
 import type { Clock } from "./clock.js";
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
@@ -59,6 +60,9 @@ export function isCalendarDay(value: unknown): value is string {
   return typeof value === "string" && parseCivilDate(value) !== null;
 }
 
+/** A `YYYY-MM-DD` calendar day in tool and form input: `isCalendarDay` as a zod schema. */
+export const calendarDaySchema = z.string().refine(isCalendarDay, "must be a YYYY-MM-DD calendar day, e.g. 2026-10-04");
+
 /** `day` moved by `days` calendar days (negative goes back). Throws a `RangeError` for a malformed day or count. */
 export function addCalendarDays(day: string, days: number): string {
   const operation = "addCalendarDays";

package/src/config.ts

@@ -63,6 +63,11 @@ export interface SoftureConfig {
   readonly timezone: string;
   /** Scheme, host and port of the app, without a path: `https://app.example.com`. */
   readonly appOrigin: string;
+  /**
+   * The public landing site (`https://example.com`) when the app lives on a subdomain beside it; `appOrigin` when
+   * the app does not name one. For links from the app to its marketing pages, not for the app's own URLs.
+   */
+  readonly landingOrigin: string;
   /** Every origin the app is served under besides `appOrigin`, read by `resolveAppOrigin`. */
   readonly origins: SoftureOrigins;
   /** Enabled modules, in the order the app listed them. */
@@ -75,6 +80,8 @@ export interface SoftureConfigInput {
   readonly locale: Locale;
   readonly timezone: string;
   readonly appOrigin: string;
+  /** The public landing site beside the app; defaults to `appOrigin`. */
+  readonly landingOrigin?: string;
   readonly origins?: SoftureOriginsInput;
   readonly modules: readonly AnySoftureModule[];
 }
@@ -98,6 +105,7 @@ const configSchema = z.object({
   locale: z.enum(LOCALES),
   timezone: z.string().refine(isTimeZone, "must be an IANA time zone, e.g. Europe/Warsaw"),
   appOrigin: z.string().refine(isOrigin, ORIGIN_MESSAGE),
+  landingOrigin: z.string().refine(isOrigin, ORIGIN_MESSAGE).optional(),
   origins: z
     .strictObject({
       trustedOrigins: z.array(z.string().refine(isOrigin, ORIGIN_MESSAGE)).max(16, "takes at most 16 origins").default([]),
@@ -126,6 +134,7 @@ export function defineSoftureConfig(input: SoftureConfigInput): SoftureConfig {
 
   return Object.freeze({
     ...config,
+    landingOrigin: config.landingOrigin ?? config.appOrigin,
     database: config.database === null ? null : Object.freeze({ ...config.database }),
     origins: Object.freeze({ ...config.origins, trustedOrigins: Object.freeze([...config.origins.trustedOrigins]) }),
     modules: Object.freeze([...config.modules]),

package/src/format.ts

@@ -2,7 +2,8 @@
 // is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it.
 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 Locale } from "./i18n.js";
+import { coreMessages } from "./messages/index.js";
 
 /** `long`: October 4, 2026 (pl names the month in the genitive); `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (pl: 04.10.2026). */
 export type CalendarDayStyle = "long" | "medium" | "numeric";
@@ -16,6 +17,19 @@ export interface FormatMoneyOptions {
   readonly compact?: boolean;
 }
 
+/** `long`: October 2026 (pl: the month in the nominative); `genitive`: pl's genitive month, as inside a date; `roman`: X 2026. */
+export type CalendarMonthStyle = "long" | "genitive" | "roman";
+
+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;
+}
+
+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;
 const BASIS_POINTS_PER_UNIT = 10_000;
 const MAX_PERCENT_FRACTION_DIGITS = 2;
 
@@ -31,13 +45,51 @@ 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 {
   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: Locale, 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}`;
+  if (style === "long") return getDayFormatter(`${locale}:month`, locale, { month: "long", year: "numeric" }).format(date);
+  // The genitive is the form a full date uses, so it is read from a day-month-year date's month part.
+  const parts = getDayFormatter(`${locale}:day-month`, locale, { day: "numeric", month: "long", year: "numeric" }).formatToParts(date);
+  const name = parts.find((part) => part.type === "month")?.value ?? "";
+  return `${name} ${year}`;
+}
+
+/**
+ * Whole months as years and months in `locale`, with its plural forms: 38 is "3 years and 2 months"; a part that is
+ * zero is left out, and zero itself is "0 months". Throws a `RangeError` for a negative or fractional count.
+ */
+export function formatDuration(months: number, locale: Locale): 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 copy = coreMessages[locale].duration;
+  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 });
 }
 
 /**
@@ -62,11 +114,37 @@ 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, and zero is never signed (`-0`
+ * and a value that rounds to zero show as `0%`). Throws a `RangeError` for a non-finite value.
+ */
+export function formatPercent(basisPoints: number, locale: Locale, 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",
+    maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS,
+    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 isNextToPercentSign(parts: readonly Intl.NumberFormatPart[], index: number): boolean {
+  return parts[index - 1]?.type === "percentSign" || parts[index + 1]?.type === "percentSign";
+}
+
+function getDayFormatter(key: string, locale: Locale, 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 {

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   addCalendarDays,
   addCalendarMonths,
   calendarDaysBetween,
+  calendarDaySchema,
   getCalendarDay,
   isCalendarDay,
   toCalendarDay,
@@ -11,7 +12,19 @@ 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 {
+  formatCalendarDay,
+  formatCalendarMonth,
+  formatDuration,
+  formatMoney,
+  formatPercent,
+  isCalendarMonth,
+  type CalendarDayStyle,
+  type CalendarMonthStyle,
+  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,

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/en.ts

@@ -3,4 +3,9 @@ export const en = {
     database_failed: "Something went wrong while saving or loading data. Please try again.",
     unexpected: "Something went wrong. Please try again.",
   },
+  duration: {
+    years: { one: "{count} year", few: "{count} years", many: "{count} years", other: "{count} years" },
+    months: { one: "{count} month", few: "{count} months", many: "{count} months", other: "{count} months" },
+    both: "{years} and {months}",
+  },
 };

package/src/messages/index.ts

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

package/src/messages/pl.ts

@@ -5,4 +5,9 @@ export const pl: typeof en = {
     database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
     unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
   },
+  duration: {
+    years: { one: "{count} rok", few: "{count} lata", many: "{count} lat", other: "{count} roku" },
+    months: { one: "{count} miesiąc", few: "{count} miesiące", many: "{count} miesięcy", other: "{count} miesiąca" },
+    both: "{years} i {months}",
+  },
 };

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";