@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/src/lib/sections-agent.ts

@@ -0,0 +1,146 @@
+// Agent / MCP tools for editable sections: an agent can read what sections a
+// page can use, arrange a layout, and change a section's data ("move Youth
+// Night to 7:30") without touching theme code. Everything stages into the
+// design draft; publishing one section needs the owner's publish permission.
+import { z } from 'zod';
+import type { ContentRepository } from './repo/types';
+import { ApiError } from './api';
+import { FieldValue, sectionIssues } from '../theme-sdk/contract.mjs';
+import { initialData, normalizeData, translationUnits, unitStatus } from '../theme-sdk/fields.mjs';
+import { extraLocales } from './i18n';
+import { publishOneSection, validateSectionDesign } from './design-service';
+import type { Settings } from './schema';
+
+const Data = z.record(z.string().max(100), FieldValue);
+export const SectionToolInputs = [
+  z.object({ tool: z.literal('list_section_types'), arguments: z.object({}).strict() }).strict(),
+  z.object({ tool: z.literal('get_page_layout'), arguments: z.object({ pageId: z.string().min(1).max(100) }).strict() }).strict(),
+  z.object({ tool: z.literal('set_page_layout'), arguments: z.object({
+    pageId: z.string().min(1).max(100),
+    mode: z.enum(['sections', 'content']).default('sections'),
+    sections: z.array(z.object({
+      id: z.string().min(1).max(100).optional(), type: z.string().min(1).max(50),
+      variant: z.string().max(50).optional(), hidden: z.boolean().optional(), data: Data.default({}),
+    }).strict()).max(50),
+  }).strict() }).strict(),
+  z.object({ tool: z.literal('update_section_data'), arguments: z.object({
+    pageId: z.string().min(1).max(100), sectionId: z.string().min(1).max(100),
+    data: Data.default({}), variant: z.string().max(50).optional(), hidden: z.boolean().optional(),
+    // words in another site language, by path (see get_page_layout's translationPaths); stored as AI drafts for review
+    translation: z.object({ locale: z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/), data: z.record(z.string().max(200), z.string().max(20_000)) }).strict().optional(),
+    publish: z.boolean().default(false),
+  }).strict() }).strict(),
+] as const;
+export const SECTION_TOOL_NAMES = ['list_section_types', 'get_page_layout', 'set_page_layout', 'update_section_data'] as const;
+export const SECTION_TOOL_DESCRIPTIONS: Record<(typeof SECTION_TOOL_NAMES)[number], string> = {
+  list_section_types: 'List the section types the active theme offers (built-in and coded), with each field’s type, variants and the theme’s starting layouts. Read this before arranging a page.',
+  get_page_layout: 'Read a page’s section layout: the staged draft if one exists, otherwise the live layout. Returns section ids, types, variants, data, and per site language the translatable paths with their English text and status (missing, ai, reviewed, outdated).',
+  set_page_layout: 'Replace a page’s whole section layout in the design draft. Never publishes. Keep existing section ids to preserve them; omit id for new sections. Data keys must match the section’s fields.',
+  update_section_data: 'Change one section’s data (merged over existing values; lists are replaced whole), variant or visibility in the design draft. `translation: { locale, data: { path: text } }` writes words in another site language (paths from get_page_layout) as AI drafts for review. publish: true also makes just this section live when the owner allows agent publishing.',
+};
+
+type Pages = Settings['sectionPages'];
+type Input = { tool: (typeof SECTION_TOOL_NAMES)[number]; arguments: Record<string, unknown> };
+const reviewUrl = (pageId: string, sectionId?: string) => `/admin/design?page=${encodeURIComponent(pageId)}${sectionId ? `&section=${encodeURIComponent(sectionId)}` : ''}#pages`;
+const newId = (type: string) => `${type}-${crypto.randomUUID().slice(0, 8)}`;
+
+export async function runSectionTool(repo: ContentRepository, input: Input, allowPublish: boolean) {
+  // lazy: the theme registry globs .astro templates, which only Astro can load
+  const { getTheme } = await import('./theme');
+  const settings = await repo.getSettings();
+  if ((input.tool === 'set_page_layout' || input.tool === 'update_section_data') && !settings.agent.allowSections) {
+    throw new ApiError(403, 'Section editing is off for agents. An owner can turn it on in Settings → AI & agents.');
+  }
+  const themeSlug = String(settings.draftDesign?.activeTheme ?? settings.activeTheme);
+  const theme = getTheme(themeSlug);
+  const staged = (settings.draftDesign?.sectionPages ?? settings.sectionPages) as Pages;
+
+  if (input.tool === 'list_section_types') {
+    return {
+      theme: theme.slug,
+      sections: Object.entries(theme.sections).map(([type, d]) => ({
+        type, name: d.name, description: d.description ?? '', version: d.version, variants: d.variants,
+        coded: type in (theme.sectionTemplates ?? {}), fields: d.fields,
+      })),
+      presets: Object.entries(theme.presets ?? {}).map(([key, p]) => ({ key, name: p.name, description: p.description ?? '', sections: p.sections })),
+      pages: (await repo.listPages()).map((p) => ({ id: p.id, title: p.title, slug: p.slug, isHome: p.isHome, hasLayout: Boolean(staged[p.id]) })),
+    };
+  }
+
+  const pageId = String(input.arguments.pageId);
+  const page = await repo.getPage(pageId);
+  if (!page) throw new ApiError(404, 'Page not found.');
+
+  if (input.tool === 'get_page_layout') {
+    const layout = staged[pageId] ?? null;
+    return {
+      pageId, title: page.title, theme: theme.slug, layout,
+      staged: JSON.stringify(layout) !== JSON.stringify(settings.sectionPages[pageId] ?? null),
+      issues: layout ? sectionIssues({ ...layout, sections: layout.sections.filter((s) => !s.hidden) }, theme.sections) : [],
+      translations: layout ? Object.fromEntries(extraLocales().map((l) => [l, layout.sections.flatMap((s) => {
+        const def = theme.sections[s.type];
+        return def ? (translationUnits(def, s.data) as { path: string; source: string; hash: string }[]).map((u) => ({ sectionId: s.id, path: u.path, english: u.source, status: unitStatus(u, s.translations?.[l]), text: s.translations?.[l]?.data?.[u.path] ?? '' })) : [];
+      })])) : {},
+      reviewUrl: reviewUrl(pageId),
+    };
+  }
+
+  if (input.tool === 'set_page_layout') {
+    const a = z.object(SectionToolInputs[2].shape.arguments.shape).parse(input.arguments);
+    const previous = new Map((staged[pageId]?.sections ?? []).map((s) => [s.id, s]));
+    const ids = new Set<string>();
+    const sections = a.sections.map((s) => {
+      const def = theme.sections[s.type];
+      if (!def) throw new ApiError(400, `Unknown section type “${s.type}”. Call list_section_types.`);
+      const unknown = Object.keys(s.data).filter((k) => !(k in def.fields));
+      if (unknown.length) throw new ApiError(400, `Section ${s.type} has no field(s): ${unknown.join(', ')}.`);
+      const id = s.id && !ids.has(s.id) ? s.id : newId(s.type);
+      ids.add(id);
+      const prev = previous.get(id);
+      const variant = s.variant ?? prev?.variant ?? def.variants[0];
+      if (!def.variants.includes(variant)) throw new ApiError(400, `Section ${s.type} has no variant “${variant}”. Use one of: ${def.variants.join(', ')}.`);
+      return { id, type: s.type, version: def.version, variant, hidden: s.hidden ?? prev?.hidden ?? false, ...(prev?.type === s.type && prev.translations ? { translations: prev.translations } : {}),
+        data: normalizeData(def, { ...initialData(def), ...(prev?.type === s.type ? prev.data : {}), ...s.data }) as Pages[string]['sections'][number]['data'] };
+    });
+    const layout = { mode: a.mode, sections };
+    const issues = sectionIssues({ ...layout, sections: sections.filter((s) => !s.hidden) }, theme.sections);
+    if (issues.length) throw new ApiError(400, `Fix these before staging: ${issues.slice(0, 5).map((i) => i.message).join('; ')}`);
+    await repo.setDesignDraft({ ...settings.draftDesign, sectionPages: { ...staged, [pageId]: layout } }, settings.designRevision, 'agent');
+    return { pageId, staged: true, sections: sections.map((s) => ({ id: s.id, type: s.type, variant: s.variant })), reviewUrl: reviewUrl(pageId) };
+  }
+
+  // update_section_data
+  const a = z.object(SectionToolInputs[3].shape.arguments.shape).parse(input.arguments);
+  const layout = staged[pageId];
+  const current = layout?.sections.find((s) => s.id === a.sectionId);
+  if (!layout || !current) throw new ApiError(404, 'Section not found on that page. Call get_page_layout.');
+  const def = theme.sections[current.type];
+  if (!def) throw new ApiError(409, `The active theme has no “${current.type}” section.`);
+  const unknown = Object.keys(a.data).filter((k) => !(k in def.fields));
+  if (unknown.length) throw new ApiError(400, `Section ${current.type} has no field(s): ${unknown.join(', ')}.`);
+  if (a.variant && !def.variants.includes(a.variant)) throw new ApiError(400, `Use one of: ${def.variants.join(', ')}.`);
+  let next = { ...current, variant: a.variant ?? current.variant, hidden: a.hidden ?? current.hidden, data: { ...current.data, ...a.data } };
+  if (a.translation) {
+    if (!extraLocales().includes(a.translation.locale)) throw new ApiError(400, `“${a.translation.locale}” isn’t one of this site’s extra languages.`);
+    const units = new Map((translationUnits(def, next.data) as { path: string; hash: string }[]).map((u) => [u.path, u]));
+    const bad = Object.keys(a.translation.data).filter((p) => !units.has(p));
+    if (bad.length) throw new ApiError(400, `No translatable text at: ${bad.join(', ')}. Call get_page_layout for paths.`);
+    const cur = next.translations?.[a.translation.locale] ?? { data: {}, meta: {} };
+    const tdata = { ...cur.data }, meta = { ...cur.meta };
+    for (const [path, text] of Object.entries(a.translation.data)) {
+      if (text.trim()) { tdata[path] = text; meta[path] = { state: 'ai', src: units.get(path)!.hash }; } else { delete tdata[path]; delete meta[path]; }
+    }
+    next = { ...next, translations: { ...(next.translations ?? {}), [a.translation.locale]: { data: tdata, meta } } };
+  }
+  const issues = sectionIssues({ mode: 'sections', sections: [next] }, theme.sections);
+  if (issues.length) throw new ApiError(400, `Fix these before staging: ${issues.map((i) => i.message).join('; ')}`);
+  const pages: Pages = { ...staged, [pageId]: { ...layout, sections: layout.sections.map((s) => (s.id === next.id ? next : s)) } };
+  await repo.setDesignDraft({ ...settings.draftDesign, sectionPages: pages }, settings.designRevision, 'agent');
+  if (!a.publish) return { pageId, sectionId: next.id, staged: true, published: false, reviewUrl: reviewUrl(pageId, next.id) };
+  if (!allowPublish) throw new ApiError(403, 'Staged, but agent publishing is disabled. An owner can publish it in Design → Pages.');
+  const fresh = await repo.getSettings();
+  const out = publishOneSection(fresh.sectionPages, (fresh.draftDesign?.sectionPages ?? fresh.sectionPages) as Pages, pageId, next.id);
+  validateSectionDesign({ ...fresh, sectionPages: out.live }, getTheme(fresh.activeTheme));
+  await repo.publishSectionPages(out.live, out.staged, { expectedRevision: fresh.designRevision, author: 'agent', summary: `Section: ${next.type}` });
+  return { pageId, sectionId: next.id, staged: false, published: true, reviewUrl: reviewUrl(pageId, next.id) };
+}

