@sarimarcus/content-sites-core 0.7.0-rc.1 → 0.8.0-rc.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.8.0-rc.0 (2026-09-30)
+
+- `./dates`: `formatUtcDate`, `formatUtcDateRange`, `buildNow`, `maxDate`, `latestDateModified`, `NEW_BADGE_DAYS`, `isNew` (takes `now`), and the iCalendar builders `eventToIcs`, `eventsToIcs`, `googleCalendarUrl`, `monthsCovered` (site identity passed as an `IcsCalendar`). New `./geo`: `haversineMetres`, `formatDistance`, `walkingMinutes`. `./text`: `fitLength`, `readingTime`. First runtime dependency: `marked` (SLA-2747).
+
+## 0.7.0 (2026-09-30)
+
+- Stable release of 0.7.0-rc.1, unchanged: adopted on all three sites with every page identical (Córdoba's 8 walk pages differ only by a stylesheet reorder, screenshots unchanged); astro check 0 errors (SLA-2747).
+
 ## 0.7.0-rc.1 (2026-09-30)
 
 - `buildImageMap` / `keyBySlug` are typed with Astro's `ImageMetadata` again, as the site copies were; the generic form typed an untyped `import.meta.glob` result as `unknown` (SLA-2747).

package/README.md

@@ -4,8 +4,8 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
 and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
 today's ui components import from tourism code).
 
-Named entry points: `url`, `dates`, `dom`, `text`, `config` and `types` (`src/internal` is never exported). No `.astro`
-files. Lowest layer: imports nothing from the other packages. Ownership per path is in
+Named entry points: `url`, `dates`, `geo`, `dom`, `text`, `config` and `types` (`src/internal` is never exported). No `.astro`
+files. Lowest layer: imports nothing from the other packages; its one runtime dependency is `marked` (`readingTime`). Ownership per path is in
 `.planning/platform/catalogue.json` (owner `core`).
 
 Code Node loads directly (config builders imported by `astro.config.mjs`) ships compiled to `dist/` with

package/dist/dates/buildClock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build-time "now", pinned to the start of the UTC day.
+ *
+ * Astro prerenders every page, so a bare `new Date()` in frontmatter bakes the build *instant* into the HTML, and
+ * anything derived from it (a moon phase, a countdown) differs between two builds a minute apart. Consumers that
+ * need the real instant re-compute client-side, so SSR only paints a no-JS fallback. Truncating to the UTC day
+ * matches the convention `validate:dates` uses for "today".
+ *
+ * Two builds either side of UTC midnight still differ; that cannot drift within one build session.
+ */
+export declare function buildNow(): Date;

package/dist/dates/buildClock.js

@@ -0,0 +1,13 @@
+/**
+ * Build-time "now", pinned to the start of the UTC day.
+ *
+ * Astro prerenders every page, so a bare `new Date()` in frontmatter bakes the build *instant* into the HTML, and
+ * anything derived from it (a moon phase, a countdown) differs between two builds a minute apart. Consumers that
+ * need the real instant re-compute client-side, so SSR only paints a no-JS fallback. Truncating to the UTC day
+ * matches the convention `validate:dates` uses for "today".
+ *
+ * Two builds either side of UTC midnight still differ; that cannot drift within one build session.
+ */
+export function buildNow() {
+    return new Date(`${new Date().toISOString().slice(0, 10)}T00:00:00Z`);
+}

package/dist/dates/formatDate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Format a date-only ISO string (`YYYY-MM-DD`) for display, anchored to UTC.
+ *
+ * The `T00:00:00Z` + `timeZone: 'UTC'` pairing is load-bearing: parsing a bare
+ * `YYYY-MM-DD` and formatting it in the host timezone drifts the displayed day
+ * by one in any negative-UTC-offset locale. Centralizing it here keeps every
+ * date on the site off-by-one-safe.
+ *
+ * @param iso     date-only or ISO datetime string (only the date part is used)
+ * @param options Intl options (default: long month + day, e.g. "July 14")
+ * @param locale  BCP-47 locale (default en-US)
+ */
+export declare function formatUtcDate(iso: string | undefined, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * Format a `startDate`/`endDate` pair as a compact display range, UTC-anchored
+ * via `formatUtcDate`: "Aug 12" (single day), "Aug 12–13" (same month),
+ * "May 29 – Jun 5" (cross-month). Returns '' when `start` is missing/invalid.
+ */
+export declare function formatUtcDateRange(start?: string, end?: string): string;

package/dist/dates/formatDate.js

@@ -0,0 +1,39 @@
+/**
+ * Format a date-only ISO string (`YYYY-MM-DD`) for display, anchored to UTC.
+ *
+ * The `T00:00:00Z` + `timeZone: 'UTC'` pairing is load-bearing: parsing a bare
+ * `YYYY-MM-DD` and formatting it in the host timezone drifts the displayed day
+ * by one in any negative-UTC-offset locale. Centralizing it here keeps every
+ * date on the site off-by-one-safe.
+ *
+ * @param iso     date-only or ISO datetime string (only the date part is used)
+ * @param options Intl options (default: long month + day, e.g. "July 14")
+ * @param locale  BCP-47 locale (default en-US)
+ */
+export function formatUtcDate(iso, options = { month: 'long', day: 'numeric' }, locale = 'en-US') {
+    // Guard partial/malformed input: a short string like "2026" would otherwise
+    // parse to a valid-but-wrong date (Jan 1), and junk would render "Invalid Date".
+    if (!iso || iso.length < 10)
+        return '';
+    const date = new Date(`${iso.slice(0, 10)}T00:00:00Z`);
+    if (Number.isNaN(date.getTime()))
+        return '';
+    return date.toLocaleDateString(locale, { ...options, timeZone: 'UTC' });
+}
+/**
+ * Format a `startDate`/`endDate` pair as a compact display range, UTC-anchored
+ * via `formatUtcDate`: "Aug 12" (single day), "Aug 12–13" (same month),
+ * "May 29 – Jun 5" (cross-month). Returns '' when `start` is missing/invalid.
+ */
+export function formatUtcDateRange(start, end) {
+    const s = formatUtcDate(start, { month: 'short', day: 'numeric' });
+    if (!s)
+        return '';
+    if (!end || end.length < 10 || end.slice(0, 10) === start.slice(0, 10))
+        return s;
+    const e = formatUtcDate(end, { month: 'short', day: 'numeric' });
+    if (!e)
+        return s;
+    const sameMonth = start.slice(0, 7) === end.slice(0, 7);
+    return sameMonth ? `${s}–${formatUtcDate(end, { day: 'numeric' })}` : `${s} – ${e}`;
+}

package/dist/dates/ics.d.ts

@@ -0,0 +1,36 @@
+/**
+ * iCalendar (RFC 5545) builders for all-day events, plus the matching Google Calendar prefill URL. Pure string
+ * functions; the site supplies its calendar identity.
+ *
+ * All-day date semantics: DTEND;VALUE=DATE is exclusive, so a single-day event ends the following day and a range
+ * ends the day after endDate.
+ */
+export interface IcsEvent {
+    slug: string;
+    name: string;
+    description?: string;
+    /** YYYY-MM-DD */
+    startDate: string;
+    /** YYYY-MM-DD */
+    endDate?: string;
+    /** Absolute URL of the event page */
+    url: string;
+}
+export interface IcsCalendar {
+    /** Domain after `@` in each UID, e.g. `example.com`. */
+    uidDomain: string;
+    /** PRODID value, e.g. `-//Example//events//EN`. */
+    prodId: string;
+    /** Plain-text location; escaped for the LOCATION line, raw in the Google URL. */
+    location: string;
+    /** X-WR-CALNAME of the multi-event feed. */
+    calendarName: string;
+}
+/** A one-event calendar, named after the event. */
+export declare function eventToIcs(ev: IcsEvent, cal: IcsCalendar): string;
+/** A multi-event feed named `cal.calendarName`. */
+export declare function eventsToIcs(events: IcsEvent[], cal: IcsCalendar): string;
+/** Google Calendar prefill URL for the same all-day event. */
+export declare function googleCalendarUrl(ev: IcsEvent, cal: IcsCalendar): string;
+/** Month numbers (1-12) an event overlaps, for by-month buckets. */
+export declare function monthsCovered(startDate: string, endDate?: string): number[];

package/dist/dates/ics.js

@@ -0,0 +1,107 @@
+/**
+ * iCalendar (RFC 5545) builders for all-day events, plus the matching Google Calendar prefill URL. Pure string
+ * functions; the site supplies its calendar identity.
+ *
+ * All-day date semantics: DTEND;VALUE=DATE is exclusive, so a single-day event ends the following day and a range
+ * ends the day after endDate.
+ */
+const compact = (isoDate) => isoDate.replaceAll('-', '');
+/** Day after the given YYYY-MM-DD, compact form (exclusive DTEND). */
+function nextDayCompact(isoDate) {
+    const d = new Date(`${isoDate}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + 1);
+    return d.toISOString().slice(0, 10).replaceAll('-', '');
+}
+/** RFC 5545 TEXT escaping: backslash, semicolon, comma, newline. */
+function escapeText(value) {
+    return value
+        .replaceAll('\\', '\\\\')
+        .replaceAll(';', '\\;')
+        .replaceAll(',', '\\,')
+        .replaceAll(/\r?\n/g, '\\n');
+}
+/** Fold lines longer than 75 octets with CRLF + space (RFC 5545 §3.1). */
+function foldLine(line) {
+    const bytes = new TextEncoder().encode(line);
+    if (bytes.length <= 75)
+        return line;
+    const parts = [];
+    let current = '';
+    let currentBytes = 0;
+    for (const ch of line) {
+        const chBytes = new TextEncoder().encode(ch).length;
+        const limit = parts.length === 0 ? 75 : 74; // continuation lines lose 1 octet to the leading space
+        if (currentBytes + chBytes > limit) {
+            parts.push(current);
+            current = ch;
+            currentBytes = chBytes;
+        }
+        else {
+            current += ch;
+            currentBytes += chBytes;
+        }
+    }
+    if (current)
+        parts.push(current);
+    return parts.join('\r\n ');
+}
+function vevent(ev, cal) {
+    const start = compact(ev.startDate);
+    const end = nextDayCompact(ev.endDate || ev.startDate);
+    return [
+        'BEGIN:VEVENT',
+        // Deterministic UID + DTSTAMP so rebuilds don't churn the committed output.
+        `UID:${ev.slug}-${start}@${cal.uidDomain}`,
+        `DTSTAMP:${start}T000000Z`,
+        `DTSTART;VALUE=DATE:${start}`,
+        `DTEND;VALUE=DATE:${end}`,
+        `SUMMARY:${escapeText(ev.name)}`,
+        ...(ev.description ? [`DESCRIPTION:${escapeText(ev.description.slice(0, 300))}`] : []),
+        `LOCATION:${escapeText(cal.location)}`,
+        `URL:${ev.url}`,
+        'END:VEVENT',
+    ];
+}
+function wrapCalendar(name, veventLines, cal) {
+    const lines = [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        `PRODID:${cal.prodId}`,
+        'CALSCALE:GREGORIAN',
+        `X-WR-CALNAME:${escapeText(name)}`,
+        ...veventLines,
+        'END:VCALENDAR',
+    ];
+    return lines.map(foldLine).join('\r\n') + '\r\n';
+}
+/** A one-event calendar, named after the event. */
+export function eventToIcs(ev, cal) {
+    return wrapCalendar(ev.name, vevent(ev, cal), cal);
+}
+/** A multi-event feed named `cal.calendarName`. */
+export function eventsToIcs(events, cal) {
+    return wrapCalendar(cal.calendarName, events.flatMap((ev) => vevent(ev, cal)), cal);
+}
+/** Google Calendar prefill URL for the same all-day event. */
+export function googleCalendarUrl(ev, cal) {
+    const params = new URLSearchParams({
+        action: 'TEMPLATE',
+        text: ev.name,
+        dates: `${compact(ev.startDate)}/${nextDayCompact(ev.endDate || ev.startDate)}`,
+        details: `${(ev.description || '').slice(0, 300)}\n${ev.url}`.trim(),
+        location: cal.location,
+    });
+    return `https://calendar.google.com/calendar/render?${params.toString()}`;
+}
+/** Month numbers (1-12) an event overlaps, for by-month buckets. */
+export function monthsCovered(startDate, endDate) {
+    const start = new Date(`${startDate}T00:00:00Z`);
+    const end = new Date(`${endDate || startDate}T00:00:00Z`);
+    const months = new Set();
+    const cursor = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
+    while (cursor <= end) {
+        months.add(cursor.getUTCMonth() + 1);
+        cursor.setUTCMonth(cursor.getUTCMonth() + 1);
+    }
+    return [...months];
+}

package/dist/dates/index.d.ts

@@ -1 +1,5 @@
-export {};
+export { formatUtcDate, formatUtcDateRange } from './formatDate.ts';
+export { buildNow } from './buildClock.ts';
+export { maxDate, latestDateModified, NEW_BADGE_DAYS, isNew } from './lastmod.ts';
+export { eventToIcs, eventsToIcs, googleCalendarUrl, monthsCovered } from './ics.ts';
+export type { IcsEvent, IcsCalendar } from './ics.ts';

package/dist/dates/index.js

@@ -1,2 +1,5 @@
-// Public surface of @sarimarcus/content-sites-core/dates. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-core/dates.
+export { formatUtcDate, formatUtcDateRange } from "./formatDate.js";
+export { buildNow } from "./buildClock.js";
+export { maxDate, latestDateModified, NEW_BADGE_DAYS, isNew } from "./lastmod.js";
+export { eventToIcs, eventsToIcs, googleCalendarUrl, monthsCovered } from "./ics.js";

package/dist/dates/lastmod.d.ts

@@ -0,0 +1,15 @@
+/** The latest of several `YYYY-MM-DD` strings; empty values are skipped, and none gives 1970-01-01. */
+export declare function maxDate(...dates: string[]): string;
+/** The latest `data.dateModified` across collection entries; entries without one are skipped. */
+export declare function latestDateModified(entries: ReadonlyArray<{
+    data: object;
+}>): string;
+/** Freshness window for a "New" badge, in days. */
+export declare const NEW_BADGE_DAYS = 30;
+/**
+ * True when `date` is a valid YYYY-MM-DD within the last `days` days of `now`.
+ *
+ * Compared as ISO strings against a UTC cutoff, so there is no timezone parsing. A future date is not new: nothing
+ * gates a future `datePublished`, so a mistyped year would otherwise pin a permanent badge.
+ */
+export declare function isNew(date: string | undefined, days?: number, now?: number): boolean;

package/dist/dates/lastmod.js

@@ -0,0 +1,35 @@
+const EPOCH = '1970-01-01';
+/** The latest of several `YYYY-MM-DD` strings; empty values are skipped, and none gives 1970-01-01. */
+export function maxDate(...dates) {
+    let latest = EPOCH;
+    for (const d of dates) {
+        if (d && d > latest)
+            latest = d;
+    }
+    return latest;
+}
+/** The latest `data.dateModified` across collection entries; entries without one are skipped. */
+export function latestDateModified(entries) {
+    let latest = EPOCH;
+    for (const entry of entries) {
+        const d = entry.data.dateModified;
+        if (d && d > latest)
+            latest = d;
+    }
+    return latest;
+}
+/** Freshness window for a "New" badge, in days. */
+export const NEW_BADGE_DAYS = 30;
+/**
+ * True when `date` is a valid YYYY-MM-DD within the last `days` days of `now`.
+ *
+ * Compared as ISO strings against a UTC cutoff, so there is no timezone parsing. A future date is not new: nothing
+ * gates a future `datePublished`, so a mistyped year would otherwise pin a permanent badge.
+ */
+export function isNew(date, days = NEW_BADGE_DAYS, now = Date.now()) {
+    if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date))
+        return false;
+    const today = new Date(now).toISOString().slice(0, 10);
+    const cutoff = new Date(now - days * 86_400_000).toISOString().slice(0, 10);
+    return date >= cutoff && date <= today;
+}

package/dist/geo/distance.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Haversine distance between two coordinates in metres.
+ * Build-time only: proximity pages sort items by it.
+ */
+export declare function haversineMetres(lat1: number, lng1: number, lat2: number, lng2: number): number;
+/** Format metres as a human-readable distance badge string. */
+export declare function formatDistance(metres: number): string;
+/** Estimate walking time in minutes (~80 m/min pedestrian pace). */
+export declare function walkingMinutes(metres: number): number;

package/dist/geo/distance.js

@@ -0,0 +1,24 @@
+/**
+ * Haversine distance between two coordinates in metres.
+ * Build-time only: proximity pages sort items by it.
+ */
+export function haversineMetres(lat1, lng1, lat2, lng2) {
+    const R = 6_371_000; // Earth radius in metres
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLng = toRad(lng2 - lng1);
+    const a = Math.sin(dLat / 2) ** 2 +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/** Format metres as a human-readable distance badge string. */
+export function formatDistance(metres) {
+    if (metres < 1000) {
+        return `${Math.round(metres)}m`;
+    }
+    return `${(metres / 1000).toFixed(1)}km`;
+}
+/** Estimate walking time in minutes (~80 m/min pedestrian pace). */
+export function walkingMinutes(metres) {
+    return Math.max(1, Math.round(metres / 80));
+}

package/dist/geo/index.d.ts

@@ -0,0 +1 @@
+export { haversineMetres, formatDistance, walkingMinutes } from './distance.ts';

package/dist/geo/index.js

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/geo.
+export { haversineMetres, formatDistance, walkingMinutes } from "./distance.js";

package/dist/text/fitLength.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The first candidate whose length is within [min, max], else the one that misses the range by the fewest
+ * characters (the earliest wins a tie).
+ */
+export declare function fitLength(candidates: string[], min: number, max: number): string;

package/dist/text/fitLength.js

@@ -0,0 +1,8 @@
+/**
+ * The first candidate whose length is within [min, max], else the one that misses the range by the fewest
+ * characters (the earliest wins a tie).
+ */
+export function fitLength(candidates, min, max) {
+    const miss = (s) => (s.length < min ? min - s.length : s.length > max ? s.length - max : 0);
+    return candidates.find((s) => miss(s) === 0) ?? [...candidates].sort((a, b) => miss(a) - miss(b))[0];
+}

package/dist/text/index.d.ts

@@ -1,2 +1,4 @@
 export { slugify } from './slugify.ts';
 export { fitWithinLength } from './fitWithinLength.ts';
+export { fitLength } from './fitLength.ts';
+export { readingTime } from './readingTime.ts';

package/dist/text/index.js

@@ -1,3 +1,5 @@
 // Public surface of @sarimarcus/content-sites-core/text.
 export { slugify } from "./slugify.js";
 export { fitWithinLength } from "./fitWithinLength.js";
+export { fitLength } from "./fitLength.js";
+export { readingTime } from "./readingTime.js";

package/dist/text/readingTime.d.ts

@@ -0,0 +1,17 @@
+interface ArticleSection {
+    body?: string;
+    subsections?: Array<{
+        body?: string;
+    }>;
+}
+interface ArticleLike {
+    intro?: string;
+    sections?: ArticleSection[];
+}
+/**
+ * Estimate reading time for an article.
+ * Counts words from intro + section bodies + subsection bodies,
+ * strips Markdown, and divides by 220 WPM. Minimum 1 minute.
+ */
+export declare function readingTime(article: ArticleLike): number;
+export {};

package/dist/text/readingTime.js

@@ -0,0 +1,39 @@
+import { marked } from 'marked';
+/**
+ * Strip Markdown / HTML markup and collapse whitespace so we can count
+ * real words. Uses `marked` to normalize Markdown, then removes HTML tags.
+ */
+function stripMarkup(markdown) {
+    const html = marked.parse(markdown, { breaks: true, gfm: true, async: false });
+    return html
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\[\^(\d+)\]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function countWords(text) {
+    const cleaned = stripMarkup(text);
+    if (!cleaned)
+        return 0;
+    return cleaned.split(/\s+/).filter((w) => w.length > 0).length;
+}
+/**
+ * Estimate reading time for an article.
+ * Counts words from intro + section bodies + subsection bodies,
+ * strips Markdown, and divides by 220 WPM. Minimum 1 minute.
+ */
+export function readingTime(article) {
+    let words = 0;
+    if (article.intro) {
+        words += countWords(article.intro);
+    }
+    for (const section of article.sections ?? []) {
+        if (section.body)
+            words += countWords(section.body);
+        for (const sub of section.subsections ?? []) {
+            if (sub.body)
+                words += countWords(sub.body);
+        }
+    }
+    return Math.max(1, Math.round(words / 220));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.7.0-rc.1",
+  "version": "0.8.0-rc.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,10 @@
       "types": "./dist/dates/index.d.ts",
       "default": "./dist/dates/index.js"
     },
+    "./geo": {
+      "types": "./dist/geo/index.d.ts",
+      "default": "./dist/geo/index.js"
+    },
     "./dom": {
       "types": "./dist/dom/index.d.ts",
       "default": "./dist/dom/index.js"
@@ -54,6 +58,9 @@
       "default": "./dist/types/index.js"
     }
   },
+  "dependencies": {
+    "marked": "^18.0.14"
+  },
   "peerDependencies": {
     "astro": "^7.0.6"
   }

package/src/dates/buildClock.ts

@@ -0,0 +1,13 @@
+/**
+ * Build-time "now", pinned to the start of the UTC day.
+ *
+ * Astro prerenders every page, so a bare `new Date()` in frontmatter bakes the build *instant* into the HTML, and
+ * anything derived from it (a moon phase, a countdown) differs between two builds a minute apart. Consumers that
+ * need the real instant re-compute client-side, so SSR only paints a no-JS fallback. Truncating to the UTC day
+ * matches the convention `validate:dates` uses for "today".
+ *
+ * Two builds either side of UTC midnight still differ; that cannot drift within one build session.
+ */
+export function buildNow(): Date {
+  return new Date(`${new Date().toISOString().slice(0, 10)}T00:00:00Z`);
+}

package/src/dates/formatDate.ts

@@ -0,0 +1,39 @@
+/**
+ * Format a date-only ISO string (`YYYY-MM-DD`) for display, anchored to UTC.
+ *
+ * The `T00:00:00Z` + `timeZone: 'UTC'` pairing is load-bearing: parsing a bare
+ * `YYYY-MM-DD` and formatting it in the host timezone drifts the displayed day
+ * by one in any negative-UTC-offset locale. Centralizing it here keeps every
+ * date on the site off-by-one-safe.
+ *
+ * @param iso     date-only or ISO datetime string (only the date part is used)
+ * @param options Intl options (default: long month + day, e.g. "July 14")
+ * @param locale  BCP-47 locale (default en-US)
+ */
+export function formatUtcDate(
+  iso: string | undefined,
+  options: Intl.DateTimeFormatOptions = { month: 'long', day: 'numeric' },
+  locale: string = 'en-US',
+): string {
+  // Guard partial/malformed input: a short string like "2026" would otherwise
+  // parse to a valid-but-wrong date (Jan 1), and junk would render "Invalid Date".
+  if (!iso || iso.length < 10) return '';
+  const date = new Date(`${iso.slice(0, 10)}T00:00:00Z`);
+  if (Number.isNaN(date.getTime())) return '';
+  return date.toLocaleDateString(locale, { ...options, timeZone: 'UTC' });
+}
+
+/**
+ * Format a `startDate`/`endDate` pair as a compact display range, UTC-anchored
+ * via `formatUtcDate`: "Aug 12" (single day), "Aug 12–13" (same month),
+ * "May 29 – Jun 5" (cross-month). Returns '' when `start` is missing/invalid.
+ */
+export function formatUtcDateRange(start?: string, end?: string): string {
+  const s = formatUtcDate(start, { month: 'short', day: 'numeric' });
+  if (!s) return '';
+  if (!end || end.length < 10 || end.slice(0, 10) === start!.slice(0, 10)) return s;
+  const e = formatUtcDate(end, { month: 'short', day: 'numeric' });
+  if (!e) return s;
+  const sameMonth = start!.slice(0, 7) === end.slice(0, 7);
+  return sameMonth ? `${s}–${formatUtcDate(end, { day: 'numeric' })}` : `${s} – ${e}`;
+}

package/src/dates/ics.ts

@@ -0,0 +1,137 @@
+/**
+ * iCalendar (RFC 5545) builders for all-day events, plus the matching Google Calendar prefill URL. Pure string
+ * functions; the site supplies its calendar identity.
+ *
+ * All-day date semantics: DTEND;VALUE=DATE is exclusive, so a single-day event ends the following day and a range
+ * ends the day after endDate.
+ */
+
+export interface IcsEvent {
+  slug: string;
+  name: string;
+  description?: string;
+  /** YYYY-MM-DD */
+  startDate: string;
+  /** YYYY-MM-DD */
+  endDate?: string;
+  /** Absolute URL of the event page */
+  url: string;
+}
+
+export interface IcsCalendar {
+  /** Domain after `@` in each UID, e.g. `example.com`. */
+  uidDomain: string;
+  /** PRODID value, e.g. `-//Example//events//EN`. */
+  prodId: string;
+  /** Plain-text location; escaped for the LOCATION line, raw in the Google URL. */
+  location: string;
+  /** X-WR-CALNAME of the multi-event feed. */
+  calendarName: string;
+}
+
+const compact = (isoDate: string): string => isoDate.replaceAll('-', '');
+
+/** Day after the given YYYY-MM-DD, compact form (exclusive DTEND). */
+function nextDayCompact(isoDate: string): string {
+  const d = new Date(`${isoDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return d.toISOString().slice(0, 10).replaceAll('-', '');
+}
+
+/** RFC 5545 TEXT escaping: backslash, semicolon, comma, newline. */
+function escapeText(value: string): string {
+  return value
+    .replaceAll('\\', '\\\\')
+    .replaceAll(';', '\\;')
+    .replaceAll(',', '\\,')
+    .replaceAll(/\r?\n/g, '\\n');
+}
+
+/** Fold lines longer than 75 octets with CRLF + space (RFC 5545 §3.1). */
+function foldLine(line: string): string {
+  const bytes = new TextEncoder().encode(line);
+  if (bytes.length <= 75) return line;
+  const parts: string[] = [];
+  let current = '';
+  let currentBytes = 0;
+  for (const ch of line) {
+    const chBytes = new TextEncoder().encode(ch).length;
+    const limit = parts.length === 0 ? 75 : 74; // continuation lines lose 1 octet to the leading space
+    if (currentBytes + chBytes > limit) {
+      parts.push(current);
+      current = ch;
+      currentBytes = chBytes;
+    } else {
+      current += ch;
+      currentBytes += chBytes;
+    }
+  }
+  if (current) parts.push(current);
+  return parts.join('\r\n ');
+}
+
+function vevent(ev: IcsEvent, cal: IcsCalendar): string[] {
+  const start = compact(ev.startDate);
+  const end = nextDayCompact(ev.endDate || ev.startDate);
+  return [
+    'BEGIN:VEVENT',
+    // Deterministic UID + DTSTAMP so rebuilds don't churn the committed output.
+    `UID:${ev.slug}-${start}@${cal.uidDomain}`,
+    `DTSTAMP:${start}T000000Z`,
+    `DTSTART;VALUE=DATE:${start}`,
+    `DTEND;VALUE=DATE:${end}`,
+    `SUMMARY:${escapeText(ev.name)}`,
+    ...(ev.description ? [`DESCRIPTION:${escapeText(ev.description.slice(0, 300))}`] : []),
+    `LOCATION:${escapeText(cal.location)}`,
+    `URL:${ev.url}`,
+    'END:VEVENT',
+  ];
+}
+
+function wrapCalendar(name: string, veventLines: string[], cal: IcsCalendar): string {
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    `PRODID:${cal.prodId}`,
+    'CALSCALE:GREGORIAN',
+    `X-WR-CALNAME:${escapeText(name)}`,
+    ...veventLines,
+    'END:VCALENDAR',
+  ];
+  return lines.map(foldLine).join('\r\n') + '\r\n';
+}
+
+/** A one-event calendar, named after the event. */
+export function eventToIcs(ev: IcsEvent, cal: IcsCalendar): string {
+  return wrapCalendar(ev.name, vevent(ev, cal), cal);
+}
+
+/** A multi-event feed named `cal.calendarName`. */
+export function eventsToIcs(events: IcsEvent[], cal: IcsCalendar): string {
+  return wrapCalendar(cal.calendarName, events.flatMap((ev) => vevent(ev, cal)), cal);
+}
+
+/** Google Calendar prefill URL for the same all-day event. */
+export function googleCalendarUrl(ev: IcsEvent, cal: IcsCalendar): string {
+  const params = new URLSearchParams({
+    action: 'TEMPLATE',
+    text: ev.name,
+    dates: `${compact(ev.startDate)}/${nextDayCompact(ev.endDate || ev.startDate)}`,
+    details: `${(ev.description || '').slice(0, 300)}\n${ev.url}`.trim(),
+    location: cal.location,
+  });
+  return `https://calendar.google.com/calendar/render?${params.toString()}`;
+}
+
+/** Month numbers (1-12) an event overlaps, for by-month buckets. */
+export function monthsCovered(startDate: string, endDate?: string): number[] {
+  const start = new Date(`${startDate}T00:00:00Z`);
+  const end = new Date(`${endDate || startDate}T00:00:00Z`);
+  const months = new Set<number>();
+  const cursor = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
+  while (cursor <= end) {
+    months.add(cursor.getUTCMonth() + 1);
+    cursor.setUTCMonth(cursor.getUTCMonth() + 1);
+  }
+  return [...months];
+}

package/src/dates/index.ts

@@ -1,2 +1,6 @@
-// Public surface of @sarimarcus/content-sites-core/dates. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-core/dates.
+export { formatUtcDate, formatUtcDateRange } from './formatDate.ts';
+export { buildNow } from './buildClock.ts';
+export { maxDate, latestDateModified, NEW_BADGE_DAYS, isNew } from './lastmod.ts';
+export { eventToIcs, eventsToIcs, googleCalendarUrl, monthsCovered } from './ics.ts';
+export type { IcsEvent, IcsCalendar } from './ics.ts';

package/src/dates/lastmod.ts

@@ -0,0 +1,36 @@
+const EPOCH = '1970-01-01';
+
+/** The latest of several `YYYY-MM-DD` strings; empty values are skipped, and none gives 1970-01-01. */
+export function maxDate(...dates: string[]): string {
+  let latest = EPOCH;
+  for (const d of dates) {
+    if (d && d > latest) latest = d;
+  }
+  return latest;
+}
+
+/** The latest `data.dateModified` across collection entries; entries without one are skipped. */
+export function latestDateModified(entries: ReadonlyArray<{ data: object }>): string {
+  let latest = EPOCH;
+  for (const entry of entries) {
+    const d = (entry.data as { dateModified?: string }).dateModified;
+    if (d && d > latest) latest = d;
+  }
+  return latest;
+}
+
+/** Freshness window for a "New" badge, in days. */
+export const NEW_BADGE_DAYS = 30;
+
+/**
+ * True when `date` is a valid YYYY-MM-DD within the last `days` days of `now`.
+ *
+ * Compared as ISO strings against a UTC cutoff, so there is no timezone parsing. A future date is not new: nothing
+ * gates a future `datePublished`, so a mistyped year would otherwise pin a permanent badge.
+ */
+export function isNew(date: string | undefined, days = NEW_BADGE_DAYS, now = Date.now()): boolean {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return false;
+  const today = new Date(now).toISOString().slice(0, 10);
+  const cutoff = new Date(now - days * 86_400_000).toISOString().slice(0, 10);
+  return date >= cutoff && date <= today;
+}

package/src/geo/distance.ts

@@ -0,0 +1,30 @@
+/**
+ * Haversine distance between two coordinates in metres.
+ * Build-time only: proximity pages sort items by it.
+ */
+export function haversineMetres(
+  lat1: number, lng1: number,
+  lat2: number, lng2: number,
+): number {
+  const R = 6_371_000; // Earth radius in metres
+  const toRad = (deg: number) => (deg * Math.PI) / 180;
+  const dLat = toRad(lat2 - lat1);
+  const dLng = toRad(lng2 - lng1);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
+  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+
+/** Format metres as a human-readable distance badge string. */
+export function formatDistance(metres: number): string {
+  if (metres < 1000) {
+    return `${Math.round(metres)}m`;
+  }
+  return `${(metres / 1000).toFixed(1)}km`;
+}
+
+/** Estimate walking time in minutes (~80 m/min pedestrian pace). */
+export function walkingMinutes(metres: number): number {
+  return Math.max(1, Math.round(metres / 80));
+}

package/src/geo/index.ts

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/geo.
+export { haversineMetres, formatDistance, walkingMinutes } from './distance.ts';

package/src/text/fitLength.ts

@@ -0,0 +1,8 @@
+/**
+ * The first candidate whose length is within [min, max], else the one that misses the range by the fewest
+ * characters (the earliest wins a tie).
+ */
+export function fitLength(candidates: string[], min: number, max: number): string {
+  const miss = (s: string) => (s.length < min ? min - s.length : s.length > max ? s.length - max : 0);
+  return candidates.find((s) => miss(s) === 0) ?? [...candidates].sort((a, b) => miss(a) - miss(b))[0];
+}

package/src/text/index.ts

@@ -1,3 +1,5 @@
 // Public surface of @sarimarcus/content-sites-core/text.
 export { slugify } from './slugify.ts';
 export { fitWithinLength } from './fitWithinLength.ts';
+export { fitLength } from './fitLength.ts';
+export { readingTime } from './readingTime.ts';

package/src/text/readingTime.ts

@@ -0,0 +1,52 @@
+import { marked } from 'marked';
+
+interface ArticleSection {
+  body?: string;
+  subsections?: Array<{ body?: string }>;
+}
+
+interface ArticleLike {
+  intro?: string;
+  sections?: ArticleSection[];
+}
+
+/**
+ * Strip Markdown / HTML markup and collapse whitespace so we can count
+ * real words. Uses `marked` to normalize Markdown, then removes HTML tags.
+ */
+function stripMarkup(markdown: string): string {
+  const html = marked.parse(markdown, { breaks: true, gfm: true, async: false });
+  return html
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\[\^(\d+)\]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function countWords(text: string): number {
+  const cleaned = stripMarkup(text);
+  if (!cleaned) return 0;
+  return cleaned.split(/\s+/).filter((w) => w.length > 0).length;
+}
+
+/**
+ * Estimate reading time for an article.
+ * Counts words from intro + section bodies + subsection bodies,
+ * strips Markdown, and divides by 220 WPM. Minimum 1 minute.
+ */
+export function readingTime(article: ArticleLike): number {
+  let words = 0;
+
+  if (article.intro) {
+    words += countWords(article.intro);
+  }
+
+  for (const section of article.sections ?? []) {
+    if (section.body) words += countWords(section.body);
+    for (const sub of section.subsections ?? []) {
+      if (sub.body) words += countWords(sub.body);
+    }
+  }
+
+  return Math.max(1, Math.round(words / 220));
+}