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

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,242 @@
+import sanitizeHtml from 'sanitize-html';
+import type { z } from 'zod';
+import type { ContentRepository } from './repo/types';
+import { authorSlug, type Settings, type User } from './schema';
+import { htmlToPlaintext } from './plaintext';
+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 { themeAssetUrl } from './theme-assets';
+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 PostAuthor { name: string; url: string; avatar: string }
+// excerpt: the post's own, else the first ~160 characters of its text
+export interface PostItem { title: string; url: string; excerpt: string; image: string; imageAlt: string; date: string; publishedAt: number | null; tags: string[]; authors: PostAuthor[] }
+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) };
+}
+
+type Asset = (path: string) => string;
+const noAsset: Asset = () => '';
+function resolveScalar(field: FieldDef, value: unknown, refs: RefMap, lp: Lp = same, asset: Asset = noAsset): unknown {
+  switch (field.type) {
+    case 'richtext': return sanitizeRichText(String(value ?? ''));
+    // images may name a file the theme ships: "assets/hero.jpg" → its built URL
+    case 'image': return typeof value === 'string' && /^(\.\/)?assets\//.test(value) ? asset(value) : safeUrl(value);
+    case 'url': 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()));
+    const shown = posts.slice(0, limit);
+    // public byline only: name, profile URL, avatar — never emails or roles
+    const users = shown.some((p) => p.authorIds.length || p.authorId) ? new Map((await repo.listUsers()).map((u) => [u.id, u])) : new Map();
+    return shown.map((raw): PostItem => { const p = lang ? localizeDoc(raw, lang) : raw; return {
+      title: p.title, url: lp(collectionUrl(p.collection, p.slug)), excerpt: p.excerpt || autoExcerpt(p.bodyHtml), image: safeUrl(p.cover), imageAlt: p.coverAlt,
+      date: formatDate(p.publishedAt, settings, 'short'), publishedAt: p.publishedAt ?? null, tags: p.tags,
+      authors: (raw.authorIds.length ? raw.authorIds : raw.authorId ? [raw.authorId] : [])
+        .map((id) => users.get(id)).filter((u): u is User => Boolean(u))
+        .map((u) => ({ name: u.name, url: lp(`/author/${authorSlug(u)}`), avatar: safeUrl(u.avatar) })),
+    }; });
+  }
+  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 };
+  });
+}
+
+// first ~160 characters of the body, cut at a word, for posts without an excerpt
+export function autoExcerpt(html: string, max = 160): string {
+  const text = htmlToPlaintext(html);
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max + 1);
+  const at = cut.lastIndexOf(' ');
+  return `${(at > max * 0.6 ? cut.slice(0, at) : text.slice(0, max)).replace(/[\s,.;:!?—–-]+$/, '')}…`;
+}
+
+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;
+  // 'ink' = DEFAULT_THEME (importing it would load every theme template)
+  const asset: Asset = (p) => themeAssetUrl(ctx.settings.activeTheme || 'ink', p);
+  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, asset);
+          if (sub.type === 'image') item[`${k}Focus`] = safeFocus(row[focusKey(k)]);
+        }
+        return item;
+      });
+    } else {
+      out[key] = resolveScalar(field, value, refMap, lp, asset);
+      // 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/site-chrome.ts

@@ -0,0 +1,34 @@
+// The `site` prop given to a theme's templates/header.astro and
+// templates/footer.astro. Everything is resolved for the current request:
+// links are already localized, `current` marks the page you're on, languages
+// carry their own names ("Español"), and social links carry inline SVG icons.
+//
+// Core behaviors keep working inside a custom header through data hooks:
+//   [data-search-open]   opens the search dialog (when site.search is set)
+//   [data-scheme-toggle] flips light/dark (when site.schemeToggle is true)
+//   [data-menu-open]     opens the phone menu sheet (built from site.links)
+//   [data-live-header]   (hidden) becomes the "Live" link during a stream
+export interface ChromeLink {
+  label: string;
+  url: string;
+  current: boolean;
+  external: boolean;
+}
+
+export interface SiteChrome {
+  title: string;
+  tagline: string;
+  logo: string; // '' when the site has no logo
+  homeUrl: string;
+  links: ChromeLink[]; // header navigation
+  footerLinks: ChromeLink[];
+  social: (ChromeLink & { icon: string })[]; // icon: inline SVG ('' = text link)
+  readLinks: ChromeLink[]; // collections, search, RSS
+  footerHtml: string; // Settings → footer text, rendered
+  languages: { code: string; label: string; url: string; current: boolean }[]; // [] when single-language
+  search: { url: string; label: string } | null;
+  schemeToggle: boolean;
+  liveHeader: boolean;
+  headerStyle: string; // theme token `header`
+  footerStyle: string; // theme token `footer`
+}

package/src/lib/theme-assets.ts

@@ -0,0 +1,16 @@
+// Files a theme ships under assets/, as built URLs. Kept apart from theme.ts
+// (which loads every .astro template) so section data resolution can use it
+// without pulling the templates in.
+import * as user from 'virtual:acms-user-themes';
+
+const builtin = import.meta.glob(['../themes/*/assets/**/*', '!**/.img-subir-originals/**'], { eager: true, query: '?url', import: 'default' }) as Record<string, string>;
+
+// "assets/hero.jpg" (relative to the theme folder) → the built asset URL, so
+// section image fields and defaults can point at files the theme ships.
+// '' when the theme has no such file. Project themes win over built-ins.
+export function themeAssetUrl(slug: string, path: string): string {
+  const file = path.replace(/^\.\//, '');
+  if (!/^assets\/[^?#]+$/.test(file) || file.includes('..')) return '';
+  const all = { ...builtin, ...((user as { assets?: Record<string, string> }).assets ?? {}) };
+  return Object.entries(all).find(([p]) => p.endsWith(`/themes/${slug}/${file}`))?.[1] ?? '';
+}

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
@@ -76,6 +83,10 @@ export interface Theme {
   pageTemplates: Record<string, unknown>;
   // templates/event.astro replaces the built-in event page layout
   EventTemplate: unknown | null;
+  // templates/header.astro / footer.astro replace the site header and footer;
+  // they receive a `site` prop (lib/site-chrome.ts) with links already resolved
+  HeaderTemplate: unknown | null;
+  FooterTemplate: unknown | null;
 }
 
 interface ThemeJson { sections?: Record<string, unknown>; version?: string; name?: string; description?: string; tokens?: Record<string, unknown>; post?: Record<string, unknown> }
@@ -93,6 +104,12 @@ 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 headerTpls = import.meta.glob('../themes/*/templates/header.astro', { eager: true }) as Record<string, { default: unknown }>;
+const footerTpls = import.meta.glob('../themes/*/templates/footer.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];
@@ -115,7 +132,9 @@ function buildThemes(
   homeMap: Record<string, { default: unknown }>,
   postMap: Record<string, { default: unknown }>,
   pageMap: Record<string, { default: unknown }>,
-  eventMap: Record<string, { default: unknown }> = {}
+  eventMap: Record<string, { default: unknown }> = {},
+  headerMap: Record<string, { default: unknown }> = {},
+  footerMap: Record<string, { default: unknown }> = {}
 ): Theme[] {
   return Object.entries(jsonMap).map(([path, raw]) => {
     const slug = slugOf(path);
@@ -124,6 +143,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}`));
@@ -142,18 +165,22 @@ function buildThemes(
       postTemplates: templatesFor(slug, postMap, 'post'),
       pageTemplates: templatesFor(slug, pageMap, 'page'),
       EventTemplate: Object.entries(eventMap).find(([p]) => slugOf(p) === slug)?.[1]?.default ?? null,
+      HeaderTemplate: Object.entries(headerMap).find(([p]) => slugOf(p) === slug)?.[1]?.default ?? null,
+      FooterTemplate: Object.entries(footerMap).find(([p]) => slugOf(p) === slug)?.[1]?.default ?? null,
     };
   });
 }
 
-const builtins = buildThemes(jsons, csses, homes, postTpls, pageTpls, eventTpls);
+const builtins = buildThemes(jsons, csses, homes, postTpls, pageTpls, eventTpls, headerTpls, footerTpls);
 const projectThemes = buildThemes(
   user.jsons as Record<string, ThemeJson>,
   user.csses,
   user.homes,
   user.postTpls,
   user.pageTpls,
-  (user as { eventTpls?: Record<string, { default: unknown }> }).eventTpls ?? {}
+  (user as { eventTpls?: Record<string, { default: unknown }> }).eventTpls ?? {},
+  (user as { headerTpls?: Record<string, { default: unknown }> }).headerTpls ?? {},
+  (user as { footerTpls?: Record<string, { default: unknown }> }).footerTpls ?? {}
 );
 const projectSlugs = new Set(projectThemes.map((t) => t.slug));
 
@@ -161,6 +188,8 @@ const themes: Theme[] = [...builtins.filter((t) => !projectSlugs.has(t.slug)), .
   (a, b) => (a.slug === DEFAULT_THEME ? -1 : b.slug === DEFAULT_THEME ? 1 : a.name.localeCompare(b.name))
 );
 
+export { themeAssetUrl } from './theme-assets';
+
 export function listThemes(): Theme[] {
   return themes;
 }

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.');
+}