@glw907/cairn-cms 0.6.0 → 0.8.0

package/dist/sveltekit/public-routes.js

@@ -0,0 +1,45 @@
+// cairn-cms: public route loaders (dated-slug design). The factory closes over the site-level
+// index, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
+// `[...path]` route resolves any concept by request path through `byPermalink`. The archive, tag,
+// and tag-index loaders stay concept-scoped, keyed by concept id. The index is built in site code
+// from globs, so it stays in the prerender graph and out of the runtime Worker.
+import { error } from '@sveltejs/kit';
+/** Build the public loaders for a site's unified index. */
+export function createPublicRoutes(deps) {
+    const { site, render, origin } = deps;
+    /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
+    function indexOf(conceptId) {
+        const index = site.concept(conceptId);
+        if (!index)
+            throw error(404, `Unknown content type: ${conceptId}`);
+        return index;
+    }
+    /** One entry by request path, rendered through the site renderer, or a 404. */
+    async function entryLoad(event) {
+        const entry = site.byPermalink(event.url.pathname);
+        if (!entry)
+            throw error(404, `Not found: ${event.url.pathname}`);
+        const { newer, older } = site.adjacent(entry);
+        return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl: origin + entry.permalink, newer, older };
+    }
+    /** The chronological archive for one concept: every non-draft summary, newest-first. */
+    function archiveLoad(conceptId) {
+        return { entries: indexOf(conceptId).all() };
+    }
+    /** All tags with counts for one concept, for a tag index page. */
+    function tagIndexLoad(conceptId) {
+        return { tags: indexOf(conceptId).allTags() };
+    }
+    /** One tag's entries for one concept, or a 404 when the tag has none. */
+    function tagLoad(conceptId, event) {
+        const entries = indexOf(conceptId).byTag(event.params.tag);
+        if (entries.length === 0)
+            throw error(404, `No entries tagged "${event.params.tag}"`);
+        return { tag: event.params.tag, entries };
+    }
+    /** Prerender enumeration: one `{ path }` per entry across every concept. */
+    function entries() {
+        return site.entries();
+    }
+    return { entryLoad, archiveLoad, tagIndexLoad, tagLoad, entries };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/ConceptList.svelte

@@ -17,9 +17,14 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   let title = $state('');
   let slug = $state('');
   let slugEdited = $state(false);
+  // Default the date client-side so the SSR pass and hydration agree across UTC midnight.
+  let dateDefault = $state('');
+  $effect(() => {
+    dateDefault = new Date().toISOString().slice(0, 10);
+  });
 
   const derivedSlug = $derived(slugEdited ? slug : slugify(title));
-  const slugPlaceholder = $derived(data.dated ? '2026-05-my-entry' : 'about-us');
+  const slugPlaceholder = $derived(data.dated ? 'my-entry' : 'about-us');
 </script>
 
 <header class="mb-4 flex items-center justify-between">
@@ -58,14 +63,13 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   <h2 class="text-sm font-semibold">New entry</h2>
   <label class="flex flex-col gap-1">
     <span class="text-sm font-medium">Title</span>
-    <input class="input" name="title" aria-label="Title" bind:value={title} required />
+    <input class="input" name="title" bind:value={title} required />
   </label>
   <label class="flex flex-col gap-1">
     <span class="text-sm font-medium">Slug</span>
     <input
       class="input"
       name="slug"
-      aria-label="Slug"
       placeholder={slugPlaceholder}
       value={derivedSlug}
       oninput={(e) => { slugEdited = true; slug = e.currentTarget.value; }}
@@ -74,7 +78,7 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   {#if data.dated}
     <label class="flex flex-col gap-1">
       <span class="text-sm font-medium">Date</span>
-      <input class="input" type="date" name="date" aria-label="Date" />
+      <input class="input" type="date" name="date" value={dateDefault} />
     </label>
   {/if}
   <button type="submit" class="btn btn-primary self-start">Create</button>

package/src/lib/components/EditPage.svelte

@@ -21,10 +21,10 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
     /** Carta preview plugins from the adapter, for the design-accurate preview. */
     preview?: unknown[];
     /** The site's design-accurate render pipeline; the preview pane sanitizes its output. */
-    renderPreview?: (md: string) => string | Promise<string>;
+    render?: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
   }
 
