@acms-subir/core 0.2.0 → 0.3.0

package/src/lib/theme.ts

@@ -1,3 +1,4 @@
+import { ThemeManifest, sectionDefinitions } from '../theme-sdk/contract.mjs';
 import { z } from 'zod';
 import type { Settings } from './schema';
 
@@ -11,37 +12,25 @@ import type { Settings } from './schema';
 // sparse per-token overrides (settings.designOverrides) on top; resolveDesign
 // merges the two and emits CSS variables consumed by site.css.
 
-export const ThemeTokens = z.object({
-  bg: z.string().default('#faf9f7'),
-  ink: z.string().default('#1e1f24'),
-  muted: z.string().default('#6b6e78'),
-  line: z.string().default('#e5e3de'),
-  accent: z.string().default('#4f46e5'),
-  panel: z.string().default('#ffffff'),
-  soft: z.string().default('#eceae5'),
-  headingFont: z.string().default("'Inter', system-ui, sans-serif"),
-  bodyFont: z.string().default("'Inter', system-ui, sans-serif"),
-  // the `family=` query for fonts.googleapis.com/css2; empty = no webfont
-  googleFonts: z.string().default('family=Inter:wght@400;600;700'),
-  width: z.coerce.number().default(760),
-});
-export type ThemeTokens = z.infer<typeof ThemeTokens>;
-
-// Token keys the Design screen may override individually.
-export const OVERRIDE_KEYS = ['bg', 'ink', 'muted', 'line', 'accent', 'panel', 'soft', 'width'] as const;
+export { ThemeTokens } from './themeTokens';
+import { ThemeTokens, tokensCss, hasCustomDark } from './themeTokens';
+
+// Token keys the Design screen may override individually. Dark-palette
+// overrides use DARK_OVERRIDE_KEYS (designOverrides.darkBg → tokens.dark.bg).
+export const OVERRIDE_KEYS = [
+  'bg', 'ink', 'muted', 'line', 'accent', 'panel', 'soft', 'width', 'wideWidth',
+  'button', 'scheme', 'radius', 'elevation', 'density', 'header', 'footer', 'blogLayout',
+] as const;
+export const DARK_OVERRIDE_KEYS = {
+  darkBg: 'bg', darkInk: 'ink', darkMuted: 'muted', darkLine: 'line',
+  darkAccent: 'accent', darkPanel: 'panel', darkSoft: 'soft',
+} as const;
 
 // Post-page display options. Themes set defaults in theme.json under `post`;
 // the Design screen overrides individual fields via designOverrides
 // (postCover: 'normal'|'full'|'hidden', the rest as 'show'|'hide' strings).
-export const PostOptions = z.object({
-  cover: z.enum(['normal', 'full', 'overlay', 'hidden']).default('normal'),
-  showDate: z.boolean().default(true),
-  showReadingTime: z.boolean().default(true),
-  byline: z.boolean().default(true),
-  authorCard: z.boolean().default(true),
-  share: z.boolean().default(true),
-  related: z.boolean().default(true),
-});
+export { PostOptions } from '../theme-sdk/contract.mjs';
+import { PostOptions } from '../theme-sdk/contract.mjs';
 export type PostOptions = z.infer<typeof PostOptions>;
 
 // override key in designOverrides → PostOptions boolean field