package/src/lib/sections.ts

@@ -0,0 +1,217 @@
+import sanitizeHtml from 'sanitize-html';
+import type { z } from 'zod';
+import type { ContentRepository } from './repo/types';
+import type { Settings } from './schema';
+import type { SectionInstance as SectionInstanceSchema, SectionDefinition } from '../theme-sdk/contract.mjs';
+import { normalizeData, safeUrl, SOURCE_LIMIT_MAX, isEmptyValue, safeFocus, focusKey } from '../theme-sdk/fields.mjs';
+import type { Theme } from './theme';
+import { CONTENT, collectionUrl } from './content';
+import { formatDate, siteLocale } from './dates';
+import { upcomingEvents } from './calendar/cards';
+import { formatOccurrence, locationLine } from './calendar/events';
+import { CALENDAR, bookingLinkUrl, eventUrl, bookingsEnabled } from './calendar/config';
+import { localePath } from './i18n';
+import { localizeDoc, isExtraLocale } from './translations';
+
+// Server side of editable sections: turn a stored instance into the props a
+// coded section component receives. Stored data stays exactly as the owner
+// saved it; everything here is derived per request —
+//   • migrations/<type>.mjs upgrades older instances on the fly
+//   • link fields resolve their ref (page/post/event/booking) to today's URL
+//   • richtext is sanitized
+//   • source fields ("next 3 Youth events") become fresh item arrays
+
+type Instance = z.infer<typeof SectionInstanceSchema>;
+type Definition = z.infer<typeof SectionDefinition>;
+type FieldDef = Definition['fields'][string];
+
+export interface LinkValue { label: string; href: string; external: boolean }
+export interface EventItem {
+  title: string; url: string; summary: string; image: string; imageAlt: string; location: string;
+  start: string; end: string; allDay: boolean; cancelled: boolean;
+  /** "Sat, Oct 3 · 11:00 AM" */ when: string; /** "Saturday, October 3, 2026" */ date: string;
+  /** "11:00 AM – 1:00 PM EDT" */ time: string; month: string; day: string; weekday: string;
+  cta: { label: string; href: string } | null;
+}
+export interface PostItem { title: string; url: string; excerpt: string; image: string; imageAlt: string; date: string; publishedAt: number | null; tags: string[] }
+export interface BookingItem { title: string; url: string; description: string; resource: string; minutes: number }
+
+/** apply a theme migration when the stored instance is older than the definition */
+export function migrateSection(theme: Pick<Theme, 'sections' | 'migrations'>, s: Instance): Instance {
+  const def = theme.sections[s.type];
+  const migrate = theme.migrations?.[s.type];
+  if (!def || !migrate || s.version >= def.version) return s;
+  try {
+    const data = migrate(structuredClone(s.data) as Record<string, unknown>, s.version);
+    if (!data || typeof data !== 'object') return s;
+    return { ...s, version: def.version, data: data as Instance['data'] };
+  } catch {
+    return s; // a throwing migration leaves the section flagged, never crashes the page
+  }
+}
+
+const RICH = {
+  allowedTags: ['p', 'br', 'strong', 'b', 'em', 'i', 'u', 's', 'a', 'ul', 'ol', 'li', 'h3', 'h4', 'blockquote', 'code'],
+  allowedAttributes: { a: ['href', 'title', 'target', 'rel'] },
+  allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+  allowProtocolRelative: false,
+  transformTags: { a: sanitizeHtml.simpleTransform('a', { rel: 'noopener' }) },
+};
+export const sanitizeRichText = (html: string) => sanitizeHtml(String(html ?? ''), RICH);
+
+type RefMap = Map<string, string>;
+
+async function resolveRefs(refs: Set<string>, repo: ContentRepository): Promise<RefMap> {
+  const out: RefMap = new Map();
+  await Promise.all([...refs].map(async (ref) => {
+    const [kind, id] = ref.split(':');
+    try {
+      if (kind === 'page') {
+        const p = await repo.getPage(id);
+        if (p && p.status === 'published') out.set(ref, p.isHome ? '/' : `/${p.slug}`);
+      } else if (kind === 'post') {
+        const p = await repo.getPost(id);
+        if (p && p.status === 'published') out.set(ref, collectionUrl(p.collection, p.slug));
+      } else if (kind === 'event' && CALENDAR.enabled) {
+        const e = await repo.getEvent(id);
+        if (e && e.status === 'published') out.set(ref, eventUrl(e.slug));
+      } else if (kind === 'booking' && bookingsEnabled()) {
+        const l = await repo.getBookingLink(id);
+        const r = l ? await repo.getResource(l.resourceId) : null;
+        if (l && r && l.active) out.set(ref, bookingLinkUrl(r.slug, l.slug));
+      }
+    } catch { /* unresolved refs fall back to the stored href */ }
+  }));
+  return out;
+}
+
+function collectRefs(def: Definition, data: Record<string, unknown>, into: Set<string>) {
+  const visit = (field: FieldDef, value: unknown) => {
+    if (field.type === 'link' && value && typeof value === 'object' && typeof (value as { ref?: unknown }).ref === 'string') into.add((value as { ref: string }).ref);
+    if (field.type === 'list' && Array.isArray(value)) for (const row of value) for (const [k, sub] of Object.entries(field.fields)) visit(sub as FieldDef, (row as Record<string, unknown>)[k]);
+  };
+  for (const [key, field] of Object.entries(def.fields)) visit(field, data[key]);
+}
+
+type Lp = (path: string) => string;
+const same: Lp = (p) => p;
+function resolveLink(value: unknown, refs: RefMap, lp: Lp = same): LinkValue {
+  const v = (value ?? {}) as { label?: string; href?: string; ref?: string };
+  const raw = (v.ref && refs.get(v.ref)) || safeUrl(v.href);
+  // site-internal links stay in the visitor's language (/visit → /es/visit)
+  const href = /^\/(?!\/|media\/|rss\.xml|admin|api|_)/.test(raw) ? lp(raw) : raw;
+  return { label: String(v.label ?? ''), href, external: /^https?:\/\//i.test(href) };
+}
+
+function resolveScalar(field: FieldDef, value: unknown, refs: RefMap, lp: Lp = same): unknown {
+  switch (field.type) {
+    case 'richtext': return sanitizeRichText(String(value ?? ''));
+    case 'url': case 'image': return safeUrl(value);
+    case 'link': return resolveLink(value, refs, lp);
+    default: return value;
+  }
+}
+
+async function resolveSource(field: Extract<FieldDef, { type: 'source' }>, value: unknown, ctx: ResolveContext): Promise<unknown[]> {
+  const cfg = (value ?? {}) as { calendar?: string; collection?: string; tag?: string; resource?: string; limit?: number };
+  const limit = Math.max(1, Math.min(SOURCE_LIMIT_MAX, Number(cfg.limit) || 3));
+  const { repo, settings, now } = ctx;
+  // another language (settings.locale is set to it by the renderer)
+  const lang = isExtraLocale(settings.locale) ? settings.locale : '';
+  const lp = (path: string) => (lang ? localePath(path, lang) : path);
+  if (field.source === 'events') {
+    if (!CALENDAR.enabled) return [];
+    let calendarIds: string[] | undefined;
+    if (cfg.calendar) {
+      const c = await repo.getCalendarBySlug(cfg.calendar);
+      if (!c || c.visibility === 'private') return [];
+      calendarIds = [c.id];
+    }
+    const tz = settings.timezone || 'UTC';
+    const locale = siteLocale(settings);
+    return (await upcomingEvents(repo, settings, now, { calendarIds, limit })).map((o): EventItem => {
+      const e = lang ? localizeDoc(o.event, lang) : o.event;
+      const f = formatOccurrence(o, tz, locale);
+      const ctaHref = safeUrl(e.cta.href);
+      return {
+        title: e.title || 'Untitled event', url: lp(eventUrl(e.slug)), summary: e.excerpt, image: safeUrl(e.cover), imageAlt: e.coverAlt,
+        location: locationLine(e.location), start: new Date(o.start).toISOString(), end: new Date(o.end).toISOString(),
+        allDay: o.allDay, cancelled: e.cancelled, when: f.range, date: f.date, time: f.time, month: f.month, day: f.day, weekday: f.weekday,
+        cta: e.cta.label && ctaHref && !e.cancelled ? { label: e.cta.label, href: ctaHref } : null,
+      };
+    });
+  }
+  if (field.source === 'posts') {
+    const collection = cfg.collection && CONTENT.collections[cfg.collection] ? cfg.collection : 'posts';
+    let posts = await repo.listPublishedPosts(collection);
+    if (cfg.tag) posts = posts.filter((p) => p.tags.some((t) => t.toLowerCase() === cfg.tag!.toLowerCase()));
+    return posts.slice(0, limit).map((raw): PostItem => { const p = lang ? localizeDoc(raw, lang) : raw; return {
+      title: p.title, url: lp(collectionUrl(p.collection, p.slug)), excerpt: p.excerpt, image: safeUrl(p.cover), imageAlt: p.coverAlt,
+      date: formatDate(p.publishedAt, settings, 'short'), publishedAt: p.publishedAt ?? null, tags: p.tags,
+    }; });
+  }
+  if (!bookingsEnabled()) return [];
+  const resources = (await repo.listResources()).filter((r) => r.visibility === 'public' && (!cfg.resource || r.slug === cfg.resource));
+  const byId = new Map(resources.map((r) => [r.id, r]));
+  const links = (await repo.listBookingLinks()).filter((l) => l.active && l.visibility === 'public' && byId.has(l.resourceId));
+  return links.slice(0, limit).map((l): BookingItem => {
+    const r = byId.get(l.resourceId)!;
+    return { title: l.name, url: bookingLinkUrl(r.slug, l.slug), description: l.description, resource: r.name, minutes: l.duration };
+  });
+}
+
+export interface ResolveContext { repo: ContentRepository; settings: Settings; now: number }
+
+/** stored data → component props: defaults filled, refs/sources resolved, richtext sanitized */
+export async function resolveSectionData(def: Definition, stored: Record<string, unknown>, ctx: ResolveContext): Promise<Record<string, unknown>> {
+  const data = normalizeData(def, stored) as Record<string, unknown>;
+  const refs = new Set<string>();
+  collectRefs(def, data, refs);
+  const refMap = refs.size ? await resolveRefs(refs, ctx.repo) : new Map<string, string>();
+  const lang = isExtraLocale(ctx.settings.locale) ? ctx.settings.locale : '';
+  const lp: Lp = lang ? (p) => localePath(p, lang) : same;
+  const out: Record<string, unknown> = {};
+  await Promise.all(Object.entries(def.fields).map(async ([key, field]) => {
+    const value = data[key];
+    if (field.type === 'source') out[key] = await resolveSource(field, value, ctx).catch(() => []);
+    else if (field.type === 'list') {
+      out[key] = (value as Record<string, unknown>[]).map((row) => {
+        const item: Record<string, unknown> = {};
+        for (const [k, sub] of Object.entries(field.fields)) {
+          item[k] = resolveScalar(sub as FieldDef, row[k], refMap, lp);
+          if (sub.type === 'image') item[`${k}Focus`] = safeFocus(row[focusKey(k)]);
+        }
+        return item;
+      });
+    } else {
+      out[key] = resolveScalar(field, value, refMap, lp);
+      // images also hand over their focal point, ready for object-position
+      if (field.type === 'image') out[`${key}Focus`] = safeFocus(stored[focusKey(key)]);
+    }
+  }));
+  return out;
+}
+
+
+/** "YYYY-MM-DDTHH:MM" for now in the site timezone (section schedules are wall-clock) */
+export function wallNow(tz: string, now = Date.now()): string {
+  try {
+    const p = Object.fromEntries(new Intl.DateTimeFormat('en-CA', { timeZone: tz || 'UTC', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(now).map((x) => [x.type, x.value]));
+    return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}`;
+  } catch {
+    return new Date(now).toISOString().slice(0, 16);
+  }
+}
+
+/** admin preview only: empty fields borrow the definition's example (never saved) */
+export function withExample(def: Definition, data: Record<string, unknown>): { data: Record<string, unknown>; used: boolean } {
+  const example = (def as { example?: Record<string, unknown> }).example;
+  if (!example) return { data, used: false };
+  const normalized = normalizeData(def, data) as Record<string, unknown>;
+  let used = false;
+  const out = { ...data };
+  for (const key of Object.keys(def.fields)) {
+    if (example[key] !== undefined && isEmptyValue(normalized[key])) { out[key] = example[key]; used = true; }
+  }
+  return { data: out, used };
+}

package/src/lib/theme.ts

@@ -1,4 +1,4 @@
-import { ThemeManifest, sectionDefinitions } from '../theme-sdk/contract.mjs';
+import { ThemeManifest, sectionDefinitions, PagePreset as PagePresetSchema } from '../theme-sdk/contract.mjs';
 import { z } from 'zod';
 import type { Settings } from './schema';
 
@@ -58,6 +58,9 @@ export const FONT_PAIRINGS = [
   { key: 'system', label: 'System UI (no webfont)', headingFont: 'system-ui, sans-serif', bodyFont: 'system-ui, sans-serif', googleFonts: '' },
 ] as const;
 
+export type SectionMigration = (data: Record<string, unknown>, fromVersion: number) => Record<string, unknown>;
+export type PagePreset = z.infer<typeof PagePresetSchema>;
+
 export interface Theme {
   slug: string;
   name: string;
@@ -68,6 +71,10 @@ export interface Theme {
   version: string;
   sections: ReturnType<typeof sectionDefinitions>;
   sectionTemplates: Record<string, unknown>;
+  // migrations/<type>.mjs default exports: (data, fromVersion) => data
+  migrations: Record<string, SectionMigration>;
+  // starting layouts ("Start from …") offered on pages without sections
+  presets: Record<string, PagePreset>;
   // Astro component (module default) when the theme ships templates/home.astro
   HomeTemplate: unknown | null;
   // optional per-document templates: templates/post-<name>.astro and
@@ -93,6 +100,10 @@ const homes = import.meta.glob('../themes/*/templates/home.astro', { eager: true
 const postTpls = import.meta.glob('../themes/*/templates/post-*.astro', { eager: true }) as Record<string, { default: unknown }>;
 const pageTpls = import.meta.glob('../themes/*/templates/page-*.astro', { eager: true }) as Record<string, { default: unknown }>;
 const eventTpls = import.meta.glob('../themes/*/templates/event.astro', { eager: true }) as Record<string, { default: unknown }>;
+const migrationMods = {
+  ...(import.meta.glob('../themes/*/migrations/*.mjs', { eager: true }) as Record<string, { default?: unknown }>),
+  ...((user as { migrations?: Record<string, { default?: unknown }> }).migrations ?? {}),
+};
 
 // works for both '../themes/<slug>/…' and '/src/themes/<slug>/…'
 const slugOf = (path: string) => /themes\/([^/]+)\//.exec(path)?.[1] ?? path.split('/')[2];
@@ -124,6 +135,10 @@ function buildThemes(
     return {
       version: manifest.version,
       sections: sectionDefinitions(manifest),
+      migrations: Object.fromEntries(Object.entries(migrationMods)
+        .filter(([p, mod]) => slugOf(p) === slug && typeof mod.default === 'function')
+        .map(([p, mod]) => [p.split('/').pop()!.replace(/\.mjs$/, ''), mod.default as SectionMigration])),
+      presets: manifest.presets,
       sectionTemplates: Object.fromEntries(Object.entries(manifest.sections).flatMap(([key, definition]) => {
         const component = (definition as {component?: string}).component;
         const match = component && Object.entries(customSections).find(([p]) => p.endsWith(`/themes/${slug}/${component}`));

package/src/lib/translate.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import sanitizeHtml from 'sanitize-html';
+import type { AiConfig } from './ai-schema';
+import { completeText } from './ai';
+import { ApiError } from './api';
+import { I18N, localeName } from './i18n';
+
+// Machine drafts for translations. Engine: the site's AI provider (follows the
+// glossary and keeps tone), else Cloudflare Workers AI's translation model
+// when the Worker has an `AI` binding. Nothing is saved here; the caller
+// stores results as "AI draft" for someone to review.
+
+const Kind = z.enum(['text', 'textarea', 'richtext', 'link', 'select']);
+export const TranslateInput = z.object({
+  locale: z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/),
+  from: z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/).optional(),
+  units: z.array(z.object({ id: z.string().max(300), text: z.string().max(60_000), kind: Kind.default('text'), label: z.string().max(200).default('') }).strict()).min(1).max(200),
+}).strict();
+export type TranslateInput = z.infer<typeof TranslateInput>;
+
+type Unit = TranslateInput['units'][number];
+interface WorkersAi { run(model: string, input: Record<string, unknown>): Promise<{ translated_text?: string }> }
+
+export function glossaryLines(glossary: string): string[] {
+  return glossary.split('\n').map((l) => l.trim()).filter(Boolean).slice(0, 200);
+}
+
+const clean = (u: Unit, text: string) => {
+  let t = text.trim();
+  if (u.kind === 'richtext') {
+    return sanitizeHtml(t, {
+      allowedTags: ['p', 'br', 'strong', 'b', 'em', 'i', 'u', 's', 'a', 'ul', 'ol', 'li', 'h2', 'h3', 'h4', 'blockquote', 'code', 'figure', 'figcaption', 'img', 'div', 'span', 'iframe', 'table', 'thead', 'tbody', 'tr', 'th', 'td', 'pre', 'hr', 'details', 'summary'],
+      allowedAttributes: { '*': ['class', 'data-*', 'id'], a: ['href', 'title', 'target', 'rel'], img: ['src', 'alt', 'title', 'width', 'height', 'loading'], iframe: ['src', 'title', 'allow', 'allowfullscreen'] },
+      allowedSchemes: ['http', 'https', 'mailto', 'tel'], allowProtocolRelative: false,
+    });
+  }
+  t = sanitizeHtml(t, { allowedTags: [], allowedAttributes: {} }).replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  return u.kind === 'textarea' ? t : t.replace(/\s*\n+\s*/g, ' ');
+};
+
+async function viaProvider(config: AiConfig, units: Unit[], from: string, to: string): Promise<Record<string, string>> {
+  const glossary = glossaryLines(config.glossary);
+  const instruction = [
+    `Translate website text from ${from} to ${to}. It is for a public site (for example a church, school or small business).`,
+    'Natural, warm and plain; match the tone and length of the original. Keep names of people, places and ministries unless the glossary says otherwise.',
+    'Keep numbers, times, dates, emoji, URLs and email addresses exactly. For HTML, translate only the visible text and keep every tag and attribute.',
+    glossary.length ? `Glossary (always follow; "A = B" means translate A as B, a bare term means keep it as is):\n${glossary.join('\n')}` : '',
+    'Input is a JSON object of id → text. Reply with ONLY a JSON object with the same ids → translated text. No commentary, no code fences.',
+  ].filter(Boolean).join('\n');
+  const out: Record<string, string> = {};
+  // batches of ~40 items / ~12k characters keep replies complete
+  let batch: Unit[] = [], size = 0;
+  const flush = async () => {
+    if (!batch.length) return;
+    const input = Object.fromEntries(batch.map((u) => [u.id, u.text]));
+    const reply = await completeText(config, instruction, JSON.stringify(input));
+    let parsed: Record<string, unknown>;
+    try { parsed = JSON.parse(reply.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim()); }
+    catch { throw new ApiError(502, 'The AI returned an unreadable translation. Try again, or translate fewer items at once.'); }
+    for (const u of batch) if (typeof parsed[u.id] === 'string' && (parsed[u.id] as string).trim()) out[u.id] = clean(u, parsed[u.id] as string);
+    batch = []; size = 0;
+  };
+  for (const u of units) {
+    if (batch.length >= 40 || size + u.text.length > 12_000) await flush();
+    batch.push(u); size += u.text.length;
+  }
+  await flush();
+  return out;
+}
+
+async function viaWorkersAi(ai: WorkersAi, units: Unit[], from: string, to: string): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const u of units) {
+    if (u.kind === 'richtext') continue; // the translation model is plain-text only
+    const r = await ai.run('@cf/meta/m2m100-1.2b', { text: u.text, source_lang: from.split('-')[0], target_lang: to.split('-')[0] });
+    if (r?.translated_text?.trim()) out[u.id] = clean(u, r.translated_text);
+  }
+  return out;
+}
+
+/** engine the site can use right now (for the UI): 'provider' | 'workers-ai' | null */
+export function translationEngine(config: AiConfig, locals?: unknown): 'provider' | 'workers-ai' | null {
+  if (config.enabled && config.model) return 'provider';
+  return workersAi(locals) ? 'workers-ai' : null;
+}
+const workersAi = (locals?: unknown) => (locals as { runtime?: { env?: { AI?: WorkersAi } } } | undefined)?.runtime?.env?.AI ?? null;
+
+export async function translateUnits(config: AiConfig, raw: unknown, locals?: unknown): Promise<{ results: Record<string, string>; engine: string }> {
+  const input = TranslateInput.parse(raw);
+  const from = input.from || I18N.defaultLocale || 'en';
+  const units = input.units.filter((u) => u.text.trim());
+  if (!units.length) return { results: {}, engine: 'none' };
+  const engine = translationEngine(config, locals);
+  if (engine === 'provider') return { results: await viaProvider(config, units, localeName(from), localeName(input.locale)), engine };
+  if (engine === 'workers-ai') return { results: await viaWorkersAi(workersAi(locals)!, units, from, input.locale), engine };
+  throw new ApiError(409, 'Turn on AI in Settings → AI & agents to draft translations automatically.');
+}

package/src/lib/translations.ts

@@ -0,0 +1,39 @@
+import type { DocTranslation, DocTranslations } from './schema';
+import { I18N } from './i18n';
+
+// Posts, pages and events in another language: the translated words laid
+// over the document; anything not translated yet stays in the main language.
+// Facts (dates, covers, tags, places' addresses…) are never translated.
+
+type Doc = { title: string; bodyHtml: string; seoTitle: string; seoDesc: string; excerpt?: string; translations?: DocTranslations; location?: { name: string }; cta?: { label: string } };
+
+export const isExtraLocale = (locale: string | undefined | null): locale is string =>
+  Boolean(locale) && I18N.enabled && locale !== I18N.defaultLocale && I18N.locales.includes(locale as string);
+
+export function translationFor(doc: { translations?: DocTranslations }, locale: string): DocTranslation | null {
+  if (!isExtraLocale(locale)) return null;
+  return doc.translations?.[locale] ?? null;
+}
+
+/** does this document have any words in the language? */
+export const hasTranslation = (doc: { translations?: DocTranslations }, locale: string) => {
+  const t = translationFor(doc, locale);
+  return Boolean(t && (t.title.trim() || t.bodyHtml.trim()));
+};
+
+export function localizeDoc<T extends Doc>(doc: T, locale: string | undefined): T {
+  const t = locale ? translationFor(doc, locale) : null;
+  if (!t) return doc;
+  const pick = (v: string, fallback: string) => (v && v.trim() ? v : fallback);
+  const out: T = {
+    ...doc,
+    title: pick(t.title, doc.title),
+    bodyHtml: pick(t.bodyHtml, doc.bodyHtml),
+    seoTitle: pick(t.seoTitle, doc.seoTitle),
+    seoDesc: pick(t.seoDesc, doc.seoDesc),
+  };
+  if (doc.excerpt !== undefined) (out as Doc).excerpt = pick(t.excerpt, doc.excerpt);
+  if (doc.location) (out as Doc).location = { ...doc.location, name: pick(t.locationName, doc.location.name) };
+  if (doc.cta) (out as Doc).cta = { ...doc.cta, label: pick(t.ctaLabel, doc.cta.label) };
+  return out;
+}

package/src/middleware.ts

@@ -1,10 +1,13 @@
 import { defineMiddleware } from 'astro:middleware';
+import { I18N } from './lib/i18n';
 import { validateSession, SESSION_COOKIE } from './lib/auth';
 import { getRepo } from './lib/repo';
 import { CONTENT } from './lib/content';
 import { processDueDeliveries, waitUntilFrom } from './lib/webhooks';
 import { dispatchEmail } from './lib/email/service';
 import { sendDueReminders } from './lib/booking/service';
+import { PUSH } from './lib/push/config';
+import { processPushQueue, runPushJobs } from './lib/push/service';
 import { previewParamRedirect, hasPreviewCookie } from './lib/designPreview';
 
 // Legacy content-URL redirects, checked only on would-be 404s (below) so they
@@ -60,6 +63,20 @@ export const onRequest = defineMiddleware(async (context, next) => {
     return context.redirect(pathname.replace(/\/+$/, '') + context.url.search, 301);
   }
 
+  // another language: /es/events/x renders /events/x with the request marked
+  // Spanish (pages lay translated words over the shared content). The URL the
+  // visitor sees stays /es/…; /es itself is the injected home route.
+  if (I18N.enabled && context.request.method !== 'OPTIONS') {
+    for (const l of I18N.locales) {
+      if (l === I18N.defaultLocale || !pathname.startsWith(`/${l}/`)) continue;
+      const bare = pathname.slice(l.length + 1);
+      if (/^\/(admin|api|_|media|embed|go)(\/|$)/.test(bare)) break;
+      (context.locals as { acmsLocale?: string; acmsPath?: string }).acmsLocale = l;
+      (context.locals as { acmsLocale?: string; acmsPath?: string }).acmsPath = pathname;
+      return context.rewrite(new URL(bare + context.url.search, context.url));
+    }
+  }
+
   // design preview links (?designPreview=1, ?designVersion=, ?preview=<token>,
   // ?preview=off) become a cookie, then the clean URL — so every link clicked
   // afterwards stays in preview mode
@@ -70,6 +87,10 @@ export const onRequest = defineMiddleware(async (context, next) => {
   if (pathname.startsWith('/admin') && pathname !== '/admin/login') {
     const token = context.cookies.get(SESSION_COOKIE)?.value;
     if (!(await validateSession(token, context.locals))) {
+      // editor-app sign-in comes back here after login (see login.astro's next)
+      if (pathname === '/admin/app-auth' && context.request.method === 'GET') {
+        return context.redirect(`/admin/login?next=${encodeURIComponent(pathname + context.url.search)}`);
+      }
       return context.redirect('/admin/login');
     }
   }
@@ -92,6 +113,10 @@ export const onRequest = defineMiddleware(async (context, next) => {
         .then((s) => sendDueReminders(repo, { origin: s.siteUrl.replace(/\/+$/, '') || context.url.origin, locals: context.locals, now }))
         .catch(() => {});
       if (wait) wait(reminders); else await reminders;
+      // push jobs (Node has no cron): never awaited here, errors are logged
+      const push = runPushJobs(repo, { locals: context.locals, fallbackOrigin: context.url.origin, now })
+        .catch((e) => console.error('acms push: scheduled jobs failed', e));
+      if (wait) wait(push);
     } catch {
       // never let the publish sweep break a request
     }
@@ -106,6 +131,13 @@ export const onRequest = defineMiddleware(async (context, next) => {
     const deliveries = getRepo(context.locals).then(repo => processDueDeliveries(repo, { limit: 5 })).catch(() => 0);
     const wait = waitUntilFrom(context.locals);
     if (wait) wait(deliveries); else await deliveries;
+    // first-publish push notices: background only, never delaying the response
+    if (PUSH.enabled) {
+      const push = getRepo(context.locals)
+        .then(repo => processPushQueue(repo, { locals: context.locals, fallbackOrigin: context.url.origin }))
+        .catch((e) => console.error('acms push: queue flush failed', e));
+      if (wait) wait(push);
+    }
   }
 
   // a preview render must never be cached where a visitor could get it

package/src/pages/.well-known/apple-app-site-association.ts

@@ -0,0 +1,6 @@
+import { associationRoute } from '../../lib/mobile/associations';
+import { methodNotAllowed } from '../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../lib/mobile/http';
+export const GET = associationRoute('ios');
+export const HEAD = GET;
+export const ALL = () => methodNotAllowed();

package/src/pages/.well-known/assetlinks.json.ts

@@ -0,0 +1,6 @@
+import { associationRoute } from '../../lib/mobile/associations';
+import { methodNotAllowed } from '../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../lib/mobile/http';
+export const GET = associationRoute('android');
+export const HEAD = GET;
+export const ALL = () => methodNotAllowed();