-  let { data, registry, preview = [], renderPreview }: Props = $props();
+  let { data, registry, preview = [], render }: Props = $props();
 
   // `body` is local editor state seeded once from the prop; it diverges as the user types.
   // untrack() captures the initial value without subscribing to future prop changes.
@@ -48,15 +48,15 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   // Render the design-accurate preview as the body changes, debounced, and sanitize before the DOM.
   // The sanitize is the one barrier between editor-authored markdown and the page (Carta is unsanitized).
   // previewRun is a plain counter (not reactive state) used as a latest-wins guard: if a slow earlier
-  // async renderPreview call resolves after a newer one has started, the stale result is discarded.
+  // async render call resolves after a newer one has started, the stale result is discarded.
   let previewRun = 0;
   $effect(() => {
-    if (!showPreview || !renderPreview) return;
+    if (!showPreview || !render) return;
     const md = body;
     const run = ++previewRun;
     const handle = setTimeout(async () => {
       try {
-        const html = await renderPreview(md);
+        const html = await render(md);
         const safe = await sanitizePreviewHtml(html);
         if (run === previewRun) previewHtml = safe;
       } catch {

package/src/lib/content/compose.ts

@@ -3,7 +3,7 @@
 // the same way and contributes the same kinds of things: nav entries, route logic,
 // concepts, components, field types, and save hooks. Shaped now so the extension contract
 // is additive later.
-import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
+import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, ConceptUrlPolicy, FieldTypeDef } from './types.js';
 import { normalizeConcepts } from './concepts.js';
 
 /**
@@ -13,6 +13,7 @@ import { normalizeConcepts } from './concepts.js';
 export function composeRuntime(
   adapter: CairnAdapter,
   extensions: CairnExtension[] = [],
+  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
 ): CairnRuntime {
   const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
   const adminPanels: AdminPanel[] = [];
@@ -26,10 +27,10 @@ export function composeRuntime(
   }
   return {
     siteName: adapter.siteName,
-    concepts: normalizeConcepts(content),
+    concepts: normalizeConcepts(content, urlPolicy),
     backend: adapter.backend,
     sender: adapter.sender,
-    renderPreview: adapter.renderPreview,
+    render: adapter.render,
     registry: adapter.registry,
     navMenu: adapter.navMenu,
     assets: adapter.assets,

package/src/lib/content/concepts.ts

@@ -3,7 +3,7 @@
 // (id, label, directory, concept-fixed routing, fields, validator) the admin reads. A
 // future Fragments concept attaches by adding one key under `content` and one routing
 // entry, with no reshape here.
-import type { ConceptConfig, ConceptDescriptor, RoutingRule } from './types.js';
+import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
 
 /**
  * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
@@ -23,24 +23,34 @@ function defaultLabel(id: string): string {
   return id.charAt(0).toUpperCase() + id.slice(1);
 }
 
+/** The default permalink pattern: Pages live at the root, other concepts under their id. */
+function defaultPermalink(id: string): string {
+  return id === 'pages' ? '/:slug' : `/${id}/:slug`;
+}
+
 /**
- * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each declared
- * key under `content` becomes one descriptor; an undeclared (`undefined`) concept is
- * skipped. `routing` is injectable so a contract test can prove a new concept attaches
- * additively; production passes the default `CONCEPT_ROUTING`.
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
+ * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
+ * concept id; each value defaults when the YAML omits it (`/:slug` for Pages, `/<id>/:slug`
+ * otherwise; `datePrefix` defaults to `day`). `routing` is injectable so a contract test can prove
+ * a new concept attaches additively; production passes the default `CONCEPT_ROUTING`.
  */
 export function normalizeConcepts(
   content: Record<string, ConceptConfig | undefined>,
+  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
   routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
 ): ConceptDescriptor[] {
   const descriptors: ConceptDescriptor[] = [];
   for (const [id, config] of Object.entries(content)) {
     if (!config) continue;
+    const policy = urlPolicy[id] ?? {};
     descriptors.push({
       id,
       label: config.label ?? defaultLabel(id),
       dir: config.dir,
       routing: routing[id] ?? DEFAULT_ROUTING,
+      permalink: policy.permalink ?? defaultPermalink(id),
+      datePrefix: policy.datePrefix ?? 'day',
       fields: config.fields,
       validate: config.validate,
     });

package/src/lib/content/ids.ts

@@ -36,3 +36,47 @@ export function slugify(title: string): string {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
 }
+
+/** Filename date-prefix granularity for a dated concept: the leading `YYYY[-MM[-DD]]-` on the stem. */
+export type DatePrefix = 'year' | 'month' | 'day';
+
+/** The leading date-prefix shape for each granularity. */
+const DATE_PREFIX_RE: Record<DatePrefix, RegExp> = {
+  year: /^\d{4}-/,
+  month: /^\d{4}-\d{2}-/,
+  day: /^\d{4}-\d{2}-\d{2}-/,
+};
+
+/**
+ * The URL slug for an id. A dated concept passes its `datePrefix` and the leading date prefix is
+ * stripped when present; a non-dated concept passes `null` and the id is returned verbatim. Only
+ * the leading prefix is removed, so a year-like tail (a post titled "2024 Recap") stays in the slug.
+ */
+export function slugFromId(id: string, datePrefix: DatePrefix | null): string {
+  if (!datePrefix) return id;
+  return id.replace(DATE_PREFIX_RE[datePrefix], '');
+}
+
+/**
+ * Compose a dated entry's id from a `YYYY-MM-DD` date, a date-free slug, and the concept's
+ * granularity: the date truncated to the granularity, a hyphen, then the slug. Throws on a
+ * malformed date so a bad create fails before touching git.
+ */
+export function composeDatedId(date: string, slug: string, datePrefix: DatePrefix): string {
+  const m = date.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m) throw new Error(`composeDatedId: malformed date "${date}"`);
+  const [, year, month, day] = m;
+  let prefix: string;
+  switch (datePrefix) {
+    case 'year':
+      prefix = year;
+      break;
+    case 'month':
+      prefix = `${year}-${month}`;
+      break;
+    case 'day':
+      prefix = `${year}-${month}-${day}`;
+      break;
+  }
+  return `${prefix}-${slug}`;
+}

package/src/lib/content/permalink.ts

@@ -0,0 +1,40 @@
+// cairn-cms: the one permalink resolver (public-delivery design, decision 3). Feeds, the
+// sitemap, canonical links, list links, and the prerender entries() all call this, so an
+// entry has exactly one canonical URL. The date is read straight from the YYYY-MM-DD string,
+// so a permalink never shifts across a timezone.
+import type { ConceptDescriptor } from './types.js';
+
+function pad(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+function dateParts(date?: string): { year: string; month: string; day: string } | null {
+  const match = date?.match(/^(\d{4})-(\d{2})-(\d{2})/);
+  return match ? { year: match[1], month: match[2], day: match[3] } : null;
+}
+
+/**
+ * Resolve an entry's canonical path from its concept's permalink pattern. Throws when the
+ * pattern uses a date token and the entry has no valid date, or when a token is unknown, so
+ * a misconfiguration fails at build rather than emitting a broken path.
+ */
+export function permalink(
+  descriptor: ConceptDescriptor,
+  entry: { id: string; slug: string; date?: string },
+): string {
+  return descriptor.permalink.replace(/:(\w+)/g, (_match, token: string) => {
+    if (token === 'slug') return entry.slug;
+    if (token === 'year' || token === 'month' || token === 'day') {
+      const parts = dateParts(entry.date);
+      if (!parts) {
+        throw new Error(
+          `permalink: concept "${descriptor.id}" pattern uses :${token}, but entry "${entry.id}" has no valid date`,
+        );
+      }
+      if (token === 'year') return parts.year;
+      if (token === 'month') return pad(Number(parts.month));
+      return pad(Number(parts.day));
+    }
+    throw new Error(`permalink: unknown token :${token} in pattern "${descriptor.permalink}"`);
+  });
+}

package/src/lib/content/types.ts

@@ -3,11 +3,12 @@
 //
 // The adapter is the single seam the engine consumes (spec §8). A site supplies a
 // `CairnAdapter` at `src/lib/cairn.config.ts` declaring its backend repo, the content
-// concepts it enables, its magic-link sender, and a design-accurate `renderPreview`. The
+// concepts it enables, its magic-link sender, and a design-accurate `render`. The
 // engine never hard-codes a concept, directory, or field; it reads them here. Field
 // descriptors are plain data so a `load` function can hand them across the server-to-client
 // boundary to the editor form.
 import type { ComponentRegistry } from '../render/registry.js';
+import type { DatePrefix } from './ids.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -86,6 +87,17 @@ export interface ConceptConfig {
   validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
 }
 
+/**
+ * A concept's URL policy, set per concept in the YAML site-config (not the adapter). `permalink` is
+ * a `/`-prefixed pattern of literal segments and the tokens `:slug`, `:year`, `:month`, `:day`.
+ * `datePrefix` is the filename date-prefix granularity for a dated concept. Both default in
+ * `normalizeConcepts` when omitted.
+ */
+export interface ConceptUrlPolicy {
+  permalink?: string;
+  datePrefix?: DatePrefix;
+}
+
 /** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
 export interface BackendConfig {
   owner: string;
@@ -135,8 +147,8 @@ export interface CairnAdapter {
   };
   backend: BackendConfig;
   sender: SenderConfig;
-  /** Design-accurate preview: the same render pipeline the site ships. */
-  renderPreview(md: string): string | Promise<string>;
+  /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
+  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
   navMenu?: NavMenuConfig;
@@ -166,6 +178,10 @@ export interface ConceptDescriptor {
   label: string;
   dir: string;
   routing: RoutingRule;
+  /** The resolved permalink pattern, defaulted by `normalizeConcepts`. */
+  permalink: string;
+  /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
+  datePrefix: DatePrefix;
   fields: FrontmatterField[];
   validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
 }
@@ -224,7 +240,8 @@ export interface CairnRuntime {
   concepts: ConceptDescriptor[];
   backend: BackendConfig;
   sender: SenderConfig;
-  renderPreview(md: string): string | Promise<string>;
+  /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
+  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
   registry?: ComponentRegistry;
   navMenu?: NavMenuConfig;
   assets?: AssetConfig;

package/src/lib/delivery/content-index.ts

@@ -0,0 +1,130 @@
+// cairn-cms: the per-concept content index (public-delivery design, decisions 1 and 5). It
+// takes raw files from a site's glob, parses them with the engine's own parseMarkdown, and
+// returns cheap plain-data summaries plus an on-demand detail lookup. It is concept-generic:
+// every operation reads the descriptor and its routing rule, never a hardcoded concept id.
+import { parseMarkdown } from '../content/frontmatter.js';
+import { idFromFilename, slugFromId } from '../content/ids.js';
+import { permalink } from '../content/permalink.js';
+import { deriveExcerpt, wordCount } from './excerpt.js';
+import type { ConceptDescriptor } from '../content/types.js';
+
+/** A raw content file before parsing: the glob key and the file's full markdown text. */
+export interface RawFile {
+  path: string;
+  raw: string;
+}
+
+/** The cheap, plain-data view of one entry, for lists, feeds, and the sitemap. */
+export interface ContentSummary {
+  id: string;
+  slug: string;
+  permalink: string;
+  title: string;
+  date?: string;
+  updated?: string;
+  tags: string[];
+  excerpt: string;
+  wordCount: number;
+  draft: boolean;
+}
+
+/** The detail view: a summary plus the frontmatter and the body to render. */
+export interface ContentEntry extends ContentSummary {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/** The per-concept query surface. */
+export interface ContentIndex {
+  all(opts?: { includeDrafts?: boolean }): ContentSummary[];
+  byId(id: string): ContentEntry | undefined;
+  byTag(tag: string, opts?: { includeDrafts?: boolean }): ContentSummary[];
+  allTags(): { tag: string; count: number }[];
+  adjacent(id: string): { newer?: ContentSummary; older?: ContentSummary };
+}
+
+/** Map a Vite eager `?raw` glob record (`{ path: raw }`) to `RawFile[]`. */
+export function fromGlob(record: Record<string, string>): RawFile[] {
+  return Object.entries(record).map(([path, raw]) => ({ path, raw }));
+}
+
+function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function asDate(value: unknown): string | undefined {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+  if (typeof value === 'string') return value.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+  return undefined;
+}
+
+function asTags(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String) : [];
+}
+
+/** Build a concept's index from its raw files and normalized descriptor. */
+export function createContentIndex(files: RawFile[], descriptor: ConceptDescriptor): ContentIndex {
+  const entries: ContentEntry[] = files.map((file) => {
+    const id = idFromFilename(basename(file.path));
+    const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
+    const { frontmatter, body } = parseMarkdown(file.raw);
+    const date = asDate(frontmatter.date);
+    return {
+      id,
+      slug,
+      permalink: permalink(descriptor, { id, slug, date }),
+      title: asString(frontmatter.title) ?? id,
+      date,
+      updated: asDate(frontmatter.updated),
+      tags: asTags(frontmatter.tags),
+      excerpt: deriveExcerpt(body, { description: asString(frontmatter.description) }),
+      wordCount: wordCount(body),
+      draft: frontmatter.draft === true,
+      frontmatter,
+      body,
+    };
+  });
+
+  // Dated concepts sort newest-first; undated concepts (Pages) sort by title.
+  const sorted = [...entries].sort((a, b) =>
+    descriptor.routing.dated ? (b.date ?? '').localeCompare(a.date ?? '') : a.title.localeCompare(b.title),
+  );
+
+  const summarize = (entry: ContentEntry): ContentSummary => {
+    const { frontmatter: _frontmatter, body: _body, ...summary } = entry;
+    return summary;
+  };
+  const visible = (list: ContentEntry[], includeDrafts?: boolean): ContentEntry[] =>
+    includeDrafts ? list : list.filter((entry) => !entry.draft);
+
+  return {
+    all: (opts = {}) => visible(sorted, opts.includeDrafts).map(summarize),
+    byId: (id) => entries.find((entry) => entry.id === id),
+    byTag: (tag, opts = {}) =>
+      visible(sorted, opts.includeDrafts)
+        .filter((entry) => entry.tags.includes(tag))
+        .map(summarize),
+    allTags: () => {
+      const counts = new Map<string, number>();
+      for (const entry of sorted) {
+        if (entry.draft) continue;
+        for (const tag of entry.tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+      }
+      return [...counts].map(([tag, count]) => ({ tag, count })).sort((a, b) => a.tag.localeCompare(b.tag));
+    },
+    adjacent: (id) => {
+      const list = visible(sorted, false);
+      const i = list.findIndex((entry) => entry.id === id);
+      if (i < 0) return {};
+      return {
+        newer: i > 0 ? summarize(list[i - 1]) : undefined,
+        older: i < list.length - 1 ? summarize(list[i + 1]) : undefined,
+      };
+    },
+  };
+}

package/src/lib/delivery/excerpt.ts

@@ -0,0 +1,41 @@
+// cairn-cms: excerpt and word count for content summaries (public-delivery design, decision
+// 5). A light markdown strip keeps summaries cheap, so a list card, an og:description, and a
+// summary-mode feed read one derived excerpt without a full render.
+
+/** Reduce markdown to readable plain text: drop fenced code, images, and markup; unwrap inline
+ * code and links to their text; collapse whitespace. */
+function toPlainText(md: string): string {
+  return md
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/^\s{0,3}[#>]+\s*/gm, ' ')
+    .replace(/^\s{0,3}[-*+]\s+/gm, ' ')
+    .replace(/[*_~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * A plain-text excerpt. Returns a trimmed frontmatter `description` when present, else the
+ * stripped body cut at a word boundary near `maxChars` (default 200) with an ellipsis.
+ */
+export function deriveExcerpt(body: string, opts: { description?: string; maxChars?: number } = {}): string {
+  const description = opts.description?.trim();
+  if (description) return description;
+
+  const max = opts.maxChars ?? 200;
+  const text = toPlainText(body);
+  if (text.length <= max) return text;
+
+  const cut = text.slice(0, max);
+  const lastSpace = cut.lastIndexOf(' ');
+  return `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+
+/** Count words in the stripped body. */
+export function wordCount(body: string): number {
+  const text = toPlainText(body);
+  return text ? text.split(/\s+/).length : 0;
+}

package/src/lib/delivery/feeds.ts

@@ -0,0 +1,112 @@
+// cairn-cms: RSS and JSON Feed builders (public-delivery design). Pure functions over a
+// channel and a list of items, so they unit-test without a render or a network. The caller
+// (a template +server.ts shim) assembles items from the content index and passes absolute
+// URLs built from PUBLIC_ORIGIN.
+
+/** Feed channel metadata. URLs are absolute. */
+export interface FeedChannel {
+  title: string;
+  description: string;
+  siteUrl: string;
+  feedUrl: string;
+  language?: string;
+  author?: { name: string; email?: string };
+}
+
+/** One feed entry. `contentHtml` carries the rendered body for a full-content feed. */
+export interface FeedItem {
+  title: string;
+  url: string;
+  date: string;
+  updated?: string;
+  summary: string;
+  contentHtml?: string;
+  tags?: string[];
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** Make a string safe inside a CDATA section by splitting any `]]>` across two sections. */
+function cdataSafe(value: string): string {
+  return value.replace(/]]>/g, ']]]]><![CDATA[>');
+}
+
+/** Format a YYYY-MM-DD (or ISO) string as an RFC-822 date in UTC, as RSS wants. */
+function rfc822(date: string): string {
+  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toUTCString();
+}
+
+/** Format a YYYY-MM-DD (or ISO) string as an ISO-8601 instant in UTC. */
+function iso(date: string): string {
+  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toISOString();
+}
+
+/** Build an RSS 2.0 document. */
+export function buildRssFeed(channel: FeedChannel, items: FeedItem[]): string {
+  const entries = items
+    .map((item) => {
+      const content = item.contentHtml ?? item.summary;
+      return [
+        '    <item>',
+        `      <title>${escapeXml(item.title)}</title>`,
+        `      <link>${escapeXml(item.url)}</link>`,
+        `      <guid isPermaLink="true">${escapeXml(item.url)}</guid>`,
+        `      <pubDate>${rfc822(item.date)}</pubDate>`,
+        `      <description>${escapeXml(item.summary)}</description>`,
+        // CDATA cannot contain `]]>`, so split that one sequence rather than escape the body.
+        `      <content:encoded><![CDATA[${cdataSafe(content)}]]></content:encoded>`,
+        '    </item>',
+      ].join('\n');
+    })
+    .join('\n');
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">',
+    '  <channel>',
+    `    <title>${escapeXml(channel.title)}</title>`,
+    `    <link>${escapeXml(channel.siteUrl)}</link>`,
+    `    <description>${escapeXml(channel.description)}</description>`,
+    channel.language ? `    <language>${escapeXml(channel.language)}</language>` : '',
+    `    <atom:link href="${escapeXml(channel.feedUrl)}" rel="self" type="application/rss+xml" />`,
+    entries,
+    '  </channel>',
+    '</rss>',
+    '',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+/** Build a JSON Feed 1.1 document. */
+export function buildJsonFeed(channel: FeedChannel, items: FeedItem[]): string {
+  return JSON.stringify(
+    {
+      version: 'https://jsonfeed.org/version/1.1',
+      title: channel.title,
+      description: channel.description,
+      home_page_url: channel.siteUrl,
+      feed_url: channel.feedUrl,
+      ...(channel.language ? { language: channel.language } : {}),
+      ...(channel.author ? { authors: [channel.author] } : {}),
+      items: items.map((item) => ({
+        id: item.url,
+        url: item.url,
+        title: item.title,
+        summary: item.summary,
+        date_published: iso(item.date),
+        ...(item.updated ? { date_modified: iso(item.updated) } : {}),
+        ...(item.contentHtml ? { content_html: item.contentHtml } : { content_text: item.summary }),
+        ...(item.tags && item.tags.length ? { tags: item.tags } : {}),
+      })),
+    },
+    null,
+    2,
+  );
+}