@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/blog/collection.ts

@@ -0,0 +1,313 @@
+import type { AuthorBio, BlogPost, BlogPostSummary, PostStatus } from "./types.js";
+
+/** A blog collection = a route base + a per-tenant content dir. */
+export interface Collection {
+  id: string;
+  base: string;
+}
+
+// ONE glob covering every tenant + every collection; the tenant id and the
+// collection id are both path segments filtered at call time. The derived index
+// is the set of `posts/*.json` files — there is no hand-maintained index.json.
+const postGlobs = import.meta.glob<BlogPost>(
+  "../../../../../tenants/*/content/*/posts/*.json",
+  { import: "default" },
+);
+const redirectGlobs = import.meta.glob<Record<string, string>>(
+  "../../../../../tenants/*/content/*/redirects.json",
+  { import: "default" },
+);
+const authorsGlobs = import.meta.glob<Record<string, AuthorBio>>(
+  "../../../../../tenants/*/content/*/authors.json",
+  { import: "default" },
+);
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const SEGMENT_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * A "scheduled" post whose `scheduledAt` instant has passed behaves exactly like
+ * "published". Before that instant it is treated like a draft (invisible, unlisted).
+ * A scheduled post with a missing/unparseable `scheduledAt` is never due (safe: it
+ * stays hidden rather than leaking). Because visibility is computed at build/request
+ * time, a post committed ahead of time simply needs a build after its instant.
+ */
+function isDueScheduled(p: { status: PostStatus; scheduledAt?: string }, now: string): boolean {
+  if (p.status !== "scheduled" || typeof p.scheduledAt !== "string") return false;
+  const due = Date.parse(p.scheduledAt);
+  return !Number.isNaN(due) && due <= Date.parse(now);
+}
+
+/**
+ * The single visibility chokepoint: is a post reachable at its URL on the live
+ * site? Published, unlisted, and due-scheduled resolve; drafts and not-yet-due
+ * scheduled posts 404. Listings (index/RSS/sitemap) apply a stricter filter
+ * (published or due-scheduled) — unlisted posts resolve at their URL but never
+ * appear in any listing. ("scheduled" branch added in B3.1.)
+ */
+export function isVisibleOnLive(
+  p: { status: PostStatus; scheduledAt?: string },
+  now: string = new Date().toISOString(),
+): boolean {
+  return p.status === "published" || p.status === "unlisted" || isDueScheduled(p, now);
+}
+
+/** "Category Insurance" -> "category-insurance" */
+export function categorySlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Collect the posts whose `field` (categories or tags) contains a term slugifying
+ * to `slug`, preserving input order, plus the human label of the first matching
+ * term (for the page heading/breadcrumb). Returns null when nothing matches, which
+ * a category/tag route turns into a 404. Terms are matched by `categorySlug` so the
+ * URL segment is stable regardless of the term's display casing/spacing.
+ */
+export function collectPostsByTerm<T extends BlogPostSummary>(
+  posts: T[],
+  field: "categories" | "tags",
+  slug: string,
+): { label: string; posts: T[] } | null {
+  const matched: T[] = [];
+  let label: string | null = null;
+  for (const post of posts) {
+    const hit = post[field].find((term) => categorySlug(term) === slug);
+    if (hit !== undefined) {
+      if (label === null) label = hit;
+      matched.push(post);
+    }
+  }
+  return label === null ? null : { label, posts: matched };
+}
+
+/**
+ * "Ada Lovelace" -> "ada-lovelace". Author bylines are people's names, so two
+ * spellings of the same person must resolve to ONE archive slug — otherwise a
+ * migrated blog splits an author across two pages. Beyond the shared category
+ * slugify we first fold the two variant classes that show up in real bylines:
+ *   - diacritics: "María García" == "Maria Garcia" (NFKD + strip combining marks)
+ *   - apostrophes/quotes are DROPPED, not turned into a word break, so
+ *     "Austin O'Brion" == "Austin Obrion" -> "austin-obrion" (WordPress-style),
+ *     not "austin-o-brion" != "austin-obrion".
+ * categorySlug is intentionally left unfolded so existing category/tag URLs
+ * (and their redirects/sitemap entries) stay byte-stable.
+ */
+export function authorSlug(name: string): string {
+  const folded = name
+    .normalize("NFKD") // decompose "é" -> "e" + combining acute
+    .replace(/[\u0300-\u036f]/g, "") // strip the combining marks
+    .replace(/['\u2018\u2019\u02bc\u0060]/g, ""); // drop apostrophes/quotes, do not split
+  return categorySlug(folded);
+}
+
+function normalizeStatus(raw: unknown): PostStatus {
+  return raw === "draft" || raw === "unlisted" || raw === "published" || raw === "scheduled"
+    ? raw
+    : "published";
+}
+
+// Legacy/seeded post JSON may omit `status`; default it to "published" on load so
+// every downstream reader sees a concrete status.
+function normalize(raw: BlogPost): BlogPost {
+  return { ...raw, status: normalizeStatus((raw as { status?: unknown }).status) };
+}
+
+function postsPrefix(tenantId: string, collection: string): string {
+  return `/tenants/${tenantId}/content/${collection}/posts/`;
+}
+
+function toSummary(p: BlogPost): BlogPostSummary {
+  return {
+    source: p.source,
+    slug: p.slug,
+    title: p.title,
+    seoTitle: p.seoTitle,
+    description: p.description,
+    excerpt: p.excerpt,
+    publishedAt: p.publishedAt,
+    modifiedAt: p.modifiedAt,
+    author: p.author,
+    categories: p.categories,
+    tags: p.tags,
+    status: p.status,
+    ...(p.scheduledAt ? { scheduledAt: p.scheduledAt } : {}),
+    ...(p.featuredImage ? { featuredImage: p.featuredImage } : {}),
+    ...(p.canonicalUrl ? { canonicalUrl: p.canonicalUrl } : {}),
+    ...(p.inLanguage ? { inLanguage: p.inLanguage } : {}),
+    ...(p.translationGroupId ? { translationGroupId: p.translationGroupId } : {}),
+  };
+}
+
+/**
+ * The collection ids that actually have post content for a tenant, derived from
+ * the same glob the index is built from (no per-tenant config needed). Sorted for
+ * a stable admin ordering. A tenant with no blog content returns `[]`.
+ */
+export function listCollections(tenantId: string): string[] {
+  const marker = `/tenants/${tenantId}/content/`;
+  const collections = new Set<string>();
+  for (const key of Object.keys(postGlobs)) {
+    const at = key.indexOf(marker);
+    if (at < 0) continue;
+    const rest = key.slice(at + marker.length);
+    const collection = rest.slice(0, rest.indexOf("/"));
+    if (collection && SEGMENT_RE.test(collection)) collections.add(collection);
+  }
+  return [...collections].sort();
+}
+
+/**
+ * The derived index for `(tenant, collection)`, newest first. Live surfaces get
+ * published posts only; admin/preview pass `includeUnpublished` to also see
+ * drafts and unlisted posts.
+ */
+export async function listPosts(
+  tenantId: string,
+  collection: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPostSummary[]> {
+  if (!SEGMENT_RE.test(collection)) return [];
+  const prefix = postsPrefix(tenantId, collection);
+  const keys = Object.keys(postGlobs).filter((key) => key.includes(prefix));
+  const posts = (await Promise.all(keys.map((key) => postGlobs[key]!()))).map(normalize);
+  const includeUnpublished = opts?.includeUnpublished ?? false;
+  const now = opts?.now ?? new Date().toISOString();
+  return posts
+    .filter((p) => includeUnpublished || p.status === "published" || isDueScheduled(p, now))
+    .sort((a, b) => (a.publishedAt < b.publishedAt ? 1 : a.publishedAt > b.publishedAt ? -1 : 0))
+    .map(toSummary);
+}
+
+/**
+ * Load a single post. On the live path a draft returns null (404) and an
+ * unlisted post still resolves; admin/preview pass `includeUnpublished` to load
+ * anything.
+ */
+export async function getPost(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPost | null> {
+  if (!SEGMENT_RE.test(collection) || !SLUG_RE.test(slug)) return null;
+  const key = Object.keys(postGlobs).find(
+    (candidate) =>
+      candidate.includes(postsPrefix(tenantId, collection)) && candidate.endsWith(`/${slug}.json`),
+  );
+  if (!key) return null;
+  const post = normalize(await postGlobs[key]!());
+  if (!(opts?.includeUnpublished ?? false) && !isVisibleOnLive(post, opts?.now)) return null;
+  return post;
+}
+
+/**
+ * Every language variant sharing a `translationGroupId`, newest first. A filter
+ * over `listPosts`, so it inherits the visibility chokepoint verbatim: on the live
+ * path a draft/not-yet-due translation never appears, and an unlisted variant —
+ * which resolves at its own URL but is absent from every listing — is likewise
+ * absent here. Pass `includeUnpublished` for the admin/preview view of the group.
+ */
+export async function listTranslations(
+  tenantId: string,
+  collection: string,
+  translationGroupId: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPostSummary[]> {
+  if (!translationGroupId) return [];
+  const posts = await listPosts(tenantId, collection, opts);
+  return posts.filter((p) => p.translationGroupId === translationGroupId);
+}
+
+/**
+ * Convenience for a route holding a slug: the full variant set for the article at
+ * `slug`, including the post itself. A singleton (no `translationGroupId`) returns
+ * exactly `[that post]` — the uniform "at least one" contract lets a caller render
+ * a switcher purely on `length > 1` without a separate group-id guard. Returns `[]`
+ * only when the post itself does not resolve (unknown, or hidden on the live path).
+ */
+export async function getTranslations(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPostSummary[]> {
+  const post = await getPost(tenantId, collection, slug, opts);
+  if (!post) return [];
+  if (!post.translationGroupId) return [toSummary(post)];
+  return listTranslations(tenantId, collection, post.translationGroupId, opts);
+}
+
+/**
+ * Live-visible related posts for an article page: same primary category first
+ * (newest first, excluding the current post), then fall back to newest overall
+ * to fill up to `n`. Only published posts are candidates; the current post may
+ * itself be unlisted (its page still resolves) and is always excluded.
+ */
+export async function relatedPosts(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  n = 3,
+): Promise<BlogPostSummary[]> {
+  const pool = (await listPosts(tenantId, collection)).filter((p) => p.slug !== slug);
+  const current = await getPost(tenantId, collection, slug);
+  const category = current?.categories[0];
+  const result = category ? pool.filter((p) => p.categories.includes(category)) : [];
+  for (const p of pool) {
+    if (result.length >= n) break;
+    if (!result.some((r) => r.slug === p.slug)) result.push(p);
+  }
+  return result.slice(0, n);
+}
+
+export async function resolveRedirect(
+  tenantId: string,
+  collection: string,
+  slug: string,
+): Promise<string | null> {
+  if (!SEGMENT_RE.test(collection)) return null;
+  const redirects = await getRedirects(tenantId, collection);
+  return redirects[slug] ?? null;
+}
+
+/**
+ * The full `slug -> path` redirect map for `(tenant, collection)`, or `{}` when
+ * there is no `redirects.json`. The admin fast lane (B2.2) reads this to APPEND a
+ * redirect when a published post is deleted, without clobbering existing entries.
+ */
+export async function getRedirects(
+  tenantId: string,
+  collection: string,
+): Promise<Record<string, string>> {
+  if (!SEGMENT_RE.test(collection)) return {};
+  const key = Object.keys(redirectGlobs).find(
+    (candidate) =>
+      candidate.includes(`/tenants/${tenantId}/content/${collection}/`) &&
+      candidate.endsWith("/redirects.json"),
+  );
+  if (!key) return {};
+  return (await redirectGlobs[key]!()) ?? {};
+}
+
+/**
+ * Optional per-tenant × per-collection author bios, keyed by author slug. Missing
+ * file returns {} so callers fall back to the byline name. Author pages resolve a
+ * bio with `getAuthors(t, c)[authorSlug(post.author)]`.
+ */
+export async function getAuthors(
+  tenantId: string,
+  collection: string,
+): Promise<Record<string, AuthorBio>> {
+  if (!SEGMENT_RE.test(collection)) return {};
+  const key = Object.keys(authorsGlobs).find(
+    (candidate) =>
+      candidate.includes(`/tenants/${tenantId}/content/${collection}/`) &&
+      candidate.endsWith("/authors.json"),
+  );
+  if (!key) return {};
+  return (await authorsGlobs[key]!()) ?? {};
+}

package/apps/storefront/src/lib/blog/markdown.ts

@@ -0,0 +1,174 @@
+/**
+ * Minimal, dependency-free Markdown -> sanitized HTML for the admin blog editor
+ * (B3.4 of docs/plans/2026-08-21-blog-platform-workstream.md). The storefront
+ * ships no markdown library (see the "No new deps" convention in §1), and the
+ * migration package's `sanitize-html` is a node-only devtool — so authoring from
+ * the admin gets this small hand-rolled renderer instead.
+ *
+ * SAFETY: the output is fed to `set:html` in the reader route
+ * (`the-build/[slug].astro`), so it must never emit author-supplied HTML
+ * verbatim. All text is HTML-escaped BEFORE any tag is emitted, only the tag set
+ * this renderer produces can appear, and link hrefs / image `src`s are
+ * scheme-checked (`http(s)`/`mailto`/site-relative/anchor only — `javascript:`
+ * etc. fall back to plain text). Admin is already gated, but escaping is
+ * defense-in-depth.
+ *
+ * SCOPE (v1): headings, bold, italic, inline code, fenced code, links, images,
+ * blockquotes, unordered/ordered lists, horizontal rules, paragraphs. NOT a
+ * CommonMark implementation — no nested lists or tables.
+ */
+
+// A control char that never appears in authored prose and is untouched by
+// escapeHtml — a collision-free placeholder while code spans are set aside.
+const CODE_MARK = String.fromCharCode(0);
+const CODE_RE = new RegExp(`${CODE_MARK}(\\d+)${CODE_MARK}`, "g");
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// Closes the one gap `escapeHtml` leaves open for attribute interpolation.
+// The url substring reaching this point has ALREADY passed through the single
+// escapeHtml(t) pass over the whole inline text (renderInline escapes before
+// running the link regex), so `&`/`<`/`>` are already entity-encoded — only
+// `"`/`'` remain untouched. Re-running full escapeHtml here would double-encode
+// those already-escaped entities, so this only needs to close the quote gap.
+function escapeAttrQuotes(s: string): string {
+  return s.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+// Only permit hrefs that can't execute script. Text is already escaped by the
+// time a URL reaches here, so a `javascript:`/`data:` payload arrives intact and
+// is rejected -> the link renders as its (escaped) label text instead. Quote/
+// angle-bracket characters are rejected outright (second line of defense on
+// top of escapeAttrQuotes at the call site) so an attribute-breakout payload
+// never matches the scheme allowlist in the first place.
+function sanitizeUrl(url: string): string | null {
+  const u = url.trim();
+  if (/["'<>]/.test(u)) return null;
+  // `//host/path` is protocol-relative — a browser resolves it to an absolute
+  // cross-origin URL using the current scheme, so it must NOT be accepted
+  // under the "site-relative" `/` allowance (only a single, non-doubled slash
+  // is genuinely site-relative).
+  if (/^\/\//.test(u)) return null;
+  return /^(https?:\/\/|mailto:|\/|#)/i.test(u) ? u : null;
+}
+
+// Inline spans, applied to already-block-split text. Code spans are extracted
+// first (and their contents escaped) so emphasis/link syntax inside `code` is
+// left literal; everything else is escaped, then link/bold/italic tags are woven
+// back in, then the code spans are restored.
+function renderInline(text: string): string {
+  const codes: string[] = [];
+  let t = text.replace(/`([^`]+)`/g, (_m, code: string) => {
+    codes.push(`<code>${escapeHtml(code)}</code>`);
+    return `${CODE_MARK}${codes.length - 1}${CODE_MARK}`;
+  });
+  t = escapeHtml(t);
+  // Images before links: `![alt](url)` embeds a link-like `[alt](url)` span, so
+  // the link regex would otherwise claim it. Each emitted `<img>` is stashed in
+  // `codes` (same placeholder machinery as code spans) so the later link and
+  // emphasis passes can't reach into its `src`/`alt` attribute values — an
+  // `alt` of `a*b*c` must stay literal inside the attribute, not sprout an
+  // `<em>`. `src` is scheme-checked (data:/protocol-relative rejected) and both
+  // attribute values are quote-encoded on top of the whole-text escapeHtml pass.
+  t = t.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (_m, alt: string, url: string) => {
+    const safe = sanitizeUrl(url);
+    if (!safe) return alt;
+    const img = `<img src="${escapeAttrQuotes(safe)}" alt="${escapeAttrQuotes(alt)}" loading="lazy" decoding="async">`;
+    codes.push(img);
+    return `${CODE_MARK}${codes.length - 1}${CODE_MARK}`;
+  });
+  t = t.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, label: string, url: string) => {
+    const safe = sanitizeUrl(url);
+    return safe ? `<a href="${escapeAttrQuotes(safe)}">${label}</a>` : label;
+  });
+  t = t
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/__([^_]+)__/g, "<strong>$1</strong>");
+  t = t
+    .replace(/\*([^*]+)\*/g, "<em>$1</em>")
+    .replace(/(^|[^a-zA-Z0-9])_([^_]+)_(?=[^a-zA-Z0-9]|$)/g, "$1<em>$2</em>");
+  return t.replace(CODE_RE, (_m, i: string) => codes[Number(i)]!);
+}
+
+const isBlank = (l: string): boolean => l.trim() === "";
+const startsBlock = (l: string): boolean =>
+  /^```/.test(l) ||
+  /^#{1,6}\s+/.test(l) ||
+  /^>\s?/.test(l) ||
+  /^\s*[-*+]\s+/.test(l) ||
+  /^\s*\d+\.\s+/.test(l) ||
+  /^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(l);
+
+export function renderMarkdown(md: string): string {
+  const lines = md.replace(/\r\n?/g, "\n").split("\n");
+  const out: string[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i]!;
+
+    if (isBlank(line)) {
+      i++;
+      continue;
+    }
+
+    const fence = line.match(/^```\s*([a-zA-Z0-9_-]*)\s*$/);
+    if (fence) {
+      const buf: string[] = [];
+      i++;
+      while (i < lines.length && !/^```\s*$/.test(lines[i]!)) buf.push(lines[i++]!);
+      i++; // consume closing fence (tolerate an unterminated block at EOF)
+      const cls = fence[1] ? ` class="language-${fence[1]}"` : "";
+      out.push(`<pre><code${cls}>${escapeHtml(buf.join("\n"))}</code></pre>`);
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1]!.length;
+      out.push(`<h${level}>${renderInline(heading[2]!.trim())}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) {
+      out.push("<hr>");
+      i++;
+      continue;
+    }
+
+    if (/^>\s?/.test(line)) {
+      const buf: string[] = [];
+      while (i < lines.length && /^>\s?/.test(lines[i]!)) buf.push(lines[i++]!.replace(/^>\s?/, ""));
+      out.push(`<blockquote>${renderMarkdown(buf.join("\n"))}</blockquote>`);
+      continue;
+    }
+
+    if (/^\s*[-*+]\s+/.test(line)) {
+      const items: string[] = [];
+      while (i < lines.length && /^\s*[-*+]\s+/.test(lines[i]!)) {
+        items.push(lines[i++]!.replace(/^\s*[-*+]\s+/, "").trim());
+      }
+      out.push(`<ul>${items.map((it) => `<li>${renderInline(it)}</li>`).join("")}</ul>`);
+      continue;
+    }
+
+    if (/^\s*\d+\.\s+/.test(line)) {
+      const items: string[] = [];
+      while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i]!)) {
+        items.push(lines[i++]!.replace(/^\s*\d+\.\s+/, "").trim());
+      }
+      out.push(`<ol>${items.map((it) => `<li>${renderInline(it)}</li>`).join("")}</ol>`);
+      continue;
+    }
+
+    const buf: string[] = [];
+    while (i < lines.length && !isBlank(lines[i]!) && !startsBlock(lines[i]!)) buf.push(lines[i++]!);
+    const text = buf.join(" ").trim();
+    if (text) out.push(`<p>${renderInline(text)}</p>`);
+  }
+
+  return out.join("\n");
+}

package/apps/storefront/src/lib/blog/provider.ts

@@ -1,3 +1,8 @@
+// The live WordPress `/blog` deliberately keeps reading its committed, curated
+// index.json (its order is hand-maintained and SEO-load-bearing). The generic
+// derived engine lives in ./collection.ts and powers `the-build` + any new
+// collection; switching `/blog` onto it is a later migration once order is
+// encoded as data (see B0.1 §"/blog migration caution").
 import type { BlogPost, BlogPostSummary } from "./types.js";
 
 const indexGlobs = import.meta.glob<BlogPostSummary[]>(

package/apps/storefront/src/lib/blog/reactions.ts

@@ -0,0 +1,87 @@
+/**
+ * E1.1 — per-post reader reactions: an anonymous, additive emoji tally, the
+ * first reader-sentiment signal for the blog platform (complements view counts,
+ * which measure reads). A near-clone of `viewCounts.ts`: KV counters keyed by
+ * (tenant, collection, slug, reaction), best-effort read-modify-write, no PII,
+ * no per-visitor identity, no moderation (an emoji count carries no user text —
+ * worst case is an inflated tally, self-limiting and low-stakes).
+ *
+ * Storage is the TENANT_CACHE KV namespace (same binding view-counts uses).
+ * Under concurrency some increments are lost to KV's last-write-wins semantics:
+ * acceptable for a demand signal, not a billing counter.
+ *
+ * Tenant/collection-generic by construction — nothing here is bound to a
+ * specific tenant or collection.
+ */
+import { getPost } from "./collection.js";
+
+/** The fixed reaction vocabulary. Not free-form — a closed set like the pillar vocabulary. */
+export const REACTIONS = ["like", "insightful", "celebrate"] as const;
+export type Reaction = (typeof REACTIONS)[number];
+
+/** Narrow an untrusted string to a known reaction, or null. */
+export function isReaction(value: unknown): value is Reaction {
+  return typeof value === "string" && (REACTIONS as readonly string[]).includes(value);
+}
+
+/** KV key for one (post, reaction) rolling tally. */
+export function reactionsKey(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  reaction: Reaction,
+): string {
+  return `blogreact:${tenantId}:${collection}:${slug}:${reaction}`;
+}
+
+async function readCount(kv: KVNamespace, key: string): Promise<number> {
+  const raw = await kv.get(key);
+  const n = raw == null ? 0 : Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+/**
+ * Increment the tally for `reaction` on a post IF the reaction is in the vocab
+ * AND the post is live (published/unlisted/due-scheduled) for this tenant —
+ * `getPost` returns null on the live path for a draft/404/non-post. Best-effort:
+ * never throws (a reaction must never fail the reader's request).
+ */
+export async function recordReaction(
+  kv: KVNamespace,
+  tenantId: string,
+  collection: string,
+  slug: string,
+  reaction: string,
+): Promise<void> {
+  try {
+    if (!isReaction(reaction)) return;
+    const post = await getPost(tenantId, collection, slug);
+    if (!post) return; // not a live post (draft / 404 / non-blog) — do not count
+    const key = reactionsKey(tenantId, collection, slug, reaction);
+    const next = (await readCount(kv, key)) + 1;
+    await kv.put(key, String(next));
+  } catch {
+    /* swallow — reactions are best-effort */
+  }
+}
+
+/**
+ * The full tally map for a post: every vocab reaction to its count (0 if unset).
+ * A null KV (local dev, no binding) yields all-zero counts. Read by the reader
+ * reaction bar and the admin engagement panel (E1.2).
+ */
+export async function getReactionCounts(
+  kv: KVNamespace | undefined,
+  tenantId: string,
+  collection: string,
+  slug: string,
+): Promise<Record<Reaction, number>> {
+  const out = Object.fromEntries(REACTIONS.map((r) => [r, 0])) as Record<Reaction, number>;
+  if (!kv) return out;
+  await Promise.all(
+    REACTIONS.map(async (reaction) => {
+      out[reaction] = await readCount(kv, reactionsKey(tenantId, collection, slug, reaction));
+    }),
+  );
+  return out;
+}

package/apps/storefront/src/lib/blog/rss.ts

@@ -0,0 +1,92 @@
+import type { BlogPostSummary } from "./types.js";
+
+/**
+ * Hand-rolled RSS 2.0 renderer (no `@astrojs/rss` dependency), the syndication
+ * mirror of `sitemap.xml.ts`. Tenant- and collection-agnostic: the caller passes
+ * the resolved canonical base + the collection's route base, so the SAME renderer
+ * serves `/the-build/rss.xml`, `/blog/rss.xml`, and any tenant. Feeding it the
+ * engine's live-visible list (`listPosts` default) inherits the visibility
+ * chokepoint — drafts/unlisted never reach a feed.
+ */
+export interface RssFeedInput {
+  channelTitle: string;
+  channelDescription: string;
+  /** Resolved canonical base, e.g. `https://x.com` or a path-prefixed preview host. */
+  canonicalBase: string;
+  /** The collection's route base, e.g. `/the-build`. */
+  collectionBase: string;
+  /**
+   * Feed items. `BlogPost` is assignable here (it extends `BlogPostSummary`),
+   * so an item may carry a full `contentHtml` body — which is emitted as
+   * `<content:encoded>` for public posts only. Gated posts stay in the feed but
+   * never syndicate their body (see the per-item guard below).
+   */
+  posts: Array<BlogPostSummary & { contentHtml?: string }>;
+}
+
+/** XML-escape text inside a tag (mirrors sitemap.xml.ts). */
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** RFC-822 date (`Sun, 01 Mar 2026 00:00:00 GMT`), the RSS `pubDate` format. */
+function rfc822(iso: string): string {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toUTCString();
+}
+
+export function renderRssFeed(input: RssFeedInput): string {
+  const { channelTitle, channelDescription, posts } = input;
+  const base = input.canonicalBase.replace(/\/$/, "");
+  const collectionBase = `/${input.collectionBase.replace(/^\/+|\/+$/g, "")}`;
+  const channelLink = `${base}${collectionBase}/`;
+  const feedLink = `${base}${collectionBase}/rss.xml`;
+
+  const items = posts
+    .map((post) => {
+      const link = `${base}${collectionBase}/${post.slug}/`;
+      const pubDate = rfc822(post.publishedAt);
+      const categories = post.categories
+        .map((c) => `      <category>${escapeXml(c)}</category>`)
+        .join("\n");
+      // Entitlement guard: a gated post (access !== "public") stays discoverable
+      // in the feed but NEVER syndicates its body — otherwise a feed reader would
+      // unlock paywalled content. Only public posts emit <content:encoded>.
+      const gated = (post.access ?? "public") !== "public";
+      const contentEncoded =
+        !gated && post.contentHtml
+          ? `      <content:encoded><![CDATA[${post.contentHtml}]]></content:encoded>`
+          : "";
+      return [
+        "    <item>",
+        `      <title>${escapeXml(post.title)}</title>`,
+        `      <link>${escapeXml(link)}</link>`,
+        `      <guid isPermaLink="true">${escapeXml(link)}</guid>`,
+        pubDate ? `      <pubDate>${pubDate}</pubDate>` : "",
+        `      <dc:creator>${escapeXml(post.author)}</dc:creator>`,
+        `      <description>${escapeXml(post.excerpt)}</description>`,
+        contentEncoded,
+        categories,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
+  <channel>
+    <title>${escapeXml(channelTitle)}</title>
+    <link>${escapeXml(channelLink)}</link>
+    <atom:link href="${escapeXml(feedLink)}" rel="self" type="application/rss+xml" />
+    <description>${escapeXml(channelDescription)}</description>
+${items}
+  </channel>
+</rss>
+`;
+}