@@ -52,11 +41,14 @@ const POST_TOGGLES: [string, keyof PostOptions][] = [
   ['postAuthorCard', 'authorCard'],
   ['postShare', 'share'],
   ['postRelated', 'related'],
+  ['postProgress', 'progress'],
+  ['postToc', 'toc'],
 ];
 
 // Curated heading/body pairings the UI can swap in (override key: fontPairing).
 // Agent-authored themes set headingFont/bodyFont/googleFonts directly instead.
 export const FONT_PAIRINGS = [
+  { key: 'geist', label: 'Geist (modern sans)', headingFont: "'Geist', ui-sans-serif, system-ui, sans-serif", bodyFont: "'Geist', ui-sans-serif, system-ui, sans-serif", googleFonts: 'family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500' },
   { key: 'inter', label: 'Inter (sans)', headingFont: "'Inter', system-ui, sans-serif", bodyFont: "'Inter', system-ui, sans-serif", googleFonts: 'family=Inter:wght@400;600;700' },
   { key: 'fraunces', label: 'Fraunces + Inter (editorial serif)', headingFont: "'Fraunces', Georgia, serif", bodyFont: "'Inter', system-ui, sans-serif", googleFonts: 'family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600;1,9..144,400&family=Inter:wght@400;500;600' },
   { key: 'playfair', label: 'Playfair Display + Inter', headingFont: "'Playfair Display', Georgia, serif", bodyFont: "'Inter', system-ui, sans-serif", googleFonts: 'family=Playfair+Display:ital,wght@0,500;0,600;1,500&family=Inter:wght@400;500;600' },
@@ -73,15 +65,20 @@ export interface Theme {
   tokens: ThemeTokens;
   post: PostOptions;
   css: string;
+  version: string;
+  sections: ReturnType<typeof sectionDefinitions>;
+  sectionTemplates: Record<string, unknown>;
   // Astro component (module default) when the theme ships templates/home.astro
   HomeTemplate: unknown | null;
   // optional per-document templates: templates/post-<name>.astro and
   // templates/page-<name>.astro, selectable in the editor sidebar
   postTemplates: Record<string, unknown>;
   pageTemplates: Record<string, unknown>;
+  // templates/event.astro replaces the built-in event page layout
+  EventTemplate: unknown | null;
 }
 
-interface ThemeJson { name?: string; description?: string; tokens?: Record<string, unknown>; post?: Record<string, unknown> }
+interface ThemeJson { sections?: Record<string, unknown>; version?: string; name?: string; description?: string; tokens?: Record<string, unknown>; post?: Record<string, unknown> }
 
 // Built-in themes ship inside the package (relative globs); project themes
 // come from the consumer's src/themes via the integration's virtual module
@@ -89,11 +86,13 @@ interface ThemeJson { name?: string; description?: string; tokens?: Record<strin
 // theme whose slug matches a built-in replaces it.
 import * as user from 'virtual:acms-user-themes';
 
+const assets = import.meta.glob(['../themes/*/assets/**/*', '!**/.img-subir-originals/**'], { eager: true, query: '?url', import: 'default' }) as Record<string, string>;
 const jsons = import.meta.glob('../themes/*/theme.json', { eager: true, import: 'default' }) as Record<string, ThemeJson>;
 const csses = import.meta.glob('../themes/*/theme.css', { eager: true, query: '?raw', import: 'default' }) as Record<string, string>;
 const homes = import.meta.glob('../themes/*/templates/home.astro', { eager: true }) as Record<string, { default: unknown }>;
 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 }>;
 
 // works for both '../themes/<slug>/…' and '/src/themes/<slug>/…'
 const slugOf = (path: string) => /themes\/([^/]+)\//.exec(path)?.[1] ?? path.split('/')[2];
@@ -115,31 +114,46 @@ function buildThemes(
   cssMap: Record<string, string>,
   homeMap: Record<string, { default: unknown }>,
   postMap: Record<string, { default: unknown }>,
-  pageMap: Record<string, { default: unknown }>
+  pageMap: Record<string, { default: unknown }>,
+  eventMap: Record<string, { default: unknown }> = {}
 ): Theme[] {
   return Object.entries(jsonMap).map(([path, raw]) => {
     const slug = slugOf(path);
+    const manifest = ThemeManifest.parse({ ...raw, name: raw.name ?? slug });
+    const customSections = (user as { sectionTpls?: Record<string, { default: unknown }> }).sectionTpls ?? {};
     return {
+      version: manifest.version,
+      sections: sectionDefinitions(manifest),
+      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}`));
+        return match ? [[key, match[1].default]] : [];
+      })),
       slug,
       name: raw.name ?? slug,
       description: raw.description ?? '',
       tokens: ThemeTokens.parse(raw.tokens ?? {}),
       post: PostOptions.parse(raw.post ?? {}),
-      css: Object.entries(cssMap).find(([p]) => slugOf(p) === slug)?.[1] ?? '',
+      css: (Object.entries(cssMap).find(([p]) => slugOf(p) === slug)?.[1] ?? '').replace(/url\(\s*['"]?(?:\.\/)?(assets\/[^)'"\s]+)['"]?\s*\)/g, (original, file) => {
+        const asset = Object.entries({ ...assets, ...((user as { assets?: Record<string,string> }).assets ?? {}) }).find(([p]) => p.endsWith(`/themes/${slug}/${file}`));
+        return asset ? `url(${asset[1]})` : original;
+      }),
       HomeTemplate: Object.entries(homeMap).find(([p]) => slugOf(p) === slug)?.[1]?.default ?? null,
       postTemplates: templatesFor(slug, postMap, 'post'),
       pageTemplates: templatesFor(slug, pageMap, 'page'),
+      EventTemplate: Object.entries(eventMap).find(([p]) => slugOf(p) === slug)?.[1]?.default ?? null,
     };
   });
 }
 
-const builtins = buildThemes(jsons, csses, homes, postTpls, pageTpls);
+const builtins = buildThemes(jsons, csses, homes, postTpls, pageTpls, eventTpls);
 const projectThemes = buildThemes(
   user.jsons as Record<string, ThemeJson>,
   user.csses,
   user.homes,
   user.postTpls,
-  user.pageTpls
+  user.pageTpls,
+  (user as { eventTpls?: Record<string, { default: unknown }> }).eventTpls ?? {}
 );
 const projectSlugs = new Set(projectThemes.map((t) => t.slug));
 
@@ -160,6 +174,7 @@ export interface ResolvedDesign {
   tokens: ThemeTokens;
   post: PostOptions;
   css: string; // ready-to-inline <style> content: :root vars + theme.css
+  customDark: boolean; // theme/overrides supply a dark palette (vs generated)
   fontsHref: string | null;
   homeMode: 'auto' | 'content';
   HomeTemplate: unknown | null;
@@ -181,24 +196,28 @@ export function resolveDesign(settings: Settings): ResolvedDesign {
       merged.googleFonts = p.googleFonts;
     }
   }
-  const tokens = ThemeTokens.parse(merged);
+  const dark: Record<string, unknown> = { ...theme.tokens.dark };
+  for (const [key, field] of Object.entries(DARK_OVERRIDE_KEYS)) {
+    const v = o[key];
+    if (typeof v === 'string' && v) dark[field] = v;
+  }
+  merged.dark = dark;
+  // a bad stored override (stale enum value, junk width) must never take the
+  // site down: fall back to the theme's own tokens
+  const parsed = ThemeTokens.safeParse(merged);
+  const tokens = parsed.success ? parsed.data : theme.tokens;
   const post: PostOptions = { ...theme.post };
   if (o.postCover === 'normal' || o.postCover === 'full' || o.postCover === 'overlay' || o.postCover === 'hidden') post.cover = o.postCover;
   for (const [key, field] of POST_TOGGLES) {
     if (o[key] === 'show') (post[field] as boolean) = true;
     if (o[key] === 'hide') (post[field] as boolean) = false;
   }
-  const vars = [
-    `--bg:${tokens.bg}`, `--ink:${tokens.ink}`, `--muted:${tokens.muted}`,
-    `--line:${tokens.line}`, `--accent:${tokens.accent}`, `--panel:${tokens.panel}`,
-    `--soft:${tokens.soft}`, `--font-heading:${tokens.headingFont}`,
-    `--font-body:${tokens.bodyFont}`, `--content-width:${tokens.width}px`,
-  ].join(';');
   return {
     theme,
     tokens,
     post,
-    css: `:root{${vars}}\n${theme.css}`,
+    css: `${tokensCss(tokens)}\n${theme.css}`,
+    customDark: hasCustomDark(tokens),
     fontsHref: tokens.googleFonts ? `https://fonts.googleapis.com/css2?${tokens.googleFonts}&display=swap` : null,
     homeMode: o.homeMode === 'content' ? 'content' : 'auto',
     HomeTemplate: theme.HomeTemplate,

package/src/lib/themeTokens.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+
+// Theme token schema v2 + the CSS it compiles to. Pure (no Astro virtual
+// modules), so it's unit-tested directly; lib/theme.ts wires it to the
+// discovered themes and the Design-screen overrides.
+//
+// Every key is optional: a theme.json that sets four colors still gets a
+// complete design (shape, depth, dark palette, derived colors) from the
+// Ink v2 defaults below. Old (v1) theme.json files parse unchanged.
+
+import { DarkTokens, ThemeTokens } from '../theme-sdk/tokens.mjs';
+export { DarkTokens, ThemeTokens };
+export type DarkTokens = z.infer<typeof DarkTokens>;
+export type ThemeTokens = z.infer<typeof ThemeTokens>;
+
+export interface Palette {
+  bg: string; ink: string; muted: string; line: string; accent: string; panel: string; soft: string;
+}
+
+// ---- color math (sRGB hex only; anything else passes through untouched) ----
+
+type RGB = [number, number, number];
+
+export function parseHex(c: string): RGB | null {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? [...m[1]].map((x) => x + x).join('') : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as RGB;
+}
+
+const toHex = (rgb: RGB) =>
+  '#' + rgb.map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, '0')).join('');
+
+export function mix(a: string, b: string, t: number): string {
+  const x = parseHex(a), y = parseHex(b);
+  if (!x || !y) return a;
+  return toHex([0, 1, 2].map((i) => x[i] + (y[i] - x[i]) * t) as RGB);
+}
+
+export function luminance(c: string): number {
+  const rgb = parseHex(c);
+  if (!rgb) return 0.5;
+  const [r, g, b] = rgb.map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a: string, b: string): number {
+  const [l1, l2] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (l1 + 0.05) / (l2 + 0.05);
+}
+
+// Nudge `fg` toward `toward` until it reaches `min` contrast on `bg`. Used for
+// accent-as-text (links, "Featured", today) so any accent a user picks stays
+// readable. Unparseable colors are returned as-is.
+export function ensureContrast(fg: string, bg: string, min = 4.5, toward?: string): string {
+  if (!parseHex(fg) || !parseHex(bg)) return fg;
+  const target = toward ?? (luminance(bg) > 0.4 ? '#000000' : '#ffffff');
+  for (let t = 0; t <= 1.0001; t += 0.04) {
+    const c = mix(fg, target, t);
+    if (contrast(c, bg) >= min) return c;
+  }
+  return target;
+}
+
+export const isDarkColor = (c: string) => luminance(c) < 0.18;
+
+// ---- palettes ----
+
+// A dark palette from a light one: neutral charcoal surfaces carrying a whisper
+// of the light background's warmth, plus the accent lifted until it reads on
+// the dark canvas.
+export function autoDark(light: Palette): Palette {
+  const warm = (base: string, t: number) => mix(base, light.bg, t);
+  const bg = warm('#121316', 0.015);
+  return {
+    bg,
+    panel: warm('#1a1b1f', 0.02),
+    soft: warm('#222328', 0.02),
+    line: warm('#2a2b31', 0.02),
+    ink: warm('#eceae5', 0.2),
+    muted: '#9a9ca4',
+    accent: ensureContrast(light.accent, bg, 4.5, '#ffffff'),
+  };
+}
+
+export function darkPalette(t: ThemeTokens): Palette {
+  const light: Palette = { bg: t.bg, ink: t.ink, muted: t.muted, line: t.line, accent: t.accent, panel: t.panel, soft: t.soft };
+  const gen = autoDark(light);
+  const d = t.dark ?? {};
+  return {
+    bg: d.bg || gen.bg, ink: d.ink || gen.ink, muted: d.muted || gen.muted, line: d.line || gen.line,
+    accent: d.accent || gen.accent, panel: d.panel || gen.panel, soft: d.soft || gen.soft,
+  };
+}
+
+// true when the theme ships its own dark palette (vs. the generated one) —
+// the Design screen flags generated palettes so authors know to check them
+export const hasCustomDark = (t: ThemeTokens) => Object.values(t.dark ?? {}).some(Boolean);
+
+// ---- CSS ----
+
+const RADII: Record<ThemeTokens['radius'], [number, number, number]> = {
+  sharp: [3, 4, 6],
+  soft: [6, 8, 12],
+  round: [10, 16, 24],
+  smooth: [12, 20, 28],
+};
+
+const DENSITY: Record<ThemeTokens['density'], number> = { compact: 0.85, cozy: 1, airy: 1.18 };
+
+function shadows(elevation: ThemeTokens['elevation'], dark: boolean): [string, string, string] {
+  if (elevation === 'flat') return ['none', 'none', dark ? '0 16px 40px -16px rgb(0 0 0 / 70%)' : '0 16px 40px -16px rgb(0 0 0 / 22%)'];
+  const k = elevation === 'lifted' ? 1.6 : 1;
+  const a = (x: number) => `${Math.min(90, Math.round(x * k * (dark ? 5 : 1)))}%`;
+  const c = dark ? '0 0 0' : '23 24 28';
+  return [
+    `0 1px 2px rgb(${c} / ${a(5)})`,
+    `0 1px 2px rgb(${c} / ${a(4)}), 0 8px 24px -12px rgb(${c} / ${a(14)})`,
+    `0 2px 6px rgb(${c} / ${a(6)}), 0 24px 48px -20px rgb(${c} / ${a(28)})`,
+  ];
+}
+
+// Per-scheme variables: the palette, derived colors and shadows. Derived
+// values that need a contrast guarantee are computed here; purely cosmetic
+// ones use color-mix() so theme.css overrides of a base token cascade.
+export function paletteVars(p: Palette, t: ThemeTokens, dark: boolean): string[] {
+  const accentInk = t.accentInk || (contrast('#ffffff', p.accent) >= 4.5 ? '#ffffff' : ensureContrast('#111214', p.accent, 4.5));
+  const [s1, s2, s3] = shadows(t.elevation, dark);
+  const btnInk = t.button === 'accent' ? 'var(--accent-ink)' : 'var(--bg)';
+  return [
+    `--bg:${p.bg}`, `--ink:${p.ink}`, `--muted:${ensureContrast(p.muted, p.bg, 4.5)}`,
+    `--line:${p.line}`, `--accent:${p.accent}`, `--panel:${p.panel}`, `--soft:${p.soft}`,
+    `--accent-ink:${accentInk}`,
+    `--accent-text:${ensureContrast(p.accent, p.bg, 4.5)}`,
+    `--btn:${t.button === 'accent' ? 'var(--accent)' : 'var(--ink)'}`, `--btn-ink:${btnInk}`,
+    `--code-bg:${dark ? '#0d0e11' : '#1b1c21'}`,
+    `--success:${dark ? '#5cc98e' : '#127442'}`, `--danger:${dark ? '#f07b7b' : '#b42f2f'}`, `--warning:${dark ? '#e3b456' : '#8a5f0a'}`,
+    `--sh-1:${s1}`, `--sh-2:${s2}`, `--sh-3:${s3}`,
+    `color-scheme:${dark ? 'dark' : 'light'}`,
+  ];
+}
+
+// Scheme-independent variables: type, shape, rhythm, layout widths.
+export function staticVars(t: ThemeTokens): string[] {
+  const [r1, r2, r3] = RADII[t.radius];
+  return [
+    `--font-heading:${t.headingFont}`, `--font-body:${t.bodyFont}`, `--font-mono:${t.monoFont}`,
+    `--display-weight:${t.displayWeight}`, `--display-tracking:${t.displayTracking}`,
+    `--base-size:${t.baseSize}px`,
+    `--r-sm:${r1}px`, `--r:${r2}px`, `--r-lg:${r3}px`,
+    `--space:${DENSITY[t.density]}`,
+    `--content-width:${t.width}px`, `--wide-width:${t.wideWidth}px`,
+  ];
+}
+
+// The inline <style> body for the tokens: light and dark blocks wired to
+// data-scheme (visitor toggle) and prefers-color-scheme (OS default).
+export function tokensCss(t: ThemeTokens): string {
+  const light: Palette = { bg: t.bg, ink: t.ink, muted: t.muted, line: t.line, accent: t.accent, panel: t.panel, soft: t.soft };
+  const dark = darkPalette(t);
+  const stat = staticVars(t).join(';');
+  const L = paletteVars(light, t, false).join(';');
+  const D = paletteVars(dark, t, true).join(';');
+  if (t.scheme === 'light') return `:root{${stat};${L}}`;
+  if (t.scheme === 'dark') return `:root{${stat};${D}}`;
+  return [
+    `:root{${stat};${L}}`,
+    `:root[data-scheme=dark]{${D}}`,
+    `@media (prefers-color-scheme:dark){:root:not([data-scheme=light]){${D}}}`,
+  ].join('\n');
+}

package/src/lib/umami.ts

@@ -0,0 +1,108 @@
+// Read-side Umami client for the admin dashboard and content rows. The public
+// site only *sends* to Umami (lib/analytics.ts); reading stats needs an API
+// credential that never reaches the browser:
+//   UMAMI_API_KEY   — Umami Cloud API key (x-umami-api-key)
+//   UMAMI_API_TOKEN — self-hosted bearer token (from POST /api/auth/login)
+// The API base is the tracker script's origin + /api (UMAMI_API_URL overrides).
+// Every call fails soft: no credential, a network error, or an unexpected
+// shape returns null and the admin simply hides the numbers.
+import type { Settings } from './schema';
+import { env } from './env';
+import { UMAMI_ID_RE, normalizeScriptUrl } from './analytics';
+
+export interface TrafficSummary {
+  visitors: number;
+  visitorsPrev: number;
+  pageviews: number;
+  pageviewsPrev: number;
+  avgSeconds: number;
+  series: { t: number; views: number; visitors: number }[];
+  topPaths: { path: string; views: number }[];
+}
+
+const TTL = 10 * 60_000;
+const cache = new Map<string, { at: number; value: TrafficSummary | null }>();
+
+function config(settings: Settings) {
+  const u = settings.analytics?.umami;
+  if (!u?.enabled || !UMAMI_ID_RE.test(u.websiteId)) return null;
+  const key = env('UMAMI_API_KEY');
+  const token = env('UMAMI_API_TOKEN');
+  if (!key && !token) return null;
+  let base = env('UMAMI_API_URL') || '';
+  if (!base) {
+    const src = normalizeScriptUrl(u.scriptUrl);
+    if (!src) return null;
+    const origin = new URL(src).origin;
+    base = origin === 'https://cloud.umami.is' ? 'https://api.umami.is/v1' : `${origin}/api`;
+  }
+  const headers: Record<string, string> = { accept: 'application/json' };
+  if (key) headers['x-umami-api-key'] = key;
+  else headers.authorization = `Bearer ${token}`;
+  return { base: base.replace(/\/+$/, ''), id: u.websiteId.toLowerCase(), headers, tz: settings.timezone || 'UTC' };
+}
+
+export function umamiReadEnabled(settings: Settings): boolean {
+  return config(settings) !== null;
+}
+
+// Umami ≥2.13 returns { pageviews: 12, comparison: { pageviews: 9 } };
+// older versions return { pageviews: { value: 12, prev: 9 } }.
+function stat(body: any, name: string): [number, number] {
+  const v = body?.[name];
+  if (v && typeof v === 'object') return [Number(v.value) || 0, Number(v.prev) || 0];
+  return [Number(v) || 0, Number(body?.comparison?.[name]) || 0];
+}
+
+export async function getTraffic(settings: Settings, days = 30): Promise<TrafficSummary | null> {
+  const c = config(settings);
+  if (!c) return null;
+  const cacheKey = `${c.id}:${days}`;
+  const hit = cache.get(cacheKey);
+  if (hit && Date.now() - hit.at < TTL) return hit.value;
+
+  const endAt = Date.now();
+  const startAt = endAt - days * 86_400_000;
+  const q = `startAt=${startAt}&endAt=${endAt}`;
+  const get = async (path: string) => {
+    const res = await fetch(`${c.base}/websites/${c.id}/${path}`, { headers: c.headers, signal: AbortSignal.timeout(4000) });
+    if (!res.ok) throw new Error(`umami ${res.status}`);
+    return res.json();
+  };
+  let value: TrafficSummary | null = null;
+  try {
+    const [stats, pv, urls] = await Promise.all([
+      get(`stats?${q}`),
+      get(`pageviews?${q}&unit=day&timezone=${encodeURIComponent(c.tz)}`),
+      get(`metrics?${q}&type=url&limit=50`).catch(() => []),
+    ]);
+    const [pageviews, pageviewsPrev] = stat(stats, 'pageviews');
+    const [visitors, visitorsPrev] = stat(stats, 'visitors');
+    const [visits] = stat(stats, 'visits');
+    const [totaltime] = stat(stats, 'totaltime');
+    const views = new Map<number, number>();
+    const sess = new Map<number, number>();
+    for (const p of pv?.pageviews ?? []) views.set(new Date(p.x).getTime(), Number(p.y) || 0);
+    for (const p of pv?.sessions ?? []) sess.set(new Date(p.x).getTime(), Number(p.y) || 0);
+    const series = [...views.keys()].sort((a, b) => a - b).map((t) => ({ t, views: views.get(t) ?? 0, visitors: sess.get(t) ?? 0 }));
+    value = {
+      visitors,
+      visitorsPrev,
+      pageviews,
+      pageviewsPrev,
+      avgSeconds: visits ? Math.round(totaltime / visits) : 0,
+      series,
+      topPaths: (Array.isArray(urls) ? urls : []).map((u: any) => ({ path: String(u.x ?? ''), views: Number(u.y) || 0 })),
+    };
+  } catch {
+    value = null;
+  }
+  cache.set(cacheKey, { at: Date.now(), value });
+  return value;
+}
+
+/** views per public path over the window, for content rows */
+export async function viewsByPath(settings: Settings): Promise<Map<string, number>> {
+  const t = await getTraffic(settings, 30);
+  return new Map((t?.topPaths ?? []).map((p) => [p.path.replace(/\/+$/, '') || '/', p.views]));
+}

package/src/lib/webhooks.ts

@@ -0,0 +1,139 @@
+// Signed outgoing webhooks. emitWebhook() queues one delivery row per
+// subscribed endpoint and tries it immediately (in the background where the
+// runtime allows); failures retry with backoff from the cron sweep
+// (processDueDeliveries, run by the Worker's scheduled handler and by the
+// middleware sweep on Node). Every request carries:
+//   X-Acms-Event:      event.published
+//   X-Acms-Delivery:   <delivery id>
+//   X-Acms-Timestamp:  <unix seconds>
+//   X-Acms-Signature:  sha256=<hex HMAC-SHA256 of "<timestamp>.<body>">
+// Receivers verify by recomputing the HMAC with the endpoint secret and
+// rejecting stale timestamps.
+import type { ContentRepository } from './repo/types';
+import type { Webhook, WebhookDelivery, WebhookEventType } from './schema';
+import { isPrivateHost } from './net';
+
+export const MAX_ATTEMPTS = 4;
+// minutes until attempt n+1 (after the first immediate try)
+const BACKOFF_MIN = [1, 10, 60];
+
+const hex = (buf: ArrayBuffer) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function signPayload(secret: string, timestamp: number, body: string): Promise<string> {
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return `sha256=${hex(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${timestamp}.${body}`)))}`;
+}
+
+export function generateWebhookSecret(): string {
+  return `whsec_${hex(crypto.getRandomValues(new Uint8Array(24)).buffer)}`;
+}
+
+// Endpoint URLs must be public http(s): a webhook must never become a way to
+// make the server call its own network. Localhost is allowed only in dev.
+export function validateWebhookUrl(raw: string, allowPrivate = false): string {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new Error('Enter a full URL starting with https://.');
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error('Webhook URLs must use http(s).');
+  if (url.username || url.password) throw new Error('Put credentials in the receiver, not the URL.');
+  if (!allowPrivate && isPrivateHost(url.hostname)) throw new Error('Webhook URLs must point at a public host.');
+  return url.href;
+}
+
+type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface EmitOptions {
+  now?: number;
+  fetcher?: Fetcher;
+  // Workers: ctx.waitUntil, so the response isn't held for delivery
+  waitUntil?: (p: Promise<unknown>) => void;
+}
+
+export async function emitWebhook(
+  repo: ContentRepository,
+  event: WebhookEventType,
+  data: Record<string, unknown>,
+  opts: EmitOptions = {}
+): Promise<WebhookDelivery[]> {
+  const hooks = (await repo.listWebhooks()).filter((h) => h.active && (h.events.includes(event) || h.events.includes('*')));
+  if (!hooks.length) return [];
+  const now = opts.now ?? Date.now();
+  const rows: WebhookDelivery[] = hooks.map((h) => {
+    const id = crypto.randomUUID();
+    return {
+      id, webhookId: h.id, event,
+      payload: JSON.stringify({ id, type: event, createdAt: new Date(now).toISOString(), data }),
+      status: 'pending', attempts: 0, nextAt: now, responseCode: null, createdAt: now, deliveredAt: null,
+    };
+  });
+  await repo.createDeliveries(rows);
+  const work = Promise.all(rows.map((d) => attemptDelivery(repo, d, hooks.find((h) => h.id === d.webhookId)!, opts))).catch(() => {});
+  if (opts.waitUntil) opts.waitUntil(work);
+  else await work;
+  return rows;
+}
+
+export async function attemptDelivery(repo: ContentRepository, d: WebhookDelivery, hook: Webhook, opts: EmitOptions = {}): Promise<void> {
+  const now = opts.now ?? Date.now();
+  const fetcher: Fetcher = opts.fetcher ?? ((url, init) => fetch(url, init));
+  const ts = Math.floor(now / 1000);
+  let code: number | null = null;
+  try {
+    const res = await fetcher(hook.url, {
+      method: 'POST',
+      redirect: 'manual',
+      headers: {
+        'content-type': 'application/json',
+        'user-agent': 'acms-webhooks/1.0',
+        'x-acms-event': d.event,
+        'x-acms-delivery': d.id,
+        'x-acms-timestamp': String(ts),
+        'x-acms-signature': await signPayload(hook.secret, ts, d.payload),
+      },
+      body: d.payload,
+      signal: AbortSignal.timeout(8000),
+    });
+    code = res.status;
+    await res.body?.cancel().catch(() => {});
+  } catch {
+    code = null; // unreachable / timeout
+  }
+  const attempts = d.attempts + 1;
+  const ok = code !== null && code >= 200 && code < 300;
+  const exhausted = attempts >= MAX_ATTEMPTS;
+  await repo.recordDelivery(d.id, {
+    status: ok ? 'delivered' : exhausted ? 'failed' : 'pending',
+    attempts,
+    nextAt: ok || exhausted ? null : now + BACKOFF_MIN[Math.min(attempts - 1, BACKOFF_MIN.length - 1)] * 60_000,
+    responseCode: code,
+    deliveredAt: ok ? now : null,
+  });
+}
+
+// retry sweep: due pending deliveries, oldest first, bounded per run
+export async function processDueDeliveries(repo: ContentRepository, opts: EmitOptions = {}): Promise<number> {
+  const now = opts.now ?? Date.now();
+  const due = await repo.listDueDeliveries(now, 25);
+  if (!due.length) return 0;
+  const hooks = new Map((await repo.listWebhooks()).map((h) => [h.id, h]));
+  let n = 0;
+  for (const d of due) {
+    const hook = hooks.get(d.webhookId);
+    if (!hook || !hook.active) {
+      await repo.recordDelivery(d.id, { status: 'failed', attempts: d.attempts, nextAt: null, responseCode: null, deliveredAt: null });
+      continue;
+    }
+    await attemptDelivery(repo, d, hook, { ...opts, now });
+    n++;
+  }
+  return n;
+}
+
+// the request's background-work hook, when the runtime has one (Workers)
+export function waitUntilFrom(locals: unknown): ((p: Promise<unknown>) => void) | undefined {
+  const ctx = (locals as { runtime?: { ctx?: { waitUntil?: (p: Promise<unknown>) => void } } } | undefined)?.runtime?.ctx;
+  return ctx?.waitUntil ? (p) => ctx.waitUntil!(p) : undefined;
+}