@acms-subir/core 0.2.0 → 0.3.0

package/src/lib/calendar/cards.ts

@@ -0,0 +1,102 @@
+// Event cards — the image-first "Coming up" look shared by the event card
+// block (data-dyn="events"), the /calendar page and embeds. Stable
+// .pc-ev-card* classes are the styling API, like .pc-cal-* for the grid.
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, Settings } from '../schema';
+import { siteLocale } from '../dates';
+import { eventUrl } from './config';
+import { eventIsPublic, featuredOccurrence, formatOccurrence, locationLine, type Occurrence } from './events';
+import { collectViewEvents } from './data';
+
+export interface EventCardAttrs {
+  mode: 'single' | 'upcoming';
+  eventId: string;
+  // calendar slug for upcoming mode; '' = every public calendar
+  calendar: string;
+  limit: number;
+  layout: 'grid' | 'list';
+  showImage: boolean;
+}
+
+const esc = (s: string) =>
+  String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+// javascript:/data: links must never reach an href
+export const safeHref = (h: string) => (/^(https?:\/\/|\/(?!\/)|mailto:|tel:|#)/i.test(h.trim()) ? h.trim() : '');
+
+export function eventCardHtml(
+  o: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>,
+  settings: Settings,
+  opts: { showImage: boolean; showCta?: boolean; href?: string; heading?: 'h2' | 'h3' }
+): string {
+  const e: CalEvent = o.event;
+  const tz = settings.timezone || 'UTC';
+  const f = formatOccurrence(o, tz, siteLocale(settings));
+  const href = opts.href ?? eventUrl(e.slug);
+  const h = opts.heading ?? 'h3';
+  // "Sat, Oct 3 · 11:00 AM", "Sat, Oct 3 · All day", "Sat, Oct 24 – Sun, Oct 25"
+  const when = f.range;
+  const media = opts.showImage
+    ? e.cover
+      ? `<a class="pc-ev-card-media" href="${esc(href)}" tabindex="-1" aria-hidden="true"><img src="${esc(e.cover)}" alt="${esc(e.coverAlt)}" loading="lazy" /></a>`
+      : `<a class="pc-ev-card-media is-tile" href="${esc(href)}" tabindex="-1" aria-hidden="true"><span class="pc-ev-tile"><b>${esc(f.month)}</b><span>${esc(f.day)}</span></span></a>`
+    : '';
+  const loc = locationLine(e.location);
+  const ctaHref = safeHref(e.cta.href);
+  const cta =
+    opts.showCta && e.cta.label && ctaHref && !e.cancelled
+      ? `<a class="pc-ev-cta${e.cta.style === 'outline' ? ' is-outline' : ''}" href="${esc(ctaHref)}">${esc(e.cta.label)}</a>`
+      : '';
+  return (
+    `<article class="pc-ev-card${e.cancelled ? ' is-cancelled' : ''}">${media}<div class="pc-ev-card-body">` +
+    `<div class="pc-ev-card-when">${e.cancelled ? '<span class="pc-ev-flag">Cancelled</span> ' : ''}${esc(when)}</div>` +
+    `<${h} class="pc-ev-card-title"><a href="${esc(href)}">${esc(e.title || 'Untitled event')}</a></${h}>` +
+    (e.excerpt ? `<p class="pc-ev-card-excerpt">${esc(e.excerpt)}</p>` : '') +
+    (loc ? `<div class="pc-ev-card-loc">${esc(loc)}</div>` : '') +
+    cta +
+    `</div></article>`
+  );
+}
+
+// next occurrence of each distinct event, soonest first
+export async function upcomingEvents(
+  repo: ContentRepository,
+  settings: Settings,
+  now: number,
+  opts: { calendarIds?: string[]; limit: number; horizonDays?: number }
+) {
+  const tz = settings.timezone || 'UTC';
+  const { events } = await collectViewEvents(repo, settings, {
+    displayTz: tz, now, windowStartMs: now, windowEndMs: now + (opts.horizonDays ?? 400) * 86_400_000,
+  }, { audience: 'public', calendarIds: opts.calendarIds, includeFeeds: false });
+  const seen = new Set<string>();
+  const out: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>[] = [];
+  for (const v of events) {
+    if (!v.event || v.end <= now || seen.has(v.event.id)) continue;
+    seen.add(v.event.id);
+    out.push({ event: v.event, start: v.start, end: v.end, allDay: v.allDay, days: v.days });
+    if (out.length >= opts.limit) break;
+  }
+  return out;
+}
+
+export async function renderEventCards(a: EventCardAttrs, repo: ContentRepository, settings: Settings, now: number): Promise<string> {
+  const wrap = (inner: string, extra = '') => `<section class="pc-ev-cards${extra}" data-layout="${a.layout}">${inner}</section>`;
+  if (a.mode === 'single') {
+    const e = a.eventId ? await repo.getEvent(a.eventId) : null;
+    const calendars = new Map((await repo.listCalendars()).map((c) => [c.id, c]));
+    if (!e || !eventIsPublic(e, calendars)) return wrap('<p class="pc-ev-empty">This event isn’t available.</p>', ' is-empty');
+    const o = featuredOccurrence(e, settings, now);
+    if (!o) return wrap('<p class="pc-ev-empty">This event isn’t available.</p>', ' is-empty');
+    return wrap(eventCardHtml(o, settings, { showImage: a.showImage, showCta: true }), ' is-single');
+  }
+  let calendarIds: string[] | undefined;
+  if (a.calendar) {
+    const c = await repo.getCalendarBySlug(a.calendar);
+    if (!c || c.visibility === 'private') return wrap('<p class="pc-ev-empty">No upcoming events.</p>', ' is-empty');
+    calendarIds = [c.id];
+  }
+  const items = await upcomingEvents(repo, settings, now, { calendarIds, limit: a.limit });
+  if (!items.length) return wrap('<p class="pc-ev-empty">No upcoming events.</p>', ' is-empty');
+  return wrap(items.map((o) => eventCardHtml(o, settings, { showImage: a.showImage })).join(''));
+}

package/src/lib/calendar/config.ts

@@ -0,0 +1,52 @@
+// Calendar module config, set per project via the integration:
+//   acms({ calendar: { base: '/calendar', eventsBase: '/events', eventFields: [...] } })
+// integration.mjs validates and fills defaults before serializing, so the
+// values here are always complete; the fallback only guards stale builds and
+// the test stub. `enabled: false` removes every calendar route and hides the
+// admin section — events stay in the database.
+import { userConfig } from 'virtual:acms-config';
+
+export type EventFieldType = 'text' | 'textarea' | 'number' | 'url' | 'select';
+
+export interface EventFieldConfig {
+  key: string;
+  label: string;
+  type: EventFieldType;
+  options: string[];
+}
+
+export interface CalendarConfig {
+  enabled: boolean;
+  base: string;
+  eventsBase: string;
+  // bookings: rooms, people and equipment at bookBase (off = no /book routes)
+  bookings: boolean;
+  bookBase: string;
+  resourceKinds: string[];
+  defaultView: 'month' | 'week' | 'list';
+  eventFields: EventFieldConfig[];
+}
+
+const FALLBACK: CalendarConfig = {
+  enabled: true,
+  base: '/calendar',
+  eventsBase: '/events',
+  bookings: true,
+  bookBase: '/book',
+  resourceKinds: ['Room', 'Person', 'Vehicle', 'Equipment'],
+  defaultView: 'month',
+  eventFields: [],
+};
+
+export const CALENDAR: CalendarConfig = { ...FALLBACK, ...(userConfig.calendar ?? {}) };
+
+export const eventUrl = (slug: string) => `${CALENDAR.eventsBase}/${slug}`;
+export const eventIcsUrl = (slug: string) => `${CALENDAR.eventsBase}/${slug}.ics`;
+export const calendarPageUrl = (slug?: string) => (slug ? `${CALENDAR.base}?cal=${encodeURIComponent(slug)}` : CALENDAR.base);
+export const calendarFeedUrl = (slug?: string) => (slug ? `${CALENDAR.base}/${slug}.ics` : `${CALENDAR.base}.ics`);
+
+export const bookingsEnabled = () => CALENDAR.enabled && CALENDAR.bookings;
+export const resourceUrl = (slug: string) => `${CALENDAR.bookBase}/${slug}`;
+export const bookingLinkUrl = (resourceSlug: string, linkSlug: string) => `${CALENDAR.bookBase}/${resourceSlug}/${linkSlug}`;
+export const manageUrl = (token: string) => `${CALENDAR.bookBase}/manage/${token}`;
+export const resourceFeedUrl = (slug: string, token: string) => `${CALENDAR.bookBase}/${slug}.ics?t=${encodeURIComponent(token)}`;

package/src/lib/calendar/data.ts

@@ -0,0 +1,130 @@
+// One place that answers "which occurrences does this view show?" for every
+// calendar surface — the /calendar page, the calendar card, embeds, the admin
+// agenda. Native events are expanded from the DB; feed calendars are fetched
+// live through the cached ICS loader. Visibility rules live in events.ts.
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, Calendar, Settings } from '../schema';
+import { eventIsListed, eventIsPublic, expandEvents, safeColor } from './events';
+import { expandVEvents, loadFeed, tzParts, type CalendarEvent, type CalendarWindow } from './ics';
+import { CALENDAR, eventUrl, resourceUrl } from './config';
+
+export interface ViewEvent extends CalendarEvent {
+  url?: string;
+  color?: string;
+  cancelled?: boolean;
+  image?: string;
+  imageAlt?: string;
+  calendarName?: string;
+  event?: CalEvent;
+}
+
+export interface ViewScope {
+  audience: 'public' | 'admin';
+  // limit to these calendars; omitted = every calendar the audience may see
+  calendarIds?: string[];
+  // native events outside any calendar (public only when unscoped)
+  includeUncategorized?: boolean;
+  // feeds are network calls — views that don't need them can skip
+  includeFeeds?: boolean;
+  // "Reserved" blocks from resources set to show on the calendar
+  includeBookings?: boolean;
+}
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+export async function collectViewEvents(
+  repo: ContentRepository,
+  settings: Pick<Settings, 'timezone'>,
+  win: CalendarWindow,
+  scope: ViewScope
+): Promise<{ events: ViewEvent[]; calendars: Calendar[]; errors: string[] }> {
+  const all = await repo.listCalendars();
+  const byId = new Map(all.map((c) => [c.id, c]));
+  const requested = scope.calendarIds ? new Set(scope.calendarIds) : null;
+  const visible = all.filter((c) => {
+    if (scope.audience === 'admin') return true;
+    // a directly requested calendar may be unlisted; private never is
+    return requested ? c.visibility !== 'private' : c.visibility === 'public';
+  });
+  const inScope = requested ? visible.filter((c) => requested.has(c.id)) : visible;
+  const idx = new Map(inScope.map((c, i) => [c.id, i]));
+  const scoped = new Set(inScope.map((c) => c.id));
+  const tz = settings.timezone || 'UTC';
+
+  const source = scope.audience === 'admin' ? (await repo.listEvents()).filter((e) => e.status !== 'archived') : await repo.listPublishedEvents();
+  const natives = source.filter((e) => {
+    if (scope.audience === 'public' && !eventIsPublic(e, byId)) return false;
+    if (!e.calendarIds.length) {
+      if (requested) return false;
+      return scope.includeUncategorized ?? true;
+    }
+    if (!requested && scope.audience === 'public') return eventIsListed(e, byId);
+    return e.calendarIds.some((id) => scoped.has(id));
+  });
+
+  const events: ViewEvent[] = [];
+  for (const o of expandEvents(natives, settings, win)) {
+    const e = o.event;
+    const cal = e.calendarIds.map((id) => byId.get(id)).find((c) => c && scoped.has(c.id));
+    const p = tzParts(o.start, tz);
+    const on = e.rrule ? `?on=${p.y}-${pad(p.m)}-${pad(p.d)}` : '';
+    events.push({
+      start: o.start, end: o.end, allDay: o.allDay, days: o.days,
+      title: e.title || 'Untitled event',
+      location: [e.location.name, e.location.address].filter(Boolean).join(', '),
+      description: e.excerpt,
+      cal: cal ? idx.get(cal.id) ?? 0 : 0,
+      ref: e.id,
+      url: eventUrl(e.slug) + on,
+      color: cal ? safeColor(cal.color) : undefined,
+      cancelled: e.cancelled,
+      image: e.cover || undefined,
+      imageAlt: e.coverAlt || undefined,
+      calendarName: cal?.name,
+      event: e,
+    });
+  }
+
+  const errors: string[] = [];
+  if (scope.includeFeeds ?? true) {
+    const feeds = inScope.filter((c) => c.kind === 'feed' && c.feedUrl);
+    const results = await Promise.all(
+      feeds.map(async (c) => {
+        try {
+          const feed = await loadFeed(c.feedUrl, win.now);
+          return expandVEvents(feed.vevents, feed.calTz, win, idx.get(c.id) ?? 0).map<ViewEvent>((ev) => ({
+            ...ev, color: safeColor(c.color), calendarName: c.name,
+          }));
+        } catch (err) {
+          errors.push(`${c.name}: ${err instanceof Error ? err.message : 'feed failed'}`);
+          return [];
+        }
+      })
+    );
+    events.push(...results.flat());
+  }
+
+  // resources marked "show on calendar": confirmed bookings appear as
+  // Reserved blocks (no guest names on public views) — only on unscoped views
+  if (!requested && (scope.includeBookings ?? true) && CALENDAR.bookings) {
+    const resources = (await repo.listResources()).filter((r) => r.showOnCalendar);
+    if (resources.length) {
+      const booked = await repo.listBookings({ from: win.windowStartMs, to: win.windowEndMs, statuses: ['confirmed'], kinds: ['booking'] });
+      const byId = new Map(resources.map((r) => [r.id, r]));
+      for (const b of booked) {
+        const r = byId.get(b.resourceId);
+        if (!r) continue;
+        const allDay = b.end - b.start >= 86_400_000 - 3_600_000;
+        events.push({
+          start: b.start, end: b.end, allDay, days: allDay ? Math.max(1, Math.round((b.end - b.start) / 86_400_000)) : 1,
+          title: scope.audience === 'admin' ? `${r.name} · ${b.name}` : `Reserved · ${r.name}`,
+          location: r.name, description: '', cal: inScope.length, color: '#8e919a', calendarName: r.name,
+          url: scope.audience === 'public' ? resourceUrl(r.slug) : undefined,
+        });
+      }
+    }
+  }
+
+  events.sort((a, b) => a.start - b.start || a.title.localeCompare(b.title));
+  return { events: events.slice(0, 1500), calendars: inScope, errors };
+}

package/src/lib/calendar/events.ts

@@ -0,0 +1,261 @@
+// Native events: wall-clock time math, recurrence expansion (reusing the ICS
+// expander, so feed events and native events follow identical rules),
+// visibility, and "add to calendar" links. Pure — no repo, no fetch.
+import type { CalEvent, Calendar, EventLocation, Settings } from '../schema';
+import { expandVEvents, tzParts, zonedToUtc, type CalendarWindow, type IcsTime, type VEvent } from './ics';
+import { cleanRrule } from './rrule';
+
+const DAY = 86_400_000;
+
+export interface Wall {
+  y: number; m: number; d: number; hh: number; mm: number;
+  dateOnly: boolean;
+}
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+export function parseWall(s: string | undefined | null): Wall | null {
+  if (!s) return null;
+  const m = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::\d{2})?)?$/.exec(s.trim());
+  if (!m) return null;
+  const w: Wall = { y: +m[1], m: +m[2], d: +m[3], hh: m[4] ? +m[4] : 0, mm: m[5] ? +m[5] : 0, dateOnly: !m[4] };
+  const probe = new Date(Date.UTC(w.y, w.m - 1, w.d));
+  if (probe.getUTCMonth() !== w.m - 1 || probe.getUTCDate() !== w.d || w.hh > 23 || w.mm > 59) return null;
+  return w;
+}
+
+export const wallDate = (w: Wall) => `${w.y}-${pad(w.m)}-${pad(w.d)}`;
+export const formatWall = (w: Wall) => (w.dateOnly ? wallDate(w) : `${wallDate(w)}T${pad(w.hh)}:${pad(w.mm)}`);
+
+// wall-clock arithmetic in "floating" time (no zone): minutes since epoch
+const wallMinutes = (w: Wall) => Date.UTC(w.y, w.m - 1, w.d, w.hh, w.mm) / 60_000;
+function fromMinutes(min: number, dateOnly: boolean): Wall {
+  const dt = new Date(min * 60_000);
+  return { y: dt.getUTCFullYear(), m: dt.getUTCMonth() + 1, d: dt.getUTCDate(), hh: dateOnly ? 0 : dt.getUTCHours(), mm: dateOnly ? 0 : dt.getUTCMinutes(), dateOnly };
+}
+export const addWallDays = (w: Wall, n: number) => fromMinutes(wallMinutes(w) + n * 1440, w.dateOnly);
+
+export function isValidTimeZone(tz: string): boolean {
+  if (!tz) return false;
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function eventTimeZone(e: Pick<CalEvent, 'timezone'>, settings: Pick<Settings, 'timezone'>): string {
+  const tz = e.timezone || settings.timezone || 'UTC';
+  return isValidTimeZone(tz) ? tz : 'UTC';
+}
+
+const wallToMs = (w: Wall, tz: string) => zonedToUtc(w.y, w.m, w.d, w.dateOnly ? 0 : w.hh, w.dateOnly ? 0 : w.mm, 0, tz);
+
+// Validate + fill defaults for a start/end pair. Timed events default to one
+// hour and never end before they start; all-day events store their inclusive
+// last day. Throws a user-facing message on unparseable input.
+export function normalizeEventTimes(input: { start: string; end?: string; allDay: boolean }): { start: string; end: string } {
+  const s = parseWall(input.start);
+  if (!s) throw new Error('Start must be a date (YYYY-MM-DD) or a date and time (YYYY-MM-DDTHH:mm).');
+  const e = parseWall(input.end);
+  if (input.allDay) {
+    const sd: Wall = { ...s, hh: 0, mm: 0, dateOnly: true };
+    let ed: Wall = e ? { ...e, hh: 0, mm: 0, dateOnly: true } : sd;
+    if (wallMinutes(ed) < wallMinutes(sd)) ed = sd;
+    return { start: formatWall(sd), end: formatWall(ed) };
+  }
+  const st: Wall = s.dateOnly ? { ...s, hh: 9, mm: 0, dateOnly: false } : s;
+  let et: Wall | null = e ? (e.dateOnly ? { ...e, hh: st.hh, mm: st.mm, dateOnly: false } : e) : null;
+  if (!et || wallMinutes(et) <= wallMinutes(st)) et = fromMinutes(wallMinutes(st) + 60, false);
+  return { start: formatWall(st), end: formatWall(et) };
+}
+
+// UTC instants of the first occurrence (all-day: midnight → midnight after
+// the last day, in the event's zone)
+export function eventInstants(e: Pick<CalEvent, 'start' | 'end' | 'allDay'>, tz: string): { startAt: number; endAt: number } {
+  const s = parseWall(e.start);
+  if (!s) return { startAt: 0, endAt: 0 };
+  const en = parseWall(e.end) ?? s;
+  if (e.allDay) {
+    return { startAt: wallToMs({ ...s, dateOnly: true }, tz), endAt: wallToMs(addWallDays({ ...en, dateOnly: true }, 1), tz) };
+  }
+  return { startAt: wallToMs(s, tz), endAt: wallToMs(en, tz) };
+}
+
+export const locationLine = (loc: EventLocation) => [loc.name, loc.address].filter(Boolean).join(', ');
+
+export function toVEvent(e: CalEvent, tz: string): VEvent | null {
+  const s = parseWall(e.start);
+  if (!s) return null;
+  const en = parseWall(e.end) ?? s;
+  const t = (w: Wall, dateOnly: boolean): IcsTime => ({
+    y: w.y, m: w.m, d: w.d, hh: dateOnly ? 0 : w.hh, mm: dateOnly ? 0 : w.mm, ss: 0,
+    tz: dateOnly ? null : tz, dateOnly, utc: false,
+  });
+  return {
+    uid: e.id,
+    ref: e.id,
+    title: e.title,
+    location: locationLine(e.location),
+    description: e.excerpt,
+    // cancelled events stay on the calendar (struck through), so the expander
+    // must still produce them
+    cancelled: false,
+    start: t(s, e.allDay),
+    end: e.allDay ? t(addWallDays({ ...en, dateOnly: true }, 1), true) : t(en, false),
+    rrule: cleanRrule(e.rrule),
+    exdates: e.exdates.map(parseWall).filter((w): w is Wall => w !== null).map((w) => t(w, e.allDay)),
+    recurrenceId: null,
+  };
+}
+
+export interface Occurrence {
+  event: CalEvent;
+  start: number;
+  end: number;
+  allDay: boolean;
+  days: number;
+}
+
+export function expandEvents(events: CalEvent[], settings: Pick<Settings, 'timezone'>, win: CalendarWindow): Occurrence[] {
+  const out: Occurrence[] = [];
+  for (const e of events) {
+    const tz = eventTimeZone(e, settings);
+    const v = toVEvent(e, tz);
+    if (!v) continue;
+    for (const o of expandVEvents([v], tz, win, 0)) {
+      out.push({ event: e, start: o.start, end: o.end, allDay: o.allDay, days: o.days });
+    }
+  }
+  return out.sort((a, b) => a.start - b.start || a.event.title.localeCompare(b.event.title));
+}
+
+// The occurrence to feature for an event: the next one that hasn't ended,
+// else the most recent. `on` ('YYYY-MM-DD') picks a specific day's instance
+// (links from the calendar grid carry it).
+export function featuredOccurrence(e: CalEvent, settings: Pick<Settings, 'timezone'>, now: number, on?: string): Occurrence | null {
+  const tz = eventTimeZone(e, settings);
+  const displayTz = settings.timezone || 'UTC';
+  if (on) {
+    const w = parseWall(on);
+    if (w) {
+      const from = zonedToUtc(w.y, w.m, w.d, 0, 0, 0, displayTz);
+      const hit = expandEvents([e], settings, { displayTz, now, windowStartMs: from, windowEndMs: from + DAY })
+        .find((o) => o.start >= from - DAY);
+      if (hit) return hit;
+    }
+  }
+  if (!e.rrule) {
+    const { startAt, endAt } = eventInstants(e, tz);
+    const s = parseWall(e.start);
+    const en = parseWall(e.end) ?? s;
+    const days = e.allDay && s && en ? Math.round((wallMinutes(en) - wallMinutes(s)) / 1440) + 1 : 1;
+    return { event: e, start: startAt, end: endAt, allDay: e.allDay, days };
+  }
+  const next = expandEvents([e], settings, { displayTz, now, windowStartMs: now, windowEndMs: now + 3 * 366 * DAY })[0];
+  if (next) return next;
+  const past = expandEvents([e], settings, { displayTz, now, windowStartMs: now - 3 * 366 * DAY, windowEndMs: now });
+  return past[past.length - 1] ?? null;
+}
+
+// ---- visibility ----------------------------------------------------------
+// An event with no calendars counts as public. Otherwise it follows its most
+// open calendar: any public/unlisted calendar makes the event page public;
+// only public calendars put it on the main calendar page and site feed.
+
+export function eventIsPublic(e: CalEvent, calendars: Map<string, Calendar>): boolean {
+  if (e.status !== 'published') return false;
+  if (!e.calendarIds.length) return true;
+  return e.calendarIds.some((id) => {
+    const c = calendars.get(id);
+    return c ? c.visibility !== 'private' : false;
+  });
+}
+
+export function eventIsListed(e: CalEvent, calendars: Map<string, Calendar>): boolean {
+  if (e.status !== 'published') return false;
+  if (!e.calendarIds.length) return true;
+  return e.calendarIds.some((id) => calendars.get(id)?.visibility === 'public');
+}
+
+// ---- formatting ----------------------------------------------------------
+
+export function formatOccurrence(
+  o: Pick<Occurrence, 'start' | 'end' | 'allDay' | 'days'>,
+  tz: string,
+  locale: string
+): { date: string; time: string; range: string; month: string; day: string; weekday: string } {
+  const safe = (opts: Intl.DateTimeFormatOptions) => {
+    try { return new Intl.DateTimeFormat(locale, { ...opts, timeZone: tz }); }
+    catch { return new Intl.DateTimeFormat('en-US', { ...opts, timeZone: 'UTC' }); }
+  };
+  const dateFmt = safe({ weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' });
+  const shortFmt = safe({ weekday: 'short', month: 'short', day: 'numeric' });
+  const timeFmt = safe({ hour: 'numeric', minute: '2-digit' });
+  const zoneFmt = safe({ hour: 'numeric', timeZoneName: 'short' });
+  const zone = zoneFmt.formatToParts(o.start).find((p) => p.type === 'timeZoneName')?.value ?? '';
+  const date = dateFmt.format(o.start);
+  let time: string;
+  let range: string;
+  if (o.allDay) {
+    time = o.days > 1 ? `${shortFmt.format(o.start)} – ${shortFmt.format(o.end - DAY)}` : 'All day';
+    range = o.days > 1 ? time : `${shortFmt.format(o.start)} · All day`;
+  } else {
+    time = `${timeFmt.format(o.start)} – ${timeFmt.format(o.end)}${zone ? ` ${zone}` : ''}`;
+    range = `${shortFmt.format(o.start)} · ${timeFmt.format(o.start)}`;
+  }
+  const p = tzParts(o.start, tz);
+  return {
+    date, time, range,
+    month: safe({ month: 'short' }).format(o.start).toUpperCase(),
+    day: String(p.d),
+    weekday: safe({ weekday: 'short' }).format(o.start),
+  };
+}
+
+// ---- add to calendar -----------------------------------------------------
+
+const utcStamp = (ms: number) => new Date(ms).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+const dateStamp = (ms: number, tz: string) => {
+  const p = tzParts(ms, tz);
+  return `${p.y}${pad(p.m)}${pad(p.d)}`;
+};
+
+export function addToCalendarLinks(
+  e: CalEvent,
+  o: Pick<Occurrence, 'start' | 'end' | 'allDay'>,
+  opts: { pageUrl: string; icsUrl: string; tz: string }
+): { google: string; outlook: string; ics: string } {
+  const details = [e.excerpt, opts.pageUrl].filter(Boolean).join('\n\n');
+  const loc = [locationLine(e.location), e.location.url].filter(Boolean).join(' · ');
+  const g = new URLSearchParams({
+    action: 'TEMPLATE',
+    text: e.title,
+    dates: o.allDay ? `${dateStamp(o.start, opts.tz)}/${dateStamp(o.end, opts.tz)}` : `${utcStamp(o.start)}/${utcStamp(o.end)}`,
+    details,
+    location: loc,
+  });
+  if (!o.allDay) g.set('ctz', opts.tz);
+  const rule = cleanRrule(e.rrule);
+  if (rule) g.set('recur', `RRULE:${rule}`);
+  const iso = (ms: number) => new Date(ms).toISOString();
+  const ol = new URLSearchParams({
+    path: '/calendar/action/compose',
+    rru: 'addevent',
+    subject: e.title,
+    startdt: o.allDay ? `${dateStamp(o.start, opts.tz).replace(/(\d{4})(\d{2})(\d{2})/, '$1-$2-$3')}` : iso(o.start),
+    enddt: o.allDay ? `${dateStamp(o.end, opts.tz).replace(/(\d{4})(\d{2})(\d{2})/, '$1-$2-$3')}` : iso(o.end),
+    body: details,
+    location: loc,
+    allday: o.allDay ? 'true' : 'false',
+  });
+  return {
+    google: `https://calendar.google.com/calendar/render?${g}`,
+    outlook: `https://outlook.live.com/calendar/0/deeplink/compose?${ol}`,
+    ics: opts.icsUrl,
+  };
+}
+
+// a #rrggbb color or the default — calendar colors reach inline styles
+export const safeColor = (c: string, fallback = '#4f46e5') => (/^#[0-9a-f]{6}$/i.test(c) ? c.toLowerCase() : fallback);

package/src/lib/calendar/feeds.ts

@@ -0,0 +1,43 @@
+// Shared plumbing for the ICS routes: which events a feed carries and the
+// response headers calendar apps expect.
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, Calendar, Settings } from '../schema';
+import { buildFeed } from './ics-write';
+import { eventIsListed, eventIsPublic } from './events';
+import { eventUrl } from './config';
+
+export function icsResponse(body: string, filename: string, cacheSeconds = 300): Response {
+  return new Response(body, {
+    headers: {
+      'Content-Type': 'text/calendar; charset=utf-8',
+      'Content-Disposition': `inline; filename="${filename.replace(/[^a-z0-9._-]/gi, '')}"`,
+      'Cache-Control': `public, max-age=${cacheSeconds}`,
+      'Access-Control-Allow-Origin': '*',
+    },
+  });
+}
+
+export async function feedFor(
+  repo: ContentRepository,
+  settings: Settings,
+  origin: string,
+  scope: { calendar?: Calendar; allowPrivate?: boolean }
+): Promise<{ events: CalEvent[]; body: string }> {
+  const [published, calendars] = await Promise.all([repo.listPublishedEvents(), repo.listCalendars()]);
+  const map = new Map(calendars.map((c) => [c.id, c]));
+  const c = scope.calendar;
+  const events = published.filter((e) =>
+    c
+      ? e.calendarIds.includes(c.id) && (scope.allowPrivate || eventIsPublic(e, map) || c.visibility !== 'private')
+      : eventIsListed(e, map)
+  );
+  const host = new URL(origin).host;
+  const body = buildFeed(events, settings.timezone, {
+    name: c ? `${c.name} · ${settings.siteTitle}` : settings.siteTitle,
+    description: c?.description || settings.tagline,
+    origin, host, tz: settings.timezone || 'UTC',
+    eventUrl: (e) => eventUrl(e.slug),
+    calendars: map,
+  });
+  return { events, body };
+}

package/src/lib/calendar/hooks.ts

@@ -0,0 +1,38 @@
+// Side effects when an event changes live: a 301 when a published event's
+// slug moves, and the matching webhook (event.published / event.updated /
+// event.unpublished). Shared by the editor actions, the list's bulk actions
+// and the agent tools so every path behaves the same.
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent } from '../schema';
+import { emitWebhook } from '../webhooks';
+import { eventToJson } from './api';
+import { eventUrl } from './config';
+
+export async function eventChanged(
+  repo: ContentRepository,
+  before: CalEvent,
+  after: CalEvent,
+  opts: { origin: string; waitUntil?: (p: Promise<unknown>) => void; applied?: boolean; onRedirect?: () => void }
+): Promise<void> {
+  if (before.status === 'published' && after.status === 'published' && before.slug !== after.slug) {
+    await repo.createRedirect({ fromPath: eventUrl(before.slug), toPath: eventUrl(after.slug) }).catch(() => {});
+    opts.onRedirect?.();
+  }
+  let type: 'event.published' | 'event.updated' | 'event.unpublished' | null = null;
+  if (before.status !== 'published' && after.status === 'published') type = 'event.published';
+  else if (before.status === 'published' && after.status !== 'published') type = 'event.unpublished';
+  else if (after.status === 'published' && (opts.applied || before.updatedAt !== after.updatedAt)) type = 'event.updated';
+  if (!type) return;
+  const [settings, calendars] = await Promise.all([repo.getSettings(), repo.listCalendars()]);
+  const data = eventToJson(after, opts.origin, new Map(calendars.map((c) => [c.id, c])), settings.timezone);
+  await emitWebhook(repo, type, { event: data }, { waitUntil: opts.waitUntil }).catch(() => {});
+}
+
+export async function eventDeleted(
+  repo: ContentRepository,
+  before: CalEvent | null,
+  opts: { waitUntil?: (p: Promise<unknown>) => void }
+): Promise<void> {
+  if (before?.status !== 'published') return;
+  await emitWebhook(repo, 'event.deleted', { event: { id: before.id, slug: before.slug, title: before.title } }, opts).catch(() => {});
+}

package/src/lib/calendar/http.ts

@@ -0,0 +1,30 @@
+// Shared plumbing for the /api/calendar/* routes: CORS (other sites and
+// apps call these from browsers), JSON errors, and the booking-error bridge.
+import { ApiError, apiError } from '../api';
+import { BookingError } from '../booking/service';
+
+export const CORS: Record<string, string> = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+  'Access-Control-Max-Age': '86400',
+};
+
+export const preflight = () => new Response(null, { status: 204, headers: CORS });
+
+export function withCors(res: Response): Response {
+  for (const [k, v] of Object.entries(CORS)) res.headers.set(k, v);
+  return res;
+}
+
+export function fail(error: unknown): Response {
+  if (error instanceof BookingError) return withCors(apiError(new ApiError(error.status, error.message)));
+  return withCors(apiError(error));
+}
+
+// ISO string or epoch ms → epoch ms
+export function toMs(v: unknown, label: string): number {
+  const n = typeof v === 'number' ? v : typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : Date.parse(String(v ?? ''));
+  if (!Number.isFinite(n)) throw new ApiError(400, `"${label}" must be an ISO date-time or epoch milliseconds.`);
+  return n;
+}